From 878d6bab5a5fdeca4b096989957708e660887e88 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 3 Sep 2024 17:49:34 +0000
Subject: [PATCH] Update unreleased documentation (#809)

* Update versions.json

* Deployed c85b9746e to unreleased in versions with MkDocs 1.5.3 and mike 2.0.0

* Sort docs versions

---------

Co-authored-by: GitHub Actions Bot <github-actions-bot@example.com>
---
 versions/unreleased/404.html                  |   3 +-
 versions/unreleased/api-ref/index.html        |   3 +-
 .../api-ref/prefect/agent/index.html          |  13 +-
 .../api-ref/prefect/artifacts/index.html      |  19 +-
 .../api-ref/prefect/automations/index.html    |  45 +-
 .../api-ref/prefect/blocks/core/index.html    |  33 +-
 .../api-ref/prefect/blocks/fields/index.html  |   3 +-
 .../prefect/blocks/kubernetes/index.html      |  11 +-
 .../prefect/blocks/notifications/index.html   |  27 +-
 .../api-ref/prefect/blocks/system/index.html  |  11 +-
 .../api-ref/prefect/blocks/webhook/index.html |   7 +-
 .../api-ref/prefect/cli/agent/index.html      |   7 +-
 .../api-ref/prefect/cli/artifact/index.html   |   9 +-
 .../api-ref/prefect/cli/block/index.html      |  21 +-
 .../prefect/cli/cloud-webhook/index.html      |  19 +-
 .../api-ref/prefect/cli/cloud/index.html      |  23 +-
 .../prefect/cli/concurrency_limit/index.html  |  15 +-
 .../api-ref/prefect/cli/config/index.html     |  13 +-
 .../api-ref/prefect/cli/deploy/index.html     |   9 +-
 .../api-ref/prefect/cli/deployment/index.html |  31 +-
 .../api-ref/prefect/cli/dev/index.html        |  23 +-
 .../api-ref/prefect/cli/events/index.html     |   5 +-
 .../api-ref/prefect/cli/flow/index.html       |   9 +-
 .../api-ref/prefect/cli/flow_run/index.html   |  15 +-
 .../api-ref/prefect/cli/kubernetes/index.html |  11 +-
 .../api-ref/prefect/cli/profile/index.html    |  17 +-
 .../api-ref/prefect/cli/root/index.html       |   7 +-
 .../api-ref/prefect/cli/server/index.html     |  19 +-
 .../api-ref/prefect/cli/shell/index.html      |  15 +-
 .../api-ref/prefect/cli/variable/index.html   |   9 +-
 .../api-ref/prefect/cli/work_pool/index.html  |  31 +-
 .../api-ref/prefect/cli/work_queue/index.html |  25 +-
 .../api-ref/prefect/cli/worker/index.html     |   5 +-
 .../api-ref/prefect/client/base/index.html    |  21 +-
 .../api-ref/prefect/client/cloud/index.html   |   9 +-
 .../prefect/client/orchestration/index.html   | 243 +++----
 .../api-ref/prefect/client/schemas/index.html | 359 +++++-----
 .../prefect/client/utilities/index.html       |   9 +-
 .../prefect/concurrency/asyncio/index.html    |  13 +-
 .../prefect/concurrency/events/index.html     |   3 +-
 .../prefect/concurrency/services/index.html   |   3 +-
 .../prefect/concurrency/sync/index.html       |   9 +-
 .../api-ref/prefect/context/index.html        |  37 +-
 .../prefect/deployments/base/index.html       |  11 +-
 .../deployments/deployments/index.html        |  27 +-
 .../prefect/deployments/runner/index.html     |  25 +-
 .../prefect/deployments/steps/core/index.html |   9 +-
 .../prefect/deployments/steps/pull/index.html |  15 +-
 .../deployments/steps/utility/index.html      |  11 +-
 .../api-ref/prefect/engine/index.html         |  41 +-
 .../api-ref/prefect/events/index.html         |  95 +--
 .../api-ref/prefect/exceptions/index.html     |  85 +--
 .../api-ref/prefect/filesystems/index.html    |  43 +-
 .../api-ref/prefect/flow_runs/index.html      |   5 +-
 .../api-ref/prefect/flows/index.html          |  47 +-
 .../api-ref/prefect/futures/index.html        |  19 +-
 .../api-ref/prefect/infrastructure/index.html |  41 +-
 .../api-ref/prefect/input/actions/index.html  |   9 +-
 .../prefect/input/run_input/index.html        |  25 +-
 .../prefect/logging/configuration/index.html  |   7 +-
 .../prefect/logging/formatters/index.html     |   5 +-
 .../prefect/logging/handlers/index.html       |  13 +-
 .../prefect/logging/highlighters/index.html   |  27 +-
 .../prefect/logging/loggers/index.html        |  27 +-
 .../api-ref/prefect/manifests/index.html      |   7 +-
 .../api-ref/prefect/runner/runner/index.html  |  21 +-
 .../api-ref/prefect/runner/server/index.html  |   9 +-
 .../api-ref/prefect/runner/storage/index.html |  37 +-
 .../api-ref/prefect/runner/utils/index.html   |  11 +-
 .../prefect/runtime/deployment/index.html     |   5 +-
 .../prefect/runtime/flow_run/index.html       |   5 +-
 .../prefect/runtime/task_run/index.html       |   5 +-
 .../api-ref/prefect/serializers/index.html    |  25 +-
 .../api-ref/prefect/settings/index.html       | 401 +++++------
 .../api-ref/prefect/software/index.html       |   3 +-
 .../api-ref/prefect/states/index.html         |  45 +-
 .../api-ref/prefect/task-runners/index.html   |  19 +-
 .../api-ref/prefect/tasks/index.html          |  27 +-
 .../api-ref/prefect/testing/index.html        |   3 +-
 .../prefect/utilities/annotations/index.html  |  13 +-
 .../prefect/utilities/asyncutils/index.html   |  35 +-
 .../prefect/utilities/callables/index.html    |  33 +-
 .../prefect/utilities/collections/index.html  |  31 +-
 .../prefect/utilities/compat/index.html       |   5 +-
 .../prefect/utilities/context/index.html      |   5 +-
 .../prefect/utilities/dispatch/index.html     |  15 +-
 .../prefect/utilities/dockerutils/index.html  |  45 +-
 .../prefect/utilities/filesystem/index.html   |  21 +-
 .../prefect/utilities/hashing/index.html      |   9 +-
 .../prefect/utilities/importtools/index.html  |  25 +-
 .../api-ref/prefect/utilities/math/index.html |  11 +-
 .../prefect/utilities/names/index.html        |   9 +-
 .../prefect/utilities/processutils/index.html |  15 +-
 .../prefect/utilities/pydantic/index.html     |  11 +-
 .../utilities/render_swagger/index.html       |   5 +-
 .../prefect/utilities/services/index.html     |   5 +-
 .../prefect/utilities/slugify/index.html      |   3 +-
 .../prefect/utilities/templating/index.html   |  13 +-
 .../api-ref/prefect/utilities/text/index.html |   3 +-
 .../utilities/visualization/index.html        |  17 +-
 .../api-ref/prefect/variables/index.html      |  89 ++-
 .../api-ref/prefect/workers/base/index.html   |  27 +-
 .../api-ref/prefect/workers/block/index.html  |   9 +-
 .../prefect/workers/process/index.html        |   7 +-
 .../api-ref/prefect/workers/server/index.html |   5 +-
 .../prefect/workers/utilities/index.html      |   3 +-
 versions/unreleased/api-ref/python/index.html |   3 +-
 .../api-ref/rest-api-reference/index.html     |   3 +-
 .../unreleased/api-ref/rest-api/index.html    |   3 +-
 .../api-ref/server/api/admin/index.html       |  15 +-
 .../api-ref/server/api/csrf_token/index.html  |   5 +-
 .../server/api/dependencies/index.html        |  15 +-
 .../api-ref/server/api/deployments/index.html |  29 +-
 .../server/api/flow_run_states/index.html     |   9 +-
 .../api-ref/server/api/flow_runs/index.html   |  37 +-
 .../api-ref/server/api/flows/index.html       |  19 +-
 .../api-ref/server/api/middleware/index.html  |   7 +-
 .../api-ref/server/api/run_history/index.html |   7 +-
 .../server/api/saved_searches/index.html      |  13 +-
 .../api-ref/server/api/server/index.html      |  23 +-
 .../server/api/task_run_states/index.html     |   9 +-
 .../api-ref/server/api/task_runs/index.html   |  21 +-
 versions/unreleased/api-ref/server/index.html |   3 +-
 .../server/models/csrf_token/index.html       |   9 +-
 .../server/models/deployments/index.html      |  35 +-
 .../server/models/flow_run_states/index.html  |  11 +-
 .../server/models/flow_runs/index.html        |  23 +-
 .../api-ref/server/models/flows/index.html    |  19 +-
 .../server/models/saved_searches/index.html   |  15 +-
 .../server/models/task_run_states/index.html  |  11 +-
 .../server/models/task_runs/index.html        |  25 +-
 .../orchestration/core_policy/index.html      |  53 +-
 .../orchestration/global_policy/index.html    |  37 +-
 .../server/orchestration/policies/index.html  |  11 +-
 .../server/orchestration/rules/index.html     |  73 +-
 .../api-ref/server/schemas/actions/index.html | 137 ++--
 .../api-ref/server/schemas/core/index.html    |  51 +-
 .../api-ref/server/schemas/filters/index.html | 377 +++++-----
 .../server/schemas/responses/index.html       |  25 +-
 .../server/schemas/schedules/index.html       |  19 +-
 .../api-ref/server/schemas/sorting/index.html |  39 +-
 .../api-ref/server/schemas/states/index.html  |  43 +-
 .../server/services/late_runs/index.html      |   9 +-
 .../server/services/loop_service/index.html   |  15 +-
 .../server/services/scheduler/index.html      |  13 +-
 .../server/utilities/database/index.html      |  33 +-
 .../server/utilities/schemas/index.html       |   3 +-
 .../server/utilities/server/index.html        |  15 +-
 .../unreleased/cloud/connecting/index.html    |   3 +-
 versions/unreleased/cloud/events/index.html   |   3 +-
 .../unreleased/cloud/incidents/index.html     |   3 +-
 versions/unreleased/cloud/index.html          |   3 +-
 .../unreleased/cloud/rate-limits/index.html   |   3 +-
 .../cloud/users/api-keys/index.html           |   3 +-
 .../cloud/users/audit-log/index.html          |   3 +-
 versions/unreleased/cloud/users/index.html    |   3 +-
 .../object-access-control-lists/index.html    |   3 +-
 .../unreleased/cloud/users/roles/index.html   |   3 +-
 .../cloud/users/service-accounts/index.html   |   3 +-
 .../unreleased/cloud/users/sso/index.html     |   3 +-
 .../unreleased/cloud/users/teams/index.html   |   3 +-
 .../unreleased/cloud/workspaces/index.html    |   3 +-
 versions/unreleased/community/index.html      |   3 +-
 .../unreleased/concepts/agents/index.html     |   3 +-
 .../unreleased/concepts/artifacts/index.html  |   3 +-
 .../concepts/automations/index.html           |   3 +-
 .../unreleased/concepts/blocks/index.html     |   3 +-
 .../deployments-block-based/index.html        |   3 +-
 .../concepts/deployments/index.html           |   3 +-
 .../concepts/filesystems/index.html           |   3 +-
 versions/unreleased/concepts/flows/index.html |   3 +-
 versions/unreleased/concepts/index.html       |   3 +-
 .../concepts/infrastructure/index.html        |   3 +-
 .../unreleased/concepts/results/index.html    |   3 +-
 .../unreleased/concepts/schedules/index.html  |   3 +-
 .../unreleased/concepts/states/index.html     |   3 +-
 .../unreleased/concepts/storage/index.html    |   3 +-
 .../concepts/task-runners/index.html          |   3 +-
 versions/unreleased/concepts/tasks/index.html |   3 +-
 .../unreleased/concepts/work-pools/index.html |   3 +-
 .../contributing/overview/index.html          |   3 +-
 .../unreleased/contributing/style/index.html  |   3 +-
 .../contributing/versioning/index.html        |   3 +-
 versions/unreleased/faq/index.html            |   3 +-
 .../getting-started/installation/index.html   |   3 +-
 .../getting-started/quickstart/index.html     |   3 +-
 .../unreleased/guides/automations/index.html  |   3 +-
 .../unreleased/guides/big-data/index.html     |   3 +-
 versions/unreleased/guides/ci-cd/index.html   |   3 +-
 .../unreleased/guides/cli-shell/index.html    |   3 +-
 .../creating-interactive-workflows/index.html |   3 +-
 .../guides/dask-ray-task-runners/index.html   |   3 +-
 .../guides/deployment/aci/index.html          |   3 +-
 .../guides/deployment/daemonize/index.html    |   3 +-
 .../developing-a-new-worker-type/index.html   |   3 +-
 .../guides/deployment/kubernetes/index.html   |   3 +-
 .../overriding-job-variables/index.html       |   3 +-
 .../deployment/push-work-pools/index.html     |   3 +-
 .../deployment/serverless-workers/index.html  |   3 +-
 .../deployment/storage-guide/index.html       |   3 +-
 versions/unreleased/guides/docker/index.html  |   3 +-
 .../global-concurrency-limits/index.html      |   3 +-
 versions/unreleased/guides/host/index.html    |   3 +-
 versions/unreleased/guides/index.html         |   3 +-
 versions/unreleased/guides/logs/index.html    |   3 +-
 .../guides/managed-execution/index.html       |   3 +-
 .../guides/migration-guide/index.html         |   3 +-
 .../unreleased/guides/moving-data/index.html  |   3 +-
 .../guides/prefect-deploy/index.html          |   3 +-
 .../guides/runtime-context/index.html         |   3 +-
 versions/unreleased/guides/secrets/index.html |   3 +-
 .../unreleased/guides/settings/index.html     |   3 +-
 .../index.html                                |   3 +-
 .../guides/state-change-hooks/index.html      |   3 +-
 versions/unreleased/guides/testing/index.html |   3 +-
 .../guides/troubleshooting/index.html         |   3 +-
 .../index.html                                |   3 +-
 .../guides/using-the-client/index.html        |   3 +-
 .../unreleased/guides/variables/index.html    |   3 +-
 .../unreleased/guides/webhooks/index.html     |   3 +-
 versions/unreleased/index.html                |   3 +-
 .../integrations/contribute/index.html        |   3 +-
 versions/unreleased/integrations/index.html   |   3 +-
 .../integrations/prefect-aws/batch/index.html |   7 +-
 .../prefect-aws/client_waiter/index.html      |   7 +-
 .../prefect-aws/credentials/index.html        |  29 +-
 .../prefect-aws/deployments/steps/index.html  |  21 +-
 .../integrations/prefect-aws/ecs/index.html   |  41 +-
 .../prefect-aws/ecs_guide/index.html          |   3 +-
 .../prefect-aws/ecs_worker/index.html         |  35 +-
 .../prefect-aws/glue_job/index.html           |  15 +-
 .../integrations/prefect-aws/index.html       |   3 +-
 .../prefect-aws/lambda_function/index.html    |  13 +-
 .../integrations/prefect-aws/s3/index.html    |  51 +-
 .../prefect-aws/secrets_manager/index.html    |  23 +-
 .../prefect-azure/aci_worker/index.html       |   3 +-
 .../prefect-azure/blob_storage/index.html     |  33 +-
 .../container_instance/index.html             |  25 +-
 .../container_instance_worker/index.html      |  23 +-
 .../prefect-azure/cosmos_db/index.html        |  11 +-
 .../prefect-azure/credentials/index.html      |  35 +-
 .../deployments/steps/index.html              |   9 +-
 .../integrations/prefect-azure/index.html     |   3 +-
 .../prefect-azure/ml_datastore/index.html     |  13 +-
 .../prefect-bitbucket/credentials/index.html  |  11 +-
 .../integrations/prefect-bitbucket/index.html |   3 +-
 .../prefect-bitbucket/repository/index.html   |   9 +-
 .../integrations/prefect-dask/index.html      |   3 +-
 .../prefect-dask/task_runners/index.html      |   9 +-
 .../prefect-dask/usage_guide/index.html       |   3 +-
 .../prefect-dask/utils/index.html             |   9 +-
 .../prefect-databricks/credentials/index.html |   9 +-
 .../prefect-databricks/flows/index.html       |  91 ++-
 .../prefect-databricks/index.html             |   3 +-
 .../prefect-databricks/jobs/index.html        |  69 +-
 .../prefect-databricks/models/jobs/index.html | 235 +++---
 .../prefect-databricks/rest/index.html        |  13 +-
 .../prefect-dbt/cli/commands/index.html       |  31 +-
 .../prefect-dbt/cli/configs/base/index.html   |  13 +-
 .../cli/configs/bigquery/index.html           |   9 +-
 .../cli/configs/postgres/index.html           |   9 +-
 .../cli/configs/snowflake/index.html          |   9 +-
 .../prefect-dbt/cli/credentials/index.html    |   9 +-
 .../prefect-dbt/cloud/clients/index.html      |  23 +-
 .../prefect-dbt/cloud/credentials/index.html  |  13 +-
 .../prefect-dbt/cloud/jobs/index.html         |  37 +-
 .../prefect-dbt/cloud/models/index.html       |   9 +-
 .../prefect-dbt/cloud/runs/index.html         |  19 +-
 .../prefect-dbt/cloud/utils/index.html        |  13 +-
 .../integrations/prefect-dbt/index.html       |   3 +-
 .../prefect-docker/containers/index.html      |  15 +-
 .../prefect-docker/credentials/index.html     |   9 +-
 .../deployments/steps/index.html              |  13 +-
 .../prefect-docker/host/index.html            |   9 +-
 .../prefect-docker/images/index.html          |   7 +-
 .../integrations/prefect-docker/index.html    |   3 +-
 .../prefect-docker/worker/index.html          |  23 +-
 .../prefect-email/credentials/index.html      |  13 +-
 .../integrations/prefect-email/index.html     |   3 +-
 .../prefect-email/message/index.html          |   7 +-
 .../prefect-gcp/aiplatform/index.html         |  21 +-
 .../prefect-gcp/bigquery/index.html           |  33 +-
 .../prefect-gcp/cloud_run/index.html          |  47 +-
 .../prefect-gcp/cloud_run_worker/index.html   |  23 +-
 .../cloud_run_worker_v2/index.html            |  21 +-
 .../prefect-gcp/cloud_storage/index.html      |  63 +-
 .../prefect-gcp/credentials/index.html        |  23 +-
 .../prefect-gcp/deployments/steps/index.html  |  21 +-
 .../prefect-gcp/gcp-worker-guide/index.html   |   3 +-
 .../integrations/prefect-gcp/index.html       |   3 +-
 .../prefect-gcp/secret_manager/index.html     |  21 +-
 .../prefect-gcp/vertex_worker/index.html      |  21 +-
 .../prefect-github/credentials/index.html     |  11 +-
 .../prefect-github/graphql/index.html         |   7 +-
 .../integrations/prefect-github/index.html    |   3 +-
 .../prefect-github/mutations/index.html       |  33 +-
 .../prefect-github/organization/index.html    |  79 +-
 .../prefect-github/repository/index.html      | 121 ++--
 .../repository_owner/index.html               |  11 +-
 .../prefect-github/user/index.html            |  95 +--
 .../prefect-github/utils/index.html           |  11 +-
 .../prefect-github/viewer/index.html          |  95 +--
 .../prefect-gitlab/credentials/index.html     |   9 +-
 .../integrations/prefect-gitlab/index.html    |   3 +-
 .../prefect-gitlab/repositories/index.html    |  11 +-
 .../prefect-kubernetes/credentials/index.html |  19 +-
 .../custom_objects/index.html                 |  17 +-
 .../prefect-kubernetes/deployments/index.html |  17 +-
 .../prefect-kubernetes/exceptions/index.html  |  13 +-
 .../prefect-kubernetes/flows/index.html       |   9 +-
 .../prefect-kubernetes/index.html             |   3 +-
 .../prefect-kubernetes/jobs/index.html        |  31 +-
 .../prefect-kubernetes/pods/index.html        |  19 +-
 .../prefect-kubernetes/services/index.html    |  17 +-
 .../prefect-kubernetes/utilities/index.html   |   7 +-
 .../prefect-kubernetes/worker/index.html      |  23 +-
 .../integrations/prefect-ray/index.html       |   3 +-
 .../prefect-ray/task-runners/index.html       |   9 +-
 .../prefect-shell/commands/index.html         |  27 +-
 .../integrations/prefect-shell/index.html     |   3 +-
 .../prefect-slack/credentials/index.html      |  15 +-
 .../integrations/prefect-slack/index.html     |   3 +-
 .../prefect-slack/messages/index.html         |   9 +-
 .../prefect-snowflake/credentials/index.html  |  13 +-
 .../prefect-snowflake/database/index.html     |  29 +-
 .../integrations/prefect-snowflake/index.html |   3 +-
 .../prefect-sqlalchemy/credentials/index.html |  23 +-
 .../prefect-sqlalchemy/database/index.html    |  41 +-
 .../prefect-sqlalchemy/index.html             |   3 +-
 .../unreleased/integrations/usage/index.html  |   3 +-
 versions/unreleased/overrides/main.html       |   3 +-
 .../unreleased/recipes/recipes/index.html     |   3 +-
 versions/unreleased/search/search_index.json  |   2 +-
 versions/unreleased/sitemap.xml               | 672 +++++++++---------
 versions/unreleased/sitemap.xml.gz            | Bin 2439 -> 2439 bytes
 .../tutorial/deployments/index.html           |   3 +-
 versions/unreleased/tutorial/flows/index.html |   3 +-
 versions/unreleased/tutorial/index.html       |   3 +-
 versions/unreleased/tutorial/tasks/index.html |   3 +-
 .../unreleased/tutorial/work-pools/index.html |   3 +-
 .../unreleased/tutorial/workers/index.html    |   3 +-
 341 files changed, 3926 insertions(+), 3534 deletions(-)

diff --git a/versions/unreleased/404.html b/versions/unreleased/404.html
index d50e09a188..0347d203ee 100644
--- a/versions/unreleased/404.html
+++ b/versions/unreleased/404.html
@@ -197,7 +197,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/index.html b/versions/unreleased/api-ref/index.html
index 35c649af81..eae7374704 100644
--- a/versions/unreleased/api-ref/index.html
+++ b/versions/unreleased/api-ref/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/agent/index.html b/versions/unreleased/api-ref/prefect/agent/index.html
index 4e5d25436b..0cd1ca4750 100644
--- a/versions/unreleased/api-ref/prefect/agent/index.html
+++ b/versions/unreleased/api-ref/prefect/agent/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13298,7 +13299,7 @@ <h1 id="prefect.agent" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This module is deprecated as of March 2024 and will not be available after September 2024.
 Agents have been replaced by workers, which offer enhanced functionality and better performance.</p>
 <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>
@@ -14649,7 +14650,7 @@ <h3 id="prefect.agent.PrefectAgent.cancel_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Cancel a flow run by killing its infrastructure</p>
+        <p>Cancel a flow run by killing its infrastructure</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/agent.py</code></summary>
@@ -14809,7 +14810,7 @@ <h3 id="prefect.agent.PrefectAgent.get_and_submit_flow_runs" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>The principle method on agents. Queries for scheduled flow runs and submits
+        <p>The principle method on agents. Queries for scheduled flow runs and submits
 them for execution in parallel.</p>
 
             <details class="quote">
@@ -14986,7 +14987,7 @@ <h3 id="prefect.agent.PrefectAgent.get_work_queues" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Loads the work queue objects corresponding to the agent's target work
+        <p>Loads the work queue objects corresponding to the agent's target work
 queues. If any of them don't exist, they are created.</p>
 
             <details class="quote">
@@ -15133,7 +15134,7 @@ <h3 id="prefect.agent.PrefectAgent.submit_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a flow run to the infrastructure</p>
+        <p>Submit a flow run to the infrastructure</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/agent.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/artifacts/index.html b/versions/unreleased/api-ref/prefect/artifacts/index.html
index 2c009172fd..694f52610f 100644
--- a/versions/unreleased/api-ref/prefect/artifacts/index.html
+++ b/versions/unreleased/api-ref/prefect/artifacts/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13364,7 +13365,7 @@ <h1 id="prefect.artifacts" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Interface for creating and reading artifacts.</p>
+        <p>Interface for creating and reading artifacts.</p>
 
 
 
@@ -13393,7 +13394,7 @@ <h2 id="prefect.artifacts.Artifact" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.actions.ArtifactCreate" href="../client/schemas/#prefect.client.schemas.actions.ArtifactCreate">ArtifactCreate</a></code></p>
 
 
-      <p>An artifact is a piece of data that is created by a flow or task run.
+        <p>An artifact is a piece of data that is created by a flow or task run.
 https://docs.prefect.io/latest/concepts/artifacts/</p>
 
 
@@ -13699,7 +13700,7 @@ <h3 id="prefect.artifacts.Artifact.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A method to create an artifact.</p>
+        <p>A method to create an artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13830,7 +13831,7 @@ <h3 id="prefect.artifacts.Artifact.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A method to get an artifact.</p>
+        <p>A method to get an artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13973,7 +13974,7 @@ <h3 id="prefect.artifacts.Artifact.get_or_create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A method to get or create an artifact.</p>
+        <p>A method to get or create an artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14250,7 +14251,7 @@ <h2 id="prefect.artifacts.create_link_artifact" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a link artifact.</p>
+        <p>Create a link artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14432,7 +14433,7 @@ <h2 id="prefect.artifacts.create_markdown_artifact" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a markdown artifact.</p>
+        <p>Create a markdown artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14590,7 +14591,7 @@ <h2 id="prefect.artifacts.create_table_artifact" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a table artifact.</p>
+        <p>Create a table artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/automations/index.html b/versions/unreleased/api-ref/prefect/automations/index.html
index 4514326fbd..111a39511e 100644
--- a/versions/unreleased/api-ref/prefect/automations/index.html
+++ b/versions/unreleased/api-ref/prefect/automations/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14030,7 +14031,7 @@ <h3 id="prefect.automations.Automation.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new automation.</p>
+        <p>Create a new automation.</p>
 <p>auto_to_create = Automation(
     name="woodchonk",
     trigger=EventTrigger(
@@ -14119,7 +14120,7 @@ <h3 id="prefect.automations.Automation.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>auto = Automation.read(id = 123)
+        <p>auto = Automation.read(id = 123)
 auto.delete()</p>
 
             <details class="quote">
@@ -14172,7 +14173,7 @@ <h3 id="prefect.automations.Automation.disable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Disable an automation.
+        <p>Disable an automation.
 auto = Automation.read(id = 123)
 auto.disable()</p>
 
@@ -14228,7 +14229,7 @@ <h3 id="prefect.automations.Automation.enable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Enable an automation.
+        <p>Enable an automation.
 auto = Automation.read(id = 123)
 auto.enable()</p>
 
@@ -14285,7 +14286,7 @@ <h3 id="prefect.automations.Automation.read" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read an automation by ID or name.
+        <p>Read an automation by ID or name.
 automation = Automation.read(name="woodchonk")</p>
 <p>or</p>
 <p>automation = Automation.read(id=UUID("b3514963-02b1-47a5-93d1-6eeb131041cb"))</p>
@@ -14374,7 +14375,7 @@ <h3 id="prefect.automations.Automation.update" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates an existing automation.
+        <p>Updates an existing automation.
 auto = Automation.read(id=123)
 auto.name = "new name"
 auto.update()</p>
@@ -14434,7 +14435,7 @@ <h2 id="prefect.automations.AutomationCore" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines an action a user wants to take when a certain number of events
+        <p>Defines an action a user wants to take when a certain number of events
 do or don't happen to the matching resources</p>
 
               <details class="quote">
@@ -14547,7 +14548,7 @@ <h2 id="prefect.automations.CompositeTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.Trigger" href="#prefect.automations.Trigger">Trigger</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Requires some number of triggers to have fired within the given time period.</p>
+        <p>Requires some number of triggers to have fired within the given time period.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -14605,7 +14606,7 @@ <h2 id="prefect.automations.CompoundTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.CompositeTrigger" href="#prefect.automations.CompositeTrigger">CompositeTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have
+        <p>A composite trigger that requires some number of triggers to have
 fired within the given time period</p>
 
               <details class="quote">
@@ -14709,7 +14710,7 @@ <h3 id="prefect.automations.CompoundTrigger.describe_for_cli" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -14774,7 +14775,7 @@ <h2 id="prefect.automations.EventTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.ResourceTrigger" href="#prefect.automations.ResourceTrigger">ResourceTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the presence or absence of events within a given
+        <p>A trigger that fires based on the presence or absence of events within a given
 period of time.</p>
 
               <details class="quote">
@@ -15016,7 +15017,7 @@ <h3 id="prefect.automations.EventTrigger.describe_for_cli" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15091,7 +15092,7 @@ <h2 id="prefect.automations.MetricTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.ResourceTrigger" href="#prefect.automations.ResourceTrigger">ResourceTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the results of a metric query.</p>
+        <p>A trigger that fires based on the results of a metric query.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15176,7 +15177,7 @@ <h3 id="prefect.automations.MetricTrigger.describe_for_cli" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15231,7 +15232,7 @@ <h2 id="prefect.automations.MetricTriggerQuery" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines a subset of the Trigger subclass, which is specific
+        <p>Defines a subset of the Trigger subclass, which is specific
 to Metric automations, that specify the query configurations
 and breaching conditions for the Automation</p>
 
@@ -15361,7 +15362,7 @@ <h2 id="prefect.automations.ResourceSpecification" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A specification that may match zero, one, or many resources, used to target or
+        <p>A specification that may match zero, one, or many resources, used to target or
 select a set of resources in a query or automation.  A resource must match at least
 one value of all of the provided labels</p>
 
@@ -15565,7 +15566,7 @@ <h2 id="prefect.automations.ResourceTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.Trigger" href="#prefect.automations.Trigger">Trigger</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Base class for triggers that may filter by the labels of resources.</p>
+        <p>Base class for triggers that may filter by the labels of resources.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15637,7 +15638,7 @@ <h2 id="prefect.automations.SequenceTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.CompositeTrigger" href="#prefect.automations.CompositeTrigger">CompositeTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have fired
+        <p>A composite trigger that requires some number of triggers to have fired
 within the given time period in a specific order</p>
 
               <details class="quote">
@@ -15711,7 +15712,7 @@ <h3 id="prefect.automations.SequenceTrigger.describe_for_cli" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15776,7 +15777,7 @@ <h2 id="prefect.automations.Trigger" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Base class describing a set of criteria that must be satisfied in order to trigger
+        <p>Base class describing a set of criteria that must be satisfied in order to trigger
 an automation.</p>
 
               <details class="quote">
@@ -15920,7 +15921,7 @@ <h3 id="prefect.automations.Trigger.describe_for_cli" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/blocks/core/index.html b/versions/unreleased/api-ref/prefect/blocks/core/index.html
index 3e61d8fc2a..56f86a773b 100644
--- a/versions/unreleased/api-ref/prefect/blocks/core/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/core/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13576,7 +13577,7 @@ <h2 id="prefect.blocks.core.Block" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>A base class for implementing a block that wraps an external service.</p>
+        <p>A base class for implementing a block that wraps an external service.</p>
 <p>This class can be defined with an arbitrary set of fields and methods, and
 couples business logic with data contained in an block document.
 <code>_block_document_name</code>, <code>_block_document_id</code>, <code>_block_schema_id</code>, and
@@ -15562,7 +15563,7 @@ <h4 id="prefect.blocks.core.Block.Config.schema_extra" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Customizes Pydantic's schema generation feature to add blocks related information.</p>
+        <p>Customizes Pydantic's schema generation feature to add blocks related information.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/core.py</code></summary>
@@ -15693,7 +15694,7 @@ <h3 id="prefect.blocks.core.Block.get_block_capabilities" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns the block capabilities for this Block. Recursively collects all block
+        <p>Returns the block capabilities for this Block. Recursively collects all block
 capabilities of all parent classes into a single frozenset.</p>
 
             <details class="quote">
@@ -15744,7 +15745,7 @@ <h3 id="prefect.blocks.core.Block.get_block_class_from_key" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the block class implementation given a key.</p>
+        <p>Retrieve the block class implementation given a key.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/core.py</code></summary>
@@ -15788,7 +15789,7 @@ <h3 id="prefect.blocks.core.Block.get_block_class_from_schema" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the block class implementation given a schema.</p>
+        <p>Retrieve the block class implementation given a schema.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/core.py</code></summary>
@@ -15820,7 +15821,7 @@ <h3 id="prefect.blocks.core.Block.get_block_placeholder" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Returns the block placeholder for the current block which can be used for
+        <p>Returns the block placeholder for the current block which can be used for
 templating.</p>
 
 
@@ -15869,7 +15870,7 @@ <h3 id="prefect.blocks.core.Block.get_block_placeholder" class="doc doc-heading"
           </tr>
       </tbody>
     </table>
-      <p>If a block has not been saved, the return value will be <code>None</code>.</p>
+        <p>If a block has not been saved, the return value will be <code>None</code>.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/core.py</code></summary>
@@ -15935,7 +15936,7 @@ <h3 id="prefect.blocks.core.Block.get_code_example" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns the code example for the given block. Attempts to parse
+        <p>Returns the code example for the given block. Attempts to parse
 code example from the class docstring if an override is not provided.</p>
 
             <details class="quote">
@@ -16034,7 +16035,7 @@ <h3 id="prefect.blocks.core.Block.get_description" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns the description for the current block. Attempts to parse
+        <p>Returns the description for the current block. Attempts to parse
 description from class docstring if an override is not defined.</p>
 
             <details class="quote">
@@ -16104,7 +16105,7 @@ <h3 id="prefect.blocks.core.Block.load" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves data from the block document with the given name for the block type
+        <p>Retrieves data from the block document with the given name for the block type
 that corresponds with the current class and returns an instantiated version of
 the current class with the data stored in the block document.</p>
 <p>If a block document for a given block type is saved with a different schema
@@ -16509,7 +16510,7 @@ <h3 id="prefect.blocks.core.Block.register_type_and_schema" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Makes block available for configuration with current Prefect API.
+        <p>Makes block available for configuration with current Prefect API.
 Recursively registers all nested blocks. Registration is idempotent.</p>
 
 
@@ -16689,7 +16690,7 @@ <h3 id="prefect.blocks.core.Block.save" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Saves the values of a block as a block document.</p>
+        <p>Saves the values of a block as a block document.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16809,7 +16810,7 @@ <h2 id="prefect.blocks.core.BlockNotSavedError" class="doc doc-heading">
               Bases: <code>RuntimeError</code></p>
 
 
-      <p>Raised when a given block is not saved and an operation that requires
+        <p>Raised when a given block is not saved and an operation that requires
 the block to be saved is attempted.</p>
 
               <details class="quote">
@@ -16850,7 +16851,7 @@ <h2 id="prefect.blocks.core.InvalidBlockRegistration" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised on attempted registration of the base Block
+        <p>Raised on attempted registration of the base Block
 class or a Block interface class</p>
 
               <details class="quote">
@@ -16883,7 +16884,7 @@ <h2 id="prefect.blocks.core.block_schema_to_key" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Defines the unique key used to lookup the Block class for a given schema.</p>
+        <p>Defines the unique key used to lookup the Block class for a given schema.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/core.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/blocks/fields/index.html b/versions/unreleased/api-ref/prefect/blocks/fields/index.html
index 3952adf317..2a6785f6df 100644
--- a/versions/unreleased/api-ref/prefect/blocks/fields/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/fields/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/blocks/kubernetes/index.html b/versions/unreleased/api-ref/prefect/blocks/kubernetes/index.html
index 5db71f90ea..42665c225f 100644
--- a/versions/unreleased/api-ref/prefect/blocks/kubernetes/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/kubernetes/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13322,7 +13323,7 @@ <h2 id="prefect.blocks.kubernetes.KubernetesClusterConfig" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Stores configuration for interaction with Kubernetes clusters.</p>
+        <p>Stores configuration for interaction with Kubernetes clusters.</p>
 <p>See <code>from_file</code> for creation.</p>
 
 
@@ -13581,7 +13582,7 @@ <h3 id="prefect.blocks.kubernetes.KubernetesClusterConfig.configure_client" clas
 
     <div class="doc doc-contents ">
 
-      <p>Activates this cluster configuration by loading the configuration into the
+        <p>Activates this cluster configuration by loading the configuration into the
 Kubernetes Python client. After calling this, Kubernetes API clients can use
 this config's context.</p>
 
@@ -13625,7 +13626,7 @@ <h3 id="prefect.blocks.kubernetes.KubernetesClusterConfig.from_file" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a cluster config from the a Kubernetes config file.</p>
+        <p>Create a cluster config from the a Kubernetes config file.</p>
 <p>By default, the current context in the default Kubernetes config file will be
 used.</p>
 <p>An alternative file or context may be specified.</p>
@@ -13721,7 +13722,7 @@ <h3 id="prefect.blocks.kubernetes.KubernetesClusterConfig.get_api_client" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a Kubernetes API client for this cluster config.</p>
+        <p>Returns a Kubernetes API client for this cluster config.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/kubernetes.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/blocks/notifications/index.html b/versions/unreleased/api-ref/prefect/blocks/notifications/index.html
index 78e17fcd6f..428392ccca 100644
--- a/versions/unreleased/api-ref/prefect/blocks/notifications/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/notifications/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13498,7 +13499,7 @@ <h2 id="prefect.blocks.notifications.AbstractAppriseNotificationBlock" class="do
               Bases: <code><span title="prefect.blocks.abstract.NotificationBlock">NotificationBlock</span></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>An abstract class for sending notifications using Apprise.</p>
+        <p>An abstract class for sending notifications using Apprise.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/blocks/notifications.py</code></summary>
@@ -13646,7 +13647,7 @@ <h2 id="prefect.blocks.notifications.AppriseNotificationBlock" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>A base class for sending notifications using Apprise, through webhook URLs.</p>
+        <p>A base class for sending notifications using Apprise, through webhook URLs.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/blocks/notifications.py</code></summary>
@@ -13712,7 +13713,7 @@ <h2 id="prefect.blocks.notifications.CustomWebhookNotificationBlock" class="doc
               Bases: <code><span title="prefect.blocks.abstract.NotificationBlock">NotificationBlock</span></code></p>
 
 
-      <p>Enables sending notifications via any custom webhook.</p>
+        <p>Enables sending notifications via any custom webhook.</p>
 <p>All nested string param contains <code>{{key}}</code> will be substituted with value from context/secrets.</p>
 <p>Context values include: <code>subject</code>, <code>body</code> and <code>name</code>.</p>
 
@@ -14030,7 +14031,7 @@ <h2 id="prefect.blocks.notifications.DiscordWebhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided Discord webhook.
+        <p>Enables sending notifications via a provided Discord webhook.
 See <a href="https://github.com/caronc/apprise/wiki/Notify_Discord">Apprise notify_Discord docs</a> # noqa</p>
 
 
@@ -14265,7 +14266,7 @@ <h2 id="prefect.blocks.notifications.MattermostWebhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided Mattermost webhook.
+        <p>Enables sending notifications via a provided Mattermost webhook.
 See <a href="https://github.com/caronc/apprise/wiki/Notify_Mattermost">Apprise notify_Mattermost docs</a> # noqa</p>
 
 
@@ -14468,7 +14469,7 @@ <h2 id="prefect.blocks.notifications.MicrosoftTeamsWebhook" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AppriseNotificationBlock" href="#prefect.blocks.notifications.AppriseNotificationBlock">AppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided Microsoft Teams webhook.</p>
+        <p>Enables sending notifications via a provided Microsoft Teams webhook.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -14613,7 +14614,7 @@ <h3 id="prefect.blocks.notifications.MicrosoftTeamsWebhook.block_initialization"
 
     <div class="doc doc-contents ">
 
-      <p>see https://github.com/caronc/apprise/pull/1172</p>
+        <p>see https://github.com/caronc/apprise/pull/1172</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/notifications.py</code></summary>
@@ -14680,7 +14681,7 @@ <h2 id="prefect.blocks.notifications.OpsgenieWebhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided Opsgenie webhook.
+        <p>Enables sending notifications via a provided Opsgenie webhook.
 See <a href="https://github.com/caronc/apprise/wiki/Notify_opsgenie">Apprise notify_opsgenie docs</a>
 for more info on formatting the URL.</p>
 
@@ -14952,7 +14953,7 @@ <h2 id="prefect.blocks.notifications.PagerDutyWebHook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided PagerDuty webhook.
+        <p>Enables sending notifications via a provided PagerDuty webhook.
 See <a href="https://github.com/caronc/apprise/wiki/Notify_pagerduty">Apprise notify_pagerduty docs</a>
 for more info on formatting the URL.</p>
 
@@ -15216,7 +15217,7 @@ <h2 id="prefect.blocks.notifications.SendgridEmail" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via any sendgrid account.
+        <p>Enables sending notifications via any sendgrid account.
 See <a href="https://github.com/caronc/apprise/wiki/Notify_Sendgrid">Apprise Notify_sendgrid docs</a></p>
 
 
@@ -15371,7 +15372,7 @@ <h2 id="prefect.blocks.notifications.SlackWebhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AppriseNotificationBlock" href="#prefect.blocks.notifications.AppriseNotificationBlock">AppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via a provided Slack webhook.</p>
+        <p>Enables sending notifications via a provided Slack webhook.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -15470,7 +15471,7 @@ <h2 id="prefect.blocks.notifications.TwilioSMS" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.notifications.AbstractAppriseNotificationBlock" href="#prefect.blocks.notifications.AbstractAppriseNotificationBlock">AbstractAppriseNotificationBlock</a></code></p>
 
 
-      <p>Enables sending notifications via Twilio SMS.
+        <p>Enables sending notifications via Twilio SMS.
 Find more on sending Twilio SMS messages in the <a href="https://www.twilio.com/docs/sms">docs</a>.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/blocks/system/index.html b/versions/unreleased/api-ref/prefect/blocks/system/index.html
index 243abbfd36..cd36e5d25e 100644
--- a/versions/unreleased/api-ref/prefect/blocks/system/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/system/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13310,7 +13311,7 @@ <h2 id="prefect.blocks.system.DateTime" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>A block that represents a datetime</p>
+        <p>A block that represents a datetime</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13434,7 +13435,7 @@ <h2 id="prefect.blocks.system.JSON" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>A block that represents JSON</p>
+        <p>A block that represents JSON</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13550,7 +13551,7 @@ <h2 id="prefect.blocks.system.Secret" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>A block that represents a secret value. The value stored in this block will be obfuscated when
+        <p>A block that represents a secret value. The value stored in this block will be obfuscated when
 this block is logged or shown in the UI.</p>
 
 
@@ -13685,7 +13686,7 @@ <h2 id="prefect.blocks.system.String" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>A block that represents a string</p>
+        <p>A block that represents a string</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/blocks/webhook/index.html b/versions/unreleased/api-ref/prefect/blocks/webhook/index.html
index 5ee39ef1ec..4875e7f710 100644
--- a/versions/unreleased/api-ref/prefect/blocks/webhook/index.html
+++ b/versions/unreleased/api-ref/prefect/blocks/webhook/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13278,7 +13279,7 @@ <h2 id="prefect.blocks.webhook.Webhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block that enables calling webhooks.</p>
+        <p>Block that enables calling webhooks.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/blocks/webhook.py</code></summary>
@@ -13397,7 +13398,7 @@ <h3 id="prefect.blocks.webhook.Webhook.call" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Call the webhook.</p>
+        <p>Call the webhook.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/cli/agent/index.html b/versions/unreleased/api-ref/prefect/cli/agent/index.html
index 714bd9bcf4..ec3325cf0a 100644
--- a/versions/unreleased/api-ref/prefect/cli/agent/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/agent/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13217,7 +13218,7 @@ <h1 id="prefect.cli.agent" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with agent services</p>
+        <p>Command line interface for working with agent services</p>
 
 
 
@@ -13246,7 +13247,7 @@ <h2 id="prefect.cli.agent.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Start an agent process to poll one or more work queues for flow runs.</p>
+        <p>Start an agent process to poll one or more work queues for flow runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/agent.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/artifact/index.html b/versions/unreleased/api-ref/prefect/cli/artifact/index.html
index 4d4d65522e..afbf4bc750 100644
--- a/versions/unreleased/api-ref/prefect/cli/artifact/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/artifact/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h2 id="prefect.cli.artifact.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete an artifact.</p>
+        <p>Delete an artifact.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13477,7 +13478,7 @@ <h2 id="prefect.cli.artifact.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <div class="codehilite"><pre><span></span><code><span class="nx">View</span><span class="w"> </span><span class="nx">details</span><span class="w"> </span><span class="nx">about</span><span class="w"> </span><span class="nx">an</span><span class="w"> </span><span class="nx">artifact</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="nx">View</span><span class="w"> </span><span class="nx">details</span><span class="w"> </span><span class="nx">about</span><span class="w"> </span><span class="nx">an</span><span class="w"> </span><span class="nx">artifact</span><span class="p">.</span>
 
 <span class="nx">Arguments</span><span class="p">:</span>
 <span class="w">    </span><span class="nx">key</span><span class="p">:</span><span class="w"> </span><span class="nx">the</span><span class="w"> </span><span class="nx">key</span><span class="w"> </span><span class="nx">of</span><span class="w"> </span><span class="nx">the</span><span class="w"> </span><span class="nx">artifact</span><span class="w"> </span><span class="nx">to</span><span class="w"> </span><span class="nx">inspect</span>
@@ -13649,7 +13650,7 @@ <h2 id="prefect.cli.artifact.list_artifacts" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List artifacts.</p>
+        <p>List artifacts.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/artifact.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/block/index.html b/versions/unreleased/api-ref/prefect/cli/block/index.html
index 39d636a719..8ec7fb9ecf 100644
--- a/versions/unreleased/api-ref/prefect/cli/block/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/block/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13371,7 +13372,7 @@ <h1 id="prefect.cli.block" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with blocks.</p>
+        <p>Command line interface for working with blocks.</p>
 
 
 
@@ -13400,7 +13401,7 @@ <h2 id="prefect.cli.block.block_create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generate a link to the Prefect UI to create a block.</p>
+        <p>Generate a link to the Prefect UI to create a block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13486,7 +13487,7 @@ <h2 id="prefect.cli.block.block_delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a configured block.</p>
+        <p>Delete a configured block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13576,7 +13577,7 @@ <h2 id="prefect.cli.block.block_inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Displays details about a configured block.</p>
+        <p>Displays details about a configured block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13670,7 +13671,7 @@ <h2 id="prefect.cli.block.block_ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View all configured blocks.</p>
+        <p>View all configured blocks.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13744,7 +13745,7 @@ <h2 id="prefect.cli.block.blocktype_delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete an unprotected Block Type.</p>
+        <p>Delete an unprotected Block Type.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13804,7 +13805,7 @@ <h2 id="prefect.cli.block.blocktype_inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Display details about a block type.</p>
+        <p>Display details about a block type.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13856,7 +13857,7 @@ <h2 id="prefect.cli.block.list_types" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List all block types.</p>
+        <p>List all block types.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/block.py</code></summary>
@@ -13942,7 +13943,7 @@ <h2 id="prefect.cli.block.register" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Register blocks types within a module or file.</p>
+        <p>Register blocks types within a module or file.</p>
 <p>This makes the blocks available for configuration via the UI.
 If a block type has already been registered, its registration will be updated to
 match the block's current definition.</p>
diff --git a/versions/unreleased/api-ref/prefect/cli/cloud-webhook/index.html b/versions/unreleased/api-ref/prefect/cli/cloud-webhook/index.html
index b024674871..0147f68a02 100644
--- a/versions/unreleased/api-ref/prefect/cli/cloud-webhook/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/cloud-webhook/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13158,7 +13159,7 @@ <h1 id="prefect.cli.cloud.webhook" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with webhooks</p>
+        <p>Command line interface for working with webhooks</p>
 
 
 
@@ -13187,7 +13188,7 @@ <h2 id="prefect.cli.cloud.webhook.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new Cloud webhook</p>
+        <p>Create a new Cloud webhook</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13283,7 +13284,7 @@ <h2 id="prefect.cli.cloud.webhook.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete an existing Cloud webhook</p>
+        <p>Delete an existing Cloud webhook</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13343,7 +13344,7 @@ <h2 id="prefect.cli.cloud.webhook.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve a webhook by ID.</p>
+        <p>Retrieve a webhook by ID.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13391,7 +13392,7 @@ <h2 id="prefect.cli.cloud.webhook.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Fetch and list all webhooks in your workspace</p>
+        <p>Fetch and list all webhooks in your workspace</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13439,7 +13440,7 @@ <h2 id="prefect.cli.cloud.webhook.rotate" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Rotate url for an existing Cloud webhook, in case it has been compromised</p>
+        <p>Rotate url for an existing Cloud webhook, in case it has been compromised</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13499,7 +13500,7 @@ <h2 id="prefect.cli.cloud.webhook.toggle" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Toggle the enabled status of an existing Cloud webhook</p>
+        <p>Toggle the enabled status of an existing Cloud webhook</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
@@ -13563,7 +13564,7 @@ <h2 id="prefect.cli.cloud.webhook.update" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Partially update an existing Cloud webhook</p>
+        <p>Partially update an existing Cloud webhook</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/webhook.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/cloud/index.html b/versions/unreleased/api-ref/prefect/cli/cloud/index.html
index c4d3b1fb4e..e53a1b6fdb 100644
--- a/versions/unreleased/api-ref/prefect/cli/cloud/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/cloud/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13393,7 +13394,7 @@ <h1 id="prefect.cli.cloud" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for interacting with Prefect Cloud</p>
+        <p>Command line interface for interacting with Prefect Cloud</p>
 
 
 
@@ -13421,7 +13422,7 @@ <h2 id="prefect.cli.cloud.login_api" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This small API server is used for data transmission for browser-based log in.</p>
+        <p>This small API server is used for data transmission for browser-based log in.</p>
     </div>
 
 </div>
@@ -13443,7 +13444,7 @@ <h2 id="prefect.cli.cloud.check_key_is_valid_for_login" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Attempt to use a key to see if it is valid</p>
+        <p>Attempt to use a key to see if it is valid</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/__init__.py</code></summary>
@@ -13487,7 +13488,7 @@ <h2 id="prefect.cli.cloud.login" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Log in to Prefect Cloud.
+        <p>Log in to Prefect Cloud.
 Creates a new profile configured to use the specified PREFECT_API_KEY.
 Uses a previously configured profile if it exists.</p>
 
@@ -13901,7 +13902,7 @@ <h2 id="prefect.cli.cloud.login_with_browser" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Perform login using the browser.</p>
+        <p>Perform login using the browser.</p>
 <p>On failure, this function will exit the process.
 On success, it will return an API key.</p>
 
@@ -14041,7 +14042,7 @@ <h2 id="prefect.cli.cloud.logout" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Logout the current workspace.
+        <p>Logout the current workspace.
 Reset PREFECT_API_KEY and PREFECT_API_URL to default.</p>
 
             <details class="quote">
@@ -14108,7 +14109,7 @@ <h2 id="prefect.cli.cloud.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List available workspaces.</p>
+        <p>List available workspaces.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/__init__.py</code></summary>
@@ -14188,7 +14189,7 @@ <h2 id="prefect.cli.cloud.open" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Open the Prefect Cloud UI in the browser.</p>
+        <p>Open the Prefect Cloud UI in the browser.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/__init__.py</code></summary>
@@ -14264,7 +14265,7 @@ <h2 id="prefect.cli.cloud.prompt_select_from_list" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a list of options, display the values to user in a table and prompt them
+        <p>Given a list of options, display the values to user in a table and prompt them
 to select one.</p>
 
 
@@ -14477,7 +14478,7 @@ <h2 id="prefect.cli.cloud.set" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set current workspace. Shows a workspace picker if no workspace is specified.</p>
+        <p>Set current workspace. Shows a workspace picker if no workspace is specified.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/cloud/__init__.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/concurrency_limit/index.html b/versions/unreleased/api-ref/prefect/cli/concurrency_limit/index.html
index 73d03418e5..813ff4743a 100644
--- a/versions/unreleased/api-ref/prefect/cli/concurrency_limit/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/concurrency_limit/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.cli.concurrency_limit" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with concurrency limits.</p>
+        <p>Command line interface for working with concurrency limits.</p>
 
 
 
@@ -13334,7 +13335,7 @@ <h2 id="prefect.cli.concurrency_limit.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a concurrency limit against a tag.</p>
+        <p>Create a concurrency limit against a tag.</p>
 <p>This limit controls how many task runs with that tag may simultaneously be in a
 Running state.</p>
 
@@ -13420,7 +13421,7 @@ <h2 id="prefect.cli.concurrency_limit.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete the concurrency limit set on the specified tag.</p>
+        <p>Delete the concurrency limit set on the specified tag.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/concurrency_limit.py</code></summary>
@@ -13470,7 +13471,7 @@ <h2 id="prefect.cli.concurrency_limit.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View details about a concurrency limit. <code>active_slots</code> shows a list of TaskRun IDs
+        <p>View details about a concurrency limit. <code>active_slots</code> shows a list of TaskRun IDs
 which are currently using a concurrency slot.</p>
 
             <details class="quote">
@@ -13569,7 +13570,7 @@ <h2 id="prefect.cli.concurrency_limit.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View all concurrency limits.</p>
+        <p>View all concurrency limits.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/concurrency_limit.py</code></summary>
@@ -13649,7 +13650,7 @@ <h2 id="prefect.cli.concurrency_limit.reset" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resets the concurrency limit slots set on the specified tag.</p>
+        <p>Resets the concurrency limit slots set on the specified tag.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/concurrency_limit.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/config/index.html b/versions/unreleased/api-ref/prefect/cli/config/index.html
index d6f607f55c..200b9f3054 100644
--- a/versions/unreleased/api-ref/prefect/cli/config/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/config/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13283,7 +13284,7 @@ <h1 id="prefect.cli.config" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with profiles</p>
+        <p>Command line interface for working with profiles</p>
 
 
 
@@ -13308,7 +13309,7 @@ <h2 id="prefect.cli.config.set_" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Change the value for a setting by setting the value in the current profile.</p>
+        <p>Change the value for a setting by setting the value in the current profile.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/config.py</code></summary>
@@ -13426,7 +13427,7 @@ <h2 id="prefect.cli.config.unset" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Restore the default value for a setting.</p>
+        <p>Restore the default value for a setting.</p>
 <p>Removes the setting from the current profile.</p>
 
             <details class="quote">
@@ -13519,7 +13520,7 @@ <h2 id="prefect.cli.config.validate" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read and validate the current profile.</p>
+        <p>Read and validate the current profile.</p>
 <p>Deprecated settings will be automatically converted to new names unless both are
 set.</p>
 
@@ -13585,7 +13586,7 @@ <h2 id="prefect.cli.config.view" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Display the current settings.</p>
+        <p>Display the current settings.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/config.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/deploy/index.html b/versions/unreleased/api-ref/prefect/cli/deploy/index.html
index 59fdc12e6c..66d0d3371b 100644
--- a/versions/unreleased/api-ref/prefect/cli/deploy/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/deploy/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.cli.deploy" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing implementation for deploying flows.</p>
+        <p>Module containing implementation for deploying flows.</p>
 
 
 
@@ -13268,7 +13269,7 @@ <h2 id="prefect.cli.deploy.deploy" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deploy a flow from this project by creating a deployment.</p>
+        <p>Deploy a flow from this project by creating a deployment.</p>
 <p>Should be run from a project root directory.</p>
 
             <details class="quote">
@@ -13761,7 +13762,7 @@ <h2 id="prefect.cli.deploy.init" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Initialize a new deployment configuration recipe.</p>
+        <p>Initialize a new deployment configuration recipe.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deploy.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/deployment/index.html b/versions/unreleased/api-ref/prefect/cli/deployment/index.html
index dd97f82a4a..a53f7a7914 100644
--- a/versions/unreleased/api-ref/prefect/cli/deployment/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/deployment/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13481,7 +13482,7 @@ <h1 id="prefect.cli.deployment" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with deployments.</p>
+        <p>Command line interface for working with deployments.</p>
 
 
 
@@ -13510,7 +13511,7 @@ <h2 id="prefect.cli.deployment.apply" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create or update a deployment from a YAML file.</p>
+        <p>Create or update a deployment from a YAML file.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -13788,7 +13789,7 @@ <h2 id="prefect.cli.deployment.build" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generate a deployment YAML from /path/to/file.py:flow_function</p>
+        <p>Generate a deployment YAML from /path/to/file.py:flow_function</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -14654,7 +14655,7 @@ <h2 id="prefect.cli.deployment.clear_schedules" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clear all schedules for a deployment.</p>
+        <p>Clear all schedules for a deployment.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -14748,7 +14749,7 @@ <h2 id="prefect.cli.deployment.create_schedule" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a schedule for a given deployment.</p>
+        <p>Create a schedule for a given deployment.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15048,7 +15049,7 @@ <h2 id="prefect.cli.deployment.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a deployment.</p>
+        <p>Delete a deployment.</p>
 <p>
 Examples:
     
@@ -15145,7 +15146,7 @@ <h2 id="prefect.cli.deployment.delete_schedule" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a deployment schedule.</p>
+        <p>Delete a deployment schedule.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15245,7 +15246,7 @@ <h2 id="prefect.cli.deployment.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View details about a deployment.</p>
+        <p>View details about a deployment.</p>
 <p>
 Example:
     
@@ -15443,7 +15444,7 @@ <h2 id="prefect.cli.deployment.list_schedules" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View all schedules for a deployment.</p>
+        <p>View all schedules for a deployment.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15549,7 +15550,7 @@ <h2 id="prefect.cli.deployment.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View all deployments or deployments for specific flows.</p>
+        <p>View all deployments or deployments for specific flows.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15647,7 +15648,7 @@ <h2 id="prefect.cli.deployment.pause_schedule" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pause a deployment schedule.</p>
+        <p>Pause a deployment schedule.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15729,7 +15730,7 @@ <h2 id="prefect.cli.deployment.resume_schedule" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resume a deployment schedule.</p>
+        <p>Resume a deployment schedule.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/deployment.py</code></summary>
@@ -15807,7 +15808,7 @@ <h2 id="prefect.cli.deployment.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run for the given flow and deployment.</p>
+        <p>Create a flow run for the given flow and deployment.</p>
 <p>The flow run will be scheduled to run immediately unless <code>--start-in</code> or <code>--start-at</code> is specified.
 The flow run will not execute until a worker starts.
 To watch the flow run until it reaches a terminal state, use the <code>--watch</code> flag.</p>
@@ -16310,7 +16311,7 @@ <h2 id="prefect.cli.deployment.str_presenter" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>configures yaml for dumping multiline strings
+        <p>configures yaml for dumping multiline strings
 Ref: https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/cli/dev/index.html b/versions/unreleased/api-ref/prefect/cli/dev/index.html
index eebe684c1c..f04079b114 100644
--- a/versions/unreleased/api-ref/prefect/cli/dev/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/dev/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13393,7 +13394,7 @@ <h1 id="prefect.cli.dev" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with Prefect Server</p>
+        <p>Command line interface for working with Prefect Server</p>
 
 
 
@@ -13422,7 +13423,7 @@ <h2 id="prefect.cli.dev.agent" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Starts a hot-reloading development agent process.</p>
+        <p>Starts a hot-reloading development agent process.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
@@ -13500,7 +13501,7 @@ <h2 id="prefect.cli.dev.agent_process_entrypoint" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>An entrypoint for starting an agent in a subprocess. Adds a Rich console
+        <p>An entrypoint for starting an agent in a subprocess. Adds a Rich console
 to the Typer app, processes Typer default parameters, then starts an agent.
 All kwargs are forwarded to  <code>prefect.cli.agent.start</code>.</p>
 
@@ -13602,7 +13603,7 @@ <h2 id="prefect.cli.dev.api" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Starts a hot-reloading development API.</p>
+        <p>Starts a hot-reloading development API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
@@ -13754,7 +13755,7 @@ <h2 id="prefect.cli.dev.build_docs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Builds REST API reference documentation for static display.</p>
+        <p>Builds REST API reference documentation for static display.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
@@ -13818,7 +13819,7 @@ <h2 id="prefect.cli.dev.build_image" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Build a docker image for development.</p>
+        <p>Build a docker image for development.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
@@ -13972,7 +13973,7 @@ <h2 id="prefect.cli.dev.container" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run a docker container with local code mounted and installed.</p>
+        <p>Run a docker container with local code mounted and installed.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
@@ -14166,7 +14167,7 @@ <h2 id="prefect.cli.dev.kubernetes_manifest" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates a Kubernetes manifest for development.</p>
+        <p>Generates a Kubernetes manifest for development.</p>
 
 
 <details class="example" open>
@@ -14239,7 +14240,7 @@ <h2 id="prefect.cli.dev.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Starts a hot-reloading development server with API, UI, and agent processes.</p>
+        <p>Starts a hot-reloading development server with API, UI, and agent processes.</p>
 <p>Each service has an individual command if you wish to start them separately.
 Each service can be excluded here as well.</p>
 
@@ -14337,7 +14338,7 @@ <h2 id="prefect.cli.dev.ui" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Starts a hot-reloading development UI.</p>
+        <p>Starts a hot-reloading development UI.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/dev.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/events/index.html b/versions/unreleased/api-ref/prefect/cli/events/index.html
index 9da093a503..0f50f0a9f1 100644
--- a/versions/unreleased/api-ref/prefect/cli/events/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/events/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13119,7 +13120,7 @@ <h2 id="prefect.cli.events.stream" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Subscribes to the event stream of a workspace, printing each event
+        <p>Subscribes to the event stream of a workspace, printing each event
 as it is received. By default, events are printed as JSON, but can be
 printed as text by passing <code>--format text</code>.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/cli/flow/index.html b/versions/unreleased/api-ref/prefect/cli/flow/index.html
index ee58c05b25..79ad3805c2 100644
--- a/versions/unreleased/api-ref/prefect/cli/flow/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/flow/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.cli.flow" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with flows.</p>
+        <p>Command line interface for working with flows.</p>
 
 
 
@@ -13268,7 +13269,7 @@ <h2 id="prefect.cli.flow.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View flows.</p>
+        <p>View flows.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow.py</code></summary>
@@ -13344,7 +13345,7 @@ <h2 id="prefect.cli.flow.serve" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Serve a flow via an entrypoint.</p>
+        <p>Serve a flow via an entrypoint.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/flow_run/index.html b/versions/unreleased/api-ref/prefect/cli/flow_run/index.html
index 8000acdeb6..59ab4ab689 100644
--- a/versions/unreleased/api-ref/prefect/cli/flow_run/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/flow_run/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.cli.flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with flow runs</p>
+        <p>Command line interface for working with flow runs</p>
 
 
 
@@ -13334,7 +13335,7 @@ <h2 id="prefect.cli.flow_run.cancel" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Cancel a flow run by ID.</p>
+        <p>Cancel a flow run by ID.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow_run.py</code></summary>
@@ -13396,7 +13397,7 @@ <h2 id="prefect.cli.flow_run.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run by ID.</p>
+        <p>Delete a flow run by ID.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow_run.py</code></summary>
@@ -13444,7 +13445,7 @@ <h2 id="prefect.cli.flow_run.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View details about a flow run.</p>
+        <p>View details about a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow_run.py</code></summary>
@@ -13498,7 +13499,7 @@ <h2 id="prefect.cli.flow_run.logs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View logs for a flow run.</p>
+        <p>View logs for a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/flow_run.py</code></summary>
@@ -13760,7 +13761,7 @@ <h2 id="prefect.cli.flow_run.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View recent flow runs or flow runs for specific flows.</p>
+        <p>View recent flow runs or flow runs for specific flows.</p>
 <p>Arguments:</p>
 <div class="codehilite"><pre><span></span><code><span class="n">flow_name</span><span class="o">:</span><span class="w"> </span><span class="n">Name</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">flow</span>
 
diff --git a/versions/unreleased/api-ref/prefect/cli/kubernetes/index.html b/versions/unreleased/api-ref/prefect/cli/kubernetes/index.html
index 0698aa98a8..229f05f8db 100644
--- a/versions/unreleased/api-ref/prefect/cli/kubernetes/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/kubernetes/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13261,7 +13262,7 @@ <h1 id="prefect.cli.kubernetes" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with Prefect on Kubernetes</p>
+        <p>Command line interface for working with Prefect on Kubernetes</p>
 
 
 
@@ -13286,7 +13287,7 @@ <h2 id="prefect.cli.kubernetes.manifest_agent" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates a manifest for deploying Agent on Kubernetes.</p>
+        <p>Generates a manifest for deploying Agent on Kubernetes.</p>
 
 
 <details class="example" open>
@@ -13405,7 +13406,7 @@ <h2 id="prefect.cli.kubernetes.manifest_flow_run_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Prints the default KubernetesJob Job manifest.</p>
+        <p>Prints the default KubernetesJob Job manifest.</p>
 <p>Use this file to fully customize your <code>KubernetesJob</code> deployments.</p>
 <p>
 Example:
@@ -13514,7 +13515,7 @@ <h2 id="prefect.cli.kubernetes.manifest_server" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates a manifest for deploying Prefect on Kubernetes.</p>
+        <p>Generates a manifest for deploying Prefect on Kubernetes.</p>
 
 
 <details class="example" open>
diff --git a/versions/unreleased/api-ref/prefect/cli/profile/index.html b/versions/unreleased/api-ref/prefect/cli/profile/index.html
index 400373ff3b..fb710e0c4a 100644
--- a/versions/unreleased/api-ref/prefect/cli/profile/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/profile/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13327,7 +13328,7 @@ <h1 id="prefect.cli.profile" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with profiles.</p>
+        <p>Command line interface for working with profiles.</p>
 
 
 
@@ -13352,7 +13353,7 @@ <h2 id="prefect.cli.profile.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new profile.</p>
+        <p>Create a new profile.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
@@ -13470,7 +13471,7 @@ <h2 id="prefect.cli.profile.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete the given profile.</p>
+        <p>Delete the given profile.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
@@ -13538,7 +13539,7 @@ <h2 id="prefect.cli.profile.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Display settings from a given profile; defaults to active.</p>
+        <p>Display settings from a given profile; defaults to active.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
@@ -13608,7 +13609,7 @@ <h2 id="prefect.cli.profile.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List profile names.</p>
+        <p>List profile names.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
@@ -13668,7 +13669,7 @@ <h2 id="prefect.cli.profile.rename" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Change the name of a profile.</p>
+        <p>Change the name of a profile.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
@@ -13748,7 +13749,7 @@ <h2 id="prefect.cli.profile.use" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set the given profile to active.</p>
+        <p>Set the given profile to active.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/profile.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/root/index.html b/versions/unreleased/api-ref/prefect/cli/root/index.html
index f75ead9734..78f510b4e1 100644
--- a/versions/unreleased/api-ref/prefect/cli/root/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/root/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13217,7 +13218,7 @@ <h1 id="prefect.cli.root" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Base <code>prefect</code> command-line application</p>
+        <p>Base <code>prefect</code> command-line application</p>
 
 
 
@@ -13246,7 +13247,7 @@ <h2 id="prefect.cli.root.version" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current Prefect version.</p>
+        <p>Get the current Prefect version.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/root.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/server/index.html b/versions/unreleased/api-ref/prefect/cli/server/index.html
index 4cb8843b9c..88a1e856e9 100644
--- a/versions/unreleased/api-ref/prefect/cli/server/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/server/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13349,7 +13350,7 @@ <h1 id="prefect.cli.server" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with Prefect</p>
+        <p>Command line interface for working with Prefect</p>
 
 
 
@@ -13378,7 +13379,7 @@ <h2 id="prefect.cli.server.downgrade" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downgrade the Prefect database</p>
+        <p>Downgrade the Prefect database</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13486,7 +13487,7 @@ <h2 id="prefect.cli.server.reset" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Drop and recreate all Prefect database tables</p>
+        <p>Drop and recreate all Prefect database tables</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13548,7 +13549,7 @@ <h2 id="prefect.cli.server.revision" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new migration for the Prefect database</p>
+        <p>Create a new migration for the Prefect database</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13612,7 +13613,7 @@ <h2 id="prefect.cli.server.stamp" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Stamp the revision table with the given revision; don't run any migrations</p>
+        <p>Stamp the revision table with the given revision; don't run any migrations</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13652,7 +13653,7 @@ <h2 id="prefect.cli.server.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Start a Prefect server instance</p>
+        <p>Start a Prefect server instance</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13900,7 +13901,7 @@ <h2 id="prefect.cli.server.stop" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Stop a Prefect server instance running in the background</p>
+        <p>Stop a Prefect server instance running in the background</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
@@ -13960,7 +13961,7 @@ <h2 id="prefect.cli.server.upgrade" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Upgrade the Prefect database</p>
+        <p>Upgrade the Prefect database</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/server.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/shell/index.html b/versions/unreleased/api-ref/prefect/cli/shell/index.html
index bcc0398606..0ff53da9ca 100644
--- a/versions/unreleased/api-ref/prefect/cli/shell/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/shell/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.cli.shell" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Provides a set of tools for executing shell commands as Prefect flows.
+        <p>Provides a set of tools for executing shell commands as Prefect flows.
 Includes functionalities for running shell commands ad-hoc or serving them as Prefect flows,
 with options for logging output, scheduling, and deployment customization.</p>
 
@@ -13332,7 +13333,7 @@ <h2 id="prefect.cli.shell.output_collect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Collects output from a subprocess pipe and stores it in a container list.</p>
+        <p>Collects output from a subprocess pipe and stores it in a container list.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13413,7 +13414,7 @@ <h2 id="prefect.cli.shell.output_stream" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read from a pipe line by line and log using the provided logging function.</p>
+        <p>Read from a pipe line by line and log using the provided logging function.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13498,7 +13499,7 @@ <h2 id="prefect.cli.shell.run_shell_process" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Asynchronously executes the specified shell command and logs its output.</p>
+        <p>Asynchronously executes the specified shell command and logs its output.</p>
 <p>This function is designed to be used within Prefect flows to run shell commands as part of task execution.
 It handles both the execution of the command and the collection of its output for logging purposes.</p>
 
@@ -13734,7 +13735,7 @@ <h2 id="prefect.cli.shell.serve" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.</p>
+        <p>Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.</p>
 <p>This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for
 scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for
 easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs,
@@ -14057,7 +14058,7 @@ <h2 id="prefect.cli.shell.watch" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a shell command and observes it as Prefect flow.</p>
+        <p>Executes a shell command and observes it as Prefect flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/cli/variable/index.html b/versions/unreleased/api-ref/prefect/cli/variable/index.html
index bec0255d07..ae115891dd 100644
--- a/versions/unreleased/api-ref/prefect/cli/variable/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/variable/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h2 id="prefect.cli.variable.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a variable.</p>
+        <p>Delete a variable.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13381,7 +13382,7 @@ <h2 id="prefect.cli.variable.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View details about a variable.</p>
+        <p>View details about a variable.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13472,7 +13473,7 @@ <h2 id="prefect.cli.variable.list_variables" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List variables.</p>
+        <p>List variables.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/variable.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/work_pool/index.html b/versions/unreleased/api-ref/prefect/cli/work_pool/index.html
index 1870161685..0c77ec09e5 100644
--- a/versions/unreleased/api-ref/prefect/cli/work_pool/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/work_pool/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13481,7 +13482,7 @@ <h1 id="prefect.cli.work_pool" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with work queues.</p>
+        <p>Command line interface for working with work queues.</p>
 
 
 
@@ -13510,7 +13511,7 @@ <h2 id="prefect.cli.work_pool.clear_concurrency_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clear the concurrency limit for a work pool.</p>
+        <p>Clear the concurrency limit for a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool clear-concurrency-limit "my-pool"</p>
@@ -13585,7 +13586,7 @@ <h2 id="prefect.cli.work_pool.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new work pool or update an existing one.</p>
+        <p>Create a new work pool or update an existing one.</p>
 <p>
 Examples:
     
@@ -13999,7 +14000,7 @@ <h2 id="prefect.cli.work_pool.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a work pool.</p>
+        <p>Delete a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool delete "my-pool"</p>
@@ -14064,7 +14065,7 @@ <h2 id="prefect.cli.work_pool.get_default_base_job_template" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get the default base job template for a given work pool type.</p>
+        <p>Get the default base job template for a given work pool type.</p>
 <p>
 Examples:
     $ prefect work-pool get-default-base-job-template --type kubernetes</p>
@@ -14155,7 +14156,7 @@ <h2 id="prefect.cli.work_pool.has_provisioner_for_type" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Check if there is a provisioner for the given work pool type.</p>
+        <p>Check if there is a provisioner for the given work pool type.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14253,7 +14254,7 @@ <h2 id="prefect.cli.work_pool.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Inspect a work pool.</p>
+        <p>Inspect a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool inspect "my-pool"</p>
@@ -14316,7 +14317,7 @@ <h2 id="prefect.cli.work_pool.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List work pools.</p>
+        <p>List work pools.</p>
 <p>
 Examples:
     $ prefect work-pool ls</p>
@@ -14439,7 +14440,7 @@ <h2 id="prefect.cli.work_pool.pause" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pause a work pool.</p>
+        <p>Pause a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool pause "my-pool"</p>
@@ -14514,7 +14515,7 @@ <h2 id="prefect.cli.work_pool.preview" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Preview the work pool's scheduled work for all queues.</p>
+        <p>Preview the work pool's scheduled work for all queues.</p>
 <p>
 Examples:
     $ prefect work-pool preview "my-pool" --hours 24</p>
@@ -14677,7 +14678,7 @@ <h2 id="prefect.cli.work_pool.provision_infrastructure" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Provision infrastructure for a work pool.</p>
+        <p>Provision infrastructure for a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool provision-infrastructure "my-pool"</p>
@@ -14822,7 +14823,7 @@ <h2 id="prefect.cli.work_pool.resume" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resume a work pool.</p>
+        <p>Resume a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool resume "my-pool"</p>
@@ -14897,7 +14898,7 @@ <h2 id="prefect.cli.work_pool.set_concurrency_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set the concurrency limit for a work pool.</p>
+        <p>Set the concurrency limit for a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool set-concurrency-limit "my-pool" 10</p>
@@ -14982,7 +14983,7 @@ <h2 id="prefect.cli.work_pool.update" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Update a work pool.</p>
+        <p>Update a work pool.</p>
 <p>
 Examples:
     $ prefect work-pool update "my-pool"</p>
diff --git a/versions/unreleased/api-ref/prefect/cli/work_queue/index.html b/versions/unreleased/api-ref/prefect/cli/work_queue/index.html
index 41a2e7e4b1..4ba3058b6f 100644
--- a/versions/unreleased/api-ref/prefect/cli/work_queue/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/work_queue/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13415,7 +13416,7 @@ <h1 id="prefect.cli.work_queue" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Command line interface for working with work queues.</p>
+        <p>Command line interface for working with work queues.</p>
 
 
 
@@ -13444,7 +13445,7 @@ <h2 id="prefect.cli.work_queue.clear_concurrency_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clear any concurrency limits from a work queue.</p>
+        <p>Clear any concurrency limits from a work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -13544,7 +13545,7 @@ <h2 id="prefect.cli.work_queue.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a work queue.</p>
+        <p>Create a work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -13764,7 +13765,7 @@ <h2 id="prefect.cli.work_queue.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a work queue by ID.</p>
+        <p>Delete a work queue by ID.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -13858,7 +13859,7 @@ <h2 id="prefect.cli.work_queue.inspect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Inspect a work queue by ID.</p>
+        <p>Inspect a work queue by ID.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -13954,7 +13955,7 @@ <h2 id="prefect.cli.work_queue.ls" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View all work queues.</p>
+        <p>View all work queues.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -14252,7 +14253,7 @@ <h2 id="prefect.cli.work_queue.pause" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pause a work queue.</p>
+        <p>Pause a work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -14362,7 +14363,7 @@ <h2 id="prefect.cli.work_queue.preview" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Preview a work queue.</p>
+        <p>Preview a work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -14558,7 +14559,7 @@ <h2 id="prefect.cli.work_queue.read_wq_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get runs in a work queue. Note that this will trigger an artificial poll of
+        <p>Get runs in a work queue. Note that this will trigger an artificial poll of
 the work queue.</p>
 
             <details class="quote">
@@ -14649,7 +14650,7 @@ <h2 id="prefect.cli.work_queue.resume" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resume a paused work queue.</p>
+        <p>Resume a paused work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
@@ -14747,7 +14748,7 @@ <h2 id="prefect.cli.work_queue.set_concurrency_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set a concurrency limit on a work queue.</p>
+        <p>Set a concurrency limit on a work queue.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/work_queue.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/cli/worker/index.html b/versions/unreleased/api-ref/prefect/cli/worker/index.html
index 276566d7fd..4970900809 100644
--- a/versions/unreleased/api-ref/prefect/cli/worker/index.html
+++ b/versions/unreleased/api-ref/prefect/cli/worker/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13244,7 +13245,7 @@ <h2 id="prefect.cli.worker.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Start a worker process to poll a work pool for flow runs.</p>
+        <p>Start a worker process to poll a work pool for flow runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/cli/worker.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/client/base/index.html b/versions/unreleased/api-ref/prefect/client/base/index.html
index c428894e48..0fcfdc487c 100644
--- a/versions/unreleased/api-ref/prefect/client/base/index.html
+++ b/versions/unreleased/api-ref/prefect/client/base/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13456,7 +13457,7 @@ <h2 id="prefect.client.base.PrefectResponse" class="doc doc-heading">
               Bases: <code><span title="httpx.Response">Response</span></code></p>
 
 
-      <p>A Prefect wrapper for the <code>httpx.Response</code> class.</p>
+        <p>A Prefect wrapper for the <code>httpx.Response</code> class.</p>
 <p>Provides more informative error messages.</p>
 
               <details class="quote">
@@ -13548,7 +13549,7 @@ <h3 id="prefect.client.base.PrefectResponse.raise_for_status" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Raise an exception if the response contains an HTTPStatusError.</p>
+        <p>Raise an exception if the response contains an HTTPStatusError.</p>
 <p>The <code>PrefectHTTPStatusError</code> contains useful additional information that
 is not contained in the <code>HTTPStatusError</code>.</p>
 
@@ -13596,7 +13597,7 @@ <h3 id="prefect.client.base.PrefectResponse.from_httpx_response" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Create a <code>PrefectReponse</code> from an <code>httpx.Response</code>.</p>
+        <p>Create a <code>PrefectReponse</code> from an <code>httpx.Response</code>.</p>
 <p>By changing the <code>__class__</code> attribute of the Response, we change the method
 resolution order to look for methods defined in PrefectResponse, while leaving
 everything else about the original Response instance intact.</p>
@@ -13656,7 +13657,7 @@ <h2 id="prefect.client.base.PrefectHttpxAsyncClient" class="doc doc-heading">
               Bases: <code><span title="httpx.AsyncClient">AsyncClient</span></code></p>
 
 
-      <p>A Prefect wrapper for the async httpx client with support for retry-after headers
+        <p>A Prefect wrapper for the async httpx client with support for retry-after headers
 for the provided status codes (typically 429, 502 and 503).</p>
 <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p>
 <p>For more details on rate limit headers, see:
@@ -14117,7 +14118,7 @@ <h3 id="prefect.client.base.PrefectHttpxAsyncClient.send" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Send a request with automatic retry behavior for the following status codes:</p>
+        <p>Send a request with automatic retry behavior for the following status codes:</p>
 <ul>
 <li>403 Forbidden, if the request failed due to CSRF protection</li>
 <li>408 Request Timeout</li>
@@ -14252,7 +14253,7 @@ <h2 id="prefect.client.base.PrefectHttpxSyncClient" class="doc doc-heading">
               Bases: <code><span title="httpx.Client">Client</span></code></p>
 
 
-      <p>A Prefect wrapper for the async httpx client with support for retry-after headers
+        <p>A Prefect wrapper for the async httpx client with support for retry-after headers
 for the provided status codes (typically 429, 502 and 503).</p>
 <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p>
 <p>For more details on rate limit headers, see:
@@ -14709,7 +14710,7 @@ <h3 id="prefect.client.base.PrefectHttpxSyncClient.send" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Send a request with automatic retry behavior for the following status codes:</p>
+        <p>Send a request with automatic retry behavior for the following status codes:</p>
 <ul>
 <li>403 Forbidden, if the request failed due to CSRF protection</li>
 <li>408 Request Timeout</li>
@@ -14844,7 +14845,7 @@ <h2 id="prefect.client.base.PrefectHttpxSyncEphemeralClient" class="doc doc-head
               Bases: <code><span title="prefect._vendor.starlette.testclient.TestClient">TestClient</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.base.PrefectHttpxSyncClient" href="#prefect.client.base.PrefectHttpxSyncClient">PrefectHttpxSyncClient</a></code></p>
 
 
-      <p>This client is a synchronous httpx client that can be used to talk directly
+        <p>This client is a synchronous httpx client that can be used to talk directly
 to an ASGI app, such as an ephemeral Prefect API.</p>
 <p>It is a subclass of both Starlette's <code>TestClient</code> and Prefect's
 <code>PrefectHttpxSyncClient</code>, so it combines the synchronous testing
@@ -14941,7 +14942,7 @@ <h2 id="prefect.client.base.app_lifespan_context" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A context manager that calls startup/shutdown hooks for the given application.</p>
+        <p>A context manager that calls startup/shutdown hooks for the given application.</p>
 <p>Lifespan contexts are cached per application to avoid calling the lifespan hooks
 more than once if the context is entered in nested code. A no-op context will be
 returned if the context for the given application is already being managed.</p>
diff --git a/versions/unreleased/api-ref/prefect/client/cloud/index.html b/versions/unreleased/api-ref/prefect/client/cloud/index.html
index b704dbb17f..ed325b66eb 100644
--- a/versions/unreleased/api-ref/prefect/client/cloud/index.html
+++ b/versions/unreleased/api-ref/prefect/client/cloud/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13322,7 +13323,7 @@ <h2 id="prefect.client.cloud.CloudUnauthorizedError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="../../exceptions/#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the CloudClient receives a 401 or 403 from the Cloud API.</p>
+        <p>Raised when the CloudClient receives a 401 or 403 from the Cloud API.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/cloud.py</code></summary>
@@ -13539,7 +13540,7 @@ <h3 id="prefect.client.cloud.CloudClient.api_healthcheck" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Attempts to connect to the Cloud API and raises the encountered exception if not
+        <p>Attempts to connect to the Cloud API and raises the encountered exception if not
 successful.</p>
 <p>If successful, returns <code>None</code>.</p>
 
@@ -13588,7 +13589,7 @@ <h2 id="prefect.client.cloud.get_cloud_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Needs a docstring.</p>
+        <p>Needs a docstring.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/cloud.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/client/orchestration/index.html b/versions/unreleased/api-ref/prefect/client/orchestration/index.html
index a195d0d505..5e540b6189 100644
--- a/versions/unreleased/api-ref/prefect/client/orchestration/index.html
+++ b/versions/unreleased/api-ref/prefect/client/orchestration/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -15679,7 +15680,7 @@ <h2 id="prefect.client.orchestration.PrefectClient" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>An asynchronous client for interacting with the <a href="/api-ref/rest-api/">Prefect REST API</a>.</p>
+        <p>An asynchronous client for interacting with the <a href="/api-ref/rest-api/">Prefect REST API</a>.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15752,7 +15753,7 @@ <h2 id="prefect.client.orchestration.PrefectClient" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code>Say<span class="w"> </span>hello<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>Prefect<span class="w"> </span>REST<span class="w"> </span>API
+        <div class="codehilite"><pre><span></span><code>Say<span class="w"> </span>hello<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>Prefect<span class="w"> </span>REST<span class="w"> </span>API
 
 <span class="nt">&lt;div</span><span class="w"> </span><span class="na">class=</span><span class="s">&quot;terminal&quot;</span><span class="nt">&gt;</span>
 ```
@@ -22115,7 +22116,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.api_url" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Get the base URL for the API.</p>
+        <p>Get the base URL for the API.</p>
     </div>
 
 </div>
@@ -22137,7 +22138,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.api_healthcheck" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Attempts to connect to the API and returns the encountered exception if not
+        <p>Attempts to connect to the API and returns the encountered exception if not
 successful.</p>
 <p>If successful, returns <code>None</code>.</p>
 
@@ -22187,7 +22188,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.hello" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Send a GET request to /hello for testing purposes.</p>
+        <p>Send a GET request to /hello for testing purposes.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -22221,7 +22222,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow in the Prefect API.</p>
+        <p>Create a flow in the Prefect API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22348,7 +22349,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow_from_name" class=
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow in the Prefect API.</p>
+        <p>Create a flow in the Prefect API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22495,7 +22496,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a flow by id.</p>
+        <p>Query the Prefect API for a flow by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22595,7 +22596,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flows" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for flows. Only flows matching all criteria will
+        <p>Query the Prefect API for flows. Only flows matching all criteria will
 be returned.</p>
 
 
@@ -22910,7 +22911,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_by_name" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a flow by name.</p>
+        <p>Query the Prefect API for a flow by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23016,7 +23017,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow_run_from_deployme
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run for a deployment.</p>
+        <p>Create a flow run for a deployment.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23388,7 +23389,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run for a flow.</p>
+        <p>Create a flow run for a flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23699,7 +23700,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_flow_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Update a flow run's details.</p>
+        <p>Update a flow run's details.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23967,7 +23968,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_flow_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run by UUID.</p>
+        <p>Delete a flow run by UUID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23997,7 +23998,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_flow_run" class="doc d
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -24061,7 +24062,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_concurrency_limit" cla
 
     <div class="doc doc-contents ">
 
-      <p>Create a tag concurrency limit in the Prefect API. These limits govern concurrently
+        <p>Create a tag concurrency limit in the Prefect API. These limits govern concurrently
 running tasks.</p>
 
 
@@ -24245,7 +24246,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_concurrency_limit_by_tag
 
     <div class="doc doc-contents ">
 
-      <p>Read the concurrency limit set on a specific tag.</p>
+        <p>Read the concurrency limit set on a specific tag.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24421,7 +24422,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_concurrency_limits" clas
 
     <div class="doc doc-contents ">
 
-      <p>Lists concurrency limits set on task run tags.</p>
+        <p>Lists concurrency limits set on task run tags.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24556,7 +24557,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.reset_concurrency_limit_by_ta
 
     <div class="doc doc-contents ">
 
-      <p>Resets the concurrency limit slots set on a specific tag.</p>
+        <p>Resets the concurrency limit slots set on a specific tag.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24725,7 +24726,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_concurrency_limit_by_t
 
     <div class="doc doc-contents ">
 
-      <p>Delete the concurrency limit set on a specific tag.</p>
+        <p>Delete the concurrency limit set on a specific tag.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24859,7 +24860,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_work_queue" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a work queue.</p>
+        <p>Create a work queue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25186,7 +25187,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_queue_by_name" clas
 
     <div class="doc doc-contents ">
 
-      <p>Read a work queue by name.</p>
+        <p>Read a work queue by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25378,7 +25379,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_work_queue" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Update properties of a work queue.</p>
+        <p>Update properties of a work queue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25537,7 +25538,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.get_runs_in_work_queue" class
 
     <div class="doc doc-contents ">
 
-      <p>Read flow runs off a work queue.</p>
+        <p>Read flow runs off a work queue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25753,7 +25754,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_queue" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Read a work queue.</p>
+        <p>Read a work queue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25912,7 +25913,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_queue_status" class
 
     <div class="doc doc-contents ">
 
-      <p>Read a work queue status.</p>
+        <p>Read a work queue status.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26071,7 +26072,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.match_work_queues" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for work queues with names with a specific prefix.</p>
+        <p>Query the Prefect API for work queues with names with a specific prefix.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26232,7 +26233,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_work_queue_by_id" clas
 
     <div class="doc doc-contents ">
 
-      <p>Delete a work queue by its ID.</p>
+        <p>Delete a work queue by its ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26364,7 +26365,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_block_type" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a block type in the Prefect API.</p>
+        <p>Create a block type in the Prefect API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26422,7 +26423,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_block_schema" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a block schema in the Prefect API.</p>
+        <p>Create a block schema in the Prefect API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26484,7 +26485,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_block_document" class=
 
     <div class="doc doc-contents ">
 
-      <p>Create a block document in the Prefect API. This data is used to configure a
+        <p>Create a block document in the Prefect API. This data is used to configure a
 corresponding Block.</p>
 
 
@@ -26623,7 +26624,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_block_document" class=
 
     <div class="doc doc-contents ">
 
-      <p>Update a block document in the Prefect API.</p>
+        <p>Update a block document in the Prefect API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26693,7 +26694,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_block_document" class=
 
     <div class="doc doc-contents ">
 
-      <p>Delete a block document.</p>
+        <p>Delete a block document.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26739,7 +26740,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_type_by_slug" clas
 
     <div class="doc doc-contents ">
 
-      <p>Read a block type by its slug.</p>
+        <p>Read a block type by its slug.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26787,7 +26788,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_schema_by_checksum
 
     <div class="doc doc-contents ">
 
-      <p>Look up a block schema checksum</p>
+        <p>Look up a block schema checksum</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26845,7 +26846,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_block_type" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Update a block document in the Prefect API.</p>
+        <p>Update a block document in the Prefect API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26907,7 +26908,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_block_type" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete a block type.</p>
+        <p>Delete a block type.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -26969,7 +26970,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_types" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Read all block types
+        <p>Read all block types
 Raises:
     httpx.RequestError: if the block types were not found</p>
 
@@ -27040,7 +27041,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_schemas" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Read all block schemas
+        <p>Read all block schemas
 Raises:
     httpx.RequestError: if a valid block schema was not found</p>
 
@@ -27111,7 +27112,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.get_most_recent_block_schema_
 
     <div class="doc doc-contents ">
 
-      <p>Fetches the most recent block schema for a specified block type ID.</p>
+        <p>Fetches the most recent block schema for a specified block type ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27264,7 +27265,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_document" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Read the block document with the specified ID.</p>
+        <p>Read the block document with the specified ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27455,7 +27456,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_document_by_name"
 
     <div class="doc doc-contents ">
 
-      <p>Read the block document with the specified name that corresponds to a
+        <p>Read the block document with the specified name that corresponds to a
 specific block type name.</p>
 
 
@@ -27662,7 +27663,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_documents" class="
 
     <div class="doc doc-contents ">
 
-      <p>Read block documents</p>
+        <p>Read block documents</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27852,7 +27853,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_block_documents_by_type"
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve block documents by block type slug.</p>
+        <p>Retrieve block documents by block type slug.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28026,7 +28027,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_deployment" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a deployment.</p>
+        <p>Create a deployment.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28440,7 +28441,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_deployment" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a deployment by id.</p>
+        <p>Query the Prefect API for a deployment by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28558,7 +28559,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_deployment_by_name" clas
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a deployment by name.</p>
+        <p>Query the Prefect API for a deployment by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28719,7 +28720,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_deployments" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for deployments. Only deployments matching all
+        <p>Query the Prefect API for deployments. Only deployments matching all
 the provided criteria will be returned.</p>
 
 
@@ -29021,7 +29022,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_deployment" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete deployment by id.</p>
+        <p>Delete deployment by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29051,7 +29052,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_deployment" class="doc
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -29115,7 +29116,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_deployment_schedules"
 
     <div class="doc doc-contents ">
 
-      <p>Create deployment schedules.</p>
+        <p>Create deployment schedules.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29293,7 +29294,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_deployment_schedules" cl
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a deployment's schedules.</p>
+        <p>Query the Prefect API for a deployment's schedules.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29411,7 +29412,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_deployment_schedule" c
 
     <div class="doc doc-contents ">
 
-      <p>Update a deployment schedule by ID.</p>
+        <p>Update a deployment schedule by ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29574,7 +29575,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_deployment_schedule" c
 
     <div class="doc doc-contents ">
 
-      <p>Delete a deployment schedule.</p>
+        <p>Delete a deployment schedule.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29712,7 +29713,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_run" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a flow run by id.</p>
+        <p>Query the Prefect API for a flow run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29824,7 +29825,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.resume_flow_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Resumes a paused flow run.</p>
+        <p>Resumes a paused flow run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29956,7 +29957,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_runs" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for flow runs. Only flow runs matching all criteria will
+        <p>Query the Prefect API for flow runs. Only flow runs matching all criteria will
 be returned.</p>
 
 
@@ -30274,7 +30275,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.set_flow_run_state" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Set the state of a flow run.</p>
+        <p>Set the state of a flow run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30445,7 +30446,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_run_states" class="
 
     <div class="doc doc-contents ">
 
-      <p>Query for the states of a flow run</p>
+        <p>Query for the states of a flow run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30556,7 +30557,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_task_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run</p>
+        <p>Create a task run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30844,7 +30845,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_task_run" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a task run by id.</p>
+        <p>Query the Prefect API for a task run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30944,7 +30945,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_task_runs" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for task runs. Only task runs matching all criteria will
+        <p>Query the Prefect API for task runs. Only task runs matching all criteria will
 be returned.</p>
 
 
@@ -31204,7 +31205,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_task_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Delete a task run by id.</p>
+        <p>Delete a task run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31234,7 +31235,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_task_run" class="doc d
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -31292,7 +31293,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.set_task_run_state" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Set the state of a task run.</p>
+        <p>Set the state of a task run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31447,7 +31448,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_task_run_states" class="
 
     <div class="doc doc-contents ">
 
-      <p>Query for the states of a task run</p>
+        <p>Query for the states of a task run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31555,7 +31556,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_logs" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Create logs for a flow or task run</p>
+        <p>Create logs for a flow or task run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31632,7 +31633,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow_run_notification_
 
     <div class="doc doc-contents ">
 
-      <p>Create a notification policy for flow runs</p>
+        <p>Create a notification policy for flow runs</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31821,7 +31822,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_flow_run_notification_
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run notification policy by id.</p>
+        <p>Delete a flow run notification policy by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31851,7 +31852,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_flow_run_notification_
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -31915,7 +31916,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_flow_run_notification_
 
     <div class="doc doc-contents ">
 
-      <p>Update a notification policy for flow runs</p>
+        <p>Update a notification policy for flow runs</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -32015,7 +32016,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_flow_run_notification_
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -32133,7 +32134,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_run_notification_po
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for flow run notification policies. Only policies matching all criteria will
+        <p>Query the Prefect API for flow run notification policies. Only policies matching all criteria will
 be returned.</p>
 
 
@@ -32303,7 +32304,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_logs" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Read flow and task run logs.</p>
+        <p>Read flow and task run logs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -32365,7 +32366,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.resolve_datadoc" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Recursively decode possibly nested data documents.</p>
+        <p>Recursively decode possibly nested data documents.</p>
 <p>"server" encoded documents will be retrieved from the server.</p>
 
 
@@ -32502,7 +32503,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.send_worker_heartbeat" class=
 
     <div class="doc doc-contents ">
 
-      <p>Sends a worker heartbeat for a given work pool.</p>
+        <p>Sends a worker heartbeat for a given work pool.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -32609,7 +32610,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_workers_for_work_pool" c
 
     <div class="doc doc-contents ">
 
-      <p>Reads workers for a given work pool.</p>
+        <p>Reads workers for a given work pool.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -32767,7 +32768,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_pool" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Reads information for a given work pool</p>
+        <p>Reads information for a given work pool</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -32882,7 +32883,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_pools" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Reads work pools.</p>
+        <p>Reads work pools.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33044,7 +33045,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_work_pool" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Creates a work pool with the provided configuration.</p>
+        <p>Creates a work pool with the provided configuration.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33222,7 +33223,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_work_pool" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Updates a work pool.</p>
+        <p>Updates a work pool.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33333,7 +33334,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_work_pool" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a work pool.</p>
+        <p>Deletes a work pool.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33420,7 +33421,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_work_queues" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves queues for a work pool.</p>
+        <p>Retrieves queues for a work pool.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33626,7 +33627,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.get_scheduled_flow_runs_for_w
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves scheduled flow runs for the provided set of work pool queues.</p>
+        <p>Retrieves scheduled flow runs for the provided set of work pool queues.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33807,7 +33808,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_artifact" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Creates an artifact with the provided configuration.</p>
+        <p>Creates an artifact with the provided configuration.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -33837,7 +33838,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_artifact" class="doc d
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -33899,7 +33900,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_artifacts" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for artifacts. Only artifacts matching all criteria will
+        <p>Query the Prefect API for artifacts. Only artifacts matching all criteria will
 be returned.
 Args:
     artifact_filter: filter criteria for artifacts
@@ -34011,7 +34012,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_latest_artifacts" class=
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for artifacts. Only artifacts matching all criteria will
+        <p>Query the Prefect API for artifacts. Only artifacts matching all criteria will
 be returned.
 Args:
     artifact_filter: filter criteria for artifacts
@@ -34123,7 +34124,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_artifact" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Deletes an artifact with the provided id.</p>
+        <p>Deletes an artifact with the provided id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34204,7 +34205,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_variable" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Creates an variable with the provided configuration.</p>
+        <p>Creates an variable with the provided configuration.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34234,7 +34235,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_variable" class="doc d
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34286,7 +34287,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_variable" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Updates a variable with the provided configuration.</p>
+        <p>Updates a variable with the provided configuration.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34316,7 +34317,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_variable" class="doc d
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34366,7 +34367,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_variable_by_name" class=
 
     <div class="doc doc-contents ">
 
-      <p>Reads a variable by name. Returns None if no variable is found.</p>
+        <p>Reads a variable by name. Returns None if no variable is found.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34410,7 +34411,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_variable_by_name" clas
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a variable by name.</p>
+        <p>Deletes a variable by name.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34452,7 +34453,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_variables" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Reads all variables.</p>
+        <p>Reads all variables.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34484,7 +34485,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_worker_metadata" class="
 
     <div class="doc doc-contents ">
 
-      <p>Reads worker metadata stored in Prefect collection registry.</p>
+        <p>Reads worker metadata stored in Prefect collection registry.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34518,7 +34519,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_flow_run_input" class=
 
     <div class="doc doc-contents ">
 
-      <p>Creates a flow run input.</p>
+        <p>Creates a flow run input.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34655,7 +34656,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_flow_run_input" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Reads a flow run input.</p>
+        <p>Reads a flow run input.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34744,7 +34745,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.delete_flow_run_input" class=
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a flow run input.</p>
+        <p>Deletes a flow run input.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -34831,7 +34832,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.create_automation" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Creates an automation in Prefect Cloud.</p>
+        <p>Creates an automation in Prefect Cloud.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34877,7 +34878,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.update_automation" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Updates an automation in Prefect Cloud.</p>
+        <p>Updates an automation in Prefect Cloud.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -34919,7 +34920,7 @@ <h3 id="prefect.client.orchestration.PrefectClient.read_automations_by_name" cla
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.</p>
+        <p>Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -35056,7 +35057,7 @@ <h2 id="prefect.client.orchestration.SyncPrefectClient" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>A synchronous client for interacting with the <a href="/api-ref/rest-api/">Prefect REST API</a>.</p>
+        <p>A synchronous client for interacting with the <a href="/api-ref/rest-api/">Prefect REST API</a>.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -35129,7 +35130,7 @@ <h2 id="prefect.client.orchestration.SyncPrefectClient" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code>Say<span class="w"> </span>hello<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>Prefect<span class="w"> </span>REST<span class="w"> </span>API
+        <div class="codehilite"><pre><span></span><code>Say<span class="w"> </span>hello<span class="w"> </span>to<span class="w"> </span>a<span class="w"> </span>Prefect<span class="w"> </span>REST<span class="w"> </span>API
 
 <span class="nt">&lt;div</span><span class="w"> </span><span class="na">class=</span><span class="s">&quot;terminal&quot;</span><span class="nt">&gt;</span>
 ```
@@ -36388,7 +36389,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.api_url" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Get the base URL for the API.</p>
+        <p>Get the base URL for the API.</p>
     </div>
 
 </div>
@@ -36406,7 +36407,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.api_healthcheck" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Attempts to connect to the API and returns the encountered exception if not
+        <p>Attempts to connect to the API and returns the encountered exception if not
 successful.</p>
 <p>If successful, returns <code>None</code>.</p>
 
@@ -36452,7 +36453,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.hello" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Send a GET request to /hello for testing purposes.</p>
+        <p>Send a GET request to /hello for testing purposes.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/orchestration.py</code></summary>
@@ -36482,7 +36483,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.create_flow" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow in the Prefect API.</p>
+        <p>Create a flow in the Prefect API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -36605,7 +36606,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.create_flow_from_name" cl
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow in the Prefect API.</p>
+        <p>Create a flow in the Prefect API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -36748,7 +36749,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.create_flow_run" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run for a flow.</p>
+        <p>Create a flow run for a flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -37055,7 +37056,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.read_flow_run" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a flow run by id.</p>
+        <p>Query the Prefect API for a flow run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -37163,7 +37164,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.read_flow_runs" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for flow runs. Only flow runs matching all criteria will
+        <p>Query the Prefect API for flow runs. Only flow runs matching all criteria will
 be returned.</p>
 
 
@@ -37477,7 +37478,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.set_flow_run_state" class
 
     <div class="doc doc-contents ">
 
-      <p>Set the state of a flow run.</p>
+        <p>Set the state of a flow run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -37644,7 +37645,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.create_task_run" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run</p>
+        <p>Create a task run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -37928,7 +37929,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.read_task_run" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for a task run by id.</p>
+        <p>Query the Prefect API for a task run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -38024,7 +38025,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.read_task_runs" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Query the Prefect API for task runs. Only task runs matching all criteria will
+        <p>Query the Prefect API for task runs. Only task runs matching all criteria will
 be returned.</p>
 
 
@@ -38280,7 +38281,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.set_task_run_state" class
 
     <div class="doc doc-contents ">
 
-      <p>Set the state of a task run.</p>
+        <p>Set the state of a task run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -38431,7 +38432,7 @@ <h3 id="prefect.client.orchestration.SyncPrefectClient.read_task_run_states" cla
 
     <div class="doc doc-contents ">
 
-      <p>Query for the states of a task run</p>
+        <p>Query for the states of a task run</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -38540,7 +38541,7 @@ <h2 id="prefect.client.orchestration.get_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve a HTTP client for communicating with the Prefect REST API.</p>
+        <p>Retrieve a HTTP client for communicating with the Prefect REST API.</p>
 <p>The client must be context managed; for example:</p>
 <div class="highlight"><pre><span></span><code><span class="k">async</span> <span class="k">with</span> <span class="n">get_client</span><span class="p">()</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
     <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">hello</span><span class="p">()</span>
diff --git a/versions/unreleased/api-ref/prefect/client/schemas/index.html b/versions/unreleased/api-ref/prefect/client/schemas/index.html
index 3bf2909ce4..371c548721 100644
--- a/versions/unreleased/api-ref/prefect/client/schemas/index.html
+++ b/versions/unreleased/api-ref/prefect/client/schemas/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -17645,7 +17646,7 @@ <h2 id="prefect.client.schemas.actions.StateCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a new state.</p>
+        <p>Data used by the Prefect REST API to create a new state.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -17707,7 +17708,7 @@ <h2 id="prefect.client.schemas.actions.FlowCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow.</p>
+        <p>Data used by the Prefect REST API to create a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -17771,7 +17772,7 @@ <h2 id="prefect.client.schemas.actions.FlowUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow.</p>
+        <p>Data used by the Prefect REST API to update a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -17829,7 +17830,7 @@ <h2 id="prefect.client.schemas.actions.DeploymentCreate" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a deployment.</p>
+        <p>Data used by the Prefect REST API to create a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -17990,7 +17991,7 @@ <h3 id="prefect.client.schemas.actions.DeploymentCreate.check_valid_configuratio
 
     <div class="doc doc-contents ">
 
-      <p>Check that the combination of base_job_template defaults
+        <p>Check that the combination of base_job_template defaults
 and job_variables conforms to the specified schema.</p>
 
             <details class="quote">
@@ -18060,7 +18061,7 @@ <h2 id="prefect.client.schemas.actions.DeploymentUpdate" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a deployment.</p>
+        <p>Data used by the Prefect REST API to update a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18211,7 +18212,7 @@ <h3 id="prefect.client.schemas.actions.DeploymentUpdate.check_valid_configuratio
 
     <div class="doc doc-contents ">
 
-      <p>Check that the combination of base_job_template defaults
+        <p>Check that the combination of base_job_template defaults
 and job_variables conforms to the specified schema.</p>
 
             <details class="quote">
@@ -18283,7 +18284,7 @@ <h2 id="prefect.client.schemas.actions.FlowRunUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow run.</p>
+        <p>Data used by the Prefect REST API to update a flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18349,7 +18350,7 @@ <h2 id="prefect.client.schemas.actions.TaskRunCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a task run</p>
+        <p>Data used by the Prefect REST API to create a task run</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18471,7 +18472,7 @@ <h2 id="prefect.client.schemas.actions.TaskRunUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a task run</p>
+        <p>Data used by the Prefect REST API to update a task run</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18521,7 +18522,7 @@ <h2 id="prefect.client.schemas.actions.FlowRunCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run.</p>
+        <p>Data used by the Prefect REST API to create a flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18619,7 +18620,7 @@ <h2 id="prefect.client.schemas.actions.DeploymentFlowRunCreate" class="doc doc-h
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run from a deployment.</p>
+        <p>Data used by the Prefect REST API to create a flow run from a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18709,7 +18710,7 @@ <h2 id="prefect.client.schemas.actions.SavedSearchCreate" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a saved search.</p>
+        <p>Data used by the Prefect REST API to create a saved search.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18765,7 +18766,7 @@ <h2 id="prefect.client.schemas.actions.ConcurrencyLimitCreate" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a concurrency limit.</p>
+        <p>Data used by the Prefect REST API to create a concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18821,7 +18822,7 @@ <h2 id="prefect.client.schemas.actions.BlockTypeCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block type.</p>
+        <p>Data used by the Prefect REST API to create a block type.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18911,7 +18912,7 @@ <h2 id="prefect.client.schemas.actions.BlockTypeUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a block type.</p>
+        <p>Data used by the Prefect REST API to update a block type.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -18975,7 +18976,7 @@ <h2 id="prefect.client.schemas.actions.BlockSchemaCreate" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block schema.</p>
+        <p>Data used by the Prefect REST API to create a block schema.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19047,7 +19048,7 @@ <h2 id="prefect.client.schemas.actions.BlockDocumentCreate" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block document.</p>
+        <p>Data used by the Prefect REST API to create a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19149,7 +19150,7 @@ <h2 id="prefect.client.schemas.actions.BlockDocumentUpdate" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a block document.</p>
+        <p>Data used by the Prefect REST API to update a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19217,7 +19218,7 @@ <h2 id="prefect.client.schemas.actions.BlockDocumentReferenceCreate" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used to create block document reference.</p>
+        <p>Data used to create block document reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19285,7 +19286,7 @@ <h2 id="prefect.client.schemas.actions.LogCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a log.</p>
+        <p>Data used by the Prefect REST API to create a log.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19345,7 +19346,7 @@ <h2 id="prefect.client.schemas.actions.WorkPoolCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a work pool.</p>
+        <p>Data used by the Prefect REST API to create a work pool.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19429,7 +19430,7 @@ <h2 id="prefect.client.schemas.actions.WorkPoolUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a work pool.</p>
+        <p>Data used by the Prefect REST API to update a work pool.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19485,7 +19486,7 @@ <h2 id="prefect.client.schemas.actions.WorkQueueCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a work queue.</p>
+        <p>Data used by the Prefect REST API to create a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19581,7 +19582,7 @@ <h2 id="prefect.client.schemas.actions.WorkQueueUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a work queue.</p>
+        <p>Data used by the Prefect REST API to update a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19661,7 +19662,7 @@ <h2 id="prefect.client.schemas.actions.FlowRunNotificationPolicyCreate" class="d
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run notification policy.</p>
+        <p>Data used by the Prefect REST API to create a flow run notification policy.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19767,7 +19768,7 @@ <h2 id="prefect.client.schemas.actions.FlowRunNotificationPolicyUpdate" class="d
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow run notification policy.</p>
+        <p>Data used by the Prefect REST API to update a flow run notification policy.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19825,7 +19826,7 @@ <h2 id="prefect.client.schemas.actions.ArtifactCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create an artifact.</p>
+        <p>Data used by the Prefect REST API to create an artifact.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19895,7 +19896,7 @@ <h2 id="prefect.client.schemas.actions.ArtifactUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update an artifact.</p>
+        <p>Data used by the Prefect REST API to update an artifact.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -19949,7 +19950,7 @@ <h2 id="prefect.client.schemas.actions.VariableCreate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a Variable.</p>
+        <p>Data used by the Prefect REST API to create a Variable.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -20029,7 +20030,7 @@ <h2 id="prefect.client.schemas.actions.VariableUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a Variable.</p>
+        <p>Data used by the Prefect REST API to update a Variable.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -20109,7 +20110,7 @@ <h2 id="prefect.client.schemas.actions.GlobalConcurrencyLimitCreate" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a global concurrency limit.</p>
+        <p>Data used by the Prefect REST API to create a global concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -20209,7 +20210,7 @@ <h2 id="prefect.client.schemas.actions.GlobalConcurrencyLimitUpdate" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a global concurrency limit.</p>
+        <p>Data used by the Prefect REST API to update a global concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/actions.py</code></summary>
@@ -20281,7 +20282,7 @@ <h1 id="prefect.client.schemas.filters" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schemas that define Prefect REST API filtering operations.</p>
+        <p>Schemas that define Prefect REST API filtering operations.</p>
 
 
 
@@ -20310,7 +20311,7 @@ <h2 id="prefect.client.schemas.filters.Operator" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Operators for combining filter criteria.</p>
+        <p>Operators for combining filter criteria.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20360,7 +20361,7 @@ <h2 id="prefect.client.schemas.filters.OperatorMixin" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Base model for Prefect filters that combines criteria with a user-provided operator</p>
+        <p>Base model for Prefect filters that combines criteria with a user-provided operator</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20416,7 +20417,7 @@ <h2 id="prefect.client.schemas.filters.FlowFilterId" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Flow.id</code>.</p>
+        <p>Filter by <code>Flow.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20470,7 +20471,7 @@ <h2 id="prefect.client.schemas.filters.FlowFilterName" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Flow.name</code>.</p>
+        <p>Filter by <code>Flow.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20548,7 +20549,7 @@ <h2 id="prefect.client.schemas.filters.FlowFilterTags" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>Flow.tags</code>.</p>
+        <p>Filter by <code>Flow.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20618,7 +20619,7 @@ <h2 id="prefect.client.schemas.filters.FlowFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter for flows. Only flows matching all criteria will be returned.</p>
+        <p>Filter for flows. Only flows matching all criteria will be returned.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20684,7 +20685,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterId" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by FlowRun.id.</p>
+        <p>Filter by FlowRun.id.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20744,7 +20745,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterName" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.name</code>.</p>
+        <p>Filter by <code>FlowRun.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20822,7 +20823,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterTags" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.tags</code>.</p>
+        <p>Filter by <code>FlowRun.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20892,7 +20893,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterDeploymentId" class="doc doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.deployment_id</code>.</p>
+        <p>Filter by <code>FlowRun.deployment_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -20954,7 +20955,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterWorkQueueName" class="doc do
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.work_queue_name</code>.</p>
+        <p>Filter by <code>FlowRun.work_queue_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21020,7 +21021,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterStateType" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.state_type</code>.</p>
+        <p>Filter by <code>FlowRun.state_type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21074,7 +21075,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterFlowVersion" class="doc doc-
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.flow_version</code>.</p>
+        <p>Filter by <code>FlowRun.flow_version</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21128,7 +21129,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterStartTime" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.start_time</code>.</p>
+        <p>Filter by <code>FlowRun.start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21198,7 +21199,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterExpectedStartTime" class="do
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.expected_start_time</code>.</p>
+        <p>Filter by <code>FlowRun.expected_start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21262,7 +21263,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterNextScheduledStartTime" clas
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p>
+        <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21338,7 +21339,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterParentFlowRunId" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter for subflows of the given flow runs</p>
+        <p>Filter for subflows of the given flow runs</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21392,7 +21393,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterParentTaskRunId" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p>
+        <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21454,7 +21455,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilterIdempotencyKey" class="doc d
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by FlowRun.idempotency_key.</p>
+        <p>Filter by FlowRun.idempotency_key.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21514,7 +21515,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter flow runs. Only flow runs matching all criteria will be returned</p>
+        <p>Filter flow runs. Only flow runs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21642,7 +21643,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterFlowRunId" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.flow_run_id</code>.</p>
+        <p>Filter by <code>TaskRun.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21706,7 +21707,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterId" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.id</code>.</p>
+        <p>Filter by <code>TaskRun.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21760,7 +21761,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterName" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.name</code>.</p>
+        <p>Filter by <code>TaskRun.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21838,7 +21839,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterTags" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.tags</code>.</p>
+        <p>Filter by <code>TaskRun.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21908,7 +21909,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterStateType" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.state_type</code>.</p>
+        <p>Filter by <code>TaskRun.state_type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -21962,7 +21963,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterSubFlowRuns" class="doc doc-
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.subflow_run</code>.</p>
+        <p>Filter by <code>TaskRun.subflow_run</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22024,7 +22025,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilterStartTime" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>TaskRun.start_time</code>.</p>
+        <p>Filter by <code>TaskRun.start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22094,7 +22095,7 @@ <h2 id="prefect.client.schemas.filters.TaskRunFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter task runs. Only task runs matching all criteria will be returned</p>
+        <p>Filter task runs. Only task runs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22184,7 +22185,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilterId" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Deployment.id</code>.</p>
+        <p>Filter by <code>Deployment.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22238,7 +22239,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilterName" class="doc doc-head
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Deployment.name</code>.</p>
+        <p>Filter by <code>Deployment.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22316,7 +22317,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilterWorkQueueName" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Deployment.work_queue_name</code>.</p>
+        <p>Filter by <code>Deployment.work_queue_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22374,7 +22375,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilterIsScheduleActive" class="
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Deployment.is_schedule_active</code>.</p>
+        <p>Filter by <code>Deployment.is_schedule_active</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22430,7 +22431,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilterTags" class="doc doc-head
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>Deployment.tags</code>.</p>
+        <p>Filter by <code>Deployment.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22500,7 +22501,7 @@ <h2 id="prefect.client.schemas.filters.DeploymentFilter" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
+        <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22578,7 +22579,7 @@ <h2 id="prefect.client.schemas.filters.LogFilterName" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Log.name</code>.</p>
+        <p>Filter by <code>Log.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22636,7 +22637,7 @@ <h2 id="prefect.client.schemas.filters.LogFilterLevel" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Log.level</code>.</p>
+        <p>Filter by <code>Log.level</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22706,7 +22707,7 @@ <h2 id="prefect.client.schemas.filters.LogFilterTimestamp" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Log.timestamp</code>.</p>
+        <p>Filter by <code>Log.timestamp</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22770,7 +22771,7 @@ <h2 id="prefect.client.schemas.filters.LogFilterFlowRunId" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Log.flow_run_id</code>.</p>
+        <p>Filter by <code>Log.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22824,7 +22825,7 @@ <h2 id="prefect.client.schemas.filters.LogFilterTaskRunId" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Log.task_run_id</code>.</p>
+        <p>Filter by <code>Log.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22878,7 +22879,7 @@ <h2 id="prefect.client.schemas.filters.LogFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter logs. Only logs matching all criteria will be returned</p>
+        <p>Filter logs. Only logs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -22950,7 +22951,7 @@ <h2 id="prefect.client.schemas.filters.FilterSet" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A collection of filters for common objects</p>
+        <p>A collection of filters for common objects</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23024,7 +23025,7 @@ <h2 id="prefect.client.schemas.filters.BlockTypeFilterName" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockType.name</code></p>
+        <p>Filter by <code>BlockType.name</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23090,7 +23091,7 @@ <h2 id="prefect.client.schemas.filters.BlockTypeFilterSlug" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockType.slug</code></p>
+        <p>Filter by <code>BlockType.slug</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23144,7 +23145,7 @@ <h2 id="prefect.client.schemas.filters.BlockTypeFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter BlockTypes</p>
+        <p>Filter BlockTypes</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23206,7 +23207,7 @@ <h2 id="prefect.client.schemas.filters.BlockSchemaFilterBlockTypeId" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockSchema.block_type_id</code>.</p>
+        <p>Filter by <code>BlockSchema.block_type_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23260,7 +23261,7 @@ <h2 id="prefect.client.schemas.filters.BlockSchemaFilterId" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by BlockSchema.id</p>
+        <p>Filter by BlockSchema.id</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23314,7 +23315,7 @@ <h2 id="prefect.client.schemas.filters.BlockSchemaFilterCapabilities" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockSchema.capabilities</code></p>
+        <p>Filter by <code>BlockSchema.capabilities</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23378,7 +23379,7 @@ <h2 id="prefect.client.schemas.filters.BlockSchemaFilterVersion" class="doc doc-
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockSchema.capabilities</code></p>
+        <p>Filter by <code>BlockSchema.capabilities</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23436,7 +23437,7 @@ <h2 id="prefect.client.schemas.filters.BlockSchemaFilter" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter BlockSchemas</p>
+        <p>Filter BlockSchemas</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23508,7 +23509,7 @@ <h2 id="prefect.client.schemas.filters.BlockDocumentFilterIsAnonymous" class="do
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockDocument.is_anonymous</code>.</p>
+        <p>Filter by <code>BlockDocument.is_anonymous</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23568,7 +23569,7 @@ <h2 id="prefect.client.schemas.filters.BlockDocumentFilterBlockTypeId" class="do
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockDocument.block_type_id</code>.</p>
+        <p>Filter by <code>BlockDocument.block_type_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23622,7 +23623,7 @@ <h2 id="prefect.client.schemas.filters.BlockDocumentFilterId" class="doc doc-hea
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockDocument.id</code>.</p>
+        <p>Filter by <code>BlockDocument.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23676,7 +23677,7 @@ <h2 id="prefect.client.schemas.filters.BlockDocumentFilterName" class="doc doc-h
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>BlockDocument.name</code>.</p>
+        <p>Filter by <code>BlockDocument.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23746,7 +23747,7 @@ <h2 id="prefect.client.schemas.filters.BlockDocumentFilter" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p>
+        <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23828,7 +23829,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunNotificationPolicyFilterIsActive"
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p>
+        <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23888,7 +23889,7 @@ <h2 id="prefect.client.schemas.filters.FlowRunNotificationPolicyFilter" class="d
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter FlowRunNotificationPolicies.</p>
+        <p>Filter FlowRunNotificationPolicies.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -23944,7 +23945,7 @@ <h2 id="prefect.client.schemas.filters.WorkQueueFilterId" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>WorkQueue.id</code>.</p>
+        <p>Filter by <code>WorkQueue.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24000,7 +24001,7 @@ <h2 id="prefect.client.schemas.filters.WorkQueueFilterName" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>WorkQueue.name</code>.</p>
+        <p>Filter by <code>WorkQueue.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24078,7 +24079,7 @@ <h2 id="prefect.client.schemas.filters.WorkQueueFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter work queues. Only work queues matching all criteria will be
+        <p>Filter work queues. Only work queues matching all criteria will be
 returned</p>
 
               <details class="quote">
@@ -24143,7 +24144,7 @@ <h2 id="prefect.client.schemas.filters.WorkPoolFilterId" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>WorkPool.id</code>.</p>
+        <p>Filter by <code>WorkPool.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24197,7 +24198,7 @@ <h2 id="prefect.client.schemas.filters.WorkPoolFilterName" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>WorkPool.name</code>.</p>
+        <p>Filter by <code>WorkPool.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24251,7 +24252,7 @@ <h2 id="prefect.client.schemas.filters.WorkPoolFilterType" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>WorkPool.type</code>.</p>
+        <p>Filter by <code>WorkPool.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24305,7 +24306,7 @@ <h2 id="prefect.client.schemas.filters.WorkerFilterWorkPoolId" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Worker.worker_config_id</code>.</p>
+        <p>Filter by <code>Worker.worker_config_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24359,7 +24360,7 @@ <h2 id="prefect.client.schemas.filters.WorkerFilterLastHeartbeatTime" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
+        <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24431,7 +24432,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilterId" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Artifact.id</code>.</p>
+        <p>Filter by <code>Artifact.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24485,7 +24486,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilterKey" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Artifact.key</code>.</p>
+        <p>Filter by <code>Artifact.key</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24573,7 +24574,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilterFlowRunId" class="doc doc-h
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Artifact.flow_run_id</code>.</p>
+        <p>Filter by <code>Artifact.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24627,7 +24628,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilterTaskRunId" class="doc doc-h
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Artifact.task_run_id</code>.</p>
+        <p>Filter by <code>Artifact.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24681,7 +24682,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilterType" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Artifact.type</code>.</p>
+        <p>Filter by <code>Artifact.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24741,7 +24742,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter artifacts. Only artifacts matching all criteria will be returned</p>
+        <p>Filter artifacts. Only artifacts matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24819,7 +24820,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilterLatestId" class="
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.latest_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.latest_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24873,7 +24874,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilterKey" class="doc d
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.key</code>.</p>
+        <p>Filter by <code>ArtifactCollection.key</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -24963,7 +24964,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilterFlowRunId" class=
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25017,7 +25018,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilterTaskRunId" class=
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25071,7 +25072,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilterType" class="doc
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.type</code>.</p>
+        <p>Filter by <code>ArtifactCollection.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25131,7 +25132,7 @@ <h2 id="prefect.client.schemas.filters.ArtifactCollectionFilter" class="doc doc-
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p>
+        <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25209,7 +25210,7 @@ <h2 id="prefect.client.schemas.filters.VariableFilterId" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Variable.id</code>.</p>
+        <p>Filter by <code>Variable.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25263,7 +25264,7 @@ <h2 id="prefect.client.schemas.filters.VariableFilterName" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Variable.name</code>.</p>
+        <p>Filter by <code>Variable.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25333,7 +25334,7 @@ <h2 id="prefect.client.schemas.filters.VariableFilterValue" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter by <code>Variable.value</code>.</p>
+        <p>Filter by <code>Variable.value</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25403,7 +25404,7 @@ <h2 id="prefect.client.schemas.filters.VariableFilterTags" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter by <code>Variable.tags</code>.</p>
+        <p>Filter by <code>Variable.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25473,7 +25474,7 @@ <h2 id="prefect.client.schemas.filters.VariableFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.filters.OperatorMixin" href="#prefect.client.schemas.filters.OperatorMixin">OperatorMixin</a></code></p>
 
 
-      <p>Filter variables. Only variables matching all criteria will be returned</p>
+        <p>Filter variables. Only variables matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/filters.py</code></summary>
@@ -25578,7 +25579,7 @@ <h2 id="prefect.client.schemas.objects.StateType" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of state types.</p>
+        <p>Enumeration of state types.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -25644,7 +25645,7 @@ <h2 id="prefect.client.schemas.objects.WorkPoolStatus" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of work pool statuses.</p>
+        <p>Enumeration of work pool statuses.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -25706,7 +25707,7 @@ <h2 id="prefect.client.schemas.objects.WorkerStatus" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of worker statuses.</p>
+        <p>Enumeration of worker statuses.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -25758,7 +25759,7 @@ <h2 id="prefect.client.schemas.objects.DeploymentStatus" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of deployment statuses.</p>
+        <p>Enumeration of deployment statuses.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -25810,7 +25811,7 @@ <h2 id="prefect.client.schemas.objects.WorkQueueStatus" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of work queue statuses.</p>
+        <p>Enumeration of work queue statuses.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -25864,7 +25865,7 @@ <h2 id="prefect.client.schemas.objects.State" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code>, <code><span title="typing.Generic">Generic</span>[<span title="prefect.client.schemas.objects.R">R</span>]</code></p>
 
 
-      <p>The state of a run.</p>
+        <p>The state of a run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -26363,7 +26364,7 @@ <h3 id="prefect.client.schemas.objects.State.result" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the result attached to this state.</p>
+        <p>Retrieve the result attached to this state.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26677,7 +26678,7 @@ <h3 id="prefect.client.schemas.objects.State.to_state_create" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Convert this state to a <code>StateCreate</code> type which can be used to set the state of
+        <p>Convert this state to a <code>StateCreate</code> type which can be used to set the state of
 a run in the API.</p>
 <p>This method will drop this state's <code>data</code> if it is not a result type. Only
 results should be sent to the API. Other data is only available locally.</p>
@@ -26802,7 +26803,7 @@ <h2 id="prefect.client.schemas.objects.FlowRunPolicy" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines of how a flow run should be orchestrated.</p>
+        <p>Defines of how a flow run should be orchestrated.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27264,7 +27265,7 @@ <h2 id="prefect.client.schemas.objects.TaskRunPolicy" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines of how a task run should retry.</p>
+        <p>Defines of how a task run should retry.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27384,7 +27385,7 @@ <h2 id="prefect.client.schemas.objects.TaskRunInput" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Base class for classes that represent inputs to task runs, which
+        <p>Base class for classes that represent inputs to task runs, which
 could include, constants, parameters, or other task runs.</p>
 
               <details class="quote">
@@ -27449,7 +27450,7 @@ <h2 id="prefect.client.schemas.objects.TaskRunResult" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.objects.TaskRunInput" href="#prefect.client.schemas.objects.TaskRunInput">TaskRunInput</a></code></p>
 
 
-      <p>Represents a task run result input to another task run.</p>
+        <p>Represents a task run result input to another task run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27501,7 +27502,7 @@ <h2 id="prefect.client.schemas.objects.Parameter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.objects.TaskRunInput" href="#prefect.client.schemas.objects.TaskRunInput">TaskRunInput</a></code></p>
 
 
-      <p>Represents a parameter input to a task run.</p>
+        <p>Represents a parameter input to a task run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27553,7 +27554,7 @@ <h2 id="prefect.client.schemas.objects.Constant" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.objects.TaskRunInput" href="#prefect.client.schemas.objects.TaskRunInput">TaskRunInput</a></code></p>
 
 
-      <p>Represents constant input value to a task run.</p>
+        <p>Represents constant input value to a task run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27605,7 +27606,7 @@ <h2 id="prefect.client.schemas.objects.Workspace" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A Prefect Cloud workspace.</p>
+        <p>A Prefect Cloud workspace.</p>
 <p>Expected payload for each workspace returned by the <code>me/workspaces</code> route.</p>
 
               <details class="quote">
@@ -27732,7 +27733,7 @@ <h3 id="prefect.client.schemas.objects.Workspace.handle" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>The full handle of the workspace as <code>account_handle</code> / <code>workspace_handle</code></p>
+        <p>The full handle of the workspace as <code>account_handle</code> / <code>workspace_handle</code></p>
     </div>
 
 </div>
@@ -27750,7 +27751,7 @@ <h3 id="prefect.client.schemas.objects.Workspace.api_url" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Generate the API URL for accessing this workspace</p>
+        <p>Generate the API URL for accessing this workspace</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27788,7 +27789,7 @@ <h3 id="prefect.client.schemas.objects.Workspace.ui_url" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Generate the UI URL for accessing this workspace</p>
+        <p>Generate the UI URL for accessing this workspace</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27839,7 +27840,7 @@ <h2 id="prefect.client.schemas.objects.BlockType" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block type</p>
+        <p>An ORM representation of a block type</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -27933,7 +27934,7 @@ <h2 id="prefect.client.schemas.objects.BlockDocument" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block document.</p>
+        <p>An ORM representation of a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28057,7 +28058,7 @@ <h2 id="prefect.client.schemas.objects.Flow" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of flow data.</p>
+        <p>An ORM representation of flow data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28129,7 +28130,7 @@ <h2 id="prefect.client.schemas.objects.Deployment" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of deployment data.</p>
+        <p>An ORM representation of deployment data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28387,7 +28388,7 @@ <h2 id="prefect.client.schemas.objects.ConcurrencyLimit" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a concurrency limit.</p>
+        <p>An ORM representation of a concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28451,7 +28452,7 @@ <h2 id="prefect.client.schemas.objects.BlockSchema" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block schema.</p>
+        <p>An ORM representation of a block schema.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28531,7 +28532,7 @@ <h2 id="prefect.client.schemas.objects.BlockSchemaReference" class="doc doc-head
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block schema reference.</p>
+        <p>An ORM representation of a block schema reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28609,7 +28610,7 @@ <h2 id="prefect.client.schemas.objects.BlockDocumentReference" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block document reference.</p>
+        <p>An ORM representation of a block document reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28695,7 +28696,7 @@ <h2 id="prefect.client.schemas.objects.SavedSearchFilter" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A filter for a saved search model. Intended for use by the Prefect UI.</p>
+        <p>A filter for a saved search model. Intended for use by the Prefect UI.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28767,7 +28768,7 @@ <h2 id="prefect.client.schemas.objects.SavedSearch" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of saved search data. Represents a set of filter criteria.</p>
+        <p>An ORM representation of saved search data. Represents a set of filter criteria.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28823,7 +28824,7 @@ <h2 id="prefect.client.schemas.objects.Log" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of log data.</p>
+        <p>An ORM representation of log data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28891,7 +28892,7 @@ <h2 id="prefect.client.schemas.objects.QueueFilter" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter criteria definition for a work queue.</p>
+        <p>Filter criteria definition for a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -28955,7 +28956,7 @@ <h2 id="prefect.client.schemas.objects.WorkQueue" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a work queue</p>
+        <p>An ORM representation of a work queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29192,7 +29193,7 @@ <h3 id="prefect.client.schemas.objects.WorkQueueHealthPolicy.evaluate_health_sta
 
     <div class="doc doc-contents ">
 
-      <p>Given empirical information about the state of the work queue, evaluate its health status.</p>
+        <p>Given empirical information about the state of the work queue, evaluate its health status.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29348,7 +29349,7 @@ <h2 id="prefect.client.schemas.objects.FlowRunNotificationPolicy" class="doc doc
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a flow run notification.</p>
+        <p>An ORM representation of a flow run notification.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29454,7 +29455,7 @@ <h2 id="prefect.client.schemas.objects.Agent" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of an agent</p>
+        <p>An ORM representation of an agent</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29528,7 +29529,7 @@ <h2 id="prefect.client.schemas.objects.WorkPool" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a work pool</p>
+        <p>An ORM representation of a work pool</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29660,7 +29661,7 @@ <h2 id="prefect.client.schemas.objects.Worker" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a worker</p>
+        <p>An ORM representation of a worker</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29812,7 +29813,7 @@ <h3 id="prefect.client.schemas.objects.FlowRunInput.decoded_value" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Decode the value of the input.</p>
+        <p>Decode the value of the input.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -29866,7 +29867,7 @@ <h2 id="prefect.client.schemas.objects.GlobalConcurrencyLimit" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a global concurrency limit</p>
+        <p>An ORM representation of a global concurrency limit</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/objects.py</code></summary>
@@ -29991,7 +29992,7 @@ <h2 id="prefect.client.schemas.responses.SetStateStatus" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumerates return statuses for setting run states.</p>
+        <p>Enumerates return statuses for setting run states.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30047,7 +30048,7 @@ <h2 id="prefect.client.schemas.responses.StateAcceptDetails" class="doc doc-head
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with an ACCEPT state transition.</p>
+        <p>Details associated with an ACCEPT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30109,7 +30110,7 @@ <h2 id="prefect.client.schemas.responses.StateRejectDetails" class="doc doc-head
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with a REJECT state transition.</p>
+        <p>Details associated with a REJECT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30177,7 +30178,7 @@ <h2 id="prefect.client.schemas.responses.StateAbortDetails" class="doc doc-headi
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with an ABORT state transition.</p>
+        <p>Details associated with an ABORT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30245,7 +30246,7 @@ <h2 id="prefect.client.schemas.responses.StateWaitDetails" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with a WAIT state transition.</p>
+        <p>Details associated with a WAIT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30327,7 +30328,7 @@ <h2 id="prefect.client.schemas.responses.HistoryResponseState" class="doc doc-he
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Represents a single state's history over an interval.</p>
+        <p>Represents a single state's history over an interval.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30409,7 +30410,7 @@ <h2 id="prefect.client.schemas.responses.HistoryResponse" class="doc doc-heading
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Represents a history of aggregation states over an interval</p>
+        <p>Represents a history of aggregation states over an interval</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30475,7 +30476,7 @@ <h2 id="prefect.client.schemas.responses.OrchestrationResult" class="doc doc-hea
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A container for the output of state orchestration.</p>
+        <p>A container for the output of state orchestration.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30879,7 +30880,7 @@ <h2 id="prefect.client.schemas.responses.GlobalConcurrencyLimitResponse" class="
               Bases: <code><span title="prefect._internal.schemas.bases.ObjectBaseModel">ObjectBaseModel</span></code></p>
 
 
-      <p>A response object for global concurrency limits.</p>
+        <p>A response object for global concurrency limits.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/responses.py</code></summary>
@@ -30961,7 +30962,7 @@ <h1 id="prefect.client.schemas.schedules" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schedule schemas</p>
+        <p>Schedule schemas</p>
 
 
 
@@ -30990,7 +30991,7 @@ <h2 id="prefect.client.schemas.schedules.IntervalSchedule" class="doc doc-headin
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no
+        <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no
 <code>anchor_date</code> is supplied, the current UTC time is used.  If a
 timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be
 in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,
@@ -31195,7 +31196,7 @@ <h2 id="prefect.client.schemas.schedules.CronSchedule" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Cron schedule</p>
+        <p>Cron schedule</p>
 <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust
 itself appropriately. Cron's rules for DST are based on schedule times, not
 intervals. This means that an hourly cron schedule will fire on every new
@@ -31395,7 +31396,7 @@ <h2 id="prefect.client.schemas.schedules.RRuleSchedule" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>RRule schedule, based on the iCalendar standard
+        <p>RRule schedule, based on the iCalendar standard
 (<a href="https://datatracker.ietf.org/doc/html/rfc5545">RFC 5545</a>) as
 implemented in <code>dateutils.rrule</code>.</p>
 <p>RRules are appropriate for any kind of calendar-date manipulation, including
@@ -31748,7 +31749,7 @@ <h3 id="prefect.client.schemas.schedules.RRuleSchedule.to_rrule" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates
+        <p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates
 here</p>
 
             <details class="quote">
@@ -31886,7 +31887,7 @@ <h2 id="prefect.client.schemas.schedules.construct_schedule" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Construct a schedule from the provided arguments.</p>
+        <p>Construct a schedule from the provided arguments.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -32125,7 +32126,7 @@ <h2 id="prefect.client.schemas.sorting.FlowRunSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines flow run sorting options.</p>
+        <p>Defines flow run sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32191,7 +32192,7 @@ <h2 id="prefect.client.schemas.sorting.TaskRunSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines task run sorting options.</p>
+        <p>Defines task run sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32253,7 +32254,7 @@ <h2 id="prefect.client.schemas.sorting.AutomationSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines automation sorting options.</p>
+        <p>Defines automation sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32309,7 +32310,7 @@ <h2 id="prefect.client.schemas.sorting.LogSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines log sorting options.</p>
+        <p>Defines log sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32361,7 +32362,7 @@ <h2 id="prefect.client.schemas.sorting.FlowSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines flow sorting options.</p>
+        <p>Defines flow sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32417,7 +32418,7 @@ <h2 id="prefect.client.schemas.sorting.DeploymentSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines deployment sorting options.</p>
+        <p>Defines deployment sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32473,7 +32474,7 @@ <h2 id="prefect.client.schemas.sorting.ArtifactSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines artifact sorting options.</p>
+        <p>Defines artifact sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32531,7 +32532,7 @@ <h2 id="prefect.client.schemas.sorting.ArtifactCollectionSort" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines artifact collection sorting options.</p>
+        <p>Defines artifact collection sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32589,7 +32590,7 @@ <h2 id="prefect.client.schemas.sorting.VariableSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines variables sorting options.</p>
+        <p>Defines variables sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
@@ -32645,7 +32646,7 @@ <h2 id="prefect.client.schemas.sorting.BlockDocumentSort" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines block document sorting options.</p>
+        <p>Defines block document sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/client/schemas/sorting.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/client/utilities/index.html b/versions/unreleased/api-ref/prefect/client/utilities/index.html
index 4c3678b425..fb432d5aa8 100644
--- a/versions/unreleased/api-ref/prefect/client/utilities/index.html
+++ b/versions/unreleased/api-ref/prefect/client/utilities/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.client.utilities" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for working with clients.</p>
+        <p>Utilities for working with clients.</p>
 
 
 
@@ -13264,7 +13265,7 @@ <h2 id="prefect.client.utilities.get_or_create_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns provided client, infers a client from context if available, or creates a new client.</p>
+        <p>Returns provided client, infers a client from context if available, or creates a new client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13406,7 +13407,7 @@ <h2 id="prefect.client.utilities.inject_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Simple helper to provide a context managed client to a asynchronous function.</p>
+        <p>Simple helper to provide a context managed client to a asynchronous function.</p>
 <p>The decorated function <em>must</em> take a <code>client</code> kwarg and if a client is passed when
 called it will be used instead of creating a new one, but it will not be context
 managed as it is assumed that the caller is managing the context.</p>
diff --git a/versions/unreleased/api-ref/prefect/concurrency/asyncio/index.html b/versions/unreleased/api-ref/prefect/concurrency/asyncio/index.html
index 1b8fead84f..aa70218c8d 100644
--- a/versions/unreleased/api-ref/prefect/concurrency/asyncio/index.html
+++ b/versions/unreleased/api-ref/prefect/concurrency/asyncio/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13310,7 +13311,7 @@ <h2 id="prefect.concurrency.asyncio.AcquireConcurrencySlotTimeoutError" class="d
               Bases: <code>TimeoutError</code></p>
 
 
-      <p>Raised when acquiring a concurrency slot times out.</p>
+        <p>Raised when acquiring a concurrency slot times out.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/concurrency/asyncio.py</code></summary>
@@ -13340,7 +13341,7 @@ <h2 id="prefect.concurrency.asyncio.ConcurrencySlotAcquisitionError" class="doc
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when an unhandlable occurs while acquiring concurrency slots.</p>
+        <p>Raised when an unhandlable occurs while acquiring concurrency slots.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/concurrency/asyncio.py</code></summary>
@@ -13370,7 +13371,7 @@ <h2 id="prefect.concurrency.asyncio.concurrency" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A context manager that acquires and releases concurrency slots from the
+        <p>A context manager that acquires and releases concurrency slots from the
 given concurrency limits.</p>
 
 
@@ -13453,7 +13454,7 @@ <h2 id="prefect.concurrency.asyncio.concurrency" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <p>A simple example of using the async <code>concurrency</code> context manager:
+        <p>A simple example of using the async <code>concurrency</code> context manager:
 <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect.concurrency.asyncio</span> <span class="kn">import</span> <span class="n">concurrency</span>
 
 <span class="k">async</span> <span class="k">def</span> <span class="nf">resource_heavy</span><span class="p">():</span>
@@ -13578,7 +13579,7 @@ <h2 id="prefect.concurrency.asyncio.rate_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Block execution until an <code>occupy</code> number of slots of the concurrency
+        <p>Block execution until an <code>occupy</code> number of slots of the concurrency
 limits given in <code>names</code> are acquired. Requires that all given concurrency
 limits have a slot decay.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/concurrency/events/index.html b/versions/unreleased/api-ref/prefect/concurrency/events/index.html
index 6a478e22aa..f982879d1c 100644
--- a/versions/unreleased/api-ref/prefect/concurrency/events/index.html
+++ b/versions/unreleased/api-ref/prefect/concurrency/events/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/concurrency/services/index.html b/versions/unreleased/api-ref/prefect/concurrency/services/index.html
index 43042307c0..60c87e775a 100644
--- a/versions/unreleased/api-ref/prefect/concurrency/services/index.html
+++ b/versions/unreleased/api-ref/prefect/concurrency/services/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/concurrency/sync/index.html b/versions/unreleased/api-ref/prefect/concurrency/sync/index.html
index e04465b8ec..b150393234 100644
--- a/versions/unreleased/api-ref/prefect/concurrency/sync/index.html
+++ b/versions/unreleased/api-ref/prefect/concurrency/sync/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13262,7 +13263,7 @@ <h2 id="prefect.concurrency.sync.concurrency" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A context manager that acquires and releases concurrency slots from the
+        <p>A context manager that acquires and releases concurrency slots from the
 given concurrency limits.</p>
 
 
@@ -13345,7 +13346,7 @@ <h2 id="prefect.concurrency.sync.concurrency" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <p>A simple example of using the sync <code>concurrency</code> context manager:
+        <p>A simple example of using the sync <code>concurrency</code> context manager:
 <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect.concurrency.sync</span> <span class="kn">import</span> <span class="n">concurrency</span>
 
 <span class="k">def</span> <span class="nf">resource_heavy</span><span class="p">():</span>
@@ -13474,7 +13475,7 @@ <h2 id="prefect.concurrency.sync.rate_limit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Block execution until an <code>occupy</code> number of slots of the concurrency
+        <p>Block execution until an <code>occupy</code> number of slots of the concurrency
 limits given in <code>names</code> are acquired. Requires that all given concurrency
 limits have a slot decay.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/context/index.html b/versions/unreleased/api-ref/prefect/context/index.html
index 8d75dcc5a9..c62e970219 100644
--- a/versions/unreleased/api-ref/prefect/context/index.html
+++ b/versions/unreleased/api-ref/prefect/context/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13530,7 +13531,7 @@ <h1 id="prefect.context" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Async and thread safe models for passing runtime context data.</p>
+        <p>Async and thread safe models for passing runtime context data.</p>
 <p>These contexts should never be directly mutated by the user.</p>
 <p>For more user-accessible information about the current run, see <a href="../runtime/flow_run"><code>prefect.runtime</code></a>.</p>
 
@@ -13561,7 +13562,7 @@ <h2 id="prefect.context.ContextModel" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>A base model for context data that forbids mutation and extra data while providing
+        <p>A base model for context data that forbids mutation and extra data while providing
 a context manager</p>
 
               <details class="quote">
@@ -13697,7 +13698,7 @@ <h3 id="prefect.context.ContextModel.copy" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Duplicate the context model, optionally choosing which fields to include, exclude, or change.</p>
+        <p>Duplicate the context model, optionally choosing which fields to include, exclude, or change.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13843,7 +13844,7 @@ <h2 id="prefect.context.EngineContext" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.RunContext" href="#prefect.context.RunContext">RunContext</a></code></p>
 
 
-      <p>The context for a flow run. Data in this context is only available from within a
+        <p>The context for a flow run. Data in this context is only available from within a
 flow run function.</p>
 
 
@@ -14101,7 +14102,7 @@ <h2 id="prefect.context.PrefectObjectRegistry" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.ContextModel" href="#prefect.context.ContextModel">ContextModel</a></code></p>
 
 
-      <p>A context that acts as a registry for all Prefect objects that are
+        <p>A context that acts as a registry for all Prefect objects that are
 registered during load and execution.</p>
 
 
@@ -14338,7 +14339,7 @@ <h3 id="prefect.context.PrefectObjectRegistry.register_instances" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Decorator for a class that adds registration to the <code>PrefectObjectRegistry</code>
+        <p>Decorator for a class that adds registration to the <code>PrefectObjectRegistry</code>
 on initialization of instances.</p>
 
             <details class="quote">
@@ -14422,7 +14423,7 @@ <h2 id="prefect.context.RunContext" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.ContextModel" href="#prefect.context.ContextModel">ContextModel</a></code></p>
 
 
-      <p>The base context for a flow or task run. Data in this context will always be
+        <p>The base context for a flow or task run. Data in this context will always be
 available when <code>get_run_context</code> is called.</p>
 
 
@@ -14527,7 +14528,7 @@ <h2 id="prefect.context.SettingsContext" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.ContextModel" href="#prefect.context.ContextModel">ContextModel</a></code></p>
 
 
-      <p>The context for a Prefect settings.</p>
+        <p>The context for a Prefect settings.</p>
 <p>This allows for safe concurrent access and modification of settings.</p>
 
 
@@ -14692,7 +14693,7 @@ <h2 id="prefect.context.TagsContext" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.ContextModel" href="#prefect.context.ContextModel">ContextModel</a></code></p>
 
 
-      <p>The context for <code>prefect.tags</code> management.</p>
+        <p>The context for <code>prefect.tags</code> management.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -14791,7 +14792,7 @@ <h2 id="prefect.context.TaskRunContext" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.context.RunContext" href="#prefect.context.RunContext">RunContext</a></code></p>
 
 
-      <p>The context for a task run. Data in this context is only available from within a
+        <p>The context for a task run. Data in this context is only available from within a
 task run function.</p>
 
 
@@ -14904,7 +14905,7 @@ <h2 id="prefect.context.get_run_context" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current run context from within a task or flow function.</p>
+        <p>Get the current run context from within a task or flow function.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14928,7 +14929,7 @@ <h2 id="prefect.context.get_run_context" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <p>Raises
+        <p>Raises
     RuntimeError: If called outside of a flow or task run.</p>
 
             <details class="quote">
@@ -14991,7 +14992,7 @@ <h2 id="prefect.context.get_settings_context" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current settings context which contains profile information and the
+        <p>Get the current settings context which contains profile information and the
 settings that are being used.</p>
 <p>Generally, the settings that are being used are a combination of values from the
 profile and environment. See <code>prefect.context.use_profile</code> for more details.</p>
@@ -15042,7 +15043,7 @@ <h2 id="prefect.context.registry_from_script" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a fresh registry with instances populated from execution of a script.</p>
+        <p>Return a fresh registry with instances populated from execution of a script.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/context.py</code></summary>
@@ -15092,7 +15093,7 @@ <h2 id="prefect.context.root_settings_context" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return the settings context that will exist as the root context for the module.</p>
+        <p>Return the settings context that will exist as the root context for the module.</p>
 <p>The profile to use is determined with the following precedence
 - Command line via 'prefect --profile <name>'
 - Environment variable via 'PREFECT_PROFILE'
@@ -15198,7 +15199,7 @@ <h2 id="prefect.context.tags" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Context manager to add tags to flow and task run calls.</p>
+        <p>Context manager to add tags to flow and task run calls.</p>
 <p>Tags are always combined with any existing tags.</p>
 
 
@@ -15391,7 +15392,7 @@ <h2 id="prefect.context.use_profile" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Switch to a profile for the duration of this context.</p>
+        <p>Switch to a profile for the duration of this context.</p>
 <p>Profile contexts are confined to an async context in a single thread.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/deployments/base/index.html b/versions/unreleased/api-ref/prefect/deployments/base/index.html
index ec8d287e21..25284ace78 100644
--- a/versions/unreleased/api-ref/prefect/deployments/base/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/base/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13261,7 +13262,7 @@ <h1 id="prefect.deployments.base" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Core primitives for managing Prefect deployments via <code>prefect deploy</code>, providing a minimally opinionated
+        <p>Core primitives for managing Prefect deployments via <code>prefect deploy</code>, providing a minimally opinionated
 build system for managing flows and deployments.</p>
 <p>To get started, follow along with <a href="/tutorials/deployments/">the deloyments tutorial</a>.</p>
 
@@ -13288,7 +13289,7 @@ <h2 id="prefect.deployments.base.configure_project_by_recipe" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Given a recipe name, returns a dictionary representing base configuration options.</p>
+        <p>Given a recipe name, returns a dictionary representing base configuration options.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13424,7 +13425,7 @@ <h2 id="prefect.deployments.base.create_default_prefect_yaml" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Creates default <code>prefect.yaml</code> file in the provided path if one does not already exist;
+        <p>Creates default <code>prefect.yaml</code> file in the provided path if one does not already exist;
 returns boolean specifying whether a file was created.</p>
 
 
@@ -13666,7 +13667,7 @@ <h2 id="prefect.deployments.base.initialize_project" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Initializes a basic project structure with base files.  If no name is provided, the name
+        <p>Initializes a basic project structure with base files.  If no name is provided, the name
 of the current directory is used.  If no recipe is provided, one is inferred.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/deployments/deployments/index.html b/versions/unreleased/api-ref/prefect/deployments/deployments/index.html
index 737c4f3724..f23da68a12 100644
--- a/versions/unreleased/api-ref/prefect/deployments/deployments/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/deployments/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13427,7 +13428,7 @@ <h1 id="prefect.deployments.deployments" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Objects for specifying deployments and utilities for loading flows from deployments.</p>
+        <p>Objects for specifying deployments and utilities for loading flows from deployments.</p>
 
 
 
@@ -13456,7 +13457,7 @@ <h2 id="prefect.deployments.deployments.Deployment" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This class is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by <code>flow.deploy</code>, which offers enhanced functionality and better a better user experience.
 For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>
@@ -13723,7 +13724,7 @@ <h2 id="prefect.deployments.deployments.Deployment" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">deployment</span><span class="w"> </span><span class="n">using</span><span class="w"> </span><span class="n">configuration</span><span class="w"> </span><span class="n">defaults</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="n">imported</span><span class="w"> </span><span class="n">flow</span><span class="p">:</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">deployment</span><span class="w"> </span><span class="n">using</span><span class="w"> </span><span class="n">configuration</span><span class="w"> </span><span class="n">defaults</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="n">imported</span><span class="w"> </span><span class="n">flow</span><span class="p">:</span>
 
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">my_project.flows</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">my_flow</span>
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">prefect.deployments</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">Deployment</span>
@@ -15178,7 +15179,7 @@ <h3 id="prefect.deployments.deployments.Deployment.location" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>The 'location' that this deployment points to is given by <code>path</code> alone
+        <p>The 'location' that this deployment points to is given by <code>path</code> alone
 in the case of no remote storage, and otherwise by <code>storage.basepath / path</code>.</p>
 <p>The underlying flow entrypoint is interpreted relative to this location.</p>
     </div>
@@ -15202,7 +15203,7 @@ <h3 id="prefect.deployments.deployments.Deployment.apply" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Registers this deployment with the API and returns the deployment's ID.</p>
+        <p>Registers this deployment with the API and returns the deployment's ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15484,7 +15485,7 @@ <h3 id="prefect.deployments.deployments.Deployment.build_from_flow" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Configure a deployment for a given flow.</p>
+        <p>Configure a deployment for a given flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15892,7 +15893,7 @@ <h3 id="prefect.deployments.deployments.Deployment.load" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Queries the API for a deployment with this name for this flow, and if found,
+        <p>Queries the API for a deployment with this name for this flow, and if found,
 prepopulates any settings that were not set at initialization.</p>
 <p>Returns a boolean specifying whether a load was successful or not.</p>
 
@@ -16103,7 +16104,7 @@ <h3 id="prefect.deployments.deployments.Deployment.update" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Performs an in-place update with the provided settings.</p>
+        <p>Performs an in-place update with the provided settings.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16193,7 +16194,7 @@ <h3 id="prefect.deployments.deployments.Deployment.upload_to_storage" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Uploads the workflow this deployment represents using a provided storage block;
+        <p>Uploads the workflow this deployment represents using a provided storage block;
 if no block is provided, defaults to configuring self for local storage.</p>
 
 
@@ -16361,7 +16362,7 @@ <h2 id="prefect.deployments.deployments.load_deployments_from_yaml" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Load deployments from a yaml file.</p>
+        <p>Load deployments from a yaml file.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/deployments/deployments.py</code></summary>
@@ -16429,7 +16430,7 @@ <h2 id="prefect.deployments.deployments.load_flow_from_flow_run" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Load a flow from the location/script provided in a deployment's storage document.</p>
+        <p>Load a flow from the location/script provided in a deployment's storage document.</p>
 <p>If <code>ignore_storage=True</code> is provided, no pull from remote storage occurs.  This flag
 is largely for testing, and assumes the flow is already available locally.</p>
 
@@ -16627,7 +16628,7 @@ <h2 id="prefect.deployments.deployments.run_deployment" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run for a deployment and return it after completion or a timeout.</p>
+        <p>Create a flow run for a deployment and return it after completion or a timeout.</p>
 <p>By default, this function blocks until the flow run finishes executing.
 Specify a timeout (in seconds) to wait for the flow run to execute before
 returning flow run metadata. To return immediately, without waiting for the
diff --git a/versions/unreleased/api-ref/prefect/deployments/runner/index.html b/versions/unreleased/api-ref/prefect/deployments/runner/index.html
index f60ab18ae6..45f0485c4e 100644
--- a/versions/unreleased/api-ref/prefect/deployments/runner/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/runner/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13427,7 +13428,7 @@ <h1 id="prefect.deployments.runner" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Objects for creating and configuring deployments for flows using <code>serve</code> functionality.</p>
+        <p>Objects for creating and configuring deployments for flows using <code>serve</code> functionality.</p>
 
 
 <details class="example" open>
@@ -13483,7 +13484,7 @@ <h2 id="prefect.deployments.runner.DeploymentApplyError" class="doc doc-heading"
               Bases: <code>RuntimeError</code></p>
 
 
-      <p>Raised when an error occurs while applying a deployment.</p>
+        <p>Raised when an error occurs while applying a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/deployments/runner.py</code></summary>
@@ -13515,7 +13516,7 @@ <h2 id="prefect.deployments.runner.DeploymentImage" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Configuration used to build and push a Docker image for a deployment.</p>
+        <p>Configuration used to build and push a Docker image for a deployment.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13737,7 +13738,7 @@ <h2 id="prefect.deployments.runner.EntrypointType" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Enum representing a entrypoint type.</p>
+        <p>Enum representing a entrypoint type.</p>
 <p>File path entrypoints are in the format: <code>path/to/file.py:function_name</code>.
 Module path entrypoints are in the format: <code>path.to.module.function_name</code>.</p>
 
@@ -13801,7 +13802,7 @@ <h2 id="prefect.deployments.runner.RunnerDeployment" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>A Prefect RunnerDeployment definition, used for specifying and building deployments.</p>
+        <p>A Prefect RunnerDeployment definition, used for specifying and building deployments.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -15344,7 +15345,7 @@ <h3 id="prefect.deployments.runner.RunnerDeployment.apply" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Registers this deployment with the API and returns the deployment's ID.</p>
+        <p>Registers this deployment with the API and returns the deployment's ID.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15641,7 +15642,7 @@ <h3 id="prefect.deployments.runner.RunnerDeployment.from_entrypoint" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Configure a deployment for a given flow located at a given entrypoint.</p>
+        <p>Configure a deployment for a given flow located at a given entrypoint.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16134,7 +16135,7 @@ <h3 id="prefect.deployments.runner.RunnerDeployment.from_flow" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Configure a deployment for a given flow.</p>
+        <p>Configure a deployment for a given flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16707,7 +16708,7 @@ <h3 id="prefect.deployments.runner.RunnerDeployment.from_storage" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a RunnerDeployment from a flow located at a given entrypoint and stored in a
+        <p>Create a RunnerDeployment from a flow located at a given entrypoint and stored in a
 local storage location.</p>
 
 
@@ -17209,7 +17210,7 @@ <h3 id="prefect.deployments.runner.RunnerDeployment.validate_automation_names" c
 
     <div class="doc doc-contents ">
 
-      <p>Ensure that each trigger has a name for its automation if none is provided.</p>
+        <p>Ensure that each trigger has a name for its automation if none is provided.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/deployments/runner.py</code></summary>
@@ -17250,7 +17251,7 @@ <h2 id="prefect.deployments.runner.deploy" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deploy the provided list of deployments to dynamic infrastructure via a
+        <p>Deploy the provided list of deployments to dynamic infrastructure via a
 work pool.</p>
 <p>By default, calling this function will build a Docker image for the deployments, push it to a
 registry, and create each deployment via the Prefect API that will run the corresponding
diff --git a/versions/unreleased/api-ref/prefect/deployments/steps/core/index.html b/versions/unreleased/api-ref/prefect/deployments/steps/core/index.html
index 5af5c74b26..3c47e22bcc 100644
--- a/versions/unreleased/api-ref/prefect/deployments/steps/core/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/steps/core/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.deployments.steps.core" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Core primitives for running Prefect deployment steps.</p>
+        <p>Core primitives for running Prefect deployment steps.</p>
 <p>Deployment steps are YAML representations of Python functions along with their inputs.</p>
 <p>Whenever a step is run, the following actions are taken:</p>
 <ul>
@@ -13276,7 +13277,7 @@ <h2 id="prefect.deployments.steps.core.StepExecutionError" class="doc doc-headin
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when a step fails to execute.</p>
+        <p>Raised when a step fails to execute.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/deployments/steps/core.py</code></summary>
@@ -13310,7 +13311,7 @@ <h2 id="prefect.deployments.steps.core.run_step" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a step, returns the step's output.</p>
+        <p>Runs a step, returns the step's output.</p>
 <p>Steps are assumed to be in the format <code>{"importable.func.name": {"kwarg1": "value1", ...}}</code>.</p>
 <p>The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the
 inputs before passing to the step function:</p>
diff --git a/versions/unreleased/api-ref/prefect/deployments/steps/pull/index.html b/versions/unreleased/api-ref/prefect/deployments/steps/pull/index.html
index 126dc5ad39..feaf5a3622 100644
--- a/versions/unreleased/api-ref/prefect/deployments/steps/pull/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/steps/pull/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.deployments.steps.pull" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Core set of steps for specifying a Prefect project pull step.</p>
+        <p>Core set of steps for specifying a Prefect project pull step.</p>
 
 
 
@@ -13334,7 +13335,7 @@ <h2 id="prefect.deployments.steps.pull.git_clone" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clones a git repository into the current working directory.</p>
+        <p>Clones a git repository into the current working directory.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13724,7 +13725,7 @@ <h2 id="prefect.deployments.steps.pull.git_clone_project" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Deprecated. Use <code>git_clone</code> instead.</p>
+        <p>Deprecated. Use <code>git_clone</code> instead.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/deployments/steps/pull.py</code></summary>
@@ -13778,7 +13779,7 @@ <h2 id="prefect.deployments.steps.pull.pull_from_remote_storage" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Pulls code from a remote storage location into the current working directory.</p>
+        <p>Pulls code from a remote storage location into the current working directory.</p>
 <p>Works with protocols supported by <code>fsspec</code>.</p>
 
 
@@ -13966,7 +13967,7 @@ <h2 id="prefect.deployments.steps.pull.pull_with_block" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls code using a block.</p>
+        <p>Pulls code using a block.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14089,7 +14090,7 @@ <h2 id="prefect.deployments.steps.pull.set_working_directory" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Sets the working directory; works with both absolute and relative paths.</p>
+        <p>Sets the working directory; works with both absolute and relative paths.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/deployments/steps/utility/index.html b/versions/unreleased/api-ref/prefect/deployments/steps/utility/index.html
index 458633e9bf..53d87abe0f 100644
--- a/versions/unreleased/api-ref/prefect/deployments/steps/utility/index.html
+++ b/versions/unreleased/api-ref/prefect/deployments/steps/utility/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13261,7 +13262,7 @@ <h1 id="prefect.deployments.steps.utility" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utility project steps that are useful for managing a project's deployment lifecycle.</p>
+        <p>Utility project steps that are useful for managing a project's deployment lifecycle.</p>
 <p>Steps within this module can be used within a <code>build</code>, <code>push</code>, or <code>pull</code> deployment action.</p>
 
 
@@ -13308,7 +13309,7 @@ <h2 id="prefect.deployments.steps.utility.RunShellScriptResult" class="doc doc-h
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The result of a <code>run_shell_script</code> step.</p>
+        <p>The result of a <code>run_shell_script</code> step.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13408,7 +13409,7 @@ <h2 id="prefect.deployments.steps.utility.pip_install_requirements" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Installs dependencies from a requirements.txt file.</p>
+        <p>Installs dependencies from a requirements.txt file.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13672,7 +13673,7 @@ <h2 id="prefect.deployments.steps.utility.run_shell_script" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Runs one or more shell commands in a subprocess. Returns the standard
+        <p>Runs one or more shell commands in a subprocess. Returns the standard
 output and standard error of the script.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/engine/index.html b/versions/unreleased/api-ref/prefect/engine/index.html
index 9dc960352d..5d4b1a3d3c 100644
--- a/versions/unreleased/api-ref/prefect/engine/index.html
+++ b/versions/unreleased/api-ref/prefect/engine/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13640,7 +13641,7 @@ <h1 id="prefect.engine" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Client-side execution and orchestration of flows and tasks.</p>
+        <p>Client-side execution and orchestration of flows and tasks.</p>
 <h3 id="prefect.engine--engine-process-overview">Engine process overview<a class="headerlink" href="#prefect.engine--engine-process-overview" title="Permanent link">&para;</a></h3>
 <h4 id="prefect.engine--flows">Flows<a class="headerlink" href="#prefect.engine--flows" title="Permanent link">&para;</a></h4>
 <ul>
@@ -13748,7 +13749,7 @@ <h2 id="prefect.engine.begin_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Begins execution of a flow run; blocks until completion of the flow run</p>
+        <p>Begins execution of a flow run; blocks until completion of the flow run</p>
 <ul>
 <li>Starts a task runner</li>
 <li>Determines the result storage block to use</li>
@@ -14017,7 +14018,7 @@ <h2 id="prefect.engine.begin_task_map" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Async entrypoint for task mapping</p>
+        <p>Async entrypoint for task mapping</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/engine.py</code></summary>
@@ -14251,7 +14252,7 @@ <h2 id="prefect.engine.begin_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Entrypoint for task run execution.</p>
+        <p>Entrypoint for task run execution.</p>
 <p>This function is intended for submission to the task runner.</p>
 <p>This method may be called from a worker so we ensure the settings context has been
 entered. For example, with a runner that is executing tasks in the same event loop,
@@ -14528,7 +14529,7 @@ <h2 id="prefect.engine.create_and_begin_subflow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Async entrypoint for flows calls within a flow run</p>
+        <p>Async entrypoint for flows calls within a flow run</p>
 <p>Subflows differ from parent flows in that they
 - Resolve futures in passed parameters into values
 - Create a dummy task for representation in the parent flow
@@ -14909,7 +14910,7 @@ <h2 id="prefect.engine.create_autonomous_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run in the API for an autonomous task submission and store
+        <p>Create a task run in the API for an autonomous task submission and store
 the provided parameters using the existing result storage mechanism.</p>
 
             <details class="quote">
@@ -14986,7 +14987,7 @@ <h2 id="prefect.engine.create_then_begin_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Async entrypoint for flow calls</p>
+        <p>Async entrypoint for flow calls</p>
 <p>Creates the flow run in the backend, then enters the main flow run engine.</p>
 
             <details class="quote">
@@ -15137,7 +15138,7 @@ <h2 id="prefect.engine.enter_flow_run_engine_from_flow_call" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Sync entrypoint for flow calls.</p>
+        <p>Sync entrypoint for flow calls.</p>
 <p>This function does the heavy lifting of ensuring we can get into an async context
 for flow run execution with minimal overhead.</p>
 
@@ -15303,7 +15304,7 @@ <h2 id="prefect.engine.enter_flow_run_engine_from_subprocess" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Sync entrypoint for flow runs that have been submitted for execution by an agent</p>
+        <p>Sync entrypoint for flow runs that have been submitted for execution by an agent</p>
 <p>Differs from <code>enter_flow_run_engine_from_flow_call</code> in that we have a flow run id
 but not a flow object. The flow must be retrieved before execution can begin.
 Additionally, this assumes that the caller is always in a context without an event
@@ -15381,7 +15382,7 @@ <h2 id="prefect.engine.enter_task_run_engine" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sync entrypoint for task calls</p>
+        <p>Sync entrypoint for task calls</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/engine.py</code></summary>
@@ -15521,7 +15522,7 @@ <h2 id="prefect.engine.orchestrate_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a flow run.</p>
+        <p>Executes a flow run.</p>
 
 
 <details class="note-on-flow-timeouts" open>
@@ -16017,7 +16018,7 @@ <h2 id="prefect.engine.orchestrate_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Execute a task run</p>
+        <p>Execute a task run</p>
 <p>This function should be submitted to a task runner. We must construct the context
 here instead of receiving it already populated since we may be in a new environment.</p>
 <p>Proposes a RUNNING state, then
@@ -16764,7 +16765,7 @@ <h2 id="prefect.engine.pause_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pauses the current flow run by blocking execution until resumed.</p>
+        <p>Pauses the current flow run by blocking execution until resumed.</p>
 <p>When called within a flow run, execution will block and no downstream tasks will
 run until the flow is resumed. Task runs that have already started will continue
 running. A timeout parameter can be passed that will fail the flow run if it has not
@@ -16889,7 +16890,7 @@ <h2 id="prefect.engine.pause_flow_run" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code><span class="nd">@task</span>
+        <div class="highlight"><pre><span></span><code><span class="nd">@task</span>
 <span class="k">def</span> <span class="nf">task_one</span><span class="p">():</span>
     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">):</span>
         <span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
@@ -17114,7 +17115,7 @@ <h2 id="prefect.engine.report_flow_run_crashes" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Detect flow run crashes during this context and update the run to a proper final
+        <p>Detect flow run crashes during this context and update the run to a proper final
 state.</p>
 <p>This context <em>must</em> reraise the exception to properly exit the run.</p>
 
@@ -17212,7 +17213,7 @@ <h2 id="prefect.engine.report_task_run_crashes" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Detect task run crashes during this context and update the run to a proper final
+        <p>Detect task run crashes during this context and update the run to a proper final
 state.</p>
 <p>This context <em>must</em> reraise the exception to properly exit the run.</p>
 
@@ -17300,7 +17301,7 @@ <h2 id="prefect.engine.resume_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resumes a paused flow.</p>
+        <p>Resumes a paused flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17420,7 +17421,7 @@ <h2 id="prefect.engine.retrieve_flow_then_begin_flow_run" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Async entrypoint for flow runs that have been submitted for execution by an agent</p>
+        <p>Async entrypoint for flow runs that have been submitted for execution by an agent</p>
 <ul>
 <li>Retrieves the deployment information</li>
 <li>Loads the flow object using deployment information</li>
@@ -17613,7 +17614,7 @@ <h2 id="prefect.engine.suspend_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Suspends a flow run by stopping code execution until resumed.</p>
+        <p>Suspends a flow run by stopping code execution until resumed.</p>
 <p>When suspended, the flow run will continue execution until the NEXT task is
 orchestrated, at which point the flow will exit. Any tasks that have
 already started will run until completion. When resumed, the flow run will
diff --git a/versions/unreleased/api-ref/prefect/events/index.html b/versions/unreleased/api-ref/prefect/events/index.html
index 15e8c9034d..924e52095c 100644
--- a/versions/unreleased/api-ref/prefect/events/index.html
+++ b/versions/unreleased/api-ref/prefect/events/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14298,7 +14299,7 @@ <h2 id="prefect.events.TriggerTypes" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The union of all concrete trigger types that a user may actually create</p>
+        <p>The union of all concrete trigger types that a user may actually create</p>
     </div>
 
 </div>
@@ -14320,7 +14321,7 @@ <h2 id="prefect.events.Action" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>An Action that may be performed when an Automation is triggered</p>
+        <p>An Action that may be performed when an Automation is triggered</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14365,7 +14366,7 @@ <h3 id="prefect.events.Action.describe_for_cli" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A human-readable description of the action</p>
+        <p>A human-readable description of the action</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14404,7 +14405,7 @@ <h2 id="prefect.events.AutomationCore" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines an action a user wants to take when a certain number of events
+        <p>Defines an action a user wants to take when a certain number of events
 do or don't happen to the matching resources</p>
 
               <details class="quote">
@@ -14517,7 +14518,7 @@ <h2 id="prefect.events.CallWebhook" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Call a webhook when an Automation is triggered.</p>
+        <p>Call a webhook when an Automation is triggered.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14581,7 +14582,7 @@ <h2 id="prefect.events.CancelFlowRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Cancels a flow run associated with the trigger</p>
+        <p>Cancels a flow run associated with the trigger</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14631,7 +14632,7 @@ <h2 id="prefect.events.ChangeFlowRunState" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Changes the state of a flow run associated with the trigger</p>
+        <p>Changes the state of a flow run associated with the trigger</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14707,7 +14708,7 @@ <h2 id="prefect.events.CompositeTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.Trigger" href="../automations/#prefect.automations.Trigger">Trigger</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Requires some number of triggers to have fired within the given time period.</p>
+        <p>Requires some number of triggers to have fired within the given time period.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -14765,7 +14766,7 @@ <h2 id="prefect.events.CompoundTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.CompositeTrigger" href="../automations/#prefect.automations.CompositeTrigger">CompositeTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have
+        <p>A composite trigger that requires some number of triggers to have
 fired within the given time period</p>
 
               <details class="quote">
@@ -14869,7 +14870,7 @@ <h3 id="prefect.events.CompoundTrigger.describe_for_cli" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -14934,7 +14935,7 @@ <h2 id="prefect.events.DeclareIncident" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Declares an incident for the triggering event.  Only available on Prefect Cloud</p>
+        <p>Declares an incident for the triggering event.  Only available on Prefect Cloud</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -14984,7 +14985,7 @@ <h2 id="prefect.events.DeploymentCompoundTrigger" class="doc doc-heading">
               Bases: <code><span title="prefect.events.schemas.deployment_triggers.BaseDeploymentTrigger">BaseDeploymentTrigger</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.CompoundTrigger" href="../automations/#prefect.automations.CompoundTrigger">CompoundTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have
+        <p>A composite trigger that requires some number of triggers to have
 fired within the given time period</p>
 
               <details class="quote">
@@ -15037,7 +15038,7 @@ <h2 id="prefect.events.DeploymentEventTrigger" class="doc doc-heading">
               Bases: <code><span title="prefect.events.schemas.deployment_triggers.BaseDeploymentTrigger">BaseDeploymentTrigger</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.EventTrigger" href="../automations/#prefect.automations.EventTrigger">EventTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the presence or absence of events within a given
+        <p>A trigger that fires based on the presence or absence of events within a given
 period of time.</p>
 
               <details class="quote">
@@ -15094,7 +15095,7 @@ <h2 id="prefect.events.DeploymentMetricTrigger" class="doc doc-heading">
               Bases: <code><span title="prefect.events.schemas.deployment_triggers.BaseDeploymentTrigger">BaseDeploymentTrigger</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.MetricTrigger" href="../automations/#prefect.automations.MetricTrigger">MetricTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the results of a metric query.</p>
+        <p>A trigger that fires based on the results of a metric query.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/deployment_triggers.py</code></summary>
@@ -15148,7 +15149,7 @@ <h2 id="prefect.events.DeploymentSequenceTrigger" class="doc doc-heading">
               Bases: <code><span title="prefect.events.schemas.deployment_triggers.BaseDeploymentTrigger">BaseDeploymentTrigger</span></code>, <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.SequenceTrigger" href="../automations/#prefect.automations.SequenceTrigger">SequenceTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have fired
+        <p>A composite trigger that requires some number of triggers to have fired
 within the given time period in a specific order</p>
 
               <details class="quote">
@@ -15201,7 +15202,7 @@ <h2 id="prefect.events.DoNothing" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Do nothing when an Automation is triggered</p>
+        <p>Do nothing when an Automation is triggered</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -15251,7 +15252,7 @@ <h2 id="prefect.events.Event" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>The client-side view of an event that has happened to a Resource</p>
+        <p>The client-side view of an event that has happened to a Resource</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/events.py</code></summary>
@@ -15429,7 +15430,7 @@ <h3 id="prefect.events.Event.resource_in_role" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a mapping of roles to the first related resource in that role</p>
+        <p>Returns a mapping of roles to the first related resource in that role</p>
     </div>
 
 </div>
@@ -15450,7 +15451,7 @@ <h3 id="prefect.events.Event.resources_in_role" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a mapping of roles to related resources in that role</p>
+        <p>Returns a mapping of roles to related resources in that role</p>
     </div>
 
 </div>
@@ -15468,7 +15469,7 @@ <h3 id="prefect.events.Event.find_resource_label" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Finds the value of the given label in this event's resource or one of its
+        <p>Finds the value of the given label in this event's resource or one of its
 related resources.  If the label starts with <code>related:&lt;role&gt;:</code>, search for the
 first matching label in a related resource with that role.</p>
 
@@ -15525,7 +15526,7 @@ <h2 id="prefect.events.EventTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.ResourceTrigger" href="../automations/#prefect.automations.ResourceTrigger">ResourceTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the presence or absence of events within a given
+        <p>A trigger that fires based on the presence or absence of events within a given
 period of time.</p>
 
               <details class="quote">
@@ -15767,7 +15768,7 @@ <h3 id="prefect.events.EventTrigger.describe_for_cli" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15842,7 +15843,7 @@ <h2 id="prefect.events.MetricTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.ResourceTrigger" href="../automations/#prefect.automations.ResourceTrigger">ResourceTrigger</a></code></p>
 
 
-      <p>A trigger that fires based on the results of a metric query.</p>
+        <p>A trigger that fires based on the results of a metric query.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15927,7 +15928,7 @@ <h3 id="prefect.events.MetricTrigger.describe_for_cli" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -15982,7 +15983,7 @@ <h2 id="prefect.events.MetricTriggerQuery" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines a subset of the Trigger subclass, which is specific
+        <p>Defines a subset of the Trigger subclass, which is specific
 to Metric automations, that specify the query configurations
 and breaching conditions for the Automation</p>
 
@@ -16112,7 +16113,7 @@ <h2 id="prefect.events.PauseAutomation" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.AutomationAction">AutomationAction</span></code></p>
 
 
-      <p>Pauses a Work Queue</p>
+        <p>Pauses a Work Queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16162,7 +16163,7 @@ <h2 id="prefect.events.PauseDeployment" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.DeploymentAction">DeploymentAction</span></code></p>
 
 
-      <p>Pauses the given Deployment</p>
+        <p>Pauses the given Deployment</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16212,7 +16213,7 @@ <h2 id="prefect.events.PauseWorkPool" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.WorkPoolAction">WorkPoolAction</span></code></p>
 
 
-      <p>Pauses a Work Pool</p>
+        <p>Pauses a Work Pool</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16262,7 +16263,7 @@ <h2 id="prefect.events.PauseWorkQueue" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.WorkQueueAction">WorkQueueAction</span></code></p>
 
 
-      <p>Pauses a Work Queue</p>
+        <p>Pauses a Work Queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16312,7 +16313,7 @@ <h2 id="prefect.events.ReceivedEvent" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.events.Event" href="#prefect.events.Event">Event</a></code></p>
 
 
-      <p>The server-side view of an event that has happened to a Resource after it has
+        <p>The server-side view of an event that has happened to a Resource after it has
 been received by the server</p>
 
               <details class="quote">
@@ -16377,7 +16378,7 @@ <h2 id="prefect.events.RelatedResource" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.events.Resource" href="#prefect.events.Resource">Resource</a></code></p>
 
 
-      <p>A Resource with a specific role in an Event</p>
+        <p>A Resource with a specific role in an Event</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/events.py</code></summary>
@@ -16465,7 +16466,7 @@ <h2 id="prefect.events.Resource" class="doc doc-heading">
               Bases: <code><span title="prefect.events.schemas.labelling.Labelled">Labelled</span></code></p>
 
 
-      <p>An observable business object of interest to the user</p>
+        <p>An observable business object of interest to the user</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/events.py</code></summary>
@@ -16585,7 +16586,7 @@ <h2 id="prefect.events.ResourceSpecification" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A specification that may match zero, one, or many resources, used to target or
+        <p>A specification that may match zero, one, or many resources, used to target or
 select a set of resources in a query or automation.  A resource must match at least
 one value of all of the provided labels</p>
 
@@ -16789,7 +16790,7 @@ <h2 id="prefect.events.ResourceTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.Trigger" href="../automations/#prefect.automations.Trigger">Trigger</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Base class for triggers that may filter by the labels of resources.</p>
+        <p>Base class for triggers that may filter by the labels of resources.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -16861,7 +16862,7 @@ <h2 id="prefect.events.ResumeAutomation" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.AutomationAction">AutomationAction</span></code></p>
 
 
-      <p>Resumes a Work Queue</p>
+        <p>Resumes a Work Queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16911,7 +16912,7 @@ <h2 id="prefect.events.ResumeDeployment" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.DeploymentAction">DeploymentAction</span></code></p>
 
 
-      <p>Resumes the given Deployment</p>
+        <p>Resumes the given Deployment</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -16961,7 +16962,7 @@ <h2 id="prefect.events.ResumeWorkPool" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.WorkPoolAction">WorkPoolAction</span></code></p>
 
 
-      <p>Resumes a Work Pool</p>
+        <p>Resumes a Work Pool</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -17011,7 +17012,7 @@ <h2 id="prefect.events.ResumeWorkQueue" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.WorkQueueAction">WorkQueueAction</span></code></p>
 
 
-      <p>Resumes a Work Queue</p>
+        <p>Resumes a Work Queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -17061,7 +17062,7 @@ <h2 id="prefect.events.RunDeployment" class="doc doc-heading">
               Bases: <code><span title="prefect.events.actions.DeploymentAction">DeploymentAction</span></code></p>
 
 
-      <p>Runs the given deployment with the given parameters</p>
+        <p>Runs the given deployment with the given parameters</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -17141,7 +17142,7 @@ <h2 id="prefect.events.SendNotification" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Send a notification when an Automation is triggered</p>
+        <p>Send a notification when an Automation is triggered</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -17201,7 +17202,7 @@ <h2 id="prefect.events.SequenceTrigger" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.schemas.automations.CompositeTrigger" href="../automations/#prefect.automations.CompositeTrigger">CompositeTrigger</a></code></p>
 
 
-      <p>A composite trigger that requires some number of triggers to have fired
+        <p>A composite trigger that requires some number of triggers to have fired
 within the given time period in a specific order</p>
 
               <details class="quote">
@@ -17275,7 +17276,7 @@ <h3 id="prefect.events.SequenceTrigger.describe_for_cli" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -17340,7 +17341,7 @@ <h2 id="prefect.events.SuspendFlowRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.events.actions.Action" href="#prefect.events.Action">Action</a></code></p>
 
 
-      <p>Suspends a flow run associated with the trigger</p>
+        <p>Suspends a flow run associated with the trigger</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/events/actions.py</code></summary>
@@ -17390,7 +17391,7 @@ <h2 id="prefect.events.Trigger" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Base class describing a set of criteria that must be satisfied in order to trigger
+        <p>Base class describing a set of criteria that must be satisfied in order to trigger
 an automation.</p>
 
               <details class="quote">
@@ -17534,7 +17535,7 @@ <h3 id="prefect.events.Trigger.describe_for_cli" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a human-readable description of this trigger for the CLI</p>
+        <p>Return a human-readable description of this trigger for the CLI</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/events/schemas/automations.py</code></summary>
@@ -17569,7 +17570,7 @@ <h2 id="prefect.events.emit_event" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Send an event to Prefect Cloud.</p>
+        <p>Send an event to Prefect Cloud.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/exceptions/index.html b/versions/unreleased/api-ref/prefect/exceptions/index.html
index 711faaf2b5..cedbf81c7d 100644
--- a/versions/unreleased/api-ref/prefect/exceptions/index.html
+++ b/versions/unreleased/api-ref/prefect/exceptions/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14068,7 +14069,7 @@ <h1 id="prefect.exceptions" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect-specific exceptions.</p>
+        <p>Prefect-specific exceptions.</p>
 
 
 
@@ -14097,7 +14098,7 @@ <h2 id="prefect.exceptions.Abort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectSignal" href="#prefect.exceptions.PrefectSignal">PrefectSignal</a></code></p>
 
 
-      <p>Raised when the API sends an 'ABORT' instruction during state proposal.</p>
+        <p>Raised when the API sends an 'ABORT' instruction during state proposal.</p>
 <p>Indicates that the run should exit immediately.</p>
 
               <details class="quote">
@@ -14136,7 +14137,7 @@ <h2 id="prefect.exceptions.BlockMissingCapabilities" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a block does not have required capabilities for a given operation.</p>
+        <p>Raised when a block does not have required capabilities for a given operation.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14170,7 +14171,7 @@ <h2 id="prefect.exceptions.CancelledRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the result from a cancelled run is retrieved and an exception
+        <p>Raised when the result from a cancelled run is retrieved and an exception
 is not attached.</p>
 <p>This occurs when a string is attached to the state instead of an exception
 or if the state's data is null.</p>
@@ -14215,7 +14216,7 @@ <h2 id="prefect.exceptions.CrashedRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the result from a crashed run is retrieved.</p>
+        <p>Raised when the result from a crashed run is retrieved.</p>
 <p>This occurs when a string is attached to the state instead of an exception or if
 the state's data is null.</p>
 
@@ -14257,7 +14258,7 @@ <h2 id="prefect.exceptions.ExternalSignal" class="doc doc-heading">
               Bases: <code>BaseException</code></p>
 
 
-      <p>Base type for external signal-like exceptions that should never be caught by users.</p>
+        <p>Base type for external signal-like exceptions that should never be caught by users.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14291,7 +14292,7 @@ <h2 id="prefect.exceptions.FailedRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the result from a failed run is retrieved and an exception is not
+        <p>Raised when the result from a failed run is retrieved and an exception is not
 attached.</p>
 <p>This occurs when a string is attached to the state instead of an exception or if
 the state's data is null.</p>
@@ -14336,7 +14337,7 @@ <h2 id="prefect.exceptions.FlowPauseTimeout" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a flow pause times out</p>
+        <p>Raised when a flow pause times out</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14366,7 +14367,7 @@ <h2 id="prefect.exceptions.FlowRunWaitTimeout" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a flow run takes longer than a given timeout</p>
+        <p>Raised when a flow run takes longer than a given timeout</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14396,7 +14397,7 @@ <h2 id="prefect.exceptions.FlowScriptError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a script errors during evaluation while attempting to load a flow.</p>
+        <p>Raised when a script errors during evaluation while attempting to load a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14482,7 +14483,7 @@ <h2 id="prefect.exceptions.InfrastructureError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>A base class for exceptions related to infrastructure blocks</p>
+        <p>A base class for exceptions related to infrastructure blocks</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14516,7 +14517,7 @@ <h2 id="prefect.exceptions.InfrastructureNotAvailable" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when infrastructure is not accessible from the current machine. For example,
+        <p>Raised when infrastructure is not accessible from the current machine. For example,
 if a process was spawned on another machine it cannot be managed.</p>
 
               <details class="quote">
@@ -14553,7 +14554,7 @@ <h2 id="prefect.exceptions.InfrastructureNotFound" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when infrastructure is missing, likely because it has exited or been
+        <p>Raised when infrastructure is missing, likely because it has exited or been
 deleted.</p>
 
               <details class="quote">
@@ -14590,7 +14591,7 @@ <h2 id="prefect.exceptions.InvalidNameError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code>, <code>ValueError</code></p>
 
 
-      <p>Raised when a name contains characters that are not permitted.</p>
+        <p>Raised when a name contains characters that are not permitted.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14624,7 +14625,7 @@ <h2 id="prefect.exceptions.InvalidRepositoryURLError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when an incorrect URL is provided to a GitHub filesystem block.</p>
+        <p>Raised when an incorrect URL is provided to a GitHub filesystem block.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14654,7 +14655,7 @@ <h2 id="prefect.exceptions.MappingLengthMismatch" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when attempting to call Task.map with arguments of different lengths.</p>
+        <p>Raised when attempting to call Task.map with arguments of different lengths.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14688,7 +14689,7 @@ <h2 id="prefect.exceptions.MappingMissingIterable" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when attempting to call Task.map with all static arguments</p>
+        <p>Raised when attempting to call Task.map with all static arguments</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14722,7 +14723,7 @@ <h2 id="prefect.exceptions.MissingContextError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code>, <code>RuntimeError</code></p>
 
 
-      <p>Raised when a method is called that requires a task or flow run context to be
+        <p>Raised when a method is called that requires a task or flow run context to be
 active but one cannot be found.</p>
 
               <details class="quote">
@@ -14759,7 +14760,7 @@ <h2 id="prefect.exceptions.MissingFlowError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a given flow name is not found in the expected script.</p>
+        <p>Raised when a given flow name is not found in the expected script.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14793,7 +14794,7 @@ <h2 id="prefect.exceptions.MissingProfileError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code>, <code>ValueError</code></p>
 
 
-      <p>Raised when a profile name does not exist.</p>
+        <p>Raised when a profile name does not exist.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14827,7 +14828,7 @@ <h2 id="prefect.exceptions.MissingResult" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a result is missing from a state; often when result persistence is
+        <p>Raised when a result is missing from a state; often when result persistence is
 disabled and the state is retrieved from the API.</p>
 
               <details class="quote">
@@ -14864,7 +14865,7 @@ <h2 id="prefect.exceptions.NotPausedError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when attempting to unpause a run that isn't paused.</p>
+        <p>Raised when attempting to unpause a run that isn't paused.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14894,7 +14895,7 @@ <h2 id="prefect.exceptions.ObjectAlreadyExists" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the client receives a 409 (conflict) from the API.</p>
+        <p>Raised when the client receives a 409 (conflict) from the API.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -14952,7 +14953,7 @@ <h2 id="prefect.exceptions.ObjectNotFound" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the client receives a 404 (not found) from the API.</p>
+        <p>Raised when the client receives a 404 (not found) from the API.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15010,7 +15011,7 @@ <h2 id="prefect.exceptions.ParameterBindError" class="doc doc-heading">
               Bases: <code>TypeError</code>, <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when args and kwargs cannot be converted to parameters.</p>
+        <p>Raised when args and kwargs cannot be converted to parameters.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15090,7 +15091,7 @@ <h2 id="prefect.exceptions.ParameterTypeError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a parameter does not pass Pydantic type validation.</p>
+        <p>Raised when a parameter does not pass Pydantic type validation.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15164,7 +15165,7 @@ <h2 id="prefect.exceptions.Pause" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectSignal" href="#prefect.exceptions.PrefectSignal">PrefectSignal</a></code></p>
 
 
-      <p>Raised when a flow run is PAUSED and needs to exit for resubmission.</p>
+        <p>Raised when a flow run is PAUSED and needs to exit for resubmission.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15222,7 +15223,7 @@ <h2 id="prefect.exceptions.PausedRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the result from a paused run is retrieved.</p>
+        <p>Raised when the result from a paused run is retrieved.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15280,7 +15281,7 @@ <h2 id="prefect.exceptions.PrefectException" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Base exception type for Prefect errors.</p>
+        <p>Base exception type for Prefect errors.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15314,7 +15315,7 @@ <h2 id="prefect.exceptions.PrefectHTTPStatusError" class="doc doc-heading">
               Bases: <code><span title="httpx._exceptions.HTTPStatusError">HTTPStatusError</span></code></p>
 
 
-      <p>Raised when client receives a <code>Response</code> that contains an HTTPStatusError.</p>
+        <p>Raised when client receives a <code>Response</code> that contains an HTTPStatusError.</p>
 <p>Used to include API error details in the error messages that the client provides users.</p>
 
               <details class="quote">
@@ -15406,7 +15407,7 @@ <h3 id="prefect.exceptions.PrefectHTTPStatusError.from_httpx_error" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Generate a <code>PrefectHTTPStatusError</code> from an <code>httpx.HTTPStatusError</code>.</p>
+        <p>Generate a <code>PrefectHTTPStatusError</code> from an <code>httpx.HTTPStatusError</code>.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15483,7 +15484,7 @@ <h2 id="prefect.exceptions.PrefectSignal" class="doc doc-heading">
               Bases: <code>BaseException</code></p>
 
 
-      <p>Base type for signal-like exceptions that should never be caught by users.</p>
+        <p>Base type for signal-like exceptions that should never be caught by users.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15517,7 +15518,7 @@ <h2 id="prefect.exceptions.ProtectedBlockError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when an operation is prevented due to block protection.</p>
+        <p>Raised when an operation is prevented due to block protection.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15551,7 +15552,7 @@ <h2 id="prefect.exceptions.ReservedArgumentError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code>, <code>TypeError</code></p>
 
 
-      <p>Raised when a function used with Prefect has an argument with a name that is
+        <p>Raised when a function used with Prefect has an argument with a name that is
 reserved for a Prefect feature</p>
 
               <details class="quote">
@@ -15588,7 +15589,7 @@ <h2 id="prefect.exceptions.ScriptError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a script errors during evaluation while attempting to load data</p>
+        <p>Raised when a script errors during evaluation while attempting to load data</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15668,7 +15669,7 @@ <h2 id="prefect.exceptions.SignatureMismatchError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code>, <code>TypeError</code></p>
 
 
-      <p>Raised when parameters passed to a function do not match its signature.</p>
+        <p>Raised when parameters passed to a function do not match its signature.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15736,7 +15737,7 @@ <h2 id="prefect.exceptions.TerminationSignal" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.ExternalSignal" href="#prefect.exceptions.ExternalSignal">ExternalSignal</a></code></p>
 
 
-      <p>Raised when a flow run receives a termination signal.</p>
+        <p>Raised when a flow run receives a termination signal.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15792,7 +15793,7 @@ <h2 id="prefect.exceptions.UnfinishedRun" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when the result from a run that is not finished is retrieved.</p>
+        <p>Raised when the result from a run that is not finished is retrieved.</p>
 <p>For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.</p>
 
               <details class="quote">
@@ -15831,7 +15832,7 @@ <h2 id="prefect.exceptions.UnspecifiedFlowError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when multiple flows are found in the expected script and no name is given.</p>
+        <p>Raised when multiple flows are found in the expected script and no name is given.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/exceptions.py</code></summary>
@@ -15865,7 +15866,7 @@ <h2 id="prefect.exceptions.UpstreamTaskError" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.exceptions.PrefectException" href="#prefect.exceptions.PrefectException">PrefectException</a></code></p>
 
 
-      <p>Raised when a task relies on the result of another task but that task is not
+        <p>Raised when a task relies on the result of another task but that task is not
 'COMPLETE'</p>
 
               <details class="quote">
@@ -15898,7 +15899,7 @@ <h2 id="prefect.exceptions.exception_traceback" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert an exception to a printable string with a traceback</p>
+        <p>Convert an exception to a printable string with a traceback</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/exceptions.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/filesystems/index.html b/versions/unreleased/api-ref/prefect/filesystems/index.html
index 6a2cb3a52b..d98019fab9 100644
--- a/versions/unreleased/api-ref/prefect/filesystems/index.html
+++ b/versions/unreleased/api-ref/prefect/filesystems/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13727,7 +13728,7 @@ <h2 id="prefect.filesystems.Azure" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This class is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by <code>AzureBlobStorageContainer</code> from the <code>prefect-azure</code> package, which
 offers enhanced functionality and better a better user experience.</p>
@@ -14091,7 +14092,7 @@ <h3 id="prefect.filesystems.Azure.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a directory from a given remote path to a local directory.</p>
+        <p>Downloads a directory from a given remote path to a local directory.</p>
 <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -14140,7 +14141,7 @@ <h3 id="prefect.filesystems.Azure.put_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to a remote directory.</p>
+        <p>Uploads a directory from a given local path to a remote directory.</p>
 <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p>
 
             <details class="quote">
@@ -14204,7 +14205,7 @@ <h2 id="prefect.filesystems.GCS" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This class is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by <code>GcsBucket</code> from the <code>prefect-gcp</code> package, which offers enhanced functionality
 and better a better user experience.
@@ -14448,7 +14449,7 @@ <h3 id="prefect.filesystems.GCS.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a directory from a given remote path to a local directory.</p>
+        <p>Downloads a directory from a given remote path to a local directory.</p>
 <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -14497,7 +14498,7 @@ <h3 id="prefect.filesystems.GCS.put_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to a remote directory.</p>
+        <p>Uploads a directory from a given local path to a remote directory.</p>
 <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p>
 
             <details class="quote">
@@ -14561,7 +14562,7 @@ <h2 id="prefect.filesystems.GitHub" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.ReadableDeploymentStorage">ReadableDeploymentStorage</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="n">DEPRECATION</span><span class="w"> </span><span class="n">WARNING</span><span class="o">:</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">DEPRECATION</span><span class="w"> </span><span class="n">WARNING</span><span class="o">:</span>
 
 <span class="n">This</span><span class="w"> </span><span class="n">class</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="n">deprecated</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">March</span><span class="w"> </span><span class="mi">2024</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="n">will</span><span class="w"> </span><span class="k">not</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="n">available</span><span class="w"> </span><span class="k">after</span><span class="w"> </span><span class="n">September</span><span class="w"> </span><span class="mf">2024.</span>
 <span class="n">It</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">been</span><span class="w"> </span><span class="n">replaced</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="n n-Quoted">`GitHubRepository`</span><span class="w"> </span><span class="k">from</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n n-Quoted">`prefect-github`</span><span class="w"> </span><span class="n">package</span><span class="p">,</span><span class="w"> </span><span class="n">which</span><span class="w"> </span><span class="n">offers</span>
@@ -14870,7 +14871,7 @@ <h3 id="prefect.filesystems.GitHub.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>;
+        <p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>;
 defaults to cloning the repository reference configured on the Block to the
 present working directory.</p>
 
@@ -15043,7 +15044,7 @@ <h2 id="prefect.filesystems.LocalFileSystem" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>Store data as a file on a local file system.</p>
+        <p>Store data as a file on a local file system.</p>
 
 
 <details class="example" open>
@@ -15419,7 +15420,7 @@ <h3 id="prefect.filesystems.LocalFileSystem.get_directory" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Copies a directory from one place to another on the local filesystem.</p>
+        <p>Copies a directory from one place to another on the local filesystem.</p>
 <p>Defaults to copying the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -15512,7 +15513,7 @@ <h3 id="prefect.filesystems.LocalFileSystem.put_directory" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Copies a directory from one place to another on the local filesystem.</p>
+        <p>Copies a directory from one place to another on the local filesystem.</p>
 <p>Defaults to copying the entire contents of the current working directory to the block's basepath.
 An <code>ignore_file</code> path may be provided that can include gitignore style expressions for filepaths to ignore.</p>
 
@@ -15609,7 +15610,7 @@ <h2 id="prefect.filesystems.RemoteFileSystem" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>Store data as a file on a remote file system.</p>
+        <p>Store data as a file on a remote file system.</p>
 <p>Supports any remote file system supported by <code>fsspec</code>. The file system is specified
 using a protocol. For example, "s3://my-bucket/my-folder/" will use S3.</p>
 
@@ -16003,7 +16004,7 @@ <h3 id="prefect.filesystems.RemoteFileSystem.get_directory" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a directory from a given remote path to a local directory.</p>
+        <p>Downloads a directory from a given remote path to a local directory.</p>
 <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -16072,7 +16073,7 @@ <h3 id="prefect.filesystems.RemoteFileSystem.put_directory" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to a remote directory.</p>
+        <p>Uploads a directory from a given local path to a remote directory.</p>
 <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p>
 
             <details class="quote">
@@ -16212,7 +16213,7 @@ <h2 id="prefect.filesystems.S3" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This class is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by <code>S3Bucket</code> from the <code>prefect-aws</code> package, which offers enhanced functionality
 and better a better user experience.</p>
@@ -16454,7 +16455,7 @@ <h3 id="prefect.filesystems.S3.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a directory from a given remote path to a local directory.</p>
+        <p>Downloads a directory from a given remote path to a local directory.</p>
 <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -16503,7 +16504,7 @@ <h3 id="prefect.filesystems.S3.put_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to a remote directory.</p>
+        <p>Uploads a directory from a given local path to a remote directory.</p>
 <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p>
 
             <details class="quote">
@@ -16567,7 +16568,7 @@ <h2 id="prefect.filesystems.SMB" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>Store data as a file on a SMB share.</p>
+        <p>Store data as a file on a SMB share.</p>
 
 
 <details class="example" open>
@@ -16802,7 +16803,7 @@ <h3 id="prefect.filesystems.SMB.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a directory from a given remote path to a local directory.
+        <p>Downloads a directory from a given remote path to a local directory.
 Defaults to downloading the entire contents of the block's basepath to the current working directory.</p>
 
             <details class="quote">
@@ -16849,7 +16850,7 @@ <h3 id="prefect.filesystems.SMB.put_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to a remote directory.
+        <p>Uploads a directory from a given local path to a remote directory.
 Defaults to uploading the entire contents of the current working directory to the block's basepath.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/flow_runs/index.html b/versions/unreleased/api-ref/prefect/flow_runs/index.html
index a0e84aad48..a845a3b11b 100644
--- a/versions/unreleased/api-ref/prefect/flow_runs/index.html
+++ b/versions/unreleased/api-ref/prefect/flow_runs/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13225,7 +13226,7 @@ <h2 id="prefect.flow_runs.wait_for_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Waits for the prefect flow run to finish and returns the FlowRun</p>
+        <p>Waits for the prefect flow run to finish and returns the FlowRun</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/flows/index.html b/versions/unreleased/api-ref/prefect/flows/index.html
index 7ff41dbaa2..350cf7e9fe 100644
--- a/versions/unreleased/api-ref/prefect/flows/index.html
+++ b/versions/unreleased/api-ref/prefect/flows/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13628,7 +13629,7 @@ <h1 id="prefect.flows" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the base workflow class and decorator - for most use cases, using the <a class="autorefs autorefs-internal" href="#prefect.flows.flow"><code>@flow</code> decorator</a> is preferred.</p>
+        <p>Module containing the base workflow class and decorator - for most use cases, using the <a class="autorefs autorefs-internal" href="#prefect.flows.flow"><code>@flow</code> decorator</a> is preferred.</p>
 
 
 
@@ -13657,7 +13658,7 @@ <h2 id="prefect.flows.Flow" class="doc doc-heading">
               Bases: <code><span title="typing.Generic">Generic</span>[<span title="prefect.flows.P">P</span>, <span title="prefect.flows.R">R</span>]</code></p>
 
 
-      <p>A Prefect workflow definition.</p>
+        <p>A Prefect workflow definition.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>We recommend using the <a class="autorefs autorefs-internal" href="#prefect.flows.flow"><code>@flow</code> decorator</a> for most use-cases.</p>
@@ -16389,7 +16390,7 @@ <h3 id="prefect.flows.Flow.deploy" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deploys a flow to run on dynamic infrastructure via a work pool.</p>
+        <p>Deploys a flow to run on dynamic infrastructure via a work pool.</p>
 <p>By default, calling this method will build a Docker image for the flow, push it to a registry,
 and create a deployment via the Prefect API that will run the flow on the given schedule.</p>
 <p>If you want to use an existing image, you can pass <code>build=False</code> to skip building and pushing
@@ -17202,7 +17203,7 @@ <h3 id="prefect.flows.Flow.from_source" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Loads a flow from a remote source.</p>
+        <p>Loads a flow from a remote source.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17475,7 +17476,7 @@ <h3 id="prefect.flows.Flow.serialize_parameters" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert parameters to a serializable form.</p>
+        <p>Convert parameters to a serializable form.</p>
 <p>Uses FastAPI's <code>jsonable_encoder</code> to convert to JSON compatible objects without
 converting everything directly to a string. This maintains basic types like
 integers during API roundtrips.</p>
@@ -17542,7 +17543,7 @@ <h3 id="prefect.flows.Flow.serve" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a deployment for this flow and starts a runner to monitor for scheduled work.</p>
+        <p>Creates a deployment for this flow and starts a runner to monitor for scheduled work.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18164,7 +18165,7 @@ <h3 id="prefect.flows.Flow.to_deployment" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a runner deployment object for this flow.</p>
+        <p>Creates a runner deployment object for this flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18764,7 +18765,7 @@ <h3 id="prefect.flows.Flow.validate_parameters" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Validate parameters for compatibility with the flow by attempting to cast the inputs to the
+        <p>Validate parameters for compatibility with the flow by attempting to cast the inputs to the
 associated types specified by the function's type annotations.</p>
 
 
@@ -18951,7 +18952,7 @@ <h3 id="prefect.flows.Flow.visualize" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates a graphviz object representing the current flow. In IPython notebooks,
+        <p>Generates a graphviz object representing the current flow. In IPython notebooks,
 it's rendered inline, otherwise in a new window as a PNG.</p>
 
 
@@ -19111,7 +19112,7 @@ <h3 id="prefect.flows.Flow.with_options" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new flow from the current object, updating provided options.</p>
+        <p>Create a new flow from the current object, updating provided options.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19408,7 +19409,7 @@ <h3 id="prefect.flows.Flow.with_options" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">flow</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">an</span><span class="w"> </span><span class="n">existing</span><span class="w"> </span><span class="n">flow</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">update</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">name</span><span class="p">:</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">flow</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">an</span><span class="w"> </span><span class="n">existing</span><span class="w"> </span><span class="n">flow</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">update</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">name</span><span class="p">:</span>
 
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="nd">@flow</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;My flow&quot;</span><span class="p">)</span>
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="k">def</span><span class="w"> </span><span class="nf">my_flow</span><span class="p">():</span>
@@ -19714,7 +19715,7 @@ <h2 id="prefect.flows.flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Decorator to designate a function as a Prefect workflow.</p>
+        <p>Decorator to designate a function as a Prefect workflow.</p>
 <p>This decorator may be used for asynchronous or synchronous functions.</p>
 <p>Flow parameters must be serializable by Pydantic.</p>
 
@@ -20484,7 +20485,7 @@ <h2 id="prefect.flows.is_entrypoint_async" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Determine if the function specified in the entrypoint is asynchronous.</p>
+        <p>Determine if the function specified in the entrypoint is asynchronous.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20583,7 +20584,7 @@ <h2 id="prefect.flows.load_flow_arguments_from_entrypoint" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Extract flow arguments from an entrypoint string.</p>
+        <p>Extract flow arguments from an entrypoint string.</p>
 <p>Loads the source code of the entrypoint and extracts the flow arguments
 from the <code>flow</code> decorator.</p>
 
@@ -20791,7 +20792,7 @@ <h2 id="prefect.flows.load_flow_from_entrypoint" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extract a flow object from a script at an entrypoint by running all of the code in the file.</p>
+        <p>Extract a flow object from a script at an entrypoint by running all of the code in the file.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21021,7 +21022,7 @@ <h2 id="prefect.flows.load_flow_from_script" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extract a flow object from a script by running all of the code in the file.</p>
+        <p>Extract a flow object from a script by running all of the code in the file.</p>
 <p>If the script has multiple flows in it, a flow name must be provided to specify
 the flow to return.</p>
 
@@ -21212,7 +21213,7 @@ <h2 id="prefect.flows.load_flow_from_text" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load a flow from a text script.</p>
+        <p>Load a flow from a text script.</p>
 <p>The script will be written to a temporary local file path so errors can refer
 to line numbers and contextual tracebacks can be provided.</p>
 
@@ -21278,7 +21279,7 @@ <h2 id="prefect.flows.load_flows_from_script" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load all flow objects from the given python script. All of the code in the file
+        <p>Load all flow objects from the given python script. All of the code in the file
 will be executed.</p>
 
 
@@ -21369,7 +21370,7 @@ <h2 id="prefect.flows.load_placeholder_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load a placeholder flow that is initialized with the same arguments as the
+        <p>Load a placeholder flow that is initialized with the same arguments as the
 flow specified in the entrypoint. If called the flow will raise <code>raises</code>.</p>
 <p>This is useful when a flow can't be loaded due to missing dependencies or
 other issues but the base metadata defining the flow is still needed.</p>
@@ -21502,7 +21503,7 @@ <h2 id="prefect.flows.safe_load_flow_from_entrypoint" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load a flow from an entrypoint and return None if an exception is raised.</p>
+        <p>Load a flow from an entrypoint and return None if an exception is raised.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21596,7 +21597,7 @@ <h2 id="prefect.flows.select_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Select the only flow in an iterable or a flow specified by name.</p>
+        <p>Select the only flow in an iterable or a flow specified by name.</p>
 <p>Returns
     A single flow object</p>
 
@@ -21749,7 +21750,7 @@ <h2 id="prefect.flows.serve" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Serve the provided list of deployments.</p>
+        <p>Serve the provided list of deployments.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/futures/index.html b/versions/unreleased/api-ref/prefect/futures/index.html
index c52f891a1e..9d602088a8 100644
--- a/versions/unreleased/api-ref/prefect/futures/index.html
+++ b/versions/unreleased/api-ref/prefect/futures/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13342,7 +13343,7 @@ <h1 id="prefect.futures" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Futures represent the execution of a task and allow retrieval of the task run's state.</p>
+        <p>Futures represent the execution of a task and allow retrieval of the task run's state.</p>
 <p>This module contains the definition for futures as well as utilities for resolving
 futures in nested data structures.</p>
 
@@ -13373,7 +13374,7 @@ <h2 id="prefect.futures.PrefectFuture" class="doc doc-heading">
               Bases: <code><span title="typing.Generic">Generic</span>[<span title="prefect.futures.R">R</span>, <span title="prefect.utilities.asyncutils.A">A</span>]</code></p>
 
 
-      <p>Represents the result of a computation happening in a task runner.</p>
+        <p>Represents the result of a computation happening in a task runner.</p>
 <p>When tasks are called, they are submitted to a task runner which creates a future
 for access to the state and result of the task.</p>
 
@@ -13959,7 +13960,7 @@ <h3 id="prefect.futures.PrefectFuture.get_state" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current state of the task run.</p>
+        <p>Get the current state of the task run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/futures.py</code></summary>
@@ -13995,7 +13996,7 @@ <h3 id="prefect.futures.PrefectFuture.result" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Wait for the run to finish and return the final state.</p>
+        <p>Wait for the run to finish and return the final state.</p>
 <p>If the timeout is reached before the run reaches a final state, a <code>TimeoutError</code>
 will be raised.</p>
 <p>If <code>raise_on_failure</code> is <code>True</code> and the task run failed, the task run's
@@ -14053,7 +14054,7 @@ <h3 id="prefect.futures.PrefectFuture.wait" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Wait for the run to finish and return the final state</p>
+        <p>Wait for the run to finish and return the final state</p>
 <p>If the timeout is reached before the run reaches a final state,
 <code>None</code> is returned.</p>
 
@@ -14110,7 +14111,7 @@ <h2 id="prefect.futures.call_repr" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generate a repr for a function call as "fn_name(arg_value, kwarg_name=kwarg_value)"</p>
+        <p>Generate a repr for a function call as "fn_name(arg_value, kwarg_name=kwarg_value)"</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/futures.py</code></summary>
@@ -14174,7 +14175,7 @@ <h2 id="prefect.futures.resolve_futures_to_data" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a
+        <p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a
 new collection with the same structure with futures resolved to their results.
 Resolving futures to their results may wait for execution to complete and require
 communication with the API.</p>
@@ -14306,7 +14307,7 @@ <h2 id="prefect.futures.resolve_futures_to_states" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a
+        <p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a
 new collection with the same structure with futures resolved to their final states.
 Resolving futures to their final states may wait for execution to complete.</p>
 <p>Unsupported object types will be returned without modification.</p>
diff --git a/versions/unreleased/api-ref/prefect/infrastructure/index.html b/versions/unreleased/api-ref/prefect/infrastructure/index.html
index 363d6e30a8..917b796daf 100644
--- a/versions/unreleased/api-ref/prefect/infrastructure/index.html
+++ b/versions/unreleased/api-ref/prefect/infrastructure/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13695,7 +13696,7 @@ <h2 id="prefect.infrastructure.DockerContainer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>Runs a command in a container.</p>
+        <p>Runs a command in a container.</p>
 <p>Requires a Docker Engine to be connectable. Docker settings will be retrieved from
 the environment.</p>
 <p>Click <a href="https://docs.prefect.io/guides/deployment/docker">here</a> to see a tutorial.</p>
@@ -13893,7 +13894,7 @@ <h2 id="prefect.infrastructure.DockerContainer" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4 id="prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api">Connecting to a locally hosted Prefect API<a class="headerlink" href="#prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api" title="Permanent link">&para;</a></h4>
+        <h4 id="prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api">Connecting to a locally hosted Prefect API<a class="headerlink" href="#prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api" title="Permanent link">&para;</a></h4>
 <p>If using a local API URL on Linux, we will update the network mode default to 'host'
 to enable connectivity. If using another OS or an alternative network mode is used,
 we will replace 'localhost' in the API URL with 'host.docker.internal'. Generally,
@@ -15201,7 +15202,7 @@ <h2 id="prefect.infrastructure.DockerContainerResult" class="doc doc-heading">
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>Contains information about a completed Docker container</p>
+        <p>Contains information about a completed Docker container</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/infrastructure/container.py</code></summary>
@@ -15802,7 +15803,7 @@ <h3 id="prefect.infrastructure.Infrastructure.prepare_for_flow_run" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Return an infrastructure block that is prepared to execute a flow run.</p>
+        <p>Return an infrastructure block that is prepared to execute a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/base.py</code></summary>
@@ -15890,7 +15891,7 @@ <h3 id="prefect.infrastructure.Infrastructure.preview" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>View a preview of the infrastructure that would be run.</p>
+        <p>View a preview of the infrastructure that would be run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/base.py</code></summary>
@@ -15924,7 +15925,7 @@ <h3 id="prefect.infrastructure.Infrastructure.publish_as_work_pool" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Creates a work pool configured to use the given block as the job creator.</p>
+        <p>Creates a work pool configured to use the given block as the job creator.</p>
 <p>Used to migrate from a agents setup to a worker setup.</p>
 
 
@@ -16114,7 +16115,7 @@ <h3 id="prefect.infrastructure.Infrastructure.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run the infrastructure.</p>
+        <p>Run the infrastructure.</p>
 <p>If provided a <code>task_status</code>, the status will be reported as started when the
 infrastructure is successfully created. The status return value will be an
 identifier for the infrastructure.</p>
@@ -16185,7 +16186,7 @@ <h2 id="prefect.infrastructure.KubernetesClusterConfig" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Stores configuration for interaction with Kubernetes clusters.</p>
+        <p>Stores configuration for interaction with Kubernetes clusters.</p>
 <p>See <code>from_file</code> for creation.</p>
 
 
@@ -16444,7 +16445,7 @@ <h3 id="prefect.infrastructure.KubernetesClusterConfig.configure_client" class="
 
     <div class="doc doc-contents ">
 
-      <p>Activates this cluster configuration by loading the configuration into the
+        <p>Activates this cluster configuration by loading the configuration into the
 Kubernetes Python client. After calling this, Kubernetes API clients can use
 this config's context.</p>
 
@@ -16488,7 +16489,7 @@ <h3 id="prefect.infrastructure.KubernetesClusterConfig.from_file" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a cluster config from the a Kubernetes config file.</p>
+        <p>Create a cluster config from the a Kubernetes config file.</p>
 <p>By default, the current context in the default Kubernetes config file will be
 used.</p>
 <p>An alternative file or context may be specified.</p>
@@ -16584,7 +16585,7 @@ <h3 id="prefect.infrastructure.KubernetesClusterConfig.get_api_client" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Returns a Kubernetes API client for this cluster config.</p>
+        <p>Returns a Kubernetes API client for this cluster config.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/blocks/kubernetes.py</code></summary>
@@ -16631,7 +16632,7 @@ <h2 id="prefect.infrastructure.KubernetesJob" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>Runs a command as a Kubernetes Job.</p>
+        <p>Runs a command as a Kubernetes Job.</p>
 <p>For a guided tutorial, see <a href="https://medium.com/the-prefect-blog/how-to-use-kubernetes-with-prefect-419b2e8b8cb2/">How to use Kubernetes with Prefect</a>.
 For more information, including examples for customizing the resulting manifest, see <a href="https://docs.prefect.io/concepts/infrastructure/#kubernetesjob"><code>KubernetesJob</code> infrastructure concepts</a>.</p>
 
@@ -18540,7 +18541,7 @@ <h3 id="prefect.infrastructure.KubernetesJob.base_job_manifest" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Produces the bare minimum allowed Job manifest</p>
+        <p>Produces the bare minimum allowed Job manifest</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/kubernetes.py</code></summary>
@@ -18606,7 +18607,7 @@ <h3 id="prefect.infrastructure.KubernetesJob.build_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Builds the Kubernetes Job Manifest</p>
+        <p>Builds the Kubernetes Job Manifest</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/kubernetes.py</code></summary>
@@ -18642,7 +18643,7 @@ <h3 id="prefect.infrastructure.KubernetesJob.customize_from_file" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Load an RFC 6902 JSON patch from a YAML or JSON file.</p>
+        <p>Load an RFC 6902 JSON patch from a YAML or JSON file.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/kubernetes.py</code></summary>
@@ -18676,7 +18677,7 @@ <h3 id="prefect.infrastructure.KubernetesJob.job_from_file" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Load a Kubernetes Job manifest from a YAML or JSON file.</p>
+        <p>Load a Kubernetes Job manifest from a YAML or JSON file.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/infrastructure/kubernetes.py</code></summary>
@@ -18719,7 +18720,7 @@ <h2 id="prefect.infrastructure.KubernetesJobResult" class="doc doc-heading">
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed Kubernetes Job</p>
+        <p>Contains information about the final state of a completed Kubernetes Job</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/infrastructure/kubernetes.py</code></summary>
@@ -18765,7 +18766,7 @@ <h2 id="prefect.infrastructure.Process" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>Run a command in a new process.</p>
+        <p>Run a command in a new process.</p>
 <p>Current environment variables and Prefect settings will be included in the created
 process. Configured environment variables will override any current environment
 variables.</p>
@@ -19353,7 +19354,7 @@ <h2 id="prefect.infrastructure.ProcessResult" class="doc doc-heading">
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/infrastructure/process.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/input/actions/index.html b/versions/unreleased/api-ref/prefect/input/actions/index.html
index 09aac0d4eb..15c5c39218 100644
--- a/versions/unreleased/api-ref/prefect/input/actions/index.html
+++ b/versions/unreleased/api-ref/prefect/input/actions/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h2 id="prefect.input.actions.create_flow_run_input" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new flow run input. The given <code>value</code> will be serialized to JSON
+        <p>Create a new flow run input. The given <code>value</code> will be serialized to JSON
 and stored as a flow run input value.</p>
 
 
@@ -13425,7 +13426,7 @@ <h2 id="prefect.input.actions.delete_flow_run_input" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run input.</p>
+        <p>Delete a flow run input.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13522,7 +13523,7 @@ <h2 id="prefect.input.actions.read_flow_run_input" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read a flow run input.</p>
+        <p>Read a flow run input.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/input/run_input/index.html b/versions/unreleased/api-ref/prefect/input/run_input/index.html
index 8531af6f53..82ad1e031f 100644
--- a/versions/unreleased/api-ref/prefect/input/run_input/index.html
+++ b/versions/unreleased/api-ref/prefect/input/run_input/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13483,7 +13484,7 @@ <h1 id="prefect.input.run_input" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This module contains functions that allow sending type-checked <code>RunInput</code> data
+        <p>This module contains functions that allow sending type-checked <code>RunInput</code> data
 to flows at runtime. Flows can send back responses, establishing two-way
 channels with senders. These functions are particularly useful for systems that
 require ongoing data transfer or need to react to input quickly.
@@ -13712,7 +13713,7 @@ <h3 id="prefect.input.run_input.AutomaticRunInput.load" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load the run input response from the given key.</p>
+        <p>Load the run input response from the given key.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13803,7 +13804,7 @@ <h3 id="prefect.input.run_input.AutomaticRunInput.subclass_from_type" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a new <code>AutomaticRunInput</code> subclass from the given type.</p>
+        <p>Create a new <code>AutomaticRunInput</code> subclass from the given type.</p>
 <p>This method uses the type's name as a key prefix to identify related
 flow run inputs. This helps in ensuring that values saved under a type
 (like List[int]) are retrievable under the generic type name (like "list").</p>
@@ -14297,7 +14298,7 @@ <h3 id="prefect.input.run_input.RunInput.load" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load the run input response from the given key.</p>
+        <p>Load the run input response from the given key.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14404,7 +14405,7 @@ <h3 id="prefect.input.run_input.RunInput.load_from_flow_run_input" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Load the run input from a FlowRunInput object.</p>
+        <p>Load the run input from a FlowRunInput object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14488,7 +14489,7 @@ <h3 id="prefect.input.run_input.RunInput.save" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Save the run input response to the given key.</p>
+        <p>Save the run input response to the given key.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14609,7 +14610,7 @@ <h3 id="prefect.input.run_input.RunInput.subclass_from_base_model_type" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a new <code>RunInput</code> subclass from the given <code>pydantic.BaseModel</code>
+        <p>Create a new <code>RunInput</code> subclass from the given <code>pydantic.BaseModel</code>
 subclass.</p>
 
 
@@ -14690,7 +14691,7 @@ <h3 id="prefect.input.run_input.RunInput.with_initial_data" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Create a new <code>RunInput</code> subclass with the given initial data as field
+        <p>Create a new <code>RunInput</code> subclass with the given initial data as field
 defaults.</p>
 
 
@@ -14808,7 +14809,7 @@ <h2 id="prefect.input.run_input.keyset_from_base_key" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the keyset for the given base key.</p>
+        <p>Get the keyset for the given base key.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14912,7 +14913,7 @@ <h2 id="prefect.input.run_input.keyset_from_paused_state" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Get the keyset for the given Paused state.</p>
+        <p>Get the keyset for the given Paused state.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14989,7 +14990,7 @@ <h2 id="prefect.input.run_input.run_input_subclass_from_type" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Create a new <code>RunInput</code> subclass from the given type.</p>
+        <p>Create a new <code>RunInput</code> subclass from the given type.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/input/run_input.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/logging/configuration/index.html b/versions/unreleased/api-ref/prefect/logging/configuration/index.html
index 39cd22d610..6e7bb8aed4 100644
--- a/versions/unreleased/api-ref/prefect/logging/configuration/index.html
+++ b/versions/unreleased/api-ref/prefect/logging/configuration/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13262,7 +13263,7 @@ <h2 id="prefect.logging.configuration.load_logging_config" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Loads logging configuration from a path allowing override from the environment</p>
+        <p>Loads logging configuration from a path allowing override from the environment</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/configuration.py</code></summary>
@@ -13348,7 +13349,7 @@ <h2 id="prefect.logging.configuration.setup_logging" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sets up logging.</p>
+        <p>Sets up logging.</p>
 <p>Returns the config used.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/logging/formatters/index.html b/versions/unreleased/api-ref/prefect/logging/formatters/index.html
index 87c982c5d0..69b08feeee 100644
--- a/versions/unreleased/api-ref/prefect/logging/formatters/index.html
+++ b/versions/unreleased/api-ref/prefect/logging/formatters/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13266,7 +13267,7 @@ <h2 id="prefect.logging.formatters.JsonFormatter" class="doc doc-heading">
               Bases: <code><span title="logging.Formatter">Formatter</span></code></p>
 
 
-      <p>Formats log records as a JSON string.</p>
+        <p>Formats log records as a JSON string.</p>
 <p>The format may be specified as "pretty" to format the JSON with indents and
 newlines.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/logging/handlers/index.html b/versions/unreleased/api-ref/prefect/logging/handlers/index.html
index 1d4b1b48d4..a6874a5ac0 100644
--- a/versions/unreleased/api-ref/prefect/logging/handlers/index.html
+++ b/versions/unreleased/api-ref/prefect/logging/handlers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13366,7 +13367,7 @@ <h2 id="prefect.logging.handlers.APILogHandler" class="doc doc-heading">
               Bases: <code><span title="logging.Handler">Handler</span></code></p>
 
 
-      <p>A logging handler that sends logs to the Prefect API.</p>
+        <p>A logging handler that sends logs to the Prefect API.</p>
 <p>Sends log records to the <code>APILogWorker</code> which manages sending batches of logs in
 the background.</p>
 
@@ -13721,7 +13722,7 @@ <h3 id="prefect.logging.handlers.APILogHandler.aflush" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until
+        <p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until
 completion.</p>
 <p>If called in a synchronous context, will only block up to 5s before returning.</p>
 
@@ -13775,7 +13776,7 @@ <h3 id="prefect.logging.handlers.APILogHandler.emit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Send a log to the <code>APILogWorker</code></p>
+        <p>Send a log to the <code>APILogWorker</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/handlers.py</code></summary>
@@ -13837,7 +13838,7 @@ <h3 id="prefect.logging.handlers.APILogHandler.flush" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until
+        <p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until
 completion.</p>
 <p>Use <code>aflush</code> from async contexts instead.</p>
 
@@ -13913,7 +13914,7 @@ <h3 id="prefect.logging.handlers.APILogHandler.prepare" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert a <code>logging.LogRecord</code> to the API <code>LogCreate</code> schema and serialize.</p>
+        <p>Convert a <code>logging.LogRecord</code> to the API <code>LogCreate</code> schema and serialize.</p>
 <p>This infers the linked flow or task run from the log record or the current
 run context.</p>
 <p>If a flow run id cannot be found, the log will be dropped.</p>
diff --git a/versions/unreleased/api-ref/prefect/logging/highlighters/index.html b/versions/unreleased/api-ref/prefect/logging/highlighters/index.html
index 50996430f7..437bc47bce 100644
--- a/versions/unreleased/api-ref/prefect/logging/highlighters/index.html
+++ b/versions/unreleased/api-ref/prefect/logging/highlighters/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13498,7 +13499,7 @@ <h2 id="prefect.logging.loggers.LogEavesdropper" class="doc doc-heading">
               Bases: <code><span title="logging.Handler">Handler</span></code></p>
 
 
-      <p>A context manager that collects logs for the duration of the context</p>
+        <p>A context manager that collects logs for the duration of the context</p>
 <div class="codehilite"><pre><span></span><code><span class="n">Example</span><span class="p">:</span>
 
 <span class="w">    </span><span class="err">```</span><span class="n">python</span>
@@ -13659,7 +13660,7 @@ <h3 id="prefect.logging.loggers.LogEavesdropper.emit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The logging.Handler implementation, not intended to be called directly.</p>
+        <p>The logging.Handler implementation, not intended to be called directly.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -13685,7 +13686,7 @@ <h3 id="prefect.logging.loggers.LogEavesdropper.text" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return the collected logs as a single newline-delimited string</p>
+        <p>Return the collected logs as a single newline-delimited string</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -13724,7 +13725,7 @@ <h2 id="prefect.logging.loggers.PrefectLogAdapter" class="doc doc-heading">
               Bases: <code><span title="logging.LoggerAdapter">LoggerAdapter</span></code></p>
 
 
-      <p>Adapter that ensures extra kwargs are passed through correctly; without this
+        <p>Adapter that ensures extra kwargs are passed through correctly; without this
 the <code>extra</code> fields set on the adapter would overshadow any provided on a
 log-by-log basis.</p>
 <p>See https://bugs.python.org/issue32732 — the Python team has declared that this is
@@ -13854,7 +13855,7 @@ <h2 id="prefect.logging.loggers.disable_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a logger by name and disables it within the context manager.
+        <p>Get a logger by name and disables it within the context manager.
 Upon exiting the context manager, the logger is returned to its
 original state.</p>
 
@@ -13912,7 +13913,7 @@ <h2 id="prefect.logging.loggers.disable_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them
+        <p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them
 within the context manager. Upon exiting the context manager, both loggers
 are returned to its original state.</p>
 
@@ -13952,7 +13953,7 @@ <h2 id="prefect.logging.loggers.flow_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run logger with the run's metadata attached.</p>
+        <p>Create a flow run logger with the run's metadata attached.</p>
 <p>Additional keyword arguments can be provided to attach custom data to the log
 records.</p>
 <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p>
@@ -14027,7 +14028,7 @@ <h2 id="prefect.logging.loggers.get_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the
+        <p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the
 <code>prefect</code> package.</p>
 <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs.
 By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p>
@@ -14102,7 +14103,7 @@ <h2 id="prefect.logging.loggers.get_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a Prefect logger for the current task run or flow run.</p>
+        <p>Get a Prefect logger for the current task run or flow run.</p>
 <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>.
 Contextual data about the run will be attached to the log records.</p>
 <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to
@@ -14312,7 +14313,7 @@ <h2 id="prefect.logging.loggers.patch_print" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p>
+        <p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -14360,7 +14361,7 @@ <h2 id="prefect.logging.loggers.print_as_log" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p>
+        <p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p>
 <p>If no run is active, <code>print</code> will behave as if it were not patched.</p>
 <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will
 not be forwarded to the Prefect logger either.</p>
@@ -14439,7 +14440,7 @@ <h2 id="prefect.logging.loggers.task_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run logger with the run's metadata attached.</p>
+        <p>Create a task run logger with the run's metadata attached.</p>
 <p>Additional keyword arguments can be provided to attach custom data to the log
 records.</p>
 <p>If the task run context is available, see <code>get_run_logger</code> instead.</p>
diff --git a/versions/unreleased/api-ref/prefect/logging/loggers/index.html b/versions/unreleased/api-ref/prefect/logging/loggers/index.html
index 4bc0c0638f..18644712be 100644
--- a/versions/unreleased/api-ref/prefect/logging/loggers/index.html
+++ b/versions/unreleased/api-ref/prefect/logging/loggers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13498,7 +13499,7 @@ <h2 id="prefect.logging.loggers.LogEavesdropper" class="doc doc-heading">
               Bases: <code><span title="logging.Handler">Handler</span></code></p>
 
 
-      <p>A context manager that collects logs for the duration of the context</p>
+        <p>A context manager that collects logs for the duration of the context</p>
 <div class="codehilite"><pre><span></span><code><span class="n">Example</span><span class="p">:</span>
 
 <span class="w">    </span><span class="err">```</span><span class="n">python</span>
@@ -13659,7 +13660,7 @@ <h3 id="prefect.logging.loggers.LogEavesdropper.emit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The logging.Handler implementation, not intended to be called directly.</p>
+        <p>The logging.Handler implementation, not intended to be called directly.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -13685,7 +13686,7 @@ <h3 id="prefect.logging.loggers.LogEavesdropper.text" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return the collected logs as a single newline-delimited string</p>
+        <p>Return the collected logs as a single newline-delimited string</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -13724,7 +13725,7 @@ <h2 id="prefect.logging.loggers.PrefectLogAdapter" class="doc doc-heading">
               Bases: <code><span title="logging.LoggerAdapter">LoggerAdapter</span></code></p>
 
 
-      <p>Adapter that ensures extra kwargs are passed through correctly; without this
+        <p>Adapter that ensures extra kwargs are passed through correctly; without this
 the <code>extra</code> fields set on the adapter would overshadow any provided on a
 log-by-log basis.</p>
 <p>See https://bugs.python.org/issue32732 — the Python team has declared that this is
@@ -13854,7 +13855,7 @@ <h2 id="prefect.logging.loggers.disable_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a logger by name and disables it within the context manager.
+        <p>Get a logger by name and disables it within the context manager.
 Upon exiting the context manager, the logger is returned to its
 original state.</p>
 
@@ -13912,7 +13913,7 @@ <h2 id="prefect.logging.loggers.disable_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them
+        <p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them
 within the context manager. Upon exiting the context manager, both loggers
 are returned to its original state.</p>
 
@@ -13952,7 +13953,7 @@ <h2 id="prefect.logging.loggers.flow_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run logger with the run's metadata attached.</p>
+        <p>Create a flow run logger with the run's metadata attached.</p>
 <p>Additional keyword arguments can be provided to attach custom data to the log
 records.</p>
 <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p>
@@ -14027,7 +14028,7 @@ <h2 id="prefect.logging.loggers.get_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the
+        <p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the
 <code>prefect</code> package.</p>
 <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs.
 By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p>
@@ -14102,7 +14103,7 @@ <h2 id="prefect.logging.loggers.get_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a Prefect logger for the current task run or flow run.</p>
+        <p>Get a Prefect logger for the current task run or flow run.</p>
 <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>.
 Contextual data about the run will be attached to the log records.</p>
 <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to
@@ -14312,7 +14313,7 @@ <h2 id="prefect.logging.loggers.patch_print" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p>
+        <p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/logging/loggers.py</code></summary>
@@ -14360,7 +14361,7 @@ <h2 id="prefect.logging.loggers.print_as_log" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p>
+        <p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p>
 <p>If no run is active, <code>print</code> will behave as if it were not patched.</p>
 <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will
 not be forwarded to the Prefect logger either.</p>
@@ -14439,7 +14440,7 @@ <h2 id="prefect.logging.loggers.task_run_logger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run logger with the run's metadata attached.</p>
+        <p>Create a task run logger with the run's metadata attached.</p>
 <p>Additional keyword arguments can be provided to attach custom data to the log
 records.</p>
 <p>If the task run context is available, see <code>get_run_logger</code> instead.</p>
diff --git a/versions/unreleased/api-ref/prefect/manifests/index.html b/versions/unreleased/api-ref/prefect/manifests/index.html
index 5805e5d537..dc1f9c67ac 100644
--- a/versions/unreleased/api-ref/prefect/manifests/index.html
+++ b/versions/unreleased/api-ref/prefect/manifests/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13198,7 +13199,7 @@ <h1 id="prefect.manifests" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Manifests are portable descriptions of one or more workflows within a given directory structure.</p>
+        <p>Manifests are portable descriptions of one or more workflows within a given directory structure.</p>
 <p>They are the foundational building blocks for defining Flow Deployments.</p>
 
 
@@ -13228,7 +13229,7 @@ <h2 id="prefect.manifests.Manifest" class="doc doc-heading">
               Bases: <code><span title="prefect.pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>A JSON representation of a flow.</p>
+        <p>A JSON representation of a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/manifests.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/runner/runner/index.html b/versions/unreleased/api-ref/prefect/runner/runner/index.html
index c591d0d2eb..0fe56cc10d 100644
--- a/versions/unreleased/api-ref/prefect/runner/runner/index.html
+++ b/versions/unreleased/api-ref/prefect/runner/runner/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13405,7 +13406,7 @@ <h1 id="prefect.runner.runner" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Runners are responsible for managing the execution of deployments created and managed by
+        <p>Runners are responsible for managing the execution of deployments created and managed by
 either <code>flow.serve</code> or the <code>serve</code> utility.</p>
 
 
@@ -15649,7 +15650,7 @@ <h3 id="prefect.runner.runner.Runner.add_deployment" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Registers the deployment with the Prefect API and will monitor for work once
+        <p>Registers the deployment with the Prefect API and will monitor for work once
 the runner is started.</p>
 
 
@@ -15743,7 +15744,7 @@ <h3 id="prefect.runner.runner.Runner.add_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Provides a flow to the runner to be run based on the provided configuration.</p>
+        <p>Provides a flow to the runner to be run based on the provided configuration.</p>
 <p>Will create a deployment for the provided flow and register the deployment
 with the runner.</p>
 
@@ -16138,7 +16139,7 @@ <h3 id="prefect.runner.runner.Runner.execute_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a single flow run with the given ID.</p>
+        <p>Executes a single flow run with the given ID.</p>
 <p>Execution will wait to monitor for cancellation requests. Exits once
 the flow run process has exited.</p>
 
@@ -16260,7 +16261,7 @@ <h3 id="prefect.runner.runner.Runner.execute_in_background" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Executes a function in the background.</p>
+        <p>Executes a function in the background.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/runner.py</code></summary>
@@ -16292,7 +16293,7 @@ <h3 id="prefect.runner.runner.Runner.handle_sigterm" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gracefully shuts down the runner when a SIGTERM is received.</p>
+        <p>Gracefully shuts down the runner when a SIGTERM is received.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/runner.py</code></summary>
@@ -16328,7 +16329,7 @@ <h3 id="prefect.runner.runner.Runner.has_slots_available" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Determine if the flow run limit has been reached.</p>
+        <p>Determine if the flow run limit has been reached.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -16393,7 +16394,7 @@ <h3 id="prefect.runner.runner.Runner.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Starts a runner.</p>
+        <p>Starts a runner.</p>
 <p>The runner will begin monitoring for and executing any scheduled work for all added flows.</p>
 
 
@@ -16667,7 +16668,7 @@ <h3 id="prefect.runner.runner.Runner.stop" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Stops the runner's polling cycle.</p>
+        <p>Stops the runner's polling cycle.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/runner.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/runner/server/index.html b/versions/unreleased/api-ref/prefect/runner/server/index.html
index f47d22450b..ee2aa0381e 100644
--- a/versions/unreleased/api-ref/prefect/runner/server/index.html
+++ b/versions/unreleased/api-ref/prefect/runner/server/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h2 id="prefect.runner.server.build_server" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Build a FastAPI server for a runner.</p>
+        <p>Build a FastAPI server for a runner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13443,7 +13444,7 @@ <h2 id="prefect.runner.server.get_subflow_schemas" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load available subflow schemas by filtering for only those subflows in the
+        <p>Load available subflow schemas by filtering for only those subflows in the
 deployment entrypoint's import space.</p>
 
             <details class="quote">
@@ -13500,7 +13501,7 @@ <h2 id="prefect.runner.server.start_webserver" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run a FastAPI server for a runner.</p>
+        <p>Run a FastAPI server for a runner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/runner/storage/index.html b/versions/unreleased/api-ref/prefect/runner/storage/index.html
index 223a8691d7..d5dc62af32 100644
--- a/versions/unreleased/api-ref/prefect/runner/storage/index.html
+++ b/versions/unreleased/api-ref/prefect/runner/storage/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13642,7 +13643,7 @@ <h2 id="prefect.runner.storage.BlockStorageAdapter" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>A storage adapter for a storage block object to allow it to be used as a
+        <p>A storage adapter for a storage block object to allow it to be used as a
 runner storage object.</p>
 
               <details class="quote">
@@ -13811,7 +13812,7 @@ <h2 id="prefect.runner.storage.GitRepository" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Pulls the contents of a git repository to the local filesystem.</p>
+        <p>Pulls the contents of a git repository to the local filesystem.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14411,7 +14412,7 @@ <h3 id="prefect.runner.storage.GitRepository.pull_code" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls the contents of the configured repository to the local filesystem.</p>
+        <p>Pulls the contents of the configured repository to the local filesystem.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/storage.py</code></summary>
@@ -14538,7 +14539,7 @@ <h2 id="prefect.runner.storage.LocalStorage" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Sets the working directory in the local filesystem.</p>
+        <p>Sets the working directory in the local filesystem.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14733,7 +14734,7 @@ <h3 id="prefect.runner.storage.LocalStorage.to_pull_step" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns a dictionary representation of the storage object that can be
+        <p>Returns a dictionary representation of the storage object that can be
 used as a deployment pull step.</p>
 
             <details class="quote">
@@ -14787,7 +14788,7 @@ <h2 id="prefect.runner.storage.RemoteStorage" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Pulls the contents of a remote storage location to the local filesystem.</p>
+        <p>Pulls the contents of a remote storage location to the local filesystem.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15284,7 +15285,7 @@ <h3 id="prefect.runner.storage.RemoteStorage.destination" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The local file path to pull contents from remote storage to.</p>
+        <p>The local file path to pull contents from remote storage to.</p>
     </div>
 
 </div>
@@ -15305,7 +15306,7 @@ <h3 id="prefect.runner.storage.RemoteStorage.pull_interval" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>The interval at which contents from remote storage should be pulled to
+        <p>The interval at which contents from remote storage should be pulled to
 local storage. If None, remote storage will perform a one-time sync.</p>
     </div>
 
@@ -15328,7 +15329,7 @@ <h3 id="prefect.runner.storage.RemoteStorage.pull_code" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls contents from remote storage to the local filesystem.</p>
+        <p>Pulls contents from remote storage to the local filesystem.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/storage.py</code></summary>
@@ -15406,7 +15407,7 @@ <h3 id="prefect.runner.storage.RemoteStorage.to_pull_step" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a dictionary representation of the storage object that can be
+        <p>Returns a dictionary representation of the storage object that can be
 used as a deployment pull step.</p>
 
             <details class="quote">
@@ -15496,7 +15497,7 @@ <h2 id="prefect.runner.storage.RunnerStorage" class="doc doc-heading">
               Bases: <code><span title="typing.Protocol">Protocol</span></code></p>
 
 
-      <p>A storage interface for a runner to use to retrieve
+        <p>A storage interface for a runner to use to retrieve
 remotely stored flow code.</p>
 
               <details class="quote">
@@ -15623,7 +15624,7 @@ <h3 id="prefect.runner.storage.RunnerStorage.destination" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The local file path to pull contents from remote storage to.</p>
+        <p>The local file path to pull contents from remote storage to.</p>
     </div>
 
 </div>
@@ -15644,7 +15645,7 @@ <h3 id="prefect.runner.storage.RunnerStorage.pull_interval" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>The interval at which contents from remote storage should be pulled to
+        <p>The interval at which contents from remote storage should be pulled to
 local storage. If None, remote storage will perform a one-time sync.</p>
     </div>
 
@@ -15667,7 +15668,7 @@ <h3 id="prefect.runner.storage.RunnerStorage.pull_code" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls contents from remote storage to the local filesystem.</p>
+        <p>Pulls contents from remote storage to the local filesystem.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/runner/storage.py</code></summary>
@@ -15697,7 +15698,7 @@ <h3 id="prefect.runner.storage.RunnerStorage.set_base_path" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Sets the base path to use when pulling contents from remote storage to
+        <p>Sets the base path to use when pulling contents from remote storage to
 local storage.</p>
 
             <details class="quote">
@@ -15730,7 +15731,7 @@ <h3 id="prefect.runner.storage.RunnerStorage.to_pull_step" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a dictionary representation of the storage object that can be
+        <p>Returns a dictionary representation of the storage object that can be
 used as a deployment pull step.</p>
 
             <details class="quote">
@@ -15772,7 +15773,7 @@ <h2 id="prefect.runner.storage.create_storage_from_source" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Creates a storage object from a URL.</p>
+        <p>Creates a storage object from a URL.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/runner/utils/index.html b/versions/unreleased/api-ref/prefect/runner/utils/index.html
index f2ca2dd34e..90528fbf63 100644
--- a/versions/unreleased/api-ref/prefect/runner/utils/index.html
+++ b/versions/unreleased/api-ref/prefect/runner/utils/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13306,7 +13307,7 @@ <h2 id="prefect.runner.utils.inject_schemas_into_openapi" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.</p>
+        <p>Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13430,7 +13431,7 @@ <h2 id="prefect.runner.utils.merge_definitions" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Integrates definitions from injected schemas into the OpenAPI components.</p>
+        <p>Integrates definitions from injected schemas into the OpenAPI components.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13535,7 +13536,7 @@ <h2 id="prefect.runner.utils.update_refs_in_schema" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Recursively replaces <code>$ref</code> with a new reference base in a schema item.</p>
+        <p>Recursively replaces <code>$ref</code> with a new reference base in a schema item.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13630,7 +13631,7 @@ <h2 id="prefect.runner.utils.update_refs_to_components" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates all <code>$ref</code> fields in the OpenAPI schema to reference the components section.</p>
+        <p>Updates all <code>$ref</code> fields in the OpenAPI schema to reference the components section.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/runtime/deployment/index.html b/versions/unreleased/api-ref/prefect/runtime/deployment/index.html
index 84ec36515b..3ab3d02d18 100644
--- a/versions/unreleased/api-ref/prefect/runtime/deployment/index.html
+++ b/versions/unreleased/api-ref/prefect/runtime/deployment/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13151,7 +13152,7 @@ <h1 id="prefect.runtime.deployment" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Access attributes of the current deployment run dynamically.</p>
+        <p>Access attributes of the current deployment run dynamically.</p>
 <p>Note that if a deployment is not currently being run, all attributes will return empty values.</p>
 <p>You can mock the runtime attributes for testing purposes by setting environment variables
 prefixed with <code>PREFECT__RUNTIME__DEPLOYMENT</code>.</p>
diff --git a/versions/unreleased/api-ref/prefect/runtime/flow_run/index.html b/versions/unreleased/api-ref/prefect/runtime/flow_run/index.html
index d2616f0e1a..934c298ab3 100644
--- a/versions/unreleased/api-ref/prefect/runtime/flow_run/index.html
+++ b/versions/unreleased/api-ref/prefect/runtime/flow_run/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13151,7 +13152,7 @@ <h1 id="prefect.runtime.flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Access attributes of the current flow run dynamically.</p>
+        <p>Access attributes of the current flow run dynamically.</p>
 <p>Note that if a flow run cannot be discovered, all attributes will return empty values.</p>
 <p>You can mock the runtime attributes for testing purposes by setting environment variables
 prefixed with <code>PREFECT__RUNTIME__FLOW_RUN</code>.</p>
diff --git a/versions/unreleased/api-ref/prefect/runtime/task_run/index.html b/versions/unreleased/api-ref/prefect/runtime/task_run/index.html
index 35d401c00c..0b015314e6 100644
--- a/versions/unreleased/api-ref/prefect/runtime/task_run/index.html
+++ b/versions/unreleased/api-ref/prefect/runtime/task_run/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13151,7 +13152,7 @@ <h1 id="prefect.runtime.task_run" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Access attributes of the current task run dynamically.</p>
+        <p>Access attributes of the current task run dynamically.</p>
 <p>Note that if a task run cannot be discovered, all attributes will return empty values.</p>
 <p>You can mock the runtime attributes for testing purposes by setting environment variables
 prefixed with <code>PREFECT__RUNTIME__TASK_RUN</code>.</p>
diff --git a/versions/unreleased/api-ref/prefect/serializers/index.html b/versions/unreleased/api-ref/prefect/serializers/index.html
index 40dcaa73c4..3dad34707a 100644
--- a/versions/unreleased/api-ref/prefect/serializers/index.html
+++ b/versions/unreleased/api-ref/prefect/serializers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13408,7 +13409,7 @@ <h1 id="prefect.serializers" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Serializer implementations for converting objects to bytes and bytes to objects.</p>
+        <p>Serializer implementations for converting objects to bytes and bytes to objects.</p>
 <p>All serializers are based on the <code>Serializer</code> class and include a <code>type</code> string that
 allows them to be referenced without referencing the actual class. For example, you
 can get often specify the <code>JSONSerializer</code> with the string "json". Some serializers
@@ -13444,7 +13445,7 @@ <h2 id="prefect.serializers.CompressedJSONSerializer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.serializers.CompressedSerializer" href="#prefect.serializers.CompressedSerializer">CompressedSerializer</a></code></p>
 
 
-      <p>A compressed serializer preconfigured to use the json serializer.</p>
+        <p>A compressed serializer preconfigured to use the json serializer.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/serializers.py</code></summary>
@@ -13502,7 +13503,7 @@ <h2 id="prefect.serializers.CompressedPickleSerializer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.serializers.CompressedSerializer" href="#prefect.serializers.CompressedSerializer">CompressedSerializer</a></code></p>
 
 
-      <p>A compressed serializer preconfigured to use the pickle serializer.</p>
+        <p>A compressed serializer preconfigured to use the pickle serializer.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/serializers.py</code></summary>
@@ -13560,7 +13561,7 @@ <h2 id="prefect.serializers.CompressedSerializer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.serializers.Serializer" href="#prefect.serializers.Serializer">Serializer</a></code></p>
 
 
-      <p>Wraps another serializer, compressing its output.
+        <p>Wraps another serializer, compressing its output.
 Uses <code>lzma</code> by default. See <code>compressionlib</code> for using alternative libraries.</p>
 
 
@@ -13719,7 +13720,7 @@ <h2 id="prefect.serializers.JSONSerializer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.serializers.Serializer" href="#prefect.serializers.Serializer">Serializer</a></code></p>
 
 
-      <p>Serializes data to JSON.</p>
+        <p>Serializes data to JSON.</p>
 <p>Input types must be compatible with the stdlib json library.</p>
 <p>Wraps the <code>json</code> library to serialize to UTF-8 bytes instead of string types.</p>
 
@@ -13877,7 +13878,7 @@ <h2 id="prefect.serializers.PickleSerializer" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.serializers.Serializer" href="#prefect.serializers.Serializer">Serializer</a></code></p>
 
 
-      <p>Serializes objects using the pickle protocol.</p>
+        <p>Serializes objects using the pickle protocol.</p>
 <ul>
 <li>Uses <code>cloudpickle</code> by default. See <code>picklelib</code> for using alternative libraries.</li>
 <li>Stores the version of the pickle library to check for compatibility during
@@ -13987,7 +13988,7 @@ <h2 id="prefect.serializers.Serializer" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code>, <code><span title="typing.Generic">Generic</span>[<span title="prefect.serializers.D">D</span>]</code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>A serializer that can encode objects of type 'D' into bytes.</p>
+        <p>A serializer that can encode objects of type 'D' into bytes.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/serializers.py</code></summary>
@@ -14096,7 +14097,7 @@ <h3 id="prefect.serializers.Serializer.dumps" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Encode the object into a blob of bytes.</p>
+        <p>Encode the object into a blob of bytes.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/serializers.py</code></summary>
@@ -14126,7 +14127,7 @@ <h3 id="prefect.serializers.Serializer.loads" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Decode the blob of bytes into an object.</p>
+        <p>Decode the blob of bytes into an object.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/serializers.py</code></summary>
@@ -14161,7 +14162,7 @@ <h2 id="prefect.serializers.prefect_json_object_decoder" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p><code>JSONDecoder.object_hook</code> for decoding objects from JSON when previously encoded
+        <p><code>JSONDecoder.object_hook</code> for decoding objects from JSON when previously encoded
 with <code>prefect_json_object_encoder</code></p>
 
             <details class="quote">
@@ -14204,7 +14205,7 @@ <h2 id="prefect.serializers.prefect_json_object_encoder" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p><code>JSONEncoder.default</code> for encoding objects into JSON with extended type support.</p>
+        <p><code>JSONEncoder.default</code> for encoding objects into JSON with extended type support.</p>
 <p>Raises a <code>TypeError</code> to fallback on other encoders on failure.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/settings/index.html b/versions/unreleased/api-ref/prefect/settings/index.html
index 33b360d041..a851e1ede1 100644
--- a/versions/unreleased/api-ref/prefect/settings/index.html
+++ b/versions/unreleased/api-ref/prefect/settings/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -17580,7 +17581,7 @@ <h1 id="prefect.settings" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect settings management.</p>
+        <p>Prefect settings management.</p>
 <p>Each setting is defined as a <code>Setting</code> type. The name of each setting is stylized in all
 caps, matching the environment variable that can be used to change the setting.</p>
 <p>All settings defined in this file are used to generate a dynamic Pydantic settings class
@@ -17637,7 +17638,7 @@ <h2 id="prefect.settings.PREFECT_HOME" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Prefect's home directory. Defaults to <code>~/.prefect</code>. This
+        <p>Prefect's home directory. Defaults to <code>~/.prefect</code>. This
 directory may be created automatically when required.</p>
     </div>
 
@@ -17659,7 +17660,7 @@ <h2 id="prefect.settings.PREFECT_EXTRA_ENTRYPOINTS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Modules for Prefect to import when Prefect is imported.</p>
+        <p>Modules for Prefect to import when Prefect is imported.</p>
 <p>Values should be separated by commas, e.g. <code>my_module,my_other_module</code>.
 Objects within modules may be specified by a ':' partition, e.g. <code>my_module:my_object</code>.
 If a callable object is provided, it will be called with no arguments on import.</p>
@@ -17683,7 +17684,7 @@ <h2 id="prefect.settings.PREFECT_DEBUG_MODE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, places the API in debug mode. This may modify
+        <p>If <code>True</code>, places the API in debug mode. This may modify
 behavior to facilitate debugging, including extra logs and other verbose
 assistance. Defaults to <code>False</code>.</p>
     </div>
@@ -17706,7 +17707,7 @@ <h2 id="prefect.settings.PREFECT_CLI_COLORS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, use colors in CLI output. If <code>False</code>,
+        <p>If <code>True</code>, use colors in CLI output. If <code>False</code>,
 output will not include colors codes. Defaults to <code>True</code>.</p>
     </div>
 
@@ -17728,7 +17729,7 @@ <h2 id="prefect.settings.PREFECT_CLI_PROMPT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, use interactive prompts in CLI commands. If <code>False</code>, no interactive
+        <p>If <code>True</code>, use interactive prompts in CLI commands. If <code>False</code>, no interactive
 prompts will be used. If <code>None</code>, the value will be dynamically determined based on
 the presence of an interactive-enabled terminal.</p>
     </div>
@@ -17751,7 +17752,7 @@ <h2 id="prefect.settings.PREFECT_CLI_WRAP_LINES" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, wrap text by inserting new lines in long lines
+        <p>If <code>True</code>, wrap text by inserting new lines in long lines
 in CLI output. If <code>False</code>, output will not be wrapped. Defaults to <code>True</code>.</p>
     </div>
 
@@ -17773,7 +17774,7 @@ <h2 id="prefect.settings.PREFECT_TEST_MODE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, places the API in test mode. This may modify
+        <p>If <code>True</code>, places the API in test mode. This may modify
 behavior to facilitate testing. Defaults to <code>False</code>.</p>
     </div>
 
@@ -17795,7 +17796,7 @@ <h2 id="prefect.settings.PREFECT_UNIT_TEST_MODE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This variable only exists to facilitate unit testing. If <code>True</code>,
+        <p>This variable only exists to facilitate unit testing. If <code>True</code>,
 code is executing in a unit test context. Defaults to <code>False</code>.</p>
     </div>
 
@@ -17817,7 +17818,7 @@ <h2 id="prefect.settings.PREFECT_UNIT_TEST_LOOP_DEBUG" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code> turns on debug mode for the unit testing event loop.
+        <p>If <code>True</code> turns on debug mode for the unit testing event loop.
 Defaults to <code>False</code>.</p>
     </div>
 
@@ -17839,7 +17840,7 @@ <h2 id="prefect.settings.PREFECT_TEST_SETTING" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This variable only exists to facilitate testing of settings.
+        <p>This variable only exists to facilitate testing of settings.
 If accessed when <code>PREFECT_TEST_MODE</code> is not set, <code>None</code> is returned.</p>
     </div>
 
@@ -17861,7 +17862,7 @@ <h2 id="prefect.settings.PREFECT_API_TLS_INSECURE_SKIP_VERIFY" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, disables SSL checking to allow insecure requests.
+        <p>If <code>True</code>, disables SSL checking to allow insecure requests.
 This is recommended only during development, e.g. when using self-signed certificates.</p>
     </div>
 
@@ -17883,7 +17884,7 @@ <h2 id="prefect.settings.PREFECT_API_SSL_CERT_FILE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This configuration settings option specifies the path to an SSL certificate file.
+        <p>This configuration settings option specifies the path to an SSL certificate file.
 When set, it allows the application to use the specified certificate for secure communication.
 If left unset, the setting will default to the value provided by the <code>SSL_CERT_FILE</code> environment variable.</p>
     </div>
@@ -17906,7 +17907,7 @@ <h2 id="prefect.settings.PREFECT_API_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If provided, the URL of a hosted Prefect API. Defaults to <code>None</code>.</p>
+        <p>If provided, the URL of a hosted Prefect API. Defaults to <code>None</code>.</p>
 <p>When using Prefect Cloud, this will include an account and workspace.</p>
     </div>
 
@@ -17928,7 +17929,7 @@ <h2 id="prefect.settings.PREFECT_SILENCE_API_URL_MISCONFIGURATION" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, disable the warning when a user accidentally misconfigure its <code>PREFECT_API_URL</code>
+        <p>If <code>True</code>, disable the warning when a user accidentally misconfigure its <code>PREFECT_API_URL</code>
 Sometimes when a user manually set <code>PREFECT_API_URL</code> to a custom url,reverse-proxy for example,
 we would like to silence this warning so we will set it to <code>FALSE</code>.</p>
     </div>
@@ -17951,7 +17952,7 @@ <h2 id="prefect.settings.PREFECT_API_KEY" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>API key used to authenticate with a the Prefect API. Defaults to <code>None</code>.</p>
+        <p>API key used to authenticate with a the Prefect API. Defaults to <code>None</code>.</p>
     </div>
 
 </div>
@@ -17972,7 +17973,7 @@ <h2 id="prefect.settings.PREFECT_API_ENABLE_HTTP2" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If true, enable support for HTTP/2 for communicating with an API.</p>
+        <p>If true, enable support for HTTP/2 for communicating with an API.</p>
 <p>If the API does not support HTTP/2, this will have no effect and connections will be
 made via HTTP/1.1.</p>
     </div>
@@ -17995,7 +17996,7 @@ <h2 id="prefect.settings.PREFECT_CLIENT_MAX_RETRIES" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of retries to perform on failed HTTP requests.</p>
+        <p>The maximum number of retries to perform on failed HTTP requests.</p>
 <p>Defaults to 5.
 Set to 0 to disable retries.</p>
 <p>See <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> for details on which HTTP status codes are
@@ -18020,7 +18021,7 @@ <h2 id="prefect.settings.PREFECT_CLIENT_RETRY_JITTER_FACTOR" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>A value greater than or equal to zero to control the amount of jitter added to retried
+        <p>A value greater than or equal to zero to control the amount of jitter added to retried
 client requests. Higher values introduce larger amounts of jitter.</p>
 <p>Set to 0 to disable jitter. See <code>clamped_poisson_interval</code> for details on the how jitter
 can affect retry lengths.</p>
@@ -18044,7 +18045,7 @@ <h2 id="prefect.settings.PREFECT_CLIENT_RETRY_EXTRA_CODES" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A comma-separated list of extra HTTP status codes to retry on. Defaults to an empty string.
+        <p>A comma-separated list of extra HTTP status codes to retry on. Defaults to an empty string.
 429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
 may result in unexpected behavior.</p>
     </div>
@@ -18067,7 +18068,7 @@ <h2 id="prefect.settings.PREFECT_CLIENT_CSRF_SUPPORT_ENABLED" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Determines if CSRF token handling is active in the Prefect client for API
+        <p>Determines if CSRF token handling is active in the Prefect client for API
 requests.</p>
 <p>When enabled (<code>True</code>), the client automatically manages CSRF tokens by
 retrieving, storing, and including them in applicable state-changing requests
@@ -18095,7 +18096,7 @@ <h2 id="prefect.settings.PREFECT_CLOUD_API_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>API URL for Prefect Cloud. Used for authentication.</p>
+        <p>API URL for Prefect Cloud. Used for authentication.</p>
     </div>
 
 </div>
@@ -18116,7 +18117,7 @@ <h2 id="prefect.settings.PREFECT_CLOUD_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      
+        
     </div>
 
 </div>
@@ -18137,7 +18138,7 @@ <h2 id="prefect.settings.PREFECT_UI_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The URL for the UI. By default, this is inferred from the PREFECT_API_URL.</p>
+        <p>The URL for the UI. By default, this is inferred from the PREFECT_API_URL.</p>
 <p>When using Prefect Cloud, this will include the account and workspace.
 When using an ephemeral server, this will be <code>None</code>.</p>
     </div>
@@ -18160,7 +18161,7 @@ <h2 id="prefect.settings.PREFECT_CLOUD_UI_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The URL for the Cloud UI. By default, this is inferred from the PREFECT_CLOUD_API_URL.</p>
+        <p>The URL for the Cloud UI. By default, this is inferred from the PREFECT_CLOUD_API_URL.</p>
 
 
 <details class="note" open>
@@ -18186,7 +18187,7 @@ <h2 id="prefect.settings.PREFECT_API_REQUEST_TIMEOUT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The default timeout for requests to the API</p>
+        <p>The default timeout for requests to the API</p>
     </div>
 
 </div>
@@ -18207,7 +18208,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If enabled, warn on usage of experimental features.</p>
+        <p>If enabled, warn on usage of experimental features.</p>
     </div>
 
 </div>
@@ -18228,7 +18229,7 @@ <h2 id="prefect.settings.PREFECT_PROFILES_PATH" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The path to a profiles configuration files.</p>
+        <p>The path to a profiles configuration files.</p>
     </div>
 
 </div>
@@ -18249,7 +18250,7 @@ <h2 id="prefect.settings.PREFECT_RESULTS_DEFAULT_SERIALIZER" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>The default serializer to use when not otherwise specified.</p>
+        <p>The default serializer to use when not otherwise specified.</p>
     </div>
 
 </div>
@@ -18270,7 +18271,7 @@ <h2 id="prefect.settings.PREFECT_RESULTS_PERSIST_BY_DEFAULT" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>The default setting for persisting results when not otherwise specified. If enabled,
+        <p>The default setting for persisting results when not otherwise specified. If enabled,
 flow and task results will be persisted unless they opt out.</p>
     </div>
 
@@ -18292,7 +18293,7 @@ <h2 id="prefect.settings.PREFECT_TASKS_REFRESH_CACHE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, enables a refresh of cached results: re-executing the
+        <p>If <code>True</code>, enables a refresh of cached results: re-executing the
 task will refresh the cached results. Defaults to <code>False</code>.</p>
     </div>
 
@@ -18314,7 +18315,7 @@ <h2 id="prefect.settings.PREFECT_TASK_DEFAULT_RETRIES" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This value sets the default number of retries for all tasks.
+        <p>This value sets the default number of retries for all tasks.
 This value does not overwrite individually set retries values on tasks</p>
     </div>
 
@@ -18336,7 +18337,7 @@ <h2 id="prefect.settings.PREFECT_FLOW_DEFAULT_RETRIES" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This value sets the default number of retries for all flows.
+        <p>This value sets the default number of retries for all flows.
 This value does not overwrite individually set retries values on a flow</p>
     </div>
 
@@ -18358,7 +18359,7 @@ <h2 id="prefect.settings.PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>This value sets the retry delay seconds for all flows.
+        <p>This value sets the retry delay seconds for all flows.
 This value does not overwrite individually set retry delay seconds</p>
     </div>
 
@@ -18380,7 +18381,7 @@ <h2 id="prefect.settings.PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>This value sets the default retry delay seconds for all tasks.
+        <p>This value sets the default retry delay seconds for all tasks.
 This value does not overwrite individually set retry delay seconds</p>
     </div>
 
@@ -18402,7 +18403,7 @@ <h2 id="prefect.settings.PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS" cla
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds to wait before retrying when a task run
+        <p>The number of seconds to wait before retrying when a task run
 cannot secure a concurrency slot from the server.</p>
     </div>
 
@@ -18424,7 +18425,7 @@ <h2 id="prefect.settings.PREFECT_LOCAL_STORAGE_PATH" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The path to a block storage directory to store things in.</p>
+        <p>The path to a block storage directory to store things in.</p>
     </div>
 
 </div>
@@ -18445,7 +18446,7 @@ <h2 id="prefect.settings.PREFECT_MEMO_STORE_PATH" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The path to the memo store file.</p>
+        <p>The path to the memo store file.</p>
     </div>
 
 </div>
@@ -18466,7 +18467,7 @@ <h2 id="prefect.settings.PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Controls whether or not block auto-registration on start
+        <p>Controls whether or not block auto-registration on start
 up should be memoized. Setting to False may result in slower server start
 up times.</p>
     </div>
@@ -18489,7 +18490,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_LEVEL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The default logging level for Prefect loggers. Defaults to
+        <p>The default logging level for Prefect loggers. Defaults to
 "INFO" during normal operation. Is forced to "DEBUG" during debug mode.</p>
     </div>
 
@@ -18511,7 +18512,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_INTERNAL_LEVEL" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>The default logging level for Prefect's internal machinery loggers. Defaults to
+        <p>The default logging level for Prefect's internal machinery loggers. Defaults to
 "ERROR" during normal operation. Is forced to "DEBUG" during debug mode.</p>
     </div>
 
@@ -18533,7 +18534,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_SERVER_LEVEL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The default logging level for the Prefect API server.</p>
+        <p>The default logging level for the Prefect API server.</p>
     </div>
 
 </div>
@@ -18554,7 +18555,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_SETTINGS_PATH" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The path to a custom YAML logging configuration file. If
+        <p>The path to a custom YAML logging configuration file. If
 no file is found, the default <code>logging.yml</code> is used.
 Defaults to a logging.yml in the Prefect home directory.</p>
     </div>
@@ -18577,7 +18578,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_EXTRA_LOGGERS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Additional loggers to attach to Prefect logging at runtime.
+        <p>Additional loggers to attach to Prefect logging at runtime.
 Values should be comma separated. The handlers attached to the 'prefect' logger
 will be added to these loggers. Additionally, if the level is not set, it will
 be set to the same level as the 'prefect' logger.</p>
@@ -18601,7 +18602,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_LOG_PRINTS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If set, <code>print</code> statements in flows and tasks will be redirected to the Prefect logger
+        <p>If set, <code>print</code> statements in flows and tasks will be redirected to the Prefect logger
 for the given run. This setting can be overridden by individual tasks and flows.</p>
     </div>
 
@@ -18623,7 +18624,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_TO_API_ENABLED" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Toggles sending logs to the API.
+        <p>Toggles sending logs to the API.
 If <code>False</code>, logs sent to the API log handler will not be sent to the API.</p>
     </div>
 
@@ -18645,7 +18646,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_TO_API_BATCH_INTERVAL" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds between batched writes of logs to the API.</p>
+        <p>The number of seconds between batched writes of logs to the API.</p>
     </div>
 
 </div>
@@ -18666,7 +18667,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_TO_API_BATCH_SIZE" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>The maximum size in bytes for a batch of logs.</p>
+        <p>The maximum size in bytes for a batch of logs.</p>
     </div>
 
 </div>
@@ -18687,7 +18688,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_TO_API_MAX_LOG_SIZE" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>The maximum size in bytes for a single log.</p>
+        <p>The maximum size in bytes for a single log.</p>
     </div>
 
 </div>
@@ -18708,7 +18709,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Controls the behavior when loggers attempt to send logs to the API handler from outside
+        <p>Controls the behavior when loggers attempt to send logs to the API handler from outside
 of a flow.</p>
 <p>All logs sent to the API must be associated with a flow run. The API log handler can
 only be used outside of a flow by manually providing a flow run identifier. Logs
@@ -18740,7 +18741,7 @@ <h2 id="prefect.settings.PREFECT_SQLALCHEMY_POOL_SIZE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Controls connection pool size when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy pool size will be used.</p>
+        <p>Controls connection pool size when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy pool size will be used.</p>
     </div>
 
 </div>
@@ -18761,7 +18762,7 @@ <h2 id="prefect.settings.PREFECT_SQLALCHEMY_MAX_OVERFLOW" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Controls maximum overflow of the connection pool when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy maximum overflow value will be used.</p>
+        <p>Controls maximum overflow of the connection pool when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy maximum overflow value will be used.</p>
     </div>
 
 </div>
@@ -18782,7 +18783,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_COLORS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether to style console logs with color.</p>
+        <p>Whether to style console logs with color.</p>
     </div>
 
 </div>
@@ -18803,7 +18804,7 @@ <h2 id="prefect.settings.PREFECT_LOGGING_MARKUP" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether to interpret strings wrapped in square brackets as a style.
+        <p>Whether to interpret strings wrapped in square brackets as a style.
 This allows styles to be conveniently added to log messages, e.g.
 <code>[red]This is a red message.[/red]</code>. However, the downside is,
 if enabled, strings that contain square brackets may be inaccurately
@@ -18829,7 +18830,7 @@ <h2 id="prefect.settings.PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Threshold time in seconds for logging a warning if task parameter introspection
+        <p>Threshold time in seconds for logging a warning if task parameter introspection
 exceeds this duration. Parameter introspection can be a significant performance hit
 when the parameter is a large collection object, e.g. a large dictionary or DataFrame,
 and each element needs to be inspected. See <code>prefect.utilities.annotations.quote</code>
@@ -18856,7 +18857,7 @@ <h2 id="prefect.settings.PREFECT_AGENT_QUERY_INTERVAL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The agent loop interval, in seconds. Agents will check for new runs this often.
+        <p>The agent loop interval, in seconds. Agents will check for new runs this often.
 Defaults to <code>15</code>.</p>
     </div>
 
@@ -18878,7 +18879,7 @@ <h2 id="prefect.settings.PREFECT_AGENT_PREFETCH_SECONDS" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Agents will look for scheduled runs this many seconds in
+        <p>Agents will look for scheduled runs this many seconds in
 the future and attempt to run them. This accounts for any additional
 infrastructure spin-up time or latency in preparing a flow run. Note
 flow runs will not start before their scheduled time, even if they are
@@ -18903,7 +18904,7 @@ <h2 id="prefect.settings.PREFECT_ASYNC_FETCH_STATE_RESULT" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Determines whether <code>State.result()</code> fetches results automatically or not.
+        <p>Determines whether <code>State.result()</code> fetches results automatically or not.
 In Prefect 2.6.0, the <code>State.result()</code> method was updated to be async
 to facilitate automatic retrieval of results from storage which means when
 writing async code you must <code>await</code> the call. For backwards compatibility,
@@ -18932,7 +18933,7 @@ <h2 id="prefect.settings.PREFECT_API_BLOCKS_REGISTER_ON_START" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>If set, any block types that have been imported will be registered with the
+        <p>If set, any block types that have been imported will be registered with the
 backend on application startup. If not set, block types must be manually
 registered.</p>
     </div>
@@ -18955,7 +18956,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_PASSWORD" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Password to template into the <code>PREFECT_API_DATABASE_CONNECTION_URL</code>.
+        <p>Password to template into the <code>PREFECT_API_DATABASE_CONNECTION_URL</code>.
 This is useful if the password must be provided separately from the connection URL.
 To use this setting, you must include it in your connection URL.</p>
     </div>
@@ -18978,7 +18979,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_CONNECTION_URL" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>A database connection URL in a SQLAlchemy-compatible
+        <p>A database connection URL in a SQLAlchemy-compatible
 format. Prefect currently supports SQLite and Postgres. Note that all
 Prefect database engines must use an async driver - for SQLite, use
 <code>sqlite+aiosqlite</code> and for Postgres use <code>postgresql+asyncpg</code>.</p>
@@ -19013,7 +19014,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_ECHO" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, SQLAlchemy will log all SQL issued to the database. Defaults to <code>False</code>.</p>
+        <p>If <code>True</code>, SQLAlchemy will log all SQL issued to the database. Defaults to <code>False</code>.</p>
     </div>
 
 </div>
@@ -19034,7 +19035,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_MIGRATE_ON_START" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>If <code>True</code>, the database will be upgraded on application creation. If <code>False</code>, the database will need to be upgraded manually.</p>
+        <p>If <code>True</code>, the database will be upgraded on application creation. If <code>False</code>, the database will need to be upgraded manually.</p>
     </div>
 
 </div>
@@ -19055,7 +19056,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_TIMEOUT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A statement timeout, in seconds, applied to all database interactions made by the API.
+        <p>A statement timeout, in seconds, applied to all database interactions made by the API.
 Defaults to 10 seconds.</p>
     </div>
 
@@ -19077,7 +19078,7 @@ <h2 id="prefect.settings.PREFECT_API_DATABASE_CONNECTION_TIMEOUT" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>A connection timeout, in seconds, applied to database
+        <p>A connection timeout, in seconds, applied to database
 connections. Defaults to <code>5</code>.</p>
     </div>
 
@@ -19099,7 +19100,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The scheduler loop interval, in seconds. This determines
+        <p>The scheduler loop interval, in seconds. This determines
 how often the scheduler will attempt to schedule new flow runs, but has no
 impact on how quickly either flow runs or task runs are actually executed.
 Defaults to <code>60</code>.</p>
@@ -19123,7 +19124,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE" c
 
     <div class="doc doc-contents ">
 
-      <p>The number of deployments the scheduler will attempt to
+        <p>The number of deployments the scheduler will attempt to
 schedule in a single batch. If there are more deployments than the batch
 size, the scheduler immediately attempts to schedule the next batch; it
 does not sleep for <code>scheduler_loop_seconds</code> until it has visited every
@@ -19148,7 +19149,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>The scheduler will attempt to schedule up to this many
+        <p>The scheduler will attempt to schedule up to this many
 auto-scheduled runs in the future. Note that runs may have fewer than
 this many scheduled runs, depending on the value of
 <code>scheduler_max_scheduled_time</code>.  Defaults to <code>100</code>.</p>
@@ -19172,7 +19173,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>The scheduler will attempt to schedule at least this many
+        <p>The scheduler will attempt to schedule at least this many
 auto-scheduled runs in the future. Note that runs may have more than
 this many scheduled runs, depending on the value of
 <code>scheduler_min_scheduled_time</code>.  Defaults to <code>3</code>.</p>
@@ -19196,7 +19197,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME" clas
 
     <div class="doc doc-contents ">
 
-      <p>The scheduler will create new runs up to this far in the
+        <p>The scheduler will create new runs up to this far in the
 future. Note that this setting will take precedence over
 <code>scheduler_max_runs</code>: if a flow runs once a month and
 <code>scheduler_max_scheduled_time</code> is three months, then only three runs will be
@@ -19221,7 +19222,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME" clas
 
     <div class="doc doc-contents ">
 
-      <p>The scheduler will create new runs at least this far in the
+        <p>The scheduler will create new runs at least this far in the
 future. Note that this setting will take precedence over <code>scheduler_min_runs</code>:
 if a flow runs every hour and <code>scheduler_min_scheduled_time</code> is three hours,
 then three runs will be scheduled even if <code>scheduler_min_runs</code> is 1. Defaults to
@@ -19246,7 +19247,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE" class
 
     <div class="doc doc-contents ">
 
-      <p>The number of flow runs the scheduler will attempt to insert
+        <p>The number of flow runs the scheduler will attempt to insert
 in one batch across all deployments. If the number of flow runs to
 schedule exceeds this amount, the runs will be inserted in batches of this size.
 Defaults to <code>500</code>.</p>
@@ -19270,7 +19271,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The late runs service will look for runs to mark as late
+        <p>The late runs service will look for runs to mark as late
 this often. Defaults to <code>5</code>.</p>
     </div>
 
@@ -19292,7 +19293,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS" class="do
 
     <div class="doc doc-contents ">
 
-      <p>The late runs service will mark runs as late after they
+        <p>The late runs service will mark runs as late after they
 have exceeded their scheduled start time by this many seconds. Defaults
 to <code>5</code> seconds.</p>
     </div>
@@ -19315,7 +19316,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS" cl
 
     <div class="doc doc-contents ">
 
-      <p>The pause expiration service will look for runs to mark as failed
+        <p>The pause expiration service will look for runs to mark as failed
 this often. Defaults to <code>5</code>.</p>
     </div>
 
@@ -19337,7 +19338,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS"
 
     <div class="doc doc-contents ">
 
-      <p>The cancellation cleanup service will look non-terminal tasks and subflows
+        <p>The cancellation cleanup service will look non-terminal tasks and subflows
 this often. Defaults to <code>20</code>.</p>
     </div>
 
@@ -19359,7 +19360,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_ENABLED" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the Foreman service in the server application.</p>
+        <p>Whether or not to start the Foreman service in the server application.</p>
     </div>
 
 </div>
@@ -19380,7 +19381,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds to wait between each iteration of the Foreman loop which checks
+        <p>The number of seconds to wait between each iteration of the Foreman loop which checks
 for offline workers and updates work pool status.</p>
     </div>
 
@@ -19402,7 +19403,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTI
 
     <div class="doc doc-contents ">
 
-      <p>The number of heartbeats that must be missed before a worker is marked as offline.</p>
+        <p>The number of heartbeats that must be missed before a worker is marked as offline.</p>
     </div>
 
 </div>
@@ -19423,7 +19424,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVA
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds to use for online/offline evaluation if a worker's heartbeat
+        <p>The number of seconds to use for online/offline evaluation if a worker's heartbeat
 interval is not set.</p>
     </div>
 
@@ -19445,7 +19446,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIM
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds before a deployment is marked as not ready if it has not been
+        <p>The number of seconds before a deployment is marked as not ready if it has not been
 polled.</p>
     </div>
 
@@ -19467,7 +19468,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIM
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds before a work queue is marked as not ready if it has not been
+        <p>The number of seconds before a work queue is marked as not ready if it has not been
 polled.</p>
     </div>
 
@@ -19489,7 +19490,7 @@ <h2 id="prefect.settings.PREFECT_API_DEFAULT_LIMIT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The default limit applied to queries that can return
+        <p>The default limit applied to queries that can return
 multiple objects, such as <code>POST /flow_runs/filter</code>.</p>
     </div>
 
@@ -19511,7 +19512,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_API_HOST" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The API's host address (defaults to <code>127.0.0.1</code>).</p>
+        <p>The API's host address (defaults to <code>127.0.0.1</code>).</p>
     </div>
 
 </div>
@@ -19532,7 +19533,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_API_PORT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The API's port address (defaults to <code>4200</code>).</p>
+        <p>The API's port address (defaults to <code>4200</code>).</p>
     </div>
 
 </div>
@@ -19553,7 +19554,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_API_KEEPALIVE_TIMEOUT" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>The API's keep alive timeout (defaults to <code>5</code>).
+        <p>The API's keep alive timeout (defaults to <code>5</code>).
 Refer to https://www.uvicorn.org/settings/#timeouts for details.</p>
 <p>When the API is hosted behind a load balancer, you may want to set this to a value
 greater than the load balancer's idle timeout.</p>
@@ -19579,7 +19580,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Controls the activation of CSRF protection for the Prefect server API.</p>
+        <p>Controls the activation of CSRF protection for the Prefect server API.</p>
 <p>When enabled (<code>True</code>), the server enforces CSRF validation checks on incoming
 state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF
 token to be included in the request headers or body. This adds a layer of
@@ -19609,7 +19610,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_CSRF_TOKEN_EXPIRATION" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Specifies the duration for which a CSRF token remains valid after being issued
+        <p>Specifies the duration for which a CSRF token remains valid after being issued
 by the server.</p>
 <p>The default expiration time is set to 1 hour, which offers a reasonable
 compromise. Adjust this setting based on your specific security requirements
@@ -19634,7 +19635,7 @@ <h2 id="prefect.settings.PREFECT_UI_ENABLED" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to serve the Prefect UI.</p>
+        <p>Whether or not to serve the Prefect UI.</p>
     </div>
 
 </div>
@@ -19655,7 +19656,7 @@ <h2 id="prefect.settings.PREFECT_UI_API_URL" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The connection url for communication from the UI to the API.
+        <p>The connection url for communication from the UI to the API.
 Defaults to <code>PREFECT_API_URL</code> if set. Otherwise, the default URL is generated from
 <code>PREFECT_SERVER_API_HOST</code> and <code>PREFECT_SERVER_API_PORT</code>. If providing a custom value,
 the aforementioned settings may be templated into the given string.</p>
@@ -19679,7 +19680,7 @@ <h2 id="prefect.settings.PREFECT_SERVER_ANALYTICS_ENABLED" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
+        <p>When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
 on server startup to help us improve our product.</p>
     </div>
 
@@ -19701,7 +19702,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_SCHEDULER_ENABLED" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the scheduling service in the server application.
+        <p>Whether or not to start the scheduling service in the server application.
 If disabled, you will need to run this service separately to schedule runs for deployments.</p>
     </div>
 
@@ -19723,7 +19724,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_ENABLED" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the late runs service in the server application.
+        <p>Whether or not to start the late runs service in the server application.
 If disabled, you will need to run this service separately to have runs past their
 scheduled start time marked as late.</p>
     </div>
@@ -19746,7 +19747,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED" cl
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the flow run notifications service in the server application.
+        <p>Whether or not to start the flow run notifications service in the server application.
 If disabled, you will need to run this service separately to send flow run notifications.</p>
     </div>
 
@@ -19768,7 +19769,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED" class="
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the paused flow run expiration service in the server
+        <p>Whether or not to start the paused flow run expiration service in the server
 application. If disabled, paused flows that have timed out will remain in a Paused state
 until a resume attempt.</p>
     </div>
@@ -19791,7 +19792,7 @@ <h2 id="prefect.settings.PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of characters allowed for a task run cache key.
+        <p>The maximum number of characters allowed for a task run cache key.
 This setting cannot be changed client-side, it must be set on the server.</p>
     </div>
 
@@ -19813,7 +19814,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED" clas
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the cancellation cleanup service in the server
+        <p>Whether or not to start the cancellation cleanup service in the server
 application. If disabled, task runs and subflow runs belonging to cancelled flows may
 remain in non-terminal states.</p>
     </div>
@@ -19836,7 +19837,7 @@ <h2 id="prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>The maximum size of a flow run graph on the v2 API</p>
+        <p>The maximum size of a flow run graph on the v2 API</p>
     </div>
 
 </div>
@@ -19857,7 +19858,7 @@ <h2 id="prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of artifacts to show on a flow run graph on the v2 API</p>
+        <p>The maximum number of artifacts to show on a flow run graph on the v2 API</p>
     </div>
 
 </div>
@@ -19878,7 +19879,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS_ON_FLOW_RUN_GRAPH
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable artifacts on the flow run graph.</p>
+        <p>Whether or not to enable artifacts on the flow run graph.</p>
     </div>
 
 </div>
@@ -19899,7 +19900,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH" c
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable flow run states on the flow run graph.</p>
+        <p>Whether or not to enable flow run states on the flow run graph.</p>
     </div>
 
 </div>
@@ -19920,7 +19921,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental Prefect work pools.</p>
+        <p>Whether or not to enable experimental Prefect work pools.</p>
     </div>
 
 </div>
@@ -19941,7 +19942,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORK_POOLS" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when experimental Prefect work pools are used.</p>
+        <p>Whether or not to warn when experimental Prefect work pools are used.</p>
     </div>
 
 </div>
@@ -19962,7 +19963,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKERS" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental Prefect workers.</p>
+        <p>Whether or not to enable experimental Prefect workers.</p>
     </div>
 
 </div>
@@ -19983,7 +19984,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKERS" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when experimental Prefect workers are used.</p>
+        <p>Whether or not to warn when experimental Prefect workers are used.</p>
     </div>
 
 </div>
@@ -20004,7 +20005,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_VISUALIZE" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when experimental Prefect visualize is used.</p>
+        <p>Whether or not to warn when experimental Prefect visualize is used.</p>
     </div>
 
 </div>
@@ -20025,7 +20026,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION" clas
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental enhanced flow run cancellation.</p>
+        <p>Whether or not to enable experimental enhanced flow run cancellation.</p>
     </div>
 
 </div>
@@ -20046,7 +20047,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION" class=
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when experimental enhanced flow run cancellation is used.</p>
+        <p>Whether or not to warn when experimental enhanced flow run cancellation is used.</p>
     </div>
 
 </div>
@@ -20067,7 +20068,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_DEPLOYMENT_STATUS" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable deployment status in the UI</p>
+        <p>Whether or not to enable deployment status in the UI</p>
     </div>
 
 </div>
@@ -20088,7 +20089,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when deployment status is used.</p>
+        <p>Whether or not to warn when deployment status is used.</p>
     </div>
 
 </div>
@@ -20109,7 +20110,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable flow run input.</p>
+        <p>Whether or not to enable flow run input.</p>
     </div>
 
 </div>
@@ -20130,7 +20131,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable flow run input.</p>
+        <p>Whether or not to enable flow run input.</p>
     </div>
 
 </div>
@@ -20151,7 +20152,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_EVENTS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether to enable Prefect's server-side event features. Note that Prefect Cloud clients
+        <p>Whether to enable Prefect's server-side event features. Note that Prefect Cloud clients
 will always emit events during flow and task runs regardless of this setting.</p>
     </div>
 
@@ -20173,7 +20174,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_PROCESS_LIMIT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Maximum number of processes a runner will execute in parallel.</p>
+        <p>Maximum number of processes a runner will execute in parallel.</p>
     </div>
 
 </div>
@@ -20194,7 +20195,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_POLL_FREQUENCY" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Number of seconds a runner should wait between queries for scheduled work.</p>
+        <p>Number of seconds a runner should wait between queries for scheduled work.</p>
     </div>
 
 </div>
@@ -20215,7 +20216,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Number of missed polls before a runner is considered unhealthy by its webserver.</p>
+        <p>Number of missed polls before a runner is considered unhealthy by its webserver.</p>
     </div>
 
 </div>
@@ -20236,7 +20237,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_SERVER_HOST" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The host address the runner's webserver should bind to.</p>
+        <p>The host address the runner's webserver should bind to.</p>
     </div>
 
 </div>
@@ -20257,7 +20258,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_SERVER_PORT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The port the runner's webserver should bind to.</p>
+        <p>The port the runner's webserver should bind to.</p>
     </div>
 
 </div>
@@ -20278,7 +20279,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_SERVER_LOG_LEVEL" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The log level of the runner's webserver.</p>
+        <p>The log level of the runner's webserver.</p>
     </div>
 
 </div>
@@ -20299,7 +20300,7 @@ <h2 id="prefect.settings.PREFECT_RUNNER_SERVER_ENABLE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable the runner's webserver.</p>
+        <p>Whether or not to enable the runner's webserver.</p>
     </div>
 
 </div>
@@ -20320,7 +20321,7 @@ <h2 id="prefect.settings.PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS" class="
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of scheduled runs to create for a deployment.</p>
+        <p>The maximum number of scheduled runs to create for a deployment.</p>
     </div>
 
 </div>
@@ -20341,7 +20342,7 @@ <h2 id="prefect.settings.PREFECT_WORKER_HEARTBEAT_SECONDS" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Number of seconds a worker should wait between sending a heartbeat.</p>
+        <p>Number of seconds a worker should wait between sending a heartbeat.</p>
     </div>
 
 </div>
@@ -20362,7 +20363,7 @@ <h2 id="prefect.settings.PREFECT_WORKER_QUERY_SECONDS" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Number of seconds a worker should wait between queries for scheduled flow runs.</p>
+        <p>Number of seconds a worker should wait between queries for scheduled flow runs.</p>
     </div>
 
 </div>
@@ -20383,7 +20384,7 @@ <h2 id="prefect.settings.PREFECT_WORKER_PREFETCH_SECONDS" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The number of seconds into the future a worker should query for scheduled flow runs.
+        <p>The number of seconds into the future a worker should query for scheduled flow runs.
 Can be used to compensate for infrastructure start up time for a worker.</p>
     </div>
 
@@ -20405,7 +20406,7 @@ <h2 id="prefect.settings.PREFECT_WORKER_WEBSERVER_HOST" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The host address the worker's webserver should bind to.</p>
+        <p>The host address the worker's webserver should bind to.</p>
     </div>
 
 </div>
@@ -20426,7 +20427,7 @@ <h2 id="prefect.settings.PREFECT_WORKER_WEBSERVER_PORT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The port the worker's webserver should bind to.</p>
+        <p>The port the worker's webserver should bind to.</p>
     </div>
 
 </div>
@@ -20447,7 +20448,7 @@ <h2 id="prefect.settings.PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK" class="d
 
     <div class="doc doc-contents ">
 
-      <p>The <code>block-type/block-document</code> slug of a block to use as the default storage
+        <p>The <code>block-type/block-document</code> slug of a block to use as the default storage
 for autonomous tasks.</p>
     </div>
 
@@ -20469,7 +20470,7 @@ <h2 id="prefect.settings.PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS" clas
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to delete failed task submissions from the database.</p>
+        <p>Whether or not to delete failed task submissions from the database.</p>
     </div>
 
 </div>
@@ -20490,7 +20491,7 @@ <h2 id="prefect.settings.PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE" class
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of scheduled tasks to queue for submission.</p>
+        <p>The maximum number of scheduled tasks to queue for submission.</p>
     </div>
 
 </div>
@@ -20511,7 +20512,7 @@ <h2 id="prefect.settings.PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE" class="do
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of retries to queue for submission.</p>
+        <p>The maximum number of retries to queue for submission.</p>
     </div>
 
 </div>
@@ -20532,7 +20533,7 @@ <h2 id="prefect.settings.PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT" class="do
 
     <div class="doc doc-contents ">
 
-      <p>How long before a PENDING task are made available to another task server.  In practice,
+        <p>How long before a PENDING task are made available to another task server.  In practice,
 a task server should move a task from PENDING to RUNNING very quickly, so runs stuck in
 PENDING for a while is a sign that the task server may have crashed.</p>
     </div>
@@ -20555,7 +20556,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS" cla
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental worker webserver endpoints.</p>
+        <p>Whether or not to enable experimental worker webserver endpoints.</p>
     </div>
 
 </div>
@@ -20576,7 +20577,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental Prefect artifacts.</p>
+        <p>Whether or not to enable experimental Prefect artifacts.</p>
     </div>
 
 </div>
@@ -20597,7 +20598,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_ARTIFACTS" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when experimental Prefect artifacts are used.</p>
+        <p>Whether or not to warn when experimental Prefect artifacts are used.</p>
     </div>
 
 </div>
@@ -20618,7 +20619,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKSPACE_DASHBOARD" class=
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable the experimental workspace dashboard.</p>
+        <p>Whether or not to enable the experimental workspace dashboard.</p>
     </div>
 
 </div>
@@ -20639,7 +20640,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKSPACE_DASHBOARD" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to warn when the experimental workspace dashboard is enabled.</p>
+        <p>Whether or not to warn when the experimental workspace dashboard is enabled.</p>
     </div>
 
 </div>
@@ -20660,7 +20661,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental task scheduling.</p>
+        <p>Whether or not to enable experimental task scheduling.</p>
     </div>
 
 </div>
@@ -20681,7 +20682,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_QUEUE_STATUS" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental work queue status in-place of work queue health.</p>
+        <p>Whether or not to enable experimental work queue status in-place of work queue health.</p>
     </div>
 
 </div>
@@ -20702,7 +20703,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to enable experimental new engine.</p>
+        <p>Whether or not to enable experimental new engine.</p>
     </div>
 
 </div>
@@ -20723,7 +20724,7 @@ <h2 id="prefect.settings.PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to disable the sync_compatible decorator utility.</p>
+        <p>Whether or not to disable the sync_compatible decorator utility.</p>
     </div>
 
 </div>
@@ -20744,7 +20745,7 @@ <h2 id="prefect.settings.PREFECT_DEFAULT_RESULT_STORAGE_BLOCK" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>The <code>block-type/block-document</code> slug of a block to use as the default result storage.</p>
+        <p>The <code>block-type/block-document</code> slug of a block to use as the default result storage.</p>
     </div>
 
 </div>
@@ -20765,7 +20766,7 @@ <h2 id="prefect.settings.PREFECT_DEFAULT_WORK_POOL_NAME" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>The default work pool to deploy to.</p>
+        <p>The default work pool to deploy to.</p>
     </div>
 
 </div>
@@ -20786,7 +20787,7 @@ <h2 id="prefect.settings.PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>The default Docker namespace to use when building images.</p>
+        <p>The default Docker namespace to use when building images.</p>
 <p>Can be either an organization/username or a registry URL with an organization/username.</p>
     </div>
 
@@ -20808,7 +20809,7 @@ <h2 id="prefect.settings.PREFECT_UI_SERVE_BASE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The base URL path to serve the Prefect UI from.</p>
+        <p>The base URL path to serve the Prefect UI from.</p>
 <p>Defaults to the root path.</p>
     </div>
 
@@ -20830,7 +20831,7 @@ <h2 id="prefect.settings.PREFECT_UI_STATIC_DIRECTORY" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The directory to serve static files from. This should be used when running into permissions issues
+        <p>The directory to serve static files from. This should be used when running into permissions issues
 when attempting to serve the UI from the default directory (for example when running in a Docker container)</p>
     </div>
 
@@ -20852,7 +20853,7 @@ <h2 id="prefect.settings.PREFECT_MESSAGING_BROKER" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Which message broker implementation to use for the messaging system, should point to a
+        <p>Which message broker implementation to use for the messaging system, should point to a
 module that exports a Publisher and Consumer class.</p>
     </div>
 
@@ -20874,7 +20875,7 @@ <h2 id="prefect.settings.PREFECT_MESSAGING_CACHE" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Which cache implementation to use for the events system.  Should point to a module that
+        <p>Which cache implementation to use for the events system.  Should point to a module that
 exports a Cache class.</p>
     </div>
 
@@ -20896,7 +20897,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of labels a resource may have.</p>
+        <p>The maximum number of labels a resource may have.</p>
     </div>
 
 </div>
@@ -20917,7 +20918,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of related resources an Event may have.</p>
+        <p>The maximum number of related resources an Event may have.</p>
     </div>
 
 </div>
@@ -20938,7 +20939,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_MAXIMUM_SIZE_BYTES" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>The maximum size of an Event when serialized to JSON</p>
+        <p>The maximum size of an Event when serialized to JSON</p>
     </div>
 
 </div>
@@ -20959,7 +20960,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the event debug logger service in the server application.</p>
+        <p>Whether or not to start the event debug logger service in the server application.</p>
     </div>
 
 </div>
@@ -20980,7 +20981,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_TRIGGERS_ENABLED" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the triggers service in the server application.</p>
+        <p>Whether or not to start the triggers service in the server application.</p>
     </div>
 
 </div>
@@ -21001,7 +21002,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>The amount of time to retain expired automation buckets</p>
+        <p>The amount of time to retain expired automation buckets</p>
     </div>
 
 </div>
@@ -21022,7 +21023,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_PROACTIVE_GRANULARITY" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>How frequently proactive automations are evaluated</p>
+        <p>How frequently proactive automations are evaluated</p>
     </div>
 
 </div>
@@ -21043,7 +21044,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to start the event persister service in the server application.</p>
+        <p>Whether or not to start the event persister service in the server application.</p>
     </div>
 
 </div>
@@ -21064,7 +21065,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE" class=
 
     <div class="doc doc-contents ">
 
-      <p>The number of events the event persister will attempt to insert in one batch.</p>
+        <p>The number of events the event persister will attempt to insert in one batch.</p>
     </div>
 
 </div>
@@ -21085,7 +21086,7 @@ <h2 id="prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL" cl
 
     <div class="doc doc-contents ">
 
-      <p>The maximum number of seconds between flushes of the event persister.</p>
+        <p>The maximum number of seconds between flushes of the event persister.</p>
     </div>
 
 </div>
@@ -21106,7 +21107,7 @@ <h2 id="prefect.settings.PREFECT_EVENTS_RETENTION_PERIOD" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The amount of time to retain events in the database.</p>
+        <p>The amount of time to retain events in the database.</p>
     </div>
 
 </div>
@@ -21127,7 +21128,7 @@ <h2 id="prefect.settings.PREFECT_API_EVENTS_STREAM_OUT_ENABLED" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not to allow streaming events out of via websockets.</p>
+        <p>Whether or not to allow streaming events out of via websockets.</p>
     </div>
 
 </div>
@@ -21148,7 +21149,7 @@ <h2 id="prefect.settings.PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL" class="d
 
     <div class="doc doc-contents ">
 
-      <p>How long to cache related resource data for emitting server-side vents</p>
+        <p>How long to cache related resource data for emitting server-side vents</p>
     </div>
 
 </div>
@@ -21170,7 +21171,7 @@ <h2 id="prefect.settings.Setting" class="doc doc-heading">
               Bases: <code><span title="typing.Generic">Generic</span>[<span title="prefect.settings.T">T</span>]</code></p>
 
 
-      <p>Setting definition type.</p>
+        <p>Setting definition type.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -21487,7 +21488,7 @@ <h3 id="prefect.settings.Setting.value" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current value of a setting.</p>
+        <p>Get the current value of a setting.</p>
 <p>Example:
 <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect.settings</span> <span class="kn">import</span> <span class="n">PREFECT_API_URL</span>
 <span class="n">PREFECT_API_URL</span><span class="o">.</span><span class="n">value</span><span class="p">()</span>
@@ -21533,7 +21534,7 @@ <h3 id="prefect.settings.Setting.value_from" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the value of a setting from a settings object</p>
+        <p>Get the value of a setting from a settings object</p>
 <p>Example:
 <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect.settings</span> <span class="kn">import</span> <span class="n">get_default_settings</span>
 <span class="n">PREFECT_API_URL</span><span class="o">.</span><span class="n">value_from</span><span class="p">(</span><span class="n">get_default_settings</span><span class="p">())</span>
@@ -21650,7 +21651,7 @@ <h2 id="prefect.settings.Settings" class="doc doc-heading">
               Bases: <code><span title="prefect.settings.SettingsFieldsMixin">SettingsFieldsMixin</span></code></p>
 
 
-      <p>Contains validated Prefect settings.</p>
+        <p>Contains validated Prefect settings.</p>
 <p>Settings should be accessed using the relevant <code>Setting</code> object. For example:
 <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect.settings</span> <span class="kn">import</span> <span class="n">PREFECT_HOME</span>
 <span class="n">PREFECT_HOME</span><span class="o">.</span><span class="n">value</span><span class="p">()</span>
@@ -21998,7 +21999,7 @@ <h3 id="prefect.settings.Settings.value_of" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve a setting's value.</p>
+        <p>Retrieve a setting's value.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -22034,7 +22035,7 @@ <h3 id="prefect.settings.Settings.post_root_validators" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Add root validation functions for settings here.</p>
+        <p>Add root validation functions for settings here.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -22080,7 +22081,7 @@ <h3 id="prefect.settings.Settings.with_obfuscated_secrets" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a copy of this settings object with secret setting values obfuscated.</p>
+        <p>Returns a copy of this settings object with secret setting values obfuscated.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -22134,7 +22135,7 @@ <h3 id="prefect.settings.Settings.hash_key" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a hash key for the settings object.  This is needed since some
+        <p>Return a hash key for the settings object.  This is needed since some
 settings may be unhashable.  An example is lists.</p>
 
             <details class="quote">
@@ -22169,7 +22170,7 @@ <h3 id="prefect.settings.Settings.to_environment_variables" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Convert the settings object to environment variables.</p>
+        <p>Convert the settings object to environment variables.</p>
 <p>Note that setting values will not be run through their <code>value_callback</code> allowing
 dynamic resolution to occur when loaded from the returned environment.</p>
 
@@ -22362,7 +22363,7 @@ <h2 id="prefect.settings.Profile" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>A user profile containing settings.</p>
+        <p>A user profile containing settings.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -22487,7 +22488,7 @@ <h3 id="prefect.settings.Profile.validate_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Validate the settings contained in this profile.</p>
+        <p>Validate the settings contained in this profile.</p>
 
 
 <p><span class="doc-section-title">Raises:</span></p>
@@ -22554,7 +22555,7 @@ <h3 id="prefect.settings.Profile.convert_deprecated_renamed_settings" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Update settings in place to replace deprecated settings with new settings when
+        <p>Update settings in place to replace deprecated settings with new settings when
 renamed.</p>
 <p>Returns a list of tuples with the old and new setting.</p>
 
@@ -22625,7 +22626,7 @@ <h2 id="prefect.settings.ProfilesCollection" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>"
+        <p>"
 A utility class for working with a collection of profiles.</p>
 <p>Profiles in the collection must have unique names.</p>
 <p>The collection may store the name of the active profile.</p>
@@ -22962,7 +22963,7 @@ <h3 id="prefect.settings.ProfilesCollection.names" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a set of profile names in this collection.</p>
+        <p>Return a set of profile names in this collection.</p>
     </div>
 
 </div>
@@ -22983,7 +22984,7 @@ <h3 id="prefect.settings.ProfilesCollection.active_profile" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the active profile in this collection.</p>
+        <p>Retrieve the active profile in this collection.</p>
     </div>
 
 </div>
@@ -23001,7 +23002,7 @@ <h3 id="prefect.settings.ProfilesCollection.set_active" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set the active profile name in the collection.</p>
+        <p>Set the active profile name in the collection.</p>
 <p>A null value may be passed to indicate that this collection does not determine
 the active profile.</p>
 
@@ -23043,7 +23044,7 @@ <h3 id="prefect.settings.ProfilesCollection.update_profile" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Add a profile to the collection or update the existing on if the name is already
+        <p>Add a profile to the collection or update the existing on if the name is already
 present in this collection.</p>
 <p>If updating an existing profile, the settings will be merged. Settings can
 be dropped from the existing profile by setting them to <code>None</code> in the new
@@ -23142,7 +23143,7 @@ <h3 id="prefect.settings.ProfilesCollection.add_profile" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Add a profile to the collection.</p>
+        <p>Add a profile to the collection.</p>
 <p>If the profile name already exists, an exception will be raised.</p>
 
             <details class="quote">
@@ -23187,7 +23188,7 @@ <h3 id="prefect.settings.ProfilesCollection.remove_profile" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Remove a profile from the collection.</p>
+        <p>Remove a profile from the collection.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23217,7 +23218,7 @@ <h3 id="prefect.settings.ProfilesCollection.without_profile_source" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Remove profiles that were loaded from a given path.</p>
+        <p>Remove profiles that were loaded from a given path.</p>
 <p>Returns a new collection.</p>
 
             <details class="quote">
@@ -23275,7 +23276,7 @@ <h2 id="prefect.settings.get_extra_loggers" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p><code>value_callback</code> for <code>PREFECT_LOGGING_EXTRA_LOGGERS</code>that parses the CSV string into a
+        <p><code>value_callback</code> for <code>PREFECT_LOGGING_EXTRA_LOGGERS</code>that parses the CSV string into a
 list and trims whitespace from logger names.</p>
 
             <details class="quote">
@@ -23308,7 +23309,7 @@ <h2 id="prefect.settings.debug_mode_log_level" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p><code>value_callback</code> for <code>PREFECT_LOGGING_LEVEL</code> that overrides the log level to DEBUG
+        <p><code>value_callback</code> for <code>PREFECT_LOGGING_LEVEL</code> that overrides the log level to DEBUG
 when debug mode is enabled.</p>
 
             <details class="quote">
@@ -23347,7 +23348,7 @@ <h2 id="prefect.settings.only_return_value_in_test_mode" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p><code>value_callback</code> for <code>PREFECT_TEST_SETTING</code> that only allows access during test mode</p>
+        <p><code>value_callback</code> for <code>PREFECT_TEST_SETTING</code> that only allows access during test mode</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23383,7 +23384,7 @@ <h2 id="prefect.settings.default_ui_api_url" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p><code>value_callback</code> for <code>PREFECT_UI_API_URL</code> that sets the default value to
+        <p><code>value_callback</code> for <code>PREFECT_UI_API_URL</code> that sets the default value to
 relative path '/api', otherwise it constructs an API URL from the API settings.</p>
 
             <details class="quote">
@@ -23428,7 +23429,7 @@ <h2 id="prefect.settings.status_codes_as_integers_in_range" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p><code>value_callback</code> for <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> that ensures status codes
+        <p><code>value_callback</code> for <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> that ensures status codes
 are integers in the range 100-599.</p>
 
             <details class="quote">
@@ -23485,7 +23486,7 @@ <h2 id="prefect.settings.template_with_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a <code>value_callback</code> that will template the given settings into the runtime
+        <p>Returns a <code>value_callback</code> that will template the given settings into the runtime
 value for the setting.</p>
 
             <details class="quote">
@@ -23550,7 +23551,7 @@ <h2 id="prefect.settings.max_log_size_smaller_than_batch_size" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Validator for settings asserting the batch size and match log size are compatible</p>
+        <p>Validator for settings asserting the batch size and match log size are compatible</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23596,7 +23597,7 @@ <h2 id="prefect.settings.warn_on_database_password_value_without_usage" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Validator for settings warning if the database password is set but not used.</p>
+        <p>Validator for settings warning if the database password is set but not used.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23654,7 +23655,7 @@ <h2 id="prefect.settings.warn_on_misconfigured_api_url" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Validator for settings warning if the API URL is misconfigured.</p>
+        <p>Validator for settings warning if the API URL is misconfigured.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23748,7 +23749,7 @@ <h2 id="prefect.settings.automation_settings_enabled" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not automations are enabled.</p>
+        <p>Whether or not automations are enabled.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -23784,7 +23785,7 @@ <h2 id="prefect.settings.get_current_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a settings object populated with values from the current settings context
+        <p>Returns a settings object populated with values from the current settings context
 or, if no settings context is active, the environment.</p>
 
             <details class="quote">
@@ -23829,7 +23830,7 @@ <h2 id="prefect.settings.get_settings_from_env" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a settings object populated with default values and overrides from
+        <p>Returns a settings object populated with default values and overrides from
 environment variables, ignoring any values in profiles.</p>
 <p>Calls with the same environment return a cached object instead of reconstructing
 to avoid validation overhead.</p>
@@ -23884,7 +23885,7 @@ <h2 id="prefect.settings.get_default_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a settings object populated with default values, ignoring any overrides
+        <p>Returns a settings object populated with default values, ignoring any overrides
 from environment variables or profiles.</p>
 <p>This is cached since the defaults should not change during the lifetime of the
 module.</p>
@@ -23949,7 +23950,7 @@ <h2 id="prefect.settings.temporary_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Temporarily override the current settings by entering a new profile.</p>
+        <p>Temporarily override the current settings by entering a new profile.</p>
 <p>See <code>Settings.copy_with_update</code> for details on different argument behavior.</p>
 
 
@@ -24066,7 +24067,7 @@ <h2 id="prefect.settings.load_profiles" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load all profiles from the default and current profile paths.</p>
+        <p>Load all profiles from the default and current profile paths.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -24130,7 +24131,7 @@ <h2 id="prefect.settings.load_current_profile" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load the current profile from the default and current profile paths.</p>
+        <p>Load the current profile from the default and current profile paths.</p>
 <p>This will <em>not</em> include settings from the current settings context. Only settings
 that have been persisted to the profiles file will be saved.</p>
 
@@ -24184,7 +24185,7 @@ <h2 id="prefect.settings.save_profiles" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Writes all non-default profiles to the current profiles path.</p>
+        <p>Writes all non-default profiles to the current profiles path.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -24218,7 +24219,7 @@ <h2 id="prefect.settings.load_profile" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load a single profile by name.</p>
+        <p>Load a single profile by name.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/settings.py</code></summary>
@@ -24256,7 +24257,7 @@ <h2 id="prefect.settings.update_current_profile" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Update the persisted data for the profile currently in-use.</p>
+        <p>Update the persisted data for the profile currently in-use.</p>
 <p>If the profile does not exist in the profiles file, it will be created.</p>
 <p>Given settings will be merged with the existing settings as described in
 <code>ProfilesCollection.update_profile</code>.</p>
diff --git a/versions/unreleased/api-ref/prefect/software/index.html b/versions/unreleased/api-ref/prefect/software/index.html
index 8066e7fccd..a5e8e76991 100644
--- a/versions/unreleased/api-ref/prefect/software/index.html
+++ b/versions/unreleased/api-ref/prefect/software/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/states/index.html b/versions/unreleased/api-ref/prefect/states/index.html
index 3145a3ef28..679b6e90d7 100644
--- a/versions/unreleased/api-ref/prefect/states/index.html
+++ b/versions/unreleased/api-ref/prefect/states/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13661,7 +13662,7 @@ <h2 id="prefect.states.AwaitingRetry" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>AwaitingRetry</code> states.</p>
+        <p>Convenience function for creating <code>AwaitingRetry</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13730,7 +13731,7 @@ <h2 id="prefect.states.Cancelled" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Cancelled</code> states.</p>
+        <p>Convenience function for creating <code>Cancelled</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13787,7 +13788,7 @@ <h2 id="prefect.states.Cancelling" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Cancelling</code> states.</p>
+        <p>Convenience function for creating <code>Cancelling</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13844,7 +13845,7 @@ <h2 id="prefect.states.Completed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Completed</code> states.</p>
+        <p>Convenience function for creating <code>Completed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13901,7 +13902,7 @@ <h2 id="prefect.states.Crashed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Crashed</code> states.</p>
+        <p>Convenience function for creating <code>Crashed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13958,7 +13959,7 @@ <h2 id="prefect.states.Failed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Failed</code> states.</p>
+        <p>Convenience function for creating <code>Failed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14015,7 +14016,7 @@ <h2 id="prefect.states.Late" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Late</code> states.</p>
+        <p>Convenience function for creating <code>Late</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14080,7 +14081,7 @@ <h2 id="prefect.states.Paused" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Paused</code> states.</p>
+        <p>Convenience function for creating <code>Paused</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14191,7 +14192,7 @@ <h2 id="prefect.states.Pending" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Pending</code> states.</p>
+        <p>Convenience function for creating <code>Pending</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14248,7 +14249,7 @@ <h2 id="prefect.states.Retrying" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Retrying</code> states.</p>
+        <p>Convenience function for creating <code>Retrying</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14305,7 +14306,7 @@ <h2 id="prefect.states.Running" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Running</code> states.</p>
+        <p>Convenience function for creating <code>Running</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14362,7 +14363,7 @@ <h2 id="prefect.states.Scheduled" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Scheduled</code> states.</p>
+        <p>Convenience function for creating <code>Scheduled</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14441,7 +14442,7 @@ <h2 id="prefect.states.Suspended" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Suspended</code> states.</p>
+        <p>Convenience function for creating <code>Suspended</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14529,7 +14530,7 @@ <h2 id="prefect.states.exception_to_crashed_state" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Takes an exception that occurs <em>outside</em> of user code and converts it to a
+        <p>Takes an exception that occurs <em>outside</em> of user code and converts it to a
 'Crash' exception with a 'Crashed' state.</p>
 
             <details class="quote">
@@ -14652,7 +14653,7 @@ <h2 id="prefect.states.exception_to_failed_state" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Failed</code> states from exceptions</p>
+        <p>Convenience function for creating <code>Failed</code> states from exceptions</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/states.py</code></summary>
@@ -14742,7 +14743,7 @@ <h2 id="prefect.states.get_state_exception" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>If not given a FAILED or CRASHED state, this raise a value error.</p>
+        <p>If not given a FAILED or CRASHED state, this raise a value error.</p>
 <p>If the state result is a state, its exception will be returned.</p>
 <p>If the state result is an iterable of states, the exception of the first failure
 will be returned.</p>
@@ -14922,7 +14923,7 @@ <h2 id="prefect.states.get_state_result" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the result from a state.</p>
+        <p>Get the result from a state.</p>
 <p>See <code>State.result()</code></p>
 
             <details class="quote">
@@ -15015,7 +15016,7 @@ <h2 id="prefect.states.is_state" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Check if the given object is a state instance</p>
+        <p>Check if the given object is a state instance</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/states.py</code></summary>
@@ -15065,7 +15066,7 @@ <h2 id="prefect.states.is_state_iterable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Check if a the given object is an iterable of states types</p>
+        <p>Check if a the given object is an iterable of states types</p>
 <p>Supported iterables are:
 - set
 - list
@@ -15136,7 +15137,7 @@ <h2 id="prefect.states.raise_state_exception" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a FAILED or CRASHED state, raise the contained exception.</p>
+        <p>Given a FAILED or CRASHED state, raise the contained exception.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/states.py</code></summary>
@@ -15178,7 +15179,7 @@ <h2 id="prefect.states.return_value_to_state" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a return value from a user's function, create a <code>State</code> the run should
+        <p>Given a return value from a user's function, create a <code>State</code> the run should
 be placed in.</p>
 <ul>
 <li>If data is returned, we create a 'COMPLETED' state with the data</li>
diff --git a/versions/unreleased/api-ref/prefect/task-runners/index.html b/versions/unreleased/api-ref/prefect/task-runners/index.html
index d019ff67e2..d12600f510 100644
--- a/versions/unreleased/api-ref/prefect/task-runners/index.html
+++ b/versions/unreleased/api-ref/prefect/task-runners/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13342,7 +13343,7 @@ <h1 id="prefect.task_runners" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Interface and implementations of various task runners.</p>
+        <p>Interface and implementations of various task runners.</p>
 <p><a href="/concepts/task-runners/">Task Runners</a> in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p>
 
 
@@ -13389,7 +13390,7 @@ <h1 id="prefect.task_runners" class="doc doc-heading">
 goodbye ford
 goodbye trillian
 </code></pre></div></p>
-</details>      <p>For usage details, see the <a href="/concepts/task-runners/">Task Runners</a> documentation.</p>
+</details>        <p>For usage details, see the <a href="/concepts/task-runners/">Task Runners</a> documentation.</p>
 
 
 
@@ -13651,7 +13652,7 @@ <h3 id="prefect.task_runners.BaseTaskRunner.duplicate" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a new task runner instance with the same options.</p>
+        <p>Return a new task runner instance with the same options.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/task_runners.py</code></summary>
@@ -13689,7 +13690,7 @@ <h3 id="prefect.task_runners.BaseTaskRunner.start" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Start the task runner, preparing any resources necessary for task submission.</p>
+        <p>Start the task runner, preparing any resources necessary for task submission.</p>
 <p>Children should implement <code>_start</code> to prepare and clean up resources.</p>
 
 
@@ -13786,7 +13787,7 @@ <h3 id="prefect.task_runners.BaseTaskRunner.submit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a call for execution and return a <code>PrefectFuture</code> that can be used to
+        <p>Submit a call for execution and return a <code>PrefectFuture</code> that can be used to
 get the call result.</p>
 
 
@@ -13946,7 +13947,7 @@ <h3 id="prefect.task_runners.BaseTaskRunner.wait" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a <code>PrefectFuture</code>, wait for its return state up to <code>timeout</code> seconds.
+        <p>Given a <code>PrefectFuture</code>, wait for its return state up to <code>timeout</code> seconds.
 If it is not finished after the timeout expires, <code>None</code> should be returned.</p>
 <p>Implementers should be careful to ensure that this function never returns or
 raises an exception.</p>
@@ -14002,7 +14003,7 @@ <h2 id="prefect.task_runners.ConcurrentTaskRunner" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.task_runners.BaseTaskRunner" href="#prefect.task_runners.BaseTaskRunner">BaseTaskRunner</a></code></p>
 
 
-      <p>A concurrent task runner that allows tasks to switch when blocking on IO.
+        <p>A concurrent task runner that allows tasks to switch when blocking on IO.
 Synchronous tasks will be submitted to a thread pool maintained by <code>anyio</code>.</p>
 
 
@@ -14306,7 +14307,7 @@ <h2 id="prefect.task_runners.SequentialTaskRunner" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.task_runners.BaseTaskRunner" href="#prefect.task_runners.BaseTaskRunner">BaseTaskRunner</a></code></p>
 
 
-      <p>A simple task runner that executes calls as they are submitted.</p>
+        <p>A simple task runner that executes calls as they are submitted.</p>
 <p>If writing synchronous tasks, this runner will always execute tasks sequentially.
 If writing async tasks, this runner will execute tasks sequentially unless grouped
 using <code>anyio.create_task_group</code> or <code>asyncio.gather</code>.</p>
diff --git a/versions/unreleased/api-ref/prefect/tasks/index.html b/versions/unreleased/api-ref/prefect/tasks/index.html
index 93f0512485..ec28ed3bf7 100644
--- a/versions/unreleased/api-ref/prefect/tasks/index.html
+++ b/versions/unreleased/api-ref/prefect/tasks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13364,7 +13365,7 @@ <h1 id="prefect.tasks" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the base workflow task class and decorator - for most use cases, using the <a class="autorefs autorefs-internal" href="#prefect.tasks.task"><code>@task</code> decorator</a> is preferred.</p>
+        <p>Module containing the base workflow task class and decorator - for most use cases, using the <a class="autorefs autorefs-internal" href="#prefect.tasks.task"><code>@task</code> decorator</a> is preferred.</p>
 
 
 
@@ -13393,7 +13394,7 @@ <h2 id="prefect.tasks.Task" class="doc doc-heading">
               Bases: <code><span title="typing.Generic">Generic</span>[<span title="prefect.tasks.P">P</span>, <span title="prefect.tasks.R">R</span>]</code></p>
 
 
-      <p>A Prefect task definition.</p>
+        <p>A Prefect task definition.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>We recommend using <a class="autorefs autorefs-internal" href="#prefect.tasks.task">the <code>@task</code> decorator</a> for most use-cases.</p>
@@ -15941,7 +15942,7 @@ <h3 id="prefect.tasks.Task.map" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a mapped run of the task to a worker.</p>
+        <p>Submit a mapped run of the task to a worker.</p>
 <p>Must be called within a flow function. If writing an async task, this
 call must be awaited.</p>
 <p>Must be called with at least one iterable and all iterables must be
@@ -16060,7 +16061,7 @@ <h3 id="prefect.tasks.Task.map" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Define</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">task</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Define</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">task</span>
 
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">prefect</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">task</span>
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="nd">@task</span>
@@ -16479,7 +16480,7 @@ <h3 id="prefect.tasks.Task.serve" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Serve the task using the provided task runner. This method is used to
+        <p>Serve the task using the provided task runner. This method is used to
 establish a websocket connection with the Prefect server and listen for
 submitted task runs to execute.</p>
 
@@ -16595,7 +16596,7 @@ <h3 id="prefect.tasks.Task.submit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a run of the task to the engine.</p>
+        <p>Submit a run of the task to the engine.</p>
 <p>If writing an async task, this call must be awaited.</p>
 <p>If called from within a flow function,</p>
 <p>Will create a new task run in the backing API and submit the task to the flow's
@@ -16710,7 +16711,7 @@ <h3 id="prefect.tasks.Task.submit" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Define</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">task</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Define</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">task</span>
 
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">prefect</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">task</span>
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="nd">@task</span>
@@ -17080,7 +17081,7 @@ <h3 id="prefect.tasks.Task.with_options" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new task from the current object, updating provided options.</p>
+        <p>Create a new task from the current object, updating provided options.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17412,7 +17413,7 @@ <h3 id="prefect.tasks.Task.with_options" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">an</span><span class="w"> </span><span class="n">existing</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">update</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">name</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Create</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">new</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">an</span><span class="w"> </span><span class="n">existing</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="n">update</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">name</span>
 
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="nd">@task</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;My task&quot;</span><span class="p">)</span>
 <span class="o">&gt;&gt;&gt;</span><span class="w"> </span><span class="k">def</span><span class="w"> </span><span class="nf">my_task</span><span class="p">():</span>
@@ -17800,7 +17801,7 @@ <h2 id="prefect.tasks.exponential_backoff" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A task retry backoff utility that configures exponential backoff for task retries.
+        <p>A task retry backoff utility that configures exponential backoff for task retries.
 The exponential backoff design matches the urllib3 implementation.</p>
 
 
@@ -17914,7 +17915,7 @@ <h2 id="prefect.tasks.task" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Decorator to designate a function as a task in a Prefect workflow.</p>
+        <p>Decorator to designate a function as a task in a Prefect workflow.</p>
 <p>This decorator may be used for asynchronous or synchronous functions.</p>
 
 
@@ -18735,7 +18736,7 @@ <h2 id="prefect.tasks.task_input_hash" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A task cache key implementation which hashes all inputs to the task using a JSON or
+        <p>A task cache key implementation which hashes all inputs to the task using a JSON or
 cloudpickle serializer. If any arguments are not JSON serializable, the pickle
 serializer is used as a fallback. If cloudpickle fails, this will return a null key
 indicating that a cache key could not be generated for the given inputs.</p>
diff --git a/versions/unreleased/api-ref/prefect/testing/index.html b/versions/unreleased/api-ref/prefect/testing/index.html
index 83de559294..d90cdb0728 100644
--- a/versions/unreleased/api-ref/prefect/testing/index.html
+++ b/versions/unreleased/api-ref/prefect/testing/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/annotations/index.html b/versions/unreleased/api-ref/prefect/utilities/annotations/index.html
index 3e347d6dc0..16f4f3250f 100644
--- a/versions/unreleased/api-ref/prefect/utilities/annotations/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/annotations/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13332,7 +13333,7 @@ <h2 id="prefect.utilities.annotations.BaseAnnotation" class="doc doc-heading">
               Bases: <code><span title="collections.namedtuple">namedtuple</span>(&#39;BaseAnnotation&#39;, field_names=&#39;value&#39;)</code>, <code><span title="abc.ABC">ABC</span></code>, <code><span title="typing.Generic">Generic</span>[<span title="prefect.utilities.annotations.T">T</span>]</code></p>
 
 
-      <p>Base class for Prefect annotation types.</p>
+        <p>Base class for Prefect annotation types.</p>
 <p>Inherits from <code>namedtuple</code> for unpacking support in another tools.</p>
 
               <details class="quote">
@@ -13417,7 +13418,7 @@ <h2 id="prefect.utilities.annotations.NotSet" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Singleton to distinguish <code>None</code> from a value that is not provided by the user.</p>
+        <p>Singleton to distinguish <code>None</code> from a value that is not provided by the user.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/annotations.py</code></summary>
@@ -13451,7 +13452,7 @@ <h2 id="prefect.utilities.annotations.allow_failure" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.annotations.BaseAnnotation" href="#prefect.utilities.annotations.BaseAnnotation">BaseAnnotation</a>[<span title="prefect.utilities.annotations.T">T</span>]</code></p>
 
 
-      <p>Wrapper for states or futures.</p>
+        <p>Wrapper for states or futures.</p>
 <p>Indicates that the upstream run for this input can be failed.</p>
 <p>Generally, Prefect will not allow a downstream run to start if any of its inputs
 are failed. This annotation allows you to opt into receiving a failed input
@@ -13525,7 +13526,7 @@ <h2 id="prefect.utilities.annotations.quote" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.annotations.BaseAnnotation" href="#prefect.utilities.annotations.BaseAnnotation">BaseAnnotation</a>[<span title="prefect.utilities.annotations.T">T</span>]</code></p>
 
 
-      <p>Simple wrapper to mark an expression as a different type so it will not be coerced
+        <p>Simple wrapper to mark an expression as a different type so it will not be coerced
 by Prefect. For example, if you want to return a state from a flow without having
 the flow assume that state.</p>
 <p>quote will also instruct prefect to ignore introspection of the wrapped object
@@ -13635,7 +13636,7 @@ <h2 id="prefect.utilities.annotations.unmapped" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.annotations.BaseAnnotation" href="#prefect.utilities.annotations.BaseAnnotation">BaseAnnotation</a>[<span title="prefect.utilities.annotations.T">T</span>]</code></p>
 
 
-      <p>Wrapper for iterables.</p>
+        <p>Wrapper for iterables.</p>
 <p>Indicates that this input should be sent as-is to all runs created during a mapping
 operation instead of being split.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/asyncutils/index.html b/versions/unreleased/api-ref/prefect/utilities/asyncutils/index.html
index b929e65cc3..ccd4802652 100644
--- a/versions/unreleased/api-ref/prefect/utilities/asyncutils/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/asyncutils/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13537,7 +13538,7 @@ <h1 id="prefect.utilities.asyncutils" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for interoperability with async functions and workers from various contexts.</p>
+        <p>Utilities for interoperability with async functions and workers from various contexts.</p>
 
 
 
@@ -13566,7 +13567,7 @@ <h2 id="prefect.utilities.asyncutils.GatherIncomplete" class="doc doc-heading">
               Bases: <code>RuntimeError</code></p>
 
 
-      <p>Used to indicate retrieving gather results before completion</p>
+        <p>Used to indicate retrieving gather results before completion</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/asyncutils.py</code></summary>
@@ -13596,7 +13597,7 @@ <h2 id="prefect.utilities.asyncutils.GatherTaskGroup" class="doc doc-heading">
               Bases: <code><span title="anyio.abc.TaskGroup">TaskGroup</span></code></p>
 
 
-      <p>A task group that gathers results.</p>
+        <p>A task group that gathers results.</p>
 <p>AnyIO does not include support <code>gather</code>. This class extends the <code>TaskGroup</code>
 interface to allow simple gathering.</p>
 <p>See https://github.com/agronholm/anyio/issues/100</p>
@@ -13739,7 +13740,7 @@ <h3 id="prefect.utilities.asyncutils.GatherTaskGroup.start" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Since <code>start</code> returns the result of <code>task_status.started()</code> but here we must
+        <p>Since <code>start</code> returns the result of <code>task_status.started()</code> but here we must
 return the key instead, we just won't support this method for now.</p>
 
             <details class="quote">
@@ -13785,7 +13786,7 @@ <h2 id="prefect.utilities.asyncutils.add_event_loop_shutdown_callback" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Adds a callback to the given callable on event loop closure. The callable must be
+        <p>Adds a callback to the given callable on event loop closure. The callable must be
 a coroutine function. It will be awaited when the current event loop is shutting
 down.</p>
 <p>Requires use of <code>asyncio.run()</code> which waits for async generator shutdown by
@@ -13904,7 +13905,7 @@ <h2 id="prefect.utilities.asyncutils.create_gather_task_group" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Create a new task group that gathers results</p>
+        <p>Create a new task group that gathers results</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/asyncutils.py</code></summary>
@@ -13940,7 +13941,7 @@ <h2 id="prefect.utilities.asyncutils.gather" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run calls concurrently and gather their results.</p>
+        <p>Run calls concurrently and gather their results.</p>
 <p>Unlike <code>asyncio.gather</code> this expects to receive <em>callables</em> not <em>coroutines</em>.
 This matches <code>anyio</code> semantics.</p>
 
@@ -13986,7 +13987,7 @@ <h2 id="prefect.utilities.asyncutils.is_async_fn" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns <code>True</code> if a function returns a coroutine.</p>
+        <p>Returns <code>True</code> if a function returns a coroutine.</p>
 <p>See https://github.com/microsoft/pyright/issues/2142 for an example use</p>
 
             <details class="quote">
@@ -14031,7 +14032,7 @@ <h2 id="prefect.utilities.asyncutils.is_async_gen_fn" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns <code>True</code> if a function is an async generator.</p>
+        <p>Returns <code>True</code> if a function is an async generator.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/asyncutils.py</code></summary>
@@ -14067,7 +14068,7 @@ <h2 id="prefect.utilities.asyncutils.raise_async_exception_in_thread" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Raise an exception in a thread asynchronously.</p>
+        <p>Raise an exception in a thread asynchronously.</p>
 <p>This will not interrupt long-running system calls like <code>sleep</code> or <code>wait</code>.</p>
 
             <details class="quote">
@@ -14110,7 +14111,7 @@ <h2 id="prefect.utilities.asyncutils.run_async_from_worker_thread" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Runs an async function in the main thread's event loop, blocking the worker
+        <p>Runs an async function in the main thread's event loop, blocking the worker
 thread until completion</p>
 
             <details class="quote">
@@ -14149,7 +14150,7 @@ <h2 id="prefect.utilities.asyncutils.run_sync" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a coroutine from a synchronous context. A thread will be spawned
+        <p>Runs a coroutine from a synchronous context. A thread will be spawned
 to run the event loop if necessary, which allows coroutines to run in
 environments like Jupyter notebooks where the event loop runs on the main
 thread.</p>
@@ -14308,7 +14309,7 @@ <h2 id="prefect.utilities.asyncutils.run_sync_in_interruptible_worker_thread" cl
 
     <div class="doc doc-contents ">
 
-      <p>Runs a sync function in a new interruptible worker thread so that the main
+        <p>Runs a sync function in a new interruptible worker thread so that the main
 thread's event loop is not blocked</p>
 <p>Unlike the anyio function, this performs best-effort cancellation of the
 thread using the C API. Cancellation will not interrupt system calls like
@@ -14452,7 +14453,7 @@ <h2 id="prefect.utilities.asyncutils.run_sync_in_worker_thread" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Runs a sync function in a new worker thread so that the main thread's event loop
+        <p>Runs a sync function in a new worker thread so that the main thread's event loop
 is not blocked</p>
 <p>Unlike the anyio function, this defaults to a cancellable thread and does not allow
 passing arguments to the anyio function so users can pass kwargs to their function.</p>
@@ -14511,7 +14512,7 @@ <h2 id="prefect.utilities.asyncutils.sync" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Call an async function from a synchronous context. Block until completion.</p>
+        <p>Call an async function from a synchronous context. Block until completion.</p>
 <p>If in an asynchronous context, we will run the code in a separate loop instead of
 failing but a warning will be displayed since this is not recommended.</p>
 
@@ -14577,7 +14578,7 @@ <h2 id="prefect.utilities.asyncutils.sync_compatible" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Converts an async function into a dual async and sync function.</p>
+        <p>Converts an async function into a dual async and sync function.</p>
 <p>When the returned function is called, we will attempt to determine the best way
 to enter the async function.</p>
 <ul>
diff --git a/versions/unreleased/api-ref/prefect/utilities/callables/index.html b/versions/unreleased/api-ref/prefect/utilities/callables/index.html
index cc8c334bf9..e36dfb54ff 100644
--- a/versions/unreleased/api-ref/prefect/utilities/callables/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/callables/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13515,7 +13516,7 @@ <h1 id="prefect.utilities.callables" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for working with Python callables.</p>
+        <p>Utilities for working with Python callables.</p>
 
 
 
@@ -13544,7 +13545,7 @@ <h2 id="prefect.utilities.callables.ParameterSchema" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Simple data model corresponding to an OpenAPI <code>Schema</code>.</p>
+        <p>Simple data model corresponding to an OpenAPI <code>Schema</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/callables.py</code></summary>
@@ -13603,7 +13604,7 @@ <h3 id="prefect.utilities.callables.ParameterSchema.dict" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Exclude <code>None</code> fields by default to comply with
+        <p>Exclude <code>None</code> fields by default to comply with
 the OpenAPI spec.</p>
 
             <details class="quote">
@@ -13645,7 +13646,7 @@ <h2 id="prefect.utilities.callables.call_with_parameters" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Call a function with parameters extracted with <code>get_call_parameters</code></p>
+        <p>Call a function with parameters extracted with <code>get_call_parameters</code></p>
 <p>The function <em>must</em> have an identical signature to the original function or this
 will fail. If you need to send to a function with a different signature, extract
 the args/kwargs using <code>parameters_to_positional_and_keyword</code> directly</p>
@@ -13688,7 +13689,7 @@ <h2 id="prefect.utilities.callables.cloudpickle_wrapped_call" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Serializes a function call using cloudpickle then returns a callable which will
+        <p>Serializes a function call using cloudpickle then returns a callable which will
 execute that call and return a cloudpickle serialized return value</p>
 <p>This is particularly useful for sending calls to libraries that only use the Python
 built-in pickler (e.g. <code>anyio.to_process</code> and <code>multiprocessing</code>) but may require
@@ -13738,7 +13739,7 @@ <h2 id="prefect.utilities.callables.collapse_variadic_parameters" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Given a parameter dictionary, move any parameters stored not present in the
+        <p>Given a parameter dictionary, move any parameters stored not present in the
 signature into the variadic keyword argument.</p>
 <p>Example:</p>
 <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
@@ -13859,7 +13860,7 @@ <h2 id="prefect.utilities.callables.explode_variadic_parameter" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Given a parameter dictionary, move any parameters stored in a variadic keyword
+        <p>Given a parameter dictionary, move any parameters stored in a variadic keyword
 argument parameter (i.e. **kwargs) into the top level.</p>
 <p>Example:</p>
 <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
@@ -13954,7 +13955,7 @@ <h2 id="prefect.utilities.callables.generate_parameter_schema" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Generate a parameter schema from a function signature and docstrings.</p>
+        <p>Generate a parameter schema from a function signature and docstrings.</p>
 <p>To get a signature from a function, use <code>inspect.signature(fn)</code> or
 <code>_generate_signature_from_source(source_code, func_name)</code>.</p>
 
@@ -14138,7 +14139,7 @@ <h2 id="prefect.utilities.callables.get_call_parameters" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Bind a call to a function to get parameter/value mapping. Default values on the
+        <p>Bind a call to a function to get parameter/value mapping. Default values on the
 signature will be included if not overridden.</p>
 <p>Raises a ParameterBindError if the arguments/kwargs are not valid for the function</p>
 
@@ -14208,7 +14209,7 @@ <h2 id="prefect.utilities.callables.get_parameter_defaults" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Get default parameter values for a callable.</p>
+        <p>Get default parameter values for a callable.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/callables.py</code></summary>
@@ -14258,7 +14259,7 @@ <h2 id="prefect.utilities.callables.parameter_docstrings" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Given a docstring in Google docstring format, parse the parameter section
+        <p>Given a docstring in Google docstring format, parse the parameter section
 and return a dictionary that maps parameter names to docstring.</p>
 
 
@@ -14387,7 +14388,7 @@ <h2 id="prefect.utilities.callables.parameter_schema" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a function, generates an OpenAPI-compatible description
+        <p>Given a function, generates an OpenAPI-compatible description
 of the function's arguments, including:
     - name
     - typing information
@@ -14513,7 +14514,7 @@ <h2 id="prefect.utilities.callables.parameter_schema_from_entrypoint" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Generate a parameter schema from an entrypoint string.</p>
+        <p>Generate a parameter schema from an entrypoint string.</p>
 <p>Will load the source code of the function and extract the signature and docstring
 to generate the schema.</p>
 <p>Useful for generating a schema for a function when instantiating the function may
@@ -14654,7 +14655,7 @@ <h2 id="prefect.utilities.callables.parameters_to_args_kwargs" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Convert a <code>parameters</code> dictionary to positional and keyword arguments</p>
+        <p>Convert a <code>parameters</code> dictionary to positional and keyword arguments</p>
 <p>The function <em>must</em> have an identical signature to the original function or this
 will return an empty tuple and dict.</p>
 
@@ -14718,7 +14719,7 @@ <h2 id="prefect.utilities.callables.raise_for_reserved_arguments" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Raise a ReservedArgumentError if <code>fn</code> has any parameters that conflict
+        <p>Raise a ReservedArgumentError if <code>fn</code> has any parameters that conflict
 with the names contained in <code>reserved_arguments</code>.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/utilities/collections/index.html b/versions/unreleased/api-ref/prefect/utilities/collections/index.html
index 9b8e20f2b1..6966d98027 100644
--- a/versions/unreleased/api-ref/prefect/utilities/collections/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/collections/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13449,7 +13450,7 @@ <h1 id="prefect.utilities.collections" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for extensions of and operations on Python collections.</p>
+        <p>Utilities for extensions of and operations on Python collections.</p>
 
 
 
@@ -13478,7 +13479,7 @@ <h2 id="prefect.utilities.collections.AutoEnum" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>An enum class that automatically generates value from variable names.</p>
+        <p>An enum class that automatically generates value from variable names.</p>
 <p>This guards against common errors where variable names are updated but values are
 not.</p>
 <p>In addition, because AutoEnums inherit from <code>str</code>, they are automatically
@@ -13588,7 +13589,7 @@ <h3 id="prefect.utilities.collections.AutoEnum.auto" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
+        <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/collections.py</code></summary>
@@ -13633,7 +13634,7 @@ <h2 id="prefect.utilities.collections.StopVisiting" class="doc doc-heading">
               Bases: <code>BaseException</code></p>
 
 
-      <p>A special exception used to stop recursive visits in <code>visit_collection</code>.</p>
+        <p>A special exception used to stop recursive visits in <code>visit_collection</code>.</p>
 <p>When raised, the expression is returned without modification and recursive visits
 in that path will end.</p>
 
@@ -13671,7 +13672,7 @@ <h2 id="prefect.utilities.collections.batched_iterable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Yield batches of a certain size from an iterable</p>
+        <p>Yield batches of a certain size from an iterable</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13791,7 +13792,7 @@ <h2 id="prefect.utilities.collections.dict_to_flatdict" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Converts a (nested) dictionary to a flattened representation.</p>
+        <p>Converts a (nested) dictionary to a flattened representation.</p>
 <p>Each key of the flat dict will be a CompoundKey tuple containing the "chain of keys"
 for the corresponding value.</p>
 
@@ -13933,7 +13934,7 @@ <h2 id="prefect.utilities.collections.extract_instances" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Extract objects from a file and returns a dict of type -&gt; instances</p>
+        <p>Extract objects from a file and returns a dict of type -&gt; instances</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14089,7 +14090,7 @@ <h2 id="prefect.utilities.collections.flatdict_to_dict" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Converts a flattened dictionary back to a nested dictionary.</p>
+        <p>Converts a flattened dictionary back to a nested dictionary.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14120,7 +14121,7 @@ <h2 id="prefect.utilities.collections.flatdict_to_dict" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <p>Returns
+        <p>Returns
     A nested dict of the same type as dct</p>
 
             <details class="quote">
@@ -14189,7 +14190,7 @@ <h2 id="prefect.utilities.collections.get_from_dict" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a value from a nested dictionary or list using a sequence of keys.</p>
+        <p>Fetch a value from a nested dictionary or list using a sequence of keys.</p>
 <p>This function allows to fetch a value from a deeply nested structure
 of dictionaries and lists using either a dot-separated string or a list
 of keys. If a requested key does not exist, the function returns the
@@ -14278,7 +14279,7 @@ <h2 id="prefect.utilities.collections.get_from_dict" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <blockquote>
+        <blockquote>
 <blockquote>
 <blockquote>
 <p>get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]')
@@ -14397,7 +14398,7 @@ <h2 id="prefect.utilities.collections.isiterable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a boolean indicating if an object is iterable.</p>
+        <p>Return a boolean indicating if an object is iterable.</p>
 <p>Excludes types that are iterable but typically used as singletons:
 - str
 - bytes
@@ -14451,7 +14452,7 @@ <h2 id="prefect.utilities.collections.remove_nested_keys" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Recurses a dictionary returns a copy without all keys that match an entry in
+        <p>Recurses a dictionary returns a copy without all keys that match an entry in
 <code>key_to_remove</code>. Return <code>obj</code> unchanged if not a dictionary.</p>
 
 
@@ -14565,7 +14566,7 @@ <h2 id="prefect.utilities.collections.visit_collection" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This function visits every element of an arbitrary Python collection. If an element
+        <p>This function visits every element of an arbitrary Python collection. If an element
 is a Python collection, it will be visited recursively. If an element is not a
 collection, <code>visit_fn</code> will be called with the element. The return value of
 <code>visit_fn</code> can be used to alter the element if <code>return_data</code> is set.</p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/compat/index.html b/versions/unreleased/api-ref/prefect/utilities/compat/index.html
index d4174b04b2..d1ff0285cd 100644
--- a/versions/unreleased/api-ref/prefect/utilities/compat/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/compat/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13151,7 +13152,7 @@ <h1 id="prefect.utilities.compat" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for Python version compatibility</p>
+        <p>Utilities for Python version compatibility</p>
 
 
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/context/index.html b/versions/unreleased/api-ref/prefect/utilities/context/index.html
index dc01b4c32b..362649e3ab 100644
--- a/versions/unreleased/api-ref/prefect/utilities/context/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/context/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13240,7 +13241,7 @@ <h2 id="prefect.utilities.context.get_task_and_flow_run_ids" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get the task run and flow run ids from the context, if available.</p>
+        <p>Get the task run and flow run ids from the context, if available.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/dispatch/index.html b/versions/unreleased/api-ref/prefect/utilities/dispatch/index.html
index 8e984db15c..16445fd8af 100644
--- a/versions/unreleased/api-ref/prefect/utilities/dispatch/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/dispatch/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.utilities.dispatch" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Provides methods for performing dynamic dispatch for actions on base type to one of its
+        <p>Provides methods for performing dynamic dispatch for actions on base type to one of its
 subtypes.</p>
 <p>Example:</p>
 <div class="highlight"><pre><span></span><code><span class="nd">@register_base_type</span>
@@ -13345,7 +13346,7 @@ <h2 id="prefect.utilities.dispatch.get_dispatch_key" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the unique dispatch key for a class type or instance.</p>
+        <p>Retrieve the unique dispatch key for a class type or instance.</p>
 <p>This key is defined at the <code>__dispatch_key__</code> attribute. If it is a callable, it
 will be resolved.</p>
 <p>If <code>allow_missing</code> is <code>False</code>, an exception will be raised if the attribute is not
@@ -13451,7 +13452,7 @@ <h2 id="prefect.utilities.dispatch.get_registry_for_type" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Get the first matching registry for a class or any of its base classes.</p>
+        <p>Get the first matching registry for a class or any of its base classes.</p>
 <p>If not found, <code>None</code> is returned.</p>
 
             <details class="quote">
@@ -13498,7 +13499,7 @@ <h2 id="prefect.utilities.dispatch.lookup_type" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Look up a dispatch key in the type registry for the given class.</p>
+        <p>Look up a dispatch key in the type registry for the given class.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dispatch.py</code></summary>
@@ -13552,7 +13553,7 @@ <h2 id="prefect.utilities.dispatch.register_base_type" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Register a base type allowing child types to be registered for dispatch with
+        <p>Register a base type allowing child types to be registered for dispatch with
 <code>register_type</code>.</p>
 <p>The base class may or may not define a <code>__dispatch_key__</code> to allow lookups of the
 base type.</p>
@@ -13611,7 +13612,7 @@ <h2 id="prefect.utilities.dispatch.register_type" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Register a type for lookup with dispatch.</p>
+        <p>Register a type for lookup with dispatch.</p>
 <p>The type or one of its parents must define a unique <code>__dispatch_key__</code>.</p>
 <p>One of the classes base types must be registered using <code>register_base_type</code>.</p>
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/dockerutils/index.html b/versions/unreleased/api-ref/prefect/utilities/dockerutils/index.html
index a5a06eeba8..3e0877f457 100644
--- a/versions/unreleased/api-ref/prefect/utilities/dockerutils/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/dockerutils/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13696,7 +13697,7 @@ <h2 id="prefect.utilities.dockerutils.BuildError" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when a Docker build fails</p>
+        <p>Raised when a Docker build fails</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -13724,7 +13725,7 @@ <h2 id="prefect.utilities.dockerutils.ImageBuilder" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>An interface for preparing Docker build contexts and building images</p>
+        <p>An interface for preparing Docker build contexts and building images</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14143,7 +14144,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.add_line" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Add a line to this image's Dockerfile</p>
+        <p>Add a line to this image's Dockerfile</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14169,7 +14170,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.add_lines" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Add lines to this image's Dockerfile</p>
+        <p>Add lines to this image's Dockerfile</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14195,7 +14196,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.assert_has_file" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Asserts that the given file or directory will be copied into the container
+        <p>Asserts that the given file or directory will be copied into the container
 at the given path</p>
 
             <details class="quote">
@@ -14230,7 +14231,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.assert_has_line" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Asserts that the given line is in the Dockerfile</p>
+        <p>Asserts that the given line is in the Dockerfile</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14268,7 +14269,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.assert_line_absent" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Asserts that the given line is absent from the Dockerfile</p>
+        <p>Asserts that the given line is absent from the Dockerfile</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14326,7 +14327,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.assert_line_after" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Asserts that the second line appears after the first line</p>
+        <p>Asserts that the second line appears after the first line</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14352,7 +14353,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.assert_line_before" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Asserts that the first line appears before the second line</p>
+        <p>Asserts that the first line appears before the second line</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14420,7 +14421,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.build" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Build the Docker image from the current state of the ImageBuilder</p>
+        <p>Build the Docker image from the current state of the ImageBuilder</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14561,7 +14562,7 @@ <h3 id="prefect.utilities.dockerutils.ImageBuilder.copy" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Copy a file to this image</p>
+        <p>Copy a file to this image</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14640,7 +14641,7 @@ <h2 id="prefect.utilities.dockerutils.PushError" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when a Docker image push fails</p>
+        <p>Raised when a Docker image push fails</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14666,7 +14667,7 @@ <h2 id="prefect.utilities.dockerutils.build_image" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Builds a Docker image, returning the image ID</p>
+        <p>Builds a Docker image, returning the image ID</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14921,7 +14922,7 @@ <h2 id="prefect.utilities.dockerutils.docker_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the environmentally-configured Docker client</p>
+        <p>Get the environmentally-configured Docker client</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/dockerutils.py</code></summary>
@@ -14971,7 +14972,7 @@ <h2 id="prefect.utilities.dockerutils.format_outlier_version_name" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Formats outlier docker version names to pass <code>packaging.version.parse</code> validation
+        <p>Formats outlier docker version names to pass <code>packaging.version.parse</code> validation
 - Current cases are simple, but creates stub for more complicated formatting if eventually needed.
 - Example outlier versions that throw a parsing exception:
   - "20.10.0-ce" (variant of community edition label)
@@ -15076,7 +15077,7 @@ <h2 id="prefect.utilities.dockerutils.generate_default_dockerfile" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Generates a default Dockerfile used for deploying flows. The Dockerfile is written
+        <p>Generates a default Dockerfile used for deploying flows. The Dockerfile is written
 to a temporary file and yielded. The temporary file is removed after the context
 manager exits.</p>
 
@@ -15210,7 +15211,7 @@ <h2 id="prefect.utilities.dockerutils.get_prefect_image_name" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Get the Prefect image name matching the current Prefect and Python versions.</p>
+        <p>Get the Prefect image name matching the current Prefect and Python versions.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15352,7 +15353,7 @@ <h2 id="prefect.utilities.dockerutils.parse_image_tag" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Parse Docker Image String</p>
+        <p>Parse Docker Image String</p>
 <ul>
 <li>If a tag exists, this function parses and returns the image registry and tag,
   separately as a tuple.</li>
@@ -15486,7 +15487,7 @@ <h2 id="prefect.utilities.dockerutils.push_image" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pushes a local image to a Docker registry, returning the registry-qualified tag
+        <p>Pushes a local image to a Docker registry, returning the registry-qualified tag
 for that image</p>
 <p>This assumes that the environment's Docker daemon is already authenticated to the
 given registry, and currently makes no attempt to authenticate.</p>
@@ -15725,7 +15726,7 @@ <h2 id="prefect.utilities.dockerutils.split_repository_path" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Splits a Docker repository path into its namespace and repository components.</p>
+        <p>Splits a Docker repository path into its namespace and repository components.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15857,7 +15858,7 @@ <h2 id="prefect.utilities.dockerutils.to_run_command" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert a process-style list of command arguments to a single Dockerfile RUN
+        <p>Convert a process-style list of command arguments to a single Dockerfile RUN
 instruction.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/utilities/filesystem/index.html b/versions/unreleased/api-ref/prefect/utilities/filesystem/index.html
index 9e7704eba9..6fbbfa5e57 100644
--- a/versions/unreleased/api-ref/prefect/utilities/filesystem/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/filesystem/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13371,7 +13372,7 @@ <h1 id="prefect.utilities.filesystem" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for working with file systems</p>
+        <p>Utilities for working with file systems</p>
 
 
 
@@ -13396,7 +13397,7 @@ <h2 id="prefect.utilities.filesystem.create_default_ignore_file" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Creates default ignore file in the provided path if one does not already exist; returns boolean specifying
+        <p>Creates default ignore file in the provided path if one does not already exist; returns boolean specifying
 whether a file was created.</p>
 
             <details class="quote">
@@ -13443,7 +13444,7 @@ <h2 id="prefect.utilities.filesystem.filename" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extract the file name from a path with remote file system support</p>
+        <p>Extract the file name from a path with remote file system support</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/filesystem.py</code></summary>
@@ -13479,7 +13480,7 @@ <h2 id="prefect.utilities.filesystem.filter_files" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>This function accepts a root directory path and a list of file patterns to ignore, and returns
+        <p>This function accepts a root directory path and a list of file patterns to ignore, and returns
 a list of files that excludes those that should be ignored.</p>
 <p>The specification matches that of <a href="https://git-scm.com/docs/gitignore">.gitignore files</a>.</p>
 
@@ -13539,7 +13540,7 @@ <h2 id="prefect.utilities.filesystem.get_open_file_limit" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Get the maximum number of open files allowed for the current process</p>
+        <p>Get the maximum number of open files allowed for the current process</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/filesystem.py</code></summary>
@@ -13595,7 +13596,7 @@ <h2 id="prefect.utilities.filesystem.is_local_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Check if the given path points to a local or remote file system</p>
+        <p>Check if the given path points to a local or remote file system</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/filesystem.py</code></summary>
@@ -13647,7 +13648,7 @@ <h2 id="prefect.utilities.filesystem.relative_path_to_current_platform" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Converts a relative path generated on any platform to a relative path for the
+        <p>Converts a relative path generated on any platform to a relative path for the
 current platform.</p>
 
             <details class="quote">
@@ -13682,7 +13683,7 @@ <h2 id="prefect.utilities.filesystem.tmpchdir" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Change current-working directories for the duration of the context</p>
+        <p>Change current-working directories for the duration of the context</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/filesystem.py</code></summary>
@@ -13736,7 +13737,7 @@ <h2 id="prefect.utilities.filesystem.to_display_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert a path to a displayable path. The absolute path or relative path to the
+        <p>Convert a path to a displayable path. The absolute path or relative path to the
 current (or given) directory will be returned, whichever is shorter.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/utilities/hashing/index.html b/versions/unreleased/api-ref/prefect/utilities/hashing/index.html
index f08580fb63..0b07c07066 100644
--- a/versions/unreleased/api-ref/prefect/utilities/hashing/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/hashing/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13284,7 +13285,7 @@ <h2 id="prefect.utilities.hashing.file_hash" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given a path to a file, produces a stable hash of the file contents.</p>
+        <p>Given a path to a file, produces a stable hash of the file contents.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13393,7 +13394,7 @@ <h2 id="prefect.utilities.hashing.hash_objects" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Attempt to hash objects by dumping to JSON or serializing with cloudpickle.
+        <p>Attempt to hash objects by dumping to JSON or serializing with cloudpickle.
 On failure of both, <code>None</code> will be returned</p>
 
             <details class="quote">
@@ -13448,7 +13449,7 @@ <h2 id="prefect.utilities.hashing.stable_hash" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Given some arguments, produces a stable 64-bit hash of their contents.</p>
+        <p>Given some arguments, produces a stable 64-bit hash of their contents.</p>
 <p>Supports bytes and strings. Strings will be UTF-8 encoded.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/importtools/index.html b/versions/unreleased/api-ref/prefect/utilities/importtools/index.html
index 941473d1a5..76f83c36eb 100644
--- a/versions/unreleased/api-ref/prefect/utilities/importtools/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/importtools/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13498,7 +13499,7 @@ <h2 id="prefect.utilities.importtools.AliasedModuleDefinition" class="doc doc-he
               Bases: <code><span title="typing.NamedTuple">NamedTuple</span></code></p>
 
 
-      <p>A definition for the <code>AliasedModuleFinder</code>.</p>
+        <p>A definition for the <code>AliasedModuleFinder</code>.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13709,7 +13710,7 @@ <h3 id="prefect.utilities.importtools.AliasedModuleFinder.find_spec" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The fullname is the imported path, e.g. "foo.bar". If there is an alias "phi"
+        <p>The fullname is the imported path, e.g. "foo.bar". If there is an alias "phi"
 for "foo" then on import of "phi.bar" we will find the spec for "foo.bar" and
 create a new spec for "phi.bar" that points to "foo.bar".</p>
 
@@ -13788,7 +13789,7 @@ <h2 id="prefect.utilities.importtools.DelayedImportErrorModule" class="doc doc-h
               Bases: <code><span title="types.ModuleType">ModuleType</span></code></p>
 
 
-      <p>A fake module returned by <code>lazy_import</code> when the module cannot be found. When any
+        <p>A fake module returned by <code>lazy_import</code> when the module cannot be found. When any
 of the module's attributes are accessed, we will throw a <code>ModuleNotFoundError</code>.</p>
 <p>Adapted from <a href="https://github.com/scientific-python/lazy_loader">lazy_loader</a></p>
 
@@ -13884,7 +13885,7 @@ <h2 id="prefect.utilities.importtools.from_qualified_name" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Import an object given a fully-qualified name.</p>
+        <p>Import an object given a fully-qualified name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14022,7 +14023,7 @@ <h2 id="prefect.utilities.importtools.import_object" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Load an object from an import path.</p>
+        <p>Load an object from an import path.</p>
 <p>Import paths can be formatted as one of:
 - module.object
 - module:object
@@ -14101,7 +14102,7 @@ <h2 id="prefect.utilities.importtools.lazy_import" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a lazily-imported module to use in place of the module of the given name.
+        <p>Create a lazily-imported module to use in place of the module of the given name.
 Use this to retain module-level imports for libraries that we don't want to
 actually import until they are needed.</p>
 <p>Adapted from the <a href="https://docs.python.org/3/library/importlib.html#implementing-lazy-imports">Python documentation</a> and <a href="https://github.com/scientific-python/lazy_loader">lazy_loader</a></p>
@@ -14216,7 +14217,7 @@ <h2 id="prefect.utilities.importtools.load_module" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Import a module with support for relative imports within the module.</p>
+        <p>Import a module with support for relative imports within the module.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/importtools.py</code></summary>
@@ -14262,7 +14263,7 @@ <h2 id="prefect.utilities.importtools.load_script_as_module" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Execute a script at the given path.</p>
+        <p>Execute a script at the given path.</p>
 <p>Sets the module name to <code>__prefect_loader__</code>.</p>
 <p>If an exception occurs during execution of the script, a
 <code>prefect.exceptions.ScriptError</code> is created to wrap the exception and raised.</p>
@@ -14379,7 +14380,7 @@ <h2 id="prefect.utilities.importtools.objects_from_script" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Run a python script and return all the global variables</p>
+        <p>Run a python script and return all the global variables</p>
 <p>Supports remote paths by copying to a local temporary file.</p>
 <p>WARNING: The Python documentation does not recommend using runpy for this pattern.</p>
 <blockquote>
@@ -14608,7 +14609,7 @@ <h2 id="prefect.utilities.importtools.safe_load_namespace" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Safely load a namespace from source code, optionally handling relative imports.</p>
+        <p>Safely load a namespace from source code, optionally handling relative imports.</p>
 <p>If a <code>filepath</code> is provided, <code>sys.path</code> is modified to support relative imports.
 Changes to <code>sys.path</code> are reverted after completion, but this function is not thread safe
 and use of it in threaded contexts may result in undesirable behavior.</p>
@@ -15005,7 +15006,7 @@ <h2 id="prefect.utilities.importtools.to_qualified_name" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Given an object, returns its fully-qualified name: a string that represents its
+        <p>Given an object, returns its fully-qualified name: a string that represents its
 Python import path.</p>
 
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/math/index.html b/versions/unreleased/api-ref/prefect/utilities/math/index.html
index 64c3e95f95..49a4f2564b 100644
--- a/versions/unreleased/api-ref/prefect/utilities/math/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/math/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13306,7 +13307,7 @@ <h2 id="prefect.utilities.math.bounded_poisson_interval" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Bounds Poisson "inter-arrival times" to a range.</p>
+        <p>Bounds Poisson "inter-arrival times" to a range.</p>
 <p>Unlike <code>clamped_poisson_interval</code> this does not take a target average interval.
 Instead, the interval is predetermined and the average is calculated as their
 midpoint. This allows Poisson intervals to be used in cases where a lower bound
@@ -13356,7 +13357,7 @@ <h2 id="prefect.utilities.math.clamped_poisson_interval" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Bounds Poisson "inter-arrival times" to a range defined by the clamping factor.</p>
+        <p>Bounds Poisson "inter-arrival times" to a range defined by the clamping factor.</p>
 <p>The upper bound for this random variate is: average_interval * (1 + clamping_factor).
 A lower bound is picked so that the average interval remains approximately fixed.</p>
 
@@ -13412,7 +13413,7 @@ <h2 id="prefect.utilities.math.lower_clamp_multiple" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Computes a lower clamp multiple that can be used to bound a random variate drawn
+        <p>Computes a lower clamp multiple that can be used to bound a random variate drawn
 from an exponential distribution.</p>
 <p>Given an upper clamp multiple <code>k</code> (and corresponding upper bound k * average_interval),
 this function computes a lower clamp multiple <code>c</code> (corresponding to a lower bound
@@ -13467,7 +13468,7 @@ <h2 id="prefect.utilities.math.poisson_interval" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates an "inter-arrival time" for a Poisson process.</p>
+        <p>Generates an "inter-arrival time" for a Poisson process.</p>
 <p>Draws a random variable from an exponential distribution using the inverse-CDF
 method. Can optionally be passed a lower and upper bound between (0, 1] to clamp
 the potential output values.</p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/names/index.html b/versions/unreleased/api-ref/prefect/utilities/names/index.html
index 07e4ef61e7..99fd166af8 100644
--- a/versions/unreleased/api-ref/prefect/utilities/names/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/names/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13284,7 +13285,7 @@ <h2 id="prefect.utilities.names.generate_slug" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generates a random slug.</p>
+        <p>Generates a random slug.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13361,7 +13362,7 @@ <h2 id="prefect.utilities.names.obfuscate" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Obfuscates any data type's string representation. See <code>obfuscate_string</code>.</p>
+        <p>Obfuscates any data type's string representation. See <code>obfuscate_string</code>.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/names.py</code></summary>
@@ -13397,7 +13398,7 @@ <h2 id="prefect.utilities.names.obfuscate_string" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Obfuscates a string by returning a new string of 8 characters. If the input
+        <p>Obfuscates a string by returning a new string of 8 characters. If the input
 string is longer than 10 characters and show_tail is True, then up to 4 of
 its final characters will become final characters of the obfuscated string;
 all other characters are "*".</p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/processutils/index.html b/versions/unreleased/api-ref/prefect/utilities/processutils/index.html
index c80c50cf25..7dab8c997a 100644
--- a/versions/unreleased/api-ref/prefect/utilities/processutils/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/processutils/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13350,7 +13351,7 @@ <h2 id="prefect.utilities.processutils.forward_signal_handler" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Forward subsequent signum events (e.g. interrupts) to respective signums.</p>
+        <p>Forward subsequent signum events (e.g. interrupts) to respective signums.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/processutils.py</code></summary>
@@ -13438,7 +13439,7 @@ <h2 id="prefect.utilities.processutils.open_process" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Like <code>anyio.open_process</code> but with:
+        <p>Like <code>anyio.open_process</code> but with:
 - Support for Windows command joining
 - Termination of the process on exception during yield
 - Forced cleanup of process resources during cancellation</p>
@@ -13577,7 +13578,7 @@ <h2 id="prefect.utilities.processutils.run_process" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Like <code>anyio.run_process</code> but with:</p>
+        <p>Like <code>anyio.run_process</code> but with:</p>
 <ul>
 <li>Use of our <code>open_process</code> utility to ensure resources are cleaned up</li>
 <li>Simple <code>stream_output</code> support to connect the subprocess to the parent stdout/err</li>
@@ -13685,7 +13686,7 @@ <h2 id="prefect.utilities.processutils.setup_signal_handlers_agent" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Handle interrupts of the agent gracefully.</p>
+        <p>Handle interrupts of the agent gracefully.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/processutils.py</code></summary>
@@ -13737,7 +13738,7 @@ <h2 id="prefect.utilities.processutils.setup_signal_handlers_server" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Handle interrupts of the server gracefully.</p>
+        <p>Handle interrupts of the server gracefully.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/processutils.py</code></summary>
@@ -13787,7 +13788,7 @@ <h2 id="prefect.utilities.processutils.setup_signal_handlers_worker" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Handle interrupts of workers gracefully.</p>
+        <p>Handle interrupts of workers gracefully.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/processutils.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/utilities/pydantic/index.html b/versions/unreleased/api-ref/prefect/utilities/pydantic/index.html
index 4f851267a4..639de24b73 100644
--- a/versions/unreleased/api-ref/prefect/utilities/pydantic/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/pydantic/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13310,7 +13311,7 @@ <h2 id="prefect.utilities.pydantic.PartialModel" class="doc doc-heading">
               Bases: <code><span title="typing.Generic">Generic</span>[<span title="prefect.utilities.pydantic.M">M</span>]</code></p>
 
 
-      <p>A utility for creating a Pydantic model in several steps.</p>
+        <p>A utility for creating a Pydantic model in several steps.</p>
 <p>Fields may be set at initialization, via attribute assignment, or at finalization
 when the concrete model is returned.</p>
 <p>Pydantic validation does not occur until finalization.</p>
@@ -13488,7 +13489,7 @@ <h2 id="prefect.utilities.pydantic.add_cloudpickle_reduction" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Adds a <code>__reducer__</code> to the given class that ensures it is cloudpickle compatible.</p>
+        <p>Adds a <code>__reducer__</code> to the given class that ensures it is cloudpickle compatible.</p>
 <p>Workaround for issues with cloudpickle when using cythonized pydantic which
 throws exceptions when attempting to pickle the class which has "compiled"
 validator methods dynamically attached to it.</p>
@@ -13572,7 +13573,7 @@ <h2 id="prefect.utilities.pydantic.add_type_dispatch" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extend a Pydantic model to add a 'type' field that is used as a discriminator field
+        <p>Extend a Pydantic model to add a 'type' field that is used as a discriminator field
 to dynamically determine the subtype that when deserializing models.</p>
 <p>This allows automatic resolution to subtypes of the decorated model.</p>
 <p>If a type field already exists, it should be a string literal field that has a
@@ -13789,7 +13790,7 @@ <h2 id="prefect.utilities.pydantic.get_class_fields_only" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Gets all the field names defined on the model class but not any parent classes.
+        <p>Gets all the field names defined on the model class but not any parent classes.
 Any fields that are on the parent but redefined on the subclass are included.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/prefect/utilities/render_swagger/index.html b/versions/unreleased/api-ref/prefect/utilities/render_swagger/index.html
index 4c1bee74ab..65f9597883 100644
--- a/versions/unreleased/api-ref/prefect/utilities/render_swagger/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/render_swagger/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13240,7 +13241,7 @@ <h2 id="prefect.utilities.render_swagger.swagger_lib" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Provides the actual swagger library used</p>
+        <p>Provides the actual swagger library used</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/render_swagger.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/utilities/services/index.html b/versions/unreleased/api-ref/prefect/utilities/services/index.html
index fe58b3e64a..5575e4daca 100644
--- a/versions/unreleased/api-ref/prefect/utilities/services/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/services/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13244,7 +13245,7 @@ <h2 id="prefect.utilities.services.critical_service_loop" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Runs the given <code>workload</code> function on the specified <code>interval</code>, while being
+        <p>Runs the given <code>workload</code> function on the specified <code>interval</code>, while being
 forgiving of intermittent issues like temporary HTTP errors.  If more than a certain
 number of <code>consecutive</code> errors occur, print a summary of up to <code>memory</code> recent
 exceptions to <code>printer</code>, then begin backoff.</p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/slugify/index.html b/versions/unreleased/api-ref/prefect/utilities/slugify/index.html
index 30f837ac20..96d9f7a1b5 100644
--- a/versions/unreleased/api-ref/prefect/utilities/slugify/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/slugify/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/templating/index.html b/versions/unreleased/api-ref/prefect/utilities/templating/index.html
index c792007052..4849e01186 100644
--- a/versions/unreleased/api-ref/prefect/utilities/templating/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/templating/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13392,7 +13393,7 @@ <h2 id="prefect.utilities.templating.apply_values" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Replaces placeholders in a template with values from a supplied dictionary.</p>
+        <p>Replaces placeholders in a template with values from a supplied dictionary.</p>
 <p>Will recursively replace placeholders in dictionaries and lists.</p>
 <p>If a value has no placeholders, it will be returned unchanged.</p>
 <p>If a template contains only a single placeholder, the placeholder will be
@@ -13669,7 +13670,7 @@ <h2 id="prefect.utilities.templating.determine_placeholder_type" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Determines the type of a placeholder based on its name.</p>
+        <p>Determines the type of a placeholder based on its name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13777,7 +13778,7 @@ <h2 id="prefect.utilities.templating.find_placeholders" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Finds all placeholders in a template.</p>
+        <p>Finds all placeholders in a template.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13905,7 +13906,7 @@ <h2 id="prefect.utilities.templating.resolve_block_document_references" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Resolve block document references in a template by replacing each reference with
+        <p>Resolve block document references in a template by replacing each reference with
 the data of the block document.</p>
 <p>Recursively searches for block document references in dictionaries and lists.</p>
 <p>Identifies block document references by the as dictionary with the following
@@ -14296,7 +14297,7 @@ <h2 id="prefect.utilities.templating.resolve_variables" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resolve variables in a template by replacing each variable placeholder with the
+        <p>Resolve variables in a template by replacing each variable placeholder with the
 value of the variable.</p>
 <p>Recursively searches for variable placeholders in dictionaries and lists.</p>
 <p>Strips variable placeholders if the variable is not found.</p>
diff --git a/versions/unreleased/api-ref/prefect/utilities/text/index.html b/versions/unreleased/api-ref/prefect/utilities/text/index.html
index 4684bcd009..66fb1455b3 100644
--- a/versions/unreleased/api-ref/prefect/utilities/text/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/text/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/prefect/utilities/visualization/index.html b/versions/unreleased/api-ref/prefect/utilities/visualization/index.html
index b8f74d07fc..39ec94a270 100644
--- a/versions/unreleased/api-ref/prefect/utilities/visualization/index.html
+++ b/versions/unreleased/api-ref/prefect/utilities/visualization/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13317,7 +13318,7 @@ <h1 id="prefect.utilities.visualization" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for working with Flow.visualize()</p>
+        <p>Utilities for working with Flow.visualize()</p>
 
 
 
@@ -13443,7 +13444,7 @@ <h3 id="prefect.utilities.visualization.TaskVizTracker.link_viz_return_value_to_
 
     <div class="doc doc-contents ">
 
-      <p>We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256
+        <p>We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256
 because they are singletons.</p>
 
             <details class="quote">
@@ -13501,13 +13502,13 @@ <h2 id="prefect.utilities.visualization.build_task_dependencies" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Constructs a Graphviz directed graph object that represents the dependencies
+        <p>Constructs a Graphviz directed graph object that represents the dependencies
 between tasks in the given TaskVizTracker.</p>
-      <ul>
+        <ul>
 <li>task_run_tracker (TaskVizTracker): An object containing tasks and their
   dependencies.</li>
 </ul>
-      <ul>
+        <ul>
 <li>graphviz.Digraph: A directed graph object depicting the relationships and
   dependencies between tasks.</li>
 </ul>
@@ -13605,7 +13606,7 @@ <h2 id="prefect.utilities.visualization.track_viz_task" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return a result if sync otherwise return a coroutine that returns the result</p>
+        <p>Return a result if sync otherwise return a coroutine that returns the result</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/visualization.py</code></summary>
@@ -13651,7 +13652,7 @@ <h2 id="prefect.utilities.visualization.visualize_task_dependencies" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Renders and displays a Graphviz directed graph representing task dependencies.</p>
+        <p>Renders and displays a Graphviz directed graph representing task dependencies.</p>
 <p>The graph is rendered in PNG format and saved with the name specified by
 flow_run_name. After rendering, the visualization is opened and displayed.</p>
 <p>Parameters:
diff --git a/versions/unreleased/api-ref/prefect/variables/index.html b/versions/unreleased/api-ref/prefect/variables/index.html
index 64f2da1928..21e70a6979 100644
--- a/versions/unreleased/api-ref/prefect/variables/index.html
+++ b/versions/unreleased/api-ref/prefect/variables/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13303,7 +13304,7 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.client.schemas.actions.VariableCreate" href="../client/schemas/#prefect.client.schemas.actions.VariableCreate">VariableCreate</a></code></p>
 
 
-      <p>Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.
+        <p>Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.
 https://docs.prefect.io/latest/concepts/variables/</p>
 
 
@@ -13441,7 +13442,13 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
 <span class="normal">86</span>
 <span class="normal">87</span>
 <span class="normal">88</span>
-<span class="normal">89</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">class</span> <span class="nc">Variable</span><span class="p">(</span><span class="n">VariableRequest</span><span class="p">):</span>
+<span class="normal">89</span>
+<span class="normal">90</span>
+<span class="normal">91</span>
+<span class="normal">92</span>
+<span class="normal">93</span>
+<span class="normal">94</span>
+<span class="normal">95</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">class</span> <span class="nc">Variable</span><span class="p">(</span><span class="n">VariableRequest</span><span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.</span>
 <span class="sd">    https://docs.prefect.io/latest/concepts/variables/</span>
@@ -13460,7 +13467,7 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
         <span class="n">value</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
         <span class="n">tags</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
         <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
-    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="s2">&quot;Variable&quot;</span><span class="p">]:</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Sets a new variable. If one exists with the same name, user must pass `overwrite=True`</span>
 <span class="sd">        ```</span>
@@ -13481,8 +13488,7 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">client</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">get_or_create_client</span><span class="p">()</span>
         <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">read_variable_by_name</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
-        <span class="n">var_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="s2">&quot;value&quot;</span><span class="p">:</span> <span class="n">value</span><span class="p">}</span>
-        <span class="n">var_dict</span><span class="p">[</span><span class="s2">&quot;tags&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">tags</span> <span class="ow">or</span> <span class="p">[]</span>
+        <span class="n">var_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="s2">&quot;value&quot;</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span> <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="n">tags</span> <span class="ow">or</span> <span class="p">[]}</span>
         <span class="k">if</span> <span class="n">variable</span><span class="p">:</span>
             <span class="k">if</span> <span class="ow">not</span> <span class="n">overwrite</span><span class="p">:</span>
                 <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
@@ -13499,7 +13505,9 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
 
     <span class="nd">@classmethod</span>
     <span class="nd">@sync_compatible</span>
-    <span class="k">async</span> <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">default</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+    <span class="k">async</span> <span class="k">def</span> <span class="nf">get</span><span class="p">(</span>
+        <span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">default</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="s2">&quot;Variable&quot;</span><span class="p">,</span> <span class="nb">str</span><span class="p">]]:</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Get a variable by name. If doesn&#39;t exist return the default.</span>
 <span class="sd">        ```</span>
@@ -13520,7 +13528,12 @@ <h2 id="prefect.variables.Variable" class="doc doc-heading">
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">client</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">get_or_create_client</span><span class="p">()</span>
         <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">read_variable_by_name</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
-        <span class="k">return</span> <span class="n">variable</span> <span class="k">if</span> <span class="n">variable</span> <span class="k">else</span> <span class="n">default</span>
+
+        <span class="k">return</span> <span class="p">(</span>
+            <span class="n">Variable</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">value</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
+            <span class="k">if</span> <span class="n">variable</span>
+            <span class="k">else</span> <span class="n">default</span>
+        <span class="p">)</span>
 </code></pre></div></td></tr></table></div>
               </details>
 
@@ -13552,7 +13565,7 @@ <h3 id="prefect.variables.Variable.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a variable by name. If doesn't exist return the default.
+        <p>Get a variable by name. If doesn't exist return the default.
 <div class="highlight"><pre><span></span><code>    from prefect.variables import Variable
 
     @flow
@@ -13569,7 +13582,8 @@ <h3 id="prefect.variables.Variable.get" class="doc doc-heading">
 
             <details class="quote">
               <summary>Source code in <code>prefect/variables.py</code></summary>
-              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">66</span>
+              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">65</span>
+<span class="normal">66</span>
 <span class="normal">67</span>
 <span class="normal">68</span>
 <span class="normal">69</span>
@@ -13592,9 +13606,17 @@ <h3 id="prefect.variables.Variable.get" class="doc doc-heading">
 <span class="normal">86</span>
 <span class="normal">87</span>
 <span class="normal">88</span>
-<span class="normal">89</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@classmethod</span>
+<span class="normal">89</span>
+<span class="normal">90</span>
+<span class="normal">91</span>
+<span class="normal">92</span>
+<span class="normal">93</span>
+<span class="normal">94</span>
+<span class="normal">95</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@classmethod</span>
 <span class="nd">@sync_compatible</span>
-<span class="k">async</span> <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">default</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+<span class="k">async</span> <span class="k">def</span> <span class="nf">get</span><span class="p">(</span>
+    <span class="bp">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">default</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="s2">&quot;Variable&quot;</span><span class="p">,</span> <span class="nb">str</span><span class="p">]]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Get a variable by name. If doesn&#39;t exist return the default.</span>
 <span class="sd">    ```</span>
@@ -13615,7 +13637,12 @@ <h3 id="prefect.variables.Variable.get" class="doc doc-heading">
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="n">client</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">get_or_create_client</span><span class="p">()</span>
     <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">read_variable_by_name</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
-    <span class="k">return</span> <span class="n">variable</span> <span class="k">if</span> <span class="n">variable</span> <span class="k">else</span> <span class="n">default</span>
+
+    <span class="k">return</span> <span class="p">(</span>
+        <span class="n">Variable</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">value</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="n">variable</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">variable</span>
+        <span class="k">else</span> <span class="n">default</span>
+    <span class="p">)</span>
 </code></pre></div></td></tr></table></div>
             </details>
     </div>
@@ -13638,7 +13665,7 @@ <h3 id="prefect.variables.Variable.set" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sets a new variable. If one exists with the same name, user must pass <code>overwrite=True</code>
+        <p>Sets a new variable. If one exists with the same name, user must pass <code>overwrite=True</code>
 <div class="highlight"><pre><span></span><code>    from prefect.variables import Variable
 
     @flow
@@ -13697,8 +13724,7 @@ <h3 id="prefect.variables.Variable.set" class="doc doc-heading">
 <span class="normal">60</span>
 <span class="normal">61</span>
 <span class="normal">62</span>
-<span class="normal">63</span>
-<span class="normal">64</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@classmethod</span>
+<span class="normal">63</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@classmethod</span>
 <span class="nd">@sync_compatible</span>
 <span class="k">async</span> <span class="k">def</span> <span class="nf">set</span><span class="p">(</span>
     <span class="bp">cls</span><span class="p">,</span>
@@ -13706,7 +13732,7 @@ <h3 id="prefect.variables.Variable.set" class="doc doc-heading">
     <span class="n">value</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
     <span class="n">tags</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
-<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="s2">&quot;Variable&quot;</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Sets a new variable. If one exists with the same name, user must pass `overwrite=True`</span>
 <span class="sd">    ```</span>
@@ -13727,8 +13753,7 @@ <h3 id="prefect.variables.Variable.set" class="doc doc-heading">
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="n">client</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">get_or_create_client</span><span class="p">()</span>
     <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">read_variable_by_name</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
-    <span class="n">var_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="s2">&quot;value&quot;</span><span class="p">:</span> <span class="n">value</span><span class="p">}</span>
-    <span class="n">var_dict</span><span class="p">[</span><span class="s2">&quot;tags&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">tags</span> <span class="ow">or</span> <span class="p">[]</span>
+    <span class="n">var_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="s2">&quot;value&quot;</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span> <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="n">tags</span> <span class="ow">or</span> <span class="p">[]}</span>
     <span class="k">if</span> <span class="n">variable</span><span class="p">:</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">overwrite</span><span class="p">:</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
@@ -13772,7 +13797,7 @@ <h2 id="prefect.variables.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a variable by name. If doesn't exist return the default.
+        <p>Get a variable by name. If doesn't exist return the default.
 <div class="highlight"><pre><span></span><code>    from prefect import variables
 
     @flow
@@ -13789,13 +13814,7 @@ <h2 id="prefect.variables.get" class="doc doc-heading">
 
             <details class="quote">
               <summary>Source code in <code>prefect/variables.py</code></summary>
-              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 92</span>
-<span class="normal"> 93</span>
-<span class="normal"> 94</span>
-<span class="normal"> 95</span>
-<span class="normal"> 96</span>
-<span class="normal"> 97</span>
-<span class="normal"> 98</span>
+              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 98</span>
 <span class="normal"> 99</span>
 <span class="normal">100</span>
 <span class="normal">101</span>
@@ -13811,7 +13830,15 @@ <h2 id="prefect.variables.get" class="doc doc-heading">
 <span class="normal">111</span>
 <span class="normal">112</span>
 <span class="normal">113</span>
-<span class="normal">114</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@deprecated_callable</span><span class="p">(</span><span class="n">start_date</span><span class="o">=</span><span class="s2">&quot;Apr 2024&quot;</span><span class="p">)</span>
+<span class="normal">114</span>
+<span class="normal">115</span>
+<span class="normal">116</span>
+<span class="normal">117</span>
+<span class="normal">118</span>
+<span class="normal">119</span>
+<span class="normal">120</span>
+<span class="normal">121</span>
+<span class="normal">122</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@deprecated_callable</span><span class="p">(</span><span class="n">start_date</span><span class="o">=</span><span class="s2">&quot;Apr 2024&quot;</span><span class="p">)</span>
 <span class="nd">@sync_compatible</span>
 <span class="k">async</span> <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">default</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
@@ -13832,8 +13859,10 @@ <h2 id="prefect.variables.get" class="doc doc-heading">
 <span class="sd">            var = await variables.get(&quot;my_var&quot;)</span>
 <span class="sd">    ```</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">Variable</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
-    <span class="k">return</span> <span class="n">variable</span><span class="o">.</span><span class="n">value</span> <span class="k">if</span> <span class="n">variable</span> <span class="k">else</span> <span class="n">default</span>
+    <span class="n">variable</span> <span class="o">=</span> <span class="k">await</span> <span class="n">Variable</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">)</span>
+    <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">variable</span><span class="p">,</span> <span class="n">Variable</span><span class="p">):</span>
+        <span class="n">variable</span> <span class="o">=</span> <span class="n">variable</span><span class="o">.</span><span class="n">value</span>
+    <span class="k">return</span> <span class="n">variable</span>
 </code></pre></div></td></tr></table></div>
             </details>
     </div>
diff --git a/versions/unreleased/api-ref/prefect/workers/base/index.html b/versions/unreleased/api-ref/prefect/workers/base/index.html
index 51e23481d2..3c9ab373eb 100644
--- a/versions/unreleased/api-ref/prefect/workers/base/index.html
+++ b/versions/unreleased/api-ref/prefect/workers/base/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14042,7 +14043,7 @@ <h3 id="prefect.workers.base.BaseJobConfiguration.from_template_and_values" clas
 
     <div class="doc doc-contents ">
 
-      <p>Creates a valid worker configuration object from the provided base
+        <p>Creates a valid worker configuration object from the provided base
 configuration and overrides.</p>
 <p>Important: this method expects that the base_job_template was already
 validated server-side.</p>
@@ -14121,7 +14122,7 @@ <h3 id="prefect.workers.base.BaseJobConfiguration.json_template" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a dict with job configuration as keys and the corresponding templates as values</p>
+        <p>Returns a dict with job configuration as keys and the corresponding templates as values</p>
 <p>Defaults to using the job configuration parameter name as the template variable name.</p>
 <p>e.g.
 {
@@ -14191,7 +14192,7 @@ <h3 id="prefect.workers.base.BaseJobConfiguration.prepare_for_flow_run" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Prepare the job configuration for a flow run.</p>
+        <p>Prepare the job configuration for a flow run.</p>
 <p>This method is called by the worker before starting a flow run. It
 should be used to set any configuration values that are dependent on
 the flow run.</p>
@@ -16191,7 +16192,7 @@ <h3 id="prefect.workers.base.BaseWorker.get_all_available_worker_types" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Returns all worker types available in the local registry.</p>
+        <p>Returns all worker types available in the local registry.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/workers/base.py</code></summary>
@@ -16231,7 +16232,7 @@ <h3 id="prefect.workers.base.BaseWorker.get_status" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves the status of the current worker including its name, current worker
+        <p>Retrieves the status of the current worker including its name, current worker
 pool, the work pool queues it is polling, and its local settings.</p>
 
             <details class="quote">
@@ -16288,7 +16289,7 @@ <h3 id="prefect.workers.base.BaseWorker.get_worker_class_from_type" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns the worker class for a given worker type. If the worker type
+        <p>Returns the worker class for a given worker type. If the worker type
 is not recognized, returns None.</p>
 
             <details class="quote">
@@ -16329,7 +16330,7 @@ <h3 id="prefect.workers.base.BaseWorker.is_worker_still_polling" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>This method is invoked by a webserver healthcheck handler
+        <p>This method is invoked by a webserver healthcheck handler
 and returns a boolean indicating if the worker has recorded a
 scheduled flow run poll within a variable amount of time.</p>
 <p>The <code>query_interval_seconds</code> is the same value that is used by
@@ -16416,7 +16417,7 @@ <h3 id="prefect.workers.base.BaseWorker.kill_infrastructure" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Method for killing infrastructure created by a worker. Should be implemented by
+        <p>Method for killing infrastructure created by a worker. Should be implemented by
 individual workers if they support killing infrastructure.</p>
 
             <details class="quote">
@@ -16468,7 +16469,7 @@ <h3 id="prefect.workers.base.BaseWorker.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a given flow run on the current worker.</p>
+        <p>Runs a given flow run on the current worker.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/workers/base.py</code></summary>
@@ -16518,7 +16519,7 @@ <h3 id="prefect.workers.base.BaseWorker.setup" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the worker to run.</p>
+        <p>Prepares the worker to run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/workers/base.py</code></summary>
@@ -16566,7 +16567,7 @@ <h3 id="prefect.workers.base.BaseWorker.sync_with_backend" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Updates the worker's local information about it's current work pool and
+        <p>Updates the worker's local information about it's current work pool and
 queues. Sends a worker heartbeat to the API.</p>
 
             <details class="quote">
@@ -16611,7 +16612,7 @@ <h3 id="prefect.workers.base.BaseWorker.teardown" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Cleans up resources after the worker is stopped.</p>
+        <p>Cleans up resources after the worker is stopped.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/workers/base.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/workers/block/index.html b/versions/unreleased/api-ref/prefect/workers/block/index.html
index 36d79e6ce6..5fb6de7d03 100644
--- a/versions/unreleased/api-ref/prefect/workers/block/index.html
+++ b/versions/unreleased/api-ref/prefect/workers/block/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13584,7 +13585,7 @@ <h3 id="prefect.workers.block.BlockWorkerJobConfiguration.from_template_and_valu
 
     <div class="doc doc-contents ">
 
-      <p>Creates a valid worker configuration object from the provided base
+        <p>Creates a valid worker configuration object from the provided base
 configuration and overrides.</p>
 <p>Important: this method expects that the base_job_template was already
 validated server-side.</p>
@@ -13685,7 +13686,7 @@ <h3 id="prefect.workers.block.BlockWorkerJobConfiguration.json_template" class="
 
     <div class="doc doc-contents ">
 
-      <p>Returns a dict with job configuration as keys and the corresponding templates as values</p>
+        <p>Returns a dict with job configuration as keys and the corresponding templates as values</p>
 <p>Defaults to using the job configuration parameter name as the template variable name.</p>
 <p>e.g.
 {
@@ -13768,7 +13769,7 @@ <h2 id="prefect.workers.block.BlockWorkerResult" class="doc doc-heading">
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Result of a block worker job</p>
+        <p>Result of a block worker job</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/workers/block.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/workers/process/index.html b/versions/unreleased/api-ref/prefect/workers/process/index.html
index f30d971ed9..f82b45a60e 100644
--- a/versions/unreleased/api-ref/prefect/workers/process/index.html
+++ b/versions/unreleased/api-ref/prefect/workers/process/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.workers.process" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the Process worker used for executing flow runs as subprocesses.</p>
+        <p>Module containing the Process worker used for executing flow runs as subprocesses.</p>
 <p>To start a Process worker, run the following command:</p>
 <div class="highlight"><pre><span></span><code>prefect<span class="w"> </span>worker<span class="w"> </span>start<span class="w"> </span>--pool<span class="w"> </span><span class="s1">&#39;my-work-pool&#39;</span><span class="w"> </span>--type<span class="w"> </span>process
 </code></pre></div>
@@ -13373,7 +13374,7 @@ <h2 id="prefect.workers.process.ProcessWorkerResult" class="doc doc-heading">
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/workers/process.py</code></summary>
diff --git a/versions/unreleased/api-ref/prefect/workers/server/index.html b/versions/unreleased/api-ref/prefect/workers/server/index.html
index 9779fde600..840c0f33da 100644
--- a/versions/unreleased/api-ref/prefect/workers/server/index.html
+++ b/versions/unreleased/api-ref/prefect/workers/server/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13240,7 +13241,7 @@ <h2 id="prefect.workers.server.start_healthcheck_server" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Run a healthcheck FastAPI server for a worker.</p>
+        <p>Run a healthcheck FastAPI server for a worker.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/prefect/workers/utilities/index.html b/versions/unreleased/api-ref/prefect/workers/utilities/index.html
index 6166e46ade..f20467ecda 100644
--- a/versions/unreleased/api-ref/prefect/workers/utilities/index.html
+++ b/versions/unreleased/api-ref/prefect/workers/utilities/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/python/index.html b/versions/unreleased/api-ref/python/index.html
index fc0b3f84b1..0aa4241373 100644
--- a/versions/unreleased/api-ref/python/index.html
+++ b/versions/unreleased/api-ref/python/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/rest-api-reference/index.html b/versions/unreleased/api-ref/rest-api-reference/index.html
index 79da3911c7..30d05f4edc 100644
--- a/versions/unreleased/api-ref/rest-api-reference/index.html
+++ b/versions/unreleased/api-ref/rest-api-reference/index.html
@@ -205,7 +205,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/rest-api/index.html b/versions/unreleased/api-ref/rest-api/index.html
index 1b9ee5d97e..4e9a75972f 100644
--- a/versions/unreleased/api-ref/rest-api/index.html
+++ b/versions/unreleased/api-ref/rest-api/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/server/api/admin/index.html b/versions/unreleased/api-ref/server/api/admin/index.html
index f6e1cadef4..c1d472e8d5 100644
--- a/versions/unreleased/api-ref/server/api/admin/index.html
+++ b/versions/unreleased/api-ref/server/api/admin/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.server.api.admin" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for admin-level interactions with the Prefect REST API.</p>
+        <p>Routes for admin-level interactions with the Prefect REST API.</p>
 
 
 
@@ -13334,7 +13335,7 @@ <h2 id="prefect.server.api.admin.clear_database" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Clear all database tables without dropping them.</p>
+        <p>Clear all database tables without dropping them.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/admin.py</code></summary>
@@ -13396,7 +13397,7 @@ <h2 id="prefect.server.api.admin.create_database" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create all database objects.</p>
+        <p>Create all database objects.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/admin.py</code></summary>
@@ -13452,7 +13453,7 @@ <h2 id="prefect.server.api.admin.drop_database" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Drop all database objects.</p>
+        <p>Drop all database objects.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/admin.py</code></summary>
@@ -13508,7 +13509,7 @@ <h2 id="prefect.server.api.admin.read_settings" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the current Prefect REST API settings.</p>
+        <p>Get the current Prefect REST API settings.</p>
 <p>Secret setting values will be obfuscated.</p>
 
             <details class="quote">
@@ -13549,7 +13550,7 @@ <h2 id="prefect.server.api.admin.read_version" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns the Prefect version number</p>
+        <p>Returns the Prefect version number</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/admin.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/csrf_token/index.html b/versions/unreleased/api-ref/server/api/csrf_token/index.html
index 93d326a21a..60051f1568 100644
--- a/versions/unreleased/api-ref/server/api/csrf_token/index.html
+++ b/versions/unreleased/api-ref/server/api/csrf_token/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13244,7 +13245,7 @@ <h2 id="prefect.server.api.csrf_token.create_csrf_token" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Create or update a CSRF token for a client</p>
+        <p>Create or update a CSRF token for a client</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/csrf_token.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/dependencies/index.html b/versions/unreleased/api-ref/server/api/dependencies/index.html
index 0468791a8e..b7dcbcb86d 100644
--- a/versions/unreleased/api-ref/server/api/dependencies/index.html
+++ b/versions/unreleased/api-ref/server/api/dependencies/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13305,7 +13306,7 @@ <h1 id="prefect.server.api.dependencies" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for injecting FastAPI dependencies.</p>
+        <p>Utilities for injecting FastAPI dependencies.</p>
 
 
 
@@ -13332,7 +13333,7 @@ <h2 id="prefect.server.api.dependencies.EnforceMinimumAPIVersion" class="doc doc
     <div class="doc doc-contents ">
 
 
-      <p>FastAPI Dependency used to check compatibility between the version of the api
+        <p>FastAPI Dependency used to check compatibility between the version of the api
 and a given request.</p>
 <p>Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it
 to the api's version. Rejects requests that are lower than the minimum version.</p>
@@ -13493,7 +13494,7 @@ <h2 id="prefect.server.api.dependencies.LimitBody" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A <code>fastapi.Depends</code> factory for pulling a <code>limit: int</code> parameter from the
+        <p>A <code>fastapi.Depends</code> factory for pulling a <code>limit: int</code> parameter from the
 request body while determining the default from the current settings.</p>
 
             <details class="quote">
@@ -13568,7 +13569,7 @@ <h2 id="prefect.server.api.dependencies.get_created_by" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A dependency that returns the provenance information to use when creating objects
+        <p>A dependency that returns the provenance information to use when creating objects
 during this API call.</p>
 
             <details class="quote">
@@ -13629,7 +13630,7 @@ <h2 id="prefect.server.api.dependencies.get_updated_by" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A dependency that returns the provenance information to use when updating objects
+        <p>A dependency that returns the provenance information to use when updating objects
 during this API call.</p>
 
             <details class="quote">
@@ -13678,7 +13679,7 @@ <h2 id="prefect.server.api.dependencies.is_ephemeral_request" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>A dependency that returns whether the request is to an ephemeral server.</p>
+        <p>A dependency that returns whether the request is to an ephemeral server.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/dependencies.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/deployments/index.html b/versions/unreleased/api-ref/server/api/deployments/index.html
index e31339b883..e20f387a5b 100644
--- a/versions/unreleased/api-ref/server/api/deployments/index.html
+++ b/versions/unreleased/api-ref/server/api/deployments/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13459,7 +13460,7 @@ <h1 id="prefect.server.api.deployments" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with Deployment objects.</p>
+        <p>Routes for interacting with Deployment objects.</p>
 
 
 
@@ -13488,7 +13489,7 @@ <h2 id="prefect.server.api.deployments.count_deployments" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Count deployments.</p>
+        <p>Count deployments.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -13558,7 +13559,7 @@ <h2 id="prefect.server.api.deployments.create_deployment" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Gracefully creates a new deployment from the provided schema. If a deployment with
+        <p>Gracefully creates a new deployment from the provided schema. If a deployment with
 the same name and flow_id already exists, the deployment is updated.</p>
 <p>If the deployment has an active schedule, flow runs will be scheduled.
 When upserting, any scheduled runs from the existing deployment will be deleted.</p>
@@ -13833,7 +13834,7 @@ <h2 id="prefect.server.api.deployments.create_flow_run_from_deployment" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run from a deployment.</p>
+        <p>Create a flow run from a deployment.</p>
 <p>Any parameters not provided will be inferred from the deployment's parameters.
 If tags are not provided, the deployment's tags will be used.</p>
 <p>If no state is provided, the flow run will be created in a SCHEDULED state.</p>
@@ -14116,7 +14117,7 @@ <h2 id="prefect.server.api.deployments.delete_deployment" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Delete a deployment by id.</p>
+        <p>Delete a deployment by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14172,7 +14173,7 @@ <h2 id="prefect.server.api.deployments.get_scheduled_flow_runs_for_deployments"
 
     <div class="doc doc-contents ">
 
-      <p>Get scheduled runs for a set of deployments. Used by a runner to poll for work.</p>
+        <p>Get scheduled runs for a set of deployments. Used by a runner to poll for work.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14288,7 +14289,7 @@ <h2 id="prefect.server.api.deployments.pause_deployment" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
+        <p>Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
 state will be deleted.</p>
 
             <details class="quote">
@@ -14399,7 +14400,7 @@ <h2 id="prefect.server.api.deployments.read_deployment" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a deployment by id.</p>
+        <p>Get a deployment by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14457,7 +14458,7 @@ <h2 id="prefect.server.api.deployments.read_deployment_by_name" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Get a deployment using the name of the flow and the deployment.</p>
+        <p>Get a deployment using the name of the flow and the deployment.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14517,7 +14518,7 @@ <h2 id="prefect.server.api.deployments.read_deployments" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Query for deployments.</p>
+        <p>Query for deployments.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14611,7 +14612,7 @@ <h2 id="prefect.server.api.deployments.resume_deployment" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Set a deployment schedule to active. Runs will be scheduled immediately.</p>
+        <p>Set a deployment schedule to active. Runs will be scheduled immediately.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/deployments.py</code></summary>
@@ -14695,7 +14696,7 @@ <h2 id="prefect.server.api.deployments.schedule_deployment" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Schedule runs for a deployment. For backfills, provide start/end times in the past.</p>
+        <p>Schedule runs for a deployment. For backfills, provide start/end times in the past.</p>
 <p>This function will generate the minimum number of runs that satisfy the min
 and max times, and the min and max counts. Specifically, the following order
 will be respected.</p>
@@ -14804,7 +14805,7 @@ <h2 id="prefect.server.api.deployments.work_queue_check_for_deployment" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Get list of work-queues that are able to pick up the specified deployment.</p>
+        <p>Get list of work-queues that are able to pick up the specified deployment.</p>
 <p>This endpoint is intended to be used by the UI to provide users warnings
 about deployments that are unable to be executed because there are no work
 queues that will pick up their runs, based on existing filter criteria. It
diff --git a/versions/unreleased/api-ref/server/api/flow_run_states/index.html b/versions/unreleased/api-ref/server/api/flow_run_states/index.html
index fe2b325887..58db709f8e 100644
--- a/versions/unreleased/api-ref/server/api/flow_run_states/index.html
+++ b/versions/unreleased/api-ref/server/api/flow_run_states/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.server.api.flow_run_states" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with flow run state objects.</p>
+        <p>Routes for interacting with flow run state objects.</p>
 
 
 
@@ -13268,7 +13269,7 @@ <h2 id="prefect.server.api.flow_run_states.read_flow_run_state" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Get a flow run state by id.</p>
+        <p>Get a flow run state by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_run_states.py</code></summary>
@@ -13330,7 +13331,7 @@ <h2 id="prefect.server.api.flow_run_states.read_flow_run_states" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Get states associated with a flow run.</p>
+        <p>Get states associated with a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_run_states.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/flow_runs/index.html b/versions/unreleased/api-ref/server/api/flow_runs/index.html
index 1dae0ff344..78b5b54953 100644
--- a/versions/unreleased/api-ref/server/api/flow_runs/index.html
+++ b/versions/unreleased/api-ref/server/api/flow_runs/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13547,7 +13548,7 @@ <h1 id="prefect.server.api.flow_runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with flow run objects.</p>
+        <p>Routes for interacting with flow run objects.</p>
 
 
 
@@ -13576,7 +13577,7 @@ <h2 id="prefect.server.api.flow_runs.average_flow_run_lateness" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Query for average flow-run lateness in seconds.</p>
+        <p>Query for average flow-run lateness in seconds.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -13716,7 +13717,7 @@ <h2 id="prefect.server.api.flow_runs.count_flow_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for flow runs.</p>
+        <p>Query for flow runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -13786,7 +13787,7 @@ <h2 id="prefect.server.api.flow_runs.create_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a flow run. If a flow run with the same flow_id and
+        <p>Create a flow run. If a flow run with the same flow_id and
 idempotency key already exists, the existing flow run will be returned.</p>
 <p>If no state is provided, the flow run will be created in a PENDING state.</p>
 
@@ -13888,7 +13889,7 @@ <h2 id="prefect.server.api.flow_runs.create_flow_run_input" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Create a key/value input for a flow run.</p>
+        <p>Create a key/value input for a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -13980,7 +13981,7 @@ <h2 id="prefect.server.api.flow_runs.delete_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run by id.</p>
+        <p>Delete a flow run by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14036,7 +14037,7 @@ <h2 id="prefect.server.api.flow_runs.delete_flow_run_input" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run input</p>
+        <p>Delete a flow run input</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14100,7 +14101,7 @@ <h2 id="prefect.server.api.flow_runs.filter_flow_run_input" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Filter flow run inputs by key prefix</p>
+        <p>Filter flow run inputs by key prefix</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14170,7 +14171,7 @@ <h2 id="prefect.server.api.flow_runs.flow_run_history" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for flow run history data across a given range and interval.</p>
+        <p>Query for flow run history data across a given range and interval.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14278,7 +14279,7 @@ <h2 id="prefect.server.api.flow_runs.read_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a flow run by id.</p>
+        <p>Get a flow run by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14332,7 +14333,7 @@ <h2 id="prefect.server.api.flow_runs.read_flow_run_graph_v1" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get a task run dependency map for a given flow run.</p>
+        <p>Get a task run dependency map for a given flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14380,7 +14381,7 @@ <h2 id="prefect.server.api.flow_runs.read_flow_run_graph_v2" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get a graph of the tasks and subflow runs for the given flow run</p>
+        <p>Get a graph of the tasks and subflow runs for the given flow run</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14452,7 +14453,7 @@ <h2 id="prefect.server.api.flow_runs.read_flow_run_input" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Create a value from a flow run input</p>
+        <p>Create a value from a flow run input</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14518,7 +14519,7 @@ <h2 id="prefect.server.api.flow_runs.read_flow_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for flow runs.</p>
+        <p>Query for flow runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14620,7 +14621,7 @@ <h2 id="prefect.server.api.flow_runs.resume_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Resume a paused flow run.</p>
+        <p>Resume a paused flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -14934,7 +14935,7 @@ <h2 id="prefect.server.api.flow_runs.set_flow_run_state" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Set a flow run state, invoking any orchestration rules.</p>
+        <p>Set a flow run state, invoking any orchestration rules.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
@@ -15056,7 +15057,7 @@ <h2 id="prefect.server.api.flow_runs.update_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates a flow run.</p>
+        <p>Updates a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flow_runs.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/flows/index.html b/versions/unreleased/api-ref/server/api/flows/index.html
index 6411da5686..78fe6827a4 100644
--- a/versions/unreleased/api-ref/server/api/flows/index.html
+++ b/versions/unreleased/api-ref/server/api/flows/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13349,7 +13350,7 @@ <h1 id="prefect.server.api.flows" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with flow objects.</p>
+        <p>Routes for interacting with flow objects.</p>
 
 
 
@@ -13378,7 +13379,7 @@ <h2 id="prefect.server.api.flows.count_flows" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Count flows.</p>
+        <p>Count flows.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
@@ -13444,7 +13445,7 @@ <h2 id="prefect.server.api.flows.create_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gracefully creates a new flow from the provided schema. If a flow with the
+        <p>Gracefully creates a new flow from the provided schema. If a flow with the
 same name already exists, the existing flow is returned.</p>
 
             <details class="quote">
@@ -13509,7 +13510,7 @@ <h2 id="prefect.server.api.flows.delete_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow by id.</p>
+        <p>Delete a flow by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
@@ -13561,7 +13562,7 @@ <h2 id="prefect.server.api.flows.read_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a flow by id.</p>
+        <p>Get a flow by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
@@ -13615,7 +13616,7 @@ <h2 id="prefect.server.api.flows.read_flow_by_name" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a flow by name.</p>
+        <p>Get a flow by name.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
@@ -13669,7 +13670,7 @@ <h2 id="prefect.server.api.flows.read_flows" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for flows.</p>
+        <p>Query for flows.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
@@ -13747,7 +13748,7 @@ <h2 id="prefect.server.api.flows.update_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates a flow.</p>
+        <p>Updates a flow.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/flows.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/middleware/index.html b/versions/unreleased/api-ref/server/api/middleware/index.html
index 745d322118..d414e2ddcb 100644
--- a/versions/unreleased/api-ref/server/api/middleware/index.html
+++ b/versions/unreleased/api-ref/server/api/middleware/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13278,7 +13279,7 @@ <h2 id="prefect.server.api.middleware.CsrfMiddleware" class="doc doc-heading">
               Bases: <code><span title="prefect._vendor.starlette.middleware.base.BaseHTTPMiddleware">BaseHTTPMiddleware</span></code></p>
 
 
-      <p>Middleware for CSRF protection. This middleware will check for a CSRF token
+        <p>Middleware for CSRF protection. This middleware will check for a CSRF token
 in the headers of any POST, PUT, PATCH, or DELETE request. If the token is
 not present or does not match the token stored in the database for the
 client, the request will be rejected with a 403 status code.</p>
@@ -13432,7 +13433,7 @@ <h3 id="prefect.server.api.middleware.CsrfMiddleware.dispatch" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Dispatch method for the middleware. This method will check for the
+        <p>Dispatch method for the middleware. This method will check for the
 presence of a CSRF token in the headers of the request and compare it
 to the token stored in the database for the client. If the token is not
 present or does not match, the request will be rejected with a 403
diff --git a/versions/unreleased/api-ref/server/api/run_history/index.html b/versions/unreleased/api-ref/server/api/run_history/index.html
index 64c2dce30d..10c3cbc87b 100644
--- a/versions/unreleased/api-ref/server/api/run_history/index.html
+++ b/versions/unreleased/api-ref/server/api/run_history/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13217,7 +13218,7 @@ <h1 id="prefect.server.api.run_history" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for querying flow and task run history.</p>
+        <p>Utilities for querying flow and task run history.</p>
 
 
 
@@ -13246,7 +13247,7 @@ <h2 id="prefect.server.api.run_history.run_history" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Produce a history of runs aggregated by interval and state</p>
+        <p>Produce a history of runs aggregated by interval and state</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/run_history.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/saved_searches/index.html b/versions/unreleased/api-ref/server/api/saved_searches/index.html
index 3dcd7f3714..4e81462cd3 100644
--- a/versions/unreleased/api-ref/server/api/saved_searches/index.html
+++ b/versions/unreleased/api-ref/server/api/saved_searches/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13283,7 +13284,7 @@ <h1 id="prefect.server.api.saved_searches" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with saved search objects.</p>
+        <p>Routes for interacting with saved search objects.</p>
 
 
 
@@ -13312,7 +13313,7 @@ <h2 id="prefect.server.api.saved_searches.create_saved_search" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Gracefully creates a new saved search from the provided schema.</p>
+        <p>Gracefully creates a new saved search from the provided schema.</p>
 <p>If a saved search with the same name already exists, the saved search's fields are
 replaced.</p>
 
@@ -13390,7 +13391,7 @@ <h2 id="prefect.server.api.saved_searches.delete_saved_search" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Delete a saved search by id.</p>
+        <p>Delete a saved search by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/saved_searches.py</code></summary>
@@ -13446,7 +13447,7 @@ <h2 id="prefect.server.api.saved_searches.read_saved_search" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get a saved search by id.</p>
+        <p>Get a saved search by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/saved_searches.py</code></summary>
@@ -13504,7 +13505,7 @@ <h2 id="prefect.server.api.saved_searches.read_saved_searches" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Query for saved searches.</p>
+        <p>Query for saved searches.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/saved_searches.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/server/index.html b/versions/unreleased/api-ref/server/api/server/index.html
index 69552bf547..eeab5ad9b3 100644
--- a/versions/unreleased/api-ref/server/api/server/index.html
+++ b/versions/unreleased/api-ref/server/api/server/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13393,7 +13394,7 @@ <h1 id="prefect.server.api.server" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Defines the Prefect REST API FastAPI app.</p>
+        <p>Defines the Prefect REST API FastAPI app.</p>
 
 
 
@@ -13420,7 +13421,7 @@ <h2 id="prefect.server.api.server.RequestLimitMiddleware" class="doc doc-heading
     <div class="doc doc-contents ">
 
 
-      <p>A middleware that limits the number of concurrent requests handled by the API.</p>
+        <p>A middleware that limits the number of concurrent requests handled by the API.</p>
 <p>This is a blunt tool for limiting SQLite concurrent writes which will cause failures
 at high volume. Ideally, we would only apply the limit to routes that perform
 writes.</p>
@@ -13497,7 +13498,7 @@ <h2 id="prefect.server.api.server.SPAStaticFiles" class="doc doc-heading">
               Bases: <code><span title="prefect._vendor.fastapi.staticfiles.StaticFiles">StaticFiles</span></code></p>
 
 
-      <p>Implementation of <code>StaticFiles</code> for serving single page applications.</p>
+        <p>Implementation of <code>StaticFiles</code> for serving single page applications.</p>
 <p>Adds <code>get_response</code> handling to ensure that when a resource isn't found the
 application still returns the index.</p>
 
@@ -13563,7 +13564,7 @@ <h2 id="prefect.server.api.server.create_api_app" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a FastAPI app that includes the Prefect REST API</p>
+        <p>Create a FastAPI app that includes the Prefect REST API</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13855,7 +13856,7 @@ <h2 id="prefect.server.api.server.create_app" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create an FastAPI app that includes the Prefect REST API and UI</p>
+        <p>Create an FastAPI app that includes the Prefect REST API and UI</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14419,7 +14420,7 @@ <h2 id="prefect.server.api.server.custom_internal_exception_handler" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Log a detailed exception for internal server errors before returning.</p>
+        <p>Log a detailed exception for internal server errors before returning.</p>
 <p>Send 503 for errors clients can retry on.</p>
 
             <details class="quote">
@@ -14480,7 +14481,7 @@ <h2 id="prefect.server.api.server.integrity_exception_handler" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Capture database integrity errors.</p>
+        <p>Capture database integrity errors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/server.py</code></summary>
@@ -14530,7 +14531,7 @@ <h2 id="prefect.server.api.server.prefect_object_not_found_exception_handler" cl
 
     <div class="doc doc-contents ">
 
-      <p>Return 404 status code on object not found exceptions.</p>
+        <p>Return 404 status code on object not found exceptions.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/server.py</code></summary>
@@ -14564,7 +14565,7 @@ <h2 id="prefect.server.api.server.replace_placeholder_string_in_files" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Recursively loops through all files in the given directory and replaces
+        <p>Recursively loops through all files in the given directory and replaces
 a placeholder string.</p>
 
             <details class="quote">
@@ -14633,7 +14634,7 @@ <h2 id="prefect.server.api.server.validation_exception_handler" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Provide a detailed message for request validation errors.</p>
+        <p>Provide a detailed message for request validation errors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/server.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/task_run_states/index.html b/versions/unreleased/api-ref/server/api/task_run_states/index.html
index 35481e271d..41d17c737a 100644
--- a/versions/unreleased/api-ref/server/api/task_run_states/index.html
+++ b/versions/unreleased/api-ref/server/api/task_run_states/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13239,7 +13240,7 @@ <h1 id="prefect.server.api.task_run_states" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with task run state objects.</p>
+        <p>Routes for interacting with task run state objects.</p>
 
 
 
@@ -13268,7 +13269,7 @@ <h2 id="prefect.server.api.task_run_states.read_task_run_state" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Get a task run state by id.</p>
+        <p>Get a task run state by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_run_states.py</code></summary>
@@ -13330,7 +13331,7 @@ <h2 id="prefect.server.api.task_run_states.read_task_run_states" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Get states associated with a task run.</p>
+        <p>Get states associated with a task run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_run_states.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/api/task_runs/index.html b/versions/unreleased/api-ref/server/api/task_runs/index.html
index 16a387242d..48e1d7243b 100644
--- a/versions/unreleased/api-ref/server/api/task_runs/index.html
+++ b/versions/unreleased/api-ref/server/api/task_runs/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13371,7 +13372,7 @@ <h1 id="prefect.server.api.task_runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Routes for interacting with task run objects.</p>
+        <p>Routes for interacting with task run objects.</p>
 
 
 
@@ -13400,7 +13401,7 @@ <h2 id="prefect.server.api.task_runs.count_task_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Count task runs.</p>
+        <p>Count task runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13462,7 +13463,7 @@ <h2 id="prefect.server.api.task_runs.create_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a task run. If a task run with the same flow_run_id,
+        <p>Create a task run. If a task run with the same flow_run_id,
 task_key, and dynamic_key already exists, the existing task
 run will be returned.</p>
 <p>If no state is provided, the task run will be created in a PENDING state.</p>
@@ -13571,7 +13572,7 @@ <h2 id="prefect.server.api.task_runs.delete_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a task run by id.</p>
+        <p>Delete a task run by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13623,7 +13624,7 @@ <h2 id="prefect.server.api.task_runs.read_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get a task run by id.</p>
+        <p>Get a task run by id.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13677,7 +13678,7 @@ <h2 id="prefect.server.api.task_runs.read_task_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for task runs.</p>
+        <p>Query for task runs.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13751,7 +13752,7 @@ <h2 id="prefect.server.api.task_runs.set_task_run_state" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Set a task run state, invoking any orchestration rules.</p>
+        <p>Set a task run state, invoking any orchestration rules.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13867,7 +13868,7 @@ <h2 id="prefect.server.api.task_runs.task_run_history" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Query for task run history data across a given range and interval.</p>
+        <p>Query for task run history data across a given range and interval.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
@@ -13967,7 +13968,7 @@ <h2 id="prefect.server.api.task_runs.update_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates a task run.</p>
+        <p>Updates a task run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/api/task_runs.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/index.html b/versions/unreleased/api-ref/server/index.html
index 80f835383a..e6b231d603 100644
--- a/versions/unreleased/api-ref/server/index.html
+++ b/versions/unreleased/api-ref/server/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/server/models/csrf_token/index.html b/versions/unreleased/api-ref/server/models/csrf_token/index.html
index 884d0e8a6f..01a74f6307 100644
--- a/versions/unreleased/api-ref/server/models/csrf_token/index.html
+++ b/versions/unreleased/api-ref/server/models/csrf_token/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13286,7 +13287,7 @@ <h2 id="prefect.server.models.csrf_token.create_or_update_csrf_token" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create or update a CSRF token for a client. If the client already has a
+        <p>Create or update a CSRF token for a client. If the client already has a
 token, it will be updated.</p>
 
 
@@ -13453,7 +13454,7 @@ <h2 id="prefect.server.models.csrf_token.delete_expired_tokens" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Delete expired CSRF tokens.</p>
+        <p>Delete expired CSRF tokens.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13563,7 +13564,7 @@ <h2 id="prefect.server.models.csrf_token.read_token_for_client" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Read a CSRF token for a client.</p>
+        <p>Read a CSRF token for a client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/deployments/index.html b/versions/unreleased/api-ref/server/models/deployments/index.html
index 793a53a262..90b4c1044b 100644
--- a/versions/unreleased/api-ref/server/models/deployments/index.html
+++ b/versions/unreleased/api-ref/server/models/deployments/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13501,7 +13502,7 @@ <h1 id="prefect.server.models.deployments" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with deployment ORM objects.
+        <p>Functions for interacting with deployment ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13531,7 +13532,7 @@ <h2 id="prefect.server.models.deployments.check_work_queues_for_deployment" clas
 
     <div class="doc doc-contents ">
 
-      <p>Get work queues that can pick up the specified deployment.</p>
+        <p>Get work queues that can pick up the specified deployment.</p>
 <p>Work queues will pick up a deployment when all of the following are met.</p>
 <ul>
 <li>The deployment has ALL tags that the work queue has (i.e. the work
@@ -13704,7 +13705,7 @@ <h2 id="prefect.server.models.deployments.count_deployments" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Count deployments.</p>
+        <p>Count deployments.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13946,7 +13947,7 @@ <h2 id="prefect.server.models.deployments.create_deployment" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Upserts a deployment.</p>
+        <p>Upserts a deployment.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14236,7 +14237,7 @@ <h2 id="prefect.server.models.deployments.create_deployment_schedules" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Creates a deployment's schedules.</p>
+        <p>Creates a deployment's schedules.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14375,7 +14376,7 @@ <h2 id="prefect.server.models.deployments.delete_deployment" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Delete a deployment by id.</p>
+        <p>Delete a deployment by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14513,7 +14514,7 @@ <h2 id="prefect.server.models.deployments.delete_deployment_schedule" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a deployment schedule.</p>
+        <p>Deletes a deployment schedule.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14630,7 +14631,7 @@ <h2 id="prefect.server.models.deployments.delete_schedules_for_deployment" class
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a deployment schedule.</p>
+        <p>Deletes a deployment schedule.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14735,7 +14736,7 @@ <h2 id="prefect.server.models.deployments.read_deployment" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Reads a deployment by id.</p>
+        <p>Reads a deployment by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14855,7 +14856,7 @@ <h2 id="prefect.server.models.deployments.read_deployment_by_name" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Reads a deployment by name.</p>
+        <p>Reads a deployment by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15013,7 +15014,7 @@ <h2 id="prefect.server.models.deployments.read_deployment_schedules" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Reads a deployment's schedules.</p>
+        <p>Reads a deployment's schedules.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15167,7 +15168,7 @@ <h2 id="prefect.server.models.deployments.read_deployments" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Read deployments.</p>
+        <p>Read deployments.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15473,7 +15474,7 @@ <h2 id="prefect.server.models.deployments.schedule_runs" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Schedule flow runs for a deployment</p>
+        <p>Schedule flow runs for a deployment</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15587,7 +15588,7 @@ <h2 id="prefect.server.models.deployments.schedule_runs" class="doc doc-heading"
           </tr>
       </tbody>
     </table>
-      <p>This function will generate the minimum number of runs that satisfy the min
+        <p>This function will generate the minimum number of runs that satisfy the min
 and max times, and the min and max counts. Specifically, the following order
 will be respected.</p>
 <div class="codehilite"><pre><span></span><code><span class="o">-</span><span class="w"> </span><span class="n">Runs</span><span class="w"> </span><span class="n">will</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="k">generated</span><span class="w"> </span><span class="k">starting</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="k">or</span><span class="w"> </span><span class="k">after</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n n-Quoted">`start_time`</span>
@@ -15766,7 +15767,7 @@ <h2 id="prefect.server.models.deployments.update_deployment" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Updates a deployment.</p>
+        <p>Updates a deployment.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16072,7 +16073,7 @@ <h2 id="prefect.server.models.deployments.update_deployment_schedule" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Updates a deployment's schedules.</p>
+        <p>Updates a deployment's schedules.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/flow_run_states/index.html b/versions/unreleased/api-ref/server/models/flow_run_states/index.html
index 86bddb5f72..f22cdb4a21 100644
--- a/versions/unreleased/api-ref/server/models/flow_run_states/index.html
+++ b/versions/unreleased/api-ref/server/models/flow_run_states/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13259,7 +13260,7 @@ <h1 id="prefect.server.models.flow_run_states" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with flow run state ORM objects.
+        <p>Functions for interacting with flow run state ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13289,7 +13290,7 @@ <h2 id="prefect.server.models.flow_run_states.delete_flow_run_state" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run state by id.</p>
+        <p>Delete a flow run state by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13417,7 +13418,7 @@ <h2 id="prefect.server.models.flow_run_states.read_flow_run_state" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Reads a flow run state by id.</p>
+        <p>Reads a flow run state by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13538,7 +13539,7 @@ <h2 id="prefect.server.models.flow_run_states.read_flow_run_states" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Reads flow runs states for a flow run.</p>
+        <p>Reads flow runs states for a flow run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/flow_runs/index.html b/versions/unreleased/api-ref/server/models/flow_runs/index.html
index ef202a41e8..a7d5390fdb 100644
--- a/versions/unreleased/api-ref/server/models/flow_runs/index.html
+++ b/versions/unreleased/api-ref/server/models/flow_runs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13391,7 +13392,7 @@ <h1 id="prefect.server.models.flow_runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with flow run ORM objects.
+        <p>Functions for interacting with flow run ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13421,7 +13422,7 @@ <h2 id="prefect.server.models.flow_runs.count_flow_runs" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Count flow runs.</p>
+        <p>Count flow runs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13631,7 +13632,7 @@ <h2 id="prefect.server.models.flow_runs.create_flow_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new flow run.</p>
+        <p>Creates a new flow run.</p>
 <p>If the provided flow run has a state attached, it will also be created.</p>
 
 
@@ -13882,7 +13883,7 @@ <h2 id="prefect.server.models.flow_runs.delete_flow_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow run by flow_run_id.</p>
+        <p>Delete a flow run by flow_run_id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14010,7 +14011,7 @@ <h2 id="prefect.server.models.flow_runs.read_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Reads a flow run by id.</p>
+        <p>Reads a flow run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14160,7 +14161,7 @@ <h2 id="prefect.server.models.flow_runs.read_flow_run_graph" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Given a flow run, return the graph of it's task and subflow runs. If a <code>since</code>
+        <p>Given a flow run, return the graph of it's task and subflow runs. If a <code>since</code>
 datetime is provided, only return items that may have changed since that time.</p>
 
             <details class="quote">
@@ -14219,7 +14220,7 @@ <h2 id="prefect.server.models.flow_runs.read_flow_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read flow runs.</p>
+        <p>Read flow runs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14529,7 +14530,7 @@ <h2 id="prefect.server.models.flow_runs.read_task_run_dependencies" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Get a task run dependency map for a given flow run.</p>
+        <p>Get a task run dependency map for a given flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/models/flow_runs.py</code></summary>
@@ -14643,7 +14644,7 @@ <h2 id="prefect.server.models.flow_runs.set_flow_run_state" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new orchestrated flow run state.</p>
+        <p>Creates a new orchestrated flow run state.</p>
 <p>Setting a new state on a run is the one of the principal actions that is governed by
 Prefect's orchestration logic. Setting a new run state will not guarantee creation,
 but instead trigger orchestration rules to govern the proposed <code>state</code> input. If
@@ -14952,7 +14953,7 @@ <h2 id="prefect.server.models.flow_runs.update_flow_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Updates a flow run.</p>
+        <p>Updates a flow run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/flows/index.html b/versions/unreleased/api-ref/server/models/flows/index.html
index 74b6f50257..b80fcda444 100644
--- a/versions/unreleased/api-ref/server/models/flows/index.html
+++ b/versions/unreleased/api-ref/server/models/flows/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13347,7 +13348,7 @@ <h1 id="prefect.server.models.flows" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with flow ORM objects.
+        <p>Functions for interacting with flow ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13377,7 +13378,7 @@ <h2 id="prefect.server.models.flows.count_flows" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Count flows.</p>
+        <p>Count flows.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13599,7 +13600,7 @@ <h2 id="prefect.server.models.flows.create_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new flow.</p>
+        <p>Creates a new flow.</p>
 <p>If a flow with the same name already exists, the existing flow is returned.</p>
 
 
@@ -13764,7 +13765,7 @@ <h2 id="prefect.server.models.flows.delete_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a flow by id.</p>
+        <p>Delete a flow by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13888,7 +13889,7 @@ <h2 id="prefect.server.models.flows.read_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Reads a flow by id.</p>
+        <p>Reads a flow by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14008,7 +14009,7 @@ <h2 id="prefect.server.models.flows.read_flow_by_name" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Reads a flow by name.</p>
+        <p>Reads a flow by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14132,7 +14133,7 @@ <h2 id="prefect.server.models.flows.read_flows" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read multiple flows.</p>
+        <p>Read multiple flows.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14404,7 +14405,7 @@ <h2 id="prefect.server.models.flows.update_flow" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates a flow.</p>
+        <p>Updates a flow.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/saved_searches/index.html b/versions/unreleased/api-ref/server/models/saved_searches/index.html
index d23372eb5f..d463a361c0 100644
--- a/versions/unreleased/api-ref/server/models/saved_searches/index.html
+++ b/versions/unreleased/api-ref/server/models/saved_searches/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13303,7 +13304,7 @@ <h1 id="prefect.server.models.saved_searches" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with saved search ORM objects.
+        <p>Functions for interacting with saved search ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13333,7 +13334,7 @@ <h2 id="prefect.server.models.saved_searches.create_saved_search" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Upserts a SavedSearch.</p>
+        <p>Upserts a SavedSearch.</p>
 <p>If a SavedSearch with the same name exists, all properties will be updated.</p>
 
 
@@ -13507,7 +13508,7 @@ <h2 id="prefect.server.models.saved_searches.delete_saved_search" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete a SavedSearch by id.</p>
+        <p>Delete a SavedSearch by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13635,7 +13636,7 @@ <h2 id="prefect.server.models.saved_searches.read_saved_search" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Reads a SavedSearch by id.</p>
+        <p>Reads a SavedSearch by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13756,7 +13757,7 @@ <h2 id="prefect.server.models.saved_searches.read_saved_search_by_name" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Reads a SavedSearch by name.</p>
+        <p>Reads a SavedSearch by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13881,7 +13882,7 @@ <h2 id="prefect.server.models.saved_searches.read_saved_searches" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Read SavedSearches.</p>
+        <p>Read SavedSearches.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/task_run_states/index.html b/versions/unreleased/api-ref/server/models/task_run_states/index.html
index 58eb3a4aa8..7e5e6c6d5d 100644
--- a/versions/unreleased/api-ref/server/models/task_run_states/index.html
+++ b/versions/unreleased/api-ref/server/models/task_run_states/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13259,7 +13260,7 @@ <h1 id="prefect.server.models.task_run_states" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with task run state ORM objects.
+        <p>Functions for interacting with task run state ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13289,7 +13290,7 @@ <h2 id="prefect.server.models.task_run_states.delete_task_run_state" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete a task run state by id.</p>
+        <p>Delete a task run state by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13417,7 +13418,7 @@ <h2 id="prefect.server.models.task_run_states.read_task_run_state" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Reads a task run state by id.</p>
+        <p>Reads a task run state by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13538,7 +13539,7 @@ <h2 id="prefect.server.models.task_run_states.read_task_run_states" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Reads task runs states for a task run.</p>
+        <p>Reads task runs states for a task run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/models/task_runs/index.html b/versions/unreleased/api-ref/server/models/task_runs/index.html
index 0b8e15aeec..33e5048369 100644
--- a/versions/unreleased/api-ref/server/models/task_runs/index.html
+++ b/versions/unreleased/api-ref/server/models/task_runs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13369,7 +13370,7 @@ <h1 id="prefect.server.models.task_runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Functions for interacting with task run ORM objects.
+        <p>Functions for interacting with task run ORM objects.
 Intended for internal use by the Prefect REST API.</p>
 
 
@@ -13399,7 +13400,7 @@ <h2 id="prefect.server.models.task_runs.count_task_runs" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Count task runs.</p>
+        <p>Count task runs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13485,7 +13486,7 @@ <h2 id="prefect.server.models.task_runs.count_task_runs" class="doc doc-heading"
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/models/task_runs.py</code></summary>
@@ -13579,7 +13580,7 @@ <h2 id="prefect.server.models.task_runs.count_task_runs_by_state" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Count task runs by state.</p>
+        <p>Count task runs by state.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13665,7 +13666,7 @@ <h2 id="prefect.server.models.task_runs.count_task_runs_by_state" class="doc doc
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/models/task_runs.py</code></summary>
@@ -13781,7 +13782,7 @@ <h2 id="prefect.server.models.task_runs.create_task_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new task run.</p>
+        <p>Creates a new task run.</p>
 <p>If a task run with the same flow_run_id, task_key, and dynamic_key already exists,
 the existing task run will be returned. If the provided task run has a state
 attached, it will also be created.</p>
@@ -14057,7 +14058,7 @@ <h2 id="prefect.server.models.task_runs.delete_task_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Delete a task run by id.</p>
+        <p>Delete a task run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14185,7 +14186,7 @@ <h2 id="prefect.server.models.task_runs.read_task_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read a task run by id.</p>
+        <p>Read a task run by id.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14308,7 +14309,7 @@ <h2 id="prefect.server.models.task_runs.read_task_runs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read task runs.</p>
+        <p>Read task runs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14579,7 +14580,7 @@ <h2 id="prefect.server.models.task_runs.set_task_run_state" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new orchestrated task run state.</p>
+        <p>Creates a new orchestrated task run state.</p>
 <p>Setting a new state on a run is the one of the principal actions that is governed by
 Prefect's orchestration logic. Setting a new run state will not guarantee creation,
 but instead trigger orchestration rules to govern the proposed <code>state</code> input. If
@@ -14868,7 +14869,7 @@ <h2 id="prefect.server.models.task_runs.update_task_run" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Updates a task run.</p>
+        <p>Updates a task run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/api-ref/server/orchestration/core_policy/index.html b/versions/unreleased/api-ref/server/orchestration/core_policy/index.html
index eb39a79de6..50de8ff425 100644
--- a/versions/unreleased/api-ref/server/orchestration/core_policy/index.html
+++ b/versions/unreleased/api-ref/server/orchestration/core_policy/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13721,7 +13722,7 @@ <h1 id="prefect.server.orchestration.core_policy" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Orchestration logic that fires on state transitions.</p>
+        <p>Orchestration logic that fires on state transitions.</p>
 <p><code>CoreFlowPolicy</code> and <code>CoreTaskPolicy</code> contain all default orchestration rules that
 Prefect enforces on a state transition.</p>
 
@@ -13752,7 +13753,7 @@ <h2 id="prefect.server.orchestration.core_policy.CoreFlowPolicy" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.policies.BaseOrchestrationPolicy" href="../policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy">BaseOrchestrationPolicy</a></code></p>
 
 
-      <p>Orchestration rules that run against flow-run-state transitions in priority order.</p>
+        <p>Orchestration rules that run against flow-run-state transitions in priority order.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -13832,7 +13833,7 @@ <h2 id="prefect.server.orchestration.core_policy.CoreTaskPolicy" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.policies.BaseOrchestrationPolicy" href="../policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy">BaseOrchestrationPolicy</a></code></p>
 
 
-      <p>Orchestration rules that run against task-run-state transitions in priority order.</p>
+        <p>Orchestration rules that run against task-run-state transitions in priority order.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -13912,7 +13913,7 @@ <h2 id="prefect.server.orchestration.core_policy.AutonomousTaskPolicy" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.policies.BaseOrchestrationPolicy" href="../policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy">BaseOrchestrationPolicy</a></code></p>
 
 
-      <p>Orchestration rules that run against task-run-state transitions in priority order.</p>
+        <p>Orchestration rules that run against task-run-state transitions in priority order.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -13994,7 +13995,7 @@ <h2 id="prefect.server.orchestration.core_policy.SecureTaskConcurrencySlots" cla
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Checks relevant concurrency slots are available before entering a Running state.</p>
+        <p>Checks relevant concurrency slots are available before entering a Running state.</p>
 <p>This rule checks if concurrency limits have been set on the tags associated with a
 TaskRun. If so, a concurrency slot will be secured against each concurrency limit
 before being allowed to transition into a running state. If a concurrency limit has
@@ -14197,7 +14198,7 @@ <h2 id="prefect.server.orchestration.core_policy.ReleaseTaskConcurrencySlots" cl
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Releases any concurrency slots held by a run upon exiting a Running or
+        <p>Releases any concurrency slots held by a run upon exiting a Running or
 Cancelling state.</p>
 
               <details class="quote">
@@ -14294,7 +14295,7 @@ <h2 id="prefect.server.orchestration.core_policy.AddUnknownResult" class="doc do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Assign an "unknown" result to runs that are forced to complete from a
+        <p>Assign an "unknown" result to runs that are forced to complete from a
 failed or crashed state, if the previous state used a persisted result.</p>
 <p>When we retry a flow run, we retry any task runs that were in a failed or
 crashed state, but we also retry completed task runs that didn't use a
@@ -14424,7 +14425,7 @@ <h2 id="prefect.server.orchestration.core_policy.CacheInsertion" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Caches completed states with cache keys after they are validated.</p>
+        <p>Caches completed states with cache keys after they are validated.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -14520,7 +14521,7 @@ <h2 id="prefect.server.orchestration.core_policy.CacheRetrieval" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Rejects running states if a completed state has been cached.</p>
+        <p>Rejects running states if a completed state has been cached.</p>
 <p>This rule rejects transitions into a running state with a cache key if the key
 has already been associated with a completed state in the cache table. The client
 will be instructed to transition into the cached completed state instead.</p>
@@ -14655,7 +14656,7 @@ <h2 id="prefect.server.orchestration.core_policy.RetryFailedFlows" class="doc do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p>
+        <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p>
 <p>This rule rejects transitions into a failed state if <code>retries</code> has been
 set and the run count has not reached the specified limit. The client will be
 instructed to transition into a scheduled state to retry flow execution.</p>
@@ -14832,7 +14833,7 @@ <h2 id="prefect.server.orchestration.core_policy.RetryFailedTasks" class="doc do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p>
+        <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p>
 <p>This rule rejects transitions into a failed state if <code>retries</code> has been
 set, the run count has not reached the specified limit, and the client
 asserts it is a retriable task run. The client will be instructed to
@@ -14972,7 +14973,7 @@ <h2 id="prefect.server.orchestration.core_policy.EnqueueScheduledTasks" class="d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Enqueues autonomous task runs when they are scheduled</p>
+        <p>Enqueues autonomous task runs when they are scheduled</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -15080,7 +15081,7 @@ <h2 id="prefect.server.orchestration.core_policy.RenameReruns" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Name the states if they have run more than once.</p>
+        <p>Name the states if they have run more than once.</p>
 <p>In the special case where the initial state is an "AwaitingRetry" scheduled state,
 the proposed state will be renamed to "Retrying" instead.</p>
 
@@ -15170,7 +15171,7 @@ <h2 id="prefect.server.orchestration.core_policy.CopyScheduledTime" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Ensures scheduled time is copied from scheduled states to pending states.</p>
+        <p>Ensures scheduled time is copied from scheduled states to pending states.</p>
 <p>If a new scheduled time has been proposed on the pending state, the scheduled time
 on the scheduled state will be ignored.</p>
 
@@ -15256,7 +15257,7 @@ <h2 id="prefect.server.orchestration.core_policy.WaitForScheduledTime" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Prevents transitions to running states from happening to early.</p>
+        <p>Prevents transitions to running states from happening to early.</p>
 <p>This rule enforces that all scheduled states will only start with the machine clock
 used by the Prefect REST API instance. This rule will identify transitions from scheduled
 states that are too early and nullify them. Instead, no state will be written to the
@@ -15369,7 +15370,7 @@ <h2 id="prefect.server.orchestration.core_policy.HandlePausingFlows" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Governs runs attempting to enter a Paused/Suspended state</p>
+        <p>Governs runs attempting to enter a Paused/Suspended state</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -15531,7 +15532,7 @@ <h2 id="prefect.server.orchestration.core_policy.HandleResumingPausedFlows" clas
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Governs runs attempting to leave a Paused state</p>
+        <p>Governs runs attempting to leave a Paused state</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -15697,7 +15698,7 @@ <h2 id="prefect.server.orchestration.core_policy.UpdateFlowRunTrackerOnTasks" cl
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Tracks the flow run attempt a task run state is associated with.</p>
+        <p>Tracks the flow run attempt a task run state is associated with.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -15789,7 +15790,7 @@ <h2 id="prefect.server.orchestration.core_policy.HandleTaskTerminalStateTransiti
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>We do not allow tasks to leave terminal states if:
+        <p>We do not allow tasks to leave terminal states if:
 - The task is completed and has a persisted result
 - The task is going to CANCELLING / PAUSED / CRASHED</p>
 <p>We reset the run count when a task leaves a terminal state for a non-terminal state
@@ -15951,7 +15952,7 @@ <h2 id="prefect.server.orchestration.core_policy.HandleFlowTerminalStateTransiti
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>We do not allow flows to leave terminal states if:
+        <p>We do not allow flows to leave terminal states if:
 - The flow is completed and has a persisted result
 - The flow is going to CANCELLING / PAUSED / CRASHED
 - The flow is going to scheduled and has no deployment</p>
@@ -16132,7 +16133,7 @@ <h2 id="prefect.server.orchestration.core_policy.PreventPendingTransitions" clas
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Prevents transitions to PENDING.</p>
+        <p>Prevents transitions to PENDING.</p>
 <p>This rule is only used for flow runs.</p>
 <p>This is intended to prevent race conditions during duplicate submissions of runs.
 Before a run is submitted to its execution environment, it should be placed in a
@@ -16271,7 +16272,7 @@ <h2 id="prefect.server.orchestration.core_policy.PreventRunningTasksFromStoppedF
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Prevents running tasks from stopped flows.</p>
+        <p>Prevents running tasks from stopped flows.</p>
 <p>A running state implies execution, but also the converse. This rule ensures that a
 flow's tasks cannot be run unless the flow is also running.</p>
 
@@ -16405,7 +16406,7 @@ <h2 id="prefect.server.orchestration.core_policy.EnforceCancellingToCancelledTra
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Rejects transitions from Cancelling to any terminal state except for Cancelled.</p>
+        <p>Rejects transitions from Cancelling to any terminal state except for Cancelled.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/core_policy.py</code></summary>
@@ -16491,7 +16492,7 @@ <h2 id="prefect.server.orchestration.core_policy.BypassCancellingFlowRunsWithNoI
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled,
+        <p>Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled,
 if the flow run has no associated infrastructure process ID. Also Rejects transitions from
 Paused to Cancelling if the Paused state's details indicates the flow run has been suspended,
 exiting the flow and tearing down infra.</p>
@@ -16618,7 +16619,7 @@ <h2 id="prefect.server.orchestration.core_policy.PreventDuplicateTransitions" cl
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseOrchestrationRule" href="../rules/#prefect.server.orchestration.rules.BaseOrchestrationRule">BaseOrchestrationRule</a></code></p>
 
 
-      <p>Prevent duplicate transitions from being made right after one another.</p>
+        <p>Prevent duplicate transitions from being made right after one another.</p>
 <p>This rule allows for clients to set an optional transition_id on a state. If the
 run's next transition has the same transition_id, the transition will be
 rejected and the existing state will be returned.</p>
diff --git a/versions/unreleased/api-ref/server/orchestration/global_policy/index.html b/versions/unreleased/api-ref/server/orchestration/global_policy/index.html
index 9b7f0a2636..03e5742c84 100644
--- a/versions/unreleased/api-ref/server/orchestration/global_policy/index.html
+++ b/versions/unreleased/api-ref/server/orchestration/global_policy/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13545,7 +13546,7 @@ <h1 id="prefect.server.orchestration.global_policy" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Bookkeeping logic that fires on every state transition.</p>
+        <p>Bookkeeping logic that fires on every state transition.</p>
 <p>For clarity, <code>GlobalFlowpolicy</code> and <code>GlobalTaskPolicy</code> contain all transition logic
 implemented using <a class="autorefs autorefs-internal" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform"><code>BaseUniversalTransform</code></a>.
 None of these operations modify state, and regardless of what orchestration Prefect REST API might
@@ -13580,7 +13581,7 @@ <h2 id="prefect.server.orchestration.global_policy.GlobalFlowPolicy" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.policies.BaseOrchestrationPolicy" href="../policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy">BaseOrchestrationPolicy</a></code></p>
 
 
-      <p>Global transforms that run against flow-run-state transitions in priority order.</p>
+        <p>Global transforms that run against flow-run-state transitions in priority order.</p>
 <p>These transforms are intended to run immediately before and after a state transition
 is validated.</p>
 
@@ -13654,7 +13655,7 @@ <h2 id="prefect.server.orchestration.global_policy.GlobalTaskPolicy" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.policies.BaseOrchestrationPolicy" href="../policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy">BaseOrchestrationPolicy</a></code></p>
 
 
-      <p>Global transforms that run against task-run-state transitions in priority order.</p>
+        <p>Global transforms that run against task-run-state transitions in priority order.</p>
 <p>These transforms are intended to run immediately before and after a state transition
 is validated.</p>
 
@@ -13722,7 +13723,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetRunStateType" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Updates the state type of a run on a state transition.</p>
+        <p>Updates the state type of a run on a state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -13786,7 +13787,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetRunStateName" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Updates the state name of a run on a state transition.</p>
+        <p>Updates the state name of a run on a state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -13850,7 +13851,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetStartTime" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the time a run enters a running state for the first time.</p>
+        <p>Records the time a run enters a running state for the first time.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -13918,7 +13919,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetRunStateTimestamp" class="
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the time a run changes states.</p>
+        <p>Records the time a run changes states.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -13982,7 +13983,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetEndTime" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the time a run enters a terminal state.</p>
+        <p>Records the time a run enters a terminal state.</p>
 <p>With normal client usage, a run will not transition out of a terminal state.
 However, it's possible to force these transitions manually via the API. While
 leaving a terminal state, the end time will be unset.</p>
@@ -14081,7 +14082,7 @@ <h2 id="prefect.server.orchestration.global_policy.IncrementRunTime" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the amount of time a run spends in the running state.</p>
+        <p>Records the amount of time a run spends in the running state.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -14153,7 +14154,7 @@ <h2 id="prefect.server.orchestration.global_policy.IncrementFlowRunCount" class=
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the number of times a run enters a running state. For use with retries.</p>
+        <p>Records the number of times a run enters a running state. For use with retries.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -14233,7 +14234,7 @@ <h2 id="prefect.server.orchestration.global_policy.RemoveResumingIndicator" clas
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Removes the indicator on a flow run that marks it as resuming.</p>
+        <p>Removes the indicator on a flow run that marks it as resuming.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -14311,7 +14312,7 @@ <h2 id="prefect.server.orchestration.global_policy.IncrementTaskRunCount" class=
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the number of times a run enters a running state. For use with retries.</p>
+        <p>Records the number of times a run enters a running state. For use with retries.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -14379,7 +14380,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetExpectedStartTime" class="
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Estimates the time a state is expected to start running if not set.</p>
+        <p>Estimates the time a state is expected to start running if not set.</p>
 <p>For scheduled states, this estimate is simply the scheduled time. For other states,
 this is set to the time the proposed state was created by Prefect.</p>
 
@@ -14463,7 +14464,7 @@ <h2 id="prefect.server.orchestration.global_policy.SetNextScheduledStartTime" cl
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Records the scheduled time on a run.</p>
+        <p>Records the scheduled time on a run.</p>
 <p>When a run enters a scheduled state, <code>run.next_scheduled_start_time</code> is set to
 the state's scheduled time. When leaving a scheduled state,
 <code>run.next_scheduled_start_time</code> is unset.</p>
@@ -14552,7 +14553,7 @@ <h2 id="prefect.server.orchestration.global_policy.UpdateSubflowParentTask" clas
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Whenever a subflow changes state, it must update its parent task run's state.</p>
+        <p>Whenever a subflow changes state, it must update its parent task run's state.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
@@ -14660,7 +14661,7 @@ <h2 id="prefect.server.orchestration.global_policy.UpdateSubflowStateDetails" cl
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Update a child subflow state's references to a corresponding tracking task run id
+        <p>Update a child subflow state's references to a corresponding tracking task run id
 in the parent flow run</p>
 
               <details class="quote">
@@ -14733,7 +14734,7 @@ <h2 id="prefect.server.orchestration.global_policy.UpdateStateDetails" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.BaseUniversalTransform" href="../rules/#prefect.server.orchestration.rules.BaseUniversalTransform">BaseUniversalTransform</a></code></p>
 
 
-      <p>Update a state's references to a corresponding flow- or task- run.</p>
+        <p>Update a state's references to a corresponding flow- or task- run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/orchestration/global_policy.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/orchestration/policies/index.html b/versions/unreleased/api-ref/server/orchestration/policies/index.html
index a51dfd9950..0ace72ddd3 100644
--- a/versions/unreleased/api-ref/server/orchestration/policies/index.html
+++ b/versions/unreleased/api-ref/server/orchestration/policies/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13271,7 +13272,7 @@ <h1 id="prefect.server.orchestration.policies" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Policies are collections of orchestration rules and transforms.</p>
+        <p>Policies are collections of orchestration rules and transforms.</p>
 <p>Prefect implements (most) orchestration with logic that governs a Prefect flow or task
 changing state. Policies organize of orchestration logic both to provide an ordering
 mechanism as well as provide observability into the orchestration process.</p>
@@ -13308,7 +13309,7 @@ <h2 id="prefect.server.orchestration.policies.BaseOrchestrationPolicy" class="do
               Bases: <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>An abstract base class used to organize orchestration rules in priority order.</p>
+        <p>An abstract base class used to organize orchestration rules in priority order.</p>
 <p>Different collections of orchestration rules might be used to govern various kinds
 of transitions. For example, flow-run states and task-run states might require
 different orchestration logic.</p>
@@ -13403,7 +13404,7 @@ <h3 id="prefect.server.orchestration.policies.BaseOrchestrationPolicy.priority"
 
     <div class="doc doc-contents ">
 
-      <p>A list of orchestration rules in priority order.</p>
+        <p>A list of orchestration rules in priority order.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/orchestration/policies.py</code></summary>
@@ -13443,7 +13444,7 @@ <h3 id="prefect.server.orchestration.policies.BaseOrchestrationPolicy.compile_tr
 
     <div class="doc doc-contents ">
 
-      <p>Returns rules in policy that are valid for the specified state transition.</p>
+        <p>Returns rules in policy that are valid for the specified state transition.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/orchestration/policies.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/orchestration/rules/index.html b/versions/unreleased/api-ref/server/orchestration/rules/index.html
index 06ba614222..d4eb798370 100644
--- a/versions/unreleased/api-ref/server/orchestration/rules/index.html
+++ b/versions/unreleased/api-ref/server/orchestration/rules/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13957,7 +13958,7 @@ <h1 id="prefect.server.orchestration.rules" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect's flow and task-run orchestration machinery.</p>
+        <p>Prefect's flow and task-run orchestration machinery.</p>
 <p>This module contains all the core concepts necessary to implement Prefect's state
 orchestration engine. These states correspond to intuitive descriptions of all the
 points that a Prefect flow or task can observe executing user code and intervene, if
@@ -13999,7 +14000,7 @@ <h2 id="prefect.server.orchestration.rules.OrchestrationContext" class="doc doc-
               Bases: <code><span title="prefect.server.utilities.schemas.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A container for a state transition, governed by orchestration rules.</p>
+        <p>A container for a state transition, governed by orchestration rules.</p>
 
 
 <details class="note" open>
@@ -14007,7 +14008,7 @@ <h2 id="prefect.server.orchestration.rules.OrchestrationContext" class="doc doc-
   <p>An <code>OrchestrationContext</code> should not be instantiated directly, instead
 use the flow- or task- specific subclasses, <code>FlowOrchestrationContext</code> and
 <code>TaskOrchestrationContext</code>.</p>
-</details>      <p>When a flow- or task- run attempts to change state, Prefect REST API has an opportunity
+</details>        <p>When a flow- or task- run attempts to change state, Prefect REST API has an opportunity
 to decide whether this transition can proceed. All the relevant information
 associated with the state transition is stored in an <code>OrchestrationContext</code>,
 which is subsequently governed by nested orchestration rules implemented using
@@ -14452,7 +14453,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.initial_state_ty
 
     <div class="doc doc-contents ">
 
-      <p>The state type of <code>self.initial_state</code> if it exists.</p>
+        <p>The state type of <code>self.initial_state</code> if it exists.</p>
     </div>
 
 </div>
@@ -14473,7 +14474,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.proposed_state_t
 
     <div class="doc doc-contents ">
 
-      <p>The state type of <code>self.proposed_state</code> if it exists.</p>
+        <p>The state type of <code>self.proposed_state</code> if it exists.</p>
     </div>
 
 </div>
@@ -14494,7 +14495,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.validated_state_
 
     <div class="doc doc-contents ">
 
-      <p>The state type of <code>self.validated_state</code> if it exists.</p>
+        <p>The state type of <code>self.validated_state</code> if it exists.</p>
     </div>
 
 </div>
@@ -14512,7 +14513,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.safe_copy" class
 
     <div class="doc doc-contents ">
 
-      <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
+        <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
 <p>Orchestration rules govern state transitions using information stored in
 an <code>OrchestrationContext</code>. However, mutating objects stored on the context
 directly can have unintended side-effects. To guard against this,
@@ -14613,7 +14614,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.entry_context" c
 
     <div class="doc doc-contents ">
 
-      <p>A convenience method that generates input parameters for orchestration rules.</p>
+        <p>A convenience method that generates input parameters for orchestration rules.</p>
 <p>An <code>OrchestrationContext</code> defines a state transition that is managed by
 orchestration rules which can fire hooks before a transition has been committed
 to the database. These hooks have a consistent interface which can be generated
@@ -14661,7 +14662,7 @@ <h3 id="prefect.server.orchestration.rules.OrchestrationContext.exit_context" cl
 
     <div class="doc doc-contents ">
 
-      <p>A convenience method that generates input parameters for orchestration rules.</p>
+        <p>A convenience method that generates input parameters for orchestration rules.</p>
 <p>An <code>OrchestrationContext</code> defines a state transition that is managed by
 orchestration rules which can fire hooks after a transition has been committed
 to the database. These hooks have a consistent interface which can be generated
@@ -14722,7 +14723,7 @@ <h2 id="prefect.server.orchestration.rules.FlowOrchestrationContext" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.OrchestrationContext" href="#prefect.server.orchestration.rules.OrchestrationContext">OrchestrationContext</a></code></p>
 
 
-      <p>A container for a flow run state transition, governed by orchestration rules.</p>
+        <p>A container for a flow run state transition, governed by orchestration rules.</p>
 <p>When a flow- run attempts to change state, Prefect REST API has an opportunity
 to decide whether this transition can proceed. All the relevant information
 associated with the state transition is stored in an <code>OrchestrationContext</code>,
@@ -15249,7 +15250,7 @@ <h3 id="prefect.server.orchestration.rules.FlowOrchestrationContext.run_settings
 
     <div class="doc doc-contents ">
 
-      <p>Run-level settings used to orchestrate the state transition.</p>
+        <p>Run-level settings used to orchestrate the state transition.</p>
     </div>
 
 </div>
@@ -15271,7 +15272,7 @@ <h3 id="prefect.server.orchestration.rules.FlowOrchestrationContext.validate_pro
 
     <div class="doc doc-contents ">
 
-      <p>Validates a proposed state by committing it to the database.</p>
+        <p>Validates a proposed state by committing it to the database.</p>
 <p>After the <code>FlowOrchestrationContext</code> is governed by orchestration rules, the
 proposed state can be validated: the proposed state is added to the current
 SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed
@@ -15393,7 +15394,7 @@ <h3 id="prefect.server.orchestration.rules.FlowOrchestrationContext.safe_copy" c
 
     <div class="doc doc-contents ">
 
-      <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
+        <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
 <p>Orchestration rules govern state transitions using information stored in
 an <code>OrchestrationContext</code>. However, mutating objects stored on the context
 directly can have unintended side-effects. To guard against this,
@@ -15494,7 +15495,7 @@ <h2 id="prefect.server.orchestration.rules.TaskOrchestrationContext" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.orchestration.rules.OrchestrationContext" href="#prefect.server.orchestration.rules.OrchestrationContext">OrchestrationContext</a></code></p>
 
 
-      <p>A container for a task run state transition, governed by orchestration rules.</p>
+        <p>A container for a task run state transition, governed by orchestration rules.</p>
 <p>When a task- run attempts to change state, Prefect REST API has an opportunity
 to decide whether this transition can proceed. All the relevant information
 associated with the state transition is stored in an <code>OrchestrationContext</code>,
@@ -16037,7 +16038,7 @@ <h3 id="prefect.server.orchestration.rules.TaskOrchestrationContext.run_settings
 
     <div class="doc doc-contents ">
 
-      <p>Run-level settings used to orchestrate the state transition.</p>
+        <p>Run-level settings used to orchestrate the state transition.</p>
     </div>
 
 </div>
@@ -16059,7 +16060,7 @@ <h3 id="prefect.server.orchestration.rules.TaskOrchestrationContext.validate_pro
 
     <div class="doc doc-contents ">
 
-      <p>Validates a proposed state by committing it to the database.</p>
+        <p>Validates a proposed state by committing it to the database.</p>
 <p>After the <code>TaskOrchestrationContext</code> is governed by orchestration rules, the
 proposed state can be validated: the proposed state is added to the current
 SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed
@@ -16181,7 +16182,7 @@ <h3 id="prefect.server.orchestration.rules.TaskOrchestrationContext.safe_copy" c
 
     <div class="doc doc-contents ">
 
-      <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
+        <p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p>
 <p>Orchestration rules govern state transitions using information stored in
 an <code>OrchestrationContext</code>. However, mutating objects stored on the context
 directly can have unintended side-effects. To guard against this,
@@ -16282,7 +16283,7 @@ <h2 id="prefect.server.orchestration.rules.BaseOrchestrationRule" class="doc doc
               Bases: <code><span title="contextlib.AbstractAsyncContextManager">AbstractAsyncContextManager</span></code></p>
 
 
-      <p>An abstract base class used to implement a discrete piece of orchestration logic.</p>
+        <p>An abstract base class used to implement a discrete piece of orchestration logic.</p>
 <p>An <code>OrchestrationRule</code> is a stateful context manager that directly governs a state
 transition. Complex orchestration is achieved by nesting multiple rules.
 Each rule runs against an <code>OrchestrationContext</code> that contains the transition
@@ -17311,7 +17312,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.before_transiti
 
     <div class="doc doc-contents ">
 
-      <p>Implements a hook that can fire before a state is committed to the database.</p>
+        <p>Implements a hook that can fire before a state is committed to the database.</p>
 <p>This hook may produce side-effects or mutate the proposed state of a
 transition using one of four methods: <code>self.reject_transition</code>,
 <code>self.delay_transition</code>, <code>self.abort_transition</code>, and <code>self.rename_state</code>.</p>
@@ -17489,7 +17490,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.after_transitio
 
     <div class="doc doc-contents ">
 
-      <p>Implements a hook that can fire after a state is committed to the database.</p>
+        <p>Implements a hook that can fire after a state is committed to the database.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17633,7 +17634,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.cleanup" class=
 
     <div class="doc doc-contents ">
 
-      <p>Implements a hook that can fire after a state is committed to the database.</p>
+        <p>Implements a hook that can fire after a state is committed to the database.</p>
 <p>The intended use of this method is to revert side-effects produced by
 <code>self.before_transition</code> when the transition is found to be invalid on exit.
 This allows multiple rules to be gracefully run in sequence, without logic that
@@ -17791,7 +17792,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.invalid" class=
 
     <div class="doc doc-contents ">
 
-      <p>Determines if a rule is invalid.</p>
+        <p>Determines if a rule is invalid.</p>
 <p>Invalid rules do nothing and no hooks fire upon entering or exiting a governed
 context. Rules are invalid if the transition states types are not contained in
 <code>self.FROM_STATES</code> and <code>self.TO_STATES</code>, or if the context is proposing
@@ -17886,7 +17887,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.fizzled" class=
 
     <div class="doc doc-contents ">
 
-      <p>Determines if a rule is fizzled and side-effects need to be reverted.</p>
+        <p>Determines if a rule is fizzled and side-effects need to be reverted.</p>
 <p>Rules are fizzled if the transitions were valid on entry (thus firing
 <code>self.before_transition</code>) but are invalid upon exiting the governed context,
 most likely caused by another rule mutating the transition.</p>
@@ -17966,7 +17967,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.invalid_transit
 
     <div class="doc doc-contents ">
 
-      <p>Determines if the transition proposed by the <code>OrchestrationContext</code> is invalid.</p>
+        <p>Determines if the transition proposed by the <code>OrchestrationContext</code> is invalid.</p>
 <p>If the <code>OrchestrationContext</code> is attempting to manage a transition with this
 rule that differs from the transition the rule was instantiated with, the
 transition is considered to be invalid. Depending on the context, a rule with an
@@ -18053,7 +18054,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.reject_transiti
 
     <div class="doc doc-contents ">
 
-      <p>Rejects a proposed transition before the transition is validated.</p>
+        <p>Rejects a proposed transition before the transition is validated.</p>
 <p>This method will reject a proposed transition, mutating the proposed state to
 the provided <code>state</code>. A reason for rejecting the transition is also passed on
 to the <code>OrchestrationContext</code>. Rules that reject the transition will not fizzle,
@@ -18195,7 +18196,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.delay_transitio
 
     <div class="doc doc-contents ">
 
-      <p>Delays a proposed transition before the transition is validated.</p>
+        <p>Delays a proposed transition before the transition is validated.</p>
 <p>This method will delay a proposed transition, setting the proposed state to
 <code>None</code>, signaling to the <code>OrchestrationContext</code> that no state should be
 written to the database. The number of seconds a transition should be delayed is
@@ -18330,7 +18331,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.abort_transitio
 
     <div class="doc doc-contents ">
 
-      <p>Aborts a proposed transition before the transition is validated.</p>
+        <p>Aborts a proposed transition before the transition is validated.</p>
 <p>This method will abort a proposed transition, expecting no further action to
 occur for this run. The proposed state is set to <code>None</code>, signaling to the
 <code>OrchestrationContext</code> that no state should be written to the database. A
@@ -18434,7 +18435,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.rename_state" c
 
     <div class="doc doc-contents ">
 
-      <p>Sets the "name" attribute on a proposed state.</p>
+        <p>Sets the "name" attribute on a proposed state.</p>
 <p>The name of a state is an annotation intended to provide rich, human-readable
 context for how a run is progressing. This method only updates the name and not
 the canonical state TYPE, and will not fizzle or invalidate any other rules
@@ -18484,7 +18485,7 @@ <h3 id="prefect.server.orchestration.rules.BaseOrchestrationRule.update_context_
 
     <div class="doc doc-contents ">
 
-      <p>Updates the "parameters" dictionary attribute with the specified key-value pair.</p>
+        <p>Updates the "parameters" dictionary attribute with the specified key-value pair.</p>
 <p>This mechanism streamlines the process of passing messages and information
 between orchestration rules if necessary and is simpler and more ephemeral than
 message-passing via the database or some other side-effect. This mechanism can
@@ -18549,13 +18550,13 @@ <h2 id="prefect.server.orchestration.rules.BaseUniversalTransform" class="doc do
               Bases: <code><span title="contextlib.AbstractAsyncContextManager">AbstractAsyncContextManager</span></code></p>
 
 
-      <p>An abstract base class used to implement privileged bookkeeping logic.</p>
+        <p>An abstract base class used to implement privileged bookkeeping logic.</p>
 
 
 <details class="warning" open>
   <summary>Warning</summary>
   <p>In almost all cases, use the <code>BaseOrchestrationRule</code> base class instead.</p>
-</details>      <p>Beyond the orchestration rules implemented with the <code>BaseOrchestrationRule</code> ABC,
+</details>        <p>Beyond the orchestration rules implemented with the <code>BaseOrchestrationRule</code> ABC,
 Universal transforms are not stateful, and fire their before- and after- transition
 hooks on every state transition unless the proposed state is <code>None</code>, indicating that
 no state should be written to the database. Because there are no guardrails in place
@@ -18923,7 +18924,7 @@ <h3 id="prefect.server.orchestration.rules.BaseUniversalTransform.before_transit
 
     <div class="doc doc-contents ">
 
-      <p>Implements a hook that fires before a state is committed to the database.</p>
+        <p>Implements a hook that fires before a state is committed to the database.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19018,7 +19019,7 @@ <h3 id="prefect.server.orchestration.rules.BaseUniversalTransform.after_transiti
 
     <div class="doc doc-contents ">
 
-      <p>Implements a hook that can fire after a state is committed to the database.</p>
+        <p>Implements a hook that can fire after a state is committed to the database.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19109,7 +19110,7 @@ <h3 id="prefect.server.orchestration.rules.BaseUniversalTransform.nullified_tran
 
     <div class="doc doc-contents ">
 
-      <p>Determines if the transition has been nullified.</p>
+        <p>Determines if the transition has been nullified.</p>
 <p>Transitions are nullified if the proposed state is <code>None</code>, indicating that
 nothing should be written to the database.</p>
 
@@ -19178,7 +19179,7 @@ <h3 id="prefect.server.orchestration.rules.BaseUniversalTransform.exception_in_t
 
     <div class="doc doc-contents ">
 
-      <p>Determines if the transition has encountered an exception.</p>
+        <p>Determines if the transition has encountered an exception.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/api-ref/server/schemas/actions/index.html b/versions/unreleased/api-ref/server/schemas/actions/index.html
index 115c9d46a6..e711a82d8e 100644
--- a/versions/unreleased/api-ref/server/schemas/actions/index.html
+++ b/versions/unreleased/api-ref/server/schemas/actions/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -15017,7 +15018,7 @@ <h1 id="prefect.server.schemas.actions" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Reduced schemas for accepting API actions.</p>
+        <p>Reduced schemas for accepting API actions.</p>
 
 
 
@@ -15046,7 +15047,7 @@ <h2 id="prefect.server.schemas.actions.ArtifactCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create an artifact.</p>
+        <p>Data used by the Prefect REST API to create an artifact.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15195,7 +15196,7 @@ <h3 id="prefect.server.schemas.actions.ArtifactCreate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15268,7 +15269,7 @@ <h2 id="prefect.server.schemas.actions.ArtifactUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update an artifact.</p>
+        <p>Data used by the Prefect REST API to update an artifact.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15317,7 +15318,7 @@ <h3 id="prefect.server.schemas.actions.ArtifactUpdate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15390,7 +15391,7 @@ <h2 id="prefect.server.schemas.actions.BlockDocumentCreate" class="doc doc-headi
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block document.</p>
+        <p>Data used by the Prefect REST API to create a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15481,7 +15482,7 @@ <h3 id="prefect.server.schemas.actions.BlockDocumentCreate.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15554,7 +15555,7 @@ <h2 id="prefect.server.schemas.actions.BlockDocumentReferenceCreate" class="doc
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used to create block document reference.</p>
+        <p>Data used to create block document reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15621,7 +15622,7 @@ <h3 id="prefect.server.schemas.actions.BlockDocumentReferenceCreate.json" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15694,7 +15695,7 @@ <h2 id="prefect.server.schemas.actions.BlockDocumentUpdate" class="doc doc-headi
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a block document.</p>
+        <p>Data used by the Prefect REST API to update a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15743,7 +15744,7 @@ <h3 id="prefect.server.schemas.actions.BlockDocumentUpdate.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15816,7 +15817,7 @@ <h2 id="prefect.server.schemas.actions.BlockSchemaCreate" class="doc doc-heading
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block schema.</p>
+        <p>Data used by the Prefect REST API to create a block schema.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -15877,7 +15878,7 @@ <h3 id="prefect.server.schemas.actions.BlockSchemaCreate.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -15950,7 +15951,7 @@ <h2 id="prefect.server.schemas.actions.BlockTypeCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a block type.</p>
+        <p>Data used by the Prefect REST API to create a block type.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16035,7 +16036,7 @@ <h3 id="prefect.server.schemas.actions.BlockTypeCreate.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16108,7 +16109,7 @@ <h2 id="prefect.server.schemas.actions.BlockTypeUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a block type.</p>
+        <p>Data used by the Prefect REST API to update a block type.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16159,7 +16160,7 @@ <h3 id="prefect.server.schemas.actions.BlockTypeUpdate.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16232,7 +16233,7 @@ <h2 id="prefect.server.schemas.actions.ConcurrencyLimitCreate" class="doc doc-he
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a concurrency limit.</p>
+        <p>Data used by the Prefect REST API to create a concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16275,7 +16276,7 @@ <h3 id="prefect.server.schemas.actions.ConcurrencyLimitCreate.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16348,7 +16349,7 @@ <h2 id="prefect.server.schemas.actions.ConcurrencyLimitV2Create" class="doc doc-
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a v2 concurrency limit.</p>
+        <p>Data used by the Prefect REST API to create a v2 concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16421,7 +16422,7 @@ <h3 id="prefect.server.schemas.actions.ConcurrencyLimitV2Create.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16494,7 +16495,7 @@ <h2 id="prefect.server.schemas.actions.ConcurrencyLimitV2Update" class="doc doc-
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a v2 concurrency limit.</p>
+        <p>Data used by the Prefect REST API to update a v2 concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16549,7 +16550,7 @@ <h3 id="prefect.server.schemas.actions.ConcurrencyLimitV2Update.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16622,7 +16623,7 @@ <h2 id="prefect.server.schemas.actions.DeploymentCreate" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a deployment.</p>
+        <p>Data used by the Prefect REST API to create a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -16855,7 +16856,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentCreate.check_valid_configuratio
 
     <div class="doc doc-contents ">
 
-      <p>Check that the combination of base_job_template defaults and job_variables
+        <p>Check that the combination of base_job_template defaults and job_variables
 conforms to the specified schema.</p>
 <p>NOTE: This method does not hydrate block references in default values within the
 base job template to validate them. Failing to do this can cause user-facing
@@ -16926,7 +16927,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentCreate.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -16990,7 +16991,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentCreate.schema" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Don't use the mixin docstring as the description if this class is missing a
+        <p>Don't use the mixin docstring as the description if this class is missing a
 docstring.</p>
 
             <details class="quote">
@@ -17052,7 +17053,7 @@ <h2 id="prefect.server.schemas.actions.DeploymentFlowRunCreate" class="doc doc-h
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run from a deployment.</p>
+        <p>Data used by the Prefect REST API to create a flow run from a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -17171,7 +17172,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentFlowRunCreate.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -17244,7 +17245,7 @@ <h2 id="prefect.server.schemas.actions.DeploymentUpdate" class="doc doc-heading"
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a deployment.</p>
+        <p>Data used by the Prefect REST API to update a deployment.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -17437,7 +17438,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentUpdate.check_valid_configuratio
 
     <div class="doc doc-contents ">
 
-      <p>Check that the combination of base_job_template defaults and job_variables
+        <p>Check that the combination of base_job_template defaults and job_variables
 conforms to the schema specified in the base_job_template.</p>
 <p>NOTE: This method does not hydrate block references in default values within the
 base job template to validate them. Failing to do this can cause user-facing
@@ -17514,7 +17515,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentUpdate.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -17578,7 +17579,7 @@ <h3 id="prefect.server.schemas.actions.DeploymentUpdate.schema" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Don't use the mixin docstring as the description if this class is missing a
+        <p>Don't use the mixin docstring as the description if this class is missing a
 docstring.</p>
 
             <details class="quote">
@@ -17640,7 +17641,7 @@ <h2 id="prefect.server.schemas.actions.FlowCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow.</p>
+        <p>Data used by the Prefect REST API to create a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -17699,7 +17700,7 @@ <h3 id="prefect.server.schemas.actions.FlowCreate.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -17772,7 +17773,7 @@ <h2 id="prefect.server.schemas.actions.FlowRunCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run.</p>
+        <p>Data used by the Prefect REST API to create a flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -17925,7 +17926,7 @@ <h3 id="prefect.server.schemas.actions.FlowRunCreate.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -17998,7 +17999,7 @@ <h2 id="prefect.server.schemas.actions.FlowRunNotificationPolicyCreate" class="d
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a flow run notification policy.</p>
+        <p>Data used by the Prefect REST API to create a flow run notification policy.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18091,7 +18092,7 @@ <h3 id="prefect.server.schemas.actions.FlowRunNotificationPolicyCreate.json" cla
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18164,7 +18165,7 @@ <h2 id="prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate" class="d
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow run notification policy.</p>
+        <p>Data used by the Prefect REST API to update a flow run notification policy.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18217,7 +18218,7 @@ <h3 id="prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate.json" cla
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18290,7 +18291,7 @@ <h2 id="prefect.server.schemas.actions.FlowRunUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow run.</p>
+        <p>Data used by the Prefect REST API to update a flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18351,7 +18352,7 @@ <h3 id="prefect.server.schemas.actions.FlowRunUpdate.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18424,7 +18425,7 @@ <h2 id="prefect.server.schemas.actions.FlowUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a flow.</p>
+        <p>Data used by the Prefect REST API to update a flow.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18477,7 +18478,7 @@ <h3 id="prefect.server.schemas.actions.FlowUpdate.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18550,7 +18551,7 @@ <h2 id="prefect.server.schemas.actions.LogCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a log.</p>
+        <p>Data used by the Prefect REST API to create a log.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18597,7 +18598,7 @@ <h3 id="prefect.server.schemas.actions.LogCreate.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18670,7 +18671,7 @@ <h2 id="prefect.server.schemas.actions.SavedSearchCreate" class="doc doc-heading
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a saved search.</p>
+        <p>Data used by the Prefect REST API to create a saved search.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18713,7 +18714,7 @@ <h3 id="prefect.server.schemas.actions.SavedSearchCreate.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18786,7 +18787,7 @@ <h2 id="prefect.server.schemas.actions.StateCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a new state.</p>
+        <p>Data used by the Prefect REST API to create a new state.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -18883,7 +18884,7 @@ <h3 id="prefect.server.schemas.actions.StateCreate.json" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18956,7 +18957,7 @@ <h2 id="prefect.server.schemas.actions.TaskRunCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a task run</p>
+        <p>Data used by the Prefect REST API to create a task run</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19129,7 +19130,7 @@ <h3 id="prefect.server.schemas.actions.TaskRunCreate.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19202,7 +19203,7 @@ <h2 id="prefect.server.schemas.actions.TaskRunUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a task run</p>
+        <p>Data used by the Prefect REST API to update a task run</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19251,7 +19252,7 @@ <h3 id="prefect.server.schemas.actions.TaskRunUpdate.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19324,7 +19325,7 @@ <h2 id="prefect.server.schemas.actions.VariableCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a Variable.</p>
+        <p>Data used by the Prefect REST API to create a Variable.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19399,7 +19400,7 @@ <h3 id="prefect.server.schemas.actions.VariableCreate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19472,7 +19473,7 @@ <h2 id="prefect.server.schemas.actions.VariableUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a Variable.</p>
+        <p>Data used by the Prefect REST API to update a Variable.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19547,7 +19548,7 @@ <h3 id="prefect.server.schemas.actions.VariableUpdate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19620,7 +19621,7 @@ <h2 id="prefect.server.schemas.actions.WorkPoolCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a work pool.</p>
+        <p>Data used by the Prefect REST API to create a work pool.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19697,7 +19698,7 @@ <h3 id="prefect.server.schemas.actions.WorkPoolCreate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19770,7 +19771,7 @@ <h2 id="prefect.server.schemas.actions.WorkPoolUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a work pool.</p>
+        <p>Data used by the Prefect REST API to update a work pool.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19829,7 +19830,7 @@ <h3 id="prefect.server.schemas.actions.WorkPoolUpdate.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19902,7 +19903,7 @@ <h2 id="prefect.server.schemas.actions.WorkQueueCreate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to create a work queue.</p>
+        <p>Data used by the Prefect REST API to create a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -19993,7 +19994,7 @@ <h3 id="prefect.server.schemas.actions.WorkQueueCreate.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20066,7 +20067,7 @@ <h2 id="prefect.server.schemas.actions.WorkQueueUpdate" class="doc doc-heading">
               Bases: <code><span title="prefect.server.schemas.actions.ActionBaseModel">ActionBaseModel</span></code></p>
 
 
-      <p>Data used by the Prefect REST API to update a work queue.</p>
+        <p>Data used by the Prefect REST API to update a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/actions.py</code></summary>
@@ -20133,7 +20134,7 @@ <h3 id="prefect.server.schemas.actions.WorkQueueUpdate.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
diff --git a/versions/unreleased/api-ref/server/schemas/core/index.html b/versions/unreleased/api-ref/server/schemas/core/index.html
index 19e5ec7cdd..3d38f9f4c3 100644
--- a/versions/unreleased/api-ref/server/schemas/core/index.html
+++ b/versions/unreleased/api-ref/server/schemas/core/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13733,7 +13734,7 @@ <h1 id="prefect.server.schemas.core" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Full schemas of Prefect REST API objects.</p>
+        <p>Full schemas of Prefect REST API objects.</p>
 
 
 
@@ -13762,7 +13763,7 @@ <h2 id="prefect.server.schemas.core.Agent" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of an agent</p>
+        <p>An ORM representation of an agent</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -13836,7 +13837,7 @@ <h2 id="prefect.server.schemas.core.BlockDocument" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block document.</p>
+        <p>An ORM representation of a block document.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14060,7 +14061,7 @@ <h2 id="prefect.server.schemas.core.BlockDocumentReference" class="doc doc-headi
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block document reference.</p>
+        <p>An ORM representation of a block document reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14146,7 +14147,7 @@ <h2 id="prefect.server.schemas.core.BlockSchema" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block schema.</p>
+        <p>An ORM representation of a block schema.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14226,7 +14227,7 @@ <h2 id="prefect.server.schemas.core.BlockSchemaReference" class="doc doc-heading
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block schema reference.</p>
+        <p>An ORM representation of a block schema reference.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14304,7 +14305,7 @@ <h2 id="prefect.server.schemas.core.BlockType" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a block type</p>
+        <p>An ORM representation of a block type</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14398,7 +14399,7 @@ <h2 id="prefect.server.schemas.core.ConcurrencyLimit" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a concurrency limit.</p>
+        <p>An ORM representation of a concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14462,7 +14463,7 @@ <h2 id="prefect.server.schemas.core.ConcurrencyLimitV2" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a v2 concurrency limit.</p>
+        <p>An ORM representation of a v2 concurrency limit.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14546,7 +14547,7 @@ <h2 id="prefect.server.schemas.core.Configuration" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of account info.</p>
+        <p>An ORM representation of account info.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14598,7 +14599,7 @@ <h2 id="prefect.server.schemas.core.Deployment" class="doc doc-heading">
               Bases: <code><span title="prefect._internal.compatibility.deprecated.DeprecatedInfraOverridesField">DeprecatedInfraOverridesField</span></code>, <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of deployment data.</p>
+        <p>An ORM representation of deployment data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14862,7 +14863,7 @@ <h2 id="prefect.server.schemas.core.Flow" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of flow data.</p>
+        <p>An ORM representation of flow data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -14934,7 +14935,7 @@ <h2 id="prefect.server.schemas.core.FlowRun" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of flow run data.</p>
+        <p>An ORM representation of flow run data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15280,7 +15281,7 @@ <h2 id="prefect.server.schemas.core.FlowRunNotificationPolicy" class="doc doc-he
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a flow run notification.</p>
+        <p>An ORM representation of a flow run notification.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15386,7 +15387,7 @@ <h2 id="prefect.server.schemas.core.FlowRunPolicy" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Defines of how a flow run should retry.</p>
+        <p>Defines of how a flow run should retry.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15498,7 +15499,7 @@ <h2 id="prefect.server.schemas.core.Log" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of log data.</p>
+        <p>An ORM representation of log data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15566,7 +15567,7 @@ <h2 id="prefect.server.schemas.core.QueueFilter" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Filter criteria definition for a work queue.</p>
+        <p>Filter criteria definition for a work queue.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15630,7 +15631,7 @@ <h2 id="prefect.server.schemas.core.SavedSearch" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of saved search data. Represents a set of filter criteria.</p>
+        <p>An ORM representation of saved search data. Represents a set of filter criteria.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15686,7 +15687,7 @@ <h2 id="prefect.server.schemas.core.SavedSearchFilter" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A filter for a saved search model. Intended for use by the Prefect UI.</p>
+        <p>A filter for a saved search model. Intended for use by the Prefect UI.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -15758,7 +15759,7 @@ <h2 id="prefect.server.schemas.core.TaskRun" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of task run data.</p>
+        <p>An ORM representation of task run data.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -16026,7 +16027,7 @@ <h2 id="prefect.server.schemas.core.WorkPool" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a work pool</p>
+        <p>An ORM representation of a work pool</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -16156,7 +16157,7 @@ <h2 id="prefect.server.schemas.core.WorkQueue" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a work queue</p>
+        <p>An ORM representation of a work queue</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
@@ -16385,7 +16386,7 @@ <h3 id="prefect.server.schemas.core.WorkQueueHealthPolicy.evaluate_health_status
 
     <div class="doc doc-contents ">
 
-      <p>Given empirical information about the state of the work queue, evaluate its health status.</p>
+        <p>Given empirical information about the state of the work queue, evaluate its health status.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16541,7 +16542,7 @@ <h2 id="prefect.server.schemas.core.Worker" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>An ORM representation of a worker</p>
+        <p>An ORM representation of a worker</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/core.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/schemas/filters/index.html b/versions/unreleased/api-ref/server/schemas/filters/index.html
index 13ce216528..77a1387ed5 100644
--- a/versions/unreleased/api-ref/server/schemas/filters/index.html
+++ b/versions/unreleased/api-ref/server/schemas/filters/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -18401,7 +18402,7 @@ <h1 id="prefect.server.schemas.filters" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schemas that define Prefect REST API filtering operations.</p>
+        <p>Schemas that define Prefect REST API filtering operations.</p>
 <p>Each filter schema includes logic for transforming itself into a SQL <code>where</code> clause.</p>
 
 
@@ -18431,7 +18432,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilter" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p>
+        <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -18528,7 +18529,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilter.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18601,7 +18602,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId" class=
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -18654,7 +18655,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId.json" c
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18727,7 +18728,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilterKey" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.key</code>.</p>
+        <p>Filter by <code>ArtifactCollection.key</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -18832,7 +18833,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilterKey.json" class="
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -18905,7 +18906,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilterLatestId" class="
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.latest_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.latest_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -18958,7 +18959,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilterLatestId.json" cl
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19031,7 +19032,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId" class=
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p>
+        <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19084,7 +19085,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId.json" c
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19157,7 +19158,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactCollectionFilterType" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>ArtifactCollection.type</code>.</p>
+        <p>Filter by <code>ArtifactCollection.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19220,7 +19221,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactCollectionFilterType.json" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19293,7 +19294,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter artifacts. Only artifacts matching all criteria will be returned</p>
+        <p>Filter artifacts. Only artifacts matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19390,7 +19391,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilter.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19463,7 +19464,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilterFlowRunId" class="doc doc-h
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Artifact.flow_run_id</code>.</p>
+        <p>Filter by <code>Artifact.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19516,7 +19517,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilterFlowRunId.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19589,7 +19590,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilterId" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Artifact.id</code>.</p>
+        <p>Filter by <code>Artifact.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19642,7 +19643,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilterId.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19715,7 +19716,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilterKey" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Artifact.key</code>.</p>
+        <p>Filter by <code>Artifact.key</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19818,7 +19819,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilterKey.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -19891,7 +19892,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilterTaskRunId" class="doc doc-h
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Artifact.task_run_id</code>.</p>
+        <p>Filter by <code>Artifact.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -19944,7 +19945,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilterTaskRunId.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20017,7 +20018,7 @@ <h2 id="prefect.server.schemas.filters.ArtifactFilterType" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Artifact.type</code>.</p>
+        <p>Filter by <code>Artifact.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20080,7 +20081,7 @@ <h3 id="prefect.server.schemas.filters.ArtifactFilterType.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20153,7 +20154,7 @@ <h2 id="prefect.server.schemas.filters.BlockDocumentFilter" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p>
+        <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20246,7 +20247,7 @@ <h3 id="prefect.server.schemas.filters.BlockDocumentFilter.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20319,7 +20320,7 @@ <h2 id="prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockDocument.block_type_id</code>.</p>
+        <p>Filter by <code>BlockDocument.block_type_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20372,7 +20373,7 @@ <h3 id="prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId.json" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20445,7 +20446,7 @@ <h2 id="prefect.server.schemas.filters.BlockDocumentFilterId" class="doc doc-hea
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockDocument.id</code>.</p>
+        <p>Filter by <code>BlockDocument.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20498,7 +20499,7 @@ <h3 id="prefect.server.schemas.filters.BlockDocumentFilterId.json" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20571,7 +20572,7 @@ <h2 id="prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockDocument.is_anonymous</code>.</p>
+        <p>Filter by <code>BlockDocument.is_anonymous</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20630,7 +20631,7 @@ <h3 id="prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous.json" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20703,7 +20704,7 @@ <h2 id="prefect.server.schemas.filters.BlockDocumentFilterName" class="doc doc-h
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockDocument.name</code>.</p>
+        <p>Filter by <code>BlockDocument.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20776,7 +20777,7 @@ <h3 id="prefect.server.schemas.filters.BlockDocumentFilterName.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -20849,7 +20850,7 @@ <h2 id="prefect.server.schemas.filters.BlockSchemaFilter" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter BlockSchemas</p>
+        <p>Filter BlockSchemas</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -20936,7 +20937,7 @@ <h3 id="prefect.server.schemas.filters.BlockSchemaFilter.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21009,7 +21010,7 @@ <h2 id="prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockSchema.block_type_id</code>.</p>
+        <p>Filter by <code>BlockSchema.block_type_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21062,7 +21063,7 @@ <h3 id="prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId.json" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21135,7 +21136,7 @@ <h2 id="prefect.server.schemas.filters.BlockSchemaFilterCapabilities" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockSchema.capabilities</code></p>
+        <p>Filter by <code>BlockSchema.capabilities</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21202,7 +21203,7 @@ <h3 id="prefect.server.schemas.filters.BlockSchemaFilterCapabilities.json" class
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21275,7 +21276,7 @@ <h2 id="prefect.server.schemas.filters.BlockSchemaFilterId" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by BlockSchema.id</p>
+        <p>Filter by BlockSchema.id</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21328,7 +21329,7 @@ <h3 id="prefect.server.schemas.filters.BlockSchemaFilterId.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21401,7 +21402,7 @@ <h2 id="prefect.server.schemas.filters.BlockSchemaFilterVersion" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockSchema.capabilities</code></p>
+        <p>Filter by <code>BlockSchema.capabilities</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21462,7 +21463,7 @@ <h3 id="prefect.server.schemas.filters.BlockSchemaFilterVersion.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21535,7 +21536,7 @@ <h2 id="prefect.server.schemas.filters.BlockTypeFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter BlockTypes</p>
+        <p>Filter BlockTypes</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21604,7 +21605,7 @@ <h3 id="prefect.server.schemas.filters.BlockTypeFilter.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21677,7 +21678,7 @@ <h2 id="prefect.server.schemas.filters.BlockTypeFilterName" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockType.name</code></p>
+        <p>Filter by <code>BlockType.name</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21742,7 +21743,7 @@ <h3 id="prefect.server.schemas.filters.BlockTypeFilterName.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21815,7 +21816,7 @@ <h2 id="prefect.server.schemas.filters.BlockTypeFilterSlug" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>BlockType.slug</code></p>
+        <p>Filter by <code>BlockType.slug</code></p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -21870,7 +21871,7 @@ <h3 id="prefect.server.schemas.filters.BlockTypeFilterSlug.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -21943,7 +21944,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilter" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
+        <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22050,7 +22051,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilter.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22123,7 +22124,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterId" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Deployment.id</code>.</p>
+        <p>Filter by <code>Deployment.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22176,7 +22177,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterId.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22249,7 +22250,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterIsScheduleActive" class="
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Legacy filter to filter by <code>Deployment.is_schedule_active</code> which
+        <p>Legacy filter to filter by <code>Deployment.is_schedule_active</code> which
 is always the opposite of <code>Deployment.paused</code>.</p>
 
               <details class="quote">
@@ -22307,7 +22308,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterIsScheduleActive.json" cl
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22380,7 +22381,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterName" class="doc doc-head
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Deployment.name</code>.</p>
+        <p>Filter by <code>Deployment.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22461,7 +22462,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterName.json" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22534,7 +22535,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterPaused" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Deployment.paused</code>.</p>
+        <p>Filter by <code>Deployment.paused</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22589,7 +22590,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterPaused.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22662,7 +22663,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterTags" class="doc doc-head
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Deployment.tags</code>.</p>
+        <p>Filter by <code>Deployment.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22743,7 +22744,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterTags.json" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22816,7 +22817,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentFilterWorkQueueName" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Deployment.work_queue_name</code>.</p>
+        <p>Filter by <code>Deployment.work_queue_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -22873,7 +22874,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentFilterWorkQueueName.json" class
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -22946,7 +22947,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentScheduleFilter" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
+        <p>Filter for deployments. Only deployments matching all criteria will be returned.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23003,7 +23004,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentScheduleFilter.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23076,7 +23077,7 @@ <h2 id="prefect.server.schemas.filters.DeploymentScheduleFilterActive" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>DeploymentSchedule.active</code>.</p>
+        <p>Filter by <code>DeploymentSchedule.active</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23131,7 +23132,7 @@ <h3 id="prefect.server.schemas.filters.DeploymentScheduleFilterActive.json" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23204,7 +23205,7 @@ <h2 id="prefect.server.schemas.filters.FilterSet" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A collection of filters for common objects</p>
+        <p>A collection of filters for common objects</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23265,7 +23266,7 @@ <h3 id="prefect.server.schemas.filters.FilterSet.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23338,7 +23339,7 @@ <h2 id="prefect.server.schemas.filters.FlowFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter for flows. Only flows matching all criteria will be returned.</p>
+        <p>Filter for flows. Only flows matching all criteria will be returned.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23425,7 +23426,7 @@ <h3 id="prefect.server.schemas.filters.FlowFilter.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23498,7 +23499,7 @@ <h2 id="prefect.server.schemas.filters.FlowFilterDeployment" class="doc doc-head
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by flows by deployment</p>
+        <p>Filter by flows by deployment</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23579,7 +23580,7 @@ <h3 id="prefect.server.schemas.filters.FlowFilterDeployment.json" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23652,7 +23653,7 @@ <h2 id="prefect.server.schemas.filters.FlowFilterId" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Flow.id</code>.</p>
+        <p>Filter by <code>Flow.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23705,7 +23706,7 @@ <h3 id="prefect.server.schemas.filters.FlowFilterId.json" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23778,7 +23779,7 @@ <h2 id="prefect.server.schemas.filters.FlowFilterName" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Flow.name</code>.</p>
+        <p>Filter by <code>Flow.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -23859,7 +23860,7 @@ <h3 id="prefect.server.schemas.filters.FlowFilterName.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -23932,7 +23933,7 @@ <h2 id="prefect.server.schemas.filters.FlowFilterTags" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Flow.tags</code>.</p>
+        <p>Filter by <code>Flow.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24009,7 +24010,7 @@ <h3 id="prefect.server.schemas.filters.FlowFilterTags.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24082,7 +24083,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter flow runs. Only flow runs matching all criteria will be returned</p>
+        <p>Filter flow runs. Only flow runs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24297,7 +24298,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilter.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24370,7 +24371,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterDeploymentId" class="doc doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.deployment_id</code>.</p>
+        <p>Filter by <code>FlowRun.deployment_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24443,7 +24444,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterDeploymentId.json" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24516,7 +24517,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterExpectedStartTime" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.expected_start_time</code>.</p>
+        <p>Filter by <code>FlowRun.expected_start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24583,7 +24584,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterExpectedStartTime.json" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24656,7 +24657,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterFlowVersion" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.flow_version</code>.</p>
+        <p>Filter by <code>FlowRun.flow_version</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24709,7 +24710,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterFlowVersion.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24782,7 +24783,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterId" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.id</code>.</p>
+        <p>Filter by <code>FlowRun.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24845,7 +24846,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterId.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -24918,7 +24919,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterIdempotencyKey" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by FlowRun.idempotency_key.</p>
+        <p>Filter by FlowRun.idempotency_key.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -24981,7 +24982,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterIdempotencyKey.json" class="
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25054,7 +25055,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterName" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.name</code>.</p>
+        <p>Filter by <code>FlowRun.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25135,7 +25136,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterName.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25208,7 +25209,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime" clas
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p>
+        <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25287,7 +25288,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime.json"
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25360,7 +25361,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterParentFlowRunId" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter for subflows of a given flow run</p>
+        <p>Filter for subflows of a given flow run</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25435,7 +25436,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterParentFlowRunId.json" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25508,7 +25509,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterParentTaskRunId" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p>
+        <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25581,7 +25582,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterParentTaskRunId.json" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25654,7 +25655,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterStartTime" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.start_time</code>.</p>
+        <p>Filter by <code>FlowRun.start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25739,7 +25740,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterStartTime.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25812,7 +25813,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterState" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.state_type</code> and <code>FlowRun.state_name</code>.</p>
+        <p>Filter by <code>FlowRun.state_type</code> and <code>FlowRun.state_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -25875,7 +25876,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterState.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -25948,7 +25949,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterStateName" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.state_name</code>.</p>
+        <p>Filter by <code>FlowRun.state_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26001,7 +26002,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterStateName.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26074,7 +26075,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterStateType" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.state_type</code>.</p>
+        <p>Filter by <code>FlowRun.state_type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26127,7 +26128,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterStateType.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26200,7 +26201,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterTags" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.tags</code>.</p>
+        <p>Filter by <code>FlowRun.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26281,7 +26282,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterTags.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26354,7 +26355,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunFilterWorkQueueName" class="doc do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRun.work_queue_name</code>.</p>
+        <p>Filter by <code>FlowRun.work_queue_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26431,7 +26432,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunFilterWorkQueueName.json" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26504,7 +26505,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunNotificationPolicyFilter" class="d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter FlowRunNotificationPolicies.</p>
+        <p>Filter FlowRunNotificationPolicies.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26561,7 +26562,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunNotificationPolicyFilter.json" cla
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26634,7 +26635,7 @@ <h2 id="prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p>
+        <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26693,7 +26694,7 @@ <h3 id="prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive.j
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26766,7 +26767,7 @@ <h2 id="prefect.server.schemas.filters.LogFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter logs. Only logs matching all criteria will be returned</p>
+        <p>Filter logs. Only logs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26853,7 +26854,7 @@ <h3 id="prefect.server.schemas.filters.LogFilter.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -26926,7 +26927,7 @@ <h2 id="prefect.server.schemas.filters.LogFilterFlowRunId" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Log.flow_run_id</code>.</p>
+        <p>Filter by <code>Log.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -26979,7 +26980,7 @@ <h3 id="prefect.server.schemas.filters.LogFilterFlowRunId.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27052,7 +27053,7 @@ <h2 id="prefect.server.schemas.filters.LogFilterLevel" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Log.level</code>.</p>
+        <p>Filter by <code>Log.level</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27125,7 +27126,7 @@ <h3 id="prefect.server.schemas.filters.LogFilterLevel.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27198,7 +27199,7 @@ <h2 id="prefect.server.schemas.filters.LogFilterName" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Log.name</code>.</p>
+        <p>Filter by <code>Log.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27255,7 +27256,7 @@ <h3 id="prefect.server.schemas.filters.LogFilterName.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27328,7 +27329,7 @@ <h2 id="prefect.server.schemas.filters.LogFilterTaskRunId" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Log.task_run_id</code>.</p>
+        <p>Filter by <code>Log.task_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27381,7 +27382,7 @@ <h3 id="prefect.server.schemas.filters.LogFilterTaskRunId.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27454,7 +27455,7 @@ <h2 id="prefect.server.schemas.filters.LogFilterTimestamp" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Log.timestamp</code>.</p>
+        <p>Filter by <code>Log.timestamp</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27521,7 +27522,7 @@ <h3 id="prefect.server.schemas.filters.LogFilterTimestamp.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27594,7 +27595,7 @@ <h2 id="prefect.server.schemas.filters.Operator" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Operators for combining filter criteria.</p>
+        <p>Operators for combining filter criteria.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27637,7 +27638,7 @@ <h3 id="prefect.server.schemas.filters.Operator.auto" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
+        <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/collections.py</code></summary>
@@ -27682,7 +27683,7 @@ <h2 id="prefect.server.schemas.filters.PrefectFilterBaseModel" class="doc doc-he
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Base model for Prefect filters</p>
+        <p>Base model for Prefect filters</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27743,7 +27744,7 @@ <h3 id="prefect.server.schemas.filters.PrefectFilterBaseModel.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27816,7 +27817,7 @@ <h2 id="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Base model for Prefect filters that combines criteria with a user-provided operator</p>
+        <p>Base model for Prefect filters that combines criteria with a user-provided operator</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -27871,7 +27872,7 @@ <h3 id="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel.json" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -27944,7 +27945,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter task runs. Only task runs matching all criteria will be returned</p>
+        <p>Filter task runs. Only task runs matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28061,7 +28062,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilter.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28134,7 +28135,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterFlowRunId" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.flow_run_id</code>.</p>
+        <p>Filter by <code>TaskRun.flow_run_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28201,7 +28202,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterFlowRunId.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28274,7 +28275,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterId" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.id</code>.</p>
+        <p>Filter by <code>TaskRun.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28327,7 +28328,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterId.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28400,7 +28401,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterName" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.name</code>.</p>
+        <p>Filter by <code>TaskRun.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28481,7 +28482,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterName.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28554,7 +28555,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterStartTime" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.start_time</code>.</p>
+        <p>Filter by <code>TaskRun.start_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28639,7 +28640,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterStartTime.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28712,7 +28713,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterState" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.type</code> and <code>TaskRun.name</code>.</p>
+        <p>Filter by <code>TaskRun.type</code> and <code>TaskRun.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28767,7 +28768,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterState.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28840,7 +28841,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterStateName" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.state_name</code>.</p>
+        <p>Filter by <code>TaskRun.state_name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -28893,7 +28894,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterStateName.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -28966,7 +28967,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterStateType" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.state_type</code>.</p>
+        <p>Filter by <code>TaskRun.state_type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29019,7 +29020,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterStateType.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29092,7 +29093,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterSubFlowRuns" class="doc doc-
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.subflow_run</code>.</p>
+        <p>Filter by <code>TaskRun.subflow_run</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29157,7 +29158,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterSubFlowRuns.json" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29230,7 +29231,7 @@ <h2 id="prefect.server.schemas.filters.TaskRunFilterTags" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>TaskRun.tags</code>.</p>
+        <p>Filter by <code>TaskRun.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29311,7 +29312,7 @@ <h3 id="prefect.server.schemas.filters.TaskRunFilterTags.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29384,7 +29385,7 @@ <h2 id="prefect.server.schemas.filters.VariableFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter variables. Only variables matching all criteria will be returned</p>
+        <p>Filter variables. Only variables matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29469,7 +29470,7 @@ <h3 id="prefect.server.schemas.filters.VariableFilter.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29542,7 +29543,7 @@ <h2 id="prefect.server.schemas.filters.VariableFilterId" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Variable.id</code>.</p>
+        <p>Filter by <code>Variable.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29595,7 +29596,7 @@ <h3 id="prefect.server.schemas.filters.VariableFilterId.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29668,7 +29669,7 @@ <h2 id="prefect.server.schemas.filters.VariableFilterName" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Variable.name</code>.</p>
+        <p>Filter by <code>Variable.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29741,7 +29742,7 @@ <h3 id="prefect.server.schemas.filters.VariableFilterName.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29814,7 +29815,7 @@ <h2 id="prefect.server.schemas.filters.VariableFilterTags" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Variable.tags</code>.</p>
+        <p>Filter by <code>Variable.tags</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -29895,7 +29896,7 @@ <h3 id="prefect.server.schemas.filters.VariableFilterTags.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -29968,7 +29969,7 @@ <h2 id="prefect.server.schemas.filters.VariableFilterValue" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Variable.value</code>.</p>
+        <p>Filter by <code>Variable.value</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30041,7 +30042,7 @@ <h3 id="prefect.server.schemas.filters.VariableFilterValue.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30114,7 +30115,7 @@ <h2 id="prefect.server.schemas.filters.WorkPoolFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter work pools. Only work pools matching all criteria will be returned</p>
+        <p>Filter work pools. Only work pools matching all criteria will be returned</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30191,7 +30192,7 @@ <h3 id="prefect.server.schemas.filters.WorkPoolFilter.json" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30264,7 +30265,7 @@ <h2 id="prefect.server.schemas.filters.WorkPoolFilterId" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>WorkPool.id</code>.</p>
+        <p>Filter by <code>WorkPool.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30317,7 +30318,7 @@ <h3 id="prefect.server.schemas.filters.WorkPoolFilterId.json" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30390,7 +30391,7 @@ <h2 id="prefect.server.schemas.filters.WorkPoolFilterName" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>WorkPool.name</code>.</p>
+        <p>Filter by <code>WorkPool.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30443,7 +30444,7 @@ <h3 id="prefect.server.schemas.filters.WorkPoolFilterName.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30516,7 +30517,7 @@ <h2 id="prefect.server.schemas.filters.WorkPoolFilterType" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>WorkPool.type</code>.</p>
+        <p>Filter by <code>WorkPool.type</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30569,7 +30570,7 @@ <h3 id="prefect.server.schemas.filters.WorkPoolFilterType.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30642,7 +30643,7 @@ <h2 id="prefect.server.schemas.filters.WorkQueueFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter work queues. Only work queues matching all criteria will be
+        <p>Filter work queues. Only work queues matching all criteria will be
 returned</p>
 
               <details class="quote">
@@ -30714,7 +30715,7 @@ <h3 id="prefect.server.schemas.filters.WorkQueueFilter.json" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30787,7 +30788,7 @@ <h2 id="prefect.server.schemas.filters.WorkQueueFilterId" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>WorkQueue.id</code>.</p>
+        <p>Filter by <code>WorkQueue.id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -30842,7 +30843,7 @@ <h3 id="prefect.server.schemas.filters.WorkQueueFilterId.json" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -30915,7 +30916,7 @@ <h2 id="prefect.server.schemas.filters.WorkQueueFilterName" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>WorkQueue.name</code>.</p>
+        <p>Filter by <code>WorkQueue.name</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -31004,7 +31005,7 @@ <h3 id="prefect.server.schemas.filters.WorkQueueFilterName.json" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -31077,7 +31078,7 @@ <h2 id="prefect.server.schemas.filters.WorkerFilter" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectOperatorFilterBaseModel" href="#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel">PrefectOperatorFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
+        <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -31152,7 +31153,7 @@ <h3 id="prefect.server.schemas.filters.WorkerFilter.json" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -31225,7 +31226,7 @@ <h2 id="prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
+        <p>Filter by <code>Worker.last_heartbeat_time</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -31300,7 +31301,7 @@ <h3 id="prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime.json" class
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -31373,7 +31374,7 @@ <h2 id="prefect.server.schemas.filters.WorkerFilterStatus" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Worker.status</code>.</p>
+        <p>Filter by <code>Worker.status</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -31436,7 +31437,7 @@ <h3 id="prefect.server.schemas.filters.WorkerFilterStatus.json" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -31509,7 +31510,7 @@ <h2 id="prefect.server.schemas.filters.WorkerFilterWorkPoolId" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.filters.PrefectFilterBaseModel" href="#prefect.server.schemas.filters.PrefectFilterBaseModel">PrefectFilterBaseModel</a></code></p>
 
 
-      <p>Filter by <code>Worker.worker_config_id</code>.</p>
+        <p>Filter by <code>Worker.worker_config_id</code>.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/filters.py</code></summary>
@@ -31562,7 +31563,7 @@ <h3 id="prefect.server.schemas.filters.WorkerFilterWorkPoolId.json" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
diff --git a/versions/unreleased/api-ref/server/schemas/responses/index.html b/versions/unreleased/api-ref/server/schemas/responses/index.html
index b79743f920..8cd2c39faa 100644
--- a/versions/unreleased/api-ref/server/schemas/responses/index.html
+++ b/versions/unreleased/api-ref/server/schemas/responses/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13435,7 +13436,7 @@ <h1 id="prefect.server.schemas.responses" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schemas for special responses from the Prefect REST API.</p>
+        <p>Schemas for special responses from the Prefect REST API.</p>
 
 
 
@@ -13824,7 +13825,7 @@ <h2 id="prefect.server.schemas.responses.GlobalConcurrencyLimitResponse" class="
               Bases: <code><span title="prefect.server.utilities.schemas.bases.ORMBaseModel">ORMBaseModel</span></code></p>
 
 
-      <p>A response object for global concurrency limits.</p>
+        <p>A response object for global concurrency limits.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -13900,7 +13901,7 @@ <h2 id="prefect.server.schemas.responses.HistoryResponse" class="doc doc-heading
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Represents a history of aggregation states over an interval</p>
+        <p>Represents a history of aggregation states over an interval</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -13966,7 +13967,7 @@ <h2 id="prefect.server.schemas.responses.HistoryResponseState" class="doc doc-he
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Represents a single state's history over an interval.</p>
+        <p>Represents a single state's history over an interval.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14052,7 +14053,7 @@ <h2 id="prefect.server.schemas.responses.OrchestrationResult" class="doc doc-hea
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A container for the output of state orchestration.</p>
+        <p>A container for the output of state orchestration.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14110,7 +14111,7 @@ <h2 id="prefect.server.schemas.responses.SetStateStatus" class="doc doc-heading"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumerates return statuses for setting run states.</p>
+        <p>Enumerates return statuses for setting run states.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14166,7 +14167,7 @@ <h2 id="prefect.server.schemas.responses.StateAbortDetails" class="doc doc-headi
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with an ABORT state transition.</p>
+        <p>Details associated with an ABORT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14234,7 +14235,7 @@ <h2 id="prefect.server.schemas.responses.StateAcceptDetails" class="doc doc-head
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with an ACCEPT state transition.</p>
+        <p>Details associated with an ACCEPT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14296,7 +14297,7 @@ <h2 id="prefect.server.schemas.responses.StateRejectDetails" class="doc doc-head
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with a REJECT state transition.</p>
+        <p>Details associated with a REJECT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14364,7 +14365,7 @@ <h2 id="prefect.server.schemas.responses.StateWaitDetails" class="doc doc-headin
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Details associated with a WAIT state transition.</p>
+        <p>Details associated with a WAIT state transition.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
@@ -14446,7 +14447,7 @@ <h2 id="prefect.server.schemas.responses.WorkQueueWithStatus" class="doc doc-hea
               Bases: <code><span title="prefect.server.schemas.responses.WorkQueueResponse">WorkQueueResponse</span></code>, <code><span title="prefect.server.schemas.core.WorkQueueStatusDetail">WorkQueueStatusDetail</span></code></p>
 
 
-      <p>Combines a work queue and its status details into a single object</p>
+        <p>Combines a work queue and its status details into a single object</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/responses.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/schemas/schedules/index.html b/versions/unreleased/api-ref/server/schemas/schedules/index.html
index 83bb70c6a9..43cf2a0d30 100644
--- a/versions/unreleased/api-ref/server/schemas/schedules/index.html
+++ b/versions/unreleased/api-ref/server/schemas/schedules/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13383,7 +13384,7 @@ <h1 id="prefect.server.schemas.schedules" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schedule schemas</p>
+        <p>Schedule schemas</p>
 
 
 
@@ -13412,7 +13413,7 @@ <h2 id="prefect.server.schemas.schedules.CronSchedule" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>Cron schedule</p>
+        <p>Cron schedule</p>
 <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust
 itself appropriately. Cron's rules for DST are based on schedule times, not
 intervals. This means that an hourly cron schedule will fire on every new
@@ -13821,7 +13822,7 @@ <h3 id="prefect.server.schemas.schedules.CronSchedule.get_dates" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
+        <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
 following the start date.</p>
 
 
@@ -13983,7 +13984,7 @@ <h2 id="prefect.server.schemas.schedules.IntervalSchedule" class="doc doc-headin
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no
+        <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no
 <code>anchor_date</code> is supplied, the current UTC time is used.  If a
 timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be
 in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,
@@ -14375,7 +14376,7 @@ <h3 id="prefect.server.schemas.schedules.IntervalSchedule.get_dates" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
+        <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
 following the start date.</p>
 
 
@@ -14537,7 +14538,7 @@ <h2 id="prefect.server.schemas.schedules.RRuleSchedule" class="doc doc-heading">
               Bases: <code><span title="prefect.server.utilities.schemas.bases.PrefectBaseModel">PrefectBaseModel</span></code></p>
 
 
-      <p>RRule schedule, based on the iCalendar standard
+        <p>RRule schedule, based on the iCalendar standard
 (<a href="https://datatracker.ietf.org/doc/html/rfc5545">RFC 5545</a>) as
 implemented in <code>dateutils.rrule</code>.</p>
 <p>RRules are appropriate for any kind of calendar-date manipulation, including
@@ -15054,7 +15055,7 @@ <h3 id="prefect.server.schemas.schedules.RRuleSchedule.get_dates" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
+        <p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked
 following the start date.</p>
 
 
@@ -15203,7 +15204,7 @@ <h3 id="prefect.server.schemas.schedules.RRuleSchedule.to_rrule" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates
+        <p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates
 here</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/server/schemas/sorting/index.html b/versions/unreleased/api-ref/server/schemas/sorting/index.html
index 16a1ece29b..0026582d82 100644
--- a/versions/unreleased/api-ref/server/schemas/sorting/index.html
+++ b/versions/unreleased/api-ref/server/schemas/sorting/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13663,7 +13664,7 @@ <h1 id="prefect.server.schemas.sorting" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Schemas for sorting Prefect REST API objects.</p>
+        <p>Schemas for sorting Prefect REST API objects.</p>
 
 
 
@@ -13692,7 +13693,7 @@ <h2 id="prefect.server.schemas.sorting.ArtifactCollectionSort" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines artifact collection sorting options.</p>
+        <p>Defines artifact collection sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -13759,7 +13760,7 @@ <h3 id="prefect.server.schemas.sorting.ArtifactCollectionSort.as_sql_sort" class
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort artifact collections</p>
+        <p>Return an expression used to sort artifact collections</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -13812,7 +13813,7 @@ <h2 id="prefect.server.schemas.sorting.ArtifactSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines artifact sorting options.</p>
+        <p>Defines artifact sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -13879,7 +13880,7 @@ <h3 id="prefect.server.schemas.sorting.ArtifactSort.as_sql_sort" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort artifacts</p>
+        <p>Return an expression used to sort artifacts</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -13932,7 +13933,7 @@ <h2 id="prefect.server.schemas.sorting.BlockDocumentSort" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines block document sorting options.</p>
+        <p>Defines block document sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -13991,7 +13992,7 @@ <h3 id="prefect.server.schemas.sorting.BlockDocumentSort.as_sql_sort" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort block documents</p>
+        <p>Return an expression used to sort block documents</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14040,7 +14041,7 @@ <h2 id="prefect.server.schemas.sorting.DeploymentSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines deployment sorting options.</p>
+        <p>Defines deployment sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14103,7 +14104,7 @@ <h3 id="prefect.server.schemas.sorting.DeploymentSort.as_sql_sort" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort deployments</p>
+        <p>Return an expression used to sort deployments</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14154,7 +14155,7 @@ <h2 id="prefect.server.schemas.sorting.FlowRunSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines flow run sorting options.</p>
+        <p>Defines flow run sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14262,7 +14263,7 @@ <h2 id="prefect.server.schemas.sorting.FlowSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines flow sorting options.</p>
+        <p>Defines flow sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14325,7 +14326,7 @@ <h3 id="prefect.server.schemas.sorting.FlowSort.as_sql_sort" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort flows</p>
+        <p>Return an expression used to sort flows</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14376,7 +14377,7 @@ <h2 id="prefect.server.schemas.sorting.LogSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines log sorting options.</p>
+        <p>Defines log sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14431,7 +14432,7 @@ <h3 id="prefect.server.schemas.sorting.LogSort.as_sql_sort" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort task runs</p>
+        <p>Return an expression used to sort task runs</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14478,7 +14479,7 @@ <h2 id="prefect.server.schemas.sorting.TaskRunSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines task run sorting options.</p>
+        <p>Defines task run sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14553,7 +14554,7 @@ <h3 id="prefect.server.schemas.sorting.TaskRunSort.as_sql_sort" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort task runs</p>
+        <p>Return an expression used to sort task runs</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14610,7 +14611,7 @@ <h2 id="prefect.server.schemas.sorting.VariableSort" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Defines variables sorting options.</p>
+        <p>Defines variables sorting options.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
@@ -14673,7 +14674,7 @@ <h3 id="prefect.server.schemas.sorting.VariableSort.as_sql_sort" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Return an expression used to sort variables</p>
+        <p>Return an expression used to sort variables</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/server/schemas/sorting.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/schemas/states/index.html b/versions/unreleased/api-ref/server/schemas/states/index.html
index f35e472ef5..fcbf8eae30 100644
--- a/versions/unreleased/api-ref/server/schemas/states/index.html
+++ b/versions/unreleased/api-ref/server/schemas/states/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13669,7 +13670,7 @@ <h1 id="prefect.server.schemas.states" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>State schemas.</p>
+        <p>State schemas.</p>
 
 
 
@@ -13698,7 +13699,7 @@ <h2 id="prefect.server.schemas.states.State" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.schemas.states.StateBaseModel" href="#prefect.server.schemas.states.StateBaseModel">StateBaseModel</a></code></p>
 
 
-      <p>Represents the state of a run.</p>
+        <p>Represents the state of a run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/states.py</code></summary>
@@ -14097,7 +14098,7 @@ <h3 id="prefect.server.schemas.states.State.from_orm_without_result" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>During orchestration, ORM states can be instantiated prior to inserting results
+        <p>During orchestration, ORM states can be instantiated prior to inserting results
 into the artifact table and the <code>data</code> field will not be eagerly loaded. In
 these cases, sqlalchemy will attempt to lazily load the the relationship, which
 will fail when called within a synchronous pydantic method.</p>
@@ -14179,7 +14180,7 @@ <h3 id="prefect.server.schemas.states.State.json" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -14315,7 +14316,7 @@ <h3 id="prefect.server.schemas.states.StateBaseModel.json" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns a representation of the model as JSON.</p>
+        <p>Returns a representation of the model as JSON.</p>
 <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are
 fully revealed. Otherwise they are obfuscated.</p>
 
@@ -14388,7 +14389,7 @@ <h2 id="prefect.server.schemas.states.StateType" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.utilities.collections.AutoEnum" href="../../../prefect/utilities/collections/#prefect.utilities.collections.AutoEnum">AutoEnum</a></code></p>
 
 
-      <p>Enumeration of state types.</p>
+        <p>Enumeration of state types.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/schemas/states.py</code></summary>
@@ -14445,7 +14446,7 @@ <h3 id="prefect.server.schemas.states.StateType.auto" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
+        <p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p>
 
             <details class="quote">
               <summary>Source code in <code>prefect/utilities/collections.py</code></summary>
@@ -14486,7 +14487,7 @@ <h2 id="prefect.server.schemas.states.AwaitingRetry" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>AwaitingRetry</code> states.</p>
+        <p>Convenience function for creating <code>AwaitingRetry</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14551,7 +14552,7 @@ <h2 id="prefect.server.schemas.states.Cancelled" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Cancelled</code> states.</p>
+        <p>Convenience function for creating <code>Cancelled</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14608,7 +14609,7 @@ <h2 id="prefect.server.schemas.states.Cancelling" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Cancelling</code> states.</p>
+        <p>Convenience function for creating <code>Cancelling</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14665,7 +14666,7 @@ <h2 id="prefect.server.schemas.states.Completed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Completed</code> states.</p>
+        <p>Convenience function for creating <code>Completed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14722,7 +14723,7 @@ <h2 id="prefect.server.schemas.states.Crashed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Crashed</code> states.</p>
+        <p>Convenience function for creating <code>Crashed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14779,7 +14780,7 @@ <h2 id="prefect.server.schemas.states.Failed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Failed</code> states.</p>
+        <p>Convenience function for creating <code>Failed</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14836,7 +14837,7 @@ <h2 id="prefect.server.schemas.states.Late" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Late</code> states.</p>
+        <p>Convenience function for creating <code>Late</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14897,7 +14898,7 @@ <h2 id="prefect.server.schemas.states.Paused" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Paused</code> states.</p>
+        <p>Convenience function for creating <code>Paused</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15008,7 +15009,7 @@ <h2 id="prefect.server.schemas.states.Pending" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Pending</code> states.</p>
+        <p>Convenience function for creating <code>Pending</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15065,7 +15066,7 @@ <h2 id="prefect.server.schemas.states.Retrying" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Retrying</code> states.</p>
+        <p>Convenience function for creating <code>Retrying</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15122,7 +15123,7 @@ <h2 id="prefect.server.schemas.states.Running" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Running</code> states.</p>
+        <p>Convenience function for creating <code>Running</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15179,7 +15180,7 @@ <h2 id="prefect.server.schemas.states.Scheduled" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Scheduled</code> states.</p>
+        <p>Convenience function for creating <code>Scheduled</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15258,7 +15259,7 @@ <h2 id="prefect.server.schemas.states.Suspended" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convenience function for creating <code>Suspended</code> states.</p>
+        <p>Convenience function for creating <code>Suspended</code> states.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/api-ref/server/services/late_runs/index.html b/versions/unreleased/api-ref/server/services/late_runs/index.html
index 3e4eb4ba70..7425c29616 100644
--- a/versions/unreleased/api-ref/server/services/late_runs/index.html
+++ b/versions/unreleased/api-ref/server/services/late_runs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13249,7 +13250,7 @@ <h1 id="prefect.server.services.late_runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>The MarkLateRuns service. Responsible for putting flow runs in a Late state if they are not started on time.
+        <p>The MarkLateRuns service. Responsible for putting flow runs in a Late state if they are not started on time.
 The threshold for a late run can be configured by changing <code>PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS</code>.</p>
 
 
@@ -13279,7 +13280,7 @@ <h2 id="prefect.server.services.late_runs.MarkLateRuns" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.services.loop_service.LoopService" href="../loop_service/#prefect.server.services.loop_service.LoopService">LoopService</a></code></p>
 
 
-      <p>A simple loop service responsible for identifying flow runs that are "late".</p>
+        <p>A simple loop service responsible for identifying flow runs that are "late".</p>
 <p>A flow run is defined as "late" if has not scheduled within a certain amount
 of time after its scheduled start time. The exact amount is configurable in
 Prefect REST API Settings.</p>
@@ -13513,7 +13514,7 @@ <h3 id="prefect.server.services.late_runs.MarkLateRuns.run_once" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Mark flow runs as late by:</p>
+        <p>Mark flow runs as late by:</p>
 <ul>
 <li>Querying for flow runs in a scheduled state that are Scheduled to start in the past</li>
 <li>For any runs past the "late" threshold, setting the flow run state to a new <code>Late</code> state</li>
diff --git a/versions/unreleased/api-ref/server/services/loop_service/index.html b/versions/unreleased/api-ref/server/services/loop_service/index.html
index 881ede2d61..57d0cbcd96 100644
--- a/versions/unreleased/api-ref/server/services/loop_service/index.html
+++ b/versions/unreleased/api-ref/server/services/loop_service/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13315,7 +13316,7 @@ <h1 id="prefect.server.services.loop_service" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>The base class for all Prefect REST API loop services.</p>
+        <p>The base class for all Prefect REST API loop services.</p>
 
 
 
@@ -13342,7 +13343,7 @@ <h2 id="prefect.server.services.loop_service.LoopService" class="doc doc-heading
     <div class="doc doc-contents ">
 
 
-      <p>Loop services are relatively lightweight maintenance routines that need to run periodically.</p>
+        <p>Loop services are relatively lightweight maintenance routines that need to run periodically.</p>
 <p>This class makes it straightforward to design and integrate them. Users only need to
 define the <code>run_once</code> coroutine to describe the behavior of the service on each loop.</p>
 
@@ -13679,7 +13680,7 @@ <h3 id="prefect.server.services.loop_service.LoopService.run_once" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Represents one loop of the service.</p>
+        <p>Represents one loop of the service.</p>
 <p>Users should override this method.</p>
 <p>To actually run the service once, call <code>LoopService().start(loops=1)</code>
 instead of <code>LoopService().run_once()</code>, because this method will not invoke setup
@@ -13729,7 +13730,7 @@ <h3 id="prefect.server.services.loop_service.LoopService.start" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Run the service <code>loops</code> time. Pass loops=None to run forever.</p>
+        <p>Run the service <code>loops</code> time. Pass loops=None to run forever.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13896,7 +13897,7 @@ <h3 id="prefect.server.services.loop_service.LoopService.stop" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Gracefully stops a running LoopService and optionally blocks until the
+        <p>Gracefully stops a running LoopService and optionally blocks until the
 service stops.</p>
 
 
@@ -14017,7 +14018,7 @@ <h2 id="prefect.server.services.loop_service.run_multiple_services" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Only one signal handler can be active at a time, so this function takes a list
+        <p>Only one signal handler can be active at a time, so this function takes a list
 of loop services and runs all of them with a global signal handler.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/api-ref/server/services/scheduler/index.html b/versions/unreleased/api-ref/server/services/scheduler/index.html
index bef6710672..59ed4a83e0 100644
--- a/versions/unreleased/api-ref/server/services/scheduler/index.html
+++ b/versions/unreleased/api-ref/server/services/scheduler/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13293,7 +13294,7 @@ <h1 id="prefect.server.services.scheduler" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>The Scheduler service.</p>
+        <p>The Scheduler service.</p>
 
 
 
@@ -13322,7 +13323,7 @@ <h2 id="prefect.server.services.scheduler.RecentDeploymentsScheduler" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.services.scheduler.Scheduler" href="#prefect.server.services.scheduler.Scheduler">Scheduler</a></code></p>
 
 
-      <p>A scheduler that only schedules deployments that were updated very recently.
+        <p>A scheduler that only schedules deployments that were updated very recently.
 This scheduler can run on a tight loop and ensure that runs from
 newly-created or updated deployments are rapidly scheduled without having to
 wait for the "main" scheduler to complete its loop.</p>
@@ -13470,7 +13471,7 @@ <h2 id="prefect.server.services.scheduler.Scheduler" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.server.services.loop_service.LoopService" href="../loop_service/#prefect.server.services.loop_service.LoopService">LoopService</a></code></p>
 
 
-      <p>A loop service that schedules flow runs from deployments.</p>
+        <p>A loop service that schedules flow runs from deployments.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/services/scheduler.py</code></summary>
@@ -14023,7 +14024,7 @@ <h3 id="prefect.server.services.scheduler.Scheduler.run_once" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Schedule flow runs by:</p>
+        <p>Schedule flow runs by:</p>
 <ul>
 <li>Querying for deployments with active schedules</li>
 <li>Generating the next set of flow runs based on each deployments schedule</li>
@@ -14163,7 +14164,7 @@ <h2 id="prefect.server.services.scheduler.TryAgain" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Internal control-flow exception used to retry the Scheduler's main loop</p>
+        <p>Internal control-flow exception used to retry the Scheduler's main loop</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/services/scheduler.py</code></summary>
diff --git a/versions/unreleased/api-ref/server/utilities/database/index.html b/versions/unreleased/api-ref/server/utilities/database/index.html
index bdb8fee7ab..5e60168a4e 100644
--- a/versions/unreleased/api-ref/server/utilities/database/index.html
+++ b/versions/unreleased/api-ref/server/utilities/database/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13501,7 +13502,7 @@ <h1 id="prefect.server.utilities.database" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for interacting with Prefect REST API database and ORM layer.</p>
+        <p>Utilities for interacting with Prefect REST API database and ORM layer.</p>
 <p>Prefect supports both SQLite and Postgres. Many of these utilities
 allow the Prefect REST API to seamlessly switch between the two.</p>
 
@@ -13532,7 +13533,7 @@ <h2 id="prefect.server.utilities.database.GenerateUUID" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform-independent UUID default generator.
+        <p>Platform-independent UUID default generator.
 Note the actual functionality for this class is specified in the
 <code>compiles</code>-decorated functions below</p>
 
@@ -13592,7 +13593,7 @@ <h2 id="prefect.server.utilities.database.JSON" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.types.TypeDecorator">TypeDecorator</span></code></p>
 
 
-      <p>JSON type that returns SQLAlchemy's dialect-specific JSON types, where
+        <p>JSON type that returns SQLAlchemy's dialect-specific JSON types, where
 possible. Uses generic JSON otherwise.</p>
 <p>The "base" type is postgresql.JSONB to expose useful methods prior
 to SQL compilation</p>
@@ -13711,7 +13712,7 @@ <h2 id="prefect.server.utilities.database.Pydantic" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.types.TypeDecorator">TypeDecorator</span></code></p>
 
 
-      <p>A pydantic type that converts inserted parameters to
+        <p>A pydantic type that converts inserted parameters to
 json and converts read values to the pydantic type.</p>
 
               <details class="quote">
@@ -13816,7 +13817,7 @@ <h2 id="prefect.server.utilities.database.Timestamp" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.types.TypeDecorator">TypeDecorator</span></code></p>
 
 
-      <p>TypeDecorator that ensures that timestamps have a timezone.</p>
+        <p>TypeDecorator that ensures that timestamps have a timezone.</p>
 <p>For SQLite, all timestamps are converted to UTC (since they are stored
 as naive timestamps without timezones) and recovered as UTC.</p>
 
@@ -13966,7 +13967,7 @@ <h2 id="prefect.server.utilities.database.UUID" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.types.TypeDecorator">TypeDecorator</span></code></p>
 
 
-      <p>Platform-independent UUID type.</p>
+        <p>Platform-independent UUID type.</p>
 <p>Uses PostgreSQL's UUID type, otherwise uses
 CHAR(36), storing as stringified hex values with
 hyphens.</p>
@@ -14081,7 +14082,7 @@ <h2 id="prefect.server.utilities.database.date_add" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform-independent way to add a date and an interval.</p>
+        <p>Platform-independent way to add a date and an interval.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/utilities/database.py</code></summary>
@@ -14151,7 +14152,7 @@ <h2 id="prefect.server.utilities.database.date_diff" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform-independent difference of dates. Computes d1 - d2.</p>
+        <p>Platform-independent difference of dates. Computes d1 - d2.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/utilities/database.py</code></summary>
@@ -14221,7 +14222,7 @@ <h2 id="prefect.server.utilities.database.interval_add" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform-independent way to add two intervals.</p>
+        <p>Platform-independent way to add two intervals.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/utilities/database.py</code></summary>
@@ -14291,7 +14292,7 @@ <h2 id="prefect.server.utilities.database.json_contains" class="doc doc-heading"
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform independent json_contains operator, tests if the
+        <p>Platform independent json_contains operator, tests if the
 <code>left</code> expression contains the <code>right</code> expression.</p>
 <p>On postgres this is equivalent to the @&gt; containment operator.
 https://www.postgresql.org/docs/current/functions-json.html</p>
@@ -14372,7 +14373,7 @@ <h2 id="prefect.server.utilities.database.json_extract" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform independent json_extract operator, extracts a value from a JSON
+        <p>Platform independent json_extract operator, extracts a value from a JSON
 field via key.</p>
 <p>On postgres this is equivalent to the -&gt;&gt; operator.
 https://www.postgresql.org/docs/current/functions-json.html</p>
@@ -14455,7 +14456,7 @@ <h2 id="prefect.server.utilities.database.json_has_all_keys" class="doc doc-head
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform independent json_has_all_keys operator.</p>
+        <p>Platform independent json_has_all_keys operator.</p>
 <p>On postgres this is equivalent to the ?&amp; existence operator.
 https://www.postgresql.org/docs/current/functions-json.html</p>
 
@@ -14539,7 +14540,7 @@ <h2 id="prefect.server.utilities.database.json_has_any_key" class="doc doc-headi
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform independent json_has_any_key operator.</p>
+        <p>Platform independent json_has_any_key operator.</p>
 <p>On postgres this is equivalent to the ?| existence operator.
 https://www.postgresql.org/docs/current/functions-json.html</p>
 
@@ -14621,7 +14622,7 @@ <h2 id="prefect.server.utilities.database.now" class="doc doc-heading">
               Bases: <code><span title="sqlalchemy.sql.functions.FunctionElement">FunctionElement</span></code></p>
 
 
-      <p>Platform-independent "now" generator.</p>
+        <p>Platform-independent "now" generator.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/utilities/database.py</code></summary>
@@ -14677,7 +14678,7 @@ <h2 id="prefect.server.utilities.database.get_dialect" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the dialect of a session, engine, or connection url.</p>
+        <p>Get the dialect of a session, engine, or connection url.</p>
 <p>Primary use case is figuring out whether the Prefect REST API is communicating with
 SQLite or Postgres.</p>
 
diff --git a/versions/unreleased/api-ref/server/utilities/schemas/index.html b/versions/unreleased/api-ref/server/utilities/schemas/index.html
index 99c08c7f2e..8d1c9e824f 100644
--- a/versions/unreleased/api-ref/server/utilities/schemas/index.html
+++ b/versions/unreleased/api-ref/server/utilities/schemas/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/api-ref/server/utilities/server/index.html b/versions/unreleased/api-ref/server/utilities/server/index.html
index 3e31b32d93..262682d7ee 100644
--- a/versions/unreleased/api-ref/server/utilities/server/index.html
+++ b/versions/unreleased/api-ref/server/utilities/server/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13315,7 +13316,7 @@ <h1 id="prefect.server.utilities.server" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for the Prefect REST API server.</p>
+        <p>Utilities for the Prefect REST API server.</p>
 
 
 
@@ -13344,7 +13345,7 @@ <h2 id="prefect.server.utilities.server.PrefectAPIRoute" class="doc doc-heading"
               Bases: <code><span title="prefect._vendor.fastapi.routing.APIRoute">APIRoute</span></code></p>
 
 
-      <p>A FastAPIRoute class which attaches an async stack to requests that exits before
+        <p>A FastAPIRoute class which attaches an async stack to requests that exits before
 a response is returned.</p>
 <p>Requests already have <code>request.scope['fastapi_astack']</code> which is an async stack for
 the full scope of the request. This stack is used for managing contexts of FastAPI
@@ -13440,7 +13441,7 @@ <h2 id="prefect.server.utilities.server.PrefectRouter" class="doc doc-heading">
               Bases: <code><span title="prefect._vendor.fastapi.APIRouter">APIRouter</span></code></p>
 
 
-      <p>A base class for Prefect REST API routers.</p>
+        <p>A base class for Prefect REST API routers.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect/server/utilities/server.py</code></summary>
@@ -13527,7 +13528,7 @@ <h3 id="prefect.server.utilities.server.PrefectRouter.add_api_route" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Add an API route.</p>
+        <p>Add an API route.</p>
 <p>For routes that return content and have not specified a <code>response_model</code>,
 use return type annotation to infer the response model.</p>
 <p>For routes that return No-Content status codes, explicitly set
@@ -13600,7 +13601,7 @@ <h2 id="prefect.server.utilities.server.method_paths_from_routes" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Generate a set of strings describing the given routes in the format: <method> <path></p>
+        <p>Generate a set of strings describing the given routes in the format: <method> <path></p>
 <p>For example, "GET /logs/"</p>
 
             <details class="quote">
@@ -13647,7 +13648,7 @@ <h2 id="prefect.server.utilities.server.response_scoped_dependency" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Ensure that this dependency closes before the response is returned to the client. By
+        <p>Ensure that this dependency closes before the response is returned to the client. By
 default, FastAPI closes dependencies after sending the response.</p>
 <p>Uses an async stack that is exited before the response is returned. This is
 particularly useful for database sessions which must be committed before the client
diff --git a/versions/unreleased/cloud/connecting/index.html b/versions/unreleased/cloud/connecting/index.html
index d4bddee796..536afbbeac 100644
--- a/versions/unreleased/cloud/connecting/index.html
+++ b/versions/unreleased/cloud/connecting/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/events/index.html b/versions/unreleased/cloud/events/index.html
index 297a1dcebf..58900465a4 100644
--- a/versions/unreleased/cloud/events/index.html
+++ b/versions/unreleased/cloud/events/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/incidents/index.html b/versions/unreleased/cloud/incidents/index.html
index 6aef7c7b95..adc2408db3 100644
--- a/versions/unreleased/cloud/incidents/index.html
+++ b/versions/unreleased/cloud/incidents/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/index.html b/versions/unreleased/cloud/index.html
index 044c24ef9e..3d8dd59409 100644
--- a/versions/unreleased/cloud/index.html
+++ b/versions/unreleased/cloud/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/rate-limits/index.html b/versions/unreleased/cloud/rate-limits/index.html
index b5d1434981..209a6d98aa 100644
--- a/versions/unreleased/cloud/rate-limits/index.html
+++ b/versions/unreleased/cloud/rate-limits/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/api-keys/index.html b/versions/unreleased/cloud/users/api-keys/index.html
index d2da1a91b7..0b8f9ded9f 100644
--- a/versions/unreleased/cloud/users/api-keys/index.html
+++ b/versions/unreleased/cloud/users/api-keys/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/audit-log/index.html b/versions/unreleased/cloud/users/audit-log/index.html
index 9a5b52cd13..545943d324 100644
--- a/versions/unreleased/cloud/users/audit-log/index.html
+++ b/versions/unreleased/cloud/users/audit-log/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/index.html b/versions/unreleased/cloud/users/index.html
index 919fcb4bd6..bbd33f88b2 100644
--- a/versions/unreleased/cloud/users/index.html
+++ b/versions/unreleased/cloud/users/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/object-access-control-lists/index.html b/versions/unreleased/cloud/users/object-access-control-lists/index.html
index de1adc033e..bbbd755d23 100644
--- a/versions/unreleased/cloud/users/object-access-control-lists/index.html
+++ b/versions/unreleased/cloud/users/object-access-control-lists/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/roles/index.html b/versions/unreleased/cloud/users/roles/index.html
index bd2a49f367..a8650468aa 100644
--- a/versions/unreleased/cloud/users/roles/index.html
+++ b/versions/unreleased/cloud/users/roles/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/service-accounts/index.html b/versions/unreleased/cloud/users/service-accounts/index.html
index 9e7d8a85c3..6500364e11 100644
--- a/versions/unreleased/cloud/users/service-accounts/index.html
+++ b/versions/unreleased/cloud/users/service-accounts/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/sso/index.html b/versions/unreleased/cloud/users/sso/index.html
index f0a9634c94..a6ea8c46c1 100644
--- a/versions/unreleased/cloud/users/sso/index.html
+++ b/versions/unreleased/cloud/users/sso/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/users/teams/index.html b/versions/unreleased/cloud/users/teams/index.html
index bec8ea657f..44a4dc0136 100644
--- a/versions/unreleased/cloud/users/teams/index.html
+++ b/versions/unreleased/cloud/users/teams/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/cloud/workspaces/index.html b/versions/unreleased/cloud/workspaces/index.html
index 8b84d4d484..da364d2595 100644
--- a/versions/unreleased/cloud/workspaces/index.html
+++ b/versions/unreleased/cloud/workspaces/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/community/index.html b/versions/unreleased/community/index.html
index 685755fdad..02046329fa 100644
--- a/versions/unreleased/community/index.html
+++ b/versions/unreleased/community/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/agents/index.html b/versions/unreleased/concepts/agents/index.html
index 481ccf12be..4f191b36bf 100644
--- a/versions/unreleased/concepts/agents/index.html
+++ b/versions/unreleased/concepts/agents/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/artifacts/index.html b/versions/unreleased/concepts/artifacts/index.html
index 71e61fd8ae..58e12cbba8 100644
--- a/versions/unreleased/concepts/artifacts/index.html
+++ b/versions/unreleased/concepts/artifacts/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/automations/index.html b/versions/unreleased/concepts/automations/index.html
index 5dfb6592c7..53bb826605 100644
--- a/versions/unreleased/concepts/automations/index.html
+++ b/versions/unreleased/concepts/automations/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/blocks/index.html b/versions/unreleased/concepts/blocks/index.html
index 94572af0ce..f4de5033d3 100644
--- a/versions/unreleased/concepts/blocks/index.html
+++ b/versions/unreleased/concepts/blocks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/deployments-block-based/index.html b/versions/unreleased/concepts/deployments-block-based/index.html
index ec764d46bb..201796427a 100644
--- a/versions/unreleased/concepts/deployments-block-based/index.html
+++ b/versions/unreleased/concepts/deployments-block-based/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/deployments/index.html b/versions/unreleased/concepts/deployments/index.html
index 34efe72750..85fc99be81 100644
--- a/versions/unreleased/concepts/deployments/index.html
+++ b/versions/unreleased/concepts/deployments/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/filesystems/index.html b/versions/unreleased/concepts/filesystems/index.html
index e6bfcbc80c..bd82509538 100644
--- a/versions/unreleased/concepts/filesystems/index.html
+++ b/versions/unreleased/concepts/filesystems/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/flows/index.html b/versions/unreleased/concepts/flows/index.html
index 959e8576e5..7840f0743d 100644
--- a/versions/unreleased/concepts/flows/index.html
+++ b/versions/unreleased/concepts/flows/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/index.html b/versions/unreleased/concepts/index.html
index 8cd08efd54..4f469c2d26 100644
--- a/versions/unreleased/concepts/index.html
+++ b/versions/unreleased/concepts/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/infrastructure/index.html b/versions/unreleased/concepts/infrastructure/index.html
index ba9d9d5334..f068c88e73 100644
--- a/versions/unreleased/concepts/infrastructure/index.html
+++ b/versions/unreleased/concepts/infrastructure/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/results/index.html b/versions/unreleased/concepts/results/index.html
index 4851605804..5e4c9c6f2e 100644
--- a/versions/unreleased/concepts/results/index.html
+++ b/versions/unreleased/concepts/results/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/schedules/index.html b/versions/unreleased/concepts/schedules/index.html
index df6c84c583..f160d57eb0 100644
--- a/versions/unreleased/concepts/schedules/index.html
+++ b/versions/unreleased/concepts/schedules/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/states/index.html b/versions/unreleased/concepts/states/index.html
index 18f4e5e47d..26950bfb06 100644
--- a/versions/unreleased/concepts/states/index.html
+++ b/versions/unreleased/concepts/states/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/storage/index.html b/versions/unreleased/concepts/storage/index.html
index 99ce2b041e..9f55c3ae40 100644
--- a/versions/unreleased/concepts/storage/index.html
+++ b/versions/unreleased/concepts/storage/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/task-runners/index.html b/versions/unreleased/concepts/task-runners/index.html
index 2ba5b4b2d3..0c998583e4 100644
--- a/versions/unreleased/concepts/task-runners/index.html
+++ b/versions/unreleased/concepts/task-runners/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/tasks/index.html b/versions/unreleased/concepts/tasks/index.html
index 3da834783b..4190474130 100644
--- a/versions/unreleased/concepts/tasks/index.html
+++ b/versions/unreleased/concepts/tasks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/concepts/work-pools/index.html b/versions/unreleased/concepts/work-pools/index.html
index 9fbcb63b42..341120ce49 100644
--- a/versions/unreleased/concepts/work-pools/index.html
+++ b/versions/unreleased/concepts/work-pools/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/contributing/overview/index.html b/versions/unreleased/contributing/overview/index.html
index 0778760dda..b422b19f55 100644
--- a/versions/unreleased/contributing/overview/index.html
+++ b/versions/unreleased/contributing/overview/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/contributing/style/index.html b/versions/unreleased/contributing/style/index.html
index 13258c82e3..586c608618 100644
--- a/versions/unreleased/contributing/style/index.html
+++ b/versions/unreleased/contributing/style/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/contributing/versioning/index.html b/versions/unreleased/contributing/versioning/index.html
index d8b84cfbf7..ff6137a6c8 100644
--- a/versions/unreleased/contributing/versioning/index.html
+++ b/versions/unreleased/contributing/versioning/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/faq/index.html b/versions/unreleased/faq/index.html
index d8a20f90f0..6b4a82c32d 100644
--- a/versions/unreleased/faq/index.html
+++ b/versions/unreleased/faq/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/getting-started/installation/index.html b/versions/unreleased/getting-started/installation/index.html
index f6223d4d1e..d12521d57e 100644
--- a/versions/unreleased/getting-started/installation/index.html
+++ b/versions/unreleased/getting-started/installation/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/getting-started/quickstart/index.html b/versions/unreleased/getting-started/quickstart/index.html
index 9d319c7762..555fe5dbf9 100644
--- a/versions/unreleased/getting-started/quickstart/index.html
+++ b/versions/unreleased/getting-started/quickstart/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/automations/index.html b/versions/unreleased/guides/automations/index.html
index 0f56c6a870..d2e852c1b5 100644
--- a/versions/unreleased/guides/automations/index.html
+++ b/versions/unreleased/guides/automations/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/big-data/index.html b/versions/unreleased/guides/big-data/index.html
index 0e432d0d83..76f34fdf2a 100644
--- a/versions/unreleased/guides/big-data/index.html
+++ b/versions/unreleased/guides/big-data/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/ci-cd/index.html b/versions/unreleased/guides/ci-cd/index.html
index 73b2bf770a..afd0ec4064 100644
--- a/versions/unreleased/guides/ci-cd/index.html
+++ b/versions/unreleased/guides/ci-cd/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/cli-shell/index.html b/versions/unreleased/guides/cli-shell/index.html
index 846d0e2d8c..65650653b1 100644
--- a/versions/unreleased/guides/cli-shell/index.html
+++ b/versions/unreleased/guides/cli-shell/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/creating-interactive-workflows/index.html b/versions/unreleased/guides/creating-interactive-workflows/index.html
index 9ab218458b..730dad52f7 100644
--- a/versions/unreleased/guides/creating-interactive-workflows/index.html
+++ b/versions/unreleased/guides/creating-interactive-workflows/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/dask-ray-task-runners/index.html b/versions/unreleased/guides/dask-ray-task-runners/index.html
index bb408d9f3b..8ce5df42dc 100644
--- a/versions/unreleased/guides/dask-ray-task-runners/index.html
+++ b/versions/unreleased/guides/dask-ray-task-runners/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/aci/index.html b/versions/unreleased/guides/deployment/aci/index.html
index 5b9097b575..386781093f 100644
--- a/versions/unreleased/guides/deployment/aci/index.html
+++ b/versions/unreleased/guides/deployment/aci/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/daemonize/index.html b/versions/unreleased/guides/deployment/daemonize/index.html
index 64b85aee26..7514a9ec99 100644
--- a/versions/unreleased/guides/deployment/daemonize/index.html
+++ b/versions/unreleased/guides/deployment/daemonize/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/developing-a-new-worker-type/index.html b/versions/unreleased/guides/deployment/developing-a-new-worker-type/index.html
index 5efa7d6e45..21adb1fe14 100644
--- a/versions/unreleased/guides/deployment/developing-a-new-worker-type/index.html
+++ b/versions/unreleased/guides/deployment/developing-a-new-worker-type/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/kubernetes/index.html b/versions/unreleased/guides/deployment/kubernetes/index.html
index cd60730533..c40cc5c560 100644
--- a/versions/unreleased/guides/deployment/kubernetes/index.html
+++ b/versions/unreleased/guides/deployment/kubernetes/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/overriding-job-variables/index.html b/versions/unreleased/guides/deployment/overriding-job-variables/index.html
index 96e72c827f..039f366e30 100644
--- a/versions/unreleased/guides/deployment/overriding-job-variables/index.html
+++ b/versions/unreleased/guides/deployment/overriding-job-variables/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/push-work-pools/index.html b/versions/unreleased/guides/deployment/push-work-pools/index.html
index bc3b99e27d..a029a7c75d 100644
--- a/versions/unreleased/guides/deployment/push-work-pools/index.html
+++ b/versions/unreleased/guides/deployment/push-work-pools/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/serverless-workers/index.html b/versions/unreleased/guides/deployment/serverless-workers/index.html
index 4c3ed975cd..f380d419f6 100644
--- a/versions/unreleased/guides/deployment/serverless-workers/index.html
+++ b/versions/unreleased/guides/deployment/serverless-workers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/deployment/storage-guide/index.html b/versions/unreleased/guides/deployment/storage-guide/index.html
index a4b6c3d221..8dfa47d587 100644
--- a/versions/unreleased/guides/deployment/storage-guide/index.html
+++ b/versions/unreleased/guides/deployment/storage-guide/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/docker/index.html b/versions/unreleased/guides/docker/index.html
index e411ec2e41..073298ba1e 100644
--- a/versions/unreleased/guides/docker/index.html
+++ b/versions/unreleased/guides/docker/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/global-concurrency-limits/index.html b/versions/unreleased/guides/global-concurrency-limits/index.html
index ad77ad8b54..686bae9da3 100644
--- a/versions/unreleased/guides/global-concurrency-limits/index.html
+++ b/versions/unreleased/guides/global-concurrency-limits/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/host/index.html b/versions/unreleased/guides/host/index.html
index c5fe366029..d6cc44cdfa 100644
--- a/versions/unreleased/guides/host/index.html
+++ b/versions/unreleased/guides/host/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/index.html b/versions/unreleased/guides/index.html
index 162a07068b..dbd115e7bc 100644
--- a/versions/unreleased/guides/index.html
+++ b/versions/unreleased/guides/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/logs/index.html b/versions/unreleased/guides/logs/index.html
index ac3ac6ae86..4f363d1572 100644
--- a/versions/unreleased/guides/logs/index.html
+++ b/versions/unreleased/guides/logs/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/managed-execution/index.html b/versions/unreleased/guides/managed-execution/index.html
index a44e359635..888babe62a 100644
--- a/versions/unreleased/guides/managed-execution/index.html
+++ b/versions/unreleased/guides/managed-execution/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/migration-guide/index.html b/versions/unreleased/guides/migration-guide/index.html
index 1e90cc241f..9a1d17fe07 100644
--- a/versions/unreleased/guides/migration-guide/index.html
+++ b/versions/unreleased/guides/migration-guide/index.html
@@ -206,7 +206,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/moving-data/index.html b/versions/unreleased/guides/moving-data/index.html
index 0bae942d64..94a452f347 100644
--- a/versions/unreleased/guides/moving-data/index.html
+++ b/versions/unreleased/guides/moving-data/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/prefect-deploy/index.html b/versions/unreleased/guides/prefect-deploy/index.html
index 92b441fe42..ab2bda6353 100644
--- a/versions/unreleased/guides/prefect-deploy/index.html
+++ b/versions/unreleased/guides/prefect-deploy/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/runtime-context/index.html b/versions/unreleased/guides/runtime-context/index.html
index dd1c6c8bf7..2f6d875ae1 100644
--- a/versions/unreleased/guides/runtime-context/index.html
+++ b/versions/unreleased/guides/runtime-context/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/secrets/index.html b/versions/unreleased/guides/secrets/index.html
index ebfa524f50..54898a6309 100644
--- a/versions/unreleased/guides/secrets/index.html
+++ b/versions/unreleased/guides/secrets/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/settings/index.html b/versions/unreleased/guides/settings/index.html
index 94fd3135fe..d5b9abf74c 100644
--- a/versions/unreleased/guides/settings/index.html
+++ b/versions/unreleased/guides/settings/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/specifying-upstream-dependencies/index.html b/versions/unreleased/guides/specifying-upstream-dependencies/index.html
index b0ac61b102..c853b43fc8 100644
--- a/versions/unreleased/guides/specifying-upstream-dependencies/index.html
+++ b/versions/unreleased/guides/specifying-upstream-dependencies/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/state-change-hooks/index.html b/versions/unreleased/guides/state-change-hooks/index.html
index 9a6c0e0c6a..cc44378ac0 100644
--- a/versions/unreleased/guides/state-change-hooks/index.html
+++ b/versions/unreleased/guides/state-change-hooks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/testing/index.html b/versions/unreleased/guides/testing/index.html
index 3a26ad2193..51dab4e7bd 100644
--- a/versions/unreleased/guides/testing/index.html
+++ b/versions/unreleased/guides/testing/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/troubleshooting/index.html b/versions/unreleased/guides/troubleshooting/index.html
index 465ee8d38f..09d4b58591 100644
--- a/versions/unreleased/guides/troubleshooting/index.html
+++ b/versions/unreleased/guides/troubleshooting/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/upgrade-guide-agents-to-workers/index.html b/versions/unreleased/guides/upgrade-guide-agents-to-workers/index.html
index 254a30ce28..9d27594dc4 100644
--- a/versions/unreleased/guides/upgrade-guide-agents-to-workers/index.html
+++ b/versions/unreleased/guides/upgrade-guide-agents-to-workers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/using-the-client/index.html b/versions/unreleased/guides/using-the-client/index.html
index ba33e5375b..287c850c77 100644
--- a/versions/unreleased/guides/using-the-client/index.html
+++ b/versions/unreleased/guides/using-the-client/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/variables/index.html b/versions/unreleased/guides/variables/index.html
index e6abe0e1ef..35721a265c 100644
--- a/versions/unreleased/guides/variables/index.html
+++ b/versions/unreleased/guides/variables/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/guides/webhooks/index.html b/versions/unreleased/guides/webhooks/index.html
index 462d1f1e97..88e3d29a08 100644
--- a/versions/unreleased/guides/webhooks/index.html
+++ b/versions/unreleased/guides/webhooks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/index.html b/versions/unreleased/index.html
index d86a1f602c..29aef6d4a6 100644
--- a/versions/unreleased/index.html
+++ b/versions/unreleased/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/contribute/index.html b/versions/unreleased/integrations/contribute/index.html
index 34e58c5813..de890eefea 100644
--- a/versions/unreleased/integrations/contribute/index.html
+++ b/versions/unreleased/integrations/contribute/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/index.html b/versions/unreleased/integrations/index.html
index 57a8e76c6b..100978a001 100644
--- a/versions/unreleased/integrations/index.html
+++ b/versions/unreleased/integrations/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-aws/batch/index.html b/versions/unreleased/integrations/prefect-aws/batch/index.html
index df6e832677..3d0fc6a489 100644
--- a/versions/unreleased/integrations/prefect-aws/batch/index.html
+++ b/versions/unreleased/integrations/prefect-aws/batch/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13224,7 +13225,7 @@ <h1 id="prefect_aws.batch" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with AWS Batch</p>
+        <p>Tasks for interacting with AWS Batch</p>
 
 
 
@@ -13253,7 +13254,7 @@ <h2 id="prefect_aws.batch.batch_submit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a job to the AWS Batch job service.</p>
+        <p>Submit a job to the AWS Batch job service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-aws/client_waiter/index.html b/versions/unreleased/integrations/prefect-aws/client_waiter/index.html
index 8e8c709e86..c9b54159ab 100644
--- a/versions/unreleased/integrations/prefect-aws/client_waiter/index.html
+++ b/versions/unreleased/integrations/prefect-aws/client_waiter/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13224,7 +13225,7 @@ <h1 id="prefect_aws.client_waiter" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Task for waiting on a long-running AWS job</p>
+        <p>Task for waiting on a long-running AWS job</p>
 
 
 
@@ -13253,7 +13254,7 @@ <h2 id="prefect_aws.client_waiter.client_waiter" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uses the underlying boto3 waiter functionality.</p>
+        <p>Uses the underlying boto3 waiter functionality.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-aws/credentials/index.html b/versions/unreleased/integrations/prefect-aws/credentials/index.html
index 512e370713..51e120a59a 100644
--- a/versions/unreleased/integrations/prefect-aws/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-aws/credentials/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13490,7 +13491,7 @@ <h1 id="prefect_aws.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module handling AWS credentials</p>
+        <p>Module handling AWS credentials</p>
 
 
 
@@ -13519,7 +13520,7 @@ <h2 id="prefect_aws.credentials.AwsCredentials" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Block used to manage authentication with AWS. AWS authentication is
+        <p>Block used to manage authentication with AWS. AWS authentication is
 handled via the <code>boto3</code> module. Refer to the
 <a href="https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html">boto3 docs</a>
 for more info about the possible credential configurations.</p>
@@ -13824,7 +13825,7 @@ <h3 id="prefect_aws.credentials.AwsCredentials.Config" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Config class for pydantic model.</p>
+        <p>Config class for pydantic model.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/credentials.py</code></summary>
@@ -13870,7 +13871,7 @@ <h3 id="prefect_aws.credentials.AwsCredentials.get_boto3_session" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated boto3 session that can be used to create clients
+        <p>Returns an authenticated boto3 session that can be used to create clients
 for AWS services</p>
 
 
@@ -13958,7 +13959,7 @@ <h3 id="prefect_aws.credentials.AwsCredentials.get_client" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Helper method to dynamically get a client type.</p>
+        <p>Helper method to dynamically get a client type.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14086,7 +14087,7 @@ <h3 id="prefect_aws.credentials.AwsCredentials.get_s3_client" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated S3 client.</p>
+        <p>Gets an authenticated S3 client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14145,7 +14146,7 @@ <h3 id="prefect_aws.credentials.AwsCredentials.get_secrets_manager_client" class
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated Secrets Manager client.</p>
+        <p>Gets an authenticated Secrets Manager client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14217,7 +14218,7 @@ <h2 id="prefect_aws.credentials.ClientType" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>The supported boto3 clients.</p>
+        <p>The supported boto3 clients.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/credentials.py</code></summary>
@@ -14273,7 +14274,7 @@ <h2 id="prefect_aws.credentials.MinIOCredentials" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Block used to manage authentication with MinIO. Refer to the
+        <p>Block used to manage authentication with MinIO. Refer to the
 <a href="https://docs.min.io/docs/minio-server-configuration-guide.html">MinIO docs</a>
 for more info about the possible credential configurations.</p>
 
@@ -14592,7 +14593,7 @@ <h3 id="prefect_aws.credentials.MinIOCredentials.Config" class="doc doc-heading"
     <div class="doc doc-contents ">
 
 
-      <p>Config class for pydantic model.</p>
+        <p>Config class for pydantic model.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/credentials.py</code></summary>
@@ -14638,7 +14639,7 @@ <h3 id="prefect_aws.credentials.MinIOCredentials.get_boto3_session" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated boto3 session that can be used to create clients
+        <p>Returns an authenticated boto3 session that can be used to create clients
 and perform object operations on MinIO server.</p>
 
 
@@ -14735,7 +14736,7 @@ <h3 id="prefect_aws.credentials.MinIOCredentials.get_client" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Helper method to dynamically get a client type.</p>
+        <p>Helper method to dynamically get a client type.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14863,7 +14864,7 @@ <h3 id="prefect_aws.credentials.MinIOCredentials.get_s3_client" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated S3 client.</p>
+        <p>Gets an authenticated S3 client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-aws/deployments/steps/index.html b/versions/unreleased/integrations/prefect-aws/deployments/steps/index.html
index 237a46fabd..e8bc6e2a46 100644
--- a/versions/unreleased/integrations/prefect-aws/deployments/steps/index.html
+++ b/versions/unreleased/integrations/prefect-aws/deployments/steps/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13397,7 +13398,7 @@ <h1 id="prefect_aws.deployments.steps" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect deployment steps for code storage and retrieval in S3 and S3
+        <p>Prefect deployment steps for code storage and retrieval in S3 and S3
 compatible services.</p>
 
 
@@ -13427,7 +13428,7 @@ <h2 id="prefect_aws.deployments.steps.PullFromS3Output" class="doc doc-heading">
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The output of the <code>pull_from_s3</code> step.</p>
+        <p>The output of the <code>pull_from_s3</code> step.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13485,7 +13486,7 @@ <h2 id="prefect_aws.deployments.steps.PullProjectFromS3Output" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_aws.deployments.steps.PullFromS3Output" href="#prefect_aws.deployments.steps.PullFromS3Output">PullFromS3Output</a></code></p>
 
 
-      <p>Deprecated. Use <code>PullFromS3Output</code> instead..</p>
+        <p>Deprecated. Use <code>PullFromS3Output</code> instead..</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13533,7 +13534,7 @@ <h2 id="prefect_aws.deployments.steps.PushProjectToS3Output" class="doc doc-head
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_aws.deployments.steps.PushToS3Output" href="#prefect_aws.deployments.steps.PushToS3Output">PushToS3Output</a></code></p>
 
 
-      <p>Deprecated. Use <code>PushToS3Output</code> instead.</p>
+        <p>Deprecated. Use <code>PushToS3Output</code> instead.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13581,7 +13582,7 @@ <h2 id="prefect_aws.deployments.steps.PushToS3Output" class="doc doc-heading">
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The output of the <code>push_to_s3</code> step.</p>
+        <p>The output of the <code>push_to_s3</code> step.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13633,7 +13634,7 @@ <h2 id="prefect_aws.deployments.steps.pull_from_s3" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls the contents of an S3 bucket folder to the current working directory.</p>
+        <p>Pulls the contents of an S3 bucket folder to the current working directory.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13903,7 +13904,7 @@ <h2 id="prefect_aws.deployments.steps.pull_project_from_s3" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Deprecated. Use <code>pull_from_s3</code> instead.</p>
+        <p>Deprecated. Use <code>pull_from_s3</code> instead.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13931,7 +13932,7 @@ <h2 id="prefect_aws.deployments.steps.push_project_to_s3" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Deprecated. Use <code>push_to_s3</code> instead.</p>
+        <p>Deprecated. Use <code>push_to_s3</code> instead.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/deployments/steps.py</code></summary>
@@ -13959,7 +13960,7 @@ <h2 id="prefect_aws.deployments.steps.push_to_s3" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pushes the contents of the current working directory to an S3 bucket,
+        <p>Pushes the contents of the current working directory to an S3 bucket,
 excluding files and folders specified in the ignore_file.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-aws/ecs/index.html b/versions/unreleased/integrations/prefect-aws/ecs/index.html
index ae9835756d..712678a7a7 100644
--- a/versions/unreleased/integrations/prefect-aws/ecs/index.html
+++ b/versions/unreleased/integrations/prefect-aws/ecs/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13610,7 +13611,7 @@ <h1 id="prefect_aws.ecs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This module is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by the ECS worker, which offers enhanced functionality and better performance.</p>
 <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>
@@ -13744,7 +13745,7 @@ <h2 id="prefect_aws.ecs.ECSTask" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="../../../api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This block is deprecated along with Agents and all other Infrastructure blocks.
 It will be removed in prefect v3.</p>
 <p>Run a command as an ECS task.</p>
@@ -16851,7 +16852,7 @@ <h3 id="prefect_aws.ecs.ECSTask.Config" class="doc doc-heading">
     <div class="doc doc-contents ">
 
 
-      <p>Configuration of pydantic.</p>
+        <p>Configuration of pydantic.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -16901,7 +16902,7 @@ <h3 id="prefect_aws.ecs.ECSTask.cast_customizations_to_a_json_patch" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Casts lists to JsonPatch instances.</p>
+        <p>Casts lists to JsonPatch instances.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -16945,7 +16946,7 @@ <h3 id="prefect_aws.ecs.ECSTask.cloudwatch_logs_options_requires_configure_cloud
 
     <div class="doc doc-contents ">
 
-      <p>Enforces that an execution role arn is provided (or could be provided by a
+        <p>Enforces that an execution role arn is provided (or could be provided by a
 runtime task definition) when configuring logging.</p>
 
             <details class="quote">
@@ -16998,7 +16999,7 @@ <h3 id="prefect_aws.ecs.ECSTask.configure_cloudwatch_logs_requires_execution_rol
 
     <div class="doc doc-contents ">
 
-      <p>Enforces that an execution role arn is provided (or could be provided by a
+        <p>Enforces that an execution role arn is provided (or could be provided by a
 runtime task definition) when configuring logging.</p>
 
             <details class="quote">
@@ -17061,7 +17062,7 @@ <h3 id="prefect_aws.ecs.ECSTask.dict" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Convert to a dictionary.</p>
+        <p>Convert to a dictionary.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17101,7 +17102,7 @@ <h3 id="prefect_aws.ecs.ECSTask.generate_work_pool_base_job_template" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Generate a base job template for a cloud-run work pool with the same
+        <p>Generate a base job template for a cloud-run work pool with the same
 configuration as this block.</p>
 
 
@@ -17315,7 +17316,7 @@ <h3 id="prefect_aws.ecs.ECSTask.get_corresponding_worker_type" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Return the corresponding worker type for this infrastructure block.</p>
+        <p>Return the corresponding worker type for this infrastructure block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17343,7 +17344,7 @@ <h3 id="prefect_aws.ecs.ECSTask.image_is_required" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Enforces that an image is available if image is <code>None</code>.</p>
+        <p>Enforces that an image is available if image is <code>None</code>.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17421,7 +17422,7 @@ <h3 id="prefect_aws.ecs.ECSTask.kill" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Kill a task running on ECS.</p>
+        <p>Kill a task running on ECS.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17505,7 +17506,7 @@ <h3 id="prefect_aws.ecs.ECSTask.prepare_for_flow_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return an copy of the block that is prepared to execute a flow run.</p>
+        <p>Return an copy of the block that is prepared to execute a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17589,7 +17590,7 @@ <h3 id="prefect_aws.ecs.ECSTask.preview" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generate a preview of the task definition and task run that will be sent to AWS.</p>
+        <p>Generate a preview of the task definition and task run that will be sent to AWS.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17685,7 +17686,7 @@ <h3 id="prefect_aws.ecs.ECSTask.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run the configured task on ECS.</p>
+        <p>Run the configured task on ECS.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17809,7 +17810,7 @@ <h3 id="prefect_aws.ecs.ECSTask.set_default_configure_cloudwatch_logs" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Streaming output generally requires CloudWatch logs to be configured.</p>
+        <p>Streaming output generally requires CloudWatch logs to be configured.</p>
 <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code>
 defaults to matching the value of <code>stream_output</code>.</p>
 
@@ -17868,7 +17869,7 @@ <h2 id="prefect_aws.ecs.ECSTaskResult" class="doc doc-heading">
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>The result of a run of an ECS task</p>
+        <p>The result of a run of an ECS task</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/ecs.py</code></summary>
@@ -17910,7 +17911,7 @@ <h2 id="prefect_aws.ecs.get_container" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extract a container from a list of containers or container definitions.
+        <p>Extract a container from a list of containers or container definitions.
 If not found, <code>None</code> is returned.</p>
 
             <details class="quote">
@@ -17949,7 +17950,7 @@ <h2 id="prefect_aws.ecs.get_prefect_container" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extract the Prefect container from a list of containers or container definitions.
+        <p>Extract the Prefect container from a list of containers or container definitions.
 If not found, <code>None</code> is returned.</p>
 
             <details class="quote">
@@ -17982,7 +17983,7 @@ <h2 id="prefect_aws.ecs.parse_task_identifier" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Splits identifier into its cluster and task components, e.g.
+        <p>Splits identifier into its cluster and task components, e.g.
 input "cluster_name::task_arn" outputs ("cluster_name", "task_arn").</p>
 
             <details class="quote">
diff --git a/versions/unreleased/integrations/prefect-aws/ecs_guide/index.html b/versions/unreleased/integrations/prefect-aws/ecs_guide/index.html
index 5ecb466586..a234a7946b 100644
--- a/versions/unreleased/integrations/prefect-aws/ecs_guide/index.html
+++ b/versions/unreleased/integrations/prefect-aws/ecs_guide/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-aws/ecs_worker/index.html b/versions/unreleased/integrations/prefect-aws/ecs_worker/index.html
index cb21adfb05..735b8ad9ff 100644
--- a/versions/unreleased/integrations/prefect-aws/ecs_worker/index.html
+++ b/versions/unreleased/integrations/prefect-aws/ecs_worker/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13556,7 +13557,7 @@ <h1 id="prefect_aws.workers.ecs_worker" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect worker for executing flow runs as ECS tasks.</p>
+        <p>Prefect worker for executing flow runs as ECS tasks.</p>
 <p>Get started by creating a work pool:</p>
 <div class="highlight"><pre><span></span><code>$ prefect work-pool create --type ecs my-ecs-pool
 </code></pre></div>
@@ -13615,7 +13616,7 @@ <h2 id="prefect_aws.workers.ecs_worker.CapacityProvider" class="doc doc-heading"
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>The capacity provider strategy to use when running the task.</p>
+        <p>The capacity provider strategy to use when running the task.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -13673,7 +13674,7 @@ <h2 id="prefect_aws.workers.ecs_worker.ECSIdentifier" class="doc doc-heading">
               Bases: <code><span title="typing.NamedTuple">NamedTuple</span></code></p>
 
 
-      <p>The identifier for a running ECS task.</p>
+        <p>The identifier for a running ECS task.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -13729,7 +13730,7 @@ <h2 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Job configuration for an ECS worker.</p>
+        <p>Job configuration for an ECS worker.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -13998,7 +13999,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.cloudwatch_logs_optio
 
     <div class="doc doc-contents ">
 
-      <p>Enforces that an execution role arn is provided (or could be provided by a
+        <p>Enforces that an execution role arn is provided (or could be provided by a
 runtime task definition) when configuring logging.</p>
 
             <details class="quote">
@@ -14051,7 +14052,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.configure_cloudwatch_
 
     <div class="doc doc-contents ">
 
-      <p>Enforces that an execution role arn is provided (or could be provided by a
+        <p>Enforces that an execution role arn is provided (or could be provided by a
 runtime task definition) when configuring logging.</p>
 
             <details class="quote">
@@ -14116,7 +14117,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.container_name_defaul
 
     <div class="doc doc-contents ">
 
-      <p>Infers the container name from the task definition if not provided.</p>
+        <p>Infers the container name from the task definition if not provided.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -14166,7 +14167,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.network_configuration
 
     <div class="doc doc-contents ">
 
-      <p>Enforces a <code>vpc_id</code> is provided when custom network configuration mode is
+        <p>Enforces a <code>vpc_id</code> is provided when custom network configuration mode is
 enabled for network settings.</p>
 
             <details class="quote">
@@ -14209,7 +14210,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.set_default_configure
 
     <div class="doc doc-contents ">
 
-      <p>Streaming output generally requires CloudWatch logs to be configured.</p>
+        <p>Streaming output generally requires CloudWatch logs to be configured.</p>
 <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code>
 defaults to matching the value of <code>stream_output</code>.</p>
 
@@ -14255,7 +14256,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSJobConfiguration.task_run_request_requ
 
     <div class="doc doc-contents ">
 
-      <p>If no task definition is provided, a task definition ARN must be present on the
+        <p>If no task definition is provided, a task definition ARN must be present on the
 task run request.</p>
 
             <details class="quote">
@@ -14317,7 +14318,7 @@ <h2 id="prefect_aws.workers.ecs_worker.ECSVariables" class="doc doc-heading">
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Variables for templating an ECS job.</p>
+        <p>Variables for templating an ECS job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -14785,7 +14786,7 @@ <h2 id="prefect_aws.workers.ecs_worker.ECSWorker" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>A Prefect worker to run flow runs as ECS tasks.</p>
+        <p>A Prefect worker to run flow runs as ECS tasks.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -17088,7 +17089,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSWorker.kill_infrastructure" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Kill a task running on ECS.</p>
+        <p>Kill a task running on ECS.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17184,7 +17185,7 @@ <h3 id="prefect_aws.workers.ecs_worker.ECSWorker.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a given flow run on the current worker.</p>
+        <p>Runs a given flow run on the current worker.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -17333,7 +17334,7 @@ <h2 id="prefect_aws.workers.ecs_worker.ECSWorkerResult" class="doc doc-heading">
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>The result of an ECS job.</p>
+        <p>The result of an ECS job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/workers/ecs_worker.py</code></summary>
@@ -17379,7 +17380,7 @@ <h2 id="prefect_aws.workers.ecs_worker.parse_identifier" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Splits identifier into its cluster and task components, e.g.
+        <p>Splits identifier into its cluster and task components, e.g.
 input "cluster_name::task_arn" outputs ("cluster_name", "task_arn").</p>
 
             <details class="quote">
diff --git a/versions/unreleased/integrations/prefect-aws/glue_job/index.html b/versions/unreleased/integrations/prefect-aws/glue_job/index.html
index 90b58a767e..71bfc93b50 100644
--- a/versions/unreleased/integrations/prefect-aws/glue_job/index.html
+++ b/versions/unreleased/integrations/prefect-aws/glue_job/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13336,7 +13337,7 @@ <h1 id="prefect_aws.glue_job" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with the AWS Glue Job.</p>
+        <p>Integrations with the AWS Glue Job.</p>
 
 
 
@@ -13365,7 +13366,7 @@ <h2 id="prefect_aws.glue_job.GlueJobBlock" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobBlock">JobBlock</span></code></p>
 
 
-      <p>Execute a job to the AWS Glue Job service.</p>
+        <p>Execute a job to the AWS Glue Job service.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13697,7 +13698,7 @@ <h3 id="prefect_aws.glue_job.GlueJobBlock.trigger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>trigger for GlueJobRun</p>
+        <p>trigger for GlueJobRun</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/glue_job.py</code></summary>
@@ -13748,7 +13749,7 @@ <h2 id="prefect_aws.glue_job.GlueJobRun" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobRun">JobRun</span></code>, <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Execute a Glue Job</p>
+        <p>Execute a Glue Job</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/glue_job.py</code></summary>
@@ -13899,7 +13900,7 @@ <h3 id="prefect_aws.glue_job.GlueJobRun.fetch_result" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>fetch glue job state</p>
+        <p>fetch glue job state</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/glue_job.py</code></summary>
@@ -13927,7 +13928,7 @@ <h3 id="prefect_aws.glue_job.GlueJobRun.wait_for_completion" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Wait for the job run to complete and get exit code</p>
+        <p>Wait for the job run to complete and get exit code</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_aws/glue_job.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-aws/index.html b/versions/unreleased/integrations/prefect-aws/index.html
index 7bbf6f9a32..6fbd822507 100644
--- a/versions/unreleased/integrations/prefect-aws/index.html
+++ b/versions/unreleased/integrations/prefect-aws/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-aws/lambda_function/index.html b/versions/unreleased/integrations/prefect-aws/lambda_function/index.html
index 1447b36b63..9416186709 100644
--- a/versions/unreleased/integrations/prefect-aws/lambda_function/index.html
+++ b/versions/unreleased/integrations/prefect-aws/lambda_function/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13280,7 +13281,7 @@ <h1 id="prefect_aws.lambda_function" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with AWS Lambda.</p>
+        <p>Integrations with AWS Lambda.</p>
 <p>Examples:</p>
 <div class="codehilite"><pre><span></span><code><span class="n">Run</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">lambda</span><span class="w"> </span><span class="n">function</span><span class="w"> </span><span class="n">with</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">payload</span>
 
@@ -13356,7 +13357,7 @@ <h2 id="prefect_aws.lambda_function.LambdaFunction" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Invoke a Lambda function. This block is part of the prefect-aws
+        <p>Invoke a Lambda function. This block is part of the prefect-aws
 collection. Install prefect-aws with <code>pip install prefect-aws</code> to use this
 block.</p>
 
@@ -13697,7 +13698,7 @@ <h3 id="prefect_aws.lambda_function.LambdaFunction.Config" class="doc doc-headin
     <div class="doc doc-contents ">
 
 
-      <p>Lambda's pydantic configuration.</p>
+        <p>Lambda's pydantic configuration.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_aws/lambda_function.py</code></summary>
@@ -13747,7 +13748,7 @@ <h3 id="prefect_aws.lambda_function.LambdaFunction.invoke" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p><a href="https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html">Invoke</a>
+        <p><a href="https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html">Invoke</a>
 the Lambda function with the given payload.</p>
 
 
@@ -13847,7 +13848,7 @@ <h3 id="prefect_aws.lambda_function.LambdaFunction.invoke" class="doc doc-headin
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
+        <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws.lambda_function</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">LambdaFunction</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws.credentials</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">AwsCredentials</span>
 
diff --git a/versions/unreleased/integrations/prefect-aws/s3/index.html b/versions/unreleased/integrations/prefect-aws/s3/index.html
index 36b4591e14..ba12a4ad96 100644
--- a/versions/unreleased/integrations/prefect-aws/s3/index.html
+++ b/versions/unreleased/integrations/prefect-aws/s3/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13676,7 +13677,7 @@ <h1 id="prefect_aws.s3" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with AWS S3</p>
+        <p>Tasks for interacting with AWS S3</p>
 
 
 
@@ -13705,7 +13706,7 @@ <h2 id="prefect_aws.s3.S3Bucket" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code>, <code><span title="prefect.blocks.abstract.ObjectStorageBlock">ObjectStorageBlock</span></code></p>
 
 
-      <p>Block used to store data using AWS S3 or S3-compatible object storage like MinIO.</p>
+        <p>Block used to store data using AWS S3 or S3-compatible object storage like MinIO.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -15742,7 +15743,7 @@ <h3 id="prefect_aws.s3.S3Bucket.basepath" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The base path of the S3 bucket.</p>
+        <p>The base path of the S3 bucket.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15787,7 +15788,7 @@ <h3 id="prefect_aws.s3.S3Bucket.copy_object" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uses S3's internal
+        <p>Uses S3's internal
 <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html">CopyObject</a>
 to copy objects within or between buckets. To copy objects between buckets,
 <code>self</code>'s credentials must have permission to read the source object and write
@@ -15887,7 +15888,7 @@ <h3 id="prefect_aws.s3.S3Bucket.copy_object" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Copy</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes_copy</span><span class="o">.</span><span class="n">txt</span><span class="o">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Copy</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes_copy</span><span class="o">.</span><span class="n">txt</span><span class="o">.</span>
 
 <span class="err">```</span><span class="n">python</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws.s3</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">S3Bucket</span>
@@ -16107,7 +16108,7 @@ <h3 id="prefect_aws.s3.S3Bucket.download_folder_to_path" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Downloads objects <em>within</em> a folder (excluding the folder itself)
+        <p>Downloads objects <em>within</em> a folder (excluding the folder itself)
 from the S3 bucket to a folder.</p>
 
 
@@ -16358,7 +16359,7 @@ <h3 id="prefect_aws.s3.S3Bucket.download_object_to_file_object" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from the object storage service to a file-like object,
+        <p>Downloads an object from the object storage service to a file-like object,
 which can be a BytesIO object or a BufferedWriter.</p>
 
 
@@ -16606,7 +16607,7 @@ <h3 id="prefect_aws.s3.S3Bucket.download_object_to_path" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from the S3 bucket to a path.</p>
+        <p>Downloads an object from the S3 bucket to a path.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16832,7 +16833,7 @@ <h3 id="prefect_aws.s3.S3Bucket.get_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Copies a folder from the configured S3 bucket to a local directory.</p>
+        <p>Copies a folder from the configured S3 bucket to a local directory.</p>
 <p>Defaults to copying the entire contents of the block's basepath to the current
 working directory.</p>
 
@@ -17213,7 +17214,7 @@ <h3 id="prefect_aws.s3.S3Bucket.move_object" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uses S3's internal CopyObject and DeleteObject to move objects within or
+        <p>Uses S3's internal CopyObject and DeleteObject to move objects within or
 between buckets. To move objects between buckets, <code>self</code>'s credentials must
 have permission to read and delete the source object and write to the target
 object. If the credentials do not have those permissions, this method will
@@ -17299,7 +17300,7 @@ <h3 id="prefect_aws.s3.S3Bucket.move_object" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Move</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes_copy</span><span class="o">.</span><span class="n">txt</span><span class="o">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Move</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes_copy</span><span class="o">.</span><span class="n">txt</span><span class="o">.</span>
 
 <span class="err">```</span><span class="n">python</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws.s3</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">S3Bucket</span>
@@ -17513,7 +17514,7 @@ <h3 id="prefect_aws.s3.S3Bucket.put_directory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to the configured S3 bucket in a
+        <p>Uploads a directory from a given local path to the configured S3 bucket in a
 given folder.</p>
 <p>Defaults to uploading the entire contents the current working directory to the
 block's basepath.</p>
@@ -17707,7 +17708,7 @@ <h3 id="prefect_aws.s3.S3Bucket.read_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read specified path from S3 and return contents. Provide the entire
+        <p>Read specified path from S3 and return contents. Provide the entire
 path to the key in S3.</p>
 
 
@@ -17846,7 +17847,7 @@ <h3 id="prefect_aws.s3.S3Bucket.stream_from" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Streams an object from another bucket to this bucket. Requires the
+        <p>Streams an object from another bucket to this bucket. Requires the
 object to be downloaded and uploaded in chunks. If <code>self</code>'s credentials
 allow for writes to the other bucket, try using <code>S3Bucket.copy_object</code>.</p>
 
@@ -18112,7 +18113,7 @@ <h3 id="prefect_aws.s3.S3Bucket.upload_from_file_object" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object to the S3 bucket from a file-like object,
+        <p>Uploads an object to the S3 bucket from a file-like object,
 which can be a BytesIO object or a BufferedReader.</p>
 
 
@@ -18347,7 +18348,7 @@ <h3 id="prefect_aws.s3.S3Bucket.upload_from_folder" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads files <em>within</em> a folder (excluding the folder itself)
+        <p>Uploads files <em>within</em> a folder (excluding the folder itself)
 to the object storage service folder.</p>
 
 
@@ -18602,7 +18603,7 @@ <h3 id="prefect_aws.s3.S3Bucket.upload_from_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object from a path to the S3 bucket.</p>
+        <p>Uploads an object from a path to the S3 bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18807,7 +18808,7 @@ <h3 id="prefect_aws.s3.S3Bucket.write_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Writes to an S3 bucket.</p>
+        <p>Writes to an S3 bucket.</p>
 <p>Args:</p>
 <div class="codehilite"><pre><span></span><code><span class="n">path</span><span class="p">:</span><span class="w"> </span><span class="n">The</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="n">name</span><span class="o">.</span><span class="w"> </span><span class="n">Each</span><span class="w"> </span><span class="n">object</span><span class="w"> </span><span class="ow">in</span><span class="w"> </span><span class="n">your</span><span class="w"> </span><span class="n">bucket</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">unique</span>
 <span class="w">    </span><span class="n">key</span><span class="w"> </span><span class="p">(</span><span class="ow">or</span><span class="w"> </span><span class="n">key</span><span class="w"> </span><span class="n">name</span><span class="p">)</span><span class="o">.</span>
@@ -18942,7 +18943,7 @@ <h2 id="prefect_aws.s3.s3_copy" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uses S3's internal
+        <p>Uses S3's internal
 <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html">CopyObject</a>
 to copy objects within or between buckets. To copy objects between buckets, the
 credentials must have permission to read the source object and write to the target
@@ -19070,7 +19071,7 @@ <h2 id="prefect_aws.s3.s3_copy" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="n">Copy</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">s3</span><span class="p">:</span><span class="o">//</span><span class="n">my</span><span class="o">-</span><span class="n">bucket</span><span class="o">/</span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span>
+        <div class="codehilite"><pre><span></span><code><span class="n">Copy</span><span class="w"> </span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="kn">from</span><span class="w"> </span><span class="nn">s3</span><span class="p">:</span><span class="o">//</span><span class="n">my</span><span class="o">-</span><span class="n">bucket</span><span class="o">/</span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes</span><span class="o">.</span><span class="n">txt</span><span class="w"> </span><span class="n">to</span>
 <span class="n">s3</span><span class="p">:</span><span class="o">//</span><span class="n">my</span><span class="o">-</span><span class="n">bucket</span><span class="o">/</span><span class="n">my_folder</span><span class="o">/</span><span class="n">notes_copy</span><span class="o">.</span><span class="n">txt</span><span class="o">.</span>
 
 <span class="err">```</span><span class="n">python</span>
@@ -19334,7 +19335,7 @@ <h2 id="prefect_aws.s3.s3_download" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object with a given key from a given S3 bucket.</p>
+        <p>Downloads an object with a given key from a given S3 bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19598,7 +19599,7 @@ <h2 id="prefect_aws.s3.s3_list_objects" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Lists details of objects in a given S3 bucket.</p>
+        <p>Lists details of objects in a given S3 bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19941,7 +19942,7 @@ <h2 id="prefect_aws.s3.s3_move" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Move an object from one S3 location to another. To move objects between buckets,
+        <p>Move an object from one S3 location to another. To move objects between buckets,
 the credentials must have permission to read and delete the source object and write
 to the target object. If the credentials do not have those permissions, this method
 will raise an error. If the credentials have permission to read the source object
@@ -20182,7 +20183,7 @@ <h2 id="prefect_aws.s3.s3_upload" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads data to an S3 bucket.</p>
+        <p>Uploads data to an S3 bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-aws/secrets_manager/index.html b/versions/unreleased/integrations/prefect-aws/secrets_manager/index.html
index 1a7a53fbd3..0912fcb0f0 100644
--- a/versions/unreleased/integrations/prefect-aws/secrets_manager/index.html
+++ b/versions/unreleased/integrations/prefect-aws/secrets_manager/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13390,7 +13391,7 @@ <h1 id="prefect_aws.secrets_manager" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with AWS Secrets Manager</p>
+        <p>Tasks for interacting with AWS Secrets Manager</p>
 
 
 
@@ -13419,7 +13420,7 @@ <h2 id="prefect_aws.secrets_manager.AwsSecret" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.SecretBlock">SecretBlock</span></code></p>
 
 
-      <p>Manages a secret in AWS's Secrets Manager.</p>
+        <p>Manages a secret in AWS's Secrets Manager.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13796,7 +13797,7 @@ <h3 id="prefect_aws.secrets_manager.AwsSecret.delete_secret" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Deletes the secret from the secret storage service.</p>
+        <p>Deletes the secret from the secret storage service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14008,7 +14009,7 @@ <h3 id="prefect_aws.secrets_manager.AwsSecret.read_secret" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Reads the secret from the secret storage service.</p>
+        <p>Reads the secret from the secret storage service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14208,7 +14209,7 @@ <h3 id="prefect_aws.secrets_manager.AwsSecret.write_secret" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Writes the secret to the secret storage service as a SecretBinary;
+        <p>Writes the secret to the secret storage service as a SecretBinary;
 if it doesn't exist, it will be created.</p>
 
 
@@ -14404,7 +14405,7 @@ <h2 id="prefect_aws.secrets_manager.create_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a secret in AWS Secrets Manager.</p>
+        <p>Creates a secret in AWS Secrets Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14526,7 +14527,7 @@ <h2 id="prefect_aws.secrets_manager.create_secret" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
+        <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">flow</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">AwsCredentials</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_aws.secrets_manager</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">create_secret</span>
@@ -14745,7 +14746,7 @@ <h2 id="prefect_aws.secrets_manager.delete_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a secret from AWS Secrets Manager.</p>
+        <p>Deletes a secret from AWS Secrets Manager.</p>
 <p>Secrets can either be deleted immediately by setting <code>force_delete_without_recovery</code>
 equal to <code>True</code>. Otherwise, secrets will be marked for deletion and available for
 recovery for the number of days specified in <code>recovery_window_in_days</code></p>
@@ -15138,7 +15139,7 @@ <h2 id="prefect_aws.secrets_manager.read_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Reads the value of a given secret from AWS Secrets Manager.</p>
+        <p>Reads the value of a given secret from AWS Secrets Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15409,7 +15410,7 @@ <h2 id="prefect_aws.secrets_manager.update_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates the value of a given secret in AWS Secrets Manager.</p>
+        <p>Updates the value of a given secret in AWS Secrets Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-azure/aci_worker/index.html b/versions/unreleased/integrations/prefect-azure/aci_worker/index.html
index 168899f5e7..70b925bf56 100644
--- a/versions/unreleased/integrations/prefect-azure/aci_worker/index.html
+++ b/versions/unreleased/integrations/prefect-azure/aci_worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-azure/blob_storage/index.html b/versions/unreleased/integrations/prefect-azure/blob_storage/index.html
index 457c6471e1..3f64d90ec9 100644
--- a/versions/unreleased/integrations/prefect-azure/blob_storage/index.html
+++ b/versions/unreleased/integrations/prefect-azure/blob_storage/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13520,7 +13521,7 @@ <h1 id="prefect_azure.blob_storage" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations for interacting with Azure Blob Storage</p>
+        <p>Integrations for interacting with Azure Blob Storage</p>
 
 
 
@@ -13549,7 +13550,7 @@ <h2 id="prefect_azure.blob_storage.AzureBlobStorageContainer" class="doc doc-hea
               Bases: <code><span title="prefect.blocks.abstract.ObjectStorageBlock">ObjectStorageBlock</span></code>, <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code></p>
 
 
-      <p>Represents a container in Azure Blob Storage.</p>
+        <p>Represents a container in Azure Blob Storage.</p>
 <p>This class provides methods for downloading and uploading files and folders
 to and from the Azure Blob Storage container.</p>
 
@@ -14656,7 +14657,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.download_folder_to_
 
     <div class="doc doc-contents ">
 
-      <p>Download a folder from the container to a local path.</p>
+        <p>Download a folder from the container to a local path.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14924,7 +14925,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from the container to a file object.</p>
+        <p>Downloads an object from the container to a file object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15163,7 +15164,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from a container to a specified path.</p>
+        <p>Downloads an object from a container to a specified path.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15417,7 +15418,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.get_directory" clas
 
     <div class="doc doc-contents ">
 
-      <p>Downloads the contents of a direry from the blob storage to a local path.</p>
+        <p>Downloads the contents of a direry from the blob storage to a local path.</p>
 <p>Used to enable flow code storage for deployments.</p>
 
 
@@ -15513,7 +15514,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.put_directory" clas
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory to the blob storage.</p>
+        <p>Uploads a directory to the blob storage.</p>
 <p>Used to enable flow code storage for deployments.</p>
 
 
@@ -15688,7 +15689,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.read_path" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Reads the contents of a file at the specified path and returns it as bytes.</p>
+        <p>Reads the contents of a file at the specified path and returns it as bytes.</p>
 <p>Used to enable results storage.</p>
 
 
@@ -15797,7 +15798,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_file_ob
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object from a file object to the specified path in the blob
+        <p>Uploads an object from a file object to the specified path in the blob
     storage container.</p>
 
 
@@ -16035,7 +16036,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_folder"
 
     <div class="doc doc-contents ">
 
-      <p>Uploads files from a local folder to a specified folder in the Azure
+        <p>Uploads files from a local folder to a specified folder in the Azure
     Blob Storage container.</p>
 
 
@@ -16302,7 +16303,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_path" c
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object from a local path to the specified destination path in the
+        <p>Uploads an object from a local path to the specified destination path in the
     blob storage container.</p>
 
 
@@ -16539,7 +16540,7 @@ <h3 id="prefect_azure.blob_storage.AzureBlobStorageContainer.write_path" class="
 
     <div class="doc doc-contents ">
 
-      <p>Writes the content to the specified path in the blob storage.</p>
+        <p>Writes the content to the specified path in the blob storage.</p>
 <p>Used to enable results storage.</p>
 
 
@@ -16640,7 +16641,7 @@ <h2 id="prefect_azure.blob_storage.blob_storage_download" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a blob with a given key from a given Blob Storage container.
+        <p>Downloads a blob with a given key from a given Blob Storage container.
 Args:
     blob: Name of the blob within this container to retrieve.
     container: Name of the Blob Storage container to retrieve from.
@@ -16784,7 +16785,7 @@ <h2 id="prefect_azure.blob_storage.blob_storage_list" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List objects from a given Blob Storage container.
+        <p>List objects from a given Blob Storage container.
 Args:
     container: Name of the Blob Storage container to retrieve from.
     blob_storage_credentials: Credentials to use for authentication with Azure.
@@ -16956,7 +16957,7 @@ <h2 id="prefect_azure.blob_storage.blob_storage_upload" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads data to an Blob Storage container.
+        <p>Uploads data to an Blob Storage container.
 Args:
     data: Bytes representation of data to upload to Blob Storage.
     container: Name of the Blob Storage container to upload to.
diff --git a/versions/unreleased/integrations/prefect-azure/container_instance/index.html b/versions/unreleased/integrations/prefect-azure/container_instance/index.html
index cadabd174b..1915ab84e8 100644
--- a/versions/unreleased/integrations/prefect-azure/container_instance/index.html
+++ b/versions/unreleased/integrations/prefect-azure/container_instance/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13432,7 +13433,7 @@ <h1 id="prefect_azure.container_instance" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with the Azure Container Instances service.
+        <p>Integrations with the Azure Container Instances service.
 Note this module is experimental. The interfaces within may change without notice.</p>
 <p>The <code>AzureContainerInstanceJob</code> infrastructure block in this module is ideally
 configured via the Prefect UI and run via a Prefect agent, but it can be called directly
@@ -13506,7 +13507,7 @@ <h2 id="prefect_azure.container_instance.ACRManagedIdentity" class="doc doc-head
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Use a Managed Identity to access Azure Container registry. Requires the
+        <p>Use a Managed Identity to access Azure Container registry. Requires the
 user-assigned managed identity be available to the ACI container group.</p>
 
               <details class="quote">
@@ -13589,7 +13590,7 @@ <h2 id="prefect_azure.container_instance.AzureContainerInstanceJob" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="../../../api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This block is deprecated along with Agents and all other Infrastructure blocks.
 It will be removed in prefect v3.</p>
 <p>Run a command using a container on Azure Container Instances.
@@ -15292,7 +15293,7 @@ <h3 id="prefect_azure.container_instance.AzureContainerInstanceJob.generate_work
 
     <div class="doc doc-contents ">
 
-      <p>Generate a base job template for an <code>Azure Container Instance</code> work pool
+        <p>Generate a base job template for an <code>Azure Container Instance</code> work pool
 with the same configuration as this block.</p>
 
 
@@ -15476,7 +15477,7 @@ <h3 id="prefect_azure.container_instance.AzureContainerInstanceJob.get_correspon
 
     <div class="doc doc-contents ">
 
-      <p>Return the corresponding worker type for this infrastructure block.</p>
+        <p>Return the corresponding worker type for this infrastructure block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_azure/container_instance.py</code></summary>
@@ -15510,7 +15511,7 @@ <h3 id="prefect_azure.container_instance.AzureContainerInstanceJob.kill" class="
 
     <div class="doc doc-contents ">
 
-      <p>Kill a flow running in an ACI container group.</p>
+        <p>Kill a flow running in an ACI container group.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15666,7 +15667,7 @@ <h3 id="prefect_azure.container_instance.AzureContainerInstanceJob.preview" clas
 
     <div class="doc doc-contents ">
 
-      <p>Provides a summary of how the container will be created when <code>run</code> is called.</p>
+        <p>Provides a summary of how the container will be created when <code>run</code> is called.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15749,7 +15750,7 @@ <h3 id="prefect_azure.container_instance.AzureContainerInstanceJob.run" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Runs the configured task using an ACI container.</p>
+        <p>Runs the configured task using an ACI container.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15966,7 +15967,7 @@ <h2 id="prefect_azure.container_instance.AzureContainerInstanceJobResult" class=
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>The result of an <code>AzureContainerInstanceJob</code> run.</p>
+        <p>The result of an <code>AzureContainerInstanceJob</code> run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/container_instance.py</code></summary>
@@ -16016,7 +16017,7 @@ <h2 id="prefect_azure.container_instance.ContainerGroupProvisioningState" class=
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Terminal provisioning states for ACI container groups. Per the Azure docs,
+        <p>Terminal provisioning states for ACI container groups. Per the Azure docs,
 the states in this Enum are the only ones that can be relied on as dependencies.</p>
 
               <details class="quote">
@@ -16075,7 +16076,7 @@ <h2 id="prefect_azure.container_instance.ContainerRunState" class="doc doc-headi
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Terminal run states for ACI containers.</p>
+        <p>Terminal run states for ACI containers.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/container_instance.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-azure/container_instance_worker/index.html b/versions/unreleased/integrations/prefect-azure/container_instance_worker/index.html
index 528b3c8409..9e151af863 100644
--- a/versions/unreleased/integrations/prefect-azure/container_instance_worker/index.html
+++ b/versions/unreleased/integrations/prefect-azure/container_instance_worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13422,7 +13423,7 @@ <h1 id="prefect_azure.workers.container_instance" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the Azure Container Instances worker used for executing flow
+        <p>Module containing the Azure Container Instances worker used for executing flow
 runs in ACI containers.</p>
 <p>To start an ACI worker, run the following command:</p>
 <div class="highlight"><pre><span></span><code>prefect<span class="w"> </span>worker<span class="w"> </span>start<span class="w"> </span>--pool<span class="w"> </span><span class="s1">&#39;my-work-pool&#39;</span><span class="w"> </span>--type<span class="w"> </span>azure-container-instance
@@ -13511,7 +13512,7 @@ <h2 id="prefect_azure.workers.container_instance.AzureContainerJobConfiguration"
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Configuration for an Azure Container Instance flow run.</p>
+        <p>Configuration for an Azure Container Instance flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
@@ -13904,7 +13905,7 @@ <h3 id="prefect_azure.workers.container_instance.AzureContainerJobConfiguration.
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the job configuration for a flow run.</p>
+        <p>Prepares the job configuration for a flow run.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
@@ -14027,7 +14028,7 @@ <h2 id="prefect_azure.workers.container_instance.AzureContainerVariables" class=
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Variables for an Azure Container Instance flow run.</p>
+        <p>Variables for an Azure Container Instance flow run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
@@ -14331,7 +14332,7 @@ <h2 id="prefect_azure.workers.container_instance.AzureContainerWorker" class="do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>A Prefect worker that runs flows in an Azure Container Instance.</p>
+        <p>A Prefect worker that runs flows in an Azure Container Instance.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
@@ -15440,7 +15441,7 @@ <h3 id="prefect_azure.workers.container_instance.AzureContainerWorker.kill_infra
 
     <div class="doc doc-contents ">
 
-      <p>Kill a flow running in an ACI container group.</p>
+        <p>Kill a flow running in an ACI container group.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15606,7 +15607,7 @@ <h3 id="prefect_azure.workers.container_instance.AzureContainerWorker.run" class
 
     <div class="doc doc-contents ">
 
-      <p>Run a flow in an Azure Container Instance.
+        <p>Run a flow in an Azure Container Instance.
 Args:
     flow_run: The flow run to run.
     configuration: The configuration for the flow run.
@@ -15854,7 +15855,7 @@ <h2 id="prefect_azure.workers.container_instance.AzureContainerWorkerResult" cla
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
@@ -15900,7 +15901,7 @@ <h2 id="prefect_azure.workers.container_instance.ContainerGroupProvisioningState
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Terminal provisioning states for ACI container groups. Per the Azure docs,
+        <p>Terminal provisioning states for ACI container groups. Per the Azure docs,
 the states in this Enum are the only ones that can be relied on as dependencies.</p>
 
               <details class="quote">
@@ -15959,7 +15960,7 @@ <h2 id="prefect_azure.workers.container_instance.ContainerRunState" class="doc d
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Terminal run states for ACI containers.</p>
+        <p>Terminal run states for ACI containers.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_azure/workers/container_instance.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-azure/cosmos_db/index.html b/versions/unreleased/integrations/prefect-azure/cosmos_db/index.html
index 358f39f549..f866863a3e 100644
--- a/versions/unreleased/integrations/prefect-azure/cosmos_db/index.html
+++ b/versions/unreleased/integrations/prefect-azure/cosmos_db/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13266,7 +13267,7 @@ <h1 id="prefect_azure.cosmos_db" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with Azure Cosmos DB</p>
+        <p>Tasks for interacting with Azure Cosmos DB</p>
 
 
 
@@ -13295,7 +13296,7 @@ <h2 id="prefect_azure.cosmos_db.cosmos_db_create_item" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create an item in the container.</p>
+        <p>Create an item in the container.</p>
 <p>To update or replace an existing item, use the upsert_item method.</p>
 
 
@@ -13610,7 +13611,7 @@ <h2 id="prefect_azure.cosmos_db.cosmos_db_query_items" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Return all results matching the given query.</p>
+        <p>Return all results matching the given query.</p>
 <p>You can use any value for the container name in the FROM clause,
 but often the container name is used.
 In the examples below, the container name is "products,"
@@ -13963,7 +13964,7 @@ <h2 id="prefect_azure.cosmos_db.cosmos_db_read_item" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Get the item identified by item.</p>
+        <p>Get the item identified by item.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-azure/credentials/index.html b/versions/unreleased/integrations/prefect-azure/credentials/index.html
index d4a26454c8..66af8214d9 100644
--- a/versions/unreleased/integrations/prefect-azure/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-azure/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13578,7 +13579,7 @@ <h1 id="prefect_azure.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes used to perform authenticated interactions with Azure</p>
+        <p>Credential classes used to perform authenticated interactions with Azure</p>
 
 
 
@@ -13607,7 +13608,7 @@ <h2 id="prefect_azure.credentials.AzureBlobStorageCredentials" class="doc doc-he
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Stores credentials for authenticating with Azure Blob Storage.</p>
+        <p>Stores credentials for authenticating with Azure Blob Storage.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14067,7 +14068,7 @@ <h3 id="prefect_azure.credentials.AzureBlobStorageCredentials.check_connection_s
 
     <div class="doc doc-contents ">
 
-      <p>Checks that either a connection string or account URL is provided, not both.</p>
+        <p>Checks that either a connection string or account URL is provided, not both.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_azure/credentials.py</code></summary>
@@ -14123,7 +14124,7 @@ <h3 id="prefect_azure.credentials.AzureBlobStorageCredentials.get_blob_client" c
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated Blob client that can be used to
+        <p>Returns an authenticated Blob client that can be used to
 download and upload blobs.</p>
 
 
@@ -14299,7 +14300,7 @@ <h3 id="prefect_azure.credentials.AzureBlobStorageCredentials.get_client" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated base Blob Service client that can be used to create
+        <p>Returns an authenticated base Blob Service client that can be used to create
 other clients for Azure services.</p>
 
 
@@ -14414,7 +14415,7 @@ <h3 id="prefect_azure.credentials.AzureBlobStorageCredentials.get_container_clie
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated Container client that can be used to create clients
+        <p>Returns an authenticated Container client that can be used to create clients
 for Azure services.</p>
 
 
@@ -14586,7 +14587,7 @@ <h2 id="prefect_azure.credentials.AzureContainerInstanceCredentials" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage Azure Container Instances authentication. Stores Azure Service
+        <p>Block used to manage Azure Container Instances authentication. Stores Azure Service
 Principal authentication data.</p>
 
               <details class="quote">
@@ -14848,7 +14849,7 @@ <h3 id="prefect_azure.credentials.AzureContainerInstanceCredentials.get_containe
 
     <div class="doc doc-contents ">
 
-      <p>Creates an Azure Container Instances client initialized with data from
+        <p>Creates an Azure Container Instances client initialized with data from
 this block's fields and a provided Azure subscription ID.</p>
 
 
@@ -14952,7 +14953,7 @@ <h3 id="prefect_azure.credentials.AzureContainerInstanceCredentials.get_resource
 
     <div class="doc doc-contents ">
 
-      <p>Creates an Azure resource management client initialized with data from
+        <p>Creates an Azure resource management client initialized with data from
 this block's fields and a provided Azure subscription ID.</p>
 
 
@@ -15056,7 +15057,7 @@ <h3 id="prefect_azure.credentials.AzureContainerInstanceCredentials.validate_cre
 
     <div class="doc doc-contents ">
 
-      <p>Validates that if any of <code>client_id</code>, <code>tenant_id</code>, or <code>client_secret</code> are
+        <p>Validates that if any of <code>client_id</code>, <code>tenant_id</code>, or <code>client_secret</code> are
 provided, all must be provided.</p>
 
             <details class="quote">
@@ -15120,7 +15121,7 @@ <h2 id="prefect_azure.credentials.AzureCosmosDbCredentials" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage Cosmos DB authentication with Azure.
+        <p>Block used to manage Cosmos DB authentication with Azure.
 Azure authentication is handled via the <code>azure</code> module through
 a connection string.</p>
 
@@ -15415,7 +15416,7 @@ <h3 id="prefect_azure.credentials.AzureCosmosDbCredentials.get_client" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated Cosmos client that can be used to create
+        <p>Returns an authenticated Cosmos client that can be used to create
 other clients for Azure services.</p>
 
 
@@ -15512,7 +15513,7 @@ <h3 id="prefect_azure.credentials.AzureCosmosDbCredentials.get_container_client"
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated Container client used for querying.</p>
+        <p>Returns an authenticated Container client used for querying.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15655,7 +15656,7 @@ <h3 id="prefect_azure.credentials.AzureCosmosDbCredentials.get_database_client"
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated Database client.</p>
+        <p>Returns an authenticated Database client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15795,7 +15796,7 @@ <h2 id="prefect_azure.credentials.AzureMlCredentials" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage authentication with AzureML. Azure authentication is
+        <p>Block used to manage authentication with AzureML. Azure authentication is
 handled via the <code>azure</code> module.</p>
 
 
@@ -16098,7 +16099,7 @@ <h3 id="prefect_azure.credentials.AzureMlCredentials.get_workspace" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated base Workspace that can be used in
+        <p>Returns an authenticated base Workspace that can be used in
 Azure's Datasets and Datastores.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-azure/deployments/steps/index.html b/versions/unreleased/integrations/prefect-azure/deployments/steps/index.html
index a6f49e002f..fc11294052 100644
--- a/versions/unreleased/integrations/prefect-azure/deployments/steps/index.html
+++ b/versions/unreleased/integrations/prefect-azure/deployments/steps/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13263,7 +13264,7 @@ <h1 id="prefect_azure.deployments.steps" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect deployment steps for code storage and retrieval in Azure Blob Storage.</p>
+        <p>Prefect deployment steps for code storage and retrieval in Azure Blob Storage.</p>
 <p>These steps can be used in a <code>prefect.yaml</code> file to define the default 
 push and pull steps for a group of deployments, or they can be used to 
 define the push and pull steps for a specific deployment.</p>
@@ -13318,7 +13319,7 @@ <h2 id="prefect_azure.deployments.steps.pull_from_azure_blob_storage" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Pulls from an Azure Blob Storage container.</p>
+        <p>Pulls from an Azure Blob Storage container.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13571,7 +13572,7 @@ <h2 id="prefect_azure.deployments.steps.push_to_azure_blob_storage" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Pushes to an Azure Blob Storage container.</p>
+        <p>Pushes to an Azure Blob Storage container.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-azure/index.html b/versions/unreleased/integrations/prefect-azure/index.html
index ed112cf58a..72e9b0dd6c 100644
--- a/versions/unreleased/integrations/prefect-azure/index.html
+++ b/versions/unreleased/integrations/prefect-azure/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-azure/ml_datastore/index.html b/versions/unreleased/integrations/prefect-azure/ml_datastore/index.html
index 0692df9cc8..e51675be48 100644
--- a/versions/unreleased/integrations/prefect-azure/ml_datastore/index.html
+++ b/versions/unreleased/integrations/prefect-azure/ml_datastore/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h1 id="prefect_azure.ml_datastore" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with Azure ML Datastore</p>
+        <p>Tasks for interacting with Azure ML Datastore</p>
 
 
 
@@ -13317,7 +13318,7 @@ <h2 id="prefect_azure.ml_datastore.ml_get_datastore" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gets the Datastore within the Workspace.</p>
+        <p>Gets the Datastore within the Workspace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13479,7 +13480,7 @@ <h2 id="prefect_azure.ml_datastore.ml_list_datastores" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Lists the Datastores in the Workspace.</p>
+        <p>Lists the Datastores in the Workspace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13624,7 +13625,7 @@ <h2 id="prefect_azure.ml_datastore.ml_register_datastore_blob_container" class="
 
     <div class="doc doc-contents ">
 
-      <p>Registers a Azure Blob Storage container as a
+        <p>Registers a Azure Blob Storage container as a
 Datastore in a Azure ML service Workspace.</p>
 
 
@@ -13967,7 +13968,7 @@ <h2 id="prefect_azure.ml_datastore.ml_upload_datastore" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Uploads local files to a Datastore.</p>
+        <p>Uploads local files to a Datastore.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-bitbucket/credentials/index.html b/versions/unreleased/integrations/prefect-bitbucket/credentials/index.html
index d0c504fbf3..8006f5037d 100644
--- a/versions/unreleased/integrations/prefect-bitbucket/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-bitbucket/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13278,7 +13279,7 @@ <h1 id="prefect_bitbucket.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module to enable authenticate interactions with BitBucket.</p>
+        <p>Module to enable authenticate interactions with BitBucket.</p>
 
 
 
@@ -13307,7 +13308,7 @@ <h2 id="prefect_bitbucket.credentials.BitBucketCredentials" class="doc doc-headi
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Store BitBucket credentials to interact with private BitBucket repositories.</p>
+        <p>Store BitBucket credentials to interact with private BitBucket repositories.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13570,7 +13571,7 @@ <h3 id="prefect_bitbucket.credentials.BitBucketCredentials.get_client" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Get an authenticated local or cloud Bitbucket client.</p>
+        <p>Get an authenticated local or cloud Bitbucket client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13709,7 +13710,7 @@ <h2 id="prefect_bitbucket.credentials.ClientType" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>The client type to use.</p>
+        <p>The client type to use.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_bitbucket/credentials.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-bitbucket/index.html b/versions/unreleased/integrations/prefect-bitbucket/index.html
index 49cfa45fc6..a56d1302fa 100644
--- a/versions/unreleased/integrations/prefect-bitbucket/index.html
+++ b/versions/unreleased/integrations/prefect-bitbucket/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-bitbucket/repository/index.html b/versions/unreleased/integrations/prefect-bitbucket/repository/index.html
index b20676917f..2107c8bf49 100644
--- a/versions/unreleased/integrations/prefect-bitbucket/repository/index.html
+++ b/versions/unreleased/integrations/prefect-bitbucket/repository/index.html
@@ -204,7 +204,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13146,7 +13147,7 @@ <h1 id="prefect_bitbucket.repository" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Allows for interaction with a BitBucket repository.</p>
+        <p>Allows for interaction with a BitBucket repository.</p>
 <p>The <code>BitBucket</code> class in this collection is a storage block that lets Prefect agents
 pull Prefect flow code from BitBucket repositories.</p>
 <p>The <code>BitBucket</code> block is ideally configured via the Prefect UI, but can also be used
@@ -13199,7 +13200,7 @@ <h2 id="prefect_bitbucket.repository.BitBucketRepository" class="doc doc-heading
               Bases: <code><span title="prefect.filesystems.ReadableDeploymentStorage">ReadableDeploymentStorage</span></code></p>
 
 
-      <p>Interact with files stored in BitBucket repositories.</p>
+        <p>Interact with files stored in BitBucket repositories.</p>
 <p>An accessible installation of git is required for this block to function
 properly.</p>
 
@@ -13520,7 +13521,7 @@ <h3 id="prefect_bitbucket.repository.BitBucketRepository.get_directory" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Clones a BitBucket project within <code>from_path</code> to the provided <code>local_path</code>.</p>
+        <p>Clones a BitBucket project within <code>from_path</code> to the provided <code>local_path</code>.</p>
 <p>This defaults to cloning the repository reference configured on the
 Block to the present working directory.</p>
 
diff --git a/versions/unreleased/integrations/prefect-dask/index.html b/versions/unreleased/integrations/prefect-dask/index.html
index 30cb2ba14e..d67dcffd5b 100644
--- a/versions/unreleased/integrations/prefect-dask/index.html
+++ b/versions/unreleased/integrations/prefect-dask/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-dask/task_runners/index.html b/versions/unreleased/integrations/prefect-dask/task_runners/index.html
index b7867b943a..a919e1317d 100644
--- a/versions/unreleased/integrations/prefect-dask/task_runners/index.html
+++ b/versions/unreleased/integrations/prefect-dask/task_runners/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_dask.task_runners" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Interface and implementations of the Dask Task Runner.
+        <p>Interface and implementations of the Dask Task Runner.
 <a href="https://docs.prefect.io/api-ref/prefect/task-runners/">Task Runners</a>
 in Prefect are responsible for managing the execution of Prefect task runs.
 Generally speaking, users are not expected to interact with
@@ -13353,7 +13354,7 @@ <h2 id="prefect_dask.task_runners.DaskTaskRunner" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.task_runners.BaseTaskRunner" href="../../../api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner">BaseTaskRunner</a></code></p>
 
 
-      <p>A parallel task_runner that submits tasks to the <code>dask.distributed</code> scheduler.
+        <p>A parallel task_runner that submits tasks to the <code>dask.distributed</code> scheduler.
 By default a temporary <code>distributed.LocalCluster</code> is created (and
 subsequently torn down) within the <code>start()</code> contextmanager. To use a
 different cluster class (e.g.
@@ -14104,7 +14105,7 @@ <h3 id="prefect_dask.task_runners.DaskTaskRunner.duplicate" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Create a new instance of the task runner with the same settings.</p>
+        <p>Create a new instance of the task runner with the same settings.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_dask/task_runners.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-dask/usage_guide/index.html b/versions/unreleased/integrations/prefect-dask/usage_guide/index.html
index 5f4f21c2aa..fbe5394175 100644
--- a/versions/unreleased/integrations/prefect-dask/usage_guide/index.html
+++ b/versions/unreleased/integrations/prefect-dask/usage_guide/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-dask/utils/index.html b/versions/unreleased/integrations/prefect-dask/utils/index.html
index 98543d4d8e..5b558574a6 100644
--- a/versions/unreleased/integrations/prefect-dask/utils/index.html
+++ b/versions/unreleased/integrations/prefect-dask/utils/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13244,7 +13245,7 @@ <h1 id="prefect_dask.utils" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utils to use alongside prefect-dask.</p>
+        <p>Utils to use alongside prefect-dask.</p>
 
 
 
@@ -13273,7 +13274,7 @@ <h2 id="prefect_dask.utils.get_async_dask_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Yields a temporary asynchronous dask client; this is useful
+        <p>Yields a temporary asynchronous dask client; this is useful
 for parallelizing operations on dask collections,
 such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p>
 <p>Without invoking this, workers do not automatically get a client to connect
@@ -13497,7 +13498,7 @@ <h2 id="prefect_dask.utils.get_dask_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Yields a temporary synchronous dask client; this is useful
+        <p>Yields a temporary synchronous dask client; this is useful
 for parallelizing operations on dask collections,
 such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p>
 <p>Without invoking this, workers do not automatically get a client to connect
diff --git a/versions/unreleased/integrations/prefect-databricks/credentials/index.html b/versions/unreleased/integrations/prefect-databricks/credentials/index.html
index 7c7965394f..39feaa9e57 100644
--- a/versions/unreleased/integrations/prefect-databricks/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_databricks.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes used to perform authenticated interactions with Databricks</p>
+        <p>Credential classes used to perform authenticated interactions with Databricks</p>
 
 
 
@@ -13285,7 +13286,7 @@ <h2 id="prefect_databricks.credentials.DatabricksCredentials" class="doc doc-hea
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage Databricks authentication.</p>
+        <p>Block used to manage Databricks authentication.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13494,7 +13495,7 @@ <h3 id="prefect_databricks.credentials.DatabricksCredentials.get_client" class="
 
     <div class="doc doc-contents ">
 
-      <p>Gets an Databricks REST AsyncClient.</p>
+        <p>Gets an Databricks REST AsyncClient.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-databricks/flows/index.html b/versions/unreleased/integrations/prefect-databricks/flows/index.html
index 8b24417521..1c5a857cc7 100644
--- a/versions/unreleased/integrations/prefect-databricks/flows/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/flows/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13354,7 +13355,7 @@ <h1 id="prefect_databricks.flows" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing flows for interacting with Databricks</p>
+        <p>Module containing flows for interacting with Databricks</p>
 
 
 
@@ -13383,7 +13384,7 @@ <h2 id="prefect_databricks.flows.DatabricksJobInternalError" class="doc doc-head
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when Databricks jobs runs submit encounters internal error</p>
+        <p>Raised when Databricks jobs runs submit encounters internal error</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/flows.py</code></summary>
@@ -13413,7 +13414,7 @@ <h2 id="prefect_databricks.flows.DatabricksJobRunTimedOut" class="doc doc-headin
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when Databricks jobs runs does not complete in the configured max
+        <p>Raised when Databricks jobs runs does not complete in the configured max
 wait seconds</p>
 
               <details class="quote">
@@ -13450,7 +13451,7 @@ <h2 id="prefect_databricks.flows.DatabricksJobSkipped" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when Databricks jobs runs submit skips</p>
+        <p>Raised when Databricks jobs runs submit skips</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/flows.py</code></summary>
@@ -13480,7 +13481,7 @@ <h2 id="prefect_databricks.flows.DatabricksJobTerminated" class="doc doc-heading
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when Databricks jobs runs submit terminates</p>
+        <p>Raised when Databricks jobs runs submit terminates</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/flows.py</code></summary>
@@ -13510,7 +13511,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
 
     <div class="doc doc-contents ">
 
-      <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
+        <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13541,7 +13542,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
           <tr class="doc-section-item">
             <td><code>tasks</code></td>
             <td>
-                  <code><span title="typing.List">List</span>[<a class="autorefs autorefs-internal" title="prefect_databricks.models.jobs.RunSubmitTaskSettings" href="../models/jobs/#prefect_databricks.models.jobs.RunSubmitTaskSettings">RunSubmitTaskSettings</a>]</code>
+                  <code><span title="typing.Optional">Optional</span>[<span title="typing.List">List</span>[<a class="autorefs autorefs-internal" title="prefect_databricks.models.jobs.RunSubmitTaskSettings" href="../models/jobs/#prefect_databricks.models.jobs.RunSubmitTaskSettings">RunSubmitTaskSettings</a>]]</code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -13756,6 +13757,20 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
                   <code>False</code>
             </td>
           </tr>
+          <tr class="doc-section-item">
+            <td><code>job_submission_handler</code></td>
+            <td>
+                  <code><span title="typing.Optional">Optional</span>[<span title="typing.Callable">Callable</span>]</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>An optional callable to intercept job submission.</p>
+              </div>
+            </td>
+            <td>
+                  <code>None</code>
+            </td>
+          </tr>
           <tr class="doc-section-item">
             <td><code>**jobs_runs_submit_kwargs</code></td>
             <td>
@@ -13785,7 +13800,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
       <tbody>
           <tr class="doc-section-item">
             <td>
-                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>]]</code>
+                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>], None]</code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -13795,7 +13810,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
           </tr>
           <tr class="doc-section-item">
             <td>
-                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>]]</code>
+                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>], None]</code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -13808,7 +13823,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
           </tr>
           <tr class="doc-section-item">
             <td>
-                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>]]</code>
+                  <code><span title="typing.Union">Union</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="typing.Tuple">Tuple</span>[<span title="prefect_databricks.flows.NotebookOutput">NotebookOutput</span>, <span title="prefect_databricks.flows.JobMetadata">JobMetadata</span>], None]</code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -14150,7 +14165,13 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
 <span class="normal">322</span>
 <span class="normal">323</span>
 <span class="normal">324</span>
-<span class="normal">325</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
+<span class="normal">325</span>
+<span class="normal">326</span>
+<span class="normal">327</span>
+<span class="normal">328</span>
+<span class="normal">329</span>
+<span class="normal">330</span>
+<span class="normal">331</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
     <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Submit jobs runs and wait for completion&quot;</span><span class="p">,</span>
     <span class="n">description</span><span class="o">=</span><span class="p">(</span>
         <span class="s2">&quot;Triggers a Databricks jobs runs and waits for the &quot;</span>
@@ -14159,7 +14180,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
 <span class="p">)</span>
 <span class="k">async</span> <span class="k">def</span> <span class="nf">jobs_runs_submit_and_wait_for_completion</span><span class="p">(</span>
     <span class="n">databricks_credentials</span><span class="p">:</span> <span class="n">DatabricksCredentials</span><span class="p">,</span>
-    <span class="n">tasks</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">RunSubmitTaskSettings</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">tasks</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">RunSubmitTaskSettings</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">run_name</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">max_wait_seconds</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">900</span><span class="p">,</span>
     <span class="n">poll_frequency_seconds</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
@@ -14168,8 +14189,9 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
     <span class="n">idempotency_token</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">access_control_list</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">AccessControlRequest</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">return_metadata</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="n">job_submission_handler</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Callable</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="o">**</span><span class="n">jobs_runs_submit_kwargs</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">],</span>
-<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Union</span><span class="p">[</span><span class="n">NotebookOutput</span><span class="p">,</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">NotebookOutput</span><span class="p">,</span> <span class="n">JobMetadata</span><span class="p">]]:</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Union</span><span class="p">[</span><span class="n">NotebookOutput</span><span class="p">,</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">NotebookOutput</span><span class="p">,</span> <span class="n">JobMetadata</span><span class="p">],</span> <span class="kc">None</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Flow that triggers a job run and waits for the triggered run to complete.</span>
 
@@ -14283,6 +14305,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
 <span class="sd">            run completion.</span>
 <span class="sd">        return_metadata: When True, method will return a tuple of notebook output as well as</span>
 <span class="sd">            job run metadata; by default though, the method only returns notebook output</span>
+<span class="sd">        job_submission_handler: An optional callable to intercept job submission.</span>
 <span class="sd">        **jobs_runs_submit_kwargs: Additional keyword arguments to pass to `jobs_runs_submit`.</span>
 
 <span class="sd">    Returns:</span>
@@ -14363,6 +14386,10 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion" class
         <span class="o">**</span><span class="n">jobs_runs_submit_kwargs</span><span class="p">,</span>
     <span class="p">)</span>
     <span class="n">multi_task_jobs_runs</span> <span class="o">=</span> <span class="k">await</span> <span class="n">multi_task_jobs_runs_future</span><span class="o">.</span><span class="n">result</span><span class="p">()</span>
+    <span class="k">if</span> <span class="n">job_submission_handler</span><span class="p">:</span>
+        <span class="n">result</span> <span class="o">=</span> <span class="n">job_submission_handler</span><span class="p">(</span><span class="n">multi_task_jobs_runs</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">inspect</span><span class="o">.</span><span class="n">isawaitable</span><span class="p">(</span><span class="n">result</span><span class="p">):</span>
+            <span class="k">await</span> <span class="n">result</span>
     <span class="n">multi_task_jobs_runs_id</span> <span class="o">=</span> <span class="n">multi_task_jobs_runs</span><span class="p">[</span><span class="s2">&quot;run_id&quot;</span><span class="p">]</span>
 
     <span class="c1"># wait for all the jobs runs to complete in a separate flow</span>
@@ -14441,7 +14468,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_by_id_and_wait_for_completion"
 
     <div class="doc doc-contents ">
 
-      <p>flow that triggers an existing job and waits for its completion</p>
+        <p>flow that triggers an existing job and waits for its completion</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14796,13 +14823,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_by_id_and_wait_for_completion"
 </details>
             <details class="quote">
               <summary>Source code in <code>prefect_databricks/flows.py</code></summary>
-              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">486</span>
-<span class="normal">487</span>
-<span class="normal">488</span>
-<span class="normal">489</span>
-<span class="normal">490</span>
-<span class="normal">491</span>
-<span class="normal">492</span>
+              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">492</span>
 <span class="normal">493</span>
 <span class="normal">494</span>
 <span class="normal">495</span>
@@ -15007,7 +15028,13 @@ <h2 id="prefect_databricks.flows.jobs_runs_submit_by_id_and_wait_for_completion"
 <span class="normal">694</span>
 <span class="normal">695</span>
 <span class="normal">696</span>
-<span class="normal">697</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
+<span class="normal">697</span>
+<span class="normal">698</span>
+<span class="normal">699</span>
+<span class="normal">700</span>
+<span class="normal">701</span>
+<span class="normal">702</span>
+<span class="normal">703</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
     <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Submit existing job runs and wait for completion&quot;</span><span class="p">,</span>
     <span class="n">description</span><span class="o">=</span><span class="p">(</span>
         <span class="s2">&quot;Triggers a Databricks jobs runs and waits for the &quot;</span>
@@ -15240,7 +15267,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_wait_for_completion" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
+        <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15380,13 +15407,7 @@ <h2 id="prefect_databricks.flows.jobs_runs_wait_for_completion" class="doc doc-h
 </details>
             <details class="quote">
               <summary>Source code in <code>prefect_databricks/flows.py</code></summary>
-              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">399</span>
-<span class="normal">400</span>
-<span class="normal">401</span>
-<span class="normal">402</span>
-<span class="normal">403</span>
-<span class="normal">404</span>
-<span class="normal">405</span>
+              <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">405</span>
 <span class="normal">406</span>
 <span class="normal">407</span>
 <span class="normal">408</span>
@@ -15464,7 +15485,13 @@ <h2 id="prefect_databricks.flows.jobs_runs_wait_for_completion" class="doc doc-h
 <span class="normal">480</span>
 <span class="normal">481</span>
 <span class="normal">482</span>
-<span class="normal">483</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
+<span class="normal">483</span>
+<span class="normal">484</span>
+<span class="normal">485</span>
+<span class="normal">486</span>
+<span class="normal">487</span>
+<span class="normal">488</span>
+<span class="normal">489</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@flow</span><span class="p">(</span>
     <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Wait for completion of jobs runs&quot;</span><span class="p">,</span>
     <span class="n">description</span><span class="o">=</span><span class="s2">&quot;Waits for the jobs runs to finish running&quot;</span><span class="p">,</span>
 <span class="p">)</span>
diff --git a/versions/unreleased/integrations/prefect-databricks/index.html b/versions/unreleased/integrations/prefect-databricks/index.html
index 9b76ff4ac0..334f61d731 100644
--- a/versions/unreleased/integrations/prefect-databricks/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-databricks/jobs/index.html b/versions/unreleased/integrations/prefect-databricks/jobs/index.html
index 6ad36b8979..9be6191606 100644
--- a/versions/unreleased/integrations/prefect-databricks/jobs/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/jobs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13552,7 +13553,7 @@ <h1 id="prefect_databricks.jobs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing tasks for interacting with:
+        <p>This is a module containing tasks for interacting with:
 Databricks jobs</p>
 
 
@@ -13582,7 +13583,7 @@ <h2 id="prefect_databricks.jobs.jobs_create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new job.</p>
+        <p>Create a new job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14006,7 +14007,7 @@ <h2 id="prefect_databricks.jobs.jobs_create" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/create</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -14676,7 +14677,7 @@ <h2 id="prefect_databricks.jobs.jobs_delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a job.</p>
+        <p>Deletes a job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14744,7 +14745,7 @@ <h2 id="prefect_databricks.jobs.jobs_delete" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/delete</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -14898,7 +14899,7 @@ <h2 id="prefect_databricks.jobs.jobs_get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves the details for a single job.</p>
+        <p>Retrieves the details for a single job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14966,7 +14967,7 @@ <h2 id="prefect_databricks.jobs.jobs_get" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/get</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -15120,7 +15121,7 @@ <h2 id="prefect_databricks.jobs.jobs_list" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieves a list of jobs.</p>
+        <p>Retrieves a list of jobs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15231,7 +15232,7 @@ <h2 id="prefect_databricks.jobs.jobs_list" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/list</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -15411,7 +15412,7 @@ <h2 id="prefect_databricks.jobs.jobs_reset" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Overwrites all the settings for a specific job. Use the Update endpoint to
+        <p>Overwrites all the settings for a specific job. Use the Update endpoint to
 update job settings partially.</p>
 
 
@@ -15655,7 +15656,7 @@ <h2 id="prefect_databricks.jobs.jobs_reset" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/reset</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -16149,7 +16150,7 @@ <h2 id="prefect_databricks.jobs.jobs_run_now" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run a job and return the <code>run_id</code> of the triggered run.</p>
+        <p>Run a job and return the <code>run_id</code> of the triggered run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16415,7 +16416,7 @@ <h2 id="prefect_databricks.jobs.jobs_run_now" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/run-now</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -16813,7 +16814,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_cancel" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Cancels a job run. The run is canceled asynchronously, so it may still be
+        <p>Cancels a job run. The run is canceled asynchronously, so it may still be
 running when this request completes.</p>
 
 
@@ -16881,7 +16882,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_cancel" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/cancel</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -17035,7 +17036,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_cancel_all" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Cancels all active runs of a job. The runs are canceled asynchronously, so it
+        <p>Cancels all active runs of a job. The runs are canceled asynchronously, so it
 doesn't prevent new runs from being started.</p>
 
 
@@ -17104,7 +17105,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_cancel_all" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/cancel-all</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -17260,7 +17261,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a non-active run. Returns an error if the run is active.</p>
+        <p>Deletes a non-active run. Returns an error if the run is active.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17328,7 +17329,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_delete" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/delete</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -17482,7 +17483,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_export" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Export and retrieve the job run task.</p>
+        <p>Export and retrieve the job run task.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17563,7 +17564,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_export" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.0/jobs/runs/export</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -17723,7 +17724,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the metadata of a run.</p>
+        <p>Retrieve the metadata of a run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17805,7 +17806,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_get" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/get</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -17967,7 +17968,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_get_output" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the output and metadata of a single task run. When a notebook task
+        <p>Retrieve the output and metadata of a single task run. When a notebook task
 returns a value through the dbutils.notebook.exit() call, you can use this
 endpoint to retrieve that value. Databricks restricts this API to return the
 first 5 MB of the output. To return a larger result, you can store job
@@ -18043,7 +18044,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_get_output" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/get-output</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -18213,7 +18214,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_list" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List runs in descending order by start time.</p>
+        <p>List runs in descending order by start time.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18405,7 +18406,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_list" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/list</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -18651,7 +18652,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_repair" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Re-run one or more tasks. Tasks are re-run as part of the original job run, use
+        <p>Re-run one or more tasks. Tasks are re-run as part of the original job run, use
 the current job and task settings, and can be viewed in the history for the
 original job run.</p>
 
@@ -18944,7 +18945,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_repair" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/repair</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -19356,7 +19357,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_submit" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Submit a one-time run. This endpoint allows you to submit a workload directly
+        <p>Submit a one-time run. This endpoint allows you to submit a workload directly
 without creating a job. Use the <code>jobs/runs/get</code> API to check the run state
 after the job is submitted.</p>
 
@@ -19628,7 +19629,7 @@ <h2 id="prefect_databricks.jobs.jobs_runs_submit" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/runs/submit</code></p>
 <h4>API Responses:</h4>
 <table>
@@ -20082,7 +20083,7 @@ <h2 id="prefect_databricks.jobs.jobs_update" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Add, update, or remove specific settings of an existing job. Use the Reset
+        <p>Add, update, or remove specific settings of an existing job. Use the Reset
 endpoint to overwrite all job settings.</p>
 
 
@@ -20344,7 +20345,7 @@ <h2 id="prefect_databricks.jobs.jobs_update" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <h4>API Endpoint:</h4>
+        <h4>API Endpoint:</h4>
 <p><code>/2.1/jobs/update</code></p>
 <h4>API Responses:</h4>
 <table>
diff --git a/versions/unreleased/integrations/prefect-databricks/models/jobs/index.html b/versions/unreleased/integrations/prefect-databricks/models/jobs/index.html
index 460408ae5b..c770453236 100644
--- a/versions/unreleased/integrations/prefect-databricks/models/jobs/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/models/jobs/index.html
@@ -204,7 +204,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14382,7 +14383,7 @@ <h2 id="prefect_databricks.models.jobs.AccessControlList" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14448,7 +14449,7 @@ <h2 id="prefect_databricks.models.jobs.AccessControlRequest" class="doc doc-head
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_databricks.models.jobs.AccessControlRequestForUser" href="#prefect_databricks.models.jobs.AccessControlRequestForUser">AccessControlRequestForUser</a></code>, <code><a class="autorefs autorefs-internal" title="prefect_databricks.models.jobs.AccessControlRequestForGroup" href="#prefect_databricks.models.jobs.AccessControlRequestForGroup">AccessControlRequestForGroup</a></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14506,7 +14507,7 @@ <h2 id="prefect_databricks.models.jobs.AccessControlRequestForGroup" class="doc
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14570,7 +14571,7 @@ <h2 id="prefect_databricks.models.jobs.AccessControlRequestForServicePrincipal"
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14634,7 +14635,7 @@ <h2 id="prefect_databricks.models.jobs.AccessControlRequestForUser" class="doc d
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14698,7 +14699,7 @@ <h2 id="prefect_databricks.models.jobs.AutoScale" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -14788,7 +14789,7 @@ <h2 id="prefect_databricks.models.jobs.AwsAttributes" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15092,7 +15093,7 @@ <h2 id="prefect_databricks.models.jobs.CanManage" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Permission to manage the job.</p>
+        <p>Permission to manage the job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15146,7 +15147,7 @@ <h2 id="prefect_databricks.models.jobs.CanManageRun" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Permission to run and/or manage runs for the job.</p>
+        <p>Permission to run and/or manage runs for the job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15200,7 +15201,7 @@ <h2 id="prefect_databricks.models.jobs.CanView" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Permission to view the settings of the job.</p>
+        <p>Permission to view the settings of the job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15254,7 +15255,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterAttributes" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15640,7 +15641,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterCloudProviderNodeInfo" class="doc
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15714,7 +15715,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterCloudProviderNodeStatus" class="do
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="nx">NotEnabledOnSubscription</span><span class="p">:</span><span class="w"> </span><span class="nx">Node</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="k">not</span><span class="w"> </span><span class="nx">available</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="nx">subscription</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="nx">NotEnabledOnSubscription</span><span class="p">:</span><span class="w"> </span><span class="nx">Node</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="k">not</span><span class="w"> </span><span class="nx">available</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="nx">subscription</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -15779,7 +15780,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterEvent" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -15871,7 +15872,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterEventType" class="doc doc-heading"
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`CREATING`</span><span class="o">:</span><span class="w"> </span><span class="n">Indicates</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="n">being</span><span class="w"> </span><span class="n">created</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`CREATING`</span><span class="o">:</span><span class="w"> </span><span class="n">Indicates</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="n">being</span><span class="w"> </span><span class="n">created</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -16039,7 +16040,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterInfo" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -16665,7 +16666,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterInstance" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -16771,7 +16772,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterLibraryStatuses" class="doc doc-he
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -16843,7 +16844,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterLogConf" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -16933,7 +16934,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterSize" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17033,7 +17034,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterSource" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="k">*</span> UI: Cluster created through the UI.
+        <div class="codehilite"><pre><span></span><code><span class="k">*</span> UI: Cluster created through the UI.
 </code></pre></div>
 
 <ul>
@@ -17103,7 +17104,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterSpec" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17209,7 +17210,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterState" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span> <span class="n">PENDING</span><span class="p">:</span> <span class="n">Indicates</span> <span class="n">that</span> <span class="n">a</span> <span class="n">cluster</span> <span class="n">is</span> <span class="n">in</span> <span class="n">the</span> <span class="n">process</span> <span class="n">of</span> <span class="n">being</span> <span class="n">created</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span> <span class="n">PENDING</span><span class="p">:</span> <span class="n">Indicates</span> <span class="n">that</span> <span class="n">a</span> <span class="n">cluster</span> <span class="n">is</span> <span class="n">in</span> <span class="n">the</span> <span class="n">process</span> <span class="n">of</span> <span class="n">being</span> <span class="n">created</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -17304,7 +17305,7 @@ <h2 id="prefect_databricks.models.jobs.ClusterTag" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>An object with key value pairs. The key length must be between 1 and 127 UTF-8 characters, inclusive. The value length must be less than or equal to 255 UTF-8 characters. For a list of all restrictions, see AWS Tag Restrictions: <a href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions">https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions</a></p>
 
               <details class="quote">
@@ -17369,7 +17370,7 @@ <h2 id="prefect_databricks.models.jobs.CronSchedule" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17479,7 +17480,7 @@ <h2 id="prefect_databricks.models.jobs.DbfsStorageInfo" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17545,7 +17546,7 @@ <h2 id="prefect_databricks.models.jobs.DbtOutput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17635,7 +17636,7 @@ <h2 id="prefect_databricks.models.jobs.DbtTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17801,7 +17802,7 @@ <h2 id="prefect_databricks.models.jobs.DockerBasicAuth" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17873,7 +17874,7 @@ <h2 id="prefect_databricks.models.jobs.DockerImage" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -17941,7 +17942,7 @@ <h2 id="prefect_databricks.models.jobs.Error" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18021,7 +18022,7 @@ <h2 id="prefect_databricks.models.jobs.EventDetails" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18163,7 +18164,7 @@ <h2 id="prefect_databricks.models.jobs.FileStorageInfo" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18229,7 +18230,7 @@ <h2 id="prefect_databricks.models.jobs.GitSnapshot" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>Read-only state of the remote repository at the time the job was run. This field is only included on job runs.</p>
 
               <details class="quote">
@@ -18312,7 +18313,7 @@ <h2 id="prefect_databricks.models.jobs.GitSource" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <div class="codehilite"><pre><span></span><code>This functionality is in Public Preview.
 </code></pre></div>
 
@@ -18494,7 +18495,7 @@ <h2 id="prefect_databricks.models.jobs.GitSource1" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18580,7 +18581,7 @@ <h2 id="prefect_databricks.models.jobs.GroupName" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18656,7 +18657,7 @@ <h2 id="prefect_databricks.models.jobs.InitScriptInfo" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18762,7 +18763,7 @@ <h2 id="prefect_databricks.models.jobs.IsOwner" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Perimssion that represents ownership of the job.</p>
+        <p>Perimssion that represents ownership of the job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18816,7 +18817,7 @@ <h2 id="prefect_databricks.models.jobs.Job" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -18928,7 +18929,7 @@ <h2 id="prefect_databricks.models.jobs.JobCluster" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -19014,7 +19015,7 @@ <h2 id="prefect_databricks.models.jobs.JobEmailNotifications" class="doc doc-hea
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -19162,7 +19163,7 @@ <h2 id="prefect_databricks.models.jobs.JobSettings" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -19560,7 +19561,7 @@ <h2 id="prefect_databricks.models.jobs.JobTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -19724,7 +19725,7 @@ <h2 id="prefect_databricks.models.jobs.JobTaskSettings" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -20058,7 +20059,7 @@ <h2 id="prefect_databricks.models.jobs.Library" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -20230,7 +20231,7 @@ <h2 id="prefect_databricks.models.jobs.LibraryFullStatus" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -20330,7 +20331,7 @@ <h2 id="prefect_databricks.models.jobs.LibraryInstallStatus" class="doc doc-head
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PENDING`</span><span class="o">:</span><span class="w"> </span><span class="k">No</span><span class="w"> </span><span class="k">action</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">yet</span><span class="w"> </span><span class="n">been</span><span class="w"> </span><span class="n">taken</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="k">install</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">library</span><span class="p">.</span><span class="w"> </span><span class="n">This</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="n">should</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="n">very</span><span class="w"> </span><span class="n">short</span><span class="w"> </span><span class="n">lived</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PENDING`</span><span class="o">:</span><span class="w"> </span><span class="k">No</span><span class="w"> </span><span class="k">action</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">yet</span><span class="w"> </span><span class="n">been</span><span class="w"> </span><span class="n">taken</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="k">install</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">library</span><span class="p">.</span><span class="w"> </span><span class="n">This</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="n">should</span><span class="w"> </span><span class="n">be</span><span class="w"> </span><span class="n">very</span><span class="w"> </span><span class="n">short</span><span class="w"> </span><span class="n">lived</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -20418,7 +20419,7 @@ <h2 id="prefect_databricks.models.jobs.ListOrder" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`DESC`</span><span class="o">:</span><span class="w"> </span><span class="n">Descending</span><span class="w"> </span><span class="k">order</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`DESC`</span><span class="o">:</span><span class="w"> </span><span class="n">Descending</span><span class="w"> </span><span class="k">order</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -20481,7 +20482,7 @@ <h2 id="prefect_databricks.models.jobs.LogSyncStatus" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -20569,7 +20570,7 @@ <h2 id="prefect_databricks.models.jobs.MavenLibrary" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -20679,7 +20680,7 @@ <h2 id="prefect_databricks.models.jobs.NewCluster" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21071,7 +21072,7 @@ <h2 id="prefect_databricks.models.jobs.NodeType" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21213,7 +21214,7 @@ <h2 id="prefect_databricks.models.jobs.NotebookOutput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21303,7 +21304,7 @@ <h2 id="prefect_databricks.models.jobs.NotebookTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21441,7 +21442,7 @@ <h2 id="prefect_databricks.models.jobs.OnFailureItem" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21503,7 +21504,7 @@ <h2 id="prefect_databricks.models.jobs.OnStartItem" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21565,7 +21566,7 @@ <h2 id="prefect_databricks.models.jobs.OnSucces" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21627,7 +21628,7 @@ <h2 id="prefect_databricks.models.jobs.ParameterPair" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>An object with additional information about why a cluster was terminated. The object keys are one of <code>TerminationParameter</code> and the value is the termination information.</p>
 
               <details class="quote">
@@ -21692,7 +21693,7 @@ <h2 id="prefect_databricks.models.jobs.PermissionLevel" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21758,7 +21759,7 @@ <h2 id="prefect_databricks.models.jobs.PermissionLevelForGroup" class="doc doc-h
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21824,7 +21825,7 @@ <h2 id="prefect_databricks.models.jobs.PipelineParams" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21890,7 +21891,7 @@ <h2 id="prefect_databricks.models.jobs.PipelineTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -21972,7 +21973,7 @@ <h2 id="prefect_databricks.models.jobs.PoolClusterTerminationCode" class="doc do
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="k">*</span> INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.
+        <div class="codehilite"><pre><span></span><code><span class="k">*</span> INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.
 </code></pre></div>
 
 <ul>
@@ -22035,7 +22036,7 @@ <h2 id="prefect_databricks.models.jobs.PythonPyPiLibrary" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22129,7 +22130,7 @@ <h2 id="prefect_databricks.models.jobs.PythonWheelTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22245,7 +22246,7 @@ <h2 id="prefect_databricks.models.jobs.RCranLibrary" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22331,7 +22332,7 @@ <h2 id="prefect_databricks.models.jobs.RepairHistory" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22397,7 +22398,7 @@ <h2 id="prefect_databricks.models.jobs.RepairHistoryItem" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22515,7 +22516,7 @@ <h2 id="prefect_databricks.models.jobs.RepairRunInput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -22631,7 +22632,7 @@ <h2 id="prefect_databricks.models.jobs.ResizeCause" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`AUTOSCALE`</span><span class="o">:</span><span class="w"> </span><span class="n">Automatically</span><span class="w"> </span><span class="n">resized</span><span class="w"> </span><span class="n">based</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="k">load</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`AUTOSCALE`</span><span class="o">:</span><span class="w"> </span><span class="n">Automatically</span><span class="w"> </span><span class="n">resized</span><span class="w"> </span><span class="n">based</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="k">load</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -22699,7 +22700,7 @@ <h2 id="prefect_databricks.models.jobs.Run" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -23321,7 +23322,7 @@ <h2 id="prefect_databricks.models.jobs.RunLifeCycleState" class="doc doc-heading
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PENDING`</span><span class="o">:</span><span class="w"> </span><span class="n">The</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">been</span><span class="w"> </span><span class="n">triggered</span><span class="p">.</span><span class="w"> </span><span class="k">If</span><span class="w"> </span><span class="n">there</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="k">not</span><span class="w"> </span><span class="n">already</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="k">active</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">same</span><span class="w"> </span><span class="n">job</span><span class="p">,</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="n">execution</span><span class="w"> </span><span class="k">context</span><span class="w"> </span><span class="n">are</span><span class="w"> </span><span class="n">being</span><span class="w"> </span><span class="n">prepared</span><span class="p">.</span><span class="w"> </span><span class="k">If</span><span class="w"> </span><span class="n">there</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="n">already</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="k">active</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">same</span><span class="w"> </span><span class="n">job</span><span class="p">,</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">immediately</span><span class="w"> </span><span class="n">transitions</span><span class="w"> </span><span class="k">into</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n n-Quoted">`SKIPPED`</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k">without</span><span class="w"> </span><span class="n">preparing</span><span class="w"> </span><span class="k">any</span><span class="w"> </span><span class="n">resources</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PENDING`</span><span class="o">:</span><span class="w"> </span><span class="n">The</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">has</span><span class="w"> </span><span class="n">been</span><span class="w"> </span><span class="n">triggered</span><span class="p">.</span><span class="w"> </span><span class="k">If</span><span class="w"> </span><span class="n">there</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="k">not</span><span class="w"> </span><span class="n">already</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="k">active</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">same</span><span class="w"> </span><span class="n">job</span><span class="p">,</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="n">execution</span><span class="w"> </span><span class="k">context</span><span class="w"> </span><span class="n">are</span><span class="w"> </span><span class="n">being</span><span class="w"> </span><span class="n">prepared</span><span class="p">.</span><span class="w"> </span><span class="k">If</span><span class="w"> </span><span class="n">there</span><span class="w"> </span><span class="k">is</span><span class="w"> </span><span class="n">already</span><span class="w"> </span><span class="n">an</span><span class="w"> </span><span class="k">active</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">same</span><span class="w"> </span><span class="n">job</span><span class="p">,</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">immediately</span><span class="w"> </span><span class="n">transitions</span><span class="w"> </span><span class="k">into</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n n-Quoted">`SKIPPED`</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="k">without</span><span class="w"> </span><span class="n">preparing</span><span class="w"> </span><span class="k">any</span><span class="w"> </span><span class="n">resources</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -23414,7 +23415,7 @@ <h2 id="prefect_databricks.models.jobs.RunNowInput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -23510,7 +23511,7 @@ <h2 id="prefect_databricks.models.jobs.RunParameters" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -23766,7 +23767,7 @@ <h2 id="prefect_databricks.models.jobs.RunResultState" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`SUCCESS`</span><span class="o">:</span><span class="w"> </span><span class="n">The</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="n">completed</span><span class="w"> </span><span class="n">successfully</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`SUCCESS`</span><span class="o">:</span><span class="w"> </span><span class="n">The</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="n">completed</span><span class="w"> </span><span class="n">successfully</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -23839,7 +23840,7 @@ <h2 id="prefect_databricks.models.jobs.RunState" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>The result and lifecycle state of the run.</p>
 
               <details class="quote">
@@ -23952,7 +23953,7 @@ <h2 id="prefect_databricks.models.jobs.RunSubmitSettings" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -24212,7 +24213,7 @@ <h2 id="prefect_databricks.models.jobs.RunSubmitTaskSettings" class="doc doc-hea
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -24438,7 +24439,7 @@ <h2 id="prefect_databricks.models.jobs.RunTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -24818,7 +24819,7 @@ <h2 id="prefect_databricks.models.jobs.RunType" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="nx">The</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="nx">of</span><span class="w"> </span><span class="nx">the</span><span class="w"> </span><span class="nx">run</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="nx">The</span><span class="w"> </span><span class="k">type</span><span class="w"> </span><span class="nx">of</span><span class="w"> </span><span class="nx">the</span><span class="w"> </span><span class="nx">run</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -24889,7 +24890,7 @@ <h2 id="prefect_databricks.models.jobs.S3StorageInfo" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25053,7 +25054,7 @@ <h2 id="prefect_databricks.models.jobs.ServicePrincipalName" class="doc doc-head
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25123,7 +25124,7 @@ <h2 id="prefect_databricks.models.jobs.SparkConfPair" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>An arbitrary object where the object key is a configuration property name and the value is a configuration property value.</p>
 
               <details class="quote">
@@ -25188,7 +25189,7 @@ <h2 id="prefect_databricks.models.jobs.SparkEnvPair" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <p>An arbitrary object where the object key is an environment variable name and the value is an environment variable value.</p>
 
               <details class="quote">
@@ -25253,7 +25254,7 @@ <h2 id="prefect_databricks.models.jobs.SparkJarTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25369,7 +25370,7 @@ <h2 id="prefect_databricks.models.jobs.SparkNode" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25499,7 +25500,7 @@ <h2 id="prefect_databricks.models.jobs.SparkNodeAwsAttributes" class="doc doc-he
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25565,7 +25566,7 @@ <h2 id="prefect_databricks.models.jobs.SparkPythonTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25663,7 +25664,7 @@ <h2 id="prefect_databricks.models.jobs.SparkSubmitTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25751,7 +25752,7 @@ <h2 id="prefect_databricks.models.jobs.SparkVersion" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25847,7 +25848,7 @@ <h2 id="prefect_databricks.models.jobs.SqlAlertOutput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -25939,7 +25940,7 @@ <h2 id="prefect_databricks.models.jobs.SqlDashboardOutput" class="doc doc-headin
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26011,7 +26012,7 @@ <h2 id="prefect_databricks.models.jobs.SqlDashboardWidgetOutput" class="doc doc-
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26125,7 +26126,7 @@ <h2 id="prefect_databricks.models.jobs.SqlOutput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26203,7 +26204,7 @@ <h2 id="prefect_databricks.models.jobs.SqlOutputError" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26269,7 +26270,7 @@ <h2 id="prefect_databricks.models.jobs.SqlQueryOutput" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26361,7 +26362,7 @@ <h2 id="prefect_databricks.models.jobs.SqlStatementOutput" class="doc doc-headin
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26427,7 +26428,7 @@ <h2 id="prefect_databricks.models.jobs.SqlTask" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26541,7 +26542,7 @@ <h2 id="prefect_databricks.models.jobs.SqlTaskAlert" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26603,7 +26604,7 @@ <h2 id="prefect_databricks.models.jobs.SqlTaskDashboard" class="doc doc-heading"
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26669,7 +26670,7 @@ <h2 id="prefect_databricks.models.jobs.SqlTaskQuery" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26731,7 +26732,7 @@ <h2 id="prefect_databricks.models.jobs.TaskDependencies" class="doc doc-heading"
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 <div class="codehilite"><pre><span></span><code>An optional array of objects specifying the dependency graph of the task. All tasks specified in this field must complete successfully before executing this task.
 </code></pre></div>
 
@@ -26826,7 +26827,7 @@ <h2 id="prefect_databricks.models.jobs.TaskDependency" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26888,7 +26889,7 @@ <h2 id="prefect_databricks.models.jobs.TaskDescription" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -26964,7 +26965,7 @@ <h2 id="prefect_databricks.models.jobs.TaskKey" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -27050,7 +27051,7 @@ <h2 id="prefect_databricks.models.jobs.TerminationCode" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n">USER_REQUEST</span><span class="o">:</span><span class="w"> </span><span class="n">A</span><span class="w"> </span><span class="k">user</span><span class="w"> </span><span class="k">terminated</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="n">directly</span><span class="p">.</span><span class="w"> </span><span class="n">Parameters</span><span class="w"> </span><span class="n">should</span><span class="w"> </span><span class="n">include</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n n-Quoted">`username`</span><span class="w"> </span><span class="n">field</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">indicates</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="k">specific</span><span class="w"> </span><span class="k">user</span><span class="w"> </span><span class="n">who</span><span class="w"> </span><span class="k">terminated</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n">USER_REQUEST</span><span class="o">:</span><span class="w"> </span><span class="n">A</span><span class="w"> </span><span class="k">user</span><span class="w"> </span><span class="k">terminated</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="w"> </span><span class="n">directly</span><span class="p">.</span><span class="w"> </span><span class="n">Parameters</span><span class="w"> </span><span class="n">should</span><span class="w"> </span><span class="n">include</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n n-Quoted">`username`</span><span class="w"> </span><span class="n">field</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">indicates</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="k">specific</span><span class="w"> </span><span class="k">user</span><span class="w"> </span><span class="n">who</span><span class="w"> </span><span class="k">terminated</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">cluster</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -27208,7 +27209,7 @@ <h2 id="prefect_databricks.models.jobs.TerminationParameter" class="doc doc-head
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -27452,7 +27453,7 @@ <h2 id="prefect_databricks.models.jobs.TerminationReason" class="doc doc-heading
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -27538,7 +27539,7 @@ <h2 id="prefect_databricks.models.jobs.TerminationType" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="k">*</span> SUCCESS: Termination succeeded.
+        <div class="codehilite"><pre><span></span><code><span class="k">*</span> SUCCESS: Termination succeeded.
 </code></pre></div>
 
 <ul>
@@ -27613,7 +27614,7 @@ <h2 id="prefect_databricks.models.jobs.TriggerType" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PERIODIC`</span><span class="o">:</span><span class="w"> </span><span class="n">Schedules</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">periodically</span><span class="w"> </span><span class="k">trigger</span><span class="w"> </span><span class="n">runs</span><span class="p">,</span><span class="w"> </span><span class="n">such</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">cron</span><span class="w"> </span><span class="n">scheduler</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`PERIODIC`</span><span class="o">:</span><span class="w"> </span><span class="n">Schedules</span><span class="w"> </span><span class="n">that</span><span class="w"> </span><span class="n">periodically</span><span class="w"> </span><span class="k">trigger</span><span class="w"> </span><span class="n">runs</span><span class="p">,</span><span class="w"> </span><span class="n">such</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">cron</span><span class="w"> </span><span class="n">scheduler</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -27681,7 +27682,7 @@ <h2 id="prefect_databricks.models.jobs.UserName" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -27747,7 +27748,7 @@ <h2 id="prefect_databricks.models.jobs.ViewItem" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
@@ -27827,7 +27828,7 @@ <h2 id="prefect_databricks.models.jobs.ViewType" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`NOTEBOOK`</span><span class="o">:</span><span class="w"> </span><span class="n">Notebook</span><span class="w"> </span><span class="k">view</span><span class="w"> </span><span class="n">item</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`NOTEBOOK`</span><span class="o">:</span><span class="w"> </span><span class="n">Notebook</span><span class="w"> </span><span class="k">view</span><span class="w"> </span><span class="n">item</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -27890,7 +27891,7 @@ <h2 id="prefect_databricks.models.jobs.ViewsToExport" class="doc doc-heading">
               Bases: <code>str</code>, <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`CODE`</span><span class="o">:</span><span class="w"> </span><span class="k">Code</span><span class="w"> </span><span class="k">view</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">notebook</span><span class="p">.</span>
+        <div class="codehilite"><pre><span></span><code><span class="o">*</span><span class="w"> </span><span class="n n-Quoted">`CODE`</span><span class="o">:</span><span class="w"> </span><span class="k">Code</span><span class="w"> </span><span class="k">view</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">notebook</span><span class="p">.</span>
 </code></pre></div>
 
 <ul>
@@ -27958,7 +27959,7 @@ <h2 id="prefect_databricks.models.jobs.WebhookNotifications" class="doc doc-head
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>See source code for the fields' description.</p>
+        <p>See source code for the fields' description.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/models/jobs.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-databricks/rest/index.html b/versions/unreleased/integrations/prefect-databricks/rest/index.html
index fb91ecf64b..aa0a80cc9a 100644
--- a/versions/unreleased/integrations/prefect-databricks/rest/index.html
+++ b/versions/unreleased/integrations/prefect-databricks/rest/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h1 id="prefect_databricks.rest" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing generic REST tasks.</p>
+        <p>This is a module containing generic REST tasks.</p>
 
 
 
@@ -13317,7 +13318,7 @@ <h2 id="prefect_databricks.rest.HTTPMethod" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Available HTTP request methods.</p>
+        <p>Available HTTP request methods.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_databricks/rest.py</code></summary>
@@ -13379,7 +13380,7 @@ <h2 id="prefect_databricks.rest.execute_endpoint" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generic function for executing REST endpoints.</p>
+        <p>Generic function for executing REST endpoints.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13670,7 +13671,7 @@ <h2 id="prefect_databricks.rest.serialize_model" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Recursively serializes <code>pydantic.BaseModel</code> into JSON;
+        <p>Recursively serializes <code>pydantic.BaseModel</code> into JSON;
 returns original obj if not a <code>BaseModel</code>.</p>
 
 
@@ -13785,7 +13786,7 @@ <h2 id="prefect_databricks.rest.strip_kwargs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Recursively drops keyword arguments if value is None,
+        <p>Recursively drops keyword arguments if value is None,
 and serializes any <code>pydantic.BaseModel</code> types.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/commands/index.html b/versions/unreleased/integrations/prefect-dbt/cli/commands/index.html
index f6a132d9e3..6fcd3ba683 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/commands/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/commands/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13395,7 +13396,7 @@ <h1 id="prefect_dbt.cli.commands" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing tasks and flows for interacting with dbt CLI</p>
+        <p>Module containing tasks and flows for interacting with dbt CLI</p>
 
 
 
@@ -13424,7 +13425,7 @@ <h2 id="prefect_dbt.cli.commands.DbtCoreOperation" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_shell.commands.ShellOperation" href="../../../prefect-shell/commands/#prefect_shell.commands.ShellOperation">ShellOperation</a></code></p>
 
 
-      <p>A block representing a dbt operation, containing multiple dbt and shell commands.</p>
+        <p>A block representing a dbt operation, containing multiple dbt and shell commands.</p>
 <p>For long-lasting operations, use the trigger method and utilize the block as a
 context manager for automatic closure of processes when context is exited.
 If not, manually call the close method to close processes.</p>
@@ -14013,7 +14014,7 @@ <h2 id="prefect_dbt.cli.commands.create_summary_markdown" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Creates a Prefect task artifact summarizing the results
+        <p>Creates a Prefect task artifact summarizing the results
 of the above predefined prefrect-dbt task.</p>
 
             <details class="quote">
@@ -14086,7 +14087,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_build" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes the 'dbt build' command within a Prefect task,
+        <p>Executes the 'dbt build' command within a Prefect task,
 and optionally creates a Prefect artifact summarizing the dbt build results.</p>
 
 
@@ -14225,7 +14226,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_build" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
     <span class="kn">from</span> <span class="nn">prefect_dbt.cli.tasks</span> <span class="kn">import</span> <span class="n">dbt_build_task</span>
 
     <span class="nd">@flow</span>
@@ -14431,7 +14432,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_model" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes the 'dbt run' command within a Prefect task,
+        <p>Executes the 'dbt run' command within a Prefect task,
 and optionally creates a Prefect artifact summarizing the dbt build results.</p>
 
 
@@ -14570,7 +14571,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_model" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
     <span class="kn">from</span> <span class="nn">prefect_dbt.cli.tasks</span> <span class="kn">import</span> <span class="n">dbt_run_task</span>
 
     <span class="nd">@flow</span>
@@ -14778,7 +14779,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_seed" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes the 'dbt seed' command within a Prefect task,
+        <p>Executes the 'dbt seed' command within a Prefect task,
 and optionally creates a Prefect artifact summarizing the dbt build results.</p>
 
 
@@ -14917,7 +14918,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_seed" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
     <span class="kn">from</span> <span class="nn">prefect_dbt.cli.tasks</span> <span class="kn">import</span> <span class="n">dbt_seed_task</span>
 
     <span class="nd">@flow</span>
@@ -15125,7 +15126,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_snapshot" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes the 'dbt snapshot' command within a Prefect task,
+        <p>Executes the 'dbt snapshot' command within a Prefect task,
 and optionally creates a Prefect artifact summarizing the dbt build results.</p>
 
 
@@ -15264,7 +15265,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_snapshot" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
     <span class="kn">from</span> <span class="nn">prefect_dbt.cli.tasks</span> <span class="kn">import</span> <span class="n">dbt_snapshot_task</span>
 
     <span class="nd">@flow</span>
@@ -15472,7 +15473,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_test" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes the 'dbt test' command within a Prefect task,
+        <p>Executes the 'dbt test' command within a Prefect task,
 and optionally creates a Prefect artifact summarizing the dbt build results.</p>
 
 
@@ -15611,7 +15612,7 @@ <h2 id="prefect_dbt.cli.commands.run_dbt_test" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
     <span class="kn">from</span> <span class="nn">prefect_dbt.cli.tasks</span> <span class="kn">import</span> <span class="n">dbt_test_task</span>
 
     <span class="nd">@flow</span>
@@ -15819,7 +15820,7 @@ <h2 id="prefect_dbt.cli.commands.trigger_dbt_cli_command" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Task for running dbt commands.</p>
+        <p>Task for running dbt commands.</p>
 <p>If no profiles.yml file is found or if overwrite_profiles flag is set to True, this
 will first generate a profiles.yml file in the profiles_dir directory. Then run the dbt
 CLI shell command.</p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/configs/base/index.html b/versions/unreleased/integrations/prefect-dbt/cli/configs/base/index.html
index b02113ba47..fbd16c01c3 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/configs/base/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/configs/base/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13338,7 +13339,7 @@ <h1 id="prefect_dbt.cli.configs.base" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing models for base configs</p>
+        <p>Module containing models for base configs</p>
 
 
 
@@ -13367,7 +13368,7 @@ <h2 id="prefect_dbt.cli.configs.base.DbtConfigs" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code>, <code><span title="abc.ABC">ABC</span></code></p>
 
 
-      <p>Abstract class for other dbt Configs.</p>
+        <p>Abstract class for other dbt Configs.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13608,7 +13609,7 @@ <h3 id="prefect_dbt.cli.configs.base.DbtConfigs.get_configs" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Returns the dbt configs, likely used eventually for writing to profiles.yml.</p>
+        <p>Returns the dbt configs, likely used eventually for writing to profiles.yml.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13680,7 +13681,7 @@ <h2 id="prefect_dbt.cli.configs.base.GlobalConfigs" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_dbt.cli.configs.base.DbtConfigs" href="#prefect_dbt.cli.configs.base.DbtConfigs">DbtConfigs</a></code></p>
 
 
-      <p>Global configs control things like the visual output
+        <p>Global configs control things like the visual output
 of logs, the manner in which dbt parses your project,
 and what to do when dbt finds a version mismatch
 or a failing model. Docs can be found <a href="https://docs.getdbt.com/reference/global-configs">here</a>.</p>
@@ -14102,7 +14103,7 @@ <h2 id="prefect_dbt.cli.configs.base.TargetConfigs" class="doc doc-heading">
               Bases: <code><span title="prefect_dbt.cli.configs.base.BaseTargetConfigs">BaseTargetConfigs</span></code></p>
 
 
-      <p>Target configs contain credentials and
+        <p>Target configs contain credentials and
 settings, specific to the warehouse you're connecting to.
 To find valid keys, head to the <a href="https://docs.getdbt.com/docs/available-adapters">Available adapters</a> page and
 click the desired adapter's "Profile Setup" hyperlink.</p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/configs/bigquery/index.html b/versions/unreleased/integrations/prefect-dbt/cli/configs/bigquery/index.html
index 1d00ffe5a2..193c5a9864 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/configs/bigquery/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/configs/bigquery/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13294,7 +13295,7 @@ <h1 id="prefect_dbt.cli.configs.bigquery" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing models for BigQuery configs</p>
+        <p>Module containing models for BigQuery configs</p>
 
 
 
@@ -13323,7 +13324,7 @@ <h2 id="prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs" class="doc doc-h
               Bases: <code><span title="prefect_dbt.cli.configs.base.BaseTargetConfigs">BaseTargetConfigs</span></code></p>
 
 
-      <p>Target configs contain credentials and
+        <p>Target configs contain credentials and
 settings, specific to BigQuery.
 To find valid keys, head to the <a href="https://docs.getdbt.com/reference/warehouse-profiles/bigquery-profile">BigQuery Profile</a>
 page.</p>
@@ -13656,7 +13657,7 @@ <h3 id="prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs.get_configs" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns the dbt configs specific to BigQuery profile.</p>
+        <p>Returns the dbt configs specific to BigQuery profile.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/configs/postgres/index.html b/versions/unreleased/integrations/prefect-dbt/cli/configs/postgres/index.html
index 20bd090764..3e4e08eff0 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/configs/postgres/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/configs/postgres/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13294,7 +13295,7 @@ <h1 id="prefect_dbt.cli.configs.postgres" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing models for Postgres configs</p>
+        <p>Module containing models for Postgres configs</p>
 
 
 
@@ -13323,7 +13324,7 @@ <h2 id="prefect_dbt.cli.configs.postgres.PostgresTargetConfigs" class="doc doc-h
               Bases: <code><span title="prefect_dbt.cli.configs.base.BaseTargetConfigs">BaseTargetConfigs</span></code></p>
 
 
-      <p>Target configs contain credentials and
+        <p>Target configs contain credentials and
 settings, specific to Postgres.
 To find valid keys, head to the <a href="https://docs.getdbt.com/reference/warehouse-profiles/postgres-profile">Postgres Profile</a>
 page.</p>
@@ -13610,7 +13611,7 @@ <h3 id="prefect_dbt.cli.configs.postgres.PostgresTargetConfigs.get_configs" clas
 
     <div class="doc doc-contents ">
 
-      <p>Returns the dbt configs specific to Postgres profile.</p>
+        <p>Returns the dbt configs specific to Postgres profile.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/configs/snowflake/index.html b/versions/unreleased/integrations/prefect-dbt/cli/configs/snowflake/index.html
index 440c8f82e2..92fe368fc3 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/configs/snowflake/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/configs/snowflake/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13294,7 +13295,7 @@ <h1 id="prefect_dbt.cli.configs.snowflake" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing models for Snowflake configs</p>
+        <p>Module containing models for Snowflake configs</p>
 
 
 
@@ -13323,7 +13324,7 @@ <h2 id="prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs" class="doc doc
               Bases: <code><span title="prefect_dbt.cli.configs.base.BaseTargetConfigs">BaseTargetConfigs</span></code></p>
 
 
-      <p>Target configs contain credentials and
+        <p>Target configs contain credentials and
 settings, specific to Snowflake.
 To find valid keys, head to the <a href="https://docs.getdbt.com/reference/warehouse-profiles/snowflake-profile">Snowflake Profile</a>
 page.</p>
@@ -13626,7 +13627,7 @@ <h3 id="prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs.get_configs" cl
 
     <div class="doc doc-contents ">
 
-      <p>Returns the dbt configs specific to Snowflake profile.</p>
+        <p>Returns the dbt configs specific to Snowflake profile.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cli/credentials/index.html b/versions/unreleased/integrations/prefect-dbt/cli/credentials/index.html
index 9ff9458bed..435fdc21d8 100644
--- a/versions/unreleased/integrations/prefect-dbt/cli/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cli/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13275,7 +13276,7 @@ <h1 id="prefect_dbt.cli.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing credentials for interacting with dbt CLI</p>
+        <p>Module containing credentials for interacting with dbt CLI</p>
 
 
 
@@ -13304,7 +13305,7 @@ <h2 id="prefect_dbt.cli.credentials.DbtCliProfile" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Profile for use across dbt CLI tasks and flows.</p>
+        <p>Profile for use across dbt CLI tasks and flows.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13715,7 +13716,7 @@ <h3 id="prefect_dbt.cli.credentials.DbtCliProfile.get_profile" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns the dbt profile, likely used for writing to profiles.yml.</p>
+        <p>Returns the dbt profile, likely used for writing to profiles.yml.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/clients/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/clients/index.html
index 0bfdba91dc..504a8273f6 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/clients/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/clients/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13441,7 +13442,7 @@ <h1 id="prefect_dbt.cloud.clients" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing clients for interacting with the dbt Cloud API</p>
+        <p>Module containing clients for interacting with the dbt Cloud API</p>
 
 
 
@@ -13468,7 +13469,7 @@ <h2 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient" class="doc doc-h
     <div class="doc doc-contents ">
 
 
-      <p>Client for interacting with the dbt cloud Administrative API.</p>
+        <p>Client for interacting with the dbt cloud Administrative API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13920,7 +13921,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.call_endpoint" cl
 
     <div class="doc doc-contents ">
 
-      <p>Call an endpoint in the dbt Cloud API.</p>
+        <p>Call an endpoint in the dbt Cloud API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14093,7 +14094,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_job" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Return job details for a job on an account.</p>
+        <p>Return job details for a job on an account.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14221,7 +14222,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById">get run endpoint</a>
+        <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById">get run endpoint</a>
 to get details about a job run.</p>
 
 
@@ -14365,7 +14366,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run_artifact"
 
     <div class="doc doc-contents ">
 
-      <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId">get run artifact endpoint</a>
+        <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId">get run artifact endpoint</a>
 to fetch an artifact generated for a completed run.</p>
 
 
@@ -14520,7 +14521,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.list_run_artifact
 
     <div class="doc doc-contents ">
 
-      <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId">list run artifacts endpoint</a>
+        <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId">list run artifacts endpoint</a>
 to fetch a list of paths of artifacts generated for a completed run.</p>
 
 
@@ -14656,7 +14657,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.trigger_job_run"
 
     <div class="doc doc-contents ">
 
-      <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun">trigger job run endpoint</a>
+        <p>Sends a request to the <a href="https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun">trigger job run endpoint</a>
 to initiate a job run.</p>
 
 
@@ -14798,7 +14799,7 @@ <h2 id="prefect_dbt.cloud.clients.DbtCloudMetadataClient" class="doc doc-heading
     <div class="doc doc-contents ">
 
 
-      <p>Client for interacting with the dbt cloud Administrative API.</p>
+        <p>Client for interacting with the dbt cloud Administrative API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14952,7 +14953,7 @@ <h3 id="prefect_dbt.cloud.clients.DbtCloudMetadataClient.query" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Run a GraphQL query against the dbt Cloud metadata API.</p>
+        <p>Run a GraphQL query against the dbt Cloud metadata API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/credentials/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/credentials/index.html
index c21432a0eb..85e8891f0c 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13319,7 +13320,7 @@ <h1 id="prefect_dbt.cloud.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing credentials for interacting with dbt Cloud</p>
+        <p>Module containing credentials for interacting with dbt Cloud</p>
 
 
 
@@ -13348,7 +13349,7 @@ <h2 id="prefect_dbt.cloud.credentials.DbtCloudCredentials" class="doc doc-headin
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Credentials block for credential use across dbt Cloud tasks and flows.</p>
+        <p>Credentials block for credential use across dbt Cloud tasks and flows.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13798,7 +13799,7 @@ <h3 id="prefect_dbt.cloud.credentials.DbtCloudCredentials.get_administrative_cli
 
     <div class="doc doc-contents ">
 
-      <p>Returns a newly instantiated client for working with the dbt Cloud
+        <p>Returns a newly instantiated client for working with the dbt Cloud
 administrative API.</p>
 
 
@@ -13868,7 +13869,7 @@ <h3 id="prefect_dbt.cloud.credentials.DbtCloudCredentials.get_client" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a newly instantiated client for working with the dbt Cloud API.</p>
+        <p>Returns a newly instantiated client for working with the dbt Cloud API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13975,7 +13976,7 @@ <h3 id="prefect_dbt.cloud.credentials.DbtCloudCredentials.get_metadata_client" c
 
     <div class="doc doc-contents ">
 
-      <p>Returns a newly instantiated client for working with the dbt Cloud
+        <p>Returns a newly instantiated client for working with the dbt Cloud
 metadata API.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/jobs/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/jobs/index.html
index baa01595fd..e327b70a05 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/jobs/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/jobs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13595,7 +13596,7 @@ <h1 id="prefect_dbt.cloud.jobs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing tasks and flows for interacting with dbt Cloud jobs</p>
+        <p>Module containing tasks and flows for interacting with dbt Cloud jobs</p>
 
 
 
@@ -13624,7 +13625,7 @@ <h2 id="prefect_dbt.cloud.jobs.DbtCloudJob" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobBlock">JobBlock</span></code></p>
 
 
-      <p>Block that holds the information and methods to interact with a dbt Cloud job.</p>
+        <p>Block that holds the information and methods to interact with a dbt Cloud job.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13994,7 +13995,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJob.get_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve information about a dbt Cloud job.</p>
+        <p>Retrieve information about a dbt Cloud job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14110,7 +14111,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJob.trigger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Triggers a dbt Cloud job.</p>
+        <p>Triggers a dbt Cloud job.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14236,7 +14237,7 @@ <h2 id="prefect_dbt.cloud.jobs.DbtCloudJobRun" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobRun">JobRun</span></code></p>
 
 
-      <p>Class that holds the information and methods to interact
+        <p>Class that holds the information and methods to interact
 with the resulting run of a dbt Cloud job.</p>
 
               <details class="quote">
@@ -14924,7 +14925,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.fetch_result" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Gets the results from the job run. Since the results
+        <p>Gets the results from the job run. Since the results
 may not be ready, use wait_for_completion before calling this method.</p>
 
 
@@ -15049,7 +15050,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Makes a request to the dbt Cloud API to get the run data.</p>
+        <p>Makes a request to the dbt Cloud API to get the run data.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15128,7 +15129,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run_artifacts" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Get an artifact generated for a completed run.</p>
+        <p>Get an artifact generated for a completed run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15290,7 +15291,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.get_status_code" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Makes a request to the dbt Cloud API to get the run status.</p>
+        <p>Makes a request to the dbt Cloud API to get the run status.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15359,7 +15360,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.retry_failed_steps" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Retries steps that did not complete successfully in a run.</p>
+        <p>Retries steps that did not complete successfully in a run.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15454,7 +15455,7 @@ <h3 id="prefect_dbt.cloud.jobs.DbtCloudJobRun.wait_for_completion" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Waits for the job run to reach a terminal state.</p>
+        <p>Waits for the job run to reach a terminal state.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_dbt/cloud/jobs.py</code></summary>
@@ -15511,7 +15512,7 @@ <h2 id="prefect_dbt.cloud.jobs.get_dbt_cloud_job_info" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A task to retrieve information about a dbt Cloud job.</p>
+        <p>A task to retrieve information about a dbt Cloud job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15720,7 +15721,7 @@ <h2 id="prefect_dbt.cloud.jobs.get_run_id" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task that extracts the run ID from a trigger job run API response,</p>
+        <p>Task that extracts the run ID from a trigger job run API response,</p>
 <p>This task is mainly used to maintain dependency tracking between the
 <code>trigger_dbt_cloud_job_run</code> task and downstream tasks/flows that use the run ID.</p>
 
@@ -15887,7 +15888,7 @@ <h2 id="prefect_dbt.cloud.jobs.retry_dbt_cloud_job_run_subset_and_wait_for_compl
 
     <div class="doc doc-contents ">
 
-      <p>Flow that retrys a subset of dbt Cloud job run, filtered by select statuses,
+        <p>Flow that retrys a subset of dbt Cloud job run, filtered by select statuses,
 and waits for the triggered retry to complete.</p>
 
 
@@ -16254,7 +16255,7 @@ <h2 id="prefect_dbt.cloud.jobs.run_dbt_cloud_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Flow that triggers and waits for a dbt Cloud job run, retrying a
+        <p>Flow that triggers and waits for a dbt Cloud job run, retrying a
 subset of failed nodes if necessary.</p>
 
 
@@ -16432,7 +16433,7 @@ <h2 id="prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A task to trigger a dbt Cloud job run.</p>
+        <p>A task to trigger a dbt Cloud job run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16792,7 +16793,7 @@ <h2 id="prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run_and_wait_for_completion
 
     <div class="doc doc-contents ">
 
-      <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
+        <p>Flow that triggers a job run and waits for the triggered run to complete.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/models/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/models/index.html
index 9541061d20..a92f4d1240 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/models/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/models/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13263,7 +13264,7 @@ <h1 id="prefect_dbt.cloud.models" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing models used for passing data to dbt Cloud</p>
+        <p>Module containing models used for passing data to dbt Cloud</p>
 
 
 
@@ -13292,7 +13293,7 @@ <h2 id="prefect_dbt.cloud.models.TriggerJobRunOptions" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Defines options that can be defined when triggering a dbt Cloud job run.</p>
+        <p>Defines options that can be defined when triggering a dbt Cloud job run.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_dbt/cloud/models.py</code></summary>
@@ -13414,7 +13415,7 @@ <h2 id="prefect_dbt.cloud.models.default_cause_factory" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Factory function to populate the default cause for a job run to include information
+        <p>Factory function to populate the default cause for a job run to include information
 from the Prefect run context.</p>
 
             <details class="quote">
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/runs/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/runs/index.html
index f80d58c90d..6f961efba7 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/runs/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/runs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13363,7 +13364,7 @@ <h1 id="prefect_dbt.cloud.runs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing tasks and flows for interacting with dbt Cloud job runs</p>
+        <p>Module containing tasks and flows for interacting with dbt Cloud job runs</p>
 
 
 
@@ -13392,7 +13393,7 @@ <h2 id="prefect_dbt.cloud.runs.DbtCloudJobRunStatus" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>dbt Cloud Job statuses.</p>
+        <p>dbt Cloud Job statuses.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_dbt/cloud/runs.py</code></summary>
@@ -13459,7 +13460,7 @@ <h3 id="prefect_dbt.cloud.runs.DbtCloudJobRunStatus.is_terminal_status_code" cla
 
     <div class="doc doc-contents ">
 
-      <p>Returns True if a status code is terminal for a job run.
+        <p>Returns True if a status code is terminal for a job run.
 Returns False otherwise.</p>
 
             <details class="quote">
@@ -13507,7 +13508,7 @@ <h2 id="prefect_dbt.cloud.runs.get_dbt_cloud_run_artifact" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A task to get an artifact generated for a completed run. The requested artifact
+        <p>A task to get an artifact generated for a completed run. The requested artifact
 is saved to a file in the current working directory.</p>
 
 
@@ -13857,7 +13858,7 @@ <h2 id="prefect_dbt.cloud.runs.get_dbt_cloud_run_info" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A task to retrieve information about a dbt Cloud job run.</p>
+        <p>A task to retrieve information about a dbt Cloud job run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14097,7 +14098,7 @@ <h2 id="prefect_dbt.cloud.runs.list_dbt_cloud_run_artifacts" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>A task to list the artifact files generated for a completed run.</p>
+        <p>A task to list the artifact files generated for a completed run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14323,7 +14324,7 @@ <h2 id="prefect_dbt.cloud.runs.wait_for_dbt_cloud_job_run" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Waits for the given dbt Cloud job run to finish running.</p>
+        <p>Waits for the given dbt Cloud job run to finish running.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14452,7 +14453,7 @@ <h2 id="prefect_dbt.cloud.runs.wait_for_dbt_cloud_job_run" class="doc doc-headin
           </tr>
       </tbody>
     </table>
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect_dbt/cloud/runs.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-dbt/cloud/utils/index.html b/versions/unreleased/integrations/prefect-dbt/cloud/utils/index.html
index be7872f9da..6f583707db 100644
--- a/versions/unreleased/integrations/prefect-dbt/cloud/utils/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/cloud/utils/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13307,7 +13308,7 @@ <h1 id="prefect_dbt.cloud.utils" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for common interactions with the dbt Cloud API</p>
+        <p>Utilities for common interactions with the dbt Cloud API</p>
 
 
 
@@ -13336,7 +13337,7 @@ <h2 id="prefect_dbt.cloud.utils.DbtCloudAdministrativeApiCallFailed" class="doc
               Bases: <code>Exception</code></p>
 
 
-      <p>Raised when a call to dbt Cloud administrative API fails.</p>
+        <p>Raised when a call to dbt Cloud administrative API fails.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_dbt/cloud/utils.py</code></summary>
@@ -13366,7 +13367,7 @@ <h2 id="prefect_dbt.cloud.utils.call_dbt_cloud_administrative_api_endpoint" clas
 
     <div class="doc doc-contents ">
 
-      <p>Task that calls a specified endpoint in the dbt Cloud administrative API. Use this
+        <p>Task that calls a specified endpoint in the dbt Cloud administrative API. Use this
 task if a prebuilt one is not yet available.</p>
 
 
@@ -13758,7 +13759,7 @@ <h2 id="prefect_dbt.cloud.utils.extract_developer_message" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Extracts developer message from a error response from the dbt Cloud
+        <p>Extracts developer message from a error response from the dbt Cloud
 administrative API.</p>
 
 
@@ -13871,7 +13872,7 @@ <h2 id="prefect_dbt.cloud.utils.extract_user_message" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Extracts user message from a error response from the dbt Cloud administrative API.</p>
+        <p>Extracts user message from a error response from the dbt Cloud administrative API.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-dbt/index.html b/versions/unreleased/integrations/prefect-dbt/index.html
index 7aefc7050d..2035e037b9 100644
--- a/versions/unreleased/integrations/prefect-dbt/index.html
+++ b/versions/unreleased/integrations/prefect-dbt/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-docker/containers/index.html b/versions/unreleased/integrations/prefect-docker/containers/index.html
index c6bed30c14..5fc10baf27 100644
--- a/versions/unreleased/integrations/prefect-docker/containers/index.html
+++ b/versions/unreleased/integrations/prefect-docker/containers/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13310,7 +13311,7 @@ <h1 id="prefect_docker.containers" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with Docker Containers.</p>
+        <p>Integrations with Docker Containers.</p>
 
 
 
@@ -13339,7 +13340,7 @@ <h2 id="prefect_docker.containers.create_docker_container" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Create a container without starting it. Similar to docker create.</p>
+        <p>Create a container without starting it. Similar to docker create.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13651,7 +13652,7 @@ <h2 id="prefect_docker.containers.get_docker_container_logs" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Get logs from this container. Similar to the docker logs command.</p>
+        <p>Get logs from this container. Similar to the docker logs command.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13852,7 +13853,7 @@ <h2 id="prefect_docker.containers.remove_docker_container" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Remove this container. Similar to the docker rm command.</p>
+        <p>Remove this container. Similar to the docker rm command.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14051,7 +14052,7 @@ <h2 id="prefect_docker.containers.start_docker_container" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Start this container. Similar to the docker start command.</p>
+        <p>Start this container. Similar to the docker start command.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14250,7 +14251,7 @@ <h2 id="prefect_docker.containers.stop_docker_container" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Stops a container. Similar to the docker stop command.</p>
+        <p>Stops a container. Similar to the docker stop command.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-docker/credentials/index.html b/versions/unreleased/integrations/prefect-docker/credentials/index.html
index 6c8bfabc8b..668c8aee35 100644
--- a/versions/unreleased/integrations/prefect-docker/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-docker/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_docker.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing docker credentials.</p>
+        <p>Module containing docker credentials.</p>
 
 
 
@@ -13285,7 +13286,7 @@ <h2 id="prefect_docker.credentials.DockerRegistryCredentials" class="doc doc-hea
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage credentials for interacting with a Docker Registry.</p>
+        <p>Block used to manage credentials for interacting with a Docker Registry.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -13453,7 +13454,7 @@ <h3 id="prefect_docker.credentials.DockerRegistryCredentials.login" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Authenticates a given Docker client with the configured Docker registry.</p>
+        <p>Authenticates a given Docker client with the configured Docker registry.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-docker/deployments/steps/index.html b/versions/unreleased/integrations/prefect-docker/deployments/steps/index.html
index c5ac7bdac7..c466336ed7 100644
--- a/versions/unreleased/integrations/prefect-docker/deployments/steps/index.html
+++ b/versions/unreleased/integrations/prefect-docker/deployments/steps/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13307,7 +13308,7 @@ <h1 id="prefect_docker.deployments.steps" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect deployment steps for building and pushing Docker images.</p>
+        <p>Prefect deployment steps for building and pushing Docker images.</p>
 <p>These steps can be used in a <code>prefect.yaml</code> file to define the default
 build steps for a group of deployments, or they can be used to define
 the build step for a specific deployment.</p>
@@ -13356,7 +13357,7 @@ <h2 id="prefect_docker.deployments.steps.BuildDockerImageResult" class="doc doc-
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The result of a <code>build_docker_image</code> step.</p>
+        <p>The result of a <code>build_docker_image</code> step.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13501,7 +13502,7 @@ <h2 id="prefect_docker.deployments.steps.PushDockerImageResult" class="doc doc-h
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The result of a <code>push_docker_image</code> step.</p>
+        <p>The result of a <code>push_docker_image</code> step.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13627,7 +13628,7 @@ <h2 id="prefect_docker.deployments.steps.build_docker_image" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Builds a Docker image for a Prefect deployment.</p>
+        <p>Builds a Docker image for a Prefect deployment.</p>
 <p>Can be used within a <code>prefect.yaml</code> file to build a Docker
 image prior to creating or updating a deployment.</p>
 
@@ -14099,7 +14100,7 @@ <h2 id="prefect_docker.deployments.steps.push_docker_image" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Push a Docker image to a remote registry.</p>
+        <p>Push a Docker image to a remote registry.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-docker/host/index.html b/versions/unreleased/integrations/prefect-docker/host/index.html
index 542a4f86f4..53f6b52c1b 100644
--- a/versions/unreleased/integrations/prefect-docker/host/index.html
+++ b/versions/unreleased/integrations/prefect-docker/host/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_docker.host" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing Docker host settings.</p>
+        <p>Module containing Docker host settings.</p>
 
 
 
@@ -13285,7 +13286,7 @@ <h2 id="prefect_docker.host.DockerHost" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage settings for interacting with a Docker host.</p>
+        <p>Block used to manage settings for interacting with a Docker host.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13576,7 +13577,7 @@ <h3 id="prefect_docker.host.DockerHost.get_client" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Gets a Docker Client to communicate with a Docker host.</p>
+        <p>Gets a Docker Client to communicate with a Docker host.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-docker/images/index.html b/versions/unreleased/integrations/prefect-docker/images/index.html
index 1cd2ba467e..24d26bb881 100644
--- a/versions/unreleased/integrations/prefect-docker/images/index.html
+++ b/versions/unreleased/integrations/prefect-docker/images/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13222,7 +13223,7 @@ <h1 id="prefect_docker.images" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with Docker Images.</p>
+        <p>Integrations with Docker Images.</p>
 
 
 
@@ -13251,7 +13252,7 @@ <h2 id="prefect_docker.images.pull_docker_image" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pull an image of the given name and return it. Similar to the docker pull command.</p>
+        <p>Pull an image of the given name and return it. Similar to the docker pull command.</p>
 <p>If all_tags is set, the tag parameter is ignored and all image tags will be pulled.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-docker/index.html b/versions/unreleased/integrations/prefect-docker/index.html
index 774f1aece2..7c34b06d73 100644
--- a/versions/unreleased/integrations/prefect-docker/index.html
+++ b/versions/unreleased/integrations/prefect-docker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-docker/worker/index.html b/versions/unreleased/integrations/prefect-docker/worker/index.html
index d7415edbd7..7cef134b5f 100644
--- a/versions/unreleased/integrations/prefect-docker/worker/index.html
+++ b/versions/unreleased/integrations/prefect-docker/worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13422,7 +13423,7 @@ <h1 id="prefect_docker.worker" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the Docker worker used for executing flow runs as Docker containers.</p>
+        <p>Module containing the Docker worker used for executing flow runs as Docker containers.</p>
 <p>To start a Docker worker, run the following command:</p>
 <div class="highlight"><pre><span></span><code>prefect<span class="w"> </span>worker<span class="w"> </span>start<span class="w"> </span>--pool<span class="w"> </span><span class="s1">&#39;my-work-pool&#39;</span><span class="w"> </span>--type<span class="w"> </span>docker
 </code></pre></div>
@@ -13458,7 +13459,7 @@ <h2 id="prefect_docker.worker.DockerWorker" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>Prefect worker that executes flow runs within Docker containers.</p>
+        <p>Prefect worker that executes flow runs within Docker containers.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_docker/worker.py</code></summary>
@@ -14329,7 +14330,7 @@ <h3 id="prefect_docker.worker.DockerWorker.kill_infrastructure" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Stops a container for a cancelled flow run based on the provided infrastructure
+        <p>Stops a container for a cancelled flow run based on the provided infrastructure
 PID.</p>
 
             <details class="quote">
@@ -14418,7 +14419,7 @@ <h3 id="prefect_docker.worker.DockerWorker.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a flow run within a Docker container and waits for the flow run
+        <p>Executes a flow run within a Docker container and waits for the flow run
 to complete.</p>
 
             <details class="quote">
@@ -14514,7 +14515,7 @@ <h2 id="prefect_docker.worker.DockerWorkerJobConfiguration" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Configuration class used by the Docker worker.</p>
+        <p>Configuration class used by the Docker worker.</p>
 <p>An instance of this class is passed to the Docker worker's <code>run</code> method
 for each flow run. It contains all the information necessary to execute the
 flow run as a Docker container.</p>
@@ -15335,7 +15336,7 @@ <h3 id="prefect_docker.worker.DockerWorkerJobConfiguration.get_extra_hosts" clas
 
     <div class="doc doc-contents ">
 
-      <p>A host.docker.internal -&gt; host-gateway mapping is necessary for communicating
+        <p>A host.docker.internal -&gt; host-gateway mapping is necessary for communicating
 with the API on Linux machines. Docker Desktop on macOS will automatically
 already have this mapping.</p>
 
@@ -15423,7 +15424,7 @@ <h3 id="prefect_docker.worker.DockerWorkerJobConfiguration.get_network_mode" cla
 
     <div class="doc doc-contents ">
 
-      <p>Returns the network mode to use for the container based on the configured
+        <p>Returns the network mode to use for the container based on the configured
 options and the platform.</p>
 
             <details class="quote">
@@ -15526,7 +15527,7 @@ <h3 id="prefect_docker.worker.DockerWorkerJobConfiguration.prepare_for_flow_run"
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the agent for a flow run by setting the image, labels, and name
+        <p>Prepares the agent for a flow run by setting the image, labels, and name
 attributes.</p>
 
             <details class="quote">
@@ -15594,7 +15595,7 @@ <h2 id="prefect_docker.worker.DockerWorkerResult" class="doc doc-heading">
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about a completed Docker container</p>
+        <p>Contains information about a completed Docker container</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_docker/worker.py</code></summary>
@@ -15640,7 +15641,7 @@ <h2 id="prefect_docker.worker.ImagePullPolicy" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Enum representing the image pull policy options for a Docker container.</p>
+        <p>Enum representing the image pull policy options for a Docker container.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_docker/worker.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-email/credentials/index.html b/versions/unreleased/integrations/prefect-email/credentials/index.html
index d60b70cc1f..69ab5f18a9 100644
--- a/versions/unreleased/integrations/prefect-email/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-email/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13300,7 +13301,7 @@ <h1 id="prefect_email.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes used to perform authenticated interactions with email services</p>
+        <p>Credential classes used to perform authenticated interactions with email services</p>
 
 
 
@@ -13329,7 +13330,7 @@ <h2 id="prefect_email.credentials.EmailServerCredentials" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage generic email server authentication.
+        <p>Block used to manage generic email server authentication.
 It is recommended you use a
 <a href="https://support.google.com/accounts/answer/185833">Google App Password</a>
 if you use Gmail.</p>
@@ -13691,7 +13692,7 @@ <h3 id="prefect_email.credentials.EmailServerCredentials.get_server" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated SMTP server.</p>
+        <p>Gets an authenticated SMTP server.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13860,7 +13861,7 @@ <h2 id="prefect_email.credentials.SMTPServer" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Server used to send email.</p>
+        <p>Server used to send email.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_email/credentials.py</code></summary>
@@ -13926,7 +13927,7 @@ <h2 id="prefect_email.credentials.SMTPType" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Protocols used to secure email transmissions.</p>
+        <p>Protocols used to secure email transmissions.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_email/credentials.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-email/index.html b/versions/unreleased/integrations/prefect-email/index.html
index ae20d5b307..e5b654db8c 100644
--- a/versions/unreleased/integrations/prefect-email/index.html
+++ b/versions/unreleased/integrations/prefect-email/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-email/message/index.html b/versions/unreleased/integrations/prefect-email/message/index.html
index 9bb37c5ba1..914e623f61 100644
--- a/versions/unreleased/integrations/prefect-email/message/index.html
+++ b/versions/unreleased/integrations/prefect-email/message/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13222,7 +13223,7 @@ <h1 id="prefect_email.message" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with email message services</p>
+        <p>Tasks for interacting with email message services</p>
 
 
 
@@ -13251,7 +13252,7 @@ <h2 id="prefect_email.message.email_send_message" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sends an email message from an authenticated email service over SMTP.
+        <p>Sends an email message from an authenticated email service over SMTP.
 Sending messages containing HTML code is supported - the default MIME
 type is set to the text/html.</p>
 
diff --git a/versions/unreleased/integrations/prefect-gcp/aiplatform/index.html b/versions/unreleased/integrations/prefect-gcp/aiplatform/index.html
index 276c17e0a3..5a6d3508e2 100644
--- a/versions/unreleased/integrations/prefect-gcp/aiplatform/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/aiplatform/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13388,7 +13389,7 @@ <h1 id="prefect_gcp.aiplatform" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This module is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by the Vertex AI worker, which offers enhanced functionality and better performance.</p>
 <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>
@@ -13466,7 +13467,7 @@ <h2 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob" class="doc doc-heading
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.Infrastructure" href="../../../api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This block is deprecated along with Agents and all other Infrastructure blocks.
 It will be removed in prefect v3.</p>
 <p>Infrastructure block used to run Vertex AI custom training jobs.</p>
@@ -14453,7 +14454,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.job_name" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:
+        <p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:
 https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>
     </div>
 
@@ -14476,7 +14477,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.generate_work_pool_base
 
     <div class="doc doc-contents ">
 
-      <p>Generate a base job template for a <code>Vertex AI</code> work pool with the same
+        <p>Generate a base job template for a <code>Vertex AI</code> work pool with the same
 configuration as this block.
 Returns:
     - dict: a base job template for a <code>Vertex AI</code> work pool</p>
@@ -14617,7 +14618,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.get_corresponding_worke
 
     <div class="doc doc-contents ">
 
-      <p>Return the corresponding worker type for this infrastructure block.</p>
+        <p>Return the corresponding worker type for this infrastructure block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/aiplatform.py</code></summary>
@@ -14647,7 +14648,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.kill" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Kill a job running Cloud Run.</p>
+        <p>Kill a job running Cloud Run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14766,7 +14767,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.preview" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Generate a preview of the job definition that will be sent to GCP.</p>
+        <p>Generate a preview of the job definition that will be sent to GCP.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/aiplatform.py</code></summary>
@@ -14808,7 +14809,7 @@ <h3 id="prefect_gcp.aiplatform.VertexAICustomTrainingJob.run" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Run the configured task on VertexAI.</p>
+        <p>Run the configured task on VertexAI.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14995,7 +14996,7 @@ <h2 id="prefect_gcp.aiplatform.VertexAICustomTrainingJobResult" class="doc doc-h
               Bases: <code><span title="prefect.infrastructure.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>Result from a Vertex AI custom training job.</p>
+        <p>Result from a Vertex AI custom training job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/aiplatform.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-gcp/bigquery/index.html b/versions/unreleased/integrations/prefect-gcp/bigquery/index.html
index 4380aa07f4..f7c55870bb 100644
--- a/versions/unreleased/integrations/prefect-gcp/bigquery/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/bigquery/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13520,7 +13521,7 @@ <h1 id="prefect_gcp.bigquery" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with GCP BigQuery</p>
+        <p>Tasks for interacting with GCP BigQuery</p>
 
 
 
@@ -13549,7 +13550,7 @@ <h2 id="prefect_gcp.bigquery.BigQueryWarehouse" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.DatabaseBlock">DatabaseBlock</span></code></p>
 
 
-      <p>A block for querying a database with BigQuery.</p>
+        <p>A block for querying a database with BigQuery.</p>
 <p>Upon instantiating, a connection to BigQuery is established
 and maintained for the life of the object until the close method is called.</p>
 <p>It is recommended to use this block as a context manager, which will automatically
@@ -14442,7 +14443,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.close" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Closes connection and its cursors.</p>
+        <p>Closes connection and its cursors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/bigquery.py</code></summary>
@@ -14486,7 +14487,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.execute" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes an operation on the database. This method is intended to be used
+        <p>Executes an operation on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p>
 <p>Unlike the fetch methods, this method will always execute the operation
 upon calling.</p>
@@ -14682,7 +14683,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.execute_many" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Executes many operations on the database. This method is intended to be used
+        <p>Executes many operations on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p>
 <p>Unlike the fetch methods, this method will always execute the operations
 upon calling.</p>
@@ -14879,7 +14880,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.fetch_all" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Fetch all results from the database.</p>
+        <p>Fetch all results from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -15121,7 +15122,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.fetch_many" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a limited number of results from the database.</p>
+        <p>Fetch a limited number of results from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -15404,7 +15405,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.fetch_one" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a single result from the database.</p>
+        <p>Fetch a single result from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -15648,7 +15649,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.get_connection" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Get the opened connection to BigQuery.</p>
+        <p>Get the opened connection to BigQuery.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/bigquery.py</code></summary>
@@ -15678,7 +15679,7 @@ <h3 id="prefect_gcp.bigquery.BigQueryWarehouse.reset_cursors" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Tries to close all opened cursors.</p>
+        <p>Tries to close all opened cursors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/bigquery.py</code></summary>
@@ -15737,7 +15738,7 @@ <h2 id="prefect_gcp.bigquery.bigquery_create_table" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates table in BigQuery.
+        <p>Creates table in BigQuery.
 Args:
     dataset: Name of a dataset in that the table will be created.
     table: Name of a table to create.
@@ -15981,7 +15982,7 @@ <h2 id="prefect_gcp.bigquery.bigquery_insert_stream" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Insert records in a Google BigQuery table via the <a href="https://cloud.google.com/bigquery/streaming-data-into-bigquery">streaming
+        <p>Insert records in a Google BigQuery table via the <a href="https://cloud.google.com/bigquery/streaming-data-into-bigquery">streaming
 API</a>.</p>
 
 
@@ -16303,7 +16304,7 @@ <h2 id="prefect_gcp.bigquery.bigquery_load_cloud_storage" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Run method for this Task.  Invoked by <em>calling</em> this
+        <p>Run method for this Task.  Invoked by <em>calling</em> this
 Task within a Flow context, after initialization.
 Args:
     uri: GCS path to load data from.
@@ -16556,7 +16557,7 @@ <h2 id="prefect_gcp.bigquery.bigquery_load_file" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Loads file into BigQuery.</p>
+        <p>Loads file into BigQuery.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16991,7 +16992,7 @@ <h2 id="prefect_gcp.bigquery.bigquery_query" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a BigQuery query.</p>
+        <p>Runs a BigQuery query.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gcp/cloud_run/index.html b/versions/unreleased/integrations/prefect-gcp/cloud_run/index.html
index 8840ee395a..9ea233af5b 100644
--- a/versions/unreleased/integrations/prefect-gcp/cloud_run/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/cloud_run/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13698,7 +13699,7 @@ <h1 id="prefect_gcp.cloud_run" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This module is deprecated as of March 2024 and will not be available after September 2024.
 It has been replaced by the Cloud Run and Cloud Run V2 workers, which offer enhanced functionality and better performance.</p>
 <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>
@@ -13751,7 +13752,7 @@ <h2 id="prefect_gcp.cloud_run.CloudRunJob" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.infrastructure.base.Infrastructure" href="../../../api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure">Infrastructure</a></code></p>
 
 
-      <p>DEPRECATION WARNING:</p>
+        <p>DEPRECATION WARNING:</p>
 <p>This block is deprecated along with Agents and all other Infrastructure blocks.
 It will be removed in prefect v3.</p>
 <p><span class="badge-api experimental"/></p>
@@ -15070,7 +15071,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.job_name" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a unique and valid job name.</p>
+        <p>Create a unique and valid job name.</p>
     </div>
 
 </div>
@@ -15091,7 +15092,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.memory_string" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Returns the string expected for memory resources argument.</p>
+        <p>Returns the string expected for memory resources argument.</p>
     </div>
 
 </div>
@@ -15113,7 +15114,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.generate_work_pool_base_job_template"
 
     <div class="doc doc-contents ">
 
-      <p>Generate a base job template for a cloud-run work pool with the same
+        <p>Generate a base job template for a cloud-run work pool with the same
 configuration as this block.</p>
 
 
@@ -15299,7 +15300,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.get_corresponding_worker_type" class="
 
     <div class="doc doc-contents ">
 
-      <p>Return the corresponding worker type for this infrastructure block.</p>
+        <p>Return the corresponding worker type for this infrastructure block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15329,7 +15330,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.kill" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Kill a task running Cloud Run.</p>
+        <p>Kill a task running Cloud Run.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15425,7 +15426,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.preview" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generate a preview of the job definition that will be sent to GCP.</p>
+        <p>Generate a preview of the job definition that will be sent to GCP.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15473,7 +15474,7 @@ <h3 id="prefect_gcp.cloud_run.CloudRunJob.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Run the configured job on a Google Cloud Run Job.</p>
+        <p>Run the configured job on a Google Cloud Run Job.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15548,7 +15549,7 @@ <h2 id="prefect_gcp.cloud_run.CloudRunJobResult" class="doc doc-heading">
               Bases: <code><span title="prefect.infrastructure.base.InfrastructureResult">InfrastructureResult</span></code></p>
 
 
-      <p>Result from a Cloud Run Job.</p>
+        <p>Result from a Cloud Run Job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15594,7 +15595,7 @@ <h2 id="prefect_gcp.cloud_run.Execution" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Utility class to call GCP <code>executions</code> API and
+        <p>Utility class to call GCP <code>executions</code> API and
 interact with the returned objects.</p>
 
               <details class="quote">
@@ -15724,7 +15725,7 @@ <h3 id="prefect_gcp.cloud_run.Execution.condition_after_completion" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns Execution condition if Execution has completed.</p>
+        <p>Returns Execution condition if Execution has completed.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15758,7 +15759,7 @@ <h3 id="prefect_gcp.cloud_run.Execution.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Make a get request to the GCP executions API
+        <p>Make a get request to the GCP executions API
 and return an Execution instance.</p>
 
             <details class="quote">
@@ -15817,7 +15818,7 @@ <h3 id="prefect_gcp.cloud_run.Execution.is_running" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns True if Execution is not completed.</p>
+        <p>Returns True if Execution is not completed.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15843,7 +15844,7 @@ <h3 id="prefect_gcp.cloud_run.Execution.succeeded" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether or not the Execution completed is a successful state.</p>
+        <p>Whether or not the Execution completed is a successful state.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -15890,7 +15891,7 @@ <h2 id="prefect_gcp.cloud_run.Job" class="doc doc-heading">
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Utility class to call GCP <code>jobs</code> API and
+        <p>Utility class to call GCP <code>jobs</code> API and
 interact with the returned objects.</p>
 
               <details class="quote">
@@ -16106,7 +16107,7 @@ <h3 id="prefect_gcp.cloud_run.Job.create" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Make a create request to the GCP jobs API.</p>
+        <p>Make a create request to the GCP jobs API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -16142,7 +16143,7 @@ <h3 id="prefect_gcp.cloud_run.Job.delete" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Make a delete request to the GCP jobs API.</p>
+        <p>Make a delete request to the GCP jobs API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -16178,7 +16179,7 @@ <h3 id="prefect_gcp.cloud_run.Job.get" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Make a get request to the GCP jobs API and return a Job instance.</p>
+        <p>Make a get request to the GCP jobs API and return a Job instance.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -16226,7 +16227,7 @@ <h3 id="prefect_gcp.cloud_run.Job.has_execution_in_progress" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>See if job has a run in progress.</p>
+        <p>See if job has a run in progress.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -16258,7 +16259,7 @@ <h3 id="prefect_gcp.cloud_run.Job.is_ready" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Whether a job is finished registering and ready to be executed</p>
+        <p>Whether a job is finished registering and ready to be executed</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
@@ -16292,7 +16293,7 @@ <h3 id="prefect_gcp.cloud_run.Job.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Make a run request to the GCP jobs API.</p>
+        <p>Make a run request to the GCP jobs API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/cloud_run.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-gcp/cloud_run_worker/index.html b/versions/unreleased/integrations/prefect-gcp/cloud_run_worker/index.html
index 2601a4bb2e..bc067271c3 100644
--- a/versions/unreleased/integrations/prefect-gcp/cloud_run_worker/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/cloud_run_worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13531,7 +13532,7 @@ <h1 id="prefect_gcp.workers.cloud_run" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <!-- # noqa -->
+        <!-- # noqa -->
 
 <p>Module containing the Cloud Run worker used for executing flow runs as Cloud Run jobs.</p>
 <p>Get started by creating a Cloud Run work pool:</p>
@@ -13695,7 +13696,7 @@ <h2 id="prefect_gcp.workers.cloud_run.CloudRunWorker" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>Prefect worker that executes flow runs within Cloud Run Jobs.</p>
+        <p>Prefect worker that executes flow runs within Cloud Run Jobs.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/cloud_run.py</code></summary>
@@ -14360,7 +14361,7 @@ <h3 id="prefect_gcp.workers.cloud_run.CloudRunWorker.kill_infrastructure" class=
 
     <div class="doc doc-contents ">
 
-      <p>Stops a job for a cancelled flow run based on the provided infrastructure PID
+        <p>Stops a job for a cancelled flow run based on the provided infrastructure PID
 and run configuration.</p>
 
             <details class="quote">
@@ -14433,7 +14434,7 @@ <h3 id="prefect_gcp.workers.cloud_run.CloudRunWorker.run" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Executes a flow run within a Cloud Run Job and waits for the flow run
+        <p>Executes a flow run within a Cloud Run Job and waits for the flow run
 to complete.</p>
 
 
@@ -14639,7 +14640,7 @@ <h2 id="prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration" class="doc
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Configuration class used by the Cloud Run Worker to create a Cloud Run Job.</p>
+        <p>Configuration class used by the Cloud Run Worker to create a Cloud Run Job.</p>
 <p>An instance of this class is passed to the Cloud Run worker's <code>run</code> method
 for each flow run. It contains all information necessary to execute
 the flow run as a Cloud Run Job.</p>
@@ -15105,7 +15106,7 @@ <h3 id="prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.job_name" c
 
     <div class="doc doc-contents ">
 
-      <p>property for accessing the name from the job metadata.</p>
+        <p>property for accessing the name from the job metadata.</p>
     </div>
 
 </div>
@@ -15126,7 +15127,7 @@ <h3 id="prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.project" cl
 
     <div class="doc doc-contents ">
 
-      <p>property for accessing the project from the credentials.</p>
+        <p>property for accessing the project from the credentials.</p>
     </div>
 
 </div>
@@ -15144,7 +15145,7 @@ <h3 id="prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.prepare_for
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the job configuration for a flow run.</p>
+        <p>Prepares the job configuration for a flow run.</p>
 <p>Ensures that necessary values are present in the job body and that the
 job body is valid.</p>
 
@@ -15287,7 +15288,7 @@ <h2 id="prefect_gcp.workers.cloud_run.CloudRunWorkerResult" class="doc doc-headi
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/cloud_run.py</code></summary>
@@ -15333,7 +15334,7 @@ <h2 id="prefect_gcp.workers.cloud_run.CloudRunWorkerVariables" class="doc doc-he
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Default variables for the Cloud Run worker.</p>
+        <p>Default variables for the Cloud Run worker.</p>
 <p>The schema for this class is used to populate the <code>variables</code> section of the default
 base job template.</p>
 
diff --git a/versions/unreleased/integrations/prefect-gcp/cloud_run_worker_v2/index.html b/versions/unreleased/integrations/prefect-gcp/cloud_run_worker_v2/index.html
index c4c2643530..0df72026ca 100644
--- a/versions/unreleased/integrations/prefect-gcp/cloud_run_worker_v2/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/cloud_run_worker_v2/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13468,7 +13469,7 @@ <h2 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration" class
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>The configuration for the Cloud Run worker V2.</p>
+        <p>The configuration for the Cloud Run worker V2.</p>
 <p>The schema for this class is used to populate the <code>job_body</code> section of the
 default base job template.</p>
 
@@ -13910,7 +13911,7 @@ <h3 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.job_na
 
     <div class="doc doc-contents ">
 
-      <p>Returns the name of the job.</p>
+        <p>Returns the name of the job.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13954,7 +13955,7 @@ <h3 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.projec
 
     <div class="doc doc-contents ">
 
-      <p>Returns the GCP project associated with the credentials.</p>
+        <p>Returns the GCP project associated with the credentials.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13995,7 +13996,7 @@ <h3 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.prepar
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the job configuration for a flow run.</p>
+        <p>Prepares the job configuration for a flow run.</p>
 <p>Ensures that necessary values are present in the job body and that the
 job body is valid.</p>
 
@@ -14148,7 +14149,7 @@ <h2 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2" class="doc doc-headin
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>The Cloud Run worker V2.</p>
+        <p>The Cloud Run worker V2.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code></summary>
@@ -15081,7 +15082,7 @@ <h3 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.kill_infrastructure" c
 
     <div class="doc doc-contents ">
 
-      <p>Stops the Cloud Run job.</p>
+        <p>Stops the Cloud Run job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15218,7 +15219,7 @@ <h3 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.run" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Runs the flow run on Cloud Run and waits for it to complete.</p>
+        <p>Runs the flow run on Cloud Run and waits for it to complete.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15423,7 +15424,7 @@ <h2 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Result" class="doc doc-
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>The result of a Cloud Run worker V2 job.</p>
+        <p>The result of a Cloud Run worker V2 job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code></summary>
@@ -15473,7 +15474,7 @@ <h2 id="prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Variables" class="doc d
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Default variables for the Cloud Run worker V2.</p>
+        <p>Default variables for the Cloud Run worker V2.</p>
 <p>The schema for this class is used to populate the <code>variables</code> section of the
 default base job template.</p>
 
diff --git a/versions/unreleased/integrations/prefect-gcp/cloud_storage/index.html b/versions/unreleased/integrations/prefect-gcp/cloud_storage/index.html
index e867b2b6ac..4b594d5e05 100644
--- a/versions/unreleased/integrations/prefect-gcp/cloud_storage/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/cloud_storage/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13862,7 +13863,7 @@ <h1 id="prefect_gcp.cloud_storage" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with GCP Cloud Storage.</p>
+        <p>Tasks for interacting with GCP Cloud Storage.</p>
 
 
 
@@ -13891,7 +13892,7 @@ <h2 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat" class="doc doc-h
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>An enumeration class to represent different file formats,
+        <p>An enumeration class to represent different file formats,
 compression options for upload_from_dataframe</p>
 
 
@@ -14125,7 +14126,7 @@ <h3 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat.compression" clas
 
     <div class="doc doc-contents ">
 
-      <p>The compression type of the current instance.</p>
+        <p>The compression type of the current instance.</p>
     </div>
 
 </div>
@@ -14146,7 +14147,7 @@ <h3 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat.content_type" cla
 
     <div class="doc doc-contents ">
 
-      <p>The content type of the current instance.</p>
+        <p>The content type of the current instance.</p>
     </div>
 
 </div>
@@ -14167,7 +14168,7 @@ <h3 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat.format" class="do
 
     <div class="doc doc-contents ">
 
-      <p>The file format of the current instance.</p>
+        <p>The file format of the current instance.</p>
     </div>
 
 </div>
@@ -14188,7 +14189,7 @@ <h3 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat.suffix" class="do
 
     <div class="doc doc-contents ">
 
-      <p>The suffix of the file format of the current instance.</p>
+        <p>The suffix of the file format of the current instance.</p>
     </div>
 
 </div>
@@ -14206,7 +14207,7 @@ <h3 id="prefect_gcp.cloud_storage.DataFrameSerializationFormat.fix_extension_wit
 
     <div class="doc doc-contents ">
 
-      <p>Fix the extension of a GCS blob.</p>
+        <p>Fix the extension of a GCS blob.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14317,7 +14318,7 @@ <h2 id="prefect_gcp.cloud_storage.GcsBucket" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.WritableDeploymentStorage">WritableDeploymentStorage</span></code>, <code><span title="prefect.filesystems.WritableFileSystem">WritableFileSystem</span></code>, <code><span title="prefect.blocks.abstract.ObjectStorageBlock">ObjectStorageBlock</span></code></p>
 
 
-      <p>Block used to store data using GCP Cloud Storage Buckets.</p>
+        <p>Block used to store data using GCP Cloud Storage Buckets.</p>
 <p>Note! <code>GcsBucket</code> in <code>prefect-gcp</code> is a unique block, separate from <code>GCS</code>
 in core Prefect. <code>GcsBucket</code> does not use <code>gcsfs</code> under the hood,
 instead using the <code>google-cloud-storage</code> package, and offers more configuration
@@ -15965,7 +15966,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.basepath" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read-only property that mirrors the bucket folder.</p>
+        <p>Read-only property that mirrors the bucket folder.</p>
 <p>Used for deployment.</p>
     </div>
 
@@ -15988,7 +15989,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.create_bucket" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Creates a bucket.</p>
+        <p>Creates a bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16147,7 +16148,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.download_folder_to_path" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Downloads objects <em>within</em> a folder (excluding the folder itself)
+        <p>Downloads objects <em>within</em> a folder (excluding the folder itself)
 from the object storage service to a folder.</p>
 
 
@@ -16398,7 +16399,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.download_object_to_file_object" clas
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from the object storage service to a file-like object,
+        <p>Downloads an object from the object storage service to a file-like object,
 which can be a BytesIO object or a BufferedWriter.</p>
 
 
@@ -16631,7 +16632,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.download_object_to_path" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Downloads an object from the object storage service to a path.</p>
+        <p>Downloads an object from the object storage service to a path.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16845,7 +16846,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.get_bucket" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Returns the bucket object.</p>
+        <p>Returns the bucket object.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -16943,7 +16944,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.get_directory" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Copies a folder from the configured GCS bucket to a local directory.
+        <p>Copies a folder from the configured GCS bucket to a local directory.
 Defaults to copying the entire contents of the block's bucket_folder
 to the current working directory.</p>
 
@@ -17143,7 +17144,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.list_blobs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Lists all blobs in the bucket that are in a folder.
+        <p>Lists all blobs in the bucket that are in a folder.
 Folders are not included in the output.</p>
 
 
@@ -17301,7 +17302,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.list_folders" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Lists all folders and subfolders in the bucket.</p>
+        <p>Lists all folders and subfolders in the bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17480,7 +17481,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.put_directory" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a directory from a given local path to the configured GCS bucket in a
+        <p>Uploads a directory from a given local path to the configured GCS bucket in a
 given folder.</p>
 <p>Defaults to uploading the entire contents the current working directory to the
 block's bucket_folder.</p>
@@ -17695,7 +17696,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.read_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read specified path from GCS and return contents. Provide the entire
+        <p>Read specified path from GCS and return contents. Provide the entire
 path to the key in GCS.</p>
 
 
@@ -17808,7 +17809,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.upload_from_dataframe" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Upload a Pandas DataFrame to Google Cloud Storage in various formats.</p>
+        <p>Upload a Pandas DataFrame to Google Cloud Storage in various formats.</p>
 <p>This function uploads the data in a Pandas DataFrame to Google Cloud Storage
 in a specified format, such as .csv, .csv.gz, .parquet,
 .parquet.snappy, and .parquet.gz.</p>
@@ -18044,7 +18045,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.upload_from_file_object" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object to the object storage service from a file-like object,
+        <p>Uploads an object to the object storage service from a file-like object,
 which can be a BytesIO object or a BufferedReader.</p>
 
 
@@ -18279,7 +18280,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.upload_from_folder" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Uploads files <em>within</em> a folder (excluding the folder itself)
+        <p>Uploads files <em>within</em> a folder (excluding the folder itself)
 to the object storage service folder.</p>
 
 
@@ -18513,7 +18514,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.upload_from_path" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Uploads an object from a path to the object storage service.</p>
+        <p>Uploads an object from a path to the object storage service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18719,7 +18720,7 @@ <h3 id="prefect_gcp.cloud_storage.GcsBucket.write_path" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Writes to an GCS bucket.</p>
+        <p>Writes to an GCS bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18863,7 +18864,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_copy_blob" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Copies data from one Google Cloud Storage bucket to another,
+        <p>Copies data from one Google Cloud Storage bucket to another,
 without downloading it locally.</p>
 
 
@@ -19227,7 +19228,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_create_bucket" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Creates a bucket.</p>
+        <p>Creates a bucket.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19469,7 +19470,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_download_blob_as_bytes" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a blob as bytes.</p>
+        <p>Downloads a blob as bytes.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19794,7 +19795,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_download_blob_to_file" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Downloads a blob to a file path.</p>
+        <p>Downloads a blob to a file path.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20156,7 +20157,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_file" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a blob from file path or file-like object. Usage for passing in
+        <p>Uploads a blob from file path or file-like object. Usage for passing in
 file-like object is if the data was downloaded from the web;
 can bypass writing to disk and directly upload to Cloud Storage.</p>
 
@@ -20549,7 +20550,7 @@ <h2 id="prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_string" class="
 
     <div class="doc doc-contents ">
 
-      <p>Uploads a blob from a string or bytes representation of data.</p>
+        <p>Uploads a blob from a string or bytes representation of data.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gcp/credentials/index.html b/versions/unreleased/integrations/prefect-gcp/credentials/index.html
index a188379a29..dd2f1a4efa 100644
--- a/versions/unreleased/integrations/prefect-gcp/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13410,7 +13411,7 @@ <h1 id="prefect_gcp.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module handling GCP credentials.</p>
+        <p>Module handling GCP credentials.</p>
 
 
 
@@ -13439,7 +13440,7 @@ <h2 id="prefect_gcp.credentials.GcpCredentials" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Block used to manage authentication with GCP. Google authentication is
+        <p>Block used to manage authentication with GCP. Google authentication is
 handled via the <code>google.oauth2</code> module or through the CLI.
 Specify either one of service <code>account_file</code> or <code>service_account_info</code>; if both
 are not specified, the client will try to detect the credentials following Google's
@@ -14440,7 +14441,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_access_token" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      
+        
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/credentials.py</code></summary>
@@ -14480,7 +14481,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_bigquery_client" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated BigQuery client.</p>
+        <p>Gets an authenticated BigQuery client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14734,7 +14735,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_client" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Helper method to dynamically get a client type.</p>
+        <p>Helper method to dynamically get a client type.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14892,7 +14893,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_cloud_storage_client" class="
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated Cloud Storage client.</p>
+        <p>Gets an authenticated Cloud Storage client.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15123,7 +15124,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_credentials_from_service_acco
 
     <div class="doc doc-contents ">
 
-      <p>Helper method to serialize credentials by using either
+        <p>Helper method to serialize credentials by using either
 service_account_file or service_account_info.</p>
 
             <details class="quote">
@@ -15180,7 +15181,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_job_service_async_client" cla
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated Job Service async client for Vertex AI.</p>
+        <p>Gets an authenticated Job Service async client for Vertex AI.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15379,7 +15380,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_job_service_client" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated Job Service client for Vertex AI.</p>
+        <p>Gets an authenticated Job Service client for Vertex AI.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -15576,7 +15577,7 @@ <h3 id="prefect_gcp.credentials.GcpCredentials.get_secret_manager_client" class=
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated Secret Manager Service client.</p>
+        <p>Gets an authenticated Secret Manager Service client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gcp/deployments/steps/index.html b/versions/unreleased/integrations/prefect-gcp/deployments/steps/index.html
index e399c92b73..a84eb6c091 100644
--- a/versions/unreleased/integrations/prefect-gcp/deployments/steps/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/deployments/steps/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13376,7 +13377,7 @@ <h1 id="prefect_gcp.deployments.steps" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Prefect deployment steps for code storage in and retrieval from Google Cloud Storage.</p>
+        <p>Prefect deployment steps for code storage in and retrieval from Google Cloud Storage.</p>
 
 
 
@@ -13405,7 +13406,7 @@ <h2 id="prefect_gcp.deployments.steps.PullFromGcsOutput" class="doc doc-heading"
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The output of the <code>pull_from_gcs</code> step.</p>
+        <p>The output of the <code>pull_from_gcs</code> step.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -13463,7 +13464,7 @@ <h2 id="prefect_gcp.deployments.steps.PullProjectFromGcsOutput" class="doc doc-h
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_gcp.deployments.steps.PullFromGcsOutput" href="#prefect_gcp.deployments.steps.PullFromGcsOutput">PullFromGcsOutput</a></code></p>
 
 
-      <p>Deprecated. Use <code>PullFromGcsOutput</code> instead.</p>
+        <p>Deprecated. Use <code>PullFromGcsOutput</code> instead.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -13511,7 +13512,7 @@ <h2 id="prefect_gcp.deployments.steps.PushProjectToGcsOutput" class="doc doc-hea
               Bases: <code><a class="autorefs autorefs-internal" title="prefect_gcp.deployments.steps.PushToGcsOutput" href="#prefect_gcp.deployments.steps.PushToGcsOutput">PushToGcsOutput</a></code></p>
 
 
-      <p>Deprecated. Use <code>PushToGcsOutput</code> instead.</p>
+        <p>Deprecated. Use <code>PushToGcsOutput</code> instead.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -13559,7 +13560,7 @@ <h2 id="prefect_gcp.deployments.steps.PushToGcsOutput" class="doc doc-heading">
               Bases: <code><span title="typing_extensions.TypedDict">TypedDict</span></code></p>
 
 
-      <p>The output of the <code>push_to_gcs</code> step.</p>
+        <p>The output of the <code>push_to_gcs</code> step.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -13611,7 +13612,7 @@ <h2 id="prefect_gcp.deployments.steps.pull_from_gcs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pulls the contents of a project from an GCS bucket to the current working directory.</p>
+        <p>Pulls the contents of a project from an GCS bucket to the current working directory.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13942,7 +13943,7 @@ <h2 id="prefect_gcp.deployments.steps.pull_project_from_gcs" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Deprecated. Use <code>pull_from_gcs</code> instead.</p>
+        <p>Deprecated. Use <code>pull_from_gcs</code> instead.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -13974,7 +13975,7 @@ <h2 id="prefect_gcp.deployments.steps.push_project_to_gcs" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Deprecated. Use <code>push_to_gcs</code> instead.</p>
+        <p>Deprecated. Use <code>push_to_gcs</code> instead.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_gcp/deployments/steps.py</code></summary>
@@ -14006,7 +14007,7 @@ <h2 id="prefect_gcp.deployments.steps.push_to_gcs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Pushes the contents of the current working directory to a GCS bucket,
+        <p>Pushes the contents of the current working directory to a GCS bucket,
 excluding files and folders specified in the ignore_file.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-gcp/gcp-worker-guide/index.html b/versions/unreleased/integrations/prefect-gcp/gcp-worker-guide/index.html
index 5f3657dcb8..3e2cbcc51f 100644
--- a/versions/unreleased/integrations/prefect-gcp/gcp-worker-guide/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/gcp-worker-guide/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-gcp/index.html b/versions/unreleased/integrations/prefect-gcp/index.html
index 91b0124f7e..64d2015192 100644
--- a/versions/unreleased/integrations/prefect-gcp/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-gcp/secret_manager/index.html b/versions/unreleased/integrations/prefect-gcp/secret_manager/index.html
index bbab0b2801..83f2103ce8 100644
--- a/versions/unreleased/integrations/prefect-gcp/secret_manager/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/secret_manager/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13437,7 +13438,7 @@ <h2 id="prefect_gcp.secret_manager.GcpSecret" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.SecretBlock">SecretBlock</span></code></p>
 
 
-      <p>Manages a secret in Google Cloud Platform's Secret Manager.</p>
+        <p>Manages a secret in Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13723,7 +13724,7 @@ <h3 id="prefect_gcp.secret_manager.GcpSecret.delete_secret" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Deletes the secret from the secret storage service.</p>
+        <p>Deletes the secret from the secret storage service.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13806,7 +13807,7 @@ <h3 id="prefect_gcp.secret_manager.GcpSecret.read_secret" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Reads the secret data from the secret storage service.</p>
+        <p>Reads the secret data from the secret storage service.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13893,7 +13894,7 @@ <h3 id="prefect_gcp.secret_manager.GcpSecret.write_secret" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Writes the secret data to the secret storage service; if it doesn't exist
+        <p>Writes the secret data to the secret storage service; if it doesn't exist
 it will be created.</p>
 
 
@@ -14067,7 +14068,7 @@ <h2 id="prefect_gcp.secret_manager.create_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a secret in Google Cloud Platform's Secret Manager.</p>
+        <p>Creates a secret in Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14311,7 +14312,7 @@ <h2 id="prefect_gcp.secret_manager.delete_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Deletes the specified secret from Google Cloud Platform's Secret Manager.</p>
+        <p>Deletes the specified secret from Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14539,7 +14540,7 @@ <h2 id="prefect_gcp.secret_manager.delete_secret_version" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Deletes a version of a given secret from Google Cloud Platform's Secret Manager.</p>
+        <p>Deletes a version of a given secret from Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14791,7 +14792,7 @@ <h2 id="prefect_gcp.secret_manager.read_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Reads the value of a given secret from Google Cloud Platform's Secret Manager.</p>
+        <p>Reads the value of a given secret from Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15023,7 +15024,7 @@ <h2 id="prefect_gcp.secret_manager.update_secret" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Updates a secret in Google Cloud Platform's Secret Manager.</p>
+        <p>Updates a secret in Google Cloud Platform's Secret Manager.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gcp/vertex_worker/index.html b/versions/unreleased/integrations/prefect-gcp/vertex_worker/index.html
index eff631f7a3..7d651df112 100644
--- a/versions/unreleased/integrations/prefect-gcp/vertex_worker/index.html
+++ b/versions/unreleased/integrations/prefect-gcp/vertex_worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13445,7 +13446,7 @@ <h1 id="prefect_gcp.workers.vertex" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <!-- # noqa -->
+        <!-- # noqa -->
 
 <p>Module containing the custom worker used for executing flow runs as Vertex AI Custom Jobs.</p>
 <p>Get started by creating a Cloud Run work pool:</p>
@@ -13485,7 +13486,7 @@ <h2 id="prefect_gcp.workers.vertex.VertexAIWorker" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>Prefect worker that executes flow runs within Vertex AI Jobs.</p>
+        <p>Prefect worker that executes flow runs within Vertex AI Jobs.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/vertex.py</code></summary>
@@ -14110,7 +14111,7 @@ <h3 id="prefect_gcp.workers.vertex.VertexAIWorker.kill_infrastructure" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Stops a job running in Vertex AI upon flow cancellation,
+        <p>Stops a job running in Vertex AI upon flow cancellation,
 based on the provided infrastructure PID + run configuration.</p>
 
             <details class="quote">
@@ -14193,7 +14194,7 @@ <h3 id="prefect_gcp.workers.vertex.VertexAIWorker.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a flow run within a Vertex AI Job and waits for the flow run
+        <p>Executes a flow run within a Vertex AI Job and waits for the flow run
 to complete.</p>
 
 
@@ -14465,7 +14466,7 @@ <h2 id="prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration" class="doc do
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Configuration class used by the Vertex AI Worker to create a Job.</p>
+        <p>Configuration class used by the Vertex AI Worker to create a Job.</p>
 <p>An instance of this class is passed to the Vertex AI Worker's <code>run</code> method
 for each flow run. It contains all information necessary to execute
 the flow run as a Vertex AI Job.</p>
@@ -14860,7 +14861,7 @@ <h3 id="prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.job_name" clas
 
     <div class="doc doc-contents ">
 
-      <p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:
+        <p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:
 https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>
     </div>
 
@@ -14882,7 +14883,7 @@ <h3 id="prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.project" class
 
     <div class="doc doc-contents ">
 
-      <p>property for accessing the project from the credentials.</p>
+        <p>property for accessing the project from the credentials.</p>
     </div>
 
 </div>
@@ -14913,7 +14914,7 @@ <h2 id="prefect_gcp.workers.vertex.VertexAIWorkerResult" class="doc doc-heading"
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_gcp/workers/vertex.py</code></summary>
@@ -14959,7 +14960,7 @@ <h2 id="prefect_gcp.workers.vertex.VertexAIWorkerVariables" class="doc doc-headi
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Default variables for the Vertex AI worker.</p>
+        <p>Default variables for the Vertex AI worker.</p>
 <p>The schema for this class is used to populate the <code>variables</code> section of the default
 base job template.</p>
 
diff --git a/versions/unreleased/integrations/prefect-github/credentials/index.html b/versions/unreleased/integrations/prefect-github/credentials/index.html
index 22d823a6cf..3c6e72a654 100644
--- a/versions/unreleased/integrations/prefect-github/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-github/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13278,7 +13279,7 @@ <h1 id="prefect_github.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes used to perform authenticated interactions with GitHub</p>
+        <p>Credential classes used to perform authenticated interactions with GitHub</p>
 
 
 
@@ -13307,7 +13308,7 @@ <h2 id="prefect_github.credentials.GitHubCredentials" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Block used to manage GitHub authentication.</p>
+        <p>Block used to manage GitHub authentication.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13526,7 +13527,7 @@ <h3 id="prefect_github.credentials.GitHubCredentials.get_client" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated GitHub GraphQL HTTPEndpoint client.</p>
+        <p>Gets an authenticated GitHub GraphQL HTTPEndpoint client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13631,7 +13632,7 @@ <h3 id="prefect_github.credentials.GitHubCredentials.get_endpoint" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated GitHub GraphQL HTTPEndpoint.</p>
+        <p>Gets an authenticated GitHub GraphQL HTTPEndpoint.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/graphql/index.html b/versions/unreleased/integrations/prefect-github/graphql/index.html
index 36f433f196..957f219b9a 100644
--- a/versions/unreleased/integrations/prefect-github/graphql/index.html
+++ b/versions/unreleased/integrations/prefect-github/graphql/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13222,7 +13223,7 @@ <h1 id="prefect_github.graphql" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing generic GraphQL tasks</p>
+        <p>This is a module containing generic GraphQL tasks</p>
 
 
 
@@ -13251,7 +13252,7 @@ <h2 id="prefect_github.graphql.execute_graphql" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Generic function for executing GraphQL operations.</p>
+        <p>Generic function for executing GraphQL operations.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/index.html b/versions/unreleased/integrations/prefect-github/index.html
index 2f1586fcc9..9747cc7954 100644
--- a/versions/unreleased/integrations/prefect-github/index.html
+++ b/versions/unreleased/integrations/prefect-github/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-github/mutations/index.html b/versions/unreleased/integrations/prefect-github/mutations/index.html
index 690f1d5495..7f49b9d34c 100644
--- a/versions/unreleased/integrations/prefect-github/mutations/index.html
+++ b/versions/unreleased/integrations/prefect-github/mutations/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13508,7 +13509,7 @@ <h1 id="prefect_github.mutations" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub mutation tasks</p>
 
 
@@ -13538,7 +13539,7 @@ <h2 id="prefect_github.mutations.add_comment_subject" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Adds a comment to an Issue or Pull Request.</p>
+        <p>Adds a comment to an Issue or Pull Request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13737,7 +13738,7 @@ <h2 id="prefect_github.mutations.add_pull_request_review" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Adds a review to a Pull Request.</p>
+        <p>Adds a review to a Pull Request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14016,7 +14017,7 @@ <h2 id="prefect_github.mutations.add_reaction" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Adds a reaction to a subject.</p>
+        <p>Adds a reaction to a subject.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14215,7 +14216,7 @@ <h2 id="prefect_github.mutations.add_reaction_subject" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Adds a reaction to a subject.</p>
+        <p>Adds a reaction to a subject.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14414,7 +14415,7 @@ <h2 id="prefect_github.mutations.add_star_starrable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Adds a star to a Starrable.</p>
+        <p>Adds a star to a Starrable.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14593,7 +14594,7 @@ <h2 id="prefect_github.mutations.close_issue" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Close an issue.</p>
+        <p>Close an issue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14792,7 +14793,7 @@ <h2 id="prefect_github.mutations.close_pull_request" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Close a pull request.</p>
+        <p>Close a pull request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14971,7 +14972,7 @@ <h2 id="prefect_github.mutations.create_issue" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Creates a new issue.</p>
+        <p>Creates a new issue.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15296,7 +15297,7 @@ <h2 id="prefect_github.mutations.create_pull_request" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a new pull request.</p>
+        <p>Create a new pull request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15616,7 +15617,7 @@ <h2 id="prefect_github.mutations.remove_reaction" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Removes a reaction from a subject.</p>
+        <p>Removes a reaction from a subject.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15815,7 +15816,7 @@ <h2 id="prefect_github.mutations.remove_reaction_subject" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Removes a reaction from a subject.</p>
+        <p>Removes a reaction from a subject.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16014,7 +16015,7 @@ <h2 id="prefect_github.mutations.remove_star_starrable" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Removes a star from a Starrable.</p>
+        <p>Removes a star from a Starrable.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16193,7 +16194,7 @@ <h2 id="prefect_github.mutations.request_reviews" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Set review requests on a pull request.</p>
+        <p>Set review requests on a pull request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16426,7 +16427,7 @@ <h2 id="prefect_github.mutations.request_reviews_pull_request" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Set review requests on a pull request.</p>
+        <p>Set review requests on a pull request.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/organization/index.html b/versions/unreleased/integrations/prefect-github/organization/index.html
index 7458c0126e..3f39139677 100644
--- a/versions/unreleased/integrations/prefect-github/organization/index.html
+++ b/versions/unreleased/integrations/prefect-github/organization/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14014,7 +14015,7 @@ <h1 id="prefect_github.organization" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub query_organization* tasks</p>
 
 
@@ -14044,7 +14045,7 @@ <h2 id="prefect_github.organization.query_organization" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The query root of GitHub's GraphQL interface.</p>
+        <p>The query root of GitHub's GraphQL interface.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14213,7 +14214,7 @@ <h2 id="prefect_github.organization.query_organization_audit_log" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Audit log entries of the organization.</p>
+        <p>Audit log entries of the organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14526,7 +14527,7 @@ <h2 id="prefect_github.organization.query_organization_domains" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>A list of domains owned by the organization.</p>
+        <p>A list of domains owned by the organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14859,7 +14860,7 @@ <h2 id="prefect_github.organization.query_organization_enterprise_owners" class=
 
     <div class="doc doc-contents ">
 
-      <p>A list of owners of the organization's enterprise account.</p>
+        <p>A list of owners of the organization's enterprise account.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15195,7 +15196,7 @@ <h2 id="prefect_github.organization.query_organization_interaction_ability" clas
 
     <div class="doc doc-contents ">
 
-      <p>The interaction ability settings for this organization.</p>
+        <p>The interaction ability settings for this organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15370,7 +15371,7 @@ <h2 id="prefect_github.organization.query_organization_ip_allow_list_entries" cl
 
     <div class="doc doc-contents ">
 
-      <p>The IP addresses that are allowed to access resources owned by the organization.</p>
+        <p>The IP addresses that are allowed to access resources owned by the organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15669,7 +15670,7 @@ <h2 id="prefect_github.organization.query_organization_item_showcase" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Showcases a selection of repositories and gists that the profile owner has
+        <p>Showcases a selection of repositories and gists that the profile owner has
 either curated or that have been selected automatically based on popularity.</p>
 
 
@@ -15847,7 +15848,7 @@ <h2 id="prefect_github.organization.query_organization_member_statuses" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Get the status messages members of this entity have set that are either public
+        <p>Get the status messages members of this entity have set that are either public
 or visible only to the organization.</p>
 
 
@@ -16146,7 +16147,7 @@ <h2 id="prefect_github.organization.query_organization_members_with_role" class=
 
     <div class="doc doc-contents ">
 
-      <p>A list of users who are members of this organization.</p>
+        <p>A list of users who are members of this organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16413,7 +16414,7 @@ <h2 id="prefect_github.organization.query_organization_packages" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>A list of packages under the owner.</p>
+        <p>A list of packages under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16766,7 +16767,7 @@ <h2 id="prefect_github.organization.query_organization_pending_members" class="d
 
     <div class="doc doc-contents ">
 
-      <p>A list of users who have been invited to join this organization.</p>
+        <p>A list of users who have been invited to join this organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17033,7 +17034,7 @@ <h2 id="prefect_github.organization.query_organization_pinnable_items" class="do
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner can pin to their profile.</p>
+        <p>A list of repositories and gists this profile owner can pin to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17323,7 +17324,7 @@ <h2 id="prefect_github.organization.query_organization_pinned_items" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
+        <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17610,7 +17611,7 @@ <h2 id="prefect_github.organization.query_organization_project" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Find project by number.</p>
+        <p>Find project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17811,7 +17812,7 @@ <h2 id="prefect_github.organization.query_organization_project_next" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by project (beta) number.</p>
+        <p>Find a project by project (beta) number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18012,7 +18013,7 @@ <h2 id="prefect_github.organization.query_organization_project_v2" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by number.</p>
+        <p>Find a project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18213,7 +18214,7 @@ <h2 id="prefect_github.organization.query_organization_projects" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18546,7 +18547,7 @@ <h2 id="prefect_github.organization.query_organization_projects_next" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects (beta) under the owner.</p>
+        <p>A list of projects (beta) under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18853,7 +18854,7 @@ <h2 id="prefect_github.organization.query_organization_projects_v2" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19160,7 +19161,7 @@ <h2 id="prefect_github.organization.query_organization_recent_projects" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Recent projects that this user has modified in the context of the owner.</p>
+        <p>Recent projects that this user has modified in the context of the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19427,7 +19428,7 @@ <h2 id="prefect_github.organization.query_organization_repositories" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user owns.</p>
+        <p>A list of repositories that the user owns.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19850,7 +19851,7 @@ <h2 id="prefect_github.organization.query_organization_repository" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Find Repository.</p>
+        <p>Find Repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20074,7 +20075,7 @@ <h2 id="prefect_github.organization.query_organization_repository_discussion_com
 
     <div class="doc doc-contents ">
 
-      <p>Discussion comments this user has authored.</p>
+        <p>Discussion comments this user has authored.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20393,7 +20394,7 @@ <h2 id="prefect_github.organization.query_organization_repository_discussions" c
 
     <div class="doc doc-contents ">
 
-      <p>Discussions this user has started.</p>
+        <p>Discussions this user has started.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20744,7 +20745,7 @@ <h2 id="prefect_github.organization.query_organization_repository_migrations" cl
 
     <div class="doc doc-contents ">
 
-      <p>A list of all repository migrations for this organization.</p>
+        <p>A list of all repository migrations for this organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21086,7 +21087,7 @@ <h2 id="prefect_github.organization.query_organization_saml_identity_provider" c
 
     <div class="doc doc-contents ">
 
-      <p>The Organization's SAML identity providers.</p>
+        <p>The Organization's SAML identity providers.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21261,7 +21262,7 @@ <h2 id="prefect_github.organization.query_organization_sponsoring" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>List of users and organizations this entity is sponsoring.</p>
+        <p>List of users and organizations this entity is sponsoring.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21551,7 +21552,7 @@ <h2 id="prefect_github.organization.query_organization_sponsors" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsors for this user or organization.</p>
+        <p>List of sponsors for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21867,7 +21868,7 @@ <h2 id="prefect_github.organization.query_organization_sponsors_activities" clas
 
     <div class="doc doc-contents ">
 
-      <p>Events involving this sponsorable, such as new sponsorships.</p>
+        <p>Events involving this sponsorable, such as new sponsorships.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22212,7 +22213,7 @@ <h2 id="prefect_github.organization.query_organization_sponsors_listing" class="
 
     <div class="doc doc-contents ">
 
-      <p>The GitHub Sponsors listing for this user or organization.</p>
+        <p>The GitHub Sponsors listing for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22387,7 +22388,7 @@ <h2 id="prefect_github.organization.query_organization_sponsorship_for_viewer_as
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from the viewer to this user/organization; that is, the
+        <p>The sponsorship from the viewer to this user/organization; that is, the
 sponsorship where you're the sponsor. Only returns a sponsorship if it is
 active.</p>
 
@@ -22568,7 +22569,7 @@ <h2 id="prefect_github.organization.query_organization_sponsorship_for_viewer_as
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from this user/organization to the viewer; that is, the
+        <p>The sponsorship from this user/organization to the viewer; that is, the
 sponsorship you're receiving. Only returns a sponsorship if it is active.</p>
 
 
@@ -22746,7 +22747,7 @@ <h2 id="prefect_github.organization.query_organization_sponsorship_newsletters"
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
+        <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23048,7 +23049,7 @@ <h2 id="prefect_github.organization.query_organization_sponsorships_as_maintaine
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the maintainer.</p>
+        <p>This object's sponsorships as the maintainer.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23373,7 +23374,7 @@ <h2 id="prefect_github.organization.query_organization_sponsorships_as_sponsor"
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the sponsor.</p>
+        <p>This object's sponsorships as the sponsor.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23675,7 +23676,7 @@ <h2 id="prefect_github.organization.query_organization_team" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Find an organization's team by its slug.</p>
+        <p>Find an organization's team by its slug.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23876,7 +23877,7 @@ <h2 id="prefect_github.organization.query_organization_teams" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>A list of teams in this organization.</p>
+        <p>A list of teams in this organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/repository/index.html b/versions/unreleased/integrations/prefect-github/repository/index.html
index f805a07f17..ff56ca23d9 100644
--- a/versions/unreleased/integrations/prefect-github/repository/index.html
+++ b/versions/unreleased/integrations/prefect-github/repository/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14488,7 +14489,7 @@ <h1 id="prefect_github.repository" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub query_repository* tasks and the GitHub storage block.</p>
 
 
@@ -14518,7 +14519,7 @@ <h2 id="prefect_github.repository.GitHubRepository" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.ReadableDeploymentStorage">ReadableDeploymentStorage</span></code></p>
 
 
-      <p>Interact with files stored on GitHub repositories.</p>
+        <p>Interact with files stored on GitHub repositories.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_github/repository.py</code></summary>
@@ -14797,7 +14798,7 @@ <h3 id="prefect_github.repository.GitHubRepository.get_directory" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>;
+        <p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>;
 defaults to cloning the repository reference configured on the Block to the
 present working directory.</p>
 
@@ -14960,7 +14961,7 @@ <h2 id="prefect_github.repository.query_repository" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The query root of GitHub's GraphQL interface.</p>
+        <p>The query root of GitHub's GraphQL interface.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15172,7 +15173,7 @@ <h2 id="prefect_github.repository.query_repository_assignable_users" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of users that can be assigned to issues in this repository.</p>
+        <p>A list of users that can be assigned to issues in this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15502,7 +15503,7 @@ <h2 id="prefect_github.repository.query_repository_branch_protection_rules" clas
 
     <div class="doc doc-contents ">
 
-      <p>A list of branch protection rules for this repository.</p>
+        <p>A list of branch protection rules for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15818,7 +15819,7 @@ <h2 id="prefect_github.repository.query_repository_code_of_conduct" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns the code of conduct for this repository.</p>
+        <p>Returns the code of conduct for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16036,7 +16037,7 @@ <h2 id="prefect_github.repository.query_repository_collaborators" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of collaborators associated with the repository.</p>
+        <p>A list of collaborators associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16389,7 +16390,7 @@ <h2 id="prefect_github.repository.query_repository_commit_comments" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>A list of commit comments associated with the repository.</p>
+        <p>A list of commit comments associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16699,7 +16700,7 @@ <h2 id="prefect_github.repository.query_repository_contact_links" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns a list of contact links associated to the repository.</p>
+        <p>Returns a list of contact links associated to the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16917,7 +16918,7 @@ <h2 id="prefect_github.repository.query_repository_default_branch_ref" class="do
 
     <div class="doc doc-contents ">
 
-      <p>The Ref associated with the repository's default branch.</p>
+        <p>The Ref associated with the repository's default branch.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17135,7 +17136,7 @@ <h2 id="prefect_github.repository.query_repository_deploy_keys" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>A list of deploy keys that are on this repository.</p>
+        <p>A list of deploy keys that are on this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17445,7 +17446,7 @@ <h2 id="prefect_github.repository.query_repository_deployments" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Deployments associated with the repository.</p>
+        <p>Deployments associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17804,7 +17805,7 @@ <h2 id="prefect_github.repository.query_repository_discussion" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single discussion from the current repository by number.</p>
+        <p>Returns a single discussion from the current repository by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18048,7 +18049,7 @@ <h2 id="prefect_github.repository.query_repository_discussion_categories" class=
 
     <div class="doc doc-contents ">
 
-      <p>A list of discussion categories that are available in the repository.</p>
+        <p>A list of discussion categories that are available in the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18384,7 +18385,7 @@ <h2 id="prefect_github.repository.query_repository_discussion_category" class="d
 
     <div class="doc doc-contents ">
 
-      <p>A discussion category by slug.</p>
+        <p>A discussion category by slug.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18631,7 +18632,7 @@ <h2 id="prefect_github.repository.query_repository_discussions" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>A list of discussions that have been opened in the repository.</p>
+        <p>A list of discussions that have been opened in the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18993,7 +18994,7 @@ <h2 id="prefect_github.repository.query_repository_environment" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single active environment from the current repository by name.</p>
+        <p>Returns a single active environment from the current repository by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19237,7 +19238,7 @@ <h2 id="prefect_github.repository.query_repository_environments" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>A list of environments that are in this repository.</p>
+        <p>A list of environments that are in this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19547,7 +19548,7 @@ <h2 id="prefect_github.repository.query_repository_forks" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A list of direct forked repositories.</p>
+        <p>A list of direct forked repositories.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19987,7 +19988,7 @@ <h2 id="prefect_github.repository.query_repository_funding_links" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>The funding links for this repository.</p>
+        <p>The funding links for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20205,7 +20206,7 @@ <h2 id="prefect_github.repository.query_repository_interaction_ability" class="d
 
     <div class="doc doc-contents ">
 
-      <p>The interaction ability settings for this repository.</p>
+        <p>The interaction ability settings for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20423,7 +20424,7 @@ <h2 id="prefect_github.repository.query_repository_issue" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single issue from the current repository by number.</p>
+        <p>Returns a single issue from the current repository by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20667,7 +20668,7 @@ <h2 id="prefect_github.repository.query_repository_issue_or_pull_request" class=
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single issue-like object from the current repository by number.</p>
+        <p>Returns a single issue-like object from the current repository by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20911,7 +20912,7 @@ <h2 id="prefect_github.repository.query_repository_issue_templates" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a list of issue templates associated to the repository.</p>
+        <p>Returns a list of issue templates associated to the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21129,7 +21130,7 @@ <h2 id="prefect_github.repository.query_repository_issues" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A list of issues that have been opened in the repository.</p>
+        <p>A list of issues that have been opened in the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21525,7 +21526,7 @@ <h2 id="prefect_github.repository.query_repository_label" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single label by name.</p>
+        <p>Returns a single label by name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21769,7 +21770,7 @@ <h2 id="prefect_github.repository.query_repository_labels" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A list of labels associated with the repository.</p>
+        <p>A list of labels associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22122,7 +22123,7 @@ <h2 id="prefect_github.repository.query_repository_languages" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>A list containing a breakdown of the language composition of the repository.</p>
+        <p>A list containing a breakdown of the language composition of the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22452,7 +22453,7 @@ <h2 id="prefect_github.repository.query_repository_latest_release" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Get the latest release for the repository if one exists.</p>
+        <p>Get the latest release for the repository if one exists.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22670,7 +22671,7 @@ <h2 id="prefect_github.repository.query_repository_license_info" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>The license associated with the repository.</p>
+        <p>The license associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22888,7 +22889,7 @@ <h2 id="prefect_github.repository.query_repository_mentionable_users" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of Users that can be mentioned in the context of the repository.</p>
+        <p>A list of Users that can be mentioned in the context of the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23218,7 +23219,7 @@ <h2 id="prefect_github.repository.query_repository_milestone" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single milestone from the current repository by number.</p>
+        <p>Returns a single milestone from the current repository by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23462,7 +23463,7 @@ <h2 id="prefect_github.repository.query_repository_milestones" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>A list of milestones associated with the repository.</p>
+        <p>A list of milestones associated with the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23832,7 +23833,7 @@ <h2 id="prefect_github.repository.query_repository_object" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A Git object in the repository.</p>
+        <p>A Git object in the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24096,7 +24097,7 @@ <h2 id="prefect_github.repository.query_repository_owner" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>The User owner of the repository.</p>
+        <p>The User owner of the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24314,7 +24315,7 @@ <h2 id="prefect_github.repository.query_repository_packages" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>A list of packages under the owner.</p>
+        <p>A list of packages under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24710,7 +24711,7 @@ <h2 id="prefect_github.repository.query_repository_pinned_discussions" class="do
 
     <div class="doc doc-contents ">
 
-      <p>A list of discussions that have been pinned in this repository.</p>
+        <p>A list of discussions that have been pinned in this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25020,7 +25021,7 @@ <h2 id="prefect_github.repository.query_repository_pinned_issues" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of pinned issues for this repository.</p>
+        <p>A list of pinned issues for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25330,7 +25331,7 @@ <h2 id="prefect_github.repository.query_repository_primary_language" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The primary language of the repository's code.</p>
+        <p>The primary language of the repository's code.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25548,7 +25549,7 @@ <h2 id="prefect_github.repository.query_repository_project" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Find project by number.</p>
+        <p>Find project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25792,7 +25793,7 @@ <h2 id="prefect_github.repository.query_repository_project_next" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Finds and returns the Project (beta) according to the provided Project (beta)
+        <p>Finds and returns the Project (beta) according to the provided Project (beta)
 number.</p>
 
 
@@ -26039,7 +26040,7 @@ <h2 id="prefect_github.repository.query_repository_project_v2" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Finds and returns the Project according to the provided Project number.</p>
+        <p>Finds and returns the Project according to the provided Project number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26283,7 +26284,7 @@ <h2 id="prefect_github.repository.query_repository_projects" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -26659,7 +26660,7 @@ <h2 id="prefect_github.repository.query_repository_projects_next" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>List of projects (beta) linked to this repository.</p>
+        <p>List of projects (beta) linked to this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27009,7 +27010,7 @@ <h2 id="prefect_github.repository.query_repository_projects_v2" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>List of projects linked to this repository.</p>
+        <p>List of projects linked to this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27359,7 +27360,7 @@ <h2 id="prefect_github.repository.query_repository_pull_request" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Returns a single pull request from the current repository by number.</p>
+        <p>Returns a single pull request from the current repository by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27603,7 +27604,7 @@ <h2 id="prefect_github.repository.query_repository_pull_request_templates" class
 
     <div class="doc doc-contents ">
 
-      <p>Returns a list of pull request templates associated to the repository.</p>
+        <p>Returns a list of pull request templates associated to the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -27821,7 +27822,7 @@ <h2 id="prefect_github.repository.query_repository_pull_requests" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of pull requests that have been opened in the repository.</p>
+        <p>A list of pull requests that have been opened in the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28243,7 +28244,7 @@ <h2 id="prefect_github.repository.query_repository_recent_projects" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Recent projects that this user has modified in the context of the owner.</p>
+        <p>Recent projects that this user has modified in the context of the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28553,7 +28554,7 @@ <h2 id="prefect_github.repository.query_repository_ref" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a given ref from the repository.</p>
+        <p>Fetch a given ref from the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -28803,7 +28804,7 @@ <h2 id="prefect_github.repository.query_repository_refs" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a list of refs from the repository.</p>
+        <p>Fetch a list of refs from the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29196,7 +29197,7 @@ <h2 id="prefect_github.repository.query_repository_release" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Lookup a single release given various criteria.</p>
+        <p>Lookup a single release given various criteria.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29440,7 +29441,7 @@ <h2 id="prefect_github.repository.query_repository_releases" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>List of releases which are dependent on this repository.</p>
+        <p>List of releases which are dependent on this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -29770,7 +29771,7 @@ <h2 id="prefect_github.repository.query_repository_repository_topics" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>A list of applied repository-topic associations for this repository.</p>
+        <p>A list of applied repository-topic associations for this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30080,7 +30081,7 @@ <h2 id="prefect_github.repository.query_repository_stargazers" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>A list of users who have starred this starrable.</p>
+        <p>A list of users who have starred this starrable.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -30410,7 +30411,7 @@ <h2 id="prefect_github.repository.query_repository_submodules" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns a list of all submodules in this repository parsed from the .gitmodules
+        <p>Returns a list of all submodules in this repository parsed from the .gitmodules
 file as of the default branch's HEAD commit.</p>
 
 
@@ -30723,7 +30724,7 @@ <h2 id="prefect_github.repository.query_repository_vulnerability_alerts" class="
 
     <div class="doc doc-contents ">
 
-      <p>A list of vulnerability alerts that are on this repository.</p>
+        <p>A list of vulnerability alerts that are on this repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -31083,7 +31084,7 @@ <h2 id="prefect_github.repository.query_repository_watchers" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>A list of users watching the repository.</p>
+        <p>A list of users watching the repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/repository_owner/index.html b/versions/unreleased/integrations/prefect-github/repository_owner/index.html
index 4e2b53b6a3..91abd15e72 100644
--- a/versions/unreleased/integrations/prefect-github/repository_owner/index.html
+++ b/versions/unreleased/integrations/prefect-github/repository_owner/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13266,7 +13267,7 @@ <h1 id="prefect_github.repository_owner" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub query_repository_owner* tasks</p>
 
 
@@ -13296,7 +13297,7 @@ <h2 id="prefect_github.repository_owner.query_repository_owner" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>The query root of GitHub's GraphQL interface.</p>
+        <p>The query root of GitHub's GraphQL interface.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13465,7 +13466,7 @@ <h2 id="prefect_github.repository_owner.query_repository_owner_repositories" cla
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user owns.</p>
+        <p>A list of repositories that the user owns.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13888,7 +13889,7 @@ <h2 id="prefect_github.repository_owner.query_repository_owner_repository" class
 
     <div class="doc doc-contents ">
 
-      <p>Find Repository.</p>
+        <p>Find Repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/user/index.html b/versions/unreleased/integrations/prefect-github/user/index.html
index 7047a7780a..259ed76bbc 100644
--- a/versions/unreleased/integrations/prefect-github/user/index.html
+++ b/versions/unreleased/integrations/prefect-github/user/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14190,7 +14191,7 @@ <h1 id="prefect_github.user" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub query_user* tasks</p>
 
 
@@ -14220,7 +14221,7 @@ <h2 id="prefect_github.user.query_user" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The query root of GitHub's GraphQL interface.</p>
+        <p>The query root of GitHub's GraphQL interface.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14389,7 +14390,7 @@ <h2 id="prefect_github.user.query_user_commit_comments" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of commit comments made by this user.</p>
+        <p>A list of commit comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14656,7 +14657,7 @@ <h2 id="prefect_github.user.query_user_contributions_collection" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>The collection of contributions this user has made to different repositories.</p>
+        <p>The collection of contributions this user has made to different repositories.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14912,7 +14913,7 @@ <h2 id="prefect_github.user.query_user_followers" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of users the given user is followed by.</p>
+        <p>A list of users the given user is followed by.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15179,7 +15180,7 @@ <h2 id="prefect_github.user.query_user_following" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of users the given user is following.</p>
+        <p>A list of users the given user is following.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15446,7 +15447,7 @@ <h2 id="prefect_github.user.query_user_gist" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find gist by repo name.</p>
+        <p>Find gist by repo name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15647,7 +15648,7 @@ <h2 id="prefect_github.user.query_user_gist_comments" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of gist comments made by this user.</p>
+        <p>A list of gist comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15914,7 +15915,7 @@ <h2 id="prefect_github.user.query_user_gists" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of the Gists the user has created.</p>
+        <p>A list of the Gists the user has created.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16221,7 +16222,7 @@ <h2 id="prefect_github.user.query_user_interaction_ability" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>The interaction ability settings for this user.</p>
+        <p>The interaction ability settings for this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16396,7 +16397,7 @@ <h2 id="prefect_github.user.query_user_issue_comments" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of issue comments made by this user.</p>
+        <p>A list of issue comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16686,7 +16687,7 @@ <h2 id="prefect_github.user.query_user_issues" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of issues associated with this user.</p>
+        <p>A list of issues associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17039,7 +17040,7 @@ <h2 id="prefect_github.user.query_user_item_showcase" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Showcases a selection of repositories and gists that the profile owner has
+        <p>Showcases a selection of repositories and gists that the profile owner has
 either curated or that have been selected automatically based on popularity.</p>
 
 
@@ -17217,7 +17218,7 @@ <h2 id="prefect_github.user.query_user_organization" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find an organization by its login that the user belongs to.</p>
+        <p>Find an organization by its login that the user belongs to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17418,7 +17419,7 @@ <h2 id="prefect_github.user.query_user_organizations" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of organizations the user belongs to.</p>
+        <p>A list of organizations the user belongs to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17685,7 +17686,7 @@ <h2 id="prefect_github.user.query_user_packages" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of packages under the owner.</p>
+        <p>A list of packages under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18038,7 +18039,7 @@ <h2 id="prefect_github.user.query_user_pinnable_items" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner can pin to their profile.</p>
+        <p>A list of repositories and gists this profile owner can pin to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18328,7 +18329,7 @@ <h2 id="prefect_github.user.query_user_pinned_items" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
+        <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18615,7 +18616,7 @@ <h2 id="prefect_github.user.query_user_project" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find project by number.</p>
+        <p>Find project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18816,7 +18817,7 @@ <h2 id="prefect_github.user.query_user_project_next" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by project (beta) number.</p>
+        <p>Find a project by project (beta) number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19017,7 +19018,7 @@ <h2 id="prefect_github.user.query_user_project_v2" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by number.</p>
+        <p>Find a project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19218,7 +19219,7 @@ <h2 id="prefect_github.user.query_user_projects" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19551,7 +19552,7 @@ <h2 id="prefect_github.user.query_user_projects_next" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects (beta) under the owner.</p>
+        <p>A list of projects (beta) under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19858,7 +19859,7 @@ <h2 id="prefect_github.user.query_user_projects_v2" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20165,7 +20166,7 @@ <h2 id="prefect_github.user.query_user_public_keys" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of public keys associated with this user.</p>
+        <p>A list of public keys associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20432,7 +20433,7 @@ <h2 id="prefect_github.user.query_user_pull_requests" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of pull requests associated with this user.</p>
+        <p>A list of pull requests associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20811,7 +20812,7 @@ <h2 id="prefect_github.user.query_user_recent_projects" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Recent projects that this user has modified in the context of the owner.</p>
+        <p>Recent projects that this user has modified in the context of the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21078,7 +21079,7 @@ <h2 id="prefect_github.user.query_user_repositories" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user owns.</p>
+        <p>A list of repositories that the user owns.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21501,7 +21502,7 @@ <h2 id="prefect_github.user.query_user_repositories_contributed_to" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user recently contributed to.</p>
+        <p>A list of repositories that the user recently contributed to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21892,7 +21893,7 @@ <h2 id="prefect_github.user.query_user_repository" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find Repository.</p>
+        <p>Find Repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22116,7 +22117,7 @@ <h2 id="prefect_github.user.query_user_repository_discussion_comments" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Discussion comments this user has authored.</p>
+        <p>Discussion comments this user has authored.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22435,7 +22436,7 @@ <h2 id="prefect_github.user.query_user_repository_discussions" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Discussions this user has started.</p>
+        <p>Discussions this user has started.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22786,7 +22787,7 @@ <h2 id="prefect_github.user.query_user_saved_replies" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Replies this user has saved.</p>
+        <p>Replies this user has saved.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23079,7 +23080,7 @@ <h2 id="prefect_github.user.query_user_sponsoring" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List of users and organizations this entity is sponsoring.</p>
+        <p>List of users and organizations this entity is sponsoring.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23369,7 +23370,7 @@ <h2 id="prefect_github.user.query_user_sponsors" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsors for this user or organization.</p>
+        <p>List of sponsors for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23685,7 +23686,7 @@ <h2 id="prefect_github.user.query_user_sponsors_activities" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Events involving this sponsorable, such as new sponsorships.</p>
+        <p>Events involving this sponsorable, such as new sponsorships.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24030,7 +24031,7 @@ <h2 id="prefect_github.user.query_user_sponsors_listing" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>The GitHub Sponsors listing for this user or organization.</p>
+        <p>The GitHub Sponsors listing for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24205,7 +24206,7 @@ <h2 id="prefect_github.user.query_user_sponsorship_for_viewer_as_sponsor" class=
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from the viewer to this user/organization; that is, the
+        <p>The sponsorship from the viewer to this user/organization; that is, the
 sponsorship where you're the sponsor. Only returns a sponsorship if it is
 active.</p>
 
@@ -24386,7 +24387,7 @@ <h2 id="prefect_github.user.query_user_sponsorship_for_viewer_as_sponsorable" cl
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from this user/organization to the viewer; that is, the
+        <p>The sponsorship from this user/organization to the viewer; that is, the
 sponsorship you're receiving. Only returns a sponsorship if it is active.</p>
 
 
@@ -24564,7 +24565,7 @@ <h2 id="prefect_github.user.query_user_sponsorship_newsletters" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
+        <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24866,7 +24867,7 @@ <h2 id="prefect_github.user.query_user_sponsorships_as_maintainer" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the maintainer.</p>
+        <p>This object's sponsorships as the maintainer.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25191,7 +25192,7 @@ <h2 id="prefect_github.user.query_user_sponsorships_as_sponsor" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the sponsor.</p>
+        <p>This object's sponsorships as the sponsor.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25493,7 +25494,7 @@ <h2 id="prefect_github.user.query_user_starred_repositories" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Repositories the user has starred.</p>
+        <p>Repositories the user has starred.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25806,7 +25807,7 @@ <h2 id="prefect_github.user.query_user_status" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The user's description of what they're currently doing.</p>
+        <p>The user's description of what they're currently doing.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -25981,7 +25982,7 @@ <h2 id="prefect_github.user.query_user_top_repositories" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Repositories the user has contributed to, ordered by contribution rank, plus
+        <p>Repositories the user has contributed to, ordered by contribution rank, plus
 repositories the user has created.</p>
 
 
@@ -26297,7 +26298,7 @@ <h2 id="prefect_github.user.query_user_watching" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories the given user is watching.</p>
+        <p>A list of repositories the given user is watching.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-github/utils/index.html b/versions/unreleased/integrations/prefect-github/utils/index.html
index c8f218fe65..95bf8691d1 100644
--- a/versions/unreleased/integrations/prefect-github/utils/index.html
+++ b/versions/unreleased/integrations/prefect-github/utils/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13266,7 +13267,7 @@ <h1 id="prefect_github.utils" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities to assist with using generated collections.</p>
+        <p>Utilities to assist with using generated collections.</p>
 
 
 
@@ -13291,7 +13292,7 @@ <h2 id="prefect_github.utils.camel_to_snake_case" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Converts CamelCase and lowerCamelCase to snake_case.
+        <p>Converts CamelCase and lowerCamelCase to snake_case.
 Args:
     string: The string in CamelCase or lowerCamelCase to convert.
 Returns:
@@ -13335,7 +13336,7 @@ <h2 id="prefect_github.utils.initialize_return_fields_defaults" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Reads config_path to parse out the desired default fields to return.
+        <p>Reads config_path to parse out the desired default fields to return.
 Args:
     config_path: The path to the config file.</p>
 
@@ -13401,7 +13402,7 @@ <h2 id="prefect_github.utils.strip_kwargs" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Drops keyword arguments if value is None because sgqlc.Operation
+        <p>Drops keyword arguments if value is None because sgqlc.Operation
 errors out if a keyword argument is provided, but set to None.</p>
 
 
diff --git a/versions/unreleased/integrations/prefect-github/viewer/index.html b/versions/unreleased/integrations/prefect-github/viewer/index.html
index e683283875..f0baa1f97e 100644
--- a/versions/unreleased/integrations/prefect-github/viewer/index.html
+++ b/versions/unreleased/integrations/prefect-github/viewer/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -14190,7 +14191,7 @@ <h1 id="prefect_github.viewer" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>This is a module containing:
+        <p>This is a module containing:
 GitHub query_viewer* tasks</p>
 
 
@@ -14220,7 +14221,7 @@ <h2 id="prefect_github.viewer.query_viewer" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The query root of GitHub's GraphQL interface.</p>
+        <p>The query root of GitHub's GraphQL interface.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14363,7 +14364,7 @@ <h2 id="prefect_github.viewer.query_viewer_commit_comments" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>A list of commit comments made by this user.</p>
+        <p>A list of commit comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14604,7 +14605,7 @@ <h2 id="prefect_github.viewer.query_viewer_contributions_collection" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>The collection of contributions this user has made to different repositories.</p>
+        <p>The collection of contributions this user has made to different repositories.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14834,7 +14835,7 @@ <h2 id="prefect_github.viewer.query_viewer_followers" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of users the given user is followed by.</p>
+        <p>A list of users the given user is followed by.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15075,7 +15076,7 @@ <h2 id="prefect_github.viewer.query_viewer_following" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of users the given user is following.</p>
+        <p>A list of users the given user is following.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15316,7 +15317,7 @@ <h2 id="prefect_github.viewer.query_viewer_gist" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find gist by repo name.</p>
+        <p>Find gist by repo name.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15491,7 +15492,7 @@ <h2 id="prefect_github.viewer.query_viewer_gist_comments" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A list of gist comments made by this user.</p>
+        <p>A list of gist comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15732,7 +15733,7 @@ <h2 id="prefect_github.viewer.query_viewer_gists" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of the Gists the user has created.</p>
+        <p>A list of the Gists the user has created.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16013,7 +16014,7 @@ <h2 id="prefect_github.viewer.query_viewer_interaction_ability" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>The interaction ability settings for this user.</p>
+        <p>The interaction ability settings for this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16162,7 +16163,7 @@ <h2 id="prefect_github.viewer.query_viewer_issue_comments" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A list of issue comments made by this user.</p>
+        <p>A list of issue comments made by this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16426,7 +16427,7 @@ <h2 id="prefect_github.viewer.query_viewer_issues" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of issues associated with this user.</p>
+        <p>A list of issues associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16753,7 +16754,7 @@ <h2 id="prefect_github.viewer.query_viewer_item_showcase" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Showcases a selection of repositories and gists that the profile owner has
+        <p>Showcases a selection of repositories and gists that the profile owner has
 either curated or that have been selected automatically based on popularity.</p>
 
 
@@ -16905,7 +16906,7 @@ <h2 id="prefect_github.viewer.query_viewer_organization" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Find an organization by its login that the user belongs to.</p>
+        <p>Find an organization by its login that the user belongs to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17080,7 +17081,7 @@ <h2 id="prefect_github.viewer.query_viewer_organizations" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A list of organizations the user belongs to.</p>
+        <p>A list of organizations the user belongs to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17321,7 +17322,7 @@ <h2 id="prefect_github.viewer.query_viewer_packages" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of packages under the owner.</p>
+        <p>A list of packages under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17648,7 +17649,7 @@ <h2 id="prefect_github.viewer.query_viewer_pinnable_items" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner can pin to their profile.</p>
+        <p>A list of repositories and gists this profile owner can pin to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17912,7 +17913,7 @@ <h2 id="prefect_github.viewer.query_viewer_pinned_items" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
+        <p>A list of repositories and gists this profile owner has pinned to their profile.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18173,7 +18174,7 @@ <h2 id="prefect_github.viewer.query_viewer_project" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find project by number.</p>
+        <p>Find project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18348,7 +18349,7 @@ <h2 id="prefect_github.viewer.query_viewer_project_next" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by project (beta) number.</p>
+        <p>Find a project by project (beta) number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18523,7 +18524,7 @@ <h2 id="prefect_github.viewer.query_viewer_project_v2" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find a project by number.</p>
+        <p>Find a project by number.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -18698,7 +18699,7 @@ <h2 id="prefect_github.viewer.query_viewer_projects" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19005,7 +19006,7 @@ <h2 id="prefect_github.viewer.query_viewer_projects_next" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects (beta) under the owner.</p>
+        <p>A list of projects (beta) under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19286,7 +19287,7 @@ <h2 id="prefect_github.viewer.query_viewer_projects_v2" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of projects under the owner.</p>
+        <p>A list of projects under the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19567,7 +19568,7 @@ <h2 id="prefect_github.viewer.query_viewer_public_keys" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of public keys associated with this user.</p>
+        <p>A list of public keys associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -19808,7 +19809,7 @@ <h2 id="prefect_github.viewer.query_viewer_pull_requests" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>A list of pull requests associated with this user.</p>
+        <p>A list of pull requests associated with this user.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20161,7 +20162,7 @@ <h2 id="prefect_github.viewer.query_viewer_recent_projects" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Recent projects that this user has modified in the context of the owner.</p>
+        <p>Recent projects that this user has modified in the context of the owner.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20402,7 +20403,7 @@ <h2 id="prefect_github.viewer.query_viewer_repositories" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user owns.</p>
+        <p>A list of repositories that the user owns.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -20799,7 +20800,7 @@ <h2 id="prefect_github.viewer.query_viewer_repositories_contributed_to" class="d
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories that the user recently contributed to.</p>
+        <p>A list of repositories that the user recently contributed to.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21164,7 +21165,7 @@ <h2 id="prefect_github.viewer.query_viewer_repository" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Find Repository.</p>
+        <p>Find Repository.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21362,7 +21363,7 @@ <h2 id="prefect_github.viewer.query_viewer_repository_discussion_comments" class
 
     <div class="doc doc-contents ">
 
-      <p>Discussion comments this user has authored.</p>
+        <p>Discussion comments this user has authored.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21655,7 +21656,7 @@ <h2 id="prefect_github.viewer.query_viewer_repository_discussions" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Discussions this user has started.</p>
+        <p>Discussions this user has started.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -21980,7 +21981,7 @@ <h2 id="prefect_github.viewer.query_viewer_saved_replies" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Replies this user has saved.</p>
+        <p>Replies this user has saved.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22247,7 +22248,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsoring" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List of users and organizations this entity is sponsoring.</p>
+        <p>List of users and organizations this entity is sponsoring.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22511,7 +22512,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsors" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsors for this user or organization.</p>
+        <p>List of sponsors for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -22801,7 +22802,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsors_activities" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Events involving this sponsorable, such as new sponsorships.</p>
+        <p>Events involving this sponsorable, such as new sponsorships.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23120,7 +23121,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsors_listing" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>The GitHub Sponsors listing for this user or organization.</p>
+        <p>The GitHub Sponsors listing for this user or organization.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23269,7 +23270,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsor" cl
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from the viewer to this user/organization; that is, the
+        <p>The sponsorship from the viewer to this user/organization; that is, the
 sponsorship where you're the sponsor. Only returns a sponsorship if it is
 active.</p>
 
@@ -23428,7 +23429,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsorable
 
     <div class="doc doc-contents ">
 
-      <p>The sponsorship from this user/organization to the viewer; that is, the
+        <p>The sponsorship from this user/organization to the viewer; that is, the
 sponsorship you're receiving. Only returns a sponsorship if it is active.</p>
 
 
@@ -23584,7 +23585,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsorship_newsletters" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
+        <p>List of sponsorship updates sent from this sponsorable to sponsors.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -23860,7 +23861,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsorships_as_maintainer" class="do
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the maintainer.</p>
+        <p>This object's sponsorships as the maintainer.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24159,7 +24160,7 @@ <h2 id="prefect_github.viewer.query_viewer_sponsorships_as_sponsor" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>This object's sponsorships as the sponsor.</p>
+        <p>This object's sponsorships as the sponsor.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24435,7 +24436,7 @@ <h2 id="prefect_github.viewer.query_viewer_starred_repositories" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Repositories the user has starred.</p>
+        <p>Repositories the user has starred.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24722,7 +24723,7 @@ <h2 id="prefect_github.viewer.query_viewer_status" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The user's description of what they're currently doing.</p>
+        <p>The user's description of what they're currently doing.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -24871,7 +24872,7 @@ <h2 id="prefect_github.viewer.query_viewer_top_repositories" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Repositories the user has contributed to, ordered by contribution rank, plus
+        <p>Repositories the user has contributed to, ordered by contribution rank, plus
 repositories the user has created.</p>
 
 
@@ -25161,7 +25162,7 @@ <h2 id="prefect_github.viewer.query_viewer_watching" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>A list of repositories the given user is watching.</p>
+        <p>A list of repositories the given user is watching.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gitlab/credentials/index.html b/versions/unreleased/integrations/prefect-gitlab/credentials/index.html
index e0eb5e6fcb..c5d98e02ef 100644
--- a/versions/unreleased/integrations/prefect-gitlab/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-gitlab/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_gitlab.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module used to enable authenticated interactions with GitLab</p>
+        <p>Module used to enable authenticated interactions with GitLab</p>
 
 
 
@@ -13285,7 +13286,7 @@ <h2 id="prefect_gitlab.credentials.GitLabCredentials" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Store a GitLab personal access token to interact with private GitLab
+        <p>Store a GitLab personal access token to interact with private GitLab
 repositories.</p>
 
 
@@ -13444,7 +13445,7 @@ <h3 id="prefect_gitlab.credentials.GitLabCredentials.get_client" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Gets an authenticated GitLab client.</p>
+        <p>Gets an authenticated GitLab client.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-gitlab/index.html b/versions/unreleased/integrations/prefect-gitlab/index.html
index 777bc03538..5f94822e8a 100644
--- a/versions/unreleased/integrations/prefect-gitlab/index.html
+++ b/versions/unreleased/integrations/prefect-gitlab/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-gitlab/repositories/index.html b/versions/unreleased/integrations/prefect-gitlab/repositories/index.html
index dda63e16da..c1ef7836a6 100644
--- a/versions/unreleased/integrations/prefect-gitlab/repositories/index.html
+++ b/versions/unreleased/integrations/prefect-gitlab/repositories/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_gitlab.repositories" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Integrations with GitLab.</p>
+        <p>Integrations with GitLab.</p>
 <p>The <code>GitLab</code> class in this collection is a storage block that lets Prefect agents
 pull Prefect flow code from GitLab repositories.</p>
 <p>The <code>GitLab</code> block is ideally configured via the Prefect UI, but can also be used
@@ -13265,7 +13266,7 @@ <h1 id="prefect_gitlab.repositories" class="doc doc-heading">
 
 <p><span class="doc-section-title">Examples:</span></p>
     
-      <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect_gitlab.repositories</span> <span class="kn">import</span> <span class="n">GitLabRepository</span>
+        <div class="highlight"><pre><span></span><code>    <span class="kn">from</span> <span class="nn">prefect_gitlab.repositories</span> <span class="kn">import</span> <span class="n">GitLabRepository</span>
 
     <span class="c1"># public GitLab repository</span>
     <span class="n">public_gitlab_block</span> <span class="o">=</span> <span class="n">GitLabRepository</span><span class="p">(</span>
@@ -13323,7 +13324,7 @@ <h2 id="prefect_gitlab.repositories.GitLabRepository" class="doc doc-heading">
               Bases: <code><span title="prefect.filesystems.ReadableDeploymentStorage">ReadableDeploymentStorage</span></code></p>
 
 
-      <p>Interact with files stored in GitLab repositories.</p>
+        <p>Interact with files stored in GitLab repositories.</p>
 <p>An accessible installation of git is required for this block to function
 properly.</p>
 
@@ -13650,7 +13651,7 @@ <h3 id="prefect_gitlab.repositories.GitLabRepository.get_directory" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Clones a GitLab project specified in <code>from_path</code> to the provided <code>local_path</code>;
+        <p>Clones a GitLab project specified in <code>from_path</code> to the provided <code>local_path</code>;
 defaults to cloning the repository reference configured on the Block to the
 present working directory.
 Args:
diff --git a/versions/unreleased/integrations/prefect-kubernetes/credentials/index.html b/versions/unreleased/integrations/prefect-kubernetes/credentials/index.html
index 381044b09c..fbf0cbf785 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13378,7 +13379,7 @@ <h1 id="prefect_kubernetes.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module for defining Kubernetes credential handling and client generation.</p>
+        <p>Module for defining Kubernetes credential handling and client generation.</p>
 
 
 
@@ -13407,7 +13408,7 @@ <h2 id="prefect_kubernetes.credentials.KubernetesClusterConfig" class="doc doc-h
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Stores configuration for interaction with Kubernetes clusters.</p>
+        <p>Stores configuration for interaction with Kubernetes clusters.</p>
 <p>See <code>from_file</code> for creation.</p>
 
 
@@ -13668,7 +13669,7 @@ <h3 id="prefect_kubernetes.credentials.KubernetesClusterConfig.configure_client"
 
     <div class="doc doc-contents ">
 
-      <p>Activates this cluster configuration by loading the configuration into the
+        <p>Activates this cluster configuration by loading the configuration into the
 Kubernetes Python client. After calling this, Kubernetes API clients can use
 this config's context.</p>
 
@@ -13712,7 +13713,7 @@ <h3 id="prefect_kubernetes.credentials.KubernetesClusterConfig.from_file" class=
 
     <div class="doc doc-contents ">
 
-      <p>Create a cluster config from the a Kubernetes config file.</p>
+        <p>Create a cluster config from the a Kubernetes config file.</p>
 <p>By default, the current context in the default Kubernetes config file will be
 used.</p>
 <p>An alternative file or context may be specified.</p>
@@ -13814,7 +13815,7 @@ <h3 id="prefect_kubernetes.credentials.KubernetesClusterConfig.get_api_client" c
 
     <div class="doc doc-contents ">
 
-      <p>Returns a Kubernetes API client for this cluster config.</p>
+        <p>Returns a Kubernetes API client for this cluster config.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_kubernetes/credentials.py</code></summary>
@@ -13861,7 +13862,7 @@ <h2 id="prefect_kubernetes.credentials.KubernetesCredentials" class="doc doc-hea
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Credentials block for generating configured Kubernetes API clients.</p>
+        <p>Credentials block for generating configured Kubernetes API clients.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -14153,7 +14154,7 @@ <h3 id="prefect_kubernetes.credentials.KubernetesCredentials.get_client" class="
 
     <div class="doc doc-contents ">
 
-      <p>Convenience method for retrieving a Kubernetes API client for deployment resources.</p>
+        <p>Convenience method for retrieving a Kubernetes API client for deployment resources.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14326,7 +14327,7 @@ <h3 id="prefect_kubernetes.credentials.KubernetesCredentials.get_resource_specif
 
     <div class="doc doc-contents ">
 
-      <p>Utility function for configuring a generic Kubernetes client.
+        <p>Utility function for configuring a generic Kubernetes client.
 It will attempt to connect to a Kubernetes cluster in three steps with
 the first successful connection attempt becoming the mode of communication with
 a cluster:</p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/custom_objects/index.html b/versions/unreleased/integrations/prefect-kubernetes/custom_objects/index.html
index c476e983f8..dac9b6e310 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/custom_objects/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/custom_objects/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13381,7 +13382,7 @@ <h2 id="prefect_kubernetes.custom_objects.create_namespaced_custom_object" class
 
     <div class="doc doc-contents ">
 
-      <p>Task for creating a namespaced custom object.</p>
+        <p>Task for creating a namespaced custom object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13690,7 +13691,7 @@ <h2 id="prefect_kubernetes.custom_objects.delete_namespaced_custom_object" class
 
     <div class="doc doc-contents ">
 
-      <p>Task for deleting a namespaced custom object.</p>
+        <p>Task for deleting a namespaced custom object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13985,7 +13986,7 @@ <h2 id="prefect_kubernetes.custom_objects.get_namespaced_custom_object" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Task for reading a namespaced Kubernetes custom object.</p>
+        <p>Task for reading a namespaced Kubernetes custom object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14305,7 +14306,7 @@ <h2 id="prefect_kubernetes.custom_objects.get_namespaced_custom_object_status" c
 
     <div class="doc doc-contents ">
 
-      <p>Task for fetching status of a namespaced custom object.</p>
+        <p>Task for fetching status of a namespaced custom object.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14602,7 +14603,7 @@ <h2 id="prefect_kubernetes.custom_objects.list_namespaced_custom_object" class="
 
     <div class="doc doc-contents ">
 
-      <p>Task for listing namespaced custom objects.</p>
+        <p>Task for listing namespaced custom objects.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14873,7 +14874,7 @@ <h2 id="prefect_kubernetes.custom_objects.patch_namespaced_custom_object" class=
 
     <div class="doc doc-contents ">
 
-      <p>Task for patching a namespaced custom resource.</p>
+        <p>Task for patching a namespaced custom resource.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15252,7 +15253,7 @@ <h2 id="prefect_kubernetes.custom_objects.replace_namespaced_custom_object" clas
 
     <div class="doc doc-contents ">
 
-      <p>Task for replacing a namespaced custom resource.</p>
+        <p>Task for replacing a namespaced custom resource.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/deployments/index.html b/versions/unreleased/integrations/prefect-kubernetes/deployments/index.html
index 263c08ac09..7ba72c24c9 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/deployments/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/deployments/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13332,7 +13333,7 @@ <h1 id="prefect_kubernetes.deployments" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module for interacting with Kubernetes deployments from Prefect flows.</p>
+        <p>Module for interacting with Kubernetes deployments from Prefect flows.</p>
 
 
 
@@ -13361,7 +13362,7 @@ <h2 id="prefect_kubernetes.deployments.create_namespaced_deployment" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Create a Kubernetes deployment in a given namespace.</p>
+        <p>Create a Kubernetes deployment in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13579,7 +13580,7 @@ <h2 id="prefect_kubernetes.deployments.delete_namespaced_deployment" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Delete a Kubernetes deployment in a given namespace.</p>
+        <p>Delete a Kubernetes deployment in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13820,7 +13821,7 @@ <h2 id="prefect_kubernetes.deployments.list_namespaced_deployment" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>List all deployments in a given namespace.</p>
+        <p>List all deployments in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14012,7 +14013,7 @@ <h2 id="prefect_kubernetes.deployments.patch_namespaced_deployment" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Patch a Kubernetes deployment in a given namespace.</p>
+        <p>Patch a Kubernetes deployment in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14253,7 +14254,7 @@ <h2 id="prefect_kubernetes.deployments.read_namespaced_deployment" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Read information on a Kubernetes deployment in a given namespace.</p>
+        <p>Read information on a Kubernetes deployment in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14465,7 +14466,7 @@ <h2 id="prefect_kubernetes.deployments.replace_namespaced_deployment" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Replace a Kubernetes deployment in a given namespace.</p>
+        <p>Replace a Kubernetes deployment in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/exceptions/index.html b/versions/unreleased/integrations/prefect-kubernetes/exceptions/index.html
index e19b8138c2..7d1a657326 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/exceptions/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/exceptions/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13288,7 +13289,7 @@ <h1 id="prefect_kubernetes.exceptions" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module to define common exceptions within <code>prefect_kubernetes</code>.</p>
+        <p>Module to define common exceptions within <code>prefect_kubernetes</code>.</p>
 
 
 
@@ -13317,7 +13318,7 @@ <h2 id="prefect_kubernetes.exceptions.KubernetesJobDefinitionError" class="doc d
               Bases: <code><span title="kubernetes_asyncio.client.exceptions.OpenApiException">OpenApiException</span></code></p>
 
 
-      <p>An exception for when a Kubernetes job definition is invalid.</p>
+        <p>An exception for when a Kubernetes job definition is invalid.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/exceptions.py</code></summary>
@@ -13347,7 +13348,7 @@ <h2 id="prefect_kubernetes.exceptions.KubernetesJobFailedError" class="doc doc-h
               Bases: <code><span title="kubernetes_asyncio.client.exceptions.OpenApiException">OpenApiException</span></code></p>
 
 
-      <p>An exception for when a Kubernetes job fails.</p>
+        <p>An exception for when a Kubernetes job fails.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/exceptions.py</code></summary>
@@ -13377,7 +13378,7 @@ <h2 id="prefect_kubernetes.exceptions.KubernetesJobTimeoutError" class="doc doc-
               Bases: <code><span title="kubernetes_asyncio.client.exceptions.OpenApiException">OpenApiException</span></code></p>
 
 
-      <p>An exception for when a Kubernetes job times out.</p>
+        <p>An exception for when a Kubernetes job times out.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/exceptions.py</code></summary>
@@ -13407,7 +13408,7 @@ <h2 id="prefect_kubernetes.exceptions.KubernetesResourceNotFoundError" class="do
               Bases: <code><span title="kubernetes_asyncio.client.exceptions.ApiException">ApiException</span></code></p>
 
 
-      <p>An exception for when a Kubernetes resource cannot be found by a client.</p>
+        <p>An exception for when a Kubernetes resource cannot be found by a client.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/exceptions.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/flows/index.html b/versions/unreleased/integrations/prefect-kubernetes/flows/index.html
index 3c01131d8b..de1a4db7b9 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/flows/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/flows/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13222,7 +13223,7 @@ <h1 id="prefect_kubernetes.flows" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>A module to define flows interacting with Kubernetes resources.</p>
+        <p>A module to define flows interacting with Kubernetes resources.</p>
 
 
 
@@ -13251,7 +13252,7 @@ <h2 id="prefect_kubernetes.flows.run_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Flow for running a namespaced Kubernetes job.</p>
+        <p>Flow for running a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13341,7 +13342,7 @@ <h2 id="prefect_kubernetes.flows.run_namespaced_job" class="doc doc-heading">
           </tr>
       </tbody>
     </table>
-      <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
+        <div class="codehilite"><pre><span></span><code><span class="err">```</span><span class="n">python</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_kubernetes</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">KubernetesJob</span><span class="p">,</span><span class="w"> </span><span class="n">run_namespaced_job</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">prefect_kubernetes.credentials</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="n">KubernetesCredentials</span>
 
diff --git a/versions/unreleased/integrations/prefect-kubernetes/index.html b/versions/unreleased/integrations/prefect-kubernetes/index.html
index a76341be63..c22d995995 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-kubernetes/jobs/index.html b/versions/unreleased/integrations/prefect-kubernetes/jobs/index.html
index c05af87561..cfc11b562e 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/jobs/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/jobs/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13510,7 +13511,7 @@ <h1 id="prefect_kubernetes.jobs" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module to define tasks for interacting with Kubernetes jobs.</p>
+        <p>Module to define tasks for interacting with Kubernetes jobs.</p>
 
 
 
@@ -13539,7 +13540,7 @@ <h2 id="prefect_kubernetes.jobs.KubernetesJob" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobBlock">JobBlock</span></code></p>
 
 
-      <p>A block representing a Kubernetes job configuration.</p>
+        <p>A block representing a Kubernetes job configuration.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/jobs.py</code></summary>
@@ -13714,7 +13715,7 @@ <h3 id="prefect_kubernetes.jobs.KubernetesJob.from_yaml_file" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Create a <code>KubernetesJob</code> from a YAML file.</p>
+        <p>Create a <code>KubernetesJob</code> from a YAML file.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13822,7 +13823,7 @@ <h3 id="prefect_kubernetes.jobs.KubernetesJob.trigger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a Kubernetes job and return a <code>KubernetesJobRun</code> object.</p>
+        <p>Create a Kubernetes job and return a <code>KubernetesJobRun</code> object.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_kubernetes/jobs.py</code></summary>
@@ -13879,7 +13880,7 @@ <h2 id="prefect_kubernetes.jobs.KubernetesJobRun" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobRun">JobRun</span>[<span title="typing.Dict">Dict</span>[str, <span title="typing.Any">Any</span>]]</code></p>
 
 
-      <p>A container representing a run of a Kubernetes job.</p>
+        <p>A container representing a run of a Kubernetes job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/jobs.py</code></summary>
@@ -14198,7 +14199,7 @@ <h3 id="prefect_kubernetes.jobs.KubernetesJobRun.fetch_result" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Fetch the results of the job.</p>
+        <p>Fetch the results of the job.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14307,7 +14308,7 @@ <h3 id="prefect_kubernetes.jobs.KubernetesJobRun.wait_for_completion" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Waits for the job to complete.</p>
+        <p>Waits for the job to complete.</p>
 <p>If the job has <code>delete_after_completion</code> set to <code>True</code>,
 the job will be deleted if it is observed by this method
 to enter a completed state.</p>
@@ -14568,7 +14569,7 @@ <h2 id="prefect_kubernetes.jobs.create_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for creating a namespaced Kubernetes job.</p>
+        <p>Task for creating a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14789,7 +14790,7 @@ <h2 id="prefect_kubernetes.jobs.delete_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for deleting a namespaced Kubernetes job.</p>
+        <p>Task for deleting a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15037,7 +15038,7 @@ <h2 id="prefect_kubernetes.jobs.list_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for listing namespaced Kubernetes jobs.</p>
+        <p>Task for listing namespaced Kubernetes jobs.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15235,7 +15236,7 @@ <h2 id="prefect_kubernetes.jobs.patch_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for patching a namespaced Kubernetes job.</p>
+        <p>Task for patching a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15513,7 +15514,7 @@ <h2 id="prefect_kubernetes.jobs.read_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for reading a namespaced Kubernetes job.</p>
+        <p>Task for reading a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15760,7 +15761,7 @@ <h2 id="prefect_kubernetes.jobs.read_namespaced_job_status" class="doc doc-headi
 
     <div class="doc doc-contents ">
 
-      <p>Task for fetching status of a namespaced Kubernetes job.</p>
+        <p>Task for fetching status of a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -15978,7 +15979,7 @@ <h2 id="prefect_kubernetes.jobs.replace_namespaced_job" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Task for replacing a namespaced Kubernetes job.</p>
+        <p>Task for replacing a namespaced Kubernetes job.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/pods/index.html b/versions/unreleased/integrations/prefect-kubernetes/pods/index.html
index 60a6b68742..3c9e524b09 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/pods/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/pods/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13354,7 +13355,7 @@ <h1 id="prefect_kubernetes.pods" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module for interacting with Kubernetes pods from Prefect flows.</p>
+        <p>Module for interacting with Kubernetes pods from Prefect flows.</p>
 
 
 
@@ -13383,7 +13384,7 @@ <h2 id="prefect_kubernetes.pods.create_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Create a Kubernetes pod in a given namespace.</p>
+        <p>Create a Kubernetes pod in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13601,7 +13602,7 @@ <h2 id="prefect_kubernetes.pods.delete_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Delete a Kubernetes pod in a given namespace.</p>
+        <p>Delete a Kubernetes pod in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13842,7 +13843,7 @@ <h2 id="prefect_kubernetes.pods.list_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>List all pods in a given namespace.</p>
+        <p>List all pods in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14032,7 +14033,7 @@ <h2 id="prefect_kubernetes.pods.patch_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Patch a Kubernetes pod in a given namespace.</p>
+        <p>Patch a Kubernetes pod in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14273,7 +14274,7 @@ <h2 id="prefect_kubernetes.pods.read_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Read information on a Kubernetes pod in a given namespace.</p>
+        <p>Read information on a Kubernetes pod in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14485,7 +14486,7 @@ <h2 id="prefect_kubernetes.pods.read_namespaced_pod_log" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Read logs from a Kubernetes pod in a given namespace.</p>
+        <p>Read logs from a Kubernetes pod in a given namespace.</p>
 <p>If <code>print_func</code> is provided, the logs will be streamed using that function.
 If the pod is no longer running, logs generated up to that point will be returned.</p>
 
@@ -14791,7 +14792,7 @@ <h2 id="prefect_kubernetes.pods.replace_namespaced_pod" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Replace a Kubernetes pod in a given namespace.</p>
+        <p>Replace a Kubernetes pod in a given namespace.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/services/index.html b/versions/unreleased/integrations/prefect-kubernetes/services/index.html
index 30ee6e1f40..b12b453b5a 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/services/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/services/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13332,7 +13333,7 @@ <h1 id="prefect_kubernetes.services" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for working with Kubernetes services.</p>
+        <p>Tasks for working with Kubernetes services.</p>
 
 
 
@@ -13361,7 +13362,7 @@ <h2 id="prefect_kubernetes.services.create_namespaced_service" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Create a namespaced Kubernetes service.</p>
+        <p>Create a namespaced Kubernetes service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13579,7 +13580,7 @@ <h2 id="prefect_kubernetes.services.delete_namespaced_service" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Delete a namespaced Kubernetes service.</p>
+        <p>Delete a namespaced Kubernetes service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13817,7 +13818,7 @@ <h2 id="prefect_kubernetes.services.list_namespaced_service" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>List namespaced Kubernetes services.</p>
+        <p>List namespaced Kubernetes services.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14009,7 +14010,7 @@ <h2 id="prefect_kubernetes.services.patch_namespaced_service" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Patch a namespaced Kubernetes service.</p>
+        <p>Patch a namespaced Kubernetes service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14250,7 +14251,7 @@ <h2 id="prefect_kubernetes.services.read_namespaced_service" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Read a namespaced Kubernetes service.</p>
+        <p>Read a namespaced Kubernetes service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14465,7 +14466,7 @@ <h2 id="prefect_kubernetes.services.replace_namespaced_service" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Replace a namespaced Kubernetes service.</p>
+        <p>Replace a namespaced Kubernetes service.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/utilities/index.html b/versions/unreleased/integrations/prefect-kubernetes/utilities/index.html
index ef01f6c66f..c2dfc25d95 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/utilities/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/utilities/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13222,7 +13223,7 @@ <h1 id="prefect_kubernetes.utilities" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Utilities for working with the Python Kubernetes API.</p>
+        <p>Utilities for working with the Python Kubernetes API.</p>
 
 
 
@@ -13247,7 +13248,7 @@ <h2 id="prefect_kubernetes.utilities.enable_socket_keep_alive" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Setting the keep-alive flags on the kubernetes client object.
+        <p>Setting the keep-alive flags on the kubernetes client object.
 Unfortunately neither the kubernetes library nor the urllib3 library which
 kubernetes is using internally offer the functionality to enable keep-alive
 messages. Thus the flags are added to be used on the underlying sockets.</p>
diff --git a/versions/unreleased/integrations/prefect-kubernetes/worker/index.html b/versions/unreleased/integrations/prefect-kubernetes/worker/index.html
index 20683d4104..b2bb91a39d 100644
--- a/versions/unreleased/integrations/prefect-kubernetes/worker/index.html
+++ b/versions/unreleased/integrations/prefect-kubernetes/worker/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13474,7 +13475,7 @@ <h1 id="prefect_kubernetes.worker" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module containing the Kubernetes worker used for executing flow runs as Kubernetes jobs.</p>
+        <p>Module containing the Kubernetes worker used for executing flow runs as Kubernetes jobs.</p>
 <p>To start a Kubernetes worker, run the following command:</p>
 <div class="highlight"><pre><span></span><code>prefect<span class="w"> </span>worker<span class="w"> </span>start<span class="w"> </span>--pool<span class="w"> </span><span class="s1">&#39;my-work-pool&#39;</span><span class="w"> </span>--type<span class="w"> </span>kubernetes
 </code></pre></div>
@@ -13582,7 +13583,7 @@ <h2 id="prefect_kubernetes.worker.HashableKubernetesClusterConfig" class="doc do
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>A hashable version of the KubernetesClusterConfig class.
+        <p>A hashable version of the KubernetesClusterConfig class.
 Used for caching.</p>
 
               <details class="quote">
@@ -13649,7 +13650,7 @@ <h2 id="prefect_kubernetes.worker.KubernetesImagePullPolicy" class="doc doc-head
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Enum representing the image pull policy options for a Kubernetes job.</p>
+        <p>Enum representing the image pull policy options for a Kubernetes job.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/worker.py</code></summary>
@@ -13703,7 +13704,7 @@ <h2 id="prefect_kubernetes.worker.KubernetesWorker" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseWorker" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker">BaseWorker</a></code></p>
 
 
-      <p>Prefect worker that executes flow runs within Kubernetes Jobs.</p>
+        <p>Prefect worker that executes flow runs within Kubernetes Jobs.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/worker.py</code></summary>
@@ -15102,7 +15103,7 @@ <h3 id="prefect_kubernetes.worker.KubernetesWorker.kill_infrastructure" class="d
 
     <div class="doc doc-contents ">
 
-      <div class="codehilite"><pre><span></span><code><span class="w">    </span><span class="nv">Stops</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">job</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">cancelled</span><span class="w"> </span><span class="nv">flow</span><span class="w"> </span><span class="nv">run</span><span class="w"> </span><span class="nv">based</span><span class="w"> </span><span class="nv">on</span><span class="w"> </span><span class="nv">the</span><span class="w"> </span><span class="nv">provided</span><span class="w"> </span><span class="nv">infrastructure</span><span class="w"> </span><span class="nv">PID</span>
+        <div class="codehilite"><pre><span></span><code><span class="w">    </span><span class="nv">Stops</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">job</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">cancelled</span><span class="w"> </span><span class="nv">flow</span><span class="w"> </span><span class="nv">run</span><span class="w"> </span><span class="nv">based</span><span class="w"> </span><span class="nv">on</span><span class="w"> </span><span class="nv">the</span><span class="w"> </span><span class="nv">provided</span><span class="w"> </span><span class="nv">infrastructure</span><span class="w"> </span><span class="nv">PID</span>
 <span class="w">    </span><span class="nv">and</span><span class="w"> </span><span class="nv">run</span><span class="w"> </span><span class="nv">configuration</span>.
 </code></pre></div>
 
@@ -15152,7 +15153,7 @@ <h3 id="prefect_kubernetes.worker.KubernetesWorker.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a flow run within a Kubernetes Job and waits for the flow run
+        <p>Executes a flow run within a Kubernetes Job and waits for the flow run
 to complete.</p>
 
 
@@ -15364,7 +15365,7 @@ <h2 id="prefect_kubernetes.worker.KubernetesWorkerJobConfiguration" class="doc d
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.workers.base.BaseJobConfiguration" href="../../../api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration">BaseJobConfiguration</a></code></p>
 
 
-      <p>Configuration class used by the Kubernetes worker.</p>
+        <p>Configuration class used by the Kubernetes worker.</p>
 <p>An instance of this class is passed to the Kubernetes worker's <code>run</code> method
 for each flow run. It contains all of the information necessary to execute
 the flow run as a Kubernetes job.</p>
@@ -16022,7 +16023,7 @@ <h3 id="prefect_kubernetes.worker.KubernetesWorkerJobConfiguration.prepare_for_f
 
     <div class="doc doc-contents ">
 
-      <p>Prepares the job configuration for a flow run.</p>
+        <p>Prepares the job configuration for a flow run.</p>
 <p>Ensures that necessary values are present in the job manifest and that the
 job manifest is valid.</p>
 
@@ -16173,7 +16174,7 @@ <h2 id="prefect_kubernetes.worker.KubernetesWorkerResult" class="doc doc-heading
               Bases: <code><span title="prefect.workers.base.BaseWorkerResult">BaseWorkerResult</span></code></p>
 
 
-      <p>Contains information about the final state of a completed process</p>
+        <p>Contains information about the final state of a completed process</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_kubernetes/worker.py</code></summary>
@@ -16219,7 +16220,7 @@ <h2 id="prefect_kubernetes.worker.KubernetesWorkerVariables" class="doc doc-head
               Bases: <code><span title="prefect.workers.base.BaseVariables">BaseVariables</span></code></p>
 
 
-      <p>Default variables for the Kubernetes worker.</p>
+        <p>Default variables for the Kubernetes worker.</p>
 <p>The schema for this class is used to populate the <code>variables</code> section of the default
 base job template.</p>
 
diff --git a/versions/unreleased/integrations/prefect-ray/index.html b/versions/unreleased/integrations/prefect-ray/index.html
index 35ccdf7e0e..b76dce056b 100644
--- a/versions/unreleased/integrations/prefect-ray/index.html
+++ b/versions/unreleased/integrations/prefect-ray/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-ray/task-runners/index.html b/versions/unreleased/integrations/prefect-ray/task-runners/index.html
index 702ac055a8..f6ed8ad7a4 100644
--- a/versions/unreleased/integrations/prefect-ray/task-runners/index.html
+++ b/versions/unreleased/integrations/prefect-ray/task-runners/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13256,7 +13257,7 @@ <h1 id="prefect_ray.task_runners" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Interface and implementations of the Ray Task Runner.
+        <p>Interface and implementations of the Ray Task Runner.
 <a href="https://docs.prefect.io/api-ref/prefect/task-runners/">Task Runners</a>
 in Prefect are responsible for managing the execution of Prefect task runs.
 Generally speaking, users are not expected to interact with
@@ -13353,7 +13354,7 @@ <h2 id="prefect_ray.task_runners.RayTaskRunner" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.task_runners.BaseTaskRunner" href="../../../api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner">BaseTaskRunner</a></code></p>
 
 
-      <p>A parallel task_runner that submits tasks to <code>ray</code>.
+        <p>A parallel task_runner that submits tasks to <code>ray</code>.
 By default, a temporary Ray cluster is created for the duration of the flow run.
 Alternatively, if you already have a <code>ray</code> instance running, you can provide
 the connection URL via the <code>address</code> kwarg.
@@ -13803,7 +13804,7 @@ <h3 id="prefect_ray.task_runners.RayTaskRunner.duplicate" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Return a new instance of with the same settings as this one.</p>
+        <p>Return a new instance of with the same settings as this one.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_ray/task_runners.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-shell/commands/index.html b/versions/unreleased/integrations/prefect-shell/commands/index.html
index 37d4eff746..fdbcb35923 100644
--- a/versions/unreleased/integrations/prefect-shell/commands/index.html
+++ b/versions/unreleased/integrations/prefect-shell/commands/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13466,7 +13467,7 @@ <h1 id="prefect_shell.commands" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for interacting with shell commands</p>
+        <p>Tasks for interacting with shell commands</p>
 
 
 
@@ -13495,7 +13496,7 @@ <h2 id="prefect_shell.commands.ShellOperation" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobBlock">JobBlock</span></code></p>
 
 
-      <p>A block representing a shell operation, containing multiple commands.</p>
+        <p>A block representing a shell operation, containing multiple commands.</p>
 <p>For long-lasting operations, use the trigger method and utilize the block as a
 context manager for automatic closure of processes when context is exited.
 If not, manually call the close method to close processes.</p>
@@ -14105,7 +14106,7 @@ <h3 id="prefect_shell.commands.ShellOperation.aclose" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Asynchronous version of the close method.</p>
+        <p>Asynchronous version of the close method.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_shell/commands.py</code></summary>
@@ -14139,7 +14140,7 @@ <h3 id="prefect_shell.commands.ShellOperation.close" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Close the job block.</p>
+        <p>Close the job block.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_shell/commands.py</code></summary>
@@ -14177,7 +14178,7 @@ <h3 id="prefect_shell.commands.ShellOperation.run" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs a shell command, but unlike the trigger method,
+        <p>Runs a shell command, but unlike the trigger method,
 additionally waits and fetches the result directly, automatically managing
 the context. This method is ideal for short-lasting shell commands;
 for long-lasting shell commands, it is
@@ -14341,7 +14342,7 @@ <h3 id="prefect_shell.commands.ShellOperation.trigger" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Triggers a shell command and returns the shell command run object
+        <p>Triggers a shell command and returns the shell command run object
 to track the execution of the run. This method is ideal for long-lasting
 shell commands; for short-lasting shell commands, it is recommended
 to use the <code>run</code> method instead.</p>
@@ -14516,7 +14517,7 @@ <h2 id="prefect_shell.commands.ShellProcess" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.JobRun">JobRun</span></code></p>
 
 
-      <p>A class representing a shell process.</p>
+        <p>A class representing a shell process.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_shell/commands.py</code></summary>
@@ -14692,7 +14693,7 @@ <h3 id="prefect_shell.commands.ShellProcess.pid" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>The PID of the process.</p>
+        <p>The PID of the process.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14736,7 +14737,7 @@ <h3 id="prefect_shell.commands.ShellProcess.return_code" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>The return code of the process.</p>
+        <p>The return code of the process.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14781,7 +14782,7 @@ <h3 id="prefect_shell.commands.ShellProcess.fetch_result" class="doc doc-heading
 
     <div class="doc doc-contents ">
 
-      <p>Retrieve the output of the shell operation.</p>
+        <p>Retrieve the output of the shell operation.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -14850,7 +14851,7 @@ <h3 id="prefect_shell.commands.ShellProcess.wait_for_completion" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Wait for the shell command to complete after a process is triggered.</p>
+        <p>Wait for the shell command to complete after a process is triggered.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_shell/commands.py</code></summary>
@@ -14923,7 +14924,7 @@ <h2 id="prefect_shell.commands.shell_run_command" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Runs arbitrary shell commands.</p>
+        <p>Runs arbitrary shell commands.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-shell/index.html b/versions/unreleased/integrations/prefect-shell/index.html
index dbaa78496d..5a55b2f798 100644
--- a/versions/unreleased/integrations/prefect-shell/index.html
+++ b/versions/unreleased/integrations/prefect-shell/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-slack/credentials/index.html b/versions/unreleased/integrations/prefect-slack/credentials/index.html
index 1dd8f867cf..bdc3952c87 100644
--- a/versions/unreleased/integrations/prefect-slack/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-slack/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13334,7 +13335,7 @@ <h1 id="prefect_slack.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes use to store Slack credentials.</p>
+        <p>Credential classes use to store Slack credentials.</p>
 
 
 
@@ -13363,7 +13364,7 @@ <h2 id="prefect_slack.credentials.SlackCredentials" class="doc doc-heading">
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block holding Slack credentials for use in tasks and flows.</p>
+        <p>Block holding Slack credentials for use in tasks and flows.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13504,7 +13505,7 @@ <h3 id="prefect_slack.credentials.SlackCredentials.get_client" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated <code>AsyncWebClient</code> to interact with the Slack API.</p>
+        <p>Returns an authenticated <code>AsyncWebClient</code> to interact with the Slack API.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_slack/credentials.py</code></summary>
@@ -13547,7 +13548,7 @@ <h2 id="prefect_slack.credentials.SlackWebhook" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.notifications.NotificationBlock">NotificationBlock</span></code></p>
 
 
-      <p>Block holding a Slack webhook for use in tasks and flows.</p>
+        <p>Block holding a Slack webhook for use in tasks and flows.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13758,7 +13759,7 @@ <h3 id="prefect_slack.credentials.SlackWebhook.get_client" class="doc doc-headin
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated <code>AsyncWebhookClient</code> to interact with the configured
+        <p>Returns an authenticated <code>AsyncWebhookClient</code> to interact with the configured
 Slack webhook.</p>
 
             <details class="quote">
@@ -13795,7 +13796,7 @@ <h3 id="prefect_slack.credentials.SlackWebhook.notify" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sends a message to the Slack channel.</p>
+        <p>Sends a message to the Slack channel.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_slack/credentials.py</code></summary>
diff --git a/versions/unreleased/integrations/prefect-slack/index.html b/versions/unreleased/integrations/prefect-slack/index.html
index 53b8b67bc6..59ce16b006 100644
--- a/versions/unreleased/integrations/prefect-slack/index.html
+++ b/versions/unreleased/integrations/prefect-slack/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-slack/messages/index.html b/versions/unreleased/integrations/prefect-slack/messages/index.html
index 248ef796c6..494d1af65d 100644
--- a/versions/unreleased/integrations/prefect-slack/messages/index.html
+++ b/versions/unreleased/integrations/prefect-slack/messages/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13244,7 +13245,7 @@ <h1 id="prefect_slack.messages" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for sending Slack messages.</p>
+        <p>Tasks for sending Slack messages.</p>
 
 
 
@@ -13273,7 +13274,7 @@ <h2 id="prefect_slack.messages.send_chat_message" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Sends a message to a Slack channel.</p>
+        <p>Sends a message to a Slack channel.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -13579,7 +13580,7 @@ <h2 id="prefect_slack.messages.send_incoming_webhook_message" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Sends a message via an incoming webhook.</p>
+        <p>Sends a message via an incoming webhook.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-snowflake/credentials/index.html b/versions/unreleased/integrations/prefect-snowflake/credentials/index.html
index e22e376a89..3571a7f58c 100644
--- a/versions/unreleased/integrations/prefect-snowflake/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-snowflake/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13300,7 +13301,7 @@ <h1 id="prefect_snowflake.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credentials block for authenticating with Snowflake.</p>
+        <p>Credentials block for authenticating with Snowflake.</p>
 
 
 
@@ -13329,7 +13330,7 @@ <h2 id="prefect_snowflake.credentials.InvalidPemFormat" class="doc doc-heading">
               Bases: <code>Exception</code></p>
 
 
-      <p>Invalid PEM Format Certificate</p>
+        <p>Invalid PEM Format Certificate</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_snowflake/credentials.py</code></summary>
@@ -13359,7 +13360,7 @@ <h2 id="prefect_snowflake.credentials.SnowflakeCredentials" class="doc doc-headi
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code></p>
 
 
-      <p>Block used to manage authentication with Snowflake.</p>
+        <p>Block used to manage authentication with Snowflake.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -14144,7 +14145,7 @@ <h3 id="prefect_snowflake.credentials.SnowflakeCredentials.get_client" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated connection that can be used to query
+        <p>Returns an authenticated connection that can be used to query
 Snowflake databases.</p>
 <p>Any additional arguments passed to this method will be used to configure
 the SnowflakeConnection. For available parameters, please refer to the
@@ -14363,7 +14364,7 @@ <h3 id="prefect_snowflake.credentials.SnowflakeCredentials.resolve_private_key"
 
     <div class="doc doc-contents ">
 
-      <p>Converts a PEM encoded private key into a DER binary key.</p>
+        <p>Converts a PEM encoded private key into a DER binary key.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
diff --git a/versions/unreleased/integrations/prefect-snowflake/database/index.html b/versions/unreleased/integrations/prefect-snowflake/database/index.html
index 16dd954636..865c081e60 100644
--- a/versions/unreleased/integrations/prefect-snowflake/database/index.html
+++ b/versions/unreleased/integrations/prefect-snowflake/database/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13476,7 +13477,7 @@ <h1 id="prefect_snowflake.database" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Module for querying against Snowflake databases.</p>
+        <p>Module for querying against Snowflake databases.</p>
 
 
 
@@ -13505,7 +13506,7 @@ <h2 id="prefect_snowflake.database.SnowflakeConnector" class="doc doc-heading">
               Bases: <code><span title="prefect.blocks.abstract.DatabaseBlock">DatabaseBlock</span></code></p>
 
 
-      <p>Block used to manage connections with Snowflake.</p>
+        <p>Block used to manage connections with Snowflake.</p>
 <p>Upon instantiating, a connection is created and maintained for the life of
 the object until the close method is called.</p>
 <p>It is recommended to use this block as a context manager, which will automatically
@@ -14774,7 +14775,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.close" class="doc doc-head
 
     <div class="doc doc-contents ">
 
-      <p>Closes connection and its cursors.</p>
+        <p>Closes connection and its cursors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_snowflake/database.py</code></summary>
@@ -14824,7 +14825,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.execute" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Executes an operation on the database. This method is intended to be used
+        <p>Executes an operation on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.
 Unlike the fetch methods, this method will always execute the operation
 upon calling.</p>
@@ -15015,7 +15016,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.execute_many" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Executes many operations on the database. This method is intended to be used
+        <p>Executes many operations on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.
 Unlike the fetch methods, this method will always execute the operations
 upon calling.</p>
@@ -15196,7 +15197,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.fetch_all" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Fetch all results from the database.
+        <p>Fetch all results from the database.
 Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -15466,7 +15467,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.fetch_many" class="doc doc
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a limited number of results from the database.
+        <p>Fetch a limited number of results from the database.
 Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -15780,7 +15781,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.fetch_one" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a single result from the database.
+        <p>Fetch a single result from the database.
 Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -16043,7 +16044,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.get_connection" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated connection that can be
+        <p>Returns an authenticated connection that can be
 used to query from Snowflake databases.</p>
 
 
@@ -16225,7 +16226,7 @@ <h3 id="prefect_snowflake.database.SnowflakeConnector.reset_cursors" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Tries to close all opened cursors.</p>
+        <p>Tries to close all opened cursors.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -16360,7 +16361,7 @@ <h2 id="prefect_snowflake.database.snowflake_multiquery" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Executes multiple queries against a Snowflake database in a shared session.
+        <p>Executes multiple queries against a Snowflake database in a shared session.
 Allows execution in a transaction.</p>
 
 
@@ -16721,7 +16722,7 @@ <h2 id="prefect_snowflake.database.snowflake_query" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a query against a Snowflake database.</p>
+        <p>Executes a query against a Snowflake database.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17015,7 +17016,7 @@ <h2 id="prefect_snowflake.database.snowflake_query_sync" class="doc doc-heading"
 
     <div class="doc doc-contents ">
 
-      <p>Executes a query in sync mode against a Snowflake database.</p>
+        <p>Executes a query in sync mode against a Snowflake database.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-snowflake/index.html b/versions/unreleased/integrations/prefect-snowflake/index.html
index 65c1871259..d2aac795b8 100644
--- a/versions/unreleased/integrations/prefect-snowflake/index.html
+++ b/versions/unreleased/integrations/prefect-snowflake/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/prefect-sqlalchemy/credentials/index.html b/versions/unreleased/integrations/prefect-sqlalchemy/credentials/index.html
index e2e0722ed2..cd5482ecf0 100644
--- a/versions/unreleased/integrations/prefect-sqlalchemy/credentials/index.html
+++ b/versions/unreleased/integrations/prefect-sqlalchemy/credentials/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13422,7 +13423,7 @@ <h1 id="prefect_sqlalchemy.credentials" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Credential classes used to perform authenticated interactions with SQLAlchemy</p>
+        <p>Credential classes used to perform authenticated interactions with SQLAlchemy</p>
 
 
 
@@ -13451,7 +13452,7 @@ <h2 id="prefect_sqlalchemy.credentials.AsyncDriver" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Known dialects with their corresponding async drivers.</p>
+        <p>Known dialects with their corresponding async drivers.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13589,7 +13590,7 @@ <h2 id="prefect_sqlalchemy.credentials.ConnectionComponents" class="doc doc-head
               Bases: <code><span title="pydantic.BaseModel">BaseModel</span></code></p>
 
 
-      <p>Parameters to use to create a SQLAlchemy engine URL.</p>
+        <p>Parameters to use to create a SQLAlchemy engine URL.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -13842,7 +13843,7 @@ <h3 id="prefect_sqlalchemy.credentials.ConnectionComponents.create_url" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Create a fully formed connection URL.</p>
+        <p>Create a fully formed connection URL.</p>
 
 
     <p><span class="doc-section-title">Returns:</span></p>
@@ -13950,7 +13951,7 @@ <h2 id="prefect_sqlalchemy.credentials.DatabaseCredentials" class="doc doc-headi
               Bases: <code><a class="autorefs autorefs-internal" title="prefect.blocks.core.Block" href="../../../api-ref/prefect/blocks/core/#prefect.blocks.core.Block">Block</a></code></p>
 
 
-      <p>Block used to manage authentication with a database.</p>
+        <p>Block used to manage authentication with a database.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
@@ -14517,7 +14518,7 @@ <h3 id="prefect_sqlalchemy.credentials.DatabaseCredentials.Config" class="doc do
     <div class="doc doc-contents ">
 
 
-      <p>Configuration of pydantic.</p>
+        <p>Configuration of pydantic.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_sqlalchemy/credentials.py</code></summary>
@@ -14567,7 +14568,7 @@ <h3 id="prefect_sqlalchemy.credentials.DatabaseCredentials.block_initialization"
 
     <div class="doc doc-contents ">
 
-      <p>Initializes the engine.</p>
+        <p>Initializes the engine.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/credentials.py</code></summary>
@@ -14691,7 +14692,7 @@ <h3 id="prefect_sqlalchemy.credentials.DatabaseCredentials.dict" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Convert to a dictionary.</p>
+        <p>Convert to a dictionary.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/credentials.py</code></summary>
@@ -14731,7 +14732,7 @@ <h3 id="prefect_sqlalchemy.credentials.DatabaseCredentials.get_engine" class="do
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated engine that can be
+        <p>Returns an authenticated engine that can be
 used to query from databases.</p>
 
 
@@ -14933,7 +14934,7 @@ <h2 id="prefect_sqlalchemy.credentials.SyncDriver" class="doc doc-heading">
               Bases: <code><span title="enum.Enum">Enum</span></code></p>
 
 
-      <p>Known dialects with their corresponding sync drivers.</p>
+        <p>Known dialects with their corresponding sync drivers.</p>
 
 
 <p><span class="doc-section-title">Attributes:</span></p>
diff --git a/versions/unreleased/integrations/prefect-sqlalchemy/database/index.html b/versions/unreleased/integrations/prefect-sqlalchemy/database/index.html
index 16b6065996..3574f6a2a7 100644
--- a/versions/unreleased/integrations/prefect-sqlalchemy/database/index.html
+++ b/versions/unreleased/integrations/prefect-sqlalchemy/database/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
@@ -13608,7 +13609,7 @@ <h1 id="prefect_sqlalchemy.database" class="doc doc-heading">
 
     <div class="doc doc-contents first">
 
-      <p>Tasks for querying a database with SQLAlchemy</p>
+        <p>Tasks for querying a database with SQLAlchemy</p>
 
 
 
@@ -13637,7 +13638,7 @@ <h2 id="prefect_sqlalchemy.database.SqlAlchemyConnector" class="doc doc-heading"
               Bases: <code><span title="prefect.blocks.abstract.CredentialsBlock">CredentialsBlock</span></code>, <code><span title="prefect.blocks.abstract.DatabaseBlock">DatabaseBlock</span></code></p>
 
 
-      <p>Block used to manage authentication with a database.</p>
+        <p>Block used to manage authentication with a database.</p>
 <p>Upon instantiating, an engine is created and maintained for the life of
 the object until the close method is called.</p>
 <p>It is recommended to use this block as a context manager, which will automatically
@@ -15303,7 +15304,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.Config" class="doc doc-h
     <div class="doc doc-contents ">
 
 
-      <p>Configuration of pydantic.</p>
+        <p>Configuration of pydantic.</p>
 
               <details class="quote">
                 <summary>Source code in <code>prefect_sqlalchemy/database.py</code></summary>
@@ -15357,7 +15358,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.aclose" class="doc doc-h
 
     <div class="doc doc-contents ">
 
-      <p>Closes async connections and its cursors.</p>
+        <p>Closes async connections and its cursors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/database.py</code></summary>
@@ -15409,7 +15410,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.block_initialization" cl
 
     <div class="doc doc-contents ">
 
-      <p>Initializes the engine.</p>
+        <p>Initializes the engine.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/database.py</code></summary>
@@ -15477,7 +15478,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.close" class="doc doc-he
 
     <div class="doc doc-contents ">
 
-      <p>Closes sync connections and its cursors.</p>
+        <p>Closes sync connections and its cursors.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/database.py</code></summary>
@@ -15531,7 +15532,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.dict" class="doc doc-hea
 
     <div class="doc doc-contents ">
 
-      <p>Convert to a dictionary.</p>
+        <p>Convert to a dictionary.</p>
 
             <details class="quote">
               <summary>Source code in <code>prefect_sqlalchemy/database.py</code></summary>
@@ -15575,7 +15576,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.execute" class="doc doc-
 
     <div class="doc doc-contents ">
 
-      <p>Executes an operation on the database. This method is intended to be used
+        <p>Executes an operation on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p>
 <p>Unlike the fetch methods, this method will always execute the operation
 upon calling.</p>
@@ -15752,7 +15753,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.execute_many" class="doc
 
     <div class="doc doc-contents ">
 
-      <p>Executes many operations on the database. This method is intended to be used
+        <p>Executes many operations on the database. This method is intended to be used
 for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p>
 <p>Unlike the fetch methods, this method will always execute the operation
 upon calling.</p>
@@ -15945,7 +15946,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_all" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Fetch all results from the database.</p>
+        <p>Fetch all results from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -16168,7 +16169,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_many" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a limited number of results from the database.</p>
+        <p>Fetch a limited number of results from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -16423,7 +16424,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_one" class="doc do
 
     <div class="doc doc-contents ">
 
-      <p>Fetch a single result from the database.</p>
+        <p>Fetch a single result from the database.</p>
 <p>Repeated calls using the same inputs to <em>any</em> of the fetch methods of this
 block will skip executing the operation again, and instead,
 return the next set of results from the previous execution,
@@ -16651,7 +16652,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.get_client" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns either an engine or connection that can be used to query from databases.</p>
+        <p>Returns either an engine or connection that can be used to query from databases.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -16840,7 +16841,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.get_connection" class="d
 
     <div class="doc doc-contents ">
 
-      <p>Returns a connection that can be used to query from databases.</p>
+        <p>Returns a connection that can be used to query from databases.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
@@ -17030,7 +17031,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.get_engine" class="doc d
 
     <div class="doc doc-contents ">
 
-      <p>Returns an authenticated engine that can be
+        <p>Returns an authenticated engine that can be
 used to query from databases.</p>
 <p>If an existing engine exists, return that one.</p>
 
@@ -17264,7 +17265,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.reset_async_connections"
 
     <div class="doc doc-contents ">
 
-      <p>Tries to close all opened connections and their results.</p>
+        <p>Tries to close all opened connections and their results.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -17367,7 +17368,7 @@ <h3 id="prefect_sqlalchemy.database.SqlAlchemyConnector.reset_connections" class
 
     <div class="doc doc-contents ">
 
-      <p>Tries to close all opened connections and their results.</p>
+        <p>Tries to close all opened connections and their results.</p>
 
 
 <p><span class="doc-section-title">Examples:</span></p>
@@ -17469,7 +17470,7 @@ <h2 id="prefect_sqlalchemy.database.sqlalchemy_execute" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a SQL DDL or DML statement; useful for creating tables and inserting rows
+        <p>Executes a SQL DDL or DML statement; useful for creating tables and inserting rows
 since this task does not return any objects.</p>
 
 
@@ -17681,7 +17682,7 @@ <h2 id="prefect_sqlalchemy.database.sqlalchemy_query" class="doc doc-heading">
 
     <div class="doc doc-contents ">
 
-      <p>Executes a SQL query; useful for querying data from existing tables.</p>
+        <p>Executes a SQL query; useful for querying data from existing tables.</p>
 
 
 <p><span class="doc-section-title">Parameters:</span></p>
diff --git a/versions/unreleased/integrations/prefect-sqlalchemy/index.html b/versions/unreleased/integrations/prefect-sqlalchemy/index.html
index 2f3154e824..6f1779725b 100644
--- a/versions/unreleased/integrations/prefect-sqlalchemy/index.html
+++ b/versions/unreleased/integrations/prefect-sqlalchemy/index.html
@@ -208,7 +208,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/integrations/usage/index.html b/versions/unreleased/integrations/usage/index.html
index 63914383bb..6f0b1e07fa 100644
--- a/versions/unreleased/integrations/usage/index.html
+++ b/versions/unreleased/integrations/usage/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/overrides/main.html b/versions/unreleased/overrides/main.html
index 81bf57b40d..860b52c102 100644
--- a/versions/unreleased/overrides/main.html
+++ b/versions/unreleased/overrides/main.html
@@ -9,7 +9,8 @@
 {% block announce %}
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/recipes/recipes/index.html b/versions/unreleased/recipes/recipes/index.html
index 4999df139a..615e30d0e5 100644
--- a/versions/unreleased/recipes/recipes/index.html
+++ b/versions/unreleased/recipes/recipes/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/search/search_index.json b/versions/unreleased/search/search_index.json
index 6276b9fab4..6a65f75445 100644
--- a/versions/unreleased/search/search_index.json
+++ b/versions/unreleased/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to Prefect","text":"<p>Prefect is a workflow orchestration framework for building resilient data pipelines in Python.</p> <p>It's the easiest way to transform any Python function into a unit of work that can be observed and orchestrated. Just bring your Python code, sprinkle in a few decorators, and go!</p> <p>With Prefect you gain:</p> <ul> <li>  scheduling  </li> <li>  retries  </li> <li>  logging  </li> <li>  convenient async functionality </li> <li>  caching </li> <li>  notifications </li> <li>  observability </li> <li>  event-based orchestration </li> </ul> <p></p>","tags":["getting started","quick start","overview"],"boost":2},{"location":"#new-to-prefect","title":"New to Prefect?","text":"<p>Get up and running quickly with the quickstart guide.</p> <p>Want more hands on practice to productionize your workflows? Follow our tutorial.</p> <p>For deeper dives into common use cases, explore our guides.</p> <p>Take your understanding even further with Prefect's concepts and API reference.</p> <p>Join Prefect's vibrant community of over 26,000 engineers to learn with others and share your knowledge!</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["getting started","quick start","overview"],"boost":2},{"location":"faq/","title":"Frequently Asked Questions","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#prefect","title":"Prefect","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#how-is-prefect-licensed","title":"How is Prefect licensed?","text":"<p>Prefect is licensed under the Apache 2.0 License, an OSI approved open-source license. If you have any questions about licensing, please contact us.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#is-the-prefect-v2-cloud-url-different-than-the-prefect-v1-cloud-url","title":"Is the Prefect v2 Cloud URL different than the Prefect v1 Cloud URL?","text":"<p>Yes. Prefect Cloud for v2 is at app.prefect.cloud/ while Prefect Cloud for v1 is at cloud.prefect.io.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#the-prefect-orchestration-engine","title":"The Prefect Orchestration Engine","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#why-was-the-prefect-orchestration-engine-created","title":"Why was the Prefect orchestration engine created?","text":"<p>The Prefect orchestration engine has three major objectives:</p> <ul> <li>Embracing dynamic, DAG-free workflows</li> <li>An extraordinary developer experience</li> <li>Transparent and observable orchestration rules</li> </ul> <p>As Prefect has matured, so has the modern data stack. The on-demand, dynamic, highly scalable workflows that used to exist principally in the domain of data science and analytics are now prevalent throughout all of data engineering. Few companies have workflows that don\u2019t deal with streaming data, uncertain timing, runtime logic, complex dependencies, versioning, or custom scheduling.</p> <p>This means that the current generation of workflow managers are built around the wrong abstraction: the directed acyclic graph (DAG). DAGs are an increasingly arcane, constrained way of representing the dynamic, heterogeneous range of modern data and computation patterns.</p> <p>Furthermore, as workflows have become more complex, it has become even more important to focus on the developer experience of building, testing, and monitoring them. Faced with an explosion of available tools, it is more important than ever for development teams to seek orchestration tools that will be compatible with any code, tools, or services they may require in the future.</p> <p>And finally, this additional complexity means that providing clear and consistent insight into the behavior of the orchestration engine and any decisions it makes is critically important.</p> <p>The Prefect orchestration engine represents a unified solution to these three problems.</p> <p>The Prefect orchestration engine is capable of governing any code through a well-defined series of state transitions designed to maximize the user's understanding of what happened during execution. It's popular to describe \"workflows as code\" or \"orchestration as code,\" but the Prefect engine represents \"code as workflows\": rather than ask users to change how they work to meet the requirements of the orchestrator, we've defined an orchestrator that adapts to how our users work.</p> <p>To achieve this, we've leveraged the familiar tools of native Python: first class functions, type annotations, and <code>async</code> support. Users are free to implement as much \u2014 or as little \u2014 of the Prefect engine as is useful for their objectives.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#if-im-using-prefect-cloud-2-do-i-still-need-to-run-a-prefect-server-locally","title":"If I\u2019m using Prefect Cloud 2, do I still need to run a Prefect server locally?","text":"<p>No, Prefect Cloud hosts an instance of the Prefect API for you. In fact, each workspace in Prefect Cloud corresponds directly to a single instance of the Prefect orchestration engine. See the Prefect Cloud Overview for more information.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#features","title":"Features","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#does-prefect-support-mapping","title":"Does Prefect support mapping?","text":"<p>Yes! For more information, see the <code>Task.map</code> API reference</p> <pre><code>@flow\ndef my_flow():\n\n    # map over a constant\n    for i in range(10):\n        my_mapped_task(i)\n\n    # map over a task's output\n    l = list_task()\n    for i in l.wait().result():\n        my_mapped_task_2(i)\n</code></pre> <p>Note that when tasks are called on constant values, they cannot detect their upstream edges automatically. In this example, <code>my_mapped_task_2</code> does not know that it is downstream from <code>list_task()</code>. Prefect will have convenience functions for detecting these associations, and Prefect's <code>.map()</code> operator will automatically track them.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-enforce-ordering-between-tasks-that-dont-share-data","title":"Can I enforce ordering between tasks that don't share data?","text":"<p>Yes! For more information, see the <code>Tasks</code> section.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#does-prefect-support-proxies","title":"Does Prefect support proxies?","text":"<p>Yes!</p> <p>Prefect supports communicating via proxies through the use of environment variables. You can read more about this in the Installation documentation and the article Using Prefect Cloud with proxies.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-run-prefect-flows-on-linux","title":"Can I run Prefect flows on Linux?","text":"<p>Yes! </p> <p>See the Installation documentation and Linux installation notes for details on getting started with Prefect on Linux.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-run-prefect-flows-on-windows","title":"Can I run Prefect flows on Windows?","text":"<p>Yes!</p> <p>See the Installation documentation and Windows installation notes for details on getting started with Prefect on Windows.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#what-external-requirements-does-prefect-have","title":"What external requirements does Prefect have?","text":"<p>Prefect does not have any additional requirements besides those installed by <code>pip install --pre prefect</code>. The entire system, including the UI and services, can be run in a single process via <code>prefect server start</code> and does not require Docker.</p> <p>Prefect Cloud users do not need to worry about the Prefect database. Prefect Cloud uses PostgreSQL on GCP behind the scenes. To use PostgreSQL with a self-hosted Prefect server, users must provide the connection string for a running database via the <code>PREFECT_API_DATABASE_CONNECTION_URL</code> environment variable.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#what-databases-does-prefect-support","title":"What databases does Prefect support?","text":"<p>A self-hosted Prefect server can work with SQLite and PostgreSQL. New Prefect installs default to a SQLite database hosted at <code>~/.prefect/prefect.db</code> on Mac or Linux machines. SQLite and PostgreSQL are not installed by Prefect.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#how-do-i-choose-between-sqlite-and-postgres","title":"How do I choose between SQLite and Postgres?","text":"<p>SQLite generally works well for getting started and exploring Prefect. We have tested it with up to hundreds of thousands of task runs. Many users may be able to stay on SQLite for some time. However, for production uses, Prefect Cloud or self-hosted PostgreSQL is highly recommended. Under write-heavy workloads, SQLite performance can begin to suffer. Users running many flows with high degrees of parallelism or concurrency should use PostgreSQL.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#relationship-with-other-prefect-products","title":"Relationship with other Prefect products","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-a-flow-written-with-prefect-1-be-orchestrated-with-prefect-2-and-vice-versa","title":"Can a flow written with Prefect 1 be orchestrated with Prefect 2 and vice versa?","text":"<p>No. Flows written with the Prefect 1 client must be rewritten with the Prefect 2 client. For most flows, this should take just a few minutes. </p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-use-prefect-1-and-prefect-2-at-the-same-time-on-my-local-machine","title":"Can I use Prefect 1 and Prefect 2 at the same time on my local machine?","text":"<p>Yes. Just use different virtual environments.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"api-ref/","title":"API Reference","text":"<p>Prefect auto-generates reference documentation for the following components:</p> <ul> <li>Prefect Python SDK: used to build, test, and execute workflows.</li> <li>Prefect REST API: used by both workflow clients as well as the Prefect UI for orchestration and data retrieval</li> <li>Prefect Cloud REST API documentation is available at https://app.prefect.cloud/api/docs.</li> <li>The REST API documentation for a locally hosted open-source Prefect server is available in the Prefect REST API Reference.</li> <li>Prefect Server SDK: used primarily by the server to work with workflow metadata and enforce orchestration logic. This is only used directly by Prefect developers and contributors.</li> </ul> <p>Self-hosted docs</p> <p>When self-hosting, you can access REST API documentation at the <code>/docs</code> endpoint of your <code>PREFECT_API_URL</code> - for example, if you ran <code>prefect server start</code> with no additional configuration you can find this reference at http://localhost:4200/docs.</p>","tags":["API","Prefect API","Prefect SDK","Prefect Cloud","REST API","development","orchestration"]},{"location":"api-ref/rest-api-reference/","title":"Prefect server REST API reference","text":"","tags":["REST API","Prefect server"]},{"location":"api-ref/prefect/agent/","title":"prefect.agent","text":"","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent","title":"<code>prefect.agent</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. Agents have been replaced by workers, which offer enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent","title":"<code>PrefectAgent</code>","text":"Source code in <code>prefect/agent.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use a worker instead. Refer to the upgrade guide for more information: https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass PrefectAgent:\n    def __init__(\n        self,\n        work_queues: List[str] = None,\n        work_queue_prefix: Union[str, List[str]] = None,\n        work_pool_name: str = None,\n        prefetch_seconds: int = None,\n        default_infrastructure: Infrastructure = None,\n        default_infrastructure_document_id: UUID = None,\n        limit: Optional[int] = None,\n    ) -&gt; None:\n        if default_infrastructure and default_infrastructure_document_id:\n            raise ValueError(\n                \"Provide only one of 'default_infrastructure' and\"\n                \" 'default_infrastructure_document_id'.\"\n            )\n\n        self.work_queues: Set[str] = set(work_queues) if work_queues else set()\n        self.work_pool_name = work_pool_name\n        self.prefetch_seconds = prefetch_seconds\n        self.submitting_flow_run_ids = set()\n        self.cancelling_flow_run_ids = set()\n        self.scheduled_task_scopes = set()\n        self.started = False\n        self.logger = get_logger(\"agent\")\n        self.task_group: Optional[anyio.abc.TaskGroup] = None\n        self.limit: Optional[int] = limit\n        self.limiter: Optional[anyio.CapacityLimiter] = None\n        self.client: Optional[PrefectClient] = None\n\n        if isinstance(work_queue_prefix, str):\n            work_queue_prefix = [work_queue_prefix]\n        self.work_queue_prefix = work_queue_prefix\n\n        self._work_queue_cache_expiration: pendulum.DateTime = None\n        self._work_queue_cache: List[WorkQueue] = []\n\n        if default_infrastructure:\n            self.default_infrastructure_document_id = (\n                default_infrastructure._block_document_id\n            )\n            self.default_infrastructure = default_infrastructure\n        elif default_infrastructure_document_id:\n            self.default_infrastructure_document_id = default_infrastructure_document_id\n            self.default_infrastructure = None\n        else:\n            self.default_infrastructure = Process()\n            self.default_infrastructure_document_id = None\n\n    async def update_matched_agent_work_queues(self):\n        if self.work_queue_prefix:\n            if self.work_pool_name:\n                matched_queues = await self.client.read_work_queues(\n                    work_pool_name=self.work_pool_name,\n                    work_queue_filter=WorkQueueFilter(\n                        name=WorkQueueFilterName(startswith_=self.work_queue_prefix)\n                    ),\n                )\n            else:\n                matched_queues = await self.client.match_work_queues(\n                    self.work_queue_prefix, work_pool_name=DEFAULT_AGENT_WORK_POOL_NAME\n                )\n\n            matched_queues = set(q.name for q in matched_queues)\n            if matched_queues != self.work_queues:\n                new_queues = matched_queues - self.work_queues\n                removed_queues = self.work_queues - matched_queues\n                if new_queues:\n                    self.logger.info(\n                        f\"Matched new work queues: {', '.join(new_queues)}\"\n                    )\n                if removed_queues:\n                    self.logger.info(\n                        f\"Work queues no longer matched: {', '.join(removed_queues)}\"\n                    )\n            self.work_queues = matched_queues\n\n    async def get_work_queues(self) -&gt; AsyncIterator[WorkQueue]:\n        \"\"\"\n        Loads the work queue objects corresponding to the agent's target work\n        queues. If any of them don't exist, they are created.\n        \"\"\"\n\n        # if the queue cache has not expired, yield queues from the cache\n        now = pendulum.now(\"UTC\")\n        if (self._work_queue_cache_expiration or now) &gt; now:\n            for queue in self._work_queue_cache:\n                yield queue\n            return\n\n        # otherwise clear the cache, set the expiration for 30 seconds, and\n        # reload the work queues\n        self._work_queue_cache.clear()\n        self._work_queue_cache_expiration = now.add(seconds=30)\n\n        await self.update_matched_agent_work_queues()\n\n        for name in self.work_queues:\n            try:\n                work_queue = await self.client.read_work_queue_by_name(\n                    work_pool_name=self.work_pool_name, name=name\n                )\n            except (ObjectNotFound, Exception):\n                work_queue = None\n\n            # if the work queue wasn't found and the agent is NOT polling\n            # for queues using a regex, try to create it\n            if work_queue is None and not self.work_queue_prefix:\n                try:\n                    work_queue = await self.client.create_work_queue(\n                        work_pool_name=self.work_pool_name, name=name\n                    )\n                except Exception:\n                    # if creating it raises an exception, it was probably just\n                    # created by some other agent; rather than entering a re-read\n                    # loop with new error handling, we log the exception and\n                    # continue.\n                    self.logger.exception(f\"Failed to create work queue {name!r}.\")\n                    continue\n                else:\n                    log_str = f\"Created work queue {name!r}\"\n                    if self.work_pool_name:\n                        log_str = (\n                            f\"Created work queue {name!r} in work pool\"\n                            f\" {self.work_pool_name!r}.\"\n                        )\n                    else:\n                        log_str = f\"Created work queue '{name}'.\"\n                    self.logger.info(log_str)\n\n            if work_queue is None:\n                self.logger.error(\n                    f\"Work queue '{name!r}' with prefix {self.work_queue_prefix} wasn't\"\n                    \" found\"\n                )\n            else:\n                self._work_queue_cache.append(work_queue)\n                yield work_queue\n\n    async def get_and_submit_flow_runs(self) -&gt; List[FlowRun]:\n        \"\"\"\n        The principle method on agents. Queries for scheduled flow runs and submits\n        them for execution in parallel.\n        \"\"\"\n        if not self.started:\n            raise RuntimeError(\n                \"Agent is not started. Use `async with PrefectAgent()...`\"\n            )\n\n        self.logger.debug(\"Checking for scheduled flow runs...\")\n\n        before = pendulum.now(\"utc\").add(\n            seconds=self.prefetch_seconds or PREFECT_AGENT_PREFETCH_SECONDS.value()\n        )\n\n        submittable_runs: List[FlowRun] = []\n\n        if self.work_pool_name:\n            responses = await self.client.get_scheduled_flow_runs_for_work_pool(\n                work_pool_name=self.work_pool_name,\n                work_queue_names=[wq.name async for wq in self.get_work_queues()],\n                scheduled_before=before,\n            )\n            submittable_runs.extend([response.flow_run for response in responses])\n\n        else:\n            # load runs from each work queue\n            async for work_queue in self.get_work_queues():\n                # print a nice message if the work queue is paused\n                if work_queue.is_paused:\n                    self.logger.info(\n                        f\"Work queue {work_queue.name!r} ({work_queue.id}) is paused.\"\n                    )\n\n                else:\n                    try:\n                        queue_runs = await self.client.get_runs_in_work_queue(\n                            id=work_queue.id, limit=10, scheduled_before=before\n                        )\n                        submittable_runs.extend(queue_runs)\n                    except ObjectNotFound:\n                        self.logger.error(\n                            f\"Work queue {work_queue.name!r} ({work_queue.id}) not\"\n                            \" found.\"\n                        )\n                    except Exception as exc:\n                        self.logger.exception(exc)\n\n            submittable_runs.sort(key=lambda run: run.next_scheduled_start_time)\n\n        for flow_run in submittable_runs:\n            # don't resubmit a run\n            if flow_run.id in self.submitting_flow_run_ids:\n                continue\n\n            try:\n                if self.limiter:\n                    self.limiter.acquire_on_behalf_of_nowait(flow_run.id)\n            except anyio.WouldBlock:\n                self.logger.info(\n                    f\"Flow run limit reached; {self.limiter.borrowed_tokens} flow runs\"\n                    \" in progress.\"\n                )\n                break\n            else:\n                self.logger.info(f\"Submitting flow run '{flow_run.id}'\")\n                self.submitting_flow_run_ids.add(flow_run.id)\n                self.task_group.start_soon(\n                    self.submit_run,\n                    flow_run,\n                )\n\n        return list(\n            filter(lambda run: run.id in self.submitting_flow_run_ids, submittable_runs)\n        )\n\n    async def check_for_cancelled_flow_runs(self):\n        if not self.started:\n            raise RuntimeError(\n                \"Agent is not started. Use `async with PrefectAgent()...`\"\n            )\n\n        self.logger.debug(\"Checking for cancelled flow runs...\")\n\n        work_queue_filter = (\n            WorkQueueFilter(name=WorkQueueFilterName(any_=list(self.work_queues)))\n            if self.work_queues\n            else None\n        )\n\n        work_pool_filter = (\n            WorkPoolFilter(name=WorkPoolFilterName(any_=[self.work_pool_name]))\n            if self.work_pool_name\n            else WorkPoolFilter(name=WorkPoolFilterName(any_=[\"default-agent-pool\"]))\n        )\n        named_cancelling_flow_runs = await self.client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self.cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=work_pool_filter,\n            work_queue_filter=work_queue_filter,\n        )\n\n        typed_cancelling_flow_runs = await self.client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self.cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=work_pool_filter,\n            work_queue_filter=work_queue_filter,\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self.logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self.cancelling_flow_run_ids.add(flow_run.id)\n            self.task_group.start_soon(self.cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def cancel_run(self, flow_run: FlowRun) -&gt; None:\n        \"\"\"\n        Cancel a flow run by killing its infrastructure\n        \"\"\"\n        if not flow_run.infrastructure_pid:\n            self.logger.error(\n                f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n                \" attached. Cancellation cannot be guaranteed.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure tracking information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            infrastructure = await self.get_infrastructure(flow_run)\n            if infrastructure.is_using_a_runner:\n                self.logger.info(\n                    f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                    \" using enhanced cancellation. A dedicated runner will handle\"\n                    \" cancellation.\"\n                )\n                return\n        except Exception:\n            self.logger.exception(\n                f\"Failed to get infrastructure for flow run '{flow_run.id}'. \"\n                \"Flow run cannot be cancelled.\"\n            )\n            # Note: We leave this flow run in the cancelling set because it cannot be\n            #       cancelled and this will prevent additional attempts.\n            return\n\n        if not hasattr(infrastructure, \"kill\"):\n            self.logger.error(\n                f\"Flow run '{flow_run.id}' infrastructure {infrastructure.type!r} \"\n                \"does not support killing created infrastructure. \"\n                \"Cancellation cannot be guaranteed.\"\n            )\n            return\n\n        self.logger.info(\n            f\"Killing {infrastructure.type} {flow_run.infrastructure_pid} for flow run \"\n            f\"'{flow_run.id}'...\"\n        )\n        try:\n            await infrastructure.kill(flow_run.infrastructure_pid)\n        except InfrastructureNotFound as exc:\n            self.logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except InfrastructureNotAvailable as exc:\n            self.logger.warning(f\"{exc} Flow run cannot be cancelled by this agent.\")\n        except Exception:\n            self.logger.exception(\n                \"Encountered exception while killing infrastructure for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self.cancelling_flow_run_ids.remove(flow_run.id)\n            return\n        else:\n            await self._mark_flow_run_as_cancelled(flow_run)\n            self.logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: FlowRun, state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self.client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self.cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def get_infrastructure(self, flow_run: FlowRun) -&gt; Infrastructure:\n        deployment = await self.client.read_deployment(flow_run.deployment_id)\n\n        flow = await self.client.read_flow(deployment.flow_id)\n\n        # overrides only apply when configuring known infra blocks\n        if not deployment.infrastructure_document_id:\n            if self.default_infrastructure:\n                infra_block = self.default_infrastructure\n            else:\n                infra_document = await self.client.read_block_document(\n                    self.default_infrastructure_document_id\n                )\n                infra_block = Block._from_block_document(infra_document)\n\n            # Add flow run metadata to the infrastructure\n            prepared_infrastructure = infra_block.prepare_for_flow_run(\n                flow_run, deployment=deployment, flow=flow\n            )\n            return prepared_infrastructure\n\n        ## get infra\n        infra_document = await self.client.read_block_document(\n            deployment.infrastructure_document_id\n        )\n\n        # this piece of logic applies any overrides that may have been set on the\n        # deployment; overrides are defined as dot.delimited paths on possibly nested\n        # attributes of the infrastructure block\n        doc_dict = infra_document.dict()\n        infra_dict = doc_dict.get(\"data\", {})\n        for override, value in (deployment.job_variables or {}).items():\n            nested_fields = override.split(\".\")\n            data = infra_dict\n            for field in nested_fields[:-1]:\n                data = data[field]\n\n            # once we reach the end, set the value\n            data[nested_fields[-1]] = value\n\n        # reconstruct the infra block\n        doc_dict[\"data\"] = infra_dict\n        infra_document = BlockDocument(**doc_dict)\n        infrastructure_block = Block._from_block_document(infra_document)\n\n        # TODO: Here the agent may update the infrastructure with agent-level settings\n\n        # Add flow run metadata to the infrastructure\n        prepared_infrastructure = infrastructure_block.prepare_for_flow_run(\n            flow_run, deployment=deployment, flow=flow\n        )\n\n        return prepared_infrastructure\n\n    async def submit_run(self, flow_run: FlowRun) -&gt; None:\n        \"\"\"\n        Submit a flow run to the infrastructure\n        \"\"\"\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            try:\n                infrastructure = await self.get_infrastructure(flow_run)\n            except Exception as exc:\n                self.logger.exception(\n                    f\"Failed to get infrastructure for flow run '{flow_run.id}'.\"\n                )\n                await self._propose_failed_state(flow_run, exc)\n                if self.limiter:\n                    self.limiter.release_on_behalf_of(flow_run.id)\n            else:\n                # Wait for submission to be completed. Note that the submission function\n                # may continue to run in the background after this exits.\n                readiness_result = await self.task_group.start(\n                    self._submit_run_and_capture_errors, flow_run, infrastructure\n                )\n\n                if readiness_result and not isinstance(readiness_result, Exception):\n                    try:\n                        await self.client.update_flow_run(\n                            flow_run_id=flow_run.id,\n                            infrastructure_pid=str(readiness_result),\n                        )\n                    except Exception:\n                        self.logger.exception(\n                            \"An error occurred while setting the `infrastructure_pid`\"\n                            f\" on flow run {flow_run.id!r}. The flow run will not be\"\n                            \" cancellable.\"\n                        )\n\n                self.logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n\n        self.submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self,\n        flow_run: FlowRun,\n        infrastructure: Infrastructure,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; Union[InfrastructureResult, Exception]:\n        # Note: There is not a clear way to determine if task_status.started() has been\n        #       called without peeking at the internal `_future`. Ideally we could just\n        #       check if the flow run id has been removed from `submitting_flow_run_ids`\n        #       but it is not so simple to guarantee that this coroutine yields back\n        #       to `submit_run` to execute that line when exceptions are raised during\n        #       submission.\n        try:\n            result = await infrastructure.run(task_status=task_status)\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                self.logger.exception(\n                    f\"Failed to submit flow run '{flow_run.id}' to infrastructure.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run could not be submitted to infrastructure\"\n                )\n            else:\n                self.logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n\n        if not task_status._future.done():\n            self.logger.error(\n                f\"Infrastructure returned without reporting flow run '{flow_run.id}' \"\n                \"as started or raising an error. This behavior is not expected and \"\n                \"generally indicates improper implementation of infrastructure. The \"\n                \"flow run will not be marked as failed, but an issue may have occurred.\"\n            )\n            # Mark the task as started to prevent agent crash\n            task_status.started()\n\n        if result.status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                (\n                    \"Flow run infrastructure exited with non-zero status code\"\n                    f\" {result.status_code}.\"\n                ),\n            )\n\n        return result\n\n    async def _propose_pending_state(self, flow_run: FlowRun) -&gt; bool:\n        state = flow_run.state\n        try:\n            state = await propose_state(self.client, Pending(), flow_run_id=flow_run.id)\n        except Abort as exc:\n            self.logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            self.logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n            return False\n\n        if not state.is_pending():\n            self.logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: FlowRun, exc: Exception) -&gt; None:\n        try:\n            await propose_state(\n                self.client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            self.logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: FlowRun, message: str) -&gt; None:\n        try:\n            state = await propose_state(\n                self.client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            self.logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                self.logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the agent exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.started:\n                with anyio.CancelScope() as scope:\n                    self.scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self.scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self.task_group.start(wrapper)\n\n    # Context management ---------------------------------------------------------------\n\n    async def start(self):\n        self.started = True\n        self.task_group = anyio.create_task_group()\n        self.limiter = (\n            anyio.CapacityLimiter(self.limit) if self.limit is not None else None\n        )\n        self.client = get_client()\n        await self.client.__aenter__()\n        await self.task_group.__aenter__()\n\n    async def shutdown(self, *exc_info):\n        self.started = False\n        # We must cancel scheduled task scopes before closing the task group\n        for scope in self.scheduled_task_scopes:\n            scope.cancel()\n        await self.task_group.__aexit__(*exc_info)\n        await self.client.__aexit__(*exc_info)\n        self.task_group = None\n        self.client = None\n        self.submitting_flow_run_ids.clear()\n        self.cancelling_flow_run_ids.clear()\n        self.scheduled_task_scopes.clear()\n        self._work_queue_cache_expiration = None\n        self._work_queue_cache = []\n\n    async def __aenter__(self):\n        await self.start()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        await self.shutdown(*exc_info)\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.cancel_run","title":"<code>cancel_run</code>  <code>async</code>","text":"<p>Cancel a flow run by killing its infrastructure</p> Source code in <code>prefect/agent.py</code> <pre><code>async def cancel_run(self, flow_run: FlowRun) -&gt; None:\n    \"\"\"\n    Cancel a flow run by killing its infrastructure\n    \"\"\"\n    if not flow_run.infrastructure_pid:\n        self.logger.error(\n            f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n            \" attached. Cancellation cannot be guaranteed.\"\n        )\n        await self._mark_flow_run_as_cancelled(\n            flow_run,\n            state_updates={\n                \"message\": (\n                    \"This flow run is missing infrastructure tracking information\"\n                    \" and cancellation cannot be guaranteed.\"\n                )\n            },\n        )\n        return\n\n    try:\n        infrastructure = await self.get_infrastructure(flow_run)\n        if infrastructure.is_using_a_runner:\n            self.logger.info(\n                f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                \" using enhanced cancellation. A dedicated runner will handle\"\n                \" cancellation.\"\n            )\n            return\n    except Exception:\n        self.logger.exception(\n            f\"Failed to get infrastructure for flow run '{flow_run.id}'. \"\n            \"Flow run cannot be cancelled.\"\n        )\n        # Note: We leave this flow run in the cancelling set because it cannot be\n        #       cancelled and this will prevent additional attempts.\n        return\n\n    if not hasattr(infrastructure, \"kill\"):\n        self.logger.error(\n            f\"Flow run '{flow_run.id}' infrastructure {infrastructure.type!r} \"\n            \"does not support killing created infrastructure. \"\n            \"Cancellation cannot be guaranteed.\"\n        )\n        return\n\n    self.logger.info(\n        f\"Killing {infrastructure.type} {flow_run.infrastructure_pid} for flow run \"\n        f\"'{flow_run.id}'...\"\n    )\n    try:\n        await infrastructure.kill(flow_run.infrastructure_pid)\n    except InfrastructureNotFound as exc:\n        self.logger.warning(f\"{exc} Marking flow run as cancelled.\")\n        await self._mark_flow_run_as_cancelled(flow_run)\n    except InfrastructureNotAvailable as exc:\n        self.logger.warning(f\"{exc} Flow run cannot be cancelled by this agent.\")\n    except Exception:\n        self.logger.exception(\n            \"Encountered exception while killing infrastructure for flow run \"\n            f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n        )\n        # We will try again on generic exceptions\n        self.cancelling_flow_run_ids.remove(flow_run.id)\n        return\n    else:\n        await self._mark_flow_run_as_cancelled(flow_run)\n        self.logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.get_and_submit_flow_runs","title":"<code>get_and_submit_flow_runs</code>  <code>async</code>","text":"<p>The principle method on agents. Queries for scheduled flow runs and submits them for execution in parallel.</p> Source code in <code>prefect/agent.py</code> <pre><code>async def get_and_submit_flow_runs(self) -&gt; List[FlowRun]:\n    \"\"\"\n    The principle method on agents. Queries for scheduled flow runs and submits\n    them for execution in parallel.\n    \"\"\"\n    if not self.started:\n        raise RuntimeError(\n            \"Agent is not started. Use `async with PrefectAgent()...`\"\n        )\n\n    self.logger.debug(\"Checking for scheduled flow runs...\")\n\n    before = pendulum.now(\"utc\").add(\n        seconds=self.prefetch_seconds or PREFECT_AGENT_PREFETCH_SECONDS.value()\n    )\n\n    submittable_runs: List[FlowRun] = []\n\n    if self.work_pool_name:\n        responses = await self.client.get_scheduled_flow_runs_for_work_pool(\n            work_pool_name=self.work_pool_name,\n            work_queue_names=[wq.name async for wq in self.get_work_queues()],\n            scheduled_before=before,\n        )\n        submittable_runs.extend([response.flow_run for response in responses])\n\n    else:\n        # load runs from each work queue\n        async for work_queue in self.get_work_queues():\n            # print a nice message if the work queue is paused\n            if work_queue.is_paused:\n                self.logger.info(\n                    f\"Work queue {work_queue.name!r} ({work_queue.id}) is paused.\"\n                )\n\n            else:\n                try:\n                    queue_runs = await self.client.get_runs_in_work_queue(\n                        id=work_queue.id, limit=10, scheduled_before=before\n                    )\n                    submittable_runs.extend(queue_runs)\n                except ObjectNotFound:\n                    self.logger.error(\n                        f\"Work queue {work_queue.name!r} ({work_queue.id}) not\"\n                        \" found.\"\n                    )\n                except Exception as exc:\n                    self.logger.exception(exc)\n\n        submittable_runs.sort(key=lambda run: run.next_scheduled_start_time)\n\n    for flow_run in submittable_runs:\n        # don't resubmit a run\n        if flow_run.id in self.submitting_flow_run_ids:\n            continue\n\n        try:\n            if self.limiter:\n                self.limiter.acquire_on_behalf_of_nowait(flow_run.id)\n        except anyio.WouldBlock:\n            self.logger.info(\n                f\"Flow run limit reached; {self.limiter.borrowed_tokens} flow runs\"\n                \" in progress.\"\n            )\n            break\n        else:\n            self.logger.info(f\"Submitting flow run '{flow_run.id}'\")\n            self.submitting_flow_run_ids.add(flow_run.id)\n            self.task_group.start_soon(\n                self.submit_run,\n                flow_run,\n            )\n\n    return list(\n        filter(lambda run: run.id in self.submitting_flow_run_ids, submittable_runs)\n    )\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.get_work_queues","title":"<code>get_work_queues</code>  <code>async</code>","text":"<p>Loads the work queue objects corresponding to the agent's target work queues. If any of them don't exist, they are created.</p> Source code in <code>prefect/agent.py</code> <pre><code>async def get_work_queues(self) -&gt; AsyncIterator[WorkQueue]:\n    \"\"\"\n    Loads the work queue objects corresponding to the agent's target work\n    queues. If any of them don't exist, they are created.\n    \"\"\"\n\n    # if the queue cache has not expired, yield queues from the cache\n    now = pendulum.now(\"UTC\")\n    if (self._work_queue_cache_expiration or now) &gt; now:\n        for queue in self._work_queue_cache:\n            yield queue\n        return\n\n    # otherwise clear the cache, set the expiration for 30 seconds, and\n    # reload the work queues\n    self._work_queue_cache.clear()\n    self._work_queue_cache_expiration = now.add(seconds=30)\n\n    await self.update_matched_agent_work_queues()\n\n    for name in self.work_queues:\n        try:\n            work_queue = await self.client.read_work_queue_by_name(\n                work_pool_name=self.work_pool_name, name=name\n            )\n        except (ObjectNotFound, Exception):\n            work_queue = None\n\n        # if the work queue wasn't found and the agent is NOT polling\n        # for queues using a regex, try to create it\n        if work_queue is None and not self.work_queue_prefix:\n            try:\n                work_queue = await self.client.create_work_queue(\n                    work_pool_name=self.work_pool_name, name=name\n                )\n            except Exception:\n                # if creating it raises an exception, it was probably just\n                # created by some other agent; rather than entering a re-read\n                # loop with new error handling, we log the exception and\n                # continue.\n                self.logger.exception(f\"Failed to create work queue {name!r}.\")\n                continue\n            else:\n                log_str = f\"Created work queue {name!r}\"\n                if self.work_pool_name:\n                    log_str = (\n                        f\"Created work queue {name!r} in work pool\"\n                        f\" {self.work_pool_name!r}.\"\n                    )\n                else:\n                    log_str = f\"Created work queue '{name}'.\"\n                self.logger.info(log_str)\n\n        if work_queue is None:\n            self.logger.error(\n                f\"Work queue '{name!r}' with prefix {self.work_queue_prefix} wasn't\"\n                \" found\"\n            )\n        else:\n            self._work_queue_cache.append(work_queue)\n            yield work_queue\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.submit_run","title":"<code>submit_run</code>  <code>async</code>","text":"<p>Submit a flow run to the infrastructure</p> Source code in <code>prefect/agent.py</code> <pre><code>async def submit_run(self, flow_run: FlowRun) -&gt; None:\n    \"\"\"\n    Submit a flow run to the infrastructure\n    \"\"\"\n    ready_to_submit = await self._propose_pending_state(flow_run)\n\n    if ready_to_submit:\n        try:\n            infrastructure = await self.get_infrastructure(flow_run)\n        except Exception as exc:\n            self.logger.exception(\n                f\"Failed to get infrastructure for flow run '{flow_run.id}'.\"\n            )\n            await self._propose_failed_state(flow_run, exc)\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n        else:\n            # Wait for submission to be completed. Note that the submission function\n            # may continue to run in the background after this exits.\n            readiness_result = await self.task_group.start(\n                self._submit_run_and_capture_errors, flow_run, infrastructure\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                try:\n                    await self.client.update_flow_run(\n                        flow_run_id=flow_run.id,\n                        infrastructure_pid=str(readiness_result),\n                    )\n                except Exception:\n                    self.logger.exception(\n                        \"An error occurred while setting the `infrastructure_pid`\"\n                        f\" on flow run {flow_run.id!r}. The flow run will not be\"\n                        \" cancellable.\"\n                    )\n\n            self.logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n    else:\n        # If the run is not ready to submit, release the concurrency slot\n        if self.limiter:\n            self.limiter.release_on_behalf_of(flow_run.id)\n\n    self.submitting_flow_run_ids.remove(flow_run.id)\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/artifacts/","title":"prefect.artifacts","text":"","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts","title":"<code>prefect.artifacts</code>","text":"<p>Interface for creating and reading artifacts.</p>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact","title":"<code>Artifact</code>","text":"<p>               Bases: <code>ArtifactCreate</code></p> <p>An artifact is a piece of data that is created by a flow or task run. https://docs.prefect.io/latest/concepts/artifacts/</p> <p>Parameters:</p> Name Type Description Default <code>type</code> <p>A string identifying the type of artifact.</p> required <code>key</code> <p>A user-provided string identifier. The key must only contain lowercase letters, numbers, and dashes.</p> required <code>description</code> <p>A user-specified description of the artifact.</p> required <code>data</code> <p>A JSON payload that allows for a result to be retrieved.</p> required Source code in <code>prefect/artifacts.py</code> <pre><code>class Artifact(ArtifactRequest):\n    \"\"\"\n    An artifact is a piece of data that is created by a flow or task run.\n    https://docs.prefect.io/latest/concepts/artifacts/\n\n    Arguments:\n        type: A string identifying the type of artifact.\n        key: A user-provided string identifier.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n        data: A JSON payload that allows for a result to be retrieved.\n    \"\"\"\n\n    @sync_compatible\n    async def create(\n        self: Self,\n        client: Optional[PrefectClient] = None,\n    ) -&gt; ArtifactResponse:\n        \"\"\"\n        A method to create an artifact.\n\n        Arguments:\n            client: The PrefectClient\n\n        Returns:\n            - The created artifact.\n        \"\"\"\n        client, _ = get_or_create_client(client)\n        task_run_id, flow_run_id = get_task_and_flow_run_ids()\n        return await client.create_artifact(\n            artifact=ArtifactRequest(\n                type=self.type,\n                key=self.key,\n                description=self.description,\n                task_run_id=self.task_run_id or task_run_id,\n                flow_run_id=self.flow_run_id or flow_run_id,\n                data=await self.format(),\n            )\n        )\n\n    @classmethod\n    @sync_compatible\n    async def get(\n        cls, key: Optional[str] = None, client: Optional[PrefectClient] = None\n    ) -&gt; Optional[ArtifactResponse]:\n        \"\"\"\n        A method to get an artifact.\n\n        Arguments:\n            key (str, optional): The key of the artifact to get.\n            client (PrefectClient, optional): The PrefectClient\n\n        Returns:\n            (ArtifactResponse, optional): The artifact (if found).\n        \"\"\"\n        client, _ = get_or_create_client(client)\n        return next(\n            iter(\n                await client.read_artifacts(\n                    limit=1,\n                    sort=ArtifactSort.UPDATED_DESC,\n                    artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n                )\n            ),\n            None,\n        )\n\n    @classmethod\n    @sync_compatible\n    async def get_or_create(\n        cls,\n        key: Optional[str] = None,\n        description: Optional[str] = None,\n        data: Optional[Union[Dict[str, Any], Any]] = None,\n        client: Optional[PrefectClient] = None,\n        **kwargs: Any,\n    ) -&gt; Tuple[ArtifactResponse, bool]:\n        \"\"\"\n        A method to get or create an artifact.\n\n        Arguments:\n            key (str, optional): The key of the artifact to get or create.\n            description (str, optional): The description of the artifact to create.\n            data (Union[Dict[str, Any], Any], optional): The data of the artifact to create.\n            client (PrefectClient, optional): The PrefectClient\n\n        Returns:\n            (ArtifactResponse): The artifact, either retrieved or created.\n        \"\"\"\n        artifact = await cls.get(key, client)\n        if artifact:\n            return artifact, False\n        else:\n            return (\n                await cls(key=key, description=description, data=data, **kwargs).create(\n                    client\n                ),\n                True,\n            )\n\n    async def format(self) -&gt; Optional[Union[Dict[str, Any], Any]]:\n        return json.dumps(self.data)\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.create","title":"<code>create</code>  <code>async</code>","text":"<p>A method to create an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>Optional[PrefectClient]</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>Artifact</code> <ul> <li>The created artifact.</li> </ul> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create(\n    self: Self,\n    client: Optional[PrefectClient] = None,\n) -&gt; ArtifactResponse:\n    \"\"\"\n    A method to create an artifact.\n\n    Arguments:\n        client: The PrefectClient\n\n    Returns:\n        - The created artifact.\n    \"\"\"\n    client, _ = get_or_create_client(client)\n    task_run_id, flow_run_id = get_task_and_flow_run_ids()\n    return await client.create_artifact(\n        artifact=ArtifactRequest(\n            type=self.type,\n            key=self.key,\n            description=self.description,\n            task_run_id=self.task_run_id or task_run_id,\n            flow_run_id=self.flow_run_id or flow_run_id,\n            data=await self.format(),\n        )\n    )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.get","title":"<code>get</code>  <code>async</code> <code>classmethod</code>","text":"<p>A method to get an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The key of the artifact to get.</p> <code>None</code> <code>client</code> <code>PrefectClient</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>(Artifact, optional)</code> <p>The artifact (if found).</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get(\n    cls, key: Optional[str] = None, client: Optional[PrefectClient] = None\n) -&gt; Optional[ArtifactResponse]:\n    \"\"\"\n    A method to get an artifact.\n\n    Arguments:\n        key (str, optional): The key of the artifact to get.\n        client (PrefectClient, optional): The PrefectClient\n\n    Returns:\n        (ArtifactResponse, optional): The artifact (if found).\n    \"\"\"\n    client, _ = get_or_create_client(client)\n    return next(\n        iter(\n            await client.read_artifacts(\n                limit=1,\n                sort=ArtifactSort.UPDATED_DESC,\n                artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n            )\n        ),\n        None,\n    )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.get_or_create","title":"<code>get_or_create</code>  <code>async</code> <code>classmethod</code>","text":"<p>A method to get or create an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The key of the artifact to get or create.</p> <code>None</code> <code>description</code> <code>str</code> <p>The description of the artifact to create.</p> <code>None</code> <code>data</code> <code>Union[Dict[str, Any], Any]</code> <p>The data of the artifact to create.</p> <code>None</code> <code>client</code> <code>PrefectClient</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>Artifact</code> <p>The artifact, either retrieved or created.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get_or_create(\n    cls,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n    data: Optional[Union[Dict[str, Any], Any]] = None,\n    client: Optional[PrefectClient] = None,\n    **kwargs: Any,\n) -&gt; Tuple[ArtifactResponse, bool]:\n    \"\"\"\n    A method to get or create an artifact.\n\n    Arguments:\n        key (str, optional): The key of the artifact to get or create.\n        description (str, optional): The description of the artifact to create.\n        data (Union[Dict[str, Any], Any], optional): The data of the artifact to create.\n        client (PrefectClient, optional): The PrefectClient\n\n    Returns:\n        (ArtifactResponse): The artifact, either retrieved or created.\n    \"\"\"\n    artifact = await cls.get(key, client)\n    if artifact:\n        return artifact, False\n    else:\n        return (\n            await cls(key=key, description=description, data=data, **kwargs).create(\n                client\n            ),\n            True,\n        )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.TableArtifact","title":"<code>TableArtifact</code>","text":"<p>               Bases: <code>Artifact</code></p> Source code in <code>prefect/artifacts.py</code> <pre><code>class TableArtifact(Artifact):\n    table: Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]]\n    type: Optional[str] = \"table\"\n\n    @classmethod\n    def _sanitize(\n        cls, item: Union[Dict[str, Any], List[Any], float]\n    ) -&gt; Union[Dict[str, Any], List[Any], int, float, None]:\n        \"\"\"\n        Sanitize NaN values in a given item.\n        The item can be a dict, list or float.\n        \"\"\"\n        if isinstance(item, list):\n            return [cls._sanitize(sub_item) for sub_item in item]\n        elif isinstance(item, dict):\n            return {k: cls._sanitize(v) for k, v in item.items()}\n        elif isinstance(item, float) and math.isnan(item):\n            return None\n        else:\n            return item\n\n    async def format(self) -&gt; str:\n        return json.dumps(self._sanitize(self.table))\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_link_artifact","title":"<code>create_link_artifact</code>  <code>async</code>","text":"<p>Create a link artifact.</p> <p>Parameters:</p> Name Type Description Default <code>link</code> <code>str</code> <p>The link to create.</p> required <code>link_text</code> <code>Optional[str]</code> <p>The link text.</p> <code>None</code> <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_link_artifact(\n    link: str,\n    link_text: Optional[str] = None,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n    client: Optional[PrefectClient] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a link artifact.\n\n    Arguments:\n        link: The link to create.\n        link_text: The link text.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n    artifact = await LinkArtifact(\n        key=key,\n        description=description,\n        link=link,\n        link_text=link_text,\n    ).create(client)\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_markdown_artifact","title":"<code>create_markdown_artifact</code>  <code>async</code>","text":"<p>Create a markdown artifact.</p> <p>Parameters:</p> Name Type Description Default <code>markdown</code> <code>str</code> <p>The markdown to create.</p> required <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_markdown_artifact(\n    markdown: str,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a markdown artifact.\n\n    Arguments:\n        markdown: The markdown to create.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n    artifact = await MarkdownArtifact(\n        key=key,\n        description=description,\n        markdown=markdown,\n    ).create()\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_table_artifact","title":"<code>create_table_artifact</code>  <code>async</code>","text":"<p>Create a table artifact.</p> <p>Parameters:</p> Name Type Description Default <code>table</code> <code>Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]]</code> <p>The table to create.</p> required <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_table_artifact(\n    table: Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]],\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a table artifact.\n\n    Arguments:\n        table: The table to create.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n\n    artifact = await TableArtifact(\n        key=key,\n        description=description,\n        table=table,\n    ).create()\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/automations/","title":"prefect.automations","text":"","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations","title":"<code>prefect.automations</code>","text":"","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation","title":"<code>Automation</code>","text":"<p>               Bases: <code>AutomationCore</code></p> Source code in <code>prefect/automations.py</code> <pre><code>class Automation(AutomationCore):\n    id: Optional[UUID] = Field(default=None, description=\"The ID of this automation\")\n\n    @sync_compatible\n    async def create(self: Self) -&gt; Self:\n        \"\"\"\n        Create a new automation.\n\n        auto_to_create = Automation(\n            name=\"woodchonk\",\n            trigger=EventTrigger(\n                expect={\"animal.walked\"},\n                match={\n                    \"genus\": \"Marmota\",\n                    \"species\": \"monax\",\n                },\n                posture=\"Reactive\",\n                threshold=3,\n                within=timedelta(seconds=10),\n            ),\n            actions=[CancelFlowRun()]\n        )\n        created_automation = auto_to_create.create()\n        \"\"\"\n        client, _ = get_or_create_client()\n        automation = AutomationCore(**self.dict(exclude={\"id\"}))\n        self.id = await client.create_automation(automation=automation)\n        return self\n\n    @sync_compatible\n    async def update(self: Self):\n        \"\"\"\n        Updates an existing automation.\n        auto = Automation.read(id=123)\n        auto.name = \"new name\"\n        auto.update()\n        \"\"\"\n\n        client, _ = get_or_create_client()\n        automation = AutomationCore(**self.dict(exclude={\"id\", \"owner_resource\"}))\n        await client.update_automation(automation_id=self.id, automation=automation)\n\n    @classmethod\n    @sync_compatible\n    async def read(\n        cls: Self, id: Optional[UUID] = None, name: Optional[str] = None\n    ) -&gt; Self:\n        \"\"\"\n        Read an automation by ID or name.\n        automation = Automation.read(name=\"woodchonk\")\n\n        or\n\n        automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))\n        \"\"\"\n        if id and name:\n            raise ValueError(\"Only one of id or name can be provided\")\n        if not id and not name:\n            raise ValueError(\"One of id or name must be provided\")\n        client, _ = get_or_create_client()\n        if id:\n            try:\n                automation = await client.read_automation(automation_id=id)\n            except PrefectHTTPStatusError as exc:\n                if exc.response.status_code == 404:\n                    raise ValueError(f\"Automation with ID {id!r} not found\")\n            return Automation(**automation.dict())\n        else:\n            automation = await client.read_automations_by_name(name=name)\n            if len(automation) &gt; 0:\n                return Automation(**automation[0].dict()) if automation else None\n            else:\n                raise ValueError(f\"Automation with name {name!r} not found\")\n\n    @sync_compatible\n    async def delete(self: Self) -&gt; bool:\n        \"\"\"\n        auto = Automation.read(id = 123)\n        auto.delete()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.delete_automation(self.id)\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n\n    @sync_compatible\n    async def disable(self: Self) -&gt; bool:\n        \"\"\"\n        Disable an automation.\n        auto = Automation.read(id = 123)\n        auto.disable()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.pause_automation(self.id)\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n\n    @sync_compatible\n    async def enable(self: Self) -&gt; bool:\n        \"\"\"\n        Enable an automation.\n        auto = Automation.read(id = 123)\n        auto.enable()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.resume_automation(\"asd\")\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new automation.</p> <p>auto_to_create = Automation(     name=\"woodchonk\",     trigger=EventTrigger(         expect={\"animal.walked\"},         match={             \"genus\": \"Marmota\",             \"species\": \"monax\",         },         posture=\"Reactive\",         threshold=3,         within=timedelta(seconds=10),     ),     actions=[CancelFlowRun()] ) created_automation = auto_to_create.create()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def create(self: Self) -&gt; Self:\n    \"\"\"\n    Create a new automation.\n\n    auto_to_create = Automation(\n        name=\"woodchonk\",\n        trigger=EventTrigger(\n            expect={\"animal.walked\"},\n            match={\n                \"genus\": \"Marmota\",\n                \"species\": \"monax\",\n            },\n            posture=\"Reactive\",\n            threshold=3,\n            within=timedelta(seconds=10),\n        ),\n        actions=[CancelFlowRun()]\n    )\n    created_automation = auto_to_create.create()\n    \"\"\"\n    client, _ = get_or_create_client()\n    automation = AutomationCore(**self.dict(exclude={\"id\"}))\n    self.id = await client.create_automation(automation=automation)\n    return self\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>auto = Automation.read(id = 123) auto.delete()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def delete(self: Self) -&gt; bool:\n    \"\"\"\n    auto = Automation.read(id = 123)\n    auto.delete()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.delete_automation(self.id)\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.disable","title":"<code>disable</code>  <code>async</code>","text":"<p>Disable an automation. auto = Automation.read(id = 123) auto.disable()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def disable(self: Self) -&gt; bool:\n    \"\"\"\n    Disable an automation.\n    auto = Automation.read(id = 123)\n    auto.disable()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.pause_automation(self.id)\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.enable","title":"<code>enable</code>  <code>async</code>","text":"<p>Enable an automation. auto = Automation.read(id = 123) auto.enable()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def enable(self: Self) -&gt; bool:\n    \"\"\"\n    Enable an automation.\n    auto = Automation.read(id = 123)\n    auto.enable()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.resume_automation(\"asd\")\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.read","title":"<code>read</code>  <code>async</code> <code>classmethod</code>","text":"<p>Read an automation by ID or name. automation = Automation.read(name=\"woodchonk\")</p> <p>or</p> <p>automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))</p> Source code in <code>prefect/automations.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def read(\n    cls: Self, id: Optional[UUID] = None, name: Optional[str] = None\n) -&gt; Self:\n    \"\"\"\n    Read an automation by ID or name.\n    automation = Automation.read(name=\"woodchonk\")\n\n    or\n\n    automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))\n    \"\"\"\n    if id and name:\n        raise ValueError(\"Only one of id or name can be provided\")\n    if not id and not name:\n        raise ValueError(\"One of id or name must be provided\")\n    client, _ = get_or_create_client()\n    if id:\n        try:\n            automation = await client.read_automation(automation_id=id)\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                raise ValueError(f\"Automation with ID {id!r} not found\")\n        return Automation(**automation.dict())\n    else:\n        automation = await client.read_automations_by_name(name=name)\n        if len(automation) &gt; 0:\n            return Automation(**automation[0].dict()) if automation else None\n        else:\n            raise ValueError(f\"Automation with name {name!r} not found\")\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.update","title":"<code>update</code>  <code>async</code>","text":"<p>Updates an existing automation. auto = Automation.read(id=123) auto.name = \"new name\" auto.update()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def update(self: Self):\n    \"\"\"\n    Updates an existing automation.\n    auto = Automation.read(id=123)\n    auto.name = \"new name\"\n    auto.update()\n    \"\"\"\n\n    client, _ = get_or_create_client()\n    automation = AutomationCore(**self.dict(exclude={\"id\", \"owner_resource\"}))\n    await client.update_automation(automation_id=self.id, automation=automation)\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.AutomationCore","title":"<code>AutomationCore</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines an action a user wants to take when a certain number of events do or don't happen to the matching resources</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class AutomationCore(PrefectBaseModel, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"Defines an action a user wants to take when a certain number of events\n    do or don't happen to the matching resources\"\"\"\n\n    name: str = Field(..., description=\"The name of this automation\")\n    description: str = Field(\"\", description=\"A longer description of this automation\")\n\n    enabled: bool = Field(True, description=\"Whether this automation will be evaluated\")\n\n    trigger: TriggerTypes = Field(\n        ...,\n        description=(\n            \"The criteria for which events this Automation covers and how it will \"\n            \"respond to the presence or absence of those events\"\n        ),\n    )\n\n    actions: List[ActionTypes] = Field(\n        ...,\n        description=\"The actions to perform when this Automation triggers\",\n    )\n\n    actions_on_trigger: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a triggered state\",\n    )\n\n    actions_on_resolve: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a resolving state\",\n    )\n\n    owner_resource: Optional[str] = Field(\n        default=None, description=\"The owning resource of this automation\"\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompositeTrigger","title":"<code>CompositeTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Requires some number of triggers to have fired within the given time period.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompositeTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Requires some number of triggers to have fired within the given time period.\n    \"\"\"\n\n    type: Literal[\"compound\", \"sequence\"]\n    triggers: List[\"TriggerTypes\"]\n    within: Optional[timedelta]\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompoundTrigger","title":"<code>CompoundTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompoundTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    type: Literal[\"compound\"] = \"compound\"\n    require: Union[int, Literal[\"any\", \"all\"]]\n\n    @root_validator\n    def validate_require(cls, values: Dict[str, Any]) -&gt; Dict[str, Any]:\n        require = values.get(\"require\")\n\n        if isinstance(require, int):\n            if require &lt; 1:\n                raise ValueError(\"required must be at least 1\")\n            if require &gt; len(values[\"triggers\"]):\n                raise ValueError(\n                    \"required must be less than or equal to the number of triggers\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"{str(self.require).capitalize()} of:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompoundTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"{str(self.require).capitalize()} of:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.EventTrigger","title":"<code>EventTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class EventTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    type: Literal[\"event\"] = \"event\"\n\n    after: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) which must first been seen to fire this trigger.  If \"\n            \"empty, then fire this trigger immediately.  Events may include \"\n            \"trailing wildcards, like `prefect.flow-run.*`\"\n        ),\n    )\n    expect: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) this trigger is expecting to see.  If empty, this \"\n            \"trigger will match any event.  Events may include trailing wildcards, \"\n            \"like `prefect.flow-run.*`\"\n        ),\n    )\n\n    for_each: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"Evaluate the trigger separately for each distinct value of these labels \"\n            \"on the resource.  By default, labels refer to the primary resource of the \"\n            \"triggering event.  You may also refer to labels from related \"\n            \"resources by specifying `related:&lt;role&gt;:&lt;label&gt;`.  This will use the \"\n            \"value of that label for the first related resource in that role.  For \"\n            'example, `\"for_each\": [\"related:flow:prefect.resource.id\"]` would '\n            \"evaluate the trigger for each flow.\"\n        ),\n    )\n    posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]\n        Posture.Reactive,\n        description=(\n            \"The posture of this trigger, either Reactive or Proactive.  Reactive \"\n            \"triggers respond to the _presence_ of the expected events, while \"\n            \"Proactive triggers respond to the _absence_ of those expected events.\"\n        ),\n    )\n    threshold: int = Field(\n        1,\n        description=(\n            \"The number of events required for this trigger to fire (for \"\n            \"Reactive triggers), or the number of events expected (for Proactive \"\n            \"triggers)\"\n        ),\n    )\n    within: timedelta = Field(\n        timedelta(0),\n        minimum=0.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The time period over which the events must occur.  For Reactive triggers, \"\n            \"this may be as low as 0 seconds, but must be at least 10 seconds for \"\n            \"Proactive triggers\"\n        ),\n    )\n\n    @validator(\"within\")\n    def enforce_minimum_within(\n        cls, value: timedelta, values, config, field: ModelField\n    ):\n        return validate_trigger_within(value, field)\n\n    @root_validator(skip_on_failure=True)\n    def enforce_minimum_within_for_proactive_triggers(cls, values: Dict[str, Any]):\n        posture: Optional[Posture] = values.get(\"posture\")\n        within: Optional[timedelta] = values.get(\"within\")\n\n        if posture == Posture.Proactive:\n            if not within or within == timedelta(0):\n                values[\"within\"] = timedelta(seconds=10.0)\n            elif within &lt; timedelta(seconds=10.0):\n                raise ValueError(\n                    \"The minimum within for Proactive triggers is 10 seconds\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        if self.posture == Posture.Reactive:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n        else:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                        f\"within {self.within}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.EventTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    if self.posture == Posture.Reactive:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n    else:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                    f\"within {self.within}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTrigger","title":"<code>MetricTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    type: Literal[\"metric\"] = \"metric\"\n\n    posture: Literal[Posture.Metric] = Field(  # type: ignore[valid-type]\n        Posture.Metric,\n        description=\"Periodically evaluate the configured metric query.\",\n    )\n\n    metric: MetricTriggerQuery = Field(\n        ...,\n        description=\"The metric query to evaluate for this trigger. \",\n    )\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        m = self.metric\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    m = self.metric\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTriggerQuery","title":"<code>MetricTriggerQuery</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines a subset of the Trigger subclass, which is specific to Metric automations, that specify the query configurations and breaching conditions for the Automation</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTriggerQuery(PrefectBaseModel):\n    \"\"\"Defines a subset of the Trigger subclass, which is specific\n    to Metric automations, that specify the query configurations\n    and breaching conditions for the Automation\"\"\"\n\n    name: PrefectMetric = Field(\n        ...,\n        description=\"The name of the metric to query.\",\n    )\n    threshold: float = Field(\n        ...,\n        description=(\n            \"The threshold value against which we'll compare \" \"the query result.\"\n        ),\n    )\n    operator: MetricTriggerOperator = Field(\n        ...,\n        description=(\n            \"The comparative operator (LT / LTE / GT / GTE) used to compare \"\n            \"the query result against the threshold value.\"\n        ),\n    )\n    range: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The lookback duration (seconds) for a metric query. This duration is \"\n            \"used to determine the time range over which the query will be executed. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n    firing_for: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The duration (seconds) for which the metric query must breach \"\n            \"or resolve continuously before the state is updated and the \"\n            \"automation is triggered. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.ResourceSpecification","title":"<code>ResourceSpecification</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation.  A resource must match at least one value of all of the provided labels</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ResourceSpecification(PrefectBaseModel):\n    \"\"\"A specification that may match zero, one, or many resources, used to target or\n    select a set of resources in a query or automation.  A resource must match at least\n    one value of all of the provided labels\"\"\"\n\n    __root__: Dict[str, Union[str, List[str]]]\n\n    def matches_every_resource(self) -&gt; bool:\n        return len(self) == 0\n\n    def matches_every_resource_of_kind(self, prefix: str) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        if len(self.__root__) == 1:\n            if resource_id := self.__root__.get(\"prefect.resource.id\"):\n                values = [resource_id] if isinstance(resource_id, str) else resource_id\n                return any(value == f\"{prefix}.*\" for value in values)\n\n        return False\n\n    def includes(self, candidates: Iterable[Resource]) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        for candidate in candidates:\n            if self.matches(candidate):\n                return True\n\n        return False\n\n    def matches(self, resource: Resource) -&gt; bool:\n        for label, expected in self.items():\n            value = resource.get(label)\n            if not any(matches(candidate, value) for candidate in expected):\n                return False\n        return True\n\n    def items(self) -&gt; Iterable[Tuple[str, List[str]]]:\n        return [\n            (label, [value] if isinstance(value, str) else value)\n            for label, value in self.__root__.items()\n        ]\n\n    def __contains__(self, key: str) -&gt; bool:\n        return self.__root__.__contains__(key)\n\n    def __getitem__(self, key: str) -&gt; List[str]:\n        value = self.__root__[key]\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def pop(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.pop(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def get(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.get(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def __len__(self) -&gt; int:\n        return len(self.__root__)\n\n    def deepcopy(self) -&gt; \"ResourceSpecification\":\n        return ResourceSpecification.parse_obj(copy.deepcopy(self.__root__))\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.ResourceTrigger","title":"<code>ResourceTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Base class for triggers that may filter by the labels of resources.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class ResourceTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Base class for triggers that may filter by the labels of resources.\n    \"\"\"\n\n    type: str\n\n    match: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for resources which this trigger will match.\",\n    )\n    match_related: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for related resources which this trigger will match.\",\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.SequenceTrigger","title":"<code>SequenceTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class SequenceTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    type: Literal[\"sequence\"] = \"sequence\"\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    \"In this order:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.SequenceTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                \"In this order:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Trigger","title":"<code>Trigger</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>Base class describing a set of criteria that must be satisfied in order to trigger an automation.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class Trigger(PrefectBaseModel, abc.ABC, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"\n    Base class describing a set of criteria that must be satisfied in order to trigger\n    an automation.\n    \"\"\"\n\n    type: str\n\n    @abc.abstractmethod\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n\n    # The following allows the regular Trigger class to be used when serving or\n    # deploying flows, analogous to how the Deployment*Trigger classes work\n\n    _deployment_id: Optional[UUID] = PrivateAttr(default=None)\n\n    def set_deployment_id(self, deployment_id: UUID):\n        self._deployment_id = deployment_id\n\n    def owner_resource(self) -&gt; Optional[str]:\n        return f\"prefect.deployment.{self._deployment_id}\"\n\n    def actions(self) -&gt; List[ActionTypes]:\n        assert self._deployment_id\n        return [\n            RunDeployment(\n                source=\"selected\",\n                deployment_id=self._deployment_id,\n                parameters=getattr(self, \"parameters\", None),\n                job_variables=getattr(self, \"job_variables\", None),\n            )\n        ]\n\n    def as_automation(self) -&gt; \"AutomationCore\":\n        assert self._deployment_id\n\n        trigger: TriggerTypes = cast(TriggerTypes, self)\n\n        # This is one of the Deployment*Trigger classes, so translate it over to a\n        # plain Trigger\n        if hasattr(self, \"trigger_type\"):\n            trigger = self.trigger_type(**self.dict())\n\n        return AutomationCore(\n            name=(\n                getattr(self, \"name\", None)\n                or f\"Automation for deployment {self._deployment_id}\"\n            ),\n            description=\"\",\n            enabled=getattr(self, \"enabled\", True),\n            trigger=trigger,\n            actions=self.actions(),\n            owner_resource=self.owner_resource(),\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Trigger.describe_for_cli","title":"<code>describe_for_cli</code>  <code>abstractmethod</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>@abc.abstractmethod\ndef describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/context/","title":"prefect.context","text":"","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context","title":"<code>prefect.context</code>","text":"<p>Async and thread safe models for passing runtime context data.</p> <p>These contexts should never be directly mutated by the user.</p> <p>For more user-accessible information about the current run, see <code>prefect.runtime</code>.</p>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.ContextModel","title":"<code>ContextModel</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A base model for context data that forbids mutation and extra data while providing a context manager</p> Source code in <code>prefect/context.py</code> <pre><code>class ContextModel(BaseModel):\n    \"\"\"\n    A base model for context data that forbids mutation and extra data while providing\n    a context manager\n    \"\"\"\n\n    # The context variable for storing data must be defined by the child class\n    __var__: ContextVar\n    _token: Token = PrivateAttr(None)\n\n    class Config:\n        # allow_mutation = False\n        arbitrary_types_allowed = True\n        extra = \"forbid\"\n\n    def __enter__(self):\n        if self._token is not None:\n            raise RuntimeError(\n                \"Context already entered. Context enter calls cannot be nested.\"\n            )\n        self._token = self.__var__.set(self)\n        return self\n\n    def __exit__(self, *_):\n        if not self._token:\n            raise RuntimeError(\n                \"Asymmetric use of context. Context exit called without an enter.\"\n            )\n        self.__var__.reset(self._token)\n        self._token = None\n\n    @classmethod\n    def get(cls: Type[T]) -&gt; Optional[T]:\n        return cls.__var__.get(None)\n\n    def copy(self, **kwargs):\n        \"\"\"\n        Duplicate the context model, optionally choosing which fields to include, exclude, or change.\n\n        Attributes:\n            include: Fields to include in new model.\n            exclude: Fields to exclude from new model, as with values this takes precedence over include.\n            update: Values to change/add in the new model. Note: the data is not validated before creating\n                the new model - you should trust this data.\n            deep: Set to `True` to make a deep copy of the model.\n\n        Returns:\n            A new model instance.\n        \"\"\"\n        # Remove the token on copy to avoid re-entrance errors\n        new = super().copy(**kwargs)\n        new._token = None\n        return new\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.ContextModel.copy","title":"<code>copy</code>","text":"<p>Duplicate the context model, optionally choosing which fields to include, exclude, or change.</p> <p>Attributes:</p> Name Type Description <code>include</code> <p>Fields to include in new model.</p> <code>exclude</code> <p>Fields to exclude from new model, as with values this takes precedence over include.</p> <code>update</code> <p>Values to change/add in the new model. Note: the data is not validated before creating the new model - you should trust this data.</p> <code>deep</code> <p>Set to <code>True</code> to make a deep copy of the model.</p> <p>Returns:</p> Type Description <p>A new model instance.</p> Source code in <code>prefect/context.py</code> <pre><code>def copy(self, **kwargs):\n    \"\"\"\n    Duplicate the context model, optionally choosing which fields to include, exclude, or change.\n\n    Attributes:\n        include: Fields to include in new model.\n        exclude: Fields to exclude from new model, as with values this takes precedence over include.\n        update: Values to change/add in the new model. Note: the data is not validated before creating\n            the new model - you should trust this data.\n        deep: Set to `True` to make a deep copy of the model.\n\n    Returns:\n        A new model instance.\n    \"\"\"\n    # Remove the token on copy to avoid re-entrance errors\n    new = super().copy(**kwargs)\n    new._token = None\n    return new\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.EngineContext","title":"<code>EngineContext</code>","text":"<p>               Bases: <code>RunContext</code></p> <p>The context for a flow run. Data in this context is only available from within a flow run function.</p> <p>Attributes:</p> Name Type Description <code>flow</code> <code>Optional[Flow]</code> <p>The flow instance associated with the run</p> <code>flow_run</code> <code>Optional[FlowRun]</code> <p>The API metadata for the flow run</p> <code>task_runner</code> <code>BaseTaskRunner</code> <p>The task runner instance being used for the flow run</p> <code>task_run_futures</code> <code>List[PrefectFuture]</code> <p>A list of futures for task runs submitted within this flow run</p> <code>task_run_states</code> <code>List[State]</code> <p>A list of states for task runs created within this flow run</p> <code>task_run_results</code> <code>Dict[int, State]</code> <p>A mapping of result ids to task run states for this flow run</p> <code>flow_run_states</code> <code>List[State]</code> <p>A list of states for flow runs created within this flow run</p> <code>sync_portal</code> <code>Optional[BlockingPortal]</code> <p>A blocking portal for sync task/flow runs in an async flow</p> <code>timeout_scope</code> <code>Optional[CancelScope]</code> <p>The cancellation scope for flow level timeouts</p> Source code in <code>prefect/context.py</code> <pre><code>class EngineContext(RunContext):\n    \"\"\"\n    The context for a flow run. Data in this context is only available from within a\n    flow run function.\n\n    Attributes:\n        flow: The flow instance associated with the run\n        flow_run: The API metadata for the flow run\n        task_runner: The task runner instance being used for the flow run\n        task_run_futures: A list of futures for task runs submitted within this flow run\n        task_run_states: A list of states for task runs created within this flow run\n        task_run_results: A mapping of result ids to task run states for this flow run\n        flow_run_states: A list of states for flow runs created within this flow run\n        sync_portal: A blocking portal for sync task/flow runs in an async flow\n        timeout_scope: The cancellation scope for flow level timeouts\n    \"\"\"\n\n    flow: Optional[\"Flow\"] = None\n    flow_run: Optional[FlowRun] = None\n    autonomous_task_run: Optional[TaskRun] = None\n    task_runner: BaseTaskRunner\n    log_prints: bool = False\n    parameters: Optional[Dict[str, Any]] = None\n\n    # Result handling\n    result_factory: ResultFactory\n\n    # Counter for task calls allowing unique\n    task_run_dynamic_keys: Dict[str, int] = Field(default_factory=dict)\n\n    # Counter for flow pauses\n    observed_flow_pauses: Dict[str, int] = Field(default_factory=dict)\n\n    # Tracking for objects created by this flow run\n    task_run_futures: List[PrefectFuture] = Field(default_factory=list)\n    task_run_states: List[State] = Field(default_factory=list)\n    task_run_results: Dict[int, State] = Field(default_factory=dict)\n    flow_run_states: List[State] = Field(default_factory=list)\n\n    # The synchronous portal is only created for async flows for creating engine calls\n    # from synchronous task and subflow calls\n    sync_portal: Optional[anyio.abc.BlockingPortal] = None\n    timeout_scope: Optional[anyio.abc.CancelScope] = None\n\n    # Task group that can be used for background tasks during the flow run\n    background_tasks: anyio.abc.TaskGroup\n\n    # Events worker to emit events to Prefect Cloud\n    events: Optional[EventsWorker] = None\n\n    __var__ = ContextVar(\"flow_run\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.PrefectObjectRegistry","title":"<code>PrefectObjectRegistry</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>A context that acts as a registry for all Prefect objects that are registered during load and execution.</p> <p>Attributes:</p> Name Type Description <code>start_time</code> <code>DateTimeTZ</code> <p>The time the object registry was created.</p> <code>block_code_execution</code> <code>bool</code> <p>If set, flow calls will be ignored.</p> <code>capture_failures</code> <code>bool</code> <p>If set, failures during init will be silenced and tracked.</p> Source code in <code>prefect/context.py</code> <pre><code>class PrefectObjectRegistry(ContextModel):\n    \"\"\"\n    A context that acts as a registry for all Prefect objects that are\n    registered during load and execution.\n\n    Attributes:\n        start_time: The time the object registry was created.\n        block_code_execution: If set, flow calls will be ignored.\n        capture_failures: If set, failures during __init__ will be silenced and tracked.\n    \"\"\"\n\n    start_time: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n\n    _instance_registry: Dict[Type[T], List[T]] = PrivateAttr(\n        default_factory=lambda: defaultdict(list)\n    )\n\n    # Failures will be a tuple of (exception, instance, args, kwargs)\n    _instance_init_failures: Dict[\n        Type[T], List[Tuple[Exception, T, Tuple, Dict]]\n    ] = PrivateAttr(default_factory=lambda: defaultdict(list))\n\n    block_code_execution: bool = False\n    capture_failures: bool = False\n\n    __var__ = ContextVar(\"object_registry\")\n\n    def get_instances(self, type_: Type[T]) -&gt; List[T]:\n        instances = []\n        for registered_type, type_instances in self._instance_registry.items():\n            if type_ in registered_type.mro():\n                instances.extend(type_instances)\n        return instances\n\n    def get_instance_failures(\n        self, type_: Type[T]\n    ) -&gt; List[Tuple[Exception, T, Tuple, Dict]]:\n        failures = []\n        for type__ in type_.mro():\n            failures.extend(self._instance_init_failures[type__])\n        return failures\n\n    def register_instance(self, object):\n        # TODO: Consider using a 'Set' to avoid duplicate entries\n        self._instance_registry[type(object)].append(object)\n\n    def register_init_failure(\n        self, exc: Exception, object: Any, init_args: Tuple, init_kwargs: Dict\n    ):\n        self._instance_init_failures[type(object)].append(\n            (exc, object, init_args, init_kwargs)\n        )\n\n    @classmethod\n    def register_instances(cls, type_: Type[T]) -&gt; Type[T]:\n        \"\"\"\n        Decorator for a class that adds registration to the `PrefectObjectRegistry`\n        on initialization of instances.\n        \"\"\"\n        original_init = type_.__init__\n\n        def __register_init__(__self__: T, *args: Any, **kwargs: Any) -&gt; None:\n            registry = cls.get()\n            try:\n                original_init(__self__, *args, **kwargs)\n            except Exception as exc:\n                if not registry or not registry.capture_failures:\n                    raise\n                else:\n                    registry.register_init_failure(exc, __self__, args, kwargs)\n            else:\n                if registry:\n                    registry.register_instance(__self__)\n\n        update_wrapper(__register_init__, original_init)\n\n        type_.__init__ = __register_init__\n        return type_\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.PrefectObjectRegistry.register_instances","title":"<code>register_instances</code>  <code>classmethod</code>","text":"<p>Decorator for a class that adds registration to the <code>PrefectObjectRegistry</code> on initialization of instances.</p> Source code in <code>prefect/context.py</code> <pre><code>@classmethod\ndef register_instances(cls, type_: Type[T]) -&gt; Type[T]:\n    \"\"\"\n    Decorator for a class that adds registration to the `PrefectObjectRegistry`\n    on initialization of instances.\n    \"\"\"\n    original_init = type_.__init__\n\n    def __register_init__(__self__: T, *args: Any, **kwargs: Any) -&gt; None:\n        registry = cls.get()\n        try:\n            original_init(__self__, *args, **kwargs)\n        except Exception as exc:\n            if not registry or not registry.capture_failures:\n                raise\n            else:\n                registry.register_init_failure(exc, __self__, args, kwargs)\n        else:\n            if registry:\n                registry.register_instance(__self__)\n\n    update_wrapper(__register_init__, original_init)\n\n    type_.__init__ = __register_init__\n    return type_\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.RunContext","title":"<code>RunContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The base context for a flow or task run. Data in this context will always be available when <code>get_run_context</code> is called.</p> <p>Attributes:</p> Name Type Description <code>start_time</code> <code>DateTimeTZ</code> <p>The time the run context was entered</p> <code>client</code> <code>Union[PrefectClient, SyncPrefectClient]</code> <p>The Prefect client instance being used for API communication</p> Source code in <code>prefect/context.py</code> <pre><code>class RunContext(ContextModel):\n    \"\"\"\n    The base context for a flow or task run. Data in this context will always be\n    available when `get_run_context` is called.\n\n    Attributes:\n        start_time: The time the run context was entered\n        client: The Prefect client instance being used for API communication\n    \"\"\"\n\n    start_time: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    input_keyset: Optional[Dict[str, Dict[str, str]]] = None\n    client: Union[PrefectClient, SyncPrefectClient]\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.SettingsContext","title":"<code>SettingsContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The context for a Prefect settings.</p> <p>This allows for safe concurrent access and modification of settings.</p> <p>Attributes:</p> Name Type Description <code>profile</code> <code>Profile</code> <p>The profile that is in use.</p> <code>settings</code> <code>Settings</code> <p>The complete settings model.</p> Source code in <code>prefect/context.py</code> <pre><code>class SettingsContext(ContextModel):\n    \"\"\"\n    The context for a Prefect settings.\n\n    This allows for safe concurrent access and modification of settings.\n\n    Attributes:\n        profile: The profile that is in use.\n        settings: The complete settings model.\n    \"\"\"\n\n    profile: Profile\n    settings: Settings\n\n    __var__ = ContextVar(\"settings\")\n\n    def __hash__(self) -&gt; int:\n        return hash(self.settings)\n\n    def __enter__(self):\n        \"\"\"\n        Upon entrance, we ensure the home directory for the profile exists.\n        \"\"\"\n        return_value = super().__enter__()\n\n        try:\n            prefect_home = Path(self.settings.value_of(PREFECT_HOME))\n            prefect_home.mkdir(mode=0o0700, exist_ok=True)\n        except OSError:\n            warnings.warn(\n                (\n                    \"Failed to create the Prefect home directory at \"\n                    f\"{self.settings.value_of(PREFECT_HOME)}\"\n                ),\n                stacklevel=2,\n            )\n\n        return return_value\n\n    @classmethod\n    def get(cls) -&gt; \"SettingsContext\":\n        # Return the global context instead of `None` if no context exists\n        return super().get() or GLOBAL_SETTINGS_CONTEXT\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.TagsContext","title":"<code>TagsContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The context for <code>prefect.tags</code> management.</p> <p>Attributes:</p> Name Type Description <code>current_tags</code> <code>Set[str]</code> <p>A set of current tags in the context</p> Source code in <code>prefect/context.py</code> <pre><code>class TagsContext(ContextModel):\n    \"\"\"\n    The context for `prefect.tags` management.\n\n    Attributes:\n        current_tags: A set of current tags in the context\n    \"\"\"\n\n    current_tags: Set[str] = Field(default_factory=set)\n\n    @classmethod\n    def get(cls) -&gt; \"TagsContext\":\n        # Return an empty `TagsContext` instead of `None` if no context exists\n        return cls.__var__.get(TagsContext())\n\n    __var__ = ContextVar(\"tags\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.TaskRunContext","title":"<code>TaskRunContext</code>","text":"<p>               Bases: <code>RunContext</code></p> <p>The context for a task run. Data in this context is only available from within a task run function.</p> <p>Attributes:</p> Name Type Description <code>task</code> <code>Task</code> <p>The task instance associated with the task run</p> <code>task_run</code> <code>TaskRun</code> <p>The API metadata for this task run</p> Source code in <code>prefect/context.py</code> <pre><code>class TaskRunContext(RunContext):\n    \"\"\"\n    The context for a task run. Data in this context is only available from within a\n    task run function.\n\n    Attributes:\n        task: The task instance associated with the task run\n        task_run: The API metadata for this task run\n    \"\"\"\n\n    task: \"Task\"\n    task_run: TaskRun\n    log_prints: bool = False\n    parameters: Dict[str, Any]\n\n    # Result handling\n    result_factory: ResultFactory\n\n    __var__ = ContextVar(\"task_run\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.get_run_context","title":"<code>get_run_context</code>","text":"<p>Get the current run context from within a task or flow function.</p> <p>Returns:</p> Type Description <code>Union[FlowRunContext, TaskRunContext]</code> <p>A <code>FlowRunContext</code> or <code>TaskRunContext</code> depending on the function type.</p> <p>Raises     RuntimeError: If called outside of a flow or task run.</p> Source code in <code>prefect/context.py</code> <pre><code>def get_run_context() -&gt; Union[FlowRunContext, TaskRunContext]:\n    \"\"\"\n    Get the current run context from within a task or flow function.\n\n    Returns:\n        A `FlowRunContext` or `TaskRunContext` depending on the function type.\n\n    Raises\n        RuntimeError: If called outside of a flow or task run.\n    \"\"\"\n    task_run_ctx = TaskRunContext.get()\n    if task_run_ctx:\n        return task_run_ctx\n\n    flow_run_ctx = FlowRunContext.get()\n    if flow_run_ctx:\n        return flow_run_ctx\n\n    raise MissingContextError(\n        \"No run context available. You are not in a flow or task run context.\"\n    )\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.get_settings_context","title":"<code>get_settings_context</code>","text":"<p>Get the current settings context which contains profile information and the settings that are being used.</p> <p>Generally, the settings that are being used are a combination of values from the profile and environment. See <code>prefect.context.use_profile</code> for more details.</p> Source code in <code>prefect/context.py</code> <pre><code>def get_settings_context() -&gt; SettingsContext:\n    \"\"\"\n    Get the current settings context which contains profile information and the\n    settings that are being used.\n\n    Generally, the settings that are being used are a combination of values from the\n    profile and environment. See `prefect.context.use_profile` for more details.\n    \"\"\"\n    settings_ctx = SettingsContext.get()\n\n    if not settings_ctx:\n        raise MissingContextError(\"No settings context found.\")\n\n    return settings_ctx\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.registry_from_script","title":"<code>registry_from_script</code>","text":"<p>Return a fresh registry with instances populated from execution of a script.</p> Source code in <code>prefect/context.py</code> <pre><code>def registry_from_script(\n    path: str,\n    block_code_execution: bool = True,\n    capture_failures: bool = True,\n) -&gt; PrefectObjectRegistry:\n    \"\"\"\n    Return a fresh registry with instances populated from execution of a script.\n    \"\"\"\n    with PrefectObjectRegistry(\n        block_code_execution=block_code_execution,\n        capture_failures=capture_failures,\n    ) as registry:\n        load_script_as_module(path)\n\n    return registry\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.root_settings_context","title":"<code>root_settings_context</code>","text":"<p>Return the settings context that will exist as the root context for the module.</p> <p>The profile to use is determined with the following precedence - Command line via 'prefect --profile ' - Environment variable via 'PREFECT_PROFILE' - Profiles file via the 'active' key Source code in <code>prefect/context.py</code> <pre><code>def root_settings_context():\n    \"\"\"\n    Return the settings context that will exist as the root context for the module.\n\n    The profile to use is determined with the following precedence\n    - Command line via 'prefect --profile &lt;name&gt;'\n    - Environment variable via 'PREFECT_PROFILE'\n    - Profiles file via the 'active' key\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    active_name = profiles.active_name\n    profile_source = \"in the profiles file\"\n\n    if \"PREFECT_PROFILE\" in os.environ:\n        active_name = os.environ[\"PREFECT_PROFILE\"]\n        profile_source = \"by environment variable\"\n\n    if (\n        sys.argv[0].endswith(\"/prefect\")\n        and len(sys.argv) &gt;= 3\n        and sys.argv[1] == \"--profile\"\n    ):\n        active_name = sys.argv[2]\n        profile_source = \"by command line argument\"\n\n    if active_name not in profiles.names:\n        print(\n            (\n                f\"WARNING: Active profile {active_name!r} set {profile_source} not \"\n                \"found. The default profile will be used instead. \"\n            ),\n            file=sys.stderr,\n        )\n        active_name = \"default\"\n\n    with use_profile(\n        profiles[active_name],\n        # Override environment variables if the profile was set by the CLI\n        override_environment_variables=profile_source == \"by command line argument\",\n    ) as settings_context:\n        return settings_context\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.tags","title":"<code>tags</code>","text":"<p>Context manager to add tags to flow and task run calls.</p> <p>Tags are always combined with any existing tags.</p> <p>Yields:</p> Type Description <code>Set[str]</code> <p>The current set of tags</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect import tags, task, flow\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Run a task with tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"a\", \"b\"):\n&gt;&gt;&gt;         my_task()  # has tags: a, b\n</code></pre> <p>Run a flow with tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt; with tags(\"a\", \"b\"):\n&gt;&gt;&gt;     my_flow()  # has tags: a, b\n</code></pre> <p>Run a task with nested tag contexts</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"a\", \"b\"):\n&gt;&gt;&gt;         with tags(\"c\", \"d\"):\n&gt;&gt;&gt;             my_task()  # has tags: a, b, c, d\n&gt;&gt;&gt;         my_task()  # has tags: a, b\n</code></pre> <p>Inspect the current tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"c\", \"d\"):\n&gt;&gt;&gt;         with tags(\"e\", \"f\") as current_tags:\n&gt;&gt;&gt;              print(current_tags)\n&gt;&gt;&gt; with tags(\"a\", \"b\"):\n&gt;&gt;&gt;     my_flow()\n{\"a\", \"b\", \"c\", \"d\", \"e\", \"f\"}\n</code></pre> Source code in <code>prefect/context.py</code> <pre><code>@contextmanager\ndef tags(*new_tags: str) -&gt; Generator[Set[str], None, None]:\n    \"\"\"\n    Context manager to add tags to flow and task run calls.\n\n    Tags are always combined with any existing tags.\n\n    Yields:\n        The current set of tags\n\n    Examples:\n        &gt;&gt;&gt; from prefect import tags, task, flow\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Run a task with tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;         my_task()  # has tags: a, b\n\n        Run a flow with tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt; with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;     my_flow()  # has tags: a, b\n\n        Run a task with nested tag contexts\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;         with tags(\"c\", \"d\"):\n        &gt;&gt;&gt;             my_task()  # has tags: a, b, c, d\n        &gt;&gt;&gt;         my_task()  # has tags: a, b\n\n        Inspect the current tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"c\", \"d\"):\n        &gt;&gt;&gt;         with tags(\"e\", \"f\") as current_tags:\n        &gt;&gt;&gt;              print(current_tags)\n        &gt;&gt;&gt; with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;     my_flow()\n        {\"a\", \"b\", \"c\", \"d\", \"e\", \"f\"}\n    \"\"\"\n    current_tags = TagsContext.get().current_tags\n    new_tags = current_tags.union(new_tags)\n    with TagsContext(current_tags=new_tags):\n        yield new_tags\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.use_profile","title":"<code>use_profile</code>","text":"<p>Switch to a profile for the duration of this context.</p> <p>Profile contexts are confined to an async context in a single thread.</p> <p>Parameters:</p> Name Type Description Default <code>profile</code> <code>Union[Profile, str]</code> <p>The name of the profile to load or an instance of a Profile.</p> required <code>override_environment_variable</code> <p>If set, variables in the profile will take precedence over current environment variables. By default, environment variables will override profile settings.</p> required <code>include_current_context</code> <code>bool</code> <p>If set, the new settings will be constructed with the current settings context as a base. If not set, the use_base settings will be loaded from the environment and defaults.</p> <code>True</code> <p>Yields:</p> Type Description <p>The created <code>SettingsContext</code> object</p> Source code in <code>prefect/context.py</code> <pre><code>@contextmanager\ndef use_profile(\n    profile: Union[Profile, str],\n    override_environment_variables: bool = False,\n    include_current_context: bool = True,\n):\n    \"\"\"\n    Switch to a profile for the duration of this context.\n\n    Profile contexts are confined to an async context in a single thread.\n\n    Args:\n        profile: The name of the profile to load or an instance of a Profile.\n        override_environment_variable: If set, variables in the profile will take\n            precedence over current environment variables. By default, environment\n            variables will override profile settings.\n        include_current_context: If set, the new settings will be constructed\n            with the current settings context as a base. If not set, the use_base settings\n            will be loaded from the environment and defaults.\n\n    Yields:\n        The created `SettingsContext` object\n    \"\"\"\n    if isinstance(profile, str):\n        profiles = prefect.settings.load_profiles()\n        profile = profiles[profile]\n\n    if not isinstance(profile, Profile):\n        raise TypeError(\n            f\"Unexpected type {type(profile).__name__!r} for `profile`. \"\n            \"Expected 'str' or 'Profile'.\"\n        )\n\n    # Create a copy of the profiles settings as we will mutate it\n    profile_settings = profile.settings.copy()\n\n    existing_context = SettingsContext.get()\n    if existing_context and include_current_context:\n        settings = existing_context.settings\n    else:\n        settings = prefect.settings.get_settings_from_env()\n\n    if not override_environment_variables:\n        for key in os.environ:\n            if key in prefect.settings.SETTING_VARIABLES:\n                profile_settings.pop(prefect.settings.SETTING_VARIABLES[key], None)\n\n    new_settings = settings.copy_with_update(updates=profile_settings)\n\n    with SettingsContext(profile=profile, settings=new_settings) as ctx:\n        yield ctx\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/engine/","title":"prefect.engine","text":"","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine","title":"<code>prefect.engine</code>","text":"<p>Client-side execution and orchestration of flows and tasks.</p>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--engine-process-overview","title":"Engine process overview","text":"","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--flows","title":"Flows","text":"<ul> <li> <p>The flow is called by the user or an existing flow run is executed in a new process.</p> <p>See <code>Flow.__call__</code> and <code>prefect.engine.__main__</code> (<code>python -m prefect.engine</code>)</p> </li> <li> <p>A synchronous function acts as an entrypoint to the engine.     The engine executes on a dedicated \"global loop\" thread. For asynchronous flow calls,     we return a coroutine from the entrypoint so the user can enter the engine without     blocking their event loop.</p> <p>See <code>enter_flow_run_engine_from_flow_call</code>, <code>enter_flow_run_engine_from_subprocess</code></p> </li> <li> <p>The thread that calls the entrypoint waits until orchestration of the flow run completes.     This thread is referred to as the \"user\" thread and is usually the \"main\" thread.     The thread is not blocked while waiting \u2014 it allows the engine to send work back to it.     This allows us to send calls back to the user thread from the global loop thread.</p> <p>See <code>wait_for_call_in_loop_thread</code> and <code>call_soon_in_waiting_thread</code></p> </li> <li> <p>The asynchronous engine branches depending on if the flow run exists already and if     there is a parent flow run in the current context.</p> <p>See <code>create_then_begin_flow_run</code>, <code>create_and_begin_subflow_run</code>, and <code>retrieve_flow_then_begin_flow_run</code></p> </li> <li> <p>The asynchronous engine prepares for execution of the flow run.     This includes starting the task runner, preparing context, etc.</p> <p>See <code>begin_flow_run</code></p> </li> <li> <p>The flow run is orchestrated through states, calling the user's function as necessary.     Generally the user's function is sent for execution on the user thread.     If the flow function cannot be safely executed on the user thread, e.g. it is     a synchronous child in an asynchronous parent it will be scheduled on a worker     thread instead.</p> <p>See <code>orchestrate_flow_run</code>, <code>call_soon_in_waiting_thread</code>, <code>call_soon_in_new_thread</code></p> </li> </ul>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--tasks","title":"Tasks","text":"<ul> <li> <p>The task is called or submitted by the user.     We require that this is always within a flow.</p> <p>See <code>Task.__call__</code> and <code>Task.submit</code></p> </li> <li> <p>A synchronous function acts as an entrypoint to the engine.     Unlike flow calls, this will not block until completion if <code>submit</code> was used.</p> <p>See <code>enter_task_run_engine</code></p> </li> <li> <p>A future is created for the task call.     Creation of the task run and submission to the task runner is scheduled as a     background task so submission of many tasks can occur concurrently.</p> <p>See <code>create_task_run_future</code> and <code>create_task_run_then_submit</code></p> </li> <li> <p>The engine branches depending on if a future, state, or result is requested.     If a future is requested, it is returned immediately to the user thread.     Otherwise, the engine will wait for the task run to complete and return the final     state or result.</p> <p>See <code>get_task_call_return_value</code></p> </li> <li> <p>An engine function is submitted to the task runner.     The task runner will schedule this function for execution on a worker.     When executed, it will prepare for orchestration and wait for completion of the run.</p> <p>See <code>create_task_run_then_submit</code> and <code>begin_task_run</code></p> </li> <li> <p>The task run is orchestrated through states, calling the user's function as necessary.     The user's function is always executed in a worker thread for isolation.</p> <p>See <code>orchestrate_task_run</code>, <code>call_soon_in_new_thread</code></p> <p>_Ideally, for local and sequential task runners we would send the task run to the user thread as we do for flows. See #9855.</p> </li> </ul>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_flow_run","title":"<code>begin_flow_run</code>  <code>async</code>","text":"<p>Begins execution of a flow run; blocks until completion of the flow run</p> <ul> <li>Starts a task runner</li> <li>Determines the result storage block to use</li> <li>Orchestrates the flow run (runs the user-function and generates tasks)</li> <li>Waits for tasks to complete / shutsdown the task runner</li> <li>Sets a terminal state for the flow run</li> </ul> <p>Note that the <code>flow_run</code> contains a <code>parameters</code> attribute which is the serialized parameters sent to the backend while the <code>parameters</code> argument here should be the deserialized and validated dictionary of python objects.</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_flow_run(\n    flow: Flow,\n    flow_run: FlowRun,\n    parameters: Dict[str, Any],\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Begins execution of a flow run; blocks until completion of the flow run\n\n    - Starts a task runner\n    - Determines the result storage block to use\n    - Orchestrates the flow run (runs the user-function and generates tasks)\n    - Waits for tasks to complete / shutsdown the task runner\n    - Sets a terminal state for the flow run\n\n    Note that the `flow_run` contains a `parameters` attribute which is the serialized\n    parameters sent to the backend while the `parameters` argument here should be the\n    deserialized and validated dictionary of python objects.\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    logger = flow_run_logger(flow_run, flow)\n\n    log_prints = should_log_prints(flow)\n    flow_run_context = FlowRunContext.construct(log_prints=log_prints)\n\n    async with AsyncExitStack() as stack:\n        await stack.enter_async_context(\n            report_flow_run_crashes(flow_run=flow_run, client=client, flow=flow)\n        )\n\n        # Create a task group for background tasks\n        flow_run_context.background_tasks = await stack.enter_async_context(\n            anyio.create_task_group()\n        )\n\n        # If the flow is async, we need to provide a portal so sync tasks can run\n        flow_run_context.sync_portal = (\n            stack.enter_context(start_blocking_portal()) if flow.isasync else None\n        )\n\n        task_runner = flow.task_runner.duplicate()\n        if task_runner is NotImplemented:\n            # Backwards compatibility; will not support concurrent flow runs\n            task_runner = flow.task_runner\n            logger.warning(\n                f\"Task runner {type(task_runner).__name__!r} does not implement the\"\n                \" `duplicate` method and will fail if used for concurrent execution of\"\n                \" the same flow.\"\n            )\n\n        logger.debug(\n            f\"Starting {type(flow.task_runner).__name__!r}; submitted tasks \"\n            f\"will be run {CONCURRENCY_MESSAGES[flow.task_runner.concurrency_type]}...\"\n        )\n\n        flow_run_context.task_runner = await stack.enter_async_context(\n            task_runner.start()\n        )\n\n        flow_run_context.result_factory = await ResultFactory.from_flow(\n            flow, client=client\n        )\n\n        if log_prints:\n            stack.enter_context(patch_print())\n\n        terminal_or_paused_state = await orchestrate_flow_run(\n            flow,\n            flow_run=flow_run,\n            parameters=parameters,\n            wait_for=None,\n            client=client,\n            partial_flow_run_context=flow_run_context,\n            # Orchestration needs to be interruptible if it has a timeout\n            interruptible=flow.timeout_seconds is not None,\n            user_thread=user_thread,\n        )\n\n    if terminal_or_paused_state.is_paused():\n        timeout = terminal_or_paused_state.state_details.pause_timeout\n        msg = \"Currently paused and suspending execution.\"\n        if timeout:\n            msg += f\" Resume before {timeout.to_rfc3339_string()} to finish execution.\"\n        logger.log(level=logging.INFO, msg=msg)\n        await APILogHandler.aflush()\n\n        return terminal_or_paused_state\n    else:\n        terminal_state = terminal_or_paused_state\n\n    # If debugging, use the more complete `repr` than the usual `str` description\n    display_state = repr(terminal_state) if PREFECT_DEBUG_MODE else str(terminal_state)\n\n    logger.log(\n        level=logging.INFO if terminal_state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n\n    # When a \"root\" flow run finishes, flush logs so we do not have to rely on handling\n    # during interpreter shutdown\n    await APILogHandler.aflush()\n\n    return terminal_state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_task_map","title":"<code>begin_task_map</code>  <code>async</code>","text":"<p>Async entrypoint for task mapping</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_task_map(\n    task: Task,\n    flow_run_context: Optional[FlowRunContext],\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    task_runner: Optional[BaseTaskRunner],\n    autonomous: bool = False,\n) -&gt; List[Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun]]:\n    \"\"\"Async entrypoint for task mapping\"\"\"\n    # We need to resolve some futures to map over their data, collect the upstream\n    # links beforehand to retain relationship tracking.\n    task_inputs = {\n        k: await collect_task_run_inputs(v, max_depth=0) for k, v in parameters.items()\n    }\n\n    # Resolve the top-level parameters in order to get mappable data of a known length.\n    # Nested parameters will be resolved in each mapped child where their relationships\n    # will also be tracked.\n    parameters = await resolve_inputs(parameters, max_depth=1)\n\n    # Ensure that any parameters in kwargs are expanded before this check\n    parameters = explode_variadic_parameter(task.fn, parameters)\n\n    iterable_parameters = {}\n    static_parameters = {}\n    annotated_parameters = {}\n    for key, val in parameters.items():\n        if isinstance(val, (allow_failure, quote)):\n            # Unwrap annotated parameters to determine if they are iterable\n            annotated_parameters[key] = val\n            val = val.unwrap()\n\n        if isinstance(val, unmapped):\n            static_parameters[key] = val.value\n        elif isiterable(val):\n            iterable_parameters[key] = list(val)\n        else:\n            static_parameters[key] = val\n\n    if not len(iterable_parameters):\n        raise MappingMissingIterable(\n            \"No iterable parameters were received. Parameters for map must \"\n            f\"include at least one iterable. Parameters: {parameters}\"\n        )\n\n    iterable_parameter_lengths = {\n        key: len(val) for key, val in iterable_parameters.items()\n    }\n    lengths = set(iterable_parameter_lengths.values())\n    if len(lengths) &gt; 1:\n        raise MappingLengthMismatch(\n            \"Received iterable parameters with different lengths. Parameters for map\"\n            f\" must all be the same length. Got lengths: {iterable_parameter_lengths}\"\n        )\n\n    map_length = list(lengths)[0]\n\n    task_runs = []\n    for i in range(map_length):\n        call_parameters = {key: value[i] for key, value in iterable_parameters.items()}\n        call_parameters.update({key: value for key, value in static_parameters.items()})\n\n        # Add default values for parameters; these are skipped earlier since they should\n        # not be mapped over\n        for key, value in get_parameter_defaults(task.fn).items():\n            call_parameters.setdefault(key, value)\n\n        # Re-apply annotations to each key again\n        for key, annotation in annotated_parameters.items():\n            call_parameters[key] = annotation.rewrap(call_parameters[key])\n\n        # Collapse any previously exploded kwargs\n        call_parameters = collapse_variadic_parameters(task.fn, call_parameters)\n\n        if autonomous:\n            task_runs.append(\n                await create_autonomous_task_run(\n                    task=task,\n                    parameters=call_parameters,\n                )\n            )\n        else:\n            task_runs.append(\n                partial(\n                    get_task_call_return_value,\n                    task=task,\n                    flow_run_context=flow_run_context,\n                    parameters=call_parameters,\n                    wait_for=wait_for,\n                    return_type=return_type,\n                    task_runner=task_runner,\n                    extra_task_inputs=task_inputs,\n                )\n            )\n\n    if autonomous:\n        return task_runs\n\n    # Maintain the order of the task runs when using the sequential task runner\n    runner = task_runner if task_runner else flow_run_context.task_runner\n    if runner.concurrency_type == TaskConcurrencyType.SEQUENTIAL:\n        return [await task_run() for task_run in task_runs]\n\n    return await gather(*task_runs)\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_task_run","title":"<code>begin_task_run</code>  <code>async</code>","text":"<p>Entrypoint for task run execution.</p> <p>This function is intended for submission to the task runner.</p> <p>This method may be called from a worker so we ensure the settings context has been entered. For example, with a runner that is executing tasks in the same event loop, we will likely not enter the context again because the current context already matches:</p> <p>main thread: --&gt; Flow called with settings A --&gt; <code>begin_task_run</code> executes same event loop --&gt; Profile A matches and is not entered again</p> <p>However, with execution on a remote environment, we are going to need to ensure the settings for the task run are respected by entering the context:</p> <p>main thread: --&gt; Flow called with settings A --&gt; <code>begin_task_run</code> is scheduled on a remote worker, settings A is serialized remote worker: --&gt; Remote worker imports Prefect (may not occur) --&gt; Global settings is loaded with default settings --&gt; <code>begin_task_run</code> executes on a different event loop than the flow --&gt; Current settings is not set or does not match, settings A is entered</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_task_run(\n    task: Task,\n    task_run: TaskRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    result_factory: ResultFactory,\n    log_prints: bool,\n    settings: prefect.context.SettingsContext,\n):\n    \"\"\"\n    Entrypoint for task run execution.\n\n    This function is intended for submission to the task runner.\n\n    This method may be called from a worker so we ensure the settings context has been\n    entered. For example, with a runner that is executing tasks in the same event loop,\n    we will likely not enter the context again because the current context already\n    matches:\n\n    main thread:\n    --&gt; Flow called with settings A\n    --&gt; `begin_task_run` executes same event loop\n    --&gt; Profile A matches and is not entered again\n\n    However, with execution on a remote environment, we are going to need to ensure the\n    settings for the task run are respected by entering the context:\n\n    main thread:\n    --&gt; Flow called with settings A\n    --&gt; `begin_task_run` is scheduled on a remote worker, settings A is serialized\n    remote worker:\n    --&gt; Remote worker imports Prefect (may not occur)\n    --&gt; Global settings is loaded with default settings\n    --&gt; `begin_task_run` executes on a different event loop than the flow\n    --&gt; Current settings is not set or does not match, settings A is entered\n    \"\"\"\n    maybe_flow_run_context = prefect.context.FlowRunContext.get()\n\n    async with AsyncExitStack() as stack:\n        # The settings context may be null on a remote worker so we use the safe `.get`\n        # method and compare it to the settings required for this task run\n        if prefect.context.SettingsContext.get() != settings:\n            stack.enter_context(settings)\n            setup_logging()\n\n        if maybe_flow_run_context:\n            # Accessible if on a worker that is running in the same thread as the flow\n            client = maybe_flow_run_context.client\n            # Only run the task in an interruptible thread if it in the same thread as\n            # the flow _and_ the flow run has a timeout attached. If the task is on a\n            # worker, the flow run timeout will not be raised in the worker process.\n            interruptible = maybe_flow_run_context.timeout_scope is not None\n        else:\n            # Otherwise, retrieve a new clien`t\n            client = await stack.enter_async_context(get_client())\n            interruptible = False\n            await stack.enter_async_context(anyio.create_task_group())\n\n        await stack.enter_async_context(report_task_run_crashes(task_run, client))\n\n        # TODO: Use the background tasks group to manage logging for this task\n\n        if log_prints:\n            stack.enter_context(patch_print())\n\n        await check_api_reachable(\n            client, f\"Cannot orchestrate task run '{task_run.id}'\"\n        )\n        try:\n            state = await orchestrate_task_run(\n                task=task,\n                task_run=task_run,\n                parameters=parameters,\n                wait_for=wait_for,\n                result_factory=result_factory,\n                log_prints=log_prints,\n                interruptible=interruptible,\n                client=client,\n            )\n\n            if not maybe_flow_run_context:\n                # When a a task run finishes on a remote worker flush logs to prevent\n                # loss if the process exits\n                await APILogHandler.aflush()\n\n        except Abort as abort:\n            # Task run probably already completed, fetch its state\n            task_run = await client.read_task_run(task_run.id)\n\n            if task_run.state.is_final():\n                task_run_logger(task_run).info(\n                    f\"Task run '{task_run.id}' already finished.\"\n                )\n            else:\n                # TODO: This is a concerning case; we should determine when this occurs\n                #       1. This can occur when the flow run is not in a running state\n                task_run_logger(task_run).warning(\n                    f\"Task run '{task_run.id}' received abort during orchestration: \"\n                    f\"{abort} Task run is in {task_run.state.type.value} state.\"\n                )\n            state = task_run.state\n\n        except Pause:\n            # A pause signal here should mean the flow run suspended, so we\n            # should do the same. We'll look up the flow run's pause state to\n            # try and reuse it, so we capture any data like timeouts.\n            flow_run = await client.read_flow_run(task_run.flow_run_id)\n            if flow_run.state and flow_run.state.is_paused():\n                state = flow_run.state\n            else:\n                state = Suspended()\n\n            task_run_logger(task_run).info(\n                \"Task run encountered a pause signal during orchestration.\"\n            )\n\n        return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_and_begin_subflow_run","title":"<code>create_and_begin_subflow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flows calls within a flow run</p> <p>Subflows differ from parent flows in that they - Resolve futures in passed parameters into values - Create a dummy task for representation in the parent flow - Retrieve default result storage from the parent flow rather than the server</p> <p>Returns:</p> Type Description <code>Any</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def create_and_begin_subflow_run(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; Any:\n    \"\"\"\n    Async entrypoint for flows calls within a flow run\n\n    Subflows differ from parent flows in that they\n    - Resolve futures in passed parameters into values\n    - Create a dummy task for representation in the parent flow\n    - Retrieve default result storage from the parent flow rather than the server\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    parent_flow_run_context = FlowRunContext.get()\n    parent_logger = get_run_logger(parent_flow_run_context)\n    log_prints = should_log_prints(flow)\n    terminal_state = None\n\n    parent_logger.debug(f\"Resolving inputs to {flow.name!r}\")\n    task_inputs = {k: await collect_task_run_inputs(v) for k, v in parameters.items()}\n\n    if wait_for:\n        task_inputs[\"wait_for\"] = await collect_task_run_inputs(wait_for)\n\n    rerunning = (\n        parent_flow_run_context.flow_run.run_count &gt; 1\n        if getattr(parent_flow_run_context, \"flow_run\", None)\n        else False\n    )\n\n    # Generate a task in the parent flow run to represent the result of the subflow run\n    dummy_task = Task(name=flow.name, fn=flow.fn, version=flow.version)\n    parent_task_run = await client.create_task_run(\n        task=dummy_task,\n        flow_run_id=(\n            parent_flow_run_context.flow_run.id\n            if getattr(parent_flow_run_context, \"flow_run\", None)\n            else None\n        ),\n        dynamic_key=_dynamic_key_for_task_run(parent_flow_run_context, dummy_task),\n        task_inputs=task_inputs,\n        state=Pending(),\n    )\n\n    # Resolve any task futures in the input\n    parameters = await resolve_inputs(parameters)\n\n    if parent_task_run.state.is_final() and not (\n        rerunning and not parent_task_run.state.is_completed()\n    ):\n        # Retrieve the most recent flow run from the database\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                parent_task_run_id={\"any_\": [parent_task_run.id]}\n            ),\n            sort=FlowRunSort.EXPECTED_START_TIME_ASC,\n        )\n        flow_run = flow_runs[-1]\n\n        # Set up variables required downstream\n        terminal_state = flow_run.state\n        logger = flow_run_logger(flow_run, flow)\n\n    else:\n        flow_run = await client.create_flow_run(\n            flow,\n            parameters=flow.serialize_parameters(parameters),\n            parent_task_run_id=parent_task_run.id,\n            state=parent_task_run.state if not rerunning else Pending(),\n            tags=TagsContext.get().current_tags,\n        )\n\n        parent_logger.info(\n            f\"Created subflow run {flow_run.name!r} for flow {flow.name!r}\"\n        )\n\n        logger = flow_run_logger(flow_run, flow)\n        ui_url = PREFECT_UI_URL.value()\n        if ui_url:\n            logger.info(\n                f\"View at {ui_url}/flow-runs/flow-run/{flow_run.id}\",\n                extra={\"send_to_api\": False},\n            )\n\n        result_factory = await ResultFactory.from_flow(\n            flow, client=parent_flow_run_context.client\n        )\n\n        if flow.should_validate_parameters:\n            try:\n                parameters = flow.validate_parameters(parameters)\n            except Exception:\n                message = \"Validation of flow parameters failed with error:\"\n                logger.exception(message)\n                terminal_state = await propose_state(\n                    client,\n                    state=await exception_to_failed_state(\n                        message=message, result_factory=result_factory\n                    ),\n                    flow_run_id=flow_run.id,\n                )\n\n        if terminal_state is None or not terminal_state.is_final():\n            async with AsyncExitStack() as stack:\n                await stack.enter_async_context(\n                    report_flow_run_crashes(flow_run=flow_run, client=client, flow=flow)\n                )\n\n                task_runner = flow.task_runner.duplicate()\n                if task_runner is NotImplemented:\n                    # Backwards compatibility; will not support concurrent flow runs\n                    task_runner = flow.task_runner\n                    logger.warning(\n                        f\"Task runner {type(task_runner).__name__!r} does not implement\"\n                        \" the `duplicate` method and will fail if used for concurrent\"\n                        \" execution of the same flow.\"\n                    )\n\n                await stack.enter_async_context(task_runner.start())\n\n                if log_prints:\n                    stack.enter_context(patch_print())\n\n                terminal_state = await orchestrate_flow_run(\n                    flow,\n                    flow_run=flow_run,\n                    parameters=parameters,\n                    wait_for=wait_for,\n                    # If the parent flow run has a timeout, then this one needs to be\n                    # interruptible as well\n                    interruptible=parent_flow_run_context.timeout_scope is not None,\n                    client=client,\n                    partial_flow_run_context=FlowRunContext.construct(\n                        sync_portal=parent_flow_run_context.sync_portal,\n                        task_runner=task_runner,\n                        background_tasks=parent_flow_run_context.background_tasks,\n                        result_factory=result_factory,\n                        log_prints=log_prints,\n                    ),\n                    user_thread=user_thread,\n                )\n\n    # Display the full state (including the result) if debugging\n    display_state = repr(terminal_state) if PREFECT_DEBUG_MODE else str(terminal_state)\n    logger.log(\n        level=logging.INFO if terminal_state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n\n    # Track the subflow state so the parent flow can use it to determine its final state\n    parent_flow_run_context.flow_run_states.append(terminal_state)\n\n    if return_type == \"state\":\n        return terminal_state\n    elif return_type == \"result\":\n        return await terminal_state.result(fetch=True)\n    else:\n        raise ValueError(f\"Invalid return type for flow engine {return_type!r}.\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_autonomous_task_run","title":"<code>create_autonomous_task_run</code>  <code>async</code>","text":"<p>Create a task run in the API for an autonomous task submission and store the provided parameters using the existing result storage mechanism.</p> Source code in <code>prefect/engine.py</code> <pre><code>async def create_autonomous_task_run(task: Task, parameters: Dict[str, Any]) -&gt; TaskRun:\n    \"\"\"Create a task run in the API for an autonomous task submission and store\n    the provided parameters using the existing result storage mechanism.\n    \"\"\"\n    async with get_client() as client:\n        state = Scheduled()\n        if parameters:\n            parameters_id = uuid4()\n            state.state_details.task_parameters_id = parameters_id\n\n            # TODO: Improve use of result storage for parameter storage / reference\n            task.persist_result = True\n\n            factory = await ResultFactory.from_autonomous_task(task, client=client)\n            await factory.store_parameters(parameters_id, parameters)\n\n        task_run = await client.create_task_run(\n            task=task,\n            flow_run_id=None,\n            dynamic_key=f\"{task.task_key}-{str(uuid4())[:NUM_CHARS_DYNAMIC_KEY]}\",\n            state=state,\n        )\n\n        engine_logger.debug(f\"Submitted run of task {task.name!r} for execution\")\n\n    return task_run\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_then_begin_flow_run","title":"<code>create_then_begin_flow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flow calls</p> <p>Creates the flow run in the backend, then enters the main flow run engine.</p> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def create_then_begin_flow_run(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; Any:\n    \"\"\"\n    Async entrypoint for flow calls\n\n    Creates the flow run in the backend, then enters the main flow run engine.\n    \"\"\"\n    # TODO: Returns a `State` depending on `return_type` and we can add an overload to\n    #       the function signature to clarify this eventually.\n\n    await check_api_reachable(client, \"Cannot create flow run\")\n\n    flow_run = None\n    state = Pending()\n    if flow.should_validate_parameters:\n        try:\n            parameters = flow.validate_parameters(parameters)\n        except Exception:\n            state = await exception_to_failed_state(\n                message=\"Validation of flow parameters failed with error:\"\n            )\n            flow_run = await _make_flow_run(flow, parameters, state, client)\n            await _run_flow_hooks(flow, flow_run, state)\n\n    flow_run = flow_run or await _make_flow_run(flow, parameters, state, client)\n\n    engine_logger.info(f\"Created flow run {flow_run.name!r} for flow {flow.name!r}\")\n\n    logger = flow_run_logger(flow_run, flow)\n\n    ui_url = PREFECT_UI_URL.value()\n    if ui_url:\n        logger.info(\n            f\"View at {ui_url}/flow-runs/flow-run/{flow_run.id}\",\n            extra={\"send_to_api\": False},\n        )\n\n    if state.is_failed():\n        logger.error(state.message)\n        engine_logger.info(\n            f\"Flow run {flow_run.name!r} received invalid parameters and is marked as\"\n            \" failed.\"\n        )\n    else:\n        state = await begin_flow_run(\n            flow=flow,\n            flow_run=flow_run,\n            parameters=parameters,\n            client=client,\n            user_thread=user_thread,\n        )\n\n    if return_type == \"state\":\n        return state\n    elif return_type == \"result\":\n        return await state.result(fetch=True)\n    else:\n        raise ValueError(f\"Invalid return type for flow engine {return_type!r}.\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_flow_run_engine_from_flow_call","title":"<code>enter_flow_run_engine_from_flow_call</code>","text":"<p>Sync entrypoint for flow calls.</p> <p>This function does the heavy lifting of ensuring we can get into an async context for flow run execution with minimal overhead.</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_flow_run_engine_from_flow_call(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n) -&gt; Union[State, Awaitable[State]]:\n    \"\"\"\n    Sync entrypoint for flow calls.\n\n    This function does the heavy lifting of ensuring we can get into an async context\n    for flow run execution with minimal overhead.\n    \"\"\"\n    setup_logging()\n\n    registry = PrefectObjectRegistry.get()\n    if registry and registry.block_code_execution:\n        engine_logger.warning(\n            f\"Script loading is in progress, flow {flow.name!r} will not be executed.\"\n            \" Consider updating the script to only call the flow if executed\"\n            f' directly:\\n\\n\\tif __name__ == \"__main__\":\\n\\t\\t{flow.fn.__name__}()'\n        )\n        return None\n\n    parent_flow_run_context = FlowRunContext.get()\n    is_subflow_run = parent_flow_run_context is not None\n\n    if wait_for is not None and not is_subflow_run:\n        raise ValueError(\"Only flows run as subflows can wait for dependencies.\")\n\n    begin_run = create_call(\n        create_and_begin_subflow_run if is_subflow_run else create_then_begin_flow_run,\n        flow=flow,\n        parameters=parameters,\n        wait_for=wait_for,\n        return_type=return_type,\n        client=parent_flow_run_context.client if is_subflow_run else None,\n        user_thread=threading.current_thread(),\n    )\n\n    # On completion of root flows, wait for the global thread to ensure that\n    # any work there is complete\n    done_callbacks = (\n        [create_call(wait_for_global_loop_exit)] if not is_subflow_run else None\n    )\n\n    # WARNING: You must define any context managers here to pass to our concurrency\n    # api instead of entering them in here in the engine entrypoint. Otherwise, async\n    # flows will not use the context as this function _exits_ to return an awaitable to\n    # the user. Generally, you should enter contexts _within_ the async `begin_run`\n    # instead but if you need to enter a context from the main thread you'll need to do\n    # it here.\n    contexts = [capture_sigterm(), collapse_excgroups()]\n\n    if flow.isasync and (\n        not is_subflow_run or (is_subflow_run and parent_flow_run_context.flow.isasync)\n    ):\n        # return a coro for the user to await if the flow is async\n        # unless it is an async subflow called in a sync flow\n        retval = from_async.wait_for_call_in_loop_thread(\n            begin_run,\n            done_callbacks=done_callbacks,\n            contexts=contexts,\n        )\n\n    else:\n        retval = from_sync.wait_for_call_in_loop_thread(\n            begin_run,\n            done_callbacks=done_callbacks,\n            contexts=contexts,\n        )\n\n    return retval\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_flow_run_engine_from_subprocess","title":"<code>enter_flow_run_engine_from_subprocess</code>","text":"<p>Sync entrypoint for flow runs that have been submitted for execution by an agent</p> <p>Differs from <code>enter_flow_run_engine_from_flow_call</code> in that we have a flow run id but not a flow object. The flow must be retrieved before execution can begin. Additionally, this assumes that the caller is always in a context without an event loop as this should be called from a fresh process.</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_flow_run_engine_from_subprocess(flow_run_id: UUID) -&gt; State:\n    \"\"\"\n    Sync entrypoint for flow runs that have been submitted for execution by an agent\n\n    Differs from `enter_flow_run_engine_from_flow_call` in that we have a flow run id\n    but not a flow object. The flow must be retrieved before execution can begin.\n    Additionally, this assumes that the caller is always in a context without an event\n    loop as this should be called from a fresh process.\n    \"\"\"\n\n    # Ensure collections are imported and have the opportunity to register types before\n    # loading the user code from the deployment\n    prefect.plugins.load_prefect_collections()\n\n    setup_logging()\n\n    state = from_sync.wait_for_call_in_loop_thread(\n        create_call(\n            retrieve_flow_then_begin_flow_run,\n            flow_run_id,\n            user_thread=threading.current_thread(),\n        ),\n        contexts=[capture_sigterm(), collapse_excgroups()],\n    )\n\n    APILogHandler.flush()\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_task_run_engine","title":"<code>enter_task_run_engine</code>","text":"<p>Sync entrypoint for task calls</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_task_run_engine(\n    task: Task,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    task_runner: Optional[BaseTaskRunner],\n    mapped: bool,\n    entering_from_task_run: Optional[bool] = False,\n) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun]:\n    \"\"\"Sync entrypoint for task calls\"\"\"\n\n    flow_run_context = FlowRunContext.get()\n\n    if not flow_run_context:\n        if return_type == \"future\" or mapped:\n            raise RuntimeError(\n                \" If you meant to submit a background task, you need to set\"\n                \" `prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=true`\"\n                \" and use `your_task.submit()` instead of `your_task()`.\"\n            )\n        from prefect.task_engine import submit_autonomous_task_run_to_engine\n\n        return submit_autonomous_task_run_to_engine(\n            task=task,\n            task_run=None,\n            parameters=parameters,\n            task_runner=task_runner,\n            wait_for=wait_for,\n            return_type=return_type,\n            client=get_client(),\n        )\n\n    if flow_run_context.timeout_scope and flow_run_context.timeout_scope.cancel_called:\n        raise TimeoutError(\"Flow run timed out\")\n\n    call_arguments = {\n        \"task\": task,\n        \"flow_run_context\": flow_run_context,\n        \"parameters\": parameters,\n        \"wait_for\": wait_for,\n        \"return_type\": return_type,\n        \"task_runner\": task_runner,\n    }\n\n    if not mapped:\n        call_arguments[\"entering_from_task_run\"] = entering_from_task_run\n\n    begin_run = create_call(\n        begin_task_map if mapped else get_task_call_return_value, **call_arguments\n    )\n\n    if task.isasync and (\n        flow_run_context.flow is None or flow_run_context.flow.isasync\n    ):\n        # return a coro for the user to await if an async task in an async flow\n        return from_async.wait_for_call_in_loop_thread(begin_run)\n    else:\n        return from_sync.wait_for_call_in_loop_thread(begin_run)\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.orchestrate_flow_run","title":"<code>orchestrate_flow_run</code>  <code>async</code>","text":"<p>Executes a flow run.</p> Note on flow timeouts <p>Since async flows are run directly in the main event loop, timeout behavior will match that described by anyio. If the flow is awaiting something, it will immediately return; otherwise, the next time it awaits it will exit. Sync flows are being task runner in a worker thread, which cannot be interrupted. The worker thread will exit at the next task call. The worker thread also has access to the status of the cancellation scope at <code>FlowRunContext.timeout_scope.cancel_called</code> which allows it to raise a <code>TimeoutError</code> to respect the timeout.</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def orchestrate_flow_run(\n    flow: Flow,\n    flow_run: FlowRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    interruptible: bool,\n    client: PrefectClient,\n    partial_flow_run_context: FlowRunContext,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Executes a flow run.\n\n    Note on flow timeouts:\n        Since async flows are run directly in the main event loop, timeout behavior will\n        match that described by anyio. If the flow is awaiting something, it will\n        immediately return; otherwise, the next time it awaits it will exit. Sync flows\n        are being task runner in a worker thread, which cannot be interrupted. The worker\n        thread will exit at the next task call. The worker thread also has access to the\n        status of the cancellation scope at `FlowRunContext.timeout_scope.cancel_called`\n        which allows it to raise a `TimeoutError` to respect the timeout.\n\n    Returns:\n        The final state of the run\n    \"\"\"\n\n    logger = flow_run_logger(flow_run, flow)\n\n    flow_run_context = None\n    parent_flow_run_context = FlowRunContext.get()\n\n    try:\n        # Resolve futures in any non-data dependencies to ensure they are ready\n        if wait_for is not None:\n            await resolve_inputs({\"wait_for\": wait_for}, return_data=False)\n    except UpstreamTaskError as upstream_exc:\n        return await propose_state(\n            client,\n            Pending(name=\"NotReady\", message=str(upstream_exc)),\n            flow_run_id=flow_run.id,\n            # if orchestrating a run already in a pending state, force orchestration to\n            # update the state name\n            force=flow_run.state.is_pending(),\n        )\n\n    state = await propose_state(client, Running(), flow_run_id=flow_run.id)\n\n    # flag to ensure we only update the flow run name once\n    run_name_set = False\n\n    await _run_flow_hooks(flow=flow, flow_run=flow_run, state=state)\n\n    while state.is_running():\n        waited_for_task_runs = False\n\n        # Update the flow run to the latest data\n        flow_run = await client.read_flow_run(flow_run.id)\n        try:\n            with FlowRunContext(\n                **{\n                    **partial_flow_run_context.dict(),\n                    **{\n                        \"flow_run\": flow_run,\n                        \"flow\": flow,\n                        \"client\": client,\n                        \"parameters\": parameters,\n                    },\n                }\n            ) as flow_run_context:\n                # update flow run name\n                if not run_name_set and flow.flow_run_name:\n                    flow_run_name = _resolve_custom_flow_run_name(\n                        flow=flow, parameters=parameters\n                    )\n\n                    await client.update_flow_run(\n                        flow_run_id=flow_run.id, name=flow_run_name\n                    )\n                    logger.extra[\"flow_run_name\"] = flow_run_name\n                    logger.debug(\n                        f\"Renamed flow run {flow_run.name!r} to {flow_run_name!r}\"\n                    )\n                    flow_run.name = flow_run_name\n                    run_name_set = True\n\n                args, kwargs = parameters_to_args_kwargs(flow.fn, parameters)\n                logger.debug(\n                    f\"Executing flow {flow.name!r} for flow run {flow_run.name!r}...\"\n                )\n\n                if PREFECT_DEBUG_MODE:\n                    logger.debug(f\"Executing {call_repr(flow.fn, *args, **kwargs)}\")\n                else:\n                    logger.debug(\n                        \"Beginning execution...\", extra={\"state_message\": True}\n                    )\n\n                flow_call = create_call(flow.fn, *args, **kwargs)\n\n                # This check for a parent call is needed for cases where the engine\n                # was entered directly during testing\n                parent_call = get_current_call()\n\n                if parent_call and (\n                    not parent_flow_run_context\n                    or (\n                        getattr(parent_flow_run_context, \"flow\", None)\n                        and parent_flow_run_context.flow.isasync == flow.isasync\n                    )\n                ):\n                    from_async.call_soon_in_waiting_thread(\n                        flow_call,\n                        thread=user_thread,\n                        timeout=flow.timeout_seconds,\n                    )\n                else:\n                    from_async.call_soon_in_new_thread(\n                        flow_call, timeout=flow.timeout_seconds\n                    )\n\n                result = await flow_call.aresult()\n\n                waited_for_task_runs = await wait_for_task_runs_and_report_crashes(\n                    flow_run_context.task_run_futures, client=client\n                )\n        except PausedRun as exc:\n            # could get raised either via utility or by returning Paused from a task run\n            # if a task run pauses, we set its state as the flow's state\n            # to preserve reschedule and timeout behavior\n            paused_flow_run = await client.read_flow_run(flow_run.id)\n            if paused_flow_run.state.is_running():\n                state = await propose_state(\n                    client,\n                    state=exc.state,\n                    flow_run_id=flow_run.id,\n                )\n\n                return state\n            paused_flow_run_state = paused_flow_run.state\n            return paused_flow_run_state\n        except CancelledError as exc:\n            if not flow_call.timedout():\n                # If the flow call was not cancelled by us; this is a crash\n                raise\n            # Construct a new exception as `TimeoutError`\n            original = exc\n            exc = TimeoutError()\n            exc.__cause__ = original\n            logger.exception(\"Encountered exception during execution:\")\n            terminal_state = await exception_to_failed_state(\n                exc,\n                message=f\"Flow run exceeded timeout of {flow.timeout_seconds} seconds\",\n                result_factory=flow_run_context.result_factory,\n                name=\"TimedOut\",\n            )\n        except Exception:\n            # Generic exception in user code\n            logger.exception(\"Encountered exception during execution:\")\n            terminal_state = await exception_to_failed_state(\n                message=\"Flow run encountered an exception.\",\n                result_factory=flow_run_context.result_factory,\n            )\n        else:\n            if result is None:\n                # All tasks and subflows are reference tasks if there is no return value\n                # If there are no tasks, use `None` instead of an empty iterable\n                result = (\n                    flow_run_context.task_run_futures\n                    + flow_run_context.task_run_states\n                    + flow_run_context.flow_run_states\n                ) or None\n\n            terminal_state = await return_value_to_state(\n                await resolve_futures_to_states(result),\n                result_factory=flow_run_context.result_factory,\n            )\n\n        if not waited_for_task_runs:\n            # An exception occurred that prevented us from waiting for task runs to\n            # complete. Ensure that we wait for them before proposing a final state\n            # for the flow run.\n            await wait_for_task_runs_and_report_crashes(\n                flow_run_context.task_run_futures, client=client\n            )\n\n        # Before setting the flow run state, store state.data using\n        # block storage and send the resulting data document to the Prefect API instead.\n        # This prevents the pickled return value of flow runs\n        # from being sent to the Prefect API and stored in the Prefect database.\n        # state.data is left as is, otherwise we would have to load\n        # the data from block storage again after storing.\n        state = await propose_state(\n            client,\n            state=terminal_state,\n            flow_run_id=flow_run.id,\n        )\n\n        await _run_flow_hooks(flow=flow, flow_run=flow_run, state=state)\n\n        if state.type != terminal_state.type and PREFECT_DEBUG_MODE:\n            logger.debug(\n                (\n                    f\"Received new state {state} when proposing final state\"\n                    f\" {terminal_state}\"\n                ),\n                extra={\"send_to_api\": False},\n            )\n\n        if not state.is_final() and not state.is_paused():\n            logger.info(\n                (\n                    f\"Received non-final state {state.name!r} when proposing final\"\n                    f\" state {terminal_state.name!r} and will attempt to run again...\"\n                ),\n            )\n            # Attempt to enter a running state again\n            state = await propose_state(client, Running(), flow_run_id=flow_run.id)\n\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.orchestrate_task_run","title":"<code>orchestrate_task_run</code>  <code>async</code>","text":"<p>Execute a task run</p> <p>This function should be submitted to a task runner. We must construct the context here instead of receiving it already populated since we may be in a new environment.</p> <p>Proposes a RUNNING state, then - if accepted, the task user function will be run - if rejected, the received state will be returned</p> <p>When the user function is run, the result will be used to determine a final state - if an exception is encountered, it is trapped and stored in a FAILED state - otherwise, <code>return_value_to_state</code> is used to determine the state</p> <p>If the final state is COMPLETED, we generate a cache key as specified by the task</p> <p>The final state is then proposed - if accepted, this is the final state and will be returned - if rejected and a new final state is provided, it will be returned - if rejected and a non-final state is provided, we will attempt to enter a RUNNING     state again</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def orchestrate_task_run(\n    task: Task,\n    task_run: TaskRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    result_factory: ResultFactory,\n    log_prints: bool,\n    interruptible: bool,\n    client: PrefectClient,\n) -&gt; State:\n    \"\"\"\n    Execute a task run\n\n    This function should be submitted to a task runner. We must construct the context\n    here instead of receiving it already populated since we may be in a new environment.\n\n    Proposes a RUNNING state, then\n    - if accepted, the task user function will be run\n    - if rejected, the received state will be returned\n\n    When the user function is run, the result will be used to determine a final state\n    - if an exception is encountered, it is trapped and stored in a FAILED state\n    - otherwise, `return_value_to_state` is used to determine the state\n\n    If the final state is COMPLETED, we generate a cache key as specified by the task\n\n    The final state is then proposed\n    - if accepted, this is the final state and will be returned\n    - if rejected and a new final state is provided, it will be returned\n    - if rejected and a non-final state is provided, we will attempt to enter a RUNNING\n        state again\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    flow_run_context = prefect.context.FlowRunContext.get()\n    if flow_run_context:\n        flow_run = flow_run_context.flow_run\n    else:\n        flow_run = await client.read_flow_run(task_run.flow_run_id)\n    logger = task_run_logger(task_run, task=task, flow_run=flow_run)\n\n    partial_task_run_context = TaskRunContext.construct(\n        task_run=task_run,\n        task=task,\n        client=client,\n        result_factory=result_factory,\n        log_prints=log_prints,\n    )\n    task_introspection_start_time = time.perf_counter()\n    try:\n        # Resolve futures in parameters into data\n        resolved_parameters = await resolve_inputs(parameters)\n        # Resolve futures in any non-data dependencies to ensure they are ready\n        await resolve_inputs({\"wait_for\": wait_for}, return_data=False)\n    except UpstreamTaskError as upstream_exc:\n        return await propose_state(\n            client,\n            Pending(name=\"NotReady\", message=str(upstream_exc)),\n            task_run_id=task_run.id,\n            # if orchestrating a run already in a pending state, force orchestration to\n            # update the state name\n            force=task_run.state.is_pending(),\n        )\n    task_introspection_end_time = time.perf_counter()\n\n    introspection_time = round(\n        task_introspection_end_time - task_introspection_start_time, 3\n    )\n    threshold = PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD.value()\n    if threshold and introspection_time &gt; threshold:\n        logger.warning(\n            f\"Task parameter introspection took {introspection_time} seconds \"\n            f\", exceeding `PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD` of {threshold}. \"\n            \"Try wrapping large task parameters with \"\n            \"`prefect.utilities.annotations.quote` for increased performance, \"\n            \"e.g. `my_task(quote(param))`. To disable this message set \"\n            \"`PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD=0`.\"\n        )\n\n    # Generate the cache key to attach to proposed states\n    # The cache key uses a TaskRunContext that does not include a `timeout_context``\n\n    task_run_context = TaskRunContext(\n        **partial_task_run_context.dict(), parameters=resolved_parameters\n    )\n\n    cache_key = (\n        task.cache_key_fn(\n            task_run_context,\n            resolved_parameters,\n        )\n        if task.cache_key_fn\n        else None\n    )\n\n    # Ignore the cached results for a cache key, default = false\n    # Setting on task level overrules the Prefect setting (env var)\n    refresh_cache = (\n        task.refresh_cache\n        if task.refresh_cache is not None\n        else PREFECT_TASKS_REFRESH_CACHE.value()\n    )\n\n    # Emit an event to capture that the task run was in the `PENDING` state.\n    last_event = emit_task_run_state_change_event(\n        task_run=task_run, initial_state=None, validated_state=task_run.state\n    )\n    last_state = (\n        Pending()\n        if flow_run_context and flow_run_context.autonomous_task_run\n        else task_run.state\n    )\n\n    # Completed states with persisted results should have result data. If it's missing,\n    # this could be a manual state transition, so we should use the Unknown result type\n    # to represent that we know we don't know the result.\n    if (\n        last_state\n        and last_state.is_completed()\n        and result_factory.persist_result\n        and not last_state.data\n    ):\n        state = await propose_state(\n            client,\n            state=Completed(data=await UnknownResult.create()),\n            task_run_id=task_run.id,\n            force=True,\n        )\n\n    # Transition from `PENDING` -&gt; `RUNNING`\n    try:\n        state = await propose_state(\n            client,\n            Running(\n                state_details=StateDetails(\n                    cache_key=cache_key, refresh_cache=refresh_cache\n                )\n            ),\n            task_run_id=task_run.id,\n        )\n    except Pause as exc:\n        # We shouldn't get a pause signal without a state, but if this happens,\n        # just use a Paused state to assume an in-process pause.\n        state = exc.state if exc.state else Paused()\n\n        # If a flow submits tasks and then pauses, we may reach this point due\n        # to concurrency timing because the tasks will try to transition after\n        # the flow run has paused. Orchestration will send back a Paused state\n        # for the task runs.\n        if state.state_details.pause_reschedule:\n            # If we're being asked to pause and reschedule, we should exit the\n            # task and expect to be resumed later.\n            raise\n\n    if state.is_paused():\n        BACKOFF_MAX = 10  # Seconds\n        backoff_count = 0\n\n        async def tick():\n            nonlocal backoff_count\n            if backoff_count &lt; BACKOFF_MAX:\n                backoff_count += 1\n            interval = 1 + backoff_count + random.random() * backoff_count\n            await anyio.sleep(interval)\n\n        # Enter a loop to wait for the task run to be resumed, i.e.\n        # become Pending, and then propose a Running state again.\n        while True:\n            await tick()\n\n            # Propose a Running state again. We do this instead of reading the\n            # task run because if the flow run times out, this lets\n            # orchestration fail the task run.\n            try:\n                state = await propose_state(\n                    client,\n                    Running(\n                        state_details=StateDetails(\n                            cache_key=cache_key, refresh_cache=refresh_cache\n                        )\n                    ),\n                    task_run_id=task_run.id,\n                )\n            except Pause as exc:\n                if not exc.state:\n                    continue\n\n                if exc.state.state_details.pause_reschedule:\n                    # If the pause state includes pause_reschedule, we should exit the\n                    # task and expect to be resumed later. We've already checked for this\n                    # above, but we check again here in case the state changed; e.g. the\n                    # flow run suspended.\n                    raise\n                else:\n                    # Propose a Running state again.\n                    continue\n            else:\n                break\n\n    # Emit an event to capture the result of proposing a `RUNNING` state.\n    last_event = emit_task_run_state_change_event(\n        task_run=task_run,\n        initial_state=last_state,\n        validated_state=state,\n        follows=last_event,\n    )\n    last_state = state\n\n    # flag to ensure we only update the task run name once\n    run_name_set = False\n\n    # Only run the task if we enter a `RUNNING` state\n    while state.is_running():\n        # Retrieve the latest metadata for the task run context\n        task_run = await client.read_task_run(task_run.id)\n\n        with task_run_context.copy(\n            update={\"task_run\": task_run, \"start_time\": pendulum.now(\"UTC\")}\n        ):\n            try:\n                args, kwargs = parameters_to_args_kwargs(task.fn, resolved_parameters)\n                # update task run name\n                if not run_name_set and task.task_run_name:\n                    task_run_name = _resolve_custom_task_run_name(\n                        task=task, parameters=resolved_parameters\n                    )\n                    await client.set_task_run_name(\n                        task_run_id=task_run.id, name=task_run_name\n                    )\n                    logger.extra[\"task_run_name\"] = task_run_name\n                    logger.debug(\n                        f\"Renamed task run {task_run.name!r} to {task_run_name!r}\"\n                    )\n                    task_run.name = task_run_name\n                    run_name_set = True\n\n                if PREFECT_DEBUG_MODE.value():\n                    logger.debug(f\"Executing {call_repr(task.fn, *args, **kwargs)}\")\n                else:\n                    logger.debug(\n                        \"Beginning execution...\", extra={\"state_message\": True}\n                    )\n\n                call = from_async.call_soon_in_new_thread(\n                    create_call(task.fn, *args, **kwargs), timeout=task.timeout_seconds\n                )\n                result = await call.aresult()\n\n            except (CancelledError, asyncio.CancelledError) as exc:\n                if not call.timedout():\n                    # If the task call was not cancelled by us; this is a crash\n                    raise\n                # Construct a new exception as `TimeoutError`\n                original = exc\n                exc = TimeoutError()\n                exc.__cause__ = original\n                logger.exception(\"Encountered exception during execution:\")\n                terminal_state = await exception_to_failed_state(\n                    exc,\n                    message=(\n                        f\"Task run exceeded timeout of {task.timeout_seconds} seconds\"\n                    ),\n                    result_factory=task_run_context.result_factory,\n                    name=\"TimedOut\",\n                )\n            except Exception as exc:\n                logger.exception(\"Encountered exception during execution:\")\n                terminal_state = await exception_to_failed_state(\n                    exc,\n                    message=\"Task run encountered an exception\",\n                    result_factory=task_run_context.result_factory,\n                )\n            else:\n                terminal_state = await return_value_to_state(\n                    result,\n                    result_factory=task_run_context.result_factory,\n                )\n\n                # for COMPLETED tasks, add the cache key and expiration\n                if terminal_state.is_completed():\n                    terminal_state.state_details.cache_expiration = (\n                        (pendulum.now(\"utc\") + task.cache_expiration)\n                        if task.cache_expiration\n                        else None\n                    )\n                    terminal_state.state_details.cache_key = cache_key\n\n            if terminal_state.is_failed():\n                # Defer to user to decide whether failure is retriable\n                terminal_state.state_details.retriable = (\n                    await _check_task_failure_retriable(task, task_run, terminal_state)\n                )\n            state = await propose_state(client, terminal_state, task_run_id=task_run.id)\n            last_event = emit_task_run_state_change_event(\n                task_run=task_run,\n                initial_state=last_state,\n                validated_state=state,\n                follows=last_event,\n            )\n            last_state = state\n\n            await _run_task_hooks(\n                task=task,\n                task_run=task_run,\n                state=state,\n            )\n\n            if state.type != terminal_state.type and PREFECT_DEBUG_MODE:\n                logger.debug(\n                    (\n                        f\"Received new state {state} when proposing final state\"\n                        f\" {terminal_state}\"\n                    ),\n                    extra={\"send_to_api\": False},\n                )\n\n            if not state.is_final() and not state.is_paused():\n                logger.info(\n                    (\n                        f\"Received non-final state {state.name!r} when proposing final\"\n                        f\" state {terminal_state.name!r} and will attempt to run\"\n                        \" again...\"\n                    ),\n                )\n                # Attempt to enter a running state again\n                state = await propose_state(client, Running(), task_run_id=task_run.id)\n                last_event = emit_task_run_state_change_event(\n                    task_run=task_run,\n                    initial_state=last_state,\n                    validated_state=state,\n                    follows=last_event,\n                )\n                last_state = state\n\n    # If debugging, use the more complete `repr` than the usual `str` description\n    display_state = repr(state) if PREFECT_DEBUG_MODE else str(state)\n\n    logger.log(\n        level=logging.INFO if state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.pause_flow_run","title":"<code>pause_flow_run</code>  <code>async</code>","text":"<p>Pauses the current flow run by blocking execution until resumed.</p> <p>When called within a flow run, execution will block and no downstream tasks will run until the flow is resumed. Task runs that have already started will continue running. A timeout parameter can be passed that will fail the flow run if it has not been resumed within the specified time.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>a flow run id. If supplied, this function will attempt to pause the specified flow run outside of the flow run process. When paused, the flow run will continue execution until the NEXT task is orchestrated, at which point the flow will exit. Any tasks that have already started will run until completion. When resumed, the flow run will be rescheduled to finish execution. In order pause a flow run in this way, the flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <code>None</code> <code>timeout</code> <code>int</code> <p>the number of seconds to wait for the flow to be resumed before failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds any configured flow-level timeout, the flow might fail even after resuming.</p> <code>3600</code> <code>poll_interval</code> <code>int</code> <p>The number of seconds between checking whether the flow has been resumed. Defaults to 10 seconds.</p> <code>10</code> <code>reschedule</code> <code>bool</code> <p>Flag that will reschedule the flow run if resumed. Instead of blocking execution, the flow will gracefully exit (with no result returned) instead. To use this flag, a flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <code>False</code> <code>key</code> <code>str</code> <p>An optional key to prevent calling pauses more than once. This defaults to the number of pauses observed by the flow so far, and prevents pauses that use the \"reschedule\" option from running the same pause twice. A custom key can be supplied for custom pausing behavior.</p> <code>None</code> <code>wait_for_input</code> <code>Optional[Type[T]]</code> <p>a subclass of <code>RunInput</code> or any type supported by Pydantic. If provided when the flow pauses, the flow will wait for the input to be provided before resuming. If the flow is resumed without providing the input, the flow will fail. If the flow is resumed with the input, the flow will resume and the input will be loaded and returned from this function.</p> <code>None</code> <pre><code>@task\ndef task_one():\n    for i in range(3):\n        sleep(1)\n\n@flow\ndef my_flow():\n    terminal_state = task_one.submit(return_state=True)\n    if terminal_state.type == StateType.COMPLETED:\n        print(\"Task one succeeded! Pausing flow run..\")\n        pause_flow_run(timeout=2)\n    else:\n        print(\"Task one failed. Skipping pause flow run..\")\n</code></pre> Source code in <code>prefect/engine.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"flow_run_id\", start_date=\"Dec 2023\", help=\"Use `suspend_flow_run` instead.\"\n)\n@deprecated_parameter(\n    \"reschedule\",\n    start_date=\"Dec 2023\",\n    when=lambda p: p is True,\n    help=\"Use `suspend_flow_run` instead.\",\n)\n@experimental_parameter(\n    \"wait_for_input\", group=\"flow_run_input\", when=lambda y: y is not None\n)\nasync def pause_flow_run(\n    wait_for_input: Optional[Type[T]] = None,\n    flow_run_id: UUID = None,\n    timeout: int = 3600,\n    poll_interval: int = 10,\n    reschedule: bool = False,\n    key: str = None,\n) -&gt; Optional[T]:\n    \"\"\"\n    Pauses the current flow run by blocking execution until resumed.\n\n    When called within a flow run, execution will block and no downstream tasks will\n    run until the flow is resumed. Task runs that have already started will continue\n    running. A timeout parameter can be passed that will fail the flow run if it has not\n    been resumed within the specified time.\n\n    Args:\n        flow_run_id: a flow run id. If supplied, this function will attempt to pause\n            the specified flow run outside of the flow run process. When paused, the\n            flow run will continue execution until the NEXT task is orchestrated, at\n            which point the flow will exit. Any tasks that have already started will\n            run until completion. When resumed, the flow run will be rescheduled to\n            finish execution. In order pause a flow run in this way, the flow needs to\n            have an associated deployment and results need to be configured with the\n            `persist_results` option.\n        timeout: the number of seconds to wait for the flow to be resumed before\n            failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds\n            any configured flow-level timeout, the flow might fail even after resuming.\n        poll_interval: The number of seconds between checking whether the flow has been\n            resumed. Defaults to 10 seconds.\n        reschedule: Flag that will reschedule the flow run if resumed. Instead of\n            blocking execution, the flow will gracefully exit (with no result returned)\n            instead. To use this flag, a flow needs to have an associated deployment and\n            results need to be configured with the `persist_results` option.\n        key: An optional key to prevent calling pauses more than once. This defaults to\n            the number of pauses observed by the flow so far, and prevents pauses that\n            use the \"reschedule\" option from running the same pause twice. A custom key\n            can be supplied for custom pausing behavior.\n        wait_for_input: a subclass of `RunInput` or any type supported by\n            Pydantic. If provided when the flow pauses, the flow will wait for the\n            input to be provided before resuming. If the flow is resumed without\n            providing the input, the flow will fail. If the flow is resumed with the\n            input, the flow will resume and the input will be loaded and returned\n            from this function.\n\n    Example:\n    ```python\n    @task\n    def task_one():\n        for i in range(3):\n            sleep(1)\n\n    @flow\n    def my_flow():\n        terminal_state = task_one.submit(return_state=True)\n        if terminal_state.type == StateType.COMPLETED:\n            print(\"Task one succeeded! Pausing flow run..\")\n            pause_flow_run(timeout=2)\n        else:\n            print(\"Task one failed. Skipping pause flow run..\")\n    ```\n\n    \"\"\"\n    if flow_run_id:\n        if wait_for_input is not None:\n            raise RuntimeError(\"Cannot wait for input when pausing out of process.\")\n\n        return await _out_of_process_pause(\n            flow_run_id=flow_run_id,\n            timeout=timeout,\n            reschedule=reschedule,\n            key=key,\n        )\n    else:\n        return await _in_process_pause(\n            timeout=timeout,\n            poll_interval=poll_interval,\n            reschedule=reschedule,\n            key=key,\n            wait_for_input=wait_for_input,\n        )\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.report_flow_run_crashes","title":"<code>report_flow_run_crashes</code>  <code>async</code>","text":"<p>Detect flow run crashes during this context and update the run to a proper final state.</p> <p>This context must reraise the exception to properly exit the run.</p> Source code in <code>prefect/engine.py</code> <pre><code>@asynccontextmanager\nasync def report_flow_run_crashes(flow_run: FlowRun, client: PrefectClient, flow: Flow):\n    \"\"\"\n    Detect flow run crashes during this context and update the run to a proper final\n    state.\n\n    This context _must_ reraise the exception to properly exit the run.\n    \"\"\"\n    try:\n        with collapse_excgroups():\n            yield\n    except (Abort, Pause):\n        # Do not capture internal signals as crashes\n        raise\n    except BaseException as exc:\n        state = await exception_to_crashed_state(exc)\n        logger = flow_run_logger(flow_run)\n        with anyio.CancelScope(shield=True):\n            logger.error(f\"Crash detected! {state.message}\")\n            logger.debug(\"Crash details:\", exc_info=exc)\n            flow_run_state = await propose_state(client, state, flow_run_id=flow_run.id)\n            engine_logger.debug(\n                f\"Reported crashed flow run {flow_run.name!r} successfully!\"\n            )\n\n            # Only `on_crashed` and `on_cancellation` flow run state change hooks can be called here.\n            # We call the hooks after the state change proposal to `CRASHED` is validated\n            # or rejected (if it is in a `CANCELLING` state).\n            await _run_flow_hooks(\n                flow=flow,\n                flow_run=flow_run,\n                state=flow_run_state,\n            )\n\n        # Reraise the exception\n        raise\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.report_task_run_crashes","title":"<code>report_task_run_crashes</code>  <code>async</code>","text":"<p>Detect task run crashes during this context and update the run to a proper final state.</p> <p>This context must reraise the exception to properly exit the run.</p> Source code in <code>prefect/engine.py</code> <pre><code>@asynccontextmanager\nasync def report_task_run_crashes(task_run: TaskRun, client: PrefectClient):\n    \"\"\"\n    Detect task run crashes during this context and update the run to a proper final\n    state.\n\n    This context _must_ reraise the exception to properly exit the run.\n    \"\"\"\n    try:\n        with collapse_excgroups():\n            yield\n    except (Abort, Pause):\n        # Do not capture internal signals as crashes\n        raise\n    except BaseException as exc:\n        state = await exception_to_crashed_state(exc)\n        logger = task_run_logger(task_run)\n        with anyio.CancelScope(shield=True):\n            logger.error(f\"Crash detected! {state.message}\")\n            logger.debug(\"Crash details:\", exc_info=exc)\n            await client.set_task_run_state(\n                state=state,\n                task_run_id=task_run.id,\n                force=True,\n            )\n            engine_logger.debug(\n                f\"Reported crashed task run {task_run.name!r} successfully!\"\n            )\n\n        # Reraise the exception\n        raise\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resumes a paused flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <p>the flow_run_id to resume</p> required <code>run_input</code> <code>Optional[Dict]</code> <p>a dictionary of inputs to provide to the flow run.</p> <code>None</code> Source code in <code>prefect/engine.py</code> <pre><code>@deprecated_callable(\n    start_date=\"Jun 2024\",\n    help=\"Will be moved in Prefect 3 to prefect.flow_runs:resume_flow_run\",\n)\n@sync_compatible\nasync def resume_flow_run(flow_run_id, run_input: Optional[Dict] = None):\n    \"\"\"\n    Resumes a paused flow.\n\n    Args:\n        flow_run_id: the flow_run_id to resume\n        run_input: a dictionary of inputs to provide to the flow run.\n    \"\"\"\n    client = get_client()\n    async with client:\n        flow_run = await client.read_flow_run(flow_run_id)\n\n        if not flow_run.state.is_paused():\n            raise NotPausedError(\"Cannot resume a run that isn't paused!\")\n\n        response = await client.resume_flow_run(flow_run_id, run_input=run_input)\n\n    if response.status == SetStateStatus.REJECT:\n        if response.state.type == StateType.FAILED:\n            raise FlowPauseTimeout(\"Flow run can no longer be resumed.\")\n        else:\n            raise RuntimeError(f\"Cannot resume this run: {response.details.reason}\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.retrieve_flow_then_begin_flow_run","title":"<code>retrieve_flow_then_begin_flow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flow runs that have been submitted for execution by an agent</p> <ul> <li>Retrieves the deployment information</li> <li>Loads the flow object using deployment information</li> <li>Updates the flow run version</li> </ul> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def retrieve_flow_then_begin_flow_run(\n    flow_run_id: UUID,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Async entrypoint for flow runs that have been submitted for execution by an agent\n\n    - Retrieves the deployment information\n    - Loads the flow object using deployment information\n    - Updates the flow run version\n    \"\"\"\n    flow_run = await client.read_flow_run(flow_run_id)\n\n    entrypoint = os.environ.get(\"PREFECT__FLOW_ENTRYPOINT\")\n\n    try:\n        flow = (\n            # We do not want to use a placeholder flow at runtime\n            load_flow_from_entrypoint(entrypoint, use_placeholder_flow=False)\n            if entrypoint\n            else await load_flow_from_flow_run(\n                flow_run, client=client, use_placeholder_flow=False\n            )\n        )\n    except Exception:\n        message = (\n            \"Flow could not be retrieved from\"\n            f\" {'entrypoint' if entrypoint else 'deployment'}.\"\n        )\n        flow_run_logger(flow_run).exception(message)\n        state = await exception_to_failed_state(message=message)\n        await client.set_flow_run_state(\n            state=state, flow_run_id=flow_run_id, force=True\n        )\n        return state\n\n    # Update the flow run policy defaults to match settings on the flow\n    # Note: Mutating the flow run object prevents us from performing another read\n    #       operation if these properties are used by the client downstream\n    if flow_run.empirical_policy.retry_delay is None:\n        flow_run.empirical_policy.retry_delay = flow.retry_delay_seconds\n\n    if flow_run.empirical_policy.retries is None:\n        flow_run.empirical_policy.retries = flow.retries\n\n    await client.update_flow_run(\n        flow_run_id=flow_run_id,\n        flow_version=flow.version,\n        empirical_policy=flow_run.empirical_policy,\n    )\n\n    if flow.should_validate_parameters:\n        failed_state = None\n        try:\n            parameters = flow.validate_parameters(flow_run.parameters)\n        except Exception:\n            message = \"Validation of flow parameters failed with error: \"\n            flow_run_logger(flow_run).exception(message)\n            failed_state = await exception_to_failed_state(message=message)\n\n        if failed_state is not None:\n            await propose_state(\n                client,\n                state=failed_state,\n                flow_run_id=flow_run_id,\n            )\n            return failed_state\n    else:\n        parameters = flow_run.parameters\n\n    # Ensure default values are populated\n    parameters = {**get_parameter_defaults(flow.fn), **parameters}\n\n    return await begin_flow_run(\n        flow=flow,\n        flow_run=flow_run,\n        parameters=parameters,\n        client=client,\n        user_thread=user_thread,\n    )\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.suspend_flow_run","title":"<code>suspend_flow_run</code>  <code>async</code>","text":"<p>Suspends a flow run by stopping code execution until resumed.</p> <p>When suspended, the flow run will continue execution until the NEXT task is orchestrated, at which point the flow will exit. Any tasks that have already started will run until completion. When resumed, the flow run will be rescheduled to finish execution. In order suspend a flow run in this way, the flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>Optional[UUID]</code> <p>a flow run id. If supplied, this function will attempt to suspend the specified flow run. If not supplied will attempt to suspend the current flow run.</p> <code>None</code> <code>timeout</code> <code>Optional[int]</code> <p>the number of seconds to wait for the flow to be resumed before failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds any configured flow-level timeout, the flow might fail even after resuming.</p> <code>3600</code> <code>key</code> <code>Optional[str]</code> <p>An optional key to prevent calling suspend more than once. This defaults to a random string and prevents suspends from running the same suspend twice. A custom key can be supplied for custom suspending behavior.</p> <code>None</code> <code>wait_for_input</code> <code>Optional[Type[T]]</code> <p>a subclass of <code>RunInput</code> or any type supported by Pydantic. If provided when the flow suspends, the flow will remain suspended until receiving the input before resuming. If the flow is resumed without providing the input, the flow will fail. If the flow is resumed with the input, the flow will resume and the input will be loaded and returned from this function.</p> <code>None</code> Source code in <code>prefect/engine.py</code> <pre><code>@sync_compatible\n@inject_client\n@experimental_parameter(\n    \"wait_for_input\", group=\"flow_run_input\", when=lambda y: y is not None\n)\nasync def suspend_flow_run(\n    wait_for_input: Optional[Type[T]] = None,\n    flow_run_id: Optional[UUID] = None,\n    timeout: Optional[int] = 3600,\n    key: Optional[str] = None,\n    client: PrefectClient = None,\n) -&gt; Optional[T]:\n    \"\"\"\n    Suspends a flow run by stopping code execution until resumed.\n\n    When suspended, the flow run will continue execution until the NEXT task is\n    orchestrated, at which point the flow will exit. Any tasks that have\n    already started will run until completion. When resumed, the flow run will\n    be rescheduled to finish execution. In order suspend a flow run in this\n    way, the flow needs to have an associated deployment and results need to be\n    configured with the `persist_results` option.\n\n    Args:\n        flow_run_id: a flow run id. If supplied, this function will attempt to\n            suspend the specified flow run. If not supplied will attempt to\n            suspend the current flow run.\n        timeout: the number of seconds to wait for the flow to be resumed before\n            failing. Defaults to 1 hour (3600 seconds). If the pause timeout\n            exceeds any configured flow-level timeout, the flow might fail even\n            after resuming.\n        key: An optional key to prevent calling suspend more than once. This\n            defaults to a random string and prevents suspends from running the\n            same suspend twice. A custom key can be supplied for custom\n            suspending behavior.\n        wait_for_input: a subclass of `RunInput` or any type supported by\n            Pydantic. If provided when the flow suspends, the flow will remain\n            suspended until receiving the input before resuming. If the flow is\n            resumed without providing the input, the flow will fail. If the flow is\n            resumed with the input, the flow will resume and the input will be\n            loaded and returned from this function.\n    \"\"\"\n    context = FlowRunContext.get()\n\n    if flow_run_id is None:\n        if TaskRunContext.get():\n            raise RuntimeError(\"Cannot suspend task runs.\")\n\n        if context is None or context.flow_run is None:\n            raise RuntimeError(\n                \"Flow runs can only be suspended from within a flow run.\"\n            )\n\n        logger = get_run_logger(context=context)\n        logger.info(\n            \"Suspending flow run, execution will be rescheduled when this flow run is\"\n            \" resumed.\"\n        )\n        flow_run_id = context.flow_run.id\n        suspending_current_flow_run = True\n        pause_counter = _observed_flow_pauses(context)\n        pause_key = key or str(pause_counter)\n    else:\n        # Since we're suspending another flow run we need to generate a pause\n        # key that won't conflict with whatever suspends/pauses that flow may\n        # have. Since this method won't be called during that flow run it's\n        # okay that this is non-deterministic.\n        suspending_current_flow_run = False\n        pause_key = key or str(uuid4())\n\n    proposed_state = Suspended(timeout_seconds=timeout, pause_key=pause_key)\n\n    if wait_for_input:\n        wait_for_input = run_input_subclass_from_type(wait_for_input)\n        run_input_keyset = keyset_from_paused_state(proposed_state)\n        proposed_state.state_details.run_input_keyset = run_input_keyset\n\n    try:\n        state = await propose_state(\n            client=client,\n            state=proposed_state,\n            flow_run_id=flow_run_id,\n        )\n    except Abort as exc:\n        # Aborted requests mean the suspension is not allowed\n        raise RuntimeError(f\"Flow run cannot be suspended: {exc}\")\n\n    if state.is_running():\n        # The orchestrator rejected the suspended state which means that this\n        # suspend has happened before and the flow run has been resumed.\n        if wait_for_input:\n            # The flow run wanted input, so we need to load it and return it\n            # to the user.\n            return await wait_for_input.load(run_input_keyset)\n        return\n\n    if not state.is_paused():\n        # If we receive anything but a PAUSED state, we are unable to continue\n        raise RuntimeError(\n            f\"Flow run cannot be suspended. Received unexpected state from API: {state}\"\n        )\n\n    if wait_for_input:\n        await wait_for_input.save(run_input_keyset)\n\n    if suspending_current_flow_run:\n        # Exit this process so the run can be resubmitted later\n        raise Pause()\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/events/","title":"prefect.events","text":"","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events","title":"<code>prefect.events</code>","text":"","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.TriggerTypes","title":"<code>TriggerTypes: TypeAlias = Union[EventTrigger, MetricTrigger, CompoundTrigger, SequenceTrigger]</code>  <code>module-attribute</code>","text":"<p>The union of all concrete trigger types that a user may actually create</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Action","title":"<code>Action</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>An Action that may be performed when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class Action(PrefectBaseModel, abc.ABC):\n    \"\"\"An Action that may be performed when an Automation is triggered\"\"\"\n\n    type: str\n\n    def describe_for_cli(self) -&gt; str:\n        \"\"\"A human-readable description of the action\"\"\"\n        return self.type.replace(\"-\", \" \").capitalize()\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Action.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>A human-readable description of the action</p> Source code in <code>prefect/events/actions.py</code> <pre><code>def describe_for_cli(self) -&gt; str:\n    \"\"\"A human-readable description of the action\"\"\"\n    return self.type.replace(\"-\", \" \").capitalize()\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.AutomationCore","title":"<code>AutomationCore</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines an action a user wants to take when a certain number of events do or don't happen to the matching resources</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class AutomationCore(PrefectBaseModel, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"Defines an action a user wants to take when a certain number of events\n    do or don't happen to the matching resources\"\"\"\n\n    name: str = Field(..., description=\"The name of this automation\")\n    description: str = Field(\"\", description=\"A longer description of this automation\")\n\n    enabled: bool = Field(True, description=\"Whether this automation will be evaluated\")\n\n    trigger: TriggerTypes = Field(\n        ...,\n        description=(\n            \"The criteria for which events this Automation covers and how it will \"\n            \"respond to the presence or absence of those events\"\n        ),\n    )\n\n    actions: List[ActionTypes] = Field(\n        ...,\n        description=\"The actions to perform when this Automation triggers\",\n    )\n\n    actions_on_trigger: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a triggered state\",\n    )\n\n    actions_on_resolve: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a resolving state\",\n    )\n\n    owner_resource: Optional[str] = Field(\n        default=None, description=\"The owning resource of this automation\"\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CallWebhook","title":"<code>CallWebhook</code>","text":"<p>               Bases: <code>Action</code></p> <p>Call a webhook when an Automation is triggered.</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class CallWebhook(Action):\n    \"\"\"Call a webhook when an Automation is triggered.\"\"\"\n\n    type: Literal[\"call-webhook\"] = \"call-webhook\"\n    block_document_id: UUID = Field(\n        description=\"The identifier of the webhook block to use\"\n    )\n    payload: str = Field(\n        default=\"\",\n        description=\"An optional templatable payload to send when calling the webhook.\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CancelFlowRun","title":"<code>CancelFlowRun</code>","text":"<p>               Bases: <code>Action</code></p> <p>Cancels a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class CancelFlowRun(Action):\n    \"\"\"Cancels a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"cancel-flow-run\"] = \"cancel-flow-run\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ChangeFlowRunState","title":"<code>ChangeFlowRunState</code>","text":"<p>               Bases: <code>Action</code></p> <p>Changes the state of a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ChangeFlowRunState(Action):\n    \"\"\"Changes the state of a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"change-flow-run-state\"] = \"change-flow-run-state\"\n\n    name: Optional[str] = Field(\n        None,\n        description=\"The name of the state to change the flow run to\",\n    )\n    state: StateType = Field(\n        ...,\n        description=\"The type of the state to change the flow run to\",\n    )\n    message: Optional[str] = Field(\n        None,\n        description=\"An optional message to associate with the state change\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompositeTrigger","title":"<code>CompositeTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Requires some number of triggers to have fired within the given time period.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompositeTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Requires some number of triggers to have fired within the given time period.\n    \"\"\"\n\n    type: Literal[\"compound\", \"sequence\"]\n    triggers: List[\"TriggerTypes\"]\n    within: Optional[timedelta]\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompoundTrigger","title":"<code>CompoundTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompoundTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    type: Literal[\"compound\"] = \"compound\"\n    require: Union[int, Literal[\"any\", \"all\"]]\n\n    @root_validator\n    def validate_require(cls, values: Dict[str, Any]) -&gt; Dict[str, Any]:\n        require = values.get(\"require\")\n\n        if isinstance(require, int):\n            if require &lt; 1:\n                raise ValueError(\"required must be at least 1\")\n            if require &gt; len(values[\"triggers\"]):\n                raise ValueError(\n                    \"required must be less than or equal to the number of triggers\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"{str(self.require).capitalize()} of:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompoundTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"{str(self.require).capitalize()} of:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeclareIncident","title":"<code>DeclareIncident</code>","text":"<p>               Bases: <code>Action</code></p> <p>Declares an incident for the triggering event.  Only available on Prefect Cloud</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class DeclareIncident(Action):\n    \"\"\"Declares an incident for the triggering event.  Only available on Prefect Cloud\"\"\"\n\n    type: Literal[\"declare-incident\"] = \"declare-incident\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentCompoundTrigger","title":"<code>DeploymentCompoundTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>CompoundTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentCompoundTrigger(BaseDeploymentTrigger, CompoundTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    trigger_type = CompoundTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentEventTrigger","title":"<code>DeploymentEventTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>EventTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentEventTrigger(BaseDeploymentTrigger, EventTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    trigger_type = EventTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentMetricTrigger","title":"<code>DeploymentMetricTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>MetricTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentMetricTrigger(BaseDeploymentTrigger, MetricTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    trigger_type = MetricTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentSequenceTrigger","title":"<code>DeploymentSequenceTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>SequenceTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentSequenceTrigger(BaseDeploymentTrigger, SequenceTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    trigger_type = SequenceTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DoNothing","title":"<code>DoNothing</code>","text":"<p>               Bases: <code>Action</code></p> <p>Do nothing when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class DoNothing(Action):\n    \"\"\"Do nothing when an Automation is triggered\"\"\"\n\n    type: Literal[\"do-nothing\"] = \"do-nothing\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event","title":"<code>Event</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>The client-side view of an event that has happened to a Resource</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class Event(PrefectBaseModel):\n    \"\"\"The client-side view of an event that has happened to a Resource\"\"\"\n\n    occurred: DateTimeTZ = Field(\n        default_factory=lambda: pendulum.now(\"UTC\"),\n        description=\"When the event happened from the sender's perspective\",\n    )\n    event: str = Field(\n        description=\"The name of the event that happened\",\n    )\n    resource: Resource = Field(\n        description=\"The primary Resource this event concerns\",\n    )\n    related: List[RelatedResource] = Field(\n        default_factory=list,\n        description=\"A list of additional Resources involved in this event\",\n    )\n    payload: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"An open-ended set of data describing what happened\",\n    )\n    id: UUID = Field(\n        default_factory=uuid4,\n        description=\"The client-provided identifier of this event\",\n    )\n    follows: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The ID of an event that is known to have occurred prior to this one. \"\n            \"If set, this may be used to establish a more precise ordering of causally-\"\n            \"related events when they occur close enough together in time that the \"\n            \"system may receive them out-of-order.\"\n        ),\n    )\n\n    @property\n    def involved_resources(self) -&gt; Sequence[Resource]:\n        return [self.resource] + list(self.related)\n\n    @property\n    def resource_in_role(self) -&gt; Mapping[str, RelatedResource]:\n        \"\"\"Returns a mapping of roles to the first related resource in that role\"\"\"\n        return {related.role: related for related in reversed(self.related)}\n\n    @property\n    def resources_in_role(self) -&gt; Mapping[str, Sequence[RelatedResource]]:\n        \"\"\"Returns a mapping of roles to related resources in that role\"\"\"\n        resources: Dict[str, List[RelatedResource]] = defaultdict(list)\n        for related in self.related:\n            resources[related.role].append(related)\n        return resources\n\n    @validator(\"related\")\n    def enforce_maximum_related_resources(cls, value: List[RelatedResource]):\n        if len(value) &gt; PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value():\n            raise ValueError(\n                \"The maximum number of related resources \"\n                f\"is {PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value()}\"\n            )\n\n        return value\n\n    def find_resource_label(self, label: str) -&gt; Optional[str]:\n        \"\"\"Finds the value of the given label in this event's resource or one of its\n        related resources.  If the label starts with `related:&lt;role&gt;:`, search for the\n        first matching label in a related resource with that role.\"\"\"\n        directive, _, related_label = label.rpartition(\":\")\n        directive, _, role = directive.partition(\":\")\n        if directive == \"related\":\n            for related in self.related:\n                if related.role == role:\n                    return related.get(related_label)\n        return self.resource.get(label)\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.resource_in_role","title":"<code>resource_in_role: Mapping[str, RelatedResource]</code>  <code>property</code>","text":"<p>Returns a mapping of roles to the first related resource in that role</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.resources_in_role","title":"<code>resources_in_role: Mapping[str, Sequence[RelatedResource]]</code>  <code>property</code>","text":"<p>Returns a mapping of roles to related resources in that role</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.find_resource_label","title":"<code>find_resource_label</code>","text":"<p>Finds the value of the given label in this event's resource or one of its related resources.  If the label starts with <code>related:&lt;role&gt;:</code>, search for the first matching label in a related resource with that role.</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>def find_resource_label(self, label: str) -&gt; Optional[str]:\n    \"\"\"Finds the value of the given label in this event's resource or one of its\n    related resources.  If the label starts with `related:&lt;role&gt;:`, search for the\n    first matching label in a related resource with that role.\"\"\"\n    directive, _, related_label = label.rpartition(\":\")\n    directive, _, role = directive.partition(\":\")\n    if directive == \"related\":\n        for related in self.related:\n            if related.role == role:\n                return related.get(related_label)\n    return self.resource.get(label)\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.EventTrigger","title":"<code>EventTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class EventTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    type: Literal[\"event\"] = \"event\"\n\n    after: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) which must first been seen to fire this trigger.  If \"\n            \"empty, then fire this trigger immediately.  Events may include \"\n            \"trailing wildcards, like `prefect.flow-run.*`\"\n        ),\n    )\n    expect: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) this trigger is expecting to see.  If empty, this \"\n            \"trigger will match any event.  Events may include trailing wildcards, \"\n            \"like `prefect.flow-run.*`\"\n        ),\n    )\n\n    for_each: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"Evaluate the trigger separately for each distinct value of these labels \"\n            \"on the resource.  By default, labels refer to the primary resource of the \"\n            \"triggering event.  You may also refer to labels from related \"\n            \"resources by specifying `related:&lt;role&gt;:&lt;label&gt;`.  This will use the \"\n            \"value of that label for the first related resource in that role.  For \"\n            'example, `\"for_each\": [\"related:flow:prefect.resource.id\"]` would '\n            \"evaluate the trigger for each flow.\"\n        ),\n    )\n    posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]\n        Posture.Reactive,\n        description=(\n            \"The posture of this trigger, either Reactive or Proactive.  Reactive \"\n            \"triggers respond to the _presence_ of the expected events, while \"\n            \"Proactive triggers respond to the _absence_ of those expected events.\"\n        ),\n    )\n    threshold: int = Field(\n        1,\n        description=(\n            \"The number of events required for this trigger to fire (for \"\n            \"Reactive triggers), or the number of events expected (for Proactive \"\n            \"triggers)\"\n        ),\n    )\n    within: timedelta = Field(\n        timedelta(0),\n        minimum=0.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The time period over which the events must occur.  For Reactive triggers, \"\n            \"this may be as low as 0 seconds, but must be at least 10 seconds for \"\n            \"Proactive triggers\"\n        ),\n    )\n\n    @validator(\"within\")\n    def enforce_minimum_within(\n        cls, value: timedelta, values, config, field: ModelField\n    ):\n        return validate_trigger_within(value, field)\n\n    @root_validator(skip_on_failure=True)\n    def enforce_minimum_within_for_proactive_triggers(cls, values: Dict[str, Any]):\n        posture: Optional[Posture] = values.get(\"posture\")\n        within: Optional[timedelta] = values.get(\"within\")\n\n        if posture == Posture.Proactive:\n            if not within or within == timedelta(0):\n                values[\"within\"] = timedelta(seconds=10.0)\n            elif within &lt; timedelta(seconds=10.0):\n                raise ValueError(\n                    \"The minimum within for Proactive triggers is 10 seconds\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        if self.posture == Posture.Reactive:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n        else:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                        f\"within {self.within}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.EventTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    if self.posture == Posture.Reactive:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n    else:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                    f\"within {self.within}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTrigger","title":"<code>MetricTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    type: Literal[\"metric\"] = \"metric\"\n\n    posture: Literal[Posture.Metric] = Field(  # type: ignore[valid-type]\n        Posture.Metric,\n        description=\"Periodically evaluate the configured metric query.\",\n    )\n\n    metric: MetricTriggerQuery = Field(\n        ...,\n        description=\"The metric query to evaluate for this trigger. \",\n    )\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        m = self.metric\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    m = self.metric\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTriggerQuery","title":"<code>MetricTriggerQuery</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines a subset of the Trigger subclass, which is specific to Metric automations, that specify the query configurations and breaching conditions for the Automation</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTriggerQuery(PrefectBaseModel):\n    \"\"\"Defines a subset of the Trigger subclass, which is specific\n    to Metric automations, that specify the query configurations\n    and breaching conditions for the Automation\"\"\"\n\n    name: PrefectMetric = Field(\n        ...,\n        description=\"The name of the metric to query.\",\n    )\n    threshold: float = Field(\n        ...,\n        description=(\n            \"The threshold value against which we'll compare \" \"the query result.\"\n        ),\n    )\n    operator: MetricTriggerOperator = Field(\n        ...,\n        description=(\n            \"The comparative operator (LT / LTE / GT / GTE) used to compare \"\n            \"the query result against the threshold value.\"\n        ),\n    )\n    range: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The lookback duration (seconds) for a metric query. This duration is \"\n            \"used to determine the time range over which the query will be executed. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n    firing_for: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The duration (seconds) for which the metric query must breach \"\n            \"or resolve continuously before the state is updated and the \"\n            \"automation is triggered. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseAutomation","title":"<code>PauseAutomation</code>","text":"<p>               Bases: <code>AutomationAction</code></p> <p>Pauses a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseAutomation(AutomationAction):\n    \"\"\"Pauses a Work Queue\"\"\"\n\n    type: Literal[\"pause-automation\"] = \"pause-automation\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseDeployment","title":"<code>PauseDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Pauses the given Deployment</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseDeployment(DeploymentAction):\n    \"\"\"Pauses the given Deployment\"\"\"\n\n    type: Literal[\"pause-deployment\"] = \"pause-deployment\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseWorkPool","title":"<code>PauseWorkPool</code>","text":"<p>               Bases: <code>WorkPoolAction</code></p> <p>Pauses a Work Pool</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseWorkPool(WorkPoolAction):\n    \"\"\"Pauses a Work Pool\"\"\"\n\n    type: Literal[\"pause-work-pool\"] = \"pause-work-pool\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseWorkQueue","title":"<code>PauseWorkQueue</code>","text":"<p>               Bases: <code>WorkQueueAction</code></p> <p>Pauses a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseWorkQueue(WorkQueueAction):\n    \"\"\"Pauses a Work Queue\"\"\"\n\n    type: Literal[\"pause-work-queue\"] = \"pause-work-queue\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ReceivedEvent","title":"<code>ReceivedEvent</code>","text":"<p>               Bases: <code>Event</code></p> <p>The server-side view of an event that has happened to a Resource after it has been received by the server</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ReceivedEvent(Event):\n    \"\"\"The server-side view of an event that has happened to a Resource after it has\n    been received by the server\"\"\"\n\n    class Config:\n        orm_mode = True\n\n    received: DateTimeTZ = Field(\n        ...,\n        description=\"When the event was received by Prefect Cloud\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.RelatedResource","title":"<code>RelatedResource</code>","text":"<p>               Bases: <code>Resource</code></p> <p>A Resource with a specific role in an Event</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class RelatedResource(Resource):\n    \"\"\"A Resource with a specific role in an Event\"\"\"\n\n    @root_validator(pre=True)\n    def requires_resource_role(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        labels = cast(Dict[str, str], labels)\n\n        if \"prefect.resource.role\" not in labels:\n            raise ValueError(\n                \"Related Resources must include the prefect.resource.role label\"\n            )\n        if not labels[\"prefect.resource.role\"]:\n            raise ValueError(\"The prefect.resource.role label must be non-empty\")\n\n        return values\n\n    @property\n    def role(self) -&gt; str:\n        return self[\"prefect.resource.role\"]\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Resource","title":"<code>Resource</code>","text":"<p>               Bases: <code>Labelled</code></p> <p>An observable business object of interest to the user</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class Resource(Labelled):\n    \"\"\"An observable business object of interest to the user\"\"\"\n\n    @root_validator(pre=True)\n    def enforce_maximum_labels(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        if len(labels) &gt; PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value():\n            raise ValueError(\n                \"The maximum number of labels per resource \"\n                f\"is {PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value()}\"\n            )\n\n        return values\n\n    @root_validator(pre=True)\n    def requires_resource_id(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        labels = cast(Dict[str, str], labels)\n\n        if \"prefect.resource.id\" not in labels:\n            raise ValueError(\"Resources must include the prefect.resource.id label\")\n        if not labels[\"prefect.resource.id\"]:\n            raise ValueError(\"The prefect.resource.id label must be non-empty\")\n\n        return values\n\n    @property\n    def id(self) -&gt; str:\n        return self[\"prefect.resource.id\"]\n\n    @property\n    def name(self) -&gt; Optional[str]:\n        return self.get(\"prefect.resource.name\")\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResourceSpecification","title":"<code>ResourceSpecification</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation.  A resource must match at least one value of all of the provided labels</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ResourceSpecification(PrefectBaseModel):\n    \"\"\"A specification that may match zero, one, or many resources, used to target or\n    select a set of resources in a query or automation.  A resource must match at least\n    one value of all of the provided labels\"\"\"\n\n    __root__: Dict[str, Union[str, List[str]]]\n\n    def matches_every_resource(self) -&gt; bool:\n        return len(self) == 0\n\n    def matches_every_resource_of_kind(self, prefix: str) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        if len(self.__root__) == 1:\n            if resource_id := self.__root__.get(\"prefect.resource.id\"):\n                values = [resource_id] if isinstance(resource_id, str) else resource_id\n                return any(value == f\"{prefix}.*\" for value in values)\n\n        return False\n\n    def includes(self, candidates: Iterable[Resource]) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        for candidate in candidates:\n            if self.matches(candidate):\n                return True\n\n        return False\n\n    def matches(self, resource: Resource) -&gt; bool:\n        for label, expected in self.items():\n            value = resource.get(label)\n            if not any(matches(candidate, value) for candidate in expected):\n                return False\n        return True\n\n    def items(self) -&gt; Iterable[Tuple[str, List[str]]]:\n        return [\n            (label, [value] if isinstance(value, str) else value)\n            for label, value in self.__root__.items()\n        ]\n\n    def __contains__(self, key: str) -&gt; bool:\n        return self.__root__.__contains__(key)\n\n    def __getitem__(self, key: str) -&gt; List[str]:\n        value = self.__root__[key]\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def pop(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.pop(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def get(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.get(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def __len__(self) -&gt; int:\n        return len(self.__root__)\n\n    def deepcopy(self) -&gt; \"ResourceSpecification\":\n        return ResourceSpecification.parse_obj(copy.deepcopy(self.__root__))\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResourceTrigger","title":"<code>ResourceTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Base class for triggers that may filter by the labels of resources.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class ResourceTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Base class for triggers that may filter by the labels of resources.\n    \"\"\"\n\n    type: str\n\n    match: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for resources which this trigger will match.\",\n    )\n    match_related: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for related resources which this trigger will match.\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeAutomation","title":"<code>ResumeAutomation</code>","text":"<p>               Bases: <code>AutomationAction</code></p> <p>Resumes a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeAutomation(AutomationAction):\n    \"\"\"Resumes a Work Queue\"\"\"\n\n    type: Literal[\"resume-automation\"] = \"resume-automation\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeDeployment","title":"<code>ResumeDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Resumes the given Deployment</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeDeployment(DeploymentAction):\n    \"\"\"Resumes the given Deployment\"\"\"\n\n    type: Literal[\"resume-deployment\"] = \"resume-deployment\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeWorkPool","title":"<code>ResumeWorkPool</code>","text":"<p>               Bases: <code>WorkPoolAction</code></p> <p>Resumes a Work Pool</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeWorkPool(WorkPoolAction):\n    \"\"\"Resumes a Work Pool\"\"\"\n\n    type: Literal[\"resume-work-pool\"] = \"resume-work-pool\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeWorkQueue","title":"<code>ResumeWorkQueue</code>","text":"<p>               Bases: <code>WorkQueueAction</code></p> <p>Resumes a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeWorkQueue(WorkQueueAction):\n    \"\"\"Resumes a Work Queue\"\"\"\n\n    type: Literal[\"resume-work-queue\"] = \"resume-work-queue\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.RunDeployment","title":"<code>RunDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Runs the given deployment with the given parameters</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class RunDeployment(DeploymentAction):\n    \"\"\"Runs the given deployment with the given parameters\"\"\"\n\n    type: Literal[\"run-deployment\"] = \"run-deployment\"\n\n    parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"The parameters to pass to the deployment, or None to use the \"\n            \"deployment's default parameters\"\n        ),\n    )\n    job_variables: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"The job variables to pass to the created flow run, or None \"\n            \"to use the deployment's default job variables\"\n        ),\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SendNotification","title":"<code>SendNotification</code>","text":"<p>               Bases: <code>Action</code></p> <p>Send a notification when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class SendNotification(Action):\n    \"\"\"Send a notification when an Automation is triggered\"\"\"\n\n    type: Literal[\"send-notification\"] = \"send-notification\"\n    block_document_id: UUID = Field(\n        description=\"The identifier of the notification block to use\"\n    )\n    subject: str = Field(\"Prefect automated notification\")\n    body: str = Field(description=\"The text of the notification to send\")\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SequenceTrigger","title":"<code>SequenceTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class SequenceTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    type: Literal[\"sequence\"] = \"sequence\"\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    \"In this order:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SequenceTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                \"In this order:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SuspendFlowRun","title":"<code>SuspendFlowRun</code>","text":"<p>               Bases: <code>Action</code></p> <p>Suspends a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class SuspendFlowRun(Action):\n    \"\"\"Suspends a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"suspend-flow-run\"] = \"suspend-flow-run\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Trigger","title":"<code>Trigger</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>Base class describing a set of criteria that must be satisfied in order to trigger an automation.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class Trigger(PrefectBaseModel, abc.ABC, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"\n    Base class describing a set of criteria that must be satisfied in order to trigger\n    an automation.\n    \"\"\"\n\n    type: str\n\n    @abc.abstractmethod\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n\n    # The following allows the regular Trigger class to be used when serving or\n    # deploying flows, analogous to how the Deployment*Trigger classes work\n\n    _deployment_id: Optional[UUID] = PrivateAttr(default=None)\n\n    def set_deployment_id(self, deployment_id: UUID):\n        self._deployment_id = deployment_id\n\n    def owner_resource(self) -&gt; Optional[str]:\n        return f\"prefect.deployment.{self._deployment_id}\"\n\n    def actions(self) -&gt; List[ActionTypes]:\n        assert self._deployment_id\n        return [\n            RunDeployment(\n                source=\"selected\",\n                deployment_id=self._deployment_id,\n                parameters=getattr(self, \"parameters\", None),\n                job_variables=getattr(self, \"job_variables\", None),\n            )\n        ]\n\n    def as_automation(self) -&gt; \"AutomationCore\":\n        assert self._deployment_id\n\n        trigger: TriggerTypes = cast(TriggerTypes, self)\n\n        # This is one of the Deployment*Trigger classes, so translate it over to a\n        # plain Trigger\n        if hasattr(self, \"trigger_type\"):\n            trigger = self.trigger_type(**self.dict())\n\n        return AutomationCore(\n            name=(\n                getattr(self, \"name\", None)\n                or f\"Automation for deployment {self._deployment_id}\"\n            ),\n            description=\"\",\n            enabled=getattr(self, \"enabled\", True),\n            trigger=trigger,\n            actions=self.actions(),\n            owner_resource=self.owner_resource(),\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Trigger.describe_for_cli","title":"<code>describe_for_cli</code>  <code>abstractmethod</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>@abc.abstractmethod\ndef describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.emit_event","title":"<code>emit_event</code>","text":"<p>Send an event to Prefect Cloud.</p> <p>Parameters:</p> Name Type Description Default <code>event</code> <code>str</code> <p>The name of the event that happened.</p> required <code>resource</code> <code>Dict[str, str]</code> <p>The primary Resource this event concerns.</p> required <code>occurred</code> <code>Optional[DateTimeTZ]</code> <p>When the event happened from the sender's perspective.       Defaults to the current datetime.</p> <code>None</code> <code>related</code> <code>Optional[Union[List[Dict[str, str]], List[RelatedResource]]]</code> <p>A list of additional Resources involved in this event.</p> <code>None</code> <code>payload</code> <code>Optional[Dict[str, Any]]</code> <p>An open-ended set of data describing what happened.</p> <code>None</code> <code>id</code> <code>Optional[UUID]</code> <p>The sender-provided identifier for this event. Defaults to a random UUID.</p> <code>None</code> <code>follows</code> <code>Optional[Event]</code> <p>The event that preceded this one. If the preceding event happened more than 5 minutes prior to this event the follows relationship will not be set.</p> <code>None</code> <p>Returns:</p> Type Description <code>Optional[Event]</code> <p>The event that was emitted if worker is using a client that emit</p> <code>Optional[Event]</code> <p>events, otherwise None</p> Source code in <code>prefect/events/utilities.py</code> <pre><code>def emit_event(\n    event: str,\n    resource: Dict[str, str],\n    occurred: Optional[DateTimeTZ] = None,\n    related: Optional[Union[List[Dict[str, str]], List[RelatedResource]]] = None,\n    payload: Optional[Dict[str, Any]] = None,\n    id: Optional[UUID] = None,\n    follows: Optional[Event] = None,\n) -&gt; Optional[Event]:\n    \"\"\"\n    Send an event to Prefect Cloud.\n\n    Args:\n        event: The name of the event that happened.\n        resource: The primary Resource this event concerns.\n        occurred: When the event happened from the sender's perspective.\n                  Defaults to the current datetime.\n        related: A list of additional Resources involved in this event.\n        payload: An open-ended set of data describing what happened.\n        id: The sender-provided identifier for this event. Defaults to a random\n            UUID.\n        follows: The event that preceded this one. If the preceding event\n            happened more than 5 minutes prior to this event the follows\n            relationship will not be set.\n\n    Returns:\n        The event that was emitted if worker is using a client that emit\n        events, otherwise None\n    \"\"\"\n    if not should_emit_events():\n        return None\n\n    operational_clients = [\n        AssertingEventsClient,\n        PrefectCloudEventsClient,\n        PrefectEventsClient,\n        PrefectEphemeralEventsClient,\n    ]\n    worker_instance = EventsWorker.instance()\n\n    if worker_instance.client_type not in operational_clients:\n        return None\n\n    event_kwargs: Dict[str, Any] = {\n        \"event\": event,\n        \"resource\": resource,\n    }\n\n    if occurred is None:\n        occurred = pendulum.now(\"UTC\")\n    event_kwargs[\"occurred\"] = occurred\n\n    if related is not None:\n        event_kwargs[\"related\"] = related\n\n    if payload is not None:\n        event_kwargs[\"payload\"] = payload\n\n    if id is not None:\n        event_kwargs[\"id\"] = id\n\n    if follows is not None:\n        if -TIGHT_TIMING &lt; (occurred - follows.occurred) &lt; TIGHT_TIMING:\n            event_kwargs[\"follows\"] = follows.id\n\n    event_obj = Event(**event_kwargs)\n    worker_instance.send(event_obj)\n\n    return event_obj\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/exceptions/","title":"prefect.exceptions","text":"","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions","title":"<code>prefect.exceptions</code>","text":"<p>Prefect-specific exceptions.</p>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.Abort","title":"<code>Abort</code>","text":"<p>               Bases: <code>PrefectSignal</code></p> <p>Raised when the API sends an 'ABORT' instruction during state proposal.</p> <p>Indicates that the run should exit immediately.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class Abort(PrefectSignal):\n    \"\"\"\n    Raised when the API sends an 'ABORT' instruction during state proposal.\n\n    Indicates that the run should exit immediately.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.BlockMissingCapabilities","title":"<code>BlockMissingCapabilities</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a block does not have required capabilities for a given operation.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class BlockMissingCapabilities(PrefectException):\n    \"\"\"\n    Raised when a block does not have required capabilities for a given operation.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.CancelledRun","title":"<code>CancelledRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a cancelled run is retrieved and an exception is not attached.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class CancelledRun(PrefectException):\n    \"\"\"\n    Raised when the result from a cancelled run is retrieved and an exception\n    is not attached.\n\n    This occurs when a string is attached to the state instead of an exception\n    or if the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.CrashedRun","title":"<code>CrashedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a crashed run is retrieved.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class CrashedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a crashed run is retrieved.\n\n    This occurs when a string is attached to the state instead of an exception or if\n    the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ExternalSignal","title":"<code>ExternalSignal</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>Base type for external signal-like exceptions that should never be caught by users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ExternalSignal(BaseException):\n    \"\"\"\n    Base type for external signal-like exceptions that should never be caught by users.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FailedRun","title":"<code>FailedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a failed run is retrieved and an exception is not attached.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FailedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a failed run is retrieved and an exception is not\n    attached.\n\n    This occurs when a string is attached to the state instead of an exception or if\n    the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowPauseTimeout","title":"<code>FlowPauseTimeout</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a flow pause times out</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowPauseTimeout(PrefectException):\n    \"\"\"Raised when a flow pause times out\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowRunWaitTimeout","title":"<code>FlowRunWaitTimeout</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a flow run takes longer than a given timeout</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowRunWaitTimeout(PrefectException):\n    \"\"\"Raised when a flow run takes longer than a given timeout\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowScriptError","title":"<code>FlowScriptError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a script errors during evaluation while attempting to load a flow.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowScriptError(PrefectException):\n    \"\"\"\n    Raised when a script errors during evaluation while attempting to load a flow.\n    \"\"\"\n\n    def __init__(\n        self,\n        user_exc: Exception,\n        script_path: str,\n    ) -&gt; None:\n        message = f\"Flow script at {script_path!r} encountered an exception\"\n        super().__init__(message)\n\n        self.user_exc = user_exc\n\n    def rich_user_traceback(self, **kwargs):\n        trace = Traceback.extract(\n            type(self.user_exc),\n            self.user_exc,\n            self.user_exc.__traceback__.tb_next.tb_next.tb_next.tb_next,\n        )\n        return Traceback(trace, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureError","title":"<code>InfrastructureError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>A base class for exceptions related to infrastructure blocks</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureError(PrefectException):\n    \"\"\"\n    A base class for exceptions related to infrastructure blocks\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureNotAvailable","title":"<code>InfrastructureNotAvailable</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when infrastructure is not accessible from the current machine. For example, if a process was spawned on another machine it cannot be managed.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureNotAvailable(PrefectException):\n    \"\"\"\n    Raised when infrastructure is not accessible from the current machine. For example,\n    if a process was spawned on another machine it cannot be managed.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureNotFound","title":"<code>InfrastructureNotFound</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when infrastructure is missing, likely because it has exited or been deleted.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureNotFound(PrefectException):\n    \"\"\"\n    Raised when infrastructure is missing, likely because it has exited or been\n    deleted.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InvalidNameError","title":"<code>InvalidNameError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>ValueError</code></p> <p>Raised when a name contains characters that are not permitted.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InvalidNameError(PrefectException, ValueError):\n    \"\"\"\n    Raised when a name contains characters that are not permitted.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InvalidRepositoryURLError","title":"<code>InvalidRepositoryURLError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when an incorrect URL is provided to a GitHub filesystem block.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InvalidRepositoryURLError(PrefectException):\n    \"\"\"Raised when an incorrect URL is provided to a GitHub filesystem block.\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MappingLengthMismatch","title":"<code>MappingLengthMismatch</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to call Task.map with arguments of different lengths.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MappingLengthMismatch(PrefectException):\n    \"\"\"\n    Raised when attempting to call Task.map with arguments of different lengths.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MappingMissingIterable","title":"<code>MappingMissingIterable</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to call Task.map with all static arguments</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MappingMissingIterable(PrefectException):\n    \"\"\"\n    Raised when attempting to call Task.map with all static arguments\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingContextError","title":"<code>MissingContextError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>RuntimeError</code></p> <p>Raised when a method is called that requires a task or flow run context to be active but one cannot be found.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingContextError(PrefectException, RuntimeError):\n    \"\"\"\n    Raised when a method is called that requires a task or flow run context to be\n    active but one cannot be found.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingFlowError","title":"<code>MissingFlowError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a given flow name is not found in the expected script.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingFlowError(PrefectException):\n    \"\"\"\n    Raised when a given flow name is not found in the expected script.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingProfileError","title":"<code>MissingProfileError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>ValueError</code></p> <p>Raised when a profile name does not exist.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingProfileError(PrefectException, ValueError):\n    \"\"\"\n    Raised when a profile name does not exist.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingResult","title":"<code>MissingResult</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a result is missing from a state; often when result persistence is disabled and the state is retrieved from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingResult(PrefectException):\n    \"\"\"\n    Raised when a result is missing from a state; often when result persistence is\n    disabled and the state is retrieved from the API.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.NotPausedError","title":"<code>NotPausedError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to unpause a run that isn't paused.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class NotPausedError(PrefectException):\n    \"\"\"Raised when attempting to unpause a run that isn't paused.\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ObjectAlreadyExists","title":"<code>ObjectAlreadyExists</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the client receives a 409 (conflict) from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ObjectAlreadyExists(PrefectException):\n    \"\"\"\n    Raised when the client receives a 409 (conflict) from the API.\n    \"\"\"\n\n    def __init__(self, http_exc: Exception, *args, **kwargs):\n        self.http_exc = http_exc\n        super().__init__(*args, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ObjectNotFound","title":"<code>ObjectNotFound</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the client receives a 404 (not found) from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ObjectNotFound(PrefectException):\n    \"\"\"\n    Raised when the client receives a 404 (not found) from the API.\n    \"\"\"\n\n    def __init__(self, http_exc: Exception, *args, **kwargs):\n        self.http_exc = http_exc\n        super().__init__(*args, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ParameterBindError","title":"<code>ParameterBindError</code>","text":"<p>               Bases: <code>TypeError</code>, <code>PrefectException</code></p> <p>Raised when args and kwargs cannot be converted to parameters.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ParameterBindError(TypeError, PrefectException):\n    \"\"\"\n    Raised when args and kwargs cannot be converted to parameters.\n    \"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_bind_failure(\n        cls, fn: Callable, exc: TypeError, call_args: List, call_kwargs: Dict\n    ) -&gt; Self:\n        fn_signature = str(inspect.signature(fn)).strip(\"()\")\n\n        base = f\"Error binding parameters for function '{fn.__name__}': {exc}\"\n        signature = f\"Function '{fn.__name__}' has signature '{fn_signature}'\"\n        received = f\"received args: {call_args} and kwargs: {list(call_kwargs.keys())}\"\n        msg = f\"{base}.\\n{signature} but {received}.\"\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ParameterTypeError","title":"<code>ParameterTypeError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a parameter does not pass Pydantic type validation.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ParameterTypeError(PrefectException):\n    \"\"\"\n    Raised when a parameter does not pass Pydantic type validation.\n    \"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_validation_error(cls, exc: ValidationError) -&gt; Self:\n        bad_params = [\n            f'{\".\".join(str(item) for item in err[\"loc\"])}: {err[\"msg\"]}'\n            for err in exc.errors()\n        ]\n        msg = \"Flow run received invalid parameters:\\n - \" + \"\\n - \".join(bad_params)\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.Pause","title":"<code>Pause</code>","text":"<p>               Bases: <code>PrefectSignal</code></p> <p>Raised when a flow run is PAUSED and needs to exit for resubmission.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class Pause(PrefectSignal):\n    \"\"\"\n    Raised when a flow run is PAUSED and needs to exit for resubmission.\n    \"\"\"\n\n    def __init__(self, *args, state=None, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.state = state\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PausedRun","title":"<code>PausedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a paused run is retrieved.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PausedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a paused run is retrieved.\n    \"\"\"\n\n    def __init__(self, *args, state=None, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.state = state\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectException","title":"<code>PrefectException</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Base exception type for Prefect errors.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectException(Exception):\n    \"\"\"\n    Base exception type for Prefect errors.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectHTTPStatusError","title":"<code>PrefectHTTPStatusError</code>","text":"<p>               Bases: <code>HTTPStatusError</code></p> <p>Raised when client receives a <code>Response</code> that contains an HTTPStatusError.</p> <p>Used to include API error details in the error messages that the client provides users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectHTTPStatusError(HTTPStatusError):\n    \"\"\"\n    Raised when client receives a `Response` that contains an HTTPStatusError.\n\n    Used to include API error details in the error messages that the client provides users.\n    \"\"\"\n\n    @classmethod\n    def from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -&gt; Self:\n        \"\"\"\n        Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.\n        \"\"\"\n        try:\n            details = httpx_error.response.json()\n        except Exception:\n            details = None\n\n        error_message, *more_info = str(httpx_error).split(\"\\n\")\n\n        if details:\n            message_components = [error_message, f\"Response: {details}\", *more_info]\n        else:\n            message_components = [error_message, *more_info]\n\n        new_message = \"\\n\".join(message_components)\n\n        return cls(\n            new_message, request=httpx_error.request, response=httpx_error.response\n        )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectHTTPStatusError.from_httpx_error","title":"<code>from_httpx_error</code>  <code>classmethod</code>","text":"<p>Generate a <code>PrefectHTTPStatusError</code> from an <code>httpx.HTTPStatusError</code>.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>@classmethod\ndef from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -&gt; Self:\n    \"\"\"\n    Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.\n    \"\"\"\n    try:\n        details = httpx_error.response.json()\n    except Exception:\n        details = None\n\n    error_message, *more_info = str(httpx_error).split(\"\\n\")\n\n    if details:\n        message_components = [error_message, f\"Response: {details}\", *more_info]\n    else:\n        message_components = [error_message, *more_info]\n\n    new_message = \"\\n\".join(message_components)\n\n    return cls(\n        new_message, request=httpx_error.request, response=httpx_error.response\n    )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectSignal","title":"<code>PrefectSignal</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>Base type for signal-like exceptions that should never be caught by users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectSignal(BaseException):\n    \"\"\"\n    Base type for signal-like exceptions that should never be caught by users.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ProtectedBlockError","title":"<code>ProtectedBlockError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when an operation is prevented due to block protection.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ProtectedBlockError(PrefectException):\n    \"\"\"\n    Raised when an operation is prevented due to block protection.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ReservedArgumentError","title":"<code>ReservedArgumentError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>TypeError</code></p> <p>Raised when a function used with Prefect has an argument with a name that is reserved for a Prefect feature</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ReservedArgumentError(PrefectException, TypeError):\n    \"\"\"\n    Raised when a function used with Prefect has an argument with a name that is\n    reserved for a Prefect feature\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ScriptError","title":"<code>ScriptError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a script errors during evaluation while attempting to load data</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ScriptError(PrefectException):\n    \"\"\"\n    Raised when a script errors during evaluation while attempting to load data\n    \"\"\"\n\n    def __init__(\n        self,\n        user_exc: Exception,\n        path: str,\n    ) -&gt; None:\n        message = f\"Script at {str(path)!r} encountered an exception: {user_exc!r}\"\n        super().__init__(message)\n        self.user_exc = user_exc\n\n        # Strip script run information from the traceback\n        self.user_exc.__traceback__ = _trim_traceback(\n            self.user_exc.__traceback__,\n            remove_modules=[prefect.utilities.importtools],\n        )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.SignatureMismatchError","title":"<code>SignatureMismatchError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>TypeError</code></p> <p>Raised when parameters passed to a function do not match its signature.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class SignatureMismatchError(PrefectException, TypeError):\n    \"\"\"Raised when parameters passed to a function do not match its signature.\"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_bad_params(cls, expected_params: List[str], provided_params: List[str]):\n        msg = (\n            f\"Function expects parameters {expected_params} but was provided with\"\n            f\" parameters {provided_params}\"\n        )\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.TerminationSignal","title":"<code>TerminationSignal</code>","text":"<p>               Bases: <code>ExternalSignal</code></p> <p>Raised when a flow run receives a termination signal.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class TerminationSignal(ExternalSignal):\n    \"\"\"\n    Raised when a flow run receives a termination signal.\n    \"\"\"\n\n    def __init__(self, signal: int):\n        self.signal = signal\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UnfinishedRun","title":"<code>UnfinishedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a run that is not finished is retrieved.</p> <p>For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UnfinishedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a run that is not finished is retrieved.\n\n    For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UnspecifiedFlowError","title":"<code>UnspecifiedFlowError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when multiple flows are found in the expected script and no name is given.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UnspecifiedFlowError(PrefectException):\n    \"\"\"\n    Raised when multiple flows are found in the expected script and no name is given.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UpstreamTaskError","title":"<code>UpstreamTaskError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a task relies on the result of another task but that task is not 'COMPLETE'</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UpstreamTaskError(PrefectException):\n    \"\"\"\n    Raised when a task relies on the result of another task but that task is not\n    'COMPLETE'\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.exception_traceback","title":"<code>exception_traceback</code>","text":"<p>Convert an exception to a printable string with a traceback</p> Source code in <code>prefect/exceptions.py</code> <pre><code>def exception_traceback(exc: Exception) -&gt; str:\n    \"\"\"\n    Convert an exception to a printable string with a traceback\n    \"\"\"\n    tb = traceback.TracebackException.from_exception(exc)\n    return \"\".join(list(tb.format()))\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/filesystems/","title":"prefect.filesystems","text":"","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems","title":"<code>prefect.filesystems</code>","text":"","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure","title":"<code>Azure</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>AzureBlobStorageContainer</code> from the <code>prefect-azure</code> package, which offers enhanced functionality and better a better user experience.</p> <p>Store data as a file on Azure Datalake and Azure Blob Storage.</p> Example <p>Load stored Azure config: <pre><code>from prefect.filesystems import Azure\n\naz_block = Azure.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `AzureBlobStorageContainer` block from prefect-azure instead.\",\n)\nclass Azure(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `AzureBlobStorageContainer` from the `prefect-azure` package, which\n    offers enhanced functionality and better a better user experience.\n\n    Store data as a file on Azure Datalake and Azure Blob Storage.\n\n    Example:\n        Load stored Azure config:\n        ```python\n        from prefect.filesystems import Azure\n\n        az_block = Azure.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#azure\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"An Azure storage bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    azure_storage_connection_string: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage connection string\",\n        description=(\n            \"Equivalent to the AZURE_STORAGE_CONNECTION_STRING environment variable.\"\n        ),\n    )\n    azure_storage_account_name: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage account name\",\n        description=(\n            \"Equivalent to the AZURE_STORAGE_ACCOUNT_NAME environment variable.\"\n        ),\n    )\n    azure_storage_account_key: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage account key\",\n        description=\"Equivalent to the AZURE_STORAGE_ACCOUNT_KEY environment variable.\",\n    )\n    azure_storage_tenant_id: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage tenant ID\",\n        description=\"Equivalent to the AZURE_TENANT_ID environment variable.\",\n    )\n    azure_storage_client_id: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage client ID\",\n        description=\"Equivalent to the AZURE_CLIENT_ID environment variable.\",\n    )\n    azure_storage_client_secret: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage client secret\",\n        description=\"Equivalent to the AZURE_CLIENT_SECRET environment variable.\",\n    )\n    azure_storage_anon: bool = Field(\n        default=True,\n        title=\"Azure storage anonymous connection\",\n        description=(\n            \"Set the 'anon' flag for ADLFS. This should be False for systems that\"\n            \" require ADLFS to use DefaultAzureCredentials.\"\n        ),\n    )\n    azure_storage_container: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage container\",\n        description=(\n            \"Blob Container in Azure Storage Account. If set the 'bucket_path' will\"\n            \" be interpreted using the following URL format:\"\n            \"'az://&lt;container&gt;@&lt;storage_account&gt;.dfs.core.windows.net/&lt;bucket_path&gt;'.\"\n        ),\n    )\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        if self.azure_storage_container:\n            return (\n                f\"az://{self.azure_storage_container.get_secret_value()}\"\n                f\"@{self.azure_storage_account_name.get_secret_value()}\"\n                f\".dfs.core.windows.net/{self.bucket_path}\"\n            )\n        else:\n            return f\"az://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.azure_storage_connection_string:\n            settings[\n                \"connection_string\"\n            ] = self.azure_storage_connection_string.get_secret_value()\n        if self.azure_storage_account_name:\n            settings[\n                \"account_name\"\n            ] = self.azure_storage_account_name.get_secret_value()\n        if self.azure_storage_account_key:\n            settings[\"account_key\"] = self.azure_storage_account_key.get_secret_value()\n        if self.azure_storage_tenant_id:\n            settings[\"tenant_id\"] = self.azure_storage_tenant_id.get_secret_value()\n        if self.azure_storage_client_id:\n            settings[\"client_id\"] = self.azure_storage_client_id.get_secret_value()\n        if self.azure_storage_client_secret:\n            settings[\n                \"client_secret\"\n            ] = self.azure_storage_client_secret.get_secret_value()\n        settings[\"anon\"] = self.azure_storage_anon\n        self._remote_file_system = RemoteFileSystem(\n            basepath=self.basepath, settings=settings\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS","title":"<code>GCS</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>GcsBucket</code> from the <code>prefect-gcp</code> package, which offers enhanced functionality and better a better user experience. Store data as a file on Google Cloud Storage.</p> Example <p>Load stored GCS config: <pre><code>from prefect.filesystems import GCS\n\ngcs_block = GCS.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\", help=\"Use the `GcsBucket` block from prefect-gcp instead.\"\n)\nclass GCS(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `GcsBucket` from the `prefect-gcp` package, which offers enhanced functionality\n    and better a better user experience.\n    Store data as a file on Google Cloud Storage.\n\n    Example:\n        Load stored GCS config:\n        ```python\n        from prefect.filesystems import GCS\n\n        gcs_block = GCS.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/422d13bb838cf247eb2b2cf229ce6a2e717d601b-256x256.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#gcs\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"A GCS bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    service_account_info: Optional[SecretStr] = Field(\n        default=None,\n        description=\"The contents of a service account keyfile as a JSON string.\",\n    )\n    project: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The project the GCS bucket resides in. If not provided, the project will\"\n            \" be inferred from the credentials or environment.\"\n        ),\n    )\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"gcs://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.service_account_info:\n            try:\n                settings[\"token\"] = json.loads(\n                    self.service_account_info.get_secret_value()\n                )\n            except json.JSONDecodeError:\n                raise ValueError(\n                    \"Unable to load provided service_account_info. Please make sure\"\n                    \" that the provided value is a valid JSON string.\"\n                )\n        remote_file_system = RemoteFileSystem(\n            basepath=f\"gcs://{self.bucket_path}\", settings=settings\n        )\n        return remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GitHub","title":"<code>GitHub</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <pre><code>DEPRECATION WARNING:\n\nThis class is deprecated as of March 2024 and will not be available after September 2024.\nIt has been replaced by `GitHubRepository` from the `prefect-github` package, which offers\nenhanced functionality and better a better user experience.\n</code></pre> <p>q     Interact with files stored on GitHub repositories.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `GitHubRepository` block from prefect-github instead.\",\n)\nclass GitHub(ReadableDeploymentStorage):\n    \"\"\"\n        DEPRECATION WARNING:\n\n        This class is deprecated as of March 2024 and will not be available after September 2024.\n        It has been replaced by `GitHubRepository` from the `prefect-github` package, which offers\n        enhanced functionality and better a better user experience.\n    q\n        Interact with files stored on GitHub repositories.\n    \"\"\"\n\n    _block_type_name = \"GitHub\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#github\"\n\n    repository: str = Field(\n        default=...,\n        description=(\n            \"The URL of a GitHub repository to read from, in either HTTPS or SSH\"\n            \" format.\"\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    access_token: Optional[SecretStr] = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=(\n            \"A GitHub Personal Access Token (PAT) with repo scope.\"\n            \" To use a fine-grained PAT, provide '{username}:{PAT}' as the value.\"\n        ),\n    )\n    include_git_objects: bool = Field(\n        default=True,\n        description=(\n            \"Whether to include git objects when copying the repo contents to a\"\n            \" directory.\"\n        ),\n    )\n\n    @validator(\"access_token\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict) -&gt; str:\n        return validate_github_access_token(v, values)\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos: https://&lt;oauth-key&gt;@github.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urllib.parse.urlparse(self.repository)\n        if url_components.scheme == \"https\" and self.access_token is not None:\n            updated_components = url_components._replace(\n                netloc=f\"{self.access_token.get_secret_value()}@{url_components.netloc}\"\n            )\n            full_url = urllib.parse.urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: str\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitHubRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitHub project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        cmd += [\"--depth\", \"1\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            ignore_func = None\n            if not self.include_git_objects:\n                ignore_func = ignore_patterns(\".git\")\n\n            copytree(\n                src=content_source,\n                dst=content_destination,\n                dirs_exist_ok=True,\n                ignore=ignore_func,\n            )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GitHub.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitHub project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    cmd += [\"--depth\", \"1\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        ignore_func = None\n        if not self.include_git_objects:\n            ignore_func = ignore_patterns(\".git\")\n\n        copytree(\n            src=content_source,\n            dst=content_destination,\n            dirs_exist_ok=True,\n            ignore=ignore_func,\n        )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem","title":"<code>LocalFileSystem</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a local file system.</p> Example <p>Load stored local file system config: <pre><code>from prefect.filesystems import LocalFileSystem\n\nlocal_file_system_block = LocalFileSystem.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a local file system.\n\n    Example:\n        Load stored local file system config:\n        ```python\n        from prefect.filesystems import LocalFileSystem\n\n        local_file_system_block = LocalFileSystem.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Local File System\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/ad39089fa66d273b943394a68f003f7a19aa850e-48x48.png\"\n    _documentation_url = (\n        \"https://docs.prefect.io/concepts/filesystems/#local-filesystem\"\n    )\n\n    basepath: Optional[str] = Field(\n        default=None, description=\"Default local path for this block to write to.\"\n    )\n\n    @validator(\"basepath\", pre=True)\n    def cast_pathlib(cls, value):\n        return stringify_path(value)\n\n    def _resolve_path(self, path: str) -&gt; Path:\n        # Only resolve the base path at runtime, default to the current directory\n        basepath = (\n            Path(self.basepath).expanduser().resolve()\n            if self.basepath\n            else Path(\".\").resolve()\n        )\n\n        # Determine the path to access relative to the base path, ensuring that paths\n        # outside of the base path are off limits\n        if path is None:\n            return basepath\n\n        path: Path = Path(path).expanduser()\n\n        if not path.is_absolute():\n            path = basepath / path\n        else:\n            path = path.resolve()\n            if basepath not in path.parents and (basepath != path):\n                raise ValueError(\n                    f\"Provided path {path} is outside of the base path {basepath}.\"\n                )\n\n        return path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: str = None, local_path: str = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a directory from one place to another on the local filesystem.\n\n        Defaults to copying the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        if not from_path:\n            from_path = Path(self.basepath).expanduser().resolve()\n        else:\n            from_path = self._resolve_path(from_path)\n\n        if not local_path:\n            local_path = Path(\".\").resolve()\n        else:\n            local_path = Path(local_path).resolve()\n\n        if from_path == local_path:\n            # If the paths are the same there is no need to copy\n            # and we avoid shutil.copytree raising an error\n            return\n\n        # .prefectignore exists in the original location, not the current location which\n        # is most likely temporary\n        if (from_path / Path(\".prefectignore\")).exists():\n            ignore_func = await self._get_ignore_func(\n                local_path=from_path, ignore_file=from_path / Path(\".prefectignore\")\n            )\n        else:\n            ignore_func = None\n\n        copytree(from_path, local_path, dirs_exist_ok=True, ignore=ignore_func)\n\n    async def _get_ignore_func(self, local_path: str, ignore_file: str):\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(root=local_path, ignore_patterns=ignore_patterns)\n\n        def ignore_func(directory, files):\n            relative_path = Path(directory).relative_to(local_path)\n\n            files_to_ignore = [\n                f for f in files if str(relative_path / f) not in included_files\n            ]\n            return files_to_ignore\n\n        return ignore_func\n\n    @sync_compatible\n    async def put_directory(\n        self, local_path: str = None, to_path: str = None, ignore_file: str = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a directory from one place to another on the local filesystem.\n\n        Defaults to copying the entire contents of the current working directory to the block's basepath.\n        An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.\n        \"\"\"\n        destination_path = self._resolve_path(to_path)\n\n        if not local_path:\n            local_path = Path(\".\").absolute()\n\n        if ignore_file:\n            ignore_func = await self._get_ignore_func(\n                local_path=local_path, ignore_file=ignore_file\n            )\n        else:\n            ignore_func = None\n\n        if local_path == destination_path:\n            pass\n        else:\n            copytree(\n                src=local_path,\n                dst=destination_path,\n                ignore=ignore_func,\n                dirs_exist_ok=True,\n            )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        path: Path = self._resolve_path(path)\n\n        # Check if the path exists\n        if not path.exists():\n            raise ValueError(f\"Path {path} does not exist.\")\n\n        # Validate that its a file\n        if not path.is_file():\n            raise ValueError(f\"Path {path} is not a file.\")\n\n        async with await anyio.open_file(str(path), mode=\"rb\") as f:\n            content = await f.read()\n\n        return content\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        path: Path = self._resolve_path(path)\n\n        # Construct the path if it does not exist\n        path.parent.mkdir(exist_ok=True, parents=True)\n\n        # Check if the file already exists\n        if path.exists() and not path.is_file():\n            raise ValueError(f\"Path {path} already exists and is not a file.\")\n\n        async with await anyio.open_file(path, mode=\"wb\") as f:\n            await f.write(content)\n        # Leave path stringify to the OS\n        return str(path)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a directory from one place to another on the local filesystem.</p> <p>Defaults to copying the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: str = None, local_path: str = None\n) -&gt; None:\n    \"\"\"\n    Copies a directory from one place to another on the local filesystem.\n\n    Defaults to copying the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    if not from_path:\n        from_path = Path(self.basepath).expanduser().resolve()\n    else:\n        from_path = self._resolve_path(from_path)\n\n    if not local_path:\n        local_path = Path(\".\").resolve()\n    else:\n        local_path = Path(local_path).resolve()\n\n    if from_path == local_path:\n        # If the paths are the same there is no need to copy\n        # and we avoid shutil.copytree raising an error\n        return\n\n    # .prefectignore exists in the original location, not the current location which\n    # is most likely temporary\n    if (from_path / Path(\".prefectignore\")).exists():\n        ignore_func = await self._get_ignore_func(\n            local_path=from_path, ignore_file=from_path / Path(\".prefectignore\")\n        )\n    else:\n        ignore_func = None\n\n    copytree(from_path, local_path, dirs_exist_ok=True, ignore=ignore_func)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Copies a directory from one place to another on the local filesystem.</p> <p>Defaults to copying the entire contents of the current working directory to the block's basepath. An <code>ignore_file</code> path may be provided that can include gitignore style expressions for filepaths to ignore.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self, local_path: str = None, to_path: str = None, ignore_file: str = None\n) -&gt; None:\n    \"\"\"\n    Copies a directory from one place to another on the local filesystem.\n\n    Defaults to copying the entire contents of the current working directory to the block's basepath.\n    An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.\n    \"\"\"\n    destination_path = self._resolve_path(to_path)\n\n    if not local_path:\n        local_path = Path(\".\").absolute()\n\n    if ignore_file:\n        ignore_func = await self._get_ignore_func(\n            local_path=local_path, ignore_file=ignore_file\n        )\n    else:\n        ignore_func = None\n\n    if local_path == destination_path:\n        pass\n    else:\n        copytree(\n            src=local_path,\n            dst=destination_path,\n            ignore=ignore_func,\n            dirs_exist_ok=True,\n        )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem","title":"<code>RemoteFileSystem</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a remote file system.</p> <p>Supports any remote file system supported by <code>fsspec</code>. The file system is specified using a protocol. For example, \"s3://my-bucket/my-folder/\" will use S3.</p> Example <p>Load stored remote file system config: <pre><code>from prefect.filesystems import RemoteFileSystem\n\nremote_file_system_block = RemoteFileSystem.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a remote file system.\n\n    Supports any remote file system supported by `fsspec`. The file system is specified\n    using a protocol. For example, \"s3://my-bucket/my-folder/\" will use S3.\n\n    Example:\n        Load stored remote file system config:\n        ```python\n        from prefect.filesystems import RemoteFileSystem\n\n        remote_file_system_block = RemoteFileSystem.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Remote File System\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/e86b41bc0f9c99ba9489abeee83433b43d5c9365-48x48.png\"\n    _documentation_url = (\n        \"https://docs.prefect.io/concepts/filesystems/#remote-file-system\"\n    )\n\n    basepath: str = Field(\n        default=...,\n        description=\"Default path for this block to write to.\",\n        examples=[\"s3://my-bucket/my-folder/\"],\n    )\n    settings: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional settings to pass through to fsspec.\",\n    )\n\n    # Cache for the configured fsspec file system used for access\n    _filesystem: fsspec.AbstractFileSystem = None\n\n    @validator(\"basepath\")\n    def check_basepath(cls, value):\n        return validate_basepath(value)\n\n    def _resolve_path(self, path: str) -&gt; str:\n        base_scheme, base_netloc, base_urlpath, _, _ = urllib.parse.urlsplit(\n            self.basepath\n        )\n        scheme, netloc, urlpath, _, _ = urllib.parse.urlsplit(path)\n\n        # Confirm that absolute paths are valid\n        if scheme:\n            if scheme != base_scheme:\n                raise ValueError(\n                    f\"Path {path!r} with scheme {scheme!r} must use the same scheme as\"\n                    f\" the base path {base_scheme!r}.\"\n                )\n\n        if netloc:\n            if (netloc != base_netloc) or not urlpath.startswith(base_urlpath):\n                raise ValueError(\n                    f\"Path {path!r} is outside of the base path {self.basepath!r}.\"\n                )\n\n        return f\"{self.basepath.rstrip('/')}/{urlpath.lstrip('/')}\"\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        if from_path is None:\n            from_path = str(self.basepath)\n        else:\n            from_path = self._resolve_path(from_path)\n\n        if local_path is None:\n            local_path = Path(\".\").absolute()\n\n        # validate that from_path has a trailing slash for proper fsspec behavior across versions\n        if not from_path.endswith(\"/\"):\n            from_path += \"/\"\n\n        return self.filesystem.get(from_path, local_path, recursive=True)\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n        overwrite: bool = True,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        if to_path is None:\n            to_path = str(self.basepath)\n        else:\n            to_path = self._resolve_path(to_path)\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(\n                local_path, ignore_patterns, include_dirs=True\n            )\n\n        counter = 0\n        for f in Path(local_path).rglob(\"*\"):\n            relative_path = f.relative_to(local_path)\n            if included_files and str(relative_path) not in included_files:\n                continue\n\n            if to_path.endswith(\"/\"):\n                fpath = to_path + relative_path.as_posix()\n            else:\n                fpath = to_path + \"/\" + relative_path.as_posix()\n\n            if f.is_dir():\n                pass\n            else:\n                f = f.as_posix()\n                if overwrite:\n                    self.filesystem.put_file(f, fpath, overwrite=True)\n                else:\n                    self.filesystem.put_file(f, fpath)\n\n                counter += 1\n\n        return counter\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        path = self._resolve_path(path)\n\n        with self.filesystem.open(path, \"rb\") as file:\n            content = await run_sync_in_worker_thread(file.read)\n\n        return content\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        path = self._resolve_path(path)\n        dirpath = path[: path.rindex(\"/\")]\n\n        self.filesystem.makedirs(dirpath, exist_ok=True)\n\n        with self.filesystem.open(path, \"wb\") as file:\n            await run_sync_in_worker_thread(file.write, content)\n        return path\n\n    @property\n    def filesystem(self) -&gt; fsspec.AbstractFileSystem:\n        if not self._filesystem:\n            scheme, _, _, _, _ = urllib.parse.urlsplit(self.basepath)\n\n            try:\n                self._filesystem = fsspec.filesystem(scheme, **self.settings)\n            except ImportError as exc:\n                # The path is a remote file system that uses a lib that is not installed\n                raise RuntimeError(\n                    f\"File system created with scheme {scheme!r} from base path \"\n                    f\"{self.basepath!r} could not be created. \"\n                    \"You are likely missing a Python module required to use the given \"\n                    \"storage protocol.\"\n                ) from exc\n\n        return self._filesystem\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    if from_path is None:\n        from_path = str(self.basepath)\n    else:\n        from_path = self._resolve_path(from_path)\n\n    if local_path is None:\n        local_path = Path(\".\").absolute()\n\n    # validate that from_path has a trailing slash for proper fsspec behavior across versions\n    if not from_path.endswith(\"/\"):\n        from_path += \"/\"\n\n    return self.filesystem.get(from_path, local_path, recursive=True)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n    overwrite: bool = True,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    if to_path is None:\n        to_path = str(self.basepath)\n    else:\n        to_path = self._resolve_path(to_path)\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(\n            local_path, ignore_patterns, include_dirs=True\n        )\n\n    counter = 0\n    for f in Path(local_path).rglob(\"*\"):\n        relative_path = f.relative_to(local_path)\n        if included_files and str(relative_path) not in included_files:\n            continue\n\n        if to_path.endswith(\"/\"):\n            fpath = to_path + relative_path.as_posix()\n        else:\n            fpath = to_path + \"/\" + relative_path.as_posix()\n\n        if f.is_dir():\n            pass\n        else:\n            f = f.as_posix()\n            if overwrite:\n                self.filesystem.put_file(f, fpath, overwrite=True)\n            else:\n                self.filesystem.put_file(f, fpath)\n\n            counter += 1\n\n    return counter\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3","title":"<code>S3</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>S3Bucket</code> from the <code>prefect-aws</code> package, which offers enhanced functionality and better a better user experience.</p> <p>Store data as a file on AWS S3.</p> Example <p>Load stored S3 config: <pre><code>from prefect.filesystems import S3\n\ns3_block = S3.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\", help=\"Use the `S3Bucket` block from prefect-aws instead.\"\n)\nclass S3(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `S3Bucket` from the `prefect-aws` package, which offers enhanced functionality\n    and better a better user experience.\n\n    Store data as a file on AWS S3.\n\n    Example:\n        Load stored S3 config:\n        ```python\n        from prefect.filesystems import S3\n\n        s3_block = S3.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"S3\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#s3\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"An S3 bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    aws_access_key_id: Optional[SecretStr] = Field(\n        default=None,\n        title=\"AWS Access Key ID\",\n        description=\"Equivalent to the AWS_ACCESS_KEY_ID environment variable.\",\n        examples=[\"AKIAIOSFODNN7EXAMPLE\"],\n    )\n    aws_secret_access_key: Optional[SecretStr] = Field(\n        default=None,\n        title=\"AWS Secret Access Key\",\n        description=\"Equivalent to the AWS_SECRET_ACCESS_KEY environment variable.\",\n        examples=[\"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\"],\n    )\n\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"s3://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.aws_access_key_id:\n            settings[\"key\"] = self.aws_access_key_id.get_secret_value()\n        if self.aws_secret_access_key:\n            settings[\"secret\"] = self.aws_secret_access_key.get_secret_value()\n        self._remote_file_system = RemoteFileSystem(\n            basepath=f\"s3://{self.bucket_path}\", settings=settings\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB","title":"<code>SMB</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a SMB share.</p> Example <p>Load stored SMB config:</p> <pre><code>from prefect.filesystems import SMB\nsmb_block = SMB.load(\"BLOCK_NAME\")\n</code></pre> Source code in <code>prefect/filesystems.py</code> <pre><code>class SMB(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a SMB share.\n\n    Example:\n        Load stored SMB config:\n\n        ```python\n        from prefect.filesystems import SMB\n        smb_block = SMB.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"SMB\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/3f624663f7beb97d011d011bffd51ecf6c499efc-195x195.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#smb\"\n\n    share_path: str = Field(\n        default=...,\n        description=\"SMB target (requires &lt;SHARE&gt;, followed by &lt;PATH&gt;).\",\n        examples=[\"/SHARE/dir/subdir\"],\n    )\n    smb_username: Optional[SecretStr] = Field(\n        default=None,\n        title=\"SMB Username\",\n        description=\"Username with access to the target SMB SHARE.\",\n    )\n    smb_password: Optional[SecretStr] = Field(\n        default=None, title=\"SMB Password\", description=\"Password for SMB access.\"\n    )\n    smb_host: str = Field(\n        default=..., tile=\"SMB server/hostname\", description=\"SMB server/hostname.\"\n    )\n    smb_port: Optional[int] = Field(\n        default=None, title=\"SMB port\", description=\"SMB port (default: 445).\"\n    )\n\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"smb://{self.smb_host.rstrip('/')}/{self.share_path.lstrip('/')}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.smb_username:\n            settings[\"username\"] = self.smb_username.get_secret_value()\n        if self.smb_password:\n            settings[\"password\"] = self.smb_password.get_secret_value()\n        if self.smb_host:\n            settings[\"host\"] = self.smb_host\n        if self.smb_port:\n            settings[\"port\"] = self.smb_port\n        self._remote_file_system = RemoteFileSystem(\n            basepath=f\"smb://{self.smb_host.rstrip('/')}/{self.share_path.lstrip('/')}\",\n            settings=settings,\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path,\n            to_path=to_path,\n            ignore_file=ignore_file,\n            overwrite=False,\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory. Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory. Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path,\n        to_path=to_path,\n        ignore_file=ignore_file,\n        overwrite=False,\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/flow_runs/","title":"prefect.flow_runs","text":"","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flow_runs/#prefect.flow_runs","title":"<code>prefect.flow_runs</code>","text":"","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flow_runs/#prefect.flow_runs.wait_for_flow_run","title":"<code>wait_for_flow_run</code>  <code>async</code>","text":"<p>Waits for the prefect flow run to finish and returns the FlowRun</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run ID for the flow run to wait for.</p> required <code>timeout</code> <code>Optional[int]</code> <p>The wait timeout in seconds. Defaults to 10800 (3 hours).</p> <code>10800</code> <code>poll_interval</code> <code>int</code> <p>The poll interval in seconds. Defaults to 5.</p> <code>5</code> <p>Returns:</p> Name Type Description <code>FlowRun</code> <code>FlowRun</code> <p>The finished flow run.</p> <p>Raises:</p> Type Description <code>FlowWaitTimeout</code> <p>If flow run goes over the timeout.</p> <p>Examples:</p> <p>Create a flow run for a deployment and wait for it to finish:     <pre><code>import asyncio\n\nfrom prefect import get_client\nfrom prefect.flow_runs import wait_for_flow_run\n\nasync def main():\n    async with get_client() as client:\n        flow_run = await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n        flow_run = await wait_for_flow_run(flow_run_id=flow_run.id)\n        print(flow_run.state)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre></p> <p>Trigger multiple flow runs and wait for them to finish:     <pre><code>import asyncio\n\nfrom prefect import get_client\nfrom prefect.flow_runs import wait_for_flow_run\n\nasync def main(num_runs: int):\n    async with get_client() as client:\n        flow_runs = [\n            await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n            for _\n            in range(num_runs)\n        ]\n        coros = [wait_for_flow_run(flow_run_id=flow_run.id) for flow_run in flow_runs]\n        finished_flow_runs = await asyncio.gather(*coros)\n        print([flow_run.state for flow_run in finished_flow_runs])\n\nif __name__ == \"__main__\":\n    asyncio.run(main(num_runs=10))\n</code></pre></p> Source code in <code>prefect/flow_runs.py</code> <pre><code>@inject_client\nasync def wait_for_flow_run(\n    flow_run_id: UUID,\n    timeout: Optional[int] = 10800,\n    poll_interval: int = 5,\n    client: Optional[PrefectClient] = None,\n    log_states: bool = False,\n) -&gt; FlowRun:\n    \"\"\"\n    Waits for the prefect flow run to finish and returns the FlowRun\n\n    Args:\n        flow_run_id: The flow run ID for the flow run to wait for.\n        timeout: The wait timeout in seconds. Defaults to 10800 (3 hours).\n        poll_interval: The poll interval in seconds. Defaults to 5.\n\n    Returns:\n        FlowRun: The finished flow run.\n\n    Raises:\n        prefect.exceptions.FlowWaitTimeout: If flow run goes over the timeout.\n\n    Examples:\n        Create a flow run for a deployment and wait for it to finish:\n            ```python\n            import asyncio\n\n            from prefect import get_client\n            from prefect.flow_runs import wait_for_flow_run\n\n            async def main():\n                async with get_client() as client:\n                    flow_run = await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n                    flow_run = await wait_for_flow_run(flow_run_id=flow_run.id)\n                    print(flow_run.state)\n\n            if __name__ == \"__main__\":\n                asyncio.run(main())\n\n            ```\n\n        Trigger multiple flow runs and wait for them to finish:\n            ```python\n            import asyncio\n\n            from prefect import get_client\n            from prefect.flow_runs import wait_for_flow_run\n\n            async def main(num_runs: int):\n                async with get_client() as client:\n                    flow_runs = [\n                        await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n                        for _\n                        in range(num_runs)\n                    ]\n                    coros = [wait_for_flow_run(flow_run_id=flow_run.id) for flow_run in flow_runs]\n                    finished_flow_runs = await asyncio.gather(*coros)\n                    print([flow_run.state for flow_run in finished_flow_runs])\n\n            if __name__ == \"__main__\":\n                asyncio.run(main(num_runs=10))\n\n            ```\n    \"\"\"\n    assert client is not None, \"Client injection failed\"\n    logger = get_logger()\n    with anyio.move_on_after(timeout):\n        while True:\n            flow_run = await client.read_flow_run(flow_run_id)\n            flow_state = flow_run.state\n            if log_states:\n                logger.info(f\"Flow run is in state {flow_run.state.name!r}\")\n            if flow_state and flow_state.is_final():\n                return flow_run\n            await anyio.sleep(poll_interval)\n    raise FlowRunWaitTimeout(\n        f\"Flow run with ID {flow_run_id} exceeded watch timeout of {timeout} seconds\"\n    )\n</code></pre>","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flows/","title":"prefect.flows","text":"","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows","title":"<code>prefect.flows</code>","text":"<p>Module containing the base workflow class and decorator - for most use cases, using the <code>@flow</code> decorator is preferred.</p>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>Generic[P, R]</code></p> <p>A Prefect workflow definition.</p> <p>Note</p> <p>We recommend using the <code>@flow</code> decorator for most use-cases.</p> <p>Wraps a function with an entrypoint to the Prefect engine. To preserve the input and output types, we use the generic type variables <code>P</code> and <code>R</code> for \"Parameters\" and \"Returns\" respectively.</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable[P, R]</code> <p>The function defining the workflow.</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional version string for the flow; if not provided, we will attempt to create a version string as a hash of the file containing the wrapped function; if the file cannot be located, the version will be null.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>task_runner</code> <code>Union[Type[BaseTaskRunner], BaseTaskRunner]</code> <p>An optional task runner to use for task execution within the flow; if not provided, a <code>ConcurrentTaskRunner</code> will be used.</p> <code>ConcurrentTaskRunner</code> <code>description</code> <code>str</code> <p>An optional string description for the flow; if not provided, the description will be pulled from the docstring for the decorated function.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>By default, parameters passed to flows are validated by Pydantic. This will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type; for example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p> <code>True</code> <code>retries</code> <code>Optional[int]</code> <p>An optional number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[int, float]]</code> <p>An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this flow should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this flow. This value will be used as the default for any tasks in this flow. If not provided, the local file system will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this flow for persistence. This value will be used as the default for any tasks in this flow. If not provided, the value of <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a completed state.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a cancelling state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a crashed state.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a running state.</p> <code>None</code> Source code in <code>prefect/flows.py</code> <pre><code>@PrefectObjectRegistry.register_instances\nclass Flow(Generic[P, R]):\n    \"\"\"\n    A Prefect workflow definition.\n\n    !!! note\n        We recommend using the [`@flow` decorator][prefect.flows.flow] for most use-cases.\n\n    Wraps a function with an entrypoint to the Prefect engine. To preserve the input\n    and output types, we use the generic type variables `P` and `R` for \"Parameters\" and\n    \"Returns\" respectively.\n\n    Args:\n        fn: The function defining the workflow.\n        name: An optional name for the flow; if not provided, the name will be inferred\n            from the given function.\n        version: An optional version string for the flow; if not provided, we will\n            attempt to create a version string as a hash of the file containing the\n            wrapped function; if the file cannot be located, the version will be null.\n        flow_run_name: An optional name to distinguish runs of this flow; this name can\n            be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        task_runner: An optional task runner to use for task execution within the flow;\n            if not provided, a `ConcurrentTaskRunner` will be used.\n        description: An optional string description for the flow; if not provided, the\n            description will be pulled from the docstring for the decorated function.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the flow. If the flow exceeds this runtime, it will be marked as failed.\n            Flow execution may continue until the next task is called.\n        validate_parameters: By default, parameters passed to flows are validated by\n            Pydantic. This will check that input values conform to the annotated types\n            on the function. Where possible, values will be coerced into the correct\n            type; for example, if a parameter is defined as `x: int` and \"5\" is passed,\n            it will be resolved to `5`. If set to `False`, no validation will be\n            performed on flow parameters.\n        retries: An optional number of times to retry on flow run failure.\n        retry_delay_seconds: An optional number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        persist_result: An optional toggle indicating whether the result of this flow\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this flow.\n            This value will be used as the default for any tasks in this flow.\n            If not provided, the local file system will be used unless called as\n            a subflow, at which point the default will be loaded from the parent flow.\n        result_serializer: An optional serializer to use to serialize the result of this\n            flow for persistence. This value will be used as the default for any tasks\n            in this flow. If not provided, the value of `PREFECT_RESULTS_DEFAULT_SERIALIZER`\n            will be used unless called as a subflow, at which point the default will be\n            loaded from the parent flow.\n        on_failure: An optional list of callables to run when the flow enters a failed state.\n        on_completion: An optional list of callables to run when the flow enters a completed state.\n        on_cancellation: An optional list of callables to run when the flow enters a cancelling state.\n        on_crashed: An optional list of callables to run when the flow enters a crashed state.\n        on_running: An optional list of callables to run when the flow enters a running state.\n    \"\"\"\n\n    # NOTE: These parameters (types, defaults, and docstrings) should be duplicated\n    #       exactly in the @flow decorator\n    def __init__(\n        self,\n        fn: Callable[P, R],\n        name: Optional[str] = None,\n        version: Optional[str] = None,\n        flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[Union[int, float]] = None,\n        task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = ConcurrentTaskRunner,\n        description: str = None,\n        timeout_seconds: Union[int, float] = None,\n        validate_parameters: bool = True,\n        persist_result: Optional[bool] = None,\n        result_storage: Optional[ResultStorage] = None,\n        result_serializer: Optional[ResultSerializer] = None,\n        cache_result_in_memory: bool = True,\n        log_prints: Optional[bool] = None,\n        on_completion: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_cancellation: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    ):\n        if name is not None and not isinstance(name, str):\n            raise TypeError(\n                \"Expected string for flow parameter 'name'; got {} instead. {}\".format(\n                    type(name).__name__,\n                    (\n                        \"Perhaps you meant to call it? e.g.\"\n                        \" '@flow(name=get_flow_run_name())'\"\n                        if callable(name)\n                        else \"\"\n                    ),\n                )\n            )\n\n        # Validate if hook passed is list and contains callables\n        hook_categories = [\n            on_completion,\n            on_failure,\n            on_cancellation,\n            on_crashed,\n            on_running,\n        ]\n        hook_names = [\n            \"on_completion\",\n            \"on_failure\",\n            \"on_cancellation\",\n            \"on_crashed\",\n            \"on_running\",\n        ]\n        for hooks, hook_name in zip(hook_categories, hook_names):\n            if hooks is not None:\n                if not hooks:\n                    raise ValueError(f\"Empty list passed for '{hook_name}'\")\n                try:\n                    hooks = list(hooks)\n                except TypeError:\n                    raise TypeError(\n                        f\"Expected iterable for '{hook_name}'; got\"\n                        f\" {type(hooks).__name__} instead. Please provide a list of\"\n                        f\" hooks to '{hook_name}':\\n\\n\"\n                        f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                        \" my_flow():\\n\\tpass\"\n                    )\n\n                for hook in hooks:\n                    if not callable(hook):\n                        raise TypeError(\n                            f\"Expected callables in '{hook_name}'; got\"\n                            f\" {type(hook).__name__} instead. Please provide a list of\"\n                            f\" hooks to '{hook_name}':\\n\\n\"\n                            f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                            \" my_flow():\\n\\tpass\"\n                        )\n\n        if not callable(fn):\n            raise TypeError(\"'fn' must be callable\")\n\n        # Validate name if given\n        if name:\n            raise_on_name_with_banned_characters(name)\n\n        self.name = name or fn.__name__.replace(\"_\", \"-\")\n\n        if flow_run_name is not None:\n            if not isinstance(flow_run_name, str) and not callable(flow_run_name):\n                raise TypeError(\n                    \"Expected string or callable for 'flow_run_name'; got\"\n                    f\" {type(flow_run_name).__name__} instead.\"\n                )\n        self.flow_run_name = flow_run_name\n\n        task_runner = task_runner or ConcurrentTaskRunner()\n        self.task_runner = (\n            task_runner() if isinstance(task_runner, type) else task_runner\n        )\n\n        self.log_prints = log_prints\n\n        self.description = description or inspect.getdoc(fn)\n        update_wrapper(self, fn)\n        self.fn = fn\n        self.isasync = is_async_fn(self.fn)\n\n        raise_for_reserved_arguments(self.fn, [\"return_state\", \"wait_for\"])\n\n        # Version defaults to a hash of the function's file\n        flow_file = inspect.getsourcefile(self.fn)\n        if not version:\n            try:\n                version = file_hash(flow_file)\n            except (FileNotFoundError, TypeError, OSError):\n                pass  # `getsourcefile` can return null values and \"&lt;stdin&gt;\" for objects in repls\n        self.version = version\n\n        self.timeout_seconds = float(timeout_seconds) if timeout_seconds else None\n\n        # FlowRunPolicy settings\n        # TODO: We can instantiate a `FlowRunPolicy` and add Pydantic bound checks to\n        #       validate that the user passes positive numbers here\n        self.retries = (\n            retries if retries is not None else PREFECT_FLOW_DEFAULT_RETRIES.value()\n        )\n\n        self.retry_delay_seconds = (\n            retry_delay_seconds\n            if retry_delay_seconds is not None\n            else PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS.value()\n        )\n\n        self.parameters = parameter_schema(self.fn)\n        self.should_validate_parameters = validate_parameters\n\n        if self.should_validate_parameters:\n            # Try to create the validated function now so that incompatibility can be\n            # raised at declaration time rather than at runtime\n            # We cannot, however, store the validated function on the flow because it\n            # is not picklable in some environments\n            try:\n                ValidatedFunction(self.fn, config={\"arbitrary_types_allowed\": True})\n            except pydantic.ConfigError as exc:\n                raise ValueError(\n                    \"Flow function is not compatible with `validate_parameters`. \"\n                    \"Disable validation or change the argument names.\"\n                ) from exc\n\n        self.persist_result = persist_result\n        self.result_storage = result_storage\n        self.result_serializer = result_serializer\n        self.cache_result_in_memory = cache_result_in_memory\n        self.on_completion = on_completion\n        self.on_failure = on_failure\n        self.on_cancellation = on_cancellation\n        self.on_crashed = on_crashed\n        self.on_running = on_running\n\n        # Used for flows loaded from remote storage\n        self._storage: Optional[RunnerStorage] = None\n        self._entrypoint: Optional[str] = None\n\n        module = fn.__module__\n        if module in (\"__main__\", \"__prefect_loader__\"):\n            module_name = inspect.getfile(fn)\n            module = module_name if module_name != \"__main__\" else module\n\n        self._entrypoint = f\"{module}:{fn.__name__}\"\n\n    def with_options(\n        self,\n        *,\n        name: str = None,\n        version: str = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[Union[int, float]] = None,\n        description: str = None,\n        flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n        task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = None,\n        timeout_seconds: Union[int, float] = None,\n        validate_parameters: bool = None,\n        persist_result: Optional[bool] = NotSet,\n        result_storage: Optional[ResultStorage] = NotSet,\n        result_serializer: Optional[ResultSerializer] = NotSet,\n        cache_result_in_memory: bool = None,\n        log_prints: Optional[bool] = NotSet,\n        on_completion: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_cancellation: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Create a new flow from the current object, updating provided options.\n\n        Args:\n            name: A new name for the flow.\n            version: A new version for the flow.\n            description: A new description for the flow.\n            flow_run_name: An optional name to distinguish runs of this flow; this name\n                can be provided as a string template with the flow's parameters as variables,\n                or a function that returns a string.\n            task_runner: A new task runner for the flow.\n            timeout_seconds: A new number of seconds to fail the flow after if still\n                running.\n            validate_parameters: A new value indicating if flow calls should validate\n                given parameters.\n            retries: A new number of times to retry on flow run failure.\n            retry_delay_seconds: A new number of seconds to wait before retrying the\n                flow after failure. This is only applicable if `retries` is nonzero.\n            persist_result: A new option for enabling or disabling result persistence.\n            result_storage: A new storage type to use for results.\n            result_serializer: A new serializer to use for results.\n            cache_result_in_memory: A new value indicating if the flow's result should\n                be cached in memory.\n            on_failure: A new list of callables to run when the flow enters a failed state.\n            on_completion: A new list of callables to run when the flow enters a completed state.\n            on_cancellation: A new list of callables to run when the flow enters a cancelling state.\n            on_crashed: A new list of callables to run when the flow enters a crashed state.\n            on_running: A new list of callables to run when the flow enters a running state.\n\n        Returns:\n            A new `Flow` instance.\n\n        Examples:\n\n            Create a new flow from an existing flow and update the name:\n\n            &gt;&gt;&gt; @flow(name=\"My flow\")\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\n            Create a new flow from an existing flow, update the task runner, and call\n            it without an intermediate variable:\n\n            &gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow(x, y):\n            &gt;&gt;&gt;     return x + y\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n            &gt;&gt;&gt; assert state.result() == 4\n\n        \"\"\"\n        new_flow = Flow(\n            fn=self.fn,\n            name=name or self.name,\n            description=description or self.description,\n            flow_run_name=flow_run_name or self.flow_run_name,\n            version=version or self.version,\n            task_runner=task_runner or self.task_runner,\n            retries=retries if retries is not None else self.retries,\n            retry_delay_seconds=(\n                retry_delay_seconds\n                if retry_delay_seconds is not None\n                else self.retry_delay_seconds\n            ),\n            timeout_seconds=(\n                timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n            ),\n            validate_parameters=(\n                validate_parameters\n                if validate_parameters is not None\n                else self.should_validate_parameters\n            ),\n            persist_result=(\n                persist_result if persist_result is not NotSet else self.persist_result\n            ),\n            result_storage=(\n                result_storage if result_storage is not NotSet else self.result_storage\n            ),\n            result_serializer=(\n                result_serializer\n                if result_serializer is not NotSet\n                else self.result_serializer\n            ),\n            cache_result_in_memory=(\n                cache_result_in_memory\n                if cache_result_in_memory is not None\n                else self.cache_result_in_memory\n            ),\n            log_prints=log_prints if log_prints is not NotSet else self.log_prints,\n            on_completion=on_completion or self.on_completion,\n            on_failure=on_failure or self.on_failure,\n            on_cancellation=on_cancellation or self.on_cancellation,\n            on_crashed=on_crashed or self.on_crashed,\n            on_running=on_running or self.on_running,\n        )\n        new_flow._storage = self._storage\n        new_flow._entrypoint = self._entrypoint\n        return new_flow\n\n    def validate_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Validate parameters for compatibility with the flow by attempting to cast the inputs to the\n        associated types specified by the function's type annotations.\n\n        Returns:\n            A new dict of parameters that have been cast to the appropriate types\n\n        Raises:\n            ParameterTypeError: if the provided parameters are not valid\n        \"\"\"\n        args, kwargs = parameters_to_args_kwargs(self.fn, parameters)\n\n        if HAS_PYDANTIC_V2:\n            has_v1_models = any(isinstance(o, V1BaseModel) for o in args) or any(\n                isinstance(o, V1BaseModel) for o in kwargs.values()\n            )\n            has_v2_types = any(is_v2_type(o) for o in args) or any(\n                is_v2_type(o) for o in kwargs.values()\n            )\n\n            if has_v1_models and has_v2_types:\n                raise ParameterTypeError(\n                    \"Cannot mix Pydantic v1 and v2 types as arguments to a flow.\"\n                )\n\n            if has_v1_models:\n                validated_fn = V1ValidatedFunction(\n                    self.fn, config={\"arbitrary_types_allowed\": True}\n                )\n            else:\n                validated_fn = V2ValidatedFunction(\n                    self.fn, config={\"arbitrary_types_allowed\": True}\n                )\n\n        else:\n            validated_fn = ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n\n        try:\n            model = validated_fn.init_model_instance(*args, **kwargs)\n        except pydantic.ValidationError as exc:\n            # We capture the pydantic exception and raise our own because the pydantic\n            # exception is not picklable when using a cythonized pydantic installation\n            raise ParameterTypeError.from_validation_error(exc) from None\n        except V2ValidationError as exc:\n            # We capture the pydantic exception and raise our own because the pydantic\n            # exception is not picklable when using a cythonized pydantic installation\n            raise ParameterTypeError.from_validation_error(exc) from None\n\n        # Get the updated parameter dict with cast values from the model\n        cast_parameters = {\n            k: v\n            for k, v in model._iter()\n            if k in model.__fields_set__ or model.__fields__[k].default_factory\n        }\n        return cast_parameters\n\n    def serialize_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Convert parameters to a serializable form.\n\n        Uses FastAPI's `jsonable_encoder` to convert to JSON compatible objects without\n        converting everything directly to a string. This maintains basic types like\n        integers during API roundtrips.\n        \"\"\"\n        serialized_parameters = {}\n        for key, value in parameters.items():\n            try:\n                serialized_parameters[key] = jsonable_encoder(value)\n            except (TypeError, ValueError):\n                logger.debug(\n                    f\"Parameter {key!r} for flow {self.name!r} is of unserializable \"\n                    f\"type {type(value).__name__!r} and will not be stored \"\n                    \"in the backend.\"\n                )\n                serialized_parameters[key] = f\"&lt;{type(value).__name__}&gt;\"\n        return serialized_parameters\n\n    @sync_compatible\n    @deprecated_parameter(\n        \"schedule\",\n        start_date=\"Mar 2024\",\n        when=lambda p: p is not None,\n        help=\"Use `schedules` instead.\",\n    )\n    @deprecated_parameter(\n        \"is_schedule_active\",\n        start_date=\"Mar 2024\",\n        when=lambda p: p is not None,\n        help=\"Use `paused` instead.\",\n    )\n    async def to_deployment(\n        self,\n        name: str,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Creates a runner deployment object for this flow.\n\n        Args:\n            name: The name to give the created deployment.\n            interval: An interval on which to execute the new deployment. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this deployment.\n            rrule: An rrule schedule of when to execute runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options such as `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n\n        Examples:\n            Prepare two deployments and serve them:\n\n            ```python\n            from prefect import flow, serve\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            @flow\n            def my_other_flow(name):\n                print(f\"goodbye {name}\")\n\n            if __name__ == \"__main__\":\n                hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n                bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n                serve(hello_deploy, bye_deploy)\n            ```\n        \"\"\"\n        from prefect.deployments.runner import RunnerDeployment\n\n        if not name.endswith(\".py\"):\n            raise_on_name_with_banned_characters(name)\n        if self._storage and self._entrypoint:\n            return await RunnerDeployment.from_storage(\n                storage=self._storage,\n                entrypoint=self._entrypoint,\n                name=name,\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                paused=paused,\n                schedules=schedules,\n                schedule=schedule,\n                is_schedule_active=is_schedule_active,\n                tags=tags,\n                triggers=triggers,\n                parameters=parameters or {},\n                description=description,\n                version=version,\n                enforce_parameter_schema=enforce_parameter_schema,\n                work_pool_name=work_pool_name,\n                work_queue_name=work_queue_name,\n                job_variables=job_variables,\n            )\n        else:\n            return RunnerDeployment.from_flow(\n                self,\n                name=name,\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                paused=paused,\n                schedules=schedules,\n                schedule=schedule,\n                is_schedule_active=is_schedule_active,\n                tags=tags,\n                triggers=triggers,\n                parameters=parameters or {},\n                description=description,\n                version=version,\n                enforce_parameter_schema=enforce_parameter_schema,\n                work_pool_name=work_pool_name,\n                work_queue_name=work_queue_name,\n                job_variables=job_variables,\n                entrypoint_type=entrypoint_type,\n            )\n\n    @sync_compatible\n    async def serve(\n        self,\n        name: Optional[str] = None,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        parameters: Optional[dict] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        pause_on_shutdown: bool = True,\n        print_starting_message: bool = True,\n        limit: Optional[int] = None,\n        webserver: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ):\n        \"\"\"\n        Creates a deployment for this flow and starts a runner to monitor for scheduled work.\n\n        Args:\n            name: The name to give the created deployment. Defaults to the name of the flow.\n            interval: An interval on which to execute the deployment. Accepts a number or a\n                timedelta object to create a single schedule. If a number is given, it will be\n                interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n                multiple schedules.\n            cron: A cron schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of cron schedule strings to create multiple schedules.\n            rrule: An rrule schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of rrule schedule strings to create multiple schedules.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment. Used to\n                define additional scheduling options such as `timezone`.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            pause_on_shutdown: If True, provided schedule will be paused when the serve function is stopped.\n                If False, the schedules will continue running.\n            print_starting_message: Whether or not to print the starting message when flow is served.\n            limit: The maximum number of runs that can be executed concurrently.\n            webserver: Whether or not to start a monitoring webserver for this flow.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n\n        Examples:\n            Serve a flow:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.serve(\"example-deployment\")\n            ```\n\n            Serve a flow and run it every hour:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.serve(\"example-deployment\", interval=3600)\n            ```\n        \"\"\"\n        from prefect.runner import Runner\n\n        if not name:\n            name = self.name\n        else:\n            # Handling for my_flow.serve(__file__)\n            # Will set name to name of file where my_flow.serve() without the extension\n            # Non filepath strings will pass through unchanged\n            name = Path(name).stem\n\n        runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown, limit=limit)\n        deployment_id = await runner.add_flow(\n            self,\n            name=name,\n            triggers=triggers,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            entrypoint_type=entrypoint_type,\n        )\n        if print_starting_message:\n            help_message = (\n                f\"[green]Your flow {self.name!r} is being served and polling for\"\n                \" scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the\"\n                \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n                f\" '{self.name}/{name}'\\n[/]\"\n            )\n            if PREFECT_UI_URL:\n                help_message += (\n                    \"\\nYou can also run your flow via the Prefect UI:\"\n                    f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n                )\n\n            console = Console()\n            console.print(help_message, soft_wrap=True)\n        await runner.start(webserver=webserver)\n\n    @classmethod\n    @sync_compatible\n    async def from_source(\n        cls: Type[F],\n        source: Union[str, RunnerStorage, ReadableDeploymentStorage],\n        entrypoint: str,\n    ) -&gt; F:\n        \"\"\"\n        Loads a flow from a remote source.\n\n        Args:\n            source: Either a URL to a git repository or a storage object.\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n\n        Returns:\n            A new `Flow` instance.\n\n        Examples:\n            Load a flow from a public git repository:\n\n\n            ```python\n            from prefect import flow\n            from prefect.runner.storage import GitRepository\n            from prefect.blocks.system import Secret\n\n            my_flow = flow.from_source(\n                source=\"https://github.com/org/repo.git\",\n                entrypoint=\"flows.py:my_flow\",\n            )\n\n            my_flow()\n            ```\n\n            Load a flow from a private git repository using an access token stored in a `Secret` block:\n\n            ```python\n            from prefect import flow\n            from prefect.runner.storage import GitRepository\n            from prefect.blocks.system import Secret\n\n            my_flow = flow.from_source(\n                source=GitRepository(\n                    url=\"https://github.com/org/repo.git\",\n                    credentials={\"access_token\": Secret.load(\"github-access-token\")}\n                ),\n                entrypoint=\"flows.py:my_flow\",\n            )\n\n            my_flow()\n            ```\n        \"\"\"\n        if isinstance(source, str):\n            storage = create_storage_from_source(source)\n        elif isinstance(source, RunnerStorage):\n            storage = source\n        elif hasattr(source, \"get_directory\"):\n            storage = BlockStorageAdapter(source)\n        else:\n            raise TypeError(\n                f\"Unsupported source type {type(source).__name__!r}. Please provide a\"\n                \" URL to remote storage or a storage object.\"\n            )\n\n        with tempfile.TemporaryDirectory() as tmpdir:\n            if not isinstance(storage, LocalStorage):\n                storage.set_base_path(Path(tmpdir))\n                await storage.pull_code()\n\n            full_entrypoint = str(storage.destination / entrypoint)\n            flow: \"Flow\" = await from_async.wait_for_call_in_new_thread(\n                create_call(load_flow_from_entrypoint, full_entrypoint)\n            )\n            flow._storage = storage\n            flow._entrypoint = entrypoint\n\n        return flow\n\n    @sync_compatible\n    async def deploy(\n        self,\n        name: str,\n        work_pool_name: Optional[str] = None,\n        image: Optional[Union[str, DeploymentImage]] = None,\n        build: bool = True,\n        push: bool = True,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[dict] = None,\n        interval: Optional[Union[int, float, datetime.timedelta]] = None,\n        cron: Optional[str] = None,\n        rrule: Optional[str] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[MinimalDeploymentSchedule]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        parameters: Optional[dict] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n        print_next_steps: bool = True,\n        ignore_warnings: bool = False,\n    ) -&gt; UUID:\n        \"\"\"\n        Deploys a flow to run on dynamic infrastructure via a work pool.\n\n        By default, calling this method will build a Docker image for the flow, push it to a registry,\n        and create a deployment via the Prefect API that will run the flow on the given schedule.\n\n        If you want to use an existing image, you can pass `build=False` to skip building and pushing\n        an image.\n\n        Args:\n            name: The name to give the created deployment.\n            work_pool_name: The name of the work pool to use for this deployment. Defaults to\n                the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n            image: The name of the Docker image to build, including the registry and\n                repository. Pass a DeploymentImage instance to customize the Dockerfile used\n                and build arguments.\n            build: Whether or not to build a new image for the flow. If False, the provided\n                image will be used as-is and pulled at runtime.\n            push: Whether or not to skip pushing the built image to a registry.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n            interval: An interval on which to execute the deployment. Accepts a number or a\n                timedelta object to create a single schedule. If a number is given, it will be\n                interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n                multiple schedules.\n            cron: A cron schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of cron schedule strings to create multiple schedules.\n            rrule: An rrule schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of rrule schedule strings to create multiple schedules.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment. Used to\n                define additional scheduling options like `timezone`.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n            print_next_steps_message: Whether or not to print a message with next steps\n                after deploying the deployments.\n            ignore_warnings: Whether or not to ignore warnings about the work pool type.\n\n        Returns:\n            The ID of the created/updated deployment.\n\n        Examples:\n            Deploy a local flow to a work pool:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.deploy(\n                    \"example-deployment\",\n                    work_pool_name=\"my-work-pool\",\n                    image=\"my-repository/my-image:dev\",\n                )\n            ```\n\n            Deploy a remotely stored flow to a work pool:\n\n            ```python\n            from prefect import flow\n\n            if __name__ == \"__main__\":\n                flow.from_source(\n                    source=\"https://github.com/org/repo.git\",\n                    entrypoint=\"flows.py:my_flow\",\n                ).deploy(\n                    \"example-deployment\",\n                    work_pool_name=\"my-work-pool\",\n                    image=\"my-repository/my-image:dev\",\n                )\n            ```\n        \"\"\"\n        work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n        try:\n            async with get_client() as client:\n                work_pool = await client.read_work_pool(work_pool_name)\n        except ObjectNotFound as exc:\n            raise ValueError(\n                f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n                \" deploying this flow.\"\n            ) from exc\n\n        deployment = await self.to_deployment(\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedules=schedules,\n            paused=paused,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            triggers=triggers,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n            entrypoint_type=entrypoint_type,\n        )\n\n        deployment_ids = await deploy(\n            deployment,\n            work_pool_name=work_pool_name,\n            image=image,\n            build=build,\n            push=push,\n            print_next_steps_message=False,\n            ignore_warnings=ignore_warnings,\n        )\n\n        if print_next_steps:\n            console = Console()\n            if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n                console.print(\n                    \"\\nTo execute flow runs from this deployment, start a worker in a\"\n                    \" separate terminal that pulls work from the\"\n                    f\" {work_pool_name!r} work pool:\"\n                )\n                console.print(\n                    f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                    style=\"blue\",\n                )\n            console.print(\n                \"\\nTo schedule a run for this deployment, use the following command:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect deployment run '{self.name}/{name}'\\n\",\n                style=\"blue\",\n            )\n            if PREFECT_UI_URL:\n                message = (\n                    \"\\nYou can also run your flow via the Prefect UI:\"\n                    f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\\n\"\n                )\n                console.print(message, soft_wrap=True)\n\n        return deployment_ids[0]\n\n    @overload\n    def __call__(self: \"Flow[P, NoReturn]\", *args: P.args, **kwargs: P.kwargs) -&gt; None:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, Coroutine[Any, Any, T]]\", *args: P.args, **kwargs: P.kwargs\n    ) -&gt; Awaitable[T]:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; T:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def __call__(\n        self,\n        *args: \"P.args\",\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: \"P.kwargs\",\n    ):\n        \"\"\"\n        Run the flow and return its result.\n\n\n        Flow parameter values must be serializable by Pydantic.\n\n        If writing an async flow, this call must be awaited.\n\n        This will create a new flow run in the API.\n\n        Args:\n            *args: Arguments to run the flow with.\n            return_state: Return a Prefect State containing the result of the\n                flow run.\n            wait_for: Upstream task futures to wait for before starting the flow if called as a subflow\n            **kwargs: Keyword arguments to run the flow with.\n\n        Returns:\n            If `return_state` is False, returns the result of the flow run.\n            If `return_state` is True, returns the result of the flow run\n                wrapped in a Prefect State which provides error handling.\n\n        Examples:\n\n            Define a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow(name):\n            &gt;&gt;&gt;     print(f\"hello {name}\")\n            &gt;&gt;&gt;     return f\"goodbye {name}\"\n\n            Run a flow\n\n            &gt;&gt;&gt; my_flow(\"marvin\")\n            hello marvin\n            \"goodbye marvin\"\n\n            Run a flow with additional tags\n\n            &gt;&gt;&gt; from prefect import tags\n            &gt;&gt;&gt; with tags(\"db\", \"blue\"):\n            &gt;&gt;&gt;     my_flow(\"foo\")\n        \"\"\"\n        from prefect.engine import enter_flow_run_engine_from_flow_call\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return_type = \"state\" if return_state else \"result\"\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            # this is a subflow, for now return a single task and do not go further\n            # we can add support for exploring subflows for tasks in the future.\n            return track_viz_task(self.isasync, self.name, parameters)\n\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE.value():\n            from prefect.new_flow_engine import run_flow, run_flow_sync\n\n            run_kwargs = dict(\n                flow=self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n            )\n            if self.isasync:\n                # this returns an awaitable coroutine\n                return run_flow(**run_kwargs)\n            else:\n                return run_flow_sync(**run_kwargs)\n\n        return enter_flow_run_engine_from_flow_call(\n            self,\n            parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n        )\n\n    @overload\n    def _run(self: \"Flow[P, NoReturn]\", *args: P.args, **kwargs: P.kwargs) -&gt; State[T]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def _run(\n        self: \"Flow[P, Coroutine[Any, Any, T]]\", *args: P.args, **kwargs: P.kwargs\n    ) -&gt; Awaitable[T]:\n        ...\n\n    @overload\n    def _run(self: \"Flow[P, T]\", *args: P.args, **kwargs: P.kwargs) -&gt; State[T]:\n        ...\n\n    def _run(\n        self,\n        *args: \"P.args\",\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: \"P.kwargs\",\n    ):\n        \"\"\"\n        Run the flow and return its final state.\n\n        Examples:\n\n            Run a flow and get the returned result\n\n            &gt;&gt;&gt; state = my_flow._run(\"marvin\")\n            &gt;&gt;&gt; state.result()\n           \"goodbye marvin\"\n        \"\"\"\n        from prefect.engine import enter_flow_run_engine_from_flow_call\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return enter_flow_run_engine_from_flow_call(\n            self,\n            parameters,\n            wait_for=wait_for,\n            return_type=\"state\",\n        )\n\n    @sync_compatible\n    async def visualize(self, *args, **kwargs):\n        \"\"\"\n        Generates a graphviz object representing the current flow. In IPython notebooks,\n        it's rendered inline, otherwise in a new window as a PNG.\n\n        Raises:\n            - ImportError: If `graphviz` isn't installed.\n            - GraphvizExecutableNotFoundError: If the `dot` executable isn't found.\n            - FlowVisualizationError: If the flow can't be visualized for any other reason.\n        \"\"\"\n        if not PREFECT_UNIT_TEST_MODE:\n            warnings.warn(\n                \"`flow.visualize()` will execute code inside of your flow that is not\"\n                \" decorated with `@task` or `@flow`.\"\n            )\n\n        try:\n            with TaskVizTracker() as tracker:\n                if self.isasync:\n                    await self.fn(*args, **kwargs)\n                else:\n                    self.fn(*args, **kwargs)\n\n                graph = build_task_dependencies(tracker)\n\n                visualize_task_dependencies(graph, self.name)\n\n        except GraphvizImportError:\n            raise\n        except GraphvizExecutableNotFoundError:\n            raise\n        except VisualizationUnsupportedError:\n            raise\n        except FlowVisualizationError:\n            raise\n        except Exception as e:\n            msg = (\n                \"It's possible you are trying to visualize a flow that contains \"\n                \"code that directly interacts with the result of a task\"\n                \" inside of the flow. \\nTry passing a `viz_return_value` \"\n                \"to the task decorator, e.g. `@task(viz_return_value=[1, 2, 3]).`\"\n            )\n\n            new_exception = type(e)(str(e) + \"\\n\" + msg)\n            # Copy traceback information from the original exception\n            new_exception.__traceback__ = e.__traceback__\n            raise new_exception\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploys a flow to run on dynamic infrastructure via a work pool.</p> <p>By default, calling this method will build a Docker image for the flow, push it to a registry, and create a deployment via the Prefect API that will run the flow on the given schedule.</p> <p>If you want to use an existing image, you can pass <code>build=False</code> to skip building and pushing an image.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name to give the created deployment.</p> required <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment. Defaults to the value of <code>PREFECT_DEFAULT_WORK_POOL_NAME</code>.</p> <code>None</code> <code>image</code> <code>Optional[Union[str, DeploymentImage]]</code> <p>The name of the Docker image to build, including the registry and repository. Pass a DeploymentImage instance to customize the Dockerfile used and build arguments.</p> <code>None</code> <code>build</code> <code>bool</code> <p>Whether or not to build a new image for the flow. If False, the provided image will be used as-is and pulled at runtime.</p> <code>True</code> <code>push</code> <code>bool</code> <p>Whether or not to skip pushing the built image to a registry.</p> <code>True</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[dict]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> <code>interval</code> <code>Optional[Union[int, float, timedelta]]</code> <p>An interval on which to execute the deployment. Accepts a number or a timedelta object to create a single schedule. If a number is given, it will be interpreted as seconds. Also accepts an iterable of numbers or timedelta to create multiple schedules.</p> <code>None</code> <code>cron</code> <code>Optional[str]</code> <p>A cron schedule string of when to execute runs of this deployment. Also accepts an iterable of cron schedule strings to create multiple schedules.</p> <code>None</code> <code>rrule</code> <code>Optional[str]</code> <p>An rrule schedule string of when to execute runs of this deployment. Also accepts an iterable of rrule schedule strings to create multiple schedules.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[MinimalDeploymentSchedule]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment. Used to define additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <code>print_next_steps_message</code> <p>Whether or not to print a message with next steps after deploying the deployments.</p> required <code>ignore_warnings</code> <code>bool</code> <p>Whether or not to ignore warnings about the work pool type.</p> <code>False</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The ID of the created/updated deployment.</p> <p>Examples:</p> <p>Deploy a local flow to a work pool:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        \"example-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my-repository/my-image:dev\",\n    )\n</code></pre> <p>Deploy a remotely stored flow to a work pool:</p> <pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/org/repo.git\",\n        entrypoint=\"flows.py:my_flow\",\n    ).deploy(\n        \"example-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my-repository/my-image:dev\",\n    )\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def deploy(\n    self,\n    name: str,\n    work_pool_name: Optional[str] = None,\n    image: Optional[Union[str, DeploymentImage]] = None,\n    build: bool = True,\n    push: bool = True,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[dict] = None,\n    interval: Optional[Union[int, float, datetime.timedelta]] = None,\n    cron: Optional[str] = None,\n    rrule: Optional[str] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[MinimalDeploymentSchedule]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    parameters: Optional[dict] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    print_next_steps: bool = True,\n    ignore_warnings: bool = False,\n) -&gt; UUID:\n    \"\"\"\n    Deploys a flow to run on dynamic infrastructure via a work pool.\n\n    By default, calling this method will build a Docker image for the flow, push it to a registry,\n    and create a deployment via the Prefect API that will run the flow on the given schedule.\n\n    If you want to use an existing image, you can pass `build=False` to skip building and pushing\n    an image.\n\n    Args:\n        name: The name to give the created deployment.\n        work_pool_name: The name of the work pool to use for this deployment. Defaults to\n            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n        image: The name of the Docker image to build, including the registry and\n            repository. Pass a DeploymentImage instance to customize the Dockerfile used\n            and build arguments.\n        build: Whether or not to build a new image for the flow. If False, the provided\n            image will be used as-is and pulled at runtime.\n        push: Whether or not to skip pushing the built image to a registry.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n        interval: An interval on which to execute the deployment. Accepts a number or a\n            timedelta object to create a single schedule. If a number is given, it will be\n            interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n            multiple schedules.\n        cron: A cron schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of cron schedule strings to create multiple schedules.\n        rrule: An rrule schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of rrule schedule strings to create multiple schedules.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment. Used to\n            define additional scheduling options like `timezone`.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n        print_next_steps_message: Whether or not to print a message with next steps\n            after deploying the deployments.\n        ignore_warnings: Whether or not to ignore warnings about the work pool type.\n\n    Returns:\n        The ID of the created/updated deployment.\n\n    Examples:\n        Deploy a local flow to a work pool:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.deploy(\n                \"example-deployment\",\n                work_pool_name=\"my-work-pool\",\n                image=\"my-repository/my-image:dev\",\n            )\n        ```\n\n        Deploy a remotely stored flow to a work pool:\n\n        ```python\n        from prefect import flow\n\n        if __name__ == \"__main__\":\n            flow.from_source(\n                source=\"https://github.com/org/repo.git\",\n                entrypoint=\"flows.py:my_flow\",\n            ).deploy(\n                \"example-deployment\",\n                work_pool_name=\"my-work-pool\",\n                image=\"my-repository/my-image:dev\",\n            )\n        ```\n    \"\"\"\n    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n    try:\n        async with get_client() as client:\n            work_pool = await client.read_work_pool(work_pool_name)\n    except ObjectNotFound as exc:\n        raise ValueError(\n            f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n            \" deploying this flow.\"\n        ) from exc\n\n    deployment = await self.to_deployment(\n        name=name,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedules=schedules,\n        paused=paused,\n        schedule=schedule,\n        is_schedule_active=is_schedule_active,\n        triggers=triggers,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n        entrypoint_type=entrypoint_type,\n    )\n\n    deployment_ids = await deploy(\n        deployment,\n        work_pool_name=work_pool_name,\n        image=image,\n        build=build,\n        push=push,\n        print_next_steps_message=False,\n        ignore_warnings=ignore_warnings,\n    )\n\n    if print_next_steps:\n        console = Console()\n        if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n            console.print(\n                \"\\nTo execute flow runs from this deployment, start a worker in a\"\n                \" separate terminal that pulls work from the\"\n                f\" {work_pool_name!r} work pool:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                style=\"blue\",\n            )\n        console.print(\n            \"\\nTo schedule a run for this deployment, use the following command:\"\n        )\n        console.print(\n            f\"\\n\\t$ prefect deployment run '{self.name}/{name}'\\n\",\n            style=\"blue\",\n        )\n        if PREFECT_UI_URL:\n            message = (\n                \"\\nYou can also run your flow via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\\n\"\n            )\n            console.print(message, soft_wrap=True)\n\n    return deployment_ids[0]\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.from_source","title":"<code>from_source</code>  <code>async</code> <code>classmethod</code>","text":"<p>Loads a flow from a remote source.</p> <p>Parameters:</p> Name Type Description Default <code>source</code> <code>Union[str, RunnerStorage, ReadableDeploymentStorage]</code> <p>Either a URL to a git repository or a storage object.</p> required <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <p>Returns:</p> Type Description <code>F</code> <p>A new <code>Flow</code> instance.</p> <p>Examples:</p> <p>Load a flow from a public git repository:</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=\"https://github.com/org/repo.git\",\n    entrypoint=\"flows.py:my_flow\",\n)\n\nmy_flow()\n</code></pre> <p>Load a flow from a private git repository using an access token stored in a <code>Secret</code> block:</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=GitRepository(\n        url=\"https://github.com/org/repo.git\",\n        credentials={\"access_token\": Secret.load(\"github-access-token\")}\n    ),\n    entrypoint=\"flows.py:my_flow\",\n)\n\nmy_flow()\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def from_source(\n    cls: Type[F],\n    source: Union[str, RunnerStorage, ReadableDeploymentStorage],\n    entrypoint: str,\n) -&gt; F:\n    \"\"\"\n    Loads a flow from a remote source.\n\n    Args:\n        source: Either a URL to a git repository or a storage object.\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n\n    Returns:\n        A new `Flow` instance.\n\n    Examples:\n        Load a flow from a public git repository:\n\n\n        ```python\n        from prefect import flow\n        from prefect.runner.storage import GitRepository\n        from prefect.blocks.system import Secret\n\n        my_flow = flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        )\n\n        my_flow()\n        ```\n\n        Load a flow from a private git repository using an access token stored in a `Secret` block:\n\n        ```python\n        from prefect import flow\n        from prefect.runner.storage import GitRepository\n        from prefect.blocks.system import Secret\n\n        my_flow = flow.from_source(\n            source=GitRepository(\n                url=\"https://github.com/org/repo.git\",\n                credentials={\"access_token\": Secret.load(\"github-access-token\")}\n            ),\n            entrypoint=\"flows.py:my_flow\",\n        )\n\n        my_flow()\n        ```\n    \"\"\"\n    if isinstance(source, str):\n        storage = create_storage_from_source(source)\n    elif isinstance(source, RunnerStorage):\n        storage = source\n    elif hasattr(source, \"get_directory\"):\n        storage = BlockStorageAdapter(source)\n    else:\n        raise TypeError(\n            f\"Unsupported source type {type(source).__name__!r}. Please provide a\"\n            \" URL to remote storage or a storage object.\"\n        )\n\n    with tempfile.TemporaryDirectory() as tmpdir:\n        if not isinstance(storage, LocalStorage):\n            storage.set_base_path(Path(tmpdir))\n            await storage.pull_code()\n\n        full_entrypoint = str(storage.destination / entrypoint)\n        flow: \"Flow\" = await from_async.wait_for_call_in_new_thread(\n            create_call(load_flow_from_entrypoint, full_entrypoint)\n        )\n        flow._storage = storage\n        flow._entrypoint = entrypoint\n\n    return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.serialize_parameters","title":"<code>serialize_parameters</code>","text":"<p>Convert parameters to a serializable form.</p> <p>Uses FastAPI's <code>jsonable_encoder</code> to convert to JSON compatible objects without converting everything directly to a string. This maintains basic types like integers during API roundtrips.</p> Source code in <code>prefect/flows.py</code> <pre><code>def serialize_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Convert parameters to a serializable form.\n\n    Uses FastAPI's `jsonable_encoder` to convert to JSON compatible objects without\n    converting everything directly to a string. This maintains basic types like\n    integers during API roundtrips.\n    \"\"\"\n    serialized_parameters = {}\n    for key, value in parameters.items():\n        try:\n            serialized_parameters[key] = jsonable_encoder(value)\n        except (TypeError, ValueError):\n            logger.debug(\n                f\"Parameter {key!r} for flow {self.name!r} is of unserializable \"\n                f\"type {type(value).__name__!r} and will not be stored \"\n                \"in the backend.\"\n            )\n            serialized_parameters[key] = f\"&lt;{type(value).__name__}&gt;\"\n    return serialized_parameters\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Creates a deployment for this flow and starts a runner to monitor for scheduled work.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>The name to give the created deployment. Defaults to the name of the flow.</p> <code>None</code> <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the deployment. Accepts a number or a timedelta object to create a single schedule. If a number is given, it will be interpreted as seconds. Also accepts an iterable of numbers or timedelta to create multiple schedules.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule string of when to execute runs of this deployment. Also accepts an iterable of cron schedule strings to create multiple schedules.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule string of when to execute runs of this deployment. Also accepts an iterable of rrule schedule strings to create multiple schedules.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[FlexibleScheduleList]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment. Used to define additional scheduling options such as <code>timezone</code>.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>pause_on_shutdown</code> <code>bool</code> <p>If True, provided schedule will be paused when the serve function is stopped. If False, the schedules will continue running.</p> <code>True</code> <code>print_starting_message</code> <code>bool</code> <p>Whether or not to print the starting message when flow is served.</p> <code>True</code> <code>limit</code> <code>Optional[int]</code> <p>The maximum number of runs that can be executed concurrently.</p> <code>None</code> <code>webserver</code> <code>bool</code> <p>Whether or not to start a monitoring webserver for this flow.</p> <code>False</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <p>Examples:</p> <p>Serve a flow:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\"example-deployment\")\n</code></pre> <p>Serve a flow and run it every hour:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\"example-deployment\", interval=3600)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def serve(\n    self,\n    name: Optional[str] = None,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    parameters: Optional[dict] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    pause_on_shutdown: bool = True,\n    print_starting_message: bool = True,\n    limit: Optional[int] = None,\n    webserver: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n):\n    \"\"\"\n    Creates a deployment for this flow and starts a runner to monitor for scheduled work.\n\n    Args:\n        name: The name to give the created deployment. Defaults to the name of the flow.\n        interval: An interval on which to execute the deployment. Accepts a number or a\n            timedelta object to create a single schedule. If a number is given, it will be\n            interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n            multiple schedules.\n        cron: A cron schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of cron schedule strings to create multiple schedules.\n        rrule: An rrule schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of rrule schedule strings to create multiple schedules.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment. Used to\n            define additional scheduling options such as `timezone`.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        pause_on_shutdown: If True, provided schedule will be paused when the serve function is stopped.\n            If False, the schedules will continue running.\n        print_starting_message: Whether or not to print the starting message when flow is served.\n        limit: The maximum number of runs that can be executed concurrently.\n        webserver: Whether or not to start a monitoring webserver for this flow.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n\n    Examples:\n        Serve a flow:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.serve(\"example-deployment\")\n        ```\n\n        Serve a flow and run it every hour:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.serve(\"example-deployment\", interval=3600)\n        ```\n    \"\"\"\n    from prefect.runner import Runner\n\n    if not name:\n        name = self.name\n    else:\n        # Handling for my_flow.serve(__file__)\n        # Will set name to name of file where my_flow.serve() without the extension\n        # Non filepath strings will pass through unchanged\n        name = Path(name).stem\n\n    runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown, limit=limit)\n    deployment_id = await runner.add_flow(\n        self,\n        name=name,\n        triggers=triggers,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        paused=paused,\n        schedules=schedules,\n        schedule=schedule,\n        is_schedule_active=is_schedule_active,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        entrypoint_type=entrypoint_type,\n    )\n    if print_starting_message:\n        help_message = (\n            f\"[green]Your flow {self.name!r} is being served and polling for\"\n            \" scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            f\" '{self.name}/{name}'\\n[/]\"\n        )\n        if PREFECT_UI_URL:\n            help_message += (\n                \"\\nYou can also run your flow via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n            )\n\n        console = Console()\n        console.print(help_message, soft_wrap=True)\n    await runner.start(webserver=webserver)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.to_deployment","title":"<code>to_deployment</code>  <code>async</code>","text":"<p>Creates a runner deployment object for this flow.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name to give the created deployment.</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the new deployment. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this deployment.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[FlexibleScheduleList]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options such as <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for</p> <code>None</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <p>Examples:</p> <p>Prepare two deployments and serve them:</p> <pre><code>from prefect import flow, serve\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef my_other_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\":\n    hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n    bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n    serve(hello_deploy, bye_deploy)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"schedule\",\n    start_date=\"Mar 2024\",\n    when=lambda p: p is not None,\n    help=\"Use `schedules` instead.\",\n)\n@deprecated_parameter(\n    \"is_schedule_active\",\n    start_date=\"Mar 2024\",\n    when=lambda p: p is not None,\n    help=\"Use `paused` instead.\",\n)\nasync def to_deployment(\n    self,\n    name: str,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Creates a runner deployment object for this flow.\n\n    Args:\n        name: The name to give the created deployment.\n        interval: An interval on which to execute the new deployment. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this deployment.\n        rrule: An rrule schedule of when to execute runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options such as `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n\n    Examples:\n        Prepare two deployments and serve them:\n\n        ```python\n        from prefect import flow, serve\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def my_other_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\":\n            hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n            bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n            serve(hello_deploy, bye_deploy)\n        ```\n    \"\"\"\n    from prefect.deployments.runner import RunnerDeployment\n\n    if not name.endswith(\".py\"):\n        raise_on_name_with_banned_characters(name)\n    if self._storage and self._entrypoint:\n        return await RunnerDeployment.from_storage(\n            storage=self._storage,\n            entrypoint=self._entrypoint,\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            tags=tags,\n            triggers=triggers,\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n    else:\n        return RunnerDeployment.from_flow(\n            self,\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            tags=tags,\n            triggers=triggers,\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n            entrypoint_type=entrypoint_type,\n        )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.validate_parameters","title":"<code>validate_parameters</code>","text":"<p>Validate parameters for compatibility with the flow by attempting to cast the inputs to the associated types specified by the function's type annotations.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A new dict of parameters that have been cast to the appropriate types</p> <p>Raises:</p> Type Description <code>ParameterTypeError</code> <p>if the provided parameters are not valid</p> Source code in <code>prefect/flows.py</code> <pre><code>def validate_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Validate parameters for compatibility with the flow by attempting to cast the inputs to the\n    associated types specified by the function's type annotations.\n\n    Returns:\n        A new dict of parameters that have been cast to the appropriate types\n\n    Raises:\n        ParameterTypeError: if the provided parameters are not valid\n    \"\"\"\n    args, kwargs = parameters_to_args_kwargs(self.fn, parameters)\n\n    if HAS_PYDANTIC_V2:\n        has_v1_models = any(isinstance(o, V1BaseModel) for o in args) or any(\n            isinstance(o, V1BaseModel) for o in kwargs.values()\n        )\n        has_v2_types = any(is_v2_type(o) for o in args) or any(\n            is_v2_type(o) for o in kwargs.values()\n        )\n\n        if has_v1_models and has_v2_types:\n            raise ParameterTypeError(\n                \"Cannot mix Pydantic v1 and v2 types as arguments to a flow.\"\n            )\n\n        if has_v1_models:\n            validated_fn = V1ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n        else:\n            validated_fn = V2ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n\n    else:\n        validated_fn = ValidatedFunction(\n            self.fn, config={\"arbitrary_types_allowed\": True}\n        )\n\n    try:\n        model = validated_fn.init_model_instance(*args, **kwargs)\n    except pydantic.ValidationError as exc:\n        # We capture the pydantic exception and raise our own because the pydantic\n        # exception is not picklable when using a cythonized pydantic installation\n        raise ParameterTypeError.from_validation_error(exc) from None\n    except V2ValidationError as exc:\n        # We capture the pydantic exception and raise our own because the pydantic\n        # exception is not picklable when using a cythonized pydantic installation\n        raise ParameterTypeError.from_validation_error(exc) from None\n\n    # Get the updated parameter dict with cast values from the model\n    cast_parameters = {\n        k: v\n        for k, v in model._iter()\n        if k in model.__fields_set__ or model.__fields__[k].default_factory\n    }\n    return cast_parameters\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.visualize","title":"<code>visualize</code>  <code>async</code>","text":"<p>Generates a graphviz object representing the current flow. In IPython notebooks, it's rendered inline, otherwise in a new window as a PNG.</p> <p>Raises:</p> Type Description <code>-ImportError</code> <p>If <code>graphviz</code> isn't installed.</p> <code>-GraphvizExecutableNotFoundError</code> <p>If the <code>dot</code> executable isn't found.</p> <code>-FlowVisualizationError</code> <p>If the flow can't be visualized for any other reason.</p> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def visualize(self, *args, **kwargs):\n    \"\"\"\n    Generates a graphviz object representing the current flow. In IPython notebooks,\n    it's rendered inline, otherwise in a new window as a PNG.\n\n    Raises:\n        - ImportError: If `graphviz` isn't installed.\n        - GraphvizExecutableNotFoundError: If the `dot` executable isn't found.\n        - FlowVisualizationError: If the flow can't be visualized for any other reason.\n    \"\"\"\n    if not PREFECT_UNIT_TEST_MODE:\n        warnings.warn(\n            \"`flow.visualize()` will execute code inside of your flow that is not\"\n            \" decorated with `@task` or `@flow`.\"\n        )\n\n    try:\n        with TaskVizTracker() as tracker:\n            if self.isasync:\n                await self.fn(*args, **kwargs)\n            else:\n                self.fn(*args, **kwargs)\n\n            graph = build_task_dependencies(tracker)\n\n            visualize_task_dependencies(graph, self.name)\n\n    except GraphvizImportError:\n        raise\n    except GraphvizExecutableNotFoundError:\n        raise\n    except VisualizationUnsupportedError:\n        raise\n    except FlowVisualizationError:\n        raise\n    except Exception as e:\n        msg = (\n            \"It's possible you are trying to visualize a flow that contains \"\n            \"code that directly interacts with the result of a task\"\n            \" inside of the flow. \\nTry passing a `viz_return_value` \"\n            \"to the task decorator, e.g. `@task(viz_return_value=[1, 2, 3]).`\"\n        )\n\n        new_exception = type(e)(str(e) + \"\\n\" + msg)\n        # Copy traceback information from the original exception\n        new_exception.__traceback__ = e.__traceback__\n        raise new_exception\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.with_options","title":"<code>with_options</code>","text":"<p>Create a new flow from the current object, updating provided options.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A new name for the flow.</p> <code>None</code> <code>version</code> <code>str</code> <p>A new version for the flow.</p> <code>None</code> <code>description</code> <code>str</code> <p>A new description for the flow.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>task_runner</code> <code>Union[Type[BaseTaskRunner], BaseTaskRunner]</code> <p>A new task runner for the flow.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>A new number of seconds to fail the flow after if still running.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>A new value indicating if flow calls should validate given parameters.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>A new number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[int, float]]</code> <p>A new number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling result persistence.</p> <code>NotSet</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>A new storage type to use for results.</p> <code>NotSet</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>A new serializer to use for results.</p> <code>NotSet</code> <code>cache_result_in_memory</code> <code>bool</code> <p>A new value indicating if the flow's result should be cached in memory.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a completed state.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a cancelling state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a crashed state.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a running state.</p> <code>None</code> <p>Returns:</p> Type Description <code>Self</code> <p>A new <code>Flow</code> instance.</p> <pre><code>Create a new flow from an existing flow and update the name:\n\n&gt;&gt;&gt; @flow(name=\"My flow\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\nCreate a new flow from an existing flow, update the task runner, and call\nit without an intermediate variable:\n\n&gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow(x, y):\n&gt;&gt;&gt;     return x + y\n&gt;&gt;&gt;\n&gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n&gt;&gt;&gt; assert state.result() == 4\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>def with_options(\n    self,\n    *,\n    name: str = None,\n    version: str = None,\n    retries: Optional[int] = None,\n    retry_delay_seconds: Optional[Union[int, float]] = None,\n    description: str = None,\n    flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n    task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = None,\n    timeout_seconds: Union[int, float] = None,\n    validate_parameters: bool = None,\n    persist_result: Optional[bool] = NotSet,\n    result_storage: Optional[ResultStorage] = NotSet,\n    result_serializer: Optional[ResultSerializer] = NotSet,\n    cache_result_in_memory: bool = None,\n    log_prints: Optional[bool] = NotSet,\n    on_completion: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_cancellation: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n) -&gt; Self:\n    \"\"\"\n    Create a new flow from the current object, updating provided options.\n\n    Args:\n        name: A new name for the flow.\n        version: A new version for the flow.\n        description: A new description for the flow.\n        flow_run_name: An optional name to distinguish runs of this flow; this name\n            can be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        task_runner: A new task runner for the flow.\n        timeout_seconds: A new number of seconds to fail the flow after if still\n            running.\n        validate_parameters: A new value indicating if flow calls should validate\n            given parameters.\n        retries: A new number of times to retry on flow run failure.\n        retry_delay_seconds: A new number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        persist_result: A new option for enabling or disabling result persistence.\n        result_storage: A new storage type to use for results.\n        result_serializer: A new serializer to use for results.\n        cache_result_in_memory: A new value indicating if the flow's result should\n            be cached in memory.\n        on_failure: A new list of callables to run when the flow enters a failed state.\n        on_completion: A new list of callables to run when the flow enters a completed state.\n        on_cancellation: A new list of callables to run when the flow enters a cancelling state.\n        on_crashed: A new list of callables to run when the flow enters a crashed state.\n        on_running: A new list of callables to run when the flow enters a running state.\n\n    Returns:\n        A new `Flow` instance.\n\n    Examples:\n\n        Create a new flow from an existing flow and update the name:\n\n        &gt;&gt;&gt; @flow(name=\"My flow\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\n        Create a new flow from an existing flow, update the task runner, and call\n        it without an intermediate variable:\n\n        &gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow(x, y):\n        &gt;&gt;&gt;     return x + y\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n        &gt;&gt;&gt; assert state.result() == 4\n\n    \"\"\"\n    new_flow = Flow(\n        fn=self.fn,\n        name=name or self.name,\n        description=description or self.description,\n        flow_run_name=flow_run_name or self.flow_run_name,\n        version=version or self.version,\n        task_runner=task_runner or self.task_runner,\n        retries=retries if retries is not None else self.retries,\n        retry_delay_seconds=(\n            retry_delay_seconds\n            if retry_delay_seconds is not None\n            else self.retry_delay_seconds\n        ),\n        timeout_seconds=(\n            timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n        ),\n        validate_parameters=(\n            validate_parameters\n            if validate_parameters is not None\n            else self.should_validate_parameters\n        ),\n        persist_result=(\n            persist_result if persist_result is not NotSet else self.persist_result\n        ),\n        result_storage=(\n            result_storage if result_storage is not NotSet else self.result_storage\n        ),\n        result_serializer=(\n            result_serializer\n            if result_serializer is not NotSet\n            else self.result_serializer\n        ),\n        cache_result_in_memory=(\n            cache_result_in_memory\n            if cache_result_in_memory is not None\n            else self.cache_result_in_memory\n        ),\n        log_prints=log_prints if log_prints is not NotSet else self.log_prints,\n        on_completion=on_completion or self.on_completion,\n        on_failure=on_failure or self.on_failure,\n        on_cancellation=on_cancellation or self.on_cancellation,\n        on_crashed=on_crashed or self.on_crashed,\n        on_running=on_running or self.on_running,\n    )\n    new_flow._storage = self._storage\n    new_flow._entrypoint = self._entrypoint\n    return new_flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.flow","title":"<code>flow</code>","text":"<p>Decorator to designate a function as a Prefect workflow.</p> <p>This decorator may be used for asynchronous or synchronous functions.</p> <p>Flow parameters must be serializable by Pydantic.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional version string for the flow; if not provided, we will attempt to create a version string as a hash of the file containing the wrapped function; if the file cannot be located, the version will be null.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>int</code> <p>An optional number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>task_runner</code> <code>BaseTaskRunner</code> <p>An optional task runner to use for task execution within the flow; if not provided, a <code>ConcurrentTaskRunner</code> will be instantiated.</p> <code>ConcurrentTaskRunner</code> <code>description</code> <code>str</code> <p>An optional string description for the flow; if not provided, the description will be pulled from the docstring for the decorated function.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>By default, parameters passed to flows are validated by Pydantic. This will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type; for example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p> <code>True</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this flow should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this flow. This value will be used as the default for any tasks in this flow. If not provided, the local file system will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this flow for persistence. This value will be used as the default for any tasks in this flow. If not provided, the value of <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>cache_result_in_memory</code> <code>bool</code> <p>An optional toggle indicating whether the cached result of a running the flow should be stored in memory. Defaults to <code>True</code>.</p> <code>True</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the flow will be redirected to the Prefect logger for the flow run. Defaults to <code>None</code>, which indicates that the value from the parent flow should be used. If this is a parent flow, the default is pulled from the <code>PREFECT_LOGGING_LOG_PRINTS</code> setting.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], Union[Awaitable[None], None]]]]</code> <p>An optional list of functions to call when the flow run is completed. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], Union[Awaitable[None], None]]]]</code> <p>An optional list of functions to call when the flow run fails. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run is cancelled. These functions will be passed the flow, flow run, and final state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run crashes. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run is started. Each function should accept three arguments: the flow, the flow run, and the current state</p> <code>None</code> <p>Returns:</p> Type Description <p>A callable <code>Flow</code> object which, when called, will run the flow and return its</p> <p>final state.</p> <p>Examples:</p> <p>Define a simple flow</p> <pre><code>&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define an async flow</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define a flow with a version and description</p> <pre><code>&gt;&gt;&gt; @flow(version=\"first-flow\", description=\"This flow is empty!\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a flow with a custom name</p> <pre><code>&gt;&gt;&gt; @flow(name=\"The Ultimate Flow\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a flow that submits its tasks to dask</p> <pre><code>&gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow(task_runner=DaskTaskRunner)\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>def flow(\n    __fn=None,\n    *,\n    name: Optional[str] = None,\n    version: Optional[str] = None,\n    flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n    retries: int = None,\n    retry_delay_seconds: Union[int, float] = None,\n    task_runner: BaseTaskRunner = ConcurrentTaskRunner,\n    description: str = None,\n    timeout_seconds: Union[int, float] = None,\n    validate_parameters: bool = True,\n    persist_result: Optional[bool] = None,\n    result_storage: Optional[ResultStorage] = None,\n    result_serializer: Optional[ResultSerializer] = None,\n    cache_result_in_memory: bool = True,\n    log_prints: Optional[bool] = None,\n    on_completion: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_failure: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_cancellation: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n):\n    \"\"\"\n    Decorator to designate a function as a Prefect workflow.\n\n    This decorator may be used for asynchronous or synchronous functions.\n\n    Flow parameters must be serializable by Pydantic.\n\n    Args:\n        name: An optional name for the flow; if not provided, the name will be inferred\n            from the given function.\n        version: An optional version string for the flow; if not provided, we will\n            attempt to create a version string as a hash of the file containing the\n            wrapped function; if the file cannot be located, the version will be null.\n        flow_run_name: An optional name to distinguish runs of this flow; this name can\n            be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on flow run failure.\n        retry_delay_seconds: An optional number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        task_runner: An optional task runner to use for task execution within the flow; if\n            not provided, a `ConcurrentTaskRunner` will be instantiated.\n        description: An optional string description for the flow; if not provided, the\n            description will be pulled from the docstring for the decorated function.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the flow. If the flow exceeds this runtime, it will be marked as failed.\n            Flow execution may continue until the next task is called.\n        validate_parameters: By default, parameters passed to flows are validated by\n            Pydantic. This will check that input values conform to the annotated types\n            on the function. Where possible, values will be coerced into the correct\n            type; for example, if a parameter is defined as `x: int` and \"5\" is passed,\n            it will be resolved to `5`. If set to `False`, no validation will be\n            performed on flow parameters.\n        persist_result: An optional toggle indicating whether the result of this flow\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this flow.\n            This value will be used as the default for any tasks in this flow.\n            If not provided, the local file system will be used unless called as\n            a subflow, at which point the default will be loaded from the parent flow.\n        result_serializer: An optional serializer to use to serialize the result of this\n            flow for persistence. This value will be used as the default for any tasks\n            in this flow. If not provided, the value of `PREFECT_RESULTS_DEFAULT_SERIALIZER`\n            will be used unless called as a subflow, at which point the default will be\n            loaded from the parent flow.\n        cache_result_in_memory: An optional toggle indicating whether the cached result of\n            a running the flow should be stored in memory. Defaults to `True`.\n        log_prints: If set, `print` statements in the flow will be redirected to the\n            Prefect logger for the flow run. Defaults to `None`, which indicates that\n            the value from the parent flow should be used. If this is a parent flow,\n            the default is pulled from the `PREFECT_LOGGING_LOG_PRINTS` setting.\n        on_completion: An optional list of functions to call when the flow run is\n            completed. Each function should accept three arguments: the flow, the flow\n            run, and the final state of the flow run.\n        on_failure: An optional list of functions to call when the flow run fails. Each\n            function should accept three arguments: the flow, the flow run, and the\n            final state of the flow run.\n        on_cancellation: An optional list of functions to call when the flow run is\n            cancelled. These functions will be passed the flow, flow run, and final state.\n        on_crashed: An optional list of functions to call when the flow run crashes. Each\n            function should accept three arguments: the flow, the flow run, and the\n            final state of the flow run.\n        on_running: An optional list of functions to call when the flow run is started. Each\n            function should accept three arguments: the flow, the flow run, and the current state\n\n    Returns:\n        A callable `Flow` object which, when called, will run the flow and return its\n        final state.\n\n    Examples:\n        Define a simple flow\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define an async flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define a flow with a version and description\n\n        &gt;&gt;&gt; @flow(version=\"first-flow\", description=\"This flow is empty!\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n\n        Define a flow with a custom name\n\n        &gt;&gt;&gt; @flow(name=\"The Ultimate Flow\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n\n        Define a flow that submits its tasks to dask\n\n        &gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow(task_runner=DaskTaskRunner)\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n    \"\"\"\n    if __fn:\n        return cast(\n            Flow[P, R],\n            Flow(\n                fn=__fn,\n                name=name,\n                version=version,\n                flow_run_name=flow_run_name,\n                task_runner=task_runner,\n                description=description,\n                timeout_seconds=timeout_seconds,\n                validate_parameters=validate_parameters,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                log_prints=log_prints,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                on_cancellation=on_cancellation,\n                on_crashed=on_crashed,\n                on_running=on_running,\n            ),\n        )\n    else:\n        return cast(\n            Callable[[Callable[P, R]], Flow[P, R]],\n            partial(\n                flow,\n                name=name,\n                version=version,\n                flow_run_name=flow_run_name,\n                task_runner=task_runner,\n                description=description,\n                timeout_seconds=timeout_seconds,\n                validate_parameters=validate_parameters,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                log_prints=log_prints,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                on_cancellation=on_cancellation,\n                on_crashed=on_crashed,\n                on_running=on_running,\n            ),\n        )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.is_entrypoint_async","title":"<code>is_entrypoint_async</code>","text":"<p>Determine if the function specified in the entrypoint is asynchronous.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>A string in the format <code>&lt;path_to_script&gt;:&lt;func_name&gt;</code> or a module path to a function.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the function is asynchronous, False otherwise.</p> Source code in <code>prefect/flows.py</code> <pre><code>def is_entrypoint_async(entrypoint: str) -&gt; bool:\n    \"\"\"\n    Determine if the function specified in the entrypoint is asynchronous.\n\n    Args:\n        entrypoint: A string in the format `&lt;path_to_script&gt;:&lt;func_name&gt;` or\n          a module path to a function.\n\n    Returns:\n        True if the function is asynchronous, False otherwise.\n    \"\"\"\n    func_def, _ = _entrypoint_definition_and_source(entrypoint)\n    return isinstance(func_def, ast.AsyncFunctionDef)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_arguments_from_entrypoint","title":"<code>load_flow_arguments_from_entrypoint</code>","text":"<p>Extract flow arguments from an entrypoint string.</p> <p>Loads the source code of the entrypoint and extracts the flow arguments from the <code>flow</code> decorator.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_arguments_from_entrypoint(\n    entrypoint: str, arguments: Optional[Union[List[str], Set[str]]] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Extract flow arguments from an entrypoint string.\n\n    Loads the source code of the entrypoint and extracts the flow arguments\n    from the `flow` decorator.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n    \"\"\"\n\n    func_def, source_code = _entrypoint_definition_and_source(entrypoint)\n    path = None\n    if \":\" in entrypoint:\n        path = entrypoint.rsplit(\":\")[0]\n\n    if arguments is None:\n        # If no arguments are provided default to known arguments that are of\n        # built-in types.\n        arguments = {\n            \"name\",\n            \"version\",\n            \"retries\",\n            \"retry_delay_seconds\",\n            \"description\",\n            \"timeout_seconds\",\n            \"validate_parameters\",\n            \"persist_result\",\n            \"cache_result_in_memory\",\n            \"log_prints\",\n        }\n\n    result = {}\n\n    for decorator in func_def.decorator_list:\n        if (\n            isinstance(decorator, ast.Call)\n            and getattr(decorator.func, \"id\", \"\") == \"flow\"\n        ):\n            for keyword in decorator.keywords:\n                if keyword.arg not in arguments:\n                    continue\n\n                if isinstance(keyword.value, ast.Constant):\n                    # Use the string value of the argument\n                    result[keyword.arg] = str(keyword.value.value)\n                    continue\n\n                # if the arg value is not a raw str (i.e. a variable or expression),\n                # then attempt to evaluate it\n                namespace = safe_load_namespace(source_code, filepath=path)\n                literal_arg_value = ast.get_source_segment(source_code, keyword.value)\n                cleaned_value = (\n                    literal_arg_value.replace(\"\\n\", \"\") if literal_arg_value else \"\"\n                )\n\n                try:\n                    evaluated_value = eval(cleaned_value, namespace)  # type: ignore\n                    result[keyword.arg] = str(evaluated_value)\n                except Exception as e:\n                    logger.info(\n                        \"Failed to parse @flow argument: `%s=%s` due to the following error. Ignoring and falling back to default behavior.\",\n                        keyword.arg,\n                        literal_arg_value,\n                        exc_info=e,\n                    )\n                    # ignore the decorator arg and fallback to default behavior\n                    continue\n\n    if \"name\" in arguments and \"name\" not in result:\n        # If no matching decorator or keyword argument for `name' is found\n        # fallback to the function name.\n        result[\"name\"] = func_def.name.replace(\"_\", \"-\")\n\n    return result\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_entrypoint","title":"<code>load_flow_from_entrypoint</code>","text":"<p>Extract a flow object from a script at an entrypoint by running all of the code in the file.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required <code>use_placeholder_flow</code> <code>bool</code> <p>If True, a placeholder flow will be used if the entrypoint cannot be loaded for any reason (e.g. dependencies are missing). If False, an exception will be raised.</p> <code>True</code> <p>Returns:</p> Type Description <code>Flow</code> <p>The flow object from the script</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> <code>MissingFlowError</code> <p>If the flow function specified in the entrypoint does not exist</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_entrypoint(\n    entrypoint: str,\n    use_placeholder_flow: bool = True,\n) -&gt; Flow:\n    \"\"\"\n    Extract a flow object from a script at an entrypoint by running all of the code in the file.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;` or a module path\n            to a flow function\n        use_placeholder_flow: If True, a placeholder flow will be used if the entrypoint\n            cannot be loaded for any reason (e.g. dependencies are missing). If False, an\n            exception will be raised.\n\n    Returns:\n        The flow object from the script\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n        MissingFlowError: If the flow function specified in the entrypoint does not exist\n    \"\"\"\n    with PrefectObjectRegistry(\n        block_code_execution=True,\n        capture_failures=True,\n    ):\n        if \":\" in entrypoint:\n            # split by the last colon once to handle Windows paths with drive letters i.e C:\\path\\to\\file.py:do_stuff\n            path, func_name = entrypoint.rsplit(\":\", maxsplit=1)\n\n        else:\n            path, func_name = entrypoint.rsplit(\".\", maxsplit=1)\n        try:\n            flow = import_object(entrypoint)\n        except AttributeError as exc:\n            raise MissingFlowError(\n                f\"Flow function with name {func_name!r} not found in {path!r}. \"\n            ) from exc\n        except ScriptError:\n            # If the flow has dependencies that are not installed in the current\n            # environment, fallback to loading the flow via AST parsing.\n            if use_placeholder_flow:\n                flow = safe_load_flow_from_entrypoint(entrypoint)\n                if flow is None:\n                    raise\n            else:\n                raise\n\n        if not isinstance(flow, Flow):\n            raise MissingFlowError(\n                f\"Function with name {func_name!r} is not a flow. Make sure that it is \"\n                \"decorated with '@flow'.\"\n            )\n\n        return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_script","title":"<code>load_flow_from_script</code>","text":"<p>Extract a flow object from a script by running all of the code in the file.</p> <p>If the script has multiple flows in it, a flow name must be provided to specify the flow to return.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>A path to a Python script containing flows</p> required <code>flow_name</code> <code>str</code> <p>An optional flow name to look for in the script</p> <code>None</code> <p>Returns:</p> Type Description <code>Flow</code> <p>The flow object from the script</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> <code>MissingFlowError</code> <p>If no flows exist in the iterable</p> <code>MissingFlowError</code> <p>If a flow name is provided and that flow does not exist</p> <code>UnspecifiedFlowError</code> <p>If multiple flows exist but no flow name was provided</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_script(path: str, flow_name: str = None) -&gt; Flow:\n    \"\"\"\n    Extract a flow object from a script by running all of the code in the file.\n\n    If the script has multiple flows in it, a flow name must be provided to specify\n    the flow to return.\n\n    Args:\n        path: A path to a Python script containing flows\n        flow_name: An optional flow name to look for in the script\n\n    Returns:\n        The flow object from the script\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n        MissingFlowError: If no flows exist in the iterable\n        MissingFlowError: If a flow name is provided and that flow does not exist\n        UnspecifiedFlowError: If multiple flows exist but no flow name was provided\n    \"\"\"\n    return select_flow(\n        load_flows_from_script(path),\n        flow_name=flow_name,\n        from_message=f\"in script '{path}'\",\n    )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_text","title":"<code>load_flow_from_text</code>","text":"<p>Load a flow from a text script.</p> <p>The script will be written to a temporary local file path so errors can refer to line numbers and contextual tracebacks can be provided.</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_text(script_contents: AnyStr, flow_name: str):\n    \"\"\"\n    Load a flow from a text script.\n\n    The script will be written to a temporary local file path so errors can refer\n    to line numbers and contextual tracebacks can be provided.\n    \"\"\"\n    with NamedTemporaryFile(\n        mode=\"wt\" if isinstance(script_contents, str) else \"wb\",\n        prefix=f\"flow-script-{flow_name}\",\n        suffix=\".py\",\n        delete=False,\n    ) as tmpfile:\n        tmpfile.write(script_contents)\n        tmpfile.flush()\n    try:\n        flow = load_flow_from_script(tmpfile.name, flow_name=flow_name)\n    finally:\n        # windows compat\n        tmpfile.close()\n        os.remove(tmpfile.name)\n    return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flows_from_script","title":"<code>load_flows_from_script</code>","text":"<p>Load all flow objects from the given python script. All of the code in the file will be executed.</p> <p>Returns:</p> Type Description <code>List[Flow]</code> <p>A list of flows</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flows_from_script(path: str) -&gt; List[Flow]:\n    \"\"\"\n    Load all flow objects from the given python script. All of the code in the file\n    will be executed.\n\n    Returns:\n        A list of flows\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n    \"\"\"\n    return registry_from_script(path).get_instances(Flow)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_placeholder_flow","title":"<code>load_placeholder_flow</code>","text":"<p>Load a placeholder flow that is initialized with the same arguments as the flow specified in the entrypoint. If called the flow will raise <code>raises</code>.</p> <p>This is useful when a flow can't be loaded due to missing dependencies or other issues but the base metadata defining the flow is still needed.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required <code>raises</code> <code>Exception</code> <p>an exception to raise when the flow is called</p> required Source code in <code>prefect/flows.py</code> <pre><code>def load_placeholder_flow(entrypoint: str, raises: Exception):\n    \"\"\"\n    Load a placeholder flow that is initialized with the same arguments as the\n    flow specified in the entrypoint. If called the flow will raise `raises`.\n\n    This is useful when a flow can't be loaded due to missing dependencies or\n    other issues but the base metadata defining the flow is still needed.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n        raises: an exception to raise when the flow is called\n    \"\"\"\n\n    def _base_placeholder():\n        raise raises\n\n    def sync_placeholder_flow(*args, **kwargs):\n        _base_placeholder()\n\n    async def async_placeholder_flow(*args, **kwargs):\n        _base_placeholder()\n\n    placeholder_flow = (\n        async_placeholder_flow\n        if is_entrypoint_async(entrypoint)\n        else sync_placeholder_flow\n    )\n\n    arguments = load_flow_arguments_from_entrypoint(entrypoint)\n    arguments[\"fn\"] = placeholder_flow\n\n    return Flow(**arguments)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.safe_load_flow_from_entrypoint","title":"<code>safe_load_flow_from_entrypoint</code>","text":"<p>Load a flow from an entrypoint and return None if an exception is raised.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required Source code in <code>prefect/flows.py</code> <pre><code>def safe_load_flow_from_entrypoint(entrypoint: str) -&gt; Optional[Flow]:\n    \"\"\"\n    Load a flow from an entrypoint and return None if an exception is raised.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n    \"\"\"\n    func_def, source_code = _entrypoint_definition_and_source(entrypoint)\n    path = None\n    if \":\" in entrypoint:\n        path = entrypoint.rsplit(\":\")[0]\n    namespace = safe_load_namespace(source_code, filepath=path)\n    if func_def.name in namespace:\n        return namespace[func_def.name]\n    else:\n        # If the function is not in the namespace, if may be due to missing dependencies\n        # for the function. We will attempt to compile each annotation and default value\n        # and remove them from the function definition to see if the function can be\n        # compiled without them.\n\n        return _sanitize_and_load_flow(func_def, namespace)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.select_flow","title":"<code>select_flow</code>","text":"<p>Select the only flow in an iterable or a flow specified by name.</p> <p>Returns     A single flow object</p> <p>Raises:</p> Type Description <code>MissingFlowError</code> <p>If no flows exist in the iterable</p> <code>MissingFlowError</code> <p>If a flow name is provided and that flow does not exist</p> <code>UnspecifiedFlowError</code> <p>If multiple flows exist but no flow name was provided</p> Source code in <code>prefect/flows.py</code> <pre><code>def select_flow(\n    flows: Iterable[Flow], flow_name: str = None, from_message: str = None\n) -&gt; Flow:\n    \"\"\"\n    Select the only flow in an iterable or a flow specified by name.\n\n    Returns\n        A single flow object\n\n    Raises:\n        MissingFlowError: If no flows exist in the iterable\n        MissingFlowError: If a flow name is provided and that flow does not exist\n        UnspecifiedFlowError: If multiple flows exist but no flow name was provided\n    \"\"\"\n    # Convert to flows by name\n    flows = {f.name: f for f in flows}\n\n    # Add a leading space if given, otherwise use an empty string\n    from_message = (\" \" + from_message) if from_message else \"\"\n    if not flows:\n        raise MissingFlowError(f\"No flows found{from_message}.\")\n\n    elif flow_name and flow_name not in flows:\n        raise MissingFlowError(\n            f\"Flow {flow_name!r} not found{from_message}. \"\n            f\"Found the following flows: {listrepr(flows.keys())}. \"\n            \"Check to make sure that your flow function is decorated with `@flow`.\"\n        )\n\n    elif not flow_name and len(flows) &gt; 1:\n        raise UnspecifiedFlowError(\n            (\n                f\"Found {len(flows)} flows{from_message}:\"\n                f\" {listrepr(sorted(flows.keys()))}. Specify a flow name to select a\"\n                \" flow.\"\n            ),\n        )\n\n    if flow_name:\n        return flows[flow_name]\n    else:\n        return list(flows.values())[0]\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Serve the provided list of deployments.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>RunnerDeployment</code> <p>A list of deployments to serve.</p> <code>()</code> <code>pause_on_shutdown</code> <code>bool</code> <p>A boolean for whether or not to automatically pause deployment schedules on shutdown.</p> <code>True</code> <code>print_starting_message</code> <code>bool</code> <p>Whether or not to print message to the console on startup.</p> <code>True</code> <code>limit</code> <code>Optional[int]</code> <p>The maximum number of runs that can be executed concurrently.</p> <code>None</code> <code>**kwargs</code> <p>Additional keyword arguments to pass to the runner.</p> <code>{}</code> <p>Examples:</p> <p>Prepare two deployments and serve them:</p> <pre><code>import datetime\n\nfrom prefect import flow, serve\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef my_other_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\":\n    # Run once a day\n    hello_deploy = my_flow.to_deployment(\n        \"hello\", tags=[\"dev\"], interval=datetime.timedelta(days=1)\n    )\n\n    # Run every Sunday at 4:00 AM\n    bye_deploy = my_other_flow.to_deployment(\n        \"goodbye\", tags=[\"dev\"], cron=\"0 4 * * sun\"\n    )\n\n    serve(hello_deploy, bye_deploy)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def serve(\n    *args: \"RunnerDeployment\",\n    pause_on_shutdown: bool = True,\n    print_starting_message: bool = True,\n    limit: Optional[int] = None,\n    **kwargs,\n):\n    \"\"\"\n    Serve the provided list of deployments.\n\n    Args:\n        *args: A list of deployments to serve.\n        pause_on_shutdown: A boolean for whether or not to automatically pause\n            deployment schedules on shutdown.\n        print_starting_message: Whether or not to print message to the console\n            on startup.\n        limit: The maximum number of runs that can be executed concurrently.\n        **kwargs: Additional keyword arguments to pass to the runner.\n\n    Examples:\n        Prepare two deployments and serve them:\n\n        ```python\n        import datetime\n\n        from prefect import flow, serve\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def my_other_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\":\n            # Run once a day\n            hello_deploy = my_flow.to_deployment(\n                \"hello\", tags=[\"dev\"], interval=datetime.timedelta(days=1)\n            )\n\n            # Run every Sunday at 4:00 AM\n            bye_deploy = my_other_flow.to_deployment(\n                \"goodbye\", tags=[\"dev\"], cron=\"0 4 * * sun\"\n            )\n\n            serve(hello_deploy, bye_deploy)\n        ```\n    \"\"\"\n    from rich.console import Console, Group\n    from rich.table import Table\n\n    from prefect.runner import Runner\n\n    runner = Runner(pause_on_shutdown=pause_on_shutdown, limit=limit, **kwargs)\n    for deployment in args:\n        await runner.add_deployment(deployment)\n\n    if print_starting_message:\n        help_message_top = (\n            \"[green]Your deployments are being served and polling for\"\n            \" scheduled runs!\\n[/]\"\n        )\n\n        table = Table(title=\"Deployments\", show_header=False)\n\n        table.add_column(style=\"blue\", no_wrap=True)\n\n        for deployment in args:\n            table.add_row(f\"{deployment.flow_name}/{deployment.name}\")\n\n        help_message_bottom = (\n            \"\\nTo trigger any of these deployments, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            \" [DEPLOYMENT_NAME]\\n[/]\"\n        )\n        if PREFECT_UI_URL:\n            help_message_bottom += (\n                \"\\nYou can also trigger your deployments via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments[/]\\n\"\n            )\n\n        console = Console()\n        console.print(\n            Group(help_message_top, table, help_message_bottom), soft_wrap=True\n        )\n\n    await runner.start()\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/futures/","title":"prefect.futures","text":"","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures","title":"<code>prefect.futures</code>","text":"<p>Futures represent the execution of a task and allow retrieval of the task run's state.</p> <p>This module contains the definition for futures as well as utilities for resolving futures in nested data structures.</p>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture","title":"<code>PrefectFuture</code>","text":"<p>               Bases: <code>Generic[R, A]</code></p> <p>Represents the result of a computation happening in a task runner.</p> <p>When tasks are called, they are submitted to a task runner which creates a future for access to the state and result of the task.</p> <p>Examples:</p> <p>Define a task that returns a string</p> <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task() -&gt; str:\n&gt;&gt;&gt;     return \"hello\"\n</code></pre> <p>Calls of this task in a flow will return a future</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()  # PrefectFuture[str, Sync] includes result type\n&gt;&gt;&gt;     future.task_run.id  # UUID for the task run\n</code></pre> <p>Wait for the task to complete</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     final_state = future.wait()\n</code></pre> <p>Wait N seconds for the task to complete</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     final_state = future.wait(0.1)\n&gt;&gt;&gt;     if final_state:\n&gt;&gt;&gt;         ... # Task done\n&gt;&gt;&gt;     else:\n&gt;&gt;&gt;         ... # Task not done yet\n</code></pre> <p>Wait for a task to complete and retrieve its result</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     result = future.result()\n&gt;&gt;&gt;     assert result == \"hello\"\n</code></pre> <p>Wait N seconds for a task to complete and retrieve its result</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     result = future.result(timeout=5)\n&gt;&gt;&gt;     assert result == \"hello\"\n</code></pre> <p>Retrieve the state of a task without waiting for completion</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     state = future.get_state()\n</code></pre> Source code in <code>prefect/futures.py</code> <pre><code>class PrefectFuture(Generic[R, A]):\n    \"\"\"\n    Represents the result of a computation happening in a task runner.\n\n    When tasks are called, they are submitted to a task runner which creates a future\n    for access to the state and result of the task.\n\n    Examples:\n        Define a task that returns a string\n\n        &gt;&gt;&gt; from prefect import flow, task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task() -&gt; str:\n        &gt;&gt;&gt;     return \"hello\"\n\n        Calls of this task in a flow will return a future\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()  # PrefectFuture[str, Sync] includes result type\n        &gt;&gt;&gt;     future.task_run.id  # UUID for the task run\n\n        Wait for the task to complete\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     final_state = future.wait()\n\n        Wait N seconds for the task to complete\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     final_state = future.wait(0.1)\n        &gt;&gt;&gt;     if final_state:\n        &gt;&gt;&gt;         ... # Task done\n        &gt;&gt;&gt;     else:\n        &gt;&gt;&gt;         ... # Task not done yet\n\n        Wait for a task to complete and retrieve its result\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     result = future.result()\n        &gt;&gt;&gt;     assert result == \"hello\"\n\n        Wait N seconds for a task to complete and retrieve its result\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     result = future.result(timeout=5)\n        &gt;&gt;&gt;     assert result == \"hello\"\n\n        Retrieve the state of a task without waiting for completion\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     state = future.get_state()\n    \"\"\"\n\n    def __init__(\n        self,\n        name: str,\n        key: UUID,\n        task_runner: \"BaseTaskRunner\",\n        asynchronous: A = True,\n        _final_state: State[R] = None,  # Exposed for testing\n    ) -&gt; None:\n        self.key = key\n        self.name = name\n        self.asynchronous = asynchronous\n        self.task_run = None\n        self._final_state = _final_state\n        self._exception: Optional[Exception] = None\n        self._task_runner = task_runner\n        self._submitted = anyio.Event()\n\n        self._loop = asyncio.get_running_loop()\n\n    @overload\n    def wait(\n        self: \"PrefectFuture[R, Async]\", timeout: None = None\n    ) -&gt; Awaitable[State[R]]:\n        ...\n\n    @overload\n    def wait(self: \"PrefectFuture[R, Sync]\", timeout: None = None) -&gt; State[R]:\n        ...\n\n    @overload\n    def wait(\n        self: \"PrefectFuture[R, Async]\", timeout: float\n    ) -&gt; Awaitable[Optional[State[R]]]:\n        ...\n\n    @overload\n    def wait(self: \"PrefectFuture[R, Sync]\", timeout: float) -&gt; Optional[State[R]]:\n        ...\n\n    def wait(self, timeout=None):\n        \"\"\"\n        Wait for the run to finish and return the final state\n\n        If the timeout is reached before the run reaches a final state,\n        `None` is returned.\n        \"\"\"\n        wait = create_call(self._wait, timeout=timeout)\n        if self.asynchronous:\n            return from_async.call_soon_in_loop_thread(wait).aresult()\n        else:\n            # type checking cannot handle the overloaded timeout passing\n            return from_sync.call_soon_in_loop_thread(wait).result()  # type: ignore\n\n    @overload\n    async def _wait(self, timeout: None = None) -&gt; State[R]:\n        ...\n\n    @overload\n    async def _wait(self, timeout: float) -&gt; Optional[State[R]]:\n        ...\n\n    async def _wait(self, timeout=None):\n        \"\"\"\n        Async implementation for `wait`\n        \"\"\"\n        await self._wait_for_submission()\n\n        if self._final_state:\n            return self._final_state\n\n        self._final_state = await self._task_runner.wait(self.key, timeout)\n        return self._final_state\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Sync]\",\n        timeout: float = None,\n        raise_on_failure: bool = True,\n    ) -&gt; R:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Sync]\",\n        timeout: float = None,\n        raise_on_failure: bool = False,\n    ) -&gt; Union[R, Exception]:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Async]\",\n        timeout: float = None,\n        raise_on_failure: bool = True,\n    ) -&gt; Awaitable[R]:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Async]\",\n        timeout: float = None,\n        raise_on_failure: bool = False,\n    ) -&gt; Awaitable[Union[R, Exception]]:\n        ...\n\n    def result(self, timeout: float = None, raise_on_failure: bool = True):\n        \"\"\"\n        Wait for the run to finish and return the final state.\n\n        If the timeout is reached before the run reaches a final state, a `TimeoutError`\n        will be raised.\n\n        If `raise_on_failure` is `True` and the task run failed, the task run's\n        exception will be raised.\n        \"\"\"\n        result = create_call(\n            self._result, timeout=timeout, raise_on_failure=raise_on_failure\n        )\n        if self.asynchronous:\n            return from_async.call_soon_in_loop_thread(result).aresult()\n        else:\n            return from_sync.call_soon_in_loop_thread(result).result()\n\n    async def _result(self, timeout: float = None, raise_on_failure: bool = True):\n        \"\"\"\n        Async implementation of `result`\n        \"\"\"\n        final_state = await self._wait(timeout=timeout)\n        if not final_state:\n            raise TimeoutError(\"Call timed out before task finished.\")\n        return await final_state.result(raise_on_failure=raise_on_failure, fetch=True)\n\n    @overload\n    def get_state(\n        self: \"PrefectFuture[R, Async]\", client: PrefectClient = None\n    ) -&gt; Awaitable[State[R]]:\n        ...\n\n    @overload\n    def get_state(\n        self: \"PrefectFuture[R, Sync]\", client: PrefectClient = None\n    ) -&gt; State[R]:\n        ...\n\n    def get_state(self, client: PrefectClient = None):\n        \"\"\"\n        Get the current state of the task run.\n        \"\"\"\n        if self.asynchronous:\n            return cast(Awaitable[State[R]], self._get_state(client=client))\n        else:\n            return cast(State[R], sync(self._get_state, client=client))\n\n    @inject_client\n    async def _get_state(self, client: PrefectClient = None) -&gt; State[R]:\n        assert client is not None  # always injected\n\n        # We must wait for the task run id to be populated\n        await self._wait_for_submission()\n\n        task_run = await client.read_task_run(self.task_run.id)\n\n        if not task_run:\n            raise RuntimeError(\"Future has no associated task run in the server.\")\n\n        # Update the task run reference\n        self.task_run = task_run\n        return task_run.state\n\n    async def _wait_for_submission(self):\n        await run_coroutine_in_loop_from_async(self._loop, self._submitted.wait())\n\n    def __hash__(self) -&gt; int:\n        return hash(self.key)\n\n    def __repr__(self) -&gt; str:\n        return f\"PrefectFuture({self.name!r})\"\n\n    def __bool__(self) -&gt; bool:\n        warnings.warn(\n            (\n                \"A 'PrefectFuture' from a task call was cast to a boolean; \"\n                \"did you mean to check the result of the task instead? \"\n                \"e.g. `if my_task().result(): ...`\"\n            ),\n            stacklevel=2,\n        )\n        return True\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.get_state","title":"<code>get_state</code>","text":"<p>Get the current state of the task run.</p> Source code in <code>prefect/futures.py</code> <pre><code>def get_state(self, client: PrefectClient = None):\n    \"\"\"\n    Get the current state of the task run.\n    \"\"\"\n    if self.asynchronous:\n        return cast(Awaitable[State[R]], self._get_state(client=client))\n    else:\n        return cast(State[R], sync(self._get_state, client=client))\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.result","title":"<code>result</code>","text":"<p>Wait for the run to finish and return the final state.</p> <p>If the timeout is reached before the run reaches a final state, a <code>TimeoutError</code> will be raised.</p> <p>If <code>raise_on_failure</code> is <code>True</code> and the task run failed, the task run's exception will be raised.</p> Source code in <code>prefect/futures.py</code> <pre><code>def result(self, timeout: float = None, raise_on_failure: bool = True):\n    \"\"\"\n    Wait for the run to finish and return the final state.\n\n    If the timeout is reached before the run reaches a final state, a `TimeoutError`\n    will be raised.\n\n    If `raise_on_failure` is `True` and the task run failed, the task run's\n    exception will be raised.\n    \"\"\"\n    result = create_call(\n        self._result, timeout=timeout, raise_on_failure=raise_on_failure\n    )\n    if self.asynchronous:\n        return from_async.call_soon_in_loop_thread(result).aresult()\n    else:\n        return from_sync.call_soon_in_loop_thread(result).result()\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.wait","title":"<code>wait</code>","text":"<p>Wait for the run to finish and return the final state</p> <p>If the timeout is reached before the run reaches a final state, <code>None</code> is returned.</p> Source code in <code>prefect/futures.py</code> <pre><code>def wait(self, timeout=None):\n    \"\"\"\n    Wait for the run to finish and return the final state\n\n    If the timeout is reached before the run reaches a final state,\n    `None` is returned.\n    \"\"\"\n    wait = create_call(self._wait, timeout=timeout)\n    if self.asynchronous:\n        return from_async.call_soon_in_loop_thread(wait).aresult()\n    else:\n        # type checking cannot handle the overloaded timeout passing\n        return from_sync.call_soon_in_loop_thread(wait).result()  # type: ignore\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.call_repr","title":"<code>call_repr</code>","text":"<p>Generate a repr for a function call as \"fn_name(arg_value, kwarg_name=kwarg_value)\"</p> Source code in <code>prefect/futures.py</code> <pre><code>def call_repr(__fn: Callable, *args: Any, **kwargs: Any) -&gt; str:\n    \"\"\"\n    Generate a repr for a function call as \"fn_name(arg_value, kwarg_name=kwarg_value)\"\n    \"\"\"\n\n    name = __fn.__name__\n\n    # TODO: If this computation is concerningly expensive, we can iterate checking the\n    #       length at each arg or avoid calling `repr` on args with large amounts of\n    #       data\n    call_args = \", \".join(\n        [repr(arg) for arg in args]\n        + [f\"{key}={repr(val)}\" for key, val in kwargs.items()]\n    )\n\n    # Enforce a maximum length\n    if len(call_args) &gt; 100:\n        call_args = call_args[:100] + \"...\"\n\n    return f\"{name}({call_args})\"\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.resolve_futures_to_data","title":"<code>resolve_futures_to_data</code>  <code>async</code>","text":"<p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a new collection with the same structure with futures resolved to their results. Resolving futures to their results may wait for execution to complete and require communication with the API.</p> <p>Unsupported object types will be returned without modification.</p> Source code in <code>prefect/futures.py</code> <pre><code>async def resolve_futures_to_data(\n    expr: Union[PrefectFuture[R, Any], Any],\n    raise_on_failure: bool = True,\n) -&gt; Union[R, Any]:\n    \"\"\"\n    Given a Python built-in collection, recursively find `PrefectFutures` and build a\n    new collection with the same structure with futures resolved to their results.\n    Resolving futures to their results may wait for execution to complete and require\n    communication with the API.\n\n    Unsupported object types will be returned without modification.\n    \"\"\"\n    futures: Set[PrefectFuture] = set()\n\n    maybe_expr = visit_collection(\n        expr,\n        visit_fn=partial(_collect_futures, futures),\n        return_data=False,\n        context={},\n    )\n    if maybe_expr is not None:\n        expr = maybe_expr\n\n    # Get results\n    results = await asyncio.gather(\n        *[\n            # We must wait for the future in the thread it was created in\n            from_async.call_soon_in_loop_thread(\n                create_call(future._result, raise_on_failure=raise_on_failure)\n            ).aresult()\n            for future in futures\n        ]\n    )\n\n    results_by_future = dict(zip(futures, results))\n\n    def replace_futures_with_results(expr, context):\n        # Expressions inside quotes should not be modified\n        if isinstance(context.get(\"annotation\"), quote):\n            raise StopVisiting()\n\n        if isinstance(expr, PrefectFuture):\n            return results_by_future[expr]\n        else:\n            return expr\n\n    return visit_collection(\n        expr,\n        visit_fn=replace_futures_with_results,\n        return_data=True,\n        context={},\n    )\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.resolve_futures_to_states","title":"<code>resolve_futures_to_states</code>  <code>async</code>","text":"<p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a new collection with the same structure with futures resolved to their final states. Resolving futures to their final states may wait for execution to complete.</p> <p>Unsupported object types will be returned without modification.</p> Source code in <code>prefect/futures.py</code> <pre><code>async def resolve_futures_to_states(\n    expr: Union[PrefectFuture[R, Any], Any],\n) -&gt; Union[State[R], Any]:\n    \"\"\"\n    Given a Python built-in collection, recursively find `PrefectFutures` and build a\n    new collection with the same structure with futures resolved to their final states.\n    Resolving futures to their final states may wait for execution to complete.\n\n    Unsupported object types will be returned without modification.\n    \"\"\"\n    futures: Set[PrefectFuture] = set()\n\n    visit_collection(\n        expr,\n        visit_fn=partial(_collect_futures, futures),\n        return_data=False,\n        context={},\n    )\n\n    # Get final states for each future\n    states = await asyncio.gather(\n        *[\n            # We must wait for the future in the thread it was created in\n            from_async.call_soon_in_loop_thread(create_call(future._wait)).aresult()\n            for future in futures\n        ]\n    )\n\n    states_by_future = dict(zip(futures, states))\n\n    def replace_futures_with_states(expr, context):\n        # Expressions inside quotes should not be modified\n        if isinstance(context.get(\"annotation\"), quote):\n            raise StopVisiting()\n\n        if isinstance(expr, PrefectFuture):\n            return states_by_future[expr]\n        else:\n            return expr\n\n    return visit_collection(\n        expr,\n        visit_fn=replace_futures_with_states,\n        return_data=True,\n        context={},\n    )\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/infrastructure/","title":"prefect.infrastructure","text":"","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure","title":"<code>prefect.infrastructure</code>","text":"","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer","title":"<code>DockerContainer</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Runs a command in a container.</p> <p>Requires a Docker Engine to be connectable. Docker settings will be retrieved from the environment.</p> <p>Click here to see a tutorial.</p> <p>Attributes:</p> Name Type Description <code>auto_remove</code> <code>bool</code> <p>If set, the container will be removed on completion. Otherwise, the container will remain after exit for inspection.</p> <code>command</code> <code>bool</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>env</code> <code>bool</code> <p>Environment variables to set for the container.</p> <code>image</code> <code>str</code> <p>An optional string specifying the tag of a Docker image to use. Defaults to the Prefect image.</p> <code>image_pull_policy</code> <code>Optional[ImagePullPolicy]</code> <p>Specifies if the image should be pulled. One of 'ALWAYS', 'NEVER', 'IF_NOT_PRESENT'.</p> <code>image_registry</code> <code>Optional[DockerRegistry]</code> <p>A <code>DockerRegistry</code> block containing credentials to use if <code>image</code> is stored in a private image registry.</p> <code>labels</code> <code>Optional[DockerRegistry]</code> <p>An optional dictionary of labels, mapping name to value.</p> <code>name</code> <code>Optional[DockerRegistry]</code> <p>An optional name for the container.</p> <code>network_mode</code> <code>Optional[str]</code> <p>Set the network mode for the created container. Defaults to 'host' if a local API url is detected, otherwise the Docker default of 'bridge' is used. If 'networks' is set, this cannot be set.</p> <code>networks</code> <code>List[str]</code> <p>An optional list of strings specifying Docker networks to connect the container to.</p> <code>stream_output</code> <code>bool</code> <p>If set, stream output from the container to local standard output.</p> <code>volumes</code> <code>List[str]</code> <p>An optional list of volume mount strings in the format of \"local_path:container_path\".</p> <code>memswap_limit</code> <code>Union[int, str]</code> <p>Total memory (memory + swap), -1 to disable swap. Should only be set if <code>mem_limit</code> is also set. If <code>mem_limit</code> is set, this defaults to allowing the container to use as much swap as memory. For example, if <code>mem_limit</code> is 300m and <code>memswap_limit</code> is not set, the container can use 600m in total of memory and swap.</p> <code>mem_limit</code> <code>Union[float, str]</code> <p>Memory limit of the created container. Accepts float values to enforce a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g. If a string is given without a unit, bytes are assumed.</p> <code>privileged</code> <code>bool</code> <p>Give extended privileges to this container.</p>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api","title":"Connecting to a locally hosted Prefect API","text":"<p>If using a local API URL on Linux, we will update the network mode default to 'host' to enable connectivity. If using another OS or an alternative network mode is used, we will replace 'localhost' in the API URL with 'host.docker.internal'. Generally, this will enable connectivity, but the API URL can be provided as an environment variable to override inference in more complex use-cases.</p> <p>Note, if using 'host.docker.internal' in the API URL on Linux, the API must be bound to 0.0.0.0 or the Docker IP address to allow connectivity. On macOS, this is not necessary and the API is connectable while bound to localhost.</p> Source code in <code>prefect/infrastructure/container.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the Docker worker from prefect-docker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass DockerContainer(Infrastructure):\n    \"\"\"\n    Runs a command in a container.\n\n    Requires a Docker Engine to be connectable. Docker settings will be retrieved from\n    the environment.\n\n    Click [here](https://docs.prefect.io/guides/deployment/docker) to see a tutorial.\n\n    Attributes:\n        auto_remove: If set, the container will be removed on completion. Otherwise,\n            the container will remain after exit for inspection.\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        env: Environment variables to set for the container.\n        image: An optional string specifying the tag of a Docker image to use.\n            Defaults to the Prefect image.\n        image_pull_policy: Specifies if the image should be pulled. One of 'ALWAYS',\n            'NEVER', 'IF_NOT_PRESENT'.\n        image_registry: A `DockerRegistry` block containing credentials to use if `image` is stored in a private\n            image registry.\n        labels: An optional dictionary of labels, mapping name to value.\n        name: An optional name for the container.\n        network_mode: Set the network mode for the created container. Defaults to 'host'\n            if a local API url is detected, otherwise the Docker default of 'bridge' is\n            used. If 'networks' is set, this cannot be set.\n        networks: An optional list of strings specifying Docker networks to connect the\n            container to.\n        stream_output: If set, stream output from the container to local standard output.\n        volumes: An optional list of volume mount strings in the format of\n            \"local_path:container_path\".\n        memswap_limit: Total memory (memory + swap), -1 to disable swap. Should only be\n            set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\n            allowing the container to use as much swap as memory. For example, if\n            `mem_limit` is 300m and `memswap_limit` is not set, the container can use\n            600m in total of memory and swap.\n        mem_limit: Memory limit of the created container. Accepts float values to enforce\n            a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g.\n            If a string is given without a unit, bytes are assumed.\n        privileged: Give extended privileges to this container.\n\n    ## Connecting to a locally hosted Prefect API\n\n    If using a local API URL on Linux, we will update the network mode default to 'host'\n    to enable connectivity. If using another OS or an alternative network mode is used,\n    we will replace 'localhost' in the API URL with 'host.docker.internal'. Generally,\n    this will enable connectivity, but the API URL can be provided as an environment\n    variable to override inference in more complex use-cases.\n\n    Note, if using 'host.docker.internal' in the API URL on Linux, the API must be bound\n    to 0.0.0.0 or the Docker IP address to allow connectivity. On macOS, this is not\n    necessary and the API is connectable while bound to localhost.\n    \"\"\"\n\n    type: Literal[\"docker-container\"] = Field(\n        default=\"docker-container\", description=\"The type of infrastructure.\"\n    )\n    image: str = Field(\n        default_factory=get_prefect_image_name,\n        description=\"Tag of a Docker image to use. Defaults to the Prefect image.\",\n    )\n    image_pull_policy: Optional[ImagePullPolicy] = Field(\n        default=None, description=\"Specifies if the image should be pulled.\"\n    )\n    image_registry: Optional[DockerRegistry] = None\n    networks: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"A list of strings specifying Docker networks to connect the container to.\"\n        ),\n    )\n    network_mode: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The network mode for the created container (e.g. host, bridge). If\"\n            \" 'networks' is set, this cannot be set.\"\n        ),\n    )\n    auto_remove: bool = Field(\n        default=False,\n        description=\"If set, the container will be removed on completion.\",\n    )\n    volumes: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"A list of volume mount strings in the format of\"\n            ' \"local_path:container_path\".'\n        ),\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, the output will be streamed from the container to local standard\"\n            \" output.\"\n        ),\n    )\n    memswap_limit: Union[int, str] = Field(\n        default=None,\n        description=(\n            \"Total memory (memory + swap), -1 to disable swap. Should only be \"\n            \"set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\"\n            \"allowing the container to use as much swap as memory. For example, if \"\n            \"`mem_limit` is 300m and `memswap_limit` is not set, the container can use \"\n            \"600m in total of memory and swap.\"\n        ),\n    )\n    mem_limit: Union[float, str] = Field(\n        default=None,\n        description=(\n            \"Memory limit of the created container. Accepts float values to enforce \"\n            \"a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g. \"\n            \"If a string is given without a unit, bytes are assumed.\"\n        ),\n    )\n    privileged: bool = Field(\n        default=False,\n        description=\"Give extended privileges to this container.\",\n    )\n\n    _block_type_name = \"Docker Container\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer\"\n\n    @validator(\"labels\")\n    def convert_labels_to_docker_format(cls, labels: Dict[str, str]):\n        labels = labels or {}\n        new_labels = {}\n        for name, value in labels.items():\n            if \"/\" in name:\n                namespace, key = name.split(\"/\", maxsplit=1)\n                new_namespace = \".\".join(reversed(namespace.split(\".\")))\n                new_labels[f\"{new_namespace}.{key}\"] = value\n            else:\n                new_labels[name] = value\n        return new_labels\n\n    @validator(\"volumes\")\n    def check_volume_format(cls, volumes):\n        for volume in volumes:\n            if \":\" not in volume:\n                raise ValueError(\n                    \"Invalid volume specification. \"\n                    f\"Expected format 'path:container_path', but got {volume!r}\"\n                )\n\n        return volumes\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; Optional[bool]:\n        if not self.command:\n            raise ValueError(\"Docker container cannot be run with empty command.\")\n\n        # The `docker` library uses requests instead of an async http library so it must\n        # be run in a thread to avoid blocking the event loop.\n        container = await run_sync_in_worker_thread(self._create_and_start_container)\n        container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n        # Mark as started and return the infrastructure id\n        if task_status:\n            task_status.started(container_pid)\n\n        # Monitor the container\n        container = await run_sync_in_worker_thread(\n            self._watch_container_safe, container\n        )\n\n        exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n        return DockerContainerResult(\n            status_code=exit_code if exit_code is not None else -1,\n            identifier=container_pid,\n        )\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        docker_client = self._get_client()\n        base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n\n        if docker_client.api.base_url != base_url:\n            raise InfrastructureNotAvailable(\n                \"\".join(\n                    [\n                        (\n                            f\"Unable to stop container {container_id!r}: the current\"\n                            \" Docker API \"\n                        ),\n                        (\n                            f\"URL {docker_client.api.base_url!r} does not match the\"\n                            \" expected \"\n                        ),\n                        f\"API base URL {base_url}.\",\n                    ]\n                )\n            )\n        try:\n            container = docker_client.containers.get(container_id=container_id)\n        except docker.errors.NotFound:\n            raise InfrastructureNotFound(\n                f\"Unable to stop container {container_id!r}: The container was not\"\n                \" found.\"\n            )\n\n        try:\n            container.stop(timeout=grace_seconds)\n        except Exception:\n            raise\n\n    def preview(self):\n        # TODO: build and document a more sophisticated preview\n        docker_client = self._get_client()\n        try:\n            return json.dumps(self._build_container_settings(docker_client))\n        finally:\n            docker_client.close()\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type()\n        )\n        if base_job_template is None:\n            return await super().generate_work_pool_base_job_template()\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key == \"image_registry\":\n                self.logger.warning(\n                    \"Image registry blocks are not supported by Docker\"\n                    \" work pools. Please authenticate to your registry using\"\n                    \" the `docker login` command on your worker instances.\"\n                )\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"image_pull_policy\":\n                new_value = None\n                if value == ImagePullPolicy.ALWAYS:\n                    new_value = \"Always\"\n                elif value == ImagePullPolicy.NEVER:\n                    new_value = \"Never\"\n                elif value == ImagePullPolicy.IF_NOT_PRESENT:\n                    new_value = \"IfNotPresent\"\n\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = new_value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Docker work pools. Skipping.\"\n                )\n\n        return base_job_template\n\n    def get_corresponding_worker_type(self):\n        return \"docker\"\n\n    def _get_infrastructure_pid(self, container_id: str) -&gt; str:\n        \"\"\"Generates a Docker infrastructure_pid string in the form of\n        `&lt;docker_host_base_url&gt;:&lt;container_id&gt;`.\n        \"\"\"\n        docker_client = self._get_client()\n        base_url = docker_client.api.base_url\n        docker_client.close()\n        return f\"{base_url}:{container_id}\"\n\n    def _parse_infrastructure_pid(self, infrastructure_pid: str) -&gt; Tuple[str, str]:\n        \"\"\"Splits a Docker infrastructure_pid into its component parts\"\"\"\n\n        # base_url can contain `:` so we only want the last item of the split\n        base_url, container_id = infrastructure_pid.rsplit(\":\", 1)\n        return base_url, str(container_id)\n\n    def _build_container_settings(\n        self,\n        docker_client: \"DockerClient\",\n    ) -&gt; Dict:\n        network_mode = self._get_network_mode()\n        return dict(\n            image=self.image,\n            network=self.networks[0] if self.networks else None,\n            network_mode=network_mode,\n            command=self.command,\n            environment=self._get_environment_variables(network_mode),\n            auto_remove=self.auto_remove,\n            labels={**CONTAINER_LABELS, **self.labels},\n            extra_hosts=self._get_extra_hosts(docker_client),\n            name=self._get_container_name(),\n            volumes=self.volumes,\n            mem_limit=self.mem_limit,\n            memswap_limit=self.memswap_limit,\n            privileged=self.privileged,\n        )\n\n    def _create_and_start_container(self) -&gt; \"Container\":\n        if self.image_registry:\n            # If an image registry block was supplied, load an authenticated Docker\n            # client from the block. Otherwise, use an unauthenticated client to\n            # pull images from public registries.\n            docker_client = self.image_registry.get_docker_client()\n        else:\n            docker_client = self._get_client()\n        container_settings = self._build_container_settings(docker_client)\n\n        if self._should_pull_image(docker_client):\n            self.logger.info(f\"Pulling image {self.image!r}...\")\n            self._pull_image(docker_client)\n\n        container = self._create_container(docker_client, **container_settings)\n\n        # Add additional networks after the container is created; only one network can\n        # be attached at creation time\n        if len(self.networks) &gt; 1:\n            for network_name in self.networks[1:]:\n                network = docker_client.networks.get(network_name)\n                network.connect(container)\n\n        # Start the container\n        container.start()\n\n        docker_client.close()\n\n        return container\n\n    def _get_image_and_tag(self) -&gt; Tuple[str, Optional[str]]:\n        return parse_image_tag(self.image)\n\n    def _determine_image_pull_policy(self) -&gt; ImagePullPolicy:\n        \"\"\"\n        Determine the appropriate image pull policy.\n\n        1. If they specified an image pull policy, use that.\n\n        2. If they did not specify an image pull policy and gave us\n           the \"latest\" tag, use ImagePullPolicy.always.\n\n        3. If they did not specify an image pull policy and did not\n           specify a tag, use ImagePullPolicy.always.\n\n        4. If they did not specify an image pull policy and gave us\n           a tag other than \"latest\", use ImagePullPolicy.if_not_present.\n\n        This logic matches the behavior of Kubernetes.\n        See:https://kubernetes.io/docs/concepts/containers/images/#imagepullpolicy-defaulting\n        \"\"\"\n        if not self.image_pull_policy:\n            _, tag = self._get_image_and_tag()\n            if tag == \"latest\" or not tag:\n                return ImagePullPolicy.ALWAYS\n            return ImagePullPolicy.IF_NOT_PRESENT\n        return self.image_pull_policy\n\n    def _get_network_mode(self) -&gt; Optional[str]:\n        # User's value takes precedence; this may collide with the incompatible options\n        # mentioned below.\n        if self.network_mode:\n            if sys.platform != \"linux\" and self.network_mode == \"host\":\n                warnings.warn(\n                    f\"{self.network_mode!r} network mode is not supported on platform \"\n                    f\"{sys.platform!r} and may not work as intended.\"\n                )\n            return self.network_mode\n\n        # Network mode is not compatible with networks or ports (we do not support ports\n        # yet though)\n        if self.networks:\n            return None\n\n        # Check for a local API connection\n        api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n        if api_url:\n            try:\n                _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n            except Exception as exc:\n                warnings.warn(\n                    f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                    f\"{exc}\\nThe network mode will not be inferred.\"\n                )\n                return None\n\n            host = netloc.split(\":\")[0]\n\n            # If using a locally hosted API, use a host network on linux\n            if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n                return \"host\"\n\n        # Default to unset\n        return None\n\n    def _should_pull_image(self, docker_client: \"DockerClient\") -&gt; bool:\n        \"\"\"\n        Decide whether we need to pull the Docker image.\n        \"\"\"\n        image_pull_policy = self._determine_image_pull_policy()\n\n        if image_pull_policy is ImagePullPolicy.ALWAYS:\n            return True\n        elif image_pull_policy is ImagePullPolicy.NEVER:\n            return False\n        elif image_pull_policy is ImagePullPolicy.IF_NOT_PRESENT:\n            try:\n                # NOTE: images.get() wants the tag included with the image\n                # name, while images.pull() wants them split.\n                docker_client.images.get(self.image)\n            except docker.errors.ImageNotFound:\n                self.logger.debug(f\"Could not find Docker image locally: {self.image}\")\n                return True\n        return False\n\n    def _pull_image(self, docker_client: \"DockerClient\"):\n        \"\"\"\n        Pull the image we're going to use to create the container.\n        \"\"\"\n        image, tag = self._get_image_and_tag()\n\n        return docker_client.images.pull(image, tag)\n\n    def _create_container(self, docker_client: \"DockerClient\", **kwargs) -&gt; \"Container\":\n        \"\"\"\n        Create a docker container with retries on name conflicts.\n\n        If the container already exists with the given name, an incremented index is\n        added.\n        \"\"\"\n        # Create the container with retries on name conflicts (with an incremented idx)\n        index = 0\n        container = None\n        name = original_name = kwargs.pop(\"name\")\n\n        while not container:\n            from docker.errors import APIError\n\n            try:\n                display_name = repr(name) if name else \"with auto-generated name\"\n                self.logger.info(f\"Creating Docker container {display_name}...\")\n                container = docker_client.containers.create(name=name, **kwargs)\n            except APIError as exc:\n                if \"Conflict\" in str(exc) and \"container name\" in str(exc):\n                    self.logger.info(\n                        f\"Docker container name {display_name} already exists; \"\n                        \"retrying...\"\n                    )\n                    index += 1\n                    name = f\"{original_name}-{index}\"\n                else:\n                    raise\n\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        return container\n\n    def _watch_container_safe(self, container: \"Container\") -&gt; \"Container\":\n        # Monitor the container capturing the latest snapshot while capturing\n        # not found errors\n        docker_client = self._get_client()\n\n        try:\n            for latest_container in self._watch_container(docker_client, container.id):\n                container = latest_container\n        except docker.errors.NotFound:\n            # The container was removed during watching\n            self.logger.warning(\n                f\"Docker container {container.name} was removed before we could wait \"\n                \"for its completion.\"\n            )\n        finally:\n            docker_client.close()\n\n        return container\n\n    def _watch_container(\n        self, docker_client: \"DockerClient\", container_id: str\n    ) -&gt; Generator[None, None, \"Container\"]:\n        container: \"Container\" = docker_client.containers.get(container_id)\n\n        status = container.status\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n        if self.stream_output:\n            try:\n                for log in container.logs(stream=True):\n                    log: bytes\n                    print(log.decode().rstrip())\n            except docker.errors.APIError as exc:\n                if \"marked for removal\" in str(exc):\n                    self.logger.warning(\n                        f\"Docker container {container.name} was marked for removal\"\n                        \" before logs could be retrieved. Output will not be\"\n                        \" streamed. \"\n                    )\n                else:\n                    self.logger.exception(\n                        \"An unexpected Docker API error occurred while streaming\"\n                        f\" output from container {container.name}.\"\n                    )\n\n            container.reload()\n            if container.status != status:\n                self.logger.info(\n                    f\"Docker container {container.name!r} has status\"\n                    f\" {container.status!r}\"\n                )\n            yield container\n\n        container.wait()\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n    def _get_client(self):\n        try:\n            with warnings.catch_warnings():\n                # Silence warnings due to use of deprecated methods within dockerpy\n                # See https://github.com/docker/docker-py/pull/2931\n                warnings.filterwarnings(\n                    \"ignore\",\n                    message=\"distutils Version classes are deprecated.*\",\n                    category=DeprecationWarning,\n                )\n\n                docker_client = docker.from_env()\n\n        except docker.errors.DockerException as exc:\n            raise RuntimeError(\"Could not connect to Docker.\") from exc\n\n        return docker_client\n\n    def _get_container_name(self) -&gt; Optional[str]:\n        \"\"\"\n        Generates a container name to match the configured name, ensuring it is Docker\n        compatible.\n        \"\"\"\n        # Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+` in the end\n        if not self.name:\n            return None\n\n        return (\n            slugify(\n                self.name,\n                lowercase=False,\n                # Docker does not limit length but URL limits apply eventually so\n                # limit the length for safety\n                max_length=250,\n                # Docker allows these characters for container names\n                regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n            ).lstrip(\n                # Docker does not allow leading underscore, dash, or period\n                \"_-.\"\n            )\n            # Docker does not allow 0 character names so cast to null if the name is\n            # empty after slufification\n            or None\n        )\n\n    def _get_extra_hosts(self, docker_client) -&gt; Dict[str, str]:\n        \"\"\"\n        A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n        with the API on Linux machines. Docker Desktop on macOS will automatically\n        already have this mapping.\n        \"\"\"\n        if sys.platform == \"linux\" and (\n            # Do not warn if the user has specified a host manually that does not use\n            # a local address\n            \"PREFECT_API_URL\" not in self.env\n            or re.search(\n                \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n                self.env[\"PREFECT_API_URL\"],\n            )\n        ):\n            user_version = packaging.version.parse(\n                format_outlier_version_name(docker_client.version()[\"Version\"])\n            )\n            required_version = packaging.version.parse(\"20.10.0\")\n\n            if user_version &lt; required_version:\n                warnings.warn(\n                    \"`host.docker.internal` could not be automatically resolved to\"\n                    \" your local ip address. This feature is not supported on Docker\"\n                    f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                    \" encounter issues.\"\n                )\n                return {}\n            else:\n                # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n                # Only supported by Docker v20.10.0+ which is our minimum recommend version\n                return {\"host.docker.internal\": \"host-gateway\"}\n\n    def _get_environment_variables(self, network_mode):\n        # If the API URL has been set by the base environment rather than the by the\n        # user, update the value to ensure connectivity when using a bridge network by\n        # updating local connections to use the docker internal host unless the\n        # network mode is \"host\" where localhost is available already.\n        env = {**self._base_environment(), **self.env}\n\n        if (\n            \"PREFECT_API_URL\" in env\n            and \"PREFECT_API_URL\" not in self.env\n            and network_mode != \"host\"\n        ):\n            env[\"PREFECT_API_URL\"] = (\n                env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", \"host.docker.internal\")\n                .replace(\"127.0.0.1\", \"host.docker.internal\")\n            )\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainerResult","title":"<code>DockerContainerResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about a completed Docker container</p> Source code in <code>prefect/infrastructure/container.py</code> <pre><code>class DockerContainerResult(InfrastructureResult):\n    \"\"\"Contains information about a completed Docker container\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure","title":"<code>Infrastructure</code>","text":"<p>               Bases: <code>Block</code>, <code>ABC</code></p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `BaseWorker` class to create custom infrastructure integrations instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Infrastructure(Block, abc.ABC):\n    _block_schema_capabilities = [\"run-infrastructure\"]\n\n    type: str\n\n    env: Dict[str, Optional[str]] = pydantic.Field(\n        default_factory=dict,\n        title=\"Environment\",\n        description=\"Environment variables to set in the configured infrastructure.\",\n    )\n    labels: Dict[str, str] = pydantic.Field(\n        default_factory=dict,\n        description=\"Labels applied to the infrastructure for metadata purposes.\",\n    )\n    name: Optional[str] = pydantic.Field(\n        default=None,\n        description=\"Name applied to the infrastructure for identification.\",\n    )\n    command: Optional[List[str]] = pydantic.Field(\n        default=None,\n        description=\"The command to run in the infrastructure.\",\n    )\n\n    async def generate_work_pool_base_job_template(self):\n        if self._block_document_id is None:\n            raise BlockNotSavedError(\n                \"Cannot publish as work pool, block has not been saved. Please call\"\n                \" `.save()` on your block before publishing.\"\n            )\n\n        block_schema = self.__class__.schema()\n        return {\n            \"job_configuration\": {\"block\": \"{{ block }}\"},\n            \"variables\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"block\": {\n                        \"title\": \"Block\",\n                        \"description\": (\n                            \"The infrastructure block to use for job creation.\"\n                        ),\n                        \"allOf\": [{\"$ref\": f\"#/definitions/{self.__class__.__name__}\"}],\n                        \"default\": {\n                            \"$ref\": {\"block_document_id\": str(self._block_document_id)}\n                        },\n                    }\n                },\n                \"required\": [\"block\"],\n                \"definitions\": {self.__class__.__name__: block_schema},\n            },\n        }\n\n    def get_corresponding_worker_type(self):\n        return \"block\"\n\n    @sync_compatible\n    async def publish_as_work_pool(self, work_pool_name: Optional[str] = None):\n        \"\"\"\n        Creates a work pool configured to use the given block as the job creator.\n\n        Used to migrate from a agents setup to a worker setup.\n\n        Args:\n            work_pool_name: The name to give to the created work pool. If not provided, the name of the current\n                block will be used.\n        \"\"\"\n\n        base_job_template = await self.generate_work_pool_base_job_template()\n        work_pool_name = work_pool_name or self._block_document_name\n\n        if work_pool_name is None:\n            raise ValueError(\n                \"`work_pool_name` must be provided if the block has not been saved.\"\n            )\n\n        console = Console()\n\n        try:\n            async with prefect.get_client() as client:\n                work_pool = await client.create_work_pool(\n                    work_pool=WorkPoolCreate(\n                        name=work_pool_name,\n                        type=self.get_corresponding_worker_type(),\n                        base_job_template=base_job_template,\n                    )\n                )\n        except ObjectAlreadyExists:\n            console.print(\n                (\n                    f\"Work pool with name {work_pool_name!r} already exists, please use\"\n                    \" a different name.\"\n                ),\n                style=\"red\",\n            )\n            return\n\n        console.print(\n            f\"Work pool {work_pool.name} created!\",\n            style=\"green\",\n        )\n        if PREFECT_UI_URL:\n            console.print(\n                \"You see your new work pool in the UI at\"\n                f\" {PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n            )\n\n        deploy_script = (\n            \"my_flow.deploy(work_pool_name='{work_pool.name}', image='my_image:tag')\"\n        )\n        if not hasattr(self, \"image\"):\n            deploy_script = (\n                \"my_flow.from_source(source='https://github.com/org/repo.git',\"\n                f\" entrypoint='flow.py:my_flow').deploy(work_pool_name='{work_pool.name}')\"\n            )\n        console.print(\n            \"\\nYou can deploy a flow to this work pool by calling\"\n            f\" [blue].deploy[/]:\\n\\n\\t{deploy_script}\\n\"\n        )\n        console.print(\n            \"\\nTo start a worker to execute flow runs in this work pool run:\\n\"\n        )\n        console.print(f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\")\n\n    @abc.abstractmethod\n    async def run(\n        self,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; InfrastructureResult:\n        \"\"\"\n        Run the infrastructure.\n\n        If provided a `task_status`, the status will be reported as started when the\n        infrastructure is successfully created. The status return value will be an\n        identifier for the infrastructure.\n\n        The call will then monitor the created infrastructure, returning a result at\n        the end containing a status code indicating if the infrastructure exited cleanly\n        or encountered an error.\n        \"\"\"\n        # Note: implementations should include `sync_compatible`\n\n    @abc.abstractmethod\n    def preview(self) -&gt; str:\n        \"\"\"\n        View a preview of the infrastructure that would be run.\n        \"\"\"\n\n    @property\n    def logger(self):\n        return get_logger(f\"prefect.infrastructure.{self.type}\")\n\n    @property\n    def is_using_a_runner(self):\n        return self.command is not None and \"prefect flow-run execute\" in shlex.join(\n            self.command\n        )\n\n    @classmethod\n    def _base_environment(cls) -&gt; Dict[str, str]:\n        \"\"\"\n        Environment variables that should be passed to all created infrastructure.\n\n        These values should be overridable with the `env` field.\n        \"\"\"\n        return get_current_settings().to_environment_variables(exclude_unset=True)\n\n    def prepare_for_flow_run(\n        self: Self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"Deployment\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Return an infrastructure block that is prepared to execute a flow run.\n        \"\"\"\n        if deployment is not None:\n            deployment_labels = self._base_deployment_labels(deployment)\n        else:\n            deployment_labels = {}\n\n        if flow is not None:\n            flow_labels = self._base_flow_labels(flow)\n        else:\n            flow_labels = {}\n\n        return self.copy(\n            update={\n                \"env\": {**self._base_flow_run_environment(flow_run), **self.env},\n                \"labels\": {\n                    **self._base_flow_run_labels(flow_run),\n                    **deployment_labels,\n                    **flow_labels,\n                    **self.labels,\n                },\n                \"name\": self.name or flow_run.name,\n                \"command\": self.command or self._base_flow_run_command(),\n            }\n        )\n\n    @staticmethod\n    def _base_flow_run_command() -&gt; List[str]:\n        \"\"\"\n        Generate a command for a flow run job.\n        \"\"\"\n        if experiment_enabled(\"enhanced_cancellation\"):\n            if (\n                PREFECT_EXPERIMENTAL_WARN\n                and PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION\n            ):\n                warnings.warn(\n                    EXPERIMENTAL_WARNING.format(\n                        feature=\"Enhanced flow run cancellation\",\n                        group=\"enhanced_cancellation\",\n                        help=\"\",\n                    ),\n                    ExperimentalFeature,\n                    stacklevel=3,\n                )\n            return [\"prefect\", \"flow-run\", \"execute\"]\n\n        return [\"python\", \"-m\", \"prefect.engine\"]\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": prefect.__version__,\n        }\n\n    @staticmethod\n    def _base_flow_run_environment(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of environment variables for a flow run job.\n        \"\"\"\n        environment = {}\n        environment[\"PREFECT__FLOW_RUN_ID\"] = str(flow_run.id)\n        return environment\n\n    @staticmethod\n    def _base_deployment_labels(deployment: \"Deployment\") -&gt; Dict[str, str]:\n        labels = {\n            \"prefect.io/deployment-name\": deployment.name,\n        }\n        if deployment.updated is not None:\n            labels[\"prefect.io/deployment-updated\"] = deployment.updated.in_timezone(\n                \"utc\"\n            ).to_iso8601_string()\n        return labels\n\n    @staticmethod\n    def _base_flow_labels(flow: \"Flow\") -&gt; Dict[str, str]:\n        return {\n            \"prefect.io/flow-name\": flow.name,\n        }\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Return an infrastructure block that is prepared to execute a flow run.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>def prepare_for_flow_run(\n    self: Self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"Deployment\"] = None,\n    flow: Optional[\"Flow\"] = None,\n) -&gt; Self:\n    \"\"\"\n    Return an infrastructure block that is prepared to execute a flow run.\n    \"\"\"\n    if deployment is not None:\n        deployment_labels = self._base_deployment_labels(deployment)\n    else:\n        deployment_labels = {}\n\n    if flow is not None:\n        flow_labels = self._base_flow_labels(flow)\n    else:\n        flow_labels = {}\n\n    return self.copy(\n        update={\n            \"env\": {**self._base_flow_run_environment(flow_run), **self.env},\n            \"labels\": {\n                **self._base_flow_run_labels(flow_run),\n                **deployment_labels,\n                **flow_labels,\n                **self.labels,\n            },\n            \"name\": self.name or flow_run.name,\n            \"command\": self.command or self._base_flow_run_command(),\n        }\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.preview","title":"<code>preview</code>  <code>abstractmethod</code>","text":"<p>View a preview of the infrastructure that would be run.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@abc.abstractmethod\ndef preview(self) -&gt; str:\n    \"\"\"\n    View a preview of the infrastructure that would be run.\n    \"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.publish_as_work_pool","title":"<code>publish_as_work_pool</code>  <code>async</code>","text":"<p>Creates a work pool configured to use the given block as the job creator.</p> <p>Used to migrate from a agents setup to a worker setup.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>The name to give to the created work pool. If not provided, the name of the current block will be used.</p> <code>None</code> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@sync_compatible\nasync def publish_as_work_pool(self, work_pool_name: Optional[str] = None):\n    \"\"\"\n    Creates a work pool configured to use the given block as the job creator.\n\n    Used to migrate from a agents setup to a worker setup.\n\n    Args:\n        work_pool_name: The name to give to the created work pool. If not provided, the name of the current\n            block will be used.\n    \"\"\"\n\n    base_job_template = await self.generate_work_pool_base_job_template()\n    work_pool_name = work_pool_name or self._block_document_name\n\n    if work_pool_name is None:\n        raise ValueError(\n            \"`work_pool_name` must be provided if the block has not been saved.\"\n        )\n\n    console = Console()\n\n    try:\n        async with prefect.get_client() as client:\n            work_pool = await client.create_work_pool(\n                work_pool=WorkPoolCreate(\n                    name=work_pool_name,\n                    type=self.get_corresponding_worker_type(),\n                    base_job_template=base_job_template,\n                )\n            )\n    except ObjectAlreadyExists:\n        console.print(\n            (\n                f\"Work pool with name {work_pool_name!r} already exists, please use\"\n                \" a different name.\"\n            ),\n            style=\"red\",\n        )\n        return\n\n    console.print(\n        f\"Work pool {work_pool.name} created!\",\n        style=\"green\",\n    )\n    if PREFECT_UI_URL:\n        console.print(\n            \"You see your new work pool in the UI at\"\n            f\" {PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n        )\n\n    deploy_script = (\n        \"my_flow.deploy(work_pool_name='{work_pool.name}', image='my_image:tag')\"\n    )\n    if not hasattr(self, \"image\"):\n        deploy_script = (\n            \"my_flow.from_source(source='https://github.com/org/repo.git',\"\n            f\" entrypoint='flow.py:my_flow').deploy(work_pool_name='{work_pool.name}')\"\n        )\n    console.print(\n        \"\\nYou can deploy a flow to this work pool by calling\"\n        f\" [blue].deploy[/]:\\n\\n\\t{deploy_script}\\n\"\n    )\n    console.print(\n        \"\\nTo start a worker to execute flow runs in this work pool run:\\n\"\n    )\n    console.print(f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\")\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.run","title":"<code>run</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Run the infrastructure.</p> <p>If provided a <code>task_status</code>, the status will be reported as started when the infrastructure is successfully created. The status return value will be an identifier for the infrastructure.</p> <p>The call will then monitor the created infrastructure, returning a result at the end containing a status code indicating if the infrastructure exited cleanly or encountered an error.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@abc.abstractmethod\nasync def run(\n    self,\n    task_status: anyio.abc.TaskStatus = None,\n) -&gt; InfrastructureResult:\n    \"\"\"\n    Run the infrastructure.\n\n    If provided a `task_status`, the status will be reported as started when the\n    infrastructure is successfully created. The status return value will be an\n    identifier for the infrastructure.\n\n    The call will then monitor the created infrastructure, returning a result at\n    the end containing a status code indicating if the infrastructure exited cleanly\n    or encountered an error.\n    \"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect.blocks.kubernetes import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the KubernetesClusterConfig block from prefect-kubernetes instead.\",\n)\nclass KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect.blocks.kubernetes import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig\"\n\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    def parse_yaml_config(cls, value):\n        return validate_yaml(value)\n\n    @classmethod\n    def from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n        kube_config = kubernetes.config.kube_config\n\n        path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        existing_contexts, current_context = kube_config.list_kube_config_contexts(\n            config_file=str(path)\n        )\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n\n        return cls(config=config_dict, context_name=context_name)\n\n    def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return kubernetes.config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        kubernetes.config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    kubernetes.config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@classmethod\ndef from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n    kube_config = kubernetes.config.kube_config\n\n    path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    existing_contexts, current_context = kube_config.list_kube_config_contexts(\n        config_file=str(path)\n    )\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return kubernetes.config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob","title":"<code>KubernetesJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Runs a command as a Kubernetes Job.</p> <p>For a guided tutorial, see How to use Kubernetes with Prefect. For more information, including examples for customizing the resulting manifest, see <code>KubernetesJob</code> infrastructure concepts.</p> <p>Attributes:</p> Name Type Description <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>An optional Kubernetes cluster config to use for this job.</p> <code>command</code> <code>Optional[KubernetesClusterConfig]</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>customizations</code> <code>JsonPatch</code> <p>A list of JSON 6902 patches to apply to the base Job manifest.</p> <code>env</code> <code>JsonPatch</code> <p>Environment variables to set for the container.</p> <code>finished_job_ttl</code> <code>Optional[int]</code> <p>The number of seconds to retain jobs after completion. If set, finished jobs will be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be manually removed.</p> <code>image</code> <code>Optional[str]</code> <p>An optional string specifying the image reference of a container image to use for the job, for example, docker.io/prefecthq/prefect:2-latest. The behavior is as described in https://kubernetes.io/docs/concepts/containers/images/#image-names. Defaults to the Prefect image.</p> <code>image_pull_policy</code> <code>Optional[KubernetesImagePullPolicy]</code> <p>The Kubernetes image pull policy to use for job containers.</p> <code>job</code> <code>KubernetesManifest</code> <p>The base manifest for the Kubernetes Job.</p> <code>job_watch_timeout_seconds</code> <code>Optional[int]</code> <p>Number of seconds to wait for the job to complete before marking it as crashed. Defaults to <code>None</code>, which means no timeout will be enforced.</p> <code>labels</code> <code>Optional[int]</code> <p>An optional dictionary of labels to add to the job.</p> <code>name</code> <code>Optional[int]</code> <p>An optional name for the job.</p> <code>namespace</code> <code>Optional[str]</code> <p>An optional string signifying the Kubernetes namespace to use.</p> <code>pod_watch_timeout_seconds</code> <code>int</code> <p>Number of seconds to watch for pod creation before timing out (default 60).</p> <code>service_account_name</code> <code>Optional[str]</code> <p>An optional string specifying which Kubernetes service account to use.</p> <code>stream_output</code> <code>bool</code> <p>If set, stream output from the job to local standard output.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the Kubernetes worker from prefect-kubernetes instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass KubernetesJob(Infrastructure):\n    \"\"\"\n    Runs a command as a Kubernetes Job.\n\n    For a guided tutorial, see [How to use Kubernetes with Prefect](https://medium.com/the-prefect-blog/how-to-use-kubernetes-with-prefect-419b2e8b8cb2/).\n    For more information, including examples for customizing the resulting manifest, see [`KubernetesJob` infrastructure concepts](https://docs.prefect.io/concepts/infrastructure/#kubernetesjob).\n\n    Attributes:\n        cluster_config: An optional Kubernetes cluster config to use for this job.\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        customizations: A list of JSON 6902 patches to apply to the base Job manifest.\n        env: Environment variables to set for the container.\n        finished_job_ttl: The number of seconds to retain jobs after completion. If set, finished jobs will\n            be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be\n            manually removed.\n        image: An optional string specifying the image reference of a container image\n            to use for the job, for example, docker.io/prefecthq/prefect:2-latest. The\n            behavior is as described in https://kubernetes.io/docs/concepts/containers/images/#image-names.\n            Defaults to the Prefect image.\n        image_pull_policy: The Kubernetes image pull policy to use for job containers.\n        job: The base manifest for the Kubernetes Job.\n        job_watch_timeout_seconds: Number of seconds to wait for the job to complete\n            before marking it as crashed. Defaults to `None`, which means no timeout will be enforced.\n        labels: An optional dictionary of labels to add to the job.\n        name: An optional name for the job.\n        namespace: An optional string signifying the Kubernetes namespace to use.\n        pod_watch_timeout_seconds: Number of seconds to watch for pod creation before timing out (default 60).\n        service_account_name: An optional string specifying which Kubernetes service account to use.\n        stream_output: If set, stream output from the job to local standard output.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob\"\n\n    type: Literal[\"kubernetes-job\"] = Field(\n        default=\"kubernetes-job\", description=\"The type of infrastructure.\"\n    )\n    # shortcuts for the most common user-serviceable settings\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image reference of a container image to use for the job, for example,\"\n            \" `docker.io/prefecthq/prefect:2-latest`.The behavior is as described in\"\n            \" the Kubernetes documentation and uses the latest version of Prefect by\"\n            \" default, unless an image is already present in a provided job manifest.\"\n        ),\n    )\n    namespace: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The Kubernetes namespace to use for this job. Defaults to 'default' \"\n            \"unless a namespace is already present in a provided job manifest.\"\n        ),\n    )\n    service_account_name: Optional[str] = Field(\n        default=None, description=\"The Kubernetes service account to use for this job.\"\n    )\n    image_pull_policy: Optional[KubernetesImagePullPolicy] = Field(\n        default=None,\n        description=\"The Kubernetes image pull policy to use for job containers.\",\n    )\n\n    # connection to a cluster\n    cluster_config: Optional[KubernetesClusterConfig] = Field(\n        default=None, description=\"The Kubernetes cluster config to use for this job.\"\n    )\n\n    # settings allowing full customization of the Job\n    job: KubernetesManifest = Field(\n        default_factory=lambda: KubernetesJob.base_job_manifest(),\n        description=\"The base manifest for the Kubernetes Job.\",\n        title=\"Base Job Manifest\",\n    )\n    customizations: JsonPatch = Field(\n        default_factory=lambda: JsonPatch([]),\n        description=\"A list of JSON 6902 patches to apply to the base Job manifest.\",\n    )\n\n    # controls the behavior of execution\n    job_watch_timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"Number of seconds to wait for the job to complete before marking it as\"\n            \" crashed. Defaults to `None`, which means no timeout will be enforced.\"\n        ),\n    )\n    pod_watch_timeout_seconds: int = Field(\n        default=60,\n        description=\"Number of seconds to watch for pod creation before timing out.\",\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the job to local standard output.\"\n        ),\n    )\n    finished_job_ttl: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to retain jobs after completion. If set, finished\"\n            \" jobs will be cleaned up by Kubernetes after the given delay. If None\"\n            \" (default), jobs will need to be manually removed.\"\n        ),\n    )\n\n    # internal-use only right now\n    _api_dns_name: Optional[str] = None  # Replaces 'localhost' in API URL\n\n    _block_type_name = \"Kubernetes Job\"\n\n    @validator(\"job\")\n    def ensure_job_includes_all_required_components(cls, value: KubernetesManifest):\n        return validate_k8s_job_required_components(cls, value)\n\n    @validator(\"job\")\n    def ensure_job_has_compatible_values(cls, value: KubernetesManifest):\n        return validate_k8s_job_compatible_values(cls, value)\n\n    @validator(\"customizations\", pre=True)\n    def cast_customizations_to_a_json_patch(\n        cls, value: Union[List[Dict], JsonPatch, str]\n    ) -&gt; JsonPatch:\n        return cast_k8s_job_customizations(cls, value)\n\n    @root_validator\n    def default_namespace(cls, values):\n        return set_default_namespace(values)\n\n    @root_validator\n    def default_image(cls, values):\n        return set_default_image(values)\n\n    # Support serialization of the 'JsonPatch' type\n    class Config:\n        arbitrary_types_allowed = True\n        json_encoders = {JsonPatch: lambda p: p.patch}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        d = super().dict(*args, **kwargs)\n        d[\"customizations\"] = self.customizations.patch\n        return d\n\n    @classmethod\n    def base_job_manifest(cls) -&gt; KubernetesManifest:\n        \"\"\"Produces the bare minimum allowed Job manifest\"\"\"\n        return {\n            \"apiVersion\": \"batch/v1\",\n            \"kind\": \"Job\",\n            \"metadata\": {\"labels\": {}},\n            \"spec\": {\n                \"template\": {\n                    \"spec\": {\n                        \"parallelism\": 1,\n                        \"completions\": 1,\n                        \"restartPolicy\": \"Never\",\n                        \"containers\": [\n                            {\n                                \"name\": \"prefect-job\",\n                                \"env\": [],\n                            }\n                        ],\n                    }\n                }\n            },\n        }\n\n    # Note that we're using the yaml package to load both YAML and JSON files below.\n    # This works because YAML is a strict superset of JSON:\n    #\n    #   &gt; The YAML 1.23 specification was published in 2009. Its primary focus was\n    #   &gt; making YAML a strict superset of JSON. It also removed many of the problematic\n    #   &gt; implicit typing recommendations.\n    #\n    #   https://yaml.org/spec/1.2.2/#12-yaml-history\n\n    @classmethod\n    def job_from_file(cls, filename: str) -&gt; KubernetesManifest:\n        \"\"\"Load a Kubernetes Job manifest from a YAML or JSON file.\"\"\"\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            return yaml.load(f, yaml.SafeLoader)\n\n    @classmethod\n    def customize_from_file(cls, filename: str) -&gt; JsonPatch:\n        \"\"\"Load an RFC 6902 JSON patch from a YAML or JSON file.\"\"\"\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            return JsonPatch(yaml.load(f, yaml.SafeLoader))\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; KubernetesJobResult:\n        if not self.command:\n            raise ValueError(\"Kubernetes job cannot be run with empty command.\")\n\n        self._configure_kubernetes_library_client()\n        manifest = self.build_job()\n        job = await run_sync_in_worker_thread(self._create_job, manifest)\n\n        pid = await run_sync_in_worker_thread(self._get_infrastructure_pid, job)\n        # Indicate that the job has started\n        if task_status is not None:\n            task_status.started(pid)\n\n        # Monitor the job until completion\n        status_code = await run_sync_in_worker_thread(\n            self._watch_job, job.metadata.name\n        )\n        return KubernetesJobResult(identifier=pid, status_code=status_code)\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        self._configure_kubernetes_library_client()\n        job_cluster_uid, job_namespace, job_name = self._parse_infrastructure_pid(\n            infrastructure_pid\n        )\n\n        if not job_namespace == self.namespace:\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill job {job_name!r}: The job is running in namespace \"\n                f\"{job_namespace!r} but this block is configured to use \"\n                f\"{self.namespace!r}.\"\n            )\n\n        current_cluster_uid = self._get_cluster_uid()\n        if job_cluster_uid != current_cluster_uid:\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill job {job_name!r}: The job is running on another \"\n                \"cluster.\"\n            )\n\n        with self.get_batch_client() as batch_client:\n            try:\n                batch_client.delete_namespaced_job(\n                    name=job_name,\n                    namespace=job_namespace,\n                    grace_period_seconds=grace_seconds,\n                    # Foreground propagation deletes dependent objects before deleting owner objects.\n                    # This ensures that the pods are cleaned up before the job is marked as deleted.\n                    # See: https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion\n                    propagation_policy=\"Foreground\",\n                )\n            except kubernetes.client.exceptions.ApiException as exc:\n                if exc.status == 404:\n                    raise InfrastructureNotFound(\n                        f\"Unable to kill job {job_name!r}: The job was not found.\"\n                    ) from exc\n                else:\n                    raise\n\n    def preview(self):\n        return yaml.dump(self.build_job())\n\n    def get_corresponding_worker_type(self):\n        return \"kubernetes\"\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type()\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to retrieve default base job template.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"job\",\n                \"customizations\",\n            ]:\n                continue\n            elif key == \"image_pull_policy\":\n                base_job_template[\"variables\"][\"properties\"][\"image_pull_policy\"][\n                    \"default\"\n                ] = value.value\n            elif key == \"cluster_config\":\n                base_job_template[\"variables\"][\"properties\"][\"cluster_config\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.cluster_config._block_document_id)\n                    }\n                }\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Kubernetes work pools.\"\n                    \" Skipping.\"\n                )\n\n        custom_job_manifest = self.dict(exclude_unset=True, exclude_defaults=True).get(\n            \"job\"\n        )\n        if custom_job_manifest:\n            job_manifest = self.build_job()\n        else:\n            job_manifest = copy.deepcopy(\n                base_job_template[\"job_configuration\"][\"job_manifest\"]\n            )\n            job_manifest = self.customizations.apply(job_manifest)\n        base_job_template[\"job_configuration\"][\"job_manifest\"] = job_manifest\n\n        return base_job_template\n\n    def build_job(self) -&gt; KubernetesManifest:\n        \"\"\"Builds the Kubernetes Job Manifest\"\"\"\n        job_manifest = copy.copy(self.job)\n        job_manifest = self._shortcut_customizations().apply(job_manifest)\n        job_manifest = self.customizations.apply(job_manifest)\n        return job_manifest\n\n    @contextmanager\n    def get_batch_client(self) -&gt; Generator[\"BatchV1Api\", None, None]:\n        with kubernetes.client.ApiClient() as client:\n            try:\n                yield kubernetes.client.BatchV1Api(api_client=client)\n            finally:\n                client.rest_client.pool_manager.clear()\n\n    @contextmanager\n    def get_client(self) -&gt; Generator[\"CoreV1Api\", None, None]:\n        with kubernetes.client.ApiClient() as client:\n            try:\n                yield kubernetes.client.CoreV1Api(api_client=client)\n            finally:\n                client.rest_client.pool_manager.clear()\n\n    def _get_infrastructure_pid(self, job: \"V1Job\") -&gt; str:\n        \"\"\"\n        Generates a Kubernetes infrastructure PID.\n\n        The PID is in the format: \"&lt;cluster uid&gt;:&lt;namespace&gt;:&lt;job name&gt;\".\n        \"\"\"\n        cluster_uid = self._get_cluster_uid()\n        pid = f\"{cluster_uid}:{self.namespace}:{job.metadata.name}\"\n        return pid\n\n    def _parse_infrastructure_pid(\n        self, infrastructure_pid: str\n    ) -&gt; Tuple[str, str, str]:\n        \"\"\"\n        Parse a Kubernetes infrastructure PID into its component parts.\n\n        Returns a cluster UID, namespace, and job name.\n        \"\"\"\n        cluster_uid, namespace, job_name = infrastructure_pid.split(\":\", 2)\n        return cluster_uid, namespace, job_name\n\n    def _get_cluster_uid(self) -&gt; str:\n        \"\"\"\n        Gets a unique id for the current cluster being used.\n\n        There is no real unique identifier for a cluster. However, the `kube-system`\n        namespace is immutable and has a persistence UID that we use instead.\n\n        PREFECT_KUBERNETES_CLUSTER_UID can be set in cases where the `kube-system`\n        namespace cannot be read e.g. when a cluster role cannot be created. If set,\n        this variable will be used and we will not attempt to read the `kube-system`\n        namespace.\n\n        See https://github.com/kubernetes/kubernetes/issues/44954\n        \"\"\"\n        # Default to an environment variable\n        env_cluster_uid = os.environ.get(\"PREFECT_KUBERNETES_CLUSTER_UID\")\n        if env_cluster_uid:\n            return env_cluster_uid\n\n        # Read the UID from the cluster namespace\n        with self.get_client() as client:\n            namespace = client.read_namespace(\"kube-system\")\n        cluster_uid = namespace.metadata.uid\n\n        return cluster_uid\n\n    def _configure_kubernetes_library_client(self) -&gt; None:\n        \"\"\"\n        Set the correct kubernetes client configuration.\n\n        WARNING: This action is not threadsafe and may override the configuration\n                  specified by another `KubernetesJob` instance.\n        \"\"\"\n        # TODO: Investigate returning a configured client so calls on other threads\n        #       will not invalidate the config needed here\n\n        # if a k8s cluster block is provided to the flow runner, use that\n        if self.cluster_config:\n            self.cluster_config.configure_client()\n        else:\n            # If no block specified, try to load Kubernetes configuration within a cluster. If that doesn't\n            # work, try to load the configuration from the local environment, allowing\n            # any further ConfigExceptions to bubble up.\n            try:\n                kubernetes.config.load_incluster_config()\n            except kubernetes.config.ConfigException:\n                kubernetes.config.load_kube_config()\n\n    def _shortcut_customizations(self) -&gt; JsonPatch:\n        \"\"\"Produces the JSON 6902 patch for the most commonly used customizations, like\n        image and namespace, which we offer as top-level parameters (with sensible\n        default values)\"\"\"\n        shortcuts = []\n\n        if self.namespace:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/namespace\",\n                    \"value\": self.namespace,\n                }\n            )\n\n        if self.image:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/image\",\n                    \"value\": self.image,\n                }\n            )\n\n        shortcuts += [\n            {\n                \"op\": \"add\",\n                \"path\": (\n                    f\"/metadata/labels/{self._slugify_label_key(key).replace('/', '~1', 1)}\"\n                ),\n                \"value\": self._slugify_label_value(value),\n            }\n            for key, value in self.labels.items()\n        ]\n\n        shortcuts += [\n            {\n                \"op\": \"add\",\n                \"path\": \"/spec/template/spec/containers/0/env/-\",\n                \"value\": {\"name\": key, \"value\": value},\n            }\n            for key, value in self._get_environment_variables().items()\n        ]\n\n        if self.image_pull_policy:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/imagePullPolicy\",\n                    \"value\": self.image_pull_policy.value,\n                }\n            )\n\n        if self.service_account_name:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/serviceAccountName\",\n                    \"value\": self.service_account_name,\n                }\n            )\n\n        if self.finished_job_ttl is not None:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/ttlSecondsAfterFinished\",\n                    \"value\": self.finished_job_ttl,\n                }\n            )\n\n        if self.command:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/args\",\n                    \"value\": self.command,\n                }\n            )\n\n        if self.name:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/generateName\",\n                    \"value\": self._slugify_name(self.name) + \"-\",\n                }\n            )\n        else:\n            # Generate name is required\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/generateName\",\n                    \"value\": (\n                        \"prefect-job-\"\n                        # We generate a name using a hash of the primary job settings\n                        + stable_hash(\n                            *self.command if self.command else \"\",\n                            *self.env.keys(),\n                            *[v for v in self.env.values() if v is not None],\n                        )\n                        + \"-\"\n                    ),\n                }\n            )\n\n        return JsonPatch(shortcuts)\n\n    def _get_job(self, job_id: str) -&gt; Optional[\"V1Job\"]:\n        with self.get_batch_client() as batch_client:\n            try:\n                job = batch_client.read_namespaced_job(job_id, self.namespace)\n            except kubernetes.client.exceptions.ApiException:\n                self.logger.error(f\"Job {job_id!r} was removed.\", exc_info=True)\n                return None\n            return job\n\n    def _get_job_pod(self, job_name: str) -&gt; \"V1Pod\":\n        \"\"\"Get the first running pod for a job.\"\"\"\n\n        # Wait until we find a running pod for the job\n        # if `pod_watch_timeout_seconds` is None, no timeout will be enforced\n        watch = kubernetes.watch.Watch()\n        self.logger.debug(f\"Job {job_name!r}: Starting watch for pod start...\")\n        last_phase = None\n        with self.get_client() as client:\n            for event in watch.stream(\n                func=client.list_namespaced_pod,\n                namespace=self.namespace,\n                label_selector=f\"job-name={job_name}\",\n                timeout_seconds=self.pod_watch_timeout_seconds,\n            ):\n                phase = event[\"object\"].status.phase\n                if phase != last_phase:\n                    self.logger.info(f\"Job {job_name!r}: Pod has status {phase!r}.\")\n\n                if phase != \"Pending\":\n                    watch.stop()\n                    return event[\"object\"]\n\n                last_phase = phase\n\n        self.logger.error(f\"Job {job_name!r}: Pod never started.\")\n\n    def _watch_job(self, job_name: str) -&gt; int:\n        \"\"\"\n        Watch a job.\n\n        Return the final status code of the first container.\n        \"\"\"\n        self.logger.debug(f\"Job {job_name!r}: Monitoring job...\")\n\n        job = self._get_job(job_name)\n        if not job:\n            return -1\n\n        pod = self._get_job_pod(job_name)\n        if not pod:\n            return -1\n\n        # Calculate the deadline before streaming output\n        deadline = (\n            (time.monotonic() + self.job_watch_timeout_seconds)\n            if self.job_watch_timeout_seconds is not None\n            else None\n        )\n\n        if self.stream_output:\n            with self.get_client() as client:\n                logs = client.read_namespaced_pod_log(\n                    pod.metadata.name,\n                    self.namespace,\n                    follow=True,\n                    _preload_content=False,\n                    container=\"prefect-job\",\n                )\n                try:\n                    for log in logs.stream():\n                        print(log.decode().rstrip())\n\n                        # Check if we have passed the deadline and should stop streaming\n                        # logs\n                        remaining_time = (\n                            deadline - time.monotonic() if deadline else None\n                        )\n                        if deadline and remaining_time &lt;= 0:\n                            break\n\n                except Exception:\n                    self.logger.warning(\n                        (\n                            \"Error occurred while streaming logs - \"\n                            \"Job will continue to run but logs will \"\n                            \"no longer be streamed to stdout.\"\n                        ),\n                        exc_info=True,\n                    )\n\n        with self.get_batch_client() as batch_client:\n            # Check if the job is completed before beginning a watch\n            job = batch_client.read_namespaced_job(\n                name=job_name, namespace=self.namespace\n            )\n            completed = job.status.completion_time is not None\n\n            while not completed:\n                remaining_time = (\n                    math.ceil(deadline - time.monotonic()) if deadline else None\n                )\n                if deadline and remaining_time &lt;= 0:\n                    self.logger.error(\n                        f\"Job {job_name!r}: Job did not complete within \"\n                        f\"timeout of {self.job_watch_timeout_seconds}s.\"\n                    )\n                    return -1\n\n                watch = kubernetes.watch.Watch()\n                # The kubernetes library will disable retries if the timeout kwarg is\n                # present regardless of the value so we do not pass it unless given\n                # https://github.com/kubernetes-client/python/blob/84f5fea2a3e4b161917aa597bf5e5a1d95e24f5a/kubernetes/base/watch/watch.py#LL160\n                timeout_seconds = (\n                    {\"timeout_seconds\": remaining_time} if deadline else {}\n                )\n\n                for event in watch.stream(\n                    func=batch_client.list_namespaced_job,\n                    field_selector=f\"metadata.name={job_name}\",\n                    namespace=self.namespace,\n                    **timeout_seconds,\n                ):\n                    if event[\"type\"] == \"DELETED\":\n                        self.logger.error(f\"Job {job_name!r}: Job has been deleted.\")\n                        completed = True\n                    elif event[\"object\"].status.completion_time:\n                        if not event[\"object\"].status.succeeded:\n                            # Job failed, exit while loop and return pod exit code\n                            self.logger.error(f\"Job {job_name!r}: Job failed.\")\n                        completed = True\n                    # Check if the job has reached its backoff limit\n                    # and stop watching if it has\n                    elif (\n                        event[\"object\"].spec.backoff_limit is not None\n                        and event[\"object\"].status.failed is not None\n                        and event[\"object\"].status.failed\n                        &gt; event[\"object\"].spec.backoff_limit\n                    ):\n                        self.logger.error(\n                            f\"Job {job_name!r}: Job reached backoff limit.\"\n                        )\n                        completed = True\n                    # If the job has no backoff limit, check if it has failed\n                    # and stop watching if it has\n                    elif (\n                        not event[\"object\"].spec.backoff_limit\n                        and event[\"object\"].status.failed\n                    ):\n                        completed = True\n\n                    if completed:\n                        watch.stop()\n                        break\n\n        with self.get_client() as core_client:\n            # Get all pods for the job\n            pods = core_client.list_namespaced_pod(\n                namespace=self.namespace, label_selector=f\"job-name={job_name}\"\n            )\n            # Get the status for only the most recently used pod\n            pods.items.sort(\n                key=lambda pod: pod.metadata.creation_timestamp, reverse=True\n            )\n            most_recent_pod = pods.items[0] if pods.items else None\n            first_container_status = (\n                most_recent_pod.status.container_statuses[0]\n                if most_recent_pod\n                else None\n            )\n            if not first_container_status:\n                self.logger.error(f\"Job {job_name!r}: No pods found for job.\")\n                return -1\n\n            # In some cases, such as spot instance evictions, the pod will be forcibly\n            # terminated and not report a status correctly.\n            elif (\n                first_container_status.state is None\n                or first_container_status.state.terminated is None\n                or first_container_status.state.terminated.exit_code is None\n            ):\n                self.logger.error(\n                    f\"Could not determine exit code for {job_name!r}.\"\n                    \"Exit code will be reported as -1.\"\n                    \"First container status info did not report an exit code.\"\n                    f\"First container info: {first_container_status}.\"\n                )\n                return -1\n\n        return first_container_status.state.terminated.exit_code\n\n    def _create_job(self, job_manifest: KubernetesManifest) -&gt; \"V1Job\":\n        \"\"\"\n        Given a Kubernetes Job Manifest, create the Job on the configured Kubernetes\n        cluster and return its name.\n        \"\"\"\n        with self.get_batch_client() as batch_client:\n            job = batch_client.create_namespaced_job(self.namespace, job_manifest)\n        return job\n\n    def _slugify_name(self, name: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a name.\n\n        Keeps only alphanumeric characters and dashes, and caps the length\n        of the slug at 45 chars.\n\n        The 45 character length allows room for the k8s utility\n        \"generateName\" to generate a unique name from the slug while\n        keeping the total length of a name below 63 characters, which is\n        the limit for e.g. label names that follow RFC 1123 (hostnames) and\n        RFC 1035 (domain names).\n\n        Args:\n            name: The name of the job\n\n        Returns:\n            the slugified job name\n        \"\"\"\n        slug = slugify(\n            name,\n            max_length=45,  # Leave enough space for generateName\n            regex_pattern=r\"[^a-zA-Z0-9-]+\",\n        )\n\n        # TODO: Handle the case that the name is an empty string after being\n        # slugified.\n\n        return slug\n\n    def _slugify_label_key(self, key: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a label key.\n\n        Keys are composed of an optional prefix and name, separated by a slash (/).\n\n        Keeps only alphanumeric characters, dashes, underscores, and periods.\n        Limits the length of the label prefix to 253 characters.\n        Limits the length of the label name to 63 characters.\n\n        See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set\n\n        Args:\n            key: The label key\n\n        Returns:\n            The slugified label key\n        \"\"\"\n        if \"/\" in key:\n            prefix, name = key.split(\"/\", maxsplit=1)\n        else:\n            prefix = None\n            name = key\n\n        name_slug = (\n            slugify(name, max_length=63, regex_pattern=r\"[^a-zA-Z0-9-_.]+\").strip(\n                \"_-.\"  # Must start or end with alphanumeric characters\n            )\n            or name\n        )\n        # Fallback to the original if we end up with an empty slug, this will allow\n        # Kubernetes to throw the validation error\n\n        if prefix:\n            prefix_slug = (\n                slugify(\n                    prefix,\n                    max_length=253,\n                    regex_pattern=r\"[^a-zA-Z0-9-\\.]+\",\n                ).strip(\"_-.\")  # Must start or end with alphanumeric characters\n                or prefix\n            )\n\n            return f\"{prefix_slug}/{name_slug}\"\n\n        return name_slug\n\n    def _slugify_label_value(self, value: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a label value.\n\n        Keeps only alphanumeric characters, dashes, underscores, and periods.\n        Limits the total length of label text to below 63 characters.\n\n        See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set\n\n        Args:\n            value: The text for the label\n\n        Returns:\n            The slugified value\n        \"\"\"\n        slug = (\n            slugify(value, max_length=63, regex_pattern=r\"[^a-zA-Z0-9-_\\.]+\").strip(\n                \"_-.\"  # Must start or end with alphanumeric characters\n            )\n            or value\n        )\n        # Fallback to the original if we end up with an empty slug, this will allow\n        # Kubernetes to throw the validation error\n\n        return slug\n\n    def _get_environment_variables(self):\n        # If the API URL has been set by the base environment rather than the by the\n        # user, update the value to ensure connectivity when using a bridge network by\n        # updating local connections to use the internal host\n        env = {**self._base_environment(), **self.env}\n\n        if (\n            \"PREFECT_API_URL\" in env\n            and \"PREFECT_API_URL\" not in self.env\n            and self._api_dns_name\n        ):\n            env[\"PREFECT_API_URL\"] = (\n                env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", self._api_dns_name)\n                .replace(\"127.0.0.1\", self._api_dns_name)\n            )\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.base_job_manifest","title":"<code>base_job_manifest</code>  <code>classmethod</code>","text":"<p>Produces the bare minimum allowed Job manifest</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef base_job_manifest(cls) -&gt; KubernetesManifest:\n    \"\"\"Produces the bare minimum allowed Job manifest\"\"\"\n    return {\n        \"apiVersion\": \"batch/v1\",\n        \"kind\": \"Job\",\n        \"metadata\": {\"labels\": {}},\n        \"spec\": {\n            \"template\": {\n                \"spec\": {\n                    \"parallelism\": 1,\n                    \"completions\": 1,\n                    \"restartPolicy\": \"Never\",\n                    \"containers\": [\n                        {\n                            \"name\": \"prefect-job\",\n                            \"env\": [],\n                        }\n                    ],\n                }\n            }\n        },\n    }\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.build_job","title":"<code>build_job</code>","text":"<p>Builds the Kubernetes Job Manifest</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>def build_job(self) -&gt; KubernetesManifest:\n    \"\"\"Builds the Kubernetes Job Manifest\"\"\"\n    job_manifest = copy.copy(self.job)\n    job_manifest = self._shortcut_customizations().apply(job_manifest)\n    job_manifest = self.customizations.apply(job_manifest)\n    return job_manifest\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.customize_from_file","title":"<code>customize_from_file</code>  <code>classmethod</code>","text":"<p>Load an RFC 6902 JSON patch from a YAML or JSON file.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef customize_from_file(cls, filename: str) -&gt; JsonPatch:\n    \"\"\"Load an RFC 6902 JSON patch from a YAML or JSON file.\"\"\"\n    with open(filename, \"r\", encoding=\"utf-8\") as f:\n        return JsonPatch(yaml.load(f, yaml.SafeLoader))\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.job_from_file","title":"<code>job_from_file</code>  <code>classmethod</code>","text":"<p>Load a Kubernetes Job manifest from a YAML or JSON file.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef job_from_file(cls, filename: str) -&gt; KubernetesManifest:\n    \"\"\"Load a Kubernetes Job manifest from a YAML or JSON file.\"\"\"\n    with open(filename, \"r\", encoding=\"utf-8\") as f:\n        return yaml.load(f, yaml.SafeLoader)\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJobResult","title":"<code>KubernetesJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about the final state of a completed Kubernetes Job</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>class KubernetesJobResult(InfrastructureResult):\n    \"\"\"Contains information about the final state of a completed Kubernetes Job\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Process","title":"<code>Process</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Run a command in a new process.</p> <p>Current environment variables and Prefect settings will be included in the created process. Configured environment variables will override any current environment variables.</p> <p>Attributes:</p> Name Type Description <code>command</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>env</code> <p>Environment variables to set for the new process.</p> <code>labels</code> <p>Labels for the process. Labels are for metadata purposes only and cannot be attached to the process itself.</p> <code>name</code> <p>A name for the process. For display purposes only.</p> <code>stream_output</code> <code>bool</code> <p>Whether to stream output to local stdout.</p> <code>working_dir</code> <code>Union[str, Path, None]</code> <p>Working directory where the process should be opened. If not set, a tmp directory will be used.</p> Source code in <code>prefect/infrastructure/process.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the process worker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Process(Infrastructure):\n    \"\"\"\n    Run a command in a new process.\n\n    Current environment variables and Prefect settings will be included in the created\n    process. Configured environment variables will override any current environment\n    variables.\n\n    Attributes:\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        env: Environment variables to set for the new process.\n        labels: Labels for the process. Labels are for metadata purposes only and\n            cannot be attached to the process itself.\n        name: A name for the process. For display purposes only.\n        stream_output: Whether to stream output to local stdout.\n        working_dir: Working directory where the process should be opened. If not set,\n            a tmp directory will be used.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/356e6766a91baf20e1d08bbe16e8b5aaef4d8643-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/infrastructure/#process\"\n\n    type: Literal[\"process\"] = Field(\n        default=\"process\", description=\"The type of infrastructure.\"\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the process to local standard output.\"\n        ),\n    )\n    working_dir: Union[str, Path, None] = Field(\n        default=None,\n        description=(\n            \"If set, the process will open within the specified path as the working\"\n            \" directory. Otherwise, a temporary directory will be created.\"\n        ),\n    )  # Underlying accepted types are str, bytes, PathLike[str], None\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; \"ProcessResult\":\n        if not self.command:\n            raise ValueError(\"Process cannot be run with empty command.\")\n\n        display_name = f\" {self.name!r}\" if self.name else \"\"\n\n        # Open a subprocess to execute the flow run\n        self.logger.info(f\"Opening process{display_name}...\")\n        working_dir_ctx = (\n            tempfile.TemporaryDirectory(suffix=\"prefect\")\n            if not self.working_dir\n            else contextlib.nullcontext(self.working_dir)\n        )\n        with working_dir_ctx as working_dir:\n            self.logger.debug(\n                f\"Process{display_name} running command: {' '.join(self.command)} in\"\n                f\" {working_dir}\"\n            )\n\n            # We must add creationflags to a dict so it is only passed as a function\n            # parameter on Windows, because the presence of creationflags causes\n            # errors on Unix even if set to None\n            kwargs: Dict[str, object] = {}\n            if sys.platform == \"win32\":\n                kwargs[\"creationflags\"] = subprocess.CREATE_NEW_PROCESS_GROUP\n\n            process = await run_process(\n                self.command,\n                stream_output=self.stream_output,\n                task_status=task_status,\n                task_status_handler=_infrastructure_pid_from_process,\n                env=self._get_environment_variables(),\n                cwd=working_dir,\n                **kwargs,\n            )\n\n        # Use the pid for display if no name was given\n        display_name = display_name or f\" {process.pid}\"\n\n        if process.returncode:\n            help_message = None\n            if process.returncode == -9:\n                help_message = (\n                    \"This indicates that the process exited due to a SIGKILL signal. \"\n                    \"Typically, this is either caused by manual cancellation or \"\n                    \"high memory usage causing the operating system to \"\n                    \"terminate the process.\"\n                )\n            if process.returncode == -15:\n                help_message = (\n                    \"This indicates that the process exited due to a SIGTERM signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n            elif process.returncode == 247:\n                help_message = (\n                    \"This indicates that the process was terminated due to high \"\n                    \"memory usage.\"\n                )\n            elif (\n                sys.platform == \"win32\" and process.returncode == STATUS_CONTROL_C_EXIT\n            ):\n                help_message = (\n                    \"Process was terminated due to a Ctrl+C or Ctrl+Break signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n\n            self.logger.error(\n                f\"Process{display_name} exited with status code: {process.returncode}\"\n                + (f\"; {help_message}\" if help_message else \"\")\n            )\n        else:\n            self.logger.info(f\"Process{display_name} exited cleanly.\")\n\n        return ProcessResult(\n            status_code=process.returncode, identifier=str(process.pid)\n        )\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        hostname, pid = _parse_infrastructure_pid(infrastructure_pid)\n\n        if hostname != socket.gethostname():\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill process {pid!r}: The process is running on a different\"\n                f\" host {hostname!r}.\"\n            )\n\n        # In a non-windows environment first send a SIGTERM, then, after\n        # `grace_seconds` seconds have passed subsequent send SIGKILL. In\n        # Windows we use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        if sys.platform == \"win32\":\n            try:\n                os.kill(pid, signal.CTRL_BREAK_EVENT)\n            except (ProcessLookupError, WindowsError):\n                raise InfrastructureNotFound(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n        else:\n            try:\n                os.kill(pid, signal.SIGTERM)\n            except ProcessLookupError:\n                raise InfrastructureNotFound(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n\n            # Throttle how often we check if the process is still alive to keep\n            # from making too many system calls in a short period of time.\n            check_interval = max(grace_seconds / 10, 1)\n\n            with anyio.move_on_after(grace_seconds):\n                while True:\n                    await anyio.sleep(check_interval)\n\n                    # Detect if the process is still alive. If not do an early\n                    # return as the process respected the SIGTERM from above.\n                    try:\n                        os.kill(pid, 0)\n                    except ProcessLookupError:\n                        return\n\n            try:\n                os.kill(pid, signal.SIGKILL)\n            except OSError:\n                # We shouldn't ever end up here, but it's possible that the\n                # process ended right after the check above.\n                return\n\n    def preview(self):\n        environment = self._get_environment_variables(include_os_environ=False)\n        return \" \\\\\\n\".join(\n            [f\"{key}={value}\" for key, value in environment.items()]\n            + [\" \".join(self.command)]\n        )\n\n    def _get_environment_variables(self, include_os_environ: bool = True):\n        os_environ = os.environ if include_os_environ else {}\n        # The base environment must override the current environment or\n        # the Prefect settings context may not be respected\n        env = {**os_environ, **self._base_environment(), **self.env}\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n\n    def _base_flow_run_command(self):\n        return [get_sys_executable(), \"-m\", \"prefect.engine\"]\n\n    def get_corresponding_worker_type(self):\n        return \"process\"\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Process worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Process work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.ProcessResult","title":"<code>ProcessResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect/infrastructure/process.py</code> <pre><code>class ProcessResult(InfrastructureResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/manifests/","title":"prefect.manifests","text":"","tags":["Python API","deployments"]},{"location":"api-ref/prefect/manifests/#prefect.manifests","title":"<code>prefect.manifests</code>","text":"<p>Manifests are portable descriptions of one or more workflows within a given directory structure.</p> <p>They are the foundational building blocks for defining Flow Deployments.</p>","tags":["Python API","deployments"]},{"location":"api-ref/prefect/manifests/#prefect.manifests.Manifest","title":"<code>Manifest</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A JSON representation of a flow.</p> Source code in <code>prefect/manifests.py</code> <pre><code>class Manifest(BaseModel):\n    \"\"\"A JSON representation of a flow.\"\"\"\n\n    flow_name: str = Field(default=..., description=\"The name of the flow.\")\n    import_path: str = Field(\n        default=..., description=\"The relative import path for the flow.\"\n    )\n    parameter_openapi_schema: ParameterSchema = Field(\n        default=..., description=\"The OpenAPI schema of the flow's parameters.\"\n    )\n</code></pre>","tags":["Python API","deployments"]},{"location":"api-ref/prefect/serializers/","title":"prefect.serializers","text":"","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers","title":"<code>prefect.serializers</code>","text":"<p>Serializer implementations for converting objects to bytes and bytes to objects.</p> <p>All serializers are based on the <code>Serializer</code> class and include a <code>type</code> string that allows them to be referenced without referencing the actual class. For example, you can get often specify the <code>JSONSerializer</code> with the string \"json\". Some serializers support additional settings for configuration of serialization. These are stored on the instance so the same settings can be used to load saved objects.</p> <p>All serializers must implement <code>dumps</code> and <code>loads</code> which convert objects to bytes and bytes to an object respectively.</p>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedJSONSerializer","title":"<code>CompressedJSONSerializer</code>","text":"<p>               Bases: <code>CompressedSerializer</code></p> <p>A compressed serializer preconfigured to use the json serializer.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedJSONSerializer(CompressedSerializer):\n    \"\"\"\n    A compressed serializer preconfigured to use the json serializer.\n    \"\"\"\n\n    type: Literal[\"compressed/json\"] = \"compressed/json\"\n\n    serializer: Serializer = Field(default_factory=JSONSerializer)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedPickleSerializer","title":"<code>CompressedPickleSerializer</code>","text":"<p>               Bases: <code>CompressedSerializer</code></p> <p>A compressed serializer preconfigured to use the pickle serializer.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedPickleSerializer(CompressedSerializer):\n    \"\"\"\n    A compressed serializer preconfigured to use the pickle serializer.\n    \"\"\"\n\n    type: Literal[\"compressed/pickle\"] = \"compressed/pickle\"\n\n    serializer: Serializer = Field(default_factory=PickleSerializer)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedSerializer","title":"<code>CompressedSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Wraps another serializer, compressing its output. Uses <code>lzma</code> by default. See <code>compressionlib</code> for using alternative libraries.</p> <p>Attributes:</p> Name Type Description <code>serializer</code> <code>Serializer</code> <p>The serializer to use before compression.</p> <code>compressionlib</code> <code>str</code> <p>The import path of a compression module to use. Must have methods <code>compress(bytes) -&gt; bytes</code> and <code>decompress(bytes) -&gt; bytes</code>.</p> <code>level</code> <code>str</code> <p>If not null, the level of compression to pass to <code>compress</code>.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedSerializer(Serializer):\n    \"\"\"\n    Wraps another serializer, compressing its output.\n    Uses `lzma` by default. See `compressionlib` for using alternative libraries.\n\n    Attributes:\n        serializer: The serializer to use before compression.\n        compressionlib: The import path of a compression module to use.\n            Must have methods `compress(bytes) -&gt; bytes` and `decompress(bytes) -&gt; bytes`.\n        level: If not null, the level of compression to pass to `compress`.\n    \"\"\"\n\n    type: Literal[\"compressed\"] = \"compressed\"\n\n    serializer: Serializer\n    compressionlib: str = \"lzma\"\n\n    @validator(\"serializer\", pre=True)\n    def validate_serializer(cls, value):\n        return cast_type_names_to_serializers(value)\n\n    @validator(\"compressionlib\")\n    def check_compressionlib(cls, value):\n        return validate_compressionlib(value)\n\n    def dumps(self, obj: Any) -&gt; bytes:\n        blob = self.serializer.dumps(obj)\n        compressor = from_qualified_name(self.compressionlib)\n        return base64.encodebytes(compressor.compress(blob))\n\n    def loads(self, blob: bytes) -&gt; Any:\n        compressor = from_qualified_name(self.compressionlib)\n        uncompressed = compressor.decompress(base64.decodebytes(blob))\n        return self.serializer.loads(uncompressed)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.JSONSerializer","title":"<code>JSONSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Serializes data to JSON.</p> <p>Input types must be compatible with the stdlib json library.</p> <p>Wraps the <code>json</code> library to serialize to UTF-8 bytes instead of string types.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class JSONSerializer(Serializer):\n    \"\"\"\n    Serializes data to JSON.\n\n    Input types must be compatible with the stdlib json library.\n\n    Wraps the `json` library to serialize to UTF-8 bytes instead of string types.\n    \"\"\"\n\n    type: Literal[\"json\"] = \"json\"\n\n    jsonlib: str = \"json\"\n    object_encoder: Optional[str] = Field(\n        default=\"prefect.serializers.prefect_json_object_encoder\",\n        description=(\n            \"An optional callable to use when serializing objects that are not \"\n            \"supported by the JSON encoder. By default, this is set to a callable that \"\n            \"adds support for all types supported by \"\n        ),\n    )\n    object_decoder: Optional[str] = Field(\n        default=\"prefect.serializers.prefect_json_object_decoder\",\n        description=(\n            \"An optional callable to use when deserializing objects. This callable \"\n            \"is passed each dictionary encountered during JSON deserialization. \"\n            \"By default, this is set to a callable that deserializes content created \"\n            \"by our default `object_encoder`.\"\n        ),\n    )\n    dumps_kwargs: Dict[str, Any] = Field(default_factory=dict)\n    loads_kwargs: Dict[str, Any] = Field(default_factory=dict)\n\n    @validator(\"dumps_kwargs\")\n    def dumps_kwargs_cannot_contain_default(cls, value):\n        return validate_dump_kwargs(value)\n\n    @validator(\"loads_kwargs\")\n    def loads_kwargs_cannot_contain_object_hook(cls, value):\n        return validate_load_kwargs(value)\n\n    def dumps(self, data: Any) -&gt; bytes:\n        json = from_qualified_name(self.jsonlib)\n        kwargs = self.dumps_kwargs.copy()\n        if self.object_encoder:\n            kwargs[\"default\"] = from_qualified_name(self.object_encoder)\n        result = json.dumps(data, **kwargs)\n        if isinstance(result, str):\n            # The standard library returns str but others may return bytes directly\n            result = result.encode()\n        return result\n\n    def loads(self, blob: bytes) -&gt; Any:\n        json = from_qualified_name(self.jsonlib)\n        kwargs = self.loads_kwargs.copy()\n        if self.object_decoder:\n            kwargs[\"object_hook\"] = from_qualified_name(self.object_decoder)\n        return json.loads(blob.decode(), **kwargs)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.PickleSerializer","title":"<code>PickleSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Serializes objects using the pickle protocol.</p> <ul> <li>Uses <code>cloudpickle</code> by default. See <code>picklelib</code> for using alternative libraries.</li> <li>Stores the version of the pickle library to check for compatibility during     deserialization.</li> <li>Wraps pickles in base64 for safe transmission.</li> </ul> Source code in <code>prefect/serializers.py</code> <pre><code>class PickleSerializer(Serializer):\n    \"\"\"\n    Serializes objects using the pickle protocol.\n\n    - Uses `cloudpickle` by default. See `picklelib` for using alternative libraries.\n    - Stores the version of the pickle library to check for compatibility during\n        deserialization.\n    - Wraps pickles in base64 for safe transmission.\n    \"\"\"\n\n    type: Literal[\"pickle\"] = \"pickle\"\n\n    picklelib: str = \"cloudpickle\"\n    picklelib_version: str = None\n\n    @validator(\"picklelib\")\n    def check_picklelib(cls, value):\n        return validate_picklelib(value)\n\n    @root_validator\n    def check_picklelib_version(cls, values):\n        return validate_picklelib_version(values)\n\n    def dumps(self, obj: Any) -&gt; bytes:\n        pickler = from_qualified_name(self.picklelib)\n        blob = pickler.dumps(obj)\n        return base64.encodebytes(blob)\n\n    def loads(self, blob: bytes) -&gt; Any:\n        pickler = from_qualified_name(self.picklelib)\n        return pickler.loads(base64.decodebytes(blob))\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer","title":"<code>Serializer</code>","text":"<p>               Bases: <code>BaseModel</code>, <code>Generic[D]</code>, <code>ABC</code></p> <p>A serializer that can encode objects of type 'D' into bytes.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@register_base_type\nclass Serializer(BaseModel, Generic[D], abc.ABC):\n    \"\"\"\n    A serializer that can encode objects of type 'D' into bytes.\n    \"\"\"\n\n    def __init__(self, **data: Any) -&gt; None:\n        type_string = get_dispatch_key(self) if type(self) != Serializer else \"__base__\"\n        data.setdefault(\"type\", type_string)\n        super().__init__(**data)\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        if \"type\" in kwargs:\n            try:\n                subcls = lookup_type(cls, dispatch_key=kwargs[\"type\"])\n            except KeyError as exc:\n                raise ValidationError(errors=[exc], model=cls)\n\n            return super().__new__(subcls)\n        else:\n            return super().__new__(cls)\n\n    type: str\n\n    @abc.abstractmethod\n    def dumps(self, obj: D) -&gt; bytes:\n        \"\"\"Encode the object into a blob of bytes.\"\"\"\n\n    @abc.abstractmethod\n    def loads(self, blob: bytes) -&gt; D:\n        \"\"\"Decode the blob of bytes into an object.\"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    @classmethod\n    def __dispatch_key__(cls):\n        return cls.__fields__.get(\"type\").get_default()\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer.dumps","title":"<code>dumps</code>  <code>abstractmethod</code>","text":"<p>Encode the object into a blob of bytes.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@abc.abstractmethod\ndef dumps(self, obj: D) -&gt; bytes:\n    \"\"\"Encode the object into a blob of bytes.\"\"\"\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer.loads","title":"<code>loads</code>  <code>abstractmethod</code>","text":"<p>Decode the blob of bytes into an object.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@abc.abstractmethod\ndef loads(self, blob: bytes) -&gt; D:\n    \"\"\"Decode the blob of bytes into an object.\"\"\"\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.prefect_json_object_decoder","title":"<code>prefect_json_object_decoder</code>","text":"<p><code>JSONDecoder.object_hook</code> for decoding objects from JSON when previously encoded with <code>prefect_json_object_encoder</code></p> Source code in <code>prefect/serializers.py</code> <pre><code>def prefect_json_object_decoder(result: dict):\n    \"\"\"\n    `JSONDecoder.object_hook` for decoding objects from JSON when previously encoded\n    with `prefect_json_object_encoder`\n    \"\"\"\n    if \"__class__\" in result:\n        return parse_obj_as(from_qualified_name(result[\"__class__\"]), result[\"data\"])\n    elif \"__exc_type__\" in result:\n        return from_qualified_name(result[\"__exc_type__\"])(result[\"message\"])\n    else:\n        return result\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.prefect_json_object_encoder","title":"<code>prefect_json_object_encoder</code>","text":"<p><code>JSONEncoder.default</code> for encoding objects into JSON with extended type support.</p> <p>Raises a <code>TypeError</code> to fallback on other encoders on failure.</p> Source code in <code>prefect/serializers.py</code> <pre><code>def prefect_json_object_encoder(obj: Any) -&gt; Any:\n    \"\"\"\n    `JSONEncoder.default` for encoding objects into JSON with extended type support.\n\n    Raises a `TypeError` to fallback on other encoders on failure.\n    \"\"\"\n    if isinstance(obj, BaseException):\n        return {\"__exc_type__\": to_qualified_name(obj.__class__), \"message\": str(obj)}\n    else:\n        return {\n            \"__class__\": to_qualified_name(obj.__class__),\n            \"data\": custom_pydantic_encoder({}, obj),\n        }\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/settings/","title":"prefect.settings","text":"","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings","title":"<code>prefect.settings</code>","text":"<p>Prefect settings management.</p> <p>Each setting is defined as a <code>Setting</code> type. The name of each setting is stylized in all caps, matching the environment variable that can be used to change the setting.</p> <p>All settings defined in this file are used to generate a dynamic Pydantic settings class called <code>Settings</code>. When instantiated, this class will load settings from environment variables and pull default values from the setting definitions.</p> <p>The current instance of <code>Settings</code> being used by the application is stored in a <code>SettingsContext</code> model which allows each instance of the <code>Settings</code> class to be accessed in an async-safe manner.</p> <p>Aside from environment variables, we allow settings to be changed during the runtime of the process using profiles. Profiles contain setting overrides that the user may persist without setting environment variables. Profiles are also used internally for managing settings during task run execution where differing settings may be used concurrently in the same process and during testing where we need to override settings to ensure their value is respected as intended.</p> <p>The <code>SettingsContext</code> is set when the <code>prefect</code> module is imported. This context is referred to as the \"root\" settings context for clarity. Generally, this is the only settings context that will be used. When this context is entered, we will instantiate a <code>Settings</code> object, loading settings from environment variables and defaults, then we will load the active profile and use it to override settings. See  <code>enter_root_settings_context</code> for details on determining the active profile.</p> <p>Another <code>SettingsContext</code> may be entered at any time to change the settings being used by the code within the context. Generally, users should not use this. Settings management should be left to Prefect application internals.</p> <p>Generally, settings should be accessed with <code>SETTING_VARIABLE.value()</code> which will pull the current <code>Settings</code> instance from the current <code>SettingsContext</code> and retrieve the value of the relevant setting.</p> <p>Accessing a setting's value will also call the <code>Setting.value_callback</code> which allows settings to be dynamically modified on retrieval. This allows us to make settings dependent on the value of other settings or perform other dynamic effects.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_HOME","title":"<code>PREFECT_HOME = Setting(Path, default=Path('~') / '.prefect', value_callback=expanduser_in_path)</code>  <code>module-attribute</code>","text":"<p>Prefect's home directory. Defaults to <code>~/.prefect</code>. This directory may be created automatically when required.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXTRA_ENTRYPOINTS","title":"<code>PREFECT_EXTRA_ENTRYPOINTS = Setting(str, default='')</code>  <code>module-attribute</code>","text":"<p>Modules for Prefect to import when Prefect is imported.</p> <p>Values should be separated by commas, e.g. <code>my_module,my_other_module</code>. Objects within modules may be specified by a ':' partition, e.g. <code>my_module:my_object</code>. If a callable object is provided, it will be called with no arguments on import.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEBUG_MODE","title":"<code>PREFECT_DEBUG_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, places the API in debug mode. This may modify behavior to facilitate debugging, including extra logs and other verbose assistance. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_COLORS","title":"<code>PREFECT_CLI_COLORS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, use colors in CLI output. If <code>False</code>, output will not include colors codes. Defaults to <code>True</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_PROMPT","title":"<code>PREFECT_CLI_PROMPT = Setting(Optional[bool], default=None)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, use interactive prompts in CLI commands. If <code>False</code>, no interactive prompts will be used. If <code>None</code>, the value will be dynamically determined based on the presence of an interactive-enabled terminal.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_WRAP_LINES","title":"<code>PREFECT_CLI_WRAP_LINES = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, wrap text by inserting new lines in long lines in CLI output. If <code>False</code>, output will not be wrapped. Defaults to <code>True</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TEST_MODE","title":"<code>PREFECT_TEST_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, places the API in test mode. This may modify behavior to facilitate testing. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UNIT_TEST_MODE","title":"<code>PREFECT_UNIT_TEST_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>This variable only exists to facilitate unit testing. If <code>True</code>, code is executing in a unit test context. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UNIT_TEST_LOOP_DEBUG","title":"<code>PREFECT_UNIT_TEST_LOOP_DEBUG = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code> turns on debug mode for the unit testing event loop. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TEST_SETTING","title":"<code>PREFECT_TEST_SETTING = Setting(Any, default=None, value_callback=only_return_value_in_test_mode)</code>  <code>module-attribute</code>","text":"<p>This variable only exists to facilitate testing of settings. If accessed when <code>PREFECT_TEST_MODE</code> is not set, <code>None</code> is returned.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_TLS_INSECURE_SKIP_VERIFY","title":"<code>PREFECT_API_TLS_INSECURE_SKIP_VERIFY = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, disables SSL checking to allow insecure requests. This is recommended only during development, e.g. when using self-signed certificates.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SSL_CERT_FILE","title":"<code>PREFECT_API_SSL_CERT_FILE = Setting(str, default=os.environ.get('SSL_CERT_FILE'))</code>  <code>module-attribute</code>","text":"<p>This configuration settings option specifies the path to an SSL certificate file. When set, it allows the application to use the specified certificate for secure communication. If left unset, the setting will default to the value provided by the <code>SSL_CERT_FILE</code> environment variable.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_URL","title":"<code>PREFECT_API_URL = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>If provided, the URL of a hosted Prefect API. Defaults to <code>None</code>.</p> <p>When using Prefect Cloud, this will include an account and workspace.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SILENCE_API_URL_MISCONFIGURATION","title":"<code>PREFECT_SILENCE_API_URL_MISCONFIGURATION = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, disable the warning when a user accidentally misconfigure its <code>PREFECT_API_URL</code> Sometimes when a user manually set <code>PREFECT_API_URL</code> to a custom url,reverse-proxy for example, we would like to silence this warning so we will set it to <code>FALSE</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_KEY","title":"<code>PREFECT_API_KEY = Setting(str, default=None, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>API key used to authenticate with a the Prefect API. Defaults to <code>None</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_ENABLE_HTTP2","title":"<code>PREFECT_API_ENABLE_HTTP2 = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If true, enable support for HTTP/2 for communicating with an API.</p> <p>If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_MAX_RETRIES","title":"<code>PREFECT_CLIENT_MAX_RETRIES = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>The maximum number of retries to perform on failed HTTP requests.</p> <p>Defaults to 5. Set to 0 to disable retries.</p> <p>See <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> for details on which HTTP status codes are retried.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_RETRY_JITTER_FACTOR","title":"<code>PREFECT_CLIENT_RETRY_JITTER_FACTOR = Setting(float, default=0.2)</code>  <code>module-attribute</code>","text":"<p>A value greater than or equal to zero to control the amount of jitter added to retried client requests. Higher values introduce larger amounts of jitter.</p> <p>Set to 0 to disable jitter. See <code>clamped_poisson_interval</code> for details on the how jitter can affect retry lengths.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_RETRY_EXTRA_CODES","title":"<code>PREFECT_CLIENT_RETRY_EXTRA_CODES = Setting(str, default='', value_callback=status_codes_as_integers_in_range)</code>  <code>module-attribute</code>","text":"<p>A comma-separated list of extra HTTP status codes to retry on. Defaults to an empty string. 429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying may result in unexpected behavior.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_CSRF_SUPPORT_ENABLED","title":"<code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Determines if CSRF token handling is active in the Prefect client for API requests.</p> <p>When enabled (<code>True</code>), the client automatically manages CSRF tokens by retrieving, storing, and including them in applicable state-changing requests (POST, PUT, PATCH, DELETE) to the API.</p> <p>Disabling this setting (<code>False</code>) means the client will not handle CSRF tokens, which might be suitable for environments where CSRF protection is disabled.</p> <p>Defaults to <code>True</code>, ensuring CSRF protection is enabled by default.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_API_URL","title":"<code>PREFECT_CLOUD_API_URL = Setting(str, default='https://api.prefect.cloud/api', value_callback=check_for_deprecated_cloud_url)</code>  <code>module-attribute</code>","text":"<p>API URL for Prefect Cloud. Used for authentication.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_URL","title":"<code>PREFECT_CLOUD_URL = Setting(str, default=None, deprecated=True, deprecated_start_date='Dec 2022', deprecated_help='Use `PREFECT_CLOUD_API_URL` instead.')</code>  <code>module-attribute</code>","text":"","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_URL","title":"<code>PREFECT_UI_URL = Setting(Optional[str], default=None, value_callback=default_ui_url)</code>  <code>module-attribute</code>","text":"<p>The URL for the UI. By default, this is inferred from the PREFECT_API_URL.</p> <p>When using Prefect Cloud, this will include the account and workspace. When using an ephemeral server, this will be <code>None</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_UI_URL","title":"<code>PREFECT_CLOUD_UI_URL = Setting(str, default=None, value_callback=default_cloud_ui_url)</code>  <code>module-attribute</code>","text":"<p>The URL for the Cloud UI. By default, this is inferred from the PREFECT_CLOUD_API_URL.</p> PREFECT_UI_URL will be workspace specific and will be usable in the open source too. <p>In contrast, this value is only valid for Cloud and will not include the workspace.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_REQUEST_TIMEOUT","title":"<code>PREFECT_API_REQUEST_TIMEOUT = Setting(float, default=60.0)</code>  <code>module-attribute</code>","text":"<p>The default timeout for requests to the API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN","title":"<code>PREFECT_EXPERIMENTAL_WARN = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If enabled, warn on usage of experimental features.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_PROFILES_PATH","title":"<code>PREFECT_PROFILES_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'profiles.toml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a profiles configuration files.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RESULTS_DEFAULT_SERIALIZER","title":"<code>PREFECT_RESULTS_DEFAULT_SERIALIZER = Setting(str, default='pickle')</code>  <code>module-attribute</code>","text":"<p>The default serializer to use when not otherwise specified.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RESULTS_PERSIST_BY_DEFAULT","title":"<code>PREFECT_RESULTS_PERSIST_BY_DEFAULT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>The default setting for persisting results when not otherwise specified. If enabled, flow and task results will be persisted unless they opt out.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASKS_REFRESH_CACHE","title":"<code>PREFECT_TASKS_REFRESH_CACHE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, enables a refresh of cached results: re-executing the task will refresh the cached results. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_DEFAULT_RETRIES","title":"<code>PREFECT_TASK_DEFAULT_RETRIES = Setting(int, default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default number of retries for all tasks. This value does not overwrite individually set retries values on tasks</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_FLOW_DEFAULT_RETRIES","title":"<code>PREFECT_FLOW_DEFAULT_RETRIES = Setting(int, default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default number of retries for all flows. This value does not overwrite individually set retries values on a flow</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS","title":"<code>PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS = Setting(Union[int, float], default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the retry delay seconds for all flows. This value does not overwrite individually set retry delay seconds</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS","title":"<code>PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS = Setting(Union[float, int, List[float]], default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default retry delay seconds for all tasks. This value does not overwrite individually set retry delay seconds</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS","title":"<code>PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS = Setting(int, default=30)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOCAL_STORAGE_PATH","title":"<code>PREFECT_LOCAL_STORAGE_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'storage', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a block storage directory to store things in.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MEMO_STORE_PATH","title":"<code>PREFECT_MEMO_STORE_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'memo_store.toml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to the memo store file.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION","title":"<code>PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Controls whether or not block auto-registration on start up should be memoized. Setting to False may result in slower server start up times.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_LEVEL","title":"<code>PREFECT_LOGGING_LEVEL = Setting(str, default='INFO', value_callback=debug_mode_log_level)</code>  <code>module-attribute</code>","text":"<p>The default logging level for Prefect loggers. Defaults to \"INFO\" during normal operation. Is forced to \"DEBUG\" during debug mode.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_INTERNAL_LEVEL","title":"<code>PREFECT_LOGGING_INTERNAL_LEVEL = Setting(str, default='ERROR', value_callback=debug_mode_log_level)</code>  <code>module-attribute</code>","text":"<p>The default logging level for Prefect's internal machinery loggers. Defaults to \"ERROR\" during normal operation. Is forced to \"DEBUG\" during debug mode.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_SERVER_LEVEL","title":"<code>PREFECT_LOGGING_SERVER_LEVEL = Setting(str, default='WARNING')</code>  <code>module-attribute</code>","text":"<p>The default logging level for the Prefect API server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_SETTINGS_PATH","title":"<code>PREFECT_LOGGING_SETTINGS_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'logging.yml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a custom YAML logging configuration file. If no file is found, the default <code>logging.yml</code> is used. Defaults to a logging.yml in the Prefect home directory.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_EXTRA_LOGGERS","title":"<code>PREFECT_LOGGING_EXTRA_LOGGERS = Setting(str, default='', value_callback=get_extra_loggers)</code>  <code>module-attribute</code>","text":"<p>Additional loggers to attach to Prefect logging at runtime. Values should be comma separated. The handlers attached to the 'prefect' logger will be added to these loggers. Additionally, if the level is not set, it will be set to the same level as the 'prefect' logger.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_LOG_PRINTS","title":"<code>PREFECT_LOGGING_LOG_PRINTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If set, <code>print</code> statements in flows and tasks will be redirected to the Prefect logger for the given run. This setting can be overridden by individual tasks and flows.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_ENABLED","title":"<code>PREFECT_LOGGING_TO_API_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Toggles sending logs to the API. If <code>False</code>, logs sent to the API log handler will not be sent to the API.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_BATCH_INTERVAL","title":"<code>PREFECT_LOGGING_TO_API_BATCH_INTERVAL = Setting(float, default=2.0)</code>  <code>module-attribute</code>","text":"<p>The number of seconds between batched writes of logs to the API.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_BATCH_SIZE","title":"<code>PREFECT_LOGGING_TO_API_BATCH_SIZE = Setting(int, default=4000000)</code>  <code>module-attribute</code>","text":"<p>The maximum size in bytes for a batch of logs.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_MAX_LOG_SIZE","title":"<code>PREFECT_LOGGING_TO_API_MAX_LOG_SIZE = Setting(int, default=1000000)</code>  <code>module-attribute</code>","text":"<p>The maximum size in bytes for a single log.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW","title":"<code>PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW = Setting(Literal['warn', 'error', 'ignore'], default='warn')</code>  <code>module-attribute</code>","text":"<p>Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.</p> <p>All logs sent to the API must be associated with a flow run. The API log handler can only be used outside of a flow by manually providing a flow run identifier. Logs that are not associated with a flow run will not be sent to the API. This setting can be used to determine if a warning or error is displayed when the identifier is missing.</p> <p>The following options are available:</p> <ul> <li>\"warn\": Log a warning message.</li> <li>\"error\": Raise an error.</li> <li>\"ignore\": Do not log a warning message or raise an error.</li> </ul>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SQLALCHEMY_POOL_SIZE","title":"<code>PREFECT_SQLALCHEMY_POOL_SIZE = Setting(int, default=None)</code>  <code>module-attribute</code>","text":"<p>Controls connection pool size when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy pool size will be used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SQLALCHEMY_MAX_OVERFLOW","title":"<code>PREFECT_SQLALCHEMY_MAX_OVERFLOW = Setting(int, default=None)</code>  <code>module-attribute</code>","text":"<p>Controls maximum overflow of the connection pool when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy maximum overflow value will be used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_COLORS","title":"<code>PREFECT_LOGGING_COLORS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether to style console logs with color.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_MARKUP","title":"<code>PREFECT_LOGGING_MARKUP = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether to interpret strings wrapped in square brackets as a style. This allows styles to be conveniently added to log messages, e.g. <code>[red]This is a red message.[/red]</code>. However, the downside is, if enabled, strings that contain square brackets may be inaccurately interpreted and lead to incomplete output, e.g. <code>DROP TABLE [dbo].[SomeTable];\"</code> outputs <code>DROP TABLE .[SomeTable];</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD","title":"<code>PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD = Setting(float, default=10.0)</code>  <code>module-attribute</code>","text":"<p>Threshold time in seconds for logging a warning if task parameter introspection exceeds this duration. Parameter introspection can be a significant performance hit when the parameter is a large collection object, e.g. a large dictionary or DataFrame, and each element needs to be inspected. See <code>prefect.utilities.annotations.quote</code> for more details. Defaults to <code>10.0</code>. Set to <code>0</code> to disable logging the warning.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_AGENT_QUERY_INTERVAL","title":"<code>PREFECT_AGENT_QUERY_INTERVAL = Setting(float, default=15)</code>  <code>module-attribute</code>","text":"<p>The agent loop interval, in seconds. Agents will check for new runs this often. Defaults to <code>15</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_AGENT_PREFETCH_SECONDS","title":"<code>PREFECT_AGENT_PREFETCH_SECONDS = Setting(int, default=15)</code>  <code>module-attribute</code>","text":"<p>Agents will look for scheduled runs this many seconds in the future and attempt to run them. This accounts for any additional infrastructure spin-up time or latency in preparing a flow run. Note flow runs will not start before their scheduled time, even if they are prefetched. Defaults to <code>15</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_ASYNC_FETCH_STATE_RESULT","title":"<code>PREFECT_ASYNC_FETCH_STATE_RESULT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Determines whether <code>State.result()</code> fetches results automatically or not. In Prefect 2.6.0, the <code>State.result()</code> method was updated to be async to facilitate automatic retrieval of results from storage which means when writing async code you must <code>await</code> the call. For backwards compatibility, the result is not retrieved by default for async users. You may opt into this per call by passing  <code>fetch=True</code> or toggle this setting to change the behavior globally. This setting does not affect users writing synchronous tasks and flows. This setting does not affect retrieval of results when using <code>Future.result()</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_BLOCKS_REGISTER_ON_START","title":"<code>PREFECT_API_BLOCKS_REGISTER_ON_START = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_PASSWORD","title":"<code>PREFECT_API_DATABASE_PASSWORD = Setting(str, default=None, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>Password to template into the <code>PREFECT_API_DATABASE_CONNECTION_URL</code>. This is useful if the password must be provided separately from the connection URL. To use this setting, you must include it in your connection URL.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_CONNECTION_URL","title":"<code>PREFECT_API_DATABASE_CONNECTION_URL = Setting(str, default=None, value_callback=default_database_connection_url, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>A database connection URL in a SQLAlchemy-compatible format. Prefect currently supports SQLite and Postgres. Note that all Prefect database engines must use an async driver - for SQLite, use <code>sqlite+aiosqlite</code> and for Postgres use <code>postgresql+asyncpg</code>.</p> <p>SQLite in-memory databases can be used by providing the url <code>sqlite+aiosqlite:///file::memory:?cache=shared&amp;uri=true&amp;check_same_thread=false</code>, which will allow the database to be accessed by multiple threads. Note that in-memory databases can not be accessed from multiple processes and should only be used for simple tests.</p> <p>Defaults to a sqlite database stored in the Prefect home directory.</p> <p>If you need to provide password via a different environment variable, you use the <code>PREFECT_API_DATABASE_PASSWORD</code> setting. For example:</p> <pre><code>PREFECT_API_DATABASE_PASSWORD='mypassword'\nPREFECT_API_DATABASE_CONNECTION_URL='postgresql+asyncpg://postgres:${PREFECT_API_DATABASE_PASSWORD}@localhost/prefect'\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_ECHO","title":"<code>PREFECT_API_DATABASE_ECHO = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, SQLAlchemy will log all SQL issued to the database. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_MIGRATE_ON_START","title":"<code>PREFECT_API_DATABASE_MIGRATE_ON_START = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, the database will be upgraded on application creation. If <code>False</code>, the database will need to be upgraded manually.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_TIMEOUT","title":"<code>PREFECT_API_DATABASE_TIMEOUT = Setting(Optional[float], default=10.0)</code>  <code>module-attribute</code>","text":"<p>A statement timeout, in seconds, applied to all database interactions made by the API. Defaults to 10 seconds.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_CONNECTION_TIMEOUT","title":"<code>PREFECT_API_DATABASE_CONNECTION_TIMEOUT = Setting(Optional[float], default=5)</code>  <code>module-attribute</code>","text":"<p>A connection timeout, in seconds, applied to database connections. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS = Setting(float, default=60)</code>  <code>module-attribute</code>","text":"<p>The scheduler loop interval, in seconds. This determines how often the scheduler will attempt to schedule new flow runs, but has no impact on how quickly either flow runs or task runs are actually executed. Defaults to <code>60</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The number of deployments the scheduler will attempt to schedule in a single batch. If there are more deployments than the batch size, the scheduler immediately attempts to schedule the next batch; it does not sleep for <code>scheduler_loop_seconds</code> until it has visited every deployment once. Defaults to <code>100</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The scheduler will attempt to schedule up to this many auto-scheduled runs in the future. Note that runs may have fewer than this many scheduled runs, depending on the value of <code>scheduler_max_scheduled_time</code>.  Defaults to <code>100</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS = Setting(int, default=3)</code>  <code>module-attribute</code>","text":"<p>The scheduler will attempt to schedule at least this many auto-scheduled runs in the future. Note that runs may have more than this many scheduled runs, depending on the value of <code>scheduler_min_scheduled_time</code>.  Defaults to <code>3</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME = Setting(timedelta, default=timedelta(days=100))</code>  <code>module-attribute</code>","text":"<p>The scheduler will create new runs up to this far in the future. Note that this setting will take precedence over <code>scheduler_max_runs</code>: if a flow runs once a month and <code>scheduler_max_scheduled_time</code> is three months, then only three runs will be scheduled. Defaults to 100 days (<code>8640000</code> seconds).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME = Setting(timedelta, default=timedelta(hours=1))</code>  <code>module-attribute</code>","text":"<p>The scheduler will create new runs at least this far in the future. Note that this setting will take precedence over <code>scheduler_min_runs</code>: if a flow runs every hour and <code>scheduler_min_scheduled_time</code> is three hours, then three runs will be scheduled even if <code>scheduler_min_runs</code> is 1. Defaults to 1 hour (<code>3600</code> seconds).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The number of flow runs the scheduler will attempt to insert in one batch across all deployments. If the number of flow runs to schedule exceeds this amount, the runs will be inserted in batches of this size. Defaults to <code>500</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS = Setting(float, default=5)</code>  <code>module-attribute</code>","text":"<p>The late runs service will look for runs to mark as late this often. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS = Setting(timedelta, default=timedelta(seconds=15))</code>  <code>module-attribute</code>","text":"<p>The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to <code>5</code> seconds.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS = Setting(float, default=5)</code>  <code>module-attribute</code>","text":"<p>The pause expiration service will look for runs to mark as failed this often. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS = Setting(float, default=20)</code>  <code>module-attribute</code>","text":"<p>The cancellation cleanup service will look non-terminal tasks and subflows this often. Defaults to <code>20</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_ENABLED","title":"<code>PREFECT_API_SERVICES_FOREMAN_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the Foreman service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS = Setting(float, default=15)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to wait between each iteration of the Foreman loop which checks for offline workers and updates work pool status.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE","title":"<code>PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE = Setting(int, default=3)</code>  <code>module-attribute</code>","text":"<p>The number of heartbeats that must be missed before a worker is marked as offline.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS = Setting(int, default=30)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to use for online/offline evaluation if a worker's heartbeat interval is not set.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS = Setting(int, default=60)</code>  <code>module-attribute</code>","text":"<p>The number of seconds before a deployment is marked as not ready if it has not been polled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS = Setting(int, default=60)</code>  <code>module-attribute</code>","text":"<p>The number of seconds before a work queue is marked as not ready if it has not been polled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DEFAULT_LIMIT","title":"<code>PREFECT_API_DEFAULT_LIMIT = Setting(int, default=200)</code>  <code>module-attribute</code>","text":"<p>The default limit applied to queries that can return multiple objects, such as <code>POST /flow_runs/filter</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_HOST","title":"<code>PREFECT_SERVER_API_HOST = Setting(str, default='127.0.0.1')</code>  <code>module-attribute</code>","text":"<p>The API's host address (defaults to <code>127.0.0.1</code>).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_PORT","title":"<code>PREFECT_SERVER_API_PORT = Setting(int, default=4200)</code>  <code>module-attribute</code>","text":"<p>The API's port address (defaults to <code>4200</code>).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_KEEPALIVE_TIMEOUT","title":"<code>PREFECT_SERVER_API_KEEPALIVE_TIMEOUT = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>The API's keep alive timeout (defaults to <code>5</code>). Refer to https://www.uvicorn.org/settings/#timeouts for details.</p> <p>When the API is hosted behind a load balancer, you may want to set this to a value greater than the load balancer's idle timeout.</p> <p>Note this setting only applies when calling <code>prefect server start</code>; if hosting the API with another tool you will need to configure this there instead.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED","title":"<code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Controls the activation of CSRF protection for the Prefect server API.</p> <p>When enabled (<code>True</code>), the server enforces CSRF validation checks on incoming state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF token to be included in the request headers or body. This adds a layer of security by preventing unauthorized or malicious sites from making requests on behalf of authenticated users.</p> <p>It is recommended to enable this setting in production environments where the API is exposed to web clients to safeguard against CSRF attacks.</p> <p>Note: Enabling this setting requires corresponding support in the client for CSRF token management. See PREFECT_CLIENT_CSRF_SUPPORT_ENABLED for more.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_CSRF_TOKEN_EXPIRATION","title":"<code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION = Setting(timedelta, default=timedelta(hours=1))</code>  <code>module-attribute</code>","text":"<p>Specifies the duration for which a CSRF token remains valid after being issued by the server.</p> <p>The default expiration time is set to 1 hour, which offers a reasonable compromise. Adjust this setting based on your specific security requirements and usage patterns.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_ENABLED","title":"<code>PREFECT_UI_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to serve the Prefect UI.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_API_URL","title":"<code>PREFECT_UI_API_URL = Setting(str, default=None, value_callback=default_ui_api_url)</code>  <code>module-attribute</code>","text":"<p>The connection url for communication from the UI to the API. Defaults to <code>PREFECT_API_URL</code> if set. Otherwise, the default URL is generated from <code>PREFECT_SERVER_API_HOST</code> and <code>PREFECT_SERVER_API_PORT</code>. If providing a custom value, the aforementioned settings may be templated into the given string.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_ANALYTICS_ENABLED","title":"<code>PREFECT_SERVER_ANALYTICS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version) on server startup to help us improve our product.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_ENABLED","title":"<code>PREFECT_API_SERVICES_SCHEDULER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the scheduling service in the server application. If disabled, you will need to run this service separately to schedule runs for deployments.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_ENABLED","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the late runs service in the server application. If disabled, you will need to run this service separately to have runs past their scheduled start time marked as late.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED","title":"<code>PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the flow run notifications service in the server application. If disabled, you will need to run this service separately to send flow run notifications.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED","title":"<code>PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the paused flow run expiration service in the server application. If disabled, paused flows that have timed out will remain in a Paused state until a resume attempt.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH","title":"<code>PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH = Setting(int, default=2000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of characters allowed for a task run cache key. This setting cannot be changed client-side, it must be set on the server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED","title":"<code>PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the cancellation cleanup service in the server application. If disabled, task runs and subflow runs belonging to cancelled flows may remain in non-terminal states.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES","title":"<code>PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES = Setting(int, default=10000)</code>  <code>module-attribute</code>","text":"<p>The maximum size of a flow run graph on the v2 API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS","title":"<code>PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS = Setting(int, default=10000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of artifacts to show on a flow run graph on the v2 API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS_ON_FLOW_RUN_GRAPH","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS_ON_FLOW_RUN_GRAPH = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable artifacts on the flow run graph.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run states on the flow run graph.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect work pools.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORK_POOLS","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORK_POOLS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect work pools are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKERS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORKERS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect workers.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKERS","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORKERS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect workers are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_VISUALIZE","title":"<code>PREFECT_EXPERIMENTAL_WARN_VISUALIZE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect visualize is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental enhanced flow run cancellation.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION","title":"<code>PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental enhanced flow run cancellation is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_DEPLOYMENT_STATUS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_DEPLOYMENT_STATUS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable deployment status in the UI</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS","title":"<code>PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when deployment status is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT","title":"<code>PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run input.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT","title":"<code>PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run input.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_EVENTS","title":"<code>PREFECT_EXPERIMENTAL_EVENTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether to enable Prefect's server-side event features. Note that Prefect Cloud clients will always emit events during flow and task runs regardless of this setting.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_PROCESS_LIMIT","title":"<code>PREFECT_RUNNER_PROCESS_LIMIT = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>Maximum number of processes a runner will execute in parallel.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_POLL_FREQUENCY","title":"<code>PREFECT_RUNNER_POLL_FREQUENCY = Setting(int, default=10)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a runner should wait between queries for scheduled work.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE","title":"<code>PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE = Setting(int, default=2)</code>  <code>module-attribute</code>","text":"<p>Number of missed polls before a runner is considered unhealthy by its webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_HOST","title":"<code>PREFECT_RUNNER_SERVER_HOST = Setting(str, default='localhost')</code>  <code>module-attribute</code>","text":"<p>The host address the runner's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_PORT","title":"<code>PREFECT_RUNNER_SERVER_PORT = Setting(int, default=8080)</code>  <code>module-attribute</code>","text":"<p>The port the runner's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_LOG_LEVEL","title":"<code>PREFECT_RUNNER_SERVER_LOG_LEVEL = Setting(str, default='error')</code>  <code>module-attribute</code>","text":"<p>The log level of the runner's webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_ENABLE","title":"<code>PREFECT_RUNNER_SERVER_ENABLE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable the runner's webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS","title":"<code>PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS = Setting(int, default=50)</code>  <code>module-attribute</code>","text":"<p>The maximum number of scheduled runs to create for a deployment.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_HEARTBEAT_SECONDS","title":"<code>PREFECT_WORKER_HEARTBEAT_SECONDS = Setting(float, default=30)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a worker should wait between sending a heartbeat.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_QUERY_SECONDS","title":"<code>PREFECT_WORKER_QUERY_SECONDS = Setting(float, default=10)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a worker should wait between queries for scheduled flow runs.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_PREFETCH_SECONDS","title":"<code>PREFECT_WORKER_PREFETCH_SECONDS = Setting(float, default=10)</code>  <code>module-attribute</code>","text":"<p>The number of seconds into the future a worker should query for scheduled flow runs. Can be used to compensate for infrastructure start up time for a worker.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_WEBSERVER_HOST","title":"<code>PREFECT_WORKER_WEBSERVER_HOST = Setting(str, default='0.0.0.0')</code>  <code>module-attribute</code>","text":"<p>The host address the worker's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_WEBSERVER_PORT","title":"<code>PREFECT_WORKER_WEBSERVER_PORT = Setting(int, default=8080)</code>  <code>module-attribute</code>","text":"<p>The port the worker's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK","title":"<code>PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK = Setting(str, default='local-file-system/prefect-task-scheduling')</code>  <code>module-attribute</code>","text":"<p>The <code>block-type/block-document</code> slug of a block to use as the default storage for autonomous tasks.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS","title":"<code>PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to delete failed task submissions from the database.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE","title":"<code>PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE = Setting(int, default=1000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of scheduled tasks to queue for submission.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE","title":"<code>PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The maximum number of retries to queue for submission.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT","title":"<code>PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT = Setting(timedelta, default=timedelta(seconds=30))</code>  <code>module-attribute</code>","text":"<p>How long before a PENDING task are made available to another task server.  In practice, a task server should move a task from PENDING to RUNNING very quickly, so runs stuck in PENDING for a while is a sign that the task server may have crashed.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental worker webserver endpoints.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect artifacts.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_ARTIFACTS","title":"<code>PREFECT_EXPERIMENTAL_WARN_ARTIFACTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect artifacts are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKSPACE_DASHBOARD","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORKSPACE_DASHBOARD = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable the experimental workspace dashboard.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKSPACE_DASHBOARD","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORKSPACE_DASHBOARD = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when the experimental workspace dashboard is enabled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental task scheduling.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_QUEUE_STATUS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORK_QUEUE_STATUS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental work queue status in-place of work queue health.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental new engine.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT","title":"<code>PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to disable the sync_compatible decorator utility.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_RESULT_STORAGE_BLOCK","title":"<code>PREFECT_DEFAULT_RESULT_STORAGE_BLOCK = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The <code>block-type/block-document</code> slug of a block to use as the default result storage.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_WORK_POOL_NAME","title":"<code>PREFECT_DEFAULT_WORK_POOL_NAME = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The default work pool to deploy to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE","title":"<code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The default Docker namespace to use when building images.</p> <p>Can be either an organization/username or a registry URL with an organization/username.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_SERVE_BASE","title":"<code>PREFECT_UI_SERVE_BASE = Setting(str, default='/')</code>  <code>module-attribute</code>","text":"<p>The base URL path to serve the Prefect UI from.</p> <p>Defaults to the root path.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_STATIC_DIRECTORY","title":"<code>PREFECT_UI_STATIC_DIRECTORY = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container)</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MESSAGING_BROKER","title":"<code>PREFECT_MESSAGING_BROKER = Setting(str, default='prefect.server.utilities.messaging.memory')</code>  <code>module-attribute</code>","text":"<p>Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MESSAGING_CACHE","title":"<code>PREFECT_MESSAGING_CACHE = Setting(str, default='prefect.server.utilities.messaging.memory')</code>  <code>module-attribute</code>","text":"<p>Which cache implementation to use for the events system.  Should point to a module that exports a Cache class.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE","title":"<code>PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The maximum number of labels a resource may have.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES","title":"<code>PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The maximum number of related resources an Event may have.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_SIZE_BYTES","title":"<code>PREFECT_EVENTS_MAXIMUM_SIZE_BYTES = Setting(int, default=1500000)</code>  <code>module-attribute</code>","text":"<p>The maximum size of an Event when serialized to JSON</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED","title":"<code>PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the event debug logger service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_TRIGGERS_ENABLED","title":"<code>PREFECT_API_SERVICES_TRIGGERS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the triggers service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER","title":"<code>PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER = Setting(timedelta, default=timedelta(seconds=60))</code>  <code>module-attribute</code>","text":"<p>The amount of time to retain expired automation buckets</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_PROACTIVE_GRANULARITY","title":"<code>PREFECT_EVENTS_PROACTIVE_GRANULARITY = Setting(timedelta, default=timedelta(seconds=5))</code>  <code>module-attribute</code>","text":"<p>How frequently proactive automations are evaluated</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the event persister service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE = Setting(int, default=20, gt=0)</code>  <code>module-attribute</code>","text":"<p>The number of events the event persister will attempt to insert in one batch.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL = Setting(float, default=5, gt=0.0)</code>  <code>module-attribute</code>","text":"<p>The maximum number of seconds between flushes of the event persister.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_RETENTION_PERIOD","title":"<code>PREFECT_EVENTS_RETENTION_PERIOD = Setting(timedelta, default=timedelta(days=7))</code>  <code>module-attribute</code>","text":"<p>The amount of time to retain events in the database.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_EVENTS_STREAM_OUT_ENABLED","title":"<code>PREFECT_API_EVENTS_STREAM_OUT_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to allow streaming events out of via websockets.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL","title":"<code>PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL = Setting(timedelta, default=timedelta(minutes=5))</code>  <code>module-attribute</code>","text":"<p>How long to cache related resource data for emitting server-side vents</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting","title":"<code>Setting</code>","text":"<p>               Bases: <code>Generic[T]</code></p> <p>Setting definition type.</p> Source code in <code>prefect/settings.py</code> <pre><code>class Setting(Generic[T]):\n    \"\"\"\n    Setting definition type.\n    \"\"\"\n\n    def __init__(\n        self,\n        type: Type[T],\n        *,\n        deprecated: bool = False,\n        deprecated_start_date: Optional[str] = None,\n        deprecated_end_date: Optional[str] = None,\n        deprecated_help: str = \"\",\n        deprecated_when_message: str = \"\",\n        deprecated_when: Optional[Callable[[Any], bool]] = None,\n        deprecated_renamed_to: Optional[\"Setting[T]\"] = None,\n        value_callback: Optional[Callable[[\"Settings\", T], T]] = None,\n        is_secret: bool = False,\n        **kwargs: Any,\n    ) -&gt; None:\n        self.field: fields.FieldInfo = Field(**kwargs)\n        self.type = type\n        self.value_callback = value_callback\n        self._name = None\n        self.is_secret = is_secret\n        self.deprecated = deprecated\n        self.deprecated_start_date = deprecated_start_date\n        self.deprecated_end_date = deprecated_end_date\n        self.deprecated_help = deprecated_help\n        self.deprecated_when = deprecated_when or (lambda _: True)\n        self.deprecated_when_message = deprecated_when_message\n        self.deprecated_renamed_to = deprecated_renamed_to\n        self.deprecated_renamed_from = None\n        self.__doc__ = self.field.description\n\n        # Validate the deprecation settings, will throw an error at setting definition\n        # time if the developer has not configured it correctly\n        if deprecated:\n            generate_deprecation_message(\n                name=\"...\",  # setting names not populated until after init\n                start_date=self.deprecated_start_date,\n                end_date=self.deprecated_end_date,\n                help=self.deprecated_help,\n                when=self.deprecated_when_message,\n            )\n\n        if deprecated_renamed_to is not None:\n            # Track the deprecation both ways\n            deprecated_renamed_to.deprecated_renamed_from = self\n\n    def value(self, bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Get the current value of a setting.\n\n        Example:\n        ```python\n        from prefect.settings import PREFECT_API_URL\n        PREFECT_API_URL.value()\n        ```\n        \"\"\"\n        return self.value_from(get_current_settings(), bypass_callback=bypass_callback)\n\n    def value_from(self, settings: \"Settings\", bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Get the value of a setting from a settings object\n\n        Example:\n        ```python\n        from prefect.settings import get_default_settings\n        PREFECT_API_URL.value_from(get_default_settings())\n        ```\n        \"\"\"\n        value = settings.value_of(self, bypass_callback=bypass_callback)\n\n        if not bypass_callback and self.deprecated and self.deprecated_when(value):\n            # Check if this setting is deprecated and someone is accessing the value\n            # via the old name\n            warnings.warn(self.deprecated_message, DeprecationWarning, stacklevel=3)\n\n            # If the the value is empty, return the new setting's value for compat\n            if value is None and self.deprecated_renamed_to is not None:\n                return self.deprecated_renamed_to.value_from(settings)\n\n        if not bypass_callback and self.deprecated_renamed_from is not None:\n            # Check if this setting is a rename of a deprecated setting and the\n            # deprecated setting is set and should be used for compatibility\n            deprecated_value = self.deprecated_renamed_from.value_from(\n                settings, bypass_callback=True\n            )\n            if deprecated_value is not None:\n                warnings.warn(\n                    (\n                        f\"{self.deprecated_renamed_from.deprecated_message} Because\"\n                        f\" {self.deprecated_renamed_from.name!r} is set it will be used\"\n                        f\" instead of {self.name!r} for backwards compatibility.\"\n                    ),\n                    DeprecationWarning,\n                    stacklevel=3,\n                )\n            return deprecated_value or value\n\n        return value\n\n    @property\n    def name(self):\n        if self._name:\n            return self._name\n\n        # Lookup the name on first access\n        for name, val in tuple(globals().items()):\n            if val == self:\n                self._name = name\n                return name\n\n        raise ValueError(\"Setting not found in `prefect.settings` module.\")\n\n    @name.setter\n    def name(self, value: str):\n        self._name = value\n\n    @property\n    def deprecated_message(self):\n        return generate_deprecation_message(\n            name=f\"Setting {self.name!r}\",\n            start_date=self.deprecated_start_date,\n            end_date=self.deprecated_end_date,\n            help=self.deprecated_help,\n            when=self.deprecated_when_message,\n        )\n\n    def __repr__(self) -&gt; str:\n        return f\"&lt;{self.name}: {self.type.__name__}&gt;\"\n\n    def __bool__(self) -&gt; bool:\n        \"\"\"\n        Returns a truthy check of the current value.\n        \"\"\"\n        return bool(self.value())\n\n    def __eq__(self, __o: object) -&gt; bool:\n        return __o.__eq__(self.value())\n\n    def __hash__(self) -&gt; int:\n        return hash((type(self), self.name))\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting.value","title":"<code>value</code>","text":"<p>Get the current value of a setting.</p> <p>Example: <pre><code>from prefect.settings import PREFECT_API_URL\nPREFECT_API_URL.value()\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>def value(self, bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Get the current value of a setting.\n\n    Example:\n    ```python\n    from prefect.settings import PREFECT_API_URL\n    PREFECT_API_URL.value()\n    ```\n    \"\"\"\n    return self.value_from(get_current_settings(), bypass_callback=bypass_callback)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting.value_from","title":"<code>value_from</code>","text":"<p>Get the value of a setting from a settings object</p> <p>Example: <pre><code>from prefect.settings import get_default_settings\nPREFECT_API_URL.value_from(get_default_settings())\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>def value_from(self, settings: \"Settings\", bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Get the value of a setting from a settings object\n\n    Example:\n    ```python\n    from prefect.settings import get_default_settings\n    PREFECT_API_URL.value_from(get_default_settings())\n    ```\n    \"\"\"\n    value = settings.value_of(self, bypass_callback=bypass_callback)\n\n    if not bypass_callback and self.deprecated and self.deprecated_when(value):\n        # Check if this setting is deprecated and someone is accessing the value\n        # via the old name\n        warnings.warn(self.deprecated_message, DeprecationWarning, stacklevel=3)\n\n        # If the the value is empty, return the new setting's value for compat\n        if value is None and self.deprecated_renamed_to is not None:\n            return self.deprecated_renamed_to.value_from(settings)\n\n    if not bypass_callback and self.deprecated_renamed_from is not None:\n        # Check if this setting is a rename of a deprecated setting and the\n        # deprecated setting is set and should be used for compatibility\n        deprecated_value = self.deprecated_renamed_from.value_from(\n            settings, bypass_callback=True\n        )\n        if deprecated_value is not None:\n            warnings.warn(\n                (\n                    f\"{self.deprecated_renamed_from.deprecated_message} Because\"\n                    f\" {self.deprecated_renamed_from.name!r} is set it will be used\"\n                    f\" instead of {self.name!r} for backwards compatibility.\"\n                ),\n                DeprecationWarning,\n                stacklevel=3,\n            )\n        return deprecated_value or value\n\n    return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings","title":"<code>Settings</code>","text":"<p>               Bases: <code>SettingsFieldsMixin</code></p> <p>Contains validated Prefect settings.</p> <p>Settings should be accessed using the relevant <code>Setting</code> object. For example: <pre><code>from prefect.settings import PREFECT_HOME\nPREFECT_HOME.value()\n</code></pre></p> <p>Accessing a setting attribute directly will ignore any <code>value_callback</code> mutations. This is not recommended: <pre><code>from prefect.settings import Settings\nSettings().PREFECT_PROFILES_PATH  # PosixPath('${PREFECT_HOME}/profiles.toml')\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>@add_cloudpickle_reduction\nclass Settings(SettingsFieldsMixin):\n    \"\"\"\n    Contains validated Prefect settings.\n\n    Settings should be accessed using the relevant `Setting` object. For example:\n    ```python\n    from prefect.settings import PREFECT_HOME\n    PREFECT_HOME.value()\n    ```\n\n    Accessing a setting attribute directly will ignore any `value_callback` mutations.\n    This is not recommended:\n    ```python\n    from prefect.settings import Settings\n    Settings().PREFECT_PROFILES_PATH  # PosixPath('${PREFECT_HOME}/profiles.toml')\n    ```\n    \"\"\"\n\n    def value_of(self, setting: Setting[T], bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Retrieve a setting's value.\n        \"\"\"\n        value = getattr(self, setting.name)\n        if setting.value_callback and not bypass_callback:\n            value = setting.value_callback(self, value)\n        return value\n\n    @validator(PREFECT_LOGGING_LEVEL.name, PREFECT_LOGGING_SERVER_LEVEL.name)\n    def check_valid_log_level(cls, value):\n        if isinstance(value, str):\n            value = value.upper()\n        logging._checkLevel(value)\n        return value\n\n    @root_validator\n    def post_root_validators(cls, values):\n        \"\"\"\n        Add root validation functions for settings here.\n        \"\"\"\n        # TODO: We could probably register these dynamically but this is the simpler\n        #       approach for now. We can explore more interesting validation features\n        #       in the future.\n        values = max_log_size_smaller_than_batch_size(values)\n        values = warn_on_database_password_value_without_usage(values)\n        if not values[\"PREFECT_SILENCE_API_URL_MISCONFIGURATION\"]:\n            values = warn_on_misconfigured_api_url(values)\n        return values\n\n    def copy_with_update(\n        self,\n        updates: Mapping[Setting, Any] = None,\n        set_defaults: Mapping[Setting, Any] = None,\n        restore_defaults: Iterable[Setting] = None,\n    ) -&gt; \"Settings\":\n        \"\"\"\n        Create a new `Settings` object with validation.\n\n        Arguments:\n            updates: A mapping of settings to new values. Existing values for the\n                given settings will be overridden.\n            set_defaults: A mapping of settings to new default values. Existing values for\n                the given settings will only be overridden if they were not set.\n            restore_defaults: An iterable of settings to restore to their default values.\n\n        Returns:\n            A new `Settings` object.\n        \"\"\"\n        updates = updates or {}\n        set_defaults = set_defaults or {}\n        restore_defaults = restore_defaults or set()\n        restore_defaults_names = {setting.name for setting in restore_defaults}\n\n        return self.__class__(\n            **{\n                **{setting.name: value for setting, value in set_defaults.items()},\n                **self.dict(exclude_unset=True, exclude=restore_defaults_names),\n                **{setting.name: value for setting, value in updates.items()},\n            }\n        )\n\n    def with_obfuscated_secrets(self):\n        \"\"\"\n        Returns a copy of this settings object with secret setting values obfuscated.\n        \"\"\"\n        settings = self.copy(\n            update={\n                setting.name: obfuscate(self.value_of(setting))\n                for setting in SETTING_VARIABLES.values()\n                if setting.is_secret\n                # Exclude deprecated settings with null values to avoid warnings\n                and not (setting.deprecated and self.value_of(setting) is None)\n            }\n        )\n        # Ensure that settings that have not been marked as \"set\" before are still so\n        # after we have updated their value above\n        settings.__fields_set__.intersection_update(self.__fields_set__)\n        return settings\n\n    def hash_key(self) -&gt; str:\n        \"\"\"\n        Return a hash key for the settings object.  This is needed since some\n        settings may be unhashable.  An example is lists.\n        \"\"\"\n        env_variables = self.to_environment_variables()\n        return str(hash(tuple((key, value) for key, value in env_variables.items())))\n\n    def to_environment_variables(\n        self, include: Iterable[Setting] = None, exclude_unset: bool = False\n    ) -&gt; Dict[str, str]:\n        \"\"\"\n        Convert the settings object to environment variables.\n\n        Note that setting values will not be run through their `value_callback` allowing\n        dynamic resolution to occur when loaded from the returned environment.\n\n        Args:\n            include_keys: An iterable of settings to include in the return value.\n                If not set, all settings are used.\n            exclude_unset: Only include settings that have been set (i.e. the value is\n                not from the default). If set, unset keys will be dropped even if they\n                are set in `include_keys`.\n\n        Returns:\n            A dictionary of settings with values cast to strings\n        \"\"\"\n        include = set(include or SETTING_VARIABLES.values())\n\n        if exclude_unset:\n            set_keys = {\n                # Collect all of the \"set\" keys and cast to `Setting` objects\n                SETTING_VARIABLES[key]\n                for key in self.dict(exclude_unset=True)\n            }\n            include.intersection_update(set_keys)\n\n        # Validate the types of items in `include` to prevent exclusion bugs\n        for key in include:\n            if not isinstance(key, Setting):\n                raise TypeError(\n                    \"Invalid type {type(key).__name__!r} for key in `include`.\"\n                )\n\n        env = {\n            # Use `getattr` instead of `value_of` to avoid value callback resolution\n            key: getattr(self, key)\n            for key, setting in SETTING_VARIABLES.items()\n            if setting in include\n        }\n\n        # Cast to strings and drop null values\n        return {key: str(value) for key, value in env.items() if value is not None}\n\n    class Config:\n        frozen = True\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.value_of","title":"<code>value_of</code>","text":"<p>Retrieve a setting's value.</p> Source code in <code>prefect/settings.py</code> <pre><code>def value_of(self, setting: Setting[T], bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Retrieve a setting's value.\n    \"\"\"\n    value = getattr(self, setting.name)\n    if setting.value_callback and not bypass_callback:\n        value = setting.value_callback(self, value)\n    return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.post_root_validators","title":"<code>post_root_validators</code>","text":"<p>Add root validation functions for settings here.</p> Source code in <code>prefect/settings.py</code> <pre><code>@root_validator\ndef post_root_validators(cls, values):\n    \"\"\"\n    Add root validation functions for settings here.\n    \"\"\"\n    # TODO: We could probably register these dynamically but this is the simpler\n    #       approach for now. We can explore more interesting validation features\n    #       in the future.\n    values = max_log_size_smaller_than_batch_size(values)\n    values = warn_on_database_password_value_without_usage(values)\n    if not values[\"PREFECT_SILENCE_API_URL_MISCONFIGURATION\"]:\n        values = warn_on_misconfigured_api_url(values)\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.with_obfuscated_secrets","title":"<code>with_obfuscated_secrets</code>","text":"<p>Returns a copy of this settings object with secret setting values obfuscated.</p> Source code in <code>prefect/settings.py</code> <pre><code>def with_obfuscated_secrets(self):\n    \"\"\"\n    Returns a copy of this settings object with secret setting values obfuscated.\n    \"\"\"\n    settings = self.copy(\n        update={\n            setting.name: obfuscate(self.value_of(setting))\n            for setting in SETTING_VARIABLES.values()\n            if setting.is_secret\n            # Exclude deprecated settings with null values to avoid warnings\n            and not (setting.deprecated and self.value_of(setting) is None)\n        }\n    )\n    # Ensure that settings that have not been marked as \"set\" before are still so\n    # after we have updated their value above\n    settings.__fields_set__.intersection_update(self.__fields_set__)\n    return settings\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.hash_key","title":"<code>hash_key</code>","text":"<p>Return a hash key for the settings object.  This is needed since some settings may be unhashable.  An example is lists.</p> Source code in <code>prefect/settings.py</code> <pre><code>def hash_key(self) -&gt; str:\n    \"\"\"\n    Return a hash key for the settings object.  This is needed since some\n    settings may be unhashable.  An example is lists.\n    \"\"\"\n    env_variables = self.to_environment_variables()\n    return str(hash(tuple((key, value) for key, value in env_variables.items())))\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.to_environment_variables","title":"<code>to_environment_variables</code>","text":"<p>Convert the settings object to environment variables.</p> <p>Note that setting values will not be run through their <code>value_callback</code> allowing dynamic resolution to occur when loaded from the returned environment.</p> <p>Parameters:</p> Name Type Description Default <code>include_keys</code> <p>An iterable of settings to include in the return value. If not set, all settings are used.</p> required <code>exclude_unset</code> <code>bool</code> <p>Only include settings that have been set (i.e. the value is not from the default). If set, unset keys will be dropped even if they are set in <code>include_keys</code>.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dictionary of settings with values cast to strings</p> Source code in <code>prefect/settings.py</code> <pre><code>def to_environment_variables(\n    self, include: Iterable[Setting] = None, exclude_unset: bool = False\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Convert the settings object to environment variables.\n\n    Note that setting values will not be run through their `value_callback` allowing\n    dynamic resolution to occur when loaded from the returned environment.\n\n    Args:\n        include_keys: An iterable of settings to include in the return value.\n            If not set, all settings are used.\n        exclude_unset: Only include settings that have been set (i.e. the value is\n            not from the default). If set, unset keys will be dropped even if they\n            are set in `include_keys`.\n\n    Returns:\n        A dictionary of settings with values cast to strings\n    \"\"\"\n    include = set(include or SETTING_VARIABLES.values())\n\n    if exclude_unset:\n        set_keys = {\n            # Collect all of the \"set\" keys and cast to `Setting` objects\n            SETTING_VARIABLES[key]\n            for key in self.dict(exclude_unset=True)\n        }\n        include.intersection_update(set_keys)\n\n    # Validate the types of items in `include` to prevent exclusion bugs\n    for key in include:\n        if not isinstance(key, Setting):\n            raise TypeError(\n                \"Invalid type {type(key).__name__!r} for key in `include`.\"\n            )\n\n    env = {\n        # Use `getattr` instead of `value_of` to avoid value callback resolution\n        key: getattr(self, key)\n        for key, setting in SETTING_VARIABLES.items()\n        if setting in include\n    }\n\n    # Cast to strings and drop null values\n    return {key: str(value) for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile","title":"<code>Profile</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A user profile containing settings.</p> Source code in <code>prefect/settings.py</code> <pre><code>class Profile(BaseModel):\n    \"\"\"\n    A user profile containing settings.\n    \"\"\"\n\n    name: str\n    settings: Dict[Setting, Any] = Field(default_factory=dict)\n    source: Optional[Path]\n\n    @validator(\"settings\", pre=True)\n    def map_names_to_settings(cls, value):\n        return validate_settings(value)\n\n    def validate_settings(self) -&gt; None:\n        \"\"\"\n        Validate the settings contained in this profile.\n\n        Raises:\n            pydantic.ValidationError: When settings do not have valid values.\n        \"\"\"\n        # Create a new `Settings` instance with the settings from this profile relying\n        # on Pydantic validation to raise an error.\n        # We do not return the `Settings` object because this is not the recommended\n        # path for constructing settings with a profile. See `use_profile` instead.\n        Settings(**{setting.name: value for setting, value in self.settings.items()})\n\n    def convert_deprecated_renamed_settings(self) -&gt; List[Tuple[Setting, Setting]]:\n        \"\"\"\n        Update settings in place to replace deprecated settings with new settings when\n        renamed.\n\n        Returns a list of tuples with the old and new setting.\n        \"\"\"\n        changed = []\n        for setting in tuple(self.settings):\n            if (\n                setting.deprecated\n                and setting.deprecated_renamed_to\n                and setting.deprecated_renamed_to not in self.settings\n            ):\n                self.settings[setting.deprecated_renamed_to] = self.settings.pop(\n                    setting\n                )\n                changed.append((setting, setting.deprecated_renamed_to))\n        return changed\n\n    class Config:\n        arbitrary_types_allowed = True\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile.validate_settings","title":"<code>validate_settings</code>","text":"<p>Validate the settings contained in this profile.</p> <p>Raises:</p> Type Description <code>ValidationError</code> <p>When settings do not have valid values.</p> Source code in <code>prefect/settings.py</code> <pre><code>def validate_settings(self) -&gt; None:\n    \"\"\"\n    Validate the settings contained in this profile.\n\n    Raises:\n        pydantic.ValidationError: When settings do not have valid values.\n    \"\"\"\n    # Create a new `Settings` instance with the settings from this profile relying\n    # on Pydantic validation to raise an error.\n    # We do not return the `Settings` object because this is not the recommended\n    # path for constructing settings with a profile. See `use_profile` instead.\n    Settings(**{setting.name: value for setting, value in self.settings.items()})\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile.convert_deprecated_renamed_settings","title":"<code>convert_deprecated_renamed_settings</code>","text":"<p>Update settings in place to replace deprecated settings with new settings when renamed.</p> <p>Returns a list of tuples with the old and new setting.</p> Source code in <code>prefect/settings.py</code> <pre><code>def convert_deprecated_renamed_settings(self) -&gt; List[Tuple[Setting, Setting]]:\n    \"\"\"\n    Update settings in place to replace deprecated settings with new settings when\n    renamed.\n\n    Returns a list of tuples with the old and new setting.\n    \"\"\"\n    changed = []\n    for setting in tuple(self.settings):\n        if (\n            setting.deprecated\n            and setting.deprecated_renamed_to\n            and setting.deprecated_renamed_to not in self.settings\n        ):\n            self.settings[setting.deprecated_renamed_to] = self.settings.pop(\n                setting\n            )\n            changed.append((setting, setting.deprecated_renamed_to))\n    return changed\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection","title":"<code>ProfilesCollection</code>","text":"<p>\" A utility class for working with a collection of profiles.</p> <p>Profiles in the collection must have unique names.</p> <p>The collection may store the name of the active profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>class ProfilesCollection:\n    \"\"\" \"\n    A utility class for working with a collection of profiles.\n\n    Profiles in the collection must have unique names.\n\n    The collection may store the name of the active profile.\n    \"\"\"\n\n    def __init__(\n        self, profiles: Iterable[Profile], active: Optional[str] = None\n    ) -&gt; None:\n        self.profiles_by_name = {profile.name: profile for profile in profiles}\n        self.active_name = active\n\n    @property\n    def names(self) -&gt; Set[str]:\n        \"\"\"\n        Return a set of profile names in this collection.\n        \"\"\"\n        return set(self.profiles_by_name.keys())\n\n    @property\n    def active_profile(self) -&gt; Optional[Profile]:\n        \"\"\"\n        Retrieve the active profile in this collection.\n        \"\"\"\n        if self.active_name is None:\n            return None\n        return self[self.active_name]\n\n    def set_active(self, name: Optional[str], check: bool = True):\n        \"\"\"\n        Set the active profile name in the collection.\n\n        A null value may be passed to indicate that this collection does not determine\n        the active profile.\n        \"\"\"\n        if check and name is not None and name not in self.names:\n            raise ValueError(f\"Unknown profile name {name!r}.\")\n        self.active_name = name\n\n    def update_profile(\n        self, name: str, settings: Mapping[Union[Dict, str], Any], source: Path = None\n    ) -&gt; Profile:\n        \"\"\"\n        Add a profile to the collection or update the existing on if the name is already\n        present in this collection.\n\n        If updating an existing profile, the settings will be merged. Settings can\n        be dropped from the existing profile by setting them to `None` in the new\n        profile.\n\n        Returns the new profile object.\n        \"\"\"\n        existing = self.profiles_by_name.get(name)\n\n        # Convert the input to a `Profile` to cast settings to the correct type\n        profile = Profile(name=name, settings=settings, source=source)\n\n        if existing:\n            new_settings = {**existing.settings, **profile.settings}\n\n            # Drop null keys to restore to default\n            for key, value in tuple(new_settings.items()):\n                if value is None:\n                    new_settings.pop(key)\n\n            new_profile = Profile(\n                name=profile.name,\n                settings=new_settings,\n                source=source or profile.source,\n            )\n        else:\n            new_profile = profile\n\n        self.profiles_by_name[new_profile.name] = new_profile\n\n        return new_profile\n\n    def add_profile(self, profile: Profile) -&gt; None:\n        \"\"\"\n        Add a profile to the collection.\n\n        If the profile name already exists, an exception will be raised.\n        \"\"\"\n        if profile.name in self.profiles_by_name:\n            raise ValueError(\n                f\"Profile name {profile.name!r} already exists in collection.\"\n            )\n\n        self.profiles_by_name[profile.name] = profile\n\n    def remove_profile(self, name: str) -&gt; None:\n        \"\"\"\n        Remove a profile from the collection.\n        \"\"\"\n        self.profiles_by_name.pop(name)\n\n    def without_profile_source(self, path: Optional[Path]) -&gt; \"ProfilesCollection\":\n        \"\"\"\n        Remove profiles that were loaded from a given path.\n\n        Returns a new collection.\n        \"\"\"\n        return ProfilesCollection(\n            [\n                profile\n                for profile in self.profiles_by_name.values()\n                if profile.source != path\n            ],\n            active=self.active_name,\n        )\n\n    def to_dict(self):\n        \"\"\"\n        Convert to a dictionary suitable for writing to disk.\n        \"\"\"\n        return {\n            \"active\": self.active_name,\n            \"profiles\": {\n                profile.name: {\n                    setting.name: value for setting, value in profile.settings.items()\n                }\n                for profile in self.profiles_by_name.values()\n            },\n        }\n\n    def __getitem__(self, name: str) -&gt; Profile:\n        return self.profiles_by_name[name]\n\n    def __iter__(self):\n        return self.profiles_by_name.__iter__()\n\n    def items(self):\n        return self.profiles_by_name.items()\n\n    def __eq__(self, __o: object) -&gt; bool:\n        if not isinstance(__o, ProfilesCollection):\n            return False\n\n        return (\n            self.profiles_by_name == __o.profiles_by_name\n            and self.active_name == __o.active_name\n        )\n\n    def __repr__(self) -&gt; str:\n        return (\n            f\"ProfilesCollection(profiles={list(self.profiles_by_name.values())!r},\"\n            f\" active={self.active_name!r})&gt;\"\n        )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.names","title":"<code>names: Set[str]</code>  <code>property</code>","text":"<p>Return a set of profile names in this collection.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.active_profile","title":"<code>active_profile: Optional[Profile]</code>  <code>property</code>","text":"<p>Retrieve the active profile in this collection.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.set_active","title":"<code>set_active</code>","text":"<p>Set the active profile name in the collection.</p> <p>A null value may be passed to indicate that this collection does not determine the active profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>def set_active(self, name: Optional[str], check: bool = True):\n    \"\"\"\n    Set the active profile name in the collection.\n\n    A null value may be passed to indicate that this collection does not determine\n    the active profile.\n    \"\"\"\n    if check and name is not None and name not in self.names:\n        raise ValueError(f\"Unknown profile name {name!r}.\")\n    self.active_name = name\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.update_profile","title":"<code>update_profile</code>","text":"<p>Add a profile to the collection or update the existing on if the name is already present in this collection.</p> <p>If updating an existing profile, the settings will be merged. Settings can be dropped from the existing profile by setting them to <code>None</code> in the new profile.</p> <p>Returns the new profile object.</p> Source code in <code>prefect/settings.py</code> <pre><code>def update_profile(\n    self, name: str, settings: Mapping[Union[Dict, str], Any], source: Path = None\n) -&gt; Profile:\n    \"\"\"\n    Add a profile to the collection or update the existing on if the name is already\n    present in this collection.\n\n    If updating an existing profile, the settings will be merged. Settings can\n    be dropped from the existing profile by setting them to `None` in the new\n    profile.\n\n    Returns the new profile object.\n    \"\"\"\n    existing = self.profiles_by_name.get(name)\n\n    # Convert the input to a `Profile` to cast settings to the correct type\n    profile = Profile(name=name, settings=settings, source=source)\n\n    if existing:\n        new_settings = {**existing.settings, **profile.settings}\n\n        # Drop null keys to restore to default\n        for key, value in tuple(new_settings.items()):\n            if value is None:\n                new_settings.pop(key)\n\n        new_profile = Profile(\n            name=profile.name,\n            settings=new_settings,\n            source=source or profile.source,\n        )\n    else:\n        new_profile = profile\n\n    self.profiles_by_name[new_profile.name] = new_profile\n\n    return new_profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.add_profile","title":"<code>add_profile</code>","text":"<p>Add a profile to the collection.</p> <p>If the profile name already exists, an exception will be raised.</p> Source code in <code>prefect/settings.py</code> <pre><code>def add_profile(self, profile: Profile) -&gt; None:\n    \"\"\"\n    Add a profile to the collection.\n\n    If the profile name already exists, an exception will be raised.\n    \"\"\"\n    if profile.name in self.profiles_by_name:\n        raise ValueError(\n            f\"Profile name {profile.name!r} already exists in collection.\"\n        )\n\n    self.profiles_by_name[profile.name] = profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.remove_profile","title":"<code>remove_profile</code>","text":"<p>Remove a profile from the collection.</p> Source code in <code>prefect/settings.py</code> <pre><code>def remove_profile(self, name: str) -&gt; None:\n    \"\"\"\n    Remove a profile from the collection.\n    \"\"\"\n    self.profiles_by_name.pop(name)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.without_profile_source","title":"<code>without_profile_source</code>","text":"<p>Remove profiles that were loaded from a given path.</p> <p>Returns a new collection.</p> Source code in <code>prefect/settings.py</code> <pre><code>def without_profile_source(self, path: Optional[Path]) -&gt; \"ProfilesCollection\":\n    \"\"\"\n    Remove profiles that were loaded from a given path.\n\n    Returns a new collection.\n    \"\"\"\n    return ProfilesCollection(\n        [\n            profile\n            for profile in self.profiles_by_name.values()\n            if profile.source != path\n        ],\n        active=self.active_name,\n    )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_extra_loggers","title":"<code>get_extra_loggers</code>","text":"<p><code>value_callback</code> for <code>PREFECT_LOGGING_EXTRA_LOGGERS</code>that parses the CSV string into a list and trims whitespace from logger names.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_extra_loggers(_: \"Settings\", value: str) -&gt; List[str]:\n    \"\"\"\n    `value_callback` for `PREFECT_LOGGING_EXTRA_LOGGERS`that parses the CSV string into a\n    list and trims whitespace from logger names.\n    \"\"\"\n    return [name.strip() for name in value.split(\",\")] if value else []\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.debug_mode_log_level","title":"<code>debug_mode_log_level</code>","text":"<p><code>value_callback</code> for <code>PREFECT_LOGGING_LEVEL</code> that overrides the log level to DEBUG when debug mode is enabled.</p> Source code in <code>prefect/settings.py</code> <pre><code>def debug_mode_log_level(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_LOGGING_LEVEL` that overrides the log level to DEBUG\n    when debug mode is enabled.\n    \"\"\"\n    if PREFECT_DEBUG_MODE.value_from(settings):\n        return \"DEBUG\"\n    else:\n        return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.only_return_value_in_test_mode","title":"<code>only_return_value_in_test_mode</code>","text":"<p><code>value_callback</code> for <code>PREFECT_TEST_SETTING</code> that only allows access during test mode</p> Source code in <code>prefect/settings.py</code> <pre><code>def only_return_value_in_test_mode(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_TEST_SETTING` that only allows access during test mode\n    \"\"\"\n    if PREFECT_TEST_MODE.value_from(settings):\n        return value\n    else:\n        return None\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.default_ui_api_url","title":"<code>default_ui_api_url</code>","text":"<p><code>value_callback</code> for <code>PREFECT_UI_API_URL</code> that sets the default value to relative path '/api', otherwise it constructs an API URL from the API settings.</p> Source code in <code>prefect/settings.py</code> <pre><code>def default_ui_api_url(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_UI_API_URL` that sets the default value to\n    relative path '/api', otherwise it constructs an API URL from the API settings.\n    \"\"\"\n    if value is None:\n        # Set a default value\n        value = \"/api\"\n\n    return template_with_settings(\n        PREFECT_SERVER_API_HOST, PREFECT_SERVER_API_PORT, PREFECT_API_URL\n    )(settings, value)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.status_codes_as_integers_in_range","title":"<code>status_codes_as_integers_in_range</code>","text":"<p><code>value_callback</code> for <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> that ensures status codes are integers in the range 100-599.</p> Source code in <code>prefect/settings.py</code> <pre><code>def status_codes_as_integers_in_range(_, value):\n    \"\"\"\n    `value_callback` for `PREFECT_CLIENT_RETRY_EXTRA_CODES` that ensures status codes\n    are integers in the range 100-599.\n    \"\"\"\n    if value == \"\":\n        return set()\n\n    values = {v.strip() for v in value.split(\",\")}\n\n    if any(not v.isdigit() or int(v) &lt; 100 or int(v) &gt; 599 for v in values):\n        raise ValueError(\n            \"PREFECT_CLIENT_RETRY_EXTRA_CODES must be a comma separated list of \"\n            \"integers between 100 and 599.\"\n        )\n\n    values = {int(v) for v in values}\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.template_with_settings","title":"<code>template_with_settings</code>","text":"<p>Returns a <code>value_callback</code> that will template the given settings into the runtime value for the setting.</p> Source code in <code>prefect/settings.py</code> <pre><code>def template_with_settings(*upstream_settings: Setting) -&gt; Callable[[\"Settings\", T], T]:\n    \"\"\"\n    Returns a `value_callback` that will template the given settings into the runtime\n    value for the setting.\n    \"\"\"\n\n    def templater(settings, value):\n        if value is None:\n            return value  # Do not attempt to template a null string\n\n        original_type = type(value)\n        template_values = {\n            setting.name: setting.value_from(settings) for setting in upstream_settings\n        }\n        template = string.Template(str(value))\n        # Note the use of `safe_substitute` to avoid raising an exception if a\n        # template value is missing. In this case, template values will be left\n        # as-is in the string. Using `safe_substitute` prevents us raising when\n        # the DB password contains a `$` character.\n        return original_type(template.safe_substitute(template_values))\n\n    return templater\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.max_log_size_smaller_than_batch_size","title":"<code>max_log_size_smaller_than_batch_size</code>","text":"<p>Validator for settings asserting the batch size and match log size are compatible</p> Source code in <code>prefect/settings.py</code> <pre><code>def max_log_size_smaller_than_batch_size(values):\n    \"\"\"\n    Validator for settings asserting the batch size and match log size are compatible\n    \"\"\"\n    if (\n        values[\"PREFECT_LOGGING_TO_API_BATCH_SIZE\"]\n        &lt; values[\"PREFECT_LOGGING_TO_API_MAX_LOG_SIZE\"]\n    ):\n        raise ValueError(\n            \"`PREFECT_LOGGING_TO_API_MAX_LOG_SIZE` cannot be larger than\"\n            \" `PREFECT_LOGGING_TO_API_BATCH_SIZE`\"\n        )\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.warn_on_database_password_value_without_usage","title":"<code>warn_on_database_password_value_without_usage</code>","text":"<p>Validator for settings warning if the database password is set but not used.</p> Source code in <code>prefect/settings.py</code> <pre><code>def warn_on_database_password_value_without_usage(values):\n    \"\"\"\n    Validator for settings warning if the database password is set but not used.\n    \"\"\"\n    value = values[\"PREFECT_API_DATABASE_PASSWORD\"]\n    if (\n        value\n        and not value.startswith(OBFUSCATED_PREFIX)\n        and (\n            \"PREFECT_API_DATABASE_PASSWORD\"\n            not in values[\"PREFECT_API_DATABASE_CONNECTION_URL\"]\n        )\n    ):\n        warnings.warn(\n            \"PREFECT_API_DATABASE_PASSWORD is set but not included in the \"\n            \"PREFECT_API_DATABASE_CONNECTION_URL. \"\n            \"The provided password will be ignored.\"\n        )\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.warn_on_misconfigured_api_url","title":"<code>warn_on_misconfigured_api_url</code>","text":"<p>Validator for settings warning if the API URL is misconfigured.</p> Source code in <code>prefect/settings.py</code> <pre><code>def warn_on_misconfigured_api_url(values):\n    \"\"\"\n    Validator for settings warning if the API URL is misconfigured.\n    \"\"\"\n    api_url = values[\"PREFECT_API_URL\"]\n    if api_url is not None:\n        misconfigured_mappings = {\n            \"app.prefect.cloud\": (\n                \"`PREFECT_API_URL` points to `app.prefect.cloud`. Did you\"\n                \" mean `api.prefect.cloud`?\"\n            ),\n            \"account/\": (\n                \"`PREFECT_API_URL` uses `/account/` but should use `/accounts/`.\"\n            ),\n            \"workspace/\": (\n                \"`PREFECT_API_URL` uses `/workspace/` but should use `/workspaces/`.\"\n            ),\n        }\n        warnings_list = []\n\n        for misconfig, warning in misconfigured_mappings.items():\n            if misconfig in api_url:\n                warnings_list.append(warning)\n\n        parsed_url = urlparse(api_url)\n        if parsed_url.path and not parsed_url.path.startswith(\"/api\"):\n            warnings_list.append(\n                \"`PREFECT_API_URL` should have `/api` after the base URL.\"\n            )\n\n        if warnings_list:\n            example = 'e.g. PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"'\n            warnings_list.append(example)\n\n            warnings.warn(\"\\n\".join(warnings_list), stacklevel=2)\n\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.automation_settings_enabled","title":"<code>automation_settings_enabled</code>","text":"<p>Whether or not automations are enabled.</p> Source code in <code>prefect/settings.py</code> <pre><code>def automation_settings_enabled() -&gt; bool:\n    \"\"\"\n    Whether or not automations are enabled.\n    \"\"\"\n    return (\n        PREFECT_EXPERIMENTAL_EVENTS.value()\n        and PREFECT_API_SERVICES_TRIGGERS_ENABLED.value()\n    )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_current_settings","title":"<code>get_current_settings</code>","text":"<p>Returns a settings object populated with values from the current settings context or, if no settings context is active, the environment.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_current_settings() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with values from the current settings context\n    or, if no settings context is active, the environment.\n    \"\"\"\n    from prefect.context import SettingsContext\n\n    settings_context = SettingsContext.get()\n    if settings_context is not None:\n        return settings_context.settings\n\n    return get_settings_from_env()\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_settings_from_env","title":"<code>get_settings_from_env</code>","text":"<p>Returns a settings object populated with default values and overrides from environment variables, ignoring any values in profiles.</p> <p>Calls with the same environment return a cached object instead of reconstructing to avoid validation overhead.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_settings_from_env() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with default values and overrides from\n    environment variables, ignoring any values in profiles.\n\n    Calls with the same environment return a cached object instead of reconstructing\n    to avoid validation overhead.\n    \"\"\"\n    # Since os.environ is a Dict[str, str] we can safely hash it by contents, but we\n    # must be careful to avoid hashing a generator instead of a tuple\n    cache_key = hash(tuple((key, value) for key, value in os.environ.items()))\n\n    if cache_key not in _FROM_ENV_CACHE:\n        _FROM_ENV_CACHE[cache_key] = Settings()\n\n    return _FROM_ENV_CACHE[cache_key]\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_default_settings","title":"<code>get_default_settings</code>","text":"<p>Returns a settings object populated with default values, ignoring any overrides from environment variables or profiles.</p> <p>This is cached since the defaults should not change during the lifetime of the module.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_default_settings() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with default values, ignoring any overrides\n    from environment variables or profiles.\n\n    This is cached since the defaults should not change during the lifetime of the\n    module.\n    \"\"\"\n    global _DEFAULTS_CACHE\n\n    if not _DEFAULTS_CACHE:\n        old = os.environ\n        try:\n            os.environ = {}\n            settings = get_settings_from_env()\n        finally:\n            os.environ = old\n\n        _DEFAULTS_CACHE = settings\n\n    return _DEFAULTS_CACHE\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.temporary_settings","title":"<code>temporary_settings</code>","text":"<p>Temporarily override the current settings by entering a new profile.</p> <p>See <code>Settings.copy_with_update</code> for details on different argument behavior.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect.settings import PREFECT_API_URL\n&gt;&gt;&gt;\n&gt;&gt;&gt; with temporary_settings(updates={PREFECT_API_URL: \"foo\"}):\n&gt;&gt;&gt;    assert PREFECT_API_URL.value() == \"foo\"\n&gt;&gt;&gt;\n&gt;&gt;&gt;    with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"}):\n&gt;&gt;&gt;         assert PREFECT_API_URL.value() == \"foo\"\n&gt;&gt;&gt;\n&gt;&gt;&gt;    with temporary_settings(restore_defaults={PREFECT_API_URL}):\n&gt;&gt;&gt;         assert PREFECT_API_URL.value() is None\n&gt;&gt;&gt;\n&gt;&gt;&gt;         with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"})\n&gt;&gt;&gt;             assert PREFECT_API_URL.value() == \"bar\"\n&gt;&gt;&gt; assert PREFECT_API_URL.value() is None\n</code></pre> Source code in <code>prefect/settings.py</code> <pre><code>@contextmanager\ndef temporary_settings(\n    updates: Optional[Mapping[Setting[T], Any]] = None,\n    set_defaults: Optional[Mapping[Setting[T], Any]] = None,\n    restore_defaults: Optional[Iterable[Setting[T]]] = None,\n) -&gt; Generator[Settings, None, None]:\n    \"\"\"\n    Temporarily override the current settings by entering a new profile.\n\n    See `Settings.copy_with_update` for details on different argument behavior.\n\n    Examples:\n        &gt;&gt;&gt; from prefect.settings import PREFECT_API_URL\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; with temporary_settings(updates={PREFECT_API_URL: \"foo\"}):\n        &gt;&gt;&gt;    assert PREFECT_API_URL.value() == \"foo\"\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;    with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"}):\n        &gt;&gt;&gt;         assert PREFECT_API_URL.value() == \"foo\"\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;    with temporary_settings(restore_defaults={PREFECT_API_URL}):\n        &gt;&gt;&gt;         assert PREFECT_API_URL.value() is None\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;         with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"})\n        &gt;&gt;&gt;             assert PREFECT_API_URL.value() == \"bar\"\n        &gt;&gt;&gt; assert PREFECT_API_URL.value() is None\n    \"\"\"\n    import prefect.context\n\n    context = prefect.context.get_settings_context()\n\n    new_settings = context.settings.copy_with_update(\n        updates=updates, set_defaults=set_defaults, restore_defaults=restore_defaults\n    )\n\n    with prefect.context.SettingsContext(\n        profile=context.profile, settings=new_settings\n    ):\n        yield new_settings\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_profiles","title":"<code>load_profiles</code>","text":"<p>Load all profiles from the default and current profile paths.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_profiles() -&gt; ProfilesCollection:\n    \"\"\"\n    Load all profiles from the default and current profile paths.\n    \"\"\"\n    profiles = _read_profiles_from(DEFAULT_PROFILES_PATH)\n\n    user_profiles_path = PREFECT_PROFILES_PATH.value()\n    if user_profiles_path.exists():\n        user_profiles = _read_profiles_from(user_profiles_path)\n\n        # Merge all of the user profiles with the defaults\n        for name in user_profiles:\n            profiles.update_profile(\n                name,\n                settings=user_profiles[name].settings,\n                source=user_profiles[name].source,\n            )\n\n        if user_profiles.active_name:\n            profiles.set_active(user_profiles.active_name, check=False)\n\n    return profiles\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_current_profile","title":"<code>load_current_profile</code>","text":"<p>Load the current profile from the default and current profile paths.</p> <p>This will not include settings from the current settings context. Only settings that have been persisted to the profiles file will be saved.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_current_profile():\n    \"\"\"\n    Load the current profile from the default and current profile paths.\n\n    This will _not_ include settings from the current settings context. Only settings\n    that have been persisted to the profiles file will be saved.\n    \"\"\"\n    from prefect.context import SettingsContext\n\n    profiles = load_profiles()\n    context = SettingsContext.get()\n\n    if context:\n        profiles.set_active(context.profile.name)\n\n    return profiles.active_profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.save_profiles","title":"<code>save_profiles</code>","text":"<p>Writes all non-default profiles to the current profiles path.</p> Source code in <code>prefect/settings.py</code> <pre><code>def save_profiles(profiles: ProfilesCollection) -&gt; None:\n    \"\"\"\n    Writes all non-default profiles to the current profiles path.\n    \"\"\"\n    profiles_path = PREFECT_PROFILES_PATH.value()\n    profiles = profiles.without_profile_source(DEFAULT_PROFILES_PATH)\n    return _write_profiles_to(profiles_path, profiles)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_profile","title":"<code>load_profile</code>","text":"<p>Load a single profile by name.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_profile(name: str) -&gt; Profile:\n    \"\"\"\n    Load a single profile by name.\n    \"\"\"\n    profiles = load_profiles()\n    try:\n        return profiles[name]\n    except KeyError:\n        raise ValueError(f\"Profile {name!r} not found.\")\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.update_current_profile","title":"<code>update_current_profile</code>","text":"<p>Update the persisted data for the profile currently in-use.</p> <p>If the profile does not exist in the profiles file, it will be created.</p> <p>Given settings will be merged with the existing settings as described in <code>ProfilesCollection.update_profile</code>.</p> <p>Returns:</p> Type Description <code>Profile</code> <p>The new profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>def update_current_profile(settings: Dict[Union[str, Setting], Any]) -&gt; Profile:\n    \"\"\"\n    Update the persisted data for the profile currently in-use.\n\n    If the profile does not exist in the profiles file, it will be created.\n\n    Given settings will be merged with the existing settings as described in\n    `ProfilesCollection.update_profile`.\n\n    Returns:\n        The new profile.\n    \"\"\"\n    import prefect.context\n\n    current_profile = prefect.context.get_settings_context().profile\n\n    if not current_profile:\n        raise MissingProfileError(\"No profile is currently in use.\")\n\n    profiles = load_profiles()\n\n    # Ensure the current profile's settings are present\n    profiles.update_profile(current_profile.name, current_profile.settings)\n    # Then merge the new settings in\n    new_profile = profiles.update_profile(current_profile.name, settings)\n\n    # Validate before saving\n    new_profile.validate_settings()\n\n    save_profiles(profiles)\n\n    return profiles[current_profile.name]\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/software/","title":"prefect.software","text":"","tags":["Python API","software"]},{"location":"api-ref/prefect/software/#prefect.software","title":"<code>prefect.software</code>","text":"","tags":["Python API","software"]},{"location":"api-ref/prefect/states/","title":"prefect.states","text":"","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states","title":"<code>prefect.states</code>","text":"","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.AwaitingRetry","title":"<code>AwaitingRetry</code>","text":"<p>Convenience function for creating <code>AwaitingRetry</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a AwaitingRetry state</p> Source code in <code>prefect/states.py</code> <pre><code>def AwaitingRetry(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `AwaitingRetry` states.\n\n    Returns:\n        State: a AwaitingRetry state\n    \"\"\"\n    return Scheduled(\n        cls=cls, scheduled_time=scheduled_time, name=\"AwaitingRetry\", **kwargs\n    )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Cancelled","title":"<code>Cancelled</code>","text":"<p>Convenience function for creating <code>Cancelled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Cancelled state</p> Source code in <code>prefect/states.py</code> <pre><code>def Cancelled(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Cancelled` states.\n\n    Returns:\n        State: a Cancelled state\n    \"\"\"\n    return cls(type=StateType.CANCELLED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Cancelling","title":"<code>Cancelling</code>","text":"<p>Convenience function for creating <code>Cancelling</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Cancelling state</p> Source code in <code>prefect/states.py</code> <pre><code>def Cancelling(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Cancelling` states.\n\n    Returns:\n        State: a Cancelling state\n    \"\"\"\n    return cls(type=StateType.CANCELLING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Completed","title":"<code>Completed</code>","text":"<p>Convenience function for creating <code>Completed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Completed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Completed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Completed` states.\n\n    Returns:\n        State: a Completed state\n    \"\"\"\n    return cls(type=StateType.COMPLETED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Crashed","title":"<code>Crashed</code>","text":"<p>Convenience function for creating <code>Crashed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Crashed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Crashed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Crashed` states.\n\n    Returns:\n        State: a Crashed state\n    \"\"\"\n    return cls(type=StateType.CRASHED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Failed","title":"<code>Failed</code>","text":"<p>Convenience function for creating <code>Failed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Failed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Failed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Failed` states.\n\n    Returns:\n        State: a Failed state\n    \"\"\"\n    return cls(type=StateType.FAILED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Late","title":"<code>Late</code>","text":"<p>Convenience function for creating <code>Late</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Late state</p> Source code in <code>prefect/states.py</code> <pre><code>def Late(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Late` states.\n\n    Returns:\n        State: a Late state\n    \"\"\"\n    return Scheduled(cls=cls, scheduled_time=scheduled_time, name=\"Late\", **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Paused","title":"<code>Paused</code>","text":"<p>Convenience function for creating <code>Paused</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Paused state</p> Source code in <code>prefect/states.py</code> <pre><code>def Paused(\n    cls: Type[State[R]] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    reschedule: bool = False,\n    pause_key: Optional[str] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Paused` states.\n\n    Returns:\n        State: a Paused state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n\n    if state_details.pause_timeout:\n        raise ValueError(\"An extra pause timeout was provided in state_details\")\n\n    if pause_expiration_time is not None and timeout_seconds is not None:\n        raise ValueError(\n            \"Cannot supply both a pause_expiration_time and timeout_seconds\"\n        )\n\n    if pause_expiration_time is None and timeout_seconds is None:\n        pass\n    else:\n        state_details.pause_timeout = pause_expiration_time or (\n            pendulum.now(\"UTC\") + pendulum.Duration(seconds=timeout_seconds)\n        )\n\n    state_details.pause_reschedule = reschedule\n    state_details.pause_key = pause_key\n\n    return cls(type=StateType.PAUSED, state_details=state_details, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Pending","title":"<code>Pending</code>","text":"<p>Convenience function for creating <code>Pending</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Pending state</p> Source code in <code>prefect/states.py</code> <pre><code>def Pending(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Pending` states.\n\n    Returns:\n        State: a Pending state\n    \"\"\"\n    return cls(type=StateType.PENDING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Retrying","title":"<code>Retrying</code>","text":"<p>Convenience function for creating <code>Retrying</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Retrying state</p> Source code in <code>prefect/states.py</code> <pre><code>def Retrying(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Retrying` states.\n\n    Returns:\n        State: a Retrying state\n    \"\"\"\n    return cls(type=StateType.RUNNING, name=\"Retrying\", **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Running","title":"<code>Running</code>","text":"<p>Convenience function for creating <code>Running</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Running state</p> Source code in <code>prefect/states.py</code> <pre><code>def Running(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Running` states.\n\n    Returns:\n        State: a Running state\n    \"\"\"\n    return cls(type=StateType.RUNNING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Scheduled","title":"<code>Scheduled</code>","text":"<p>Convenience function for creating <code>Scheduled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Scheduled state</p> Source code in <code>prefect/states.py</code> <pre><code>def Scheduled(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Scheduled` states.\n\n    Returns:\n        State: a Scheduled state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n    elif state_details.scheduled_time:\n        raise ValueError(\"An extra scheduled_time was provided in state_details\")\n    state_details.scheduled_time = scheduled_time\n\n    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Suspended","title":"<code>Suspended</code>","text":"<p>Convenience function for creating <code>Suspended</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <p>a Suspended state</p> Source code in <code>prefect/states.py</code> <pre><code>def Suspended(\n    cls: Type[State[R]] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    pause_key: Optional[str] = None,\n    **kwargs: Any,\n):\n    \"\"\"Convenience function for creating `Suspended` states.\n\n    Returns:\n        State: a Suspended state\n    \"\"\"\n    return Paused(\n        cls=cls,\n        name=\"Suspended\",\n        reschedule=True,\n        timeout_seconds=timeout_seconds,\n        pause_expiration_time=pause_expiration_time,\n        pause_key=pause_key,\n        **kwargs,\n    )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.exception_to_crashed_state","title":"<code>exception_to_crashed_state</code>  <code>async</code>","text":"<p>Takes an exception that occurs outside of user code and converts it to a 'Crash' exception with a 'Crashed' state.</p> Source code in <code>prefect/states.py</code> <pre><code>async def exception_to_crashed_state(\n    exc: BaseException,\n    result_factory: Optional[ResultFactory] = None,\n) -&gt; State:\n    \"\"\"\n    Takes an exception that occurs _outside_ of user code and converts it to a\n    'Crash' exception with a 'Crashed' state.\n    \"\"\"\n    state_message = None\n\n    if isinstance(exc, anyio.get_cancelled_exc_class()):\n        state_message = \"Execution was cancelled by the runtime environment.\"\n\n    elif isinstance(exc, KeyboardInterrupt):\n        state_message = \"Execution was aborted by an interrupt signal.\"\n\n    elif isinstance(exc, TerminationSignal):\n        state_message = \"Execution was aborted by a termination signal.\"\n\n    elif isinstance(exc, SystemExit):\n        state_message = \"Execution was aborted by Python system exit call.\"\n\n    elif isinstance(exc, (httpx.TimeoutException, httpx.ConnectError)):\n        try:\n            request: httpx.Request = exc.request\n        except RuntimeError:\n            # The request property is not set\n            state_message = (\n                \"Request failed while attempting to contact the server:\"\n                f\" {format_exception(exc)}\"\n            )\n        else:\n            # TODO: We can check if this is actually our API url\n            state_message = f\"Request to {request.url} failed: {format_exception(exc)}.\"\n\n    else:\n        state_message = (\n            \"Execution was interrupted by an unexpected exception:\"\n            f\" {format_exception(exc)}\"\n        )\n\n    if result_factory:\n        data = await result_factory.create_result(exc)\n    else:\n        # Attach the exception for local usage, will not be available when retrieved\n        # from the API\n        data = exc\n\n    return Crashed(message=state_message, data=data)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.exception_to_failed_state","title":"<code>exception_to_failed_state</code>  <code>async</code>","text":"<p>Convenience function for creating <code>Failed</code> states from exceptions</p> Source code in <code>prefect/states.py</code> <pre><code>async def exception_to_failed_state(\n    exc: Optional[BaseException] = None,\n    result_factory: Optional[ResultFactory] = None,\n    **kwargs,\n) -&gt; State:\n    \"\"\"\n    Convenience function for creating `Failed` states from exceptions\n    \"\"\"\n    if not exc:\n        _, exc, _ = sys.exc_info()\n        if exc is None:\n            raise ValueError(\n                \"Exception was not passed and no active exception could be found.\"\n            )\n    else:\n        pass\n\n    if result_factory:\n        data = await result_factory.create_result(exc)\n    else:\n        # Attach the exception for local usage, will not be available when retrieved\n        # from the API\n        data = exc\n\n    existing_message = kwargs.pop(\"message\", \"\")\n    if existing_message and not existing_message.endswith(\" \"):\n        existing_message += \" \"\n\n    # TODO: Consider if we want to include traceback information, it is intentionally\n    #       excluded from messages for now\n    message = existing_message + format_exception(exc)\n\n    return Failed(data=data, message=message, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.get_state_exception","title":"<code>get_state_exception</code>  <code>async</code>","text":"<p>If not given a FAILED or CRASHED state, this raise a value error.</p> <p>If the state result is a state, its exception will be returned.</p> <p>If the state result is an iterable of states, the exception of the first failure will be returned.</p> <p>If the state result is a string, a wrapper exception will be returned with the string as the message.</p> <p>If the state result is null, a wrapper exception will be returned with the state message attached.</p> <p>If the state result is not of a known type, a <code>TypeError</code> will be returned.</p> <p>When a wrapper exception is returned, the type will be:     - <code>FailedRun</code> if the state type is FAILED.     - <code>CrashedRun</code> if the state type is CRASHED.     - <code>CancelledRun</code> if the state type is CANCELLED.</p> Source code in <code>prefect/states.py</code> <pre><code>@sync_compatible\nasync def get_state_exception(state: State) -&gt; BaseException:\n    \"\"\"\n    If not given a FAILED or CRASHED state, this raise a value error.\n\n    If the state result is a state, its exception will be returned.\n\n    If the state result is an iterable of states, the exception of the first failure\n    will be returned.\n\n    If the state result is a string, a wrapper exception will be returned with the\n    string as the message.\n\n    If the state result is null, a wrapper exception will be returned with the state\n    message attached.\n\n    If the state result is not of a known type, a `TypeError` will be returned.\n\n    When a wrapper exception is returned, the type will be:\n        - `FailedRun` if the state type is FAILED.\n        - `CrashedRun` if the state type is CRASHED.\n        - `CancelledRun` if the state type is CANCELLED.\n    \"\"\"\n\n    if state.is_failed():\n        wrapper = FailedRun\n        default_message = \"Run failed.\"\n    elif state.is_crashed():\n        wrapper = CrashedRun\n        default_message = \"Run crashed.\"\n    elif state.is_cancelled():\n        wrapper = CancelledRun\n        default_message = \"Run cancelled.\"\n    else:\n        raise ValueError(f\"Expected failed or crashed state got {state!r}.\")\n\n    if isinstance(state.data, BaseResult):\n        result = await state.data.get()\n    elif state.data is None:\n        result = None\n    else:\n        result = state.data\n\n    if result is None:\n        return wrapper(state.message or default_message)\n\n    if isinstance(result, Exception):\n        return result\n\n    elif isinstance(result, BaseException):\n        return result\n\n    elif isinstance(result, str):\n        return wrapper(result)\n\n    elif is_state(result):\n        # Return the exception from the inner state\n        return await get_state_exception(result)\n\n    elif is_state_iterable(result):\n        # Return the first failure\n        for state in result:\n            if state.is_failed() or state.is_crashed() or state.is_cancelled():\n                return await get_state_exception(state)\n\n        raise ValueError(\n            \"Failed state result was an iterable of states but none were failed.\"\n        )\n\n    else:\n        raise TypeError(\n            f\"Unexpected result for failed state: {result!r} \u2014\u2014 \"\n            f\"{type(result).__name__} cannot be resolved into an exception\"\n        )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.get_state_result","title":"<code>get_state_result</code>","text":"<p>Get the result from a state.</p> <p>See <code>State.result()</code></p> Source code in <code>prefect/states.py</code> <pre><code>def get_state_result(\n    state: State[R], raise_on_failure: bool = True, fetch: Optional[bool] = None\n) -&gt; R:\n    \"\"\"\n    Get the result from a state.\n\n    See `State.result()`\n    \"\"\"\n\n    if fetch is None and (\n        PREFECT_ASYNC_FETCH_STATE_RESULT or not in_async_main_thread()\n    ):\n        # Fetch defaults to `True` for sync users or async users who have opted in\n        fetch = True\n\n    if not fetch:\n        if fetch is None and in_async_main_thread():\n            warnings.warn(\n                (\n                    \"State.result() was called from an async context but not awaited. \"\n                    \"This method will be updated to return a coroutine by default in \"\n                    \"the future. Pass `fetch=True` and `await` the call to get rid of \"\n                    \"this warning.\"\n                ),\n                DeprecationWarning,\n                stacklevel=2,\n            )\n        # Backwards compatibility\n        if isinstance(state.data, DataDocument):\n            return result_from_state_with_data_document(\n                state, raise_on_failure=raise_on_failure\n            )\n        else:\n            return state.data\n    else:\n        return _get_state_result(state, raise_on_failure=raise_on_failure)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.is_state","title":"<code>is_state</code>","text":"<p>Check if the given object is a state instance</p> Source code in <code>prefect/states.py</code> <pre><code>def is_state(obj: Any) -&gt; TypeGuard[State]:\n    \"\"\"\n    Check if the given object is a state instance\n    \"\"\"\n    # We may want to narrow this to client-side state types but for now this provides\n    # backwards compatibility\n    try:\n        from prefect.server.schemas.states import State as State_\n\n        classes_ = (State, State_)\n    except ImportError:\n        classes_ = State\n\n    # return isinstance(obj, (State, State_))\n    return isinstance(obj, classes_)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.is_state_iterable","title":"<code>is_state_iterable</code>","text":"<p>Check if a the given object is an iterable of states types</p> <p>Supported iterables are: - set - list - tuple</p> <p>Other iterables will return <code>False</code> even if they contain states.</p> Source code in <code>prefect/states.py</code> <pre><code>def is_state_iterable(obj: Any) -&gt; TypeGuard[Iterable[State]]:\n    \"\"\"\n    Check if a the given object is an iterable of states types\n\n    Supported iterables are:\n    - set\n    - list\n    - tuple\n\n    Other iterables will return `False` even if they contain states.\n    \"\"\"\n    # We do not check for arbitrary iterables because this is not intended to be used\n    # for things like dictionaries, dataframes, or pydantic models\n    if (\n        not isinstance(obj, BaseAnnotation)\n        and isinstance(obj, (list, set, tuple))\n        and obj\n    ):\n        return all([is_state(o) for o in obj])\n    else:\n        return False\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.raise_state_exception","title":"<code>raise_state_exception</code>  <code>async</code>","text":"<p>Given a FAILED or CRASHED state, raise the contained exception.</p> Source code in <code>prefect/states.py</code> <pre><code>@sync_compatible\nasync def raise_state_exception(state: State) -&gt; None:\n    \"\"\"\n    Given a FAILED or CRASHED state, raise the contained exception.\n    \"\"\"\n    if not (state.is_failed() or state.is_crashed() or state.is_cancelled()):\n        return None\n\n    raise await get_state_exception(state)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.return_value_to_state","title":"<code>return_value_to_state</code>  <code>async</code>","text":"<p>Given a return value from a user's function, create a <code>State</code> the run should be placed in.</p> <ul> <li>If data is returned, we create a 'COMPLETED' state with the data</li> <li>If a single, manually created state is returned, we use that state as given     (manual creation is determined by the lack of ids)</li> <li>If an upstream state or iterable of upstream states is returned, we apply the     aggregate rule</li> </ul> <p>The aggregate rule says that given multiple states we will determine the final state such that:</p> <ul> <li>If any states are not COMPLETED the final state is FAILED</li> <li>If all of the states are COMPLETED the final state is COMPLETED</li> <li>The states will be placed in the final state <code>data</code> attribute</li> </ul> <p>Callers should resolve all futures into states before passing return values to this function.</p> Source code in <code>prefect/states.py</code> <pre><code>async def return_value_to_state(retval: R, result_factory: ResultFactory) -&gt; State[R]:\n    \"\"\"\n    Given a return value from a user's function, create a `State` the run should\n    be placed in.\n\n    - If data is returned, we create a 'COMPLETED' state with the data\n    - If a single, manually created state is returned, we use that state as given\n        (manual creation is determined by the lack of ids)\n    - If an upstream state or iterable of upstream states is returned, we apply the\n        aggregate rule\n\n    The aggregate rule says that given multiple states we will determine the final state\n    such that:\n\n    - If any states are not COMPLETED the final state is FAILED\n    - If all of the states are COMPLETED the final state is COMPLETED\n    - The states will be placed in the final state `data` attribute\n\n    Callers should resolve all futures into states before passing return values to this\n    function.\n    \"\"\"\n\n    if (\n        is_state(retval)\n        # Check for manual creation\n        and not retval.state_details.flow_run_id\n        and not retval.state_details.task_run_id\n    ):\n        state = retval\n\n        # Do not modify states with data documents attached; backwards compatibility\n        if isinstance(state.data, DataDocument):\n            return state\n\n        # Unless the user has already constructed a result explicitly, use the factory\n        # to update the data to the correct type\n        if not isinstance(state.data, BaseResult):\n            state.data = await result_factory.create_result(state.data)\n\n        return state\n\n    # Determine a new state from the aggregate of contained states\n    if is_state(retval) or is_state_iterable(retval):\n        states = StateGroup(ensure_iterable(retval))\n\n        # Determine the new state type\n        if states.all_completed():\n            new_state_type = StateType.COMPLETED\n        elif states.any_cancelled():\n            new_state_type = StateType.CANCELLED\n        elif states.any_paused():\n            new_state_type = StateType.PAUSED\n        else:\n            new_state_type = StateType.FAILED\n\n        # Generate a nice message for the aggregate\n        if states.all_completed():\n            message = \"All states completed.\"\n        elif states.any_cancelled():\n            message = f\"{states.cancelled_count}/{states.total_count} states cancelled.\"\n        elif states.any_paused():\n            message = f\"{states.paused_count}/{states.total_count} states paused.\"\n        elif states.any_failed():\n            message = f\"{states.fail_count}/{states.total_count} states failed.\"\n        elif not states.all_final():\n            message = (\n                f\"{states.not_final_count}/{states.total_count} states are not final.\"\n            )\n        else:\n            message = \"Given states: \" + states.counts_message()\n\n        # TODO: We may actually want to set the data to a `StateGroup` object and just\n        #       allow it to be unpacked into a tuple and such so users can interact with\n        #       it\n        return State(\n            type=new_state_type,\n            message=message,\n            data=await result_factory.create_result(retval),\n        )\n\n    # Generators aren't portable, implicitly convert them to a list.\n    if isinstance(retval, GeneratorType):\n        data = list(retval)\n    else:\n        data = retval\n\n    # Otherwise, they just gave data and this is a completed retval\n    return Completed(data=await result_factory.create_result(data))\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/task-runners/","title":"prefect.task_runners","text":"","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners","title":"<code>prefect.task_runners</code>","text":"<p>Interface and implementations of various task runners.</p> <p>Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n&gt;&gt;&gt; from typing import List\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def say_hello(name):\n...     print(f\"hello {name}\")\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def say_goodbye(name):\n...     print(f\"goodbye {name}\")\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow(task_runner=SequentialTaskRunner())\n&gt;&gt;&gt; def greetings(names: List[str]):\n...     for name in names:\n...         say_hello(name)\n...         say_goodbye(name)\n&gt;&gt;&gt;\n&gt;&gt;&gt; greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\nhello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre> <p>Switching to a <code>DaskTaskRunner</code>: <pre><code>&gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n&gt;&gt;&gt; flow.task_runner = DaskTaskRunner()\n&gt;&gt;&gt; greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\nhello arthur\ngoodbye arthur\nhello trillian\nhello ford\ngoodbye marvin\nhello marvin\ngoodbye ford\ngoodbye trillian\n</code></pre></p> <p>For usage details, see the Task Runners documentation.</p>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner","title":"<code>BaseTaskRunner</code>","text":"Source code in <code>prefect/task_runners.py</code> <pre><code>class BaseTaskRunner(metaclass=abc.ABCMeta):\n    def __init__(self) -&gt; None:\n        self.logger = get_logger(f\"task_runner.{self.name}\")\n        self._started: bool = False\n\n    @property\n    @abc.abstractmethod\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        pass  # noqa\n\n    @property\n    def name(self):\n        return type(self).__name__.lower().replace(\"taskrunner\", \"\")\n\n    def duplicate(self):\n        \"\"\"\n        Return a new task runner instance with the same options.\n        \"\"\"\n        # The base class returns `NotImplemented` to indicate that this is not yet\n        # implemented by a given task runner.\n        return NotImplemented\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Returns true if the task runners use the same options.\n        \"\"\"\n        if type(other) == type(self) and (\n            # Compare public attributes for naive equality check\n            # Subclasses should implement this method with a check init option equality\n            {k: v for k, v in self.__dict__.items() if not k.startswith(\"_\")}\n            == {k: v for k, v in other.__dict__.items() if not k.startswith(\"_\")}\n        ):\n            return True\n        else:\n            return NotImplemented\n\n    @abc.abstractmethod\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        \"\"\"\n        Submit a call for execution and return a `PrefectFuture` that can be used to\n        get the call result.\n\n        Args:\n            task_run: The task run being submitted.\n            task_key: A unique key for this orchestration run of the task. Can be used\n                for caching.\n            call: The function to be executed\n            run_kwargs: A dict of keyword arguments to pass to `call`\n\n        Returns:\n            A future representing the result of `call` execution\n        \"\"\"\n        raise NotImplementedError()\n\n    @abc.abstractmethod\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        \"\"\"\n        Given a `PrefectFuture`, wait for its return state up to `timeout` seconds.\n        If it is not finished after the timeout expires, `None` should be returned.\n\n        Implementers should be careful to ensure that this function never returns or\n        raises an exception.\n        \"\"\"\n        raise NotImplementedError()\n\n    @asynccontextmanager\n    async def start(\n        self: T,\n    ) -&gt; AsyncIterator[T]:\n        \"\"\"\n        Start the task runner, preparing any resources necessary for task submission.\n\n        Children should implement `_start` to prepare and clean up resources.\n\n        Yields:\n            The prepared task runner\n        \"\"\"\n        if self._started:\n            raise RuntimeError(\"The task runner is already started!\")\n\n        async with AsyncExitStack() as exit_stack:\n            self.logger.debug(\"Starting task runner...\")\n            try:\n                await self._start(exit_stack)\n                self._started = True\n                yield self\n            finally:\n                self.logger.debug(\"Shutting down task runner...\")\n                self._started = False\n\n    async def _start(self, exit_stack: AsyncExitStack) -&gt; None:\n        \"\"\"\n        Create any resources required for this task runner to submit work.\n\n        Cleanup of resources should be submitted to the `exit_stack`.\n        \"\"\"\n        pass  # noqa\n\n    def __str__(self) -&gt; str:\n        return type(self).__name__\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Return a new task runner instance with the same options.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Return a new task runner instance with the same options.\n    \"\"\"\n    # The base class returns `NotImplemented` to indicate that this is not yet\n    # implemented by a given task runner.\n    return NotImplemented\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start the task runner, preparing any resources necessary for task submission.</p> <p>Children should implement <code>_start</code> to prepare and clean up resources.</p> <p>Yields:</p> Type Description <code>AsyncIterator[T]</code> <p>The prepared task runner</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@asynccontextmanager\nasync def start(\n    self: T,\n) -&gt; AsyncIterator[T]:\n    \"\"\"\n    Start the task runner, preparing any resources necessary for task submission.\n\n    Children should implement `_start` to prepare and clean up resources.\n\n    Yields:\n        The prepared task runner\n    \"\"\"\n    if self._started:\n        raise RuntimeError(\"The task runner is already started!\")\n\n    async with AsyncExitStack() as exit_stack:\n        self.logger.debug(\"Starting task runner...\")\n        try:\n            await self._start(exit_stack)\n            self._started = True\n            yield self\n        finally:\n            self.logger.debug(\"Shutting down task runner...\")\n            self._started = False\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.submit","title":"<code>submit</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Submit a call for execution and return a <code>PrefectFuture</code> that can be used to get the call result.</p> <p>Parameters:</p> Name Type Description Default <code>task_run</code> <p>The task run being submitted.</p> required <code>task_key</code> <p>A unique key for this orchestration run of the task. Can be used for caching.</p> required <code>call</code> <code>Callable[..., Awaitable[State[R]]]</code> <p>The function to be executed</p> required <code>run_kwargs</code> <p>A dict of keyword arguments to pass to <code>call</code></p> required <p>Returns:</p> Type Description <code>None</code> <p>A future representing the result of <code>call</code> execution</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@abc.abstractmethod\nasync def submit(\n    self,\n    key: UUID,\n    call: Callable[..., Awaitable[State[R]]],\n) -&gt; None:\n    \"\"\"\n    Submit a call for execution and return a `PrefectFuture` that can be used to\n    get the call result.\n\n    Args:\n        task_run: The task run being submitted.\n        task_key: A unique key for this orchestration run of the task. Can be used\n            for caching.\n        call: The function to be executed\n        run_kwargs: A dict of keyword arguments to pass to `call`\n\n    Returns:\n        A future representing the result of `call` execution\n    \"\"\"\n    raise NotImplementedError()\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.wait","title":"<code>wait</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Given a <code>PrefectFuture</code>, wait for its return state up to <code>timeout</code> seconds. If it is not finished after the timeout expires, <code>None</code> should be returned.</p> <p>Implementers should be careful to ensure that this function never returns or raises an exception.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@abc.abstractmethod\nasync def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n    \"\"\"\n    Given a `PrefectFuture`, wait for its return state up to `timeout` seconds.\n    If it is not finished after the timeout expires, `None` should be returned.\n\n    Implementers should be careful to ensure that this function never returns or\n    raises an exception.\n    \"\"\"\n    raise NotImplementedError()\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.ConcurrentTaskRunner","title":"<code>ConcurrentTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A concurrent task runner that allows tasks to switch when blocking on IO. Synchronous tasks will be submitted to a thread pool maintained by <code>anyio</code>.</p> Example <pre><code>Using a thread for concurrency:\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; from prefect.task_runners import ConcurrentTaskRunner\n&gt;&gt;&gt; @flow(task_runner=ConcurrentTaskRunner)\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     ...\n</code></pre> Source code in <code>prefect/task_runners.py</code> <pre><code>class ConcurrentTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A concurrent task runner that allows tasks to switch when blocking on IO.\n    Synchronous tasks will be submitted to a thread pool maintained by `anyio`.\n\n    Example:\n        ```\n        Using a thread for concurrency:\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; from prefect.task_runners import ConcurrentTaskRunner\n        &gt;&gt;&gt; @flow(task_runner=ConcurrentTaskRunner)\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     ...\n        ```\n    \"\"\"\n\n    def __init__(self):\n        # TODO: Consider adding `max_workers` support using anyio capacity limiters\n\n        # Runtime attributes\n        self._task_group: anyio.abc.TaskGroup = None\n        self._result_events: Dict[UUID, Event] = {}\n        self._results: Dict[UUID, Any] = {}\n        self._keys: Set[UUID] = set()\n\n        super().__init__()\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.CONCURRENT\n\n    def duplicate(self):\n        return type(self)()\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[[], Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        if not self._task_group:\n            raise RuntimeError(\n                \"The concurrent task runner cannot be used to submit work after \"\n                \"serialization.\"\n            )\n\n        # Create an event to set on completion\n        self._result_events[key] = Event()\n\n        # Rely on the event loop for concurrency\n        self._task_group.start_soon(self._run_and_store_result, key, call)\n\n    async def wait(\n        self,\n        key: UUID,\n        timeout: float = None,\n    ) -&gt; Optional[State]:\n        if not self._task_group:\n            raise RuntimeError(\n                \"The concurrent task runner cannot be used to wait for work after \"\n                \"serialization.\"\n            )\n\n        return await self._get_run_result(key, timeout)\n\n    async def _run_and_store_result(\n        self, key: UUID, call: Callable[[], Awaitable[State[R]]]\n    ):\n        \"\"\"\n        Simple utility to store the orchestration result in memory on completion\n\n        Since this run is occurring on the main thread, we capture exceptions to prevent\n        task crashes from crashing the flow run.\n        \"\"\"\n        try:\n            result = await call()\n        except BaseException as exc:\n            result = await exception_to_crashed_state(exc)\n\n        self._results[key] = result\n        self._result_events[key].set()\n\n    async def _get_run_result(\n        self, key: UUID, timeout: float = None\n    ) -&gt; Optional[State]:\n        \"\"\"\n        Block until the run result has been populated.\n        \"\"\"\n        result = None  # retval on timeout\n\n        # Note we do not use `asyncio.wrap_future` and instead use an `Event` to avoid\n        # stdlib behavior where the wrapped future is cancelled if the parent future is\n        # cancelled (as it would be during a timeout here)\n        with anyio.move_on_after(timeout):\n            await self._result_events[key].wait()\n            result = self._results[key]\n\n        return result  # timeout reached\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the process pool\n        \"\"\"\n        self._task_group = await exit_stack.enter_async_context(\n            anyio.create_task_group()\n        )\n\n    def __getstate__(self):\n        \"\"\"\n        Allow the `ConcurrentTaskRunner` to be serialized by dropping the task group.\n        \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_task_group\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"\n        When deserialized, we will no longer have a reference to the task group.\n        \"\"\"\n        self.__dict__.update(data)\n        self._task_group = None\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.SequentialTaskRunner","title":"<code>SequentialTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A simple task runner that executes calls as they are submitted.</p> <p>If writing synchronous tasks, this runner will always execute tasks sequentially. If writing async tasks, this runner will execute tasks sequentially unless grouped using <code>anyio.create_task_group</code> or <code>asyncio.gather</code>.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>class SequentialTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A simple task runner that executes calls as they are submitted.\n\n    If writing synchronous tasks, this runner will always execute tasks sequentially.\n    If writing async tasks, this runner will execute tasks sequentially unless grouped\n    using `anyio.create_task_group` or `asyncio.gather`.\n    \"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__()\n        self._results: Dict[str, State] = {}\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.SEQUENTIAL\n\n    def duplicate(self):\n        return type(self)()\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        # Run the function immediately and store the result in memory\n        try:\n            result = await call()\n        except BaseException as exc:\n            result = await exception_to_crashed_state(exc)\n\n        self._results[key] = result\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        return self._results[key]\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/tasks/","title":"prefect.tasks","text":"","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks","title":"<code>prefect.tasks</code>","text":"<p>Module containing the base workflow task class and decorator - for most use cases, using the <code>@task</code> decorator is preferred.</p>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task","title":"<code>Task</code>","text":"<p>               Bases: <code>Generic[P, R]</code></p> <p>A Prefect task definition.</p> <p>Note</p> <p>We recommend using the <code>@task</code> decorator for most use-cases.</p> <p>Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function creates a new task run.</p> <p>To preserve the input and output types, we use the generic type variables P and R for \"Parameters\" and \"Returns\" respectively.</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable[P, R]</code> <p>The function defining the task.</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>An optional string description for the task.</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional string specifying the version of this task definition</p> <code>None</code> <code>cache_key_fn</code> <code>Optional[Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]]</code> <p>An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.</p> <code>None</code> <code>cache_expiration</code> <code>Optional[timedelta]</code> <p>An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>An optional number of times to retry on task run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[float, int, List[float], Callable[[int], List[float]]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>None</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>An optional key to store the result in storage at when persisted. Defaults to a unique identifier.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float, None]</code> <p>An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the task will be redirected to the Prefect logger for the task run. Defaults to <code>None</code>, which indicates that the value from the flow should be used.</p> <code>False</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>If set, cached results for the cache key are not used. Defaults to <code>None</code>, which indicates that a cached result from a previous execution with matching cache key is used.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a completed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy (e.g. <code>retries=3</code>), and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Optional[Any]</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> Source code in <code>prefect/tasks.py</code> <pre><code>@PrefectObjectRegistry.register_instances\nclass Task(Generic[P, R]):\n    \"\"\"\n    A Prefect task definition.\n\n    !!! note\n        We recommend using [the `@task` decorator][prefect.tasks.task] for most use-cases.\n\n    Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function\n    creates a new task run.\n\n    To preserve the input and output types, we use the generic type variables P and R for \"Parameters\" and\n    \"Returns\" respectively.\n\n    Args:\n        fn: The function defining the task.\n        name: An optional name for the task; if not provided, the name will be inferred\n            from the given function.\n        description: An optional string description for the task.\n        tags: An optional set of tags to be associated with runs of this task. These\n            tags are combined with any tags defined by a `prefect.tags` context at\n            task runtime.\n        version: An optional string specifying the version of this task definition\n        cache_key_fn: An optional callable that, given the task run context and call\n            parameters, generates a string key; if the key matches a previous completed\n            state, that state result will be restored instead of running the task again.\n        cache_expiration: An optional amount of time indicating how long cached states\n            for this task should be restorable; if not provided, cached states will\n            never expire.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on task run failure.\n        retry_delay_seconds: Optionally configures how long to wait before retrying the\n            task after failure. This is only applicable if `retries` is nonzero. This\n            setting can either be a number of seconds, a list of retry delays, or a\n            callable that, given the total number of retries, generates a list of retry\n            delays. If a number of seconds, that delay will be applied to all retries.\n            If a list, each retry will wait for the corresponding delay before retrying.\n            When passing a callable or a list, the number of configured retry delays\n            cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a retry\n            can be jittered in order to avoid a \"thundering herd\".\n        persist_result: An optional toggle indicating whether the result of this task\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this task.\n            Defaults to the value set in the flow the task is called in.\n        result_storage_key: An optional key to store the result in storage at when persisted.\n            Defaults to a unique identifier.\n        result_serializer: An optional serializer to use to serialize the result of this\n            task for persistence. Defaults to the value set in the flow the task is\n            called in.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the task. If the task exceeds this runtime, it will be marked as failed.\n        log_prints: If set, `print` statements in the task will be redirected to the\n            Prefect logger for the task run. Defaults to `None`, which indicates\n            that the value from the flow should be used.\n        refresh_cache: If set, cached results for the cache key are not used.\n            Defaults to `None`, which indicates that a cached result from a previous\n            execution with matching cache key is used.\n        on_failure: An optional list of callables to run when the task enters a failed state.\n        on_completion: An optional list of callables to run when the task enters a completed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state. Should\n            return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task\n            should end as failed. Defaults to `None`, indicating the task should always continue\n            to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n    \"\"\"\n\n    # NOTE: These parameters (types, defaults, and docstrings) should be duplicated\n    #       exactly in the @task decorator\n    def __init__(\n        self,\n        fn: Callable[P, R],\n        name: Optional[str] = None,\n        description: Optional[str] = None,\n        tags: Optional[Iterable[str]] = None,\n        version: Optional[str] = None,\n        cache_key_fn: Optional[\n            Callable[[\"TaskRunContext\", Dict[str, Any]], Optional[str]]\n        ] = None,\n        cache_expiration: Optional[datetime.timedelta] = None,\n        task_run_name: Optional[Union[Callable[[], str], str]] = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[\n            Union[\n                float,\n                int,\n                List[float],\n                Callable[[int], List[float]],\n            ]\n        ] = None,\n        retry_jitter_factor: Optional[float] = None,\n        persist_result: Optional[bool] = None,\n        result_storage: Optional[ResultStorage] = None,\n        result_serializer: Optional[ResultSerializer] = None,\n        result_storage_key: Optional[str] = None,\n        cache_result_in_memory: bool = True,\n        timeout_seconds: Union[int, float, None] = None,\n        log_prints: Optional[bool] = False,\n        refresh_cache: Optional[bool] = None,\n        on_completion: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n        on_failure: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n        retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n        viz_return_value: Optional[Any] = None,\n    ):\n        # Validate if hook passed is list and contains callables\n        hook_categories = [on_completion, on_failure]\n        hook_names = [\"on_completion\", \"on_failure\"]\n        for hooks, hook_name in zip(hook_categories, hook_names):\n            if hooks is not None:\n                if not hooks:\n                    raise ValueError(f\"Empty list passed for '{hook_name}'\")\n                try:\n                    hooks = list(hooks)\n                except TypeError:\n                    raise TypeError(\n                        f\"Expected iterable for '{hook_name}'; got\"\n                        f\" {type(hooks).__name__} instead. Please provide a list of\"\n                        f\" hooks to '{hook_name}':\\n\\n\"\n                        f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                        \" my_flow():\\n\\tpass\"\n                    )\n\n                for hook in hooks:\n                    if not callable(hook):\n                        raise TypeError(\n                            f\"Expected callables in '{hook_name}'; got\"\n                            f\" {type(hook).__name__} instead. Please provide a list of\"\n                            f\" hooks to '{hook_name}':\\n\\n\"\n                            f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                            \" my_flow():\\n\\tpass\"\n                        )\n\n        if not callable(fn):\n            raise TypeError(\"'fn' must be callable\")\n\n        self.description = description or inspect.getdoc(fn)\n        update_wrapper(self, fn)\n        self.fn = fn\n        self.isasync = inspect.iscoroutinefunction(self.fn)\n\n        if not name:\n            if not hasattr(self.fn, \"__name__\"):\n                self.name = type(self.fn).__name__\n            else:\n                self.name = self.fn.__name__\n        else:\n            self.name = name\n\n        if task_run_name is not None:\n            if not isinstance(task_run_name, str) and not callable(task_run_name):\n                raise TypeError(\n                    \"Expected string or callable for 'task_run_name'; got\"\n                    f\" {type(task_run_name).__name__} instead.\"\n                )\n        self.task_run_name = task_run_name\n\n        self.version = version\n        self.log_prints = log_prints\n\n        raise_for_reserved_arguments(self.fn, [\"return_state\", \"wait_for\"])\n\n        self.tags = set(tags if tags else [])\n\n        self.task_key = _generate_task_key(self.fn)\n\n        self.cache_key_fn = cache_key_fn\n        self.cache_expiration = cache_expiration\n        self.refresh_cache = refresh_cache\n\n        # TaskRunPolicy settings\n        # TODO: We can instantiate a `TaskRunPolicy` and add Pydantic bound checks to\n        #       validate that the user passes positive numbers here\n\n        self.retries = (\n            retries if retries is not None else PREFECT_TASK_DEFAULT_RETRIES.value()\n        )\n        if retry_delay_seconds is None:\n            retry_delay_seconds = PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS.value()\n\n        if callable(retry_delay_seconds):\n            self.retry_delay_seconds = retry_delay_seconds(retries)\n        else:\n            self.retry_delay_seconds = retry_delay_seconds\n\n        if isinstance(self.retry_delay_seconds, list) and (\n            len(self.retry_delay_seconds) &gt; 50\n        ):\n            raise ValueError(\"Can not configure more than 50 retry delays per task.\")\n\n        if retry_jitter_factor is not None and retry_jitter_factor &lt; 0:\n            raise ValueError(\"`retry_jitter_factor` must be &gt;= 0.\")\n\n        self.retry_jitter_factor = retry_jitter_factor\n        self.persist_result = persist_result\n        self.result_storage = result_storage\n        self.result_serializer = result_serializer\n        self.result_storage_key = result_storage_key\n        self.cache_result_in_memory = cache_result_in_memory\n        self.timeout_seconds = float(timeout_seconds) if timeout_seconds else None\n        self.on_completion = on_completion\n        self.on_failure = on_failure\n\n        # retry_condition_fn must be a callable or None. If it is neither, raise a TypeError\n        if retry_condition_fn is not None and not (callable(retry_condition_fn)):\n            raise TypeError(\n                \"Expected `retry_condition_fn` to be callable, got\"\n                f\" {type(retry_condition_fn).__name__} instead.\"\n            )\n\n        self.retry_condition_fn = retry_condition_fn\n        self.viz_return_value = viz_return_value\n\n    def with_options(\n        self,\n        *,\n        name: str = None,\n        description: str = None,\n        tags: Iterable[str] = None,\n        cache_key_fn: Callable[\n            [\"TaskRunContext\", Dict[str, Any]], Optional[str]\n        ] = None,\n        task_run_name: Optional[Union[Callable[[], str], str]] = None,\n        cache_expiration: datetime.timedelta = None,\n        retries: Optional[int] = NotSet,\n        retry_delay_seconds: Union[\n            float,\n            int,\n            List[float],\n            Callable[[int], List[float]],\n        ] = NotSet,\n        retry_jitter_factor: Optional[float] = NotSet,\n        persist_result: Optional[bool] = NotSet,\n        result_storage: Optional[ResultStorage] = NotSet,\n        result_serializer: Optional[ResultSerializer] = NotSet,\n        result_storage_key: Optional[str] = NotSet,\n        cache_result_in_memory: Optional[bool] = None,\n        timeout_seconds: Union[int, float] = None,\n        log_prints: Optional[bool] = NotSet,\n        refresh_cache: Optional[bool] = NotSet,\n        on_completion: Optional[\n            List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n        ] = None,\n        on_failure: Optional[\n            List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n        ] = None,\n        retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n        viz_return_value: Optional[Any] = None,\n    ):\n        \"\"\"\n        Create a new task from the current object, updating provided options.\n\n        Args:\n            name: A new name for the task.\n            description: A new description for the task.\n            tags: A new set of tags for the task. If given, existing tags are ignored,\n                not merged.\n            cache_key_fn: A new cache key function for the task.\n            cache_expiration: A new cache expiration time for the task.\n            task_run_name: An optional name to distinguish runs of this task; this name can be provided\n                as a string template with the task's keyword arguments as variables,\n                or a function that returns a string.\n            retries: A new number of times to retry on task run failure.\n            retry_delay_seconds: Optionally configures how long to wait before retrying\n                the task after failure. This is only applicable if `retries` is nonzero.\n                This setting can either be a number of seconds, a list of retry delays,\n                or a callable that, given the total number of retries, generates a list\n                of retry delays. If a number of seconds, that delay will be applied to\n                all retries. If a list, each retry will wait for the corresponding delay\n                before retrying. When passing a callable or a list, the number of\n                configured retry delays cannot exceed 50.\n            retry_jitter_factor: An optional factor that defines the factor to which a\n                retry can be jittered in order to avoid a \"thundering herd\".\n            persist_result: A new option for enabling or disabling result persistence.\n            result_storage: A new storage type to use for results.\n            result_serializer: A new serializer to use for results.\n            result_storage_key: A new key for the persisted result to be stored at.\n            timeout_seconds: A new maximum time for the task to complete in seconds.\n            log_prints: A new option for enabling or disabling redirection of `print` statements.\n            refresh_cache: A new option for enabling or disabling cache refresh.\n            on_completion: A new list of callables to run when the task enters a completed state.\n            on_failure: A new list of callables to run when the task enters a failed state.\n            retry_condition_fn: An optional callable run when a task run returns a Failed state.\n                Should return `True` if the task should continue to its retry policy, and `False`\n                if the task should end as failed. Defaults to `None`, indicating the task should\n                always continue to its retry policy.\n            viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n        Returns:\n            A new `Task` instance.\n\n        Examples:\n\n            Create a new task from an existing task and update the name\n\n            &gt;&gt;&gt; @task(name=\"My task\")\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\n            Create a new task from an existing task and update the retry settings\n\n            &gt;&gt;&gt; from random import randint\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     x = randint(0, 5)\n            &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n            &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n            &gt;&gt;&gt;     return x\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\n            Use a task with updated options within a flow\n\n            &gt;&gt;&gt; @task(name=\"My task\")\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; my_flow():\n            &gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n            &gt;&gt;&gt;     new_task()\n        \"\"\"\n        return Task(\n            fn=self.fn,\n            name=name or self.name,\n            description=description or self.description,\n            tags=tags or copy(self.tags),\n            cache_key_fn=cache_key_fn or self.cache_key_fn,\n            cache_expiration=cache_expiration or self.cache_expiration,\n            task_run_name=task_run_name,\n            retries=retries if retries is not NotSet else self.retries,\n            retry_delay_seconds=(\n                retry_delay_seconds\n                if retry_delay_seconds is not NotSet\n                else self.retry_delay_seconds\n            ),\n            retry_jitter_factor=(\n                retry_jitter_factor\n                if retry_jitter_factor is not NotSet\n                else self.retry_jitter_factor\n            ),\n            persist_result=(\n                persist_result if persist_result is not NotSet else self.persist_result\n            ),\n            result_storage=(\n                result_storage if result_storage is not NotSet else self.result_storage\n            ),\n            result_storage_key=(\n                result_storage_key\n                if result_storage_key is not NotSet\n                else self.result_storage_key\n            ),\n            result_serializer=(\n                result_serializer\n                if result_serializer is not NotSet\n                else self.result_serializer\n            ),\n            cache_result_in_memory=(\n                cache_result_in_memory\n                if cache_result_in_memory is not None\n                else self.cache_result_in_memory\n            ),\n            timeout_seconds=(\n                timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n            ),\n            log_prints=(log_prints if log_prints is not NotSet else self.log_prints),\n            refresh_cache=(\n                refresh_cache if refresh_cache is not NotSet else self.refresh_cache\n            ),\n            on_completion=on_completion or self.on_completion,\n            on_failure=on_failure or self.on_failure,\n            retry_condition_fn=retry_condition_fn or self.retry_condition_fn,\n            viz_return_value=viz_return_value or self.viz_return_value,\n        )\n\n    async def create_run(\n        self,\n        client: Optional[Union[PrefectClient, SyncPrefectClient]],\n        parameters: Dict[str, Any] = None,\n        flow_run_context: Optional[FlowRunContext] = None,\n        parent_task_run_context: Optional[TaskRunContext] = None,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        extra_task_inputs: Optional[Dict[str, Set[TaskRunInput]]] = None,\n    ) -&gt; TaskRun:\n        from prefect.utilities.engine import (\n            _dynamic_key_for_task_run,\n            _resolve_custom_task_run_name,\n            collect_task_run_inputs,\n        )\n\n        if flow_run_context is None:\n            flow_run_context = FlowRunContext.get()\n        if parent_task_run_context is None:\n            parent_task_run_context = TaskRunContext.get()\n        if parameters is None:\n            parameters = {}\n\n        try:\n            task_run_name = _resolve_custom_task_run_name(self, parameters)\n        except TypeError:\n            task_run_name = None\n\n        if flow_run_context:\n            dynamic_key = _dynamic_key_for_task_run(context=flow_run_context, task=self)\n        else:\n            dynamic_key = uuid4().hex\n\n        # collect task inputs\n        task_inputs = {\n            k: await collect_task_run_inputs(v) for k, v in parameters.items()\n        }\n\n        # check if this task has a parent task run based on running in another\n        # task run's existing context. A task run is only considered a parent if\n        # it is in the same flow run (because otherwise presumably the child is\n        # in a subflow, so the subflow serves as the parent) or if there is no\n        # flow run\n        if parent_task_run_context:\n            # there is no flow run\n            if not flow_run_context:\n                task_inputs[\"__parents__\"] = [\n                    TaskRunResult(id=parent_task_run_context.task_run.id)\n                ]\n            # there is a flow run and the task run is in the same flow run\n            elif (\n                flow_run_context\n                and parent_task_run_context.task_run.flow_run_id\n                == flow_run_context.flow_run.id\n            ):\n                task_inputs[\"__parents__\"] = [\n                    TaskRunResult(id=parent_task_run_context.task_run.id)\n                ]\n\n        if wait_for:\n            task_inputs[\"wait_for\"] = await collect_task_run_inputs(wait_for)\n\n        # Join extra task inputs\n        for k, extras in (extra_task_inputs or {}).items():\n            task_inputs[k] = task_inputs[k].union(extras)\n\n        # create the task run\n        task_run = client.create_task_run(\n            task=self,\n            name=task_run_name,\n            flow_run_id=(\n                getattr(flow_run_context.flow_run, \"id\", None)\n                if flow_run_context and flow_run_context.flow_run\n                else None\n            ),\n            dynamic_key=str(dynamic_key),\n            state=Pending(),\n            task_inputs=task_inputs,\n            extra_tags=TagsContext.get().current_tags,\n        )\n        # the new engine uses sync clients but old engines use async clients\n        if inspect.isawaitable(task_run):\n            task_run = await task_run\n\n        if flow_run_context and flow_run_context.flow_run:\n            get_run_logger(flow_run_context).debug(\n                f\"Created task run {task_run.name!r} for task {self.name!r}\"\n            )\n        else:\n            logger.debug(f\"Created task run {task_run.name!r} for task {self.name!r}\")\n\n        return task_run\n\n    @overload\n    def __call__(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; None:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def __call__(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; T:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def __call__(\n        self,\n        *args: P.args,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: P.kwargs,\n    ):\n        \"\"\"\n        Run the task and return the result. If `return_state` is True returns\n        the result is wrapped in a Prefect State which provides error handling.\n        \"\"\"\n        from prefect.engine import enter_task_run_engine\n        from prefect.task_engine import submit_autonomous_task_run_to_engine\n        from prefect.task_runners import SequentialTaskRunner\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return_type = \"state\" if return_state else \"result\"\n\n        task_run_tracker = get_task_viz_tracker()\n        if task_run_tracker:\n            return track_viz_task(\n                self.isasync, self.name, parameters, self.viz_return_value\n            )\n\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE.value():\n            from prefect.new_task_engine import run_task\n\n            return run_task(\n                task=self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n            )\n\n        if (\n            PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n            and not FlowRunContext.get()\n        ):\n            from prefect import get_client\n\n            return submit_autonomous_task_run_to_engine(\n                task=self,\n                task_run=None,\n                task_runner=SequentialTaskRunner(),\n                parameters=parameters,\n                return_type=return_type,\n                client=get_client(),\n            )\n        entering_from_task_run = bool(TaskRunContext.get())\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            task_runner=SequentialTaskRunner(),\n            return_type=return_type,\n            mapped=False,\n            entering_from_task_run=entering_from_task_run,\n        )\n\n    @overload\n    def _run(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[None, Sync]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def _run(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[State[T]]:\n        ...\n\n    @overload\n    def _run(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def _run(\n        self,\n        *args: P.args,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: P.kwargs,\n    ) -&gt; Union[State, Awaitable[State]]:\n        \"\"\"\n        Run the task and return the final state.\n        \"\"\"\n        from prefect.engine import enter_task_run_engine\n        from prefect.task_runners import SequentialTaskRunner\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=\"state\",\n            task_runner=SequentialTaskRunner(),\n            mapped=False,\n        )\n\n    @overload\n    def submit(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[None, Sync]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[PrefectFuture[T, Async]]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[T, Sync]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; TaskRun:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[TaskRun]:\n        ...\n\n    def submit(\n        self,\n        *args: Any,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: Any,\n    ) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]:\n        \"\"\"\n        Submit a run of the task to the engine.\n\n        If writing an async task, this call must be awaited.\n\n        If called from within a flow function,\n\n        Will create a new task run in the backing API and submit the task to the flow's\n        task runner. This call only blocks execution while the task is being submitted,\n        once it is submitted, the flow function will continue executing. However, note\n        that the `SequentialTaskRunner` does not implement parallel execution for sync tasks\n        and they are fully resolved on submission.\n\n        Args:\n            *args: Arguments to run the task with\n            return_state: Return the result of the flow run wrapped in a\n                Prefect State.\n            wait_for: Upstream task futures to wait for before starting the task\n            **kwargs: Keyword arguments to run the task with\n\n        Returns:\n            If `return_state` is False a future allowing asynchronous access to\n                the state of the task\n            If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to\n                the state of the task\n\n        Examples:\n\n            Define a task\n\n            &gt;&gt;&gt; from prefect import task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return \"hello\"\n\n            Run a task in a flow\n\n            &gt;&gt;&gt; from prefect import flow\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.submit()\n\n            Wait for a task to finish\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.submit().wait()\n\n            Use the result from a task in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     print(my_task.submit().result())\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            hello\n\n            Run an async task in an async flow\n\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; async def my_async_task():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     await my_async_task.submit()\n\n            Run a sync task in an async flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     my_task.submit()\n\n            Enforce ordering between tasks that do not exchange data\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_1():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_2():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     x = task_1.submit()\n            &gt;&gt;&gt;\n            &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n            &gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n\n        \"\"\"\n\n        from prefect.engine import create_autonomous_task_run, enter_task_run_engine\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n        return_type = \"state\" if return_state else \"future\"\n        flow_run_context = FlowRunContext.get()\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            raise VisualizationUnsupportedError(\n                \"`task.submit()` is not currently supported by `flow.visualize()`\"\n            )\n\n        if PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING and not flow_run_context:\n            create_autonomous_task_run_call = create_call(\n                create_autonomous_task_run, task=self, parameters=parameters\n            )\n            if self.isasync:\n                return from_async.wait_for_call_in_loop_thread(\n                    create_autonomous_task_run_call\n                )\n            else:\n                return from_sync.wait_for_call_in_loop_thread(\n                    create_autonomous_task_run_call\n                )\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE and flow_run_context:\n            if self.isasync:\n                return self._submit_async(\n                    parameters=parameters,\n                    flow_run_context=flow_run_context,\n                    wait_for=wait_for,\n                    return_state=return_state,\n                )\n            else:\n                raise NotImplementedError(\n                    \"Submitting sync tasks with the new engine has not be implemented yet.\"\n                )\n\n        else:\n            return enter_task_run_engine(\n                self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n                task_runner=None,  # Use the flow's task runner\n                mapped=False,\n            )\n\n    async def _submit_async(\n        self,\n        parameters: Dict[str, Any],\n        flow_run_context: FlowRunContext,\n        wait_for: Optional[Iterable[PrefectFuture]],\n        return_state: bool,\n    ):\n        from prefect.new_task_engine import run_task_async\n\n        task_runner = flow_run_context.task_runner\n\n        task_run = await self.create_run(\n            client=flow_run_context.client,\n            flow_run_context=flow_run_context,\n            parameters=parameters,\n            wait_for=wait_for,\n        )\n\n        future = PrefectFuture(\n            name=task_run.name,\n            key=uuid4(),\n            task_runner=task_runner,\n            asynchronous=(self.isasync and flow_run_context.flow.isasync),\n        )\n        future.task_run = task_run\n        flow_run_context.task_run_futures.append(future)\n        await task_runner.submit(\n            key=future.key,\n            call=partial(\n                run_task_async,\n                task=self,\n                task_run=task_run,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=\"state\",\n            ),\n        )\n        # TODO: I don't like this. Can we move responsibility for creating the future\n        # and setting this anyio.Event to the task runner?\n        future._submitted.set()\n\n        if return_state:\n            return await future.wait()\n        else:\n            return future\n\n    @overload\n    def map(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; List[PrefectFuture[None, Sync]]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[List[PrefectFuture[T, Async]]]:\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; List[PrefectFuture[T, Sync]]:\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; List[State[T]]:\n        ...\n\n    def map(\n        self,\n        *args: Any,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: Any,\n    ) -&gt; Any:\n        \"\"\"\n        Submit a mapped run of the task to a worker.\n\n        Must be called within a flow function. If writing an async task, this\n        call must be awaited.\n\n        Must be called with at least one iterable and all iterables must be\n        the same length. Any arguments that are not iterable will be treated as\n        a static value and each task run will receive the same value.\n\n        Will create as many task runs as the length of the iterable(s) in the\n        backing API and submit the task runs to the flow's task runner. This\n        call blocks if given a future as input while the future is resolved. It\n        also blocks while the tasks are being submitted, once they are\n        submitted, the flow function will continue executing. However, note\n        that the `SequentialTaskRunner` does not implement parallel execution\n        for sync tasks and they are fully resolved on submission.\n\n        Args:\n            *args: Iterable and static arguments to run the tasks with\n            return_state: Return a list of Prefect States that wrap the results\n                of each task run.\n            wait_for: Upstream task futures to wait for before starting the\n                task\n            **kwargs: Keyword iterable arguments to run the task with\n\n        Returns:\n            A list of futures allowing asynchronous access to the state of the\n            tasks\n\n        Examples:\n\n            Define a task\n\n            &gt;&gt;&gt; from prefect import task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task(x):\n            &gt;&gt;&gt;     return x + 1\n\n            Create mapped tasks\n\n            &gt;&gt;&gt; from prefect import flow\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.map([1, 2, 3])\n\n            Wait for all mapped tasks to finish\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n            &gt;&gt;&gt;     for future in futures:\n            &gt;&gt;&gt;         future.wait()\n            &gt;&gt;&gt;     # Now all of the mapped tasks have finished\n            &gt;&gt;&gt;     my_task(10)\n\n            Use the result from mapped tasks in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n            &gt;&gt;&gt;     for future in futures:\n            &gt;&gt;&gt;         print(future.result())\n            &gt;&gt;&gt; my_flow()\n            2\n            3\n            4\n\n            Enforce ordering between tasks that do not exchange data\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_1(x):\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_2(y):\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     x = task_1.submit()\n            &gt;&gt;&gt;\n            &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n            &gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\n            Use a non-iterable input as a constant across mapped tasks\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def display(prefix, item):\n            &gt;&gt;&gt;    print(prefix, item)\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            Check it out: 1\n            Check it out: 2\n            Check it out: 3\n\n            Use `unmapped` to treat an iterable argument as a constant\n            &gt;&gt;&gt; from prefect import unmapped\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def add_n_to_items(items, n):\n            &gt;&gt;&gt;     return [item + n for item in items]\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            [[11, 21], [12, 22], [13, 23]]\n        \"\"\"\n\n        from prefect.engine import begin_task_map, enter_task_run_engine\n\n        # Convert the call args/kwargs to a parameter dict; do not apply defaults\n        # since they should not be mapped over\n        parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)\n        return_type = \"state\" if return_state else \"future\"\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            raise VisualizationUnsupportedError(\n                \"`task.map()` is not currently supported by `flow.visualize()`\"\n            )\n\n        if (\n            PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n            and not FlowRunContext.get()\n        ):\n            map_call = create_call(\n                begin_task_map,\n                task=self,\n                parameters=parameters,\n                flow_run_context=None,\n                wait_for=wait_for,\n                return_type=return_type,\n                task_runner=None,\n                autonomous=True,\n            )\n            if self.isasync:\n                return from_async.wait_for_call_in_loop_thread(map_call)\n            else:\n                return from_sync.wait_for_call_in_loop_thread(map_call)\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,\n            mapped=True,\n        )\n\n    def serve(self, task_runner: Optional[BaseTaskRunner] = None) -&gt; \"Task\":\n        \"\"\"Serve the task using the provided task runner. This method is used to\n        establish a websocket connection with the Prefect server and listen for\n        submitted task runs to execute.\n\n        Args:\n            task_runner: The task runner to use for serving the task. If not provided,\n                the default ConcurrentTaskRunner will be used.\n\n        Examples:\n            Serve a task using the default task runner\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n\n            &gt;&gt;&gt; my_task.serve()\n        \"\"\"\n\n        if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING:\n            raise ValueError(\n                \"Task's `serve` method is an experimental feature and must be enabled with \"\n                \"`prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=True`\"\n            )\n\n        from prefect.task_server import serve\n\n        serve(self, task_runner=task_runner)\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.map","title":"<code>map</code>","text":"<p>Submit a mapped run of the task to a worker.</p> <p>Must be called within a flow function. If writing an async task, this call must be awaited.</p> <p>Must be called with at least one iterable and all iterables must be the same length. Any arguments that are not iterable will be treated as a static value and each task run will receive the same value.</p> <p>Will create as many task runs as the length of the iterable(s) in the backing API and submit the task runs to the flow's task runner. This call blocks if given a future as input while the future is resolved. It also blocks while the tasks are being submitted, once they are submitted, the flow function will continue executing. However, note that the <code>SequentialTaskRunner</code> does not implement parallel execution for sync tasks and they are fully resolved on submission.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Iterable and static arguments to run the tasks with</p> <code>()</code> <code>return_state</code> <code>bool</code> <p>Return a list of Prefect States that wrap the results of each task run.</p> <code>False</code> <code>wait_for</code> <code>Optional[Iterable[PrefectFuture]]</code> <p>Upstream task futures to wait for before starting the task</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Keyword iterable arguments to run the task with</p> <code>{}</code> <p>Returns:</p> Type Description <code>Any</code> <p>A list of futures allowing asynchronous access to the state of the</p> <code>Any</code> <p>tasks</p> <pre><code>Define a task\n\n&gt;&gt;&gt; from prefect import task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task(x):\n&gt;&gt;&gt;     return x + 1\n\nCreate mapped tasks\n\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.map([1, 2, 3])\n\nWait for all mapped tasks to finish\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n&gt;&gt;&gt;     for future in futures:\n&gt;&gt;&gt;         future.wait()\n&gt;&gt;&gt;     # Now all of the mapped tasks have finished\n&gt;&gt;&gt;     my_task(10)\n\nUse the result from mapped tasks in a flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n&gt;&gt;&gt;     for future in futures:\n&gt;&gt;&gt;         print(future.result())\n&gt;&gt;&gt; my_flow()\n2\n3\n4\n\nEnforce ordering between tasks that do not exchange data\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_1(x):\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_2(y):\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     x = task_1.submit()\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n&gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\nUse a non-iterable input as a constant across mapped tasks\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def display(prefix, item):\n&gt;&gt;&gt;    print(prefix, item)\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\nCheck it out: 1\nCheck it out: 2\nCheck it out: 3\n\nUse `unmapped` to treat an iterable argument as a constant\n&gt;&gt;&gt; from prefect import unmapped\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def add_n_to_items(items, n):\n&gt;&gt;&gt;     return [item + n for item in items]\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\n[[11, 21], [12, 22], [13, 23]]\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def map(\n    self,\n    *args: Any,\n    return_state: bool = False,\n    wait_for: Optional[Iterable[PrefectFuture]] = None,\n    **kwargs: Any,\n) -&gt; Any:\n    \"\"\"\n    Submit a mapped run of the task to a worker.\n\n    Must be called within a flow function. If writing an async task, this\n    call must be awaited.\n\n    Must be called with at least one iterable and all iterables must be\n    the same length. Any arguments that are not iterable will be treated as\n    a static value and each task run will receive the same value.\n\n    Will create as many task runs as the length of the iterable(s) in the\n    backing API and submit the task runs to the flow's task runner. This\n    call blocks if given a future as input while the future is resolved. It\n    also blocks while the tasks are being submitted, once they are\n    submitted, the flow function will continue executing. However, note\n    that the `SequentialTaskRunner` does not implement parallel execution\n    for sync tasks and they are fully resolved on submission.\n\n    Args:\n        *args: Iterable and static arguments to run the tasks with\n        return_state: Return a list of Prefect States that wrap the results\n            of each task run.\n        wait_for: Upstream task futures to wait for before starting the\n            task\n        **kwargs: Keyword iterable arguments to run the task with\n\n    Returns:\n        A list of futures allowing asynchronous access to the state of the\n        tasks\n\n    Examples:\n\n        Define a task\n\n        &gt;&gt;&gt; from prefect import task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task(x):\n        &gt;&gt;&gt;     return x + 1\n\n        Create mapped tasks\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.map([1, 2, 3])\n\n        Wait for all mapped tasks to finish\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n        &gt;&gt;&gt;     for future in futures:\n        &gt;&gt;&gt;         future.wait()\n        &gt;&gt;&gt;     # Now all of the mapped tasks have finished\n        &gt;&gt;&gt;     my_task(10)\n\n        Use the result from mapped tasks in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n        &gt;&gt;&gt;     for future in futures:\n        &gt;&gt;&gt;         print(future.result())\n        &gt;&gt;&gt; my_flow()\n        2\n        3\n        4\n\n        Enforce ordering between tasks that do not exchange data\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_1(x):\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_2(y):\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     x = task_1.submit()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n        &gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\n        Use a non-iterable input as a constant across mapped tasks\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def display(prefix, item):\n        &gt;&gt;&gt;    print(prefix, item)\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        Check it out: 1\n        Check it out: 2\n        Check it out: 3\n\n        Use `unmapped` to treat an iterable argument as a constant\n        &gt;&gt;&gt; from prefect import unmapped\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def add_n_to_items(items, n):\n        &gt;&gt;&gt;     return [item + n for item in items]\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        [[11, 21], [12, 22], [13, 23]]\n    \"\"\"\n\n    from prefect.engine import begin_task_map, enter_task_run_engine\n\n    # Convert the call args/kwargs to a parameter dict; do not apply defaults\n    # since they should not be mapped over\n    parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)\n    return_type = \"state\" if return_state else \"future\"\n\n    task_viz_tracker = get_task_viz_tracker()\n    if task_viz_tracker:\n        raise VisualizationUnsupportedError(\n            \"`task.map()` is not currently supported by `flow.visualize()`\"\n        )\n\n    if (\n        PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n        and not FlowRunContext.get()\n    ):\n        map_call = create_call(\n            begin_task_map,\n            task=self,\n            parameters=parameters,\n            flow_run_context=None,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,\n            autonomous=True,\n        )\n        if self.isasync:\n            return from_async.wait_for_call_in_loop_thread(map_call)\n        else:\n            return from_sync.wait_for_call_in_loop_thread(map_call)\n\n    return enter_task_run_engine(\n        self,\n        parameters=parameters,\n        wait_for=wait_for,\n        return_type=return_type,\n        task_runner=None,\n        mapped=True,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.serve","title":"<code>serve</code>","text":"<p>Serve the task using the provided task runner. This method is used to establish a websocket connection with the Prefect server and listen for submitted task runs to execute.</p> <p>Parameters:</p> Name Type Description Default <code>task_runner</code> <code>Optional[BaseTaskRunner]</code> <p>The task runner to use for serving the task. If not provided, the default ConcurrentTaskRunner will be used.</p> <code>None</code> <p>Examples:</p> <p>Serve a task using the default task runner</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n</code></pre> <pre><code>&gt;&gt;&gt; my_task.serve()\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def serve(self, task_runner: Optional[BaseTaskRunner] = None) -&gt; \"Task\":\n    \"\"\"Serve the task using the provided task runner. This method is used to\n    establish a websocket connection with the Prefect server and listen for\n    submitted task runs to execute.\n\n    Args:\n        task_runner: The task runner to use for serving the task. If not provided,\n            the default ConcurrentTaskRunner will be used.\n\n    Examples:\n        Serve a task using the default task runner\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n\n        &gt;&gt;&gt; my_task.serve()\n    \"\"\"\n\n    if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING:\n        raise ValueError(\n            \"Task's `serve` method is an experimental feature and must be enabled with \"\n            \"`prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=True`\"\n        )\n\n    from prefect.task_server import serve\n\n    serve(self, task_runner=task_runner)\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.submit","title":"<code>submit</code>","text":"<p>Submit a run of the task to the engine.</p> <p>If writing an async task, this call must be awaited.</p> <p>If called from within a flow function,</p> <p>Will create a new task run in the backing API and submit the task to the flow's task runner. This call only blocks execution while the task is being submitted, once it is submitted, the flow function will continue executing. However, note that the <code>SequentialTaskRunner</code> does not implement parallel execution for sync tasks and they are fully resolved on submission.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Arguments to run the task with</p> <code>()</code> <code>return_state</code> <code>bool</code> <p>Return the result of the flow run wrapped in a Prefect State.</p> <code>False</code> <code>wait_for</code> <code>Optional[Iterable[PrefectFuture]]</code> <p>Upstream task futures to wait for before starting the task</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Keyword arguments to run the task with</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]</code> <p>If <code>return_state</code> is False a future allowing asynchronous access to the state of the task</p> <code>Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]</code> <p>If <code>return_state</code> is True a future wrapped in a Prefect State allowing asynchronous access to the state of the task</p> <pre><code>Define a task\n\n&gt;&gt;&gt; from prefect import task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return \"hello\"\n\nRun a task in a flow\n\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.submit()\n\nWait for a task to finish\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.submit().wait()\n\nUse the result from a task in a flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     print(my_task.submit().result())\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\nhello\n\nRun an async task in an async flow\n\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; async def my_async_task():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     await my_async_task.submit()\n\nRun a sync task in an async flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     my_task.submit()\n\nEnforce ordering between tasks that do not exchange data\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_1():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_2():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     x = task_1.submit()\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n&gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def submit(\n    self,\n    *args: Any,\n    return_state: bool = False,\n    wait_for: Optional[Iterable[PrefectFuture]] = None,\n    **kwargs: Any,\n) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]:\n    \"\"\"\n    Submit a run of the task to the engine.\n\n    If writing an async task, this call must be awaited.\n\n    If called from within a flow function,\n\n    Will create a new task run in the backing API and submit the task to the flow's\n    task runner. This call only blocks execution while the task is being submitted,\n    once it is submitted, the flow function will continue executing. However, note\n    that the `SequentialTaskRunner` does not implement parallel execution for sync tasks\n    and they are fully resolved on submission.\n\n    Args:\n        *args: Arguments to run the task with\n        return_state: Return the result of the flow run wrapped in a\n            Prefect State.\n        wait_for: Upstream task futures to wait for before starting the task\n        **kwargs: Keyword arguments to run the task with\n\n    Returns:\n        If `return_state` is False a future allowing asynchronous access to\n            the state of the task\n        If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to\n            the state of the task\n\n    Examples:\n\n        Define a task\n\n        &gt;&gt;&gt; from prefect import task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return \"hello\"\n\n        Run a task in a flow\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.submit()\n\n        Wait for a task to finish\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.submit().wait()\n\n        Use the result from a task in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     print(my_task.submit().result())\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        hello\n\n        Run an async task in an async flow\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; async def my_async_task():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     await my_async_task.submit()\n\n        Run a sync task in an async flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     my_task.submit()\n\n        Enforce ordering between tasks that do not exchange data\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_1():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_2():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     x = task_1.submit()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n        &gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n\n    \"\"\"\n\n    from prefect.engine import create_autonomous_task_run, enter_task_run_engine\n\n    # Convert the call args/kwargs to a parameter dict\n    parameters = get_call_parameters(self.fn, args, kwargs)\n    return_type = \"state\" if return_state else \"future\"\n    flow_run_context = FlowRunContext.get()\n\n    task_viz_tracker = get_task_viz_tracker()\n    if task_viz_tracker:\n        raise VisualizationUnsupportedError(\n            \"`task.submit()` is not currently supported by `flow.visualize()`\"\n        )\n\n    if PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING and not flow_run_context:\n        create_autonomous_task_run_call = create_call(\n            create_autonomous_task_run, task=self, parameters=parameters\n        )\n        if self.isasync:\n            return from_async.wait_for_call_in_loop_thread(\n                create_autonomous_task_run_call\n            )\n        else:\n            return from_sync.wait_for_call_in_loop_thread(\n                create_autonomous_task_run_call\n            )\n    if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE and flow_run_context:\n        if self.isasync:\n            return self._submit_async(\n                parameters=parameters,\n                flow_run_context=flow_run_context,\n                wait_for=wait_for,\n                return_state=return_state,\n            )\n        else:\n            raise NotImplementedError(\n                \"Submitting sync tasks with the new engine has not be implemented yet.\"\n            )\n\n    else:\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,  # Use the flow's task runner\n            mapped=False,\n        )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.with_options","title":"<code>with_options</code>","text":"<p>Create a new task from the current object, updating provided options.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A new name for the task.</p> <code>None</code> <code>description</code> <code>str</code> <p>A new description for the task.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>A new set of tags for the task. If given, existing tags are ignored, not merged.</p> <code>None</code> <code>cache_key_fn</code> <code>Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]</code> <p>A new cache key function for the task.</p> <code>None</code> <code>cache_expiration</code> <code>timedelta</code> <p>A new cache expiration time for the task.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>A new number of times to retry on task run failure.</p> <code>NotSet</code> <code>retry_delay_seconds</code> <code>Union[float, int, List[float], Callable[[int], List[float]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>NotSet</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>NotSet</code> <code>persist_result</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling result persistence.</p> <code>NotSet</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>A new storage type to use for results.</p> <code>NotSet</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>A new serializer to use for results.</p> <code>NotSet</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>A new key for the persisted result to be stored at.</p> <code>NotSet</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>A new maximum time for the task to complete in seconds.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling redirection of <code>print</code> statements.</p> <code>NotSet</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling cache refresh.</p> <code>NotSet</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], Union[Awaitable[None], None]]]]</code> <p>A new list of callables to run when the task enters a completed state.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], Union[Awaitable[None], None]]]]</code> <p>A new list of callables to run when the task enters a failed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy, and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Optional[Any]</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> <p>Returns:</p> Type Description <p>A new <code>Task</code> instance.</p> <pre><code>Create a new task from an existing task and update the name\n\n&gt;&gt;&gt; @task(name=\"My task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\nCreate a new task from an existing task and update the retry settings\n\n&gt;&gt;&gt; from random import randint\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     x = randint(0, 5)\n&gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n&gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n&gt;&gt;&gt;     return x\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\nUse a task with updated options within a flow\n\n&gt;&gt;&gt; @task(name=\"My task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; my_flow():\n&gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n&gt;&gt;&gt;     new_task()\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def with_options(\n    self,\n    *,\n    name: str = None,\n    description: str = None,\n    tags: Iterable[str] = None,\n    cache_key_fn: Callable[\n        [\"TaskRunContext\", Dict[str, Any]], Optional[str]\n    ] = None,\n    task_run_name: Optional[Union[Callable[[], str], str]] = None,\n    cache_expiration: datetime.timedelta = None,\n    retries: Optional[int] = NotSet,\n    retry_delay_seconds: Union[\n        float,\n        int,\n        List[float],\n        Callable[[int], List[float]],\n    ] = NotSet,\n    retry_jitter_factor: Optional[float] = NotSet,\n    persist_result: Optional[bool] = NotSet,\n    result_storage: Optional[ResultStorage] = NotSet,\n    result_serializer: Optional[ResultSerializer] = NotSet,\n    result_storage_key: Optional[str] = NotSet,\n    cache_result_in_memory: Optional[bool] = None,\n    timeout_seconds: Union[int, float] = None,\n    log_prints: Optional[bool] = NotSet,\n    refresh_cache: Optional[bool] = NotSet,\n    on_completion: Optional[\n        List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_failure: Optional[\n        List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n    viz_return_value: Optional[Any] = None,\n):\n    \"\"\"\n    Create a new task from the current object, updating provided options.\n\n    Args:\n        name: A new name for the task.\n        description: A new description for the task.\n        tags: A new set of tags for the task. If given, existing tags are ignored,\n            not merged.\n        cache_key_fn: A new cache key function for the task.\n        cache_expiration: A new cache expiration time for the task.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: A new number of times to retry on task run failure.\n        retry_delay_seconds: Optionally configures how long to wait before retrying\n            the task after failure. This is only applicable if `retries` is nonzero.\n            This setting can either be a number of seconds, a list of retry delays,\n            or a callable that, given the total number of retries, generates a list\n            of retry delays. If a number of seconds, that delay will be applied to\n            all retries. If a list, each retry will wait for the corresponding delay\n            before retrying. When passing a callable or a list, the number of\n            configured retry delays cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a\n            retry can be jittered in order to avoid a \"thundering herd\".\n        persist_result: A new option for enabling or disabling result persistence.\n        result_storage: A new storage type to use for results.\n        result_serializer: A new serializer to use for results.\n        result_storage_key: A new key for the persisted result to be stored at.\n        timeout_seconds: A new maximum time for the task to complete in seconds.\n        log_prints: A new option for enabling or disabling redirection of `print` statements.\n        refresh_cache: A new option for enabling or disabling cache refresh.\n        on_completion: A new list of callables to run when the task enters a completed state.\n        on_failure: A new list of callables to run when the task enters a failed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state.\n            Should return `True` if the task should continue to its retry policy, and `False`\n            if the task should end as failed. Defaults to `None`, indicating the task should\n            always continue to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n    Returns:\n        A new `Task` instance.\n\n    Examples:\n\n        Create a new task from an existing task and update the name\n\n        &gt;&gt;&gt; @task(name=\"My task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\n        Create a new task from an existing task and update the retry settings\n\n        &gt;&gt;&gt; from random import randint\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     x = randint(0, 5)\n        &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n        &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n        &gt;&gt;&gt;     return x\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\n        Use a task with updated options within a flow\n\n        &gt;&gt;&gt; @task(name=\"My task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; my_flow():\n        &gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n        &gt;&gt;&gt;     new_task()\n    \"\"\"\n    return Task(\n        fn=self.fn,\n        name=name or self.name,\n        description=description or self.description,\n        tags=tags or copy(self.tags),\n        cache_key_fn=cache_key_fn or self.cache_key_fn,\n        cache_expiration=cache_expiration or self.cache_expiration,\n        task_run_name=task_run_name,\n        retries=retries if retries is not NotSet else self.retries,\n        retry_delay_seconds=(\n            retry_delay_seconds\n            if retry_delay_seconds is not NotSet\n            else self.retry_delay_seconds\n        ),\n        retry_jitter_factor=(\n            retry_jitter_factor\n            if retry_jitter_factor is not NotSet\n            else self.retry_jitter_factor\n        ),\n        persist_result=(\n            persist_result if persist_result is not NotSet else self.persist_result\n        ),\n        result_storage=(\n            result_storage if result_storage is not NotSet else self.result_storage\n        ),\n        result_storage_key=(\n            result_storage_key\n            if result_storage_key is not NotSet\n            else self.result_storage_key\n        ),\n        result_serializer=(\n            result_serializer\n            if result_serializer is not NotSet\n            else self.result_serializer\n        ),\n        cache_result_in_memory=(\n            cache_result_in_memory\n            if cache_result_in_memory is not None\n            else self.cache_result_in_memory\n        ),\n        timeout_seconds=(\n            timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n        ),\n        log_prints=(log_prints if log_prints is not NotSet else self.log_prints),\n        refresh_cache=(\n            refresh_cache if refresh_cache is not NotSet else self.refresh_cache\n        ),\n        on_completion=on_completion or self.on_completion,\n        on_failure=on_failure or self.on_failure,\n        retry_condition_fn=retry_condition_fn or self.retry_condition_fn,\n        viz_return_value=viz_return_value or self.viz_return_value,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.exponential_backoff","title":"<code>exponential_backoff</code>","text":"<p>A task retry backoff utility that configures exponential backoff for task retries. The exponential backoff design matches the urllib3 implementation.</p> <p>Parameters:</p> Name Type Description Default <code>backoff_factor</code> <code>float</code> <p>the base delay for the first retry, subsequent retries will increase the delay time by powers of 2.</p> required <p>Returns:</p> Type Description <code>Callable[[int], List[float]]</code> <p>a callable that can be passed to the task constructor</p> Source code in <code>prefect/tasks.py</code> <pre><code>def exponential_backoff(backoff_factor: float) -&gt; Callable[[int], List[float]]:\n    \"\"\"\n    A task retry backoff utility that configures exponential backoff for task retries.\n    The exponential backoff design matches the urllib3 implementation.\n\n    Arguments:\n        backoff_factor: the base delay for the first retry, subsequent retries will\n            increase the delay time by powers of 2.\n\n    Returns:\n        a callable that can be passed to the task constructor\n    \"\"\"\n\n    def retry_backoff_callable(retries: int) -&gt; List[float]:\n        # no more than 50 retry delays can be configured on a task\n        retries = min(retries, 50)\n\n        return [backoff_factor * max(0, 2**r) for r in range(retries)]\n\n    return retry_backoff_callable\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.task","title":"<code>task</code>","text":"<p>Decorator to designate a function as a task in a Prefect workflow.</p> <p>This decorator may be used for asynchronous or synchronous functions.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An optional name for the task; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>description</code> <code>str</code> <p>An optional string description for the task.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime.</p> <code>None</code> <code>version</code> <code>str</code> <p>An optional string specifying the version of this task definition</p> <code>None</code> <code>cache_key_fn</code> <code>Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]</code> <p>An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.</p> <code>None</code> <code>cache_expiration</code> <code>timedelta</code> <p>An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>int</code> <p>An optional number of times to retry on task run failure</p> <code>None</code> <code>retry_delay_seconds</code> <code>Union[float, int, List[float], Callable[[int], List[float]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>None</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>An optional key to store the result in storage at when persisted. Defaults to a unique identifier.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the task will be redirected to the Prefect logger for the task run. Defaults to <code>None</code>, which indicates that the value from the flow should be used.</p> <code>None</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>If set, cached results for the cache key are not used. Defaults to <code>None</code>, which indicates that a cached result from a previous execution with matching cache key is used.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a completed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy (e.g. <code>retries=3</code>), and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Any</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> <p>Returns:</p> Type Description <p>A callable <code>Task</code> object which, when called, will submit the task for execution.</p> <p>Examples:</p> <p>Define a simple task</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define an async task</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; async def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define a task with tags and a description</p> <pre><code>&gt;&gt;&gt; @task(tags={\"a\", \"b\"}, description=\"This task is empty but its my first!\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a task with a custom name</p> <pre><code>&gt;&gt;&gt; @task(name=\"The Ultimate Task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a task that retries 3 times with a 5 second delay between attempts</p> <pre><code>&gt;&gt;&gt; from random import randint\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(retries=3, retry_delay_seconds=5)\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     x = randint(0, 5)\n&gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n&gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n&gt;&gt;&gt;     return x\n</code></pre> <p>Define a task that is cached for a day based on its inputs</p> <pre><code>&gt;&gt;&gt; from prefect.tasks import task_input_hash\n&gt;&gt;&gt; from datetime import timedelta\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return \"hello\"\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def task(\n    __fn=None,\n    *,\n    name: str = None,\n    description: str = None,\n    tags: Iterable[str] = None,\n    version: str = None,\n    cache_key_fn: Callable[[\"TaskRunContext\", Dict[str, Any]], Optional[str]] = None,\n    cache_expiration: datetime.timedelta = None,\n    task_run_name: Optional[Union[Callable[[], str], str]] = None,\n    retries: int = None,\n    retry_delay_seconds: Union[\n        float,\n        int,\n        List[float],\n        Callable[[int], List[float]],\n    ] = None,\n    retry_jitter_factor: Optional[float] = None,\n    persist_result: Optional[bool] = None,\n    result_storage: Optional[ResultStorage] = None,\n    result_storage_key: Optional[str] = None,\n    result_serializer: Optional[ResultSerializer] = None,\n    cache_result_in_memory: bool = True,\n    timeout_seconds: Union[int, float] = None,\n    log_prints: Optional[bool] = None,\n    refresh_cache: Optional[bool] = None,\n    on_completion: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n    on_failure: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n    retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n    viz_return_value: Any = None,\n):\n    \"\"\"\n    Decorator to designate a function as a task in a Prefect workflow.\n\n    This decorator may be used for asynchronous or synchronous functions.\n\n    Args:\n        name: An optional name for the task; if not provided, the name will be inferred\n            from the given function.\n        description: An optional string description for the task.\n        tags: An optional set of tags to be associated with runs of this task. These\n            tags are combined with any tags defined by a `prefect.tags` context at\n            task runtime.\n        version: An optional string specifying the version of this task definition\n        cache_key_fn: An optional callable that, given the task run context and call\n            parameters, generates a string key; if the key matches a previous completed\n            state, that state result will be restored instead of running the task again.\n        cache_expiration: An optional amount of time indicating how long cached states\n            for this task should be restorable; if not provided, cached states will\n            never expire.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on task run failure\n        retry_delay_seconds: Optionally configures how long to wait before retrying the\n            task after failure. This is only applicable if `retries` is nonzero. This\n            setting can either be a number of seconds, a list of retry delays, or a\n            callable that, given the total number of retries, generates a list of retry\n            delays. If a number of seconds, that delay will be applied to all retries.\n            If a list, each retry will wait for the corresponding delay before retrying.\n            When passing a callable or a list, the number of configured retry delays\n            cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a retry\n            can be jittered in order to avoid a \"thundering herd\".\n        persist_result: An optional toggle indicating whether the result of this task\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this task.\n            Defaults to the value set in the flow the task is called in.\n        result_storage_key: An optional key to store the result in storage at when persisted.\n            Defaults to a unique identifier.\n        result_serializer: An optional serializer to use to serialize the result of this\n            task for persistence. Defaults to the value set in the flow the task is\n            called in.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the task. If the task exceeds this runtime, it will be marked as failed.\n        log_prints: If set, `print` statements in the task will be redirected to the\n            Prefect logger for the task run. Defaults to `None`, which indicates\n            that the value from the flow should be used.\n        refresh_cache: If set, cached results for the cache key are not used.\n            Defaults to `None`, which indicates that a cached result from a previous\n            execution with matching cache key is used.\n        on_failure: An optional list of callables to run when the task enters a failed state.\n        on_completion: An optional list of callables to run when the task enters a completed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state. Should\n            return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task\n            should end as failed. Defaults to `None`, indicating the task should always continue\n            to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n    Returns:\n        A callable `Task` object which, when called, will submit the task for execution.\n\n    Examples:\n        Define a simple task\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define an async task\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; async def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define a task with tags and a description\n\n        &gt;&gt;&gt; @task(tags={\"a\", \"b\"}, description=\"This task is empty but its my first!\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Define a task with a custom name\n\n        &gt;&gt;&gt; @task(name=\"The Ultimate Task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Define a task that retries 3 times with a 5 second delay between attempts\n\n        &gt;&gt;&gt; from random import randint\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(retries=3, retry_delay_seconds=5)\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     x = randint(0, 5)\n        &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n        &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n        &gt;&gt;&gt;     return x\n\n        Define a task that is cached for a day based on its inputs\n\n        &gt;&gt;&gt; from prefect.tasks import task_input_hash\n        &gt;&gt;&gt; from datetime import timedelta\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return \"hello\"\n    \"\"\"\n\n    if __fn:\n        return cast(\n            Task[P, R],\n            Task(\n                fn=__fn,\n                name=name,\n                description=description,\n                tags=tags,\n                version=version,\n                cache_key_fn=cache_key_fn,\n                cache_expiration=cache_expiration,\n                task_run_name=task_run_name,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                retry_jitter_factor=retry_jitter_factor,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_storage_key=result_storage_key,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                timeout_seconds=timeout_seconds,\n                log_prints=log_prints,\n                refresh_cache=refresh_cache,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                retry_condition_fn=retry_condition_fn,\n                viz_return_value=viz_return_value,\n            ),\n        )\n    else:\n        return cast(\n            Callable[[Callable[P, R]], Task[P, R]],\n            partial(\n                task,\n                name=name,\n                description=description,\n                tags=tags,\n                version=version,\n                cache_key_fn=cache_key_fn,\n                cache_expiration=cache_expiration,\n                task_run_name=task_run_name,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                retry_jitter_factor=retry_jitter_factor,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_storage_key=result_storage_key,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                timeout_seconds=timeout_seconds,\n                log_prints=log_prints,\n                refresh_cache=refresh_cache,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                retry_condition_fn=retry_condition_fn,\n                viz_return_value=viz_return_value,\n            ),\n        )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.task_input_hash","title":"<code>task_input_hash</code>","text":"<p>A task cache key implementation which hashes all inputs to the task using a JSON or cloudpickle serializer. If any arguments are not JSON serializable, the pickle serializer is used as a fallback. If cloudpickle fails, this will return a null key indicating that a cache key could not be generated for the given inputs.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>TaskRunContext</code> <p>the active <code>TaskRunContext</code></p> required <code>arguments</code> <code>Dict[str, Any]</code> <p>a dictionary of arguments to be passed to the underlying task</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>a string hash if hashing succeeded, else <code>None</code></p> Source code in <code>prefect/tasks.py</code> <pre><code>def task_input_hash(\n    context: \"TaskRunContext\", arguments: Dict[str, Any]\n) -&gt; Optional[str]:\n    \"\"\"\n    A task cache key implementation which hashes all inputs to the task using a JSON or\n    cloudpickle serializer. If any arguments are not JSON serializable, the pickle\n    serializer is used as a fallback. If cloudpickle fails, this will return a null key\n    indicating that a cache key could not be generated for the given inputs.\n\n    Arguments:\n        context: the active `TaskRunContext`\n        arguments: a dictionary of arguments to be passed to the underlying task\n\n    Returns:\n        a string hash if hashing succeeded, else `None`\n    \"\"\"\n    return hash_objects(\n        # We use the task key to get the qualified name for the task and include the\n        # task functions `co_code` bytes to avoid caching when the underlying function\n        # changes\n        context.task.task_key,\n        context.task.fn.__code__.co_code.hex(),\n        arguments,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/testing/","title":"prefect.testing","text":"","tags":["Python API","testing"]},{"location":"api-ref/prefect/testing/#prefect.testing","title":"<code>prefect.testing</code>","text":"","tags":["Python API","testing"]},{"location":"api-ref/prefect/variables/","title":"prefect.variables","text":"","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables","title":"<code>prefect.variables</code>","text":"","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable","title":"<code>Variable</code>","text":"<p>               Bases: <code>VariableCreate</code></p> <p>Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud. https://docs.prefect.io/latest/concepts/variables/</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <p>A string identifying the variable.</p> required <code>value</code> <p>A string that is the value of the variable.</p> required <code>tags</code> <p>An optional list of strings to associate with the variable.</p> required Source code in <code>prefect/variables.py</code> <pre><code>class Variable(VariableRequest):\n    \"\"\"\n    Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.\n    https://docs.prefect.io/latest/concepts/variables/\n\n    Arguments:\n        name: A string identifying the variable.\n        value: A string that is the value of the variable.\n        tags: An optional list of strings to associate with the variable.\n    \"\"\"\n\n    @classmethod\n    @sync_compatible\n    async def set(\n        cls,\n        name: str,\n        value: str,\n        tags: Optional[List[str]] = None,\n        overwrite: bool = False,\n    ) -&gt; Optional[str]:\n        \"\"\"\n        Sets a new variable. If one exists with the same name, user must pass `overwrite=True`\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            def my_flow():\n                var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n        ```\n        or\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            async def my_flow():\n                var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n        ```\n        \"\"\"\n        client, _ = get_or_create_client()\n        variable = await client.read_variable_by_name(name)\n        var_dict = {\"name\": name, \"value\": value}\n        var_dict[\"tags\"] = tags or []\n        if variable:\n            if not overwrite:\n                raise ValueError(\n                    \"You are attempting to save a variable with a name that is already in use. If you would like to overwrite the values that are saved, then call .set with `overwrite=True`.\"\n                )\n            var = VariableUpdateRequest(**var_dict)\n            await client.update_variable(variable=var)\n            variable = await client.read_variable_by_name(name)\n        else:\n            var = VariableRequest(**var_dict)\n            variable = await client.create_variable(variable=var)\n\n        return variable if variable else None\n\n    @classmethod\n    @sync_compatible\n    async def get(cls, name: str, default: Optional[str] = None) -&gt; Optional[str]:\n        \"\"\"\n        Get a variable by name. If doesn't exist return the default.\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            def my_flow():\n                var = Variable.get(\"my_var\")\n        ```\n        or\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            async def my_flow():\n                var = await Variable.get(\"my_var\")\n        ```\n        \"\"\"\n        client, _ = get_or_create_client()\n        variable = await client.read_variable_by_name(name)\n        return variable if variable else default\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable.get","title":"<code>get</code>  <code>async</code> <code>classmethod</code>","text":"<p>Get a variable by name. If doesn't exist return the default. <pre><code>    from prefect.variables import Variable\n\n    @flow\n    def my_flow():\n        var = Variable.get(\"my_var\")\n</code></pre> or <pre><code>    from prefect.variables import Variable\n\n    @flow\n    async def my_flow():\n        var = await Variable.get(\"my_var\")\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get(cls, name: str, default: Optional[str] = None) -&gt; Optional[str]:\n    \"\"\"\n    Get a variable by name. If doesn't exist return the default.\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        def my_flow():\n            var = Variable.get(\"my_var\")\n    ```\n    or\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        async def my_flow():\n            var = await Variable.get(\"my_var\")\n    ```\n    \"\"\"\n    client, _ = get_or_create_client()\n    variable = await client.read_variable_by_name(name)\n    return variable if variable else default\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable.set","title":"<code>set</code>  <code>async</code> <code>classmethod</code>","text":"<p>Sets a new variable. If one exists with the same name, user must pass <code>overwrite=True</code> <pre><code>    from prefect.variables import Variable\n\n    @flow\n    def my_flow():\n        var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n</code></pre> or <pre><code>    from prefect.variables import Variable\n\n    @flow\n    async def my_flow():\n        var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def set(\n    cls,\n    name: str,\n    value: str,\n    tags: Optional[List[str]] = None,\n    overwrite: bool = False,\n) -&gt; Optional[str]:\n    \"\"\"\n    Sets a new variable. If one exists with the same name, user must pass `overwrite=True`\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        def my_flow():\n            var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n    ```\n    or\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        async def my_flow():\n            var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n    ```\n    \"\"\"\n    client, _ = get_or_create_client()\n    variable = await client.read_variable_by_name(name)\n    var_dict = {\"name\": name, \"value\": value}\n    var_dict[\"tags\"] = tags or []\n    if variable:\n        if not overwrite:\n            raise ValueError(\n                \"You are attempting to save a variable with a name that is already in use. If you would like to overwrite the values that are saved, then call .set with `overwrite=True`.\"\n            )\n        var = VariableUpdateRequest(**var_dict)\n        await client.update_variable(variable=var)\n        variable = await client.read_variable_by_name(name)\n    else:\n        var = VariableRequest(**var_dict)\n        variable = await client.create_variable(variable=var)\n\n    return variable if variable else None\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.get","title":"<code>get</code>  <code>async</code>","text":"<p>Get a variable by name. If doesn't exist return the default. <pre><code>    from prefect import variables\n\n    @flow\n    def my_flow():\n        var = variables.get(\"my_var\")\n</code></pre> or <pre><code>    from prefect import variables\n\n    @flow\n    async def my_flow():\n        var = await variables.get(\"my_var\")\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@deprecated_callable(start_date=\"Apr 2024\")\n@sync_compatible\nasync def get(name: str, default: Optional[str] = None) -&gt; Optional[str]:\n    \"\"\"\n    Get a variable by name. If doesn't exist return the default.\n    ```\n        from prefect import variables\n\n        @flow\n        def my_flow():\n            var = variables.get(\"my_var\")\n    ```\n    or\n    ```\n        from prefect import variables\n\n        @flow\n        async def my_flow():\n            var = await variables.get(\"my_var\")\n    ```\n    \"\"\"\n    variable = await Variable.get(name)\n    return variable.value if variable else default\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/blocks/core/","title":"core","text":"","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core","title":"<code>prefect.blocks.core</code>","text":"","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block","title":"<code>Block</code>","text":"<p>               Bases: <code>BaseModel</code>, <code>ABC</code></p> <p>A base class for implementing a block that wraps an external service.</p> <p>This class can be defined with an arbitrary set of fields and methods, and couples business logic with data contained in an block document. <code>_block_document_name</code>, <code>_block_document_id</code>, <code>_block_schema_id</code>, and <code>_block_type_id</code> are reserved by Prefect as Block metadata fields, but otherwise a Block can implement arbitrary logic. Blocks can be instantiated without populating these metadata fields, but can only be used interactively, not with the Prefect API.</p> <p>Instead of the init method, a block implementation allows the definition of a <code>block_initialization</code> method that is called after initialization.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@register_base_type\n@instrument_method_calls_on_class_instances\nclass Block(BaseModel, ABC):\n    \"\"\"\n    A base class for implementing a block that wraps an external service.\n\n    This class can be defined with an arbitrary set of fields and methods, and\n    couples business logic with data contained in an block document.\n    `_block_document_name`, `_block_document_id`, `_block_schema_id`, and\n    `_block_type_id` are reserved by Prefect as Block metadata fields, but\n    otherwise a Block can implement arbitrary logic. Blocks can be instantiated\n    without populating these metadata fields, but can only be used interactively,\n    not with the Prefect API.\n\n    Instead of the __init__ method, a block implementation allows the\n    definition of a `block_initialization` method that is called after\n    initialization.\n    \"\"\"\n\n    class Config:\n        extra = \"allow\"\n\n        json_encoders = {SecretDict: lambda v: v.dict()}\n\n        @staticmethod\n        def schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n            \"\"\"\n            Customizes Pydantic's schema generation feature to add blocks related information.\n            \"\"\"\n            schema[\"block_type_slug\"] = model.get_block_type_slug()\n            # Ensures args and code examples aren't included in the schema\n            description = model.get_description()\n            if description:\n                schema[\"description\"] = description\n            else:\n                # Prevent the description of the base class from being included in the schema\n                schema.pop(\"description\", None)\n\n            # create a list of secret field names\n            # secret fields include both top-level keys and dot-delimited nested secret keys\n            # A wildcard (*) means that all fields under a given key are secret.\n            # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n            # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n            # nested under the \"child\" key are all secret. There is no limit to nesting.\n            secrets = schema[\"secret_fields\"] = []\n            for field in model.__fields__.values():\n                _collect_secret_fields(field.name, field.type_, secrets)\n\n            # create block schema references\n            refs = schema[\"block_schema_references\"] = {}\n\n            def collect_block_schema_references(\n                field_name: str, annotation: type\n            ) -&gt; None:\n                \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n                if Block.is_block_class(annotation):\n                    if isinstance(refs.get(field_name), list):\n                        refs[field_name].append(\n                            annotation._to_block_schema_reference_dict()\n                        )\n                    elif isinstance(refs.get(field_name), dict):\n                        refs[field_name] = [\n                            refs[field_name],\n                            annotation._to_block_schema_reference_dict(),\n                        ]\n                    else:\n                        refs[field_name] = annotation._to_block_schema_reference_dict()\n                if get_origin(annotation) in (Union, list, tuple, dict):\n                    for type_ in get_args(annotation):\n                        collect_block_schema_references(field_name, type_)\n\n            for field in model.__fields__.values():\n                collect_block_schema_references(field.name, field.type_)\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.block_initialization()\n\n    def __str__(self) -&gt; str:\n        return self.__repr__()\n\n    def __repr_args__(self):\n        repr_args = super().__repr_args__()\n        data_keys = self.schema()[\"properties\"].keys()\n        return [\n            (key, value) for key, value in repr_args if key is None or key in data_keys\n        ]\n\n    def block_initialization(self) -&gt; None:\n        pass\n\n    # -- private class variables\n    # set by the class itself\n\n    # Attribute to customize the name of the block type created\n    # when the block is registered with the API. If not set, block\n    # type name will default to the class name.\n    _block_type_name: Optional[str] = None\n    _block_type_slug: Optional[str] = None\n\n    # Attributes used to set properties on a block type when registered\n    # with the API.\n    _logo_url: Optional[HttpUrl] = None\n    _documentation_url: Optional[HttpUrl] = None\n    _description: Optional[str] = None\n    _code_example: Optional[str] = None\n\n    # -- private instance variables\n    # these are set when blocks are loaded from the API\n    _block_type_id: Optional[UUID] = None\n    _block_schema_id: Optional[UUID] = None\n    _block_schema_capabilities: Optional[List[str]] = None\n    _block_schema_version: Optional[str] = None\n    _block_document_id: Optional[UUID] = None\n    _block_document_name: Optional[str] = None\n    _is_anonymous: Optional[bool] = None\n\n    # Exclude `save` as it uses the `sync_compatible` decorator and needs to be\n    # decorated directly.\n    _events_excluded_methods = [\"block_initialization\", \"save\", \"dict\"]\n\n    @classmethod\n    def __dispatch_key__(cls):\n        if cls.__name__ == \"Block\":\n            return None  # The base class is abstract\n        return block_schema_to_key(cls._to_block_schema())\n\n    @classmethod\n    def get_block_type_name(cls):\n        return cls._block_type_name or cls.__name__\n\n    @classmethod\n    def get_block_type_slug(cls):\n        return slugify(cls._block_type_slug or cls.get_block_type_name())\n\n    @classmethod\n    def get_block_capabilities(cls) -&gt; FrozenSet[str]:\n        \"\"\"\n        Returns the block capabilities for this Block. Recursively collects all block\n        capabilities of all parent classes into a single frozenset.\n        \"\"\"\n        return frozenset(\n            {\n                c\n                for base in (cls,) + cls.__mro__\n                for c in getattr(base, \"_block_schema_capabilities\", []) or []\n            }\n        )\n\n    @classmethod\n    def _get_current_package_version(cls):\n        current_module = inspect.getmodule(cls)\n        if current_module:\n            top_level_module = sys.modules[\n                current_module.__name__.split(\".\")[0] or \"__main__\"\n            ]\n            try:\n                version = Version(top_level_module.__version__)\n                # Strips off any local version information\n                return version.base_version\n            except (AttributeError, InvalidVersion):\n                # Module does not have a __version__ attribute or is not a parsable format\n                pass\n        return DEFAULT_BLOCK_SCHEMA_VERSION\n\n    @classmethod\n    def get_block_schema_version(cls) -&gt; str:\n        return cls._block_schema_version or cls._get_current_package_version()\n\n    @classmethod\n    def _to_block_schema_reference_dict(cls):\n        return dict(\n            block_type_slug=cls.get_block_type_slug(),\n            block_schema_checksum=cls._calculate_schema_checksum(),\n        )\n\n    @classmethod\n    def _calculate_schema_checksum(\n        cls, block_schema_fields: Optional[Dict[str, Any]] = None\n    ):\n        \"\"\"\n        Generates a unique hash for the underlying schema of block.\n\n        Args:\n            block_schema_fields: Dictionary detailing block schema fields to generate a\n                checksum for. The fields of the current class is used if this parameter\n                is not provided.\n\n        Returns:\n            str: The calculated checksum prefixed with the hashing algorithm used.\n        \"\"\"\n        block_schema_fields = (\n            cls.schema() if block_schema_fields is None else block_schema_fields\n        )\n        fields_for_checksum = remove_nested_keys([\"secret_fields\"], block_schema_fields)\n        if fields_for_checksum.get(\"definitions\"):\n            non_block_definitions = _get_non_block_reference_definitions(\n                fields_for_checksum, fields_for_checksum[\"definitions\"]\n            )\n            if non_block_definitions:\n                fields_for_checksum[\"definitions\"] = non_block_definitions\n            else:\n                # Pop off definitions entirely instead of empty dict for consistency\n                # with the OpenAPI specification\n                fields_for_checksum.pop(\"definitions\")\n        checksum = hash_objects(fields_for_checksum, hash_algo=hashlib.sha256)\n        if checksum is None:\n            raise ValueError(\"Unable to compute checksum for block schema\")\n        else:\n            return f\"sha256:{checksum}\"\n\n    def _to_block_document(\n        self,\n        name: Optional[str] = None,\n        block_schema_id: Optional[UUID] = None,\n        block_type_id: Optional[UUID] = None,\n        is_anonymous: Optional[bool] = None,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Creates the corresponding block document based on the data stored in a block.\n        The corresponding block document name, block type ID, and block schema ID must\n        either be passed into the method or configured on the block.\n\n        Args:\n            name: The name of the created block document. Not required if anonymous.\n            block_schema_id: UUID of the corresponding block schema.\n            block_type_id: UUID of the corresponding block type.\n            is_anonymous: if True, an anonymous block is created. Anonymous\n                blocks are not displayed in the UI and used primarily for system\n                operations and features that need to automatically generate blocks.\n\n        Returns:\n            BlockDocument: Corresponding block document\n                populated with the block's configured data.\n        \"\"\"\n        if is_anonymous is None:\n            is_anonymous = self._is_anonymous or False\n\n        # name must be present if not anonymous\n        if not is_anonymous and not name and not self._block_document_name:\n            raise ValueError(\"No name provided, either as an argument or on the block.\")\n\n        if not block_schema_id and not self._block_schema_id:\n            raise ValueError(\n                \"No block schema ID provided, either as an argument or on the block.\"\n            )\n        if not block_type_id and not self._block_type_id:\n            raise ValueError(\n                \"No block type ID provided, either as an argument or on the block.\"\n            )\n\n        # The keys passed to `include` must NOT be aliases, else some items will be missed\n        # i.e. must do `self.schema_` vs `self.schema` to get a `schema_ = Field(alias=\"schema\")`\n        # reported from https://github.com/PrefectHQ/prefect-dbt/issues/54\n        data_keys = self.schema(by_alias=False)[\"properties\"].keys()\n\n        # `block_document_data`` must return the aliased version for it to show in the UI\n        block_document_data = self.dict(by_alias=True, include=data_keys)\n\n        # Iterate through and find blocks that already have saved block documents to\n        # create references to those saved block documents.\n        for key in data_keys:\n            field_value = getattr(self, key)\n            if (\n                isinstance(field_value, Block)\n                and field_value._block_document_id is not None\n            ):\n                block_document_data[key] = {\n                    \"$ref\": {\"block_document_id\": field_value._block_document_id}\n                }\n\n        return BlockDocument(\n            id=self._block_document_id or uuid4(),\n            name=(name or self._block_document_name) if not is_anonymous else None,\n            block_schema_id=block_schema_id or self._block_schema_id,\n            block_type_id=block_type_id or self._block_type_id,\n            data=block_document_data,\n            block_schema=self._to_block_schema(\n                block_type_id=block_type_id or self._block_type_id,\n            ),\n            block_type=self._to_block_type(),\n            is_anonymous=is_anonymous,\n        )\n\n    @classmethod\n    def _to_block_schema(cls, block_type_id: Optional[UUID] = None) -&gt; BlockSchema:\n        \"\"\"\n        Creates the corresponding block schema of the block.\n        The corresponding block_type_id must either be passed into\n        the method or configured on the block.\n\n        Args:\n            block_type_id: UUID of the corresponding block type.\n\n        Returns:\n            BlockSchema: The corresponding block schema.\n        \"\"\"\n        fields = cls.schema()\n        return BlockSchema(\n            id=cls._block_schema_id if cls._block_schema_id is not None else uuid4(),\n            checksum=cls._calculate_schema_checksum(),\n            fields=fields,\n            block_type_id=block_type_id or cls._block_type_id,\n            block_type=cls._to_block_type(),\n            capabilities=list(cls.get_block_capabilities()),\n            version=cls.get_block_schema_version(),\n        )\n\n    @classmethod\n    def _parse_docstring(cls) -&gt; List[DocstringSection]:\n        \"\"\"\n        Parses the docstring into list of DocstringSection objects.\n        Helper method used primarily to suppress irrelevant logs, e.g.\n        `&lt;module&gt;:11: No type or annotation for parameter 'write_json'`\n        because griffe is unable to parse the types from pydantic.BaseModel.\n        \"\"\"\n        with disable_logger(\"griffe.docstrings.google\"):\n            with disable_logger(\"griffe.agents.nodes\"):\n                docstring = Docstring(cls.__doc__)\n                parsed = parse(docstring, Parser.google)\n        return parsed\n\n    @classmethod\n    def get_description(cls) -&gt; Optional[str]:\n        \"\"\"\n        Returns the description for the current block. Attempts to parse\n        description from class docstring if an override is not defined.\n        \"\"\"\n        description = cls._description\n        # If no description override has been provided, find the first text section\n        # and use that as the description\n        if description is None and cls.__doc__ is not None:\n            parsed = cls._parse_docstring()\n            parsed_description = next(\n                (\n                    section.as_dict().get(\"value\")\n                    for section in parsed\n                    if section.kind == DocstringSectionKind.text\n                ),\n                None,\n            )\n            if isinstance(parsed_description, str):\n                description = parsed_description.strip()\n        return description\n\n    @classmethod\n    def get_code_example(cls) -&gt; Optional[str]:\n        \"\"\"\n        Returns the code example for the given block. Attempts to parse\n        code example from the class docstring if an override is not provided.\n        \"\"\"\n        code_example = (\n            dedent(cls._code_example) if cls._code_example is not None else None\n        )\n        # If no code example override has been provided, attempt to find a examples\n        # section or an admonition with the annotation \"example\" and use that as the\n        # code example\n        if code_example is None and cls.__doc__ is not None:\n            parsed = cls._parse_docstring()\n            for section in parsed:\n                # Section kind will be \"examples\" if Examples section heading is used.\n                if section.kind == DocstringSectionKind.examples:\n                    # Examples sections are made up of smaller sections that need to be\n                    # joined with newlines. Smaller sections are represented as tuples\n                    # with shape (DocstringSectionKind, str)\n                    code_example = \"\\n\".join(\n                        (part[1] for part in section.as_dict().get(\"value\", []))\n                    )\n                    break\n                # Section kind will be \"admonition\" if Example section heading is used.\n                if section.kind == DocstringSectionKind.admonition:\n                    value = section.as_dict().get(\"value\", {})\n                    if value.get(\"annotation\") == \"example\":\n                        code_example = value.get(\"description\")\n                        break\n\n        if code_example is None:\n            # If no code example has been specified or extracted from the class\n            # docstring, generate a sensible default\n            code_example = cls._generate_code_example()\n\n        return code_example\n\n    @classmethod\n    def _generate_code_example(cls) -&gt; str:\n        \"\"\"Generates a default code example for the current class\"\"\"\n        qualified_name = to_qualified_name(cls)\n        module_str = \".\".join(qualified_name.split(\".\")[:-1])\n        class_name = cls.__name__\n        block_variable_name = f'{cls.get_block_type_slug().replace(\"-\", \"_\")}_block'\n\n        return dedent(\n            f\"\"\"\\\n        ```python\n        from {module_str} import {class_name}\n\n        {block_variable_name} = {class_name}.load(\"BLOCK_NAME\")\n        ```\"\"\"\n        )\n\n    @classmethod\n    def _to_block_type(cls) -&gt; BlockType:\n        \"\"\"\n        Creates the corresponding block type of the block.\n\n        Returns:\n            BlockType: The corresponding block type.\n        \"\"\"\n        return BlockType(\n            id=cls._block_type_id or uuid4(),\n            slug=cls.get_block_type_slug(),\n            name=cls.get_block_type_name(),\n            logo_url=cls._logo_url,\n            documentation_url=cls._documentation_url,\n            description=cls.get_description(),\n            code_example=cls.get_code_example(),\n        )\n\n    @classmethod\n    def _from_block_document(cls, block_document: BlockDocument):\n        \"\"\"\n        Instantiates a block from a given block document. The corresponding block class\n        will be looked up in the block registry based on the corresponding block schema\n        of the provided block document.\n\n        Args:\n            block_document: The block document used to instantiate a block.\n\n        Raises:\n            ValueError: If the provided block document doesn't have a corresponding block\n                schema.\n\n        Returns:\n            Block: Hydrated block with data from block document.\n        \"\"\"\n        if block_document.block_schema is None:\n            raise ValueError(\n                \"Unable to determine block schema for provided block document\"\n            )\n\n        block_cls = (\n            cls\n            if cls.__name__ != \"Block\"\n            # Look up the block class by dispatch\n            else cls.get_block_class_from_schema(block_document.block_schema)\n        )\n\n        block_cls = instrument_method_calls_on_class_instances(block_cls)\n\n        block = block_cls.parse_obj(block_document.data)\n        block._block_document_id = block_document.id\n        block.__class__._block_schema_id = block_document.block_schema_id\n        block.__class__._block_type_id = block_document.block_type_id\n        block._block_document_name = block_document.name\n        block._is_anonymous = block_document.is_anonymous\n        block._define_metadata_on_nested_blocks(\n            block_document.block_document_references\n        )\n\n        # Due to the way blocks are loaded we can't directly instrument the\n        # `load` method and have the data be about the block document. Instead\n        # this will emit a proxy event for the load method so that block\n        # document data can be included instead of the event being about an\n        # 'anonymous' block.\n\n        emit_instance_method_called_event(block, \"load\", successful=True)\n\n        return block\n\n    def _event_kind(self) -&gt; str:\n        return f\"prefect.block.{self.get_block_type_slug()}\"\n\n    def _event_method_called_resources(self) -&gt; Optional[ResourceTuple]:\n        if not (self._block_document_id and self._block_document_name):\n            return None\n\n        return (\n            {\n                \"prefect.resource.id\": (\n                    f\"prefect.block-document.{self._block_document_id}\"\n                ),\n                \"prefect.resource.name\": self._block_document_name,\n            },\n            [\n                {\n                    \"prefect.resource.id\": (\n                        f\"prefect.block-type.{self.get_block_type_slug()}\"\n                    ),\n                    \"prefect.resource.role\": \"block-type\",\n                }\n            ],\n        )\n\n    @classmethod\n    def get_block_class_from_schema(cls: Type[Self], schema: BlockSchema) -&gt; Type[Self]:\n        \"\"\"\n        Retrieve the block class implementation given a schema.\n        \"\"\"\n        return cls.get_block_class_from_key(block_schema_to_key(schema))\n\n    @classmethod\n    def get_block_class_from_key(cls: Type[Self], key: str) -&gt; Type[Self]:\n        \"\"\"\n        Retrieve the block class implementation given a key.\n        \"\"\"\n        # Ensure collections are imported and have the opportunity to register types\n        # before looking up the block class\n        prefect.plugins.load_prefect_collections()\n\n        return lookup_type(cls, key)\n\n    def _define_metadata_on_nested_blocks(\n        self, block_document_references: Dict[str, Dict[str, Any]]\n    ):\n        \"\"\"\n        Recursively populates metadata fields on nested blocks based on the\n        provided block document references.\n        \"\"\"\n        for item in block_document_references.items():\n            field_name, block_document_reference = item\n            nested_block = getattr(self, field_name)\n            if isinstance(nested_block, Block):\n                nested_block_document_info = block_document_reference.get(\n                    \"block_document\", {}\n                )\n                nested_block._define_metadata_on_nested_blocks(\n                    nested_block_document_info.get(\"block_document_references\", {})\n                )\n                nested_block_document_id = nested_block_document_info.get(\"id\")\n                nested_block._block_document_id = (\n                    UUID(nested_block_document_id) if nested_block_document_id else None\n                )\n                nested_block._block_document_name = nested_block_document_info.get(\n                    \"name\"\n                )\n                nested_block._is_anonymous = nested_block_document_info.get(\n                    \"is_anonymous\"\n                )\n\n    @classmethod\n    @inject_client\n    async def _get_block_document(\n        cls,\n        name: str,\n        client: \"PrefectClient\" = None,\n    ):\n        if cls.__name__ == \"Block\":\n            block_type_slug, block_document_name = name.split(\"/\", 1)\n        else:\n            block_type_slug = cls.get_block_type_slug()\n            block_document_name = name\n\n        try:\n            block_document = await client.read_block_document_by_name(\n                name=block_document_name, block_type_slug=block_type_slug\n            )\n        except prefect.exceptions.ObjectNotFound as e:\n            raise ValueError(\n                f\"Unable to find block document named {block_document_name} for block\"\n                f\" type {block_type_slug}\"\n            ) from e\n\n        return block_document, block_document_name\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def load(\n        cls,\n        name: str,\n        validate: bool = True,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Retrieves data from the block document with the given name for the block type\n        that corresponds with the current class and returns an instantiated version of\n        the current class with the data stored in the block document.\n\n        If a block document for a given block type is saved with a different schema\n        than the current class calling `load`, a warning will be raised.\n\n        If the current class schema is a subset of the block document schema, the block\n        can be loaded as normal using the default `validate = True`.\n\n        If the current class schema is a superset of the block document schema, `load`\n        must be called with `validate` set to False to prevent a validation error. In\n        this case, the block attributes will default to `None` and must be set manually\n        and saved to a new block document before the block can be used as expected.\n\n        Args:\n            name: The name or slug of the block document. A block document slug is a\n                string with the format &lt;block_type_slug&gt;/&lt;block_document_name&gt;\n            validate: If False, the block document will be loaded without Pydantic\n                validating the block schema. This is useful if the block schema has\n                changed client-side since the block document referred to by `name` was saved.\n            client: The client to use to load the block document. If not provided, the\n                default client will be injected.\n\n        Raises:\n            ValueError: If the requested block document is not found.\n\n        Returns:\n            An instance of the current class hydrated with the data stored in the\n            block document with the specified name.\n\n        Examples:\n            Load from a Block subclass with a block document name:\n            ```python\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            loaded_block = Custom.load(\"my-custom-message\")\n            ```\n\n            Load from Block with a block document slug:\n            ```python\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            loaded_block = Block.load(\"custom/my-custom-message\")\n            ```\n\n            Migrate a block document to a new schema:\n            ```python\n            # original class\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            # Updated class with new required field\n            class Custom(Block):\n                message: str\n                number_of_ducks: int\n\n            loaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n            # Prints UserWarning about schema mismatch\n\n            loaded_block.number_of_ducks = 42\n\n            loaded_block.save(\"my-custom-message\", overwrite=True)\n            ```\n        \"\"\"\n        block_document, block_document_name = await cls._get_block_document(name)\n\n        try:\n            return cls._from_block_document(block_document)\n        except ValidationError as e:\n            if not validate:\n                missing_fields = tuple(err[\"loc\"][0] for err in e.errors())\n                missing_block_data = {field: None for field in missing_fields}\n                warnings.warn(\n                    f\"Could not fully load {block_document_name!r} of block type\"\n                    f\" {cls._block_type_slug!r} - this is likely because one or more\"\n                    \" required fields were added to the schema for\"\n                    f\" {cls.__name__!r} that did not exist on the class when this block\"\n                    \" was last saved. Please specify values for new field(s):\"\n                    f\" {listrepr(missing_fields)}, then run\"\n                    f' `{cls.__name__}.save(\"{block_document_name}\", overwrite=True)`,'\n                    \" and load this block again before attempting to use it.\"\n                )\n                return cls.construct(**block_document.data, **missing_block_data)\n            raise RuntimeError(\n                f\"Unable to load {block_document_name!r} of block type\"\n                f\" {cls._block_type_slug!r} due to failed validation. To load without\"\n                \" validation, try loading again with `validate=False`.\"\n            ) from e\n\n    @staticmethod\n    def is_block_class(block) -&gt; bool:\n        return _is_subclass(block, Block)\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def register_type_and_schema(cls, client: \"PrefectClient\" = None):\n        \"\"\"\n        Makes block available for configuration with current Prefect API.\n        Recursively registers all nested blocks. Registration is idempotent.\n\n        Args:\n            client: Optional client to use for registering type and schema with the\n                Prefect API. A new client will be created and used if one is not\n                provided.\n        \"\"\"\n        if cls.__name__ == \"Block\":\n            raise InvalidBlockRegistration(\n                \"`register_type_and_schema` should be called on a Block \"\n                \"subclass and not on the Block class directly.\"\n            )\n        if ABC in getattr(cls, \"__bases__\", []):\n            raise InvalidBlockRegistration(\n                \"`register_type_and_schema` should be called on a Block \"\n                \"subclass and not on a Block interface class directly.\"\n            )\n\n        async def register_blocks_in_annotation(annotation: type) -&gt; None:\n            \"\"\"Walk through the annotation and register any nested blocks.\"\"\"\n            if Block.is_block_class(annotation):\n                await annotation.register_type_and_schema(client=client)\n            elif get_origin(annotation) in (Union, tuple, list, dict):\n                for inner_annotation in get_args(annotation):\n                    await register_blocks_in_annotation(inner_annotation)\n\n        for field in cls.__fields__.values():\n            await register_blocks_in_annotation(field.annotation)\n\n        try:\n            block_type = await client.read_block_type_by_slug(\n                slug=cls.get_block_type_slug()\n            )\n            cls._block_type_id = block_type.id\n            local_block_type = cls._to_block_type()\n            if _should_update_block_type(\n                local_block_type=local_block_type, server_block_type=block_type\n            ):\n                await client.update_block_type(\n                    block_type_id=block_type.id, block_type=local_block_type\n                )\n        except prefect.exceptions.ObjectNotFound:\n            block_type = await client.create_block_type(block_type=cls._to_block_type())\n            cls._block_type_id = block_type.id\n\n        try:\n            block_schema = await client.read_block_schema_by_checksum(\n                checksum=cls._calculate_schema_checksum(),\n                version=cls.get_block_schema_version(),\n            )\n        except prefect.exceptions.ObjectNotFound:\n            block_schema = await client.create_block_schema(\n                block_schema=cls._to_block_schema(block_type_id=block_type.id)\n            )\n\n        cls._block_schema_id = block_schema.id\n\n    @inject_client\n    async def _save(\n        self,\n        name: Optional[str] = None,\n        is_anonymous: bool = False,\n        overwrite: bool = False,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Saves the values of a block as a block document with an option to save as an\n        anonymous block document.\n\n        Args:\n            name: User specified name to give saved block document which can later be used to load the\n                block document.\n            is_anonymous: Boolean value specifying whether the block document is anonymous. Anonymous\n                blocks are intended for system use and are not shown in the UI. Anonymous blocks do not\n                require a user-supplied name.\n            overwrite: Boolean value specifying if values should be overwritten if a block document with\n                the specified name already exists.\n\n        Raises:\n            ValueError: If a name is not given and `is_anonymous` is `False` or a name is given and\n                `is_anonymous` is `True`.\n        \"\"\"\n        if name is None and not is_anonymous:\n            if self._block_document_name is None:\n                raise ValueError(\n                    \"You're attempting to save a block document without a name.\"\n                    \" Please either call `save` with a `name` or pass\"\n                    \" `is_anonymous=True` to save an anonymous block.\"\n                )\n            else:\n                name = self._block_document_name\n\n        self._is_anonymous = is_anonymous\n\n        # Ensure block type and schema are registered before saving block document.\n        await self.register_type_and_schema(client=client)\n\n        try:\n            block_document = await client.create_block_document(\n                block_document=self._to_block_document(name=name)\n            )\n        except prefect.exceptions.ObjectAlreadyExists as err:\n            if overwrite:\n                block_document_id = self._block_document_id\n                if block_document_id is None:\n                    existing_block_document = await client.read_block_document_by_name(\n                        name=name, block_type_slug=self.get_block_type_slug()\n                    )\n                    block_document_id = existing_block_document.id\n                await client.update_block_document(\n                    block_document_id=block_document_id,\n                    block_document=self._to_block_document(name=name),\n                )\n                block_document = await client.read_block_document(\n                    block_document_id=block_document_id\n                )\n            else:\n                raise ValueError(\n                    \"You are attempting to save values with a name that is already in\"\n                    \" use for this block type. If you would like to overwrite the\"\n                    \" values that are saved, then save with `overwrite=True`.\"\n                ) from err\n\n        # Update metadata on block instance for later use.\n        self._block_document_name = block_document.name\n        self._block_document_id = block_document.id\n        return self._block_document_id\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def save(\n        self,\n        name: Optional[str] = None,\n        overwrite: bool = False,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Saves the values of a block as a block document.\n\n        Args:\n            name: User specified name to give saved block document which can later be used to load the\n                block document.\n            overwrite: Boolean value specifying if values should be overwritten if a block document with\n                the specified name already exists.\n\n        \"\"\"\n        document_id = await self._save(name=name, overwrite=overwrite, client=client)\n\n        return document_id\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def delete(\n        cls,\n        name: str,\n        client: \"PrefectClient\" = None,\n    ):\n        block_document, block_document_name = await cls._get_block_document(name)\n\n        await client.delete_block_document(block_document.id)\n\n    def _iter(self, *, include=None, exclude=None, **kwargs):\n        # Injects the `block_type_slug` into serialized payloads for dispatch\n        for key_value in super()._iter(include=include, exclude=exclude, **kwargs):\n            yield key_value\n\n        # Respect inclusion and exclusion still\n        if include and \"block_type_slug\" not in include:\n            return\n        if exclude and \"block_type_slug\" in exclude:\n            return\n\n        yield \"block_type_slug\", self.get_block_type_slug()\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        \"\"\"\n        Create an instance of the Block subclass type if a `block_type_slug` is\n        present in the data payload.\n        \"\"\"\n        block_type_slug = kwargs.pop(\"block_type_slug\", None)\n        if block_type_slug:\n            subcls = lookup_type(cls, dispatch_key=block_type_slug)\n            m = super().__new__(subcls)\n            # NOTE: This is a workaround for an obscure issue where copied models were\n            #       missing attributes. This pattern is from Pydantic's\n            #       `BaseModel._copy_and_set_values`.\n            #       The issue this fixes could not be reproduced in unit tests that\n            #       directly targeted dispatch handling and was only observed when\n            #       copying then saving infrastructure blocks on deployment models.\n            object.__setattr__(m, \"__dict__\", kwargs)\n            object.__setattr__(m, \"__fields_set__\", set(kwargs.keys()))\n            return m\n        else:\n            m = super().__new__(cls)\n            object.__setattr__(m, \"__dict__\", kwargs)\n            object.__setattr__(m, \"__fields_set__\", set(kwargs.keys()))\n            return m\n\n    def get_block_placeholder(self) -&gt; str:\n        \"\"\"\n        Returns the block placeholder for the current block which can be used for\n        templating.\n\n        Returns:\n            str: The block placeholder for the current block in the format\n                `prefect.blocks.{block_type_name}.{block_document_name}`\n\n        Raises:\n            BlockNotSavedError: Raised if the block has not been saved.\n\n        If a block has not been saved, the return value will be `None`.\n        \"\"\"\n        block_document_name = self._block_document_name\n        if not block_document_name:\n            raise BlockNotSavedError(\n                \"Could not generate block placeholder for unsaved block.\"\n            )\n\n        return f\"prefect.blocks.{self.get_block_type_slug()}.{block_document_name}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.Config","title":"<code>Config</code>","text":"Source code in <code>prefect/blocks/core.py</code> <pre><code>class Config:\n    extra = \"allow\"\n\n    json_encoders = {SecretDict: lambda v: v.dict()}\n\n    @staticmethod\n    def schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n        \"\"\"\n        Customizes Pydantic's schema generation feature to add blocks related information.\n        \"\"\"\n        schema[\"block_type_slug\"] = model.get_block_type_slug()\n        # Ensures args and code examples aren't included in the schema\n        description = model.get_description()\n        if description:\n            schema[\"description\"] = description\n        else:\n            # Prevent the description of the base class from being included in the schema\n            schema.pop(\"description\", None)\n\n        # create a list of secret field names\n        # secret fields include both top-level keys and dot-delimited nested secret keys\n        # A wildcard (*) means that all fields under a given key are secret.\n        # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n        # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n        # nested under the \"child\" key are all secret. There is no limit to nesting.\n        secrets = schema[\"secret_fields\"] = []\n        for field in model.__fields__.values():\n            _collect_secret_fields(field.name, field.type_, secrets)\n\n        # create block schema references\n        refs = schema[\"block_schema_references\"] = {}\n\n        def collect_block_schema_references(\n            field_name: str, annotation: type\n        ) -&gt; None:\n            \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n            if Block.is_block_class(annotation):\n                if isinstance(refs.get(field_name), list):\n                    refs[field_name].append(\n                        annotation._to_block_schema_reference_dict()\n                    )\n                elif isinstance(refs.get(field_name), dict):\n                    refs[field_name] = [\n                        refs[field_name],\n                        annotation._to_block_schema_reference_dict(),\n                    ]\n                else:\n                    refs[field_name] = annotation._to_block_schema_reference_dict()\n            if get_origin(annotation) in (Union, list, tuple, dict):\n                for type_ in get_args(annotation):\n                    collect_block_schema_references(field_name, type_)\n\n        for field in model.__fields__.values():\n            collect_block_schema_references(field.name, field.type_)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.Config.schema_extra","title":"<code>schema_extra</code>  <code>staticmethod</code>","text":"<p>Customizes Pydantic's schema generation feature to add blocks related information.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@staticmethod\ndef schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n    \"\"\"\n    Customizes Pydantic's schema generation feature to add blocks related information.\n    \"\"\"\n    schema[\"block_type_slug\"] = model.get_block_type_slug()\n    # Ensures args and code examples aren't included in the schema\n    description = model.get_description()\n    if description:\n        schema[\"description\"] = description\n    else:\n        # Prevent the description of the base class from being included in the schema\n        schema.pop(\"description\", None)\n\n    # create a list of secret field names\n    # secret fields include both top-level keys and dot-delimited nested secret keys\n    # A wildcard (*) means that all fields under a given key are secret.\n    # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n    # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n    # nested under the \"child\" key are all secret. There is no limit to nesting.\n    secrets = schema[\"secret_fields\"] = []\n    for field in model.__fields__.values():\n        _collect_secret_fields(field.name, field.type_, secrets)\n\n    # create block schema references\n    refs = schema[\"block_schema_references\"] = {}\n\n    def collect_block_schema_references(\n        field_name: str, annotation: type\n    ) -&gt; None:\n        \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n        if Block.is_block_class(annotation):\n            if isinstance(refs.get(field_name), list):\n                refs[field_name].append(\n                    annotation._to_block_schema_reference_dict()\n                )\n            elif isinstance(refs.get(field_name), dict):\n                refs[field_name] = [\n                    refs[field_name],\n                    annotation._to_block_schema_reference_dict(),\n                ]\n            else:\n                refs[field_name] = annotation._to_block_schema_reference_dict()\n        if get_origin(annotation) in (Union, list, tuple, dict):\n            for type_ in get_args(annotation):\n                collect_block_schema_references(field_name, type_)\n\n    for field in model.__fields__.values():\n        collect_block_schema_references(field.name, field.type_)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_capabilities","title":"<code>get_block_capabilities</code>  <code>classmethod</code>","text":"<p>Returns the block capabilities for this Block. Recursively collects all block capabilities of all parent classes into a single frozenset.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_capabilities(cls) -&gt; FrozenSet[str]:\n    \"\"\"\n    Returns the block capabilities for this Block. Recursively collects all block\n    capabilities of all parent classes into a single frozenset.\n    \"\"\"\n    return frozenset(\n        {\n            c\n            for base in (cls,) + cls.__mro__\n            for c in getattr(base, \"_block_schema_capabilities\", []) or []\n        }\n    )\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_class_from_key","title":"<code>get_block_class_from_key</code>  <code>classmethod</code>","text":"<p>Retrieve the block class implementation given a key.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_class_from_key(cls: Type[Self], key: str) -&gt; Type[Self]:\n    \"\"\"\n    Retrieve the block class implementation given a key.\n    \"\"\"\n    # Ensure collections are imported and have the opportunity to register types\n    # before looking up the block class\n    prefect.plugins.load_prefect_collections()\n\n    return lookup_type(cls, key)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_class_from_schema","title":"<code>get_block_class_from_schema</code>  <code>classmethod</code>","text":"<p>Retrieve the block class implementation given a schema.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_class_from_schema(cls: Type[Self], schema: BlockSchema) -&gt; Type[Self]:\n    \"\"\"\n    Retrieve the block class implementation given a schema.\n    \"\"\"\n    return cls.get_block_class_from_key(block_schema_to_key(schema))\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_placeholder","title":"<code>get_block_placeholder</code>","text":"<p>Returns the block placeholder for the current block which can be used for templating.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The block placeholder for the current block in the format <code>prefect.blocks.{block_type_name}.{block_document_name}</code></p> <p>Raises:</p> Type Description <code>BlockNotSavedError</code> <p>Raised if the block has not been saved.</p> <p>If a block has not been saved, the return value will be <code>None</code>.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>def get_block_placeholder(self) -&gt; str:\n    \"\"\"\n    Returns the block placeholder for the current block which can be used for\n    templating.\n\n    Returns:\n        str: The block placeholder for the current block in the format\n            `prefect.blocks.{block_type_name}.{block_document_name}`\n\n    Raises:\n        BlockNotSavedError: Raised if the block has not been saved.\n\n    If a block has not been saved, the return value will be `None`.\n    \"\"\"\n    block_document_name = self._block_document_name\n    if not block_document_name:\n        raise BlockNotSavedError(\n            \"Could not generate block placeholder for unsaved block.\"\n        )\n\n    return f\"prefect.blocks.{self.get_block_type_slug()}.{block_document_name}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_code_example","title":"<code>get_code_example</code>  <code>classmethod</code>","text":"<p>Returns the code example for the given block. Attempts to parse code example from the class docstring if an override is not provided.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_code_example(cls) -&gt; Optional[str]:\n    \"\"\"\n    Returns the code example for the given block. Attempts to parse\n    code example from the class docstring if an override is not provided.\n    \"\"\"\n    code_example = (\n        dedent(cls._code_example) if cls._code_example is not None else None\n    )\n    # If no code example override has been provided, attempt to find a examples\n    # section or an admonition with the annotation \"example\" and use that as the\n    # code example\n    if code_example is None and cls.__doc__ is not None:\n        parsed = cls._parse_docstring()\n        for section in parsed:\n            # Section kind will be \"examples\" if Examples section heading is used.\n            if section.kind == DocstringSectionKind.examples:\n                # Examples sections are made up of smaller sections that need to be\n                # joined with newlines. Smaller sections are represented as tuples\n                # with shape (DocstringSectionKind, str)\n                code_example = \"\\n\".join(\n                    (part[1] for part in section.as_dict().get(\"value\", []))\n                )\n                break\n            # Section kind will be \"admonition\" if Example section heading is used.\n            if section.kind == DocstringSectionKind.admonition:\n                value = section.as_dict().get(\"value\", {})\n                if value.get(\"annotation\") == \"example\":\n                    code_example = value.get(\"description\")\n                    break\n\n    if code_example is None:\n        # If no code example has been specified or extracted from the class\n        # docstring, generate a sensible default\n        code_example = cls._generate_code_example()\n\n    return code_example\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_description","title":"<code>get_description</code>  <code>classmethod</code>","text":"<p>Returns the description for the current block. Attempts to parse description from class docstring if an override is not defined.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_description(cls) -&gt; Optional[str]:\n    \"\"\"\n    Returns the description for the current block. Attempts to parse\n    description from class docstring if an override is not defined.\n    \"\"\"\n    description = cls._description\n    # If no description override has been provided, find the first text section\n    # and use that as the description\n    if description is None and cls.__doc__ is not None:\n        parsed = cls._parse_docstring()\n        parsed_description = next(\n            (\n                section.as_dict().get(\"value\")\n                for section in parsed\n                if section.kind == DocstringSectionKind.text\n            ),\n            None,\n        )\n        if isinstance(parsed_description, str):\n            description = parsed_description.strip()\n    return description\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document.</p> <p>If a block document for a given block type is saved with a different schema than the current class calling <code>load</code>, a warning will be raised.</p> <p>If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default <code>validate = True</code>.</p> <p>If the current class schema is a superset of the block document schema, <code>load</code> must be called with <code>validate</code> set to False to prevent a validation error. In this case, the block attributes will default to <code>None</code> and must be set manually and saved to a new block document before the block can be used as expected.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name or slug of the block document. A block document slug is a string with the format / required <code>validate</code> <code>bool</code> <p>If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by <code>name</code> was saved.</p> <code>True</code> <code>client</code> <code>PrefectClient</code> <p>The client to use to load the block document. If not provided, the default client will be injected.</p> <code>None</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the requested block document is not found.</p> <p>Returns:</p> Type Description <p>An instance of the current class hydrated with the data stored in the</p> <p>block document with the specified name.</p> <p>Examples:</p> <p>Load from a Block subclass with a block document name: <pre><code>class Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\nloaded_block = Custom.load(\"my-custom-message\")\n</code></pre></p> <p>Load from Block with a block document slug: <pre><code>class Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\nloaded_block = Block.load(\"custom/my-custom-message\")\n</code></pre></p> <p>Migrate a block document to a new schema: <pre><code># original class\nclass Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\n# Updated class with new required field\nclass Custom(Block):\n    message: str\n    number_of_ducks: int\n\nloaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n# Prints UserWarning about schema mismatch\n\nloaded_block.number_of_ducks = 42\n\nloaded_block.save(\"my-custom-message\", overwrite=True)\n</code></pre></p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\n@sync_compatible\n@inject_client\nasync def load(\n    cls,\n    name: str,\n    validate: bool = True,\n    client: \"PrefectClient\" = None,\n):\n    \"\"\"\n    Retrieves data from the block document with the given name for the block type\n    that corresponds with the current class and returns an instantiated version of\n    the current class with the data stored in the block document.\n\n    If a block document for a given block type is saved with a different schema\n    than the current class calling `load`, a warning will be raised.\n\n    If the current class schema is a subset of the block document schema, the block\n    can be loaded as normal using the default `validate = True`.\n\n    If the current class schema is a superset of the block document schema, `load`\n    must be called with `validate` set to False to prevent a validation error. In\n    this case, the block attributes will default to `None` and must be set manually\n    and saved to a new block document before the block can be used as expected.\n\n    Args:\n        name: The name or slug of the block document. A block document slug is a\n            string with the format &lt;block_type_slug&gt;/&lt;block_document_name&gt;\n        validate: If False, the block document will be loaded without Pydantic\n            validating the block schema. This is useful if the block schema has\n            changed client-side since the block document referred to by `name` was saved.\n        client: The client to use to load the block document. If not provided, the\n            default client will be injected.\n\n    Raises:\n        ValueError: If the requested block document is not found.\n\n    Returns:\n        An instance of the current class hydrated with the data stored in the\n        block document with the specified name.\n\n    Examples:\n        Load from a Block subclass with a block document name:\n        ```python\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        loaded_block = Custom.load(\"my-custom-message\")\n        ```\n\n        Load from Block with a block document slug:\n        ```python\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        loaded_block = Block.load(\"custom/my-custom-message\")\n        ```\n\n        Migrate a block document to a new schema:\n        ```python\n        # original class\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        # Updated class with new required field\n        class Custom(Block):\n            message: str\n            number_of_ducks: int\n\n        loaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n        # Prints UserWarning about schema mismatch\n\n        loaded_block.number_of_ducks = 42\n\n        loaded_block.save(\"my-custom-message\", overwrite=True)\n        ```\n    \"\"\"\n    block_document, block_document_name = await cls._get_block_document(name)\n\n    try:\n        return cls._from_block_document(block_document)\n    except ValidationError as e:\n        if not validate:\n            missing_fields = tuple(err[\"loc\"][0] for err in e.errors())\n            missing_block_data = {field: None for field in missing_fields}\n            warnings.warn(\n                f\"Could not fully load {block_document_name!r} of block type\"\n                f\" {cls._block_type_slug!r} - this is likely because one or more\"\n                \" required fields were added to the schema for\"\n                f\" {cls.__name__!r} that did not exist on the class when this block\"\n                \" was last saved. Please specify values for new field(s):\"\n                f\" {listrepr(missing_fields)}, then run\"\n                f' `{cls.__name__}.save(\"{block_document_name}\", overwrite=True)`,'\n                \" and load this block again before attempting to use it.\"\n            )\n            return cls.construct(**block_document.data, **missing_block_data)\n        raise RuntimeError(\n            f\"Unable to load {block_document_name!r} of block type\"\n            f\" {cls._block_type_slug!r} due to failed validation. To load without\"\n            \" validation, try loading again with `validate=False`.\"\n        ) from e\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.register_type_and_schema","title":"<code>register_type_and_schema</code>  <code>async</code> <code>classmethod</code>","text":"<p>Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>PrefectClient</code> <p>Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.</p> <code>None</code> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\n@sync_compatible\n@inject_client\nasync def register_type_and_schema(cls, client: \"PrefectClient\" = None):\n    \"\"\"\n    Makes block available for configuration with current Prefect API.\n    Recursively registers all nested blocks. Registration is idempotent.\n\n    Args:\n        client: Optional client to use for registering type and schema with the\n            Prefect API. A new client will be created and used if one is not\n            provided.\n    \"\"\"\n    if cls.__name__ == \"Block\":\n        raise InvalidBlockRegistration(\n            \"`register_type_and_schema` should be called on a Block \"\n            \"subclass and not on the Block class directly.\"\n        )\n    if ABC in getattr(cls, \"__bases__\", []):\n        raise InvalidBlockRegistration(\n            \"`register_type_and_schema` should be called on a Block \"\n            \"subclass and not on a Block interface class directly.\"\n        )\n\n    async def register_blocks_in_annotation(annotation: type) -&gt; None:\n        \"\"\"Walk through the annotation and register any nested blocks.\"\"\"\n        if Block.is_block_class(annotation):\n            await annotation.register_type_and_schema(client=client)\n        elif get_origin(annotation) in (Union, tuple, list, dict):\n            for inner_annotation in get_args(annotation):\n                await register_blocks_in_annotation(inner_annotation)\n\n    for field in cls.__fields__.values():\n        await register_blocks_in_annotation(field.annotation)\n\n    try:\n        block_type = await client.read_block_type_by_slug(\n            slug=cls.get_block_type_slug()\n        )\n        cls._block_type_id = block_type.id\n        local_block_type = cls._to_block_type()\n        if _should_update_block_type(\n            local_block_type=local_block_type, server_block_type=block_type\n        ):\n            await client.update_block_type(\n                block_type_id=block_type.id, block_type=local_block_type\n            )\n    except prefect.exceptions.ObjectNotFound:\n        block_type = await client.create_block_type(block_type=cls._to_block_type())\n        cls._block_type_id = block_type.id\n\n    try:\n        block_schema = await client.read_block_schema_by_checksum(\n            checksum=cls._calculate_schema_checksum(),\n            version=cls.get_block_schema_version(),\n        )\n    except prefect.exceptions.ObjectNotFound:\n        block_schema = await client.create_block_schema(\n            block_schema=cls._to_block_schema(block_type_id=block_type.id)\n        )\n\n    cls._block_schema_id = block_schema.id\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.save","title":"<code>save</code>  <code>async</code>","text":"<p>Saves the values of a block as a block document.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>User specified name to give saved block document which can later be used to load the block document.</p> <code>None</code> <code>overwrite</code> <code>bool</code> <p>Boolean value specifying if values should be overwritten if a block document with the specified name already exists.</p> <code>False</code> Source code in <code>prefect/blocks/core.py</code> <pre><code>@sync_compatible\n@instrument_instance_method_call\nasync def save(\n    self,\n    name: Optional[str] = None,\n    overwrite: bool = False,\n    client: \"PrefectClient\" = None,\n):\n    \"\"\"\n    Saves the values of a block as a block document.\n\n    Args:\n        name: User specified name to give saved block document which can later be used to load the\n            block document.\n        overwrite: Boolean value specifying if values should be overwritten if a block document with\n            the specified name already exists.\n\n    \"\"\"\n    document_id = await self._save(name=name, overwrite=overwrite, client=client)\n\n    return document_id\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.BlockNotSavedError","title":"<code>BlockNotSavedError</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Raised when a given block is not saved and an operation that requires the block to be saved is attempted.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>class BlockNotSavedError(RuntimeError):\n    \"\"\"\n    Raised when a given block is not saved and an operation that requires\n    the block to be saved is attempted.\n    \"\"\"\n\n    pass\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.InvalidBlockRegistration","title":"<code>InvalidBlockRegistration</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised on attempted registration of the base Block class or a Block interface class</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>class InvalidBlockRegistration(Exception):\n    \"\"\"\n    Raised on attempted registration of the base Block\n    class or a Block interface class\n    \"\"\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.block_schema_to_key","title":"<code>block_schema_to_key</code>","text":"<p>Defines the unique key used to lookup the Block class for a given schema.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>def block_schema_to_key(schema: BlockSchema) -&gt; str:\n    \"\"\"\n    Defines the unique key used to lookup the Block class for a given schema.\n    \"\"\"\n    return f\"{schema.block_type.slug}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/fields/","title":"fields","text":"","tags":["Python API","fields"]},{"location":"api-ref/prefect/blocks/fields/#prefect.blocks.fields","title":"<code>prefect.blocks.fields</code>","text":"","tags":["Python API","fields"]},{"location":"api-ref/prefect/blocks/kubernetes/","title":"kubernetes","text":"","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes","title":"<code>prefect.blocks.kubernetes</code>","text":"","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect.blocks.kubernetes import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the KubernetesClusterConfig block from prefect-kubernetes instead.\",\n)\nclass KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect.blocks.kubernetes import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig\"\n\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    def parse_yaml_config(cls, value):\n        return validate_yaml(value)\n\n    @classmethod\n    def from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n        kube_config = kubernetes.config.kube_config\n\n        path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        existing_contexts, current_context = kube_config.list_kube_config_contexts(\n            config_file=str(path)\n        )\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n\n        return cls(config=config_dict, context_name=context_name)\n\n    def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return kubernetes.config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        kubernetes.config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    kubernetes.config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@classmethod\ndef from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n    kube_config = kubernetes.config.kube_config\n\n    path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    existing_contexts, current_context = kube_config.list_kube_config_contexts(\n        config_file=str(path)\n    )\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return kubernetes.config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/notifications/","title":"notifications","text":"","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications","title":"<code>prefect.blocks.notifications</code>","text":"","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.AbstractAppriseNotificationBlock","title":"<code>AbstractAppriseNotificationBlock</code>","text":"<p>               Bases: <code>NotificationBlock</code>, <code>ABC</code></p> <p>An abstract class for sending notifications using Apprise.</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class AbstractAppriseNotificationBlock(NotificationBlock, ABC):\n    \"\"\"\n    An abstract class for sending notifications using Apprise.\n    \"\"\"\n\n    notify_type: Literal[\n        \"prefect_default\", \"info\", \"success\", \"warning\", \"failure\"\n    ] = Field(\n        default=PREFECT_NOTIFY_TYPE_DEFAULT,\n        description=(\n            \"The type of notification being performed; the prefect_default \"\n            \"is a plain notification that does not attach an image.\"\n        ),\n    )\n\n    def __init__(self, *args, **kwargs):\n        import apprise\n\n        if PREFECT_NOTIFY_TYPE_DEFAULT not in apprise.NOTIFY_TYPES:\n            apprise.NOTIFY_TYPES += (PREFECT_NOTIFY_TYPE_DEFAULT,)\n\n        super().__init__(*args, **kwargs)\n\n    def _start_apprise_client(self, url: SecretStr):\n        from apprise import Apprise, AppriseAsset\n\n        # A custom `AppriseAsset` that ensures Prefect Notifications\n        # appear correctly across multiple messaging platforms\n        prefect_app_data = AppriseAsset(\n            app_id=\"Prefect Notifications\",\n            app_desc=\"Prefect Notifications\",\n            app_url=\"https://prefect.io\",\n        )\n\n        self._apprise_client = Apprise(asset=prefect_app_data)\n        self._apprise_client.add(url.get_secret_value())\n\n    def block_initialization(self) -&gt; None:\n        self._start_apprise_client(self.url)\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def notify(\n        self,\n        body: str,\n        subject: Optional[str] = None,\n    ):\n        with LogEavesdropper(\"apprise\", level=logging.DEBUG) as eavesdropper:\n            result = await self._apprise_client.async_notify(\n                body=body, title=subject, notify_type=self.notify_type\n            )\n        if not result and self._raise_on_failure:\n            raise NotificationError(log=eavesdropper.text())\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.AppriseNotificationBlock","title":"<code>AppriseNotificationBlock</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code>, <code>ABC</code></p> <p>A base class for sending notifications using Apprise, through webhook URLs.</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class AppriseNotificationBlock(AbstractAppriseNotificationBlock, ABC):\n    \"\"\"\n    A base class for sending notifications using Apprise, through webhook URLs.\n    \"\"\"\n\n    _documentation_url = \"https://docs.prefect.io/ui/notifications/\"\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Incoming webhook URL used to send notifications.\",\n        examples=[\"https://hooks.example.com/XXX\"],\n    )\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.CustomWebhookNotificationBlock","title":"<code>CustomWebhookNotificationBlock</code>","text":"<p>               Bases: <code>NotificationBlock</code></p> <p>Enables sending notifications via any custom webhook.</p> <p>All nested string param contains <code>{{key}}</code> will be substituted with value from context/secrets.</p> <p>Context values include: <code>subject</code>, <code>body</code> and <code>name</code>.</p> <p>Examples:</p> <p>Load a saved custom webhook and send a message: <pre><code>from prefect.blocks.notifications import CustomWebhookNotificationBlock\n\ncustom_webhook_block = CustomWebhookNotificationBlock.load(\"BLOCK_NAME\")\n\ncustom_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class CustomWebhookNotificationBlock(NotificationBlock):\n    \"\"\"\n    Enables sending notifications via any custom webhook.\n\n    All nested string param contains `{{key}}` will be substituted with value from context/secrets.\n\n    Context values include: `subject`, `body` and `name`.\n\n    Examples:\n        Load a saved custom webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import CustomWebhookNotificationBlock\n\n        custom_webhook_block = CustomWebhookNotificationBlock.load(\"BLOCK_NAME\")\n\n        custom_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Custom Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c7247cb359eb6cf276734d4b1fbf00fb8930e89e-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.CustomWebhookNotificationBlock\"\n\n    name: str = Field(title=\"Name\", description=\"Name of the webhook.\")\n\n    url: str = Field(\n        title=\"Webhook URL\",\n        description=\"The webhook URL.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n\n    method: Literal[\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"] = Field(\n        default=\"POST\", description=\"The webhook request method. Defaults to `POST`.\"\n    )\n\n    params: Optional[Dict[str, str]] = Field(\n        default=None, title=\"Query Params\", description=\"Custom query params.\"\n    )\n    json_data: Optional[dict] = Field(\n        default=None,\n        title=\"JSON Data\",\n        description=\"Send json data as payload.\",\n        examples=[\n            '{\"text\": \"{{subject}}\\\\n{{body}}\", \"title\": \"{{name}}\", \"token\":'\n            ' \"{{tokenFromSecrets}}\"}'\n        ],\n    )\n    form_data: Optional[Dict[str, str]] = Field(\n        default=None,\n        title=\"Form Data\",\n        description=(\n            \"Send form data as payload. Should not be used together with _JSON Data_.\"\n        ),\n        examples=[\n            '{\"text\": \"{{subject}}\\\\n{{body}}\", \"title\": \"{{name}}\", \"token\":'\n            ' \"{{tokenFromSecrets}}\"}'\n        ],\n    )\n\n    headers: Optional[Dict[str, str]] = Field(None, description=\"Custom headers.\")\n    cookies: Optional[Dict[str, str]] = Field(None, description=\"Custom cookies.\")\n\n    timeout: float = Field(\n        default=10, description=\"Request timeout in seconds. Defaults to 10.\"\n    )\n\n    secrets: SecretDict = Field(\n        default_factory=lambda: SecretDict(dict()),\n        title=\"Custom Secret Values\",\n        description=\"A dictionary of secret values to be substituted in other configs.\",\n        examples=['{\"tokenFromSecrets\":\"SomeSecretToken\"}'],\n    )\n\n    def _build_request_args(self, body: str, subject: Optional[str]):\n        \"\"\"Build kwargs for httpx.AsyncClient.request\"\"\"\n        # prepare values\n        values = self.secrets.get_secret_value()\n        # use 'null' when subject is None\n        values.update(\n            {\n                \"subject\": \"null\" if subject is None else subject,\n                \"body\": body,\n                \"name\": self.name,\n            }\n        )\n        # do substution\n        return apply_values(\n            {\n                \"method\": self.method,\n                \"url\": self.url,\n                \"params\": self.params,\n                \"data\": self.form_data,\n                \"json\": self.json_data,\n                \"headers\": self.headers,\n                \"cookies\": self.cookies,\n                \"timeout\": self.timeout,\n            },\n            values,\n        )\n\n    def block_initialization(self) -&gt; None:\n        # check form_data and json_data\n        if self.form_data is not None and self.json_data is not None:\n            raise ValueError(\"both `Form Data` and `JSON Data` provided\")\n        allowed_keys = {\"subject\", \"body\", \"name\"}.union(\n            self.secrets.get_secret_value().keys()\n        )\n        # test template to raise a error early\n        for name in [\"url\", \"params\", \"form_data\", \"json_data\", \"headers\", \"cookies\"]:\n            template = getattr(self, name)\n            if template is None:\n                continue\n            # check for placeholders not in predefined keys and secrets\n            placeholders = find_placeholders(template)\n            for placeholder in placeholders:\n                if placeholder.name not in allowed_keys:\n                    raise KeyError(f\"{name}/{placeholder}\")\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def notify(self, body: str, subject: Optional[str] = None):\n        import httpx\n\n        request_args = self._build_request_args(body, subject)\n        cookies = request_args.pop(\"cookies\", None)\n        # make request with httpx\n        client = httpx.AsyncClient(\n            headers={\"user-agent\": \"Prefect Notifications\"}, cookies=cookies\n        )\n        async with client:\n            resp = await client.request(**request_args)\n        resp.raise_for_status()\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.DiscordWebhook","title":"<code>DiscordWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Discord webhook. See Apprise notify_Discord docs # noqa</p> <p>Examples:</p> <p>Load a saved Discord webhook and send a message: <pre><code>from prefect.blocks.notifications import DiscordWebhook\n\ndiscord_webhook_block = DiscordWebhook.load(\"BLOCK_NAME\")\n\ndiscord_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class DiscordWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Discord webhook.\n    See [Apprise notify_Discord docs](https://github.com/caronc/apprise/wiki/Notify_Discord) # noqa\n\n    Examples:\n        Load a saved Discord webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import DiscordWebhook\n\n        discord_webhook_block = DiscordWebhook.load(\"BLOCK_NAME\")\n\n        discord_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Discord webhook.\"\n    _block_type_name = \"Discord Webhook\"\n    _block_type_slug = \"discord-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/9e94976c80ef925b66d24e5d14f0d47baa6b8f88-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.DiscordWebhook\"\n\n    webhook_id: SecretStr = Field(\n        default=...,\n        description=(\n            \"The first part of 2 tokens provided to you after creating a\"\n            \" incoming-webhook.\"\n        ),\n    )\n\n    webhook_token: SecretStr = Field(\n        default=...,\n        description=(\n            \"The second part of 2 tokens provided to you after creating a\"\n            \" incoming-webhook.\"\n        ),\n    )\n\n    botname: Optional[str] = Field(\n        title=\"Bot name\",\n        default=None,\n        description=(\n            \"Identify the name of the bot that should issue the message. If one isn't\"\n            \" specified then the default is to just use your account (associated with\"\n            \" the incoming-webhook).\"\n        ),\n    )\n\n    tts: bool = Field(\n        default=False,\n        description=\"Whether to enable Text-To-Speech.\",\n    )\n\n    include_image: bool = Field(\n        default=False,\n        description=(\n            \"Whether to include an image in-line with the message describing the\"\n            \" notification type.\"\n        ),\n    )\n\n    avatar: bool = Field(\n        default=False,\n        description=\"Whether to override the default discord avatar icon.\",\n    )\n\n    avatar_url: Optional[str] = Field(\n        title=\"Avatar URL\",\n        default=False,\n        description=(\n            \"Over-ride the default discord avatar icon URL. By default this is not set\"\n            \" and Apprise chooses the URL dynamically based on the type of message\"\n            \" (info, success, warning, or error).\"\n        ),\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.discord import NotifyDiscord\n\n        url = SecretStr(\n            NotifyDiscord(\n                webhook_id=self.webhook_id.get_secret_value(),\n                webhook_token=self.webhook_token.get_secret_value(),\n                botname=self.botname,\n                tts=self.tts,\n                include_image=self.include_image,\n                avatar=self.avatar,\n                avatar_url=self.avatar_url,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MattermostWebhook","title":"<code>MattermostWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Mattermost webhook. See Apprise notify_Mattermost docs # noqa</p> <p>Examples:</p> <p>Load a saved Mattermost webhook and send a message: <pre><code>from prefect.blocks.notifications import MattermostWebhook\n\nmattermost_webhook_block = MattermostWebhook.load(\"BLOCK_NAME\")\n\nmattermost_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class MattermostWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Mattermost webhook.\n    See [Apprise notify_Mattermost docs](https://github.com/caronc/apprise/wiki/Notify_Mattermost) # noqa\n\n\n    Examples:\n        Load a saved Mattermost webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import MattermostWebhook\n\n        mattermost_webhook_block = MattermostWebhook.load(\"BLOCK_NAME\")\n\n        mattermost_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Mattermost webhook.\"\n    _block_type_name = \"Mattermost Webhook\"\n    _block_type_slug = \"mattermost-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/1350a147130bf82cbc799a5f868d2c0116207736-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MattermostWebhook\"\n\n    hostname: str = Field(\n        default=...,\n        description=\"The hostname of your Mattermost server.\",\n        examples=[\"Mattermost.example.com\"],\n    )\n\n    token: SecretStr = Field(\n        default=...,\n        description=\"The token associated with your Mattermost webhook.\",\n    )\n\n    botname: Optional[str] = Field(\n        title=\"Bot name\",\n        default=None,\n        description=\"The name of the bot that will send the message.\",\n    )\n\n    channels: Optional[List[str]] = Field(\n        default=None,\n        description=\"The channel(s) you wish to notify.\",\n    )\n\n    include_image: bool = Field(\n        default=False,\n        description=\"Whether to include the Apprise status image in the message.\",\n    )\n\n    path: Optional[str] = Field(\n        default=None,\n        description=\"An optional sub-path specification to append to the hostname.\",\n    )\n\n    port: int = Field(\n        default=8065,\n        description=\"The port of your Mattermost server.\",\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.mattermost import NotifyMattermost\n\n        url = SecretStr(\n            NotifyMattermost(\n                token=self.token.get_secret_value(),\n                fullpath=self.path,\n                host=self.hostname,\n                botname=self.botname,\n                channels=self.channels,\n                include_image=self.include_image,\n                port=self.port,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook","title":"<code>MicrosoftTeamsWebhook</code>","text":"<p>               Bases: <code>AppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Microsoft Teams webhook.</p> <p>Examples:</p> <p>Load a saved Teams webhook and send a message: <pre><code>from prefect.blocks.notifications import MicrosoftTeamsWebhook\nteams_webhook_block = MicrosoftTeamsWebhook.load(\"BLOCK_NAME\")\nteams_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class MicrosoftTeamsWebhook(AppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Microsoft Teams webhook.\n\n    Examples:\n        Load a saved Teams webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import MicrosoftTeamsWebhook\n        teams_webhook_block = MicrosoftTeamsWebhook.load(\"BLOCK_NAME\")\n        teams_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Microsoft Teams Webhook\"\n    _block_type_slug = \"ms-teams-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/817efe008a57f0a24f3587414714b563e5e23658-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook\"\n\n    url: SecretStr = Field(\n        ...,\n        title=\"Webhook URL\",\n        description=\"The Microsoft Power Automate (Workflows) URL used to send notifications to Teams.\",\n        examples=[\n            \"https://prod-NO.LOCATION.logic.azure.com:443/workflows/WFID/triggers/manual/paths/invoke?sp=%2Ftriggers%2Fmanual%2Frun&amp;sv=1.0&amp;sig=SIGNATURE\"\n        ],\n    )\n\n    include_image: bool = Field(\n        default=True,\n        description=\"Include an image with the notification.\",\n    )\n\n    wrap: bool = Field(\n        default=True,\n        description=\"Wrap the notification text.\",\n    )\n\n    def block_initialization(self) -&gt; None:\n        \"\"\"see https://github.com/caronc/apprise/pull/1172\"\"\"\n        from apprise.plugins.workflows import NotifyWorkflows\n\n        if not (\n            parsed_url := NotifyWorkflows.parse_native_url(self.url.get_secret_value())\n        ):\n            raise ValueError(\"Invalid Microsoft Teams Workflow URL provided.\")\n\n        parsed_url.update(\n            {\n                \"include_image\": self.include_image,\n                \"wrap\": self.wrap,\n            }\n        )\n\n        self._start_apprise_client(SecretStr(NotifyWorkflows(**parsed_url).url()))\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook.block_initialization","title":"<code>block_initialization</code>","text":"<p>see https://github.com/caronc/apprise/pull/1172</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>def block_initialization(self) -&gt; None:\n    \"\"\"see https://github.com/caronc/apprise/pull/1172\"\"\"\n    from apprise.plugins.workflows import NotifyWorkflows\n\n    if not (\n        parsed_url := NotifyWorkflows.parse_native_url(self.url.get_secret_value())\n    ):\n        raise ValueError(\"Invalid Microsoft Teams Workflow URL provided.\")\n\n    parsed_url.update(\n        {\n            \"include_image\": self.include_image,\n            \"wrap\": self.wrap,\n        }\n    )\n\n    self._start_apprise_client(SecretStr(NotifyWorkflows(**parsed_url).url()))\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.OpsgenieWebhook","title":"<code>OpsgenieWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Opsgenie webhook. See Apprise notify_opsgenie docs for more info on formatting the URL.</p> <p>Examples:</p> <p>Load a saved Opsgenie webhook and send a message: <pre><code>from prefect.blocks.notifications import OpsgenieWebhook\nopsgenie_webhook_block = OpsgenieWebhook.load(\"BLOCK_NAME\")\nopsgenie_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class OpsgenieWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Opsgenie webhook.\n    See [Apprise notify_opsgenie docs](https://github.com/caronc/apprise/wiki/Notify_opsgenie)\n    for more info on formatting the URL.\n\n    Examples:\n        Load a saved Opsgenie webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import OpsgenieWebhook\n        opsgenie_webhook_block = OpsgenieWebhook.load(\"BLOCK_NAME\")\n        opsgenie_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Opsgenie webhook.\"\n\n    _block_type_name = \"Opsgenie Webhook\"\n    _block_type_slug = \"opsgenie-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d8b5bc6244ae6cd83b62ec42f10d96e14d6e9113-280x280.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.OpsgenieWebhook\"\n\n    apikey: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"The API Key associated with your Opsgenie account.\",\n    )\n\n    target_user: Optional[List] = Field(\n        default=None, description=\"The user(s) you wish to notify.\"\n    )\n\n    target_team: Optional[List] = Field(\n        default=None, description=\"The team(s) you wish to notify.\"\n    )\n\n    target_schedule: Optional[List] = Field(\n        default=None, description=\"The schedule(s) you wish to notify.\"\n    )\n\n    target_escalation: Optional[List] = Field(\n        default=None, description=\"The escalation(s) you wish to notify.\"\n    )\n\n    region_name: Literal[\"us\", \"eu\"] = Field(\n        default=\"us\", description=\"The 2-character region code.\"\n    )\n\n    batch: bool = Field(\n        default=False,\n        description=\"Notify all targets in batches (instead of individually).\",\n    )\n\n    tags: Optional[List] = Field(\n        default=None,\n        description=(\n            \"A comma-separated list of tags you can associate with your Opsgenie\"\n            \" message.\"\n        ),\n        examples=['[\"tag1\", \"tag2\"]'],\n    )\n\n    priority: Optional[str] = Field(\n        default=3,\n        description=(\n            \"The priority to associate with the message. It is on a scale between 1\"\n            \" (LOW) and 5 (EMERGENCY).\"\n        ),\n    )\n\n    alias: Optional[str] = Field(\n        default=None, description=\"The alias to associate with the message.\"\n    )\n\n    entity: Optional[str] = Field(\n        default=None, description=\"The entity to associate with the message.\"\n    )\n\n    details: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=\"Additional details composed of key/values pairs.\",\n        examples=['{\"key1\": \"value1\", \"key2\": \"value2\"}'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.opsgenie import NotifyOpsgenie\n\n        targets = []\n        if self.target_user:\n            [targets.append(f\"@{x}\") for x in self.target_user]\n        if self.target_team:\n            [targets.append(f\"#{x}\") for x in self.target_team]\n        if self.target_schedule:\n            [targets.append(f\"*{x}\") for x in self.target_schedule]\n        if self.target_escalation:\n            [targets.append(f\"^{x}\") for x in self.target_escalation]\n        url = SecretStr(\n            NotifyOpsgenie(\n                apikey=self.apikey.get_secret_value(),\n                targets=targets,\n                region_name=self.region_name,\n                details=self.details,\n                priority=self.priority,\n                alias=self.alias,\n                entity=self.entity,\n                batch=self.batch,\n                tags=self.tags,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.PagerDutyWebHook","title":"<code>PagerDutyWebHook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided PagerDuty webhook. See Apprise notify_pagerduty docs for more info on formatting the URL.</p> <p>Examples:</p> <p>Load a saved PagerDuty webhook and send a message: <pre><code>from prefect.blocks.notifications import PagerDutyWebHook\npagerduty_webhook_block = PagerDutyWebHook.load(\"BLOCK_NAME\")\npagerduty_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class PagerDutyWebHook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided PagerDuty webhook.\n    See [Apprise notify_pagerduty docs](https://github.com/caronc/apprise/wiki/Notify_pagerduty)\n    for more info on formatting the URL.\n\n    Examples:\n        Load a saved PagerDuty webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import PagerDutyWebHook\n        pagerduty_webhook_block = PagerDutyWebHook.load(\"BLOCK_NAME\")\n        pagerduty_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided PagerDuty webhook.\"\n\n    _block_type_name = \"Pager Duty Webhook\"\n    _block_type_slug = \"pager-duty-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8dbf37d17089c1ce531708eac2e510801f7b3aee-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.PagerDutyWebHook\"\n\n    # The default cannot be prefect_default because NotifyPagerDuty's\n    # PAGERDUTY_SEVERITY_MAP only has these notify types defined as keys\n    notify_type: Literal[\"info\", \"success\", \"warning\", \"failure\"] = Field(\n        default=\"info\", description=\"The severity of the notification.\"\n    )\n\n    integration_key: SecretStr = Field(\n        default=...,\n        description=(\n            \"This can be found on the Events API V2 \"\n            \"integration's detail page, and is also referred to as a Routing Key. \"\n            \"This must be provided alongside `api_key`, but will error if provided \"\n            \"alongside `url`.\"\n        ),\n    )\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=(\n            \"This can be found under Integrations. \"\n            \"This must be provided alongside `integration_key`, but will error if \"\n            \"provided alongside `url`.\"\n        ),\n    )\n\n    source: Optional[str] = Field(\n        default=\"Prefect\", description=\"The source string as part of the payload.\"\n    )\n\n    component: str = Field(\n        default=\"Notification\",\n        description=\"The component string as part of the payload.\",\n    )\n\n    group: Optional[str] = Field(\n        default=None, description=\"The group string as part of the payload.\"\n    )\n\n    class_id: Optional[str] = Field(\n        default=None,\n        title=\"Class ID\",\n        description=\"The class string as part of the payload.\",\n    )\n\n    region_name: Literal[\"us\", \"eu\"] = Field(\n        default=\"us\", description=\"The region name.\"\n    )\n\n    clickable_url: Optional[AnyHttpUrl] = Field(\n        default=None,\n        title=\"Clickable URL\",\n        description=\"A clickable URL to associate with the notice.\",\n    )\n\n    include_image: bool = Field(\n        default=True,\n        description=\"Associate the notification status via a represented icon.\",\n    )\n\n    custom_details: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=\"Additional details to include as part of the payload.\",\n        examples=['{\"disk_space_left\": \"145GB\"}'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.pagerduty import NotifyPagerDuty\n\n        url = SecretStr(\n            NotifyPagerDuty(\n                apikey=self.api_key.get_secret_value(),\n                integrationkey=self.integration_key.get_secret_value(),\n                source=self.source,\n                component=self.component,\n                group=self.group,\n                class_id=self.class_id,\n                region_name=self.region_name,\n                click=self.clickable_url,\n                include_image=self.include_image,\n                details=self.custom_details,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SendgridEmail","title":"<code>SendgridEmail</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via any sendgrid account. See Apprise Notify_sendgrid docs</p> <p>Examples:</p> <p>Load a saved Sendgrid and send a email message: ```python from prefect.blocks.notifications import SendgridEmail</p> <p>sendgrid_block = SendgridEmail.load(\"BLOCK_NAME\")</p> <p>sendgrid_block.notify(\"Hello from Prefect!\")</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class SendgridEmail(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via any sendgrid account.\n    See [Apprise Notify_sendgrid docs](https://github.com/caronc/apprise/wiki/Notify_Sendgrid)\n\n    Examples:\n        Load a saved Sendgrid and send a email message:\n        ```python\n        from prefect.blocks.notifications import SendgridEmail\n\n        sendgrid_block = SendgridEmail.load(\"BLOCK_NAME\")\n\n        sendgrid_block.notify(\"Hello from Prefect!\")\n    \"\"\"\n\n    _description = \"Enables sending notifications via Sendgrid email service.\"\n    _block_type_name = \"Sendgrid Email\"\n    _block_type_slug = \"sendgrid-email\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/82bc6ed16ca42a2252a5512c72233a253b8a58eb-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SendgridEmail\"\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"The API Key associated with your sendgrid account.\",\n    )\n\n    sender_email: str = Field(\n        title=\"Sender email id\",\n        description=\"The sender email id.\",\n        examples=[\"test-support@gmail.com\"],\n    )\n\n    to_emails: List[str] = Field(\n        default=...,\n        title=\"Recipient emails\",\n        description=\"Email ids of all recipients.\",\n        examples=['\"recipient1@gmail.com\"'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.sendgrid import NotifySendGrid\n\n        url = SecretStr(\n            NotifySendGrid(\n                apikey=self.api_key.get_secret_value(),\n                from_email=self.sender_email,\n                targets=self.to_emails,\n            ).url()\n        )\n\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SlackWebhook","title":"<code>SlackWebhook</code>","text":"<p>               Bases: <code>AppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Slack webhook.</p> <p>Examples:</p> <p>Load a saved Slack webhook and send a message: <pre><code>from prefect.blocks.notifications import SlackWebhook\n\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nslack_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class SlackWebhook(AppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Slack webhook.\n\n    Examples:\n        Load a saved Slack webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import SlackWebhook\n\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        slack_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Slack Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c1965ecbf8704ee1ea20d77786de9a41ce1087d1-500x500.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SlackWebhook\"\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Slack incoming webhook URL used to send notifications.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.TwilioSMS","title":"<code>TwilioSMS</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via Twilio SMS. Find more on sending Twilio SMS messages in the docs.</p> <p>Examples:</p> <p>Load a saved <code>TwilioSMS</code> block and send a message: <pre><code>from prefect.blocks.notifications import TwilioSMS\ntwilio_webhook_block = TwilioSMS.load(\"BLOCK_NAME\")\ntwilio_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class TwilioSMS(AbstractAppriseNotificationBlock):\n    \"\"\"Enables sending notifications via Twilio SMS.\n    Find more on sending Twilio SMS messages in the [docs](https://www.twilio.com/docs/sms).\n\n    Examples:\n        Load a saved `TwilioSMS` block and send a message:\n        ```python\n        from prefect.blocks.notifications import TwilioSMS\n        twilio_webhook_block = TwilioSMS.load(\"BLOCK_NAME\")\n        twilio_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via Twilio SMS.\"\n    _block_type_name = \"Twilio SMS\"\n    _block_type_slug = \"twilio-sms\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8bd8777999f82112c09b9c8d57083ac75a4a0d65-250x250.png\"  # noqa\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.TwilioSMS\"\n\n    account_sid: str = Field(\n        default=...,\n        description=(\n            \"The Twilio Account SID - it can be found on the homepage \"\n            \"of the Twilio console.\"\n        ),\n    )\n\n    auth_token: SecretStr = Field(\n        default=...,\n        description=(\n            \"The Twilio Authentication Token - \"\n            \"it can be found on the homepage of the Twilio console.\"\n        ),\n    )\n\n    from_phone_number: str = Field(\n        default=...,\n        description=\"The valid Twilio phone number to send the message from.\",\n        examples=[\"18001234567\"],\n    )\n\n    to_phone_numbers: List[str] = Field(\n        default=...,\n        description=\"A list of valid Twilio phone number(s) to send the message to.\",\n        # not wrapped in brackets because of the way UI displays examples; in code should be [\"18004242424\"]\n        examples=[\"18004242424\"],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.twilio import NotifyTwilio\n\n        url = SecretStr(\n            NotifyTwilio(\n                account_sid=self.account_sid,\n                auth_token=self.auth_token.get_secret_value(),\n                source=self.from_phone_number,\n                targets=self.to_phone_numbers,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/system/","title":"system","text":"","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system","title":"<code>prefect.blocks.system</code>","text":"","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.DateTime","title":"<code>DateTime</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a datetime</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>DateTimeTZ</code> <p>An ISO 8601-compatible datetime value.</p> Example <p>Load a stored JSON value: <pre><code>from prefect.blocks.system import DateTime\n\ndata_time_block = DateTime.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class DateTime(Block):\n    \"\"\"\n    A block that represents a datetime\n\n    Attributes:\n        value: An ISO 8601-compatible datetime value.\n\n    Example:\n        Load a stored JSON value:\n        ```python\n        from prefect.blocks.system import DateTime\n\n        data_time_block = DateTime.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Date Time\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8b3da9a6621e92108b8e6a75b82e15374e170ff7-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.DateTime\"\n\n    value: DateTimeTZ = Field(\n        default=...,\n        description=\"An ISO 8601-compatible datetime value.\",\n    )\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.JSON","title":"<code>JSON</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents JSON</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>Any</code> <p>A JSON-compatible value.</p> Example <p>Load a stored JSON value: <pre><code>from prefect.blocks.system import JSON\n\njson_block = JSON.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class JSON(Block):\n    \"\"\"\n    A block that represents JSON\n\n    Attributes:\n        value: A JSON-compatible value.\n\n    Example:\n        Load a stored JSON value:\n        ```python\n        from prefect.blocks.system import JSON\n\n        json_block = JSON.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/4fcef2294b6eeb423b1332d1ece5156bf296ff96-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.JSON\"\n\n    value: Any = Field(default=..., description=\"A JSON-compatible value.\")\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.Secret","title":"<code>Secret</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a secret value. The value stored in this block will be obfuscated when this block is logged or shown in the UI.</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>SecretStr</code> <p>A string value that should be kept secret.</p> Example <pre><code>from prefect.blocks.system import Secret\n\nsecret_block = Secret.load(\"BLOCK_NAME\")\n\n# Access the stored secret\nsecret_block.get()\n</code></pre> Source code in <code>prefect/blocks/system.py</code> <pre><code>class Secret(Block):\n    \"\"\"\n    A block that represents a secret value. The value stored in this block will be obfuscated when\n    this block is logged or shown in the UI.\n\n    Attributes:\n        value: A string value that should be kept secret.\n\n    Example:\n        ```python\n        from prefect.blocks.system import Secret\n\n        secret_block = Secret.load(\"BLOCK_NAME\")\n\n        # Access the stored secret\n        secret_block.get()\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c6f20e556dd16effda9df16551feecfb5822092b-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.Secret\"\n\n    value: SecretStr = Field(\n        default=..., description=\"A string value that should be kept secret.\"\n    )\n\n    def get(self):\n        return self.value.get_secret_value()\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.String","title":"<code>String</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a string</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>str</code> <p>A string value.</p> Example <p>Load a stored string value: <pre><code>from prefect.blocks.system import String\n\nstring_block = String.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class String(Block):\n    \"\"\"\n    A block that represents a string\n\n    Attributes:\n        value: A string value.\n\n    Example:\n        Load a stored string value:\n        ```python\n        from prefect.blocks.system import String\n\n        string_block = String.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c262ea2c80a2c043564e8763f3370c3db5a6b3e6-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.String\"\n\n    value: str = Field(default=..., description=\"A string value.\")\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/webhook/","title":"webhook","text":"","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook","title":"<code>prefect.blocks.webhook</code>","text":"","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook","title":"<code>Webhook</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block that enables calling webhooks.</p> Source code in <code>prefect/blocks/webhook.py</code> <pre><code>class Webhook(Block):\n    \"\"\"\n    Block that enables calling webhooks.\n    \"\"\"\n\n    _block_type_name = \"Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c7247cb359eb6cf276734d4b1fbf00fb8930e89e-250x250.png\"  # type: ignore\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook\"\n\n    method: Literal[\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"] = Field(\n        default=\"POST\", description=\"The webhook request method. Defaults to `POST`.\"\n    )\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"The webhook URL.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n\n    headers: SecretDict = Field(\n        default_factory=lambda: SecretDict(dict()),\n        title=\"Webhook Headers\",\n        description=\"A dictionary of headers to send with the webhook request.\",\n    )\n\n    def block_initialization(self):\n        self._client = AsyncClient(transport=_http_transport)\n\n    async def call(self, payload: Optional[dict] = None) -&gt; Response:\n        \"\"\"\n        Call the webhook.\n\n        Args:\n            payload: an optional payload to send when calling the webhook.\n        \"\"\"\n        async with self._client:\n            return await self._client.request(\n                method=self.method,\n                url=self.url.get_secret_value(),\n                headers=self.headers.get_secret_value(),\n                json=payload,\n            )\n</code></pre>","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook.call","title":"<code>call</code>  <code>async</code>","text":"<p>Call the webhook.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Optional[dict]</code> <p>an optional payload to send when calling the webhook.</p> <code>None</code> Source code in <code>prefect/blocks/webhook.py</code> <pre><code>async def call(self, payload: Optional[dict] = None) -&gt; Response:\n    \"\"\"\n    Call the webhook.\n\n    Args:\n        payload: an optional payload to send when calling the webhook.\n    \"\"\"\n    async with self._client:\n        return await self._client.request(\n            method=self.method,\n            url=self.url.get_secret_value(),\n            headers=self.headers.get_secret_value(),\n            json=payload,\n        )\n</code></pre>","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/cli/agent/","title":"agent","text":"","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/agent/#prefect.cli.agent","title":"<code>prefect.cli.agent</code>","text":"<p>Command line interface for working with agent services</p>","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/agent/#prefect.cli.agent.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start an agent process to poll one or more work queues for flow runs.</p> Source code in <code>prefect/cli/agent.py</code> <pre><code>@agent_app.command()\nasync def start(\n    # deprecated main argument\n    work_queue: str = typer.Argument(\n        None,\n        show_default=False,\n        help=\"DEPRECATED: A work queue name or ID\",\n    ),\n    work_queues: List[str] = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the agent to pull from.\",\n    ),\n    work_queue_prefix: List[str] = typer.Option(\n        None,\n        \"-m\",\n        \"--match\",\n        help=(\n            \"Dynamically matches work queue names with the specified prefix for the\"\n            \" agent to pull from,for example `dev-` will match all work queues with a\"\n            \" name that starts with `dev-`\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"A work pool name for the agent to pull from.\",\n    ),\n    hide_welcome: bool = typer.Option(False, \"--hide-welcome\"),\n    api: str = SettingsOption(PREFECT_API_URL),\n    run_once: bool = typer.Option(\n        False, help=\"Run the agent loop once, instead of forever.\"\n    ),\n    prefetch_seconds: int = SettingsOption(PREFECT_AGENT_PREFETCH_SECONDS),\n    # deprecated tags\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"DEPRECATED: One or more optional tags that will be used to create a work\"\n            \" queue. This option will be removed on 2023-02-23.\"\n        ),\n    ),\n    limit: int = typer.Option(\n        None,\n        \"-l\",\n        \"--limit\",\n        help=\"Maximum number of flow runs to start simultaneously.\",\n    ),\n):\n    \"\"\"\n    Start an agent process to poll one or more work queues for flow runs.\n    \"\"\"\n    work_queues = work_queues or []\n\n    if work_queue is not None:\n        # try to treat the work_queue as a UUID\n        try:\n            async with get_client() as client:\n                q = await client.read_work_queue(UUID(work_queue))\n                work_queue = q.name\n        # otherwise treat it as a string name\n        except (TypeError, ValueError):\n            pass\n        work_queues.append(work_queue)\n        app.console.print(\n            (\n                \"Agents now support multiple work queues. Instead of passing a single\"\n                \" argument, provide work queue names with the `-q` or `--work-queue`\"\n                f\" flag: `prefect agent start -q {work_queue}`\\n\"\n            ),\n            style=\"blue\",\n        )\n    if work_pool_name:\n        is_queues_paused = await _check_work_queues_paused(\n            work_pool_name=work_pool_name,\n            work_queues=work_queues,\n        )\n        if is_queues_paused:\n            queue_scope = (\n                \"The 'default' work queue\"\n                if not work_queues\n                else \"Specified work queue(s)\"\n            )\n            app.console.print(\n                (\n                    f\"{queue_scope} in the work pool {work_pool_name!r} is currently\"\n                    \" paused. This agent will not execute any flow runs until the work\"\n                    \" queue(s) are unpaused.\"\n                ),\n                style=\"yellow\",\n            )\n\n    if not work_queues and not tags and not work_queue_prefix and not work_pool_name:\n        exit_with_error(\"No work queues provided!\", style=\"red\")\n    elif bool(work_queues) + bool(tags) + bool(work_queue_prefix) &gt; 1:\n        exit_with_error(\n            \"Only one of `work_queues`, `match`, or `tags` can be provided.\",\n            style=\"red\",\n        )\n    if work_pool_name and tags:\n        exit_with_error(\n            \"`tag` and `pool` options cannot be used together.\", style=\"red\"\n        )\n\n    if tags:\n        work_queue_name = f\"Agent queue {'-'.join(sorted(tags))}\"\n        app.console.print(\n            (\n                \"`tags` are deprecated. For backwards-compatibility with old versions\"\n                \" of Prefect, this agent will create a work queue named\"\n                f\" `{work_queue_name}` that uses legacy tag-based matching. This option\"\n                \" will be removed on 2023-02-23.\"\n            ),\n            style=\"red\",\n        )\n\n        async with get_client() as client:\n            try:\n                work_queue = await client.read_work_queue_by_name(work_queue_name)\n                if work_queue.filter is None:\n                    # ensure the work queue has legacy (deprecated) tag-based behavior\n                    await client.update_work_queue(filter=dict(tags=tags))\n            except ObjectNotFound:\n                # if the work queue doesn't already exist, we create it with tags\n                # to enable legacy (deprecated) tag-matching behavior\n                await client.create_work_queue(name=work_queue_name, tags=tags)\n\n        work_queues = [work_queue_name]\n\n    if not hide_welcome:\n        if api:\n            app.console.print(\n                f\"Starting v{prefect.__version__} agent connected to {api}...\"\n            )\n        else:\n            app.console.print(\n                f\"Starting v{prefect.__version__} agent with ephemeral API...\"\n            )\n\n    agent_process_id = os.getpid()\n    setup_signal_handlers_agent(\n        agent_process_id, \"the Prefect agent\", app.console.print\n    )\n\n    async with PrefectAgent(\n        work_queues=work_queues,\n        work_queue_prefix=work_queue_prefix,\n        work_pool_name=work_pool_name,\n        prefetch_seconds=prefetch_seconds,\n        limit=limit,\n    ) as agent:\n        if not hide_welcome:\n            app.console.print(ascii_name)\n            if work_pool_name:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"work pool '{work_pool_name}'...\"\n                )\n            elif work_queue_prefix:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"queue(s) that start with the prefix: {work_queue_prefix}...\"\n                )\n            else:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"queue(s): {', '.join(work_queues)}...\"\n                )\n\n        try:\n            async with anyio.create_task_group() as tg:\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        agent.get_and_submit_flow_runs,\n                        PREFECT_AGENT_QUERY_INTERVAL.value(),\n                        printer=app.console.print,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                        backoff=4,  # Up to ~1 minute interval during backoff\n                    )\n                )\n\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        agent.check_for_cancelled_flow_runs,\n                        PREFECT_AGENT_QUERY_INTERVAL.value() * 2,\n                        printer=app.console.print,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n        except CancelledError:\n            logger.debug(\"Agent task group cancelled\")\n\n    app.console.print(\"Agent stopped!\")\n</code></pre>","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/artifact/","title":"artifact","text":"","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact","title":"<code>prefect.cli.artifact</code>","text":"","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>Optional[str]</code> <p>the key of the artifact to delete</p> <code>Argument(None, help='The key of the artifact to delete.')</code> <p>Examples:</p> <p>$ prefect artifact delete \"my-artifact\"</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"delete\")\nasync def delete(\n    key: Optional[str] = typer.Argument(\n        None, help=\"The key of the artifact to delete.\"\n    ),\n    artifact_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"The ID of the artifact to delete.\"\n    ),\n):\n    \"\"\"\n    Delete an artifact.\n\n    Arguments:\n        key: the key of the artifact to delete\n\n    Examples:\n        $ prefect artifact delete \"my-artifact\"\n    \"\"\"\n    if key and artifact_id:\n        exit_with_error(\"Please provide either a key or an artifact_id but not both.\")\n\n    async with get_client() as client:\n        if artifact_id is not None:\n            try:\n                confirm_delete = typer.confirm(\n                    (\n                        \"Are you sure you want to delete artifact with id\"\n                        f\" {artifact_id!r}?\"\n                    ),\n                    default=False,\n                )\n                if not confirm_delete:\n                    exit_with_error(\"Deletion aborted.\")\n\n                await client.delete_artifact(artifact_id)\n                exit_with_success(f\"Deleted artifact with id {artifact_id!r}.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Artifact with id {artifact_id!r} not found!\")\n\n        elif key is not None:\n            artifacts = await client.read_artifacts(\n                artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n            )\n            if not artifacts:\n                exit_with_error(\n                    f\"Artifact with key {key!r} not found. You can also specify an\"\n                    \" artifact id with the --id flag.\"\n                )\n\n            confirm_delete = typer.confirm(\n                (\n                    f\"Are you sure you want to delete {len(artifacts)} artifact(s) with\"\n                    f\" key {key!r}?\"\n                ),\n                default=False,\n            )\n            if not confirm_delete:\n                exit_with_error(\"Deletion aborted.\")\n\n            for a in artifacts:\n                await client.delete_artifact(a.id)\n\n            exit_with_success(f\"Deleted {len(artifacts)} artifact(s) with key {key!r}.\")\n\n        else:\n            exit_with_error(\"Please provide a key or an artifact_id.\")\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<pre><code>View details about an artifact.\n\nArguments:\n    key: the key of the artifact to inspect\n\nExamples:\n    $ prefect artifact inspect \"my-artifact\"\n   [\n    {\n        'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',\n        'created': '2023-03-21T21:40:09.895910+00:00',\n        'updated': '2023-03-21T21:40:09.895910+00:00',\n        'key': 'my-artifact',\n        'type': 'markdown',\n        'description': None,\n        'data': 'my markdown',\n        'metadata_': None,\n        'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',\n        'task_run_id': None\n    },\n    {\n        'id': '57f235b5-2576-45a5-bd93-c829c2900966',\n        'created': '2023-03-27T23:16:15.536434+00:00',\n        'updated': '2023-03-27T23:16:15.536434+00:00',\n        'key': 'my-artifact',\n        'type': 'markdown',\n        'description': 'my-artifact-description',\n        'data': 'my markdown',\n        'metadata_': None,\n        'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',\n        'task_run_id': None\n    }\n</code></pre> <p>]</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"inspect\")\nasync def inspect(\n    key: str,\n    limit: int = typer.Option(\n        10,\n        \"--limit\",\n        help=\"The maximum number of artifacts to return.\",\n    ),\n):\n    \"\"\"\n        View details about an artifact.\n\n        Arguments:\n            key: the key of the artifact to inspect\n\n        Examples:\n            $ prefect artifact inspect \"my-artifact\"\n           [\n            {\n                'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',\n                'created': '2023-03-21T21:40:09.895910+00:00',\n                'updated': '2023-03-21T21:40:09.895910+00:00',\n                'key': 'my-artifact',\n                'type': 'markdown',\n                'description': None,\n                'data': 'my markdown',\n                'metadata_': None,\n                'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',\n                'task_run_id': None\n            },\n            {\n                'id': '57f235b5-2576-45a5-bd93-c829c2900966',\n                'created': '2023-03-27T23:16:15.536434+00:00',\n                'updated': '2023-03-27T23:16:15.536434+00:00',\n                'key': 'my-artifact',\n                'type': 'markdown',\n                'description': 'my-artifact-description',\n                'data': 'my markdown',\n                'metadata_': None,\n                'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',\n                'task_run_id': None\n            }\n    ]\n    \"\"\"\n\n    async with get_client() as client:\n        artifacts = await client.read_artifacts(\n            limit=limit,\n            sort=ArtifactSort.UPDATED_DESC,\n            artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n        )\n        if not artifacts:\n            exit_with_error(f\"Artifact {key!r} not found.\")\n\n        artifacts = [a.dict(json_compatible=True) for a in artifacts]\n\n        app.console.print(Pretty(artifacts))\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.list_artifacts","title":"<code>list_artifacts</code>  <code>async</code>","text":"<p>List artifacts.</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"ls\")\nasync def list_artifacts(\n    limit: int = typer.Option(\n        100,\n        \"--limit\",\n        help=\"The maximum number of artifacts to return.\",\n    ),\n    all: bool = typer.Option(\n        False,\n        \"--all\",\n        \"-a\",\n        help=\"Whether or not to only return the latest version of each artifact.\",\n    ),\n):\n    \"\"\"\n    List artifacts.\n    \"\"\"\n    table = Table(\n        title=\"Artifacts\",\n        caption=\"List Artifacts using `prefect artifact ls`\",\n        show_header=True,\n    )\n\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Key\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Type\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Updated\", style=\"blue\", no_wrap=True)\n\n    async with get_client() as client:\n        if all:\n            artifacts = await client.read_artifacts(\n                sort=ArtifactSort.KEY_ASC,\n                limit=limit,\n            )\n\n            for artifact in sorted(artifacts, key=lambda x: f\"{x.key}\"):\n                table.add_row(\n                    str(artifact.id),\n                    artifact.key,\n                    artifact.type,\n                    pendulum.instance(artifact.updated).diff_for_humans(),\n                )\n\n        else:\n            artifacts = await client.read_latest_artifacts(\n                sort=ArtifactCollectionSort.KEY_ASC,\n                limit=limit,\n            )\n\n            for artifact in sorted(artifacts, key=lambda x: f\"{x.key}\"):\n                table.add_row(\n                    str(artifact.latest_id),\n                    artifact.key,\n                    artifact.type,\n                    pendulum.instance(artifact.updated).diff_for_humans(),\n                )\n\n        app.console.print(table)\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/block/","title":"block","text":"","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block","title":"<code>prefect.cli.block</code>","text":"<p>Command line interface for working with blocks.</p>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_create","title":"<code>block_create</code>  <code>async</code>","text":"<p>Generate a link to the Prefect UI to create a block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"create\")\nasync def block_create(\n    block_type_slug: str = typer.Argument(\n        ...,\n        help=\"A block type slug. View available types with: prefect block type ls\",\n        show_default=False,\n    ),\n):\n    \"\"\"\n    Generate a link to the Prefect UI to create a block.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(block_type_slug)\n        except ObjectNotFound:\n            app.console.print(f\"[red]Block type {block_type_slug!r} not found![/red]\")\n            block_types = await client.read_block_types()\n            slugs = {block_type.slug for block_type in block_types}\n            app.console.print(f\"Available block types: {', '.join(slugs)}\")\n            raise typer.Exit(1)\n\n        if not PREFECT_UI_URL:\n            exit_with_error(\n                \"Prefect must be configured to use a hosted Prefect server or \"\n                \"Prefect Cloud to display the Prefect UI\"\n            )\n\n        block_link = f\"{PREFECT_UI_URL.value()}/blocks/catalog/{block_type.slug}/create\"\n        app.console.print(\n            f\"Create a {block_type_slug} block: {block_link}\",\n        )\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_delete","title":"<code>block_delete</code>  <code>async</code>","text":"<p>Delete a configured block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"delete\")\nasync def block_delete(\n    slug: Optional[str] = typer.Argument(\n        None, help=\"A block slug. Formatted as '&lt;BLOCK_TYPE_SLUG&gt;/&lt;BLOCK_NAME&gt;'\"\n    ),\n    block_id: Optional[str] = typer.Option(None, \"--id\", help=\"A block id.\"),\n):\n    \"\"\"\n    Delete a configured block.\n    \"\"\"\n    async with get_client() as client:\n        if slug is None and block_id is not None:\n            try:\n                await client.delete_block_document(block_id)\n                exit_with_success(f\"Deleted Block '{block_id}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {block_id!r} not found!\")\n        elif slug is not None:\n            if \"/\" not in slug:\n                exit_with_error(\n                    f\"{slug!r} is not valid. Slug must contain a '/', e.g. 'json/my-json-block'\"\n                )\n            block_type_slug, block_document_name = slug.split(\"/\")\n            try:\n                block_document = await client.read_block_document_by_name(\n                    block_document_name, block_type_slug, include_secrets=False\n                )\n                await client.delete_block_document(block_document.id)\n                exit_with_success(f\"Deleted Block '{slug}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Block {slug!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a block slug or id\")\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_inspect","title":"<code>block_inspect</code>  <code>async</code>","text":"<p>Displays details about a configured block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"inspect\")\nasync def block_inspect(\n    slug: Optional[str] = typer.Argument(\n        None, help=\"A Block slug: &lt;BLOCK_TYPE_SLUG&gt;/&lt;BLOCK_NAME&gt;\"\n    ),\n    block_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"A Block id to search for if no slug is given\"\n    ),\n):\n    \"\"\"\n    Displays details about a configured block.\n    \"\"\"\n    async with get_client() as client:\n        if slug is None and block_id is not None:\n            try:\n                block_document = await client.read_block_document(\n                    block_id, include_secrets=False\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {block_id!r} not found!\")\n        elif slug is not None:\n            if \"/\" not in slug:\n                exit_with_error(\n                    f\"{slug!r} is not valid. Slug must contain a '/', e.g. 'json/my-json-block'\"\n                )\n            block_type_slug, block_document_name = slug.split(\"/\")\n            try:\n                block_document = await client.read_block_document_by_name(\n                    block_document_name, block_type_slug, include_secrets=False\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"Block {slug!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a block slug or id\")\n        app.console.print(display_block(block_document))\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_ls","title":"<code>block_ls</code>  <code>async</code>","text":"<p>View all configured blocks.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"ls\")\nasync def block_ls():\n    \"\"\"\n    View all configured blocks.\n    \"\"\"\n    async with get_client() as client:\n        blocks = await client.read_block_documents()\n\n    table = Table(\n        title=\"Blocks\", caption=\"List Block Types using `prefect block type ls`\"\n    )\n    table.add_column(\"ID\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Type\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Slug\", style=\"blue\", no_wrap=True)\n\n    for block in sorted(blocks, key=lambda x: f\"{x.block_type.slug}/{x.name}\"):\n        table.add_row(\n            str(block.id),\n            block.block_type.name,\n            str(block.name),\n            f\"{block.block_type.slug}/{block.name}\",\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.blocktype_delete","title":"<code>blocktype_delete</code>  <code>async</code>","text":"<p>Delete an unprotected Block Type.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"delete\")\nasync def blocktype_delete(\n    slug: str = typer.Argument(..., help=\"A Block type slug\"),\n):\n    \"\"\"\n    Delete an unprotected Block Type.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(slug)\n            await client.delete_block_type(block_type.id)\n            exit_with_success(f\"Deleted Block Type '{slug}'.\")\n        except ObjectNotFound:\n            exit_with_error(f\"Block Type {slug!r} not found!\")\n        except ProtectedBlockError:\n            exit_with_error(f\"Block Type {slug!r} is a protected block!\")\n        except PrefectHTTPStatusError:\n            exit_with_error(f\"Cannot delete Block Type {slug!r}!\")\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.blocktype_inspect","title":"<code>blocktype_inspect</code>  <code>async</code>","text":"<p>Display details about a block type.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"inspect\")\nasync def blocktype_inspect(\n    slug: str = typer.Argument(..., help=\"A block type slug\"),\n):\n    \"\"\"\n    Display details about a block type.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(slug)\n        except ObjectNotFound:\n            exit_with_error(f\"Block type {slug!r} not found!\")\n\n        app.console.print(display_block_type(block_type))\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.list_types","title":"<code>list_types</code>  <code>async</code>","text":"<p>List all block types.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"ls\")\nasync def list_types():\n    \"\"\"\n    List all block types.\n    \"\"\"\n    async with get_client() as client:\n        block_types = await client.read_block_types()\n\n    table = Table(\n        title=\"Block Types\",\n        show_lines=True,\n    )\n\n    table.add_column(\"Block Type Slug\", style=\"italic cyan\", no_wrap=True)\n    table.add_column(\"Description\", style=\"blue\", no_wrap=False, justify=\"left\")\n    table.add_column(\n        \"Generate creation link\", style=\"italic cyan\", no_wrap=False, justify=\"left\"\n    )\n\n    for blocktype in sorted(block_types, key=lambda x: x.name):\n        table.add_row(\n            str(blocktype.slug),\n            (\n                str(blocktype.description.splitlines()[0].partition(\".\")[0])\n                if blocktype.description is not None\n                else \"\"\n            ),\n            f\"prefect block create {blocktype.slug}\",\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.register","title":"<code>register</code>  <code>async</code>","text":"<p>Register blocks types within a module or file.</p> <p>This makes the blocks available for configuration via the UI. If a block type has already been registered, its registration will be updated to match the block's current definition.</p> <p>\b Examples:     \b     Register block types in a Python module:     $ prefect block register -m prefect_aws.credentials     \b     Register block types in a .py file:     $ prefect block register -f my_blocks.py</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command()\nasync def register(\n    module_name: Optional[str] = typer.Option(\n        None,\n        \"--module\",\n        \"-m\",\n        help=\"Python module containing block types to be registered\",\n    ),\n    file_path: Optional[Path] = typer.Option(\n        None,\n        \"--file\",\n        \"-f\",\n        help=\"Path to .py file containing block types to be registered\",\n    ),\n):\n    \"\"\"\n    Register blocks types within a module or file.\n\n    This makes the blocks available for configuration via the UI.\n    If a block type has already been registered, its registration will be updated to\n    match the block's current definition.\n\n    \\b\n    Examples:\n        \\b\n        Register block types in a Python module:\n        $ prefect block register -m prefect_aws.credentials\n        \\b\n        Register block types in a .py file:\n        $ prefect block register -f my_blocks.py\n    \"\"\"\n    # Handles if both options are specified or if neither are specified\n    if not (bool(file_path) ^ bool(module_name)):\n        exit_with_error(\n            \"Please specify either a module or a file containing blocks to be\"\n            \" registered, but not both.\"\n        )\n\n    if module_name:\n        try:\n            imported_module = import_module(name=module_name)\n        except ModuleNotFoundError:\n            exit_with_error(\n                f\"Unable to load {module_name}. Please make sure the module is \"\n                \"installed in your current environment.\"\n            )\n\n    if file_path:\n        if file_path.suffix != \".py\":\n            exit_with_error(\n                f\"{file_path} is not a .py file. Please specify a \"\n                \".py that contains blocks to be registered.\"\n            )\n        try:\n            imported_module = await run_sync_in_worker_thread(\n                load_script_as_module, str(file_path)\n            )\n        except ScriptError as exc:\n            app.console.print(exc)\n            app.console.print(exception_traceback(exc.user_exc))\n            exit_with_error(\n                f\"Unable to load file at {file_path}. Please make sure the file path \"\n                \"is correct and the file contains valid Python.\"\n            )\n\n    registered_blocks = await _register_blocks_in_module(imported_module)\n    number_of_registered_blocks = len(registered_blocks)\n    block_text = \"block\" if 0 &lt; number_of_registered_blocks &lt; 2 else \"blocks\"\n    app.console.print(\n        f\"[green]Successfully registered {number_of_registered_blocks} {block_text}\\n\"\n    )\n    app.console.print(_build_registered_blocks_table(registered_blocks))\n    msg = (\n        \"\\n To configure the newly registered blocks, \"\n        \"go to the Blocks page in the Prefect UI.\\n\"\n    )\n\n    ui_url = PREFECT_UI_URL.value()\n    if ui_url is not None:\n        block_catalog_url = f\"{ui_url}/blocks/catalog\"\n        msg = f\"{msg.rstrip().rstrip('.')}: {block_catalog_url}\\n\"\n\n    app.console.print(msg)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/cloud-webhook/","title":"Cloud webhook","text":"","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook","title":"<code>prefect.cli.cloud.webhook</code>","text":"<p>Command line interface for working with webhooks</p>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def create(\n    webhook_name: str,\n    description: str = typer.Option(\n        \"\", \"--description\", \"-d\", help=\"Description of the webhook\"\n    ),\n    template: str = typer.Option(\n        None, \"--template\", \"-t\", help=\"Jinja2 template expression\"\n    ),\n):\n    \"\"\"\n    Create a new Cloud webhook\n    \"\"\"\n    if not template:\n        exit_with_error(\n            \"Please provide a Jinja2 template expression in the --template flag \\nwhich\"\n            ' should define (at minimum) the following attributes: \\n{ \"event\":'\n            ' \"your.event.name\", \"resource\": { \"prefect.resource.id\":'\n            ' \"your.resource.id\" } }'\n            \" \\nhttps://docs.prefect.io/latest/cloud/webhooks/#webhook-templates\"\n        )\n\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\n            \"POST\",\n            \"/webhooks/\",\n            json={\n                \"name\": webhook_name,\n                \"description\": description,\n                \"template\": template,\n            },\n        )\n        app.console.print(f'Successfully created webhook {response[\"name\"]}')\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def delete(webhook_id: UUID):\n    \"\"\"\n    Delete an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    confirm_delete = typer.confirm(\n        \"Are you sure you want to delete it? This cannot be undone.\"\n    )\n\n    if not confirm_delete:\n        return\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        await client.request(\"DELETE\", f\"/webhooks/{webhook_id}\")\n        app.console.print(f\"Successfully deleted webhook {webhook_id}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.get","title":"<code>get</code>  <code>async</code>","text":"<p>Retrieve a webhook by ID.</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def get(webhook_id: UUID):\n    \"\"\"\n    Retrieve a webhook by ID.\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        webhook = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        display_table = _render_webhooks_into_table([webhook])\n        app.console.print(display_table)\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>Fetch and list all webhooks in your workspace</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def ls():\n    \"\"\"\n    Fetch and list all webhooks in your workspace\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        retrieved_webhooks = await client.request(\"POST\", \"/webhooks/filter\")\n        display_table = _render_webhooks_into_table(retrieved_webhooks)\n        app.console.print(display_table)\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.rotate","title":"<code>rotate</code>  <code>async</code>","text":"<p>Rotate url for an existing Cloud webhook, in case it has been compromised</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def rotate(webhook_id: UUID):\n    \"\"\"\n    Rotate url for an existing Cloud webhook, in case it has been compromised\n    \"\"\"\n    confirm_logged_in()\n\n    confirm_rotate = typer.confirm(\n        \"Are you sure you want to rotate? This will invalidate the old URL.\"\n    )\n\n    if not confirm_rotate:\n        return\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"POST\", f\"/webhooks/{webhook_id}/rotate\")\n        app.console.print(f'Successfully rotated webhook URL to {response[\"slug\"]}')\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.toggle","title":"<code>toggle</code>  <code>async</code>","text":"<p>Toggle the enabled status of an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def toggle(\n    webhook_id: UUID,\n):\n    \"\"\"\n    Toggle the enabled status of an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    status_lookup = {True: \"enabled\", False: \"disabled\"}\n\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        current_status = response[\"enabled\"]\n        new_status = not current_status\n\n        await client.request(\n            \"PATCH\", f\"/webhooks/{webhook_id}\", json={\"enabled\": new_status}\n        )\n        app.console.print(f\"Webhook is now {status_lookup[new_status]}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.update","title":"<code>update</code>  <code>async</code>","text":"<p>Partially update an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def update(\n    webhook_id: UUID,\n    webhook_name: str = typer.Option(None, \"--name\", \"-n\", help=\"Webhook name\"),\n    description: str = typer.Option(\n        None, \"--description\", \"-d\", help=\"Description of the webhook\"\n    ),\n    template: str = typer.Option(\n        None, \"--template\", \"-t\", help=\"Jinja2 template expression\"\n    ),\n):\n    \"\"\"\n    Partially update an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        update_payload = {\n            \"name\": webhook_name or response[\"name\"],\n            \"description\": description or response[\"description\"],\n            \"template\": template or response[\"template\"],\n        }\n\n        await client.request(\"PUT\", f\"/webhooks/{webhook_id}\", json=update_payload)\n        app.console.print(f\"Successfully updated webhook {webhook_id}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud/","title":"cloud","text":"","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud","title":"<code>prefect.cli.cloud</code>","text":"<p>Command line interface for interacting with Prefect Cloud</p>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login_api","title":"<code>login_api = FastAPI(lifespan=lifespan)</code>  <code>module-attribute</code>","text":"<p>This small API server is used for data transmission for browser-based log in.</p>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.check_key_is_valid_for_login","title":"<code>check_key_is_valid_for_login</code>  <code>async</code>","text":"<p>Attempt to use a key to see if it is valid</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>async def check_key_is_valid_for_login(key: str):\n    \"\"\"\n    Attempt to use a key to see if it is valid\n    \"\"\"\n    async with get_cloud_client(api_key=key) as client:\n        try:\n            await client.read_workspaces()\n            return True\n        except CloudUnauthorizedError:\n            return False\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login","title":"<code>login</code>  <code>async</code>","text":"<p>Log in to Prefect Cloud. Creates a new profile configured to use the specified PREFECT_API_KEY. Uses a previously configured profile if it exists.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def login(\n    key: Optional[str] = typer.Option(\n        None, \"--key\", \"-k\", help=\"API Key to authenticate with Prefect\"\n    ),\n    workspace_handle: Optional[str] = typer.Option(\n        None,\n        \"--workspace\",\n        \"-w\",\n        help=(\n            \"Full handle of workspace, in format '&lt;account_handle&gt;/&lt;workspace_handle&gt;'\"\n        ),\n    ),\n):\n    \"\"\"\n    Log in to Prefect Cloud.\n    Creates a new profile configured to use the specified PREFECT_API_KEY.\n    Uses a previously configured profile if it exists.\n    \"\"\"\n    if not is_interactive() and (not key or not workspace_handle):\n        exit_with_error(\n            \"When not using an interactive terminal, you must supply a `--key` and\"\n            \" `--workspace`.\"\n        )\n\n    profiles = load_profiles()\n    current_profile = get_settings_context().profile\n    env_var_api_key = PREFECT_API_KEY.value()\n    selected_workspace = None\n\n    if env_var_api_key and key and env_var_api_key != key:\n        exit_with_error(\n            \"Cannot log in with a key when a different PREFECT_API_KEY is present as an\"\n            \" environment variable that will override it.\"\n        )\n\n    if env_var_api_key and env_var_api_key == key:\n        is_valid_key = await check_key_is_valid_for_login(key)\n        is_correct_key_format = key.startswith(\"pnu_\") or key.startswith(\"pnb_\")\n        if not is_valid_key:\n            help_message = \"Please ensure your credentials are correct and unexpired.\"\n            if not is_correct_key_format:\n                help_message = \"Your key is not in our expected format.\"\n            exit_with_error(\n                f\"Unable to authenticate with Prefect Cloud. {help_message}\"\n            )\n\n    already_logged_in_profiles = []\n    for name, profile in profiles.items():\n        profile_key = profile.settings.get(PREFECT_API_KEY)\n        if (\n            # If a key is provided, only show profiles with the same key\n            (key and profile_key == key)\n            # Otherwise, show all profiles with a key set\n            or (not key and profile_key is not None)\n            # Check that the key is usable to avoid suggesting unauthenticated profiles\n            and await check_key_is_valid_for_login(profile_key)\n        ):\n            already_logged_in_profiles.append(name)\n\n    current_profile_is_logged_in = current_profile.name in already_logged_in_profiles\n\n    if current_profile_is_logged_in:\n        app.console.print(\"It looks like you're already authenticated on this profile.\")\n        if is_interactive():\n            should_reauth = typer.confirm(\n                \"? Would you like to reauthenticate?\", default=False\n            )\n        else:\n            should_reauth = True\n\n        if not should_reauth:\n            app.console.print(\"Using the existing authentication on this profile.\")\n            key = PREFECT_API_KEY.value()\n\n    elif already_logged_in_profiles:\n        app.console.print(\n            \"It looks like you're already authenticated with another profile.\"\n        )\n        if typer.confirm(\n            \"? Would you like to switch profiles?\",\n            default=True,\n        ):\n            profile_name = prompt_select_from_list(\n                app.console,\n                \"Which authenticated profile would you like to switch to?\",\n                already_logged_in_profiles,\n            )\n\n            profiles.set_active(profile_name)\n            save_profiles(profiles)\n            exit_with_success(f\"Switched to authenticated profile {profile_name!r}.\")\n\n    if not key:\n        choice = prompt_select_from_list(\n            app.console,\n            \"How would you like to authenticate?\",\n            [\n                (\"browser\", \"Log in with a web browser\"),\n                (\"key\", \"Paste an API key\"),\n            ],\n        )\n\n        if choice == \"key\":\n            key = typer.prompt(\"Paste your API key\", hide_input=True)\n        elif choice == \"browser\":\n            key = await login_with_browser()\n\n    async with get_cloud_client(api_key=key) as client:\n        try:\n            workspaces = await client.read_workspaces()\n            current_workspace = get_current_workspace(workspaces)\n            prompt_switch_workspace = False\n        except CloudUnauthorizedError:\n            if key.startswith(\"pcu\"):\n                help_message = (\n                    \"It looks like you're using API key from Cloud 1\"\n                    \" (https://cloud.prefect.io). Make sure that you generate API key\"\n                    \" using Cloud 2 (https://app.prefect.cloud)\"\n                )\n            elif not key.startswith(\"pnu_\") and not key.startswith(\"pnb_\"):\n                help_message = (\n                    \"Your key is not in our expected format: 'pnu_' or 'pnb_'.\"\n                )\n            else:\n                help_message = (\n                    \"Please ensure your credentials are correct and unexpired.\"\n                )\n            exit_with_error(\n                f\"Unable to authenticate with Prefect Cloud. {help_message}\"\n            )\n        except httpx.HTTPStatusError as exc:\n            exit_with_error(f\"Error connecting to Prefect Cloud: {exc!r}\")\n\n    if workspace_handle:\n        # Search for the given workspace\n        for workspace in workspaces:\n            if workspace.handle == workspace_handle:\n                selected_workspace = workspace\n                break\n        else:\n            if workspaces:\n                hint = (\n                    \" Available workspaces:\"\n                    f\" {listrepr((w.handle for w in workspaces), ', ')}\"\n                )\n            else:\n                hint = \"\"\n\n            exit_with_error(f\"Workspace {workspace_handle!r} not found.\" + hint)\n    else:\n        # Prompt a switch if the number of workspaces is greater than one\n        prompt_switch_workspace = len(workspaces) &gt; 1\n\n        # Confirm that we want to switch if the current profile is already logged in\n        if (\n            current_profile_is_logged_in and current_workspace is not None\n        ) and prompt_switch_workspace:\n            app.console.print(\n                f\"You are currently using workspace {current_workspace.handle!r}.\"\n            )\n            prompt_switch_workspace = typer.confirm(\n                \"? Would you like to switch workspaces?\", default=False\n            )\n    if prompt_switch_workspace:\n        go_back = True\n        while go_back:\n            selected_workspace, go_back = await _prompt_for_account_and_workspace(\n                workspaces\n            )\n        if selected_workspace is None:\n            exit_with_error(\"No workspace selected.\")\n\n    elif not selected_workspace and not workspace_handle:\n        if current_workspace:\n            selected_workspace = current_workspace\n        elif len(workspaces) &gt; 0:\n            selected_workspace = workspaces[0]\n        else:\n            exit_with_error(\n                \"No workspaces found! Create a workspace at\"\n                f\" {PREFECT_CLOUD_UI_URL.value()} and try again.\"\n            )\n\n    update_current_profile(\n        {\n            PREFECT_API_KEY: key,\n            PREFECT_API_URL: selected_workspace.api_url(),\n        }\n    )\n\n    exit_with_success(\n        f\"Authenticated with Prefect Cloud! Using workspace {selected_workspace.handle!r}.\"\n    )\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login_with_browser","title":"<code>login_with_browser</code>  <code>async</code>","text":"<p>Perform login using the browser.</p> <p>On failure, this function will exit the process. On success, it will return an API key.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>async def login_with_browser() -&gt; str:\n    \"\"\"\n    Perform login using the browser.\n\n    On failure, this function will exit the process.\n    On success, it will return an API key.\n    \"\"\"\n\n    # Set up an event that the login API will toggle on startup\n    ready_event = login_api.extra[\"ready-event\"] = anyio.Event()\n\n    # Set up an event that the login API will set when a response comes from the UI\n    result_event = login_api.extra[\"result-event\"] = anyio.Event()\n\n    timeout_scope = None\n    async with anyio.create_task_group() as tg:\n        # Run a server in the background to get payload from the browser\n        server = await tg.start(serve_login_api, tg.cancel_scope)\n\n        # Wait for the login server to be ready\n        with anyio.fail_after(10):\n            await ready_event.wait()\n\n            # The server may not actually be serving as the lifespan is started first\n            while not server.started:\n                await anyio.sleep(0)\n\n        # Get the port the server is using\n        server_port = server.servers[0].sockets[0].getsockname()[1]\n        callback = urllib.parse.quote(f\"http://localhost:{server_port}\")\n        ui_login_url = (\n            PREFECT_CLOUD_UI_URL.value() + f\"/auth/client?callback={callback}\"\n        )\n\n        # Then open the authorization page in a new browser tab\n        app.console.print(\"Opening browser...\")\n        await run_sync_in_worker_thread(webbrowser.open_new_tab, ui_login_url)\n\n        # Wait for the response from the browser,\n        with anyio.move_on_after(120) as timeout_scope:\n            app.console.print(\"Waiting for response...\")\n            await result_event.wait()\n\n        # Shut down the background uvicorn server\n        tg.cancel_scope.cancel()\n\n    result = login_api.extra.get(\"result\")\n    if not result:\n        if timeout_scope and timeout_scope.cancel_called:\n            exit_with_error(\"Timed out while waiting for authorization.\")\n        else:\n            exit_with_error(\"Aborted.\")\n\n    if result.type == \"success\":\n        return result.content.api_key\n    elif result.type == \"failure\":\n        exit_with_error(f\"Failed to log in. {result.content.reason}\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.logout","title":"<code>logout</code>  <code>async</code>","text":"<p>Logout the current workspace. Reset PREFECT_API_KEY and PREFECT_API_URL to default.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def logout():\n    \"\"\"\n    Logout the current workspace.\n    Reset PREFECT_API_KEY and PREFECT_API_URL to default.\n    \"\"\"\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile is None:\n        exit_with_error(\"There is no current profile set.\")\n\n    if current_profile.settings.get(PREFECT_API_KEY) is None:\n        exit_with_error(\"Current profile is not logged into Prefect Cloud.\")\n\n    update_current_profile(\n        {\n            PREFECT_API_URL: None,\n            PREFECT_API_KEY: None,\n        },\n    )\n\n    exit_with_success(\"Logged out from Prefect Cloud.\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>List available workspaces.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@workspace_app.command()\nasync def ls():\n    \"\"\"List available workspaces.\"\"\"\n\n    confirm_logged_in()\n\n    async with get_cloud_client() as client:\n        try:\n            workspaces = await client.read_workspaces()\n        except CloudUnauthorizedError:\n            exit_with_error(\n                \"Unable to authenticate. Please ensure your credentials are correct.\"\n            )\n\n    current_workspace = get_current_workspace(workspaces)\n\n    table = Table(caption=\"* active workspace\")\n    table.add_column(\n        \"[#024dfd]Workspaces:\", justify=\"left\", style=\"#8ea0ae\", no_wrap=True\n    )\n\n    for workspace_handle in sorted(workspace.handle for workspace in workspaces):\n        if workspace_handle == current_workspace.handle:\n            table.add_row(f\"[green]* {workspace_handle}[/green]\")\n        else:\n            table.add_row(f\"  {workspace_handle}\")\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.open","title":"<code>open</code>  <code>async</code>","text":"<p>Open the Prefect Cloud UI in the browser.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def open():\n    \"\"\"\n    Open the Prefect Cloud UI in the browser.\n    \"\"\"\n    confirm_logged_in()\n\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile is None:\n        exit_with_error(\n            \"There is no current profile set - set one with `prefect profile create\"\n            \" &lt;name&gt;` and `prefect profile use &lt;name&gt;`.\"\n        )\n\n    current_workspace = get_current_workspace(\n        await prefect.get_cloud_client().read_workspaces()\n    )\n    if current_workspace is None:\n        exit_with_error(\n            \"There is no current workspace set - set one with `prefect cloud workspace\"\n            \" set --workspace &lt;workspace&gt;`.\"\n        )\n\n    ui_url = current_workspace.ui_url()\n\n    await run_sync_in_worker_thread(webbrowser.open_new_tab, ui_url)\n\n    exit_with_success(f\"Opened {current_workspace.handle!r} in browser.\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.prompt_select_from_list","title":"<code>prompt_select_from_list</code>","text":"<p>Given a list of options, display the values to user in a table and prompt them to select one.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>Union[List[str], List[Tuple[Hashable, str]]]</code> <p>A list of options to present to the user. A list of tuples can be passed as key value pairs. If a value is chosen, the key will be returned.</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>the selected option</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>def prompt_select_from_list(\n    console, prompt: str, options: Union[List[str], List[Tuple[Hashable, str]]]\n) -&gt; str:\n    \"\"\"\n    Given a list of options, display the values to user in a table and prompt them\n    to select one.\n\n    Args:\n        options: A list of options to present to the user.\n            A list of tuples can be passed as key value pairs. If a value is chosen, the\n            key will be returned.\n\n    Returns:\n        str: the selected option\n    \"\"\"\n\n    current_idx = 0\n    selected_option = None\n\n    def build_table() -&gt; Table:\n        \"\"\"\n        Generate a table of options. The `current_idx` will be highlighted.\n        \"\"\"\n\n        table = Table(box=False, header_style=None, padding=(0, 0))\n        table.add_column(\n            f\"? [bold]{prompt}[/] [bright_blue][Use arrows to move; enter to select]\",\n            justify=\"left\",\n            no_wrap=True,\n        )\n\n        for i, option in enumerate(options):\n            if isinstance(option, tuple):\n                option = option[1]\n\n            if i == current_idx:\n                # Use blue for selected options\n                table.add_row(\"[bold][blue]&gt; \" + option)\n            else:\n                table.add_row(\"  \" + option)\n        return table\n\n    with Live(build_table(), auto_refresh=False, console=console) as live:\n        while selected_option is None:\n            key = readchar.readkey()\n\n            if key == readchar.key.UP:\n                current_idx = current_idx - 1\n                # wrap to bottom if at the top\n                if current_idx &lt; 0:\n                    current_idx = len(options) - 1\n            elif key == readchar.key.DOWN:\n                current_idx = current_idx + 1\n                # wrap to top if at the bottom\n                if current_idx &gt;= len(options):\n                    current_idx = 0\n            elif key == readchar.key.CTRL_C:\n                # gracefully exit with no message\n                exit_with_error(\"\")\n            elif key == readchar.key.ENTER or key == readchar.key.CR:\n                selected_option = options[current_idx]\n                if isinstance(selected_option, tuple):\n                    selected_option = selected_option[0]\n\n            live.update(build_table(), refresh=True)\n\n        return selected_option\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.set","title":"<code>set</code>  <code>async</code>","text":"<p>Set current workspace. Shows a workspace picker if no workspace is specified.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@workspace_app.command()\nasync def set(\n    workspace_handle: str = typer.Option(\n        None,\n        \"--workspace\",\n        \"-w\",\n        help=(\n            \"Full handle of workspace, in format '&lt;account_handle&gt;/&lt;workspace_handle&gt;'\"\n        ),\n    ),\n):\n    \"\"\"Set current workspace. Shows a workspace picker if no workspace is specified.\"\"\"\n    confirm_logged_in()\n    async with get_cloud_client() as client:\n        try:\n            workspaces = await client.read_workspaces()\n        except CloudUnauthorizedError:\n            exit_with_error(\n                \"Unable to authenticate. Please ensure your credentials are correct.\"\n            )\n\n        if workspace_handle:\n            # Search for the given workspace\n            for workspace in workspaces:\n                if workspace.handle == workspace_handle:\n                    break\n            else:\n                exit_with_error(f\"Workspace {workspace_handle!r} not found.\")\n        else:\n            if not workspaces:\n                exit_with_error(\"No workspaces found in the selected account.\")\n\n            go_back = True\n            while go_back:\n                workspace, go_back = await _prompt_for_account_and_workspace(workspaces)\n            if workspace is None:\n                exit_with_error(\"No workspace selected.\")\n\n        profile = update_current_profile({PREFECT_API_URL: workspace.api_url()})\n        exit_with_success(\n            f\"Successfully set workspace to {workspace.handle!r} in profile\"\n            f\" {profile.name!r}.\"\n        )\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/concurrency_limit/","title":"concurrency_limit","text":"","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit","title":"<code>prefect.cli.concurrency_limit</code>","text":"<p>Command line interface for working with concurrency limits.</p>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a concurrency limit against a tag.</p> <p>This limit controls how many task runs with that tag may simultaneously be in a Running state.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def create(tag: str, concurrency_limit: int):\n    \"\"\"\n    Create a concurrency limit against a tag.\n\n    This limit controls how many task runs with that tag may simultaneously be in a\n    Running state.\n    \"\"\"\n\n    async with get_client() as client:\n        await client.create_concurrency_limit(\n            tag=tag, concurrency_limit=concurrency_limit\n        )\n        await client.read_concurrency_limit_by_tag(tag)\n\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n            Created concurrency limit with properties:\n                tag - {tag!r}\n                concurrency_limit - {concurrency_limit}\n\n            Delete the concurrency limit:\n                prefect concurrency-limit delete {tag!r}\n\n            Inspect the concurrency limit:\n                prefect concurrency-limit inspect {tag!r}\n        \"\"\"\n        )\n    )\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete the concurrency limit set on the specified tag.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def delete(tag: str):\n    \"\"\"\n    Delete the concurrency limit set on the specified tag.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.delete_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    exit_with_success(f\"Deleted concurrency limit set on the tag: {tag}\")\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a concurrency limit. <code>active_slots</code> shows a list of TaskRun IDs which are currently using a concurrency slot.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def inspect(tag: str):\n    \"\"\"\n    View details about a concurrency limit. `active_slots` shows a list of TaskRun IDs\n    which are currently using a concurrency slot.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            result = await client.read_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    trid_table = Table()\n    trid_table.add_column(\"Active Task Run IDs\", style=\"cyan\", no_wrap=True)\n\n    cl_table = Table(title=f\"Concurrency Limit ID: [red]{str(result.id)}\")\n    cl_table.add_column(\"Tag\", style=\"green\", no_wrap=True)\n    cl_table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    cl_table.add_column(\"Created\", style=\"magenta\", no_wrap=True)\n    cl_table.add_column(\"Updated\", style=\"magenta\", no_wrap=True)\n\n    for trid in sorted(result.active_slots):\n        trid_table.add_row(str(trid))\n\n    cl_table.add_row(\n        str(result.tag),\n        str(result.concurrency_limit),\n        Pretty(pendulum.instance(result.created).diff_for_humans()),\n        Pretty(pendulum.instance(result.updated).diff_for_humans()),\n    )\n\n    group = Group(\n        cl_table,\n        trid_table,\n    )\n    app.console.print(Panel(group, expand=False))\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all concurrency limits.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def ls(limit: int = 15, offset: int = 0):\n    \"\"\"\n    View all concurrency limits.\n    \"\"\"\n    table = Table(\n        title=\"Concurrency Limits\",\n        caption=\"inspect a concurrency limit to show active task run IDs\",\n    )\n    table.add_column(\"Tag\", style=\"green\", no_wrap=True)\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Active Task Runs\", style=\"magenta\", no_wrap=True)\n\n    async with get_client() as client:\n        concurrency_limits = await client.read_concurrency_limits(\n            limit=limit, offset=offset\n        )\n\n    for cl in sorted(concurrency_limits, key=lambda c: c.updated, reverse=True):\n        table.add_row(\n            str(cl.tag),\n            str(cl.id),\n            str(cl.concurrency_limit),\n            str(len(cl.active_slots)),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.reset","title":"<code>reset</code>  <code>async</code>","text":"<p>Resets the concurrency limit slots set on the specified tag.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def reset(tag: str):\n    \"\"\"\n    Resets the concurrency limit slots set on the specified tag.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.reset_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    exit_with_success(f\"Reset concurrency limit set on the tag: {tag}\")\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/config/","title":"config","text":"","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config","title":"<code>prefect.cli.config</code>","text":"<p>Command line interface for working with profiles</p>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.set_","title":"<code>set_</code>","text":"<p>Change the value for a setting by setting the value in the current profile.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command(\"set\")\ndef set_(settings: List[str]):\n    \"\"\"\n    Change the value for a setting by setting the value in the current profile.\n    \"\"\"\n    parsed_settings = {}\n    for item in settings:\n        try:\n            setting, value = item.split(\"=\", maxsplit=1)\n        except ValueError:\n            exit_with_error(\n                f\"Failed to parse argument {item!r}. Use the format 'VAR=VAL'.\"\n            )\n\n        if setting not in prefect.settings.SETTING_VARIABLES:\n            exit_with_error(f\"Unknown setting name {setting!r}.\")\n\n        # Guard against changing settings that tweak config locations\n        if setting in {\"PREFECT_HOME\", \"PREFECT_PROFILES_PATH\"}:\n            exit_with_error(\n                f\"Setting {setting!r} cannot be changed with this command. \"\n                \"Use an environment variable instead.\"\n            )\n\n        parsed_settings[setting] = value\n\n    try:\n        new_profile = prefect.settings.update_current_profile(parsed_settings)\n    except pydantic.ValidationError as exc:\n        for error in exc.errors():\n            setting = error[\"loc\"][0]\n            message = error[\"msg\"]\n            app.console.print(f\"Validation error for setting {setting!r}: {message}\")\n        exit_with_error(\"Invalid setting value.\")\n\n    for setting, value in parsed_settings.items():\n        app.console.print(f\"Set {setting!r} to {value!r}.\")\n        if setting in os.environ:\n            app.console.print(\n                f\"[yellow]{setting} is also set by an environment variable which will \"\n                f\"override your config value. Run `unset {setting}` to clear it.\"\n            )\n\n        if prefect.settings.SETTING_VARIABLES[setting].deprecated:\n            app.console.print(\n                f\"[yellow]{prefect.settings.SETTING_VARIABLES[setting].deprecated_message}.\"\n            )\n\n    exit_with_success(f\"Updated profile {new_profile.name!r}.\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.unset","title":"<code>unset</code>","text":"<p>Restore the default value for a setting.</p> <p>Removes the setting from the current profile.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef unset(settings: List[str]):\n    \"\"\"\n    Restore the default value for a setting.\n\n    Removes the setting from the current profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    profile = profiles[prefect.context.get_settings_context().profile.name]\n    parsed = set()\n\n    for setting in settings:\n        if setting not in prefect.settings.SETTING_VARIABLES:\n            exit_with_error(f\"Unknown setting name {setting!r}.\")\n        # Cast to settings objects\n        parsed.add(prefect.settings.SETTING_VARIABLES[setting])\n\n    for setting in parsed:\n        if setting not in profile.settings:\n            exit_with_error(f\"{setting.name!r} is not set in profile {profile.name!r}.\")\n\n    profiles.update_profile(\n        name=profile.name, settings={setting: None for setting in parsed}\n    )\n\n    for setting in settings:\n        app.console.print(f\"Unset {setting!r}.\")\n\n        if setting in os.environ:\n            app.console.print(\n                f\"[yellow]{setting!r} is also set by an environment variable. \"\n                f\"Use `unset {setting}` to clear it.\"\n            )\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"Updated profile {profile.name!r}.\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.validate","title":"<code>validate</code>","text":"<p>Read and validate the current profile.</p> <p>Deprecated settings will be automatically converted to new names unless both are set.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef validate():\n    \"\"\"\n    Read and validate the current profile.\n\n    Deprecated settings will be automatically converted to new names unless both are\n    set.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    profile = profiles[prefect.context.get_settings_context().profile.name]\n    changed = profile.convert_deprecated_renamed_settings()\n    for old, new in changed:\n        app.console.print(f\"Updated {old.name!r} to {new.name!r}.\")\n\n    for setting in profile.settings.keys():\n        if setting.deprecated:\n            app.console.print(f\"Found deprecated setting {setting.name!r}.\")\n\n    profile.validate_settings()\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(\"Configuration valid!\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.view","title":"<code>view</code>","text":"<p>Display the current settings.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef view(\n    show_defaults: Optional[bool] = typer.Option(\n        False, \"--show-defaults/--hide-defaults\", help=(show_defaults_help)\n    ),\n    show_sources: Optional[bool] = typer.Option(\n        True,\n        \"--show-sources/--hide-sources\",\n        help=(show_sources_help),\n    ),\n    show_secrets: Optional[bool] = typer.Option(\n        False,\n        \"--show-secrets/--hide-secrets\",\n        help=\"Toggle display of secrets setting values.\",\n    ),\n):\n    \"\"\"\n    Display the current settings.\n    \"\"\"\n    context = prefect.context.get_settings_context()\n\n    # Get settings at each level, converted to a flat dictionary for easy comparison\n    default_settings = prefect.settings.get_default_settings()\n    env_settings = prefect.settings.get_settings_from_env()\n    current_profile_settings = context.settings\n\n    # Obfuscate secrets\n    if not show_secrets:\n        default_settings = default_settings.with_obfuscated_secrets()\n        env_settings = env_settings.with_obfuscated_secrets()\n        current_profile_settings = current_profile_settings.with_obfuscated_secrets()\n\n    # Display the profile first\n    app.console.print(f\"PREFECT_PROFILE={context.profile.name!r}\")\n\n    settings_output = []\n\n    # The combination of environment variables and profile settings that are in use\n    profile_overrides = current_profile_settings.dict(exclude_unset=True)\n\n    # Used to see which settings in current_profile_settings came from env vars\n    env_overrides = env_settings.dict(exclude_unset=True)\n\n    for key, value in profile_overrides.items():\n        source = \"env\" if env_overrides.get(key) is not None else \"profile\"\n        source_blurb = f\" (from {source})\" if show_sources else \"\"\n        settings_output.append(f\"{key}='{value}'{source_blurb}\")\n\n    if show_defaults:\n        for key, value in default_settings.dict().items():\n            if key not in profile_overrides:\n                source_blurb = \" (from defaults)\" if show_sources else \"\"\n                settings_output.append(f\"{key}='{value}'{source_blurb}\")\n\n    app.console.print(\"\\n\".join(sorted(settings_output)))\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/deploy/","title":"deploy","text":"","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy","title":"<code>prefect.cli.deploy</code>","text":"<p>Module containing implementation for deploying flows.</p>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploy a flow from this project by creating a deployment.</p> <p>Should be run from a project root directory.</p> Source code in <code>prefect/cli/deploy.py</code> <pre><code>@app.command()\nasync def deploy(\n    entrypoint: str = typer.Argument(\n        None,\n        help=(\n            \"The path to a flow entrypoint within a project, in the form of\"\n            \" `./path/to/file.py:flow_func_name`\"\n        ),\n    ),\n    names: List[str] = typer.Option(\n        None,\n        \"--name\",\n        \"-n\",\n        help=(\n            \"The name to give the deployment. Can be a pattern. Examples:\"\n            \" 'my-deployment', 'my-flow/my-deployment', 'my-deployment-*',\"\n            \" '*-flow-name/deployment*'\"\n        ),\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the deployment. If not provided, the description\"\n            \" will be populated from the flow's description.\"\n        ),\n    ),\n    version: str = typer.Option(\n        None, \"--version\", help=\"A version to give the deployment.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"One or more optional tags to apply to the deployment. Note: tags are used\"\n            \" only for organizational purposes. For delegating work to agents, use the\"\n            \" --work-queue flag.\"\n        ),\n    ),\n    work_pool_name: str = SettingsOption(\n        PREFECT_DEFAULT_WORK_POOL_NAME,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool that will handle this deployment's runs.\",\n    ),\n    work_queue_name: str = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"The work queue that will handle this deployment's runs. \"\n            \"It will be created if it doesn't already exist. Defaults to `None`.\"\n        ),\n    ),\n    variables: List[str] = typer.Option(\n        None,\n        \"-v\",\n        \"--variable\",\n        help=(\"DEPRECATED: Please use --jv/--job-variable for similar functionality \"),\n    ),\n    job_variables: List[str] = typer.Option(\n        None,\n        \"-jv\",\n        \"--job-variable\",\n        help=(\n            \"One or more job variable overrides for the work pool provided in the\"\n            \" format of key=value string or a JSON object\"\n        ),\n    ),\n    cron: List[str] = typer.Option(\n        None,\n        \"--cron\",\n        help=\"A cron string that will be used to set a CronSchedule on the deployment.\",\n    ),\n    interval: List[int] = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) that will be used to set an\"\n            \" IntervalSchedule on the deployment.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The anchor date for all interval schedules\"\n    ),\n    rrule: List[str] = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set an RRuleSchedule on the deployment.\",\n    ),\n    timezone: str = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    trigger: List[str] = typer.Option(\n        None,\n        \"--trigger\",\n        help=(\n            \"Specifies a trigger for the deployment. The value can be a\"\n            \" json string or path to `.yaml`/`.json` file. This flag can be used\"\n            \" multiple times.\"\n        ),\n    ),\n    param: List[str] = typer.Option(\n        None,\n        \"--param\",\n        help=(\n            \"An optional parameter override, values are parsed as JSON strings e.g.\"\n            \" --param question=ultimate --param answer=42\"\n        ),\n    ),\n    params: str = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"An optional parameter override in a JSON string format e.g.\"\n            ' --params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\''\n        ),\n    ),\n    enforce_parameter_schema: bool = typer.Option(\n        False,\n        \"--enforce-parameter-schema\",\n        help=(\n            \"Whether to enforce the parameter schema on this deployment. If set to\"\n            \" True, any parameters passed to this deployment must match the signature\"\n            \" of the flow.\"\n        ),\n    ),\n    deploy_all: bool = typer.Option(\n        False,\n        \"--all\",\n        help=(\n            \"Deploy all flows in the project. If a flow name or entrypoint is also\"\n            \" provided, this flag will be ignored.\"\n        ),\n    ),\n    prefect_file: Path = typer.Option(\n        Path(\"prefect.yaml\"),\n        \"--prefect-file\",\n        help=\"Specify a custom path to a prefect.yaml file\",\n    ),\n):\n    \"\"\"\n    Deploy a flow from this project by creating a deployment.\n\n    Should be run from a project root directory.\n    \"\"\"\n\n    if variables is not None:\n        app.console.print(\n            generate_deprecation_message(\n                name=\"The `--variable` flag\",\n                start_date=\"Mar 2024\",\n                help=(\n                    \"Please use the `--job-variable foo=bar` argument instead: `prefect\"\n                    \" deploy --job-variable`.\"\n                ),\n            ),\n            style=\"yellow\",\n        )\n\n    if variables is None:\n        variables = list()\n    if job_variables is None:\n        job_variables = list()\n    job_variables.extend(variables)\n\n    options = {\n        \"entrypoint\": entrypoint,\n        \"description\": description,\n        \"version\": version,\n        \"tags\": tags,\n        \"work_pool_name\": work_pool_name,\n        \"work_queue_name\": work_queue_name,\n        \"variables\": job_variables,\n        \"cron\": cron,\n        \"interval\": interval,\n        \"anchor_date\": interval_anchor,\n        \"rrule\": rrule,\n        \"timezone\": timezone,\n        \"triggers\": trigger,\n        \"param\": param,\n        \"params\": params,\n        \"enforce_parameter_schema\": enforce_parameter_schema,\n    }\n    try:\n        deploy_configs, actions = _load_deploy_configs_and_actions(\n            prefect_file=prefect_file,\n        )\n        parsed_names = []\n        for name in names or []:\n            if \"*\" in name:\n                parsed_names.extend(_parse_name_from_pattern(deploy_configs, name))\n            else:\n                parsed_names.append(name)\n        deploy_configs = _pick_deploy_configs(\n            deploy_configs,\n            parsed_names,\n            deploy_all,\n        )\n\n        if len(deploy_configs) &gt; 1:\n            if any(options.values()):\n                app.console.print(\n                    (\n                        \"You have passed options to the deploy command, but you are\"\n                        \" creating or updating multiple deployments. These options\"\n                        \" will be ignored.\"\n                    ),\n                    style=\"yellow\",\n                )\n            await _run_multi_deploy(\n                deploy_configs=deploy_configs,\n                actions=actions,\n                deploy_all=deploy_all,\n                prefect_file=prefect_file,\n            )\n        else:\n            # Accommodate passing in -n flow-name/deployment-name as well as -n deployment-name\n            options[\"names\"] = [\n                name.split(\"/\", 1)[-1] if \"/\" in name else name for name in parsed_names\n            ]\n\n            await _run_single_deploy(\n                deploy_config=deploy_configs[0] if deploy_configs else {},\n                actions=actions,\n                options=options,\n                prefect_file=prefect_file,\n            )\n    except ValueError as exc:\n        exit_with_error(str(exc))\n</code></pre>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy.init","title":"<code>init</code>  <code>async</code>","text":"<p>Initialize a new deployment configuration recipe.</p> Source code in <code>prefect/cli/deploy.py</code> <pre><code>@app.command()\nasync def init(\n    name: str = None,\n    recipe: str = None,\n    fields: List[str] = typer.Option(\n        None,\n        \"-f\",\n        \"--field\",\n        help=(\n            \"One or more fields to pass to the recipe (e.g., image_name) in the format\"\n            \" of key=value.\"\n        ),\n    ),\n):\n    \"\"\"\n    Initialize a new deployment configuration recipe.\n    \"\"\"\n    inputs = {}\n    fields = fields or []\n    recipe_paths = prefect.__module_path__ / \"deployments\" / \"recipes\"\n\n    for field in fields:\n        key, value = field.split(\"=\")\n        inputs[key] = value\n\n    if not recipe and is_interactive():\n        recipe_paths = prefect.__module_path__ / \"deployments\" / \"recipes\"\n        recipes = []\n\n        for r in recipe_paths.iterdir():\n            if r.is_dir() and (r / \"prefect.yaml\").exists():\n                with open(r / \"prefect.yaml\") as f:\n                    recipe_data = yaml.safe_load(f)\n                    recipe_name = r.name\n                    recipe_description = recipe_data.get(\n                        \"description\", \"(no description available)\"\n                    )\n                    recipe_dict = {\n                        \"name\": recipe_name,\n                        \"description\": recipe_description,\n                    }\n                    recipes.append(recipe_dict)\n\n        selected_recipe = prompt_select_from_table(\n            app.console,\n            \"Would you like to initialize your deployment configuration with a recipe?\",\n            columns=[\n                {\"header\": \"Name\", \"key\": \"name\"},\n                {\"header\": \"Description\", \"key\": \"description\"},\n            ],\n            data=recipes,\n            opt_out_message=\"No, I'll use the default deployment configuration.\",\n            opt_out_response={},\n        )\n        if selected_recipe != {}:\n            recipe = selected_recipe[\"name\"]\n\n    if recipe and (recipe_paths / recipe / \"prefect.yaml\").exists():\n        with open(recipe_paths / recipe / \"prefect.yaml\") as f:\n            recipe_inputs = yaml.safe_load(f).get(\"required_inputs\") or {}\n\n        if recipe_inputs:\n            if set(recipe_inputs.keys()) &lt; set(inputs.keys()):\n                # message to user about extra fields\n                app.console.print(\n                    (\n                        f\"Warning: extra fields provided for {recipe!r} recipe:\"\n                        f\" '{', '.join(set(inputs.keys()) - set(recipe_inputs.keys()))}'\"\n                    ),\n                    style=\"red\",\n                )\n            elif set(recipe_inputs.keys()) &gt; set(inputs.keys()):\n                table = Table(\n                    title=f\"[red]Required inputs for {recipe!r} recipe[/red]\",\n                )\n                table.add_column(\"Field Name\", style=\"green\", no_wrap=True)\n                table.add_column(\n                    \"Description\", justify=\"left\", style=\"white\", no_wrap=False\n                )\n                for field, description in recipe_inputs.items():\n                    if field not in inputs:\n                        table.add_row(field, description)\n\n                app.console.print(table)\n\n                for key, description in recipe_inputs.items():\n                    if key not in inputs:\n                        inputs[key] = typer.prompt(key)\n\n            app.console.print(\"-\" * 15)\n\n    try:\n        files = [\n            f\"[green]{fname}[/green]\"\n            for fname in initialize_project(name=name, recipe=recipe, inputs=inputs)\n        ]\n    except ValueError as exc:\n        if \"Unknown recipe\" in str(exc):\n            exit_with_error(\n                f\"Unknown recipe {recipe!r} provided - run [yellow]`prefect init\"\n                \"`[/yellow] to see all available recipes.\"\n            )\n        else:\n            raise\n\n    files = \"\\n\".join(files)\n    empty_msg = (\n        f\"Created project in [green]{Path('.').resolve()}[/green]; no new files\"\n        \" created.\"\n    )\n    file_msg = (\n        f\"Created project in [green]{Path('.').resolve()}[/green] with the following\"\n        f\" new files:\\n{files}\"\n    )\n    app.console.print(file_msg if files else empty_msg)\n</code></pre>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deployment/","title":"deployment","text":"","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment","title":"<code>prefect.cli.deployment</code>","text":"<p>Command line interface for working with deployments.</p>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Create or update a deployment from a YAML file.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command(\n    deprecated=True,\n    deprecated_start_date=\"Mar 2024\",\n    deprecated_name=\"deployment apply\",\n    deprecated_help=\"Use 'prefect deploy' to deploy flows via YAML instead.\",\n)\nasync def apply(\n    paths: List[str] = typer.Argument(\n        ...,\n        help=\"One or more paths to deployment YAML files.\",\n    ),\n    upload: bool = typer.Option(\n        False,\n        \"--upload\",\n        help=(\n            \"A flag that, when provided, uploads this deployment's files to remote\"\n            \" storage.\"\n        ),\n    ),\n    work_queue_concurrency: int = typer.Option(\n        None,\n        \"--limit\",\n        \"-l\",\n        help=(\n            \"Sets the concurrency limit on the work queue that handles this\"\n            \" deployment's runs\"\n        ),\n    ),\n):\n    \"\"\"\n    Create or update a deployment from a YAML file.\n    \"\"\"\n    deployment = None\n    async with get_client() as client:\n        for path in paths:\n            try:\n                deployment = await Deployment.load_from_yaml(path)\n                app.console.print(\n                    f\"Successfully loaded {deployment.name!r}\", style=\"green\"\n                )\n            except Exception as exc:\n                exit_with_error(\n                    f\"'{path!s}' did not conform to deployment spec: {exc!r}\"\n                )\n\n            assert deployment\n\n            await create_work_queue_and_set_concurrency_limit(\n                deployment.work_queue_name,\n                deployment.work_pool_name,\n                work_queue_concurrency,\n            )\n\n            if upload:\n                if (\n                    deployment.storage\n                    and \"put-directory\" in deployment.storage.get_block_capabilities()\n                ):\n                    file_count = await deployment.upload_to_storage()\n                    if file_count:\n                        app.console.print(\n                            (\n                                f\"Successfully uploaded {file_count} files to\"\n                                f\" {deployment.location}\"\n                            ),\n                            style=\"green\",\n                        )\n                else:\n                    app.console.print(\n                        (\n                            f\"Deployment storage {deployment.storage} does not have\"\n                            \" upload capabilities; no files uploaded.\"\n                        ),\n                        style=\"red\",\n                    )\n            await check_work_pool_exists(\n                work_pool_name=deployment.work_pool_name, client=client\n            )\n\n            if client.server_type != ServerType.CLOUD and deployment.triggers:\n                app.console.print(\n                    (\n                        \"Deployment triggers are only supported on \"\n                        f\"Prefect Cloud. Triggers defined in {path!r} will be \"\n                        \"ignored.\"\n                    ),\n                    style=\"red\",\n                )\n\n            deployment_id = await deployment.apply()\n            app.console.print(\n                (\n                    f\"Deployment '{deployment.flow_name}/{deployment.name}'\"\n                    f\" successfully created with id '{deployment_id}'.\"\n                ),\n                style=\"green\",\n            )\n\n            if PREFECT_UI_URL:\n                app.console.print(\n                    \"View Deployment in UI:\"\n                    f\" {PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}\"\n                )\n\n            if deployment.work_pool_name is not None:\n                await _print_deployment_work_pool_instructions(\n                    work_pool_name=deployment.work_pool_name, client=client\n                )\n            elif deployment.work_queue_name is not None:\n                app.console.print(\n                    \"\\nTo execute flow runs from this deployment, start an agent that\"\n                    f\" pulls work from the {deployment.work_queue_name!r} work queue:\"\n                )\n                app.console.print(\n                    f\"$ prefect agent start -q {deployment.work_queue_name!r}\",\n                    style=\"blue\",\n                )\n            else:\n                app.console.print(\n                    (\n                        \"\\nThis deployment does not specify a work queue name, which\"\n                        \" means agents will not be able to pick up its runs. To add a\"\n                        \" work queue, edit the deployment spec and re-run this command,\"\n                        \" or visit the deployment in the UI.\"\n                    ),\n                    style=\"red\",\n                )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.build","title":"<code>build</code>  <code>async</code>","text":"<p>Generate a deployment YAML from /path/to/file.py:flow_function</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command(\n    deprecated=True,\n    deprecated_start_date=\"Mar 2024\",\n    deprecated_name=\"deployment build\",\n    deprecated_help=\"Use 'prefect deploy' to deploy flows via YAML instead.\",\n)\nasync def build(\n    entrypoint: str = typer.Argument(\n        ...,\n        help=(\n            \"The path to a flow entrypoint, in the form of\"\n            \" `./path/to/file.py:flow_func_name`\"\n        ),\n    ),\n    name: str = typer.Option(\n        None, \"--name\", \"-n\", help=\"The name to give the deployment.\"\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the deployment. If not provided, the description\"\n            \" will be populated from the flow's description.\"\n        ),\n    ),\n    version: str = typer.Option(\n        None, \"--version\", \"-v\", help=\"A version to give the deployment.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"One or more optional tags to apply to the deployment. Note: tags are used\"\n            \" only for organizational purposes. For delegating work to agents, use the\"\n            \" --work-queue flag.\"\n        ),\n    ),\n    work_queue_name: str = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"The work queue that will handle this deployment's runs. \"\n            \"It will be created if it doesn't already exist. Defaults to `None`. \"\n            \"Note that if a work queue is not set, work will not be scheduled.\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool that will handle this deployment's runs.\",\n    ),\n    work_queue_concurrency: int = typer.Option(\n        None,\n        \"--limit\",\n        \"-l\",\n        help=(\n            \"Sets the concurrency limit on the work queue that handles this\"\n            \" deployment's runs\"\n        ),\n    ),\n    infra_type: str = typer.Option(\n        None,\n        \"--infra\",\n        \"-i\",\n        help=\"The infrastructure type to use, prepopulated with defaults. For example: \"\n        + listrepr(builtin_infrastructure_types, sep=\", \"),\n    ),\n    infra_block: str = typer.Option(\n        None,\n        \"--infra-block\",\n        \"-ib\",\n        help=\"The slug of the infrastructure block to use as a template.\",\n    ),\n    overrides: List[str] = typer.Option(\n        None,\n        \"--override\",\n        help=(\n            \"One or more optional infrastructure overrides provided as a dot delimited\"\n            \" path, e.g., `env.env_key=env_value`\"\n        ),\n    ),\n    storage_block: str = typer.Option(\n        None,\n        \"--storage-block\",\n        \"-sb\",\n        help=(\n            \"The slug of a remote storage block. Use the syntax:\"\n            \" 'block_type/block_name', where block_type is one of 'github', 's3',\"\n            \" 'gcs', 'azure', 'smb', or a registered block from a library that\"\n            \" implements the WritableDeploymentStorage interface such as\"\n            \" 'gitlab-repository', 'bitbucket-repository', 's3-bucket',\"\n            \" 'gcs-bucket'\"\n        ),\n    ),\n    skip_upload: bool = typer.Option(\n        False,\n        \"--skip-upload\",\n        help=(\n            \"A flag that, when provided, skips uploading this deployment's files to\"\n            \" remote storage.\"\n        ),\n    ),\n    cron: str = typer.Option(\n        None,\n        \"--cron\",\n        help=\"A cron string that will be used to set a CronSchedule on the deployment.\",\n    ),\n    interval: int = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) that will be used to set an\"\n            \" IntervalSchedule on the deployment.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The anchor date for an interval schedule\"\n    ),\n    rrule: str = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set an RRuleSchedule on the deployment.\",\n    ),\n    timezone: str = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    path: str = typer.Option(\n        None,\n        \"--path\",\n        help=(\n            \"An optional path to specify a subdirectory of remote storage to upload to,\"\n            \" or to point to a subdirectory of a locally stored flow.\"\n        ),\n    ),\n    output: str = typer.Option(\n        None,\n        \"--output\",\n        \"-o\",\n        help=\"An optional filename to write the deployment file to.\",\n    ),\n    _apply: bool = typer.Option(\n        False,\n        \"--apply\",\n        \"-a\",\n        help=(\n            \"An optional flag to automatically register the resulting deployment with\"\n            \" the API.\"\n        ),\n    ),\n    param: List[str] = typer.Option(\n        None,\n        \"--param\",\n        help=(\n            \"An optional parameter override, values are parsed as JSON strings e.g.\"\n            \" --param question=ultimate --param answer=42\"\n        ),\n    ),\n    params: str = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"An optional parameter override in a JSON string format e.g.\"\n            ' --params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\''\n        ),\n    ),\n    no_schedule: bool = typer.Option(\n        False,\n        \"--no-schedule\",\n        help=\"An optional flag to disable scheduling for this deployment.\",\n    ),\n):\n    \"\"\"\n    Generate a deployment YAML from /path/to/file.py:flow_function\n    \"\"\"\n    # validate inputs\n    if not name:\n        exit_with_error(\n            \"A name for this deployment must be provided with the '--name' flag.\"\n        )\n\n    if (\n        len([value for value in (cron, rrule, interval) if value is not None])\n        + (1 if no_schedule else 0)\n        &gt; 1\n    ):\n        exit_with_error(\"Only one schedule type can be provided.\")\n\n    if infra_block and infra_type:\n        exit_with_error(\n            \"Only one of `infra` or `infra_block` can be provided, please choose one.\"\n        )\n\n    output_file = None\n    if output:\n        output_file = Path(output)\n        if output_file.suffix and output_file.suffix != \".yaml\":\n            exit_with_error(\"Output file must be a '.yaml' file.\")\n        else:\n            output_file = output_file.with_suffix(\".yaml\")\n\n    # validate flow\n    try:\n        fpath, obj_name = entrypoint.rsplit(\":\", 1)\n    except ValueError as exc:\n        if str(exc) == \"not enough values to unpack (expected 2, got 1)\":\n            missing_flow_name_msg = (\n                \"Your flow entrypoint must include the name of the function that is\"\n                f\" the entrypoint to your flow.\\nTry {entrypoint}:&lt;flow_name&gt;\"\n            )\n            exit_with_error(missing_flow_name_msg)\n        else:\n            raise exc\n    try:\n        flow = await run_sync_in_worker_thread(load_flow_from_entrypoint, entrypoint)\n    except Exception as exc:\n        exit_with_error(exc)\n    app.console.print(f\"Found flow {flow.name!r}\", style=\"green\")\n    job_variables = {}\n    for override in overrides or []:\n        key, value = override.split(\"=\", 1)\n        job_variables[key] = value\n\n    if infra_block:\n        infrastructure = await Block.load(infra_block)\n    elif infra_type:\n        # Create an instance of the given type\n        infrastructure = Block.get_block_class_from_key(infra_type)()\n    else:\n        # will reset to a default of Process is no infra is present on the\n        # server-side definition of this deployment\n        infrastructure = None\n\n    if interval_anchor and not interval:\n        exit_with_error(\"An anchor date can only be provided with an interval schedule\")\n\n    schedule = None\n    if cron:\n        cron_kwargs = {\"cron\": cron, \"timezone\": timezone}\n        schedule = CronSchedule(\n            **{k: v for k, v in cron_kwargs.items() if v is not None}\n        )\n    elif interval:\n        interval_kwargs = {\n            \"interval\": timedelta(seconds=interval),\n            \"anchor_date\": interval_anchor,\n            \"timezone\": timezone,\n        }\n        schedule = IntervalSchedule(\n            **{k: v for k, v in interval_kwargs.items() if v is not None}\n        )\n    elif rrule:\n        try:\n            schedule = RRuleSchedule(**json.loads(rrule))\n            if timezone:\n                # override timezone if specified via CLI argument\n                schedule.timezone = timezone\n        except json.JSONDecodeError:\n            schedule = RRuleSchedule(rrule=rrule, timezone=timezone)\n\n    # parse storage_block\n    if storage_block:\n        block_type, block_name, *block_path = storage_block.split(\"/\")\n        if block_path and path:\n            exit_with_error(\n                \"Must provide a `path` explicitly or provide one on the storage block\"\n                \" specification, but not both.\"\n            )\n        elif not path:\n            path = \"/\".join(block_path)\n        storage_block = f\"{block_type}/{block_name}\"\n        storage = await Block.load(storage_block)\n    else:\n        storage = None\n\n    if create_default_ignore_file(path=\".\"):\n        app.console.print(\n            (\n                \"Default '.prefectignore' file written to\"\n                f\" {(Path('.') / '.prefectignore').absolute()}\"\n            ),\n            style=\"green\",\n        )\n\n    if param and (params is not None):\n        exit_with_error(\"Can only pass one of `param` or `params` options\")\n\n    parameters = dict()\n\n    if param:\n        for p in param or []:\n            k, unparsed_value = p.split(\"=\", 1)\n            try:\n                v = json.loads(unparsed_value)\n                app.console.print(\n                    f\"The parameter value {unparsed_value} is parsed as a JSON string\"\n                )\n            except json.JSONDecodeError:\n                v = unparsed_value\n            parameters[k] = v\n\n    if params is not None:\n        parameters = json.loads(params)\n\n    # set up deployment object\n    entrypoint = (\n        f\"{Path(fpath).absolute().relative_to(Path('.').absolute())}:{obj_name}\"\n    )\n\n    init_kwargs = dict(\n        path=path,\n        entrypoint=entrypoint,\n        version=version,\n        storage=storage,\n        job_variables=job_variables or {},\n    )\n\n    if parameters:\n        init_kwargs[\"parameters\"] = parameters\n\n    if description:\n        init_kwargs[\"description\"] = description\n\n    # if a schedule, tags, work_queue_name, or infrastructure are not provided via CLI,\n    # we let `build_from_flow` load them from the server\n    if schedule or no_schedule:\n        init_kwargs.update(schedule=schedule)\n    if tags:\n        init_kwargs.update(tags=tags)\n    if infrastructure:\n        init_kwargs.update(infrastructure=infrastructure)\n    if work_queue_name:\n        init_kwargs.update(work_queue_name=work_queue_name)\n    if work_pool_name:\n        init_kwargs.update(work_pool_name=work_pool_name)\n\n    deployment_loc = output_file or f\"{obj_name}-deployment.yaml\"\n    deployment = await Deployment.build_from_flow(\n        flow=flow,\n        name=name,\n        output=deployment_loc,\n        skip_upload=skip_upload,\n        apply=False,\n        **init_kwargs,\n    )\n    app.console.print(\n        f\"Deployment YAML created at '{Path(deployment_loc).absolute()!s}'.\",\n        style=\"green\",\n    )\n\n    await create_work_queue_and_set_concurrency_limit(\n        deployment.work_queue_name, deployment.work_pool_name, work_queue_concurrency\n    )\n\n    # we process these separately for informative output\n    if not skip_upload:\n        if (\n            deployment.storage\n            and \"put-directory\" in deployment.storage.get_block_capabilities()\n        ):\n            file_count = await deployment.upload_to_storage()\n            if file_count:\n                app.console.print(\n                    (\n                        f\"Successfully uploaded {file_count} files to\"\n                        f\" {deployment.location}\"\n                    ),\n                    style=\"green\",\n                )\n        else:\n            app.console.print(\n                (\n                    f\"Deployment storage {deployment.storage} does not have upload\"\n                    \" capabilities; no files uploaded.  Pass --skip-upload to suppress\"\n                    \" this warning.\"\n                ),\n                style=\"green\",\n            )\n\n    if _apply:\n        async with get_client() as client:\n            await check_work_pool_exists(\n                work_pool_name=deployment.work_pool_name, client=client\n            )\n            deployment_id = await deployment.apply()\n            app.console.print(\n                (\n                    f\"Deployment '{deployment.flow_name}/{deployment.name}'\"\n                    f\" successfully created with id '{deployment_id}'.\"\n                ),\n                style=\"green\",\n            )\n            if deployment.work_pool_name is not None:\n                await _print_deployment_work_pool_instructions(\n                    work_pool_name=deployment.work_pool_name, client=client\n                )\n\n            elif deployment.work_queue_name is not None:\n                app.console.print(\n                    \"\\nTo execute flow runs from this deployment, start an agent that\"\n                    f\" pulls work from the {deployment.work_queue_name!r} work queue:\"\n                )\n                app.console.print(\n                    f\"$ prefect agent start -q {deployment.work_queue_name!r}\",\n                    style=\"blue\",\n                )\n            else:\n                app.console.print(\n                    (\n                        \"\\nThis deployment does not specify a work queue name, which\"\n                        \" means agents will not be able to pick up its runs. To add a\"\n                        \" work queue, edit the deployment spec and re-run this command,\"\n                        \" or visit the deployment in the UI.\"\n                    ),\n                    style=\"red\",\n                )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.clear_schedules","title":"<code>clear_schedules</code>  <code>async</code>","text":"<p>Clear all schedules for a deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"clear\")\nasync def clear_schedules(\n    deployment_name: str,\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Clear all schedules for a deployment.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        await client.read_flow(deployment.flow_id)\n\n        # Get input from user: confirm removal of all schedules\n        if not assume_yes and not typer.confirm(\n            \"Are you sure you want to clear all schedules for this deployment?\",\n        ):\n            exit_with_error(\"Clearing schedules cancelled.\")\n\n        for schedule in deployment.schedules:\n            try:\n                await client.delete_deployment_schedule(deployment.id, schedule.id)\n            except ObjectNotFound:\n                pass\n\n        exit_with_success(f\"Cleared all schedules for deployment {deployment_name}\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.create_schedule","title":"<code>create_schedule</code>  <code>async</code>","text":"<p>Create a schedule for a given deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"create\")\nasync def create_schedule(\n    name: str,\n    interval: Optional[float] = typer.Option(\n        None,\n        \"--interval\",\n        help=\"An interval to schedule on, specified in seconds\",\n        min=0.0001,\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None,\n        \"--anchor-date\",\n        help=\"The anchor date for an interval schedule\",\n    ),\n    rrule_string: Optional[str] = typer.Option(\n        None, \"--rrule\", help=\"Deployment schedule rrule string\"\n    ),\n    cron_string: Optional[str] = typer.Option(\n        None, \"--cron\", help=\"Deployment schedule cron string\"\n    ),\n    cron_day_or: Optional[str] = typer.Option(\n        None,\n        \"--day_or\",\n        help=\"Control how croniter handles `day` and `day_of_week` entries\",\n    ),\n    timezone: Optional[str] = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    active: Optional[bool] = typer.Option(\n        True,\n        \"--active\",\n        help=\"Whether the schedule is active. Defaults to True.\",\n    ),\n    replace: Optional[bool] = typer.Option(\n        False,\n        \"--replace\",\n        help=\"Replace the deployment's current schedule(s) with this new schedule.\",\n    ),\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Create a schedule for a given deployment.\n    \"\"\"\n    assert_deployment_name_format(name)\n\n    if sum(option is not None for option in [interval, rrule_string, cron_string]) != 1:\n        exit_with_error(\n            \"Exactly one of `--interval`, `--rrule`, or `--cron` must be provided.\"\n        )\n\n    schedule = None\n\n    if interval_anchor and not interval:\n        exit_with_error(\"An anchor date can only be provided with an interval schedule\")\n\n    if interval is not None:\n        if interval_anchor:\n            try:\n                pendulum.parse(interval_anchor)\n            except ValueError:\n                return exit_with_error(\"The anchor date must be a valid date string.\")\n        interval_schedule = {\n            \"interval\": interval,\n            \"anchor_date\": interval_anchor,\n            \"timezone\": timezone,\n        }\n        schedule = IntervalSchedule(\n            **{k: v for k, v in interval_schedule.items() if v is not None}\n        )\n\n    if cron_string is not None:\n        cron_schedule = {\n            \"cron\": cron_string,\n            \"day_or\": cron_day_or,\n            \"timezone\": timezone,\n        }\n        schedule = CronSchedule(\n            **{k: v for k, v in cron_schedule.items() if v is not None}\n        )\n\n    if rrule_string is not None:\n        # a timezone in the `rrule_string` gets ignored by the RRuleSchedule constructor\n        if \"TZID\" in rrule_string and not timezone:\n            exit_with_error(\n                \"You can provide a timezone by providing a dict with a `timezone` key\"\n                \" to the --rrule option. E.g. {'rrule': 'FREQ=MINUTELY;INTERVAL=5',\"\n                \" 'timezone': 'America/New_York'}.\\nAlternatively, you can provide a\"\n                \" timezone by passing in a --timezone argument.\"\n            )\n        try:\n            schedule = RRuleSchedule(**json.loads(rrule_string))\n            if timezone:\n                # override timezone if specified via CLI argument\n                schedule.timezone = timezone\n        except json.JSONDecodeError:\n            schedule = RRuleSchedule(rrule=rrule_string, timezone=timezone)\n\n    if schedule is None:\n        return exit_with_success(\n            \"Could not create a valid schedule from the provided options.\"\n        )\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {name!r} not found!\")\n\n        num_schedules = len(deployment.schedules)\n        noun = \"schedule\" if num_schedules == 1 else \"schedules\"\n\n        if replace and num_schedules &gt; 0:\n            if not assume_yes and not typer.confirm(\n                f\"Are you sure you want to replace {num_schedules} {noun} for {name}?\"\n            ):\n                return exit_with_error(\"Schedule replacement cancelled.\")\n\n            for existing_schedule in deployment.schedules:\n                try:\n                    await client.delete_deployment_schedule(\n                        deployment.id, existing_schedule.id\n                    )\n                except ObjectNotFound:\n                    pass\n\n        await client.create_deployment_schedules(deployment.id, [(schedule, active)])\n\n        if replace and num_schedules &gt; 0:\n            exit_with_success(f\"Replaced existing deployment {noun} with new schedule!\")\n        else:\n            exit_with_success(\"Created deployment schedule!\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a deployment.</p> <p>\b Examples:     \b     $ prefect deployment delete test_flow/test_deployment     $ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def delete(\n    name: Optional[str] = typer.Argument(\n        None, help=\"A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\"\n    ),\n    deployment_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"A deployment id to search for if no name is given\"\n    ),\n):\n    \"\"\"\n    Delete a deployment.\n\n    \\b\n    Examples:\n        \\b\n        $ prefect deployment delete test_flow/test_deployment\n        $ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6\n    \"\"\"\n    async with get_client() as client:\n        if name is None and deployment_id is not None:\n            try:\n                await client.delete_deployment(deployment_id)\n                exit_with_success(f\"Deleted deployment '{deployment_id}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {deployment_id!r} not found!\")\n        elif name is not None:\n            try:\n                deployment = await client.read_deployment_by_name(name)\n                await client.delete_deployment(deployment.id)\n                exit_with_success(f\"Deleted deployment '{name}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {name!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a deployment name or id\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.delete_schedule","title":"<code>delete_schedule</code>  <code>async</code>","text":"<p>Delete a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"delete\")\nasync def delete_schedule(\n    deployment_name: str,\n    schedule_id: UUID,\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Delete a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if not assume_yes and not typer.confirm(\n            f\"Are you sure you want to delete this schedule: {schedule.schedule}\",\n        ):\n            return exit_with_error(\"Deletion cancelled.\")\n\n        try:\n            await client.delete_deployment_schedule(deployment.id, schedule_id)\n        except ObjectNotFound:\n            exit_with_error(\"Deployment schedule not found!\")\n\n        exit_with_success(f\"Deleted deployment schedule {schedule_id}\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a deployment.</p> <p>\b Example:     \b     $ prefect deployment inspect \"hello-world/my-deployment\"     {         'id': '610df9c3-0fb4-4856-b330-67f588d20201',         'created': '2022-08-01T18:36:25.192102+00:00',         'updated': '2022-08-01T18:36:25.188166+00:00',         'name': 'my-deployment',         'description': None,         'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',         'schedules': None,         'parameters': {'name': 'Marvin'},         'tags': ['test'],         'parameter_openapi_schema': {             'title': 'Parameters',             'type': 'object',             'properties': {                 'name': {                     'title': 'name',                     'type': 'string'                 }             },             'required': ['name']         },         'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',         'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',         'infrastructure': {             'type': 'process',             'env': {},             'labels': {},             'name': None,             'command': ['python', '-m', 'prefect.engine'],             'stream_output': True         }     }</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def inspect(name: str):\n    \"\"\"\n    View details about a deployment.\n\n    \\b\n    Example:\n        \\b\n        $ prefect deployment inspect \"hello-world/my-deployment\"\n        {\n            'id': '610df9c3-0fb4-4856-b330-67f588d20201',\n            'created': '2022-08-01T18:36:25.192102+00:00',\n            'updated': '2022-08-01T18:36:25.188166+00:00',\n            'name': 'my-deployment',\n            'description': None,\n            'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',\n            'schedules': None,\n            'parameters': {'name': 'Marvin'},\n            'tags': ['test'],\n            'parameter_openapi_schema': {\n                'title': 'Parameters',\n                'type': 'object',\n                'properties': {\n                    'name': {\n                        'title': 'name',\n                        'type': 'string'\n                    }\n                },\n                'required': ['name']\n            },\n            'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',\n            'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',\n            'infrastructure': {\n                'type': 'process',\n                'env': {},\n                'labels': {},\n                'name': None,\n                'command': ['python', '-m', 'prefect.engine'],\n                'stream_output': True\n            }\n        }\n\n    \"\"\"\n    assert_deployment_name_format(name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(name)\n        except ObjectNotFound:\n            exit_with_error(f\"Deployment {name!r} not found!\")\n\n        deployment_json = deployment.dict(json_compatible=True)\n\n        if deployment.infrastructure_document_id:\n            deployment_json[\"infrastructure\"] = Block._from_block_document(\n                await client.read_block_document(deployment.infrastructure_document_id)\n            ).dict(\n                exclude={\"_block_document_id\", \"_block_document_name\", \"_is_anonymous\"}\n            )\n\n        if client.server_type.supports_automations():\n            deployment_json[\"automations\"] = [\n                a.dict()\n                for a in await client.read_resource_related_automations(\n                    f\"prefect.deployment.{deployment.id}\"\n                )\n            ]\n\n    app.console.print(Pretty(deployment_json))\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.list_schedules","title":"<code>list_schedules</code>  <code>async</code>","text":"<p>View all schedules for a deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"ls\")\nasync def list_schedules(deployment_name: str):\n    \"\"\"\n    View all schedules for a deployment.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n    def sort_by_created_key(schedule: DeploymentSchedule):  # type: ignore\n        assert schedule.created is not None, \"All schedules should have a created time.\"\n        return pendulum.now(\"utc\") - schedule.created\n\n    def schedule_details(schedule: DeploymentSchedule) -&gt; str:\n        if isinstance(schedule.schedule, IntervalSchedule):\n            return f\"interval: {schedule.schedule.interval}s\"\n        elif isinstance(schedule.schedule, CronSchedule):\n            return f\"cron: {schedule.schedule.cron}\"\n        elif isinstance(schedule.schedule, RRuleSchedule):\n            return f\"rrule: {schedule.schedule.rrule}\"\n        else:\n            return \"unknown\"\n\n    table = Table(\n        title=\"Deployment Schedules\",\n    )\n    table.add_column(\"ID\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Schedule\", style=\"cyan\", no_wrap=False)\n    table.add_column(\"Active\", style=\"purple\", no_wrap=True)\n\n    for schedule in sorted(deployment.schedules, key=sort_by_created_key):\n        table.add_row(\n            str(schedule.id),\n            schedule_details(schedule),\n            str(schedule.active),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all deployments or deployments for specific flows.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def ls(flow_name: Optional[List[str]] = None, by_created: bool = False):\n    \"\"\"\n    View all deployments or deployments for specific flows.\n    \"\"\"\n    async with get_client() as client:\n        deployments = await client.read_deployments(\n            flow_filter=FlowFilter(name={\"any_\": flow_name}) if flow_name else None\n        )\n        flows = {\n            flow.id: flow\n            for flow in await client.read_flows(\n                flow_filter=FlowFilter(id={\"any_\": [d.flow_id for d in deployments]})\n            )\n        }\n\n    def sort_by_name_keys(d):\n        return flows[d.flow_id].name, d.name\n\n    def sort_by_created_key(d):\n        return pendulum.now(\"utc\") - d.created\n\n    table = Table(\n        title=\"Deployments\",\n    )\n    table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(\"ID\", style=\"cyan\", no_wrap=True)\n\n    for deployment in sorted(\n        deployments, key=sort_by_created_key if by_created else sort_by_name_keys\n    ):\n        table.add_row(\n            f\"{flows[deployment.flow_id].name}/[bold]{deployment.name}[/]\",\n            str(deployment.id),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.pause_schedule","title":"<code>pause_schedule</code>  <code>async</code>","text":"<p>Pause a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"pause\")\nasync def pause_schedule(deployment_name: str, schedule_id: UUID):\n    \"\"\"\n    Pause a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if not schedule.active:\n            return exit_with_error(\n                f\"Deployment schedule {schedule_id} is already inactive\"\n            )\n\n        await client.update_deployment_schedule(\n            deployment.id, schedule_id, active=False\n        )\n        exit_with_success(\n            f\"Paused schedule {schedule.schedule} for deployment {deployment_name}\"\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.resume_schedule","title":"<code>resume_schedule</code>  <code>async</code>","text":"<p>Resume a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"resume\")\nasync def resume_schedule(deployment_name: str, schedule_id: UUID):\n    \"\"\"\n    Resume a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if schedule.active:\n            return exit_with_error(\n                f\"Deployment schedule {schedule_id} is already active\"\n            )\n\n        await client.update_deployment_schedule(deployment.id, schedule_id, active=True)\n        exit_with_success(\n            f\"Resumed schedule {schedule.schedule} for deployment {deployment_name}\"\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.run","title":"<code>run</code>  <code>async</code>","text":"<p>Create a flow run for the given flow and deployment.</p> <p>The flow run will be scheduled to run immediately unless <code>--start-in</code> or <code>--start-at</code> is specified. The flow run will not execute until a worker starts. To watch the flow run until it reaches a terminal state, use the <code>--watch</code> flag.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def run(\n    name: Optional[str] = typer.Argument(\n        None, help=\"A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\"\n    ),\n    deployment_id: Optional[str] = typer.Option(\n        None,\n        \"--id\",\n        help=(\"A deployment id to search for if no name is given\"),\n    ),\n    job_variables: List[str] = typer.Option(\n        None,\n        \"-jv\",\n        \"--job-variable\",\n        help=(\n            \"A key, value pair (key=value) specifying a flow run job variable. The value will\"\n            \" be interpreted as JSON. May be passed multiple times to specify multiple\"\n            \" job variable values.\"\n        ),\n    ),\n    params: List[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--param\",\n        help=(\n            \"A key, value pair (key=value) specifying a flow parameter. The value will\"\n            \" be interpreted as JSON. May be passed multiple times to specify multiple\"\n            \" parameter values.\"\n        ),\n    ),\n    multiparams: Optional[str] = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"A mapping of parameters to values. To use a stdin, pass '-'. Any \"\n            \"parameters passed with `--param` will take precedence over these values.\"\n        ),\n    ),\n    start_in: Optional[str] = typer.Option(\n        None,\n        \"--start-in\",\n        help=(\n            \"A human-readable string specifying a time interval to wait before starting\"\n            \" the flow run. E.g. 'in 5 minutes', 'in 1 hour', 'in 2 days'.\"\n        ),\n    ),\n    start_at: Optional[str] = typer.Option(\n        None,\n        \"--start-at\",\n        help=(\n            \"A human-readable string specifying a time to start the flow run. E.g.\"\n            \" 'at 5:30pm', 'at 2022-08-01 17:30', 'at 2022-08-01 17:30:00'.\"\n        ),\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"--tag\",\n        help=(\"Tag(s) to be applied to flow run.\"),\n    ),\n    watch: bool = typer.Option(\n        False,\n        \"--watch\",\n        help=(\"Whether to poll the flow run until a terminal state is reached.\"),\n    ),\n    watch_interval: Optional[int] = typer.Option(\n        None,\n        \"--watch-interval\",\n        help=(\"How often to poll the flow run for state changes (in seconds).\"),\n    ),\n    watch_timeout: Optional[int] = typer.Option(\n        None,\n        \"--watch-timeout\",\n        help=(\"Timeout for --watch.\"),\n    ),\n):\n    \"\"\"\n    Create a flow run for the given flow and deployment.\n\n    The flow run will be scheduled to run immediately unless `--start-in` or `--start-at` is specified.\n    The flow run will not execute until a worker starts.\n    To watch the flow run until it reaches a terminal state, use the `--watch` flag.\n    \"\"\"\n    import dateparser\n\n    now = pendulum.now(\"UTC\")\n\n    multi_params = {}\n    if multiparams:\n        if multiparams == \"-\":\n            multiparams = sys.stdin.read()\n            if not multiparams:\n                exit_with_error(\"No data passed to stdin\")\n\n        try:\n            multi_params = json.loads(multiparams)\n        except ValueError as exc:\n            exit_with_error(f\"Failed to parse JSON: {exc}\")\n        if watch_interval and not watch:\n            exit_with_error(\n                \"`--watch-interval` can only be used with `--watch`.\",\n            )\n    cli_params = _load_json_key_values(params or [], \"parameter\")\n    conflicting_keys = set(cli_params.keys()).intersection(multi_params.keys())\n    if conflicting_keys:\n        app.console.print(\n            \"The following parameters were specified by `--param` and `--params`, the \"\n            f\"`--param` value will be used: {conflicting_keys}\"\n        )\n    parameters = {**multi_params, **cli_params}\n\n    job_vars = _load_json_key_values(job_variables or [], \"job variable\")\n    if start_in and start_at:\n        exit_with_error(\n            \"Only one of `--start-in` or `--start-at` can be set, not both.\"\n        )\n\n    elif start_in is None and start_at is None:\n        scheduled_start_time = now\n        human_dt_diff = \" (now)\"\n    else:\n        if start_in:\n            start_time_raw = \"in \" + start_in\n        else:\n            start_time_raw = \"at \" + start_at\n        with warnings.catch_warnings():\n            # PyTZ throws a warning based on dateparser usage of the library\n            # See https://github.com/scrapinghub/dateparser/issues/1089\n            warnings.filterwarnings(\"ignore\", module=\"dateparser\")\n\n            try:\n                start_time_parsed = dateparser.parse(\n                    start_time_raw,\n                    settings={\n                        \"TO_TIMEZONE\": \"UTC\",\n                        \"RETURN_AS_TIMEZONE_AWARE\": False,\n                        \"PREFER_DATES_FROM\": \"future\",\n                        \"RELATIVE_BASE\": datetime.fromtimestamp(\n                            now.timestamp(), tz=timezone.utc\n                        ),\n                    },\n                )\n\n            except Exception as exc:\n                exit_with_error(f\"Failed to parse '{start_time_raw!r}': {exc!s}\")\n\n        if start_time_parsed is None:\n            exit_with_error(f\"Unable to parse scheduled start time {start_time_raw!r}.\")\n\n        scheduled_start_time = pendulum.instance(start_time_parsed)\n        human_dt_diff = (\n            \" (\" + pendulum.format_diff(scheduled_start_time.diff(now)) + \")\"\n        )\n\n    async with get_client() as client:\n        deployment = await get_deployment(client, name, deployment_id)\n        flow = await client.read_flow(deployment.flow_id)\n\n        deployment_parameters = deployment.parameter_openapi_schema[\"properties\"].keys()\n        unknown_keys = set(parameters.keys()).difference(deployment_parameters)\n        if unknown_keys:\n            available_parameters = (\n                (\n                    \"The following parameters are available on the deployment: \"\n                    + listrepr(deployment_parameters, sep=\", \")\n                )\n                if deployment_parameters\n                else \"This deployment does not accept parameters.\"\n            )\n\n            exit_with_error(\n                \"The following parameters were specified but not found on the \"\n                f\"deployment: {listrepr(unknown_keys, sep=', ')}\"\n                f\"\\n{available_parameters}\"\n            )\n\n        app.console.print(\n            f\"Creating flow run for deployment '{flow.name}/{deployment.name}'...\",\n        )\n\n        try:\n            flow_run = await client.create_flow_run_from_deployment(\n                deployment.id,\n                parameters=parameters,\n                state=Scheduled(scheduled_time=scheduled_start_time),\n                tags=tags,\n                job_variables=job_vars,\n            )\n        except PrefectHTTPStatusError as exc:\n            detail = exc.response.json().get(\"detail\")\n            if detail:\n                exit_with_error(\n                    exc.response.json()[\"detail\"],\n                )\n            else:\n                raise\n\n    if PREFECT_UI_URL:\n        run_url = f\"{PREFECT_UI_URL.value()}/flow-runs/flow-run/{flow_run.id}\"\n    else:\n        run_url = \"&lt;no dashboard available&gt;\"\n\n    datetime_local_tz = scheduled_start_time.in_tz(pendulum.tz.local_timezone())\n    scheduled_display = (\n        datetime_local_tz.to_datetime_string()\n        + \" \"\n        + datetime_local_tz.tzname()\n        + human_dt_diff\n    )\n\n    app.console.print(f\"Created flow run {flow_run.name!r}.\")\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n        \u2514\u2500\u2500 UUID: {flow_run.id}\n        \u2514\u2500\u2500 Parameters: {flow_run.parameters}\n        \u2514\u2500\u2500 Job Variables: {flow_run.job_variables}\n        \u2514\u2500\u2500 Scheduled start time: {scheduled_display}\n        \u2514\u2500\u2500 URL: {run_url}\n        \"\"\"\n        ).strip(),\n        soft_wrap=True,\n    )\n    if watch:\n        watch_interval = 5 if watch_interval is None else watch_interval\n        app.console.print(f\"Watching flow run {flow_run.name!r}...\")\n        finished_flow_run = await wait_for_flow_run(\n            flow_run.id,\n            timeout=watch_timeout,\n            poll_interval=watch_interval,\n            log_states=True,\n        )\n        finished_flow_run_state = finished_flow_run.state\n        if finished_flow_run_state.is_completed():\n            exit_with_success(\n                f\"Flow run finished successfully in {finished_flow_run_state.name!r}.\"\n            )\n        exit_with_error(\n            f\"Flow run finished in state {finished_flow_run_state.name!r}.\",\n            code=1,\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.str_presenter","title":"<code>str_presenter</code>","text":"<p>configures yaml for dumping multiline strings Ref: https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>def str_presenter(dumper, data):\n    \"\"\"\n    configures yaml for dumping multiline strings\n    Ref: https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data\n    \"\"\"\n    if len(data.splitlines()) &gt; 1:  # check for multiline string\n        return dumper.represent_scalar(\"tag:yaml.org,2002:str\", data, style=\"|\")\n    return dumper.represent_scalar(\"tag:yaml.org,2002:str\", data)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/dev/","title":"dev","text":"","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev","title":"<code>prefect.cli.dev</code>","text":"<p>Command line interface for working with Prefect Server</p>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.agent","title":"<code>agent</code>  <code>async</code>","text":"<p>Starts a hot-reloading development agent process.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def agent(\n    api_url: str = SettingsOption(PREFECT_API_URL),\n    work_queues: List[str] = typer.Option(\n        [\"default\"],\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Starts a hot-reloading development agent process.\n    \"\"\"\n    # Delayed import since this is only a 'dev' dependency\n    import watchfiles\n\n    app.console.print(\"Creating hot-reloading agent process...\")\n\n    try:\n        await watchfiles.arun_process(\n            prefect.__module_path__,\n            target=agent_process_entrypoint,\n            kwargs=dict(api=api_url, work_queues=work_queues),\n        )\n    except RuntimeError as err:\n        # a bug in watchfiles causes an 'Already borrowed' error from Rust when\n        # exiting: https://github.com/samuelcolvin/watchfiles/issues/200\n        if str(err).strip() != \"Already borrowed\":\n            raise\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.agent_process_entrypoint","title":"<code>agent_process_entrypoint</code>","text":"<p>An entrypoint for starting an agent in a subprocess. Adds a Rich console to the Typer app, processes Typer default parameters, then starts an agent. All kwargs are forwarded to  <code>prefect.cli.agent.start</code>.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>def agent_process_entrypoint(**kwargs):\n    \"\"\"\n    An entrypoint for starting an agent in a subprocess. Adds a Rich console\n    to the Typer app, processes Typer default parameters, then starts an agent.\n    All kwargs are forwarded to  `prefect.cli.agent.start`.\n    \"\"\"\n    import inspect\n\n    # import locally so only the `dev` command breaks if Typer internals change\n    from typer.models import ParameterInfo\n\n    # Typer does not process default parameters when calling a function\n    # directly, so we must set `start_agent`'s default parameters manually.\n    # get the signature of the `start_agent` function\n    start_agent_signature = inspect.signature(start_agent)\n\n    # for any arguments not present in kwargs, use the default value.\n    for name, param in start_agent_signature.parameters.items():\n        if name not in kwargs:\n            # All `param.default` values for start_agent are Typer params that store the\n            # actual default value in their `default` attribute and we must call\n            # `param.default.default` to get the actual default value. We should also\n            # ensure we extract the right default if non-Typer defaults are added\n            # to `start_agent` in the future.\n            if isinstance(param.default, ParameterInfo):\n                default = param.default.default\n            else:\n                default = param.default\n\n            # Some defaults are Prefect `SettingsOption.value` methods\n            # that must be called to get the actual value.\n            kwargs[name] = default() if callable(default) else default\n\n    try:\n        start_agent(**kwargs)  # type: ignore\n    except KeyboardInterrupt:\n        # expected when watchfiles kills the process\n        pass\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.api","title":"<code>api</code>  <code>async</code>","text":"<p>Starts a hot-reloading development API.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def api(\n    host: str = SettingsOption(PREFECT_SERVER_API_HOST),\n    port: int = SettingsOption(PREFECT_SERVER_API_PORT),\n    log_level: str = \"DEBUG\",\n    services: bool = True,\n):\n    \"\"\"\n    Starts a hot-reloading development API.\n    \"\"\"\n    import watchfiles\n\n    server_env = os.environ.copy()\n    server_env[\"PREFECT_API_SERVICES_RUN_IN_APP\"] = str(services)\n    server_env[\"PREFECT_API_SERVICES_UI\"] = \"False\"\n    server_env[\"PREFECT_UI_API_URL\"] = f\"http://{host}:{port}/api\"\n\n    command = [\n        sys.executable,\n        \"-m\",\n        \"uvicorn\",\n        \"--factory\",\n        \"prefect.server.api.server:create_app\",\n        \"--host\",\n        str(host),\n        \"--port\",\n        str(port),\n        \"--log-level\",\n        log_level.lower(),\n    ]\n\n    app.console.print(f\"Running: {' '.join(command)}\")\n    import signal\n\n    stop_event = anyio.Event()\n    start_command = partial(\n        run_process, command=command, env=server_env, stream_output=True\n    )\n\n    async with anyio.create_task_group() as tg:\n        try:\n            server_pid = await tg.start(start_command)\n            async for _ in watchfiles.awatch(\n                prefect.__module_path__,\n                stop_event=stop_event,  # type: ignore\n            ):\n                # when any watched files change, restart the server\n                app.console.print(\"Restarting Prefect Server...\")\n                os.kill(server_pid, signal.SIGTERM)  # type: ignore\n                # start a new server\n                server_pid = await tg.start(start_command)\n        except RuntimeError as err:\n            # a bug in watchfiles causes an 'Already borrowed' error from Rust when\n            # exiting: https://github.com/samuelcolvin/watchfiles/issues/200\n            if str(err).strip() != \"Already borrowed\":\n                raise\n        except KeyboardInterrupt:\n            # exit cleanly on ctrl-c by killing the server process if it's\n            # still running\n            try:\n                os.kill(server_pid, signal.SIGTERM)  # type: ignore\n            except ProcessLookupError:\n                # process already exited\n                pass\n\n            stop_event.set()\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.build_docs","title":"<code>build_docs</code>","text":"<p>Builds REST API reference documentation for static display.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef build_docs(\n    schema_path: str = None,\n):\n    \"\"\"\n    Builds REST API reference documentation for static display.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n\n    from prefect.server.api.server import create_app\n\n    schema = create_app(ephemeral=True).openapi()\n\n    if not schema_path:\n        schema_path = (\n            prefect.__development_base_path__ / \"docs\" / \"api-ref\" / \"schema.json\"\n        ).absolute()\n    # overwrite info for display purposes\n    schema[\"info\"] = {}\n    with open(schema_path, \"w\") as f:\n        json.dump(schema, f)\n    app.console.print(f\"OpenAPI schema written to {schema_path}\")\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.build_image","title":"<code>build_image</code>","text":"<p>Build a docker image for development.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef build_image(\n    arch: str = typer.Option(\n        None,\n        help=(\n            \"The architecture to build the container for. \"\n            \"Defaults to the architecture of the host Python. \"\n            f\"[default: {platform.machine()}]\"\n        ),\n    ),\n    python_version: str = typer.Option(\n        None,\n        help=(\n            \"The Python version to build the container for. \"\n            \"Defaults to the version of the host Python. \"\n            f\"[default: {python_version_minor()}]\"\n        ),\n    ),\n    flavor: str = typer.Option(\n        None,\n        help=(\n            \"An alternative flavor to build, for example 'conda'. \"\n            \"Defaults to the standard Python base image\"\n        ),\n    ),\n    dry_run: bool = False,\n):\n    \"\"\"\n    Build a docker image for development.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    # TODO: Once https://github.com/tiangolo/typer/issues/354 is addressed, the\n    #       default can be set in the function signature\n    arch = arch or platform.machine()\n    python_version = python_version or python_version_minor()\n\n    tag = get_prefect_image_name(python_version=python_version, flavor=flavor)\n\n    # Here we use a subprocess instead of the docker-py client to easily stream output\n    # as it comes\n    command = [\n        \"docker\",\n        \"build\",\n        str(prefect.__development_base_path__),\n        \"--tag\",\n        tag,\n        \"--platform\",\n        f\"linux/{arch}\",\n        \"--build-arg\",\n        \"PREFECT_EXTRAS=[dev]\",\n        \"--build-arg\",\n        f\"PYTHON_VERSION={python_version}\",\n    ]\n\n    if flavor:\n        command += [\"--build-arg\", f\"BASE_IMAGE=prefect-{flavor}\"]\n\n    if dry_run:\n        print(\" \".join(command))\n        return\n\n    try:\n        subprocess.check_call(command, shell=sys.platform == \"win32\")\n    except subprocess.CalledProcessError:\n        exit_with_error(\"Failed to build image!\")\n    else:\n        exit_with_success(f\"Built image {tag!r} for linux/{arch}\")\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.container","title":"<code>container</code>","text":"<p>Run a docker container with local code mounted and installed.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef container(bg: bool = False, name=\"prefect-dev\", api: bool = True, tag: str = None):\n    \"\"\"\n    Run a docker container with local code mounted and installed.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    import docker\n    from docker.models.containers import Container\n\n    client = docker.from_env()\n\n    containers = client.containers.list()\n    container_names = {container.name for container in containers}\n    if name in container_names:\n        exit_with_error(\n            f\"Container {name!r} already exists. Specify a different name or stop \"\n            \"the existing container.\"\n        )\n\n    blocking_cmd = \"prefect dev api\" if api else \"sleep infinity\"\n    tag = tag or get_prefect_image_name()\n\n    container: Container = client.containers.create(\n        image=tag,\n        command=[\n            \"/bin/bash\",\n            \"-c\",\n            (  # noqa\n                \"pip install -e /opt/prefect/repo\\\\[dev\\\\] &amp;&amp; touch /READY &amp;&amp;\"\n                f\" {blocking_cmd}\"\n            ),\n        ],\n        name=name,\n        auto_remove=True,\n        working_dir=\"/opt/prefect/repo\",\n        volumes=[f\"{prefect.__development_base_path__}:/opt/prefect/repo\"],\n        shm_size=\"4G\",\n    )\n\n    print(f\"Starting container for image {tag!r}...\")\n    container.start()\n\n    print(\"Waiting for installation to complete\", end=\"\", flush=True)\n    try:\n        ready = False\n        while not ready:\n            print(\".\", end=\"\", flush=True)\n            result = container.exec_run(\"test -f /READY\")\n            ready = result.exit_code == 0\n            if not ready:\n                time.sleep(3)\n    except BaseException:\n        print(\"\\nInterrupted. Stopping container...\")\n        container.stop()\n        raise\n\n    print(\n        textwrap.dedent(\n            f\"\"\"\n            Container {container.name!r} is ready! To connect to the container, run:\n\n                docker exec -it {container.name} /bin/bash\n            \"\"\"\n        )\n    )\n\n    if bg:\n        print(\n            textwrap.dedent(\n                f\"\"\"\n                The container will run forever. Stop the container with:\n\n                    docker stop {container.name}\n                \"\"\"\n            )\n        )\n        # Exit without stopping\n        return\n\n    try:\n        print(\"Send a keyboard interrupt to exit...\")\n        container.wait()\n    except KeyboardInterrupt:\n        pass  # Avoid showing \"Abort\"\n    finally:\n        print(\"\\nStopping container...\")\n        container.stop()\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.kubernetes_manifest","title":"<code>kubernetes_manifest</code>","text":"<p>Generates a Kubernetes manifest for development.</p> Example <p>$ prefect dev kubernetes-manifest | kubectl apply -f -</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef kubernetes_manifest():\n    \"\"\"\n    Generates a Kubernetes manifest for development.\n\n    Example:\n        $ prefect dev kubernetes-manifest | kubectl apply -f -\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-dev.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"prefect_root_directory\": prefect.__development_base_path__,\n            \"image_name\": get_prefect_image_name(),\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.start","title":"<code>start</code>  <code>async</code>","text":"<p>Starts a hot-reloading development server with API, UI, and agent processes.</p> <p>Each service has an individual command if you wish to start them separately. Each service can be excluded here as well.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def start(\n    exclude_api: bool = typer.Option(False, \"--no-api\"),\n    exclude_ui: bool = typer.Option(False, \"--no-ui\"),\n    exclude_agent: bool = typer.Option(False, \"--no-agent\"),\n    work_queues: List[str] = typer.Option(\n        [\"default\"],\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the dev agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Starts a hot-reloading development server with API, UI, and agent processes.\n\n    Each service has an individual command if you wish to start them separately.\n    Each service can be excluded here as well.\n    \"\"\"\n    async with anyio.create_task_group() as tg:\n        if not exclude_api:\n            tg.start_soon(\n                partial(\n                    api,\n                    host=PREFECT_SERVER_API_HOST.value(),\n                    port=PREFECT_SERVER_API_PORT.value(),\n                )\n            )\n        if not exclude_ui:\n            tg.start_soon(ui)\n        if not exclude_agent:\n            # Hook the agent to the hosted API if running\n            if not exclude_api:\n                host = f\"http://{PREFECT_SERVER_API_HOST.value()}:{PREFECT_SERVER_API_PORT.value()}/api\"  # noqa\n            else:\n                host = PREFECT_API_URL.value()\n            tg.start_soon(agent, host, work_queues)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.ui","title":"<code>ui</code>  <code>async</code>","text":"<p>Starts a hot-reloading development UI.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def ui():\n    \"\"\"\n    Starts a hot-reloading development UI.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    with tmpchdir(prefect.__development_base_path__ / \"ui\"):\n        app.console.print(\"Installing npm packages...\")\n        await run_process([\"npm\", \"install\"], stream_output=True)\n\n        app.console.print(\"Starting UI development server...\")\n        await run_process(command=[\"npm\", \"run\", \"serve\"], stream_output=True)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/events/","title":"Events","text":"","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/events/#prefect.cli.events","title":"<code>prefect.cli.events</code>","text":"","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/events/#prefect.cli.events.stream","title":"<code>stream</code>  <code>async</code>","text":"<p>Subscribes to the event stream of a workspace, printing each event as it is received. By default, events are printed as JSON, but can be printed as text by passing <code>--format text</code>.</p> Source code in <code>prefect/cli/events.py</code> <pre><code>@events_app.command()\nasync def stream(\n    format: StreamFormat = typer.Option(\n        StreamFormat.json, \"--format\", help=\"Output format (json or text)\"\n    ),\n    output_file: str = typer.Option(\n        None, \"--output-file\", help=\"File to write events to\"\n    ),\n    account: bool = typer.Option(\n        False,\n        \"--account\",\n        help=\"Stream events for entire account, including audit logs\",\n    ),\n    run_once: bool = typer.Option(False, \"--run-once\", help=\"Stream only one event\"),\n):\n    \"\"\"Subscribes to the event stream of a workspace, printing each event\n    as it is received. By default, events are printed as JSON, but can be\n    printed as text by passing `--format text`.\n    \"\"\"\n\n    try:\n        if account:\n            events_subscriber = PrefectCloudAccountEventSubscriber()\n        else:\n            events_subscriber = get_events_subscriber()\n\n        app.console.print(\"Subscribing to event stream...\")\n        async with events_subscriber as subscriber:\n            async for event in subscriber:\n                await handle_event(event, format, output_file)\n                if run_once:\n                    typer.Exit(0)\n    except Exception as exc:\n        handle_error(exc)\n</code></pre>","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/flow/","title":"flow","text":"","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow","title":"<code>prefect.cli.flow</code>","text":"<p>Command line interface for working with flows.</p>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View flows.</p> Source code in <code>prefect/cli/flow.py</code> <pre><code>@flow_app.command()\nasync def ls(\n    limit: int = 15,\n):\n    \"\"\"\n    View flows.\n    \"\"\"\n    async with get_client() as client:\n        flows = await client.read_flows(\n            limit=limit,\n            sort=FlowSort.CREATED_DESC,\n        )\n\n    table = Table(title=\"Flows\")\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Created\", no_wrap=True)\n\n    for flow in flows:\n        table.add_row(\n            str(flow.id),\n            str(flow.name),\n            str(flow.created),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Serve a flow via an entrypoint.</p> Source code in <code>prefect/cli/flow.py</code> <pre><code>@flow_app.command()\nasync def serve(\n    entrypoint: str = typer.Argument(\n        ...,\n        help=(\n            \"The path to a file containing a flow and the name of the flow function in\"\n            \" the format `./path/to/file.py:flow_func_name`.\"\n        ),\n    ),\n    name: str = typer.Option(\n        ...,\n        \"--name\",\n        \"-n\",\n        help=\"The name to give the deployment created for the flow.\",\n    ),\n    description: Optional[str] = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the created deployment. If not provided, the\"\n            \" description will be populated from the flow's description.\"\n        ),\n    ),\n    version: Optional[str] = typer.Option(\n        None, \"-v\", \"--version\", help=\"A version to give the created deployment.\"\n    ),\n    tags: Optional[List[str]] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=\"One or more optional tags to apply to the created deployment.\",\n    ),\n    cron: Optional[str] = typer.Option(\n        None,\n        \"--cron\",\n        help=(\n            \"A cron string that will be used to set a schedule for the created\"\n            \" deployment.\"\n        ),\n    ),\n    interval: Optional[int] = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) between scheduled runs of\"\n            \" the flow.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The start date for an interval schedule.\"\n    ),\n    rrule: Optional[str] = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set a schedule for the created deployment.\",\n    ),\n    timezone: Optional[str] = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Timezone to used scheduling flow runs e.g. 'America/New_York'\",\n    ),\n    pause_on_shutdown: bool = typer.Option(\n        True,\n        help=(\n            \"If set, provided schedule will be paused when the serve command is\"\n            \" stopped. If not set, the schedules will continue running.\"\n        ),\n    ),\n):\n    \"\"\"\n    Serve a flow via an entrypoint.\n    \"\"\"\n    runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown)\n    try:\n        schedules = []\n        if interval or cron or rrule:\n            schedule = construct_schedule(\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                timezone=timezone,\n                anchor_date=interval_anchor,\n            )\n            schedules = [MinimalDeploymentSchedule(schedule=schedule, active=True)]\n\n        runner_deployment = RunnerDeployment.from_entrypoint(\n            entrypoint=entrypoint,\n            name=name,\n            schedules=schedules,\n            description=description,\n            tags=tags or [],\n            version=version,\n        )\n    except (MissingFlowError, ValueError) as exc:\n        exit_with_error(str(exc))\n    deployment_id = await runner.add_deployment(runner_deployment)\n\n    help_message = (\n        f\"[green]Your flow {runner_deployment.flow_name!r} is being served and polling\"\n        \" for scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the following\"\n        \" command:\\n[blue]\\n\\t$ prefect deployment run\"\n        f\" '{runner_deployment.flow_name}/{name}'\\n[/]\"\n    )\n    if PREFECT_UI_URL:\n        help_message += (\n            \"\\nYou can also run your flow via the Prefect UI:\"\n            f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n        )\n\n    app.console.print(help_message, soft_wrap=True)\n    await runner.start()\n</code></pre>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow_run/","title":"flow_run","text":"","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run","title":"<code>prefect.cli.flow_run</code>","text":"<p>Command line interface for working with flow runs</p>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.cancel","title":"<code>cancel</code>  <code>async</code>","text":"<p>Cancel a flow run by ID.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def cancel(id: UUID):\n    \"\"\"Cancel a flow run by ID.\"\"\"\n    async with get_client() as client:\n        cancelling_state = State(type=StateType.CANCELLING)\n        try:\n            result = await client.set_flow_run_state(\n                flow_run_id=id, state=cancelling_state\n            )\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run '{id}' not found!\")\n\n    if result.status == SetStateStatus.ABORT:\n        exit_with_error(\n            f\"Flow run '{id}' was unable to be cancelled. Reason:\"\n            f\" '{result.details.reason}'\"\n        )\n\n    exit_with_success(f\"Flow run '{id}' was successfully scheduled for cancellation.\")\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a flow run by ID.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def delete(id: UUID):\n    \"\"\"\n    Delete a flow run by ID.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.delete_flow_run(id)\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run '{id}' not found!\")\n\n    exit_with_success(f\"Successfully deleted flow run '{id}'.\")\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a flow run.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def inspect(id: UUID):\n    \"\"\"\n    View details about a flow run.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            flow_run = await client.read_flow_run(id)\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code == status.HTTP_404_NOT_FOUND:\n                exit_with_error(f\"Flow run {id!r} not found!\")\n            else:\n                raise\n\n    app.console.print(Pretty(flow_run))\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.logs","title":"<code>logs</code>  <code>async</code>","text":"<p>View logs for a flow run.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def logs(\n    id: UUID,\n    head: bool = typer.Option(\n        False,\n        \"--head\",\n        \"-h\",\n        help=(\n            f\"Show the first {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of\"\n            \" all logs.\"\n        ),\n    ),\n    num_logs: int = typer.Option(\n        None,\n        \"--num-logs\",\n        \"-n\",\n        help=(\n            \"Number of logs to show when using the --head or --tail flag. If None,\"\n            f\" defaults to {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS}.\"\n        ),\n        min=1,\n    ),\n    reverse: bool = typer.Option(\n        False,\n        \"--reverse\",\n        \"-r\",\n        help=\"Reverse the logs order to print the most recent logs first\",\n    ),\n    tail: bool = typer.Option(\n        False,\n        \"--tail\",\n        \"-t\",\n        help=(\n            f\"Show the last {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of\"\n            \" all logs.\"\n        ),\n    ),\n):\n    \"\"\"\n    View logs for a flow run.\n    \"\"\"\n    # Pagination - API returns max 200 (LOGS_DEFAULT_PAGE_SIZE) logs at a time\n    offset = 0\n    more_logs = True\n    num_logs_returned = 0\n\n    # if head and tail flags are being used together\n    if head and tail:\n        exit_with_error(\"Please provide either a `head` or `tail` option but not both.\")\n\n    user_specified_num_logs = (\n        num_logs or LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS\n        if head or tail or num_logs\n        else None\n    )\n\n    # if using tail update offset according to LOGS_DEFAULT_PAGE_SIZE\n    if tail:\n        offset = max(0, user_specified_num_logs - LOGS_DEFAULT_PAGE_SIZE)\n\n    log_filter = LogFilter(flow_run_id={\"any_\": [id]})\n\n    async with get_client() as client:\n        # Get the flow run\n        try:\n            flow_run = await client.read_flow_run(id)\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run {str(id)!r} not found!\")\n\n        while more_logs:\n            num_logs_to_return_from_page = (\n                LOGS_DEFAULT_PAGE_SIZE\n                if user_specified_num_logs is None\n                else min(\n                    LOGS_DEFAULT_PAGE_SIZE, user_specified_num_logs - num_logs_returned\n                )\n            )\n\n            # Get the next page of logs\n            page_logs = await client.read_logs(\n                log_filter=log_filter,\n                limit=num_logs_to_return_from_page,\n                offset=offset,\n                sort=(\n                    LogSort.TIMESTAMP_DESC if reverse or tail else LogSort.TIMESTAMP_ASC\n                ),\n            )\n\n            for log in reversed(page_logs) if tail and not reverse else page_logs:\n                app.console.print(\n                    # Print following the flow run format (declared in logging.yml)\n                    (\n                        f\"{pendulum.instance(log.timestamp).to_datetime_string()}.{log.timestamp.microsecond // 1000:03d} |\"\n                        f\" {logging.getLevelName(log.level):7s} | Flow run\"\n                        f\" {flow_run.name!r} - {log.message}\"\n                    ),\n                    soft_wrap=True,\n                )\n\n            # Update the number of logs retrieved\n            num_logs_returned += num_logs_to_return_from_page\n\n            if tail:\n                #  If the current offset is not 0, update the offset for the next page\n                if offset != 0:\n                    offset = (\n                        0\n                        # Reset the offset to 0 if there are less logs than the LOGS_DEFAULT_PAGE_SIZE to get the remaining log\n                        if offset &lt; LOGS_DEFAULT_PAGE_SIZE\n                        else offset - LOGS_DEFAULT_PAGE_SIZE\n                    )\n                else:\n                    more_logs = False\n            else:\n                if len(page_logs) == LOGS_DEFAULT_PAGE_SIZE:\n                    offset += LOGS_DEFAULT_PAGE_SIZE\n                else:\n                    # No more logs to show, exit\n                    more_logs = False\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View recent flow runs or flow runs for specific flows.</p> <p>Arguments:</p> <pre><code>flow_name: Name of the flow\n\nlimit: Maximum number of flow runs to list. Defaults to 15.\n\nstate: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.\n\nstate_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.\n</code></pre> <p>Examples:</p> <p>$ prefect flow-runs ls --state Running</p> <p>$ prefect flow-runs ls --state Running --state late</p> <p>$ prefect flow-runs ls --state-type RUNNING</p> <p>$ prefect flow-runs ls --state-type RUNNING --state-type FAILED</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def ls(\n    flow_name: List[str] = typer.Option(None, help=\"Name of the flow\"),\n    limit: int = typer.Option(15, help=\"Maximum number of flow runs to list\"),\n    state: List[str] = typer.Option(None, help=\"Name of the flow run's state\"),\n    state_type: List[str] = typer.Option(None, help=\"Type of the flow run's state\"),\n):\n    \"\"\"\n    View recent flow runs or flow runs for specific flows.\n\n    Arguments:\n\n        flow_name: Name of the flow\n\n        limit: Maximum number of flow runs to list. Defaults to 15.\n\n        state: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.\n\n        state_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.\n\n    Examples:\n\n    $ prefect flow-runs ls --state Running\n\n    $ prefect flow-runs ls --state Running --state late\n\n    $ prefect flow-runs ls --state-type RUNNING\n\n    $ prefect flow-runs ls --state-type RUNNING --state-type FAILED\n    \"\"\"\n\n    # Handling `state` and `state_type` argument validity in the function instead of by specifying\n    # List[StateType] and List[StateName] in the type hints, allows users to provide\n    # case-insensitive arguments for `state` and `state_type`.\n\n    prefect_state_names = {\n        \"SCHEDULED\": \"Scheduled\",\n        \"PENDING\": \"Pending\",\n        \"RUNNING\": \"Running\",\n        \"COMPLETED\": \"Completed\",\n        \"FAILED\": \"Failed\",\n        \"CANCELLED\": \"Cancelled\",\n        \"CRASHED\": \"Crashed\",\n        \"PAUSED\": \"Paused\",\n        \"CANCELLING\": \"Cancelling\",\n        \"SUSPENDED\": \"Suspended\",\n        \"AWAITINGRETRY\": \"AwaitingRetry\",\n        \"RETRYING\": \"Retrying\",\n        \"LATE\": \"Late\",\n    }\n\n    state_filter = {}\n    formatted_states = []\n\n    if state:\n        for s in state:\n            uppercased_state = s.upper()\n            if uppercased_state in prefect_state_names:\n                capitalized_state = prefect_state_names[uppercased_state]\n                formatted_states.append(capitalized_state)\n            else:\n                # Do not change the case of the state name if it is not one of the official Prefect state names\n                formatted_states.append(s)\n                logger.warning(\n                    f\"State name {repr(s)} is not one of the official Prefect state names.\"\n                )\n\n        state_filter[\"name\"] = {\"any_\": formatted_states}\n\n    if state_type:\n        upper_cased_states = [s.upper() for s in state_type]\n        if not all(s in StateType.__members__ for s in upper_cased_states):\n            exit_with_error(\n                f\"Invalid state type. Options are {', '.join(StateType.__members__)}.\"\n            )\n\n        state_filter[\"type\"] = {\n            \"any_\": [StateType[s].value for s in upper_cased_states]\n        }\n\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_filter=FlowFilter(name={\"any_\": flow_name}) if flow_name else None,\n            flow_run_filter=FlowRunFilter(state=state_filter) if state_filter else None,\n            limit=limit,\n            sort=FlowRunSort.EXPECTED_START_TIME_DESC,\n        )\n        flows_by_id = {\n            flow.id: flow\n            for flow in await client.read_flows(\n                flow_filter=FlowFilter(id={\"any_\": [run.flow_id for run in flow_runs]})\n            )\n        }\n\n        if not flow_runs:\n            exit_with_success(\"No flow runs found.\")\n\n    table = Table(title=\"Flow Runs\")\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Flow\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"State\", no_wrap=True)\n    table.add_column(\"When\", style=\"bold\", no_wrap=True)\n\n    for flow_run in sorted(flow_runs, key=lambda d: d.created, reverse=True):\n        flow = flows_by_id[flow_run.flow_id]\n        timestamp = (\n            flow_run.state.state_details.scheduled_time\n            if flow_run.state.is_scheduled()\n            else flow_run.state.timestamp\n        )\n        table.add_row(\n            str(flow_run.id),\n            str(flow.name),\n            str(flow_run.name),\n            str(flow_run.state.type.value),\n            pendulum.instance(timestamp).diff_for_humans(),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/kubernetes/","title":"kubernetes","text":"","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes","title":"<code>prefect.cli.kubernetes</code>","text":"<p>Command line interface for working with Prefect on Kubernetes</p>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_agent","title":"<code>manifest_agent</code>","text":"<p>Generates a manifest for deploying Agent on Kubernetes.</p> Example <p>$ prefect kubernetes manifest agent | kubectl apply -f -</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"agent\")\ndef manifest_agent(\n    api_url: str = SettingsOption(PREFECT_API_URL),\n    api_key: str = SettingsOption(PREFECT_API_KEY),\n    image_tag: str = typer.Option(\n        get_prefect_image_name(),\n        \"-i\",\n        \"--image-tag\",\n        help=\"The tag of a Docker image to use for the Agent.\",\n    ),\n    namespace: str = typer.Option(\n        \"default\",\n        \"-n\",\n        \"--namespace\",\n        help=\"A Kubernetes namespace to create agent in.\",\n    ),\n    work_queue: str = typer.Option(\n        \"kubernetes\",\n        \"-q\",\n        \"--work-queue\",\n        help=\"A work queue name for the agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Generates a manifest for deploying Agent on Kubernetes.\n\n    Example:\n        $ prefect kubernetes manifest agent | kubectl apply -f -\n    \"\"\"\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-agent.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"api_url\": api_url,\n            \"api_key\": api_key,\n            \"image_name\": image_tag,\n            \"namespace\": namespace,\n            \"work_queue\": work_queue,\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_flow_run_job","title":"<code>manifest_flow_run_job</code>  <code>async</code>","text":"<p>Prints the default KubernetesJob Job manifest.</p> <p>Use this file to fully customize your <code>KubernetesJob</code> deployments.</p> <p>\b Example:     \b     $ prefect kubernetes manifest flow-run-job</p> <p>\b Output, a YAML file:     \b     apiVersion: batch/v1     kind: Job     ...</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"flow-run-job\")\nasync def manifest_flow_run_job():\n    \"\"\"\n    Prints the default KubernetesJob Job manifest.\n\n    Use this file to fully customize your `KubernetesJob` deployments.\n\n    \\b\n    Example:\n        \\b\n        $ prefect kubernetes manifest flow-run-job\n\n    \\b\n    Output, a YAML file:\n        \\b\n        apiVersion: batch/v1\n        kind: Job\n        ...\n    \"\"\"\n\n    KubernetesJob.base_job_manifest()\n\n    output = yaml.dump(KubernetesJob.base_job_manifest())\n\n    # add some commentary where appropriate\n    output = output.replace(\n        \"metadata:\\n  labels:\",\n        \"metadata:\\n  # labels are required, even if empty\\n  labels:\",\n    )\n    output = output.replace(\n        \"containers:\\n\",\n        \"containers:  # the first container is required\\n\",\n    )\n    output = output.replace(\n        \"env: []\\n\",\n        \"env: []  # env is required, even if empty\\n\",\n    )\n\n    print(output)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_server","title":"<code>manifest_server</code>","text":"<p>Generates a manifest for deploying Prefect on Kubernetes.</p> Example <p>$ prefect kubernetes manifest server | kubectl apply -f -</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"server\")\ndef manifest_server(\n    image_tag: str = typer.Option(\n        get_prefect_image_name(),\n        \"-i\",\n        \"--image-tag\",\n        help=\"The tag of a Docker image to use for the server.\",\n    ),\n    namespace: str = typer.Option(\n        \"default\",\n        \"-n\",\n        \"--namespace\",\n        help=\"A Kubernetes namespace to create the server in.\",\n    ),\n    log_level: str = SettingsOption(PREFECT_LOGGING_SERVER_LEVEL),\n):\n    \"\"\"\n    Generates a manifest for deploying Prefect on Kubernetes.\n\n    Example:\n        $ prefect kubernetes manifest server | kubectl apply -f -\n    \"\"\"\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-server.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"image_name\": image_tag,\n            \"namespace\": namespace,\n            \"log_level\": log_level,\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/profile/","title":"profile","text":"","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile","title":"<code>prefect.cli.profile</code>","text":"<p>Command line interface for working with profiles.</p>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.create","title":"<code>create</code>","text":"<p>Create a new profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef create(\n    name: str,\n    from_name: str = typer.Option(None, \"--from\", help=\"Copy an existing profile.\"),\n):\n    \"\"\"\n    Create a new profile.\n    \"\"\"\n\n    profiles = prefect.settings.load_profiles()\n    if name in profiles:\n        app.console.print(\n            textwrap.dedent(\n                f\"\"\"\n                [red]Profile {name!r} already exists.[/red]\n                To create a new profile, remove the existing profile first:\n\n                    prefect profile delete {name!r}\n                \"\"\"\n            ).strip()\n        )\n        raise typer.Exit(1)\n\n    if from_name:\n        if from_name not in profiles:\n            exit_with_error(f\"Profile {from_name!r} not found.\")\n\n        # Create a copy of the profile with a new name and add to the collection\n        profiles.add_profile(profiles[from_name].copy(update={\"name\": name}))\n    else:\n        profiles.add_profile(prefect.settings.Profile(name=name, settings={}))\n\n    prefect.settings.save_profiles(profiles)\n\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n            Created profile with properties:\n                name - {name!r}\n                from name - {from_name or None}\n\n            Use created profile for future, subsequent commands:\n                prefect profile use {name!r}\n\n            Use created profile temporarily for a single command:\n                prefect -p {name!r} config view\n            \"\"\"\n        )\n    )\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.delete","title":"<code>delete</code>","text":"<p>Delete the given profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef delete(name: str):\n    \"\"\"\n    Delete the given profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile.name == name:\n        exit_with_error(\n            f\"Profile {name!r} is the active profile. You must switch profiles before\"\n            \" it can be deleted.\"\n        )\n\n    profiles.remove_profile(name)\n\n    verb = \"Removed\"\n    if name == \"default\":\n        verb = \"Reset\"\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"{verb} profile {name!r}.\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.inspect","title":"<code>inspect</code>","text":"<p>Display settings from a given profile; defaults to active.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef inspect(\n    name: Optional[str] = typer.Argument(\n        None, help=\"Name of profile to inspect; defaults to active profile.\"\n    ),\n):\n    \"\"\"\n    Display settings from a given profile; defaults to active.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name is None:\n        current_profile = prefect.context.get_settings_context().profile\n        if not current_profile:\n            exit_with_error(\"No active profile set - please provide a name to inspect.\")\n        name = current_profile.name\n        print(f\"No name provided, defaulting to {name!r}\")\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    if not profiles[name].settings:\n        # TODO: Consider instructing on how to add settings.\n        print(f\"Profile {name!r} is empty.\")\n\n    for setting, value in profiles[name].settings.items():\n        app.console.print(f\"{setting.name}='{value}'\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.ls","title":"<code>ls</code>","text":"<p>List profile names.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef ls():\n    \"\"\"\n    List profile names.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    current_profile = prefect.context.get_settings_context().profile\n    current_name = current_profile.name if current_profile is not None else None\n\n    table = Table(caption=\"* active profile\")\n    table.add_column(\n        \"[#024dfd]Available Profiles:\", justify=\"right\", style=\"#8ea0ae\", no_wrap=True\n    )\n\n    for name in profiles:\n        if name == current_name:\n            table.add_row(f\"[green]  * {name}[/green]\")\n        else:\n            table.add_row(f\"  {name}\")\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.rename","title":"<code>rename</code>","text":"<p>Change the name of a profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef rename(name: str, new_name: str):\n    \"\"\"\n    Change the name of a profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    if new_name in profiles:\n        exit_with_error(f\"Profile {new_name!r} already exists.\")\n\n    profiles.add_profile(profiles[name].copy(update={\"name\": new_name}))\n    profiles.remove_profile(name)\n\n    # If the active profile was renamed switch the active profile to the new name.\n    prefect.context.get_settings_context().profile\n    if profiles.active_name == name:\n        profiles.set_active(new_name)\n    if os.environ.get(\"PREFECT_PROFILE\") == name:\n        app.console.print(\n            f\"You have set your current profile to {name!r} with the \"\n            \"PREFECT_PROFILE environment variable. You must update this variable to \"\n            f\"{new_name!r} to continue using the profile.\"\n        )\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"Renamed profile {name!r} to {new_name!r}.\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.use","title":"<code>use</code>  <code>async</code>","text":"<p>Set the given profile to active.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\nasync def use(name: str):\n    \"\"\"\n    Set the given profile to active.\n    \"\"\"\n    status_messages = {\n        ConnectionStatus.CLOUD_CONNECTED: (\n            exit_with_success,\n            f\"Connected to Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.CLOUD_ERROR: (\n            exit_with_error,\n            f\"Error connecting to Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.CLOUD_UNAUTHORIZED: (\n            exit_with_error,\n            f\"Error authenticating with Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.ORION_CONNECTED: (\n            exit_with_success,\n            f\"Connected to Prefect server using profile {name!r}\",\n        ),\n        ConnectionStatus.ORION_ERROR: (\n            exit_with_error,\n            f\"Error connecting to Prefect server using profile {name!r}\",\n        ),\n        ConnectionStatus.EPHEMERAL: (\n            exit_with_success,\n            (\n                f\"No Prefect server specified using profile {name!r} - the API will run\"\n                \" in ephemeral mode.\"\n            ),\n        ),\n        ConnectionStatus.INVALID_API: (\n            exit_with_error,\n            \"Error connecting to Prefect API URL\",\n        ),\n    }\n\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles.names:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    profiles.set_active(name)\n    prefect.settings.save_profiles(profiles)\n\n    with Progress(\n        SpinnerColumn(),\n        TextColumn(\"[progress.description]{task.description}\"),\n        transient=False,\n    ) as progress:\n        progress.add_task(\n            description=\"Checking API connectivity...\",\n            total=None,\n        )\n\n        with use_profile(name, include_current_context=False):\n            connection_status = await check_orion_connection()\n\n        exit_method, msg = status_messages[connection_status]\n\n    exit_method(msg)\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/root/","title":"root","text":"","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/root/#prefect.cli.root","title":"<code>prefect.cli.root</code>","text":"<p>Base <code>prefect</code> command-line application</p>","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/root/#prefect.cli.root.version","title":"<code>version</code>  <code>async</code>","text":"<p>Get the current Prefect version.</p> Source code in <code>prefect/cli/root.py</code> <pre><code>@app.command()\nasync def version():\n    \"\"\"Get the current Prefect version.\"\"\"\n    import sqlite3\n\n    from prefect.server.utilities.database import get_dialect\n    from prefect.settings import PREFECT_API_DATABASE_CONNECTION_URL\n\n    version_info = {\n        \"Version\": prefect.__version__,\n        \"API version\": SERVER_API_VERSION,\n        \"Python version\": platform.python_version(),\n        \"Git commit\": prefect.__version_info__[\"full-revisionid\"][:8],\n        \"Built\": pendulum.parse(\n            prefect.__version_info__[\"date\"]\n        ).to_day_datetime_string(),\n        \"OS/Arch\": f\"{sys.platform}/{platform.machine()}\",\n        \"Profile\": prefect.context.get_settings_context().profile.name,\n    }\n\n    server_type: str\n\n    try:\n        # We do not context manage the client because when using an ephemeral app we do not\n        # want to create the database or run migrations\n        client = prefect.get_client()\n        server_type = client.server_type.value\n    except Exception:\n        server_type = \"&lt;client error&gt;\"\n\n    version_info[\"Server type\"] = server_type.lower()\n\n    # TODO: Consider adding an API route to retrieve this information?\n    if server_type == ServerType.EPHEMERAL.value:\n        database = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value()).name\n        version_info[\"Server\"] = {\"Database\": database}\n        if database == \"sqlite\":\n            version_info[\"Server\"][\"SQLite version\"] = sqlite3.sqlite_version\n\n    def display(object: dict, nesting: int = 0):\n        # Recursive display of a dictionary with nesting\n        for key, value in object.items():\n            key += \":\"\n            if isinstance(value, dict):\n                app.console.print(key)\n                return display(value, nesting + 2)\n            prefix = \" \" * nesting\n            app.console.print(f\"{prefix}{key.ljust(20 - len(prefix))} {value}\")\n\n    display(version_info)\n</code></pre>","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/server/","title":"server","text":"","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server","title":"<code>prefect.cli.server</code>","text":"<p>Command line interface for working with Prefect</p>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.downgrade","title":"<code>downgrade</code>  <code>async</code>","text":"<p>Downgrade the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def downgrade(\n    yes: bool = typer.Option(False, \"--yes\", \"-y\"),\n    revision: str = typer.Option(\n        \"-1\",\n        \"-r\",\n        help=(\n            \"The revision to pass to `alembic downgrade`. If not provided, \"\n            \"downgrades to the most recent revision. Use 'base' to run all \"\n            \"migrations.\"\n        ),\n    ),\n    dry_run: bool = typer.Option(\n        False,\n        help=(\n            \"Flag to show what migrations would be made without applying them. Will\"\n            \" emit sql statements to stdout.\"\n        ),\n    ),\n):\n    \"\"\"Downgrade the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_downgrade\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n\n    engine = await db.engine()\n\n    if not yes:\n        confirm = typer.confirm(\n            \"Are you sure you want to downgrade the Prefect \"\n            f\"database at {engine.url!r}?\"\n        )\n        if not confirm:\n            exit_with_error(\"Database downgrade aborted!\")\n\n    app.console.print(\"Running downgrade migrations ...\")\n    await run_sync_in_worker_thread(\n        alembic_downgrade, revision=revision, dry_run=dry_run\n    )\n    app.console.print(\"Migrations succeeded!\")\n    exit_with_success(f\"Prefect database at {engine.url!r} downgraded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.reset","title":"<code>reset</code>  <code>async</code>","text":"<p>Drop and recreate all Prefect database tables</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def reset(yes: bool = typer.Option(False, \"--yes\", \"-y\")):\n    \"\"\"Drop and recreate all Prefect database tables\"\"\"\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n    engine = await db.engine()\n    if not yes:\n        confirm = typer.confirm(\n            \"Are you sure you want to reset the Prefect database located \"\n            f'at \"{engine.url!r}\"? This will drop and recreate all tables.'\n        )\n        if not confirm:\n            exit_with_error(\"Database reset aborted\")\n    app.console.print(\"Downgrading database...\")\n    await db.drop_db()\n    app.console.print(\"Upgrading database...\")\n    await db.create_db()\n    exit_with_success(f'Prefect database \"{engine.url!r}\" reset!')\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.revision","title":"<code>revision</code>  <code>async</code>","text":"<p>Create a new migration for the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def revision(\n    message: str = typer.Option(\n        None,\n        \"--message\",\n        \"-m\",\n        help=\"A message to describe the migration.\",\n    ),\n    autogenerate: bool = False,\n):\n    \"\"\"Create a new migration for the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_revision\n\n    app.console.print(\"Running migration file creation ...\")\n    await run_sync_in_worker_thread(\n        alembic_revision,\n        message=message,\n        autogenerate=autogenerate,\n    )\n    exit_with_success(\"Creating new migration file succeeded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.stamp","title":"<code>stamp</code>  <code>async</code>","text":"<p>Stamp the revision table with the given revision; don't run any migrations</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def stamp(revision: str):\n    \"\"\"Stamp the revision table with the given revision; don't run any migrations\"\"\"\n    from prefect.server.database.alembic_commands import alembic_stamp\n\n    app.console.print(\"Stamping database with revision ...\")\n    await run_sync_in_worker_thread(alembic_stamp, revision=revision)\n    exit_with_success(\"Stamping database with revision succeeded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start a Prefect server instance</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@server_app.command()\nasync def start(\n    host: str = SettingsOption(PREFECT_SERVER_API_HOST),\n    port: int = SettingsOption(PREFECT_SERVER_API_PORT),\n    keep_alive_timeout: int = SettingsOption(PREFECT_SERVER_API_KEEPALIVE_TIMEOUT),\n    log_level: str = SettingsOption(PREFECT_LOGGING_SERVER_LEVEL),\n    scheduler: bool = SettingsOption(PREFECT_API_SERVICES_SCHEDULER_ENABLED),\n    analytics: bool = SettingsOption(\n        PREFECT_SERVER_ANALYTICS_ENABLED, \"--analytics-on/--analytics-off\"\n    ),\n    late_runs: bool = SettingsOption(PREFECT_API_SERVICES_LATE_RUNS_ENABLED),\n    ui: bool = SettingsOption(PREFECT_UI_ENABLED),\n    background: bool = typer.Option(\n        False, \"--background\", \"-b\", help=\"Run the server in the background\"\n    ),\n):\n    \"\"\"\n    Start a Prefect server instance\n    \"\"\"\n\n    server_env = os.environ.copy()\n    server_env[\"PREFECT_API_SERVICES_SCHEDULER_ENABLED\"] = str(scheduler)\n    server_env[\"PREFECT_SERVER_ANALYTICS_ENABLED\"] = str(analytics)\n    server_env[\"PREFECT_API_SERVICES_LATE_RUNS_ENABLED\"] = str(late_runs)\n    server_env[\"PREFECT_API_SERVICES_UI\"] = str(ui)\n    server_env[\"PREFECT_UI_ENABLED\"] = str(ui)\n    server_env[\"PREFECT_LOGGING_SERVER_LEVEL\"] = log_level\n\n    base_url = f\"http://{host}:{port}\"\n\n    pid_file = anyio.Path(PREFECT_HOME.value() / PID_FILE)\n    # check if port is already in use\n    try:\n        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n            s.bind((host, port))\n    except socket.error:\n        if await pid_file.exists():\n            exit_with_error(\n                f\"A background server process is already running on port {port}. \"\n                \"Run `prefect server stop` to stop it or specify a different port \"\n                \"with the `--port` flag.\"\n            )\n        exit_with_error(\n            f\"Port {port} is already in use. Please specify a different port with the \"\n            \"`--port` flag.\"\n        )\n\n    # check if server is already running in the background\n    if background:\n        try:\n            await pid_file.touch(mode=0o600, exist_ok=False)\n        except FileExistsError:\n            exit_with_error(\n                \"A server is already running in the background. To stop it,\"\n                \" run `prefect server stop`.\"\n            )\n\n    app.console.print(generate_welcome_blurb(base_url, ui_enabled=ui))\n    app.console.print(\"\\n\")\n\n    try:\n        command = [\n            sys.executable,\n            \"-m\",\n            \"uvicorn\",\n            \"--app-dir\",\n            str(prefect.__module_path__.parent),\n            \"--factory\",\n            \"prefect.server.api.server:create_app\",\n            \"--host\",\n            str(host),\n            \"--port\",\n            str(port),\n            \"--timeout-keep-alive\",\n            str(keep_alive_timeout),\n        ]\n        logger.debug(\"Opening server process with command: %s\", shlex.join(command))\n        process = await anyio.open_process(\n            command=command,\n            env=server_env,\n        )\n\n        process_id = process.pid\n        if background:\n            await pid_file.write_text(str(process_id))\n\n            app.console.print(\n                \"The Prefect server is running in the background. Run `prefect\"\n                \" server stop` to stop it.\"\n            )\n            return\n\n        async with process:\n            # Explicitly handle the interrupt signal here, as it will allow us to\n            # cleanly stop the uvicorn server. Failing to do that may cause a\n            # large amount of anyio error traces on the terminal, because the\n            # SIGINT is handled by Typer/Click in this process (the parent process)\n            # and will start shutting down subprocesses:\n            # https://github.com/PrefectHQ/server/issues/2475\n\n            setup_signal_handlers_server(\n                process_id, \"the Prefect server\", app.console.print\n            )\n\n            await consume_process_output(process, sys.stdout, sys.stderr)\n\n    except anyio.EndOfStream:\n        logging.error(\"Subprocess stream ended unexpectedly\")\n    except Exception as e:\n        logging.error(f\"An error occurred: {str(e)}\")\n\n    app.console.print(\"Server stopped!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Stop a Prefect server instance running in the background</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@server_app.command()\nasync def stop():\n    \"\"\"Stop a Prefect server instance running in the background\"\"\"\n    pid_file = anyio.Path(PREFECT_HOME.value() / PID_FILE)\n    if not await pid_file.exists():\n        exit_with_success(\"No server running in the background.\")\n    pid = int(await pid_file.read_text())\n    try:\n        os.kill(pid, 15)\n    except ProcessLookupError:\n        exit_with_success(\n            \"The server process is not running. Cleaning up stale PID file.\"\n        )\n    finally:\n        # The file probably exists, but use `missing_ok` to avoid an\n        # error if the file was deleted by another actor\n        await pid_file.unlink(missing_ok=True)\n    app.console.print(\"Server stopped!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.upgrade","title":"<code>upgrade</code>  <code>async</code>","text":"<p>Upgrade the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def upgrade(\n    yes: bool = typer.Option(False, \"--yes\", \"-y\"),\n    revision: str = typer.Option(\n        \"head\",\n        \"-r\",\n        help=(\n            \"The revision to pass to `alembic upgrade`. If not provided, runs all\"\n            \" migrations.\"\n        ),\n    ),\n    dry_run: bool = typer.Option(\n        False,\n        help=(\n            \"Flag to show what migrations would be made without applying them. Will\"\n            \" emit sql statements to stdout.\"\n        ),\n    ),\n):\n    \"\"\"Upgrade the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_upgrade\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n    engine = await db.engine()\n\n    if not yes:\n        confirm = typer.confirm(\n            f\"Are you sure you want to upgrade the Prefect database at {engine.url!r}?\"\n        )\n        if not confirm:\n            exit_with_error(\"Database upgrade aborted!\")\n\n    app.console.print(\"Running upgrade migrations ...\")\n    await run_sync_in_worker_thread(alembic_upgrade, revision=revision, dry_run=dry_run)\n    app.console.print(\"Migrations succeeded!\")\n    exit_with_success(f\"Prefect database at {engine.url!r} upgraded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/shell/","title":"shell","text":"","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell","title":"<code>prefect.cli.shell</code>","text":"<p>Provides a set of tools for executing shell commands as Prefect flows. Includes functionalities for running shell commands ad-hoc or serving them as Prefect flows, with options for logging output, scheduling, and deployment customization.</p>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.output_collect","title":"<code>output_collect</code>","text":"<p>Collects output from a subprocess pipe and stores it in a container list.</p> <p>Parameters:</p> Name Type Description Default <code>pipe</code> <p>The output pipe of the subprocess, either stdout or stderr.</p> required <code>container</code> <p>A list to store the collected output lines.</p> required Source code in <code>prefect/cli/shell.py</code> <pre><code>def output_collect(pipe, container):\n    \"\"\"\n    Collects output from a subprocess pipe and stores it in a container list.\n\n    Args:\n        pipe: The output pipe of the subprocess, either stdout or stderr.\n        container: A list to store the collected output lines.\n    \"\"\"\n    for line in iter(pipe.readline, \"\"):\n        container.append(line)\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.output_stream","title":"<code>output_stream</code>","text":"<p>Read from a pipe line by line and log using the provided logging function.</p> <p>Parameters:</p> Name Type Description Default <code>pipe</code> <code>IO</code> <p>A file-like object for reading process output.</p> required <code>logger_function</code> <code>function</code> <p>A logging function from the logger.</p> required Source code in <code>prefect/cli/shell.py</code> <pre><code>def output_stream(pipe, logger_function):\n    \"\"\"\n    Read from a pipe line by line and log using the provided logging function.\n\n    Args:\n        pipe (IO): A file-like object for reading process output.\n        logger_function (function): A logging function from the logger.\n    \"\"\"\n    with pipe:\n        for line in iter(pipe.readline, \"\"):\n            logger_function(line.strip())\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.run_shell_process","title":"<code>run_shell_process</code>","text":"<p>Asynchronously executes the specified shell command and logs its output.</p> <p>This function is designed to be used within Prefect flows to run shell commands as part of task execution. It handles both the execution of the command and the collection of its output for logging purposes.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command to execute.</p> required <code>log_output</code> <code>bool</code> <p>If True, the output of the command (both stdout and stderr) is logged to Prefect.                          Defaults to True</p> <code>True</code> <code>stream_stdout</code> <code>bool</code> <p>If True, the stdout of the command is streamed to Prefect logs. Defaults to False.</p> <code>False</code> <code>log_stderr</code> <code>bool</code> <p>If True, the stderr of the command is logged to Prefect logs. Defaults to False.</p> <code>False</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@flow\ndef run_shell_process(\n    command: str,\n    log_output: bool = True,\n    stream_stdout: bool = False,\n    log_stderr: bool = False,\n):\n    \"\"\"\n    Asynchronously executes the specified shell command and logs its output.\n\n    This function is designed to be used within Prefect flows to run shell commands as part of task execution.\n    It handles both the execution of the command and the collection of its output for logging purposes.\n\n    Args:\n        command (str): The shell command to execute.\n        log_output (bool, optional): If True, the output of the command (both stdout and stderr) is logged to Prefect.\n                                     Defaults to True\n        stream_stdout (bool, optional): If True, the stdout of the command is streamed to Prefect logs. Defaults to False.\n        log_stderr (bool, optional): If True, the stderr of the command is logged to Prefect logs. Defaults to False.\n\n\n    \"\"\"\n\n    logger = get_run_logger() if log_output else logging.getLogger(\"prefect\")\n\n    # Containers for log batching\n    stdout_container, stderr_container = [], []\n    with subprocess.Popen(\n        command,\n        stdout=subprocess.PIPE,\n        stderr=subprocess.PIPE,\n        shell=True,\n        text=True,\n        bufsize=1,\n        universal_newlines=True,\n    ) as proc:\n        # Create threads for collecting stdout and stderr\n        if stream_stdout:\n            stdout_logger = logger.info\n            output = output_stream\n        else:\n            stdout_logger = stdout_container\n            output = output_collect\n\n        stdout_thread = threading.Thread(\n            target=output, args=(proc.stdout, stdout_logger)\n        )\n\n        stderr_thread = threading.Thread(\n            target=output_collect, args=(proc.stderr, stderr_container)\n        )\n\n        stdout_thread.start()\n        stderr_thread.start()\n\n        stdout_thread.join()\n        stderr_thread.join()\n\n        proc.wait()\n        if stdout_container:\n            logger.info(\"\".join(stdout_container).strip())\n\n        if stderr_container and log_stderr:\n            logger.error(\"\".join(stderr_container).strip())\n            # Suppress traceback\n        if proc.returncode != 0:\n            logger.error(\"\".join(stderr_container).strip())\n            sys.tracebacklimit = 0\n            raise FailedRun(f\"Command failed with exit code {proc.returncode}\")\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.</p> <p>This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs, setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command the flow will execute.</p> required <code>name</code> <code>str</code> <p>The name assigned to the flow. This is required..</p> required <code>deployment_tags</code> <code>List[str]</code> <p>Optional tags for the deployment to facilitate filtering and organization.</p> <code>Option(None, '--tag', help='Tag for the deployment (can be provided multiple times)')</code> <code>log_output</code> <code>bool</code> <p>If True, streams the output of the shell command to the Prefect logs. Defaults to True.</p> <code>Option(True, help='Stream the output of the command', hidden=True)</code> <code>cron_schedule</code> <code>str</code> <p>A cron expression that defines when the flow will run. If not provided, the flow can be triggered manually.</p> <code>Option(None, help='Cron schedule for the flow')</code> <code>timezone</code> <code>str</code> <p>The timezone for the cron schedule. This is important if the schedule should align with local time.</p> <code>Option(None, help='Timezone for the schedule')</code> <code>concurrency_limit</code> <code>int</code> <p>The maximum number of instances of the flow that can run simultaneously.</p> <code>Option(None, min=1, help='The maximum number of flow runs that can execute at the same time')</code> <code>deployment_name</code> <code>str</code> <p>The name of the deployment. This helps distinguish deployments within the Prefect platform.</p> <code>Option('CLI Runner Deployment', help='Name of the deployment')</code> <code>run_once</code> <code>bool</code> <p>When True, the flow will only run once upon deployment initiation, rather than continuously.</p> <code>Option(False, help='Run the agent loop once, instead of forever.')</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@shell_app.command(\"serve\")\nasync def serve(\n    command: str,\n    flow_name: str = typer.Option(..., help=\"Name of the flow\"),\n    deployment_name: str = typer.Option(\n        \"CLI Runner Deployment\", help=\"Name of the deployment\"\n    ),\n    deployment_tags: List[str] = typer.Option(\n        None, \"--tag\", help=\"Tag for the deployment (can be provided multiple times)\"\n    ),\n    log_output: bool = typer.Option(\n        True, help=\"Stream the output of the command\", hidden=True\n    ),\n    stream_stdout: bool = typer.Option(True, help=\"Stream the output of the command\"),\n    cron_schedule: str = typer.Option(None, help=\"Cron schedule for the flow\"),\n    timezone: str = typer.Option(None, help=\"Timezone for the schedule\"),\n    concurrency_limit: int = typer.Option(\n        None,\n        min=1,\n        help=\"The maximum number of flow runs that can execute at the same time\",\n    ),\n    run_once: bool = typer.Option(\n        False, help=\"Run the agent loop once, instead of forever.\"\n    ),\n):\n    \"\"\"\n    Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.\n\n    This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for\n    scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for\n    easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs,\n    setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.\n\n    Args:\n        command (str): The shell command the flow will execute.\n        name (str): The name assigned to the flow. This is required..\n        deployment_tags (List[str], optional): Optional tags for the deployment to facilitate filtering and organization.\n        log_output (bool, optional): If True, streams the output of the shell command to the Prefect logs. Defaults to True.\n        cron_schedule (str, optional): A cron expression that defines when the flow will run. If not provided, the flow can be triggered manually.\n        timezone (str, optional): The timezone for the cron schedule. This is important if the schedule should align with local time.\n        concurrency_limit (int, optional): The maximum number of instances of the flow that can run simultaneously.\n        deployment_name (str, optional): The name of the deployment. This helps distinguish deployments within the Prefect platform.\n        run_once (bool, optional): When True, the flow will only run once upon deployment initiation, rather than continuously.\n    \"\"\"\n    schedule = (\n        CronSchedule(cron=cron_schedule, timezone=timezone) if cron_schedule else None\n    )\n    defined_flow = run_shell_process.with_options(name=flow_name)\n\n    runner_deployment = await defined_flow.to_deployment(\n        name=deployment_name,\n        parameters={\n            \"command\": command,\n            \"log_output\": log_output,\n            \"stream_stdout\": stream_stdout,\n        },\n        entrypoint_type=EntrypointType.MODULE_PATH,\n        schedule=schedule,\n        tags=(deployment_tags or []) + [\"shell\"],\n    )\n\n    runner = Runner(name=flow_name)\n    deployment_id = await runner.add_deployment(runner_deployment)\n    help_message = (\n        f\"[green]Your flow {runner_deployment.flow_name!r} is being served and polling\"\n        \" for scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the following\"\n        \" command:\\n[blue]\\n\\t$ prefect deployment run\"\n        f\" '{runner_deployment.flow_name}/{deployment_name}'\\n[/]\"\n    )\n    if PREFECT_UI_URL:\n        help_message += (\n            \"\\nYou can also run your flow via the Prefect UI:\"\n            f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n        )\n\n    app.console.print(help_message, soft_wrap=True)\n    await runner.start(run_once=run_once)\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.watch","title":"<code>watch</code>  <code>async</code>","text":"<p>Executes a shell command and observes it as Prefect flow.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command to be executed.</p> required <code>log_output</code> <code>bool</code> <p>If True, logs the command's output. Defaults to True.</p> <code>Option(True, help='Log the output of the command to Prefect logs.')</code> <code>flow_run_name</code> <code>str</code> <p>An optional name for the flow run.</p> <code>Option(None, help='Name of the flow run.')</code> <code>flow_name</code> <code>str</code> <p>An optional name for the flow. Useful for identification in the Prefect UI.</p> <code>Option('Shell Command', help='Name of the flow.')</code> <code>tag</code> <code>List[str]</code> <p>An optional list of tags for categorizing and filtering flows in the Prefect UI.</p> <code>None</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@shell_app.command(\"watch\")\nasync def watch(\n    command: str,\n    log_output: bool = typer.Option(\n        True, help=\"Log the output of the command to Prefect logs.\"\n    ),\n    flow_run_name: str = typer.Option(None, help=\"Name of the flow run.\"),\n    flow_name: str = typer.Option(\"Shell Command\", help=\"Name of the flow.\"),\n    stream_stdout: bool = typer.Option(True, help=\"Stream the output of the command.\"),\n    tag: Annotated[\n        Optional[List[str]], typer.Option(help=\"Optional tags for the flow run.\")\n    ] = None,\n):\n    \"\"\"\n    Executes a shell command and observes it as Prefect flow.\n\n    Args:\n        command (str): The shell command to be executed.\n        log_output (bool, optional): If True, logs the command's output. Defaults to True.\n        flow_run_name (str, optional): An optional name for the flow run.\n        flow_name (str, optional): An optional name for the flow. Useful for identification in the Prefect UI.\n        tag (List[str], optional): An optional list of tags for categorizing and filtering flows in the Prefect UI.\n    \"\"\"\n    tag = (tag or []) + [\"shell\"]\n\n    # Call the shell_run_command flow with provided arguments\n    defined_flow = run_shell_process.with_options(\n        name=flow_name, flow_run_name=flow_run_name\n    )\n    with tags(*tag):\n        defined_flow(\n            command=command, log_output=log_output, stream_stdout=stream_stdout\n        )\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/variable/","title":"variable","text":"","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable","title":"<code>prefect.cli.variable</code>","text":"","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a variable.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the variable to delete</p> required Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"delete\")\nasync def delete(\n    name: str,\n):\n    \"\"\"\n    Delete a variable.\n\n    Arguments:\n        name: the name of the variable to delete\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.delete_variable_by_name(\n                name=name,\n            )\n        except ObjectNotFound:\n            exit_with_error(f\"Variable {name!r} not found.\")\n\n        exit_with_success(f\"Deleted variable {name!r}.\")\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a variable.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the variable to inspect</p> required Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"inspect\")\nasync def inspect(\n    name: str,\n):\n    \"\"\"\n    View details about a variable.\n\n    Arguments:\n        name: the name of the variable to inspect\n    \"\"\"\n\n    async with get_client() as client:\n        variable = await client.read_variable_by_name(\n            name=name,\n        )\n        if not variable:\n            exit_with_error(f\"Variable {name!r} not found.\")\n\n        app.console.print(Pretty(variable))\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.list_variables","title":"<code>list_variables</code>  <code>async</code>","text":"<p>List variables.</p> Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"ls\")\nasync def list_variables(\n    limit: int = typer.Option(\n        100,\n        \"--limit\",\n        help=\"The maximum number of variables to return.\",\n    ),\n):\n    \"\"\"\n    List variables.\n    \"\"\"\n    async with get_client() as client:\n        variables = await client.read_variables(\n            limit=limit,\n        )\n\n        table = Table(\n            title=\"Variables\",\n            caption=\"List Variables using `prefect variable ls`\",\n            show_header=True,\n        )\n\n        table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n        # values can be up 5000 characters so truncate early\n        table.add_column(\"Value\", style=\"blue\", no_wrap=True, max_width=50)\n        table.add_column(\"Created\", style=\"blue\", no_wrap=True)\n        table.add_column(\"Updated\", style=\"blue\", no_wrap=True)\n\n        for variable in sorted(variables, key=lambda x: f\"{x.name}\"):\n            table.add_row(\n                variable.name,\n                variable.value,\n                pendulum.instance(variable.created).diff_for_humans(),\n                pendulum.instance(variable.updated).diff_for_humans(),\n            )\n\n        app.console.print(table)\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/work_pool/","title":"work_pool","text":"","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool","title":"<code>prefect.cli.work_pool</code>","text":"<p>Command line interface for working with work queues.</p>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.clear_concurrency_limit","title":"<code>clear_concurrency_limit</code>  <code>async</code>","text":"<p>Clear the concurrency limit for a work pool.</p> <p>\b Examples:     $ prefect work-pool clear-concurrency-limit \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def clear_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n):\n    \"\"\"\n    Clear the concurrency limit for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool clear-concurrency-limit \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    concurrency_limit=None,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Cleared concurrency limit for work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new work pool or update an existing one.</p> <p>\b Examples:     \b     Create a Kubernetes work pool in a paused state:         \b         $ prefect work-pool create \"my-pool\" --type kubernetes --paused     \b     Create a Docker work pool with a custom base job template:         \b         $ prefect work-pool create \"my-pool\" --type docker --base-job-template ./base-job-template.json     \b     Update an existing work pool:         \b         $ prefect work-pool create \"existing-pool\" --base-job-template ./base-job-template.json --overwrite</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def create(\n    name: str = typer.Argument(..., help=\"The name of the work pool.\"),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type.\"\n        ),\n    ),\n    paused: bool = typer.Option(\n        False,\n        \"--paused\",\n        help=\"Whether or not to create the work pool in a paused state.\",\n    ),\n    type: str = typer.Option(\n        None, \"-t\", \"--type\", help=\"The type of work pool to create.\"\n    ),\n    set_as_default: bool = typer.Option(\n        False,\n        \"--set-as-default\",\n        help=(\n            \"Whether or not to use the created work pool as the local default for\"\n            \" deployment.\"\n        ),\n    ),\n    provision_infrastructure: bool = typer.Option(\n        False,\n        \"--provision-infrastructure\",\n        \"--provision-infra\",\n        help=(\n            \"Whether or not to provision infrastructure for the work pool if supported\"\n            \" for the given work pool type.\"\n        ),\n    ),\n    overwrite: bool = typer.Option(\n        False,\n        \"--overwrite\",\n        help=(\"Whether or not to overwrite an existing work pool with the same name.\"),\n    ),\n):\n    \"\"\"\n    Create a new work pool or update an existing one.\n\n    \\b\n    Examples:\n        \\b\n        Create a Kubernetes work pool in a paused state:\n            \\b\n            $ prefect work-pool create \"my-pool\" --type kubernetes --paused\n        \\b\n        Create a Docker work pool with a custom base job template:\n            \\b\n            $ prefect work-pool create \"my-pool\" --type docker --base-job-template ./base-job-template.json\n        \\b\n        Update an existing work pool:\n            \\b\n            $ prefect work-pool create \"existing-pool\" --base-job-template ./base-job-template.json --overwrite\n\n    \"\"\"\n    if not name.lower().strip(\"'\\\" \"):\n        exit_with_error(\"Work pool name cannot be empty.\")\n    async with get_client() as client:\n        try:\n            existing_pool = await client.read_work_pool(work_pool_name=name)\n            if not overwrite:\n                exit_with_error(\n                    f\"Work pool named {name!r} already exists. Use --overwrite to update it.\"\n                )\n        except ObjectNotFound:\n            existing_pool = None\n\n        if type is None and existing_pool is None:\n            async with get_collections_metadata_client() as collections_client:\n                if not is_interactive():\n                    exit_with_error(\n                        \"When not using an interactive terminal, you must supply a\"\n                        \" `--type` value.\"\n                    )\n                worker_metadata = await collections_client.read_worker_metadata()\n\n                # Retrieve only push pools if provisioning infrastructure\n                data = [\n                    worker\n                    for collection in worker_metadata.values()\n                    for worker in collection.values()\n                    if provision_infrastructure\n                    and has_provisioner_for_type(worker[\"type\"])\n                    or not provision_infrastructure\n                ]\n                worker = prompt_select_from_table(\n                    app.console,\n                    \"What type of work pool infrastructure would you like to use?\",\n                    columns=[\n                        {\"header\": \"Infrastructure Type\", \"key\": \"display_name\"},\n                        {\"header\": \"Description\", \"key\": \"description\"},\n                    ],\n                    data=data,\n                    table_kwargs={\"show_lines\": True},\n                )\n                type = worker[\"type\"]\n        elif existing_pool:\n            type = existing_pool.type\n\n        available_work_pool_types = await get_available_work_pool_types()\n        if type not in available_work_pool_types:\n            exit_with_error(\n                f\"Unknown work pool type {type!r}. \"\n                \"Please choose from\"\n                f\" {', '.join(available_work_pool_types)}.\"\n            )\n\n        if base_job_template is None:\n            template_contents = (\n                await get_default_base_job_template_for_infrastructure_type(type)\n            )\n        else:\n            template_contents = json.load(base_job_template)\n\n        if provision_infrastructure:\n            try:\n                provisioner = get_infrastructure_provisioner_for_work_pool_type(type)\n                provisioner.console = app.console\n                template_contents = await provisioner.provision(\n                    work_pool_name=name, base_job_template=template_contents\n                )\n            except ValueError as exc:\n                print(exc)\n                app.console.print(\n                    (\n                        \"Automatic infrastructure provisioning is not supported for\"\n                        f\" {type!r} work pools.\"\n                    ),\n                    style=\"yellow\",\n                )\n            except RuntimeError as exc:\n                exit_with_error(f\"Failed to provision infrastructure: {exc}\")\n\n        try:\n            wp = WorkPoolCreate(\n                name=name,\n                type=type,\n                base_job_template=template_contents,\n                is_paused=paused,\n            )\n            work_pool = await client.create_work_pool(work_pool=wp, overwrite=overwrite)\n            action = \"Updated\" if overwrite and existing_pool else \"Created\"\n            app.console.print(\n                f\"{action} work pool {work_pool.name!r}!\\n\", style=\"green\"\n            )\n            if (\n                not work_pool.is_paused\n                and not work_pool.is_managed_pool\n                and not work_pool.is_push_pool\n            ):\n                app.console.print(\"To start a worker for this work pool, run:\\n\")\n                app.console.print(\n                    f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\"\n                )\n            if set_as_default:\n                set_work_pool_as_default(work_pool.name)\n\n            url = (\n                f\"{PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n                if PREFECT_UI_URL\n                else None\n            )\n            pool_url = url if url else \"&lt;no dashboard available&gt;\"\n\n            app.console.print(\n                textwrap.dedent(\n                    f\"\"\"\n                \u2514\u2500\u2500 UUID: {work_pool.id}\n                \u2514\u2500\u2500 Type: {work_pool.type}\n                \u2514\u2500\u2500 Description: {work_pool.description}\n                {\"\u2514\u2500\u2500 Status: \" + work_pool.status.display_name if work_pool.status else \"\"}\n                \u2514\u2500\u2500 URL: {pool_url}\n                \"\"\"\n                ).strip(),\n                soft_wrap=True,\n            )\n            exit_with_success(\"\")\n        except ObjectAlreadyExists:\n            exit_with_error(\n                f\"Work pool named {name!r} already exists. Please use --overwrite to update it.\"\n            )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a work pool.</p> <p>\b Examples:     $ prefect work-pool delete \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def delete(\n    name: str = typer.Argument(..., help=\"The name of the work pool to delete.\"),\n):\n    \"\"\"\n    Delete a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool delete \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.delete_work_pool(work_pool_name=name)\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Deleted work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.get_default_base_job_template","title":"<code>get_default_base_job_template</code>  <code>async</code>","text":"<p>Get the default base job template for a given work pool type.</p> <p>\b Examples:     $ prefect work-pool get-default-base-job-template --type kubernetes</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def get_default_base_job_template(\n    type: str = typer.Option(\n        None,\n        \"-t\",\n        \"--type\",\n        help=\"The type of work pool for which to get the default base job template.\",\n    ),\n    file: str = typer.Option(\n        None, \"-f\", \"--file\", help=\"If set, write the output to a file.\"\n    ),\n):\n    \"\"\"\n    Get the default base job template for a given work pool type.\n\n    \\b\n    Examples:\n        $ prefect work-pool get-default-base-job-template --type kubernetes\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        type\n    )\n    if base_job_template is None:\n        exit_with_error(\n            f\"Unknown work pool type {type!r}. \"\n            \"Please choose from\"\n            f\" {', '.join(await get_available_work_pool_types())}.\"\n        )\n\n    if file is None:\n        print(json.dumps(base_job_template, indent=2))\n    else:\n        with open(file, mode=\"w\") as f:\n            json.dump(base_job_template, fp=f, indent=2)\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.has_provisioner_for_type","title":"<code>has_provisioner_for_type</code>","text":"<p>Check if there is a provisioner for the given work pool type.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_type</code> <code>str</code> <p>The type of the work pool.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a provisioner exists for the given type, False otherwise.</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>def has_provisioner_for_type(work_pool_type: str) -&gt; bool:\n    \"\"\"\n    Check if there is a provisioner for the given work pool type.\n\n    Args:\n        work_pool_type (str): The type of the work pool.\n\n    Returns:\n        bool: True if a provisioner exists for the given type, False otherwise.\n    \"\"\"\n    return work_pool_type in _provisioners\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>Inspect a work pool.</p> <p>\b Examples:     $ prefect work-pool inspect \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def inspect(\n    name: str = typer.Argument(..., help=\"The name of the work pool to inspect.\"),\n):\n    \"\"\"\n    Inspect a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool inspect \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            pool = await client.read_work_pool(work_pool_name=name)\n            app.console.print(Pretty(pool))\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool {name!r} not found!\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>List work pools.</p> <p>\b Examples:     $ prefect work-pool ls</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def ls(\n    verbose: bool = typer.Option(\n        False,\n        \"--verbose\",\n        \"-v\",\n        help=\"Show additional information about work pools.\",\n    ),\n):\n    \"\"\"\n    List work pools.\n\n    \\b\n    Examples:\n        $ prefect work-pool ls\n    \"\"\"\n    table = Table(\n        title=\"Work Pools\", caption=\"(**) denotes a paused pool\", caption_style=\"red\"\n    )\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Type\", style=\"magenta\", no_wrap=True)\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    if verbose:\n        table.add_column(\"Base Job Template\", style=\"magenta\", no_wrap=True)\n\n    async with get_client() as client:\n        pools = await client.read_work_pools()\n\n    def sort_by_created_key(q):\n        return pendulum.now(\"utc\") - q.created\n\n    for pool in sorted(pools, key=sort_by_created_key):\n        row = [\n            f\"{pool.name} [red](**)\" if pool.is_paused else pool.name,\n            str(pool.type),\n            str(pool.id),\n            (\n                f\"[red]{pool.concurrency_limit}\"\n                if pool.concurrency_limit is not None\n                else \"[blue]None\"\n            ),\n        ]\n        if verbose:\n            row.append(str(pool.base_job_template))\n        table.add_row(*row)\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.pause","title":"<code>pause</code>  <code>async</code>","text":"<p>Pause a work pool.</p> <p>\b Examples:     $ prefect work-pool pause \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def pause(\n    name: str = typer.Argument(..., help=\"The name of the work pool to pause.\"),\n):\n    \"\"\"\n    Pause a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool pause \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    is_paused=True,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Paused work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.preview","title":"<code>preview</code>  <code>async</code>","text":"<p>Preview the work pool's scheduled work for all queues.</p> <p>\b Examples:     $ prefect work-pool preview \"my-pool\" --hours 24</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def preview(\n    name: str = typer.Argument(None, help=\"The name or ID of the work pool to preview\"),\n    hours: int = typer.Option(\n        None,\n        \"-h\",\n        \"--hours\",\n        help=\"The number of hours to look ahead; defaults to 1 hour\",\n    ),\n):\n    \"\"\"\n    Preview the work pool's scheduled work for all queues.\n\n    \\b\n    Examples:\n        $ prefect work-pool preview \"my-pool\" --hours 24\n\n    \"\"\"\n    if hours is None:\n        hours = 1\n\n    async with get_client() as client:\n        try:\n            responses = await client.get_scheduled_flow_runs_for_work_pool(\n                work_pool_name=name,\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n    runs = [response.flow_run for response in responses]\n    table = Table(caption=\"(**) denotes a late run\", caption_style=\"red\")\n\n    table.add_column(\n        \"Scheduled Start Time\", justify=\"left\", style=\"yellow\", no_wrap=True\n    )\n    table.add_column(\"Run ID\", justify=\"left\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Deployment ID\", style=\"blue\", no_wrap=True)\n\n    pendulum.now(\"utc\").add(hours=hours or 1)\n\n    now = pendulum.now(\"utc\")\n\n    def sort_by_created_key(r):\n        return now - r.created\n\n    for run in sorted(runs, key=sort_by_created_key):\n        table.add_row(\n            (\n                f\"{run.expected_start_time} [red](**)\"\n                if run.expected_start_time &lt; now\n                else f\"{run.expected_start_time}\"\n            ),\n            str(run.id),\n            run.name,\n            str(run.deployment_id),\n        )\n\n    if runs:\n        app.console.print(table)\n    else:\n        app.console.print(\n            (\n                \"No runs found - try increasing how far into the future you preview\"\n                \" with the --hours flag\"\n            ),\n            style=\"yellow\",\n        )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.provision_infrastructure","title":"<code>provision_infrastructure</code>  <code>async</code>","text":"<p>Provision infrastructure for a work pool.</p> <p>\b Examples:     $ prefect work-pool provision-infrastructure \"my-pool\"</p> <pre><code>$ prefect work-pool provision-infra \"my-pool\"\n</code></pre> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command(aliases=[\"provision-infra\"])\nasync def provision_infrastructure(\n    name: str = typer.Argument(\n        ..., help=\"The name of the work pool to provision infrastructure for.\"\n    ),\n):\n    \"\"\"\n    Provision infrastructure for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool provision-infrastructure \"my-pool\"\n\n        $ prefect work-pool provision-infra \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            work_pool = await client.read_work_pool(work_pool_name=name)\n            if not work_pool.is_push_pool:\n                exit_with_error(\n                    f\"Work pool {name!r} is not a push pool type. \"\n                    \"Please try provisioning infrastructure for a push pool.\"\n                )\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool {name!r} does not exist.\")\n        except Exception as exc:\n            exit_with_error(f\"Failed to read work pool {name!r}: {exc}\")\n\n        try:\n            provisioner = get_infrastructure_provisioner_for_work_pool_type(\n                work_pool.type\n            )\n            provisioner.console = app.console\n            new_base_job_template = await provisioner.provision(\n                work_pool_name=name, base_job_template=work_pool.base_job_template\n            )\n\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    base_job_template=new_base_job_template,\n                ),\n            )\n\n        except ValueError as exc:\n            app.console.print(f\"Error: {exc}\")\n            app.console.print(\n                (\n                    \"Automatic infrastructure provisioning is not supported for\"\n                    f\" {work_pool.type!r} work pools.\"\n                ),\n                style=\"yellow\",\n            )\n        except RuntimeError as exc:\n            exit_with_error(\n                f\"Failed to provision infrastructure for '{name}' work pool: {exc}\"\n            )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.resume","title":"<code>resume</code>  <code>async</code>","text":"<p>Resume a work pool.</p> <p>\b Examples:     $ prefect work-pool resume \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def resume(\n    name: str = typer.Argument(..., help=\"The name of the work pool to resume.\"),\n):\n    \"\"\"\n    Resume a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool resume \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    is_paused=False,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Resumed work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.set_concurrency_limit","title":"<code>set_concurrency_limit</code>  <code>async</code>","text":"<p>Set the concurrency limit for a work pool.</p> <p>\b Examples:     $ prefect work-pool set-concurrency-limit \"my-pool\" 10</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def set_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n    concurrency_limit: int = typer.Argument(\n        ..., help=\"The new concurrency limit for the work pool.\"\n    ),\n):\n    \"\"\"\n    Set the concurrency limit for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool set-concurrency-limit \"my-pool\" 10\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    concurrency_limit=concurrency_limit,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(\n            f\"Set concurrency limit for work pool {name!r} to {concurrency_limit}\"\n        )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.update","title":"<code>update</code>  <code>async</code>","text":"<p>Update a work pool.</p> <p>\b Examples:     $ prefect work-pool update \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def update(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type. If None, the base job template will not be modified.\"\n        ),\n    ),\n    concurrency_limit: int = typer.Option(\n        None,\n        \"--concurrency-limit\",\n        help=(\n            \"The concurrency limit for the work pool. If None, the concurrency limit\"\n            \" will not be modified.\"\n        ),\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        help=(\n            \"The description for the work pool. If None, the description will not be\"\n            \" modified.\"\n        ),\n    ),\n):\n    \"\"\"\n    Update a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool update \"my-pool\"\n\n    \"\"\"\n    wp = WorkPoolUpdate()\n    if base_job_template:\n        wp.base_job_template = json.load(base_job_template)\n    if concurrency_limit:\n        wp.concurrency_limit = concurrency_limit\n    if description:\n        wp.description = description\n\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=wp,\n            )\n        except ObjectNotFound:\n            exit_with_error(\"Work pool named {name!r} does not exist.\")\n\n        exit_with_success(f\"Updated work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_queue/","title":"work_queue","text":"","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue","title":"<code>prefect.cli.work_queue</code>","text":"<p>Command line interface for working with work queues.</p>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.clear_concurrency_limit","title":"<code>clear_concurrency_limit</code>  <code>async</code>","text":"<p>Clear any concurrency limits from a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def clear_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to clear\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Clear any concurrency limits from a work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                concurrency_limit=None,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = (\n            f\"Concurrency limits removed on work queue {name!r} in work pool {pool!r}\"\n        )\n    else:\n        success_message = f\"Concurrency limits removed on work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def create(\n    name: str = typer.Argument(..., help=\"The unique name to assign this work queue\"),\n    limit: int = typer.Option(\n        None, \"-l\", \"--limit\", help=\"The concurrency limit to set on the queue.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"DEPRECATED: One or more optional tags. This option will be removed on\"\n            \" 2023-02-23.\"\n        ),\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool to create the work queue in.\",\n    ),\n    priority: Optional[int] = typer.Option(\n        None,\n        \"-q\",\n        \"--priority\",\n        help=\"The associated priority for the created work queue\",\n    ),\n):\n    \"\"\"\n    Create a work queue.\n    \"\"\"\n    if tags:\n        app.console.print(\n            (\n                \"Supplying `tags` for work queues is deprecated. This work \"\n                \"queue will use legacy tag-matching behavior. \"\n                \"This option will be removed on 2023-02-23.\"\n            ),\n            style=\"red\",\n        )\n\n    if pool and tags:\n        exit_with_error(\n            \"Work queues created with tags cannot specify work pools or set priorities.\"\n        )\n\n    async with get_client() as client:\n        try:\n            result = await client.create_work_queue(\n                name=name, tags=tags or None, work_pool_name=pool, priority=priority\n            )\n            if limit is not None:\n                await client.update_work_queue(\n                    id=result.id,\n                    concurrency_limit=limit,\n                )\n        except ObjectAlreadyExists:\n            exit_with_error(f\"Work queue with name: {name!r} already exists.\")\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool with name: {pool!r} not found.\")\n\n    if tags:\n        tags_message = f\"tags - {', '.join(sorted(tags))}\\n\" or \"\"\n        output_msg = dedent(\n            f\"\"\"\n            Created work queue with properties:\n                name - {name!r}\n                id - {result.id}\n                concurrency limit - {limit}\n                {tags_message}\n            Start an agent to pick up flow runs from the work queue:\n                prefect agent start -q '{result.name}'\n\n            Inspect the work queue:\n                prefect work-queue inspect '{result.name}'\n            \"\"\"\n        )\n    else:\n        if not pool:\n            # specify the default work pool name after work queue creation to allow the server\n            # to handle a bunch of logic associated with agents without work pools\n            pool = DEFAULT_AGENT_WORK_POOL_NAME\n        output_msg = dedent(\n            f\"\"\"\n            Created work queue with properties:\n                name - {name!r}\n                work pool - {pool!r}\n                id - {result.id}\n                concurrency limit - {limit}\n            Start an agent to pick up flow runs from the work queue:\n                prefect agent start -q '{result.name} -p {pool}'\n\n            Inspect the work queue:\n                prefect work-queue inspect '{result.name}'\n            \"\"\"\n        )\n    exit_with_success(output_msg)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a work queue by ID.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def delete(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to delete\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queue to delete.\",\n    ),\n):\n    \"\"\"\n    Delete a work queue by ID.\n    \"\"\"\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            await client.delete_work_queue_by_id(id=queue_id)\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n    if pool:\n        success_message = (\n            f\"Successfully deleted work queue {name!r} in work pool {pool!r}\"\n        )\n    else:\n        success_message = f\"Successfully deleted work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>Inspect a work queue by ID.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def inspect(\n    name: str = typer.Argument(\n        None, help=\"The name or ID of the work queue to inspect\"\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Inspect a work queue by ID.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            result = await client.read_work_queue(id=queue_id)\n            app.console.print(Pretty(result))\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n        try:\n            status = await client.read_work_queue_status(id=queue_id)\n            app.console.print(Pretty(status))\n        except ObjectNotFound:\n            pass\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all work queues.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def ls(\n    verbose: bool = typer.Option(\n        False, \"--verbose\", \"-v\", help=\"Display more information.\"\n    ),\n    work_queue_prefix: str = typer.Option(\n        None,\n        \"--match\",\n        \"-m\",\n        help=(\n            \"Will match work queues with names that start with the specified prefix\"\n            \" string\"\n        ),\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queues to list.\",\n    ),\n):\n    \"\"\"\n    View all work queues.\n    \"\"\"\n    if not pool and not experiment_enabled(\"work_pools\"):\n        table = Table(\n            title=\"Work Queues\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Filter (Deprecated)\", style=\"magenta\", no_wrap=True)\n\n        async with get_client() as client:\n            if work_queue_prefix is not None:\n                queues = await client.match_work_queues([work_queue_prefix])\n            else:\n                queues = await client.read_work_queues()\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    str(queue.id),\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose and queue.filter is not None:\n                    row.append(queue.filter.json())\n                table.add_row(*row)\n    elif not pool:\n        table = Table(\n            title=\"Work Queues\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"Pool\", style=\"magenta\", no_wrap=True)\n        table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Filter (Deprecated)\", style=\"magenta\", no_wrap=True)\n\n        async with get_client() as client:\n            if work_queue_prefix is not None:\n                queues = await client.match_work_queues([work_queue_prefix])\n            else:\n                queues = await client.read_work_queues()\n\n            pool_ids = [q.work_pool_id for q in queues]\n            wp_filter = WorkPoolFilter(id=WorkPoolFilterId(any_=pool_ids))\n            pools = await client.read_work_pools(work_pool_filter=wp_filter)\n            pool_id_name_map = {p.id: p.name for p in pools}\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    pool_id_name_map[queue.work_pool_id],\n                    str(queue.id),\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose and queue.filter is not None:\n                    row.append(queue.filter.json())\n                table.add_row(*row)\n\n    else:\n        table = Table(\n            title=f\"Work Queues in Work Pool {pool!r}\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"Priority\", style=\"magenta\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Description\", style=\"cyan\", no_wrap=False)\n\n        async with get_client() as client:\n            try:\n                queues = await client.read_work_queues(work_pool_name=pool)\n            except ObjectNotFound:\n                exit_with_error(f\"No work pool found: {pool!r}\")\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    f\"{queue.priority}\",\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose:\n                    row.append(queue.description)\n                table.add_row(*row)\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.pause","title":"<code>pause</code>  <code>async</code>","text":"<p>Pause a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def pause(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to pause\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Pause a work queue.\n    \"\"\"\n\n    if not pool and not typer.confirm(\n        f\"You have not specified a work pool. Are you sure you want to pause {name} work queue in `{DEFAULT_AGENT_WORK_POOL_NAME}`?\"\n    ):\n        exit_with_error(\"Work queue pause aborted!\")\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                is_paused=True,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = f\"Work queue {name!r} in work pool {pool!r} paused\"\n    else:\n        success_message = f\"Work queue {name!r} paused\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.preview","title":"<code>preview</code>  <code>async</code>","text":"<p>Preview a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def preview(\n    name: str = typer.Argument(\n        None, help=\"The name or ID of the work queue to preview\"\n    ),\n    hours: int = typer.Option(\n        None,\n        \"-h\",\n        \"--hours\",\n        help=\"The number of hours to look ahead; defaults to 1 hour\",\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Preview a work queue.\n    \"\"\"\n    if pool:\n        title = f\"Preview of Work Queue {name!r} in Work Pool {pool!r}\"\n    else:\n        title = f\"Preview of Work Queue {name!r}\"\n\n    table = Table(title=title, caption=\"(**) denotes a late run\", caption_style=\"red\")\n    table.add_column(\n        \"Scheduled Start Time\", justify=\"left\", style=\"yellow\", no_wrap=True\n    )\n    table.add_column(\"Run ID\", justify=\"left\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Deployment ID\", style=\"blue\", no_wrap=True)\n\n    window = pendulum.now(\"utc\").add(hours=hours or 1)\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name, work_pool_name=pool\n    )\n    async with get_client() as client:\n        if pool:\n            try:\n                responses = await client.get_scheduled_flow_runs_for_work_pool(\n                    work_pool_name=pool,\n                    work_queue_names=[name],\n                )\n                runs = [response.flow_run for response in responses]\n            except ObjectNotFound:\n                exit_with_error(f\"No work queue found: {name!r} in work pool {pool!r}\")\n        else:\n            try:\n                runs = await client.get_runs_in_work_queue(\n                    queue_id,\n                    limit=10,\n                    scheduled_before=window,\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"No work queue found: {name!r}\")\n    now = pendulum.now(\"utc\")\n\n    def sort_by_created_key(r):\n        return now - r.created\n\n    for run in sorted(runs, key=sort_by_created_key):\n        table.add_row(\n            (\n                f\"{run.expected_start_time} [red](**)\"\n                if run.expected_start_time &lt; now\n                else f\"{run.expected_start_time}\"\n            ),\n            str(run.id),\n            run.name,\n            str(run.deployment_id),\n        )\n\n    if runs:\n        app.console.print(table)\n    else:\n        app.console.print(\n            (\n                \"No runs found - try increasing how far into the future you preview\"\n                \" with the --hours flag\"\n            ),\n            style=\"yellow\",\n        )\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.read_wq_runs","title":"<code>read_wq_runs</code>  <code>async</code>","text":"<p>Get runs in a work queue. Note that this will trigger an artificial poll of the work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command(\"read-runs\")\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def read_wq_runs(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to poll\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queue to poll.\",\n    ),\n):\n    \"\"\"\n    Get runs in a work queue. Note that this will trigger an artificial poll of\n    the work queue.\n    \"\"\"\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            runs = await client.get_runs_in_work_queue(id=queue_id)\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n    success_message = (\n        f\"Read {len(runs)} runs for work queue {name!r} in work pool {pool}: {runs}\"\n    )\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.resume","title":"<code>resume</code>  <code>async</code>","text":"<p>Resume a paused work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def resume(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to resume\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Resume a paused work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                is_paused=False,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = f\"Work queue {name!r} in work pool {pool!r} resumed\"\n    else:\n        success_message = f\"Work queue {name!r} resumed\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.set_concurrency_limit","title":"<code>set_concurrency_limit</code>  <code>async</code>","text":"<p>Set a concurrency limit on a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def set_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue\"),\n    limit: int = typer.Argument(..., help=\"The concurrency limit to set on the queue.\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Set a concurrency limit on a work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                concurrency_limit=limit,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = (\n                    f\"No work queue named {name!r} found in work pool {pool!r}.\"\n                )\n            else:\n                error_message = f\"No work queue named {name!r} found.\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = (\n            f\"Concurrency limit of {limit} set on work queue {name!r} in work pool\"\n            f\" {pool!r}\"\n        )\n    else:\n        success_message = f\"Concurrency limit of {limit} set on work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/worker/","title":"worker","text":"","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/cli/worker/#prefect.cli.worker","title":"<code>prefect.cli.worker</code>","text":"","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/cli/worker/#prefect.cli.worker.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start a worker process to poll a work pool for flow runs.</p> Source code in <code>prefect/cli/worker.py</code> <pre><code>@worker_app.command()\nasync def start(\n    worker_name: str = typer.Option(\n        None,\n        \"-n\",\n        \"--name\",\n        help=(\n            \"The name to give to the started worker. If not provided, a unique name\"\n            \" will be generated.\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        ...,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool the started worker should poll.\",\n        prompt=True,\n    ),\n    work_queues: List[str] = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"One or more work queue names for the worker to pull from. If not provided,\"\n            \" the worker will pull from all work queues in the work pool.\"\n        ),\n    ),\n    worker_type: Optional[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--type\",\n        help=(\n            \"The type of worker to start. If not provided, the worker type will be\"\n            \" inferred from the work pool.\"\n        ),\n    ),\n    prefetch_seconds: int = SettingsOption(\n        PREFECT_WORKER_PREFETCH_SECONDS,\n        help=\"Number of seconds to look into the future for scheduled flow runs.\",\n    ),\n    run_once: bool = typer.Option(\n        False, help=\"Only run worker polling once. By default, the worker runs forever.\"\n    ),\n    limit: int = typer.Option(\n        None,\n        \"-l\",\n        \"--limit\",\n        help=\"Maximum number of flow runs to start simultaneously.\",\n    ),\n    with_healthcheck: bool = typer.Option(\n        False, help=\"Start a healthcheck server for the worker.\"\n    ),\n    install_policy: InstallPolicy = typer.Option(\n        InstallPolicy.PROMPT.value,\n        \"--install-policy\",\n        help=\"Install policy to use workers from Prefect integration packages.\",\n        case_sensitive=False,\n    ),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type. If the work pool already exists, this will be ignored.\"\n        ),\n    ),\n):\n    \"\"\"\n    Start a worker process to poll a work pool for flow runs.\n    \"\"\"\n\n    is_paused = await _check_work_pool_paused(work_pool_name)\n    if is_paused:\n        app.console.print(\n            (\n                f\"The work pool {work_pool_name!r} is currently paused. This worker\"\n                \" will not execute any flow runs until the work pool is unpaused.\"\n            ),\n            style=\"yellow\",\n        )\n\n    is_queues_paused = await _check_work_queues_paused(\n        work_pool_name,\n        work_queues,\n    )\n    if is_queues_paused:\n        queue_scope = (\n            \"All work queues\" if not work_queues else \"Specified work queue(s)\"\n        )\n        app.console.print(\n            (\n                f\"{queue_scope} in the work pool {work_pool_name!r} are currently\"\n                \" paused. This worker will not execute any flow runs until the work\"\n                \" queues are unpaused.\"\n            ),\n            style=\"yellow\",\n        )\n\n    worker_cls = await _get_worker_class(worker_type, work_pool_name, install_policy)\n\n    if worker_cls is None:\n        exit_with_error(\n            \"Unable to start worker. Please ensure you have the necessary dependencies\"\n            \" installed to run your desired worker type.\"\n        )\n\n    worker_process_id = os.getpid()\n    setup_signal_handlers_worker(\n        worker_process_id, f\"the {worker_type} worker\", app.console.print\n    )\n\n    template_contents = None\n    if base_job_template is not None:\n        template_contents = json.load(fp=base_job_template)\n\n    async with worker_cls(\n        name=worker_name,\n        work_pool_name=work_pool_name,\n        work_queues=work_queues,\n        limit=limit,\n        prefetch_seconds=prefetch_seconds,\n        heartbeat_interval_seconds=PREFECT_WORKER_HEARTBEAT_SECONDS.value(),\n        base_job_template=template_contents,\n    ) as worker:\n        app.console.print(f\"Worker {worker.name!r} started!\", style=\"green\")\n        try:\n            async with anyio.create_task_group() as tg:\n                # wait for an initial heartbeat to configure the worker\n                await worker.sync_with_backend()\n                # schedule the scheduled flow run polling loop\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.get_and_submit_flow_runs,\n                        interval=PREFECT_WORKER_QUERY_SECONDS.value(),\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,  # Up to ~1 minute interval during backoff\n                    )\n                )\n                # schedule the sync loop\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.sync_with_backend,\n                        interval=worker.heartbeat_interval_seconds,\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.check_for_cancelled_flow_runs,\n                        interval=PREFECT_WORKER_QUERY_SECONDS.value() * 2,\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n\n                started_event = await worker._emit_worker_started_event()\n\n                # if --with-healthcheck was passed, start the healthcheck server\n                if with_healthcheck:\n                    # we'll start the ASGI server in a separate thread so that\n                    # uvicorn does not block the main thread\n                    server_thread = threading.Thread(\n                        name=\"healthcheck-server-thread\",\n                        target=partial(\n                            start_healthcheck_server,\n                            worker=worker,\n                            query_interval_seconds=PREFECT_WORKER_QUERY_SECONDS.value(),\n                        ),\n                        daemon=True,\n                    )\n                    server_thread.start()\n        except CancelledError:\n            logger.debug(\"Worker task group cancelled\")\n\n    await worker._emit_worker_stopped_event(started_event)\n    app.console.print(f\"Worker {worker.name!r} stopped!\")\n</code></pre>","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/client/base/","title":"base","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base","title":"<code>prefect.client.base</code>","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse","title":"<code>PrefectResponse</code>","text":"<p>               Bases: <code>Response</code></p> <p>A Prefect wrapper for the <code>httpx.Response</code> class.</p> <p>Provides more informative error messages.</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectResponse(httpx.Response):\n    \"\"\"\n    A Prefect wrapper for the `httpx.Response` class.\n\n    Provides more informative error messages.\n    \"\"\"\n\n    def raise_for_status(self) -&gt; None:\n        \"\"\"\n        Raise an exception if the response contains an HTTPStatusError.\n\n        The `PrefectHTTPStatusError` contains useful additional information that\n        is not contained in the `HTTPStatusError`.\n        \"\"\"\n        try:\n            return super().raise_for_status()\n        except HTTPStatusError as exc:\n            raise PrefectHTTPStatusError.from_httpx_error(exc) from exc.__cause__\n\n    @classmethod\n    def from_httpx_response(cls: Type[Self], response: httpx.Response) -&gt; Self:\n        \"\"\"\n        Create a `PrefectReponse` from an `httpx.Response`.\n\n        By changing the `__class__` attribute of the Response, we change the method\n        resolution order to look for methods defined in PrefectResponse, while leaving\n        everything else about the original Response instance intact.\n        \"\"\"\n        new_response = copy.copy(response)\n        new_response.__class__ = cls\n        return new_response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse.raise_for_status","title":"<code>raise_for_status</code>","text":"<p>Raise an exception if the response contains an HTTPStatusError.</p> <p>The <code>PrefectHTTPStatusError</code> contains useful additional information that is not contained in the <code>HTTPStatusError</code>.</p> Source code in <code>prefect/client/base.py</code> <pre><code>def raise_for_status(self) -&gt; None:\n    \"\"\"\n    Raise an exception if the response contains an HTTPStatusError.\n\n    The `PrefectHTTPStatusError` contains useful additional information that\n    is not contained in the `HTTPStatusError`.\n    \"\"\"\n    try:\n        return super().raise_for_status()\n    except HTTPStatusError as exc:\n        raise PrefectHTTPStatusError.from_httpx_error(exc) from exc.__cause__\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse.from_httpx_response","title":"<code>from_httpx_response</code>  <code>classmethod</code>","text":"<p>Create a <code>PrefectReponse</code> from an <code>httpx.Response</code>.</p> <p>By changing the <code>__class__</code> attribute of the Response, we change the method resolution order to look for methods defined in PrefectResponse, while leaving everything else about the original Response instance intact.</p> Source code in <code>prefect/client/base.py</code> <pre><code>@classmethod\ndef from_httpx_response(cls: Type[Self], response: httpx.Response) -&gt; Self:\n    \"\"\"\n    Create a `PrefectReponse` from an `httpx.Response`.\n\n    By changing the `__class__` attribute of the Response, we change the method\n    resolution order to look for methods defined in PrefectResponse, while leaving\n    everything else about the original Response instance intact.\n    \"\"\"\n    new_response = copy.copy(response)\n    new_response.__class__ = cls\n    return new_response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxAsyncClient","title":"<code>PrefectHttpxAsyncClient</code>","text":"<p>               Bases: <code>AsyncClient</code></p> <p>A Prefect wrapper for the async httpx client with support for retry-after headers for the provided status codes (typically 429, 502 and 503).</p> <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p> <p>For more details on rate limit headers, see: Configuring Cloudflare Rate Limiting</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxAsyncClient(httpx.AsyncClient):\n    \"\"\"\n    A Prefect wrapper for the async httpx client with support for retry-after headers\n    for the provided status codes (typically 429, 502 and 503).\n\n    Additionally, this client will always call `raise_for_status` on responses.\n\n    For more details on rate limit headers, see:\n    [Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        enable_csrf_support: bool = False,\n        raise_on_all_errors: bool = True,\n        **kwargs,\n    ):\n        self.enable_csrf_support: bool = enable_csrf_support\n        self.csrf_token: Optional[str] = None\n        self.csrf_token_expiration: Optional[datetime] = None\n        self.csrf_client_id: uuid.UUID = uuid.uuid4()\n        self.raise_on_all_errors: bool = raise_on_all_errors\n\n        super().__init__(*args, **kwargs)\n\n        user_agent = (\n            f\"prefect/{prefect.__version__} (API {constants.SERVER_API_VERSION})\"\n        )\n        self.headers[\"User-Agent\"] = user_agent\n\n    async def _send_with_retry(\n        self,\n        request: Request,\n        send: Callable[[Request], Awaitable[Response]],\n        send_args: Tuple,\n        send_kwargs: Dict,\n        retry_codes: Set[int] = set(),\n        retry_exceptions: Tuple[Exception, ...] = tuple(),\n    ):\n        \"\"\"\n        Send a request and retry it if it fails.\n\n        Sends the provided request and retries it up to PREFECT_CLIENT_MAX_RETRIES times\n        if the request either raises an exception listed in `retry_exceptions` or\n        receives a response with a status code listed in `retry_codes`.\n\n        Retries will be delayed based on either the retry header (preferred) or\n        exponential backoff if a retry header is not provided.\n        \"\"\"\n        try_count = 0\n        response = None\n\n        is_change_request = request.method.lower() in {\"post\", \"put\", \"patch\", \"delete\"}\n\n        if self.enable_csrf_support and is_change_request:\n            await self._add_csrf_headers(request=request)\n\n        while try_count &lt;= PREFECT_CLIENT_MAX_RETRIES.value():\n            try_count += 1\n            retry_seconds = None\n            exc_info = None\n\n            try:\n                response = await send(request, *send_args, **send_kwargs)\n            except retry_exceptions:  # type: ignore\n                if try_count &gt; PREFECT_CLIENT_MAX_RETRIES.value():\n                    raise\n                # Otherwise, we will ignore this error but capture the info for logging\n                exc_info = sys.exc_info()\n            else:\n                # We got a response; check if it's a CSRF error, otherwise\n                # return immediately if it is not retryable\n                if (\n                    response.status_code == status.HTTP_403_FORBIDDEN\n                    and \"Invalid CSRF token\" in response.text\n                ):\n                    # We got a CSRF error, clear the token and try again\n                    self.csrf_token = None\n                    await self._add_csrf_headers(request)\n                elif response.status_code not in retry_codes:\n                    return response\n\n                if \"Retry-After\" in response.headers:\n                    retry_seconds = float(response.headers[\"Retry-After\"])\n\n            # Use an exponential back-off if not set in a header\n            if retry_seconds is None:\n                retry_seconds = 2**try_count\n\n            # Add jitter\n            jitter_factor = PREFECT_CLIENT_RETRY_JITTER_FACTOR.value()\n            if retry_seconds &gt; 0 and jitter_factor &gt; 0:\n                if response is not None and \"Retry-After\" in response.headers:\n                    # Always wait for _at least_ retry seconds if requested by the API\n                    retry_seconds = bounded_poisson_interval(\n                        retry_seconds, retry_seconds * (1 + jitter_factor)\n                    )\n                else:\n                    # Otherwise, use a symmetrical jitter\n                    retry_seconds = clamped_poisson_interval(\n                        retry_seconds, jitter_factor\n                    )\n\n            logger.debug(\n                (\n                    \"Encountered retryable exception during request. \"\n                    if exc_info\n                    else (\n                        \"Received response with retryable status code\"\n                        f\" {response.status_code}. \"\n                    )\n                )\n                + f\"Another attempt will be made in {retry_seconds}s. \"\n                \"This is attempt\"\n                f\" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.\",\n                exc_info=exc_info,\n            )\n            await anyio.sleep(retry_seconds)\n\n        assert (\n            response is not None\n        ), \"Retry handling ended without response or exception\"\n\n        # We ran out of retries, return the failed response\n        return response\n\n    async def send(self, request: Request, *args, **kwargs) -&gt; Response:\n        \"\"\"\n        Send a request with automatic retry behavior for the following status codes:\n\n        - 403 Forbidden, if the request failed due to CSRF protection\n        - 408 Request Timeout\n        - 429 CloudFlare-style rate limiting\n        - 502 Bad Gateway\n        - 503 Service unavailable\n        - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n        \"\"\"\n\n        super_send = super().send\n        response = await self._send_with_retry(\n            request=request,\n            send=super_send,\n            send_args=args,\n            send_kwargs=kwargs,\n            retry_codes={\n                status.HTTP_429_TOO_MANY_REQUESTS,\n                status.HTTP_503_SERVICE_UNAVAILABLE,\n                status.HTTP_502_BAD_GATEWAY,\n                status.HTTP_408_REQUEST_TIMEOUT,\n                *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n            },\n            retry_exceptions=(\n                httpx.ReadTimeout,\n                httpx.PoolTimeout,\n                httpx.ConnectTimeout,\n                # `ConnectionResetError` when reading socket raises as a `ReadError`\n                httpx.ReadError,\n                # Sockets can be closed during writes resulting in a `WriteError`\n                httpx.WriteError,\n                # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n                httpx.RemoteProtocolError,\n                # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n                httpx.LocalProtocolError,\n            ),\n        )\n\n        # Convert to a Prefect response to add nicer errors messages\n        response = PrefectResponse.from_httpx_response(response)\n\n        if self.raise_on_all_errors:\n            response.raise_for_status()\n\n        return response\n\n    async def _add_csrf_headers(self, request: Request):\n        now = datetime.now(timezone.utc)\n\n        if not self.enable_csrf_support:\n            return\n\n        if not self.csrf_token or (\n            self.csrf_token_expiration and now &gt; self.csrf_token_expiration\n        ):\n            token_request = self.build_request(\n                \"GET\", f\"/csrf-token?client={self.csrf_client_id}\"\n            )\n\n            try:\n                token_response = await self.send(token_request)\n            except PrefectHTTPStatusError as exc:\n                old_server = exc.response.status_code == status.HTTP_404_NOT_FOUND\n                unconfigured_server = (\n                    exc.response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY\n                    and \"CSRF protection is disabled.\" in exc.response.text\n                )\n\n                if old_server or unconfigured_server:\n                    # The token endpoint is either unavailable, suggesting an\n                    # older server, or CSRF protection is disabled. In either\n                    # case we should disable CSRF support.\n                    self.enable_csrf_support = False\n                    return\n\n                raise\n\n            token: CsrfToken = CsrfToken.parse_obj(token_response.json())\n            self.csrf_token = token.token\n            self.csrf_token_expiration = token.expiration\n\n        request.headers[\"Prefect-Csrf-Token\"] = self.csrf_token\n        request.headers[\"Prefect-Csrf-Client\"] = str(self.csrf_client_id)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxAsyncClient.send","title":"<code>send</code>  <code>async</code>","text":"<p>Send a request with automatic retry behavior for the following status codes:</p> <ul> <li>403 Forbidden, if the request failed due to CSRF protection</li> <li>408 Request Timeout</li> <li>429 CloudFlare-style rate limiting</li> <li>502 Bad Gateway</li> <li>503 Service unavailable</li> <li>Any additional status codes provided in <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code></li> </ul> Source code in <code>prefect/client/base.py</code> <pre><code>async def send(self, request: Request, *args, **kwargs) -&gt; Response:\n    \"\"\"\n    Send a request with automatic retry behavior for the following status codes:\n\n    - 403 Forbidden, if the request failed due to CSRF protection\n    - 408 Request Timeout\n    - 429 CloudFlare-style rate limiting\n    - 502 Bad Gateway\n    - 503 Service unavailable\n    - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n    \"\"\"\n\n    super_send = super().send\n    response = await self._send_with_retry(\n        request=request,\n        send=super_send,\n        send_args=args,\n        send_kwargs=kwargs,\n        retry_codes={\n            status.HTTP_429_TOO_MANY_REQUESTS,\n            status.HTTP_503_SERVICE_UNAVAILABLE,\n            status.HTTP_502_BAD_GATEWAY,\n            status.HTTP_408_REQUEST_TIMEOUT,\n            *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n        },\n        retry_exceptions=(\n            httpx.ReadTimeout,\n            httpx.PoolTimeout,\n            httpx.ConnectTimeout,\n            # `ConnectionResetError` when reading socket raises as a `ReadError`\n            httpx.ReadError,\n            # Sockets can be closed during writes resulting in a `WriteError`\n            httpx.WriteError,\n            # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n            httpx.RemoteProtocolError,\n            # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n            httpx.LocalProtocolError,\n        ),\n    )\n\n    # Convert to a Prefect response to add nicer errors messages\n    response = PrefectResponse.from_httpx_response(response)\n\n    if self.raise_on_all_errors:\n        response.raise_for_status()\n\n    return response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncClient","title":"<code>PrefectHttpxSyncClient</code>","text":"<p>               Bases: <code>Client</code></p> <p>A Prefect wrapper for the async httpx client with support for retry-after headers for the provided status codes (typically 429, 502 and 503).</p> <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p> <p>For more details on rate limit headers, see: Configuring Cloudflare Rate Limiting</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxSyncClient(httpx.Client):\n    \"\"\"\n    A Prefect wrapper for the async httpx client with support for retry-after headers\n    for the provided status codes (typically 429, 502 and 503).\n\n    Additionally, this client will always call `raise_for_status` on responses.\n\n    For more details on rate limit headers, see:\n    [Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        enable_csrf_support: bool = False,\n        raise_on_all_errors: bool = True,\n        **kwargs,\n    ):\n        self.enable_csrf_support: bool = enable_csrf_support\n        self.csrf_token: Optional[str] = None\n        self.csrf_token_expiration: Optional[datetime] = None\n        self.csrf_client_id: uuid.UUID = uuid.uuid4()\n        self.raise_on_all_errors: bool = raise_on_all_errors\n\n        super().__init__(*args, **kwargs)\n\n        user_agent = (\n            f\"prefect/{prefect.__version__} (API {constants.SERVER_API_VERSION})\"\n        )\n        self.headers[\"User-Agent\"] = user_agent\n\n    def _send_with_retry(\n        self,\n        request: Request,\n        send: Callable[[Request], Response],\n        send_args: Tuple,\n        send_kwargs: Dict,\n        retry_codes: Set[int] = set(),\n        retry_exceptions: Tuple[Exception, ...] = tuple(),\n    ):\n        \"\"\"\n        Send a request and retry it if it fails.\n\n        Sends the provided request and retries it up to PREFECT_CLIENT_MAX_RETRIES times\n        if the request either raises an exception listed in `retry_exceptions` or\n        receives a response with a status code listed in `retry_codes`.\n\n        Retries will be delayed based on either the retry header (preferred) or\n        exponential backoff if a retry header is not provided.\n        \"\"\"\n        try_count = 0\n        response = None\n\n        is_change_request = request.method.lower() in {\"post\", \"put\", \"patch\", \"delete\"}\n\n        if self.enable_csrf_support and is_change_request:\n            self._add_csrf_headers(request=request)\n\n        while try_count &lt;= PREFECT_CLIENT_MAX_RETRIES.value():\n            try_count += 1\n            retry_seconds = None\n            exc_info = None\n\n            try:\n                response = send(request, *send_args, **send_kwargs)\n            except retry_exceptions:  # type: ignore\n                if try_count &gt; PREFECT_CLIENT_MAX_RETRIES.value():\n                    raise\n                # Otherwise, we will ignore this error but capture the info for logging\n                exc_info = sys.exc_info()\n            else:\n                # We got a response; check if it's a CSRF error, otherwise\n                # return immediately if it is not retryable\n                if (\n                    response.status_code == status.HTTP_403_FORBIDDEN\n                    and \"Invalid CSRF token\" in response.text\n                ):\n                    # We got a CSRF error, clear the token and try again\n                    self.csrf_token = None\n                    self._add_csrf_headers(request)\n                elif response.status_code not in retry_codes:\n                    return response\n\n                if \"Retry-After\" in response.headers:\n                    retry_seconds = float(response.headers[\"Retry-After\"])\n\n            # Use an exponential back-off if not set in a header\n            if retry_seconds is None:\n                retry_seconds = 2**try_count\n\n            # Add jitter\n            jitter_factor = PREFECT_CLIENT_RETRY_JITTER_FACTOR.value()\n            if retry_seconds &gt; 0 and jitter_factor &gt; 0:\n                if response is not None and \"Retry-After\" in response.headers:\n                    # Always wait for _at least_ retry seconds if requested by the API\n                    retry_seconds = bounded_poisson_interval(\n                        retry_seconds, retry_seconds * (1 + jitter_factor)\n                    )\n                else:\n                    # Otherwise, use a symmetrical jitter\n                    retry_seconds = clamped_poisson_interval(\n                        retry_seconds, jitter_factor\n                    )\n\n            logger.debug(\n                (\n                    \"Encountered retryable exception during request. \"\n                    if exc_info\n                    else (\n                        \"Received response with retryable status code\"\n                        f\" {response.status_code}. \"\n                    )\n                )\n                + f\"Another attempt will be made in {retry_seconds}s. \"\n                \"This is attempt\"\n                f\" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.\",\n                exc_info=exc_info,\n            )\n            time.sleep(retry_seconds)\n\n        assert (\n            response is not None\n        ), \"Retry handling ended without response or exception\"\n\n        # We ran out of retries, return the failed response\n        return response\n\n    def send(self, request: Request, *args, **kwargs) -&gt; Response:\n        \"\"\"\n        Send a request with automatic retry behavior for the following status codes:\n\n        - 403 Forbidden, if the request failed due to CSRF protection\n        - 408 Request Timeout\n        - 429 CloudFlare-style rate limiting\n        - 502 Bad Gateway\n        - 503 Service unavailable\n        - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n        \"\"\"\n\n        super_send = super().send\n        response = self._send_with_retry(\n            request=request,\n            send=super_send,\n            send_args=args,\n            send_kwargs=kwargs,\n            retry_codes={\n                status.HTTP_429_TOO_MANY_REQUESTS,\n                status.HTTP_503_SERVICE_UNAVAILABLE,\n                status.HTTP_502_BAD_GATEWAY,\n                status.HTTP_408_REQUEST_TIMEOUT,\n                *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n            },\n            retry_exceptions=(\n                httpx.ReadTimeout,\n                httpx.PoolTimeout,\n                httpx.ConnectTimeout,\n                # `ConnectionResetError` when reading socket raises as a `ReadError`\n                httpx.ReadError,\n                # Sockets can be closed during writes resulting in a `WriteError`\n                httpx.WriteError,\n                # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n                httpx.RemoteProtocolError,\n                # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n                httpx.LocalProtocolError,\n            ),\n        )\n\n        # Convert to a Prefect response to add nicer errors messages\n        response = PrefectResponse.from_httpx_response(response)\n\n        if self.raise_on_all_errors:\n            response.raise_for_status()\n\n        return response\n\n    def _add_csrf_headers(self, request: Request):\n        now = datetime.now(timezone.utc)\n\n        if not self.enable_csrf_support:\n            return\n\n        if not self.csrf_token or (\n            self.csrf_token_expiration and now &gt; self.csrf_token_expiration\n        ):\n            token_request = self.build_request(\n                \"GET\", f\"/csrf-token?client={self.csrf_client_id}\"\n            )\n\n            try:\n                token_response = self.send(token_request)\n            except PrefectHTTPStatusError as exc:\n                old_server = exc.response.status_code == status.HTTP_404_NOT_FOUND\n                unconfigured_server = (\n                    exc.response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY\n                    and \"CSRF protection is disabled.\" in exc.response.text\n                )\n\n                if old_server or unconfigured_server:\n                    # The token endpoint is either unavailable, suggesting an\n                    # older server, or CSRF protection is disabled. In either\n                    # case we should disable CSRF support.\n                    self.enable_csrf_support = False\n                    return\n\n                raise\n\n            token: CsrfToken = CsrfToken.parse_obj(token_response.json())\n            self.csrf_token = token.token\n            self.csrf_token_expiration = token.expiration\n\n        request.headers[\"Prefect-Csrf-Token\"] = self.csrf_token\n        request.headers[\"Prefect-Csrf-Client\"] = str(self.csrf_client_id)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncClient.send","title":"<code>send</code>","text":"<p>Send a request with automatic retry behavior for the following status codes:</p> <ul> <li>403 Forbidden, if the request failed due to CSRF protection</li> <li>408 Request Timeout</li> <li>429 CloudFlare-style rate limiting</li> <li>502 Bad Gateway</li> <li>503 Service unavailable</li> <li>Any additional status codes provided in <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code></li> </ul> Source code in <code>prefect/client/base.py</code> <pre><code>def send(self, request: Request, *args, **kwargs) -&gt; Response:\n    \"\"\"\n    Send a request with automatic retry behavior for the following status codes:\n\n    - 403 Forbidden, if the request failed due to CSRF protection\n    - 408 Request Timeout\n    - 429 CloudFlare-style rate limiting\n    - 502 Bad Gateway\n    - 503 Service unavailable\n    - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n    \"\"\"\n\n    super_send = super().send\n    response = self._send_with_retry(\n        request=request,\n        send=super_send,\n        send_args=args,\n        send_kwargs=kwargs,\n        retry_codes={\n            status.HTTP_429_TOO_MANY_REQUESTS,\n            status.HTTP_503_SERVICE_UNAVAILABLE,\n            status.HTTP_502_BAD_GATEWAY,\n            status.HTTP_408_REQUEST_TIMEOUT,\n            *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n        },\n        retry_exceptions=(\n            httpx.ReadTimeout,\n            httpx.PoolTimeout,\n            httpx.ConnectTimeout,\n            # `ConnectionResetError` when reading socket raises as a `ReadError`\n            httpx.ReadError,\n            # Sockets can be closed during writes resulting in a `WriteError`\n            httpx.WriteError,\n            # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n            httpx.RemoteProtocolError,\n            # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n            httpx.LocalProtocolError,\n        ),\n    )\n\n    # Convert to a Prefect response to add nicer errors messages\n    response = PrefectResponse.from_httpx_response(response)\n\n    if self.raise_on_all_errors:\n        response.raise_for_status()\n\n    return response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncEphemeralClient","title":"<code>PrefectHttpxSyncEphemeralClient</code>","text":"<p>               Bases: <code>TestClient</code>, <code>PrefectHttpxSyncClient</code></p> <p>This client is a synchronous httpx client that can be used to talk directly to an ASGI app, such as an ephemeral Prefect API.</p> <p>It is a subclass of both Starlette's <code>TestClient</code> and Prefect's <code>PrefectHttpxSyncClient</code>, so it combines the synchronous testing capabilities of <code>TestClient</code> with the Prefect-specific behaviors of <code>PrefectHttpxSyncClient</code>.</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxSyncEphemeralClient(TestClient, PrefectHttpxSyncClient):\n    \"\"\"\n    This client is a synchronous httpx client that can be used to talk directly\n    to an ASGI app, such as an ephemeral Prefect API.\n\n    It is a subclass of both Starlette's `TestClient` and Prefect's\n    `PrefectHttpxSyncClient`, so it combines the synchronous testing\n    capabilities of `TestClient` with the Prefect-specific behaviors of\n    `PrefectHttpxSyncClient`.\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        # override TestClient default\n        raise_server_exceptions=False,\n        **kwargs,\n    ):\n        super().__init__(\n            *args,\n            raise_server_exceptions=raise_server_exceptions,\n            **kwargs,\n        )\n\n    pass\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.app_lifespan_context","title":"<code>app_lifespan_context</code>  <code>async</code>","text":"<p>A context manager that calls startup/shutdown hooks for the given application.</p> <p>Lifespan contexts are cached per application to avoid calling the lifespan hooks more than once if the context is entered in nested code. A no-op context will be returned if the context for the given application is already being managed.</p> <p>This manager is robust to concurrent access within the event loop. For example, if you have concurrent contexts for the same application, it is guaranteed that startup hooks will be called before their context starts and shutdown hooks will only be called after their context exits.</p> <p>A reference count is used to support nested use of clients without running lifespan hooks excessively. The first client context entered will create and enter a lifespan context. Each subsequent client will increment a reference count but will not create a new lifespan context. When each client context exits, the reference count is decremented. When the last client context exits, the lifespan will be closed.</p> <p>In simple nested cases, the first client context will be the one to exit the lifespan. However, if client contexts are entered concurrently they may not exit in a consistent order. If the first client context was responsible for closing the lifespan, it would have to wait until all other client contexts to exit to avoid firing shutdown hooks while the application is in use. Waiting for the other clients to exit can introduce deadlocks, so, instead, the first client will exit without closing the lifespan context and reference counts will be used to ensure the lifespan is closed once all of the clients are done.</p> Source code in <code>prefect/client/base.py</code> <pre><code>@asynccontextmanager\nasync def app_lifespan_context(app: ASGIApp) -&gt; AsyncGenerator[None, None]:\n    \"\"\"\n    A context manager that calls startup/shutdown hooks for the given application.\n\n    Lifespan contexts are cached per application to avoid calling the lifespan hooks\n    more than once if the context is entered in nested code. A no-op context will be\n    returned if the context for the given application is already being managed.\n\n    This manager is robust to concurrent access within the event loop. For example,\n    if you have concurrent contexts for the same application, it is guaranteed that\n    startup hooks will be called before their context starts and shutdown hooks will\n    only be called after their context exits.\n\n    A reference count is used to support nested use of clients without running\n    lifespan hooks excessively. The first client context entered will create and enter\n    a lifespan context. Each subsequent client will increment a reference count but will\n    not create a new lifespan context. When each client context exits, the reference\n    count is decremented. When the last client context exits, the lifespan will be\n    closed.\n\n    In simple nested cases, the first client context will be the one to exit the\n    lifespan. However, if client contexts are entered concurrently they may not exit\n    in a consistent order. If the first client context was responsible for closing\n    the lifespan, it would have to wait until all other client contexts to exit to\n    avoid firing shutdown hooks while the application is in use. Waiting for the other\n    clients to exit can introduce deadlocks, so, instead, the first client will exit\n    without closing the lifespan context and reference counts will be used to ensure\n    the lifespan is closed once all of the clients are done.\n    \"\"\"\n    # TODO: A deadlock has been observed during multithreaded use of clients while this\n    #       lifespan context is being used. This has only been reproduced on Python 3.7\n    #       and while we hope to discourage using multiple event loops in threads, this\n    #       bug may emerge again.\n    #       See https://github.com/PrefectHQ/orion/pull/1696\n    thread_id = threading.get_ident()\n\n    # The id of the application is used instead of the hash so each application instance\n    # is managed independently even if they share the same settings. We include the\n    # thread id since applications are managed separately per thread.\n    key = (thread_id, id(app))\n\n    # On exception, this will be populated with exception details\n    exc_info = (None, None, None)\n\n    # Get a lock unique to this thread since anyio locks are not threadsafe\n    lock = APP_LIFESPANS_LOCKS[thread_id]\n\n    async with lock:\n        if key in APP_LIFESPANS:\n            # The lifespan is already being managed, just increment the reference count\n            APP_LIFESPANS_REF_COUNTS[key] += 1\n        else:\n            # Create a new lifespan manager\n            APP_LIFESPANS[key] = context = LifespanManager(\n                app, startup_timeout=30, shutdown_timeout=30\n            )\n            APP_LIFESPANS_REF_COUNTS[key] = 1\n\n            # Ensure we enter the context before releasing the lock so startup hooks\n            # are complete before another client can be used\n            await context.__aenter__()\n\n    try:\n        yield\n    except BaseException:\n        exc_info = sys.exc_info()\n        raise\n    finally:\n        # If we do not shield against anyio cancellation, the lock will return\n        # immediately and the code in its context will not run, leaving the lifespan\n        # open\n        with anyio.CancelScope(shield=True):\n            async with lock:\n                # After the consumer exits the context, decrement the reference count\n                APP_LIFESPANS_REF_COUNTS[key] -= 1\n\n                # If this the last context to exit, close the lifespan\n                if APP_LIFESPANS_REF_COUNTS[key] &lt;= 0:\n                    APP_LIFESPANS_REF_COUNTS.pop(key)\n                    context = APP_LIFESPANS.pop(key)\n                    await context.__aexit__(*exc_info)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/","title":"cloud","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud","title":"<code>prefect.client.cloud</code>","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudUnauthorizedError","title":"<code>CloudUnauthorizedError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the CloudClient receives a 401 or 403 from the Cloud API.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>class CloudUnauthorizedError(PrefectException):\n    \"\"\"\n    Raised when the CloudClient receives a 401 or 403 from the Cloud API.\n    \"\"\"\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudClient","title":"<code>CloudClient</code>","text":"Source code in <code>prefect/client/cloud.py</code> <pre><code>class CloudClient:\n    def __init__(\n        self,\n        host: str,\n        api_key: str,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings or dict()\n        httpx_settings.setdefault(\"headers\", dict())\n        httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        httpx_settings.setdefault(\"base_url\", host)\n        if not PREFECT_UNIT_TEST_MODE.value():\n            httpx_settings.setdefault(\"follow_redirects\", True)\n        self._client = PrefectHttpxAsyncClient(\n            **httpx_settings, enable_csrf_support=False\n        )\n\n    async def api_healthcheck(self):\n        \"\"\"\n        Attempts to connect to the Cloud API and raises the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        with anyio.fail_after(10):\n            await self.read_workspaces()\n\n    async def read_workspaces(self) -&gt; List[Workspace]:\n        workspaces = pydantic.parse_obj_as(\n            List[Workspace], await self.get(\"/me/workspaces\")\n        )\n        return workspaces\n\n    async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n        configured_url = prefect.settings.PREFECT_API_URL.value()\n        account_id, workspace_id = re.findall(PARSE_API_URL_REGEX, configured_url)[0]\n        return await self.get(\n            f\"accounts/{account_id}/workspaces/{workspace_id}/collections/work_pool_types\"\n        )\n\n    async def __aenter__(self):\n        await self._client.__aenter__()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        return await self._client.__aexit__(*exc_info)\n\n    def __enter__(self):\n        raise RuntimeError(\n            \"The `CloudClient` must be entered with an async context. Use 'async \"\n            \"with CloudClient(...)' not 'with CloudClient(...)'\"\n        )\n\n    def __exit__(self, *_):\n        assert False, \"This should never be called but must be defined for __enter__\"\n\n    async def get(self, route, **kwargs):\n        return await self.request(\"GET\", route, **kwargs)\n\n    async def request(self, method, route, **kwargs):\n        try:\n            res = await self._client.request(method, route, **kwargs)\n            res.raise_for_status()\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code in (\n                status.HTTP_401_UNAUTHORIZED,\n                status.HTTP_403_FORBIDDEN,\n            ):\n                raise CloudUnauthorizedError\n            else:\n                raise exc\n\n        if res.status_code == status.HTTP_204_NO_CONTENT:\n            return\n\n        return res.json()\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudClient.api_healthcheck","title":"<code>api_healthcheck</code>  <code>async</code>","text":"<p>Attempts to connect to the Cloud API and raises the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>async def api_healthcheck(self):\n    \"\"\"\n    Attempts to connect to the Cloud API and raises the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    with anyio.fail_after(10):\n        await self.read_workspaces()\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.get_cloud_client","title":"<code>get_cloud_client</code>","text":"<p>Needs a docstring.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>def get_cloud_client(\n    host: Optional[str] = None,\n    api_key: Optional[str] = None,\n    httpx_settings: Optional[dict] = None,\n    infer_cloud_url: bool = False,\n) -&gt; \"CloudClient\":\n    \"\"\"\n    Needs a docstring.\n    \"\"\"\n    if httpx_settings is not None:\n        httpx_settings = httpx_settings.copy()\n\n    if infer_cloud_url is False:\n        host = host or PREFECT_CLOUD_API_URL.value()\n    else:\n        configured_url = prefect.settings.PREFECT_API_URL.value()\n        host = re.sub(PARSE_API_URL_REGEX, \"\", configured_url)\n\n    return CloudClient(\n        host=host,\n        api_key=api_key or PREFECT_API_KEY.value(),\n        httpx_settings=httpx_settings,\n    )\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/orchestration/","title":"orchestration","text":"<p>Asynchronous client implementation for communicating with the Prefect REST API.</p> <p>Explore the client by communicating with an in-memory webserver \u2014 no setup required:</p> <pre><code>$ # start python REPL with native await functionality\n$ python -m asyncio\n&gt;&gt;&gt; from prefect import get_client\n&gt;&gt;&gt; async with get_client() as client:\n...     response = await client.hello()\n...     print(response.json())\n\ud83d\udc4b\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration","title":"<code>prefect.client.orchestration</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient","title":"<code>PrefectClient</code>","text":"<p>An asynchronous client for interacting with the Prefect REST API.</p> <p>Parameters:</p> Name Type Description Default <code>api</code> <code>Union[str, ASGIApp]</code> <p>the REST API URL or FastAPI application to connect to</p> required <code>api_key</code> <code>str</code> <p>An optional API key for authentication.</p> <code>None</code> <code>api_version</code> <code>str</code> <p>The API version this client is compatible with.</p> <code>None</code> <code>httpx_settings</code> <code>Optional[Dict[str, Any]]</code> <p>An optional dictionary of settings to pass to the underlying <code>httpx.AsyncClient</code></p> <code>None</code> <pre><code>Say hello to a Prefect REST API\n\n&lt;div class=\"terminal\"&gt;\n```\n&gt;&gt;&gt; async with get_client() as client:\n&gt;&gt;&gt;     response = await client.hello()\n&gt;&gt;&gt;\n&gt;&gt;&gt; print(response.json())\n\ud83d\udc4b\n```\n&lt;/div&gt;\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>class PrefectClient:\n    \"\"\"\n    An asynchronous client for interacting with the [Prefect REST API](/api-ref/rest-api/).\n\n    Args:\n        api: the REST API URL or FastAPI application to connect to\n        api_key: An optional API key for authentication.\n        api_version: The API version this client is compatible with.\n        httpx_settings: An optional dictionary of settings to pass to the underlying\n            `httpx.AsyncClient`\n\n    Examples:\n\n        Say hello to a Prefect REST API\n\n        &lt;div class=\"terminal\"&gt;\n        ```\n        &gt;&gt;&gt; async with get_client() as client:\n        &gt;&gt;&gt;     response = await client.hello()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; print(response.json())\n        \ud83d\udc4b\n        ```\n        &lt;/div&gt;\n    \"\"\"\n\n    def __init__(\n        self,\n        api: Union[str, ASGIApp],\n        *,\n        api_key: str = None,\n        api_version: str = None,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings.copy() if httpx_settings else {}\n        httpx_settings.setdefault(\"headers\", {})\n\n        if PREFECT_API_TLS_INSECURE_SKIP_VERIFY:\n            httpx_settings.setdefault(\"verify\", False)\n        else:\n            cert_file = PREFECT_API_SSL_CERT_FILE.value()\n            if not cert_file:\n                cert_file = certifi.where()\n            httpx_settings.setdefault(\"verify\", cert_file)\n\n        if api_version is None:\n            api_version = SERVER_API_VERSION\n        httpx_settings[\"headers\"].setdefault(\"X-PREFECT-API-VERSION\", api_version)\n        if api_key:\n            httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        # Context management\n        self._exit_stack = AsyncExitStack()\n        self._ephemeral_app: Optional[ASGIApp] = None\n        self.manage_lifespan = True\n        self.server_type: ServerType\n\n        # Only set if this client started the lifespan of the application\n        self._ephemeral_lifespan: Optional[LifespanManager] = None\n\n        self._closed = False\n        self._started = False\n\n        # Connect to an external application\n        if isinstance(api, str):\n            if httpx_settings.get(\"app\"):\n                raise ValueError(\n                    \"Invalid httpx settings: `app` cannot be set when providing an \"\n                    \"api url. `app` is only for use with ephemeral instances. Provide \"\n                    \"it as the `api` parameter instead.\"\n                )\n            httpx_settings.setdefault(\"base_url\", api)\n\n            # See https://www.python-httpx.org/advanced/#pool-limit-configuration\n            httpx_settings.setdefault(\n                \"limits\",\n                httpx.Limits(\n                    # We see instability when allowing the client to open many connections at once.\n                    # Limiting concurrency results in more stable performance.\n                    max_connections=16,\n                    max_keepalive_connections=8,\n                    # The Prefect Cloud LB will keep connections alive for 30s.\n                    # Only allow the client to keep connections alive for 25s.\n                    keepalive_expiry=25,\n                ),\n            )\n\n            # See https://www.python-httpx.org/http2/\n            # Enabling HTTP/2 support on the client does not necessarily mean that your requests\n            # and responses will be transported over HTTP/2, since both the client and the server\n            # need to support HTTP/2. If you connect to a server that only supports HTTP/1.1 the\n            # client will use a standard HTTP/1.1 connection instead.\n            httpx_settings.setdefault(\"http2\", PREFECT_API_ENABLE_HTTP2.value())\n\n            self.server_type = (\n                ServerType.CLOUD\n                if api.startswith(PREFECT_CLOUD_API_URL.value())\n                else ServerType.SERVER\n            )\n\n        # Connect to an in-process application\n        elif isinstance(api, ASGIApp):\n            self._ephemeral_app = api\n            self.server_type = ServerType.EPHEMERAL\n\n            # When using an ephemeral server, server-side exceptions can be raised\n            # client-side breaking all of our response error code handling. To work\n            # around this, we create an ASGI transport with application exceptions\n            # disabled instead of using the application directly.\n            # refs:\n            # - https://github.com/PrefectHQ/prefect/pull/9637\n            # - https://github.com/encode/starlette/blob/d3a11205ed35f8e5a58a711db0ff59c86fa7bb31/starlette/middleware/errors.py#L184\n            # - https://github.com/tiangolo/fastapi/blob/8cc967a7605d3883bd04ceb5d25cc94ae079612f/fastapi/applications.py#L163-L164\n            httpx_settings.setdefault(\n                \"transport\",\n                httpx.ASGITransport(\n                    app=self._ephemeral_app, raise_app_exceptions=False\n                ),\n            )\n            httpx_settings.setdefault(\"base_url\", \"http://ephemeral-prefect/api\")\n\n        else:\n            raise TypeError(\n                f\"Unexpected type {type(api).__name__!r} for argument `api`. Expected\"\n                \" 'str' or 'ASGIApp/FastAPI'\"\n            )\n\n        # See https://www.python-httpx.org/advanced/#timeout-configuration\n        httpx_settings.setdefault(\n            \"timeout\",\n            httpx.Timeout(\n                connect=PREFECT_API_REQUEST_TIMEOUT.value(),\n                read=PREFECT_API_REQUEST_TIMEOUT.value(),\n                write=PREFECT_API_REQUEST_TIMEOUT.value(),\n                pool=PREFECT_API_REQUEST_TIMEOUT.value(),\n            ),\n        )\n\n        if not PREFECT_UNIT_TEST_MODE:\n            httpx_settings.setdefault(\"follow_redirects\", True)\n\n        enable_csrf_support = (\n            self.server_type != ServerType.CLOUD\n            and PREFECT_CLIENT_CSRF_SUPPORT_ENABLED.value()\n        )\n\n        self._client = PrefectHttpxAsyncClient(\n            **httpx_settings, enable_csrf_support=enable_csrf_support\n        )\n        self._loop = None\n\n        # See https://www.python-httpx.org/advanced/#custom-transports\n        #\n        # If we're using an HTTP/S client (not the ephemeral client), adjust the\n        # transport to add retries _after_ it is instantiated. If we alter the transport\n        # before instantiation, the transport will not be aware of proxies unless we\n        # reproduce all of the logic to make it so.\n        #\n        # Only alter the transport to set our default of 3 retries, don't modify any\n        # transport a user may have provided via httpx_settings.\n        #\n        # Making liberal use of getattr and isinstance checks here to avoid any\n        # surprises if the internals of httpx or httpcore change on us\n        if isinstance(api, str) and not httpx_settings.get(\"transport\"):\n            transport_for_url = getattr(self._client, \"_transport_for_url\", None)\n            if callable(transport_for_url):\n                server_transport = transport_for_url(httpx.URL(api))\n                if isinstance(server_transport, httpx.AsyncHTTPTransport):\n                    pool = getattr(server_transport, \"_pool\", None)\n                    if isinstance(pool, httpcore.AsyncConnectionPool):\n                        pool._retries = 3\n\n        self.logger = get_logger(\"client\")\n\n    @property\n    def api_url(self) -&gt; httpx.URL:\n        \"\"\"\n        Get the base URL for the API.\n        \"\"\"\n        return self._client.base_url\n\n    # API methods ----------------------------------------------------------------------\n\n    async def api_healthcheck(self) -&gt; Optional[Exception]:\n        \"\"\"\n        Attempts to connect to the API and returns the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        try:\n            await self._client.get(\"/health\")\n            return None\n        except Exception as exc:\n            return exc\n\n    async def hello(self) -&gt; httpx.Response:\n        \"\"\"\n        Send a GET request to /hello for testing purposes.\n        \"\"\"\n        return await self._client.get(\"/hello\")\n\n    async def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow: a [Flow][prefect.flows.Flow] object\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        return await self.create_flow_from_name(flow.name)\n\n    async def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow_name: the name of the new flow\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        flow_data = FlowCreate(name=flow_name)\n        response = await self._client.post(\n            \"/flows/\", json=flow_data.dict(json_compatible=True)\n        )\n\n        flow_id = response.json().get(\"id\")\n        if not flow_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        # Return the id of the created flow\n        return UUID(flow_id)\n\n    async def read_flow(self, flow_id: UUID) -&gt; Flow:\n        \"\"\"\n        Query the Prefect API for a flow by id.\n\n        Args:\n            flow_id: the flow ID of interest\n\n        Returns:\n            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow\n        \"\"\"\n        response = await self._client.get(f\"/flows/{flow_id}\")\n        return Flow.parse_obj(response.json())\n\n    async def read_flows(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[Flow]:\n        \"\"\"\n        Query the Prefect API for flows. Only flows matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flows\n            limit: limit for the flow query\n            offset: offset for the flow query\n\n        Returns:\n            a list of Flow model representations of the flows\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/flows/filter\", json=body)\n        return pydantic.parse_obj_as(List[Flow], response.json())\n\n    async def read_flow_by_name(\n        self,\n        flow_name: str,\n    ) -&gt; Flow:\n        \"\"\"\n        Query the Prefect API for a flow by name.\n\n        Args:\n            flow_name: the name of a flow\n\n        Returns:\n            a fully hydrated Flow model\n        \"\"\"\n        response = await self._client.get(f\"/flows/name/{flow_name}\")\n        return Flow.parse_obj(response.json())\n\n    async def create_flow_run_from_deployment(\n        self,\n        deployment_id: UUID,\n        *,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        state: prefect.states.State = None,\n        name: str = None,\n        tags: Iterable[str] = None,\n        idempotency_key: str = None,\n        parent_task_run_id: UUID = None,\n        work_queue_name: str = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a deployment.\n\n        Args:\n            deployment_id: The deployment ID to create the flow run from\n            parameters: Parameter overrides for this flow run. Merged with the\n                deployment defaults\n            context: Optional run context data\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n            name: An optional name for the flow run. If not provided, the server will\n                generate a name.\n            tags: An optional iterable of tags to apply to the flow run; these tags\n                are merged with the deployment's tags.\n            idempotency_key: Optional idempotency key for creation of the flow run.\n                If the key matches the key of an existing flow run, the existing run will\n                be returned instead of creating a new one.\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            work_queue_name: An optional work queue name to add this run to. If not provided,\n                will default to the deployment's set work queue.  If one is provided that does not\n                exist, a new work queue will be created within the deployment's work pool.\n            job_variables: Optional variables that will be supplied to the flow run job.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n        state = state or prefect.states.Scheduled()\n        tags = tags or []\n\n        flow_run_create = DeploymentFlowRunCreate(\n            parameters=parameters,\n            context=context,\n            state=state.to_state_create(),\n            tags=tags,\n            name=name,\n            idempotency_key=idempotency_key,\n            parent_task_run_id=parent_task_run_id,\n            job_variables=job_variables,\n        )\n\n        # done separately to avoid including this field in payloads sent to older API versions\n        if work_queue_name:\n            flow_run_create.work_queue_name = work_queue_name\n\n        response = await self._client.post(\n            f\"/deployments/{deployment_id}/create_flow_run\",\n            json=flow_run_create.dict(json_compatible=True, exclude_unset=True),\n        )\n        return FlowRun.parse_obj(response.json())\n\n    async def create_flow_run(\n        self,\n        flow: \"FlowObject\",\n        name: Optional[str] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        tags: Optional[Iterable[str]] = None,\n        parent_task_run_id: Optional[UUID] = None,\n        state: Optional[\"prefect.states.State\"] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a flow.\n\n        Args:\n            flow: The flow model to create the flow run for\n            name: An optional name for the flow run\n            parameters: Parameter overrides for this flow run.\n            context: Optional run context data\n            tags: a list of tags to apply to this flow run\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        # Retrieve the flow id\n        flow_id = await self.create_flow(flow)\n\n        flow_run_create = FlowRunCreate(\n            flow_id=flow_id,\n            flow_version=flow.version,\n            name=name,\n            parameters=parameters,\n            context=context,\n            tags=list(tags or []),\n            parent_task_run_id=parent_task_run_id,\n            state=state.to_state_create(),\n            empirical_policy=FlowRunPolicy(\n                retries=flow.retries,\n                retry_delay=flow.retry_delay_seconds,\n            ),\n        )\n\n        flow_run_create_json = flow_run_create.dict(json_compatible=True)\n        response = await self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n        flow_run = FlowRun.parse_obj(response.json())\n\n        # Restore the parameters to the local objects to retain expectations about\n        # Python objects\n        flow_run.parameters = parameters\n\n        return flow_run\n\n    async def update_flow_run(\n        self,\n        flow_run_id: UUID,\n        flow_version: Optional[str] = None,\n        parameters: Optional[dict] = None,\n        name: Optional[str] = None,\n        tags: Optional[Iterable[str]] = None,\n        empirical_policy: Optional[FlowRunPolicy] = None,\n        infrastructure_pid: Optional[str] = None,\n        job_variables: Optional[dict] = None,\n    ) -&gt; httpx.Response:\n        \"\"\"\n        Update a flow run's details.\n\n        Args:\n            flow_run_id: The identifier for the flow run to update.\n            flow_version: A new version string for the flow run.\n            parameters: A dictionary of parameter values for the flow run. This will not\n                be merged with any existing parameters.\n            name: A new name for the flow run.\n            empirical_policy: A new flow run orchestration policy. This will not be\n                merged with any existing policy.\n            tags: An iterable of new tags for the flow run. These will not be merged with\n                any existing tags.\n            infrastructure_pid: The id of flow run as returned by an\n                infrastructure block.\n\n        Returns:\n            an `httpx.Response` object from the PATCH request\n        \"\"\"\n        params = {}\n        if flow_version is not None:\n            params[\"flow_version\"] = flow_version\n        if parameters is not None:\n            params[\"parameters\"] = parameters\n        if name is not None:\n            params[\"name\"] = name\n        if tags is not None:\n            params[\"tags\"] = tags\n        if empirical_policy is not None:\n            params[\"empirical_policy\"] = empirical_policy\n        if infrastructure_pid:\n            params[\"infrastructure_pid\"] = infrastructure_pid\n        if job_variables is not None:\n            params[\"job_variables\"] = job_variables\n\n        flow_run_data = FlowRunUpdate(**params)\n\n        return await self._client.patch(\n            f\"/flow_runs/{flow_run_id}\",\n            json=flow_run_data.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def delete_flow_run(\n        self,\n        flow_run_id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a flow run by UUID.\n\n        Args:\n            flow_run_id: The flow run UUID of interest.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_concurrency_limit(\n        self,\n        tag: str,\n        concurrency_limit: int,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a tag concurrency limit in the Prefect API. These limits govern concurrently\n        running tasks.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n            concurrency_limit: the maximum number of concurrent task runs for a given tag\n\n        Raises:\n            httpx.RequestError: if the concurrency limit was not created for any reason\n\n        Returns:\n            the ID of the concurrency limit in the backend\n        \"\"\"\n\n        concurrency_limit_create = ConcurrencyLimitCreate(\n            tag=tag,\n            concurrency_limit=concurrency_limit,\n        )\n        response = await self._client.post(\n            \"/concurrency_limits/\",\n            json=concurrency_limit_create.dict(json_compatible=True),\n        )\n\n        concurrency_limit_id = response.json().get(\"id\")\n\n        if not concurrency_limit_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(concurrency_limit_id)\n\n    async def read_concurrency_limit_by_tag(\n        self,\n        tag: str,\n    ):\n        \"\"\"\n        Read the concurrency limit set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: if the concurrency limit was not created for any reason\n\n        Returns:\n            the concurrency limit set on a specific tag\n        \"\"\"\n        try:\n            response = await self._client.get(\n                f\"/concurrency_limits/tag/{tag}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        concurrency_limit_id = response.json().get(\"id\")\n\n        if not concurrency_limit_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        concurrency_limit = ConcurrencyLimit.parse_obj(response.json())\n        return concurrency_limit\n\n    async def read_concurrency_limits(\n        self,\n        limit: int,\n        offset: int,\n    ):\n        \"\"\"\n        Lists concurrency limits set on task run tags.\n\n        Args:\n            limit: the maximum number of concurrency limits returned\n            offset: the concurrency limit query offset\n\n        Returns:\n            a list of concurrency limits\n        \"\"\"\n\n        body = {\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/concurrency_limits/filter\", json=body)\n        return pydantic.parse_obj_as(List[ConcurrencyLimit], response.json())\n\n    async def reset_concurrency_limit_by_tag(\n        self,\n        tag: str,\n        slot_override: Optional[List[Union[UUID, str]]] = None,\n    ):\n        \"\"\"\n        Resets the concurrency limit slots set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n            slot_override: a list of task run IDs that are currently using a\n                concurrency slot, please check that any task run IDs included in\n                `slot_override` are currently running, otherwise those concurrency\n                slots will never be released.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        \"\"\"\n        if slot_override is not None:\n            slot_override = [str(slot) for slot in slot_override]\n\n        try:\n            await self._client.post(\n                f\"/concurrency_limits/tag/{tag}/reset\",\n                json=dict(slot_override=slot_override),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_concurrency_limit_by_tag(\n        self,\n        tag: str,\n    ):\n        \"\"\"\n        Delete the concurrency limit set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/concurrency_limits/tag/{tag}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_work_queue(\n        self,\n        name: str,\n        tags: Optional[List[str]] = None,\n        description: Optional[str] = None,\n        is_paused: Optional[bool] = None,\n        concurrency_limit: Optional[int] = None,\n        priority: Optional[int] = None,\n        work_pool_name: Optional[str] = None,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Create a work queue.\n\n        Args:\n            name: a unique name for the work queue\n            tags: DEPRECATED: an optional list of tags to filter on; only work scheduled with these tags\n                will be included in the queue. This option will be removed on 2023-02-23.\n            description: An optional description for the work queue.\n            is_paused: Whether or not the work queue is paused.\n            concurrency_limit: An optional concurrency limit for the work queue.\n            priority: The queue's priority. Lower values are higher priority (1 is the highest).\n            work_pool_name: The name of the work pool to use for this queue.\n\n        Raises:\n            prefect.exceptions.ObjectAlreadyExists: If request returns 409\n            httpx.RequestError: If request fails\n\n        Returns:\n            The created work queue\n        \"\"\"\n        if tags:\n            warnings.warn(\n                (\n                    \"The use of tags for creating work queue filters is deprecated.\"\n                    \" This option will be removed on 2023-02-23.\"\n                ),\n                DeprecationWarning,\n            )\n            filter = QueueFilter(tags=tags)\n        else:\n            filter = None\n        create_model = WorkQueueCreate(name=name, filter=filter)\n        if description is not None:\n            create_model.description = description\n        if is_paused is not None:\n            create_model.is_paused = is_paused\n        if concurrency_limit is not None:\n            create_model.concurrency_limit = concurrency_limit\n        if priority is not None:\n            create_model.priority = priority\n\n        data = create_model.dict(json_compatible=True)\n        try:\n            if work_pool_name is not None:\n                response = await self._client.post(\n                    f\"/work_pools/{work_pool_name}/queues\", json=data\n                )\n            else:\n                response = await self._client.post(\"/work_queues/\", json=data)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            elif e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueue.parse_obj(response.json())\n\n    async def read_work_queue_by_name(\n        self,\n        name: str,\n        work_pool_name: Optional[str] = None,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Read a work queue by name.\n\n        Args:\n            name (str): a unique name for the work queue\n            work_pool_name (str, optional): the name of the work pool\n                the queue belongs to.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: if no work queue is found\n            httpx.HTTPStatusError: other status errors\n\n        Returns:\n            WorkQueue: a work queue API object\n        \"\"\"\n        try:\n            if work_pool_name is not None:\n                response = await self._client.get(\n                    f\"/work_pools/{work_pool_name}/queues/{name}\"\n                )\n            else:\n                response = await self._client.get(f\"/work_queues/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return WorkQueue.parse_obj(response.json())\n\n    async def update_work_queue(self, id: UUID, **kwargs):\n        \"\"\"\n        Update properties of a work queue.\n\n        Args:\n            id: the ID of the work queue to update\n            **kwargs: the fields to update\n\n        Raises:\n            ValueError: if no kwargs are provided\n            prefect.exceptions.ObjectNotFound: if request returns 404\n            httpx.RequestError: if the request fails\n\n        \"\"\"\n        if not kwargs:\n            raise ValueError(\"No fields provided to update.\")\n\n        data = WorkQueueUpdate(**kwargs).dict(json_compatible=True, exclude_unset=True)\n        try:\n            await self._client.patch(f\"/work_queues/{id}\", json=data)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def get_runs_in_work_queue(\n        self,\n        id: UUID,\n        limit: int = 10,\n        scheduled_before: datetime.datetime = None,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Read flow runs off a work queue.\n\n        Args:\n            id: the id of the work queue to read from\n            limit: a limit on the number of runs to return\n            scheduled_before: a timestamp; only runs scheduled before this time will be returned.\n                Defaults to now.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            List[FlowRun]: a list of FlowRun objects read from the queue\n        \"\"\"\n        if scheduled_before is None:\n            scheduled_before = pendulum.now(\"UTC\")\n\n        try:\n            response = await self._client.post(\n                f\"/work_queues/{id}/get_runs\",\n                json={\n                    \"limit\": limit,\n                    \"scheduled_before\": scheduled_before.isoformat(),\n                },\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    async def read_work_queue(\n        self,\n        id: UUID,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Read a work queue.\n\n        Args:\n            id: the id of the work queue to load\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            WorkQueue: an instantiated WorkQueue object\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_queues/{id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueue.parse_obj(response.json())\n\n    async def read_work_queue_status(\n        self,\n        id: UUID,\n    ) -&gt; WorkQueueStatusDetail:\n        \"\"\"\n        Read a work queue status.\n\n        Args:\n            id: the id of the work queue to load\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            WorkQueueStatus: an instantiated WorkQueueStatus object\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_queues/{id}/status\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueueStatusDetail.parse_obj(response.json())\n\n    async def match_work_queues(\n        self,\n        prefixes: List[str],\n        work_pool_name: Optional[str] = None,\n    ) -&gt; List[WorkQueue]:\n        \"\"\"\n        Query the Prefect API for work queues with names with a specific prefix.\n\n        Args:\n            prefixes: a list of strings used to match work queue name prefixes\n            work_pool_name: an optional work pool name to scope the query to\n\n        Returns:\n            a list of WorkQueue model representations\n                of the work queues\n        \"\"\"\n        page_length = 100\n        current_page = 0\n        work_queues = []\n\n        while True:\n            new_queues = await self.read_work_queues(\n                work_pool_name=work_pool_name,\n                offset=current_page * page_length,\n                limit=page_length,\n                work_queue_filter=WorkQueueFilter(\n                    name=WorkQueueFilterName(startswith_=prefixes)\n                ),\n            )\n            if not new_queues:\n                break\n            work_queues += new_queues\n            current_page += 1\n\n        return work_queues\n\n    async def delete_work_queue_by_id(\n        self,\n        id: UUID,\n    ):\n        \"\"\"\n        Delete a work queue by its ID.\n\n        Args:\n            id: the id of the work queue to delete\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/work_queues/{id}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_block_type(self, block_type: BlockTypeCreate) -&gt; BlockType:\n        \"\"\"\n        Create a block type in the Prefect API.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_types/\",\n                json=block_type.dict(\n                    json_compatible=True, exclude_unset=True, exclude={\"id\"}\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockType.parse_obj(response.json())\n\n    async def create_block_schema(self, block_schema: BlockSchemaCreate) -&gt; BlockSchema:\n        \"\"\"\n        Create a block schema in the Prefect API.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_schemas/\",\n                json=block_schema.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_type\", \"checksum\"},\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockSchema.parse_obj(response.json())\n\n    async def create_block_document(\n        self,\n        block_document: Union[BlockDocument, BlockDocumentCreate],\n        include_secrets: bool = True,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Create a block document in the Prefect API. This data is used to configure a\n        corresponding Block.\n\n        Args:\n            include_secrets (bool): whether to include secret values\n                on the stored Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. Note Blocks may not work as expected if\n                this is set to `False`.\n        \"\"\"\n        if isinstance(block_document, BlockDocument):\n            block_document = BlockDocumentCreate.parse_obj(\n                block_document.dict(\n                    json_compatible=True,\n                    include_secrets=include_secrets,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_schema\", \"block_type\"},\n                ),\n            )\n\n        try:\n            response = await self._client.post(\n                \"/block_documents/\",\n                json=block_document.dict(\n                    json_compatible=True,\n                    include_secrets=include_secrets,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_schema\", \"block_type\"},\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def update_block_document(\n        self,\n        block_document_id: UUID,\n        block_document: BlockDocumentUpdate,\n    ):\n        \"\"\"\n        Update a block document in the Prefect API.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/block_documents/{block_document_id}\",\n                json=block_document.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    include={\"data\", \"merge_existing_data\", \"block_schema_id\"},\n                    include_secrets=True,\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_block_document(self, block_document_id: UUID):\n        \"\"\"\n        Delete a block document.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/block_documents/{block_document_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_block_type_by_slug(self, slug: str) -&gt; BlockType:\n        \"\"\"\n        Read a block type by its slug.\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/block_types/slug/{slug}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockType.parse_obj(response.json())\n\n    async def read_block_schema_by_checksum(\n        self, checksum: str, version: Optional[str] = None\n    ) -&gt; BlockSchema:\n        \"\"\"\n        Look up a block schema checksum\n        \"\"\"\n        try:\n            url = f\"/block_schemas/checksum/{checksum}\"\n            if version is not None:\n                url = f\"{url}?version={version}\"\n            response = await self._client.get(url)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockSchema.parse_obj(response.json())\n\n    async def update_block_type(self, block_type_id: UUID, block_type: BlockTypeUpdate):\n        \"\"\"\n        Update a block document in the Prefect API.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/block_types/{block_type_id}\",\n                json=block_type.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    include=BlockTypeUpdate.updatable_fields(),\n                    include_secrets=True,\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_block_type(self, block_type_id: UUID):\n        \"\"\"\n        Delete a block type.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/block_types/{block_type_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            elif (\n                e.response.status_code == status.HTTP_403_FORBIDDEN\n                and e.response.json()[\"detail\"]\n                == \"protected block types cannot be deleted.\"\n            ):\n                raise prefect.exceptions.ProtectedBlockError(\n                    \"Protected block types cannot be deleted.\"\n                ) from e\n            else:\n                raise\n\n    async def read_block_types(self) -&gt; List[BlockType]:\n        \"\"\"\n        Read all block types\n        Raises:\n            httpx.RequestError: if the block types were not found\n\n        Returns:\n            List of BlockTypes.\n        \"\"\"\n        response = await self._client.post(\"/block_types/filter\", json={})\n        return pydantic.parse_obj_as(List[BlockType], response.json())\n\n    async def read_block_schemas(self) -&gt; List[BlockSchema]:\n        \"\"\"\n        Read all block schemas\n        Raises:\n            httpx.RequestError: if a valid block schema was not found\n\n        Returns:\n            A BlockSchema.\n        \"\"\"\n        response = await self._client.post(\"/block_schemas/filter\", json={})\n        return pydantic.parse_obj_as(List[BlockSchema], response.json())\n\n    async def get_most_recent_block_schema_for_block_type(\n        self,\n        block_type_id: UUID,\n    ) -&gt; Optional[BlockSchema]:\n        \"\"\"\n        Fetches the most recent block schema for a specified block type ID.\n\n        Args:\n            block_type_id: The ID of the block type.\n\n        Raises:\n            httpx.RequestError: If the request fails for any reason.\n\n        Returns:\n            The most recent block schema or None.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_schemas/filter\",\n                json={\n                    \"block_schemas\": {\"block_type_id\": {\"any_\": [str(block_type_id)]}},\n                    \"limit\": 1,\n                },\n            )\n        except httpx.HTTPStatusError:\n            raise\n        return BlockSchema.parse_obj(response.json()[0]) if response.json() else None\n\n    async def read_block_document(\n        self,\n        block_document_id: UUID,\n        include_secrets: bool = True,\n    ):\n        \"\"\"\n        Read the block document with the specified ID.\n\n        Args:\n            block_document_id: the block document id\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Raises:\n            httpx.RequestError: if the block document was not found for any reason\n\n        Returns:\n            A block document or None.\n        \"\"\"\n        assert (\n            block_document_id is not None\n        ), \"Unexpected ID on block document. Was it persisted?\"\n        try:\n            response = await self._client.get(\n                f\"/block_documents/{block_document_id}\",\n                params=dict(include_secrets=include_secrets),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def read_block_document_by_name(\n        self,\n        name: str,\n        block_type_slug: str,\n        include_secrets: bool = True,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Read the block document with the specified name that corresponds to a\n        specific block type name.\n\n        Args:\n            name: The block document name.\n            block_type_slug: The block type slug.\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Raises:\n            httpx.RequestError: if the block document was not found for any reason\n\n        Returns:\n            A block document or None.\n        \"\"\"\n        try:\n            response = await self._client.get(\n                f\"/block_types/slug/{block_type_slug}/block_documents/name/{name}\",\n                params=dict(include_secrets=include_secrets),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def read_block_documents(\n        self,\n        block_schema_type: Optional[str] = None,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n        include_secrets: bool = True,\n    ):\n        \"\"\"\n        Read block documents\n\n        Args:\n            block_schema_type: an optional block schema type\n            offset: an offset\n            limit: the number of blocks to return\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Returns:\n            A list of block documents\n        \"\"\"\n        response = await self._client.post(\n            \"/block_documents/filter\",\n            json=dict(\n                block_schema_type=block_schema_type,\n                offset=offset,\n                limit=limit,\n                include_secrets=include_secrets,\n            ),\n        )\n        return pydantic.parse_obj_as(List[BlockDocument], response.json())\n\n    async def read_block_documents_by_type(\n        self,\n        block_type_slug: str,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n        include_secrets: bool = True,\n    ) -&gt; List[BlockDocument]:\n        \"\"\"Retrieve block documents by block type slug.\n\n        Args:\n            block_type_slug: The block type slug.\n            offset: an offset\n            limit: the number of blocks to return\n            include_secrets: whether to include secret values\n\n        Returns:\n            A list of block documents\n        \"\"\"\n        response = await self._client.get(\n            f\"/block_types/slug/{block_type_slug}/block_documents\",\n            params=dict(\n                offset=offset,\n                limit=limit,\n                include_secrets=include_secrets,\n            ),\n        )\n\n        return pydantic.parse_obj_as(List[BlockDocument], response.json())\n\n    async def create_deployment(\n        self,\n        flow_id: UUID,\n        name: str,\n        version: str = None,\n        schedule: SCHEDULE_TYPES = None,\n        schedules: List[DeploymentScheduleCreate] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        description: str = None,\n        work_queue_name: str = None,\n        work_pool_name: str = None,\n        tags: List[str] = None,\n        storage_document_id: UUID = None,\n        manifest_path: str = None,\n        path: str = None,\n        entrypoint: str = None,\n        infrastructure_document_id: UUID = None,\n        infra_overrides: Optional[Dict[str, Any]] = None,  # for backwards compat\n        parameter_openapi_schema: Optional[Dict[str, Any]] = None,\n        is_schedule_active: Optional[bool] = None,\n        paused: Optional[bool] = None,\n        pull_steps: Optional[List[dict]] = None,\n        enforce_parameter_schema: Optional[bool] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a deployment.\n\n        Args:\n            flow_id: the flow ID to create a deployment for\n            name: the name of the deployment\n            version: an optional version string for the deployment\n            schedule: an optional schedule to apply to the deployment\n            tags: an optional list of tags to apply to the deployment\n            storage_document_id: an reference to the storage block document\n                used for the deployed flow\n            infrastructure_document_id: an reference to the infrastructure block document\n                to use for this deployment\n            job_variables: A dictionary of dot delimited infrastructure overrides that\n                will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n                `namespace='prefect'`. This argument was previously named `infra_overrides`.\n                Both arguments are supported for backwards compatibility.\n\n        Raises:\n            httpx.RequestError: if the deployment was not created for any reason\n\n        Returns:\n            the ID of the deployment in the backend\n        \"\"\"\n        jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n        deployment_create = DeploymentCreate(\n            flow_id=flow_id,\n            name=name,\n            version=version,\n            parameters=dict(parameters or {}),\n            tags=list(tags or []),\n            work_queue_name=work_queue_name,\n            description=description,\n            storage_document_id=storage_document_id,\n            path=path,\n            entrypoint=entrypoint,\n            manifest_path=manifest_path,  # for backwards compat\n            infrastructure_document_id=infrastructure_document_id,\n            job_variables=jv,\n            parameter_openapi_schema=parameter_openapi_schema,\n            is_schedule_active=is_schedule_active,\n            paused=paused,\n            schedule=schedule,\n            schedules=schedules or [],\n            pull_steps=pull_steps,\n            enforce_parameter_schema=enforce_parameter_schema,\n        )\n\n        if work_pool_name is not None:\n            deployment_create.work_pool_name = work_pool_name\n\n        # Exclude newer fields that are not set to avoid compatibility issues\n        exclude = {\n            field\n            for field in [\"work_pool_name\", \"work_queue_name\"]\n            if field not in deployment_create.__fields_set__\n        }\n\n        if deployment_create.is_schedule_active is None:\n            exclude.add(\"is_schedule_active\")\n\n        if deployment_create.paused is None:\n            exclude.add(\"paused\")\n\n        if deployment_create.pull_steps is None:\n            exclude.add(\"pull_steps\")\n\n        if deployment_create.enforce_parameter_schema is None:\n            exclude.add(\"enforce_parameter_schema\")\n\n        json = deployment_create.dict(json_compatible=True, exclude=exclude)\n        response = await self._client.post(\n            \"/deployments/\",\n            json=json,\n        )\n        deployment_id = response.json().get(\"id\")\n        if not deployment_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(deployment_id)\n\n    async def update_schedule(self, deployment_id: UUID, active: bool = True):\n        path = \"set_schedule_active\" if active else \"set_schedule_inactive\"\n        await self._client.post(\n            f\"/deployments/{deployment_id}/{path}\",\n        )\n\n    async def set_deployment_paused_state(self, deployment_id: UUID, paused: bool):\n        await self._client.patch(\n            f\"/deployments/{deployment_id}\", json={\"paused\": paused}\n        )\n\n    async def update_deployment(\n        self,\n        deployment: Deployment,\n        schedule: SCHEDULE_TYPES = None,\n        is_schedule_active: bool = None,\n    ):\n        deployment_update = DeploymentUpdate(\n            version=deployment.version,\n            schedule=schedule if schedule is not None else deployment.schedule,\n            is_schedule_active=(\n                is_schedule_active\n                if is_schedule_active is not None\n                else deployment.is_schedule_active\n            ),\n            description=deployment.description,\n            work_queue_name=deployment.work_queue_name,\n            tags=deployment.tags,\n            manifest_path=deployment.manifest_path,\n            path=deployment.path,\n            entrypoint=deployment.entrypoint,\n            parameters=deployment.parameters,\n            storage_document_id=deployment.storage_document_id,\n            infrastructure_document_id=deployment.infrastructure_document_id,\n            job_variables=deployment.job_variables,\n            enforce_parameter_schema=deployment.enforce_parameter_schema,\n        )\n\n        if getattr(deployment, \"work_pool_name\", None) is not None:\n            deployment_update.work_pool_name = deployment.work_pool_name\n\n        exclude = set()\n        if deployment.enforce_parameter_schema is None:\n            exclude.add(\"enforce_parameter_schema\")\n\n        await self._client.patch(\n            f\"/deployments/{deployment.id}\",\n            json=deployment_update.dict(json_compatible=True, exclude=exclude),\n        )\n\n    async def _create_deployment_from_schema(self, schema: DeploymentCreate) -&gt; UUID:\n        \"\"\"\n        Create a deployment from a prepared `DeploymentCreate` schema.\n        \"\"\"\n        # TODO: We are likely to remove this method once we have considered the\n        #       packaging interface for deployments further.\n        response = await self._client.post(\n            \"/deployments/\", json=schema.dict(json_compatible=True)\n        )\n        deployment_id = response.json().get(\"id\")\n        if not deployment_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(deployment_id)\n\n    async def read_deployment(\n        self,\n        deployment_id: UUID,\n    ) -&gt; DeploymentResponse:\n        \"\"\"\n        Query the Prefect API for a deployment by id.\n\n        Args:\n            deployment_id: the deployment ID of interest\n\n        Returns:\n            a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/{deployment_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return DeploymentResponse.parse_obj(response.json())\n\n    async def read_deployment_by_name(\n        self,\n        name: str,\n    ) -&gt; DeploymentResponse:\n        \"\"\"\n        Query the Prefect API for a deployment by name.\n\n        Args:\n            name: A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            a Deployment model representation of the deployment\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return DeploymentResponse.parse_obj(response.json())\n\n    async def read_deployments(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        limit: int = None,\n        sort: DeploymentSort = None,\n        offset: int = 0,\n    ) -&gt; List[DeploymentResponse]:\n        \"\"\"\n        Query the Prefect API for deployments. Only deployments matching all\n        the provided criteria will be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            limit: a limit for the deployment query\n            offset: an offset for the deployment query\n\n        Returns:\n            a list of Deployment model representations\n                of the deployments\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n            \"sort\": sort,\n        }\n\n        response = await self._client.post(\"/deployments/filter\", json=body)\n        return pydantic.parse_obj_as(List[DeploymentResponse], response.json())\n\n    async def delete_deployment(\n        self,\n        deployment_id: UUID,\n    ):\n        \"\"\"\n        Delete deployment by id.\n\n        Args:\n            deployment_id: The deployment id of interest.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/deployments/{deployment_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_deployment_schedules(\n        self,\n        deployment_id: UUID,\n        schedules: List[Tuple[SCHEDULE_TYPES, bool]],\n    ) -&gt; List[DeploymentSchedule]:\n        \"\"\"\n        Create deployment schedules.\n\n        Args:\n            deployment_id: the deployment ID\n            schedules: a list of tuples containing the schedule to create\n                       and whether or not it should be active.\n\n        Raises:\n            httpx.RequestError: if the schedules were not created for any reason\n\n        Returns:\n            the list of schedules created in the backend\n        \"\"\"\n        deployment_schedule_create = [\n            DeploymentScheduleCreate(schedule=schedule[0], active=schedule[1])\n            for schedule in schedules\n        ]\n\n        json = [\n            deployment_schedule_create.dict(json_compatible=True)\n            for deployment_schedule_create in deployment_schedule_create\n        ]\n        response = await self._client.post(\n            f\"/deployments/{deployment_id}/schedules\", json=json\n        )\n        return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n\n    async def read_deployment_schedules(\n        self,\n        deployment_id: UUID,\n    ) -&gt; List[DeploymentSchedule]:\n        \"\"\"\n        Query the Prefect API for a deployment's schedules.\n\n        Args:\n            deployment_id: the deployment ID\n\n        Returns:\n            a list of DeploymentSchedule model representations of the deployment schedules\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/{deployment_id}/schedules\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n\n    async def update_deployment_schedule(\n        self,\n        deployment_id: UUID,\n        schedule_id: UUID,\n        active: Optional[bool] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n    ):\n        \"\"\"\n        Update a deployment schedule by ID.\n\n        Args:\n            deployment_id: the deployment ID\n            schedule_id: the deployment schedule ID of interest\n            active: whether or not the schedule should be active\n            schedule: the cron, rrule, or interval schedule this deployment schedule should use\n        \"\"\"\n        kwargs = {}\n        if active is not None:\n            kwargs[\"active\"] = active\n        if schedule is not None:\n            kwargs[\"schedule\"] = schedule\n\n        deployment_schedule_update = DeploymentScheduleUpdate(**kwargs)\n        json = deployment_schedule_update.dict(json_compatible=True, exclude_unset=True)\n\n        try:\n            await self._client.patch(\n                f\"/deployments/{deployment_id}/schedules/{schedule_id}\", json=json\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_deployment_schedule(\n        self,\n        deployment_id: UUID,\n        schedule_id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a deployment schedule.\n\n        Args:\n            deployment_id: the deployment ID\n            schedule_id: the ID of the deployment schedule to delete.\n\n        Raises:\n            httpx.RequestError: if the schedules were not deleted for any reason\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/deployments/{deployment_id}/schedules/{schedule_id}\"\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n        \"\"\"\n        Query the Prefect API for a flow run by id.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n\n        Returns:\n            a Flow Run model representation of the flow run\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return FlowRun.parse_obj(response.json())\n\n    async def resume_flow_run(\n        self, flow_run_id: UUID, run_input: Optional[Dict] = None\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Resumes a paused flow run.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n            run_input: the input to resume the flow run with\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        try:\n            response = await self._client.post(\n                f\"/flow_runs/{flow_run_id}/resume\", json={\"run_input\": run_input}\n            )\n        except httpx.HTTPStatusError:\n            raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_flow_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Query the Prefect API for flow runs. Only flow runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flow runs\n            limit: limit for the flow run query\n            offset: offset for the flow run query\n\n        Returns:\n            a list of Flow Run model representations\n                of the flow runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/flow_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    async def set_flow_run_state(\n        self,\n        flow_run_id: UUID,\n        state: \"prefect.states.State\",\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a flow run.\n\n        Args:\n            flow_run_id: the id of the flow run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.flow_run_id = flow_run_id\n        state_create.state_details.transition_id = uuid4()\n        try:\n            response = await self._client.post(\n                f\"/flow_runs/{flow_run_id}/set_state\",\n                json=dict(state=state_create.dict(json_compatible=True), force=force),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_flow_run_states(\n        self, flow_run_id: UUID\n    ) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a flow run\n\n        Args:\n            flow_run_id: the id of the flow run\n\n        Returns:\n            a list of State model representations\n                of the flow run states\n        \"\"\"\n        response = await self._client.get(\n            \"/flow_run_states/\", params=dict(flow_run_id=str(flow_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n\n    async def set_task_run_name(self, task_run_id: UUID, name: str):\n        task_run_data = TaskRunUpdate(name=name)\n        return await self._client.patch(\n            f\"/task_runs/{task_run_id}\",\n            json=task_run_data.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def create_task_run(\n        self,\n        task: \"TaskObject[P, R]\",\n        flow_run_id: Optional[UUID],\n        dynamic_key: str,\n        name: Optional[str] = None,\n        extra_tags: Optional[Iterable[str]] = None,\n        state: Optional[prefect.states.State[R]] = None,\n        task_inputs: Optional[\n            Dict[\n                str,\n                List[\n                    Union[\n                        TaskRunResult,\n                        Parameter,\n                        Constant,\n                    ]\n                ],\n            ]\n        ] = None,\n    ) -&gt; TaskRun:\n        \"\"\"\n        Create a task run\n\n        Args:\n            task: The Task to run\n            flow_run_id: The flow run id with which to associate the task run\n            dynamic_key: A key unique to this particular run of a Task within the flow\n            name: An optional name for the task run\n            extra_tags: an optional list of extra tags to apply to the task run in\n                addition to `task.tags`\n            state: The initial state for the run. If not provided, defaults to\n                `Pending` for now. Should always be a `Scheduled` type.\n            task_inputs: the set of inputs passed to the task\n\n        Returns:\n            The created task run.\n        \"\"\"\n        tags = set(task.tags).union(extra_tags or [])\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        task_run_data = TaskRunCreate(\n            name=name,\n            flow_run_id=flow_run_id,\n            task_key=task.task_key,\n            dynamic_key=dynamic_key,\n            tags=list(tags),\n            task_version=task.version,\n            empirical_policy=TaskRunPolicy(\n                retries=task.retries,\n                retry_delay=task.retry_delay_seconds,\n                retry_jitter_factor=task.retry_jitter_factor,\n            ),\n            state=state.to_state_create(),\n            task_inputs=task_inputs or {},\n        )\n\n        response = await self._client.post(\n            \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n        )\n        return TaskRun.parse_obj(response.json())\n\n    async def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n        \"\"\"\n        Query the Prefect API for a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n\n        Returns:\n            a Task Run model representation of the task run\n        \"\"\"\n        response = await self._client.get(f\"/task_runs/{task_run_id}\")\n        return TaskRun.parse_obj(response.json())\n\n    async def read_task_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        sort: TaskRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[TaskRun]:\n        \"\"\"\n        Query the Prefect API for task runs. Only task runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            sort: sort criteria for the task runs\n            limit: a limit for the task run query\n            offset: an offset for the task run query\n\n        Returns:\n            a list of Task Run model representations\n                of the task runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/task_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[TaskRun], response.json())\n\n    async def delete_task_run(self, task_run_id: UUID) -&gt; None:\n        \"\"\"\n        Delete a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/task_runs/{task_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def set_task_run_state(\n        self,\n        task_run_id: UUID,\n        state: prefect.states.State,\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a task run.\n\n        Args:\n            task_run_id: the id of the task run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.task_run_id = task_run_id\n        response = await self._client.post(\n            f\"/task_runs/{task_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_task_run_states(\n        self, task_run_id: UUID\n    ) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a task run\n\n        Args:\n            task_run_id: the id of the task run\n\n        Returns:\n            a list of State model representations of the task run states\n        \"\"\"\n        response = await self._client.get(\n            \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n\n    async def create_logs(self, logs: Iterable[Union[LogCreate, dict]]) -&gt; None:\n        \"\"\"\n        Create logs for a flow or task run\n\n        Args:\n            logs: An iterable of `LogCreate` objects or already json-compatible dicts\n        \"\"\"\n        serialized_logs = [\n            log.dict(json_compatible=True) if isinstance(log, LogCreate) else log\n            for log in logs\n        ]\n        await self._client.post(\"/logs/\", json=serialized_logs)\n\n    async def create_flow_run_notification_policy(\n        self,\n        block_document_id: UUID,\n        is_active: bool = True,\n        tags: List[str] = None,\n        state_names: List[str] = None,\n        message_template: Optional[str] = None,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a notification policy for flow runs\n\n        Args:\n            block_document_id: The block document UUID\n            is_active: Whether the notification policy is active\n            tags: List of flow tags\n            state_names: List of state names\n            message_template: Notification message template\n        \"\"\"\n        if tags is None:\n            tags = []\n        if state_names is None:\n            state_names = []\n\n        policy = FlowRunNotificationPolicyCreate(\n            block_document_id=block_document_id,\n            is_active=is_active,\n            tags=tags,\n            state_names=state_names,\n            message_template=message_template,\n        )\n        response = await self._client.post(\n            \"/flow_run_notification_policies/\",\n            json=policy.dict(json_compatible=True),\n        )\n\n        policy_id = response.json().get(\"id\")\n        if not policy_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(policy_id)\n\n    async def delete_flow_run_notification_policy(\n        self,\n        id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a flow run notification policy by id.\n\n        Args:\n            id: UUID of the flow run notification policy to delete.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/flow_run_notification_policies/{id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def update_flow_run_notification_policy(\n        self,\n        id: UUID,\n        block_document_id: Optional[UUID] = None,\n        is_active: Optional[bool] = None,\n        tags: Optional[List[str]] = None,\n        state_names: Optional[List[str]] = None,\n        message_template: Optional[str] = None,\n    ) -&gt; None:\n        \"\"\"\n        Update a notification policy for flow runs\n\n        Args:\n            id: UUID of the notification policy\n            block_document_id: The block document UUID\n            is_active: Whether the notification policy is active\n            tags: List of flow tags\n            state_names: List of state names\n            message_template: Notification message template\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        params = {}\n        if block_document_id is not None:\n            params[\"block_document_id\"] = block_document_id\n        if is_active is not None:\n            params[\"is_active\"] = is_active\n        if tags is not None:\n            params[\"tags\"] = tags\n        if state_names is not None:\n            params[\"state_names\"] = state_names\n        if message_template is not None:\n            params[\"message_template\"] = message_template\n\n        policy = FlowRunNotificationPolicyUpdate(**params)\n\n        try:\n            await self._client.patch(\n                f\"/flow_run_notification_policies/{id}\",\n                json=policy.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_flow_run_notification_policies(\n        self,\n        flow_run_notification_policy_filter: FlowRunNotificationPolicyFilter,\n        limit: Optional[int] = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRunNotificationPolicy]:\n        \"\"\"\n        Query the Prefect API for flow run notification policies. Only policies matching all criteria will\n        be returned.\n\n        Args:\n            flow_run_notification_policy_filter: filter criteria for notification policies\n            limit: a limit for the notification policies query\n            offset: an offset for the notification policies query\n\n        Returns:\n            a list of FlowRunNotificationPolicy model representations\n                of the notification policies\n        \"\"\"\n        body = {\n            \"flow_run_notification_policy_filter\": (\n                flow_run_notification_policy_filter.dict(json_compatible=True)\n                if flow_run_notification_policy_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\n            \"/flow_run_notification_policies/filter\", json=body\n        )\n        return pydantic.parse_obj_as(List[FlowRunNotificationPolicy], response.json())\n\n    async def read_logs(\n        self,\n        log_filter: LogFilter = None,\n        limit: int = None,\n        offset: int = None,\n        sort: LogSort = LogSort.TIMESTAMP_ASC,\n    ) -&gt; List[Log]:\n        \"\"\"\n        Read flow and task run logs.\n        \"\"\"\n        body = {\n            \"logs\": log_filter.dict(json_compatible=True) if log_filter else None,\n            \"limit\": limit,\n            \"offset\": offset,\n            \"sort\": sort,\n        }\n\n        response = await self._client.post(\"/logs/filter\", json=body)\n        return pydantic.parse_obj_as(List[Log], response.json())\n\n    async def resolve_datadoc(self, datadoc: DataDocument) -&gt; Any:\n        \"\"\"\n        Recursively decode possibly nested data documents.\n\n        \"server\" encoded documents will be retrieved from the server.\n\n        Args:\n            datadoc: The data document to resolve\n\n        Returns:\n            a decoded object, the innermost data\n        \"\"\"\n        if not isinstance(datadoc, DataDocument):\n            raise TypeError(\n                f\"`resolve_datadoc` received invalid type {type(datadoc).__name__}\"\n            )\n\n        async def resolve_inner(data):\n            if isinstance(data, bytes):\n                try:\n                    data = DataDocument.parse_raw(data)\n                except pydantic.ValidationError:\n                    return data\n\n            if isinstance(data, DataDocument):\n                return await resolve_inner(data.decode())\n\n            return data\n\n        return await resolve_inner(datadoc)\n\n    async def send_worker_heartbeat(\n        self,\n        work_pool_name: str,\n        worker_name: str,\n        heartbeat_interval_seconds: Optional[float] = None,\n    ):\n        \"\"\"\n        Sends a worker heartbeat for a given work pool.\n\n        Args:\n            work_pool_name: The name of the work pool to heartbeat against.\n            worker_name: The name of the worker sending the heartbeat.\n        \"\"\"\n        await self._client.post(\n            f\"/work_pools/{work_pool_name}/workers/heartbeat\",\n            json={\n                \"name\": worker_name,\n                \"heartbeat_interval_seconds\": heartbeat_interval_seconds,\n            },\n        )\n\n    async def read_workers_for_work_pool(\n        self,\n        work_pool_name: str,\n        worker_filter: Optional[WorkerFilter] = None,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n    ) -&gt; List[Worker]:\n        \"\"\"\n        Reads workers for a given work pool.\n\n        Args:\n            work_pool_name: The name of the work pool for which to get\n                member workers.\n            worker_filter: Criteria by which to filter workers.\n            limit: Limit for the worker query.\n            offset: Limit for the worker query.\n        \"\"\"\n        response = await self._client.post(\n            f\"/work_pools/{work_pool_name}/workers/filter\",\n            json={\n                \"worker_filter\": (\n                    worker_filter.dict(json_compatible=True, exclude_unset=True)\n                    if worker_filter\n                    else None\n                ),\n                \"offset\": offset,\n                \"limit\": limit,\n            },\n        )\n\n        return pydantic.parse_obj_as(List[Worker], response.json())\n\n    async def read_work_pool(self, work_pool_name: str) -&gt; WorkPool:\n        \"\"\"\n        Reads information for a given work pool\n\n        Args:\n            work_pool_name: The name of the work pool to for which to get\n                information.\n\n        Returns:\n            Information about the requested work pool.\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_pools/{work_pool_name}\")\n            return pydantic.parse_obj_as(WorkPool, response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_work_pools(\n        self,\n        limit: Optional[int] = None,\n        offset: int = 0,\n        work_pool_filter: Optional[WorkPoolFilter] = None,\n    ) -&gt; List[WorkPool]:\n        \"\"\"\n        Reads work pools.\n\n        Args:\n            limit: Limit for the work pool query.\n            offset: Offset for the work pool query.\n            work_pool_filter: Criteria by which to filter work pools.\n\n        Returns:\n            A list of work pools.\n        \"\"\"\n\n        body = {\n            \"limit\": limit,\n            \"offset\": offset,\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n        }\n        response = await self._client.post(\"/work_pools/filter\", json=body)\n        return pydantic.parse_obj_as(List[WorkPool], response.json())\n\n    async def create_work_pool(\n        self,\n        work_pool: WorkPoolCreate,\n        overwrite: bool = False,\n    ) -&gt; WorkPool:\n        \"\"\"\n        Creates a work pool with the provided configuration.\n\n        Args:\n            work_pool: Desired configuration for the new work pool.\n            overwrite: Whether to overwrite an existing work pool with the same name.\n\n        Returns:\n            Information about the newly created work pool.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/work_pools/\",\n                json=work_pool.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                if overwrite:\n                    existing_work_pool = await self.read_work_pool(\n                        work_pool_name=work_pool.name\n                    )\n                    if existing_work_pool.type != work_pool.type:\n                        warnings.warn(\n                            \"Overwriting work pool type is not supported. Ignoring provided type.\",\n                            category=UserWarning,\n                        )\n                    await self.update_work_pool(\n                        work_pool_name=work_pool.name,\n                        work_pool=WorkPoolUpdate.parse_obj(\n                            work_pool.dict(exclude={\"name\", \"type\"})\n                        ),\n                    )\n                    response = await self._client.get(f\"/work_pools/{work_pool.name}\")\n                else:\n                    raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n\n        return pydantic.parse_obj_as(WorkPool, response.json())\n\n    async def update_work_pool(\n        self,\n        work_pool_name: str,\n        work_pool: WorkPoolUpdate,\n    ):\n        \"\"\"\n        Updates a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool to update.\n            work_pool: Fields to update in the work pool.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/work_pools/{work_pool_name}\",\n                json=work_pool.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_work_pool(\n        self,\n        work_pool_name: str,\n    ):\n        \"\"\"\n        Deletes a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool to delete.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/work_pools/{work_pool_name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_work_queues(\n        self,\n        work_pool_name: Optional[str] = None,\n        work_queue_filter: Optional[WorkQueueFilter] = None,\n        limit: Optional[int] = None,\n        offset: Optional[int] = None,\n    ) -&gt; List[WorkQueue]:\n        \"\"\"\n        Retrieves queues for a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool for which to get queues.\n            work_queue_filter: Criteria by which to filter queues.\n            limit: Limit for the queue query.\n            offset: Limit for the queue query.\n\n        Returns:\n            List of queues for the specified work pool.\n        \"\"\"\n        json = {\n            \"work_queues\": (\n                work_queue_filter.dict(json_compatible=True, exclude_unset=True)\n                if work_queue_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        if work_pool_name:\n            try:\n                response = await self._client.post(\n                    f\"/work_pools/{work_pool_name}/queues/filter\",\n                    json=json,\n                )\n            except httpx.HTTPStatusError as e:\n                if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                    raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n                else:\n                    raise\n        else:\n            response = await self._client.post(\"/work_queues/filter\", json=json)\n\n        return pydantic.parse_obj_as(List[WorkQueue], response.json())\n\n    async def get_scheduled_flow_runs_for_deployments(\n        self,\n        deployment_ids: List[UUID],\n        scheduled_before: Optional[datetime.datetime] = None,\n        limit: Optional[int] = None,\n    ):\n        body: Dict[str, Any] = dict(deployment_ids=[str(id) for id in deployment_ids])\n        if scheduled_before:\n            body[\"scheduled_before\"] = str(scheduled_before)\n        if limit:\n            body[\"limit\"] = limit\n\n        response = await self._client.post(\n            \"/deployments/get_scheduled_flow_runs\",\n            json=body,\n        )\n\n        return pydantic.parse_obj_as(List[FlowRunResponse], response.json())\n\n    async def get_scheduled_flow_runs_for_work_pool(\n        self,\n        work_pool_name: str,\n        work_queue_names: Optional[List[str]] = None,\n        scheduled_before: Optional[datetime.datetime] = None,\n    ) -&gt; List[WorkerFlowRunResponse]:\n        \"\"\"\n        Retrieves scheduled flow runs for the provided set of work pool queues.\n\n        Args:\n            work_pool_name: The name of the work pool that the work pool\n                queues are associated with.\n            work_queue_names: The names of the work pool queues from which\n                to get scheduled flow runs.\n            scheduled_before: Datetime used to filter returned flow runs. Flow runs\n                scheduled for after the given datetime string will not be returned.\n\n        Returns:\n            A list of worker flow run responses containing information about the\n            retrieved flow runs.\n        \"\"\"\n        body: Dict[str, Any] = {}\n        if work_queue_names is not None:\n            body[\"work_queue_names\"] = list(work_queue_names)\n        if scheduled_before:\n            body[\"scheduled_before\"] = str(scheduled_before)\n\n        response = await self._client.post(\n            f\"/work_pools/{work_pool_name}/get_scheduled_flow_runs\",\n            json=body,\n        )\n        return pydantic.parse_obj_as(List[WorkerFlowRunResponse], response.json())\n\n    async def create_artifact(\n        self,\n        artifact: ArtifactCreate,\n    ) -&gt; Artifact:\n        \"\"\"\n        Creates an artifact with the provided configuration.\n\n        Args:\n            artifact: Desired configuration for the new artifact.\n        Returns:\n            Information about the newly created artifact.\n        \"\"\"\n\n        response = await self._client.post(\n            \"/artifacts/\",\n            json=artifact.dict(json_compatible=True, exclude_unset=True),\n        )\n\n        return pydantic.parse_obj_as(Artifact, response.json())\n\n    async def read_artifacts(\n        self,\n        *,\n        artifact_filter: ArtifactFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        sort: ArtifactSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[Artifact]:\n        \"\"\"\n        Query the Prefect API for artifacts. Only artifacts matching all criteria will\n        be returned.\n        Args:\n            artifact_filter: filter criteria for artifacts\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            sort: sort criteria for the artifacts\n            limit: limit for the artifact query\n            offset: offset for the artifact query\n        Returns:\n            a list of Artifact model representations of the artifacts\n        \"\"\"\n        body = {\n            \"artifacts\": (\n                artifact_filter.dict(json_compatible=True) if artifact_filter else None\n            ),\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/artifacts/filter\", json=body)\n        return pydantic.parse_obj_as(List[Artifact], response.json())\n\n    async def read_latest_artifacts(\n        self,\n        *,\n        artifact_filter: ArtifactCollectionFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        sort: ArtifactCollectionSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[ArtifactCollection]:\n        \"\"\"\n        Query the Prefect API for artifacts. Only artifacts matching all criteria will\n        be returned.\n        Args:\n            artifact_filter: filter criteria for artifacts\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            sort: sort criteria for the artifacts\n            limit: limit for the artifact query\n            offset: offset for the artifact query\n        Returns:\n            a list of Artifact model representations of the artifacts\n        \"\"\"\n        body = {\n            \"artifacts\": (\n                artifact_filter.dict(json_compatible=True) if artifact_filter else None\n            ),\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/artifacts/latest/filter\", json=body)\n        return pydantic.parse_obj_as(List[ArtifactCollection], response.json())\n\n    async def delete_artifact(self, artifact_id: UUID) -&gt; None:\n        \"\"\"\n        Deletes an artifact with the provided id.\n\n        Args:\n            artifact_id: The id of the artifact to delete.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/artifacts/{artifact_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_variable(self, variable: VariableCreate) -&gt; Variable:\n        \"\"\"\n        Creates an variable with the provided configuration.\n\n        Args:\n            variable: Desired configuration for the new variable.\n        Returns:\n            Information about the newly created variable.\n        \"\"\"\n        response = await self._client.post(\n            \"/variables/\",\n            json=variable.dict(json_compatible=True, exclude_unset=True),\n        )\n        return Variable(**response.json())\n\n    async def update_variable(self, variable: VariableUpdate) -&gt; None:\n        \"\"\"\n        Updates a variable with the provided configuration.\n\n        Args:\n            variable: Desired configuration for the updated variable.\n        Returns:\n            Information about the updated variable.\n        \"\"\"\n        await self._client.patch(\n            f\"/variables/name/{variable.name}\",\n            json=variable.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def read_variable_by_name(self, name: str) -&gt; Optional[Variable]:\n        \"\"\"Reads a variable by name. Returns None if no variable is found.\"\"\"\n        try:\n            response = await self._client.get(f\"/variables/name/{name}\")\n            return Variable(**response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                return None\n            else:\n                raise\n\n    async def delete_variable_by_name(self, name: str):\n        \"\"\"Deletes a variable by name.\"\"\"\n        try:\n            await self._client.delete(f\"/variables/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_variables(self, limit: int = None) -&gt; List[Variable]:\n        \"\"\"Reads all variables.\"\"\"\n        response = await self._client.post(\"/variables/filter\", json={\"limit\": limit})\n        return pydantic.parse_obj_as(List[Variable], response.json())\n\n    async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n        \"\"\"Reads worker metadata stored in Prefect collection registry.\"\"\"\n        response = await self._client.get(\"collections/views/aggregate-worker-metadata\")\n        response.raise_for_status()\n        return response.json()\n\n    async def increment_concurrency_slots(\n        self, names: List[str], slots: int, mode: str\n    ) -&gt; httpx.Response:\n        return await self._client.post(\n            \"/v2/concurrency_limits/increment\",\n            json={\"names\": names, \"slots\": slots, \"mode\": mode},\n        )\n\n    async def release_concurrency_slots(\n        self, names: List[str], slots: int, occupancy_seconds: float\n    ) -&gt; httpx.Response:\n        return await self._client.post(\n            \"/v2/concurrency_limits/decrement\",\n            json={\n                \"names\": names,\n                \"slots\": slots,\n                \"occupancy_seconds\": occupancy_seconds,\n            },\n        )\n\n    async def create_global_concurrency_limit(\n        self, concurrency_limit: GlobalConcurrencyLimitCreate\n    ) -&gt; UUID:\n        response = await self._client.post(\n            \"/v2/concurrency_limits/\",\n            json=concurrency_limit.dict(json_compatible=True, exclude_unset=True),\n        )\n        return UUID(response.json()[\"id\"])\n\n    async def update_global_concurrency_limit(\n        self, name: str, concurrency_limit: GlobalConcurrencyLimitUpdate\n    ) -&gt; httpx.Response:\n        try:\n            response = await self._client.patch(\n                f\"/v2/concurrency_limits/{name}\",\n                json=concurrency_limit.dict(json_compatible=True, exclude_unset=True),\n            )\n            return response\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_global_concurrency_limit_by_name(\n        self, name: str\n    ) -&gt; httpx.Response:\n        try:\n            response = await self._client.delete(f\"/v2/concurrency_limits/{name}\")\n            return response\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_global_concurrency_limit_by_name(\n        self, name: str\n    ) -&gt; GlobalConcurrencyLimitResponse:\n        try:\n            response = await self._client.get(f\"/v2/concurrency_limits/{name}\")\n            return GlobalConcurrencyLimitResponse.parse_obj(response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_global_concurrency_limits(\n        self, limit: int = 10, offset: int = 0\n    ) -&gt; List[GlobalConcurrencyLimitResponse]:\n        response = await self._client.post(\n            \"/v2/concurrency_limits/filter\",\n            json={\n                \"limit\": limit,\n                \"offset\": offset,\n            },\n        )\n        return pydantic.parse_obj_as(\n            List[GlobalConcurrencyLimitResponse], response.json()\n        )\n\n    async def create_flow_run_input(\n        self, flow_run_id: UUID, key: str, value: str, sender: Optional[str] = None\n    ):\n        \"\"\"\n        Creates a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n            value: The input value.\n            sender: The sender of the input.\n        \"\"\"\n\n        # Initialize the input to ensure that the key is valid.\n        FlowRunInput(flow_run_id=flow_run_id, key=key, value=value)\n\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/input\",\n            json={\"key\": key, \"value\": value, \"sender\": sender},\n        )\n        response.raise_for_status()\n\n    async def filter_flow_run_input(\n        self, flow_run_id: UUID, key_prefix: str, limit: int, exclude_keys: Set[str]\n    ) -&gt; List[FlowRunInput]:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/input/filter\",\n            json={\n                \"prefix\": key_prefix,\n                \"limit\": limit,\n                \"exclude_keys\": list(exclude_keys),\n            },\n        )\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[FlowRunInput], response.json())\n\n    async def read_flow_run_input(self, flow_run_id: UUID, key: str) -&gt; str:\n        \"\"\"\n        Reads a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n        \"\"\"\n        response = await self._client.get(f\"/flow_runs/{flow_run_id}/input/{key}\")\n        response.raise_for_status()\n        return response.content.decode()\n\n    async def delete_flow_run_input(self, flow_run_id: UUID, key: str):\n        \"\"\"\n        Deletes a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n        \"\"\"\n        response = await self._client.delete(f\"/flow_runs/{flow_run_id}/input/{key}\")\n        response.raise_for_status()\n\n    def _raise_for_unsupported_automations(self) -&gt; NoReturn:\n        if not PREFECT_EXPERIMENTAL_EVENTS:\n            raise RuntimeError(\n                \"The current server and client configuration does not support \"\n                \"events.  Enable experimental events support with the \"\n                \"PREFECT_EXPERIMENTAL_EVENTS setting.\"\n            )\n        else:\n            raise RuntimeError(\n                \"The current server and client configuration does not support \"\n                \"automations.  Enable experimental automations with the \"\n                \"PREFECT_API_SERVICES_TRIGGERS_ENABLED setting.\"\n            )\n\n    async def create_automation(self, automation: AutomationCore) -&gt; UUID:\n        \"\"\"Creates an automation in Prefect Cloud.\"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.post(\n            \"/automations/\",\n            json=automation.dict(json_compatible=True),\n        )\n\n        return UUID(response.json()[\"id\"])\n\n    async def update_automation(self, automation_id: UUID, automation: AutomationCore):\n        \"\"\"Updates an automation in Prefect Cloud.\"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n        response = await self._client.put(\n            f\"/automations/{automation_id}\",\n            json=automation.dict(json_compatible=True, exclude_unset=True),\n        )\n        response.raise_for_status\n\n    async def read_automations(self) -&gt; List[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.post(\"/automations/filter\")\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def find_automation(\n        self, id_or_name: Union[str, UUID], exit_if_not_found: bool = True\n    ) -&gt; Optional[Automation]:\n        if isinstance(id_or_name, str):\n            try:\n                id = UUID(id_or_name)\n            except ValueError:\n                id = None\n        elif isinstance(id_or_name, UUID):\n            id = id_or_name\n\n        if id:\n            try:\n                automation = await self.read_automation(id)\n                return automation\n            except prefect.exceptions.HTTPStatusError as e:\n                if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                    raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n\n        automations = await self.read_automations()\n\n        # Look for it by an exact name\n        for automation in automations:\n            if automation.name == id_or_name:\n                return automation\n\n        # Look for it by a case-insensitive name\n        for automation in automations:\n            if automation.name.lower() == id_or_name.lower():\n                return automation\n\n        return None\n\n    async def read_automation(self, automation_id: UUID) -&gt; Optional[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.get(f\"/automations/{automation_id}\")\n        if response.status_code == 404:\n            return None\n        response.raise_for_status()\n        return Automation.parse_obj(response.json())\n\n    async def read_automations_by_name(self, name: str) -&gt; List[Automation]:\n        \"\"\"\n        Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.\n\n        Args:\n            name: the name of the automation to query\n\n        Returns:\n            a list of Automation model representations of the automations\n        \"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n        automation_filter = filters.AutomationFilter(name=dict(any_=[name]))\n\n        response = await self._client.post(\n            \"/automations/filter\",\n            json={\n                \"sort\": sorting.AutomationSort.UPDATED_DESC,\n                \"automations\": automation_filter.dict(json_compatible=True)\n                if automation_filter\n                else None,\n            },\n        )\n\n        response.raise_for_status()\n\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def pause_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.patch(\n            f\"/automations/{automation_id}\", json={\"enabled\": False}\n        )\n        response.raise_for_status()\n\n    async def resume_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.patch(\n            f\"/automations/{automation_id}\", json={\"enabled\": True}\n        )\n        response.raise_for_status()\n\n    async def delete_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.delete(f\"/automations/{automation_id}\")\n        if response.status_code == 404:\n            return\n\n        response.raise_for_status()\n\n    async def read_resource_related_automations(\n        self, resource_id: str\n    ) -&gt; List[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.get(f\"/automations/related-to/{resource_id}\")\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def delete_resource_owned_automations(self, resource_id: str):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        await self._client.delete(f\"/automations/owned-by/{resource_id}\")\n\n    async def __aenter__(self):\n        \"\"\"\n        Start the client.\n\n        If the client is already started, this will raise an exception.\n\n        If the client is already closed, this will raise an exception. Use a new client\n        instance instead.\n        \"\"\"\n        if self._closed:\n            # httpx.AsyncClient does not allow reuse so we will not either.\n            raise RuntimeError(\n                \"The client cannot be started again after closing. \"\n                \"Retrieve a new client with `get_client()` instead.\"\n            )\n\n        if self._started:\n            # httpx.AsyncClient does not allow reentrancy so we will not either.\n            raise RuntimeError(\"The client cannot be started more than once.\")\n\n        self._loop = asyncio.get_running_loop()\n        await self._exit_stack.__aenter__()\n\n        # Enter a lifespan context if using an ephemeral application.\n        # See https://github.com/encode/httpx/issues/350\n        if self._ephemeral_app and self.manage_lifespan:\n            self._ephemeral_lifespan = await self._exit_stack.enter_async_context(\n                app_lifespan_context(self._ephemeral_app)\n            )\n\n        if self._ephemeral_app:\n            self.logger.debug(\n                \"Using ephemeral application with database at \"\n                f\"{PREFECT_API_DATABASE_CONNECTION_URL.value()}\"\n            )\n        else:\n            self.logger.debug(f\"Connecting to API at {self.api_url}\")\n\n        # Enter the httpx client's context\n        await self._exit_stack.enter_async_context(self._client)\n\n        self._started = True\n\n        return self\n\n    async def __aexit__(self, *exc_info):\n        \"\"\"\n        Shutdown the client.\n        \"\"\"\n        self._closed = True\n        return await self._exit_stack.__aexit__(*exc_info)\n\n    def __enter__(self):\n        raise RuntimeError(\n            \"The `PrefectClient` must be entered with an async context. Use 'async \"\n            \"with PrefectClient(...)' not 'with PrefectClient(...)'\"\n        )\n\n    def __exit__(self, *_):\n        assert False, \"This should never be called but must be defined for __enter__\"\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.api_url","title":"<code>api_url: httpx.URL</code>  <code>property</code>","text":"<p>Get the base URL for the API.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.api_healthcheck","title":"<code>api_healthcheck</code>  <code>async</code>","text":"<p>Attempts to connect to the API and returns the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def api_healthcheck(self) -&gt; Optional[Exception]:\n    \"\"\"\n    Attempts to connect to the API and returns the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    try:\n        await self._client.get(\"/health\")\n        return None\n    except Exception as exc:\n        return exc\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.hello","title":"<code>hello</code>  <code>async</code>","text":"<p>Send a GET request to /hello for testing purposes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def hello(self) -&gt; httpx.Response:\n    \"\"\"\n    Send a GET request to /hello for testing purposes.\n    \"\"\"\n    return await self._client.get(\"/hello\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>a Flow object</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow: a [Flow][prefect.flows.Flow] object\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    return await self.create_flow_from_name(flow.name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_from_name","title":"<code>create_flow_from_name</code>  <code>async</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of the new flow</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow_name: the name of the new flow\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    flow_data = FlowCreate(name=flow_name)\n    response = await self._client.post(\n        \"/flows/\", json=flow_data.dict(json_compatible=True)\n    )\n\n    flow_id = response.json().get(\"id\")\n    if not flow_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    # Return the id of the created flow\n    return UUID(flow_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_id</code> <code>UUID</code> <p>the flow ID of interest</p> required <p>Returns:</p> Type Description <code>Flow</code> <p>a Flow model representation of the flow</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow(self, flow_id: UUID) -&gt; Flow:\n    \"\"\"\n    Query the Prefect API for a flow by id.\n\n    Args:\n        flow_id: the flow ID of interest\n\n    Returns:\n        a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow\n    \"\"\"\n    response = await self._client.get(f\"/flows/{flow_id}\")\n    return Flow.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Query the Prefect API for flows. Only flows matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowSort</code> <p>sort criteria for the flows</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[Flow]</code> <p>a list of Flow model representations of the flows</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flows(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[Flow]:\n    \"\"\"\n    Query the Prefect API for flows. Only flows matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flows\n        limit: limit for the flow query\n        offset: offset for the flow query\n\n    Returns:\n        a list of Flow model representations of the flows\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/flows/filter\", json=body)\n    return pydantic.parse_obj_as(List[Flow], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow by name.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of a flow</p> required <p>Returns:</p> Type Description <code>Flow</code> <p>a fully hydrated Flow model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_by_name(\n    self,\n    flow_name: str,\n) -&gt; Flow:\n    \"\"\"\n    Query the Prefect API for a flow by name.\n\n    Args:\n        flow_name: the name of a flow\n\n    Returns:\n        a fully hydrated Flow model\n    \"\"\"\n    response = await self._client.get(f\"/flows/name/{flow_name}\")\n    return Flow.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_from_deployment","title":"<code>create_flow_run_from_deployment</code>  <code>async</code>","text":"<p>Create a flow run for a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>The deployment ID to create the flow run from</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run. Merged with the deployment defaults</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>state</code> <code>State</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>name</code> <code>str</code> <p>An optional name for the flow run. If not provided, the server will generate a name.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>An optional iterable of tags to apply to the flow run; these tags are merged with the deployment's tags.</p> <code>None</code> <code>idempotency_key</code> <code>str</code> <p>Optional idempotency key for creation of the flow run. If the key matches the key of an existing flow run, the existing run will be returned instead of creating a new one.</p> <code>None</code> <code>parent_task_run_id</code> <code>UUID</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>work_queue_name</code> <code>str</code> <p>An optional work queue name to add this run to. If not provided, will default to the deployment's set work queue.  If one is provided that does not exist, a new work queue will be created within the deployment's work pool.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Optional variables that will be supplied to the flow run job.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_from_deployment(\n    self,\n    deployment_id: UUID,\n    *,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    state: prefect.states.State = None,\n    name: str = None,\n    tags: Iterable[str] = None,\n    idempotency_key: str = None,\n    parent_task_run_id: UUID = None,\n    work_queue_name: str = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a deployment.\n\n    Args:\n        deployment_id: The deployment ID to create the flow run from\n        parameters: Parameter overrides for this flow run. Merged with the\n            deployment defaults\n        context: Optional run context data\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n        name: An optional name for the flow run. If not provided, the server will\n            generate a name.\n        tags: An optional iterable of tags to apply to the flow run; these tags\n            are merged with the deployment's tags.\n        idempotency_key: Optional idempotency key for creation of the flow run.\n            If the key matches the key of an existing flow run, the existing run will\n            be returned instead of creating a new one.\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        work_queue_name: An optional work queue name to add this run to. If not provided,\n            will default to the deployment's set work queue.  If one is provided that does not\n            exist, a new work queue will be created within the deployment's work pool.\n        job_variables: Optional variables that will be supplied to the flow run job.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n    state = state or prefect.states.Scheduled()\n    tags = tags or []\n\n    flow_run_create = DeploymentFlowRunCreate(\n        parameters=parameters,\n        context=context,\n        state=state.to_state_create(),\n        tags=tags,\n        name=name,\n        idempotency_key=idempotency_key,\n        parent_task_run_id=parent_task_run_id,\n        job_variables=job_variables,\n    )\n\n    # done separately to avoid including this field in payloads sent to older API versions\n    if work_queue_name:\n        flow_run_create.work_queue_name = work_queue_name\n\n    response = await self._client.post(\n        f\"/deployments/{deployment_id}/create_flow_run\",\n        json=flow_run_create.dict(json_compatible=True, exclude_unset=True),\n    )\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Create a flow run for a flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>The flow model to create the flow run for</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow run</p> <code>None</code> <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run.</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>a list of tags to apply to this flow run</p> <code>None</code> <code>parent_task_run_id</code> <code>Optional[UUID]</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>state</code> <code>Optional[State]</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run(\n    self,\n    flow: \"FlowObject\",\n    name: Optional[str] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    tags: Optional[Iterable[str]] = None,\n    parent_task_run_id: Optional[UUID] = None,\n    state: Optional[\"prefect.states.State\"] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a flow.\n\n    Args:\n        flow: The flow model to create the flow run for\n        name: An optional name for the flow run\n        parameters: Parameter overrides for this flow run.\n        context: Optional run context data\n        tags: a list of tags to apply to this flow run\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    # Retrieve the flow id\n    flow_id = await self.create_flow(flow)\n\n    flow_run_create = FlowRunCreate(\n        flow_id=flow_id,\n        flow_version=flow.version,\n        name=name,\n        parameters=parameters,\n        context=context,\n        tags=list(tags or []),\n        parent_task_run_id=parent_task_run_id,\n        state=state.to_state_create(),\n        empirical_policy=FlowRunPolicy(\n            retries=flow.retries,\n            retry_delay=flow.retry_delay_seconds,\n        ),\n    )\n\n    flow_run_create_json = flow_run_create.dict(json_compatible=True)\n    response = await self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n    flow_run = FlowRun.parse_obj(response.json())\n\n    # Restore the parameters to the local objects to retain expectations about\n    # Python objects\n    flow_run.parameters = parameters\n\n    return flow_run\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Update a flow run's details.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The identifier for the flow run to update.</p> required <code>flow_version</code> <code>Optional[str]</code> <p>A new version string for the flow run.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of parameter values for the flow run. This will not be merged with any existing parameters.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>A new name for the flow run.</p> <code>None</code> <code>empirical_policy</code> <code>Optional[FlowRunPolicy]</code> <p>A new flow run orchestration policy. This will not be merged with any existing policy.</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>An iterable of new tags for the flow run. These will not be merged with any existing tags.</p> <code>None</code> <code>infrastructure_pid</code> <code>Optional[str]</code> <p>The id of flow run as returned by an infrastructure block.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>an <code>httpx.Response</code> object from the PATCH request</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_flow_run(\n    self,\n    flow_run_id: UUID,\n    flow_version: Optional[str] = None,\n    parameters: Optional[dict] = None,\n    name: Optional[str] = None,\n    tags: Optional[Iterable[str]] = None,\n    empirical_policy: Optional[FlowRunPolicy] = None,\n    infrastructure_pid: Optional[str] = None,\n    job_variables: Optional[dict] = None,\n) -&gt; httpx.Response:\n    \"\"\"\n    Update a flow run's details.\n\n    Args:\n        flow_run_id: The identifier for the flow run to update.\n        flow_version: A new version string for the flow run.\n        parameters: A dictionary of parameter values for the flow run. This will not\n            be merged with any existing parameters.\n        name: A new name for the flow run.\n        empirical_policy: A new flow run orchestration policy. This will not be\n            merged with any existing policy.\n        tags: An iterable of new tags for the flow run. These will not be merged with\n            any existing tags.\n        infrastructure_pid: The id of flow run as returned by an\n            infrastructure block.\n\n    Returns:\n        an `httpx.Response` object from the PATCH request\n    \"\"\"\n    params = {}\n    if flow_version is not None:\n        params[\"flow_version\"] = flow_version\n    if parameters is not None:\n        params[\"parameters\"] = parameters\n    if name is not None:\n        params[\"name\"] = name\n    if tags is not None:\n        params[\"tags\"] = tags\n    if empirical_policy is not None:\n        params[\"empirical_policy\"] = empirical_policy\n    if infrastructure_pid:\n        params[\"infrastructure_pid\"] = infrastructure_pid\n    if job_variables is not None:\n        params[\"job_variables\"] = job_variables\n\n    flow_run_data = FlowRunUpdate(**params)\n\n    return await self._client.patch(\n        f\"/flow_runs/{flow_run_id}\",\n        json=flow_run_data.dict(json_compatible=True, exclude_unset=True),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by UUID.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run UUID of interest.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run(\n    self,\n    flow_run_id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a flow run by UUID.\n\n    Args:\n        flow_run_id: The flow run UUID of interest.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_concurrency_limit","title":"<code>create_concurrency_limit</code>  <code>async</code>","text":"<p>Create a tag concurrency limit in the Prefect API. These limits govern concurrently running tasks.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <code>concurrency_limit</code> <code>int</code> <p>the maximum number of concurrent task runs for a given tag</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the concurrency limit was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the concurrency limit in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_concurrency_limit(\n    self,\n    tag: str,\n    concurrency_limit: int,\n) -&gt; UUID:\n    \"\"\"\n    Create a tag concurrency limit in the Prefect API. These limits govern concurrently\n    running tasks.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n        concurrency_limit: the maximum number of concurrent task runs for a given tag\n\n    Raises:\n        httpx.RequestError: if the concurrency limit was not created for any reason\n\n    Returns:\n        the ID of the concurrency limit in the backend\n    \"\"\"\n\n    concurrency_limit_create = ConcurrencyLimitCreate(\n        tag=tag,\n        concurrency_limit=concurrency_limit,\n    )\n    response = await self._client.post(\n        \"/concurrency_limits/\",\n        json=concurrency_limit_create.dict(json_compatible=True),\n    )\n\n    concurrency_limit_id = response.json().get(\"id\")\n\n    if not concurrency_limit_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(concurrency_limit_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_concurrency_limit_by_tag","title":"<code>read_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Read the concurrency limit set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>if the concurrency limit was not created for any reason</p> <p>Returns:</p> Type Description <p>the concurrency limit set on a specific tag</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_concurrency_limit_by_tag(\n    self,\n    tag: str,\n):\n    \"\"\"\n    Read the concurrency limit set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: if the concurrency limit was not created for any reason\n\n    Returns:\n        the concurrency limit set on a specific tag\n    \"\"\"\n    try:\n        response = await self._client.get(\n            f\"/concurrency_limits/tag/{tag}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    concurrency_limit_id = response.json().get(\"id\")\n\n    if not concurrency_limit_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    concurrency_limit = ConcurrencyLimit.parse_obj(response.json())\n    return concurrency_limit\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_concurrency_limits","title":"<code>read_concurrency_limits</code>  <code>async</code>","text":"<p>Lists concurrency limits set on task run tags.</p> <p>Parameters:</p> Name Type Description Default <code>limit</code> <code>int</code> <p>the maximum number of concurrency limits returned</p> required <code>offset</code> <code>int</code> <p>the concurrency limit query offset</p> required <p>Returns:</p> Type Description <p>a list of concurrency limits</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_concurrency_limits(\n    self,\n    limit: int,\n    offset: int,\n):\n    \"\"\"\n    Lists concurrency limits set on task run tags.\n\n    Args:\n        limit: the maximum number of concurrency limits returned\n        offset: the concurrency limit query offset\n\n    Returns:\n        a list of concurrency limits\n    \"\"\"\n\n    body = {\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/concurrency_limits/filter\", json=body)\n    return pydantic.parse_obj_as(List[ConcurrencyLimit], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.reset_concurrency_limit_by_tag","title":"<code>reset_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Resets the concurrency limit slots set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <code>slot_override</code> <code>Optional[List[Union[UUID, str]]]</code> <p>a list of task run IDs that are currently using a concurrency slot, please check that any task run IDs included in <code>slot_override</code> are currently running, otherwise those concurrency slots will never be released.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def reset_concurrency_limit_by_tag(\n    self,\n    tag: str,\n    slot_override: Optional[List[Union[UUID, str]]] = None,\n):\n    \"\"\"\n    Resets the concurrency limit slots set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n        slot_override: a list of task run IDs that are currently using a\n            concurrency slot, please check that any task run IDs included in\n            `slot_override` are currently running, otherwise those concurrency\n            slots will never be released.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    \"\"\"\n    if slot_override is not None:\n        slot_override = [str(slot) for slot in slot_override]\n\n    try:\n        await self._client.post(\n            f\"/concurrency_limits/tag/{tag}/reset\",\n            json=dict(slot_override=slot_override),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_concurrency_limit_by_tag","title":"<code>delete_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Delete the concurrency limit set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_concurrency_limit_by_tag(\n    self,\n    tag: str,\n):\n    \"\"\"\n    Delete the concurrency limit set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/concurrency_limits/tag/{tag}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_work_queue","title":"<code>create_work_queue</code>  <code>async</code>","text":"<p>Create a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>a unique name for the work queue</p> required <code>tags</code> <code>Optional[List[str]]</code> <p>will be included in the queue. This option will be removed on 2023-02-23.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>An optional description for the work queue.</p> <code>None</code> <code>is_paused</code> <code>Optional[bool]</code> <p>Whether or not the work queue is paused.</p> <code>None</code> <code>concurrency_limit</code> <code>Optional[int]</code> <p>An optional concurrency limit for the work queue.</p> <code>None</code> <code>priority</code> <code>Optional[int]</code> <p>The queue's priority. Lower values are higher priority (1 is the highest).</p> <code>None</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this queue.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectAlreadyExists</code> <p>If request returns 409</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>WorkQueue</code> <p>The created work queue</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_work_queue(\n    self,\n    name: str,\n    tags: Optional[List[str]] = None,\n    description: Optional[str] = None,\n    is_paused: Optional[bool] = None,\n    concurrency_limit: Optional[int] = None,\n    priority: Optional[int] = None,\n    work_pool_name: Optional[str] = None,\n) -&gt; WorkQueue:\n    \"\"\"\n    Create a work queue.\n\n    Args:\n        name: a unique name for the work queue\n        tags: DEPRECATED: an optional list of tags to filter on; only work scheduled with these tags\n            will be included in the queue. This option will be removed on 2023-02-23.\n        description: An optional description for the work queue.\n        is_paused: Whether or not the work queue is paused.\n        concurrency_limit: An optional concurrency limit for the work queue.\n        priority: The queue's priority. Lower values are higher priority (1 is the highest).\n        work_pool_name: The name of the work pool to use for this queue.\n\n    Raises:\n        prefect.exceptions.ObjectAlreadyExists: If request returns 409\n        httpx.RequestError: If request fails\n\n    Returns:\n        The created work queue\n    \"\"\"\n    if tags:\n        warnings.warn(\n            (\n                \"The use of tags for creating work queue filters is deprecated.\"\n                \" This option will be removed on 2023-02-23.\"\n            ),\n            DeprecationWarning,\n        )\n        filter = QueueFilter(tags=tags)\n    else:\n        filter = None\n    create_model = WorkQueueCreate(name=name, filter=filter)\n    if description is not None:\n        create_model.description = description\n    if is_paused is not None:\n        create_model.is_paused = is_paused\n    if concurrency_limit is not None:\n        create_model.concurrency_limit = concurrency_limit\n    if priority is not None:\n        create_model.priority = priority\n\n    data = create_model.dict(json_compatible=True)\n    try:\n        if work_pool_name is not None:\n            response = await self._client.post(\n                f\"/work_pools/{work_pool_name}/queues\", json=data\n            )\n        else:\n            response = await self._client.post(\"/work_queues/\", json=data)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        elif e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue_by_name","title":"<code>read_work_queue_by_name</code>  <code>async</code>","text":"<p>Read a work queue by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>a unique name for the work queue</p> required <code>work_pool_name</code> <code>str</code> <p>the name of the work pool the queue belongs to.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>if no work queue is found</p> <code>HTTPStatusError</code> <p>other status errors</p> <p>Returns:</p> Name Type Description <code>WorkQueue</code> <code>WorkQueue</code> <p>a work queue API object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue_by_name(\n    self,\n    name: str,\n    work_pool_name: Optional[str] = None,\n) -&gt; WorkQueue:\n    \"\"\"\n    Read a work queue by name.\n\n    Args:\n        name (str): a unique name for the work queue\n        work_pool_name (str, optional): the name of the work pool\n            the queue belongs to.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: if no work queue is found\n        httpx.HTTPStatusError: other status errors\n\n    Returns:\n        WorkQueue: a work queue API object\n    \"\"\"\n    try:\n        if work_pool_name is not None:\n            response = await self._client.get(\n                f\"/work_pools/{work_pool_name}/queues/{name}\"\n            )\n        else:\n            response = await self._client.get(f\"/work_queues/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_work_queue","title":"<code>update_work_queue</code>  <code>async</code>","text":"<p>Update properties of a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the ID of the work queue to update</p> required <code>**kwargs</code> <p>the fields to update</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if no kwargs are provided</p> <code>ObjectNotFound</code> <p>if request returns 404</p> <code>RequestError</code> <p>if the request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_work_queue(self, id: UUID, **kwargs):\n    \"\"\"\n    Update properties of a work queue.\n\n    Args:\n        id: the ID of the work queue to update\n        **kwargs: the fields to update\n\n    Raises:\n        ValueError: if no kwargs are provided\n        prefect.exceptions.ObjectNotFound: if request returns 404\n        httpx.RequestError: if the request fails\n\n    \"\"\"\n    if not kwargs:\n        raise ValueError(\"No fields provided to update.\")\n\n    data = WorkQueueUpdate(**kwargs).dict(json_compatible=True, exclude_unset=True)\n    try:\n        await self._client.patch(f\"/work_queues/{id}\", json=data)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_runs_in_work_queue","title":"<code>get_runs_in_work_queue</code>  <code>async</code>","text":"<p>Read flow runs off a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to read from</p> required <code>limit</code> <code>int</code> <p>a limit on the number of runs to return</p> <code>10</code> <code>scheduled_before</code> <code>datetime</code> <p>a timestamp; only runs scheduled before this time will be returned. Defaults to now.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>List[FlowRun]: a list of FlowRun objects read from the queue</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_runs_in_work_queue(\n    self,\n    id: UUID,\n    limit: int = 10,\n    scheduled_before: datetime.datetime = None,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Read flow runs off a work queue.\n\n    Args:\n        id: the id of the work queue to read from\n        limit: a limit on the number of runs to return\n        scheduled_before: a timestamp; only runs scheduled before this time will be returned.\n            Defaults to now.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        List[FlowRun]: a list of FlowRun objects read from the queue\n    \"\"\"\n    if scheduled_before is None:\n        scheduled_before = pendulum.now(\"UTC\")\n\n    try:\n        response = await self._client.post(\n            f\"/work_queues/{id}/get_runs\",\n            json={\n                \"limit\": limit,\n                \"scheduled_before\": scheduled_before.isoformat(),\n            },\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue","title":"<code>read_work_queue</code>  <code>async</code>","text":"<p>Read a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to load</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Name Type Description <code>WorkQueue</code> <code>WorkQueue</code> <p>an instantiated WorkQueue object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue(\n    self,\n    id: UUID,\n) -&gt; WorkQueue:\n    \"\"\"\n    Read a work queue.\n\n    Args:\n        id: the id of the work queue to load\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        WorkQueue: an instantiated WorkQueue object\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_queues/{id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue_status","title":"<code>read_work_queue_status</code>  <code>async</code>","text":"<p>Read a work queue status.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to load</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Name Type Description <code>WorkQueueStatus</code> <code>WorkQueueStatusDetail</code> <p>an instantiated WorkQueueStatus object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue_status(\n    self,\n    id: UUID,\n) -&gt; WorkQueueStatusDetail:\n    \"\"\"\n    Read a work queue status.\n\n    Args:\n        id: the id of the work queue to load\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        WorkQueueStatus: an instantiated WorkQueueStatus object\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_queues/{id}/status\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueueStatusDetail.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.match_work_queues","title":"<code>match_work_queues</code>  <code>async</code>","text":"<p>Query the Prefect API for work queues with names with a specific prefix.</p> <p>Parameters:</p> Name Type Description Default <code>prefixes</code> <code>List[str]</code> <p>a list of strings used to match work queue name prefixes</p> required <code>work_pool_name</code> <code>Optional[str]</code> <p>an optional work pool name to scope the query to</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>a list of WorkQueue model representations of the work queues</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def match_work_queues(\n    self,\n    prefixes: List[str],\n    work_pool_name: Optional[str] = None,\n) -&gt; List[WorkQueue]:\n    \"\"\"\n    Query the Prefect API for work queues with names with a specific prefix.\n\n    Args:\n        prefixes: a list of strings used to match work queue name prefixes\n        work_pool_name: an optional work pool name to scope the query to\n\n    Returns:\n        a list of WorkQueue model representations\n            of the work queues\n    \"\"\"\n    page_length = 100\n    current_page = 0\n    work_queues = []\n\n    while True:\n        new_queues = await self.read_work_queues(\n            work_pool_name=work_pool_name,\n            offset=current_page * page_length,\n            limit=page_length,\n            work_queue_filter=WorkQueueFilter(\n                name=WorkQueueFilterName(startswith_=prefixes)\n            ),\n        )\n        if not new_queues:\n            break\n        work_queues += new_queues\n        current_page += 1\n\n    return work_queues\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_work_queue_by_id","title":"<code>delete_work_queue_by_id</code>  <code>async</code>","text":"<p>Delete a work queue by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to delete</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If requests fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_work_queue_by_id(\n    self,\n    id: UUID,\n):\n    \"\"\"\n    Delete a work queue by its ID.\n\n    Args:\n        id: the id of the work queue to delete\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/work_queues/{id}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_type","title":"<code>create_block_type</code>  <code>async</code>","text":"<p>Create a block type in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_type(self, block_type: BlockTypeCreate) -&gt; BlockType:\n    \"\"\"\n    Create a block type in the Prefect API.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_types/\",\n            json=block_type.dict(\n                json_compatible=True, exclude_unset=True, exclude={\"id\"}\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockType.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_schema","title":"<code>create_block_schema</code>  <code>async</code>","text":"<p>Create a block schema in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_schema(self, block_schema: BlockSchemaCreate) -&gt; BlockSchema:\n    \"\"\"\n    Create a block schema in the Prefect API.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_schemas/\",\n            json=block_schema.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                exclude={\"id\", \"block_type\", \"checksum\"},\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockSchema.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_document","title":"<code>create_block_document</code>  <code>async</code>","text":"<p>Create a block document in the Prefect API. This data is used to configure a corresponding Block.</p> <p>Parameters:</p> Name Type Description Default <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the stored Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. Note Blocks may not work as expected if this is set to <code>False</code>.</p> <code>True</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_document(\n    self,\n    block_document: Union[BlockDocument, BlockDocumentCreate],\n    include_secrets: bool = True,\n) -&gt; BlockDocument:\n    \"\"\"\n    Create a block document in the Prefect API. This data is used to configure a\n    corresponding Block.\n\n    Args:\n        include_secrets (bool): whether to include secret values\n            on the stored Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. Note Blocks may not work as expected if\n            this is set to `False`.\n    \"\"\"\n    if isinstance(block_document, BlockDocument):\n        block_document = BlockDocumentCreate.parse_obj(\n            block_document.dict(\n                json_compatible=True,\n                include_secrets=include_secrets,\n                exclude_unset=True,\n                exclude={\"id\", \"block_schema\", \"block_type\"},\n            ),\n        )\n\n    try:\n        response = await self._client.post(\n            \"/block_documents/\",\n            json=block_document.dict(\n                json_compatible=True,\n                include_secrets=include_secrets,\n                exclude_unset=True,\n                exclude={\"id\", \"block_schema\", \"block_type\"},\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_block_document","title":"<code>update_block_document</code>  <code>async</code>","text":"<p>Update a block document in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_block_document(\n    self,\n    block_document_id: UUID,\n    block_document: BlockDocumentUpdate,\n):\n    \"\"\"\n    Update a block document in the Prefect API.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/block_documents/{block_document_id}\",\n            json=block_document.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                include={\"data\", \"merge_existing_data\", \"block_schema_id\"},\n                include_secrets=True,\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_block_document","title":"<code>delete_block_document</code>  <code>async</code>","text":"<p>Delete a block document.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_block_document(self, block_document_id: UUID):\n    \"\"\"\n    Delete a block document.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/block_documents/{block_document_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_type_by_slug","title":"<code>read_block_type_by_slug</code>  <code>async</code>","text":"<p>Read a block type by its slug.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_type_by_slug(self, slug: str) -&gt; BlockType:\n    \"\"\"\n    Read a block type by its slug.\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/block_types/slug/{slug}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockType.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_schema_by_checksum","title":"<code>read_block_schema_by_checksum</code>  <code>async</code>","text":"<p>Look up a block schema checksum</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_schema_by_checksum(\n    self, checksum: str, version: Optional[str] = None\n) -&gt; BlockSchema:\n    \"\"\"\n    Look up a block schema checksum\n    \"\"\"\n    try:\n        url = f\"/block_schemas/checksum/{checksum}\"\n        if version is not None:\n            url = f\"{url}?version={version}\"\n        response = await self._client.get(url)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockSchema.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_block_type","title":"<code>update_block_type</code>  <code>async</code>","text":"<p>Update a block document in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_block_type(self, block_type_id: UUID, block_type: BlockTypeUpdate):\n    \"\"\"\n    Update a block document in the Prefect API.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/block_types/{block_type_id}\",\n            json=block_type.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                include=BlockTypeUpdate.updatable_fields(),\n                include_secrets=True,\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_block_type","title":"<code>delete_block_type</code>  <code>async</code>","text":"<p>Delete a block type.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_block_type(self, block_type_id: UUID):\n    \"\"\"\n    Delete a block type.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/block_types/{block_type_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        elif (\n            e.response.status_code == status.HTTP_403_FORBIDDEN\n            and e.response.json()[\"detail\"]\n            == \"protected block types cannot be deleted.\"\n        ):\n            raise prefect.exceptions.ProtectedBlockError(\n                \"Protected block types cannot be deleted.\"\n            ) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_types","title":"<code>read_block_types</code>  <code>async</code>","text":"<p>Read all block types Raises:     httpx.RequestError: if the block types were not found</p> <p>Returns:</p> Type Description <code>List[BlockType]</code> <p>List of BlockTypes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_types(self) -&gt; List[BlockType]:\n    \"\"\"\n    Read all block types\n    Raises:\n        httpx.RequestError: if the block types were not found\n\n    Returns:\n        List of BlockTypes.\n    \"\"\"\n    response = await self._client.post(\"/block_types/filter\", json={})\n    return pydantic.parse_obj_as(List[BlockType], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_schemas","title":"<code>read_block_schemas</code>  <code>async</code>","text":"<p>Read all block schemas Raises:     httpx.RequestError: if a valid block schema was not found</p> <p>Returns:</p> Type Description <code>List[BlockSchema]</code> <p>A BlockSchema.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_schemas(self) -&gt; List[BlockSchema]:\n    \"\"\"\n    Read all block schemas\n    Raises:\n        httpx.RequestError: if a valid block schema was not found\n\n    Returns:\n        A BlockSchema.\n    \"\"\"\n    response = await self._client.post(\"/block_schemas/filter\", json={})\n    return pydantic.parse_obj_as(List[BlockSchema], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_most_recent_block_schema_for_block_type","title":"<code>get_most_recent_block_schema_for_block_type</code>  <code>async</code>","text":"<p>Fetches the most recent block schema for a specified block type ID.</p> <p>Parameters:</p> Name Type Description Default <code>block_type_id</code> <code>UUID</code> <p>The ID of the block type.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>If the request fails for any reason.</p> <p>Returns:</p> Type Description <code>Optional[BlockSchema]</code> <p>The most recent block schema or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_most_recent_block_schema_for_block_type(\n    self,\n    block_type_id: UUID,\n) -&gt; Optional[BlockSchema]:\n    \"\"\"\n    Fetches the most recent block schema for a specified block type ID.\n\n    Args:\n        block_type_id: The ID of the block type.\n\n    Raises:\n        httpx.RequestError: If the request fails for any reason.\n\n    Returns:\n        The most recent block schema or None.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_schemas/filter\",\n            json={\n                \"block_schemas\": {\"block_type_id\": {\"any_\": [str(block_type_id)]}},\n                \"limit\": 1,\n            },\n        )\n    except httpx.HTTPStatusError:\n        raise\n    return BlockSchema.parse_obj(response.json()[0]) if response.json() else None\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_document","title":"<code>read_block_document</code>  <code>async</code>","text":"<p>Read the block document with the specified ID.</p> <p>Parameters:</p> Name Type Description Default <code>block_document_id</code> <code>UUID</code> <p>the block document id</p> required <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the block document was not found for any reason</p> <p>Returns:</p> Type Description <p>A block document or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_document(\n    self,\n    block_document_id: UUID,\n    include_secrets: bool = True,\n):\n    \"\"\"\n    Read the block document with the specified ID.\n\n    Args:\n        block_document_id: the block document id\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Raises:\n        httpx.RequestError: if the block document was not found for any reason\n\n    Returns:\n        A block document or None.\n    \"\"\"\n    assert (\n        block_document_id is not None\n    ), \"Unexpected ID on block document. Was it persisted?\"\n    try:\n        response = await self._client.get(\n            f\"/block_documents/{block_document_id}\",\n            params=dict(include_secrets=include_secrets),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_document_by_name","title":"<code>read_block_document_by_name</code>  <code>async</code>","text":"<p>Read the block document with the specified name that corresponds to a specific block type name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The block document name.</p> required <code>block_type_slug</code> <code>str</code> <p>The block type slug.</p> required <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the block document was not found for any reason</p> <p>Returns:</p> Type Description <code>BlockDocument</code> <p>A block document or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_document_by_name(\n    self,\n    name: str,\n    block_type_slug: str,\n    include_secrets: bool = True,\n) -&gt; BlockDocument:\n    \"\"\"\n    Read the block document with the specified name that corresponds to a\n    specific block type name.\n\n    Args:\n        name: The block document name.\n        block_type_slug: The block type slug.\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Raises:\n        httpx.RequestError: if the block document was not found for any reason\n\n    Returns:\n        A block document or None.\n    \"\"\"\n    try:\n        response = await self._client.get(\n            f\"/block_types/slug/{block_type_slug}/block_documents/name/{name}\",\n            params=dict(include_secrets=include_secrets),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_documents","title":"<code>read_block_documents</code>  <code>async</code>","text":"<p>Read block documents</p> <p>Parameters:</p> Name Type Description Default <code>block_schema_type</code> <code>Optional[str]</code> <p>an optional block schema type</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>an offset</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>the number of blocks to return</p> <code>None</code> <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Returns:</p> Type Description <p>A list of block documents</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_documents(\n    self,\n    block_schema_type: Optional[str] = None,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n    include_secrets: bool = True,\n):\n    \"\"\"\n    Read block documents\n\n    Args:\n        block_schema_type: an optional block schema type\n        offset: an offset\n        limit: the number of blocks to return\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Returns:\n        A list of block documents\n    \"\"\"\n    response = await self._client.post(\n        \"/block_documents/filter\",\n        json=dict(\n            block_schema_type=block_schema_type,\n            offset=offset,\n            limit=limit,\n            include_secrets=include_secrets,\n        ),\n    )\n    return pydantic.parse_obj_as(List[BlockDocument], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_documents_by_type","title":"<code>read_block_documents_by_type</code>  <code>async</code>","text":"<p>Retrieve block documents by block type slug.</p> <p>Parameters:</p> Name Type Description Default <code>block_type_slug</code> <code>str</code> <p>The block type slug.</p> required <code>offset</code> <code>Optional[int]</code> <p>an offset</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>the number of blocks to return</p> <code>None</code> <code>include_secrets</code> <code>bool</code> <p>whether to include secret values</p> <code>True</code> <p>Returns:</p> Type Description <code>List[BlockDocument]</code> <p>A list of block documents</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_documents_by_type(\n    self,\n    block_type_slug: str,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n    include_secrets: bool = True,\n) -&gt; List[BlockDocument]:\n    \"\"\"Retrieve block documents by block type slug.\n\n    Args:\n        block_type_slug: The block type slug.\n        offset: an offset\n        limit: the number of blocks to return\n        include_secrets: whether to include secret values\n\n    Returns:\n        A list of block documents\n    \"\"\"\n    response = await self._client.get(\n        f\"/block_types/slug/{block_type_slug}/block_documents\",\n        params=dict(\n            offset=offset,\n            limit=limit,\n            include_secrets=include_secrets,\n        ),\n    )\n\n    return pydantic.parse_obj_as(List[BlockDocument], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Create a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>flow_id</code> <code>UUID</code> <p>the flow ID to create a deployment for</p> required <code>name</code> <code>str</code> <p>the name of the deployment</p> required <code>version</code> <code>str</code> <p>an optional version string for the deployment</p> <code>None</code> <code>schedule</code> <code>SCHEDULE_TYPES</code> <p>an optional schedule to apply to the deployment</p> <code>None</code> <code>tags</code> <code>List[str]</code> <p>an optional list of tags to apply to the deployment</p> <code>None</code> <code>storage_document_id</code> <code>UUID</code> <p>an reference to the storage block document used for the deployed flow</p> <code>None</code> <code>infrastructure_document_id</code> <code>UUID</code> <p>an reference to the infrastructure block document to use for this deployment</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code>. This argument was previously named <code>infra_overrides</code>. Both arguments are supported for backwards compatibility.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the deployment was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the deployment in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_deployment(\n    self,\n    flow_id: UUID,\n    name: str,\n    version: str = None,\n    schedule: SCHEDULE_TYPES = None,\n    schedules: List[DeploymentScheduleCreate] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    description: str = None,\n    work_queue_name: str = None,\n    work_pool_name: str = None,\n    tags: List[str] = None,\n    storage_document_id: UUID = None,\n    manifest_path: str = None,\n    path: str = None,\n    entrypoint: str = None,\n    infrastructure_document_id: UUID = None,\n    infra_overrides: Optional[Dict[str, Any]] = None,  # for backwards compat\n    parameter_openapi_schema: Optional[Dict[str, Any]] = None,\n    is_schedule_active: Optional[bool] = None,\n    paused: Optional[bool] = None,\n    pull_steps: Optional[List[dict]] = None,\n    enforce_parameter_schema: Optional[bool] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a deployment.\n\n    Args:\n        flow_id: the flow ID to create a deployment for\n        name: the name of the deployment\n        version: an optional version string for the deployment\n        schedule: an optional schedule to apply to the deployment\n        tags: an optional list of tags to apply to the deployment\n        storage_document_id: an reference to the storage block document\n            used for the deployed flow\n        infrastructure_document_id: an reference to the infrastructure block document\n            to use for this deployment\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`. This argument was previously named `infra_overrides`.\n            Both arguments are supported for backwards compatibility.\n\n    Raises:\n        httpx.RequestError: if the deployment was not created for any reason\n\n    Returns:\n        the ID of the deployment in the backend\n    \"\"\"\n    jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n    deployment_create = DeploymentCreate(\n        flow_id=flow_id,\n        name=name,\n        version=version,\n        parameters=dict(parameters or {}),\n        tags=list(tags or []),\n        work_queue_name=work_queue_name,\n        description=description,\n        storage_document_id=storage_document_id,\n        path=path,\n        entrypoint=entrypoint,\n        manifest_path=manifest_path,  # for backwards compat\n        infrastructure_document_id=infrastructure_document_id,\n        job_variables=jv,\n        parameter_openapi_schema=parameter_openapi_schema,\n        is_schedule_active=is_schedule_active,\n        paused=paused,\n        schedule=schedule,\n        schedules=schedules or [],\n        pull_steps=pull_steps,\n        enforce_parameter_schema=enforce_parameter_schema,\n    )\n\n    if work_pool_name is not None:\n        deployment_create.work_pool_name = work_pool_name\n\n    # Exclude newer fields that are not set to avoid compatibility issues\n    exclude = {\n        field\n        for field in [\"work_pool_name\", \"work_queue_name\"]\n        if field not in deployment_create.__fields_set__\n    }\n\n    if deployment_create.is_schedule_active is None:\n        exclude.add(\"is_schedule_active\")\n\n    if deployment_create.paused is None:\n        exclude.add(\"paused\")\n\n    if deployment_create.pull_steps is None:\n        exclude.add(\"pull_steps\")\n\n    if deployment_create.enforce_parameter_schema is None:\n        exclude.add(\"enforce_parameter_schema\")\n\n    json = deployment_create.dict(json_compatible=True, exclude=exclude)\n    response = await self._client.post(\n        \"/deployments/\",\n        json=json,\n    )\n    deployment_id = response.json().get(\"id\")\n    if not deployment_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(deployment_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID of interest</p> required <p>Returns:</p> Type Description <code>DeploymentResponse</code> <p>a Deployment model representation of the deployment</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment(\n    self,\n    deployment_id: UUID,\n) -&gt; DeploymentResponse:\n    \"\"\"\n    Query the Prefect API for a deployment by id.\n\n    Args:\n        deployment_id: the deployment ID of interest\n\n    Returns:\n        a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/{deployment_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return DeploymentResponse.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A deployed flow's name: / required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>DeploymentResponse</code> <p>a Deployment model representation of the deployment</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment_by_name(\n    self,\n    name: str,\n) -&gt; DeploymentResponse:\n    \"\"\"\n    Query the Prefect API for a deployment by name.\n\n    Args:\n        name: A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        a Deployment model representation of the deployment\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return DeploymentResponse.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Query the Prefect API for deployments. Only deployments matching all the provided criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the deployment query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the deployment query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[DeploymentResponse]</code> <p>a list of Deployment model representations of the deployments</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployments(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    limit: int = None,\n    sort: DeploymentSort = None,\n    offset: int = 0,\n) -&gt; List[DeploymentResponse]:\n    \"\"\"\n    Query the Prefect API for deployments. Only deployments matching all\n    the provided criteria will be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        limit: a limit for the deployment query\n        offset: an offset for the deployment query\n\n    Returns:\n        a list of Deployment model representations\n            of the deployments\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n        \"sort\": sort,\n    }\n\n    response = await self._client.post(\"/deployments/filter\", json=body)\n    return pydantic.parse_obj_as(List[DeploymentResponse], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>The deployment id of interest.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_deployment(\n    self,\n    deployment_id: UUID,\n):\n    \"\"\"\n    Delete deployment by id.\n\n    Args:\n        deployment_id: The deployment id of interest.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/deployments/{deployment_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_deployment_schedules","title":"<code>create_deployment_schedules</code>  <code>async</code>","text":"<p>Create deployment schedules.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedules</code> <code>List[Tuple[SCHEDULE_TYPES, bool]]</code> <p>a list of tuples containing the schedule to create        and whether or not it should be active.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the schedules were not created for any reason</p> <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>the list of schedules created in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_deployment_schedules(\n    self,\n    deployment_id: UUID,\n    schedules: List[Tuple[SCHEDULE_TYPES, bool]],\n) -&gt; List[DeploymentSchedule]:\n    \"\"\"\n    Create deployment schedules.\n\n    Args:\n        deployment_id: the deployment ID\n        schedules: a list of tuples containing the schedule to create\n                   and whether or not it should be active.\n\n    Raises:\n        httpx.RequestError: if the schedules were not created for any reason\n\n    Returns:\n        the list of schedules created in the backend\n    \"\"\"\n    deployment_schedule_create = [\n        DeploymentScheduleCreate(schedule=schedule[0], active=schedule[1])\n        for schedule in schedules\n    ]\n\n    json = [\n        deployment_schedule_create.dict(json_compatible=True)\n        for deployment_schedule_create in deployment_schedule_create\n    ]\n    response = await self._client.post(\n        f\"/deployments/{deployment_id}/schedules\", json=json\n    )\n    return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment_schedules","title":"<code>read_deployment_schedules</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>a list of DeploymentSchedule model representations of the deployment schedules</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment_schedules(\n    self,\n    deployment_id: UUID,\n) -&gt; List[DeploymentSchedule]:\n    \"\"\"\n    Query the Prefect API for a deployment's schedules.\n\n    Args:\n        deployment_id: the deployment ID\n\n    Returns:\n        a list of DeploymentSchedule model representations of the deployment schedules\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/{deployment_id}/schedules\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_deployment_schedule","title":"<code>update_deployment_schedule</code>  <code>async</code>","text":"<p>Update a deployment schedule by ID.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedule_id</code> <code>UUID</code> <p>the deployment schedule ID of interest</p> required <code>active</code> <code>Optional[bool]</code> <p>whether or not the schedule should be active</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>the cron, rrule, or interval schedule this deployment schedule should use</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_deployment_schedule(\n    self,\n    deployment_id: UUID,\n    schedule_id: UUID,\n    active: Optional[bool] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n):\n    \"\"\"\n    Update a deployment schedule by ID.\n\n    Args:\n        deployment_id: the deployment ID\n        schedule_id: the deployment schedule ID of interest\n        active: whether or not the schedule should be active\n        schedule: the cron, rrule, or interval schedule this deployment schedule should use\n    \"\"\"\n    kwargs = {}\n    if active is not None:\n        kwargs[\"active\"] = active\n    if schedule is not None:\n        kwargs[\"schedule\"] = schedule\n\n    deployment_schedule_update = DeploymentScheduleUpdate(**kwargs)\n    json = deployment_schedule_update.dict(json_compatible=True, exclude_unset=True)\n\n    try:\n        await self._client.patch(\n            f\"/deployments/{deployment_id}/schedules/{schedule_id}\", json=json\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_deployment_schedule","title":"<code>delete_deployment_schedule</code>  <code>async</code>","text":"<p>Delete a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedule_id</code> <code>UUID</code> <p>the ID of the deployment schedule to delete.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the schedules were not deleted for any reason</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_deployment_schedule(\n    self,\n    deployment_id: UUID,\n    schedule_id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a deployment schedule.\n\n    Args:\n        deployment_id: the deployment ID\n        schedule_id: the ID of the deployment schedule to delete.\n\n    Raises:\n        httpx.RequestError: if the schedules were not deleted for any reason\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/deployments/{deployment_id}/schedules/{schedule_id}\"\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <p>Returns:</p> Type Description <code>FlowRun</code> <p>a Flow Run model representation of the flow run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n    \"\"\"\n    Query the Prefect API for a flow run by id.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n\n    Returns:\n        a Flow Run model representation of the flow run\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resumes a paused flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <code>run_input</code> <code>Optional[Dict]</code> <p>the input to resume the flow run with</p> <code>None</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def resume_flow_run(\n    self, flow_run_id: UUID, run_input: Optional[Dict] = None\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Resumes a paused flow run.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n        run_input: the input to resume the flow run with\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    try:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/resume\", json={\"run_input\": run_input}\n        )\n    except httpx.HTTPStatusError:\n        raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>sort criteria for the flow runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>a list of Flow Run model representations of the flow runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Query the Prefect API for flow runs. Only flow runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flow runs\n        limit: limit for the flow run query\n        offset: offset for the flow run query\n\n    Returns:\n        a list of Flow Run model representations\n            of the flow runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/flow_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Set the state of a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def set_flow_run_state(\n    self,\n    flow_run_id: UUID,\n    state: \"prefect.states.State\",\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a flow run.\n\n    Args:\n        flow_run_id: the id of the flow run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.flow_run_id = flow_run_id\n    state_create.state_details.transition_id = uuid4()\n    try:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Query for the states of a flow run</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the flow run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_states(\n    self, flow_run_id: UUID\n) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a flow run\n\n    Args:\n        flow_run_id: the id of the flow run\n\n    Returns:\n        a list of State model representations\n            of the flow run states\n    \"\"\"\n    response = await self._client.get(\n        \"/flow_run_states/\", params=dict(flow_run_id=str(flow_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Create a task run</p> <p>Parameters:</p> Name Type Description Default <code>task</code> <code>Task[P, R]</code> <p>The Task to run</p> required <code>flow_run_id</code> <code>Optional[UUID]</code> <p>The flow run id with which to associate the task run</p> required <code>dynamic_key</code> <code>str</code> <p>A key unique to this particular run of a Task within the flow</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task run</p> <code>None</code> <code>extra_tags</code> <code>Optional[Iterable[str]]</code> <p>an optional list of extra tags to apply to the task run in addition to <code>task.tags</code></p> <code>None</code> <code>state</code> <code>Optional[State[R]]</code> <p>The initial state for the run. If not provided, defaults to <code>Pending</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>task_inputs</code> <code>Optional[Dict[str, List[Union[TaskRunResult, Parameter, Constant]]]]</code> <p>the set of inputs passed to the task</p> <code>None</code> <p>Returns:</p> Type Description <code>TaskRun</code> <p>The created task run.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_task_run(\n    self,\n    task: \"TaskObject[P, R]\",\n    flow_run_id: Optional[UUID],\n    dynamic_key: str,\n    name: Optional[str] = None,\n    extra_tags: Optional[Iterable[str]] = None,\n    state: Optional[prefect.states.State[R]] = None,\n    task_inputs: Optional[\n        Dict[\n            str,\n            List[\n                Union[\n                    TaskRunResult,\n                    Parameter,\n                    Constant,\n                ]\n            ],\n        ]\n    ] = None,\n) -&gt; TaskRun:\n    \"\"\"\n    Create a task run\n\n    Args:\n        task: The Task to run\n        flow_run_id: The flow run id with which to associate the task run\n        dynamic_key: A key unique to this particular run of a Task within the flow\n        name: An optional name for the task run\n        extra_tags: an optional list of extra tags to apply to the task run in\n            addition to `task.tags`\n        state: The initial state for the run. If not provided, defaults to\n            `Pending` for now. Should always be a `Scheduled` type.\n        task_inputs: the set of inputs passed to the task\n\n    Returns:\n        The created task run.\n    \"\"\"\n    tags = set(task.tags).union(extra_tags or [])\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    task_run_data = TaskRunCreate(\n        name=name,\n        flow_run_id=flow_run_id,\n        task_key=task.task_key,\n        dynamic_key=dynamic_key,\n        tags=list(tags),\n        task_version=task.version,\n        empirical_policy=TaskRunPolicy(\n            retries=task.retries,\n            retry_delay=task.retry_delay_seconds,\n            retry_jitter_factor=task.retry_jitter_factor,\n        ),\n        state=state.to_state_create(),\n        task_inputs=task_inputs or {},\n    )\n\n    response = await self._client.post(\n        \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n    )\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Query the Prefect API for a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required <p>Returns:</p> Type Description <code>TaskRun</code> <p>a Task Run model representation of the task run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n    \"\"\"\n    Query the Prefect API for a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n\n    Returns:\n        a Task Run model representation of the task run\n    \"\"\"\n    response = await self._client.get(f\"/task_runs/{task_run_id}\")\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Query the Prefect API for task runs. Only task runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>sort criteria for the task runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the task run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the task run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[TaskRun]</code> <p>a list of Task Run model representations of the task runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    sort: TaskRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[TaskRun]:\n    \"\"\"\n    Query the Prefect API for task runs. Only task runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        sort: sort criteria for the task runs\n        limit: a limit for the task run query\n        offset: an offset for the task run query\n\n    Returns:\n        a list of Task Run model representations\n            of the task runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/task_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[TaskRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_task_run(self, task_run_id: UUID) -&gt; None:\n    \"\"\"\n    Delete a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/task_runs/{task_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Set the state of a task run.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def set_task_run_state(\n    self,\n    task_run_id: UUID,\n    state: prefect.states.State,\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a task run.\n\n    Args:\n        task_run_id: the id of the task run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.task_run_id = task_run_id\n    response = await self._client.post(\n        f\"/task_runs/{task_run_id}/set_state\",\n        json=dict(state=state_create.dict(json_compatible=True), force=force),\n    )\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Query for the states of a task run</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the task run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_run_states(\n    self, task_run_id: UUID\n) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a task run\n\n    Args:\n        task_run_id: the id of the task run\n\n    Returns:\n        a list of State model representations of the task run states\n    \"\"\"\n    response = await self._client.get(\n        \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_logs","title":"<code>create_logs</code>  <code>async</code>","text":"<p>Create logs for a flow or task run</p> <p>Parameters:</p> Name Type Description Default <code>logs</code> <code>Iterable[Union[LogCreate, dict]]</code> <p>An iterable of <code>LogCreate</code> objects or already json-compatible dicts</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_logs(self, logs: Iterable[Union[LogCreate, dict]]) -&gt; None:\n    \"\"\"\n    Create logs for a flow or task run\n\n    Args:\n        logs: An iterable of `LogCreate` objects or already json-compatible dicts\n    \"\"\"\n    serialized_logs = [\n        log.dict(json_compatible=True) if isinstance(log, LogCreate) else log\n        for log in logs\n    ]\n    await self._client.post(\"/logs/\", json=serialized_logs)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_notification_policy","title":"<code>create_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Create a notification policy for flow runs</p> <p>Parameters:</p> Name Type Description Default <code>block_document_id</code> <code>UUID</code> <p>The block document UUID</p> required <code>is_active</code> <code>bool</code> <p>Whether the notification policy is active</p> <code>True</code> <code>tags</code> <code>List[str]</code> <p>List of flow tags</p> <code>None</code> <code>state_names</code> <code>List[str]</code> <p>List of state names</p> <code>None</code> <code>message_template</code> <code>Optional[str]</code> <p>Notification message template</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_notification_policy(\n    self,\n    block_document_id: UUID,\n    is_active: bool = True,\n    tags: List[str] = None,\n    state_names: List[str] = None,\n    message_template: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a notification policy for flow runs\n\n    Args:\n        block_document_id: The block document UUID\n        is_active: Whether the notification policy is active\n        tags: List of flow tags\n        state_names: List of state names\n        message_template: Notification message template\n    \"\"\"\n    if tags is None:\n        tags = []\n    if state_names is None:\n        state_names = []\n\n    policy = FlowRunNotificationPolicyCreate(\n        block_document_id=block_document_id,\n        is_active=is_active,\n        tags=tags,\n        state_names=state_names,\n        message_template=message_template,\n    )\n    response = await self._client.post(\n        \"/flow_run_notification_policies/\",\n        json=policy.dict(json_compatible=True),\n    )\n\n    policy_id = response.json().get(\"id\")\n    if not policy_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(policy_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run_notification_policy","title":"<code>delete_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Delete a flow run notification policy by id.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>UUID of the flow run notification policy to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run_notification_policy(\n    self,\n    id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a flow run notification policy by id.\n\n    Args:\n        id: UUID of the flow run notification policy to delete.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/flow_run_notification_policies/{id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_flow_run_notification_policy","title":"<code>update_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Update a notification policy for flow runs</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>UUID of the notification policy</p> required <code>block_document_id</code> <code>Optional[UUID]</code> <p>The block document UUID</p> <code>None</code> <code>is_active</code> <code>Optional[bool]</code> <p>Whether the notification policy is active</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>List of flow tags</p> <code>None</code> <code>state_names</code> <code>Optional[List[str]]</code> <p>List of state names</p> <code>None</code> <code>message_template</code> <code>Optional[str]</code> <p>Notification message template</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_flow_run_notification_policy(\n    self,\n    id: UUID,\n    block_document_id: Optional[UUID] = None,\n    is_active: Optional[bool] = None,\n    tags: Optional[List[str]] = None,\n    state_names: Optional[List[str]] = None,\n    message_template: Optional[str] = None,\n) -&gt; None:\n    \"\"\"\n    Update a notification policy for flow runs\n\n    Args:\n        id: UUID of the notification policy\n        block_document_id: The block document UUID\n        is_active: Whether the notification policy is active\n        tags: List of flow tags\n        state_names: List of state names\n        message_template: Notification message template\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    params = {}\n    if block_document_id is not None:\n        params[\"block_document_id\"] = block_document_id\n    if is_active is not None:\n        params[\"is_active\"] = is_active\n    if tags is not None:\n        params[\"tags\"] = tags\n    if state_names is not None:\n        params[\"state_names\"] = state_names\n    if message_template is not None:\n        params[\"message_template\"] = message_template\n\n    policy = FlowRunNotificationPolicyUpdate(**params)\n\n    try:\n        await self._client.patch(\n            f\"/flow_run_notification_policies/{id}\",\n            json=policy.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_notification_policies","title":"<code>read_flow_run_notification_policies</code>  <code>async</code>","text":"<p>Query the Prefect API for flow run notification policies. Only policies matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_notification_policy_filter</code> <code>FlowRunNotificationPolicyFilter</code> <p>filter criteria for notification policies</p> required <code>limit</code> <code>Optional[int]</code> <p>a limit for the notification policies query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the notification policies query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRunNotificationPolicy]</code> <p>a list of FlowRunNotificationPolicy model representations of the notification policies</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_notification_policies(\n    self,\n    flow_run_notification_policy_filter: FlowRunNotificationPolicyFilter,\n    limit: Optional[int] = None,\n    offset: int = 0,\n) -&gt; List[FlowRunNotificationPolicy]:\n    \"\"\"\n    Query the Prefect API for flow run notification policies. Only policies matching all criteria will\n    be returned.\n\n    Args:\n        flow_run_notification_policy_filter: filter criteria for notification policies\n        limit: a limit for the notification policies query\n        offset: an offset for the notification policies query\n\n    Returns:\n        a list of FlowRunNotificationPolicy model representations\n            of the notification policies\n    \"\"\"\n    body = {\n        \"flow_run_notification_policy_filter\": (\n            flow_run_notification_policy_filter.dict(json_compatible=True)\n            if flow_run_notification_policy_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\n        \"/flow_run_notification_policies/filter\", json=body\n    )\n    return pydantic.parse_obj_as(List[FlowRunNotificationPolicy], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_logs","title":"<code>read_logs</code>  <code>async</code>","text":"<p>Read flow and task run logs.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_logs(\n    self,\n    log_filter: LogFilter = None,\n    limit: int = None,\n    offset: int = None,\n    sort: LogSort = LogSort.TIMESTAMP_ASC,\n) -&gt; List[Log]:\n    \"\"\"\n    Read flow and task run logs.\n    \"\"\"\n    body = {\n        \"logs\": log_filter.dict(json_compatible=True) if log_filter else None,\n        \"limit\": limit,\n        \"offset\": offset,\n        \"sort\": sort,\n    }\n\n    response = await self._client.post(\"/logs/filter\", json=body)\n    return pydantic.parse_obj_as(List[Log], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.resolve_datadoc","title":"<code>resolve_datadoc</code>  <code>async</code>","text":"<p>Recursively decode possibly nested data documents.</p> <p>\"server\" encoded documents will be retrieved from the server.</p> <p>Parameters:</p> Name Type Description Default <code>datadoc</code> <code>DataDocument</code> <p>The data document to resolve</p> required <p>Returns:</p> Type Description <code>Any</code> <p>a decoded object, the innermost data</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def resolve_datadoc(self, datadoc: DataDocument) -&gt; Any:\n    \"\"\"\n    Recursively decode possibly nested data documents.\n\n    \"server\" encoded documents will be retrieved from the server.\n\n    Args:\n        datadoc: The data document to resolve\n\n    Returns:\n        a decoded object, the innermost data\n    \"\"\"\n    if not isinstance(datadoc, DataDocument):\n        raise TypeError(\n            f\"`resolve_datadoc` received invalid type {type(datadoc).__name__}\"\n        )\n\n    async def resolve_inner(data):\n        if isinstance(data, bytes):\n            try:\n                data = DataDocument.parse_raw(data)\n            except pydantic.ValidationError:\n                return data\n\n        if isinstance(data, DataDocument):\n            return await resolve_inner(data.decode())\n\n        return data\n\n    return await resolve_inner(datadoc)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.send_worker_heartbeat","title":"<code>send_worker_heartbeat</code>  <code>async</code>","text":"<p>Sends a worker heartbeat for a given work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool to heartbeat against.</p> required <code>worker_name</code> <code>str</code> <p>The name of the worker sending the heartbeat.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def send_worker_heartbeat(\n    self,\n    work_pool_name: str,\n    worker_name: str,\n    heartbeat_interval_seconds: Optional[float] = None,\n):\n    \"\"\"\n    Sends a worker heartbeat for a given work pool.\n\n    Args:\n        work_pool_name: The name of the work pool to heartbeat against.\n        worker_name: The name of the worker sending the heartbeat.\n    \"\"\"\n    await self._client.post(\n        f\"/work_pools/{work_pool_name}/workers/heartbeat\",\n        json={\n            \"name\": worker_name,\n            \"heartbeat_interval_seconds\": heartbeat_interval_seconds,\n        },\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_workers_for_work_pool","title":"<code>read_workers_for_work_pool</code>  <code>async</code>","text":"<p>Reads workers for a given work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool for which to get member workers.</p> required <code>worker_filter</code> <code>Optional[WorkerFilter]</code> <p>Criteria by which to filter workers.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>Limit for the worker query.</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>Limit for the worker query.</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_workers_for_work_pool(\n    self,\n    work_pool_name: str,\n    worker_filter: Optional[WorkerFilter] = None,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n) -&gt; List[Worker]:\n    \"\"\"\n    Reads workers for a given work pool.\n\n    Args:\n        work_pool_name: The name of the work pool for which to get\n            member workers.\n        worker_filter: Criteria by which to filter workers.\n        limit: Limit for the worker query.\n        offset: Limit for the worker query.\n    \"\"\"\n    response = await self._client.post(\n        f\"/work_pools/{work_pool_name}/workers/filter\",\n        json={\n            \"worker_filter\": (\n                worker_filter.dict(json_compatible=True, exclude_unset=True)\n                if worker_filter\n                else None\n            ),\n            \"offset\": offset,\n            \"limit\": limit,\n        },\n    )\n\n    return pydantic.parse_obj_as(List[Worker], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_pool","title":"<code>read_work_pool</code>  <code>async</code>","text":"<p>Reads information for a given work pool</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool to for which to get information.</p> required <p>Returns:</p> Type Description <code>WorkPool</code> <p>Information about the requested work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_pool(self, work_pool_name: str) -&gt; WorkPool:\n    \"\"\"\n    Reads information for a given work pool\n\n    Args:\n        work_pool_name: The name of the work pool to for which to get\n            information.\n\n    Returns:\n        Information about the requested work pool.\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_pools/{work_pool_name}\")\n        return pydantic.parse_obj_as(WorkPool, response.json())\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_pools","title":"<code>read_work_pools</code>  <code>async</code>","text":"<p>Reads work pools.</p> <p>Parameters:</p> Name Type Description Default <code>limit</code> <code>Optional[int]</code> <p>Limit for the work pool query.</p> <code>None</code> <code>offset</code> <code>int</code> <p>Offset for the work pool query.</p> <code>0</code> <code>work_pool_filter</code> <code>Optional[WorkPoolFilter]</code> <p>Criteria by which to filter work pools.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkPool]</code> <p>A list of work pools.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_pools(\n    self,\n    limit: Optional[int] = None,\n    offset: int = 0,\n    work_pool_filter: Optional[WorkPoolFilter] = None,\n) -&gt; List[WorkPool]:\n    \"\"\"\n    Reads work pools.\n\n    Args:\n        limit: Limit for the work pool query.\n        offset: Offset for the work pool query.\n        work_pool_filter: Criteria by which to filter work pools.\n\n    Returns:\n        A list of work pools.\n    \"\"\"\n\n    body = {\n        \"limit\": limit,\n        \"offset\": offset,\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n    }\n    response = await self._client.post(\"/work_pools/filter\", json=body)\n    return pydantic.parse_obj_as(List[WorkPool], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_work_pool","title":"<code>create_work_pool</code>  <code>async</code>","text":"<p>Creates a work pool with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool</code> <code>WorkPoolCreate</code> <p>Desired configuration for the new work pool.</p> required <code>overwrite</code> <code>bool</code> <p>Whether to overwrite an existing work pool with the same name.</p> <code>False</code> <p>Returns:</p> Type Description <code>WorkPool</code> <p>Information about the newly created work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_work_pool(\n    self,\n    work_pool: WorkPoolCreate,\n    overwrite: bool = False,\n) -&gt; WorkPool:\n    \"\"\"\n    Creates a work pool with the provided configuration.\n\n    Args:\n        work_pool: Desired configuration for the new work pool.\n        overwrite: Whether to overwrite an existing work pool with the same name.\n\n    Returns:\n        Information about the newly created work pool.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/work_pools/\",\n            json=work_pool.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            if overwrite:\n                existing_work_pool = await self.read_work_pool(\n                    work_pool_name=work_pool.name\n                )\n                if existing_work_pool.type != work_pool.type:\n                    warnings.warn(\n                        \"Overwriting work pool type is not supported. Ignoring provided type.\",\n                        category=UserWarning,\n                    )\n                await self.update_work_pool(\n                    work_pool_name=work_pool.name,\n                    work_pool=WorkPoolUpdate.parse_obj(\n                        work_pool.dict(exclude={\"name\", \"type\"})\n                    ),\n                )\n                response = await self._client.get(f\"/work_pools/{work_pool.name}\")\n            else:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n\n    return pydantic.parse_obj_as(WorkPool, response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_work_pool","title":"<code>update_work_pool</code>  <code>async</code>","text":"<p>Updates a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>Name of the work pool to update.</p> required <code>work_pool</code> <code>WorkPoolUpdate</code> <p>Fields to update in the work pool.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_work_pool(\n    self,\n    work_pool_name: str,\n    work_pool: WorkPoolUpdate,\n):\n    \"\"\"\n    Updates a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool to update.\n        work_pool: Fields to update in the work pool.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/work_pools/{work_pool_name}\",\n            json=work_pool.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_work_pool","title":"<code>delete_work_pool</code>  <code>async</code>","text":"<p>Deletes a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>Name of the work pool to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_work_pool(\n    self,\n    work_pool_name: str,\n):\n    \"\"\"\n    Deletes a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool to delete.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/work_pools/{work_pool_name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queues","title":"<code>read_work_queues</code>  <code>async</code>","text":"<p>Retrieves queues for a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>Name of the work pool for which to get queues.</p> <code>None</code> <code>work_queue_filter</code> <code>Optional[WorkQueueFilter]</code> <p>Criteria by which to filter queues.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>Limit for the queue query.</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>Limit for the queue query.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>List of queues for the specified work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queues(\n    self,\n    work_pool_name: Optional[str] = None,\n    work_queue_filter: Optional[WorkQueueFilter] = None,\n    limit: Optional[int] = None,\n    offset: Optional[int] = None,\n) -&gt; List[WorkQueue]:\n    \"\"\"\n    Retrieves queues for a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool for which to get queues.\n        work_queue_filter: Criteria by which to filter queues.\n        limit: Limit for the queue query.\n        offset: Limit for the queue query.\n\n    Returns:\n        List of queues for the specified work pool.\n    \"\"\"\n    json = {\n        \"work_queues\": (\n            work_queue_filter.dict(json_compatible=True, exclude_unset=True)\n            if work_queue_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    if work_pool_name:\n        try:\n            response = await self._client.post(\n                f\"/work_pools/{work_pool_name}/queues/filter\",\n                json=json,\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n    else:\n        response = await self._client.post(\"/work_queues/filter\", json=json)\n\n    return pydantic.parse_obj_as(List[WorkQueue], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_scheduled_flow_runs_for_work_pool","title":"<code>get_scheduled_flow_runs_for_work_pool</code>  <code>async</code>","text":"<p>Retrieves scheduled flow runs for the provided set of work pool queues.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool that the work pool queues are associated with.</p> required <code>work_queue_names</code> <code>Optional[List[str]]</code> <p>The names of the work pool queues from which to get scheduled flow runs.</p> <code>None</code> <code>scheduled_before</code> <code>Optional[datetime]</code> <p>Datetime used to filter returned flow runs. Flow runs scheduled for after the given datetime string will not be returned.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkerFlowRunResponse]</code> <p>A list of worker flow run responses containing information about the</p> <code>List[WorkerFlowRunResponse]</code> <p>retrieved flow runs.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_scheduled_flow_runs_for_work_pool(\n    self,\n    work_pool_name: str,\n    work_queue_names: Optional[List[str]] = None,\n    scheduled_before: Optional[datetime.datetime] = None,\n) -&gt; List[WorkerFlowRunResponse]:\n    \"\"\"\n    Retrieves scheduled flow runs for the provided set of work pool queues.\n\n    Args:\n        work_pool_name: The name of the work pool that the work pool\n            queues are associated with.\n        work_queue_names: The names of the work pool queues from which\n            to get scheduled flow runs.\n        scheduled_before: Datetime used to filter returned flow runs. Flow runs\n            scheduled for after the given datetime string will not be returned.\n\n    Returns:\n        A list of worker flow run responses containing information about the\n        retrieved flow runs.\n    \"\"\"\n    body: Dict[str, Any] = {}\n    if work_queue_names is not None:\n        body[\"work_queue_names\"] = list(work_queue_names)\n    if scheduled_before:\n        body[\"scheduled_before\"] = str(scheduled_before)\n\n    response = await self._client.post(\n        f\"/work_pools/{work_pool_name}/get_scheduled_flow_runs\",\n        json=body,\n    )\n    return pydantic.parse_obj_as(List[WorkerFlowRunResponse], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_artifact","title":"<code>create_artifact</code>  <code>async</code>","text":"<p>Creates an artifact with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>artifact</code> <code>ArtifactCreate</code> <p>Desired configuration for the new artifact.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_artifact(\n    self,\n    artifact: ArtifactCreate,\n) -&gt; Artifact:\n    \"\"\"\n    Creates an artifact with the provided configuration.\n\n    Args:\n        artifact: Desired configuration for the new artifact.\n    Returns:\n        Information about the newly created artifact.\n    \"\"\"\n\n    response = await self._client.post(\n        \"/artifacts/\",\n        json=artifact.dict(json_compatible=True, exclude_unset=True),\n    )\n\n    return pydantic.parse_obj_as(Artifact, response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_artifacts","title":"<code>read_artifacts</code>  <code>async</code>","text":"<p>Query the Prefect API for artifacts. Only artifacts matching all criteria will be returned. Args:     artifact_filter: filter criteria for artifacts     flow_run_filter: filter criteria for flow runs     task_run_filter: filter criteria for task runs     sort: sort criteria for the artifacts     limit: limit for the artifact query     offset: offset for the artifact query Returns:     a list of Artifact model representations of the artifacts</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_artifacts(\n    self,\n    *,\n    artifact_filter: ArtifactFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    sort: ArtifactSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[Artifact]:\n    \"\"\"\n    Query the Prefect API for artifacts. Only artifacts matching all criteria will\n    be returned.\n    Args:\n        artifact_filter: filter criteria for artifacts\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        sort: sort criteria for the artifacts\n        limit: limit for the artifact query\n        offset: offset for the artifact query\n    Returns:\n        a list of Artifact model representations of the artifacts\n    \"\"\"\n    body = {\n        \"artifacts\": (\n            artifact_filter.dict(json_compatible=True) if artifact_filter else None\n        ),\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/artifacts/filter\", json=body)\n    return pydantic.parse_obj_as(List[Artifact], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_latest_artifacts","title":"<code>read_latest_artifacts</code>  <code>async</code>","text":"<p>Query the Prefect API for artifacts. Only artifacts matching all criteria will be returned. Args:     artifact_filter: filter criteria for artifacts     flow_run_filter: filter criteria for flow runs     task_run_filter: filter criteria for task runs     sort: sort criteria for the artifacts     limit: limit for the artifact query     offset: offset for the artifact query Returns:     a list of Artifact model representations of the artifacts</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_latest_artifacts(\n    self,\n    *,\n    artifact_filter: ArtifactCollectionFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    sort: ArtifactCollectionSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[ArtifactCollection]:\n    \"\"\"\n    Query the Prefect API for artifacts. Only artifacts matching all criteria will\n    be returned.\n    Args:\n        artifact_filter: filter criteria for artifacts\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        sort: sort criteria for the artifacts\n        limit: limit for the artifact query\n        offset: offset for the artifact query\n    Returns:\n        a list of Artifact model representations of the artifacts\n    \"\"\"\n    body = {\n        \"artifacts\": (\n            artifact_filter.dict(json_compatible=True) if artifact_filter else None\n        ),\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/artifacts/latest/filter\", json=body)\n    return pydantic.parse_obj_as(List[ArtifactCollection], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_artifact","title":"<code>delete_artifact</code>  <code>async</code>","text":"<p>Deletes an artifact with the provided id.</p> <p>Parameters:</p> Name Type Description Default <code>artifact_id</code> <code>UUID</code> <p>The id of the artifact to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_artifact(self, artifact_id: UUID) -&gt; None:\n    \"\"\"\n    Deletes an artifact with the provided id.\n\n    Args:\n        artifact_id: The id of the artifact to delete.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/artifacts/{artifact_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_variable","title":"<code>create_variable</code>  <code>async</code>","text":"<p>Creates an variable with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>variable</code> <code>VariableCreate</code> <p>Desired configuration for the new variable.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_variable(self, variable: VariableCreate) -&gt; Variable:\n    \"\"\"\n    Creates an variable with the provided configuration.\n\n    Args:\n        variable: Desired configuration for the new variable.\n    Returns:\n        Information about the newly created variable.\n    \"\"\"\n    response = await self._client.post(\n        \"/variables/\",\n        json=variable.dict(json_compatible=True, exclude_unset=True),\n    )\n    return Variable(**response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_variable","title":"<code>update_variable</code>  <code>async</code>","text":"<p>Updates a variable with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>variable</code> <code>VariableUpdate</code> <p>Desired configuration for the updated variable.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_variable(self, variable: VariableUpdate) -&gt; None:\n    \"\"\"\n    Updates a variable with the provided configuration.\n\n    Args:\n        variable: Desired configuration for the updated variable.\n    Returns:\n        Information about the updated variable.\n    \"\"\"\n    await self._client.patch(\n        f\"/variables/name/{variable.name}\",\n        json=variable.dict(json_compatible=True, exclude_unset=True),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_variable_by_name","title":"<code>read_variable_by_name</code>  <code>async</code>","text":"<p>Reads a variable by name. Returns None if no variable is found.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_variable_by_name(self, name: str) -&gt; Optional[Variable]:\n    \"\"\"Reads a variable by name. Returns None if no variable is found.\"\"\"\n    try:\n        response = await self._client.get(f\"/variables/name/{name}\")\n        return Variable(**response.json())\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            return None\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_variable_by_name","title":"<code>delete_variable_by_name</code>  <code>async</code>","text":"<p>Deletes a variable by name.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_variable_by_name(self, name: str):\n    \"\"\"Deletes a variable by name.\"\"\"\n    try:\n        await self._client.delete(f\"/variables/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_variables","title":"<code>read_variables</code>  <code>async</code>","text":"<p>Reads all variables.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_variables(self, limit: int = None) -&gt; List[Variable]:\n    \"\"\"Reads all variables.\"\"\"\n    response = await self._client.post(\"/variables/filter\", json={\"limit\": limit})\n    return pydantic.parse_obj_as(List[Variable], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_worker_metadata","title":"<code>read_worker_metadata</code>  <code>async</code>","text":"<p>Reads worker metadata stored in Prefect collection registry.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n    \"\"\"Reads worker metadata stored in Prefect collection registry.\"\"\"\n    response = await self._client.get(\"collections/views/aggregate-worker-metadata\")\n    response.raise_for_status()\n    return response.json()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Creates a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required <code>value</code> <code>str</code> <p>The input value.</p> required <code>sender</code> <code>Optional[str]</code> <p>The sender of the input.</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_input(\n    self, flow_run_id: UUID, key: str, value: str, sender: Optional[str] = None\n):\n    \"\"\"\n    Creates a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n        value: The input value.\n        sender: The sender of the input.\n    \"\"\"\n\n    # Initialize the input to ensure that the key is valid.\n    FlowRunInput(flow_run_id=flow_run_id, key=key, value=value)\n\n    response = await self._client.post(\n        f\"/flow_runs/{flow_run_id}/input\",\n        json={\"key\": key, \"value\": value, \"sender\": sender},\n    )\n    response.raise_for_status()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Reads a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_input(self, flow_run_id: UUID, key: str) -&gt; str:\n    \"\"\"\n    Reads a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n    \"\"\"\n    response = await self._client.get(f\"/flow_runs/{flow_run_id}/input/{key}\")\n    response.raise_for_status()\n    return response.content.decode()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Deletes a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run_input(self, flow_run_id: UUID, key: str):\n    \"\"\"\n    Deletes a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n    \"\"\"\n    response = await self._client.delete(f\"/flow_runs/{flow_run_id}/input/{key}\")\n    response.raise_for_status()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_automation","title":"<code>create_automation</code>  <code>async</code>","text":"<p>Creates an automation in Prefect Cloud.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_automation(self, automation: AutomationCore) -&gt; UUID:\n    \"\"\"Creates an automation in Prefect Cloud.\"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n\n    response = await self._client.post(\n        \"/automations/\",\n        json=automation.dict(json_compatible=True),\n    )\n\n    return UUID(response.json()[\"id\"])\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_automation","title":"<code>update_automation</code>  <code>async</code>","text":"<p>Updates an automation in Prefect Cloud.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_automation(self, automation_id: UUID, automation: AutomationCore):\n    \"\"\"Updates an automation in Prefect Cloud.\"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n    response = await self._client.put(\n        f\"/automations/{automation_id}\",\n        json=automation.dict(json_compatible=True, exclude_unset=True),\n    )\n    response.raise_for_status\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_automations_by_name","title":"<code>read_automations_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the automation to query</p> required <p>Returns:</p> Type Description <code>List[Automation]</code> <p>a list of Automation model representations of the automations</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_automations_by_name(self, name: str) -&gt; List[Automation]:\n    \"\"\"\n    Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.\n\n    Args:\n        name: the name of the automation to query\n\n    Returns:\n        a list of Automation model representations of the automations\n    \"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n    automation_filter = filters.AutomationFilter(name=dict(any_=[name]))\n\n    response = await self._client.post(\n        \"/automations/filter\",\n        json={\n            \"sort\": sorting.AutomationSort.UPDATED_DESC,\n            \"automations\": automation_filter.dict(json_compatible=True)\n            if automation_filter\n            else None,\n        },\n    )\n\n    response.raise_for_status()\n\n    return pydantic.parse_obj_as(List[Automation], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient","title":"<code>SyncPrefectClient</code>","text":"<p>A synchronous client for interacting with the Prefect REST API.</p> <p>Parameters:</p> Name Type Description Default <code>api</code> <code>Union[str, ASGIApp]</code> <p>the REST API URL or FastAPI application to connect to</p> required <code>api_key</code> <code>str</code> <p>An optional API key for authentication.</p> <code>None</code> <code>api_version</code> <code>str</code> <p>The API version this client is compatible with.</p> <code>None</code> <code>httpx_settings</code> <code>Optional[Dict[str, Any]]</code> <p>An optional dictionary of settings to pass to the underlying <code>httpx.Client</code></p> <code>None</code> <pre><code>Say hello to a Prefect REST API\n\n&lt;div class=\"terminal\"&gt;\n```\n&gt;&gt;&gt; with get_client(sync_client=True) as client:\n&gt;&gt;&gt;     response = client.hello()\n&gt;&gt;&gt;\n&gt;&gt;&gt; print(response.json())\n\ud83d\udc4b\n```\n&lt;/div&gt;\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>class SyncPrefectClient:\n    \"\"\"\n    A synchronous client for interacting with the [Prefect REST API](/api-ref/rest-api/).\n\n    Args:\n        api: the REST API URL or FastAPI application to connect to\n        api_key: An optional API key for authentication.\n        api_version: The API version this client is compatible with.\n        httpx_settings: An optional dictionary of settings to pass to the underlying\n            `httpx.Client`\n\n    Examples:\n\n        Say hello to a Prefect REST API\n\n        &lt;div class=\"terminal\"&gt;\n        ```\n        &gt;&gt;&gt; with get_client(sync_client=True) as client:\n        &gt;&gt;&gt;     response = client.hello()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; print(response.json())\n        \ud83d\udc4b\n        ```\n        &lt;/div&gt;\n    \"\"\"\n\n    def __init__(\n        self,\n        api: Union[str, ASGIApp],\n        *,\n        api_key: str = None,\n        api_version: str = None,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings.copy() if httpx_settings else {}\n        httpx_settings.setdefault(\"headers\", {})\n\n        if PREFECT_API_TLS_INSECURE_SKIP_VERIFY:\n            httpx_settings.setdefault(\"verify\", False)\n        else:\n            cert_file = PREFECT_API_SSL_CERT_FILE.value()\n            if not cert_file:\n                cert_file = certifi.where()\n            httpx_settings.setdefault(\"verify\", cert_file)\n\n        if api_version is None:\n            api_version = SERVER_API_VERSION\n        httpx_settings[\"headers\"].setdefault(\"X-PREFECT-API-VERSION\", api_version)\n        if api_key:\n            httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        # Context management\n        self._ephemeral_app: Optional[ASGIApp] = None\n        self.manage_lifespan = True\n        self.server_type: ServerType\n\n        self._closed = False\n        self._started = False\n\n        # Connect to an external application\n        if isinstance(api, str):\n            if httpx_settings.get(\"app\"):\n                raise ValueError(\n                    \"Invalid httpx settings: `app` cannot be set when providing an \"\n                    \"api url. `app` is only for use with ephemeral instances. Provide \"\n                    \"it as the `api` parameter instead.\"\n                )\n            httpx_settings.setdefault(\"base_url\", api)\n\n            # See https://www.python-httpx.org/advanced/#pool-limit-configuration\n            httpx_settings.setdefault(\n                \"limits\",\n                httpx.Limits(\n                    # We see instability when allowing the client to open many connections at once.\n                    # Limiting concurrency results in more stable performance.\n                    max_connections=16,\n                    max_keepalive_connections=8,\n                    # The Prefect Cloud LB will keep connections alive for 30s.\n                    # Only allow the client to keep connections alive for 25s.\n                    keepalive_expiry=25,\n                ),\n            )\n\n            # See https://www.python-httpx.org/http2/\n            # Enabling HTTP/2 support on the client does not necessarily mean that your requests\n            # and responses will be transported over HTTP/2, since both the client and the server\n            # need to support HTTP/2. If you connect to a server that only supports HTTP/1.1 the\n            # client will use a standard HTTP/1.1 connection instead.\n            httpx_settings.setdefault(\"http2\", PREFECT_API_ENABLE_HTTP2.value())\n\n            self.server_type = (\n                ServerType.CLOUD\n                if api.startswith(PREFECT_CLOUD_API_URL.value())\n                else ServerType.SERVER\n            )\n\n        # Connect to an in-process application\n        elif isinstance(api, ASGIApp):\n            self._ephemeral_app = api\n            self.server_type = ServerType.EPHEMERAL\n\n        else:\n            raise TypeError(\n                f\"Unexpected type {type(api).__name__!r} for argument `api`. Expected\"\n                \" 'str' or 'ASGIApp/FastAPI'\"\n            )\n\n        # See https://www.python-httpx.org/advanced/#timeout-configuration\n        httpx_settings.setdefault(\n            \"timeout\",\n            httpx.Timeout(\n                connect=PREFECT_API_REQUEST_TIMEOUT.value(),\n                read=PREFECT_API_REQUEST_TIMEOUT.value(),\n                write=PREFECT_API_REQUEST_TIMEOUT.value(),\n                pool=PREFECT_API_REQUEST_TIMEOUT.value(),\n            ),\n        )\n\n        if not PREFECT_UNIT_TEST_MODE:\n            httpx_settings.setdefault(\"follow_redirects\", True)\n\n        enable_csrf_support = (\n            self.server_type != ServerType.CLOUD\n            and PREFECT_CLIENT_CSRF_SUPPORT_ENABLED.value()\n        )\n\n        if self.server_type == ServerType.EPHEMERAL:\n            self._client = PrefectHttpxSyncEphemeralClient(\n                api, base_url=\"http://ephemeral-prefect/api\"\n            )\n        else:\n            self._client = PrefectHttpxSyncClient(\n                **httpx_settings, enable_csrf_support=enable_csrf_support\n            )\n\n        # See https://www.python-httpx.org/advanced/#custom-transports\n        #\n        # If we're using an HTTP/S client (not the ephemeral client), adjust the\n        # transport to add retries _after_ it is instantiated. If we alter the transport\n        # before instantiation, the transport will not be aware of proxies unless we\n        # reproduce all of the logic to make it so.\n        #\n        # Only alter the transport to set our default of 3 retries, don't modify any\n        # transport a user may have provided via httpx_settings.\n        #\n        # Making liberal use of getattr and isinstance checks here to avoid any\n        # surprises if the internals of httpx or httpcore change on us\n        if isinstance(api, str) and not httpx_settings.get(\"transport\"):\n            transport_for_url = getattr(self._client, \"_transport_for_url\", None)\n            if callable(transport_for_url):\n                server_transport = transport_for_url(httpx.URL(api))\n                if isinstance(server_transport, httpx.HTTPTransport):\n                    pool = getattr(server_transport, \"_pool\", None)\n                    if isinstance(pool, httpcore.ConnectionPool):\n                        pool._retries = 3\n\n        self.logger = get_logger(\"client\")\n\n    @property\n    def api_url(self) -&gt; httpx.URL:\n        \"\"\"\n        Get the base URL for the API.\n        \"\"\"\n        return self._client.base_url\n\n    # Context management ----------------------------------------------------------------\n\n    def __enter__(self) -&gt; \"SyncPrefectClient\":\n        \"\"\"\n        Start the client.\n\n        If the client is already started, this will raise an exception.\n\n        If the client is already closed, this will raise an exception. Use a new client\n        instance instead.\n        \"\"\"\n        if self._closed:\n            # httpx.Client does not allow reuse so we will not either.\n            raise RuntimeError(\n                \"The client cannot be started again after closing. \"\n                \"Retrieve a new client with `get_client()` instead.\"\n            )\n\n        if self._started:\n            # httpx.Client does not allow reentrancy so we will not either.\n            raise RuntimeError(\"The client cannot be started more than once.\")\n        self._client.__enter__()\n        self._started = True\n\n        return self\n\n    def __exit__(self, *exc_info) -&gt; None:\n        \"\"\"\n        Shutdown the client.\n        \"\"\"\n        self._closed = True\n        self._client.__exit__(*exc_info)\n\n    # API methods ----------------------------------------------------------------------\n\n    def api_healthcheck(self) -&gt; Optional[Exception]:\n        \"\"\"\n        Attempts to connect to the API and returns the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        try:\n            self._client.get(\"/health\")\n            return None\n        except Exception as exc:\n            return exc\n\n    def hello(self) -&gt; httpx.Response:\n        \"\"\"\n        Send a GET request to /hello for testing purposes.\n        \"\"\"\n        return self._client.get(\"/hello\")\n\n    def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow: a [Flow][prefect.flows.Flow] object\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        return self.create_flow_from_name(flow.name)\n\n    def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow_name: the name of the new flow\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        flow_data = FlowCreate(name=flow_name)\n        response = self._client.post(\n            \"/flows/\", json=flow_data.dict(json_compatible=True)\n        )\n\n        flow_id = response.json().get(\"id\")\n        if not flow_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        # Return the id of the created flow\n        return UUID(flow_id)\n\n    def create_flow_run(\n        self,\n        flow: \"FlowObject\",\n        name: Optional[str] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        tags: Optional[Iterable[str]] = None,\n        parent_task_run_id: Optional[UUID] = None,\n        state: Optional[\"prefect.states.State\"] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a flow.\n\n        Args:\n            flow: The flow model to create the flow run for\n            name: An optional name for the flow run\n            parameters: Parameter overrides for this flow run.\n            context: Optional run context data\n            tags: a list of tags to apply to this flow run\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        # Retrieve the flow id\n        flow_id = self.create_flow(flow)\n\n        flow_run_create = FlowRunCreate(\n            flow_id=flow_id,\n            flow_version=flow.version,\n            name=name,\n            parameters=parameters,\n            context=context,\n            tags=list(tags or []),\n            parent_task_run_id=parent_task_run_id,\n            state=state.to_state_create(),\n            empirical_policy=FlowRunPolicy(\n                retries=flow.retries,\n                retry_delay=flow.retry_delay_seconds,\n            ),\n        )\n\n        flow_run_create_json = flow_run_create.dict(json_compatible=True)\n        response = self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n        flow_run = FlowRun.parse_obj(response.json())\n\n        # Restore the parameters to the local objects to retain expectations about\n        # Python objects\n        flow_run.parameters = parameters\n\n        return flow_run\n\n    def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n        \"\"\"\n        Query the Prefect API for a flow run by id.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n\n        Returns:\n            a Flow Run model representation of the flow run\n        \"\"\"\n        try:\n            response = self._client.get(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return FlowRun.parse_obj(response.json())\n\n    def read_flow_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Query the Prefect API for flow runs. Only flow runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flow runs\n            limit: limit for the flow run query\n            offset: offset for the flow run query\n\n        Returns:\n            a list of Flow Run model representations\n                of the flow runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = self._client.post(\"/flow_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    def set_flow_run_state(\n        self,\n        flow_run_id: UUID,\n        state: \"prefect.states.State\",\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a flow run.\n\n        Args:\n            flow_run_id: the id of the flow run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.flow_run_id = flow_run_id\n        state_create.state_details.transition_id = uuid4()\n        try:\n            response = self._client.post(\n                f\"/flow_runs/{flow_run_id}/set_state\",\n                json=dict(state=state_create.dict(json_compatible=True), force=force),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    def create_task_run(\n        self,\n        task: \"TaskObject[P, R]\",\n        flow_run_id: Optional[UUID],\n        dynamic_key: str,\n        name: Optional[str] = None,\n        extra_tags: Optional[Iterable[str]] = None,\n        state: Optional[prefect.states.State[R]] = None,\n        task_inputs: Optional[\n            Dict[\n                str,\n                List[\n                    Union[\n                        TaskRunResult,\n                        Parameter,\n                        Constant,\n                    ]\n                ],\n            ]\n        ] = None,\n    ) -&gt; TaskRun:\n        \"\"\"\n        Create a task run\n\n        Args:\n            task: The Task to run\n            flow_run_id: The flow run id with which to associate the task run\n            dynamic_key: A key unique to this particular run of a Task within the flow\n            name: An optional name for the task run\n            extra_tags: an optional list of extra tags to apply to the task run in\n                addition to `task.tags`\n            state: The initial state for the run. If not provided, defaults to\n                `Pending` for now. Should always be a `Scheduled` type.\n            task_inputs: the set of inputs passed to the task\n\n        Returns:\n            The created task run.\n        \"\"\"\n        tags = set(task.tags).union(extra_tags or [])\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        task_run_data = TaskRunCreate(\n            name=name,\n            flow_run_id=flow_run_id,\n            task_key=task.task_key,\n            dynamic_key=dynamic_key,\n            tags=list(tags),\n            task_version=task.version,\n            empirical_policy=TaskRunPolicy(\n                retries=task.retries,\n                retry_delay=task.retry_delay_seconds,\n                retry_jitter_factor=task.retry_jitter_factor,\n            ),\n            state=state.to_state_create(),\n            task_inputs=task_inputs or {},\n        )\n\n        response = self._client.post(\n            \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n        )\n        return TaskRun.parse_obj(response.json())\n\n    def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n        \"\"\"\n        Query the Prefect API for a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n\n        Returns:\n            a Task Run model representation of the task run\n        \"\"\"\n        response = self._client.get(f\"/task_runs/{task_run_id}\")\n        return TaskRun.parse_obj(response.json())\n\n    def read_task_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        sort: TaskRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[TaskRun]:\n        \"\"\"\n        Query the Prefect API for task runs. Only task runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            sort: sort criteria for the task runs\n            limit: a limit for the task run query\n            offset: an offset for the task run query\n\n        Returns:\n            a list of Task Run model representations\n                of the task runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = self._client.post(\"/task_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[TaskRun], response.json())\n\n    def set_task_run_state(\n        self,\n        task_run_id: UUID,\n        state: prefect.states.State,\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a task run.\n\n        Args:\n            task_run_id: the id of the task run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.task_run_id = task_run_id\n        response = self._client.post(\n            f\"/task_runs/{task_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n        return OrchestrationResult.parse_obj(response.json())\n\n    def read_task_run_states(self, task_run_id: UUID) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a task run\n\n        Args:\n            task_run_id: the id of the task run\n\n        Returns:\n            a list of State model representations of the task run states\n        \"\"\"\n        response = self._client.get(\n            \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.api_url","title":"<code>api_url: httpx.URL</code>  <code>property</code>","text":"<p>Get the base URL for the API.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.api_healthcheck","title":"<code>api_healthcheck</code>","text":"<p>Attempts to connect to the API and returns the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def api_healthcheck(self) -&gt; Optional[Exception]:\n    \"\"\"\n    Attempts to connect to the API and returns the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    try:\n        self._client.get(\"/health\")\n        return None\n    except Exception as exc:\n        return exc\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.hello","title":"<code>hello</code>","text":"<p>Send a GET request to /hello for testing purposes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def hello(self) -&gt; httpx.Response:\n    \"\"\"\n    Send a GET request to /hello for testing purposes.\n    \"\"\"\n    return self._client.get(\"/hello\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow","title":"<code>create_flow</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>a Flow object</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow: a [Flow][prefect.flows.Flow] object\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    return self.create_flow_from_name(flow.name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow_from_name","title":"<code>create_flow_from_name</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of the new flow</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow_name: the name of the new flow\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    flow_data = FlowCreate(name=flow_name)\n    response = self._client.post(\n        \"/flows/\", json=flow_data.dict(json_compatible=True)\n    )\n\n    flow_id = response.json().get(\"id\")\n    if not flow_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    # Return the id of the created flow\n    return UUID(flow_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow_run","title":"<code>create_flow_run</code>","text":"<p>Create a flow run for a flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>The flow model to create the flow run for</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow run</p> <code>None</code> <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run.</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>a list of tags to apply to this flow run</p> <code>None</code> <code>parent_task_run_id</code> <code>Optional[UUID]</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>state</code> <code>Optional[State]</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow_run(\n    self,\n    flow: \"FlowObject\",\n    name: Optional[str] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    tags: Optional[Iterable[str]] = None,\n    parent_task_run_id: Optional[UUID] = None,\n    state: Optional[\"prefect.states.State\"] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a flow.\n\n    Args:\n        flow: The flow model to create the flow run for\n        name: An optional name for the flow run\n        parameters: Parameter overrides for this flow run.\n        context: Optional run context data\n        tags: a list of tags to apply to this flow run\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    # Retrieve the flow id\n    flow_id = self.create_flow(flow)\n\n    flow_run_create = FlowRunCreate(\n        flow_id=flow_id,\n        flow_version=flow.version,\n        name=name,\n        parameters=parameters,\n        context=context,\n        tags=list(tags or []),\n        parent_task_run_id=parent_task_run_id,\n        state=state.to_state_create(),\n        empirical_policy=FlowRunPolicy(\n            retries=flow.retries,\n            retry_delay=flow.retry_delay_seconds,\n        ),\n    )\n\n    flow_run_create_json = flow_run_create.dict(json_compatible=True)\n    response = self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n    flow_run = FlowRun.parse_obj(response.json())\n\n    # Restore the parameters to the local objects to retain expectations about\n    # Python objects\n    flow_run.parameters = parameters\n\n    return flow_run\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_flow_run","title":"<code>read_flow_run</code>","text":"<p>Query the Prefect API for a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <p>Returns:</p> Type Description <code>FlowRun</code> <p>a Flow Run model representation of the flow run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n    \"\"\"\n    Query the Prefect API for a flow run by id.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n\n    Returns:\n        a Flow Run model representation of the flow run\n    \"\"\"\n    try:\n        response = self._client.get(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_flow_runs","title":"<code>read_flow_runs</code>","text":"<p>Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>sort criteria for the flow runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>a list of Flow Run model representations of the flow runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_flow_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Query the Prefect API for flow runs. Only flow runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flow runs\n        limit: limit for the flow run query\n        offset: offset for the flow run query\n\n    Returns:\n        a list of Flow Run model representations\n            of the flow runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = self._client.post(\"/flow_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.set_flow_run_state","title":"<code>set_flow_run_state</code>","text":"<p>Set the state of a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def set_flow_run_state(\n    self,\n    flow_run_id: UUID,\n    state: \"prefect.states.State\",\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a flow run.\n\n    Args:\n        flow_run_id: the id of the flow run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.flow_run_id = flow_run_id\n    state_create.state_details.transition_id = uuid4()\n    try:\n        response = self._client.post(\n            f\"/flow_runs/{flow_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_task_run","title":"<code>create_task_run</code>","text":"<p>Create a task run</p> <p>Parameters:</p> Name Type Description Default <code>task</code> <code>Task[P, R]</code> <p>The Task to run</p> required <code>flow_run_id</code> <code>Optional[UUID]</code> <p>The flow run id with which to associate the task run</p> required <code>dynamic_key</code> <code>str</code> <p>A key unique to this particular run of a Task within the flow</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task run</p> <code>None</code> <code>extra_tags</code> <code>Optional[Iterable[str]]</code> <p>an optional list of extra tags to apply to the task run in addition to <code>task.tags</code></p> <code>None</code> <code>state</code> <code>Optional[State[R]]</code> <p>The initial state for the run. If not provided, defaults to <code>Pending</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>task_inputs</code> <code>Optional[Dict[str, List[Union[TaskRunResult, Parameter, Constant]]]]</code> <p>the set of inputs passed to the task</p> <code>None</code> <p>Returns:</p> Type Description <code>TaskRun</code> <p>The created task run.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_task_run(\n    self,\n    task: \"TaskObject[P, R]\",\n    flow_run_id: Optional[UUID],\n    dynamic_key: str,\n    name: Optional[str] = None,\n    extra_tags: Optional[Iterable[str]] = None,\n    state: Optional[prefect.states.State[R]] = None,\n    task_inputs: Optional[\n        Dict[\n            str,\n            List[\n                Union[\n                    TaskRunResult,\n                    Parameter,\n                    Constant,\n                ]\n            ],\n        ]\n    ] = None,\n) -&gt; TaskRun:\n    \"\"\"\n    Create a task run\n\n    Args:\n        task: The Task to run\n        flow_run_id: The flow run id with which to associate the task run\n        dynamic_key: A key unique to this particular run of a Task within the flow\n        name: An optional name for the task run\n        extra_tags: an optional list of extra tags to apply to the task run in\n            addition to `task.tags`\n        state: The initial state for the run. If not provided, defaults to\n            `Pending` for now. Should always be a `Scheduled` type.\n        task_inputs: the set of inputs passed to the task\n\n    Returns:\n        The created task run.\n    \"\"\"\n    tags = set(task.tags).union(extra_tags or [])\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    task_run_data = TaskRunCreate(\n        name=name,\n        flow_run_id=flow_run_id,\n        task_key=task.task_key,\n        dynamic_key=dynamic_key,\n        tags=list(tags),\n        task_version=task.version,\n        empirical_policy=TaskRunPolicy(\n            retries=task.retries,\n            retry_delay=task.retry_delay_seconds,\n            retry_jitter_factor=task.retry_jitter_factor,\n        ),\n        state=state.to_state_create(),\n        task_inputs=task_inputs or {},\n    )\n\n    response = self._client.post(\n        \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n    )\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_run","title":"<code>read_task_run</code>","text":"<p>Query the Prefect API for a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required <p>Returns:</p> Type Description <code>TaskRun</code> <p>a Task Run model representation of the task run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n    \"\"\"\n    Query the Prefect API for a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n\n    Returns:\n        a Task Run model representation of the task run\n    \"\"\"\n    response = self._client.get(f\"/task_runs/{task_run_id}\")\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_runs","title":"<code>read_task_runs</code>","text":"<p>Query the Prefect API for task runs. Only task runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>sort criteria for the task runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the task run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the task run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[TaskRun]</code> <p>a list of Task Run model representations of the task runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    sort: TaskRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[TaskRun]:\n    \"\"\"\n    Query the Prefect API for task runs. Only task runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        sort: sort criteria for the task runs\n        limit: a limit for the task run query\n        offset: an offset for the task run query\n\n    Returns:\n        a list of Task Run model representations\n            of the task runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = self._client.post(\"/task_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[TaskRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.set_task_run_state","title":"<code>set_task_run_state</code>","text":"<p>Set the state of a task run.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def set_task_run_state(\n    self,\n    task_run_id: UUID,\n    state: prefect.states.State,\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a task run.\n\n    Args:\n        task_run_id: the id of the task run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.task_run_id = task_run_id\n    response = self._client.post(\n        f\"/task_runs/{task_run_id}/set_state\",\n        json=dict(state=state_create.dict(json_compatible=True), force=force),\n    )\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_run_states","title":"<code>read_task_run_states</code>","text":"<p>Query for the states of a task run</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the task run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_run_states(self, task_run_id: UUID) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a task run\n\n    Args:\n        task_run_id: the id of the task run\n\n    Returns:\n        a list of State model representations of the task run states\n    \"\"\"\n    response = self._client.get(\n        \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.get_client","title":"<code>get_client</code>","text":"<p>Retrieve a HTTP client for communicating with the Prefect REST API.</p> <p>The client must be context managed; for example:</p> <pre><code>async with get_client() as client:\n    await client.hello()\n</code></pre> <p>To return a synchronous client, pass sync_client=True:</p> <pre><code>with get_client(sync_client=True) as client:\n    client.hello()\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def get_client(\n    httpx_settings: Optional[Dict[str, Any]] = None, sync_client: bool = False\n) -&gt; Union[\"PrefectClient\", \"SyncPrefectClient\"]:\n    \"\"\"\n    Retrieve a HTTP client for communicating with the Prefect REST API.\n\n    The client must be context managed; for example:\n\n    ```python\n    async with get_client() as client:\n        await client.hello()\n    ```\n\n    To return a synchronous client, pass sync_client=True:\n\n    ```python\n    with get_client(sync_client=True) as client:\n        client.hello()\n    ```\n    \"\"\"\n    ctx = prefect.context.get_settings_context()\n    api = PREFECT_API_URL.value()\n\n    if not api:\n        # create an ephemeral API if none was provided\n        from prefect.server.api.server import create_app\n\n        api = create_app(ctx.settings, ephemeral=True)\n\n    if sync_client:\n        return SyncPrefectClient(\n            api,\n            api_key=PREFECT_API_KEY.value(),\n            httpx_settings=httpx_settings,\n        )\n    else:\n        return PrefectClient(\n            api,\n            api_key=PREFECT_API_KEY.value(),\n            httpx_settings=httpx_settings,\n        )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_1","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions","title":"<code>prefect.client.schemas.actions</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.StateCreate","title":"<code>StateCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a new state.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class StateCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a new state.\"\"\"\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    state_details: StateDetails = Field(default_factory=StateDetails)\n    data: Union[\"BaseResult[R]\", \"DataDocument[R]\", Any] = Field(\n        default=None,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowCreate","title":"<code>FlowCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowUpdate","title":"<code>FlowUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow.\"\"\"\n\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentCreate","title":"<code>DeploymentCreate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentCreate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    name: str = Field(..., description=\"The name of the deployment.\")\n    flow_id: UUID = Field(..., description=\"The ID of the flow to deploy.\")\n    is_schedule_active: Optional[bool] = Field(None)\n    paused: Optional[bool] = Field(None)\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(None)\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(default_factory=list)\n    pull_steps: Optional[List[dict]] = Field(None)\n\n    manifest_path: Optional[str] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    schedule: Optional[SCHEDULE_TYPES] = Field(None)\n    description: Optional[str] = Field(None)\n    path: Optional[str] = Field(None)\n    version: Optional[str] = Field(None)\n    entrypoint: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"Check that the combination of base_job_template defaults\n        and job_variables conforms to the specified schema.\n        \"\"\"\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            # jsonschema considers required fields, even if that field has a default,\n            # to still be required. To get around this we remove the fields from\n            # required if there is a default present.\n            required = variables_schema.get(\"required\")\n            properties = variables_schema.get(\"properties\")\n            if required is not None and properties is not None:\n                for k, v in properties.items():\n                    if \"default\" in v and k in required:\n                        required.remove(k)\n\n            jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentCreate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"Check that the combination of base_job_template defaults\n    and job_variables conforms to the specified schema.\n    \"\"\"\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        # jsonschema considers required fields, even if that field has a default,\n        # to still be required. To get around this we remove the fields from\n        # required if there is a default present.\n        required = variables_schema.get(\"required\")\n        properties = variables_schema.get(\"properties\")\n        if required is not None and properties is not None:\n            for k, v in properties.items():\n                if \"default\" in v and k in required:\n                    required.remove(k)\n\n        jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentUpdate","title":"<code>DeploymentUpdate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentUpdate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    @validator(\"schedule\")\n    def validate_none_schedule(cls, v):\n        return return_none_schedule(v)\n\n    version: Optional[str] = Field(None)\n    schedule: Optional[SCHEDULE_TYPES] = Field(None)\n    description: Optional[str] = Field(None)\n    is_schedule_active: bool = Field(None)\n    parameters: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(default_factory=list)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    path: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    entrypoint: Optional[str] = Field(None)\n    manifest_path: Optional[str] = Field(None)\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"Check that the combination of base_job_template defaults\n        and job_variables conforms to the specified schema.\n        \"\"\"\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            # jsonschema considers required fields, even if that field has a default,\n            # to still be required. To get around this we remove the fields from\n            # required if there is a default present.\n            required = variables_schema.get(\"required\")\n            properties = variables_schema.get(\"properties\")\n            if required is not None and properties is not None:\n                for k, v in properties.items():\n                    if \"default\" in v and k in required:\n                        required.remove(k)\n\n        if variables_schema is not None:\n            jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentUpdate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"Check that the combination of base_job_template defaults\n    and job_variables conforms to the specified schema.\n    \"\"\"\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        # jsonschema considers required fields, even if that field has a default,\n        # to still be required. To get around this we remove the fields from\n        # required if there is a default present.\n        required = variables_schema.get(\"required\")\n        properties = variables_schema.get(\"properties\")\n        if required is not None and properties is not None:\n            for k, v in properties.items():\n                if \"default\" in v and k in required:\n                    required.remove(k)\n\n    if variables_schema is not None:\n        jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunUpdate","title":"<code>FlowRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run.\"\"\"\n\n    name: Optional[str] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Optional[Dict[str, Any]] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    infrastructure_pid: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.TaskRunCreate","title":"<code>TaskRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a task run</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class TaskRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a task run\"\"\"\n\n    # TaskRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the task run to create\"\n    )\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the task run\",\n    )\n    flow_run_id: Optional[UUID] = Field(None)\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(None)\n    cache_expiration: Optional[objects.DateTimeTZ] = Field(None)\n    task_version: Optional[str] = Field(None)\n    empirical_policy: objects.TaskRunPolicy = Field(\n        default_factory=objects.TaskRunPolicy,\n    )\n    tags: List[str] = Field(default_factory=list)\n    task_inputs: Dict[\n        str,\n        List[\n            Union[\n                objects.TaskRunResult,\n                objects.Parameter,\n                objects.Constant,\n            ]\n        ],\n    ] = Field(default_factory=dict)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.TaskRunUpdate","title":"<code>TaskRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a task run</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class TaskRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a task run\"\"\"\n\n    name: Optional[str] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunCreate","title":"<code>FlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: Optional[str] = Field(default=None, description=\"The name of the flow run.\")\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    deployment_id: Optional[UUID] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The parameters for the flow run.\"\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The context for the flow run.\"\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    idempotency_key: Optional[str] = Field(None)\n\n    class Config(ActionBaseModel.Config):\n        json_dumps = orjson_dumps_extra_compatible\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentFlowRunCreate","title":"<code>DeploymentFlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run from a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentFlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run from a deployment.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: Optional[str] = Field(default=None, description=\"The name of the flow run.\")\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The parameters for the flow run.\"\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The context for the flow run.\"\n    )\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    idempotency_key: Optional[str] = Field(None)\n    parent_task_run_id: Optional[UUID] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    job_variables: Optional[dict] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.SavedSearchCreate","title":"<code>SavedSearchCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a saved search.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class SavedSearchCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a saved search.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[objects.SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ConcurrencyLimitCreate","title":"<code>ConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockTypeCreate","title":"<code>BlockTypeCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block type.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockTypeCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block type.\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[objects.HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[objects.HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n\n    # validators\n    _validate_slug_format = validator(\"slug\", allow_reuse=True)(\n        validate_block_type_slug\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockTypeUpdate","title":"<code>BlockTypeUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block type.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockTypeUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block type.\"\"\"\n\n    logo_url: Optional[objects.HttpUrl] = Field(None)\n    documentation_url: Optional[objects.HttpUrl] = Field(None)\n    description: Optional[str] = Field(None)\n    code_example: Optional[str] = Field(None)\n\n    @classmethod\n    def updatable_fields(cls) -&gt; set:\n        return get_class_fields_only(cls)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockSchemaCreate","title":"<code>BlockSchemaCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockSchemaCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block schema.\"\"\"\n\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(None)\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=objects.DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentCreate","title":"<code>BlockDocumentCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block document.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None, description=\"The name of the block document\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(\n        default=..., description=\"The block schema ID for the block document\"\n    )\n    block_type_id: UUID = Field(\n        default=..., description=\"The block type ID for the block document\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    _validate_name_format = validator(\"name\", allow_reuse=True)(\n        validate_block_document_name\n    )\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentUpdate","title":"<code>BlockDocumentUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block document.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block document.\"\"\"\n\n    block_schema_id: Optional[UUID] = Field(\n        default=None, description=\"A block schema ID\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    merge_existing_data: bool = Field(\n        default=True,\n        description=\"Whether to merge the existing data with the new data or replace it\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentReferenceCreate","title":"<code>BlockDocumentReferenceCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used to create block document reference.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentReferenceCreate(ActionBaseModel):\n    \"\"\"Data used to create block document reference.\"\"\"\n\n    id: UUID = Field(default_factory=uuid4)\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.LogCreate","title":"<code>LogCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a log.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class LogCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a log.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkPoolCreate","title":"<code>WorkPoolCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work pool.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkPoolCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work pool.\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(None)\n    type: str = Field(\n        description=\"The work pool type.\", default=\"prefect-agent\"\n    )  # TODO: change default\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"The base job template for the work pool.\",\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Whether the work pool is paused.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkPoolUpdate","title":"<code>WorkPoolUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work pool.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkPoolUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work pool.\"\"\"\n\n    description: Optional[str] = Field(None)\n    is_paused: Optional[bool] = Field(None)\n    base_job_template: Optional[Dict[str, Any]] = Field(None)\n    concurrency_limit: Optional[int] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkQueueCreate","title":"<code>WorkQueueCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work queue.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkQueueCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work queue.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False,\n        description=\"Whether the work queue is paused.\",\n    )\n    concurrency_limit: Optional[int] = Field(\n        default=None,\n        description=\"A concurrency limit for the work queue.\",\n    )\n    priority: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n\n    # DEPRECATED\n\n    filter: Optional[objects.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkQueueUpdate","title":"<code>WorkQueueUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work queue.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkQueueUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work queue.\"\"\"\n\n    name: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[int] = Field(None)\n    priority: Optional[int] = Field(None)\n    last_polled: Optional[DateTimeTZ] = Field(None)\n\n    # DEPRECATED\n\n    filter: Optional[objects.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunNotificationPolicyCreate","title":"<code>FlowRunNotificationPolicyCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run notification policy.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run notification policy.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(objects.FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunNotificationPolicyUpdate","title":"<code>FlowRunNotificationPolicyUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run notification policy.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run notification policy.\"\"\"\n\n    is_active: Optional[bool] = Field(None)\n    state_names: Optional[List[str]] = Field(None)\n    tags: Optional[List[str]] = Field(None)\n    block_document_id: Optional[UUID] = Field(None)\n    message_template: Optional[str] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ArtifactCreate","title":"<code>ArtifactCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create an artifact.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ArtifactCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create an artifact.\"\"\"\n\n    key: Optional[str] = Field(None)\n    type: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n\n    _validate_artifact_format = validator(\"key\", allow_reuse=True)(\n        validate_artifact_key\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ArtifactUpdate","title":"<code>ArtifactUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update an artifact.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ArtifactUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update an artifact.\"\"\"\n\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    description: Optional[str] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.VariableCreate","title":"<code>VariableCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a Variable.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class VariableCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a Variable.\"\"\"\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the variable\",\n        examples=[\"my_variable\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: str = Field(\n        default=...,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=objects.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(default=None)\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.VariableUpdate","title":"<code>VariableUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a Variable.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class VariableUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a Variable.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the variable\",\n        examples=[\"my_variable\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: Optional[str] = Field(\n        default=None,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(default=None)\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.GlobalConcurrencyLimitCreate","title":"<code>GlobalConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a global concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class GlobalConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a global concurrency limit.\"\"\"\n\n    name: str = Field(description=\"The name of the global concurrency limit.\")\n    limit: NonNegativeInteger = Field(\n        description=(\n            \"The maximum number of slots that can be occupied on this concurrency\"\n            \" limit.\"\n        )\n    )\n    active: Optional[bool] = Field(\n        default=True,\n        description=\"Whether or not the concurrency limit is in an active state.\",\n    )\n    active_slots: Optional[NonNegativeInteger] = Field(\n        default=0,\n        description=\"Number of tasks currently using a concurrency slot.\",\n    )\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(\n        default=0.0,\n        description=(\n            \"Controls the rate at which slots are released when the concurrency limit\"\n            \" is used as a rate limit.\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.GlobalConcurrencyLimitUpdate","title":"<code>GlobalConcurrencyLimitUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a global concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class GlobalConcurrencyLimitUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a global concurrency limit.\"\"\"\n\n    name: Optional[str] = Field(None)\n    limit: Optional[NonNegativeInteger] = Field(None)\n    active: Optional[bool] = Field(None)\n    active_slots: Optional[NonNegativeInteger] = Field(None)\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(None)\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_2","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters","title":"<code>prefect.client.schemas.filters</code>","text":"<p>Schemas that define Prefect REST API filtering operations.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.Operator","title":"<code>Operator</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Operators for combining filter criteria.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class Operator(AutoEnum):\n    \"\"\"Operators for combining filter criteria.\"\"\"\n\n    and_ = AutoEnum.auto()\n    or_ = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.OperatorMixin","title":"<code>OperatorMixin</code>","text":"<p>Base model for Prefect filters that combines criteria with a user-provided operator</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class OperatorMixin:\n    \"\"\"Base model for Prefect filters that combines criteria with a user-provided operator\"\"\"\n\n    operator: Operator = Field(\n        default=Operator.and_,\n        description=\"Operator for combining filter criteria. Defaults to 'and_'.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterId","title":"<code>FlowFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Flow.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Flow.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterName","title":"<code>FlowFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Flow.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Flow.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow names to include\",\n        examples=[[\"my-flow-1\", \"my-flow-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterTags","title":"<code>FlowFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Flow.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Flow.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flows will be returned only if their tags are a superset\"\n            \" of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flows without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilter","title":"<code>FlowFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for flows. Only flows matching all criteria will be returned.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for flows. Only flows matching all criteria will be returned.\"\"\"\n\n    id: Optional[FlowFilterId] = Field(\n        default=None, description=\"Filter criteria for `Flow.id`\"\n    )\n    name: Optional[FlowFilterName] = Field(\n        default=None, description=\"Filter criteria for `Flow.name`\"\n    )\n    tags: Optional[FlowFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Flow.tags`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterId","title":"<code>FlowRunFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by FlowRun.id.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterId(PrefectBaseModel):\n    \"\"\"Filter by FlowRun.id.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n    not_any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterName","title":"<code>FlowRunFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterName(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow run names to include\",\n        examples=[[\"my-flow-run-1\", \"my-flow-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterTags","title":"<code>FlowRunFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flow runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flow runs without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterDeploymentId","title":"<code>FlowRunFilterDeploymentId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.deployment_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterDeploymentId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.deployment_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run deployment ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without deployment ids\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterWorkQueueName","title":"<code>FlowRunFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.work_queue_name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterWorkQueueName(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without work queue names\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterStateType","title":"<code>FlowRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterStateType(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.state_type`.\"\"\"\n\n    any_: Optional[List[StateType]] = Field(\n        default=None, description=\"A list of flow run state types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterFlowVersion","title":"<code>FlowRunFilterFlowVersion</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.flow_version</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterFlowVersion(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.flow_version`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run flow_versions to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterStartTime","title":"<code>FlowRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return flow runs without a start time\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterExpectedStartTime","title":"<code>FlowRunFilterExpectedStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.expected_start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterExpectedStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.expected_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or after this time\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterNextScheduledStartTime","title":"<code>FlowRunFilterNextScheduledStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterNextScheduledStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.next_scheduled_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time or before this\"\n            \" time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time at or after this\"\n            \" time\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterParentFlowRunId","title":"<code>FlowRunFilterParentFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for subflows of the given flow runs</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterParentFlowRunId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for subflows of the given flow runs\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parents to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterParentTaskRunId","title":"<code>FlowRunFilterParentTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterParentTaskRunId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.parent_task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parent_task_run_ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without parent_task_run_id\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterIdempotencyKey","title":"<code>FlowRunFilterIdempotencyKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by FlowRun.idempotency_key.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterIdempotencyKey(PrefectBaseModel):\n    \"\"\"Filter by FlowRun.idempotency_key.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilter","title":"<code>FlowRunFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter flow runs. Only flow runs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter flow runs. Only flow runs matching all criteria will be returned\"\"\"\n\n    id: Optional[FlowRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.id`\"\n    )\n    name: Optional[FlowRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.name`\"\n    )\n    tags: Optional[FlowRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.tags`\"\n    )\n    deployment_id: Optional[FlowRunFilterDeploymentId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.deployment_id`\"\n    )\n    work_queue_name: Optional[FlowRunFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.work_queue_name\"\n    )\n    state: Optional[FlowRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state`\"\n    )\n    flow_version: Optional[FlowRunFilterFlowVersion] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.flow_version`\"\n    )\n    start_time: Optional[FlowRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.start_time`\"\n    )\n    expected_start_time: Optional[FlowRunFilterExpectedStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.expected_start_time`\"\n    )\n    next_scheduled_start_time: Optional[FlowRunFilterNextScheduledStartTime] = Field(\n        default=None,\n        description=\"Filter criteria for `FlowRun.next_scheduled_start_time`\",\n    )\n    parent_flow_run_id: Optional[FlowRunFilterParentFlowRunId] = Field(\n        default=None, description=\"Filter criteria for subflows of the given flow runs\"\n    )\n    parent_task_run_id: Optional[FlowRunFilterParentTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.parent_task_run_id`\"\n    )\n    idempotency_key: Optional[FlowRunFilterIdempotencyKey] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.idempotency_key`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterFlowRunId","title":"<code>TaskRunFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n\n    is_null_: bool = Field(\n        default=False,\n        description=\"If true, only include task runs without a flow run id\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterId","title":"<code>TaskRunFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterId(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterName","title":"<code>TaskRunFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterName(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of task run names to include\",\n        examples=[[\"my-task-run-1\", \"my-task-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterTags","title":"<code>TaskRunFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>TaskRun.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `TaskRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Task runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include task runs without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterStateType","title":"<code>TaskRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.state_type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterStateType(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.state_type`.\"\"\"\n\n    any_: Optional[List[StateType]] = Field(\n        default=None, description=\"A list of task run state types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterSubFlowRuns","title":"<code>TaskRunFilterSubFlowRuns</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.subflow_run</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterSubFlowRuns(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.subflow_run`.\"\"\"\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If true, only include task runs that are subflow run parents; if false,\"\n            \" exclude parent task runs\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterStartTime","title":"<code>TaskRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterStartTime(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return task runs without a start time\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilter","title":"<code>TaskRunFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter task runs. Only task runs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter task runs. Only task runs matching all criteria will be returned\"\"\"\n\n    id: Optional[TaskRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.id`\"\n    )\n    name: Optional[TaskRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.name`\"\n    )\n    tags: Optional[TaskRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.tags`\"\n    )\n    state: Optional[TaskRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.state`\"\n    )\n    start_time: Optional[TaskRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.start_time`\"\n    )\n    subflow_runs: Optional[TaskRunFilterSubFlowRuns] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.subflow_run`\"\n    )\n    flow_run_id: Optional[TaskRunFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.flow_run_id`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterId","title":"<code>DeploymentFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of deployment ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterName","title":"<code>DeploymentFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of deployment names to include\",\n        examples=[[\"my-deployment-1\", \"my-deployment-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterWorkQueueName","title":"<code>DeploymentFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.work_queue_name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterWorkQueueName(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterIsScheduleActive","title":"<code>DeploymentFilterIsScheduleActive</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.is_schedule_active</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterIsScheduleActive(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.is_schedule_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterTags","title":"<code>DeploymentFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Deployment.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Deployment.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Deployments will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include deployments without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilter","title":"<code>DeploymentFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    id: Optional[DeploymentFilterId] = Field(\n        default=None, description=\"Filter criteria for `Deployment.id`\"\n    )\n    name: Optional[DeploymentFilterName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.name`\"\n    )\n    is_schedule_active: Optional[DeploymentFilterIsScheduleActive] = Field(\n        default=None, description=\"Filter criteria for `Deployment.is_schedule_active`\"\n    )\n    tags: Optional[DeploymentFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Deployment.tags`\"\n    )\n    work_queue_name: Optional[DeploymentFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.work_queue_name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterName","title":"<code>LogFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Log.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of log names to include\",\n        examples=[[\"prefect.logger.flow_runs\", \"prefect.logger.task_runs\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterLevel","title":"<code>LogFilterLevel</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.level</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterLevel(PrefectBaseModel):\n    \"\"\"Filter by `Log.level`.\"\"\"\n\n    ge_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level greater than or equal to this level\",\n        examples=[20],\n    )\n\n    le_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level less than or equal to this level\",\n        examples=[50],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterTimestamp","title":"<code>LogFilterTimestamp</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.timestamp</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterTimestamp(PrefectBaseModel):\n    \"\"\"Filter by `Log.timestamp`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or after this time\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterFlowRunId","title":"<code>LogFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `Log.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterTaskRunId","title":"<code>LogFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `Log.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilter","title":"<code>LogFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter logs. Only logs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter logs. Only logs matching all criteria will be returned\"\"\"\n\n    level: Optional[LogFilterLevel] = Field(\n        default=None, description=\"Filter criteria for `Log.level`\"\n    )\n    timestamp: Optional[LogFilterTimestamp] = Field(\n        default=None, description=\"Filter criteria for `Log.timestamp`\"\n    )\n    flow_run_id: Optional[LogFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.flow_run_id`\"\n    )\n    task_run_id: Optional[LogFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.task_run_id`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FilterSet","title":"<code>FilterSet</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A collection of filters for common objects</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FilterSet(PrefectBaseModel):\n    \"\"\"A collection of filters for common objects\"\"\"\n\n    flows: FlowFilter = Field(\n        default_factory=FlowFilter, description=\"Filters that apply to flows\"\n    )\n    flow_runs: FlowRunFilter = Field(\n        default_factory=FlowRunFilter, description=\"Filters that apply to flow runs\"\n    )\n    task_runs: TaskRunFilter = Field(\n        default_factory=TaskRunFilter, description=\"Filters that apply to task runs\"\n    )\n    deployments: DeploymentFilter = Field(\n        default_factory=DeploymentFilter,\n        description=\"Filters that apply to deployments\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilterName","title":"<code>BlockTypeFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockType.name</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilterName(PrefectBaseModel):\n    \"\"\"Filter by `BlockType.name`\"\"\"\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilterSlug","title":"<code>BlockTypeFilterSlug</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockType.slug</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilterSlug(PrefectBaseModel):\n    \"\"\"Filter by `BlockType.slug`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of slugs to match\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilter","title":"<code>BlockTypeFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter BlockTypes</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilter(PrefectBaseModel):\n    \"\"\"Filter BlockTypes\"\"\"\n\n    name: Optional[BlockTypeFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockType.name`\"\n    )\n\n    slug: Optional[BlockTypeFilterSlug] = Field(\n        default=None, description=\"Filter criteria for `BlockType.slug`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterBlockTypeId","title":"<code>BlockSchemaFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.block_type_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterBlockTypeId(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterId","title":"<code>BlockSchemaFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by BlockSchema.id</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterId(PrefectBaseModel):\n    \"\"\"Filter by BlockSchema.id\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterCapabilities","title":"<code>BlockSchemaFilterCapabilities</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterCapabilities(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"write-storage\", \"read-storage\"]],\n        description=(\n            \"A list of block capabilities. Block entities will be returned only if an\"\n            \" associated block schema has a superset of the defined capabilities.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterVersion","title":"<code>BlockSchemaFilterVersion</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterVersion(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"2.0.0\", \"2.1.0\"]],\n        description=\"A list of block schema versions.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilter","title":"<code>BlockSchemaFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter BlockSchemas</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter BlockSchemas\"\"\"\n\n    block_type_id: Optional[BlockSchemaFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.block_type_id`\"\n    )\n    block_capabilities: Optional[BlockSchemaFilterCapabilities] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.capabilities`\"\n    )\n    id: Optional[BlockSchemaFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.id`\"\n    )\n    version: Optional[BlockSchemaFilterVersion] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.version`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterIsAnonymous","title":"<code>BlockDocumentFilterIsAnonymous</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.is_anonymous</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterIsAnonymous(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.is_anonymous`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter block documents for only those that are or are not anonymous.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterBlockTypeId","title":"<code>BlockDocumentFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.block_type_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterBlockTypeId(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterId","title":"<code>BlockDocumentFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterId(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterName","title":"<code>BlockDocumentFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterName(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of block names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match block names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-block%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilter","title":"<code>BlockDocumentFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned\"\"\"\n\n    id: Optional[BlockDocumentFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.id`\"\n    )\n    is_anonymous: Optional[BlockDocumentFilterIsAnonymous] = Field(\n        # default is to exclude anonymous blocks\n        BlockDocumentFilterIsAnonymous(eq_=False),\n        description=(\n            \"Filter criteria for `BlockDocument.is_anonymous`. \"\n            \"Defaults to excluding anonymous blocks.\"\n        ),\n    )\n    block_type_id: Optional[BlockDocumentFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.block_type_id`\"\n    )\n    name: Optional[BlockDocumentFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunNotificationPolicyFilterIsActive","title":"<code>FlowRunNotificationPolicyFilterIsActive</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilterIsActive(PrefectBaseModel):\n    \"\"\"Filter by `FlowRunNotificationPolicy.is_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter notification policies for only those that are or are not active.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunNotificationPolicyFilter","title":"<code>FlowRunNotificationPolicyFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter FlowRunNotificationPolicies.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilter(PrefectBaseModel):\n    \"\"\"Filter FlowRunNotificationPolicies.\"\"\"\n\n    is_active: Optional[FlowRunNotificationPolicyFilterIsActive] = Field(\n        default=FlowRunNotificationPolicyFilterIsActive(eq_=False),\n        description=\"Filter criteria for `FlowRunNotificationPolicy.is_active`. \",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilterId","title":"<code>WorkQueueFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkQueue.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilterId(PrefectBaseModel):\n    \"\"\"Filter by `WorkQueue.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"A list of work queue ids to include\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilterName","title":"<code>WorkQueueFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkQueue.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilterName(PrefectBaseModel):\n    \"\"\"Filter by `WorkQueue.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"wq-1\", \"wq-2\"]],\n    )\n\n    startswith_: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"A list of case-insensitive starts-with matches. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', and 'Marvin-robot', but not 'sad-marvin'.\"\n        ),\n        examples=[[\"marvin\", \"Marvin-robot\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilter","title":"<code>WorkQueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter work queues. Only work queues matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter work queues. Only work queues matching all criteria will be\n    returned\"\"\"\n\n    id: Optional[WorkQueueFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.id`\"\n    )\n\n    name: Optional[WorkQueueFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterId","title":"<code>WorkPoolFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterId(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterName","title":"<code>WorkPoolFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterName(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool names to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterType","title":"<code>WorkPoolFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterType(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkerFilterWorkPoolId","title":"<code>WorkerFilterWorkPoolId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Worker.worker_config_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkerFilterWorkPoolId(PrefectBaseModel):\n    \"\"\"Filter by `Worker.worker_config_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkerFilterLastHeartbeatTime","title":"<code>WorkerFilterLastHeartbeatTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkerFilterLastHeartbeatTime(PrefectBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or before this time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or after this time\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterId","title":"<code>ArtifactFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterKey","title":"<code>ArtifactFilterKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.key</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterKey(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterFlowRunId","title":"<code>ArtifactFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterTaskRunId","title":"<code>ArtifactFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterType","title":"<code>ArtifactFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterType(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilter","title":"<code>ArtifactFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter artifacts. Only artifacts matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter artifacts. Only artifacts matching all criteria will be returned\"\"\"\n\n    id: Optional[ArtifactFilterId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterLatestId","title":"<code>ArtifactCollectionFilterLatestId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.latest_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterLatestId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.latest_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterKey","title":"<code>ArtifactCollectionFilterKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.key</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterKey(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key. Should return all rows in \"\n            \"the ArtifactCollection table if specified.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterFlowRunId","title":"<code>ArtifactCollectionFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterTaskRunId","title":"<code>ArtifactCollectionFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterType","title":"<code>ArtifactCollectionFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterType(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilter","title":"<code>ArtifactCollectionFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter artifact collections. Only artifact collections matching all criteria will be returned\"\"\"\n\n    latest_id: Optional[ArtifactCollectionFilterLatestId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactCollectionFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactCollectionFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactCollectionFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactCollectionFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterId","title":"<code>VariableFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Variable.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of variable ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterName","title":"<code>VariableFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Variable.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my_variable_%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterValue","title":"<code>VariableFilterValue</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.value</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterValue(PrefectBaseModel):\n    \"\"\"Filter by `Variable.value`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables value to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable value against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-value-%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterTags","title":"<code>VariableFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Variable.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Variable.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Variables will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include Variables without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilter","title":"<code>VariableFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter variables. Only variables matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter variables. Only variables matching all criteria will be returned\"\"\"\n\n    id: Optional[VariableFilterId] = Field(\n        default=None, description=\"Filter criteria for `Variable.id`\"\n    )\n    name: Optional[VariableFilterName] = Field(\n        default=None, description=\"Filter criteria for `Variable.name`\"\n    )\n    value: Optional[VariableFilterValue] = Field(\n        default=None, description=\"Filter criteria for `Variable.value`\"\n    )\n    tags: Optional[VariableFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Variable.tags`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_3","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects","title":"<code>prefect.client.schemas.objects</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.StateType","title":"<code>StateType</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of state types.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class StateType(AutoEnum):\n    \"\"\"Enumeration of state types.\"\"\"\n\n    SCHEDULED = AutoEnum.auto()\n    PENDING = AutoEnum.auto()\n    RUNNING = AutoEnum.auto()\n    COMPLETED = AutoEnum.auto()\n    FAILED = AutoEnum.auto()\n    CANCELLED = AutoEnum.auto()\n    CRASHED = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n    CANCELLING = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkPoolStatus","title":"<code>WorkPoolStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of work pool statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkPoolStatus(AutoEnum):\n    \"\"\"Enumeration of work pool statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n\n    @property\n    def display_name(self):\n        return self.name.replace(\"_\", \" \").capitalize()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkerStatus","title":"<code>WorkerStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of worker statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkerStatus(AutoEnum):\n    \"\"\"Enumeration of worker statuses.\"\"\"\n\n    ONLINE = AutoEnum.auto()\n    OFFLINE = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.DeploymentStatus","title":"<code>DeploymentStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of deployment statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class DeploymentStatus(AutoEnum):\n    \"\"\"Enumeration of deployment statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueStatus","title":"<code>WorkQueueStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of work queue statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueueStatus(AutoEnum):\n    \"\"\"Enumeration of work queue statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State","title":"<code>State</code>","text":"<p>               Bases: <code>ObjectBaseModel</code>, <code>Generic[R]</code></p> <p>The state of a run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class State(ObjectBaseModel, Generic[R]):\n    \"\"\"\n    The state of a run.\n    \"\"\"\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    timestamp: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    state_details: StateDetails = Field(default_factory=StateDetails)\n    data: Union[\"BaseResult[R]\", \"DataDocument[R]\", Any] = Field(\n        default=None,\n    )\n\n    @overload\n    def result(self: \"State[R]\", raise_on_failure: bool = True) -&gt; R:\n        ...\n\n    @overload\n    def result(self: \"State[R]\", raise_on_failure: bool = False) -&gt; Union[R, Exception]:\n        ...\n\n    def result(\n        self, raise_on_failure: bool = True, fetch: Optional[bool] = None\n    ) -&gt; Union[R, Exception]:\n        \"\"\"\n        Retrieve the result attached to this state.\n\n        Args:\n            raise_on_failure: a boolean specifying whether to raise an exception\n                if the state is of type `FAILED` and the underlying data is an exception\n            fetch: a boolean specifying whether to resolve references to persisted\n                results into data. For synchronous users, this defaults to `True`.\n                For asynchronous users, this defaults to `False` for backwards\n                compatibility.\n\n        Raises:\n            TypeError: If the state is failed but the result is not an exception.\n\n        Returns:\n            The result of the run\n\n        Examples:\n            &gt;&gt;&gt; from prefect import flow, task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task(x):\n            &gt;&gt;&gt;     return x\n\n            Get the result from a task future in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     future = my_task(\"hello\")\n            &gt;&gt;&gt;     state = future.wait()\n            &gt;&gt;&gt;     result = state.result()\n            &gt;&gt;&gt;     print(result)\n            &gt;&gt;&gt; my_flow()\n            hello\n\n            Get the result from a flow state\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return \"hello\"\n            &gt;&gt;&gt; my_flow(return_state=True).result()\n            hello\n\n            Get the result from a failed state\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n            &gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n            &gt;&gt;&gt; state.result()  # Raises `ValueError`\n\n            Get the result from a failed state without erroring\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n            &gt;&gt;&gt; state = my_flow(return_state=True)\n            &gt;&gt;&gt; result = state.result(raise_on_failure=False)\n            &gt;&gt;&gt; print(result)\n            ValueError(\"oh no!\")\n\n\n            Get the result from a flow state in an async context\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     return \"hello\"\n            &gt;&gt;&gt; state = await my_flow(return_state=True)\n            &gt;&gt;&gt; await state.result()\n            hello\n        \"\"\"\n        from prefect.states import get_state_result\n\n        return get_state_result(self, raise_on_failure=raise_on_failure, fetch=fetch)\n\n    def to_state_create(self):\n        \"\"\"\n        Convert this state to a `StateCreate` type which can be used to set the state of\n        a run in the API.\n\n        This method will drop this state's `data` if it is not a result type. Only\n        results should be sent to the API. Other data is only available locally.\n        \"\"\"\n        from prefect.client.schemas.actions import StateCreate\n        from prefect.results import BaseResult\n\n        return StateCreate(\n            type=self.type,\n            name=self.name,\n            message=self.message,\n            data=self.data if isinstance(self.data, BaseResult) else None,\n            state_details=self.state_details,\n        )\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        \"\"\"\n        TODO: This should throw an error instead of setting a default but is out of\n              scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled\n              into work refactoring state initialization\n        \"\"\"\n        if values.get(\"type\") == StateType.SCHEDULED:\n            state_details = values.setdefault(\n                \"state_details\", cls.__fields__[\"state_details\"].get_default()\n            )\n            if not state_details.scheduled_time:\n                state_details.scheduled_time = pendulum.now(\"utc\")\n        return values\n\n    def is_scheduled(self) -&gt; bool:\n        return self.type == StateType.SCHEDULED\n\n    def is_pending(self) -&gt; bool:\n        return self.type == StateType.PENDING\n\n    def is_running(self) -&gt; bool:\n        return self.type == StateType.RUNNING\n\n    def is_completed(self) -&gt; bool:\n        return self.type == StateType.COMPLETED\n\n    def is_failed(self) -&gt; bool:\n        return self.type == StateType.FAILED\n\n    def is_crashed(self) -&gt; bool:\n        return self.type == StateType.CRASHED\n\n    def is_cancelled(self) -&gt; bool:\n        return self.type == StateType.CANCELLED\n\n    def is_cancelling(self) -&gt; bool:\n        return self.type == StateType.CANCELLING\n\n    def is_final(self) -&gt; bool:\n        return self.type in {\n            StateType.CANCELLED,\n            StateType.FAILED,\n            StateType.COMPLETED,\n            StateType.CRASHED,\n        }\n\n    def is_paused(self) -&gt; bool:\n        return self.type == StateType.PAUSED\n\n    def copy(\n        self,\n        *,\n        update: Optional[Dict[str, Any]] = None,\n        reset_fields: bool = False,\n        **kwargs,\n    ):\n        \"\"\"\n        Copying API models should return an object that could be inserted into the\n        database again. The 'timestamp' is reset using the default factory.\n        \"\"\"\n        update = update or {}\n        update.setdefault(\"timestamp\", self.__fields__[\"timestamp\"].get_default())\n        return super().copy(reset_fields=reset_fields, update=update, **kwargs)\n\n    def __repr__(self) -&gt; str:\n        \"\"\"\n        Generates a complete state representation appropriate for introspection\n        and debugging, including the result:\n\n        `MyCompletedState(message=\"my message\", type=COMPLETED, result=...)`\n        \"\"\"\n        from prefect.deprecated.data_documents import DataDocument\n\n        if isinstance(self.data, DataDocument):\n            result = self.data.decode()\n        else:\n            result = self.data\n\n        display = dict(\n            message=repr(self.message),\n            type=str(self.type.value),\n            result=repr(result),\n        )\n\n        return f\"{self.name}({', '.join(f'{k}={v}' for k, v in display.items())})\"\n\n    def __str__(self) -&gt; str:\n        \"\"\"\n        Generates a simple state representation appropriate for logging:\n\n        `MyCompletedState(\"my message\", type=COMPLETED)`\n        \"\"\"\n\n        display = []\n\n        if self.message:\n            display.append(repr(self.message))\n\n        if self.type.value.lower() != self.name.lower():\n            display.append(f\"type={self.type.value}\")\n\n        return f\"{self.name}({', '.join(display)})\"\n\n    def __hash__(self) -&gt; int:\n        return hash(\n            (\n                getattr(self.state_details, \"flow_run_id\", None),\n                getattr(self.state_details, \"task_run_id\", None),\n                self.timestamp,\n                self.type,\n            )\n        )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.result","title":"<code>result</code>","text":"<p>Retrieve the result attached to this state.</p> <p>Parameters:</p> Name Type Description Default <code>raise_on_failure</code> <code>bool</code> <p>a boolean specifying whether to raise an exception if the state is of type <code>FAILED</code> and the underlying data is an exception</p> <code>True</code> <code>fetch</code> <code>Optional[bool]</code> <p>a boolean specifying whether to resolve references to persisted results into data. For synchronous users, this defaults to <code>True</code>. For asynchronous users, this defaults to <code>False</code> for backwards compatibility.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If the state is failed but the result is not an exception.</p> <p>Returns:</p> Type Description <code>Union[R, Exception]</code> <p>The result of the run</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task(x):\n&gt;&gt;&gt;     return x\n</code></pre> <p>Get the result from a task future in a flow</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task(\"hello\")\n&gt;&gt;&gt;     state = future.wait()\n&gt;&gt;&gt;     result = state.result()\n&gt;&gt;&gt;     print(result)\n&gt;&gt;&gt; my_flow()\nhello\n</code></pre> <p>Get the result from a flow state</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return \"hello\"\n&gt;&gt;&gt; my_flow(return_state=True).result()\nhello\n</code></pre> <p>Get the result from a failed state</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     raise ValueError(\"oh no!\")\n&gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n&gt;&gt;&gt; state.result()  # Raises `ValueError`\n</code></pre> <p>Get the result from a failed state without erroring</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     raise ValueError(\"oh no!\")\n&gt;&gt;&gt; state = my_flow(return_state=True)\n&gt;&gt;&gt; result = state.result(raise_on_failure=False)\n&gt;&gt;&gt; print(result)\nValueError(\"oh no!\")\n</code></pre> <p>Get the result from a flow state in an async context</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     return \"hello\"\n&gt;&gt;&gt; state = await my_flow(return_state=True)\n&gt;&gt;&gt; await state.result()\nhello\n</code></pre> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def result(\n    self, raise_on_failure: bool = True, fetch: Optional[bool] = None\n) -&gt; Union[R, Exception]:\n    \"\"\"\n    Retrieve the result attached to this state.\n\n    Args:\n        raise_on_failure: a boolean specifying whether to raise an exception\n            if the state is of type `FAILED` and the underlying data is an exception\n        fetch: a boolean specifying whether to resolve references to persisted\n            results into data. For synchronous users, this defaults to `True`.\n            For asynchronous users, this defaults to `False` for backwards\n            compatibility.\n\n    Raises:\n        TypeError: If the state is failed but the result is not an exception.\n\n    Returns:\n        The result of the run\n\n    Examples:\n        &gt;&gt;&gt; from prefect import flow, task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task(x):\n        &gt;&gt;&gt;     return x\n\n        Get the result from a task future in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task(\"hello\")\n        &gt;&gt;&gt;     state = future.wait()\n        &gt;&gt;&gt;     result = state.result()\n        &gt;&gt;&gt;     print(result)\n        &gt;&gt;&gt; my_flow()\n        hello\n\n        Get the result from a flow state\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return \"hello\"\n        &gt;&gt;&gt; my_flow(return_state=True).result()\n        hello\n\n        Get the result from a failed state\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n        &gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n        &gt;&gt;&gt; state.result()  # Raises `ValueError`\n\n        Get the result from a failed state without erroring\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n        &gt;&gt;&gt; state = my_flow(return_state=True)\n        &gt;&gt;&gt; result = state.result(raise_on_failure=False)\n        &gt;&gt;&gt; print(result)\n        ValueError(\"oh no!\")\n\n\n        Get the result from a flow state in an async context\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     return \"hello\"\n        &gt;&gt;&gt; state = await my_flow(return_state=True)\n        &gt;&gt;&gt; await state.result()\n        hello\n    \"\"\"\n    from prefect.states import get_state_result\n\n    return get_state_result(self, raise_on_failure=raise_on_failure, fetch=fetch)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.to_state_create","title":"<code>to_state_create</code>","text":"<p>Convert this state to a <code>StateCreate</code> type which can be used to set the state of a run in the API.</p> <p>This method will drop this state's <code>data</code> if it is not a result type. Only results should be sent to the API. Other data is only available locally.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def to_state_create(self):\n    \"\"\"\n    Convert this state to a `StateCreate` type which can be used to set the state of\n    a run in the API.\n\n    This method will drop this state's `data` if it is not a result type. Only\n    results should be sent to the API. Other data is only available locally.\n    \"\"\"\n    from prefect.client.schemas.actions import StateCreate\n    from prefect.results import BaseResult\n\n    return StateCreate(\n        type=self.type,\n        name=self.name,\n        message=self.message,\n        data=self.data if isinstance(self.data, BaseResult) else None,\n        state_details=self.state_details,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.default_scheduled_start_time","title":"<code>default_scheduled_start_time</code>","text":"This should throw an error instead of setting a default but is out of <p>scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled into work refactoring state initialization</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>@root_validator\ndef default_scheduled_start_time(cls, values):\n    \"\"\"\n    TODO: This should throw an error instead of setting a default but is out of\n          scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled\n          into work refactoring state initialization\n    \"\"\"\n    if values.get(\"type\") == StateType.SCHEDULED:\n        state_details = values.setdefault(\n            \"state_details\", cls.__fields__[\"state_details\"].get_default()\n        )\n        if not state_details.scheduled_time:\n            state_details.scheduled_time = pendulum.now(\"utc\")\n    return values\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunPolicy","title":"<code>FlowRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a flow run should be orchestrated.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a flow run should be orchestrated.\"\"\"\n\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Optional[int] = Field(\n        default=None, description=\"The delay time between retries, in seconds.\"\n    )\n    pause_keys: Optional[set] = Field(\n        default_factory=set, description=\"Tracks pauses this run has observed.\"\n    )\n    resuming: Optional[bool] = Field(\n        default=False, description=\"Indicates if this run is resuming from a pause.\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRun","title":"<code>FlowRun</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRun(ObjectBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[State] = Field(\n        default=None,\n        description=\"The state of the flow run.\",\n        examples=[State(type=StateType.COMPLETED)],\n    )\n    job_variables: Optional[dict] = Field(\n        default=None, description=\"Job variables for the flow run.\"\n    )\n\n    # These are server-side optimizations and should not be present on client models\n    # TODO: Deprecate these fields\n\n    state_type: Optional[StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n\n    @validator(\"name\", pre=True)\n    def set_default_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunPolicy","title":"<code>TaskRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a task run should retry.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a task run should retry.\"\"\"\n\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Union[None, int, List[int]] = Field(\n        default=None,\n        description=\"A delay time or list of delay times between retries, in seconds.\",\n    )\n    retry_jitter_factor: Optional[float] = Field(\n        default=None, description=\"Determines the amount a retry should jitter\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n\n    @validator(\"retry_delay\")\n    def validate_configured_retry_delays(cls, v):\n        return list_length_50_or_less(v)\n\n    @validator(\"retry_jitter_factor\")\n    def validate_jitter_factor(cls, v):\n        return validate_not_negative(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunInput","title":"<code>TaskRunInput</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Base class for classes that represent inputs to task runs, which could include, constants, parameters, or other task runs.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunInput(PrefectBaseModel):\n    \"\"\"\n    Base class for classes that represent inputs to task runs, which\n    could include, constants, parameters, or other task runs.\n    \"\"\"\n\n    # freeze TaskRunInputs to allow them to be placed in sets\n    class Config:\n        frozen = True\n\n    input_type: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunResult","title":"<code>TaskRunResult</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents a task run result input to another task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunResult(TaskRunInput):\n    \"\"\"Represents a task run result input to another task run.\"\"\"\n\n    input_type: Literal[\"task_run\"] = \"task_run\"\n    id: UUID\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Parameter","title":"<code>Parameter</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents a parameter input to a task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Parameter(TaskRunInput):\n    \"\"\"Represents a parameter input to a task run.\"\"\"\n\n    input_type: Literal[\"parameter\"] = \"parameter\"\n    name: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Constant","title":"<code>Constant</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents constant input value to a task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Constant(TaskRunInput):\n    \"\"\"Represents constant input value to a task run.\"\"\"\n\n    input_type: Literal[\"constant\"] = \"constant\"\n    type: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace","title":"<code>Workspace</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A Prefect Cloud workspace.</p> <p>Expected payload for each workspace returned by the <code>me/workspaces</code> route.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Workspace(PrefectBaseModel):\n    \"\"\"\n    A Prefect Cloud workspace.\n\n    Expected payload for each workspace returned by the `me/workspaces` route.\n    \"\"\"\n\n    account_id: UUID = Field(..., description=\"The account id of the workspace.\")\n    account_name: str = Field(..., description=\"The account name.\")\n    account_handle: str = Field(..., description=\"The account's unique handle.\")\n    workspace_id: UUID = Field(..., description=\"The workspace id.\")\n    workspace_name: str = Field(..., description=\"The workspace name.\")\n    workspace_description: str = Field(..., description=\"Description of the workspace.\")\n    workspace_handle: str = Field(..., description=\"The workspace's unique handle.\")\n\n    class Config:\n        extra = \"ignore\"\n\n    @property\n    def handle(self) -&gt; str:\n        \"\"\"\n        The full handle of the workspace as `account_handle` / `workspace_handle`\n        \"\"\"\n        return self.account_handle + \"/\" + self.workspace_handle\n\n    def api_url(self) -&gt; str:\n        \"\"\"\n        Generate the API URL for accessing this workspace\n        \"\"\"\n        return (\n            f\"{PREFECT_CLOUD_API_URL.value()}\"\n            f\"/accounts/{self.account_id}\"\n            f\"/workspaces/{self.workspace_id}\"\n        )\n\n    def ui_url(self) -&gt; str:\n        \"\"\"\n        Generate the UI URL for accessing this workspace\n        \"\"\"\n        return (\n            f\"{PREFECT_CLOUD_UI_URL.value()}\"\n            f\"/account/{self.account_id}\"\n            f\"/workspace/{self.workspace_id}\"\n        )\n\n    def __hash__(self):\n        return hash(self.handle)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.handle","title":"<code>handle: str</code>  <code>property</code>","text":"<p>The full handle of the workspace as <code>account_handle</code> / <code>workspace_handle</code></p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.api_url","title":"<code>api_url</code>","text":"<p>Generate the API URL for accessing this workspace</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def api_url(self) -&gt; str:\n    \"\"\"\n    Generate the API URL for accessing this workspace\n    \"\"\"\n    return (\n        f\"{PREFECT_CLOUD_API_URL.value()}\"\n        f\"/accounts/{self.account_id}\"\n        f\"/workspaces/{self.workspace_id}\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.ui_url","title":"<code>ui_url</code>","text":"<p>Generate the UI URL for accessing this workspace</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def ui_url(self) -&gt; str:\n    \"\"\"\n    Generate the UI URL for accessing this workspace\n    \"\"\"\n    return (\n        f\"{PREFECT_CLOUD_UI_URL.value()}\"\n        f\"/account/{self.account_id}\"\n        f\"/workspace/{self.workspace_id}\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockType","title":"<code>BlockType</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block type</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockType(ObjectBaseModel):\n    \"\"\"An ORM representation of a block type\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n    is_protected: bool = Field(\n        default=False, description=\"Protected block types cannot be modified via API.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockDocument","title":"<code>BlockDocument</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block document.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockDocument(ObjectBaseModel):\n    \"\"\"An ORM representation of a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n    block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The associated block schema\"\n    )\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n    block_type_name: Optional[str] = Field(None, description=\"A block type name\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    block_document_references: Dict[str, Dict[str, Any]] = Field(\n        default_factory=dict, description=\"Record of the block document's references\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        # the BlockDocumentCreate subclass allows name=None\n        # and will inherit this validator\n        return raise_on_name_with_banned_characters(v)\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of flow data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Flow(ObjectBaseModel):\n    \"\"\"An ORM representation of flow data.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ObjectBaseModel</code></p> <p>An ORM representation of deployment data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Deployment(DeprecatedInfraOverridesField, ObjectBaseModel):\n    \"\"\"An ORM representation of deployment data.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the deployment.\")\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description for the deployment.\"\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The flow id associated with the deployment.\"\n    )\n    schedule: Optional[SCHEDULE_TYPES] = Field(\n        default=None, description=\"A schedule for the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether or not the deployment schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentSchedule] = Field(\n        default_factory=list, description=\"A list of schedules for the deployment.\"\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    pull_steps: Optional[List[dict]] = Field(\n        default=None,\n        description=\"Pull steps for cloning and running this deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the deployment\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The work queue for the deployment. If no work queue is set, work will not\"\n            \" be scheduled.\"\n        ),\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The last time the deployment was polled for status updates.\",\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    storage_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining storage used for this flow.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use for flow runs.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this deployment.\",\n    )\n    updated_by: Optional[UpdatedBy] = Field(\n        default=None,\n        description=\"Optional information about the updater of this deployment.\",\n    )\n    work_queue_id: UUID = Field(\n        default=None,\n        description=(\n            \"The id of the work pool queue to which this deployment is assigned.\"\n        ),\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.ConcurrencyLimit","title":"<code>ConcurrencyLimit</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a concurrency limit.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class ConcurrencyLimit(ObjectBaseModel):\n    \"\"\"An ORM representation of a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: List[UUID] = Field(\n        default_factory=list,\n        description=\"A list of active run ids using a concurrency slot\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockSchema","title":"<code>BlockSchema</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block schema.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockSchema(ObjectBaseModel):\n    \"\"\"An ORM representation of a block schema.\"\"\"\n\n    checksum: str = Field(default=..., description=\"The block schema's unique checksum\")\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockSchemaReference","title":"<code>BlockSchemaReference</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block schema reference.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockSchemaReference(ObjectBaseModel):\n    \"\"\"An ORM representation of a block schema reference.\"\"\"\n\n    parent_block_schema_id: UUID = Field(\n        default=..., description=\"ID of block schema the reference is nested within\"\n    )\n    parent_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The block schema the reference is nested within\"\n    )\n    reference_block_schema_id: UUID = Field(\n        default=..., description=\"ID of the nested block schema\"\n    )\n    reference_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The nested block schema\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockDocumentReference","title":"<code>BlockDocumentReference</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block document reference.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockDocumentReference(ObjectBaseModel):\n    \"\"\"An ORM representation of a block document reference.\"\"\"\n\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    parent_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    reference_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.SavedSearchFilter","title":"<code>SavedSearchFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A filter for a saved search model. Intended for use by the Prefect UI.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class SavedSearchFilter(PrefectBaseModel):\n    \"\"\"A filter for a saved search model. Intended for use by the Prefect UI.\"\"\"\n\n    object: str = Field(default=..., description=\"The object over which to filter.\")\n    property: str = Field(\n        default=..., description=\"The property of the object on which to filter.\"\n    )\n    type: str = Field(default=..., description=\"The type of the property.\")\n    operation: str = Field(\n        default=...,\n        description=\"The operator to apply to the object. For example, `equals`.\",\n    )\n    value: Any = Field(\n        default=..., description=\"A JSON-compatible value for the filter.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.SavedSearch","title":"<code>SavedSearch</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of saved search data. Represents a set of filter criteria.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class SavedSearch(ObjectBaseModel):\n    \"\"\"An ORM representation of saved search data. Represents a set of filter criteria.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Log","title":"<code>Log</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of log data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Log(ObjectBaseModel):\n    \"\"\"An ORM representation of log data.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run ID associated with the log.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run ID associated with the log.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.QueueFilter","title":"<code>QueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter criteria definition for a work queue.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class QueueFilter(PrefectBaseModel):\n    \"\"\"Filter criteria definition for a work queue.\"\"\"\n\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"Only include flow runs with these tags in the work queue.\",\n    )\n    deployment_ids: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"Only include flow runs from these deployments in the work queue.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueue","title":"<code>WorkQueue</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a work queue</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueue(ObjectBaseModel):\n    \"\"\"An ORM representation of a work queue\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"An optional concurrency limit for the work queue.\"\n    )\n    priority: PositiveInteger = Field(\n        default=1,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n    work_pool_name: Optional[str] = Field(default=None)\n    # Will be required after a future migration\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    filter: Optional[QueueFilter] = Field(\n        default=None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time an agent polled this queue for work.\"\n    )\n    status: Optional[WorkQueueStatus] = Field(\n        default=None, description=\"The queue status.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueHealthPolicy","title":"<code>WorkQueueHealthPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueueHealthPolicy(PrefectBaseModel):\n    maximum_late_runs: Optional[int] = Field(\n        default=0,\n        description=(\n            \"The maximum number of late runs in the work queue before it is deemed\"\n            \" unhealthy. Defaults to `0`.\"\n        ),\n    )\n    maximum_seconds_since_last_polled: Optional[int] = Field(\n        default=60,\n        description=(\n            \"The maximum number of time in seconds elapsed since work queue has been\"\n            \" polled before it is deemed unhealthy. Defaults to `60`.\"\n        ),\n    )\n\n    def evaluate_health_status(\n        self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n    ) -&gt; bool:\n        \"\"\"\n        Given empirical information about the state of the work queue, evaluate its health status.\n\n        Args:\n            late_runs: the count of late runs for the work queue.\n            last_polled: the last time the work queue was polled, if available.\n\n        Returns:\n            bool: whether or not the work queue is healthy.\n        \"\"\"\n        healthy = True\n        if (\n            self.maximum_late_runs is not None\n            and late_runs_count &gt; self.maximum_late_runs\n        ):\n            healthy = False\n\n        if self.maximum_seconds_since_last_polled is not None:\n            if (\n                last_polled is None\n                or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n                &gt; self.maximum_seconds_since_last_polled\n            ):\n                healthy = False\n\n        return healthy\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueHealthPolicy.evaluate_health_status","title":"<code>evaluate_health_status</code>","text":"<p>Given empirical information about the state of the work queue, evaluate its health status.</p> <p>Parameters:</p> Name Type Description Default <code>late_runs</code> <p>the count of late runs for the work queue.</p> required <code>last_polled</code> <code>Optional[DateTimeTZ]</code> <p>the last time the work queue was polled, if available.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the work queue is healthy.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def evaluate_health_status(\n    self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n) -&gt; bool:\n    \"\"\"\n    Given empirical information about the state of the work queue, evaluate its health status.\n\n    Args:\n        late_runs: the count of late runs for the work queue.\n        last_polled: the last time the work queue was polled, if available.\n\n    Returns:\n        bool: whether or not the work queue is healthy.\n    \"\"\"\n    healthy = True\n    if (\n        self.maximum_late_runs is not None\n        and late_runs_count &gt; self.maximum_late_runs\n    ):\n        healthy = False\n\n    if self.maximum_seconds_since_last_polled is not None:\n        if (\n            last_polled is None\n            or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n            &gt; self.maximum_seconds_since_last_polled\n        ):\n            healthy = False\n\n    return healthy\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunNotificationPolicy","title":"<code>FlowRunNotificationPolicy</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a flow run notification.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunNotificationPolicy(ObjectBaseModel):\n    \"\"\"An ORM representation of a flow run notification.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Agent","title":"<code>Agent</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of an agent</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Agent(ObjectBaseModel):\n    \"\"\"An ORM representation of an agent\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the agent. If a name is not provided, it will be\"\n            \" auto-generated.\"\n        ),\n    )\n    work_queue_id: UUID = Field(\n        default=..., description=\"The work queue with which the agent is associated.\"\n    )\n    last_activity_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time this agent polled for work.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkPool","title":"<code>WorkPool</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a work pool</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkPool(ObjectBaseModel):\n    \"\"\"An ORM representation of a work pool\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description of the work pool.\"\n    )\n    type: str = Field(description=\"The work pool type.\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n    status: Optional[WorkPoolStatus] = Field(\n        default=None, description=\"The current status of the work pool.\"\n    )\n\n    # this required field has a default of None so that the custom validator\n    # below will be called and produce a more helpful error message\n    default_queue_id: UUID = Field(\n        None, description=\"The id of the pool's default queue.\"\n    )\n\n    @property\n    def is_push_pool(self) -&gt; bool:\n        return self.type.endswith(\":push\")\n\n    @property\n    def is_managed_pool(self) -&gt; bool:\n        return self.type.endswith(\":managed\")\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n\n    @validator(\"default_queue_id\", always=True)\n    def helpful_error_for_missing_default_queue_id(cls, v):\n        return validate_default_queue_id_not_none(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Worker","title":"<code>Worker</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a worker</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Worker(ObjectBaseModel):\n    \"\"\"An ORM representation of a worker\"\"\"\n\n    name: str = Field(description=\"The name of the worker.\")\n    work_pool_id: UUID = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    last_heartbeat_time: datetime.datetime = Field(\n        None, description=\"The last time the worker process sent a heartbeat.\"\n    )\n    heartbeat_interval_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to expect between heartbeats sent by the worker.\"\n        ),\n    )\n    status: WorkerStatus = Field(\n        WorkerStatus.OFFLINE,\n        description=\"Current status of the worker.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunInput","title":"<code>FlowRunInput</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunInput(ObjectBaseModel):\n    flow_run_id: UUID = Field(description=\"The flow run ID associated with the input.\")\n    key: str = Field(description=\"The key of the input.\")\n    value: str = Field(description=\"The value of the input.\")\n    sender: Optional[str] = Field(description=\"The sender of the input.\")\n\n    @property\n    def decoded_value(self) -&gt; Any:\n        \"\"\"\n        Decode the value of the input.\n\n        Returns:\n            Any: the decoded value\n        \"\"\"\n        return orjson.loads(self.value)\n\n    @validator(\"key\", check_fields=False)\n    def validate_name_characters(cls, v):\n        raise_on_name_alphanumeric_dashes_only(v)\n        return v\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunInput.decoded_value","title":"<code>decoded_value: Any</code>  <code>property</code>","text":"<p>Decode the value of the input.</p> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>the decoded value</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.GlobalConcurrencyLimit","title":"<code>GlobalConcurrencyLimit</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a global concurrency limit</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class GlobalConcurrencyLimit(ObjectBaseModel):\n    \"\"\"An ORM representation of a global concurrency limit\"\"\"\n\n    name: str = Field(description=\"The name of the global concurrency limit.\")\n    limit: int = Field(\n        description=(\n            \"The maximum number of slots that can be occupied on this concurrency\"\n            \" limit.\"\n        )\n    )\n    active: Optional[bool] = Field(\n        default=True,\n        description=\"Whether or not the concurrency limit is in an active state.\",\n    )\n    active_slots: Optional[int] = Field(\n        default=0,\n        description=\"Number of tasks currently using a concurrency slot.\",\n    )\n    slot_decay_per_second: Optional[float] = Field(\n        default=0.0,\n        description=(\n            \"Controls the rate at which slots are released when the concurrency limit\"\n            \" is used as a rate limit.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_4","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses","title":"<code>prefect.client.schemas.responses</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.SetStateStatus","title":"<code>SetStateStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumerates return statuses for setting run states.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class SetStateStatus(AutoEnum):\n    \"\"\"Enumerates return statuses for setting run states.\"\"\"\n\n    ACCEPT = AutoEnum.auto()\n    REJECT = AutoEnum.auto()\n    ABORT = AutoEnum.auto()\n    WAIT = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateAcceptDetails","title":"<code>StateAcceptDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ACCEPT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateAcceptDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ACCEPT state transition.\"\"\"\n\n    type: Literal[\"accept_details\"] = Field(\n        default=\"accept_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateRejectDetails","title":"<code>StateRejectDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a REJECT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateRejectDetails(PrefectBaseModel):\n    \"\"\"Details associated with a REJECT state transition.\"\"\"\n\n    type: Literal[\"reject_details\"] = Field(\n        default=\"reject_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was rejected.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateAbortDetails","title":"<code>StateAbortDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ABORT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateAbortDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ABORT state transition.\"\"\"\n\n    type: Literal[\"abort_details\"] = Field(\n        default=\"abort_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was aborted.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateWaitDetails","title":"<code>StateWaitDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a WAIT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateWaitDetails(PrefectBaseModel):\n    \"\"\"Details associated with a WAIT state transition.\"\"\"\n\n    type: Literal[\"wait_details\"] = Field(\n        default=\"wait_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    delay_seconds: int = Field(\n        default=...,\n        description=(\n            \"The length of time in seconds the client should wait before transitioning\"\n            \" states.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition should wait.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.HistoryResponseState","title":"<code>HistoryResponseState</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a single state's history over an interval.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class HistoryResponseState(PrefectBaseModel):\n    \"\"\"Represents a single state's history over an interval.\"\"\"\n\n    state_type: objects.StateType = Field(default=..., description=\"The state type.\")\n    state_name: str = Field(default=..., description=\"The state name.\")\n    count_runs: int = Field(\n        default=...,\n        description=\"The number of runs in the specified state during the interval.\",\n    )\n    sum_estimated_run_time: datetime.timedelta = Field(\n        default=...,\n        description=\"The total estimated run time of all runs during the interval.\",\n    )\n    sum_estimated_lateness: datetime.timedelta = Field(\n        default=...,\n        description=(\n            \"The sum of differences between actual and expected start time during the\"\n            \" interval.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.HistoryResponse","title":"<code>HistoryResponse</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a history of aggregation states over an interval</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class HistoryResponse(PrefectBaseModel):\n    \"\"\"Represents a history of aggregation states over an interval\"\"\"\n\n    interval_start: DateTimeTZ = Field(\n        default=..., description=\"The start date of the interval.\"\n    )\n    interval_end: DateTimeTZ = Field(\n        default=..., description=\"The end date of the interval.\"\n    )\n    states: List[HistoryResponseState] = Field(\n        default=..., description=\"A list of state histories during the interval.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.OrchestrationResult","title":"<code>OrchestrationResult</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for the output of state orchestration.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class OrchestrationResult(PrefectBaseModel):\n    \"\"\"\n    A container for the output of state orchestration.\n    \"\"\"\n\n    state: Optional[objects.State]\n    status: SetStateStatus\n    details: StateResponseDetails\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.FlowRunResponse","title":"<code>FlowRunResponse</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class FlowRunResponse(ObjectBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[objects.State] = Field(\n        default=None,\n        description=\"The state of the flow run.\",\n        examples=[objects.State(type=objects.StateType.COMPLETED)],\n    )\n    job_variables: Optional[dict] = Field(\n        default=None, description=\"Job variables for the flow run.\"\n    )\n\n    # These are server-side optimizations and should not be present on client models\n    # TODO: Deprecate these fields\n\n    state_type: Optional[objects.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, objects.FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.GlobalConcurrencyLimitResponse","title":"<code>GlobalConcurrencyLimitResponse</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>A response object for global concurrency limits.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class GlobalConcurrencyLimitResponse(ObjectBaseModel):\n    \"\"\"\n    A response object for global concurrency limits.\n    \"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the global concurrency limit is active.\"\n    )\n    name: str = Field(\n        default=..., description=\"The name of the global concurrency limit.\"\n    )\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=..., description=\"The number of active slots.\")\n    slot_decay_per_second: float = Field(\n        default=2.0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_5","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules","title":"<code>prefect.client.schemas.schedules</code>","text":"<p>Schedule schemas</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.IntervalSchedule","title":"<code>IntervalSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no <code>anchor_date</code> is supplied, the current UTC time is used.  If a timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a <code>timezone</code> can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date.</p> <p>NOTE: If the <code>IntervalSchedule</code> <code>anchor_date</code> or <code>timezone</code> is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>timedelta</code> <p>an interval to schedule on</p> required <code>anchor_date</code> <code>DateTimeTZ</code> <p>an anchor date to schedule increments against; if not provided, the current timestamp will be used</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class IntervalSchedule(PrefectBaseModel):\n    \"\"\"\n    A schedule formed by adding `interval` increments to an `anchor_date`. If no\n    `anchor_date` is supplied, the current UTC time is used.  If a\n    timezone-naive datetime is provided for `anchor_date`, it is assumed to be\n    in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,\n    anchor dates are always stored as UTC offsets, so a `timezone` can be\n    provided to determine localization behaviors like DST boundary handling. If\n    none is provided it will be inferred from the anchor date.\n\n    NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a\n    DST-observing timezone, then the schedule will adjust itself appropriately.\n    Intervals greater than 24 hours will follow DST conventions, while intervals\n    of less than 24 hours will follow UTC intervals. For example, an hourly\n    schedule will fire every UTC hour, even across DST boundaries. When clocks\n    are set back, this will result in two runs that *appear* to both be\n    scheduled for 1am local time, even though they are an hour apart in UTC\n    time. For longer intervals, like a daily schedule, the interval schedule\n    will adjust for DST boundaries so that the clock-hour remains constant. This\n    means that a daily schedule that always fires at 9am will observe DST and\n    continue to fire at 9am in the local time zone.\n\n    Args:\n        interval (datetime.timedelta): an interval to schedule on\n        anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against;\n            if not provided, the current timestamp will be used\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n        exclude_none = True\n\n    interval: PositiveDuration\n    anchor_date: Optional[DateTimeTZ] = None\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"anchor_date\", always=True)\n    def validate_anchor_date(cls, v):\n        return default_anchor_date(v)\n\n    @validator(\"timezone\", always=True)\n    def validate_default_timezone(cls, v, values):\n        return default_timezone(v, values=values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Cron schedule</p> <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST.</p> <p>Parameters:</p> Name Type Description Default <code>cron</code> <code>str</code> <p>a valid cron string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string in IANA tzdata format (for example, America/New_York).</p> required <code>day_or</code> <code>bool</code> <p>Control how croniter handles <code>day</code> and <code>day_of_week</code> entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class CronSchedule(PrefectBaseModel):\n    \"\"\"\n    Cron schedule\n\n    NOTE: If the timezone is a DST-observing one, then the schedule will adjust\n    itself appropriately. Cron's rules for DST are based on schedule times, not\n    intervals. This means that an hourly cron schedule will fire on every new\n    schedule hour, not every elapsed hour; for example, when clocks are set back\n    this will result in a two-hour pause as the schedule will fire *the first\n    time* 1am is reached and *the first time* 2am is reached, 120 minutes later.\n    Longer schedules, such as one that fires at 9am every morning, will\n    automatically adjust for DST.\n\n    Args:\n        cron (str): a valid cron string\n        timezone (str): a valid timezone string in IANA tzdata format (for example,\n            America/New_York).\n        day_or (bool, optional): Control how croniter handles `day` and `day_of_week`\n            entries. Defaults to True, matching cron which connects those values using\n            OR. If the switch is set to False, the values are connected using AND. This\n            behaves like fcron and enables you to e.g. define a job that executes each\n            2nd friday of a month by setting the days of month and the weekday.\n\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    cron: str = Field(default=..., examples=[\"0 0 * * *\"])\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n    day_or: bool = Field(\n        default=True,\n        description=(\n            \"Control croniter behavior for handling day and day_of_week entries.\"\n        ),\n    )\n\n    @validator(\"timezone\")\n    def valid_timezone(cls, v):\n        return default_timezone(v)\n\n    @validator(\"cron\")\n    def valid_cron_string(cls, v):\n        return validate_cron_string(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.RRuleSchedule","title":"<code>RRuleSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>RRule schedule, based on the iCalendar standard (RFC 5545) as implemented in <code>dateutils.rrule</code>.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more.</p> <p>Note that as a calendar-oriented standard, <code>RRuleSchedules</code> are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p> <p>Parameters:</p> Name Type Description Default <code>rrule</code> <code>str</code> <p>a valid RRule string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class RRuleSchedule(PrefectBaseModel):\n    \"\"\"\n    RRule schedule, based on the iCalendar standard\n    ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as\n    implemented in `dateutils.rrule`.\n\n    RRules are appropriate for any kind of calendar-date manipulation, including\n    irregular intervals, repetition, exclusions, week day or day-of-month\n    adjustments, and more.\n\n    Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to\n    to the initial timezone provided. A 9am daily schedule with a daylight saving\n    time-aware start date will maintain a local 9am time through DST boundaries;\n    a 9am daily schedule with a UTC start date will maintain a 9am UTC time.\n\n    Args:\n        rrule (str): a valid RRule string\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    rrule: str\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"rrule\")\n    def validate_rrule_str(cls, v):\n        return validate_rrule_string(v)\n\n    @classmethod\n    def from_rrule(cls, rrule: dateutil.rrule.rrule):\n        if isinstance(rrule, dateutil.rrule.rrule):\n            if rrule._dtstart.tzinfo is not None:\n                timezone = rrule._dtstart.tzinfo.name\n            else:\n                timezone = \"UTC\"\n            return RRuleSchedule(rrule=str(rrule), timezone=timezone)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            dtstarts = [rr._dtstart for rr in rrule._rrule if rr._dtstart is not None]\n            unique_dstarts = set(pendulum.instance(d).in_tz(\"UTC\") for d in dtstarts)\n            unique_timezones = set(d.tzinfo for d in dtstarts if d.tzinfo is not None)\n\n            if len(unique_timezones) &gt; 1:\n                raise ValueError(\n                    f\"rruleset has too many dtstart timezones: {unique_timezones}\"\n                )\n\n            if len(unique_dstarts) &gt; 1:\n                raise ValueError(f\"rruleset has too many dtstarts: {unique_dstarts}\")\n\n            if unique_dstarts and unique_timezones:\n                timezone = dtstarts[0].tzinfo.name\n            else:\n                timezone = \"UTC\"\n\n            rruleset_string = \"\"\n            if rrule._rrule:\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._rrule)\n            if rrule._exrule:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._exrule).replace(\n                    \"RRULE\", \"EXRULE\"\n                )\n            if rrule._rdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"RDATE:\" + \",\".join(\n                    rd.strftime(\"%Y%m%dT%H%M%SZ\") for rd in rrule._rdate\n                )\n            if rrule._exdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"EXDATE:\" + \",\".join(\n                    exd.strftime(\"%Y%m%dT%H%M%SZ\") for exd in rrule._exdate\n                )\n            return RRuleSchedule(rrule=rruleset_string, timezone=timezone)\n        else:\n            raise ValueError(f\"Invalid RRule object: {rrule}\")\n\n    def to_rrule(self) -&gt; dateutil.rrule.rrule:\n        \"\"\"\n        Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n        here\n        \"\"\"\n        rrule = dateutil.rrule.rrulestr(\n            self.rrule,\n            dtstart=DEFAULT_ANCHOR_DATE,\n            cache=True,\n        )\n        timezone = dateutil.tz.gettz(self.timezone)\n        if isinstance(rrule, dateutil.rrule.rrule):\n            kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n            if rrule._until:\n                kwargs.update(\n                    until=rrule._until.replace(tzinfo=timezone),\n                )\n            return rrule.replace(**kwargs)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            # update rrules\n            localized_rrules = []\n            for rr in rrule._rrule:\n                kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n                if rr._until:\n                    kwargs.update(\n                        until=rr._until.replace(tzinfo=timezone),\n                    )\n                localized_rrules.append(rr.replace(**kwargs))\n            rrule._rrule = localized_rrules\n\n            # update exrules\n            localized_exrules = []\n            for exr in rrule._exrule:\n                kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n                if exr._until:\n                    kwargs.update(\n                        until=exr._until.replace(tzinfo=timezone),\n                    )\n                localized_exrules.append(exr.replace(**kwargs))\n            rrule._exrule = localized_exrules\n\n            # update rdates\n            localized_rdates = []\n            for rd in rrule._rdate:\n                localized_rdates.append(rd.replace(tzinfo=timezone))\n            rrule._rdate = localized_rdates\n\n            # update exdates\n            localized_exdates = []\n            for exd in rrule._exdate:\n                localized_exdates.append(exd.replace(tzinfo=timezone))\n            rrule._exdate = localized_exdates\n\n            return rrule\n\n    @validator(\"timezone\", always=True)\n    def valid_timezone(cls, v):\n        return validate_rrule_timezone(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.RRuleSchedule.to_rrule","title":"<code>to_rrule</code>","text":"<p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates here</p> Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>def to_rrule(self) -&gt; dateutil.rrule.rrule:\n    \"\"\"\n    Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n    here\n    \"\"\"\n    rrule = dateutil.rrule.rrulestr(\n        self.rrule,\n        dtstart=DEFAULT_ANCHOR_DATE,\n        cache=True,\n    )\n    timezone = dateutil.tz.gettz(self.timezone)\n    if isinstance(rrule, dateutil.rrule.rrule):\n        kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n        if rrule._until:\n            kwargs.update(\n                until=rrule._until.replace(tzinfo=timezone),\n            )\n        return rrule.replace(**kwargs)\n    elif isinstance(rrule, dateutil.rrule.rruleset):\n        # update rrules\n        localized_rrules = []\n        for rr in rrule._rrule:\n            kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n            if rr._until:\n                kwargs.update(\n                    until=rr._until.replace(tzinfo=timezone),\n                )\n            localized_rrules.append(rr.replace(**kwargs))\n        rrule._rrule = localized_rrules\n\n        # update exrules\n        localized_exrules = []\n        for exr in rrule._exrule:\n            kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n            if exr._until:\n                kwargs.update(\n                    until=exr._until.replace(tzinfo=timezone),\n                )\n            localized_exrules.append(exr.replace(**kwargs))\n        rrule._exrule = localized_exrules\n\n        # update rdates\n        localized_rdates = []\n        for rd in rrule._rdate:\n            localized_rdates.append(rd.replace(tzinfo=timezone))\n        rrule._rdate = localized_rdates\n\n        # update exdates\n        localized_exdates = []\n        for exd in rrule._exdate:\n            localized_exdates.append(exd.replace(tzinfo=timezone))\n        rrule._exdate = localized_exdates\n\n        return rrule\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.construct_schedule","title":"<code>construct_schedule</code>","text":"<p>Construct a schedule from the provided arguments.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>Optional[Union[int, float, timedelta]]</code> <p>An interval on which to schedule runs. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>anchor_date</code> <code>Optional[Union[datetime, str]]</code> <p>The start date for an interval schedule.</p> <code>None</code> <code>cron</code> <code>Optional[str]</code> <p>A cron schedule for runs.</p> <code>None</code> <code>rrule</code> <code>Optional[str]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>timezone</code> <code>Optional[str]</code> <p>A timezone to use for the schedule. Defaults to UTC.</p> <code>None</code> Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>def construct_schedule(\n    interval: Optional[Union[int, float, datetime.timedelta]] = None,\n    anchor_date: Optional[Union[datetime.datetime, str]] = None,\n    cron: Optional[str] = None,\n    rrule: Optional[str] = None,\n    timezone: Optional[str] = None,\n) -&gt; SCHEDULE_TYPES:\n    \"\"\"\n    Construct a schedule from the provided arguments.\n\n    Args:\n        interval: An interval on which to schedule runs. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        anchor_date: The start date for an interval schedule.\n        cron: A cron schedule for runs.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        timezone: A timezone to use for the schedule. Defaults to UTC.\n    \"\"\"\n    num_schedules = sum(1 for entry in (interval, cron, rrule) if entry is not None)\n    if num_schedules &gt; 1:\n        raise ValueError(\"Only one of interval, cron, or rrule can be provided.\")\n\n    if anchor_date and not interval:\n        raise ValueError(\n            \"An anchor date can only be provided with an interval schedule\"\n        )\n\n    if timezone and not (interval or cron or rrule):\n        raise ValueError(\n            \"A timezone can only be provided with interval, cron, or rrule\"\n        )\n\n    schedule = None\n    if interval:\n        if isinstance(interval, (int, float)):\n            interval = datetime.timedelta(seconds=interval)\n        schedule = IntervalSchedule(\n            interval=interval, anchor_date=anchor_date, timezone=timezone\n        )\n    elif cron:\n        schedule = CronSchedule(cron=cron, timezone=timezone)\n    elif rrule:\n        schedule = RRuleSchedule(rrule=rrule, timezone=timezone)\n\n    if schedule is None:\n        raise ValueError(\"Either interval, cron, or rrule must be provided\")\n\n    return schedule\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_6","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting","title":"<code>prefect.client.schemas.sorting</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.FlowRunSort","title":"<code>FlowRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow run sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class FlowRunSort(AutoEnum):\n    \"\"\"Defines flow run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    START_TIME_ASC = AutoEnum.auto()\n    START_TIME_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.TaskRunSort","title":"<code>TaskRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines task run sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class TaskRunSort(AutoEnum):\n    \"\"\"Defines task run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.AutomationSort","title":"<code>AutomationSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines automation sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class AutomationSort(AutoEnum):\n    \"\"\"Defines automation sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.LogSort","title":"<code>LogSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines log sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class LogSort(AutoEnum):\n    \"\"\"Defines log sorting options.\"\"\"\n\n    TIMESTAMP_ASC = AutoEnum.auto()\n    TIMESTAMP_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.FlowSort","title":"<code>FlowSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class FlowSort(AutoEnum):\n    \"\"\"Defines flow sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.DeploymentSort","title":"<code>DeploymentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines deployment sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class DeploymentSort(AutoEnum):\n    \"\"\"Defines deployment sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.ArtifactSort","title":"<code>ArtifactSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class ArtifactSort(AutoEnum):\n    \"\"\"Defines artifact sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.ArtifactCollectionSort","title":"<code>ArtifactCollectionSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact collection sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class ArtifactCollectionSort(AutoEnum):\n    \"\"\"Defines artifact collection sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.VariableSort","title":"<code>VariableSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines variables sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class VariableSort(AutoEnum):\n    \"\"\"Defines variables sorting options.\"\"\"\n\n    CREATED_DESC = \"CREATED_DESC\"\n    UPDATED_DESC = \"UPDATED_DESC\"\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.BlockDocumentSort","title":"<code>BlockDocumentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines block document sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class BlockDocumentSort(AutoEnum):\n    \"\"\"Defines block document sorting options.\"\"\"\n\n    NAME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    BLOCK_TYPE_AND_NAME_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/","title":"utilities","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities","title":"<code>prefect.client.utilities</code>","text":"<p>Utilities for working with clients.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities.get_or_create_client","title":"<code>get_or_create_client</code>","text":"<p>Returns provided client, infers a client from context if available, or creates a new client.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>client (PrefectClient</code> <p>an optional client to use</p> required <p>Returns:</p> Type Description <code>Tuple[PrefectClient, bool]</code> <ul> <li>tuple: a tuple of the client and a boolean indicating if the client was inferred from context</li> </ul> Source code in <code>prefect/client/utilities.py</code> <pre><code>def get_or_create_client(\n    client: Optional[\"PrefectClient\"] = None,\n) -&gt; Tuple[\"PrefectClient\", bool]:\n    \"\"\"\n    Returns provided client, infers a client from context if available, or creates a new client.\n\n    Args:\n        - client (PrefectClient, optional): an optional client to use\n\n    Returns:\n        - tuple: a tuple of the client and a boolean indicating if the client was inferred from context\n    \"\"\"\n    if client is not None:\n        return client, True\n    from prefect._internal.concurrency.event_loop import get_running_loop\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    flow_run_context = FlowRunContext.get()\n    task_run_context = TaskRunContext.get()\n\n    if (\n        flow_run_context\n        and getattr(flow_run_context.client, \"_loop\", None) == get_running_loop()\n    ):\n        return flow_run_context.client, True\n    elif (\n        task_run_context\n        and getattr(task_run_context.client, \"_loop\", None) == get_running_loop()\n    ):\n        return task_run_context.client, True\n    else:\n        from prefect.client.orchestration import get_client as get_httpx_client\n\n        return get_httpx_client(), False\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities.inject_client","title":"<code>inject_client</code>","text":"<p>Simple helper to provide a context managed client to a asynchronous function.</p> <p>The decorated function must take a <code>client</code> kwarg and if a client is passed when called it will be used instead of creating a new one, but it will not be context managed as it is assumed that the caller is managing the context.</p> Source code in <code>prefect/client/utilities.py</code> <pre><code>def inject_client(\n    fn: Callable[P, Coroutine[Any, Any, Any]],\n) -&gt; Callable[P, Coroutine[Any, Any, Any]]:\n    \"\"\"\n    Simple helper to provide a context managed client to a asynchronous function.\n\n    The decorated function _must_ take a `client` kwarg and if a client is passed when\n    called it will be used instead of creating a new one, but it will not be context\n    managed as it is assumed that the caller is managing the context.\n    \"\"\"\n\n    @wraps(fn)\n    async def with_injected_client(*args: P.args, **kwargs: P.kwargs) -&gt; Any:\n        client = cast(Optional[\"PrefectClient\"], kwargs.pop(\"client\", None))\n        client, inferred = get_or_create_client(client)\n        if not inferred:\n            context = client\n        else:\n            from prefect.utilities.asyncutils import asyncnullcontext\n\n            context = asyncnullcontext()\n        async with context as new_client:\n            kwargs.setdefault(\"client\", new_client or client)\n            return await fn(*args, **kwargs)\n\n    return with_injected_client\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/concurrency/asyncio/","title":"asyncio","text":"","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio","title":"<code>prefect.concurrency.asyncio</code>","text":"","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.AcquireConcurrencySlotTimeoutError","title":"<code>AcquireConcurrencySlotTimeoutError</code>","text":"<p>               Bases: <code>TimeoutError</code></p> <p>Raised when acquiring a concurrency slot times out.</p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>class AcquireConcurrencySlotTimeoutError(TimeoutError):\n    \"\"\"Raised when acquiring a concurrency slot times out.\"\"\"\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.ConcurrencySlotAcquisitionError","title":"<code>ConcurrencySlotAcquisitionError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when an unhandlable occurs while acquiring concurrency slots.</p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>class ConcurrencySlotAcquisitionError(Exception):\n    \"\"\"Raised when an unhandlable occurs while acquiring concurrency slots.\"\"\"\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.concurrency","title":"<code>concurrency</code>  <code>async</code>","text":"<p>A context manager that acquires and releases concurrency slots from the given concurrency limits.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> <code>timeout_seconds</code> <code>Optional[float]</code> <p>The number of seconds to wait for the slots to be acquired before raising a <code>TimeoutError</code>. A timeout of <code>None</code> will wait indefinitely.</p> <code>None</code> <p>Raises:</p> Type Description <code>TimeoutError</code> <p>If the slots are not acquired within the given timeout.</p> <p>A simple example of using the async <code>concurrency</code> context manager: <pre><code>from prefect.concurrency.asyncio import concurrency\n\nasync def resource_heavy():\n    async with concurrency(\"test\", occupy=1):\n        print(\"Resource heavy task\")\n\nasync def main():\n    await resource_heavy()\n</code></pre></p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>@asynccontextmanager\nasync def concurrency(\n    names: Union[str, List[str]],\n    occupy: int = 1,\n    timeout_seconds: Optional[float] = None,\n):\n    \"\"\"A context manager that acquires and releases concurrency slots from the\n    given concurrency limits.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n        timeout_seconds: The number of seconds to wait for the slots to be acquired before\n            raising a `TimeoutError`. A timeout of `None` will wait indefinitely.\n\n    Raises:\n        TimeoutError: If the slots are not acquired within the given timeout.\n\n    Example:\n    A simple example of using the async `concurrency` context manager:\n    ```python\n    from prefect.concurrency.asyncio import concurrency\n\n    async def resource_heavy():\n        async with concurrency(\"test\", occupy=1):\n            print(\"Resource heavy task\")\n\n    async def main():\n        await resource_heavy()\n    ```\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = await _acquire_concurrency_slots(\n        names, occupy, timeout_seconds=timeout_seconds\n    )\n    acquisition_time = pendulum.now(\"UTC\")\n    emitted_events = _emit_concurrency_acquisition_events(limits, occupy)\n\n    try:\n        yield\n    finally:\n        occupancy_period = cast(Interval, (pendulum.now(\"UTC\") - acquisition_time))\n        await _release_concurrency_slots(\n            names, occupy, occupancy_period.total_seconds()\n        )\n        _emit_concurrency_release_events(limits, occupy, emitted_events)\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.rate_limit","title":"<code>rate_limit</code>  <code>async</code>","text":"<p>Block execution until an <code>occupy</code> number of slots of the concurrency limits given in <code>names</code> are acquired. Requires that all given concurrency limits have a slot decay.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>async def rate_limit(names: Union[str, List[str]], occupy: int = 1):\n    \"\"\"Block execution until an `occupy` number of slots of the concurrency\n    limits given in `names` are acquired. Requires that all given concurrency\n    limits have a slot decay.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = await _acquire_concurrency_slots(names, occupy, mode=\"rate_limit\")\n    _emit_concurrency_acquisition_events(limits, occupy)\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/events/","title":"events","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/events/#prefect.concurrency.events","title":"<code>prefect.concurrency.events</code>","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/services/","title":"services","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/services/#prefect.concurrency.services","title":"<code>prefect.concurrency.services</code>","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/sync/","title":"sync","text":"","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync","title":"<code>prefect.concurrency.sync</code>","text":"","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync.concurrency","title":"<code>concurrency</code>","text":"<p>A context manager that acquires and releases concurrency slots from the given concurrency limits.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> <code>timeout_seconds</code> <code>Optional[float]</code> <p>The number of seconds to wait for the slots to be acquired before raising a <code>TimeoutError</code>. A timeout of <code>None</code> will wait indefinitely.</p> <code>None</code> <p>Raises:</p> Type Description <code>TimeoutError</code> <p>If the slots are not acquired within the given timeout.</p> <p>A simple example of using the sync <code>concurrency</code> context manager: <pre><code>from prefect.concurrency.sync import concurrency\n\ndef resource_heavy():\n    with concurrency(\"test\", occupy=1):\n        print(\"Resource heavy task\")\n\ndef main():\n    resource_heavy()\n</code></pre></p> Source code in <code>prefect/concurrency/sync.py</code> <pre><code>@contextmanager\ndef concurrency(\n    names: Union[str, List[str]],\n    occupy: int = 1,\n    timeout_seconds: Optional[float] = None,\n):\n    \"\"\"A context manager that acquires and releases concurrency slots from the\n    given concurrency limits.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n        timeout_seconds: The number of seconds to wait for the slots to be acquired before\n            raising a `TimeoutError`. A timeout of `None` will wait indefinitely.\n\n    Raises:\n        TimeoutError: If the slots are not acquired within the given timeout.\n\n    Example:\n    A simple example of using the sync `concurrency` context manager:\n    ```python\n    from prefect.concurrency.sync import concurrency\n\n    def resource_heavy():\n        with concurrency(\"test\", occupy=1):\n            print(\"Resource heavy task\")\n\n    def main():\n        resource_heavy()\n    ```\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n\n    limits: List[MinimalConcurrencyLimitResponse] = _call_async_function_from_sync(\n        _acquire_concurrency_slots, names, occupy, timeout_seconds=timeout_seconds\n    )\n    acquisition_time = pendulum.now(\"UTC\")\n    emitted_events = _emit_concurrency_acquisition_events(limits, occupy)\n\n    try:\n        yield\n    finally:\n        occupancy_period = cast(Interval, pendulum.now(\"UTC\") - acquisition_time)\n        _call_async_function_from_sync(\n            _release_concurrency_slots,\n            names,\n            occupy,\n            occupancy_period.total_seconds(),\n        )\n        _emit_concurrency_release_events(limits, occupy, emitted_events)\n</code></pre>","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync.rate_limit","title":"<code>rate_limit</code>","text":"<p>Block execution until an <code>occupy</code> number of slots of the concurrency limits given in <code>names</code> are acquired. Requires that all given concurrency limits have a slot decay.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> Source code in <code>prefect/concurrency/sync.py</code> <pre><code>def rate_limit(names: Union[str, List[str]], occupy: int = 1):\n    \"\"\"Block execution until an `occupy` number of slots of the concurrency\n    limits given in `names` are acquired. Requires that all given concurrency\n    limits have a slot decay.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = _call_async_function_from_sync(\n        _acquire_concurrency_slots, names, occupy, mode=\"rate_limit\"\n    )\n    _emit_concurrency_acquisition_events(limits, occupy)\n</code></pre>","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/deployments/base/","title":"base","text":"","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base","title":"<code>prefect.deployments.base</code>","text":"<p>Core primitives for managing Prefect deployments via <code>prefect deploy</code>, providing a minimally opinionated build system for managing flows and deployments.</p> <p>To get started, follow along with the deloyments tutorial.</p>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.configure_project_by_recipe","title":"<code>configure_project_by_recipe</code>","text":"<p>Given a recipe name, returns a dictionary representing base configuration options.</p> <p>Parameters:</p> Name Type Description Default <code>recipe</code> <code>str</code> <p>the name of the recipe to use</p> required <code>formatting_kwargs</code> <code>dict</code> <p>additional keyword arguments to format the recipe</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if provided recipe name does not exist.</p> Source code in <code>prefect/deployments/base.py</code> <pre><code>def configure_project_by_recipe(recipe: str, **formatting_kwargs) -&gt; dict:\n    \"\"\"\n    Given a recipe name, returns a dictionary representing base configuration options.\n\n    Args:\n        recipe (str): the name of the recipe to use\n        formatting_kwargs (dict, optional): additional keyword arguments to format the recipe\n\n    Raises:\n        ValueError: if provided recipe name does not exist.\n    \"\"\"\n    # load the recipe\n    recipe_path = Path(__file__).parent / \"recipes\" / recipe / \"prefect.yaml\"\n\n    if not recipe_path.exists():\n        raise ValueError(f\"Unknown recipe {recipe!r} provided.\")\n\n    with recipe_path.open(mode=\"r\") as f:\n        config = yaml.safe_load(f)\n\n    config = apply_values(\n        template=config, values=formatting_kwargs, remove_notset=False\n    )\n\n    return config\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.create_default_prefect_yaml","title":"<code>create_default_prefect_yaml</code>","text":"<p>Creates default <code>prefect.yaml</code> file in the provided path if one does not already exist; returns boolean specifying whether a file was created.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the project; if not provided, the current directory name will be used</p> <code>None</code> <code>contents</code> <code>dict</code> <p>a dictionary of contents to write to the file; if not provided, defaults will be used</p> <code>None</code> Source code in <code>prefect/deployments/base.py</code> <pre><code>def create_default_prefect_yaml(\n    path: str, name: str = None, contents: Optional[Dict[str, Any]] = None\n) -&gt; bool:\n    \"\"\"\n    Creates default `prefect.yaml` file in the provided path if one does not already exist;\n    returns boolean specifying whether a file was created.\n\n    Args:\n        name (str, optional): the name of the project; if not provided, the current directory name\n            will be used\n        contents (dict, optional): a dictionary of contents to write to the file; if not provided,\n            defaults will be used\n    \"\"\"\n    path = Path(path)\n    prefect_file = path / \"prefect.yaml\"\n    if prefect_file.exists():\n        return False\n    default_file = Path(__file__).parent / \"templates\" / \"prefect.yaml\"\n\n    with default_file.open(mode=\"r\") as df:\n        default_contents = yaml.safe_load(df)\n\n    import prefect\n\n    contents[\"prefect-version\"] = prefect.__version__\n    contents[\"name\"] = name\n\n    with prefect_file.open(mode=\"w\") as f:\n        # write header\n        f.write(\n            \"# Welcome to your prefect.yaml file! You can use this file for storing and\"\n            \" managing\\n# configuration for deploying your flows. We recommend\"\n            \" committing this file to source\\n# control along with your flow code.\\n\\n\"\n        )\n\n        f.write(\"# Generic metadata about this project\\n\")\n        yaml.dump({\"name\": contents[\"name\"]}, f, sort_keys=False)\n        yaml.dump({\"prefect-version\": contents[\"prefect-version\"]}, f, sort_keys=False)\n        f.write(\"\\n\")\n\n        # build\n        f.write(\"# build section allows you to manage and build docker images\\n\")\n        yaml.dump(\n            {\"build\": contents.get(\"build\", default_contents.get(\"build\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # push\n        f.write(\n            \"# push section allows you to manage if and how this project is uploaded to\"\n            \" remote locations\\n\"\n        )\n        yaml.dump(\n            {\"push\": contents.get(\"push\", default_contents.get(\"push\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # pull\n        f.write(\n            \"# pull section allows you to provide instructions for cloning this project\"\n            \" in remote locations\\n\"\n        )\n        yaml.dump(\n            {\"pull\": contents.get(\"pull\", default_contents.get(\"pull\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # deployments\n        f.write(\n            \"# the deployments section allows you to provide configuration for\"\n            \" deploying flows\\n\"\n        )\n        yaml.dump(\n            {\n                \"deployments\": contents.get(\n                    \"deployments\", default_contents.get(\"deployments\")\n                )\n            },\n            f,\n            sort_keys=False,\n        )\n    return True\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.initialize_project","title":"<code>initialize_project</code>","text":"<p>Initializes a basic project structure with base files.  If no name is provided, the name of the current directory is used.  If no recipe is provided, one is inferred.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the project; if not provided, the current directory name</p> <code>None</code> <code>recipe</code> <code>str</code> <p>the name of the recipe to use; if not provided, one is inferred</p> <code>None</code> <code>inputs</code> <code>dict</code> <p>a dictionary of inputs to use when formatting the recipe</p> <code>None</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>List[str]: a list of files / directories that were created</p> Source code in <code>prefect/deployments/base.py</code> <pre><code>def initialize_project(\n    name: str = None, recipe: str = None, inputs: Optional[Dict[str, Any]] = None\n) -&gt; List[str]:\n    \"\"\"\n    Initializes a basic project structure with base files.  If no name is provided, the name\n    of the current directory is used.  If no recipe is provided, one is inferred.\n\n    Args:\n        name (str, optional): the name of the project; if not provided, the current directory name\n        recipe (str, optional): the name of the recipe to use; if not provided, one is inferred\n        inputs (dict, optional): a dictionary of inputs to use when formatting the recipe\n\n    Returns:\n        List[str]: a list of files / directories that were created\n    \"\"\"\n    # determine if in git repo or use directory name as a default\n    is_git_based = False\n    formatting_kwargs = {\"directory\": str(Path(\".\").absolute().resolve())}\n    dir_name = os.path.basename(os.getcwd())\n\n    remote_url = _get_git_remote_origin_url()\n    if remote_url:\n        formatting_kwargs[\"repository\"] = remote_url\n        is_git_based = True\n        branch = _get_git_branch()\n        formatting_kwargs[\"branch\"] = branch or \"main\"\n\n    formatting_kwargs[\"name\"] = dir_name\n\n    has_dockerfile = Path(\"Dockerfile\").exists()\n\n    if has_dockerfile:\n        formatting_kwargs[\"dockerfile\"] = \"Dockerfile\"\n    elif recipe is not None and \"docker\" in recipe:\n        formatting_kwargs[\"dockerfile\"] = \"auto\"\n\n    # hand craft a pull step\n    if is_git_based and recipe is None:\n        if has_dockerfile:\n            recipe = \"docker-git\"\n        else:\n            recipe = \"git\"\n    elif recipe is None and has_dockerfile:\n        recipe = \"docker\"\n    elif recipe is None:\n        recipe = \"local\"\n\n    formatting_kwargs.update(inputs or {})\n    configuration = configure_project_by_recipe(recipe=recipe, **formatting_kwargs)\n\n    project_name = name or dir_name\n\n    files = []\n    if create_default_ignore_file(\".\"):\n        files.append(\".prefectignore\")\n    if create_default_prefect_yaml(\".\", name=project_name, contents=configuration):\n        files.append(\"prefect.yaml\")\n\n    return files\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/deployments/","title":"deployments","text":"","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments","title":"<code>prefect.deployments.deployments</code>","text":"<p>Objects for specifying deployments and utilities for loading flows from deployments.</p>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>BaseModel</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>flow.deploy</code>, which offers enhanced functionality and better a better user experience. For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>A Prefect Deployment definition, used for specifying and building deployments.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <p>A name for the deployment (required).</p> required <code>version</code> <p>An optional version for the deployment; defaults to the flow's version</p> required <code>description</code> <p>An optional description of the deployment; defaults to the flow's description</p> required <code>tags</code> <p>An optional list of tags to associate with this deployment; note that tags are used only for organizational purposes. For delegating work to agents, see <code>work_queue_name</code>.</p> required <code>schedule</code> <p>A schedule to run this deployment on, once registered (deprecated)</p> required <code>is_schedule_active</code> <p>Whether or not the schedule is active (deprecated)</p> required <code>schedules</code> <p>A list of schedules to run this deployment on</p> required <code>work_queue_name</code> <p>The work queue that will handle this deployment's runs</p> required <code>work_pool_name</code> <p>The work pool for the deployment</p> required <code>flow_name</code> <p>The name of the flow this deployment encapsulates</p> required <code>parameters</code> <p>A dictionary of parameter values to pass to runs created from this deployment</p> required <code>infrastructure</code> <p>An optional infrastructure block used to configure infrastructure for runs; if not provided, will default to running this deployment in Agent subprocesses</p> required <code>job_variables</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code></p> required <code>storage</code> <p>An optional remote storage block used to store and retrieve this workflow; if not provided, will default to referencing this flow by its local path</p> required <code>path</code> <p>The path to the working directory for the workflow, relative to remote storage or, if stored on a local filesystem, an absolute path</p> required <code>entrypoint</code> <p>The path to the entrypoint for the workflow, always relative to the <code>path</code></p> required <code>parameter_openapi_schema</code> <p>The parameter schema of the flow, including defaults.</p> required <code>enforce_parameter_schema</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> required <pre><code>Create a new deployment using configuration defaults for an imported flow:\n\n&gt;&gt;&gt; from my_project.flows import my_flow\n&gt;&gt;&gt; from prefect.deployments import Deployment\n&gt;&gt;&gt;\n&gt;&gt;&gt; deployment = Deployment.build_from_flow(\n...     flow=my_flow,\n...     name=\"example\",\n...     version=\"1\",\n...     tags=[\"demo\"],\n&gt;&gt;&gt; )\n&gt;&gt;&gt; deployment.apply()\n\nCreate a new deployment with custom storage and an infrastructure override:\n\n&gt;&gt;&gt; from my_project.flows import my_flow\n&gt;&gt;&gt; from prefect.deployments import Deployment\n&gt;&gt;&gt; from prefect.filesystems import S3\n\n&gt;&gt;&gt; storage = S3.load(\"dev-bucket\") # load a pre-defined block\n&gt;&gt;&gt; deployment = Deployment.build_from_flow(\n...     flow=my_flow,\n...     name=\"s3-example\",\n...     version=\"2\",\n...     tags=[\"aws\"],\n...     storage=storage,\n...     job_variables=dict(\"env.PREFECT_LOGGING_LEVEL\"=\"DEBUG\"),\n&gt;&gt;&gt; )\n&gt;&gt;&gt; deployment.apply()\n</code></pre> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use `flow.deploy` to deploy your flows instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Deployment(DeprecatedInfraOverridesField, BaseModel):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `flow.deploy`, which offers enhanced functionality and better a better user experience.\n    For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\n\n    A Prefect Deployment definition, used for specifying and building deployments.\n\n    Args:\n        name: A name for the deployment (required).\n        version: An optional version for the deployment; defaults to the flow's version\n        description: An optional description of the deployment; defaults to the flow's\n            description\n        tags: An optional list of tags to associate with this deployment; note that tags\n            are used only for organizational purposes. For delegating work to agents,\n            see `work_queue_name`.\n        schedule: A schedule to run this deployment on, once registered (deprecated)\n        is_schedule_active: Whether or not the schedule is active (deprecated)\n        schedules: A list of schedules to run this deployment on\n        work_queue_name: The work queue that will handle this deployment's runs\n        work_pool_name: The work pool for the deployment\n        flow_name: The name of the flow this deployment encapsulates\n        parameters: A dictionary of parameter values to pass to runs created from this\n            deployment\n        infrastructure: An optional infrastructure block used to configure\n            infrastructure for runs; if not provided, will default to running this\n            deployment in Agent subprocesses\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`\n        storage: An optional remote storage block used to store and retrieve this\n            workflow; if not provided, will default to referencing this flow by its\n            local path\n        path: The path to the working directory for the workflow, relative to remote\n            storage or, if stored on a local filesystem, an absolute path\n        entrypoint: The path to the entrypoint for the workflow, always relative to the\n            `path`\n        parameter_openapi_schema: The parameter schema of the flow, including defaults.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n\n    Examples:\n\n        Create a new deployment using configuration defaults for an imported flow:\n\n        &gt;&gt;&gt; from my_project.flows import my_flow\n        &gt;&gt;&gt; from prefect.deployments import Deployment\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; deployment = Deployment.build_from_flow(\n        ...     flow=my_flow,\n        ...     name=\"example\",\n        ...     version=\"1\",\n        ...     tags=[\"demo\"],\n        &gt;&gt;&gt; )\n        &gt;&gt;&gt; deployment.apply()\n\n        Create a new deployment with custom storage and an infrastructure override:\n\n        &gt;&gt;&gt; from my_project.flows import my_flow\n        &gt;&gt;&gt; from prefect.deployments import Deployment\n        &gt;&gt;&gt; from prefect.filesystems import S3\n\n        &gt;&gt;&gt; storage = S3.load(\"dev-bucket\") # load a pre-defined block\n        &gt;&gt;&gt; deployment = Deployment.build_from_flow(\n        ...     flow=my_flow,\n        ...     name=\"s3-example\",\n        ...     version=\"2\",\n        ...     tags=[\"aws\"],\n        ...     storage=storage,\n        ...     job_variables=dict(\"env.PREFECT_LOGGING_LEVEL\"=\"DEBUG\"),\n        &gt;&gt;&gt; )\n        &gt;&gt;&gt; deployment.apply()\n\n    \"\"\"\n\n    class Config:\n        json_encoders = {SecretDict: lambda v: v.dict()}\n        validate_assignment = True\n        extra = \"forbid\"\n\n    @property\n    def _editable_fields(self) -&gt; List[str]:\n        editable_fields = [\n            \"name\",\n            \"description\",\n            \"version\",\n            \"work_queue_name\",\n            \"work_pool_name\",\n            \"tags\",\n            \"parameters\",\n            \"schedule\",\n            \"schedules\",\n            \"is_schedule_active\",\n            # The `infra_overrides` field has been renamed to `job_variables`.\n            # We will continue writing it in the YAML file as `infra_overrides`\n            # instead of `job_variables` for better backwards compat, but we'll\n            # accept either `job_variables` or `infra_overrides` when we read\n            # the file.\n            \"infra_overrides\",\n        ]\n\n        # if infrastructure is baked as a pre-saved block, then\n        # editing its fields will not update anything\n        if self.infrastructure._block_document_id:\n            return editable_fields\n        else:\n            return editable_fields + [\"infrastructure\"]\n\n    @property\n    def location(self) -&gt; str:\n        \"\"\"\n        The 'location' that this deployment points to is given by `path` alone\n        in the case of no remote storage, and otherwise by `storage.basepath / path`.\n\n        The underlying flow entrypoint is interpreted relative to this location.\n        \"\"\"\n        location = \"\"\n        if self.storage:\n            location = (\n                self.storage.basepath + \"/\"\n                if not self.storage.basepath.endswith(\"/\")\n                else \"\"\n            )\n        if self.path:\n            location += self.path\n        return location\n\n    @sync_compatible\n    async def to_yaml(self, path: Path) -&gt; None:\n        yaml_dict = self._yaml_dict()\n        schema = self.schema()\n\n        with open(path, \"w\") as f:\n            # write header\n            f.write(\n                \"###\\n### A complete description of a Prefect Deployment for flow\"\n                f\" {self.flow_name!r}\\n###\\n\"\n            )\n\n            # write editable fields\n            for field in self._editable_fields:\n                # write any comments\n                if schema[\"properties\"][field].get(\"yaml_comment\"):\n                    f.write(f\"# {schema['properties'][field]['yaml_comment']}\\n\")\n                # write the field\n                yaml.dump({field: yaml_dict[field]}, f, sort_keys=False)\n\n            # write non-editable fields, excluding `job_variables` because we'll\n            # continue writing it as `infra_overrides` for better backwards compat\n            # with the existing file format.\n            f.write(\"\\n###\\n### DO NOT EDIT BELOW THIS LINE\\n###\\n\")\n            yaml.dump(\n                {\n                    k: v\n                    for k, v in yaml_dict.items()\n                    if k not in self._editable_fields and k != \"job_variables\"\n                },\n                f,\n                sort_keys=False,\n            )\n\n    def _yaml_dict(self) -&gt; dict:\n        \"\"\"\n        Returns a YAML-compatible representation of this deployment as a dictionary.\n        \"\"\"\n        # avoids issues with UUIDs showing up in YAML\n        all_fields = json.loads(\n            self.json(\n                exclude={\n                    \"storage\": {\"_filesystem\", \"filesystem\", \"_remote_file_system\"}\n                }\n            )\n        )\n        if all_fields[\"storage\"]:\n            all_fields[\"storage\"][\n                \"_block_type_slug\"\n            ] = self.storage.get_block_type_slug()\n        if all_fields[\"infrastructure\"]:\n            all_fields[\"infrastructure\"][\n                \"_block_type_slug\"\n            ] = self.infrastructure.get_block_type_slug()\n        return all_fields\n\n    @classmethod\n    def _validate_schedule(cls, value):\n        \"\"\"We do not support COUNT-based (# of occurrences) RRule schedules for deployments.\"\"\"\n        if value:\n            rrule_value = getattr(value, \"rrule\", None)\n            if rrule_value and \"COUNT\" in rrule_value.upper():\n                raise ValueError(\n                    \"RRule schedules with `COUNT` are not supported. Please use `UNTIL`\"\n                    \" or the `/deployments/{id}/schedule` endpoint to schedule a fixed\"\n                    \" number of flow runs.\"\n                )\n\n    # top level metadata\n    name: str = Field(..., description=\"The name of the deployment.\")\n    description: Optional[str] = Field(\n        default=None, description=\"An optional description of the deployment.\"\n    )\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"One of more tags to apply to this deployment.\",\n    )\n    schedule: Optional[SCHEDULE_TYPES] = Field(default=None)\n    schedules: List[MinimalDeploymentSchedule] = Field(\n        default_factory=list,\n        description=\"The schedules to run this deployment on.\",\n    )\n    is_schedule_active: Optional[bool] = Field(\n        default=None, description=\"Whether or not the schedule is active.\"\n    )\n    flow_name: Optional[str] = Field(default=None, description=\"The name of the flow.\")\n    work_queue_name: Optional[str] = Field(\n        \"default\",\n        description=\"The work queue for the deployment.\",\n        yaml_comment=\"The work queue that will handle this deployment's runs\",\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None, description=\"The work pool for the deployment\"\n    )\n    # flow data\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    infrastructure: Infrastructure = Field(default_factory=Process)\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to the base infrastructure block at runtime.\",\n    )\n    storage: Optional[Block] = Field(\n        None,\n        help=\"The remote storage to use for this workflow.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    parameter_openapi_schema: ParameterSchema = Field(\n        default_factory=ParameterSchema,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    timestamp: datetime = Field(default_factory=partial(pendulum.now, \"UTC\"))\n    triggers: List[Union[DeploymentTriggerTypes, TriggerTypes]] = Field(\n        default_factory=list,\n        description=\"The triggers that should cause this deployment to run.\",\n    )\n    # defaults to None to allow for backwards compatibility\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the Prefect API should enforce the parameter schema for\"\n            \" this deployment.\"\n        ),\n    )\n\n    @validator(\"infrastructure\", pre=True)\n    def validate_infrastructure_capabilities(cls, value):\n        return infrastructure_must_have_capabilities(value)\n\n    @validator(\"storage\", pre=True)\n    def validate_storage(cls, value):\n        return storage_must_have_capabilities(value)\n\n    @validator(\"parameter_openapi_schema\", pre=True)\n    def validate_parameter_openapi_schema(cls, value):\n        return handle_openapi_schema(value)\n\n    @validator(\"triggers\")\n    def validate_triggers(cls, field_value, values):\n        return validate_automation_names(field_value, values)\n\n    @root_validator(pre=True)\n    def validate_schedule(cls, values):\n        return validate_deprecated_schedule_fields(values, logger)\n\n    @root_validator(pre=True)\n    def validate_backwards_compatibility_for_schedule(cls, values):\n        return reconcile_schedules(cls, values)\n\n    @classmethod\n    @sync_compatible\n    async def load_from_yaml(cls, path: str):\n        data = yaml.safe_load(await anyio.Path(path).read_bytes())\n        # load blocks from server to ensure secret values are properly hydrated\n        if data.get(\"storage\"):\n            block_doc_name = data[\"storage\"].get(\"_block_document_name\")\n            # if no doc name, this block is not stored on the server\n            if block_doc_name:\n                block_slug = data[\"storage\"][\"_block_type_slug\"]\n                block = await Block.load(f\"{block_slug}/{block_doc_name}\")\n                data[\"storage\"] = block\n\n        if data.get(\"infrastructure\"):\n            block_doc_name = data[\"infrastructure\"].get(\"_block_document_name\")\n            # if no doc name, this block is not stored on the server\n            if block_doc_name:\n                block_slug = data[\"infrastructure\"][\"_block_type_slug\"]\n                block = await Block.load(f\"{block_slug}/{block_doc_name}\")\n                data[\"infrastructure\"] = block\n\n            return cls(**data)\n\n    @sync_compatible\n    async def load(self) -&gt; bool:\n        \"\"\"\n        Queries the API for a deployment with this name for this flow, and if found,\n        prepopulates any settings that were not set at initialization.\n\n        Returns a boolean specifying whether a load was successful or not.\n\n        Raises:\n            - ValueError: if both name and flow name are not set\n        \"\"\"\n        if not self.name or not self.flow_name:\n            raise ValueError(\"Both a deployment name and flow name must be provided.\")\n        async with get_client() as client:\n            try:\n                deployment = await client.read_deployment_by_name(\n                    f\"{self.flow_name}/{self.name}\"\n                )\n                if deployment.storage_document_id:\n                    Block._from_block_document(\n                        await client.read_block_document(deployment.storage_document_id)\n                    )\n\n                excluded_fields = self.__fields_set__.union(\n                    {\n                        \"infrastructure\",\n                        \"storage\",\n                        \"timestamp\",\n                        \"triggers\",\n                        \"enforce_parameter_schema\",\n                        \"schedules\",\n                        \"schedule\",\n                        \"is_schedule_active\",\n                    }\n                )\n                for field in set(self.__fields__.keys()) - excluded_fields:\n                    new_value = getattr(deployment, field)\n                    setattr(self, field, new_value)\n\n                if \"schedules\" not in self.__fields_set__:\n                    self.schedules = [\n                        MinimalDeploymentSchedule(\n                            **schedule.dict(include={\"schedule\", \"active\"})\n                        )\n                        for schedule in deployment.schedules\n                    ]\n\n                # The API server generates the \"schedule\" field from the\n                # current list of schedules, so if the user has locally set\n                # \"schedules\" to anything, we should avoid sending \"schedule\"\n                # and let the API server generate a new value if necessary.\n                if \"schedules\" in self.__fields_set__:\n                    self.schedule = None\n                    self.is_schedule_active = None\n                else:\n                    # The user isn't using \"schedules,\" so we should\n                    # populate \"schedule\" and \"is_schedule_active\" from the\n                    # API's version of the deployment, unless the user gave\n                    # us these fields in __init__().\n                    if \"schedule\" not in self.__fields_set__:\n                        self.schedule = deployment.schedule\n                    if \"is_schedule_active\" not in self.__fields_set__:\n                        self.is_schedule_active = deployment.is_schedule_active\n\n                if \"infrastructure\" not in self.__fields_set__:\n                    if deployment.infrastructure_document_id:\n                        self.infrastructure = Block._from_block_document(\n                            await client.read_block_document(\n                                deployment.infrastructure_document_id\n                            )\n                        )\n                if \"storage\" not in self.__fields_set__:\n                    if deployment.storage_document_id:\n                        self.storage = Block._from_block_document(\n                            await client.read_block_document(\n                                deployment.storage_document_id\n                            )\n                        )\n            except ObjectNotFound:\n                return False\n        return True\n\n    @sync_compatible\n    async def update(self, ignore_none: bool = False, **kwargs):\n        \"\"\"\n        Performs an in-place update with the provided settings.\n\n        Args:\n            ignore_none: if True, all `None` values are ignored when performing the\n                update\n        \"\"\"\n        unknown_keys = set(kwargs.keys()) - set(self.dict().keys())\n        if unknown_keys:\n            raise ValueError(\n                f\"Received unexpected attributes: {', '.join(unknown_keys)}\"\n            )\n        for key, value in kwargs.items():\n            if ignore_none and value is None:\n                continue\n            setattr(self, key, value)\n\n    @sync_compatible\n    async def upload_to_storage(\n        self, storage_block: str = None, ignore_file: str = \".prefectignore\"\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Uploads the workflow this deployment represents using a provided storage block;\n        if no block is provided, defaults to configuring self for local storage.\n\n        Args:\n            storage_block: a string reference a remote storage block slug `$type/$name`;\n                if provided, used to upload the workflow's project\n            ignore_file: an optional path to a `.prefectignore` file that specifies\n                filename patterns to ignore when uploading to remote storage; if not\n                provided, looks for `.prefectignore` in the current working directory\n        \"\"\"\n        file_count = None\n        if storage_block:\n            storage = await Block.load(storage_block)\n\n            if \"put-directory\" not in storage.get_block_capabilities():\n                raise BlockMissingCapabilities(\n                    f\"Storage block {storage!r} missing 'put-directory' capability.\"\n                )\n\n            self.storage = storage\n\n            # upload current directory to storage location\n            file_count = await self.storage.put_directory(\n                ignore_file=ignore_file, to_path=self.path\n            )\n        elif self.storage:\n            if \"put-directory\" not in self.storage.get_block_capabilities():\n                raise BlockMissingCapabilities(\n                    f\"Storage block {self.storage!r} missing 'put-directory'\"\n                    \" capability.\"\n                )\n\n            file_count = await self.storage.put_directory(\n                ignore_file=ignore_file, to_path=self.path\n            )\n\n        # persists storage now in case it contains secret values\n        if self.storage and not self.storage._block_document_id:\n            await self.storage._save(is_anonymous=True)\n\n        return file_count\n\n    @sync_compatible\n    async def apply(\n        self, upload: bool = False, work_queue_concurrency: int = None\n    ) -&gt; UUID:\n        \"\"\"\n        Registers this deployment with the API and returns the deployment's ID.\n\n        Args:\n            upload: if True, deployment files are automatically uploaded to remote\n                storage\n            work_queue_concurrency: If provided, sets the concurrency limit on the\n                deployment's work queue\n        \"\"\"\n        if not self.name or not self.flow_name:\n            raise ValueError(\"Both a deployment name and flow name must be set.\")\n        async with get_client() as client:\n            # prep IDs\n            flow_id = await client.create_flow_from_name(self.flow_name)\n\n            infrastructure_document_id = self.infrastructure._block_document_id\n            if not infrastructure_document_id:\n                # if not building off a block, will create an anonymous block\n                self.infrastructure = self.infrastructure.copy()\n                infrastructure_document_id = await self.infrastructure._save(\n                    is_anonymous=True,\n                )\n\n            if upload:\n                await self.upload_to_storage()\n\n            if self.work_queue_name and work_queue_concurrency is not None:\n                try:\n                    res = await client.create_work_queue(\n                        name=self.work_queue_name, work_pool_name=self.work_pool_name\n                    )\n                except ObjectAlreadyExists:\n                    res = await client.read_work_queue_by_name(\n                        name=self.work_queue_name, work_pool_name=self.work_pool_name\n                    )\n                await client.update_work_queue(\n                    res.id, concurrency_limit=work_queue_concurrency\n                )\n\n            if self.schedule:\n                logger.info(\n                    \"Interpreting the deprecated `schedule` field as an entry in \"\n                    \"`schedules`.\"\n                )\n                schedules = [\n                    DeploymentScheduleCreate(\n                        schedule=self.schedule, active=self.is_schedule_active\n                    )\n                ]\n            elif self.schedules:\n                schedules = [\n                    DeploymentScheduleCreate(**schedule.dict())\n                    for schedule in self.schedules\n                ]\n            else:\n                schedules = None\n\n            # we assume storage was already saved\n            storage_document_id = getattr(self.storage, \"_block_document_id\", None)\n            deployment_id = await client.create_deployment(\n                flow_id=flow_id,\n                name=self.name,\n                work_queue_name=self.work_queue_name,\n                work_pool_name=self.work_pool_name,\n                version=self.version,\n                schedules=schedules,\n                is_schedule_active=self.is_schedule_active,\n                parameters=self.parameters,\n                description=self.description,\n                tags=self.tags,\n                manifest_path=self.manifest_path,  # allows for backwards YAML compat\n                path=self.path,\n                entrypoint=self.entrypoint,\n                job_variables=self.job_variables,\n                storage_document_id=storage_document_id,\n                infrastructure_document_id=infrastructure_document_id,\n                parameter_openapi_schema=self.parameter_openapi_schema.dict(),\n                enforce_parameter_schema=self.enforce_parameter_schema,\n            )\n\n            if client.server_type.supports_automations():\n                try:\n                    # The triggers defined in the deployment spec are, essentially,\n                    # anonymous and attempting truly sync them with cloud is not\n                    # feasible. Instead, we remove all automations that are owned\n                    # by the deployment, meaning that they were created via this\n                    # mechanism below, and then recreate them.\n                    await client.delete_resource_owned_automations(\n                        f\"prefect.deployment.{deployment_id}\"\n                    )\n                except PrefectHTTPStatusError as e:\n                    if e.response.status_code == 404:\n                        # This Prefect server does not support automations, so we can safely\n                        # ignore this 404 and move on.\n                        return deployment_id\n                    raise e\n\n                for trigger in self.triggers:\n                    trigger.set_deployment_id(deployment_id)\n                    await client.create_automation(trigger.as_automation())\n\n            return deployment_id\n\n    @classmethod\n    @sync_compatible\n    async def build_from_flow(\n        cls,\n        flow: Flow,\n        name: str,\n        output: str = None,\n        skip_upload: bool = False,\n        ignore_file: str = \".prefectignore\",\n        apply: bool = False,\n        load_existing: bool = True,\n        schedules: Optional[FlexibleScheduleList] = None,\n        **kwargs,\n    ) -&gt; \"Deployment\":\n        \"\"\"\n        Configure a deployment for a given flow.\n\n        Args:\n            flow: A flow function to deploy\n            name: A name for the deployment\n            output (optional): if provided, the full deployment specification will be\n                written as a YAML file in the location specified by `output`\n            skip_upload: if True, deployment files are not automatically uploaded to\n                remote storage\n            ignore_file: an optional path to a `.prefectignore` file that specifies\n                filename patterns to ignore when uploading to remote storage; if not\n                provided, looks for `.prefectignore` in the current working directory\n            apply: if True, the deployment is automatically registered with the API\n            load_existing: if True, load any settings that may already be configured for\n                the named deployment server-side (e.g., schedules, default parameter\n                values, etc.)\n            schedules: An optional list of schedules. Each item in the list can be:\n                  - An instance of `MinimalDeploymentSchedule`.\n                  - A dictionary with a `schedule` key, and optionally, an\n                    `active` key. The `schedule` key should correspond to a\n                    schedule type, and `active` is a boolean indicating whether\n                    the schedule is active or not.\n                  - An instance of one of the predefined schedule types:\n                    `IntervalSchedule`, `CronSchedule`, or `RRuleSchedule`.\n            **kwargs: other keyword arguments to pass to the constructor for the\n                `Deployment` class\n        \"\"\"\n        if not name:\n            raise ValueError(\"A deployment name must be provided.\")\n\n        # note that `deployment.load` only updates settings that were *not*\n        # provided at initialization\n\n        deployment_args = {\n            \"name\": name,\n            \"flow_name\": flow.name,\n            **kwargs,\n        }\n\n        if schedules is not None:\n            deployment_args[\"schedules\"] = schedules\n\n        deployment = cls(**deployment_args)\n        deployment.flow_name = flow.name\n        if not deployment.entrypoint:\n            ## first see if an entrypoint can be determined\n            flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n            mod_name = getattr(flow, \"__module__\", None)\n            if not flow_file:\n                if not mod_name:\n                    # todo, check if the file location was manually set already\n                    raise ValueError(\"Could not determine flow's file location.\")\n                module = importlib.import_module(mod_name)\n                flow_file = getattr(module, \"__file__\", None)\n                if not flow_file:\n                    raise ValueError(\"Could not determine flow's file location.\")\n\n            # set entrypoint\n            entry_path = Path(flow_file).absolute().relative_to(Path(\".\").absolute())\n            deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n        if load_existing:\n            await deployment.load()\n\n        # set a few attributes for this flow object\n        deployment.parameter_openapi_schema = parameter_schema(flow)\n\n        # ensure the ignore file exists\n        if not Path(ignore_file).exists():\n            Path(ignore_file).touch()\n\n        if not deployment.version:\n            deployment.version = flow.version\n        if not deployment.description:\n            deployment.description = flow.description\n\n        # proxy for whether infra is docker-based\n        is_docker_based = hasattr(deployment.infrastructure, \"image\")\n\n        if not deployment.storage and not is_docker_based and not deployment.path:\n            deployment.path = str(Path(\".\").absolute())\n        elif not deployment.storage and is_docker_based:\n            # only update if a path is not already set\n            if not deployment.path:\n                deployment.path = \"/opt/prefect/flows\"\n\n        if not skip_upload:\n            if (\n                deployment.storage\n                and \"put-directory\" in deployment.storage.get_block_capabilities()\n            ):\n                await deployment.upload_to_storage(ignore_file=ignore_file)\n\n        if output:\n            await deployment.to_yaml(output)\n\n        if apply:\n            await deployment.apply()\n\n        return deployment\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.location","title":"<code>location: str</code>  <code>property</code>","text":"<p>The 'location' that this deployment points to is given by <code>path</code> alone in the case of no remote storage, and otherwise by <code>storage.basepath / path</code>.</p> <p>The underlying flow entrypoint is interpreted relative to this location.</p>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Registers this deployment with the API and returns the deployment's ID.</p> <p>Parameters:</p> Name Type Description Default <code>upload</code> <code>bool</code> <p>if True, deployment files are automatically uploaded to remote storage</p> <code>False</code> <code>work_queue_concurrency</code> <code>int</code> <p>If provided, sets the concurrency limit on the deployment's work queue</p> <code>None</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def apply(\n    self, upload: bool = False, work_queue_concurrency: int = None\n) -&gt; UUID:\n    \"\"\"\n    Registers this deployment with the API and returns the deployment's ID.\n\n    Args:\n        upload: if True, deployment files are automatically uploaded to remote\n            storage\n        work_queue_concurrency: If provided, sets the concurrency limit on the\n            deployment's work queue\n    \"\"\"\n    if not self.name or not self.flow_name:\n        raise ValueError(\"Both a deployment name and flow name must be set.\")\n    async with get_client() as client:\n        # prep IDs\n        flow_id = await client.create_flow_from_name(self.flow_name)\n\n        infrastructure_document_id = self.infrastructure._block_document_id\n        if not infrastructure_document_id:\n            # if not building off a block, will create an anonymous block\n            self.infrastructure = self.infrastructure.copy()\n            infrastructure_document_id = await self.infrastructure._save(\n                is_anonymous=True,\n            )\n\n        if upload:\n            await self.upload_to_storage()\n\n        if self.work_queue_name and work_queue_concurrency is not None:\n            try:\n                res = await client.create_work_queue(\n                    name=self.work_queue_name, work_pool_name=self.work_pool_name\n                )\n            except ObjectAlreadyExists:\n                res = await client.read_work_queue_by_name(\n                    name=self.work_queue_name, work_pool_name=self.work_pool_name\n                )\n            await client.update_work_queue(\n                res.id, concurrency_limit=work_queue_concurrency\n            )\n\n        if self.schedule:\n            logger.info(\n                \"Interpreting the deprecated `schedule` field as an entry in \"\n                \"`schedules`.\"\n            )\n            schedules = [\n                DeploymentScheduleCreate(\n                    schedule=self.schedule, active=self.is_schedule_active\n                )\n            ]\n        elif self.schedules:\n            schedules = [\n                DeploymentScheduleCreate(**schedule.dict())\n                for schedule in self.schedules\n            ]\n        else:\n            schedules = None\n\n        # we assume storage was already saved\n        storage_document_id = getattr(self.storage, \"_block_document_id\", None)\n        deployment_id = await client.create_deployment(\n            flow_id=flow_id,\n            name=self.name,\n            work_queue_name=self.work_queue_name,\n            work_pool_name=self.work_pool_name,\n            version=self.version,\n            schedules=schedules,\n            is_schedule_active=self.is_schedule_active,\n            parameters=self.parameters,\n            description=self.description,\n            tags=self.tags,\n            manifest_path=self.manifest_path,  # allows for backwards YAML compat\n            path=self.path,\n            entrypoint=self.entrypoint,\n            job_variables=self.job_variables,\n            storage_document_id=storage_document_id,\n            infrastructure_document_id=infrastructure_document_id,\n            parameter_openapi_schema=self.parameter_openapi_schema.dict(),\n            enforce_parameter_schema=self.enforce_parameter_schema,\n        )\n\n        if client.server_type.supports_automations():\n            try:\n                # The triggers defined in the deployment spec are, essentially,\n                # anonymous and attempting truly sync them with cloud is not\n                # feasible. Instead, we remove all automations that are owned\n                # by the deployment, meaning that they were created via this\n                # mechanism below, and then recreate them.\n                await client.delete_resource_owned_automations(\n                    f\"prefect.deployment.{deployment_id}\"\n                )\n            except PrefectHTTPStatusError as e:\n                if e.response.status_code == 404:\n                    # This Prefect server does not support automations, so we can safely\n                    # ignore this 404 and move on.\n                    return deployment_id\n                raise e\n\n            for trigger in self.triggers:\n                trigger.set_deployment_id(deployment_id)\n                await client.create_automation(trigger.as_automation())\n\n        return deployment_id\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.build_from_flow","title":"<code>build_from_flow</code>  <code>async</code> <code>classmethod</code>","text":"<p>Configure a deployment for a given flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow function to deploy</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>output</code> <code>optional</code> <p>if provided, the full deployment specification will be written as a YAML file in the location specified by <code>output</code></p> <code>None</code> <code>skip_upload</code> <code>bool</code> <p>if True, deployment files are not automatically uploaded to remote storage</p> <code>False</code> <code>ignore_file</code> <code>str</code> <p>an optional path to a <code>.prefectignore</code> file that specifies filename patterns to ignore when uploading to remote storage; if not provided, looks for <code>.prefectignore</code> in the current working directory</p> <code>'.prefectignore'</code> <code>apply</code> <code>bool</code> <p>if True, the deployment is automatically registered with the API</p> <code>False</code> <code>load_existing</code> <code>bool</code> <p>if True, load any settings that may already be configured for the named deployment server-side (e.g., schedules, default parameter values, etc.)</p> <code>True</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>An optional list of schedules. Each item in the list can be:   - An instance of <code>MinimalDeploymentSchedule</code>.   - A dictionary with a <code>schedule</code> key, and optionally, an     <code>active</code> key. The <code>schedule</code> key should correspond to a     schedule type, and <code>active</code> is a boolean indicating whether     the schedule is active or not.   - An instance of one of the predefined schedule types:     <code>IntervalSchedule</code>, <code>CronSchedule</code>, or <code>RRuleSchedule</code>.</p> <code>None</code> <code>**kwargs</code> <p>other keyword arguments to pass to the constructor for the <code>Deployment</code> class</p> <code>{}</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def build_from_flow(\n    cls,\n    flow: Flow,\n    name: str,\n    output: str = None,\n    skip_upload: bool = False,\n    ignore_file: str = \".prefectignore\",\n    apply: bool = False,\n    load_existing: bool = True,\n    schedules: Optional[FlexibleScheduleList] = None,\n    **kwargs,\n) -&gt; \"Deployment\":\n    \"\"\"\n    Configure a deployment for a given flow.\n\n    Args:\n        flow: A flow function to deploy\n        name: A name for the deployment\n        output (optional): if provided, the full deployment specification will be\n            written as a YAML file in the location specified by `output`\n        skip_upload: if True, deployment files are not automatically uploaded to\n            remote storage\n        ignore_file: an optional path to a `.prefectignore` file that specifies\n            filename patterns to ignore when uploading to remote storage; if not\n            provided, looks for `.prefectignore` in the current working directory\n        apply: if True, the deployment is automatically registered with the API\n        load_existing: if True, load any settings that may already be configured for\n            the named deployment server-side (e.g., schedules, default parameter\n            values, etc.)\n        schedules: An optional list of schedules. Each item in the list can be:\n              - An instance of `MinimalDeploymentSchedule`.\n              - A dictionary with a `schedule` key, and optionally, an\n                `active` key. The `schedule` key should correspond to a\n                schedule type, and `active` is a boolean indicating whether\n                the schedule is active or not.\n              - An instance of one of the predefined schedule types:\n                `IntervalSchedule`, `CronSchedule`, or `RRuleSchedule`.\n        **kwargs: other keyword arguments to pass to the constructor for the\n            `Deployment` class\n    \"\"\"\n    if not name:\n        raise ValueError(\"A deployment name must be provided.\")\n\n    # note that `deployment.load` only updates settings that were *not*\n    # provided at initialization\n\n    deployment_args = {\n        \"name\": name,\n        \"flow_name\": flow.name,\n        **kwargs,\n    }\n\n    if schedules is not None:\n        deployment_args[\"schedules\"] = schedules\n\n    deployment = cls(**deployment_args)\n    deployment.flow_name = flow.name\n    if not deployment.entrypoint:\n        ## first see if an entrypoint can be determined\n        flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n        mod_name = getattr(flow, \"__module__\", None)\n        if not flow_file:\n            if not mod_name:\n                # todo, check if the file location was manually set already\n                raise ValueError(\"Could not determine flow's file location.\")\n            module = importlib.import_module(mod_name)\n            flow_file = getattr(module, \"__file__\", None)\n            if not flow_file:\n                raise ValueError(\"Could not determine flow's file location.\")\n\n        # set entrypoint\n        entry_path = Path(flow_file).absolute().relative_to(Path(\".\").absolute())\n        deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n    if load_existing:\n        await deployment.load()\n\n    # set a few attributes for this flow object\n    deployment.parameter_openapi_schema = parameter_schema(flow)\n\n    # ensure the ignore file exists\n    if not Path(ignore_file).exists():\n        Path(ignore_file).touch()\n\n    if not deployment.version:\n        deployment.version = flow.version\n    if not deployment.description:\n        deployment.description = flow.description\n\n    # proxy for whether infra is docker-based\n    is_docker_based = hasattr(deployment.infrastructure, \"image\")\n\n    if not deployment.storage and not is_docker_based and not deployment.path:\n        deployment.path = str(Path(\".\").absolute())\n    elif not deployment.storage and is_docker_based:\n        # only update if a path is not already set\n        if not deployment.path:\n            deployment.path = \"/opt/prefect/flows\"\n\n    if not skip_upload:\n        if (\n            deployment.storage\n            and \"put-directory\" in deployment.storage.get_block_capabilities()\n        ):\n            await deployment.upload_to_storage(ignore_file=ignore_file)\n\n    if output:\n        await deployment.to_yaml(output)\n\n    if apply:\n        await deployment.apply()\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.load","title":"<code>load</code>  <code>async</code>","text":"<p>Queries the API for a deployment with this name for this flow, and if found, prepopulates any settings that were not set at initialization.</p> <p>Returns a boolean specifying whether a load was successful or not.</p> <p>Raises:</p> Type Description <code>-ValueError</code> <p>if both name and flow name are not set</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def load(self) -&gt; bool:\n    \"\"\"\n    Queries the API for a deployment with this name for this flow, and if found,\n    prepopulates any settings that were not set at initialization.\n\n    Returns a boolean specifying whether a load was successful or not.\n\n    Raises:\n        - ValueError: if both name and flow name are not set\n    \"\"\"\n    if not self.name or not self.flow_name:\n        raise ValueError(\"Both a deployment name and flow name must be provided.\")\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(\n                f\"{self.flow_name}/{self.name}\"\n            )\n            if deployment.storage_document_id:\n                Block._from_block_document(\n                    await client.read_block_document(deployment.storage_document_id)\n                )\n\n            excluded_fields = self.__fields_set__.union(\n                {\n                    \"infrastructure\",\n                    \"storage\",\n                    \"timestamp\",\n                    \"triggers\",\n                    \"enforce_parameter_schema\",\n                    \"schedules\",\n                    \"schedule\",\n                    \"is_schedule_active\",\n                }\n            )\n            for field in set(self.__fields__.keys()) - excluded_fields:\n                new_value = getattr(deployment, field)\n                setattr(self, field, new_value)\n\n            if \"schedules\" not in self.__fields_set__:\n                self.schedules = [\n                    MinimalDeploymentSchedule(\n                        **schedule.dict(include={\"schedule\", \"active\"})\n                    )\n                    for schedule in deployment.schedules\n                ]\n\n            # The API server generates the \"schedule\" field from the\n            # current list of schedules, so if the user has locally set\n            # \"schedules\" to anything, we should avoid sending \"schedule\"\n            # and let the API server generate a new value if necessary.\n            if \"schedules\" in self.__fields_set__:\n                self.schedule = None\n                self.is_schedule_active = None\n            else:\n                # The user isn't using \"schedules,\" so we should\n                # populate \"schedule\" and \"is_schedule_active\" from the\n                # API's version of the deployment, unless the user gave\n                # us these fields in __init__().\n                if \"schedule\" not in self.__fields_set__:\n                    self.schedule = deployment.schedule\n                if \"is_schedule_active\" not in self.__fields_set__:\n                    self.is_schedule_active = deployment.is_schedule_active\n\n            if \"infrastructure\" not in self.__fields_set__:\n                if deployment.infrastructure_document_id:\n                    self.infrastructure = Block._from_block_document(\n                        await client.read_block_document(\n                            deployment.infrastructure_document_id\n                        )\n                    )\n            if \"storage\" not in self.__fields_set__:\n                if deployment.storage_document_id:\n                    self.storage = Block._from_block_document(\n                        await client.read_block_document(\n                            deployment.storage_document_id\n                        )\n                    )\n        except ObjectNotFound:\n            return False\n    return True\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.update","title":"<code>update</code>  <code>async</code>","text":"<p>Performs an in-place update with the provided settings.</p> <p>Parameters:</p> Name Type Description Default <code>ignore_none</code> <code>bool</code> <p>if True, all <code>None</code> values are ignored when performing the update</p> <code>False</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def update(self, ignore_none: bool = False, **kwargs):\n    \"\"\"\n    Performs an in-place update with the provided settings.\n\n    Args:\n        ignore_none: if True, all `None` values are ignored when performing the\n            update\n    \"\"\"\n    unknown_keys = set(kwargs.keys()) - set(self.dict().keys())\n    if unknown_keys:\n        raise ValueError(\n            f\"Received unexpected attributes: {', '.join(unknown_keys)}\"\n        )\n    for key, value in kwargs.items():\n        if ignore_none and value is None:\n            continue\n        setattr(self, key, value)\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.upload_to_storage","title":"<code>upload_to_storage</code>  <code>async</code>","text":"<p>Uploads the workflow this deployment represents using a provided storage block; if no block is provided, defaults to configuring self for local storage.</p> <p>Parameters:</p> Name Type Description Default <code>storage_block</code> <code>str</code> <p>a string reference a remote storage block slug <code>$type/$name</code>; if provided, used to upload the workflow's project</p> <code>None</code> <code>ignore_file</code> <code>str</code> <p>an optional path to a <code>.prefectignore</code> file that specifies filename patterns to ignore when uploading to remote storage; if not provided, looks for <code>.prefectignore</code> in the current working directory</p> <code>'.prefectignore'</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def upload_to_storage(\n    self, storage_block: str = None, ignore_file: str = \".prefectignore\"\n) -&gt; Optional[int]:\n    \"\"\"\n    Uploads the workflow this deployment represents using a provided storage block;\n    if no block is provided, defaults to configuring self for local storage.\n\n    Args:\n        storage_block: a string reference a remote storage block slug `$type/$name`;\n            if provided, used to upload the workflow's project\n        ignore_file: an optional path to a `.prefectignore` file that specifies\n            filename patterns to ignore when uploading to remote storage; if not\n            provided, looks for `.prefectignore` in the current working directory\n    \"\"\"\n    file_count = None\n    if storage_block:\n        storage = await Block.load(storage_block)\n\n        if \"put-directory\" not in storage.get_block_capabilities():\n            raise BlockMissingCapabilities(\n                f\"Storage block {storage!r} missing 'put-directory' capability.\"\n            )\n\n        self.storage = storage\n\n        # upload current directory to storage location\n        file_count = await self.storage.put_directory(\n            ignore_file=ignore_file, to_path=self.path\n        )\n    elif self.storage:\n        if \"put-directory\" not in self.storage.get_block_capabilities():\n            raise BlockMissingCapabilities(\n                f\"Storage block {self.storage!r} missing 'put-directory'\"\n                \" capability.\"\n            )\n\n        file_count = await self.storage.put_directory(\n            ignore_file=ignore_file, to_path=self.path\n        )\n\n    # persists storage now in case it contains secret values\n    if self.storage and not self.storage._block_document_id:\n        await self.storage._save(is_anonymous=True)\n\n    return file_count\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.load_deployments_from_yaml","title":"<code>load_deployments_from_yaml</code>","text":"<p>Load deployments from a yaml file.</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_callable(start_date=\"Mar 2024\")\ndef load_deployments_from_yaml(\n    path: str,\n) -&gt; PrefectObjectRegistry:\n    \"\"\"\n    Load deployments from a yaml file.\n    \"\"\"\n    with open(path, \"r\") as f:\n        contents = f.read()\n\n    # Parse into a yaml tree to retrieve separate documents\n    nodes = yaml.compose_all(contents)\n\n    with PrefectObjectRegistry(capture_failures=True) as registry:\n        for node in nodes:\n            with tmpchdir(path):\n                deployment_dict = yaml.safe_load(yaml.serialize(node))\n                # The return value is not necessary, just instantiating the Deployment\n                # is enough to get it recorded on the registry\n                parse_obj_as(Deployment, deployment_dict)\n\n    return registry\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.load_flow_from_flow_run","title":"<code>load_flow_from_flow_run</code>  <code>async</code>","text":"<p>Load a flow from the location/script provided in a deployment's storage document.</p> <p>If <code>ignore_storage=True</code> is provided, no pull from remote storage occurs.  This flag is largely for testing, and assumes the flow is already available locally.</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_callable(\n    start_date=\"Jun 2024\",\n    help=\"Will be moved in Prefect 3 to prefect.flows:load_flow_from_flow_run\",\n)\n@inject_client\nasync def load_flow_from_flow_run(\n    flow_run: FlowRun,\n    client: PrefectClient,\n    ignore_storage: bool = False,\n    storage_base_path: Optional[str] = None,\n    use_placeholder_flow: bool = True,\n) -&gt; Flow:\n    \"\"\"\n    Load a flow from the location/script provided in a deployment's storage document.\n\n    If `ignore_storage=True` is provided, no pull from remote storage occurs.  This flag\n    is largely for testing, and assumes the flow is already available locally.\n    \"\"\"\n    deployment = await client.read_deployment(flow_run.deployment_id)\n\n    if deployment.entrypoint is None:\n        raise ValueError(\n            f\"Deployment {deployment.id} does not have an entrypoint and can not be run.\"\n        )\n\n    run_logger = flow_run_logger(flow_run)\n\n    runner_storage_base_path = storage_base_path or os.environ.get(\n        \"PREFECT__STORAGE_BASE_PATH\"\n    )\n\n    # If there's no colon, assume it's a module path\n    if \":\" not in deployment.entrypoint:\n        run_logger.debug(\n            f\"Importing flow code from module path {deployment.entrypoint}\"\n        )\n        flow = await run_sync_in_worker_thread(\n            load_flow_from_entrypoint, deployment.entrypoint, use_placeholder_flow\n        )\n        return flow\n\n    if not ignore_storage and not deployment.pull_steps:\n        sys.path.insert(0, \".\")\n        if deployment.storage_document_id:\n            storage_document = await client.read_block_document(\n                deployment.storage_document_id\n            )\n            storage_block = Block._from_block_document(storage_document)\n        else:\n            basepath = deployment.path or Path(deployment.manifest_path).parent\n            if runner_storage_base_path:\n                basepath = str(basepath).replace(\n                    \"$STORAGE_BASE_PATH\", runner_storage_base_path\n                )\n            storage_block = LocalFileSystem(basepath=basepath)\n\n        from_path = (\n            str(deployment.path).replace(\"$STORAGE_BASE_PATH\", runner_storage_base_path)\n            if runner_storage_base_path and deployment.path\n            else deployment.path\n        )\n        run_logger.info(f\"Downloading flow code from storage at {from_path!r}\")\n        await storage_block.get_directory(from_path=from_path, local_path=\".\")\n\n    if deployment.pull_steps:\n        run_logger.debug(f\"Running {len(deployment.pull_steps)} deployment pull steps\")\n        output = await run_steps(deployment.pull_steps)\n        if output.get(\"directory\"):\n            run_logger.debug(f\"Changing working directory to {output['directory']!r}\")\n            os.chdir(output[\"directory\"])\n\n    import_path = relative_path_to_current_platform(deployment.entrypoint)\n    # for backwards compat\n    if deployment.manifest_path:\n        with open(deployment.manifest_path, \"r\") as f:\n            import_path = json.load(f)[\"import_path\"]\n            import_path = (\n                Path(deployment.manifest_path).parent / import_path\n            ).absolute()\n    run_logger.debug(f\"Importing flow code from '{import_path}'\")\n\n    flow = await run_sync_in_worker_thread(\n        load_flow_from_entrypoint, str(import_path), use_placeholder_flow\n    )\n\n    return flow\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.run_deployment","title":"<code>run_deployment</code>  <code>async</code>","text":"<p>Create a flow run for a deployment and return it after completion or a timeout.</p> <p>By default, this function blocks until the flow run finishes executing. Specify a timeout (in seconds) to wait for the flow run to execute before returning flow run metadata. To return immediately, without waiting for the flow run to execute, set <code>timeout=0</code>.</p> <p>Note that if you specify a timeout, this function will return the flow run metadata whether or not the flow run finished executing.</p> <p>If called within a flow or task, the flow run this function creates will be linked to the current flow run as a subflow. Disable this behavior by passing <code>as_subflow=False</code>.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Union[str, UUID]</code> <p>The deployment id or deployment name in the form: <code>\"flow name/deployment name\"</code></p> required <code>parameters</code> <code>Optional[dict]</code> <p>Parameter overrides for this flow run. Merged with the deployment defaults.</p> <code>None</code> <code>scheduled_time</code> <code>Optional[datetime]</code> <p>The time to schedule the flow run for, defaults to scheduling the flow run to start now.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[str]</code> <p>A name for the created flow run</p> <code>None</code> <code>timeout</code> <code>Optional[float]</code> <p>The amount of time to wait (in seconds) for the flow run to complete before returning. Setting <code>timeout</code> to 0 will return the flow run metadata immediately. Setting <code>timeout</code> to None will allow this function to poll indefinitely. Defaults to None.</p> <code>None</code> <code>poll_interval</code> <code>Optional[float]</code> <p>The number of seconds between polls</p> <code>5</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>A list of tags to associate with this flow run; tags can be used in automations and for organizational purposes.</p> <code>None</code> <code>idempotency_key</code> <code>Optional[str]</code> <p>A unique value to recognize retries of the same run, and prevent creating multiple flow runs.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of a work queue to use for this run. Defaults to the default work queue for the deployment.</p> <code>None</code> <code>as_subflow</code> <code>Optional[bool]</code> <p>Whether to link the flow run as a subflow of the current flow or task run.</p> <code>True</code> <code>job_variables</code> <code>Optional[dict]</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code></p> <code>None</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"infra_overrides\",\n    start_date=\"Apr 2024\",\n    help=\"Use `job_variables` instead.\",\n)\n@inject_client\nasync def run_deployment(\n    name: Union[str, UUID],\n    client: Optional[PrefectClient] = None,\n    parameters: Optional[dict] = None,\n    scheduled_time: Optional[datetime] = None,\n    flow_run_name: Optional[str] = None,\n    timeout: Optional[float] = None,\n    poll_interval: Optional[float] = 5,\n    tags: Optional[Iterable[str]] = None,\n    idempotency_key: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    as_subflow: Optional[bool] = True,\n    infra_overrides: Optional[dict] = None,\n    job_variables: Optional[dict] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a deployment and return it after completion or a timeout.\n\n    By default, this function blocks until the flow run finishes executing.\n    Specify a timeout (in seconds) to wait for the flow run to execute before\n    returning flow run metadata. To return immediately, without waiting for the\n    flow run to execute, set `timeout=0`.\n\n    Note that if you specify a timeout, this function will return the flow run\n    metadata whether or not the flow run finished executing.\n\n    If called within a flow or task, the flow run this function creates will\n    be linked to the current flow run as a subflow. Disable this behavior by\n    passing `as_subflow=False`.\n\n    Args:\n        name: The deployment id or deployment name in the form:\n            `\"flow name/deployment name\"`\n        parameters: Parameter overrides for this flow run. Merged with the deployment\n            defaults.\n        scheduled_time: The time to schedule the flow run for, defaults to scheduling\n            the flow run to start now.\n        flow_run_name: A name for the created flow run\n        timeout: The amount of time to wait (in seconds) for the flow run to\n            complete before returning. Setting `timeout` to 0 will return the flow\n            run metadata immediately. Setting `timeout` to None will allow this\n            function to poll indefinitely. Defaults to None.\n        poll_interval: The number of seconds between polls\n        tags: A list of tags to associate with this flow run; tags can be used in\n            automations and for organizational purposes.\n        idempotency_key: A unique value to recognize retries of the same run, and\n            prevent creating multiple flow runs.\n        work_queue_name: The name of a work queue to use for this run. Defaults to\n            the default work queue for the deployment.\n        as_subflow: Whether to link the flow run as a subflow of the current\n            flow or task run.\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`\n    \"\"\"\n    if timeout is not None and timeout &lt; 0:\n        raise ValueError(\"`timeout` cannot be negative\")\n\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n\n    jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n    parameters = parameters or {}\n\n    deployment_id = None\n\n    if isinstance(name, UUID):\n        deployment_id = name\n    else:\n        try:\n            deployment_id = UUID(name)\n        except ValueError:\n            pass\n\n    if deployment_id:\n        deployment = await client.read_deployment(deployment_id=deployment_id)\n    else:\n        deployment = await client.read_deployment_by_name(name)\n\n    flow_run_ctx = FlowRunContext.get()\n    task_run_ctx = TaskRunContext.get()\n    if as_subflow and (flow_run_ctx or task_run_ctx):\n        # This was called from a flow. Link the flow run as a subflow.\n        from prefect.engine import (\n            Pending,\n            _dynamic_key_for_task_run,\n            collect_task_run_inputs,\n        )\n\n        task_inputs = {\n            k: await collect_task_run_inputs(v) for k, v in parameters.items()\n        }\n\n        if deployment_id:\n            flow = await client.read_flow(deployment.flow_id)\n            deployment_name = f\"{flow.name}/{deployment.name}\"\n        else:\n            deployment_name = name\n\n        # Generate a task in the parent flow run to represent the result of the subflow\n        dummy_task = Task(\n            name=deployment_name,\n            fn=lambda: None,\n            version=deployment.version,\n        )\n        # Override the default task key to include the deployment name\n        dummy_task.task_key = f\"{__name__}.run_deployment.{slugify(deployment_name)}\"\n        flow_run_id = (\n            flow_run_ctx.flow_run.id\n            if flow_run_ctx\n            else task_run_ctx.task_run.flow_run_id\n        )\n        dynamic_key = (\n            _dynamic_key_for_task_run(flow_run_ctx, dummy_task)\n            if flow_run_ctx\n            else task_run_ctx.task_run.dynamic_key\n        )\n        parent_task_run = await client.create_task_run(\n            task=dummy_task,\n            flow_run_id=flow_run_id,\n            dynamic_key=dynamic_key,\n            task_inputs=task_inputs,\n            state=Pending(),\n        )\n        parent_task_run_id = parent_task_run.id\n    else:\n        parent_task_run_id = None\n\n    flow_run = await client.create_flow_run_from_deployment(\n        deployment.id,\n        parameters=parameters,\n        state=Scheduled(scheduled_time=scheduled_time),\n        name=flow_run_name,\n        tags=tags,\n        idempotency_key=idempotency_key,\n        parent_task_run_id=parent_task_run_id,\n        work_queue_name=work_queue_name,\n        job_variables=jv,\n    )\n\n    flow_run_id = flow_run.id\n\n    if timeout == 0:\n        return flow_run\n\n    with anyio.move_on_after(timeout):\n        while True:\n            flow_run = await client.read_flow_run(flow_run_id)\n            flow_state = flow_run.state\n            if flow_state and flow_state.is_final():\n                return flow_run\n            await anyio.sleep(poll_interval)\n\n    return flow_run\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/runner/","title":"runner","text":"","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner","title":"<code>prefect.deployments.runner</code>","text":"<p>Objects for creating and configuring deployments for flows using <code>serve</code> functionality.</p> Example <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    # to_deployment creates RunnerDeployment instances\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n\n    serve(slow_deploy, fast_deploy)\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.DeploymentApplyError","title":"<code>DeploymentApplyError</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Raised when an error occurs while applying a deployment.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class DeploymentApplyError(RuntimeError):\n    \"\"\"\n    Raised when an error occurs while applying a deployment.\n    \"\"\"\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.DeploymentImage","title":"<code>DeploymentImage</code>","text":"<p>Configuration used to build and push a Docker image for a deployment.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name of the Docker image to build, including the registry and repository.</p> <code>tag</code> <p>The tag to apply to the built image.</p> <code>dockerfile</code> <p>The path to the Dockerfile to use for building the image. If not provided, a default Dockerfile will be generated.</p> <code>**build_kwargs</code> <p>Additional keyword arguments to pass to the Docker build request. See the <code>docker-py</code> documentation for more information.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class DeploymentImage:\n    \"\"\"\n    Configuration used to build and push a Docker image for a deployment.\n\n    Attributes:\n        name: The name of the Docker image to build, including the registry and\n            repository.\n        tag: The tag to apply to the built image.\n        dockerfile: The path to the Dockerfile to use for building the image. If\n            not provided, a default Dockerfile will be generated.\n        **build_kwargs: Additional keyword arguments to pass to the Docker build request.\n            See the [`docker-py` documentation](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build)\n            for more information.\n\n    \"\"\"\n\n    def __init__(self, name, tag=None, dockerfile=\"auto\", **build_kwargs):\n        image_name, image_tag = parse_image_tag(name)\n        if tag and image_tag:\n            raise ValueError(\n                f\"Only one tag can be provided - both {image_tag!r} and {tag!r} were\"\n                \" provided as tags.\"\n            )\n        namespace, repository = split_repository_path(image_name)\n        # if the provided image name does not include a namespace (registry URL or user/org name),\n        # use the default namespace\n        if not namespace:\n            namespace = PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE.value()\n        # join the namespace and repository to create the full image name\n        # ignore namespace if it is None\n        self.name = \"/\".join(filter(None, [namespace, repository]))\n        self.tag = tag or image_tag or slugify(pendulum.now(\"utc\").isoformat())\n        self.dockerfile = dockerfile\n        self.build_kwargs = build_kwargs\n\n    @property\n    def reference(self):\n        return f\"{self.name}:{self.tag}\"\n\n    def build(self):\n        full_image_name = self.reference\n        build_kwargs = self.build_kwargs.copy()\n        build_kwargs[\"context\"] = Path.cwd()\n        build_kwargs[\"tag\"] = full_image_name\n        build_kwargs[\"pull\"] = build_kwargs.get(\"pull\", True)\n\n        if self.dockerfile == \"auto\":\n            with generate_default_dockerfile():\n                build_image(**build_kwargs)\n        else:\n            build_kwargs[\"dockerfile\"] = self.dockerfile\n            build_image(**build_kwargs)\n\n    def push(self):\n        with docker_client() as client:\n            events = client.api.push(\n                repository=self.name, tag=self.tag, stream=True, decode=True\n            )\n            for event in events:\n                if \"error\" in event:\n                    raise PushError(event[\"error\"])\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.EntrypointType","title":"<code>EntrypointType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing a entrypoint type.</p> <p>File path entrypoints are in the format: <code>path/to/file.py:function_name</code>. Module path entrypoints are in the format: <code>path.to.module.function_name</code>.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class EntrypointType(enum.Enum):\n    \"\"\"\n    Enum representing a entrypoint type.\n\n    File path entrypoints are in the format: `path/to/file.py:function_name`.\n    Module path entrypoints are in the format: `path.to.module.function_name`.\n    \"\"\"\n\n    FILE_PATH = \"file_path\"\n    MODULE_PATH = \"module_path\"\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment","title":"<code>RunnerDeployment</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A Prefect RunnerDeployment definition, used for specifying and building deployments.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>A name for the deployment (required).</p> <code>version</code> <code>Optional[str]</code> <p>An optional version for the deployment; defaults to the flow's version</p> <code>description</code> <code>Optional[str]</code> <p>An optional description of the deployment; defaults to the flow's description</p> <code>tags</code> <code>List[str]</code> <p>An optional list of tags to associate with this deployment; note that tags are used only for organizational purposes. For delegating work to agents, see <code>work_queue_name</code>.</p> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule to run this deployment on, once registered</p> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not the schedule is active</p> <code>parameters</code> <code>Dict[str, Any]</code> <p>A dictionary of parameter values to pass to runs created from this deployment</p> <code>path</code> <code>Dict[str, Any]</code> <p>The path to the working directory for the workflow, relative to remote storage or, if stored on a local filesystem, an absolute path</p> <code>entrypoint</code> <code>Optional[str]</code> <p>The path to the entrypoint for the workflow, always relative to the <code>path</code></p> <code>parameter_openapi_schema</code> <code>Optional[str]</code> <p>The parameter schema of the flow, including defaults.</p> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>job_variables</code> <code>Dict[str, Any]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class RunnerDeployment(BaseModel):\n    \"\"\"\n    A Prefect RunnerDeployment definition, used for specifying and building deployments.\n\n    Attributes:\n        name: A name for the deployment (required).\n        version: An optional version for the deployment; defaults to the flow's version\n        description: An optional description of the deployment; defaults to the flow's\n            description\n        tags: An optional list of tags to associate with this deployment; note that tags\n            are used only for organizational purposes. For delegating work to agents,\n            see `work_queue_name`.\n        schedule: A schedule to run this deployment on, once registered\n        is_schedule_active: Whether or not the schedule is active\n        parameters: A dictionary of parameter values to pass to runs created from this\n            deployment\n        path: The path to the working directory for the workflow, relative to remote\n            storage or, if stored on a local filesystem, an absolute path\n        entrypoint: The path to the entrypoint for the workflow, always relative to the\n            `path`\n        parameter_openapi_schema: The parameter schema of the flow, including defaults.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n\n    class Config:\n        arbitrary_types_allowed = True\n\n    name: str = Field(..., description=\"The name of the deployment.\")\n    flow_name: Optional[str] = Field(\n        None, description=\"The name of the underlying flow; typically inferred.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"An optional description of the deployment.\"\n    )\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"One of more tags to apply to this deployment.\",\n    )\n    schedules: Optional[List[MinimalDeploymentSchedule]] = Field(\n        default=None,\n        description=\"The schedules that should cause this deployment to run.\",\n    )\n    schedule: Optional[SCHEDULE_TYPES] = None\n    paused: Optional[bool] = Field(\n        default=None, description=\"Whether or not the deployment is paused.\"\n    )\n    is_schedule_active: Optional[bool] = Field(\n        default=None, description=\"DEPRECATED: Whether or not the schedule is active.\"\n    )\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    triggers: List[Union[DeploymentTriggerTypes, TriggerTypes]] = Field(\n        default_factory=list,\n        description=\"The triggers that should cause this deployment to run.\",\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the Prefect API should enforce the parameter schema for\"\n            \" this deployment.\"\n        ),\n    )\n    storage: Optional[RunnerStorage] = Field(\n        default=None,\n        description=(\n            \"The storage object used to retrieve flow code for this deployment.\"\n        ),\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The name of the work pool to use for this deployment. Only used when\"\n            \" the deployment is registered with a built runner.\"\n        ),\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The name of the work queue to use for this deployment. Only used when\"\n            \" the deployment is registered with a built runner.\"\n        ),\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=(\n            \"Job variables used to override the default values of a work pool\"\n            \" base job template. Only used when the deployment is registered with\"\n            \" a built runner.\"\n        ),\n    )\n    _entrypoint_type: EntrypointType = PrivateAttr(\n        default=EntrypointType.FILE_PATH,\n    )\n    _path: Optional[str] = PrivateAttr(\n        default=None,\n    )\n    _parameter_openapi_schema: ParameterSchema = PrivateAttr(\n        default_factory=ParameterSchema,\n    )\n\n    @property\n    def entrypoint_type(self) -&gt; EntrypointType:\n        return self._entrypoint_type\n\n    @validator(\"triggers\", allow_reuse=True)\n    def validate_automation_names(cls, field_value, values):\n        \"\"\"Ensure that each trigger has a name for its automation if none is provided.\"\"\"\n        return validate_automation_names(field_value, values)\n\n    @root_validator(pre=True)\n    def reconcile_paused(cls, values):\n        return reconcile_paused_deployment(values)\n\n    @root_validator(pre=True)\n    def reconcile_schedules(cls, values):\n        return reconcile_schedules_runner(values)\n\n    @sync_compatible\n    async def apply(\n        self, work_pool_name: Optional[str] = None, image: Optional[str] = None\n    ) -&gt; UUID:\n        \"\"\"\n        Registers this deployment with the API and returns the deployment's ID.\n\n        Args:\n            work_pool_name: The name of the work pool to use for this\n                deployment.\n            image: The registry, name, and tag of the Docker image to\n                use for this deployment. Only used when the deployment is\n                deployed to a work pool.\n\n        Returns:\n            The ID of the created deployment.\n        \"\"\"\n\n        work_pool_name = work_pool_name or self.work_pool_name\n\n        if image and not work_pool_name:\n            raise ValueError(\n                \"An image can only be provided when registering a deployment with a\"\n                \" work pool.\"\n            )\n\n        if self.work_queue_name and not work_pool_name:\n            raise ValueError(\n                \"A work queue can only be provided when registering a deployment with\"\n                \" a work pool.\"\n            )\n\n        if self.job_variables and not work_pool_name:\n            raise ValueError(\n                \"Job variables can only be provided when registering a deployment\"\n                \" with a work pool.\"\n            )\n\n        async with get_client() as client:\n            flow_id = await client.create_flow_from_name(self.flow_name)\n\n            create_payload = dict(\n                flow_id=flow_id,\n                name=self.name,\n                work_queue_name=self.work_queue_name,\n                work_pool_name=work_pool_name,\n                version=self.version,\n                paused=self.paused,\n                schedules=self.schedules,\n                parameters=self.parameters,\n                description=self.description,\n                tags=self.tags,\n                path=self._path,\n                entrypoint=self.entrypoint,\n                storage_document_id=None,\n                infrastructure_document_id=None,\n                parameter_openapi_schema=self._parameter_openapi_schema.dict(),\n                enforce_parameter_schema=self.enforce_parameter_schema,\n            )\n\n            if work_pool_name:\n                create_payload[\"job_variables\"] = self.job_variables\n                if image:\n                    create_payload[\"job_variables\"][\"image\"] = image\n                create_payload[\"path\"] = None if self.storage else self._path\n                create_payload[\"pull_steps\"] = (\n                    [self.storage.to_pull_step()] if self.storage else []\n                )\n\n            try:\n                deployment_id = await client.create_deployment(**create_payload)\n            except Exception as exc:\n                if isinstance(exc, PrefectHTTPStatusError):\n                    detail = exc.response.json().get(\"detail\")\n                    if detail:\n                        raise DeploymentApplyError(detail) from exc\n                raise DeploymentApplyError(\n                    f\"Error while applying deployment: {str(exc)}\"\n                ) from exc\n\n            if client.server_type.supports_automations():\n                try:\n                    # The triggers defined in the deployment spec are, essentially,\n                    # anonymous and attempting truly sync them with cloud is not\n                    # feasible. Instead, we remove all automations that are owned\n                    # by the deployment, meaning that they were created via this\n                    # mechanism below, and then recreate them.\n                    await client.delete_resource_owned_automations(\n                        f\"prefect.deployment.{deployment_id}\"\n                    )\n                except PrefectHTTPStatusError as e:\n                    if e.response.status_code == 404:\n                        # This Prefect server does not support automations, so we can safely\n                        # ignore this 404 and move on.\n                        return deployment_id\n                    raise e\n\n                for trigger in self.triggers:\n                    trigger.set_deployment_id(deployment_id)\n                    await client.create_automation(trigger.as_automation())\n\n            return deployment_id\n\n    @staticmethod\n    def _construct_deployment_schedules(\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        anchor_date: Optional[Union[datetime, str]] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        timezone: Optional[str] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n    ) -&gt; Union[List[MinimalDeploymentSchedule], FlexibleScheduleList]:\n        \"\"\"\n        Construct a schedule or schedules from the provided arguments.\n\n        This method serves as a unified interface for creating deployment\n        schedules. If `schedules` is provided, it is directly returned. If\n        `schedule` is provided, it is encapsulated in a list and returned. If\n        `interval`, `cron`, or `rrule` are provided, they are used to construct\n        schedule objects.\n\n        Args:\n            interval: An interval on which to schedule runs, either as a single\n              value or as a list of values. Accepts numbers (interpreted as\n              seconds) or `timedelta` objects. Each value defines a separate\n              scheduling interval.\n            anchor_date: The anchor date from which interval schedules should\n              start. This applies to all intervals if a list is provided.\n            cron: A cron expression or a list of cron expressions defining cron\n              schedules. Each expression defines a separate cron schedule.\n            rrule: An rrule string or a list of rrule strings for scheduling.\n              Each string defines a separate recurrence rule.\n            timezone: The timezone to apply to the cron or rrule schedules.\n              This is a single value applied uniformly to all schedules.\n            schedule: A singular schedule object, used for advanced scheduling\n              options like specifying a timezone. This is returned as a list\n              containing this single schedule.\n            schedules: A pre-defined list of schedule objects. If provided,\n              this list is returned as-is, bypassing other schedule construction\n              logic.\n        \"\"\"\n\n        num_schedules = sum(\n            1\n            for entry in (interval, cron, rrule, schedule, schedules)\n            if entry is not None\n        )\n        if num_schedules &gt; 1:\n            raise ValueError(\n                \"Only one of interval, cron, rrule, schedule, or schedules can be provided.\"\n            )\n        elif num_schedules == 0:\n            return []\n\n        if schedules is not None:\n            return schedules\n        elif interval or cron or rrule:\n            # `interval`, `cron`, and `rrule` can be lists of values. This\n            # block figures out which one is not None and uses that to\n            # construct the list of schedules via `construct_schedule`.\n            parameters = [(\"interval\", interval), (\"cron\", cron), (\"rrule\", rrule)]\n            schedule_type, value = [\n                param for param in parameters if param[1] is not None\n            ][0]\n\n            if not isiterable(value):\n                value = [value]\n\n            return [\n                create_minimal_deployment_schedule(\n                    construct_schedule(\n                        **{\n                            schedule_type: v,\n                            \"timezone\": timezone,\n                            \"anchor_date\": anchor_date,\n                        }\n                    )\n                )\n                for v in value\n            ]\n        else:\n            return [create_minimal_deployment_schedule(schedule)]\n\n    def _set_defaults_from_flow(self, flow: \"Flow\"):\n        self._parameter_openapi_schema = parameter_schema(flow)\n\n        if not self.version:\n            self.version = flow.version\n        if not self.description:\n            self.description = flow.description\n\n    @classmethod\n    def from_flow(\n        cls,\n        flow: \"Flow\",\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Configure a deployment for a given flow.\n\n        Args:\n            flow: A flow function to deploy\n            name: A name for the deployment\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        job_variables = job_variables or {}\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            is_schedule_active=is_schedule_active,\n            paused=paused,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n\n        if not deployment.entrypoint:\n            no_file_location_error = (\n                \"Flows defined interactively cannot be deployed. Check out the\"\n                \" quickstart guide for help getting started:\"\n                \" https://docs.prefect.io/latest/getting-started/quickstart\"\n            )\n            ## first see if an entrypoint can be determined\n            flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n            mod_name = getattr(flow, \"__module__\", None)\n            if entrypoint_type == EntrypointType.MODULE_PATH:\n                if mod_name:\n                    deployment.entrypoint = f\"{mod_name}.{flow.__name__}\"\n                else:\n                    raise ValueError(\n                        \"Unable to determine module path for provided flow.\"\n                    )\n            else:\n                if not flow_file:\n                    if not mod_name:\n                        raise ValueError(no_file_location_error)\n                    try:\n                        module = importlib.import_module(mod_name)\n                        flow_file = getattr(module, \"__file__\", None)\n                    except ModuleNotFoundError as exc:\n                        if \"__prefect_loader__\" in str(exc):\n                            raise ValueError(\n                                \"Cannot create a RunnerDeployment from a flow that has been\"\n                                \" loaded from an entrypoint. To deploy a flow via\"\n                                \" entrypoint, use RunnerDeployment.from_entrypoint instead.\"\n                            )\n                        raise ValueError(no_file_location_error)\n                    if not flow_file:\n                        raise ValueError(no_file_location_error)\n\n                # set entrypoint\n                entry_path = (\n                    Path(flow_file).absolute().relative_to(Path.cwd().absolute())\n                )\n                deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n        if entrypoint_type == EntrypointType.FILE_PATH and not deployment._path:\n            deployment._path = \".\"\n\n        deployment._entrypoint_type = entrypoint_type\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n\n    @classmethod\n    def from_entrypoint(\n        cls,\n        entrypoint: str,\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Configure a deployment for a given flow located at a given entrypoint.\n\n        Args:\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n            name: A name for the deployment\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        from prefect.flows import load_flow_from_entrypoint\n\n        job_variables = job_variables or {}\n        flow = load_flow_from_entrypoint(entrypoint)\n\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            entrypoint=entrypoint,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n        deployment._path = str(Path.cwd())\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n\n    @classmethod\n    @sync_compatible\n    async def from_storage(\n        cls,\n        storage: RunnerStorage,\n        entrypoint: str,\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ):\n        \"\"\"\n        Create a RunnerDeployment from a flow located at a given entrypoint and stored in a\n        local storage location.\n\n        Args:\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n            name: A name for the deployment\n            storage: A storage object to use for retrieving flow code. If not provided, a\n                URL must be provided.\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        from prefect.flows import load_flow_from_entrypoint\n\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        job_variables = job_variables or {}\n\n        with tempfile.TemporaryDirectory() as tmpdir:\n            storage.set_base_path(Path(tmpdir))\n            await storage.pull_code()\n\n            full_entrypoint = str(storage.destination / entrypoint)\n            flow = await from_async.wait_for_call_in_new_thread(\n                create_call(load_flow_from_entrypoint, full_entrypoint)\n            )\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            entrypoint=entrypoint,\n            enforce_parameter_schema=enforce_parameter_schema,\n            storage=storage,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n        deployment._path = str(storage.destination).replace(\n            tmpdir, \"$STORAGE_BASE_PATH\"\n        )\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Registers this deployment with the API and returns the deployment's ID.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>image</code> <code>Optional[str]</code> <p>The registry, name, and tag of the Docker image to use for this deployment. Only used when the deployment is deployed to a work pool.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The ID of the created deployment.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@sync_compatible\nasync def apply(\n    self, work_pool_name: Optional[str] = None, image: Optional[str] = None\n) -&gt; UUID:\n    \"\"\"\n    Registers this deployment with the API and returns the deployment's ID.\n\n    Args:\n        work_pool_name: The name of the work pool to use for this\n            deployment.\n        image: The registry, name, and tag of the Docker image to\n            use for this deployment. Only used when the deployment is\n            deployed to a work pool.\n\n    Returns:\n        The ID of the created deployment.\n    \"\"\"\n\n    work_pool_name = work_pool_name or self.work_pool_name\n\n    if image and not work_pool_name:\n        raise ValueError(\n            \"An image can only be provided when registering a deployment with a\"\n            \" work pool.\"\n        )\n\n    if self.work_queue_name and not work_pool_name:\n        raise ValueError(\n            \"A work queue can only be provided when registering a deployment with\"\n            \" a work pool.\"\n        )\n\n    if self.job_variables and not work_pool_name:\n        raise ValueError(\n            \"Job variables can only be provided when registering a deployment\"\n            \" with a work pool.\"\n        )\n\n    async with get_client() as client:\n        flow_id = await client.create_flow_from_name(self.flow_name)\n\n        create_payload = dict(\n            flow_id=flow_id,\n            name=self.name,\n            work_queue_name=self.work_queue_name,\n            work_pool_name=work_pool_name,\n            version=self.version,\n            paused=self.paused,\n            schedules=self.schedules,\n            parameters=self.parameters,\n            description=self.description,\n            tags=self.tags,\n            path=self._path,\n            entrypoint=self.entrypoint,\n            storage_document_id=None,\n            infrastructure_document_id=None,\n            parameter_openapi_schema=self._parameter_openapi_schema.dict(),\n            enforce_parameter_schema=self.enforce_parameter_schema,\n        )\n\n        if work_pool_name:\n            create_payload[\"job_variables\"] = self.job_variables\n            if image:\n                create_payload[\"job_variables\"][\"image\"] = image\n            create_payload[\"path\"] = None if self.storage else self._path\n            create_payload[\"pull_steps\"] = (\n                [self.storage.to_pull_step()] if self.storage else []\n            )\n\n        try:\n            deployment_id = await client.create_deployment(**create_payload)\n        except Exception as exc:\n            if isinstance(exc, PrefectHTTPStatusError):\n                detail = exc.response.json().get(\"detail\")\n                if detail:\n                    raise DeploymentApplyError(detail) from exc\n            raise DeploymentApplyError(\n                f\"Error while applying deployment: {str(exc)}\"\n            ) from exc\n\n        if client.server_type.supports_automations():\n            try:\n                # The triggers defined in the deployment spec are, essentially,\n                # anonymous and attempting truly sync them with cloud is not\n                # feasible. Instead, we remove all automations that are owned\n                # by the deployment, meaning that they were created via this\n                # mechanism below, and then recreate them.\n                await client.delete_resource_owned_automations(\n                    f\"prefect.deployment.{deployment_id}\"\n                )\n            except PrefectHTTPStatusError as e:\n                if e.response.status_code == 404:\n                    # This Prefect server does not support automations, so we can safely\n                    # ignore this 404 and move on.\n                    return deployment_id\n                raise e\n\n            for trigger in self.triggers:\n                trigger.set_deployment_id(deployment_id)\n                await client.create_automation(trigger.as_automation())\n\n        return deployment_id\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_entrypoint","title":"<code>from_entrypoint</code>  <code>classmethod</code>","text":"<p>Configure a deployment for a given flow located at a given entrypoint.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\ndef from_entrypoint(\n    cls,\n    entrypoint: str,\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Configure a deployment for a given flow located at a given entrypoint.\n\n    Args:\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n        name: A name for the deployment\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    from prefect.flows import load_flow_from_entrypoint\n\n    job_variables = job_variables or {}\n    flow = load_flow_from_entrypoint(entrypoint)\n\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        entrypoint=entrypoint,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n    deployment._path = str(Path.cwd())\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_flow","title":"<code>from_flow</code>  <code>classmethod</code>","text":"<p>Configure a deployment for a given flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow function to deploy</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\ndef from_flow(\n    cls,\n    flow: \"Flow\",\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Configure a deployment for a given flow.\n\n    Args:\n        flow: A flow function to deploy\n        name: A name for the deployment\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    job_variables = job_variables or {}\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        is_schedule_active=is_schedule_active,\n        paused=paused,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n\n    if not deployment.entrypoint:\n        no_file_location_error = (\n            \"Flows defined interactively cannot be deployed. Check out the\"\n            \" quickstart guide for help getting started:\"\n            \" https://docs.prefect.io/latest/getting-started/quickstart\"\n        )\n        ## first see if an entrypoint can be determined\n        flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n        mod_name = getattr(flow, \"__module__\", None)\n        if entrypoint_type == EntrypointType.MODULE_PATH:\n            if mod_name:\n                deployment.entrypoint = f\"{mod_name}.{flow.__name__}\"\n            else:\n                raise ValueError(\n                    \"Unable to determine module path for provided flow.\"\n                )\n        else:\n            if not flow_file:\n                if not mod_name:\n                    raise ValueError(no_file_location_error)\n                try:\n                    module = importlib.import_module(mod_name)\n                    flow_file = getattr(module, \"__file__\", None)\n                except ModuleNotFoundError as exc:\n                    if \"__prefect_loader__\" in str(exc):\n                        raise ValueError(\n                            \"Cannot create a RunnerDeployment from a flow that has been\"\n                            \" loaded from an entrypoint. To deploy a flow via\"\n                            \" entrypoint, use RunnerDeployment.from_entrypoint instead.\"\n                        )\n                    raise ValueError(no_file_location_error)\n                if not flow_file:\n                    raise ValueError(no_file_location_error)\n\n            # set entrypoint\n            entry_path = (\n                Path(flow_file).absolute().relative_to(Path.cwd().absolute())\n            )\n            deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n    if entrypoint_type == EntrypointType.FILE_PATH and not deployment._path:\n        deployment._path = \".\"\n\n    deployment._entrypoint_type = entrypoint_type\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_storage","title":"<code>from_storage</code>  <code>async</code> <code>classmethod</code>","text":"<p>Create a RunnerDeployment from a flow located at a given entrypoint and stored in a local storage location.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>storage</code> <code>RunnerStorage</code> <p>A storage object to use for retrieving flow code. If not provided, a URL must be provided.</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def from_storage(\n    cls,\n    storage: RunnerStorage,\n    entrypoint: str,\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n):\n    \"\"\"\n    Create a RunnerDeployment from a flow located at a given entrypoint and stored in a\n    local storage location.\n\n    Args:\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n        name: A name for the deployment\n        storage: A storage object to use for retrieving flow code. If not provided, a\n            URL must be provided.\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    from prefect.flows import load_flow_from_entrypoint\n\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    job_variables = job_variables or {}\n\n    with tempfile.TemporaryDirectory() as tmpdir:\n        storage.set_base_path(Path(tmpdir))\n        await storage.pull_code()\n\n        full_entrypoint = str(storage.destination / entrypoint)\n        flow = await from_async.wait_for_call_in_new_thread(\n            create_call(load_flow_from_entrypoint, full_entrypoint)\n        )\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        entrypoint=entrypoint,\n        enforce_parameter_schema=enforce_parameter_schema,\n        storage=storage,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n    deployment._path = str(storage.destination).replace(\n        tmpdir, \"$STORAGE_BASE_PATH\"\n    )\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.validate_automation_names","title":"<code>validate_automation_names</code>","text":"<p>Ensure that each trigger has a name for its automation if none is provided.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@validator(\"triggers\", allow_reuse=True)\ndef validate_automation_names(cls, field_value, values):\n    \"\"\"Ensure that each trigger has a name for its automation if none is provided.\"\"\"\n    return validate_automation_names(field_value, values)\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploy the provided list of deployments to dynamic infrastructure via a work pool.</p> <p>By default, calling this function will build a Docker image for the deployments, push it to a registry, and create each deployment via the Prefect API that will run the corresponding flow on the given schedule.</p> <p>If you want to use an existing image, you can pass <code>build=False</code> to skip building and pushing an image.</p> <p>Parameters:</p> Name Type Description Default <code>*deployments</code> <code>RunnerDeployment</code> <p>A list of deployments to deploy.</p> <code>()</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for these deployments. Defaults to the value of <code>PREFECT_DEFAULT_WORK_POOL_NAME</code>.</p> <code>None</code> <code>image</code> <code>Optional[Union[str, DeploymentImage]]</code> <p>The name of the Docker image to build, including the registry and repository. Pass a DeploymentImage instance to customize the Dockerfile used and build arguments.</p> <code>None</code> <code>build</code> <code>bool</code> <p>Whether or not to build a new image for the flow. If False, the provided image will be used as-is and pulled at runtime.</p> <code>True</code> <code>push</code> <code>bool</code> <p>Whether or not to skip pushing the built image to a registry.</p> <code>True</code> <code>print_next_steps_message</code> <code>bool</code> <p>Whether or not to print a message with next steps after deploying the deployments.</p> <code>True</code> <p>Returns:</p> Type Description <code>List[UUID]</code> <p>A list of deployment IDs for the created/updated deployments.</p> <p>Examples:</p> <p>Deploy a group of flows to a work pool:</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef local_flow():\n    print(\"I'm a locally defined flow!\")\n\nif __name__ == \"__main__\":\n    deploy(\n        local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n        flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        ).to_deployment(\n            name=\"example-deploy-remote-flow\",\n        ),\n        work_pool_name=\"my-work-pool\",\n        image=\"my-registry/my-image:dev\",\n    )\n</code></pre> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@sync_compatible\nasync def deploy(\n    *deployments: RunnerDeployment,\n    work_pool_name: Optional[str] = None,\n    image: Optional[Union[str, DeploymentImage]] = None,\n    build: bool = True,\n    push: bool = True,\n    print_next_steps_message: bool = True,\n    ignore_warnings: bool = False,\n) -&gt; List[UUID]:\n    \"\"\"\n    Deploy the provided list of deployments to dynamic infrastructure via a\n    work pool.\n\n    By default, calling this function will build a Docker image for the deployments, push it to a\n    registry, and create each deployment via the Prefect API that will run the corresponding\n    flow on the given schedule.\n\n    If you want to use an existing image, you can pass `build=False` to skip building and pushing\n    an image.\n\n    Args:\n        *deployments: A list of deployments to deploy.\n        work_pool_name: The name of the work pool to use for these deployments. Defaults to\n            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n        image: The name of the Docker image to build, including the registry and\n            repository. Pass a DeploymentImage instance to customize the Dockerfile used\n            and build arguments.\n        build: Whether or not to build a new image for the flow. If False, the provided\n            image will be used as-is and pulled at runtime.\n        push: Whether or not to skip pushing the built image to a registry.\n        print_next_steps_message: Whether or not to print a message with next steps\n            after deploying the deployments.\n\n    Returns:\n        A list of deployment IDs for the created/updated deployments.\n\n    Examples:\n        Deploy a group of flows to a work pool:\n\n        ```python\n        from prefect import deploy, flow\n\n        @flow(log_prints=True)\n        def local_flow():\n            print(\"I'm a locally defined flow!\")\n\n        if __name__ == \"__main__\":\n            deploy(\n                local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n                flow.from_source(\n                    source=\"https://github.com/org/repo.git\",\n                    entrypoint=\"flows.py:my_flow\",\n                ).to_deployment(\n                    name=\"example-deploy-remote-flow\",\n                ),\n                work_pool_name=\"my-work-pool\",\n                image=\"my-registry/my-image:dev\",\n            )\n        ```\n    \"\"\"\n    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n    if not image and not all(\n        d.storage or d.entrypoint_type == EntrypointType.MODULE_PATH\n        for d in deployments\n    ):\n        raise ValueError(\n            \"Either an image or remote storage location must be provided when deploying\"\n            \" a deployment.\"\n        )\n\n    if not work_pool_name:\n        raise ValueError(\n            \"A work pool name must be provided when deploying a deployment. Either\"\n            \" provide a work pool name when calling `deploy` or set\"\n            \" `PREFECT_DEFAULT_WORK_POOL_NAME` in your profile.\"\n        )\n\n    if image and isinstance(image, str):\n        image_name, image_tag = parse_image_tag(image)\n        image = DeploymentImage(name=image_name, tag=image_tag)\n\n    try:\n        async with get_client() as client:\n            work_pool = await client.read_work_pool(work_pool_name)\n    except ObjectNotFound as exc:\n        raise ValueError(\n            f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n            \" deploying this flow.\"\n        ) from exc\n\n    is_docker_based_work_pool = get_from_dict(\n        work_pool.base_job_template, \"variables.properties.image\", False\n    )\n    is_block_based_work_pool = get_from_dict(\n        work_pool.base_job_template, \"variables.properties.block\", False\n    )\n    # carve out an exception for block based work pools that only have a block in their base job template\n    console = Console()\n    if not is_docker_based_work_pool and not is_block_based_work_pool:\n        if image:\n            raise ValueError(\n                f\"Work pool {work_pool_name!r} does not support custom Docker images.\"\n                \" Please use a work pool with an `image` variable in its base job template\"\n                \" or specify a remote storage location for the flow with `.from_source`.\"\n                \" If you are attempting to deploy a flow to a local process work pool,\"\n                \" consider using `flow.serve` instead. See the documentation for more\"\n                \" information: https://docs.prefect.io/latest/concepts/flows/#serving-a-flow\"\n            )\n        elif work_pool.type == \"process\" and not ignore_warnings:\n            console.print(\n                \"Looks like you're deploying to a process work pool. If you're creating a\"\n                \" deployment for local development, calling `.serve` on your flow is a great\"\n                \" way to get started. See the documentation for more information:\"\n                \" https://docs.prefect.io/latest/concepts/flows/#serving-a-flow. \"\n                \" Set `ignore_warnings=True` to suppress this message.\",\n                style=\"yellow\",\n            )\n\n    is_managed_pool = work_pool.is_managed_pool\n    if is_managed_pool:\n        build = False\n        push = False\n\n    if image and build:\n        with Progress(\n            SpinnerColumn(),\n            TextColumn(f\"Building image {image.reference}...\"),\n            transient=True,\n            console=console,\n        ) as progress:\n            docker_build_task = progress.add_task(\"docker_build\", total=1)\n            image.build()\n\n            progress.update(docker_build_task, completed=1)\n            console.print(\n                f\"Successfully built image {image.reference!r}\", style=\"green\"\n            )\n\n    if image and build and push:\n        with Progress(\n            SpinnerColumn(),\n            TextColumn(\"Pushing image...\"),\n            transient=True,\n            console=console,\n        ) as progress:\n            docker_push_task = progress.add_task(\"docker_push\", total=1)\n\n            image.push()\n\n            progress.update(docker_push_task, completed=1)\n\n        console.print(f\"Successfully pushed image {image.reference!r}\", style=\"green\")\n\n    deployment_exceptions = []\n    deployment_ids = []\n    image_ref = image.reference if image else None\n    for deployment in track(\n        deployments,\n        description=\"Creating/updating deployments...\",\n        console=console,\n        transient=True,\n    ):\n        try:\n            deployment_ids.append(\n                await deployment.apply(image=image_ref, work_pool_name=work_pool_name)\n            )\n        except Exception as exc:\n            if len(deployments) == 1:\n                raise\n            deployment_exceptions.append({\"deployment\": deployment, \"exc\": exc})\n\n    if deployment_exceptions:\n        console.print(\n            \"Encountered errors while creating/updating deployments:\\n\",\n            style=\"orange_red1\",\n        )\n    else:\n        console.print(\"Successfully created/updated all deployments!\\n\", style=\"green\")\n\n    complete_failure = len(deployment_exceptions) == len(deployments)\n\n    table = Table(\n        title=\"Deployments\",\n        show_lines=True,\n    )\n\n    table.add_column(header=\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(header=\"Status\", style=\"blue\", no_wrap=True)\n    table.add_column(header=\"Details\", style=\"blue\")\n\n    for deployment in deployments:\n        errored_deployment = next(\n            (d for d in deployment_exceptions if d[\"deployment\"] == deployment),\n            None,\n        )\n        if errored_deployment:\n            table.add_row(\n                f\"{deployment.flow_name}/{deployment.name}\",\n                \"failed\",\n                str(errored_deployment[\"exc\"]),\n                style=\"red\",\n            )\n        else:\n            table.add_row(f\"{deployment.flow_name}/{deployment.name}\", \"applied\")\n    console.print(table)\n\n    if print_next_steps_message and not complete_failure:\n        if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n            console.print(\n                \"\\nTo execute flow runs from these deployments, start a worker in a\"\n                \" separate terminal that pulls work from the\"\n                f\" {work_pool_name!r} work pool:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                style=\"blue\",\n            )\n        console.print(\n            \"\\nTo trigger any of these deployments, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            \" [DEPLOYMENT_NAME]\\n[/]\"\n        )\n\n        if PREFECT_UI_URL:\n            console.print(\n                \"\\nYou can also trigger your deployments via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments[/]\\n\"\n            )\n\n    return deployment_ids\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/steps/core/","title":"steps.core","text":"","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core","title":"<code>prefect.deployments.steps.core</code>","text":"<p>Core primitives for running Prefect deployment steps.</p> <p>Deployment steps are YAML representations of Python functions along with their inputs.</p> <p>Whenever a step is run, the following actions are taken:</p> <ul> <li>The step's inputs and block / variable references are resolved (see the <code>prefect deploy</code> documentation for more details)</li> <li>The step's function is imported; if it cannot be found, the <code>requires</code> keyword is used to install the necessary packages</li> <li>The step's function is called with the resolved inputs</li> <li>The step's output is returned and used to resolve inputs for subsequent steps</li> </ul>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core.StepExecutionError","title":"<code>StepExecutionError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a step fails to execute.</p> Source code in <code>prefect/deployments/steps/core.py</code> <pre><code>class StepExecutionError(Exception):\n    \"\"\"\n    Raised when a step fails to execute.\n    \"\"\"\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core.run_step","title":"<code>run_step</code>  <code>async</code>","text":"<p>Runs a step, returns the step's output.</p> <p>Steps are assumed to be in the format <code>{\"importable.func.name\": {\"kwarg1\": \"value1\", ...}}</code>.</p> <p>The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the inputs before passing to the step function:</p> <p>This keyword is used to specify packages that should be installed before running the step.</p> Source code in <code>prefect/deployments/steps/core.py</code> <pre><code>async def run_step(step: Dict, upstream_outputs: Optional[Dict] = None) -&gt; Dict:\n    \"\"\"\n    Runs a step, returns the step's output.\n\n    Steps are assumed to be in the format `{\"importable.func.name\": {\"kwarg1\": \"value1\", ...}}`.\n\n    The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the\n    inputs before passing to the step function:\n\n    This keyword is used to specify packages that should be installed before running the step.\n    \"\"\"\n    fqn, inputs = _get_step_fully_qualified_name_and_inputs(step)\n    upstream_outputs = upstream_outputs or {}\n\n    if len(step.keys()) &gt; 1:\n        raise ValueError(\n            f\"Step has unexpected additional keys: {', '.join(list(step.keys())[1:])}\"\n        )\n\n    keywords = {\n        keyword: inputs.pop(keyword)\n        for keyword in RESERVED_KEYWORDS\n        if keyword in inputs\n    }\n\n    inputs = apply_values(inputs, upstream_outputs)\n    inputs = await resolve_block_document_references(inputs)\n    inputs = await resolve_variables(inputs)\n    inputs = apply_values(inputs, os.environ)\n    step_func = _get_function_for_step(fqn, requires=keywords.get(\"requires\"))\n    result = await from_async.call_soon_in_new_thread(\n        Call.new(step_func, **inputs)\n    ).aresult()\n    return result\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/pull/","title":"steps.pull","text":"","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull","title":"<code>prefect.deployments.steps.pull</code>","text":"<p>Core set of steps for specifying a Prefect project pull step.</p>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.git_clone","title":"<code>git_clone</code>  <code>async</code>","text":"<p>Clones a git repository into the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>repository</code> <code>str</code> <p>the URL of the repository to clone</p> required <code>branch</code> <code>Optional[str]</code> <p>the branch to clone; if not provided, the default branch will be used</p> <code>None</code> <code>include_submodules</code> <code>bool</code> <p>whether to include git submodules when cloning the repository</p> <code>False</code> <code>access_token</code> <code>Optional[str]</code> <p>an access token to use for cloning the repository; if not provided the repository will be cloned using the default git credentials</p> <code>None</code> <code>credentials</code> <code>Optional[Block]</code> <p>a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the credentials to use for cloning the repository.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the new directory that was created</p> <p>Raises:</p> Type Description <code>CalledProcessError</code> <p>if the git clone command fails for any reason</p> <p>Examples:</p> <p>Clone a public repository: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/PrefectHQ/prefect.git\n</code></pre></p> <p>Clone a branch of a public repository: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/PrefectHQ/prefect.git\n        branch: my-branch\n</code></pre></p> <p>Clone a private repository using a GitHubCredentials block: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n</code></pre></p> <p>Clone a private repository using an access token: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        access_token: \"{{ prefect.blocks.secret.github-access-token }}\" # Requires creation of a Secret block\n</code></pre> Note that you will need to create a Secret block to store the value of your git credentials. You can also store a username/password combo or token prefix (e.g. <code>x-token-auth</code>) in your secret block. Refer to your git providers documentation for the correct authentication schema.</p> <p>Clone a repository with submodules: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        include_submodules: true\n</code></pre></p> <p>Clone a repository with an SSH key (note that the SSH key must be added to the worker before executing flows): <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: git@github.com:org/repo.git\n</code></pre></p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>@sync_compatible\nasync def git_clone(\n    repository: str,\n    branch: Optional[str] = None,\n    include_submodules: bool = False,\n    access_token: Optional[str] = None,\n    credentials: Optional[Block] = None,\n) -&gt; dict:\n    \"\"\"\n    Clones a git repository into the current working directory.\n\n    Args:\n        repository: the URL of the repository to clone\n        branch: the branch to clone; if not provided, the default branch will be used\n        include_submodules (bool): whether to include git submodules when cloning the repository\n        access_token: an access token to use for cloning the repository; if not provided\n            the repository will be cloned using the default git credentials\n        credentials: a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the\n            credentials to use for cloning the repository.\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the new directory that was created\n\n    Raises:\n        subprocess.CalledProcessError: if the git clone command fails for any reason\n\n    Examples:\n        Clone a public repository:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/PrefectHQ/prefect.git\n        ```\n\n        Clone a branch of a public repository:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/PrefectHQ/prefect.git\n                branch: my-branch\n        ```\n\n        Clone a private repository using a GitHubCredentials block:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n        ```\n\n        Clone a private repository using an access token:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                access_token: \"{{ prefect.blocks.secret.github-access-token }}\" # Requires creation of a Secret block\n        ```\n        Note that you will need to [create a Secret block](/concepts/blocks/#using-existing-block-types) to store the\n        value of your git credentials. You can also store a username/password combo or token prefix (e.g. `x-token-auth`)\n        in your secret block. Refer to your git providers documentation for the correct authentication schema.\n\n        Clone a repository with submodules:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                include_submodules: true\n        ```\n\n        Clone a repository with an SSH key (note that the SSH key must be added to the worker\n        before executing flows):\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: git@github.com:org/repo.git\n        ```\n    \"\"\"\n    if access_token and credentials:\n        raise ValueError(\n            \"Please provide either an access token or credentials but not both.\"\n        )\n\n    credentials = {\"access_token\": access_token} if access_token else credentials\n\n    storage = GitRepository(\n        url=repository,\n        credentials=credentials,\n        branch=branch,\n        include_submodules=include_submodules,\n    )\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(f\"Cloned repository {repository!r} into {directory!r}\")\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.git_clone_project","title":"<code>git_clone_project</code>  <code>async</code>","text":"<p>Deprecated. Use <code>git_clone</code> instead.</p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use 'git clone' instead.\")\n@sync_compatible\nasync def git_clone_project(\n    repository: str,\n    branch: Optional[str] = None,\n    include_submodules: bool = False,\n    access_token: Optional[str] = None,\n) -&gt; dict:\n    \"\"\"Deprecated. Use `git_clone` instead.\"\"\"\n    return await git_clone(\n        repository=repository,\n        branch=branch,\n        include_submodules=include_submodules,\n        access_token=access_token,\n    )\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.pull_from_remote_storage","title":"<code>pull_from_remote_storage</code>  <code>async</code>","text":"<p>Pulls code from a remote storage location into the current working directory.</p> <p>Works with protocols supported by <code>fsspec</code>.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>the URL of the remote storage location. Should be a valid <code>fsspec</code> URL. Some protocols may require an additional <code>fsspec</code> dependency to be installed. Refer to the <code>fsspec</code> docs for more details.</p> required <code>**settings</code> <code>Any</code> <p>any additional settings to pass the <code>fsspec</code> filesystem class.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the new directory that was created</p> <p>Examples:</p> <p>Pull code from a remote storage location: <pre><code>pull:\n    - prefect.deployments.steps.pull_from_remote_storage:\n        url: s3://my-bucket/my-folder\n</code></pre></p> <p>Pull code from a remote storage location with additional settings: <pre><code>pull:\n    - prefect.deployments.steps.pull_from_remote_storage:\n        url: s3://my-bucket/my-folder\n        key: {{ prefect.blocks.secret.my-aws-access-key }}}\n        secret: {{ prefect.blocks.secret.my-aws-secret-key }}}\n</code></pre></p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>async def pull_from_remote_storage(url: str, **settings: Any):\n    \"\"\"\n    Pulls code from a remote storage location into the current working directory.\n\n    Works with protocols supported by `fsspec`.\n\n    Args:\n        url (str): the URL of the remote storage location. Should be a valid `fsspec` URL.\n            Some protocols may require an additional `fsspec` dependency to be installed.\n            Refer to the [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)\n            for more details.\n        **settings (Any): any additional settings to pass the `fsspec` filesystem class.\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the new directory that was created\n\n    Examples:\n        Pull code from a remote storage location:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.pull_from_remote_storage:\n                url: s3://my-bucket/my-folder\n        ```\n\n        Pull code from a remote storage location with additional settings:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.pull_from_remote_storage:\n                url: s3://my-bucket/my-folder\n                key: {{ prefect.blocks.secret.my-aws-access-key }}}\n                secret: {{ prefect.blocks.secret.my-aws-secret-key }}}\n        ```\n    \"\"\"\n    storage = RemoteStorage(url, **settings)\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(f\"Pulled code from {url!r} into {directory!r}\")\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.pull_with_block","title":"<code>pull_with_block</code>  <code>async</code>","text":"<p>Pulls code using a block.</p> <p>Parameters:</p> Name Type Description Default <code>block_document_name</code> <code>str</code> <p>The name of the block document to use</p> required <code>block_type_slug</code> <code>str</code> <p>The slug of the type of block to use</p> required Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>async def pull_with_block(block_document_name: str, block_type_slug: str):\n    \"\"\"\n    Pulls code using a block.\n\n    Args:\n        block_document_name: The name of the block document to use\n        block_type_slug: The slug of the type of block to use\n    \"\"\"\n    full_slug = f\"{block_type_slug}/{block_document_name}\"\n    try:\n        block = await Block.load(full_slug)\n    except Exception:\n        deployment_logger.exception(\"Unable to load block '%s'\", full_slug)\n        raise\n\n    try:\n        storage = BlockStorageAdapter(block)\n    except Exception:\n        deployment_logger.exception(\n            \"Unable to create storage adapter for block '%s'\", full_slug\n        )\n        raise\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(\n        \"Pulled code using block '%s' into '%s'\", full_slug, directory\n    )\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.set_working_directory","title":"<code>set_working_directory</code>","text":"<p>Sets the working directory; works with both absolute and relative paths.</p> <p>Parameters:</p> Name Type Description Default <code>directory</code> <code>str</code> <p>the directory to set as the working directory</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the directory that was set</p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>def set_working_directory(directory: str) -&gt; dict:\n    \"\"\"\n    Sets the working directory; works with both absolute and relative paths.\n\n    Args:\n        directory (str): the directory to set as the working directory\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the\n            directory that was set\n    \"\"\"\n    os.chdir(directory)\n    return dict(directory=directory)\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/utility/","title":"steps.utility","text":"","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility","title":"<code>prefect.deployments.steps.utility</code>","text":"<p>Utility project steps that are useful for managing a project's deployment lifecycle.</p> <p>Steps within this module can be used within a <code>build</code>, <code>push</code>, or <code>pull</code> deployment action.</p> Example <p>Use the <code>run_shell_script</code> setp to retrieve the short Git commit hash of the current      repository and use it as a Docker image tag: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre></p>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.RunShellScriptResult","title":"<code>RunShellScriptResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>run_shell_script</code> step.</p> <p>Attributes:</p> Name Type Description <code>stdout</code> <code>str</code> <p>The captured standard output of the script.</p> <code>stderr</code> <code>str</code> <p>The captured standard error of the script.</p> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>class RunShellScriptResult(TypedDict):\n    \"\"\"\n    The result of a `run_shell_script` step.\n\n    Attributes:\n        stdout: The captured standard output of the script.\n        stderr: The captured standard error of the script.\n    \"\"\"\n\n    stdout: str\n    stderr: str\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.pip_install_requirements","title":"<code>pip_install_requirements</code>  <code>async</code>","text":"<p>Installs dependencies from a requirements.txt file.</p> <p>Parameters:</p> Name Type Description Default <code>requirements_file</code> <code>str</code> <p>The requirements.txt to use for installation.</p> <code>'requirements.txt'</code> <code>directory</code> <code>Optional[str]</code> <p>The directory the requirements.txt file is in. Defaults to the current working directory.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream the output from pip install should be streamed to the console</p> <code>True</code> <p>Returns:</p> Type Description <p>A dictionary with the keys <code>stdout</code> and <code>stderr</code> containing the output the <code>pip install</code> command</p> <p>Raises:</p> Type Description <code>CalledProcessError</code> <p>if the pip install command fails for any reason</p> Example <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        id: clone-step\n        repository: https://github.com/org/repo.git\n    - prefect.deployments.steps.pip_install_requirements:\n        directory: {{ clone-step.directory }}\n        requirements_file: requirements.txt\n        stream_output: False\n</code></pre> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>async def pip_install_requirements(\n    directory: Optional[str] = None,\n    requirements_file: str = \"requirements.txt\",\n    stream_output: bool = True,\n):\n    \"\"\"\n    Installs dependencies from a requirements.txt file.\n\n    Args:\n        requirements_file: The requirements.txt to use for installation.\n        directory: The directory the requirements.txt file is in. Defaults to\n            the current working directory.\n        stream_output: Whether to stream the output from pip install should be\n            streamed to the console\n\n    Returns:\n        A dictionary with the keys `stdout` and `stderr` containing the output\n            the `pip install` command\n\n    Raises:\n        subprocess.CalledProcessError: if the pip install command fails for any reason\n\n    Example:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                id: clone-step\n                repository: https://github.com/org/repo.git\n            - prefect.deployments.steps.pip_install_requirements:\n                directory: {{ clone-step.directory }}\n                requirements_file: requirements.txt\n                stream_output: False\n        ```\n    \"\"\"\n    stdout_sink = io.StringIO()\n    stderr_sink = io.StringIO()\n\n    async with open_process(\n        [get_sys_executable(), \"-m\", \"pip\", \"install\", \"-r\", requirements_file],\n        stdout=subprocess.PIPE,\n        stderr=subprocess.PIPE,\n        cwd=directory,\n    ) as process:\n        await _stream_capture_process_output(\n            process,\n            stdout_sink=stdout_sink,\n            stderr_sink=stderr_sink,\n            stream_output=stream_output,\n        )\n        await process.wait()\n\n        if process.returncode != 0:\n            raise RuntimeError(\n                f\"pip_install_requirements failed with error code {process.returncode}:\"\n                f\" {stderr_sink.getvalue()}\"\n            )\n\n    return {\n        \"stdout\": stdout_sink.getvalue().strip(),\n        \"stderr\": stderr_sink.getvalue().strip(),\n    }\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.run_shell_script","title":"<code>run_shell_script</code>  <code>async</code>","text":"<p>Runs one or more shell commands in a subprocess. Returns the standard output and standard error of the script.</p> <p>Parameters:</p> Name Type Description Default <code>script</code> <code>str</code> <p>The script to run</p> required <code>directory</code> <code>Optional[str]</code> <p>The directory to run the script in. Defaults to the current working directory.</p> <code>None</code> <code>env</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of environment variables to set for the script</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream the output of the script to stdout/stderr</p> <code>True</code> <code>expand_env_vars</code> <code>bool</code> <p>Whether to expand environment variables in the script before running it</p> <code>False</code> <p>Returns:</p> Type Description <code>RunShellScriptResult</code> <p>A dictionary with the keys <code>stdout</code> and <code>stderr</code> containing the output of the script</p> <p>Examples:</p> <p>Retrieve the short Git commit hash of the current repository to use as     a Docker image tag: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre></p> <p>Run a multi-line shell script: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: |\n            echo \"Hello\"\n            echo \"World\"\n</code></pre></p> <p>Run a shell script with environment variables: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: echo \"Hello $NAME\"\n        env:\n            NAME: World\n</code></pre></p> <p>Run a shell script with environment variables expanded     from the current environment: <pre><code>pull:\n    - prefect.deployments.steps.run_shell_script:\n        script: |\n            echo \"User: $USER\"\n            echo \"Home Directory: $HOME\"\n        stream_output: true\n        expand_env_vars: true\n</code></pre></p> <p>Run a shell script in a specific directory: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: echo \"Hello\"\n        directory: /path/to/directory\n</code></pre></p> <p>Run a script stored in a file: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: \"bash path/to/script.sh\"\n</code></pre></p> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>async def run_shell_script(\n    script: str,\n    directory: Optional[str] = None,\n    env: Optional[Dict[str, str]] = None,\n    stream_output: bool = True,\n    expand_env_vars: bool = False,\n) -&gt; RunShellScriptResult:\n    \"\"\"\n    Runs one or more shell commands in a subprocess. Returns the standard\n    output and standard error of the script.\n\n    Args:\n        script: The script to run\n        directory: The directory to run the script in. Defaults to the current\n            working directory.\n        env: A dictionary of environment variables to set for the script\n        stream_output: Whether to stream the output of the script to\n            stdout/stderr\n        expand_env_vars: Whether to expand environment variables in the script\n            before running it\n\n    Returns:\n        A dictionary with the keys `stdout` and `stderr` containing the output\n            of the script\n\n    Examples:\n        Retrieve the short Git commit hash of the current repository to use as\n            a Docker image tag:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                id: get-commit-hash\n                script: git rev-parse --short HEAD\n                stream_output: false\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: my-image\n                image_tag: \"{{ get-commit-hash.stdout }}\"\n                dockerfile: auto\n        ```\n\n        Run a multi-line shell script:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: |\n                    echo \"Hello\"\n                    echo \"World\"\n        ```\n\n        Run a shell script with environment variables:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: echo \"Hello $NAME\"\n                env:\n                    NAME: World\n        ```\n\n        Run a shell script with environment variables expanded\n            from the current environment:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.run_shell_script:\n                script: |\n                    echo \"User: $USER\"\n                    echo \"Home Directory: $HOME\"\n                stream_output: true\n                expand_env_vars: true\n        ```\n\n        Run a shell script in a specific directory:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: echo \"Hello\"\n                directory: /path/to/directory\n        ```\n\n        Run a script stored in a file:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: \"bash path/to/script.sh\"\n        ```\n    \"\"\"\n    current_env = os.environ.copy()\n    current_env.update(env or {})\n\n    commands = script.splitlines()\n    stdout_sink = io.StringIO()\n    stderr_sink = io.StringIO()\n\n    for command in commands:\n        if expand_env_vars:\n            # Expand environment variables in command and provided environment\n            command = string.Template(command).safe_substitute(current_env)\n        split_command = shlex.split(command, posix=sys.platform != \"win32\")\n        if not split_command:\n            continue\n        async with open_process(\n            split_command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.PIPE,\n            cwd=directory,\n            env=current_env,\n        ) as process:\n            await _stream_capture_process_output(\n                process,\n                stdout_sink=stdout_sink,\n                stderr_sink=stderr_sink,\n                stream_output=stream_output,\n            )\n\n            await process.wait()\n\n            if process.returncode != 0:\n                raise RuntimeError(\n                    f\"`run_shell_script` failed with error code {process.returncode}:\"\n                    f\" {stderr_sink.getvalue()}\"\n                )\n\n    return {\n        \"stdout\": stdout_sink.getvalue().strip(),\n        \"stderr\": stderr_sink.getvalue().strip(),\n    }\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/input/actions/","title":"actions","text":"","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions","title":"<code>prefect.input.actions</code>","text":"","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Create a new flow run input. The given <code>value</code> will be serialized to JSON and stored as a flow run input value.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>key (str</code> <p>the flow run input key</p> required <code>-</code> <code>value (Any</code> <p>the flow run input value</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the, optional, flow run ID. If not given will default to pulling the flow run ID from the current context.</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def create_flow_run_input(\n    client: \"PrefectClient\",\n    key: str,\n    value: Any,\n    flow_run_id: Optional[UUID] = None,\n    sender: Optional[str] = None,\n):\n    \"\"\"\n    Create a new flow run input. The given `value` will be serialized to JSON\n    and stored as a flow run input value.\n\n    Args:\n        - key (str): the flow run input key\n        - value (Any): the flow run input value\n        - flow_run_id (UUID): the, optional, flow run ID. If not given will\n          default to pulling the flow run ID from the current context.\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    await client.create_flow_run_input(\n        flow_run_id=flow_run_id,\n        key=key,\n        sender=sender,\n        value=orjson.dumps(value).decode(),\n    )\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Delete a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID</p> required <code>-</code> <code>key (str</code> <p>the flow run input key</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def delete_flow_run_input(\n    client: \"PrefectClient\", key: str, flow_run_id: Optional[UUID] = None\n):\n    \"\"\"Delete a flow run input.\n\n    Args:\n        - flow_run_id (UUID): the flow run ID\n        - key (str): the flow run input key\n    \"\"\"\n\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    await client.delete_flow_run_input(flow_run_id=flow_run_id, key=key)\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Read a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>key (str</code> <p>the flow run input key</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def read_flow_run_input(\n    client: \"PrefectClient\", key: str, flow_run_id: Optional[UUID] = None\n) -&gt; Any:\n    \"\"\"Read a flow run input.\n\n    Args:\n        - key (str): the flow run input key\n        - flow_run_id (UUID): the flow run ID\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    try:\n        value = await client.read_flow_run_input(flow_run_id=flow_run_id, key=key)\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return None\n        raise\n    else:\n        return orjson.loads(value)\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/run_input/","title":"run_input","text":"","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input","title":"<code>prefect.input.run_input</code>","text":"<p>This module contains functions that allow sending type-checked <code>RunInput</code> data to flows at runtime. Flows can send back responses, establishing two-way channels with senders. These functions are particularly useful for systems that require ongoing data transfer or need to react to input quickly. real-time interaction and efficient data handling. It's designed to facilitate dynamic communication within distributed or microservices-oriented systems, making it ideal for scenarios requiring continuous data synchronization and processing. It's particularly useful for systems that require ongoing data input and output.</p> <p>The following is an example of two flows. One sends a random number to the other and waits for a response. The other receives the number, squares it, and sends the result back. The sender flow then prints the result.</p> <p>Sender flow:</p> <pre><code>import random\nfrom uuid import UUID\nfrom prefect import flow, get_run_logger\nfrom prefect.input import RunInput\n\nclass NumberData(RunInput):\n    number: int\n\n\n@flow\nasync def sender_flow(receiver_flow_run_id: UUID):\n    logger = get_run_logger()\n\n    the_number = random.randint(1, 100)\n\n    await NumberData(number=the_number).send_to(receiver_flow_run_id)\n\n    receiver = NumberData.receive(flow_run_id=receiver_flow_run_id)\n    squared = await receiver.next()\n\n    logger.info(f\"{the_number} squared is {squared.number}\")\n</code></pre> <p>Receiver flow: <pre><code>import random\nfrom uuid import UUID\nfrom prefect import flow, get_run_logger\nfrom prefect.input import RunInput\n\nclass NumberData(RunInput):\n    number: int\n\n\n@flow\nasync def receiver_flow():\n    async for data in NumberData.receive():\n        squared = data.number ** 2\n        data.respond(NumberData(number=squared))\n</code></pre></p>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput","title":"<code>AutomaticRunInput</code>","text":"<p>               Bases: <code>RunInput</code>, <code>Generic[T]</code></p> Source code in <code>prefect/input/run_input.py</code> <pre><code>class AutomaticRunInput(RunInput, Generic[T]):\n    value: T\n\n    @classmethod\n    @sync_compatible\n    async def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -&gt; T:\n        \"\"\"\n        Load the run input response from the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to load the input for\n            - flow_run_id (UUID, optional): the flow run ID to load the input for\n        \"\"\"\n        instance = await super().load(keyset, flow_run_id=flow_run_id)\n        return instance.value\n\n    @classmethod\n    def subclass_from_type(cls, _type: Type[T]) -&gt; Type[\"AutomaticRunInput[T]\"]:\n        \"\"\"\n        Create a new `AutomaticRunInput` subclass from the given type.\n\n        This method uses the type's name as a key prefix to identify related\n        flow run inputs. This helps in ensuring that values saved under a type\n        (like List[int]) are retrievable under the generic type name (like \"list\").\n        \"\"\"\n        fields: Dict[str, Any] = {\"value\": (_type, ...)}\n\n        # Explanation for using getattr for type name extraction:\n        # - \"__name__\": This is the usual attribute for getting the name of\n        #   most types.\n        # - \"_name\": Used as a fallback, some type annotations in Python 3.9\n        #   and earlier might only have this attribute instead of __name__.\n        # - If neither is available, defaults to an empty string to prevent\n        #   errors, but typically we should find at least one valid name\n        #   attribute. This will match all automatic inputs sent to the flow\n        #   run, rather than a specific type.\n        #\n        # This approach ensures compatibility across Python versions and\n        # handles various edge cases in type annotations.\n\n        type_prefix: str = getattr(\n            _type, \"__name__\", getattr(_type, \"_name\", \"\")\n        ).lower()\n\n        class_name = f\"{type_prefix}AutomaticRunInput\"\n\n        # Creating a new Pydantic model class dynamically with the name based\n        # on the type prefix.\n        new_cls: Type[\"AutomaticRunInput\"] = pydantic.create_model(\n            class_name, **fields, __base__=AutomaticRunInput\n        )\n        return new_cls\n\n    @classmethod\n    def receive(cls, *args, **kwargs):\n        if kwargs.get(\"key_prefix\") is None:\n            kwargs[\"key_prefix\"] = f\"{cls.__name__.lower()}-auto\"\n\n        return GetAutomaticInputHandler(run_input_cls=cls, *args, **kwargs)\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Load the run input response from the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to load the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -&gt; T:\n    \"\"\"\n    Load the run input response from the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to load the input for\n        - flow_run_id (UUID, optional): the flow run ID to load the input for\n    \"\"\"\n    instance = await super().load(keyset, flow_run_id=flow_run_id)\n    return instance.value\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput.subclass_from_type","title":"<code>subclass_from_type</code>  <code>classmethod</code>","text":"<p>Create a new <code>AutomaticRunInput</code> subclass from the given type.</p> <p>This method uses the type's name as a key prefix to identify related flow run inputs. This helps in ensuring that values saved under a type (like List[int]) are retrievable under the generic type name (like \"list\").</p> Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef subclass_from_type(cls, _type: Type[T]) -&gt; Type[\"AutomaticRunInput[T]\"]:\n    \"\"\"\n    Create a new `AutomaticRunInput` subclass from the given type.\n\n    This method uses the type's name as a key prefix to identify related\n    flow run inputs. This helps in ensuring that values saved under a type\n    (like List[int]) are retrievable under the generic type name (like \"list\").\n    \"\"\"\n    fields: Dict[str, Any] = {\"value\": (_type, ...)}\n\n    # Explanation for using getattr for type name extraction:\n    # - \"__name__\": This is the usual attribute for getting the name of\n    #   most types.\n    # - \"_name\": Used as a fallback, some type annotations in Python 3.9\n    #   and earlier might only have this attribute instead of __name__.\n    # - If neither is available, defaults to an empty string to prevent\n    #   errors, but typically we should find at least one valid name\n    #   attribute. This will match all automatic inputs sent to the flow\n    #   run, rather than a specific type.\n    #\n    # This approach ensures compatibility across Python versions and\n    # handles various edge cases in type annotations.\n\n    type_prefix: str = getattr(\n        _type, \"__name__\", getattr(_type, \"_name\", \"\")\n    ).lower()\n\n    class_name = f\"{type_prefix}AutomaticRunInput\"\n\n    # Creating a new Pydantic model class dynamically with the name based\n    # on the type prefix.\n    new_cls: Type[\"AutomaticRunInput\"] = pydantic.create_model(\n        class_name, **fields, __base__=AutomaticRunInput\n    )\n    return new_cls\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput","title":"<code>RunInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/input/run_input.py</code> <pre><code>class RunInput(pydantic.BaseModel):\n    class Config:\n        extra = \"forbid\"\n\n    _description: Optional[str] = pydantic.PrivateAttr(default=None)\n    _metadata: RunInputMetadata = pydantic.PrivateAttr()\n\n    @property\n    def metadata(self) -&gt; RunInputMetadata:\n        return self._metadata\n\n    @classmethod\n    def keyset_from_type(cls) -&gt; Keyset:\n        return keyset_from_base_key(cls.__name__.lower())\n\n    @classmethod\n    @sync_compatible\n    async def save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n        \"\"\"\n        Save the run input response to the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to save the input for\n            - flow_run_id (UUID, optional): the flow run ID to save the input for\n        \"\"\"\n\n        if HAS_PYDANTIC_V2:\n            schema = create_v2_schema(cls.__name__, model_base=cls)\n        else:\n            schema = cls.schema(by_alias=True)\n\n        await create_flow_run_input(\n            key=keyset[\"schema\"], value=schema, flow_run_id=flow_run_id\n        )\n\n        description = cls._description if isinstance(cls._description, str) else None\n        if description:\n            await create_flow_run_input(\n                key=keyset[\"description\"],\n                value=description,\n                flow_run_id=flow_run_id,\n            )\n\n    @classmethod\n    @sync_compatible\n    async def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n        \"\"\"\n        Load the run input response from the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to load the input for\n            - flow_run_id (UUID, optional): the flow run ID to load the input for\n        \"\"\"\n        flow_run_id = ensure_flow_run_id(flow_run_id)\n        value = await read_flow_run_input(keyset[\"response\"], flow_run_id=flow_run_id)\n        if value:\n            instance = cls(**value)\n        else:\n            instance = cls()\n        instance._metadata = RunInputMetadata(\n            key=keyset[\"response\"], sender=None, receiver=flow_run_id\n        )\n        return instance\n\n    @classmethod\n    def load_from_flow_run_input(cls, flow_run_input: \"FlowRunInput\"):\n        \"\"\"\n        Load the run input from a FlowRunInput object.\n\n        Args:\n            - flow_run_input (FlowRunInput): the flow run input to load the input for\n        \"\"\"\n        instance = cls(**flow_run_input.decoded_value)\n        instance._metadata = RunInputMetadata(\n            key=flow_run_input.key,\n            sender=flow_run_input.sender,\n            receiver=flow_run_input.flow_run_id,\n        )\n        return instance\n\n    @classmethod\n    def with_initial_data(\n        cls: Type[R], description: Optional[str] = None, **kwargs: Any\n    ) -&gt; Type[R]:\n        \"\"\"\n        Create a new `RunInput` subclass with the given initial data as field\n        defaults.\n\n        Args:\n            - description (str, optional): a description to show when resuming\n                a flow run that requires input\n            - kwargs (Any): the initial data to populate the subclass\n        \"\"\"\n        fields: Dict[str, Any] = {}\n        for key, value in kwargs.items():\n            fields[key] = (type(value), value)\n        model = pydantic.create_model(cls.__name__, **fields, __base__=cls)\n\n        if description is not None:\n            model._description = description\n\n        return model\n\n    @sync_compatible\n    async def respond(\n        self,\n        run_input: \"RunInput\",\n        sender: Optional[str] = None,\n        key_prefix: Optional[str] = None,\n    ):\n        flow_run_id = None\n        if self.metadata.sender and self.metadata.sender.startswith(\"prefect.flow-run\"):\n            _, _, id = self.metadata.sender.rpartition(\".\")\n            flow_run_id = UUID(id)\n\n        if not flow_run_id:\n            raise RuntimeError(\n                \"Cannot respond to an input that was not sent by a flow run.\"\n            )\n\n        await _send_input(\n            flow_run_id=flow_run_id,\n            run_input=run_input,\n            sender=sender,\n            key_prefix=key_prefix,\n        )\n\n    @sync_compatible\n    async def send_to(\n        self,\n        flow_run_id: UUID,\n        sender: Optional[str] = None,\n        key_prefix: Optional[str] = None,\n    ):\n        await _send_input(\n            flow_run_id=flow_run_id,\n            run_input=self,\n            sender=sender,\n            key_prefix=key_prefix,\n        )\n\n    @classmethod\n    def receive(\n        cls,\n        timeout: Optional[float] = 3600,\n        poll_interval: float = 10,\n        raise_timeout_error: bool = False,\n        exclude_keys: Optional[Set[str]] = None,\n        key_prefix: Optional[str] = None,\n        flow_run_id: Optional[UUID] = None,\n    ):\n        if key_prefix is None:\n            key_prefix = f\"{cls.__name__.lower()}-auto\"\n\n        return GetInputHandler(\n            run_input_cls=cls,\n            key_prefix=key_prefix,\n            timeout=timeout,\n            poll_interval=poll_interval,\n            raise_timeout_error=raise_timeout_error,\n            exclude_keys=exclude_keys,\n            flow_run_id=flow_run_id,\n        )\n\n    @classmethod\n    def subclass_from_base_model_type(\n        cls, model_cls: Type[pydantic.BaseModel]\n    ) -&gt; Type[\"RunInput\"]:\n        \"\"\"\n        Create a new `RunInput` subclass from the given `pydantic.BaseModel`\n        subclass.\n\n        Args:\n            - model_cls (pydantic.BaseModel subclass): the class from which\n                to create the new `RunInput` subclass\n        \"\"\"\n        return type(f\"{model_cls.__name__}RunInput\", (RunInput, model_cls), {})  # type: ignore\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Load the run input response from the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to load the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n    \"\"\"\n    Load the run input response from the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to load the input for\n        - flow_run_id (UUID, optional): the flow run ID to load the input for\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n    value = await read_flow_run_input(keyset[\"response\"], flow_run_id=flow_run_id)\n    if value:\n        instance = cls(**value)\n    else:\n        instance = cls()\n    instance._metadata = RunInputMetadata(\n        key=keyset[\"response\"], sender=None, receiver=flow_run_id\n    )\n    return instance\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.load_from_flow_run_input","title":"<code>load_from_flow_run_input</code>  <code>classmethod</code>","text":"<p>Load the run input from a FlowRunInput object.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>flow_run_input (FlowRunInput</code> <p>the flow run input to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef load_from_flow_run_input(cls, flow_run_input: \"FlowRunInput\"):\n    \"\"\"\n    Load the run input from a FlowRunInput object.\n\n    Args:\n        - flow_run_input (FlowRunInput): the flow run input to load the input for\n    \"\"\"\n    instance = cls(**flow_run_input.decoded_value)\n    instance._metadata = RunInputMetadata(\n        key=flow_run_input.key,\n        sender=flow_run_input.sender,\n        receiver=flow_run_input.flow_run_id,\n    )\n    return instance\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.save","title":"<code>save</code>  <code>async</code> <code>classmethod</code>","text":"<p>Save the run input response to the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to save the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to save the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n    \"\"\"\n    Save the run input response to the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to save the input for\n        - flow_run_id (UUID, optional): the flow run ID to save the input for\n    \"\"\"\n\n    if HAS_PYDANTIC_V2:\n        schema = create_v2_schema(cls.__name__, model_base=cls)\n    else:\n        schema = cls.schema(by_alias=True)\n\n    await create_flow_run_input(\n        key=keyset[\"schema\"], value=schema, flow_run_id=flow_run_id\n    )\n\n    description = cls._description if isinstance(cls._description, str) else None\n    if description:\n        await create_flow_run_input(\n            key=keyset[\"description\"],\n            value=description,\n            flow_run_id=flow_run_id,\n        )\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.subclass_from_base_model_type","title":"<code>subclass_from_base_model_type</code>  <code>classmethod</code>","text":"<p>Create a new <code>RunInput</code> subclass from the given <code>pydantic.BaseModel</code> subclass.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>model_cls (pydantic.BaseModel subclass</code> <p>the class from which to create the new <code>RunInput</code> subclass</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef subclass_from_base_model_type(\n    cls, model_cls: Type[pydantic.BaseModel]\n) -&gt; Type[\"RunInput\"]:\n    \"\"\"\n    Create a new `RunInput` subclass from the given `pydantic.BaseModel`\n    subclass.\n\n    Args:\n        - model_cls (pydantic.BaseModel subclass): the class from which\n            to create the new `RunInput` subclass\n    \"\"\"\n    return type(f\"{model_cls.__name__}RunInput\", (RunInput, model_cls), {})  # type: ignore\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.with_initial_data","title":"<code>with_initial_data</code>  <code>classmethod</code>","text":"<p>Create a new <code>RunInput</code> subclass with the given initial data as field defaults.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>description (str</code> <p>a description to show when resuming a flow run that requires input</p> required <code>-</code> <code>kwargs (Any</code> <p>the initial data to populate the subclass</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef with_initial_data(\n    cls: Type[R], description: Optional[str] = None, **kwargs: Any\n) -&gt; Type[R]:\n    \"\"\"\n    Create a new `RunInput` subclass with the given initial data as field\n    defaults.\n\n    Args:\n        - description (str, optional): a description to show when resuming\n            a flow run that requires input\n        - kwargs (Any): the initial data to populate the subclass\n    \"\"\"\n    fields: Dict[str, Any] = {}\n    for key, value in kwargs.items():\n        fields[key] = (type(value), value)\n    model = pydantic.create_model(cls.__name__, **fields, __base__=cls)\n\n    if description is not None:\n        model._description = description\n\n    return model\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.keyset_from_base_key","title":"<code>keyset_from_base_key</code>","text":"<p>Get the keyset for the given base key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>base_key (str</code> <p>the base key to get the keyset for</p> required <p>Returns:</p> Type Description <code>Keyset</code> <ul> <li>Dict[str, str]: the keyset</li> </ul> Source code in <code>prefect/input/run_input.py</code> <pre><code>def keyset_from_base_key(base_key: str) -&gt; Keyset:\n    \"\"\"\n    Get the keyset for the given base key.\n\n    Args:\n        - base_key (str): the base key to get the keyset for\n\n    Returns:\n        - Dict[str, str]: the keyset\n    \"\"\"\n    return {\n        \"description\": f\"{base_key}-description\",\n        \"response\": f\"{base_key}-response\",\n        \"schema\": f\"{base_key}-schema\",\n    }\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.keyset_from_paused_state","title":"<code>keyset_from_paused_state</code>","text":"<p>Get the keyset for the given Paused state.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>state (State</code> <p>the state to get the keyset for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>def keyset_from_paused_state(state: \"State\") -&gt; Keyset:\n    \"\"\"\n    Get the keyset for the given Paused state.\n\n    Args:\n        - state (State): the state to get the keyset for\n    \"\"\"\n\n    if not state.is_paused():\n        raise RuntimeError(f\"{state.type.value!r} is unsupported.\")\n\n    state_name = state.name or \"\"\n    base_key = f\"{state_name.lower()}-{str(state.state_details.pause_key)}\"\n    return keyset_from_base_key(base_key)\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.run_input_subclass_from_type","title":"<code>run_input_subclass_from_type</code>","text":"<p>Create a new <code>RunInput</code> subclass from the given type.</p> Source code in <code>prefect/input/run_input.py</code> <pre><code>def run_input_subclass_from_type(\n    _type: Union[Type[R], Type[T], pydantic.BaseModel],\n) -&gt; Union[Type[AutomaticRunInput[T]], Type[R]]:\n    \"\"\"\n    Create a new `RunInput` subclass from the given type.\n    \"\"\"\n    if isclass(_type):\n        if issubclass(_type, RunInput):\n            return cast(Type[R], _type)\n        elif issubclass(_type, pydantic.BaseModel):\n            return cast(Type[R], RunInput.subclass_from_base_model_type(_type))\n\n    # Could be something like a typing._GenericAlias or any other type that\n    # isn't a `RunInput` subclass or `pydantic.BaseModel` subclass. Try passing\n    # it to AutomaticRunInput to see if we can create a model from it.\n    return cast(\n        Type[AutomaticRunInput[T]],\n        AutomaticRunInput.subclass_from_type(cast(Type[T], _type)),\n    )\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/logging/configuration/","title":"configuration","text":"<p>\"\"\"</p>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration","title":"<code>prefect.logging.configuration</code>","text":"","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration.load_logging_config","title":"<code>load_logging_config</code>","text":"<p>Loads logging configuration from a path allowing override from the environment</p> Source code in <code>prefect/logging/configuration.py</code> <pre><code>def load_logging_config(path: Path) -&gt; dict:\n    \"\"\"\n    Loads logging configuration from a path allowing override from the environment\n    \"\"\"\n    template = string.Template(path.read_text())\n    with warnings.catch_warnings():\n        warnings.filterwarnings(\"ignore\", category=DeprecationWarning)\n        config = yaml.safe_load(\n            # Substitute settings into the template in format $SETTING / ${SETTING}\n            template.substitute(\n                {\n                    setting.name: str(setting.value())\n                    for setting in SETTING_VARIABLES.values()\n                    if setting.value() is not None\n                }\n            )\n        )\n\n    # Load overrides from the environment\n    flat_config = dict_to_flatdict(config)\n\n    for key_tup, val in flat_config.items():\n        env_val = os.environ.get(\n            # Generate a valid environment variable with nesting indicated with '_'\n            to_envvar(\"PREFECT_LOGGING_\" + \"_\".join(key_tup)).upper()\n        )\n        if env_val:\n            val = env_val\n\n        # reassign the updated value\n        flat_config[key_tup] = val\n\n    return flatdict_to_dict(flat_config)\n</code></pre>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration.setup_logging","title":"<code>setup_logging</code>","text":"<p>Sets up logging.</p> <p>Returns the config used.</p> Source code in <code>prefect/logging/configuration.py</code> <pre><code>def setup_logging(incremental: Optional[bool] = None) -&gt; dict:\n    \"\"\"\n    Sets up logging.\n\n    Returns the config used.\n    \"\"\"\n    global PROCESS_LOGGING_CONFIG\n\n    # If the user has specified a logging path and it exists we will ignore the\n    # default entirely rather than dealing with complex merging\n    config = load_logging_config(\n        (\n            PREFECT_LOGGING_SETTINGS_PATH.value()\n            if PREFECT_LOGGING_SETTINGS_PATH.value().exists()\n            else DEFAULT_LOGGING_SETTINGS_PATH\n        )\n    )\n\n    incremental = (\n        incremental if incremental is not None else bool(PROCESS_LOGGING_CONFIG)\n    )\n\n    # Perform an incremental update if setup has already been run\n    config.setdefault(\"incremental\", incremental)\n\n    try:\n        logging.config.dictConfig(config)\n    except ValueError:\n        if incremental:\n            setup_logging(incremental=False)\n\n    # Copy configuration of the 'prefect.extra' logger to the extra loggers\n    extra_config = logging.getLogger(\"prefect.extra\")\n\n    for logger_name in PREFECT_LOGGING_EXTRA_LOGGERS.value():\n        logger = logging.getLogger(logger_name)\n        for handler in extra_config.handlers:\n            if not config[\"incremental\"]:\n                logger.addHandler(handler)\n            if logger.level == logging.NOTSET:\n                logger.setLevel(extra_config.level)\n            logger.propagate = extra_config.propagate\n\n    PROCESS_LOGGING_CONFIG = config\n\n    return config\n</code></pre>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/formatters/","title":"formatters","text":"<p>\"\"\"</p>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters","title":"<code>prefect.logging.formatters</code>","text":"","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters.JsonFormatter","title":"<code>JsonFormatter</code>","text":"<p>               Bases: <code>Formatter</code></p> <p>Formats log records as a JSON string.</p> <p>The format may be specified as \"pretty\" to format the JSON with indents and newlines.</p> Source code in <code>prefect/logging/formatters.py</code> <pre><code>class JsonFormatter(logging.Formatter):\n    \"\"\"\n    Formats log records as a JSON string.\n\n    The format may be specified as \"pretty\" to format the JSON with indents and\n    newlines.\n    \"\"\"\n\n    def __init__(self, fmt, dmft, style) -&gt; None:  # noqa\n        super().__init__()\n\n        if fmt not in [\"pretty\", \"default\"]:\n            raise ValueError(\"Format must be either 'pretty' or 'default'.\")\n\n        self.serializer = JSONSerializer(\n            jsonlib=\"orjson\",\n            object_encoder=\"pydantic.json.pydantic_encoder\",\n            dumps_kwargs={\"option\": orjson.OPT_INDENT_2} if fmt == \"pretty\" else {},\n        )\n\n    def format(self, record: logging.LogRecord) -&gt; str:\n        record_dict = record.__dict__.copy()\n\n        # GCP severity detection compatibility\n        record_dict.setdefault(\"severity\", record.levelname)\n\n        # replace any exception tuples returned by `sys.exc_info()`\n        # with a JSON-serializable `dict`.\n        if record.exc_info:\n            record_dict[\"exc_info\"] = format_exception_info(record.exc_info)\n\n        log_json_bytes = self.serializer.dumps(record_dict)\n\n        # JSONSerializer returns bytes; decode to string to conform to\n        # the `logging.Formatter.format` interface\n        return log_json_bytes.decode()\n</code></pre>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters.PrefectFormatter","title":"<code>PrefectFormatter</code>","text":"<p>               Bases: <code>Formatter</code></p> Source code in <code>prefect/logging/formatters.py</code> <pre><code>class PrefectFormatter(logging.Formatter):\n    def __init__(\n        self,\n        format=None,\n        datefmt=None,\n        style=\"%\",\n        validate=True,\n        *,\n        defaults=None,\n        task_run_fmt: str = None,\n        flow_run_fmt: str = None,\n    ) -&gt; None:\n        \"\"\"\n        Implementation of the standard Python formatter with support for multiple\n        message formats.\n\n        \"\"\"\n        # See https://github.com/python/cpython/blob/c8c6113398ee9a7867fe9b08bc539cceb61e2aaa/Lib/logging/__init__.py#L546\n        # for implementation details\n\n        init_kwargs = {}\n        style_kwargs = {}\n\n        # defaults added in 3.10\n        if sys.version_info &gt;= (3, 10):\n            init_kwargs[\"defaults\"] = defaults\n            style_kwargs[\"defaults\"] = defaults\n\n        # validate added in 3.8\n        init_kwargs[\"validate\"] = validate\n\n        super().__init__(format, datefmt, style, **init_kwargs)\n\n        self.flow_run_fmt = flow_run_fmt\n        self.task_run_fmt = task_run_fmt\n\n        # Retrieve the style class from the base class to avoid importing private\n        # `_STYLES` mapping\n        style_class = type(self._style)\n\n        self._flow_run_style = (\n            style_class(flow_run_fmt, **style_kwargs) if flow_run_fmt else self._style\n        )\n        self._task_run_style = (\n            style_class(task_run_fmt, **style_kwargs) if task_run_fmt else self._style\n        )\n        if validate:\n            self._flow_run_style.validate()\n            self._task_run_style.validate()\n\n    def formatMessage(self, record: logging.LogRecord):\n        if record.name == \"prefect.flow_runs\":\n            style = self._flow_run_style\n        elif record.name == \"prefect.task_runs\":\n            style = self._task_run_style\n        else:\n            style = self._style\n\n        return style.format(record)\n</code></pre>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/handlers/","title":"handlers","text":"<p>\"\"\"</p>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers","title":"<code>prefect.logging.handlers</code>","text":"","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler","title":"<code>APILogHandler</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A logging handler that sends logs to the Prefect API.</p> <p>Sends log records to the <code>APILogWorker</code> which manages sending batches of logs in the background.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>class APILogHandler(logging.Handler):\n    \"\"\"\n    A logging handler that sends logs to the Prefect API.\n\n    Sends log records to the `APILogWorker` which manages sending batches of logs in\n    the background.\n    \"\"\"\n\n    @classmethod\n    def flush(cls):\n        \"\"\"\n        Tell the `APILogWorker` to send any currently enqueued logs and block until\n        completion.\n\n        Use `aflush` from async contexts instead.\n        \"\"\"\n        loop = get_running_loop()\n        if loop:\n            if in_global_loop():  # Guard against internal misuse\n                raise RuntimeError(\n                    \"Cannot call `APILogWorker.flush` from the global event loop; it\"\n                    \" would block the event loop and cause a deadlock. Use\"\n                    \" `APILogWorker.aflush` instead.\"\n                )\n\n            # Not ideal, but this method is called by the stdlib and cannot return a\n            # coroutine so we just schedule the drain in a new thread and continue\n            from_sync.call_soon_in_new_thread(create_call(APILogWorker.drain_all))\n            return None\n        else:\n            # We set a timeout of 5s because we don't want to block forever if the worker\n            # is stuck. This can occur when the handler is being shutdown and the\n            # `logging._lock` is held but the worker is attempting to emit logs resulting\n            # in a deadlock.\n            return APILogWorker.drain_all(timeout=5)\n\n    @classmethod\n    def aflush(cls):\n        \"\"\"\n        Tell the `APILogWorker` to send any currently enqueued logs and block until\n        completion.\n\n        If called in a synchronous context, will only block up to 5s before returning.\n        \"\"\"\n\n        if not get_running_loop():\n            raise RuntimeError(\n                \"`aflush` cannot be used from a synchronous context; use `flush`\"\n                \" instead.\"\n            )\n\n        return APILogWorker.drain_all()\n\n    def emit(self, record: logging.LogRecord):\n        \"\"\"\n        Send a log to the `APILogWorker`\n        \"\"\"\n        try:\n            profile = prefect.context.get_settings_context()\n\n            if not PREFECT_LOGGING_TO_API_ENABLED.value_from(profile.settings):\n                return  # Respect the global settings toggle\n            if not getattr(record, \"send_to_api\", True):\n                return  # Do not send records that have opted out\n            if not getattr(record, \"send_to_orion\", True):\n                return  # Backwards compatibility\n\n            log = self.prepare(record)\n            APILogWorker.instance().send(log)\n\n        except Exception:\n            self.handleError(record)\n\n    def handleError(self, record: logging.LogRecord) -&gt; None:\n        _, exc, _ = sys.exc_info()\n\n        if isinstance(exc, MissingContextError):\n            log_handling_when_missing_flow = (\n                PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW.value()\n            )\n            if log_handling_when_missing_flow == \"warn\":\n                # Warn when a logger is used outside of a run context, the stack level here\n                # gets us to the user logging call\n                warnings.warn(str(exc), stacklevel=8)\n                return\n            elif log_handling_when_missing_flow == \"ignore\":\n                return\n            else:\n                raise exc\n\n        # Display a longer traceback for other errors\n        return super().handleError(record)\n\n    def prepare(self, record: logging.LogRecord) -&gt; Dict[str, Any]:\n        \"\"\"\n        Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.\n\n        This infers the linked flow or task run from the log record or the current\n        run context.\n\n        If a flow run id cannot be found, the log will be dropped.\n\n        Logs exceeding the maximum size will be dropped.\n        \"\"\"\n        flow_run_id = getattr(record, \"flow_run_id\", None)\n        task_run_id = getattr(record, \"task_run_id\", None)\n\n        if not flow_run_id:\n            try:\n                context = prefect.context.get_run_context()\n            except MissingContextError:\n                raise MissingContextError(\n                    f\"Logger {record.name!r} attempted to send logs to the API without\"\n                    \" a flow run id. The API log handler can only send logs within\"\n                    \" flow run contexts unless the flow run id is manually provided.\"\n                ) from None\n\n            if hasattr(context, \"flow_run\"):\n                flow_run_id = context.flow_run.id\n            elif hasattr(context, \"task_run\"):\n                flow_run_id = context.task_run.flow_run_id\n                task_run_id = task_run_id or context.task_run.id\n            else:\n                raise ValueError(\n                    \"Encountered malformed run context. Does not contain flow or task \"\n                    \"run information.\"\n                )\n\n        # Parsing to a `LogCreate` object here gives us nice parsing error messages\n        # from the standard lib `handleError` method if something goes wrong and\n        # prevents malformed logs from entering the queue\n        try:\n            is_uuid_like = isinstance(flow_run_id, uuid.UUID) or (\n                isinstance(flow_run_id, str) and uuid.UUID(flow_run_id)\n            )\n        except ValueError:\n            is_uuid_like = False\n\n        log = LogCreate(\n            flow_run_id=flow_run_id if is_uuid_like else None,\n            task_run_id=task_run_id,\n            name=record.name,\n            level=record.levelno,\n            timestamp=pendulum.from_timestamp(\n                getattr(record, \"created\", None) or time.time()\n            ),\n            message=self.format(record),\n        ).dict(json_compatible=True)\n\n        log_size = log[\"__payload_size__\"] = self._get_payload_size(log)\n        if log_size &gt; PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value():\n            raise ValueError(\n                f\"Log of size {log_size} is greater than the max size of \"\n                f\"{PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value()}\"\n            )\n\n        return log\n\n    def _get_payload_size(self, log: Dict[str, Any]) -&gt; int:\n        return len(json.dumps(log).encode())\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.aflush","title":"<code>aflush</code>  <code>classmethod</code>","text":"<p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until completion.</p> <p>If called in a synchronous context, will only block up to 5s before returning.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>@classmethod\ndef aflush(cls):\n    \"\"\"\n    Tell the `APILogWorker` to send any currently enqueued logs and block until\n    completion.\n\n    If called in a synchronous context, will only block up to 5s before returning.\n    \"\"\"\n\n    if not get_running_loop():\n        raise RuntimeError(\n            \"`aflush` cannot be used from a synchronous context; use `flush`\"\n            \" instead.\"\n        )\n\n    return APILogWorker.drain_all()\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.emit","title":"<code>emit</code>","text":"<p>Send a log to the <code>APILogWorker</code></p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>def emit(self, record: logging.LogRecord):\n    \"\"\"\n    Send a log to the `APILogWorker`\n    \"\"\"\n    try:\n        profile = prefect.context.get_settings_context()\n\n        if not PREFECT_LOGGING_TO_API_ENABLED.value_from(profile.settings):\n            return  # Respect the global settings toggle\n        if not getattr(record, \"send_to_api\", True):\n            return  # Do not send records that have opted out\n        if not getattr(record, \"send_to_orion\", True):\n            return  # Backwards compatibility\n\n        log = self.prepare(record)\n        APILogWorker.instance().send(log)\n\n    except Exception:\n        self.handleError(record)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.flush","title":"<code>flush</code>  <code>classmethod</code>","text":"<p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until completion.</p> <p>Use <code>aflush</code> from async contexts instead.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>@classmethod\ndef flush(cls):\n    \"\"\"\n    Tell the `APILogWorker` to send any currently enqueued logs and block until\n    completion.\n\n    Use `aflush` from async contexts instead.\n    \"\"\"\n    loop = get_running_loop()\n    if loop:\n        if in_global_loop():  # Guard against internal misuse\n            raise RuntimeError(\n                \"Cannot call `APILogWorker.flush` from the global event loop; it\"\n                \" would block the event loop and cause a deadlock. Use\"\n                \" `APILogWorker.aflush` instead.\"\n            )\n\n        # Not ideal, but this method is called by the stdlib and cannot return a\n        # coroutine so we just schedule the drain in a new thread and continue\n        from_sync.call_soon_in_new_thread(create_call(APILogWorker.drain_all))\n        return None\n    else:\n        # We set a timeout of 5s because we don't want to block forever if the worker\n        # is stuck. This can occur when the handler is being shutdown and the\n        # `logging._lock` is held but the worker is attempting to emit logs resulting\n        # in a deadlock.\n        return APILogWorker.drain_all(timeout=5)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.prepare","title":"<code>prepare</code>","text":"<p>Convert a <code>logging.LogRecord</code> to the API <code>LogCreate</code> schema and serialize.</p> <p>This infers the linked flow or task run from the log record or the current run context.</p> <p>If a flow run id cannot be found, the log will be dropped.</p> <p>Logs exceeding the maximum size will be dropped.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>def prepare(self, record: logging.LogRecord) -&gt; Dict[str, Any]:\n    \"\"\"\n    Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.\n\n    This infers the linked flow or task run from the log record or the current\n    run context.\n\n    If a flow run id cannot be found, the log will be dropped.\n\n    Logs exceeding the maximum size will be dropped.\n    \"\"\"\n    flow_run_id = getattr(record, \"flow_run_id\", None)\n    task_run_id = getattr(record, \"task_run_id\", None)\n\n    if not flow_run_id:\n        try:\n            context = prefect.context.get_run_context()\n        except MissingContextError:\n            raise MissingContextError(\n                f\"Logger {record.name!r} attempted to send logs to the API without\"\n                \" a flow run id. The API log handler can only send logs within\"\n                \" flow run contexts unless the flow run id is manually provided.\"\n            ) from None\n\n        if hasattr(context, \"flow_run\"):\n            flow_run_id = context.flow_run.id\n        elif hasattr(context, \"task_run\"):\n            flow_run_id = context.task_run.flow_run_id\n            task_run_id = task_run_id or context.task_run.id\n        else:\n            raise ValueError(\n                \"Encountered malformed run context. Does not contain flow or task \"\n                \"run information.\"\n            )\n\n    # Parsing to a `LogCreate` object here gives us nice parsing error messages\n    # from the standard lib `handleError` method if something goes wrong and\n    # prevents malformed logs from entering the queue\n    try:\n        is_uuid_like = isinstance(flow_run_id, uuid.UUID) or (\n            isinstance(flow_run_id, str) and uuid.UUID(flow_run_id)\n        )\n    except ValueError:\n        is_uuid_like = False\n\n    log = LogCreate(\n        flow_run_id=flow_run_id if is_uuid_like else None,\n        task_run_id=task_run_id,\n        name=record.name,\n        level=record.levelno,\n        timestamp=pendulum.from_timestamp(\n            getattr(record, \"created\", None) or time.time()\n        ),\n        message=self.format(record),\n    ).dict(json_compatible=True)\n\n    log_size = log[\"__payload_size__\"] = self._get_payload_size(log)\n    if log_size &gt; PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value():\n        raise ValueError(\n            f\"Log of size {log_size} is greater than the max size of \"\n            f\"{PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value()}\"\n        )\n\n    return log\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.PrefectConsoleHandler","title":"<code>PrefectConsoleHandler</code>","text":"<p>               Bases: <code>StreamHandler</code></p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>class PrefectConsoleHandler(logging.StreamHandler):\n    def __init__(\n        self,\n        stream=None,\n        highlighter: Highlighter = PrefectConsoleHighlighter,\n        styles: Dict[str, str] = None,\n        level: Union[int, str] = logging.NOTSET,\n    ):\n        \"\"\"\n        The default console handler for Prefect, which highlights log levels,\n        web and file URLs, flow and task (run) names, and state types in the\n        local console (terminal).\n\n        Highlighting can be toggled on/off with the PREFECT_LOGGING_COLORS setting.\n        For finer control, use logging.yml to add or remove styles, and/or\n        adjust colors.\n        \"\"\"\n        super().__init__(stream=stream)\n\n        styled_console = PREFECT_LOGGING_COLORS.value()\n        markup_console = PREFECT_LOGGING_MARKUP.value()\n        if styled_console:\n            highlighter = highlighter()\n            theme = Theme(styles, inherit=False)\n        else:\n            highlighter = NullHighlighter()\n            theme = Theme(inherit=False)\n\n        self.level = level\n        self.console = Console(\n            highlighter=highlighter,\n            theme=theme,\n            file=self.stream,\n            markup=markup_console,\n        )\n\n    def emit(self, record: logging.LogRecord):\n        try:\n            message = self.format(record)\n            self.console.print(message, soft_wrap=True)\n        except RecursionError:\n            # This was copied over from logging.StreamHandler().emit()\n            # https://bugs.python.org/issue36272\n            raise\n        except Exception:\n            self.handleError(record)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/highlighters/","title":"highlighters","text":"<p>\"\"\"</p>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers","title":"<code>prefect.logging.loggers</code>","text":"","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper","title":"<code>LogEavesdropper</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A context manager that collects logs for the duration of the context</p> <pre><code>Example:\n\n    ```python\n    import logging\n    from prefect.logging import LogEavesdropper\n\n    with LogEavesdropper(\"my_logger\") as eavesdropper:\n        logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n        logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n    print(eavesdropper.text())\n\n    # Outputs: \"Hello, world!\n</code></pre> <p>Another one!\"</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class LogEavesdropper(logging.Handler):\n    \"\"\"A context manager that collects logs for the duration of the context\n\n    Example:\n\n        ```python\n        import logging\n        from prefect.logging import LogEavesdropper\n\n        with LogEavesdropper(\"my_logger\") as eavesdropper:\n            logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n            logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n        print(eavesdropper.text())\n\n        # Outputs: \"Hello, world!\\nAnother one!\"\n    \"\"\"\n\n    _target_logger: logging.Logger\n    _lines: List[str]\n\n    def __init__(self, eavesdrop_on: str, level: int = logging.NOTSET):\n        \"\"\"\n        Args:\n            eavesdrop_on (str): the name of the logger to eavesdrop on\n            level (int): the minimum log level to eavesdrop on; if omitted, all levels\n                are captured\n        \"\"\"\n\n        super().__init__(level=level)\n        self.eavesdrop_on = eavesdrop_on\n        self._target_logger = None\n\n        # It's important that we use a very minimalistic formatter for use cases where\n        # we may present these logs back to the user.  We shouldn't leak filenames,\n        # versions, or other environmental information.\n        self.formatter = logging.Formatter(\"[%(levelname)s]: %(message)s\")\n\n    def __enter__(self) -&gt; Self:\n        self._target_logger = logging.getLogger(self.eavesdrop_on)\n        self._original_level = self._target_logger.level\n        self._target_logger.level = self.level\n        self._target_logger.addHandler(self)\n        self._lines = []\n        return self\n\n    def __exit__(self, *_):\n        if self._target_logger:\n            self._target_logger.removeHandler(self)\n            self._target_logger.level = self._original_level\n\n    def emit(self, record: LogRecord) -&gt; None:\n        \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n        self._lines.append(self.format(record))\n\n    def text(self) -&gt; str:\n        \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n        return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper.emit","title":"<code>emit</code>","text":"<p>The logging.Handler implementation, not intended to be called directly.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def emit(self, record: LogRecord) -&gt; None:\n    \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n    self._lines.append(self.format(record))\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper.text","title":"<code>text</code>","text":"<p>Return the collected logs as a single newline-delimited string</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def text(self) -&gt; str:\n    \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n    return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.PrefectLogAdapter","title":"<code>PrefectLogAdapter</code>","text":"<p>               Bases: <code>LoggerAdapter</code></p> <p>Adapter that ensures extra kwargs are passed through correctly; without this the <code>extra</code> fields set on the adapter would overshadow any provided on a log-by-log basis.</p> <p>See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is not a bug in the LoggingAdapter and subclassing is the intended workaround.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class PrefectLogAdapter(logging.LoggerAdapter):\n    \"\"\"\n    Adapter that ensures extra kwargs are passed through correctly; without this\n    the `extra` fields set on the adapter would overshadow any provided on a\n    log-by-log basis.\n\n    See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is\n    not a bug in the LoggingAdapter and subclassing is the intended workaround.\n    \"\"\"\n\n    def process(self, msg, kwargs):\n        kwargs[\"extra\"] = {**(self.extra or {}), **(kwargs.get(\"extra\") or {})}\n\n        from prefect._internal.compatibility.deprecated import (\n            PrefectDeprecationWarning,\n            generate_deprecation_message,\n        )\n\n        if \"send_to_orion\" in kwargs[\"extra\"]:\n            warnings.warn(\n                generate_deprecation_message(\n                    'The \"send_to_orion\" option',\n                    start_date=\"May 2023\",\n                    help='Use \"send_to_api\" instead.',\n                ),\n                PrefectDeprecationWarning,\n                stacklevel=4,\n            )\n\n        return (msg, kwargs)\n\n    def getChild(\n        self, suffix: str, extra: Optional[Dict[str, str]] = None\n    ) -&gt; \"PrefectLogAdapter\":\n        if extra is None:\n            extra = {}\n\n        return PrefectLogAdapter(\n            self.logger.getChild(suffix),\n            extra={\n                **self.extra,\n                **extra,\n            },\n        )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.disable_logger","title":"<code>disable_logger</code>","text":"<p>Get a logger by name and disables it within the context manager. Upon exiting the context manager, the logger is returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_logger(name: str):\n    \"\"\"\n    Get a logger by name and disables it within the context manager.\n    Upon exiting the context manager, the logger is returned to its\n    original state.\n    \"\"\"\n    logger = logging.getLogger(name=name)\n\n    # determine if it's already disabled\n    base_state = logger.disabled\n    try:\n        # disable the logger\n        logger.disabled = True\n        yield\n    finally:\n        # return to base state\n        logger.disabled = base_state\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.disable_run_logger","title":"<code>disable_run_logger</code>","text":"<p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them within the context manager. Upon exiting the context manager, both loggers are returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_run_logger():\n    \"\"\"\n    Gets both `prefect.flow_run` and `prefect.task_run` and disables them\n    within the context manager. Upon exiting the context manager, both loggers\n    are returned to its original state.\n    \"\"\"\n    with disable_logger(\"prefect.flow_run\"), disable_logger(\"prefect.task_run\"):\n        yield\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.flow_run_logger","title":"<code>flow_run_logger</code>","text":"<p>Create a flow run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def flow_run_logger(\n    flow_run: Union[\"FlowRun\", \"ClientFlowRun\"],\n    flow: Optional[\"Flow\"] = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a flow run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the flow run context is available, see `get_run_logger` instead.\n    \"\"\"\n    return PrefectLogAdapter(\n        get_logger(\"prefect.flow_runs\"),\n        extra={\n            **{\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_run_id\": str(flow_run.id) if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.get_logger","title":"<code>get_logger</code>  <code>cached</code>","text":"<p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the <code>prefect</code> package.</p> <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs. By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@lru_cache()\ndef get_logger(name: str = None) -&gt; logging.Logger:\n    \"\"\"\n    Get a `prefect` logger. These loggers are intended for internal use within the\n    `prefect` package.\n\n    See `get_run_logger` for retrieving loggers for use within task or flow runs.\n    By default, only run-related loggers are connected to the `APILogHandler`.\n    \"\"\"\n    parent_logger = logging.getLogger(\"prefect\")\n\n    if name:\n        # Append the name if given but allow explicit full names e.g. \"prefect.test\"\n        # should not become \"prefect.prefect.test\"\n        if not name.startswith(parent_logger.name + \".\"):\n            logger = parent_logger.getChild(name)\n        else:\n            logger = logging.getLogger(name)\n    else:\n        logger = parent_logger\n\n    # Prevent the current API key from being logged in plain text\n    obfuscate_api_key_filter = ObfuscateApiKeyFilter()\n    logger.addFilter(obfuscate_api_key_filter)\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.get_run_logger","title":"<code>get_run_logger</code>","text":"<p>Get a Prefect logger for the current task run or flow run.</p> <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>. Contextual data about the run will be attached to the log records.</p> <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to the API.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>RunContext</code> <p>A specific context may be provided as an override. By default, the context is inferred from global state and this should not be needed.</p> <code>None</code> <code>**kwargs</code> <code>str</code> <p>Additional keyword arguments will be attached to the log records in addition to the run metadata</p> <code>{}</code> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no context can be found</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def get_run_logger(\n    context: \"RunContext\" = None, **kwargs: str\n) -&gt; Union[logging.Logger, logging.LoggerAdapter]:\n    \"\"\"\n    Get a Prefect logger for the current task run or flow run.\n\n    The logger will be named either `prefect.task_runs` or `prefect.flow_runs`.\n    Contextual data about the run will be attached to the log records.\n\n    These loggers are connected to the `APILogHandler` by default to send log records to\n    the API.\n\n    Arguments:\n        context: A specific context may be provided as an override. By default, the\n            context is inferred from global state and this should not be needed.\n        **kwargs: Additional keyword arguments will be attached to the log records in\n            addition to the run metadata\n\n    Raises:\n        RuntimeError: If no context can be found\n    \"\"\"\n    # Check for existing contexts\n    task_run_context = prefect.context.TaskRunContext.get()\n    flow_run_context = prefect.context.FlowRunContext.get()\n\n    # Apply the context override\n    if context:\n        if isinstance(context, prefect.context.FlowRunContext):\n            flow_run_context = context\n        elif isinstance(context, prefect.context.TaskRunContext):\n            task_run_context = context\n        else:\n            raise TypeError(\n                f\"Received unexpected type {type(context).__name__!r} for context. \"\n                \"Expected one of 'None', 'FlowRunContext', or 'TaskRunContext'.\"\n            )\n\n    # Determine if this is a task or flow run logger\n    if task_run_context:\n        logger = task_run_logger(\n            task_run=task_run_context.task_run,\n            task=task_run_context.task,\n            flow_run=flow_run_context.flow_run if flow_run_context else None,\n            flow=flow_run_context.flow if flow_run_context else None,\n            **kwargs,\n        )\n    elif flow_run_context:\n        logger = flow_run_logger(\n            flow_run=flow_run_context.flow_run, flow=flow_run_context.flow, **kwargs\n        )\n    elif (\n        get_logger(\"prefect.flow_run\").disabled\n        and get_logger(\"prefect.task_run\").disabled\n    ):\n        logger = logging.getLogger(\"null\")\n    else:\n        raise MissingContextError(\"There is no active flow or task run context.\")\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.patch_print","title":"<code>patch_print</code>","text":"<p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef patch_print():\n    \"\"\"\n    Patches the Python builtin `print` method to use `print_as_log`\n    \"\"\"\n    import builtins\n\n    original = builtins.print\n\n    try:\n        builtins.print = print_as_log\n        yield\n    finally:\n        builtins.print = original\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.print_as_log","title":"<code>print_as_log</code>","text":"<p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p> <p>If no run is active, <code>print</code> will behave as if it were not patched.</p> <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will not be forwarded to the Prefect logger either.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def print_as_log(*args, **kwargs):\n    \"\"\"\n    A patch for `print` to send printed messages to the Prefect run logger.\n\n    If no run is active, `print` will behave as if it were not patched.\n\n    If `print` sends data to a file other than `sys.stdout` or `sys.stderr`, it will\n    not be forwarded to the Prefect logger either.\n    \"\"\"\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    context = TaskRunContext.get() or FlowRunContext.get()\n    if (\n        not context\n        or not context.log_prints\n        or kwargs.get(\"file\") not in {None, sys.stdout, sys.stderr}\n    ):\n        return print(*args, **kwargs)\n\n    logger = get_run_logger()\n\n    # Print to an in-memory buffer; so we do not need to implement `print`\n    buffer = io.StringIO()\n    kwargs[\"file\"] = buffer\n    print(*args, **kwargs)\n\n    # Remove trailing whitespace to prevent duplicates\n    logger.info(buffer.getvalue().rstrip())\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.task_run_logger","title":"<code>task_run_logger</code>","text":"<p>Create a task run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the task run context is available, see <code>get_run_logger</code> instead.</p> <p>If only the flow run context is available, it will be used for default values of <code>flow_run</code> and <code>flow</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def task_run_logger(\n    task_run: \"TaskRun\",\n    task: \"Task\" = None,\n    flow_run: \"FlowRun\" = None,\n    flow: \"Flow\" = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a task run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the task run context is available, see `get_run_logger` instead.\n\n    If only the flow run context is available, it will be used for default values\n    of `flow_run` and `flow`.\n    \"\"\"\n    if not flow_run or not flow:\n        flow_run_context = prefect.context.FlowRunContext.get()\n        if flow_run_context:\n            flow_run = flow_run or flow_run_context.flow_run\n            flow = flow or flow_run_context.flow\n\n    return PrefectLogAdapter(\n        get_logger(\"prefect.task_runs\"),\n        extra={\n            **{\n                \"task_run_id\": str(task_run.id),\n                \"flow_run_id\": str(task_run.flow_run_id),\n                \"task_run_name\": task_run.name,\n                \"task_name\": task.name if task else \"&lt;unknown&gt;\",\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/","title":"loggers","text":"<p>\"\"\"</p>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers","title":"<code>prefect.logging.loggers</code>","text":"","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper","title":"<code>LogEavesdropper</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A context manager that collects logs for the duration of the context</p> <pre><code>Example:\n\n    ```python\n    import logging\n    from prefect.logging import LogEavesdropper\n\n    with LogEavesdropper(\"my_logger\") as eavesdropper:\n        logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n        logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n    print(eavesdropper.text())\n\n    # Outputs: \"Hello, world!\n</code></pre> <p>Another one!\"</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class LogEavesdropper(logging.Handler):\n    \"\"\"A context manager that collects logs for the duration of the context\n\n    Example:\n\n        ```python\n        import logging\n        from prefect.logging import LogEavesdropper\n\n        with LogEavesdropper(\"my_logger\") as eavesdropper:\n            logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n            logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n        print(eavesdropper.text())\n\n        # Outputs: \"Hello, world!\\nAnother one!\"\n    \"\"\"\n\n    _target_logger: logging.Logger\n    _lines: List[str]\n\n    def __init__(self, eavesdrop_on: str, level: int = logging.NOTSET):\n        \"\"\"\n        Args:\n            eavesdrop_on (str): the name of the logger to eavesdrop on\n            level (int): the minimum log level to eavesdrop on; if omitted, all levels\n                are captured\n        \"\"\"\n\n        super().__init__(level=level)\n        self.eavesdrop_on = eavesdrop_on\n        self._target_logger = None\n\n        # It's important that we use a very minimalistic formatter for use cases where\n        # we may present these logs back to the user.  We shouldn't leak filenames,\n        # versions, or other environmental information.\n        self.formatter = logging.Formatter(\"[%(levelname)s]: %(message)s\")\n\n    def __enter__(self) -&gt; Self:\n        self._target_logger = logging.getLogger(self.eavesdrop_on)\n        self._original_level = self._target_logger.level\n        self._target_logger.level = self.level\n        self._target_logger.addHandler(self)\n        self._lines = []\n        return self\n\n    def __exit__(self, *_):\n        if self._target_logger:\n            self._target_logger.removeHandler(self)\n            self._target_logger.level = self._original_level\n\n    def emit(self, record: LogRecord) -&gt; None:\n        \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n        self._lines.append(self.format(record))\n\n    def text(self) -&gt; str:\n        \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n        return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper.emit","title":"<code>emit</code>","text":"<p>The logging.Handler implementation, not intended to be called directly.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def emit(self, record: LogRecord) -&gt; None:\n    \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n    self._lines.append(self.format(record))\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper.text","title":"<code>text</code>","text":"<p>Return the collected logs as a single newline-delimited string</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def text(self) -&gt; str:\n    \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n    return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.PrefectLogAdapter","title":"<code>PrefectLogAdapter</code>","text":"<p>               Bases: <code>LoggerAdapter</code></p> <p>Adapter that ensures extra kwargs are passed through correctly; without this the <code>extra</code> fields set on the adapter would overshadow any provided on a log-by-log basis.</p> <p>See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is not a bug in the LoggingAdapter and subclassing is the intended workaround.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class PrefectLogAdapter(logging.LoggerAdapter):\n    \"\"\"\n    Adapter that ensures extra kwargs are passed through correctly; without this\n    the `extra` fields set on the adapter would overshadow any provided on a\n    log-by-log basis.\n\n    See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is\n    not a bug in the LoggingAdapter and subclassing is the intended workaround.\n    \"\"\"\n\n    def process(self, msg, kwargs):\n        kwargs[\"extra\"] = {**(self.extra or {}), **(kwargs.get(\"extra\") or {})}\n\n        from prefect._internal.compatibility.deprecated import (\n            PrefectDeprecationWarning,\n            generate_deprecation_message,\n        )\n\n        if \"send_to_orion\" in kwargs[\"extra\"]:\n            warnings.warn(\n                generate_deprecation_message(\n                    'The \"send_to_orion\" option',\n                    start_date=\"May 2023\",\n                    help='Use \"send_to_api\" instead.',\n                ),\n                PrefectDeprecationWarning,\n                stacklevel=4,\n            )\n\n        return (msg, kwargs)\n\n    def getChild(\n        self, suffix: str, extra: Optional[Dict[str, str]] = None\n    ) -&gt; \"PrefectLogAdapter\":\n        if extra is None:\n            extra = {}\n\n        return PrefectLogAdapter(\n            self.logger.getChild(suffix),\n            extra={\n                **self.extra,\n                **extra,\n            },\n        )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.disable_logger","title":"<code>disable_logger</code>","text":"<p>Get a logger by name and disables it within the context manager. Upon exiting the context manager, the logger is returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_logger(name: str):\n    \"\"\"\n    Get a logger by name and disables it within the context manager.\n    Upon exiting the context manager, the logger is returned to its\n    original state.\n    \"\"\"\n    logger = logging.getLogger(name=name)\n\n    # determine if it's already disabled\n    base_state = logger.disabled\n    try:\n        # disable the logger\n        logger.disabled = True\n        yield\n    finally:\n        # return to base state\n        logger.disabled = base_state\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.disable_run_logger","title":"<code>disable_run_logger</code>","text":"<p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them within the context manager. Upon exiting the context manager, both loggers are returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_run_logger():\n    \"\"\"\n    Gets both `prefect.flow_run` and `prefect.task_run` and disables them\n    within the context manager. Upon exiting the context manager, both loggers\n    are returned to its original state.\n    \"\"\"\n    with disable_logger(\"prefect.flow_run\"), disable_logger(\"prefect.task_run\"):\n        yield\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.flow_run_logger","title":"<code>flow_run_logger</code>","text":"<p>Create a flow run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def flow_run_logger(\n    flow_run: Union[\"FlowRun\", \"ClientFlowRun\"],\n    flow: Optional[\"Flow\"] = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a flow run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the flow run context is available, see `get_run_logger` instead.\n    \"\"\"\n    return PrefectLogAdapter(\n        get_logger(\"prefect.flow_runs\"),\n        extra={\n            **{\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_run_id\": str(flow_run.id) if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.get_logger","title":"<code>get_logger</code>  <code>cached</code>","text":"<p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the <code>prefect</code> package.</p> <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs. By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@lru_cache()\ndef get_logger(name: str = None) -&gt; logging.Logger:\n    \"\"\"\n    Get a `prefect` logger. These loggers are intended for internal use within the\n    `prefect` package.\n\n    See `get_run_logger` for retrieving loggers for use within task or flow runs.\n    By default, only run-related loggers are connected to the `APILogHandler`.\n    \"\"\"\n    parent_logger = logging.getLogger(\"prefect\")\n\n    if name:\n        # Append the name if given but allow explicit full names e.g. \"prefect.test\"\n        # should not become \"prefect.prefect.test\"\n        if not name.startswith(parent_logger.name + \".\"):\n            logger = parent_logger.getChild(name)\n        else:\n            logger = logging.getLogger(name)\n    else:\n        logger = parent_logger\n\n    # Prevent the current API key from being logged in plain text\n    obfuscate_api_key_filter = ObfuscateApiKeyFilter()\n    logger.addFilter(obfuscate_api_key_filter)\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.get_run_logger","title":"<code>get_run_logger</code>","text":"<p>Get a Prefect logger for the current task run or flow run.</p> <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>. Contextual data about the run will be attached to the log records.</p> <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to the API.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>RunContext</code> <p>A specific context may be provided as an override. By default, the context is inferred from global state and this should not be needed.</p> <code>None</code> <code>**kwargs</code> <code>str</code> <p>Additional keyword arguments will be attached to the log records in addition to the run metadata</p> <code>{}</code> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no context can be found</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def get_run_logger(\n    context: \"RunContext\" = None, **kwargs: str\n) -&gt; Union[logging.Logger, logging.LoggerAdapter]:\n    \"\"\"\n    Get a Prefect logger for the current task run or flow run.\n\n    The logger will be named either `prefect.task_runs` or `prefect.flow_runs`.\n    Contextual data about the run will be attached to the log records.\n\n    These loggers are connected to the `APILogHandler` by default to send log records to\n    the API.\n\n    Arguments:\n        context: A specific context may be provided as an override. By default, the\n            context is inferred from global state and this should not be needed.\n        **kwargs: Additional keyword arguments will be attached to the log records in\n            addition to the run metadata\n\n    Raises:\n        RuntimeError: If no context can be found\n    \"\"\"\n    # Check for existing contexts\n    task_run_context = prefect.context.TaskRunContext.get()\n    flow_run_context = prefect.context.FlowRunContext.get()\n\n    # Apply the context override\n    if context:\n        if isinstance(context, prefect.context.FlowRunContext):\n            flow_run_context = context\n        elif isinstance(context, prefect.context.TaskRunContext):\n            task_run_context = context\n        else:\n            raise TypeError(\n                f\"Received unexpected type {type(context).__name__!r} for context. \"\n                \"Expected one of 'None', 'FlowRunContext', or 'TaskRunContext'.\"\n            )\n\n    # Determine if this is a task or flow run logger\n    if task_run_context:\n        logger = task_run_logger(\n            task_run=task_run_context.task_run,\n            task=task_run_context.task,\n            flow_run=flow_run_context.flow_run if flow_run_context else None,\n            flow=flow_run_context.flow if flow_run_context else None,\n            **kwargs,\n        )\n    elif flow_run_context:\n        logger = flow_run_logger(\n            flow_run=flow_run_context.flow_run, flow=flow_run_context.flow, **kwargs\n        )\n    elif (\n        get_logger(\"prefect.flow_run\").disabled\n        and get_logger(\"prefect.task_run\").disabled\n    ):\n        logger = logging.getLogger(\"null\")\n    else:\n        raise MissingContextError(\"There is no active flow or task run context.\")\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.patch_print","title":"<code>patch_print</code>","text":"<p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef patch_print():\n    \"\"\"\n    Patches the Python builtin `print` method to use `print_as_log`\n    \"\"\"\n    import builtins\n\n    original = builtins.print\n\n    try:\n        builtins.print = print_as_log\n        yield\n    finally:\n        builtins.print = original\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.print_as_log","title":"<code>print_as_log</code>","text":"<p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p> <p>If no run is active, <code>print</code> will behave as if it were not patched.</p> <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will not be forwarded to the Prefect logger either.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def print_as_log(*args, **kwargs):\n    \"\"\"\n    A patch for `print` to send printed messages to the Prefect run logger.\n\n    If no run is active, `print` will behave as if it were not patched.\n\n    If `print` sends data to a file other than `sys.stdout` or `sys.stderr`, it will\n    not be forwarded to the Prefect logger either.\n    \"\"\"\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    context = TaskRunContext.get() or FlowRunContext.get()\n    if (\n        not context\n        or not context.log_prints\n        or kwargs.get(\"file\") not in {None, sys.stdout, sys.stderr}\n    ):\n        return print(*args, **kwargs)\n\n    logger = get_run_logger()\n\n    # Print to an in-memory buffer; so we do not need to implement `print`\n    buffer = io.StringIO()\n    kwargs[\"file\"] = buffer\n    print(*args, **kwargs)\n\n    # Remove trailing whitespace to prevent duplicates\n    logger.info(buffer.getvalue().rstrip())\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.task_run_logger","title":"<code>task_run_logger</code>","text":"<p>Create a task run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the task run context is available, see <code>get_run_logger</code> instead.</p> <p>If only the flow run context is available, it will be used for default values of <code>flow_run</code> and <code>flow</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def task_run_logger(\n    task_run: \"TaskRun\",\n    task: \"Task\" = None,\n    flow_run: \"FlowRun\" = None,\n    flow: \"Flow\" = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a task run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the task run context is available, see `get_run_logger` instead.\n\n    If only the flow run context is available, it will be used for default values\n    of `flow_run` and `flow`.\n    \"\"\"\n    if not flow_run or not flow:\n        flow_run_context = prefect.context.FlowRunContext.get()\n        if flow_run_context:\n            flow_run = flow_run or flow_run_context.flow_run\n            flow = flow or flow_run_context.flow\n\n    return PrefectLogAdapter(\n        get_logger(\"prefect.task_runs\"),\n        extra={\n            **{\n                \"task_run_id\": str(task_run.id),\n                \"flow_run_id\": str(task_run.flow_run_id),\n                \"task_run_name\": task_run.name,\n                \"task_name\": task.name if task else \"&lt;unknown&gt;\",\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/runner/runner/","title":"runner","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner","title":"<code>prefect.runner.runner</code>","text":"<p>Runners are responsible for managing the execution of deployments created and managed by either <code>flow.serve</code> or the <code>serve</code> utility.</p> Example <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n\n    # serve generates a Runner instance\n    serve(slow_deploy, fast_deploy)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner","title":"<code>Runner</code>","text":"Source code in <code>prefect/runner/runner.py</code> <pre><code>class Runner:\n    def __init__(\n        self,\n        name: Optional[str] = None,\n        query_seconds: Optional[float] = None,\n        prefetch_seconds: float = 10,\n        limit: Optional[int] = None,\n        pause_on_shutdown: bool = True,\n        webserver: bool = False,\n    ):\n        \"\"\"\n        Responsible for managing the execution of remotely initiated flow runs.\n\n        Args:\n            name: The name of the runner. If not provided, a random one\n                will be generated. If provided, it cannot contain '/' or '%'.\n            query_seconds: The number of seconds to wait between querying for\n                scheduled flow runs; defaults to `PREFECT_RUNNER_POLL_FREQUENCY`\n            prefetch_seconds: The number of seconds to prefetch flow runs for.\n            limit: The maximum number of flow runs this runner should be running at\n            pause_on_shutdown: A boolean for whether or not to automatically pause\n                deployment schedules on shutdown; defaults to `True`\n            webserver: a boolean flag for whether to start a webserver for this runner\n\n        Examples:\n            Set up a Runner to manage the execute of scheduled flow runs for two flows:\n                ```python\n                from prefect import flow, Runner\n\n                @flow\n                def hello_flow(name):\n                    print(f\"hello {name}\")\n\n                @flow\n                def goodbye_flow(name):\n                    print(f\"goodbye {name}\")\n\n                if __name__ == \"__main__\"\n                    runner = Runner(name=\"my-runner\")\n\n                    # Will be runnable via the API\n                    runner.add_flow(hello_flow)\n\n                    # Run on a cron schedule\n                    runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n                    runner.start()\n                ```\n        \"\"\"\n        if name and (\"/\" in name or \"%\" in name):\n            raise ValueError(\"Runner name cannot contain '/' or '%'\")\n        self.name = Path(name).stem if name is not None else f\"runner-{uuid4()}\"\n        self._logger = get_logger(\"runner\")\n\n        self.started = False\n        self.stopping = False\n        self.pause_on_shutdown = pause_on_shutdown\n        self.limit = limit or PREFECT_RUNNER_PROCESS_LIMIT.value()\n        self.webserver = webserver\n\n        self.query_seconds = query_seconds or PREFECT_RUNNER_POLL_FREQUENCY.value()\n        self._prefetch_seconds = prefetch_seconds\n\n        self._runs_task_group: anyio.abc.TaskGroup = anyio.create_task_group()\n        self._loops_task_group: anyio.abc.TaskGroup = anyio.create_task_group()\n\n        self._limiter: Optional[anyio.CapacityLimiter] = anyio.CapacityLimiter(\n            self.limit\n        )\n        self._client = get_client()\n        self._submitting_flow_run_ids = set()\n        self._cancelling_flow_run_ids = set()\n        self._scheduled_task_scopes = set()\n        self._deployment_ids: Set[UUID] = set()\n        self._flow_run_process_map = dict()\n\n        self._tmp_dir: Path = (\n            Path(tempfile.gettempdir()) / \"runner_storage\" / str(uuid4())\n        )\n        self._storage_objs: List[RunnerStorage] = []\n        self._deployment_storage_map: Dict[UUID, RunnerStorage] = {}\n        self._loop = asyncio.get_event_loop()\n\n    @sync_compatible\n    async def add_deployment(\n        self,\n        deployment: RunnerDeployment,\n    ) -&gt; UUID:\n        \"\"\"\n        Registers the deployment with the Prefect API and will monitor for work once\n        the runner is started.\n\n        Args:\n            deployment: A deployment for the runner to register.\n        \"\"\"\n        deployment_id = await deployment.apply()\n        storage = deployment.storage\n        if storage is not None:\n            storage = await self._add_storage(storage)\n            self._deployment_storage_map[deployment_id] = storage\n        self._deployment_ids.add(deployment_id)\n\n        return deployment_id\n\n    @sync_compatible\n    async def add_flow(\n        self,\n        flow: Flow,\n        name: str = None,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; UUID:\n        \"\"\"\n        Provides a flow to the runner to be run based on the provided configuration.\n\n        Will create a deployment for the provided flow and register the deployment\n        with the runner.\n\n        Args:\n            flow: A flow for the runner to run.\n            name: The name to give the created deployment. Will default to the name\n                of the runner.\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n        \"\"\"\n        api = PREFECT_API_URL.value()\n        if any([interval, cron, rrule]) and not api:\n            self._logger.warning(\n                \"Cannot schedule flows on an ephemeral server; run `prefect server\"\n                \" start` to start the scheduler.\"\n            )\n        name = self.name if name is None else name\n\n        deployment = await flow.to_deployment(\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedules=schedules,\n            schedule=schedule,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            triggers=triggers,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            entrypoint_type=entrypoint_type,\n        )\n        return await self.add_deployment(deployment)\n\n    @sync_compatible\n    async def _add_storage(self, storage: RunnerStorage) -&gt; RunnerStorage:\n        \"\"\"\n        Adds a storage object to the runner. The storage object will be used to pull\n        code to the runner's working directory before the runner starts.\n\n        Args:\n            storage: The storage object to add to the runner.\n        Returns:\n            The updated storage object that was added to the runner.\n        \"\"\"\n        if storage not in self._storage_objs:\n            storage_copy = deepcopy(storage)\n            storage_copy.set_base_path(self._tmp_dir)\n\n            self._logger.debug(\n                f\"Adding storage {storage_copy!r} to runner at\"\n                f\" {str(storage_copy.destination)!r}\"\n            )\n            self._storage_objs.append(storage_copy)\n\n            return storage_copy\n        else:\n            return next(s for s in self._storage_objs if s == storage)\n\n    def handle_sigterm(self, signum, frame):\n        \"\"\"\n        Gracefully shuts down the runner when a SIGTERM is received.\n        \"\"\"\n        self._logger.info(\"SIGTERM received, initiating graceful shutdown...\")\n        from_sync.call_in_loop_thread(create_call(self.stop))\n\n        sys.exit(0)\n\n    @sync_compatible\n    async def start(\n        self, run_once: bool = False, webserver: Optional[bool] = None\n    ) -&gt; None:\n        \"\"\"\n        Starts a runner.\n\n        The runner will begin monitoring for and executing any scheduled work for all added flows.\n\n        Args:\n            run_once: If True, the runner will through one query loop and then exit.\n            webserver: a boolean for whether to start a webserver for this runner. If provided,\n                overrides the default on the runner\n\n        Examples:\n            Initialize a Runner, add two flows, and serve them by starting the Runner:\n\n            ```python\n            from prefect import flow, Runner\n\n            @flow\n            def hello_flow(name):\n                print(f\"hello {name}\")\n\n            @flow\n            def goodbye_flow(name):\n                print(f\"goodbye {name}\")\n\n            if __name__ == \"__main__\"\n                runner = Runner(name=\"my-runner\")\n\n                # Will be runnable via the API\n                runner.add_flow(hello_flow)\n\n                # Run on a cron schedule\n                runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n                runner.start()\n            ```\n        \"\"\"\n        _register_signal(signal.SIGTERM, self.handle_sigterm)\n\n        webserver = webserver if webserver is not None else self.webserver\n\n        if webserver or PREFECT_RUNNER_SERVER_ENABLE.value():\n            # we'll start the ASGI server in a separate thread so that\n            # uvicorn does not block the main thread\n            server_thread = threading.Thread(\n                name=\"runner-server-thread\",\n                target=partial(\n                    start_webserver,\n                    runner=self,\n                ),\n                daemon=True,\n            )\n            server_thread.start()\n\n        async with self as runner:\n            async with self._loops_task_group as tg:\n                for storage in self._storage_objs:\n                    if storage.pull_interval:\n                        tg.start_soon(\n                            partial(\n                                critical_service_loop,\n                                workload=storage.pull_code,\n                                interval=storage.pull_interval,\n                                run_once=run_once,\n                                jitter_range=0.3,\n                            )\n                        )\n                    else:\n                        tg.start_soon(storage.pull_code)\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=runner._get_and_submit_flow_runs,\n                        interval=self.query_seconds,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                    )\n                )\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=runner._check_for_cancelled_flow_runs,\n                        interval=self.query_seconds * 2,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                    )\n                )\n\n    def execute_in_background(self, func, *args, **kwargs):\n        \"\"\"\n        Executes a function in the background.\n        \"\"\"\n\n        return asyncio.run_coroutine_threadsafe(func(*args, **kwargs), self._loop)\n\n    async def cancel_all(self):\n        runs_to_cancel = []\n\n        # done to avoid dictionary size changing during iteration\n        for info in self._flow_run_process_map.values():\n            runs_to_cancel.append(info[\"flow_run\"])\n        if runs_to_cancel:\n            for run in runs_to_cancel:\n                try:\n                    await self._cancel_run(run, state_msg=\"Runner is shutting down.\")\n                except Exception:\n                    self._logger.exception(\n                        f\"Exception encountered while cancelling {run.id}\",\n                        exc_info=True,\n                    )\n\n    @sync_compatible\n    async def stop(self):\n        \"\"\"Stops the runner's polling cycle.\"\"\"\n        if not self.started:\n            raise RuntimeError(\n                \"Runner has not yet started. Please start the runner by calling\"\n                \" .start()\"\n            )\n\n        self.started = False\n        self.stopping = True\n        await self.cancel_all()\n        try:\n            self._loops_task_group.cancel_scope.cancel()\n        except Exception:\n            self._logger.exception(\n                \"Exception encountered while shutting down\", exc_info=True\n            )\n\n    async def execute_flow_run(\n        self, flow_run_id: UUID, entrypoint: Optional[str] = None\n    ):\n        \"\"\"\n        Executes a single flow run with the given ID.\n\n        Execution will wait to monitor for cancellation requests. Exits once\n        the flow run process has exited.\n        \"\"\"\n        self.pause_on_shutdown = False\n        context = self if not self.started else asyncnullcontext()\n\n        async with context:\n            if not self._acquire_limit_slot(flow_run_id):\n                return\n\n            async with anyio.create_task_group() as tg:\n                with anyio.CancelScope():\n                    self._submitting_flow_run_ids.add(flow_run_id)\n                    flow_run = await self._client.read_flow_run(flow_run_id)\n\n                    pid = await self._runs_task_group.start(\n                        partial(\n                            self._submit_run_and_capture_errors,\n                            flow_run=flow_run,\n                            entrypoint=entrypoint,\n                        ),\n                    )\n\n                    self._flow_run_process_map[flow_run.id] = dict(\n                        pid=pid, flow_run=flow_run\n                    )\n\n                    # We want this loop to stop when the flow run process exits\n                    # so we'll check if the flow run process is still alive on\n                    # each iteration and cancel the task group if it is not.\n                    workload = partial(\n                        self._check_for_cancelled_flow_runs,\n                        should_stop=lambda: not self._flow_run_process_map,\n                        on_stop=tg.cancel_scope.cancel,\n                    )\n\n                    tg.start_soon(\n                        partial(\n                            critical_service_loop,\n                            workload=workload,\n                            interval=self.query_seconds,\n                            jitter_range=0.3,\n                        )\n                    )\n\n    def _get_flow_run_logger(self, flow_run: \"FlowRun\") -&gt; PrefectLogAdapter:\n        return flow_run_logger(flow_run=flow_run).getChild(\n            \"runner\",\n            extra={\n                \"runner_name\": self.name,\n            },\n        )\n\n    async def _run_process(\n        self,\n        flow_run: \"FlowRun\",\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n        entrypoint: Optional[str] = None,\n    ):\n        \"\"\"\n        Runs the given flow run in a subprocess.\n\n        Args:\n            flow_run: Flow run to execute via process. The ID of this flow run\n                is stored in the PREFECT__FLOW_RUN_ID environment variable to\n                allow the engine to retrieve the corresponding flow's code and\n                begin execution.\n            task_status: anyio task status used to send a message to the caller\n                than the flow run process has started.\n        \"\"\"\n        command = [get_sys_executable(), \"-m\", \"prefect.engine\"]\n\n        flow_run_logger = self._get_flow_run_logger(flow_run)\n\n        # We must add creationflags to a dict so it is only passed as a function\n        # parameter on Windows, because the presence of creationflags causes\n        # errors on Unix even if set to None\n        kwargs: Dict[str, object] = {}\n        if sys.platform == \"win32\":\n            kwargs[\"creationflags\"] = subprocess.CREATE_NEW_PROCESS_GROUP\n\n        flow_run_logger.info(\"Opening process...\")\n\n        env = get_current_settings().to_environment_variables(exclude_unset=True)\n        env.update(\n            {\n                **{\n                    \"PREFECT__FLOW_RUN_ID\": str(flow_run.id),\n                    \"PREFECT__STORAGE_BASE_PATH\": str(self._tmp_dir),\n                    \"PREFECT__ENABLE_CANCELLATION_AND_CRASHED_HOOKS\": \"false\",\n                },\n                **({\"PREFECT__FLOW_ENTRYPOINT\": entrypoint} if entrypoint else {}),\n            }\n        )\n        env.update(**os.environ)  # is this really necessary??\n\n        storage = self._deployment_storage_map.get(flow_run.deployment_id)\n        if storage and storage.pull_interval:\n            # perform an adhoc pull of code before running the flow if an\n            # adhoc pull hasn't been performed in the last pull_interval\n            # TODO: Explore integrating this behavior with global concurrency.\n            last_adhoc_pull = getattr(storage, \"last_adhoc_pull\", None)\n            if (\n                last_adhoc_pull is None\n                or last_adhoc_pull\n                &lt; datetime.datetime.now()\n                - datetime.timedelta(seconds=storage.pull_interval)\n            ):\n                self._logger.debug(\n                    \"Performing adhoc pull of code for flow run %s with storage %r\",\n                    flow_run.id,\n                    storage,\n                )\n                await storage.pull_code()\n                setattr(storage, \"last_adhoc_pull\", datetime.datetime.now())\n\n        process = await run_process(\n            command=command,\n            stream_output=True,\n            task_status=task_status,\n            env=env,\n            **kwargs,\n            cwd=storage.destination if storage else None,\n        )\n\n        # Use the pid for display if no name was given\n\n        if process.returncode:\n            help_message = None\n            level = logging.ERROR\n            if process.returncode == -9:\n                level = logging.INFO\n                help_message = (\n                    \"This indicates that the process exited due to a SIGKILL signal. \"\n                    \"Typically, this is either caused by manual cancellation or \"\n                    \"high memory usage causing the operating system to \"\n                    \"terminate the process.\"\n                )\n            if process.returncode == -15:\n                level = logging.INFO\n                help_message = (\n                    \"This indicates that the process exited due to a SIGTERM signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n            elif process.returncode == 247:\n                help_message = (\n                    \"This indicates that the process was terminated due to high \"\n                    \"memory usage.\"\n                )\n            elif (\n                sys.platform == \"win32\" and process.returncode == STATUS_CONTROL_C_EXIT\n            ):\n                level = logging.INFO\n                help_message = (\n                    \"Process was terminated due to a Ctrl+C or Ctrl+Break signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n\n            flow_run_logger.log(\n                level,\n                f\"Process for flow run {flow_run.name!r} exited with status code:\"\n                f\" {process.returncode}\"\n                + (f\"; {help_message}\" if help_message else \"\"),\n            )\n        else:\n            flow_run_logger.info(\n                f\"Process for flow run {flow_run.name!r} exited cleanly.\"\n            )\n\n        return process.returncode\n\n    async def _kill_process(\n        self,\n        pid: int,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Kills a given flow run process.\n\n        Args:\n            pid: ID of the process to kill\n            grace_seconds: Number of seconds to wait for the process to end.\n        \"\"\"\n        # In a non-windows environment first send a SIGTERM, then, after\n        # `grace_seconds` seconds have passed subsequent send SIGKILL. In\n        # Windows we use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        if sys.platform == \"win32\":\n            try:\n                os.kill(pid, signal.CTRL_BREAK_EVENT)\n            except (ProcessLookupError, WindowsError):\n                raise RuntimeError(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n        else:\n            try:\n                os.kill(pid, signal.SIGTERM)\n            except ProcessLookupError:\n                raise RuntimeError(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n\n            # Throttle how often we check if the process is still alive to keep\n            # from making too many system calls in a short period of time.\n            check_interval = max(grace_seconds / 10, 1)\n\n            with anyio.move_on_after(grace_seconds):\n                while True:\n                    await anyio.sleep(check_interval)\n\n                    # Detect if the process is still alive. If not do an early\n                    # return as the process respected the SIGTERM from above.\n                    try:\n                        os.kill(pid, 0)\n                    except ProcessLookupError:\n                        return\n\n            try:\n                os.kill(pid, signal.SIGKILL)\n            except OSError:\n                # We shouldn't ever end up here, but it's possible that the\n                # process ended right after the check above.\n                return\n\n    async def _pause_schedules(self):\n        \"\"\"\n        Pauses all deployment schedules.\n        \"\"\"\n        self._logger.info(\"Pausing all deployments...\")\n        for deployment_id in self._deployment_ids:\n            self._logger.debug(f\"Pausing deployment '{deployment_id}'\")\n            await self._client.set_deployment_paused_state(deployment_id, True)\n        self._logger.info(\"All deployments have been paused!\")\n\n    async def _get_and_submit_flow_runs(self):\n        if self.stopping:\n            return\n        runs_response = await self._get_scheduled_flow_runs()\n        self.last_polled = pendulum.now(\"UTC\")\n        return await self._submit_scheduled_flow_runs(flow_run_response=runs_response)\n\n    async def _check_for_cancelled_flow_runs(\n        self, should_stop: Callable = lambda: False, on_stop: Callable = lambda: None\n    ):\n        \"\"\"\n        Checks for flow runs with CANCELLING a cancelling state and attempts to\n        cancel them.\n\n        Args:\n            should_stop: A callable that returns a boolean indicating whether or not\n                the runner should stop checking for cancelled flow runs.\n            on_stop: A callable that is called when the runner should stop checking\n                for cancelled flow runs.\n        \"\"\"\n        if self.stopping:\n            return\n        if not self.started:\n            raise RuntimeError(\n                \"Runner is not set up. Please make sure you are running this runner \"\n                \"as an async context manager.\"\n            )\n\n        if should_stop():\n            self._logger.debug(\n                \"Runner has no active flow runs or deployments. Sending message to loop\"\n                \" service that no further cancellation checks are needed.\"\n            )\n            on_stop()\n\n        self._logger.debug(\"Checking for cancelled flow runs...\")\n\n        named_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(\n                    any_=list(\n                        self._flow_run_process_map.keys()\n                        - self._cancelling_flow_run_ids\n                    )\n                ),\n            ),\n        )\n\n        typed_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(\n                    any_=list(\n                        self._flow_run_process_map.keys()\n                        - self._cancelling_flow_run_ids\n                    )\n                ),\n            ),\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self._logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self._cancelling_flow_run_ids.add(flow_run.id)\n            self._runs_task_group.start_soon(self._cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def _cancel_run(self, flow_run: \"FlowRun\", state_msg: Optional[str] = None):\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        pid = self._flow_run_process_map.get(flow_run.id, {}).get(\"pid\")\n        if not pid:\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"Could not find process ID for flow run\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            await self._kill_process(pid)\n        except RuntimeError as exc:\n            self._logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except Exception:\n            run_logger.exception(\n                \"Encountered exception while killing process for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self._cancelling_flow_run_ids.remove(flow_run.id)\n        else:\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": state_msg or \"Flow run was cancelled successfully.\"\n                },\n            )\n            run_logger.info(f\"Cancelled flow run '{flow_run.name}'!\")\n\n    async def _get_scheduled_flow_runs(\n        self,\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Retrieve scheduled flow runs for this runner.\n        \"\"\"\n        scheduled_before = pendulum.now(\"utc\").add(seconds=int(self._prefetch_seconds))\n        self._logger.debug(\n            f\"Querying for flow runs scheduled before {scheduled_before}\"\n        )\n\n        scheduled_flow_runs = (\n            await self._client.get_scheduled_flow_runs_for_deployments(\n                deployment_ids=list(self._deployment_ids),\n                scheduled_before=scheduled_before,\n            )\n        )\n        self._logger.debug(f\"Discovered {len(scheduled_flow_runs)} scheduled_flow_runs\")\n        return scheduled_flow_runs\n\n    def has_slots_available(self) -&gt; bool:\n        \"\"\"\n        Determine if the flow run limit has been reached.\n\n        Returns:\n            - bool: True if the limit has not been reached, False otherwise.\n        \"\"\"\n        return self._limiter.available_tokens &gt; 0\n\n    def _acquire_limit_slot(self, flow_run_id: str) -&gt; bool:\n        \"\"\"\n        Enforces flow run limit set on runner.\n\n        Returns:\n            - bool: True if a slot was acquired, False otherwise.\n        \"\"\"\n        try:\n            if self._limiter:\n                self._limiter.acquire_on_behalf_of_nowait(flow_run_id)\n                self._logger.debug(\"Limit slot acquired for flow run '%s'\", flow_run_id)\n            return True\n        except RuntimeError as exc:\n            if (\n                \"this borrower is already holding one of this CapacityLimiter's tokens\"\n                in str(exc)\n            ):\n                self._logger.warning(\n                    f\"Duplicate submission of flow run '{flow_run_id}' detected. Runner\"\n                    \" will not re-submit flow run.\"\n                )\n                return False\n            else:\n                raise\n        except anyio.WouldBlock:\n            self._logger.info(\n                f\"Flow run limit reached; {self._limiter.borrowed_tokens} flow runs\"\n                \" in progress. You can control this limit by passing a `limit` value\"\n                \" to `serve` or adjusting the PREFECT_RUNNER_PROCESS_LIMIT setting.\"\n            )\n            return False\n\n    def _release_limit_slot(self, flow_run_id: str) -&gt; None:\n        \"\"\"\n        Frees up a slot taken by the given flow run id.\n        \"\"\"\n        if self._limiter:\n            self._limiter.release_on_behalf_of(flow_run_id)\n            self._logger.debug(\"Limit slot released for flow run '%s'\", flow_run_id)\n\n    async def _submit_scheduled_flow_runs(\n        self,\n        flow_run_response: List[\"FlowRun\"],\n        entrypoints: Optional[List[str]] = None,\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Takes a list of FlowRuns and submits the referenced flow runs\n        for execution by the runner.\n        \"\"\"\n        submittable_flow_runs = flow_run_response\n        submittable_flow_runs.sort(key=lambda run: run.next_scheduled_start_time)\n        for i, flow_run in enumerate(submittable_flow_runs):\n            if flow_run.id in self._submitting_flow_run_ids:\n                continue\n\n            if self._acquire_limit_slot(flow_run.id):\n                run_logger = self._get_flow_run_logger(flow_run)\n                run_logger.info(\n                    f\"Runner '{self.name}' submitting flow run '{flow_run.id}'\"\n                )\n                self._submitting_flow_run_ids.add(flow_run.id)\n                self._runs_task_group.start_soon(\n                    partial(\n                        self._submit_run,\n                        flow_run=flow_run,\n                        entrypoint=(\n                            entrypoints[i] if entrypoints else None\n                        ),  # TODO: avoid relying on index\n                    )\n                )\n            else:\n                break\n\n        return list(\n            filter(\n                lambda run: run.id in self._submitting_flow_run_ids,\n                submittable_flow_runs,\n            )\n        )\n\n    async def _submit_run(self, flow_run: \"FlowRun\", entrypoint: Optional[str] = None):\n        \"\"\"\n        Submits a given flow run for execution by the runner.\n        \"\"\"\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            readiness_result = await self._runs_task_group.start(\n                partial(\n                    self._submit_run_and_capture_errors,\n                    flow_run=flow_run,\n                    entrypoint=entrypoint,\n                ),\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                self._flow_run_process_map[flow_run.id] = dict(\n                    pid=readiness_result, flow_run=flow_run\n                )\n\n            run_logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            self._release_limit_slot(flow_run.id)\n\n        self._submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self,\n        flow_run: \"FlowRun\",\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n        entrypoint: Optional[str] = None,\n    ) -&gt; Union[Optional[int], Exception]:\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        try:\n            status_code = await self._run_process(\n                flow_run=flow_run,\n                task_status=task_status,\n                entrypoint=entrypoint,\n            )\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                run_logger.exception(\n                    f\"Failed to start process for flow run '{flow_run.id}'.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run process could not be started\"\n                )\n            else:\n                run_logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            self._release_limit_slot(flow_run.id)\n            self._flow_run_process_map.pop(flow_run.id, None)\n\n        if status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                f\"Flow run process exited with non-zero status code {status_code}.\",\n            )\n\n        api_flow_run = await self._client.read_flow_run(flow_run_id=flow_run.id)\n        terminal_state = api_flow_run.state\n        if terminal_state.is_crashed():\n            await self._run_on_crashed_hooks(flow_run=flow_run, state=terminal_state)\n\n        return status_code\n\n    async def _propose_pending_state(self, flow_run: \"FlowRun\") -&gt; bool:\n        run_logger = self._get_flow_run_logger(flow_run)\n        state = flow_run.state\n        try:\n            state = await propose_state(\n                self._client, Pending(), flow_run_id=flow_run.id\n            )\n        except Abort as exc:\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            run_logger.exception(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n            )\n            return False\n\n        if not state.is_pending():\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: \"FlowRun\", exc: Exception) -&gt; None:\n        run_logger = self._get_flow_run_logger(flow_run)\n        try:\n            await propose_state(\n                self._client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            run_logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: \"FlowRun\", message: str) -&gt; None:\n        run_logger = self._get_flow_run_logger(flow_run)\n        try:\n            state = await propose_state(\n                self._client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            run_logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                run_logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: \"FlowRun\", state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self._client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self._cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the runner exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.started:\n                with anyio.CancelScope() as scope:\n                    self._scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self._scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self._runs_task_group.start(wrapper)\n\n    async def _run_on_cancellation_hooks(\n        self,\n        flow_run: \"FlowRun\",\n        state: State,\n    ) -&gt; None:\n        \"\"\"\n        Run the hooks for a flow.\n        \"\"\"\n        if state.is_cancelling():\n            try:\n                flow = await load_flow_from_flow_run(\n                    flow_run, client=self._client, storage_base_path=str(self._tmp_dir)\n                )\n                hooks = flow.on_cancellation or []\n\n                await _run_hooks(hooks, flow_run, flow, state)\n            except ObjectNotFound:\n                run_logger = self._get_flow_run_logger(flow_run)\n                run_logger.warning(\n                    f\"Runner cannot retrieve flow to execute cancellation hooks for flow run {flow_run.id!r}.\"\n                )\n\n    async def _run_on_crashed_hooks(\n        self,\n        flow_run: \"FlowRun\",\n        state: State,\n    ) -&gt; None:\n        \"\"\"\n        Run the hooks for a flow.\n        \"\"\"\n        if state.is_crashed():\n            flow = await load_flow_from_flow_run(\n                flow_run, client=self._client, storage_base_path=str(self._tmp_dir)\n            )\n            hooks = flow.on_crashed or []\n\n            await _run_hooks(hooks, flow_run, flow, state)\n\n    async def __aenter__(self):\n        self._logger.debug(\"Starting runner...\")\n        self._client = get_client()\n        self._tmp_dir.mkdir(parents=True)\n        await self._client.__aenter__()\n        await self._runs_task_group.__aenter__()\n\n        self.started = True\n        return self\n\n    async def __aexit__(self, *exc_info):\n        self._logger.debug(\"Stopping runner...\")\n        if self.pause_on_shutdown:\n            await self._pause_schedules()\n        self.started = False\n        for scope in self._scheduled_task_scopes:\n            scope.cancel()\n        if self._runs_task_group:\n            await self._runs_task_group.__aexit__(*exc_info)\n        if self._client:\n            await self._client.__aexit__(*exc_info)\n        shutil.rmtree(str(self._tmp_dir))\n\n    def __repr__(self):\n        return f\"Runner(name={self.name!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.add_deployment","title":"<code>add_deployment</code>  <code>async</code>","text":"<p>Registers the deployment with the Prefect API and will monitor for work once the runner is started.</p> <p>Parameters:</p> Name Type Description Default <code>deployment</code> <code>RunnerDeployment</code> <p>A deployment for the runner to register.</p> required Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def add_deployment(\n    self,\n    deployment: RunnerDeployment,\n) -&gt; UUID:\n    \"\"\"\n    Registers the deployment with the Prefect API and will monitor for work once\n    the runner is started.\n\n    Args:\n        deployment: A deployment for the runner to register.\n    \"\"\"\n    deployment_id = await deployment.apply()\n    storage = deployment.storage\n    if storage is not None:\n        storage = await self._add_storage(storage)\n        self._deployment_storage_map[deployment_id] = storage\n    self._deployment_ids.add(deployment_id)\n\n    return deployment_id\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.add_flow","title":"<code>add_flow</code>  <code>async</code>","text":"<p>Provides a flow to the runner to be run based on the provided configuration.</p> <p>Will create a deployment for the provided flow and register the deployment with the runner.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow for the runner to run.</p> required <code>name</code> <code>str</code> <p>The name to give the created deployment. Will default to the name of the runner.</p> <code>None</code> <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def add_flow(\n    self,\n    flow: Flow,\n    name: str = None,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; UUID:\n    \"\"\"\n    Provides a flow to the runner to be run based on the provided configuration.\n\n    Will create a deployment for the provided flow and register the deployment\n    with the runner.\n\n    Args:\n        flow: A flow for the runner to run.\n        name: The name to give the created deployment. Will default to the name\n            of the runner.\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n    \"\"\"\n    api = PREFECT_API_URL.value()\n    if any([interval, cron, rrule]) and not api:\n        self._logger.warning(\n            \"Cannot schedule flows on an ephemeral server; run `prefect server\"\n            \" start` to start the scheduler.\"\n        )\n    name = self.name if name is None else name\n\n    deployment = await flow.to_deployment(\n        name=name,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedules=schedules,\n        schedule=schedule,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        triggers=triggers,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        entrypoint_type=entrypoint_type,\n    )\n    return await self.add_deployment(deployment)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.execute_flow_run","title":"<code>execute_flow_run</code>  <code>async</code>","text":"<p>Executes a single flow run with the given ID.</p> <p>Execution will wait to monitor for cancellation requests. Exits once the flow run process has exited.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>async def execute_flow_run(\n    self, flow_run_id: UUID, entrypoint: Optional[str] = None\n):\n    \"\"\"\n    Executes a single flow run with the given ID.\n\n    Execution will wait to monitor for cancellation requests. Exits once\n    the flow run process has exited.\n    \"\"\"\n    self.pause_on_shutdown = False\n    context = self if not self.started else asyncnullcontext()\n\n    async with context:\n        if not self._acquire_limit_slot(flow_run_id):\n            return\n\n        async with anyio.create_task_group() as tg:\n            with anyio.CancelScope():\n                self._submitting_flow_run_ids.add(flow_run_id)\n                flow_run = await self._client.read_flow_run(flow_run_id)\n\n                pid = await self._runs_task_group.start(\n                    partial(\n                        self._submit_run_and_capture_errors,\n                        flow_run=flow_run,\n                        entrypoint=entrypoint,\n                    ),\n                )\n\n                self._flow_run_process_map[flow_run.id] = dict(\n                    pid=pid, flow_run=flow_run\n                )\n\n                # We want this loop to stop when the flow run process exits\n                # so we'll check if the flow run process is still alive on\n                # each iteration and cancel the task group if it is not.\n                workload = partial(\n                    self._check_for_cancelled_flow_runs,\n                    should_stop=lambda: not self._flow_run_process_map,\n                    on_stop=tg.cancel_scope.cancel,\n                )\n\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=workload,\n                        interval=self.query_seconds,\n                        jitter_range=0.3,\n                    )\n                )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.execute_in_background","title":"<code>execute_in_background</code>","text":"<p>Executes a function in the background.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>def execute_in_background(self, func, *args, **kwargs):\n    \"\"\"\n    Executes a function in the background.\n    \"\"\"\n\n    return asyncio.run_coroutine_threadsafe(func(*args, **kwargs), self._loop)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.handle_sigterm","title":"<code>handle_sigterm</code>","text":"<p>Gracefully shuts down the runner when a SIGTERM is received.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>def handle_sigterm(self, signum, frame):\n    \"\"\"\n    Gracefully shuts down the runner when a SIGTERM is received.\n    \"\"\"\n    self._logger.info(\"SIGTERM received, initiating graceful shutdown...\")\n    from_sync.call_in_loop_thread(create_call(self.stop))\n\n    sys.exit(0)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.has_slots_available","title":"<code>has_slots_available</code>","text":"<p>Determine if the flow run limit has been reached.</p> <p>Returns:</p> Type Description <code>bool</code> <ul> <li>bool: True if the limit has not been reached, False otherwise.</li> </ul> Source code in <code>prefect/runner/runner.py</code> <pre><code>def has_slots_available(self) -&gt; bool:\n    \"\"\"\n    Determine if the flow run limit has been reached.\n\n    Returns:\n        - bool: True if the limit has not been reached, False otherwise.\n    \"\"\"\n    return self._limiter.available_tokens &gt; 0\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.start","title":"<code>start</code>  <code>async</code>","text":"<p>Starts a runner.</p> <p>The runner will begin monitoring for and executing any scheduled work for all added flows.</p> <p>Parameters:</p> Name Type Description Default <code>run_once</code> <code>bool</code> <p>If True, the runner will through one query loop and then exit.</p> <code>False</code> <code>webserver</code> <code>Optional[bool]</code> <p>a boolean for whether to start a webserver for this runner. If provided, overrides the default on the runner</p> <code>None</code> <p>Examples:</p> <p>Initialize a Runner, add two flows, and serve them by starting the Runner:</p> <pre><code>from prefect import flow, Runner\n\n@flow\ndef hello_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef goodbye_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\"\n    runner = Runner(name=\"my-runner\")\n\n    # Will be runnable via the API\n    runner.add_flow(hello_flow)\n\n    # Run on a cron schedule\n    runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n    runner.start()\n</code></pre> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def start(\n    self, run_once: bool = False, webserver: Optional[bool] = None\n) -&gt; None:\n    \"\"\"\n    Starts a runner.\n\n    The runner will begin monitoring for and executing any scheduled work for all added flows.\n\n    Args:\n        run_once: If True, the runner will through one query loop and then exit.\n        webserver: a boolean for whether to start a webserver for this runner. If provided,\n            overrides the default on the runner\n\n    Examples:\n        Initialize a Runner, add two flows, and serve them by starting the Runner:\n\n        ```python\n        from prefect import flow, Runner\n\n        @flow\n        def hello_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def goodbye_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\"\n            runner = Runner(name=\"my-runner\")\n\n            # Will be runnable via the API\n            runner.add_flow(hello_flow)\n\n            # Run on a cron schedule\n            runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n            runner.start()\n        ```\n    \"\"\"\n    _register_signal(signal.SIGTERM, self.handle_sigterm)\n\n    webserver = webserver if webserver is not None else self.webserver\n\n    if webserver or PREFECT_RUNNER_SERVER_ENABLE.value():\n        # we'll start the ASGI server in a separate thread so that\n        # uvicorn does not block the main thread\n        server_thread = threading.Thread(\n            name=\"runner-server-thread\",\n            target=partial(\n                start_webserver,\n                runner=self,\n            ),\n            daemon=True,\n        )\n        server_thread.start()\n\n    async with self as runner:\n        async with self._loops_task_group as tg:\n            for storage in self._storage_objs:\n                if storage.pull_interval:\n                    tg.start_soon(\n                        partial(\n                            critical_service_loop,\n                            workload=storage.pull_code,\n                            interval=storage.pull_interval,\n                            run_once=run_once,\n                            jitter_range=0.3,\n                        )\n                    )\n                else:\n                    tg.start_soon(storage.pull_code)\n            tg.start_soon(\n                partial(\n                    critical_service_loop,\n                    workload=runner._get_and_submit_flow_runs,\n                    interval=self.query_seconds,\n                    run_once=run_once,\n                    jitter_range=0.3,\n                )\n            )\n            tg.start_soon(\n                partial(\n                    critical_service_loop,\n                    workload=runner._check_for_cancelled_flow_runs,\n                    interval=self.query_seconds * 2,\n                    run_once=run_once,\n                    jitter_range=0.3,\n                )\n            )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Stops the runner's polling cycle.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def stop(self):\n    \"\"\"Stops the runner's polling cycle.\"\"\"\n    if not self.started:\n        raise RuntimeError(\n            \"Runner has not yet started. Please start the runner by calling\"\n            \" .start()\"\n        )\n\n    self.started = False\n    self.stopping = True\n    await self.cancel_all()\n    try:\n        self._loops_task_group.cancel_scope.cancel()\n    except Exception:\n        self._logger.exception(\n            \"Exception encountered while shutting down\", exc_info=True\n        )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/server/","title":"server","text":"","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server","title":"<code>prefect.runner.server</code>","text":"","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.build_server","title":"<code>build_server</code>  <code>async</code>","text":"<p>Build a FastAPI server for a runner.</p> <p>Parameters:</p> Name Type Description Default <code>runner</code> <code>Runner</code> <p>the runner this server interacts with and monitors</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> required Source code in <code>prefect/runner/server.py</code> <pre><code>@sync_compatible\nasync def build_server(runner: \"Runner\") -&gt; FastAPI:\n    \"\"\"\n    Build a FastAPI server for a runner.\n\n    Args:\n        runner (Runner): the runner this server interacts with and monitors\n        log_level (str): the log level to use for the server\n    \"\"\"\n    webserver = FastAPI()\n    router = APIRouter()\n\n    router.add_api_route(\n        \"/health\", perform_health_check(runner=runner), methods=[\"GET\"]\n    )\n    router.add_api_route(\"/run_count\", run_count(runner=runner), methods=[\"GET\"])\n    router.add_api_route(\"/shutdown\", shutdown(runner=runner), methods=[\"POST\"])\n    webserver.include_router(router)\n\n    if PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS.value():\n        deployments_router, deployment_schemas = await get_deployment_router(runner)\n        webserver.include_router(deployments_router)\n\n        subflow_schemas = await get_subflow_schemas(runner)\n        webserver.add_api_route(\n            \"/flow/run\",\n            _build_generic_endpoint_for_flows(runner=runner, schemas=subflow_schemas),\n            methods=[\"POST\"],\n            name=\"Run flow in background\",\n            description=\"Trigger any flow run as a background task on the runner.\",\n            summary=\"Run flow\",\n        )\n\n        def customize_openapi():\n            if webserver.openapi_schema:\n                return webserver.openapi_schema\n\n            openapi_schema = inject_schemas_into_openapi(webserver, deployment_schemas)\n            webserver.openapi_schema = openapi_schema\n            return webserver.openapi_schema\n\n        webserver.openapi = customize_openapi\n\n    return webserver\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.get_subflow_schemas","title":"<code>get_subflow_schemas</code>  <code>async</code>","text":"<p>Load available subflow schemas by filtering for only those subflows in the deployment entrypoint's import space.</p> Source code in <code>prefect/runner/server.py</code> <pre><code>async def get_subflow_schemas(runner: \"Runner\") -&gt; Dict[str, Dict]:\n    \"\"\"\n    Load available subflow schemas by filtering for only those subflows in the\n    deployment entrypoint's import space.\n    \"\"\"\n    schemas = {}\n    async with get_client() as client:\n        for deployment_id in runner._deployment_ids:\n            deployment = await client.read_deployment(deployment_id)\n            if deployment.entrypoint is None:\n                continue\n\n            script = deployment.entrypoint.split(\":\")[0]\n            subflows = load_flows_from_script(script)\n            for flow in subflows:\n                schemas[flow.name] = flow.parameters.dict()\n\n    return schemas\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.start_webserver","title":"<code>start_webserver</code>","text":"<p>Run a FastAPI server for a runner.</p> <p>Parameters:</p> Name Type Description Default <code>runner</code> <code>Runner</code> <p>the runner this server interacts with and monitors</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> <code>None</code> Source code in <code>prefect/runner/server.py</code> <pre><code>def start_webserver(runner: \"Runner\", log_level: Optional[str] = None) -&gt; None:\n    \"\"\"\n    Run a FastAPI server for a runner.\n\n    Args:\n        runner (Runner): the runner this server interacts with and monitors\n        log_level (str): the log level to use for the server\n    \"\"\"\n    host = PREFECT_RUNNER_SERVER_HOST.value()\n    port = PREFECT_RUNNER_SERVER_PORT.value()\n    log_level = log_level or PREFECT_RUNNER_SERVER_LOG_LEVEL.value()\n    webserver = build_server(runner)\n    uvicorn.run(webserver, host=host, port=port, log_level=log_level)\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/storage/","title":"storage","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage","title":"<code>prefect.runner.storage</code>","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.BlockStorageAdapter","title":"<code>BlockStorageAdapter</code>","text":"<p>A storage adapter for a storage block object to allow it to be used as a runner storage object.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>class BlockStorageAdapter:\n    \"\"\"\n    A storage adapter for a storage block object to allow it to be used as a\n    runner storage object.\n    \"\"\"\n\n    def __init__(\n        self,\n        block: Union[ReadableDeploymentStorage, WritableDeploymentStorage],\n        pull_interval: Optional[int] = 60,\n    ):\n        self._block = block\n        self._pull_interval = pull_interval\n        self._storage_base_path = Path.cwd()\n        if not isinstance(block, Block):\n            raise TypeError(\n                f\"Expected a block object. Received a {type(block).__name__!r} object.\"\n            )\n        if not hasattr(block, \"get_directory\"):\n            raise ValueError(\"Provided block must have a `get_directory` method.\")\n\n        self._name = (\n            f\"{block.get_block_type_slug()}-{block._block_document_name}\"\n            if block._block_document_name\n            else str(uuid4())\n        )\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._storage_base_path / self._name\n\n    async def pull_code(self):\n        if not self.destination.exists():\n            self.destination.mkdir(parents=True, exist_ok=True)\n        await self._block.get_directory(local_path=str(self.destination))\n\n    def to_pull_step(self) -&gt; dict:\n        # Give blocks the change to implement their own pull step\n        if hasattr(self._block, \"get_pull_step\"):\n            return self._block.get_pull_step()\n        else:\n            if not self._block._block_document_name:\n                raise BlockNotSavedError(\n                    \"Block must be saved with `.save()` before it can be converted to a\"\n                    \" pull step.\"\n                )\n            return {\n                \"prefect.deployments.steps.pull_with_block\": {\n                    \"block_type_slug\": self._block.get_block_type_slug(),\n                    \"block_document_name\": self._block._block_document_name,\n                }\n            }\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, BlockStorageAdapter):\n            return self._block == __value._block\n        return False\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.GitRepository","title":"<code>GitRepository</code>","text":"<p>Pulls the contents of a git repository to the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>The URL of the git repository to pull from</p> required <code>credentials</code> <code>Union[GitCredentials, Block, Dict[str, Any], None]</code> <p>A dictionary of credentials to use when pulling from the repository. If a username is provided, an access token must also be provided.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>The name of the repository. If not provided, the name will be inferred from the repository URL.</p> <code>None</code> <code>branch</code> <code>Optional[str]</code> <p>The branch to pull from. Defaults to \"main\".</p> <code>None</code> <code>pull_interval</code> <code>Optional[int]</code> <p>The interval in seconds at which to pull contents from remote storage to local storage. If None, remote storage will perform a one-time sync.</p> <code>60</code> <p>Examples:</p> <p>Pull the contents of a private git repository to the local filesystem:</p> <pre><code>from prefect.runner.storage import GitRepository\n\nstorage = GitRepository(\n    url=\"https://github.com/org/repo.git\",\n    credentials={\"username\": \"oauth2\", \"access_token\": \"my-access-token\"},\n)\n\nawait storage.pull_code()\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class GitRepository:\n    \"\"\"\n    Pulls the contents of a git repository to the local filesystem.\n\n    Parameters:\n        url: The URL of the git repository to pull from\n        credentials: A dictionary of credentials to use when pulling from the\n            repository. If a username is provided, an access token must also be\n            provided.\n        name: The name of the repository. If not provided, the name will be\n            inferred from the repository URL.\n        branch: The branch to pull from. Defaults to \"main\".\n        pull_interval: The interval in seconds at which to pull contents from\n            remote storage to local storage. If None, remote storage will perform\n            a one-time sync.\n\n    Examples:\n        Pull the contents of a private git repository to the local filesystem:\n\n        ```python\n        from prefect.runner.storage import GitRepository\n\n        storage = GitRepository(\n            url=\"https://github.com/org/repo.git\",\n            credentials={\"username\": \"oauth2\", \"access_token\": \"my-access-token\"},\n        )\n\n        await storage.pull_code()\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        url: str,\n        credentials: Union[GitCredentials, Block, Dict[str, Any], None] = None,\n        name: Optional[str] = None,\n        branch: Optional[str] = None,\n        include_submodules: bool = False,\n        pull_interval: Optional[int] = 60,\n    ):\n        if credentials is None:\n            credentials = {}\n\n        if (\n            isinstance(credentials, dict)\n            and credentials.get(\"username\")\n            and not (credentials.get(\"access_token\") or credentials.get(\"password\"))\n        ):\n            raise ValueError(\n                \"If a username is provided, an access token or password must also be\"\n                \" provided.\"\n            )\n        self._url = url\n        self._branch = branch\n        self._credentials = credentials\n        self._include_submodules = include_submodules\n        repo_name = urlparse(url).path.split(\"/\")[-1].replace(\".git\", \"\")\n        default_name = f\"{repo_name}-{branch}\" if branch else repo_name\n        self._name = name or default_name\n        self._logger = get_logger(f\"runner.storage.git-repository.{self._name}\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._storage_base_path / self._name\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    @property\n    def _repository_url_with_credentials(self) -&gt; str:\n        if not self._credentials:\n            return self._url\n\n        url_components = urlparse(self._url)\n\n        credentials = (\n            self._credentials.dict()\n            if isinstance(self._credentials, Block)\n            else deepcopy(self._credentials)\n        )\n\n        for k, v in credentials.items():\n            if isinstance(v, Secret):\n                credentials[k] = v.get()\n            elif isinstance(v, SecretStr):\n                credentials[k] = v.get_secret_value()\n\n        formatted_credentials = _format_token_from_credentials(\n            urlparse(self._url).netloc, credentials\n        )\n        if url_components.scheme == \"https\" and formatted_credentials is not None:\n            updated_components = url_components._replace(\n                netloc=f\"{formatted_credentials}@{url_components.netloc}\"\n            )\n            repository_url = urlunparse(updated_components)\n        else:\n            repository_url = self._url\n\n        return repository_url\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls the contents of the configured repository to the local filesystem.\n        \"\"\"\n        self._logger.debug(\n            \"Pulling contents from repository '%s' to '%s'...\",\n            self._name,\n            self.destination,\n        )\n\n        git_dir = self.destination / \".git\"\n\n        if git_dir.exists():\n            # Check if the existing repository matches the configured repository\n            result = await run_process(\n                [\"git\", \"config\", \"--get\", \"remote.origin.url\"],\n                cwd=str(self.destination),\n            )\n            existing_repo_url = None\n            if result.stdout is not None:\n                existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())\n\n            if existing_repo_url != self._url:\n                raise ValueError(\n                    f\"The existing repository at {str(self.destination)} \"\n                    f\"does not match the configured repository {self._url}\"\n                )\n\n            self._logger.debug(\"Pulling latest changes from origin/%s\", self._branch)\n            # Update the existing repository\n            cmd = [\"git\", \"pull\", \"origin\"]\n            if self._branch:\n                cmd += [self._branch]\n            if self._include_submodules:\n                cmd += [\"--recurse-submodules\"]\n            cmd += [\"--depth\", \"1\"]\n            try:\n                await run_process(cmd, cwd=self.destination)\n                self._logger.debug(\"Successfully pulled latest changes\")\n            except subprocess.CalledProcessError as exc:\n                self._logger.error(\n                    f\"Failed to pull latest changes with exit code {exc}\"\n                )\n                shutil.rmtree(self.destination)\n                await self._clone_repo()\n\n        else:\n            await self._clone_repo()\n\n    async def _clone_repo(self):\n        \"\"\"\n        Clones the repository into the local destination.\n        \"\"\"\n        self._logger.debug(\"Cloning repository %s\", self._url)\n\n        repository_url = self._repository_url_with_credentials\n\n        cmd = [\n            \"git\",\n            \"clone\",\n            repository_url,\n        ]\n        if self._branch:\n            cmd += [\"--branch\", self._branch]\n        if self._include_submodules:\n            cmd += [\"--recurse-submodules\"]\n\n        # Limit git history and set path to clone to\n        cmd += [\"--depth\", \"1\", str(self.destination)]\n\n        try:\n            await run_process(cmd)\n        except subprocess.CalledProcessError as exc:\n            # Hide the command used to avoid leaking the access token\n            exc_chain = None if self._credentials else exc\n            raise RuntimeError(\n                f\"Failed to clone repository {self._url!r} with exit code\"\n                f\" {exc.returncode}.\"\n            ) from exc_chain\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, GitRepository):\n            return (\n                self._url == __value._url\n                and self._branch == __value._branch\n                and self._name == __value._name\n            )\n        return False\n\n    def __repr__(self) -&gt; str:\n        return (\n            f\"GitRepository(name={self._name!r} repository={self._url!r},\"\n            f\" branch={self._branch!r})\"\n        )\n\n    def to_pull_step(self) -&gt; Dict:\n        pull_step = {\n            \"prefect.deployments.steps.git_clone\": {\n                \"repository\": self._url,\n                \"branch\": self._branch,\n            }\n        }\n        if self._include_submodules:\n            pull_step[\"prefect.deployments.steps.git_clone\"][\n                \"include_submodules\"\n            ] = self._include_submodules\n        if isinstance(self._credentials, Block):\n            pull_step[\"prefect.deployments.steps.git_clone\"][\n                \"credentials\"\n            ] = f\"{{{{ {self._credentials.get_block_placeholder()} }}}}\"\n        elif isinstance(self._credentials, dict):\n            if isinstance(self._credentials.get(\"access_token\"), Secret):\n                pull_step[\"prefect.deployments.steps.git_clone\"][\"credentials\"] = {\n                    **self._credentials,\n                    \"access_token\": (\n                        \"{{\"\n                        f\" {self._credentials['access_token'].get_block_placeholder()} }}}}\"\n                    ),\n                }\n            elif self._credentials.get(\"access_token\") is not None:\n                raise ValueError(\n                    \"Please save your access token as a Secret block before converting\"\n                    \" this storage object to a pull step.\"\n                )\n\n        return pull_step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.GitRepository.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls the contents of the configured repository to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls the contents of the configured repository to the local filesystem.\n    \"\"\"\n    self._logger.debug(\n        \"Pulling contents from repository '%s' to '%s'...\",\n        self._name,\n        self.destination,\n    )\n\n    git_dir = self.destination / \".git\"\n\n    if git_dir.exists():\n        # Check if the existing repository matches the configured repository\n        result = await run_process(\n            [\"git\", \"config\", \"--get\", \"remote.origin.url\"],\n            cwd=str(self.destination),\n        )\n        existing_repo_url = None\n        if result.stdout is not None:\n            existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())\n\n        if existing_repo_url != self._url:\n            raise ValueError(\n                f\"The existing repository at {str(self.destination)} \"\n                f\"does not match the configured repository {self._url}\"\n            )\n\n        self._logger.debug(\"Pulling latest changes from origin/%s\", self._branch)\n        # Update the existing repository\n        cmd = [\"git\", \"pull\", \"origin\"]\n        if self._branch:\n            cmd += [self._branch]\n        if self._include_submodules:\n            cmd += [\"--recurse-submodules\"]\n        cmd += [\"--depth\", \"1\"]\n        try:\n            await run_process(cmd, cwd=self.destination)\n            self._logger.debug(\"Successfully pulled latest changes\")\n        except subprocess.CalledProcessError as exc:\n            self._logger.error(\n                f\"Failed to pull latest changes with exit code {exc}\"\n            )\n            shutil.rmtree(self.destination)\n            await self._clone_repo()\n\n    else:\n        await self._clone_repo()\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.LocalStorage","title":"<code>LocalStorage</code>","text":"<p>Sets the working directory in the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>Path</code> <p>Local file path to set the working directory for the flow</p> required <p>Examples:</p> <p>Sets the working directory for the local path to the flow:</p> <pre><code>from prefect.runner.storage import Localstorage\n\nstorage = LocalStorage(\n    path=\"/path/to/local/flow_directory\",\n)\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class LocalStorage:\n    \"\"\"\n    Sets the working directory in the local filesystem.\n\n    Parameters:\n        Path: Local file path to set the working directory for the flow\n\n    Examples:\n        Sets the working directory for the local path to the flow:\n\n        ```python\n        from prefect.runner.storage import Localstorage\n\n        storage = LocalStorage(\n            path=\"/path/to/local/flow_directory\",\n        )\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        path: str,\n        pull_interval: Optional[int] = None,\n    ):\n        self._path = Path(path).resolve()\n        self._logger = get_logger(\"runner.storage.local-storage\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._path\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    async def pull_code(self):\n        # Local storage assumes the code already exists on the local filesystem\n        # and does not need to be pulled from a remote location\n        pass\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n        step = {\n            \"prefect.deployments.steps.set_working_directory\": {\n                \"directory\": str(self.destination)\n            }\n        }\n        return step\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, LocalStorage):\n            return self._path == __value._path\n        return False\n\n    def __repr__(self) -&gt; str:\n        return f\"LocalStorage(path={self._path!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.LocalStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n    step = {\n        \"prefect.deployments.steps.set_working_directory\": {\n            \"directory\": str(self.destination)\n        }\n    }\n    return step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage","title":"<code>RemoteStorage</code>","text":"<p>Pulls the contents of a remote storage location to the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>The URL of the remote storage location to pull from. Supports <code>fsspec</code> URLs. Some protocols may require an additional <code>fsspec</code> dependency to be installed. Refer to the <code>fsspec</code> docs for more details.</p> required <code>pull_interval</code> <code>Optional[int]</code> <p>The interval in seconds at which to pull contents from remote storage to local storage. If None, remote storage will perform a one-time sync.</p> <code>60</code> <code>**settings</code> <code>Any</code> <p>Any additional settings to pass the <code>fsspec</code> filesystem class.</p> <code>{}</code> <p>Examples:</p> <p>Pull the contents of a remote storage location to the local filesystem:</p> <pre><code>from prefect.runner.storage import RemoteStorage\n\nstorage = RemoteStorage(url=\"s3://my-bucket/my-folder\")\n\nawait storage.pull_code()\n</code></pre> <p>Pull the contents of a remote storage location to the local filesystem with additional settings:</p> <pre><code>from prefect.runner.storage import RemoteStorage\nfrom prefect.blocks.system import Secret\n\nstorage = RemoteStorage(\n    url=\"s3://my-bucket/my-folder\",\n    # Use Secret blocks to keep credentials out of your code\n    key=Secret.load(\"my-aws-access-key\"),\n    secret=Secret.load(\"my-aws-secret-key\"),\n)\n\nawait storage.pull_code()\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class RemoteStorage:\n    \"\"\"\n    Pulls the contents of a remote storage location to the local filesystem.\n\n    Parameters:\n        url: The URL of the remote storage location to pull from. Supports\n            `fsspec` URLs. Some protocols may require an additional `fsspec`\n            dependency to be installed. Refer to the\n            [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)\n            for more details.\n        pull_interval: The interval in seconds at which to pull contents from\n            remote storage to local storage. If None, remote storage will perform\n            a one-time sync.\n        **settings: Any additional settings to pass the `fsspec` filesystem class.\n\n    Examples:\n        Pull the contents of a remote storage location to the local filesystem:\n\n        ```python\n        from prefect.runner.storage import RemoteStorage\n\n        storage = RemoteStorage(url=\"s3://my-bucket/my-folder\")\n\n        await storage.pull_code()\n        ```\n\n        Pull the contents of a remote storage location to the local filesystem\n        with additional settings:\n\n        ```python\n        from prefect.runner.storage import RemoteStorage\n        from prefect.blocks.system import Secret\n\n        storage = RemoteStorage(\n            url=\"s3://my-bucket/my-folder\",\n            # Use Secret blocks to keep credentials out of your code\n            key=Secret.load(\"my-aws-access-key\"),\n            secret=Secret.load(\"my-aws-secret-key\"),\n        )\n\n        await storage.pull_code()\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        url: str,\n        pull_interval: Optional[int] = 60,\n        **settings: Any,\n    ):\n        self._url = url\n        self._settings = settings\n        self._logger = get_logger(\"runner.storage.remote-storage\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @staticmethod\n    def _get_required_package_for_scheme(scheme: str) -&gt; Optional[str]:\n        # attempt to discover the package name for the given scheme\n        # from fsspec's registry\n        known_implementation = fsspec.registry.get(scheme)\n        if known_implementation:\n            return known_implementation.__module__.split(\".\")[0]\n        # if we don't know the implementation, try to guess it for some\n        # common schemes\n        elif scheme == \"s3\":\n            return \"s3fs\"\n        elif scheme == \"gs\" or scheme == \"gcs\":\n            return \"gcsfs\"\n        elif scheme == \"abfs\" or scheme == \"az\":\n            return \"adlfs\"\n        else:\n            return None\n\n    @property\n    def _filesystem(self) -&gt; fsspec.AbstractFileSystem:\n        scheme, _, _, _, _ = urlsplit(self._url)\n\n        def replace_blocks_with_values(obj: Any) -&gt; Any:\n            if isinstance(obj, Block):\n                if hasattr(obj, \"get\"):\n                    return obj.get()\n                if hasattr(obj, \"value\"):\n                    return obj.value\n                else:\n                    return obj.dict()\n            return obj\n\n        settings_with_block_values = visit_collection(\n            self._settings, replace_blocks_with_values, return_data=True\n        )\n\n        return fsspec.filesystem(scheme, **settings_with_block_values)\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        \"\"\"\n        The interval at which contents from remote storage should be pulled to\n        local storage. If None, remote storage will perform a one-time sync.\n        \"\"\"\n        return self._pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        \"\"\"\n        The local file path to pull contents from remote storage to.\n        \"\"\"\n        return self._storage_base_path / self._remote_path\n\n    @property\n    def _remote_path(self) -&gt; Path:\n        \"\"\"\n        The remote file path to pull contents from remote storage to.\n        \"\"\"\n        _, netloc, urlpath, _, _ = urlsplit(self._url)\n        return Path(netloc) / Path(urlpath.lstrip(\"/\"))\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls contents from remote storage to the local filesystem.\n        \"\"\"\n        self._logger.debug(\n            \"Pulling contents from remote storage '%s' to '%s'...\",\n            self._url,\n            self.destination,\n        )\n\n        if not self.destination.exists():\n            self.destination.mkdir(parents=True, exist_ok=True)\n\n        remote_path = str(self._remote_path) + \"/\"\n\n        try:\n            await from_async.wait_for_call_in_new_thread(\n                create_call(\n                    self._filesystem.get,\n                    remote_path,\n                    str(self.destination),\n                    recursive=True,\n                )\n            )\n        except Exception as exc:\n            raise RuntimeError(\n                f\"Failed to pull contents from remote storage {self._url!r} to\"\n                f\" {self.destination!r}\"\n            ) from exc\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n\n        def replace_block_with_placeholder(obj: Any) -&gt; Any:\n            if isinstance(obj, Block):\n                return f\"{{{{ {obj.get_block_placeholder()} }}}}\"\n            return obj\n\n        settings_with_placeholders = visit_collection(\n            self._settings, replace_block_with_placeholder, return_data=True\n        )\n        required_package = self._get_required_package_for_scheme(\n            urlparse(self._url).scheme\n        )\n        step = {\n            \"prefect.deployments.steps.pull_from_remote_storage\": {\n                \"url\": self._url,\n                **settings_with_placeholders,\n            }\n        }\n        if required_package:\n            step[\"prefect.deployments.steps.pull_from_remote_storage\"][\n                \"requires\"\n            ] = required_package\n        return step\n\n    def __eq__(self, __value) -&gt; bool:\n        \"\"\"\n        Equality check for runner storage objects.\n        \"\"\"\n        if isinstance(__value, RemoteStorage):\n            return self._url == __value._url and self._settings == __value._settings\n        return False\n\n    def __repr__(self) -&gt; str:\n        return f\"RemoteStorage(url={self._url!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.destination","title":"<code>destination: Path</code>  <code>property</code>","text":"<p>The local file path to pull contents from remote storage to.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.pull_interval","title":"<code>pull_interval: Optional[int]</code>  <code>property</code>","text":"<p>The interval at which contents from remote storage should be pulled to local storage. If None, remote storage will perform a one-time sync.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls contents from remote storage to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls contents from remote storage to the local filesystem.\n    \"\"\"\n    self._logger.debug(\n        \"Pulling contents from remote storage '%s' to '%s'...\",\n        self._url,\n        self.destination,\n    )\n\n    if not self.destination.exists():\n        self.destination.mkdir(parents=True, exist_ok=True)\n\n    remote_path = str(self._remote_path) + \"/\"\n\n    try:\n        await from_async.wait_for_call_in_new_thread(\n            create_call(\n                self._filesystem.get,\n                remote_path,\n                str(self.destination),\n                recursive=True,\n            )\n        )\n    except Exception as exc:\n        raise RuntimeError(\n            f\"Failed to pull contents from remote storage {self._url!r} to\"\n            f\" {self.destination!r}\"\n        ) from exc\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n\n    def replace_block_with_placeholder(obj: Any) -&gt; Any:\n        if isinstance(obj, Block):\n            return f\"{{{{ {obj.get_block_placeholder()} }}}}\"\n        return obj\n\n    settings_with_placeholders = visit_collection(\n        self._settings, replace_block_with_placeholder, return_data=True\n    )\n    required_package = self._get_required_package_for_scheme(\n        urlparse(self._url).scheme\n    )\n    step = {\n        \"prefect.deployments.steps.pull_from_remote_storage\": {\n            \"url\": self._url,\n            **settings_with_placeholders,\n        }\n    }\n    if required_package:\n        step[\"prefect.deployments.steps.pull_from_remote_storage\"][\n            \"requires\"\n        ] = required_package\n    return step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage","title":"<code>RunnerStorage</code>","text":"<p>               Bases: <code>Protocol</code></p> <p>A storage interface for a runner to use to retrieve remotely stored flow code.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>@runtime_checkable\nclass RunnerStorage(Protocol):\n    \"\"\"\n    A storage interface for a runner to use to retrieve\n    remotely stored flow code.\n    \"\"\"\n\n    def set_base_path(self, path: Path):\n        \"\"\"\n        Sets the base path to use when pulling contents from remote storage to\n        local storage.\n        \"\"\"\n        ...\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        \"\"\"\n        The interval at which contents from remote storage should be pulled to\n        local storage. If None, remote storage will perform a one-time sync.\n        \"\"\"\n        ...\n\n    @property\n    def destination(self) -&gt; Path:\n        \"\"\"\n        The local file path to pull contents from remote storage to.\n        \"\"\"\n        ...\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls contents from remote storage to the local filesystem.\n        \"\"\"\n        ...\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n        ...\n\n    def __eq__(self, __value) -&gt; bool:\n        \"\"\"\n        Equality check for runner storage objects.\n        \"\"\"\n        ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.destination","title":"<code>destination: Path</code>  <code>property</code>","text":"<p>The local file path to pull contents from remote storage to.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.pull_interval","title":"<code>pull_interval: Optional[int]</code>  <code>property</code>","text":"<p>The interval at which contents from remote storage should be pulled to local storage. If None, remote storage will perform a one-time sync.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls contents from remote storage to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls contents from remote storage to the local filesystem.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.set_base_path","title":"<code>set_base_path</code>","text":"<p>Sets the base path to use when pulling contents from remote storage to local storage.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def set_base_path(self, path: Path):\n    \"\"\"\n    Sets the base path to use when pulling contents from remote storage to\n    local storage.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.create_storage_from_source","title":"<code>create_storage_from_source</code>","text":"<p>Creates a storage object from a URL.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <p>The URL to create a storage object from. Supports git and <code>fsspec</code> URLs.</p> required <code>pull_interval</code> <code>Optional[int]</code> <p>The interval at which to pull contents from remote storage to local storage</p> <code>60</code> <p>Returns:</p> Name Type Description <code>RunnerStorage</code> <code>RunnerStorage</code> <p>A runner storage compatible object</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def create_storage_from_source(\n    source: str, pull_interval: Optional[int] = 60\n) -&gt; RunnerStorage:\n    \"\"\"\n    Creates a storage object from a URL.\n\n    Args:\n        url: The URL to create a storage object from. Supports git and `fsspec`\n            URLs.\n        pull_interval: The interval at which to pull contents from remote storage to\n            local storage\n\n    Returns:\n        RunnerStorage: A runner storage compatible object\n    \"\"\"\n    logger = get_logger(\"runner.storage\")\n    parsed_source = urlparse(source)\n    if parsed_source.scheme == \"git\" or parsed_source.path.endswith(\".git\"):\n        return GitRepository(url=source, pull_interval=pull_interval)\n    elif parsed_source.scheme in (\"file\", \"local\"):\n        source_path = source.split(\"://\", 1)[-1]\n        return LocalStorage(path=source_path, pull_interval=pull_interval)\n    elif parsed_source.scheme in fsspec.available_protocols():\n        return RemoteStorage(url=source, pull_interval=pull_interval)\n    else:\n        logger.debug(\"No valid fsspec protocol found for URL, assuming local storage.\")\n        return LocalStorage(path=source, pull_interval=pull_interval)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/utils/","title":"utils","text":"","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils","title":"<code>prefect.runner.utils</code>","text":"","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.inject_schemas_into_openapi","title":"<code>inject_schemas_into_openapi</code>","text":"<p>Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.</p> <p>Parameters:</p> Name Type Description Default <code>webserver</code> <code>FastAPI</code> <p>The FastAPI instance representing the webserver.</p> required <code>schemas_to_inject</code> <code>Dict[str, Any]</code> <p>A dictionary of OpenAPI schemas to integrate.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The augmented OpenAPI schema dictionary.</p> Source code in <code>prefect/runner/utils.py</code> <pre><code>def inject_schemas_into_openapi(\n    webserver: FastAPI, schemas_to_inject: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.\n\n    Args:\n        webserver: The FastAPI instance representing the webserver.\n        schemas_to_inject: A dictionary of OpenAPI schemas to integrate.\n\n    Returns:\n        The augmented OpenAPI schema dictionary.\n    \"\"\"\n    openapi_schema = get_openapi(\n        title=\"FastAPI Prefect Runner\", version=PREFECT_VERSION, routes=webserver.routes\n    )\n\n    augmented_schema = merge_definitions(schemas_to_inject, openapi_schema)\n    return update_refs_to_components(augmented_schema)\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.merge_definitions","title":"<code>merge_definitions</code>","text":"<p>Integrates definitions from injected schemas into the OpenAPI components.</p> <p>Parameters:</p> Name Type Description Default <code>injected_schemas</code> <code>Dict[str, Any]</code> <p>A dictionary of deployment-specific schemas.</p> required <code>openapi_schema</code> <code>Dict[str, Any]</code> <p>The base OpenAPI schema to update.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def merge_definitions(\n    injected_schemas: Dict[str, Any], openapi_schema: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Integrates definitions from injected schemas into the OpenAPI components.\n\n    Args:\n        injected_schemas: A dictionary of deployment-specific schemas.\n        openapi_schema: The base OpenAPI schema to update.\n    \"\"\"\n    openapi_schema_copy = deepcopy(openapi_schema)\n    components = openapi_schema_copy.setdefault(\"components\", {}).setdefault(\n        \"schemas\", {}\n    )\n    for definitions in injected_schemas.values():\n        if \"definitions\" in definitions:\n            for def_name, def_schema in definitions[\"definitions\"].items():\n                def_schema_copy = deepcopy(def_schema)\n                update_refs_in_schema(def_schema_copy, \"#/components/schemas/\")\n                components[def_name] = def_schema_copy\n    return openapi_schema_copy\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.update_refs_in_schema","title":"<code>update_refs_in_schema</code>","text":"<p>Recursively replaces <code>$ref</code> with a new reference base in a schema item.</p> <p>Parameters:</p> Name Type Description Default <code>schema_item</code> <code>Any</code> <p>A schema or part of a schema to update references in.</p> required <code>new_ref</code> <code>str</code> <p>The new base string to replace in <code>$ref</code> values.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def update_refs_in_schema(schema_item: Any, new_ref: str) -&gt; None:\n    \"\"\"\n    Recursively replaces `$ref` with a new reference base in a schema item.\n\n    Args:\n        schema_item: A schema or part of a schema to update references in.\n        new_ref: The new base string to replace in `$ref` values.\n    \"\"\"\n    if isinstance(schema_item, dict):\n        if \"$ref\" in schema_item:\n            schema_item[\"$ref\"] = schema_item[\"$ref\"].replace(\"#/definitions/\", new_ref)\n        for value in schema_item.values():\n            update_refs_in_schema(value, new_ref)\n    elif isinstance(schema_item, list):\n        for item in schema_item:\n            update_refs_in_schema(item, new_ref)\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.update_refs_to_components","title":"<code>update_refs_to_components</code>","text":"<p>Updates all <code>$ref</code> fields in the OpenAPI schema to reference the components section.</p> <p>Parameters:</p> Name Type Description Default <code>openapi_schema</code> <code>Dict[str, Any]</code> <p>The OpenAPI schema to modify <code>$ref</code> fields in.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def update_refs_to_components(openapi_schema: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Updates all `$ref` fields in the OpenAPI schema to reference the components section.\n\n    Args:\n        openapi_schema: The OpenAPI schema to modify `$ref` fields in.\n    \"\"\"\n    for path_item in openapi_schema.get(\"paths\", {}).values():\n        for operation in path_item.values():\n            schema = (\n                operation.get(\"requestBody\", {})\n                .get(\"content\", {})\n                .get(\"application/json\", {})\n                .get(\"schema\", {})\n            )\n            update_refs_in_schema(schema, \"#/components/schemas/\")\n\n    for definition in openapi_schema.get(\"definitions\", {}).values():\n        update_refs_in_schema(definition, \"#/components/schemas/\")\n\n    return openapi_schema\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runtime/deployment/","title":"deployment","text":"","tags":["Python API","deployment context","context"]},{"location":"api-ref/prefect/runtime/deployment/#prefect.runtime.deployment","title":"<code>prefect.runtime.deployment</code>","text":"<p>Access attributes of the current deployment run dynamically.</p> <p>Note that if a deployment is not currently being run, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__DEPLOYMENT</code>.</p> Example usage <pre><code>from prefect.runtime import deployment\n\ndef get_task_runner():\n    task_runner_config = deployment.parameters.get(\"runner_config\", \"default config here\")\n    return DummyTaskRunner(task_runner_specs=task_runner_config)\n</code></pre> Available attributes <ul> <li><code>id</code>: the deployment's unique ID</li> <li><code>name</code>: the deployment's name</li> <li><code>version</code>: the deployment's version</li> <li><code>flow_run_id</code>: the current flow run ID for this deployment</li> <li><code>parameters</code>: the parameters that were passed to this run; note that these do not necessarily     include default values set on the flow function, only the parameter values set on the deployment     object or those directly provided via API for this run</li> </ul>","tags":["Python API","deployment context","context"]},{"location":"api-ref/prefect/runtime/flow_run/","title":"flow_run","text":"","tags":["Python API","flow run context","context"]},{"location":"api-ref/prefect/runtime/flow_run/#prefect.runtime.flow_run","title":"<code>prefect.runtime.flow_run</code>","text":"<p>Access attributes of the current flow run dynamically.</p> <p>Note that if a flow run cannot be discovered, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__FLOW_RUN</code>.</p> Available attributes <ul> <li><code>id</code>: the flow run's unique ID</li> <li><code>tags</code>: the flow run's set of tags</li> <li><code>scheduled_start_time</code>: the flow run's expected scheduled start time; defaults to now if not present</li> <li><code>name</code>: the name of the flow run</li> <li><code>flow_name</code>: the name of the flow</li> <li><code>flow_version</code>: the version of the flow</li> <li><code>parameters</code>: the parameters that were passed to this run; note that these do not necessarily     include default values set on the flow function, only the parameter values explicitly passed for the run</li> <li><code>parent_flow_run_id</code>: the ID of the flow run that triggered this run, if any</li> <li><code>parent_deployment_id</code>: the ID of the deployment that triggered this run, if any</li> <li><code>run_count</code>: the number of times this flow run has been run</li> </ul>","tags":["Python API","flow run context","context"]},{"location":"api-ref/prefect/runtime/task_run/","title":"task_run","text":"","tags":["Python API","task run context","context","task run"]},{"location":"api-ref/prefect/runtime/task_run/#prefect.runtime.task_run","title":"<code>prefect.runtime.task_run</code>","text":"<p>Access attributes of the current task run dynamically.</p> <p>Note that if a task run cannot be discovered, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__TASK_RUN</code>.</p> Available attributes <ul> <li><code>id</code>: the task run's unique ID</li> <li><code>name</code>: the name of the task run</li> <li><code>tags</code>: the task run's set of tags</li> <li><code>parameters</code>: the parameters the task was called with</li> <li><code>run_count</code>: the number of times this task run has been run</li> <li><code>task_name</code>: the name of the task</li> </ul>","tags":["Python API","task run context","context","task run"]},{"location":"api-ref/prefect/utilities/annotations/","title":"annotations","text":"","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations","title":"<code>prefect.utilities.annotations</code>","text":"","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.BaseAnnotation","title":"<code>BaseAnnotation</code>","text":"<p>               Bases: <code>namedtuple('BaseAnnotation', field_names='value')</code>, <code>ABC</code>, <code>Generic[T]</code></p> <p>Base class for Prefect annotation types.</p> <p>Inherits from <code>namedtuple</code> for unpacking support in another tools.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class BaseAnnotation(\n    namedtuple(\"BaseAnnotation\", field_names=\"value\"), ABC, Generic[T]\n):\n    \"\"\"\n    Base class for Prefect annotation types.\n\n    Inherits from `namedtuple` for unpacking support in another tools.\n    \"\"\"\n\n    def unwrap(self) -&gt; T:\n        return self.value\n\n    def rewrap(self, value: T) -&gt; \"BaseAnnotation[T]\":\n        return type(self)(value)\n\n    def __eq__(self, other: object) -&gt; bool:\n        if not type(self) == type(other):\n            return False\n        return self.unwrap() == other.unwrap()\n\n    def __repr__(self) -&gt; str:\n        return f\"{type(self).__name__}({self.value!r})\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.NotSet","title":"<code>NotSet</code>","text":"<p>Singleton to distinguish <code>None</code> from a value that is not provided by the user.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class NotSet:\n    \"\"\"\n    Singleton to distinguish `None` from a value that is not provided by the user.\n    \"\"\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.allow_failure","title":"<code>allow_failure</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Wrapper for states or futures.</p> <p>Indicates that the upstream run for this input can be failed.</p> <p>Generally, Prefect will not allow a downstream run to start if any of its inputs are failed. This annotation allows you to opt into receiving a failed input downstream.</p> <p>If the input is from a failed run, the attached exception will be passed to your function.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class allow_failure(BaseAnnotation[T]):\n    \"\"\"\n    Wrapper for states or futures.\n\n    Indicates that the upstream run for this input can be failed.\n\n    Generally, Prefect will not allow a downstream run to start if any of its inputs\n    are failed. This annotation allows you to opt into receiving a failed input\n    downstream.\n\n    If the input is from a failed run, the attached exception will be passed to your\n    function.\n    \"\"\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.quote","title":"<code>quote</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Simple wrapper to mark an expression as a different type so it will not be coerced by Prefect. For example, if you want to return a state from a flow without having the flow assume that state.</p> <p>quote will also instruct prefect to ignore introspection of the wrapped object when passed as flow or task parameter. Parameter introspection can be a significant performance hit when the object is a large collection, e.g. a large dictionary or DataFrame, and each element needs to be visited. This will disable task dependency tracking for the wrapped object, but likely will increase performance.</p> <pre><code>@task\ndef my_task(df):\n    ...\n\n@flow\ndef my_flow():\n    my_task(quote(df))\n</code></pre> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class quote(BaseAnnotation[T]):\n    \"\"\"\n    Simple wrapper to mark an expression as a different type so it will not be coerced\n    by Prefect. For example, if you want to return a state from a flow without having\n    the flow assume that state.\n\n    quote will also instruct prefect to ignore introspection of the wrapped object\n    when passed as flow or task parameter. Parameter introspection can be a\n    significant performance hit when the object is a large collection,\n    e.g. a large dictionary or DataFrame, and each element needs to be visited. This\n    will disable task dependency tracking for the wrapped object, but likely will\n    increase performance.\n\n    ```\n    @task\n    def my_task(df):\n        ...\n\n    @flow\n    def my_flow():\n        my_task(quote(df))\n    ```\n    \"\"\"\n\n    def unquote(self) -&gt; T:\n        return self.unwrap()\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.unmapped","title":"<code>unmapped</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Wrapper for iterables.</p> <p>Indicates that this input should be sent as-is to all runs created during a mapping operation instead of being split.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class unmapped(BaseAnnotation[T]):\n    \"\"\"\n    Wrapper for iterables.\n\n    Indicates that this input should be sent as-is to all runs created during a mapping\n    operation instead of being split.\n    \"\"\"\n\n    def __getitem__(self, _) -&gt; T:\n        # Internally, this acts as an infinite array where all items are the same value\n        return self.unwrap()\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/asyncutils/","title":"asyncutils","text":"","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils","title":"<code>prefect.utilities.asyncutils</code>","text":"<p>Utilities for interoperability with async functions and workers from various contexts.</p>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherIncomplete","title":"<code>GatherIncomplete</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Used to indicate retrieving gather results before completion</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>class GatherIncomplete(RuntimeError):\n    \"\"\"Used to indicate retrieving gather results before completion\"\"\"\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherTaskGroup","title":"<code>GatherTaskGroup</code>","text":"<p>               Bases: <code>TaskGroup</code></p> <p>A task group that gathers results.</p> <p>AnyIO does not include support <code>gather</code>. This class extends the <code>TaskGroup</code> interface to allow simple gathering.</p> <p>See https://github.com/agronholm/anyio/issues/100</p> <p>This class should be instantiated with <code>create_gather_task_group</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>class GatherTaskGroup(anyio.abc.TaskGroup):\n    \"\"\"\n    A task group that gathers results.\n\n    AnyIO does not include support `gather`. This class extends the `TaskGroup`\n    interface to allow simple gathering.\n\n    See https://github.com/agronholm/anyio/issues/100\n\n    This class should be instantiated with `create_gather_task_group`.\n    \"\"\"\n\n    def __init__(self, task_group: anyio.abc.TaskGroup):\n        self._results: Dict[UUID, Any] = {}\n        # The concrete task group implementation to use\n        self._task_group: anyio.abc.TaskGroup = task_group\n\n    async def _run_and_store(self, key, fn, args):\n        self._results[key] = await fn(*args)\n\n    def start_soon(self, fn, *args) -&gt; UUID:\n        key = uuid4()\n        # Put a placeholder in-case the result is retrieved earlier\n        self._results[key] = GatherIncomplete\n        self._task_group.start_soon(self._run_and_store, key, fn, args)\n        return key\n\n    async def start(self, fn, *args):\n        \"\"\"\n        Since `start` returns the result of `task_status.started()` but here we must\n        return the key instead, we just won't support this method for now.\n        \"\"\"\n        raise RuntimeError(\"`GatherTaskGroup` does not support `start`.\")\n\n    def get_result(self, key: UUID) -&gt; Any:\n        result = self._results[key]\n        if result is GatherIncomplete:\n            raise GatherIncomplete(\n                \"Task is not complete. \"\n                \"Results should not be retrieved until the task group exits.\"\n            )\n        return result\n\n    async def __aenter__(self):\n        await self._task_group.__aenter__()\n        return self\n\n    async def __aexit__(self, *tb):\n        try:\n            retval = await self._task_group.__aexit__(*tb)\n            return retval\n        finally:\n            del self._task_group\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherTaskGroup.start","title":"<code>start</code>  <code>async</code>","text":"<p>Since <code>start</code> returns the result of <code>task_status.started()</code> but here we must return the key instead, we just won't support this method for now.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def start(self, fn, *args):\n    \"\"\"\n    Since `start` returns the result of `task_status.started()` but here we must\n    return the key instead, we just won't support this method for now.\n    \"\"\"\n    raise RuntimeError(\"`GatherTaskGroup` does not support `start`.\")\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.add_event_loop_shutdown_callback","title":"<code>add_event_loop_shutdown_callback</code>  <code>async</code>","text":"<p>Adds a callback to the given callable on event loop closure. The callable must be a coroutine function. It will be awaited when the current event loop is shutting down.</p> <p>Requires use of <code>asyncio.run()</code> which waits for async generator shutdown by default or explicit call of <code>asyncio.shutdown_asyncgens()</code>. If the application is entered with <code>asyncio.run_until_complete()</code> and the user calls <code>asyncio.close()</code> without the generator shutdown call, this will not trigger callbacks.</p> <p>asyncio does not provided any other way to clean up a resource when the event loop is about to close.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def add_event_loop_shutdown_callback(coroutine_fn: Callable[[], Awaitable]):\n    \"\"\"\n    Adds a callback to the given callable on event loop closure. The callable must be\n    a coroutine function. It will be awaited when the current event loop is shutting\n    down.\n\n    Requires use of `asyncio.run()` which waits for async generator shutdown by\n    default or explicit call of `asyncio.shutdown_asyncgens()`. If the application\n    is entered with `asyncio.run_until_complete()` and the user calls\n    `asyncio.close()` without the generator shutdown call, this will not trigger\n    callbacks.\n\n    asyncio does not provided _any_ other way to clean up a resource when the event\n    loop is about to close.\n    \"\"\"\n\n    async def on_shutdown(key):\n        # It appears that EVENT_LOOP_GC_REFS is somehow being garbage collected early.\n        # We hold a reference to it so as to preserve it, at least for the lifetime of\n        # this coroutine. See the issue below for the initial report/discussion:\n        # https://github.com/PrefectHQ/prefect/issues/7709#issuecomment-1560021109\n        _ = EVENT_LOOP_GC_REFS\n        try:\n            yield\n        except GeneratorExit:\n            await coroutine_fn()\n            # Remove self from the garbage collection set\n            EVENT_LOOP_GC_REFS.pop(key)\n\n    # Create the iterator and store it in a global variable so it is not garbage\n    # collected. If the iterator is garbage collected before the event loop closes, the\n    # callback will not run. Since this function does not know the scope of the event\n    # loop that is calling it, a reference with global scope is necessary to ensure\n    # garbage collection does not occur until after event loop closure.\n    key = id(on_shutdown)\n    EVENT_LOOP_GC_REFS[key] = on_shutdown(key)\n\n    # Begin iterating so it will be cleaned up as an incomplete generator\n    try:\n        await EVENT_LOOP_GC_REFS[key].__anext__()\n    # There is a poorly understood edge case we've seen in CI where the key is\n    # removed from the dict before we begin generator iteration.\n    except KeyError:\n        logger.warning(\"The event loop shutdown callback was not properly registered. \")\n        pass\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.create_gather_task_group","title":"<code>create_gather_task_group</code>","text":"<p>Create a new task group that gathers results</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def create_gather_task_group() -&gt; GatherTaskGroup:\n    \"\"\"Create a new task group that gathers results\"\"\"\n    # This function matches the AnyIO API which uses callables since the concrete\n    # task group class depends on the async library being used and cannot be\n    # determined until runtime\n    return GatherTaskGroup(anyio.create_task_group())\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.gather","title":"<code>gather</code>  <code>async</code>","text":"<p>Run calls concurrently and gather their results.</p> <p>Unlike <code>asyncio.gather</code> this expects to receive callables not coroutines. This matches <code>anyio</code> semantics.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def gather(*calls: Callable[[], Coroutine[Any, Any, T]]) -&gt; List[T]:\n    \"\"\"\n    Run calls concurrently and gather their results.\n\n    Unlike `asyncio.gather` this expects to receive _callables_ not _coroutines_.\n    This matches `anyio` semantics.\n    \"\"\"\n    keys = []\n    async with create_gather_task_group() as tg:\n        for call in calls:\n            keys.append(tg.start_soon(call))\n    return [tg.get_result(key) for key in keys]\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.is_async_fn","title":"<code>is_async_fn</code>","text":"<p>Returns <code>True</code> if a function returns a coroutine.</p> <p>See https://github.com/microsoft/pyright/issues/2142 for an example use</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def is_async_fn(\n    func: Union[Callable[P, R], Callable[P, Awaitable[R]]],\n) -&gt; TypeGuard[Callable[P, Awaitable[R]]]:\n    \"\"\"\n    Returns `True` if a function returns a coroutine.\n\n    See https://github.com/microsoft/pyright/issues/2142 for an example use\n    \"\"\"\n    while hasattr(func, \"__wrapped__\"):\n        func = func.__wrapped__\n\n    return inspect.iscoroutinefunction(func)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.is_async_gen_fn","title":"<code>is_async_gen_fn</code>","text":"<p>Returns <code>True</code> if a function is an async generator.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def is_async_gen_fn(func):\n    \"\"\"\n    Returns `True` if a function is an async generator.\n    \"\"\"\n    while hasattr(func, \"__wrapped__\"):\n        func = func.__wrapped__\n\n    return inspect.isasyncgenfunction(func)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.raise_async_exception_in_thread","title":"<code>raise_async_exception_in_thread</code>","text":"<p>Raise an exception in a thread asynchronously.</p> <p>This will not interrupt long-running system calls like <code>sleep</code> or <code>wait</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def raise_async_exception_in_thread(thread: Thread, exc_type: Type[BaseException]):\n    \"\"\"\n    Raise an exception in a thread asynchronously.\n\n    This will not interrupt long-running system calls like `sleep` or `wait`.\n    \"\"\"\n    ret = ctypes.pythonapi.PyThreadState_SetAsyncExc(\n        ctypes.c_long(thread.ident), ctypes.py_object(exc_type)\n    )\n    if ret == 0:\n        raise ValueError(\"Thread not found.\")\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_async_from_worker_thread","title":"<code>run_async_from_worker_thread</code>","text":"<p>Runs an async function in the main thread's event loop, blocking the worker thread until completion</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def run_async_from_worker_thread(\n    __fn: Callable[..., Awaitable[T]], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs an async function in the main thread's event loop, blocking the worker\n    thread until completion\n    \"\"\"\n    call = partial(__fn, *args, **kwargs)\n    return anyio.from_thread.run(call)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync","title":"<code>run_sync</code>","text":"<p>Runs a coroutine from a synchronous context. A thread will be spawned to run the event loop if necessary, which allows coroutines to run in environments like Jupyter notebooks where the event loop runs on the main thread.</p> <p>Parameters:</p> Name Type Description Default <code>coroutine</code> <code>Coroutine[Any, Any, T]</code> <p>The coroutine to run.</p> required <p>Returns:</p> Type Description <code>T</code> <p>The return value of the coroutine.</p> Example <p>Basic usage: <pre><code>async def my_async_function(x: int) -&gt; int:\n    return x + 1\n\nrun_sync(my_async_function(1))\n</code></pre></p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def run_sync(coroutine: Coroutine[Any, Any, T]) -&gt; T:\n    \"\"\"\n    Runs a coroutine from a synchronous context. A thread will be spawned\n    to run the event loop if necessary, which allows coroutines to run in\n    environments like Jupyter notebooks where the event loop runs on the main\n    thread.\n\n    Args:\n        coroutine: The coroutine to run.\n\n    Returns:\n        The return value of the coroutine.\n\n    Example:\n        Basic usage:\n        ```python\n        async def my_async_function(x: int) -&gt; int:\n            return x + 1\n\n        run_sync(my_async_function(1))\n        ```\n    \"\"\"\n    # ensure context variables are properly copied to the async frame\n    context = copy_context()\n    try:\n        loop = asyncio.get_running_loop()\n    except RuntimeError:\n        loop = None\n\n    if loop and loop.is_running():\n        with ThreadPoolExecutor() as executor:\n            future = executor.submit(context.run, asyncio.run, coroutine)\n            return cast(T, future.result())\n    else:\n        return context.run(asyncio.run, coroutine)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync_in_interruptible_worker_thread","title":"<code>run_sync_in_interruptible_worker_thread</code>  <code>async</code>","text":"<p>Runs a sync function in a new interruptible worker thread so that the main thread's event loop is not blocked</p> <p>Unlike the anyio function, this performs best-effort cancellation of the thread using the C API. Cancellation will not interrupt system calls like <code>sleep</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def run_sync_in_interruptible_worker_thread(\n    __fn: Callable[..., T], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs a sync function in a new interruptible worker thread so that the main\n    thread's event loop is not blocked\n\n    Unlike the anyio function, this performs best-effort cancellation of the\n    thread using the C API. Cancellation will not interrupt system calls like\n    `sleep`.\n    \"\"\"\n\n    class NotSet:\n        pass\n\n    thread: Thread = None\n    result = NotSet\n    event = asyncio.Event()\n    loop = asyncio.get_running_loop()\n\n    def capture_worker_thread_and_result():\n        # Captures the worker thread that AnyIO is using to execute the function so\n        # the main thread can perform actions on it\n        nonlocal thread, result\n        try:\n            thread = threading.current_thread()\n            result = __fn(*args, **kwargs)\n        except BaseException as exc:\n            result = exc\n            raise\n        finally:\n            loop.call_soon_threadsafe(event.set)\n\n    async def send_interrupt_to_thread():\n        # This task waits until the result is returned from the thread, if cancellation\n        # occurs during that time, we will raise the exception in the thread as well\n        try:\n            await event.wait()\n        except anyio.get_cancelled_exc_class():\n            # NOTE: We could send a SIGINT here which allow us to interrupt system\n            # calls but the interrupt bubbles from the child thread into the main thread\n            # and there is not a clear way to prevent it.\n            raise_async_exception_in_thread(thread, anyio.get_cancelled_exc_class())\n            raise\n\n    async with anyio.create_task_group() as tg:\n        tg.start_soon(send_interrupt_to_thread)\n        tg.start_soon(\n            partial(\n                anyio.to_thread.run_sync,\n                capture_worker_thread_and_result,\n                abandon_on_cancel=True,\n                limiter=get_thread_limiter(),\n            )\n        )\n\n    assert result is not NotSet\n    return result\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync_in_worker_thread","title":"<code>run_sync_in_worker_thread</code>  <code>async</code>","text":"<p>Runs a sync function in a new worker thread so that the main thread's event loop is not blocked</p> <p>Unlike the anyio function, this defaults to a cancellable thread and does not allow passing arguments to the anyio function so users can pass kwargs to their function.</p> <p>Note that cancellation of threads will not result in interrupted computation, the thread may continue running \u2014 the outcome will just be ignored.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def run_sync_in_worker_thread(\n    __fn: Callable[..., T], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs a sync function in a new worker thread so that the main thread's event loop\n    is not blocked\n\n    Unlike the anyio function, this defaults to a cancellable thread and does not allow\n    passing arguments to the anyio function so users can pass kwargs to their function.\n\n    Note that cancellation of threads will not result in interrupted computation, the\n    thread may continue running \u2014 the outcome will just be ignored.\n    \"\"\"\n    call = partial(__fn, *args, **kwargs)\n    return await anyio.to_thread.run_sync(\n        call, abandon_on_cancel=True, limiter=get_thread_limiter()\n    )\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.sync","title":"<code>sync</code>","text":"<p>Call an async function from a synchronous context. Block until completion.</p> <p>If in an asynchronous context, we will run the code in a separate loop instead of failing but a warning will be displayed since this is not recommended.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def sync(__async_fn: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs) -&gt; T:\n    \"\"\"\n    Call an async function from a synchronous context. Block until completion.\n\n    If in an asynchronous context, we will run the code in a separate loop instead of\n    failing but a warning will be displayed since this is not recommended.\n    \"\"\"\n    if in_async_main_thread():\n        warnings.warn(\n            \"`sync` called from an asynchronous context; \"\n            \"you should `await` the async function directly instead.\"\n        )\n        with start_blocking_portal() as portal:\n            return portal.call(partial(__async_fn, *args, **kwargs))\n    elif in_async_worker_thread():\n        # In a sync context but we can access the event loop thread; send the async\n        # call to the parent\n        return run_async_from_worker_thread(__async_fn, *args, **kwargs)\n    else:\n        # In a sync context and there is no event loop; just create an event loop\n        # to run the async code then tear it down\n        return run_async_in_new_loop(__async_fn, *args, **kwargs)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.sync_compatible","title":"<code>sync_compatible</code>","text":"<p>Converts an async function into a dual async and sync function.</p> <p>When the returned function is called, we will attempt to determine the best way to enter the async function.</p> <ul> <li>If in a thread with a running event loop, we will return the coroutine for the     caller to await. This is normal async behavior.</li> <li>If in a blocking worker thread with access to an event loop in another thread, we     will submit the async method to the event loop.</li> <li>If we cannot find an event loop, we will create a new one and run the async method     then tear down the loop.</li> </ul> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def sync_compatible(async_fn: T) -&gt; T:\n    \"\"\"\n    Converts an async function into a dual async and sync function.\n\n    When the returned function is called, we will attempt to determine the best way\n    to enter the async function.\n\n    - If in a thread with a running event loop, we will return the coroutine for the\n        caller to await. This is normal async behavior.\n    - If in a blocking worker thread with access to an event loop in another thread, we\n        will submit the async method to the event loop.\n    - If we cannot find an event loop, we will create a new one and run the async method\n        then tear down the loop.\n    \"\"\"\n\n    @wraps(async_fn)\n    def coroutine_wrapper(*args, _sync: Optional[bool] = None, **kwargs):\n        from prefect._internal.concurrency.api import create_call, from_sync\n        from prefect._internal.concurrency.calls import get_current_call, logger\n        from prefect._internal.concurrency.event_loop import get_running_loop\n        from prefect._internal.concurrency.threads import get_global_loop\n        from prefect.settings import PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT\n\n        if PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT or _sync is False:\n            return async_fn(*args, **kwargs)\n\n        global_thread_portal = get_global_loop()\n        current_thread = threading.current_thread()\n        current_call = get_current_call()\n        current_loop = get_running_loop()\n\n        if (\n            current_thread.ident == global_thread_portal.thread.ident\n            and _sync is not True\n        ):\n            logger.debug(f\"{async_fn} --&gt; return coroutine for internal await\")\n            # In the prefect async context; return the coro for us to await\n            return async_fn(*args, **kwargs)\n        elif (\n            in_async_main_thread()\n            and (not current_call or is_async_fn(current_call.fn))\n            and _sync is not True\n        ):\n            # In the main async context; return the coro for them to await\n            logger.debug(f\"{async_fn} --&gt; return coroutine for user await\")\n            return async_fn(*args, **kwargs)\n        elif in_async_worker_thread():\n            # In a sync context but we can access the event loop thread; send the async\n            # call to the parent\n            return run_async_from_worker_thread(async_fn, *args, **kwargs)\n        elif current_loop is not None:\n            logger.debug(f\"{async_fn} --&gt; run async in global loop portal\")\n            # An event loop is already present but we are in a sync context, run the\n            # call in Prefect's event loop thread\n            return from_sync.call_soon_in_loop_thread(\n                create_call(async_fn, *args, **kwargs)\n            ).result()\n        else:\n            logger.debug(f\"{async_fn} --&gt; run async in new loop\")\n            # Run in a new event loop, but use a `Call` for nested context detection\n            call = create_call(async_fn, *args, **kwargs)\n            return call()\n\n    # TODO: This is breaking type hints on the callable... mypy is behind the curve\n    #       on argument annotations. We can still fix this for editors though.\n    if is_async_fn(async_fn):\n        wrapper = coroutine_wrapper\n    elif is_async_gen_fn(async_fn):\n        raise ValueError(\"Async generators cannot yet be marked as `sync_compatible`\")\n    else:\n        raise TypeError(\"The decorated function must be async.\")\n\n    wrapper.aio = async_fn\n    return wrapper\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/callables/","title":"callables","text":"","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables","title":"<code>prefect.utilities.callables</code>","text":"<p>Utilities for working with Python callables.</p>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.ParameterSchema","title":"<code>ParameterSchema</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Simple data model corresponding to an OpenAPI <code>Schema</code>.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>class ParameterSchema(pydantic.BaseModel):\n    \"\"\"Simple data model corresponding to an OpenAPI `Schema`.\"\"\"\n\n    title: Literal[\"Parameters\"] = \"Parameters\"\n    type: Literal[\"object\"] = \"object\"\n    properties: Dict[str, Any] = pydantic.Field(default_factory=dict)\n    required: List[str] = None\n    definitions: Optional[Dict[str, Any]] = None\n\n    def dict(self, *args, **kwargs):\n        \"\"\"Exclude `None` fields by default to comply with\n        the OpenAPI spec.\n        \"\"\"\n        kwargs.setdefault(\"exclude_none\", True)\n        return super().dict(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.ParameterSchema.dict","title":"<code>dict</code>","text":"<p>Exclude <code>None</code> fields by default to comply with the OpenAPI spec.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def dict(self, *args, **kwargs):\n    \"\"\"Exclude `None` fields by default to comply with\n    the OpenAPI spec.\n    \"\"\"\n    kwargs.setdefault(\"exclude_none\", True)\n    return super().dict(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.call_with_parameters","title":"<code>call_with_parameters</code>","text":"<p>Call a function with parameters extracted with <code>get_call_parameters</code></p> <p>The function must have an identical signature to the original function or this will fail. If you need to send to a function with a different signature, extract the args/kwargs using <code>parameters_to_positional_and_keyword</code> directly</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def call_with_parameters(fn: Callable, parameters: Dict[str, Any]):\n    \"\"\"\n    Call a function with parameters extracted with `get_call_parameters`\n\n    The function _must_ have an identical signature to the original function or this\n    will fail. If you need to send to a function with a different signature, extract\n    the args/kwargs using `parameters_to_positional_and_keyword` directly\n    \"\"\"\n    args, kwargs = parameters_to_args_kwargs(fn, parameters)\n    return fn(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.cloudpickle_wrapped_call","title":"<code>cloudpickle_wrapped_call</code>","text":"<p>Serializes a function call using cloudpickle then returns a callable which will execute that call and return a cloudpickle serialized return value</p> <p>This is particularly useful for sending calls to libraries that only use the Python built-in pickler (e.g. <code>anyio.to_process</code> and <code>multiprocessing</code>) but may require a wider range of pickling support.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def cloudpickle_wrapped_call(\n    __fn: Callable, *args: Any, **kwargs: Any\n) -&gt; Callable[[], bytes]:\n    \"\"\"\n    Serializes a function call using cloudpickle then returns a callable which will\n    execute that call and return a cloudpickle serialized return value\n\n    This is particularly useful for sending calls to libraries that only use the Python\n    built-in pickler (e.g. `anyio.to_process` and `multiprocessing`) but may require\n    a wider range of pickling support.\n    \"\"\"\n    payload = cloudpickle.dumps((__fn, args, kwargs))\n    return partial(_run_serialized_call, payload)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.collapse_variadic_parameters","title":"<code>collapse_variadic_parameters</code>","text":"<p>Given a parameter dictionary, move any parameters stored not present in the signature into the variadic keyword argument.</p> <p>Example:</p> <pre><code>```python\ndef foo(a, b, **kwargs):\n    pass\n\nparameters = {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\ncollapse_variadic_parameters(foo, parameters)\n# {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n```\n</code></pre> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def collapse_variadic_parameters(\n    fn: Callable, parameters: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Given a parameter dictionary, move any parameters stored not present in the\n    signature into the variadic keyword argument.\n\n    Example:\n\n        ```python\n        def foo(a, b, **kwargs):\n            pass\n\n        parameters = {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n        collapse_variadic_parameters(foo, parameters)\n        # {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n        ```\n    \"\"\"\n    signature_parameters = inspect.signature(fn).parameters\n    variadic_key = None\n    for key, parameter in signature_parameters.items():\n        if parameter.kind == parameter.VAR_KEYWORD:\n            variadic_key = key\n            break\n\n    missing_parameters = set(parameters.keys()) - set(signature_parameters.keys())\n\n    if not variadic_key and missing_parameters:\n        raise ValueError(\n            f\"Signature for {fn} does not include any variadic keyword argument \"\n            \"but parameters were given that are not present in the signature.\"\n        )\n\n    if variadic_key and not missing_parameters:\n        # variadic key is present but no missing parameters, return parameters unchanged\n        return parameters\n\n    new_parameters = parameters.copy()\n    if variadic_key:\n        new_parameters[variadic_key] = {}\n\n    for key in missing_parameters:\n        new_parameters[variadic_key][key] = new_parameters.pop(key)\n\n    return new_parameters\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.explode_variadic_parameter","title":"<code>explode_variadic_parameter</code>","text":"<p>Given a parameter dictionary, move any parameters stored in a variadic keyword argument parameter (i.e. **kwargs) into the top level.</p> <p>Example:</p> <pre><code>```python\ndef foo(a, b, **kwargs):\n    pass\n\nparameters = {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\nexplode_variadic_parameter(foo, parameters)\n# {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n```\n</code></pre> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def explode_variadic_parameter(\n    fn: Callable, parameters: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Given a parameter dictionary, move any parameters stored in a variadic keyword\n    argument parameter (i.e. **kwargs) into the top level.\n\n    Example:\n\n        ```python\n        def foo(a, b, **kwargs):\n            pass\n\n        parameters = {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n        explode_variadic_parameter(foo, parameters)\n        # {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n        ```\n    \"\"\"\n    variadic_key = None\n    for key, parameter in inspect.signature(fn).parameters.items():\n        if parameter.kind == parameter.VAR_KEYWORD:\n            variadic_key = key\n            break\n\n    if not variadic_key:\n        return parameters\n\n    new_parameters = parameters.copy()\n    for key, value in new_parameters.pop(variadic_key, {}).items():\n        new_parameters[key] = value\n\n    return new_parameters\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.generate_parameter_schema","title":"<code>generate_parameter_schema</code>","text":"<p>Generate a parameter schema from a function signature and docstrings.</p> <p>To get a signature from a function, use <code>inspect.signature(fn)</code> or <code>_generate_signature_from_source(source_code, func_name)</code>.</p> <p>Parameters:</p> Name Type Description Default <code>signature</code> <code>Signature</code> <p>The function signature.</p> required <code>docstrings</code> <code>Dict[str, str]</code> <p>A dictionary mapping parameter names to docstrings.</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>The parameter schema.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def generate_parameter_schema(\n    signature: inspect.Signature, docstrings: Dict[str, str]\n) -&gt; ParameterSchema:\n    \"\"\"\n    Generate a parameter schema from a function signature and docstrings.\n\n    To get a signature from a function, use `inspect.signature(fn)` or\n    `_generate_signature_from_source(source_code, func_name)`.\n\n    Args:\n        signature: The function signature.\n        docstrings: A dictionary mapping parameter names to docstrings.\n\n    Returns:\n        ParameterSchema: The parameter schema.\n    \"\"\"\n\n    model_fields = {}\n    aliases = {}\n\n    class ModelConfig:\n        arbitrary_types_allowed = True\n\n    if HAS_PYDANTIC_V2 and not has_v1_type_as_param(signature):\n        create_schema = create_v2_schema\n        process_params = process_v2_params\n    else:\n        create_schema = create_v1_schema\n        process_params = process_v1_params\n\n    for position, param in enumerate(signature.parameters.values()):\n        name, type_, field = process_params(\n            param, position=position, docstrings=docstrings, aliases=aliases\n        )\n        # Generate a Pydantic model at each step so we can check if this parameter\n        # type supports schema generation\n        try:\n            create_schema(\n                \"CheckParameter\", model_cfg=ModelConfig, **{name: (type_, field)}\n            )\n        except (ValueError, TypeError):\n            # This field's type is not valid for schema creation, update it to `Any`\n            type_ = Any\n        model_fields[name] = (type_, field)\n\n    # Generate the final model and schema\n    schema = create_schema(\"Parameters\", model_cfg=ModelConfig, **model_fields)\n    return ParameterSchema(**schema)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.get_call_parameters","title":"<code>get_call_parameters</code>","text":"<p>Bind a call to a function to get parameter/value mapping. Default values on the signature will be included if not overridden.</p> <p>Raises a ParameterBindError if the arguments/kwargs are not valid for the function</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def get_call_parameters(\n    fn: Callable,\n    call_args: Tuple[Any, ...],\n    call_kwargs: Dict[str, Any],\n    apply_defaults: bool = True,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Bind a call to a function to get parameter/value mapping. Default values on the\n    signature will be included if not overridden.\n\n    Raises a ParameterBindError if the arguments/kwargs are not valid for the function\n    \"\"\"\n    try:\n        bound_signature = inspect.signature(fn).bind(*call_args, **call_kwargs)\n    except TypeError as exc:\n        raise ParameterBindError.from_bind_failure(fn, exc, call_args, call_kwargs)\n\n    if apply_defaults:\n        bound_signature.apply_defaults()\n\n    # We cast from `OrderedDict` to `dict` because Dask will not convert futures in an\n    # ordered dictionary to values during execution; this is the default behavior in\n    # Python 3.9 anyway.\n    return dict(bound_signature.arguments)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.get_parameter_defaults","title":"<code>get_parameter_defaults</code>","text":"<p>Get default parameter values for a callable.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def get_parameter_defaults(\n    fn: Callable,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Get default parameter values for a callable.\n    \"\"\"\n    signature = inspect.signature(fn)\n\n    parameter_defaults = {}\n\n    for name, param in signature.parameters.items():\n        if param.default is not signature.empty:\n            parameter_defaults[name] = param.default\n\n    return parameter_defaults\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_docstrings","title":"<code>parameter_docstrings</code>","text":"<p>Given a docstring in Google docstring format, parse the parameter section and return a dictionary that maps parameter names to docstring.</p> <p>Parameters:</p> Name Type Description Default <code>docstring</code> <code>Optional[str]</code> <p>The function's docstring.</p> required <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>Mapping from parameter names to docstrings.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_docstrings(docstring: Optional[str]) -&gt; Dict[str, str]:\n    \"\"\"\n    Given a docstring in Google docstring format, parse the parameter section\n    and return a dictionary that maps parameter names to docstring.\n\n    Args:\n        docstring: The function's docstring.\n\n    Returns:\n        Mapping from parameter names to docstrings.\n    \"\"\"\n    param_docstrings = {}\n\n    if not docstring:\n        return param_docstrings\n\n    with disable_logger(\"griffe.docstrings.google\"), disable_logger(\n        \"griffe.agents.nodes\"\n    ):\n        parsed = parse(Docstring(docstring), Parser.google)\n        for section in parsed:\n            if section.kind != DocstringSectionKind.parameters:\n                continue\n            param_docstrings = {\n                parameter.name: parameter.description for parameter in section.value\n            }\n\n    return param_docstrings\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_schema","title":"<code>parameter_schema</code>","text":"<p>Given a function, generates an OpenAPI-compatible description of the function's arguments, including:     - name     - typing information     - whether it is required     - a default value     - additional constraints (like possible enum values)</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable</code> <p>The function whose arguments will be serialized</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>the argument schema</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_schema(fn: Callable) -&gt; ParameterSchema:\n    \"\"\"Given a function, generates an OpenAPI-compatible description\n    of the function's arguments, including:\n        - name\n        - typing information\n        - whether it is required\n        - a default value\n        - additional constraints (like possible enum values)\n\n    Args:\n        fn (Callable): The function whose arguments will be serialized\n\n    Returns:\n        ParameterSchema: the argument schema\n    \"\"\"\n    try:\n        signature = inspect.signature(fn, eval_str=True)  # novm\n    except (NameError, TypeError):\n        # `eval_str` is not available in Python &lt; 3.10\n        signature = inspect.signature(fn)\n\n    docstrings = parameter_docstrings(inspect.getdoc(fn))\n\n    return generate_parameter_schema(signature, docstrings)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_schema_from_entrypoint","title":"<code>parameter_schema_from_entrypoint</code>","text":"<p>Generate a parameter schema from an entrypoint string.</p> <p>Will load the source code of the function and extract the signature and docstring to generate the schema.</p> <p>Useful for generating a schema for a function when instantiating the function may not be possible due to missing imports or other issues.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>A string representing the entrypoint to a function. The string should be in the format of <code>module.path.to.function:do_stuff</code>.</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>The parameter schema for the function.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_schema_from_entrypoint(entrypoint: str) -&gt; ParameterSchema:\n    \"\"\"\n    Generate a parameter schema from an entrypoint string.\n\n    Will load the source code of the function and extract the signature and docstring\n    to generate the schema.\n\n    Useful for generating a schema for a function when instantiating the function may\n    not be possible due to missing imports or other issues.\n\n    Args:\n        entrypoint: A string representing the entrypoint to a function. The string\n            should be in the format of `module.path.to.function:do_stuff`.\n\n    Returns:\n        ParameterSchema: The parameter schema for the function.\n    \"\"\"\n    filepath = None\n    if \":\" in entrypoint:\n        # split by the last colon once to handle Windows paths with drive letters i.e C:\\path\\to\\file.py:do_stuff\n        path, func_name = entrypoint.rsplit(\":\", maxsplit=1)\n        source_code = Path(path).read_text()\n        filepath = path\n    else:\n        path, func_name = entrypoint.rsplit(\".\", maxsplit=1)\n        spec = importlib.util.find_spec(path)\n        if not spec or not spec.origin:\n            raise ValueError(f\"Could not find module {path!r}\")\n        source_code = Path(spec.origin).read_text()\n    signature = _generate_signature_from_source(source_code, func_name, filepath)\n    docstring = _get_docstring_from_source(source_code, func_name)\n    return generate_parameter_schema(signature, parameter_docstrings(docstring))\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameters_to_args_kwargs","title":"<code>parameters_to_args_kwargs</code>","text":"<p>Convert a <code>parameters</code> dictionary to positional and keyword arguments</p> <p>The function must have an identical signature to the original function or this will return an empty tuple and dict.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameters_to_args_kwargs(\n    fn: Callable,\n    parameters: Dict[str, Any],\n) -&gt; Tuple[Tuple[Any, ...], Dict[str, Any]]:\n    \"\"\"\n    Convert a `parameters` dictionary to positional and keyword arguments\n\n    The function _must_ have an identical signature to the original function or this\n    will return an empty tuple and dict.\n    \"\"\"\n    function_params = dict(inspect.signature(fn).parameters).keys()\n    # Check for parameters that are not present in the function signature\n    unknown_params = parameters.keys() - function_params\n    if unknown_params:\n        raise SignatureMismatchError.from_bad_params(\n            list(function_params), list(parameters.keys())\n        )\n    bound_signature = inspect.signature(fn).bind_partial()\n    bound_signature.arguments = parameters\n\n    return bound_signature.args, bound_signature.kwargs\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.raise_for_reserved_arguments","title":"<code>raise_for_reserved_arguments</code>","text":"<p>Raise a ReservedArgumentError if <code>fn</code> has any parameters that conflict with the names contained in <code>reserved_arguments</code>.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def raise_for_reserved_arguments(fn: Callable, reserved_arguments: Iterable[str]):\n    \"\"\"Raise a ReservedArgumentError if `fn` has any parameters that conflict\n    with the names contained in `reserved_arguments`.\"\"\"\n    function_paremeters = inspect.signature(fn).parameters\n\n    for argument in reserved_arguments:\n        if argument in function_paremeters:\n            raise ReservedArgumentError(\n                f\"{argument!r} is a reserved argument name and cannot be used.\"\n            )\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/collections/","title":"collections","text":"","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections","title":"<code>prefect.utilities.collections</code>","text":"<p>Utilities for extensions of and operations on Python collections.</p>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.AutoEnum","title":"<code>AutoEnum</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>An enum class that automatically generates value from variable names.</p> <p>This guards against common errors where variable names are updated but values are not.</p> <p>In addition, because AutoEnums inherit from <code>str</code>, they are automatically JSON-serializable.</p> <p>See https://docs.python.org/3/library/enum.html#using-automatic-values</p> Example <pre><code>class MyEnum(AutoEnum):\n    RED = AutoEnum.auto() # equivalent to RED = 'RED'\n    BLUE = AutoEnum.auto() # equivalent to BLUE = 'BLUE'\n</code></pre> Source code in <code>prefect/utilities/collections.py</code> <pre><code>class AutoEnum(str, Enum):\n    \"\"\"\n    An enum class that automatically generates value from variable names.\n\n    This guards against common errors where variable names are updated but values are\n    not.\n\n    In addition, because AutoEnums inherit from `str`, they are automatically\n    JSON-serializable.\n\n    See https://docs.python.org/3/library/enum.html#using-automatic-values\n\n    Example:\n        ```python\n        class MyEnum(AutoEnum):\n            RED = AutoEnum.auto() # equivalent to RED = 'RED'\n            BLUE = AutoEnum.auto() # equivalent to BLUE = 'BLUE'\n        ```\n    \"\"\"\n\n    def _generate_next_value_(name, start, count, last_values):\n        return name\n\n    @staticmethod\n    def auto():\n        \"\"\"\n        Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n        \"\"\"\n        return auto()\n\n    def __repr__(self) -&gt; str:\n        return f\"{type(self).__name__}.{self.value}\"\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.AutoEnum.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.StopVisiting","title":"<code>StopVisiting</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>A special exception used to stop recursive visits in <code>visit_collection</code>.</p> <p>When raised, the expression is returned without modification and recursive visits in that path will end.</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>class StopVisiting(BaseException):\n    \"\"\"\n    A special exception used to stop recursive visits in `visit_collection`.\n\n    When raised, the expression is returned without modification and recursive visits\n    in that path will end.\n    \"\"\"\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.batched_iterable","title":"<code>batched_iterable</code>","text":"<p>Yield batches of a certain size from an iterable</p> <p>Parameters:</p> Name Type Description Default <code>iterable</code> <code>Iterable</code> <p>An iterable</p> required <code>size</code> <code>int</code> <p>The batch size to return</p> required <p>Yields:</p> Name Type Description <code>tuple</code> <code>T</code> <p>A batch of the iterable</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def batched_iterable(iterable: Iterable[T], size: int) -&gt; Iterator[Tuple[T, ...]]:\n    \"\"\"\n    Yield batches of a certain size from an iterable\n\n    Args:\n        iterable (Iterable): An iterable\n        size (int): The batch size to return\n\n    Yields:\n        tuple: A batch of the iterable\n    \"\"\"\n    it = iter(iterable)\n    while True:\n        batch = tuple(itertools.islice(it, size))\n        if not batch:\n            break\n        yield batch\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.dict_to_flatdict","title":"<code>dict_to_flatdict</code>","text":"<p>Converts a (nested) dictionary to a flattened representation.</p> <p>Each key of the flat dict will be a CompoundKey tuple containing the \"chain of keys\" for the corresponding value.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>dict</code> <p>The dictionary to flatten</p> required <code>_parent</code> <code>Tuple</code> <p>The current parent for recursion</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[Tuple[KT, ...], Any]</code> <p>A flattened dict of the same type as dct</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def dict_to_flatdict(\n    dct: Dict[KT, Union[Any, Dict[KT, Any]]], _parent: Tuple[KT, ...] = None\n) -&gt; Dict[Tuple[KT, ...], Any]:\n    \"\"\"Converts a (nested) dictionary to a flattened representation.\n\n    Each key of the flat dict will be a CompoundKey tuple containing the \"chain of keys\"\n    for the corresponding value.\n\n    Args:\n        dct (dict): The dictionary to flatten\n        _parent (Tuple, optional): The current parent for recursion\n\n    Returns:\n        A flattened dict of the same type as dct\n    \"\"\"\n    typ = cast(Type[Dict[Tuple[KT, ...], Any]], type(dct))\n    items: List[Tuple[Tuple[KT, ...], Any]] = []\n    parent = _parent or tuple()\n\n    for k, v in dct.items():\n        k_parent = tuple(parent + (k,))\n        # if v is a non-empty dict, recurse\n        if isinstance(v, dict) and v:\n            items.extend(dict_to_flatdict(v, _parent=k_parent).items())\n        else:\n            items.append((k_parent, v))\n    return typ(items)\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.extract_instances","title":"<code>extract_instances</code>","text":"<p>Extract objects from a file and returns a dict of type -&gt; instances</p> <p>Parameters:</p> Name Type Description Default <code>objects</code> <code>Iterable</code> <p>An iterable of objects</p> required <code>types</code> <code>Union[Type[T], Tuple[Type[T], ...]]</code> <p>A type or tuple of types to extract, defaults to all objects</p> <code>object</code> <p>Returns:</p> Type Description <code>Union[List[T], Dict[Type[T], T]]</code> <p>If a single type is given: a list of instances of that type</p> <code>Union[List[T], Dict[Type[T], T]]</code> <p>If a tuple of types is given: a mapping of type to a list of instances</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def extract_instances(\n    objects: Iterable,\n    types: Union[Type[T], Tuple[Type[T], ...]] = object,\n) -&gt; Union[List[T], Dict[Type[T], T]]:\n    \"\"\"\n    Extract objects from a file and returns a dict of type -&gt; instances\n\n    Args:\n        objects: An iterable of objects\n        types: A type or tuple of types to extract, defaults to all objects\n\n    Returns:\n        If a single type is given: a list of instances of that type\n        If a tuple of types is given: a mapping of type to a list of instances\n    \"\"\"\n    types = ensure_iterable(types)\n\n    # Create a mapping of type -&gt; instance from the exec values\n    ret = defaultdict(list)\n\n    for o in objects:\n        # We iterate here so that the key is the passed type rather than type(o)\n        for type_ in types:\n            if isinstance(o, type_):\n                ret[type_].append(o)\n\n    if len(types) == 1:\n        return ret[types[0]]\n\n    return ret\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.flatdict_to_dict","title":"<code>flatdict_to_dict</code>","text":"<p>Converts a flattened dictionary back to a nested dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>dict</code> <p>The dictionary to be nested. Each key should be a tuple of keys as generated by <code>dict_to_flatdict</code></p> required <p>Returns     A nested dict of the same type as dct</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def flatdict_to_dict(\n    dct: Dict[Tuple[KT, ...], VT],\n) -&gt; Dict[KT, Union[VT, Dict[KT, VT]]]:\n    \"\"\"Converts a flattened dictionary back to a nested dictionary.\n\n    Args:\n        dct (dict): The dictionary to be nested. Each key should be a tuple of keys\n            as generated by `dict_to_flatdict`\n\n    Returns\n        A nested dict of the same type as dct\n    \"\"\"\n    typ = type(dct)\n    result = cast(Dict[KT, Union[VT, Dict[KT, VT]]], typ())\n    for key_tuple, value in dct.items():\n        current_dict = result\n        for prefix_key in key_tuple[:-1]:\n            # Build nested dictionaries up for the current key tuple\n            # Use `setdefault` in case the nested dict has already been created\n            current_dict = current_dict.setdefault(prefix_key, typ())  # type: ignore\n        # Set the value\n        current_dict[key_tuple[-1]] = value\n\n    return result\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.get_from_dict","title":"<code>get_from_dict</code>","text":"<p>Fetch a value from a nested dictionary or list using a sequence of keys.</p> <p>This function allows to fetch a value from a deeply nested structure of dictionaries and lists using either a dot-separated string or a list of keys. If a requested key does not exist, the function returns the provided default value.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>Dict</code> <p>The nested dictionary or list from which to fetch the value.</p> required <code>keys</code> <code>Union[str, List[str]]</code> <p>The sequence of keys to use for access. Can be a dot-separated string or a list of keys. List indices can be included in the sequence as either integer keys or as string indices in square brackets.</p> required <code>default</code> <code>Any</code> <p>The default value to return if the requested key path does not exist. Defaults to None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Any</code> <p>The fetched value if the key exists, or the default value if it does not.</p> <p>get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]') 2 get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1]) 2 get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default') 'default'</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def get_from_dict(dct: Dict, keys: Union[str, List[str]], default: Any = None) -&gt; Any:\n    \"\"\"\n    Fetch a value from a nested dictionary or list using a sequence of keys.\n\n    This function allows to fetch a value from a deeply nested structure\n    of dictionaries and lists using either a dot-separated string or a list\n    of keys. If a requested key does not exist, the function returns the\n    provided default value.\n\n    Args:\n        dct: The nested dictionary or list from which to fetch the value.\n        keys: The sequence of keys to use for access. Can be a\n            dot-separated string or a list of keys. List indices can be included\n            in the sequence as either integer keys or as string indices in square\n            brackets.\n        default: The default value to return if the requested key path does not\n            exist. Defaults to None.\n\n    Returns:\n        The fetched value if the key exists, or the default value if it does not.\n\n    Examples:\n    &gt;&gt;&gt; get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]')\n    2\n    &gt;&gt;&gt; get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1])\n    2\n    &gt;&gt;&gt; get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default')\n    'default'\n    \"\"\"\n    if isinstance(keys, str):\n        keys = keys.replace(\"[\", \".\").replace(\"]\", \"\").split(\".\")\n    try:\n        for key in keys:\n            try:\n                # Try to cast to int to handle list indices\n                key = int(key)\n            except ValueError:\n                # If it's not an int, use the key as-is\n                # for dict lookup\n                pass\n            dct = dct[key]\n        return dct\n    except (TypeError, KeyError, IndexError):\n        return default\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.isiterable","title":"<code>isiterable</code>","text":"<p>Return a boolean indicating if an object is iterable.</p> <p>Excludes types that are iterable but typically used as singletons: - str - bytes - IO objects</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def isiterable(obj: Any) -&gt; bool:\n    \"\"\"\n    Return a boolean indicating if an object is iterable.\n\n    Excludes types that are iterable but typically used as singletons:\n    - str\n    - bytes\n    - IO objects\n    \"\"\"\n    try:\n        iter(obj)\n    except TypeError:\n        return False\n    else:\n        return not isinstance(obj, (str, bytes, io.IOBase))\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.remove_nested_keys","title":"<code>remove_nested_keys</code>","text":"<p>Recurses a dictionary returns a copy without all keys that match an entry in <code>key_to_remove</code>. Return <code>obj</code> unchanged if not a dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>keys_to_remove</code> <code>List[Hashable]</code> <p>A list of keys to remove from obj obj: The object to remove keys from.</p> required <p>Returns:</p> Type Description <p><code>obj</code> without keys matching an entry in <code>keys_to_remove</code> if <code>obj</code> is a dictionary. <code>obj</code> if <code>obj</code> is not a dictionary.</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def remove_nested_keys(keys_to_remove: List[Hashable], obj):\n    \"\"\"\n    Recurses a dictionary returns a copy without all keys that match an entry in\n    `key_to_remove`. Return `obj` unchanged if not a dictionary.\n\n    Args:\n        keys_to_remove: A list of keys to remove from obj obj: The object to remove keys\n            from.\n\n    Returns:\n        `obj` without keys matching an entry in `keys_to_remove` if `obj` is a\n            dictionary. `obj` if `obj` is not a dictionary.\n    \"\"\"\n    if not isinstance(obj, dict):\n        return obj\n    return {\n        key: remove_nested_keys(keys_to_remove, value)\n        for key, value in obj.items()\n        if key not in keys_to_remove\n    }\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.visit_collection","title":"<code>visit_collection</code>","text":"<p>This function visits every element of an arbitrary Python collection. If an element is a Python collection, it will be visited recursively. If an element is not a collection, <code>visit_fn</code> will be called with the element. The return value of <code>visit_fn</code> can be used to alter the element if <code>return_data</code> is set.</p> <p>Note that when using <code>return_data</code> a copy of each collection is created to avoid mutating the original object. This may have significant performance penalties and should only be used if you intend to transform the collection.</p> <p>Supported types: - List - Tuple - Set - Dict (note: keys are also visited recursively) - Dataclass - Pydantic model - Prefect annotations</p> <p>Parameters:</p> Name Type Description Default <code>expr</code> <code>Any</code> <p>a Python object or expression</p> required <code>visit_fn</code> <code>Callable[[Any], Awaitable[Any]]</code> <p>an async function that will be applied to every non-collection element of expr.</p> required <code>return_data</code> <code>bool</code> <p>if <code>True</code>, a copy of <code>expr</code> containing data modified by <code>visit_fn</code> will be returned. This is slower than <code>return_data=False</code> (the default).</p> <code>False</code> <code>max_depth</code> <code>int</code> <p>Controls the depth of recursive visitation. If set to zero, no recursion will occur. If set to a positive integer N, visitation will only descend to N layers deep. If set to any negative integer, no limit will be enforced and recursion will continue until terminal items are reached. By default, recursion is unlimited.</p> <code>-1</code> <code>context</code> <code>Optional[dict]</code> <p>An optional dictionary. If passed, the context will be sent to each call to the <code>visit_fn</code>. The context can be mutated by each visitor and will be available for later visits to expressions at the given depth. Values will not be available \"up\" a level from a given expression.</p> <p>The context will be automatically populated with an 'annotation' key when visiting collections within a <code>BaseAnnotation</code> type. This requires the caller to pass <code>context={}</code> and will not be activated by default.</p> <code>None</code> <code>remove_annotations</code> <code>bool</code> <p>If set, annotations will be replaced by their contents. By default, annotations are preserved but their contents are visited.</p> <code>False</code> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def visit_collection(\n    expr,\n    visit_fn: Callable[[Any], Any],\n    return_data: bool = False,\n    max_depth: int = -1,\n    context: Optional[dict] = None,\n    remove_annotations: bool = False,\n):\n    \"\"\"\n    This function visits every element of an arbitrary Python collection. If an element\n    is a Python collection, it will be visited recursively. If an element is not a\n    collection, `visit_fn` will be called with the element. The return value of\n    `visit_fn` can be used to alter the element if `return_data` is set.\n\n    Note that when using `return_data` a copy of each collection is created to avoid\n    mutating the original object. This may have significant performance penalties and\n    should only be used if you intend to transform the collection.\n\n    Supported types:\n    - List\n    - Tuple\n    - Set\n    - Dict (note: keys are also visited recursively)\n    - Dataclass\n    - Pydantic model\n    - Prefect annotations\n\n    Args:\n        expr (Any): a Python object or expression\n        visit_fn (Callable[[Any], Awaitable[Any]]): an async function that\n            will be applied to every non-collection element of expr.\n        return_data (bool): if `True`, a copy of `expr` containing data modified\n            by `visit_fn` will be returned. This is slower than `return_data=False`\n            (the default).\n        max_depth: Controls the depth of recursive visitation. If set to zero, no\n            recursion will occur. If set to a positive integer N, visitation will only\n            descend to N layers deep. If set to any negative integer, no limit will be\n            enforced and recursion will continue until terminal items are reached. By\n            default, recursion is unlimited.\n        context: An optional dictionary. If passed, the context will be sent to each\n            call to the `visit_fn`. The context can be mutated by each visitor and will\n            be available for later visits to expressions at the given depth. Values\n            will not be available \"up\" a level from a given expression.\n\n            The context will be automatically populated with an 'annotation' key when\n            visiting collections within a `BaseAnnotation` type. This requires the\n            caller to pass `context={}` and will not be activated by default.\n        remove_annotations: If set, annotations will be replaced by their contents. By\n            default, annotations are preserved but their contents are visited.\n    \"\"\"\n\n    def visit_nested(expr):\n        # Utility for a recursive call, preserving options and updating the depth.\n        return visit_collection(\n            expr,\n            visit_fn=visit_fn,\n            return_data=return_data,\n            remove_annotations=remove_annotations,\n            max_depth=max_depth - 1,\n            # Copy the context on nested calls so it does not \"propagate up\"\n            context=context.copy() if context is not None else None,\n        )\n\n    def visit_expression(expr):\n        if context is not None:\n            return visit_fn(expr, context)\n        else:\n            return visit_fn(expr)\n\n    # Visit every expression\n    try:\n        result = visit_expression(expr)\n    except StopVisiting:\n        max_depth = 0\n        result = expr\n\n    if return_data:\n        # Only mutate the expression while returning data, otherwise it could be null\n        expr = result\n\n    # Then, visit every child of the expression recursively\n\n    # If we have reached the maximum depth, do not perform any recursion\n    if max_depth == 0:\n        return result if return_data else None\n\n    # Get the expression type; treat iterators like lists\n    typ = list if isinstance(expr, IteratorABC) and isiterable(expr) else type(expr)\n    typ = cast(type, typ)  # mypy treats this as 'object' otherwise and complains\n\n    # Then visit every item in the expression if it is a collection\n    if isinstance(expr, Mock):\n        # Do not attempt to recurse into mock objects\n        result = expr\n\n    elif isinstance(expr, BaseAnnotation):\n        if context is not None:\n            context[\"annotation\"] = expr\n        value = visit_nested(expr.unwrap())\n\n        if remove_annotations:\n            result = value if return_data else None\n        else:\n            result = expr.rewrap(value) if return_data else None\n\n    elif typ in (list, tuple, set):\n        items = [visit_nested(o) for o in expr]\n        result = typ(items) if return_data else None\n\n    elif typ in (dict, OrderedDict):\n        assert isinstance(expr, (dict, OrderedDict))  # typecheck assertion\n        items = [(visit_nested(k), visit_nested(v)) for k, v in expr.items()]\n        result = typ(items) if return_data else None\n\n    elif is_dataclass(expr) and not isinstance(expr, type):\n        values = [visit_nested(getattr(expr, f.name)) for f in fields(expr)]\n        items = {field.name: value for field, value in zip(fields(expr), values)}\n        result = typ(**items) if return_data else None\n\n    elif isinstance(expr, pydantic.BaseModel):\n        # NOTE: This implementation *does not* traverse private attributes\n        # Pydantic does not expose extras in `__fields__` so we use `__fields_set__`\n        # as well to get all of the relevant attributes\n        # Check for presence of attrs even if they're in the field set due to pydantic#4916\n        model_fields = {\n            f for f in expr.__fields_set__.union(expr.__fields__) if hasattr(expr, f)\n        }\n        items = [visit_nested(getattr(expr, key)) for key in model_fields]\n\n        if return_data:\n            # Collect fields with aliases so reconstruction can use the correct field name\n            aliases = {\n                key: value.alias\n                for key, value in expr.__fields__.items()\n                if value.has_alias\n            }\n\n            model_instance = typ(\n                **{\n                    aliases.get(key) or key: value\n                    for key, value in zip(model_fields, items)\n                }\n            )\n\n            # Private attributes are not included in `__fields_set__` but we do not want\n            # to drop them from the model so we restore them after constructing a new\n            # model\n            for attr in expr.__private_attributes__:\n                # Use `object.__setattr__` to avoid errors on immutable models\n                object.__setattr__(model_instance, attr, getattr(expr, attr))\n\n            # Preserve data about which fields were explicitly set on the original model\n            object.__setattr__(model_instance, \"__fields_set__\", expr.__fields_set__)\n            result = model_instance\n        else:\n            result = None\n\n    else:\n        result = result if return_data else None\n\n    return result\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/compat/","title":"compat","text":"","tags":["Python API","utilities","compatibility"]},{"location":"api-ref/prefect/utilities/compat/#prefect.utilities.compat","title":"<code>prefect.utilities.compat</code>","text":"<p>Utilities for Python version compatibility</p>","tags":["Python API","utilities","compatibility"]},{"location":"api-ref/prefect/utilities/context/","title":"context","text":"","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/context/#prefect.utilities.context","title":"<code>prefect.utilities.context</code>","text":"","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/context/#prefect.utilities.context.get_task_and_flow_run_ids","title":"<code>get_task_and_flow_run_ids</code>","text":"<p>Get the task run and flow run ids from the context, if available.</p> <p>Returns:</p> Type Description <code>Tuple[Optional[UUID], Optional[UUID]]</code> <p>Tuple[Optional[UUID], Optional[UUID]]: a tuple of the task run id and flow run id</p> Source code in <code>prefect/utilities/context.py</code> <pre><code>def get_task_and_flow_run_ids() -&gt; Tuple[Optional[UUID], Optional[UUID]]:\n    \"\"\"\n    Get the task run and flow run ids from the context, if available.\n\n    Returns:\n        Tuple[Optional[UUID], Optional[UUID]]: a tuple of the task run id and flow run id\n    \"\"\"\n    return get_task_run_id(), get_flow_run_id()\n</code></pre>","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/dispatch/","title":"dispatch","text":"","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch","title":"<code>prefect.utilities.dispatch</code>","text":"<p>Provides methods for performing dynamic dispatch for actions on base type to one of its subtypes.</p> <p>Example:</p> <pre><code>@register_base_type\nclass Base:\n    @classmethod\n    def __dispatch_key__(cls):\n        return cls.__name__.lower()\n\n\nclass Foo(Base):\n    ...\n\nkey = get_dispatch_key(Foo)  # 'foo'\nlookup_type(Base, key) # Foo\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.get_dispatch_key","title":"<code>get_dispatch_key</code>","text":"<p>Retrieve the unique dispatch key for a class type or instance.</p> <p>This key is defined at the <code>__dispatch_key__</code> attribute. If it is a callable, it will be resolved.</p> <p>If <code>allow_missing</code> is <code>False</code>, an exception will be raised if the attribute is not defined or the key is null. If <code>True</code>, <code>None</code> will be returned in these cases.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def get_dispatch_key(\n    cls_or_instance: Any, allow_missing: bool = False\n) -&gt; Optional[str]:\n    \"\"\"\n    Retrieve the unique dispatch key for a class type or instance.\n\n    This key is defined at the `__dispatch_key__` attribute. If it is a callable, it\n    will be resolved.\n\n    If `allow_missing` is `False`, an exception will be raised if the attribute is not\n    defined or the key is null. If `True`, `None` will be returned in these cases.\n    \"\"\"\n    dispatch_key = getattr(cls_or_instance, \"__dispatch_key__\", None)\n\n    type_name = (\n        cls_or_instance.__name__\n        if isinstance(cls_or_instance, type)\n        else type(cls_or_instance).__name__\n    )\n\n    if dispatch_key is None:\n        if allow_missing:\n            return None\n        raise ValueError(\n            f\"Type {type_name!r} does not define a value for \"\n            \"'__dispatch_key__' which is required for registry lookup.\"\n        )\n\n    if callable(dispatch_key):\n        dispatch_key = dispatch_key()\n\n    if allow_missing and dispatch_key is None:\n        return None\n\n    if not isinstance(dispatch_key, str):\n        raise TypeError(\n            f\"Type {type_name!r} has a '__dispatch_key__' of type \"\n            f\"{type(dispatch_key).__name__} but a type of 'str' is required.\"\n        )\n\n    return dispatch_key\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.get_registry_for_type","title":"<code>get_registry_for_type</code>","text":"<p>Get the first matching registry for a class or any of its base classes.</p> <p>If not found, <code>None</code> is returned.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def get_registry_for_type(cls: T) -&gt; Optional[Dict[str, T]]:\n    \"\"\"\n    Get the first matching registry for a class or any of its base classes.\n\n    If not found, `None` is returned.\n    \"\"\"\n    return next(\n        filter(\n            lambda registry: registry is not None,\n            (_TYPE_REGISTRIES.get(cls) for cls in cls.mro()),\n        ),\n        None,\n    )\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.lookup_type","title":"<code>lookup_type</code>","text":"<p>Look up a dispatch key in the type registry for the given class.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def lookup_type(cls: T, dispatch_key: str) -&gt; T:\n    \"\"\"\n    Look up a dispatch key in the type registry for the given class.\n    \"\"\"\n    # Get the first matching registry for the class or one of its bases\n    registry = get_registry_for_type(cls)\n\n    # Look up this type in the registry\n    subcls = registry.get(dispatch_key)\n\n    if subcls is None:\n        raise KeyError(\n            f\"No class found for dispatch key {dispatch_key!r} in registry for type \"\n            f\"{cls.__name__!r}.\"\n        )\n\n    return subcls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.register_base_type","title":"<code>register_base_type</code>","text":"<p>Register a base type allowing child types to be registered for dispatch with <code>register_type</code>.</p> <p>The base class may or may not define a <code>__dispatch_key__</code> to allow lookups of the base type.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def register_base_type(cls: T) -&gt; T:\n    \"\"\"\n    Register a base type allowing child types to be registered for dispatch with\n    `register_type`.\n\n    The base class may or may not define a `__dispatch_key__` to allow lookups of the\n    base type.\n    \"\"\"\n    registry = _TYPE_REGISTRIES.setdefault(cls, {})\n    base_key = get_dispatch_key(cls, allow_missing=True)\n    if base_key is not None:\n        registry[base_key] = cls\n\n    # Add automatic subtype registration\n    cls.__init_subclass_original__ = getattr(cls, \"__init_subclass__\")\n    cls.__init_subclass__ = _register_subclass_of_base_type\n\n    return cls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.register_type","title":"<code>register_type</code>","text":"<p>Register a type for lookup with dispatch.</p> <p>The type or one of its parents must define a unique <code>__dispatch_key__</code>.</p> <p>One of the classes base types must be registered using <code>register_base_type</code>.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def register_type(cls: T) -&gt; T:\n    \"\"\"\n    Register a type for lookup with dispatch.\n\n    The type or one of its parents must define a unique `__dispatch_key__`.\n\n    One of the classes base types must be registered using `register_base_type`.\n    \"\"\"\n    # Lookup the registry for this type\n    registry = get_registry_for_type(cls)\n\n    # Check if a base type is registered\n    if registry is None:\n        # Include a description of registered base types\n        known = \", \".join(repr(base.__name__) for base in _TYPE_REGISTRIES)\n        known_message = (\n            f\" Did you mean to inherit from one of the following known types: {known}.\"\n            if known\n            else \"\"\n        )\n\n        # And a list of all base types for the type they tried to register\n        bases = \", \".join(\n            repr(base.__name__) for base in cls.mro() if base not in (object, cls)\n        )\n\n        raise ValueError(\n            f\"No registry found for type {cls.__name__!r} with bases {bases}.\"\n            + known_message\n        )\n\n    key = get_dispatch_key(cls)\n    existing_value = registry.get(key)\n    if existing_value is not None and id(existing_value) != id(cls):\n        # Get line numbers for debugging\n        file = inspect.getsourcefile(cls)\n        line_number = inspect.getsourcelines(cls)[1]\n        existing_file = inspect.getsourcefile(existing_value)\n        existing_line_number = inspect.getsourcelines(existing_value)[1]\n        warnings.warn(\n            f\"Type {cls.__name__!r} at {file}:{line_number} has key {key!r} that \"\n            f\"matches existing registered type {existing_value.__name__!r} from \"\n            f\"{existing_file}:{existing_line_number}. The existing type will be \"\n            \"overridden.\"\n        )\n\n    # Add to the registry\n    registry[key] = cls\n\n    return cls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dockerutils/","title":"dockerutils","text":"","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils","title":"<code>prefect.utilities.dockerutils</code>","text":"","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.BuildError","title":"<code>BuildError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a Docker build fails</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class BuildError(Exception):\n    \"\"\"Raised when a Docker build fails\"\"\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder","title":"<code>ImageBuilder</code>","text":"<p>An interface for preparing Docker build contexts and building images</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class ImageBuilder:\n    \"\"\"An interface for preparing Docker build contexts and building images\"\"\"\n\n    base_directory: Path\n    context: Optional[Path]\n    platform: Optional[str]\n    dockerfile_lines: List[str]\n\n    def __init__(\n        self,\n        base_image: str,\n        base_directory: Path = None,\n        platform: str = None,\n        context: Path = None,\n    ):\n        \"\"\"Create an ImageBuilder\n\n        Args:\n            base_image: the base image to use\n            base_directory: the starting point on your host for relative file locations,\n                defaulting to the current directory\n            context: use this path as the build context (if not provided, will create a\n                temporary directory for the context)\n\n        Returns:\n            The image ID\n        \"\"\"\n        self.base_directory = base_directory or context or Path().absolute()\n        self.temporary_directory = None\n        self.context = context\n        self.platform = platform\n        self.dockerfile_lines = []\n\n        if self.context:\n            dockerfile_path: Path = self.context / \"Dockerfile\"\n            if dockerfile_path.exists():\n                raise ValueError(f\"There is already a Dockerfile at {context}\")\n\n        self.add_line(f\"FROM {base_image}\")\n\n    def __enter__(self) -&gt; Self:\n        if self.context and not self.temporary_directory:\n            return self\n\n        self.temporary_directory = TemporaryDirectory()\n        self.context = Path(self.temporary_directory.__enter__())\n        return self\n\n    def __exit__(\n        self, exc: Type[BaseException], value: BaseException, traceback: TracebackType\n    ) -&gt; None:\n        if not self.temporary_directory:\n            return\n\n        self.temporary_directory.__exit__(exc, value, traceback)\n        self.temporary_directory = None\n        self.context = None\n\n    def add_line(self, line: str) -&gt; None:\n        \"\"\"Add a line to this image's Dockerfile\"\"\"\n        self.add_lines([line])\n\n    def add_lines(self, lines: Iterable[str]) -&gt; None:\n        \"\"\"Add lines to this image's Dockerfile\"\"\"\n        self.dockerfile_lines.extend(lines)\n\n    def copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]):\n        \"\"\"Copy a file to this image\"\"\"\n        if not self.context:\n            raise Exception(\"No context available\")\n\n        if not isinstance(destination, PurePosixPath):\n            destination = PurePosixPath(destination)\n\n        if not isinstance(source, Path):\n            source = Path(source)\n\n        if source.is_absolute():\n            source = source.resolve().relative_to(self.base_directory)\n\n        if self.temporary_directory:\n            os.makedirs(self.context / source.parent, exist_ok=True)\n\n            if source.is_dir():\n                shutil.copytree(self.base_directory / source, self.context / source)\n            else:\n                shutil.copy2(self.base_directory / source, self.context / source)\n\n        self.add_line(f\"COPY {source} {destination}\")\n\n    def write_text(self, text: str, destination: Union[str, PurePosixPath]):\n        if not self.context:\n            raise Exception(\"No context available\")\n\n        if not isinstance(destination, PurePosixPath):\n            destination = PurePosixPath(destination)\n\n        source_hash = hashlib.sha256(text.encode()).hexdigest()\n        (self.context / f\".{source_hash}\").write_text(text)\n        self.add_line(f\"COPY .{source_hash} {destination}\")\n\n    def build(\n        self, pull: bool = False, stream_progress_to: Optional[TextIO] = None\n    ) -&gt; str:\n        \"\"\"Build the Docker image from the current state of the ImageBuilder\n\n        Args:\n            pull: True to pull the base image during the build\n            stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO)\n                that will collect the build output as it is reported by Docker\n\n        Returns:\n            The image ID\n        \"\"\"\n        dockerfile_path: Path = self.context / \"Dockerfile\"\n\n        with dockerfile_path.open(\"w\") as dockerfile:\n            dockerfile.writelines(line + \"\\n\" for line in self.dockerfile_lines)\n\n        try:\n            return build_image(\n                self.context,\n                platform=self.platform,\n                pull=pull,\n                stream_progress_to=stream_progress_to,\n            )\n        finally:\n            os.unlink(dockerfile_path)\n\n    def assert_has_line(self, line: str) -&gt; None:\n        \"\"\"Asserts that the given line is in the Dockerfile\"\"\"\n        all_lines = \"\\n\".join(\n            [f\"  {i+1:&gt;3}: {line}\" for i, line in enumerate(self.dockerfile_lines)]\n        )\n        message = (\n            f\"Expected {line!r} not found in Dockerfile.  Dockerfile:\\n{all_lines}\"\n        )\n        assert line in self.dockerfile_lines, message\n\n    def assert_line_absent(self, line: str) -&gt; None:\n        \"\"\"Asserts that the given line is absent from the Dockerfile\"\"\"\n        if line not in self.dockerfile_lines:\n            return\n\n        i = self.dockerfile_lines.index(line)\n\n        surrounding_lines = \"\\n\".join(\n            [\n                f\"  {i+1:&gt;3}: {line}\"\n                for i, line in enumerate(self.dockerfile_lines[i - 2 : i + 2])\n            ]\n        )\n        message = (\n            f\"Unexpected {line!r} found in Dockerfile at line {i+1}.  \"\n            f\"Surrounding lines:\\n{surrounding_lines}\"\n        )\n\n        assert line not in self.dockerfile_lines, message\n\n    def assert_line_before(self, first: str, second: str) -&gt; None:\n        \"\"\"Asserts that the first line appears before the second line\"\"\"\n        self.assert_has_line(first)\n        self.assert_has_line(second)\n\n        first_index = self.dockerfile_lines.index(first)\n        second_index = self.dockerfile_lines.index(second)\n\n        surrounding_lines = \"\\n\".join(\n            [\n                f\"  {i+1:&gt;3}: {line}\"\n                for i, line in enumerate(\n                    self.dockerfile_lines[second_index - 2 : first_index + 2]\n                )\n            ]\n        )\n\n        message = (\n            f\"Expected {first!r} to appear before {second!r} in the Dockerfile, but \"\n            f\"{first!r} was at line {first_index+1} and {second!r} as at line \"\n            f\"{second_index+1}.  Surrounding lines:\\n{surrounding_lines}\"\n        )\n\n        assert first_index &lt; second_index, message\n\n    def assert_line_after(self, second: str, first: str) -&gt; None:\n        \"\"\"Asserts that the second line appears after the first line\"\"\"\n        self.assert_line_before(first, second)\n\n    def assert_has_file(self, source: Path, container_path: PurePosixPath) -&gt; None:\n        \"\"\"Asserts that the given file or directory will be copied into the container\n        at the given path\"\"\"\n        if source.is_absolute():\n            source = source.relative_to(self.base_directory)\n\n        self.assert_has_line(f\"COPY {source} {container_path}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.add_line","title":"<code>add_line</code>","text":"<p>Add a line to this image's Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def add_line(self, line: str) -&gt; None:\n    \"\"\"Add a line to this image's Dockerfile\"\"\"\n    self.add_lines([line])\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.add_lines","title":"<code>add_lines</code>","text":"<p>Add lines to this image's Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def add_lines(self, lines: Iterable[str]) -&gt; None:\n    \"\"\"Add lines to this image's Dockerfile\"\"\"\n    self.dockerfile_lines.extend(lines)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_has_file","title":"<code>assert_has_file</code>","text":"<p>Asserts that the given file or directory will be copied into the container at the given path</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_has_file(self, source: Path, container_path: PurePosixPath) -&gt; None:\n    \"\"\"Asserts that the given file or directory will be copied into the container\n    at the given path\"\"\"\n    if source.is_absolute():\n        source = source.relative_to(self.base_directory)\n\n    self.assert_has_line(f\"COPY {source} {container_path}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_has_line","title":"<code>assert_has_line</code>","text":"<p>Asserts that the given line is in the Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_has_line(self, line: str) -&gt; None:\n    \"\"\"Asserts that the given line is in the Dockerfile\"\"\"\n    all_lines = \"\\n\".join(\n        [f\"  {i+1:&gt;3}: {line}\" for i, line in enumerate(self.dockerfile_lines)]\n    )\n    message = (\n        f\"Expected {line!r} not found in Dockerfile.  Dockerfile:\\n{all_lines}\"\n    )\n    assert line in self.dockerfile_lines, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_absent","title":"<code>assert_line_absent</code>","text":"<p>Asserts that the given line is absent from the Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_absent(self, line: str) -&gt; None:\n    \"\"\"Asserts that the given line is absent from the Dockerfile\"\"\"\n    if line not in self.dockerfile_lines:\n        return\n\n    i = self.dockerfile_lines.index(line)\n\n    surrounding_lines = \"\\n\".join(\n        [\n            f\"  {i+1:&gt;3}: {line}\"\n            for i, line in enumerate(self.dockerfile_lines[i - 2 : i + 2])\n        ]\n    )\n    message = (\n        f\"Unexpected {line!r} found in Dockerfile at line {i+1}.  \"\n        f\"Surrounding lines:\\n{surrounding_lines}\"\n    )\n\n    assert line not in self.dockerfile_lines, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_after","title":"<code>assert_line_after</code>","text":"<p>Asserts that the second line appears after the first line</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_after(self, second: str, first: str) -&gt; None:\n    \"\"\"Asserts that the second line appears after the first line\"\"\"\n    self.assert_line_before(first, second)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_before","title":"<code>assert_line_before</code>","text":"<p>Asserts that the first line appears before the second line</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_before(self, first: str, second: str) -&gt; None:\n    \"\"\"Asserts that the first line appears before the second line\"\"\"\n    self.assert_has_line(first)\n    self.assert_has_line(second)\n\n    first_index = self.dockerfile_lines.index(first)\n    second_index = self.dockerfile_lines.index(second)\n\n    surrounding_lines = \"\\n\".join(\n        [\n            f\"  {i+1:&gt;3}: {line}\"\n            for i, line in enumerate(\n                self.dockerfile_lines[second_index - 2 : first_index + 2]\n            )\n        ]\n    )\n\n    message = (\n        f\"Expected {first!r} to appear before {second!r} in the Dockerfile, but \"\n        f\"{first!r} was at line {first_index+1} and {second!r} as at line \"\n        f\"{second_index+1}.  Surrounding lines:\\n{surrounding_lines}\"\n    )\n\n    assert first_index &lt; second_index, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.build","title":"<code>build</code>","text":"<p>Build the Docker image from the current state of the ImageBuilder</p> <p>Parameters:</p> Name Type Description Default <code>pull</code> <code>bool</code> <p>True to pull the base image during the build</p> <code>False</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The image ID</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def build(\n    self, pull: bool = False, stream_progress_to: Optional[TextIO] = None\n) -&gt; str:\n    \"\"\"Build the Docker image from the current state of the ImageBuilder\n\n    Args:\n        pull: True to pull the base image during the build\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO)\n            that will collect the build output as it is reported by Docker\n\n    Returns:\n        The image ID\n    \"\"\"\n    dockerfile_path: Path = self.context / \"Dockerfile\"\n\n    with dockerfile_path.open(\"w\") as dockerfile:\n        dockerfile.writelines(line + \"\\n\" for line in self.dockerfile_lines)\n\n    try:\n        return build_image(\n            self.context,\n            platform=self.platform,\n            pull=pull,\n            stream_progress_to=stream_progress_to,\n        )\n    finally:\n        os.unlink(dockerfile_path)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.copy","title":"<code>copy</code>","text":"<p>Copy a file to this image</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]):\n    \"\"\"Copy a file to this image\"\"\"\n    if not self.context:\n        raise Exception(\"No context available\")\n\n    if not isinstance(destination, PurePosixPath):\n        destination = PurePosixPath(destination)\n\n    if not isinstance(source, Path):\n        source = Path(source)\n\n    if source.is_absolute():\n        source = source.resolve().relative_to(self.base_directory)\n\n    if self.temporary_directory:\n        os.makedirs(self.context / source.parent, exist_ok=True)\n\n        if source.is_dir():\n            shutil.copytree(self.base_directory / source, self.context / source)\n        else:\n            shutil.copy2(self.base_directory / source, self.context / source)\n\n    self.add_line(f\"COPY {source} {destination}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.PushError","title":"<code>PushError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a Docker image push fails</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class PushError(Exception):\n    \"\"\"Raised when a Docker image push fails\"\"\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.build_image","title":"<code>build_image</code>","text":"<p>Builds a Docker image, returning the image ID</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>Path</code> <p>the root directory for the Docker build context</p> required <code>dockerfile</code> <code>str</code> <p>the path to the Dockerfile, relative to the context</p> <code>'Dockerfile'</code> <code>tag</code> <code>Optional[str]</code> <p>the tag to give this image</p> <code>None</code> <code>pull</code> <code>bool</code> <p>True to pull the base image during the build</p> <code>False</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The image ID</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@silence_docker_warnings()\ndef build_image(\n    context: Path,\n    dockerfile: str = \"Dockerfile\",\n    tag: Optional[str] = None,\n    pull: bool = False,\n    platform: str = None,\n    stream_progress_to: Optional[TextIO] = None,\n    **kwargs,\n) -&gt; str:\n    \"\"\"Builds a Docker image, returning the image ID\n\n    Args:\n        context: the root directory for the Docker build context\n        dockerfile: the path to the Dockerfile, relative to the context\n        tag: the tag to give this image\n        pull: True to pull the base image during the build\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that\n            will collect the build output as it is reported by Docker\n\n    Returns:\n        The image ID\n    \"\"\"\n\n    if not context:\n        raise ValueError(\"context required to build an image\")\n\n    if not Path(context).exists():\n        raise ValueError(f\"Context path {context} does not exist\")\n\n    kwargs = {key: kwargs[key] for key in kwargs if key not in [\"decode\", \"labels\"]}\n\n    image_id = None\n    with docker_client() as client:\n        events = client.api.build(\n            path=str(context),\n            tag=tag,\n            dockerfile=dockerfile,\n            pull=pull,\n            decode=True,\n            labels=IMAGE_LABELS,\n            platform=platform,\n            **kwargs,\n        )\n\n        try:\n            for event in events:\n                if \"stream\" in event:\n                    if not stream_progress_to:\n                        continue\n                    stream_progress_to.write(event[\"stream\"])\n                    stream_progress_to.flush()\n                elif \"aux\" in event:\n                    image_id = event[\"aux\"][\"ID\"]\n                elif \"error\" in event:\n                    raise BuildError(event[\"error\"])\n                elif \"message\" in event:\n                    raise BuildError(event[\"message\"])\n        except docker.errors.APIError as e:\n            raise BuildError(e.explanation) from e\n\n    assert image_id, \"The Docker daemon did not return an image ID\"\n    return image_id\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.docker_client","title":"<code>docker_client</code>","text":"<p>Get the environmentally-configured Docker client</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@contextmanager\ndef docker_client() -&gt; Generator[\"DockerClient\", None, None]:\n    \"\"\"Get the environmentally-configured Docker client\"\"\"\n    client = None\n    try:\n        with silence_docker_warnings():\n            client = docker.DockerClient.from_env()\n\n            yield client\n    except docker.errors.DockerException as exc:\n        raise RuntimeError(\n            \"This error is often thrown because Docker is not running. Please ensure Docker is running.\"\n        ) from exc\n    finally:\n        client is not None and client.close()\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.format_outlier_version_name","title":"<code>format_outlier_version_name</code>","text":"<p>Formats outlier docker version names to pass <code>packaging.version.parse</code> validation - Current cases are simple, but creates stub for more complicated formatting if eventually needed. - Example outlier versions that throw a parsing exception:   - \"20.10.0-ce\" (variant of community edition label)   - \"20.10.0-ee\" (variant of enterprise edition label)</p> <p>Parameters:</p> Name Type Description Default <code>version</code> <code>str</code> <p>raw docker version value</p> required <p>Returns:</p> Name Type Description <code>str</code> <p>value that can pass <code>packaging.version.parse</code> validation</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def format_outlier_version_name(version: str):\n    \"\"\"\n    Formats outlier docker version names to pass `packaging.version.parse` validation\n    - Current cases are simple, but creates stub for more complicated formatting if eventually needed.\n    - Example outlier versions that throw a parsing exception:\n      - \"20.10.0-ce\" (variant of community edition label)\n      - \"20.10.0-ee\" (variant of enterprise edition label)\n\n    Args:\n        version (str): raw docker version value\n\n    Returns:\n        str: value that can pass `packaging.version.parse` validation\n    \"\"\"\n    return version.replace(\"-ce\", \"\").replace(\"-ee\", \"\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.generate_default_dockerfile","title":"<code>generate_default_dockerfile</code>","text":"<p>Generates a default Dockerfile used for deploying flows. The Dockerfile is written to a temporary file and yielded. The temporary file is removed after the context manager exits.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>context</code> <p>The context to use for the Dockerfile. Defaults to the current working directory.</p> required Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@contextmanager\ndef generate_default_dockerfile(context: Optional[Path] = None):\n    \"\"\"\n    Generates a default Dockerfile used for deploying flows. The Dockerfile is written\n    to a temporary file and yielded. The temporary file is removed after the context\n    manager exits.\n\n    Args:\n        - context: The context to use for the Dockerfile. Defaults to\n            the current working directory.\n    \"\"\"\n    if not context:\n        context = Path.cwd()\n    lines = []\n    base_image = get_prefect_image_name()\n    lines.append(f\"FROM {base_image}\")\n    dir_name = context.name\n\n    if (context / \"requirements.txt\").exists():\n        lines.append(f\"COPY requirements.txt /opt/prefect/{dir_name}/requirements.txt\")\n        lines.append(\n            f\"RUN python -m pip install -r /opt/prefect/{dir_name}/requirements.txt\"\n        )\n\n    lines.append(f\"COPY . /opt/prefect/{dir_name}/\")\n    lines.append(f\"WORKDIR /opt/prefect/{dir_name}/\")\n\n    temp_dockerfile = context / \"Dockerfile\"\n    if Path(temp_dockerfile).exists():\n        raise RuntimeError(\n            \"Failed to generate Dockerfile. Dockerfile already exists in the\"\n            \" current directory.\"\n        )\n\n    with Path(temp_dockerfile).open(\"w\") as f:\n        f.writelines(line + \"\\n\" for line in lines)\n\n    try:\n        yield temp_dockerfile\n    finally:\n        temp_dockerfile.unlink()\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.get_prefect_image_name","title":"<code>get_prefect_image_name</code>","text":"<p>Get the Prefect image name matching the current Prefect and Python versions.</p> <p>Parameters:</p> Name Type Description Default <code>prefect_version</code> <code>str</code> <p>An optional override for the Prefect version.</p> <code>None</code> <code>python_version</code> <code>str</code> <p>An optional override for the Python version; must be at the minor level e.g. '3.9'.</p> <code>None</code> <code>flavor</code> <code>str</code> <p>An optional alternative image flavor to build, like 'conda'</p> <code>None</code> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def get_prefect_image_name(\n    prefect_version: str = None, python_version: str = None, flavor: str = None\n) -&gt; str:\n    \"\"\"\n    Get the Prefect image name matching the current Prefect and Python versions.\n\n    Args:\n        prefect_version: An optional override for the Prefect version.\n        python_version: An optional override for the Python version; must be at the\n            minor level e.g. '3.9'.\n        flavor: An optional alternative image flavor to build, like 'conda'\n    \"\"\"\n    parsed_version = (prefect_version or prefect.__version__).split(\"+\")\n    is_prod_build = len(parsed_version) == 1\n    prefect_version = (\n        parsed_version[0]\n        if is_prod_build\n        else \"sha-\" + prefect.__version_info__[\"full-revisionid\"][:7]\n    )\n\n    python_version = python_version or python_version_minor()\n\n    tag = slugify(\n        f\"{prefect_version}-python{python_version}\" + (f\"-{flavor}\" if flavor else \"\"),\n        lowercase=False,\n        max_length=128,\n        # Docker allows these characters for tag names\n        regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n    )\n\n    image = \"prefect\" if is_prod_build else \"prefect-dev\"\n    return f\"prefecthq/{image}:{tag}\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.parse_image_tag","title":"<code>parse_image_tag</code>","text":"<p>Parse Docker Image String</p> <ul> <li>If a tag exists, this function parses and returns the image registry and tag,   separately as a tuple.</li> <li>Example 1: 'prefecthq/prefect:latest' -&gt; ('prefecthq/prefect', 'latest')</li> <li>Example 2: 'hostname.io:5050/folder/subfolder:latest' -&gt; ('hostname.io:5050/folder/subfolder', 'latest')</li> <li>Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0</li> <li>Image building tools typically enforce this standard</li> </ul> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of Docker Image</p> required Return Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def parse_image_tag(name: str) -&gt; Tuple[str, Optional[str]]:\n    \"\"\"\n    Parse Docker Image String\n\n    - If a tag exists, this function parses and returns the image registry and tag,\n      separately as a tuple.\n      - Example 1: 'prefecthq/prefect:latest' -&gt; ('prefecthq/prefect', 'latest')\n      - Example 2: 'hostname.io:5050/folder/subfolder:latest' -&gt; ('hostname.io:5050/folder/subfolder', 'latest')\n    - Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0\n      - Image building tools typically enforce this standard\n\n    Args:\n        name (str): Name of Docker Image\n\n    Return:\n        tuple: image registry, image tag\n    \"\"\"\n    tag = None\n    name_parts = name.split(\"/\")\n    # First handles the simplest image names (DockerHub-based, index-free, potentionally with a tag)\n    # - Example: simplename:latest\n    if len(name_parts) == 1:\n        if \":\" in name_parts[0]:\n            image_name, tag = name_parts[0].split(\":\")\n        else:\n            image_name = name_parts[0]\n    else:\n        # 1. Separates index (hostname.io or prefecthq) from path:tag (folder/subfolder:latest or prefect:latest)\n        # 2. Separates path and tag (if tag exists)\n        # 3. Reunites index and path (without tag) as image name\n        index_name = name_parts[0]\n        image_path = \"/\".join(name_parts[1:])\n        if \":\" in image_path:\n            image_path, tag = image_path.split(\":\")\n        image_name = f\"{index_name}/{image_path}\"\n    return image_name, tag\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.push_image","title":"<code>push_image</code>","text":"<p>Pushes a local image to a Docker registry, returning the registry-qualified tag for that image</p> <p>This assumes that the environment's Docker daemon is already authenticated to the given registry, and currently makes no attempt to authenticate.</p> <p>Parameters:</p> Name Type Description Default <code>image_id</code> <code>str</code> <p>a Docker image ID</p> required <code>registry_url</code> <code>str</code> <p>the URL of a Docker registry</p> required <code>name</code> <code>str</code> <p>the name of this image</p> required <code>tag</code> <code>str</code> <p>the tag to give this image (defaults to a short representation of the image's ID)</p> <code>None</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>A registry-qualified tag, like my-registry.example.com/my-image:abcdefg</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@silence_docker_warnings()\ndef push_image(\n    image_id: str,\n    registry_url: str,\n    name: str,\n    tag: Optional[str] = None,\n    stream_progress_to: Optional[TextIO] = None,\n) -&gt; str:\n    \"\"\"Pushes a local image to a Docker registry, returning the registry-qualified tag\n    for that image\n\n    This assumes that the environment's Docker daemon is already authenticated to the\n    given registry, and currently makes no attempt to authenticate.\n\n    Args:\n        image_id (str): a Docker image ID\n        registry_url (str): the URL of a Docker registry\n        name (str): the name of this image\n        tag (str): the tag to give this image (defaults to a short representation of\n            the image's ID)\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that\n            will collect the build output as it is reported by Docker\n\n    Returns:\n        A registry-qualified tag, like my-registry.example.com/my-image:abcdefg\n    \"\"\"\n\n    if not tag:\n        tag = slugify(pendulum.now(\"utc\").isoformat())\n\n    _, registry, _, _, _ = urlsplit(registry_url)\n    repository = f\"{registry}/{name}\"\n\n    with docker_client() as client:\n        image: \"docker.Image\" = client.images.get(image_id)\n        image.tag(repository, tag=tag)\n        events = client.api.push(repository, tag=tag, stream=True, decode=True)\n        try:\n            for event in events:\n                if \"status\" in event:\n                    if not stream_progress_to:\n                        continue\n                    stream_progress_to.write(event[\"status\"])\n                    if \"progress\" in event:\n                        stream_progress_to.write(\" \" + event[\"progress\"])\n                    stream_progress_to.write(\"\\n\")\n                    stream_progress_to.flush()\n                elif \"error\" in event:\n                    raise PushError(event[\"error\"])\n        finally:\n            client.api.remove_image(f\"{repository}:{tag}\", noprune=True)\n\n    return f\"{repository}:{tag}\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.split_repository_path","title":"<code>split_repository_path</code>","text":"<p>Splits a Docker repository path into its namespace and repository components.</p> <p>Parameters:</p> Name Type Description Default <code>repository_path</code> <code>str</code> <p>The Docker repository path to split.</p> required <p>Returns:</p> Type Description <code>Tuple[Optional[str], str]</code> <p>Tuple[Optional[str], str]: A tuple containing the namespace and repository components. - namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present. - repository (Optionals[str]): The repository name.</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def split_repository_path(repository_path: str) -&gt; Tuple[Optional[str], str]:\n    \"\"\"\n    Splits a Docker repository path into its namespace and repository components.\n\n    Args:\n        repository_path: The Docker repository path to split.\n\n    Returns:\n        Tuple[Optional[str], str]: A tuple containing the namespace and repository components.\n            - namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present.\n            - repository (Optionals[str]): The repository name.\n    \"\"\"\n    parts = repository_path.split(\"/\", 2)\n\n    # Check if the path includes a registry and organization or just organization/repository\n    if len(parts) == 3 or (len(parts) == 2 and (\".\" in parts[0] or \":\" in parts[0])):\n        # Namespace includes registry and organization\n        namespace = \"/\".join(parts[:-1])\n        repository = parts[-1]\n    elif len(parts) == 2:\n        # Only organization/repository provided, so namespace is just the first part\n        namespace = parts[0]\n        repository = parts[1]\n    else:\n        # No namespace provided\n        namespace = None\n        repository = parts[0]\n\n    return namespace, repository\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.to_run_command","title":"<code>to_run_command</code>","text":"<p>Convert a process-style list of command arguments to a single Dockerfile RUN instruction.</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def to_run_command(command: List[str]) -&gt; str:\n    \"\"\"\n    Convert a process-style list of command arguments to a single Dockerfile RUN\n    instruction.\n    \"\"\"\n    if not command:\n        return \"\"\n\n    run_command = f\"RUN {command[0]}\"\n    if len(command) &gt; 1:\n        run_command += \" \" + \" \".join([repr(arg) for arg in command[1:]])\n\n    # TODO: Consider performing text-wrapping to improve readability of the generated\n    #       Dockerfile\n    # return textwrap.wrap(\n    #     run_command,\n    #     subsequent_indent=\" \" * 4,\n    #     break_on_hyphens=False,\n    #     break_long_words=False\n    # )\n\n    return run_command\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/filesystem/","title":"filesystem","text":"","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem","title":"<code>prefect.utilities.filesystem</code>","text":"<p>Utilities for working with file systems</p>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.create_default_ignore_file","title":"<code>create_default_ignore_file</code>","text":"<p>Creates default ignore file in the provided path if one does not already exist; returns boolean specifying whether a file was created.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def create_default_ignore_file(path: str) -&gt; bool:\n    \"\"\"\n    Creates default ignore file in the provided path if one does not already exist; returns boolean specifying\n    whether a file was created.\n    \"\"\"\n    path = pathlib.Path(path)\n    ignore_file = path / \".prefectignore\"\n    if ignore_file.exists():\n        return False\n    default_file = pathlib.Path(prefect.__module_path__) / \".prefectignore\"\n    with ignore_file.open(mode=\"w\") as f:\n        f.write(default_file.read_text())\n    return True\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.filename","title":"<code>filename</code>","text":"<p>Extract the file name from a path with remote file system support</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def filename(path: str) -&gt; str:\n    \"\"\"Extract the file name from a path with remote file system support\"\"\"\n    try:\n        of: OpenFile = fsspec.open(path)\n        sep = of.fs.sep\n    except (ImportError, AttributeError):\n        sep = \"\\\\\" if \"\\\\\" in path else \"/\"\n    return path.split(sep)[-1]\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.filter_files","title":"<code>filter_files</code>","text":"<p>This function accepts a root directory path and a list of file patterns to ignore, and returns a list of files that excludes those that should be ignored.</p> <p>The specification matches that of .gitignore files.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def filter_files(\n    root: str = \".\", ignore_patterns: list = None, include_dirs: bool = True\n) -&gt; set:\n    \"\"\"\n    This function accepts a root directory path and a list of file patterns to ignore, and returns\n    a list of files that excludes those that should be ignored.\n\n    The specification matches that of [.gitignore files](https://git-scm.com/docs/gitignore).\n    \"\"\"\n    if ignore_patterns is None:\n        ignore_patterns = []\n    spec = pathspec.PathSpec.from_lines(\"gitwildmatch\", ignore_patterns)\n    ignored_files = {p.path for p in spec.match_tree_entries(root)}\n    if include_dirs:\n        all_files = {p.path for p in pathspec.util.iter_tree_entries(root)}\n    else:\n        all_files = set(pathspec.util.iter_tree_files(root))\n    included_files = all_files - ignored_files\n    return included_files\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.get_open_file_limit","title":"<code>get_open_file_limit</code>","text":"<p>Get the maximum number of open files allowed for the current process</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def get_open_file_limit() -&gt; int:\n    \"\"\"Get the maximum number of open files allowed for the current process\"\"\"\n\n    try:\n        if os.name == \"nt\":\n            import ctypes\n\n            return ctypes.cdll.ucrtbase._getmaxstdio()\n        else:\n            import resource\n\n            soft_limit, _ = resource.getrlimit(resource.RLIMIT_NOFILE)\n            return soft_limit\n    except Exception:\n        # Catch all exceptions, as ctypes can raise several errors\n        # depending on what went wrong. Return a safe default if we\n        # can't get the limit from the OS.\n        return 200\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.is_local_path","title":"<code>is_local_path</code>","text":"<p>Check if the given path points to a local or remote file system</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def is_local_path(path: Union[str, pathlib.Path, OpenFile]):\n    \"\"\"Check if the given path points to a local or remote file system\"\"\"\n    if isinstance(path, str):\n        try:\n            of = fsspec.open(path)\n        except ImportError:\n            # The path is a remote file system that uses a lib that is not installed\n            return False\n    elif isinstance(path, pathlib.Path):\n        return True\n    elif isinstance(path, OpenFile):\n        of = path\n    else:\n        raise TypeError(f\"Invalid path of type {type(path).__name__!r}\")\n\n    return type(of.fs) == LocalFileSystem\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.relative_path_to_current_platform","title":"<code>relative_path_to_current_platform</code>","text":"<p>Converts a relative path generated on any platform to a relative path for the current platform.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def relative_path_to_current_platform(path_str: str) -&gt; Path:\n    \"\"\"\n    Converts a relative path generated on any platform to a relative path for the\n    current platform.\n    \"\"\"\n\n    return Path(PureWindowsPath(path_str).as_posix())\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.tmpchdir","title":"<code>tmpchdir</code>","text":"<p>Change current-working directories for the duration of the context</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>@contextmanager\ndef tmpchdir(path: str):\n    \"\"\"\n    Change current-working directories for the duration of the context\n    \"\"\"\n    path = os.path.abspath(path)\n    if os.path.isfile(path) or (not os.path.exists(path) and not path.endswith(\"/\")):\n        path = os.path.dirname(path)\n\n    owd = os.getcwd()\n\n    with chdir_lock:\n        try:\n            os.chdir(path)\n            yield path\n        finally:\n            os.chdir(owd)\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.to_display_path","title":"<code>to_display_path</code>","text":"<p>Convert a path to a displayable path. The absolute path or relative path to the current (or given) directory will be returned, whichever is shorter.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def to_display_path(\n    path: Union[pathlib.Path, str], relative_to: Union[pathlib.Path, str] = None\n) -&gt; str:\n    \"\"\"\n    Convert a path to a displayable path. The absolute path or relative path to the\n    current (or given) directory will be returned, whichever is shorter.\n    \"\"\"\n    path, relative_to = (\n        pathlib.Path(path).resolve(),\n        pathlib.Path(relative_to or \".\").resolve(),\n    )\n    relative_path = str(path.relative_to(relative_to))\n    absolute_path = str(path)\n    return relative_path if len(relative_path) &lt; len(absolute_path) else absolute_path\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/hashing/","title":"hashing","text":"","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing","title":"<code>prefect.utilities.hashing</code>","text":"","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.file_hash","title":"<code>file_hash</code>","text":"<p>Given a path to a file, produces a stable hash of the file contents.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>the path to a file</p> required <code>hash_algo</code> <p>Hash algorithm from hashlib to use.</p> <code>_md5</code> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>a hash of the file contents</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def file_hash(path: str, hash_algo=_md5) -&gt; str:\n    \"\"\"Given a path to a file, produces a stable hash of the file contents.\n\n    Args:\n        path (str): the path to a file\n        hash_algo: Hash algorithm from hashlib to use.\n\n    Returns:\n        str: a hash of the file contents\n    \"\"\"\n    contents = Path(path).read_bytes()\n    return stable_hash(contents, hash_algo=hash_algo)\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.hash_objects","title":"<code>hash_objects</code>","text":"<p>Attempt to hash objects by dumping to JSON or serializing with cloudpickle. On failure of both, <code>None</code> will be returned</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def hash_objects(*args, hash_algo=_md5, **kwargs) -&gt; Optional[str]:\n    \"\"\"\n    Attempt to hash objects by dumping to JSON or serializing with cloudpickle.\n    On failure of both, `None` will be returned\n    \"\"\"\n    try:\n        serializer = JSONSerializer(dumps_kwargs={\"sort_keys\": True})\n        return stable_hash(serializer.dumps((args, kwargs)), hash_algo=hash_algo)\n    except Exception:\n        pass\n\n    try:\n        return stable_hash(cloudpickle.dumps((args, kwargs)), hash_algo=hash_algo)\n    except Exception:\n        pass\n\n    return None\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.stable_hash","title":"<code>stable_hash</code>","text":"<p>Given some arguments, produces a stable 64-bit hash of their contents.</p> <p>Supports bytes and strings. Strings will be UTF-8 encoded.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Union[str, bytes]</code> <p>Items to include in the hash.</p> <code>()</code> <code>hash_algo</code> <p>Hash algorithm from hashlib to use.</p> <code>_md5</code> <p>Returns:</p> Type Description <code>str</code> <p>A hex hash.</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def stable_hash(*args: Union[str, bytes], hash_algo=_md5) -&gt; str:\n    \"\"\"Given some arguments, produces a stable 64-bit hash of their contents.\n\n    Supports bytes and strings. Strings will be UTF-8 encoded.\n\n    Args:\n        *args: Items to include in the hash.\n        hash_algo: Hash algorithm from hashlib to use.\n\n    Returns:\n        A hex hash.\n    \"\"\"\n    h = hash_algo()\n    for a in args:\n        if isinstance(a, str):\n            a = a.encode()\n        h.update(a)\n    return h.hexdigest()\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/importtools/","title":"importtools","text":"","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools","title":"<code>prefect.utilities.importtools</code>","text":"","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleDefinition","title":"<code>AliasedModuleDefinition</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>A definition for the <code>AliasedModuleFinder</code>.</p> <p>Parameters:</p> Name Type Description Default <code>alias</code> <p>The import name to create</p> required <code>real</code> <p>The import name of the module to reference for the alias</p> required <code>callback</code> <p>A function to call when the alias module is loaded</p> required Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class AliasedModuleDefinition(NamedTuple):\n    \"\"\"\n    A definition for the `AliasedModuleFinder`.\n\n    Args:\n        alias: The import name to create\n        real: The import name of the module to reference for the alias\n        callback: A function to call when the alias module is loaded\n    \"\"\"\n\n    alias: str\n    real: str\n    callback: Optional[Callable[[str], None]]\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleFinder","title":"<code>AliasedModuleFinder</code>","text":"<p>               Bases: <code>MetaPathFinder</code></p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class AliasedModuleFinder(MetaPathFinder):\n    def __init__(self, aliases: Iterable[AliasedModuleDefinition]):\n        \"\"\"\n        See `AliasedModuleDefinition` for alias specification.\n\n        Aliases apply to all modules nested within an alias.\n        \"\"\"\n        self.aliases = aliases\n\n    def find_spec(\n        self,\n        fullname: str,\n        path=None,\n        target=None,\n    ) -&gt; Optional[ModuleSpec]:\n        \"\"\"\n        The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\"\n        for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and\n        create a new spec for \"phi.bar\" that points to \"foo.bar\".\n        \"\"\"\n        for alias, real, callback in self.aliases:\n            if fullname.startswith(alias):\n                # Retrieve the spec of the real module\n                real_spec = importlib.util.find_spec(fullname.replace(alias, real, 1))\n                # Create a new spec for the alias\n                return ModuleSpec(\n                    fullname,\n                    AliasedModuleLoader(fullname, callback, real_spec),\n                    origin=real_spec.origin,\n                    is_package=real_spec.submodule_search_locations is not None,\n                )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleFinder.find_spec","title":"<code>find_spec</code>","text":"<p>The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\" for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and create a new spec for \"phi.bar\" that points to \"foo.bar\".</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def find_spec(\n    self,\n    fullname: str,\n    path=None,\n    target=None,\n) -&gt; Optional[ModuleSpec]:\n    \"\"\"\n    The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\"\n    for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and\n    create a new spec for \"phi.bar\" that points to \"foo.bar\".\n    \"\"\"\n    for alias, real, callback in self.aliases:\n        if fullname.startswith(alias):\n            # Retrieve the spec of the real module\n            real_spec = importlib.util.find_spec(fullname.replace(alias, real, 1))\n            # Create a new spec for the alias\n            return ModuleSpec(\n                fullname,\n                AliasedModuleLoader(fullname, callback, real_spec),\n                origin=real_spec.origin,\n                is_package=real_spec.submodule_search_locations is not None,\n            )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.DelayedImportErrorModule","title":"<code>DelayedImportErrorModule</code>","text":"<p>               Bases: <code>ModuleType</code></p> <p>A fake module returned by <code>lazy_import</code> when the module cannot be found. When any of the module's attributes are accessed, we will throw a <code>ModuleNotFoundError</code>.</p> <p>Adapted from lazy_loader</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class DelayedImportErrorModule(ModuleType):\n    \"\"\"\n    A fake module returned by `lazy_import` when the module cannot be found. When any\n    of the module's attributes are accessed, we will throw a `ModuleNotFoundError`.\n\n    Adapted from [lazy_loader][1]\n\n    [1]: https://github.com/scientific-python/lazy_loader\n    \"\"\"\n\n    def __init__(self, frame_data, help_message, *args, **kwargs):\n        self.__frame_data = frame_data\n        self.__help_message = (\n            help_message or \"Import errors for this module are only reported when used.\"\n        )\n        super().__init__(*args, **kwargs)\n\n    def __getattr__(self, attr):\n        if attr in (\"__class__\", \"__file__\", \"__frame_data\", \"__help_message\"):\n            super().__getattr__(attr)\n        else:\n            fd = self.__frame_data\n            raise ModuleNotFoundError(\n                f\"No module named '{fd['spec']}'\\n\\nThis module was originally imported\"\n                f\" at:\\n  File \\\"{fd['filename']}\\\", line {fd['lineno']}, in\"\n                f\" {fd['function']}\\n\\n    {''.join(fd['code_context']).strip()}\\n\"\n                + self.__help_message\n            )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.from_qualified_name","title":"<code>from_qualified_name</code>","text":"<p>Import an object given a fully-qualified name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The fully-qualified name of the object to import.</p> required <p>Returns:</p> Type Description <code>Any</code> <p>the imported object</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; obj = from_qualified_name(\"random.randint\")\n&gt;&gt;&gt; import random\n&gt;&gt;&gt; obj == random.randint\nTrue\n</code></pre> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def from_qualified_name(name: str) -&gt; Any:\n    \"\"\"\n    Import an object given a fully-qualified name.\n\n    Args:\n        name: The fully-qualified name of the object to import.\n\n    Returns:\n        the imported object\n\n    Examples:\n        &gt;&gt;&gt; obj = from_qualified_name(\"random.randint\")\n        &gt;&gt;&gt; import random\n        &gt;&gt;&gt; obj == random.randint\n        True\n    \"\"\"\n    # Try importing it first so we support \"module\" or \"module.sub_module\"\n    try:\n        module = importlib.import_module(name)\n        return module\n    except ImportError:\n        # If no subitem was included raise the import error\n        if \".\" not in name:\n            raise\n\n    # Otherwise, we'll try to load it as an attribute of a module\n    mod_name, attr_name = name.rsplit(\".\", 1)\n    module = importlib.import_module(mod_name)\n    return getattr(module, attr_name)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.import_object","title":"<code>import_object</code>","text":"<p>Load an object from an import path.</p> <p>Import paths can be formatted as one of: - module.object - module:object - /path/to/script.py:object</p> <p>This function is not thread safe as it modifies the 'sys' module during execution.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def import_object(import_path: str):\n    \"\"\"\n    Load an object from an import path.\n\n    Import paths can be formatted as one of:\n    - module.object\n    - module:object\n    - /path/to/script.py:object\n\n    This function is not thread safe as it modifies the 'sys' module during execution.\n    \"\"\"\n    if \".py:\" in import_path:\n        script_path, object_name = import_path.rsplit(\":\", 1)\n        module = load_script_as_module(script_path)\n    else:\n        if \":\" in import_path:\n            module_name, object_name = import_path.rsplit(\":\", 1)\n        elif \".\" in import_path:\n            module_name, object_name = import_path.rsplit(\".\", 1)\n        else:\n            raise ValueError(\n                f\"Invalid format for object import. Received {import_path!r}.\"\n            )\n\n        module = load_module(module_name)\n\n    return getattr(module, object_name)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.lazy_import","title":"<code>lazy_import</code>","text":"<p>Create a lazily-imported module to use in place of the module of the given name. Use this to retain module-level imports for libraries that we don't want to actually import until they are needed.</p> <p>Adapted from the Python documentation and lazy_loader</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def lazy_import(\n    name: str, error_on_import: bool = False, help_message: str = \"\"\n) -&gt; ModuleType:\n    \"\"\"\n    Create a lazily-imported module to use in place of the module of the given name.\n    Use this to retain module-level imports for libraries that we don't want to\n    actually import until they are needed.\n\n    Adapted from the [Python documentation][1] and [lazy_loader][2]\n\n    [1]: https://docs.python.org/3/library/importlib.html#implementing-lazy-imports\n    [2]: https://github.com/scientific-python/lazy_loader\n    \"\"\"\n\n    try:\n        return sys.modules[name]\n    except KeyError:\n        pass\n\n    spec = importlib.util.find_spec(name)\n    if spec is None:\n        if error_on_import:\n            raise ModuleNotFoundError(f\"No module named '{name}'.\\n{help_message}\")\n        else:\n            try:\n                parent = inspect.stack()[1]\n                frame_data = {\n                    \"spec\": name,\n                    \"filename\": parent.filename,\n                    \"lineno\": parent.lineno,\n                    \"function\": parent.function,\n                    \"code_context\": parent.code_context,\n                }\n                return DelayedImportErrorModule(\n                    frame_data, help_message, \"DelayedImportErrorModule\"\n                )\n            finally:\n                del parent\n\n    module = importlib.util.module_from_spec(spec)\n    sys.modules[name] = module\n\n    loader = importlib.util.LazyLoader(spec.loader)\n    loader.exec_module(module)\n\n    return module\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.load_module","title":"<code>load_module</code>","text":"<p>Import a module with support for relative imports within the module.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def load_module(module_name: str) -&gt; ModuleType:\n    \"\"\"\n    Import a module with support for relative imports within the module.\n    \"\"\"\n    # Ensure relative imports within the imported module work if the user is in the\n    # correct working directory\n    working_directory = os.getcwd()\n    sys.path.insert(0, working_directory)\n\n    try:\n        return importlib.import_module(module_name)\n    finally:\n        sys.path.remove(working_directory)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.load_script_as_module","title":"<code>load_script_as_module</code>","text":"<p>Execute a script at the given path.</p> <p>Sets the module name to <code>__prefect_loader__</code>.</p> <p>If an exception occurs during execution of the script, a <code>prefect.exceptions.ScriptError</code> is created to wrap the exception and raised.</p> <p>During the duration of this function call, <code>sys</code> is modified to support loading. These changes are reverted after completion, but this function is not thread safe and use of it in threaded contexts may result in undesirable behavior.</p> <p>See https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def load_script_as_module(path: str) -&gt; ModuleType:\n    \"\"\"\n    Execute a script at the given path.\n\n    Sets the module name to `__prefect_loader__`.\n\n    If an exception occurs during execution of the script, a\n    `prefect.exceptions.ScriptError` is created to wrap the exception and raised.\n\n    During the duration of this function call, `sys` is modified to support loading.\n    These changes are reverted after completion, but this function is not thread safe\n    and use of it in threaded contexts may result in undesirable behavior.\n\n    See https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly\n    \"\"\"\n    # We will add the parent directory to search locations to support relative imports\n    # during execution of the script\n    if not path.endswith(\".py\"):\n        raise ValueError(f\"The provided path does not point to a python file: {path!r}\")\n\n    parent_path = str(Path(path).resolve().parent)\n    working_directory = os.getcwd()\n\n    spec = importlib.util.spec_from_file_location(\n        \"__prefect_loader__\",\n        path,\n        # Support explicit relative imports i.e. `from .foo import bar`\n        submodule_search_locations=[parent_path, working_directory],\n    )\n    module = importlib.util.module_from_spec(spec)\n    sys.modules[\"__prefect_loader__\"] = module\n\n    # Support implicit relative imports i.e. `from foo import bar`\n    sys.path.insert(0, working_directory)\n    sys.path.insert(0, parent_path)\n    try:\n        spec.loader.exec_module(module)\n    except Exception as exc:\n        raise ScriptError(user_exc=exc, path=path) from exc\n    finally:\n        sys.modules.pop(\"__prefect_loader__\")\n        sys.path.remove(parent_path)\n        sys.path.remove(working_directory)\n\n    return module\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.objects_from_script","title":"<code>objects_from_script</code>","text":"<p>Run a python script and return all the global variables</p> <p>Supports remote paths by copying to a local temporary file.</p> <p>WARNING: The Python documentation does not recommend using runpy for this pattern.</p> <p>Furthermore, any functions and classes defined by the executed code are not guaranteed to work correctly after a runpy function has returned. If that limitation is not acceptable for a given use case, importlib is likely to be a more suitable choice than this module.</p> <p>The function <code>load_script_as_module</code> uses importlib instead and should be used instead for loading objects from scripts.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path to the script to run</p> required <code>text</code> <code>Union[str, bytes]</code> <p>Optionally, the text of the script. Skips loading the contents if given.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dictionary mapping variable name to value</p> <p>Raises:</p> Type Description <code>ScriptError</code> <p>if the script raises an exception during execution</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def objects_from_script(path: str, text: Union[str, bytes] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Run a python script and return all the global variables\n\n    Supports remote paths by copying to a local temporary file.\n\n    WARNING: The Python documentation does not recommend using runpy for this pattern.\n\n    &gt; Furthermore, any functions and classes defined by the executed code are not\n    &gt; guaranteed to work correctly after a runpy function has returned. If that\n    &gt; limitation is not acceptable for a given use case, importlib is likely to be a\n    &gt; more suitable choice than this module.\n\n    The function `load_script_as_module` uses importlib instead and should be used\n    instead for loading objects from scripts.\n\n    Args:\n        path: The path to the script to run\n        text: Optionally, the text of the script. Skips loading the contents if given.\n\n    Returns:\n        A dictionary mapping variable name to value\n\n    Raises:\n        ScriptError: if the script raises an exception during execution\n    \"\"\"\n\n    def run_script(run_path: str):\n        # Cast to an absolute path before changing directories to ensure relative paths\n        # are not broken\n        abs_run_path = os.path.abspath(run_path)\n        with tmpchdir(run_path):\n            try:\n                return runpy.run_path(abs_run_path)\n            except Exception as exc:\n                raise ScriptError(user_exc=exc, path=path) from exc\n\n    if text:\n        with NamedTemporaryFile(\n            mode=\"wt\" if isinstance(text, str) else \"wb\",\n            prefix=f\"run-{filename(path)}\",\n            suffix=\".py\",\n        ) as tmpfile:\n            tmpfile.write(text)\n            tmpfile.flush()\n            return run_script(tmpfile.name)\n\n    else:\n        if not is_local_path(path):\n            # Remote paths need to be local to run\n            with fsspec.open(path) as f:\n                contents = f.read()\n            return objects_from_script(path, contents)\n        else:\n            return run_script(path)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.safe_load_namespace","title":"<code>safe_load_namespace</code>","text":"<p>Safely load a namespace from source code, optionally handling relative imports.</p> <p>If a <code>filepath</code> is provided, <code>sys.path</code> is modified to support relative imports. Changes to <code>sys.path</code> are reverted after completion, but this function is not thread safe and use of it in threaded contexts may result in undesirable behavior.</p> <p>Parameters:</p> Name Type Description Default <code>source_code</code> <code>str</code> <p>The source code to load</p> required <code>filepath</code> <code>Optional[str]</code> <p>Optional file path of the source code. If provided, enables relative imports.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The namespace loaded from the source code.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def safe_load_namespace(\n    source_code: str, filepath: Optional[str] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Safely load a namespace from source code, optionally handling relative imports.\n\n    If a `filepath` is provided, `sys.path` is modified to support relative imports.\n    Changes to `sys.path` are reverted after completion, but this function is not thread safe\n    and use of it in threaded contexts may result in undesirable behavior.\n\n    Args:\n        source_code: The source code to load\n        filepath: Optional file path of the source code. If provided, enables relative imports.\n\n    Returns:\n        The namespace loaded from the source code.\n    \"\"\"\n    parsed_code = ast.parse(source_code)\n\n    namespace: Dict[str, Any] = {\"__name__\": \"prefect_safe_namespace_loader\"}\n\n    # Remove the body of the if __name__ == \"__main__\": block\n    new_body = [node for node in parsed_code.body if not _is_main_block(node)]\n    parsed_code.body = new_body\n\n    temp_module = None\n    original_sys_path = None\n\n    if filepath:\n        # Setup for relative imports\n        file_dir = os.path.dirname(os.path.abspath(filepath))\n        package_name = os.path.basename(file_dir)\n        parent_dir = os.path.dirname(file_dir)\n\n        # Save original sys.path and modify it\n        original_sys_path = sys.path.copy()\n        sys.path.insert(0, parent_dir)\n\n        # Create a temporary module for import context\n        temp_module = ModuleType(package_name)\n        temp_module.__file__ = filepath\n        temp_module.__package__ = package_name\n\n        # Create a spec for the module\n        temp_module.__spec__ = ModuleSpec(package_name, None)\n        temp_module.__spec__.loader = None\n        temp_module.__spec__.submodule_search_locations = [file_dir]\n\n    try:\n        for node in parsed_code.body:\n            if isinstance(node, ast.Import):\n                for alias in node.names:\n                    module_name = alias.name\n                    as_name = alias.asname or module_name\n                    try:\n                        namespace[as_name] = importlib.import_module(module_name)\n                        logger.debug(\"Successfully imported %s\", module_name)\n                    except ImportError as e:\n                        logger.debug(f\"Failed to import {module_name}: {e}\")\n            elif isinstance(node, ast.ImportFrom):\n                module_name = node.module or \"\"\n                if filepath:\n                    try:\n                        if node.level &gt; 0:\n                            # For relative imports, use the parent package to inform the import\n                            package_parts = temp_module.__package__.split(\".\")\n                            if len(package_parts) &lt; node.level:\n                                raise ImportError(\n                                    \"Attempted relative import beyond top-level package\"\n                                )\n                            parent_package = \".\".join(\n                                package_parts[: (1 - node.level)]\n                                if node.level &gt; 1\n                                else package_parts\n                            )\n                            module = importlib.import_module(\n                                f\".{module_name}\" if module_name else \"\",\n                                package=parent_package,\n                            )\n                        else:\n                            # Absolute imports are handled as normal\n                            module = importlib.import_module(module_name)\n\n                        for alias in node.names:\n                            name = alias.name\n                            asname = alias.asname or name\n                            if name == \"*\":\n                                # Handle 'from module import *'\n                                module_dict = {\n                                    k: v\n                                    for k, v in module.__dict__.items()\n                                    if not k.startswith(\"_\")\n                                }\n                                namespace.update(module_dict)\n                            else:\n                                try:\n                                    attribute = getattr(module, name)\n                                    namespace[asname] = attribute\n                                except AttributeError as e:\n                                    logger.debug(\n                                        \"Failed to retrieve %s from %s: %s\",\n                                        name,\n                                        module_name,\n                                        e,\n                                    )\n                    except ImportError as e:\n                        logger.debug(\"Failed to import from %s: %s\", module_name, e)\n                else:\n                    # Handle as absolute import when no filepath is provided\n                    try:\n                        module = importlib.import_module(module_name)\n                        for alias in node.names:\n                            name = alias.name\n                            asname = alias.asname or name\n                            if name == \"*\":\n                                # Handle 'from module import *'\n                                module_dict = {\n                                    k: v\n                                    for k, v in module.__dict__.items()\n                                    if not k.startswith(\"_\")\n                                }\n                                namespace.update(module_dict)\n                            else:\n                                try:\n                                    attribute = getattr(module, name)\n                                    namespace[asname] = attribute\n                                except AttributeError as e:\n                                    logger.debug(\n                                        \"Failed to retrieve %s from %s: %s\",\n                                        name,\n                                        module_name,\n                                        e,\n                                    )\n                    except ImportError as e:\n                        logger.debug(\"Failed to import from %s: %s\", module_name, e)\n        # Handle local definitions\n        for node in parsed_code.body:\n            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.Assign)):\n                try:\n                    code = compile(\n                        ast.Module(body=[node], type_ignores=[]),\n                        filename=\"&lt;ast&gt;\",\n                        mode=\"exec\",\n                    )\n                    exec(code, namespace)\n                except Exception as e:\n                    logger.debug(\"Failed to compile: %s\", e)\n\n    finally:\n        # Restore original sys.path if it was modified\n        if original_sys_path:\n            sys.path[:] = original_sys_path\n\n    return namespace\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.to_qualified_name","title":"<code>to_qualified_name</code>","text":"<p>Given an object, returns its fully-qualified name: a string that represents its Python import path.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Any</code> <p>an importable Python object</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>the qualified name</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def to_qualified_name(obj: Any) -&gt; str:\n    \"\"\"\n    Given an object, returns its fully-qualified name: a string that represents its\n    Python import path.\n\n    Args:\n        obj (Any): an importable Python object\n\n    Returns:\n        str: the qualified name\n    \"\"\"\n    if sys.version_info &lt; (3, 10):\n        # These attributes are only available in Python 3.10+\n        if isinstance(obj, (classmethod, staticmethod)):\n            obj = obj.__func__\n    return obj.__module__ + \".\" + obj.__qualname__\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/math/","title":"math","text":"","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math","title":"<code>prefect.utilities.math</code>","text":"","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.bounded_poisson_interval","title":"<code>bounded_poisson_interval</code>","text":"<p>Bounds Poisson \"inter-arrival times\" to a range.</p> <p>Unlike <code>clamped_poisson_interval</code> this does not take a target average interval. Instead, the interval is predetermined and the average is calculated as their midpoint. This allows Poisson intervals to be used in cases where a lower bound must be enforced.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def bounded_poisson_interval(lower_bound, upper_bound):\n    \"\"\"\n    Bounds Poisson \"inter-arrival times\" to a range.\n\n    Unlike `clamped_poisson_interval` this does not take a target average interval.\n    Instead, the interval is predetermined and the average is calculated as their\n    midpoint. This allows Poisson intervals to be used in cases where a lower bound\n    must be enforced.\n    \"\"\"\n    average = (float(lower_bound) + float(upper_bound)) / 2.0\n    upper_rv = exponential_cdf(upper_bound, average)\n    lower_rv = exponential_cdf(lower_bound, average)\n    return poisson_interval(average, lower_rv, upper_rv)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.clamped_poisson_interval","title":"<code>clamped_poisson_interval</code>","text":"<p>Bounds Poisson \"inter-arrival times\" to a range defined by the clamping factor.</p> <p>The upper bound for this random variate is: average_interval * (1 + clamping_factor). A lower bound is picked so that the average interval remains approximately fixed.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def clamped_poisson_interval(average_interval, clamping_factor=0.3):\n    \"\"\"\n    Bounds Poisson \"inter-arrival times\" to a range defined by the clamping factor.\n\n    The upper bound for this random variate is: average_interval * (1 + clamping_factor).\n    A lower bound is picked so that the average interval remains approximately fixed.\n    \"\"\"\n    if clamping_factor &lt;= 0:\n        raise ValueError(\"`clamping_factor` must be &gt;= 0.\")\n\n    upper_clamp_multiple = 1 + clamping_factor\n    upper_bound = average_interval * upper_clamp_multiple\n    lower_bound = max(0, average_interval * lower_clamp_multiple(upper_clamp_multiple))\n\n    upper_rv = exponential_cdf(upper_bound, average_interval)\n    lower_rv = exponential_cdf(lower_bound, average_interval)\n    return poisson_interval(average_interval, lower_rv, upper_rv)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.lower_clamp_multiple","title":"<code>lower_clamp_multiple</code>","text":"<p>Computes a lower clamp multiple that can be used to bound a random variate drawn from an exponential distribution.</p> <p>Given an upper clamp multiple <code>k</code> (and corresponding upper bound k * average_interval), this function computes a lower clamp multiple <code>c</code> (corresponding to a lower bound c * average_interval) where the probability mass between the lower bound and the median is equal to the probability mass between the median and the upper bound.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def lower_clamp_multiple(k):\n    \"\"\"\n    Computes a lower clamp multiple that can be used to bound a random variate drawn\n    from an exponential distribution.\n\n    Given an upper clamp multiple `k` (and corresponding upper bound k * average_interval),\n    this function computes a lower clamp multiple `c` (corresponding to a lower bound\n    c * average_interval) where the probability mass between the lower bound and the\n    median is equal to the probability mass between the median and the upper bound.\n    \"\"\"\n    if k &gt;= 50:\n        # return 0 for large values of `k` to prevent numerical overflow\n        return 0.0\n\n    return math.log(max(2**k / (2**k - 1), 1e-10), 2)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.poisson_interval","title":"<code>poisson_interval</code>","text":"<p>Generates an \"inter-arrival time\" for a Poisson process.</p> <p>Draws a random variable from an exponential distribution using the inverse-CDF method. Can optionally be passed a lower and upper bound between (0, 1] to clamp the potential output values.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def poisson_interval(average_interval, lower=0, upper=1):\n    \"\"\"\n    Generates an \"inter-arrival time\" for a Poisson process.\n\n    Draws a random variable from an exponential distribution using the inverse-CDF\n    method. Can optionally be passed a lower and upper bound between (0, 1] to clamp\n    the potential output values.\n    \"\"\"\n\n    # note that we ensure the argument to the logarithm is stabilized to prevent\n    # calling log(0), which results in a DomainError\n    return -math.log(max(1 - random.uniform(lower, upper), 1e-10)) * average_interval\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/names/","title":"names","text":"","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names","title":"<code>prefect.utilities.names</code>","text":"","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.generate_slug","title":"<code>generate_slug</code>","text":"<p>Generates a random slug.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>n_words (int</code> <p>the number of words in the slug</p> required Source code in <code>prefect/utilities/names.py</code> <pre><code>def generate_slug(n_words: int) -&gt; str:\n    \"\"\"\n    Generates a random slug.\n\n    Args:\n        - n_words (int): the number of words in the slug\n    \"\"\"\n    words = coolname.generate(n_words)\n\n    # regenerate words if they include ignored words\n    while IGNORE_LIST.intersection(words):\n        words = coolname.generate(n_words)\n\n    return \"-\".join(words)\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.obfuscate","title":"<code>obfuscate</code>","text":"<p>Obfuscates any data type's string representation. See <code>obfuscate_string</code>.</p> Source code in <code>prefect/utilities/names.py</code> <pre><code>def obfuscate(s: Any, show_tail=False) -&gt; str:\n    \"\"\"\n    Obfuscates any data type's string representation. See `obfuscate_string`.\n    \"\"\"\n    if s is None:\n        return OBFUSCATED_PREFIX + \"*\" * 4\n\n    return obfuscate_string(str(s), show_tail=show_tail)\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.obfuscate_string","title":"<code>obfuscate_string</code>","text":"<p>Obfuscates a string by returning a new string of 8 characters. If the input string is longer than 10 characters and show_tail is True, then up to 4 of its final characters will become final characters of the obfuscated string; all other characters are \"*\".</p> <p>\"abc\"      -&gt; \"*\" \"abcdefgh\" -&gt; \"*\" \"abcdefghijk\" -&gt; \"*k\" \"abcdefghijklmnopqrs\" -&gt; \"****pqrs\"</p> Source code in <code>prefect/utilities/names.py</code> <pre><code>def obfuscate_string(s: str, show_tail=False) -&gt; str:\n    \"\"\"\n    Obfuscates a string by returning a new string of 8 characters. If the input\n    string is longer than 10 characters and show_tail is True, then up to 4 of\n    its final characters will become final characters of the obfuscated string;\n    all other characters are \"*\".\n\n    \"abc\"      -&gt; \"********\"\n    \"abcdefgh\" -&gt; \"********\"\n    \"abcdefghijk\" -&gt; \"*******k\"\n    \"abcdefghijklmnopqrs\" -&gt; \"****pqrs\"\n    \"\"\"\n    result = OBFUSCATED_PREFIX + \"*\" * 4\n    # take up to 4 characters, but only after the 10th character\n    suffix = s[10:][-4:]\n    if suffix and show_tail:\n        result = f\"{result[:-len(suffix)]}{suffix}\"\n    return result\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/processutils/","title":"processutils","text":""},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils","title":"<code>prefect.utilities.processutils</code>","text":""},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.forward_signal_handler","title":"<code>forward_signal_handler</code>","text":"<p>Forward subsequent signum events (e.g. interrupts) to respective signums.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def forward_signal_handler(\n    pid: int, signum: int, *signums: int, process_name: str, print_fn: Callable\n):\n    \"\"\"Forward subsequent signum events (e.g. interrupts) to respective signums.\"\"\"\n    current_signal, future_signals = signums[0], signums[1:]\n\n    # avoid RecursionError when setting up a direct signal forward to the same signal for the main pid\n    avoid_infinite_recursion = signum == current_signal and pid == os.getpid()\n    if avoid_infinite_recursion:\n        # store the vanilla handler so it can be temporarily restored below\n        original_handler = signal.getsignal(current_signal)\n\n    def handler(*args):\n        print_fn(\n            f\"Received {getattr(signum, 'name', signum)}. \"\n            f\"Sending {getattr(current_signal, 'name', current_signal)} to\"\n            f\" {process_name} (PID {pid})...\"\n        )\n        if avoid_infinite_recursion:\n            signal.signal(current_signal, original_handler)\n        os.kill(pid, current_signal)\n        if future_signals:\n            forward_signal_handler(\n                pid,\n                signum,\n                *future_signals,\n                process_name=process_name,\n                print_fn=print_fn,\n            )\n\n    # register current and future signal handlers\n    _register_signal(signum, handler)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.open_process","title":"<code>open_process</code>  <code>async</code>","text":"<p>Like <code>anyio.open_process</code> but with: - Support for Windows command joining - Termination of the process on exception during yield - Forced cleanup of process resources during cancellation</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>@asynccontextmanager\nasync def open_process(command: List[str], **kwargs):\n    \"\"\"\n    Like `anyio.open_process` but with:\n    - Support for Windows command joining\n    - Termination of the process on exception during yield\n    - Forced cleanup of process resources during cancellation\n    \"\"\"\n    # Passing a string to open_process is equivalent to shell=True which is\n    # generally necessary for Unix-like commands on Windows but otherwise should\n    # be avoided\n    if not isinstance(command, list):\n        raise TypeError(\n            \"The command passed to open process must be a list. You passed the command\"\n            f\"'{command}', which is type '{type(command)}'.\"\n        )\n\n    if sys.platform == \"win32\":\n        command = \" \".join(command)\n        process = await _open_anyio_process(command, **kwargs)\n    else:\n        process = await anyio.open_process(command, **kwargs)\n\n    # if there's a creationflags kwarg and it contains CREATE_NEW_PROCESS_GROUP,\n    # use SetConsoleCtrlHandler to handle CTRL-C\n    win32_process_group = False\n    if (\n        sys.platform == \"win32\"\n        and \"creationflags\" in kwargs\n        and kwargs[\"creationflags\"] &amp; subprocess.CREATE_NEW_PROCESS_GROUP\n    ):\n        win32_process_group = True\n        _windows_process_group_pids.add(process.pid)\n        # Add a handler for CTRL-C. Re-adding the handler is safe as Windows\n        # will not add a duplicate handler if _win32_ctrl_handler is\n        # already registered.\n        windll.kernel32.SetConsoleCtrlHandler(_win32_ctrl_handler, 1)\n\n    try:\n        async with process:\n            yield process\n    finally:\n        try:\n            process.terminate()\n            if win32_process_group:\n                _windows_process_group_pids.remove(process.pid)\n\n        except OSError:\n            # Occurs if the process is already terminated\n            pass\n\n        # Ensure the process resource is closed. If not shielded from cancellation,\n        # this resource can be left open and the subprocess output can appear after\n        # the parent process has exited.\n        with anyio.CancelScope(shield=True):\n            await process.aclose()\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.run_process","title":"<code>run_process</code>  <code>async</code>","text":"<p>Like <code>anyio.run_process</code> but with:</p> <ul> <li>Use of our <code>open_process</code> utility to ensure resources are cleaned up</li> <li>Simple <code>stream_output</code> support to connect the subprocess to the parent stdout/err</li> <li>Support for submission with <code>TaskGroup.start</code> marking as 'started' after the     process has been created. When used, the PID is returned to the task status.</li> </ul> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>async def run_process(\n    command: List[str],\n    stream_output: Union[bool, Tuple[Optional[TextSink], Optional[TextSink]]] = False,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n    task_status_handler: Optional[Callable[[anyio.abc.Process], Any]] = None,\n    **kwargs,\n):\n    \"\"\"\n    Like `anyio.run_process` but with:\n\n    - Use of our `open_process` utility to ensure resources are cleaned up\n    - Simple `stream_output` support to connect the subprocess to the parent stdout/err\n    - Support for submission with `TaskGroup.start` marking as 'started' after the\n        process has been created. When used, the PID is returned to the task status.\n\n    \"\"\"\n    if stream_output is True:\n        stream_output = (sys.stdout, sys.stderr)\n\n    async with open_process(\n        command,\n        stdout=subprocess.PIPE if stream_output else subprocess.DEVNULL,\n        stderr=subprocess.PIPE if stream_output else subprocess.DEVNULL,\n        **kwargs,\n    ) as process:\n        if task_status is not None:\n            if not task_status_handler:\n\n                def task_status_handler(process):\n                    return process.pid\n\n            task_status.started(task_status_handler(process))\n\n        if stream_output:\n            await consume_process_output(\n                process, stdout_sink=stream_output[0], stderr_sink=stream_output[1]\n            )\n\n        await process.wait()\n\n    return process\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_agent","title":"<code>setup_signal_handlers_agent</code>","text":"<p>Handle interrupts of the agent gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_agent(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of the agent gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when agent receives SIGINT, it stops dequeueing new FlowRuns, and runs until the subprocesses finish\n    # the signal is not forwarded to subprocesses, so they can continue to run and hopefully still complete\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # forward first SIGINT directly, send SIGKILL on subsequent interrupt\n        setup_handler(signal.SIGINT, signal.SIGINT, signal.SIGKILL)\n        # first SIGTERM: send SIGINT, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGINT, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_server","title":"<code>setup_signal_handlers_server</code>","text":"<p>Handle interrupts of the server gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_server(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of the server gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when server receives a signal, it needs to be propagated to the uvicorn subprocess\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # first interrupt: SIGTERM, second interrupt: SIGKILL\n        setup_handler(signal.SIGINT, signal.SIGTERM, signal.SIGKILL)\n        # forward first SIGTERM directly, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGTERM, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_worker","title":"<code>setup_signal_handlers_worker</code>","text":"<p>Handle interrupts of workers gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_worker(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of workers gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when agent receives SIGINT, it stops dequeueing new FlowRuns, and runs until the subprocesses finish\n    # the signal is not forwarded to subprocesses, so they can continue to run and hopefully still complete\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # forward first SIGINT directly, send SIGKILL on subsequent interrupt\n        setup_handler(signal.SIGINT, signal.SIGINT, signal.SIGKILL)\n        # first SIGTERM: send SIGINT, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGINT, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/pydantic/","title":"pydantic","text":"","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic","title":"<code>prefect.utilities.pydantic</code>","text":"","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.PartialModel","title":"<code>PartialModel</code>","text":"<p>               Bases: <code>Generic[M]</code></p> <p>A utility for creating a Pydantic model in several steps.</p> <p>Fields may be set at initialization, via attribute assignment, or at finalization when the concrete model is returned.</p> <p>Pydantic validation does not occur until finalization.</p> <p>Each field can only be set once and a <code>ValueError</code> will be raised on assignment if a field already has a value.</p> Example <p>class MyModel(pydantic_v1.BaseModel):     x: int     y: str     z: float</p> <p>partial_model = PartialModel(MyModel, x=1) partial_model.y = \"two\" model = partial_model.finalize(z=3.0)</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>class PartialModel(Generic[M]):\n    \"\"\"\n    A utility for creating a Pydantic model in several steps.\n\n    Fields may be set at initialization, via attribute assignment, or at finalization\n    when the concrete model is returned.\n\n    Pydantic validation does not occur until finalization.\n\n    Each field can only be set once and a `ValueError` will be raised on assignment if\n    a field already has a value.\n\n    Example:\n        &gt;&gt;&gt; class MyModel(pydantic_v1.BaseModel):\n        &gt;&gt;&gt;     x: int\n        &gt;&gt;&gt;     y: str\n        &gt;&gt;&gt;     z: float\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; partial_model = PartialModel(MyModel, x=1)\n        &gt;&gt;&gt; partial_model.y = \"two\"\n        &gt;&gt;&gt; model = partial_model.finalize(z=3.0)\n    \"\"\"\n\n    def __init__(self, __model_cls: Type[M], **kwargs: Any) -&gt; None:\n        self.fields = kwargs\n        # Set fields first to avoid issues if `fields` is also set on the `model_cls`\n        # in our custom `setattr` implementation.\n        self.model_cls = __model_cls\n\n        for name in kwargs.keys():\n            self.raise_if_not_in_model(name)\n\n    def finalize(self, **kwargs: Any) -&gt; M:\n        for name in kwargs.keys():\n            self.raise_if_already_set(name)\n            self.raise_if_not_in_model(name)\n        return self.model_cls(**self.fields, **kwargs)\n\n    def raise_if_already_set(self, name):\n        if name in self.fields:\n            raise ValueError(f\"Field {name!r} has already been set.\")\n\n    def raise_if_not_in_model(self, name):\n        if name not in self.model_cls.__fields__:\n            raise ValueError(f\"Field {name!r} is not present in the model.\")\n\n    def __setattr__(self, __name: str, __value: Any) -&gt; None:\n        if __name in {\"fields\", \"model_cls\"}:\n            return super().__setattr__(__name, __value)\n\n        self.raise_if_already_set(__name)\n        self.raise_if_not_in_model(__name)\n        self.fields[__name] = __value\n\n    def __repr__(self) -&gt; str:\n        dsp_fields = \", \".join(\n            f\"{key}={repr(value)}\" for key, value in self.fields.items()\n        )\n        return f\"PartialModel(cls={self.model_cls.__name__}, {dsp_fields})\"\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.add_cloudpickle_reduction","title":"<code>add_cloudpickle_reduction</code>","text":"<p>Adds a <code>__reducer__</code> to the given class that ensures it is cloudpickle compatible.</p> <p>Workaround for issues with cloudpickle when using cythonized pydantic which throws exceptions when attempting to pickle the class which has \"compiled\" validator methods dynamically attached to it.</p> <p>We cannot define this utility in the model class itself because the class is the type that contains unserializable methods.</p> <p>Any model using some features of Pydantic (e.g. <code>Path</code> validation) with a Cython compiled Pydantic installation may encounter pickling issues.</p> <p>See related issue at https://github.com/cloudpipe/cloudpickle/issues/408</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def add_cloudpickle_reduction(__model_cls: Type[M] = None, **kwargs: Any):\n    \"\"\"\n    Adds a `__reducer__` to the given class that ensures it is cloudpickle compatible.\n\n    Workaround for issues with cloudpickle when using cythonized pydantic which\n    throws exceptions when attempting to pickle the class which has \"compiled\"\n    validator methods dynamically attached to it.\n\n    We cannot define this utility in the model class itself because the class is the\n    type that contains unserializable methods.\n\n    Any model using some features of Pydantic (e.g. `Path` validation) with a Cython\n    compiled Pydantic installation may encounter pickling issues.\n\n    See related issue at https://github.com/cloudpipe/cloudpickle/issues/408\n    \"\"\"\n    if __model_cls:\n        __model_cls.__reduce__ = _reduce_model\n        __model_cls.__reduce_kwargs__ = kwargs\n        return __model_cls\n    else:\n        return cast(\n            Callable[[Type[M]], Type[M]],\n            partial(\n                add_cloudpickle_reduction,\n                **kwargs,\n            ),\n        )\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.add_type_dispatch","title":"<code>add_type_dispatch</code>","text":"<p>Extend a Pydantic model to add a 'type' field that is used as a discriminator field to dynamically determine the subtype that when deserializing models.</p> <p>This allows automatic resolution to subtypes of the decorated model.</p> <p>If a type field already exists, it should be a string literal field that has a constant value for each subclass. The default value of this field will be used as the dispatch key.</p> <p>If a type field does not exist, one will be added. In this case, the value of the field will be set to the value of the <code>__dispatch_key__</code>. The base class should define a <code>__dispatch_key__</code> class method that is used to determine the unique key for each subclass. Alternatively, each subclass can define the <code>__dispatch_key__</code> as a string literal.</p> <p>The base class must not define a 'type' field. If it is not desirable to add a field to the model and the dispatch key can be tracked separately, the lower level utilities in <code>prefect.utilities.dispatch</code> should be used directly.</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def add_type_dispatch(model_cls: Type[M]) -&gt; Type[M]:\n    \"\"\"\n    Extend a Pydantic model to add a 'type' field that is used as a discriminator field\n    to dynamically determine the subtype that when deserializing models.\n\n    This allows automatic resolution to subtypes of the decorated model.\n\n    If a type field already exists, it should be a string literal field that has a\n    constant value for each subclass. The default value of this field will be used as\n    the dispatch key.\n\n    If a type field does not exist, one will be added. In this case, the value of the\n    field will be set to the value of the `__dispatch_key__`. The base class should\n    define a `__dispatch_key__` class method that is used to determine the unique key\n    for each subclass. Alternatively, each subclass can define the `__dispatch_key__`\n    as a string literal.\n\n    The base class must not define a 'type' field. If it is not desirable to add a field\n    to the model and the dispatch key can be tracked separately, the lower level\n    utilities in `prefect.utilities.dispatch` should be used directly.\n    \"\"\"\n    defines_dispatch_key = hasattr(\n        model_cls, \"__dispatch_key__\"\n    ) or \"__dispatch_key__\" in getattr(model_cls, \"__annotations__\", {})\n\n    defines_type_field = \"type\" in model_cls.__fields__\n\n    if not defines_dispatch_key and not defines_type_field:\n        raise ValueError(\n            f\"Model class {model_cls.__name__!r} does not define a `__dispatch_key__` \"\n            \"or a type field. One of these is required for dispatch.\"\n        )\n\n    elif defines_dispatch_key and not defines_type_field:\n        # Add a type field to store the value of the dispatch key\n        model_cls.__fields__[\"type\"] = pydantic_v1.fields.ModelField(\n            name=\"type\",\n            type_=str,\n            required=True,\n            class_validators=None,\n            model_config=model_cls.__config__,\n        )\n\n    elif not defines_dispatch_key and defines_type_field:\n        field_type_annotation = model_cls.__fields__[\"type\"].type_\n        if field_type_annotation != str:\n            raise TypeError(\n                f\"Model class {model_cls.__name__!r} defines a 'type' field with \"\n                f\"type {field_type_annotation.__name__!r} but it must be 'str'.\"\n            )\n\n        # Set the dispatch key to retrieve the value from the type field\n        @classmethod\n        def dispatch_key_from_type_field(cls):\n            return cls.__fields__[\"type\"].default\n\n        model_cls.__dispatch_key__ = dispatch_key_from_type_field\n\n    else:\n        raise ValueError(\n            f\"Model class {model_cls.__name__!r} defines a `__dispatch_key__` \"\n            \"and a type field. Only one of these may be defined for dispatch.\"\n        )\n\n    cls_init = model_cls.__init__\n    cls_new = model_cls.__new__\n\n    def __init__(__pydantic_self__, **data: Any) -&gt; None:\n        type_string = (\n            get_dispatch_key(__pydantic_self__)\n            if type(__pydantic_self__) != model_cls\n            else \"__base__\"\n        )\n        data.setdefault(\"type\", type_string)\n        cls_init(__pydantic_self__, **data)\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        if \"type\" in kwargs:\n            try:\n                subcls = lookup_type(cls, dispatch_key=kwargs[\"type\"])\n            except KeyError as exc:\n                raise pydantic_v1.ValidationError(errors=[exc], model=cls)\n            return cls_new(subcls)\n        else:\n            return cls_new(cls)\n\n    model_cls.__init__ = __init__\n    model_cls.__new__ = __new__\n\n    register_base_type(model_cls)\n\n    return model_cls\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.get_class_fields_only","title":"<code>get_class_fields_only</code>","text":"<p>Gets all the field names defined on the model class but not any parent classes. Any fields that are on the parent but redefined on the subclass are included.</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def get_class_fields_only(model: Type[pydantic_v1.BaseModel]) -&gt; set:\n    \"\"\"\n    Gets all the field names defined on the model class but not any parent classes.\n    Any fields that are on the parent but redefined on the subclass are included.\n    \"\"\"\n    subclass_class_fields = set(model.__annotations__.keys())\n    parent_class_fields = set()\n\n    for base in model.__class__.__bases__:\n        if issubclass(base, pydantic_v1.BaseModel):\n            parent_class_fields.update(base.__annotations__.keys())\n\n    return (subclass_class_fields - parent_class_fields) | (\n        subclass_class_fields &amp; parent_class_fields\n    )\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/render_swagger/","title":"render_swagger","text":"","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/render_swagger/#prefect.utilities.render_swagger","title":"<code>prefect.utilities.render_swagger</code>","text":"","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/render_swagger/#prefect.utilities.render_swagger.swagger_lib","title":"<code>swagger_lib</code>","text":"<p>Provides the actual swagger library used</p> Source code in <code>prefect/utilities/render_swagger.py</code> <pre><code>def swagger_lib(config) -&gt; dict:\n    \"\"\"\n    Provides the actual swagger library used\n    \"\"\"\n    lib_swagger = {\n        \"css\": \"https://unpkg.com/swagger-ui-dist@3/swagger-ui.css\",\n        \"js\": \"https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js\",\n    }\n\n    extra_javascript = config.get(\"extra_javascript\", [])\n    extra_css = config.get(\"extra_css\", [])\n    for lib in extra_javascript:\n        if os.path.basename(urllib.parse.urlparse(lib).path) == \"swagger-ui-bundle.js\":\n            lib_swagger[\"js\"] = lib\n            break\n\n    for css in extra_css:\n        if os.path.basename(urllib.parse.urlparse(css).path) == \"swagger-ui.css\":\n            lib_swagger[\"css\"] = css\n            break\n    return lib_swagger\n</code></pre>","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/services/","title":"services","text":"","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/services/#prefect.utilities.services","title":"<code>prefect.utilities.services</code>","text":"","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/services/#prefect.utilities.services.critical_service_loop","title":"<code>critical_service_loop</code>  <code>async</code>","text":"<p>Runs the given <code>workload</code> function on the specified <code>interval</code>, while being forgiving of intermittent issues like temporary HTTP errors.  If more than a certain number of <code>consecutive</code> errors occur, print a summary of up to <code>memory</code> recent exceptions to <code>printer</code>, then begin backoff.</p> <p>The loop will exit after reaching the consecutive error limit <code>backoff</code> times. On each backoff, the interval will be doubled. On a successful loop, the backoff will be reset.</p> <p>Parameters:</p> Name Type Description Default <code>workload</code> <code>Callable[..., Coroutine]</code> <p>the function to call</p> required <code>interval</code> <code>float</code> <p>how frequently to call it</p> required <code>memory</code> <code>int</code> <p>how many recent errors to remember</p> <code>10</code> <code>consecutive</code> <code>int</code> <p>how many consecutive errors must we see before we begin backoff</p> <code>3</code> <code>backoff</code> <code>int</code> <p>how many times we should allow consecutive errors before exiting</p> <code>1</code> <code>printer</code> <code>Callable[..., None]</code> <p>a <code>print</code>-like function where errors will be reported</p> <code>print</code> <code>run_once</code> <code>bool</code> <p>if set, the loop will only run once then return</p> <code>False</code> <code>jitter_range</code> <code>float</code> <p>if set, the interval will be a random variable (rv) drawn from a clamped Poisson distribution where lambda = interval and the rv is bound between <code>interval * (1 - range) &lt; rv &lt; interval * (1 + range)</code></p> <code>None</code> Source code in <code>prefect/utilities/services.py</code> <pre><code>async def critical_service_loop(\n    workload: Callable[..., Coroutine],\n    interval: float,\n    memory: int = 10,\n    consecutive: int = 3,\n    backoff: int = 1,\n    printer: Callable[..., None] = print,\n    run_once: bool = False,\n    jitter_range: float = None,\n):\n    \"\"\"\n    Runs the given `workload` function on the specified `interval`, while being\n    forgiving of intermittent issues like temporary HTTP errors.  If more than a certain\n    number of `consecutive` errors occur, print a summary of up to `memory` recent\n    exceptions to `printer`, then begin backoff.\n\n    The loop will exit after reaching the consecutive error limit `backoff` times.\n    On each backoff, the interval will be doubled. On a successful loop, the backoff\n    will be reset.\n\n    Args:\n        workload: the function to call\n        interval: how frequently to call it\n        memory: how many recent errors to remember\n        consecutive: how many consecutive errors must we see before we begin backoff\n        backoff: how many times we should allow consecutive errors before exiting\n        printer: a `print`-like function where errors will be reported\n        run_once: if set, the loop will only run once then return\n        jitter_range: if set, the interval will be a random variable (rv) drawn from\n            a clamped Poisson distribution where lambda = interval and the rv is bound\n            between `interval * (1 - range) &lt; rv &lt; interval * (1 + range)`\n    \"\"\"\n\n    track_record: Deque[bool] = deque([True] * consecutive, maxlen=consecutive)\n    failures: Deque[Tuple[Exception, TracebackType]] = deque(maxlen=memory)\n    backoff_count = 0\n\n    while True:\n        try:\n            workload_display_name = (\n                workload.__name__ if hasattr(workload, \"__name__\") else workload\n            )\n            logger.debug(f\"Starting run of {workload_display_name!r}\")\n            await workload()\n\n            # Reset the backoff count on success; we may want to consider resetting\n            # this only if the track record is _all_ successful to avoid ending backoff\n            # prematurely\n            if backoff_count &gt; 0:\n                printer(\"Resetting backoff due to successful run.\")\n                backoff_count = 0\n\n            track_record.append(True)\n        except CancelledError as exc:\n            # Exit immediately because the task was cancelled, possibly due\n            # to a signal or timeout.\n            logger.debug(f\"Run of {workload!r} cancelled\", exc_info=exc)\n            return\n        except httpx.TransportError as exc:\n            # httpx.TransportError is the base class for any kind of communications\n            # error, like timeouts, connection failures, etc.  This does _not_ cover\n            # routine HTTP error codes (even 5xx errors like 502/503) so this\n            # handler should not be attempting to cover cases where the Prefect server\n            # or Prefect Cloud is having an outage (which will be covered by the\n            # exception clause below)\n            track_record.append(False)\n            failures.append((exc, sys.exc_info()[-1]))\n            logger.debug(\n                f\"Run of {workload!r} failed with TransportError\", exc_info=exc\n            )\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code &gt;= 500:\n                # 5XX codes indicate a potential outage of the Prefect API which is\n                # likely to be temporary and transient.  Don't quit over these unless\n                # it is prolonged.\n                track_record.append(False)\n                failures.append((exc, sys.exc_info()[-1]))\n                logger.debug(\n                    f\"Run of {workload!r} failed with HTTPStatusError\", exc_info=exc\n                )\n            else:\n                raise\n\n        # Decide whether to exit now based on recent history.\n        #\n        # Given some typical background error rate of, say, 1%, we may still observe\n        # quite a few errors in our recent samples, but this is not necessarily a cause\n        # for concern.\n        #\n        # Imagine two distributions that could reflect our situation at any time: the\n        # everything-is-fine distribution of errors, and the everything-is-on-fire\n        # distribution of errors. We are trying to determine which of those two worlds\n        # we are currently experiencing.  We compare the likelihood that we'd draw N\n        # consecutive errors from each.  In the everything-is-fine distribution, that\n        # would be a very low-probability occurrence, but in the everything-is-on-fire\n        # distribution, that is a high-probability occurrence.\n        #\n        # Remarkably, we only need to look back for a small number of consecutive\n        # errors to have reasonable confidence that this is indeed an anomaly.\n        # @anticorrelator and @chrisguidry estimated that we should only need to look\n        # back for 3 consecutive errors.\n        if not any(track_record):\n            # We've failed enough times to be sure something is wrong, the writing is\n            # on the wall.  Let's explain what we've seen and exit.\n            printer(\n                f\"\\nFailed the last {consecutive} attempts. \"\n                \"Please check your environment and configuration.\"\n            )\n\n            printer(\"Examples of recent errors:\\n\")\n\n            failures_by_type = distinct(\n                reversed(failures),\n                key=lambda pair: type(pair[0]),  # Group by the type of exception\n            )\n            for exception, traceback in failures_by_type:\n                printer(\"\".join(format_exception(None, exception, traceback)))\n                printer()\n\n            backoff_count += 1\n\n            if backoff_count &gt;= backoff:\n                raise RuntimeError(\"Service exceeded error threshold.\")\n\n            # Reset the track record\n            track_record.extend([True] * consecutive)\n            failures.clear()\n            printer(\n                \"Backing off due to consecutive errors, using increased interval of \"\n                f\" {interval * 2 ** backoff_count}s.\"\n            )\n\n        if run_once:\n            return\n\n        if jitter_range is not None:\n            sleep = clamped_poisson_interval(interval, clamping_factor=jitter_range)\n        else:\n            sleep = interval * 2**backoff_count\n\n        await anyio.sleep(sleep)\n</code></pre>","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/slugify/","title":"slugify","text":"","tags":["Python API","slugify"]},{"location":"api-ref/prefect/utilities/slugify/#prefect.utilities.slugify","title":"<code>prefect.utilities.slugify</code>","text":"","tags":["Python API","slugify"]},{"location":"api-ref/prefect/utilities/templating/","title":"templating","text":"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating","title":"<code>prefect.utilities.templating</code>","text":"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.apply_values","title":"<code>apply_values</code>","text":"<p>Replaces placeholders in a template with values from a supplied dictionary.</p> <p>Will recursively replace placeholders in dictionaries and lists.</p> <p>If a value has no placeholders, it will be returned unchanged.</p> <p>If a template contains only a single placeholder, the placeholder will be fully replaced with the value.</p> <p>If a template contains text before or after a placeholder or there are multiple placeholders, the placeholders will be replaced with the corresponding variable values.</p> <p>If a template contains a placeholder that is not in <code>values</code>, NotSet will be returned to signify that no placeholder replacement occurred. If <code>template</code> is a dictionary that contains a key with a value of NotSet, the key will be removed in the return value unless <code>remove_notset</code> is set to False.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>template to discover and replace values in</p> required <code>values</code> <code>Dict[str, Any]</code> <p>The values to apply to placeholders in the template</p> required <code>remove_notset</code> <code>bool</code> <p>If True, remove keys with an unset value</p> <code>True</code> <p>Returns:</p> Type Description <code>Union[T, Type[NotSet]]</code> <p>The template with the values applied</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def apply_values(\n    template: T, values: Dict[str, Any], remove_notset: bool = True\n) -&gt; Union[T, Type[NotSet]]:\n    \"\"\"\n    Replaces placeholders in a template with values from a supplied dictionary.\n\n    Will recursively replace placeholders in dictionaries and lists.\n\n    If a value has no placeholders, it will be returned unchanged.\n\n    If a template contains only a single placeholder, the placeholder will be\n    fully replaced with the value.\n\n    If a template contains text before or after a placeholder or there are\n    multiple placeholders, the placeholders will be replaced with the\n    corresponding variable values.\n\n    If a template contains a placeholder that is not in `values`, NotSet will\n    be returned to signify that no placeholder replacement occurred. If\n    `template` is a dictionary that contains a key with a value of NotSet,\n    the key will be removed in the return value unless `remove_notset` is set to False.\n\n    Args:\n        template: template to discover and replace values in\n        values: The values to apply to placeholders in the template\n        remove_notset: If True, remove keys with an unset value\n\n    Returns:\n        The template with the values applied\n    \"\"\"\n    if isinstance(template, (int, float, bool, type(NotSet), type(None))):\n        return template\n    if isinstance(template, str):\n        placeholders = find_placeholders(template)\n        if not placeholders:\n            # If there are no values, we can just use the template\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.STANDARD\n        ):\n            # If there is only one variable with no surrounding text,\n            # we can replace it. If there is no variable value, we\n            # return NotSet to indicate that the value should not be included.\n            return get_from_dict(values, list(placeholders)[0].name, NotSet)\n        else:\n            for full_match, name, placeholder_type in placeholders:\n                if placeholder_type is PlaceholderType.STANDARD:\n                    value = get_from_dict(values, name, NotSet)\n                elif placeholder_type is PlaceholderType.ENV_VAR:\n                    name = name.lstrip(ENV_VAR_PLACEHOLDER_PREFIX)\n                    value = os.environ.get(name, NotSet)\n                else:\n                    continue\n\n                if value is NotSet and not remove_notset:\n                    continue\n                elif value is NotSet:\n                    template = template.replace(full_match, \"\")\n                else:\n                    template = template.replace(full_match, str(value))\n\n            return template\n    elif isinstance(template, dict):\n        updated_template = {}\n        for key, value in template.items():\n            updated_value = apply_values(value, values, remove_notset=remove_notset)\n            if updated_value is not NotSet:\n                updated_template[key] = updated_value\n            elif not remove_notset:\n                updated_template[key] = value\n\n        return updated_template\n    elif isinstance(template, list):\n        updated_list = []\n        for value in template:\n            updated_value = apply_values(value, values, remove_notset=remove_notset)\n            if updated_value is not NotSet:\n                updated_list.append(updated_value)\n        return updated_list\n    else:\n        raise ValueError(f\"Unexpected template type {type(template).__name__!r}\")\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.determine_placeholder_type","title":"<code>determine_placeholder_type</code>","text":"<p>Determines the type of a placeholder based on its name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the placeholder</p> required <p>Returns:</p> Type Description <code>PlaceholderType</code> <p>The type of the placeholder</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def determine_placeholder_type(name: str) -&gt; PlaceholderType:\n    \"\"\"\n    Determines the type of a placeholder based on its name.\n\n    Args:\n        name: The name of the placeholder\n\n    Returns:\n        The type of the placeholder\n    \"\"\"\n    if name.startswith(BLOCK_DOCUMENT_PLACEHOLDER_PREFIX):\n        return PlaceholderType.BLOCK_DOCUMENT\n    elif name.startswith(VARIABLE_PLACEHOLDER_PREFIX):\n        return PlaceholderType.VARIABLE\n    elif name.startswith(ENV_VAR_PLACEHOLDER_PREFIX):\n        return PlaceholderType.ENV_VAR\n    else:\n        return PlaceholderType.STANDARD\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.find_placeholders","title":"<code>find_placeholders</code>","text":"<p>Finds all placeholders in a template.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>template to discover placeholders in</p> required <p>Returns:</p> Type Description <code>Set[Placeholder]</code> <p>A set of all placeholders in the template</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def find_placeholders(template: T) -&gt; Set[Placeholder]:\n    \"\"\"\n    Finds all placeholders in a template.\n\n    Args:\n        template: template to discover placeholders in\n\n    Returns:\n        A set of all placeholders in the template\n    \"\"\"\n    if isinstance(template, (int, float, bool)):\n        return set()\n    if isinstance(template, str):\n        result = PLACEHOLDER_CAPTURE_REGEX.findall(template)\n        return {\n            Placeholder(full_match, name, determine_placeholder_type(name))\n            for full_match, name in result\n        }\n    elif isinstance(template, dict):\n        return set().union(\n            *[find_placeholders(value) for key, value in template.items()]\n        )\n    elif isinstance(template, list):\n        return set().union(*[find_placeholders(item) for item in template])\n    else:\n        raise ValueError(f\"Unexpected type: {type(template)}\")\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references","title":"<code>resolve_block_document_references</code>  <code>async</code>","text":"<p>Resolve block document references in a template by replacing each reference with the data of the block document.</p> <p>Recursively searches for block document references in dictionaries and lists.</p> <p>Identifies block document references by the as dictionary with the following structure: <pre><code>{\n    \"$ref\": {\n        \"block_document_id\": &lt;block_document_id&gt;\n    }\n}\n</code></pre> where <code>&lt;block_document_id&gt;</code> is the ID of the block document to resolve.</p> <p>Once the block document is retrieved from the API, the data of the block document is used to replace the reference.</p>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references--accessing-values","title":"Accessing Values:","text":"<p>To access different values in a block document, use dot notation combined with the block document's prefix, slug, and block name.</p> <p>For a block document with the structure: <pre><code>{\n    \"value\": {\n        \"key\": {\n            \"nested-key\": \"nested-value\"\n        },\n        \"list\": [\n            {\"list-key\": \"list-value\"},\n            1,\n            2\n        ]\n    }\n}\n</code></pre> examples of value resolution are as follows:</p> <ol> <li> <p>Accessing a nested dictionary:    Format: prefect.blocks...value.key    Example: Returns {\"nested-key\": \"nested-value\"} <li> <p>Accessing a specific nested value:    Format: prefect.blocks...value.key.nested-key    Example: Returns \"nested-value\" <li> <p>Accessing a list element's key-value:    Format: prefect.blocks...value.list[0].list-key    Example: Returns \"list-value\"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references--default-resolution-for-system-blocks","title":"Default Resolution for System Blocks:","text":"<p>For system blocks, which only contain a <code>value</code> attribute, this attribute is resolved by default.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>The template to resolve block documents in</p> required <p>Returns:</p> Type Description <code>Union[T, Dict[str, Any]]</code> <p>The template with block documents resolved</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>@inject_client\nasync def resolve_block_document_references(\n    template: T, client: \"PrefectClient\" = None\n) -&gt; Union[T, Dict[str, Any]]:\n    \"\"\"\n    Resolve block document references in a template by replacing each reference with\n    the data of the block document.\n\n    Recursively searches for block document references in dictionaries and lists.\n\n    Identifies block document references by the as dictionary with the following\n    structure:\n    ```\n    {\n        \"$ref\": {\n            \"block_document_id\": &lt;block_document_id&gt;\n        }\n    }\n    ```\n    where `&lt;block_document_id&gt;` is the ID of the block document to resolve.\n\n    Once the block document is retrieved from the API, the data of the block document\n    is used to replace the reference.\n\n    Accessing Values:\n    -----------------\n    To access different values in a block document, use dot notation combined with the block document's prefix, slug, and block name.\n\n    For a block document with the structure:\n    ```json\n    {\n        \"value\": {\n            \"key\": {\n                \"nested-key\": \"nested-value\"\n            },\n            \"list\": [\n                {\"list-key\": \"list-value\"},\n                1,\n                2\n            ]\n        }\n    }\n    ```\n    examples of value resolution are as follows:\n\n    1. Accessing a nested dictionary:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.key\n       Example: Returns {\"nested-key\": \"nested-value\"}\n\n    2. Accessing a specific nested value:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.key.nested-key\n       Example: Returns \"nested-value\"\n\n    3. Accessing a list element's key-value:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.list[0].list-key\n       Example: Returns \"list-value\"\n\n    Default Resolution for System Blocks:\n    -------------------------------------\n    For system blocks, which only contain a `value` attribute, this attribute is resolved by default.\n\n    Args:\n        template: The template to resolve block documents in\n\n    Returns:\n        The template with block documents resolved\n    \"\"\"\n    if isinstance(template, dict):\n        block_document_id = template.get(\"$ref\", {}).get(\"block_document_id\")\n        if block_document_id:\n            block_document = await client.read_block_document(block_document_id)\n            return block_document.data\n        updated_template = {}\n        for key, value in template.items():\n            updated_value = await resolve_block_document_references(\n                value, client=client\n            )\n            updated_template[key] = updated_value\n        return updated_template\n    elif isinstance(template, list):\n        return [\n            await resolve_block_document_references(item, client=client)\n            for item in template\n        ]\n    elif isinstance(template, str):\n        placeholders = find_placeholders(template)\n        has_block_document_placeholder = any(\n            placeholder.type is PlaceholderType.BLOCK_DOCUMENT\n            for placeholder in placeholders\n        )\n        if len(placeholders) == 0 or not has_block_document_placeholder:\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.BLOCK_DOCUMENT\n        ):\n            # value_keypath will be a list containing a dot path if additional\n            # attributes are accessed and an empty list otherwise.\n            block_type_slug, block_document_name, *value_keypath = (\n                list(placeholders)[0]\n                .name.replace(BLOCK_DOCUMENT_PLACEHOLDER_PREFIX, \"\")\n                .split(\".\", 2)\n            )\n            block_document = await client.read_block_document_by_name(\n                name=block_document_name, block_type_slug=block_type_slug\n            )\n            value = block_document.data\n\n            # resolving system blocks to their data for backwards compatibility\n            if len(value) == 1 and \"value\" in value:\n                # only resolve the value if the keypath is not already pointing to \"value\"\n                if len(value_keypath) == 0 or value_keypath[0][:5] != \"value\":\n                    value = value[\"value\"]\n\n            # resolving keypath/block attributes\n            if len(value_keypath) &gt; 0:\n                value_keypath: str = value_keypath[0]\n                value = get_from_dict(value, value_keypath, default=NotSet)\n                if value is NotSet:\n                    raise ValueError(\n                        f\"Invalid template: {template!r}. Could not resolve the\"\n                        \" keypath in the block document data.\"\n                    )\n\n            return value\n        else:\n            raise ValueError(\n                f\"Invalid template: {template!r}. Only a single block placeholder is\"\n                \" allowed in a string and no surrounding text is allowed.\"\n            )\n\n    return template\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_variables","title":"<code>resolve_variables</code>  <code>async</code>","text":"<p>Resolve variables in a template by replacing each variable placeholder with the value of the variable.</p> <p>Recursively searches for variable placeholders in dictionaries and lists.</p> <p>Strips variable placeholders if the variable is not found.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>The template to resolve variables in</p> required <p>Returns:</p> Type Description <p>The template with variables resolved</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>@inject_client\nasync def resolve_variables(template: T, client: \"PrefectClient\" = None):\n    \"\"\"\n    Resolve variables in a template by replacing each variable placeholder with the\n    value of the variable.\n\n    Recursively searches for variable placeholders in dictionaries and lists.\n\n    Strips variable placeholders if the variable is not found.\n\n    Args:\n        template: The template to resolve variables in\n\n    Returns:\n        The template with variables resolved\n    \"\"\"\n    if isinstance(template, str):\n        placeholders = find_placeholders(template)\n        has_variable_placeholder = any(\n            placeholder.type is PlaceholderType.VARIABLE for placeholder in placeholders\n        )\n        if not placeholders or not has_variable_placeholder:\n            # If there are no values, we can just use the template\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.VARIABLE\n        ):\n            variable_name = list(placeholders)[0].name.replace(\n                VARIABLE_PLACEHOLDER_PREFIX, \"\"\n            )\n            variable = await client.read_variable_by_name(name=variable_name)\n            if variable is None:\n                return \"\"\n            else:\n                return variable.value\n        else:\n            for full_match, name, placeholder_type in placeholders:\n                if placeholder_type is PlaceholderType.VARIABLE:\n                    variable_name = name.replace(VARIABLE_PLACEHOLDER_PREFIX, \"\")\n                    variable = await client.read_variable_by_name(name=variable_name)\n                    if variable is None:\n                        template = template.replace(full_match, \"\")\n                    else:\n                        template = template.replace(full_match, variable.value)\n            return template\n    elif isinstance(template, dict):\n        return {\n            key: await resolve_variables(value, client=client)\n            for key, value in template.items()\n        }\n    elif isinstance(template, list):\n        return [await resolve_variables(item, client=client) for item in template]\n    else:\n        return template\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/text/","title":"text","text":"","tags":["Python API","text"]},{"location":"api-ref/prefect/utilities/text/#prefect.utilities.text","title":"<code>prefect.utilities.text</code>","text":"","tags":["Python API","text"]},{"location":"api-ref/prefect/utilities/visualization/","title":"visualization","text":"","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization","title":"<code>prefect.utilities.visualization</code>","text":"<p>Utilities for working with Flow.visualize()</p>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.TaskVizTracker","title":"<code>TaskVizTracker</code>","text":"Source code in <code>prefect/utilities/visualization.py</code> <pre><code>class TaskVizTracker:\n    def __init__(self):\n        self.tasks = []\n        self.dynamic_task_counter = {}\n        self.object_id_to_task = {}\n\n    def add_task(self, task: VizTask):\n        if task.name not in self.dynamic_task_counter:\n            self.dynamic_task_counter[task.name] = 0\n        else:\n            self.dynamic_task_counter[task.name] += 1\n\n        task.name = f\"{task.name}-{self.dynamic_task_counter[task.name]}\"\n        self.tasks.append(task)\n\n    def __enter__(self):\n        TaskVizTrackerState.current = self\n        return self\n\n    def __exit__(self, exc_type, exc_val, exc_tb):\n        TaskVizTrackerState.current = None\n\n    def link_viz_return_value_to_viz_task(\n        self, viz_return_value: Any, viz_task: VizTask\n    ) -&gt; None:\n        \"\"\"\n        We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256\n        because they are singletons.\n        \"\"\"\n        from prefect.utilities.engine import UNTRACKABLE_TYPES\n\n        if (type(viz_return_value) in UNTRACKABLE_TYPES) or (\n            isinstance(viz_return_value, int) and (-5 &lt;= viz_return_value &lt;= 256)\n        ):\n            return\n        self.object_id_to_task[id(viz_return_value)] = viz_task\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.TaskVizTracker.link_viz_return_value_to_viz_task","title":"<code>link_viz_return_value_to_viz_task</code>","text":"<p>We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256 because they are singletons.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def link_viz_return_value_to_viz_task(\n    self, viz_return_value: Any, viz_task: VizTask\n) -&gt; None:\n    \"\"\"\n    We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256\n    because they are singletons.\n    \"\"\"\n    from prefect.utilities.engine import UNTRACKABLE_TYPES\n\n    if (type(viz_return_value) in UNTRACKABLE_TYPES) or (\n        isinstance(viz_return_value, int) and (-5 &lt;= viz_return_value &lt;= 256)\n    ):\n        return\n    self.object_id_to_task[id(viz_return_value)] = viz_task\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.build_task_dependencies","title":"<code>build_task_dependencies</code>","text":"<p>Constructs a Graphviz directed graph object that represents the dependencies between tasks in the given TaskVizTracker.</p> <ul> <li>task_run_tracker (TaskVizTracker): An object containing tasks and their   dependencies.</li> </ul> <ul> <li>graphviz.Digraph: A directed graph object depicting the relationships and   dependencies between tasks.</li> </ul> <p>Raises: - GraphvizImportError: If there's an ImportError related to graphviz. - FlowVisualizationError: If there's any other error during the visualization   process or if return values of tasks are directly accessed without   specifying a <code>viz_return_value</code>.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def build_task_dependencies(task_run_tracker: TaskVizTracker):\n    \"\"\"\n    Constructs a Graphviz directed graph object that represents the dependencies\n    between tasks in the given TaskVizTracker.\n\n    Parameters:\n    - task_run_tracker (TaskVizTracker): An object containing tasks and their\n      dependencies.\n\n    Returns:\n    - graphviz.Digraph: A directed graph object depicting the relationships and\n      dependencies between tasks.\n\n    Raises:\n    - GraphvizImportError: If there's an ImportError related to graphviz.\n    - FlowVisualizationError: If there's any other error during the visualization\n      process or if return values of tasks are directly accessed without\n      specifying a `viz_return_value`.\n    \"\"\"\n    try:\n        g = graphviz.Digraph()\n        for task in task_run_tracker.tasks:\n            g.node(task.name)\n            for upstream in task.upstream_tasks:\n                g.edge(upstream.name, task.name)\n        return g\n    except ImportError as exc:\n        raise GraphvizImportError from exc\n    except Exception:\n        raise FlowVisualizationError(\n            \"Something went wrong building the flow's visualization.\"\n            \" If you're interacting with the return value of a task\"\n            \" directly inside of your flow, you must set a set a `viz_return_value`\"\n            \", for example `@task(viz_return_value=[1, 2, 3])`.\"\n        )\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.track_viz_task","title":"<code>track_viz_task</code>","text":"<p>Return a result if sync otherwise return a coroutine that returns the result</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def track_viz_task(\n    is_async: bool,\n    task_name: str,\n    parameters: dict,\n    viz_return_value: Optional[Any] = None,\n):\n    \"\"\"Return a result if sync otherwise return a coroutine that returns the result\"\"\"\n    if is_async:\n        return from_async.wait_for_call_in_loop_thread(\n            partial(_track_viz_task, task_name, parameters, viz_return_value)\n        )\n    else:\n        return _track_viz_task(task_name, parameters, viz_return_value)\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.visualize_task_dependencies","title":"<code>visualize_task_dependencies</code>","text":"<p>Renders and displays a Graphviz directed graph representing task dependencies.</p> <p>The graph is rendered in PNG format and saved with the name specified by flow_run_name. After rendering, the visualization is opened and displayed.</p> <p>Parameters: - graph (graphviz.Digraph): The directed graph object to visualize. - flow_run_name (str): The name to use when saving the rendered graph image.</p> <p>Raises: - GraphvizExecutableNotFoundError: If Graphviz isn't found on the system. - FlowVisualizationError: If there's any other error during the visualization   process or if return values of tasks are directly accessed without   specifying a <code>viz_return_value</code>.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def visualize_task_dependencies(graph: graphviz.Digraph, flow_run_name: str):\n    \"\"\"\n    Renders and displays a Graphviz directed graph representing task dependencies.\n\n    The graph is rendered in PNG format and saved with the name specified by\n    flow_run_name. After rendering, the visualization is opened and displayed.\n\n    Parameters:\n    - graph (graphviz.Digraph): The directed graph object to visualize.\n    - flow_run_name (str): The name to use when saving the rendered graph image.\n\n    Raises:\n    - GraphvizExecutableNotFoundError: If Graphviz isn't found on the system.\n    - FlowVisualizationError: If there's any other error during the visualization\n      process or if return values of tasks are directly accessed without\n      specifying a `viz_return_value`.\n    \"\"\"\n    try:\n        graph.render(filename=flow_run_name, view=True, format=\"png\", cleanup=True)\n    except graphviz.backend.ExecutableNotFound as exc:\n        msg = (\n            \"It appears you do not have Graphviz installed, or it is not on your \"\n            \"PATH. Please install Graphviz from http://www.graphviz.org/download/. \"\n            \"Note: Just installing the `graphviz` python package is not \"\n            \"sufficient.\"\n        )\n        raise GraphvizExecutableNotFoundError(msg) from exc\n    except Exception:\n        raise FlowVisualizationError(\n            \"Something went wrong building the flow's visualization.\"\n            \" If you're interacting with the return value of a task\"\n            \" directly inside of your flow, you must set a set a `viz_return_value`\"\n            \", for example `@task(viz_return_value=[1, 2, 3])`.\"\n        )\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/workers/base/","title":"base","text":"","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base","title":"<code>prefect.workers.base</code>","text":"","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration","title":"<code>BaseJobConfiguration</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>class BaseJobConfiguration(BaseModel):\n    command: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The command to use when starting a flow run. \"\n            \"In most cases, this should be left blank and the command \"\n            \"will be automatically generated by the worker.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to set when starting a flow run.\",\n    )\n    labels: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"Labels applied to infrastructure created by the worker using \"\n            \"this job configuration.\"\n        ),\n    )\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"Name given to infrastructure created by the worker using this \"\n            \"job configuration.\"\n        ),\n    )\n\n    _related_objects: Dict[str, Any] = PrivateAttr(default_factory=dict)\n\n    @property\n    def is_using_a_runner(self):\n        return self.command is not None and \"prefect flow-run execute\" in self.command\n\n    @validator(\"command\")\n    def _coerce_command(cls, v):\n        return return_v_or_none(v)\n\n    @staticmethod\n    def _get_base_config_defaults(variables: dict) -&gt; dict:\n        \"\"\"Get default values from base config for all variables that have them.\"\"\"\n        defaults = dict()\n        for variable_name, attrs in variables.items():\n            if \"default\" in attrs:\n                defaults[variable_name] = attrs[\"default\"]\n\n        return defaults\n\n    @classmethod\n    @inject_client\n    async def from_template_and_values(\n        cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n    ):\n        \"\"\"Creates a valid worker configuration object from the provided base\n        configuration and overrides.\n\n        Important: this method expects that the base_job_template was already\n        validated server-side.\n        \"\"\"\n        job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n        variables_schema = base_job_template[\"variables\"]\n        variables = cls._get_base_config_defaults(\n            variables_schema.get(\"properties\", {})\n        )\n        variables.update(values)\n\n        populated_configuration = apply_values(template=job_config, values=variables)\n        populated_configuration = await resolve_block_document_references(\n            template=populated_configuration, client=client\n        )\n        populated_configuration = await resolve_variables(\n            template=populated_configuration, client=client\n        )\n        return cls(**populated_configuration)\n\n    @classmethod\n    def json_template(cls) -&gt; dict:\n        \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n        Defaults to using the job configuration parameter name as the template variable name.\n\n        e.g.\n        {\n            key1: '{{ key1 }}',     # default variable template\n            key2: '{{ template2 }}', # `template2` specifically provide as template\n        }\n        \"\"\"\n        configuration = {}\n        properties = cls.schema()[\"properties\"]\n        for k, v in properties.items():\n            if v.get(\"template\"):\n                template = v[\"template\"]\n            else:\n                template = \"{{ \" + k + \" }}\"\n            configuration[k] = template\n\n        return configuration\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepare the job configuration for a flow run.\n\n        This method is called by the worker before starting a flow run. It\n        should be used to set any configuration values that are dependent on\n        the flow run.\n\n        Args:\n            flow_run: The flow run to be executed.\n            deployment: The deployment that the flow run is associated with.\n            flow: The flow that the flow run is associated with.\n        \"\"\"\n\n        self._related_objects = {\n            \"deployment\": deployment,\n            \"flow\": flow,\n            \"flow-run\": flow_run,\n        }\n        if deployment is not None:\n            deployment_labels = self._base_deployment_labels(deployment)\n        else:\n            deployment_labels = {}\n\n        if flow is not None:\n            flow_labels = self._base_flow_labels(flow)\n        else:\n            flow_labels = {}\n\n        env = {\n            **self._base_environment(),\n            **self._base_flow_run_environment(flow_run),\n            **self.env,\n        }\n        self.env = {key: value for key, value in env.items() if value is not None}\n        self.labels = {\n            **self._base_flow_run_labels(flow_run),\n            **deployment_labels,\n            **flow_labels,\n            **self.labels,\n        }\n        self.name = self.name or flow_run.name\n        self.command = self.command or self._base_flow_run_command()\n\n    @staticmethod\n    def _base_flow_run_command() -&gt; str:\n        \"\"\"\n        Generate a command for a flow run job.\n        \"\"\"\n        if experiment_enabled(\"enhanced_cancellation\"):\n            if (\n                PREFECT_EXPERIMENTAL_WARN\n                and PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION\n            ):\n                warnings.warn(\n                    EXPERIMENTAL_WARNING.format(\n                        feature=\"Enhanced flow run cancellation\",\n                        group=\"enhanced_cancellation\",\n                        help=\"\",\n                    ),\n                    ExperimentalFeature,\n                    stacklevel=3,\n                )\n            return \"prefect flow-run execute\"\n        return \"python -m prefect.engine\"\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": prefect.__version__,\n        }\n\n    @classmethod\n    def _base_environment(cls) -&gt; Dict[str, str]:\n        \"\"\"\n        Environment variables that should be passed to all created infrastructure.\n\n        These values should be overridable with the `env` field.\n        \"\"\"\n        return get_current_settings().to_environment_variables(exclude_unset=True)\n\n    @staticmethod\n    def _base_flow_run_environment(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of environment variables for a flow run job.\n        \"\"\"\n        return {\"PREFECT__FLOW_RUN_ID\": str(flow_run.id)}\n\n    @staticmethod\n    def _base_deployment_labels(deployment: \"DeploymentResponse\") -&gt; Dict[str, str]:\n        labels = {\n            \"prefect.io/deployment-id\": str(deployment.id),\n            \"prefect.io/deployment-name\": deployment.name,\n        }\n        if deployment.updated is not None:\n            labels[\"prefect.io/deployment-updated\"] = deployment.updated.in_timezone(\n                \"utc\"\n            ).to_iso8601_string()\n        return labels\n\n    @staticmethod\n    def _base_flow_labels(flow: \"Flow\") -&gt; Dict[str, str]:\n        return {\n            \"prefect.io/flow-id\": str(flow.id),\n            \"prefect.io/flow-name\": flow.name,\n        }\n\n    def _related_resources(self) -&gt; List[RelatedResource]:\n        tags = set()\n        related = []\n\n        for kind, obj in self._related_objects.items():\n            if obj is None:\n                continue\n            if hasattr(obj, \"tags\"):\n                tags.update(obj.tags)\n            related.append(object_as_related_resource(kind=kind, role=kind, object=obj))\n\n        return related + tags_as_related_resources(tags)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.from_template_and_values","title":"<code>from_template_and_values</code>  <code>async</code> <code>classmethod</code>","text":"<p>Creates a valid worker configuration object from the provided base configuration and overrides.</p> <p>Important: this method expects that the base_job_template was already validated server-side.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@classmethod\n@inject_client\nasync def from_template_and_values(\n    cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n):\n    \"\"\"Creates a valid worker configuration object from the provided base\n    configuration and overrides.\n\n    Important: this method expects that the base_job_template was already\n    validated server-side.\n    \"\"\"\n    job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n    variables_schema = base_job_template[\"variables\"]\n    variables = cls._get_base_config_defaults(\n        variables_schema.get(\"properties\", {})\n    )\n    variables.update(values)\n\n    populated_configuration = apply_values(template=job_config, values=variables)\n    populated_configuration = await resolve_block_document_references(\n        template=populated_configuration, client=client\n    )\n    populated_configuration = await resolve_variables(\n        template=populated_configuration, client=client\n    )\n    return cls(**populated_configuration)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.json_template","title":"<code>json_template</code>  <code>classmethod</code>","text":"<p>Returns a dict with job configuration as keys and the corresponding templates as values</p> <p>Defaults to using the job configuration parameter name as the template variable name.</p> <p>e.g. {     key1: '{{ key1 }}',     # default variable template     key2: '{{ template2 }}', # <code>template2</code> specifically provide as template }</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@classmethod\ndef json_template(cls) -&gt; dict:\n    \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n    Defaults to using the job configuration parameter name as the template variable name.\n\n    e.g.\n    {\n        key1: '{{ key1 }}',     # default variable template\n        key2: '{{ template2 }}', # `template2` specifically provide as template\n    }\n    \"\"\"\n    configuration = {}\n    properties = cls.schema()[\"properties\"]\n    for k, v in properties.items():\n        if v.get(\"template\"):\n            template = v[\"template\"]\n        else:\n            template = \"{{ \" + k + \" }}\"\n        configuration[k] = template\n\n    return configuration\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepare the job configuration for a flow run.</p> <p>This method is called by the worker before starting a flow run. It should be used to set any configuration values that are dependent on the flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to be executed.</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment that the flow run is associated with.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow that the flow run is associated with.</p> <code>None</code> Source code in <code>prefect/workers/base.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepare the job configuration for a flow run.\n\n    This method is called by the worker before starting a flow run. It\n    should be used to set any configuration values that are dependent on\n    the flow run.\n\n    Args:\n        flow_run: The flow run to be executed.\n        deployment: The deployment that the flow run is associated with.\n        flow: The flow that the flow run is associated with.\n    \"\"\"\n\n    self._related_objects = {\n        \"deployment\": deployment,\n        \"flow\": flow,\n        \"flow-run\": flow_run,\n    }\n    if deployment is not None:\n        deployment_labels = self._base_deployment_labels(deployment)\n    else:\n        deployment_labels = {}\n\n    if flow is not None:\n        flow_labels = self._base_flow_labels(flow)\n    else:\n        flow_labels = {}\n\n    env = {\n        **self._base_environment(),\n        **self._base_flow_run_environment(flow_run),\n        **self.env,\n    }\n    self.env = {key: value for key, value in env.items() if value is not None}\n    self.labels = {\n        **self._base_flow_run_labels(flow_run),\n        **deployment_labels,\n        **flow_labels,\n        **self.labels,\n    }\n    self.name = self.name or flow_run.name\n    self.command = self.command or self._base_flow_run_command()\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker","title":"<code>BaseWorker</code>","text":"<p>               Bases: <code>ABC</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>@register_base_type\nclass BaseWorker(abc.ABC):\n    type: str\n    job_configuration: Type[BaseJobConfiguration] = BaseJobConfiguration\n    job_configuration_variables: Optional[Type[BaseVariables]] = None\n\n    _documentation_url = \"\"\n    _logo_url = \"\"\n    _description = \"\"\n\n    def __init__(\n        self,\n        work_pool_name: str,\n        work_queues: Optional[List[str]] = None,\n        name: Optional[str] = None,\n        prefetch_seconds: Optional[float] = None,\n        create_pool_if_not_found: bool = True,\n        limit: Optional[int] = None,\n        heartbeat_interval_seconds: Optional[int] = None,\n        *,\n        base_job_template: Optional[Dict[str, Any]] = None,\n    ):\n        \"\"\"\n        Base class for all Prefect workers.\n\n        Args:\n            name: The name of the worker. If not provided, a random one\n                will be generated. If provided, it cannot contain '/' or '%'.\n                The name is used to identify the worker in the UI; if two\n                processes have the same name, they will be treated as the same\n                worker.\n            work_pool_name: The name of the work pool to poll.\n            work_queues: A list of work queues to poll. If not provided, all\n                work queue in the work pool will be polled.\n            prefetch_seconds: The number of seconds to prefetch flow runs for.\n            create_pool_if_not_found: Whether to create the work pool\n                if it is not found. Defaults to `True`, but can be set to `False` to\n                ensure that work pools are not created accidentally.\n            limit: The maximum number of flow runs this worker should be running at\n                a given time.\n            base_job_template: If creating the work pool, provide the base job\n                template to use. Logs a warning if the pool already exists.\n        \"\"\"\n        if name and (\"/\" in name or \"%\" in name):\n            raise ValueError(\"Worker name cannot contain '/' or '%'\")\n        self.name = name or f\"{self.__class__.__name__} {uuid4()}\"\n        self._logger = get_logger(f\"worker.{self.__class__.type}.{self.name.lower()}\")\n\n        self.is_setup = False\n        self._create_pool_if_not_found = create_pool_if_not_found\n        self._base_job_template = base_job_template\n        self._work_pool_name = work_pool_name\n        self._work_queues: Set[str] = set(work_queues) if work_queues else set()\n\n        self._prefetch_seconds: float = (\n            prefetch_seconds or PREFECT_WORKER_PREFETCH_SECONDS.value()\n        )\n        self.heartbeat_interval_seconds = (\n            heartbeat_interval_seconds or PREFECT_WORKER_HEARTBEAT_SECONDS.value()\n        )\n\n        self._work_pool: Optional[WorkPool] = None\n        self._runs_task_group: Optional[anyio.abc.TaskGroup] = None\n        self._client: Optional[PrefectClient] = None\n        self._last_polled_time: pendulum.DateTime = pendulum.now(\"utc\")\n        self._limit = limit\n        self._limiter: Optional[anyio.CapacityLimiter] = None\n        self._submitting_flow_run_ids = set()\n        self._cancelling_flow_run_ids = set()\n        self._scheduled_task_scopes = set()\n\n    @classmethod\n    def get_documentation_url(cls) -&gt; str:\n        return cls._documentation_url\n\n    @classmethod\n    def get_logo_url(cls) -&gt; str:\n        return cls._logo_url\n\n    @classmethod\n    def get_description(cls) -&gt; str:\n        return cls._description\n\n    @classmethod\n    def get_default_base_job_template(cls) -&gt; Dict:\n        if cls.job_configuration_variables is None:\n            schema = cls.job_configuration.schema()\n            # remove \"template\" key from all dicts in schema['properties'] because it is not a\n            # relevant field\n            for key, value in schema[\"properties\"].items():\n                if isinstance(value, dict):\n                    schema[\"properties\"][key].pop(\"template\", None)\n            variables_schema = schema\n        else:\n            variables_schema = cls.job_configuration_variables.schema()\n        variables_schema.pop(\"title\", None)\n        return {\n            \"job_configuration\": cls.job_configuration.json_template(),\n            \"variables\": variables_schema,\n        }\n\n    @staticmethod\n    def get_worker_class_from_type(type: str) -&gt; Optional[Type[\"BaseWorker\"]]:\n        \"\"\"\n        Returns the worker class for a given worker type. If the worker type\n        is not recognized, returns None.\n        \"\"\"\n        load_prefect_collections()\n        worker_registry = get_registry_for_type(BaseWorker)\n        if worker_registry is not None:\n            return worker_registry.get(type)\n\n    @staticmethod\n    def get_all_available_worker_types() -&gt; List[str]:\n        \"\"\"\n        Returns all worker types available in the local registry.\n        \"\"\"\n        load_prefect_collections()\n        worker_registry = get_registry_for_type(BaseWorker)\n        if worker_registry is not None:\n            return list(worker_registry.keys())\n        return []\n\n    def get_name_slug(self):\n        return slugify(self.name)\n\n    def get_flow_run_logger(self, flow_run: \"FlowRun\") -&gt; PrefectLogAdapter:\n        return flow_run_logger(flow_run=flow_run).getChild(\n            \"worker\",\n            extra={\n                \"worker_name\": self.name,\n                \"work_pool_name\": (\n                    self._work_pool_name if self._work_pool else \"&lt;unknown&gt;\"\n                ),\n                \"work_pool_id\": str(getattr(self._work_pool, \"id\", \"unknown\")),\n            },\n        )\n\n    @abc.abstractmethod\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: BaseJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        \"\"\"\n        Runs a given flow run on the current worker.\n        \"\"\"\n        raise NotImplementedError(\n            \"Workers must implement a method for running submitted flow runs\"\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: BaseJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Method for killing infrastructure created by a worker. Should be implemented by\n        individual workers if they support killing infrastructure.\n        \"\"\"\n        raise NotImplementedError(\n            \"This worker does not support killing infrastructure.\"\n        )\n\n    @classmethod\n    def __dispatch_key__(cls):\n        if cls.__name__ == \"BaseWorker\":\n            return None  # The base class is abstract\n        return cls.type\n\n    async def setup(self):\n        \"\"\"Prepares the worker to run.\"\"\"\n        self._logger.debug(\"Setting up worker...\")\n        self._runs_task_group = anyio.create_task_group()\n        self._limiter = (\n            anyio.CapacityLimiter(self._limit) if self._limit is not None else None\n        )\n        self._client = get_client()\n        await self._client.__aenter__()\n        await self._runs_task_group.__aenter__()\n\n        self.is_setup = True\n\n    async def teardown(self, *exc_info):\n        \"\"\"Cleans up resources after the worker is stopped.\"\"\"\n        self._logger.debug(\"Tearing down worker...\")\n        self.is_setup = False\n        for scope in self._scheduled_task_scopes:\n            scope.cancel()\n        if self._runs_task_group:\n            await self._runs_task_group.__aexit__(*exc_info)\n        if self._client:\n            await self._client.__aexit__(*exc_info)\n        self._runs_task_group = None\n        self._client = None\n\n    def is_worker_still_polling(self, query_interval_seconds: int) -&gt; bool:\n        \"\"\"\n        This method is invoked by a webserver healthcheck handler\n        and returns a boolean indicating if the worker has recorded a\n        scheduled flow run poll within a variable amount of time.\n\n        The `query_interval_seconds` is the same value that is used by\n        the loop services - we will evaluate if the _last_polled_time\n        was within that interval x 30 (so 10s -&gt; 5m)\n\n        The instance property `self._last_polled_time`\n        is currently set/updated in `get_and_submit_flow_runs()`\n        \"\"\"\n        threshold_seconds = query_interval_seconds * 30\n\n        seconds_since_last_poll = (\n            pendulum.now(\"utc\") - self._last_polled_time\n        ).in_seconds()\n\n        is_still_polling = seconds_since_last_poll &lt;= threshold_seconds\n\n        if not is_still_polling:\n            self._logger.error(\n                f\"Worker has not polled in the last {seconds_since_last_poll} seconds \"\n                \"and should be restarted\"\n            )\n\n        return is_still_polling\n\n    async def get_and_submit_flow_runs(self):\n        runs_response = await self._get_scheduled_flow_runs()\n\n        self._last_polled_time = pendulum.now(\"utc\")\n\n        return await self._submit_scheduled_flow_runs(flow_run_response=runs_response)\n\n    async def check_for_cancelled_flow_runs(self):\n        if not self.is_setup:\n            raise RuntimeError(\n                \"Worker is not set up. Please make sure you are running this worker \"\n                \"as an async context manager.\"\n            )\n\n        self._logger.debug(\"Checking for cancelled flow runs...\")\n\n        work_queue_filter = (\n            WorkQueueFilter(name=WorkQueueFilterName(any_=list(self._work_queues)))\n            if self._work_queues\n            else None\n        )\n\n        named_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self._cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=WorkPoolFilter(\n                name=WorkPoolFilterName(any_=[self._work_pool_name])\n            ),\n            work_queue_filter=work_queue_filter,\n        )\n\n        typed_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self._cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=WorkPoolFilter(\n                name=WorkPoolFilterName(any_=[self._work_pool_name])\n            ),\n            work_queue_filter=work_queue_filter,\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self._logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self._cancelling_flow_run_ids.add(flow_run.id)\n            self._runs_task_group.start_soon(self.cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def cancel_run(self, flow_run: \"FlowRun\"):\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            configuration = await self._get_configuration(flow_run)\n        except ObjectNotFound:\n            self._logger.warning(\n                f\"Flow run {flow_run.id!r} cannot be cancelled by this worker:\"\n                f\" associated deployment {flow_run.deployment_id!r} does not exist.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure configuration information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n        else:\n            if configuration.is_using_a_runner:\n                self._logger.info(\n                    f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                    \" using enhanced cancellation. A dedicated runner will handle\"\n                    \" cancellation.\"\n                )\n                return\n\n        if not flow_run.infrastructure_pid:\n            run_logger.error(\n                f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n                \" attached. Cancellation cannot be guaranteed.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure tracking information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            await self.kill_infrastructure(\n                infrastructure_pid=flow_run.infrastructure_pid,\n                configuration=configuration,\n            )\n        except NotImplementedError:\n            self._logger.error(\n                f\"Worker type {self.type!r} does not support killing created \"\n                \"infrastructure. Cancellation cannot be guaranteed.\"\n            )\n        except InfrastructureNotFound as exc:\n            self._logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except InfrastructureNotAvailable as exc:\n            self._logger.warning(f\"{exc} Flow run cannot be cancelled by this worker.\")\n        except Exception:\n            run_logger.exception(\n                \"Encountered exception while killing infrastructure for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self._cancelling_flow_run_ids.remove(flow_run.id)\n            return\n        else:\n            self._emit_flow_run_cancelled_event(\n                flow_run=flow_run, configuration=configuration\n            )\n            await self._mark_flow_run_as_cancelled(flow_run)\n            run_logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n\n    async def _update_local_work_pool_info(self):\n        try:\n            work_pool = await self._client.read_work_pool(\n                work_pool_name=self._work_pool_name\n            )\n        except ObjectNotFound:\n            if self._create_pool_if_not_found:\n                wp = WorkPoolCreate(\n                    name=self._work_pool_name,\n                    type=self.type,\n                )\n                if self._base_job_template is not None:\n                    wp.base_job_template = self._base_job_template\n\n                work_pool = await self._client.create_work_pool(work_pool=wp)\n                self._logger.info(f\"Work pool {self._work_pool_name!r} created.\")\n            else:\n                self._logger.warning(f\"Work pool {self._work_pool_name!r} not found!\")\n                if self._base_job_template is not None:\n                    self._logger.warning(\n                        \"Ignoring supplied base job template because the work pool\"\n                        \" already exists\"\n                    )\n                return\n\n        # if the remote config type changes (or if it's being loaded for the\n        # first time), check if it matches the local type and warn if not\n        if getattr(self._work_pool, \"type\", 0) != work_pool.type:\n            if work_pool.type != self.__class__.type:\n                self._logger.warning(\n                    \"Worker type mismatch! This worker process expects type \"\n                    f\"{self.type!r} but received {work_pool.type!r}\"\n                    \" from the server. Unexpected behavior may occur.\"\n                )\n\n        # once the work pool is loaded, verify that it has a `base_job_template` and\n        # set it if not\n        if not work_pool.base_job_template:\n            job_template = self.__class__.get_default_base_job_template()\n            await self._set_work_pool_template(work_pool, job_template)\n            work_pool.base_job_template = job_template\n\n        self._work_pool = work_pool\n\n    async def _send_worker_heartbeat(self):\n        if self._work_pool:\n            await self._client.send_worker_heartbeat(\n                work_pool_name=self._work_pool_name,\n                worker_name=self.name,\n                heartbeat_interval_seconds=self.heartbeat_interval_seconds,\n            )\n\n    async def sync_with_backend(self):\n        \"\"\"\n        Updates the worker's local information about it's current work pool and\n        queues. Sends a worker heartbeat to the API.\n        \"\"\"\n        await self._update_local_work_pool_info()\n\n        await self._send_worker_heartbeat()\n\n        self._logger.debug(\"Worker synchronized with the Prefect API server.\")\n\n    async def _get_scheduled_flow_runs(\n        self,\n    ) -&gt; List[\"WorkerFlowRunResponse\"]:\n        \"\"\"\n        Retrieve scheduled flow runs from the work pool's queues.\n        \"\"\"\n        scheduled_before = pendulum.now(\"utc\").add(seconds=int(self._prefetch_seconds))\n        self._logger.debug(\n            f\"Querying for flow runs scheduled before {scheduled_before}\"\n        )\n        try:\n            scheduled_flow_runs = (\n                await self._client.get_scheduled_flow_runs_for_work_pool(\n                    work_pool_name=self._work_pool_name,\n                    scheduled_before=scheduled_before,\n                    work_queue_names=list(self._work_queues),\n                )\n            )\n            self._logger.debug(\n                f\"Discovered {len(scheduled_flow_runs)} scheduled_flow_runs\"\n            )\n            return scheduled_flow_runs\n        except ObjectNotFound:\n            # the pool doesn't exist; it will be created on the next\n            # heartbeat (or an appropriate warning will be logged)\n            return []\n\n    async def _submit_scheduled_flow_runs(\n        self, flow_run_response: List[\"WorkerFlowRunResponse\"]\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Takes a list of WorkerFlowRunResponses and submits the referenced flow runs\n        for execution by the worker.\n        \"\"\"\n        submittable_flow_runs = [entry.flow_run for entry in flow_run_response]\n        submittable_flow_runs.sort(key=lambda run: run.next_scheduled_start_time)\n        for flow_run in submittable_flow_runs:\n            if flow_run.id in self._submitting_flow_run_ids:\n                continue\n\n            try:\n                if self._limiter:\n                    self._limiter.acquire_on_behalf_of_nowait(flow_run.id)\n            except anyio.WouldBlock:\n                self._logger.info(\n                    f\"Flow run limit reached; {self._limiter.borrowed_tokens} flow runs\"\n                    \" in progress.\"\n                )\n                break\n            else:\n                run_logger = self.get_flow_run_logger(flow_run)\n                run_logger.info(\n                    f\"Worker '{self.name}' submitting flow run '{flow_run.id}'\"\n                )\n                self._submitting_flow_run_ids.add(flow_run.id)\n                self._runs_task_group.start_soon(\n                    self._submit_run,\n                    flow_run,\n                )\n\n        return list(\n            filter(\n                lambda run: run.id in self._submitting_flow_run_ids,\n                submittable_flow_runs,\n            )\n        )\n\n    async def _check_flow_run(self, flow_run: \"FlowRun\") -&gt; None:\n        \"\"\"\n        Performs a check on a submitted flow run to warn the user if the flow run\n        was created from a deployment with a storage block.\n        \"\"\"\n        if flow_run.deployment_id:\n            assert (\n                self._client and self._client._started\n            ), \"Client must be started to check flow run deployment.\"\n            deployment = await self._client.read_deployment(flow_run.deployment_id)\n            if deployment.storage_document_id:\n                raise ValueError(\n                    f\"Flow run {flow_run.id!r} was created from deployment\"\n                    f\" {deployment.name!r} which is configured with a storage block.\"\n                    \" Please use an agent to execute this flow run.\"\n                )\n\n            #\n\n    async def _submit_run(self, flow_run: \"FlowRun\") -&gt; None:\n        \"\"\"\n        Submits a given flow run for execution by the worker.\n        \"\"\"\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            await self._check_flow_run(flow_run)\n        except (ValueError, ObjectNotFound):\n            self._logger.exception(\n                (\n                    \"Flow run %s did not pass checks and will not be submitted for\"\n                    \" execution\"\n                ),\n                flow_run.id,\n            )\n            self._submitting_flow_run_ids.remove(flow_run.id)\n            return\n\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            readiness_result = await self._runs_task_group.start(\n                self._submit_run_and_capture_errors, flow_run\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                try:\n                    await self._client.update_flow_run(\n                        flow_run_id=flow_run.id,\n                        infrastructure_pid=str(readiness_result),\n                    )\n                except Exception:\n                    run_logger.exception(\n                        \"An error occurred while setting the `infrastructure_pid` on \"\n                        f\"flow run {flow_run.id!r}. The flow run will \"\n                        \"not be cancellable.\"\n                    )\n\n            run_logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            if self._limiter:\n                self._limiter.release_on_behalf_of(flow_run.id)\n\n        self._submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self, flow_run: \"FlowRun\", task_status: Optional[anyio.abc.TaskStatus] = None\n    ) -&gt; Union[BaseWorkerResult, Exception]:\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            configuration = await self._get_configuration(flow_run)\n            submitted_event = self._emit_flow_run_submitted_event(configuration)\n            result = await self.run(\n                flow_run=flow_run,\n                task_status=task_status,\n                configuration=configuration,\n            )\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                run_logger.exception(\n                    f\"Failed to submit flow run '{flow_run.id}' to infrastructure.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run could not be submitted to infrastructure\"\n                )\n            else:\n                run_logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            if self._limiter:\n                self._limiter.release_on_behalf_of(flow_run.id)\n\n        if not task_status._future.done():\n            run_logger.error(\n                f\"Infrastructure returned without reporting flow run '{flow_run.id}' \"\n                \"as started or raising an error. This behavior is not expected and \"\n                \"generally indicates improper implementation of infrastructure. The \"\n                \"flow run will not be marked as failed, but an issue may have occurred.\"\n            )\n            # Mark the task as started to prevent agent crash\n            task_status.started()\n\n        if result.status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                (\n                    \"Flow run infrastructure exited with non-zero status code\"\n                    f\" {result.status_code}.\"\n                ),\n            )\n\n        self._emit_flow_run_executed_event(result, configuration, submitted_event)\n\n        return result\n\n    def get_status(self):\n        \"\"\"\n        Retrieves the status of the current worker including its name, current worker\n        pool, the work pool queues it is polling, and its local settings.\n        \"\"\"\n        return {\n            \"name\": self.name,\n            \"work_pool\": (\n                self._work_pool.dict(json_compatible=True)\n                if self._work_pool is not None\n                else None\n            ),\n            \"settings\": {\n                \"prefetch_seconds\": self._prefetch_seconds,\n            },\n        }\n\n    async def _get_configuration(\n        self,\n        flow_run: \"FlowRun\",\n    ) -&gt; BaseJobConfiguration:\n        deployment = await self._client.read_deployment(flow_run.deployment_id)\n        flow = await self._client.read_flow(flow_run.flow_id)\n\n        deployment_vars = deployment.job_variables or {}\n        flow_run_vars = flow_run.job_variables or {}\n        job_variables = {**deployment_vars}\n\n        # merge environment variables carefully, otherwise full override\n        if isinstance(job_variables.get(\"env\"), dict):\n            job_variables[\"env\"].update(flow_run_vars.pop(\"env\", {}))\n        job_variables.update(flow_run_vars)\n\n        configuration = await self.job_configuration.from_template_and_values(\n            base_job_template=self._work_pool.base_job_template,\n            values=job_variables,\n            client=self._client,\n        )\n        configuration.prepare_for_flow_run(\n            flow_run=flow_run, deployment=deployment, flow=flow\n        )\n        return configuration\n\n    async def _propose_pending_state(self, flow_run: \"FlowRun\") -&gt; bool:\n        run_logger = self.get_flow_run_logger(flow_run)\n        state = flow_run.state\n        try:\n            state = await propose_state(\n                self._client, Pending(), flow_run_id=flow_run.id\n            )\n        except Abort as exc:\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            run_logger.exception(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n            )\n            return False\n\n        if not state.is_pending():\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: \"FlowRun\", exc: Exception) -&gt; None:\n        run_logger = self.get_flow_run_logger(flow_run)\n        try:\n            await propose_state(\n                self._client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            run_logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: \"FlowRun\", message: str) -&gt; None:\n        run_logger = self.get_flow_run_logger(flow_run)\n        try:\n            state = await propose_state(\n                self._client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            run_logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                run_logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: \"FlowRun\", state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self._client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self._cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def _set_work_pool_template(self, work_pool, job_template):\n        \"\"\"Updates the `base_job_template` for the worker's work pool server side.\"\"\"\n        await self._client.update_work_pool(\n            work_pool_name=work_pool.name,\n            work_pool=WorkPoolUpdate(\n                base_job_template=job_template,\n            ),\n        )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the worker exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.is_setup:\n                with anyio.CancelScope() as scope:\n                    self._scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self._scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self._runs_task_group.start(wrapper)\n\n    async def __aenter__(self):\n        self._logger.debug(\"Entering worker context...\")\n        await self.setup()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        self._logger.debug(\"Exiting worker context...\")\n        await self.teardown(*exc_info)\n\n    def __repr__(self):\n        return f\"Worker(pool={self._work_pool_name!r}, name={self.name!r})\"\n\n    def _event_resource(self):\n        return {\n            \"prefect.resource.id\": f\"prefect.worker.{self.type}.{self.get_name_slug()}\",\n            \"prefect.resource.name\": self.name,\n            \"prefect.version\": prefect.__version__,\n            \"prefect.worker-type\": self.type,\n        }\n\n    def _event_related_resources(\n        self,\n        configuration: Optional[BaseJobConfiguration] = None,\n        include_self: bool = False,\n    ) -&gt; List[RelatedResource]:\n        related = []\n        if configuration:\n            related += configuration._related_resources()\n\n        if self._work_pool:\n            related.append(\n                object_as_related_resource(\n                    kind=\"work-pool\", role=\"work-pool\", object=self._work_pool\n                )\n            )\n\n        if include_self:\n            worker_resource = self._event_resource()\n            worker_resource[\"prefect.resource.role\"] = \"worker\"\n            related.append(RelatedResource.parse_obj(worker_resource))\n\n        return related\n\n    def _emit_flow_run_submitted_event(\n        self, configuration: BaseJobConfiguration\n    ) -&gt; Event:\n        return emit_event(\n            event=\"prefect.worker.submitted-flow-run\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(configuration=configuration),\n        )\n\n    def _emit_flow_run_executed_event(\n        self,\n        result: BaseWorkerResult,\n        configuration: BaseJobConfiguration,\n        submitted_event: Event,\n    ):\n        related = self._event_related_resources(configuration=configuration)\n\n        for resource in related:\n            if resource.role == \"flow-run\":\n                resource[\"prefect.infrastructure.identifier\"] = str(result.identifier)\n                resource[\"prefect.infrastructure.status-code\"] = str(result.status_code)\n\n        emit_event(\n            event=\"prefect.worker.executed-flow-run\",\n            resource=self._event_resource(),\n            related=related,\n            follows=submitted_event,\n        )\n\n    async def _emit_worker_started_event(self) -&gt; Event:\n        return emit_event(\n            \"prefect.worker.started\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(),\n        )\n\n    async def _emit_worker_stopped_event(self, started_event: Event):\n        emit_event(\n            \"prefect.worker.stopped\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(),\n            follows=started_event,\n        )\n\n    def _emit_flow_run_cancelled_event(\n        self, flow_run: \"FlowRun\", configuration: BaseJobConfiguration\n    ):\n        related = self._event_related_resources(configuration=configuration)\n\n        for resource in related:\n            if resource.role == \"flow-run\":\n                resource[\"prefect.infrastructure.identifier\"] = str(\n                    flow_run.infrastructure_pid\n                )\n\n        emit_event(\n            event=\"prefect.worker.cancelled-flow-run\",\n            resource=self._event_resource(),\n            related=related,\n        )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_all_available_worker_types","title":"<code>get_all_available_worker_types</code>  <code>staticmethod</code>","text":"<p>Returns all worker types available in the local registry.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@staticmethod\ndef get_all_available_worker_types() -&gt; List[str]:\n    \"\"\"\n    Returns all worker types available in the local registry.\n    \"\"\"\n    load_prefect_collections()\n    worker_registry = get_registry_for_type(BaseWorker)\n    if worker_registry is not None:\n        return list(worker_registry.keys())\n    return []\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_status","title":"<code>get_status</code>","text":"<p>Retrieves the status of the current worker including its name, current worker pool, the work pool queues it is polling, and its local settings.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>def get_status(self):\n    \"\"\"\n    Retrieves the status of the current worker including its name, current worker\n    pool, the work pool queues it is polling, and its local settings.\n    \"\"\"\n    return {\n        \"name\": self.name,\n        \"work_pool\": (\n            self._work_pool.dict(json_compatible=True)\n            if self._work_pool is not None\n            else None\n        ),\n        \"settings\": {\n            \"prefetch_seconds\": self._prefetch_seconds,\n        },\n    }\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_worker_class_from_type","title":"<code>get_worker_class_from_type</code>  <code>staticmethod</code>","text":"<p>Returns the worker class for a given worker type. If the worker type is not recognized, returns None.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@staticmethod\ndef get_worker_class_from_type(type: str) -&gt; Optional[Type[\"BaseWorker\"]]:\n    \"\"\"\n    Returns the worker class for a given worker type. If the worker type\n    is not recognized, returns None.\n    \"\"\"\n    load_prefect_collections()\n    worker_registry = get_registry_for_type(BaseWorker)\n    if worker_registry is not None:\n        return worker_registry.get(type)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.is_worker_still_polling","title":"<code>is_worker_still_polling</code>","text":"<p>This method is invoked by a webserver healthcheck handler and returns a boolean indicating if the worker has recorded a scheduled flow run poll within a variable amount of time.</p> <p>The <code>query_interval_seconds</code> is the same value that is used by the loop services - we will evaluate if the _last_polled_time was within that interval x 30 (so 10s -&gt; 5m)</p> <p>The instance property <code>self._last_polled_time</code> is currently set/updated in <code>get_and_submit_flow_runs()</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>def is_worker_still_polling(self, query_interval_seconds: int) -&gt; bool:\n    \"\"\"\n    This method is invoked by a webserver healthcheck handler\n    and returns a boolean indicating if the worker has recorded a\n    scheduled flow run poll within a variable amount of time.\n\n    The `query_interval_seconds` is the same value that is used by\n    the loop services - we will evaluate if the _last_polled_time\n    was within that interval x 30 (so 10s -&gt; 5m)\n\n    The instance property `self._last_polled_time`\n    is currently set/updated in `get_and_submit_flow_runs()`\n    \"\"\"\n    threshold_seconds = query_interval_seconds * 30\n\n    seconds_since_last_poll = (\n        pendulum.now(\"utc\") - self._last_polled_time\n    ).in_seconds()\n\n    is_still_polling = seconds_since_last_poll &lt;= threshold_seconds\n\n    if not is_still_polling:\n        self._logger.error(\n            f\"Worker has not polled in the last {seconds_since_last_poll} seconds \"\n            \"and should be restarted\"\n        )\n\n    return is_still_polling\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Method for killing infrastructure created by a worker. Should be implemented by individual workers if they support killing infrastructure.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: BaseJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Method for killing infrastructure created by a worker. Should be implemented by\n    individual workers if they support killing infrastructure.\n    \"\"\"\n    raise NotImplementedError(\n        \"This worker does not support killing infrastructure.\"\n    )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.run","title":"<code>run</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Runs a given flow run on the current worker.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@abc.abstractmethod\nasync def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: BaseJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; BaseWorkerResult:\n    \"\"\"\n    Runs a given flow run on the current worker.\n    \"\"\"\n    raise NotImplementedError(\n        \"Workers must implement a method for running submitted flow runs\"\n    )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.setup","title":"<code>setup</code>  <code>async</code>","text":"<p>Prepares the worker to run.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def setup(self):\n    \"\"\"Prepares the worker to run.\"\"\"\n    self._logger.debug(\"Setting up worker...\")\n    self._runs_task_group = anyio.create_task_group()\n    self._limiter = (\n        anyio.CapacityLimiter(self._limit) if self._limit is not None else None\n    )\n    self._client = get_client()\n    await self._client.__aenter__()\n    await self._runs_task_group.__aenter__()\n\n    self.is_setup = True\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.sync_with_backend","title":"<code>sync_with_backend</code>  <code>async</code>","text":"<p>Updates the worker's local information about it's current work pool and queues. Sends a worker heartbeat to the API.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def sync_with_backend(self):\n    \"\"\"\n    Updates the worker's local information about it's current work pool and\n    queues. Sends a worker heartbeat to the API.\n    \"\"\"\n    await self._update_local_work_pool_info()\n\n    await self._send_worker_heartbeat()\n\n    self._logger.debug(\"Worker synchronized with the Prefect API server.\")\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.teardown","title":"<code>teardown</code>  <code>async</code>","text":"<p>Cleans up resources after the worker is stopped.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def teardown(self, *exc_info):\n    \"\"\"Cleans up resources after the worker is stopped.\"\"\"\n    self._logger.debug(\"Tearing down worker...\")\n    self.is_setup = False\n    for scope in self._scheduled_task_scopes:\n        scope.cancel()\n    if self._runs_task_group:\n        await self._runs_task_group.__aexit__(*exc_info)\n    if self._client:\n        await self._client.__aexit__(*exc_info)\n    self._runs_task_group = None\n    self._client = None\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/block/","title":"block","text":"","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block","title":"<code>prefect.workers.block</code>","text":"","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration","title":"<code>BlockWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/workers/block.py</code> <pre><code>@deprecated_class(\n    start_date=\"Jun 2024\",\n    help=\"Refer to the upgrade guide for more information: https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/\",\n)\nclass BlockWorkerJobConfiguration(BaseModel):\n    block: Block = Field(\n        default=..., description=\"The infrastructure block to use for job creation.\"\n    )\n\n    @validator(\"block\")\n    def _validate_infrastructure_block(cls, v):\n        return validate_block_is_infrastructure(v)\n\n    _related_objects: Dict[str, Any] = PrivateAttr(default_factory=dict)\n\n    @property\n    def is_using_a_runner(self):\n        return (\n            self.block.command is not None\n            and \"prefect flow-run execute\" in shlex.join(self.block.command)\n        )\n\n    @staticmethod\n    def _get_base_config_defaults(variables: dict) -&gt; dict:\n        \"\"\"Get default values from base config for all variables that have them.\"\"\"\n        defaults = dict()\n        for variable_name, attrs in variables.items():\n            if \"default\" in attrs:\n                defaults[variable_name] = attrs[\"default\"]\n\n        return defaults\n\n    @classmethod\n    @inject_client\n    async def from_template_and_values(\n        cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n    ):\n        \"\"\"Creates a valid worker configuration object from the provided base\n        configuration and overrides.\n\n        Important: this method expects that the base_job_template was already\n        validated server-side.\n        \"\"\"\n        job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n        variables_schema = base_job_template[\"variables\"]\n        variables = cls._get_base_config_defaults(\n            variables_schema.get(\"properties\", {})\n        )\n        variables.update(values)\n\n        populated_configuration = apply_values(template=job_config, values=variables)\n\n        block_document_id = get_from_dict(\n            populated_configuration, \"block.$ref.block_document_id\"\n        )\n        if not block_document_id:\n            raise ValueError(\n                \"Base job template is invalid for this worker type because it does not\"\n                \" contain a block_document_id after variable resolution.\"\n            )\n\n        block_document = await client.read_block_document(\n            block_document_id=block_document_id\n        )\n        infrastructure_block = Block._from_block_document(block_document)\n\n        populated_configuration[\"block\"] = infrastructure_block\n\n        return cls(**populated_configuration)\n\n    @classmethod\n    def json_template(cls) -&gt; dict:\n        \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n        Defaults to using the job configuration parameter name as the template variable name.\n\n        e.g.\n        {\n            key1: '{{ key1 }}',     # default variable template\n            key2: '{{ template2 }}', # `template2` specifically provide as template\n        }\n        \"\"\"\n        configuration = {}\n        properties = cls.schema()[\"properties\"]\n        for k, v in properties.items():\n            if v.get(\"template\"):\n                template = v[\"template\"]\n            else:\n                template = \"{{ \" + k + \" }}\"\n            configuration[k] = template\n\n        return configuration\n\n    def _related_resources(self) -&gt; List[RelatedResource]:\n        tags = set()\n        related = []\n\n        for kind, obj in self._related_objects.items():\n            if obj is None:\n                continue\n            if hasattr(obj, \"tags\"):\n                tags.update(obj.tags)\n            related.append(object_as_related_resource(kind=kind, role=kind, object=obj))\n\n        return related + tags_as_related_resources(tags)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        self.block = self.block.prepare_for_flow_run(\n            flow_run=flow_run, deployment=deployment, flow=flow\n        )\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration.from_template_and_values","title":"<code>from_template_and_values</code>  <code>async</code> <code>classmethod</code>","text":"<p>Creates a valid worker configuration object from the provided base configuration and overrides.</p> <p>Important: this method expects that the base_job_template was already validated server-side.</p> Source code in <code>prefect/workers/block.py</code> <pre><code>@classmethod\n@inject_client\nasync def from_template_and_values(\n    cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n):\n    \"\"\"Creates a valid worker configuration object from the provided base\n    configuration and overrides.\n\n    Important: this method expects that the base_job_template was already\n    validated server-side.\n    \"\"\"\n    job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n    variables_schema = base_job_template[\"variables\"]\n    variables = cls._get_base_config_defaults(\n        variables_schema.get(\"properties\", {})\n    )\n    variables.update(values)\n\n    populated_configuration = apply_values(template=job_config, values=variables)\n\n    block_document_id = get_from_dict(\n        populated_configuration, \"block.$ref.block_document_id\"\n    )\n    if not block_document_id:\n        raise ValueError(\n            \"Base job template is invalid for this worker type because it does not\"\n            \" contain a block_document_id after variable resolution.\"\n        )\n\n    block_document = await client.read_block_document(\n        block_document_id=block_document_id\n    )\n    infrastructure_block = Block._from_block_document(block_document)\n\n    populated_configuration[\"block\"] = infrastructure_block\n\n    return cls(**populated_configuration)\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration.json_template","title":"<code>json_template</code>  <code>classmethod</code>","text":"<p>Returns a dict with job configuration as keys and the corresponding templates as values</p> <p>Defaults to using the job configuration parameter name as the template variable name.</p> <p>e.g. {     key1: '{{ key1 }}',     # default variable template     key2: '{{ template2 }}', # <code>template2</code> specifically provide as template }</p> Source code in <code>prefect/workers/block.py</code> <pre><code>@classmethod\ndef json_template(cls) -&gt; dict:\n    \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n    Defaults to using the job configuration parameter name as the template variable name.\n\n    e.g.\n    {\n        key1: '{{ key1 }}',     # default variable template\n        key2: '{{ template2 }}', # `template2` specifically provide as template\n    }\n    \"\"\"\n    configuration = {}\n    properties = cls.schema()[\"properties\"]\n    for k, v in properties.items():\n        if v.get(\"template\"):\n            template = v[\"template\"]\n        else:\n            template = \"{{ \" + k + \" }}\"\n        configuration[k] = template\n\n    return configuration\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerResult","title":"<code>BlockWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Result of a block worker job</p> Source code in <code>prefect/workers/block.py</code> <pre><code>class BlockWorkerResult(BaseWorkerResult):\n    \"\"\"Result of a block worker job\"\"\"\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/process/","title":"process","text":"","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process","title":"<code>prefect.workers.process</code>","text":"<p>Module containing the Process worker used for executing flow runs as subprocesses.</p> <p>To start a Process worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type process\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process.ProcessJobConfiguration","title":"<code>ProcessJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> Source code in <code>prefect/workers/process.py</code> <pre><code>class ProcessJobConfiguration(BaseJobConfiguration):\n    stream_output: bool = Field(default=True)\n    working_dir: Optional[Path] = Field(default=None)\n\n    @validator(\"working_dir\")\n    def validate_command(cls, v):\n        return validate_command(v)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self.env = {**os.environ, **self.env}\n        self.command = (\n            f\"{get_sys_executable()} -m prefect.engine\"\n            if self.command == self._base_flow_run_command()\n            else self.command\n        )\n\n    def _base_flow_run_command(self) -&gt; str:\n        \"\"\"\n        Override the base flow run command because enhanced cancellation doesn't\n        work with the process worker.\n        \"\"\"\n        return \"python -m prefect.engine\"\n</code></pre>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process.ProcessWorkerResult","title":"<code>ProcessWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect/workers/process.py</code> <pre><code>class ProcessWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/server/","title":"server","text":"","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/server/#prefect.workers.server","title":"<code>prefect.workers.server</code>","text":"","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/server/#prefect.workers.server.start_healthcheck_server","title":"<code>start_healthcheck_server</code>","text":"<p>Run a healthcheck FastAPI server for a worker.</p> <p>Parameters:</p> Name Type Description Default <code>worker</code> <code>BaseWorker | ProcessWorker</code> <p>the worker whose health we will check</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> <code>'error'</code> Source code in <code>prefect/workers/server.py</code> <pre><code>def start_healthcheck_server(\n    worker: Union[BaseWorker, ProcessWorker],\n    query_interval_seconds: int,\n    log_level: str = \"error\",\n) -&gt; None:\n    \"\"\"\n    Run a healthcheck FastAPI server for a worker.\n\n    Args:\n        worker (BaseWorker | ProcessWorker): the worker whose health we will check\n        log_level (str): the log level to use for the server\n    \"\"\"\n    webserver = FastAPI()\n    router = APIRouter()\n\n    def perform_health_check():\n        did_recently_poll = worker.is_worker_still_polling(\n            query_interval_seconds=query_interval_seconds\n        )\n\n        if not did_recently_poll:\n            return JSONResponse(\n                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n                content={\"message\": \"Worker may be unresponsive at this time\"},\n            )\n        return JSONResponse(status_code=status.HTTP_200_OK, content={\"message\": \"OK\"})\n\n    router.add_api_route(\"/health\", perform_health_check, methods=[\"GET\"])\n\n    webserver.include_router(router)\n\n    uvicorn.run(\n        webserver,\n        host=PREFECT_WORKER_WEBSERVER_HOST.value(),\n        port=PREFECT_WORKER_WEBSERVER_PORT.value(),\n        log_level=log_level,\n    )\n</code></pre>","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/utilities/","title":"utilities","text":"","tags":["Python API","workers","utilities"]},{"location":"api-ref/prefect/workers/utilities/#prefect.workers.utilities","title":"<code>prefect.workers.utilities</code>","text":"","tags":["Python API","workers","utilities"]},{"location":"api-ref/python/","title":"Python SDK","text":"<p>The Prefect Python SDK is used to build, test, and execute workflows against the Prefect API.</p> <p>Explore the modules in the navigation bar to the left to learn more.</p>","tags":["API","Python SDK"]},{"location":"api-ref/rest-api/","title":"REST API","text":"<p>The Prefect REST API is used for communicating data from clients to a Prefect server so that orchestration can be performed. This API is consumed by clients such as the Prefect Python SDK or the server dashboard.</p> <p>Prefect Cloud and a locally hosted Prefect server each provide a REST API.</p> <ul> <li>Prefect Cloud:<ul> <li>Interactive Prefect Cloud REST API documentation</li> <li>Finding your Prefect Cloud details</li> </ul> </li> <li>A Locally hosted open-source Prefect server:<ul> <li>Interactive REST API documentation for a locally hosted open-source Prefect server is available at <code>http://localhost:4200/docs</code> or the <code>/docs</code> endpoint of the PREFECT_API_URL you have configured to access the server. You must have the server running with <code>prefect server start</code> to access the interactive documentation.</li> <li>Prefect REST API documentation</li> </ul> </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#interacting-with-the-rest-api","title":"Interacting with the REST API","text":"<p>You have many options to interact with the Prefect REST API:</p> <ul> <li>Create an instance of <code>PrefectClient</code> </li> <li>Use your favorite Python HTTP library such as Requests or HTTPX</li> <li>Use an HTTP library in your language of choice</li> <li>Use curl from the command line </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#prefectclient-with-a-prefect-server","title":"PrefectClient with a Prefect server","text":"<p>This example uses <code>PrefectClient</code> with a locally hosted Prefect server:</p> <pre><code>import asyncio\nfrom prefect.client import get_client\n\nasync def get_flows():\n    client = get_client()\n    r = await client.read_flows(limit=5)\n    return r\n\nr = asyncio.run(get_flows())\n\nfor flow in r:\n    print(flow.name, flow.id)\n\nif __name__ == \"__main__\":\n    asyncio.run(get_flows())\n</code></pre> <p>Output:</p> <pre><code>cat-facts 58ed68b1-0201-4f37-adef-0ea24bd2a022\ndog-facts e7c0403d-44e7-45cf-a6c8-79117b7f3766\nsloth-facts 771c0574-f5bf-4f59-a69d-3be3e061a62d\ncapybara-facts fbadaf8b-584f-48b9-b092-07d351edd424\nlemur-facts 53f710e7-3b0f-4b2f-ab6b-44934111818c\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#requests-with-prefect","title":"Requests with Prefect","text":"<p>This example uses the Requests library with Prefect Cloud to return the five newest artifacts.</p> <pre><code>import requests\n\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/abc-my-cloud-account-id-is-here/workspaces/123-my-workspace-id-is-here\"\nPREFECT_API_KEY=\"123abc_my_api_key_goes_here\"\ndata = {\n    \"sort\": \"CREATED_DESC\",\n    \"limit\": 5,\n    \"artifacts\": {\n        \"key\": {\n            \"exists_\": True\n        }\n    }\n}\n\nheaders = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\nendpoint = f\"{PREFECT_API_URL}/artifacts/filter\"\n\nresponse = requests.post(endpoint, headers=headers, json=data)\nassert response.status_code == 200\nfor artifact in response.json():\n    print(artifact)\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#curl-with-prefect-cloud","title":"curl with Prefect Cloud","text":"<p>This example uses curl with Prefect Cloud to create a flow run:</p> <pre><code>ACCOUNT_ID=\"abc-my-cloud-account-id-goes-here\"\nWORKSPACE_ID=\"123-my-workspace-id-goes-here\"\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/$ACCOUNT_ID/workspaces/$WORKSPACE_ID\"\nPREFECT_API_KEY=\"123abc_my_api_key_goes_here\"\nDEPLOYMENT_ID=\"my_deployment_id\"\n\ncurl --location --request POST \"$PREFECT_API_URL/deployments/$DEPLOYMENT_ID/create_flow_run\" \\\n  --header \"Content-Type: application/json\" \\\n  --header \"Authorization: Bearer $PREFECT_API_KEY\" \\\n  --header \"X-PREFECT-API-VERSION: 0.8.4\" \\\n  --data-raw \"{}\"\n</code></pre> <p>Note that in this example <code>--data-raw \"{}\"</code> is required and is where you can specify other aspects of the flow run such as the state. Windows users substitute <code>^</code> for <code>\\</code> for line multi-line commands.</p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#finding-your-prefect-cloud-details","title":"Finding your Prefect Cloud details","text":"<p>When working with the Prefect Cloud REST API you will need your Account ID and often the Workspace ID for the workspace you want to interact with. You can find both IDs for a Prefect profile in the CLI with <code>prefect profile inspect my_profile</code>. This command will also display your Prefect API key, as shown below:</p> <pre><code>PREFECT_API_URL='https://api.prefect.cloud/api/accounts/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here'\nPREFECT_API_KEY='123abc_my_api_key_is_here'\n</code></pre> <p>Alternatively, view your Account ID and Workspace ID in your browser URL. For example: <code>https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here</code>. </p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#rest-guidelines","title":"REST Guidelines","text":"<p>The REST APIs adhere to the following guidelines:</p> <ul> <li>Collection names are pluralized (for example, <code>/flows</code> or <code>/runs</code>).</li> <li>We indicate variable placeholders with colons: <code>GET /flows/:id</code>.</li> <li>We use snake case for route names: <code>GET /task_runs</code>.</li> <li>We avoid nested resources unless there is no possibility of accessing the child resource outside the parent context. For example, we query <code>/task_runs</code> with a flow run filter instead of accessing <code>/flow_runs/:id/task_runs</code>.</li> <li>The API is hosted with an <code>/api/:version</code> prefix that (optionally) allows versioning in the future. By convention, we treat that as part of the base URL and do not include that in API examples.</li> <li>Filtering, sorting, and pagination parameters are provided in the request body of <code>POST</code> requests where applicable.<ul> <li>Pagination parameters are <code>limit</code> and <code>offset</code>.</li> <li>Sorting is specified with a single <code>sort</code> parameter.</li> <li>See more information on filtering below.</li> </ul> </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#http-verbs","title":"HTTP verbs","text":"<ul> <li><code>GET</code>, <code>PUT</code> and <code>DELETE</code> requests are always idempotent. <code>POST</code> and <code>PATCH</code> are not guaranteed to be idempotent.</li> <li><code>GET</code> requests cannot receive information from the request body.</li> <li><code>POST</code> requests can receive information from the request body.</li> <li><code>POST /collection</code> creates a new member of the collection.</li> <li><code>GET /collection</code> lists all members of the collection.</li> <li><code>GET /collection/:id</code> gets a specific member of the collection by ID.</li> <li><code>DELETE /collection/:id</code> deletes a specific member of the collection.</li> <li><code>PUT /collection/:id</code> creates or replaces a specific member of the collection.</li> <li><code>PATCH /collection/:id</code> partially updates a specific member of the collection.</li> <li><code>POST /collection/action</code> is how we implement non-CRUD actions. For example, to set a flow run's state, we use <code>POST /flow_runs/:id/set_state</code>.</li> <li><code>POST /collection/action</code> may also be used for read-only queries. This is to allow us to send complex arguments as body arguments (which often cannot be done via <code>GET</code>). Examples include <code>POST /flow_runs/filter</code>, <code>POST /flow_runs/count</code>, and <code>POST /flow_runs/history</code>.</li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#filtering","title":"Filtering","text":"<p>Objects can be filtered by providing filter criteria in the body of a <code>POST</code> request. When multiple criteria are specified, logical AND will be applied to the criteria.</p> <p>Filter criteria are structured as follows:</p> <pre><code>{\n    \"objects\": {\n        \"object_field\": {\n            \"field_operator_\": &lt;field_value&gt;\n        }\n    }\n}\n</code></pre> <p>In this example, <code>objects</code> is the name of the collection to filter over (for example, <code>flows</code>). The collection can be either the object being queried for (<code>flows</code> for <code>POST /flows/filter</code>) or a related object (<code>flow_runs</code> for <code>POST /flows/filter</code>).</p> <p><code>object_field</code> is the name of the field over which to filter (<code>name</code> for <code>flows</code>). Note that some objects may have nested object fields, such as <code>{flow_run: {state: {type: {any_: []}}}}</code>.</p> <p><code>field_operator_</code> is the operator to apply to a field when filtering. Common examples include:</p> <ul> <li><code>any_</code>: return objects where this field matches any of the following values.</li> <li><code>is_null_</code>: return objects where this field is or is not null.</li> <li><code>eq_</code>: return objects where this field is equal to the following value.</li> <li><code>all_</code>: return objects where this field matches all of the following values.</li> <li><code>before_</code>: return objects where this datetime field is less than or equal to the following value.</li> <li><code>after_</code>: return objects where this datetime field is greater than or equal to the following value.</li> </ul> <p>For example, to query for flows with the tag <code>\"database\"</code> and failed flow runs, <code>POST /flows/filter</code> with the following request body:</p> <pre><code>{\n    \"flows\": {\n        \"tags\": {\n            \"all_\": [\"database\"]\n        }\n    },\n    \"flow_runs\": {\n        \"state\": {\n            \"type\": {\n              \"any_\": [\"FAILED\"]\n            }\n        }\n    }\n}\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#openapi","title":"OpenAPI","text":"<p>The Prefect REST API can be fully described with an OpenAPI 3.0 compliant document. OpenAPI is a standard specification for describing REST APIs.</p> <p>To generate the Prefect server's complete OpenAPI document, run the following commands in an interactive Python session:</p> <pre><code>from prefect.server.api.server import create_app\n\napp = create_app()\nopenapi_doc = app.openapi()\n</code></pre> <p>This document allows you to generate your own API client, explore the API using an API inspection tool, or write tests to ensure API compliance.</p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/server/","title":"Server API","text":"<p>The Prefect server API is used by the server to work with workflow metadata and enforce orchestration logic. This API is primarily used by Prefect developers.</p> <p>Select links in the left navigation menu to explore.</p>","tags":["API","Server API"]},{"location":"api-ref/server/api/admin/","title":"server.api.admin","text":"","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin","title":"<code>prefect.server.api.admin</code>","text":"<p>Routes for admin-level interactions with the Prefect REST API.</p>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.clear_database","title":"<code>clear_database</code>  <code>async</code>","text":"<p>Clear all database tables without dropping them.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/clear\", status_code=status.HTTP_204_NO_CONTENT)\nasync def clear_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Clear all database tables without dropping them.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n    async with db.session_context(begin_transaction=True) as session:\n        # work pool has a circular dependency on pool queue; delete it first\n        await session.execute(db.WorkPool.__table__.delete())\n        for table in reversed(db.Base.metadata.sorted_tables):\n            await session.execute(table.delete())\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.create_database","title":"<code>create_database</code>  <code>async</code>","text":"<p>Create all database objects.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/create\", status_code=status.HTTP_204_NO_CONTENT)\nasync def create_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Create all database objects.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n\n    await db.create_db()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.drop_database","title":"<code>drop_database</code>  <code>async</code>","text":"<p>Drop all database objects.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/drop\", status_code=status.HTTP_204_NO_CONTENT)\nasync def drop_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Drop all database objects.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n\n    await db.drop_db()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.read_settings","title":"<code>read_settings</code>  <code>async</code>","text":"<p>Get the current Prefect REST API settings.</p> <p>Secret setting values will be obfuscated.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.get(\"/settings\")\nasync def read_settings() -&gt; prefect.settings.Settings:\n    \"\"\"\n    Get the current Prefect REST API settings.\n\n    Secret setting values will be obfuscated.\n    \"\"\"\n    return prefect.settings.get_current_settings().with_obfuscated_secrets()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.read_version","title":"<code>read_version</code>  <code>async</code>","text":"<p>Returns the Prefect version number</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.get(\"/version\")\nasync def read_version() -&gt; str:\n    \"\"\"Returns the Prefect version number\"\"\"\n    return prefect.__version__\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/csrf_token/","title":"server.api.csrf_token","text":"","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/csrf_token/#prefect.server.api.csrf_token","title":"<code>prefect.server.api.csrf_token</code>","text":"","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/csrf_token/#prefect.server.api.csrf_token.create_csrf_token","title":"<code>create_csrf_token</code>  <code>async</code>","text":"<p>Create or update a CSRF token for a client</p> Source code in <code>prefect/server/api/csrf_token.py</code> <pre><code>@router.get(\"\")\nasync def create_csrf_token(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    client: str = Query(..., description=\"The client to create a CSRF token for\"),\n) -&gt; schemas.core.CsrfToken:\n    \"\"\"Create or update a CSRF token for a client\"\"\"\n    if PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value() is False:\n        raise HTTPException(\n            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"CSRF protection is disabled.\",\n        )\n\n    async with db.session_context(begin_transaction=True) as session:\n        token = await models.csrf_token.create_or_update_csrf_token(\n            session=session, client=client\n        )\n        await models.csrf_token.delete_expired_tokens(session=session)\n\n    return token\n</code></pre>","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/dependencies/","title":"server.api.dependencies","text":"","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies","title":"<code>prefect.server.api.dependencies</code>","text":"<p>Utilities for injecting FastAPI dependencies.</p>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.EnforceMinimumAPIVersion","title":"<code>EnforceMinimumAPIVersion</code>","text":"<p>FastAPI Dependency used to check compatibility between the version of the api and a given request.</p> <p>Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it to the api's version. Rejects requests that are lower than the minimum version.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>class EnforceMinimumAPIVersion:\n    \"\"\"\n    FastAPI Dependency used to check compatibility between the version of the api\n    and a given request.\n\n    Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it\n    to the api's version. Rejects requests that are lower than the minimum version.\n    \"\"\"\n\n    def __init__(self, minimum_api_version: str, logger: logging.Logger):\n        self.minimum_api_version = minimum_api_version\n        versions = [int(v) for v in minimum_api_version.split(\".\")]\n        self.api_major = versions[0]\n        self.api_minor = versions[1]\n        self.api_patch = versions[2]\n        self.logger = logger\n\n    async def __call__(\n        self,\n        x_prefect_api_version: str = Header(None),\n    ):\n        request_version = x_prefect_api_version\n\n        # if no version header, assume latest and continue\n        if not request_version:\n            return\n\n        # parse version\n        try:\n            major, minor, patch = [int(v) for v in request_version.split(\".\")]\n        except ValueError:\n            await self._notify_of_invalid_value(request_version)\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=(\n                    \"Invalid X-PREFECT-API-VERSION header format.\"\n                    f\"Expected header in format 'x.y.z' but received {request_version}\"\n                ),\n            )\n\n        if (major, minor, patch) &lt; (self.api_major, self.api_minor, self.api_patch):\n            await self._notify_of_outdated_version(request_version)\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=(\n                    f\"The request specified API version {request_version} but this \"\n                    f\"server requires version {self.minimum_api_version} or higher.\"\n                ),\n            )\n\n    async def _notify_of_invalid_value(self, request_version: str):\n        self.logger.error(\n            f\"Invalid X-PREFECT-API-VERSION header format: '{request_version}'\"\n        )\n\n    async def _notify_of_outdated_version(self, request_version: str):\n        self.logger.error(\n            f\"X-PREFECT-API-VERSION header specifies version '{request_version}' \"\n            f\"but minimum allowed version is '{self.minimum_api_version}'\"\n        )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.LimitBody","title":"<code>LimitBody</code>","text":"<p>A <code>fastapi.Depends</code> factory for pulling a <code>limit: int</code> parameter from the request body while determining the default from the current settings.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def LimitBody() -&gt; Depends:\n    \"\"\"\n    A `fastapi.Depends` factory for pulling a `limit: int` parameter from the\n    request body while determining the default from the current settings.\n    \"\"\"\n\n    def get_limit(\n        limit: int = Body(\n            None,\n            description=\"Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.\",\n        ),\n    ):\n        default_limit = PREFECT_API_DEFAULT_LIMIT.value()\n        limit = limit if limit is not None else default_limit\n        if not limit &gt;= 0:\n            raise HTTPException(\n                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                detail=\"Invalid limit: must be greater than or equal to 0.\",\n            )\n        if limit &gt; default_limit:\n            raise HTTPException(\n                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                detail=f\"Invalid limit: must be less than or equal to {default_limit}.\",\n            )\n        return limit\n\n    return Depends(get_limit)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.get_created_by","title":"<code>get_created_by</code>","text":"<p>A dependency that returns the provenance information to use when creating objects during this API call.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def get_created_by(\n    prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False),\n    prefect_automation_name: Optional[str] = Header(None, include_in_schema=False),\n) -&gt; Optional[schemas.core.CreatedBy]:\n    \"\"\"A dependency that returns the provenance information to use when creating objects\n    during this API call.\"\"\"\n    if prefect_automation_id and prefect_automation_name:\n        try:\n            display_value = b64decode(prefect_automation_name.encode()).decode()\n        except Exception:\n            display_value = None\n\n        if display_value:\n            return schemas.core.CreatedBy(\n                id=prefect_automation_id,\n                type=\"AUTOMATION\",\n                display_value=display_value,\n            )\n\n    return None\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.get_updated_by","title":"<code>get_updated_by</code>","text":"<p>A dependency that returns the provenance information to use when updating objects during this API call.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def get_updated_by(\n    prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False),\n    prefect_automation_name: Optional[str] = Header(None, include_in_schema=False),\n) -&gt; Optional[schemas.core.UpdatedBy]:\n    \"\"\"A dependency that returns the provenance information to use when updating objects\n    during this API call.\"\"\"\n    if prefect_automation_id and prefect_automation_name:\n        return schemas.core.UpdatedBy(\n            id=prefect_automation_id,\n            type=\"AUTOMATION\",\n            display_value=prefect_automation_name,\n        )\n\n    return None\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.is_ephemeral_request","title":"<code>is_ephemeral_request</code>","text":"<p>A dependency that returns whether the request is to an ephemeral server.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def is_ephemeral_request(request: Request):\n    \"\"\"\n    A dependency that returns whether the request is to an ephemeral server.\n    \"\"\"\n    return \"ephemeral-prefect\" in str(request.base_url)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/deployments/","title":"server.api.deployments","text":"","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments","title":"<code>prefect.server.api.deployments</code>","text":"<p>Routes for interacting with Deployment objects.</p>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.count_deployments","title":"<code>count_deployments</code>  <code>async</code>","text":"<p>Count deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/count\")\nasync def count_deployments(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Count deployments.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.deployments.count_deployments(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Gracefully creates a new deployment from the provided schema. If a deployment with the same name and flow_id already exists, the deployment is updated.</p> <p>If the deployment has an active schedule, flow runs will be scheduled. When upserting, any scheduled runs from the existing deployment will be deleted.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/\")\nasync def create_deployment(\n    deployment: schemas.actions.DeploymentCreate,\n    response: Response,\n    worker_lookups: WorkerLookups = Depends(WorkerLookups),\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    updated_by: Optional[schemas.core.UpdatedBy] = Depends(dependencies.get_updated_by),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Gracefully creates a new deployment from the provided schema. If a deployment with\n    the same name and flow_id already exists, the deployment is updated.\n\n    If the deployment has an active schedule, flow runs will be scheduled.\n    When upserting, any scheduled runs from the existing deployment will be deleted.\n    \"\"\"\n\n    data = deployment.dict(exclude_unset=True)\n    data[\"created_by\"] = created_by.dict() if created_by else None\n    data[\"updated_by\"] = updated_by.dict() if created_by else None\n\n    async with db.session_context(begin_transaction=True) as session:\n        if (\n            deployment.work_pool_name\n            and deployment.work_pool_name != DEFAULT_AGENT_WORK_POOL_NAME\n        ):\n            # Make sure that deployment is valid before beginning creation process\n            work_pool = await models.workers.read_work_pool_by_name(\n                session=session, work_pool_name=deployment.work_pool_name\n            )\n            if work_pool is None:\n                raise HTTPException(\n                    status_code=status.HTTP_404_NOT_FOUND,\n                    detail=f'Work pool \"{deployment.work_pool_name}\" not found.',\n                )\n\n            await validate_job_variables_for_deployment(\n                session,\n                work_pool,\n                deployment,\n            )\n\n        # hydrate the input model into a full model\n        deployment_dict = deployment.dict(exclude={\"work_pool_name\"})\n        if deployment.work_pool_name and deployment.work_queue_name:\n            # If a specific pool name/queue name combination was provided, get the\n            # ID for that work pool queue.\n            deployment_dict[\n                \"work_queue_id\"\n            ] = await worker_lookups._get_work_queue_id_from_name(\n                session=session,\n                work_pool_name=deployment.work_pool_name,\n                work_queue_name=deployment.work_queue_name,\n                create_queue_if_not_found=True,\n            )\n        elif deployment.work_pool_name:\n            # If just a pool name was provided, get the ID for its default\n            # work pool queue.\n            deployment_dict[\n                \"work_queue_id\"\n            ] = await worker_lookups._get_default_work_queue_id_from_work_pool_name(\n                session=session,\n                work_pool_name=deployment.work_pool_name,\n            )\n        elif deployment.work_queue_name:\n            # If just a queue name was provided, ensure that the queue exists and\n            # get its ID.\n            work_queue = await models.work_queues.ensure_work_queue_exists(\n                session=session, name=deployment.work_queue_name\n            )\n            deployment_dict[\"work_queue_id\"] = work_queue.id\n\n        deployment = schemas.core.Deployment(**deployment_dict)\n        # check to see if relevant blocks exist, allowing us throw a useful error message\n        # for debugging\n        if deployment.infrastructure_document_id is not None:\n            infrastructure_block = (\n                await models.block_documents.read_block_document_by_id(\n                    session=session,\n                    block_document_id=deployment.infrastructure_document_id,\n                )\n            )\n            if not infrastructure_block:\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error creating deployment. Could not find infrastructure\"\n                        f\" block with id: {deployment.infrastructure_document_id}. This\"\n                        \" usually occurs when applying a deployment specification that\"\n                        \" was built against a different Prefect database / workspace.\"\n                    ),\n                )\n\n        if deployment.storage_document_id is not None:\n            storage_block = await models.block_documents.read_block_document_by_id(\n                session=session,\n                block_document_id=deployment.storage_document_id,\n            )\n            if not storage_block:\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error creating deployment. Could not find storage block with\"\n                        f\" id: {deployment.storage_document_id}. This usually occurs\"\n                        \" when applying a deployment specification that was built\"\n                        \" against a different Prefect database / workspace.\"\n                    ),\n                )\n\n        # Ensure that `paused` and `is_schedule_active` are consistent.\n        if \"paused\" in data:\n            deployment.is_schedule_active = not data[\"paused\"]\n        elif \"is_schedule_active\" in data:\n            deployment.paused = not data[\"is_schedule_active\"]\n\n        now = pendulum.now(\"UTC\")\n        model = await models.deployments.create_deployment(\n            session=session, deployment=deployment\n        )\n\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n\n        return schemas.responses.DeploymentResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.create_flow_run_from_deployment","title":"<code>create_flow_run_from_deployment</code>  <code>async</code>","text":"<p>Create a flow run from a deployment.</p> <p>Any parameters not provided will be inferred from the deployment's parameters. If tags are not provided, the deployment's tags will be used.</p> <p>If no state is provided, the flow run will be created in a SCHEDULED state.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id}/create_flow_run\")\nasync def create_flow_run_from_deployment(\n    flow_run: schemas.actions.DeploymentFlowRunCreate,\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    worker_lookups: WorkerLookups = Depends(WorkerLookups),\n    response: Response = None,\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Create a flow run from a deployment.\n\n    Any parameters not provided will be inferred from the deployment's parameters.\n    If tags are not provided, the deployment's tags will be used.\n\n    If no state is provided, the flow run will be created in a SCHEDULED state.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        # get relevant info from the deployment\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n\n        try:\n            dehydrated_params = deployment.parameters\n            dehydrated_params.update(flow_run.parameters or {})\n            ctx = await HydrationContext.build(\n                session=session,\n                raise_on_error=True,\n                render_jinja=True,\n                render_workspace_variables=True,\n            )\n            parameters = hydrate(dehydrated_params, ctx)\n        except HydrationError as exc:\n            raise HTTPException(\n                status.HTTP_400_BAD_REQUEST,\n                detail=f\"Error hydrating flow run parameters: {exc}\",\n            )\n\n        # default\n        enforce_parameter_schema = deployment.enforce_parameter_schema\n\n        # run override\n        if flow_run.enforce_parameter_schema is not None:\n            enforce_parameter_schema = flow_run.enforce_parameter_schema\n\n        if enforce_parameter_schema:\n            if not isinstance(deployment.parameter_openapi_schema, dict):\n                raise HTTPException(\n                    status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error updating deployment: Cannot update parameters because\"\n                        \" parameter schema enforcement is enabled and the deployment\"\n                        \" does not have a valid parameter schema.\"\n                    ),\n                )\n            try:\n                validate(\n                    parameters, deployment.parameter_openapi_schema, raise_on_error=True\n                )\n            except ValidationError as exc:\n                raise HTTPException(\n                    status.HTTP_409_CONFLICT,\n                    detail=f\"Error creating flow run: {exc}\",\n                )\n            except CircularSchemaRefError:\n                raise HTTPException(\n                    status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                    detail=\"Invalid schema: Unable to validate schema with circular references.\",\n                )\n\n        await validate_job_variables_for_deployment_flow_run(\n            session, deployment, flow_run\n        )\n\n        work_queue_name = deployment.work_queue_name\n        work_queue_id = deployment.work_queue_id\n\n        if flow_run.work_queue_name:\n            # can't mutate the ORM model or else it will commit the changes back\n            work_queue_id = await worker_lookups._get_work_queue_id_from_name(\n                session=session,\n                work_pool_name=deployment.work_queue.work_pool.name,\n                work_queue_name=flow_run.work_queue_name,\n                create_queue_if_not_found=True,\n            )\n            work_queue_name = flow_run.work_queue_name\n\n        # hydrate the input model into a full flow run / state model\n        flow_run = schemas.core.FlowRun(\n            **flow_run.dict(\n                exclude={\n                    \"parameters\",\n                    \"tags\",\n                    \"infrastructure_document_id\",\n                    \"work_queue_name\",\n                    \"enforce_parameter_schema\",\n                }\n            ),\n            flow_id=deployment.flow_id,\n            deployment_id=deployment.id,\n            deployment_version=deployment.version,\n            parameters=parameters,\n            tags=set(deployment.tags).union(flow_run.tags),\n            infrastructure_document_id=(\n                flow_run.infrastructure_document_id\n                or deployment.infrastructure_document_id\n            ),\n            work_queue_name=work_queue_name,\n            work_queue_id=work_queue_id,\n            created_by=created_by,\n        )\n\n        if not flow_run.state:\n            flow_run.state = schemas.states.Scheduled()\n\n        now = pendulum.now(\"UTC\")\n        model = await models.flow_runs.create_flow_run(\n            session=session, flow_run=flow_run\n        )\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n        return schemas.responses.FlowRunResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete a deployment by id.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a deployment by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.deployments.delete_deployment(\n            session=session, deployment_id=deployment_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.get_scheduled_flow_runs_for_deployments","title":"<code>get_scheduled_flow_runs_for_deployments</code>  <code>async</code>","text":"<p>Get scheduled runs for a set of deployments. Used by a runner to poll for work.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/get_scheduled_flow_runs\")\nasync def get_scheduled_flow_runs_for_deployments(\n    background_tasks: BackgroundTasks,\n    deployment_ids: List[UUID] = Body(\n        default=..., description=\"The deployment IDs to get scheduled runs for\"\n    ),\n    scheduled_before: DateTimeTZ = Body(\n        None, description=\"The maximum time to look for scheduled flow runs\"\n    ),\n    limit: int = dependencies.LimitBody(),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.FlowRunResponse]:\n    \"\"\"\n    Get scheduled runs for a set of deployments. Used by a runner to poll for work.\n    \"\"\"\n    async with db.session_context() as session:\n        orm_flow_runs = await models.flow_runs.read_flow_runs(\n            session=session,\n            limit=limit,\n            deployment_filter=schemas.filters.DeploymentFilter(\n                id=schemas.filters.DeploymentFilterId(any_=deployment_ids),\n            ),\n            flow_run_filter=schemas.filters.FlowRunFilter(\n                next_scheduled_start_time=schemas.filters.FlowRunFilterNextScheduledStartTime(\n                    before_=scheduled_before\n                ),\n                state=schemas.filters.FlowRunFilterState(\n                    type=schemas.filters.FlowRunFilterStateType(\n                        any_=[schemas.states.StateType.SCHEDULED]\n                    )\n                ),\n            ),\n            sort=schemas.sorting.FlowRunSort.NEXT_SCHEDULED_START_TIME_ASC,\n        )\n\n        flow_run_responses = [\n            schemas.responses.FlowRunResponse.from_orm(orm_flow_run=orm_flow_run)\n            for orm_flow_run in orm_flow_runs\n        ]\n\n    background_tasks.add_task(\n        mark_deployments_ready,\n        deployment_ids=deployment_ids,\n    )\n\n    return flow_run_responses\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.pause_deployment","title":"<code>pause_deployment</code>  <code>async</code>","text":"<p>Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled state will be deleted.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id:uuid}/set_schedule_inactive\")  # Legacy route\n@router.post(\"/{id:uuid}/pause_deployment\")\nasync def pause_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled\n    state will be deleted.\n    \"\"\"\n    async with db.session_context(begin_transaction=False) as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        deployment.is_schedule_active = False\n        deployment.paused = True\n\n        # Ensure that we're updating the replicated schedule's `active` field,\n        # if there is only a single schedule. This is support for legacy\n        # clients.\n\n        number_of_schedules = len(deployment.schedules)\n\n        if number_of_schedules == 1:\n            deployment.schedules[0].active = False\n        elif number_of_schedules &gt; 1:\n            raise _multiple_schedules_error(deployment_id)\n\n        # commit here to make the inactive schedule \"visible\" to the scheduler service\n        await session.commit()\n\n        # delete any auto scheduled runs\n        await models.deployments._delete_scheduled_runs(\n            session=session,\n            deployment_id=deployment_id,\n            auto_scheduled_only=True,\n        )\n\n        await session.commit()\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Get a deployment by id.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Get a deployment by id.\n    \"\"\"\n    async with db.session_context() as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        return schemas.responses.DeploymentResponse.from_orm(deployment)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Get a deployment using the name of the flow and the deployment.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/name/{flow_name}/{deployment_name}\")\nasync def read_deployment_by_name(\n    flow_name: str = Path(..., description=\"The name of the flow\"),\n    deployment_name: str = Path(..., description=\"The name of the deployment\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Get a deployment using the name of the flow and the deployment.\n    \"\"\"\n    async with db.session_context() as session:\n        deployment = await models.deployments.read_deployment_by_name(\n            session=session, name=deployment_name, flow_name=flow_name\n        )\n        if not deployment:\n            raise HTTPException(\n                status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        return schemas.responses.DeploymentResponse.from_orm(deployment)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Query for deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_deployments(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    sort: schemas.sorting.DeploymentSort = Body(\n        schemas.sorting.DeploymentSort.NAME_ASC\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.DeploymentResponse]:\n    \"\"\"\n    Query for deployments.\n    \"\"\"\n    async with db.session_context() as session:\n        response = await models.deployments.read_deployments(\n            session=session,\n            offset=offset,\n            sort=sort,\n            limit=limit,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n        return [\n            schemas.responses.DeploymentResponse.from_orm(orm_deployment=deployment)\n            for deployment in response\n        ]\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.resume_deployment","title":"<code>resume_deployment</code>  <code>async</code>","text":"<p>Set a deployment schedule to active. Runs will be scheduled immediately.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id:uuid}/set_schedule_active\")  # Legacy route\n@router.post(\"/{id:uuid}/resume_deployment\")\nasync def resume_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Set a deployment schedule to active. Runs will be scheduled immediately.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        deployment.is_schedule_active = True\n        deployment.paused = False\n\n        # Ensure that we're updating the replicated schedule's `active` field,\n        # if there is only a single schedule. This is support for legacy\n        # clients.\n\n        number_of_schedules = len(deployment.schedules)\n\n        if number_of_schedules == 1:\n            deployment.schedules[0].active = True\n        elif number_of_schedules &gt; 1:\n            raise _multiple_schedules_error(deployment_id)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.schedule_deployment","title":"<code>schedule_deployment</code>  <code>async</code>","text":"<p>Schedule runs for a deployment. For backfills, provide start/end times in the past.</p> <p>This function will generate the minimum number of runs that satisfy the min and max times, and the min and max counts. Specifically, the following order will be respected.</p> <pre><code>- Runs will be generated starting on or after the `start_time`\n- No more than `max_runs` runs will be generated\n- No runs will be generated after `end_time` is reached\n- At least `min_runs` runs will be generated\n- Runs will be generated until at least `start_time + min_time` is reached\n</code></pre> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id}/schedule\")\nasync def schedule_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    start_time: DateTimeTZ = Body(None, description=\"The earliest date to schedule\"),\n    end_time: DateTimeTZ = Body(None, description=\"The latest date to schedule\"),\n    min_time: datetime.timedelta = Body(\n        None,\n        description=(\n            \"Runs will be scheduled until at least this long after the `start_time`\"\n        ),\n    ),\n    min_runs: int = Body(None, description=\"The minimum number of runs to schedule\"),\n    max_runs: int = Body(None, description=\"The maximum number of runs to schedule\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Schedule runs for a deployment. For backfills, provide start/end times in the past.\n\n    This function will generate the minimum number of runs that satisfy the min\n    and max times, and the min and max counts. Specifically, the following order\n    will be respected.\n\n        - Runs will be generated starting on or after the `start_time`\n        - No more than `max_runs` runs will be generated\n        - No runs will be generated after `end_time` is reached\n        - At least `min_runs` runs will be generated\n        - Runs will be generated until at least `start_time + min_time` is reached\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        await models.deployments.schedule_runs(\n            session=session,\n            deployment_id=deployment_id,\n            start_time=start_time,\n            min_time=min_time,\n            end_time=end_time,\n            min_runs=min_runs,\n            max_runs=max_runs,\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.work_queue_check_for_deployment","title":"<code>work_queue_check_for_deployment</code>  <code>async</code>","text":"<p>Get list of work-queues that are able to pick up the specified deployment.</p> <p>This endpoint is intended to be used by the UI to provide users warnings about deployments that are unable to be executed because there are no work queues that will pick up their runs, based on existing filter criteria. It may be deprecated in the future because there is not a strict relationship between work queues and deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/{id}/work_queue_check\", deprecated=True)\nasync def work_queue_check_for_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.WorkQueue]:\n    \"\"\"\n    Get list of work-queues that are able to pick up the specified deployment.\n\n    This endpoint is intended to be used by the UI to provide users warnings\n    about deployments that are unable to be executed because there are no work\n    queues that will pick up their runs, based on existing filter criteria. It\n    may be deprecated in the future because there is not a strict relationship\n    between work queues and deployments.\n    \"\"\"\n    try:\n        async with db.session_context() as session:\n            work_queues = await models.deployments.check_work_queues_for_deployment(\n                session=session, deployment_id=deployment_id\n            )\n    except ObjectNotFoundError:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n        )\n    return work_queues\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/flow_run_states/","title":"server.api.flow_run_states","text":"","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states","title":"<code>prefect.server.api.flow_run_states</code>","text":"<p>Routes for interacting with flow run state objects.</p>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states.read_flow_run_state","title":"<code>read_flow_run_state</code>  <code>async</code>","text":"<p>Get a flow run state by id.</p> Source code in <code>prefect/server/api/flow_run_states.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow_run_state(\n    flow_run_state_id: UUID = Path(\n        ..., description=\"The flow run state id\", alias=\"id\"\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.states.State:\n    \"\"\"\n    Get a flow run state by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow_run_state = await models.flow_run_states.read_flow_run_state(\n            session=session, flow_run_state_id=flow_run_state_id\n        )\n    if not flow_run_state:\n        raise HTTPException(\n            status.HTTP_404_NOT_FOUND, detail=\"Flow run state not found\"\n        )\n    return flow_run_state\n</code></pre>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Get states associated with a flow run.</p> Source code in <code>prefect/server/api/flow_run_states.py</code> <pre><code>@router.get(\"/\")\nasync def read_flow_run_states(\n    flow_run_id: UUID,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.states.State]:\n    \"\"\"\n    Get states associated with a flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_run_states.read_flow_run_states(\n            session=session, flow_run_id=flow_run_id\n        )\n</code></pre>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_runs/","title":"server.api.flow_runs","text":"","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs","title":"<code>prefect.server.api.flow_runs</code>","text":"<p>Routes for interacting with flow run objects.</p>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.average_flow_run_lateness","title":"<code>average_flow_run_lateness</code>  <code>async</code>","text":"<p>Query for average flow-run lateness in seconds.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/lateness\")\nasync def average_flow_run_lateness(\n    flows: Optional[schemas.filters.FlowFilter] = None,\n    flow_runs: Optional[schemas.filters.FlowRunFilter] = None,\n    task_runs: Optional[schemas.filters.TaskRunFilter] = None,\n    deployments: Optional[schemas.filters.DeploymentFilter] = None,\n    work_pools: Optional[schemas.filters.WorkPoolFilter] = None,\n    work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; Optional[float]:\n    \"\"\"\n    Query for average flow-run lateness in seconds.\n    \"\"\"\n    async with db.session_context() as session:\n        if db.dialect.name == \"sqlite\":\n            # Since we want an _average_ of the lateness we're unable to use\n            # the existing FlowRun.expected_start_time_delta property as it\n            # returns a timedelta and SQLite is unable to properly deal with it\n            # and always returns 1970.0 as the average. This copies the same\n            # logic but ensures that it returns the number of seconds instead\n            # so it's compatible with SQLite.\n            base_query = sa.case(\n                (\n                    db.FlowRun.start_time &gt; db.FlowRun.expected_start_time,\n                    sa.func.strftime(\"%s\", db.FlowRun.start_time)\n                    - sa.func.strftime(\"%s\", db.FlowRun.expected_start_time),\n                ),\n                (\n                    db.FlowRun.start_time.is_(None)\n                    &amp; db.FlowRun.state_type.notin_(schemas.states.TERMINAL_STATES)\n                    &amp; (db.FlowRun.expected_start_time &lt; sa.func.datetime(\"now\")),\n                    sa.func.strftime(\"%s\", sa.func.datetime(\"now\"))\n                    - sa.func.strftime(\"%s\", db.FlowRun.expected_start_time),\n                ),\n                else_=0,\n            )\n        else:\n            base_query = db.FlowRun.estimated_start_time_delta\n\n        query = await models.flow_runs._apply_flow_run_filters(\n            sa.select(sa.func.avg(base_query)),\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n        result = await session.execute(query)\n\n        avg_lateness = result.scalar()\n\n        if avg_lateness is None:\n            return None\n        elif isinstance(avg_lateness, datetime.timedelta):\n            return avg_lateness.total_seconds()\n        else:\n            return avg_lateness\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.count_flow_runs","title":"<code>count_flow_runs</code>  <code>async</code>","text":"<p>Query for flow runs.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/count\")\nasync def count_flow_runs(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Query for flow runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_runs.count_flow_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Create a flow run. If a flow run with the same flow_id and idempotency key already exists, the existing flow run will be returned.</p> <p>If no state is provided, the flow run will be created in a PENDING state.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/\")\nasync def create_flow_run(\n    flow_run: schemas.actions.FlowRunCreate,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Create a flow run. If a flow run with the same flow_id and\n    idempotency key already exists, the existing flow run will be returned.\n\n    If no state is provided, the flow run will be created in a PENDING state.\n    \"\"\"\n    # hydrate the input model into a full flow run / state model\n    flow_run = schemas.core.FlowRun(**flow_run.dict(), created_by=created_by)\n\n    # pass the request version to the orchestration engine to support compatibility code\n    orchestration_parameters.update({\"api-version\": api_version})\n\n    if not flow_run.state:\n        flow_run.state = schemas.states.Pending()\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.flow_runs.create_flow_run(\n            session=session,\n            flow_run=flow_run,\n            orchestration_parameters=orchestration_parameters,\n        )\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n\n        return schemas.responses.FlowRunResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Create a key/value input for a flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/input\", status_code=status.HTTP_201_CREATED)\nasync def create_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Body(..., description=\"The input key\"),\n    value: bytes = Body(..., description=\"The value of the input\"),\n    sender: Optional[str] = Body(None, description=\"The sender of the input\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Create a key/value input for a flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        try:\n            await models.flow_run_input.create_flow_run_input(\n                session=session,\n                flow_run_input=schemas.core.FlowRunInput(\n                    flow_run_id=flow_run_id,\n                    key=key,\n                    sender=sender,\n                    value=value.decode(),\n                ),\n            )\n            await session.commit()\n\n        except IntegrityError as exc:\n            if \"unique constraint\" in str(exc).lower():\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=\"A flow run input with this key already exists.\",\n                )\n            else:\n                raise HTTPException(\n                    status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n                )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by id.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow run by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flow_runs.delete_flow_run(\n            session=session, flow_run_id=flow_run_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Delete a flow run input</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.delete(\"/{id}/input/{key}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Path(..., description=\"The input key\", alias=\"key\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow run input\n    \"\"\"\n\n    async with db.session_context() as session:\n        deleted = await models.flow_run_input.delete_flow_run_input(\n            session=session, flow_run_id=flow_run_id, key=key\n        )\n        await session.commit()\n\n        if not deleted:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run input not found\"\n            )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.filter_flow_run_input","title":"<code>filter_flow_run_input</code>  <code>async</code>","text":"<p>Filter flow run inputs by key prefix</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/input/filter\")\nasync def filter_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    prefix: str = Body(..., description=\"The input key prefix\", embed=True),\n    limit: int = Body(\n        1, description=\"The maximum number of results to return\", embed=True\n    ),\n    exclude_keys: List[str] = Body(\n        [], description=\"Exclude inputs with these keys\", embed=True\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.FlowRunInput]:\n    \"\"\"\n    Filter flow run inputs by key prefix\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_run_input.filter_flow_run_input(\n            session=session,\n            flow_run_id=flow_run_id,\n            prefix=prefix,\n            limit=limit,\n            exclude_keys=exclude_keys,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.flow_run_history","title":"<code>flow_run_history</code>  <code>async</code>","text":"<p>Query for flow run history data across a given range and interval.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/history\")\nasync def flow_run_history(\n    history_start: DateTimeTZ = Body(..., description=\"The history's start time.\"),\n    history_end: DateTimeTZ = Body(..., description=\"The history's end time.\"),\n    history_interval: datetime.timedelta = Body(\n        ...,\n        description=(\n            \"The size of each history interval, in seconds. Must be at least 1 second.\"\n        ),\n        alias=\"history_interval_seconds\",\n    ),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Query for flow run history data across a given range and interval.\n    \"\"\"\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise HTTPException(\n            status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"History interval must not be less than 1 second.\",\n        )\n\n    async with db.session_context() as session:\n        return await run_history(\n            session=session,\n            run_type=\"flow_run\",\n            history_start=history_start,\n            history_end=history_end,\n            history_interval=history_interval,\n            flows=flows,\n            flow_runs=flow_runs,\n            task_runs=task_runs,\n            deployments=deployments,\n            work_pools=work_pools,\n            work_queues=work_queues,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Get a flow run by id.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Get a flow run by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow_run = await models.flow_runs.read_flow_run(\n            session=session, flow_run_id=flow_run_id\n        )\n        if not flow_run:\n            raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\")\n        return schemas.responses.FlowRunResponse.from_orm(flow_run)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_graph_v1","title":"<code>read_flow_run_graph_v1</code>  <code>async</code>","text":"<p>Get a task run dependency map for a given flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}/graph\")\nasync def read_flow_run_graph_v1(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[DependencyResult]:\n    \"\"\"\n    Get a task run dependency map for a given flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_runs.read_task_run_dependencies(\n            session=session, flow_run_id=flow_run_id\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_graph_v2","title":"<code>read_flow_run_graph_v2</code>  <code>async</code>","text":"<p>Get a graph of the tasks and subflow runs for the given flow run</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id:uuid}/graph-v2\")\nasync def read_flow_run_graph_v2(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    since: datetime.datetime = Query(\n        datetime.datetime.min,\n        description=\"Only include runs that start or end after this time.\",\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; Graph:\n    \"\"\"\n    Get a graph of the tasks and subflow runs for the given flow run\n    \"\"\"\n    async with db.session_context() as session:\n        try:\n            return await read_flow_run_graph(\n                session=session,\n                flow_run_id=flow_run_id,\n                since=since,\n            )\n        except FlowRunGraphTooLarge as e:\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=str(e),\n            )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Create a value from a flow run input</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}/input/{key}\")\nasync def read_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Path(..., description=\"The input key\", alias=\"key\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; PlainTextResponse:\n    \"\"\"\n    Create a value from a flow run input\n    \"\"\"\n\n    async with db.session_context() as session:\n        flow_run_input = await models.flow_run_input.read_flow_run_input(\n            session=session, flow_run_id=flow_run_id, key=key\n        )\n\n    if flow_run_input:\n        return PlainTextResponse(flow_run_input.value)\n    else:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run input not found\"\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Query for flow runs.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/filter\", response_class=ORJSONResponse)\nasync def read_flow_runs(\n    sort: schemas.sorting.FlowRunSort = Body(schemas.sorting.FlowRunSort.ID_DESC),\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.FlowRunResponse]:\n    \"\"\"\n    Query for flow runs.\n    \"\"\"\n    async with db.session_context() as session:\n        db_flow_runs = await models.flow_runs.read_flow_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n            offset=offset,\n            limit=limit,\n            sort=sort,\n        )\n\n        # Instead of relying on fastapi.encoders.jsonable_encoder to convert the\n        # response to JSON, we do so more efficiently ourselves.\n        # In particular, the FastAPI encoder is very slow for large, nested objects.\n        # See: https://github.com/tiangolo/fastapi/issues/1224\n        encoded = [\n            schemas.responses.FlowRunResponse.from_orm(fr).dict(json_compatible=True)\n            for fr in db_flow_runs\n        ]\n        return ORJSONResponse(content=encoded)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resume a paused flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/resume\")\nasync def resume_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    run_input: Optional[Dict] = Body(default=None, embed=True),\n    response: Response = None,\n    flow_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_flow_policy\n    ),\n    task_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_task_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Resume a paused flow run.\n    \"\"\"\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        flow_run = await models.flow_runs.read_flow_run(session, flow_run_id)\n        state = flow_run.state\n\n        if state is None or state.type != schemas.states.StateType.PAUSED:\n            result = OrchestrationResult(\n                state=None,\n                status=schemas.responses.SetStateStatus.ABORT,\n                details=schemas.responses.StateAbortDetails(\n                    reason=\"Cannot resume a flow run that is not paused.\"\n                ),\n            )\n            return result\n\n        orchestration_parameters.update({\"api-version\": api_version})\n\n        keyset = state.state_details.run_input_keyset\n\n        if keyset:\n            run_input = run_input or {}\n\n            try:\n                hydration_context = await schema_tools.HydrationContext.build(\n                    session=session,\n                    raise_on_error=True,\n                    render_jinja=True,\n                    render_workspace_variables=True,\n                )\n                run_input = schema_tools.hydrate(run_input, hydration_context) or {}\n            except schema_tools.HydrationError as exc:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=f\"Error hydrating run input: {exc}\",\n                    ),\n                )\n\n            schema_json = await models.flow_run_input.read_flow_run_input(\n                session=session, flow_run_id=flow_run.id, key=keyset[\"schema\"]\n            )\n\n            if schema_json is None:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Run input schema not found.\"\n                    ),\n                )\n\n            try:\n                schema = orjson.loads(schema_json.value)\n            except orjson.JSONDecodeError:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Run input schema is not valid JSON.\"\n                    ),\n                )\n\n            try:\n                schema_tools.validate(run_input, schema, raise_on_error=True)\n            except schema_tools.ValidationError as exc:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=f\"Reason: {exc}\"\n                    ),\n                )\n            except schema_tools.CircularSchemaRefError:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Invalid schema: Unable to validate schema with circular references.\",\n                    ),\n                )\n\n        if state.state_details.pause_reschedule:\n            orchestration_result = await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run_id,\n                state=schemas.states.Scheduled(\n                    name=\"Resuming\", scheduled_time=pendulum.now(\"UTC\")\n                ),\n                flow_policy=flow_policy,\n                orchestration_parameters=orchestration_parameters,\n            )\n        else:\n            orchestration_result = await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run_id,\n                state=schemas.states.Running(),\n                flow_policy=flow_policy,\n                orchestration_parameters=orchestration_parameters,\n            )\n\n        if (\n            keyset\n            and run_input\n            and orchestration_result.status == schemas.responses.SetStateStatus.ACCEPT\n        ):\n            # The state change is accepted, go ahead and store the validated\n            # run input.\n            await models.flow_run_input.create_flow_run_input(\n                session=session,\n                flow_run_input=schemas.core.FlowRunInput(\n                    flow_run_id=flow_run_id,\n                    key=keyset[\"response\"],\n                    value=orjson.dumps(run_input).decode(\"utf-8\"),\n                ),\n            )\n\n        # set the 201 if a new state was created\n        if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n        else:\n            response.status_code = status.HTTP_200_OK\n\n        return orchestration_result\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Set a flow run state, invoking any orchestration rules.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/set_state\")\nasync def set_flow_run_state(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    state: schemas.actions.StateCreate = Body(..., description=\"The intended state.\"),\n    force: bool = Body(\n        False,\n        description=(\n            \"If false, orchestration rules will be applied that may alter or prevent\"\n            \" the state transition. If True, orchestration rules are not applied.\"\n        ),\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    flow_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_flow_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; OrchestrationResult:\n    \"\"\"Set a flow run state, invoking any orchestration rules.\"\"\"\n\n    # pass the request version to the orchestration engine to support compatibility code\n    orchestration_parameters.update({\"api-version\": api_version})\n\n    now = pendulum.now(\"UTC\")\n\n    # create the state\n    async with db.session_context(\n        begin_transaction=True, with_for_update=True\n    ) as session:\n        orchestration_result = await models.flow_runs.set_flow_run_state(\n            session=session,\n            flow_run_id=flow_run_id,\n            # convert to a full State object\n            state=schemas.states.State.parse_obj(state),\n            force=force,\n            flow_policy=flow_policy,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    # set the 201 if a new state was created\n    if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    else:\n        response.status_code = status.HTTP_200_OK\n\n    return orchestration_result\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Updates a flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_flow_run(\n    flow_run: schemas.actions.FlowRunUpdate,\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a flow run.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        if flow_run.job_variables is not None:\n            this_run = await models.flow_runs.read_flow_run(\n                session, flow_run_id=flow_run_id\n            )\n            if this_run is None:\n                raise HTTPException(\n                    status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n                )\n            if not this_run.state:\n                raise HTTPException(\n                    status.HTTP_400_BAD_REQUEST,\n                    detail=\"Flow run state is required to update job variables but none exists\",\n                )\n            if this_run.state.type != schemas.states.StateType.SCHEDULED:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=f\"Job variables for a flow run in state {this_run.state.type.name} cannot be updated\",\n                )\n            if this_run.deployment_id is None:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=\"A deployment for the flow run could not be found\",\n                )\n\n            deployment = await models.deployments.read_deployment(\n                session=session, deployment_id=this_run.deployment_id\n            )\n            if deployment is None:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=\"A deployment for the flow run could not be found\",\n                )\n\n            await validate_job_variables_for_deployment_flow_run(\n                session, deployment, flow_run\n            )\n\n        result = await models.flow_runs.update_flow_run(\n            session=session, flow_run=flow_run, flow_run_id=flow_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\")\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flows/","title":"server.api.flows","text":"","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows","title":"<code>prefect.server.api.flows</code>","text":"<p>Routes for interacting with flow objects.</p>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.count_flows","title":"<code>count_flows</code>  <code>async</code>","text":"<p>Count flows.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/count\")\nasync def count_flows(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Count flows.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flows.count_flows(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Gracefully creates a new flow from the provided schema. If a flow with the same name already exists, the existing flow is returned.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/\")\nasync def create_flow(\n    flow: schemas.actions.FlowCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"Gracefully creates a new flow from the provided schema. If a flow with the\n    same name already exists, the existing flow is returned.\n    \"\"\"\n    # hydrate the input model into a full flow model\n    flow = schemas.core.Flow(**flow.dict())\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.flows.create_flow(session=session, flow=flow)\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    return model\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.delete_flow","title":"<code>delete_flow</code>  <code>async</code>","text":"<p>Delete a flow by id.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow(\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flows.delete_flow(session=session, flow_id=flow_id)\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Get a flow by id.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow(\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"\n    Get a flow by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow = await models.flows.read_flow(session=session, flow_id=flow_id)\n    if not flow:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n    return flow\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Get a flow by name.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.get(\"/name/{name}\")\nasync def read_flow_by_name(\n    name: str = Path(..., description=\"The name of the flow\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"\n    Get a flow by name.\n    \"\"\"\n    async with db.session_context() as session:\n        flow = await models.flows.read_flow_by_name(session=session, name=name)\n    if not flow:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n    return flow\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Query for flows.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_flows(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    sort: schemas.sorting.FlowSort = Body(schemas.sorting.FlowSort.NAME_ASC),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.Flow]:\n    \"\"\"\n    Query for flows.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flows.read_flows(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            sort=sort,\n            offset=offset,\n            limit=limit,\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.update_flow","title":"<code>update_flow</code>  <code>async</code>","text":"<p>Updates a flow.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_flow(\n    flow: schemas.actions.FlowUpdate,\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a flow.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flows.update_flow(\n            session=session, flow=flow, flow_id=flow_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/middleware/","title":"server.api.middleware","text":"","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware","title":"<code>prefect.server.api.middleware</code>","text":"","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware.CsrfMiddleware","title":"<code>CsrfMiddleware</code>","text":"<p>               Bases: <code>BaseHTTPMiddleware</code></p> <p>Middleware for CSRF protection. This middleware will check for a CSRF token in the headers of any POST, PUT, PATCH, or DELETE request. If the token is not present or does not match the token stored in the database for the client, the request will be rejected with a 403 status code.</p> Source code in <code>prefect/server/api/middleware.py</code> <pre><code>class CsrfMiddleware(BaseHTTPMiddleware):\n    \"\"\"\n    Middleware for CSRF protection. This middleware will check for a CSRF token\n    in the headers of any POST, PUT, PATCH, or DELETE request. If the token is\n    not present or does not match the token stored in the database for the\n    client, the request will be rejected with a 403 status code.\n    \"\"\"\n\n    async def dispatch(\n        self, request: Request, call_next: NextMiddlewareFunction\n    ) -&gt; Response:\n        \"\"\"\n        Dispatch method for the middleware. This method will check for the\n        presence of a CSRF token in the headers of the request and compare it\n        to the token stored in the database for the client. If the token is not\n        present or does not match, the request will be rejected with a 403\n        status code.\n        \"\"\"\n\n        request_needs_csrf_protection = request.method in {\n            \"POST\",\n            \"PUT\",\n            \"PATCH\",\n            \"DELETE\",\n        }\n\n        if (\n            settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value()\n            and request_needs_csrf_protection\n        ):\n            incoming_token = request.headers.get(\"Prefect-Csrf-Token\")\n            incoming_client = request.headers.get(\"Prefect-Csrf-Client\")\n\n            if incoming_token is None:\n                return JSONResponse(\n                    {\"detail\": \"Missing CSRF token.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                )\n\n            if incoming_client is None:\n                return JSONResponse(\n                    {\"detail\": \"Missing client identifier.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                )\n\n            db = provide_database_interface()\n            async with db.session_context() as session:\n                token = await models.csrf_token.read_token_for_client(\n                    session=session, client=incoming_client\n                )\n\n                if token is None or token.token != incoming_token:\n                    return JSONResponse(\n                        {\"detail\": \"Invalid CSRF token or client identifier.\"},\n                        status_code=status.HTTP_403_FORBIDDEN,\n                        headers={\"Access-Control-Allow-Origin\": \"*\"},\n                    )\n\n        return await call_next(request)\n</code></pre>","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware.CsrfMiddleware.dispatch","title":"<code>dispatch</code>  <code>async</code>","text":"<p>Dispatch method for the middleware. This method will check for the presence of a CSRF token in the headers of the request and compare it to the token stored in the database for the client. If the token is not present or does not match, the request will be rejected with a 403 status code.</p> Source code in <code>prefect/server/api/middleware.py</code> <pre><code>async def dispatch(\n    self, request: Request, call_next: NextMiddlewareFunction\n) -&gt; Response:\n    \"\"\"\n    Dispatch method for the middleware. This method will check for the\n    presence of a CSRF token in the headers of the request and compare it\n    to the token stored in the database for the client. If the token is not\n    present or does not match, the request will be rejected with a 403\n    status code.\n    \"\"\"\n\n    request_needs_csrf_protection = request.method in {\n        \"POST\",\n        \"PUT\",\n        \"PATCH\",\n        \"DELETE\",\n    }\n\n    if (\n        settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value()\n        and request_needs_csrf_protection\n    ):\n        incoming_token = request.headers.get(\"Prefect-Csrf-Token\")\n        incoming_client = request.headers.get(\"Prefect-Csrf-Client\")\n\n        if incoming_token is None:\n            return JSONResponse(\n                {\"detail\": \"Missing CSRF token.\"},\n                status_code=status.HTTP_403_FORBIDDEN,\n            )\n\n        if incoming_client is None:\n            return JSONResponse(\n                {\"detail\": \"Missing client identifier.\"},\n                status_code=status.HTTP_403_FORBIDDEN,\n            )\n\n        db = provide_database_interface()\n        async with db.session_context() as session:\n            token = await models.csrf_token.read_token_for_client(\n                session=session, client=incoming_client\n            )\n\n            if token is None or token.token != incoming_token:\n                return JSONResponse(\n                    {\"detail\": \"Invalid CSRF token or client identifier.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                    headers={\"Access-Control-Allow-Origin\": \"*\"},\n                )\n\n    return await call_next(request)\n</code></pre>","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/run_history/","title":"server.api.run_history","text":"","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/run_history/#prefect.server.api.run_history","title":"<code>prefect.server.api.run_history</code>","text":"<p>Utilities for querying flow and task run history.</p>","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/run_history/#prefect.server.api.run_history.run_history","title":"<code>run_history</code>  <code>async</code>","text":"<p>Produce a history of runs aggregated by interval and state</p> Source code in <code>prefect/server/api/run_history.py</code> <pre><code>@db_injector\nasync def run_history(\n    db: PrefectDBInterface,\n    session: sa.orm.Session,\n    run_type: Literal[\"flow_run\", \"task_run\"],\n    history_start: DateTimeTZ,\n    history_end: DateTimeTZ,\n    history_interval: datetime.timedelta,\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_queues: schemas.filters.WorkQueueFilter = None,\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Produce a history of runs aggregated by interval and state\n    \"\"\"\n\n    # SQLite has issues with very small intervals\n    # (by 0.001 seconds it stops incrementing the interval)\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise ValueError(\"History interval must not be less than 1 second.\")\n\n    # prepare run-specific models\n    if run_type == \"flow_run\":\n        run_model = db.FlowRun\n        run_filter_function = models.flow_runs._apply_flow_run_filters\n    elif run_type == \"task_run\":\n        run_model = db.TaskRun\n        run_filter_function = models.task_runs._apply_task_run_filters\n    else:\n        raise ValueError(\n            f\"Unknown run type {run_type!r}. Expected 'flow_run' or 'task_run'.\"\n        )\n\n    # create a CTE for timestamp intervals\n    intervals = db.make_timestamp_intervals(\n        history_start,\n        history_end,\n        history_interval,\n    ).cte(\"intervals\")\n\n    # apply filters to the flow runs (and related states)\n    runs = (\n        await run_filter_function(\n            sa.select(\n                run_model.id,\n                run_model.expected_start_time,\n                run_model.estimated_run_time,\n                run_model.estimated_start_time_delta,\n                run_model.state_type,\n                run_model.state_name,\n            ).select_from(run_model),\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_queues,\n        )\n    ).alias(\"runs\")\n    # outer join intervals to the filtered runs to create a dataset composed of\n    # every interval and the aggregate of all its runs. The runs aggregate is represented\n    # by a descriptive JSON object\n    counts = (\n        sa.select(\n            intervals.c.interval_start,\n            intervals.c.interval_end,\n            # build a JSON object, ignoring the case where the count of runs is 0\n            sa.case(\n                (sa.func.count(runs.c.id) == 0, None),\n                else_=db.build_json_object(\n                    \"state_type\",\n                    runs.c.state_type,\n                    \"state_name\",\n                    runs.c.state_name,\n                    \"count_runs\",\n                    sa.func.count(runs.c.id),\n                    # estimated run times only includes positive run times (to avoid any unexpected corner cases)\n                    \"sum_estimated_run_time\",\n                    sa.func.sum(\n                        db.greatest(0, sa.extract(\"epoch\", runs.c.estimated_run_time))\n                    ),\n                    # estimated lateness is the sum of any positive start time deltas\n                    \"sum_estimated_lateness\",\n                    sa.func.sum(\n                        db.greatest(\n                            0, sa.extract(\"epoch\", runs.c.estimated_start_time_delta)\n                        )\n                    ),\n                ),\n            ).label(\"state_agg\"),\n        )\n        .select_from(intervals)\n        .join(\n            runs,\n            sa.and_(\n                runs.c.expected_start_time &gt;= intervals.c.interval_start,\n                runs.c.expected_start_time &lt; intervals.c.interval_end,\n            ),\n            isouter=True,\n        )\n        .group_by(\n            intervals.c.interval_start,\n            intervals.c.interval_end,\n            runs.c.state_type,\n            runs.c.state_name,\n        )\n    ).alias(\"counts\")\n\n    # aggregate all state-aggregate objects into a single array for each interval,\n    # ensuring that intervals with no runs have an empty array\n    query = (\n        sa.select(\n            counts.c.interval_start,\n            counts.c.interval_end,\n            sa.func.coalesce(\n                db.json_arr_agg(db.cast_to_json(counts.c.state_agg)).filter(\n                    counts.c.state_agg.is_not(None)\n                ),\n                sa.text(\"'[]'\"),\n            ).label(\"states\"),\n        )\n        .group_by(counts.c.interval_start, counts.c.interval_end)\n        .order_by(counts.c.interval_start)\n        # return no more than 500 bars\n        .limit(500)\n    )\n\n    # issue the query\n    result = await session.execute(query)\n    records = result.mappings()\n\n    # load and parse the record if the database returns JSON as strings\n    if db.uses_json_strings:\n        records = [dict(r) for r in records]\n        for r in records:\n            r[\"states\"] = json.loads(r[\"states\"])\n\n    return pydantic.parse_obj_as(List[schemas.responses.HistoryResponse], list(records))\n</code></pre>","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/saved_searches/","title":"server.api.saved_searches","text":"","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches","title":"<code>prefect.server.api.saved_searches</code>","text":"<p>Routes for interacting with saved search objects.</p>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.create_saved_search","title":"<code>create_saved_search</code>  <code>async</code>","text":"<p>Gracefully creates a new saved search from the provided schema.</p> <p>If a saved search with the same name already exists, the saved search's fields are replaced.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.put(\"/\")\nasync def create_saved_search(\n    saved_search: schemas.actions.SavedSearchCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.SavedSearch:\n    \"\"\"Gracefully creates a new saved search from the provided schema.\n\n    If a saved search with the same name already exists, the saved search's fields are\n    replaced.\n    \"\"\"\n\n    # hydrate the input model into a full model\n    saved_search = schemas.core.SavedSearch(**saved_search.dict())\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.saved_searches.create_saved_search(\n            session=session, saved_search=saved_search\n        )\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n\n    return model\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.delete_saved_search","title":"<code>delete_saved_search</code>  <code>async</code>","text":"<p>Delete a saved search by id.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_saved_search(\n    saved_search_id: UUID = Path(..., description=\"The saved search id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a saved search by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.saved_searches.delete_saved_search(\n            session=session, saved_search_id=saved_search_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Saved search not found\"\n        )\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.read_saved_search","title":"<code>read_saved_search</code>  <code>async</code>","text":"<p>Get a saved search by id.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_saved_search(\n    saved_search_id: UUID = Path(..., description=\"The saved search id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.SavedSearch:\n    \"\"\"\n    Get a saved search by id.\n    \"\"\"\n    async with db.session_context() as session:\n        saved_search = await models.saved_searches.read_saved_search(\n            session=session, saved_search_id=saved_search_id\n        )\n    if not saved_search:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Saved search not found\"\n        )\n    return saved_search\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.read_saved_searches","title":"<code>read_saved_searches</code>  <code>async</code>","text":"<p>Query for saved searches.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_saved_searches(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.SavedSearch]:\n    \"\"\"\n    Query for saved searches.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.saved_searches.read_saved_searches(\n            session=session,\n            offset=offset,\n            limit=limit,\n        )\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/server/","title":"server.api.server","text":"","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server","title":"<code>prefect.server.api.server</code>","text":"<p>Defines the Prefect REST API FastAPI app.</p>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.RequestLimitMiddleware","title":"<code>RequestLimitMiddleware</code>","text":"<p>A middleware that limits the number of concurrent requests handled by the API.</p> <p>This is a blunt tool for limiting SQLite concurrent writes which will cause failures at high volume. Ideally, we would only apply the limit to routes that perform writes.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>class RequestLimitMiddleware:\n    \"\"\"\n    A middleware that limits the number of concurrent requests handled by the API.\n\n    This is a blunt tool for limiting SQLite concurrent writes which will cause failures\n    at high volume. Ideally, we would only apply the limit to routes that perform\n    writes.\n    \"\"\"\n\n    def __init__(self, app, limit: float):\n        self.app = app\n        self._limiter = anyio.CapacityLimiter(limit)\n\n    async def __call__(self, scope, receive, send) -&gt; None:\n        async with self._limiter:\n            await self.app(scope, receive, send)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.SPAStaticFiles","title":"<code>SPAStaticFiles</code>","text":"<p>               Bases: <code>StaticFiles</code></p> <p>Implementation of <code>StaticFiles</code> for serving single page applications.</p> <p>Adds <code>get_response</code> handling to ensure that when a resource isn't found the application still returns the index.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>class SPAStaticFiles(StaticFiles):\n    \"\"\"\n    Implementation of `StaticFiles` for serving single page applications.\n\n    Adds `get_response` handling to ensure that when a resource isn't found the\n    application still returns the index.\n    \"\"\"\n\n    async def get_response(self, path: str, scope):\n        try:\n            return await super().get_response(path, scope)\n        except HTTPException:\n            return await super().get_response(\"./index.html\", scope)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.create_api_app","title":"<code>create_api_app</code>","text":"<p>Create a FastAPI app that includes the Prefect REST API</p> <p>Parameters:</p> Name Type Description Default <code>router_prefix</code> <code>Optional[str]</code> <p>a prefix to apply to all included routers</p> <code>''</code> <code>dependencies</code> <code>Optional[List[Depends]]</code> <p>a list of global dependencies to add to each Prefect REST API router</p> <code>None</code> <code>health_check_path</code> <code>str</code> <p>the health check route path</p> <code>'/health'</code> <code>fast_api_app_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>kwargs to pass to the FastAPI constructor</p> <code>None</code> <code>router_overrides</code> <code>Mapping[str, Optional[APIRouter]]</code> <p>a mapping of route prefixes (i.e. \"/admin\") to new routers allowing the caller to override the default routers. If <code>None</code> is provided as a value, the default router will be dropped from the application.</p> <code>None</code> <p>Returns:</p> Type Description <code>FastAPI</code> <p>a FastAPI app that serves the Prefect REST API</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>def create_api_app(\n    router_prefix: Optional[str] = \"\",\n    dependencies: Optional[List[Depends]] = None,\n    health_check_path: str = \"/health\",\n    version_check_path: str = \"/version\",\n    fast_api_app_kwargs: Optional[Dict[str, Any]] = None,\n    router_overrides: Mapping[str, Optional[APIRouter]] = None,\n) -&gt; FastAPI:\n    \"\"\"\n    Create a FastAPI app that includes the Prefect REST API\n\n    Args:\n        router_prefix: a prefix to apply to all included routers\n        dependencies: a list of global dependencies to add to each Prefect REST API router\n        health_check_path: the health check route path\n        fast_api_app_kwargs: kwargs to pass to the FastAPI constructor\n        router_overrides: a mapping of route prefixes (i.e. \"/admin\") to new routers\n            allowing the caller to override the default routers. If `None` is provided\n            as a value, the default router will be dropped from the application.\n\n    Returns:\n        a FastAPI app that serves the Prefect REST API\n    \"\"\"\n    fast_api_app_kwargs = fast_api_app_kwargs or {}\n    api_app = FastAPI(title=API_TITLE, **fast_api_app_kwargs)\n    api_app.add_middleware(GZipMiddleware)\n\n    @api_app.get(health_check_path, tags=[\"Root\"])\n    async def health_check():\n        return True\n\n    @api_app.get(version_check_path, tags=[\"Root\"])\n    async def orion_info():\n        return SERVER_API_VERSION\n\n    # always include version checking\n    if dependencies is None:\n        dependencies = [Depends(enforce_minimum_version)]\n    else:\n        dependencies.append(Depends(enforce_minimum_version))\n\n    routers = {router.prefix: router for router in API_ROUTERS}\n\n    if router_overrides:\n        for prefix, router in router_overrides.items():\n            # We may want to allow this behavior in the future to inject new routes, but\n            # for now this will be treated an as an exception\n            if prefix not in routers:\n                raise KeyError(\n                    \"Router override provided for prefix that does not exist:\"\n                    f\" {prefix!r}\"\n                )\n\n            # Drop the existing router\n            existing_router = routers.pop(prefix)\n\n            # Replace it with a new router if provided\n            if router is not None:\n                if prefix != router.prefix:\n                    # We may want to allow this behavior in the future, but it will\n                    # break expectations without additional routing and is banned for\n                    # now\n                    raise ValueError(\n                        f\"Router override for {prefix!r} defines a different prefix \"\n                        f\"{router.prefix!r}.\"\n                    )\n\n                existing_paths = method_paths_from_routes(existing_router.routes)\n                new_paths = method_paths_from_routes(router.routes)\n                if not existing_paths.issubset(new_paths):\n                    raise ValueError(\n                        f\"Router override for {prefix!r} is missing paths defined by \"\n                        f\"the original router: {existing_paths.difference(new_paths)}\"\n                    )\n\n                routers[prefix] = router\n\n    for router in routers.values():\n        api_app.include_router(router, prefix=router_prefix, dependencies=dependencies)\n\n    return api_app\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.create_app","title":"<code>create_app</code>","text":"<p>Create an FastAPI app that includes the Prefect REST API and UI</p> <p>Parameters:</p> Name Type Description Default <code>settings</code> <code>Settings</code> <p>The settings to use to create the app. If not set, settings are pulled from the context.</p> <code>None</code> <code>ignore_cache</code> <code>bool</code> <p>If set, a new application will be created even if the settings match. Otherwise, an application is returned from the cache.</p> <code>False</code> <code>ephemeral</code> <code>bool</code> <p>If set, the application will be treated as ephemeral. The UI and services will be disabled.</p> <code>False</code> Source code in <code>prefect/server/api/server.py</code> <pre><code>def create_app(\n    settings: prefect.settings.Settings = None,\n    ephemeral: bool = False,\n    ignore_cache: bool = False,\n) -&gt; FastAPI:\n    \"\"\"\n    Create an FastAPI app that includes the Prefect REST API and UI\n\n    Args:\n        settings: The settings to use to create the app. If not set, settings are pulled\n            from the context.\n        ignore_cache: If set, a new application will be created even if the settings\n            match. Otherwise, an application is returned from the cache.\n        ephemeral: If set, the application will be treated as ephemeral. The UI\n            and services will be disabled.\n    \"\"\"\n    settings = settings or prefect.settings.get_current_settings()\n    cache_key = (settings.hash_key(), ephemeral)\n\n    if cache_key in APP_CACHE and not ignore_cache:\n        return APP_CACHE[cache_key]\n\n    # TODO: Move these startup functions out of this closure into the top-level or\n    #       another dedicated location\n    async def run_migrations():\n        \"\"\"Ensure the database is created and up to date with the current migrations\"\"\"\n        if prefect.settings.PREFECT_API_DATABASE_MIGRATE_ON_START:\n            from prefect.server.database.dependencies import provide_database_interface\n\n            db = provide_database_interface()\n            await db.create_db()\n\n    @_memoize_block_auto_registration\n    async def add_block_types():\n        \"\"\"Add all registered blocks to the database\"\"\"\n        if not prefect.settings.PREFECT_API_BLOCKS_REGISTER_ON_START:\n            return\n\n        from prefect.server.database.dependencies import provide_database_interface\n        from prefect.server.models.block_registration import run_block_auto_registration\n\n        db = provide_database_interface()\n        session = await db.session()\n\n        async with session:\n            await run_block_auto_registration(session=session)\n\n    async def start_services():\n        \"\"\"Start additional services when the Prefect REST API starts up.\"\"\"\n\n        if ephemeral:\n            app.state.services = None\n            return\n\n        service_instances = []\n\n        if prefect.settings.PREFECT_API_SERVICES_SCHEDULER_ENABLED.value():\n            service_instances.append(services.scheduler.Scheduler(handle_signals=False))\n            service_instances.append(\n                services.scheduler.RecentDeploymentsScheduler(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_ENABLED.value():\n            service_instances.append(\n                services.late_runs.MarkLateRuns(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED.value():\n            service_instances.append(\n                services.pause_expirations.FailExpiredPauses(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED.value():\n            service_instances.append(\n                services.cancellation_cleanup.CancellationCleanup(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_SERVER_ANALYTICS_ENABLED.value():\n            service_instances.append(services.telemetry.Telemetry(handle_signals=False))\n\n        if prefect.settings.PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED.value():\n            service_instances.append(\n                services.flow_run_notifications.FlowRunNotifications(\n                    handle_signals=False\n                )\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_FOREMAN_ENABLED.value():\n            service_instances.append(services.foreman.Foreman(handle_signals=False))\n\n        if prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value():\n            service_instances.append(\n                services.task_scheduling.TaskSchedulingTimeouts(handle_signals=False)\n            )\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS.value()\n            and prefect.settings.PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED.value()\n        ):\n            service_instances.append(EventLogger())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS.value()\n            and prefect.settings.PREFECT_API_SERVICES_TRIGGERS_ENABLED.value()\n        ):\n            service_instances.append(ReactiveTriggers())\n            service_instances.append(ProactiveTriggers(handle_signals=False))\n            service_instances.append(Actions())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS\n            and prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED\n        ):\n            service_instances.append(EventPersister())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS\n            and prefect.settings.PREFECT_API_EVENTS_STREAM_OUT_ENABLED\n        ):\n            service_instances.append(stream.Distributor())\n\n        loop = asyncio.get_running_loop()\n\n        app.state.services = {\n            service: loop.create_task(service.start()) for service in service_instances\n        }\n\n        for service, task in app.state.services.items():\n            logger.info(f\"{service.name} service scheduled to start in-app\")\n            task.add_done_callback(partial(on_service_exit, service))\n\n    async def stop_services():\n        \"\"\"Ensure services are stopped before the Prefect REST API shuts down.\"\"\"\n        if hasattr(app.state, \"services\") and app.state.services:\n            await asyncio.gather(*[service.stop() for service in app.state.services])\n            try:\n                await asyncio.gather(\n                    *[task.stop() for task in app.state.services.values()]\n                )\n            except Exception:\n                # `on_service_exit` should handle logging exceptions on exit\n                pass\n\n    @asynccontextmanager\n    async def lifespan(app):\n        try:\n            await run_migrations()\n            await add_block_types()\n            await start_services()\n            yield\n        finally:\n            await stop_services()\n\n    def on_service_exit(service, task):\n        \"\"\"\n        Added as a callback for completion of services to log exit\n        \"\"\"\n        try:\n            # Retrieving the result will raise the exception\n            task.result()\n        except Exception:\n            logger.error(f\"{service.name} service failed!\", exc_info=True)\n        else:\n            logger.info(f\"{service.name} service stopped!\")\n\n    app = FastAPI(\n        title=TITLE,\n        version=API_VERSION,\n        lifespan=lifespan,\n    )\n    api_app = create_api_app(\n        fast_api_app_kwargs={\n            \"exception_handlers\": {\n                # NOTE: FastAPI special cases the generic `Exception` handler and\n                #       registers it as a separate middleware from the others\n                Exception: custom_internal_exception_handler,\n                RequestValidationError: validation_exception_handler,\n                sa.exc.IntegrityError: integrity_exception_handler,\n                ObjectNotFoundError: prefect_object_not_found_exception_handler,\n            }\n        },\n    )\n    ui_app = create_ui_app(ephemeral)\n\n    # middleware\n    app.add_middleware(\n        CORSMiddleware,\n        allow_origins=[\"*\"],\n        allow_methods=[\"*\"],\n        allow_headers=[\"*\"],\n    )\n\n    # Limit the number of concurrent requests when using a SQLite database to reduce\n    # chance of errors where the database cannot be opened due to a high number of\n    # concurrent writes\n    if (\n        get_dialect(prefect.settings.PREFECT_API_DATABASE_CONNECTION_URL.value()).name\n        == \"sqlite\"\n    ):\n        app.add_middleware(RequestLimitMiddleware, limit=100)\n\n    if prefect.settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value():\n        app.add_middleware(api.middleware.CsrfMiddleware)\n\n    api_app.mount(\n        \"/static\",\n        StaticFiles(\n            directory=os.path.join(\n                os.path.dirname(os.path.realpath(__file__)), \"static\"\n            )\n        ),\n        name=\"static\",\n    )\n    app.api_app = api_app\n    app.mount(\"/api\", app=api_app, name=\"api\")\n    app.mount(\"/\", app=ui_app, name=\"ui\")\n\n    def openapi():\n        \"\"\"\n        Convenience method for extracting the user facing OpenAPI schema from the API app.\n\n        This method is attached to the global public app for easy access.\n        \"\"\"\n        partial_schema = get_openapi(\n            title=API_TITLE,\n            version=API_VERSION,\n            routes=api_app.routes,\n        )\n        new_schema = partial_schema.copy()\n        new_schema[\"paths\"] = {}\n        for path, value in partial_schema[\"paths\"].items():\n            new_schema[\"paths\"][f\"/api{path}\"] = value\n\n        new_schema[\"info\"][\"x-logo\"] = {\"url\": \"static/prefect-logo-mark-gradient.png\"}\n        return new_schema\n\n    app.openapi = openapi\n\n    APP_CACHE[cache_key] = app\n    return app\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.custom_internal_exception_handler","title":"<code>custom_internal_exception_handler</code>  <code>async</code>","text":"<p>Log a detailed exception for internal server errors before returning.</p> <p>Send 503 for errors clients can retry on.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def custom_internal_exception_handler(request: Request, exc: Exception):\n    \"\"\"\n    Log a detailed exception for internal server errors before returning.\n\n    Send 503 for errors clients can retry on.\n    \"\"\"\n    logger.error(\"Encountered exception in request:\", exc_info=True)\n\n    if is_client_retryable_exception(exc):\n        return JSONResponse(\n            content={\"exception_message\": \"Service Unavailable\"},\n            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n        )\n\n    return JSONResponse(\n        content={\"exception_message\": \"Internal Server Error\"},\n        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.integrity_exception_handler","title":"<code>integrity_exception_handler</code>  <code>async</code>","text":"<p>Capture database integrity errors.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def integrity_exception_handler(request: Request, exc: Exception):\n    \"\"\"Capture database integrity errors.\"\"\"\n    logger.error(\"Encountered exception in request:\", exc_info=True)\n    return JSONResponse(\n        content={\n            \"detail\": (\n                \"Data integrity conflict. This usually means a \"\n                \"unique or foreign key constraint was violated. \"\n                \"See server logs for details.\"\n            )\n        },\n        status_code=status.HTTP_409_CONFLICT,\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.prefect_object_not_found_exception_handler","title":"<code>prefect_object_not_found_exception_handler</code>  <code>async</code>","text":"<p>Return 404 status code on object not found exceptions.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def prefect_object_not_found_exception_handler(\n    request: Request, exc: ObjectNotFoundError\n):\n    \"\"\"Return 404 status code on object not found exceptions.\"\"\"\n    return JSONResponse(\n        content={\"exception_message\": str(exc)}, status_code=status.HTTP_404_NOT_FOUND\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.replace_placeholder_string_in_files","title":"<code>replace_placeholder_string_in_files</code>","text":"<p>Recursively loops through all files in the given directory and replaces a placeholder string.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>def replace_placeholder_string_in_files(\n    directory, placeholder, replacement, allowed_extensions=None\n):\n    \"\"\"\n    Recursively loops through all files in the given directory and replaces\n    a placeholder string.\n    \"\"\"\n    if allowed_extensions is None:\n        allowed_extensions = [\".txt\", \".html\", \".css\", \".js\", \".json\", \".txt\"]\n\n    for root, dirs, files in os.walk(directory):\n        for file in files:\n            if any(file.endswith(ext) for ext in allowed_extensions):\n                file_path = os.path.join(root, file)\n\n                with open(file_path, \"r\", encoding=\"utf-8\") as file:\n                    file_data = file.read()\n\n                file_data = file_data.replace(placeholder, replacement)\n\n                with open(file_path, \"w\", encoding=\"utf-8\") as file:\n                    file.write(file_data)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.validation_exception_handler","title":"<code>validation_exception_handler</code>  <code>async</code>","text":"<p>Provide a detailed message for request validation errors.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def validation_exception_handler(request: Request, exc: RequestValidationError):\n    \"\"\"Provide a detailed message for request validation errors.\"\"\"\n    return JSONResponse(\n        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n        content=jsonable_encoder(\n            {\n                \"exception_message\": \"Invalid request received.\",\n                \"exception_detail\": exc.errors(),\n                \"request_body\": exc.body,\n            }\n        ),\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/task_run_states/","title":"server.api.task_run_states","text":"","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states","title":"<code>prefect.server.api.task_run_states</code>","text":"<p>Routes for interacting with task run state objects.</p>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states.read_task_run_state","title":"<code>read_task_run_state</code>  <code>async</code>","text":"<p>Get a task run state by id.</p> Source code in <code>prefect/server/api/task_run_states.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_task_run_state(\n    task_run_state_id: UUID = Path(\n        ..., description=\"The task run state id\", alias=\"id\"\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.states.State:\n    \"\"\"\n    Get a task run state by id.\n    \"\"\"\n    async with db.session_context() as session:\n        task_run_state = await models.task_run_states.read_task_run_state(\n            session=session, task_run_state_id=task_run_state_id\n        )\n    if not task_run_state:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run state not found\"\n        )\n    return task_run_state\n</code></pre>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Get states associated with a task run.</p> Source code in <code>prefect/server/api/task_run_states.py</code> <pre><code>@router.get(\"/\")\nasync def read_task_run_states(\n    task_run_id: UUID,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.states.State]:\n    \"\"\"\n    Get states associated with a task run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_run_states.read_task_run_states(\n            session=session, task_run_id=task_run_id\n        )\n</code></pre>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_runs/","title":"server.api.task_runs","text":"","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs","title":"<code>prefect.server.api.task_runs</code>","text":"<p>Routes for interacting with task run objects.</p>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.count_task_runs","title":"<code>count_task_runs</code>  <code>async</code>","text":"<p>Count task runs.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/count\")\nasync def count_task_runs(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count task runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_runs.count_task_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Create a task run. If a task run with the same flow_run_id, task_key, and dynamic_key already exists, the existing task run will be returned.</p> <p>If no state is provided, the task run will be created in a PENDING state.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/\")\nasync def create_task_run(\n    task_run: schemas.actions.TaskRunCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_task_orchestration_parameters\n    ),\n) -&gt; schemas.core.TaskRun:\n    \"\"\"\n    Create a task run. If a task run with the same flow_run_id,\n    task_key, and dynamic_key already exists, the existing task\n    run will be returned.\n\n    If no state is provided, the task run will be created in a PENDING state.\n    \"\"\"\n\n    # hydrate the input model into a full task run / state model\n    task_run_dict = task_run.dict()\n    if not task_run_dict.get(\"id\"):\n        task_run_dict.pop(\"id\", None)\n    task_run = schemas.core.TaskRun(**task_run_dict)\n\n    if not task_run.state:\n        task_run.state = schemas.states.Pending()\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.task_runs.create_task_run(\n            session=session,\n            task_run=task_run,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n\n    new_task_run: schemas.core.TaskRun = schemas.core.TaskRun.from_orm(model)\n\n    return new_task_run\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_task_run(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a task run by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.task_runs.delete_task_run(\n            session=session, task_run_id=task_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task not found\")\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Get a task run by id.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_task_run(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.TaskRun:\n    \"\"\"\n    Get a task run by id.\n    \"\"\"\n    async with db.session_context() as session:\n        task_run = await models.task_runs.read_task_run(\n            session=session, task_run_id=task_run_id\n        )\n    if not task_run:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task not found\")\n    return task_run\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Query for task runs.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_task_runs(\n    sort: schemas.sorting.TaskRunSort = Body(schemas.sorting.TaskRunSort.ID_DESC),\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.TaskRun]:\n    \"\"\"\n    Query for task runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_runs.read_task_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            offset=offset,\n            limit=limit,\n            sort=sort,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Set a task run state, invoking any orchestration rules.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/{id}/set_state\")\nasync def set_task_run_state(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    state: schemas.actions.StateCreate = Body(..., description=\"The intended state.\"),\n    force: bool = Body(\n        False,\n        description=(\n            \"If false, orchestration rules will be applied that may alter or prevent\"\n            \" the state transition. If True, orchestration rules are not applied.\"\n        ),\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    task_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_task_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_task_orchestration_parameters\n    ),\n) -&gt; OrchestrationResult:\n    \"\"\"Set a task run state, invoking any orchestration rules.\"\"\"\n\n    now = pendulum.now(\"UTC\")\n\n    # create the state\n    async with db.session_context(\n        begin_transaction=True, with_for_update=True\n    ) as session:\n        orchestration_result = await models.task_runs.set_task_run_state(\n            session=session,\n            task_run_id=task_run_id,\n            state=schemas.states.State.parse_obj(\n                state\n            ),  # convert to a full State object\n            force=force,\n            task_policy=task_policy,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    # set the 201 if a new state was created\n    if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    else:\n        response.status_code = status.HTTP_200_OK\n\n    return orchestration_result\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.task_run_history","title":"<code>task_run_history</code>  <code>async</code>","text":"<p>Query for task run history data across a given range and interval.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/history\")\nasync def task_run_history(\n    history_start: DateTimeTZ = Body(..., description=\"The history's start time.\"),\n    history_end: DateTimeTZ = Body(..., description=\"The history's end time.\"),\n    history_interval: datetime.timedelta = Body(\n        ...,\n        description=(\n            \"The size of each history interval, in seconds. Must be at least 1 second.\"\n        ),\n        alias=\"history_interval_seconds\",\n    ),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Query for task run history data across a given range and interval.\n    \"\"\"\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise HTTPException(\n            status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"History interval must not be less than 1 second.\",\n        )\n\n    async with db.session_context() as session:\n        return await run_history(\n            session=session,\n            run_type=\"task_run\",\n            history_start=history_start,\n            history_end=history_end,\n            history_interval=history_interval,\n            flows=flows,\n            flow_runs=flow_runs,\n            task_runs=task_runs,\n            deployments=deployments,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.update_task_run","title":"<code>update_task_run</code>  <code>async</code>","text":"<p>Updates a task run.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_task_run(\n    task_run: schemas.actions.TaskRunUpdate,\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a task run.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.task_runs.update_task_run(\n            session=session, task_run=task_run, task_run_id=task_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task run not found\")\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/models/csrf_token/","title":"server.models.csrf_token","text":""},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token","title":"<code>prefect.server.models.csrf_token</code>","text":""},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.create_or_update_csrf_token","title":"<code>create_or_update_csrf_token</code>  <code>async</code>","text":"<p>Create or update a CSRF token for a client. If the client already has a token, it will be updated.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <code>client</code> <code>str</code> <p>The client identifier</p> required <p>Returns:</p> Type Description <code>CsrfToken</code> <p>core.CsrfToken: The CSRF token</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def create_or_update_csrf_token(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    client: str,\n) -&gt; core.CsrfToken:\n    \"\"\"Create or update a CSRF token for a client. If the client already has a\n    token, it will be updated.\n\n    Args:\n        session (AsyncSession): The database session\n        client (str): The client identifier\n\n    Returns:\n        core.CsrfToken: The CSRF token\n    \"\"\"\n\n    expiration = (\n        datetime.now(timezone.utc)\n        + settings.PREFECT_SERVER_CSRF_TOKEN_EXPIRATION.value()\n    )\n    token = secrets.token_hex(32)\n\n    await session.execute(\n        db.insert(db.CsrfToken)\n        .values(\n            client=client,\n            token=token,\n            expiration=expiration,\n        )\n        .on_conflict_do_update(\n            index_elements=[db.CsrfToken.client],\n            set_={\"token\": token, \"expiration\": expiration},\n        ),\n    )\n\n    # Return the created / updated token object\n    return await read_token_for_client(session=session, client=client)\n</code></pre>"},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.delete_expired_tokens","title":"<code>delete_expired_tokens</code>  <code>async</code>","text":"<p>Delete expired CSRF tokens.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of tokens deleted</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def delete_expired_tokens(db: PrefectDBInterface, session: AsyncSession) -&gt; int:\n    \"\"\"Delete expired CSRF tokens.\n\n    Args:\n        session (AsyncSession): The database session\n\n    Returns:\n        int: The number of tokens deleted\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.CsrfToken).where(\n            db.CsrfToken.expiration &lt; datetime.now(timezone.utc)\n        )\n    )\n    return result.rowcount\n</code></pre>"},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.read_token_for_client","title":"<code>read_token_for_client</code>  <code>async</code>","text":"<p>Read a CSRF token for a client.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <code>client</code> <code>str</code> <p>The client identifier</p> required <p>Returns:</p> Type Description <code>Optional[CsrfToken]</code> <p>Optional[core.CsrfToken]: The CSRF token, if it exists and is not expired.</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def read_token_for_client(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    client: str,\n) -&gt; Optional[core.CsrfToken]:\n    \"\"\"Read a CSRF token for a client.\n\n    Args:\n        session (AsyncSession): The database session\n        client (str): The client identifier\n\n    Returns:\n        Optional[core.CsrfToken]: The CSRF token, if it exists and is not\n            expired.\n    \"\"\"\n    token = (\n        await session.execute(\n            sa.select(db.CsrfToken).where(\n                sa.and_(\n                    db.CsrfToken.expiration &gt; datetime.now(timezone.utc),\n                    db.CsrfToken.client == client,\n                )\n            )\n        )\n    ).scalar_one_or_none()\n\n    if token is None:\n        return None\n\n    return core.CsrfToken.from_orm(token)\n</code></pre>"},{"location":"api-ref/server/models/deployments/","title":"server.models.deployments","text":""},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments","title":"<code>prefect.server.models.deployments</code>","text":"<p>Functions for interacting with deployment ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.check_work_queues_for_deployment","title":"<code>check_work_queues_for_deployment</code>  <code>async</code>","text":"<p>Get work queues that can pick up the specified deployment.</p> <p>Work queues will pick up a deployment when all of the following are met.</p> <ul> <li>The deployment has ALL tags that the work queue has (i.e. the work queue's tags must be a subset of the deployment's tags).</li> <li>The work queue's specified deployment IDs match the deployment's ID, or the work queue does NOT have specified deployment IDs.</li> <li>The work queue's specified flow runners match the deployment's flow runner or the work queue does NOT have a specified flow runner.</li> </ul> <p>Notes on the query:</p> <ul> <li>Our database currently allows either \"null\" and empty lists as null values in filters, so we need to catch both cases with \"or\".</li> <li><code>json_contains(A, B)</code> should be interpreted as \"True if A contains B\".</li> </ul> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>List[db.WorkQueue]: WorkQueues</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def check_work_queues_for_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; List[schemas.core.WorkQueue]:\n    \"\"\"\n    Get work queues that can pick up the specified deployment.\n\n    Work queues will pick up a deployment when all of the following are met.\n\n    - The deployment has ALL tags that the work queue has (i.e. the work\n    queue's tags must be a subset of the deployment's tags).\n    - The work queue's specified deployment IDs match the deployment's ID,\n    or the work queue does NOT have specified deployment IDs.\n    - The work queue's specified flow runners match the deployment's flow\n    runner or the work queue does NOT have a specified flow runner.\n\n    Notes on the query:\n\n    - Our database currently allows either \"null\" and empty lists as\n    null values in filters, so we need to catch both cases with \"or\".\n    - `json_contains(A, B)` should be interpreted as \"True if A\n    contains B\".\n\n    Returns:\n        List[db.WorkQueue]: WorkQueues\n    \"\"\"\n    deployment = await session.get(db.Deployment, deployment_id)\n    if not deployment:\n        raise ObjectNotFoundError(f\"Deployment with id {deployment_id} not found\")\n\n    query = (\n        select(db.WorkQueue)\n        # work queue tags are a subset of deployment tags\n        .filter(\n            or_(\n                json_contains(deployment.tags, db.WorkQueue.filter[\"tags\"]),\n                json_contains([], db.WorkQueue.filter[\"tags\"]),\n                json_contains(None, db.WorkQueue.filter[\"tags\"]),\n            )\n        )\n        # deployment_ids is null or contains the deployment's ID\n        .filter(\n            or_(\n                json_contains(\n                    db.WorkQueue.filter[\"deployment_ids\"],\n                    str(deployment.id),\n                ),\n                json_contains(None, db.WorkQueue.filter[\"deployment_ids\"]),\n                json_contains([], db.WorkQueue.filter[\"deployment_ids\"]),\n            )\n        )\n    )\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.count_deployments","title":"<code>count_deployments</code>  <code>async</code>","text":"<p>Count deployments.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count deployments whose flows match these criteria</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count deployments whose flow runs match these criteria</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count deployments whose task runs match these criteria</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count deployment that match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>only count deployments that match these work pool filters</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>only count deployments that match these work pool queue filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>the number of deployments matching filters</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def count_deployments(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count deployments.\n\n    Args:\n        session: A database session\n        flow_filter: only count deployments whose flows match these criteria\n        flow_run_filter: only count deployments whose flow runs match these criteria\n        task_run_filter: only count deployments whose task runs match these criteria\n        deployment_filter: only count deployment that match these filters\n        work_pool_filter: only count deployments that match these work pool filters\n        work_queue_filter: only count deployments that match these work pool queue filters\n\n    Returns:\n        int: the number of deployments matching filters\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.Deployment)\n\n    query = await _apply_deployment_filters(\n        query=query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Upserts a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment</code> <code>Deployment</code> <p>a deployment model</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the newly-created or updated deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def create_deployment(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment: schemas.core.Deployment,\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Upserts a deployment.\n\n    Args:\n        session: a database session\n        deployment: a deployment model\n\n    Returns:\n        db.Deployment: the newly-created or updated deployment\n\n    \"\"\"\n\n    # set `updated` manually\n    # known limitation of `on_conflict_do_update`, will not use `Column.onupdate`\n    # https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#the-set-clause\n    deployment.updated = pendulum.now(\"UTC\")\n\n    schedules = deployment.schedules\n    insert_values = deployment.dict(\n        shallow=True, exclude_unset=True, exclude={\"schedules\"}\n    )\n\n    # The job_variables field in client and server schemas is named\n    # infra_overrides in the database.\n    job_variables = insert_values.pop(\"job_variables\", None)\n    if job_variables:\n        insert_values[\"infra_overrides\"] = job_variables\n\n    conflict_update_fields = deployment.dict(\n        shallow=True,\n        exclude_unset=True,\n        exclude={\"id\", \"created\", \"created_by\", \"schedules\", \"job_variables\"},\n    )\n    if job_variables:\n        conflict_update_fields[\"infra_overrides\"] = job_variables\n\n    insert_stmt = (\n        db.insert(db.Deployment)\n        .values(**insert_values)\n        .on_conflict_do_update(\n            index_elements=db.deployment_unique_upsert_columns,\n            set_={**conflict_update_fields},\n        )\n    )\n\n    await session.execute(insert_stmt)\n\n    # Get the id of the deployment we just created or updated\n    result = await session.execute(\n        sa.select(db.Deployment.id).where(\n            sa.and_(\n                db.Deployment.flow_id == deployment.flow_id,\n                db.Deployment.name == deployment.name,\n            )\n        )\n    )\n    deployment_id = result.scalar_one_or_none()\n\n    if not deployment_id:\n        return None\n\n    # Because this was possibly an upsert, we need to delete any existing\n    # schedules and any runs from the old deployment.\n\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=True\n    )\n\n    await delete_schedules_for_deployment(session=session, deployment_id=deployment_id)\n\n    if schedules:\n        await create_deployment_schedules(\n            session=session,\n            deployment_id=deployment_id,\n            schedules=[\n                schemas.actions.DeploymentScheduleCreate(\n                    schedule=schedule.schedule,\n                    active=schedule.active,  # type: ignore[call-arg]\n                )\n                for schedule in schedules\n            ],\n        )\n\n    query = (\n        sa.select(db.Deployment)\n        .where(\n            sa.and_(\n                db.Deployment.flow_id == deployment.flow_id,\n                db.Deployment.name == deployment.name,\n            )\n        )\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.create_deployment_schedules","title":"<code>create_deployment_schedules</code>  <code>async</code>","text":"<p>Creates a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <code>schedules</code> <code>List[DeploymentScheduleCreate]</code> <p>a list of deployment schedule create actions</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def create_deployment_schedules(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    schedules: List[schemas.actions.DeploymentScheduleCreate],\n) -&gt; List[schemas.core.DeploymentSchedule]:\n    \"\"\"\n    Creates a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n        schedules: a list of deployment schedule create actions\n    \"\"\"\n\n    schedules_with_deployment_id = []\n    for schedule in schedules:\n        data = schedule.dict()\n        data[\"deployment_id\"] = deployment_id\n        schedules_with_deployment_id.append(data)\n\n    models = [\n        db.DeploymentSchedule(**schedule) for schedule in schedules_with_deployment_id\n    ]\n    session.add_all(models)\n    await session.flush()\n\n    return [schemas.core.DeploymentSchedule.from_orm(m) for m in models]\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the deployment was deleted</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a deployment by id.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        bool: whether or not the deployment was deleted\n    \"\"\"\n\n    # delete scheduled runs, both auto- and user- created.\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=False\n    )\n\n    result = await session.execute(\n        delete(db.Deployment).where(db.Deployment.id == deployment_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_deployment_schedule","title":"<code>delete_deployment_schedule</code>  <code>async</code>","text":"<p>Deletes a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_schedule_id</code> <code>UUID</code> <p>a deployment schedule id</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_deployment_schedule(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_id: UUID,\n) -&gt; bool:\n    \"\"\"\n    Deletes a deployment schedule.\n\n    Args:\n        session: A database session\n        deployment_schedule_id: a deployment schedule id\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.DeploymentSchedule).where(\n            sa.and_(\n                db.DeploymentSchedule.id == deployment_schedule_id,\n                db.DeploymentSchedule.deployment_id == deployment_id,\n            )\n        )\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_schedules_for_deployment","title":"<code>delete_schedules_for_deployment</code>  <code>async</code>","text":"<p>Deletes a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_schedules_for_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Deletes a deployment schedule.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.DeploymentSchedule).where(\n            db.DeploymentSchedule.deployment_id == deployment_id\n        )\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Reads a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Reads a deployment by id.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        db.Deployment: the deployment\n    \"\"\"\n\n    return await session.get(db.Deployment, deployment_id)\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Reads a deployment by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a deployment name</p> required <code>flow_name</code> <code>str</code> <p>the name of the flow the deployment belongs to</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment_by_name(\n    db: PrefectDBInterface, session: AsyncSession, name: str, flow_name: str\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Reads a deployment by name.\n\n    Args:\n        session: A database session\n        name: a deployment name\n        flow_name: the name of the flow the deployment belongs to\n\n    Returns:\n        db.Deployment: the deployment\n    \"\"\"\n\n    result = await session.execute(\n        select(db.Deployment)\n        .join(db.Flow, db.Deployment.flow_id == db.Flow.id)\n        .where(\n            sa.and_(\n                db.Flow.name == flow_name,\n                db.Deployment.name == name,\n            )\n        )\n        .limit(1)\n    )\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment_schedules","title":"<code>read_deployment_schedules</code>  <code>async</code>","text":"<p>Reads a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>list[schemas.core.DeploymentSchedule]: the deployment's schedules</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment_schedules(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_filter: Optional[\n        schemas.filters.DeploymentScheduleFilter\n    ] = None,\n) -&gt; List[schemas.core.DeploymentSchedule]:\n    \"\"\"\n    Reads a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        list[schemas.core.DeploymentSchedule]: the deployment's schedules\n    \"\"\"\n\n    query = (\n        sa.select(db.DeploymentSchedule)\n        .where(db.DeploymentSchedule.deployment_id == deployment_id)\n        .order_by(db.DeploymentSchedule.updated.desc())\n    )\n\n    if deployment_schedule_filter:\n        query = query.where(deployment_schedule_filter.as_sql_filter(db))\n\n    result = await session.execute(query)\n\n    return [schemas.core.DeploymentSchedule.from_orm(s) for s in result.scalars().all()]\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Read deployments.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>flow_filter</code> <code>FlowFilter</code> <p>only select deployments whose flows match these criteria</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select deployments whose flow runs match these criteria</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select deployments whose task runs match these criteria</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select deployment that match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>only select deployments whose work pools match these criteria</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>only select deployments whose work pool queues match these criteria</p> <code>None</code> <code>sort</code> <code>DeploymentSort</code> <p>the sort criteria for selected deployments. Defaults to <code>name</code> ASC.</p> <code>NAME_ASC</code> <p>Returns:</p> Type Description <code>Sequence[ORMDeployment]</code> <p>List[db.Deployment]: deployments</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployments(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    offset: int = None,\n    limit: int = None,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n    sort: schemas.sorting.DeploymentSort = schemas.sorting.DeploymentSort.NAME_ASC,\n) -&gt; Sequence[\"ORMDeployment\"]:\n    \"\"\"\n    Read deployments.\n\n    Args:\n        session: A database session\n        offset: Query offset\n        limit: Query limit\n        flow_filter: only select deployments whose flows match these criteria\n        flow_run_filter: only select deployments whose flow runs match these criteria\n        task_run_filter: only select deployments whose task runs match these criteria\n        deployment_filter: only select deployment that match these filters\n        work_pool_filter: only select deployments whose work pools match these criteria\n        work_queue_filter: only select deployments whose work pool queues match these criteria\n        sort: the sort criteria for selected deployments. Defaults to `name` ASC.\n\n    Returns:\n        List[db.Deployment]: deployments\n    \"\"\"\n\n    query = select(db.Deployment).order_by(sort.as_sql_sort(db=db))\n\n    query = await _apply_deployment_filters(\n        query=query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.schedule_runs","title":"<code>schedule_runs</code>  <code>async</code>","text":"<p>Schedule flow runs for a deployment</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment_id</code> <code>UUID</code> <p>the id of the deployment to schedule</p> required <code>start_time</code> <code>datetime</code> <p>the time from which to start scheduling runs</p> <code>None</code> <code>end_time</code> <code>datetime</code> <p>runs will be scheduled until at most this time</p> <code>None</code> <code>min_time</code> <code>timedelta</code> <p>runs will be scheduled until at least this far in the future</p> <code>None</code> <code>min_runs</code> <code>int</code> <p>a minimum amount of runs to schedule</p> <code>None</code> <code>max_runs</code> <code>int</code> <p>a maximum amount of runs to schedule</p> <code>None</code> <p>This function will generate the minimum number of runs that satisfy the min and max times, and the min and max counts. Specifically, the following order will be respected.</p> <pre><code>- Runs will be generated starting on or after the `start_time`\n- No more than `max_runs` runs will be generated\n- No runs will be generated after `end_time` is reached\n- At least `min_runs` runs will be generated\n- Runs will be generated until at least `start_time` + `min_time` is reached\n</code></pre> <p>Returns:</p> Type Description <code>List[UUID]</code> <p>a list of flow run ids scheduled for the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>async def schedule_runs(\n    session: AsyncSession,\n    deployment_id: UUID,\n    start_time: datetime.datetime = None,\n    end_time: datetime.datetime = None,\n    min_time: datetime.timedelta = None,\n    min_runs: int = None,\n    max_runs: int = None,\n    auto_scheduled: bool = True,\n) -&gt; List[UUID]:\n    \"\"\"\n    Schedule flow runs for a deployment\n\n    Args:\n        session: a database session\n        deployment_id: the id of the deployment to schedule\n        start_time: the time from which to start scheduling runs\n        end_time: runs will be scheduled until at most this time\n        min_time: runs will be scheduled until at least this far in the future\n        min_runs: a minimum amount of runs to schedule\n        max_runs: a maximum amount of runs to schedule\n\n    This function will generate the minimum number of runs that satisfy the min\n    and max times, and the min and max counts. Specifically, the following order\n    will be respected.\n\n        - Runs will be generated starting on or after the `start_time`\n        - No more than `max_runs` runs will be generated\n        - No runs will be generated after `end_time` is reached\n        - At least `min_runs` runs will be generated\n        - Runs will be generated until at least `start_time` + `min_time` is reached\n\n    Returns:\n        a list of flow run ids scheduled for the deployment\n    \"\"\"\n    if min_runs is None:\n        min_runs = PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS.value()\n    if max_runs is None:\n        max_runs = PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS.value()\n    if start_time is None:\n        start_time = pendulum.now(\"UTC\")\n    if end_time is None:\n        end_time = start_time + (\n            PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME.value()\n        )\n    if min_time is None:\n        min_time = PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME.value()\n\n    start_time = pendulum.instance(start_time)\n    end_time = pendulum.instance(end_time)\n\n    runs = await _generate_scheduled_flow_runs(\n        session=session,\n        deployment_id=deployment_id,\n        start_time=start_time,\n        end_time=end_time,\n        min_time=min_time,\n        min_runs=min_runs,\n        max_runs=max_runs,\n        auto_scheduled=auto_scheduled,\n    )\n    return await _insert_scheduled_flow_runs(session=session, runs=runs)\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.update_deployment","title":"<code>update_deployment</code>  <code>async</code>","text":"<p>Updates a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment_id</code> <code>UUID</code> <p>the ID of the deployment to modify</p> required <code>deployment</code> <code>DeploymentUpdate</code> <p>changes to a deployment model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether the deployment was updated</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def update_deployment(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment: schemas.actions.DeploymentUpdate,\n) -&gt; bool:\n    \"\"\"Updates a deployment.\n\n    Args:\n        session: a database session\n        deployment_id: the ID of the deployment to modify\n        deployment: changes to a deployment model\n\n    Returns:\n        bool: whether the deployment was updated\n\n    \"\"\"\n\n    from prefect.server.api.workers import WorkerLookups\n\n    schedules = deployment.schedules\n\n    # exclude_unset=True allows us to only update values provided by\n    # the user, ignoring any defaults on the model\n    update_data = deployment.dict(\n        shallow=True,\n        exclude_unset=True,\n        exclude={\"work_pool_name\"},\n    )\n\n    # The job_variables field in client and server schemas is named\n    # infra_overrides in the database.\n    job_variables = update_data.pop(\"job_variables\", None)\n    if job_variables:\n        update_data[\"infra_overrides\"] = job_variables\n\n    should_update_schedules = update_data.pop(\"schedules\", None) is not None\n\n    if deployment.work_pool_name and deployment.work_queue_name:\n        # If a specific pool name/queue name combination was provided, get the\n        # ID for that work pool queue.\n        update_data[\n            \"work_queue_id\"\n        ] = await WorkerLookups()._get_work_queue_id_from_name(\n            session=session,\n            work_pool_name=deployment.work_pool_name,\n            work_queue_name=deployment.work_queue_name,\n            create_queue_if_not_found=True,\n        )\n    elif deployment.work_pool_name:\n        # If just a pool name was provided, get the ID for its default\n        # work pool queue.\n        update_data[\n            \"work_queue_id\"\n        ] = await WorkerLookups()._get_default_work_queue_id_from_work_pool_name(\n            session=session,\n            work_pool_name=deployment.work_pool_name,\n        )\n    elif deployment.work_queue_name:\n        # If just a queue name was provided, ensure the queue exists and\n        # get its ID.\n        work_queue = await models.work_queues.ensure_work_queue_exists(\n            session=session, name=update_data[\"work_queue_name\"]\n        )\n        update_data[\"work_queue_id\"] = work_queue.id\n\n    if \"is_schedule_active\" in update_data:\n        update_data[\"paused\"] = not update_data[\"is_schedule_active\"]\n\n    update_stmt = (\n        sa.update(db.Deployment)\n        .where(db.Deployment.id == deployment_id)\n        .values(**update_data)\n    )\n    result = await session.execute(update_stmt)\n\n    # delete any auto scheduled runs that would have reflected the old deployment config\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=True\n    )\n\n    if should_update_schedules:\n        # If schedules were provided, remove the existing schedules and\n        # replace them with the new ones.\n        await delete_schedules_for_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        await create_deployment_schedules(\n            session=session,\n            deployment_id=deployment_id,\n            schedules=[\n                schemas.actions.DeploymentScheduleCreate(\n                    schedule=schedule.schedule,\n                    active=schedule.active,  # type: ignore[call-arg]\n                )\n                for schedule in schedules\n            ],\n        )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.update_deployment_schedule","title":"<code>update_deployment_schedule</code>  <code>async</code>","text":"<p>Updates a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_schedule_id</code> <code>UUID</code> <p>a deployment schedule id</p> required <code>schedule</code> <code>DeploymentScheduleUpdate</code> <p>a deployment schedule update action</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def update_deployment_schedule(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_id: UUID,\n    schedule: schemas.actions.DeploymentScheduleUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_schedule_id: a deployment schedule id\n        schedule: a deployment schedule update action\n    \"\"\"\n\n    result = await session.execute(\n        sa.update(db.DeploymentSchedule)\n        .where(\n            sa.and_(\n                db.DeploymentSchedule.id == deployment_schedule_id,\n                db.DeploymentSchedule.deployment_id == deployment_id,\n            )\n        )\n        .values(**schedule.dict(exclude_none=True))\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/","title":"server.models.flow_run_states","text":""},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states","title":"<code>prefect.server.models.flow_run_states</code>","text":"<p>Functions for interacting with flow run state ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.delete_flow_run_state","title":"<code>delete_flow_run_state</code>  <code>async</code>","text":"<p>Delete a flow run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_state_id</code> <code>UUID</code> <p>a flow run state id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow run state was deleted</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def delete_flow_run_state(\n    session: sa.orm.Session, flow_run_state_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a flow run state by id.\n\n    Args:\n        session: A database session\n        flow_run_state_id: a flow run state id\n\n    Returns:\n        bool: whether or not the flow run state was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.FlowRunState).where(db.FlowRunState.id == flow_run_state_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.read_flow_run_state","title":"<code>read_flow_run_state</code>  <code>async</code>","text":"<p>Reads a flow run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_state_id</code> <code>UUID</code> <p>a flow run state id</p> required <p>Returns:</p> Type Description <p>db.FlowRunState: the flow state</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def read_flow_run_state(\n    session: sa.orm.Session, flow_run_state_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a flow run state by id.\n\n    Args:\n        session: A database session\n        flow_run_state_id: a flow run state id\n\n    Returns:\n        db.FlowRunState: the flow state\n    \"\"\"\n\n    return await session.get(db.FlowRunState, flow_run_state_id)\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Reads flow runs states for a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id</p> required <p>Returns:</p> Type Description <p>List[db.FlowRunState]: the flow run states</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def read_flow_run_states(\n    session: sa.orm.Session, flow_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads flow runs states for a flow run.\n\n    Args:\n        session: A database session\n        flow_run_id: the flow run id\n\n    Returns:\n        List[db.FlowRunState]: the flow run states\n    \"\"\"\n\n    query = (\n        select(db.FlowRunState)\n        .filter_by(flow_run_id=flow_run_id)\n        .order_by(db.FlowRunState.timestamp)\n    )\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/","title":"server.models.flow_runs","text":""},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs","title":"<code>prefect.server.models.flow_runs</code>","text":"<p>Functions for interacting with flow run ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.count_flow_runs","title":"<code>count_flow_runs</code>  <code>async</code>","text":"<p>Count flow runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count flow runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count flow runs that match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count flow runs whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count flow runs whose deployments match these filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>count of flow runs</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def count_flow_runs(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count flow runs.\n\n    Args:\n        session: a database session\n        flow_filter: only count flow runs whose flows match these filters\n        flow_run_filter: only count flow runs that match these filters\n        task_run_filter: only count flow runs whose task runs match these filters\n        deployment_filter: only count flow runs whose deployments match these filters\n\n    Returns:\n        int: count of flow runs\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.FlowRun)\n\n    query = await _apply_flow_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Creates a new flow run.</p> <p>If the provided flow run has a state attached, it will also be created.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run</code> <code>FlowRun</code> <p>a flow run model</p> required <p>Returns:</p> Type Description <code>ORMFlowRun</code> <p>db.FlowRun: the newly-created flow run</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def create_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run: schemas.core.FlowRun,\n    orchestration_parameters: Optional[dict] = None,\n) -&gt; \"ORMFlowRun\":\n    \"\"\"Creates a new flow run.\n\n    If the provided flow run has a state attached, it will also be created.\n\n    Args:\n        session: a database session\n        flow_run: a flow run model\n\n    Returns:\n        db.FlowRun: the newly-created flow run\n    \"\"\"\n    now = pendulum.now(\"UTC\")\n\n    flow_run_dict = dict(\n        **flow_run.dict(\n            shallow=True,\n            exclude={\n                \"created\",\n                \"state\",\n                \"estimated_run_time\",\n                \"estimated_start_time_delta\",\n            },\n            exclude_unset=True,\n        ),\n        created=now,\n    )\n\n    # if no idempotency key was provided, create the run directly\n    if not flow_run.idempotency_key:\n        model = db.FlowRun(**flow_run_dict)\n        session.add(model)\n        await session.flush()\n\n    # otherwise let the database take care of enforcing idempotency\n    else:\n        insert_stmt = (\n            db.insert(db.FlowRun)\n            .values(**flow_run_dict)\n            .on_conflict_do_nothing(\n                index_elements=db.flow_run_unique_upsert_columns,\n            )\n        )\n        await session.execute(insert_stmt)\n\n        # read the run to see if idempotency was applied or not\n        query = (\n            sa.select(db.FlowRun)\n            .where(\n                sa.and_(\n                    db.FlowRun.flow_id == flow_run.flow_id,\n                    db.FlowRun.idempotency_key == flow_run.idempotency_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n            .options(\n                selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n            )\n        )\n        result = await session.execute(query)\n        model = result.scalar()\n\n    # if the flow run was created in this function call then we need to set the\n    # state. If it was created idempotently, the created time won't match.\n    if model.created == now and flow_run.state:\n        await models.flow_runs.set_flow_run_state(\n            session=session,\n            flow_run_id=model.id,\n            state=flow_run.state,\n            force=True,\n            orchestration_parameters=orchestration_parameters,\n        )\n    return model\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by flow_run_id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>a flow run id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow run was deleted</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def delete_flow_run(\n    db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a flow run by flow_run_id.\n\n    Args:\n        session: A database session\n        flow_run_id: a flow run id\n\n    Returns:\n        bool: whether or not the flow run was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.FlowRun).where(db.FlowRun.id == flow_run_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Reads a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>a flow run id</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlowRun]</code> <p>db.FlowRun: the flow run</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    for_update: bool = False,\n) -&gt; Optional[\"ORMFlowRun\"]:\n    \"\"\"\n    Reads a flow run by id.\n\n    Args:\n        session: A database session\n        flow_run_id: a flow run id\n\n    Returns:\n        db.FlowRun: the flow run\n    \"\"\"\n    select = (\n        sa.select(db.FlowRun)\n        .where(db.FlowRun.id == flow_run_id)\n        .options(\n            selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n        )\n    )\n\n    if for_update:\n        select = select.with_for_update()\n\n    result = await session.execute(select)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_run_graph","title":"<code>read_flow_run_graph</code>  <code>async</code>","text":"<p>Given a flow run, return the graph of it's task and subflow runs. If a <code>since</code> datetime is provided, only return items that may have changed since that time.</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_run_graph(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    since: datetime.datetime = datetime.datetime.min,\n) -&gt; Graph:\n    \"\"\"Given a flow run, return the graph of it's task and subflow runs. If a `since`\n    datetime is provided, only return items that may have changed since that time.\"\"\"\n    return await db.queries.flow_run_graph_v2(\n        db=db,\n        session=session,\n        flow_run_id=flow_run_id,\n        since=since,\n        max_nodes=PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES.value(),\n        max_artifacts=PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS.value(),\n    )\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Read flow runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>columns</code> <code>List</code> <p>a list of the flow run ORM columns to load, for performance</p> <code>None</code> <code>flow_filter</code> <code>FlowFilter</code> <p>only select flow runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select flow runs whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select flow runs whose deployments match these filters</p> <code>None</code> <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>Query sort</p> <code>ID_DESC</code> <p>Returns:</p> Type Description <code>Sequence[ORMFlowRun]</code> <p>List[db.FlowRun]: flow runs</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_runs(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    columns: List = None,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n    offset: int = None,\n    limit: int = None,\n    sort: schemas.sorting.FlowRunSort = schemas.sorting.FlowRunSort.ID_DESC,\n) -&gt; Sequence[\"ORMFlowRun\"]:\n    \"\"\"\n    Read flow runs.\n\n    Args:\n        session: a database session\n        columns: a list of the flow run ORM columns to load, for performance\n        flow_filter: only select flow runs whose flows match these filters\n        flow_run_filter: only select flow runs match these filters\n        task_run_filter: only select flow runs whose task runs match these filters\n        deployment_filter: only select flow runs whose deployments match these filters\n        offset: Query offset\n        limit: Query limit\n        sort: Query sort\n\n    Returns:\n        List[db.FlowRun]: flow runs\n    \"\"\"\n    query = (\n        select(db.FlowRun)\n        .order_by(sort.as_sql_sort(db))\n        .options(\n            selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n        )\n    )\n\n    if columns:\n        query = query.options(load_only(*columns))\n\n    query = await _apply_flow_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_task_run_dependencies","title":"<code>read_task_run_dependencies</code>  <code>async</code>","text":"<p>Get a task run dependency map for a given flow run.</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>async def read_task_run_dependencies(\n    session: AsyncSession,\n    flow_run_id: UUID,\n) -&gt; List[DependencyResult]:\n    \"\"\"\n    Get a task run dependency map for a given flow run.\n    \"\"\"\n    flow_run = await models.flow_runs.read_flow_run(\n        session=session, flow_run_id=flow_run_id\n    )\n    if not flow_run:\n        raise ObjectNotFoundError(f\"Flow run with id {flow_run_id} not found\")\n\n    task_runs = await models.task_runs.read_task_runs(\n        session=session,\n        flow_run_filter=schemas.filters.FlowRunFilter(\n            id=schemas.filters.FlowRunFilterId(any_=[flow_run_id])\n        ),\n    )\n\n    dependency_graph = []\n\n    for task_run in task_runs:\n        inputs = list(set(chain(*task_run.task_inputs.values())))\n        untrackable_result_status = (\n            False\n            if task_run.state is None\n            else task_run.state.state_details.untrackable_result\n        )\n        dependency_graph.append(\n            {\n                \"id\": task_run.id,\n                \"upstream_dependencies\": inputs,\n                \"state\": task_run.state,\n                \"expected_start_time\": task_run.expected_start_time,\n                \"name\": task_run.name,\n                \"start_time\": task_run.start_time,\n                \"end_time\": task_run.end_time,\n                \"total_run_time\": task_run.total_run_time,\n                \"estimated_run_time\": task_run.estimated_run_time,\n                \"untrackable_result\": untrackable_result_status,\n            }\n        )\n\n    return dependency_graph\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Creates a new orchestrated flow run state.</p> <p>Setting a new state on a run is the one of the principal actions that is governed by Prefect's orchestration logic. Setting a new run state will not guarantee creation, but instead trigger orchestration rules to govern the proposed <code>state</code> input. If the state is considered valid, it will be written to the database. Otherwise, a it's possible a different state, or no state, will be created. A <code>force</code> flag is supplied to bypass a subset of orchestration logic.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id</p> required <code>state</code> <code>State</code> <p>a flow run state model</p> required <code>force</code> <code>bool</code> <p>if False, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>OrchestrationResult object</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>async def set_flow_run_state(\n    session: AsyncSession,\n    flow_run_id: UUID,\n    state: schemas.states.State,\n    force: bool = False,\n    flow_policy: BaseOrchestrationPolicy = None,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Creates a new orchestrated flow run state.\n\n    Setting a new state on a run is the one of the principal actions that is governed by\n    Prefect's orchestration logic. Setting a new run state will not guarantee creation,\n    but instead trigger orchestration rules to govern the proposed `state` input. If\n    the state is considered valid, it will be written to the database. Otherwise, a\n    it's possible a different state, or no state, will be created. A `force` flag is\n    supplied to bypass a subset of orchestration logic.\n\n    Args:\n        session: a database session\n        flow_run_id: the flow run id\n        state: a flow run state model\n        force: if False, orchestration rules will be applied that may alter or prevent\n            the state transition. If True, orchestration rules are not applied.\n\n    Returns:\n        OrchestrationResult object\n    \"\"\"\n\n    # load the flow run\n    run = await models.flow_runs.read_flow_run(\n        session=session,\n        flow_run_id=flow_run_id,\n        # Lock the row to prevent orchestration race conditions\n        for_update=True,\n    )\n\n    if not run:\n        raise ObjectNotFoundError(f\"Flow run with id {flow_run_id} not found\")\n\n    initial_state = run.state.as_state() if run.state else None\n    initial_state_type = initial_state.type if initial_state else None\n    proposed_state_type = state.type if state else None\n    intended_transition = (initial_state_type, proposed_state_type)\n\n    if force or flow_policy is None:\n        flow_policy = MinimalFlowPolicy\n\n    orchestration_rules = flow_policy.compile_transition_rules(*intended_transition)\n    global_rules = GlobalFlowPolicy.compile_transition_rules(*intended_transition)\n\n    context = FlowOrchestrationContext(\n        session=session,\n        run=run,\n        initial_state=initial_state,\n        proposed_state=state,\n    )\n\n    if orchestration_parameters is not None:\n        context.parameters = orchestration_parameters\n\n    # apply orchestration rules and create the new flow run state\n    async with contextlib.AsyncExitStack() as stack:\n        for rule in orchestration_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        for rule in global_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        await context.validate_proposed_state()\n\n    if context.orchestration_error is not None:\n        raise context.orchestration_error\n\n    result = OrchestrationResult(\n        state=context.validated_state,\n        status=context.response_status,\n        details=context.response_details,\n    )\n\n    # if a new state is being set (either ACCEPTED from user or REJECTED\n    # and set by the server), check for any notification policies\n    if result.status in (SetStateStatus.ACCEPT, SetStateStatus.REJECT):\n        await models.flow_run_notification_policies.queue_flow_run_notifications(\n            session=session, flow_run=run\n        )\n\n    return result\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Updates a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id to update</p> required <code>flow_run</code> <code>FlowRunUpdate</code> <p>a flow run model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def update_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    flow_run: schemas.actions.FlowRunUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a flow run.\n\n    Args:\n        session: a database session\n        flow_run_id: the flow run id to update\n        flow_run: a flow run model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.FlowRun)\n        .where(db.FlowRun.id == flow_run_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**flow_run.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flows/","title":"server.models.flows","text":""},{"location":"api-ref/server/models/flows/#prefect.server.models.flows","title":"<code>prefect.server.models.flows</code>","text":"<p>Functions for interacting with flow ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.count_flows","title":"<code>count_flows</code>  <code>async</code>","text":"<p>Count flows.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>Union[FlowFilter, None]</code> <p>only count flows that match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Union[FlowRunFilter, None]</code> <p>only count flows whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Union[TaskRunFilter, None]</code> <p>only count flows whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Union[DeploymentFilter, None]</code> <p>only count flows whose deployments match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>Union[WorkPoolFilter, None]</code> <p>only count flows whose work pools match these filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>count of flows</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def count_flows(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: Union[schemas.filters.FlowFilter, None] = None,\n    flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None,\n    task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None,\n    deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None,\n    work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None,\n) -&gt; int:\n    \"\"\"\n    Count flows.\n\n    Args:\n        session: A database session\n        flow_filter: only count flows that match these filters\n        flow_run_filter: only count flows whose flow runs match these filters\n        task_run_filter: only count flows whose task runs match these filters\n        deployment_filter: only count flows whose deployments match these filters\n        work_pool_filter: only count flows whose work pools match these filters\n\n    Returns:\n        int: count of flows\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.Flow)\n\n    query = await _apply_flow_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar_one()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Creates a new flow.</p> <p>If a flow with the same name already exists, the existing flow is returned.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow</code> <code>Flow</code> <p>a flow model</p> required <p>Returns:</p> Type Description <code>ORMFlow</code> <p>db.Flow: the newly-created or existing flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def create_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow: schemas.core.Flow\n) -&gt; \"ORMFlow\":\n    \"\"\"\n    Creates a new flow.\n\n    If a flow with the same name already exists, the existing flow is returned.\n\n    Args:\n        session: a database session\n        flow: a flow model\n\n    Returns:\n        db.Flow: the newly-created or existing flow\n    \"\"\"\n\n    insert_stmt = (\n        db.insert(db.Flow)\n        .values(**flow.dict(shallow=True, exclude_unset=True))\n        .on_conflict_do_nothing(\n            index_elements=db.flow_unique_upsert_columns,\n        )\n    )\n    await session.execute(insert_stmt)\n\n    query = (\n        sa.select(db.Flow)\n        .where(\n            db.Flow.name == flow.name,\n        )\n        .limit(1)\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    model = result.scalar_one()\n    return model\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.delete_flow","title":"<code>delete_flow</code>  <code>async</code>","text":"<p>Delete a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_id</code> <code>UUID</code> <p>a flow id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow was deleted</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def delete_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a flow by id.\n\n    Args:\n        session: A database session\n        flow_id: a flow id\n\n    Returns:\n        bool: whether or not the flow was deleted\n    \"\"\"\n\n    result = await session.execute(delete(db.Flow).where(db.Flow.id == flow_id))\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Reads a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_id</code> <code>UUID</code> <p>a flow id</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlow]</code> <p>db.Flow: the flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow_id: UUID\n) -&gt; Optional[\"ORMFlow\"]:\n    \"\"\"\n    Reads a flow by id.\n\n    Args:\n        session: A database session\n        flow_id: a flow id\n\n    Returns:\n        db.Flow: the flow\n    \"\"\"\n    return await session.get(db.Flow, flow_id)\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Reads a flow by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a flow name</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlow]</code> <p>db.Flow: the flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flow_by_name(\n    db: PrefectDBInterface, session: AsyncSession, name: str\n) -&gt; Optional[\"ORMFlow\"]:\n    \"\"\"\n    Reads a flow by name.\n\n    Args:\n        session: A database session\n        name: a flow name\n\n    Returns:\n        db.Flow: the flow\n    \"\"\"\n\n    result = await session.execute(select(db.Flow).filter_by(name=name))\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Read multiple flows.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>Union[FlowFilter, None]</code> <p>only select flows that match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Union[FlowRunFilter, None]</code> <p>only select flows whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Union[TaskRunFilter, None]</code> <p>only select flows whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Union[DeploymentFilter, None]</code> <p>only select flows whose deployments match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>Union[WorkPoolFilter, None]</code> <p>only select flows whose work pools match these filters</p> <code>None</code> <code>offset</code> <code>Union[int, None]</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>Union[int, None]</code> <p>Query limit</p> <code>None</code> <p>Returns:</p> Type Description <code>Sequence[ORMFlow]</code> <p>List[db.Flow]: flows</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flows(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: Union[schemas.filters.FlowFilter, None] = None,\n    flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None,\n    task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None,\n    deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None,\n    work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None,\n    sort: schemas.sorting.FlowSort = schemas.sorting.FlowSort.NAME_ASC,\n    offset: Union[int, None] = None,\n    limit: Union[int, None] = None,\n) -&gt; Sequence[\"ORMFlow\"]:\n    \"\"\"\n    Read multiple flows.\n\n    Args:\n        session: A database session\n        flow_filter: only select flows that match these filters\n        flow_run_filter: only select flows whose flow runs match these filters\n        task_run_filter: only select flows whose task runs match these filters\n        deployment_filter: only select flows whose deployments match these filters\n        work_pool_filter: only select flows whose work pools match these filters\n        offset: Query offset\n        limit: Query limit\n\n    Returns:\n        List[db.Flow]: flows\n    \"\"\"\n\n    query = select(db.Flow).order_by(sort.as_sql_sort(db=db))\n\n    query = await _apply_flow_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.update_flow","title":"<code>update_flow</code>  <code>async</code>","text":"<p>Updates a flow.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_id</code> <code>UUID</code> <p>the flow id to update</p> required <code>flow</code> <code>FlowUpdate</code> <p>a flow update model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def update_flow(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_id: UUID,\n    flow: schemas.actions.FlowUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a flow.\n\n    Args:\n        session: a database session\n        flow_id: the flow id to update\n        flow: a flow update model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.Flow)\n        .where(db.Flow.id == flow_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**flow.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/","title":"server.models.saved_searches","text":""},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches","title":"<code>prefect.server.models.saved_searches</code>","text":"<p>Functions for interacting with saved search ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.create_saved_search","title":"<code>create_saved_search</code>  <code>async</code>","text":"<p>Upserts a SavedSearch.</p> <p>If a SavedSearch with the same name exists, all properties will be updated.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>saved_search</code> <code>SavedSearch</code> <p>a SavedSearch model</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the newly-created or updated SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def create_saved_search(\n    session: sa.orm.Session,\n    saved_search: schemas.core.SavedSearch,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Upserts a SavedSearch.\n\n    If a SavedSearch with the same name exists, all properties will be updated.\n\n    Args:\n        session (sa.orm.Session): a database session\n        saved_search (schemas.core.SavedSearch): a SavedSearch model\n\n    Returns:\n        db.SavedSearch: the newly-created or updated SavedSearch\n\n    \"\"\"\n\n    insert_stmt = (\n        db.insert(db.SavedSearch)\n        .values(**saved_search.dict(shallow=True, exclude_unset=True))\n        .on_conflict_do_update(\n            index_elements=db.saved_search_unique_upsert_columns,\n            set_=saved_search.dict(shallow=True, include={\"filters\"}),\n        )\n    )\n\n    await session.execute(insert_stmt)\n\n    query = (\n        sa.select(db.SavedSearch)\n        .where(\n            db.SavedSearch.name == saved_search.name,\n        )\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    model = result.scalar()\n\n    return model\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.delete_saved_search","title":"<code>delete_saved_search</code>  <code>async</code>","text":"<p>Delete a SavedSearch by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>saved_search_id</code> <code>str</code> <p>a SavedSearch id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the SavedSearch was deleted</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def delete_saved_search(\n    session: sa.orm.Session, saved_search_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a SavedSearch by id.\n\n    Args:\n        session (sa.orm.Session): A database session\n        saved_search_id (str): a SavedSearch id\n\n    Returns:\n        bool: whether or not the SavedSearch was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.SavedSearch).where(db.SavedSearch.id == saved_search_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_search","title":"<code>read_saved_search</code>  <code>async</code>","text":"<p>Reads a SavedSearch by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>saved_search_id</code> <code>str</code> <p>a SavedSearch id</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_search(\n    session: sa.orm.Session, saved_search_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a SavedSearch by id.\n\n    Args:\n        session (sa.orm.Session): A database session\n        saved_search_id (str): a SavedSearch id\n\n    Returns:\n        db.SavedSearch: the SavedSearch\n    \"\"\"\n\n    return await session.get(db.SavedSearch, saved_search_id)\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_search_by_name","title":"<code>read_saved_search_by_name</code>  <code>async</code>","text":"<p>Reads a SavedSearch by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a SavedSearch name</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_search_by_name(\n    session: sa.orm.Session, name: str, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a SavedSearch by name.\n\n    Args:\n        session (sa.orm.Session): A database session\n        name (str): a SavedSearch name\n\n    Returns:\n        db.SavedSearch: the SavedSearch\n    \"\"\"\n    result = await session.execute(\n        select(db.SavedSearch).where(db.SavedSearch.name == name).limit(1)\n    )\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_searches","title":"<code>read_saved_searches</code>  <code>async</code>","text":"<p>Read SavedSearches.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit(int)</code> <p>Query limit</p> required <p>Returns:</p> Type Description <p>List[db.SavedSearch]: SavedSearches</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_searches(\n    db: PrefectDBInterface,\n    session: sa.orm.Session,\n    offset: int = None,\n    limit: int = None,\n):\n    \"\"\"\n    Read SavedSearches.\n\n    Args:\n        session (sa.orm.Session): A database session\n        offset (int): Query offset\n        limit(int): Query limit\n\n    Returns:\n        List[db.SavedSearch]: SavedSearches\n    \"\"\"\n\n    query = select(db.SavedSearch).order_by(db.SavedSearch.name)\n\n    if offset is not None:\n        query = query.offset(offset)\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/","title":"server.models.task_run_states","text":""},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states","title":"<code>prefect.server.models.task_run_states</code>","text":"<p>Functions for interacting with task run state ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.delete_task_run_state","title":"<code>delete_task_run_state</code>  <code>async</code>","text":"<p>Delete a task run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_state_id</code> <code>UUID</code> <p>a task run state id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the task run state was deleted</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def delete_task_run_state(\n    session: sa.orm.Session, task_run_state_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a task run state by id.\n\n    Args:\n        session: A database session\n        task_run_state_id: a task run state id\n\n    Returns:\n        bool: whether or not the task run state was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.TaskRunState).where(db.TaskRunState.id == task_run_state_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.read_task_run_state","title":"<code>read_task_run_state</code>  <code>async</code>","text":"<p>Reads a task run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_state_id</code> <code>UUID</code> <p>a task run state id</p> required <p>Returns:</p> Type Description <p>db.TaskRunState: the task state</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def read_task_run_state(\n    session: sa.orm.Session, task_run_state_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a task run state by id.\n\n    Args:\n        session: A database session\n        task_run_state_id: a task run state id\n\n    Returns:\n        db.TaskRunState: the task state\n    \"\"\"\n\n    return await session.get(db.TaskRunState, task_run_state_id)\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Reads task runs states for a task run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <p>Returns:</p> Type Description <p>List[db.TaskRunState]: the task run states</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def read_task_run_states(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads task runs states for a task run.\n\n    Args:\n        session: A database session\n        task_run_id: the task run id\n\n    Returns:\n        List[db.TaskRunState]: the task run states\n    \"\"\"\n\n    query = (\n        select(db.TaskRunState)\n        .filter_by(task_run_id=task_run_id)\n        .order_by(db.TaskRunState.timestamp)\n    )\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/","title":"server.models.task_runs","text":""},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs","title":"<code>prefect.server.models.task_runs</code>","text":"<p>Functions for interacting with task run ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.count_task_runs","title":"<code>count_task_runs</code>  <code>async</code>","text":"<p>Count task runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count task runs whose deployments match these filters</p> <code>None</code> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def count_task_runs(\n    session: sa.orm.Session,\n    db: PrefectDBInterface,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count task runs.\n\n    Args:\n        session: a database session\n        flow_filter: only count task runs whose flows match these filters\n        flow_run_filter: only count task runs whose flow runs match these filters\n        task_run_filter: only count task runs that match these filters\n        deployment_filter: only count task runs whose deployments match these filters\n    Returns:\n        int: count of task runs\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.TaskRun)\n\n    query = await _apply_task_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        db=db,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.count_task_runs_by_state","title":"<code>count_task_runs_by_state</code>  <code>async</code>","text":"<p>Count task runs by state.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_filter</code> <code>Optional[FlowFilter]</code> <p>only count task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Optional[FlowRunFilter]</code> <p>only count task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Optional[TaskRunFilter]</code> <p>only count task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Optional[DeploymentFilter]</code> <p>only count task runs whose deployments match these filters</p> <code>None</code> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>async def count_task_runs_by_state(\n    session: AsyncSession,\n    db: PrefectDBInterface,\n    flow_filter: Optional[schemas.filters.FlowFilter] = None,\n    flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None,\n    task_run_filter: Optional[schemas.filters.TaskRunFilter] = None,\n    deployment_filter: Optional[schemas.filters.DeploymentFilter] = None,\n) -&gt; schemas.states.CountByState:\n    \"\"\"\n    Count task runs by state.\n\n    Args:\n        session: a database session\n        flow_filter: only count task runs whose flows match these filters\n        flow_run_filter: only count task runs whose flow runs match these filters\n        task_run_filter: only count task runs that match these filters\n        deployment_filter: only count task runs whose deployments match these filters\n    Returns:\n        schemas.states.CountByState: count of task runs by state\n    \"\"\"\n\n    base_query = (\n        select(\n            db.TaskRun.state_type,\n            sa.func.count(sa.text(\"*\")).label(\"count\"),\n        )\n        .select_from(db.TaskRun)\n        .group_by(db.TaskRun.state_type)\n    )\n\n    query = await _apply_task_run_filters(\n        base_query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n    )\n\n    result = await session.execute(query)\n\n    counts = schemas.states.CountByState()\n\n    for row in result:\n        setattr(counts, row.state_type, row.count)\n\n    return counts\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Creates a new task run.</p> <p>If a task run with the same flow_run_id, task_key, and dynamic_key already exists, the existing task run will be returned. If the provided task run has a state attached, it will also be created.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run</code> <code>TaskRun</code> <p>a task run model</p> required <p>Returns:</p> Type Description <p>db.TaskRun: the newly-created or existing task run</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def create_task_run(\n    session: sa.orm.Session,\n    task_run: schemas.core.TaskRun,\n    db: PrefectDBInterface,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n):\n    \"\"\"\n    Creates a new task run.\n\n    If a task run with the same flow_run_id, task_key, and dynamic_key already exists,\n    the existing task run will be returned. If the provided task run has a state\n    attached, it will also be created.\n\n    Args:\n        session: a database session\n        task_run: a task run model\n\n    Returns:\n        db.TaskRun: the newly-created or existing task run\n    \"\"\"\n\n    now = pendulum.now(\"UTC\")\n\n    # if a dynamic key exists, we need to guard against conflicts\n    if task_run.flow_run_id:\n        insert_stmt = (\n            db.insert(db.TaskRun)\n            .values(\n                created=now,\n                **task_run.dict(\n                    shallow=True, exclude={\"state\", \"created\"}, exclude_unset=True\n                ),\n            )\n            .on_conflict_do_nothing(\n                index_elements=db.task_run_unique_upsert_columns,\n            )\n        )\n        await session.execute(insert_stmt)\n\n        query = (\n            sa.select(db.TaskRun)\n            .where(\n                sa.and_(\n                    db.TaskRun.flow_run_id == task_run.flow_run_id,\n                    db.TaskRun.task_key == task_run.task_key,\n                    db.TaskRun.dynamic_key == task_run.dynamic_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n        )\n        result = await session.execute(query)\n        model = result.scalar()\n    else:\n        # Upsert on (task_key, dynamic_key) application logic.\n        query = (\n            sa.select(db.TaskRun)\n            .where(\n                sa.and_(\n                    db.TaskRun.flow_run_id.is_(None),\n                    db.TaskRun.task_key == task_run.task_key,\n                    db.TaskRun.dynamic_key == task_run.dynamic_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n        )\n\n        result = await session.execute(query)\n        model = result.scalar()\n\n        if model is None:\n            model = db.TaskRun(\n                created=now,\n                **task_run.dict(\n                    shallow=True, exclude={\"state\", \"created\"}, exclude_unset=True\n                ),\n                state=None,\n            )\n            session.add(model)\n            await session.flush()\n\n    if model.created == now and task_run.state:\n        await models.task_runs.set_task_run_state(\n            session=session,\n            task_run_id=model.id,\n            state=task_run.state,\n            force=True,\n            orchestration_parameters=orchestration_parameters,\n        )\n    return model\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id to delete</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the task run was deleted</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def delete_task_run(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a task run by id.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id to delete\n\n    Returns:\n        bool: whether or not the task run was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.TaskRun).where(db.TaskRun.id == task_run_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Read a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <p>Returns:</p> Type Description <p>db.TaskRun: the task run</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def read_task_run(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Read a task run by id.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id\n\n    Returns:\n        db.TaskRun: the task run\n    \"\"\"\n\n    model = await session.get(db.TaskRun, task_run_id)\n    return model\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Read task runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only select task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select task runs whose deployments match these filters</p> <code>None</code> <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>Query sort</p> <code>ID_DESC</code> <p>Returns:</p> Type Description <p>List[db.TaskRun]: the task runs</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def read_task_runs(\n    session: sa.orm.Session,\n    db: PrefectDBInterface,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    offset: int = None,\n    limit: int = None,\n    sort: schemas.sorting.TaskRunSort = schemas.sorting.TaskRunSort.ID_DESC,\n):\n    \"\"\"\n    Read task runs.\n\n    Args:\n        session: a database session\n        flow_filter: only select task runs whose flows match these filters\n        flow_run_filter: only select task runs whose flow runs match these filters\n        task_run_filter: only select task runs that match these filters\n        deployment_filter: only select task runs whose deployments match these filters\n        offset: Query offset\n        limit: Query limit\n        sort: Query sort\n\n    Returns:\n        List[db.TaskRun]: the task runs\n    \"\"\"\n\n    query = select(db.TaskRun).order_by(sort.as_sql_sort(db))\n\n    query = await _apply_task_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        db=db,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    logger.debug(f\"In read_task_runs, query generated is:\\n{query}\")\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Creates a new orchestrated task run state.</p> <p>Setting a new state on a run is the one of the principal actions that is governed by Prefect's orchestration logic. Setting a new run state will not guarantee creation, but instead trigger orchestration rules to govern the proposed <code>state</code> input. If the state is considered valid, it will be written to the database. Otherwise, a it's possible a different state, or no state, will be created. A <code>force</code> flag is supplied to bypass a subset of orchestration logic.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <code>state</code> <code>State</code> <p>a task run state model</p> required <code>force</code> <code>bool</code> <p>if False, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>OrchestrationResult object</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>async def set_task_run_state(\n    session: sa.orm.Session,\n    task_run_id: UUID,\n    state: schemas.states.State,\n    force: bool = False,\n    task_policy: BaseOrchestrationPolicy = None,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Creates a new orchestrated task run state.\n\n    Setting a new state on a run is the one of the principal actions that is governed by\n    Prefect's orchestration logic. Setting a new run state will not guarantee creation,\n    but instead trigger orchestration rules to govern the proposed `state` input. If\n    the state is considered valid, it will be written to the database. Otherwise, a\n    it's possible a different state, or no state, will be created. A `force` flag is\n    supplied to bypass a subset of orchestration logic.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id\n        state: a task run state model\n        force: if False, orchestration rules will be applied that may alter or prevent\n            the state transition. If True, orchestration rules are not applied.\n\n    Returns:\n        OrchestrationResult object\n    \"\"\"\n\n    # load the task run\n    run = await models.task_runs.read_task_run(session=session, task_run_id=task_run_id)\n\n    if not run:\n        raise ObjectNotFoundError(f\"Task run with id {task_run_id} not found\")\n\n    initial_state = run.state.as_state() if run.state else None\n    initial_state_type = initial_state.type if initial_state else None\n    proposed_state_type = state.type if state else None\n    intended_transition = (initial_state_type, proposed_state_type)\n\n    if run.flow_run_id is None:\n        task_policy = AutonomousTaskPolicy  # CoreTaskPolicy + prevent `Running` -&gt; `Running` transition\n    elif force or task_policy is None:\n        task_policy = MinimalTaskPolicy\n\n    orchestration_rules = task_policy.compile_transition_rules(*intended_transition)\n    global_rules = GlobalTaskPolicy.compile_transition_rules(*intended_transition)\n\n    context = TaskOrchestrationContext(\n        session=session,\n        run=run,\n        initial_state=initial_state,\n        proposed_state=state,\n    )\n\n    if orchestration_parameters is not None:\n        context.parameters = orchestration_parameters\n\n    # apply orchestration rules and create the new task run state\n    async with contextlib.AsyncExitStack() as stack:\n        for rule in orchestration_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        for rule in global_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        await context.validate_proposed_state()\n\n    if context.orchestration_error is not None:\n        raise context.orchestration_error\n\n    result = OrchestrationResult(\n        state=context.validated_state,\n        status=context.response_status,\n        details=context.response_details,\n    )\n\n    return result\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.update_task_run","title":"<code>update_task_run</code>  <code>async</code>","text":"<p>Updates a task run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id to update</p> required <code>task_run</code> <code>TaskRunUpdate</code> <p>a task run model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def update_task_run(\n    session: AsyncSession,\n    task_run_id: UUID,\n    task_run: schemas.actions.TaskRunUpdate,\n    db: PrefectDBInterface,\n) -&gt; bool:\n    \"\"\"\n    Updates a task run.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id to update\n        task_run: a task run model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.TaskRun)\n        .where(db.TaskRun.id == task_run_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**task_run.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/","title":"server.orchestration.core_policy","text":""},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy","title":"<code>prefect.server.orchestration.core_policy</code>","text":"<p>Orchestration logic that fires on state transitions.</p> <p><code>CoreFlowPolicy</code> and <code>CoreTaskPolicy</code> contain all default orchestration rules that Prefect enforces on a state transition.</p>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CoreFlowPolicy","title":"<code>CoreFlowPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against flow-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CoreFlowPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against flow-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            PreventDuplicateTransitions,\n            HandleFlowTerminalStateTransitions,\n            EnforceCancellingToCancelledTransition,\n            BypassCancellingFlowRunsWithNoInfra,\n            PreventPendingTransitions,\n            EnsureOnlyScheduledFlowsMarkedLate,\n            HandlePausingFlows,\n            HandleResumingPausedFlows,\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedFlows,\n        ] + ([InstrumentFlowRunStateTransitions] if PREFECT_EXPERIMENTAL_EVENTS else [])\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CoreTaskPolicy","title":"<code>CoreTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against task-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CoreTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against task-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            CacheRetrieval,\n            HandleTaskTerminalStateTransitions,\n            PreventRunningTasksFromStoppedFlows,\n            SecureTaskConcurrencySlots,  # retrieve cached states even if slots are full\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedTasks,\n            RenameReruns,\n            UpdateFlowRunTrackerOnTasks,\n            CacheInsertion,\n            ReleaseTaskConcurrencySlots,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.AutonomousTaskPolicy","title":"<code>AutonomousTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against task-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class AutonomousTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against task-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            PreventPendingTransitions,\n            CacheRetrieval,\n            HandleTaskTerminalStateTransitions,\n            SecureTaskConcurrencySlots,  # retrieve cached states even if slots are full\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedTasks,\n            RenameReruns,\n            UpdateFlowRunTrackerOnTasks,\n            CacheInsertion,\n            ReleaseTaskConcurrencySlots,\n            EnqueueScheduledTasks,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.SecureTaskConcurrencySlots","title":"<code>SecureTaskConcurrencySlots</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Checks relevant concurrency slots are available before entering a Running state.</p> <p>This rule checks if concurrency limits have been set on the tags associated with a TaskRun. If so, a concurrency slot will be secured against each concurrency limit before being allowed to transition into a running state. If a concurrency limit has been reached, the client will be instructed to delay the transition for the duration specified by the \"PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS\" setting before trying again. If the concurrency limit set on a tag is 0, the transition will be aborted to prevent deadlocks.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class SecureTaskConcurrencySlots(BaseOrchestrationRule):\n    \"\"\"\n    Checks relevant concurrency slots are available before entering a Running state.\n\n    This rule checks if concurrency limits have been set on the tags associated with a\n    TaskRun. If so, a concurrency slot will be secured against each concurrency limit\n    before being allowed to transition into a running state. If a concurrency limit has\n    been reached, the client will be instructed to delay the transition for the duration\n    specified by the \"PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS\" setting\n    before trying again. If the concurrency limit set on a tag is 0, the transition will\n    be aborted to prevent deadlocks.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        self._applied_limits = []\n        filtered_limits = (\n            await concurrency_limits.filter_concurrency_limits_for_orchestration(\n                context.session, tags=context.run.tags\n            )\n        )\n        run_limits = {limit.tag: limit for limit in filtered_limits}\n        for tag, cl in run_limits.items():\n            limit = cl.concurrency_limit\n            if limit == 0:\n                # limits of 0 will deadlock, and the transition needs to abort\n                for stale_tag in self._applied_limits:\n                    stale_limit = run_limits.get(stale_tag, None)\n                    active_slots = set(stale_limit.active_slots)\n                    active_slots.discard(str(context.run.id))\n                    stale_limit.active_slots = list(active_slots)\n\n                await self.abort_transition(\n                    reason=(\n                        f'The concurrency limit on tag \"{tag}\" is 0 and will deadlock'\n                        \" if the task tries to run again.\"\n                    ),\n                )\n            elif len(cl.active_slots) &gt;= limit:\n                # if the limit has already been reached, delay the transition\n                for stale_tag in self._applied_limits:\n                    stale_limit = run_limits.get(stale_tag, None)\n                    active_slots = set(stale_limit.active_slots)\n                    active_slots.discard(str(context.run.id))\n                    stale_limit.active_slots = list(active_slots)\n\n                await self.delay_transition(\n                    PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS.value(),\n                    f\"Concurrency limit for the {tag} tag has been reached\",\n                )\n            else:\n                # log the TaskRun ID to active_slots\n                self._applied_limits.append(tag)\n                active_slots = set(cl.active_slots)\n                active_slots.add(str(context.run.id))\n                cl.active_slots = list(active_slots)\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        for tag in self._applied_limits:\n            cl = await concurrency_limits.read_concurrency_limit_by_tag(\n                context.session, tag\n            )\n            active_slots = set(cl.active_slots)\n            active_slots.discard(str(context.run.id))\n            cl.active_slots = list(active_slots)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.ReleaseTaskConcurrencySlots","title":"<code>ReleaseTaskConcurrencySlots</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Releases any concurrency slots held by a run upon exiting a Running or Cancelling state.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class ReleaseTaskConcurrencySlots(BaseUniversalTransform):\n    \"\"\"\n    Releases any concurrency slots held by a run upon exiting a Running or\n    Cancelling state.\n    \"\"\"\n\n    async def after_transition(\n        self,\n        context: OrchestrationContext,\n    ):\n        if self.nullified_transition():\n            return\n\n        if context.validated_state and context.validated_state.type not in [\n            states.StateType.RUNNING,\n            states.StateType.CANCELLING,\n        ]:\n            filtered_limits = (\n                await concurrency_limits.filter_concurrency_limits_for_orchestration(\n                    context.session, tags=context.run.tags\n                )\n            )\n            run_limits = {limit.tag: limit for limit in filtered_limits}\n            for tag, cl in run_limits.items():\n                active_slots = set(cl.active_slots)\n                active_slots.discard(str(context.run.id))\n                cl.active_slots = list(active_slots)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.AddUnknownResult","title":"<code>AddUnknownResult</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Assign an \"unknown\" result to runs that are forced to complete from a failed or crashed state, if the previous state used a persisted result.</p> <p>When we retry a flow run, we retry any task runs that were in a failed or crashed state, but we also retry completed task runs that didn't use a persisted result. This means that without a sentinel value for unknown results, a task run forced into Completed state will always get rerun if the flow run retries because the task run lacks a persisted result. The \"unknown\" sentinel ensures that when we see a completed task run with an unknown result, we know that it was forced to complete and we shouldn't rerun it.</p> <p>Flow runs forced into a Completed state have a similar problem: without a sentinel value, attempting to refer to the flow run's result will raise an exception because the flow run has no result. The sentinel ensures that we can distinguish between a flow run that has no result and a flow run that has an unknown result.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class AddUnknownResult(BaseOrchestrationRule):\n    \"\"\"\n    Assign an \"unknown\" result to runs that are forced to complete from a\n    failed or crashed state, if the previous state used a persisted result.\n\n    When we retry a flow run, we retry any task runs that were in a failed or\n    crashed state, but we also retry completed task runs that didn't use a\n    persisted result. This means that without a sentinel value for unknown\n    results, a task run forced into Completed state will always get rerun if the\n    flow run retries because the task run lacks a persisted result. The\n    \"unknown\" sentinel ensures that when we see a completed task run with an\n    unknown result, we know that it was forced to complete and we shouldn't\n    rerun it.\n\n    Flow runs forced into a Completed state have a similar problem: without a\n    sentinel value, attempting to refer to the flow run's result will raise an\n    exception because the flow run has no result. The sentinel ensures that we\n    can distinguish between a flow run that has no result and a flow run that\n    has an unknown result.\n    \"\"\"\n\n    FROM_STATES = [StateType.FAILED, StateType.CRASHED]\n    TO_STATES = [StateType.COMPLETED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state\n            and initial_state.data\n            and initial_state.data.get(\"type\") == \"reference\"\n        ):\n            unknown_result = await UnknownResult.create()\n            self.context.proposed_state.data = unknown_result.dict()\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CacheInsertion","title":"<code>CacheInsertion</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Caches completed states with cache keys after they are validated.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CacheInsertion(BaseOrchestrationRule):\n    \"\"\"\n    Caches completed states with cache keys after they are validated.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.COMPLETED]\n\n    @inject_db\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n        db: PrefectDBInterface,\n    ) -&gt; None:\n        if not validated_state or not context.session:\n            return\n\n        cache_key = validated_state.state_details.cache_key\n        if cache_key:\n            new_cache_item = db.TaskRunStateCache(\n                cache_key=cache_key,\n                cache_expiration=validated_state.state_details.cache_expiration,\n                task_run_state_id=validated_state.id,\n            )\n            context.session.add(new_cache_item)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CacheRetrieval","title":"<code>CacheRetrieval</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects running states if a completed state has been cached.</p> <p>This rule rejects transitions into a running state with a cache key if the key has already been associated with a completed state in the cache table. The client will be instructed to transition into the cached completed state instead.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CacheRetrieval(BaseOrchestrationRule):\n    \"\"\"\n    Rejects running states if a completed state has been cached.\n\n    This rule rejects transitions into a running state with a cache key if the key\n    has already been associated with a completed state in the cache table. The client\n    will be instructed to transition into the cached completed state instead.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    @inject_db\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n        db: PrefectDBInterface,\n    ) -&gt; None:\n        cache_key = proposed_state.state_details.cache_key\n        if cache_key and not proposed_state.state_details.refresh_cache:\n            # Check for cached states matching the cache key\n            cached_state_id = (\n                select(db.TaskRunStateCache.task_run_state_id)\n                .where(\n                    sa.and_(\n                        db.TaskRunStateCache.cache_key == cache_key,\n                        sa.or_(\n                            db.TaskRunStateCache.cache_expiration.is_(None),\n                            db.TaskRunStateCache.cache_expiration &gt; pendulum.now(\"utc\"),\n                        ),\n                    ),\n                )\n                .order_by(db.TaskRunStateCache.created.desc())\n                .limit(1)\n            ).scalar_subquery()\n            query = select(db.TaskRunState).where(db.TaskRunState.id == cached_state_id)\n            cached_state = (await context.session.execute(query)).scalar()\n            if cached_state:\n                new_state = cached_state.as_state().copy(reset_fields=True)\n                new_state.name = \"Cached\"\n                await self.reject_transition(\n                    state=new_state, reason=\"Retrieved state from cache\"\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RetryFailedFlows","title":"<code>RetryFailedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p> <p>This rule rejects transitions into a failed state if <code>retries</code> has been set and the run count has not reached the specified limit. The client will be instructed to transition into a scheduled state to retry flow execution.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RetryFailedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Rejects failed states and schedules a retry if the retry limit has not been reached.\n\n    This rule rejects transitions into a failed state if `retries` has been\n    set and the run count has not reached the specified limit. The client will be\n    instructed to transition into a scheduled state to retry flow execution.\n    \"\"\"\n\n    FROM_STATES = [StateType.RUNNING]\n    TO_STATES = [StateType.FAILED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        run_settings = context.run_settings\n        run_count = context.run.run_count\n\n        if run_settings.retries is None or run_count &gt; run_settings.retries:\n            return  # Retry count exceeded, allow transition to failed\n\n        scheduled_start_time = pendulum.now(\"UTC\").add(\n            seconds=run_settings.retry_delay or 0\n        )\n\n        # support old-style flow run retries for older clients\n        # older flow retries require us to loop over failed tasks to update their state\n        # this is not required after API version 0.8.3\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version and api_version &lt; Version(\"0.8.3\"):\n            failed_task_runs = await models.task_runs.read_task_runs(\n                context.session,\n                flow_run_filter=filters.FlowRunFilter(id={\"any_\": [context.run.id]}),\n                task_run_filter=filters.TaskRunFilter(\n                    state={\"type\": {\"any_\": [\"FAILED\"]}}\n                ),\n            )\n            for run in failed_task_runs:\n                await models.task_runs.set_task_run_state(\n                    context.session,\n                    run.id,\n                    state=states.AwaitingRetry(scheduled_time=scheduled_start_time),\n                    force=True,\n                )\n                # Reset the run count so that the task run retries still work correctly\n                run.run_count = 0\n\n        # Reset pause metadata on retry\n        # Pauses as a concept only exist after API version 0.8.4\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n            updated_policy = context.run.empirical_policy.dict()\n            updated_policy[\"resuming\"] = False\n            updated_policy[\"pause_keys\"] = set()\n            context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n\n        # Generate a new state for the flow\n        retry_state = states.AwaitingRetry(\n            scheduled_time=scheduled_start_time,\n            message=proposed_state.message,\n            data=proposed_state.data,\n        )\n        await self.reject_transition(state=retry_state, reason=\"Retrying\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RetryFailedTasks","title":"<code>RetryFailedTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p> <p>This rule rejects transitions into a failed state if <code>retries</code> has been set, the run count has not reached the specified limit, and the client asserts it is a retriable task run. The client will be instructed to transition into a scheduled state to retry task execution.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RetryFailedTasks(BaseOrchestrationRule):\n    \"\"\"\n    Rejects failed states and schedules a retry if the retry limit has not been reached.\n\n    This rule rejects transitions into a failed state if `retries` has been\n    set, the run count has not reached the specified limit, and the client\n    asserts it is a retriable task run. The client will be instructed to\n    transition into a scheduled state to retry task execution.\n    \"\"\"\n\n    FROM_STATES = [StateType.RUNNING]\n    TO_STATES = [StateType.FAILED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        run_settings = context.run_settings\n        run_count = context.run.run_count\n        delay = run_settings.retry_delay\n\n        if isinstance(delay, list):\n            base_delay = delay[min(run_count - 1, len(delay) - 1)]\n        else:\n            base_delay = run_settings.retry_delay or 0\n\n        # guard against negative relative jitter inputs\n        if run_settings.retry_jitter_factor:\n            delay = clamped_poisson_interval(\n                base_delay, clamping_factor=run_settings.retry_jitter_factor\n            )\n        else:\n            delay = base_delay\n\n        # set by user to conditionally retry a task using @task(retry_condition_fn=...)\n        if getattr(proposed_state.state_details, \"retriable\", True) is False:\n            return\n\n        if run_settings.retries is not None and run_count &lt;= run_settings.retries:\n            retry_state = states.AwaitingRetry(\n                scheduled_time=pendulum.now(\"UTC\").add(seconds=delay),\n                message=proposed_state.message,\n                data=proposed_state.data,\n            )\n            await self.reject_transition(state=retry_state, reason=\"Retrying\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.EnqueueScheduledTasks","title":"<code>EnqueueScheduledTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Enqueues autonomous task runs when they are scheduled</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class EnqueueScheduledTasks(BaseOrchestrationRule):\n    \"\"\"\n    Enqueues autonomous task runs when they are scheduled\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.SCHEDULED]\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value():\n            # Only if task scheduling is enabled\n            return\n\n        if not validated_state:\n            # Only if the transition was valid\n            return\n\n        if context.run.flow_run_id:\n            # Only for autonomous tasks\n            return\n\n        task_run: TaskRun = TaskRun.from_orm(context.run)\n        queue = TaskQueue.for_key(task_run.task_key)\n\n        if validated_state.name == \"AwaitingRetry\":\n            await queue.retry(task_run)\n        else:\n            await queue.enqueue(task_run)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RenameReruns","title":"<code>RenameReruns</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Name the states if they have run more than once.</p> <p>In the special case where the initial state is an \"AwaitingRetry\" scheduled state, the proposed state will be renamed to \"Retrying\" instead.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RenameReruns(BaseOrchestrationRule):\n    \"\"\"\n    Name the states if they have run more than once.\n\n    In the special case where the initial state is an \"AwaitingRetry\" scheduled state,\n    the proposed state will be renamed to \"Retrying\" instead.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        run_count = context.run.run_count\n        if run_count &gt; 0:\n            if initial_state.name == \"AwaitingRetry\":\n                await self.rename_state(\"Retrying\")\n            else:\n                await self.rename_state(\"Rerunning\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CopyScheduledTime","title":"<code>CopyScheduledTime</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Ensures scheduled time is copied from scheduled states to pending states.</p> <p>If a new scheduled time has been proposed on the pending state, the scheduled time on the scheduled state will be ignored.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CopyScheduledTime(BaseOrchestrationRule):\n    \"\"\"\n    Ensures scheduled time is copied from scheduled states to pending states.\n\n    If a new scheduled time has been proposed on the pending state, the scheduled time\n    on the scheduled state will be ignored.\n    \"\"\"\n\n    FROM_STATES = [StateType.SCHEDULED]\n    TO_STATES = [StateType.PENDING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if not proposed_state.state_details.scheduled_time:\n            proposed_state.state_details.scheduled_time = (\n                initial_state.state_details.scheduled_time\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.WaitForScheduledTime","title":"<code>WaitForScheduledTime</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents transitions to running states from happening to early.</p> <p>This rule enforces that all scheduled states will only start with the machine clock used by the Prefect REST API instance. This rule will identify transitions from scheduled states that are too early and nullify them. Instead, no state will be written to the database and the client will be sent an instruction to wait for <code>delay_seconds</code> before attempting the transition again.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class WaitForScheduledTime(BaseOrchestrationRule):\n    \"\"\"\n    Prevents transitions to running states from happening to early.\n\n    This rule enforces that all scheduled states will only start with the machine clock\n    used by the Prefect REST API instance. This rule will identify transitions from scheduled\n    states that are too early and nullify them. Instead, no state will be written to the\n    database and the client will be sent an instruction to wait for `delay_seconds`\n    before attempting the transition again.\n    \"\"\"\n\n    FROM_STATES = [StateType.SCHEDULED, StateType.PENDING]\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        scheduled_time = initial_state.state_details.scheduled_time\n        if not scheduled_time:\n            return\n\n        # At this moment, we round delay to the nearest second as the API schema\n        # specifies an integer return value.\n        delay = scheduled_time - pendulum.now(\"UTC\")\n        delay_seconds = delay.in_seconds()\n        delay_seconds += round(delay.microseconds / 1e6)\n        if delay_seconds &gt; 0:\n            await self.delay_transition(\n                delay_seconds, reason=\"Scheduled time is in the future\"\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandlePausingFlows","title":"<code>HandlePausingFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Governs runs attempting to enter a Paused/Suspended state</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandlePausingFlows(BaseOrchestrationRule):\n    \"\"\"\n    Governs runs attempting to enter a Paused/Suspended state\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.PAUSED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        verb = \"suspend\" if proposed_state.name == \"Suspended\" else \"pause\"\n\n        if initial_state is None:\n            await self.abort_transition(f\"Cannot {verb} flows with no state.\")\n            return\n\n        if not initial_state.is_running():\n            await self.reject_transition(\n                state=None,\n                reason=f\"Cannot {verb} flows that are not currently running.\",\n            )\n            return\n\n        self.key = proposed_state.state_details.pause_key\n        if self.key is None:\n            # if no pause key is provided, default to a UUID\n            self.key = str(uuid4())\n\n        if self.key in context.run.empirical_policy.pause_keys:\n            await self.reject_transition(\n                state=None, reason=f\"This {verb} has already fired.\"\n            )\n            return\n\n        if proposed_state.state_details.pause_reschedule:\n            if context.run.parent_task_run_id:\n                await self.abort_transition(\n                    reason=f\"Cannot {verb} subflows.\",\n                )\n                return\n\n            if context.run.deployment_id is None:\n                await self.abort_transition(\n                    reason=f\"Cannot {verb} flows without a deployment.\",\n                )\n                return\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        updated_policy = context.run.empirical_policy.dict()\n        updated_policy[\"pause_keys\"].add(self.key)\n        context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleResumingPausedFlows","title":"<code>HandleResumingPausedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Governs runs attempting to leave a Paused state</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleResumingPausedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Governs runs attempting to leave a Paused state\n    \"\"\"\n\n    FROM_STATES = [StateType.PAUSED]\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if not (\n            proposed_state.is_running()\n            or proposed_state.is_scheduled()\n            or proposed_state.is_final()\n        ):\n            await self.reject_transition(\n                state=None,\n                reason=(\n                    f\"This run cannot transition to the {proposed_state.type} state\"\n                    f\" from the {initial_state.type} state.\"\n                ),\n            )\n            return\n\n        verb = \"suspend\" if proposed_state.name == \"Suspended\" else \"pause\"\n\n        if initial_state.state_details.pause_reschedule:\n            if not context.run.deployment_id:\n                await self.reject_transition(\n                    state=None,\n                    reason=(\n                        f\"Cannot reschedule a {proposed_state.name.lower()} flow run\"\n                        \" without a deployment.\"\n                    ),\n                )\n                return\n        pause_timeout = initial_state.state_details.pause_timeout\n        if pause_timeout and pause_timeout &lt; pendulum.now(\"UTC\"):\n            pause_timeout_failure = states.Failed(\n                message=(\n                    f\"The flow was {proposed_state.name.lower()} and never resumed.\"\n                ),\n            )\n            await self.reject_transition(\n                state=pause_timeout_failure,\n                reason=f\"The flow run {verb} has timed out and can no longer resume.\",\n            )\n            return\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        updated_policy = context.run.empirical_policy.dict()\n        updated_policy[\"resuming\"] = True\n        context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.UpdateFlowRunTrackerOnTasks","title":"<code>UpdateFlowRunTrackerOnTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Tracks the flow run attempt a task run state is associated with.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class UpdateFlowRunTrackerOnTasks(BaseOrchestrationRule):\n    \"\"\"\n    Tracks the flow run attempt a task run state is associated with.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if context.run.flow_run_id is not None:\n            self.flow_run = await context.flow_run()\n            if self.flow_run:\n                context.run.flow_run_run_count = self.flow_run.run_count\n            else:\n                raise ObjectNotFoundError(\n                    (\n                        \"Unable to read flow run associated with task run:\"\n                        f\" {context.run.id}, this flow run might have been deleted\"\n                    ),\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleTaskTerminalStateTransitions","title":"<code>HandleTaskTerminalStateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>We do not allow tasks to leave terminal states if: - The task is completed and has a persisted result - The task is going to CANCELLING / PAUSED / CRASHED</p> <p>We reset the run count when a task leaves a terminal state for a non-terminal state which resets task run retries; this is particularly relevant for flow run retries.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleTaskTerminalStateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    We do not allow tasks to leave terminal states if:\n    - The task is completed and has a persisted result\n    - The task is going to CANCELLING / PAUSED / CRASHED\n\n    We reset the run count when a task leaves a terminal state for a non-terminal state\n    which resets task run retries; this is particularly relevant for flow run retries.\n    \"\"\"\n\n    FROM_STATES = TERMINAL_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        self.original_run_count = context.run.run_count\n\n        # Do not allow runs to be marked as crashed, paused, or cancelling if already terminal\n        if proposed_state.type in {\n            StateType.CANCELLING,\n            StateType.PAUSED,\n            StateType.CRASHED,\n        }:\n            await self.abort_transition(f\"Run is already {initial_state.type.value}.\")\n            return\n\n        # Only allow departure from a happily completed state if the result is not persisted\n        if (\n            initial_state.is_completed()\n            and initial_state.data\n            and initial_state.data.get(\"type\") != \"unpersisted\"\n        ):\n            await self.reject_transition(None, \"This run is already completed.\")\n            return\n\n        if not proposed_state.is_final():\n            # Reset run count to reset retries\n            context.run.run_count = 0\n\n        # Change the name of the state to retrying if its a flow run retry\n        if proposed_state.is_running() and context.run.flow_run_id is not None:\n            self.flow_run = await context.flow_run()\n            flow_retrying = context.run.flow_run_run_count &lt; self.flow_run.run_count\n            if flow_retrying:\n                await self.rename_state(\"Retrying\")\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ):\n        # reset run count\n        context.run.run_count = self.original_run_count\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleFlowTerminalStateTransitions","title":"<code>HandleFlowTerminalStateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>We do not allow flows to leave terminal states if: - The flow is completed and has a persisted result - The flow is going to CANCELLING / PAUSED / CRASHED - The flow is going to scheduled and has no deployment</p> <p>We reset the pause metadata when a flow leaves a terminal state for a non-terminal state. This resets pause behavior during manual flow run retries.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleFlowTerminalStateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    We do not allow flows to leave terminal states if:\n    - The flow is completed and has a persisted result\n    - The flow is going to CANCELLING / PAUSED / CRASHED\n    - The flow is going to scheduled and has no deployment\n\n    We reset the pause metadata when a flow leaves a terminal state for a non-terminal\n    state. This resets pause behavior during manual flow run retries.\n    \"\"\"\n\n    FROM_STATES = TERMINAL_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        self.original_flow_policy = context.run.empirical_policy.dict()\n\n        # Do not allow runs to be marked as crashed, paused, or cancelling if already terminal\n        if proposed_state.type in {\n            StateType.CANCELLING,\n            StateType.PAUSED,\n            StateType.CRASHED,\n        }:\n            await self.abort_transition(\n                f\"Run is already in terminal state {initial_state.type.value}.\"\n            )\n            return\n\n        # Only allow departure from a happily completed state if the result is not\n        # persisted and the a rerun is being proposed\n        if (\n            initial_state.is_completed()\n            and not proposed_state.is_final()\n            and initial_state.data\n            and initial_state.data.get(\"type\") != \"unpersisted\"\n        ):\n            await self.reject_transition(None, \"Run is already COMPLETED.\")\n            return\n\n        # Do not allows runs to be rescheduled without a deployment\n        if proposed_state.is_scheduled() and not context.run.deployment_id:\n            await self.abort_transition(\n                \"Cannot reschedule a run without an associated deployment.\"\n            )\n            return\n\n        if not proposed_state.is_final():\n            # Reset pause metadata when leaving a terminal state\n            api_version = context.parameters.get(\"api-version\", None)\n            if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n                updated_policy = context.run.empirical_policy.dict()\n                updated_policy[\"resuming\"] = False\n                updated_policy[\"pause_keys\"] = set()\n                context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ):\n        context.run.empirical_policy = core.FlowRunPolicy(**self.original_flow_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventPendingTransitions","title":"<code>PreventPendingTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents transitions to PENDING.</p> <p>This rule is only used for flow runs.</p> <p>This is intended to prevent race conditions during duplicate submissions of runs. Before a run is submitted to its execution environment, it should be placed in a PENDING state. If two workers attempt to submit the same run, one of them should encounter a PENDING -&gt; PENDING transition and abort orchestration of the run.</p> <p>Similarly, if the execution environment starts quickly the run may be in a RUNNING state when the second worker attempts the PENDING transition. We deny these state changes as well to prevent duplicate submission. If a run has transitioned to a RUNNING state a worker should not attempt to submit it again unless it has moved into a terminal state.</p> <p>CANCELLING and CANCELLED runs should not be allowed to transition to PENDING. For re-runs of deployed runs, they should transition to SCHEDULED first. For re-runs of ad-hoc runs, they should transition directly to RUNNING.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventPendingTransitions(BaseOrchestrationRule):\n    \"\"\"\n    Prevents transitions to PENDING.\n\n    This rule is only used for flow runs.\n\n    This is intended to prevent race conditions during duplicate submissions of runs.\n    Before a run is submitted to its execution environment, it should be placed in a\n    PENDING state. If two workers attempt to submit the same run, one of them should\n    encounter a PENDING -&gt; PENDING transition and abort orchestration of the run.\n\n    Similarly, if the execution environment starts quickly the run may be in a RUNNING\n    state when the second worker attempts the PENDING transition. We deny these state\n    changes as well to prevent duplicate submission. If a run has transitioned to a\n    RUNNING state a worker should not attempt to submit it again unless it has moved\n    into a terminal state.\n\n    CANCELLING and CANCELLED runs should not be allowed to transition to PENDING.\n    For re-runs of deployed runs, they should transition to SCHEDULED first.\n    For re-runs of ad-hoc runs, they should transition directly to RUNNING.\n    \"\"\"\n\n    FROM_STATES = [\n        StateType.PENDING,\n        StateType.CANCELLING,\n        StateType.RUNNING,\n        StateType.CANCELLED,\n    ]\n    TO_STATES = [StateType.PENDING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        await self.abort_transition(\n            reason=(\n                f\"This run is in a {initial_state.type.name} state and cannot\"\n                \" transition to a PENDING state.\"\n            )\n        )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventRunningTasksFromStoppedFlows","title":"<code>PreventRunningTasksFromStoppedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents running tasks from stopped flows.</p> <p>A running state implies execution, but also the converse. This rule ensures that a flow's tasks cannot be run unless the flow is also running.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventRunningTasksFromStoppedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Prevents running tasks from stopped flows.\n\n    A running state implies execution, but also the converse. This rule ensures that a\n    flow's tasks cannot be run unless the flow is also running.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        flow_run = await context.flow_run()\n        if flow_run is not None:\n            if flow_run.state is None:\n                await self.abort_transition(\n                    reason=\"The enclosing flow must be running to begin task execution.\"\n                )\n            elif flow_run.state.type == StateType.PAUSED:\n                # Use the flow run's Paused state details to preserve data like\n                # timeouts.\n                paused_state = states.Paused(\n                    name=\"NotReady\",\n                    pause_expiration_time=flow_run.state.state_details.pause_timeout,\n                    reschedule=flow_run.state.state_details.pause_reschedule,\n                )\n                await self.reject_transition(\n                    state=paused_state,\n                    reason=(\n                        \"The flow is paused, new tasks can execute after resuming flow\"\n                        f\" run: {flow_run.id}.\"\n                    ),\n                )\n            elif not flow_run.state.type == StateType.RUNNING:\n                # task runners should abort task run execution\n                await self.abort_transition(\n                    reason=(\n                        \"The enclosing flow must be running to begin task execution.\"\n                    ),\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.EnforceCancellingToCancelledTransition","title":"<code>EnforceCancellingToCancelledTransition</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects transitions from Cancelling to any terminal state except for Cancelled.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class EnforceCancellingToCancelledTransition(BaseOrchestrationRule):\n    \"\"\"\n    Rejects transitions from Cancelling to any terminal state except for Cancelled.\n    \"\"\"\n\n    FROM_STATES = {StateType.CANCELLED, StateType.CANCELLING}\n    TO_STATES = ALL_ORCHESTRATION_STATES - {StateType.CANCELLED}\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        await self.reject_transition(\n            state=None,\n            reason=(\n                \"Cannot transition flows that are cancelling to a state other \"\n                \"than Cancelled.\"\n            ),\n        )\n        return\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.BypassCancellingFlowRunsWithNoInfra","title":"<code>BypassCancellingFlowRunsWithNoInfra</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled, if the flow run has no associated infrastructure process ID. Also Rejects transitions from Paused to Cancelling if the Paused state's details indicates the flow run has been suspended, exiting the flow and tearing down infra.</p> <p>The <code>Cancelling</code> state is used to clean up infrastructure. If there is not infrastructure to clean up, we can transition directly to <code>Cancelled</code>. Runs that are <code>Resuming</code> are in a <code>Scheduled</code> state that were previously <code>Suspended</code> and do not yet have infrastructure.</p> <p>Runs that are <code>AwaitingRetry</code> are a <code>Scheduled</code> state that may have associated infrastructure.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class BypassCancellingFlowRunsWithNoInfra(BaseOrchestrationRule):\n    \"\"\"Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled,\n    if the flow run has no associated infrastructure process ID. Also Rejects transitions from\n    Paused to Cancelling if the Paused state's details indicates the flow run has been suspended,\n    exiting the flow and tearing down infra.\n\n    The `Cancelling` state is used to clean up infrastructure. If there is not infrastructure\n    to clean up, we can transition directly to `Cancelled`. Runs that are `Resuming` are in a\n    `Scheduled` state that were previously `Suspended` and do not yet have infrastructure.\n\n    Runs that are `AwaitingRetry` are a `Scheduled` state that may have associated infrastructure.\n    \"\"\"\n\n    FROM_STATES = {StateType.SCHEDULED, StateType.PAUSED}\n    TO_STATES = {StateType.CANCELLING}\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state.type == states.StateType.SCHEDULED\n            and not context.run.infrastructure_pid\n            or initial_state.name == \"Resuming\"\n        ):\n            await self.reject_transition(\n                state=states.Cancelled(),\n                reason=\"Scheduled flow run has no infrastructure to terminate.\",\n            )\n        elif (\n            initial_state.type == states.StateType.PAUSED\n            and initial_state.state_details.pause_reschedule\n        ):\n            await self.reject_transition(\n                state=states.Cancelled(),\n                reason=\"Suspended flow run has no infrastructure to terminate.\",\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventDuplicateTransitions","title":"<code>PreventDuplicateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevent duplicate transitions from being made right after one another.</p> <p>This rule allows for clients to set an optional transition_id on a state. If the run's next transition has the same transition_id, the transition will be rejected and the existing state will be returned.</p> <p>This allows for clients to make state transition requests without worrying about the following case: - A client making a state transition request - The server accepts transition and commits the transition - The client is unable to receive the response and retries the request</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventDuplicateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    Prevent duplicate transitions from being made right after one another.\n\n    This rule allows for clients to set an optional transition_id on a state. If the\n    run's next transition has the same transition_id, the transition will be\n    rejected and the existing state will be returned.\n\n    This allows for clients to make state transition requests without worrying about\n    the following case:\n    - A client making a state transition request\n    - The server accepts transition and commits the transition\n    - The client is unable to receive the response and retries the request\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state is None\n            or proposed_state is None\n            or initial_state.state_details is None\n            or proposed_state.state_details is None\n        ):\n            return\n\n        initial_transition_id = getattr(\n            initial_state.state_details, \"transition_id\", None\n        )\n        proposed_transition_id = getattr(\n            proposed_state.state_details, \"transition_id\", None\n        )\n        if (\n            initial_transition_id is not None\n            and proposed_transition_id is not None\n            and initial_transition_id == proposed_transition_id\n        ):\n            await self.reject_transition(\n                # state=None will return the initial (current) state\n                state=None,\n                reason=\"This run has already made this state transition.\",\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/","title":"server.orchestration.global_policy","text":""},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy","title":"<code>prefect.server.orchestration.global_policy</code>","text":"<p>Bookkeeping logic that fires on every state transition.</p> <p>For clarity, <code>GlobalFlowpolicy</code> and <code>GlobalTaskPolicy</code> contain all transition logic implemented using <code>BaseUniversalTransform</code>. None of these operations modify state, and regardless of what orchestration Prefect REST API might enforce on a transition, the global policies contain Prefect's necessary bookkeeping. Because these transforms record information about the validated state committed to the state database, they should be the most deeply nested contexts in orchestration loop.</p>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.GlobalFlowPolicy","title":"<code>GlobalFlowPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Global transforms that run against flow-run-state transitions in priority order.</p> <p>These transforms are intended to run immediately before and after a state transition is validated.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class GlobalFlowPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Global transforms that run against flow-run-state transitions in priority order.\n\n    These transforms are intended to run immediately before and after a state transition\n    is validated.\n    \"\"\"\n\n    def priority():\n        return COMMON_GLOBAL_TRANSFORMS() + [\n            UpdateSubflowParentTask,\n            UpdateSubflowStateDetails,\n            IncrementFlowRunCount,\n            RemoveResumingIndicator,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.GlobalTaskPolicy","title":"<code>GlobalTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Global transforms that run against task-run-state transitions in priority order.</p> <p>These transforms are intended to run immediately before and after a state transition is validated.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class GlobalTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Global transforms that run against task-run-state transitions in priority order.\n\n    These transforms are intended to run immediately before and after a state transition\n    is validated.\n    \"\"\"\n\n    def priority():\n        return COMMON_GLOBAL_TRANSFORMS() + [\n            IncrementTaskRunCount,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateType","title":"<code>SetRunStateType</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Updates the state type of a run on a state transition.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateType(BaseUniversalTransform):\n    \"\"\"\n    Updates the state type of a run on a state transition.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's type\n        context.run.state_type = context.proposed_state.type\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateName","title":"<code>SetRunStateName</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Updates the state name of a run on a state transition.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateName(BaseUniversalTransform):\n    \"\"\"\n    Updates the state name of a run on a state transition.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's name\n        context.run.state_name = context.proposed_state.name\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetStartTime","title":"<code>SetStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run enters a running state for the first time.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetStartTime(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run enters a running state for the first time.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state and no start time is set...\n        if context.proposed_state.is_running() and context.run.start_time is None:\n            # set the start time\n            context.run.start_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateTimestamp","title":"<code>SetRunStateTimestamp</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run changes states.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateTimestamp(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run changes states.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's timestamp\n        context.run.state_timestamp = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetEndTime","title":"<code>SetEndTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run enters a terminal state.</p> <p>With normal client usage, a run will not transition out of a terminal state. However, it's possible to force these transitions manually via the API. While leaving a terminal state, the end time will be unset.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetEndTime(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run enters a terminal state.\n\n    With normal client usage, a run will not transition out of a terminal state.\n    However, it's possible to force these transitions manually via the API. While\n    leaving a terminal state, the end time will be unset.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if exiting a final state for a non-final state...\n        if (\n            context.initial_state\n            and context.initial_state.is_final()\n            and not context.proposed_state.is_final()\n        ):\n            # clear the end time\n            context.run.end_time = None\n\n        # if entering a final state...\n        if context.proposed_state.is_final():\n            # if the run has a start time and no end time, give it one\n            if context.run.start_time and not context.run.end_time:\n                context.run.end_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementRunTime","title":"<code>IncrementRunTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the amount of time a run spends in the running state.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementRunTime(BaseUniversalTransform):\n    \"\"\"\n    Records the amount of time a run spends in the running state.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if exiting a running state...\n        if context.initial_state and context.initial_state.is_running():\n            # increment the run time by the time spent in the previous state\n            context.run.total_run_time += (\n                context.proposed_state.timestamp - context.initial_state.timestamp\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementFlowRunCount","title":"<code>IncrementFlowRunCount</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the number of times a run enters a running state. For use with retries.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementFlowRunCount(BaseUniversalTransform):\n    \"\"\"\n    Records the number of times a run enters a running state. For use with retries.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state...\n        if context.proposed_state.is_running():\n            # do not increment the run count if resuming a paused flow\n            api_version = context.parameters.get(\"api-version\", None)\n            if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n                if context.run.empirical_policy.resuming:\n                    return\n\n            # increment the run count\n            context.run.run_count += 1\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.RemoveResumingIndicator","title":"<code>RemoveResumingIndicator</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Removes the indicator on a flow run that marks it as resuming.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class RemoveResumingIndicator(BaseUniversalTransform):\n    \"\"\"\n    Removes the indicator on a flow run that marks it as resuming.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        proposed_state = context.proposed_state\n\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n            if proposed_state.is_running() or proposed_state.is_final():\n                if context.run.empirical_policy.resuming:\n                    updated_policy = context.run.empirical_policy.dict()\n                    updated_policy[\"resuming\"] = False\n                    context.run.empirical_policy = FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementTaskRunCount","title":"<code>IncrementTaskRunCount</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the number of times a run enters a running state. For use with retries.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementTaskRunCount(BaseUniversalTransform):\n    \"\"\"\n    Records the number of times a run enters a running state. For use with retries.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state...\n        if context.proposed_state.is_running():\n            # increment the run count\n            context.run.run_count += 1\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetExpectedStartTime","title":"<code>SetExpectedStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Estimates the time a state is expected to start running if not set.</p> <p>For scheduled states, this estimate is simply the scheduled time. For other states, this is set to the time the proposed state was created by Prefect.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetExpectedStartTime(BaseUniversalTransform):\n    \"\"\"\n    Estimates the time a state is expected to start running if not set.\n\n    For scheduled states, this estimate is simply the scheduled time. For other states,\n    this is set to the time the proposed state was created by Prefect.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # set expected start time if this is the first state\n        if not context.run.expected_start_time:\n            if context.proposed_state.is_scheduled():\n                context.run.expected_start_time = (\n                    context.proposed_state.state_details.scheduled_time\n                )\n            else:\n                context.run.expected_start_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetNextScheduledStartTime","title":"<code>SetNextScheduledStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the scheduled time on a run.</p> <p>When a run enters a scheduled state, <code>run.next_scheduled_start_time</code> is set to the state's scheduled time. When leaving a scheduled state, <code>run.next_scheduled_start_time</code> is unset.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetNextScheduledStartTime(BaseUniversalTransform):\n    \"\"\"\n    Records the scheduled time on a run.\n\n    When a run enters a scheduled state, `run.next_scheduled_start_time` is set to\n    the state's scheduled time. When leaving a scheduled state,\n    `run.next_scheduled_start_time` is unset.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # remove the next scheduled start time if exiting a scheduled state\n        if context.initial_state and context.initial_state.is_scheduled():\n            context.run.next_scheduled_start_time = None\n\n        # set next scheduled start time if entering a scheduled state\n        if context.proposed_state.is_scheduled():\n            context.run.next_scheduled_start_time = (\n                context.proposed_state.state_details.scheduled_time\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateSubflowParentTask","title":"<code>UpdateSubflowParentTask</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Whenever a subflow changes state, it must update its parent task run's state.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateSubflowParentTask(BaseUniversalTransform):\n    \"\"\"\n    Whenever a subflow changes state, it must update its parent task run's state.\n    \"\"\"\n\n    async def after_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # only applies to flow runs with a parent task run id\n        if context.run.parent_task_run_id is not None:\n            # avoid mutation of the flow run state\n            subflow_parent_task_state = context.validated_state.copy(\n                reset_fields=True,\n                include={\n                    \"type\",\n                    \"timestamp\",\n                    \"name\",\n                    \"message\",\n                    \"state_details\",\n                    \"data\",\n                },\n            )\n\n            # set the task's \"child flow run id\" to be the subflow run id\n            subflow_parent_task_state.state_details.child_flow_run_id = context.run.id\n\n            await models.task_runs.set_task_run_state(\n                session=context.session,\n                task_run_id=context.run.parent_task_run_id,\n                state=subflow_parent_task_state,\n                force=True,\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateSubflowStateDetails","title":"<code>UpdateSubflowStateDetails</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Update a child subflow state's references to a corresponding tracking task run id in the parent flow run</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateSubflowStateDetails(BaseUniversalTransform):\n    \"\"\"\n    Update a child subflow state's references to a corresponding tracking task run id\n    in the parent flow run\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # only applies to flow runs with a parent task run id\n        if context.run.parent_task_run_id is not None:\n            context.proposed_state.state_details.task_run_id = (\n                context.run.parent_task_run_id\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateStateDetails","title":"<code>UpdateStateDetails</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Update a state's references to a corresponding flow- or task- run.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateStateDetails(BaseUniversalTransform):\n    \"\"\"\n    Update a state's references to a corresponding flow- or task- run.\n    \"\"\"\n\n    async def before_transition(\n        self,\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        if isinstance(context, FlowOrchestrationContext):\n            flow_run = await context.flow_run()\n            context.proposed_state.state_details.flow_run_id = flow_run.id\n\n        elif isinstance(context, TaskOrchestrationContext):\n            task_run = await context.task_run()\n            context.proposed_state.state_details.flow_run_id = task_run.flow_run_id\n            context.proposed_state.state_details.task_run_id = task_run.id\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/","title":"server.orchestration.policies","text":""},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies","title":"<code>prefect.server.orchestration.policies</code>","text":"<p>Policies are collections of orchestration rules and transforms.</p> <p>Prefect implements (most) orchestration with logic that governs a Prefect flow or task changing state. Policies organize of orchestration logic both to provide an ordering mechanism as well as provide observability into the orchestration process.</p> <p>While Prefect's orchestration rules can gracefully run independently of one another, ordering can still have an impact on the observed behavior of the system. For example, it makes no sense to secure a concurrency slot for a run if a cached state exists. Furthermore, policies, provide a mechanism to configure and observe exactly what logic will fire against a transition.</p>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy","title":"<code>BaseOrchestrationPolicy</code>","text":"<p>               Bases: <code>ABC</code></p> <p>An abstract base class used to organize orchestration rules in priority order.</p> <p>Different collections of orchestration rules might be used to govern various kinds of transitions. For example, flow-run states and task-run states might require different orchestration logic.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>class BaseOrchestrationPolicy(ABC):\n    \"\"\"\n    An abstract base class used to organize orchestration rules in priority order.\n\n    Different collections of orchestration rules might be used to govern various kinds\n    of transitions. For example, flow-run states and task-run states might require\n    different orchestration logic.\n    \"\"\"\n\n    @staticmethod\n    @abstractmethod\n    def priority():\n        \"\"\"\n        A list of orchestration rules in priority order.\n        \"\"\"\n\n        return []\n\n    @classmethod\n    def compile_transition_rules(cls, from_state=None, to_state=None):\n        \"\"\"\n        Returns rules in policy that are valid for the specified state transition.\n        \"\"\"\n\n        transition_rules = []\n        for rule in cls.priority():\n            if from_state in rule.FROM_STATES and to_state in rule.TO_STATES:\n                transition_rules.append(rule)\n        return transition_rules\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy.priority","title":"<code>priority</code>  <code>abstractmethod</code> <code>staticmethod</code>","text":"<p>A list of orchestration rules in priority order.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>@staticmethod\n@abstractmethod\ndef priority():\n    \"\"\"\n    A list of orchestration rules in priority order.\n    \"\"\"\n\n    return []\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy.compile_transition_rules","title":"<code>compile_transition_rules</code>  <code>classmethod</code>","text":"<p>Returns rules in policy that are valid for the specified state transition.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>@classmethod\ndef compile_transition_rules(cls, from_state=None, to_state=None):\n    \"\"\"\n    Returns rules in policy that are valid for the specified state transition.\n    \"\"\"\n\n    transition_rules = []\n    for rule in cls.priority():\n        if from_state in rule.FROM_STATES and to_state in rule.TO_STATES:\n            transition_rules.append(rule)\n    return transition_rules\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/","title":"server.orchestration.rules","text":""},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules","title":"<code>prefect.server.orchestration.rules</code>","text":"<p>Prefect's flow and task-run orchestration machinery.</p> <p>This module contains all the core concepts necessary to implement Prefect's state orchestration engine. These states correspond to intuitive descriptions of all the points that a Prefect flow or task can observe executing user code and intervene, if necessary. A detailed description of states can be found in our concept documentation.</p> <p>Prefect's orchestration engine operates under the assumption that no governed user code will execute without first requesting Prefect REST API validate a change in state and record metadata about the run. With all attempts to run user code being checked against a Prefect instance, the Prefect REST API database becomes the unambiguous source of truth for managing the execution of complex interacting workflows. Orchestration rules can be implemented as discrete units of logic that operate against each state transition and can be fully observable, extensible, and customizable -- all without needing to store or parse a single line of user code.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext","title":"<code>OrchestrationContext</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for a state transition, governed by orchestration rules.</p> Note <p>An <code>OrchestrationContext</code> should not be instantiated directly, instead use the flow- or task- specific subclasses, <code>FlowOrchestrationContext</code> and <code>TaskOrchestrationContext</code>.</p> <p>When a flow- or task- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>OrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <code>Optional[Union[Session, AsyncSession]]</code> <p>a SQLAlchemy database session</p> <code>initial_state</code> <code>Optional[State]</code> <p>the initial state of a run</p> <code>proposed_state</code> <code>Optional[State]</code> <p>the proposed state a run is transitioning into</p> <code>validated_state</code> <code>Optional[State]</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>List[str]</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>List[str]</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>SetStateStatus</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>StateResponseDetails</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class OrchestrationContext(PrefectBaseModel):\n    \"\"\"\n    A container for a state transition, governed by orchestration rules.\n\n    Note:\n        An `OrchestrationContext` should not be instantiated directly, instead\n        use the flow- or task- specific subclasses, `FlowOrchestrationContext` and\n        `TaskOrchestrationContext`.\n\n    When a flow- or task- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `OrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    class Config:\n        arbitrary_types_allowed = True\n\n    session: Optional[Union[sa.orm.Session, AsyncSession]] = ...\n    initial_state: Optional[states.State] = ...\n    proposed_state: Optional[states.State] = ...\n    validated_state: Optional[states.State]\n    rule_signature: List[str] = Field(default_factory=list)\n    finalization_signature: List[str] = Field(default_factory=list)\n    response_status: SetStateStatus = Field(default=SetStateStatus.ACCEPT)\n    response_details: StateResponseDetails = Field(default_factory=StateAcceptDetails)\n    orchestration_error: Optional[Exception] = Field(default=None)\n    parameters: Dict[Any, Any] = Field(default_factory=dict)\n\n    @property\n    def initial_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.initial_state` if it exists.\"\"\"\n\n        return self.initial_state.type if self.initial_state else None\n\n    @property\n    def proposed_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.proposed_state` if it exists.\"\"\"\n\n        return self.proposed_state.type if self.proposed_state else None\n\n    @property\n    def validated_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.validated_state` if it exists.\"\"\"\n        return self.validated_state.type if self.validated_state else None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Returns:\n            A mutation-safe copy of the `OrchestrationContext`\n        \"\"\"\n\n        safe_copy = self.copy()\n\n        safe_copy.initial_state = (\n            self.initial_state.copy() if self.initial_state else None\n        )\n        safe_copy.proposed_state = (\n            self.proposed_state.copy() if self.proposed_state else None\n        )\n        safe_copy.validated_state = (\n            self.validated_state.copy() if self.validated_state else None\n        )\n        safe_copy.parameters = self.parameters.copy()\n        return safe_copy\n\n    def entry_context(self):\n        \"\"\"\n        A convenience method that generates input parameters for orchestration rules.\n\n        An `OrchestrationContext` defines a state transition that is managed by\n        orchestration rules which can fire hooks before a transition has been committed\n        to the database. These hooks have a consistent interface which can be generated\n        with this method.\n        \"\"\"\n\n        safe_context = self.safe_copy()\n        return safe_context.initial_state, safe_context.proposed_state, safe_context\n\n    def exit_context(self):\n        \"\"\"\n        A convenience method that generates input parameters for orchestration rules.\n\n        An `OrchestrationContext` defines a state transition that is managed by\n        orchestration rules which can fire hooks after a transition has been committed\n        to the database. These hooks have a consistent interface which can be generated\n        with this method.\n        \"\"\"\n\n        safe_context = self.safe_copy()\n        return safe_context.initial_state, safe_context.validated_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.initial_state_type","title":"<code>initial_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.initial_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.proposed_state_type","title":"<code>proposed_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.proposed_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.validated_state_type","title":"<code>validated_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.validated_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of the <code>OrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Returns:\n        A mutation-safe copy of the `OrchestrationContext`\n    \"\"\"\n\n    safe_copy = self.copy()\n\n    safe_copy.initial_state = (\n        self.initial_state.copy() if self.initial_state else None\n    )\n    safe_copy.proposed_state = (\n        self.proposed_state.copy() if self.proposed_state else None\n    )\n    safe_copy.validated_state = (\n        self.validated_state.copy() if self.validated_state else None\n    )\n    safe_copy.parameters = self.parameters.copy()\n    return safe_copy\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.entry_context","title":"<code>entry_context</code>","text":"<p>A convenience method that generates input parameters for orchestration rules.</p> <p>An <code>OrchestrationContext</code> defines a state transition that is managed by orchestration rules which can fire hooks before a transition has been committed to the database. These hooks have a consistent interface which can be generated with this method.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def entry_context(self):\n    \"\"\"\n    A convenience method that generates input parameters for orchestration rules.\n\n    An `OrchestrationContext` defines a state transition that is managed by\n    orchestration rules which can fire hooks before a transition has been committed\n    to the database. These hooks have a consistent interface which can be generated\n    with this method.\n    \"\"\"\n\n    safe_context = self.safe_copy()\n    return safe_context.initial_state, safe_context.proposed_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.exit_context","title":"<code>exit_context</code>","text":"<p>A convenience method that generates input parameters for orchestration rules.</p> <p>An <code>OrchestrationContext</code> defines a state transition that is managed by orchestration rules which can fire hooks after a transition has been committed to the database. These hooks have a consistent interface which can be generated with this method.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def exit_context(self):\n    \"\"\"\n    A convenience method that generates input parameters for orchestration rules.\n\n    An `OrchestrationContext` defines a state transition that is managed by\n    orchestration rules which can fire hooks after a transition has been committed\n    to the database. These hooks have a consistent interface which can be generated\n    with this method.\n    \"\"\"\n\n    safe_context = self.safe_copy()\n    return safe_context.initial_state, safe_context.validated_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext","title":"<code>FlowOrchestrationContext</code>","text":"<p>               Bases: <code>OrchestrationContext</code></p> <p>A container for a flow run state transition, governed by orchestration rules.</p> <p>When a flow- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>FlowOrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <p>a SQLAlchemy database session</p> <code>run</code> <code>Any</code> <p>the flow run attempting to change state</p> <code>initial_state</code> <code>Any</code> <p>the initial state of the run</p> <code>proposed_state</code> <code>Any</code> <p>the proposed state the run is transitioning into</p> <code>validated_state</code> <code>Any</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>Any</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>Any</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>Any</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>Any</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>run</code> <p>the flow run attempting to change state</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class FlowOrchestrationContext(OrchestrationContext):\n    \"\"\"\n    A container for a flow run state transition, governed by orchestration rules.\n\n    When a flow- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `FlowOrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        run: the flow run attempting to change state\n        initial_state: the initial state of the run\n        proposed_state: the proposed state the run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        run: the flow run attempting to change state\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    # run: db.FlowRun = ...\n    run: Any = ...\n\n    @inject_db\n    async def validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        \"\"\"\n        Validates a proposed state by committing it to the database.\n\n        After the `FlowOrchestrationContext` is governed by orchestration rules, the\n        proposed state can be validated: the proposed state is added to the current\n        SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n        state. The state on the run is set to the validated state as well.\n\n        If the proposed state is `None` when this method is called, no state will be\n        written and `self.validated_state` will be set to the run's current state.\n\n        Returns:\n            None\n        \"\"\"\n        # (circular import)\n        from prefect.server.api.server import is_client_retryable_exception\n\n        try:\n            await self._validate_proposed_state()\n            return\n        except Exception as exc:\n            logger.exception(\"Encountered error during state validation\")\n            self.proposed_state = None\n\n            if is_client_retryable_exception(exc):\n                # Do not capture retryable database exceptions, this exception will be\n                # raised as a 503 in the API layer\n                raise\n\n            reason = f\"Error validating state: {exc!r}\"\n            self.response_status = SetStateStatus.ABORT\n            self.response_details = StateAbortDetails(reason=reason)\n\n    @inject_db\n    async def _validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        if self.proposed_state is None:\n            validated_orm_state = self.run.state\n            # We cannot access `self.run.state.data` directly for unknown reasons\n            state_data = (\n                (\n                    await artifacts.read_artifact(\n                        self.session, self.run.state.result_artifact_id\n                    )\n                ).data\n                if self.run.state.result_artifact_id\n                else None\n            )\n        else:\n            state_payload = self.proposed_state.dict(shallow=True)\n            state_data = state_payload.pop(\"data\", None)\n\n            if state_data is not None and not (\n                isinstance(state_data, dict) and state_data.get(\"type\") == \"unpersisted\"\n            ):\n                state_result_artifact = core.Artifact.from_result(state_data)\n                state_result_artifact.flow_run_id = self.run.id\n                await artifacts.create_artifact(self.session, state_result_artifact)\n                state_payload[\"result_artifact_id\"] = state_result_artifact.id\n\n            validated_orm_state = db.FlowRunState(\n                flow_run_id=self.run.id,\n                **state_payload,\n            )\n\n        self.session.add(validated_orm_state)\n        self.run.set_state(validated_orm_state)\n\n        await self.session.flush()\n        if validated_orm_state:\n            self.validated_state = states.State.from_orm_without_result(\n                validated_orm_state, with_data=state_data\n            )\n        else:\n            self.validated_state = None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Note:\n            `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n        Returns:\n            A mutation-safe copy of `FlowOrchestrationContext`\n        \"\"\"\n\n        return super().safe_copy()\n\n    @property\n    def run_settings(self) -&gt; Dict:\n        \"\"\"Run-level settings used to orchestrate the state transition.\"\"\"\n\n        return self.run.empirical_policy\n\n    async def task_run(self):\n        return None\n\n    async def flow_run(self):\n        return self.run\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.run_settings","title":"<code>run_settings: Dict</code>  <code>property</code>","text":"<p>Run-level settings used to orchestrate the state transition.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.validate_proposed_state","title":"<code>validate_proposed_state</code>  <code>async</code>","text":"<p>Validates a proposed state by committing it to the database.</p> <p>After the <code>FlowOrchestrationContext</code> is governed by orchestration rules, the proposed state can be validated: the proposed state is added to the current SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed state. The state on the run is set to the validated state as well.</p> <p>If the proposed state is <code>None</code> when this method is called, no state will be written and <code>self.validated_state</code> will be set to the run's current state.</p> <p>Returns:</p> Type Description <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>@inject_db\nasync def validate_proposed_state(\n    self,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Validates a proposed state by committing it to the database.\n\n    After the `FlowOrchestrationContext` is governed by orchestration rules, the\n    proposed state can be validated: the proposed state is added to the current\n    SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n    state. The state on the run is set to the validated state as well.\n\n    If the proposed state is `None` when this method is called, no state will be\n    written and `self.validated_state` will be set to the run's current state.\n\n    Returns:\n        None\n    \"\"\"\n    # (circular import)\n    from prefect.server.api.server import is_client_retryable_exception\n\n    try:\n        await self._validate_proposed_state()\n        return\n    except Exception as exc:\n        logger.exception(\"Encountered error during state validation\")\n        self.proposed_state = None\n\n        if is_client_retryable_exception(exc):\n            # Do not capture retryable database exceptions, this exception will be\n            # raised as a 503 in the API layer\n            raise\n\n        reason = f\"Error validating state: {exc!r}\"\n        self.response_status = SetStateStatus.ABORT\n        self.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> Note <p><code>self.run</code> is an ORM model, and even when copied is unsafe to mutate</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of <code>FlowOrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Note:\n        `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n    Returns:\n        A mutation-safe copy of `FlowOrchestrationContext`\n    \"\"\"\n\n    return super().safe_copy()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext","title":"<code>TaskOrchestrationContext</code>","text":"<p>               Bases: <code>OrchestrationContext</code></p> <p>A container for a task run state transition, governed by orchestration rules.</p> <p>When a task- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>TaskOrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <p>a SQLAlchemy database session</p> <code>run</code> <code>Any</code> <p>the task run attempting to change state</p> <code>initial_state</code> <code>Any</code> <p>the initial state of the run</p> <code>proposed_state</code> <code>Any</code> <p>the proposed state the run is transitioning into</p> <code>validated_state</code> <code>Any</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>Any</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>Any</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>Any</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>Any</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>run</code> <p>the task run attempting to change state</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class TaskOrchestrationContext(OrchestrationContext):\n    \"\"\"\n    A container for a task run state transition, governed by orchestration rules.\n\n    When a task- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `TaskOrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        run: the task run attempting to change state\n        initial_state: the initial state of the run\n        proposed_state: the proposed state the run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        run: the task run attempting to change state\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    # run: db.TaskRun = ...\n    run: Any = ...\n\n    @inject_db\n    async def validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        \"\"\"\n        Validates a proposed state by committing it to the database.\n\n        After the `TaskOrchestrationContext` is governed by orchestration rules, the\n        proposed state can be validated: the proposed state is added to the current\n        SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n        state. The state on the run is set to the validated state as well.\n\n        If the proposed state is `None` when this method is called, no state will be\n        written and `self.validated_state` will be set to the run's current state.\n\n        Returns:\n            None\n        \"\"\"\n        # (circular import)\n        from prefect.server.api.server import is_client_retryable_exception\n\n        try:\n            await self._validate_proposed_state()\n            return\n        except Exception as exc:\n            logger.exception(\"Encountered error during state validation\")\n            self.proposed_state = None\n\n            if is_client_retryable_exception(exc):\n                # Do not capture retryable database exceptions, this exception will be\n                # raised as a 503 in the API layer\n                raise\n\n            reason = f\"Error validating state: {exc!r}\"\n            self.response_status = SetStateStatus.ABORT\n            self.response_details = StateAbortDetails(reason=reason)\n\n    @inject_db\n    async def _validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        if self.proposed_state is None:\n            validated_orm_state = self.run.state\n            # We cannot access `self.run.state.data` directly for unknown reasons\n            state_data = (\n                (\n                    await artifacts.read_artifact(\n                        self.session, self.run.state.result_artifact_id\n                    )\n                ).data\n                if self.run.state.result_artifact_id\n                else None\n            )\n        else:\n            state_payload = self.proposed_state.dict(shallow=True)\n            state_data = state_payload.pop(\"data\", None)\n\n            if state_data is not None and not (\n                isinstance(state_data, dict) and state_data.get(\"type\") == \"unpersisted\"\n            ):\n                state_result_artifact = core.Artifact.from_result(state_data)\n                state_result_artifact.task_run_id = self.run.id\n\n                if self.run.flow_run_id is not None:\n                    flow_run = await self.flow_run()\n                    state_result_artifact.flow_run_id = flow_run.id\n\n                await artifacts.create_artifact(self.session, state_result_artifact)\n                state_payload[\"result_artifact_id\"] = state_result_artifact.id\n\n            validated_orm_state = db.TaskRunState(\n                task_run_id=self.run.id,\n                **state_payload,\n            )\n\n        self.session.add(validated_orm_state)\n        self.run.set_state(validated_orm_state)\n\n        await self.session.flush()\n        if validated_orm_state:\n            self.validated_state = states.State.from_orm_without_result(\n                validated_orm_state, with_data=state_data\n            )\n        else:\n            self.validated_state = None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Note:\n            `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n        Returns:\n            A mutation-safe copy of `TaskOrchestrationContext`\n        \"\"\"\n\n        return super().safe_copy()\n\n    @property\n    def run_settings(self) -&gt; Dict:\n        \"\"\"Run-level settings used to orchestrate the state transition.\"\"\"\n\n        return self.run.empirical_policy\n\n    async def task_run(self):\n        return self.run\n\n    async def flow_run(self):\n        return await flow_runs.read_flow_run(\n            session=self.session,\n            flow_run_id=self.run.flow_run_id,\n        )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.run_settings","title":"<code>run_settings: Dict</code>  <code>property</code>","text":"<p>Run-level settings used to orchestrate the state transition.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.validate_proposed_state","title":"<code>validate_proposed_state</code>  <code>async</code>","text":"<p>Validates a proposed state by committing it to the database.</p> <p>After the <code>TaskOrchestrationContext</code> is governed by orchestration rules, the proposed state can be validated: the proposed state is added to the current SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed state. The state on the run is set to the validated state as well.</p> <p>If the proposed state is <code>None</code> when this method is called, no state will be written and <code>self.validated_state</code> will be set to the run's current state.</p> <p>Returns:</p> Type Description <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>@inject_db\nasync def validate_proposed_state(\n    self,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Validates a proposed state by committing it to the database.\n\n    After the `TaskOrchestrationContext` is governed by orchestration rules, the\n    proposed state can be validated: the proposed state is added to the current\n    SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n    state. The state on the run is set to the validated state as well.\n\n    If the proposed state is `None` when this method is called, no state will be\n    written and `self.validated_state` will be set to the run's current state.\n\n    Returns:\n        None\n    \"\"\"\n    # (circular import)\n    from prefect.server.api.server import is_client_retryable_exception\n\n    try:\n        await self._validate_proposed_state()\n        return\n    except Exception as exc:\n        logger.exception(\"Encountered error during state validation\")\n        self.proposed_state = None\n\n        if is_client_retryable_exception(exc):\n            # Do not capture retryable database exceptions, this exception will be\n            # raised as a 503 in the API layer\n            raise\n\n        reason = f\"Error validating state: {exc!r}\"\n        self.response_status = SetStateStatus.ABORT\n        self.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> Note <p><code>self.run</code> is an ORM model, and even when copied is unsafe to mutate</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of <code>TaskOrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Note:\n        `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n    Returns:\n        A mutation-safe copy of `TaskOrchestrationContext`\n    \"\"\"\n\n    return super().safe_copy()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule","title":"<code>BaseOrchestrationRule</code>","text":"<p>               Bases: <code>AbstractAsyncContextManager</code></p> <p>An abstract base class used to implement a discrete piece of orchestration logic.</p> <p>An <code>OrchestrationRule</code> is a stateful context manager that directly governs a state transition. Complex orchestration is achieved by nesting multiple rules. Each rule runs against an <code>OrchestrationContext</code> that contains the transition details; this context is then passed to subsequent rules. The context can be modified by hooks that fire before and after a new state is validated and committed to the database. These hooks will fire as long as the state transition is considered \"valid\" and govern a transition by either modifying the proposed state before it is validated or by producing a side-effect.</p> <p>A state transition occurs whenever a flow- or task- run changes state, prompting Prefect REST API to decide whether or not this transition can proceed. The current state of the run is referred to as the \"initial state\", and the state a run is attempting to transition into is the \"proposed state\". Together, the initial state transitioning into the proposed state is the intended transition that is governed by these orchestration rules. After using rules to enter a runtime context, the <code>OrchestrationContext</code> will contain a proposed state that has been governed by each rule, and at that point can validate the proposed state and commit it to the database. The validated state will be set on the context as <code>context.validated_state</code>, and rules will call the <code>self.after_transition</code> hook upon exiting the managed context.</p> <p>Examples:</p> <pre><code>Create a rule:\n\n&gt;&gt;&gt; class BasicRule(BaseOrchestrationRule):\n&gt;&gt;&gt;     # allowed initial state types\n&gt;&gt;&gt;     FROM_STATES = [StateType.RUNNING]\n&gt;&gt;&gt;     # allowed proposed state types\n&gt;&gt;&gt;     TO_STATES = [StateType.COMPLETED, StateType.FAILED]\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def before_transition(initial_state, proposed_state, ctx):\n&gt;&gt;&gt;         # side effects and proposed state mutation can happen here\n&gt;&gt;&gt;         ...\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def after_transition(initial_state, validated_state, ctx):\n&gt;&gt;&gt;         # operations on states that have been validated can happen here\n&gt;&gt;&gt;         ...\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def cleanup(intitial_state, validated_state, ctx):\n&gt;&gt;&gt;         # reverts side effects generated by `before_transition` if necessary\n&gt;&gt;&gt;         ...\n\nUse a rule:\n\n&gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n&gt;&gt;&gt; async with BasicRule(context, *intended_transition):\n&gt;&gt;&gt;     # context.proposed_state has been governed by BasicRule\n&gt;&gt;&gt;     ...\n\nUse multiple rules:\n\n&gt;&gt;&gt; rules = [BasicRule, BasicRule]\n&gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n&gt;&gt;&gt; async with contextlib.AsyncExitStack() as stack:\n&gt;&gt;&gt;     for rule in rules:\n&gt;&gt;&gt;         stack.enter_async_context(rule(context, *intended_transition))\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # context.proposed_state has been governed by all rules\n&gt;&gt;&gt;     ...\n</code></pre> <p>Attributes:</p> Name Type Description <code>FROM_STATES</code> <code>Iterable</code> <p>list of valid initial state types this rule governs</p> <code>TO_STATES</code> <code>Iterable</code> <p>list of valid proposed state types this rule governs</p> <code>context</code> <p>the orchestration context</p> <code>from_state_type</code> <p>the state type a run is currently in</p> <code>to_state_type</code> <p>the intended proposed state type prior to any orchestration</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>OrchestrationContext</code> <p>A <code>FlowOrchestrationContext</code> or <code>TaskOrchestrationContext</code> that is passed between rules</p> required <code>from_state_type</code> <code>Optional[StateType]</code> <p>The state type of the initial state of a run, if this state type is not contained in <code>FROM_STATES</code>, no hooks will fire</p> required <code>to_state_type</code> <code>Optional[StateType]</code> <p>The state type of the proposed state before orchestration, if this state type is not contained in <code>TO_STATES</code>, no hooks will fire</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class BaseOrchestrationRule(contextlib.AbstractAsyncContextManager):\n    \"\"\"\n    An abstract base class used to implement a discrete piece of orchestration logic.\n\n    An `OrchestrationRule` is a stateful context manager that directly governs a state\n    transition. Complex orchestration is achieved by nesting multiple rules.\n    Each rule runs against an `OrchestrationContext` that contains the transition\n    details; this context is then passed to subsequent rules. The context can be\n    modified by hooks that fire before and after a new state is validated and committed\n    to the database. These hooks will fire as long as the state transition is\n    considered \"valid\" and govern a transition by either modifying the proposed state\n    before it is validated or by producing a side-effect.\n\n    A state transition occurs whenever a flow- or task- run changes state, prompting\n    Prefect REST API to decide whether or not this transition can proceed. The current state of\n    the run is referred to as the \"initial state\", and the state a run is\n    attempting to transition into is the \"proposed state\". Together, the initial state\n    transitioning into the proposed state is the intended transition that is governed\n    by these orchestration rules. After using rules to enter a runtime context, the\n    `OrchestrationContext` will contain a proposed state that has been governed by\n    each rule, and at that point can validate the proposed state and commit it to\n    the database. The validated state will be set on the context as\n    `context.validated_state`, and rules will call the `self.after_transition` hook\n    upon exiting the managed context.\n\n    Examples:\n\n        Create a rule:\n\n        &gt;&gt;&gt; class BasicRule(BaseOrchestrationRule):\n        &gt;&gt;&gt;     # allowed initial state types\n        &gt;&gt;&gt;     FROM_STATES = [StateType.RUNNING]\n        &gt;&gt;&gt;     # allowed proposed state types\n        &gt;&gt;&gt;     TO_STATES = [StateType.COMPLETED, StateType.FAILED]\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def before_transition(initial_state, proposed_state, ctx):\n        &gt;&gt;&gt;         # side effects and proposed state mutation can happen here\n        &gt;&gt;&gt;         ...\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def after_transition(initial_state, validated_state, ctx):\n        &gt;&gt;&gt;         # operations on states that have been validated can happen here\n        &gt;&gt;&gt;         ...\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def cleanup(intitial_state, validated_state, ctx):\n        &gt;&gt;&gt;         # reverts side effects generated by `before_transition` if necessary\n        &gt;&gt;&gt;         ...\n\n        Use a rule:\n\n        &gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n        &gt;&gt;&gt; async with BasicRule(context, *intended_transition):\n        &gt;&gt;&gt;     # context.proposed_state has been governed by BasicRule\n        &gt;&gt;&gt;     ...\n\n        Use multiple rules:\n\n        &gt;&gt;&gt; rules = [BasicRule, BasicRule]\n        &gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n        &gt;&gt;&gt; async with contextlib.AsyncExitStack() as stack:\n        &gt;&gt;&gt;     for rule in rules:\n        &gt;&gt;&gt;         stack.enter_async_context(rule(context, *intended_transition))\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # context.proposed_state has been governed by all rules\n        &gt;&gt;&gt;     ...\n\n    Attributes:\n        FROM_STATES: list of valid initial state types this rule governs\n        TO_STATES: list of valid proposed state types this rule governs\n        context: the orchestration context\n        from_state_type: the state type a run is currently in\n        to_state_type: the intended proposed state type prior to any orchestration\n\n    Args:\n        context: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is\n            passed between rules\n        from_state_type: The state type of the initial state of a run, if this\n            state type is not contained in `FROM_STATES`, no hooks will fire\n        to_state_type: The state type of the proposed state before orchestration, if\n            this state type is not contained in `TO_STATES`, no hooks will fire\n    \"\"\"\n\n    FROM_STATES: Iterable = []\n    TO_STATES: Iterable = []\n\n    def __init__(\n        self,\n        context: OrchestrationContext,\n        from_state_type: Optional[states.StateType],\n        to_state_type: Optional[states.StateType],\n    ):\n        self.context = context\n        self.from_state_type = from_state_type\n        self.to_state_type = to_state_type\n        self._invalid_on_entry = None\n\n    async def __aenter__(self) -&gt; OrchestrationContext:\n        \"\"\"\n        Enter an async runtime context governed by this rule.\n\n        The `with` statement will bind a governed `OrchestrationContext` to the target\n        specified by the `as` clause. If the transition proposed by the\n        `OrchestrationContext` is considered invalid on entry, entering this context\n        will do nothing. Otherwise, `self.before_transition` will fire.\n        \"\"\"\n\n        if await self.invalid():\n            pass\n        else:\n            try:\n                entry_context = self.context.entry_context()\n                await self.before_transition(*entry_context)\n                self.context.rule_signature.append(str(self.__class__))\n            except Exception as before_transition_error:\n                reason = (\n                    f\"Aborting orchestration due to error in {self.__class__!r}:\"\n                    f\" !{before_transition_error!r}\"\n                )\n                logger.exception(\n                    f\"Error running before-transition hook in rule {self.__class__!r}:\"\n                    f\" !{before_transition_error!r}\"\n                )\n\n                self.context.proposed_state = None\n                self.context.response_status = SetStateStatus.ABORT\n                self.context.response_details = StateAbortDetails(reason=reason)\n                self.context.orchestration_error = before_transition_error\n\n        return self.context\n\n    async def __aexit__(\n        self,\n        exc_type: Optional[Type[BaseException]],\n        exc_val: Optional[BaseException],\n        exc_tb: Optional[TracebackType],\n    ) -&gt; None:\n        \"\"\"\n        Exit the async runtime context governed by this rule.\n\n        One of three outcomes can happen upon exiting this rule's context depending on\n        the state of the rule. If the rule was found to be invalid on entry, nothing\n        happens. If the rule was valid on entry and continues to be valid on exit,\n        `self.after_transition` will fire. If the rule was valid on entry but invalid\n        on exit, the rule will \"fizzle\" and `self.cleanup` will fire in order to revert\n        any side-effects produced by `self.before_transition`.\n        \"\"\"\n\n        exit_context = self.context.exit_context()\n        if await self.invalid():\n            pass\n        elif await self.fizzled():\n            await self.cleanup(*exit_context)\n        else:\n            await self.after_transition(*exit_context)\n            self.context.finalization_signature.append(str(self.__class__))\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire before a state is committed to the database.\n\n        This hook may produce side-effects or mutate the proposed state of a\n        transition using one of four methods: `self.reject_transition`,\n        `self.delay_transition`, `self.abort_transition`, and `self.rename_state`.\n\n        Note:\n            As currently implemented, the `before_transition` hook is not\n            perfectly isolated from mutating the transition. It is a standard instance\n            method that has access to `self`, and therefore `self.context`. This should\n            never be modified directly. Furthermore, `context.run` is an ORM model, and\n            mutating the run can also cause unintended writes to the database.\n\n        Args:\n            initial_state: The initial state of a transition\n            proposed_state: The proposed state of a transition\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        Args:\n            initial_state: The initial state of a transition\n            validated_state: The governed state that has been committed to the database\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        The intended use of this method is to revert side-effects produced by\n        `self.before_transition` when the transition is found to be invalid on exit.\n        This allows multiple rules to be gracefully run in sequence, without logic that\n        keeps track of all other rules that might govern a transition.\n\n        Args:\n            initial_state: The initial state of a transition\n            validated_state: The governed state that has been committed to the database\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def invalid(self) -&gt; bool:\n        \"\"\"\n        Determines if a rule is invalid.\n\n        Invalid rules do nothing and no hooks fire upon entering or exiting a governed\n        context. Rules are invalid if the transition states types are not contained in\n        `self.FROM_STATES` and `self.TO_STATES`, or if the context is proposing\n        a transition that differs from the transition the rule was instantiated with.\n\n        Returns:\n            True if the rules in invalid, False otherwise.\n        \"\"\"\n        # invalid and fizzled states are mutually exclusive,\n        # `_invalid_on_entry` holds this statefulness\n        if self.from_state_type not in self.FROM_STATES:\n            self._invalid_on_entry = True\n        if self.to_state_type not in self.TO_STATES:\n            self._invalid_on_entry = True\n\n        if self._invalid_on_entry is None:\n            self._invalid_on_entry = await self.invalid_transition()\n        return self._invalid_on_entry\n\n    async def fizzled(self) -&gt; bool:\n        \"\"\"\n        Determines if a rule is fizzled and side-effects need to be reverted.\n\n        Rules are fizzled if the transitions were valid on entry (thus firing\n        `self.before_transition`) but are invalid upon exiting the governed context,\n        most likely caused by another rule mutating the transition.\n\n        Returns:\n            True if the rule is fizzled, False otherwise.\n        \"\"\"\n\n        if self._invalid_on_entry:\n            return False\n        return await self.invalid_transition()\n\n    async def invalid_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition proposed by the `OrchestrationContext` is invalid.\n\n        If the `OrchestrationContext` is attempting to manage a transition with this\n        rule that differs from the transition the rule was instantiated with, the\n        transition is considered to be invalid. Depending on the context, a rule with an\n        invalid transition is either \"invalid\" or \"fizzled\".\n\n        Returns:\n            True if the transition is invalid, False otherwise.\n        \"\"\"\n\n        initial_state_type = self.context.initial_state_type\n        proposed_state_type = self.context.proposed_state_type\n        return (self.from_state_type != initial_state_type) or (\n            self.to_state_type != proposed_state_type\n        )\n\n    async def reject_transition(self, state: Optional[states.State], reason: str):\n        \"\"\"\n        Rejects a proposed transition before the transition is validated.\n\n        This method will reject a proposed transition, mutating the proposed state to\n        the provided `state`. A reason for rejecting the transition is also passed on\n        to the `OrchestrationContext`. Rules that reject the transition will not fizzle,\n        despite the proposed state type changing.\n\n        Args:\n            state: The new proposed state. If `None`, the current run state will be\n                returned in the result instead.\n            reason: The reason for rejecting the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # the current state will be used if a new one is not provided\n        if state is None:\n            if self.from_state_type is None:\n                raise OrchestrationError(\n                    \"The current run has no state; this transition cannot be \"\n                    \"rejected without providing a new state.\"\n                )\n            self.to_state_type = None\n            self.context.proposed_state = None\n        else:\n            # a rule that mutates state should not fizzle itself\n            self.to_state_type = state.type\n            self.context.proposed_state = state\n\n        self.context.response_status = SetStateStatus.REJECT\n        self.context.response_details = StateRejectDetails(reason=reason)\n\n    async def delay_transition(\n        self,\n        delay_seconds: int,\n        reason: str,\n    ):\n        \"\"\"\n        Delays a proposed transition before the transition is validated.\n\n        This method will delay a proposed transition, setting the proposed state to\n        `None`, signaling to the `OrchestrationContext` that no state should be\n        written to the database. The number of seconds a transition should be delayed is\n        passed to the `OrchestrationContext`. A reason for delaying the transition is\n        also provided. Rules that delay the transition will not fizzle, despite the\n        proposed state type changing.\n\n        Args:\n            delay_seconds: The number of seconds the transition should be delayed\n            reason: The reason for delaying the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = None\n        self.context.proposed_state = None\n        self.context.response_status = SetStateStatus.WAIT\n        self.context.response_details = StateWaitDetails(\n            delay_seconds=delay_seconds, reason=reason\n        )\n\n    async def abort_transition(self, reason: str):\n        \"\"\"\n        Aborts a proposed transition before the transition is validated.\n\n        This method will abort a proposed transition, expecting no further action to\n        occur for this run. The proposed state is set to `None`, signaling to the\n        `OrchestrationContext` that no state should be written to the database. A\n        reason for aborting the transition is also provided. Rules that abort the\n        transition will not fizzle, despite the proposed state type changing.\n\n        Args:\n            reason: The reason for aborting the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = None\n        self.context.proposed_state = None\n        self.context.response_status = SetStateStatus.ABORT\n        self.context.response_details = StateAbortDetails(reason=reason)\n\n    async def rename_state(self, state_name):\n        \"\"\"\n        Sets the \"name\" attribute on a proposed state.\n\n        The name of a state is an annotation intended to provide rich, human-readable\n        context for how a run is progressing. This method only updates the name and not\n        the canonical state TYPE, and will not fizzle or invalidate any other rules\n        that might govern this state transition.\n        \"\"\"\n        if self.context.proposed_state is not None:\n            self.context.proposed_state.name = state_name\n\n    async def update_context_parameters(self, key, value):\n        \"\"\"\n        Updates the \"parameters\" dictionary attribute with the specified key-value pair.\n\n        This mechanism streamlines the process of passing messages and information\n        between orchestration rules if necessary and is simpler and more ephemeral than\n        message-passing via the database or some other side-effect. This mechanism can\n        be used to break up large rules for ease of testing or comprehension, but note\n        that any rules coupled this way (or any other way) are no longer independent and\n        the order in which they appear in the orchestration policy priority will matter.\n        \"\"\"\n\n        self.context.parameters.update({key: value})\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.before_transition","title":"<code>before_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire before a state is committed to the database.</p> <p>This hook may produce side-effects or mutate the proposed state of a transition using one of four methods: <code>self.reject_transition</code>, <code>self.delay_transition</code>, <code>self.abort_transition</code>, and <code>self.rename_state</code>.</p> Note <p>As currently implemented, the <code>before_transition</code> hook is not perfectly isolated from mutating the transition. It is a standard instance method that has access to <code>self</code>, and therefore <code>self.context</code>. This should never be modified directly. Furthermore, <code>context.run</code> is an ORM model, and mutating the run can also cause unintended writes to the database.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>proposed_state</code> <code>Optional[State]</code> <p>The proposed state of a transition</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def before_transition(\n    self,\n    initial_state: Optional[states.State],\n    proposed_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire before a state is committed to the database.\n\n    This hook may produce side-effects or mutate the proposed state of a\n    transition using one of four methods: `self.reject_transition`,\n    `self.delay_transition`, `self.abort_transition`, and `self.rename_state`.\n\n    Note:\n        As currently implemented, the `before_transition` hook is not\n        perfectly isolated from mutating the transition. It is a standard instance\n        method that has access to `self`, and therefore `self.context`. This should\n        never be modified directly. Furthermore, `context.run` is an ORM model, and\n        mutating the run can also cause unintended writes to the database.\n\n    Args:\n        initial_state: The initial state of a transition\n        proposed_state: The proposed state of a transition\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.after_transition","title":"<code>after_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>validated_state</code> <code>Optional[State]</code> <p>The governed state that has been committed to the database</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def after_transition(\n    self,\n    initial_state: Optional[states.State],\n    validated_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    Args:\n        initial_state: The initial state of a transition\n        validated_state: The governed state that has been committed to the database\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.cleanup","title":"<code>cleanup</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>The intended use of this method is to revert side-effects produced by <code>self.before_transition</code> when the transition is found to be invalid on exit. This allows multiple rules to be gracefully run in sequence, without logic that keeps track of all other rules that might govern a transition.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>validated_state</code> <code>Optional[State]</code> <p>The governed state that has been committed to the database</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def cleanup(\n    self,\n    initial_state: Optional[states.State],\n    validated_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    The intended use of this method is to revert side-effects produced by\n    `self.before_transition` when the transition is found to be invalid on exit.\n    This allows multiple rules to be gracefully run in sequence, without logic that\n    keeps track of all other rules that might govern a transition.\n\n    Args:\n        initial_state: The initial state of a transition\n        validated_state: The governed state that has been committed to the database\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.invalid","title":"<code>invalid</code>  <code>async</code>","text":"<p>Determines if a rule is invalid.</p> <p>Invalid rules do nothing and no hooks fire upon entering or exiting a governed context. Rules are invalid if the transition states types are not contained in <code>self.FROM_STATES</code> and <code>self.TO_STATES</code>, or if the context is proposing a transition that differs from the transition the rule was instantiated with.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the rules in invalid, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def invalid(self) -&gt; bool:\n    \"\"\"\n    Determines if a rule is invalid.\n\n    Invalid rules do nothing and no hooks fire upon entering or exiting a governed\n    context. Rules are invalid if the transition states types are not contained in\n    `self.FROM_STATES` and `self.TO_STATES`, or if the context is proposing\n    a transition that differs from the transition the rule was instantiated with.\n\n    Returns:\n        True if the rules in invalid, False otherwise.\n    \"\"\"\n    # invalid and fizzled states are mutually exclusive,\n    # `_invalid_on_entry` holds this statefulness\n    if self.from_state_type not in self.FROM_STATES:\n        self._invalid_on_entry = True\n    if self.to_state_type not in self.TO_STATES:\n        self._invalid_on_entry = True\n\n    if self._invalid_on_entry is None:\n        self._invalid_on_entry = await self.invalid_transition()\n    return self._invalid_on_entry\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.fizzled","title":"<code>fizzled</code>  <code>async</code>","text":"<p>Determines if a rule is fizzled and side-effects need to be reverted.</p> <p>Rules are fizzled if the transitions were valid on entry (thus firing <code>self.before_transition</code>) but are invalid upon exiting the governed context, most likely caused by another rule mutating the transition.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the rule is fizzled, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def fizzled(self) -&gt; bool:\n    \"\"\"\n    Determines if a rule is fizzled and side-effects need to be reverted.\n\n    Rules are fizzled if the transitions were valid on entry (thus firing\n    `self.before_transition`) but are invalid upon exiting the governed context,\n    most likely caused by another rule mutating the transition.\n\n    Returns:\n        True if the rule is fizzled, False otherwise.\n    \"\"\"\n\n    if self._invalid_on_entry:\n        return False\n    return await self.invalid_transition()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.invalid_transition","title":"<code>invalid_transition</code>  <code>async</code>","text":"<p>Determines if the transition proposed by the <code>OrchestrationContext</code> is invalid.</p> <p>If the <code>OrchestrationContext</code> is attempting to manage a transition with this rule that differs from the transition the rule was instantiated with, the transition is considered to be invalid. Depending on the context, a rule with an invalid transition is either \"invalid\" or \"fizzled\".</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is invalid, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def invalid_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition proposed by the `OrchestrationContext` is invalid.\n\n    If the `OrchestrationContext` is attempting to manage a transition with this\n    rule that differs from the transition the rule was instantiated with, the\n    transition is considered to be invalid. Depending on the context, a rule with an\n    invalid transition is either \"invalid\" or \"fizzled\".\n\n    Returns:\n        True if the transition is invalid, False otherwise.\n    \"\"\"\n\n    initial_state_type = self.context.initial_state_type\n    proposed_state_type = self.context.proposed_state_type\n    return (self.from_state_type != initial_state_type) or (\n        self.to_state_type != proposed_state_type\n    )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.reject_transition","title":"<code>reject_transition</code>  <code>async</code>","text":"<p>Rejects a proposed transition before the transition is validated.</p> <p>This method will reject a proposed transition, mutating the proposed state to the provided <code>state</code>. A reason for rejecting the transition is also passed on to the <code>OrchestrationContext</code>. Rules that reject the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>Optional[State]</code> <p>The new proposed state. If <code>None</code>, the current run state will be returned in the result instead.</p> required <code>reason</code> <code>str</code> <p>The reason for rejecting the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def reject_transition(self, state: Optional[states.State], reason: str):\n    \"\"\"\n    Rejects a proposed transition before the transition is validated.\n\n    This method will reject a proposed transition, mutating the proposed state to\n    the provided `state`. A reason for rejecting the transition is also passed on\n    to the `OrchestrationContext`. Rules that reject the transition will not fizzle,\n    despite the proposed state type changing.\n\n    Args:\n        state: The new proposed state. If `None`, the current run state will be\n            returned in the result instead.\n        reason: The reason for rejecting the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # the current state will be used if a new one is not provided\n    if state is None:\n        if self.from_state_type is None:\n            raise OrchestrationError(\n                \"The current run has no state; this transition cannot be \"\n                \"rejected without providing a new state.\"\n            )\n        self.to_state_type = None\n        self.context.proposed_state = None\n    else:\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = state.type\n        self.context.proposed_state = state\n\n    self.context.response_status = SetStateStatus.REJECT\n    self.context.response_details = StateRejectDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.delay_transition","title":"<code>delay_transition</code>  <code>async</code>","text":"<p>Delays a proposed transition before the transition is validated.</p> <p>This method will delay a proposed transition, setting the proposed state to <code>None</code>, signaling to the <code>OrchestrationContext</code> that no state should be written to the database. The number of seconds a transition should be delayed is passed to the <code>OrchestrationContext</code>. A reason for delaying the transition is also provided. Rules that delay the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>delay_seconds</code> <code>int</code> <p>The number of seconds the transition should be delayed</p> required <code>reason</code> <code>str</code> <p>The reason for delaying the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def delay_transition(\n    self,\n    delay_seconds: int,\n    reason: str,\n):\n    \"\"\"\n    Delays a proposed transition before the transition is validated.\n\n    This method will delay a proposed transition, setting the proposed state to\n    `None`, signaling to the `OrchestrationContext` that no state should be\n    written to the database. The number of seconds a transition should be delayed is\n    passed to the `OrchestrationContext`. A reason for delaying the transition is\n    also provided. Rules that delay the transition will not fizzle, despite the\n    proposed state type changing.\n\n    Args:\n        delay_seconds: The number of seconds the transition should be delayed\n        reason: The reason for delaying the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # a rule that mutates state should not fizzle itself\n    self.to_state_type = None\n    self.context.proposed_state = None\n    self.context.response_status = SetStateStatus.WAIT\n    self.context.response_details = StateWaitDetails(\n        delay_seconds=delay_seconds, reason=reason\n    )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.abort_transition","title":"<code>abort_transition</code>  <code>async</code>","text":"<p>Aborts a proposed transition before the transition is validated.</p> <p>This method will abort a proposed transition, expecting no further action to occur for this run. The proposed state is set to <code>None</code>, signaling to the <code>OrchestrationContext</code> that no state should be written to the database. A reason for aborting the transition is also provided. Rules that abort the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>reason</code> <code>str</code> <p>The reason for aborting the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def abort_transition(self, reason: str):\n    \"\"\"\n    Aborts a proposed transition before the transition is validated.\n\n    This method will abort a proposed transition, expecting no further action to\n    occur for this run. The proposed state is set to `None`, signaling to the\n    `OrchestrationContext` that no state should be written to the database. A\n    reason for aborting the transition is also provided. Rules that abort the\n    transition will not fizzle, despite the proposed state type changing.\n\n    Args:\n        reason: The reason for aborting the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # a rule that mutates state should not fizzle itself\n    self.to_state_type = None\n    self.context.proposed_state = None\n    self.context.response_status = SetStateStatus.ABORT\n    self.context.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.rename_state","title":"<code>rename_state</code>  <code>async</code>","text":"<p>Sets the \"name\" attribute on a proposed state.</p> <p>The name of a state is an annotation intended to provide rich, human-readable context for how a run is progressing. This method only updates the name and not the canonical state TYPE, and will not fizzle or invalidate any other rules that might govern this state transition.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def rename_state(self, state_name):\n    \"\"\"\n    Sets the \"name\" attribute on a proposed state.\n\n    The name of a state is an annotation intended to provide rich, human-readable\n    context for how a run is progressing. This method only updates the name and not\n    the canonical state TYPE, and will not fizzle or invalidate any other rules\n    that might govern this state transition.\n    \"\"\"\n    if self.context.proposed_state is not None:\n        self.context.proposed_state.name = state_name\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.update_context_parameters","title":"<code>update_context_parameters</code>  <code>async</code>","text":"<p>Updates the \"parameters\" dictionary attribute with the specified key-value pair.</p> <p>This mechanism streamlines the process of passing messages and information between orchestration rules if necessary and is simpler and more ephemeral than message-passing via the database or some other side-effect. This mechanism can be used to break up large rules for ease of testing or comprehension, but note that any rules coupled this way (or any other way) are no longer independent and the order in which they appear in the orchestration policy priority will matter.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def update_context_parameters(self, key, value):\n    \"\"\"\n    Updates the \"parameters\" dictionary attribute with the specified key-value pair.\n\n    This mechanism streamlines the process of passing messages and information\n    between orchestration rules if necessary and is simpler and more ephemeral than\n    message-passing via the database or some other side-effect. This mechanism can\n    be used to break up large rules for ease of testing or comprehension, but note\n    that any rules coupled this way (or any other way) are no longer independent and\n    the order in which they appear in the orchestration policy priority will matter.\n    \"\"\"\n\n    self.context.parameters.update({key: value})\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform","title":"<code>BaseUniversalTransform</code>","text":"<p>               Bases: <code>AbstractAsyncContextManager</code></p> <p>An abstract base class used to implement privileged bookkeeping logic.</p> Warning <p>In almost all cases, use the <code>BaseOrchestrationRule</code> base class instead.</p> <p>Beyond the orchestration rules implemented with the <code>BaseOrchestrationRule</code> ABC, Universal transforms are not stateful, and fire their before- and after- transition hooks on every state transition unless the proposed state is <code>None</code>, indicating that no state should be written to the database. Because there are no guardrails in place to prevent directly mutating state or other parts of the orchestration context, universal transforms should only be used with care.</p> <p>Attributes:</p> Name Type Description <code>FROM_STATES</code> <code>Iterable</code> <p>for compatibility with <code>BaseOrchestrationPolicy</code></p> <code>TO_STATES</code> <code>Iterable</code> <p>for compatibility with <code>BaseOrchestrationPolicy</code></p> <code>context</code> <p>the orchestration context</p> <code>from_state_type</code> <p>the state type a run is currently in</p> <code>to_state_type</code> <p>the intended proposed state type prior to any orchestration</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>OrchestrationContext</code> <p>A <code>FlowOrchestrationContext</code> or <code>TaskOrchestrationContext</code> that is passed between transforms</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class BaseUniversalTransform(contextlib.AbstractAsyncContextManager):\n    \"\"\"\n    An abstract base class used to implement privileged bookkeeping logic.\n\n    Warning:\n        In almost all cases, use the `BaseOrchestrationRule` base class instead.\n\n    Beyond the orchestration rules implemented with the `BaseOrchestrationRule` ABC,\n    Universal transforms are not stateful, and fire their before- and after- transition\n    hooks on every state transition unless the proposed state is `None`, indicating that\n    no state should be written to the database. Because there are no guardrails in place\n    to prevent directly mutating state or other parts of the orchestration context,\n    universal transforms should only be used with care.\n\n    Attributes:\n        FROM_STATES: for compatibility with `BaseOrchestrationPolicy`\n        TO_STATES: for compatibility with `BaseOrchestrationPolicy`\n        context: the orchestration context\n        from_state_type: the state type a run is currently in\n        to_state_type: the intended proposed state type prior to any orchestration\n\n    Args:\n        context: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is\n            passed between transforms\n    \"\"\"\n\n    # `BaseUniversalTransform` will always fire on non-null transitions\n    FROM_STATES: Iterable = ALL_ORCHESTRATION_STATES\n    TO_STATES: Iterable = ALL_ORCHESTRATION_STATES\n\n    def __init__(\n        self,\n        context: OrchestrationContext,\n        from_state_type: Optional[states.StateType],\n        to_state_type: Optional[states.StateType],\n    ):\n        self.context = context\n        self.from_state_type = from_state_type\n        self.to_state_type = to_state_type\n\n    async def __aenter__(self):\n        \"\"\"\n        Enter an async runtime context governed by this transform.\n\n        The `with` statement will bind a governed `OrchestrationContext` to the target\n        specified by the `as` clause. If the transition proposed by the\n        `OrchestrationContext` has been nullified on entry and `context.proposed_state`\n        is `None`, entering this context will do nothing. Otherwise\n        `self.before_transition` will fire.\n        \"\"\"\n\n        await self.before_transition(self.context)\n        self.context.rule_signature.append(str(self.__class__))\n        return self.context\n\n    async def __aexit__(\n        self,\n        exc_type: Optional[Type[BaseException]],\n        exc_val: Optional[BaseException],\n        exc_tb: Optional[TracebackType],\n    ) -&gt; None:\n        \"\"\"\n        Exit the async runtime context governed by this transform.\n\n        If the transition has been nullified or errorred upon exiting this transforms's context,\n        nothing happens. Otherwise, `self.after_transition` will fire on every non-null\n        proposed state.\n        \"\"\"\n\n        if not self.exception_in_transition():\n            await self.after_transition(self.context)\n            self.context.finalization_signature.append(str(self.__class__))\n\n    async def before_transition(self, context) -&gt; None:\n        \"\"\"\n        Implements a hook that fires before a state is committed to the database.\n\n        Args:\n            context: the `OrchestrationContext` that contains transition details\n\n        Returns:\n            None\n        \"\"\"\n\n    async def after_transition(self, context) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        Args:\n            context: the `OrchestrationContext` that contains transition details\n\n        Returns:\n            None\n        \"\"\"\n\n    def nullified_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition has been nullified.\n\n        Transitions are nullified if the proposed state is `None`, indicating that\n        nothing should be written to the database.\n\n        Returns:\n            True if the transition is nullified, False otherwise.\n        \"\"\"\n\n        return self.context.proposed_state is None\n\n    def exception_in_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition has encountered an exception.\n\n        Returns:\n            True if the transition is encountered an exception, False otherwise.\n        \"\"\"\n\n        return self.context.orchestration_error is not None\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.before_transition","title":"<code>before_transition</code>  <code>async</code>","text":"<p>Implements a hook that fires before a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <p>the <code>OrchestrationContext</code> that contains transition details</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def before_transition(self, context) -&gt; None:\n    \"\"\"\n    Implements a hook that fires before a state is committed to the database.\n\n    Args:\n        context: the `OrchestrationContext` that contains transition details\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.after_transition","title":"<code>after_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <p>the <code>OrchestrationContext</code> that contains transition details</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def after_transition(self, context) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    Args:\n        context: the `OrchestrationContext` that contains transition details\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.nullified_transition","title":"<code>nullified_transition</code>","text":"<p>Determines if the transition has been nullified.</p> <p>Transitions are nullified if the proposed state is <code>None</code>, indicating that nothing should be written to the database.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is nullified, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def nullified_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition has been nullified.\n\n    Transitions are nullified if the proposed state is `None`, indicating that\n    nothing should be written to the database.\n\n    Returns:\n        True if the transition is nullified, False otherwise.\n    \"\"\"\n\n    return self.context.proposed_state is None\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.exception_in_transition","title":"<code>exception_in_transition</code>","text":"<p>Determines if the transition has encountered an exception.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is encountered an exception, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def exception_in_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition has encountered an exception.\n\n    Returns:\n        True if the transition is encountered an exception, False otherwise.\n    \"\"\"\n\n    return self.context.orchestration_error is not None\n</code></pre>"},{"location":"api-ref/server/schemas/actions/","title":"server.schemas.actions","text":""},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions","title":"<code>prefect.server.schemas.actions</code>","text":"<p>Reduced schemas for accepting API actions.</p>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactCreate","title":"<code>ArtifactCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create an artifact.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ArtifactCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create an artifact.\"\"\"\n\n    key: Optional[str] = Field(\n        default=None, description=\"An optional unique reference key for this artifact.\"\n    )\n    type: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier that describes the shape of the data field. e.g. 'result',\"\n            \" 'table', 'markdown'\"\n        ),\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A markdown-enabled description of the artifact.\"\n    )\n    data: Optional[Union[Dict[str, Any], Any]] = Field(\n        default=None,\n        description=(\n            \"Data associated with the artifact, e.g. a result.; structure depends on\"\n            \" the artifact type.\"\n        ),\n    )\n    metadata_: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"User-defined artifact metadata. Content must be string key and value\"\n            \" pairs.\"\n        ),\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run associated with the artifact.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run associated with the artifact.\"\n    )\n\n    @classmethod\n    def from_result(cls, data: Any):\n        artifact_info = dict()\n        if isinstance(data, dict):\n            artifact_key = data.pop(\"artifact_key\", None)\n            if artifact_key:\n                artifact_info[\"key\"] = artifact_key\n\n            artifact_type = data.pop(\"artifact_type\", None)\n            if artifact_type:\n                artifact_info[\"type\"] = artifact_type\n\n            description = data.pop(\"artifact_description\", None)\n            if description:\n                artifact_info[\"description\"] = description\n\n        return cls(data=data, **artifact_info)\n\n    _validate_metadata_length = validator(\"metadata_\")(validate_max_metadata_length)\n\n    _validate_artifact_format = validator(\"key\", allow_reuse=True)(\n        validate_artifact_key\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactUpdate","title":"<code>ArtifactUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update an artifact.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ArtifactUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update an artifact.\"\"\"\n\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    description: Optional[str] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n\n    _validate_metadata_length = validator(\"metadata_\", allow_reuse=True)(\n        validate_max_metadata_length\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentCreate","title":"<code>BlockDocumentCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block document.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    _validate_name_format = validator(\"name\", allow_reuse=True)(\n        validate_block_document_name\n    )\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentReferenceCreate","title":"<code>BlockDocumentReferenceCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used to create block document reference.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentReferenceCreate(ActionBaseModel):\n    \"\"\"Data used to create block document reference.\"\"\"\n\n    id: UUID = Field(\n        default_factory=uuid4, description=\"The block document reference ID\"\n    )\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of the parent block document\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentReferenceCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentUpdate","title":"<code>BlockDocumentUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block document.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block document.\"\"\"\n\n    block_schema_id: Optional[UUID] = Field(\n        default=None, description=\"A block schema ID\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    merge_existing_data: bool = True\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockSchemaCreate","title":"<code>BlockSchemaCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block schema.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockSchemaCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block schema.\"\"\"\n\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=schemas.core.DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockSchemaCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeCreate","title":"<code>BlockTypeCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block type.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockTypeCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block type.\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n\n    # validators\n    _validate_slug_format = validator(\"slug\", allow_reuse=True)(\n        validate_block_type_slug\n    )\n\n    _validate_name_characters = validator(\"name\", check_fields=False)(\n        raise_on_name_with_banned_characters\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeUpdate","title":"<code>BlockTypeUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block type.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockTypeUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block type.\"\"\"\n\n    logo_url: Optional[schemas.core.HttpUrl] = Field(None)\n    documentation_url: Optional[schemas.core.HttpUrl] = Field(None)\n    description: Optional[str] = Field(None)\n    code_example: Optional[str] = Field(None)\n\n    @classmethod\n    def updatable_fields(cls) -&gt; set:\n        return get_class_fields_only(cls)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitCreate","title":"<code>ConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Create","title":"<code>ConcurrencyLimitV2Create</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitV2Create(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a v2 concurrency limit.\"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the concurrency limit is active.\"\n    )\n    name: str = Field(default=..., description=\"The name of the concurrency limit.\")\n    limit: NonNegativeInteger = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: NonNegativeInteger = Field(\n        default=0, description=\"The number of active slots.\"\n    )\n    denied_slots: NonNegativeInteger = Field(\n        default=0, description=\"The number of denied slots.\"\n    )\n    slot_decay_per_second: NonNegativeFloat = Field(\n        default=0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Create.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Update","title":"<code>ConcurrencyLimitV2Update</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitV2Update(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a v2 concurrency limit.\"\"\"\n\n    active: Optional[bool] = Field(None)\n    name: Optional[str] = Field(None)\n    limit: Optional[NonNegativeInteger] = Field(None)\n    active_slots: Optional[NonNegativeInteger] = Field(None)\n    denied_slots: Optional[NonNegativeInteger] = Field(None)\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(None)\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Update.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate","title":"<code>DeploymentCreate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentCreate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a deployment.\"\"\"\n\n    @root_validator\n    def populate_schedules(cls, values):\n        return set_deployment_schedules(values)\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the deployment.\",\n        examples=[\"my-deployment\"],\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The ID of the flow associated with the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether the schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of deployment tags.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    pull_steps: Optional[List[dict]] = Field(None)\n\n    manifest_path: Optional[str] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    schedule: Optional[schemas.schedules.SCHEDULE_TYPES] = Field(\n        None, description=\"The schedule for the deployment.\"\n    )\n    description: Optional[str] = Field(None)\n    path: Optional[str] = Field(None)\n    version: Optional[str] = Field(None)\n    entrypoint: Optional[str] = Field(None)\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides for the flow's infrastructure configuration.\",\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"\n        Check that the combination of base_job_template defaults and job_variables\n        conforms to the specified schema.\n\n        NOTE: This method does not hydrate block references in default values within the\n        base job template to validate them. Failing to do this can cause user-facing\n        errors. Instead of this method, use `validate_job_variables_for_deployment`\n        function from `prefect_cloud.orion.api.validation`.\n        \"\"\"\n        # This import is here to avoid a circular import\n        from prefect.utilities.schema_tools import validate\n\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            validate(\n                self.job_variables,\n                variables_schema,\n                raise_on_error=True,\n                preprocess=True,\n                ignore_required=True,\n            )\n\n    @validator(\"parameters\")\n    def _validate_parameters_conform_to_schema(cls, value, values):\n        return validate_parameters_conform_to_schema(value, values)\n\n    @validator(\"parameter_openapi_schema\")\n    def _validate_parameter_openapi_schema(cls, value, values):\n        return validate_parameter_openapi_schema(value, values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> <p>NOTE: This method does not hydrate block references in default values within the base job template to validate them. Failing to do this can cause user-facing errors. Instead of this method, use <code>validate_job_variables_for_deployment</code> function from <code>prefect_cloud.orion.api.validation</code>.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"\n    Check that the combination of base_job_template defaults and job_variables\n    conforms to the specified schema.\n\n    NOTE: This method does not hydrate block references in default values within the\n    base job template to validate them. Failing to do this can cause user-facing\n    errors. Instead of this method, use `validate_job_variables_for_deployment`\n    function from `prefect_cloud.orion.api.validation`.\n    \"\"\"\n    # This import is here to avoid a circular import\n    from prefect.utilities.schema_tools import validate\n\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        validate(\n            self.job_variables,\n            variables_schema,\n            raise_on_error=True,\n            preprocess=True,\n            ignore_required=True,\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.schema","title":"<code>schema</code>  <code>classmethod</code>","text":"<p>Don't use the mixin docstring as the description if this class is missing a docstring.</p> Source code in <code>prefect/_internal/compatibility/deprecated.py</code> <pre><code>@classmethod\ndef schema(\n    cls, by_alias: bool = True, ref_template: str = default_ref_template\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Don't use the mixin docstring as the description if this class is missing a\n    docstring.\n    \"\"\"\n    schema = super().schema(by_alias=by_alias, ref_template=ref_template)\n\n    if not cls.__doc__:\n        schema.pop(\"description\", None)\n\n    return schema\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentFlowRunCreate","title":"<code>DeploymentFlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run from a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentFlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run from a deployment.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=\"Whether or not to enforce the parameter schema on this run.\",\n    )\n    context: Dict[str, Any] = Field(default_factory=dict)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy,\n        description=\"The empirical policy for the flow run.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the flow run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    idempotency_key: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional idempotency key. If a flow run with the same idempotency key\"\n            \" has already been created, the existing flow run will be returned.\"\n        ),\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentFlowRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate","title":"<code>DeploymentUpdate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentUpdate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    version: Optional[str] = Field(None)\n    schedule: Optional[schemas.schedules.SCHEDULE_TYPES] = Field(\n        None, description=\"The schedule for the deployment.\"\n    )\n    description: Optional[str] = Field(None)\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether the schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    parameters: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of deployment tags.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    path: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Overrides for the flow's infrastructure configuration.\",\n    )\n    entrypoint: Optional[str] = Field(None)\n    manifest_path: Optional[str] = Field(None)\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    class Config:\n        allow_population_by_field_name = True\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"\n        Check that the combination of base_job_template defaults and job_variables\n        conforms to the schema specified in the base_job_template.\n\n        NOTE: This method does not hydrate block references in default values within the\n        base job template to validate them. Failing to do this can cause user-facing\n        errors. Instead of this method, use `validate_job_variables_for_deployment`\n        function from `prefect_cloud.orion.api.validation`.\n        \"\"\"\n        # This import is here to avoid a circular import\n        from prefect.utilities.schema_tools import validate\n\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            errors = validate(\n                self.job_variables,\n                variables_schema,\n                raise_on_error=False,\n                preprocess=True,\n                ignore_required=True,\n            )\n            if errors:\n                for error in errors:\n                    raise error\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the schema specified in the base_job_template.</p> <p>NOTE: This method does not hydrate block references in default values within the base job template to validate them. Failing to do this can cause user-facing errors. Instead of this method, use <code>validate_job_variables_for_deployment</code> function from <code>prefect_cloud.orion.api.validation</code>.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"\n    Check that the combination of base_job_template defaults and job_variables\n    conforms to the schema specified in the base_job_template.\n\n    NOTE: This method does not hydrate block references in default values within the\n    base job template to validate them. Failing to do this can cause user-facing\n    errors. Instead of this method, use `validate_job_variables_for_deployment`\n    function from `prefect_cloud.orion.api.validation`.\n    \"\"\"\n    # This import is here to avoid a circular import\n    from prefect.utilities.schema_tools import validate\n\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        errors = validate(\n            self.job_variables,\n            variables_schema,\n            raise_on_error=False,\n            preprocess=True,\n            ignore_required=True,\n        )\n        if errors:\n            for error in errors:\n                raise error\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.schema","title":"<code>schema</code>  <code>classmethod</code>","text":"<p>Don't use the mixin docstring as the description if this class is missing a docstring.</p> Source code in <code>prefect/_internal/compatibility/deprecated.py</code> <pre><code>@classmethod\ndef schema(\n    cls, by_alias: bool = True, ref_template: str = default_ref_template\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Don't use the mixin docstring as the description if this class is missing a\n    docstring.\n    \"\"\"\n    schema = super().schema(by_alias=by_alias, ref_template=ref_template)\n\n    if not cls.__doc__:\n        schema.pop(\"description\", None)\n\n    return schema\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowCreate","title":"<code>FlowCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunCreate","title":"<code>FlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    flow_version: Optional[str] = Field(\n        default=None, description=\"The version of the flow being run.\"\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"The context of the flow run.\",\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy,\n        description=\"The empirical policy for the flow run.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the flow run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    idempotency_key: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional idempotency key. If a flow run with the same idempotency key\"\n            \" has already been created, the existing flow run will be returned.\"\n        ),\n    )\n\n    # DEPRECATED\n\n    deployment_id: Optional[UUID] = Field(\n        None,\n        description=(\n            \"DEPRECATED: The id of the deployment associated with this flow run, if\"\n            \" available.\"\n        ),\n        deprecated=True,\n    )\n\n    class Config(ActionBaseModel.Config):\n        json_dumps = orjson_dumps_extra_compatible\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyCreate","title":"<code>FlowRunNotificationPolicyCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run notification policy.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run notification policy.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(schemas.core.FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate","title":"<code>FlowRunNotificationPolicyUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run notification policy.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run notification policy.\"\"\"\n\n    is_active: Optional[bool] = Field(None)\n    state_names: Optional[List[str]] = Field(None)\n    tags: Optional[List[str]] = Field(None)\n    block_document_id: Optional[UUID] = Field(None)\n    message_template: Optional[str] = Field(None)\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunUpdate","title":"<code>FlowRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run.\"\"\"\n\n    name: Optional[str] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    infrastructure_pid: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowUpdate","title":"<code>FlowUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow.\"\"\"\n\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.LogCreate","title":"<code>LogCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a log.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class LogCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a log.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.LogCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.SavedSearchCreate","title":"<code>SavedSearchCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a saved search.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class SavedSearchCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a saved search.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[schemas.core.SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.SavedSearchCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.StateCreate","title":"<code>StateCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a new state.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class StateCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a new state.\"\"\"\n\n    type: schemas.states.StateType = Field(\n        default=..., description=\"The type of the state to create\"\n    )\n    name: Optional[str] = Field(\n        default=None, description=\"The name of the state to create\"\n    )\n    message: Optional[str] = Field(\n        default=None, description=\"The message of the state to create\"\n    )\n    data: Optional[Any] = Field(\n        default=None, description=\"The data of the state to create\"\n    )\n    state_details: schemas.states.StateDetails = Field(\n        default_factory=schemas.states.StateDetails,\n        description=\"The details of the state to create\",\n    )\n\n    timestamp: Optional[DateTimeTZ] = Field(\n        default=None,\n        repr=False,\n        ignored=True,\n    )\n    id: Optional[UUID] = Field(default=None, repr=False, ignored=True)\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        return set_default_scheduled_time(cls, values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.StateCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunCreate","title":"<code>TaskRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a task run</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class TaskRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a task run\"\"\"\n\n    id: Optional[UUID] = Field(\n        default=None,\n        description=\"The ID to use for the task run. If not provided, a random UUID will be generated.\",\n    )\n\n    # TaskRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the task run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run id of the task run.\"\n    )\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional cache key. If a COMPLETED state associated with this cache key\"\n            \" is found, the cached COMPLETED state will be used instead of executing\"\n            \" the task run.\"\n        ),\n    )\n    cache_expiration: Optional[DateTimeTZ] = Field(\n        default=None, description=\"Specifies when the cached state should expire.\"\n    )\n    task_version: Optional[str] = Field(\n        default=None, description=\"The version of the task being run.\"\n    )\n    empirical_policy: schemas.core.TaskRunPolicy = Field(\n        default_factory=schemas.core.TaskRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the task run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    task_inputs: Dict[\n        str,\n        List[\n            Union[\n                schemas.core.TaskRunResult,\n                schemas.core.Parameter,\n                schemas.core.Constant,\n            ]\n        ],\n    ] = Field(\n        default_factory=dict,\n        description=\"The inputs to the task run.\",\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    @validator(\"cache_key\")\n    def validate_cache_key(cls, cache_key):\n        return validate_cache_key_length(cache_key)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunUpdate","title":"<code>TaskRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a task run</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class TaskRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a task run\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableCreate","title":"<code>VariableCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a Variable.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class VariableCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a Variable.\"\"\"\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the variable\",\n        examples=[\"my-variable\"],\n        max_length=schemas.core.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: str = Field(\n        default=...,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=schemas.core.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of variable tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableUpdate","title":"<code>VariableUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a Variable.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class VariableUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a Variable.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the variable\",\n        examples=[\"my-variable\"],\n        max_length=schemas.core.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: Optional[str] = Field(\n        default=None,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=schemas.core.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of variable tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolCreate","title":"<code>WorkPoolCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work pool.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkPoolCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work pool.\"\"\"\n\n    name: str = Field(..., description=\"The name of the work pool.\")\n    description: Optional[str] = Field(None, description=\"The work pool description.\")\n    type: str = Field(description=\"The work pool type.\", default=\"prefect-agent\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n\n    _validate_base_job_template = validator(\"base_job_template\", allow_reuse=True)(\n        validate_base_job_template\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolUpdate","title":"<code>WorkPoolUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work pool.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkPoolUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work pool.\"\"\"\n\n    description: Optional[str] = Field(None)\n    is_paused: Optional[bool] = Field(None)\n    base_job_template: Optional[Dict[str, Any]] = Field(None)\n    concurrency_limit: Optional[NonNegativeInteger] = Field(None)\n\n    _validate_base_job_template = validator(\"base_job_template\", allow_reuse=True)(\n        validate_base_job_template\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueCreate","title":"<code>WorkQueueCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work queue.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkQueueCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work queue.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        None, description=\"The work queue's concurrency limit.\"\n    )\n    priority: Optional[PositiveInteger] = Field(\n        None,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n\n    # DEPRECATED\n\n    filter: Optional[schemas.core.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueUpdate","title":"<code>WorkQueueUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work queue.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkQueueUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work queue.\"\"\"\n\n    name: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(None)\n    priority: Optional[PositiveInteger] = Field(None)\n    last_polled: Optional[DateTimeTZ] = Field(None)\n\n    # DEPRECATED\n\n    filter: Optional[schemas.core.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/core/","title":"server.schemas.core","text":""},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core","title":"<code>prefect.server.schemas.core</code>","text":"<p>Full schemas of Prefect REST API objects.</p>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Agent","title":"<code>Agent</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of an agent</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Agent(ORMBaseModel):\n    \"\"\"An ORM representation of an agent\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the agent. If a name is not provided, it will be\"\n            \" auto-generated.\"\n        ),\n    )\n    work_queue_id: UUID = Field(\n        default=..., description=\"The work queue with which the agent is associated.\"\n    )\n    last_activity_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time this agent polled for work.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockDocument","title":"<code>BlockDocument</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block document.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockDocument(ORMBaseModel):\n    \"\"\"An ORM representation of a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n    block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The associated block schema\"\n    )\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n    block_type_name: Optional[str] = Field(\n        default=None, description=\"The associated block type's name\"\n    )\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    block_document_references: Dict[str, Dict[str, Any]] = Field(\n        default_factory=dict, description=\"Record of the block document's references\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        # the BlockDocumentCreate subclass allows name=None\n        # and will inherit this validator\n        return raise_on_name_with_banned_characters(v)\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n\n    @classmethod\n    async def from_orm_model(\n        cls,\n        session,\n        orm_block_document: \"prefect.server.database.orm_models.ORMBlockDocument\",\n        include_secrets: bool = False,\n    ):\n        data = await orm_block_document.decrypt_data(session=session)\n        # if secrets are not included, obfuscate them based on the schema's\n        # `secret_fields`. Note this walks any nested blocks as well. If the\n        # nested blocks were recovered from named blocks, they will already\n        # be obfuscated, but if nested fields were hardcoded into the parent\n        # blocks data, this is the only opportunity to obfuscate them.\n        if not include_secrets:\n            flat_data = dict_to_flatdict(data)\n            # iterate over the (possibly nested) secret fields\n            # and obfuscate their data\n            for secret_field in orm_block_document.block_schema.fields.get(\n                \"secret_fields\", []\n            ):\n                secret_key = tuple(secret_field.split(\".\"))\n                if flat_data.get(secret_key) is not None:\n                    flat_data[secret_key] = obfuscate_string(flat_data[secret_key])\n                # If a wildcard (*) is in the current secret key path, we take the portion\n                # of the path before the wildcard and compare it to the same level of each\n                # key. A match means that the field is nested under the secret key and should\n                # be obfuscated.\n                elif \"*\" in secret_key:\n                    wildcard_index = secret_key.index(\"*\")\n                    for data_key in flat_data.keys():\n                        if secret_key[0:wildcard_index] == data_key[0:wildcard_index]:\n                            flat_data[data_key] = obfuscate(flat_data[data_key])\n            data = flatdict_to_dict(flat_data)\n\n        return cls(\n            id=orm_block_document.id,\n            created=orm_block_document.created,\n            updated=orm_block_document.updated,\n            name=orm_block_document.name,\n            data=data,\n            block_schema_id=orm_block_document.block_schema_id,\n            block_schema=orm_block_document.block_schema,\n            block_type_id=orm_block_document.block_type_id,\n            block_type_name=orm_block_document.block_type_name,\n            block_type=orm_block_document.block_type,\n            is_anonymous=orm_block_document.is_anonymous,\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockDocumentReference","title":"<code>BlockDocumentReference</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block document reference.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockDocumentReference(ORMBaseModel):\n    \"\"\"An ORM representation of a block document reference.\"\"\"\n\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    parent_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    reference_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockSchema","title":"<code>BlockSchema</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block schema.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockSchema(ORMBaseModel):\n    \"\"\"An ORM representation of a block schema.\"\"\"\n\n    checksum: str = Field(default=..., description=\"The block schema's unique checksum\")\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockSchemaReference","title":"<code>BlockSchemaReference</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block schema reference.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockSchemaReference(ORMBaseModel):\n    \"\"\"An ORM representation of a block schema reference.\"\"\"\n\n    parent_block_schema_id: UUID = Field(\n        default=..., description=\"ID of block schema the reference is nested within\"\n    )\n    parent_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The block schema the reference is nested within\"\n    )\n    reference_block_schema_id: UUID = Field(\n        default=..., description=\"ID of the nested block schema\"\n    )\n    reference_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The nested block schema\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockType","title":"<code>BlockType</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block type</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockType(ORMBaseModel):\n    \"\"\"An ORM representation of a block type\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n    is_protected: bool = Field(\n        default=False, description=\"Protected block types cannot be modified via API.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.ConcurrencyLimit","title":"<code>ConcurrencyLimit</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a concurrency limit.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class ConcurrencyLimit(ORMBaseModel):\n    \"\"\"An ORM representation of a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: List[UUID] = Field(\n        default_factory=list,\n        description=\"A list of active run ids using a concurrency slot\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.ConcurrencyLimitV2","title":"<code>ConcurrencyLimitV2</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class ConcurrencyLimitV2(ORMBaseModel):\n    \"\"\"An ORM representation of a v2 concurrency limit.\"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the concurrency limit is active.\"\n    )\n    name: str = Field(default=..., description=\"The name of the concurrency limit.\")\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=0, description=\"The number of active slots.\")\n    denied_slots: int = Field(default=0, description=\"The number of denied slots.\")\n    slot_decay_per_second: float = Field(\n        default=0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n    avg_slot_occupancy_seconds: float = Field(\n        default=2.0, description=\"The average amount of time a slot is occupied.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Configuration","title":"<code>Configuration</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of account info.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Configuration(ORMBaseModel):\n    \"\"\"An ORM representation of account info.\"\"\"\n\n    key: str = Field(default=..., description=\"Account info key\")\n    value: Dict[str, Any] = Field(default=..., description=\"Account info\")\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ORMBaseModel</code></p> <p>An ORM representation of deployment data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Deployment(DeprecatedInfraOverridesField, ORMBaseModel):\n    \"\"\"An ORM representation of deployment data.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the deployment.\")\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description for the deployment.\"\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The flow id associated with the deployment.\"\n    )\n    schedule: Optional[schedules.SCHEDULE_TYPES] = Field(\n        default=None, description=\"A schedule for the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether or not the deployment schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentSchedule] = Field(\n        default_factory=list, description=\"A list of schedules for the deployment.\"\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    pull_steps: Optional[List[dict]] = Field(\n        default=None,\n        description=\"Pull steps for cloning and running this deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the deployment\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The work queue for the deployment. If no work queue is set, work will not\"\n            \" be scheduled.\"\n        ),\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The last time the deployment was polled for status updates.\",\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    storage_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining storage used for this flow.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use for flow runs.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this deployment.\",\n    )\n    updated_by: Optional[UpdatedBy] = Field(\n        default=None,\n        description=\"Optional information about the updater of this deployment.\",\n    )\n    work_queue_id: UUID = Field(\n        default=None,\n        description=(\n            \"The id of the work pool queue to which this deployment is assigned.\"\n        ),\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    class Config:\n        allow_population_by_field_name = True\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of flow data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Flow(ORMBaseModel):\n    \"\"\"An ORM representation of flow data.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRun","title":"<code>FlowRun</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of flow run data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRun(ORMBaseModel):\n    \"\"\"An ORM representation of flow run data.\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_value\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n\n    state_type: Optional[states.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    # relationships\n    # flow: Flow = None\n    # task_runs: List[\"TaskRun\"] = Field(default_factory=list)\n    state: Optional[states.State] = Field(\n        default=None, description=\"The current state of the flow run.\"\n    )\n    # parent_task_run: \"TaskRun\" = None\n\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Variables used as overrides in the base job template\",\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRunNotificationPolicy","title":"<code>FlowRunNotificationPolicy</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a flow run notification.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRunNotificationPolicy(ORMBaseModel):\n    \"\"\"An ORM representation of a flow run notification.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRunPolicy","title":"<code>FlowRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a flow run should retry.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a flow run should retry.\"\"\"\n\n    # TODO: Determine how to separate between infrastructure and within-process level\n    #       retries\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Optional[int] = Field(\n        default=None, description=\"The delay time between retries, in seconds.\"\n    )\n    pause_keys: Optional[set] = Field(\n        default_factory=set, description=\"Tracks pauses this run has observed.\"\n    )\n    resuming: Optional[bool] = Field(\n        default=False, description=\"Indicates if this run is resuming from a pause.\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Log","title":"<code>Log</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of log data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Log(ORMBaseModel):\n    \"\"\"An ORM representation of log data.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run ID associated with the log.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run ID associated with the log.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.QueueFilter","title":"<code>QueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter criteria definition for a work queue.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class QueueFilter(PrefectBaseModel):\n    \"\"\"Filter criteria definition for a work queue.\"\"\"\n\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"Only include flow runs with these tags in the work queue.\",\n    )\n    deployment_ids: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"Only include flow runs from these deployments in the work queue.\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.SavedSearch","title":"<code>SavedSearch</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of saved search data. Represents a set of filter criteria.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class SavedSearch(ORMBaseModel):\n    \"\"\"An ORM representation of saved search data. Represents a set of filter criteria.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.SavedSearchFilter","title":"<code>SavedSearchFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A filter for a saved search model. Intended for use by the Prefect UI.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class SavedSearchFilter(PrefectBaseModel):\n    \"\"\"A filter for a saved search model. Intended for use by the Prefect UI.\"\"\"\n\n    object: str = Field(default=..., description=\"The object over which to filter.\")\n    property: str = Field(\n        default=..., description=\"The property of the object on which to filter.\"\n    )\n    type: str = Field(default=..., description=\"The type of the property.\")\n    operation: str = Field(\n        default=...,\n        description=\"The operator to apply to the object. For example, `equals`.\",\n    )\n    value: Any = Field(\n        default=..., description=\"A JSON-compatible value for the filter.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.TaskRun","title":"<code>TaskRun</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of task run data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class TaskRun(ORMBaseModel):\n    \"\"\"An ORM representation of task run data.\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run id of the task run.\"\n    )\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional cache key. If a COMPLETED state associated with this cache key\"\n            \" is found, the cached COMPLETED state will be used instead of executing\"\n            \" the task run.\"\n        ),\n    )\n    cache_expiration: Optional[DateTimeTZ] = Field(\n        default=None, description=\"Specifies when the cached state should expire.\"\n    )\n    task_version: Optional[str] = Field(\n        default=None, description=\"The version of the task being run.\"\n    )\n    empirical_policy: TaskRunPolicy = Field(\n        default_factory=TaskRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the task run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the current task run state.\"\n    )\n    task_inputs: Dict[str, List[Union[TaskRunResult, Parameter, Constant]]] = Field(\n        default_factory=dict,\n        description=(\n            \"Tracks the source of inputs to a task run. Used for internal bookkeeping.\"\n        ),\n    )\n    state_type: Optional[states.StateType] = Field(\n        default=None, description=\"The type of the current task run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current task run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the task run has been executed.\"\n    )\n    flow_run_run_count: int = Field(\n        default=0,\n        description=(\n            \"If the parent flow has retried, this indicates the flow retry this run is\"\n            \" associated with.\"\n        ),\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The task run's expected start time.\",\n    )\n\n    # the next scheduled start time will be populated\n    # whenever the run is in a scheduled state\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the task run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the task run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n\n    # relationships\n    # flow_run: FlowRun = None\n    # subflow_runs: List[FlowRun] = Field(default_factory=list)\n    state: Optional[states.State] = Field(\n        default=None, description=\"The current task run state.\"\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    @validator(\"cache_key\")\n    def validate_cache_key(cls, cache_key):\n        return validate_cache_key_length(cache_key)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkPool","title":"<code>WorkPool</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a work pool</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkPool(ORMBaseModel):\n    \"\"\"An ORM representation of a work pool\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description of the work pool.\"\n    )\n    type: str = Field(description=\"The work pool type.\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n    status: Optional[WorkPoolStatus] = Field(\n        default=None, description=\"The current status of the work pool.\"\n    )\n\n    # this required field has a default of None so that the custom validator\n    # below will be called and produce a more helpful error message\n    default_queue_id: UUID = Field(\n        None, description=\"The id of the pool's default queue.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n\n    @validator(\"default_queue_id\", always=True)\n    def helpful_error_for_missing_default_queue_id(cls, v):\n        return validate_default_queue_id_not_none(v)\n\n    @classmethod\n    def from_orm(cls, work_pool: \"ORMWorkPool\") -&gt; Self:\n        parsed: WorkPool = super().from_orm(work_pool)\n        if work_pool.type == \"prefect-agent\":\n            parsed.status = None\n        return parsed\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueue","title":"<code>WorkQueue</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a work queue</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkQueue(ORMBaseModel):\n    \"\"\"An ORM representation of a work queue\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"An optional concurrency limit for the work queue.\"\n    )\n    priority: PositiveInteger = Field(\n        default=1,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n    # Will be required after a future migration\n    work_pool_id: Optional[UUID] = Field(\n        default=None, description=\"The work pool with which the queue is associated.\"\n    )\n    filter: Optional[QueueFilter] = Field(\n        default=None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time an agent polled this queue for work.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueueHealthPolicy","title":"<code>WorkQueueHealthPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkQueueHealthPolicy(PrefectBaseModel):\n    maximum_late_runs: Optional[int] = Field(\n        default=0,\n        description=(\n            \"The maximum number of late runs in the work queue before it is deemed\"\n            \" unhealthy. Defaults to `0`.\"\n        ),\n    )\n    maximum_seconds_since_last_polled: Optional[int] = Field(\n        default=60,\n        description=(\n            \"The maximum number of time in seconds elapsed since work queue has been\"\n            \" polled before it is deemed unhealthy. Defaults to `60`.\"\n        ),\n    )\n\n    def evaluate_health_status(\n        self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n    ) -&gt; bool:\n        \"\"\"\n        Given empirical information about the state of the work queue, evaluate its health status.\n\n        Args:\n            late_runs: the count of late runs for the work queue.\n            last_polled: the last time the work queue was polled, if available.\n\n        Returns:\n            bool: whether or not the work queue is healthy.\n        \"\"\"\n        healthy = True\n        if (\n            self.maximum_late_runs is not None\n            and late_runs_count &gt; self.maximum_late_runs\n        ):\n            healthy = False\n\n        if self.maximum_seconds_since_last_polled is not None:\n            if (\n                last_polled is None\n                or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n                &gt; self.maximum_seconds_since_last_polled\n            ):\n                healthy = False\n\n        return healthy\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueueHealthPolicy.evaluate_health_status","title":"<code>evaluate_health_status</code>","text":"<p>Given empirical information about the state of the work queue, evaluate its health status.</p> <p>Parameters:</p> Name Type Description Default <code>late_runs</code> <p>the count of late runs for the work queue.</p> required <code>last_polled</code> <code>Optional[DateTimeTZ]</code> <p>the last time the work queue was polled, if available.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the work queue is healthy.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>def evaluate_health_status(\n    self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n) -&gt; bool:\n    \"\"\"\n    Given empirical information about the state of the work queue, evaluate its health status.\n\n    Args:\n        late_runs: the count of late runs for the work queue.\n        last_polled: the last time the work queue was polled, if available.\n\n    Returns:\n        bool: whether or not the work queue is healthy.\n    \"\"\"\n    healthy = True\n    if (\n        self.maximum_late_runs is not None\n        and late_runs_count &gt; self.maximum_late_runs\n    ):\n        healthy = False\n\n    if self.maximum_seconds_since_last_polled is not None:\n        if (\n            last_polled is None\n            or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n            &gt; self.maximum_seconds_since_last_polled\n        ):\n            healthy = False\n\n    return healthy\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Worker","title":"<code>Worker</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a worker</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Worker(ORMBaseModel):\n    \"\"\"An ORM representation of a worker\"\"\"\n\n    name: str = Field(description=\"The name of the worker.\")\n    work_pool_id: UUID = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    last_heartbeat_time: datetime.datetime = Field(\n        None, description=\"The last time the worker process sent a heartbeat.\"\n    )\n    heartbeat_interval_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to expect between heartbeats sent by the worker.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/filters/","title":"server.schemas.filters","text":""},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters","title":"<code>prefect.server.schemas.filters</code>","text":"<p>Schemas that define Prefect REST API filtering operations.</p> <p>Each filter schema includes logic for transforming itself into a SQL <code>where</code> clause.</p>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilter","title":"<code>ArtifactCollectionFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter artifact collections. Only artifact collections matching all criteria will be returned\"\"\"\n\n    latest_id: Optional[ArtifactCollectionFilterLatestId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactCollectionFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactCollectionFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactCollectionFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactCollectionFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.latest_id is not None:\n            filters.append(self.latest_id.as_sql_filter(db))\n        if self.key is not None:\n            filters.append(self.key.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId","title":"<code>ArtifactCollectionFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterKey","title":"<code>ArtifactCollectionFilterKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.key</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterKey(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key. Should return all rows in \"\n            \"the ArtifactCollection table if specified.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.key.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.ArtifactCollection.key.ilike(f\"%{self.like_}%\"))\n        if self.exists_ is not None:\n            filters.append(\n                db.ArtifactCollection.key.isnot(None)\n                if self.exists_\n                else db.ArtifactCollection.key.is_(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterLatestId","title":"<code>ArtifactCollectionFilterLatestId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.latest_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterLatestId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.latest_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.latest_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterLatestId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId","title":"<code>ArtifactCollectionFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterType","title":"<code>ArtifactCollectionFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.type.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.ArtifactCollection.type.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilter","title":"<code>ArtifactFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter artifacts. Only artifacts matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter artifacts. Only artifacts matching all criteria will be returned\"\"\"\n\n    id: Optional[ArtifactFilterId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.key is not None:\n            filters.append(self.key.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterFlowRunId","title":"<code>ArtifactFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterId","title":"<code>ArtifactFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterKey","title":"<code>ArtifactFilterKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.key</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterKey(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.key.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Artifact.key.ilike(f\"%{self.like_}%\"))\n        if self.exists_ is not None:\n            filters.append(\n                db.Artifact.key.isnot(None)\n                if self.exists_\n                else db.Artifact.key.is_(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterTaskRunId","title":"<code>ArtifactFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterType","title":"<code>ArtifactFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.type.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.Artifact.type.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilter","title":"<code>BlockDocumentFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned\"\"\"\n\n    id: Optional[BlockDocumentFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.id`\"\n    )\n    is_anonymous: Optional[BlockDocumentFilterIsAnonymous] = Field(\n        # default is to exclude anonymous blocks\n        BlockDocumentFilterIsAnonymous(eq_=False),\n        description=(\n            \"Filter criteria for `BlockDocument.is_anonymous`. \"\n            \"Defaults to excluding anonymous blocks.\"\n        ),\n    )\n    block_type_id: Optional[BlockDocumentFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.block_type_id`\"\n    )\n    name: Optional[BlockDocumentFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.is_anonymous is not None:\n            filters.append(self.is_anonymous.as_sql_filter(db))\n        if self.block_type_id is not None:\n            filters.append(self.block_type_id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId","title":"<code>BlockDocumentFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.block_type_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterBlockTypeId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.block_type_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterId","title":"<code>BlockDocumentFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous","title":"<code>BlockDocumentFilterIsAnonymous</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.is_anonymous</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterIsAnonymous(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.is_anonymous`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter block documents for only those that are or are not anonymous.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.BlockDocument.is_anonymous.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterName","title":"<code>BlockDocumentFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of block names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match block names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-block%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.BlockDocument.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilter","title":"<code>BlockSchemaFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter BlockSchemas</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter BlockSchemas\"\"\"\n\n    block_type_id: Optional[BlockSchemaFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.block_type_id`\"\n    )\n    block_capabilities: Optional[BlockSchemaFilterCapabilities] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.capabilities`\"\n    )\n    id: Optional[BlockSchemaFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.id`\"\n    )\n    version: Optional[BlockSchemaFilterVersion] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.version`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.block_type_id is not None:\n            filters.append(self.block_type_id.as_sql_filter(db))\n        if self.block_capabilities is not None:\n            filters.append(self.block_capabilities.as_sql_filter(db))\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.version is not None:\n            filters.append(self.version.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId","title":"<code>BlockSchemaFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.block_type_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterBlockTypeId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.block_type_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterCapabilities","title":"<code>BlockSchemaFilterCapabilities</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterCapabilities(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"write-storage\", \"read-storage\"]],\n        description=(\n            \"A list of block capabilities. Block entities will be returned only if an\"\n            \" associated block schema has a superset of the defined capabilities.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.BlockSchema.capabilities, self.all_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterCapabilities.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterId","title":"<code>BlockSchemaFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by BlockSchema.id</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by BlockSchema.id\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterVersion","title":"<code>BlockSchemaFilterVersion</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterVersion(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"2.0.0\", \"2.1.0\"]],\n        description=\"A list of block schema versions.\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        pass\n\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.version.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterVersion.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilter","title":"<code>BlockTypeFilter</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter BlockTypes</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilter(PrefectFilterBaseModel):\n    \"\"\"Filter BlockTypes\"\"\"\n\n    name: Optional[BlockTypeFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockType.name`\"\n    )\n\n    slug: Optional[BlockTypeFilterSlug] = Field(\n        default=None, description=\"Filter criteria for `BlockType.slug`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.slug is not None:\n            filters.append(self.slug.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterName","title":"<code>BlockTypeFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockType.name</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockType.name`\"\"\"\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.like_ is not None:\n            filters.append(db.BlockType.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterSlug","title":"<code>BlockTypeFilterSlug</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockType.slug</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilterSlug(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockType.slug`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of slugs to match\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockType.slug.in_(self.any_))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterSlug.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilter","title":"<code>DeploymentFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    id: Optional[DeploymentFilterId] = Field(\n        default=None, description=\"Filter criteria for `Deployment.id`\"\n    )\n    name: Optional[DeploymentFilterName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.name`\"\n    )\n    paused: Optional[DeploymentFilterPaused] = Field(\n        default=None, description=\"Filter criteria for `Deployment.paused`\"\n    )\n    is_schedule_active: Optional[DeploymentFilterIsScheduleActive] = Field(\n        default=None, description=\"Filter criteria for `Deployment.is_schedule_active`\"\n    )\n    tags: Optional[DeploymentFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Deployment.tags`\"\n    )\n    work_queue_name: Optional[DeploymentFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.work_queue_name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.paused is not None:\n            filters.append(self.paused.as_sql_filter(db))\n        if self.is_schedule_active is not None:\n            filters.append(self.is_schedule_active.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.work_queue_name is not None:\n            filters.append(self.work_queue_name.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterId","title":"<code>DeploymentFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of deployment ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterIsScheduleActive","title":"<code>DeploymentFilterIsScheduleActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Legacy filter to filter by <code>Deployment.is_schedule_active</code> which is always the opposite of <code>Deployment.paused</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterIsScheduleActive(PrefectFilterBaseModel):\n    \"\"\"Legacy filter to filter by `Deployment.is_schedule_active` which\n    is always the opposite of `Deployment.paused`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.Deployment.paused.is_not(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterIsScheduleActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterName","title":"<code>DeploymentFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of deployment names to include\",\n        examples=[[\"my-deployment-1\", \"my-deployment-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Deployment.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterPaused","title":"<code>DeploymentFilterPaused</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.paused</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterPaused(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.paused`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment is/is not paused\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.Deployment.paused.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterPaused.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterTags","title":"<code>DeploymentFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Deployment.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Deployment.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Deployments will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include deployments without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Deployment.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.Deployment.tags == [] if self.is_null_ else db.Deployment.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterWorkQueueName","title":"<code>DeploymentFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.work_queue_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterWorkQueueName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.work_queue_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterWorkQueueName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilter","title":"<code>DeploymentScheduleFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentScheduleFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    active: Optional[DeploymentScheduleFilterActive] = Field(\n        default=None, description=\"Filter criteria for `DeploymentSchedule.active`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.active is not None:\n            filters.append(self.active.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilterActive","title":"<code>DeploymentScheduleFilterActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>DeploymentSchedule.active</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentScheduleFilterActive(PrefectFilterBaseModel):\n    \"\"\"Filter by `DeploymentSchedule.active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.DeploymentSchedule.active.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilterActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FilterSet","title":"<code>FilterSet</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A collection of filters for common objects</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FilterSet(PrefectBaseModel):\n    \"\"\"A collection of filters for common objects\"\"\"\n\n    flows: FlowFilter = Field(\n        default_factory=FlowFilter, description=\"Filters that apply to flows\"\n    )\n    flow_runs: FlowRunFilter = Field(\n        default_factory=FlowRunFilter, description=\"Filters that apply to flow runs\"\n    )\n    task_runs: TaskRunFilter = Field(\n        default_factory=TaskRunFilter, description=\"Filters that apply to task runs\"\n    )\n    deployments: DeploymentFilter = Field(\n        default_factory=DeploymentFilter,\n        description=\"Filters that apply to deployments\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FilterSet.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilter","title":"<code>FlowFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for flows. Only flows matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for flows. Only flows matching all criteria will be returned.\"\"\"\n\n    id: Optional[FlowFilterId] = Field(\n        default=None, description=\"Filter criteria for `Flow.id`\"\n    )\n    deployment: Optional[FlowFilterDeployment] = Field(\n        default=None, description=\"Filter criteria for Flow deployments\"\n    )\n    name: Optional[FlowFilterName] = Field(\n        default=None, description=\"Filter criteria for `Flow.name`\"\n    )\n    tags: Optional[FlowFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Flow.tags`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.deployment is not None:\n            filters.append(self.deployment.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterDeployment","title":"<code>FlowFilterDeployment</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by flows by deployment</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterDeployment(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by flows by deployment\"\"\"\n\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flows without deployments\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.is_null_ is not None:\n            deployments_subquery = (\n                sa.select(db.Deployment.flow_id).distinct().subquery()\n            )\n\n            if self.is_null_:\n                filters.append(\n                    db.Flow.id.not_in(sa.select(deployments_subquery.c.flow_id))\n                )\n            else:\n                filters.append(\n                    db.Flow.id.in_(sa.select(deployments_subquery.c.flow_id))\n                )\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterDeployment.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterId","title":"<code>FlowFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Flow.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Flow.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Flow.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterName","title":"<code>FlowFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Flow.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Flow.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow names to include\",\n        examples=[[\"my-flow-1\", \"my-flow-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Flow.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Flow.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterTags","title":"<code>FlowFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Flow.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Flow.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flows will be returned only if their tags are a superset\"\n            \" of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flows without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Flow.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(db.Flow.tags == [] if self.is_null_ else db.Flow.tags != [])\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilter","title":"<code>FlowRunFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter flow runs. Only flow runs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter flow runs. Only flow runs matching all criteria will be returned\"\"\"\n\n    id: Optional[FlowRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.id`\"\n    )\n    name: Optional[FlowRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.name`\"\n    )\n    tags: Optional[FlowRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.tags`\"\n    )\n    deployment_id: Optional[FlowRunFilterDeploymentId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.deployment_id`\"\n    )\n    work_queue_name: Optional[FlowRunFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.work_queue_name\"\n    )\n    state: Optional[FlowRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state`\"\n    )\n    flow_version: Optional[FlowRunFilterFlowVersion] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.flow_version`\"\n    )\n    start_time: Optional[FlowRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.start_time`\"\n    )\n    expected_start_time: Optional[FlowRunFilterExpectedStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.expected_start_time`\"\n    )\n    next_scheduled_start_time: Optional[FlowRunFilterNextScheduledStartTime] = Field(\n        default=None,\n        description=\"Filter criteria for `FlowRun.next_scheduled_start_time`\",\n    )\n    parent_flow_run_id: Optional[FlowRunFilterParentFlowRunId] = Field(\n        default=None, description=\"Filter criteria for subflows of the given flow runs\"\n    )\n    parent_task_run_id: Optional[FlowRunFilterParentTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.parent_task_run_id`\"\n    )\n    idempotency_key: Optional[FlowRunFilterIdempotencyKey] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.idempotency_key`\"\n    )\n\n    def only_filters_on_id(self):\n        return (\n            self.id is not None\n            and (self.id.any_ and not self.id.not_any_)\n            and self.name is None\n            and self.tags is None\n            and self.deployment_id is None\n            and self.work_queue_name is None\n            and self.state is None\n            and self.flow_version is None\n            and self.start_time is None\n            and self.expected_start_time is None\n            and self.next_scheduled_start_time is None\n            and self.parent_flow_run_id is None\n            and self.parent_task_run_id is None\n            and self.idempotency_key is None\n        )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.deployment_id is not None:\n            filters.append(self.deployment_id.as_sql_filter(db))\n        if self.work_queue_name is not None:\n            filters.append(self.work_queue_name.as_sql_filter(db))\n        if self.flow_version is not None:\n            filters.append(self.flow_version.as_sql_filter(db))\n        if self.state is not None:\n            filters.append(self.state.as_sql_filter(db))\n        if self.start_time is not None:\n            filters.append(self.start_time.as_sql_filter(db))\n        if self.expected_start_time is not None:\n            filters.append(self.expected_start_time.as_sql_filter(db))\n        if self.next_scheduled_start_time is not None:\n            filters.append(self.next_scheduled_start_time.as_sql_filter(db))\n        if self.parent_flow_run_id is not None:\n            filters.append(self.parent_flow_run_id.as_sql_filter(db))\n        if self.parent_task_run_id is not None:\n            filters.append(self.parent_task_run_id.as_sql_filter(db))\n        if self.idempotency_key is not None:\n            filters.append(self.idempotency_key.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterDeploymentId","title":"<code>FlowRunFilterDeploymentId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.deployment_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterDeploymentId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.deployment_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run deployment ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without deployment ids\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.deployment_id.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.deployment_id.is_(None)\n                if self.is_null_\n                else db.FlowRun.deployment_id.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterDeploymentId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterExpectedStartTime","title":"<code>FlowRunFilterExpectedStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.expected_start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterExpectedStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.expected_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or after this time\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.expected_start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.expected_start_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterExpectedStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterFlowVersion","title":"<code>FlowRunFilterFlowVersion</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.flow_version</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterFlowVersion(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.flow_version`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run flow_versions to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.flow_version.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterFlowVersion.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterId","title":"<code>FlowRunFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n    not_any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.id.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.FlowRun.id.not_in(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterIdempotencyKey","title":"<code>FlowRunFilterIdempotencyKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by FlowRun.idempotency_key.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterIdempotencyKey(PrefectFilterBaseModel):\n    \"\"\"Filter by FlowRun.idempotency_key.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.idempotency_key.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.FlowRun.idempotency_key.not_in(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterIdempotencyKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterName","title":"<code>FlowRunFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow run names to include\",\n        examples=[[\"my-flow-run-1\", \"my-flow-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.FlowRun.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime","title":"<code>FlowRunFilterNextScheduledStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterNextScheduledStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.next_scheduled_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time or before this\"\n            \" time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time at or after this\"\n            \" time\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.next_scheduled_start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.next_scheduled_start_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentFlowRunId","title":"<code>FlowRunFilterParentFlowRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for subflows of a given flow run</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterParentFlowRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for subflows of a given flow run\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of parent flow run ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(\n                db.FlowRun.id.in_(\n                    sa.select(db.FlowRun.id)\n                    .join(\n                        db.TaskRun,\n                        sa.and_(\n                            db.TaskRun.id == db.FlowRun.parent_task_run_id,\n                        ),\n                    )\n                    .where(db.TaskRun.flow_run_id.in_(self.any_))\n                )\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentTaskRunId","title":"<code>FlowRunFilterParentTaskRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterParentTaskRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.parent_task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parent_task_run_ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without parent_task_run_id\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.parent_task_run_id.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.parent_task_run_id.is_(None)\n                if self.is_null_\n                else db.FlowRun.parent_task_run_id.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStartTime","title":"<code>FlowRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return flow runs without a start time\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.start_time &gt;= self.after_)\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.start_time.is_(None)\n                if self.is_null_\n                else db.FlowRun.start_time.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterState","title":"<code>FlowRunFilterState</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code> and <code>FlowRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterState(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_type` and `FlowRun.state_name`.\"\"\"\n\n    type: Optional[FlowRunFilterStateType] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state_type`\"\n    )\n    name: Optional[FlowRunFilterStateName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state_name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.type is not None:\n            filters.extend(self.type._get_filter_list(db))\n        if self.name is not None:\n            filters.extend(self.name._get_filter_list(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterState.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateName","title":"<code>FlowRunFilterStateName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStateName(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run state names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.state_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateType","title":"<code>FlowRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStateType(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_type`.\"\"\"\n\n    any_: Optional[List[schemas.states.StateType]] = Field(\n        default=None, description=\"A list of flow run state types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.state_type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterTags","title":"<code>FlowRunFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flow runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flow runs without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.FlowRun.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.tags == [] if self.is_null_ else db.FlowRun.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterWorkQueueName","title":"<code>FlowRunFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.work_queue_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterWorkQueueName(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without work queue names\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.work_queue_name.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.work_queue_name.is_(None)\n                if self.is_null_\n                else db.FlowRun.work_queue_name.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterWorkQueueName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilter","title":"<code>FlowRunNotificationPolicyFilter</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter FlowRunNotificationPolicies.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilter(PrefectFilterBaseModel):\n    \"\"\"Filter FlowRunNotificationPolicies.\"\"\"\n\n    is_active: Optional[FlowRunNotificationPolicyFilterIsActive] = Field(\n        default=FlowRunNotificationPolicyFilterIsActive(eq_=False),\n        description=\"Filter criteria for `FlowRunNotificationPolicy.is_active`. \",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.is_active is not None:\n            filters.append(self.is_active.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive","title":"<code>FlowRunNotificationPolicyFilterIsActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilterIsActive(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRunNotificationPolicy.is_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter notification policies for only those that are or are not active.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.FlowRunNotificationPolicy.is_active.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilter","title":"<code>LogFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter logs. Only logs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter logs. Only logs matching all criteria will be returned\"\"\"\n\n    level: Optional[LogFilterLevel] = Field(\n        default=None, description=\"Filter criteria for `Log.level`\"\n    )\n    timestamp: Optional[LogFilterTimestamp] = Field(\n        default=None, description=\"Filter criteria for `Log.timestamp`\"\n    )\n    flow_run_id: Optional[LogFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.flow_run_id`\"\n    )\n    task_run_id: Optional[LogFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.task_run_id`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.level is not None:\n            filters.append(self.level.as_sql_filter(db))\n        if self.timestamp is not None:\n            filters.append(self.timestamp.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterFlowRunId","title":"<code>LogFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterLevel","title":"<code>LogFilterLevel</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.level</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterLevel(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.level`.\"\"\"\n\n    ge_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level greater than or equal to this level\",\n        examples=[20],\n    )\n\n    le_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level less than or equal to this level\",\n        examples=[50],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.ge_ is not None:\n            filters.append(db.Log.level &gt;= self.ge_)\n        if self.le_ is not None:\n            filters.append(db.Log.level &lt;= self.le_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterLevel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterName","title":"<code>LogFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of log names to include\",\n        examples=[[\"prefect.logger.flow_runs\", \"prefect.logger.task_runs\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTaskRunId","title":"<code>LogFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTimestamp","title":"<code>LogFilterTimestamp</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.timestamp</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterTimestamp(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.timestamp`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or after this time\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.Log.timestamp &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.Log.timestamp &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTimestamp.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.Operator","title":"<code>Operator</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Operators for combining filter criteria.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class Operator(AutoEnum):\n    \"\"\"Operators for combining filter criteria.\"\"\"\n\n    and_ = AutoEnum.auto()\n    or_ = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.Operator.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectFilterBaseModel","title":"<code>PrefectFilterBaseModel</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Base model for Prefect filters</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class PrefectFilterBaseModel(PrefectBaseModel):\n    \"\"\"Base model for Prefect filters\"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    def as_sql_filter(self, db: \"PrefectDBInterface\") -&gt; \"BooleanClauseList\":\n        \"\"\"Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.\"\"\"\n        filters = self._get_filter_list(db)\n        if not filters:\n            return True\n        return sa.and_(*filters)\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        \"\"\"Return a list of boolean filter statements based on filter parameters\"\"\"\n        raise NotImplementedError(\"_get_filter_list must be implemented\")\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectFilterBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel","title":"<code>PrefectOperatorFilterBaseModel</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Base model for Prefect filters that combines criteria with a user-provided operator</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class PrefectOperatorFilterBaseModel(PrefectFilterBaseModel):\n    \"\"\"Base model for Prefect filters that combines criteria with a user-provided operator\"\"\"\n\n    operator: Operator = Field(\n        default=Operator.and_,\n        description=\"Operator for combining filter criteria. Defaults to 'and_'.\",\n    )\n\n    def as_sql_filter(self, db: \"PrefectDBInterface\") -&gt; \"BooleanClauseList\":\n        filters = self._get_filter_list(db)\n        if not filters:\n            return True\n        return sa.and_(*filters) if self.operator == Operator.and_ else sa.or_(*filters)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilter","title":"<code>TaskRunFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter task runs. Only task runs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter task runs. Only task runs matching all criteria will be returned\"\"\"\n\n    id: Optional[TaskRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.id`\"\n    )\n    name: Optional[TaskRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.name`\"\n    )\n    tags: Optional[TaskRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.tags`\"\n    )\n    state: Optional[TaskRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.state`\"\n    )\n    start_time: Optional[TaskRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.start_time`\"\n    )\n    subflow_runs: Optional[TaskRunFilterSubFlowRuns] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.subflow_run`\"\n    )\n    flow_run_id: Optional[TaskRunFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.flow_run_id`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.state is not None:\n            filters.append(self.state.as_sql_filter(db))\n        if self.start_time is not None:\n            filters.append(self.start_time.as_sql_filter(db))\n        if self.subflow_runs is not None:\n            filters.append(self.subflow_runs.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterFlowRunId","title":"<code>TaskRunFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterFlowRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run flow run ids to include\"\n    )\n\n    is_null_: bool = Field(\n        default=False, description=\"Filter for task runs with None as their flow run id\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.is_null_ is True:\n            filters.append(db.TaskRun.flow_run_id.is_(None))\n        else:\n            if self.any_ is not None:\n                filters.append(db.TaskRun.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterId","title":"<code>TaskRunFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterName","title":"<code>TaskRunFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of task run names to include\",\n        examples=[[\"my-task-run-1\", \"my-task-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.TaskRun.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStartTime","title":"<code>TaskRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return task runs without a start time\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.TaskRun.start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.TaskRun.start_time &gt;= self.after_)\n        if self.is_null_ is not None:\n            filters.append(\n                db.TaskRun.start_time.is_(None)\n                if self.is_null_\n                else db.TaskRun.start_time.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterState","title":"<code>TaskRunFilterState</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.type</code> and <code>TaskRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterState(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.type` and `TaskRun.name`.\"\"\"\n\n    type: Optional[TaskRunFilterStateType]\n    name: Optional[TaskRunFilterStateName]\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.type is not None:\n            filters.extend(self.type._get_filter_list(db))\n        if self.name is not None:\n            filters.extend(self.name._get_filter_list(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterState.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateName","title":"<code>TaskRunFilterStateName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStateName(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.state_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of task run state names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.state_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateType","title":"<code>TaskRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.state_type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStateType(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.state_type`.\"\"\"\n\n    any_: Optional[List[schemas.states.StateType]] = Field(\n        default=None, description=\"A list of task run state types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.state_type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterSubFlowRuns","title":"<code>TaskRunFilterSubFlowRuns</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.subflow_run</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterSubFlowRuns(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.subflow_run`.\"\"\"\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If true, only include task runs that are subflow run parents; if false,\"\n            \" exclude parent task runs\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.exists_ is True:\n            filters.append(db.TaskRun.subflow_run.has())\n        elif self.exists_ is False:\n            filters.append(sa.not_(db.TaskRun.subflow_run.has()))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterSubFlowRuns.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterTags","title":"<code>TaskRunFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Task runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include task runs without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.TaskRun.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.TaskRun.tags == [] if self.is_null_ else db.TaskRun.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilter","title":"<code>VariableFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter variables. Only variables matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter variables. Only variables matching all criteria will be returned\"\"\"\n\n    id: Optional[VariableFilterId] = Field(\n        default=None, description=\"Filter criteria for `Variable.id`\"\n    )\n    name: Optional[VariableFilterName] = Field(\n        default=None, description=\"Filter criteria for `Variable.name`\"\n    )\n    value: Optional[VariableFilterValue] = Field(\n        default=None, description=\"Filter criteria for `Variable.value`\"\n    )\n    tags: Optional[VariableFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Variable.tags`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.value is not None:\n            filters.append(self.value.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterId","title":"<code>VariableFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of variable ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterName","title":"<code>VariableFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my_variable_%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Variable.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterTags","title":"<code>VariableFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Variable.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Variable.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Variables will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include Variables without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Variable.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.Variable.tags == [] if self.is_null_ else db.Variable.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterValue","title":"<code>VariableFilterValue</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.value</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterValue(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.value`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables value to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable value against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-value-%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.value.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Variable.value.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterValue.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilter","title":"<code>WorkPoolFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter work pools. Only work pools matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter work pools. Only work pools matching all criteria will be returned\"\"\"\n\n    id: Optional[WorkPoolFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.id`\"\n    )\n    name: Optional[WorkPoolFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.name`\"\n    )\n    type: Optional[WorkPoolFilterType] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterId","title":"<code>WorkPoolFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterName","title":"<code>WorkPoolFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterType","title":"<code>WorkPoolFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilter","title":"<code>WorkQueueFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter work queues. Only work queues matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter work queues. Only work queues matching all criteria will be\n    returned\"\"\"\n\n    id: Optional[WorkQueueFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.id`\"\n    )\n\n    name: Optional[WorkQueueFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterId","title":"<code>WorkQueueFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkQueue.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkQueue.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"A list of work queue ids to include\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkQueue.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterName","title":"<code>WorkQueueFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkQueue.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkQueue.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"wq-1\", \"wq-2\"]],\n    )\n\n    startswith_: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"A list of case-insensitive starts-with matches. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', and 'Marvin-robot', but not 'sad-marvin'.\"\n        ),\n        examples=[[\"marvin\", \"Marvin-robot\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkQueue.name.in_(self.any_))\n        if self.startswith_ is not None:\n            filters.append(\n                sa.or_(\n                    *[db.WorkQueue.name.ilike(f\"{item}%\") for item in self.startswith_]\n                )\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilter","title":"<code>WorkerFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    # worker_config_id: Optional[WorkerFilterWorkPoolId] = Field(\n    #     default=None, description=\"Filter criteria for `Worker.worker_config_id`\"\n    # )\n\n    last_heartbeat_time: Optional[WorkerFilterLastHeartbeatTime] = Field(\n        default=None,\n        description=\"Filter criteria for `Worker.last_heartbeat_time`\",\n    )\n\n    status: Optional[WorkerFilterStatus] = Field(\n        default=None, description=\"Filter criteria for `Worker.status`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.last_heartbeat_time is not None:\n            filters.append(self.last_heartbeat_time.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime","title":"<code>WorkerFilterLastHeartbeatTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterLastHeartbeatTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or before this time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or after this time\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.Worker.last_heartbeat_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.Worker.last_heartbeat_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterStatus","title":"<code>WorkerFilterStatus</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.status</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterStatus(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.status`.\"\"\"\n\n    any_: Optional[List[schemas.statuses.WorkerStatus]] = Field(\n        default=None, description=\"A list of worker statuses to include\"\n    )\n    not_any_: Optional[List[schemas.statuses.WorkerStatus]] = Field(\n        default=None, description=\"A list of worker statuses to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Worker.status.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.Worker.status.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterStatus.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterWorkPoolId","title":"<code>WorkerFilterWorkPoolId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.worker_config_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterWorkPoolId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.worker_config_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Worker.worker_config_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterWorkPoolId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/responses/","title":"server.schemas.responses","text":""},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses","title":"<code>prefect.server.schemas.responses</code>","text":"<p>Schemas for special responses from the Prefect REST API.</p>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.FlowRunResponse","title":"<code>FlowRunResponse</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class FlowRunResponse(ORMBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    state_type: Optional[schemas.states.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_pool_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The id of the flow run's work pool.\",\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[schemas.states.State] = Field(\n        default=None, description=\"The current state of the flow run.\"\n    )\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Variables used as overrides in the base job template\",\n    )\n\n    @classmethod\n    def from_orm(cls, orm_flow_run: \"ORMFlowRun\"):\n        response = super().from_orm(orm_flow_run)\n        if orm_flow_run.work_queue:\n            response.work_queue_id = orm_flow_run.work_queue.id\n            response.work_queue_name = orm_flow_run.work_queue.name\n            if orm_flow_run.work_queue.work_pool:\n                response.work_pool_id = orm_flow_run.work_queue.work_pool.id\n                response.work_pool_name = orm_flow_run.work_queue.work_pool.name\n\n        return response\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRunResponse):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.GlobalConcurrencyLimitResponse","title":"<code>GlobalConcurrencyLimitResponse</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>A response object for global concurrency limits.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class GlobalConcurrencyLimitResponse(ORMBaseModel):\n    \"\"\"\n    A response object for global concurrency limits.\n    \"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the global concurrency limit is active.\"\n    )\n    name: str = Field(\n        default=..., description=\"The name of the global concurrency limit.\"\n    )\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=..., description=\"The number of active slots.\")\n    slot_decay_per_second: float = Field(\n        default=2.0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.HistoryResponse","title":"<code>HistoryResponse</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a history of aggregation states over an interval</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class HistoryResponse(PrefectBaseModel):\n    \"\"\"Represents a history of aggregation states over an interval\"\"\"\n\n    interval_start: DateTimeTZ = Field(\n        default=..., description=\"The start date of the interval.\"\n    )\n    interval_end: DateTimeTZ = Field(\n        default=..., description=\"The end date of the interval.\"\n    )\n    states: List[HistoryResponseState] = Field(\n        default=..., description=\"A list of state histories during the interval.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.HistoryResponseState","title":"<code>HistoryResponseState</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a single state's history over an interval.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class HistoryResponseState(PrefectBaseModel):\n    \"\"\"Represents a single state's history over an interval.\"\"\"\n\n    state_type: schemas.states.StateType = Field(\n        default=..., description=\"The state type.\"\n    )\n    state_name: str = Field(default=..., description=\"The state name.\")\n    count_runs: int = Field(\n        default=...,\n        description=\"The number of runs in the specified state during the interval.\",\n    )\n    sum_estimated_run_time: datetime.timedelta = Field(\n        default=...,\n        description=\"The total estimated run time of all runs during the interval.\",\n    )\n    sum_estimated_lateness: datetime.timedelta = Field(\n        default=...,\n        description=(\n            \"The sum of differences between actual and expected start time during the\"\n            \" interval.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.OrchestrationResult","title":"<code>OrchestrationResult</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for the output of state orchestration.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class OrchestrationResult(PrefectBaseModel):\n    \"\"\"\n    A container for the output of state orchestration.\n    \"\"\"\n\n    state: Optional[schemas.states.State]\n    status: SetStateStatus\n    details: StateResponseDetails\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.SetStateStatus","title":"<code>SetStateStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumerates return statuses for setting run states.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class SetStateStatus(AutoEnum):\n    \"\"\"Enumerates return statuses for setting run states.\"\"\"\n\n    ACCEPT = AutoEnum.auto()\n    REJECT = AutoEnum.auto()\n    ABORT = AutoEnum.auto()\n    WAIT = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateAbortDetails","title":"<code>StateAbortDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ABORT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateAbortDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ABORT state transition.\"\"\"\n\n    type: Literal[\"abort_details\"] = Field(\n        default=\"abort_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was aborted.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateAcceptDetails","title":"<code>StateAcceptDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ACCEPT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateAcceptDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ACCEPT state transition.\"\"\"\n\n    type: Literal[\"accept_details\"] = Field(\n        default=\"accept_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateRejectDetails","title":"<code>StateRejectDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a REJECT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateRejectDetails(PrefectBaseModel):\n    \"\"\"Details associated with a REJECT state transition.\"\"\"\n\n    type: Literal[\"reject_details\"] = Field(\n        default=\"reject_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was rejected.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateWaitDetails","title":"<code>StateWaitDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a WAIT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateWaitDetails(PrefectBaseModel):\n    \"\"\"Details associated with a WAIT state transition.\"\"\"\n\n    type: Literal[\"wait_details\"] = Field(\n        default=\"wait_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    delay_seconds: int = Field(\n        default=...,\n        description=(\n            \"The length of time in seconds the client should wait before transitioning\"\n            \" states.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition should wait.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.WorkQueueWithStatus","title":"<code>WorkQueueWithStatus</code>","text":"<p>               Bases: <code>WorkQueueResponse</code>, <code>WorkQueueStatusDetail</code></p> <p>Combines a work queue and its status details into a single object</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class WorkQueueWithStatus(WorkQueueResponse, WorkQueueStatusDetail):\n    \"\"\"Combines a work queue and its status details into a single object\"\"\"\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/","title":"server.schemas.schedules","text":""},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules","title":"<code>prefect.server.schemas.schedules</code>","text":"<p>Schedule schemas</p>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Cron schedule</p> <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST.</p> <p>Parameters:</p> Name Type Description Default <code>cron</code> <code>str</code> <p>a valid cron string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string in IANA tzdata format (for example, America/New_York).</p> required <code>day_or</code> <code>bool</code> <p>Control how croniter handles <code>day</code> and <code>day_of_week</code> entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class CronSchedule(PrefectBaseModel):\n    \"\"\"\n    Cron schedule\n\n    NOTE: If the timezone is a DST-observing one, then the schedule will adjust\n    itself appropriately. Cron's rules for DST are based on schedule times, not\n    intervals. This means that an hourly cron schedule will fire on every new\n    schedule hour, not every elapsed hour; for example, when clocks are set back\n    this will result in a two-hour pause as the schedule will fire *the first\n    time* 1am is reached and *the first time* 2am is reached, 120 minutes later.\n    Longer schedules, such as one that fires at 9am every morning, will\n    automatically adjust for DST.\n\n    Args:\n        cron (str): a valid cron string\n        timezone (str): a valid timezone string in IANA tzdata format (for example,\n            America/New_York).\n        day_or (bool, optional): Control how croniter handles `day` and `day_of_week`\n            entries. Defaults to True, matching cron which connects those values using\n            OR. If the switch is set to False, the values are connected using AND. This\n            behaves like fcron and enables you to e.g. define a job that executes each\n            2nd friday of a month by setting the days of month and the weekday.\n\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    cron: str = Field(default=..., examples=[\"0 0 * * *\"])\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n    day_or: bool = Field(\n        default=True,\n        description=(\n            \"Control croniter behavior for handling day and day_of_week entries.\"\n        ),\n    )\n\n    @validator(\"timezone\")\n    def validate_timezone(cls, v, *, values, **kwargs):\n        return default_timezone(v, values)\n\n    @validator(\"cron\")\n    def valid_cron_string(cls, v):\n        return validate_cron_string(v)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to the current date. If a timezone-naive\n                datetime is provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): No returned date will exceed this date.\n                If a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up to\n            # MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        elif self.timezone:\n            start = start.in_tz(self.timezone)\n\n        # subtract one second from the start date, so that croniter returns it\n        # as an event (if it meets the cron criteria)\n        start = start.subtract(seconds=1)\n\n        # Respect microseconds by rounding up\n        if start.microsecond &gt; 0:\n            start += datetime.timedelta(seconds=1)\n\n        # croniter's DST logic interferes with all other datetime libraries except pytz\n        start_localized = pytz.timezone(start.tz.name).localize(\n            datetime.datetime(\n                year=start.year,\n                month=start.month,\n                day=start.day,\n                hour=start.hour,\n                minute=start.minute,\n                second=start.second,\n                microsecond=start.microsecond,\n            )\n        )\n        start_naive_tz = start.naive()\n\n        cron = croniter(self.cron, start_naive_tz, day_or=self.day_or)  # type: ignore\n        dates = set()\n        counter = 0\n\n        while True:\n            # croniter does not handle DST properly when the start time is\n            # in and around when the actual shift occurs. To work around this,\n            # we use the naive start time to get the next cron date delta, then\n            # add that time to the original scheduling anchor.\n            next_time = cron.get_next(datetime.datetime)\n            delta = next_time - start_naive_tz\n            next_date = pendulum.instance(start_localized + delta)\n\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.CronSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.IntervalSchedule","title":"<code>IntervalSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no <code>anchor_date</code> is supplied, the current UTC time is used.  If a timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a <code>timezone</code> can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date.</p> <p>NOTE: If the <code>IntervalSchedule</code> <code>anchor_date</code> or <code>timezone</code> is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>timedelta</code> <p>an interval to schedule on.</p> required <code>anchor_date</code> <code>DateTimeTZ</code> <p>an anchor date to schedule increments against; if not provided, the current timestamp will be used.</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string.</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class IntervalSchedule(PrefectBaseModel):\n    \"\"\"\n    A schedule formed by adding `interval` increments to an `anchor_date`. If no\n    `anchor_date` is supplied, the current UTC time is used.  If a\n    timezone-naive datetime is provided for `anchor_date`, it is assumed to be\n    in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,\n    anchor dates are always stored as UTC offsets, so a `timezone` can be\n    provided to determine localization behaviors like DST boundary handling. If\n    none is provided it will be inferred from the anchor date.\n\n    NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a\n    DST-observing timezone, then the schedule will adjust itself appropriately.\n    Intervals greater than 24 hours will follow DST conventions, while intervals\n    of less than 24 hours will follow UTC intervals. For example, an hourly\n    schedule will fire every UTC hour, even across DST boundaries. When clocks\n    are set back, this will result in two runs that *appear* to both be\n    scheduled for 1am local time, even though they are an hour apart in UTC\n    time. For longer intervals, like a daily schedule, the interval schedule\n    will adjust for DST boundaries so that the clock-hour remains constant. This\n    means that a daily schedule that always fires at 9am will observe DST and\n    continue to fire at 9am in the local time zone.\n\n    Args:\n        interval (datetime.timedelta): an interval to schedule on.\n        anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against;\n            if not provided, the current timestamp will be used.\n        timezone (str, optional): a valid timezone string.\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n        exclude_none = True\n\n    interval: PositiveDuration\n    anchor_date: DateTimeTZ = None\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"anchor_date\", always=True)\n    def validate_anchor_date(cls, v):\n        return default_anchor_date(v)\n\n    @validator(\"timezone\", always=True)\n    def validate_timezone(cls, v, *, values, **kwargs):\n        return default_timezone(v, values)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up to\n            # MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        anchor_tz = self.anchor_date.in_tz(self.timezone)\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        # compute the offset between the anchor date and the start date to jump to the\n        # next date\n        offset = (start - anchor_tz).total_seconds() / self.interval.total_seconds()\n        next_date = anchor_tz.add(seconds=self.interval.total_seconds() * int(offset))\n\n        # break the interval into `days` and `seconds` because pendulum\n        # will handle DST boundaries properly if days are provided, but not\n        # if we add `total seconds`. Therefore, `next_date + self.interval`\n        # fails while `next_date.add(days=days, seconds=seconds)` works.\n        interval_days = self.interval.days\n        interval_seconds = self.interval.total_seconds() - (\n            interval_days * 24 * 60 * 60\n        )\n\n        # daylight saving time boundaries can create a situation where the next date is\n        # before the start date, so we advance it if necessary\n        while next_date &lt; start:\n            next_date = next_date.add(days=interval_days, seconds=interval_seconds)\n\n        counter = 0\n        dates = set()\n\n        while True:\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n\n            next_date = next_date.add(days=interval_days, seconds=interval_seconds)\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.IntervalSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule","title":"<code>RRuleSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>RRule schedule, based on the iCalendar standard (RFC 5545) as implemented in <code>dateutils.rrule</code>.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more.</p> <p>Note that as a calendar-oriented standard, <code>RRuleSchedules</code> are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p> <p>Parameters:</p> Name Type Description Default <code>rrule</code> <code>str</code> <p>a valid RRule string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class RRuleSchedule(PrefectBaseModel):\n    \"\"\"\n    RRule schedule, based on the iCalendar standard\n    ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as\n    implemented in `dateutils.rrule`.\n\n    RRules are appropriate for any kind of calendar-date manipulation, including\n    irregular intervals, repetition, exclusions, week day or day-of-month\n    adjustments, and more.\n\n    Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to\n    to the initial timezone provided. A 9am daily schedule with a daylight saving\n    time-aware start date will maintain a local 9am time through DST boundaries;\n    a 9am daily schedule with a UTC start date will maintain a 9am UTC time.\n\n    Args:\n        rrule (str): a valid RRule string\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    rrule: str\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"rrule\")\n    def validate_rrule_str(cls, v):\n        return validate_rrule_string(v)\n\n    @classmethod\n    def from_rrule(cls, rrule: dateutil.rrule.rrule):\n        if isinstance(rrule, dateutil.rrule.rrule):\n            if rrule._dtstart.tzinfo is not None:\n                timezone = rrule._dtstart.tzinfo.name\n            else:\n                timezone = \"UTC\"\n            return RRuleSchedule(rrule=str(rrule), timezone=timezone)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            dtstarts = [rr._dtstart for rr in rrule._rrule if rr._dtstart is not None]\n            unique_dstarts = set(pendulum.instance(d).in_tz(\"UTC\") for d in dtstarts)\n            unique_timezones = set(d.tzinfo for d in dtstarts if d.tzinfo is not None)\n\n            if len(unique_timezones) &gt; 1:\n                raise ValueError(\n                    f\"rruleset has too many dtstart timezones: {unique_timezones}\"\n                )\n\n            if len(unique_dstarts) &gt; 1:\n                raise ValueError(f\"rruleset has too many dtstarts: {unique_dstarts}\")\n\n            if unique_dstarts and unique_timezones:\n                timezone = dtstarts[0].tzinfo.name\n            else:\n                timezone = \"UTC\"\n\n            rruleset_string = \"\"\n            if rrule._rrule:\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._rrule)\n            if rrule._exrule:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._exrule).replace(\n                    \"RRULE\", \"EXRULE\"\n                )\n            if rrule._rdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"RDATE:\" + \",\".join(\n                    rd.strftime(\"%Y%m%dT%H%M%SZ\") for rd in rrule._rdate\n                )\n            if rrule._exdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"EXDATE:\" + \",\".join(\n                    exd.strftime(\"%Y%m%dT%H%M%SZ\") for exd in rrule._exdate\n                )\n            return RRuleSchedule(rrule=rruleset_string, timezone=timezone)\n        else:\n            raise ValueError(f\"Invalid RRule object: {rrule}\")\n\n    def to_rrule(self) -&gt; dateutil.rrule.rrule:\n        \"\"\"\n        Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n        here\n        \"\"\"\n        rrule = dateutil.rrule.rrulestr(\n            self.rrule,\n            dtstart=DEFAULT_ANCHOR_DATE,\n            cache=True,\n        )\n        timezone = dateutil.tz.gettz(self.timezone)\n        if isinstance(rrule, dateutil.rrule.rrule):\n            kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n            if rrule._until:\n                kwargs.update(\n                    until=rrule._until.replace(tzinfo=timezone),\n                )\n            return rrule.replace(**kwargs)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            # update rrules\n            localized_rrules = []\n            for rr in rrule._rrule:\n                kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n                if rr._until:\n                    kwargs.update(\n                        until=rr._until.replace(tzinfo=timezone),\n                    )\n                localized_rrules.append(rr.replace(**kwargs))\n            rrule._rrule = localized_rrules\n\n            # update exrules\n            localized_exrules = []\n            for exr in rrule._exrule:\n                kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n                if exr._until:\n                    kwargs.update(\n                        until=exr._until.replace(tzinfo=timezone),\n                    )\n                localized_exrules.append(exr.replace(**kwargs))\n            rrule._exrule = localized_exrules\n\n            # update rdates\n            localized_rdates = []\n            for rd in rrule._rdate:\n                localized_rdates.append(rd.replace(tzinfo=timezone))\n            rrule._rdate = localized_rdates\n\n            # update exdates\n            localized_exdates = []\n            for exd in rrule._exdate:\n                localized_exdates.append(exd.replace(tzinfo=timezone))\n            rrule._exdate = localized_exdates\n\n            return rrule\n\n    @validator(\"timezone\", always=True)\n    def valid_timezone(cls, v):\n        return validate_rrule_timezone(v)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to the current date. If a timezone-naive\n                datetime is provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): No returned date will exceed this date.\n                If a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up\n            # to MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        dates = set()\n        counter = 0\n\n        # pass count = None to account for discrepancies with duplicates around DST\n        # boundaries\n        for next_date in self.to_rrule().xafter(start, count=None, inc=True):\n            next_date = pendulum.instance(next_date).in_tz(self.timezone)\n\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule.to_rrule","title":"<code>to_rrule</code>","text":"<p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates here</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>def to_rrule(self) -&gt; dateutil.rrule.rrule:\n    \"\"\"\n    Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n    here\n    \"\"\"\n    rrule = dateutil.rrule.rrulestr(\n        self.rrule,\n        dtstart=DEFAULT_ANCHOR_DATE,\n        cache=True,\n    )\n    timezone = dateutil.tz.gettz(self.timezone)\n    if isinstance(rrule, dateutil.rrule.rrule):\n        kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n        if rrule._until:\n            kwargs.update(\n                until=rrule._until.replace(tzinfo=timezone),\n            )\n        return rrule.replace(**kwargs)\n    elif isinstance(rrule, dateutil.rrule.rruleset):\n        # update rrules\n        localized_rrules = []\n        for rr in rrule._rrule:\n            kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n            if rr._until:\n                kwargs.update(\n                    until=rr._until.replace(tzinfo=timezone),\n                )\n            localized_rrules.append(rr.replace(**kwargs))\n        rrule._rrule = localized_rrules\n\n        # update exrules\n        localized_exrules = []\n        for exr in rrule._exrule:\n            kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n            if exr._until:\n                kwargs.update(\n                    until=exr._until.replace(tzinfo=timezone),\n                )\n            localized_exrules.append(exr.replace(**kwargs))\n        rrule._exrule = localized_exrules\n\n        # update rdates\n        localized_rdates = []\n        for rd in rrule._rdate:\n            localized_rdates.append(rd.replace(tzinfo=timezone))\n        rrule._rdate = localized_rdates\n\n        # update exdates\n        localized_exdates = []\n        for exd in rrule._exdate:\n            localized_exdates.append(exd.replace(tzinfo=timezone))\n        rrule._exdate = localized_exdates\n\n        return rrule\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/","title":"server.schemas.sorting","text":""},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting","title":"<code>prefect.server.schemas.sorting</code>","text":"<p>Schemas for sorting Prefect REST API objects.</p>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactCollectionSort","title":"<code>ArtifactCollectionSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact collection sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class ArtifactCollectionSort(AutoEnum):\n    \"\"\"Defines artifact collection sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort artifact collections\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.ArtifactCollection.created.desc(),\n            \"UPDATED_DESC\": db.ArtifactCollection.updated.desc(),\n            \"ID_DESC\": db.ArtifactCollection.id.desc(),\n            \"KEY_DESC\": db.ArtifactCollection.key.desc(),\n            \"KEY_ASC\": db.ArtifactCollection.key.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactCollectionSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort artifact collections</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort artifact collections\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.ArtifactCollection.created.desc(),\n        \"UPDATED_DESC\": db.ArtifactCollection.updated.desc(),\n        \"ID_DESC\": db.ArtifactCollection.id.desc(),\n        \"KEY_DESC\": db.ArtifactCollection.key.desc(),\n        \"KEY_ASC\": db.ArtifactCollection.key.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactSort","title":"<code>ArtifactSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class ArtifactSort(AutoEnum):\n    \"\"\"Defines artifact sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort artifacts\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Artifact.created.desc(),\n            \"UPDATED_DESC\": db.Artifact.updated.desc(),\n            \"ID_DESC\": db.Artifact.id.desc(),\n            \"KEY_DESC\": db.Artifact.key.desc(),\n            \"KEY_ASC\": db.Artifact.key.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort artifacts</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort artifacts\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Artifact.created.desc(),\n        \"UPDATED_DESC\": db.Artifact.updated.desc(),\n        \"ID_DESC\": db.Artifact.id.desc(),\n        \"KEY_DESC\": db.Artifact.key.desc(),\n        \"KEY_ASC\": db.Artifact.key.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.BlockDocumentSort","title":"<code>BlockDocumentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines block document sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class BlockDocumentSort(AutoEnum):\n    \"\"\"Defines block document sorting options.\"\"\"\n\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n    BLOCK_TYPE_AND_NAME_ASC = \"BLOCK_TYPE_AND_NAME_ASC\"\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort block documents\"\"\"\n        sort_mapping = {\n            \"NAME_DESC\": db.BlockDocument.name.desc(),\n            \"NAME_ASC\": db.BlockDocument.name.asc(),\n            \"BLOCK_TYPE_AND_NAME_ASC\": sa.text(\"block_type_name asc, name asc\"),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.BlockDocumentSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort block documents</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort block documents\"\"\"\n    sort_mapping = {\n        \"NAME_DESC\": db.BlockDocument.name.desc(),\n        \"NAME_ASC\": db.BlockDocument.name.asc(),\n        \"BLOCK_TYPE_AND_NAME_ASC\": sa.text(\"block_type_name asc, name asc\"),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.DeploymentSort","title":"<code>DeploymentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines deployment sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class DeploymentSort(AutoEnum):\n    \"\"\"Defines deployment sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort deployments\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Deployment.created.desc(),\n            \"UPDATED_DESC\": db.Deployment.updated.desc(),\n            \"NAME_ASC\": db.Deployment.name.asc(),\n            \"NAME_DESC\": db.Deployment.name.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.DeploymentSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort deployments</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort deployments\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Deployment.created.desc(),\n        \"UPDATED_DESC\": db.Deployment.updated.desc(),\n        \"NAME_ASC\": db.Deployment.name.asc(),\n        \"NAME_DESC\": db.Deployment.name.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowRunSort","title":"<code>FlowRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow run sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class FlowRunSort(AutoEnum):\n    \"\"\"Defines flow run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    START_TIME_ASC = AutoEnum.auto()\n    START_TIME_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        from sqlalchemy.sql.functions import coalesce\n\n        \"\"\"Return an expression used to sort flow runs\"\"\"\n        sort_mapping = {\n            \"ID_DESC\": db.FlowRun.id.desc(),\n            \"START_TIME_ASC\": coalesce(\n                db.FlowRun.start_time, db.FlowRun.expected_start_time\n            ).asc(),\n            \"START_TIME_DESC\": coalesce(\n                db.FlowRun.start_time, db.FlowRun.expected_start_time\n            ).desc(),\n            \"EXPECTED_START_TIME_ASC\": db.FlowRun.expected_start_time.asc(),\n            \"EXPECTED_START_TIME_DESC\": db.FlowRun.expected_start_time.desc(),\n            \"NAME_ASC\": db.FlowRun.name.asc(),\n            \"NAME_DESC\": db.FlowRun.name.desc(),\n            \"NEXT_SCHEDULED_START_TIME_ASC\": db.FlowRun.next_scheduled_start_time.asc(),\n            \"END_TIME_DESC\": db.FlowRun.end_time.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowSort","title":"<code>FlowSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class FlowSort(AutoEnum):\n    \"\"\"Defines flow sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort flows\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Flow.created.desc(),\n            \"UPDATED_DESC\": db.Flow.updated.desc(),\n            \"NAME_ASC\": db.Flow.name.asc(),\n            \"NAME_DESC\": db.Flow.name.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort flows</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort flows\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Flow.created.desc(),\n        \"UPDATED_DESC\": db.Flow.updated.desc(),\n        \"NAME_ASC\": db.Flow.name.asc(),\n        \"NAME_DESC\": db.Flow.name.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.LogSort","title":"<code>LogSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines log sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class LogSort(AutoEnum):\n    \"\"\"Defines log sorting options.\"\"\"\n\n    TIMESTAMP_ASC = AutoEnum.auto()\n    TIMESTAMP_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort task runs\"\"\"\n        sort_mapping = {\n            \"TIMESTAMP_ASC\": db.Log.timestamp.asc(),\n            \"TIMESTAMP_DESC\": db.Log.timestamp.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.LogSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort task runs</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort task runs\"\"\"\n    sort_mapping = {\n        \"TIMESTAMP_ASC\": db.Log.timestamp.asc(),\n        \"TIMESTAMP_DESC\": db.Log.timestamp.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.TaskRunSort","title":"<code>TaskRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines task run sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class TaskRunSort(AutoEnum):\n    \"\"\"Defines task run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort task runs\"\"\"\n        sort_mapping = {\n            \"ID_DESC\": db.TaskRun.id.desc(),\n            \"EXPECTED_START_TIME_ASC\": db.TaskRun.expected_start_time.asc(),\n            \"EXPECTED_START_TIME_DESC\": db.TaskRun.expected_start_time.desc(),\n            \"NAME_ASC\": db.TaskRun.name.asc(),\n            \"NAME_DESC\": db.TaskRun.name.desc(),\n            \"NEXT_SCHEDULED_START_TIME_ASC\": db.TaskRun.next_scheduled_start_time.asc(),\n            \"END_TIME_DESC\": db.TaskRun.end_time.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.TaskRunSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort task runs</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort task runs\"\"\"\n    sort_mapping = {\n        \"ID_DESC\": db.TaskRun.id.desc(),\n        \"EXPECTED_START_TIME_ASC\": db.TaskRun.expected_start_time.asc(),\n        \"EXPECTED_START_TIME_DESC\": db.TaskRun.expected_start_time.desc(),\n        \"NAME_ASC\": db.TaskRun.name.asc(),\n        \"NAME_DESC\": db.TaskRun.name.desc(),\n        \"NEXT_SCHEDULED_START_TIME_ASC\": db.TaskRun.next_scheduled_start_time.asc(),\n        \"END_TIME_DESC\": db.TaskRun.end_time.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.VariableSort","title":"<code>VariableSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines variables sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class VariableSort(AutoEnum):\n    \"\"\"Defines variables sorting options.\"\"\"\n\n    CREATED_DESC = \"CREATED_DESC\"\n    UPDATED_DESC = \"UPDATED_DESC\"\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort variables\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Variable.created.desc(),\n            \"UPDATED_DESC\": db.Variable.updated.desc(),\n            \"NAME_DESC\": db.Variable.name.desc(),\n            \"NAME_ASC\": db.Variable.name.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.VariableSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort variables</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort variables\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Variable.created.desc(),\n        \"UPDATED_DESC\": db.Variable.updated.desc(),\n        \"NAME_DESC\": db.Variable.name.desc(),\n        \"NAME_ASC\": db.Variable.name.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/states/","title":"server.schemas.states","text":""},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states","title":"<code>prefect.server.schemas.states</code>","text":"<p>State schemas.</p>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State","title":"<code>State</code>","text":"<p>               Bases: <code>StateBaseModel</code></p> <p>Represents the state of a run.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class State(StateBaseModel):\n    \"\"\"Represents the state of a run.\"\"\"\n\n    class Config:\n        orm_mode = True\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    timestamp: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    data: Optional[Any] = Field(\n        default=None,\n        description=(\n            \"Data associated with the state, e.g. a result. \"\n            \"Content must be storable as JSON.\"\n        ),\n    )\n    state_details: StateDetails = Field(default_factory=StateDetails)\n\n    @classmethod\n    def from_orm_without_result(\n        cls,\n        orm_state: Union[\n            \"prefect.server.database.orm_models.ORMFlowRunState\",\n            \"prefect.server.database.orm_models.ORMTaskRunState\",\n        ],\n        with_data: Optional[Any] = None,\n    ):\n        \"\"\"\n        During orchestration, ORM states can be instantiated prior to inserting results\n        into the artifact table and the `data` field will not be eagerly loaded. In\n        these cases, sqlalchemy will attempt to lazily load the the relationship, which\n        will fail when called within a synchronous pydantic method.\n\n        This method will construct a `State` object from an ORM model without a loaded\n        artifact and attach data passed using the `with_data` argument to the `data`\n        field.\n        \"\"\"\n\n        field_keys = cls.schema()[\"properties\"].keys()\n        state_data = {\n            field: getattr(orm_state, field, None)\n            for field in field_keys\n            if field != \"data\"\n        }\n        state_data[\"data\"] = with_data\n        return cls(**state_data)\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        return set_default_scheduled_time(cls, values)\n\n    def is_scheduled(self) -&gt; bool:\n        return self.type == StateType.SCHEDULED\n\n    def is_pending(self) -&gt; bool:\n        return self.type == StateType.PENDING\n\n    def is_running(self) -&gt; bool:\n        return self.type == StateType.RUNNING\n\n    def is_completed(self) -&gt; bool:\n        return self.type == StateType.COMPLETED\n\n    def is_failed(self) -&gt; bool:\n        return self.type == StateType.FAILED\n\n    def is_crashed(self) -&gt; bool:\n        return self.type == StateType.CRASHED\n\n    def is_cancelled(self) -&gt; bool:\n        return self.type == StateType.CANCELLED\n\n    def is_cancelling(self) -&gt; bool:\n        return self.type == StateType.CANCELLING\n\n    def is_final(self) -&gt; bool:\n        return self.type in TERMINAL_STATES\n\n    def is_paused(self) -&gt; bool:\n        return self.type == StateType.PAUSED\n\n    def copy(\n        self,\n        *,\n        update: Optional[Dict[str, Any]] = None,\n        reset_fields: bool = False,\n        **kwargs,\n    ):\n        \"\"\"\n        Copying API models should return an object that could be inserted into the\n        database again. The 'timestamp' is reset using the default factory.\n        \"\"\"\n        update = update or {}\n        update.setdefault(\"timestamp\", self.__fields__[\"timestamp\"].get_default())\n        return super().copy(reset_fields=reset_fields, update=update, **kwargs)\n\n    def result(self, raise_on_failure: bool = True, fetch: Optional[bool] = None):\n        # Backwards compatible `result` handling on the server-side schema\n        from prefect.states import State\n\n        warnings.warn(\n            (\n                \"`result` is no longer supported by\"\n                \" `prefect.server.schemas.states.State` and will be removed in a future\"\n                \" release. When result retrieval is needed, use `prefect.states.State`.\"\n            ),\n            DeprecationWarning,\n            stacklevel=2,\n        )\n\n        state = State.parse_obj(self)\n        return state.result(raise_on_failure=raise_on_failure, fetch=fetch)\n\n    def to_state_create(self):\n        # Backwards compatibility for `to_state_create`\n        from prefect.client.schemas import State\n\n        warnings.warn(\n            (\n                \"Use of `prefect.server.schemas.states.State` from the client is\"\n                \" deprecated and support will be removed in a future release. Use\"\n                \" `prefect.states.State` instead.\"\n            ),\n            DeprecationWarning,\n            stacklevel=2,\n        )\n\n        state = State.parse_obj(self)\n        return state.to_state_create()\n\n    def __repr__(self) -&gt; str:\n        \"\"\"\n        Generates a complete state representation appropriate for introspection\n        and debugging, including the result:\n\n        `MyCompletedState(message=\"my message\", type=COMPLETED, result=...)`\n        \"\"\"\n        from prefect.deprecated.data_documents import DataDocument\n\n        if isinstance(self.data, DataDocument):\n            result = self.data.decode()\n        else:\n            result = self.data\n\n        display = dict(\n            message=repr(self.message),\n            type=str(self.type.value),\n            result=repr(result),\n        )\n\n        return f\"{self.name}({', '.join(f'{k}={v}' for k, v in display.items())})\"\n\n    def __str__(self) -&gt; str:\n        \"\"\"\n        Generates a simple state representation appropriate for logging:\n\n        `MyCompletedState(\"my message\", type=COMPLETED)`\n        \"\"\"\n\n        display = []\n\n        if self.message:\n            display.append(repr(self.message))\n\n        if self.type.value.lower() != self.name.lower():\n            display.append(f\"type={self.type.value}\")\n\n        return f\"{self.name}({', '.join(display)})\"\n\n    def __hash__(self) -&gt; int:\n        return hash(\n            (\n                getattr(self.state_details, \"flow_run_id\", None),\n                getattr(self.state_details, \"task_run_id\", None),\n                self.timestamp,\n                self.type,\n            )\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State.from_orm_without_result","title":"<code>from_orm_without_result</code>  <code>classmethod</code>","text":"<p>During orchestration, ORM states can be instantiated prior to inserting results into the artifact table and the <code>data</code> field will not be eagerly loaded. In these cases, sqlalchemy will attempt to lazily load the the relationship, which will fail when called within a synchronous pydantic method.</p> <p>This method will construct a <code>State</code> object from an ORM model without a loaded artifact and attach data passed using the <code>with_data</code> argument to the <code>data</code> field.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>@classmethod\ndef from_orm_without_result(\n    cls,\n    orm_state: Union[\n        \"prefect.server.database.orm_models.ORMFlowRunState\",\n        \"prefect.server.database.orm_models.ORMTaskRunState\",\n    ],\n    with_data: Optional[Any] = None,\n):\n    \"\"\"\n    During orchestration, ORM states can be instantiated prior to inserting results\n    into the artifact table and the `data` field will not be eagerly loaded. In\n    these cases, sqlalchemy will attempt to lazily load the the relationship, which\n    will fail when called within a synchronous pydantic method.\n\n    This method will construct a `State` object from an ORM model without a loaded\n    artifact and attach data passed using the `with_data` argument to the `data`\n    field.\n    \"\"\"\n\n    field_keys = cls.schema()[\"properties\"].keys()\n    state_data = {\n        field: getattr(orm_state, field, None)\n        for field in field_keys\n        if field != \"data\"\n    }\n    state_data[\"data\"] = with_data\n    return cls(**state_data)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateBaseModel","title":"<code>StateBaseModel</code>","text":"<p>               Bases: <code>IDBaseModel</code></p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class StateBaseModel(IDBaseModel):\n    def orm_dict(\n        self, *args, shallow: bool = False, json_compatible: bool = False, **kwargs\n    ) -&gt; dict:\n        \"\"\"\n        This method is used as a convenience method for constructing fixtues by first\n        building a `State` schema object and converting it into an ORM-compatible\n        format. Because the `data` field is not writable on ORM states, this method\n        omits the `data` field entirely for the purposes of constructing an ORM model.\n        If state data is required, an artifact must be created separately.\n        \"\"\"\n\n        schema_dict = self.dict(\n            *args, shallow=shallow, json_compatible=json_compatible, **kwargs\n        )\n        # remove the data field in order to construct a state ORM model\n        schema_dict.pop(\"data\", None)\n        return schema_dict\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateType","title":"<code>StateType</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of state types.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class StateType(AutoEnum):\n    \"\"\"Enumeration of state types.\"\"\"\n\n    SCHEDULED = AutoEnum.auto()\n    PENDING = AutoEnum.auto()\n    RUNNING = AutoEnum.auto()\n    COMPLETED = AutoEnum.auto()\n    FAILED = AutoEnum.auto()\n    CANCELLED = AutoEnum.auto()\n    CRASHED = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n    CANCELLING = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateType.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.AwaitingRetry","title":"<code>AwaitingRetry</code>","text":"<p>Convenience function for creating <code>AwaitingRetry</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a AwaitingRetry state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def AwaitingRetry(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `AwaitingRetry` states.\n\n    Returns:\n        State: a AwaitingRetry state\n    \"\"\"\n    return Scheduled(\n        cls=cls, scheduled_time=scheduled_time, name=\"AwaitingRetry\", **kwargs\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Cancelled","title":"<code>Cancelled</code>","text":"<p>Convenience function for creating <code>Cancelled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Cancelled state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Cancelled(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Cancelled` states.\n\n    Returns:\n        State: a Cancelled state\n    \"\"\"\n    return cls(type=StateType.CANCELLED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Cancelling","title":"<code>Cancelling</code>","text":"<p>Convenience function for creating <code>Cancelling</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Cancelling state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Cancelling(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Cancelling` states.\n\n    Returns:\n        State: a Cancelling state\n    \"\"\"\n    return cls(type=StateType.CANCELLING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Completed","title":"<code>Completed</code>","text":"<p>Convenience function for creating <code>Completed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Completed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Completed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Completed` states.\n\n    Returns:\n        State: a Completed state\n    \"\"\"\n    return cls(type=StateType.COMPLETED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Crashed","title":"<code>Crashed</code>","text":"<p>Convenience function for creating <code>Crashed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Crashed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Crashed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Crashed` states.\n\n    Returns:\n        State: a Crashed state\n    \"\"\"\n    return cls(type=StateType.CRASHED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Failed","title":"<code>Failed</code>","text":"<p>Convenience function for creating <code>Failed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Failed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Failed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Failed` states.\n\n    Returns:\n        State: a Failed state\n    \"\"\"\n    return cls(type=StateType.FAILED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Late","title":"<code>Late</code>","text":"<p>Convenience function for creating <code>Late</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Late state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Late(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `Late` states.\n\n    Returns:\n        State: a Late state\n    \"\"\"\n    return Scheduled(cls=cls, scheduled_time=scheduled_time, name=\"Late\", **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Paused","title":"<code>Paused</code>","text":"<p>Convenience function for creating <code>Paused</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Paused state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Paused(\n    cls: Type[State] = State,\n    timeout_seconds: int = None,\n    pause_expiration_time: datetime.datetime = None,\n    reschedule: bool = False,\n    pause_key: str = None,\n    **kwargs,\n) -&gt; State:\n    \"\"\"Convenience function for creating `Paused` states.\n\n    Returns:\n        State: a Paused state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n\n    if state_details.pause_timeout:\n        raise ValueError(\"An extra pause timeout was provided in state_details\")\n\n    if pause_expiration_time is not None and timeout_seconds is not None:\n        raise ValueError(\n            \"Cannot supply both a pause_expiration_time and timeout_seconds\"\n        )\n\n    if pause_expiration_time is None and timeout_seconds is None:\n        pass\n    else:\n        state_details.pause_timeout = pause_expiration_time or (\n            pendulum.now(\"UTC\") + pendulum.Duration(seconds=timeout_seconds)\n        )\n\n    state_details.pause_reschedule = reschedule\n    state_details.pause_key = pause_key\n\n    return cls(type=StateType.PAUSED, state_details=state_details, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Pending","title":"<code>Pending</code>","text":"<p>Convenience function for creating <code>Pending</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Pending state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Pending(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Pending` states.\n\n    Returns:\n        State: a Pending state\n    \"\"\"\n    return cls(type=StateType.PENDING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Retrying","title":"<code>Retrying</code>","text":"<p>Convenience function for creating <code>Retrying</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Retrying state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Retrying(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Retrying` states.\n\n    Returns:\n        State: a Retrying state\n    \"\"\"\n    return cls(type=StateType.RUNNING, name=\"Retrying\", **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Running","title":"<code>Running</code>","text":"<p>Convenience function for creating <code>Running</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Running state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Running(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Running` states.\n\n    Returns:\n        State: a Running state\n    \"\"\"\n    return cls(type=StateType.RUNNING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Scheduled","title":"<code>Scheduled</code>","text":"<p>Convenience function for creating <code>Scheduled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Scheduled state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Scheduled(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `Scheduled` states.\n\n    Returns:\n        State: a Scheduled state\n    \"\"\"\n    # NOTE: `scheduled_time` must come first for backwards compatibility\n\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n    elif state_details.scheduled_time:\n        raise ValueError(\"An extra scheduled_time was provided in state_details\")\n    state_details.scheduled_time = scheduled_time\n\n    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Suspended","title":"<code>Suspended</code>","text":"<p>Convenience function for creating <code>Suspended</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <p>a Suspended state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Suspended(\n    cls: Type[State] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    pause_key: Optional[str] = None,\n    **kwargs,\n):\n    \"\"\"Convenience function for creating `Suspended` states.\n\n    Returns:\n        State: a Suspended state\n    \"\"\"\n    return Paused(\n        cls=cls,\n        name=\"Suspended\",\n        reschedule=True,\n        timeout_seconds=timeout_seconds,\n        pause_expiration_time=pause_expiration_time,\n        pause_key=pause_key,\n        **kwargs,\n    )\n</code></pre>"},{"location":"api-ref/server/services/late_runs/","title":"server.services.late_runs","text":""},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs","title":"<code>prefect.server.services.late_runs</code>","text":"<p>The MarkLateRuns service. Responsible for putting flow runs in a Late state if they are not started on time. The threshold for a late run can be configured by changing <code>PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS</code>.</p>"},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs.MarkLateRuns","title":"<code>MarkLateRuns</code>","text":"<p>               Bases: <code>LoopService</code></p> <p>A simple loop service responsible for identifying flow runs that are \"late\".</p> <p>A flow run is defined as \"late\" if has not scheduled within a certain amount of time after its scheduled start time. The exact amount is configurable in Prefect REST API Settings.</p> Source code in <code>prefect/server/services/late_runs.py</code> <pre><code>class MarkLateRuns(LoopService):\n    \"\"\"\n    A simple loop service responsible for identifying flow runs that are \"late\".\n\n    A flow run is defined as \"late\" if has not scheduled within a certain amount\n    of time after its scheduled start time. The exact amount is configurable in\n    Prefect REST API Settings.\n    \"\"\"\n\n    def __init__(self, loop_seconds: float = None, **kwargs):\n        super().__init__(\n            loop_seconds=loop_seconds\n            or PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS.value(),\n            **kwargs,\n        )\n\n        # mark runs late if they are this far past their expected start time\n        self.mark_late_after: datetime.timedelta = (\n            PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS.value()\n        )\n\n        # query for this many runs to mark as late at once\n        self.batch_size = 400\n\n    @inject_db\n    async def run_once(self, db: PrefectDBInterface):\n        \"\"\"\n        Mark flow runs as late by:\n\n        - Querying for flow runs in a scheduled state that are Scheduled to start in the past\n        - For any runs past the \"late\" threshold, setting the flow run state to a new `Late` state\n        \"\"\"\n        scheduled_to_start_before = pendulum.now(\"UTC\").subtract(\n            seconds=self.mark_late_after.total_seconds()\n        )\n\n        while True:\n            async with db.session_context(begin_transaction=True) as session:\n                query = self._get_select_late_flow_runs_query(\n                    scheduled_to_start_before=scheduled_to_start_before, db=db\n                )\n\n                result = await session.execute(query)\n                runs = result.all()\n\n                # mark each run as late\n                for run in runs:\n                    await self._mark_flow_run_as_late(session=session, flow_run=run)\n\n                # if no runs were found, exit the loop\n                if len(runs) &lt; self.batch_size:\n                    break\n\n        self.logger.info(\"Finished monitoring for late runs.\")\n\n    @inject_db\n    def _get_select_late_flow_runs_query(\n        self, scheduled_to_start_before: datetime.datetime, db: PrefectDBInterface\n    ):\n        \"\"\"\n        Returns a sqlalchemy query for late flow runs.\n\n        Args:\n            scheduled_to_start_before: the maximum next scheduled start time of\n                scheduled flow runs to consider in the returned query\n        \"\"\"\n        query = (\n            sa.select(\n                db.FlowRun.id,\n                db.FlowRun.next_scheduled_start_time,\n            )\n            .where(\n                # The next scheduled start time is in the past, including the mark late\n                # after buffer\n                (db.FlowRun.next_scheduled_start_time &lt;= scheduled_to_start_before),\n                db.FlowRun.state_type == states.StateType.SCHEDULED,\n                db.FlowRun.state_name == \"Scheduled\",\n            )\n            .limit(self.batch_size)\n        )\n        return query\n\n    async def _mark_flow_run_as_late(\n        self, session: AsyncSession, flow_run: PrefectDBInterface.FlowRun\n    ) -&gt; None:\n        \"\"\"\n        Mark a flow run as late.\n\n        Pass-through method for overrides.\n        \"\"\"\n        try:\n            await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run.id,\n                state=states.Late(scheduled_time=flow_run.next_scheduled_start_time),\n                flow_policy=MarkLateRunsPolicy,  # type: ignore\n            )\n        except ObjectNotFoundError:\n            return  # flow run was deleted, ignore it\n</code></pre>"},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs.MarkLateRuns.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Mark flow runs as late by:</p> <ul> <li>Querying for flow runs in a scheduled state that are Scheduled to start in the past</li> <li>For any runs past the \"late\" threshold, setting the flow run state to a new <code>Late</code> state</li> </ul> Source code in <code>prefect/server/services/late_runs.py</code> <pre><code>@inject_db\nasync def run_once(self, db: PrefectDBInterface):\n    \"\"\"\n    Mark flow runs as late by:\n\n    - Querying for flow runs in a scheduled state that are Scheduled to start in the past\n    - For any runs past the \"late\" threshold, setting the flow run state to a new `Late` state\n    \"\"\"\n    scheduled_to_start_before = pendulum.now(\"UTC\").subtract(\n        seconds=self.mark_late_after.total_seconds()\n    )\n\n    while True:\n        async with db.session_context(begin_transaction=True) as session:\n            query = self._get_select_late_flow_runs_query(\n                scheduled_to_start_before=scheduled_to_start_before, db=db\n            )\n\n            result = await session.execute(query)\n            runs = result.all()\n\n            # mark each run as late\n            for run in runs:\n                await self._mark_flow_run_as_late(session=session, flow_run=run)\n\n            # if no runs were found, exit the loop\n            if len(runs) &lt; self.batch_size:\n                break\n\n    self.logger.info(\"Finished monitoring for late runs.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/","title":"server.services.loop_service","text":""},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service","title":"<code>prefect.server.services.loop_service</code>","text":"<p>The base class for all Prefect REST API loop services.</p>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService","title":"<code>LoopService</code>","text":"<p>Loop services are relatively lightweight maintenance routines that need to run periodically.</p> <p>This class makes it straightforward to design and integrate them. Users only need to define the <code>run_once</code> coroutine to describe the behavior of the service on each loop.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>class LoopService:\n    \"\"\"\n    Loop services are relatively lightweight maintenance routines that need to run periodically.\n\n    This class makes it straightforward to design and integrate them. Users only need to\n    define the `run_once` coroutine to describe the behavior of the service on each loop.\n    \"\"\"\n\n    loop_seconds = 60\n\n    def __init__(self, loop_seconds: float = None, handle_signals: bool = True):\n        \"\"\"\n        Args:\n            loop_seconds (float): if provided, overrides the loop interval\n                otherwise specified as a class variable\n            handle_signals (bool): if True (default), SIGINT and SIGTERM are\n                gracefully intercepted and shut down the running service.\n        \"\"\"\n        if loop_seconds:\n            self.loop_seconds = loop_seconds  # seconds between runs\n        self._should_stop = False  # flag for whether the service should stop running\n        self._is_running = False  # flag for whether the service is running\n        self.name = type(self).__name__\n        self.logger = get_logger(f\"server.services.{self.name.lower()}\")\n\n        if handle_signals:\n            _register_signal(signal.SIGINT, self._stop)\n            _register_signal(signal.SIGTERM, self._stop)\n\n    @inject_db\n    async def _on_start(self, db: PrefectDBInterface) -&gt; None:\n        \"\"\"\n        Called prior to running the service\n        \"\"\"\n        # reset the _should_stop flag\n        self._should_stop = False\n        # set the _is_running flag\n        self._is_running = True\n\n    async def _on_stop(self) -&gt; None:\n        \"\"\"\n        Called after running the service\n        \"\"\"\n        # reset the _is_running flag\n        self._is_running = False\n\n    async def start(self, loops=None) -&gt; None:\n        \"\"\"\n        Run the service `loops` time. Pass loops=None to run forever.\n\n        Args:\n            loops (int, optional): the number of loops to run before exiting.\n        \"\"\"\n\n        await self._on_start()\n\n        i = 0\n        while not self._should_stop:\n            start_time = pendulum.now(\"UTC\")\n\n            try:\n                self.logger.debug(f\"About to run {self.name}...\")\n                await self.run_once()\n\n            except NotImplementedError as exc:\n                raise exc from None\n\n            # if an error is raised, log and continue\n            except Exception as exc:\n                self.logger.error(f\"Unexpected error in: {repr(exc)}\", exc_info=True)\n\n            end_time = pendulum.now(\"UTC\")\n\n            # if service took longer than its loop interval, log a warning\n            # that the interval might be too short\n            if (end_time - start_time).total_seconds() &gt; self.loop_seconds:\n                self.logger.warning(\n                    f\"{self.name} took {(end_time-start_time).total_seconds()} seconds\"\n                    \" to run, which is longer than its loop interval of\"\n                    f\" {self.loop_seconds} seconds.\"\n                )\n\n            # check if early stopping was requested\n            i += 1\n            if loops is not None and i == loops:\n                self.logger.debug(f\"{self.name} exiting after {loops} loop(s).\")\n                await self.stop(block=False)\n\n            # next run is every \"loop seconds\" after each previous run *started*.\n            # note that if the loop took unexpectedly long, the \"next_run\" time\n            # might be in the past, which will result in an instant start\n            next_run = max(\n                start_time.add(seconds=self.loop_seconds), pendulum.now(\"UTC\")\n            )\n            self.logger.debug(f\"Finished running {self.name}. Next run at {next_run}\")\n\n            # check the `_should_stop` flag every 1 seconds until the next run time is reached\n            while pendulum.now(\"UTC\") &lt; next_run and not self._should_stop:\n                await asyncio.sleep(\n                    min(1, (next_run - pendulum.now(\"UTC\")).total_seconds())\n                )\n\n        await self._on_stop()\n\n    async def stop(self, block=True) -&gt; None:\n        \"\"\"\n        Gracefully stops a running LoopService and optionally blocks until the\n        service stops.\n\n        Args:\n            block (bool): if True, blocks until the service is\n                finished running. Otherwise it requests a stop and returns but\n                the service may still be running a final loop.\n\n        \"\"\"\n        self._stop()\n\n        if block:\n            # if block=True, sleep until the service stops running,\n            # but no more than `loop_seconds` to avoid a deadlock\n            with anyio.move_on_after(self.loop_seconds):\n                while self._is_running:\n                    await asyncio.sleep(0.1)\n\n            # if the service is still running after `loop_seconds`, something's wrong\n            if self._is_running:\n                self.logger.warning(\n                    f\"`stop(block=True)` was called on {self.name} but more than one\"\n                    f\" loop interval ({self.loop_seconds} seconds) has passed. This\"\n                    \" usually means something is wrong. If `stop()` was called from\"\n                    \" inside the loop service, use `stop(block=False)` instead.\"\n                )\n\n    def _stop(self, *_) -&gt; None:\n        \"\"\"\n        Private, synchronous method for setting the `_should_stop` flag. Takes arbitrary\n        arguments so it can be used as a signal handler.\n        \"\"\"\n        self._should_stop = True\n\n    async def run_once(self) -&gt; None:\n        \"\"\"\n        Represents one loop of the service.\n\n        Users should override this method.\n\n        To actually run the service once, call `LoopService().start(loops=1)`\n        instead of `LoopService().run_once()`, because this method will not invoke setup\n        and teardown methods properly.\n        \"\"\"\n        raise NotImplementedError(\"LoopService subclasses must implement this method.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Represents one loop of the service.</p> <p>Users should override this method.</p> <p>To actually run the service once, call <code>LoopService().start(loops=1)</code> instead of <code>LoopService().run_once()</code>, because this method will not invoke setup and teardown methods properly.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def run_once(self) -&gt; None:\n    \"\"\"\n    Represents one loop of the service.\n\n    Users should override this method.\n\n    To actually run the service once, call `LoopService().start(loops=1)`\n    instead of `LoopService().run_once()`, because this method will not invoke setup\n    and teardown methods properly.\n    \"\"\"\n    raise NotImplementedError(\"LoopService subclasses must implement this method.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.start","title":"<code>start</code>  <code>async</code>","text":"<p>Run the service <code>loops</code> time. Pass loops=None to run forever.</p> <p>Parameters:</p> Name Type Description Default <code>loops</code> <code>int</code> <p>the number of loops to run before exiting.</p> <code>None</code> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def start(self, loops=None) -&gt; None:\n    \"\"\"\n    Run the service `loops` time. Pass loops=None to run forever.\n\n    Args:\n        loops (int, optional): the number of loops to run before exiting.\n    \"\"\"\n\n    await self._on_start()\n\n    i = 0\n    while not self._should_stop:\n        start_time = pendulum.now(\"UTC\")\n\n        try:\n            self.logger.debug(f\"About to run {self.name}...\")\n            await self.run_once()\n\n        except NotImplementedError as exc:\n            raise exc from None\n\n        # if an error is raised, log and continue\n        except Exception as exc:\n            self.logger.error(f\"Unexpected error in: {repr(exc)}\", exc_info=True)\n\n        end_time = pendulum.now(\"UTC\")\n\n        # if service took longer than its loop interval, log a warning\n        # that the interval might be too short\n        if (end_time - start_time).total_seconds() &gt; self.loop_seconds:\n            self.logger.warning(\n                f\"{self.name} took {(end_time-start_time).total_seconds()} seconds\"\n                \" to run, which is longer than its loop interval of\"\n                f\" {self.loop_seconds} seconds.\"\n            )\n\n        # check if early stopping was requested\n        i += 1\n        if loops is not None and i == loops:\n            self.logger.debug(f\"{self.name} exiting after {loops} loop(s).\")\n            await self.stop(block=False)\n\n        # next run is every \"loop seconds\" after each previous run *started*.\n        # note that if the loop took unexpectedly long, the \"next_run\" time\n        # might be in the past, which will result in an instant start\n        next_run = max(\n            start_time.add(seconds=self.loop_seconds), pendulum.now(\"UTC\")\n        )\n        self.logger.debug(f\"Finished running {self.name}. Next run at {next_run}\")\n\n        # check the `_should_stop` flag every 1 seconds until the next run time is reached\n        while pendulum.now(\"UTC\") &lt; next_run and not self._should_stop:\n            await asyncio.sleep(\n                min(1, (next_run - pendulum.now(\"UTC\")).total_seconds())\n            )\n\n    await self._on_stop()\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Gracefully stops a running LoopService and optionally blocks until the service stops.</p> <p>Parameters:</p> Name Type Description Default <code>block</code> <code>bool</code> <p>if True, blocks until the service is finished running. Otherwise it requests a stop and returns but the service may still be running a final loop.</p> <code>True</code> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def stop(self, block=True) -&gt; None:\n    \"\"\"\n    Gracefully stops a running LoopService and optionally blocks until the\n    service stops.\n\n    Args:\n        block (bool): if True, blocks until the service is\n            finished running. Otherwise it requests a stop and returns but\n            the service may still be running a final loop.\n\n    \"\"\"\n    self._stop()\n\n    if block:\n        # if block=True, sleep until the service stops running,\n        # but no more than `loop_seconds` to avoid a deadlock\n        with anyio.move_on_after(self.loop_seconds):\n            while self._is_running:\n                await asyncio.sleep(0.1)\n\n        # if the service is still running after `loop_seconds`, something's wrong\n        if self._is_running:\n            self.logger.warning(\n                f\"`stop(block=True)` was called on {self.name} but more than one\"\n                f\" loop interval ({self.loop_seconds} seconds) has passed. This\"\n                \" usually means something is wrong. If `stop()` was called from\"\n                \" inside the loop service, use `stop(block=False)` instead.\"\n            )\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.run_multiple_services","title":"<code>run_multiple_services</code>  <code>async</code>","text":"<p>Only one signal handler can be active at a time, so this function takes a list of loop services and runs all of them with a global signal handler.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def run_multiple_services(loop_services: List[LoopService]):\n    \"\"\"\n    Only one signal handler can be active at a time, so this function takes a list\n    of loop services and runs all of them with a global signal handler.\n    \"\"\"\n\n    def stop_all_services(self, *_):\n        for service in loop_services:\n            service._stop()\n\n    signal.signal(signal.SIGINT, stop_all_services)\n    signal.signal(signal.SIGTERM, stop_all_services)\n    await asyncio.gather(*[service.start() for service in loop_services])\n</code></pre>"},{"location":"api-ref/server/services/scheduler/","title":"server.services.scheduler","text":""},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler","title":"<code>prefect.server.services.scheduler</code>","text":"<p>The Scheduler service.</p>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.RecentDeploymentsScheduler","title":"<code>RecentDeploymentsScheduler</code>","text":"<p>               Bases: <code>Scheduler</code></p> <p>A scheduler that only schedules deployments that were updated very recently. This scheduler can run on a tight loop and ensure that runs from newly-created or updated deployments are rapidly scheduled without having to wait for the \"main\" scheduler to complete its loop.</p> <p>Note that scheduling is idempotent, so its ok for this scheduler to attempt to schedule the same deployments as the main scheduler. It's purpose is to accelerate scheduling for any deployments that users are interacting with.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class RecentDeploymentsScheduler(Scheduler):\n    \"\"\"\n    A scheduler that only schedules deployments that were updated very recently.\n    This scheduler can run on a tight loop and ensure that runs from\n    newly-created or updated deployments are rapidly scheduled without having to\n    wait for the \"main\" scheduler to complete its loop.\n\n    Note that scheduling is idempotent, so its ok for this scheduler to attempt\n    to schedule the same deployments as the main scheduler. It's purpose is to\n    accelerate scheduling for any deployments that users are interacting with.\n    \"\"\"\n\n    # this scheduler runs on a tight loop\n    loop_seconds = 5\n\n    @inject_db\n    def _get_select_deployments_to_schedule_query(self, db: PrefectDBInterface):\n        \"\"\"\n        Returns a sqlalchemy query for selecting deployments to schedule\n        \"\"\"\n        query = (\n            sa.select(db.Deployment.id)\n            .where(\n                sa.and_(\n                    db.Deployment.paused.is_not(True),\n                    # use a slightly larger window than the loop interval to pick up\n                    # any deployments that were created *while* the scheduler was\n                    # last running (assuming the scheduler takes less than one\n                    # second to run). Scheduling is idempotent so picking up schedules\n                    # multiple times is not a concern.\n                    db.Deployment.updated\n                    &gt;= pendulum.now(\"UTC\").subtract(seconds=self.loop_seconds + 1),\n                    (\n                        # Only include deployments that have at least one\n                        # active schedule.\n                        sa.select(db.DeploymentSchedule.deployment_id)\n                        .where(\n                            sa.and_(\n                                db.DeploymentSchedule.deployment_id == db.Deployment.id,\n                                db.DeploymentSchedule.active.is_(True),\n                            )\n                        )\n                        .exists()\n                    ),\n                )\n            )\n            .order_by(db.Deployment.id)\n            .limit(self.deployment_batch_size)\n        )\n        return query\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.Scheduler","title":"<code>Scheduler</code>","text":"<p>               Bases: <code>LoopService</code></p> <p>A loop service that schedules flow runs from deployments.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class Scheduler(LoopService):\n    \"\"\"\n    A loop service that schedules flow runs from deployments.\n    \"\"\"\n\n    # the main scheduler takes its loop interval from\n    # PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS\n    loop_seconds = None\n\n    def __init__(self, loop_seconds: float = None, **kwargs):\n        super().__init__(\n            loop_seconds=(\n                loop_seconds\n                or self.loop_seconds\n                or PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS.value()\n            ),\n            **kwargs,\n        )\n        self.deployment_batch_size: int = (\n            PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE.value()\n        )\n        self.max_runs: int = PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS.value()\n        self.min_runs: int = PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS.value()\n        self.max_scheduled_time: datetime.timedelta = (\n            PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME.value()\n        )\n        self.min_scheduled_time: datetime.timedelta = (\n            PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME.value()\n        )\n        self.insert_batch_size = (\n            PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE.value()\n        )\n\n    @inject_db\n    async def run_once(self, db: PrefectDBInterface):\n        \"\"\"\n        Schedule flow runs by:\n\n        - Querying for deployments with active schedules\n        - Generating the next set of flow runs based on each deployments schedule\n        - Inserting all scheduled flow runs into the database\n\n        All inserted flow runs are committed to the database at the termination of the\n        loop.\n        \"\"\"\n        total_inserted_runs = 0\n\n        last_id = None\n        while True:\n            async with db.session_context(begin_transaction=False) as session:\n                query = self._get_select_deployments_to_schedule_query()\n\n                # use cursor based pagination\n                if last_id:\n                    query = query.where(db.Deployment.id &gt; last_id)\n\n                result = await session.execute(query)\n                deployment_ids = result.scalars().unique().all()\n\n                # collect runs across all deployments\n                try:\n                    runs_to_insert = await self._collect_flow_runs(\n                        session=session, deployment_ids=deployment_ids\n                    )\n                except TryAgain:\n                    continue\n\n            # bulk insert the runs based on batch size setting\n            for batch in batched_iterable(runs_to_insert, self.insert_batch_size):\n                async with db.session_context(begin_transaction=True) as session:\n                    inserted_runs = await self._insert_scheduled_flow_runs(\n                        session=session, runs=batch\n                    )\n                    total_inserted_runs += len(inserted_runs)\n\n            # if this is the last page of deployments, exit the loop\n            if len(deployment_ids) &lt; self.deployment_batch_size:\n                break\n            else:\n                # record the last deployment ID\n                last_id = deployment_ids[-1]\n\n        self.logger.info(f\"Scheduled {total_inserted_runs} runs.\")\n\n    @inject_db\n    def _get_select_deployments_to_schedule_query(self, db: PrefectDBInterface):\n        \"\"\"\n        Returns a sqlalchemy query for selecting deployments to schedule.\n\n        The query gets the IDs of any deployments with:\n\n            - an active schedule\n            - EITHER:\n                - fewer than `min_runs` auto-scheduled runs\n                - OR the max scheduled time is less than `max_scheduled_time` in the future\n        \"\"\"\n        now = pendulum.now(\"UTC\")\n        query = (\n            sa.select(db.Deployment.id)\n            .select_from(db.Deployment)\n            # TODO: on Postgres, this could be replaced with a lateral join that\n            # sorts by `next_scheduled_start_time desc` and limits by\n            # `self.min_runs` for a ~ 50% speedup. At the time of writing,\n            # performance of this universal query appears to be fast enough that\n            # this optimization is not worth maintaining db-specific queries\n            .join(\n                db.FlowRun,\n                # join on matching deployments, only picking up future scheduled runs\n                sa.and_(\n                    db.Deployment.id == db.FlowRun.deployment_id,\n                    db.FlowRun.state_type == StateType.SCHEDULED,\n                    db.FlowRun.next_scheduled_start_time &gt;= now,\n                    db.FlowRun.auto_scheduled.is_(True),\n                ),\n                isouter=True,\n            )\n            .where(\n                sa.and_(\n                    db.Deployment.paused.is_not(True),\n                    (\n                        # Only include deployments that have at least one\n                        # active schedule.\n                        sa.select(db.DeploymentSchedule.deployment_id)\n                        .where(\n                            sa.and_(\n                                db.DeploymentSchedule.deployment_id == db.Deployment.id,\n                                db.DeploymentSchedule.active.is_(True),\n                            )\n                        )\n                        .exists()\n                    ),\n                )\n            )\n            .group_by(db.Deployment.id)\n            # having EITHER fewer than three runs OR runs not scheduled far enough out\n            .having(\n                sa.or_(\n                    sa.func.count(db.FlowRun.next_scheduled_start_time) &lt; self.min_runs,\n                    sa.func.max(db.FlowRun.next_scheduled_start_time)\n                    &lt; now + self.min_scheduled_time,\n                )\n            )\n            .order_by(db.Deployment.id)\n            .limit(self.deployment_batch_size)\n        )\n        return query\n\n    async def _collect_flow_runs(\n        self,\n        session: sa.orm.Session,\n        deployment_ids: List[UUID],\n    ) -&gt; List[Dict]:\n        runs_to_insert = []\n        for deployment_id in deployment_ids:\n            now = pendulum.now(\"UTC\")\n            # guard against erroneously configured schedules\n            try:\n                runs_to_insert.extend(\n                    await self._generate_scheduled_flow_runs(\n                        session=session,\n                        deployment_id=deployment_id,\n                        start_time=now,\n                        end_time=now + self.max_scheduled_time,\n                        min_time=self.min_scheduled_time,\n                        min_runs=self.min_runs,\n                        max_runs=self.max_runs,\n                    )\n                )\n            except Exception:\n                self.logger.exception(\n                    f\"Error scheduling deployment {deployment_id!r}.\",\n                )\n            finally:\n                connection = await session.connection()\n                if connection.invalidated:\n                    # If the error we handled above was the kind of database error that\n                    # causes underlying transaction to rollback and the connection to\n                    # become invalidated, rollback this session.  Errors that may cause\n                    # this are connection drops, database restarts, and things of the\n                    # sort.\n                    #\n                    # This rollback _does not rollback a transaction_, since that has\n                    # actually already happened due to the error above.  It brings the\n                    # Python session in sync with underlying connection so that when we\n                    # exec the outer with block, the context manager will not attempt to\n                    # commit the session.\n                    #\n                    # Then, raise TryAgain to break out of these nested loops, back to\n                    # the outer loop, where we'll begin a new transaction with\n                    # session.begin() in the next loop iteration.\n                    await session.rollback()\n                    raise TryAgain()\n        return runs_to_insert\n\n    @inject_db\n    async def _generate_scheduled_flow_runs(\n        self,\n        session: sa.orm.Session,\n        deployment_id: UUID,\n        start_time: datetime.datetime,\n        end_time: datetime.datetime,\n        min_time: datetime.timedelta,\n        min_runs: int,\n        max_runs: int,\n        db: PrefectDBInterface,\n    ) -&gt; List[Dict]:\n        \"\"\"\n        Given a `deployment_id` and schedule params, generates a list of flow run\n        objects and associated scheduled states that represent scheduled flow runs.\n\n        Pass-through method for overrides.\n\n\n        Args:\n            session: a database session\n            deployment_id: the id of the deployment to schedule\n            start_time: the time from which to start scheduling runs\n            end_time: runs will be scheduled until at most this time\n            min_time: runs will be scheduled until at least this far in the future\n            min_runs: a minimum amount of runs to schedule\n            max_runs: a maximum amount of runs to schedule\n\n        This function will generate the minimum number of runs that satisfy the min\n        and max times, and the min and max counts. Specifically, the following order\n        will be respected:\n\n            - Runs will be generated starting on or after the `start_time`\n            - No more than `max_runs` runs will be generated\n            - No runs will be generated after `end_time` is reached\n            - At least `min_runs` runs will be generated\n            - Runs will be generated until at least `start_time + min_time` is reached\n\n        \"\"\"\n        return await models.deployments._generate_scheduled_flow_runs(\n            session=session,\n            deployment_id=deployment_id,\n            start_time=start_time,\n            end_time=end_time,\n            min_time=min_time,\n            min_runs=min_runs,\n            max_runs=max_runs,\n        )\n\n    @inject_db\n    async def _insert_scheduled_flow_runs(\n        self,\n        session: sa.orm.Session,\n        runs: List[Dict],\n        db: PrefectDBInterface,\n    ) -&gt; List[UUID]:\n        \"\"\"\n        Given a list of flow runs to schedule, as generated by\n        `_generate_scheduled_flow_runs`, inserts them into the database. Note this is a\n        separate method to facilitate batch operations on many scheduled runs.\n\n        Pass-through method for overrides.\n        \"\"\"\n        return await models.deployments._insert_scheduled_flow_runs(\n            session=session, runs=runs\n        )\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.Scheduler.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Schedule flow runs by:</p> <ul> <li>Querying for deployments with active schedules</li> <li>Generating the next set of flow runs based on each deployments schedule</li> <li>Inserting all scheduled flow runs into the database</li> </ul> <p>All inserted flow runs are committed to the database at the termination of the loop.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>@inject_db\nasync def run_once(self, db: PrefectDBInterface):\n    \"\"\"\n    Schedule flow runs by:\n\n    - Querying for deployments with active schedules\n    - Generating the next set of flow runs based on each deployments schedule\n    - Inserting all scheduled flow runs into the database\n\n    All inserted flow runs are committed to the database at the termination of the\n    loop.\n    \"\"\"\n    total_inserted_runs = 0\n\n    last_id = None\n    while True:\n        async with db.session_context(begin_transaction=False) as session:\n            query = self._get_select_deployments_to_schedule_query()\n\n            # use cursor based pagination\n            if last_id:\n                query = query.where(db.Deployment.id &gt; last_id)\n\n            result = await session.execute(query)\n            deployment_ids = result.scalars().unique().all()\n\n            # collect runs across all deployments\n            try:\n                runs_to_insert = await self._collect_flow_runs(\n                    session=session, deployment_ids=deployment_ids\n                )\n            except TryAgain:\n                continue\n\n        # bulk insert the runs based on batch size setting\n        for batch in batched_iterable(runs_to_insert, self.insert_batch_size):\n            async with db.session_context(begin_transaction=True) as session:\n                inserted_runs = await self._insert_scheduled_flow_runs(\n                    session=session, runs=batch\n                )\n                total_inserted_runs += len(inserted_runs)\n\n        # if this is the last page of deployments, exit the loop\n        if len(deployment_ids) &lt; self.deployment_batch_size:\n            break\n        else:\n            # record the last deployment ID\n            last_id = deployment_ids[-1]\n\n    self.logger.info(f\"Scheduled {total_inserted_runs} runs.\")\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.TryAgain","title":"<code>TryAgain</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Internal control-flow exception used to retry the Scheduler's main loop</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class TryAgain(Exception):\n    \"\"\"Internal control-flow exception used to retry the Scheduler's main loop\"\"\"\n</code></pre>"},{"location":"api-ref/server/utilities/database/","title":"server.utilities.database","text":""},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database","title":"<code>prefect.server.utilities.database</code>","text":"<p>Utilities for interacting with Prefect REST API database and ORM layer.</p> <p>Prefect supports both SQLite and Postgres. Many of these utilities allow the Prefect REST API to seamlessly switch between the two.</p>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.GenerateUUID","title":"<code>GenerateUUID</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent UUID default generator. Note the actual functionality for this class is specified in the <code>compiles</code>-decorated functions below</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class GenerateUUID(FunctionElement):\n    \"\"\"\n    Platform-independent UUID default generator.\n    Note the actual functionality for this class is specified in the\n    `compiles`-decorated functions below\n    \"\"\"\n\n    name = \"uuid_default\"\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.JSON","title":"<code>JSON</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>JSON type that returns SQLAlchemy's dialect-specific JSON types, where possible. Uses generic JSON otherwise.</p> <p>The \"base\" type is postgresql.JSONB to expose useful methods prior to SQL compilation</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class JSON(TypeDecorator):\n    \"\"\"\n    JSON type that returns SQLAlchemy's dialect-specific JSON types, where\n    possible. Uses generic JSON otherwise.\n\n    The \"base\" type is postgresql.JSONB to expose useful methods prior\n    to SQL compilation\n    \"\"\"\n\n    impl = postgresql.JSONB\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.JSONB(none_as_null=True))\n        elif dialect.name == \"sqlite\":\n            return dialect.type_descriptor(sqlite.JSON(none_as_null=True))\n        else:\n            return dialect.type_descriptor(sa.JSON(none_as_null=True))\n\n    def process_bind_param(self, value, dialect):\n        \"\"\"Prepares the given value to be used as a JSON field in a parameter binding\"\"\"\n        if not value:\n            return value\n\n        # PostgreSQL does not support the floating point extrema values `NaN`,\n        # `-Infinity`, or `Infinity`\n        # https://www.postgresql.org/docs/current/datatype-json.html#JSON-TYPE-MAPPING-TABLE\n        #\n        # SQLite supports storing and retrieving full JSON values that include\n        # `NaN`, `-Infinity`, or `Infinity`, but any query that requires SQLite to parse\n        # the value (like `json_extract`) will fail.\n        #\n        # Replace any `NaN`, `-Infinity`, or `Infinity` values with `None` in the\n        # returned value.  See more about `parse_constant` at\n        # https://docs.python.org/3/library/json.html#json.load.\n        return json.loads(json.dumps(value), parse_constant=lambda c: None)\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.Pydantic","title":"<code>Pydantic</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>A pydantic type that converts inserted parameters to json and converts read values to the pydantic type.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class Pydantic(TypeDecorator):\n    \"\"\"\n    A pydantic type that converts inserted parameters to\n    json and converts read values to the pydantic type.\n    \"\"\"\n\n    impl = JSON\n    cache_ok = True\n\n    def __init__(self, pydantic_type, sa_column_type=None):\n        super().__init__()\n        self._pydantic_type = pydantic_type\n        if sa_column_type is not None:\n            self.impl = sa_column_type\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        # parse the value to ensure it complies with the schema\n        # (this will raise validation errors if not)\n        value = pydantic.parse_obj_as(self._pydantic_type, value)\n        # sqlalchemy requires the bind parameter's value to be a python-native\n        # collection of JSON-compatible objects. we achieve that by dumping the\n        # value to a json string using the pydantic JSON encoder and re-parsing\n        # it into a python-native form.\n        return json.loads(json.dumps(value, default=pydantic.json.pydantic_encoder))\n\n    def process_result_value(self, value, dialect):\n        if value is not None:\n            # load the json object into a fully hydrated typed object\n            return pydantic.parse_obj_as(self._pydantic_type, value)\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.Timestamp","title":"<code>Timestamp</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>TypeDecorator that ensures that timestamps have a timezone.</p> <p>For SQLite, all timestamps are converted to UTC (since they are stored as naive timestamps without timezones) and recovered as UTC.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class Timestamp(TypeDecorator):\n    \"\"\"TypeDecorator that ensures that timestamps have a timezone.\n\n    For SQLite, all timestamps are converted to UTC (since they are stored\n    as naive timestamps without timezones) and recovered as UTC.\n    \"\"\"\n\n    impl = sa.TIMESTAMP(timezone=True)\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.TIMESTAMP(timezone=True))\n        elif dialect.name == \"sqlite\":\n            return dialect.type_descriptor(\n                sqlite.DATETIME(\n                    # SQLite is very particular about datetimes, and performs all comparisons\n                    # as alphanumeric comparisons without regard for actual timestamp\n                    # semantics or timezones. Therefore, it's important to have uniform\n                    # and sortable datetime representations. The default is an ISO8601-compatible\n                    # string with NO time zone and a space (\" \") delimiter between the date\n                    # and the time. The below settings can be used to add a \"T\" delimiter but\n                    # will require all other sqlite datetimes to be set similarly, including\n                    # the custom default value for datetime columns and any handwritten SQL\n                    # formed with `strftime()`.\n                    #\n                    # store with \"T\" separator for time\n                    # storage_format=(\n                    #     \"%(year)04d-%(month)02d-%(day)02d\"\n                    #     \"T%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d\"\n                    # ),\n                    # handle ISO 8601 with \"T\" or \" \" as the time separator\n                    # regexp=r\"(\\d+)-(\\d+)-(\\d+)[T ](\\d+):(\\d+):(\\d+).(\\d+)\",\n                )\n            )\n        else:\n            return dialect.type_descriptor(sa.TIMESTAMP(timezone=True))\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        else:\n            if value.tzinfo is None:\n                raise ValueError(\"Timestamps must have a timezone.\")\n            elif dialect.name == \"sqlite\":\n                return pendulum.instance(value).in_timezone(\"UTC\")\n            else:\n                return value\n\n    def process_result_value(self, value, dialect):\n        # retrieve timestamps in their native timezone (or UTC)\n        if value is not None:\n            return pendulum.instance(value).in_timezone(\"utc\")\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.UUID","title":"<code>UUID</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>Platform-independent UUID type.</p> <p>Uses PostgreSQL's UUID type, otherwise uses CHAR(36), storing as stringified hex values with hyphens.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class UUID(TypeDecorator):\n    \"\"\"\n    Platform-independent UUID type.\n\n    Uses PostgreSQL's UUID type, otherwise uses\n    CHAR(36), storing as stringified hex values with\n    hyphens.\n    \"\"\"\n\n    impl = TypeEngine\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.UUID())\n        else:\n            return dialect.type_descriptor(CHAR(36))\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        elif dialect.name == \"postgresql\":\n            return str(value)\n        elif isinstance(value, uuid.UUID):\n            return str(value)\n        else:\n            return str(uuid.UUID(value))\n\n    def process_result_value(self, value, dialect):\n        if value is None:\n            return value\n        else:\n            if not isinstance(value, uuid.UUID):\n                value = uuid.UUID(value)\n            return value\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.date_add","title":"<code>date_add</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent way to add a date and an interval.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class date_add(FunctionElement):\n    \"\"\"\n    Platform-independent way to add a date and an interval.\n    \"\"\"\n\n    type = Timestamp()\n    name = \"date_add\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, dt, interval):\n        self.dt = dt\n        self.interval = interval\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.date_diff","title":"<code>date_diff</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent difference of dates. Computes d1 - d2.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class date_diff(FunctionElement):\n    \"\"\"\n    Platform-independent difference of dates. Computes d1 - d2.\n    \"\"\"\n\n    type = sa.Interval()\n    name = \"date_diff\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, d1, d2):\n        self.d1 = d1\n        self.d2 = d2\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.interval_add","title":"<code>interval_add</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent way to add two intervals.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class interval_add(FunctionElement):\n    \"\"\"\n    Platform-independent way to add two intervals.\n    \"\"\"\n\n    type = sa.Interval()\n    name = \"interval_add\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, i1, i2):\n        self.i1 = i1\n        self.i2 = i2\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_contains","title":"<code>json_contains</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_contains operator, tests if the <code>left</code> expression contains the <code>right</code> expression.</p> <p>On postgres this is equivalent to the @&gt; containment operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_contains(FunctionElement):\n    \"\"\"\n    Platform independent json_contains operator, tests if the\n    `left` expression contains the `right` expression.\n\n    On postgres this is equivalent to the @&gt; containment operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_contains\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, left, right):\n        self.left = left\n        self.right = right\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_extract","title":"<code>json_extract</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_extract operator, extracts a value from a JSON field via key.</p> <p>On postgres this is equivalent to the -&gt;&gt; operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_extract(FunctionElement):\n    \"\"\"\n    Platform independent json_extract operator, extracts a value from a JSON\n    field via key.\n\n    On postgres this is equivalent to the -&gt;&gt; operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = sa.Text()\n    name = \"json_extract\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, column: sa.Column, path: str, wrap_quotes: bool = False):\n        self.column = column\n        self.path = path\n        self.wrap_quotes = wrap_quotes\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_has_all_keys","title":"<code>json_has_all_keys</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_has_all_keys operator.</p> <p>On postgres this is equivalent to the ?&amp; existence operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_has_all_keys(FunctionElement):\n    \"\"\"Platform independent json_has_all_keys operator.\n\n    On postgres this is equivalent to the ?&amp; existence operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_has_all_keys\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, json_expr, values: List):\n        self.json_expr = json_expr\n        if isinstance(values, list) and not all(isinstance(v, str) for v in values):\n            raise ValueError(\n                \"json_has_all_key values must be strings if provided as a literal list\"\n            )\n        self.values = values\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_has_any_key","title":"<code>json_has_any_key</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_has_any_key operator.</p> <p>On postgres this is equivalent to the ?| existence operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_has_any_key(FunctionElement):\n    \"\"\"\n    Platform independent json_has_any_key operator.\n\n    On postgres this is equivalent to the ?| existence operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_has_any_key\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, json_expr, values: List):\n        self.json_expr = json_expr\n        if not all(isinstance(v, str) for v in values):\n            raise ValueError(\"json_has_any_key values must be strings\")\n        self.values = values\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.now","title":"<code>now</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent \"now\" generator.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class now(FunctionElement):\n    \"\"\"\n    Platform-independent \"now\" generator.\n    \"\"\"\n\n    type = Timestamp()\n    name = \"now\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = True\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.get_dialect","title":"<code>get_dialect</code>","text":"<p>Get the dialect of a session, engine, or connection url.</p> <p>Primary use case is figuring out whether the Prefect REST API is communicating with SQLite or Postgres.</p> Example <pre><code>import prefect.settings\nfrom prefect.server.utilities.database import get_dialect\n\ndialect = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value())\nif dialect.name == \"sqlite\":\n    print(\"Using SQLite!\")\nelse:\n    print(\"Using Postgres!\")\n</code></pre> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>def get_dialect(\n    obj: Union[str, sa.orm.Session, sa.engine.Engine],\n) -&gt; sa.engine.Dialect:\n    \"\"\"\n    Get the dialect of a session, engine, or connection url.\n\n    Primary use case is figuring out whether the Prefect REST API is communicating with\n    SQLite or Postgres.\n\n    Example:\n        ```python\n        import prefect.settings\n        from prefect.server.utilities.database import get_dialect\n\n        dialect = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value())\n        if dialect.name == \"sqlite\":\n            print(\"Using SQLite!\")\n        else:\n            print(\"Using Postgres!\")\n        ```\n    \"\"\"\n    if isinstance(obj, sa.orm.Session):\n        url = obj.bind.url\n    elif isinstance(obj, sa.engine.Engine):\n        url = obj.url\n    else:\n        url = sa.engine.url.make_url(obj)\n\n    return url.get_dialect()\n</code></pre>"},{"location":"api-ref/server/utilities/schemas/","title":"server.utilities.schemas","text":""},{"location":"api-ref/server/utilities/schemas/#prefect.server.utilities.schemas","title":"<code>prefect.server.utilities.schemas</code>","text":""},{"location":"api-ref/server/utilities/server/","title":"server.utilities.server","text":""},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server","title":"<code>prefect.server.utilities.server</code>","text":"<p>Utilities for the Prefect REST API server.</p>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectAPIRoute","title":"<code>PrefectAPIRoute</code>","text":"<p>               Bases: <code>APIRoute</code></p> <p>A FastAPIRoute class which attaches an async stack to requests that exits before a response is returned.</p> <p>Requests already have <code>request.scope['fastapi_astack']</code> which is an async stack for the full scope of the request. This stack is used for managing contexts of FastAPI dependencies. If we want to close a dependency before the request is complete (i.e. before returning a response to the user), we need a stack with a different scope. This extension adds this stack at <code>request.state.response_scoped_stack</code>.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>class PrefectAPIRoute(APIRoute):\n    \"\"\"\n    A FastAPIRoute class which attaches an async stack to requests that exits before\n    a response is returned.\n\n    Requests already have `request.scope['fastapi_astack']` which is an async stack for\n    the full scope of the request. This stack is used for managing contexts of FastAPI\n    dependencies. If we want to close a dependency before the request is complete\n    (i.e. before returning a response to the user), we need a stack with a different\n    scope. This extension adds this stack at `request.state.response_scoped_stack`.\n    \"\"\"\n\n    def get_route_handler(self) -&gt; Callable[[Request], Coroutine[Any, Any, Response]]:\n        default_handler = super().get_route_handler()\n\n        async def handle_response_scoped_depends(request: Request) -&gt; Response:\n            # Create a new stack scoped to exit before the response is returned\n            async with AsyncExitStack() as stack:\n                request.state.response_scoped_stack = stack\n                response = await default_handler(request)\n\n            return response\n\n        return handle_response_scoped_depends\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectRouter","title":"<code>PrefectRouter</code>","text":"<p>               Bases: <code>APIRouter</code></p> <p>A base class for Prefect REST API routers.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>class PrefectRouter(APIRouter):\n    \"\"\"\n    A base class for Prefect REST API routers.\n    \"\"\"\n\n    def __init__(self, **kwargs: Any) -&gt; None:\n        kwargs.setdefault(\"route_class\", PrefectAPIRoute)\n        super().__init__(**kwargs)\n\n    def add_api_route(\n        self, path: str, endpoint: Callable[..., Any], **kwargs: Any\n    ) -&gt; None:\n        \"\"\"\n        Add an API route.\n\n        For routes that return content and have not specified a `response_model`,\n        use return type annotation to infer the response model.\n\n        For routes that return No-Content status codes, explicitly set\n        a `response_class` to ensure nothing is returned in the response body.\n        \"\"\"\n        if kwargs.get(\"status_code\") == status.HTTP_204_NO_CONTENT:\n            # any routes that return No-Content status codes must\n            # explicitly set a response_class that will handle status codes\n            # and not return anything in the body\n            kwargs[\"response_class\"] = Response\n        if kwargs.get(\"response_model\") is None:\n            kwargs[\"response_model\"] = get_type_hints(endpoint).get(\"return\")\n        return super().add_api_route(path, endpoint, **kwargs)\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectRouter.add_api_route","title":"<code>add_api_route</code>","text":"<p>Add an API route.</p> <p>For routes that return content and have not specified a <code>response_model</code>, use return type annotation to infer the response model.</p> <p>For routes that return No-Content status codes, explicitly set a <code>response_class</code> to ensure nothing is returned in the response body.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def add_api_route(\n    self, path: str, endpoint: Callable[..., Any], **kwargs: Any\n) -&gt; None:\n    \"\"\"\n    Add an API route.\n\n    For routes that return content and have not specified a `response_model`,\n    use return type annotation to infer the response model.\n\n    For routes that return No-Content status codes, explicitly set\n    a `response_class` to ensure nothing is returned in the response body.\n    \"\"\"\n    if kwargs.get(\"status_code\") == status.HTTP_204_NO_CONTENT:\n        # any routes that return No-Content status codes must\n        # explicitly set a response_class that will handle status codes\n        # and not return anything in the body\n        kwargs[\"response_class\"] = Response\n    if kwargs.get(\"response_model\") is None:\n        kwargs[\"response_model\"] = get_type_hints(endpoint).get(\"return\")\n    return super().add_api_route(path, endpoint, **kwargs)\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.method_paths_from_routes","title":"<code>method_paths_from_routes</code>","text":"<p>Generate a set of strings describing the given routes in the format:  <p>For example, \"GET /logs/\"</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def method_paths_from_routes(routes: Sequence[BaseRoute]) -&gt; Set[str]:\n    \"\"\"\n    Generate a set of strings describing the given routes in the format: &lt;method&gt; &lt;path&gt;\n\n    For example, \"GET /logs/\"\n    \"\"\"\n    method_paths = set()\n    for route in routes:\n        if isinstance(route, (APIRoute, StarletteRoute)):\n            for method in route.methods:\n                method_paths.add(f\"{method} {route.path}\")\n\n    return method_paths\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.response_scoped_dependency","title":"<code>response_scoped_dependency</code>","text":"<p>Ensure that this dependency closes before the response is returned to the client. By default, FastAPI closes dependencies after sending the response.</p> <p>Uses an async stack that is exited before the response is returned. This is particularly useful for database sessions which must be committed before the client can do more work.</p> Do not use a response-scoped dependency within a FastAPI background task. <p>Background tasks run after FastAPI sends the response, so a response-scoped dependency will already be closed. Use a normal FastAPI dependency instead.</p> <p>Parameters:</p> Name Type Description Default <code>dependency</code> <code>Callable</code> <p>An async callable. FastAPI dependencies may still be used.</p> required <p>Returns:</p> Type Description <p>A wrapped <code>dependency</code> which will push the <code>dependency</code> context manager onto</p> <p>a stack when called.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def response_scoped_dependency(dependency: Callable):\n    \"\"\"\n    Ensure that this dependency closes before the response is returned to the client. By\n    default, FastAPI closes dependencies after sending the response.\n\n    Uses an async stack that is exited before the response is returned. This is\n    particularly useful for database sessions which must be committed before the client\n    can do more work.\n\n    NOTE: Do not use a response-scoped dependency within a FastAPI background task.\n          Background tasks run after FastAPI sends the response, so a response-scoped\n          dependency will already be closed. Use a normal FastAPI dependency instead.\n\n    Args:\n        dependency: An async callable. FastAPI dependencies may still be used.\n\n    Returns:\n        A wrapped `dependency` which will push the `dependency` context manager onto\n        a stack when called.\n    \"\"\"\n    signature = inspect.signature(dependency)\n\n    async def wrapper(*args, request: Request, **kwargs):\n        # Replicate FastAPI behavior of auto-creating a context manager\n        if inspect.isasyncgenfunction(dependency):\n            context_manager = asynccontextmanager(dependency)\n        else:\n            context_manager = dependency\n\n        # Ensure request is provided if requested\n        if \"request\" in signature.parameters:\n            kwargs[\"request\"] = request\n\n        # Enter the route handler provided stack that is closed before responding,\n        # return the value yielded by the wrapped dependency\n        return await request.state.response_scoped_stack.enter_async_context(\n            context_manager(*args, **kwargs)\n        )\n\n    # Ensure that the signature includes `request: Request` to ensure that FastAPI will\n    # inject the request as a dependency; maintain the old signature so those depends\n    # work\n    request_parameter = inspect.signature(wrapper).parameters[\"request\"]\n    functools.update_wrapper(wrapper, dependency)\n\n    if \"request\" not in signature.parameters:\n        new_parameters = signature.parameters.copy()\n        new_parameters[\"request\"] = request_parameter\n        wrapper.__signature__ = signature.replace(\n            parameters=tuple(new_parameters.values())\n        )\n\n    return wrapper\n</code></pre>"},{"location":"cloud/","title":"Welcome to Prefect Cloud","text":"<p>Prefect Cloud is a hosted workflow application framework that provides all the capabilities of Prefect server plus additional features, such as:</p> <ul> <li>automations, events, and webhooks so you can create event-driven workflows</li> <li>workspaces, RBAC, SSO, audit logs and related user management tools for collaboration</li> <li>push work pools for running flows on serverless infrastructure without a worker</li> <li>error summaries powered by Marvin AI to help you resolve errors faster</li> </ul> <p>Getting Started with Prefect Cloud</p> <p>Ready to jump right in and start running with Prefect Cloud? See the Quickstart and follow the instructions on the Cloud tabs to write and deploy your first Prefect Cloud-monitored flow run.</p> <p></p> <p>Prefect Cloud includes all the features in the open-source Prefect server plus the following:</p> <p>Prefect Cloud features</p> <ul> <li>User accounts \u2014 personal accounts for working in Prefect Cloud.</li> <li>Workspaces \u2014 isolated environments to organize your flows, deployments, and flow runs.</li> <li>Automations \u2014 configure triggers, actions, and notifications in response to real-time monitoring events.</li> <li>Email notifications \u2014 send email alerts from Prefect's server based on automation triggers.</li> <li>Service accounts \u2014 configure API access for running workers or executing flow runs on remote infrastructure.</li> <li>Custom role-based access controls (RBAC) \u2014 assign users granular permissions to perform certain activities within an account or a workspace.</li> <li>Single Sign-on (SSO) \u2014 authentication using your identity provider.</li> <li>Audit Log \u2014 a record of user activities to monitor security and compliance.</li> <li>Collaboration \u2014 invite other people to your account.</li> <li>Error summaries  \u2014 (enabled by Marvin AI) distill the error logs of <code>Failed</code> and <code>Crashed</code> flow runs into actionable information.</li> <li>Push work pools \u2014 run flows on your serverless infrastructure without running a worker.</li> </ul>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#user-accounts","title":"User accounts","text":"<p>When you sign up for Prefect Cloud, an account and a user profile are automatically provisioned for you.</p> <p>Your profile is the place where you'll manage settings related to yourself as a user, including:</p> <ul> <li>Profile, including profile handle and image</li> <li>API keys</li> <li>Preferences, including timezone and color mode</li> </ul> <p>As an account Admin, you will also have access to account settings from the Account Settings page, such as:</p> <ul> <li>Members</li> <li>Workspaces</li> <li>Roles</li> </ul> <p>As an account Admin you can create a workspace and invite other individuals to your workspace.</p> <p>Upgrading from a Prefect Cloud Free tier plan to a Pro or Custom tier plan enables additional functionality for adding workspaces, managing teams, and running higher volume workloads.</p> <p>Workspace Admins for Pro tier plans have the ability to set role-based access controls (RBAC), view Audit Logs, and configure service accounts.</p> <p>Custom plans have object-level access control lists, custom roles, teams, and [single sign-on (SSO)](#single-sign-on-(sso) with Directory Sync/SCIM provisioning.</p> <p>Prefect Cloud plans for teams of every size</p> <p>See the Prefect Cloud plans for details on Pro and Custom account tiers.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#workspaces","title":"Workspaces","text":"<p>A workspace is an isolated environment within Prefect Cloud for your flows, deployments, and block configuration. See the Workspaces documentation for more information about configuring and using workspaces.</p> <p>Each workspace keeps track of its own:</p> <ul> <li>Flow runs and task runs executed in an environment that is syncing with the workspace</li> <li>Flows associated with flow runs and deployments observed by the Prefect Cloud API</li> <li>Deployments</li> <li>Work pools</li> <li>Blocks and storage</li> <li>Events</li> <li>Automations</li> <li>Incidents</li> </ul> <p></p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#events","title":"Events","text":"<p>Prefect Cloud allows you to see your events. Events provide information about the state of your workflows, and can be used as automation triggers.</p> <p></p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#automations","title":"Automations","text":"<p>Prefect Cloud automations provide additional notification capabilities beyond those in a self-hosted open-source Prefect server. Automations also enable you to create event-driven workflows, toggle resources such as schedules and work pools, and declare incidents.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#incidents","title":"Incidents","text":"<p>Prefect Cloud's incidents help teams identify, rectify, and document issues in mission-critical workflows. Incidents are formal declarations of disruptions to a workspace. With automations), activity in that workspace can be paused when an incident is created and resumed when it is resolved.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#error-summaries","title":"Error summaries","text":"<p>Prefect Cloud error summaries, enabled by Marvin AI, distill the error logs of <code>Failed</code> and <code>Crashed</code> flow runs into actionable information. To enable this feature and others powered by Marvin AI, visit the Settings page for your account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#service-accounts","title":"Service accounts","text":"<p>Service accounts enable you to create Prefect Cloud API keys that are not associated with a user account. Service accounts are typically used to configure API access for running workers or executing flow runs on remote infrastructure. See the service accounts documentation for more information about creating and managing service accounts.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#roles-and-custom-permissions","title":"Roles and custom permissions","text":"<p>Role-based access controls (RBAC) enable you to assign users a role with permissions to perform certain activities within an account or a workspace. See the role-based access controls (RBAC) documentation for more information about managing user roles in a Prefect Cloud account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#single-sign-on-sso","title":"Single Sign-on (SSO)","text":"<p>Prefect Cloud's Pro and Custom plans offer single sign-on (SSO) authentication integration with your team\u2019s identity provider. SSO integration can bet set up with identity providers that support OIDC and SAML. Directory Sync and SCIM provisioning is also available with Custom plans.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#audit-log","title":"Audit log","text":"<p>Prefect Cloud's Pro and Custom plans offer Audit Logs for compliance and security. Audit logs provide a chronological record of activities performed by users in an account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#prefect-cloud-rest-api","title":"Prefect Cloud REST API","text":"<p>The Prefect REST API is used for communicating data from Prefect clients to Prefect Cloud or a local Prefect server for orchestration and monitoring. This API is mainly consumed by Prefect clients like the Prefect Python Client or the Prefect UI.</p> <p>Prefect Cloud REST API interactive documentation</p> <p>Prefect Cloud REST API documentation is available at https://app.prefect.cloud/api/docs.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#start-using-prefect-cloud","title":"Start using Prefect Cloud","text":"<p>To create an account or sign in with an existing Prefect Cloud account, go to https://app.prefect.cloud/.</p> <p>Then follow the steps in the UI to deploy your first Prefect Cloud-monitored flow run. For more details, see the Prefect Quickstart and follow the instructions on the Cloud tabs.</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/connecting/","title":"Connecting &amp; Troubleshooting Prefect Cloud","text":"<p>To create flow runs in a local or remote execution environment and use either Prefect Cloud or a Prefect server as the backend API server, you need to  </p> <ul> <li>Configure the execution environment with the location of the API.</li> <li>Authenticate with the API, either by logging in or providing a valid API key (Prefect Cloud only).</li> </ul>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#log-into-prefect-cloud-from-a-terminal","title":"Log into Prefect Cloud from a terminal","text":"<p>Configure a local execution environment to use Prefect Cloud as the API server for flow runs. In other words, \"log in\" to Prefect Cloud from a local environment where you want to run a flow.</p> <ol> <li>Open a new terminal session.</li> <li>Install Prefect in the environment in which you want to execute flow runs.</li> </ol> <pre><code>$ pip install -U prefect\n</code></pre> <ol> <li>Use the <code>prefect cloud login</code> Prefect CLI command to log into Prefect Cloud from your environment.</li> </ol> <pre><code>$ prefect cloud login\n</code></pre> <p>The <code>prefect cloud login</code> command, used on its own, provides an interactive login experience. Using this command, you can log in with either an API key or through a browser.</p> <pre><code>$ prefect cloud login\n? How would you like to authenticate? [Use arrows to move; enter to select]\n&gt; Log in with a web browser\n    Paste an API key\nPaste your authentication key:\n? Which workspace would you like to use? [Use arrows to move; enter to select]\n&gt; prefect/terry-prefect-workspace\n    g-gadflow/g-workspace\nAuthenticated with Prefect Cloud! Using workspace 'prefect/terry-prefect-workspace'.\n</code></pre> <p>You can also log in by providing a Prefect Cloud API key that you create.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#change-workspaces","title":"Change workspaces","text":"<p>If you need to change which workspace you're syncing with, use the <code>prefect cloud workspace set</code> Prefect CLI command while logged in, passing the account handle and workspace name.</p> <pre><code>$ prefect cloud workspace set --workspace \"prefect/my-workspace\"\n</code></pre> <p>If no workspace is provided, you will be prompted to select one.</p> <p>Workspace Settings also shows you the <code>prefect cloud workspace set</code> Prefect CLI command you can use to sync a local execution environment with a given workspace.</p> <p>You may also use the <code>prefect cloud login</code> command with the <code>--workspace</code> or <code>-w</code> option to set the current workspace.</p> <pre><code>$ prefect cloud login --workspace \"prefect/my-workspace\"\n</code></pre>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#manually-configure-prefect-api-settings","title":"Manually configure Prefect API settings","text":"<p>You can also manually configure the <code>PREFECT_API_URL</code> setting to specify the Prefect Cloud API.</p> <p>For Prefect Cloud, you can configure the <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> settings to authenticate with Prefect Cloud by using an account ID, workspace ID, and API key.</p> <pre><code>$ prefect config set PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n$ prefect config set PREFECT_API_KEY=\"[API-KEY]\"\n</code></pre> <p>When you're in a Prefect Cloud workspace, you can copy the <code>PREFECT_API_URL</code> value directly from the page URL.</p> <p>In this example, we configured <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> in the default profile. You can use <code>prefect profile</code> CLI commands to create settings profiles for different configurations. For example, you could have a \"cloud\" profile configured to use the Prefect Cloud API URL and API key, and another \"local\" profile for local development using a local Prefect API server started with <code>prefect server start</code>. See Settings for details.</p> <p>Environment variables</p> <p>You can also set <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as you would any other environment variable. See Overriding defaults with environment variables for more information.</p> <p>See the Flow orchestration with Prefect tutorial for examples.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#install-requirements-in-execution-environments","title":"Install requirements in execution environments","text":"<p>In local and remote execution environments \u2014 such as VMs and containers \u2014 you must make sure any flow requirements or dependencies have been installed before creating a flow run.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#troubleshooting-prefect-cloud","title":"Troubleshooting Prefect Cloud","text":"<p>This section provides tips that may be helpful if you run into problems using Prefect Cloud.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-and-proxies","title":"Prefect Cloud and proxies","text":"<p>Proxies intermediate network requests between a server and a client.</p> <p>To communicate with Prefect Cloud, the Prefect client library makes HTTPS requests. These requests are made using the <code>httpx</code> Python library. <code>httpx</code> respects accepted proxy environment variables, so the Prefect client is able to communicate through proxies.</p> <p>To enable communication via proxies, simply set the <code>HTTPS_PROXY</code> and <code>SSL_CERT_FILE</code> environment variables as appropriate in your execution environment and things should \u201cjust work.\u201d</p> <p>See the Using Prefect Cloud with proxies topic in Prefect Discourse for examples of proxy configuration.</p> <p>URLs that should be whitelisted for outbound-communication in a secure environment include the UI, the API, Authentication, and the current OCSP server:  </p> <ul> <li>app.prefect.cloud</li> <li>api.prefect.cloud</li> <li>auth.workos.com</li> <li>api.github.com</li> <li>github.com</li> <li>ocsp.pki.goog/s/gts1d4/OxYEb8XcYmo</li> </ul>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-access-via-api","title":"Prefect Cloud access via API","text":"<p>If the Prefect Cloud API key, environment variable settings, or account login for your execution environment are not configured correctly, you may experience errors or unexpected flow run results when using Prefect CLI commands, running flows, or observing flow run results in Prefect Cloud.</p> <p>Use the <code>prefect config view</code> CLI command to make sure your execution environment is correctly configured to access Prefect Cloud.</p> <pre><code>$ prefect config view\nPREFECT_PROFILE='cloud'\nPREFECT_API_KEY='pnu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' (from profile)\nPREFECT_API_URL='https://api.prefect.cloud/api/accounts/...' (from profile)\n</code></pre> <p>Make sure <code>PREFECT_API_URL</code> is configured to use <code>https://api.prefect.cloud/api/...</code>.</p> <p>Make sure <code>PREFECT_API_KEY</code> is configured to use a valid API key.</p> <p>You can use the <code>prefect cloud workspace ls</code> CLI command to view or set the active workspace.</p> <pre><code>$ prefect cloud workspace ls\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503   Available Workspaces: \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502   g-gadflow/g-workspace \u2502\n\u2502    * prefect/workinonit \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n    * active workspace\n</code></pre> <p>You can also check that the account and workspace IDs specified in the URL for <code>PREFECT_API_URL</code> match those shown in the URL bar for your Prefect Cloud workspace.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-login-errors","title":"Prefect Cloud login errors","text":"<p>If you're having difficulty logging in to Prefect Cloud, the following troubleshooting steps may resolve the issue, or will provide more information when sharing your case to the support channel.</p> <ul> <li>Are you logging into Prefect Cloud 2? Prefect Cloud 1 and Prefect Cloud 2 use separate accounts. Make sure to use the right Prefect Cloud 2 URL: https://app.prefect.cloud/</li> <li>Do you already have a Prefect Cloud account? If you\u2019re having difficulty accepting an invitation, try creating an account first using the email associated with the invitation, then accept the invitation.</li> <li>Are you using a single sign-on (SSO) provider, social authentication (Google, Microsoft, or GitHub) or just using an emailed link?</li> </ul> <p>Other tips to help with login difficulties:</p> <ul> <li>Hard refresh your browser with Cmd+Shift+R.</li> <li>Try in a different browser. We actively test against the following browsers:</li> <li>Chrome</li> <li>Edge</li> <li>Firefox</li> <li>Safari</li> <li>Clear recent browser history/cookies</li> </ul> <p>None of this worked?</p> <p>Email us at help@prefect.io and provide answers to the questions above in your email to make it faster to troubleshoot and unblock you. Make sure you add the email address with which you were trying to log in, your Prefect Cloud account name, and, if applicable, the organization to which it belongs.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/events/","title":"Events","text":"<p>An event is a notification of a change. Together, events form a feed of activity recording what's happening across your stack.</p> <p>Events power several features in Prefect Cloud, including flow run logs, audit logs, and automations.</p> <p>Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.</p> <p>Events enable observability into your data stack via the event feed, and the configuration of Prefect's reactivity via automations.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-specification","title":"Event specification","text":"<p>Events adhere to a structured specification.</p> <p></p> Name Type Required? Description occurred String yes When the event happened event String yes The name of the event that happened resource Object yes The primary Resource this event concerns related Array no A list of additional Resources involved in this event payload Object no An open-ended set of data describing what happened id String yes The client-provided identifier of this event follows String no The ID of an event that is known to have occurred prior to this one.","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-grammar","title":"Event grammar","text":"<p>Generally, events have a consistent and informative grammar - an event describes a resource and an action that the resource took or that was taken on that resource. For example, events emitted by Prefect objects take the form of:</p> <pre><code>prefect.block.write-method.called\nprefect-cloud.automation.action.executed\nprefect-cloud.user.logged-in\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-sources","title":"Event sources","text":"<p>Events are automatically emitted by all Prefect objects, including flows, tasks, deployments, work queues, and logs. Prefect-emitted events will contain the <code>prefect</code> or <code>prefect-cloud</code> resource prefix. Events can also be sent to the Prefect events API via authenticated http request.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#emit-custom-events-from-python-code","title":"Emit custom events from Python code","text":"<p>The Prefect Python SDK provides an <code>emit_event</code> function that emits an Prefect event when called. The function can be called inside or outside of a task or flow. Running the following code will emit an event to Prefect Cloud, which will validate and ingest the event data.</p> <pre><code>from prefect.events import emit_event\n\ndef some_function(name: str=\"kiki\") -&gt; None:\n    print(f\"hi {name}!\")\n    emit_event(event=f\"{name}.sent.event!\", resource={\"prefect.resource.id\": f\"coder.{name}\"})\n\nsome_function()\n</code></pre> <p>Note that the <code>emit_event</code> arguments shown above are required: <code>event</code> represents the name of the event and <code>resource={\"prefect.resource.id\": \"my_string\"}</code> is the resource id.  To get data into an event for use in an automation action, you can specify a dictionary of values for the <code>payload</code> parameter. </p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#emit-events-via-webhooks","title":"Emit events via webhooks","text":"<p>Prefect Cloud offers programmable webhooks to receive HTTP requests from other systems and translate them into events within your workspace.  Webhooks can emit pre-defined static events, dynamic events that use portions of the incoming HTTP request, or events derived from CloudEvents.</p> <p>Events emitted from any source will appear in the event feed, where you can visualize activity in context and configure automations to react to the presence or absence of it in the future. </p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#resources","title":"Resources","text":"<p>Every event has a primary resource, which describes the object that emitted an event. Resources are used as quasi-stable identifiers for sources of events, and are constructed as dot-delimited strings, for example:</p> <pre><code>prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0\nacme.user.kiki.elt_script_1\nprefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6\n</code></pre> <p>Resources can optionally have additional arbitrary labels which can be used in event aggregation queries, such as:</p> <pre><code>\"resource\": {\n    \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3\",\n    \"prefect-cloud.action.type\": \"call-webhook\"\n    }\n</code></pre> <p>Events can optionally contain related resources, used to associate the event with other resources, such as in the case that the primary resource acted on or with another resource:</p> <pre><code>\"resource\": {\n    \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0\",\n    \"prefect-cloud.action.type\": \"call-webhook\"\n  },\n\"related\": [\n  {\n      \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3\",\n      \"prefect.resource.role\": \"automation\",\n      \"prefect-cloud.name\": \"webhook_body_demo\",\n      \"prefect-cloud.posture\": \"Reactive\"\n  }\n]\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#events-in-the-cloud-ui","title":"Events in the Cloud UI","text":"<p>Prefect Cloud provides an interactive dashboard to analyze and take action on events that occurred in your workspace on the event feed page.</p> <p></p> <p>The event feed is the primary place to view, search, and filter events to understand activity across your stack. Each entry displays data on the resource, related resource, and event that took place.</p> <p>You can view more information about an event by clicking into it, where you can view the full details of an event's resource, related resources, and its payload.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#reacting-to-events","title":"Reacting to events","text":"<p>From an event page, you can configure an automation to trigger on the observation of matching events or a lack of matching events by clicking the automate button in the overflow menu:</p> <p></p> <p>The default trigger configuration will fire every time it sees an event with a matching resource identifier. Advanced configuration is possible via custom triggers.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/incidents/","title":"Incidents","text":"","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#overview","title":"Overview","text":"<p>Incidents are a Prefect Cloud feature to help your team manage workflow disruptions. Incidents help you identify, resolve, and document issues with mission-critical workflows. This system enhances operational efficiency by automating the incident management process and providing a centralized platform for collaboration and compliance.</p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#what-are-incidents","title":"What are incidents?","text":"<p>Incidents are formal declarations of disruptions to a workspace. With automations, activity in a workspace can be paused when an incident is created and resumed when it is resolved.</p> <p>Incidents vary in nature and severity, ranging from minor glitches to critical system failures. Prefect Cloud enables users to effectively and automatically track and manage these incidents, ensuring minimal impact on operational continuity.</p> <p></p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#why-use-incident-management","title":"Why use incident management?","text":"<ol> <li> <p>Automated detection and reporting: Incidents can be automatically identified based on specific triggers or manually reported by team members, facilitating prompt response.</p> </li> <li> <p>Collaborative problem-solving: The platform fosters collaboration, allowing team members to share insights, discuss resolutions, and track contributions.</p> </li> <li> <p>Comprehensive impact assessment: Users gain insights into the incident's influence on workflows, helping in prioritizing response efforts.</p> </li> <li> <p>Compliance with incident management processes: Detailed documentation and reporting features support compliance with incident management systems.</p> </li> <li> <p>Enhanced operational transparency: The system provides a transparent view of both ongoing and resolved incidents, promoting accountability and continuous improvement.</p> </li> </ol> <p></p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#how-to-use-incident-management-in-prefect-cloud","title":"How to use incident management in Prefect Cloud","text":"","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#creating-an-incident","title":"Creating an incident","text":"<p>There are several ways to create an incident:</p> <ol> <li> <p>From the Incidents page:</p> <ul> <li>Click on the + button.</li> <li>Fill in required fields and attach any Prefect resources related to your incident.</li> </ul> </li> <li> <p>From a flow run, work pool, or block:</p> <ul> <li>Initiate an incident directly from a failed flow run, automatically linking it as a resource, by clicking on the menu button and selecting \"Declare an incident\".</li> </ul> </li> <li> <p>Via an automation:</p> <ul> <li>Set up incident creation as an automated response to selected triggers.</li> </ul> </li> </ol>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#incident-automations","title":"Incident automations","text":"<p>Automations can be used for triggering an incident and for selecting actions to take when an incident is triggered. For example, a work pool status change could trigger the declaration of an incident, or a critical level incident could trigger a notification action.</p> <p>To automatically take action when an incident is declared, set up a custom trigger that listens for declaration events.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect-cloud.incident.*\"\n  },\n  \"expect\": [\n    \"prefect-cloud.incident.declared\"\n  ],\n  \"posture\": \"Reactive\",\n  \"threshold\": 1,\n  \"within\": 0\n}\n</code></pre> <p>Building custom triggers</p> <p>To get started with incident automations, you only need to specify two fields in your trigger:</p> <ul> <li> <p>match: The resource emitting your event of interest. You can match on specific resource IDs, use wildcards to match on all resources of a given type, and even match on other resource attributes, like <code>prefect.resource.name</code>.</p> </li> <li> <p>expect: The event type to listen for. For example, you could listen for any (or all) of the following event types:</p> <ul> <li><code>prefect-cloud.incident.declared</code></li> <li><code>prefect-cloud.incident.resolved</code></li> <li><code>prefect-cloud.incident.updated.severity</code></li> </ul> </li> </ul> <p>See Event Triggers for more information on custom triggers, and check out your Event Feed to see the event types emitted by your incidents and other resources (i.e. events that you can react to).</p> <p>When an incident is declared, any actions you configure such as pausing work pools or sending notifications, will execute immediately.</p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#managing-an-incident","title":"Managing an incident","text":"<ul> <li>Monitor active incidents: View real-time status, severity, and impact.</li> <li>Adjust incident details: Update status, severity, and other relevant information.</li> <li>Collaborate: Add comments and insights; these will display with user identifiers and timestamps.</li> <li>Impact assessment: Evaluate how the incident affects ongoing and future workflows.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#resolving-and-documenting-incidents","title":"Resolving and documenting incidents","text":"<ul> <li>Resolution: Update the incident status to reflect resolution steps taken.</li> <li>Documentation: Ensure all actions, comments, and changes are logged for future reference.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#incident-reporting","title":"Incident reporting","text":"<ul> <li>Generate a detailed timeline of the incident: actions taken, updates to severity and resolution - suitable for compliance and retrospective analysis.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/rate-limits/","title":"API Rate Limits &amp; Retention Periods","text":"<p>API rate limits restrict the number of requests that a single client can make in a given time period. They ensure Prefect Cloud's stability, so that when you make an API call, you always get a response.</p> <p>Prefect Cloud rate limits are subject to change</p> <p>The following rate limits are in effect currently, but are subject to change. Contact Prefect support at help@prefect.io if you have questions about current rate limits.</p> <p>Prefect Cloud enforces the following rate limits:</p> <ul> <li>Flow and task creation rate limits</li> <li>Log service rate limits</li> </ul>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#flow-flow-run-and-task-run-rate-limits","title":"Flow, flow run, and task run rate limits","text":"<p>Prefect Cloud limits the <code>flow_runs</code>, <code>task_runs</code>, and <code>flows</code> endpoints and their subroutes at the following levels:</p> <ul> <li>400 per minute for personal accounts</li> <li>2,000 per minute for Pro accounts</li> </ul> <p>The Prefect Cloud API will return a <code>429</code> response with an appropriate <code>Retry-After</code> header if these limits are triggered.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#log-service-rate-limits","title":"Log service rate limits","text":"<p>Prefect Cloud limits the number of logs accepted:</p> <ul> <li>700 logs per minute for personal accounts</li> <li>10,000 logs per minute for Pro accounts</li> </ul> <p>The Prefect Cloud API will return a <code>429</code> response if these limits are triggered.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#flow-run-retention","title":"Flow run retention","text":"<p>Prefect Cloud feature</p> <p>The Flow Run Retention Policy setting is only applicable in Prefect Cloud.</p> <p>Flow runs in Prefect Cloud are retained according to the Flow Run Retention Policy set by your account tier. The policy setting applies to all workspaces owned by the account.</p> <p>The flow run retention policy represents the number of days each flow run is available in the Prefect Cloud UI, and via the Prefect CLI and API after it ends. Once a flow run reaches a terminal state (detailed in the chart here), it will be retained until the end of the flow run retention period.</p> <p>Flow Run Retention Policy keys on terminal state</p> <p>Note that, because Flow Run Retention Policy keys on terminal state, if two flows start at the same time, but reach a terminal state at different times, they will be removed at different times according to when they each reached their respective terminal states.</p> <p>This retention policy applies to all details about a flow run, including its task runs. Subflow runs follow the retention policy independently from their parent flow runs, and are removed based on the time each subflow run reaches a terminal state.</p> <p>If you or your organization have needs that require a tailored retention period, contact the Prefect Sales team.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/workspaces/","title":"Workspaces","text":"<p>A workspace is a discrete environment within Prefect Cloud for your workflows and blocks. Workspaces are available to Prefect Cloud accounts only.</p> <p>Workspaces can be used to organize and compartmentalize your workflows. For example, you can use separate workspaces to isolate dev, staging, and prod environments, or to provide separation between different teams.</p> <p>When you first log into Prefect Cloud, you will be prompted to create your own initial workspace. After creating your workspace, you'll be able to view flow runs, flows, deployments, and other workspace-specific features in the Prefect Cloud UI.</p> <p></p> <p>Select a workspace name in the navigation menu to see all workspaces you can access.</p> <p></p> <p>Your list of available workspaces may include:</p> <ul> <li>Your own account's workspace.</li> <li>Workspaces in an account to which you've been invited and have been given access as an Admin or Member.</li> </ul> <p>Workspace-specific features</p> <p>Each workspace keeps track of its own:</p> <ul> <li>Flow runs and task runs executed in an environment that is syncing with the workspace</li> <li>Flows associated with flow runs or deployments observed by the Prefect Cloud API</li> <li>Deployments</li> <li>Work pools</li> <li>Blocks and Storage</li> <li>Automations</li> </ul> <p>Your user permissions within workspaces may vary. Account admins can assign roles and permissions at the workspace level.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#create-a-workspace","title":"Create a workspace","text":"<p>On the Account Workspaces dropdown or the Workspaces page select the + icon to create a new workspace.</p> <p>You'll be prompted to configure:</p> <ul> <li>The Workspace Owner from the dropdown account menu options.</li> <li>The Workspace Name must be unique within the account.</li> <li>An optional description for the workspace.</li> </ul> <p></p> <p>Select Create to create the new workspace. The number of available workspaces varies by Prefect Cloud plan. See Pricing if you need additional workspaces or users.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-settings","title":"Workspace settings","text":"<p>Within a workspace, select Settings -&gt; General to view or edit workspace details.  </p> <p></p> <p>On this page you can edit workspace details or delete the workspace.</p> <p>Deleting a workspace</p> <p>Deleting a workspace deletes all deployments, flow run history, work pools, and notifications configured in workspace.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-access","title":"Workspace access","text":"<p>Within a Prefect Cloud Pro or Custom tier account, Workspace Owners can invite other people to be members and provision service accounts to a workspace. In addition to giving the user access to the workspace, a Workspace Owner assigns a workspace role to the user. The role specifies the scope of permissions for the user within the workspace.</p> <p>As a Workspace Owner, select Workspaces -&gt; Sharing to manage members and service accounts for the workspace.</p> <p>If you've previously invited individuals to your account or provisioned service accounts, you'll see them listed here.</p> <p></p> <p>To invite someone to an account, select the Members + icon. You can select from a list of existing account members.</p> <p>Select a Role for the user. This will be the initial role for the user within the workspace. A workspace Owner can change this role at any time.</p> <p>Select Send to initiate the invitation.</p> <p>To add a service account to a workspace, select the Service Accounts + icon. You can select from a list of configured service accounts. Select a Workspace Role for the service account. This will be the initial role for the service account within the workspace. A workspace Owner can change this role at any time. Select Share to finalize adding the service account.</p> <p>To remove a workspace member or service account, select Remove from the menu on the right side of the user or service account information on this page.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-transfer","title":"Workspace transfer","text":"<p>Workspace transfer enables you to move an existing workspace from one account to another.</p> <p>Workspace transfer retains existing workspace configuration and flow run history, including blocks, deployments, notifications, work pools, and logs.</p> <p>Workspace transfer permissions</p> <p>Workspace transfer must be initiated or approved by a user with admin privileges for the workspace to be transferred.</p> <p>To initiate a workspace transfer between personal accounts, contact support@prefect.io.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#transfer-a-workspace","title":"Transfer a workspace","text":"<p>To transfer a workspace, select Settings  -&gt; General within the workspace. Then, from the three dot menu in the upper right of the page, select Transfer.</p> <p></p> <p>The Transfer Workspace page shows the workspace to be transferred on the left. Select the target account for the workspace on the right.</p> <p>Workspace transfer impact on accounts</p> <p>Workspace transfer may impact resource usage and costs for source and target accounts.</p> <p>When you transfer a workspace, users, API keys, and service accounts may lose access to the workspace.  Audit log will no longer track activity on the workspace.  Flow runs ending outside of the destination account\u2019s flow run retention period will be removed.  You may also need to update Prefect CLI profiles and execution environment settings to access the workspace's new location.</p> <p>You may also incur new charges in the target account to accommodate the transferred workspace.</p> <p>The Transfer Workspace page outlines the impacts of transferring the selected workspace to the selected target.  Please review these notes carefully before selecting Transfer to transfer the workspace.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/","title":"User accounts","text":"<p>Sign up for a Prefect Cloud account at app.prefect.cloud.</p> <p>An individual user can be invited to become a member of other accounts.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#user-settings","title":"User settings","text":"<p>Users can access their personal settings in the profile menu, including:</p> <ul> <li>Profile: View and editing basic information, such as name.</li> <li>API keys: Create and view API keys for connecting to Prefect Cloud from the CLI or other environments.</li> <li>Preferences: Manage settings, such as color mode and default time zone.</li> <li>Feature previews: Enable or disable feature previews.</li> </ul>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#account-roles","title":"Account roles","text":"<p>Users who are part of an account can hold the role of Admin or Member. Admins can invite other users to join the account and manage the account's workspaces and teams.</p> <p>Admins on Pro and Custom tier Prefect Cloud accounts can grant members of the account roles in a workspace, such as Runner or Viewer. Custom roles are available on Custom tier accounts.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#api-keys","title":"API keys","text":"<p>API keys enable you to authenticate an environment to work with Prefect Cloud.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#service-accounts","title":"Service accounts","text":"<p>Service accounts enable you to create a Prefect Cloud API key that is not associated with a user account.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#single-sign-on-sso","title":"Single sign-on (SSO)","text":"<p>Custom tier plans offer single sign-on (SSO) integration with your team\u2019s identity provider, including options for directory sync and SCIM provisioning.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#audit-log","title":"Audit log","text":"<p>Audit logs provide a chronological record of activities performed by Prefect Cloud users who are members of an account.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#object-level-access-control-lists-acls","title":"Object-level access control lists (ACLs)","text":"<p>Prefect Cloud's Custom plan offers object-level access control lists to restrict access to specific users and service accounts within a workspace.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#teams","title":"Teams","text":"<p>Users of Custom tier Prefect Cloud accounts can be added to Teams to simplify access control governance.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/api-keys/","title":"Manage Prefect Cloud API Keys","text":"<p>API keys enable you to authenticate a local environment to work with Prefect Cloud.</p> <p>If you run <code>prefect cloud login</code> from your CLI, you'll have the choice to authenticate through your browser or by pasting an API key.</p> <p>If you choose to authenticate through your browser, you'll be directed to an authorization page. After you grant approval to connect, you'll be redirected to the CLI and the API key will be saved to your local Prefect profile.</p> <p>If you choose to authenticate by pasting an API key, you'll need to create an API key in the Prefect Cloud UI first.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#create-an-api-key","title":"Create an API key","text":"<p>To create an API key, select the account icon at the bottom-left corner of the UI.</p> <p>Select API Keys. The page displays a list of previously generated keys and lets you create new API keys or delete keys.</p> <p></p> <p>Select the + button to create a new API key. Provide a name for the key and an expiration date.</p> <p></p> <p>Warning</p> <p>Note that an API key cannot be revealed again in the UI after it is generated, so copy the key to a secure location.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#log-into-prefect-cloud-with-an-api-key","title":"Log into Prefect Cloud with an API Key","text":"<pre><code>prefect cloud login -k '&lt;my-api-key&gt;'\n</code></pre>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#service-account-api-keys","title":"Service account API keys","text":"<p>Service accounts are a feature of Prefect Cloud Pro and Custom tier plans that enable you to create a Prefect Cloud API key that is not associated with a user account.</p> <p>Service accounts are typically used to configure API access for running workers or executing flow runs on remote infrastructure. Events and logs for flow runs in those environments are then associated with the service account rather than a user, and API access may be managed or revoked by configuring or removing the service account without disrupting user access.</p> <p>See the service accounts documentation for more information about creating and managing service accounts in Prefect Cloud.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/audit-log/","title":"Audit Log","text":"<p>Prefect Cloud's Pro and Custom plans offer enhanced compliance and transparency tools with Audit Log. Audit logs provide a chronological record of activities performed by members in your account, allowing you to monitor detailed Prefect Cloud actions for security and compliance purposes.</p> <p>Audit logs enable you to identify who took what action, when, and using what resources within your Prefect Cloud account. In conjunction with appropriate tools and procedures, audit logs can assist in detecting potential security violations and investigating application errors.  </p> <p>Audit logs can be used to identify changes in:</p> <ul> <li>Access to workspaces</li> <li>User login activity</li> <li>User API key creation and removal</li> <li>Workspace creation and removal</li> <li>Account member invitations and removal</li> <li>Service account creation, API key rotation, and removal</li> <li>Billing payment method for self-serve pricing tiers</li> </ul> <p>See the Prefect Cloud plan information to learn more about options for supporting audit logs.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/audit-log/#viewing-audit-logs","title":"Viewing audit logs","text":"<p>From your Pro or Custom account settings page, select the Audit Log page to view audit logs.</p> <p></p> <p>Pro and Custom account tier admins can view audit logs for:</p> <ul> <li>Account-level events in Prefect Cloud, such as:</li> <li>Member invites</li> <li>Changing a member\u2019s role</li> <li>Member login and logout of Prefect Cloud</li> <li>Creating or deleting a service account</li> <li>Workspace-level events in Prefect Cloud, such as:</li> <li>Adding a member to a workspace</li> <li>Changing a member\u2019s workspace role</li> <li>Creating or deleting a workspace</li> </ul> <p>Admins can filter audit logs on multiple dimensions to restrict the results they see by workspace, user, or event type. Available audit log events are displayed in the Events drop-down menu.</p> <p>Audit logs may also be filtered by date range. Audit log retention period varies by Prefect Cloud plan.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/object-access-control-lists/","title":"Object Access Control Lists","text":"<p>Prefect Cloud's Custom plan offers object-level access control lists to restrict access to specific users and service accounts within a workspace. ACLs are supported for blocks and deployments.</p> <p>Organization Admins and Workspace Owners can configure access control lists by navigating to an object and clicking manage access. When an ACL is added, all users and service accounts with access to an object via their workspace role will lose access if not explicitly added to the ACL.</p> <p></p> <p>ACLs and visibility</p> <p>Objects not governed by access control lists such as flow runs, flows, and artifacts will be visible to a user within a workspace even if an associated block or deployment has been restricted for that user.</p> <p>See the Prefect Cloud plans to learn more about options for supporting object-level access control.</p>","tags":["UI","Permissions","Access","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/roles/","title":"User and Service Account Roles","text":"<p>Prefect Cloud's Pro and Custom tiers allow you to set team member access to the appropriate level within specific workspaces.</p> <p>Role-based access controls (RBAC) enable you to assign users granular permissions to perform certain activities.</p> <p>To give users access to functionality beyond the scope of Prefect\u2019s built-in workspace roles, Custom account Admins can create custom roles for users.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#built-in-roles","title":"Built-in roles","text":"<p>Roles give users abilities at either the account level or at the individual workspace level.</p> <ul> <li>An account-level role defines a user's default permissions within an account.</li> <li>A workspace-level role defines a user's permissions within a specific workspace.</li> </ul> <p>The following sections outline the abilities of the built-in, Prefect-defined ac and workspace roles.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#account-level-roles","title":"Account-level roles","text":"<p>The following built-in roles have permissions across an account in Prefect Cloud.</p> Role Abilities Owner \u2022 Set/change all account profile settings allowed to be set/changed by a Prefect user.  \u2022 Add and remove account members, and their account roles.  \u2022 Create and delete service accounts in the account.  \u2022 Create workspaces in the account.  \u2022 Implicit workspace owner access on all workspaces in the account.  \u2022 Bypass SSO. Admin \u2022 Set/change all account profile settings allowed to be set/changed by a Prefect user.  \u2022 Add and remove account members, and their account roles.  \u2022 Create and delete service accounts in the account.  \u2022 Create workspaces in the account.  \u2022 Implicit workspace owner access on all workspaces in the account.  \u2022 Cannot bypass SSO. Member \u2022 View account profile settings.  \u2022 View workspaces I have access to in the account.  \u2022 View account members and their roles.  \u2022 View service accounts in the account.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-level-roles","title":"Workspace-level roles","text":"<p>The following built-in roles have permissions within a given workspace in Prefect Cloud.</p> Role Abilities Viewer \u2022 View flow runs within a workspace.  \u2022 View deployments within a workspace.  \u2022 View all work pools within a workspace.  \u2022 View all blocks within a workspace.  \u2022 View all automations within a workspace.  \u2022 View workspace handle and description. Runner All Viewer abilities, plus:  \u2022 Run deployments within a workspace. Developer All Runner abilities, plus:  \u2022 Run flows within a workspace.  \u2022 Delete flow runs within a workspace.  \u2022 Create, edit, and delete deployments within a workspace.  \u2022 Create, edit, and delete work pools within a workspace.  \u2022 Create, edit, and delete all blocks and their secrets within a workspace.  \u2022 Create, edit, and delete automations within a workspace.  \u2022 View all workspace settings. Owner All Developer abilities, plus:  \u2022 Add and remove account members, and set their role within a workspace.  \u2022 Set the workspace\u2019s default workspace role for all users in the account.  \u2022 Set, view, edit workspace settings. Worker The minimum scopes required for a worker to poll for and submit work.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#custom-workspace-roles","title":"Custom workspace roles","text":"<p>The built-in roles will serve the needs of most users, but your team may need to configure custom roles, giving users access to specific permissions within a workspace.</p> <p>Custom roles can inherit permissions from a built-in role. This enables tweaks to the role to meet your team\u2019s needs, while ensuring users can still benefit from Prefect\u2019s default workspace role permission curation as new functionality becomes available.</p> <p>Custom workspace roles can also be created independent of Prefect\u2019s built-in roles. This option gives workspace admins full control of user access to workspace functionality. However, for non-inherited custom roles, the workspace admin takes on the responsibility for monitoring and setting permissions for new functionality as it is released.</p> <p>See Role permissions for details of permissions you may set for custom roles.</p> <p>After you create a new role, it become available in the account Members page and the Workspace Sharing page for you to apply to users.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#inherited-roles","title":"Inherited roles","text":"<p>A custom role may be configured as an Inherited Role. Using an inherited role allows you to create a custom role using a set of initial permissions associated with a built-in Prefect role. Additional permissions can be added to the custom role. Permissions included in the inherited role cannot be removed.</p> <p>Custom roles created using an inherited role will follow Prefect's default workspace role permission curation as new functionality becomes available.</p> <p>To configure an inherited role when configuring a custom role, select the Inherit permission from a default role check box, then select the role from which the new role should inherit permissions.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-role-permissions","title":"Workspace role permissions","text":"<p>The following permissions are available for custom roles.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#automations","title":"Automations","text":"Permission Description View automations User can see configured automations within a workspace. Create, edit, and delete automations User can create, edit, and delete automations within a workspace. Includes permissions of View automations.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#blocks","title":"Blocks","text":"Permission Description View blocks User can see configured blocks within a workspace. View secret block data User can see configured blocks and their secrets within a workspace. Includes permissions of\u00a0View blocks. Create, edit, and delete blocks User can create, edit, and delete blocks within a workspace. Includes permissions of View blocks and View secret block data.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#deployments","title":"Deployments","text":"Permission Description View deployments User can see configured deployments within a workspace. Run deployments User can run deployments within a workspace. This does not give a user permission to execute the flow associated with the deployment. This only gives a user (via their key) the ability to run a deployment \u2014 another user/key must actually execute that flow, such as a service account with an appropriate role. Includes permissions of View deployments. Create and edit deployments User can create and edit deployments within a workspace. Includes permissions of View deployments and Run deployments. Delete deployments User can delete deployments within a workspace. Includes permissions of View deployments, Run deployments, and Create and edit deployments.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#flows","title":"Flows","text":"Permission Description View flows and flow runs User can see flows and flow runs within a workspace. Create, update, and delete saved search filters User can create, update, and delete saved flow run search filters configured within a workspace. Includes permissions of View flows and flow runs. Create, update, and run flows User can create, update, and run flows within a workspace. Includes permissions of View flows and flow runs. Delete flows User can delete flows within a workspace. Includes permissions of View flows and flow runs and Create, update, and run flows.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#notifications","title":"Notifications","text":"Permission Description View notification policies User can see notification policies configured within a workspace. Create and edit notification policies User can create and edit notification policies configured within a workspace. Includes permissions of View notification policies. Delete notification policies User can delete notification policies configured within a workspace. Includes permissions of View notification policies and Create and edit notification policies.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#task-run-concurrency","title":"Task run concurrency","text":"Permission Description View concurrency limits User can see configured task run concurrency limits within a workspace. Create, edit, and delete concurrency limits User can create, edit, and delete task run concurrency limits within a workspace. Includes permissions of View concurrency limits.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#work-pools","title":"Work pools","text":"Permission Description View work pools User can see work pools configured within a workspace. Create, edit, and pause work pools User can create, edit, and pause work pools configured within a workspace. Includes permissions of View work pools. Delete work pools User can delete work pools configured within a workspace. Includes permissions of View work pools and Create, edit, and pause work pools.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-management","title":"Workspace management","text":"Permission Description View information about workspace service accounts User can see service accounts configured within a workspace. View information about workspace users User can see user accounts for users invited to the workspace. View workspace settings User can see settings configured within a workspace. Edit workspace settings User can edit settings for a workspace. Includes permissions of View workspace settings. Delete the workspace User can delete a workspace. Includes permissions of View workspace settings and Edit workspace settings.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/service-accounts/","title":"Service Accounts","text":"<p>Service accounts enable you to create a Prefect Cloud API key that is not associated with a user account. Service accounts are typically used to configure API access for running workers or executing deployment flow runs on remote infrastructure.</p> <p>Service accounts are non-user accounts that have the following features:</p> <ul> <li>Prefect Cloud API keys</li> <li>Roles and permissions</li> </ul> <p>Using service account credentials, you can configure an execution environment to interact with your Prefect Cloud workspaces without a user having to manually log in from that environment. Service accounts may be created, added to workspaces, have their roles changed, or deleted without affecting other user accounts.</p> <p>Select Service Accounts to view, create, or edit service accounts.</p> <p></p> <p>Service accounts are created at the account level, but individual workspaces may be shared with the service account. See workspace sharing for more information.</p> <p>Service account credentials</p> <p>When you create a service account, Prefect Cloud creates a new API key for the account and provides the API configuration command for the execution environment. Save these to a safe location for future use. If the access credentials are lost or compromised, you should regenerate the credentials from the service account page.</p> <p>Service account roles</p> <p>Service accounts are created at the account level, and can then be added to workspaces within the account. You may apply any valid workspace-level role to a service account.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/service-accounts/#create-a-service-account","title":"Create a service account","text":"<p>Within your account, on the Service Accounts page, select the + icon to create a new service account. You'll be prompted to configure:</p> <ul> <li>The service account name. This name must be unique within your account.</li> <li>An expiration date, or the Never Expire option.</li> </ul> <p>Service account roles</p> <p>A service account may only be a Member of an account. You may apply any valid workspace-level role to a service account when it is added to a workspace.</p> <p>Select Create to create the new service account.</p> <p>Warning</p> <p>Note that an API key cannot be revealed again in the UI after it is generated, so copy the key to a secure location.</p> <p>You can change the API key and expiration for a service account by rotating the API key. Select Rotate API Key from the menu on the left side of the service account's information on this page. Optionally, you can set a period of time for your old service account key to remain active.</p> <p>To delete a service account, select Remove from the menu on the left side of the service account's information.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/sso/","title":"Single Sign-on (SSO)","text":"<p>Prefect Cloud's Custom plans offer single sign-on (SSO) integration with your team\u2019s identity provider. SSO integration can be set up with any identity provider that supports:</p> <ul> <li>OIDC</li> <li>SAML 2.0</li> </ul> <p>When using SSO, Prefect Cloud won't store passwords for any accounts managed by your identity provider. Members of your Prefect Cloud account will instead log in and authenticate using your identity provider.</p> <p>Once your SSO integration has been set up, non-admins will be required to authenticate through the SSO provider when accessing account resources.</p> <p>See the Prefect Cloud plans to learn more about options for supporting more users and workspaces, service accounts, and SSO.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#configuring-sso","title":"Configuring SSO","text":"<p>Within your account, select the SSO page to enable SSO for users.</p> <p>If you haven't enabled SSO for a domain yet, enter the email domains for which you want to configure SSO in Prefect Cloud and save it.</p> <p>Under Enabled Domains, select the domains from the Domains list, then select Generate Link. This step creates a link you can use to configure SSO with your identity provider.</p> <p></p> <p>Using the provided link navigate to the Identity Provider Configuration dashboard and select your identity provider to continue configuration. If your provider isn't listed, you can continue with the <code>SAML</code> or <code>Open ID Connect</code> choices instead.</p> <p></p> <p>Once you complete SSO configuration your users will be required to authenticate via your identity provider when accessing account resources, giving you full control over application access.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#directory-sync","title":"Directory sync","text":"<p>Directory sync automatically provisions and de-provisions users for your account.</p> <p>Provisioned users are given basic \u201cMember\u201d roles and will have access to any resources that role entails.</p> <p>When a user is unassigned from the Prefect Cloud application in your identity provider, they will automatically lose access to Prefect Cloud resources, allowing your IT team to control access to Prefect Cloud without ever signing into the Prefect UI.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#scim-provisioning","title":"SCIM Provisioning","text":"<p>Custom accounts have access to SCIM for user provisioning. The SSO tab provides access to enable SCIM provisioning.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/teams/","title":"Teams","text":"<p>Prefect Cloud's Custom plan offers team management to simplify access control governance.</p> <p>Account Admins can configure teams and team membership from the account settings menu by clicking Teams. Teams are composed of users and service accounts. Teams can be added to workspaces or object access control lists just like users and service accounts.</p> <p></p> <p>If SCIM is enabled on your account, the set of teams and the users within them is governed by your IDP. Prefect Cloud service accounts, which are not governed by your IDP, can be still be added to your existing set of teams.</p> <p>See the Prefect Cloud plans to learn more about options for supporting teams.</p>","tags":["UI","Permissions","Access","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"community/","title":"Community","text":"<p>There are many ways to get involved with the Prefect community</p> <ul> <li>Join over 26,000 engineers in the Prefect Slack community</li> <li>Get help in Prefect Discourse - the community-driven knowledge base</li> <li>Give Prefect a \u2b50\ufe0f on GitHub</li> <li>Contribute to Prefect's open source libraries</li> <li>Become a Prefect Ambassador by joining Club 42</li> </ul>","tags":["community","Slack","Discourse"],"boost":2},{"location":"concepts/","title":"Explore Prefect concepts","text":"Concept Description Flows A Prefect workflow, defined as a Python function. Tasks Discrete units of work in a Prefect workflow. Deployments A server-side concept that encapsulates flow metadata, allowing it to be scheduled and triggered via API. Work Pools &amp; Workers Use Prefect to dynamically provision and configure infrastructure in your execution environment. Schedules Tell the Prefect API how to create new flow runs for you automatically on a specified cadence. Results The data returned by a flow or a task. Artifacts Formatted outputs rendered in the Prefect UI, such as markdown, tables, or links. States Rich objects that capture the status of a particular task run or flow run. Blocks Prefect primitives that enable the storage of configuration and provide a UI interface. Task Runners Configure how tasks are run - concurrently, in parallel, or in a distributed environment. Automations Configure actions that Prefect executes automatically based on trigger conditions. Block and Agent-Based Deployments Description Block-based Deployments Create deployments that rely on blocks. Infrastructure Blocks that specify infrastructure for flow runs created by a deployment. Storage Lets you configure how flow code for deployments is persisted and retrieved. Agents Like untyped workers. <p>Many features specific to Prefect Cloud are in their own navigation subheading.</p>","tags":["concepts","features","overview"],"boost":2},{"location":"concepts/agents/","title":"Agents","text":"<p>Workers are recommended</p> <p>Agents are part of the block-based deployment model. Work Pools and Workers simplify the specification of a flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-overview","title":"Agent overview","text":"<p>Agent processes are lightweight polling services that get scheduled work from a work pool and deploy the corresponding flow runs.</p> <p>Agents poll for work every 15 seconds by default. This interval is configurable in your profile settings with the <code>PREFECT_AGENT_QUERY_INTERVAL</code> setting.</p> <p>It is possible for multiple agent processes to be started for a single work pool. Each agent process sends a unique ID to the server to help disambiguate themselves and let users know how many agents are active.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-options","title":"Agent options","text":"<p>Agents are configured to pull work from one or more work pool queues. If the agent references a work queue that doesn't exist, it will be created automatically.</p> <p>Configuration parameters you can specify when starting an agent include:</p> Option Description <code>--api</code> The API URL for the Prefect server. Default is the value of <code>PREFECT_API_URL</code>. <code>--hide-welcome</code> Do not display the startup ASCII art for the agent process. <code>--limit</code> Maximum number of flow runs to start simultaneously. [default: None] <code>--match</code>, <code>-m</code> Dynamically matches work queue names with the specified prefix for the agent to pull from,for example <code>dev-</code> will match all work queues with a name that starts with <code>dev-</code>. [default: None] <code>--pool</code>, <code>-p</code> A work pool name for the agent to pull from. [default: None] <code>--prefetch-seconds</code> The amount of time before a flow run's scheduled start time to begin submission. Default is the value of <code>PREFECT_AGENT_PREFETCH_SECONDS</code>. <code>--run-once</code> Only run agent polling once. By default, the agent runs forever. [default: no-run-once] <code>--work-queue</code>, <code>-q</code> One or more work queue names for the agent to pull from. [default: None] <p>You must start an agent within an environment that can access or create the infrastructure needed to execute flow runs. Your agent will deploy flow runs to the infrastructure specified by the deployment.</p> <p>Prefect must be installed in execution environments</p> <p>Prefect must be installed in any environment in which you intend to run the agent or execute a flow run.</p> <p><code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> settings for agents</p> <p><code>PREFECT_API_URL</code> must be set for the environment in which your agent is running or specified when starting the agent with the <code>--api</code> flag. You must also have a user or service account with the <code>Worker</code> role, which can be configured by setting the <code>PREFECT_API_KEY</code>.</p> <p>If you want an agent to communicate with Prefect Cloud or a Prefect server from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#starting-an-agent","title":"Starting an agent","text":"<p>Use the <code>prefect agent start</code> CLI command to start an agent. You must pass at least one work pool name or match string that the agent will poll for work. If the work pool does not exist, it will be created.</p> <pre><code>prefect agent start -p [work pool name]\n</code></pre> <p>For example:</p> <pre><code>Starting agent with ephemeral API...\n\u00a0 ___ ___ ___ ___ ___ ___ _____ \u00a0 \u00a0 _ \u00a0 ___ ___ _\u00a0 _ _____\n\u00a0| _ \\ _ \\ __| __| __/ __|_ \u00a0 _| \u00a0 /_\\ / __| __| \\| |_ \u00a0 _|\n\u00a0|\u00a0 _/ \u00a0 / _|| _|| _| (__\u00a0 | |\u00a0 \u00a0 / _ \\ (_ | _|| .` | | |\n\u00a0|_| |_|_\\___|_| |___\\___| |_| \u00a0 /_/ \\_\\___|___|_|\\_| |_|\n\nAgent started! Looking for work from work pool 'my-pool'...\n</code></pre> <p>By default, the agent polls the API specified by the <code>PREFECT_API_URL</code> environment variable. To configure the agent to poll from a different server location, use the <code>--api</code> flag, specifying the URL of the server.</p> <p>In addition, agents can match multiple queues in a work pool by providing a <code>--match</code> string instead of specifying all of the queues. The agent will poll every queue with a name that starts with the given string. New queues matching this prefix will be found by the agent without needing to restart it.</p> <p>For example:</p> <pre><code>prefect agent start --match \"foo-\"\n</code></pre> <p>This example will poll every work queue that starts with \"foo-\".</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#configuring-prefetch","title":"Configuring prefetch","text":"<p>By default, the agent begins submission of flow runs a short time (10 seconds) before they are scheduled to run. This allows time for the infrastructure to be created, so the flow run can start on time. In some cases, infrastructure will take longer than this to actually start the flow run. In these cases, the prefetch can be increased using the <code>--prefetch-seconds</code> option or the <code>PREFECT_AGENT_PREFETCH_SECONDS</code> setting.</p> <p>Submission can begin an arbitrary amount of time before the flow run is scheduled to start. If this value is larger than the amount of time it takes for the infrastructure to start, the flow run will wait until its scheduled start time. This allows flow runs to start exactly on time.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#troubleshooting","title":"Troubleshooting","text":"","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-crash-or-keyboard-interrupt","title":"Agent crash or keyboard interrupt","text":"<p>If the agent process is ended abruptly, you can sometimes have left over flows that were destined for the agent whose process was ended. In the UI, these will show up as pending. You will need to delete these flows in order for the restarted agent to begin processing the work queue again. Take note of the flows you deleted, you might need to set them to run manually.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/artifacts/","title":"Artifacts","text":"<p>Artifacts are persisted outputs such as tables, Markdown, or links. They are stored on Prefect Cloud or a Prefect server instance and rendered in the Prefect UI. Artifacts make it easy to track and monitor the objects that your flows produce and update over time.</p> <p></p> <p>Published artifacts may be associated with a particular task run or flow run. Artifacts can also be created outside of any flow run context.</p> <p>Whether you're publishing links, Markdown, or tables, artifacts provide a powerful and flexible way to showcase data within your workflows.</p> <p>With artifacts, you can easily manage and share information with your team, providing valuable insights and context.</p> <p>Common use cases for artifacts include:</p> <ul> <li>Debugging: By publishing data that you care about in the UI, you can easily see when and where your results were written. If an artifact doesn't look the way you expect, you can find out which flow run last updated it, and you can click through a link in the artifact to a storage location (such as an S3 bucket).</li> <li>Data quality checks: Artifacts can be used to publish data quality checks from in-progress tasks. This can help ensure that data quality is maintained throughout the pipeline. During long-running tasks such as ML model training, you might use artifacts to publish performance graphs. This can help you visualize how well your models are performing and make adjustments as needed. You can also track the versions of these artifacts over time, making it easier to identify changes in your data.</li> <li>Documentation: Artifacts can be used to publish documentation and sample data to help you keep track of your work and share information with your colleagues. For instance, artifacts allow you to add a description to let your colleagues know why this piece of data is important.</li> </ul>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-artifacts","title":"Creating artifacts","text":"<p>Creating artifacts allows you to publish data from task and flow runs or outside of a flow run context. Currently, you can render three artifact types: links, Markdown, and tables.</p> <p>Artifacts render individually</p> <p>Please note that every artifact created within a task will be displayed as an individual artifact in the Prefect UI. This means that each call to <code>create_link_artifact()</code> or <code>create_markdown_artifact()</code> generates a distinct artifact.</p> <p>Unlike the <code>print()</code> command, where you can concatenate multiple calls to include additional items in a report, within a task, these commands must be used multiple times if necessary. </p> <p>To create artifacts like reports or summaries using <code>create_markdown_artifact()</code>, compile your message string separately and then pass it to <code>create_markdown_artifact()</code> to create the complete artifact.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-link-artifacts","title":"Creating link artifacts","text":"<p>To create a link artifact, use the <code>create_link_artifact()</code> function. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_link_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the Artifacts tab of the associated flow run or task run.</p> <pre><code>from prefect import flow, task\nfrom prefect.artifacts import create_link_artifact\n\n@task\ndef my_first_task():\n        create_link_artifact(\n            key=\"irregular-data\",\n            link=\"https://nyc3.digitaloceanspaces.com/my-bucket-name/highly_variable_data.csv\",\n            description=\"## Highly variable data\",\n        )\n\n@task\ndef my_second_task():\n        create_link_artifact(\n            key=\"irregular-data\",\n            link=\"https://nyc3.digitaloceanspaces.com/my-bucket-name/low_pred_data.csv\",\n            description=\"# Low prediction accuracy\",\n        )\n\n@flow\ndef my_flow():\n    my_first_task()\n    my_second_task()\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Tip</p> <p>You can specify multiple artifacts with the same key to more easily track something very specific that you care about, such as irregularities in your data pipeline.</p> <p>After running the above flows, you can find your new artifacts in the Artifacts page of the UI. Click into the \"irregular-data\" artifact and see all versions of it, along with custom descriptions and links to the relevant data.</p> <p></p> <p>Here, you'll also be able to view information about your artifact such as its associated flow run or task run id, previous and future versions of the artifact (multiple artifacts can have the same key in order to show lineage), the data you've stored (in this case a Markdown-rendered link), an optional Markdown description, and when the artifact was created or updated.</p> <p>To make the links more readable for you and your collaborators, you can pass in a <code>link_text</code> argument for your link artifacts:</p> <pre><code>from prefect import flow\nfrom prefect.artifacts import create_link_artifact\n\n@flow\ndef my_flow():\n    create_link_artifact(\n        key=\"my-important-link\",\n        link=\"https://www.prefect.io/\",\n        link_text=\"Prefect\",\n    )\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>In the above example, the <code>create_link_artifact</code> method is used within a flow to create a link artifact with a key of <code>my-important-link</code>. The <code>link</code> parameter is used to specify the external resource to be linked to, and <code>link_text</code> is used to specify the text to be displayed for the link. An optional <code>description</code> could also be added for context.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-markdown-artifacts","title":"Creating Markdown artifacts","text":"<p>To create a Markdown artifact, you can use the <code>create_markdown_artifact()</code> function. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_markdown_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the Artifacts tab of the associated flow run or task run.</p> <p>Don't indent Markdown</p> <p>Markdown in mult-line strings must be unindented to be interpreted correctly.</p> <pre><code>from prefect import flow, task\nfrom prefect.artifacts import create_markdown_artifact\n\n@task\ndef markdown_task():\n    na_revenue = 500000\n    markdown_report = f\"\"\"# Sales Report\n\n## Summary\n\nIn the past quarter, our company saw a significant increase in sales, with a total revenue of $1,000,000. \nThis represents a 20% increase over the same period last year.\n\n## Sales by Region\n\n| Region        | Revenue |\n|:--------------|-------:|\n| North America | ${na_revenue:,} |\n| Europe        | $250,000 |\n| Asia          | $150,000 |\n| South America | $75,000 |\n| Africa        | $25,000 |\n\n## Top Products\n\n1. Product A - $300,000 in revenue\n2. Product B - $200,000 in revenue\n3. Product C - $150,000 in revenue\n\n## Conclusion\n\nOverall, these results are very encouraging and demonstrate the success of our sales team in increasing revenue \nacross all regions. However, we still have room for improvement and should focus on further increasing sales in \nthe coming quarter.\n\"\"\"\n    create_markdown_artifact(\n        key=\"gtm-report\",\n        markdown=markdown_report,\n        description=\"Quarterly Sales Report\",\n    )\n\n@flow()\ndef my_flow():\n    markdown_task()\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>After running the above flow, you should see your \"gtm-report\" artifact in the Artifacts page of the UI.</p> <p></p> <p>As with all artifacts, you'll be able to view the associated flow run or task run id, previous and future versions of the artifact, your rendered Markdown data, and your optional Markdown description.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#create-table-artifacts","title":"Create table artifacts","text":"<p>You can create a table artifact by calling <code>create_table_artifact()</code>. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_table_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the artifacts tab of the associated flow run or task run.</p> <p>Note</p> <p>The <code>create_table_artifact()</code> function accepts a <code>table</code> argument, which can be provided as either a list of lists, a list of dictionaries, or a dictionary of lists.</p> <pre><code>from prefect.artifacts import create_table_artifact\n\ndef my_fn():\n    highest_churn_possibility = [\n       {'customer_id':'12345', 'name': 'John Smith', 'churn_probability': 0.85 }, \n       {'customer_id':'56789', 'name': 'Jane Jones', 'churn_probability': 0.65 } \n    ]\n\n    create_table_artifact(\n        key=\"personalized-reachout\",\n        table=highest_churn_possibility,\n        description= \"# Marvin, please reach out to these customers today!\"\n    )\n\nif __name__ == \"__main__\":\n    my_fn()\n</code></pre> <p> As you can see, you don't need to create an artifact in a flow run context. You can create one anywhere in a Python script and see it in the Prefect UI.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#managing-artifacts","title":"Managing artifacts","text":"","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#reading-artifacts","title":"Reading artifacts","text":"<p>In the Prefect UI, you can view all of the latest versions of your artifacts and click into a specific artifact to see its lineage over time. Additionally, you can inspect all versions of an artifact with a given key from the CLI by running:</p> <pre><code>prefect artifact inspect &lt;my_key&gt;\n</code></pre> <p>or view all artifacts by running:</p> <pre><code>prefect artifact ls\n</code></pre> <p>You can also use the Prefect REST API to programmatically filter your results.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#fetching-artifacts","title":"Fetching artifacts","text":"<p>In Python code, you can retrieve an existing artifact with the <code>Artifact.get</code> class method:</p> <pre><code>from prefect.artifacts import Artifact\n\nmy_retrieved_artifact = Artifact.get(\"my_artifact_key\")\n</code></pre>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#deleting-artifacts","title":"Deleting artifacts","text":"<p>You can delete an artifact directly using the CLI to delete specific artifacts with a given key or id:</p> <pre><code>prefect artifact delete &lt;my_key&gt;\n</code></pre> <pre><code>prefect artifact delete --id &lt;my_id&gt;\n</code></pre> <p>Alternatively, you can delete artifacts using the Prefect REST API.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#artifacts-api","title":"Artifacts API","text":"<p>Prefect provides the Prefect REST API to allow you to create, read, and delete artifacts programmatically. With the Artifacts API, you can automate the creation and management of artifacts as part of your workflow.</p> <p>For example, to read the five most recently created Markdown, table, and link artifacts, you can run the following:</p> <pre><code>import requests\n\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/abc/workspaces/xyz\"\nPREFECT_API_KEY=\"pnu_ghijk\"\ndata = {\n    \"sort\": \"CREATED_DESC\",\n    \"limit\": 5,\n    \"artifacts\": {\n        \"key\": {\n            \"exists_\": True\n        }\n    }\n}\n\nheaders = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\nendpoint = f\"{PREFECT_API_URL}/artifacts/filter\"\n\nresponse = requests.post(endpoint, headers=headers, json=data)\nassert response.status_code == 200\nfor artifact in response.json():\n    print(artifact)\n</code></pre> <p>If you don't specify a key or that a key must exist, you will also return results (which are a type of key-less artifact).</p> <p>See the rest of the Prefect REST API documentation on artifacts for more information!</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/automations/","title":"Automations","text":"<p>Automations in Prefect Cloud enable you to configure actions that Prefect executes automatically based on trigger conditions.</p> <p>Potential triggers include the occurrence of events from changes in a flow run's state - or the absence of such events. You can even define your own custom trigger to fire based on an event created from a webhook or a custom event defined in Python code.</p> <p>Potential actions include kicking off flow runs, pausing schedules, and sending custom notifications.</p> <p>Automations are only available in Prefect Cloud</p> <p>Notifications in an open-source Prefect server provide a subset of the notification message-sending features available in Automations.</p> <p>Automations provide a flexible and powerful framework for automatically taking action in response to events.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#automations-overview","title":"Automations overview","text":"<p>The Automations page provides an overview of all configured automations for your workspace.</p> <p></p> <p>Selecting the toggle next to an automation pauses execution of the automation.</p> <p>The button next to the toggle provides commands to copy the automation ID, edit the automation, or delete the automation.</p> <p>Select the name of an automation to view Details about it and relevant Events.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#create-an-automation","title":"Create an automation","text":"<p>On the Automations page, select the + icon to create a new automation. You'll be prompted to configure:</p> <ul> <li>A trigger condition that causes the automation to execute.</li> <li>One or more actions carried out by the automation.</li> <li>Details about the automation, such as a name and description.</li> </ul>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#triggers","title":"Triggers","text":"<p>Triggers specify the conditions under which your action should be performed. The Prefect UI includes templates for many common conditions, such as:</p> <ul> <li>Flow run state change</li> <li>Note - Flow Run Tags currently are only evaluated with <code>OR</code> criteria</li> <li>Work pool status</li> <li>Work queue status</li> <li>Deployment status</li> <li>Metric thresholds, such as average duration, lateness, or completion percentage</li> <li>Incident declarations (available on Pro and Custom plans)</li> <li>Custom event triggers</li> </ul> <p>Automations API</p> <p>The automations API enables further programmatic customization of trigger and action policies based on arbitrary events.</p> <p>Importantly, triggers can be configured not only in reaction to events, but also proactively: to fire in the absence of an expected event.</p> <p></p> <p>For example, in the case of flow run state change triggers, you might expect production flows to finish in no longer than thirty minutes. But transient infrastructure or network issues could cause your flow to get \u201cstuck\u201d in a running state. A trigger could kick off an action if the flow stays in a running state for more than 30 minutes. This action could be taken on the flow itself, such as canceling or restarting it. Or the action could take the form of a notification so someone can take manual remediation steps. Or you could set both actions to to take place when the trigger occurs.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#actions","title":"Actions","text":"<p>Actions specify what your automation does when its trigger criteria are met. Current action types include:</p> <ul> <li>Cancel a flow run</li> <li>Pause or resume a schedule</li> <li>Run a deployment</li> <li>Pause or resume a deployment schedule</li> <li>Pause or resume a work pool</li> <li>Pause or resume a work queue</li> <li>Pause or resume an automation</li> <li>Send a notification</li> <li>Call a webhook</li> <li>Suspend a flow run</li> <li>Declare an incident (available on Pro and Custom plans)</li> <li>Change the state of a flow run</li> </ul> <p></p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#creating-automations-in-python-code","title":"Creating automations In Python code","text":"<p>You can create and access any automation with the Python SDK's <code>Automation</code> class and its methods.</p> <pre><code>from prefect.automations import Automation\nfrom prefect.events.schemas.automations import EventTrigger\nfrom prefect.server.events.actions import CancelFlowRun\n\n# creating an automation\nautomation = Automation(\n    name=\"woodchonk\",\n    trigger=EventTrigger(\n        expect={\"animal.walked\"},\n        match={\n            \"genus\": \"Marmota\",\n            \"species\": \"monax\",\n        },\n        posture=\"Reactive\",\n        threshold=3,\n    ),\n    actions=[CancelFlowRun()]\n).create()\nprint(automation)\n# name='woodchonk' description='' enabled=True trigger=EventTrigger(type='event', match=ResourceSpecification(__root__={'genus': 'Marmota', 'species': 'monax'}), match_related=ResourceSpecification(__root__={}), after=set(), expect={'animal.walked'}, for_each=set(), posture=Posture.Reactive, threshold=3, within=datetime.timedelta(seconds=10)) actions=[CancelFlowRun(type='cancel-flow-run')] actions_on_trigger=[] actions_on_resolve=[] owner_resource=None id=UUID('d641c552-775c-4dc6-a31e-541cb11137a6')\n\n# reading the automation\n\nautomation = Automation.read(id =\"d641c552-775c-4dc6-a31e-541cb11137a6\")\n# or\nautomation = Automation.read(\"woodchonk\")\n\nprint(automation)\n# name='woodchonk' description='' enabled=True trigger=EventTrigger(type='event', match=ResourceSpecification(__root__={'genus': 'Marmota', 'species': 'monax'}), match_related=ResourceSpecification(__root__={}), after=set(), expect={'animal.walked'}, for_each=set(), posture=Posture.Reactive, threshold=3, within=datetime.timedelta(seconds=10)) actions=[CancelFlowRun(type='cancel-flow-run')] actions_on_trigger=[] actions_on_resolve=[] owner_resource=None id=UUID('d641c552-775c-4dc6-a31e-541cb11137a6')\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#selected-and-inferred-action-targets","title":"Selected and inferred action targets","text":"<p>Some actions require you to either select the target of the action, or specify that the target of the action should be inferred.</p> <p>Selected targets are simple, and useful for when you know exactly what object your action should act on \u2014 for example, the case of a cleanup flow you want to run or a specific notification you\u2019d like to send.</p> <p>Inferred targets are deduced from the trigger itself.</p> <p>For example, if a trigger fires on a flow run that is stuck in a running state, and the action is to cancel an inferred flow run, the flow run to cancel is inferred as the stuck run that caused the trigger to fire.</p> <p>Similarly, if a trigger fires on a work queue event and the corresponding action is to pause an inferred work queue, the inferred work queue is the one that emitted the event.</p> <p>Prefect tries to infer the relevant event whenever possible, but sometimes one does not exist.</p> <p>Specify a name and, optionally, a description for the automation.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#custom-triggers","title":"Custom triggers","text":"<p>When you need a trigger that doesn't quite fit the templates in UI trigger builder, you can define a custom trigger in JSON.  With custom triggers, you have access to the full capabilities of Prefect's automation system - allowing you to react to many kinds of events and metrics in your workspace.</p> <p>Each automation has a single trigger that, when fired, will cause all of its associated actions to run.  That single trigger may be a reactive or proactive event trigger, a trigger monitoring the value of a metric, or a composite trigger that combines several underlying triggers.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#event-triggers","title":"Event triggers","text":"<p>Event triggers are the most common types of trigger, and they are intended to react to the presence or absence of an event happening in your workspace.  Event triggers are indicated with <code>{\"type\": \"event\"}</code>.</p> <p></p> <p>The schema that defines an event trigger is as follows:</p> Name Type Supports trailing wildcards Description match object Labels for resources which this Automation will match. match_related object Labels for related resources which this Automation will match. posture string enum N/A The posture of this Automation, either Reactive or Proactive. Reactive automations respond to the presence of the expected events, while Proactive automations respond to the absence of those expected events. after array of strings Event(s), one of which must have first been seen to start this automation. expect array of strings The event(s) this automation is expecting to see. If empty, this automation will evaluate any matched event. for_each array of strings Evaluate the Automation separately for each distinct value of these labels on the resource. By default, labels refer to the primary resource of the triggering event. You may also refer to labels from related resources by specifying <code>related:&lt;role&gt;:&lt;label&gt;</code>. This will use the value of that label for the first related resource in that role. threshold integer N/A The number of events required for this Automation to trigger (for Reactive automations), or the number of events expected (for Proactive automations) within number N/A The time period over which the events must occur. For Reactive triggers, this may be as low as 0 seconds, but must be at least 10 seconds for Proactive triggers","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#resource-matching","title":"Resource matching","text":"<p>Both the <code>event</code> and <code>metric</code> triggers support matching events for specific resources in your workspace, including most Prefect objects (like flows, deployment, blocks, work pools, tags, etc) as well as resources you have defined in any events you emit yourself.  The <code>match</code> and <code>match_related</code> fields control which events a trigger considers for evaluation by filtering on the contents of their <code>resource</code> and <code>related</code> fields, respectively. Each label added to a <code>match</code> filter is <code>AND</code>ed with the other labels, and can accept a single value or a list of multiple values that are <code>OR</code>ed together.</p> <p>Consider the <code>resource</code> and <code>related</code> fields on the following <code>prefect.flow-run.Completed</code> event, truncated for the sake of example. Its primary resource is a flow run, and since that flow run was started via a deployment, it is related to both its flow and its deployment:</p> <pre><code>\"resource\": {\n  \"prefect.resource.id\": \"prefect.flow-run.925eacce-7fe5-4753-8f02-77f1511543db\",\n  \"prefect.resource.name\": \"cute-kittiwake\"\n}\n\"related\": [\n  {\n    \"prefect.resource.id\": \"prefect.flow.cb6126db-d528-402f-b439-96637187a8ca\",\n    \"prefect.resource.role\": \"flow\",\n    \"prefect.resource.name\": \"hello\"\n  },\n  {\n    \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\",\n    \"prefect.resource.role\": \"deployment\",\n    \"prefect.resource.name\": \"example\"\n  }\n]\n</code></pre> <p>There are a number of valid ways to select the above event for evaluation, and the approach depends on the purpose of the automation.</p> <p>The following configuration will filter for any events whose primary resource is a flow run, and that flow run has a name starting with <code>cute-</code> or <code>radical-</code>.</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": \"prefect.flow-run.*\",\n  \"prefect.resource.name\": [\"cute-*\", \"radical-*\"]\n},\n\"match_related\": {},\n...\n</code></pre> <p>This configuration, on the other hand, will filter for any events for which this specific deployment is a related resource.</p> <pre><code>\"match\": {},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n},\n...\n</code></pre> <p>Both of the above approaches will select the example <code>prefect.flow-run.Completed</code> event, but will permit additional, possibly undesired events through the filter as well. <code>match</code> and <code>match_related</code> can be combined for more restrictive filtering:</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": \"prefect.flow-run.*\",\n  \"prefect.resource.name\": [\"cute-*\", \"radical-*\"]\n},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n},\n...\n</code></pre> <p>Now this trigger will filter only for events whose primary resource is a flow run started by a specific deployment, and that flow run has a name starting with <code>cute-</code> or <code>radical-</code>.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#expected-events","title":"Expected events","text":"<p>Once an event has passed through the <code>match</code> filters, it must be decided if this event should be counted toward the trigger's <code>threshold</code>. Whether that is the case is determined by the event names present in <code>expect</code>.</p> <p>This configuration informs the trigger to evaluate only <code>prefect.flow-run.Completed</code> events that have passed the <code>match</code> filters.</p> <pre><code>\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n...\n</code></pre> <p><code>threshold</code> decides the quantity of <code>expect</code>ed events needed to satisfy the trigger. Increasing the <code>threshold</code> above 1 will also require use of <code>within</code> to define a range of time in which multiple events are seen. The following configuration will expect two occurrences of <code>prefect.flow-run.Completed</code> within 60 seconds.</p> <pre><code>\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n\"threshold\": 2,\n\"within\": 60,\n...\n</code></pre> <p><code>after</code> can be used to handle scenarios that require more complex event reactivity.</p> <p>Take, for example, this flow which emits an event indicating the table it operates on is missing or empty:</p> <pre><code>from prefect import flow\nfrom prefect.events import emit_event\nfrom db import Table\n\n\n@flow\ndef transform(table_name: str):\n    table = Table(table_name)\n\n    if not table.exists():\n        emit_event(\n            event=\"table-missing\",\n            resource={\"prefect.resource.id\": \"etl-events.transform\"}\n        )\n    elif table.is_empty():\n        emit_event(\n            event=\"table-empty\",\n            resource={\"prefect.resource.id\": \"etl-events.transform\"}\n        )\n    else:\n        # transform data\n</code></pre> <p>The following configuration uses <code>after</code> to prevent this automation from firing unless either a <code>table-missing</code> or a <code>table-empty</code> event has occurred before a flow run of this deployment completes.</p> <p>Tip</p> <p>Note how <code>match</code> and <code>match_related</code> are used to ensure the trigger only evaluates events that are relevant to its purpose.</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": [\n    \"prefect.flow-run.*\",\n    \"etl-events.transform\"\n  ]\n},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n}\n\"after\": [\n  \"table-missing\",\n  \"table-empty\"\n]\n\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n...\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#evaluation-strategy","title":"Evaluation strategy","text":"<p>All of the previous examples were designed around a reactive <code>posture</code> - that is, count up events toward the <code>threshold</code> until it is met, then execute actions. To respond to the absence of events, use a proactive <code>posture</code>. A proactive trigger will fire when its <code>threshold</code> has not been met by the end of the window of time defined by <code>within</code>. Proactive triggers must have a <code>within</code> value of at least 10 seconds.</p> <p>The following trigger will fire if a <code>prefect.flow-run.Completed</code> event is not seen within 60 seconds after a <code>prefect.flow-run.Running</code> event is seen.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {},\n  \"after\": [\n    \"prefect.flow-run.Running\"\n  ],\n  \"expect\": [\n    \"prefect.flow-run.Completed\"\n  ],\n  \"for_each\": [],\n  \"posture\": \"Proactive\",\n  \"threshold\": 1,\n  \"within\": 60\n}\n</code></pre> <p>However, without <code>for_each</code>, a <code>prefect.flow-run.Completed</code> event from a different flow run than the one that started this trigger with its <code>prefect.flow-run.Running</code> event could satisfy the condition. Adding a <code>for_each</code> of <code>prefect.resource.id</code> will cause this trigger to be evaluated separately for each flow run id associated with these events.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {},\n  \"after\": [\n    \"prefect.flow-run.Running\"\n  ],\n  \"expect\": [\n    \"prefect.flow-run.Completed\"\n  ],\n  \"for_each\": [\n    \"prefect.resource.id\"\n  ],\n  \"posture\": \"Proactive\",\n  \"threshold\": 1,\n  \"within\": 60\n}\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#metric-triggers","title":"Metric triggers","text":"<p>Metric triggers (<code>{\"type\": \"metric\"}</code>) fire when the value of a metric in your workspace crosses a threshold you've defined.  For example, you can trigger an automation when the success rate of flows in your workspace drops below 95% over the course of an hour.</p> <p>Prefect's metrics are all derived by examining your workspace's events, and if applicable, use the <code>occurred</code> times of those events as the basis for their calculations.</p> <p>Prefect defines three metrics today:</p> <ul> <li>Successes (<code>{\"name\": \"successes\"}</code>), defined as the number of flow runs that went <code>Pending</code> and then the latest state we saw was not a failure (<code>Failed</code> or <code>Crashed</code>).  This metric accounts for retries if the ultimate state was successful.</li> <li>Duration (<code>{\"name\": \"duration\"}</code>), defined as the length of time that a flow remains in a <code>Running</code> state before transitioning to a terminal state such as <code>Completed</code>, <code>Failed</code>, or <code>Crashed</code>.  Because this time is derived in terms of flow run state change events, it may be greater than the runtime of your function.</li> <li>Lateness (<code>{\"name\": \"lateness\"}</code>), defined as the length of time that a <code>Scheduled</code> flow remains in a <code>Late</code> state before transitioning to a <code>Running</code> and/or <code>Crashed</code> state.  Only flow runs that the system marks <code>Late</code> are included.</li> </ul> <p>The schema of a metric trigger is as follows:</p> Name Type Supports trailing wildcards Description match object Labels for resources which this Automation will match. match_related object Labels for related resources which this Automation will match. metric <code>MetricTriggerQuery</code> N/A The definition of the metric query to run <p>And the <code>MetricTriggerQuery</code> query is defined as:</p> Name Type Description name string The name of the Prefect metric to evaluate (see above). threshold number The threshold to which the current metric value is compared operator string (<code>\"&lt;\"</code>, <code>\"&lt;=\"</code>, <code>\"&gt;\"</code>, <code>\"&gt;=\"</code>) The comparison operator to use to decide if the threshold value is met range duration in seconds How far back to evaluate the metric firing_for duration in seconds How long the value must exceed the threshold before this trigger fires <p>For example, to fire when flow runs tagged <code>production</code> in your workspace are failing at a rate of 10% or worse for the last hour (in other words, your success rate is below 90%), create this trigger:</p> <pre><code>{\n  \"type\": \"metric\",\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {\n    \"prefect.resource.id\": \"prefect.tag.production\",\n    \"prefect.resource.role\": \"tag\"\n  },\n  \"metric\": {\n    \"name\": \"successes\",\n    \"threshold\": 0.9,\n    \"operator\": \"&lt;\",\n    \"range\": 3600,\n    \"firing_for\": 0\n  }\n}\n</code></pre> <p>To detect when the average lateness of your Kubernetes workloads (running on a work pool named <code>kubernetes</code>) in the last day exceeds 5 minutes late, and that number hasn't gotten better for the last 10 minutes, use a trigger like this:</p> <pre><code>{\n  \"type\": \"metric\",\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {\n    \"prefect.resource.id\": \"prefect.work-pool.kubernetes\",\n    \"prefect.resource.role\": \"work-pool\"\n  },\n  \"metric\": {\n    \"name\": \"lateness\",\n    \"threshold\": 300,\n    \"operator\": \"&gt;\",\n    \"range\": 86400,\n    \"firing_for\": 600\n  }\n}\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#composite-triggers","title":"Composite triggers","text":"<p>To create a trigger from multiple kinds of events and metrics, use a <code>compound</code> or <code>sequence</code> trigger.  These higher-order triggers are composed from a set of underlying <code>event</code> and <code>metric</code> triggers.</p> <p>For example, if you want to run a deployment only after three different flows in your workspace have written their results to a remote filesystem, combine them with a 'compound' trigger:</p> <pre><code>{\n  \"type\": \"compound\",\n  \"require\": \"all\",\n  \"within\": 3600,\n  \"triggers\": [\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-customer-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-revenue-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-expenses-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    }\n  ]\n}\n</code></pre> <p>This trigger will fire once it sees at least one of each of the underlying event triggers fire within the time frame specified. Then the trigger will reset its state and fire the next time these three events all happen.  The order the events occur doesn't matter, just that all of the events occur within one hour.</p> <p>If you want a flow run to complete prior to starting to watch for those three events,  you can combine the entire previous trigger as the second part of a sequence of two triggers:</p> <pre><code>{\n  // the outer trigger is now a \"sequence\" trigger\n  \"type\": \"sequence\",\n  \"within\": 7200,\n  \"triggers\": [\n    // with the first child trigger expecting a Completed event\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.flow-run.Completed\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-export-initiator\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    // and the second child trigger being the compound trigger from the prior example\n    {\n      \"type\": \"compound\",\n      \"require\": \"all\",\n      \"within\": 3600,\n      \"triggers\": [\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-customer-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        },\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-revenue-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        },\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-expenses-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre> <p>In this case, the trigger will only fire if it sees the <code>daily-export-initiator</code> flow complete, and then the three files written by the other flows.</p> <p>The <code>within</code> parameter for compound and sequence triggers constrains how close in time (in seconds) the child triggers must fire to satisfy the composite trigger.  For example, if the <code>daily-export-initiator</code> flow runs, but the other three flows don't write their result files until three hours later, this trigger won't fire.  Placing these time constraints on the triggers can prevent a misfire if you know that the events will generally happen within a specific timeframe, and you don't want a stray older event to be included in the evaluation of the trigger.  If this isn't a concern for you, you may omit the <code>within</code> period, in which case there is no limit to how far apart in time the child triggers occur.</p> <p>Any type of trigger may be composed into higher-order composite triggers, including proactive event triggers and metric triggers.  In the following example, the compound trigger will fire if any of the following events occur: a flow run stuck in <code>Pending</code>, a work pool becoming unready, or the average amount of <code>Late</code> work in your workspace going over 10 minutes:</p> <pre><code>{\n  \"type\": \"compound\",\n  \"require\": \"any\",\n  \"triggers\": [\n    {\n      \"type\": \"event\",\n      \"posture\": \"Proactive\",\n      \"after\": [\"prefect.flow-run.Pending\"],\n      \"expect\": [\"prefect.flow-run.Running\", \"prefect.flow-run.Crashed\"],\n      \"for_each\": [\"prefect.resource.id\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-customer-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.work-pool.not-ready\"],\n      \"match\": {\n        \"prefect.resource.name\": \"kubernetes-workers\",\n      }\n    },\n    {\n      \"type\": \"metric\",\n      \"metric\": {\n        \"name\": \"lateness\",\n        \"operator\": \"&gt;\",\n        \"threshold\": 600,\n        \"range\": 3600,\n        \"firing_for\": 300\n      }\n    }\n  ]\n}\n</code></pre> <p>For compound triggers, the <code>require</code> parameter may be <code>\"any\"</code>, <code>\"all\"</code>, or a number between 1 and the number of child triggers.  In the example above, if you feel that you are receiving too many spurious notifications for issues that resolve on their own, you can specify <code>{\"require\": 2}</code> to express that any two of the triggers must fire in order for the compound trigger to fire.  Sequence triggers, on the other hand, always require all of their child triggers to fire before they fire.</p> <p>Compound triggers are defined as:</p> Name Type Description require number, <code>\"any\"</code>, or <code>\"all\"</code> How many of the child triggers must fire for this trigger to fire within time, in seconds How close in time the child triggers must fire for this trigger to fire triggers array of other triggers <p>Sequence triggers are defined as:</p> Name Type Description within time, in seconds How close in time the child triggers must fire for this trigger to fire triggers array of other triggers","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#create-an-automation-via-deployment-triggers","title":"Create an automation via deployment triggers","text":"<p>To enable the simple configuration of event-driven deployments, Prefect provides deployment triggers - a shorthand for creating automations that are linked to specific deployments to run them based on the presence or absence of events.</p> <p>Trigger definitions for deployments are supported in <code>prefect.yaml</code>, <code>.serve</code>, and <code>.deploy</code>. At deployment time, specified trigger definitions will create linked automations that are triggered by events matching your chosen grammar. Each trigger definition may include a jinja template to render the triggering <code>event</code> as the <code>parameters</code> of your  deployment's flow run.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#defining-triggers-in-prefectyaml","title":"Defining triggers in <code>prefect.yaml</code>","text":"<p>A list of triggers can be included directly on any deployment in a <code>prefect.yaml</code> file:</p> <pre><code>deployments:\n  - name: my-deployment\n    entrypoint: path/to/flow.py:decorated_fn\n    work_pool:\n      name: my-work-pool\n    triggers:\n      - type: event\n        enabled: true\n        match:\n          prefect.resource.id: my.external.resource\n        expect:\n          - external.resource.pinged\n        parameters:\n          param_1: \"{{ event }}\"\n</code></pre> <p>This deployment will create a flow run when an <code>external.resource.pinged</code> event and an <code>external.resource.replied</code> event have been seen from <code>my.external.resource</code>:</p> <pre><code>deployments:\n  - name: my-deployment\n    entrypoint: path/to/flow.py:decorated_fn\n    work_pool:\n      name: my-work-pool\n    triggers:\n      - type: compound\n        require: all\n        parameters:\n          param_1: \"{{ event }}\"\n        triggers:\n          - type: event\n            match:\n              prefect.resource.id: my.external.resource\n            expect:\n              - external.resource.pinged\n          - type: event\n            match:\n              prefect.resource.id: my.external.resource\n            expect:\n              - external.resource.replied\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#defining-triggers-in-serve-and-deploy","title":"Defining triggers in <code>.serve</code> and <code>.deploy</code>","text":"<p>For creating deployments with triggers in Python, the trigger types <code>DeploymentEventTrigger</code>, <code>DeploymentMetricTrigger</code>, <code>DeploymentCompoundTrigger</code>, and <code>DeploymentSequenceTrigger</code> can be imported from <code>prefect.events</code>:</p> <pre><code>from prefect import flow\nfrom prefect.events import DeploymentEventTrigger\n\n\n@flow(log_prints=True)\ndef decorated_fn(param_1: str):\n    print(param_1)\n\n\nif __name__==\"__main__\":\n    decorated_fn.serve(\n        name=\"my-deployment\",\n        triggers=[\n            DeploymentEventTrigger(\n                enabled=True,\n                match={\"prefect.resource.id\": \"my.external.resource\"},\n                expect=[\"external.resource.pinged\"],\n                parameters={\n                    \"param_1\": \"{{ event }}\",\n                },\n            )\n        ],\n    )\n</code></pre> <p>As with prior examples, composite triggers must be supplied with a list of underlying triggers:</p> <pre><code>from prefect import flow\nfrom prefect.events import DeploymentCompoundTrigger\n\n\n@flow(log_prints=True)\ndef decorated_fn(param_1: str):\n    print(param_1)\n\n\nif __name__==\"__main__\":\n    decorated_fn.deploy(\n        name=\"my-deployment\",\n        image=\"my-image-registry/my-image:my-tag\"\n        triggers=[\n            DeploymentCompoundTrigger(\n                enabled=True,\n                name=\"my-compound-trigger\",\n                require=\"all\",\n                triggers=[\n                    {\n                      \"type\": \"event\",\n                      \"match\": {\"prefect.resource.id\": \"my.external.resource\"},\n                      \"expect\": [\"external.resource.pinged\"],\n                    },\n                    {\n                      \"type\": \"event\",\n                      \"match\": {\"prefect.resource.id\": \"my.external.resource\"},\n                      \"expect\": [\"external.resource.replied\"],\n                    },\n                ],\n                parameters={\n                    \"param_1\": \"{{ event }}\",\n                },\n            )\n        ],\n        work_pool_name=\"my-work-pool\",\n    )\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#pass-triggers-to-prefect-deploy","title":"Pass triggers to <code>prefect deploy</code>","text":"<p>You can pass one or more <code>--trigger</code> arguments to <code>prefect deploy</code>, which can be either a JSON string or a path to a <code>.yaml</code> or <code>.json</code> file.</p> <pre><code># Pass a trigger as a JSON string\nprefect deploy -n test-deployment \\\n  --trigger '{\n    \"enabled\": true,\n    \"match\": {\n      \"prefect.resource.id\": \"prefect.flow-run.*\"\n    },\n    \"expect\": [\"prefect.flow-run.Completed\"]\n  }'\n\n# Pass a trigger using a JSON/YAML file\nprefect deploy -n test-deployment --trigger triggers.yaml\nprefect deploy -n test-deployment --trigger my_stuff/triggers.json\n</code></pre> <p>For example, a <code>triggers.yaml</code> file could have many triggers defined:</p> <pre><code>triggers:\n  - enabled: true\n    match:\n      prefect.resource.id: my.external.resource\n    expect:\n      - external.resource.pinged\n    parameters:\n      param_1: \"{{ event }}\"\n  - enabled: true\n    match:\n      prefect.resource.id: my.other.external.resource\n    expect:\n      - some.other.event\n    parameters:\n      param_1: \"{{ event }}\"\n</code></pre> <p>Both of the above triggers would be attached to <code>test-deployment</code> after running <code>prefect deploy</code>.</p> <p>Triggers passed to <code>prefect deploy</code> will override any triggers defined in <code>prefect.yaml</code></p> <p>While you can define triggers in <code>prefect.yaml</code> for a given deployment, triggers passed to <code>prefect deploy</code> will take precedence over those defined in <code>prefect.yaml</code>.</p> <p>Note that deployment triggers contribute to the total number of automations in your workspace.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#automation-notifications","title":"Automation notifications","text":"<p>Notifications enable you to set up automation actions that send a message.</p> <p>Automation notifications support sending notifications via any predefined block that is capable of and configured to send a message. That includes, for example:</p> <ul> <li>Slack message to a channel</li> <li>Microsoft Teams message to a channel</li> <li>Email to a configured email address</li> </ul> <p></p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#templating-with-jinja","title":"Templating with Jinja","text":"<p>Automation actions can access templated variables through Jinja syntax. Templated variables enable you to dynamically include details from an automation trigger, such as a flow or pool name.</p> <p>Jinja templated variable syntax wraps the variable name in double curly brackets, like this: <code>{{ variable }}</code>.</p> <p>You can access properties of the underlying flow run objects including:</p> <ul> <li>flow_run</li> <li>flow</li> <li>deployment</li> <li>work_queue</li> <li>work_pool</li> </ul> <p>In addition to its native properties, each object includes an <code>id</code> along with <code>created</code> and <code>updated</code> timestamps.</p> <p>The <code>flow_run|ui_url</code> token returns the URL for viewing the flow run in Prefect Cloud.</p> <p>Here\u2019s an example for something that would be relevant to a flow run state-based notification:</p> <pre><code>Flow run {{ flow_run.name }} entered state {{ flow_run.state.name }}.\n\n    Timestamp: {{ flow_run.state.timestamp }}\n    Flow ID: {{ flow_run.flow_id }}\n    Flow Run ID: {{ flow_run.id }}\n    State message: {{ flow_run.state.message }}\n</code></pre> <p>The resulting Slack webhook notification would look something like this:</p> <p></p> <p>You could include <code>flow</code> and <code>deployment</code> properties.</p> <pre><code>Flow run {{ flow_run.name }} for flow {{ flow.name }}\nentered state {{ flow_run.state.name }}\nwith message {{ flow_run.state.message }}\n\nFlow tags: {{ flow_run.tags }}\nDeployment name: {{ deployment.name }}\nDeployment version: {{ deployment.version }}\nDeployment parameters: {{ deployment.parameters }}\n</code></pre> <p>An automation that reports on work pool status might include notifications using <code>work_pool</code> properties.</p> <pre><code>Work pool status alert!\n\nName: {{ work_pool.name }}\nLast polled: {{ work_pool.last_polled }}\n</code></pre> <p>In addition to those shortcuts for flows, deployments, and work pools, you have access to the automation and the event that triggered the automation. See the Automations API for additional details.</p> <pre><code>Automation: {{ automation.name }}\nDescription: {{ automation.description }}\n\nEvent: {{ event.id }}\nResource:\n{% for label, value in event.resource %}\n{{ label }}: {{ value }}\n{% endfor %}\nRelated Resources:\n{% for related in event.related %}\n    Role: {{ related.role }}\n    {% for label, value in related %}\n    {{ label }}: {{ value }}\n    {% endfor %}\n{% endfor %}\n</code></pre> <p>Note that this example also illustrates the ability to use Jinja features such as iterator and for loop control structures when templating notifications.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/blocks/","title":"Blocks","text":"<p>Prefect blocks store configuration and provide an interface for interacting with external systems.</p> <p>Blocks expose methods that provide functionality specific to the systems they interface with. For example, blocks can be used to download data from or upload data to an S3 bucket, query data from or write data to a database, or send a message to a Slack channel.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#overview","title":"Overview","text":"<p>Block types are Python classes with a handy UI webform for configuration. Blocks are instantiation of these classes with specific values.</p> <p>Configure blocks through Python code or via a form in the UI. Access blocks for use in Python code.</p> <p>Block values are stored in Prefect Cloud or your self-hosted Prefect server instance. Blocks can be shared with other users in your Prefect Cloud workspace.</p> <p>To see block types available for configuration, use <code>prefect block type ls</code> from the CLI or navigate to the Blocks page in the UI and click +.</p> <p></p> <p>Blocks and parameters</p> <p>Blocks are useful for configuration that needs to be shared across flow runs and between flows.</p> <p>For configuration that will change between flow runs, we recommend using parameters.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#prefect-built-in-blocks","title":"Prefect built-in blocks","text":"<p>Commonly used block types come built-in with Prefect.  These block types can be created via the UI and used without installing any additional packages.</p> Block Slug Description Azure <code>azure</code> Stores data as a file on Azure Data Lake and Azure Blob Storage. Custom Webhook <code>custom-webhook</code> Calls custom webhooks. Discord Webhook <code>discord-webhook</code> Calls Discord webhooks. Date Time <code>date-time</code> Stores a datetime value. Docker Container <code>docker-container</code> Runs a command in a container. Docker Registry <code>docker-registry</code> Connects to a Docker registry.  Requires a Docker Engine to be connectable. GCS <code>gcs</code> Store data as a file on Google Cloud Storage. GitHub <code>github</code> Interacts with files stored on public GitHub repositories. JSON <code>json</code> Stores JSON data. Kubernetes Cluster Config <code>kubernetes-cluster-config</code> Stores configuration for interaction with Kubernetes clusters. Kubernetes Job <code>kubernetes-job</code> Runs a command as a Kubernetes Job. Local File System <code>local-file-system</code> Stores data as a file on a local file system. Mattermost Webhook <code>mattermost-webhook</code> Sends notifications via a provided Mattermost webhook. Microsoft Teams Webhook <code>ms-teams-webhook</code> Sends notifications via a provided Microsoft Teams webhook. Opsgenie Webhook <code>opsgenie-webhook</code> Sends notifications via a provided Opsgenie webhook. Pager Duty Webhook <code>pager-duty-webhook</code> Sends notifications via a provided PagerDuty webhook. Process <code>process</code> Run a command in a new process. Remote File System <code>remote-file-system</code> Stores data as a file on any remote file system that supports <code>fsspec</code>. S3 <code>s3</code> Stores data as a file on AWS S3. Secret <code>secret</code> Stores a secret value. The value will be obfuscated when this block is logged or shown in the UI. Sendgrid Email <code>sendgrid-email</code> Sends notifications via Sendgrid email. Slack Webhook <code>slack-webhook</code> Sends notifications via a provided Slack webhook. SMB <code>smb</code> Stores data as a file on a SMB share. String <code>string</code> Stores a string value. Twilio SMS <code>twilio-sms</code> Sends notifications via Twilio SMS. <p>Warning</p> <p>The <code>S3</code>, <code>Azure</code>, <code>GCS</code>, and <code>GitHub</code> blocks are deprecated in favor of the the corresponding <code>S3Bucket</code>, <code>AzureBlobStorageCredentials</code>, <code>GCSBucket</code>, and <code>GitHubRepository</code> blocks found in the Prefect integration libraries.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#blocks-in-prefect-integration-libraries","title":"Blocks in Prefect integration libraries","text":"<p>Some block types that appear in the UI can be created immediately, and then the corresponding integration library must be installed for use. For example, an AWS Secret block can be created, but not used until the <code>prefect-aws</code> library is installed.</p> <p>Block types can be created by anyone and optionally shared with the community. You'll find block types available for consumption in many of the published Prefect integrations libraries. If a block type is not available in the UI, you can register it via the CLI.</p> Integration Block Slug prefect-aws ECS Task <code>ecs-task</code> prefect-aws MinIO Credentials <code>minio-credentials</code> prefect-aws S3 Bucket <code>s3-bucket</code> prefect-azure Azure Blob Storage Credentials <code>azure-blob-storage-credentials</code> prefect-azure Azure Container Instance Credentials <code>azure-container-instance-credentials</code> prefect-azure Azure Container Instance Job <code>azure-container-instance-job</code> prefect-azure Azure Cosmos DB Credentials <code>azure-cosmos-db-credentials</code> prefect-azure AzureML Credentials <code>azureml-credentials</code> prefect-bitbucket BitBucket Credentials <code>bitbucket-credentials</code> prefect-bitbucket BitBucket Repository <code>bitbucket-repository</code> prefect-databricks Databricks Credentials <code>databricks-credentials</code> prefect-dbt dbt CLI BigQuery Target Configs <code>dbt-cli-bigquery-target-configs</code> prefect-dbt dbt CLI Profile <code>dbt-cli-profile</code> prefect-dbt dbt Cloud Credentials <code>dbt-cloud-credentials</code> prefect-dbt dbt CLI Global Configs <code>dbt-cli-global-configs</code> prefect-dbt dbt CLI Postgres Target Configs <code>dbt-cli-postgres-target-configs</code> prefect-dbt dbt CLI Snowflake Target Configs <code>dbt-cli-snowflake-target-configs</code> prefect-dbt dbt CLI Target Configs <code>dbt-cli-target-configs</code> prefect-docker Docker Host <code>docker-host</code> prefect-docker Docker Registry Credentials <code>docker-registry-credentials</code> prefect-email Email Server Credentials <code>email-server-credentials</code> prefect-gcp BigQuery Warehouse <code>bigquery-warehouse</code> prefect-gcp GCP Cloud Run Job <code>cloud-run-job</code> prefect-gcp GCP Credentials <code>gcp-credentials</code> prefect-gcp GcpSecret <code>gcpsecret</code> prefect-gcp GCS Bucket <code>gcs-bucket</code> prefect-gcp Vertex AI Custom Training Job <code>vertex-ai-custom-training-job</code> prefect-github GitHub Credentials <code>github-credentials</code> prefect-github GitHub Repository <code>github-repository</code> prefect-gitlab GitLab Credentials <code>gitlab-credentials</code> prefect-gitlab GitLab Repository <code>gitlab-repository</code> prefect-kubernetes Kubernetes Credentials <code>kubernetes-credentials</code> prefect-shell Shell Operation <code>shell-operation</code> prefect-slack Slack Credentials <code>slack-credentials</code> prefect-slack Slack Incoming Webhook <code>slack-incoming-webhook</code> prefect-snowflake Snowflake Connector <code>snowflake-connector</code> prefect-snowflake Snowflake Credentials <code>snowflake-credentials</code> prefect-sqlalchemy Database Credentials <code>database-credentials</code> prefect-sqlalchemy SQLAlchemy Connector <code>sqlalchemy-connector</code>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#use-existing-block-types","title":"Use existing block types","text":"<p>Blocks are classes that subclass the <code>Block</code> base class. They can be instantiated and used like normal classes.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#instantiate-blocks","title":"Instantiate blocks","text":"<p>To instantiate a block that stores a JSON value, use the <code>JSON</code> block:</p> <pre><code>from prefect.blocks.system import JSON\n\njson_block = JSON(value={\"the_answer\": 42})\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#save-blocks","title":"Save blocks","text":"<p>To retrieve this saved value use the <code>.save()</code> method:</p> <pre><code>json_block.save(name=\"life-the-universe-everything\")\n</code></pre> <p>To update saved block value stored for a given block, overwrite the existing block by passing <code>overwrite=True</code>:</p> <pre><code>json_block.save(overwrite=True)\n</code></pre> <p>Create a new JSON block by setting the <code>name</code> parameter to a new value:</p> <pre><code>json_block.save(name=\"actually-life-the-universe-everything\")\n</code></pre> <p>Note that blocks can also be created and updated via the Prefect UI.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#load-blocks","title":"Load blocks","text":"<p>The block name can be used to load the block:</p> <pre><code>from prefect import flow\nfrom prefect.blocks.system import JSON\n\n@flow\ndef what_is_the_answer():\n    json_block = JSON.load(\"life-the-universe-everything\")\n    print(json_block.value[\"the_answer\"])\n\nif __name__ == \"__main__\":\n    what_is_the_answer() # 42\n</code></pre> <p>Alternatively, load a block with the unique slug that is a combination of the block type slug and the block name.</p> <p>To load our JSON block from above, run the following:</p> <pre><code>from prefect.blocks.core import Block\n\njson_block = Block.load(\"json/life-the-universe-everything\")\nprint(json_block.value[\"the-answer\"]) #42\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#delete-blocks","title":"Delete blocks","text":"<p>Delete a block with the <code>.delete()</code> method:</p> <pre><code>from prefect.blocks.core import Block\n\nBlock.delete(\"json/life-the-universe-everything\")\n</code></pre> <p>Alternatively, use the CLI to delete specific blocks with a given slug or id:</p> <pre><code>prefect block delete json/life-the-universe-everything\n</code></pre> <pre><code>prefect block delete --id &lt;my-id&gt;\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#creating-new-block-types","title":"Creating new block types","text":"<p>To create a custom block type, define a class that subclasses <code>Block</code>. The <code>Block</code> base class builds on Pydantic's <code>BaseModel</code>, so custom blocks can be declared in the same manner as a Pydantic model.</p> <p>Here's a block that represents a cube and holds information about the length of each edge in inches:</p> <pre><code>from prefect.blocks.core import Block\n\nclass Cube(Block):\n    edge_length_inches: float\n</code></pre> <p>You can include methods on a block to provide functionality. Here's the same cube block with methods to calculate the volume and surface area of the cube:</p> <pre><code>from prefect.blocks.core import Block\n\nclass Cube(Block):\n    edge_length_inches: float\n\n    def get_volume(self):\n        return self.edge_length_inches**3\n\n    def get_surface_area(self):\n        return 6 * self.edge_length_inches**2\n</code></pre> <p>Use the new <code>Cube</code> block type in a flow:</p> <pre><code>from prefect import flow\n\nrubiks_cube = Cube(edge_length_inches=2.25)\nrubiks_cube.save(\"rubiks-cube\")\n\n@flow\ndef calculate_cube_surface_area(cube_name):\n    cube = Cube.load(cube_name)\n    print(cube.get_surface_area())\n\nif __name__ == \"__main__\":\n    calculate_cube_surface_area(\"rubiks-cube\") # 30.375\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#secret-fields","title":"Secret fields","text":"<p>All block values are encrypted before being stored. If you have values that you would not like visible in the UI or in logs, use the <code>SecretStr</code> field type provided by Pydantic to automatically obfuscate those values. This functionality can be useful for fields that are used to store credentials such as passwords and API tokens.</p> <p>Here's an example of an <code>AWSCredentials</code> block that uses <code>SecretStr</code>:</p> <pre><code>from typing import Optional\n\nfrom prefect.blocks.core import Block\nfrom pydantic import SecretStr  # if pydantic version &gt;= 2.0, use: from pydantic.v1 import SecretStr\n\nclass AWSCredentials(Block):\n    aws_access_key_id: Optional[str] = None\n    aws_secret_access_key: Optional[SecretStr] = None\n    aws_session_token: Optional[str] = None\n    profile_name: Optional[str] = None\n    region_name: Optional[str] = None\n</code></pre> <p>Because <code>aws_secret_access_key</code> has the <code>SecretStr</code> type hint assigned to it, the value of that field will not be exposed if the object is logged:</p> <pre><code>aws_credentials_block = AWSCredentials(\n    aws_access_key_id=\"AKIAJKLJKLJKLJKLJKLJK\",\n    aws_secret_access_key=\"secret_access_key\"\n)\n\nprint(aws_credentials_block)\n# aws_access_key_id='AKIAJKLJKLJKLJKLJKLJK' aws_secret_access_key=SecretStr('**********') aws_session_token=None profile_name=None region_name=None\n</code></pre> <p>Prefect's <code>SecretDict</code> field type allows you to add a dictionary field to your block that will have values at all levels automatically obfuscated in the UI or in logs. This functionality is useful for blocks where typing or structure of secret fields is not known until configuration time.</p> <p>Here's an example of a block that uses <code>SecretDict</code>:</p> <pre><code>from typing import Dict\n\nfrom prefect.blocks.core import Block\nfrom prefect.blocks.fields import SecretDict\n\n\nclass SystemConfiguration(Block):\n    system_secrets: SecretDict\n    system_variables: Dict\n\n\nsystem_configuration_block = SystemConfiguration(\n    system_secrets={\n        \"password\": \"p@ssw0rd\",\n        \"api_token\": \"token_123456789\",\n        \"private_key\": \"&lt;private key here&gt;\",\n    },\n    system_variables={\n        \"self_destruct_countdown_seconds\": 60,\n        \"self_destruct_countdown_stop_time\": 7,\n    },\n)\n</code></pre> <p><code>system_secrets</code> will be obfuscated when <code>system_configuration_block</code> is displayed, but <code>system_variables</code> will be shown in plain-text:</p> <pre><code>print(system_configuration_block)\n# SystemConfiguration(\n#   system_secrets=SecretDict('{'password': '**********', 'api_token': '**********', 'private_key': '**********'}'), \n#   system_variables={'self_destruct_countdown_seconds': 60, 'self_destruct_countdown_stop_time': 7}\n# )\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#block-type-metadata","title":"Block type metadata","text":"<p>The way that a block is displayed can be controlled by metadata fields that can be set on a block type's subclass.</p> <p>Available metadata fields include:</p> Property Description _block_type_name Display name of the block in the UI. Defaults to the class name. _block_type_slug Unique slug used to reference the block type in the API. Defaults to a lowercase, dash-delimited version of the block type name. _logo_url URL pointing to an image that should be displayed for the block type in the UI. Default to <code>None</code>. _description Short description of block type. Defaults to docstring, if provided. _code_example Short code snippet shown in UI for how to load/use block type. Default to first example provided in the docstring of the class, if provided.","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#nested-blocks","title":"Nested blocks","text":"<p>Blocks are composable - a block can be used within other blocks. You can create a block type that uses functionality from another block type by declaring it as an attribute.</p> <p>Nestable blocks are loosely coupled, as configuration can be changed for each block independently. This allows configuration to be shared across multiple use cases.</p> <p>To illustrate, here's a an expanded <code>AWSCredentials</code> block that includes the ability to get an authenticated session via the <code>boto3</code> library:</p> <pre><code>from typing import Optional\n\nimport boto3\nfrom prefect.blocks.core import Block\nfrom pydantic import SecretStr\n\nclass AWSCredentials(Block):\n    aws_access_key_id: Optional[str] = None\n    aws_secret_access_key: Optional[SecretStr] = None\n    aws_session_token: Optional[str] = None\n    profile_name: Optional[str] = None\n    region_name: Optional[str] = None\n\n    def get_boto3_session(self):\n        return boto3.Session(\n            aws_access_key_id = self.aws_access_key_id\n            aws_secret_access_key = self.aws_secret_access_key\n            aws_session_token = self.aws_session_token\n            profile_name = self.profile_name\n            region_name = self.region\n        )\n</code></pre> <p>The <code>AWSCredentials</code> block can be used within an S3Bucket block to provide authentication when interacting with an S3 bucket:</p> <pre><code>import io\n\nclass S3Bucket(Block):\n    bucket_name: str\n    credentials: AWSCredentials\n\n    def read(self, key: str) -&gt; bytes:\n        s3_client = self.credentials.get_boto3_session().client(\"s3\")\n\n        stream = io.BytesIO()\n        s3_client.download_fileobj(Bucket=self.bucket_name, key=key, Fileobj=stream)\n\n        stream.seek(0)\n        output = stream.read()\n\n        return output\n\n    def write(self, key: str, data: bytes) -&gt; None:\n        s3_client = self.credentials.get_boto3_session().client(\"s3\")\n        stream = io.BytesIO(data)\n        s3_client.upload_fileobj(stream, Bucket=self.bucket_name, Key=key)\n</code></pre> <p>You can use this <code>S3Bucket</code> block with previously saved <code>AWSCredentials</code> block values in order to interact with the configured S3 bucket:</p> <pre><code>my_s3_bucket = S3Bucket(\n    bucket_name=\"my_s3_bucket\",\n    credentials=AWSCredentials.load(\"my_aws_credentials\")\n)\n\nmy_s3_bucket.save(\"my_s3_bucket\")\n</code></pre> <p>Saving block values like this links the values of the two blocks so that any changes to the values stored for the <code>AWSCredentials</code> block with the name <code>my_aws_credentials</code> will be seen the next time that block values for the <code>S3Bucket</code> block named <code>my_s3_bucket</code> is loaded.</p> <p>Values for nested blocks can also be hard coded by not first saving child blocks:</p> <pre><code>my_s3_bucket = S3Bucket(\n    bucket_name=\"my_s3_bucket\",\n    credentials=AWSCredentials(\n        aws_access_key_id=\"AKIAJKLJKLJKLJKLJKLJK\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n)\n\nmy_s3_bucket.save(\"my_s3_bucket\")\n</code></pre> <p>In the above example, the values for <code>AWSCredentials</code> are saved with <code>my_s3_bucket</code> and will not be usable with any other blocks.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#update-custom-block-types","title":"Update custom <code>Block</code> types","text":"<p>Let's add a <code>bucket_folder</code> field to your custom <code>S3Bucket</code> block that represents the default path to read and write objects from (this field exists on our implementation).</p> <p>Add the new field to the class definition:</p> <pre><code>class S3Bucket(Block):\n    bucket_name: str\n    credentials: AWSCredentials\n    bucket_folder: str = None\n    ...\n</code></pre> <p>Then register the updated block type with either Prefect Cloud or your self-hosted Prefect server instance.</p> <p>If you have any existing blocks of this type that were created before the update and you'd prefer to not re-create them, migrate them to the new version of your block type by adding the missing values:</p> <pre><code># Bypass Pydantic validation to allow your local Block class to load the old block version\nmy_s3_bucket_block = S3Bucket.load(\"my-s3-bucket\", validate=False)\n\n# Set the new field to an appropriate value\nmy_s3_bucket_block.bucket_path = \"my-default-bucket-path\"\n\n# Overwrite the old block values and update the expected fields on the block\nmy_s3_bucket_block.save(\"my-s3-bucket\", overwrite=True)\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#register-blocks","title":"Register blocks","text":"<p>Prefect comes with many blocks pre-registered and ready to use. If you do not have a block available for use, you can register it.</p> <p>Blocks can be registered from a Python module available in the current environment with a CLI command like this:</p> <pre><code>prefect block register --module prefect_aws.credentials\n</code></pre> <p>This command is useful for registering all blocks found within a module in a Prefect Integration library.</p> <p>Alternatively, if a custom block has been created in a <code>.py</code> file, the block can also be registered with the CLI command:</p> <pre><code>prefect block register --file my_block.py\n</code></pre> <p>The registered block will then be available for configuration.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/deployments-block-based/","title":"Block Based Deployments","text":"<p>Workers are recommended</p> <p>This page is about the block-based deployment model. The Work Pools and Workers based deployment model simplifies the specification of a flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p> <p>We encourage you to check out the new deployment experience with guided command line prompts and convenient CI/CD with <code>prefect.yaml</code> files.</p> <p>With remote storage blocks, you can package not only your flow code script but also any supporting files, including your custom modules, SQL scripts and any configuration files needed in your project.</p> <p>To define how your flow execution environment should be configured, you may either reference pre-configured infrastructure blocks or let Prefect create those automatically for you as anonymous blocks (this happens when you specify the infrastructure type using <code>--infra</code> flag during the build process).</p> <p>Work queue affinity improved starting from Prefect 2.0.5</p> <p>Until Prefect 2.0.4, tags were used to associate flow runs with work queues. Starting in Prefect 2.0.5, tag-based work queues are deprecated. Instead, work queue names are used to explicitly direct flow runs from deployments into queues.</p> <p>Note that backward compatibility is maintained and work queues that use tag-based matching can still be created and will continue to work. However, those work queues are now considered legacy and we encourage you to use the new behavior by specifying work queues explicitly on agents and deployments.</p> <p>See Agents &amp; Work Pools for details.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployments-and-flows","title":"Deployments and flows","text":"<p>Each deployment is associated with a single flow, but any given flow can be referenced by multiple deployments.</p> <p>Deployments are uniquely identified by the combination of: <code>flow_name/deployment_name</code>.</p> <pre><code>graph LR\n    F(\"my_flow\"):::yellow -.-&gt; A(\"Deployment 'daily'\"):::tan --&gt; W(\"my_flow/daily\"):::fgreen\n    F -.-&gt; B(\"Deployment 'weekly'\"):::gold  --&gt; X(\"my_flow/weekly\"):::green\n    F -.-&gt; C(\"Deployment 'ad-hoc'\"):::dgold --&gt; Y(\"my_flow/ad-hoc\"):::dgreen\n    F -.-&gt; D(\"Deployment 'trigger-based'\"):::dgold --&gt; Z(\"my_flow/trigger-based\"):::dgreen\n\n    classDef gold fill:goldenrod,stroke:goldenrod,stroke-width:4px,color:white\n    classDef yellow fill:gold,stroke:gold,stroke-width:4px\n    classDef dgold fill:darkgoldenrod,stroke:darkgoldenrod,stroke-width:4px,color:white\n    classDef tan fill:tan,stroke:tan,stroke-width:4px,color:white\n    classDef fgreen fill:forestgreen,stroke:forestgreen,stroke-width:4px,color:white\n    classDef green fill:green,stroke:green,stroke-width:4px,color:white\n    classDef dgreen fill:darkgreen,stroke:darkgreen,stroke-width:4px,color:white</code></pre> <p>This enables you to run a single flow with different parameters, based on multiple schedules and triggers, and in different environments. This also enables you to run different versions of the same flow for testing and production purposes.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-definition","title":"Deployment definition","text":"<p>A deployment definition captures the settings for creating a deployment object on the Prefect API. You can create the deployment definition by:</p> <ul> <li>Run the <code>prefect deployment build</code> CLI command with deployment options to create a <code>deployment.yaml</code> deployment definition file, then run <code>prefect deployment apply</code> to create a deployment on the API using the settings in <code>deployment.yaml</code>.</li> <li>Define a <code>Deployment</code> Python object, specifying the deployment options as properties of the object, then building and applying the object using methods of <code>Deployment</code>.</li> </ul> <p>The minimum required information to create a deployment includes:</p> <ul> <li>The path and filename of the file containing the flow script.</li> <li>The name of the entrypoint flow function \u2014 this is the flow function that starts the flow and calls and additional tasks or subflows.</li> <li>The name of the deployment.</li> </ul> <p>You may provide additional settings for the deployment. Any settings you do not explicitly specify are inferred from defaults.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment-on-the-cli","title":"Create a deployment on the CLI","text":"<p>To create a deployment on the CLI, there are two steps:</p> <ol> <li>Build the deployment definition file <code>deployment.yaml</code>. This step includes uploading your flow to its configured remote storage location, if one is specified.</li> <li>Create the deployment on the API.</li> </ol>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#build-the-deployment","title":"Build the deployment","text":"<p>To build the deployment definition file <code>deployment.yaml</code>, run the <code>prefect deployment build</code> Prefect CLI command from the folder containing your flow script and any dependencies of the script.</p> <pre><code>$ prefect deployment build [OPTIONS] PATH\n</code></pre> <p>Path to the flow is specified in the format <code>path-to-script:flow-function-name</code> \u2014 The path and filename of the flow script file, a colon, then the name of the entrypoint flow function.</p> <p>For example:</p> <pre><code>$ prefect deployment build -n marvin -p default-agent-pool -q test flows/marvin.py:say_hi\n</code></pre> <p>When you run this command, Prefect:</p> <ul> <li>Creates a <code>marvin_flow-deployment.yaml</code> file for your deployment based on your flow code and options.</li> <li>Uploads your flow files to the configured storage location (local by default).</li> <li>Submit your deployment to the work queue <code>test</code>. The work queue <code>test</code> will be created if it doesn't exist.</li> </ul> <p>Uploading files may require storage filesystem libraries</p> <p>Note that the appropriate filesystem library supporting the storage location must be installed prior to building a deployment with a storage block. For example, the AWS S3 Storage block requires the <code>s3fs</code> library.</p> <p>Ignore files or directories from a deployment</p> <p>By default, Prefect uploads all files in the current folder to the configured storage location (local by default) when you build a deployment.</p> <p>If you want to omit certain files or directories from your deployments, add a <code>.prefectignore</code> file to the root directory. <code>.prefectignore</code> enables users to omit certain files or directories from their deployments.</p> <p>Similar to other <code>.ignore</code> files, the syntax supports pattern matching, so an entry of <code>*.pyc</code> will ensure all <code>.pyc</code> files are ignored by the deployment call when uploading to remote storage.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-build-options","title":"Deployment build options","text":"<p>You may specify additional options to further customize your deployment.</p> <p> Options Description PATH Path, filename, and flow name of the flow definition. (Required) <code>--apply</code>, <code>-a</code> When provided, automatically registers the resulting deployment with the API. <code>--cron TEXT</code> A cron string that will be used to set a <code>CronSchedule</code> on the deployment. For example, <code>--cron \"*/1 * * * *\"</code> to create flow runs from that deployment every minute. <code>--help</code> Display help for available commands and options. <code>--infra-block TEXT</code>, <code>-ib</code> The infrastructure block to use, in <code>block-type/block-name</code> format. <code>--infra</code>, <code>-i</code> The infrastructure type to use. (Default is <code>Process</code>) <code>--interval INTEGER</code> An integer specifying an interval (in seconds) that will be used to set an <code>IntervalSchedule</code> on the deployment. For example, <code>--interval 60</code> to create flow runs from that deployment every minute. <code>--name TEXT</code>, <code>-n</code> The name of the deployment. <code>--output TEXT</code>, <code>-o</code> Optional location for the YAML manifest generated as a result of the <code>build</code> step. You can version-control that file, but it's not required since the CLI can generate everything you need to define a deployment. <code>--override TEXT</code> One or more optional infrastructure overrides provided as a dot delimited path. For example, specify an environment variable: <code>env.env_key=env_value</code>. For Kubernetes, specify customizations: <code>customizations='[{\"op\": \"add\",\"path\": \"/spec/template/spec/containers/0/resources/limits\", \"value\": {\"memory\": \"8Gi\",\"cpu\": \"4000m\"}}]'</code> (note the string format). <code>--param</code> An optional parameter override, values are parsed as JSON strings. For example, <code>--param question=ultimate --param answer=42</code>. <code>--params</code> An optional parameter override in a JSON string format. For example, <code>--params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\'</code>. <code>--path</code> An optional path to specify a subdirectory of remote storage to upload to, or to point to a subdirectory of a locally stored flow. <code>--pool TEXT</code>, <code>-p</code> The work pool that will handle this deployment's runs. \u2502 <code>--rrule TEXT</code> An <code>RRule</code> that will be used to set an <code>RRuleSchedule</code> on the deployment. For example, <code>--rrule 'FREQ=HOURLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9,10,11,12,13,14,15,16,17'</code> to create flow runs from that deployment every hour but only during business hours. <code>--skip-upload</code> When provided, skips uploading this deployment's files to remote storage. <code>--storage-block TEXT</code>, <code>-sb</code> The storage block to use, in <code>block-type/block-name</code> or <code>block-type/block-name/path</code> format. Note that the appropriate library supporting the storage filesystem must be installed. <code>--tag TEXT</code>, <code>-t</code> One or more optional tags to apply to the deployment. <code>--version TEXT</code>, <code>-v</code> An optional version for the deployment. This could be a git commit hash if you use this command from a CI/CD pipeline. <code>--work-queue TEXT</code>, <code>-q</code> The work queue that will handle this deployment's runs. It will be created if it doesn't already exist. Defaults to <code>None</code>. Note that if a work queue is not set, work will not be scheduled.","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#block-identifiers","title":"Block identifiers","text":"<p>When specifying a storage block with the <code>-sb</code> or <code>--storage-block</code> flag, you may specify the block by passing its slug. The storage block slug is formatted as <code>block-type/block-name</code>. </p> <p>For example, <code>s3/example-block</code> is the slug for an S3 block named <code>example-block</code>.</p> <p>In addition, when passing the storage block slug, you may pass just the block slug or the block slug and a path.</p> <ul> <li><code>block-type/block-name</code> indicates just the block, including any path included in the block configuration.</li> <li><code>block-type/block-name/path</code> indicates a storage path in addition to any path included in the block configuration.</li> </ul> <p>When specifying an infrastructure block with the <code>-ib</code> or <code>--infra-block</code> flag, you specify the block by passing its slug. The infrastructure block slug is formatted as <code>block-type/block-name</code>. </p> Block name Block class name Block type for a slug Azure <code>Azure</code> <code>azure</code> Docker Container <code>DockerContainer</code> <code>docker-container</code> GitHub <code>GitHub</code> <code>github</code> GCS <code>GCS</code> <code>gcs</code> Kubernetes Job <code>KubernetesJob</code> <code>kubernetes-job</code> Process <code>Process</code> <code>process</code> Remote File System <code>RemoteFileSystem</code> <code>remote-file-system</code> S3 <code>S3</code> <code>s3</code> SMB <code>SMB</code> <code>smb</code> GitLab Repository <code>GitLabRepository</code> <code>gitlab-repository</code> <p>Note that the appropriate library supporting the storage filesystem must be installed prior to building a deployment with a storage block. For example, the AWS S3 Storage block requires the <code>s3fs</code> library. See Storage for more information.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deploymentyaml","title":"deployment.yaml","text":"<p>A deployment's YAML file configures additional settings needed to create a deployment on the server.</p> <p>A single flow may have multiple deployments created for it, with different schedules, tags, and so on. A single flow definition may have multiple deployment YAML files referencing it, each specifying different settings. The only requirement is that each deployment must have a unique name.</p> <p>The default <code>{flow-name}-deployment.yaml</code> filename may be edited as needed with the <code>--output</code> flag to <code>prefect deployment build</code>.</p> <pre><code>###\n### A complete description of a Prefect Deployment for flow 'Cat Facts'\n###\nname: catfact\ndescription: null\nversion: c0fc95308d8137c50d2da51af138aa23\n# The work queue that will handle this deployment's runs\nwork_queue_name: test\nwork_pool_name: null\ntags: []\nparameters: {}\nschedule: null\ninfra_overrides: {}\ninfrastructure:\n  type: process\n  env: {}\n  labels: {}\n  name: null\n  command:\n  - python\n  - -m\n  - prefect.engine\n  stream_output: true\n###\n### DO NOT EDIT BELOW THIS LINE\n###\nflow_name: Cat Facts\nmanifest_path: null\nstorage: null\npath: /Users/terry/test/testflows/catfact\nentrypoint: catfact.py:catfacts_flow\nparameter_openapi_schema:\n  title: Parameters\n  type: object\n  properties:\n    url:\n      title: url\n  required:\n  - url\n  definitions: null\n</code></pre> <p>Editing deployment.yaml</p> <p>Note the big DO NOT EDIT comment in your deployment's YAML: In practice, anything above this block can be freely edited before running <code>prefect deployment apply</code> to create the deployment on the API.</p> <p>We recommend editing most of these fields from the CLI or Prefect UI for convenience.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#parameters-in-deployments","title":"Parameters in deployments","text":"<p>You may provide default parameter values in the <code>deployment.yaml</code> configuration, and these parameter values will be used for flow runs based on the deployment. </p> <p>To configure default parameter values, add them to the <code>parameters: {}</code> line of <code>deployment.yaml</code> as JSON key-value pairs. The parameter list configured in <code>deployment.yaml</code> must match the parameters expected by the entrypoint flow function.</p> <pre><code>parameters: {\"name\": \"Marvin\", \"num\": 42, \"url\": \"https://catfact.ninja/fact\"}\n</code></pre> <p>Passing **kwargs as flow parameters</p> <p>You may pass <code>**kwargs</code> as a deployment parameter as a <code>\"kwargs\":{}</code> JSON object containing the key-value pairs of any passed keyword arguments.</p> <pre><code>parameters: {\"name\": \"Marvin\", \"kwargs\":{\"cattype\":\"tabby\",\"num\": 42}\n</code></pre> <p>You can edit default parameters for deployments in the Prefect UI, and you can override default parameter values when creating ad-hoc flow runs via the Prefect UI.</p> <p>To edit parameters in the Prefect UI, go the the details page for a deployment, then select Edit from the commands menu. If you change parameter values, the new values are used for all future flow runs based on the deployment.</p> <p>To create an ad-hoc flow run with different parameter values, go the the details page for a deployment, select Run, then select Custom. You will be able to provide custom values for any editable deployment fields. Under Parameters, select Custom. Provide the new values, then select Save. Select Run to begin the flow run with custom values.</p> <p>If you want the Prefect API to verify the parameter values passed to a flow run against the schema defined by <code>parameter_openapi_schema</code>, set <code>enforce_parameter_schema</code> to <code>true</code>.</p> <p></p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment","title":"Create a deployment","text":"<p>When you've configured <code>deployment.yaml</code> for a deployment, you can create the deployment on the API by running the <code>prefect deployment apply</code> Prefect CLI command.</p> <pre><code>$ prefect deployment apply catfacts_flow-deployment.yaml\n</code></pre> <p>For example:</p> <pre><code>$ prefect deployment apply ./catfacts_flow-deployment.yaml\nSuccessfully loaded 'catfact'\nDeployment '76a9f1ac-4d8c-4a92-8869-615bec502685' successfully created.\n</code></pre> <p><code>prefect deployment apply</code> accepts an optional <code>--upload</code> flag that, when provided, uploads this deployment's files to remote storage.</p> <p>Once the deployment has been created, you'll see it in the Prefect UI and can inspect it using the CLI.</p> <pre><code>$ prefect deployment ls\n                               Deployments\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                           \u2503 ID                                   \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Cat Facts/catfact              \u2502 76a9f1ac-4d8c-4a92-8869-615bec502685 \u2502\n\u2502 leonardo_dicapriflow/hello_leo \u2502 fb4681d7-aa5a-4617-bf6f-f67e6f964984 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> <p></p> <p>When you run a deployed flow with Prefect, the following happens:</p> <ul> <li>The user runs the deployment, which creates a flow run. (The API creates flow runs automatically for deployments with schedules.)</li> <li>An agent picks up the flow run from a work queue and uses an infrastructure block to create infrastructure for the run.</li> <li>The flow run executes within the infrastructure.</li> </ul> <p>Agents and work pools enable the Prefect orchestration engine and API to run deployments in your local execution environments. To execute deployed flow runs you need to configure at least one agent.</p> <p>Scheduled flow runs</p> <p>Scheduled flow runs will not be created unless the scheduler is running with either Prefect Cloud or a local Prefect server started with <code>prefect server start</code>.</p> <p>Scheduled flow runs will not run unless an appropriate agent and work pool are configured.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment-from-a-python-object","title":"Create a deployment from a Python object","text":"<p>You can also create deployments from Python scripts by using the <code>prefect.deployments.Deployment</code> class.</p> <p>Create a new deployment using configuration defaults for an imported flow:</p> <pre><code>from my_project.flows import my_flow\nfrom prefect.deployments import Deployment\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"example-deployment\", \n    version=1, \n    work_queue_name=\"demo\",\n    work_pool_name=\"default-agent-pool\",\n)\ndeployment.apply()\n</code></pre> <p>Create a new deployment with a pre-defined storage block and an infrastructure override:</p> <pre><code>from my_project.flows import my_flow\nfrom prefect.deployments import Deployment\nfrom prefect.filesystems import S3\n\nstorage = S3.load(\"dev-bucket\") # load a pre-defined block\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"s3-example\",\n    version=2,\n    work_queue_name=\"aws\",\n    work_pool_name=\"default-agent-pool\",\n    storage=storage,\n    infra_overrides={\n        \"env\": {\n            \"ENV_VAR\": \"value\"\n        }\n    },\n)\n\ndeployment.apply()\n</code></pre> <p>If you have settings that you want to share from an existing deployment you can load those settings:</p> <pre><code>deployment = Deployment(\n    name=\"a-name-you-used\", \n    flow_name=\"name-of-flow\"\n)\ndeployment.load() # loads server-side settings\n</code></pre> <p>Once the existing deployment settings are loaded, you may update them as needed by changing deployment properties.</p> <p>View all of the parameters for the <code>Deployment</code> object in the Python API documentation.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-api-representation","title":"Deployment API representation","text":"<p>When you create a deployment, it is constructed from deployment definition data you provide and additional properties set by client-side utilities.</p> <p>Deployment properties include:</p> Property Description <code>id</code> An auto-generated UUID ID value identifying the deployment. <code>created</code> A <code>datetime</code> timestamp indicating when the deployment was created. <code>updated</code> A <code>datetime</code> timestamp indicating when the deployment was last changed. <code>name</code> The name of the deployment. <code>version</code> The version of the deployment <code>description</code> A description of the deployment. <code>flow_id</code> The id of the flow associated with the deployment. <code>schedule</code> An optional schedule for the deployment. <code>is_schedule_active</code> Boolean indicating whether the deployment schedule is active. Default is True. <code>infra_overrides</code> One or more optional infrastructure overrides <code>parameters</code> An optional dictionary of parameters for flow runs scheduled by the deployment. <code>tags</code> An optional list of tags for the deployment. <code>work_queue_name</code> The optional work queue that will handle the deployment's run <code>parameter_openapi_schema</code> JSON schema for flow parameters. <code>enforce_parameter_schema</code> Whether the API should validate the parameters passed to a flow run against the schema defined by <code>parameter_openapi_schema</code> <code>path</code> The path to the deployment.yaml file <code>entrypoint</code> The path to a flow entry point <code>storage_document_id</code> Storage block configured for the deployment. <code>infrastructure_document_id</code> Infrastructure block configured for the deployment. <p>You can inspect a deployment using the CLI with the <code>prefect deployment inspect</code> command, referencing the deployment with <code>&lt;flow_name&gt;/&lt;deployment_name&gt;</code>.</p> <pre><code>$ prefect deployment inspect 'Cat Facts/catfact'\n{\n    'id': '76a9f1ac-4d8c-4a92-8869-615bec502685',\n    'created': '2022-07-26T03:48:14.723328+00:00',\n    'updated': '2022-07-26T03:50:02.043238+00:00',\n    'name': 'catfact',\n    'version': '899b136ebc356d58562f48d8ddce7c19',\n    'description': None,\n    'flow_id': '2c7b36d1-0bdb-462e-bb97-f6eb9fef6fd5',\n    'schedule': None,\n    'is_schedule_active': True,\n    'infra_overrides': {},\n    'parameters': {},\n    'tags': [],\n    'work_queue_name': 'test',\n    'parameter_openapi_schema': {\n        'title': 'Parameters',\n        'type': 'object',\n        'properties': {'url': {'title': 'url'}},\n        'required': ['url']\n    },\n    'path': '/Users/terry/test/testflows/catfact',\n    'entrypoint': 'catfact.py:catfacts_flow',\n    'manifest_path': None,\n    'storage_document_id': None,\n    'infrastructure_document_id': 'f958db1c-b143-4709-846c-321125247e07',\n    'infrastructure': {\n        'type': 'process',\n        'env': {},\n        'labels': {},\n        'name': None,\n        'command': ['python', '-m', 'prefect.engine'],\n        'stream_output': True\n    }\n}\n</code></pre>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-from-a-deployment","title":"Create a flow run from a deployment","text":"","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-a-schedule","title":"Create a flow run with a schedule","text":"<p>If you specify a schedule for a deployment, the deployment will execute its flow automatically on that schedule as long as a Prefect server and agent are running. Prefect Cloud creates schedules flow runs automatically, and they will run on schedule if an agent is configured to pick up flow runs for the deployment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-an-event-trigger","title":"Create a flow run with an event trigger","text":"<p>deployment triggers are only available in Prefect Cloud</p> <p>Deployments can optionally take a trigger specification, which will configure an automation to run the deployment based on the presence or absence of events, and optionally pass event data into the deployment run as parameters via jinja templating.</p> <pre><code>triggers:\n  - enabled: true\n    match:\n      prefect.resource.id: prefect.flow-run.*\n    expect:\n      - prefect.flow-run.Completed\n    match_related:\n      prefect.resource.name: prefect.flow.etl-flow\n      prefect.resource.role: flow\n    parameters:\n      param_1: \"{{ event }}\"\n</code></pre> <p>When applied, this deployment will start a flow run upon the completion of the upstream flow specified in the <code>match_related</code> key, with the flow run passed in as a parameter. Triggers can be configured to respond to the presence or absence of arbitrary internal or external events. The trigger system and API are detailed in Automations.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-prefect-ui","title":"Create a flow run with Prefect UI","text":"<p>In the Prefect UI, you can click the Run button next to any deployment to execute an ad hoc flow run for that deployment.</p> <p>The <code>prefect deployment</code> CLI command provides commands for managing and running deployments locally.</p> Command Description <code>apply</code> Create or update a deployment from a YAML file. <code>build</code> Generate a deployment YAML from /path/to/file.py:flow_function. <code>delete</code> Delete a deployment. <code>inspect</code> View details about a deployment. <code>ls</code> View all deployments or deployments for specific flows. <code>pause-schedule</code> Pause schedule of a given deployment. <code>resume-schedule</code> Resume schedule of a given deployment. <code>run</code> Create a flow run for the given flow and deployment. <code>schedule</code> Commands for interacting with your deployment's schedules. <code>set-schedule</code> Set schedule for a given deployment. <p>Deprecated Schedule Commands</p> <p>The pause-schedule, resume-schedule, and set-schedule commands are deprecated due to the introduction of multi-schedule support for deployments. Use the new <code>prefect deployment schedule</code> command for enhanced flexibility and control over your deployment schedules.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-in-a-python-script","title":"Create a flow run in a Python script","text":"<p>You can create a flow run from a deployment in a Python script with the <code>run_deployment</code> function.</p> <pre><code>from prefect.deployments import run_deployment\n\n\ndef main():\n    response = run_deployment(name=\"flow-name/deployment-name\")\n    print(response)\n\n\nif __name__ == \"__main__\":\n   main()\n</code></pre> <p><code>PREFECT_API_URL</code> setting for agents</p> <p>You'll need to configure agents and work pools that can create flow runs for deployments in remote environments. <code>PREFECT_API_URL</code> must be set for the environment in which your agent is running.</p> <p>If you want the agent to communicate with Prefect Cloud from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#examples","title":"Examples","text":"<ul> <li>How to deploy Prefect flows to AWS</li> <li>How to deploy Prefect flows to GCP</li> <li>How to deploy Prefect flows to Azure</li> <li>How to deploy Prefect flows using files stored locally</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments/","title":"Deployments","text":"<p>Deployments are server-side representations of flows.  They store the crucial metadata needed for remote orchestration including when, where, and how a workflow should run. Deployments elevate workflows from functions that you must call manually to API-managed entities that can be triggered remotely.</p> <p>Here we will focus largely on the metadata that defines a deployment and how it is used.  Different ways of creating a deployment populate these fields differently.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#overview","title":"Overview","text":"<p>Every Prefect deployment references one and only one \"entrypoint\" flow (though that flow may itself call any number of subflows).  Different deployments may reference the same underlying flow, a useful pattern when developing or promoting workflow changes through staged environments.</p> <p>The complete schema that defines a deployment is as follows:</p> <pre><code>class Deployment:\n    \"\"\"\n    Structure of the schema defining a deployment\n    \"\"\"\n\n    # required defining data\n    name: str \n    flow_id: UUID\n    entrypoint: str\n    path: str = None\n\n    # workflow scheduling and parametrization\n    parameters: Optional[Dict[str, Any]] = None\n    parameter_openapi_schema: Optional[Dict[str, Any]] = None\n    schedules: list[Schedule] = None\n    paused: bool = False\n    trigger: Trigger = None\n\n    # metadata for bookkeeping\n    version: str = None\n    description: str = None\n    tags: list = None\n\n    # worker-specific fields\n    work_pool_name: str = None\n    work_queue_name: str = None\n    infra_overrides: Optional[Dict[str, Any]] = None\n    pull_steps: Optional[Dict[str, Any]] = None\n</code></pre> <p>All methods for creating Prefect deployments are interfaces for populating this schema. Let's look at each section in turn.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#required-data","title":"Required data","text":"<p>Deployments universally require both a <code>name</code> and a reference to an underlying <code>Flow</code>. In almost all instances of deployment creation, users do not need to concern themselves with the <code>flow_id</code> as most interfaces will only need the flow's name. Note that the deployment name is not required to be unique across all deployments but is required to be unique for a given flow ID. As a consequence, you will often see references to the deployment's unique identifying name <code>{FLOW_NAME}/{DEPLOYMENT_NAME}</code>. For example, triggering a run of a deployment from the Prefect CLI can be done via:</p> <pre><code>prefect deployment run my-first-flow/my-first-deployment\n</code></pre> <p>The other two fields are less obvious:</p> <ul> <li><code>path</code>: the path can generally be interpreted as the runtime working directory for the flow.  For example, if a deployment references a workflow defined within a Docker image, the <code>path</code> will be the absolute path to the parent directory where that workflow will run anytime the deployment is triggered.  This interpretation is more subtle in the case of flows defined in remote filesystems.</li> <li><code>entrypoint</code>: the entrypoint of a deployment is a relative reference to a function decorated as a flow that exists on some filesystem.  It is always specified relative to the <code>path</code>. Entrypoints use Python's standard path-to-object syntax (e.g., <code>path/to/file.py:function_name</code> or simply <code>path:object</code>).</li> </ul> <p>The entrypoint must reference the same flow as the flow ID.</p> <p>Note that Prefect requires that deployments reference flows defined within Python files. Flows defined within interactive REPLs or notebooks cannot currently be deployed as such.  They are still valid flows that will be monitored by the API and observable in the UI whenever they are run, but Prefect cannot trigger them.</p> <p>Deployments do not contain code definitions</p> <p>Deployment metadata references code that exists in potentially diverse locations within your environment. This separation of concerns means that your flow code stays within your storage and execution infrastructure and never lives on the Prefect server or database.</p> <p>This is the heart of the Prefect hybrid model: there's a boundary between your proprietary assets, such as your flow code, and the Prefect backend (including Prefect Cloud). </p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#scheduling-and-parametrization","title":"Scheduling and parametrization","text":"<p>One of the primary motivations for creating deployments of flows is to remotely schedule and trigger them. Just as flows can be called as functions with different input values, so can deployments be triggered or scheduled with different values through the use of parameters.</p> <p>The six fields here capture the necessary metadata to perform such actions:</p> <ul> <li><code>schedules</code>: a list of schedule objects. Most of the convenient interfaces for creating deployments allow users to avoid creating this object themselves. For example, when updating a deployment schedule in the UI basic information such as a cron string or interval is all that's required.</li> <li><code>trigger</code> (Cloud-only): triggers allow you to define event-based rules for running a deployment. For more information see Automations.</li> <li><code>parameter_openapi_schema</code>: an OpenAPI compatible schema that defines the types and defaults for the flow's parameters. This is used by both the UI and the backend to expose options for creating manual runs as well as type validation.</li> <li><code>parameters</code>: default values of flow parameters that this deployment will pass on each run. These can be overwritten through a trigger or when manually creating a custom run.</li> <li><code>enforce_parameter_schema</code>: a boolean flag that determines whether the API should validate the parameters passed to a flow run against the schema defined by <code>parameter_openapi_schema</code>.</li> </ul> <p>Scheduling is asynchronous and decoupled</p> <p>Because deployments are nothing more than metadata, runs can be created at anytime. Note that pausing a schedule, updating your deployment, and other actions reset your auto-scheduled runs.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#running-a-deployed-flow-from-within-python-flow-code","title":"Running a deployed flow from within Python flow code","text":"<p>Prefect provides a <code>run_deployment</code> function that can be used to schedule the run of an existing deployment when your Python code executes.</p> <pre><code>from prefect.deployments import run_deployment\n\ndef main():\n    run_deployment(name=\"my_flow_name/my_deployment_name\")\n</code></pre> <p>Run a deployment without blocking</p> <p>By default, <code>run_deployment</code> blocks until the scheduled flow run finishes executing. Pass <code>timeout=0</code> to return immediately and not block.</p> <p>If you call <code>run_deployment</code> from within a flow or task, the scheduled flow run will be linked to the calling flow run (or the calling task's flow run) as a subflow run by default.</p> <p>Subflow runs have different behavior than regular flow runs. For example, a  subflow run can't be suspended independently of its parent flow. If you'd rather not link the scheduled flow run to the calling flow or task run, you can disable this behavior by passing <code>as_subflow=False</code>:</p> <pre><code>from prefect import flow\nfrom prefect.deployments import run_deployment\n\n\n@flow\ndef my_flow():\n    # The scheduled flow run will not be linked to this flow as a subflow.\n    run_deployment(name=\"my_other_flow/my_deployment_name\", as_subflow=False)\n</code></pre> <p>The return value of <code>run_deployment</code> is a FlowRun object containing metadata about the scheduled run. You can use this object to retrieve information about the run after calling <code>run_deployment</code>:</p> <pre><code>from prefect import get_client\nfrom prefect.deployments import run_deployment\n\ndef main():\n    flow_run = run_deployment(name=\"my_flow_name/my_deployment_name\")\n    flow_run_id = flow_run.id\n\n    # If you save the flow run's ID, you can use it later to retrieve\n    # flow run metadata again, e.g. to check if it's completed.\n    async with get_client() as client:\n        flow_run = client.read_flow_run(flow_run_id)\n        print(f\"Current state of the flow run: {flow_run.state}\")\n</code></pre> <p>Using the Prefect client</p> <p>For more information on using the Prefect client to interact with Prefect's REST API, see our guide.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#versioning-and-bookkeeping","title":"Versioning and bookkeeping","text":"<p>Versions, descriptions and tags are omnipresent fields throughout Prefect that can be easy to overlook. However, putting some extra thought into how you use these fields can pay dividends down the road.</p> <ul> <li><code>version</code>: versions are always set by the client and can be any arbitrary string.  We recommend tightly coupling this field on your deployments to your software development lifecycle.  For example if you leverage <code>git</code> to manage code changes, use either a tag or commit hash in this field. If you don't set a value for the version, Prefect will compute a hash</li> <li><code>description</code>: the description field of a deployment is a place to provide rich reference material for downstream stakeholders such as intended use and parameter documentation. Markdown formatting will be rendered in the Prefect UI, allowing for section headers, links, tables, and other formatting. If not provided explicitly, Prefect will use the docstring of your flow function as a default value.</li> <li><code>tags</code>: tags are a mechanism for grouping related work together across a diverse set of objects. Tags set on a deployment will be inherited by that deployment's flow runs. These tags can then be used to filter what runs are displayed on the primary UI dashboard, allowing you to customize different views into your work. In addition, in Prefect Cloud you can easily find objects through searching by tag.</li> </ul> <p>All of these bits of metadata can be leveraged to great effect by injecting them into the processes that Prefect is orchestrating. For example you can use both run ID and versions to organize files that you produce from your workflows, or by associating your flow run's tags with the metadata of a job it orchestrates. This metadata is available during execution through Prefect runtime.</p> <p>Everything has a version</p> <p>Deployments aren't the only entity in Prefect with a version attached; both flows and tasks also have versions that can be set through their respective decorators. These versions will be sent to the API anytime the flow or task is run and thereby allow you to audit your changes across all levels.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#workers-and-work-pools","title":"Workers and Work Pools","text":"<p>Workers and work pools are an advanced deployment pattern that allow you to dynamically provision infrastructure for each flow run. In addition, the work pool job template interface allows users to create and govern opinionated interfaces to their workflow infrastructure. To do this, a deployment using workers needs to evaluate the following fields:</p> <ul> <li><code>work_pool_name</code>: the name of the work pool this deployment will be associated with. Work pool types mirror infrastructure types and therefore the decision here affects the options available for the other fields.</li> <li><code>work_queue_name</code>: if you are using work queues to either manage priority or concurrency, you can associate a deployment with a specific queue within a work pool using this field.</li> <li><code>infra_overrides</code>: often called <code>job_variables</code> within various interfaces, this field allows deployment authors to customize whatever infrastructure options have been exposed on this work pool. This field is often used for things such as Docker image names, Kubernetes annotations and limits, and environment variables.</li> <li><code>pull_steps</code>: a JSON description of steps that should be performed to retrieve flow code or configuration and prepare the runtime environment for workflow execution.</li> </ul> <p>Pull steps allow users to highly decouple their workflow architecture. For example, a common use of pull steps is to dynamically pull code from remote filesystems such as GitHub with each run of their deployment.</p> <p>For more information see the guide to deploying with a worker.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#two-approaches-to-deployments","title":"Two approaches to deployments","text":"<p>There are two primary ways to deploy flows with Prefect, differentiated by how much control Prefect has over the infrastructure in which the flows run.</p> <p>In one setup, deploying Prefect flows is analogous to deploying a webserver - users author their workflows and then start a long-running process (often within a Docker container) that is responsible for managing all of the runs for the associated deployment(s).</p> <p>In the other setup, you do a little extra up-front work to set up a work pool and a base job template that defines how individual flow runs will be submitted to infrastructure.</p> <p>Prefect provides several types of work pools corresponding to different types of infrastructure. Prefect Cloud provides a Prefect Managed work pool option that is the simplest way to run workflows remotely. A cloud-provider account, such as AWS, is not required with a Prefect Managed work pool.</p> <p>Some work pool types require a client-side worker to submit job definitions to the appropriate infrastructure with each run.</p> <p>Each of these setups can support production workloads.  The choice ultimately boils down to your use case and preferences.  Read further to decide which setup is best for your situation.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#serving-flows-on-long-lived-infrastructure","title":"Serving flows on long-lived infrastructure","text":"<p>When you have several flows running regularly, the <code>serve</code> method of the <code>Flow</code> object or the <code>serve</code> utility is a great option for managing multiple flows simultaneously.</p> <p>Once you have authored your flow and decided on its deployment settings as described above, all that's left is to run this long-running process in a location of your choosing. The process will stay in communication with the Prefect API, monitoring for work and submitting each run within an individual subprocess. Note that because runs are submitted to subprocesses, any external infrastructure configuration will need to be setup beforehand and kept associated with this process.</p> <p>This approach has many benefits:</p> <ul> <li>Users are in complete control of their infrastructure, and anywhere the \"serve\" Python process can run is a suitable deployment environment.</li> <li>It is simple to reason about.</li> <li>Creating deployments requires a minimal set of decisions.</li> <li>Iteration speed is fast.</li> </ul> <p>However, there are a few reasons you might consider running flows on dynamically provisioned infrastructure with work pools instead:</p> <ul> <li>Flows that have expensive infrastructure needs may be more costly in this setup due to the long-running process.</li> <li>Flows with heterogeneous infrastructure needs across runs will be more difficult to configure and schedule.</li> <li>Large volumes of deployments can be harder to track.</li> <li>If your internal team structure requires that deployment authors be members of a different team than the team managing infrastructure, the work pool interface may be preferred.</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#dynamically-provisioning-infrastructure-with-work-pools","title":"Dynamically provisioning infrastructure with work pools","text":"<p>Work pools allow Prefect to exercise greater control of the infrastructure on which flows run. Options for serverless work pools allow you to scale to zero when workflows aren't running. Prefect even provides you with the ability to provision cloud infrastructure via a single CLI command, if you use a Prefect Cloud push work pool option.</p> <p>With work pools:</p> <ul> <li>You can configure and monitor infrastructure configuration within the Prefect UI.</li> <li>Infrastructure is ephemeral and dynamically provisioned.</li> <li>Prefect is more infrastructure-aware and therefore collects more event data from your infrastructure by default.</li> <li>Highly decoupled setups are possible.</li> </ul> <p>You don't have to commit to one approach</p> <p>You are not required to use only one of these approaches for your deployments. You can mix and match approaches based on the needs of each flow. Further, you can change the deployment approach for a particular flow as its needs evolve. For example, you might use workers for your expensive machine learning pipelines, but use the serve mechanics for smaller, more frequent file-processing pipelines.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/filesystems/","title":"Filesystems","text":"<p>A filesystem block is an object that allows you to read and write data from paths. Prefect provides multiple built-in file system types that cover a wide range of use cases. </p> <ul> <li><code>LocalFileSystem</code></li> <li><code>RemoteFileSystem</code></li> <li><code>Azure</code></li> <li><code>GitHub</code></li> <li><code>GitLab</code></li> <li><code>GCS</code></li> <li><code>S3</code></li> <li><code>SMB</code></li> </ul> <p>Additional file system types are available in Prefect Collections.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#local-filesystem","title":"Local filesystem","text":"<p>The <code>LocalFileSystem</code> block enables interaction with the files in your current development environment. </p> <p><code>LocalFileSystem</code> properties include:</p> Property Description basepath String path to the location of files on the local filesystem. Access to files outside of the base path will not be allowed. <pre><code>from prefect.filesystems import LocalFileSystem\n\nfs = LocalFileSystem(basepath=\"/foo/bar\")\n</code></pre> <p>Limited access to local file system</p> <p>Be aware that <code>LocalFileSystem</code> access is limited to the exact path provided. This file system may not be ideal for some use cases. The execution environment for your workflows may not have the same file system as the environment you are writing and deploying your code on. </p> <p>Use of this file system can limit the availability of results after a flow run has completed or prevent the code for a flow from being retrieved successfully at the start of a run.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#remote-file-system","title":"Remote file system","text":"<p>The <code>RemoteFileSystem</code> block enables interaction with arbitrary remote file systems. Under the hood, <code>RemoteFileSystem</code> uses <code>fsspec</code> and supports any file system that <code>fsspec</code> supports. </p> <p><code>RemoteFileSystem</code> properties include:</p> Property Description basepath String path to the location of files on the remote filesystem. Access to files outside of the base path will not be allowed. settings Dictionary containing extra parameters required to access the remote file system. <p>The file system is specified using a protocol:</p> <ul> <li><code>s3://my-bucket/my-folder/</code> will use S3</li> <li><code>gcs://my-bucket/my-folder/</code> will use GCS</li> <li><code>az://my-bucket/my-folder/</code> will use Azure</li> </ul> <p>For example, to use it with Amazon S3:</p> <pre><code>from prefect.filesystems import RemoteFileSystem\n\nblock = RemoteFileSystem(basepath=\"s3://my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>You may need to install additional libraries to use some remote storage types.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#remotefilesystem-examples","title":"RemoteFileSystem examples","text":"<p>How can we use <code>RemoteFileSystem</code> to store our flow code? The following is a use case where we use MinIO as a storage backend:</p> <pre><code>from prefect.filesystems import RemoteFileSystem\n\nminio_block = RemoteFileSystem(\n    basepath=\"s3://my-bucket\",\n    settings={\n        \"key\": \"MINIO_ROOT_USER\",\n        \"secret\": \"MINIO_ROOT_PASSWORD\",\n        \"client_kwargs\": {\"endpoint_url\": \"http://localhost:9000\"},\n    },\n)\nminio_block.save(\"minio\")\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#azure","title":"Azure","text":"<p>The <code>Azure</code> file system block enables interaction with Azure Datalake and Azure Blob Storage. Under the hood, the <code>Azure</code> block uses <code>adlfs</code>.</p> <p><code>Azure</code> properties include:</p> Property Description bucket_path String path to the location of files on the remote filesystem. Access to files outside of the bucket path will not be allowed. azure_storage_connection_string Azure storage connection string. azure_storage_account_name Azure storage account name. azure_storage_account_key Azure storage account key. azure_storage_tenant_id Azure storage tenant ID. azure_storage_client_id Azure storage client ID. azure_storage_client_secret Azure storage client secret. azure_storage_anon Anonymous authentication, disable to use <code>DefaultAzureCredential</code>. <p>To create a block:</p> <pre><code>from prefect.filesystems import Azure\n\nblock = Azure(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb az/dev\n</code></pre> <p>You need to install <code>adlfs</code> to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#github","title":"GitHub","text":"<p>The <code>GitHub</code> filesystem block enables interaction with GitHub repositories. This block is read-only and works with both public and private repositories.</p> <p><code>GitHub</code> properties include:</p> Property Description reference An optional reference to pin to, such as a branch name or tag. repository The URL of a GitHub repository to read from, in either HTTPS or SSH format. access_token A GitHub Personal Access Token (PAT) with <code>repo</code> scope. <p>To create a block:</p> <pre><code>from prefect.filesystems import GitHub\n\nblock = GitHub(\n    repository=\"https://github.com/my-repo/\",\n    access_token=&lt;my_access_token&gt; # only required for private repos\n)\nblock.get_directory(\"folder-in-repo\") # specify a subfolder of repo\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb github/dev -a\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#gitlabrepository","title":"GitLabRepository","text":"<p>The <code>GitLabRepository</code> block is read-only and works with private GitLab repositories.</p> <p><code>GitLabRepository</code> properties include:</p> Property Description reference An optional reference to pin to, such as a branch name or tag. repository The URL of a GitLab repository to read from, in either HTTPS or SSH format. credentials A <code>GitLabCredentials</code> block with Personal Access Token (PAT) with <code>read_repository</code> scope. <p>To create a block:</p> <pre><code>from prefect_gitlab.credentials import GitLabCredentials\nfrom prefect_gitlab.repositories import GitLabRepository\n\ngitlab_creds = GitLabCredentials(token=\"YOUR_GITLAB_ACCESS_TOKEN\")\ngitlab_repo = GitLabRepository(\n    repository=\"https://gitlab.com/yourorg/yourrepo.git\",\n    reference=\"main\",\n    credentials=gitlab_creds,\n)\ngitlab_repo.save(\"dev\")\n</code></pre> <p>To use it in a deployment (and apply):</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb gitlab-repository/dev -a\n</code></pre> <p>Note that to use this block, you need to install the <code>prefect-gitlab</code> collection.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#gcs","title":"GCS","text":"<p>The <code>GCS</code> file system block enables interaction with Google Cloud Storage. Under the hood, <code>GCS</code> uses <code>gcsfs</code>.</p> <p><code>GCS</code> properties include:</p> Property Description bucket_path A GCS bucket path service_account_info The contents of a service account keyfile as a JSON string. project The project the GCS bucket resides in. If not provided, the project will be inferred from the credentials or environment. <p>To create a block:</p> <pre><code>from prefect.filesystems import GCS\n\nblock = GCS(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb gcs/dev\n</code></pre> <p>You need to install <code>gcsfs</code>to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#s3","title":"S3","text":"<p>The <code>S3</code> file system block enables interaction with Amazon S3. Under the hood, <code>S3</code> uses <code>s3fs</code>.</p> <p><code>S3</code> properties include:</p> Property Description bucket_path An S3 bucket path aws_access_key_id AWS Access Key ID aws_secret_access_key AWS Secret Access Key <p>To create a block:</p> <pre><code>from prefect.filesystems import S3\n\nblock = S3(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb s3/dev\n</code></pre> <p>You need to install <code>s3fs</code>to use this block.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#smb","title":"SMB","text":"<p>The <code>SMB</code> file system block enables interaction with SMB shared network storage. Under the hood, <code>SMB</code> uses <code>smbprotocol</code>. Used to connect to Windows-based SMB shares from Linux-based Prefect flows. The SMB file system block is able to copy files, but cannot create directories.</p> <p><code>SMB</code> properties include:</p> Property Description basepath String path to the location of files on the remote filesystem. Access to files outside of the base path will not be allowed. smb_host Hostname or IP address where SMB network share is located. smb_port Port for SMB network share (defaults to 445). smb_username SMB username with read/write permissions. smb_password SMB password. <p>To create a block:</p> <pre><code>from prefect.filesystems import SMB\n\nblock = SMB(basepath=\"my-share/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb smb/dev\n</code></pre> <p>You need to install <code>smbprotocol</code> to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#handling-credentials-for-cloud-object-storage-services","title":"Handling credentials for cloud object storage services","text":"<p>If you leverage <code>S3</code>, <code>GCS</code>, or <code>Azure</code> storage blocks, and you don't explicitly configure credentials on the respective storage block, those credentials will be inferred from the environment. Make sure to set those either explicitly on the block or as environment variables, configuration files, or IAM roles within both the build and runtime environment for your deployments.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#filesystem-package-dependencies","title":"Filesystem package dependencies","text":"<p>A Prefect installation and doesn't include filesystem-specific package dependencies such as <code>s3fs</code>, <code>gcsfs</code> or <code>adlfs</code>. This includes Prefect base Docker images.</p> <p>You must ensure that filesystem-specific libraries are installed in an execution environment where they will be used by flow runs.</p> <p>In Dockerized deployments using the Prefect base image, you can leverage the <code>EXTRA_PIP_PACKAGES</code> environment variable. Those dependencies will be installed at runtime within your Docker container or Kubernetes Job before the flow starts running. </p> <p>In Dockerized deployments using a custom image, you must include the filesystem-specific package dependency in your image.</p> <p>Here is an example from a deployment YAML file showing how to specify the installation of <code>s3fs</code> from into your image:</p> <pre><code>infrastructure:\n  type: docker-container\n  env:\n    EXTRA_PIP_PACKAGES: s3fs  # could be gcsfs, adlfs, etc.\n</code></pre> <p>You may specify multiple dependencies by providing a comma-delimted list.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#saving-and-loading-file-systems","title":"Saving and loading file systems","text":"<p>Configuration for a file system can be saved to the Prefect API. For example:</p> <pre><code>fs = RemoteFileSystem(basepath=\"s3://my-bucket/folder/\")\nfs.write_path(\"foo\", b\"hello\")\nfs.save(\"dev-s3\")\n</code></pre> <p>This file system can be retrieved for later use with <code>load</code>.</p> <pre><code>fs = RemoteFileSystem.load(\"dev-s3\")\nfs.read_path(\"foo\")  # b'hello'\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#readable-and-writable-file-systems","title":"Readable and writable file systems","text":"<p>Prefect provides two abstract file system types, <code>ReadableFileSystem</code> and <code>WriteableFileSystem</code>. </p> <ul> <li>All readable file systems must implement <code>read_path</code>, which takes a file path to read content from and returns bytes. </li> <li>All writeable file systems must implement <code>write_path</code> which takes a file path and content and writes the content to the file as bytes. </li> </ul> <p>A file system may implement both of these types.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/flows/","title":"Flows","text":"<p>Flows are the most central Prefect object. A flow is a container for workflow logic as-code and allows users to configure how their workflows behave. Flows are defined as Python functions, and any Python function is eligible to be a flow.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flows-overview","title":"Flows overview","text":"<p>Flows can be thought of as special types of functions. They can take inputs, perform work, and return an output. In fact, you can turn any function into a Prefect flow by adding the <code>@flow</code> decorator. When a function becomes a flow, its behavior changes, giving it the following advantages:</p> <ul> <li>Every invocation of this function is tracked and all state transitions are reported to the API, allowing observation of flow execution.</li> <li>Input arguments are automatically type checked and coerced to the appropriate types.</li> <li>Retries can be performed on failure.</li> <li>Timeouts can be enforced to prevent unintentional, long-running workflows.</li> </ul> <p>Flows also take advantage of automatic Prefect logging to capture details about flow runs such as run time and final state.</p> <p>Flows can include calls to tasks as well as to other flows, which Prefect calls \"subflows\" in this context. Flows may be defined within modules and imported for use as subflows in your flow definitions.</p> <p>Deployments elevate individual workflows from functions that you call manually to API-managed entities.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flow-runs","title":"Flow runs","text":"<p>A flow run represents a single execution of the flow.</p> <p>You can create a flow run by calling the flow manually. For example, by running a Python script or importing the flow into an interactive session and calling it.</p> <p>You can also create a flow run by:</p> <ul> <li>Using external schedulers such as <code>cron</code> to invoke a flow function</li> <li>Creating a deployment on Prefect Cloud or a locally run Prefect server.</li> <li>Creating a flow run for the deployment via a schedule, the Prefect UI, or the Prefect API.</li> </ul> <p>However you run the flow, the Prefect API monitors the flow run, capturing flow run state for observability.</p> <p>When you run a flow that contains tasks or additional flows, Prefect will track the relationship of each child run to the parent flow run.</p> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#writing-flows","title":"Writing flows","text":"<p>The <code>@flow</code> decorator is used to designate a flow:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow():\n    return\n</code></pre> <p>There are no rigid rules for what code you include within a flow definition - all valid Python is acceptable.</p> <p>Flows are uniquely identified by name. You can provide a <code>name</code> parameter value for the flow. If you don't provide a name, Prefect uses the flow function name.</p> <pre><code>@flow(name=\"My Flow\")\ndef my_flow():\n    return\n</code></pre> <p>Flows can call tasks to allow Prefect to orchestrate and track more granular units of work:</p> <pre><code>from prefect import flow, task\n\n@task\ndef print_hello(name):\n    print(f\"Hello {name}!\")\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    print_hello(name)\n</code></pre> <p>Flows and tasks</p> <p>There's nothing stopping you from putting all of your code in a single flow function \u2014 Prefect will happily run it!</p> <p>However, organizing your workflow code into smaller flow and task units lets you take advantage of Prefect features like retries, more granular visibility into runtime state, the ability to determine final state regardless of individual task state, and more.</p> <p>In addition, if you put all of your workflow logic in a single flow function and any line of code fails, the entire flow will fail and must be retried from the beginning.  This can be avoided by breaking up the code into multiple tasks.</p> <p>You may call any number of other tasks, subflows, and even regular Python functions within your flow.  You can pass parameters to your flow function that will be used elsewhere in the workflow, and Prefect will report on the progress and final state of any invocation.</p> <p>Prefect encourages \"small tasks\" \u2014 each one should represent a single logical step of your workflow.  This allows Prefect to better contain task failures.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flow-settings","title":"Flow settings","text":"<p>Flows allow a great deal of configuration by passing arguments to the decorator. Flows accept the following optional settings.</p> Argument Description <code>description</code> An optional string description for the flow. If not provided, the description will be pulled from the docstring for the decorated function. <code>name</code> An optional name for the flow. If not provided, the name will be inferred from the function. <code>retries</code> An optional number of times to retry on flow run failure. <code>retry_delay_seconds</code> An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero. <code>flow_run_name</code> An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables; this name can also be provided as a function that returns a string. <code>task_runner</code> An optional task runner to use for task execution within the flow when you <code>.submit()</code> tasks. If not provided and you <code>.submit()</code> tasks, the <code>ConcurrentTaskRunner</code> will be used. <code>timeout_seconds</code> An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called. <code>validate_parameters</code> Boolean indicating whether parameters passed to flows are validated by Pydantic. Default is <code>True</code>. <code>version</code> An optional version string for the flow. If not provided, we will attempt to create a version string as a hash of the file containing the wrapped function. If the file cannot be located, the version will be null. <p>For example, you can provide a <code>name</code> value for the flow. Here we've also used the optional <code>description</code> argument and specified a non-default task runner.</p> <pre><code>from prefect import flow\nfrom prefect.task_runners import SequentialTaskRunner\n\n@flow(name=\"My Flow\",\n      description=\"My flow using SequentialTaskRunner\",\n      task_runner=SequentialTaskRunner())\ndef my_flow():\n    return\n</code></pre> <p>You can also provide the description as the docstring on the flow function.</p> <pre><code>@flow(name=\"My Flow\",\n      task_runner=SequentialTaskRunner())\ndef my_flow():\n    \"\"\"My flow using SequentialTaskRunner\"\"\"\n    return\n</code></pre> <p>You can distinguish runs of this flow by providing a <code>flow_run_name</code>. This setting accepts a string that can optionally contain templated references to the parameters of your flow. The name will be formatted using Python's standard string formatting syntax as can be seen here:</p> <pre><code>import datetime\nfrom prefect import flow\n\n@flow(flow_run_name=\"{name}-on-{date:%A}\")\ndef my_flow(name: str, date: datetime.datetime):\n    pass\n\n# creates a flow run called 'marvin-on-Thursday'\nmy_flow(name=\"marvin\", date=datetime.datetime.now(datetime.timezone.utc))\n</code></pre> <p>Additionally this setting also accepts a function that returns a string for the flow run name:</p> <pre><code>import datetime\nfrom prefect import flow\n\ndef generate_flow_run_name():\n    date = datetime.datetime.now(datetime.timezone.utc)\n\n    return f\"{date:%A}-is-a-nice-day\"\n\n@flow(flow_run_name=generate_flow_run_name)\ndef my_flow(name: str):\n    pass\n\n# creates a flow run called 'Thursday-is-a-nice-day'\nif __name__ == \"__main__\":\n    my_flow(name=\"marvin\")\n</code></pre> <p>If you need access to information about the flow, use the <code>prefect.runtime</code> module. For example:</p> <pre><code>from prefect import flow\nfrom prefect.runtime import flow_run\n\ndef generate_flow_run_name():\n    flow_name = flow_run.flow_name\n\n    parameters = flow_run.parameters\n    name = parameters[\"name\"]\n    limit = parameters[\"limit\"]\n\n    return f\"{flow_name}-with-{name}-and-{limit}\"\n\n@flow(flow_run_name=generate_flow_run_name)\ndef my_flow(name: str, limit: int = 100):\n    pass\n\n# creates a flow run called 'my-flow-with-marvin-and-100'\nif __name__ == \"__main__\":\n    my_flow(name=\"marvin\")\n</code></pre> <p>Note that <code>validate_parameters</code> will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type. For example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#separating-logic-into-tasks","title":"Separating logic into tasks","text":"<p>The simplest workflow is just a <code>@flow</code> function that does all the work of the workflow.</p> <pre><code>from prefect import flow\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    print(f\"Hello {name}!\")\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>When you run this flow, you'll see output like the following:</p> <pre><code>$ python hello.py\n15:11:23.594 | INFO    | prefect.engine - Created flow run 'benevolent-donkey' for flow 'hello-world'\n15:11:23.594 | INFO    | Flow run 'benevolent-donkey' - Using task runner 'ConcurrentTaskRunner'\nHello Marvin!\n15:11:24.447 | INFO    | Flow run 'benevolent-donkey' - Finished in state Completed()\n</code></pre> <p>A better practice is to create <code>@task</code> functions that do the specific work of your flow, and use your <code>@flow</code> function as the conductor that orchestrates the flow of your application:</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>When you run this flow, you'll see the following output, which illustrates how the work is encapsulated in a task run.</p> <pre><code>$ python hello.py\n15:15:58.673 | INFO    | prefect.engine - Created flow run 'loose-wolverine' for flow 'Hello Flow'\n15:15:58.674 | INFO    | Flow run 'loose-wolverine' - Using task runner 'ConcurrentTaskRunner'\n15:15:58.973 | INFO    | Flow run 'loose-wolverine' - Created task run 'Print Hello-84f0fe0e-0' for task 'Print Hello'\nHello Marvin!\n15:15:59.037 | INFO    | Task run 'Print Hello-84f0fe0e-0' - Finished in state Completed()\n15:15:59.568 | INFO    | Flow run 'loose-wolverine' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#visualizing-flow-structure","title":"Visualizing flow structure","text":"<p>You can get a quick sense of the structure of your flow using the <code>.visualize()</code> method on your flow. Calling this method will attempt to produce a schematic diagram of your flow and tasks without actually running your flow code.</p> <p>Functions and code not inside of flows or tasks will still be run when calling <code>.visualize()</code>. This may have unintended consequences. Place your code into tasks to avoid unintended execution.</p> <p>To use the <code>visualize()</code> method, Graphviz must be installed and on your PATH. Please install Graphviz from http://www.graphviz.org/download/. And note: just installing the <code>graphviz</code> python package is not sufficient.</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@task(name=\"Print Hello Again\")\ndef print_hello_again(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    message2 = print_hello_again(message)\n\nif __name__ == \"__main__\":\n    hello_world.visualize()\n</code></pre> <p></p> <p>Prefect cannot automatically produce a schematic for dynamic workflows, such as those with loops or if/else control flow. In this case, you can provide tasks with mock return values for use in the <code>visualize()</code> call.</p> <pre><code>from prefect import flow, task\n@task(viz_return_value=[4])\ndef get_list():\n    return [1, 2, 3]\n\n@task\ndef append_one(n):\n    return n.append(6)\n\n@flow\ndef viz_return_value_tracked():\n    l = get_list()\n    for num in range(3):\n        l.append(5)\n        append_one(l)\n\nif __name__ == \"__main__\":\n    viz_return_value_tracked.visualize()\n</code></pre> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#composing-flows","title":"Composing flows","text":"<p>A subflow run is created when a flow function is called inside the execution of another flow. The primary flow is the \"parent\" flow. The flow created within the parent is the \"child\" flow or \"subflow.\"</p> <p>Subflow runs behave like normal flow runs. There is a full representation of the flow run in the backend as if it had been called separately. When a subflow starts, it will create a new task runner for tasks within the subflow. When the subflow completes, the task runner is shut down.</p> <p>Subflows will block execution of the parent flow until completion. However, asynchronous subflows can be run concurrently by using AnyIO task groups or asyncio.gather.</p> <p>Subflows differ from normal flows in that they will resolve any passed task futures into data. This allows data to be passed from the parent flow to the child easily.</p> <p>The relationship between a child and parent flow is tracked by creating a special task run in the parent flow. This task run will mirror the state of the child flow run.</p> <p>A task that represents a subflow will be annotated as such in its <code>state_details</code> via the presence of a <code>child_flow_run_id</code> field. A subflow can be identified via the presence of a <code>parent_task_run_id</code> on <code>state_details</code>.</p> <p>You can define multiple flows within the same file. Whether running locally or via a deployment, you must indicate which flow is the entrypoint for a flow run.</p> <p>Cancelling subflow runs</p> <p>Inline subflow runs, specifically those created without <code>run_deployment</code>, cannot be cancelled without cancelling their parent flow run. If you may need to cancel a subflow run independent of its parent flow run, we recommend deploying it separately and starting it using the run_deployment function.</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Subflow\")\ndef my_subflow(msg):\n    print(f\"Subflow says: {msg}\")\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    my_subflow(message)\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>You can also define flows or tasks in separate modules and import them for usage. For example, here's a simple subflow module:</p> <pre><code>from prefect import flow, task\n\n@flow(name=\"Subflow\")\ndef my_subflow(msg):\n    print(f\"Subflow says: {msg}\")\n</code></pre> <p>Here's a parent flow that imports and uses <code>my_subflow()</code> as a subflow:</p> <pre><code>from prefect import flow, task\nfrom subflow import my_subflow\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    my_subflow(message)\n\nhello_world(\"Marvin\")\n</code></pre> <p>Running the <code>hello_world()</code> flow (in this example from the file <code>hello.py</code>) creates a flow run like this:</p> <pre><code>$ python hello.py\n15:19:21.651 | INFO    | prefect.engine - Created flow run 'daft-cougar' for flow 'Hello Flow'\n15:19:21.651 | INFO    | Flow run 'daft-cougar' - Using task runner 'ConcurrentTaskRunner'\n15:19:21.945 | INFO    | Flow run 'daft-cougar' - Created task run 'Print Hello-84f0fe0e-0' for task 'Print Hello'\nHello Marvin!\n15:19:22.055 | INFO    | Task run 'Print Hello-84f0fe0e-0' - Finished in state Completed()\n15:19:22.107 | INFO    | Flow run 'daft-cougar' - Created subflow run 'ninja-duck' for flow 'Subflow'\nSubflow says: Hello Marvin!\n15:19:22.794 | INFO    | Flow run 'ninja-duck' - Finished in state Completed()\n15:19:23.215 | INFO    | Flow run 'daft-cougar' - Finished in state Completed('All states completed.')\n</code></pre> <p>Subflows or tasks?</p> <p>In Prefect you can call tasks or subflows to do work within your workflow, including passing results from other tasks to your subflow. So a common question is:</p> <p>\"When should I use a subflow instead of a task?\"</p> <p>We recommend writing tasks that do a discrete, specific piece of work in your workflow: calling an API, performing a database operation, analyzing or transforming a data point.  Prefect tasks are well suited to parallel or distributed execution using distributed computation frameworks such as Dask or Ray.  For troubleshooting, the more granular you create your tasks, the easier it is to find and fix issues should a task fail.</p> <p>Subflows enable you to group related tasks within your workflow.  Here are some scenarios where you might choose to use a subflow rather than calling tasks individually:</p> <ul> <li>Observability: Subflows, like any other flow run, have first-class observability within the Prefect UI and Prefect Cloud. You'll see subflow status in the Flow Runs dashboard rather than having to dig down into the tasks within a specific flow run. See Final state determination for some examples of leveraging task state within flows.</li> <li>Conditional flows: If you have a group of tasks that run only under certain conditions, you can group them within a subflow and conditionally run the subflow rather than each task individually.</li> <li>Parameters: Flows have first-class support for parameterization, making it easy to run the same group of tasks in different use cases by simply passing different parameters to the subflow in which they run.</li> <li>Task runners: Subflows enable you to specify the task runner used for tasks within the flow. For example, if you want to optimize parallel execution of certain tasks with Dask, you can group them in a subflow that uses the Dask task runner. You can use a different task runner for each subflow.</li> </ul>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#parameters","title":"Parameters","text":"<p>Flows can be called with both positional and keyword arguments. These arguments are resolved at runtime into a dictionary of parameters mapping name to value. These parameters are stored by the Prefect orchestration engine on the flow run object.</p> <p>Prefect API requires keyword arguments</p> <p>When creating flow runs from the Prefect API, parameter names must be specified when overriding defaults \u2014 they cannot be positional.</p> <p>Type hints provide an easy way to enforce typing on your flow parameters via pydantic. This means any pydantic model used as a type hint within a flow will be coerced automatically into the relevant object type:</p> <pre><code>from prefect import flow\nfrom pydantic import BaseModel\n\nclass Model(BaseModel):\n    a: int\n    b: float\n    c: str\n\n@flow\ndef model_validator(model: Model):\n    print(model)\n</code></pre> <p>Note that parameter values can be provided to a flow via API using a deployment. Flow run parameters sent to the API on flow calls are coerced to a serializable form. Type hints on your flow functions provide you a way of automatically coercing JSON provided values to their appropriate Python representation.</p> <p>For example, to automatically convert something to a datetime:</p> <pre><code>from prefect import flow\nfrom datetime import datetime\n\n@flow\ndef what_day_is_it(date: datetime = None):\n    if date is None:\n        date = datetime.now(timezone.utc)\n    print(f\"It was {date.strftime('%A')} on {date.isoformat()}\")\n\nif __name__ == \"__main__\":\n    what_day_is_it(\"2021-01-01T02:00:19.180906\")\n</code></pre> <p>When you run this flow, you'll see the following output:</p> <pre><code>It was Friday on 2021-01-01T02:00:19.180906\n</code></pre> <p>Parameters are validated before a flow is run. If a flow call receives invalid parameters, a flow run is created in a <code>Failed</code> state. If a flow run for a deployment receives invalid parameters, it will move from a <code>Pending</code> state to a <code>Failed</code> without entering a <code>Running</code> state.</p> <p>Flow run parameters cannot exceed <code>512kb</code> in size</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#final-state-determination","title":"Final state determination","text":"<p>Prerequisite</p> <p>Read the documentation about states before proceeding with this section.</p> <p>The final state of the flow is determined by its return value. The following rules apply:</p> <ul> <li>If an exception is raised directly in the flow function, the flow run is marked as failed.</li> <li>If the flow does not return a value (or returns <code>None</code>), its state is determined by the states of all of the tasks and subflows within it.</li> <li>If any task run or subflow run failed, then the final flow run state is marked as <code>FAILED</code>.</li> <li>If any task run was cancelled, then the final flow run state is marked as <code>CANCELLED</code>.</li> <li>If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.</li> <li>If the flow run returns any other object, then it is marked as completed.</li> </ul> <p>The following examples illustrate each of these cases:</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#raise-an-exception","title":"Raise an exception","text":"<p>If an exception is raised within the flow function, the flow is immediately marked as failed.</p> <pre><code>from prefect import flow\n\n@flow\ndef always_fails_flow():\n    raise ValueError(\"This flow immediately fails\")\n\nif __name__ == \"__main__\":\n    always_fails_flow()\n</code></pre> <p>Running this flow produces the following result:</p> <pre><code>22:22:36.864 | INFO    | prefect.engine - Created flow run 'acrid-tuatara' for flow 'always-fails-flow'\n22:22:36.864 | INFO    | Flow run 'acrid-tuatara' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n22:22:37.060 | ERROR   | Flow run 'acrid-tuatara' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: This flow immediately fails\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-none","title":"Return <code>none</code>","text":"<p>A flow with no return statement is determined by the state of all of its task runs.</p> <pre><code>from prefect import flow, task\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_fails_flow():\n    always_fails_task.submit().result(raise_on_failure=False)\n    always_succeeds_task()\n\nif __name__ == \"__main__\":\n    always_fails_flow()\n</code></pre> <p>Running this flow produces the following result:</p> <pre><code>18:32:05.345 | INFO    | prefect.engine - Created flow run 'auburn-lionfish' for flow 'always-fails-flow'\n18:32:05.346 | INFO    | Flow run 'auburn-lionfish' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:32:05.582 | INFO    | Flow run 'auburn-lionfish' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:32:05.582 | INFO    | Flow run 'auburn-lionfish' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:32:05.610 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n18:32:05.638 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:32:05.658 | INFO    | Flow run 'auburn-lionfish' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:32:05.659 | INFO    | Flow run 'auburn-lionfish' - Executing 'always_succeeds_task-9c27db32-0' immediately...\nI'm fail safe!\n18:32:05.703 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:32:05.730 | ERROR   | Flow run 'auburn-lionfish' - Finished in state Failed('1/2 states failed.')\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-a-future","title":"Return a future","text":"<p>If a flow returns one or more futures, the final state is determined based on the underlying states.</p> <pre><code>from prefect import flow, task\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_succeeds_flow():\n    x = always_fails_task.submit().result(raise_on_failure=False)\n    y = always_succeeds_task.submit(wait_for=[x])\n    return y\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result \u2014 it succeeds because it returns the future of the task that succeeds:</p> <pre><code>18:35:24.965 | INFO    | prefect.engine - Created flow run 'whispering-guan' for flow 'always-succeeds-flow'\n18:35:24.965 | INFO    | Flow run 'whispering-guan' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:35:25.204 | INFO    | Flow run 'whispering-guan' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:35:25.205 | INFO    | Flow run 'whispering-guan' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:35:25.232 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n18:35:25.265 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:35:25.289 | INFO    | Flow run 'whispering-guan' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:35:25.289 | INFO    | Flow run 'whispering-guan' - Submitted task run 'always_succeeds_task-9c27db32-0' for execution.\nI'm fail safe!\n18:35:25.335 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:35:25.362 | INFO    | Flow run 'whispering-guan' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-multiple-states-or-futures","title":"Return multiple states or futures","text":"<p>If a flow returns a mix of futures and states, the final state is determined by resolving all futures to states, then determining if any of the states are not <code>COMPLETED</code>.</p> <pre><code>from prefect import task, flow\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I am bad task\")\n\n@task\ndef always_succeeds_task():\n    return \"foo\"\n\n@flow\ndef always_succeeds_flow():\n    return \"bar\"\n\n@flow\ndef always_fails_flow():\n    x = always_fails_task()\n    y = always_succeeds_task()\n    z = always_succeeds_flow()\n    return x, y, z\n</code></pre> <p>Running this flow produces the following result. It fails because one of the three returned futures failed. Note that the final state is <code>Failed</code>, but the states of each of the returned futures is included in the flow state:</p> <pre><code>20:57:51.547 | INFO    | prefect.engine - Created flow run 'impartial-gorilla' for flow 'always-fails-flow'\n20:57:51.548 | INFO    | Flow run 'impartial-gorilla' - Using task runner 'ConcurrentTaskRunner'\n20:57:51.645 | INFO    | Flow run 'impartial-gorilla' - Created task run 'always_fails_task-58ea43a6-0' for task 'always_fails_task'\n20:57:51.686 | INFO    | Flow run 'impartial-gorilla' - Created task run 'always_succeeds_task-c9014725-0' for task 'always_succeeds_task'\n20:57:51.727 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: I am bad task\n20:57:51.787 | INFO    | Task run 'always_succeeds_task-c9014725-0' - Finished in state Completed()\n20:57:51.808 | INFO    | Flow run 'impartial-gorilla' - Created subflow run 'unbiased-firefly' for flow 'always-succeeds-flow'\n20:57:51.884 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Finished in state Failed('Task run encountered an exception.')\n20:57:52.438 | INFO    | Flow run 'unbiased-firefly' - Finished in state Completed()\n20:57:52.811 | ERROR   | Flow run 'impartial-gorilla' - Finished in state Failed('1/3 states failed.')\nFailed(message='1/3 states failed.', type=FAILED, result=(Failed(message='Task run encountered an exception.', type=FAILED, result=ValueError('I am bad task'), task_run_id=5fd4c697-7c4c-440d-8ebc-dd9c5bbf2245), Completed(message=None, type=COMPLETED, result='foo', task_run_id=df9b6256-f8ac-457c-ba69-0638ac9b9367), Completed(message=None, type=COMPLETED, result='bar', task_run_id=cfdbf4f1-dccd-4816-8d0f-128750017d0c)), flow_run_id=6d2ec094-001a-4cb0-a24e-d2051db6318d)\n</code></pre> <p>Returning multiple states</p> <p>When returning multiple states, they must be contained in a <code>set</code>, <code>list</code>, or <code>tuple</code>. If other collection types are used, the result of the contained states will not be checked.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-a-manual-state","title":"Return a manual state","text":"<p>If a flow returns a manually created state, the final state is determined based on the return value.</p> <pre><code>from prefect import task, flow\nfrom prefect.states import Completed, Failed\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_succeeds_flow():\n    x = always_fails_task.submit()\n    y = always_succeeds_task.submit()\n    if y.result() == \"success\":\n        return Completed(message=\"I am happy with this result\")\n    else:\n        return Failed(message=\"How did this happen!?\")\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result.</p> <pre><code>18:37:42.844 | INFO    | prefect.engine - Created flow run 'lavender-elk' for flow 'always-succeeds-flow'\n18:37:42.845 | INFO    | Flow run 'lavender-elk' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:37:43.125 | INFO    | Flow run 'lavender-elk' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:37:43.126 | INFO    | Flow run 'lavender-elk' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:37:43.162 | INFO    | Flow run 'lavender-elk' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:37:43.163 | INFO    | Flow run 'lavender-elk' - Submitted task run 'always_succeeds_task-9c27db32-0' for execution.\n18:37:43.175 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\nI'm fail safe!\n18:37:43.217 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:37:43.236 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:37:43.264 | INFO    | Flow run 'lavender-elk' - Finished in state Completed('I am happy with this result')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-an-object","title":"Return an object","text":"<p>If the flow run returns any other object, then it is marked as completed.</p> <pre><code>from prefect import task, flow\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@flow\ndef always_succeeds_flow():\n    always_fails_task().submit()\n    return \"foo\"\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result.</p> <pre><code>21:02:45.715 | INFO    | prefect.engine - Created flow run 'sparkling-pony' for flow 'always-succeeds-flow'\n21:02:45.715 | INFO    | Flow run 'sparkling-pony' - Using task runner 'ConcurrentTaskRunner'\n21:02:45.816 | INFO    | Flow run 'sparkling-pony' - Created task run 'always_fails_task-58ea43a6-0' for task 'always_fails_task'\n21:02:45.853 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: I am bad task\n21:02:45.879 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Finished in state Failed('Task run encountered an exception.')\n21:02:46.593 | INFO    | Flow run 'sparkling-pony' - Finished in state Completed()\nCompleted(message=None, type=COMPLETED, result='foo', flow_run_id=7240e6f5-f0a8-4e00-9440-a7b33fb51153)\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#serving-a-flow","title":"Serving a flow","text":"<p>The simplest way to create a deployment for your flow is by calling its <code>serve</code> method. This method creates a deployment for the flow and starts a long-running process that monitors for work from the Prefect server. When work is found, it is executed within its own isolated subprocess.</p> hello_world.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef hello_world(name: str = \"world\", goodbye: bool = False):\n    print(f\"Hello {name} from Prefect! \ud83e\udd17\")\n\n    if goodbye:\n        print(f\"Goodbye {name}!\")\n\n\nif __name__ == \"__main__\":\n    # creates a deployment and stays running to monitor for work instructions generated on the server\n\n    hello_world.serve(name=\"my-first-deployment\",\n                      tags=[\"onboarding\"],\n                      parameters={\"goodbye\": True},\n                      interval=60)\n</code></pre> <p>This interface provides all of the configuration needed for a deployment with no strong infrastructure requirements:</p> <ul> <li>schedules</li> <li>event triggers</li> <li>metadata such as tags and description</li> <li>default parameter values</li> </ul> <p>Schedules are auto-paused on shutdown</p> <p>By default, stopping the process running <code>flow.serve</code> will pause the schedule for the deployment (if it has one). When running this in environments where restarts are expected use the <code>pause_on_shutdown=False</code> flag to prevent this behavior:</p> <pre><code>if __name__ == \"__main__\":\n    hello_world.serve(name=\"my-first-deployment\",\n                      tags=[\"onboarding\"],\n                      parameters={\"goodbye\": True},\n                      pause_on_shutdown=False,\n                      interval=60)\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#serving-multiple-flows-at-once","title":"Serving multiple flows at once","text":"<p>You can take this further and serve multiple flows with the same process using the <code>serve</code> utility along with the <code>to_deployment</code> method of flows:</p> <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n    serve(slow_deploy, fast_deploy)\n</code></pre> <p>The behavior and interfaces are identical to the single flow case.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#retrieve-a-flow-from-remote-storage","title":"Retrieve a flow from remote storage","text":"<p>Flows can be retrieved from remote storage using the <code>flow.from_source</code> method.</p> <p><code>flow.from_source</code> accepts a git repository URL  and an entrypoint pointing to the flow to load from the repository:</p> load_from_url.py<pre><code>from prefect import flow\n\nmy_flow = flow.from_source(\n    source=\"https://github.com/PrefectHQ/prefect.git\",\n    entrypoint=\"flows/hello_world.py:hello\"\n)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <pre><code>16:40:33.818 | INFO    | prefect.engine - Created flow run 'muscular-perch' for flow 'hello'\n16:40:34.048 | INFO    | Flow run 'muscular-perch' - Hello world!\n16:40:34.706 | INFO    | Flow run 'muscular-perch' - Finished in state Completed()\n</code></pre> <p>A flow entrypoint is the path to the file the flow is located in and the name of the flow function separated by a colon.</p> <p>If you need additional configuration, such as specifying a private repository, you can provide a <code>GitRepository</code> instead of URL:</p> load_from_storage.py<pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        branch=\"dev\",\n        credentials={\n            \"access_token\": Secret.load(\"github-access-token\").get()\n        }\n    ),\n    entrypoint=\"flows.py:my_flow\"\n)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>You can serve loaded flows</p> <p>Flows loaded from remote storage can be served using the same <code>serve</code> method as local flows:</p> serve_loaded_flow.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/org/repo.git\",\n        entrypoint=\"flows.py:my_flow\"\n    ).serve(name=\"my-deployment\")\n</code></pre> <p>When you serve a flow loaded from remote storage, the serving process will periodically poll your remote storage for updates to the flow's code.  This pattern allows you to update your flow code without restarting the serving process.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#pausing-or-suspending-a-flow-run","title":"Pausing or suspending a flow run","text":"<p>Prefect provides you with the ability to halt a flow run with two functions that are similar, but slightly different. When a flow run is paused, code execution is stopped and the process continues to run. When a flow run is suspended, code execution is stopped and so is the process.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#pausing-a-flow-run","title":"Pausing a flow run","text":"<p>Prefect enables pausing an in-progress flow run for manual approval. Prefect exposes this functionality via the <code>pause_flow_run</code> and <code>resume_flow_run</code> functions.</p> <p>Timeouts</p> <p>Paused flow runs time out after one hour by default. After the timeout, the flow run will fail with a message saying it paused and never resumed. You can specify a different timeout period in seconds using the <code>timeout</code> parameter.</p> <p>Most simply, <code>pause_flow_run</code> can be called inside a flow:</p> <pre><code>from prefect import task, flow, pause_flow_run, resume_flow_run\n\n@task\nasync def marvin_setup():\n    return \"a raft of ducks walk into a bar...\"\n\n\n@task\nasync def marvin_punchline():\n    return \"it's a wonder none of them ducked!\"\n\n\n@flow\nasync def inspiring_joke():\n    await marvin_setup()\n    await pause_flow_run(timeout=600)  # pauses for 10 minutes\n    await marvin_punchline()\n</code></pre> <p>You can also implement conditional pauses:</p> <pre><code>from prefect import task, flow, pause_flow_run\n\n@task\ndef task_one():\n    for i in range(3):\n        sleep(1)\n        print(i)\n\n@flow(log_prints=True)\ndef my_flow():\n    terminal_state = task_one.submit(return_state=True)\n    if terminal_state.type == StateType.COMPLETED:\n        print(\"Task one succeeded! Pausing flow run..\")\n        pause_flow_run(timeout=2) \n    else:\n        print(\"Task one failed. Skipping pause flow run..\")\n</code></pre> <p>Calling this flow will block code execution after the first task and wait for resumption to deliver the punchline.</p> <pre><code>await inspiring_joke()\n&gt; \"a raft of ducks walk into a bar...\"\n</code></pre> <p>Paused flow runs can be resumed by clicking the Resume button in the Prefect UI or calling the <code>resume_flow_run</code> utility via client code.</p> <pre><code>resume_flow_run(FLOW_RUN_ID)\n</code></pre> <p>The paused flow run will then finish!</p> <pre><code>&gt; \"it's a wonder none of them ducked!\"\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#suspending-a-flow-run","title":"Suspending a flow run","text":"<p>Similar to pausing a flow run, Prefect enables suspending an in-progress flow run.</p> <p>The difference between pausing and suspending a flow run</p> <p>There is an important difference between pausing and suspending a flow run. When you pause a flow run, the flow code is still running but is blocked until someone resumes the flow. This is not the case with suspending a flow run! When you suspend a flow run, the flow exits completely and the infrastructure running it (e.g., a Kubernetes Job) tears down.</p> <p>This means that you can suspend flow runs to save costs instead of paying for long-running infrastructure.  However, when the flow run resumes, the flow code will execute again from the beginning of the flow, so you should use tasks and task caching to avoid recomputing expensive operations.</p> <p>Prefect exposes this functionality via the <code>suspend_flow_run</code> and <code>resume_flow_run</code> functions, as well as the Prefect UI.</p> <p>When called inside of a flow <code>suspend_flow_run</code> will immediately suspend execution of the flow run. The flow run will be marked as <code>Suspended</code> and will not be resumed until <code>resume_flow_run</code> is called.</p> <p>Timeouts</p> <p>Suspended flow runs time out after one hour by default. After the timeout, the flow run will fail with a message saying it suspended and never resumed. You can specify a different timeout period in seconds using the <code>timeout</code> parameter or pass <code>timeout=None</code> for no timeout.</p> <p>Here is an example of a flow that does not block flow execution while paused. This flow will exit after one task, and will be rescheduled upon resuming. The stored result of the first task is retrieved instead of being rerun.</p> <pre><code>from prefect import flow, pause_flow_run, task\n\n@task(persist_result=True)\ndef foo():\n    return 42\n\n@flow(persist_result=True)\ndef noblock_pausing():\n    x = foo.submit()\n    pause_flow_run(timeout=30, reschedule=True)\n    y = foo.submit()\n    z = foo(wait_for=[x])\n    alpha = foo(wait_for=[y])\n    omega = foo(wait_for=[x, y])\n</code></pre> <p>Flow runs can be suspended out-of-process by calling <code>suspend_flow_run(flow_run_id=&lt;ID&gt;)</code> or selecting the Suspend button in the Prefect UI or Prefect Cloud.</p> <p>Suspended flow runs can be resumed by clicking the Resume button in the Prefect UI or calling the <code>resume_flow_run</code> utility via client code.</p> <pre><code>resume_flow_run(FLOW_RUN_ID)\n</code></pre> <p>Subflows can't be suspended independently of their parent run</p> <p>You can't suspend a subflow run independently of its parent flow run.</p> <p>If you use a flow to schedule a flow run with <code>run_deployment</code>, the scheduled flow run will be linked to the calling flow as a subflow run by default. This means you won't be able to suspend the scheduled flow run independently of the calling flow. Call <code>run_deployment</code> with <code>as_subflow=False</code> to disable this linking if you need to be able to suspend the scheduled flow run independently of the calling flow.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#waiting-for-input-when-pausing-or-suspending-a-flow-run","title":"Waiting for input when pausing or suspending a flow run","text":"<p>Experimental</p> <p>The <code>wait_for_input</code> parameter used in the <code>pause_flow_run</code> or <code>suspend_flow_run</code> functions is an experimental feature. The interface or behavior of this feature may change without warning in future releases.</p> <p>If you encounter any issues, please let us know in Slack or with a Github issue.</p> <p>When pausing or suspending a flow run you may want to wait for input from a user. Prefect provides a way to do this by leveraging the <code>pause_flow_run</code> and <code>suspend_flow_run</code> functions. These functions accept a <code>wait_for_input</code> argument, the value of which should be a subclass of <code>prefect.input.RunInput</code>, a pydantic model. When resuming the flow run, users are required to provide data for this model. Upon successful validation, the flow run resumes, and the return value of the <code>pause_flow_run</code> or <code>suspend_flow_run</code> is an instance of the model containing the provided data.</p> <p>Here is an example of a flow that pauses and waits for input from a user:</p> <pre><code>from prefect import flow, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass UserNameInput(RunInput):\n    name: str\n\n\n@flow(log_prints=True)\nasync def greet_user():\n    user_input = await pause_flow_run(\n        wait_for_input=UserNameInput\n    )\n\n    print(f\"Hello, {user_input.name}!\")\n</code></pre> <p>Running this flow will create a flow run. The flow run will advance until code execution reaches <code>pause_flow_run</code>, at which point it will move into a <code>Paused</code> state. Execution will block and wait for resumption.</p> <p>When resuming the flow run, users will be prompted to provide a value for the <code>name</code> field of the <code>UserNameInput</code> model. Upon successful validation, the flow run will resume, and the return value of the <code>pause_flow_run</code> will be an instance of the <code>UserNameInput</code> model containing the provided data.</p> <p>For more in-depth information on receiving input from users when pausing and suspending flow runs, see the Creating interactive workflows guide.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#canceling-a-flow-run","title":"Canceling a flow run","text":"<p>You may cancel a scheduled or in-progress flow run from the CLI, UI, REST API, or Python client.</p> <p>When cancellation is requested, the flow run is moved to a \"Cancelling\" state. If the deployment is a work pool-based deployemnt with a worker, then the worker monitors the state of flow runs and detects that cancellation has been requested. The worker then sends a signal to the flow run infrastructure, requesting termination of the run. If the run does not terminate after a grace period (default of 30 seconds), the infrastructure will be killed, ensuring the flow run exits.</p> <p>A deployment is required</p> <p>Flow run cancellation requires the flow run to be associated with a deployment. A monitoring process must be running to enforce the cancellation. Inline subflow runs, i.e. those created without <code>run_deployment</code>, cannot be cancelled without cancelling the parent flow run. If you may need to cancel a subflow run independent of its parent flow run, we recommend deploying it separately and starting it using the run_deployment function.</p> <p>Cancellation is robust to restarts of Prefect workers. To enable this, we attach metadata about the created infrastructure to the flow run. Internally, this is referred to as the <code>infrastructure_pid</code> or infrastructure identifier. Generally, this is composed of two parts:</p> <ol> <li>Scope: identifying where the infrastructure is running.</li> <li>ID: a unique identifier for the infrastructure within the scope.</li> </ol> <p>The scope is used to ensure that Prefect does not kill the wrong infrastructure. For example, workers running on multiple machines may have overlapping process IDs but should not have a matching scope.</p> <p>The identifiers for infrastructure types:</p> <ul> <li>Processes: The machine hostname and the PID.</li> <li>Docker Containers: The Docker API URL and container ID.</li> <li>Kubernetes Jobs: The Kubernetes cluster name and the job name.</li> </ul> <p>While the cancellation process is robust, there are a few issues than can occur:</p> <ul> <li>If the infrastructure block for the flow run has been removed or altered, cancellation may not work.</li> <li>If the infrastructure block for the flow run does not have support for cancellation, cancellation will not work.</li> <li>If the identifier scope does not match when attempting to cancel a flow run the worker will be unable to cancel the flow run. Another worker may attempt cancellation.</li> <li>If the infrastructure associated with the run cannot be found or has already been killed, the worker will mark the flow run as cancelled.</li> <li>If the <code>infrastructre_pid</code> is missing from the flow run will be marked as cancelled but cancellation cannot be enforced.</li> <li>If the worker runs into an unexpected error during cancellation the flow run may or may not be cancelled depending on where the error occurred. The worker will try again to cancel the flow run. Another worker may attempt cancellation.</li> </ul> <p>Enhanced cancellation</p> <p>We are working on improving cases where cancellation can fail. You can try the improved cancellation experience by enabling the <code>PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION</code> setting on your worker or agents:</p> <p> <pre><code>prefect config set PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION=True\n</code></pre> </p> <p>If you encounter any issues, please let us know in Slack or with a Github issue.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#cancel-via-the-cli","title":"Cancel via the CLI","text":"<p>From the command line in your execution environment, you can cancel a flow run by using the <code>prefect flow-run cancel</code> CLI command, passing the ID of the flow run.</p> <pre><code>prefect flow-run cancel 'a55a4804-9e3c-4042-8b59-b3b6b7618736'\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#cancel-via-the-ui","title":"Cancel via the UI","text":"<p>From the UI you can cancel a flow run by navigating to the flow run's detail page and clicking the <code>Cancel</code> button in the upper right corner.</p> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#timeouts","title":"Timeouts","text":"<p>Flow timeouts are used to prevent unintentional long-running flows. When the duration of execution for a flow exceeds the duration specified in the timeout, a timeout exception will be raised and the flow will be marked as failed. In the UI, the flow will be visibly designated as <code>TimedOut</code>.</p> <p>Timeout durations are specified using the <code>timeout_seconds</code> keyword argument.</p> <pre><code>from prefect import flow\nimport time\n\n@flow(timeout_seconds=1, log_prints=True)\ndef show_timeouts():\n    print(\"I will execute\")\n    time.sleep(5)\n    print(\"I will not execute\")\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/infrastructure/","title":"Infrastructure","text":"<p>Workers are recommended</p> <p>Infrastructure blocks are part of the agent based deployment model. Work Pools and Workers simplify the specification of each flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p> <p>Users may specify an infrastructure block when creating a deployment. This block will be used to specify infrastructure for flow runs created by the deployment at runtime.</p> <p>Infrastructure can only be used with a deployment. When you run a flow directly by calling the flow yourself, you are responsible for the environment in which the flow executes.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#infrastructure-overview","title":"Infrastructure overview","text":"<p>Prefect uses infrastructure to create the environment for a user's flow to execute.</p> <p>Infrastructure is attached to a deployment and is propagated to flow runs created for that deployment. Infrastructure is deserialized by the agent and it has two jobs:</p> <ul> <li>Create execution environment infrastructure for the flow run.</li> <li>Run a Python command to start the <code>prefect.engine</code> in the infrastructure, which retrieves the flow from storage and executes the flow.</li> </ul> <p>The engine acquires and calls the flow. Infrastructure doesn't know anything about how the flow is stored, it's just passing a flow run ID to the engine.</p> <p>Infrastructure is specific to the environments in which flows will run. Prefect currently provides the following infrastructure types:</p> <ul> <li><code>Process</code> runs flows in a local subprocess.</li> <li><code>DockerContainer</code> runs flows in a Docker container.</li> <li><code>KubernetesJob</code> runs flows in a Kubernetes Job.</li> <li><code>ECSTask</code> runs flows in an Amazon ECS Task.</li> <li><code>Cloud Run</code> runs flows in a Google Cloud Run Job.</li> <li><code>Container Instance</code> runs flows in an Azure Container Instance.</li> </ul> <p>What about tasks?</p> <p>Flows and tasks can both use configuration objects to manage the environment in which code runs.</p> <p>Flows use infrastructure.</p> <p>Tasks use task runners. For more on how task runners work, see Task Runners.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#using-infrastructure","title":"Using infrastructure","text":"<p>You may create customized infrastructure blocks through the Prefect UI or Prefect Cloud Blocks page or create them in code and save them to the API using the blocks <code>.save()</code> method.</p> <p>Once created, there are two distinct ways to use infrastructure in a deployment:</p> <ul> <li>Starting with Prefect defaults \u2014 this is what happens when you pass  the <code>-i</code> or <code>--infra</code> flag and provide a type when building deployment files.</li> <li>Pre-configure infrastructure settings as blocks and base your deployment infrastructure on those settings \u2014 by passing <code>-ib</code> or <code>--infra-block</code> and a block slug when building deployment files.</li> </ul> <p>For example, when creating your deployment files, the supported Prefect infrastrucure types are:</p> <ul> <li><code>process</code></li> <li><code>docker-container</code></li> <li><code>kubernetes-job</code></li> <li><code>ecs-task</code></li> <li><code>cloud-run-job</code></li> <li><code>container-instance-job</code></li> </ul> <pre><code>$ prefect deployment build ./my_flow.py:my_flow -n my-flow-deployment -t test -i docker-container -sb s3/my-bucket --override env.EXTRA_PIP_PACKAGES=s3fs\nFound flow 'my-flow'\nSuccessfully uploaded 2 files to s3://bucket-full-of-sunshine\nDeployment YAML created at '/Users/terry/test/flows/infra/deployment.yaml'.\n</code></pre> <p>In this example we specify the <code>DockerContainer</code> infrastructure in addition to a preconfigured AWS S3 bucket storage block.</p> <p>The default deployment YAML filename may be edited as needed to add an infrastructure type or infrastructure settings.</p> <pre><code>###\n### A complete description of a Prefect Deployment for flow 'my-flow'\n###\nname: my-flow-deployment\ndescription: null\nversion: e29de5d01b06d61b4e321d40f34a480c\n# The work queue that will handle this deployment's runs\nwork_queue_name: default\nwork_pool_name: default-agent-pool\ntags:\n- test\nparameters: {}\nschedules: []\npaused: true\ninfra_overrides:\n  env.EXTRA_PIP_PACKAGES: s3fs\ninfrastructure:\n  type: docker-container\n  env: {}\n  labels: {}\n  name: null\n  command:\n  - python\n  - -m\n  - prefect.engine\n  image: prefecthq/prefect:2-latest\n  image_pull_policy: null\n  networks: []\n  network_mode: null\n  auto_remove: false\n  volumes: []\n  stream_output: true\n  memswap_limit: null\n  mem_limit: null\n  privileged: false\n  block_type_slug: docker-container\n  _block_type_slug: docker-container\n\n###\n### DO NOT EDIT BELOW THIS LINE\n###\nflow_name: my-flow\nmanifest_path: my_flow-manifest.json\nstorage:\n  bucket_path: bucket-full-of-sunshine\n  aws_access_key_id: '**********'\n  aws_secret_access_key: '**********'\n  _is_anonymous: true\n  _block_document_name: anonymous-xxxxxxxx-f1ff-4265-b55c-6353a6d65333\n  _block_document_id: xxxxxxxx-06c2-4c3c-a505-4a8db0147011\n  block_type_slug: s3\n  _block_type_slug: s3\npath: ''\nentrypoint: my_flow.py:my-flow\nparameter_openapi_schema:\n  title: Parameters\n  type: object\n  properties: {}\n  required: null\n  definitions: null\ntimestamp: '2023-02-08T23:00:14.974642+00:00'\n</code></pre> <p>Editing deployment YAML</p> <p>Note the big DO NOT EDIT comment in the deployment YAML: In practice, anything above this block can be freely edited before running <code>prefect deployment apply</code> to create the deployment on the API.</p> <p>Once the deployment exists, any flow runs that this deployment starts will use <code>DockerContainer</code> infrastructure.</p> <p>You can also create custom infrastructure blocks \u2014 either in the Prefect UI for in code via the API \u2014 and use the settings in the block to configure your infastructure. For example, here we specify settings for Kubernetes infrastructure in a block named <code>k8sdev</code>.</p> <pre><code>from prefect.infrastructure import KubernetesJob, KubernetesImagePullPolicy\n\nk8s_job = KubernetesJob(\n    namespace=\"dev\",\n    image=\"prefecthq/prefect:2.0.0-python3.9\",\n    image_pull_policy=KubernetesImagePullPolicy.IF_NOT_PRESENT,\n)\nk8s_job.save(\"k8sdev\")\n</code></pre> <p>Now we can apply the infrastrucure type and settings in the block by specifying the block slug <code>kubernetes-job/k8sdev</code> as the infrastructure type when building a deployment:</p> <pre><code>prefect deployment build flows/k8s_example.py:k8s_flow --name k8sdev --tag k8s -sb s3/dev -ib kubernetes-job/k8sdev\n</code></pre> <p>See Deployments for more information about deployment build options.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#configuring-infrastructure","title":"Configuring infrastructure","text":"<p>Every infrastrcture type has type-specific options.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#process","title":"Process","text":"<p><code>Process</code> infrastructure runs a command in a new process.</p> <p>Current environment variables and Prefect settings will be included in the created process. Configured environment variables will override any current environment variables.</p> <p><code>Process</code> supports the following settings:</p> Attributes Description command A list of strings specifying the command to start the flow run. In most cases you should not override this. env Environment variables to set for the new process. labels Labels for the process. Labels are for metadata purposes only and cannot be attached to the process itself. name A name for the process. For display purposes only.","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#dockercontainer","title":"DockerContainer","text":"<p><code>DockerContainer</code> infrastructure  executes flow runs in a container.</p> <p>Requirements for <code>DockerContainer</code>:</p> <ul> <li>Docker Engine must be available.</li> <li>You must configure remote Storage. Local storage is not supported for Docker.</li> <li>The API must be available from within the flow run container. To facilitate connections to locally hosted APIs, <code>localhost</code> and <code>127.0.0.1</code> will be replaced with <code>host.docker.internal</code>.</li> <li>The ephemeral Prefect API won't work with Docker and Kubernetes. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> </ul> <p><code>DockerContainer</code> supports the following settings:</p> Attributes Description auto_remove Bool indicating whether the container will be removed on completion. If False, the container will remain after exit for inspection. command A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this. env Environment variables to set for the container. image An optional string specifying the name of a Docker image to use. Defaults to the Prefect image. If the image is stored anywhere other than a public Docker Hub registry, use a corresponding registry block, e.g. <code>DockerRegistry</code> or ensure otherwise that your execution layer is authenticated to pull the image from the image registry. image_pull_policy Specifies if the image should be pulled. One of 'ALWAYS', 'NEVER', 'IF_NOT_PRESENT'. image_registry A <code>DockerRegistry</code> block containing credentials to use if <code>image</code> is stored in a private image registry. labels An optional dictionary of labels, mapping name to value. name An optional name for the container. networks An optional list of strings specifying Docker networks to connect the container to. network_mode Set the network mode for the created container. Defaults to 'host' if a local API url is detected, otherwise the Docker default of 'bridge' is used. If 'networks' is set, this cannot be set. stream_output Bool indicating whether to stream output from the subprocess to local standard output. volumes An optional list of volume mount strings in the format of \"local_path:container_path\". <p>Prefect automatically sets a Docker image matching the Python and Prefect version you're using at deployment time. You can see all available images at Docker Hub.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#kubernetesjob","title":"KubernetesJob","text":"<p><code>KubernetesJob</code> infrastructure executes flow runs in a Kubernetes Job.</p> <p>Requirements for <code>KubernetesJob</code>:</p> <ul> <li><code>kubectl</code> must be available.</li> <li>You must configure remote Storage. Local storage is not supported for Kubernetes.</li> <li>The ephemeral Prefect API won't work with Docker and Kubernetes. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> </ul> <p>The Prefect CLI command <code>prefect kubernetes manifest server</code> automatically generates a Kubernetes manifest with default settings for Prefect deployments. By default, it simply prints out the YAML configuration for a manifest. You can pipe this output to a file of your choice and edit as necessary.</p> <p><code>KubernetesJob</code> supports the following settings:</p> Attributes Description cluster_config An optional Kubernetes cluster config to use for this job. command A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this. customizations A list of JSON 6902 patches to apply to the base Job manifest. Alternatively, a valid JSON string is allowed (handy for deployments CLI). env Environment variables to set for the container. finished_job_ttl The number of seconds to retain jobs after completion. If set, finished jobs will be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be manually removed. image String specifying the tag of a Docker image to use for the Job. image_pull_policy The Kubernetes image pull policy to use for job containers. job The base manifest for the Kubernetes Job. job_watch_timeout_seconds Number of seconds to watch for job creation before timing out (defaults to None). labels Dictionary of labels to add to the Job. name An optional name for the job. namespace String signifying the Kubernetes namespace to use. pod_watch_timeout_seconds Number of seconds to watch for pod creation before timing out (default 60). service_account_name An optional string specifying which Kubernetes service account to use. stream_output Bool indicating whether to stream output from the subprocess to local standard output.","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#kubernetesjob-overrides-and-customizations","title":"KubernetesJob overrides and customizations","text":"<p>When creating deployments using <code>KubernetesJob</code> infrastructure, the <code>infra_overrides</code> parameter expects a dictionary. For a <code>KubernetesJob</code>, the <code>customizations</code> parameter expects a list.</p> <p>Containers expect a list of objects, even if there is only one. For any patches applying to the container, the path value should be a list, for example:   <code>/spec/templates/spec/containers/0/resources</code></p> <p>A <code>Kubernetes-Job</code> infrastructure block defined in Python:</p> <pre><code>customizations = [\n {\n     \"op\": \"add\",\n     \"path\": \"/spec/template/spec/containers/0/resources\",\n     \"value\": {\n         \"requests\": {\n             \"cpu\": \"2000m\",\n             \"memory\": \"4gi\"\n         },\n         \"limits\": {\n             \"cpu\": \"4000m\",\n             \"memory\": \"8Gi\",\n             \"nvidia.com/gpu\": \"1\"\n      }\n  },\n }\n]\n\nk8s_job = KubernetesJob(\n        namespace=namespace,\n        image=image_name,\n        image_pull_policy=KubernetesImagePullPolicy.ALWAYS,\n        finished_job_ttl=300,\n        job_watch_timeout_seconds=600,\n        pod_watch_timeout_seconds=600,\n        service_account_name=\"prefect-server\",\n        customizations=customizations,\n    )\nk8s_job.save(\"devk8s\")\n</code></pre> <p>A <code>Deployment</code> with infra-overrides defined in Python:</p> <pre><code>infra_overrides={ \n    \"customizations\": [\n            {\n                \"op\": \"add\",\n                \"path\": \"/spec/template/spec/containers/0/resources\",\n                \"value\": {\n                    \"requests\": {\n                        \"cpu\": \"2000m\",\n                        \"memory\": \"4gi\"\n                    },\n                    \"limits\": {\n                        \"cpu\": \"4000m\",\n                        \"memory\": \"8Gi\",\n                        \"nvidia.com/gpu\": \"1\"\n                }\n            },\n        }\n    ]\n}\n\n# Load an already created K8s Block\nk8sjob = k8s_job.load(\"devk8s\")\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"s3-example\",\n    version=2,\n    work_queue_name=\"aws\",\n    infrastructure=k8sjob,\n    storage=storage,\n    infra_overrides=infra_overrides,\n)\n\ndeployment.apply()\n</code></pre>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#ecstask","title":"ECSTask","text":"<p><code>ECSTask</code> infrastructure runs your flow in an ECS Task.</p> <p>Requirements for <code>ECSTask</code>:</p> <ul> <li>The ephemeral Prefect API won't work with ECS directly. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> <li>The <code>prefect-aws</code> collection must be installed within the agent environment: <code>pip install prefect-aws</code></li> <li>The <code>ECSTask</code> and <code>AwsCredentials</code> blocks must be registered within the agent environment: <code>prefect block register -m prefect_aws.ecs</code></li> <li>You must configure remote Storage. Local storage is not supported for ECS tasks. The most commonly used type of storage with <code>ECSTask</code> is S3. If you leverage that type of block, make sure that <code>s3fs</code> is installed within your agent and flow run environment. The easiest way to satisfy all the installation-related points mentioned above is to include the following commands in your Dockerfile:  </li> </ul> <pre><code>FROM prefecthq/prefect:2-python3.9  # example base image \nRUN pip install s3fs prefect-aws\n</code></pre> <p>Make sure to allocate enough CPU and memory to your agent, and consider adding retries</p> <p>When you start a Prefect agent on AWS ECS Fargate, allocate as much CPU and memory as needed for your workloads. Your agent needs enough resources to appropriately provision infrastructure for your flow runs and to monitor their execution. Otherwise, your flow runs may get stuck in a <code>Pending</code> state. Alternatively, set a work-queue concurrency limit to ensure that the agent will not try to process all runs at the same time.</p> <p>Some API calls to provision infrastructure may fail due to unexpected issues on the client side (for example, transient errors such as <code>ConnectionError</code>, <code>HTTPClientError</code>, or <code>RequestTimeout</code>), or due to server-side rate limiting from the AWS service. To mitigate those issues, we recommend adding environment variables such as <code>AWS_MAX_ATTEMPTS</code> (can be set to an integer value such as 10) and <code>AWS_RETRY_MODE</code> (can be set to a string value including <code>standard</code> or <code>adaptive</code> modes). Those environment variables must be added within the agent environment, e.g. on your ECS service running the agent, rather than on the <code>ECSTask</code> infrastructure block. </p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#docker-images","title":"Docker images","text":"<p>Learn about options for Prefect-maintained Docker images in the Docker guide.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/results/","title":"Results","text":"<p>Results represent the data returned by a flow or a task.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#retrieving-results","title":"Retrieving results","text":"<p>When calling flows or tasks, the result is returned directly:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    task_result = my_task()\n    return task_result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>When working with flow and task states, the result can be retrieved with the <code>State.result()</code> method:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n    return state.result() + 1\n\nstate = my_flow(return_state=True)\nassert state.result() == 2\n</code></pre> <p>When submitting tasks to a runner, the result can be retrieved with the <code>Future.result()</code> method:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    return future.result() + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#handling-failures","title":"Handling failures","text":"<p>Sometimes your flows or tasks will encounter an exception. Prefect captures all exceptions in order to report states to the orchestrator, but we do not hide them from you (unless you ask us to) as your program needs to know if an unexpected error has occurred.</p> <p>When calling flows or tasks, the exceptions are raised as in normal Python:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    try:\n        my_task()\n    except ValueError:\n        print(\"Oh no! The task failed.\")\n\n    return True\n\nmy_flow()\n</code></pre> <p>If you would prefer to check for a failed task without using <code>try/except</code>, you may ask Prefect to return the state:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    if state.is_failed():\n        print(\"Oh no! The task failed. Falling back to '1'.\")\n        result = 1\n    else:\n        result = state.result()\n\n    return result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>If you retrieve the result from a failed state, the exception will be raised. For this reason, it's often best to check if the state is failed first.</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    try:\n        result = state.result()\n    except ValueError:\n        print(\"Oh no! The state raised the error!\")\n\n    return True\n\nmy_flow()\n</code></pre> <p>When retrieving the result from a state, you can ask Prefect not to raise exceptions:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    maybe_result = state.result(raise_on_failure=False)\n    if isinstance(maybe_result, ValueError):\n        print(\"Oh no! The task failed. Falling back to '1'.\")\n        result = 1\n    else:\n        result = maybe_result\n\n    return result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>When submitting tasks to a runner, <code>Future.result()</code> works the same as <code>State.result()</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n\n    try:\n        future.result()\n    except ValueError:\n        print(\"Ah! Futures will raise the failure as well.\")\n\n    # You can ask it not to raise the exception too\n    maybe_result = future.result(raise_on_failure=False)\n    print(f\"Got {type(maybe_result)}\")\n\n    return True\n\nmy_flow()\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#working-with-async-results","title":"Working with async results","text":"<p>When calling flows or tasks, the result is returned directly:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    task_result = await my_task()\n    return task_result + 1\n\nresult = asyncio.run(my_flow())\nassert result == 2\n</code></pre> <p>When working with flow and task states, the result can be retrieved with the <code>State.result()</code> method:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    state = await my_task(return_state=True)\n    result = await state.result(fetch=True)\n    return result + 1\n\nasync def main():\n    state = await my_flow(return_state=True)\n    assert await state.result(fetch=True) == 2\n\nasyncio.run(main())\n</code></pre> <p>Resolving results</p> <p>Prefect 2.6.0 added automatic retrieval of persisted results. Prior to this version, <code>State.result()</code> did not require an <code>await</code>. For backwards compatibility, when used from an asynchronous context, <code>State.result()</code> returns a raw result type.</p> <p>You may opt-in to the new behavior by passing <code>fetch=True</code> as shown in the example above. If you would like this behavior to be used automatically, you may enable the <code>PREFECT_ASYNC_FETCH_STATE_RESULT</code> setting. If you do not opt-in to this behavior, you will see a warning.</p> <p>You may also opt-out by setting <code>fetch=False</code>. This will silence the warning, but you will need to retrieve your result manually from the result type.</p> <p>When submitting tasks to a runner, the result can be retrieved with the <code>Future.result()</code> method:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    future = await my_task.submit()\n    result = await future.result()\n    return result + 1\n\nresult = asyncio.run(my_flow())\nassert result == 2\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisting-results","title":"Persisting results","text":"<p>The Prefect API does not store your results except in special cases. Instead, the result is persisted to a storage location in your infrastructure and Prefect stores a reference to the result.</p> <p>The following Prefect features require results to be persisted:</p> <ul> <li>Task cache keys</li> <li>Flow run retries</li> </ul> <p>If results are not persisted, these features may not be usable.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#configuring-persistence-of-results","title":"Configuring persistence of results","text":"<p>Persistence of results requires a serializer and a storage location. Prefect sets defaults for these, and you should not need to adjust them until you want to customize behavior. You can configure results on the <code>flow</code> and <code>task</code> decorators with the following options:</p> <ul> <li><code>persist_result</code>: Whether the result should be persisted to storage.</li> <li><code>result_storage</code>: Where to store the result when persisted.</li> <li><code>result_serializer</code>: How to convert the result to a storable form.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#toggling-persistence","title":"Toggling persistence","text":"<p>Persistence of the result of a task or flow can be configured with the <code>persist_result</code> option. The <code>persist_result</code> option defaults to a null value, which will automatically enable persistence if it is needed for a Prefect feature used by the flow or task. Otherwise, persistence is disabled by default.</p> <p>For example, the following flow has retries enabled. Flow retries require that all task results are persisted, so the task's result will be persisted:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return \"hello world!\"\n\n@flow(retries=2)\ndef my_flow():\n    # This task does not have persistence toggled off and it is needed for the flow feature,\n    # so Prefect will persist its result at runtime\n    my_task()\n</code></pre> <p>Flow retries do not require the flow's result to be persisted, so it will not be.</p> <p>In this next example, one task has caching enabled. Task caching requires that the given task's result is persisted:</p> <pre><code>from prefect import flow, task\nfrom datetime import timedelta\n\n@task(cache_key_fn=lambda: \"always\", cache_expiration=timedelta(seconds=20))\ndef my_task():\n    # This task uses caching so its result will be persisted by default\n    return \"hello world!\"\n\n\n@task\ndef my_other_task():\n    ...\n\n@flow\ndef my_flow():\n    # This task uses a feature that requires result persistence\n    my_task()\n\n    # This task does not use a feature that requires result persistence and the\n    # flow does not use any features that require task result persistence so its\n    # result will not be persisted by default\n    my_other_task()\n</code></pre> <p>Persistence of results can be manually toggled on or off:</p> <pre><code>from prefect import flow, task\n\n@flow(persist_result=True)\ndef my_flow():\n    # This flow will persist its result even if not necessary for a feature.\n    ...\n\n@task(persist_result=False)\ndef my_task():\n    # This task will never persist its result.\n    # If persistence needed for a feature, an error will be raised.\n    ...\n</code></pre> <p>Toggling persistence manually will always override any behavior that Prefect would infer.</p> <p>You may also change Prefect's default persistence behavior with the <code>PREFECT_RESULTS_PERSIST_BY_DEFAULT</code> setting. To persist results by default, even if they are not needed for a feature change the value to a truthy value:</p> <pre><code>prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true\n</code></pre> <p>Task and flows with <code>persist_result=False</code> will not persist their results even if <code>PREFECT_RESULTS_PERSIST_BY_DEFAULT</code> is <code>true</code>.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-location","title":"Result storage location","text":"<p>The result storage location can be configured with the <code>result_storage</code> option. The <code>result_storage</code> option defaults to a null value, which infers storage from the context. Generally, this means that tasks will use the result storage configured on the flow unless otherwise specified. If there is no context to load the storage from and results must be persisted, results will be stored in the path specified by the <code>PREFECT_LOCAL_STORAGE_PATH</code> setting (defaults to <code>~/.prefect/storage</code>).</p> <pre><code>from prefect import flow, task\nfrom prefect.filesystems import LocalFileSystem, S3\n\n@flow(persist_result=True)\ndef my_flow():\n    my_task()  # This task will use the flow's result storage\n\n@task(persist_result=True)\ndef my_task():\n    ...\n\nmy_flow()  # The flow has no result storage configured and no parent, the local file system will be used.\n\n\n# Reconfigure the flow to use a different storage type\nnew_flow = my_flow.with_options(result_storage=S3(bucket_path=\"my-bucket\"))\n\nnew_flow()  # The flow and task within it will use S3 for result storage.\n</code></pre> <p>You can configure this to use a specific storage using one of the following:</p> <ul> <li>A storage instance, e.g. <code>LocalFileSystem(basepath=\".my-results\")</code></li> <li>A storage slug, e.g. <code>'s3/dev-s3-block'</code></li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-key","title":"Result storage key","text":"<p>The path of the result file in the result storage can be configured with the <code>result_storage_key</code>. The <code>result_storage_key</code> option defaults to a null value, which generates a unique identifier for each result.</p> <pre><code>from prefect import flow, task\nfrom prefect.filesystems import LocalFileSystem, S3\n\n@flow(result_storage=S3(bucket_path=\"my-bucket\"))\ndef my_flow():\n    my_task()\n\n@task(persist_result=True, result_storage_key=\"my_task.json\")\ndef my_task():\n    ...\n\nmy_flow()  # The task's result will be persisted to 's3://my-bucket/my_task.json'\n</code></pre> <p>Result storage keys are formatted with access to all of the modules in <code>prefect.runtime</code> and the run's <code>parameters</code>. In the following example, we will run a flow with three runs of the same task. Each task run will write its result to a unique file based on the <code>name</code> parameter.</p> <pre><code>from prefect import flow, task\n\n@flow()\ndef my_flow():\n    hello_world()\n    hello_world(name=\"foo\")\n    hello_world(name=\"bar\")\n\n@task(persist_result=True, result_storage_key=\"hello-{parameters[name]}.json\")\ndef hello_world(name: str = \"world\"):\n    return f\"hello {name}\"\n\nmy_flow()\n</code></pre> <p>After running the flow, we can see three persisted result files in our storage directory:</p> <pre><code>$ ls ~/.prefect/storage | grep \"hello-\"\nhello-bar.json\nhello-foo.json\nhello-world.json\n</code></pre> <p>In the next example, we include metadata about the flow run from the <code>prefect.runtime.flow_run</code> module:</p> <pre><code>from prefect import flow, task\n\n@flow\ndef my_flow():\n    hello_world()\n\n@task(persist_result=True, result_storage_key=\"{flow_run.flow_name}_{flow_run.name}_hello.json\")\ndef hello_world(name: str = \"world\"):\n    return f\"hello {name}\"\n\nmy_flow()\n</code></pre> <p>After running this flow, we can see a result file templated with the name of the flow and the flow run:</p> <pre><code>\u276f ls ~/.prefect/storage | grep \"my-flow\"    \nmy-flow_industrious-trout_hello.json\n</code></pre> <p>If a result exists at a given storage key in the storage location, it will be overwritten.</p> <p>Result storage keys can only be configured on tasks at this time.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-serializer","title":"Result serializer","text":"<p>The result serializer can be configured with the <code>result_serializer</code> option. The <code>result_serializer</code> option defaults to a null value, which infers the serializer from the context. Generally, this means that tasks will use the result serializer configured on the flow unless otherwise specified. If there is no context to load the serializer from, the serializer defined by <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used. This setting defaults to Prefect's pickle serializer.</p> <p>You may configure the result serializer using:</p> <ul> <li>A type name, e.g. <code>\"json\"</code> or <code>\"pickle\"</code> \u2014 this corresponds to an instance with default values</li> <li>An instance, e.g. <code>JSONSerializer(jsonlib=\"orjson\")</code></li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#compressing-results","title":"Compressing results","text":"<p>Prefect provides a <code>CompressedSerializer</code> which can be used to wrap other serializers to provide compression over the bytes they generate. The compressed serializer uses <code>lzma</code> compression by default. We test other compression schemes provided in the Python standard library such as <code>bz2</code> and <code>zlib</code>, but you should be able to use any compression library that provides <code>compress</code> and <code>decompress</code> methods.</p> <p>You may configure compression of results using:</p> <ul> <li>A type name, prefixed with <code>compressed/</code> e.g. <code>\"compressed/json\"</code> or <code>\"compressed/pickle\"</code></li> <li>An instance e.g. <code>CompressedSerializer(serializer=\"pickle\", compressionlib=\"lzma\")</code></li> </ul> <p>Note that the <code>\"compressed/&lt;serializer-type&gt;\"</code> shortcut will only work for serializers provided by Prefect. If you are using custom serializers, you must pass a full instance.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#storage-of-results-in-prefect","title":"Storage of results in Prefect","text":"<p>The Prefect API does not store your results in most cases for the following reasons:</p> <ul> <li>Results can be large and slow to send to and from the API.</li> <li>Results often contain private information or data.</li> <li>Results would need to be stored in the database or complex logic implemented to hydrate from another source.</li> </ul> <p>There are a few cases where Prefect will store your results directly in the database. This is an optimization to reduce the overhead of reading and writing to result storage.</p> <p>The following data types will be stored by the API without persistence to storage:</p> <ul> <li>booleans (<code>True</code>, <code>False</code>)</li> <li>nulls (<code>None</code>)</li> </ul> <p>If <code>persist_result</code> is set to <code>False</code>, these values will never be stored.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#tracking-results","title":"Tracking results","text":"<p>The Prefect API tracks metadata about your results. The value of your result is only stored in specific cases. Result metadata can be seen in the UI on the \"Results\" page for flows.</p> <p>Prefect tracks the following result metadata:</p> <ul> <li>Data type</li> <li>Storage location (if persisted)</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#caching-of-results-in-memory","title":"Caching of results in memory","text":"<p>When running your workflows, Prefect will keep the results of all tasks and flows in memory so they can be passed downstream. In some cases, it is desirable to override this behavior. For example, if you are returning a large amount of data from a task it can be costly to keep it memory for the entire duration of the flow run.</p> <p>Flows and tasks both include an option to drop the result from memory with <code>cache_result_in_memory</code>:</p> <pre><code>@flow(cache_result_in_memory=False)\ndef foo():\n    return \"pretend this is large data\"\n\n@task(cache_result_in_memory=False)\ndef bar():\n    return \"pretend this is biiiig data\"\n</code></pre> <p>When <code>cache_result_in_memory</code> is disabled, the result of your flow or task will be persisted by default. The result will then be pulled from storage when needed.</p> <pre><code>@flow\ndef foo():\n    result = bar()\n    state = bar(return_state=True)\n\n    # The result will be retrieved from storage here\n    state.result()\n\n    future = bar.submit()\n    # The result will be retrieved from storage here\n    future.result()\n\n@task(cache_result_in_memory=False)\ndef bar():\n    # This result will persisted\n    return \"pretend this is biiiig data\"\n</code></pre> <p>If both <code>cache_result_in_memory</code> and persistence are disabled, your results will not be available downstream.</p> <pre><code>@task(persist_result=False, cache_result_in_memory=False)\ndef bar():\n    return \"pretend this is biiiig data\"\n\n@flow\ndef foo():\n    # Raises an error\n    result = bar()\n\n    # This is oaky\n    state = bar(return_state=True)\n\n    # Raises an error\n    state.result()\n\n    # This is okay\n    future = bar.submit()\n\n    # Raises an error\n    future.result()\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-types","title":"Result storage types","text":"<p>Result storage is responsible for reading and writing serialized data to an external location. At this time, any file system block can be used for result storage.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-serializer-types","title":"Result serializer types","text":"<p>A result serializer is responsible for converting your Python object to and from bytes. This is necessary to store the object outside of Python and retrieve it later.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#pickle-serializer","title":"Pickle serializer","text":"<p>Pickle is a standard Python protocol for encoding arbitrary Python objects. We supply a custom pickle serializer at <code>prefect.serializers.PickleSerializer</code>. Prefect's pickle serializer uses the cloudpickle project by default to support more object types. Alternative pickle libraries can be specified:</p> <pre><code>from prefect.serializers import PickleSerializer\n\nPickleSerializer(picklelib=\"custompickle\")\n</code></pre> <p>Benefits of the pickle serializer:</p> <ul> <li>Many object types are supported.</li> <li>Objects can define custom pickle support.</li> </ul> <p>Drawbacks of the pickle serializer:</p> <ul> <li>When nested attributes of an object cannot be pickled, it is hard to determine the cause.</li> <li>When deserializing objects, your Python and pickle library versions must match the one used at serialization time.</li> <li>Serialized objects cannot be easily shared across different programming languages.</li> <li>Serialized objects are not human readable.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#json-serializer","title":"JSON serializer","text":"<p>We supply a custom JSON serializer at <code>prefect.serializers.JSONSerializer</code>. Prefect's JSON serializer uses custom hooks by default to support more object types. Specifically, we add support for all types supported by Pydantic.</p> <p>By default, we use the standard Python <code>json</code> library. Alternative JSON libraries can be specified:</p> <pre><code>from prefect.serializers import JSONSerializer\n\nJSONSerializer(jsonlib=\"orjson\")\n</code></pre> <p>Benefits of the JSON serializer:</p> <ul> <li>Serialized objects are human readable.</li> <li>Serialized objects can often be shared across different programming languages.</li> <li>Deserialization of serialized objects is generally version agnostic.</li> </ul> <p>Drawbacks of the JSON serializer:</p> <ul> <li>Supported types are limited.</li> <li>Implementing support for additional types must be done at the serializer level.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-types","title":"Result types","text":"<p>Prefect uses internal result types to capture information about the result attached to a state. The following types are used:</p> <ul> <li><code>UnpersistedResult</code>: Stores result metadata but the value is only available when created.</li> <li><code>LiteralResult</code>: Stores simple values inline.</li> <li><code>PersistedResult</code>: Stores a reference to a result persisted to storage.</li> </ul> <p>All result types include a <code>get()</code> method that can be called to return the value of the result. This is done behind the scenes when the <code>result()</code> method is used on states or futures.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#unpersisted-results","title":"Unpersisted results","text":"<p>Unpersisted results are used to represent results that have not been and will not be persisted beyond the current flow run. The value associated with the result is stored in memory, but will not be available later. Result metadata is attached to this object for storage in the API and representation in the UI.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#literal-results","title":"Literal results","text":"<p>Literal results are used to represent results stored in the Prefect database. The values contained by these results must always be JSON serializable.</p> <p>Example:</p> <pre><code>result = LiteralResult(value=None)\nresult.json()\n# {\"type\": \"result\", \"value\": \"null\"}\n</code></pre> <p>Literal results reduce the overhead required to persist simple results.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisted-results","title":"Persisted results","text":"<p>The persisted result type contains all of the information needed to retrieve the result from storage. This includes:</p> <ul> <li>Storage: A reference to the result storage that can be used to read the serialized result.</li> <li>Key: Indicates where this specific result is in storage.</li> </ul> <p>Persisted result types also contain metadata for inspection without retrieving the result:</p> <ul> <li>Serializer type: The name of the result serializer type.</li> </ul> <p>The <code>get()</code> method on result references retrieves the data from storage, deserializes it, and returns the original object. The <code>get()</code> operation will cache the resolved object to reduce the overhead of subsequent calls.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisted-result-blob","title":"Persisted result blob","text":"<p>When results are persisted to storage, they are always written as a JSON document. The schema for this is described by the <code>PersistedResultBlob</code> type. The document contains:</p> <ul> <li>The serialized data of the result.</li> <li>A full description of result serializer that can be used to deserialize the result data.</li> <li>The Prefect version used to create the result.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/schedules/","title":"Schedules","text":"<p>Scheduling is one of the primary reasons for using an orchestrator such as Prefect. Prefect allows you to use schedules to automatically create new flow runs for deployments.</p> <p>Prefect Cloud can also schedule flow runs through event-driven automations.</p> <p>Schedules tell the Prefect API how to create new flow runs for you automatically on a specified cadence.</p> <p>You can add a schedule to any deployment. The Prefect <code>Scheduler</code> service periodically reviews every deployment and creates new flow runs according to the schedule configured for the deployment.</p> <p>Support for multiple schedules</p> <p>We are currently rolling out support for multiple schedules per deployment. You can now assign multiple schedules to deployments in the Prefect UI, the CLI via <code>prefect deployment schedule</code> commands, the <code>Deployment</code> class, and in block-based deployment YAML files.</p> <p>Support for multiple schedules in <code>flow.serve</code>, <code>flow.deploy</code>, <code>serve</code>, and worker-based deployments with <code>prefect deploy</code> will arrive soon.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#schedule-types","title":"Schedule types","text":"<p>Prefect supports several types of schedules that cover a wide range of use cases and offer a large degree of customization:</p> <ul> <li><code>Cron</code> is most appropriate for users who are already familiar with <code>cron</code> from previous use.</li> <li><code>Interval</code> is best suited for deployments that need to run at some consistent cadence that isn't related to absolute time.</li> <li><code>RRule</code> is best suited for deployments that rely on calendar logic for simple recurring schedules, irregular intervals, exclusions, or day-of-month adjustments.</li> </ul> <p>Schedules can be inactive</p> <p>When you create or edit a schedule, you can set the <code>active</code> property to <code>False</code> in Python (or <code>false</code> in a YAML file) to deactivate the schedule. This is useful if you want to keep the schedule configuration but temporarily stop the schedule from creating new flow runs.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#cron","title":"Cron","text":"<p>A schedule may be specified with a <code>cron</code> pattern. Users may also provide a timezone to enforce DST behaviors.</p> <p><code>Cron</code> uses <code>croniter</code> to specify datetime iteration with a <code>cron</code>-like format.</p> <p><code>Cron</code> properties include:</p> Property Description cron A valid <code>cron</code> string. (Required) day_or Boolean indicating how <code>croniter</code> handles <code>day</code> and <code>day_of_week</code> entries. Default is <code>True</code>. timezone String name of a time zone. (See the IANA Time Zone Database for valid time zones.)","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#how-the-day_or-property-works","title":"How the <code>day_or</code> property works","text":"<p>The <code>day_or</code> property defaults to <code>True</code>, matching the behavior of <code>cron</code>. In this mode, if you specify a <code>day</code> (of the month) entry and a <code>day_of_week</code> entry, the schedule will run a flow on both the specified day of the month and on the specified day of the week. The \"or\" in <code>day_or</code> refers to the fact that the two entries are treated like an <code>OR</code> statement, so the schedule should include both, as in the SQL statement <code>SELECT * FROM employees WHERE first_name = 'Xi\u0101ng' OR last_name = 'Brookins';</code>.</p> <p>For example, with <code>day_or</code> set to <code>True</code>, the cron schedule <code>* * 3 1 2</code> runs a flow every minute on the 3rd day of the month (whatever that is) and on Tuesday (the second day of the week) in January (the first month of the year).</p> <p>With <code>day_or</code> set to <code>False</code>, the <code>day</code> (of the month) and <code>day_of_week</code> entries are joined with the more restrictive <code>AND</code> operation, as in the SQL statement <code>SELECT * from employees WHERE first_name = 'Andrew' AND last_name = 'Brookins';</code>. For example, the same schedule, when <code>day_or</code> is <code>False</code>, runs a flow on every minute on the 3rd Tuesday in January. This behavior matches <code>fcron</code> instead of <code>cron</code>.</p> <p>Supported <code>croniter</code> features</p> <p>While Prefect supports most features of <code>croniter</code> for creating <code>cron</code>-like schedules, we do not currently support \"R\" random or \"H\" hashed keyword expressions or the schedule jittering possible with those expressions.</p> <p>Daylight saving time considerations</p> <p>If the <code>timezone</code> is a DST-observing one, then the schedule will adjust itself appropriately.</p> <p>The <code>cron</code> rules for DST are based on schedule times, not intervals. This means that an hourly <code>cron</code> schedule fires on every new schedule hour, not every elapsed hour.  For example, when clocks are set back, this results in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. </p> <p>Longer schedules, such as one that fires at 9am every morning, will adjust for DST automatically.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#interval","title":"Interval","text":"<p>An <code>Interval</code> schedule creates new flow runs on a regular interval measured in seconds. Intervals are computed using an optional <code>anchor_date</code>. For example, here's how you can create a schedule for every 10 minutes in a block-based deployment YAML file:</p> <pre><code>schedule:\n  interval: 600\n  timezone: America/Chicago \n</code></pre> <p><code>Interval</code> properties include:</p> Property Description interval <code>datetime.timedelta</code> indicating the time between flow runs. (Required) anchor_date <code>datetime.datetime</code> indicating the starting or \"anchor\" date to begin the schedule. If no <code>anchor_date</code> is supplied, the current UTC time is used. timezone String name of a time zone, used to enforce localization behaviors like DST boundaries. (See the IANA Time Zone Database for valid time zones.) <p>Note that the <code>anchor_date</code> does not indicate a \"start time\" for the schedule, but rather a fixed point in time from which to compute intervals. If the anchor date is in the future, then schedule dates are computed by subtracting the <code>interval</code> from it. Note that in this example, we import the Pendulum Python package for easy datetime manipulation. Pendulum isn\u2019t required, but it\u2019s a useful tool for specifying dates.</p> <p>Daylight saving time considerations</p> <p>If the schedule's <code>anchor_date</code> or <code>timezone</code> are provided with a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals.</p> <p>For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. </p> <p>For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant.  This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#rrule","title":"RRule","text":"<p>An <code>RRule</code> scheduling supports iCal recurrence rules (RRules), which provide convenient syntax for creating repetitive schedules. Schedules can repeat on a frequency from yearly down to every minute.</p> <p><code>RRule</code> uses the dateutil rrule module to specify iCal recurrence rules.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including simple repetition, irregular intervals, exclusions, week day or day-of-month adjustments, and more. RRules can represent complex logic like:</p> <ul> <li>The last weekday of each month</li> <li>The fourth Thursday of November</li> <li>Every other day of the week</li> </ul> <p><code>RRule</code> properties include:</p> Property Description rrule String representation of an RRule schedule. See the <code>rrulestr</code> examples for syntax. timezone String name of a time zone. See the IANA Time Zone Database for valid time zones. <p>You may find it useful to use an RRule string generator such as the iCalendar.org RRule Tool to help create valid RRules.</p> <p>For example, the following RRule schedule in a block-based deployment YAML file creates flow runs on Monday, Wednesday, and Friday until July 30, 2024.</p> <pre><code>schedule:\n  rrule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20240730T040000Z'\n</code></pre> <p>RRule restrictions</p> <p>Note the max supported character length of an <code>rrulestr</code> is 6500 characters</p> <p>Note that <code>COUNT</code> is not supported. Please use <code>UNTIL</code> or the <code>/deployments/{id}/runs</code> endpoint to schedule a fixed number of flow runs.</p> <p>Daylight saving time considerations</p> <p>Note that as a calendar-oriented standard, <code>RRules</code> are sensitive to the initial timezone provided. A 9am daily schedule with a DST-aware start date will maintain a local 9am time through DST boundaries. A 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules","title":"Creating schedules","text":"<p>There are several ways to create a schedule for a deployment:</p> <ul> <li>Through the Prefect UI</li> <li>Via the <code>cron</code>, <code>interval</code>, or <code>rrule</code> parameters if building your deployment via the <code>serve</code> method of the <code>Flow</code> object or the <code>serve</code> utility for managing multiple flows simultaneously</li> <li>If using worker-based deployments</li> <li>When you define a deployment with <code>flow.serve</code> or <code>flow.deploy</code></li> <li>Through the interactive <code>prefect deploy</code> command</li> <li>With the <code>deployments</code> -&gt; <code>schedules</code> section of the <code>prefect.yaml</code> file</li> <li>If using block-based deployments - Deprecated </li> <li><code>Through the schedules</code> section of the deployment YAML file</li> <li>By passing <code>schedules</code> into the <code>Deployment</code> class or <code>Deployment.build_from_flow</code></li> </ul>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-in-the-ui","title":"Creating schedules in the UI","text":"<p>You can add schedules in the Schedules section on a Deployment page in the UI.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#locating-the-schedules-section","title":"Locating the Schedules section","text":"<p>The Schedules section appears in the sidebar on the right side of the page on wider displays. On narrower displays, it appears on the Details tab of the page.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#adding-a-schedule","title":"Adding a schedule","text":"<p>Under Schedules, select the + Schedule button. A modal dialog will open. Choose Interval or Cron to create a schedule.</p> <p></p> <p>What about RRule?</p> <p>The UI does not support creating RRule schedules. However, the UI will display RRule schedules that you've created via the command line.</p> <p>The new schedule will appear on the Deployment page where you created it. In addition, the schedule will be viewable in human-friendly text in the list of deployments on the Deployments page.</p> <p>After you create a schedule, new scheduled flow runs will be visible in the Upcoming tab of the Deployment page where you created it.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#editing-schedules","title":"Editing schedules","text":"<p>You can edit a schedule by selecting Edit from the three-dot menu next to a schedule on a Deployment page.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-with-a-python-deployment-creation-file","title":"Creating schedules with a Python deployment creation file","text":"<p>When you create a deployment in a Python file with <code>flow.serve()</code>, <code>serve</code>, <code>flow.deploy()</code>, or <code>deploy</code> you can specify the schedule. Just add the keyword argument <code>cron</code>, <code>interval</code>, or <code>rrule</code>.</p> <pre><code>interval: An interval on which to execute the deployment. Accepts a number or a \n    timedelta object to create a single schedule. If a number is given, it will be \n    interpreted as seconds. Also accepts an iterable of numbers or timedelta to create \n    multiple schedules.\ncron: A cron schedule string of when to execute runs of this deployment. \n    Also accepts an iterable of cron schedule strings to create multiple schedules.\nrrule: An rrule schedule string of when to execute runs of this deployment.\n    Also accepts an iterable of rrule schedule strings to create multiple schedules.\nschedules: A list of schedule objects defining when to execute runs of this deployment.\n    Used to define multiple schedules or additional scheduling options such as `timezone`.\nschedule: A schedule object defining when to execute runs of this deployment. Used to\n    define additional scheduling options like `timezone`.\n</code></pre> <p>Here's an example of creating a cron schedule with <code>serve</code> for a deployment flow that will run every minute of every day:</p> <pre><code>my_flow.serve(name=\"flowing\", cron=\"* * * * *\")\n</code></pre> <p>If using work pool-based deployments, the <code>deploy</code> method has the same schedule-based parameters.</p> <p>Here's an example of creating an interval schedule with <code>serve</code> for a deployment flow that will run every 10 minutes with an anchor date and a timezone:</p> <pre><code>from datetime import timedelta, datetime\nfrom prefect.client.schemas.schedules import IntervalSchedule\n\nmy_flow.serve(name=\"flowing\", schedule=IntervalSchedule(interval=timedelta(minutes=10), anchor_date=datetime(2023, 1, 1, 0, 0), timezone=\"America/Chicago\"))\n</code></pre> <p>Block and agent-based deployments with Python files are not a recommended way to create deployments. However, if you are using that deployment creation method you can create a schedule by passing a <code>schedule</code> argument to the <code>Deployment.build_from_flow</code> method.</p> <p>Here's how you create the equivalent schedule in a Python deployment file.</p> <pre><code>from prefect.client.schemas.schedules import CronSchedule\n\ncron_demo = Deployment.build_from_flow(\n    pipeline,\n    \"etl\",\n    schedule=(CronSchedule(cron=\"0 0 * * *\", timezone=\"America/Chicago\"))\n)\n</code></pre>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-with-the-interactive-prefect-deploy-command","title":"Creating schedules with the interactive <code>prefect deploy</code> command","text":"<p>If you are using worker-based deployments, you can create a schedule through the interactive <code>prefect deploy</code> command. You will be prompted to choose which type of schedule to create.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-in-the-prefectyaml-files-deployments-schedule-section","title":"Creating schedules in the <code>prefect.yaml</code> file's <code>deployments</code> -&gt; <code>schedule</code> section","text":"<p>If you save the <code>prefect.yaml</code> file from the <code>prefect deploy</code> command, you will see it has a <code>schedules</code> section for your deployment. Alternatively, you can create a <code>prefect.yaml</code> file from a recipe or from scratch and add a <code>schedules</code> section to it.</p> <pre><code>deployments:\n  ...\n  schedules:\n    - cron: \"0 0 * * *\"\n      timezone: \"America/Chicago\"\n      active: false\n    - cron: \"0 12 * * *\"\n      timezone: \"America/New_York\"\n      active: true\n    - cron: \"0 18 * * *\"\n      timezone: \"Europe/London\"\n      active: true\n</code></pre>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#the-scheduler-service","title":"The <code>Scheduler</code> service","text":"<p>The <code>Scheduler</code> service is started automatically when <code>prefect server start</code> is run and it is a built-in service of Prefect Cloud.</p> <p>By default, the <code>Scheduler</code> service visits deployments on a 60-second loop, though recently-modified deployments will be visited more frequently. The <code>Scheduler</code> evaluates each deployment's schedules and creates new runs appropriately. For typical deployments, it will create the next three runs, though more runs will be scheduled if the next 3 would all start in the next hour.</p> <p>More specifically, the <code>Scheduler</code> tries to create the smallest number of runs that satisfy the following constraints, in order:</p> <ul> <li>No more than 100 runs will be scheduled.</li> <li>Runs will not be scheduled more than 100 days in the future.</li> <li>At least 3 runs will be scheduled.</li> <li>Runs will be scheduled until at least one hour in the future.</li> </ul> <p>These behaviors can all be adjusted through the relevant settings that can be viewed with the terminal command <code>prefect config view --show-defaults</code>:</p> <pre><code>PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE='100'\nPREFECT_API_SERVICES_SCHEDULER_ENABLED='True'\nPREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE='500'\nPREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS='60.0'\nPREFECT_API_SERVICES_SCHEDULER_MIN_RUNS='3'\nPREFECT_API_SERVICES_SCHEDULER_MAX_RUNS='100'\nPREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME='1:00:00'\nPREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME='100 days, 0:00:00'\n</code></pre> <p>See the Settings docs for more information on altering your settings.</p> <p>These settings mean that if a deployment has an hourly schedule, the default settings will create runs for the next 4 days (or 100 hours). If it has a weekly schedule, the default settings will maintain the next 14 runs (up to 100 days in the future).</p> <p>The <code>Scheduler</code> does not affect execution</p> <p>The Prefect <code>Scheduler</code> service only creates new flow runs and places them in <code>Scheduled</code> states. It is not involved in flow or task execution.</p> <p>If you change a schedule, previously scheduled flow runs that have not started are removed, and new scheduled flow runs are created to reflect the new schedule.</p> <p>To remove all scheduled runs for a flow deployment, you can remove the schedule via the UI.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/states/","title":"States","text":"","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#overview","title":"Overview","text":"<p>States are rich objects that contain information about the status of a particular task run or flow run. While you don't need to know the details of the states to use Prefect, you can give your workflows superpowers by taking advantage of it.</p> <p>At any moment, you can learn anything you need to know about a task or flow by examining its current state or the history of its states. For example, a state could tell you that a task:</p> <ul> <li> <p>is scheduled to make a third run attempt in an hour</p> </li> <li> <p>succeeded and what data it produced</p> </li> <li> <p>was scheduled to run, but later cancelled</p> </li> <li> <p>used the cached result of a previous run instead of re-running</p> </li> <li> <p>failed because it timed out</p> </li> </ul> <p>By manipulating a relatively small number of task states, Prefect flows can harness the complexity that emerges in workflows.</p> <p>Only runs have states</p> <p>Though we often refer to the \"state\" of a flow or a task, what we really mean is the state of a flow run or a task run. Flows and tasks are templates that describe what a system does; only when we run the system does it also take on a state. So while we might refer to a task as \"running\" or being \"successful\", we really mean that a specific instance of the task is in that state.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#state-types","title":"State Types","text":"<p>States have names and types. State types are canonical, with specific orchestration rules that apply to transitions into and out of each state type. A state's name, is often, but not always, synonymous with its type. For example, a task run that is running for the first time has a state with the name Running and the type <code>RUNNING</code>. However, if the task retries, that same task run will have the name Retrying and the type <code>RUNNING</code>. Each time the task run transitions into the <code>RUNNING</code> state, the same orchestration rules are applied.</p> <p>There are terminal state types from which there are no orchestrated transitions to any other state type.</p> <ul> <li><code>COMPLETED</code></li> <li><code>CANCELLED</code></li> <li><code>FAILED</code></li> <li><code>CRASHED</code></li> </ul> <p>The full complement of states and state types includes:</p> Name Type Terminal? Description Scheduled SCHEDULED No The run will begin at a particular time in the future. Late SCHEDULED No The run's scheduled start time has passed, but it has not transitioned to PENDING (15 seconds by default). AwaitingRetry SCHEDULED No The run did not complete successfully because of a code issue and had remaining retry attempts. Pending PENDING No The run has been submitted to run, but is waiting on necessary preconditions to be satisfied. Running RUNNING No The run code is currently executing. Retrying RUNNING No The run code is currently executing after previously not complete successfully. Paused PAUSED No The run code has stopped executing until it receives manual approval to proceed. Cancelling CANCELLING No The infrastructure on which the code was running is being cleaned up. Cancelled CANCELLED Yes The run did not complete because a user determined that it should not. Completed COMPLETED Yes The run completed successfully. Failed FAILED Yes The run did not complete because of a code issue and had no remaining retry attempts. Crashed CRASHED Yes The run did not complete because of an infrastructure issue.","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#returned-values","title":"Returned values","text":"<p>When calling a task or a flow, there are three types of returned values:</p> <ul> <li>Data: A Python object (such as <code>int</code>, <code>str</code>, <code>dict</code>, <code>list</code>, and so on).</li> <li><code>State</code>: A Prefect object indicating the state of a flow or task run.</li> <li><code>PrefectFuture</code>: A Prefect object that contains both data and State.</li> </ul> <p>Returning data\u200a is the default behavior any time you call <code>your_task()</code>.</p> <p>Returning Prefect <code>State</code> occurs anytime you call your task or flow with the argument <code>return_state=True</code>.</p> <p>Returning <code>PrefectFuture</code> is achieved by calling <code>your_task.submit()</code>.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-data","title":"Return Data","text":"<p>By default, running a task will return data:</p> <pre><code>from prefect import flow, task \n\n@task \ndef add_one(x):\n    return x + 1\n\n@flow \ndef my_flow():\n    result = add_one(1) # return int\n</code></pre> <p>The same rule applies for a subflow:</p> <pre><code>@flow \ndef subflow():\n    return 42 \n\n@flow \ndef my_flow():\n    result = subflow() # return data\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-prefect-state","title":"Return Prefect State","text":"<p>To return a <code>State</code> instead, add <code>return_state=True</code> as a parameter of your task call.</p> <pre><code>@flow \ndef my_flow():\n    state = add_one(1, return_state=True) # return State\n</code></pre> <p>To get data from a <code>State</code>, call <code>.result()</code>.</p> <pre><code>@flow \ndef my_flow():\n    state = add_one(1, return_state=True) # return State\n    result = state.result() # return int\n</code></pre> <p>The same rule applies for a subflow:</p> <pre><code>@flow \ndef subflow():\n    return 42 \n\n@flow \ndef my_flow():\n    state = subflow(return_state=True) # return State\n    result = state.result() # return int\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-a-prefectfuture","title":"Return a PrefectFuture","text":"<p>To get a <code>PrefectFuture</code>, add <code>.submit()</code> to your task call.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n</code></pre> <p>To get data from a <code>PrefectFuture</code>, call <code>.result()</code>.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n    result = future.result() # return data\n</code></pre> <p>To get a <code>State</code> from a <code>PrefectFuture</code>, call <code>.wait()</code>.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n    state = future.wait() # return State\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#final-state-determination","title":"Final state determination","text":"<p>The final state of a flow is determined by its return value.  The following rules apply:</p> <ul> <li>If an exception is raised directly in the flow function, the flow run is marked as <code>FAILED</code>.</li> <li>If the flow does not return a value (or returns <code>None</code>), its state is determined by the states of all of the tasks and subflows within it.</li> <li>If any task run or subflow run failed and none were cancelled, then the final flow run state is marked as <code>FAILED</code>.</li> <li>If any task run or subflow run was cancelled, then the final flow run state is marked as <code>CANCELLED</code>.</li> <li>If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.</li> <li>If the flow run returns any other object, then it is marked as successfully completed.</li> </ul> <p>See the Final state determination section of the Flows documentation for further details and examples.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#state-change-hooks","title":"State Change Hooks","text":"<p>State change hooks execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#a-simple-example","title":"A simple example","text":"<pre><code>from prefect import flow\n\ndef my_success_hook(flow, flow_run, state):\n    print(\"Flow run succeeded!\")\n\n@flow(on_completion=[my_success_hook])\ndef my_flow():\n    return 42\n\nmy_flow()\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-and-use-hooks","title":"Create and use hooks","text":"","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#available-state-change-hooks","title":"Available state change hooks","text":"Type Flow Task Description <code>on_completion</code> \u2713 \u2713 Executes when a flow or task run enters a <code>Completed</code> state. <code>on_failure</code> \u2713 \u2713 Executes when a flow or task run enters a <code>Failed</code> state. <code>on_cancellation</code> \u2713 - Executes when a flow run enters a <code>Cancelling</code> state. <code>on_crashed</code> \u2713 - Executes when a flow run enters a <code>Crashed</code> state. <code>on_running</code> \u2713 - Executes when a flow run enters a <code>Running</code> state.","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-flow-run-state-change-hooks","title":"Create flow run state change hooks","text":"<pre><code>def my_flow_hook(flow: Flow, flow_run: FlowRun, state: State):\n    \"\"\"This is the required signature for a flow run state\n    change hook. This hook can only be passed into flows.\n    \"\"\"\n\n# pass hook as a list of callables\n@flow(on_completion=[my_flow_hook])\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-task-run-state-change-hooks","title":"Create task run state change hooks","text":"<pre><code>def my_task_hook(task: Task, task_run: TaskRun, state: State):\n    \"\"\"This is the required signature for a task run state change\n    hook. This hook can only be passed into tasks.\n    \"\"\"\n\n# pass hook as a list of callables\n@task(on_failure=[my_task_hook])\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#use-multiple-state-change-hooks","title":"Use multiple state change hooks","text":"<p>State change hooks are versatile, allowing you to specify multiple state change hooks for the same state transition, or to use the same state change hook for different transitions:</p> <pre><code>def my_success_hook(task, task_run, state):\n    print(\"Task run succeeded!\")\n\ndef my_failure_hook(task, task_run, state):\n    print(\"Task run failed!\")\n\ndef my_succeed_or_fail_hook(task, task_run, state):\n    print(\"If the task run succeeds or fails, this hook runs.\")\n\n@task(\n    on_completion=[my_success_hook, my_succeed_or_fail_hook],\n    on_failure=[my_failure_hook, my_succeed_or_fail_hook]\n)\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#pass-kwargs-to-your-hooks","title":"Pass <code>kwargs</code> to your hooks","text":"<p>The Prefect engine will call your hooks for you upon the state change, passing in the flow, flow run, and state objects.</p> <p>However, you can define your hook to have additional default arguments:</p> <pre><code>from prefect import flow\n\ndata = {}\n\ndef my_hook(flow, flow_run, state, my_arg=\"custom_value\"):\n    data.update(my_arg=my_arg, state=state)\n\n@flow(on_completion=[my_hook])\ndef lazy_flow():\n    pass\n\nstate = lazy_flow(return_state=True)\n\nassert data == {\"my_arg\": \"custom_value\", \"state\": state}\n</code></pre> <p>... or define your hook to accept arbitrary keyword arguments:</p> <pre><code>from functools import partial\nfrom prefect import flow, task\n\ndata = {}\n\ndef my_hook(task, task_run, state, **kwargs):\n    data.update(state=state, **kwargs)\n\n@task\ndef bad_task():\n    raise ValueError(\"meh\")\n\n@flow\ndef ok_with_failure_flow(x: str = \"foo\", y: int = 42):\n    bad_task_with_a_hook = bad_task.with_options(\n        on_failure=[partial(my_hook, **dict(x=x, y=y))]\n    )\n    # return a tuple of \"bar\" and the task run state\n    # to avoid raising the task's exception\n    return \"bar\", bad_task_with_a_hook(return_state=True)\n\n_, task_run_state = ok_with_failure_flow()\n\nassert data == {\"x\": \"foo\", \"y\": 42, \"state\": task_run_state}\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#more-examples-of-state-change-hooks","title":"More examples of state change hooks","text":"<ul> <li>Send a notification when a flow run fails</li> <li>Delete a Cloud Run job when a flow crashes</li> </ul>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/storage/","title":"Storage","text":"<p>Storage blocks are not recommended</p> <p>Storage blocks are part of the legacy block-based deployment model. Instead, using <code>serve</code> or <code>runner</code>-based Python creation methods or workers and work pools with <code>prefect deploy</code> via the CLI are the recommended options for creating a deployment.  Flow code storage can be specified in the Python file with <code>serve</code> or <code>runner</code>-based Python creation methods; alternatively, with the work pools and workers style of flow deployment, you can specify flow code storage during the interactive <code>prefect deploy</code> CLI experience and in its resulting <code>prefect.yaml</code> file. </p> <p>Storage lets you configure how flow code for deployments is persisted and retrieved by Prefect workers (or legacy agents). Anytime you build a block-based deployment, a storage block is used to upload the entire directory containing your workflow code (along with supporting files) to its configured location.  This helps ensure portability of your relative imports, configuration files, and more.  Note that your environment dependencies (for example, external Python packages) still need to be managed separately.</p> <p>If no storage is explicitly configured, Prefect will use <code>LocalFileSystem</code> storage by default. Local storage works fine for many local flow run scenarios, especially when testing and getting started. However, due to the inherent lack of portability, many use cases are better served by using remote storage such as S3 or Google Cloud Storage.</p> <p>Prefect supports creating multiple storage configurations and switching between storage as needed.</p> <p>Storage uses blocks</p> <p>Blocks are the Prefect technology underlying storage, and enables you to do so much more.</p> <p>In addition to creating storage blocks via the Prefect CLI, you can now create storage blocks and other kinds of block configuration objects via the Prefect UI and Prefect Cloud.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#configuring-storage-for-a-deployment","title":"Configuring storage for a deployment","text":"<p>When building a deployment for a workflow, you have two options for configuring workflow storage:</p> <ul> <li>Use the default local storage</li> <li>Preconfigure a storage block to use</li> </ul>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#using-the-default","title":"Using the default","text":"<p>Anytime you call <code>prefect deployment build</code> without providing the <code>--storage-block</code> flag, a default <code>LocalFileSystem</code> block will be used.  Note that this block will always use your present working directory as its basepath (which is usually desirable).  You can see the block's settings by inspecting the <code>deployment.yaml</code> file that Prefect creates after calling <code>prefect deployment build</code>.</p> <p>While you generally can't run a deployment stored on a local file system on other machines, any agent running on the same machine will be able to successfully run your deployment.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#supported-storage-blocks","title":"Supported storage blocks","text":"<p>Current options for deployment storage blocks include:</p> Storage Description Required Library Local File System Store code in a run's local file system. Remote File System Store code in a any filesystem supported by <code>fsspec</code>. AWS S3 Storage Store code in an AWS S3 bucket. <code>s3fs</code> Azure Storage Store code in Azure Datalake and Azure Blob Storage. <code>adlfs</code> GitHub Storage Store code in a GitHub repository. Google Cloud Storage Store code in a Google Cloud Platform (GCP) Cloud Storage bucket. <code>gcsfs</code> SMB Store code in SMB shared network storage. <code>smbprotocol</code> GitLab Repository Store code in a GitLab repository. <code>prefect-gitlab</code> Bitbucket Repository Store code in a Bitbucket repository. <code>prefect-bitbucket</code> <p>Accessing files may require storage filesystem libraries</p> <p>Note that the appropriate filesystem library supporting the storage location must be installed prior to building a deployment with a storage block or accessing the storage location from flow scripts.</p> <p>For example, the AWS S3 Storage block requires the <code>s3fs</code> library.</p> <p>See Filesystem package dependencies for more information about configuring filesystem libraries in your execution environment.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#configuring-a-block","title":"Configuring a block","text":"<p>You can create these blocks either via the UI or via Python.</p> <p>You can create, edit, and manage storage blocks in the Prefect UI and Prefect Cloud. On a Prefect server, blocks are created in the server's database. On Prefect Cloud, blocks are created on a workspace.</p> <p>To create a new block, select the + button. Prefect displays a library of block types you can configure to create blocks to be used by your flows.</p> <p></p> <p>Select Add + to configure a new storage block based on a specific block type. Prefect displays a Create page that enables specifying storage settings.</p> <p></p> <p>You can also create blocks using the Prefect Python API:</p> <pre><code>from prefect.filesystems import S3\n\nblock = S3(bucket_path=\"my-bucket/a-sub-directory\", \n           aws_access_key_id=\"foo\", \n           aws_secret_access_key=\"bar\"\n)\nblock.save(\"example-block\")\n</code></pre> <p>This block configuration is now available to be used by anyone with appropriate access to your Prefect API.  We can use this block to build a deployment by passing its slug to the <code>prefect deployment build</code> command. The storage block slug is formatted as <code>block-type/block-name</code>. In this case, <code>s3/example-block</code> for an AWS S3 Bucket block named <code>example-block</code>. See block identifiers for details.</p> <pre><code>prefect deployment build ./flows/my_flow.py:my_flow --name \"Example Deployment\" --storage-block s3/example-block\n</code></pre> <p>This command will upload the contents of your flow's directory to the designated storage location, then the full deployment specification will be persisted to a newly created <code>deployment.yaml</code> file.  For more information, see Deployments.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/task-runners/","title":"Task runners","text":"<p>Task runners enable you to engage specific executors for Prefect tasks, such as for concurrent, parallel, or distributed execution of tasks.</p> <p>Task runners are not required for task execution. If you call a task function directly, the task executes as a regular Python function, without a task runner, and produces whatever result is returned by the function.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#task-runner-overview","title":"Task runner overview","text":"<p>Calling a task function from within a flow, using the default task settings, executes the function sequentially. Execution of the task function blocks execution of the flow until the task completes. This means, by default, calling multiple tasks in a flow causes them to run in order. </p> <p>However, that's not the only way to run tasks!</p> <p>You can use the <code>.submit()</code> method on a task function to submit the task to a task runner. Using a task runner enables you to control whether tasks run sequentially, concurrently, or if you want to take advantage of a parallel or distributed execution library such as Dask or Ray.</p> <p>Using the <code>.submit()</code> method to submit a task also causes the task run to return a <code>PrefectFuture</code>, a Prefect object that contains both any data returned by the task function and a <code>State</code>, a Prefect object indicating the state of the task run.</p> <p>Prefect currently provides the following built-in task runners: </p> <ul> <li><code>SequentialTaskRunner</code> can run tasks sequentially. </li> <li><code>ConcurrentTaskRunner</code> can run tasks concurrently, allowing tasks to switch when blocking on IO. Tasks will be submitted to a thread pool maintained by <code>anyio</code>.</li> </ul> <p>In addition, the following Prefect-developed task runners for parallel or distributed task execution may be installed as Prefect Integrations. </p> <ul> <li><code>DaskTaskRunner</code> can run tasks requiring parallel execution using <code>dask.distributed</code>. </li> <li><code>RayTaskRunner</code> can run tasks requiring parallel execution using Ray.</li> </ul> <p>Concurrency versus parallelism</p> <p>The words \"concurrency\" and \"parallelism\" may sound the same, but they mean different things in computing.</p> <p>Concurrency refers to a system that can do more than one thing simultaneously, but not at the exact same time. It may be more accurate to think of concurrent execution as non-blocking: within the restrictions of resources available in the execution environment and data dependencies between tasks, execution of one task does not block execution of other tasks in a flow.</p> <p>Parallelism refers to a system that can do more than one thing at the exact same time. Again, within the restrictions of resources available, parallel execution can run tasks at the same time, such as for operations mapped across a dataset.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-a-task-runner","title":"Using a task runner","text":"<p>You do not need to specify a task runner for a flow unless your tasks require a specific type of execution. </p> <p>To configure your flow to use a specific task runner, import a task runner and assign it as an argument for the flow when the flow is defined.</p> <p>Remember to call <code>.submit()</code> when using a task runner</p> <p>Make sure you use <code>.submit()</code> to run your task with a task runner. Calling the task directly, without <code>.submit()</code>, from within a flow will run the task sequentially instead of using a specified task runner.</p> <p>For example, you can use <code>ConcurrentTaskRunner</code> to allow tasks to switch when they would block.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import ConcurrentTaskRunner\nimport time\n\n@task\ndef stop_at_floor(floor):\n    print(f\"elevator moving to floor {floor}\")\n    time.sleep(floor)\n    print(f\"elevator stops on floor {floor}\")\n\n@flow(task_runner=ConcurrentTaskRunner())\ndef elevator():\n    for floor in range(10, 0, -1):\n        stop_at_floor.submit(floor)\n</code></pre> <p>If you specify an uninitialized task runner class, a task runner instance of that type is created with the default settings. You can also pass additional configuration parameters for task runners that accept parameters, such as <code>DaskTaskRunner</code> and <code>RayTaskRunner</code>.</p> <p>Default task runner</p> <p>If you don't specify a task runner for a flow and you call a task with <code>.submit()</code> within the flow, Prefect uses the default <code>ConcurrentTaskRunner</code>.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-sequentially","title":"Running tasks sequentially","text":"<p>Sometimes, it's useful to force tasks to run sequentially to make it easier to reason about the behavior of your program. Switching to the <code>SequentialTaskRunner</code> will force submitted tasks to run sequentially rather than concurrently.</p> <p>Synchronous and asynchronous tasks</p> <p>The <code>SequentialTaskRunner</code> works with both synchronous and asynchronous task functions. Asynchronous tasks are Python functions defined using <code>async def</code> rather than <code>def</code>.</p> <p>The following example demonstrates using the <code>SequentialTaskRunner</code> to ensure that tasks run sequentially. In the example, the flow <code>glass_tower</code> runs the task <code>stop_at_floor</code> for floors one through 38, in that order.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\nimport random\n\n@task\ndef stop_at_floor(floor):\n    situation = random.choice([\"on fire\",\"clear\"])\n    print(f\"elevator stops on {floor} which is {situation}\")\n\n@flow(task_runner=SequentialTaskRunner(),\n      name=\"towering-infernflow\",\n      )\ndef glass_tower():\n    for floor in range(1, 39):\n        stop_at_floor.submit(floor)\n\nglass_tower()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-multiple-task-runners","title":"Using multiple task runners","text":"<p>Each flow can only have a single task runner, but sometimes you may want a subset of your tasks to run using a specific task runner. In this case, you can create subflows for tasks that need to use a different task runner.</p> <p>For example, you can have a flow (in the example below called <code>sequential_flow</code>) that runs its tasks locally using the <code>SequentialTaskRunner</code>. If you have some tasks that can run more efficiently in parallel on a Dask cluster, you could create a subflow (such as <code>dask_subflow</code>) to run those tasks using the <code>DaskTaskRunner</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef hello_local():\n    print(\"Hello!\")\n\n@task\ndef hello_dask():\n    print(\"Hello from Dask!\")\n\n@flow(task_runner=SequentialTaskRunner())\ndef sequential_flow():\n    hello_local.submit()\n    dask_subflow()\n    hello_local.submit()\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_subflow():\n    hello_dask.submit()\n\nif __name__ == \"__main__\":\n    sequential_flow()\n</code></pre> <p>Guarding main</p> <p>Note that you should guard the <code>main</code> function by using <code>if __name__ == \"__main__\"</code> to avoid issues with parallel processing. </p> <p>This script outputs the following logs demonstrating the use of the Dask task runner:</p> <pre><code>120:14:29.785 | INFO    | prefect.engine - Created flow run 'ivory-caiman' for flow 'sequential-flow'\n20:14:29.785 | INFO    | Flow run 'ivory-caiman' - Starting 'SequentialTaskRunner'; submitted tasks will be run sequentially...\n20:14:29.880 | INFO    | Flow run 'ivory-caiman' - Created task run 'hello_local-7633879f-0' for task 'hello_local'\n20:14:29.881 | INFO    | Flow run 'ivory-caiman' - Executing 'hello_local-7633879f-0' immediately...\nHello!\n20:14:29.904 | INFO    | Task run 'hello_local-7633879f-0' - Finished in state Completed()\n20:14:29.952 | INFO    | Flow run 'ivory-caiman' - Created subflow run 'nimble-sparrow' for flow 'dask-subflow'\n20:14:29.953 | INFO    | prefect.task_runner.dask - Creating a new Dask cluster with `distributed.deploy.local.LocalCluster`\n20:14:31.862 | INFO    | prefect.task_runner.dask - The Dask dashboard is available at http://127.0.0.1:8787/status\n20:14:31.901 | INFO    | Flow run 'nimble-sparrow' - Created task run 'hello_dask-2b96d711-0' for task 'hello_dask'\n20:14:32.370 | INFO    | Flow run 'nimble-sparrow' - Submitted task run 'hello_dask-2b96d711-0' for execution.\nHello from Dask!\n20:14:33.358 | INFO    | Flow run 'nimble-sparrow' - Finished in state Completed('All states completed.')\n20:14:33.368 | INFO    | Flow run 'ivory-caiman' - Created task run 'hello_local-7633879f-1' for task 'hello_local'\n20:14:33.368 | INFO    | Flow run 'ivory-caiman' - Executing 'hello_local-7633879f-1' immediately...\nHello!\n20:14:33.386 | INFO    | Task run 'hello_local-7633879f-1' - Finished in state Completed()\n20:14:33.399 | INFO    | Flow run 'ivory-caiman' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-results-from-submitted-tasks","title":"Using results from submitted tasks","text":"<p>When you use <code>.submit()</code> to submit a task to a task runner, the task runner creates a <code>PrefectFuture</code> for access to the state and result of the task.</p> <p>A <code>PrefectFuture</code> is an object that provides access to a computation happening in a task runner \u2014 even if that computation is happening on a remote system.</p> <p>In the following example, we save the return value of calling <code>.submit()</code> on the task <code>say_hello</code> to the variable <code>future</code>, and then we print the type of the variable:</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@flow\ndef hello_world():\n    future = say_hello.submit(\"Marvin\")\n    print(f\"variable 'future' is type {type(future)}\")\n\nhello_world()\n</code></pre> <p>When you run this code, you'll see that the variable <code>future</code> is a <code>PrefectFuture</code>:</p> <pre><code>variable 'future' is type &lt;class 'prefect.futures.PrefectFuture'&gt;\n</code></pre> <p>When you pass a future into a task, Prefect waits for the \"upstream\" task \u2014 the one that the future references \u2014 to reach a final state before starting the downstream task.</p> <p>This means that the downstream task won't receive the <code>PrefectFuture</code> you passed as an argument. Instead, the downstream task will receive the value that the upstream task returned.</p> <p>Take a look at how this works in the following example</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef print_result(result):\n    print(type(result))\n    print(result)\n\n@flow(name=\"hello-flow\")\ndef hello_world():\n    future = say_hello.submit(\"Marvin\")\n    print_result.submit(future)\n\nhello_world()\n</code></pre> <pre><code>&lt;class 'str'&gt;\nHello Marvin!\n</code></pre> <p>Futures have a few useful methods. For example, you can get the return value of the task run with  <code>.result()</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 42\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    result = future.result()\n    print(result)\n\nmy_flow()\n</code></pre> <p>The <code>.result()</code> method will wait for the task to complete before returning the result to the caller. If the task run fails, <code>.result()</code> will raise the task run's exception. You may disable this behavior with the <code>raise_on_failure</code> option:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return \"I'm a task!\"\n\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    result = future.result(raise_on_failure=False)\n    if future.get_state().is_failed():\n        # `result` is an exception! handle accordingly\n        ...\n    else:\n        # `result` is the expected return value of our task\n        ...\n</code></pre> <p>You can retrieve the current state of the task run associated with the <code>PrefectFuture</code> using <code>.get_state()</code>:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    state = future.get_state()\n</code></pre> <p>You can also wait for a task to complete by using the <code>.wait()</code> method:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    final_state = future.wait()\n</code></pre> <p>You can include a timeout in the <code>wait</code> call to perform logic if the task has not finished in a given amount of time:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    final_state = future.wait(1)  # Wait one second max\n    if final_state:\n        # Take action if the task is done\n        result = final_state.result()\n    else:\n        ... # Task action if the task is still running\n</code></pre> <p>You may also use the <code>wait_for=[]</code> parameter when calling a task, specifying upstream task dependencies. This enables you to control task execution order for tasks that do not share data dependencies.</p> <pre><code>@task\ndef task_a():\n    pass\n\n@task\ndef task_b():\n    pass\n\n@task\ndef task_c():\n    pass\n\n@task\ndef task_d():\n    pass\n\n@flow\ndef my_flow():\n    a = task_a.submit()\n    b = task_b.submit()\n    # Wait for task_a and task_b to complete\n    c = task_c.submit(wait_for=[a, b])\n    # task_d will wait for task_c to complete\n    # Note: If waiting for one task it must still be in a list.\n    d = task_d(wait_for=[c])\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#when-to-use-result-in-flows","title":"When to use <code>.result()</code> in flows","text":"<p>The simplest pattern for writing a flow is either only using tasks or only using pure Python functions. When you need to mix the two, use <code>.result()</code>.</p> <p>Using only tasks:</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    hello = say_hello.submit(\"Marvin\")\n    nice_to_meet_you = say_nice_to_meet_you.submit(hello)\n\nhello_world()\n</code></pre> <p>Using only Python functions:</p> <pre><code>from prefect import flow, task\n\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    # because this is just a Python function, calls will not be tracked\n    hello = say_hello(\"Marvin\") \n    nice_to_meet_you = say_nice_to_meet_you(hello)\n\nhello_world()\n</code></pre> <p>Mixing tasks and Python functions:</p> <pre><code>from prefect import flow, task\n\ndef say_hello_extra_nicely_to_marvin(hello): # not a task or flow!\n    if hello == \"Hello Marvin!\":\n        return \"HI MARVIN!\"\n    return hello\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    # run a task and get the result\n    hello = say_hello.submit(\"Marvin\").result()\n\n    # not calling a task or flow\n    special_greeting = say_hello_extra_nicely_to_marvin(hello)\n\n    # pass our modified greeting back into a task\n    nice_to_meet_you = say_nice_to_meet_you.submit(special_greeting)\n\n    print(nice_to_meet_you.result())\n\nhello_world()\n</code></pre> <p>Note that <code>.result()</code> also limits Prefect's ability to track task dependencies. In the \"mixed\" example above, Prefect will not be aware that <code>say_hello</code> is upstream of <code>nice_to_meet_you</code>.</p> <p>Calling <code>.result()</code> is blocking</p> <p>When calling <code>.result()</code>, be mindful your flow function will have to wait until the task run is completed before continuing.</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef do_important_stuff():\n    print(\"Doing lots of important stuff!\")\n\n@flow\ndef hello_world():\n    # blocks until `say_hello` has finished\n    result = say_hello.submit(\"Marvin\").result() \n    do_important_stuff.submit()\n\nhello_world()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-on-dask","title":"Running tasks on Dask","text":"<p>The <code>DaskTaskRunner</code> is a parallel task runner that submits tasks to the <code>dask.distributed</code> scheduler. By default, a temporary Dask cluster is created for the duration of the flow run. If you already have a Dask cluster running, either local or cloud hosted, you can provide the connection URL via the <code>address</code> kwarg.</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed: <code>pip install prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>DaskTaskRunner</code> configured to access an existing Dask cluster at <code>http://my-dask-cluster</code>.</p> <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner(address=\"http://my-dask-cluster\"))\ndef my_flow():\n    ...\n</code></pre> <p><code>DaskTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Dask scheduler. cluster_class The cluster class to use when creating a temporary Dask cluster. It can be either the full class name (for example, <code>\"distributed.LocalCluster\"</code>), or the class itself. cluster_kwargs Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary Dask cluster. adapt_kwargs Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary Dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided. client_kwargs Additional kwargs to use when creating a <code>dask.distributed.Client</code>. <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or you will encounter  warnings and errors.</p> <p>If you don't provide the <code>address</code> of a Dask scheduler, Prefect creates a temporary local cluster automatically. The number of workers used is based on the number of cores on your machine. The default provides a mix of processes and threads that should work well for most workloads. If you want to specify this explicitly, you can pass values for <code>n_workers</code> or <code>threads_per_worker</code> to <code>cluster_kwargs</code>.</p> <pre><code># Use 4 worker processes, each with 2 threads\nDaskTaskRunner(\n    cluster_kwargs={\"n_workers\": 4, \"threads_per_worker\": 2}\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-a-temporary-cluster","title":"Using a temporary cluster","text":"<p>The <code>DaskTaskRunner</code> is capable of creating a temporary cluster using any of Dask's cluster-manager options. This can be useful when you want each flow run to have its own Dask cluster, allowing for per-flow adaptive scaling.</p> <p>To configure, you need to provide a <code>cluster_class</code>. This can be:</p> <ul> <li>A string specifying the import path to the cluster class (for example, <code>\"dask_cloudprovider.aws.FargateCluster\"</code>)</li> <li>The cluster class itself</li> <li>A function for creating a custom cluster. </li> </ul> <p>You can also configure <code>cluster_kwargs</code>, which takes a dictionary of keyword arguments to pass to <code>cluster_class</code> when starting the flow run.</p> <p>For example, to configure a flow to use a temporary <code>dask_cloudprovider.aws.FargateCluster</code> with 4 workers running with an image named <code>my-prefect-image</code>:</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    cluster_kwargs={\"n_workers\": 4, \"image\": \"my-prefect-image\"},\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#connecting-to-an-existing-cluster","title":"Connecting to an existing cluster","text":"<p>Multiple Prefect flow runs can all use the same existing Dask cluster. You might manage a single long-running Dask cluster (maybe using the Dask  Helm Chart) and configure flows to connect to it during execution. This has a few downsides when compared to using a temporary cluster (as described above):</p> <ul> <li>All workers in the cluster must have dependencies installed for all flows you   intend to run.</li> <li>Multiple flow runs may compete for resources. Dask tries to do a good job   sharing resources between tasks, but you may still run into issues.</li> </ul> <p>That said, you may prefer managing a single long-running cluster. </p> <p>To configure a <code>DaskTaskRunner</code> to connect to an existing cluster, pass in the address of the scheduler to the <code>address</code> argument:</p> <pre><code># Connect to an existing cluster running at a specified address\nDaskTaskRunner(address=\"tcp://...\")\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#adaptive-scaling","title":"Adaptive scaling","text":"<p>One nice feature of using a <code>DaskTaskRunner</code> is the ability to scale adaptively to the workload. Instead of specifying <code>n_workers</code> as a fixed number, this lets you specify a minimum and maximum number of workers to use, and the dask cluster will scale up and down as needed.</p> <p>To do this, you can pass <code>adapt_kwargs</code> to <code>DaskTaskRunner</code>. This takes the following fields:</p> <ul> <li><code>maximum</code> (<code>int</code> or <code>None</code>, optional): the maximum number of workers to scale   to. Set to <code>None</code> for no maximum.</li> <li><code>minimum</code> (<code>int</code> or <code>None</code>, optional): the minimum number of workers to scale   to. Set to <code>None</code> for no minimum.</li> </ul> <p>For example, here we configure a flow to run on a <code>FargateCluster</code> scaling up to at most 10 workers.</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    adapt_kwargs={\"maximum\": 10}\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#dask-annotations","title":"Dask annotations","text":"<p>Dask annotations can be used to further control the behavior of tasks.</p> <p>For example, we can set the priority of tasks in the Dask scheduler:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n\n@flow(task_runner=DaskTaskRunner())\ndef my_flow():\n    with dask.annotate(priority=-10):\n        future = show.submit(1)  # low priority task\n\n    with dask.annotate(priority=10):\n        future = show.submit(2)  # high priority task\n</code></pre> <p>Another common use case is resource annotations:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n# Create a `LocalCluster` with some resource annotations\n# Annotations are abstract in dask and not inferred from your system.\n# Here, we claim that our system has 1 GPU and 1 process available per worker\n@flow(\n    task_runner=DaskTaskRunner(\n        cluster_kwargs={\"n_workers\": 1, \"resources\": {\"GPU\": 1, \"process\": 1}}\n    )\n)\n\ndef my_flow():\n    with dask.annotate(resources={'GPU': 1}):\n        future = show(0)  # this task requires 1 GPU resource on a worker\n\n    with dask.annotate(resources={'process': 1}):\n        # These tasks each require 1 process on a worker; because we've \n        # specified that our cluster has 1 process per worker and 1 worker,\n        # these tasks will run sequentially\n        future = show(1)\n        future = show(2)\n        future = show(3)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-on-ray","title":"Running tasks on Ray","text":"<p>The <code>RayTaskRunner</code> \u2014 installed separately as a Prefect Collection \u2014 is a parallel task runner that submits tasks to Ray. By default, a temporary Ray instance is created for the duration of the flow run. If you already have a Ray instance running, you can provide the connection URL via an <code>address</code> argument.</p> <p>Remote storage and Ray tasks</p> <p>We recommend configuring remote storage for task execution with the <code>RayTaskRunner</code>. This ensures tasks executing in Ray have access to task result storage, particularly when accessing a Ray instance outside of your execution environment.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-ray</code> collection is installed: <code>pip install prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>RayTaskRunner</code> configured to access an existing Ray instance at <code>ray://192.0.2.255:8786</code>.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner(address=\"ray://192.0.2.255:8786\"))\ndef my_flow():\n    ... \n</code></pre> <p><code>RayTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Ray instance, starting with the ray:// URI. init_kwargs Additional kwargs to use when calling <code>ray.init</code>. <p>Note that Ray Client uses the ray:// URI to indicate the address of a Ray instance. If you don't provide the <code>address</code> of a Ray instance, Prefect creates a temporary instance automatically.</p> <p>Ray environment limitations</p> <p>While we're excited about adding support for parallel task execution via Ray to Prefect, there are some inherent limitations with Ray you should be aware of:</p> <p>Ray's support for Python 3.11 is experimental.</p> <p>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</p> <p>See the Ray installation documentation for further compatibility information.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/tasks/","title":"Tasks","text":"<p>A task is a function that represents a discrete unit of work in a Prefect workflow. Tasks are not required \u2014 you may define Prefect workflows that consist only of flows, using regular Python statements and functions. Tasks enable you to encapsulate elements of your workflow logic in observable units that can be reused across flows and subflows.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#tasks-overview","title":"Tasks overview","text":"<p>Tasks are functions: they can take inputs, perform work, and return an output. A Prefect task can do almost anything a Python function can do.  </p> <p>Tasks are special because they receive metadata about upstream dependencies and the state of those dependencies before they run, even if they don't receive any explicit data inputs from them. This gives you the opportunity to, for example, have a task wait on the completion of another task before executing.</p> <p>Tasks also take advantage of automatic Prefect logging to capture details about task runs such as runtime, tags, and final state.</p> <p>You can define your tasks within the same file as your flow definition, or you can define tasks within modules and import them for use in your flow definitions. Tasks may be called from within a flow, from within a subflow, or (as of <code>prefect 2.18.x</code>) from within another task.</p> <p>Calling a task from a flow</p> <p>Use the <code>@task</code> decorator to designate a function as a task. Calling the task creates a new task run:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@flow\ndef my_flow():\n    my_task()\n</code></pre> <p>Calling a task from another task</p> <p>As of <code>prefect 2.18.x</code>, you can call a task from within another task:</p> <pre><code>from prefect import task\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@task(log_prints=True)\ndef my_parent_task():\n    my_task()\n</code></pre> <p>Tasks are uniquely identified by a task key, which is a hash composed of the task name, the fully-qualified name of the function, and any tags. If the task does not have a name specified, the name is derived from the task function.</p> <p>How big should a task be?</p> <p>Prefect encourages \"small tasks\" \u2014 each one should represent a single logical step of your workflow. This allows Prefect to better contain task failures.</p> <p>To be clear, there's nothing stopping you from putting all of your code in a single task \u2014 Prefect will happily run it! However, if any line of code fails, the entire task will fail and must be retried from the beginning. This can be avoided by splitting the code into multiple dependent tasks.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-arguments","title":"Task arguments","text":"<p>Tasks allow for customization through optional arguments:</p> Argument Description <code>name</code> An optional name for the task. If not provided, the name will be inferred from the function name. <code>description</code> An optional string description for the task. If not provided, the description will be pulled from the docstring for the decorated function. <code>tags</code> An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime. <code>cache_key_fn</code> An optional callable that, given the task run context and call parameters, generates a string key. If the key matches a previous completed state, that state result will be restored instead of running the task again. <code>cache_expiration</code> An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire. <code>retries</code> An optional number of times to retry on task run failure. <code>retry_delay_seconds</code> An optional number of seconds to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. <code>log_prints</code> An optional boolean indicating whether to log print statements. <code>persist_result</code> An optional boolean indicating whether to persist the result of the task run to storage. <p>See all possible parameters in the Python SDK API docs.</p> <p>For example, you can provide a <code>name</code> value for the task. Here we've used the optional <code>description</code> argument as well.</p> <pre><code>@task(name=\"hello-task\", \n      description=\"This task says hello.\")\ndef my_task():\n    print(\"Hello, I'm a task\")\n</code></pre> <p>You can distinguish runs of this task by providing a <code>task_run_name</code>; this setting accepts a string that can optionally contain templated references to the keyword arguments of your task. The name will be formatted using Python's standard string formatting syntax as can be seen here:</p> <pre><code>import datetime\nfrom prefect import flow, task\n\n@task(name=\"My Example Task\", \n      description=\"An example task for a tutorial.\",\n      task_run_name=\"hello-{name}-on-{date:%A}\")\ndef my_task(name, date):\n    pass\n\n@flow\ndef my_flow():\n    # creates a run with a name like \"hello-marvin-on-Thursday\"\n    my_task(name=\"marvin\", date=datetime.datetime.now(datetime.timezone.utc))\n</code></pre> <p>Additionally this setting also accepts a function that returns a string to be used for the task run name:</p> <pre><code>import datetime\nfrom prefect import flow, task\n\ndef generate_task_name():\n    date = datetime.datetime.now(datetime.timezone.utc)\n    return f\"{date:%A}-is-a-lovely-day\"\n\n@task(name=\"My Example Task\",\n      description=\"An example task for a tutorial.\",\n      task_run_name=generate_task_name)\ndef my_task(name):\n    pass\n\n@flow\ndef my_flow():\n    # creates a run with a name like \"Thursday-is-a-lovely-day\"\n    my_task(name=\"marvin\")\n</code></pre> <p>If you need access to information about the task, use the <code>prefect.runtime</code> module. For example:</p> <pre><code>from prefect import flow\nfrom prefect.runtime import flow_run, task_run\n\ndef generate_task_name():\n    flow_name = flow_run.flow_name\n    task_name = task_run.task_name\n\n    parameters = task_run.parameters\n    name = parameters[\"name\"]\n    limit = parameters[\"limit\"]\n\n    return f\"{flow_name}-{task_name}-with-{name}-and-{limit}\"\n\n@task(name=\"my-example-task\",\n      description=\"An example task for a tutorial.\",\n      task_run_name=generate_task_name)\ndef my_task(name: str, limit: int = 100):\n    pass\n\n@flow\ndef my_flow(name: str):\n    # creates a run with a name like \"my-flow-my-example-task-with-marvin-and-100\"\n    my_task(name=\"marvin\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#tags","title":"Tags","text":"<p>Tags are optional string labels that enable you to identify and group tasks other than by name or flow. Tags are useful for:</p> <ul> <li>Filtering task runs by tag in the UI and via the Prefect REST API.</li> <li>Setting concurrency limits on task runs by tag.</li> </ul> <p>Tags may be specified as a keyword argument on the task decorator.</p> <pre><code>@task(name=\"hello-task\", tags=[\"test\"])\ndef my_task():\n    print(\"Hello, I'm a task\")\n</code></pre> <p>You can also provide tags as an argument with a <code>tags</code> context manager, specifying tags when the task is called rather than in its definition.</p> <pre><code>from prefect import flow, task\nfrom prefect import tags\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@flow\ndef my_flow():\n    with tags(\"test\"):\n        my_task()\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#retries","title":"Retries","text":"<p>Prefect can automatically retry tasks on failure. In Prefect, a task fails if its Python function raises an exception.</p> <p>To enable retries, pass <code>retries</code> and <code>retry_delay_seconds</code> parameters to your task. If the task fails, Prefect will retry it up to <code>retries</code> times, waiting <code>retry_delay_seconds</code> seconds between each attempt. If the task fails on the final retry, Prefect marks the task as crashed if the task raised an exception or failed if it returned a string.</p> <p>Retries don't create new task runs</p> <p>A new task run is not created when a task is retried. A new state is added to the state history of the original task run.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#a-real-world-example-making-an-api-request","title":"A real-world example: making an API request","text":"<p>Consider the real-world problem of making an API request. In this example, we'll use the <code>httpx</code> library to make an HTTP request.</p> <pre><code>import httpx\n\nfrom prefect import flow, task\n\n\n@task(retries=2, retry_delay_seconds=5)\ndef get_data_task(\n    url: str = \"https://api.brittle-service.com/endpoint\"\n) -&gt; dict:\n    response = httpx.get(url)\n\n    # If the response status code is anything but a 2xx, httpx will raise\n    # an exception. This task doesn't handle the exception, so Prefect will\n    # catch the exception and will consider the task run failed.\n    response.raise_for_status()\n\n    return response.json()\n\n\n@flow\ndef get_data_flow():\n    get_data_task()\n</code></pre> <p>In this task, if the HTTP request to the brittle API receives any status code other than a 2xx (200, 201, etc.), Prefect will retry the task a maximum of two times, waiting five seconds in between retries.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#custom-retry-behavior","title":"Custom retry behavior","text":"<p>The <code>retry_delay_seconds</code> option accepts a list of delays for more custom retry behavior. The following task will wait for successively increasing intervals of 1, 10, and 100 seconds, respectively, before the next attempt starts:</p> <pre><code>from prefect import task\n\n@task(retries=3, retry_delay_seconds=[1, 10, 100])\ndef some_task_with_manual_backoff_retries():\n   ...\n</code></pre> <p>The <code>retry_condition_fn</code> option accepts a callable that returns a boolean. If the callable returns <code>True</code>, the task will be retried. If the callable returns <code>False</code>, the task will not be retried. The callable accepts three arguments \u2014 the task, the task run, and the state of the task run. The following task will retry on HTTP status codes other than 401 or 404:</p> <pre><code>import httpx\nfrom prefect import flow, task\n\ndef retry_handler(task, task_run, state) -&gt; bool:\n    \"\"\"This is a custom retry handler to handle when we want to retry a task\"\"\"\n    try:\n        # Attempt to get the result of the task\n        state.result()\n    except httpx.HTTPStatusError as exc:\n        # Retry on any HTTP status code that is not 401 or 404\n        do_not_retry_on_these_codes = [401, 404]\n        return exc.response.status_code not in do_not_retry_on_these_codes\n    except httpx.ConnectError:\n        # Do not retry\n        return False\n    except:\n        # For any other exception, retry\n        return True\n\n@task(retries=1, retry_condition_fn=retry_handler)\ndef my_api_call_task(url):\n    response = httpx.get(url)\n    response.raise_for_status()\n    return response.json()\n\n@flow\ndef get_data_flow(url):\n    my_api_call_task(url=url)\n\nif __name__ == \"__main__\":\n    get_data_flow(url=\"https://httpbin.org/status/503\")\n</code></pre> <p>Additionally, you can pass a callable that accepts the number of retries as an argument and returns a list. Prefect includes an <code>exponential_backoff</code> utility that will automatically generate a list of retry delays that correspond to an exponential backoff retry strategy. The following flow will wait for 10, 20, then 40 seconds before each retry.</p> <pre><code>from prefect import task\nfrom prefect.tasks import exponential_backoff\n\n@task(retries=3, retry_delay_seconds=exponential_backoff(backoff_factor=10))\ndef some_task_with_exponential_backoff_retries():\n   ...\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#advanced-topic-adding-jitter","title":"Advanced topic: adding \"jitter\"","text":"<p>While using exponential backoff, you may also want to add jitter to the delay times. Jitter is a random amount of time added to retry periods that helps prevent \"thundering herd\" scenarios, which is when many tasks all retry at the exact same time, potentially overwhelming systems.</p> <p>The <code>retry_jitter_factor</code> option can be used to add variance to the base delay. For example, a retry delay of 10 seconds with a <code>retry_jitter_factor</code> of 0.5 will be allowed to delay up to 15 seconds. Large values of <code>retry_jitter_factor</code> provide more protection against \"thundering herds,\" while keeping the average retry delay time constant. For example, the following task adds jitter to its exponential backoff so the retry delays will vary up to a maximum delay time of 20, 40, and 80 seconds respectively.</p> <pre><code>from prefect import task\nfrom prefect.tasks import exponential_backoff\n\n@task(\n    retries=3,\n    retry_delay_seconds=exponential_backoff(backoff_factor=10),\n    retry_jitter_factor=1,\n)\ndef some_task_with_exponential_backoff_retries():\n   ...\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#configuring-retry-behavior-globally-with-settings","title":"Configuring retry behavior globally with settings","text":"<p>You can also set retries and retry delays by using the following global settings. These settings will not override the <code>retries</code> or <code>retry_delay_seconds</code> that are set in the flow or task decorator.</p> <pre><code>prefect config set PREFECT_FLOW_DEFAULT_RETRIES=2\nprefect config set PREFECT_TASK_DEFAULT_RETRIES=2\nprefect config set PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS = [1, 10, 100]\nprefect config set PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS = [1, 10, 100]\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#caching","title":"Caching","text":"<p>Caching refers to the ability of a task run to reflect a finished state without actually running the code that defines the task. This allows you to efficiently reuse results of tasks that may be expensive to run with every flow run, or reuse cached results if the inputs to a task have not changed.</p> <p>To determine whether a task run should retrieve a cached state, we use \"cache keys\". A cache key is a string value that indicates if one run should be considered identical to another. When a task run with a cache key finishes, we attach that cache key to the state. When each task run starts, Prefect checks for states with a matching cache key. If a state with an identical key is found, Prefect will use the cached state instead of running the task again.</p> <p>To enable caching, specify a <code>cache_key_fn</code> \u2014 a function that returns a cache key \u2014 on your task. You may optionally provide a <code>cache_expiration</code> timedelta indicating when the cache expires. If you do not specify a <code>cache_expiration</code>, the cache key does not expire.</p> <p>You can define a task that is cached based on its inputs by using the Prefect <code>task_input_hash</code>. This is a task cache key implementation that hashes all inputs to the task using a JSON or cloudpickle serializer. If the task inputs do not change, the cached results are used rather than running the task until the cache expires.</p> <p>Note that, if any arguments are not JSON serializable, the pickle serializer is used as a fallback. If cloudpickle fails, <code>task_input_hash</code> returns a null key indicating that a cache key could not be generated for the given inputs.</p> <p>In this example, until the <code>cache_expiration</code> time ends, as long as the input to <code>hello_task()</code> remains the same when it is called, the cached return value is returned. In this situation the task is not rerun. However, if the input argument value changes, <code>hello_task()</code> runs using the new input.</p> <pre><code>from datetime import timedelta\nfrom prefect import flow, task\nfrom prefect.tasks import task_input_hash\n\n@task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\ndef hello_task(name_input):\n    # Doing some work\n    print(\"Saying hello\")\n    return \"hello \" + name_input\n\n@flow(log_prints=True)\ndef hello_flow(name_input):\n    hello_task(name_input)\n</code></pre> <p>Alternatively, you can provide your own function or other callable that returns a string cache key. A generic <code>cache_key_fn</code> is a function that accepts two positional arguments:</p> <ul> <li>The first argument corresponds to the <code>TaskRunContext</code>, which stores task run metadata in the attributes <code>task_run_id</code>, <code>flow_run_id</code>, and <code>task</code>.</li> <li>The second argument corresponds to a dictionary of input values to the task. For example, if your task is defined with signature <code>fn(x, y, z)</code> then the dictionary will have keys <code>\"x\"</code>, <code>\"y\"</code>, and <code>\"z\"</code> with corresponding values that can be used to compute your cache key.</li> </ul> <p>Note that the <code>cache_key_fn</code> is not defined as a <code>@task</code>.</p> <p>Task cache keys</p> <p>By default, a task cache key is limited to 2000 characters, specified by the <code>PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH</code> setting.</p> <pre><code>from prefect import task, flow\n\ndef static_cache_key(context, parameters):\n    # return a constant\n    return \"static cache key\"\n\n@task(cache_key_fn=static_cache_key)\ndef cached_task():\n    print('running an expensive operation')\n    return 42\n\n@flow\ndef test_caching():\n    cached_task()\n    cached_task()\n    cached_task()\n</code></pre> <p>In this case, there's no expiration for the cache key, and no logic to change the cache key, so <code>cached_task()</code> only runs once.</p> <pre><code>&gt;&gt;&gt; test_caching()\nrunning an expensive operation\n&gt;&gt;&gt; test_caching()\n&gt;&gt;&gt; test_caching()\n</code></pre> <p>When each task run requested to enter a <code>Running</code> state, it provided its cache key computed from the <code>cache_key_fn</code>.  The Prefect backend identified that there was a COMPLETED state associated with this key and instructed the run to immediately enter the same COMPLETED state, including the same return values.  </p> <p>A real-world example might include the flow run ID from the context in the cache key so only repeated calls in the same flow run are cached.</p> <pre><code>def cache_within_flow_run(context, parameters):\n    return f\"{context.task_run.flow_run_id}-{task_input_hash(context, parameters)}\"\n\n@task(cache_key_fn=cache_within_flow_run)\ndef cached_task():\n    print('running an expensive operation')\n    return 42\n</code></pre> <p>Task results, retries, and caching</p> <p>Task results are cached in memory during a flow run and persisted to the location specified by the <code>PREFECT_LOCAL_STORAGE_PATH</code> setting. As a result, task caching between flow runs is currently limited to flow runs with access to that local storage path.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#refreshing-the-cache","title":"Refreshing the cache","text":"<p>Sometimes, you want a task to update the data associated with its cache key instead of using the cache. This is a cache \"refresh\".</p> <p>The <code>refresh_cache</code> option can be used to enable this behavior for a specific task:</p> <pre><code>import random\n\n\ndef static_cache_key(context, parameters):\n    # return a constant\n    return \"static cache key\"\n\n\n@task(cache_key_fn=static_cache_key, refresh_cache=True)\ndef caching_task():\n    return random.random()\n</code></pre> <p>When this task runs, it will always update the cache key instead of using the cached value. This is particularly useful when you have a flow that is responsible for updating the cache.</p> <p>If you want to refresh the cache for all tasks, you can use the <code>PREFECT_TASKS_REFRESH_CACHE</code> setting. Setting <code>PREFECT_TASKS_REFRESH_CACHE=true</code> will change the default behavior of all tasks to refresh. This is particularly useful if you want to rerun a flow without cached results.</p> <p>If you have tasks that should not refresh when this setting is enabled, you may explicitly set <code>refresh_cache</code> to <code>False</code>. These tasks will never refresh the cache \u2014 if a cache key exists it will be read, not updated. Note that, if a cache key does not exist yet, these tasks can still write to the cache.</p> <pre><code>@task(cache_key_fn=static_cache_key, refresh_cache=False)\ndef caching_task():\n    return random.random()\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#timeouts","title":"Timeouts","text":"<p>Task timeouts are used to prevent unintentional long-running tasks. When the duration of execution for a task exceeds the duration specified in the timeout, a timeout exception will be raised and the task will be marked as failed. In the UI, the task will be visibly designated as <code>TimedOut</code>. From the perspective of the flow, the timed-out task will be treated like any other failed task.</p> <p>Timeout durations are specified using the <code>timeout_seconds</code> keyword argument.</p> <pre><code>from prefect import task\nimport time\n\n@task(timeout_seconds=1, log_prints=True)\ndef show_timeouts():\n    print(\"I will execute\")\n    time.sleep(5)\n    print(\"I will not execute\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-results","title":"Task results","text":"<p>Depending on how you call tasks, they can return different types of results and optionally engage the use of a task runner.</p> <p>Any task can return:</p> <ul> <li>Data\u200a, such as <code>int</code>, <code>str</code>, <code>dict</code>, <code>list</code>, and so on \u2014 \u200athis is the default behavior any time you call <code>your_task()</code>.</li> <li><code>PrefectFuture</code> \u2014 \u200athis is achieved by calling <code>your_task.submit()</code>. A <code>PrefectFuture</code> contains both data and State</li> <li>Prefect <code>State</code> \u200a\u2014 anytime you call your task or flow with the argument <code>return_state=True</code>, it will directly return a state you can use to build custom behavior based on a state change you care about, such as task or flow failing or retrying.</li> </ul> <p>To run your task with a task runner, you must call the task with <code>.submit()</code>.</p> <p>See state returned values for examples.</p> <p>Task runners are optional</p> <p>If you just need the result from a task, you can simply call the task from your flow. For most workflows, the default behavior of calling a task directly and receiving a result is all you'll need.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#wait-for","title":"Wait for","text":"<p>To create a dependency between two tasks that do not exchange data, but one needs to wait for the other to finish, use the special <code>wait_for</code> keyword argument:</p> <pre><code>@task\ndef task_1():\n    pass\n\n@task\ndef task_2():\n    pass\n\n@flow\ndef my_flow():\n    x = task_1()\n\n    # task 2 will wait for task_1 to complete\n    y = task_2(wait_for=[x])\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#map","title":"Map","text":"<p>Prefect provides a <code>.map()</code> implementation that automatically creates a task run for each element of its input data. Mapped tasks represent the computations of many individual children tasks.</p> <p>The simplest Prefect map takes a tasks and applies it to each element of its inputs.</p> <pre><code>from prefect import flow, task\n\n@task\ndef print_nums(nums):\n    for n in nums:\n        print(n)\n\n@task\ndef square_num(num):\n    return num**2\n\n@flow\ndef map_flow(nums):\n    print_nums(nums)\n    squared_nums = square_num.map(nums) \n    print_nums(squared_nums)\n\nmap_flow([1,2,3,5,8,13])\n</code></pre> <p>Prefect also supports <code>unmapped</code> arguments, allowing you to pass static values that don't get mapped over.</p> <pre><code>from prefect import flow, task\n\n@task\ndef add_together(x, y):\n    return x + y\n\n@flow\ndef sum_it(numbers, static_value):\n    futures = add_together.map(numbers, static_value)\n    return futures\n\nsum_it([1, 2, 3], 5)\n</code></pre> <p>If your static argument is an iterable, you'll need to wrap it with <code>unmapped</code> to tell Prefect that it should be treated as a static value.</p> <pre><code>from prefect import flow, task, unmapped\n\n@task\ndef sum_plus(x, static_iterable):\n    return x + sum(static_iterable)\n\n@flow\ndef sum_it(numbers, static_iterable):\n    futures = sum_plus.map(numbers, static_iterable)\n    return futures\n\nsum_it([4, 5, 6], unmapped([1, 2, 3]))\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#async-tasks","title":"Async tasks","text":"<p>Prefect also supports asynchronous task and flow definitions by default. All of the standard rules of async apply:</p> <pre><code>import asyncio\n\nfrom prefect import task, flow\n\n@task\nasync def print_values(values):\n    for value in values:\n        await asyncio.sleep(1) # yield\n        print(value, end=\" \")\n\n@flow\nasync def async_flow():\n    await print_values([1, 2])  # runs immediately\n    coros = [print_values(\"abcd\"), print_values(\"6789\")]\n\n    # asynchronously gather the tasks\n    await asyncio.gather(*coros)\n\nasyncio.run(async_flow())\n</code></pre> <p>Note, if you are not using <code>asyncio.gather</code>, calling <code>.submit()</code> is required for asynchronous execution on the <code>ConcurrentTaskRunner</code>.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-run-concurrency-limits","title":"Task run concurrency limits","text":"<p>There are situations in which you want to actively prevent too many tasks from running simultaneously. For example, if many tasks across multiple flows are designed to interact with a database that only allows 10 connections, you want to make sure that no more than 10 tasks that connect to this database are running at any given time.</p> <p>Prefect has built-in functionality for achieving this: task concurrency limits.</p> <p>Task concurrency limits use task tags. You can specify an optional concurrency limit as the maximum number of concurrent task runs in a <code>Running</code> state for tasks with a given tag. The specified concurrency limit applies to any task to which the tag is applied.</p> <p>If a task has multiple tags, it will run only if all tags have available concurrency.</p> <p>Tags without explicit limits are considered to have unlimited concurrency.</p> <p>0 concurrency limit aborts task runs</p> <p>Currently, if the concurrency limit is set to 0 for a tag, any attempt to run a task with that tag will be aborted instead of delayed.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#execution-behavior","title":"Execution behavior","text":"<p>Task tag limits are checked whenever a task run attempts to enter a <code>Running</code> state.</p> <p>If there are no concurrency slots available for any one of your task's tags, the transition to a <code>Running</code> state will be delayed and the client is instructed to try entering a <code>Running</code> state again in 30 seconds (or the value specified by the <code>PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS</code> setting).</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#configuring-concurrency-limits","title":"Configuring concurrency limits","text":"<p>Flow run concurrency limits are set at a work pool and/or work queue level</p> <p>While task run concurrency limits are configured via tags (as shown below), flow run concurrency limits are configured via work pools and/or work queues.</p> <p>You can set concurrency limits on as few or as many tags as you wish. You can set limits through:</p> <ul> <li>Prefect CLI</li> <li>Prefect API by using <code>PrefectClient</code> Python client</li> <li>Prefect server UI or Prefect Cloud</li> </ul>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#cli","title":"CLI","text":"<p>You can create, list, and remove concurrency limits by using Prefect CLI <code>concurrency-limit</code> commands.</p> <pre><code>prefect concurrency-limit [command] [arguments]\n</code></pre> Command Description create Create a concurrency limit by specifying a tag and limit. delete Delete the concurrency limit set on the specified tag. inspect View details about a concurrency limit set on the specified tag. ls View all defined concurrency limits. <p>For example, to set a concurrency limit of 10 on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit create small_instance 10\n</code></pre> <p>To delete the concurrency limit on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit delete small_instance\n</code></pre> <p>To view details about the concurrency limit on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit inspect small_instance\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#python-client","title":"Python client","text":"<p>To update your tag concurrency limits programmatically, use <code>PrefectClient.orchestration.create_concurrency_limit</code>.</p> <p><code>create_concurrency_limit</code> takes two arguments:</p> <ul> <li><code>tag</code> specifies the task tag on which you're setting a limit.</li> <li><code>concurrency_limit</code> specifies the maximum number of concurrent task runs for that tag.</li> </ul> <p>For example, to set a concurrency limit of 10 on the 'small_instance' tag:</p> <pre><code>from prefect import get_client\n\nasync with get_client() as client:\n    # set a concurrency limit of 10 on the 'small_instance' tag\n    limit_id = await client.create_concurrency_limit(\n        tag=\"small_instance\", \n        concurrency_limit=10\n        )\n</code></pre> <p>To remove all concurrency limits on a tag, use <code>PrefectClient.delete_concurrency_limit_by_tag</code>, passing the tag:</p> <pre><code>async with get_client() as client:\n    # remove a concurrency limit on the 'small_instance' tag\n    await client.delete_concurrency_limit_by_tag(tag=\"small_instance\")\n</code></pre> <p>If you wish to query for the currently set limit on a tag, use <code>PrefectClient.read_concurrency_limit_by_tag</code>, passing the tag:</p> <p>To see all of your limits across all of your tags, use <code>PrefectClient.read_concurrency_limits</code>.</p> <pre><code>async with get_client() as client:\n    # query the concurrency limit on the 'small_instance' tag\n    limit = await client.read_concurrency_limit_by_tag(tag=\"small_instance\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/work-pools/","title":"Work Pools &amp;  Workers","text":"<p>Work pools and workers bridge the Prefect orchestration environment with your execution environment. When a deployment creates a flow run, it is submitted to a specific work pool for scheduling. A worker running in the execution environment can poll its respective work pool for new runs to execute, or the work pool can submit flow runs to serverless infrastructure directly, depending on your configuration.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-overview","title":"Work pool overview","text":"<p>Work pools organize work for execution. Work pools have types corresponding to the infrastructure that will execute the flow code, as well as the delivery method of work to that environment. Pull work pools require workers (or less ideally, agents) to poll the work pool for flow runs to execute. Push work pools can submit runs directly to your serverless infrastructure providers such as Google Cloud Run, Azure Container Instances, and AWS ECS without the need for an agent or worker. Managed work pools are administered by Prefect and handle the submission and execution of code on your behalf.</p> <p>Work pools are like pub/sub topics</p> <p>It's helpful to think of work pools as a way to coordinate (potentially many) deployments with (potentially many) workers through a known channel: the pool itself. This is similar to how \"topics\" are used to connect producers and consumers in a pub/sub or message-based system. By switching a deployment's work pool, users can quickly change the worker that will execute their runs, making it easy to promote runs through environments or even debug locally.</p> <p>In addition, users can control aspects of work pool behavior, such as how many runs the pool allows to be run concurrently or pausing delivery entirely. These options can be modified at any time, and any workers requesting work for a specific pool will only see matching flow runs.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-configuration","title":"Work pool configuration","text":"<p>You can configure work pools by using any of the following:</p> <ul> <li>Prefect UI</li> <li>Prefect CLI commands</li> <li>Prefect REST API</li> <li>Terraform provider for Prefect Cloud</li> </ul> <p>To manage work pools in the UI, click the Work Pools icon. This displays a list of currently configured work pools.</p> <p></p> <p>You can pause a work pool from this page by using the toggle.</p> <p>Select the + button to create a new work pool. You'll be able to specify the details for work served by this work pool.</p> <p>To create a work pool via the Prefect CLI, use the <code>prefect work-pool create</code> command:</p> <pre><code>prefect work-pool create [OPTIONS] NAME\n</code></pre> <p><code>NAME</code> is a required, unique name for the work pool.</p> <p>Optional configuration parameters you can specify to filter work on the pool include:</p> Option Description <code>--paused</code> If provided, the work pool will be created in a paused state. <code>--type</code> The type of infrastructure that can execute runs from this work pool. <code>--set-as-default</code> Whether to use the created work pool as the local default for deployment. <code>--base-job-template</code> The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. <p>For example, to create a work pool called <code>test-pool</code>, you would run this command:</p> <pre><code>prefect work-pool create test-pool\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-types","title":"Work pool types","text":"<p>If you don't use the <code>--type</code> flag to specify an infrastructure type, you are prompted to select from the following options:</p> Prefect CloudPrefect server instance Infrastructure Type Description Prefect Agent Execute flow runs on heterogeneous infrastructure using infrastructure blocks. Process Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started. AWS Elastic Container Service Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account. Azure Container Instances Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Docker Execute flow runs within Docker containers. Works well for managing flow execution environments via Docker images. Requires  access to a running Docker daemon. Google Cloud Run Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Google Cloud Run V2 Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account. Google Vertex AI Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account. Kubernetes Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster. Google Cloud Run - Push Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. AWS Elastic Container Service - Push Execute flow runs within containers on AWS ECS. Works with existing ECS clusters and serverless execution via AWS Fargate. Requires an AWS account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. Azure Container Instances - Push Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. Modal - Push Execute flow runs on Modal. Requires a Modal account. Flow runs are pushed directly to your Modal workspace, without the need for a Prefect worker. Prefect Managed Execute flow runs within containers on Prefect managed infrastructure. Infrastructure Type Description Prefect Agent Execute flow runs on heterogeneous infrastructure using infrastructure blocks. Process Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started. AWS Elastic Container Service Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account. Azure Container Instances Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Docker Execute flow runs within Docker containers. Works well for managing flow execution environments via Docker images. Requires access to a running Docker daemon. Google Cloud Run Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Google Cloud Run V2 Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account. Google Vertex AI Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account. Kubernetes Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster. <p>On success, the command returns the details of the newly created work pool.</p> <pre><code>Created work pool with properties:\n    name - 'test-pool'\n    id - a51adf8c-58bb-4949-abe6-1b87af46eabd\n    concurrency limit - None\n\nStart a worker to pick up flows from the work pool:\n    prefect worker start -p 'test-pool'\n\nInspect the work pool:\n    prefect work-pool inspect 'test-pool'\n</code></pre> <p>Set a work pool as the default for new deployments by adding the <code>--set-as-default</code> flag.</p> <p>Which would result in output similar to the following:</p> <pre><code>Set 'test-pool' as default work pool for profile 'default'\n\nTo change your default work pool, run:\n\n        prefect config set PREFECT_DEFAULT_WORK_POOL_NAME=&lt;work-pool-name&gt;\n</code></pre> <p>To update a work pool via the Prefect CLI, use the <code>prefect work-pool update</code> command:</p> <pre><code>prefect work-pool update [OPTIONS] NAME\n</code></pre> <p><code>NAME</code> is the name of the work pool to update.</p> <p>Optional configuration parameters you can specify to update the work pool include:</p> Option Description <code>--base-job-template</code> The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. <code>--description</code> A description of the work pool. <code>--concurrency-limit</code> The maximum number of flow runs to run simultaneously in the work pool. <p>Managing work pools in CI/CD</p> <p>You can version control your base job template by committing it as a JSON file to your repository and control updates to your work pools' base job templates by using the <code>prefect work-pool update</code> command in your CI/CD pipeline. For example, you could use the following command to update a work pool's base job template to the contents of a file named <code>base-job-template.json</code>:</p> <pre><code>prefect work-pool update --base-job-template base-job-template.json my-work-pool\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#base-job-template","title":"Base job template","text":"<p>Each work pool has a base job template that allows the customization of the behavior of the worker executing flow runs from the work pool.</p> <p>The base job template acts as a contract defining the configuration passed to the worker for each flow run and the options available to deployment creators to customize worker behavior per deployment.</p> <p>A base job template comprises a <code>job_configuration</code> section and a <code>variables</code> section.</p> <p>The <code>variables</code> section defines the fields available to be customized per deployment. The <code>variables</code> section follows the OpenAPI specification, which allows work pool creators to place limits on provided values (type, minimum, maximum, etc.).</p> <p>The job configuration section defines how values provided for fields in the variables section should be translated into the configuration given to a worker when executing a flow run.</p> <p>The values in the <code>job_configuration</code> can use placeholders to reference values provided in the <code>variables</code> section. Placeholders are declared using double curly braces, e.g., <code>{{ variable_name }}</code>. <code>job_configuration</code> values can also be hard-coded if the value should not be customizable.</p> <p>Each worker type is configured with a default base job template, making it easy to start with a work pool. The default base template defines values that will be passed to every flow run, but can be overridden on a per-deployment or per-flow run basis.</p> <p>For example, if we create a <code>process</code> work pool named 'above-ground' via the CLI:</p> <pre><code>prefect work-pool create --type process above-ground\n</code></pre> <p>We see these configuration options available in the Prefect UI: </p> <p>For a <code>process</code> work pool with the default base job template, we can set environment variables for spawned processes, set the working directory to execute flows, and control whether the flow run output is streamed to workers' standard output. You can also see an example of JSON formatted base job template with the 'Advanced' tab.</p> <p>You can examine the default base job template for a given worker type by running:</p> <pre><code>prefect work-pool get-default-base-job-template --type process\n</code></pre> <pre><code>{\n  \"job_configuration\": {\n    \"command\": \"{{ command }}\",\n    \"env\": \"{{ env }}\",\n    \"labels\": \"{{ labels }}\",\n    \"name\": \"{{ name }}\",\n    \"stream_output\": \"{{ stream_output }}\",\n    \"working_dir\": \"{{ working_dir }}\"\n  },\n  \"variables\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"name\": {\n        \"title\": \"Name\",\n        \"description\": \"Name given to infrastructure created by a worker.\",\n        \"type\": \"string\"\n      },\n      \"env\": {\n        \"title\": \"Environment Variables\",\n        \"description\": \"Environment variables to set when starting a flow run.\",\n        \"type\": \"object\",\n        \"additionalProperties\": {\n          \"type\": \"string\"\n        }\n      },\n      \"labels\": {\n        \"title\": \"Labels\",\n        \"description\": \"Labels applied to infrastructure created by a worker.\",\n        \"type\": \"object\",\n        \"additionalProperties\": {\n          \"type\": \"string\"\n        }\n      },\n      \"command\": {\n        \"title\": \"Command\",\n        \"description\": \"The command to use when starting a flow run. In most cases, this should be left blank and the command will be automatically generated by the worker.\",\n        \"type\": \"string\"\n      },\n      \"stream_output\": {\n        \"title\": \"Stream Output\",\n        \"description\": \"If enabled, workers will stream output from flow run processes to local standard output.\",\n        \"default\": true,\n        \"type\": \"boolean\"\n      },\n      \"working_dir\": {\n        \"title\": \"Working Directory\",\n        \"description\": \"If provided, workers will open flow run processes within the specified path as the working directory. Otherwise, a temporary directory will be created.\",\n        \"type\": \"string\",\n        \"format\": \"path\"\n      }\n    }\n  }\n}\n</code></pre> <p>You can override each of these attributes on a per-deployment or per-flow run basis. When creating a deployment, you can specify these overrides in the <code>deployments.work_pool.job_variables</code> section of a <code>prefect.yaml</code> file or in the <code>job_variables</code> argument of a Python <code>flow.deploy</code> method.</p> <p>For example, to turn off streaming output for a specific deployment, we could add the following to our <code>prefect.yaml</code>:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: above-ground  \n    job_variables:\n        stream_output: false\n</code></pre> <p>See more about overriding job variables in the Overriding Job Variables Guide.</p> <p>Advanced Customization of the Base Job Template</p> <p>For advanced use cases, you can create work pools with fully customizable job templates. This customization is available when creating or editing a work pool on the 'Advanced' tab within the UI or when updating a work pool via the Prefect CLI.</p> <p>Advanced customization is useful anytime the underlying infrastructure supports a high degree of customization. In these scenarios a work pool job template allows you to expose a minimal and easy-to-digest set of options to deployment authors.  Additionally, these options are the only customizable aspects for deployment infrastructure, which can be useful for restricting functionality in secure environments. For example, the <code>kubernetes</code> worker type allows users to specify a custom job template that can be used to configure the manifest that workers use to create jobs for flow execution.</p> <p>For more information and advanced configuration examples, see the Kubernetes Worker documentation.</p> <p>For more information on overriding a work pool's job variables see this guide.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#viewing-work-pools","title":"Viewing work pools","text":"<p>At any time, users can see and edit configured work pools in the Prefect UI.</p> <p></p> <p>To view work pools with the Prefect CLI, you can:</p> <ul> <li>List (<code>ls</code>) all available pools</li> <li>Inspect (<code>inspect</code>) the details of a single pool</li> <li>Preview (<code>preview</code>) scheduled work for a single pool</li> </ul> <p><code>prefect work-pool ls</code> lists all configured work pools for the server.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>For example:</p> <pre><code>                               Work pools\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name       \u2503    Type        \u2503                                   ID \u2503 Concurrency Limit \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 barbeque   \u2502 docker         \u2502 72c0a101-b3e2-4448-b5f8-a8c5184abd17 \u2502 None              \u2502\n\u2502 k8s-pool   \u2502 kubernetes     \u2502 7b6e3523-d35b-4882-84a7-7a107325bb3f \u2502 None              \u2502\n\u2502 test-pool  \u2502 prefect-agent  \u2502 a51adf8c-58bb-4949-abe6-1b87af46eabd \u2502 None              |\n| my-pool    \u2502 process        \u2502 cd6ff9e8-bfd8-43be-9be3-69375f7a11cd \u2502 None              \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                       (**) denotes a paused pool\n</code></pre> <p><code>prefect work-pool inspect</code> provides all configuration metadata for a specific work pool by ID.</p> <pre><code>prefect work-pool inspect 'test-pool'\n</code></pre> <p>Outputs information similar to the following:</p> <pre><code>Workpool(\n    id='a51adf8c-58bb-4949-abe6-1b87af46eabd',\n    created='2 minutes ago',\n    updated='2 minutes ago',\n    name='test-pool',\n    filter=None,\n)\n</code></pre> <p><code>prefect work-pool preview</code> displays scheduled flow runs for a specific work pool by ID for the upcoming hour. The optional <code>--hours</code> flag lets you specify the number of hours to look ahead.</p> <pre><code>prefect work-pool preview 'test-pool' --hours 12\n</code></pre> <pre><code>\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Scheduled Star\u2026 \u2503 Run ID                     \u2503 Name         \u2503 Deployment ID               \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 2022-02-26 06:\u2026 \u2502 741483d4-dc90-4913-b88d-0\u2026 \u2502 messy-petrel \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 05:\u2026 \u2502 14e23a19-a51b-4833-9322-5\u2026 \u2502 unselfish-g\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 04:\u2026 \u2502 deb44d4d-5fa2-4f70-a370-e\u2026 \u2502 solid-ostri\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 03:\u2026 \u2502 07374b5c-121f-4c8d-9105-b\u2026 \u2502 sophisticat\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 02:\u2026 \u2502 545bc975-b694-4ece-9def-8\u2026 \u2502 gorgeous-mo\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 01:\u2026 \u2502 704f2d67-9dfa-4fb8-9784-4\u2026 \u2502 sassy-hedge\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 00:\u2026 \u2502 691312f0-d142-4218-b617-a\u2026 \u2502 sincere-moo\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 23:\u2026 \u2502 7cb3ff96-606b-4d8c-8a33-4\u2026 \u2502 curious-cat\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 22:\u2026 \u2502 3ea559fe-cb34-43b0-8090-1\u2026 \u2502 primitive-f\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 21:\u2026 \u2502 96212e80-426d-4bf4-9c49-e\u2026 \u2502 phenomenal-\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                   (**) denotes a late run\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-status","title":"Work pool status","text":"<p>Work pools have three statuses: <code>READY</code>, <code>NOT_READY</code>, and <code>PAUSED</code>. A work pool is considered ready if it has at least one online worker sending heartbeats to the work pool. If a work pool has no online workers, it is considered not ready to execute work. A work pool can be placed in a paused status manually by a user or via an automation. When a paused work pool is unpaused, it will be reassigned the appropriate status based on whether any workers are sending heartbeats.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#pausing-and-deleting-work-pools","title":"Pausing and deleting work pools","text":"<p>A work pool can be paused at any time to stop the delivery of work to workers. Workers will not receive any work when polling a paused pool.</p> <p>To pause a work pool through the Prefect CLI, use the <code>prefect work-pool pause</code> command:</p> <pre><code>prefect work-pool pause 'test-pool'\n</code></pre> <p>To resume a work pool through the Prefect CLI, use the <code>prefect work-pool resume</code> command with the work pool name.</p> <p>To delete a work pool through the Prefect CLI, use the <code>prefect work-pool delete</code> command with the work pool name.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#managing-concurrency","title":"Managing concurrency","text":"<p>Each work pool can optionally restrict concurrent runs of matching flows.</p> <p>For example, a work pool with a concurrency limit of 5 will only release new work if fewer than 5 matching runs are currently in a <code>Running</code> or <code>Pending</code> state. If 3 runs are <code>Running</code> or <code>Pending</code>, polling the pool for work will only result in 2 new runs, even if there are many more available, to ensure that the concurrency limit is not exceeded.</p> <p>When using the <code>prefect work-pool</code> Prefect CLI command to configure a work pool, the following subcommands set concurrency limits:</p> <ul> <li><code>set-concurrency-limit</code>  sets a concurrency limit on a work pool.</li> <li><code>clear-concurrency-limit</code> clears any concurrency limits from a work pool.</li> </ul>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-queues","title":"Work queues","text":"<p>Advanced topic</p> <p>Prefect will automatically create a default work queue if needed.</p> <p>Work queues offer advanced control over how runs are executed. Each work pool has a \"default\" queue that all work will be sent to by default. Additional queues can be added to a work pool to enable greater control over work delivery through fine grained priority and concurrency. Each work queue has a priority indicated by a unique positive integer. Lower numbers take greater priority in the allocation of work. Accordingly, new queues can be added without changing the rank of the higher-priority queues (e.g. no matter how many queues you add, the queue with priority <code>1</code> will always be the highest priority).</p> <p>Work queues can also have their own concurrency limits. Note that each queue is also subject to the global work pool concurrency limit, which cannot be exceeded.</p> <p>Together work queue priority and concurrency enable precise control over work. For example, a pool may have three queues: A \"low\" queue with priority <code>10</code> and no concurrency limit, a \"high\" queue with priority <code>5</code> and a concurrency limit of <code>3</code>, and a \"critical\" queue with priority <code>1</code> and a concurrency limit of <code>1</code>. This arrangement would enable a pattern in which there are two levels of priority, \"high\" and \"low\" for regularly scheduled flow runs, with the remaining \"critical\" queue for unplanned, urgent work, such as a backfill.</p> <p>Priority is evaluated to determine the order in which flow runs are submitted for execution. If all flow runs are capable of being executed with no limitation due to concurrency or otherwise, priority is still used to determine order of submission, but there is no impact to execution. If not all flow runs can be executed, usually as a result of concurrency limits, priority is used to determine which queues receive precedence to submit runs for execution.</p> <p>Priority for flow run submission proceeds from the highest priority to the lowest priority. In the preceding example, all work from the \"critical\" queue (priority 1) will be submitted, before any work is submitted from \"high\" (priority 5). Once all work has been submitted from priority queue \"critical\", work from the \"high\" queue will begin submission.</p> <p>If new flow runs are received on the \"critical\" queue while flow runs are still in scheduled on the \"high\" and \"low\" queues, flow run submission goes back to ensuring all scheduled work is first satisfied from the highest priority queue, until it is empty, in waterfall fashion.</p> <p>Work queue status</p> <p>A work queue has a <code>READY</code> status when it has been polled by a worker in the last 60 seconds. Pausing a work queue will give it a <code>PAUSED</code> status and mean that it will accept no new work until it is unpaused. A user can control the work queue's paused status in the UI. Unpausing a work queue will give the work queue a <code>NOT_READY</code> status unless a worker has polled it in the last 60 seconds.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#local-debugging","title":"Local debugging","text":"<p>As long as your deployment's infrastructure block supports it, you can use work pools to temporarily send runs to a worker running on your local machine for debugging by running <code>prefect worker start -p my-local-machine</code> and updating the deployment's work pool to <code>my-local-machine</code>.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-overview","title":"Worker overview","text":"<p>Workers are lightweight polling services that retrieve scheduled runs from a work pool and execute them.</p> <p>Workers are similar to agents, but offer greater control over infrastructure configuration and the ability to route work to specific types of execution environments.</p> <p>Workers each have a type corresponding to the execution environment to which they will submit flow runs. Workers are only able to poll work pools that match their type. As a result, when deployments are assigned to a work pool, you know in which execution environment scheduled flow runs for that deployment will run.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-types","title":"Worker types","text":"<p>Below is a list of available worker types. Note that most worker types will require installation of an additional package.</p> Worker Type Description Required Package <code>process</code> Executes flow runs in subprocesses <code>kubernetes</code> Executes flow runs as Kubernetes jobs <code>prefect-kubernetes</code> <code>docker</code> Executes flow runs within Docker containers <code>prefect-docker</code> <code>ecs</code> Executes flow runs as ECS tasks <code>prefect-aws</code> <code>cloud-run</code> Executes flow runs as Google Cloud Run jobs <code>prefect-gcp</code> <code>vertex-ai</code> Executes flow runs as Google Cloud Vertex AI jobs <code>prefect-gcp</code> <code>azure-container-instance</code> Execute flow runs in ACI containers <code>prefect-azure</code> <p>If you don\u2019t see a worker type that meets your needs, consider developing a new worker type!</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-options","title":"Worker options","text":"<p>Workers poll for work from one or more queues within a work pool. If the worker references a work queue that doesn't exist, it will be created automatically. The worker CLI is able to infer the worker type from the work pool. Alternatively, you can also specify the worker type explicitly. If you supply the worker type to the worker CLI, a work pool will be created automatically if it doesn't exist (using default job settings).</p> <p>Configuration parameters you can specify when starting a worker include:</p> Option Description <code>--name</code>, <code>-n</code> The name to give to the started worker. If not provided, a unique name will be generated. <code>--pool</code>, <code>-p</code> The work pool the started worker should poll. <code>--work-queue</code>, <code>-q</code> One or more work queue names for the worker to pull from. If not provided, the worker will pull from all work queues in the work pool. <code>--type</code>, <code>-t</code> The type of worker to start. If not provided, the worker type will be inferred from the work pool. <code>--prefetch-seconds</code> The amount of time before a flow run's scheduled start time to begin submission. Default is the value of <code>PREFECT_WORKER_PREFETCH_SECONDS</code>. <code>--run-once</code> Only run worker polling once. By default, the worker runs forever. <code>--limit</code>, <code>-l</code> The maximum number of flow runs to start simultaneously. <code>--with-healthcheck</code> Start a healthcheck server for the worker. <code>--install-policy</code> Install policy to use workers from Prefect integration packages. <p>You must start a worker within an environment that can access or create the infrastructure needed to execute flow runs. The worker will deploy flow runs to the infrastructure corresponding to the worker type. For example, if you start a worker with type <code>kubernetes</code>, the worker will deploy flow runs to a Kubernetes cluster.</p> <p>Prefect must be installed in execution environments</p> <p>Prefect must be installed in any environment (virtual environment, Docker container, etc.) where you intend to run the worker or execute a flow run.</p> <p><code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code>settings for workers</p> <p><code>PREFECT_API_URL</code> must be set for the environment in which your worker is running. You must also have a user or service account with the <code>Worker</code> role, which can be configured by setting the <code>PREFECT_API_KEY</code>.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-status","title":"Worker status","text":"<p>Workers have two statuses: <code>ONLINE</code> and <code>OFFLINE</code>. A worker is online if it sends regular heartbeat messages to the Prefect API. If a worker has missed three heartbeats, it is considered offline. By default, a worker is considered offline a maximum of 90 seconds after it stopped sending heartbeats, but the threshold can be configured via the <code>PREFECT_WORKER_HEARTBEAT_SECONDS</code> setting.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#starting-a-worker","title":"Starting a worker","text":"<p>Use the <code>prefect worker start</code> CLI command to start a worker. You must pass at least the work pool name. If the work pool does not exist, it will be created if the <code>--type</code> flag is used.</p> <pre><code>prefect worker start -p [work pool name]\n</code></pre> <p>For example:</p> <pre><code>prefect worker start -p \"my-pool\"\n</code></pre> <p>Results in output like this:</p> <pre><code>Discovered worker type 'process' for work pool 'my-pool'.\nWorker 'ProcessWorker 65716280-96f8-420b-9300-7e94417f2673' started!\n</code></pre> <p>In this case, Prefect automatically discovered the worker type from the work pool. To create a work pool and start a worker in one command, use the <code>--type</code> flag:</p> <pre><code>prefect worker start -p \"my-pool\" --type \"process\"\n</code></pre> <pre><code>Worker 'ProcessWorker d24f3768-62a9-4141-9480-a056b9539a25' started!\n06:57:53.289 | INFO    | prefect.worker.process.processworker d24f3768-62a9-4141-9480-a056b9539a25 - Worker pool 'my-pool' created.\n</code></pre> <p>In addition, workers can limit the number of flow runs they will start simultaneously with the <code>--limit</code> flag. For example, to limit a worker to five concurrent flow runs:</p> <pre><code>prefect worker start --pool \"my-pool\" --limit 5\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#configuring-prefetch","title":"Configuring prefetch","text":"<p>By default, the worker begins submitting flow runs a short time (10 seconds) before they are scheduled to run. This behavior allows time for the infrastructure to be created so that the flow run can start on time.</p> <p>In some cases, infrastructure will take longer than 10 seconds to start the flow run. The prefetch can be increased using the <code>--prefetch-seconds</code> option or the <code>PREFECT_WORKER_PREFETCH_SECONDS</code> setting.</p> <p>If this value is more than the amount of time it takes for the infrastructure to start, the flow run will wait until its scheduled start time.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#polling-for-work","title":"Polling for work","text":"<p>Workers poll for work every 15 seconds by default. This interval is configurable in your profile settings with the <code>PREFECT_WORKER_QUERY_SECONDS</code> setting.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#install-policy","title":"Install policy","text":"<p>The Prefect CLI can install the required package for Prefect-maintained worker types automatically. You can configure this behavior with the <code>--install-policy</code> option. The following are valid install policies</p> Install Policy Description <code>always</code> Always install the required package. Will update the required package to the most recent version if already installed. <code>if-not-present</code> Install the required package if it is not already installed. <code>never</code> Never install the required package. <code>prompt</code> Prompt the user to choose whether to install the required package. This is the default install policy. If <code>prefect worker start</code> is run non-interactively, the <code>prompt</code> install policy will behave the same as <code>never</code>.","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#additional-resources","title":"Additional resources","text":"<p>See how to daemonize a Prefect worker in this guide.</p> <p>For more information on overriding a work pool's job variables see this guide.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"contributing/overview/","title":"Contributing","text":"<p>Thanks for considering contributing to Prefect!</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#setting-up-a-development-environment","title":"Setting up a development environment","text":"<p>First, download the source code and install an editable version of the Python package:</p> <pre><code># Clone the repository\ngit clone https://github.com/PrefectHQ/prefect.git\ncd prefect\n\n# We recommend using a virtual environment\n\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install the package with development dependencies\n\npip install -e \".[dev]\"\n\n# Setup pre-commit hooks for required formatting\n\npre-commit install\n</code></pre> <p>If you don't want to install the pre-commit hooks, you can manually install the formatting dependencies with:</p> <pre><code>pip install $(./scripts/precommit-versions.py)\n</code></pre> <p>You'll need to run <code>black</code> and  <code>ruff</code> before a contribution can be accepted.</p> <p>After installation, you can run the test suite with <code>pytest</code>:</p> <pre><code># Run all the tests\npytest tests\n\n# Run a subset of tests\n\npytest tests/test_flows.py\n</code></pre> <p>Building the Prefect UI</p> <p>If you intend to run a local Prefect server during development, you must first build the UI. See UI development for instructions.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#prefect-code-of-conduct","title":"Prefect Code of Conduct","text":"","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or   advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic   address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#scope","title":"Scope","text":"<p>This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Chris White at chris@prefect.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#developer-tooling","title":"Developer tooling","text":"<p>The Prefect CLI provides several helpful commands to aid development.</p> <p>Start all services with hot-reloading on code changes (requires UI dependencies to be installed):</p> <pre><code>prefect dev start\n</code></pre> <p>Start a Prefect API that reloads on code changes:</p> <pre><code>prefect dev api\n</code></pre> <p>Start a Prefect worker that reloads on code changes:</p> <pre><code>prefect dev agent\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#ui-development","title":"UI development","text":"<p>Developing the Prefect UI requires that npm is installed.</p> <p>Start a development UI that reloads on code changes:</p> <pre><code>prefect dev ui\n</code></pre> <p>Build the static UI (the UI served by <code>prefect server start</code>):</p> <pre><code>prefect dev build-ui\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#docs-development","title":"Docs Development","text":"<p>Prefect uses mkdocs for the docs website and the mkdocs-material theme. While we use <code>mkdocs-material-insiders</code> for production, builds can still happen without the extra plugins. Deploy previews are available on pull requests, so you'll be able to browse the final look of your changes before merging.</p> <p>To build the docs:</p> <pre><code>mkdocs build\n</code></pre> <p>To serve the docs locally at http://127.0.0.1:8000/:</p> <pre><code>mkdocs serve\n</code></pre> <p>For additional mkdocs help and options:</p> <pre><code>mkdocs --help\n</code></pre> <p>We use the mkdocs-material theme. To add additional JavaScript or CSS to the docs, please see the theme documentation here.</p> <p>Internal developers can install the production theme by running:</p> <pre><code>pip install -e git+https://github.com/PrefectHQ/mkdocs-material-insiders.git#egg=mkdocs-material\nmkdocs build # or mkdocs build --config-file mkdocs.insiders.yml if needed\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#kubernetes-development","title":"Kubernetes development","text":"<p>Generate a manifest to deploy a development API to a local kubernetes cluster:</p> <pre><code>prefect dev kubernetes-manifest\n</code></pre> <p>To access the Prefect UI running in a Kubernetes cluster, use the <code>kubectl port-forward</code> command to forward a port on your local machine to an open port within the cluster. For example:</p> <pre><code>kubectl port-forward deployment/prefect-dev 4200:4200\n</code></pre> <p>This forwards port 4200 on the default internal loop IP for localhost to the Prefect server deployment.</p> <p>To tell the local <code>prefect</code> command how to communicate with the Prefect API running in Kubernetes, set the <code>PREFECT_API_URL</code> environment variable:</p> <pre><code>export PREFECT_API_URL=http://localhost:4200/api\n</code></pre> <p>Since you previously configured port forwarding for the localhost port to the Kubernetes environment, you\u2019ll be able to interact with the Prefect API running in Kubernetes when using local Prefect CLI commands.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#adding-database-migrations","title":"Adding database migrations","text":"<p>To make changes to a table, first update the SQLAlchemy model in <code>src/prefect/server/database/orm_models.py</code>. For example, if you wanted to add a new column to the <code>flow_run</code> table, you would add a new column to the <code>FlowRun</code> model:</p> <pre><code># src/prefect/server/database/orm_models.py\n\n@declarative_mixin\nclass ORMFlowRun(ORMRun):\n    \"\"\"SQLAlchemy model of a flow run.\"\"\"\n    ...\n    new_column = Column(String, nullable=True) # &lt;-- add this line\n</code></pre> <p>Next, you will need to generate new migration files. You must generate a new migration file for each database type. Migrations will be generated for whatever database type <code>PREFECT_API_DATABASE_CONNECTION_URL</code> is set to. See here for how to set the database connection URL for each database type.</p> <p>To generate a new migration file, run the following command:</p> <pre><code>prefect server database revision --autogenerate -m \"&lt;migration name&gt;\"\n</code></pre> <p>Try to make your migration name brief but descriptive. For example:</p> <ul> <li><code>add_flow_run_new_column</code></li> <li><code>add_flow_run_new_column_idx</code></li> <li><code>rename_flow_run_old_column_to_new_column</code></li> </ul> <p>The <code>--autogenerate</code> flag will automatically generate a migration file based on the changes to the models.</p> <p>Always inspect the output of <code>--autogenerate</code></p> <p><code>--autogenerate</code> will generate a migration file based on the changes to the models. However, it is not perfect. Be sure to check the file to make sure it only includes the changes you want to make. Additionally, you may need to remove extra statements that were included and not related to your change.</p> <p>The new migration can be found in the <code>src/prefect/server/database/migrations/versions/</code> directory. Each database type has its own subdirectory. For example, the SQLite migrations are stored in <code>src/prefect/server/database/migrations/versions/sqlite/</code>.</p> <p>After you have inspected the migration file, you can apply the migration to your database by running the following command:</p> <pre><code>prefect server database upgrade -y\n</code></pre> <p>Once you have successfully created and applied migrations for all database types, make sure to update <code>MIGRATION-NOTES.md</code> to document your additions.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/style/","title":"Code style and practices","text":"<p>Generally, we follow the Google Python Style Guide. This document covers sections where we differ or where additional clarification is necessary.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports","title":"Imports","text":"<p>A brief collection of rules and guidelines for how imports should be handled in this repository.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports-in-__init__-files","title":"Imports in <code>__init__</code> files","text":"<p>Leave <code>__init__</code> files empty unless exposing an interface. If you must expose objects to present a simpler API, please follow these rules.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#exposing-objects-from-submodules","title":"Exposing objects from submodules","text":"<p>If importing objects from submodules, the <code>__init__</code> file should use a relative import. This is required for type checkers to understand the exposed interface.</p> <pre><code># Correct\nfrom .flows import flow\n</code></pre> <pre><code># Wrong\nfrom prefect.flows import flow\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#exposing-submodules","title":"Exposing submodules","text":"<p>Generally, submodules should not be imported in the <code>__init__</code> file. Submodules should only be exposed when the module is designed to be imported and used as a namespaced object.</p> <p>For example, we do this for our schema and model modules because it is important to know if you are working with an API schema or database model, both of which may have similar names.</p> <pre><code>import prefect.server.schemas as schemas\n\n# The full module is accessible now\nschemas.core.FlowRun\n</code></pre> <p>If exposing a submodule, use a relative import as you would when exposing an object.</p> <pre><code># Correct\nfrom . import flows\n</code></pre> <pre><code># Wrong\nimport prefect.flows\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-to-run-side-effects","title":"Importing to run side-effects","text":"<p>Another use case for importing submodules is perform global side-effects that occur when they are imported.</p> <p>Often, global side-effects on import are a dangerous pattern. Avoid them if feasible.</p> <p>We have a couple acceptable use-cases for this currently:</p> <ul> <li>To register dispatchable types, e.g. <code>prefect.serializers</code>.</li> <li>To extend a CLI application e.g. <code>prefect.cli</code>.</li> </ul>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports-in-modules","title":"Imports in modules","text":"","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-other-modules","title":"Importing other modules","text":"<p>The <code>from</code> syntax should be reserved for importing objects from modules. Modules should not be imported using the <code>from</code> syntax.</p> <pre><code># Correct\nimport prefect.server.schemas  # use with the full name\nimport prefect.server.schemas as schemas  # use the shorter name\n</code></pre> <pre><code># Wrong\nfrom prefect.server import schemas\n</code></pre> <p>Unless in an <code>__init__.py</code> file, relative imports should not be used.</p> <pre><code># Correct\nfrom prefect.utilities.foo import bar\n</code></pre> <pre><code># Wrong\nfrom .utilities.foo import bar\n</code></pre> <p>Imports dependent on file location should never be used without explicit indication it is relative. This avoids confusion about the source of a module.</p> <pre><code># Correct\nfrom . import test\n</code></pre> <pre><code># Wrong\nimport test\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#resolving-circular-dependencies","title":"Resolving circular dependencies","text":"<p>Sometimes, we must defer an import and perform it within a function to avoid a circular dependency.</p> <pre><code>## This function in `settings.py` requires a method from the global `context` but the context\n## uses settings\ndef from_context():\n    from prefect.context import get_profile_context\n\n    ...\n</code></pre> <p>Attempt to avoid circular dependencies. This often reveals overentanglement in the design.</p> <p>When performing deferred imports, they should all be placed at the top of the function.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#with-type-annotations","title":"With type annotations","text":"<p>If you are just using the imported object for a type signature, you should use the <code>TYPE_CHECKING</code> flag.</p> <pre><code># Correct\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from prefect.server.schemas.states import State\n\ndef foo(state: \"State\"):\n    pass\n</code></pre> <p>Note that usage of the type within the module will need quotes e.g. <code>\"State\"</code> since it is not available at runtime.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-optional-requirements","title":"Importing optional requirements","text":"<p>We do not have a best practice for this yet. See the <code>kubernetes</code>, <code>docker</code>, and <code>distributed</code> implementations for now.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#delaying-expensive-imports","title":"Delaying expensive imports","text":"<p>Sometimes, imports are slow. We'd like to keep the <code>prefect</code> module import times fast. In these cases, we can lazily import the slow module by deferring import to the relevant function body. For modules that are consumed by many functions, the pattern used for optional requirements may be used instead.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#command-line-interface-cli-output-messages","title":"Command line interface (CLI) output messages","text":"<p>Upon executing a command that creates an object, the output message should offer: - A short description of what the command just did. - A bullet point list, rehashing user inputs, if possible. - Next steps, like the next command to run, if applicable. - Other relevant, pre-formatted commands that can be copied and pasted, if applicable. - A new line before the first line and after the last line.</p> <p>Output Example: <pre><code>$ prefect work-queue create testing\n\nCreated work queue with properties:\n    name - 'abcde'\n    uuid - 940f9828-c820-4148-9526-ea8107082bda\n    tags - None\n    deployment_ids - None\n\nStart an agent to pick up flows from the created work queue:\n    prefect agent start -q 'abcde'\n\nInspect the created work queue:\n    prefect work-queue inspect 'abcde'\n</code></pre></p> <p>Additionally:</p> <ul> <li>Wrap generated arguments in apostrophes (') to ensure validity by using suffixing formats with <code>!r</code>.</li> <li>Indent example commands, instead of wrapping in backticks (`).</li> <li>Use placeholders if the example cannot be pre-formatted completely.</li> <li>Capitalize placeholder labels and wrap them in less than (&lt;) and greater than (&gt;) signs.</li> <li>Utilize <code>textwrap.dedent</code> to remove extraneous spacing for strings that are written with triple quotes (\"\"\").</li> </ul> <p>Placeholder Example: <pre><code>Create a work queue with tags:\n    prefect work-queue create '&lt;WORK QUEUE NAME&gt;' -t '&lt;OPTIONAL TAG 1&gt;' -t '&lt;OPTIONAL TAG 2&gt;'\n</code></pre></p> <p>Dedent Example: <pre><code>from textwrap import dedent\n...\noutput_msg = dedent(\n    f\"\"\"\n    Created work queue with properties:\n        name - {name!r}\n        uuid - {result}\n        tags - {tags or None}\n        deployment_ids - {deployment_ids or None}\n\n    Start an agent to pick up flows from the created work queue:\n        prefect agent start -q {name!r}\n\n    Inspect the created work queue:\n        prefect work-queue inspect {name!r}\n    \"\"\"\n)\n</code></pre></p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#api-versioning","title":"API Versioning","text":"<p>The Prefect client can be run separately from the Prefect orchestration server and communicate entirely via an API. Among other things, the Prefect client includes anything that runs task or flow code, (e.g. agents, and the Python client) or any consumer of Prefect metadata, (e.g. the Prefect UI, and CLI). The Prefect server stores this metadata and serves it via the REST API.</p> <p>Sometimes, we make breaking changes to the API (for good reasons). In order to check that a Prefect client is compatible with the API it's making requests to, every API call the client makes includes a three-component <code>API_VERSION</code> header with major, minor, and patch versions.</p> <p>For example, a request with the <code>X-PREFECT-API-VERSION=3.2.1</code> header has a major version of <code>3</code>, minor version <code>2</code>, and patch version <code>1</code>.</p> <p>This version header can be changed by modifying the <code>API_VERSION</code> constant in <code>prefect.server.api.server</code>.</p> <p>When making a breaking change to the API, we should consider if the change might be backwards compatible for clients, meaning that the previous version of the client would still be able to make calls against the updated version of the server code. This might happen if the changes are purely additive: such as adding a non-critical API route. In these cases, we should make sure to bump the patch version.</p> <p>In almost all other cases, we should bump the minor version, which denotes a non-backwards-compatible API change. We have reserved the major version chanes to denote also-backwards compatible change that might be significant in some way, such as a major release milestone.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/versioning/","title":"Versioning","text":"","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#understanding-version-numbers","title":"Understanding version numbers","text":"<p>Versions are composed of three parts: MAJOR.MINOR.PATCH. For example, the version 2.5.0 has a major version of 2, a minor version of 5, and patch version of 0.</p> <p>Occasionally, we will add a suffix to the version such as <code>rc</code>, <code>a</code>, or <code>b</code>. These indicate pre-release versions that users can opt-into installing to test functionality before it is ready for release.</p> <p>Each release will increase one of the version numbers. If we increase a number other than the patch version, the versions to the right of it will be reset to zero.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#prefects-versioning-scheme","title":"Prefect's versioning scheme","text":"<p>Prefect will increase the major version when significant and widespread changes are made to the core product. It is very unlikely that the major version will change without extensive warning.</p> <p>Prefect will increase the minor version when:</p> <ul> <li>Introducing a new concept that changes how Prefect can be used</li> <li>Changing an existing concept in a way that fundamentally alters how it is used</li> <li>Removing a deprecated feature</li> </ul> <p>Prefect will increase the patch version when:</p> <ul> <li>Making enhancements to existing features</li> <li>Fixing behavior in existing features</li> <li>Adding new functionality to existing concepts</li> <li>Updating dependencies</li> </ul>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#breaking-changes-and-deprecation","title":"Breaking changes and deprecation","text":"<p>A breaking change means that your code will need to change to use a new version of Prefect. We strive to avoid breaking changes in all releases.</p> <p>At times, Prefect will deprecate a feature. This means that a feature has been marked for removal in the future. When you use it, you may see warnings that it will be removed. A feature is deprecated when it will no longer be maintained. Frequently, a deprecated feature will have a new and improved alternative. Deprecated features will be retained for at least 3 minor version increases or 6 months, whichever is longer. We may retain deprecated features longer than this time period.</p> <p>Prefect will sometimes include changes to behavior to fix a bug. These changes are not categorized as breaking changes.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#client-compatibility-with-prefect","title":"Client compatibility with Prefect","text":"<p>When running a Prefect server, you are in charge of ensuring the version is compatible with those of the clients that are using the server. Prefect aims to maintain backwards compatibility with old clients for each server release. In contrast, sometimes new clients cannot be used with an old server. The new client may expect the server to support functionality that it does not yet include. For this reason, we recommend that all clients are the same version as the server or older.</p> <p>For example, a client on 2.1.0 can be used with a server on 2.5.0. A client on 2.5.0 cannot be used with a server on 2.1.0.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#client-compatibility-with-cloud","title":"Client compatibility with Cloud","text":"<p>Prefect Cloud targets compatibility with all versions of Prefect clients. If you encounter a compatibility issue, please file a bug report.</p>","tags":["versioning","semver"],"boost":2},{"location":"getting-started/installation/","title":"Installation","text":"<p>Prefect requires Python 3.8 or newer.</p> <p> </p> <p>We recommend installing Prefect using a Python virtual environment manager such as <code>pipenv</code>, <code>conda</code>, or <code>virtualenv</code>/<code>venv</code>.</p> <p>You can use Prefect Cloud as your API server or host your own Prefect server instance backed by PostgreSQL. For development, you can use SQLite 2.24 or newer as your database.</p> <p>Prefect Cloud is a managed solution that provides strong scaling, performance, and security. Learn more about Prefect Cloud solutions for enterprises here.</p> <p>Windows and Linux requirements</p> <p>See Windows installation notes and Linux installation notes for details on additional installation requirements and considerations.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#install-prefect","title":"Install Prefect","text":"<p>The following sections describe how to install Prefect in your environment.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#installing-the-latest-version","title":"Installing the latest version","text":"<p>Prefect is published as a Python package. To install the latest release or upgrade an existing Prefect install, and upgrade existing Python dependencies, run the following command in your terminal:</p> <pre><code>pip install -U prefect\n</code></pre> <p>To install a specific Prefect version, specify the version number like this:</p> <pre><code>pip install -U \"prefect==2.17.1\"\n</code></pre> <p>See available release versions in the Prefect Release Notes.</p> <p>See our Contributing guide for instructions on installing Prefect for development and see the section below to install directly from the <code>main</code> branch.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#checking-your-installation","title":"Checking your installation","text":"<p>To confirm that Prefect was installed correctly, run the command <code>prefect version</code> in your terminal.</p> <pre><code>prefect version\n</code></pre> <p>You should see output similar to the following:</p> <pre><code>Version:             2.17.1\nAPI version:         0.8.4\nPython version:      3.12.2\nGit commit:          d6bdb075\nBuilt:               Thu, Apr 11, 2024 6:58 PM\nOS/Arch:             darwin/arm64\nProfile:              local\nServer type:         ephemeral\nServer:\n  Database:          sqlite\n  SQLite version:    3.45.2\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#windows-installation-notes","title":"Windows installation notes","text":"<p>You can install and run Prefect via Windows PowerShell, the Windows Command Prompt, or <code>conda</code>. After installation, you may need to manually add the Python local packages <code>Scripts</code> folder to your <code>Path</code> environment variable.</p> <p>The <code>Scripts</code> folder path looks something like this (the username and Python version may be different on your system):</p> <pre><code>C:\\Users\\MyUserNameHere\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python311\\Scripts\n</code></pre> <p>Watch the <code>pip install</code> output messages for the <code>Scripts</code> folder path on your system.</p> <p>If you're using Windows Subsystem for Linux (WSL), see Linux installation notes.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#linux-installation-notes","title":"Linux installation notes","text":"<p>Linux is a popular operating system for running Prefect. If you are hosting your own Prefect server instance with a SQLite database, note that certain Linux versions of SQLite can be problematic. Compatible versions include Ubuntu 22.04 LTS and Ubuntu 20.04 LTS.</p> <p>Alternatively, you can install SQLite on Red Hat Custom Linux (RHEL) or use the <code>conda</code> virtual environment manager and configure a compatible SQLite version.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#using-a-self-signed-ssl-certificate","title":"Using a self-signed SSL certificate","text":"<p>If you're using a self-signed SSL certificate, you need to configure your environment to trust the certificate. You can add the certificate to your system bundle and pointing your tools to use that bundle by configuring the <code>SSL_CERT_FILE</code> environment variable.</p> <p>If the certificate is not part of your system bundle, you can set the <code>PREFECT_API_TLS_INSECURE_SKIP_VERIFY</code> to <code>True</code> to disable certificate verification altogether.</p> <p>Note: Disabling certificate validation is insecure and only suggested as an option for testing!</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#proxies","title":"Proxies","text":"<p>Prefect supports communicating via proxies through environment variables. Whether you are using Prefect Cloud or hosting your own Prefect server instance, set <code>HTTPS_PROXY</code> and <code>SSL_CERT_FILE</code> in your environment, and the underlying network libraries will route Prefect\u2019s requests appropriately.</p> <p>Alternatively, the Prefect library will connect to the API via any proxies you have listed in the <code>HTTP_PROXY</code> or <code>ALL_PROXY</code> environment variables. You may also use the <code>NO_PROXY</code> environment variable to specify which hosts should not be sent through the proxy.</p> <p>For more information about these environment variables, see the cURL documentation.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#prefect-client-library","title":"<code>prefect-client</code> library","text":"<p>The <code>prefect-client</code> library is a minimal installation of Prefect designed for interacting with Prefect Cloud or a remote self-hosted server instance.</p> <p><code>prefect-client</code> enables a subset of Prefect's functionality with a smaller installation size, making it ideal for use in lightweight, resource-constrained, or ephemeral environments. It omits all CLI and server components found in the <code>prefect</code> library.</p> <p>Install the latest version with:</p> <pre><code>pip install -U prefect-client\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#sqlite","title":"SQLite","text":"<p>By default, a local Prefect server instance uses SQLite as the backing database. SQLite is not packaged with the Prefect installation. Most systems will already have SQLite installed, because it is typically bundled with Python.</p> <p>Note</p> <p>Note that in production we recommend using Prefect Cloud as your API server or hosting your own Prefect server instance backed by PostgreSQL.</p> <p>Info</p> <p>If you install the <code>prefect-client</code> library that provides a limited set of the full Prefect library's functionality, you do not need SQLite installed.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#install-sqlite-on-rhel","title":"Install SQLite on RHEL","text":"<p>To install an appropriate version of SQLite on Red Hat Custom Linux (RHEL), follow the instructions below:</p> Expand for instructions  Note that some RHEL instances have no C compiler, so you may need to check for and install `gcc` first:   <pre><code>yum install gcc\n</code></pre>   Download and extract the tarball for SQLite.   <pre><code>wget https://www.sqlite.org/2022/sqlite-autoconf-3390200.tar.gz\ntar -xzf sqlite-autoconf-3390200.tar.gz\n</code></pre>   Move to the extracted SQLite directory, then build and install SQLite.   <pre><code>cd sqlite-autoconf-3390200/\n./configure\nmake\nmake install\n</code></pre>   Add `LD_LIBRARY_PATH` to your profile.   <pre><code>echo 'export LD_LIBRARY_PATH=\"/usr/local/lib\"' &gt;&gt; /etc/profile\n</code></pre>   Restart your shell to register these changes.  Now you can install Prefect using `pip`.   <pre><code>pip3 install prefect\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#installing-unreleased-code","title":"Installing unreleased code","text":"<p>To use the most up-to-date, unreleased Prefect code, you can install directly off the <code>main</code> GitHub branch:</p> <pre><code>pip install -U git+https://github.com/PrefectHQ/prefect\n</code></pre> <p>The <code>main</code> branch may not be stable</p> <p>Please be aware that this method installs unreleased code and may not be stable.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#next-steps","title":"Next steps","text":"<p>Now that you have Prefect installed and your environment configured, check out the Tutorial to get more familiar with Prefect.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/quickstart/","title":"Quickstart","text":"<p>Prefect is an orchestration and observability platform that empowers developers to build and scale code quickly, turning their Python scripts into resilient, recurring workflows.</p> <p>In this quickstart, you'll see how you can schedule your code on remote infrastructure and observe the state of your workflows. With Prefect, you can go from a Python script to a production-ready workflow that runs remotely in a few minutes.</p> <p>Let's get started!</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#setup","title":"Setup","text":"<p>Here's a basic script that fetches statistics about the main Prefect GitHub repository.</p> <pre><code>import httpx\n\ndef get_repo_info():\n    url = \"https://api.github.com/repos/PrefectHQ/prefect\"\n    response = httpx.get(url)\n    repo = response.json()\n    print(\"PrefectHQ/prefect repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Let's make this script schedulable, observable, resilient, and capable of running anywhere.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-1-install-prefect","title":"Step 1: Install Prefect","text":"<pre><code>pip install -U prefect\n</code></pre> <p>See the install guide for more detailed installation instructions, if needed.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-2-connect-to-prefects-api","title":"Step 2: Connect to Prefect's API","text":"<p>Much of Prefect's functionality is backed by an API. The easiest way to get started is to use the API hosted by Prefect:</p> <ol> <li>Create a forever-free Prefect Cloud account or sign in at https://app.prefect.cloud/</li> <li>Use the <code>prefect cloud login</code> CLI command to log in to Prefect Cloud from your development environment</li> </ol> <pre><code>prefect cloud login\n</code></pre> <p>Choose Log in with a web browser and click the Authorize button in the browser window that opens. Your CLI is now authenticated with your Prefect Cloud account through a locally-stored API key that expires in 30 days.</p> <p>If you have any issues with browser-based authentication, see the Prefect Cloud docs to learn how to authenticate with a manually created API key.</p> <p>Self-hosted Prefect server instance</p> <p>If you would like to host a Prefect server instance on your own infrastructure, see the tutorial and select the \"Self-hosted\" tab. Note that you will need to both host your own server and run your flows on your own infrastructure.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-3-turn-your-function-into-a-prefect-flow","title":"Step 3: Turn your function into a Prefect flow","text":"<p>The fastest way to get started with Prefect is to add a <code>@flow</code> decorator to your Python function. Flows are the core observable, deployable units in Prefect and are the primary entrypoint to orchestrated work.</p> my_gh_workflow.py<pre><code>import httpx   # an HTTP client library and dependency of Prefect\nfrom prefect import flow, task\n\n\n@task(retries=2)\ndef get_repo_info(repo_owner: str, repo_name: str):\n    \"\"\"Get info about a repo - will retry twice after failing\"\"\"\n    url = f\"https://api.github.com/repos/{repo_owner}/{repo_name}\"\n    api_response = httpx.get(url)\n    api_response.raise_for_status()\n    repo_info = api_response.json()\n    return repo_info\n\n\n@task\ndef get_contributors(repo_info: dict):\n    \"\"\"Get contributors for a repo\"\"\"\n    contributors_url = repo_info[\"contributors_url\"]\n    response = httpx.get(contributors_url)\n    response.raise_for_status()\n    contributors = response.json()\n    return contributors\n\n\n@flow(log_prints=True)\ndef repo_info(repo_owner: str = \"PrefectHQ\", repo_name: str = \"prefect\"):\n    \"\"\"\n    Given a GitHub repository, logs the number of stargazers\n    and contributors for that repo.\n    \"\"\"\n    repo_info = get_repo_info(repo_owner, repo_name)\n    print(f\"Stars \ud83c\udf20 : {repo_info['stargazers_count']}\")\n\n    contributors = get_contributors(repo_info)\n    print(f\"Number of contributors \ud83d\udc77: {len(contributors)}\")\n\n\nif __name__ == \"__main__\":\n    repo_info()\n</code></pre> <p>Note that we added a <code>log_prints=True</code> argument to the <code>@flow</code> decorator so that <code>print</code> statements within the flow-decorated function will be logged. Also note that our flow calls two tasks, which are defined by the <code>@task</code> decorator. Tasks are the smallest unit of observed and orchestrated work in Prefect.</p> <pre><code>python my_gh_workflow.py\n</code></pre> <p>Now when we run this script, Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.</p> <pre><code>14:28:31.099 | INFO    | prefect.engine - Created flow run 'energetic-panther' for flow 'repo-info'\n14:28:31.100 | INFO    | Flow run 'energetic-panther' - View at https://app.prefect.cloud/account/123/workspace/abc/flow-runs/flow-run/xyz\n14:28:32.178 | INFO    | Flow run 'energetic-panther' - Created task run 'get_repo_info-0' for task 'get_repo_info'\n14:28:32.179 | INFO    | Flow run 'energetic-panther' - Executing 'get_repo_info-0' immediately...\n14:28:32.584 | INFO    | Task run 'get_repo_info-0' - Finished in state Completed()\n14:28:32.599 | INFO    | Flow run 'energetic-panther' - Stars \ud83c\udf20 : 13609\n14:28:32.682 | INFO    | Flow run 'energetic-panther' - Created task run 'get_contributors-0' for task 'get_contributors'\n14:28:32.682 | INFO    | Flow run 'energetic-panther' - Executing 'get_contributors-0' immediately...\n14:28:33.118 | INFO    | Task run 'get_contributors-0' - Finished in state Completed()\n14:28:33.134 | INFO    | Flow run 'energetic-panther' - Number of contributors \ud83d\udc77: 30\n14:28:33.255 | INFO    | Flow run 'energetic-panther' - Finished in state Completed('All states completed.')\n</code></pre> <p>You should see similar output in your terminal, with your own randomly generated flow run name and your own Prefect Cloud account URL.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-4-choose-a-remote-infrastructure-location","title":"Step 4: Choose a remote infrastructure location","text":"<p>Let's get this workflow running on infrastructure other than your local machine! We can tell Prefect where we want to run our workflow by creating a work pool.</p> <p>We can have Prefect Cloud run our flow code for us with a Prefect Managed work pool.</p> <p>Let's create a Prefect Managed work pool so that Prefect can run our flows for us. We can create a work pool in the UI or from the CLI. Let's use the CLI:</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed\n</code></pre> <p>You should see a message in the CLI that your work pool was created. Feel free to check out your new work pool on the Work Pools page in the UI.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-5-make-your-code-schedulable","title":"Step 5: Make your code schedulable","text":"<p>We have a flow function and we have a work pool where we can run our flow remotely. Let's package both of these things, along with the location for where to find our flow code, into a deployment so that we can schedule our workflow to run remotely.</p> <p>Deployments elevate flows to remotely configurable entities that have their own API.</p> <p>Let's make a script to build a deployment with the name my-first-deployment and set it to run on a schedule.</p> create_deployment.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/prefecthq/demos.git\",\n        entrypoint=\"my_gh_workflow.py:repo_info\",\n    ).deploy(\n        name=\"my-first-deployment\",\n        work_pool_name=\"my-managed-pool\",\n        cron=\"0 1 * * *\",\n    )\n</code></pre> <p>Run the script to create the deployment on the Prefect Cloud server. Note that the <code>cron</code> argument will schedule the deployment to run at 1am every day.</p> <pre><code>python create_deployment.py\n</code></pre> <p>You should see a message that your deployment was created, similar to the one below.</p> <pre><code>Successfully created/updated all deployments!\n______________________________________________________\n|                    Deployments                     |  \n______________________________________________________\n|    Name                       |  Status  | Details |\n______________________________________________________\n| repo-info/my-first-deployment | applied  |         |\n______________________________________________________\n\nTo schedule a run for this deployment, use the following command:\n\n       $ prefect deployment run 'repo-info/my-first-deployment'\n\nYou can also run your flow via the Prefect UI: &lt;https://app.prefect.cloud/account/abc/workspace/123/deployments/deployment/xyz&gt;\n</code></pre> <p>Head to the Deployments page of the UI to check it out.</p> <p>Code storage options</p> <p>You can store your flow code in nearly any location. You just need to tell Prefect where to find it. In this example, we use a GitHub repository, but you could bake your code into a Docker image or store it in cloud provider storage. Read more in this guide.</p> <p>Push your code to GitHub</p> <p>In the example above, we use an existing GitHub repository. If you make changes to the flow code, you will need to push those changes to your own GitHub account and update the <code>source</code> argument to point to your repository.</p> <p>You can trigger a manual run of this deployment by either clicking the Run button in the top right of the deployment page in the UI, or by running the following CLI command in your terminal:</p> <pre><code>prefect deployment run 'repo-info/my-first-deployment'\n</code></pre> <p>The deployment is configured to run on a Prefect Managed work pool, so Prefect will automatically spin up the infrastructure to run this flow. It may take a minute to set up the Docker image in which the flow will run.</p> <p>After a minute or so, you should see the flow run graph and logs on the Flow Run page in the UI.</p> <p></p> <p>Remove the schedule</p> <p>Click the Remove button in the top right of the Deployment page so that the workflow is no longer scheduled to run once per day.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#next-steps","title":"Next steps","text":"<p>You've seen how to move from a Python script to a scheduled, observable, remotely orchestrated workflow with Prefect.</p> <p>To learn how to run flows on your own infrastructure, customize the Docker image where your flow runs, and gain more orchestration and observation benefits check out the tutorial.</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a meeting</p> <p>Happy building!</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"guides/","title":"How-to Guides","text":"<p>This section of the documentation contains how-to guides for common workflows and use cases.</p>","tags":["guides","how to"],"boost":2},{"location":"guides/#development","title":"Development","text":"Title Description Hosting Host your own Prefect server instance. Profiles &amp; Settings Configure Prefect and save your settings. Testing Easily test your workflows. Global Concurrency Limits Limit flow runs. Runtime Context Enable a flow to access metadata about itself and its context when it runs. Variables Store and retrieve configuration data. Prefect Client Use <code>PrefectClient</code> to interact with the API server. Interactive Workflows Create human-in-the-loop workflows by pausing flow runs for input. Automations Configure actions that Prefect executes automatically based on trigger conditions. Webhooks Receive, observe, and react to events from other systems. Terraform Provider Use the Terraform Provider for Prefect Cloud for infrastructure as code. CI/CD Use CI/CD with Prefect. Specifying Upstream Dependencies Run tasks in a desired order. Third-party Secrets Use credentials stored in a secrets manager in your workflows. Prefect Recipes Common, extensible examples for setting up Prefect.","tags":["guides","how to"],"boost":2},{"location":"guides/#execution","title":"Execution","text":"Title Description Docker Deploy flows with Docker containers. State Change Hooks Execute code in response to state changes. Dask and Ray Scale your flows with parallel computing frameworks. Read and Write Data Read and write data to and from cloud provider storage. Big Data Handle large data with Prefect. Logging Configure Prefect's logger and aggregate logs from other tools. Troubleshooting Identify and resolve common issues with Prefect. Managed Execution Let prefect run your code. Shell Commands Shell commands as Prefect flows","tags":["guides","how to"],"boost":2},{"location":"guides/#work-pools","title":"Work Pools","text":"Title Description Deploying Flows to Work Pools and Workers Learn how to run you code with dynamic infrastructure. Upgrade from Agents to Workers Why and how to upgrade from agents to workers. Flow Code Storage Where to store your code for deployments. Kubernetes Deploy flows on Kubernetes. Serverless Push Work Pools Run flows on serverless infrastructure without a worker. Serverless Work Pools with Workers Run flows on serverless infrastructure with a worker. Daemonize Processes Set up a systemd service to run a Prefect worker or .serve process. Custom Workers Develop your own worker type. Overriding Work Pool Job Variables Override job variables for a work pool for a given deployment. <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["guides","how to"],"boost":2},{"location":"guides/automations/","title":"Using Automations for Dynamic Responses","text":"<p>From the Automations concept page, we saw what an automation can do and how to configure one within the UI. </p> <p>In this guide, we will showcase the following common use cases:</p> <ul> <li>Create a simple notification automation in just a few UI clicks</li> <li>Build upon an event based automation</li> <li>Combine into a multi-layered responsive deployment pattern</li> </ul> <p>Available only on Prefect Cloud</p> <pre><code>Automations are a Prefect Cloud feature.\n</code></pre>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#prerequisites","title":"Prerequisites","text":"<p>Please have the following before exploring the guide:</p> <ul> <li>Python installed</li> <li>Prefect installed (follow the installation guide)</li> <li>Authenticated to a Prefect Cloud workspace</li> <li>A work pool set up to handle the deployments</li> </ul>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#creating-the-example-script","title":"Creating the example script","text":"<p>Automations allow you to take actions in response to triggering events recorded by Prefect. </p> <p>For example, let's try to grab data from an API and send a notification based on the end state. </p> <p>We can start by pulling hypothetical user data from an endpoint and then performing data cleaning and transformations. </p> <p>Let's create a simple extract method, that pulls the data from a random user data generator endpoint. </p> <pre><code>from prefect import flow, task, get_run_logger\nimport requests\nimport json\n\n@task\ndef fetch(url: str):\n    logger = get_run_logger()\n    response = requests.get(url)\n    raw_data = response.json()\n    logger.info(f\"Raw response: {raw_data}\")\n    return raw_data\n\n@task\ndef clean(raw_data: dict):\n    print(raw_data.get('results')[0])\n    results = raw_data.get('results')[0]\n    logger = get_run_logger()\n    logger.info(f\"Cleaned results: {results}\")\n    return results['name']\n\n@flow\ndef build_names(num: int = 10):\n    df = []\n    url = \"https://randomuser.me/api/\"\n    logger = get_run_logger()\n    copy = num\n    while num != 0:\n        raw_data = fetch(url)\n        df.append(clean(raw_data))\n        num -= 1\n    logger.info(f\"Built {copy} names: {df}\")\n    return df\n\nif __name__ == \"__main__\":\n    list_of_names = build_names()\n</code></pre> <p>The data cleaning workflow has visibility into each step, and we are sending a list of names to our next step of our pipeline.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#create-notification-block-within-the-ui","title":"Create notification block within the UI","text":"<p>Now let's try to send a notification based off a completed state outcome. We can configure a notification to be sent so that we know when to look into our workflow logic. </p> <ol> <li> <p>Prior to creating the automation, let's confirm the notification location. We have to create a notification block to help define where the notification will be sent.  </p> </li> <li> <p>Let's navigate to the blocks page on the UI, and click into creating an email notification block.  </p> </li> <li> <p>Now that we created a notification block, we can go to the automations page to create our first automation. </p> </li> <li> <p>Next we try to find the trigger type, in this case let's use a flow completion.  </p> </li> <li> <p>Finally, let's create the actions that will be done once the triggered is hit. In this case, let's create a notification to be sent out to showcase the completion.  </p> </li> <li> <p>Now the automation is ready to be triggered from a flow run completion. Let's run the file locally and see that the notification is sent to our inbox after the completion. It may take a few minutes for the notification to arrive. </p> </li> </ol> <p>No deployment created</p> <p>Keep in mind, we did not need to create a deployment to trigger our automation, where a state outcome of a local flow run helped trigger this notification block. We are not required to create a deployment to trigger a notification.</p> <p>Now that you've seen how to create an email notification from a flow run completion, let's see how we can kick off a deployment run in response to an event.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#event-based-deployment-automation","title":"Event-based deployment automation","text":"<p>We can create an automation that can kick off a deployment instead of a notification. Let's explore how we can programmatically create this automation. We will take advantage of Prefect's REST API to help create this automation.  </p> <p>See the REST API documentation as a reference for interacting with the Prefect Cloud automation endpoints.</p> <p>Let's create a deployment where we can kick off some work based on how long a flow is running. For example, if the <code>build_names</code> flow is taking too long to execute, we can kick off a deployment of the with the same <code>build_names</code> flow, but replace the <code>count</code> value with a lower number - to speed up completion. You can create a deployment with a <code>prefect.yaml</code> file or a Python file that uses <code>flow.deploy</code>.</p> prefect.yaml.deploy <p>Create a <code>prefect.yaml</code> file like this one for our flow <code>build_names</code>:</p> <pre><code>  # Welcome to your prefect.yaml file! You can use this file for storing and managing\n  # configuration for deploying your flows. We recommend committing this file to source\n  # control along with your flow code.\n\n  # Generic metadata about this project\n  name: automations-guide\n  prefect-version: 2.13.1\n\n  # build section allows you to manage and build docker images\n  build: null\n\n  # push section allows you to manage if and how this project is uploaded to remote locations\n  push: null\n\n  # pull section allows you to provide instructions for cloning this project in remote locations\n  pull:\n  - prefect.deployments.steps.set_working_directory:\n      directory: /Users/src/prefect/Playground/automations-guide\n\n  # the deployments section allows you to provide configuration for deploying flows\n  deployments:\n  - name: deploy-build-names\n    version: null\n    tags: []\n    description: null\n    entrypoint: test-automations.py:build_names\n    parameters: {}\n    work_pool:\n      name: tutorial-process-pool\n      work_queue_name: null\n      job_variables: {}\n    schedule: null\n</code></pre> <p>To follow a more Python based approach to create a deployment, you can use <code>flow.deploy</code> as in the example below.</p> <pre><code># .deploy only needs a name, valid work pool \n# and a reference to where the flow code exists\n\nif __name__ == \"__main__\":\nbuild_names.deploy(\n    name=\"deploy-build-names\",\n    work_pool_name=\"tutorial-process-pool\"\n    image=\"my_registry/my_image:my_image_tag\",\n)\n</code></pre> <p>Now let's grab our <code>deployment_id</code> from this deployment, and embed it in our automation. There are many ways to obtain the <code>deployment_id</code>, but the CLI is a quick way to see all of your deployment ids. </p> <p>Find deployment_id from the CLI</p> <p>The quickest way to see the ID's associated with your deployment would be running <code>prefect deployment ls</code>   in an authenticated command prompt, and you will be able to see the id's associated with all of your deployments</p> <p><pre><code>prefect deployment ls\n                                          Deployments                                           \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                                                  \u2503 ID                                   \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Extract islands/island-schedule                       \u2502 d9d7289c-7a41-436d-8313-80a044e61532 \u2502\n\u2502 build-names/deploy-build-names                        \u2502 8b10a65e-89ef-4c19-9065-eec5c50242f4 \u2502\n\u2502 ride-duration-prediction-backfill/backfill-deployment \u2502 76dc6581-1773-45c5-a291-7f864d064c57 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> We can create an automation via a POST call, where we can programmatically create the automation. Ensure you have your <code>api_key</code>, <code>account_id</code>, and <code>workspace_id</code>. </p> <pre><code>def create_event_driven_automation():\n    api_url = f\"https://api.prefect.cloud/api/accounts/{account_id}/workspaces/{workspace_id}/automations/\"\n    data = {\n    \"name\": \"Event Driven Redeploy\",\n    \"description\": \"Programmatically created an automation to redeploy a flow based on an event\",\n    \"enabled\": \"true\",\n    \"trigger\": {\n    \"after\": [\n        \"string\"\n    ],\n    \"expect\": [\n        \"prefect.flow-run.Running\"\n    ],\n    \"for_each\": [\n        \"prefect.resource.id\"\n    ],\n    \"posture\": \"Proactive\",\n    \"threshold\": 30,\n    \"within\": 0\n    },\n    \"actions\": [\n    {\n        \"type\": \"run-deployment\",\n        \"source\": \"selected\",\n        \"deployment_id\": \"YOUR-DEPLOYMENT-ID\", \n        \"parameters\": \"10\"\n    }\n    ],\n    \"owner_resource\": \"string\"\n        }\n\n    headers = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\n    response = requests.post(api_url, headers=headers, json=data)\n\n    print(response.json())\n    return response.json()\n</code></pre> <p>After running this function, you will see within the UI the changes that came from the post request. Keep in mind, the context will be \"custom\" on UI. </p> <p>Let's run the underlying flow and see the deployment get kicked off after 30 seconds elapsed. This will result in a new flow run of <code>build_names</code>, and we are able to see this new deployment get initiated with the custom parameters we outlined above. </p> <p>In a few quick changes, we are able to programmatically create an automation that deploys workflows with custom parameters. </p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#using-an-underlying-yaml-file","title":"Using an underlying .yaml file","text":"<p>We can extend this idea one step further by utilizing our own .yaml version of the automation, and registering that file with our UI. This simplifies the requirements of the automation by declaring it in its own .yaml file, and then registering that .yaml with the API. </p> <p>Let's first start with creating the .yaml file that will house the automation requirements. Here is how it would look like:</p> <pre><code>name: Cancel long running flows\ndescription: Cancel any flow run after an hour of execution\ntrigger:\n  match:\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  match_related: {}\n  after:\n    - \"prefect.flow-run.Failed\"\n  expect:\n    - \"prefect.flow-run.*\"\n  for_each:\n    - \"prefect.resource.id\"\n  posture: \"Proactive\"\n  threshold: 1\n  within: 30\nactions:\n  - type: \"cancel-flow-run\"\n</code></pre> <p>We can then have a helper function that applies this YAML file with the REST API function.  <pre><code>import yaml\n\nfrom utils import post, put\n\ndef create_or_update_automation(path: str = \"automation.yaml\"):\n    \"\"\"Create or update an automation from a local YAML file\"\"\"\n    # Load the definition\n    with open(path, \"r\") as fh:\n        payload = yaml.safe_load(fh)\n\n    # Find existing automations by name\n    automations = post(\"/automations/filter\")\n    existing_automation = [a[\"id\"] for a in automations if a[\"name\"] == payload[\"name\"]]\n    automation_exists = len(existing_automation) &gt; 0\n\n    # Create or update the automation\n    if automation_exists:\n        print(f\"Automation '{payload['name']}' already exists and will be updated\")\n        put(f\"/automations/{existing_automation[0]}\", payload=payload)\n    else:\n        print(f\"Creating automation '{payload['name']}'\")\n        post(\"/automations/\", payload=payload)\n\nif __name__ == \"__main__\":\n    create_or_update_automation()\n</code></pre></p> <p>You can find a complete repo with these APIs examples in this GitHub repository. </p> <p>In this example, we managed to create the automation by registering the .yaml file with a helper function. This offers another experience when trying to create an automation.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#custom-webhook-kicking-off-an-automation","title":"Custom webhook kicking off an automation","text":"<p>We can use webhooks to expose the events API which allows us to extend the functionality of deployments and ways to respond to changes in our workflow through a few easy steps. </p> <p>By exposing a webhook endpoint, we can kick off workflows that can trigger deployments - all from a simple event created from an HTTP request. </p> <p>Lets create a webhook within the UI.  Here is the webhook we can use to create these dynamic events. <pre><code>{\n    \"event\": \"model-update\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.{{ body.model_id}}\",\n        \"prefect.resource.name\": \"{{ body.friendly_name }}\",\n        \"run_count\": \"{{body.run_count}}\"\n    }\n}\n</code></pre> From a simple input, we can easily create an exposed webhook endpoint. </p> <p></p> <p>Each webhook will correspond to a custom event created, where you can react to it downstream with a separate deployment or automation. </p> <p>For example, we can create a curl request that sends the endpoint information such as a run count for our deployment.  <pre><code>curl -X POST https://api.prefect.cloud/hooks/34iV2SFke3mVa6y5Y-YUoA -d \"model_id=adhoc\" -d \"run_count=10\" -d \"friendly_name=test-user-input\"\n</code></pre> From here, we can make a webhook that is connected to pulling in parameters on the curl command, and then it kicks off a deployment that uses these pulled parameters. </p> <p>Let us go into the event feed, and we can automate straight from this event.  </p> <p>This allows us to create automations that respond to these webhook events. From a few clicks in the UI, we are able to associate an external process with the Prefect events API, that can enable us to trigger downstream deployments.  </p> <p>In the next section, we will explore event triggers that automate the kickoff of a deployment run.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#using-triggers","title":"Using triggers","text":"<p>Let's take this idea one step further, by creating a deployment that will be triggered when a flow run takes longer than expected.  We can take advantage of Prefect's Marvin library that will use an LLM to classify our data.  Marvin is great at embedding data science and data analysis applications within your pre-existing data engineering workflows. In this case, we can use Marvin'd AI functions to help make our dataset more information rich. </p> <p>Install Marvin with <code>pip install marvin</code> and set you OpenAI API key as shown here</p> <p>We can add a trigger to run a deployment in response to a specific event. </p> <p>Let's create an example with Marvin's AI functions. We will take in a pandas DataFrame and use the AI function to analyze it. </p> <p>Here is an example of pulling in that data and classifying using Marvin AI. We can help create dummy data based on classifications we have already created.</p> <pre><code>from marvin import ai_classifier\nfrom enum import Enum\nimport pandas as pd\n\n@ai_fn\ndef generate_synthetic_user_data(build_of_names: list[dict]) -&gt; list:\n    \"\"\"\n    Generate additional data for userID (numerical values with 6 digits), location, and timestamp as separate columns and append the data onto 'build_of_names'. Make userID the first column\n    \"\"\"\n\n@flow\ndef create_fake_user_dataset(df):\n  artifact_df = generate_synthetic_user_data(df)\n  print(artifact_df)\n\n  create_table_artifact(\n      key=\"fake-user-data\",\n      table=artifact_df,\n      description= \"Dataset that is comprised of a mix of autogenerated data based on user data\"\n  )\n\nif __name__ == \"__main__\":\n    create_fake_artifact()  \n</code></pre> <p>Let's kick off a deployment with a trigger defined in a <code>prefect.yaml</code> file. Let's specify what we want to trigger when the event stays in a running state for longer than 30 seconds.  <pre><code># Welcome to your prefect.yaml file! You can use this file for storing and managing\n# configuration for deploying your flows. We recommend committing this file to source\n# control along with your flow code.\n\n# Generic metadata about this project\nname: automations-guide\nprefect-version: 2.13.1\n\n# build section allows you to manage and build docker images\nbuild: null\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush: null\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /Users/src/prefect/Playground/marvin-extension\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: create-fake-user-dataset\n  triggers:\n    - enabled: true\n      match:\n        prefect.resource.id: \"prefect.flow-run.*\"\n      after: \"prefect.flow-run.Running\",\n      expect: [],\n      for_each: [\"prefect.resource.id\"],\n      parameters:\n        param_1: 10\n      posture: \"Proactive\"\n  version: null\n  tags: []\n  description: null\n  entrypoint: marvin-extension.py:create_fake_user_dataset\n  parameters: {}\n  work_pool:\n    name: tutorial-process-pool\n    work_queue_name: null\n    job_variables: {}\n  schedule: null\n</code></pre></p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#next-steps","title":"Next steps","text":"<p>You've seen how to create automations via the UI, REST API, and a triggers defined in a <code>prefect.yaml</code> deployment definition.</p> <p>To learn more about events that can act as automation triggers, see the events docs.  To learn more about event webhooks in particular, see the webhooks guide.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/big-data/","title":"Big Data with Prefect","text":"<p>In this guide you'll learn tips for working with large amounts of data in Prefect.</p> <p>Big data doesn't have a widely accepted, precise definition. In this guide, we'll discuss methods to reduce the processing time or memory utilization of Prefect workflows, without editing your Python code.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#optimizing-your-python-code-with-prefect-for-big-data","title":"Optimizing your Python code with Prefect for big data","text":"<p>Depending upon your needs, you may want to optimize your Python code for speed, memory, compute, or disk space.</p> <p>Prefect provides several options that we'll explore in this guide:</p> <ol> <li>Remove task introspection with <code>quote</code> to save time running your code.</li> <li>Write task results to cloud storage such as S3 using a block to save memory.</li> <li>Save data to disk within a flow rather than using results.</li> <li>Cache task results to save time and compute.</li> <li>Compress results written to disk to save space.</li> <li>Use a task runner for parallelizable operations to save time.</li> </ol>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#remove-task-introspection","title":"Remove task introspection","text":"<p>When a task is called from a flow, each argument is introspected by Prefect, by default. To speed up your flow runs, you can disable this behavior for a task by wrapping the argument using <code>quote</code>.</p> <p>To demonstrate, let's use a basic example that extracts and transforms some New York taxi data.</p> et_quote.py<pre><code>from prefect import task, flow\nfrom prefect.utilities.annotations import quote\nimport pandas as pd\n\n\n@task\ndef extract(url: str):\n    \"\"\"Extract data\"\"\"\n    df_raw = pd.read_parquet(url)\n    print(df_raw.info())\n    return df_raw\n\n\n@task\ndef transform(df: pd.DataFrame):\n    \"\"\"Basic transformation\"\"\"\n    df[\"tip_fraction\"] = df[\"tip_amount\"] / df[\"total_amount\"]\n    print(df.info())\n    return df\n\n\n@flow(log_prints=True)\ndef et(url: str):\n    \"\"\"ET pipeline\"\"\"\n    df_raw = extract(url)\n    df = transform(quote(df_raw))\n\n\nif __name__ == \"__main__\":\n    url = \"https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2023-09.parquet\"\n    et(url)\n</code></pre> <p>Introspection can take significant time when the object being passed is a large collection, such as dictionary or DataFrame, where each element needs to be visited. Note that using <code>quote</code> reduces execution time at the expense of disabling task dependency tracking for the wrapped object.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#write-task-results-to-cloud-storage","title":"Write task results to cloud storage","text":"<p>By default, the results of task runs are stored in memory in your execution environment. This behavior makes flow runs fast for small data, but can be problematic for large data. You can save memory by writing results to disk. In production, you'll generally want to write results to a cloud provider storage such as AWS S3. Prefect lets you to use a storage block from a Prefect cloud integration library such as prefect-aws to save your configuration information. Learn more about blocks here.</p> <p>Install the relevant library, register the block with the server, and create your storage block. Then you can reference the block in your flow like this:</p> <pre><code>...\nfrom prefect_aws.s3 import S3Bucket\n\nmy_s3_block = S3Bucket.load(\"MY_BLOCK_NAME\")\n\n...\n@task(result_storage=my_s3_block)\n</code></pre> <p>Now the result of the task will be written to S3, rather than stored in memory.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#save-data-to-disk-within-a-flow","title":"Save data to disk within a flow","text":"<p>To save memory and time with big data, you don't need to pass results between tasks at all. Instead, you can write and read data to disk directly in your flow code. Prefect has integration libraries for each of the major cloud providers. Each library contains blocks with methods that make it convenient to read and write data to and from cloud object storage. The moving data guide has step-by-step examples for each cloud provider.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#cache-task-results","title":"Cache task results","text":"<p>Caching allows you to avoid re-running tasks when doing so is unnecessary. Caching can save you time and compute. Note that caching requires task result persistence. Caching is discussed in detail in the tasks concept page.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#compress-results-written-to-disk","title":"Compress results written to disk","text":"<p>If you're using Prefect's task result persistence, you can save disk space by compressing the results. You just need to specify the result type with <code>compressed/</code> prefixed like this:</p> <pre><code>@task(result_serializer=\"compressed/json\")\n</code></pre> <p>Read about compressing results with Prefect for more details. The tradeoff of using compression is that it takes time to compress and decompress the data.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#use-a-task-runner-for-parallelizable-operations","title":"Use a task runner for parallelizable operations","text":"<p>Prefect's task runners allow you to use the Dask and Ray Python libraries to run tasks in parallel and distributed across multiple machines. This can save you time and compute when operating on large data structures. See the guide to working with Dask and Ray Task Runners for details.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/ci-cd/","title":"CI/CD With Prefect","text":"<p>Many organizations deploy Prefect workflows via their CI/CD process. Each organization has their own unique CI/CD setup, but a common pattern is to use CI/CD to manage Prefect deployments. Combining Prefect's deployment features with CI/CD tools enables efficient management of flow code updates, scheduling changes, and container builds. This guide uses GitHub Actions to implement a CI/CD process, but these concepts are generally applicable across many CI/CD tools.</p> <p>Note that Prefect's primary ways for creating deployments, a <code>.deploy</code> flow method or a <code>prefect.yaml</code> configuration file, are both designed with building and pushing images to a Docker registry in mind.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#getting-started-with-github-actions-and-prefect","title":"Getting started with GitHub Actions and Prefect","text":"<p>In this example, you'll write a GitHub Actions workflow that will run each time you push to your repository's <code>main</code> branch. This workflow will build and push a Docker image containing your flow code to Docker Hub, then deploy the flow to Prefect Cloud.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#repository-secrets","title":"Repository secrets","text":"<p>Your CI/CD process must be able to authenticate with Prefect in order to deploy flows.</p> <p>Deploying flows securely and non-interactively in your CI/CD process can be accomplished by saving your <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as secrets in your repository's settings so they can be accessed in your CI/CD runner's environment without exposing them in any scripts or configuration files.</p> <p>In this scenario, deploying flows involves building and pushing Docker images, so add <code>DOCKER_USERNAME</code> and <code>DOCKER_PASSWORD</code> as secrets to your repository as well.</p> <p>You can create secrets for GitHub Actions in your repository under Settings -&gt; Secrets and variables -&gt; Actions -&gt; New repository secret:</p> <p></p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#writing-a-github-workflow","title":"Writing a GitHub workflow","text":"<p>To deploy your flow via GitHub Actions, you'll need a workflow YAML file. GitHub will look for workflow YAML files in the <code>.github/workflows/</code> directory in the root of your repository. In their simplest form, GitHub workflow files are made up of triggers and jobs.</p> <p>The <code>on:</code> trigger is set to run the workflow each time a push occurs on the <code>main</code> branch of the repository.</p> <p>The <code>deploy</code> job is comprised of four <code>steps</code>:</p> <ul> <li><code>Checkout</code> clones your repository into the GitHub Actions runner so you can reference files or run scripts from your repository in later steps.</li> <li><code>Log in to Docker Hub</code> authenticates to DockerHub so your image can be pushed to the Docker registry in your DockerHub account. docker/login-action is an existing GitHub action maintained by Docker. <code>with:</code> passes values into the Action, similar to passing parameters to a function.</li> <li><code>Setup Python</code> installs your selected version of Python.</li> <li><code>Prefect Deploy</code> installs the dependencies used in your flow, then deploys your flow. <code>env:</code> makes the <code>PREFECT_API_KEY</code> and <code>PREFECT_API_URL</code> secrets from your repository available as environment variables during this step's execution.</li> </ul> <p>For reference, the examples below can be found on their respective branches of this repository.</p> .deployprefect.yaml <pre><code>.\n\u251c\u2500\u2500 .github/\n\u2502   \u2514\u2500\u2500 workflows/\n\u2502       \u2514\u2500\u2500 deploy-prefect-flow.yaml\n\u251c\u2500\u2500 flow.py\n\u2514\u2500\u2500 requirements.txt\n</code></pre> <p><code>flow.py</code></p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef hello():\n  print(\"Hello!\")\n\nif __name__ == \"__main__\":\n    hello.deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my_registry/my_image:my_image_tag\",\n    )\n</code></pre> <p><code>.github/workflows/deploy-prefect-flow.yaml</code></p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n\n      - name: Prefect Deploy\n        env:\n          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}\n          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}\n        run: |\n          pip install -r requirements.txt\n          python flow.py\n</code></pre> <pre><code>.\n\u251c\u2500\u2500 .github/\n\u2502   \u2514\u2500\u2500 workflows/\n\u2502       \u2514\u2500\u2500 deploy-prefect-flow.yaml\n\u251c\u2500\u2500 flow.py\n\u251c\u2500\u2500 prefect.yaml\n\u2514\u2500\u2500 requirements.txt\n</code></pre> <p><code>flow.py</code></p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef hello():\n  print(\"Hello!\")\n</code></pre> <p><code>prefect.yaml</code></p> <pre><code>name: cicd-example\nprefect-version: 2.14.11\n\nbuild:\n  - prefect_docker.deployments.steps.build_docker_image:\n      id: build_image\n      requires: prefect-docker&gt;=0.3.1\n      image_name: my_registry/my_image\n      tag: my_image_tag\n      dockerfile: auto\n\npush:\n  - prefect_docker.deployments.steps.push_docker_image:\n      requires: prefect-docker&gt;=0.3.1\n      image_name: \"{{ build_image.image_name }}\"\n      tag: \"{{ build_image.tag }}\"\n\npull: null\n\ndeployments:\n  - name: my-deployment\n    entrypoint: flow.py:hello\n    work_pool:\n      name: my-work-pool\n      work_queue_name: default\n      job_variables:\n        image: \"{{ build-image.image }}\"\n</code></pre> <p><code>.github/workflows/deploy-prefect-flow.yaml</code></p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n\n      - name: Prefect Deploy\n        env:\n          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}\n          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}\n        run: |\n          pip install -r requirements.txt\n          prefect deploy -n my-deployment\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#running-a-github-workflow","title":"Running a GitHub workflow","text":"<p>After pushing commits to your repository, GitHub will automatically trigger a run of your workflow. The status of running and completed workflows can be monitored from the Actions tab of your repository.</p> <p></p> <p>You can view the logs from each workflow step as they run. The <code>Prefect Deploy</code> step will include output about your image build and push, and the creation/update of your deployment.</p> <pre><code>Successfully built image '***/cicd-example:latest'\n\nSuccessfully pushed image '***/cicd-example:latest'\n\nSuccessfully created/updated all deployments!\n\n                Deployments\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                \u2503 Status  \u2503 Details \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 hello/my-deployment \u2502 applied \u2502         \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#advanced-example","title":"Advanced example","text":"<p>In more complex scenarios, CI/CD processes often need to accommodate several additional considerations to enable a smooth development workflow:</p> <ul> <li>Making code available in different environments as it advances through stages of development</li> <li>Handling independent deployment of distinct groupings of work, as in a monorepo</li> <li>Efficiently using build time to avoid repeated work</li> </ul> <p>This example repository demonstrates how each of these considerations can be addressed using a combination of Prefect's and GitHub's capabilities.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#deploying-to-multiple-workspaces","title":"Deploying to multiple workspaces","text":"<p>Which deployment processes should run are automatically selected when changes are pushed depending on two conditions:</p> <pre><code>on:\n  push:\n    branches:\n      - stg\n      - main\n    paths:\n      - \"project_1/**\"\n</code></pre> <ol> <li><code>branches:</code> - which branch has changed. This will ultimately select which Prefect workspace a deployment is created or updated in. In this example, changes on the <code>stg</code> branch will deploy flows to a staging workspace, and changes on the <code>main</code> branch will deploy flows to a production workspace.</li> <li><code>paths:</code> - which project folders' files have changed. Since each project folder contains its own flows, dependencies, and <code>prefect.yaml</code>, it represents a complete set of logic and configuration that can be deployed independently. Each project in this repository gets its own GitHub Actions workflow YAML file.</li> </ol> <p>The <code>prefect.yaml</code> file in each project folder depends on environment variables that are dictated by the selected job in each CI/CD workflow, enabling external code storage for Prefect deployments that is clearly separated across projects and environments.</p> <pre><code>  .\n  \u251c\u2500\u2500 cicd-example-workspaces-prod  # production bucket\n  \u2502   \u251c\u2500\u2500 project_1\n  \u2502   \u2514\u2500\u2500 project_2\n  \u2514\u2500\u2500 cicd-example-workspaces-stg  # staging bucket\n      \u251c\u2500\u2500 project_1\n      \u2514\u2500\u2500 project_2  \n</code></pre> <p>Since the deployments in this example use S3 for code storage, it's important that push steps place flow files in separate locations depending upon their respective environment and project so no deployment overwrites another deployment's files.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#caching-build-dependencies","title":"Caching build dependencies","text":"<p>Since building Docker images and installing Python dependencies are essential parts of the deployment process, it's useful to rely on caching to skip repeated build steps.</p> <p>The <code>setup-python</code> action offers caching options so Python packages do not have to be downloaded on repeat workflow runs.</p> <pre><code>- name: Setup Python\n  uses: actions/setup-python@v5\n  with:\n    python-version: \"3.11\"\n    cache: \"pip\"\n</code></pre> <pre><code>Using cached prefect-2.16.1-py3-none-any.whl (2.9 MB)\nUsing cached prefect_aws-0.4.10-py3-none-any.whl (61 kB)\n</code></pre> <p>The <code>build-push-action</code> for building Docker images also offers caching options for GitHub Actions. If you are not using GitHub, other remote cache backends are available as well.</p> <pre><code>- name: Build and push\n  id: build-docker-image\n  env:\n      GITHUB_SHA: ${{ steps.get-commit-hash.outputs.COMMIT_HASH }}\n  uses: docker/build-push-action@v5\n  with:\n    context: ${{ env.PROJECT_NAME }}/\n    push: true\n    tags: ${{ secrets.DOCKER_USERNAME }}/${{ env.PROJECT_NAME }}:${{ env.GITHUB_SHA }}-stg\n    cache-from: type=gha\n    cache-to: type=gha,mode=max\n</code></pre> <pre><code>importing cache manifest from gha:***\nDONE 0.1s\n\n[internal] load build context\ntransferring context: 70B done\nDONE 0.0s\n\n[2/3] COPY requirements.txt requirements.txt\nCACHED\n\n[3/3] RUN pip install -r requirements.txt\nCACHED\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#prefect-github-actions","title":"Prefect GitHub Actions","text":"<p>Prefect provides its own GitHub Actions for authentication and deployment creation. These actions can simplify deploying with CI/CD when using <code>prefect.yaml</code>, especially in cases where a repository contains flows that are used in multiple deployments across multiple Prefect Cloud workspaces.</p> <p>Here's an example of integrating these actions into the workflow we created above:</p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: \"3.11\"\n\n      - name: Prefect Auth\n        uses: PrefectHQ/actions-prefect-auth@v1\n        with:\n          prefect-api-key: ${{ secrets.PREFECT_API_KEY }}\n          prefect-workspace: ${{ secrets.PREFECT_WORKSPACE }}\n\n      - name: Run Prefect Deploy\n        uses: PrefectHQ/actions-prefect-deploy@v3\n        with:\n          deployment-names: my-deployment\n          requirements-file-paths: requirements.txt\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#authenticating-to-other-docker-image-registries","title":"Authenticating to other Docker image registries","text":"<p>The <code>docker/login-action</code> GitHub Action supports pushing images to a wide variety of image registries.</p> <p>For example, if you are storing Docker images in AWS Elastic Container Registry, you can add your ECR registry URL to the <code>registry</code> key in the <code>with:</code> part of the action and use an <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code> as your <code>username</code> and <code>password</code>.</p> <pre><code>- name: Login to ECR\n  uses: docker/login-action@v3\n  with:\n    registry: &lt;aws-account-number&gt;.dkr.ecr.&lt;region&gt;.amazonaws.com\n    username: ${{ secrets.AWS_ACCESS_KEY_ID }}\n    password: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#other-resources","title":"Other resources","text":"<p>Check out the Prefect Cloud Terraform provider if you're using Terraform to manage your infrastructure.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/cli-shell/","title":"Orchestrating Shell Commands with Prefect","text":"<p>Harness the power of the Prefect CLI to execute and schedule shell commands as Prefect flows. This guide shows how to use the <code>watch</code> and <code>serve</code> commands to showcase the CLI's versatility for automation tasks.</p> <p>Here's what you'll learn:</p> <ul> <li>Running a shell command as a Prefect flow on-demand with <code>watch</code>.</li> <li>Scheduling a shell command as a recurring Prefect flow using <code>serve</code>.</li> <li>The benefits of embedding these commands into your automation workflows.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#prerequisites","title":"Prerequisites","text":"<p>Before you begin, ensure you have:</p> <ul> <li>A basic understanding of Prefect flows. Start with the Getting Started guide if you're new.</li> <li>A recent version of Prefect installed in your command line environment. Follow the instructions in the docs if you have any issues.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#the-watch-command","title":"The <code>watch</code> command","text":"<p>The <code>watch</code> command wraps any shell command in a Prefect flow for instant execution, ideal for quick tasks or integrating shell scripts into your workflows.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#example-usage","title":"Example usage","text":"<p>Imagine you want to fetch the current weather in Chicago using the <code>curl</code> command. The following Prefect CLI command does just that:</p> <pre><code>prefect shell watch \"curl http://wttr.in/Chicago?format=3\"\n</code></pre> <p>This command makes a request to <code>wttr.in</code>, a console-oriented weather service, and prints the weather conditions for Chicago.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#benefits-of-watch","title":"Benefits of <code>watch</code>","text":"<ul> <li>Immediate feedback: Execute shell commands  within the Prefect framework for immediate results.</li> <li>Easy integration: Seamlessly blend external scripts or data fetching into your data workflows.</li> <li>Visibility and logging: Leverage Prefect's logging to track the execution and output of your shell tasks.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#deploying-with-serve","title":"Deploying with <code>serve</code>","text":"<p>When you need to run shell commands on a schedule, the <code>serve</code> command creates a Prefect [deployment](/concepts/deployments/ for regular execution. This is an extremely quick way to create a deployment that is served by Prefect.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#example-usage_1","title":"Example usage","text":"<p>To set up a daily weather report for Chicago at 9 AM, you can use the <code>serve</code> command as follows:</p> <pre><code>prefect shell serve \"curl http://wttr.in/Chicago?format=3\" --flow-name \"Daily Chicago Weather Report\" --cron-schedule \"0 9 * * *\" --deployment-name \"Chicago Weather\"\n</code></pre> <p>This command schedules a Prefect flow to fetch Chicago's weather conditions daily, providing consistent updates without manual intervention. Additionally, if you want to fetch the Chicago weather, you can manually create a run of your new deployment from the UI or the CLI.</p> <p>To shut down your server and pause your scheduled runs, hit <code>ctrl</code> + <code>c</code> in the CLI.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#benefits-of-serve","title":"Benefits of <code>serve</code>","text":"<ul> <li>Automated scheduling: Schedule shell commands to run automatically, ensuring critical updates are generated and available on time.</li> <li>Centralized workflow management: Manage and monitor your scheduled shell commands inside Prefect for a unified workflow overview.</li> <li>Configurable execution: Tailor execution frequency, concurrency limits, and other parameters to suit your project's needs and resources.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#next-steps","title":"Next steps","text":"<p>With the <code>watch</code> and <code>serve</code> commands at your disposal, you're ready to incorporate shell command automation into your Prefect workflows. You can start with straightforward tasks like observing cron jobs and expand to more complex automation scenarios to enhance your workflows' efficiency and capabilities.</p> <p>Check out the tutorial and explore other Prefect docs to learn how to gain more observability and orchestration capabilities in your workflows. </p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/creating-interactive-workflows/","title":"Creating Interactive Workflows","text":"<p>Flows can pause or suspend execution and automatically resume when they receive type-checked input in Prefect's UI. Flows can also send and receive type-checked input at any time while running, without pausing or suspending. This guide will show you how to use these features to build interactive workflows.</p> <p>A note on async Python syntax</p> <p>Most of the example code in this section uses async Python functions and <code>await</code>. However, as with other Prefect features, you can call these functions with or without <code>await</code>.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#pausing-or-suspending-a-flow-until-it-receives-input","title":"Pausing or suspending a flow until it receives input","text":"<p>You can pause or suspend a flow until it receives input from a user in Prefect's UI. This is useful when you need to ask for additional information or feedback before resuming a flow. Such workflows are often called human-in-the-loop (HITL) systems.</p> <p>What is human-in-the-loop interactivity used for?</p> <p>Approval workflows that pause to ask a human to confirm whether a workflow should continue are very common in the business world. Certain types of machine learning training and artificial intelligence workflows benefit from incorporating HITL design.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#waiting-for-input","title":"Waiting for input","text":"<p>To receive input while paused or suspended use the <code>wait_for_input</code> parameter in the <code>pause_flow_run</code> or <code>suspend_flow_run</code> functions. This parameter accepts one of the following:</p> <ul> <li>A built-in type like <code>int</code> or <code>str</code>, or a built-in collection like <code>List[int]</code></li> <li>A <code>pydantic.BaseModel</code> subclass</li> <li>A subclass of <code>prefect.input.RunInput</code></li> </ul> <p>When to use a <code>RunModel</code> or <code>BaseModel</code> instead of a built-in type</p> <p>There are a few reasons to use a <code>RunModel</code> or <code>BaseModel</code>. The first is that when you let Prefect automatically create one of these classes for your input type, the field that users will see in Prefect's UI when they click \"Resume\" on a flow run is named <code>value</code> and has no help text to suggest what the field is. If you create a <code>RunInput</code> or <code>BaseModel</code>, you can change details like the field name, help text, and default value, and users will see those reflected in the \"Resume\" form.</p> <p>The simplest way to pause or suspend and wait for input is to pass a built-in type:</p> <pre><code>from prefect import flow, pause_flow_run, get_run_logger\n\n@flow\ndef greet_user():\n    logger = get_run_logger()\n\n    user = pause_flow_run(wait_for_input=str)\n\n    logger.info(f\"Hello, {user}!\")\n</code></pre> <p>In this example, the flow run will pause until a user clicks the Resume button in the Prefect UI, enters a name, and submits the form.</p> <p>What types can you pass for <code>wait_for_input</code>?</p> <p>When you pass a built-in type such as <code>int</code> as an argument for the <code>wait_for_input</code> parameter to <code>pause_flow_run</code> or <code>suspend_flow_run</code>, Prefect automatically creates a Pydantic model containing one field annotated with the type you specified. This means you can use any type annotation that Pydantic accepts for model fields with these functions.</p> <p>Instead of a built-in type, you can pass in a <code>pydantic.BaseModel</code> class. This is useful if you already have a <code>BaseModel</code> you want to use:</p> <pre><code>from prefect import flow, pause_flow_run, get_run_logger\nfrom pydantic import BaseModel\n\n\nclass User(BaseModel):\n    name: str\n    age: int\n\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user = await pause_flow_run(wait_for_input=User)\n\n    logger.info(f\"Hello, {user.name}!\")\n</code></pre> <p><code>BaseModel</code> classes are upgraded to <code>RunInput</code> classes automatically</p> <p>When you pass a <code>pydantic.BaseModel</code> class as the <code>wait_for_input</code> argument to <code>pause_flow_run</code> or <code>suspend_flow_run</code>, Prefect automatically creates a <code>RunInput</code> class with the same behavior as your <code>BaseModel</code> and uses that instead.</p> <p><code>RunInput</code> classes contain extra logic that allows flows to send and receive them at runtime. You shouldn't notice any difference!</p> <p>Finally, for advanced use cases like overriding how Prefect stores flow run inputs, you can create a <code>RunInput</code> class:</p> <pre><code>from prefect import get_run_logger\nfrom prefect.input import RunInput\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n    # Imagine overridden methods here!\n    def override_something(self, *args, **kwargs):\n        super().override_something(*args, **kwargs)\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user = await pause_flow_run(wait_for_input=UserInput)\n\n    logger.info(f\"Hello, {user.name}!\")\n</code></pre>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#providing-initial-data","title":"Providing initial data","text":"<p>You can set default values for fields in your model by using the <code>with_initial_data</code> method. This is useful when you want to provide default values for the fields in your own <code>RunInput</code> class.</p> <p>Expanding on the example above, you could make the <code>name</code> field default to \"anonymous\":</p> <pre><code>from prefect import get_run_logger\nfrom prefect.input import RunInput\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user_input = await pause_flow_run(\n        wait_for_input=UserInput.with_initial_data(name=\"anonymous\")\n    )\n\n    if user_input.name == \"anonymous\":\n        logger.info(\"Hello, stranger!\")\n    else:\n        logger.info(f\"Hello, {user_input.name}!\")\n</code></pre> <p>When a user sees the form for this input, the name field will contain \"anonymous\" as the default.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#providing-a-description-with-runtime-data","title":"Providing a description with runtime data","text":"<p>You can provide a dynamic, markdown description that will appear in the Prefect UI when the flow run pauses. This feature enables context-specific prompts, enhancing clarity and user interaction. Building on the example above:</p> <pre><code>from datetime import datetime\nfrom prefect import flow, pause_flow_run, get_run_logger\nfrom prefect.input import RunInput\n\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n    current_date = datetime.now().strftime(\"%B %d, %Y\")\n\n    description_md = f\"\"\"\n**Welcome to the User Greeting Flow!**\nToday's Date: {current_date}\n\nPlease enter your details below:\n- **Name**: What should we call you?\n- **Age**: Just a number, nothing more.\n\"\"\"\n\n    user_input = await pause_flow_run(\n        wait_for_input=UserInput.with_initial_data(\n            description=description_md, name=\"anonymous\"\n        )\n    )\n\n    if user_input.name == \"anonymous\":\n        logger.info(\"Hello, stranger!\")\n    else:\n        logger.info(f\"Hello, {user_input.name}!\")\n</code></pre> <p>When a user sees the form for this input, the given markdown will appear above the input fields.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#handling-custom-validation","title":"Handling custom validation","text":"<p>Prefect uses the fields and type hints on your <code>RunInput</code> or <code>BaseModel</code> class to validate the general structure of input your flow receives, but you might require more complex validation. If you do, you can use Pydantic validators.</p> <p>Custom validation runs after the flow resumes</p> <p>Prefect transforms the type annotations in your <code>RunInput</code> or <code>BaseModel</code> class to a JSON schema and uses that schema in the UI for client-side validation. However, custom validation requires running Python logic defined in your <code>RunInput</code> class. Because of this, validation happens after the flow resumes, so you'll want to handle it explicitly in your flow. Continue reading for an example best practice.</p> <p>The following is an example <code>RunInput</code> class that uses a custom field validator:</p> <pre><code>import pydantic\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n</code></pre> <p>In the example, we use Pydantic's <code>validator</code> decorator to define a custom validation method for the <code>color</code> field. We can use it in a flow like this:</p> <pre><code>import pydantic\nfrom prefect import flow, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n\n\n@flow\ndef get_shirt_order():\n    shirt_order = pause_flow_run(wait_for_input=ShirtOrder)\n</code></pre> <p>If a user chooses any size and color combination other than <code>small</code> and <code>green</code>, the flow run will resume successfully. However, if the user chooses size <code>small</code> and color <code>green</code>, the flow run will resume, and <code>pause_flow_run</code> will raise a <code>ValidationError</code> exception. This will cause the flow run to fail and log the error.</p> <p>However, what if you don't want the flow run to fail? One way to handle this case is to use a <code>while</code> loop and pause again if the <code>ValidationError</code> exception is raised:</p> <pre><code>from typing import Literal\n\nimport pydantic\nfrom prefect import flow, get_run_logger, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n\n\n@flow\ndef get_shirt_order():\n    logger = get_run_logger()\n    shirt_order = None\n\n    while shirt_order is None:\n        try:\n            shirt_order = pause_flow_run(wait_for_input=ShirtOrder)\n        except pydantic.ValidationError as exc:\n            logger.error(f\"Invalid size and color combination: {exc}\")\n\n    logger.info(\n        f\"Shirt order: {shirt_order.size}, {shirt_order.color}\"\n    )\n</code></pre> <p>This code will cause the flow run to continually pause until the user enters a valid age.</p> <p>As an additional step, you may want to use an automation or notification to alert the user to the error.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#sending-and-receiving-input-at-runtime","title":"Sending and receiving input at runtime","text":"<p>Use the <code>send_input</code> and <code>receive_input</code> functions to send input to a flow or receive input from a flow at runtime. You don't need to pause or suspend the flow to send or receive input.</p> <p>Why would you send or receive input without pausing or suspending?</p> <p>You might want to send or receive input without pausing or suspending in scenarios where the flow run is designed to handle real-time data. For instance, in a live monitoring system, you might need to update certain parameters based on the incoming data without interrupting the flow. Another use is having a long-running flow that continually responds to runtime input with low latency. For example, if you're building a chatbot, you could have a flow that starts a GPT Assistant and manages a conversation thread.</p> <p>The most important parameter to the <code>send_input</code> and <code>receive_input</code> functions is <code>run_type</code>, which should be one of the following:</p> <ul> <li>A built-in type such as <code>int</code> or <code>str</code></li> <li>A <code>pydantic.BaseModel</code> class</li> <li>A <code>prefect.input.RunInput</code> class</li> </ul> <p>When to use a <code>BaseModel</code> or <code>RunInput</code> instead of a built-in type</p> <p>Most built-in types and collections of built-in types should work with <code>send_input</code> and <code>receive_input</code>, but there is a caveat with nested collection types, such as lists of tuples, e.g. <code>List[Tuple[str, float]])</code>. In this case, validation may happen after your flow receives the data, so calling <code>receive_input</code> may raise a <code>ValidationError</code>. You can plan to catch this exception, but also, consider placing the field in an explicit <code>BaseModel</code> or <code>RunInput</code> so that your flow only receives exact type matches.</p> <p>Let's look at some examples! We'll check out <code>receive_input</code> first, followed by <code>send_input</code>, and then we'll see the two functions working together.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#receiving-input","title":"Receiving input","text":"<p>The following flow uses <code>receive_input</code> to continually receive names and print a personalized greeting for each name it receives:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(str, timeout=None):\n        # Prints \"Hello, andrew!\" if another flow sent \"andrew\"\n        print(f\"Hello, {name_input}!\")\n</code></pre> <p>When you pass a type such as <code>str</code> into <code>receive_input</code>, Prefect creates a <code>RunInput</code> class to manage your input automatically. When a flow sends input of this type, Prefect uses the <code>RunInput</code> class to validate the input. If the validation succeeds, your flow receives the input in the type you specified. In this example, if the flow received a valid string as input, the variable <code>name_input</code> would contain the string value.</p> <p>If, instead, you pass a <code>BaseModel</code>, Prefect upgrades your <code>BaseModel</code> to a <code>RunInput</code> class, and the variable your flow sees \u2014 in this case, <code>name_input</code> \u2014 is a <code>RunInput</code> instance that behaves like a <code>BaseModel</code>. Of course, if you pass in a <code>RunInput</code> class, no upgrade is needed, and you'll get a <code>RunInput</code> instance.</p> <p>If you prefer to keep things simple and pass types such as <code>str</code> into <code>receive_input</code>, you can do so. If you need access to the generated <code>RunInput</code> that contains the received value, pass <code>with_metadata=True</code> to <code>receive_input</code>:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(\n        str,\n        timeout=None,\n        with_metadata=True\n    ):\n        # Input will always be in the field \"value\" on this object.\n        print(f\"Hello, {name_input.value}!\")\n</code></pre> <p>Why would you need to use <code>with_metadata=True</code>?</p> <p>The primary uses of accessing the <code>RunInput</code> object for a receive input are to respond to the sender with the <code>RunInput.respond()</code> function or to access the unique key for an input. Later in this guide, we'll discuss how and why you might use these features.</p> <p>Notice that we are now printing <code>name_input.value</code>. When Prefect generates a <code>RunInput</code> for you from a built-in type, the <code>RunInput</code> class has a single field, <code>value</code>, that uses a type annotation matching the type you specified. So if you call <code>receive_input</code> like this: <code>receive_input(str, with_metadata=True)</code>, that's equivalent to manually creating the following <code>RunInput</code> class and <code>receive_input</code> call:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import RunInput\n\nclass GreeterInput(RunInput):\n    value: str\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(GreeterInput, timeout=None):\n        print(f\"Hello, {name_input.value}!\")\n</code></pre> <p>The type used in <code>receive_input</code> and <code>send_input</code> must match</p> <p>For a flow to receive input, the sender must use the same type that the receiver is receiving. This means that if the receiver is receiving <code>GreeterInput</code>, the sender must send <code>GreeterInput</code>. If the receiver is receiving <code>GreeterInput</code> and the sender sends <code>str</code> input that Prefect automatically upgrades to a <code>RunInput</code> class, the types won't match, so the receiving flow run won't receive the input. However, the input will be waiting if the flow ever calls <code>receive_input(str)</code>!</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#keeping-track-of-inputs-youve-already-seen","title":"Keeping track of inputs you've already seen","text":"<p>By default, each time you call <code>receive_input</code>, you get an iterator that iterates over all known inputs to a specific flow run, starting with the first received. The iterator will keep track of your current position as you iterate over it, or you can call <code>next()</code> to explicitly get the next input. If you're using the iterator in a loop, you should probably assign it to a variable:</p> <pre><code>from prefect import flow, get_client\nfrom prefect.deployments.deployments import run_deployment\nfrom prefect.input.run_input import receive_input, send_input\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    client = get_client()\n\n    # Assigning the `receive_input` iterator to a variable\n    # outside of the the `while True` loop allows us to continue\n    # iterating over inputs in subsequent passes through the\n    # while loop without losing our position.\n    receiver = receive_input(\n        str,\n        with_metadata=True,\n        timeout=None,\n        poll_interval=0.1\n    )\n\n    while True:\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n\n        # Saving the iterator outside of the while loop and\n        # calling next() on each iteration of the loop ensures\n        # that we're always getting the newest greeting. If we\n        # had instead called `receive_input` here, we would\n        # always get the _first_ greeting this flow received,\n        # print it, and then ask for a new name.\n        greeting = await receiver.next()\n        print(greeting)\n</code></pre> <p>So, an iterator helps to keep track of the inputs your flow has already received. But what if you want your flow to suspend and then resume later, picking up where it left off? In that case, you will need to save the keys of the inputs you've seen so that the flow can read them back out when it resumes. You might use a Block, such as a <code>JSONBlock</code>.</p> <p>The following flow receives input for 30 seconds then suspends itself, which exits the flow and tears down infrastructure:</p> <pre><code>from prefect import flow, get_run_logger, suspend_flow_run\nfrom prefect.blocks.system import JSON\nfrom prefect.context import get_run_context\nfrom prefect.input.run_input import receive_input\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    logger = get_run_logger()\n    run_context = get_run_context()\n    assert run_context.flow_run, \"Could not see my flow run ID\"\n\n    block_name = f\"{run_context.flow_run.id}-seen-ids\"\n\n    try:\n        seen_keys_block = await JSON.load(block_name)\n    except ValueError:\n        seen_keys_block = JSON(\n            value=[],\n        )\n\n    try:\n        async for name_input in receive_input(\n            str,\n            with_metadata=True,\n            poll_interval=0.1,\n            timeout=30,\n            exclude_keys=seen_keys_block.value\n        ):\n            if name_input.value == EXIT_SIGNAL:\n                print(\"Goodbye!\")\n                return\n            await name_input.respond(f\"Hello, {name_input.value}!\")\n\n            seen_keys_block.value.append(name_input.metadata.key)\n            await seen_keys_block.save(\n                name=block_name,\n                overwrite=True\n            )\n    except TimeoutError:\n        logger.info(\"Suspending greeter after 30 seconds of idle time\")\n        await suspend_flow_run(timeout=10000)\n</code></pre> <p>As this flow processes name input, it adds the key of the flow run input to the <code>seen_keys_block</code>. When the flow later suspends and then resumes, it reads the keys it has already seen out of the JSON Block and passes them as the <code>exlude_keys</code> parameter to <code>receive_input</code>.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#responding-to-the-inputs-sender","title":"Responding to the input's sender","text":"<p>When your flow receives input from another flow, Prefect knows the sending flow run ID, so the receiving flow can respond by calling the <code>respond</code> method on the <code>RunInput</code> instance the flow received. There are a couple of requirements:</p> <ol> <li>You will need to pass in a <code>BaseModel</code> or <code>RunInput</code>, or use <code>with_metadata=True</code></li> <li>The flow you are responding to must receive the same type of input you send in order to see it.</li> </ol> <p>The <code>respond</code> method is equivalent to calling <code>send_input(..., flow_run_id=sending_flow_run.id)</code>, but with <code>respond</code>, your flow doesn't need to know the sending flow run's ID.</p> <p>Now that we know about <code>respond</code>, let's make our <code>greeter_flow</code> respond to name inputs instead of printing them:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter():\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        timeout=None\n    ):\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n</code></pre> <p>Cool! There's one problem left: this flow runs forever! We need a way to signal that it should exit. Let's keep things simple and teach it to look for a special string:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        poll_interval=0.1,\n        timeout=None\n    ):\n        if name_input.value == EXIT_SIGNAL:\n            print(\"Goodbye!\")\n            return\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n</code></pre> <p>With a <code>greeter</code> flow in place, we're ready to create the flow that sends <code>greeter</code> names!</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#sending-input","title":"Sending input","text":"<p>You can send input to a flow with the <code>send_input</code> function. This works similarly to <code>receive_input</code> and, like that function, accepts the same <code>run_input</code> argument, which can be a built-in type such as <code>str</code>, or else a <code>BaseModel</code> or <code>RunInput</code> subclass.</p> <p>When can you send input to a flow run?</p> <p>You can send input to a flow run as soon as you have the flow run's ID. The flow does not have to be receiving input for you to send input. If you send a flow input before it is receiving, it will see your input when it calls <code>receive_input</code> (as long as the types in the <code>send_input</code> and <code>receive_input</code> calls match!)</p> <p>Next, we'll create a <code>sender</code> flow that starts a <code>greeter</code> flow run and then enters a loop, continuously getting input from the terminal and sending it to the greeter flow:</p> <pre><code>@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    receiver = receive_input(str, timeout=None, poll_interval=0.1)\n    client = get_client()\n\n    while True:\n        flow_run = await client.read_flow_run(greeter_flow_run.id)\n\n        if not flow_run.state or not flow_run.state.is_running():\n            continue\n\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n        greeting = await receiver.next()\n        print(greeting)\n</code></pre> <p>There's more going on here than in <code>greeter</code>, so let's take a closer look at the pieces.</p> <p>First, we use <code>run_deployment</code> to start a <code>greeter</code> flow run. This means we must have a worker or <code>flow.serve()</code> running in separate process. That process will begin running <code>greeter</code> while <code>sender</code> continues to execute. Calling <code>run_deployment(..., timeout=0)</code> ensures that <code>sender</code> won't wait for the <code>greeter</code> flow run to complete, because it's running a loop and will only exit when we send <code>EXIT_SIGNAL</code>.</p> <p>Next, we capture the iterator returned by <code>receive_input</code> as <code>receiver</code>. This flow works by entering a loop, and on each iteration of the loop, the flow asks for terminal input, sends that to the <code>greeter</code> flow, and then runs <code>receiver.next()</code> to wait until it receives the response from <code>greeter</code>.</p> <p>Next, we let the terminal user who ran this flow exit by entering the string <code>q</code> or <code>quit</code>. When that happens, we send the <code>greeter</code> flow an exit signal so it will shut down too.</p> <p>Finally, we send the new name to <code>greeter</code>. We know that <code>greeter</code> is going to send back a greeting as a string, so we immediately wait for new string input. When we receive the greeting, we print it and continue the loop that gets terminal input.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#seeing-a-complete-example","title":"Seeing a complete example","text":"<p>Finally, let's see a complete example of using <code>send_input</code> and <code>receive_input</code>. Here is what the <code>greeter</code> and <code>sender</code> flows look like together:</p> <pre><code>import asyncio\nimport sys\nfrom prefect import flow, get_client\nfrom prefect.blocks.system import JSON\nfrom prefect.context import get_run_context\nfrom prefect.deployments.deployments import run_deployment\nfrom prefect.input.run_input import receive_input, send_input\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    run_context = get_run_context()\n    assert run_context.flow_run, \"Could not see my flow run ID\"\n\n    block_name = f\"{run_context.flow_run.id}-seen-ids\"\n\n    try:\n        seen_keys_block = await JSON.load(block_name)\n    except ValueError:\n        seen_keys_block = JSON(\n            value=[],\n        )\n\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        poll_interval=0.1,\n        timeout=None\n    ):\n        if name_input.value == EXIT_SIGNAL:\n            print(\"Goodbye!\")\n            return\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n\n        seen_keys_block.value.append(name_input.metadata.key)\n        await seen_keys_block.save(\n            name=block_name,\n            overwrite=True\n        )\n\n\n@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    receiver = receive_input(str, timeout=None, poll_interval=0.1)\n    client = get_client()\n\n    while True:\n        flow_run = await client.read_flow_run(greeter_flow_run.id)\n\n        if not flow_run.state or not flow_run.state.is_running():\n            continue\n\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n        greeting = await receiver.next()\n        print(greeting)\n\n\nif __name__ == \"__main__\":\n    if sys.argv[1] == \"greeter\":\n        asyncio.run(greeter.serve(name=\"send-receive\"))\n    elif sys.argv[1] == \"sender\":\n        asyncio.run(sender())\n</code></pre> <p>To run the example, you'll need a Python environment with Prefect installed, pointed at either an open-source Prefect server instance or Prefect Cloud.</p> <p>With your environment set up, start a flow runner in one terminal with the following command:</p> <pre><code>python my_file_name greeter\n</code></pre> <p>For example, with Prefect Cloud, you should see output like this:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Your flow 'greeter' is being served and polling for scheduled runs!                              \u2502\n\u2502                                                                                                  \u2502\n\u2502 To trigger a run for this flow, use the following command:                                       \u2502\n\u2502                                                                                                  \u2502\n\u2502         $ prefect deployment run 'greeter/send-receive'                                          \u2502\n\u2502                                                                                                  \u2502\n\u2502 You can also run your flow via the Prefect UI:                                                   \u2502\n\u2502 https://app.prefect.cloud/account/...(a URL for your account)                                    \u2502\n\u2502                                                                                                  \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>Then start the greeter process in another terminal:</p> <pre><code>python my_file_name sender\n</code></pre> <p>You should see output like this:</p> <pre><code>11:38:41.800 | INFO    | prefect.engine - Created flow run 'gregarious-owl' for flow 'sender'\n11:38:41.802 | INFO    | Flow run 'gregarious-owl' - View at https://app.prefect.cloud/account/...\nWhat is your name?\n</code></pre> <p>Type a name and press the enter key to see a greeting, and you'll see sending and receiving in action:</p> <pre><code>What is your name? andrew\nHello, andrew!\n</code></pre>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/dask-ray-task-runners/","title":"Dask and Ray Task Runners","text":"<p>Task runners provide an execution environment for tasks. In a flow decorator, you can specify a task runner to run the tasks called in that flow.</p> <p>The default task runner is the <code>ConcurrentTaskRunner</code>.</p> <p>Use <code>.submit</code> to run your tasks asynchronously</p> <p>To run tasks asynchronously use the <code>.submit</code> method when you call them. If you call a task as you would normally in Python code it will run synchronously, even if you are calling the task within a flow that uses the <code>ConcurrentTaskRunner</code>, <code>DaskTaskRunner</code>, or <code>RayTaskRunner</code>.</p> <p>Many real-world data workflows benefit from true parallel, distributed task execution. For these use cases, the following Prefect-developed task runners for parallel task execution may be installed as Prefect Integrations.</p> <ul> <li><code>DaskTaskRunner</code> runs tasks requiring parallel execution using <code>dask.distributed</code>.</li> <li><code>RayTaskRunner</code> runs tasks requiring parallel execution using Ray.</li> </ul> <p>These task runners can spin up a local Dask cluster or Ray instance on the fly, or let you connect with a Dask or Ray environment you've set up separately. Then you can take advantage of massively parallel computing environments.</p> <p>Use Dask or Ray in your flows to choose the execution environment that fits your particular needs.</p> <p>To show you how they work, let's start small.</p> <p>Remote storage</p> <p>We recommend configuring remote file storage for task execution with <code>DaskTaskRunner</code> or <code>RayTaskRunner</code>. This ensures tasks executing in Dask or Ray have access to task result storage, particularly when accessing a Dask or Ray instance outside of your execution environment.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#configure-a-task-runner","title":"Configure a task runner","text":"<p>You may have seen this briefly in a previous tutorial, but let's look a bit more closely at how you can configure a specific task runner for a flow.</p> <p>Let's start with the <code>SequentialTaskRunner</code>. This task runner runs all tasks synchronously and may be useful when used as a debugging tool in conjunction with async code.</p> <p>Let's start with this simple flow. We import the <code>SequentialTaskRunner</code>, specify a <code>task_runner</code> on the flow, and call the tasks with <code>.submit()</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=SequentialTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Save this code as <code>sequential_flow.py</code> and run it.</p> <pre><code>python sequential_flow.py\n</code></pre> <p>If you remove the log messages from the output and just look at the printed output from the task runs, you see they're executed sequentially:</p> <pre><code>hello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#run-tasks-in-parallel-with-dask","title":"Run tasks in parallel with Dask","text":"<p>This basic flow won't benefit from parallel execution, but let's proceed so you can see just how simple it is to use the <code>DaskTaskRunner</code> for more complex flows.</p> <p>Configure your flow to use the <code>DaskTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed by running <code>pip install -U prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> <li>Use the <code>.submit</code> method when calling task-decorated functions.</li> </ol> <p>Example code:</p> <pre><code>from prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=DaskTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Note that, because you're using <code>DaskTaskRunner</code> in a script, you must use <code>if __name__ == \"__main__\":</code> or you'll see warnings and errors.</p> <p>Run <code>dask_flow.py</code>. If you get a warning about accepting incoming network connections, that's okay - everything is local in this example.</p> <pre><code>python dask_flow.py\n</code></pre> <p><code>DaskTaskRunner</code> automatically creates a local Dask cluster, then starts executing all of the task runs in parallel. The results do not return in the same order as the sequential code above.</p> <p>Abbreviated output:</p> <pre><code>goodbye marvin\nhello arthur\ngoodbye ford\nhello trillian\n</code></pre> <p>Notice what happens if you do not use the <code>submit</code> method when calling tasks:</p> <pre><code>from prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=DaskTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello(name)\n        say_goodbye(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Run the script:</p> <pre><code>python dask_flow.py\n</code></pre> <p>Once again, the tasks run sequentially. Here's the output with logs removed.</p> <pre><code>hello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre> <p>The task runs are not submitted to the <code>DaskTaskRunner</code>; instead, they run sequentially.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#run-tasks-in-parallel-with-ray","title":"Run tasks in parallel with Ray","text":"<p>You can easily switch to Ray as another parallel task runner option. Use the <code>RayTaskRunner</code> instead of <code>DaskTaskRunner</code>.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Install <code>prefect-ray</code> into your environment with <code>pip install -U prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Specify the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>Ray environment limitations</p> <p>While we're excited about parallel task execution via Ray, there are a few limitations with Ray you should be aware of:</p> <ul> <li>Support for Python 3.11 is experimental.</li> <li>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</li> <li>Ray's Windows support is currently in beta.</li> </ul> <p>See the Ray installation documentation for further compatibility information.</p> <p>Save this code in <code>ray_flow.py</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n@flow(task_runner=RayTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Now run <code>ray_flow.py</code> <code>RayTaskRunner</code> automatically creates a local Ray instance, then immediately starts executing all of the tasks in parallel. If you have an existing Ray instance, you can provide the address as a parameter to run tasks in the instance. See Running tasks on Ray for details.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#using-multiple-task-runners","title":"Using multiple task runners","text":"<p>Many workflows include a variety of tasks, and not all of them benefit from parallel execution. You'll most likely want to use the Dask or Ray task runners and spin up their respective resources only for those tasks that need them.</p> <p>Because task runners are specified on flows, you can assign different task runners to tasks by using subflows to organize those tasks.</p> <p>This example uses the same tasks as the previous examples, but on the parent flow <code>greetings()</code> we use the default <code>ConcurrentTaskRunner</code>. Then we call a <code>ray_greetings()</code> subflow that uses the <code>RayTaskRunner</code> to execute the same tasks in a Ray instance.</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n@flow(task_runner=RayTaskRunner())\ndef ray_greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\n@flow()\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n    ray_greetings(names)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>If you save this as <code>ray_subflow.py</code> and run it, you'll see that the flow <code>greetings</code> runs as you'd expect for a concurrent flow, then flow <code>ray-greetings</code> spins up a Ray instance to run the tasks again.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/docker/","title":"Running Flows with Docker","text":"<p>In the Deployments tutorial, we looked at serving a flow that enables scheduling or creating flow runs via the Prefect API.</p> <p>With our Python script in hand, we can build a Docker image for our script, allowing us to serve our flow in various remote environments. We'll use Kubernetes in this guide, but you can use any Docker-compatible infrastructure.</p> <p>In this guide we'll:</p> <ul> <li>Write a Dockerfile to build an image that stores our Prefect flow code.</li> <li>Build a Docker image for our flow.</li> <li>Deploy and run our Docker image on a Kubernetes cluster.</li> <li>Look at the Prefect-maintained Docker images and discuss options for use</li> </ul> <p>Note that in this guide we'll create a Dockerfile from scratch. Alternatively, Prefect makes it convenient to build a Docker image as part of deployment creation. You can even include environment variables and specify additional Python packages to install at runtime.</p> <p>If creating a deployment with a <code>prefect.yaml</code> file, the build step makes it easy to customize your Docker image and push it to the registry of your choice. See an example here.</p> <p>Deployment creation with a Python script that includes <code>flow.deploy</code> similarly allows you to customize your Docker image with keyword arguments as shown below.</p> <pre><code>...\n\nif __name__ == \"__main__\":\n    hello_world.deploy(\n        name=\"my-first-deployment\",\n        work_pool_name=\"above-ground\",\n        image='my_registry/hello_world:demo',\n        job_variables={\"env\": { \"EXTRA_PIP_PACKAGES\": \"boto3\" } }\n    )\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#prerequisites","title":"Prerequisites","text":"<p>To complete this guide, you'll need the following:</p> <ul> <li>A Python script that defines and serves a flow.</li> <li>We'll use the flow script and deployment from the Deployments tutorial.</li> <li>Access to a running Prefect API server.</li> <li>You can sign up for a forever free Prefect Cloud account or run a Prefect API server locally with <code>prefect server start</code>.</li> <li>Docker Desktop installed on your machine.</li> </ul>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#writing-a-dockerfile","title":"Writing a Dockerfile","text":"<p>First let's make a clean directory to work from, <code>prefect-docker-guide</code>.</p> <pre><code>mkdir prefect-docker-guide\ncd prefect-docker-guide\n</code></pre> <p>In this directory, we'll create a sub-directory named <code>flows</code> and put our flow script from the Deployments tutorial in it.</p> <pre><code>mkdir flows\ncd flows\ntouch prefect-docker-guide-flow.py\n</code></pre> <p>Here's the flow code for reference:</p> prefect-docker-guide-flow.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.serve(name=\"prefect-docker-guide\")\n</code></pre> <p>The next file we'll add to the <code>prefect-docker-guide</code> directory is a <code>requirements.txt</code>. We'll include all dependencies required for our <code>prefect-docker-guide-flow.py</code> script in the Docker image we'll build.</p> <pre><code># ensure you run this line from the top level of the `prefect-docker-guide` directory\ntouch requirements.txt\n</code></pre> <p>Here's what we'll put in our <code>requirements.txt</code> file:</p> requirements.txt<pre><code>prefect&gt;=2.12.0\nhttpx\n</code></pre> <p>Next, we'll create a <code>Dockerfile</code> that we'll use to create a Docker image that will also store the flow code.</p> <pre><code>touch Dockerfile\n</code></pre> <p>We'll add the following content to our <code>Dockerfile</code>:</p> Dockerfile<pre><code># We're using the latest version of Prefect with Python 3.10\nFROM prefecthq/prefect:2-python3.10\n\n# Add our requirements.txt file to the image and install dependencies\nCOPY requirements.txt .\nRUN pip install -r requirements.txt --trusted-host pypi.python.org --no-cache-dir\n\n# Add our flow code to the image\nCOPY flows /opt/prefect/flows\n\n# Run our flow script when the container starts\nCMD [\"python\", \"flows/prefect-docker-guide-flow.py\"]\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#building-a-docker-image","title":"Building a Docker image","text":"<p>Now that we have a Dockerfile we can build our image by running:</p> <pre><code>docker build -t prefect-docker-guide-image .\n</code></pre> <p>We can check that our build worked by running a container from our new image.</p> CloudSelf-hosted <p>Our container will need an API URL and and API key to communicate with Prefect Cloud. </p> <ul> <li> <p>You can get an API key from the API Keys section of the user settings in the Prefect UI. </p> </li> <li> <p>You can get your API URL by running <code>prefect config view</code> and copying the <code>PREFECT_API_URL</code> value.</p> </li> </ul> <p>We'll provide both these values to our container by passing them as environment variables with the <code>-e</code> flag.</p> <pre><code>docker run -e PREFECT_API_URL=YOUR_PREFECT_API_URL -e PREFECT_API_KEY=YOUR_API_KEY prefect-docker-guide-image\n</code></pre> <p>After running the above command, the container should start up and serve the flow within the container!</p> <p>Our container will need an API URL and network access to communicate with the Prefect API. </p> <p>For this guide, we'll assume the Prefect API is running on the same machine that we'll run our container on and the Prefect API was started with <code>prefect server start</code>. If you're running a different setup, check out the Hosting a Prefect server guide for information on how to connect to your Prefect API instance.</p> <p>To ensure that our flow container can communicate with the Prefect API, we'll set our <code>PREFECT_API_URL</code> to <code>http://host.docker.internal:4200/api</code>. If you're running Linux, you'll need to set your <code>PREFECT_API_URL</code> to <code>http://localhost:4200/api</code> and use the <code>--network=\"host\"</code> option instead.</p> <pre><code>docker run --network=\"host\" -e PREFECT_API_URL=http://host.docker.internal:4200/api prefect-docker-guide-image\n</code></pre> <p>After running the above command, the container should start up and serve the flow within the container!</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#deploying-to-a-remote-environment","title":"Deploying to a remote environment","text":"<p>Now that we have a Docker image with our flow code embedded, we can deploy it to a remote environment!</p> <p>For this guide, we'll simulate a remote environment by using Kubernetes locally with Docker Desktop. You can use the instructions provided by Docker to set up Kubernetes locally.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#creating-a-kubernetes-deployment-manifest","title":"Creating a Kubernetes deployment manifest","text":"<p>To ensure the process serving our flow is always running, we'll create a Kubernetes deployment. If our flow's container ever crashes, Kubernetes will automatically restart it, ensuring that we won't miss any scheduled runs.</p> <p>First, we'll create a <code>deployment-manifest.yaml</code> file in our <code>prefect-docker-guide</code> directory:</p> <pre><code>touch deployment-manifest.yaml\n</code></pre> <p>And we'll add the following content to our <code>deployment-manifest.yaml</code> file:</p> CloudSelf-hosted deployment-manifest.yaml<pre><code>apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: prefect-docker-guide\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      flow: get-repo-info\n  template:\n    metadata:\n      labels:\n        flow: get-repo-info\n    spec:\n      containers:\n      - name: flow-container\n        image: prefect-docker-guide-image:latest\n        env:\n        - name: PREFECT_API_URL\n          value: YOUR_PREFECT_API_URL\n        - name: PREFECT_API_KEY\n          value: YOUR_API_KEY\n        # Never pull the image because we're using a local image\n        imagePullPolicy: Never\n</code></pre> <p>Keep your API key secret</p> <p>In the above manifest we are passing in the Prefect API URL and API key as environment variables. This approach is simple, but it is not secure. If you are deploying your flow to a remote cluster, you should use a Kubernetes secret to store your API key.</p> deployment-manifest.yaml<pre><code>apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: prefect-docker-guide\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      flow: get-repo-info\n  template:\n    metadata:\n      labels:\n        flow: get-repo-info\n    spec:\n      containers:\n      - name: flow-container\n        image: prefect-docker-guide-image:latest\n        env:\n        - name: PREFECT_API_URL\n          value: &lt;http://host.docker.internal:4200/api&gt;\n        # Never pull the image because we're using a local image\n        imagePullPolicy: Never\n</code></pre> <p>Linux users</p> <p>If you're running Linux, you'll need to set your <code>PREFECT_API_URL</code> to use the IP address of your machine instead of <code>host.docker.internal</code>.</p> <p>This manifest defines how our image will run when deployed in our Kubernetes cluster. Note that we will be running a single replica of our flow container. If you want to run multiple replicas of your flow container to keep up with an active schedule, or because our flow is resource-intensive, you can increase the <code>replicas</code> value.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#deploying-our-flow-to-the-cluster","title":"Deploying our flow to the cluster","text":"<p>Now that we have a deployment manifest, we can deploy our flow to the cluster by running:</p> <pre><code>kubectl apply -f deployment-manifest.yaml\n</code></pre> <p>We can monitor the status of our Kubernetes deployment by running:</p> <pre><code>kubectl get deployments\n</code></pre> <p>Once the deployment has successfully started, we can check the logs of our flow container by running the following:</p> <pre><code>kubectl logs -l flow=get-repo-info\n</code></pre> <p>Now that we're serving our flow in our cluster, we can trigger a flow run by running:</p> <pre><code>prefect deployment run get-repo-info/prefect-docker-guide\n</code></pre> <p>If we navigate to the URL provided by the <code>prefect deployment run</code> command, we can follow the flow run via the logs in the Prefect UI!</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#prefect-maintained-docker-images","title":"Prefect-maintained Docker images","text":"<p>Every release of Prefect results in several new Docker images. These images are all named prefecthq/prefect and their tags identify their differences.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#image-tags","title":"Image tags","text":"<p>When a release is published, images are built for all of Prefect's supported Python versions. These images are tagged to identify the combination of Prefect and Python versions contained. Additionally, we have \"convenience\" tags which are updated with each release to facilitate automatic updates.</p> <p>For example, when release <code>2.11.5</code> is published:</p> <ol> <li>Images with the release packaged are built for each supported Python version (3.8, 3.9, 3.10, 3.11) with both standard Python and Conda.</li> <li>These images are tagged with the full description, e.g. <code>prefect:2.1.1-python3.10</code> and <code>prefect:2.1.1-python3.10-conda</code>.</li> <li>For users that want more specific pins, these images are also tagged with the SHA of the git commit of the release, e.g. <code>sha-88a7ff17a3435ec33c95c0323b8f05d7b9f3f6d2-python3.10</code></li> <li>For users that want to be on the latest <code>2.1.x</code> release, receiving patch updates, we update a tag without the patch version to this release, e.g. <code>prefect.2.1-python3.10</code>.</li> <li>For users that want to be on the latest <code>2.x.y</code> release, receiving minor version updates, we update a tag without the minor or patch version to this release, e.g. <code>prefect.2-python3.10</code></li> <li>Finally, for users who want the latest <code>2.x.y</code> release without specifying a Python version, we update <code>2-latest</code> to the image for our highest supported Python version, which in this case would be equivalent to <code>prefect:2.1.1-python3.10</code>.</li> </ol> <p>Choose image versions carefully</p> <p>It's a good practice to use Docker images with specific Prefect versions in production.</p> <p>Use care when employing images that automatically update to new versions (such as <code>prefecthq/prefect:2-python3.11</code> or <code>prefecthq/prefect:2-latest</code>).</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#standard-python","title":"Standard Python","text":"<p>Standard Python images are based on the official Python <code>slim</code> images, e.g. <code>python:3.10-slim</code>.</p> Tag Prefect Version Python Version 2-latest most recent v2 PyPi version 3.10 2-python3.11 most recent v2 PyPi version 3.11 2-python3.10 most recent v2 PyPi version 3.10 2-python3.9 most recent v2 PyPi version 3.9 2-python3.8 most recent v2 PyPi version 3.8 2.X-python3.11 2.X 3.11 2.X-python3.10 2.X 3.10 2.X-python3.9 2.X 3.9 2.X-python3.8 2.X 3.8 sha-&lt;hash&gt;-python3.11 &lt;hash&gt; 3.11 sha-&lt;hash&gt;-python3.10 &lt;hash&gt; 3.10 sha-&lt;hash&gt;-python3.9 &lt;hash&gt; 3.9 sha-&lt;hash&gt;-python3.8 &lt;hash&gt; 3.8","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#conda-flavored-python","title":"Conda-flavored Python","text":"<p>Conda flavored images are based on <code>continuumio/miniconda3</code>. Prefect is installed into a conda environment named <code>prefect</code>.</p> Tag Prefect Version Python Version 2-latest-conda most recent v2 PyPi version 3.10 2-python3.11-conda most recent v2 PyPi version 3.11 2-python3.10-conda most recent v2 PyPi version 3.10 2-python3.9-conda most recent v2 PyPi version 3.9 2-python3.8-conda most recent v2 PyPi version 3.8 2.X-python3.11-conda 2.X 3.11 2.X-python3.10-conda 2.X 3.10 2.X-python3.9-conda 2.X 3.9 2.X-python3.8-conda 2.X 3.8 sha-&lt;hash&gt;-python3.11-conda &lt;hash&gt; 3.11 sha-&lt;hash&gt;-python3.10-conda &lt;hash&gt; 3.10 sha-&lt;hash&gt;-python3.9-conda &lt;hash&gt; 3.9 sha-&lt;hash&gt;-python3.8-conda &lt;hash&gt; 3.8","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#building-your-own-image","title":"Building your own image","text":"<p>If your flow relies on dependencies not found in the default <code>prefecthq/prefect</code> images, you may want to build your own image. You can either base it off of one of the provided <code>prefecthq/prefect</code> images, or build your own image. See the Work pool deployment guide for discussion of how Prefect can help you build custom images with dependencies specified in a <code>requirements.txt</code> file.</p> <p>By default, Prefect work pools that use containers refer to the <code>2-latest</code> image. You can specify another image at work pool creation. The work pool image choice can be overridden in individual deployments.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#extending-the-prefecthqprefect-image-manually","title":"Extending the <code>prefecthq/prefect</code> image manually","text":"<p>Here we provide an example <code>Dockerfile</code> for building an image based on <code>prefecthq/prefect:2-latest</code>, but with <code>scikit-learn</code> installed.</p> <pre><code>FROM prefecthq/prefect:2-latest\n\nRUN pip install scikit-learn\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#choosing-an-image-strategy","title":"Choosing an image strategy","text":"<p>The options described above have different complexity (and performance) characteristics. For choosing a strategy, we provide the following recommendations:</p> <ul> <li> <p>If your flow only makes use of tasks defined in the same file as the flow, or tasks that are part of <code>prefect</code> itself, then you can rely on the default provided <code>prefecthq/prefect</code> image.</p> </li> <li> <p>If your flow requires a few extra dependencies found on PyPI, you can use the default <code>prefecthq/prefect</code> image and set <code>prefect.deployments.steps.pip_install_requirements:</code> in the <code>pull</code>step to install these dependencies at runtime.</p> </li> <li> <p>If the installation process requires compiling code or other expensive operations, you may be better off building a custom image instead.</p> </li> <li> <p>If your flow (or flows) require extra dependencies or shared libraries, we recommend building a shared custom image with all the extra dependencies and shared task definitions you need. Your flows can then all rely on the same image, but have their source stored externally. This option can ease development, as the shared image only needs to be rebuilt when dependencies change, not when the flow source changes.</p> </li> </ul>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#next-steps","title":"Next steps","text":"<p>We only served a single flow in this guide, but you can extend this setup to serve multiple flows in a single Docker image by updating your Python script to using <code>flow.to_deployment</code> and <code>serve</code> to serve multiple flows or the same flow with different configuration.</p> <p>To learn more about deploying flows, check out the Deployments concept doc!</p> <p>For advanced infrastructure requirements, such as executing each flow run within its own dedicated Docker container, learn more in the Work pool deployment guide.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/global-concurrency-limits/","title":"Global Concurrency Limits and Rate Limits","text":"<p>Global concurrency limits allow you to manage execution efficiently, controlling how many tasks, flows, or other operations can run simultaneously. They are ideal when optimizing resource usage, preventing bottlenecks, and customizing task execution are priorities.</p> <p>Clarification on use of the term 'tasks'</p> <p>In the context of global concurrency and rate limits, \"tasks\" refers not specifically to Prefect tasks, but to concurrent units of work in general, such as those managed by an event loop or <code>TaskGroup</code> in asynchronous programming. These general \"tasks\" could include Prefect tasks when they are part of an asynchronous execution environment.</p> <p>Rate Limits ensure system stability by governing the frequency of requests or operations. They are suitable for preventing overuse, ensuring fairness, and handling errors gracefully.</p> <p>When selecting between Concurrency and Rate Limits, consider your primary goal. Choose Concurrency Limits for resource optimization and task management. Choose Rate Limits to maintain system stability and fair access to services.</p> <p>The core difference between a rate limit and a concurrency limit is the way in which slots are released. With a rate limit, slots are released at a controlled rate, controlled by <code>slot_decay_per_second</code> whereas with a concurrency limit, slots are released when the concurrency manager is exited.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#managing-global-concurrency-limits-and-rate-limits","title":"Managing Global concurrency limits and rate limits","text":"","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#active-vs-inactive-limits","title":"Active vs inactive limits","text":"<p>Global concurrency limits can be in either an <code>active</code> or <code>inactive</code> state.</p> <ul> <li>Active: In this state, slots can be occupied, and code execution will be blocked when slots are unable to be acquired.</li> <li>Inactive: In this state, slots will not be occupied, and code execution will not be blocked. Concurrency enforcement occurs only when you activate the limit.</li> </ul>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#slot-decay","title":"Slot decay","text":"<p>Global concurrency limits can be configured with slot decay. This is used when the concurrency limit is used as a rate limit, and it governs the pace at which slots are released or become available for reuse after being occupied. These slots effectively represent the concurrency capacity within a specific concurrency limit. The concept is best understood as the rate at which these slots \"decay\" or refresh.</p> <p>To configure slot decay, you can set the <code>slot_decay_per_second</code> parameter when defining or adjusting a concurrency limit.</p> <p>For practical use, consider the following:</p> <ul> <li> <p>Higher values: Setting <code>slot_decay_per_second</code> to a higher value, such as 5.0, results in slots becoming available relatively quickly. In this scenario, a slot that was occupied by a task will free up after just <code>0.2</code> (<code>1.0 / 5.0</code>) seconds.</p> </li> <li> <p>Lower values: Conversely, setting <code>slot_decay_per_second</code> to a lower value, like 0.1, causes slots to become available more slowly. In this scenario it would take <code>10</code> (<code>1.0 / 0.1</code>) seconds for a slot to become available again after occupancy</p> </li> </ul> <p>Slot decay provides fine-grained control over the availability of slots, enabling you to optimize the rate of your workflow based on your specific requirements.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#via-the-ui","title":"Via the UI","text":"<p>You can create, read, edit, and delete concurrency limits via the Prefect UI.</p> <p>When creating a concurrency limit, you can specify the following parameters:</p> <ul> <li>Name: The name of the concurrency limit. This name is also how you'll reference the concurrency limit in your code. Special characters, such as <code>/</code>, <code>%</code>, <code>&amp;</code>, <code>&gt;</code>, <code>&lt;</code>, are not allowed.</li> <li>Concurrency Limit: The maximum number of slots that can be occupied on this concurrency limit.</li> <li>Slot Decay Per Second: Controls the rate at which slots are released when the concurrency limit is used as a rate limit. This value must be configured when using the <code>rate_limit</code> function.</li> <li>Active Slots: The number of slots currently in use by clients. Prefect manages this field automatically, but you can set it to 0 to reset the limit if necessary.</li> <li>Active: Whether or not the concurrency limit is in an active state.</li> </ul>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#via-the-cli","title":"Via the CLI","text":"<p>You can create, read, edit, and delete global concurrency limits via the Prefect CLI.</p> <p>To create a new concurrency limit, use the <code>prefect gcl create</code> command. You must specify a <code>--limit</code> argument, and can optionally specify a <code>--slot-decay-per-second</code> and <code>--disable</code> argument.</p> <pre><code>prefect gcl create my-concurrency-limit --limit 5 --slot-decay-per-second 1.0\n</code></pre> <p>You can inspect the details of a concurrency limit using the <code>prefect gcl inspect</code> command:</p> <pre><code>prefect gcl inspect my-concurrency-limit\n</code></pre> <p>To update a concurrency limit, use the <code>prefect gcl update</code> command. You can update the <code>--limit</code>, <code>--slot-decay-per-second</code>, <code>--enable</code>, and <code>--disable</code> arguments:</p> <pre><code>prefect gcl update my-concurrency-limit --limit 10\n</code></pre> <pre><code>prefect gcl update my-concurrency-limit --disable\n</code></pre> <p>To delete a concurrency limit, use the <code>prefect gcl delete</code> command:</p> <pre><code>prefect gcl delete my-concurrency-limit\nAre you sure you want to delete global concurrency limit 'my-concurrency-limit'? [y/N]: y\nDeleted global concurrency limit with name 'my-concurrency-limit'.\n</code></pre> <p>See all available commands and options by running <code>prefect gcl --help</code>.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-the-concurrency-context-manager","title":"Using the <code>concurrency</code> context manager","text":"<p>The <code>concurrency</code>context manager allows control over the maximum number of concurrent operations. You can select either the synchronous (<code>sync</code>) or asynchronous (<code>async</code>) version, depending on your use case. Here's how to use it:</p> <p>Concurrency limits are implicitly created</p> <p>When using the <code>concurrency</code> context manager, the concurrency limit you use will be created, in an inactive state, if it does not already exist.</p> <p>Sync</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import concurrency\n\n\n@task\ndef process_data(x, y):\n    with concurrency(\"database\", occupy=1):\n        return x + y\n\n\n@flow\ndef my_flow():\n    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:\n        process_data.submit(x, y)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Async</p> <pre><code>import asyncio\nfrom prefect import flow, task\nfrom prefect.concurrency.asyncio import concurrency\n\n\n@task\nasync def process_data(x, y):\n    async with concurrency(\"database\", occupy=1):\n        return x + y\n\n\n@flow\nasync def my_flow():\n    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:\n        await process_data.submit(x, y)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(my_flow())\n</code></pre> <ol> <li>The code imports the necessary modules and the concurrency context manager. Use the <code>prefect.concurrency.sync</code> module for sync usage and the <code>prefect.concurrency.asyncio</code> module for async usage.</li> <li>It defines a <code>process_data</code> task, taking <code>x</code> and <code>y</code> as input arguments. Inside this task, the concurrency context manager controls concurrency, using the <code>database</code> concurrency limit and occupying one slot. If another task attempts to run with the same limit and no slots are available, that task will be blocked until a slot becomes available.</li> <li>A flow named <code>my_flow</code> is defined. Within this flow, it iterates through a list of tuples, each containing pairs of x and y values. For each pair, the <code>process_data</code> task is submitted with the corresponding x and y values for processing.</li> </ol>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-rate_limit","title":"Using <code>rate_limit</code>","text":"<p>The Rate Limit feature provides control over the frequency of requests or operations, ensuring responsible usage and system stability. Depending on your requirements, you can utilize <code>rate_limit</code> to govern both synchronous (sync) and asynchronous (async) operations. Here's how to make the most of it:</p> <p>Slot decay</p> <p>When using the <code>rate_limit</code> function the concurrency limit you use must have a slot decay configured.</p> <p>Sync</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import rate_limit\n\n\n@task\ndef make_http_request():\n    rate_limit(\"rate-limited-api\")\n    print(\"Making an HTTP request...\")\n\n\n@flow\ndef my_flow():\n    for _ in range(10):\n        make_http_request.submit()\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Async</p> <pre><code>import asyncio\n\nfrom prefect import flow, task\nfrom prefect.concurrency.asyncio import rate_limit\n\n\n@task\nasync def make_http_request():\n    await rate_limit(\"rate-limited-api\")\n    print(\"Making an HTTP request...\")\n\n\n@flow\nasync def my_flow():\n    for _ in range(10):\n        await make_http_request.submit()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(my_flow())\n</code></pre> <ol> <li>The code imports the necessary modules and the <code>rate_limit</code> function. Use the <code>prefect.concurrency.sync</code> module for sync usage and the <code>prefect.concurrency.asyncio</code> module for async usage.</li> <li>It defines a <code>make_http_request</code> task. Inside this task, the <code>rate_limit</code> function is used to ensure that the requests are made at a controlled pace.</li> <li>A flow named <code>my_flow</code> is defined. Within this flow the <code>make_http_request</code> task is submitted 10 times.</li> </ol>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-concurrency-and-rate_limit-outside-of-a-flow","title":"Using <code>concurrency</code> and <code>rate_limit</code> outside of a flow","text":"<p><code>concurreny</code> and <code>rate_limit</code> can be used outside of a flow to control concurrency and rate limits for any operation.</p> <pre><code>import asyncio\n\nfrom prefect.concurrency.asyncio import rate_limit\n\n\nasync def main():\n    for _ in range(10):\n        await rate_limit(\"rate-limited-api\")\n        print(\"Making an HTTP request...\")\n\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#use-cases","title":"Use cases","text":"","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#throttling-task-submission","title":"Throttling task submission","text":"<p>Throttling task submission to avoid overloading resources, to comply with external rate limits, or ensure a steady, controlled flow of work.</p> <p>In this scenario the <code>rate_limit</code> function is used to throttle the submission of tasks. The rate limit acts as a bottleneck, ensuring that tasks are submitted at a controlled rate, governed by the <code>slot_decay_per_second</code> setting on the associated concurrency limit.</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import rate_limit\n\n\n@task\ndef my_task(i):\n    return i\n\n\n@flow\ndef my_flow():\n    for _ in range(100):\n        rate_limit(\"slow-my-flow\", occupy=1)\n        my_task.submit(1)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#managing-database-connections","title":"Managing database connections","text":"<p>Managing the maximum number of concurrent database connections to avoid exhausting database resources.</p> <p>In this scenario we've setup a concurrency limit named <code>database</code> and given it a maximum concurrency limit that matches the maximum number of database connections we want to allow. We then use the <code>concurrency</code> context manager to control the number of database connections allowed at any one time.</p> <pre><code>from prefect import flow, task, concurrency\nimport psycopg2\n\n@task\ndef database_query(query):\n    # Here we request a single slot on the 'database' concurrency limit. This\n    # will block in the case that all of the database connections are in use\n    # ensuring that we never exceed the maximum number of database connections.\n    with concurrency(\"database\", occupy=1):\n        connection = psycopg2.connect(\"&lt;connection_string&gt;\")\n        cursor = connection.cursor()\n        cursor.execute(query)\n        result = cursor.fetchall()\n        connection.close()\n        return result\n\n@flow\ndef my_flow():\n    queries = [\"SELECT * FROM table1\", \"SELECT * FROM table2\", \"SELECT * FROM table3\"]\n\n    for query in queries:\n        database_query.submit(query)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#parallel-data-processing","title":"Parallel data processing","text":"<p>Limiting the maximum number of parallel processing tasks.</p> <p>In this scenario we want to limit the number of <code>process_data</code> tasks to five at any one time. We do this by using the <code>concurrency</code> context manager to request five slots on the <code>data-processing</code> concurrency limit. This will block until five slots are free and then submit five more tasks, ensuring that we never exceed the maximum number of parallel processing tasks.</p> <pre><code>import asyncio\nfrom prefect.concurrency.sync import concurrency\n\n\nasync def process_data(data):\n    print(f\"Processing: {data}\")\n    await asyncio.sleep(1)\n    return f\"Processed: {data}\"\n\n\nasync def main():\n    data_items = list(range(100))\n    processed_data = []\n\n    while data_items:\n        with concurrency(\"data-processing\", occupy=5):\n            chunk = [data_items.pop() for _ in range(5)]\n            processed_data += await asyncio.gather(\n                *[process_data(item) for item in chunk]\n            )\n\n    print(processed_data)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/host/","title":"Host a Prefect server instance","text":"<p>Learn how to host your own Prefect server instance.</p> <p>Note</p> <p>If you would like to host a Prefect server instance on Kubernetes, check out the prefect-server Helm chart.</p> <p>After installing Prefect, you have:</p> <ul> <li>a Python SDK client that can communicate with Prefect Cloud</li> <li>an API server instance backed by a database and a UI</li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#steps","title":"Steps","text":"<ol> <li>Spin up a local Prefect server UI with the <code>prefect server start</code> CLI command in the terminal:</li> </ol> <pre><code>prefect server start\n</code></pre> <ol> <li>Open the URL for the Prefect server UI (http://127.0.0.1:4200 by default) in a browser.</li> </ol> <ol> <li>Shut down the Prefect server with  ctrl  +  c  in the terminal.","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#comparing-a-self-hosted-prefect-server-instance-and-prefect-cloud","title":"Comparing a self-hosted Prefect server instance and Prefect Cloud","text":"<p>A self-hosted Prefect server instance and Prefect Cloud share a common set of features. Prefect Cloud includes the following additional features:</p> <ul> <li>Workspaces \u2014 isolated environments to organize your flows, deployments, and flow runs.</li> <li>Automations \u2014 configure triggers, actions, and notifications in response to real-time monitoring events.</li> <li>Email notifications \u2014 send email alerts from Prefect's servers based on automation triggers.</li> <li>Service accounts \u2014 configure API access for running workers or executing flow runs on remote infrastructure.</li> <li>Custom role-based access controls (RBAC) \u2014 assign users granular permissions to perform activities within an account or workspace.</li> <li>Single Sign-on (SSO) \u2014 authentication using your identity provider.</li> <li>Audit Log \u2014 a record of user activities to monitor security and compliance.</li> </ul> <p>Read more about Prefect Cloud in the Cloud section.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-a-prefect-server-instance","title":"Configure a Prefect server instance","text":"<p>Go to your terminal session and run this command to set the API URL to point to a Prefect server instance:</p> <pre><code>prefect config set PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n</code></pre> <p><code>PREFECT_API_URL</code> required when running Prefect inside a container</p> <p>You must set the API server address to use Prefect within a container, such as a Docker container.</p> <p>You can save the API server address in a Prefect profile. Whenever that profile is active, the API endpoint is at that address.</p> <p>See Profiles &amp; Configuration for more information on profiles and configurable Prefect settings.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#the-prefect-database","title":"The Prefect database","text":"<p>The Prefect database persists data to track the state of your flow runs and related Prefect concepts, including:</p> <ul> <li>Flow run and task run state</li> <li>Run history</li> <li>Logs</li> <li>Deployments</li> <li>Flow and task run concurrency limits</li> <li>Storage blocks for flow and task results</li> <li>Variables</li> <li>Artifacts</li> <li>Work pool status</li> </ul> <p>Currently Prefect supports the following databases:</p> <ul> <li>SQLite (default in Prefect): Recommended for lightweight, single-server deployments. SQLite requires essentially no setup.</li> <li>PostgreSQL: Best for connecting to external databases, but requires additional setup (such as Docker). Prefect uses the <code>pg_trgm</code> extension, so it must be installed and enabled.</li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#using-the-database","title":"Using the database","text":"<p>A local SQLite database is the default database and is configured upon Prefect installation. The database is located at <code>~/.prefect/prefect.db</code> by default.</p> <p>To reset your database, run the CLI command:  </p> <pre><code>prefect server database reset -y\n</code></pre> <p>This command clears all data and reapplies the schema.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#database-settings","title":"Database settings","text":"<p>Prefect provides several settings for configuring the database. The default settings are:</p> <pre><code>PREFECT_API_DATABASE_CONNECTION_URL='sqlite+aiosqlite:///${PREFECT_HOME}/prefect.db'\nPREFECT_API_DATABASE_ECHO='False'\nPREFECT_API_DATABASE_MIGRATE_ON_START='True'\nPREFECT_API_DATABASE_PASSWORD='None'\n</code></pre> <p>Save a setting to your active Prefect profile with <code>prefect config set</code>.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-a-postgresql-database","title":"Configure a PostgreSQL database","text":"<p>Connect Prefect to a PostgreSQL database by setting the following environment variable:</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"postgresql+asyncpg://postgres:yourTopSecretPassword@localhost:5432/prefect\"\n</code></pre> <p>The above environment variable assumes:</p> <ul> <li>You have a username called <code>postgres</code></li> <li>Your password is set to <code>yourTopSecretPassword</code></li> <li>Your database runs on the same host as the Prefect server instance, <code>localhost</code></li> <li>You use the default PostgreSQL port <code>5432</code></li> <li>Your PostgreSQL instance has a database called <code>prefect</code></li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#quickstart-configure-a-postgresql-database-with-docker","title":"Quickstart: configure a PostgreSQL database with Docker","text":"<p>Quickly start a PostgreSQL instance to use as your Prefect database with the following command (which will start a Docker container running PostgreSQL):</p> <pre><code>docker run -d --name prefect-postgres -v prefectdb:/var/lib/postgresql/data -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=yourTopSecretPassword -e POSTGRES_DB=prefect postgres:latest\n</code></pre> <p>The above command:</p> <ul> <li>Pulls the latest version of the official <code>postgres</code> Docker image, which is compatible with Prefect.</li> <li>Starts a container with the name <code>prefect-postgres</code>.</li> <li>Creates a database <code>prefect</code> with a user <code>postgres</code> and <code>yourTopSecretPassword</code> password.</li> <li>Mounts the PostgreSQL data to a Docker volume called <code>prefectdb</code> to provide persistence if you ever have to restart or rebuild that container.</li> </ul> <p>Run the command below to set your current Prefect Profile to the PostgreSQL database instance running in your Docker container.</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"postgresql+asyncpg://postgres:yourTopSecretPassword@localhost:5432/prefect\"\n</code></pre>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#confirm-your-postgresql-database-configuration","title":"Confirm your PostgreSQL database configuration","text":"<p>Inspect your Prefect profile to confirm that the environment variable has been properly set:</p> <pre><code>prefect config view --show-sources\n</code></pre> <pre><code>You should see output similar to the following:\n\nPREFECT_PROFILE='my_profile'\nPREFECT_API_DATABASE_CONNECTION_URL='********' (from profile)\nPREFECT_API_URL='http://127.0.0.1:4200/api' (from profile)\n</code></pre> <p>Start the Prefect server to use your PostgreSQL database instance:</p> <pre><code>prefect server start\n</code></pre>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#in-memory-database","title":"In-memory database","text":"<p>To use an in-memory SQLite database, set the following environment variable:</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"sqlite+aiosqlite:///file::memory:?cache=shared&amp;uri=true&amp;check_same_thread=false\"\n</code></pre> <p>Use SQLite database for testing only</p> <p>SQLite is only supported by Prefect for testing purposes and is not compatible with multiprocessing.  </p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#migrations","title":"Migrations","text":"<p>Prefect uses Alembic to manage database migrations. Alembic is a database migration tool to use with the SQLAlchemy Database Toolkit for Python. Alembic provides a framework for generating and applying schema changes to a database.</p> <p>Apply migrations to your database with the following commands:</p> <p>To upgrade:</p> <pre><code>prefect server database upgrade -y\n</code></pre> <p>To downgrade:</p> <pre><code>prefect server database downgrade -y\n</code></pre> <p>Use the <code>-r</code> flag to specify a specific migration version to upgrade or downgrade to. For example, to downgrade to the previous migration version, run:</p> <pre><code>prefect server database downgrade -y -r -1\n</code></pre> <p>or to downgrade to a specific revision:</p> <pre><code>prefect server database downgrade -y -r d20618ce678e\n</code></pre> <p>To downgrade all migrations, use the <code>base</code> revision.</p> <p>See the contributing docs to create new database migrations.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#notifications","title":"Notifications","text":"<p>Prefect Cloud gives you access to a hosted platform with Workspace &amp; User controls, Events, and Automations. Prefect Cloud has an option for automation notifications. The more limited Notifications option is provided for the self-hosted Prefect server.</p> <p>Notifications enable you to set up alerts that are sent when a flow enters any state you specify. When your flow and task runs changes state, Prefect notes the state change and checks whether the new state matches any notification policies. If it does, a new notification is queued.</p> <p>Prefect supports sending notifications through:</p> <ul> <li>Custom webhook</li> <li>Discord webhook</li> <li>Mattermost webhook</li> <li>Microsoft Teams webhook</li> <li>Opsgenie webhook</li> <li>PagerDuty webhook</li> <li>Sendgrid email</li> <li>Slack webhook</li> <li>Twilio SMS</li> </ul> <p>Notifications in Prefect Cloud</p> <p>Prefect Cloud uses the robust Automations interface to enable notifications related to flow run state changes and work pool status.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-notifications","title":"Configure notifications","text":"<p>To configure a notification in a Prefect server, go to the Notifications page and select Create Notification or the + button.</p> <p></p> <p>You can choose:</p> <ul> <li>Which run states should trigger a notification</li> <li>Tags to filter which flow runs are covered by the notification</li> <li>Whether to send an email, a Slack message, Microsoft Teams message, or use another services</li> </ul> <p>For email notifications (supported on Prefect Cloud only), the configuration requires email addresses to which the message is sent.</p> <p>For Slack notifications, the configuration requires webhook credentials for your Slack and the channel to which the message is sent.</p> <p>For example, to get a Slack message if a flow with a <code>daily-etl</code> tag fails, the notification will read:</p> <p>If a run of any flow with daily-etl tag enters a failed state, send a notification to my-slack-webhook</p> <p>When the conditions of the notification are triggered, you\u2019ll receive a message:</p> <p>The fuzzy-leopard run of the daily-etl flow entered a failed state at 22-06-27 16:21:37 EST.</p> <p>On the Notifications page you can pause, edit, or delete any configured notification.</p> <p></p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/logs/","title":"Logging","text":"<p>Prefect enables you to log a variety of useful information about your flow and task runs, capturing information about your workflows for purposes such as monitoring, troubleshooting, and auditing.</p> <p>Prefect captures logs for your flow and task runs by default, even if you have not started a Prefect server with <code>prefect server start</code>.</p> <p>You can view and filter logs in the Prefect UI or Prefect Cloud, or access log records via the API.</p> <p>Prefect enables fine-grained customization of log levels for flows and tasks, including configuration for default levels and log message formatting.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-overview","title":"Logging overview","text":"<p>Whenever you run a flow, Prefect automatically logs events for flow runs and task runs, along with any custom log handlers you have configured. No configuration is needed to enable Prefect logging.</p> <p>For example, say you created a simple flow in a file <code>flow.py</code>. If you create a local flow run with <code>python flow.py</code>, you'll see an example of the log messages created automatically by Prefect:</p> <pre><code>16:45:44.534 | INFO    | prefect.engine - Created flow run 'gray-dingo' for flow\n'hello-flow'\n16:45:44.534 | INFO    | Flow run 'gray-dingo' - Using task runner 'SequentialTaskRunner'\n16:45:44.598 | INFO    | Flow run 'gray-dingo' - Created task run 'hello-task-54135dc1-0'\nfor task 'hello-task'\nHello world!\n16:45:44.650 | INFO    | Task run 'hello-task-54135dc1-0' - Finished in state\nCompleted(None)\n16:45:44.672 | INFO    | Flow run 'gray-dingo' - Finished in state\nCompleted('All states completed.')\n</code></pre> <p>You can see logs for a flow run in the Prefect UI by navigating to the Flow Runs page and selecting a specific flow run to inspect.</p> <p></p> <p>These log messages reflect the logging configuration for log levels and message formatters. You may customize the log levels captured and the default message format through configuration, and you can capture custom logging events by explicitly emitting log messages during flow and task runs.</p> <p>Prefect supports the standard Python logging levels <code>CRITICAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, and <code>DEBUG</code>. By default, Prefect displays <code>INFO</code>-level and above events. You can configure the root logging level as well as specific logging levels for flow and task runs.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-configuration","title":"Logging configuration","text":"","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-settings","title":"Logging settings","text":"<p>Prefect provides several settings for configuring logging level and loggers.</p> <p>By default, Prefect displays <code>INFO</code>-level and above logging records. You may change this level to <code>DEBUG</code> and <code>DEBUG</code>-level logs created by Prefect will be shown as well. You may need to change the log level used by loggers from other libraries to see their log records.</p> <p>You can override any logging configuration by setting an environment variable or Prefect Profile setting using the syntax <code>PREFECT_LOGGING_[PATH]_[TO]_[KEY]</code>, with <code>[PATH]_[TO]_[KEY]</code> corresponding to the nested address of any setting.</p> <p>For example, to change the default logging levels for Prefect to <code>DEBUG</code>, you can set the environment variable <code>PREFECT_LOGGING_LEVEL=\"DEBUG\"</code>.</p> <p>You may also configure the \"root\" Python logger. The root logger receives logs from all loggers unless they explicitly opt out by disabling propagation. By default, the root logger is configured to output <code>WARNING</code> level logs to the console. As with other logging settings, you can override this from the environment or in the logging configuration file. For example, you can change the level with the variable <code>PREFECT_LOGGING_ROOT_LEVEL</code>.</p> <p>You may adjust the log level used by specific handlers. For example, you could set <code>PREFECT_LOGGING_HANDLERS_API_LEVEL=ERROR</code> to have only <code>ERROR</code> logs reported to the Prefect API. The console handlers will still default to level <code>INFO</code>.</p> <p>There is a <code>logging.yml</code> file packaged with Prefect that defines the default logging configuration.</p> <p>You can customize logging configuration by creating your own version of <code>logging.yml</code> with custom settings, by either creating the file at the default location (<code>/.prefect/logging.yml</code>) or by specifying the path to the file with <code>PREFECT_LOGGING_SETTINGS_PATH</code>. (If the file does not exist at the specified location, Prefect ignores the setting and uses the default configuration.)</p> <p>See the Python Logging configuration documentation for more information about the configuration options and syntax used by <code>logging.yml</code>.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#prefect-loggers","title":"Prefect loggers","text":"<p>To access the Prefect logger, import <code>from prefect import get_run_logger</code>. You can send messages to the logger in both flows and tasks.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-in-flows","title":"Logging in flows","text":"<p>To log from a flow, retrieve a logger instance with <code>get_run_logger()</code>, then call the standard Python logging methods.</p> <pre><code>from prefect import flow, get_run_logger\n\n@flow(name=\"log-example-flow\")\ndef logger_flow():\n    logger = get_run_logger()\n    logger.info(\"INFO level log message.\")\n</code></pre> <p>Prefect automatically uses the flow run logger based on the flow context. If you run the above code, Prefect captures the following as a log event.</p> <pre><code>15:35:17.304 | INFO    | Flow run 'mottled-marten' - INFO level log message.\n</code></pre> <p>The default flow run log formatter uses the flow run name for log messages.</p> <p>Note</p> <pre><code>Starting in 2.7.11, if you use a logger that sends logs to the API outside of a flow or task run, a warning will be displayed instead of an error. You can silence this warning by setting `PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW=ignore` or have the logger raise an error by setting the value to `error`.\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-in-tasks","title":"Logging in tasks","text":"<p>Logging in tasks works much as logging in flows: retrieve a logger instance with <code>get_run_logger()</code>, then call the standard Python logging methods.</p> <pre><code>from prefect import flow, task, get_run_logger\n\n@task(name=\"log-example-task\")\ndef logger_task():\n    logger = get_run_logger()\n    logger.info(\"INFO level log message from a task.\")\n\n@flow(name=\"log-example-flow\")\ndef logger_flow():\n    logger_task()\n</code></pre> <p>Prefect automatically uses the task run logger based on the task context. The default task run log formatter uses the task run name for log messages.</p> <pre><code>15:33:47.179 | INFO   | Task run 'logger_task-80a1ffd1-0' - INFO level log message from a task.\n</code></pre> <p>The underlying log model for task runs captures the task name, task run ID, and parent flow run ID, which are persisted to the database for reporting and may also be used in custom message formatting.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-print-statements","title":"Logging print statements","text":"<p>Prefect provides the <code>log_prints</code> option to enable the logging of <code>print</code> statements at the task or flow level. When <code>log_prints=True</code> for a given task or flow, the Python builtin <code>print</code> will be patched to redirect to the Prefect logger for the scope of that task or flow.</p> <p>By default, tasks and subflows will inherit the <code>log_prints</code> setting from their parent flow, unless opted out with their own explicit <code>log_prints</code> setting.</p> <pre><code>from prefect import task, flow\n\n@task\ndef my_task():\n    print(\"we're logging print statements from a task\")\n\n@flow(log_prints=True)\ndef my_flow():\n    print(\"we're logging print statements from a flow\")\n    my_task()\n</code></pre> <p>Will output:</p> <pre><code>15:52:11.244 | INFO    | prefect.engine - Created flow run 'emerald-gharial' for flow 'my-flow'\n15:52:11.812 | INFO    | Flow run 'emerald-gharial' - we're logging print statements from a flow\n15:52:11.926 | INFO    | Flow run 'emerald-gharial' - Created task run 'my_task-20c6ece6-0' for task 'my_task'\n15:52:11.927 | INFO    | Flow run 'emerald-gharial' - Executing 'my_task-20c6ece6-0' immediately...\n15:52:12.217 | INFO    | Task run 'my_task-20c6ece6-0' - we're logging print statements from a task\n</code></pre> <pre><code>from prefect import task, flow\n\n@task\ndef my_task(log_prints=False):\n    print(\"not logging print statements in this task\")\n\n@flow(log_prints=True)\ndef my_flow():\n    print(\"we're logging print statements from a flow\")\n    my_task()\n</code></pre> <p>Using <code>log_prints=False</code> at the task level will output:</p> <pre><code>15:52:11.244 | INFO    | prefect.engine - Created flow run 'emerald-gharial' for flow 'my-flow'\n15:52:11.812 | INFO    | Flow run 'emerald-gharial' - we're logging print statements from a flow\n15:52:11.926 | INFO    | Flow run 'emerald-gharial' - Created task run 'my_task-20c6ece6-0' for task 'my_task'\n15:52:11.927 | INFO    | Flow run 'emerald-gharial' - Executing 'my_task-20c6ece6-0' immediately...\nnot logging print statements in this task\n</code></pre> <p>You can also configure this behavior globally for all Prefect flows, tasks, and subflows.</p> <pre><code>prefect config set PREFECT_LOGGING_LOG_PRINTS=True\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#formatters","title":"Formatters","text":"<p>Prefect log formatters specify the format of log messages. You can see details of message formatting for different loggers in <code>logging.yml</code>. For example, the default formatting for task run log records is:</p> <pre><code>\"%(asctime)s.%(msecs)03d | %(levelname)-7s | Task run %(task_run_name)r - %(message)s\"\n</code></pre> <p>The variables available to interpolate in log messages varies by logger. In addition to the run context, message string, and any keyword arguments, flow and task run loggers have access to additional variables.</p> <p>The flow run logger has the following:</p> <ul> <li><code>flow_run_name</code></li> <li><code>flow_run_id</code></li> <li><code>flow_name</code></li> </ul> <p>The task run logger has the following:</p> <ul> <li><code>task_run_id</code></li> <li><code>flow_run_id</code></li> <li><code>task_run_name</code></li> <li><code>task_name</code></li> <li><code>flow_run_name</code></li> <li><code>flow_name</code></li> </ul> <p>You can specify custom formatting by setting an environment variable or by modifying the formatter in a <code>logging.yml</code> file as described earlier. For example, to change the formatting for the flow runs formatter:</p> <pre><code>PREFECT_LOGGING_FORMATTERS_STANDARD_FLOW_RUN_FMT=\"%(asctime)s.%(msecs)03d | %(levelname)-7s | %(flow_run_id)s - %(message)s\"\n</code></pre> <p>The resulting messages, using the flow run ID instead of name, would look like this:</p> <pre><code>10:40:01.211 | INFO    | e43a5a80-417a-41c4-a39e-2ef7421ee1fc - Created task run\n'othertask-1c085beb-3' for task 'othertask'\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#styles","title":"Styles","text":"<p>By default, Prefect highlights specific keywords in the console logs with a variety of colors.</p> <p>Highlighting can be toggled on/off with the <code>PREFECT_LOGGING_COLORS</code> setting, e.g.</p> <pre><code>PREFECT_LOGGING_COLORS=False\n</code></pre> <p>You can change what gets highlighted and also adjust the colors by updating the styles in a <code>logging.yml</code> file. Below lists the specific keys built-in to the <code>PrefectConsoleHighlighter</code>.</p> <p>URLs:</p> <ul> <li><code>log.web_url</code></li> <li><code>log.local_url</code></li> </ul> <p>Log levels:</p> <ul> <li><code>log.info_level</code></li> <li><code>log.warning_level</code></li> <li><code>log.error_level</code></li> <li><code>log.critical_level</code></li> </ul> <p>State types:</p> <ul> <li><code>log.pending_state</code></li> <li><code>log.running_state</code></li> <li><code>log.scheduled_state</code></li> <li><code>log.completed_state</code></li> <li><code>log.cancelled_state</code></li> <li><code>log.failed_state</code></li> <li><code>log.crashed_state</code></li> </ul> <p>Flow (run) names:</p> <ul> <li><code>log.flow_run_name</code></li> <li><code>log.flow_name</code></li> </ul> <p>Task (run) names:</p> <ul> <li><code>log.task_run_name</code></li> <li><code>log.task_name</code></li> </ul> <p>You can also build your own handler with a custom highlighter. For example, to additionally highlight emails:</p> <ol> <li>Copy and paste the following into  <code>my_package_or_module.py</code> (rename as needed) in the same directory as the flow run script, or ideally part of a Python package so it's available in <code>site-packages</code> to be accessed anywhere within your environment.</li> </ol> <pre><code>import logging\nfrom typing import Dict, Union\n\nfrom rich.highlighter import Highlighter\n\nfrom prefect.logging.handlers import PrefectConsoleHandler\nfrom prefect.logging.highlighters import PrefectConsoleHighlighter\n\nclass CustomConsoleHighlighter(PrefectConsoleHighlighter):\n    base_style = \"log.\"\n    highlights = PrefectConsoleHighlighter.highlights + [\n        # ?P&lt;email&gt; is naming this expression as `email`\n        r\"(?P&lt;email&gt;[\\w-]+@([\\w-]+\\.)+[\\w-]+)\",\n    ]\n\nclass CustomConsoleHandler(PrefectConsoleHandler):\n    def __init__(\n        self,\n        highlighter: Highlighter = CustomConsoleHighlighter,\n        styles: Dict[str, str] = None,\n        level: Union[int, str] = logging.NOTSET,\n   ):\n        super().__init__(highlighter=highlighter, styles=styles, level=level)\n</code></pre> <ol> <li>Update <code>/.prefect/logging.yml</code> to use <code>my_package_or_module.CustomConsoleHandler</code> and additionally reference the base_style and named expression: <code>log.email</code>.</li> </ol> <pre><code>    console_flow_runs:\n        level: 0\n        class: my_package_or_module.CustomConsoleHandler\n        formatter: flow_runs\n        styles:\n            log.email: magenta\n            # other styles can be appended here, e.g.\n            # log.completed_state: green\n</code></pre> <ol> <li>Then on your next flow run, text that looks like an email will be highlighted--e.g. <code>my@email.com</code> is colored in magenta here.</li> </ol> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef log_email_flow():\n    logger = get_run_logger()\n    logger.info(\"my@email.com\")\n\nlog_email_flow()\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#applying-markup-in-logs","title":"Applying markup in logs","text":"<p>To use Rich's markup in Prefect logs, first configure <code>PREFECT_LOGGING_MARKUP</code>.</p> <pre><code>PREFECT_LOGGING_MARKUP=True\n</code></pre> <p>Then, the following will highlight \"fancy\" in red.</p> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"This is [bold red]fancy[/]\")\n\nmy_flow()\n</code></pre> <p>Inaccurate logs could result</p> <p>Although this can be convenient, the downside is, if enabled, strings that contain square brackets may be inaccurately interpreted and lead to incomplete output, e.g. <code>DROP TABLE [dbo].[SomeTable];\"</code> outputs <code>DROP TABLE .[SomeTable];</code>.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#log-database-schema","title":"Log database schema","text":"<p>Logged events are also persisted to the Prefect database. A log record includes the following data:</p> Column Description id Primary key ID of the log record. created Timestamp specifying when the record was created. updated Timestamp specifying when the record was updated. name String specifying the name of the logger. level Integer representation of the logging level. flow_run_id ID of the flow run associated with the log record. If the log record is for a task run, this is the parent flow of the task. task_run_id ID of the task run associated with the log record. Null if logging a flow run event. message Log message. timestamp The client-side timestamp of this logged statement. <p>For more information, see Log schema in the API documentation.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#including-logs-from-other-libraries","title":"Including logs from other libraries","text":"<p>By default, Prefect won't capture log statements from libraries that your flows and tasks use. You can tell Prefect to include logs from these libraries with the <code>PREFECT_LOGGING_EXTRA_LOGGERS</code> setting.</p> <p>To use this setting, specify one or more Python library names to include, separated by commas. For example, if you want to make sure Prefect captures Dask and SciPy logging statements with your flow and task run logs:</p> <pre><code>PREFECT_LOGGING_EXTRA_LOGGERS=dask,scipy\n</code></pre> <p>You can set this setting as an environment variable or in a profile. See Settings for more details about how to use settings.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/managed-execution/","title":"Managed Execution","text":"<p>Prefect Cloud can run your flows on your behalf with Prefect Managed work pools. Flows run with this work pool do not require a worker or cloud provider account. Prefect handles the infrastructure and code execution for you.</p> <p>Managed execution is a great option for users who want to get started quickly, with no infrastructure setup.</p> <p>Managed Execution is in beta</p> <p>Managed Execution is currently in beta. Features are likely to change without warning.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#usage-guide","title":"Usage guide","text":"<p>Run a flow with managed infrastructure in three steps.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-1","title":"Step 1","text":"<p>Create a new work pool of type Prefect Managed in the UI or the CLI. Here's the command to create a new work pool using the CLI:</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed\n</code></pre>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-2","title":"Step 2","text":"<p>Create a deployment using the flow <code>deploy</code> method or <code>prefect.yaml</code>.</p> <p>Specify the name of your managed work pool, as shown in this example that uses the <code>deploy</code> method:</p> managed-execution.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n    source=\"https://github.com/prefecthq/demo.git\",\n    entrypoint=\"flow.py:my_flow\",\n    ).deploy(\n        name=\"test-managed-flow\",\n        work_pool_name=\"my-managed-pool\",\n    )\n</code></pre> <p>With your CLI authenticated to your Prefect Cloud workspace, run the script to create your deployment:</p> <pre><code>python managed-execution.py\n</code></pre> <p>Note that this deployment uses flow code stored in a GitHub repository.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-3","title":"Step 3","text":"<p>Run the deployment from the UI or from the CLI.</p> <p>That's it! You ran a flow on remote infrastructure without any infrastructure setup, starting a worker, or needing a cloud provider account.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#adding-dependencies","title":"Adding dependencies","text":"<p>Prefect can install Python packages in the container that runs your flow at runtime. You can specify these dependencies in the Pip Packages field in the UI, or by configuring <code>job_variables={\"pip_packages\": [\"pandas\", \"prefect-aws\"]}</code> in your deployment creation like this:</p> <pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n    source=\"https://github.com/prefecthq/demo.git\",\n    entrypoint=\"flow.py:my_flow\",\n    ).deploy(\n        name=\"test-managed-flow\",\n        work_pool_name=\"my-managed-pool\",\n        job_variables={\"pip_packages\": [\"pandas\", \"prefect-aws\"]}\n    )\n</code></pre> <p>Alternatively, you can create a <code>requirements.txt</code> file and reference it in your <code>prefect.yaml</code> <code>pull_step</code>.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#limitations","title":"Limitations","text":"<p>Managed execution requires Prefect 2.14.4 or newer.</p> <p>All limitations listed below may change without warning during the beta period. We will update this page as we make changes.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#concurrency-work-pools","title":"Concurrency &amp; work pools","text":"<p>Free tier accounts are limited to:</p> <ul> <li>Maximum of 1 concurrent flow run per workspace across all <code>prefect:managed</code> pools.</li> <li>Maximum of 1 managed execution work pool per workspace.</li> </ul> <p>Pro tier and above accounts are limited to:</p> <ul> <li>Maximum of 10 concurrent flow runs per workspace across all <code>prefect:managed</code> pools.</li> <li>Maximum of 5 managed execution work pools per workspace.</li> </ul>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#images","title":"Images","text":"<p>At this time, managed execution requires that you run the official Prefect Docker image: <code>prefecthq/prefect:2-latest</code>. However, as noted above, you can install Python package dependencies at runtime. If you need to use your own image, we recommend using another type of work pool.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#code-storage","title":"Code storage","text":"<p>Flow code must be stored in an accessible remote location. This means git-based cloud providers such as GitHub, Bitbucket, or GitLab are supported. Remote block-based storage is also supported, so S3, GCS, and Azure Blob are additional code storage options.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#resources","title":"Resources","text":"<p>Memory is limited to 2GB of RAM, which includes all operations such as dependency installation. Maximum job run time is 24 hours.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#usage-limits","title":"Usage limits","text":"<p>Free tier accounts are limited to ten compute hours per workspace per month. Pro tier and above accounts are limited to 250 hours per workspace per month. You can view your compute hours quota usage on the Work Pools page in the UI.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#next-steps","title":"Next steps","text":"<p>Read more about creating deployments in the deployment guide.</p> <p>If you find that you need more control over your infrastructure, such as the ability to run custom Docker images, serverless push work pools might be a good option. Read more here.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/migration-guide/","title":"Migrating from Prefect 1 to Prefect 2","text":"<p>This guide is designed to help you migrate your workflows from Prefect 1 to Prefect 2. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-stayed-the-same","title":"What stayed the same","text":"<p>Prefect 2 still:</p> <ul> <li>Has tasks and flows.</li> <li>Orchestrates your flow runs and provides observability into their execution states.</li> <li>Runs and inspects flow runs locally.</li> <li>Provides a coordination plane for your dataflows based on the same principles. </li> <li>Employs the same hybrid execution model, where Prefect doesn't store your flow code or data. </li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed","title":"What changed","text":"<p>Prefect 2 requires modifications to your existing tasks, flows, and deployment patterns. We've organized this section into the following categories:</p> <ul> <li>Simplified patterns \u2014 abstractions from Prefect 1 that are no longer necessary in the dynamic, DAG-free Prefect workflows that support running native Python code in your flows.</li> <li>Conceptual and syntax changes that often clarify names and simplify familiar abstractions such as retries and caching.</li> <li>New features enabled by the dynamic and flexible Prefect API.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#simplified-patterns","title":"Simplified patterns","text":"<p>Since Prefect 2 allows running native Python code within the flow function, some abstractions are no longer necessary:</p> <ul> <li><code>Parameter</code> tasks: in Prefect 2, inputs to your flow function are automatically treated as parameters of your flow. You can define the parameter values in your flow code when you create your <code>Deployment</code>, or when you schedule an ad-hoc flow run. One benefit of Prefect parametrization is built-in type validation with pydantic.</li> <li>Task-level <code>state_handlers</code>: in Prefect 2, you can build custom logic that reacts to task-run states within your flow function without the need for <code>state_handlers</code>. The page \"   How to take action on a state change of a task run\" provides a further explanation and code examples.</li> <li>Instead of using <code>signals</code>, Prefect 2 allows you to raise an arbitrary exception in your task or flow and return a custom state. For more details and examples, see How can I stop the task run based on a custom logic.</li> <li>Conditional tasks such as <code>case</code> are no longer required. Use Python native <code>if...else</code> statements to build a conditional logic. The Discourse tag \"conditional-logic\" provides more resources.</li> <li>Since you can use any context manager directly in your flow, a <code>resource_manager</code> is no longer necessary. As long as you point to your flow script in your <code>Deployment</code>, you can share database connections and any other resources between tasks in your flow. The Discourse page How to clean up resources used in a flow provides a full example.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#conceptual-and-syntax-changes","title":"Conceptual and syntax changes","text":"<p>The changes listed below require you to modify your workflow code. The following table shows how Prefect 1 concepts have been implemented in Prefect 2. The last column contains references to additional resources that provide more details and examples.</p> Concept Prefect 1 Prefect 2 Reference links Flow definition. <code>with Flow(\"flow_name\") as flow:</code> <code>@flow(name=\"flow_name\")</code> How can I define a flow? Flow executor that determines how to execute your task runs. Executor such as <code>LocalExecutor</code>. Task runner such as <code>ConcurrentTaskRunner</code>. What is the default TaskRunner (executor)? Configuration that determines how and where to execute your flow runs. Run configuration such as <code>flow.run_config = DockerRun()</code>. Create an infrastructure block such as a Docker Container and specify it as the infrastructure when creating a deployment. How can I run my flow in a Docker container? Assignment of schedules and default parameter values. Schedules are attached to the flow object and default parameter values are defined within the Parameter tasks. Schedules and default parameters are assigned to a flow\u2019s <code>Deployment</code>, rather than to a Flow object. How can I attach a schedule to a flow? Retries <code>@task(max_retries=2, retry_delay=timedelta(seconds=5))</code> <code>@task(retries=2, retry_delay_seconds=5)</code> How can I specify the retry behavior for a specific task? Logger syntax. Logger is retrieved from <code>prefect.context</code> and can only be used within tasks. In Prefect 2, you can log not only from tasks, but also within flows. To get the logger object, use: <code>prefect.get_run_logger()</code>. How can I add logs to my flow? The syntax and contents of Prefect context. Context is a thread-safe way of accessing variables related to the flow run and task run. The syntax to retrieve it: <code>prefect.context</code>. Context is still available, but its content is much richer, allowing you to retrieve even more information about your flow runs and task runs. The syntax to retrieve it: <code>prefect.context.get_run_context()</code>. How to access Prefect context values? Task library. Included in the main Prefect Core repository. Separated into individual repositories per system, cloud provider, or technology. How to migrate Prefect 1 tasks to Prefect 2 integrations.","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed-in-dataflow-orchestration","title":"What changed in dataflow orchestration?","text":"<p>Let\u2019s look at the differences in how Prefect 2 transitions your flow and task runs between various execution states.</p> <ul> <li>In Prefect 2, the final state of a flow run that finished without errors is <code>Completed</code>, while in Prefect 1, this flow run has a <code>Success</code> state. You can find more about that topic here.</li> <li>The decision about whether a flow run should be considered successful or not is no longer based on special reference tasks. Instead, your flow\u2019s return value determines the final state of a flow run. This link provides a more detailed explanation with code examples.</li> <li>In Prefect 1, concurrency limits were only available to Prefect Cloud users. Prefect 2 provides customizable concurrency limits with the open-source Prefect server and Prefect Cloud. In Prefect 2, flow run concurrency limits are set on work pools.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed-in-flow-deployment-patterns","title":"What changed in flow deployment patterns?","text":"<p>To deploy your Prefect 1 flows, you have to send flow metadata to the backend in a step called registration. Prefect 2 no longer requires flow pre-registration. Instead, you create a Deployment that specifies the entry point to your flow code and optionally specifies:</p> <ul> <li>Where to run your flow (your Infrastructure, such as a <code>DockerContainer</code>, <code>KubernetesJob</code>, or <code>ECSTask</code>).</li> <li>When to run your flow (an <code>Interval</code>, <code>Cron</code>, or <code>RRule</code> schedule).</li> <li>How to run your flow (execution details such as <code>parameters</code>, flow deployment <code>name</code>, and more).</li> <li>The work pool for your deployment. If no work pool is specified, a default work pool named <code>default</code> is used.</li> </ul> <p>The API is now implemented as a REST API rather than GraphQL. This page illustrates how you can interact with the API.</p> <p>In Prefect 1, the logical grouping of flows was based on projects. Prefect 2 provides a much more flexible way of organizing your flows, tasks, and deployments through customizable filters and\u00a0tags. This page provides more details on how to assign tags to various Prefect 2 objects.</p> <p>The role of agents has changed:</p> <ul> <li>In Prefect 2, there is only one generic agent type. The agent polls a work pool looking for flow runs.</li> <li>See this Discourse page for a more detailed discussion.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#new-features-introduced-in-prefect-2","title":"New features introduced in Prefect 2","text":"<p>The following new components and capabilities are enabled by Prefect 2.</p> <ul> <li>More flexibility thanks to the elimination of flow pre-registration.</li> <li>More flexibility for flow deployments, including easier promotion of a flow through development, staging, and production environments.</li> <li>Native <code>async</code> support.</li> <li>Out-of-the-box <code>pydantic</code> validation.</li> <li>Blocks allowing you to securely store UI-editable, type-checked configuration to external systems and an easy-to-use Key-Value Store. All those components are configurable in one place and provided as part of the open-source Prefect 2 product. In contrast, the concept of Secrets in Prefect 1 was much more narrow and only available in Prefect Cloud.  </li> <li>Notifications available in the open-source Prefect 2 version, as opposed to Cloud-only Automations in Prefect 1.  </li> <li>A first-class <code>subflows</code> concept: Prefect 1 only allowed the flow-of-flows orchestrator pattern. With Prefect 2 subflows, you gain a natural and intuitive way of organizing your flows into modular sub-components. For more details, see the following list of resources about subflows.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#orchestration-behind-the-api","title":"Orchestration behind the API","text":"<p>Apart from new features, Prefect 2 simplifies many usage patterns and provides a much more seamless onboarding experience.</p> <p>Every time you run a flow, whether it is tracked by the API server or ad-hoc through a Python script, it is on the same UI page for easier debugging and observability. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#code-as-workflows","title":"Code as workflows","text":"<p>With Prefect 2, your functions\u00a0are\u00a0your flows and tasks. Prefect 2 automatically detects your flows and tasks without the need to define a rigid DAG structure. While use of tasks is encouraged to provide you the maximum visibility into your workflows, they are no longer required. You can add a single <code>@flow</code> decorator to your main function to transform any Python script into a Prefect workflow.</p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#incremental-adoption","title":"Incremental adoption","text":"<p>The built-in SQLite database automatically tracks all your locally executed flow runs. As soon as you start a Prefect server and open the Prefect UI in your browser (or authenticate your CLI with your Prefect Cloud workspace), you can see all your locally executed flow runs in the UI. You don't even need to start an agent.</p> <p>Then, when you want to move toward scheduled, repeatable workflows, you can build a deployment and send it to the server by running a CLI command or a Python script. </p> <ul> <li>You can create a deployment to on remote infrastructure, where the run environment is defined by a reusable infrastructure block.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#fewer-ambiguities","title":"Fewer ambiguities","text":"<p>Prefect 2 eliminates ambiguities in many ways. For example. there is no more confusion between Prefect Core and Prefect Server \u2014 Prefect 2 unifies those into a single open source product. This product is also much easier to deploy with no requirement for Docker or docker-compose.</p> <p>If you want to switch your backend to use Prefect Cloud for an easier production-level managed experience, Prefect profiles let you quickly connect to your workspace.</p> <p>In Prefect 1, there are several confusing ways you could implement <code>caching</code>. Prefect 2 resolves those ambiguities by providing a single <code>cache_key_fn</code> function paired with <code>cache_expiration</code>, allowing you to define arbitrary caching mechanisms \u2014 no more confusion about whether you need to use <code>cache_for</code>, <code>cache_validator</code>, or file-based caching using <code>targets</code>.</p> <p>For more details on how to configure caching, check out the following resources:</p> <ul> <li>Caching docs</li> <li>Time-based caching</li> <li>Input-based caching</li> </ul> <p>A similarly confusing concept in Prefect 1 was distinguishing between the functional and imperative APIs. This distinction caused ambiguities with respect to how to define state dependencies between tasks. Prefect 1 users were often unsure whether they should use the functional <code>upstream_tasks</code> keyword argument or the imperative methods such as <code>task.set_upstream()</code>, <code>task.set_downstream()</code>, or <code>flow.set_dependencies()</code>. In Prefect 2, there is only the functional API. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#next-steps","title":"Next steps","text":"<p>We know migrations can be tough. We encourage you to take it step-by-step and experiment with the new features.</p> <p>To make the migration process easier for you:</p> <ul> <li>We provided a detailed FAQ section allowing you to find the right information you need to move your workflows to Prefect 2. If you still have some open questions, feel free to create a new topic describing your migration issue.</li> <li>We have dedicated resources in the Customer Success team to help you along your migration journey. Reach out to cs@prefect.io to discuss how we can help.  </li> <li>You can ask questions in our 20,000+ member Community Slack.</li> </ul> <p>Happy Engineering!</p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/moving-data/","title":"Read and Write Data to and from Cloud Provider Storage","text":"<p>Writing data to cloud-based storage and reading data from that storage is a common task in data engineering. In this guide we'll learn how to use Prefect to move data to and from AWS, Azure, and GCP blob storage.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed</li> <li>Authenticated with Prefect Cloud (or self-hosted Prefect server instance)</li> <li>A cloud provider account (e.g. AWS)</li> </ul>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#install-relevant-prefect-integration-library","title":"Install relevant Prefect integration library","text":"<p>In the CLI, install the Prefect integration library for your cloud provider:</p> AWSAzureGCP <p>prefect-aws provides blocks for interacting with AWS services.</p> <p> <pre><code>pip install -U prefect-aws\n</code></pre> </p> <p>prefect-azure provides blocks for interacting with Azure services.</p> <p> <pre><code> pip install -U prefect-azure\n</code></pre> </p> <p>prefect-gcp provides blocks for interacting with GCP services.</p> <p> <pre><code> pip install -U prefect-gcp\n</code></pre> </p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#register-the-block-types","title":"Register the block types","text":"<p>Register the new block types with Prefect Cloud (or with your self-hosted Prefect server instance):</p> AWSAzureGCP <p> <pre><code>prefect block register -m prefect_aws  \n</code></pre> </p> <p> <pre><code>prefect block register -m prefect_azure \n</code></pre> </p> <p> <pre><code>prefect block register -m prefect_gcp\n</code></pre> </p> <p>We should see a message in the CLI that several block types were registered. If we check the UI, we should see the new block types listed.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-storage-bucket","title":"Create a storage bucket","text":"<p>Create a storage bucket in the cloud provider account. Ensure the bucket is publicly accessible or create a user or service account with the appropriate permissions to fetch and write data to the bucket.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-credentials-block","title":"Create a credentials block","text":"<p>If the bucket is private, there are several options to authenticate:</p> <ol> <li>At deployment runtime, ensure the runtime environment is authenticated.</li> <li>Create a block with configuration details and reference it when creating the storage block.</li> </ol> <p>If saving credential details in a block we can use a credentials block specific to the cloud provider or use a more generic secret block. We can create blocks via the UI or Python code. Below we'll use Python code to create a credentials block for our cloud provider.</p> <p>Credentials safety</p> <p>Reminder, don't store credential values in public locations such as public git platform repositories.  In the examples below we use environment variables to store credential values.</p> AWSAzureGCP <pre><code>import os\nfrom prefect_aws import AwsCredentials\n\nmy_aws_creds = AwsCredentials(\n    aws_access_key_id=\"123abc\",\n    aws_secret_access_key=os.environ.get(\"MY_AWS_SECRET_ACCESS_KEY\"),\n)\nmy_aws_creds.save(name=\"my-aws-creds-block\", overwrite=True)\n</code></pre> <pre><code>import os\nfrom prefect_azure import AzureBlobStorageCredentials\n\nmy_azure_creds = AzureBlobStorageCredentials(\n    connection_string=os.environ.get(\"MY_AZURE_CONNECTION_STRING\"),\n)\nmy_azure_creds.save(name=\"my-azure-creds-block\", overwrite=True)\n</code></pre> <p>We recommend specifying the service account key file contents as a string, rather than the path to the file, because that file might not be available in your production environments.</p> <pre><code>import os\nfrom prefect_gcp import GCPCredentials\n\nmy_gcp_creds = GCPCredentials(\n    service_account_info=os.environ.get(\"GCP_SERVICE_ACCOUNT_KEY_FILE_CONTENTS\"), \n)\nmy_gcp_creds.save(name=\"my-gcp-creds-block\", overwrite=True)\n</code></pre> <p>Run the code to create the block. We should see a message that the block was created.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-storage-block","title":"Create a storage block","text":"<p>Let's create a block for the chosen cloud provider using Python code or the UI. In this example we'll use Python code.</p> AWSAzureGCP <p>Note that the <code>S3Bucket</code> block is not the same as the <code>S3</code> block that ships with Prefect.  The <code>S3Bucket</code> block we use in this example is part of the <code>prefect-aws</code> library and provides additional functionality. </p> <p>We'll reference the credentials block created above.</p> <pre><code>from prefect_aws import S3Bucket\n\ns3bucket = S3Bucket.create(\n    bucket=\"my-bucket-name\",\n    credentials=\"my-aws-creds-block\"\n    )\ns3bucket.save(name=\"my-s3-bucket-block\", overwrite=True)\n</code></pre> <p>Note that the <code>AzureBlobStorageCredentials</code> block is not the same as the Azure block that ships with Prefect.  The <code>AzureBlobStorageCredentials</code> block we use in this example is part of the <code>prefect-azure</code> library and provides additional functionality. </p> <p>Azure blob storage doesn't require a separate block, the connection string used in the <code>AzureBlobStorageCredentials</code> block can encode the information needed. </p> <p>Note that the <code>GcsBucket</code> block is not the same as the <code>GCS</code> block that ships with Prefect.  The <code>GcsBucket</code> block is part of the <code>prefect-gcp</code> library and provides additional functionality.  We'll use it here.</p> <p>We'll reference the credentials block created above.</p> <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcsbucket = GcsBucket(\n    bucket=\"my-bucket-name\", \n    credentials=\"my-gcp-creds-block\"\n    )\ngcsbucket.save(name=\"my-gcs-bucket-block\", overwrite=True)\n</code></pre> <p>Run the code to create the block. We should see a message that the block was created.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#write-data","title":"Write data","text":"<p>Use your new block inside a flow to write data to your cloud provider.</p> AWSAzureGCP <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_aws.s3 import S3Bucket\n\n@flow()\ndef upload_to_s3():\n    \"\"\"Flow function to upload data\"\"\"\n    path = Path(\"my_path_to/my_file.parquet\")\n    aws_block = S3Bucket.load(\"my-s3-bucket-block\")\n    aws_block.upload_from_path(from_path=path, to_path=path)\n\nif __name__ == \"__main__\":\n    upload_to_s3()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_upload\n\n@flow\ndef upload_to_azure():\n    \"\"\"Flow function to upload data\"\"\"\n    blob_storage_credentials = AzureBlobStorageCredentials.load(\n        name=\"my-azure-creds-block\"\n    )\n\n    with open(\"my_path_to/my_file.parquet\", \"rb\") as f:\n        blob_storage_upload(\n            data=f.read(),\n            container=\"my_container\",\n            blob=\"my_path_to/my_file.parquet\",\n            blob_storage_credentials=blob_storage_credentials,\n        )\n\nif __name__ == \"__main__\":\n    upload_to_azure()\n</code></pre> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_gcp.cloud_storage import GcsBucket\n\n@flow()\ndef upload_to_gcs():\n    \"\"\"Flow function to upload data\"\"\"\n    path = Path(\"my_path_to/my_file.parquet\")\n    gcs_block = GcsBucket.load(\"my-gcs-bucket-block\")\n    gcs_block.upload_from_path(from_path=path, to_path=path)\n\nif __name__ == \"__main__\":\n    upload_to_gcs()\n</code></pre>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#read-data","title":"Read data","text":"<p>Use your block to read data from your cloud provider inside a flow.</p> AWSAzureGCP <pre><code>from prefect import flow\nfrom prefect_aws import S3Bucket\n\n@flow\ndef download_from_s3():\n    \"\"\"Flow function to download data\"\"\"\n    s3_block = S3Bucket.load(\"my-s3-bucket-block\")\n    s3_block.get_directory(\n        from_path=\"my_path_to/my_file.parquet\", \n        local_path=\"my_path_to/my_file.parquet\"\n    )\n\nif __name__ == \"__main__\":\n    download_from_s3()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef download_from_azure():\n    \"\"\"Flow function to download data\"\"\"\n    blob_storage_credentials = AzureBlobStorageCredentials.load(\n        name=\"my-azure-creds-block\"\n    )\n    blob_storage_download(\n        blob=\"my_path_to/my_file.parquet\",\n        container=\"my_container\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n\nif __name__ == \"__main__\":\n    download_from_azure()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_gcp.cloud_storage import GcsBucket\n\n@flow\ndef download_from_gcs():\n    gcs_block = GcsBucket.load(\"my-gcs-bucket-block\")\n    gcs_block.get_directory(\n        from_path=\"my_path_to/my_file.parquet\", \n        local_path=\"my_path_to/my_file.parquet\"\n    )\n\nif __name__ == \"__main__\":\n    download_from_gcs()\n</code></pre> <p>In this guide we've seen how to use Prefect to read data from and write data to cloud providers!</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#next-steps","title":"Next steps","text":"<p>Check out the <code>prefect-aws</code>, <code>prefect-azure</code>, and <code>prefect-gcp</code> docs to see additional methods for interacting with cloud storage providers. Each library also contains blocks for interacting with other cloud-provider services.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/prefect-deploy/","title":"Deploying Flows to Work Pools and Workers","text":"<p>In this guide, we will configure a deployment that uses a work pool for dynamically provisioned infrastructure.</p> <p>All Prefect flow runs are tracked by the API. The API does not require prior registration of flows. With Prefect, you can call a flow locally or on a remote environment and it will be tracked.</p> <p>A deployment turns your workflow into an application that can be interacted with and managed via the Prefect API. A deployment enables you to:</p> <ul> <li>Schedule flow runs.</li> <li>Specify event triggers for flow runs.</li> <li>Assign one or more tags to organize your deployments and flow runs. You can use those tags as filters in the Prefect UI.</li> <li>Assign custom parameter values for flow runs based on the deployment.</li> <li>Create ad-hoc flow runs from the API or Prefect UI.</li> <li>Upload flow files to a defined storage location for retrieval at run time.</li> </ul> <p>Deployments created with <code>.serve</code></p> <p>A deployment created with the Python <code>flow.serve</code> method or the <code>serve</code> function runs flows in a subprocess on the same machine where the deployment is created. It does not use a work pool or worker.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#work-pool-based-deployments","title":"Work pool-based deployments","text":"<p>A work pool-based deployment is useful when you want to dynamically scale the infrastructure where your flow code runs. Work pool-based deployments contain information about the infrastructure type and configuration for your workflow execution.</p> <p>Work pool-based deployment infrastructure options include the following:</p> <ul> <li>Process - runs flow in a subprocess. In most cases, you're better off using <code>.serve</code>.</li> <li>Docker - runs flows in an ephemeral Docker container.</li> <li>Kubernetes - runs flows as a Kubernetes Job.</li> <li>Serverless Cloud Provider options - runs flows in a Docker container in a serverless cloud provider environment, such as AWS ECS, Azure Container Instance, Google Cloud Run, or Vertex AI.</li> </ul> <p>The following diagram provides a high-level overview of the conceptual elements involved in defining a work-pool based deployment that is polled by a worker and executes a flow run based on that deployment.</p> <pre><code>%%{\n  init: {\n    'theme': 'base',\n    'themeVariables': {\n      'fontSize': '19px'\n    }\n  }\n}%%\n\nflowchart LR\n    F(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Flow Code&lt;/div&gt;\"):::yellow -.-&gt; A(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Deployment Definition&lt;/div&gt;\"):::gold\n    subgraph Server [\"&lt;div style='width: 150px; text-align: center; margin-top: 5px;'&gt;Prefect API&lt;/div&gt;\"]\n        D(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Deployment&lt;/div&gt;\"):::green\n    end\n    subgraph Remote Storage [\"&lt;div style='width: 160px; text-align: center; margin-top: 5px;'&gt;Remote Storage&lt;/div&gt;\"]\n        B(\"&lt;div style='margin: 5px 6px 5px 5px;'&gt;Flow&lt;/div&gt;\"):::yellow\n    end\n    subgraph Infrastructure [\"&lt;div style='width: 150px; text-align: center; margin-top: 5px;'&gt;Infrastructure&lt;/div&gt;\"]\n        G(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Flow Run&lt;/div&gt;\"):::blue\n    end\n\n    A --&gt; D\n    D --&gt; E(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Worker&lt;/div&gt;\"):::red\n    B -.-&gt; E\n    A -.-&gt; B\n    E -.-&gt; G\n\n    classDef gold fill:goldenrod,stroke:goldenrod,stroke-width:4px,color:black\n    classDef yellow fill:gold,stroke:gold,stroke-width:4px,color:black\n    classDef gray fill:lightgray,stroke:lightgray,stroke-width:4px\n    classDef blue fill:blue,stroke:blue,stroke-width:4px,color:white\n    classDef green fill:green,stroke:green,stroke-width:4px,color:white\n    classDef red fill:red,stroke:red,stroke-width:4px,color:white\n    classDef dkgray fill:darkgray,stroke:darkgray,stroke-width:4px,color:white</code></pre> <p>The work pool types above require a worker to be running on your infrastructure to poll a work pool for scheduled flow runs.</p> <p>Additional work pool options available with Prefect Cloud</p> <p>Prefect Cloud offers other flavors of work pools that don't require a worker:</p> <ul> <li> <p>Push Work Pools - serverless cloud options that don't require a worker because Prefect Cloud submits them to your serverless cloud infrastructure on your behalf. Prefect can auto-provision your cloud infrastructure for you and set it up to use your work pool.</p> </li> <li> <p>Managed Execution Prefect Cloud submits and runs your deployment on serverless infrastructure. No cloud provider account required.</p> </li> </ul> <p>In this guide, we focus on deployments that require a worker.</p> <p>Work pool-based deployments that use a worker also allow you to assign a work queue name to prioritize work and allow you to limit concurrent runs at the work pool level.</p> <p>When creating a deployment that uses a work pool and worker, we must answer two basic questions:</p> <ul> <li>What instructions does a worker need to set up an execution environment for our flow? For example, a flow may have Python package requirements, unique Kubernetes settings, or Docker networking configuration.</li> <li>How should the flow code be accessed?</li> </ul> <p>The tutorial shows how you can create a deployment with a long-running process using <code>.serve</code> and how to move to a work-pool-based deployment setup with <code>.deploy</code>. See the discussion of when you might want to move to work-pool-based deployments there.</p> <p>Next, we'll explore how to use <code>.deploy</code> to create deployments with Python code. If you'd prefer to learn about using a YAML-based alternative for managing deployment configuration, skip to the later section on <code>prefect.yaml</code>.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#creating-work-pool-based-deployments-with-deploy","title":"Creating work pool-based deployments with <code>.deploy</code>","text":"","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#automatically-bake-your-code-into-a-docker-image","title":"Automatically bake your code into a Docker image","text":"<p>You can create a deployment from Python code by calling the <code>.deploy</code> method on a flow.</p> buy.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities\")\n\n\nif __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/my_image:my_image_tag\"\n    )\n</code></pre> <p>Make sure you have the work pool created in the Prefect Cloud workspace you are authenticated to or on your running self-hosted server instance. Then run the script to create a deployment (in future examples this step will be omitted for brevity):</p> <pre><code>python buy.py\n</code></pre> <p>You should see messages in your terminal that Docker is building your image. When the deployment build succeeds you will see helpful information in your terminal showing you how to start a worker for your deployment and how to run your deployment. Your deployment will be visible on the <code>Deployments</code> page in the UI.</p> <p>By default, <code>.deploy</code> will build a Docker image with your flow code baked into it and push the image to the Docker Hub registry specified in the <code>image</code> argument`.</p> <p>Authentication to Docker Hub</p> <p>You need your environment to be authenticated to your Docker registry to push an image to it.</p> <p>You can specify a registry other than Docker Hub by providing the full registry path in the <code>image</code> argument.</p> <p>Warning</p> <p>If building a Docker image, the environment in which you are creating the deployment needs to have Docker installed and running.</p> <p>To avoid pushing to a registry, set <code>push=False</code> in the <code>.deploy</code> method.</p> <pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/my_image:my_image_tag\",\n        push=False\n    )\n</code></pre> <p>To avoid building an image, set <code>build=False</code> in the <code>.deploy</code> method.</p> <pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/no-build-image:1.0\",\n        build=False\n    )\n</code></pre> <p>The specified image will need to be available in your deployment's execution environment for your flow code to be accessible.</p> <p>Prefect generates a Dockerfile for you that will build an image based off of one of Prefect's published images. The generated Dockerfile will copy the current directory into the Docker image and install any dependencies listed in a <code>requirements.txt</code> file.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#automatically-build-a-custom-docker-image-with-a-local-dockerfile","title":"Automatically build a custom Docker image with a local Dockerfile","text":"<p>If you want to use a custom Dockerfile, you can specify the path to the Dockerfile with the <code>DeploymentImage</code> class:</p> custom_dockerfile.py<pre><code>from prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Selling securities\")\n\n\nif __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-custom-dockerfile-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=DeploymentImage(\n            name=\"my_image\",\n            tag=\"deploy-guide\",\n            dockerfile=\"Dockerfile\"\n    ),\n    push=False\n)\n</code></pre> <p>The <code>DeploymentImage</code> object allows for a great deal of image customization.</p> <p>For example, you can install a private Python package from GCP's artifact registry like this:</p> <p>Create a custom base Dockerfile.</p> <pre><code>FROM python:3.10\n\nARG AUTHED_ARTIFACT_REG_URL\nCOPY ./requirements.txt /requirements.txt\n\nRUN pip install --extra-index-url ${AUTHED_ARTIFACT_REG_URL} -r /requirements.txt\n</code></pre> <p>Create our deployment by leveraging the DeploymentImage class.</p> private-package.py<pre><code>from prefect import flow\nfrom prefect.deployments.runner import DeploymentImage\nfrom prefect.blocks.system import Secret\nfrom my_private_package import do_something_cool\n\n\n@flow(log_prints=True)\ndef my_flow():\n    do_something_cool()\n\n\nif __name__ == \"__main__\":\n    artifact_reg_url: Secret = Secret.load(\"artifact-reg-url\")\n\n    my_flow.deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"k8s-demo\",\n        image=DeploymentImage(\n            name=\"my-image\",\n            tag=\"test\",\n            dockerfile=\"Dockerfile\",\n            buildargs={\"AUTHED_ARTIFACT_REG_URL\": artifact_reg_url.get()},\n        ),\n    )\n</code></pre> <p>Note that we used a Prefect Secret block to load the URL configuration for the artifact registry above.</p> <p>See all the optional keyword arguments for the DeploymentImage class here.</p> <p>Default Docker namespace</p> <p>You can set the <code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE</code> setting to append a default Docker namespace to all images you build with <code>.deploy</code>. This is great if you use a private registry to store your images.</p> <p>To set a default Docker namespace for your current profile run:</p> <p> <pre><code>prefect config set PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE=&lt;docker-registry-url&gt;/&lt;organization-or-username&gt;\n</code></pre> </p> <p>Once set, you can omit the namespace from your image name when creating a deployment:</p> with_default_docker_namespace.py<pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_image:my_image_tag\"\n    )\n</code></pre> <p>The above code will build an image with the format <code>&lt;docker-registry-url&gt;/&lt;organization-or-username&gt;/my_image:my_image_tag</code> when <code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE</code> is set.</p> <p>While baking code into Docker images is a popular deployment option, many teams decide to store their workflow code in git-based storage, such as GitHub, Bitbucket, or Gitlab. Let's see how to do that next.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#store-your-code-in-git-based-cloud-storage","title":"Store your code in git-based cloud storage","text":"<p>If you don't specify an <code>image</code> argument for <code>.deploy</code>, then you need to specify where to pull the flow code from at runtime with the <code>from_source</code> method.</p> <p>Here's how we can pull our flow code from a GitHub repository.</p> git_storage.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        \"https://github.com/my_github_account/my_repo/my_file.git\",\n        entrypoint=\"flows/no-image.py:hello_world\",\n    ).deploy(\n        name=\"no-image-deployment\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>The <code>entrypoint</code> is the path to the file the flow is located in and the function name, separated by a colon.</p> <p>Alternatively, you could specify a git-based cloud storage URL for a Bitbucket or Gitlab repository.</p> <p>Note</p> <p>If you don't specify an image as part of your deployment creation, the image specified in the work pool will be used to run your flow.</p> <p>After creating a deployment you might change your flow code. Generally, you can just push your code to GitHub, without rebuilding your deployment. The exception is if something that the server needs to know about changes, such as the flow entrypoint parameters. Rerunning the Python script with <code>.deploy</code> will update your deployment on the server with the new flow code.</p> <p>If you need to provide additional configuration, such as specifying a private repository, you can provide a <code>GitRepository</code> object instead of a URL:</p> private_git_storage.py<pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        branch=\"dev\",\n        credentials={\n            \"access_token\": Secret.load(\"github-access-token\")\n        }\n    ),\n    entrypoint=\"flows/no-image.py:hello_world\",\n    ).deploy(\n        name=\"private-git-storage-deployment\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Note the use of the Secret block to load the GitHub access token. Alternatively, you could provide a username and password to the <code>username</code> and <code>password</code> fields of the <code>credentials</code> argument.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#store-your-code-in-cloud-provider-storage","title":"Store your code in cloud provider storage","text":"<p>Another option for flow code storage is any fsspec-supported storage location, such as AWS S3, GCP GCS, or Azure Blob Storage.</p> <p>For example, you can pass the S3 bucket path to <code>source</code>.</p> s3_storage.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"s3://my-bucket/my-folder\",\n        entrypoint=\"flows.py:my_flow\",\n    ).deploy(\n        name=\"deployment-from-aws-flow\",\n        work_pool_name=\"my_pool\",\n    )\n</code></pre> <p>In the example above your credentials will be auto-discovered from your deployment creation environment and credentials will need to be available in your runtime environment.</p> <p>If you need additional configuration for your cloud-based storage - for example, with a private S3 Bucket -  we recommend using a storage block. A storage block also ensures your credentials will be available in both your deployment creation environment and your execution environment.</p> <p>Here's an example that uses an <code>S3Bucket</code> block from the prefect-aws library.</p> s3_storage_auth.py<pre><code>from prefect import flow\nfrom prefect_aws.s3 import S3Bucket\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=S3Bucket.load(\"my-code-storage\"), entrypoint=\"my_file.py:my_flow\"\n    ).deploy(name=\"test-s3\", work_pool_name=\"my_pool\")\n</code></pre> <p>If you are familiar with the deployment creation mechanics with <code>.serve</code>, you will notice that <code>.deploy</code> is very similar. <code>.deploy</code> just requires a work pool name and has a number of parameters dealing with flow-code storage for Docker images.</p> <p>Unlike <code>.serve</code>, if you don't specify an image to use for your flow, you must to specify where to pull the flow code from at runtime with the <code>from_source</code> method, whereas <code>from_source</code> is optional with <code>.serve</code>.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#additional-configuration-with-deploy","title":"Additional configuration with <code>.deploy</code>","text":"<p>Our examples thus far have explored options for where to store flow code. Let's turn our attention to other deployment configuration options.</p> <p>To pass parameters to your flow, you can use the <code>parameters</code> argument in the <code>.deploy</code> method. Just pass in a dictionary of key-value pairs.</p> pass_params.py<pre><code>from prefect import flow\n\n@flow\ndef hello_world(name: str):\n    print(f\"Hello, {name}!\")\n\nif __name__ == \"__main__\":\n    hello_world.deploy(\n        name=\"pass-params-deployment\",\n        work_pool_name=\"my_pool\",\n        parameters=dict(name=\"Prefect\"),\n        image=\"my_registry/my_image:my_image_tag\",\n    )\n</code></pre> <p>The <code>job_variables</code> parameter allows you to fine-tune the infrastructure settings for a deployment. The values passed in override default values in the specified work pool's base job template.</p> <p>You can override environment variables, such as <code>image_pull_policy</code> and <code>image</code>, for a specific deployment with the <code>job_variables</code> argument.</p> job_var_image_pull.py<pre><code>if __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-deployment-never-pull\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"image_pull_policy\": \"Never\"},\n        image=\"my-image:my-tag\"\",\n        push=False\n    )\n</code></pre> <p>Similarly, you can override the environment variables specified in a work pool through the <code>job_variables</code> parameter:</p> job_var_env_vars.py<pre><code>if __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-deployment-never-pull\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"env\": {\"EXTRA_PIP_PACKAGES\": \"boto3\"} },\n        image=\"my-image:my-tag\"\",\n        push=False\n    )\n</code></pre> <p>The dictionary key \"EXTRA_PIP_PACKAGES\" denotes a special environment variable that Prefect will use to install additional Python packages at runtime. This approach is an alternative to building an image with a custom <code>requirements.txt</code> copied into it.</p> <p>For more information on overriding job variables see this guide.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#working-with-multiple-deployments-with-deploy","title":"Working with multiple deployments with <code>deploy</code>","text":"<p>You can create multiple deployments from one or more Python files that use <code>.deploy</code>. These deployments can be managed independently of one another, allowing you to deploy the same flow with different configurations in the same codebase.</p> <p>To create multiple work pool-based deployments at once you can use the <code>deploy</code> function, which is analogous to the <code>serve</code> function.</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities\")\n\n\nif __name__ == \"__main__\":\n    deploy(\n        buy.to_deployment(name=\"dev-deploy\", work_pool_name=\"my-dev-work-pool\"),\n        buy.to_deployment(name=\"prod-deploy\", work_pool_name=\"my-prod-work-pool\"),\n        image=\"my-registry/my-image:dev\",\n        push=False,\n    )\n</code></pre> <p>Note that in the example above we created two deployments from the same flow, but with different work pools. Alternatively, we could have created two deployments from different flows.</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities.\")\n\n@flow(log_prints=True)\ndef sell():\n    print(\"Selling securities.\")\n\n\nif __name__ == \"__main__\":\n    deploy(\n        buy.to_deployment(name=\"buy-deploy\"),\n        sell.to_deployment(name=\"sell-deploy\"),\n        work_pool_name=\"my-dev-work-pool\"\n        image=\"my-registry/my-image:dev\",\n        push=False,\n    )\n</code></pre> <p>In the example above the code for both flows gets baked into the same image.</p> <p>We can specify that one or more flows should be pulled from a remote location at runtime by using the <code>from_source</code> method. Here's an example of deploying two flows, one defined locally and one defined in a remote repository:</p> <pre><code>from prefect import deploy, flow\n\n\n@flow(log_prints=True)\ndef local_flow():\n    print(\"I'm a flow!\")\n\nif __name__ == \"__main__\":\n    deploy(\n        local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n        flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        ).to_deployment(\n            name=\"example-deploy-remote-flow\",\n        ),\n        work_pool_name=\"my-work-pool\",\n        image=\"my-registry/my-image:dev\",\n    )\n</code></pre> <p>You could pass any number of flows to the <code>deploy</code> function. This behavior is useful if using a monorepo approach to your workflows.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#creating-work-pool-based-deployments-with-prefectyaml","title":"Creating work pool-based deployments with prefect.yaml","text":"<p>The <code>prefect.yaml</code> file is a YAML file describing base settings for your deployments, procedural steps for preparing deployments, and instructions for preparing the execution environment for a deployment run.</p> <p>You can initialize your deployment configuration, which creates the <code>prefect.yaml</code> file, by running the CLI command <code>prefect init</code> in any directory or repository that stores your flow code.</p> <p>Deployment configuration recipes</p> <p>Prefect ships with many off-the-shelf \"recipes\" that allow you to get started with more structure within your <code>prefect.yaml</code> file; run <code>prefect init</code> to be prompted with available recipes in your installation. You can provide a recipe name in your initialization command with the <code>--recipe</code> flag, otherwise Prefect will attempt to guess an appropriate recipe based on the structure of your working directory (for example if you initialize within a <code>git</code> repository, Prefect will use the <code>git</code> recipe).</p> <p>The <code>prefect.yaml</code> file contains deployment configuration for deployments created from this file, default instructions for how to build and push any necessary code artifacts (such as Docker images), and default instructions for pulling a deployment in remote execution environments (e.g., cloning a GitHub repository).</p> <p>Any deployment configuration can be overridden via options available on the <code>prefect deploy</code> CLI command when creating a deployment.</p> <p><code>prefect.yaml</code> file flexibility</p> <p>In older versions of Prefect, this file had to be in the root of your repository or project directory and named <code>prefect.yaml</code>. Now this file can be located in a directory outside the project or a subdirectory inside the project. It can be named differently, provided the filename ends in <code>.yaml</code>. You can even have multiple <code>prefect.yaml</code> files with the same name in different directories. By default, <code>prefect deploy</code> will use a <code>prefect.yaml</code> file in the project's root directory. To use a custom deployment configuration file, supply the new  <code>--prefect-file</code> CLI argument when running the <code>deploy</code> command from the root of your project directory:</p> <p><code>prefect deploy --prefect-file path/to/my_file.yaml</code></p> <p>The base structure for <code>prefect.yaml</code> is as follows:</p> <pre><code># generic metadata\nprefect-version: null\nname: null\n\n# preparation steps\nbuild: null\npush: null\n\n# runtime steps\npull: null\n\n# deployment configurations\ndeployments:\n- # base metadata\n    name: null\n    version: null\n    tags: []\n    description: null\n    schedule: null\n\n    # flow-specific fields\n    entrypoint: null\n    parameters: {}\n\n    # infra-specific fields\n    work_pool:\n    name: null\n    work_queue_name: null\n    job_variables: {}\n</code></pre> <p>The metadata fields are always pre-populated for you. These fields are for bookkeeping purposes only.  The other sections are pre-populated based on recipe; if no recipe is provided, Prefect will attempt to guess an appropriate one based on local configuration.</p> <p>You can create deployments via the CLI command <code>prefect deploy</code> without ever needing to alter the <code>deployments</code> section of your <code>prefect.yaml</code> file \u2014 the <code>prefect deploy</code> command will help in deployment creation via interactive prompts. The <code>prefect.yaml</code> file facilitates version-controlling your deployment configuration and managing multiple deployments.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-actions","title":"Deployment actions","text":"<p>Deployment actions defined in your <code>prefect.yaml</code> file control the lifecycle of the creation and execution of your deployments. The three actions available are <code>build</code>, <code>push</code>, and <code>pull</code>. <code>pull</code> is the only required deployment action \u2014 it is used to define how Prefect will pull your deployment in remote execution environments.</p> <p>Each action is defined as a list of steps that are executing in sequence.</p> <p>Each step has the following format:</p> <pre><code>section:\n- prefect_package.path.to.importable.step:\n    id: \"step-id\" # optional\n    requires: \"pip-installable-package-spec\" # optional\n    kwarg1: value\n    kwarg2: more-values\n</code></pre> <p>Every step can optionally provide a <code>requires</code> field that Prefect will use to auto-install in the event that the step cannot be found in the current environment. Each step can also specify an <code>id</code> for the step which is used when referencing step outputs in later steps. The additional fields map directly onto Python keyword arguments to the step function. Within a given section, steps always run in the order that they are provided within the <code>prefect.yaml</code> file.</p> <p>Deployment Instruction Overrides</p> <p><code>build</code>, <code>push</code>, and <code>pull</code> sections can all be overridden on a per-deployment basis by defining <code>build</code>, <code>push</code>, and <code>pull</code> fields within a deployment definition in the <code>prefect.yaml</code> file.</p> <p>The <code>prefect deploy</code> command will use any <code>build</code>, <code>push</code>, or <code>pull</code> instructions provided in a deployment's definition in the <code>prefect.yaml</code> file.</p> <p>This capability is useful with multiple deployments that require different deployment instructions.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-build-action","title":"The build action","text":"<p>The build section of <code>prefect.yaml</code> is where any necessary side effects for running your deployments are built - the most common type of side effect produced here is a Docker image. If you initialize with the docker recipe, you will be prompted to provide required information, such as image name and tag:</p> <pre><code>prefect init --recipe docker\n&gt;&gt; image_name: &lt; insert image name here &gt;\n&gt;&gt; tag: &lt; insert image tag here &gt;\n</code></pre> <p>Use <code>--field</code> to avoid the interactive experience</p> <p>We recommend that you only initialize a recipe when you are first creating your deployment structure, and afterwards store your configuration files within version control. However, sometimes you may need to initialize programmatically and avoid the interactive prompts. To do so, provide all required fields for your recipe using the <code>--field</code> flag:</p> <p> <pre><code>prefect init --recipe docker \\\n    --field image_name=my-repo/my-image \\\n    --field tag=my-tag\n</code></pre> </p> <pre><code>build:\n- prefect_docker.deployments.steps.build_docker_image:\n    requires: prefect-docker&gt;=0.3.0\n    image_name: my-repo/my-image\n    tag: my-tag\n    dockerfile: auto\n    push: true\n</code></pre> <p>Once you've confirmed that these fields are set to their desired values, this step will automatically build a Docker image with the provided name and tag and push it to the repository referenced by the image name. As the <code>prefect-docker</code> package documentation notes, this step produces a few fields that can optionally be used in future steps or within <code>prefect.yaml</code> as template values. It is best practice to use <code>{{ image }}</code> within <code>prefect.yaml</code> (specifically the work pool's job variables section) so that you don't risk having your build step and deployment specification get out of sync with hardcoded values.  </p> <p>Note</p> <p>Note that in the build step example above, we relied on the <code>prefect-docker</code> package; in cases that deal with external services, additional packages are often required and will be auto-installed for you.</p> <p>Pass output to downstream steps</p> <p>Each deployment action can be composed of multiple steps. For example, if you wanted to build a Docker image tagged with the current commit hash, you could use the <code>run_shell_script</code> step and feed the output into the <code>build_docker_image</code> step:</p> <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre> <p>Note that the <code>id</code> field is used in the <code>run_shell_script</code> step so that its output can be referenced in the next step.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-push-action","title":"The push action","text":"<p>The push section is most critical for situations in which code is not stored on persistent filesystems or in version control.  In this scenario, code is often pushed and pulled from a Cloud storage bucket of some kind (e.g., S3, GCS, Azure Blobs, etc.).  The push section allows users to specify and customize the logic for pushing this code repository to arbitrary remote locations.</p> <p>For example, a user wishing to store their code in an S3 bucket and rely on default worker settings for its runtime environment could use the <code>s3</code> recipe:</p> <pre><code>prefect init --recipe s3\n&gt;&gt; bucket: &lt; insert bucket name here &gt;\n</code></pre> <p>Inspecting our newly created <code>prefect.yaml</code> file we find that the <code>push</code> and <code>pull</code> sections have been templated out for us as follows:</p> <pre><code>push:\n- prefect_aws.deployments.steps.push_to_s3:\n    id: push-code\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: project-name\n    credentials: null\n\npull:\n- prefect_aws.deployments.steps.pull_from_s3:\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: \"{{ push-code.folder }}\"\n    credentials: null\n</code></pre> <p>The bucket has been populated with our provided value (which also could have been provided with the <code>--field</code> flag); note that the <code>folder</code> property of the <code>push</code> step is a template - the <code>pull_from_s3</code> step outputs both a <code>bucket</code> value as well as a <code>folder</code> value that can be used to template downstream steps.  Doing this helps you keep your steps consistent across edits.</p> <p>As discussed above, if you are using blocks, the credentials section can be templated with a block reference for secure and dynamic credentials access:</p> <pre><code>push:\n- prefect_aws.deployments.steps.push_to_s3:\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: project-name\n    credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre> <p>Anytime you run <code>prefect deploy</code>, this <code>push</code> section will be executed upon successful completion of your <code>build</code> section. For more information on the mechanics of steps, see below.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-pull-action","title":"The pull action","text":"<p>The pull section is the most important section within the <code>prefect.yaml</code> file. It contains instructions for preparing your flows for a deployment run. These instructions will be executed each time a deployment created within this folder is run via a worker.</p> <p>There are three main types of steps that typically show up in a <code>pull</code> section:</p> <ul> <li><code>set_working_directory</code>: this step simply sets the working directory for the process prior to importing your flow</li> <li><code>git_clone</code>: this step clones the provided repository on the provided branch</li> <li><code>pull_from_{cloud}</code>: this step pulls the working directory from a Cloud storage location (e.g., S3)</li> </ul> <p>Use block and variable references</p> <p>All block and variable references within your pull step will remain unresolved until runtime and will be pulled each time your deployment is run. This allows you to avoid storing sensitive information insecurely; it also allows you to manage certain types of configuration from the API and UI without having to rebuild your deployment every time.</p> <p>Below is an example of how to use an existing <code>GitHubCredentials</code> block to clone a private GitHub repository:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-credentials }}\"\n</code></pre> <p>Alternatively, you can specify a <code>BitBucketCredentials</code> or <code>GitLabCredentials</code> block to clone from Bitbucket or GitLab. In lieu of a credentials block, you can also provide a GitHub, GitLab, or Bitbucket token directly to the 'access_token` field. You can use a Secret block to do this securely:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://bitbucket.org/org/repo.git\n        access_token: \"{{ prefect.blocks.secret.bitbucket-token }}\"\n</code></pre>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#utility-steps","title":"Utility steps","text":"<p>Utility steps can be used within a build, push, or pull action to assist in managing the deployment lifecycle:</p> <ul> <li><code>run_shell_script</code> allows for the execution of one or more shell commands in a subprocess, and returns the standard output and standard error of the script. This step is useful for scripts that require execution in a specific environment, or those which have specific input and output requirements.</li> </ul> <p>Here is an example of retrieving the short Git commit hash of the current repository to use as a Docker image tag:</p> <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker&gt;=0.3.0\n        image_name: my-image\n        tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre> <p>Provided environment variables are not expanded by default</p> <p>To expand environment variables in your shell script, set <code>expand_env_vars: true</code> in your <code>run_shell_script</code> step. For example:</p> <pre><code>- prefect.deployments.steps.run_shell_script:\n    id: get-user\n    script: echo $USER\n    stream_output: true\n    expand_env_vars: true\n</code></pre> <p>Without <code>expand_env_vars: true</code>, the above step would return a literal string <code>$USER</code> instead of the current user.</p> <ul> <li><code>pip_install_requirements</code> installs dependencies from a <code>requirements.txt</code> file within a specified directory.</li> </ul> <p>Below is an example of installing dependencies from a <code>requirements.txt</code> file after cloning:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        id: clone-step  # needed in order to be referenced in subsequent steps\n        repository: https://github.com/org/repo.git\n    - prefect.deployments.steps.pip_install_requirements:\n        directory: {{ clone-step.directory }}  # `clone-step` is a user-provided `id` field\n        requirements_file: requirements.txt\n</code></pre> <p>Below is an example that retrieves an access token from a 3rd party Key Vault and uses it in a private clone step:</p> <pre><code>pull:\n- prefect.deployments.steps.run_shell_script:\n    id: get-access-token\n    script: az keyvault secret show --name &lt;secret name&gt; --vault-name &lt;secret vault&gt; --query \"value\" --output tsv\n    stream_output: false\n- prefect.deployments.steps.git_clone:\n    repository: https://bitbucket.org/samples/deployments.git\n    branch: master\n    access_token: \"{{ get-access-token.stdout }}\"\n</code></pre> <p>You can also run custom steps by packaging them. In the example below, <code>retrieve_secrets</code> is a custom python module that has been packaged into the default working directory of a Docker image (which is /opt/prefect by default). <code>main</code> is the function entry point, which returns an access token (e.g. <code>return {\"access_token\": access_token}</code>) like the preceding example, but utilizing the Azure Python SDK for retrieval.</p> <pre><code>- retrieve_secrets.main:\n    id: get-access-token\n- prefect.deployments.steps.git_clone:\n    repository: https://bitbucket.org/samples/deployments.git\n    branch: master\n    access_token: '{{ get-access-token.access_token }}'\n</code></pre>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#templating-options","title":"Templating options","text":"<p>Values that you place within your <code>prefect.yaml</code> file can reference dynamic values in several different ways:</p> <ul> <li>step outputs: every step of both <code>build</code> and <code>push</code> produce named fields such as <code>image_name</code>; you can reference these fields within <code>prefect.yaml</code> and <code>prefect deploy</code> will populate them with each call.  References must be enclosed in double brackets and be of the form <code>\"{{ field_name }}\"</code></li> <li>blocks: Prefect blocks can also be referenced with the special syntax <code>{{ prefect.blocks.block_type.block_slug }}</code>. It is highly recommended that you use block references for any sensitive information (such as a GitHub access token or any credentials) to avoid hardcoding these values in plaintext</li> <li>variables: Prefect variables can also be referenced with the special syntax <code>{{ prefect.variables.variable_name }}</code>. Variables can be used to reference non-sensitive, reusable pieces of information such as a default image name or a default work pool name.</li> <li>environment variables: you can also reference environment variables with the special syntax <code>{{ $MY_ENV_VAR }}</code>. This is especially useful for referencing environment variables that are set at runtime.</li> </ul> <p>As an example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.3.0\n    image_name: my-repo/my-image\n    tag: my-tag\n    dockerfile: auto\n    push: true\n\ndeployments:\n- # base metadata\n    name: null\n    version: \"{{ build-image.tag }}\"\n    tags:\n        - \"{{ $my_deployment_tag }}\"\n        - \"{{ prefect.variables.some_common_tag }}\"\n    description: null\n    schedule: null\n\n    # flow-specific fields\n    entrypoint: null\n    parameters: {}\n\n    # infra-specific fields\n    work_pool:\n        name: \"my-k8s-work-pool\"\n        work_queue_name: null\n        job_variables:\n            image: \"{{ build-image.image }}\"\n            cluster_config: \"{{ prefect.blocks.kubernetes-cluster-config.my-favorite-config }}\"\n</code></pre> <p>So long as our <code>build</code> steps produce fields called <code>image_name</code> and <code>tag</code>, every time we deploy a new version of our deployment, the <code>{{ build-image.image }}</code> variable will be dynamically populated with the relevant values.</p> <p>Docker step</p> <p>The most commonly used build step is <code>prefect_docker.deployments.steps.build_docker_image</code> which produces both the <code>image_name</code> and <code>tag</code> fields.</p> <p>For an example, check out the deployments tutorial.</p> <p>A <code>prefect.yaml</code> file can have multiple deployment configurations that control the behavior of several deployments. These deployments can be managed independently of one another, allowing you to deploy the same flow with different configurations in the same codebase.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#working-with-multiple-deployments-with-prefectyaml","title":"Working with multiple deployments with prefect.yaml","text":"<p>Prefect supports multiple deployment declarations within the <code>prefect.yaml</code> file. This method of declaring multiple deployments allows the configuration for all deployments to be version controlled and deployed with a single command.</p> <p>New deployment declarations can be added to the <code>prefect.yaml</code> file by adding a new entry to the <code>deployments</code> list. Each deployment declaration must have a unique <code>name</code> field which is used to select deployment declarations when using the <code>prefect deploy</code> command.</p> <p>Warning</p> <p>When using a <code>prefect.yaml</code> file that is in another directory or differently named, remember that the value for the deployment <code>entrypoint</code> must be relative to the root directory of the project.  </p> <p>For example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build: ...\npush: ...\npull: ...\n\ndeployments:\n- name: deployment-1\n    entrypoint: flows/hello.py:my_flow\n    parameters:\n        number: 42,\n        message: Don't panic!\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: primary-queue\n\n- name: deployment-2\n    entrypoint: flows/goodbye.py:my_other_flow\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: secondary-queue\n\n- name: deployment-3\n    entrypoint: flows/hello.py:yet_another_flow\n    work_pool:\n        name: my-docker-work-pool\n        work_queue_name: tertiary-queue\n</code></pre> <p>This file has three deployment declarations, each referencing a different flow. Each deployment declaration has a unique <code>name</code> field and can be deployed individually by using the <code>--name</code> flag when deploying.</p> <p>For example, to deploy <code>deployment-1</code> you would run:</p> <pre><code>prefect deploy --name deployment-1\n</code></pre> <p>To deploy multiple deployments you can provide multiple <code>--name</code> flags:</p> <pre><code>prefect deploy --name deployment-1 --name deployment-2\n</code></pre> <p>To deploy multiple deployments with the same name, you can prefix the deployment name with its flow name:</p> <pre><code>prefect deploy --name my_flow/deployment-1 --name my_other_flow/deployment-1\n</code></pre> <p>To deploy all deployments you can use the <code>--all</code> flag:</p> <pre><code>prefect deploy --all\n</code></pre> <p>To deploy deployments that match a pattern you can run:</p> <pre><code>prefect deploy -n my-flow/* -n *dev/my-deployment -n dep*prod\n</code></pre> <p>The above command will deploy all deployments from the flow <code>my-flow</code>, all flows ending in <code>dev</code> with a deployment named <code>my-deployment</code>, and all deployments starting with <code>dep</code> and ending in <code>prod</code>.</p> <p>CLI Options When Deploying Multiple Deployments</p> <p>When deploying more than one deployment with a single <code>prefect deploy</code> command, any additional attributes provided via the CLI will be ignored.</p> <p>To provide overrides to a deployment via the CLI, you must deploy that deployment individually.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#reusing-configuration-across-deployments","title":"Reusing configuration across deployments","text":"<p>Because a <code>prefect.yaml</code> file is a standard YAML file, you can use YAML aliases to reuse configuration across deployments.</p> <p>This functionality is useful when multiple deployments need to share the work pool configuration, deployment actions, or other configurations.</p> <p>You can declare a YAML alias by using the <code>&amp;{alias_name}</code> syntax and insert that alias elsewhere in the file with the <code>*{alias_name}</code> syntax. When aliasing YAML maps, you can also override specific fields of the aliased map by using the <code>&lt;&lt;: *{alias_name}</code> syntax and adding additional fields below.</p> <p>We recommend adding a <code>definitions</code> section to your <code>prefect.yaml</code> file at the same level as the <code>deployments</code> section to store your aliases.</p> <p>For example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build: ...\npush: ...\npull: ...\n\ndefinitions:\n    work_pools:\n        my_docker_work_pool: &amp;my_docker_work_pool\n            name: my-docker-work-pool\n            work_queue_name: default\n            job_variables:\n                image: \"{{ build-image.image }}\"\n    schedules:\n        every_ten_minutes: &amp;every_10_minutes\n            interval: 600\n    actions:\n        docker_build: &amp;docker_build\n            - prefect_docker.deployments.steps.build_docker_image: &amp;docker_build_config\n                id: build-image\n                requires: prefect-docker&gt;=0.3.0\n                image_name: my-example-image\n                tag: dev\n                dockerfile: auto\n                push: true\n\ndeployments:\n- name: deployment-1\n    entrypoint: flows/hello.py:my_flow\n    schedule: *every_10_minutes\n    parameters:\n        number: 42,\n        message: Don't panic!\n    work_pool: *my_docker_work_pool\n    build: *docker_build # Uses the full docker_build action with no overrides\n\n- name: deployment-2\n    entrypoint: flows/goodbye.py:my_other_flow\n    work_pool: *my_docker_work_pool\n    build:\n        - prefect_docker.deployments.steps.build_docker_image:\n            &lt;&lt;: *docker_build_config # Uses the docker_build_config alias and overrides the dockerfile field\n            dockerfile: Dockerfile.custom\n\n- name: deployment-3\n    entrypoint: flows/hello.py:yet_another_flow\n    schedule: *every_10_minutes\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: primary-queue\n</code></pre> <p>In the above example, we are using YAML aliases to reuse work pool, schedule, and build configuration across multiple deployments:</p> <ul> <li><code>deployment-1</code> and <code>deployment-2</code> are using the same work pool configuration</li> <li><code>deployment-1</code> and <code>deployment-3</code> are using the same schedule</li> <li><code>deployment-1</code> and <code>deployment-2</code> are using the same build deployment action, but <code>deployment-2</code> is overriding the <code>dockerfile</code> field to use a custom Dockerfile</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-declaration-reference","title":"Deployment declaration reference","text":"","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-fields","title":"Deployment fields","text":"<p>Below are fields that can be added to each deployment declaration.</p> Property Description <code>name</code> The name to give to the created deployment. Used with the <code>prefect deploy</code> command to create or update specific deployments. <code>version</code> An optional version for the deployment. <code>tags</code> A list of strings to assign to the deployment as tags. <code>description</code> An optional description for the deployment. <code>schedule</code> An optional schedule to assign to the deployment. Fields for this section are documented in the Schedule Fields section. <code>triggers</code> An optional array of triggers to assign to the deployment <code>entrypoint</code> Required path to the <code>.py</code> file containing the flow you want to deploy (relative to the root directory of your development folder) combined with the name of the flow function. Should be in the format <code>path/to/file.py:flow_function_name</code>. <code>parameters</code> Optional default values to provide for the parameters of the deployed flow. Should be an object with key/value pairs. <code>enforce_parameter_schema</code> Boolean flag that determines whether the API should validate the parameters passed to a flow run against the parameter schema generated for the deployed flow. <code>work_pool</code> Information on where to schedule flow runs for the deployment. Fields for this section are documented in the Work Pool Fields section.","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#schedule-fields","title":"Schedule fields","text":"<p>Below are fields that can be added to a deployment declaration's <code>schedule</code> section.</p> Property Description <code>interval</code> Number of seconds indicating the time between flow runs. Cannot be used in conjunction with <code>cron</code> or <code>rrule</code>. <code>anchor_date</code> Datetime string indicating the starting or \"anchor\" date to begin the schedule. If no <code>anchor_date</code> is supplied, the current UTC time is used. Can only be used with <code>interval</code>. <code>timezone</code> String name of a time zone, used to enforce localization behaviors like DST boundaries. See the IANA Time Zone Database for valid time zones. <code>cron</code> A valid cron string. Cannot be used in conjunction with <code>interval</code> or <code>rrule</code>. <code>day_or</code> Boolean indicating how croniter handles day and day_of_week entries. Must be used with <code>cron</code>. Defaults to <code>True</code>. <code>rrule</code> String representation of an RRule schedule. See the <code>rrulestr</code> examples for syntax. Cannot be used in conjunction with <code>interval</code> or <code>cron</code>. <p>For more information about schedules, see the Schedules concept doc.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#work-pool-fields","title":"Work pool fields","text":"<p>Below are fields that can be added to a deployment declaration's <code>work_pool</code> section.</p> Property Description <code>name</code> The name of the work pool to schedule flow runs in for the deployment. <code>work_queue_name</code> The name of the work queue within the specified work pool to schedule flow runs in for the deployment. If not provided, the default queue for the specified work pool will be used. <code>job_variables</code> Values used to override the default values in the specified work pool's base job template. Maps directly to a created deployments <code>infra_overrides</code> attribute.","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-mechanics","title":"Deployment mechanics","text":"<p>Anytime you run <code>prefect deploy</code> in a directory that contains a <code>prefect.yaml</code> file, the following actions are taken in order:</p> <ul> <li>The <code>prefect.yaml</code> file is loaded. First, the <code>build</code> section is loaded and all variable and block references are resolved. The steps are then run in the order provided.</li> <li>Next, the <code>push</code> section is loaded and all variable and block references are resolved; the steps within this section are then run in the order provided</li> <li>Next, the <code>pull</code> section is templated with any step outputs but is not run.  Note that block references are not hydrated for security purposes - block references are always resolved at runtime</li> <li>Next, all variable and block references are resolved with the deployment declaration.  All flags provided via the <code>prefect deploy</code> CLI are then overlaid on the values loaded from the file.</li> <li>The final step occurs when the fully realized deployment specification is registered with the Prefect API</li> </ul> <p>Deployment Instruction Overrides</p> <p>The <code>build</code>, <code>push</code>, and <code>pull</code> sections in deployment definitions take precedence over the corresponding sections above them in <code>prefect.yaml</code>.</p> <p>Each time a step is run, the following actions are taken in order:</p> <ul> <li>The step's inputs and block / variable references are resolved (see the templating documentation above for more details).</li> <li>The step's function is imported; if it cannot be found, the special <code>requires</code> keyword is used to install the necessary packages</li> <li>The step's function is called with the resolved inputs.</li> <li>The step's output is returned and used to resolve inputs for subsequent steps.</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#next-steps","title":"Next steps","text":"<p>Now that you are familiar with creating deployments, you may want to explore infrastructure options for running your deployments:</p> <ul> <li>Managed work pools</li> <li>Push work pools</li> <li>Kubernetes work pools</li> <li>Serverless hybrid work pools</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/runtime-context/","title":"Get Information about the Runtime Context","text":"<p>Prefect tracks information about the current flow or task run with a run context. The run context can be thought of as a global variable that allows the Prefect engine to determine relationships between your runs, such as which flow your task was called from.</p> <p>The run context itself contains many internal objects used by Prefect to manage execution of your run and is only available in specific situations. For this reason, we expose a simple interface that only includes the items you care about and dynamically retrieves additional information when necessary. We call this the \"runtime context\" as it contains information that can be accessed only when a run is happening.</p> <p>Mock values via environment variable</p> <p>Oftentimes, you may want to mock certain values for testing purposes.  For example, by manually setting an ID or a scheduled start time to ensure your code is functioning properly.  Starting in version <code>2.10.3</code>, you can mock values in runtime via environment variable using the schema <code>PREFECT__RUNTIME__{SUBMODULE}__{KEY_NAME}=value</code>:  <pre><code>$ export PREFECT__RUNTIME__TASK_RUN__FAKE_KEY='foo'\n$ python -c 'from prefect.runtime import task_run; print(task_run.fake_key)' # \"foo\"\n</code></pre> </p> <p>If the environment variable mocks an existing runtime attribute, the value is cast to the same type. This works for runtime attributes of basic types (<code>bool</code>, <code>int</code>, <code>float</code> and <code>str</code>) and <code>pendulum.DateTime</code>. For complex types like <code>list</code> or <code>dict</code>, we suggest mocking them using monkeypatch or a similar tool.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/runtime-context/#accessing-runtime-information","title":"Accessing runtime information","text":"<p>The <code>prefect.runtime</code> module is the home for all runtime context access. Each major runtime concept has its own submodule:</p> <ul> <li><code>deployment</code>: Access information about the deployment for the current run</li> <li><code>flow_run</code>: Access information about the current flow run</li> <li><code>task_run</code>: Access information about the current task run</li> </ul> <p>For example:</p> my_runtime_info.py<pre><code>from prefect import flow, task\nfrom prefect import runtime\n\n@flow(log_prints=True)\ndef my_flow(x):\n    print(\"My name is\", runtime.flow_run.name)\n    print(\"I belong to deployment\", runtime.deployment.name)\n    my_task(2)\n\n@task\ndef my_task(y):\n    print(\"My name is\", runtime.task_run.name)\n    print(\"Flow run parameters:\", runtime.flow_run.parameters)\n\nmy_flow(1)\n</code></pre> <p>Running this file will produce output similar to the following:</p> <pre><code>10:08:02.948 | INFO    | prefect.engine - Created flow run 'solid-gibbon' for flow 'my-flow'\n10:08:03.555 | INFO    | Flow run 'solid-gibbon' - My name is solid-gibbon\n10:08:03.558 | INFO    | Flow run 'solid-gibbon' - I belong to deployment None\n10:08:03.703 | INFO    | Flow run 'solid-gibbon' - Created task run 'my_task-0' for task 'my_task'\n10:08:03.704 | INFO    | Flow run 'solid-gibbon' - Executing 'my_task-0' immediately...\n10:08:04.006 | INFO    | Task run 'my_task-0' - My name is my_task-0\n10:08:04.007 | INFO    | Task run 'my_task-0' - Flow run parameters: {'x': 1}\n10:08:04.105 | INFO    | Task run 'my_task-0' - Finished in state Completed()\n10:08:04.968 | INFO    | Flow run 'solid-gibbon' - Finished in state Completed('All states completed.')\n</code></pre> <p>Above, we demonstrated access to information about the current flow run, task run, and deployment. When run without a deployment (via <code>python my_runtime_info.py</code>), you should see <code>\"I belong to deployment None\"</code> logged. When information is not available, the runtime will always return an empty value. Because this flow was run outside of a deployment, there is no deployment data. If this flow was run as part of a deployment, we'd see the name of the deployment instead.</p> <p>See the runtime API reference for a full list of available attributes.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/runtime-context/#accessing-the-run-context-directly","title":"Accessing the run context directly","text":"<p>The current run context can be accessed with <code>prefect.context.get_run_context()</code>. This function will raise an exception if no run context is available, meaning you are not in a flow or task run. If a task run context is available, it will be returned even if a flow run context is available.</p> <p>Alternatively, you can access the flow run or task run context explicitly. This will, for example, allow you to access the flow run context from a task run.</p> <p>Note that we do not send the flow run context to distributed task workers because the context is costly to serialize and deserialize.</p> <pre><code>from prefect.context import FlowRunContext, TaskRunContext\n\nflow_run_ctx = FlowRunContext.get()\ntask_run_ctx = TaskRunContext.get()\n</code></pre> <p>Unlike <code>get_run_context</code>, these method calls will not raise an error if the context is not available. Instead, they will return <code>None</code>.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/secrets/","title":"Third-party Secrets: Connect to services without storing credentials in blocks","text":"<p>Credentials blocks and secret blocks are popular ways to store and retrieve sensitive information for connecting to third-party services.</p> <p>In Prefect Cloud, these block values are stored in encrypted format. Organizations whose security policies make such storage infeasible can still use Prefect to connect to third-party services securely.</p> <p>Any sensitive information that is not stored in a block can be read from the environment.</p> <p>For example, to find AWS credentials for authentication, any attributes not provided to an AWS Credentials block are sourced at runtime in the order shown in the Boto3 docs. Prefect-aws creates the session object using the values in the block and then, any missing values follow the sequence in the Boto3 docs.</p> <p>Prefect-gcp and prefect-azure follow similar patterns.</p> <p>In the example below, we interact with a Snowflake database using credentials stored in AWS Secrets Manager. This example can be generalized to other third party services that require credentials.</p>"},{"location":"guides/secrets/#prerequisites","title":"Prerequisites","text":"<ol> <li>Prefect installed.</li> <li>CLI authenticated to your Prefect Cloud account.</li> <li>Snowflake account.</li> <li>AWS account.</li> </ol>"},{"location":"guides/secrets/#steps","title":"Steps","text":"<ol> <li>Install <code>prefect-aws</code> and <code>prefect-snowflake</code> integration libraries.</li> <li>Store Snowflake password in AWS Secrets Manager.</li> <li>Create <code>AwsSecret</code> block to access the Snowflake password.</li> <li>Create <code>AwsCredentials</code> block for authentication.</li> <li>Ensure the compute environment has access to AWS credentials that are authorized to access the secret in AWS.</li> <li>Create and use <code>SnowflakeCredentials</code> and <code>SnowflakeConnector</code> blocks in Python code to interact with Snowflake.</li> </ol>"},{"location":"guides/secrets/#install-prefect-aws-and-prefect-snowflake-libraries","title":"Install <code>prefect-aws</code> and <code>prefect-snowflake</code> libraries","text":"<p>The following code will install and upgrade the necessary libraries and their dependencies.</p> <pre><code>pip install -U prefect-aws prefect-snowflake\n</code></pre>"},{"location":"guides/secrets/#store-snowflake-password-in-aws-secrets-manager","title":"Store Snowflake password in AWS Secrets Manager","text":"<p>Go to the AWS Secrets Manager console and create a new secret. Alternatively, create a secret using the AWS CLI or a script.</p> <ol> <li>In the UI, choose Store a new secret.</li> <li>Select Other type of secret.</li> <li>Input the key-value pair for your Snowflake password where the key is any string and the value is your Snowflake password.</li> <li>Copy the key for future reference and click Next.</li> <li>Enter a name for your secret, copy the name, and click Next.</li> <li>For this demo, we won't rotate the key, so click Next.</li> <li>Click Store.</li> </ol>"},{"location":"guides/secrets/#create-awssecret-block-to-access-your-snowflake-password","title":"Create <code>AwsSecret</code> block to access your Snowflake password","text":"<p>You can create blocks with Python code or via the Prefect UI. Block creation through the UI can help you visualize how the pieces fit together, so let's use it here.</p> <p>On the Blocks page, click on + to add a new block and select AWS Secret from the list of block types. Enter a name for your block and enter the secret name from AWS Secrets Manager.</p> <p>Note that if you're using a self-hosted Prefect server instance, you'll need to register the block types in the newly installed modules before creating blocks.</p> <pre><code>prefect block register -m prefect_aws &amp;&amp; prefect block register -m prefect_snowflake\n</code></pre>"},{"location":"guides/secrets/#create-awscredentials-block","title":"Create <code>AwsCredentials</code> block","text":"<p>Under the hood, Prefect is using the AWS <code>boto3</code> client to create a session.</p> <p>In the AwsCredentials section of the form, click Add + and create an AWS Credentials block by entering the necessary values.</p> <p>Values for Access Key ID and Secret Access Key will be read from the compute environment. My AWS Access Key ID and Secret Access Key values with permissions to read the AWS Secret are stored locally in my <code>~/.aws/credentials</code> file, so I'll leave those fields blank. You could enter those values at block creation, but then they would be saved to the database, and that's what we're trying to avoid. By leaving those attributes blank, Prefect knows to look to the compute environment. If the compute environment contains the necessary credentials, Prefect will use them to authenticate in the order shown in the Boto3 docs.</p> <p>The same order is followed to resolve the AWS region. Let's specify the region in our <code>AWSCredentials</code> block so that our connection works regardless of the contents of our local AWS config file or whether we run our code on AWS compute located in anther region than our secret.</p> <p>Click Create to save the blocks.</p>"},{"location":"guides/secrets/#ensure-the-compute-environment-has-access-to-aws-credentials","title":"Ensure the compute environment has access to AWS credentials","text":"<p>Ensure the compute environment contains AWS credentials with authorization to access AWS Secrets Manager. When we connect to Snowflake, Prefect will automatically use these credentials to authenticate and access the AWS secret that contains the Snowflake password.</p>"},{"location":"guides/secrets/#create-and-use-snowflakecredentials-and-snowflakeconnector-blocks-in-python-code","title":"Create and use <code>SnowflakeCredentials</code> and <code>SnowflakeConnector</code> blocks in Python code","text":"<p>Let's use Prefect's blocks for convenient access to Snowflake. We won't save the blocks, to ensure the credentials are not stored in Prefect Cloud.</p> <p>We'll create a flow that connects to Snowflake and calls two tasks. The first task creates a table and inserts some data. The second task reads the data out.</p> <pre><code>import json\nfrom prefect import flow, task\nfrom prefect_aws import AwsSecret\nfrom prefect_snowflake import SnowflakeConnector, SnowflakeCredentials\n\n\n@task\ndef setup_table(snow_connector: SnowflakeConnector) -&gt; None:\n    with snow_connector as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n\n@task\ndef fetch_data(snow_connector: SnowflakeConnector) -&gt; list:\n    all_rows = []\n    with snow_connector as connector:\n        while True:\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n\n@flow(log_prints=True)\ndef snowflake_flow():\n    aws_secret_block = AwsSecret.load(\"my-snowflake-pw\")\n\n    snow_connector = SnowflakeConnector(\n        schema=\"MY_SCHEMA\",\n        database=\"MY_DATABASE\",\n        warehouse=\"COMPUTE_WH\",\n        fetch_size=1,\n        credentials=SnowflakeCredentials(\n            role=\"MYROLE\",\n            user=\"MYUSERNAME\",\n            account=\"ab12345.us-east-2.aws\",\n            password=json.loads(aws_secret_block.read_secret()).get(\"my-snowflake-pw\"),\n        ),\n        poll_frequency_s=1,\n    )\n\n    setup_table(snow_connector)\n    all_rows = fetch_data(snow_connector)\n    print(all_rows)\n\n\nif __name__ == \"__main__\":\n    snowflake_flow()\n</code></pre> <p>Fill in the relevant details for your Snowflake account and run the script.</p> <p>Note that the flow reads the Snowflake password from the AWS Secret Manager and uses it in the <code>SnowflakeCredentials</code> block. The <code>SnowflakeConnector</code> block uses the nested <code>SnowflakeCredentials</code> block to connect to Snowflake. Again, neither of the Snowflake blocks are saved, so the credentials are not stored in Prefect Cloud.</p> <p>Check out the <code>prefect-snowflake</code> docs for more examples of working with Snowflake.</p>"},{"location":"guides/secrets/#next-steps","title":"Next steps","text":"<p>Now you can turn your flow into a deployment so that you and your team can run it remotely on a schedule, in response to an event, or manually.  </p> <p>Make sure to specify the <code>prefect-aws</code> and <code>prefect-snowflake</code> dependencies in your work pool or deployment so that they are available at runtime.</p> <p>Also ensure your compute has the AWS credentials for accessing the secret in AWS Secrets Manager.</p> <p>You've seen how to use Prefect blocks to store non-sensitive configuration and fetch sensitive configuration values from the environment. You can use this pattern to connect to other third-party services that require credentials, such as databases and APIs. You can use a similar pattern with any secret manager, or extend it to work with environment variables.</p>"},{"location":"guides/settings/","title":"Profiles &amp; Configuration","text":"<p>Prefect's local settings are documented and type-validated. </p> <p>By modifying the default settings, you can customize various aspects of the system.  You can override a setting with an environment variable or by updating the setting in a Prefect profile.</p> <p>Prefect profiles are persisted groups of settings on your local machine. A single profile is always active.</p> <p>Initially, a default profile named <code>default</code> is active and contains no settings overrides.</p> <p>All currently active settings can be viewed from the command line by running the following command:</p> <pre><code>prefect config view --show-defaults\n</code></pre> <p>When you switch to a different profile, all of the settings configured in the newly activated profile are applied. </p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#commonly-configured-settings","title":"Commonly configured settings","text":"<p>This section describes some commonly configured settings.  See Configuring settings for details on setting and unsetting configuration values.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_api_key","title":"PREFECT_API_KEY","text":"<p>The <code>PREFECT_API_KEY</code> value specifies the API key used to authenticate with Prefect Cloud.</p> <pre><code>PREFECT_API_KEY=\"[API-KEY]\"\n</code></pre> <p>Generally, you will set the <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> for your active profile by running <code>prefect cloud login</code>.  If you're curious, read more about managing API keys. </p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_api_url","title":"PREFECT_API_URL","text":"<p>The <code>PREFECT_API_URL</code> value specifies the API endpoint of your Prefect Cloud workspace or a self-hosted Prefect server instance.</p> <p>For example, if using Prefect Cloud:</p> <pre><code>PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n</code></pre> <p>You can view your Account ID and Workspace ID in your browser URL when at a Prefect Cloud workspace page.  For example: https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here.</p> <p>If using a local Prefect server instance, set your API URL like this:</p> <pre><code>PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n</code></pre> <p><code>PREFECT_API_URL</code> setting for workers</p> <p>If using a worker (agent and block-based deployments are legacy) that can create flow runs for deployments in remote environments,  <code>PREFECT_API_URL</code> must be set for the environment in which your worker is running.</p> <p>If you want the worker to communicate with Prefect Cloud or a Prefect server instance from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p> <p>Running the Prefect UI behind a reverse proxy</p> <p>When using a reverse proxy (such as Nginx or Traefik) to proxy traffic to a locally-hosted Prefect UI instance, the Prefect server instance also needs to be configured to know how to connect to the API.  The <code>PREFECT_UI_API_URL</code> should be set to the external proxy URL (e.g. if your external URL is https://prefect-server.example.com/ then set <code>PREFECT_UI_API_URL=https://prefect-server.example.com/api</code> for the Prefect server process).  You can also accomplish this by setting <code>PREFECT_API_URL</code> to the API URL, as this setting is used as a fallback if <code>PREFECT_UI_API_URL</code> is not set.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_home","title":"PREFECT_HOME","text":"<p>The <code>PREFECT_HOME</code> value specifies the local Prefect directory for configuration files, profiles, and the location of the default Prefect SQLite database.</p> <pre><code>PREFECT_HOME='~/.prefect'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_local_storage_path","title":"PREFECT_LOCAL_STORAGE_PATH","text":"<p>The <code>PREFECT_LOCAL_STORAGE_PATH</code> value specifies the default location of local storage for flow runs.</p> <pre><code>PREFECT_LOCAL_STORAGE_PATH='${PREFECT_HOME}/storage'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#csrf-protection-settings","title":"CSRF Protection Settings","text":"<p>If using a local Prefect server instance, you can configure CSRF protection settings.</p> <p><code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED</code> - Activates CSRF protection on the server, requiring valid CSRF tokens for applicable requests. Recommended for production to prevent CSRF attacks. Defaults to False.</p> <pre><code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED=True\n</code></pre> <p><code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION</code> - Sets the expiration duration for server-issued CSRF tokens, influencing how often tokens need to be refreshed. The default is 1 hour.</p> <pre><code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION='3600'  # 1 hour in seconds\n</code></pre> <p>By default clients expect that CSRF protection is enabled on the server. If you are running a server without CSRF protection, you can disable CSRF support in the client.</p> <p><code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED</code> - Enables or disables CSRF token handling in the Prefect client. When enabled, the client manages CSRF tokens for state-changing API requests. Defaults to True.</p> <pre><code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED=True\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#database-settings","title":"Database settings","text":"<p>If running a self-hosted Prefect server instance, there are several database configuration settings you can read about here.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#logging-settings","title":"Logging settings","text":"<p>Prefect provides several logging configuration settings that you can read about in the logging docs.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#configuring-settings","title":"Configuring settings","text":"<p>The <code>prefect config</code> CLI commands enable you to view, set, and unset settings.</p> Command Description set Change the value for a setting. unset Restore the default value for a setting. view Display the current settings.","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#viewing-settings-from-the-cli","title":"Viewing settings from the CLI","text":"<p>The <code>prefect config view</code> command will display settings that override default values.</p> <pre><code>$ prefect config view\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG'\n</code></pre> <p>You can show the sources of values with <code>--show-sources</code>:</p> <pre><code>$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG' (from env)\n</code></pre> <p>You can also include default values with <code>--show-defaults</code>:</p> <pre><code>$ prefect config view --show-defaults\nPREFECT_PROFILE='default'\nPREFECT_AGENT_PREFETCH_SECONDS='10' (from defaults)\nPREFECT_AGENT_QUERY_INTERVAL='5.0' (from defaults)\nPREFECT_API_KEY='None' (from defaults)\nPREFECT_API_REQUEST_TIMEOUT='60.0' (from defaults)\nPREFECT_API_URL='None' (from defaults)\n...\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#setting-and-clearing-values","title":"Setting and clearing values","text":"<p>The <code>prefect config set</code> command lets you change the value of a default setting.</p> <p>A commonly used example is setting the <code>PREFECT_API_URL</code>, which you may need to change when interacting with different Prefect server instances or Prefect Cloud.</p> <pre><code># use a local Prefect server\nprefect config set PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n\n# use Prefect Cloud\nprefect config set PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n</code></pre> <p>If you want to configure a setting to use its default value, use the <code>prefect config unset</code> command.</p> <pre><code>prefect config unset PREFECT_API_URL\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#overriding-defaults-with-environment-variables","title":"Overriding defaults with environment variables","text":"<p>All settings have keys that match the environment variable that can be used to override them.</p> <p>For example, configuring the home directory:</p> <pre><code># environment variable\nexport PREFECT_HOME=\"/path/to/home\"\n</code></pre> <pre><code># python\nimport prefect.settings\nprefect.settings.PREFECT_HOME.value()  # PosixPath('/path/to/home')\n</code></pre> <p>Configuring the a server instance's port:</p> <pre><code># environment variable\nexport PREFECT_SERVER_API_PORT=4242\n</code></pre> <pre><code># python\nprefect.settings.PREFECT_SERVER_API_PORT.value()  # 4242\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#configuration-profiles","title":"Configuration profiles","text":"<p>Prefect allows you to persist settings instead of setting an environment variable each time you open a new shell. Settings are persisted to profiles, which allow you to move between groups of settings quickly.</p> <p>The <code>prefect profile</code> CLI commands enable you to create, review, and manage profiles.</p> Command Description create Create a new profile. delete Delete the given profile. inspect Display settings from a given profile; defaults to active. ls List profile names. rename Change the name of a profile. use Switch the active profile. <p>If you configured settings for a profile, <code>prefect profile inspect</code> displays those settings:</p> <pre><code>$ prefect profile inspect\nPREFECT_PROFILE = \"default\"\nPREFECT_API_KEY = \"pnu_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nPREFECT_API_URL = \"http://127.0.0.1:4200/api\"\n</code></pre> <p>You can pass the name of a profile to view its settings:</p> <pre><code>$ prefect profile create test\n$ prefect profile inspect test\nPREFECT_PROFILE=\"test\"\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#creating-and-removing-profiles","title":"Creating and removing profiles","text":"<p>Create a new profile with no settings:</p> <pre><code>$ prefect profile create test\nCreated profile 'test' at /Users/terry/.prefect/profiles.toml.\n</code></pre> <p>Create a new profile <code>foo</code> with settings cloned from an existing <code>default</code> profile:</p> <pre><code>$ prefect profile create foo --from default\nCreated profile 'cloud' matching 'default' at /Users/terry/.prefect/profiles.toml.\n</code></pre> <p>Rename a profile:</p> <pre><code>$ prefect profile rename temp test\nRenamed profile 'temp' to 'test'.\n</code></pre> <p>Remove a profile:</p> <pre><code>$ prefect profile delete test\nRemoved profile 'test'.\n</code></pre> <p>Removing the default profile resets it:</p> <pre><code>$ prefect profile delete default\nReset profile 'default'.\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#change-values-in-profiles","title":"Change values in profiles","text":"<p>Set a value in the current profile:</p> <pre><code>$ prefect config set VAR=X\nSet variable 'VAR' to 'X'\nUpdated profile 'default'\n</code></pre> <p>Set multiple values in the current profile:</p> <pre><code>$ prefect config set VAR2=Y VAR3=Z\nSet variable 'VAR2' to 'Y'\nSet variable 'VAR3' to 'Z'\nUpdated profile 'default'\n</code></pre> <p>You can set a value in another profile by passing the <code>--profile NAME</code> option to a CLI command:</p> <pre><code>$ prefect --profile \"foo\" config set VAR=Y\nSet variable 'VAR' to 'Y'\nUpdated profile 'foo'\n</code></pre> <p>Unset values in the current profile to restore the defaults:</p> <pre><code>$ prefect config unset VAR2 VAR3\nUnset variable 'VAR2'\nUnset variable 'VAR3'\nUpdated profile 'default'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#inspecting-profiles","title":"Inspecting profiles","text":"<p>See a list of available profiles:</p> <pre><code>$ prefect profile ls\n* default\ncloud\ntest\nlocal\n</code></pre> <p>View all settings for a profile:</p> <pre><code>$ prefect profile inspect cloud\nPREFECT_API_URL='https://api.prefect.cloud/api/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx\nx/workspaces/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\nPREFECT_API_KEY='xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'          \n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#using-profiles","title":"Using profiles","text":"<p>The profile named <code>default</code> is used by default. There are several methods to switch to another profile.</p> <p>The recommended method is to use the <code>prefect profile use</code> command with the name of the profile:</p> <pre><code>$ prefect profile use foo\nProfile 'test' now active.\n</code></pre> <p>Alternatively, you can set the environment variable <code>PREFECT_PROFILE</code> to the name of the profile:</p> <pre><code>export PREFECT_PROFILE=foo\n</code></pre> <p>Or, specify the profile in the CLI command for one-time usage:</p> <pre><code>prefect --profile \"foo\" ...\n</code></pre> <p>Note that this option must come before the subcommand. For example, to list flow runs using the profile <code>foo</code>:</p> <pre><code>prefect --profile \"foo\" flow-run ls\n</code></pre> <p>You may use the <code>-p</code> flag as well:</p> <pre><code>prefect -p \"foo\" flow-run ls\n</code></pre> <p>You may also create an 'alias' to automatically use your profile:</p> <pre><code>$ alias prefect-foo=\"prefect --profile 'foo' \"\n# uses our profile!\n$ prefect-foo config view  \n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#conflicts-with-environment-variables","title":"Conflicts with environment variables","text":"<p>If setting the profile from the CLI with <code>--profile</code>, environment variables that conflict with settings in the profile will be ignored.</p> <p>In all other cases, environment variables will take precedence over the value in the profile.</p> <p>For example, a value set in a profile will be used by default:</p> <pre><code>$ prefect config set PREFECT_LOGGING_LEVEL=\"ERROR\"\n$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='ERROR' (from profile)\n</code></pre> <p>But, setting an environment variable will override the profile setting:</p> <pre><code>$ export PREFECT_LOGGING_LEVEL=\"DEBUG\"\n$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG' (from env)\n</code></pre> <p>Unless the profile is explicitly requested when using the CLI:</p> <pre><code>$ prefect --profile default config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='ERROR' (from profile)\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#profile-files","title":"Profile files","text":"<p>Profiles are persisted to the file location specified by <code>PREFECT_PROFILES_PATH</code>.  The default location is a <code>profiles.toml</code> file in the <code>PREFECT_HOME</code> directory:</p> <pre><code>$ prefect config view --show-defaults\n...\nPREFECT_PROFILES_PATH='${PREFECT_HOME}/profiles.toml'\n...\n</code></pre> <p>The TOML format is used to store profile data.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/specifying-upstream-dependencies/","title":"Specifying Upstream Dependencies","text":"<p>Results from a task can be provided to other tasks (or subflows) as upstream dependencies. Prefect uses upstream dependencies in two ways:</p> <ol> <li>To populate dependency arrows in the flow run graph</li> <li>To determine execution order for concurrently submitted units of work that depend on each other</li> </ol> <p>Tasks vs. other functions</p> <p>Only results from tasks inform Prefect's ability to determine dependencies. Return values from functions without task decorators, including subflows, do not carry the same information about their origin as task results.</p> <p>When using non-sequential task runners such as the <code>ConcurrentTaskRunner</code> or <code>DaskTaskRunner</code>, the order of execution for submitted tasks is not guaranteed unless their dependencies are specified.</p> <p>For example, compare how tasks submitted to the <code>ConcurrentTaskRunner</code> behave with and without upstream dependencies by clicking on the tabs below.</p> Without dependenciesWith dependencies <pre><code>@flow(log_prints=True) # Default task runner is ConcurrentTaskRunner\ndef flow_of_tasks():\n    # no dependencies, execution is order not guaranteed\n    first.submit()\n    second.submit()\n    third.submit()\n\n@task\ndef first():\n    print(\"I'm first!\")\n\n@task\ndef second():\n    print(\"I'm second!\")\n\n@task\ndef third():\n    print(\"I'm third!\")\n</code></pre> <pre><code>Flow run 'pumpkin-puffin' - Created task run 'first-0' for task 'first'\nFlow run 'pumpkin-puffin' - Submitted task run 'first-0' for execution.\nFlow run 'pumpkin-puffin' - Created task run 'second-0' for task 'second'\nFlow run 'pumpkin-puffin' - Submitted task run 'second-0' for execution.\nFlow run 'pumpkin-puffin' - Created task run 'third-0' for task 'third'\nFlow run 'pumpkin-puffin' - Submitted task run 'third-0' for execution.\nTask run 'third-0' - I'm third!\nTask run 'first-0' - I'm first!\nTask run 'second-0' - I'm second!\nTask run 'second-0' - Finished in state Completed()\nTask run 'third-0' - Finished in state Completed()\nTask run 'first-0' - Finished in state Completed()\nFlow run 'pumpkin-puffin' - Finished in state Completed('All states completed.')\n</code></pre> <pre><code>@flow(log_prints=True) # Default task runner is ConcurrentTaskRunner\ndef flow_of_tasks():\n    # with dependencies, tasks execute in order\n    first_result = first.submit()\n    second_result = second.submit(first_result)\n    third.submit(second_result)\n\n@task\ndef first():\n    print(\"I'm first!\")\n\n@task\ndef second(input):\n    print(\"I'm second!\")\n\n@task\ndef third(input):\n    print(\"I'm third!\")\n</code></pre> <pre><code>Flow run 'statuesque-waxbill' - Created task run 'first-0' for task 'first'\nFlow run 'statuesque-waxbill' - Submitted task run 'first-0' for execution.\nFlow run 'statuesque-waxbill' - Created task run 'second-0' for task 'second'\nFlow run 'statuesque-waxbill' - Submitted task run 'second-0' for execution.\nFlow run 'statuesque-waxbill' - Created task run 'third-0' for task 'third'\nFlow run 'statuesque-waxbill' - Submitted task run 'third-0' for execution.\nTask run 'first-0' - I'm first!\nTask run 'first-0' - Finished in state Completed()\nTask run 'second-0' - I'm second!\nTask run 'second-0' - Finished in state Completed()\nTask run 'third-0' - I'm third!\nTask run 'third-0' - Finished in state Completed()\nFlow run 'statuesque-waxbill' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#determination-methods","title":"Determination methods","text":"<p>A task or subflow's upstream dependencies can be inferred automatically via its inputs, or stated explicitly via the <code>wait_for</code> parameter.</p>","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#automatic","title":"Automatic","text":"<p>When a result from a task is used as input for another task, Prefect automatically recognizes the task that result originated from as an upstream dependency.</p> <p>This applies to every way you can run tasks with Prefect, whether you're calling the task function directly, calling <code>.submit()</code>, or calling <code>.map()</code>. Subflows similarly recognize tasks results as upstream dependencies.</p> <pre><code>from prefect import flow, task\n\n\n@flow(log_prints=True)\ndef flow_of_tasks():\n    upstream_result = upstream.submit()\n    downstream_1_result = downstream_1.submit(upstream_result)\n    downstream_2_result = downstream_2.submit(upstream_result)\n    mapped_task_results = mapped_task.map([downstream_1_result, downstream_2_result])\n    final_task(mapped_task_results)\n\n@task\ndef upstream():\n    return \"Hello from upstream!\"\n\n@task\ndef downstream_1(input):\n    return input\n\n@task\ndef downstream_2(input):\n    return input\n\n@task\ndef mapped_task(input):\n    return input\n\n@task\ndef final_task(input):\n    print(input)\n</code></pre> Flow run graph displaying inferred dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#manual","title":"Manual","text":"<p>Tasks that do not share data can be informed of their upstream dependencies through the <code>wait_for</code> parameter. Just as with automatic dependencies, this applies to direct task function calls, <code>.submit()</code>, <code>.map()</code>, and subflows.</p> <p>Differences with <code>.map()</code></p> <p>Manually defined upstream dependencies apply to all tasks submitted by <code>.map()</code>, so each mapped task must wait for all upstream dependencies passed into <code>wait_for</code> to finish. This is distinct from automatic dependencies for mapped tasks, where each mapped task must only wait for the upstream tasks whose results it depends on.</p> <pre><code>from prefect import flow, task\n\n\n@flow(log_prints=True)\ndef flow_of_tasks():\n    upstream_result = upstream.submit()\n    downstream_1_result = downstream_1.submit(wait_for=[upstream_result])\n    downstream_2_result = downstream_2.submit(wait_for=[upstream_result])\n    mapped_task_results = mapped_task.map([1, 2], wait_for=[downstream_1_result, downstream_2_result])\n    final_task(wait_for=mapped_task_results)\n\n@task\ndef upstream():\n    pass\n\n@task\ndef downstream_1():\n    pass\n\n@task\ndef downstream_2():\n    pass\n\n@task\ndef mapped_task(input):\n    pass\n\n@task\ndef final_task():\n    pass\n</code></pre> Flow run graph displaying manual dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#deployments-as-dependencies","title":"Deployments as dependencies","text":"<p>For more complex workflows, parts of your logic may require additional resources, different infrastructure, or independent parallel execution. A typical approach for addressing these needs is to execute that logic as separate deployment runs from within a flow.</p> <p>Composing deployment runs into a flow so that they can be treated as upstream dependencies is as simple as calling <code>run_deployment</code> from within a task.</p> <p>Given a deployment <code>process-user</code> of flow <code>parallel-work</code>, a flow of deployments might look like this:</p> <pre><code>from prefect import flow, task\nfrom prefect.deployments import run_deployment\n\n\n@flow\ndef flow_of_deployments():\n    deployment_run_1 = run_deployment_task.submit(\n        flow_name=\"parallel-work\",\n        deployment_name=\"process-user\",\n        parameters={\"user_id\": 1},\n    )\n    deployment_run_2 = run_deployment_task.submit(\n        flow_name=\"parallel-work\",\n        deployment_name=\"process-user\",\n        parameters={\"user_id\": 2},\n    )\n    downstream_task(wait_for=[deployment_run_1, deployment_run_2])\n\n\n@task(task_run_name=\"Run deployment {flow_name}/{deployment_name}\")\ndef run_deployment_task(\n    flow_name: str,\n    deployment_name: str,\n    parameters: dict\n):\n    run_deployment(\n        name=f\"{flow_name}/{deployment_name}\",\n        parameters=parameters\n    )\n\n\n@task\ndef downstream_task():\n    print(\"I'm downstream!\")\n</code></pre> <p>By default, deployments started from <code>run_deployment</code> will also appear as subflows for tracking purposes. This behavior can be disabled by setting the <code>as_subflow</code> parameter for <code>run_deployment</code> to <code>False</code>.</p> Flow run graph displaying deployments as dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/state-change-hooks/","title":"State Change Hooks","text":"<p>State change hooks execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow. This guide provides examples of real-world use cases.</p>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#example-use-cases","title":"Example use cases","text":"","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#send-a-notification-when-a-flow-run-fails","title":"Send a notification when a flow run fails","text":"<p>State change hooks enable you to customize messages sent when tasks transition between states, such as sending notifications containing sensitive information when tasks enter a <code>Failed</code> state. Let's run a client-side hook upon a flow run entering a <code>Failed</code> state.</p> <pre><code>from prefect import flow\nfrom prefect.blocks.core import Block\nfrom prefect.settings import PREFECT_API_URL\n\ndef notify_slack(flow, flow_run, state):\n    slack_webhook_block = Block.load(\n        \"slack-webhook/my-slack-webhook\"\n    )\n\n    slack_webhook_block.notify(\n        (\n            f\"Your job {flow_run.name} entered {state.name} \"\n            f\"with message:\\n\\n\"\n            f\"See &lt;https://{PREFECT_API_URL.value()}/flow-runs/\"\n            f\"flow-run/{flow_run.id}|the flow run in the UI&gt;\\n\\n\"\n            f\"Tags: {flow_run.tags}\\n\\n\"\n            f\"Scheduled start: {flow_run.expected_start_time}\"\n        )\n    )\n\n@flow(on_failure=[notify_slack], retries=1)\ndef failing_flow():\n    raise ValueError(\"oops!\")\n\nif __name__ == \"__main__\":\n    failing_flow()\n</code></pre> <p>Note that because we've configured retries in this example, the <code>on_failure</code> hook will not run until all <code>retries</code> have completed, when the flow run enters a <code>Failed</code> state.</p>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#delete-a-cloud-run-job-when-a-flow-run-crashes","title":"Delete a Cloud Run job when a flow run crashes","text":"<p>State change hooks can aid in managing infrastructure cleanup in scenarios where tasks spin up individual infrastructure resources independently of Prefect. When a flow run crashes, tasks may exit abruptly, resulting in the potential omission of cleanup logic within the tasks. State change hooks can be used to ensure infrastructure is properly cleaned up even when a flow run enters a <code>Crashed</code> state!</p> <p>Let's create a hook that deletes a Cloud Run job if the flow run crashes.</p> <pre><code>import os\nfrom prefect import flow, task\nfrom prefect.blocks.system import String\nfrom prefect.client import get_client\nimport prefect.runtime\n\nasync def delete_cloud_run_job(flow, flow_run, state):\n    \"\"\"Flow run state change hook that deletes a Cloud Run Job if\n    the flow run crashes.\"\"\"\n\n    # retrieve Cloud Run job name\n    cloud_run_job_name = await String.load(\n        name=\"crashing-flow-cloud-run-job\"\n    )\n\n    # delete Cloud Run job\n    delete_job_command = f\"yes | gcloud beta run jobs delete \n    {cloud_run_job_name.value} --region us-central1\"\n    os.system(delete_job_command)\n\n    # clean up the Cloud Run job string block as well\n    async with get_client() as client:\n        block_document = await client.read_block_document_by_name(\n            \"crashing-flow-cloud-run-job\", block_type_slug=\"string\"\n        )\n        await client.delete_block_document(block_document.id)\n\n@task\ndef my_task_that_crashes():\n    raise SystemExit(\"Crashing on purpose!\")\n\n@flow(on_crashed=[delete_cloud_run_job])\ndef crashing_flow():\n    \"\"\"Save the flow run name (i.e. Cloud Run job name) as a \n    String block. It then executes a task that ends up crashing.\"\"\"\n    flow_run_name = prefect.runtime.flow_run.name\n    cloud_run_job_name = String(value=flow_run_name)\n    cloud_run_job_name.save(\n        name=\"crashing-flow-cloud-run-job\", overwrite=True\n    )\n\n    my_task_that_crashes()\n\nif __name__ == \"__main__\":\n    crashing_flow()\n</code></pre>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/testing/","title":"Testing","text":"<p>Once you have some awesome flows, you probably want to test them!</p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/testing/#unit-testing-flows","title":"Unit testing flows","text":"<p>Prefect provides a simple context manager for unit tests that allows you to run flows and tasks against a temporary local SQLite database.</p> <pre><code>from prefect import flow\nfrom prefect.testing.utilities import prefect_test_harness\n\n@flow\ndef my_favorite_flow():\n    return 42\n\ndef test_my_favorite_flow():\n  with prefect_test_harness():\n      # run the flow against a temporary testing database\n      assert my_favorite_flow() == 42\n</code></pre> <p>For more extensive testing, you can leverage <code>prefect_test_harness</code> as a fixture in your unit testing framework. For example, when using <code>pytest</code>:</p> <pre><code>from prefect import flow\nimport pytest\nfrom prefect.testing.utilities import prefect_test_harness\n\n@pytest.fixture(autouse=True, scope=\"session\")\ndef prefect_test_fixture():\n    with prefect_test_harness():\n        yield\n\n@flow\ndef my_favorite_flow():\n    return 42\n\ndef test_my_favorite_flow():\n    assert my_favorite_flow() == 42\n</code></pre> <p>Note</p> <p>In this example, the fixture is scoped to run once for the entire test session. In most cases, you will not need a clean database for each test and just want to isolate your test runs to a test database. Creating a new test database per test creates significant overhead, so we recommend scoping the fixture to the session. If you need to isolate some tests fully, you can use the test harness again to create a fresh database.</p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/testing/#unit-testing-tasks","title":"Unit testing tasks","text":"<p>To test an individual task, you can access the original function using <code>.fn</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_favorite_task():\n    return 42\n\n@flow\ndef my_favorite_flow():\n    val = my_favorite_task()\n    return val\n\ndef test_my_favorite_task():\n    assert my_favorite_task.fn() == 42\n</code></pre> <p>Disable logger</p> <p>If your task makes uses a logger, you can disable the logger in order to avoid the <code>RuntimeError</code> raised from a missing flow context. <pre><code>from prefect.logging import disable_run_logger\n\ndef test_my_favorite_task():\n    with disable_run_logger():\n        assert my_favorite_task.fn() == 42\n</code></pre></p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/troubleshooting/","title":"Troubleshooting","text":"<p>Don't Panic! If you experience an error with Prefect, there are many paths to understanding and resolving it. The first troubleshooting step is confirming that you are running the latest version of Prefect. If you are not, be sure to upgrade to the latest version, since the issue may have already been fixed. Beyond that, there are several categories of errors:</p> <ul> <li>The issue may be in your flow code, in which case you should carefully read the logs.</li> <li>The issue could be with how you are authenticated, and whether or not you are connected to Cloud.</li> <li>The issue might have to do with how your code is executed.</li> </ul>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#upgrade","title":"Upgrade","text":"<p>Prefect is constantly evolving, adding new features and fixing bugs. Chances are that a patch has already been identified and released. Search existing issues for similar reports and check out the Release Notes. Upgrade to the newest version with the following command:</p> <pre><code>pip install --upgrade prefect\n</code></pre> <p>Different components may use different versions of Prefect:</p> <ul> <li>Cloud will generally always be the newest version. Cloud is continuously deployed by the Prefect team. When using a self-hosted server, you can control this version.</li> <li>Workers and agents typically don't change versions frequently, and are usually whatever the latest version was at the time of creation. Workers and agents provision infrastructure for flow runs, so upgrading them may help with infrastructure problems.</li> <li>Flows could use a different version than the worker or agent that created them, especially when running in different environments. Suppose your worker and flow both use the latest official Docker image, but your worker was created a month ago. Your worker will often be on an older version than your flow.</li> </ul> <p>Integration Versions</p> <p>Keep in mind that integrations are versioned and released independently of the core Prefect library. They should be upgraded simultaneously with the core library, using the same method.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#logs","title":"Logs","text":"<p>In many cases, there will be an informative stack trace in Prefect's logs. Read it carefully, locate the source of the error, and try to identify the cause.</p> <p>There are two types of logs:</p> <ul> <li>Flow and task logs are always scoped to a flow. They are sent to Prefect and are viewable in the UI.</li> <li>Worker and agent logs are not scoped to a flow and may have more information on what happened before the flow started. These logs are generally only available where the worker or agent is running.</li> </ul> <p>If your flow and task logs are empty, there may have been an infrastructure issue that prevented your flow from starting. Check your worker logs for more details.</p> <p>If there is no clear indication of what went wrong, try updating the logging level from the default <code>INFO</code> level to the <code>DEBUG</code> level. Settings such as the logging level are propagated from the worker environment to the flow run environment and can be set via environment variables or the <code>prefect config set</code> CLI:</p> <pre><code># Using the CLI\nprefect config set PREFECT_LOGGING_LEVEL=DEBUG\n\n# Using environment variables\nexport PREFECT_LOGGING_LEVEL=DEBUG\n</code></pre> <p>The <code>DEBUG</code> logging level produces a high volume of logs so consider setting it back to <code>INFO</code> once any issues are resolved.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#cloud","title":"Cloud","text":"<p>When using Prefect Cloud, there are the additional concerns of authentication and authorization. The Prefect API authenticates users and service accounts - collectively known as actors - with API keys. Missing, incorrect, or expired API keys will result in a 401 response with detail <code>Invalid authentication credentials</code>. Use the following command to check your authentication, replacing <code>$PREFECT_API_KEY</code> with your API key:</p> <pre><code>curl -s -H \"Authorization: Bearer $PREFECT_API_KEY\" \"https://api.prefect.cloud/api/me/\"\n</code></pre> <p>Users vs Service Accounts</p> <p>Service accounts - sometimes referred to as bots - represent non-human actors that interact with Prefect such as workers and CI/CD systems. Each human that interacts with Prefect should be represented as a user. User API keys start with <code>pnu_</code> and service account API keys start with <code>pnb_</code>.</p> <p>Supposing the response succeeds, let's check our authorization. Actors can be members of workspaces. An actor attempting an action in a workspace they are not a member of will result in a 404 response. Use the following command to check your actor's workspace memberships:</p> <pre><code>curl -s -H \"Authorization: Bearer $PREFECT_API_KEY\" \"https://api.prefect.cloud/api/me/workspaces\"\n</code></pre> <p>Formatting JSON</p> <p>Python comes with a helpful tool for formatting JSON. Append the following to the end of the command above to make the output more readable: <code>| python -m json.tool</code></p> <p>Make sure your actor is a member of the workspace you are working in. Within a workspace, an actor has a role which grants them certain permissions. Insufficient permissions will result in an error. For example, starting an agent or worker with the Viewer role, will result in errors.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#execution","title":"Execution","text":"<p>Prefect flows can be executed locally by the user, or remotely by a worker or agent. Local execution generally means that you - the user - run your flow directly with a command like <code>python flow.py</code>. Remote execution generally means that a worker runs your flow via a deployment, optionally on different infrastructure.</p> <p>With remote execution, the creation of your flow run happens separately from its execution. Flow runs are assigned to a work pool and a work queue. For flow runs to execute, a worker must be subscribed to the work pool and work queue, otherwise the flow runs will go from <code>Scheduled</code> to <code>Late</code>. Ensure that your work pool and work queue have a subscribed worker.</p> <p>Local and remote execution can also differ in their treatment of relative imports. If switching from local to remote execution results in local import errors, try replicating the behavior by executing the flow locally with the <code>-m</code> flag (i.e. <code>python -m flow</code> instead of <code>python flow.py</code>). Read more about <code>-m</code> here.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#api-tests-return-an-unexpected-307-redirected","title":"API tests return an unexpected 307 Redirected","text":"<p>Summary: Requests require a trailing <code>/</code> in the request URL.</p> <p>If you write a test that does not include a trailing <code>/</code> when making a request to a specific endpoint:</p> <pre><code>async def test_example(client):\n    response = await client.post(\"/my_route\")\n    assert response.status_code == 201\n</code></pre> <p>You'll see a failure like:</p> <pre><code>E       assert 307 == 201\nE        +  where 307 = &lt;Response [307 Temporary Redirect]&gt;.status_code\n</code></pre> <p>To resolve this, include the trailing <code>/</code>:</p> <pre><code>async def test_example(client):\n    response = await client.post(\"/my_route/\")\n    assert response.status_code == 201\n</code></pre> <p>Note: requests to nested URLs may exhibit the opposite behavior and require no trailing slash:</p> <pre><code>async def test_nested_example(client):\n    response = await client.post(\"/my_route/filter/\")\n    assert response.status_code == 307\n\n    response = await client.post(\"/my_route/filter\")\n    assert response.status_code == 200\n</code></pre> <p>Reference: \"HTTPX disabled redirect following by default\" in <code>0.22.0</code>.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#pytestpytestunraisableexceptionwarning-or-resourcewarning","title":"<code>pytest.PytestUnraisableExceptionWarning</code> or <code>ResourceWarning</code>","text":"<p>As you're working with one of the <code>FlowRunner</code> implementations, you may get an error like this one:</p> <pre><code>E               pytest.PytestUnraisableExceptionWarning: Exception ignored in: &lt;ssl.SSLSocket fd=-1, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0&gt;\nE\nE               Traceback (most recent call last):\nE                 File \".../pytest_asyncio/plugin.py\", line 306, in setup\nE                   res = await func(**_add_kwargs(func, kwargs, event_loop, request))\nE               ResourceWarning: unclosed &lt;ssl.SSLSocket fd=10, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 60605), raddr=('127.0.0.1', 6443)&gt;\n\n.../_pytest/unraisableexception.py:78: PytestUnraisableExceptionWarning\n</code></pre> <p>This error is saying that your test suite (or the <code>prefect</code> library code) opened a connection to something (like a Docker daemon or a Kubernetes cluster) and didn't close it.</p> <p>It may help to re-run the specific test with <code>PYTHONTRACEMALLOC=25 pytest ...</code> so that Python can display more of the stack trace where the connection was opened.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/upgrade-guide-agents-to-workers/","title":"Upgrade from Agents to Workers","text":"<p>Upgrading from agents to workers significantly enhances the experience of deploying flows. It simplifies the specification of each flow's infrastructure and runtime environment.</p> <p>A worker is the fusion of an agent with an infrastructure block. Like agents, workers poll a work pool for flow runs that are scheduled to start. Like infrastructure blocks, workers are typed - they work with only one kind of infrastructure, and they specify the default configuration for jobs submitted to that infrastructure.</p> <p>Accordingly, workers are not a drop-in replacement for agents. Using workers requires deploying flows differently. In particular, deploying a flow with a worker does not involve specifying an infrastructure block. Instead, infrastructure configuration is specified on the work pool and passed to each worker that polls work from that pool.</p> <p>This guide provides an overview of the differences between agents and workers. It also describes how to upgrade from agents to workers in just a few quick steps.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#enhancements","title":"Enhancements","text":"","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#workers","title":"Workers","text":"<ul> <li>Improved visibility into the status of each worker, including when a worker was started and when it last polled.</li> <li>Better handling of race conditions for high availability use cases.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#work-pools","title":"Work pools","text":"<ul> <li>Work pools allow greater customization and governance of infrastructure parameters for deployments via their base job template.</li> <li>Prefect Cloud push work pools enable flow execution in your cloud provider environment without needing to host a worker.</li> <li>Prefect Cloud managed work pools allow you to run flows on Prefect's infrastructure, without needing to host a worker or configure cloud provider infrastructure.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#improved-deployment-interfaces","title":"Improved deployment interfaces","text":"<ul> <li>The Python deployment experience with <code>.deploy()</code> or the alternative deployment experience with <code>prefect.yaml</code> are more flexible and easier to use than block and agent-based deployments.</li> <li>Both options allow you to deploy multiple flows with a single command.</li> <li>Both options allow you to build Docker images for your flows to create portable execution environments.</li> <li>The YAML-based API supports templating to enable dryer deployment definitions.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#whats-different","title":"What's different","text":"<ol> <li> <p>Deployment CLI and Python SDK:</p> <p><code>prefect deployment build &lt;entrypoint&gt;</code>/<code>prefect deployment apply</code> --&gt; <code>prefect deploy</code></p> <p>Prefect will now automatically detect flows in your repo and provide a wizard \ud83e\uddd9 to guide you through setting required attributes for your deployments.</p> <p><code>Deployment.build_from_flow</code> --&gt; <code>flow.deploy</code></p> </li> <li> <p>Configuring remote flow code storage:</p> <p>storage blocks --&gt; pull action</p> <p>When using the YAML-based deployment API, you can configure a pull action in your <code>prefect.yaml</code> file to specify how to retrieve flow code for your deployments. You can use configuration from your existing storage blocks to define your pull action via templating.</p> <p>When using the Python deployment API, you can pass any storage block to the <code>flow.deploy</code> method to specify how to retrieve flow code for your deployment.</p> </li> <li> <p>Configuring flow run infrastructure:</p> <p>infrastructure blocks --&gt; typed work pool</p> <p>Default infrastructure config is now set on the typed work pool, and can be overwritten by individual deployments.</p> </li> <li> <p>Managing multiple deployments:</p> <p>Create and/or update many deployments at once through a <code>prefect.yaml</code> file or use the <code>deploy</code> function.</p> </li> </ol>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#whats-similar","title":"What's similar","text":"<ul> <li>Storage blocks can be set as the pull action in a <code>prefect.yaml</code> file.</li> <li>Infrastructure blocks have configuration fields similar to typed work pools.</li> <li> <p>Deployment-level infrastructure overrides operate in much the same way.</p> <p><code>infra_override</code> -&gt; <code>job_variable</code></p> </li> <li> <p>The process for starting an agent and starting a worker in your environment are virtually identical.</p> <p><code>prefect agent start --pool &lt;work pool name&gt;</code> --&gt; <code>prefect worker start --pool &lt;work pool name&gt;</code></p> <p>Worker Helm chart</p> <p>If you host your agents in a Kubernetes cluster, you can use the Prefect worker Helm chart to host workers in your cluster.</p> </li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#upgrade-guide","title":"Upgrade guide","text":"<p>If you have existing deployments that use infrastructure blocks, you can quickly upgrade them to be compatible with workers by following these steps:</p> <ol> <li>Create a work pool</li> </ol> <p>This new work pool will replace your infrastructure block.</p> <p>You can use the <code>.publish_as_work_pool</code> method on any infrastructure block to create a work pool with the same configuration.</p> <p>For example, if you have a <code>KubernetesJob</code> infrastructure block named 'my-k8s-job', you can create a work pool with the same configuration with this script:</p> <pre><code>from prefect.infrastructure import KubernetesJob\n\nKubernetesJob.load(\"my-k8s-job\").publish_as_work_pool()\n</code></pre> <pre><code>Running this script will create a work pool named 'my-k8s-job' with the same configuration as your infrastructure block.\n</code></pre> <p>Serving flows</p> <p>If you are using a <code>Process</code> infrastructure block and a <code>LocalFilesystem</code> storage block (or aren't using an infrastructure and storage block at all), you can use <code>flow.serve</code> to create a deployment without needing to specify a work pool name or start a worker.</p> <p>This is a quick way to create a deployment for a flow and is a great way to manage your deployments if you don't need the dynamic infrastructure creation or configuration offered by workers.</p> <p>Check out our Docker guide for how to build a served flow into a Docker image and host it in your environment.</p> <ol> <li>Start a worker</li> </ol> <p>This worker will replace your agent and poll your new work pool for flow runs to execute.</p> <pre><code>prefect worker start -p &lt;work pool name&gt;\n</code></pre> <ol> <li>Deploy your flows to the new work pool</li> </ol> <p>To deploy your flows to the new work pool, you can use <code>flow.deploy</code> for a Pythonic deployment experience or <code>prefect deploy</code> for a YAML-based deployment experience.</p> <p>If you currently use <code>Deployment.build_from_flow</code>, we recommend using <code>flow.deploy</code>.</p> <p>If you currently use <code>prefect deployment build</code> and <code>prefect deployment apply</code>, we recommend using <code>prefect deploy</code>.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#flowdeploy","title":"<code>flow.deploy</code>","text":"<p>If you have a Python script that uses <code>Deployment.build_from_flow</code>, you can replace it with <code>flow.deploy</code>.</p> <p>Most arguments to <code>Deployment.build_from_flow</code> can be translated directly to <code>flow.deploy</code>, but here are some changes that you may need to make:</p> <ul> <li>Replace <code>infrastructure</code> with <code>work_pool_name</code>.</li> <li>If you've used the <code>.publish_as_work_pool</code> method on your infrastructure block, use the name of the created work pool.</li> <li>Replace <code>infra_overrides</code> with <code>job_variables</code>.</li> <li>Replace <code>storage</code> with a call to <code>flow.from_source</code>.</li> <li><code>flow.from_source</code> will load your flow from a remote storage location and make it deployable. Your existing storage block can be passed to the <code>source</code> argument of <code>flow.from_source</code>.</li> </ul> <p>Below are some examples of how to translate <code>Deployment.build_from_flow</code> to <code>flow.deploy</code>.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-without-any-blocks","title":"Deploying without any blocks","text":"<p>If you aren't using any blocks:</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Python script!\")\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>You can replace <code>Deployment.build_from_flow</code> with <code>flow.serve</code> :</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Python script!\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>This will start a process that will serve your flow and execute any flow runs that are scheduled to start.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-using-a-storage-block","title":"Deploying using a storage block","text":"<p>If you currently use a storage block to load your flow code but no infrastructure block:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a GitHub repo!\")\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        storage=GitHub.load(\"demo-repo\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>you can use <code>flow.from_source</code> to load your flow from the same location and <code>flow.serve</code> to create a deployment:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\"\n    ).serve(\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>This will allow you to execute scheduled flow runs without starting a worker. Additionally, the process serving your flow will regularly check for updates to your flow code and automatically update the flow if it detects any changes to the code.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-using-an-infrastructure-and-storage-block","title":"Deploying using an infrastructure and storage block","text":"<p>For the code below, we'll need to create a work pool from our infrastructure block and pass it to <code>flow.deploy</code> as the <code>work_pool_name</code> argument. We'll also need to pass our storage block to <code>flow.from_source</code> as the <code>source</code> argument.</p> <pre><code>from prefect import flow\nfrom prefect.deployments import Deployment\nfrom prefect.filesystems import GitHub\nfrom prefect.infrastructure.kubernetes import KubernetesJob\n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a GitHub repo!\")\n\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        storage=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\",\n        infrastructure=KubernetesJob.load(\"my-k8s-job\"),\n        infra_overrides=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>The equivalent deployment code using <code>flow.deploy</code> would look like this:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\"\n    ).deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"my-k8s-job\",\n        job_variables=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>Note that when using <code>flow.from_source(...).deploy(...)</code>, the flow you're deploying does not need to be available locally before running your script.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-via-a-docker-image","title":"Deploying via a Docker image","text":"<p>If you currently bake your flow code into a Docker image before deploying, you can use the <code>image</code> argument of <code>flow.deploy</code> to build a Docker image as part of your deployment process:</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Docker image!\")\n\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"my-deployment\",\n        image=\"my-repo/my-image:latest\",\n        work_pool_name=\"my-k8s-job\",\n        job_variables=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>You can skip a <code>flow.from_source</code> call when building an image with <code>flow.deploy</code>. Prefect will keep track of the flow's source code location in the image and load it from that location when the flow is executed.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#using-prefect-deploy","title":"Using <code>prefect deploy</code>","text":"<p>Always run <code>prefect deploy</code> commands from the root level of your repo!</p> <p>With agents, you might have had multiple <code>deployment.yaml</code> files, but under worker deployment patterns, each repo will have a single <code>prefect.yaml</code> file located at the root of the repo that contains deployment configuration for all flows in that repo.</p> <p>To set up a new <code>prefect.yaml</code> file for your deployments, run the following command from the root level of your repo:</p> <pre><code>prefect deploy\n</code></pre> <p>This will start a wizard that will guide you through setting up your deployment.</p> <p>For step 4, select <code>y</code> on the last prompt to save the configuration for the deployment.</p> <p>Saving the configuration for your deployment will result in a <code>prefect.yaml</code> file populated with your first deployment. You can use this YAML file to edit and define multiple deployments for this repo.</p> <p>You can add more deployments to the <code>deployments</code> list in your <code>prefect.yaml</code> file and/or by continuing to use the deployment creation wizard.</p> <p>For more information on deployments, check out our in-depth guide for deploying flows to work pools.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/using-the-client/","title":"Using the Prefect Orchestration Client","text":"","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#overview","title":"Overview","text":"<p>In the API reference for the <code>PrefectClient</code>, you can find many useful client methods that make it simpler to do things such as:</p> <ul> <li>reschedule late flow runs</li> <li>get the last <code>N</code> completed flow runs from my workspace</li> </ul> <p>The <code>PrefectClient</code> is an async context manager, so you can use it like this:</p> <pre><code>from prefect import get_client\n\nasync with get_client() as client:\n    response = await client.hello()\n    print(response.json()) # \ud83d\udc4b\n</code></pre>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#examples","title":"Examples","text":"","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#rescheduling-late-flow-runs","title":"Rescheduling late flow runs","text":"<p>Sometimes, you may need to bulk reschedule flow runs that are late - for example, if you've accidentally scheduled many flow runs of a deployment to an inactive work pool.</p> <p>To do this, we can delete late flow runs and create new ones in a <code>Scheduled</code> state with a delay.</p> <p>This example reschedules the last 3 late flow runs of a deployment named <code>healthcheck-storage-test</code> to run 6 hours later than their original expected start time. It also deletes any remaining late flow runs of that deployment.</p> <pre><code>import asyncio\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Optional\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import (\n    DeploymentFilter, FlowRunFilter\n)\nfrom prefect.client.schemas.objects import FlowRun\nfrom prefect.client.schemas.sorting import FlowRunSort\nfrom prefect.states import Scheduled\n\nasync def reschedule_late_flow_runs(\n    deployment_name: str,\n    delay: timedelta,\n    most_recent_n: int,\n    delete_remaining: bool = True,\n    states: Optional[list[str]] = None\n) -&gt; list[FlowRun]:\n    if not states:\n        states = [\"Late\"]\n\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=dict(name=dict(any_=states)),\n                expected_start_time=dict(\n                    before_=datetime.now(timezone.utc)\n                ),\n            ),\n            deployment_filter=DeploymentFilter(\n                name={'like_': deployment_name}\n            ),\n            sort=FlowRunSort.START_TIME_DESC,\n            limit=most_recent_n if not delete_remaining else None\n        )\n\n        if not flow_runs:\n            print(f\"No flow runs found in states: {states!r}\")\n            return []\n\n        rescheduled_flow_runs = []\n        for i, run in enumerate(flow_runs):\n            await client.delete_flow_run(flow_run_id=run.id)\n            if i &lt; most_recent_n:\n                new_run = await client.create_flow_run_from_deployment(\n                    deployment_id=run.deployment_id,\n                    state=Scheduled(\n                        scheduled_time=run.expected_start_time + delay\n                    ),\n                )\n                rescheduled_flow_runs.append(new_run)\n\n        return rescheduled_flow_runs\n\nif __name__ == \"__main__\":\n    rescheduled_flow_runs = asyncio.run(\n        reschedule_late_flow_runs(\n            deployment_name=\"healthcheck-storage-test\",\n            delay=timedelta(hours=6),\n            most_recent_n=3,\n        )\n    )\n\n    print(f\"Rescheduled {len(rescheduled_flow_runs)} flow runs\")\n\n    assert all(\n        run.state.is_scheduled() for run in rescheduled_flow_runs\n    )\n    assert all(\n        run.expected_start_time &gt; datetime.now(timezone.utc)\n        for run in rescheduled_flow_runs\n    )\n</code></pre>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#get-the-last-n-completed-flow-runs-from-my-workspace","title":"Get the last <code>N</code> completed flow runs from my workspace","text":"<p>To get the last <code>N</code> completed flow runs from our workspace, we can make use of <code>read_flow_runs</code> and <code>prefect.client.schemas</code>.</p> <p>This example gets the last three completed flow runs from our workspace:</p> <pre><code>import asyncio\nfrom typing import Optional\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import FlowRunFilter\nfrom prefect.client.schemas.objects import FlowRun\nfrom prefect.client.schemas.sorting import FlowRunSort\n\nasync def get_most_recent_flow_runs(\n    n: int = 3,\n    states: Optional[list[str]] = None\n) -&gt; list[FlowRun]:\n    if not states:\n        states = [\"COMPLETED\"]\n\n    async with get_client() as client:\n        return await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state={'type': {'any_': states}}\n            ),\n            sort=FlowRunSort.END_TIME_DESC,\n            limit=n,\n        )\n\nif __name__ == \"__main__\":\n    last_3_flow_runs: list[FlowRun] = asyncio.run(\n        get_most_recent_flow_runs()\n    )\n    print(last_3_flow_runs)\n\n    assert all(\n        run.state.is_completed() for run in last_3_flow_runs\n    )\n    assert (\n        end_times := [run.end_time for run in last_3_flow_runs]\n    ) == sorted(end_times, reverse=True)\n</code></pre> <p>Instead of the last three from the whole workspace, you could also use the <code>DeploymentFilter</code> like the previous example to get the last three completed flow runs of a specific deployment.</p>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#transition-all-running-flows-to-cancelled-via-the-client","title":"Transition all running flows to cancelled via the Client","text":"<p>It can be cumbersome to cancel many flow runs through the UI.  You can use <code>get_client</code>to set multiple runs to a <code>Cancelled</code> state. The code below will cancel all flow runs that are in <code>Pending</code>, <code>Running</code>, <code>Scheduled</code>, or <code>Late</code> states when the script is run. <pre><code>import anyio\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import FlowRunFilter, FlowRunFilterState, FlowRunFilterStateName\nfrom prefect.client.schemas.objects import StateType\n\nasync def list_flow_runs_with_states(states: list[str]):\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    name=FlowRunFilterStateName(any_=states)\n                )\n            )\n        )\n    return flow_runs\n\n\nasync def cancel_flow_runs(flow_runs):\n    async with get_client() as client:\n        for idx, flow_run in enumerate(flow_runs):\n            print(f\"[{idx + 1}] Cancelling flow run '{flow_run.name}' with ID '{flow_run.id}'\")\n            state_updates = {}\n            state_updates.setdefault(\"name\", \"Cancelled\")\n            state_updates.setdefault(\"type\", StateType.CANCELLED)\n            state = flow_run.state.copy(update=state_updates)\n            await client.set_flow_run_state(flow_run.id, state, force=True)\n\n\nasync def bulk_cancel_flow_runs():\n    states = [\"Pending\", \"Running\", \"Scheduled\", \"Late\"]\n    flow_runs = await list_flow_runs_with_states(states)\n\n    while len(flow_runs) &gt; 0:\n        print(f\"Cancelling {len(flow_runs)} flow runs\\n\")\n        await cancel_flow_runs(flow_runs)\n        flow_runs = await list_flow_runs_with_states(states)\n    print(\"Done!\")\n\n\nif __name__ == \"__main__\":\n    anyio.run(bulk_cancel_flow_runs)\n</code></pre></p> <p>There are other ways to filter objects like flow runs</p> <p>See <code>the filters API reference</code> for more ways to filter flow runs and other objects in your Prefect ecosystem.</p>","tags":["client","API","filters","orchestration"]},{"location":"guides/variables/","title":"Variables","text":"<p>Variables enable you to store and reuse non-sensitive bits of data, such as configuration information. Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.</p> <p>Variables can be created or modified at any time, but are intended for values with infrequent writes and frequent reads. Variable values may be cached for quicker retrieval.</p> <p>While variable values are most commonly loaded during flow runtime, they can be loaded in other contexts, at any time, such that they can be used to pass configuration information to Prefect configuration files, such as deployment steps.</p> <p>Variables are not Encrypted</p> <p>Using variables to store sensitive information, such as credentials, is not recommended. Instead, use Secret blocks to store and access sensitive information.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#managing-variables","title":"Managing variables","text":"<p>You can create, read, edit and delete variables via the Prefect UI, API, and CLI. Names must adhere to traditional variable naming conventions:</p> <ul> <li>Have no more than 255 characters.</li> <li>Only contain lowercase alphanumeric characters ([a-z], [0-9]) or underscores (_). Spaces are not allowed.</li> <li>be unique.</li> </ul> <p>Values must:</p> <ul> <li>have less than or equal to 5000 characters.</li> </ul> <p>Optionally, you can add tags to the variable.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-prefect-ui","title":"Via the Prefect UI","text":"<p>You can see all the variables in your Prefect server instance or Prefect Cloud workspace on the Variables page of the Prefect UI. Both the name and value of all variables are visible to anyone with access to the server or workspace.</p> <p>To create a new variable, select the + button next to the header of the Variables page. Enter the name and value of the variable.</p> <p></p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-rest-api","title":"Via the REST API","text":"<p>Variables can be created and deleted via the REST API. You can also set and get variables via the API with either the variable name or ID. See the REST reference for more information.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-cli","title":"Via the CLI","text":"<p>You can list, inspect, and delete variables via the command line interface with the <code>prefect variable ls</code>, <code>prefect variable inspect &lt;name&gt;</code>, and <code>prefect variable delete &lt;name&gt;</code> commands, respectively.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#accessing-variables","title":"Accessing variables","text":"<p>In addition to the UI and API, variables can be referenced in code and in certain Prefect configuration files.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#in-python-code","title":"In Python code","text":"<p>You can access any variable via the Python SDK via the <code>Variable.get()</code> method. If you attempt to reference a variable that does not exist, the method will return <code>None</code>. You can create variables via the Python SDK with the <code>Variable.set()</code> method. Note that if a variable of the same name exists, you'll need to pass <code>overwrite=True</code>.</p> <pre><code>from prefect.variables import Variable\n\n# setting the variable\nvariable = Variable.set(name=\"the_answer\", value=\"42\")\n\n# getting from a synchronous context\nanswer = Variable.get('the_answer')\nprint(answer.value)\n# 42\n\n# getting from an asynchronous context\nanswer = await Variable.get('the_answer')\nprint(answer.value)\n# 42\n\n# getting without a default value\nanswer = Variable.get('not_the_answer')\nprint(answer.value)\n# None\n\n# getting with a default value\nanswer = Variable.get('not_the_answer', default='42')\nprint(answer.value)\n# 42\n\n# using `overwrite=True`\nanswer = Variable.get('the_answer')\nprint(answer.value)\n#42\nanswer = Variable.set(name=\"the_answer\", value=\"43\", overwrite=True)\nprint(answer.value)\n#43\n</code></pre>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#in-prefectyaml-deployment-steps","title":"In <code>prefect.yaml</code> deployment steps","text":"<p>In <code>.yaml</code> files, variables are denoted by quotes and double curly brackets, like so: <code>\"{{ prefect.variables.my_variable }}\"</code>. You can use variables to templatize deployment steps by referencing them in the <code>prefect.yaml</code> file used to create deployments. For example, you could pass a variable in to specify a branch for a git repo in a deployment <code>pull</code> step:</p> <pre><code>pull:\n- prefect.deployments.steps.git_clone:\n    repository: https://github.com/PrefectHQ/hello-projects.git\n    branch: \"{{ prefect.variables.deployment_branch }}\"\n</code></pre> <p>The <code>deployment_branch</code> variable will be evaluated at runtime for the deployed flow, allowing changes to be made to variables used in a pull action without updating a deployment directly.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/webhooks/","title":"Webhooks","text":"<p>Use webhooks in your Prefect Cloud workspace to receive, observe, and react to events from other systems in your ecosystem.  Each webhook exposes a unique URL endpoint to receive events from other systems and transforms them into Prefect events for use in automations.</p> <p>Webhooks are defined by two essential components: a unique URL and a template that translates incoming web requests to a Prefect event.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#configuring-webhooks","title":"Configuring webhooks","text":"","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-the-prefect-cloud-api","title":"Via the Prefect Cloud API","text":"<p>Webhooks are managed via the Webhooks API endpoints.  This is a Prefect Cloud-only feature. You authenticate API calls using the standard authentication methods you use with Prefect Cloud.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-prefect-cloud","title":"Via Prefect Cloud","text":"<p>Webhooks can be created and managed from the Prefect Cloud UI.</p> <p></p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-the-prefect-cli","title":"Via the Prefect CLI","text":"<p>Webhooks can be managed and interacted with via the <code>prefect cloud webhook</code> command group.</p> <pre><code>prefect cloud webhook --help\n</code></pre> <p>You can create your first webhook by invoking <code>create</code>:</p> <pre><code>prefect cloud webhook create your-webhook-name \\\n    --description \"Receives webhooks from your system\" \\\n    --template '{ \"event\": \"your.event.name\", \"resource\": { \"prefect.resource.id\": \"your.resource.id\" } }'\n</code></pre> <p>Note the template string, which is discussed in greater detail below</p> <p>You can retrieve details for a specific webhook by ID using <code>get</code>, or optionally query all webhooks in your workspace via <code>ls</code>:</p> <pre><code># get webhook by ID\nprefect cloud webhook get &lt;webhook-id&gt;\n\n# list all configured webhooks in your workspace\n\nprefect cloud webhook ls\n</code></pre> <p>If you need to disable an existing webhook without deleting it, use <code>toggle</code>:</p> <pre><code>prefect cloud webhook toggle &lt;webhook-id&gt;\nWebhook is now disabled\n\nprefect cloud webhook toggle &lt;webhook-id&gt;\nWebhook is now enabled\n</code></pre> <p>If you are concerned that your webhook endpoint may have been compromised, use <code>rotate</code> to generate a new, random endpoint</p> <pre><code>prefect cloud webhook rotate &lt;webhook-url-slug&gt;\n</code></pre>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#webhook-endpoints","title":"Webhook endpoints","text":"<p>The webhook endpoints have randomly generated opaque URLs that do not divulge any information about your Prefect Cloud workspace.  They are rooted at <code>https://api.prefect.cloud/hooks/</code>. For example: <code>https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ</code>. Prefect Cloud assigns this URL when you create a webhook; it cannot be set via the API. You may rotate your webhook URL at any time without losing the associated configuration.</p> <p>All webhooks may accept requests via the most common HTTP methods:</p> <ul> <li><code>GET</code>, <code>HEAD</code>, and <code>DELETE</code> may be used for webhooks that define a static event   template, or a template that does not depend on the body of the HTTP request.  The   headers of the request will be available for templates.</li> <li><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> may be used when the webhook request will include a body.   See How HTTP request components are   handled for more details on how the body is   parsed.</li> </ul> <p>Prefect Cloud webhooks are deliberately quiet to the outside world, and will only return a <code>204 No Content</code> response when they are successful, and a <code>400 Bad Request</code> error when there is any error interpreting the request.  For more visibility when your webhooks fail, see the Troubleshooting section below.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#webhook-templates","title":"Webhook templates","text":"<p>The purpose of a webhook is to accept an HTTP request from another system and produce a Prefect event from it.  You may find that you often have little influence or control over the format of those requests, so Prefect's webhook system gives you full control over how you turn those notifications from other systems into meaningful events in your Prefect Cloud workspace.  The template you define for each webhook will determine how individual components of the incoming HTTP request become the event name and resource labels of the resulting Prefect event.</p> <p>As with the templates available in Prefect Cloud Automation for defining notifications and other parameters, you will write templates in Jinja2.  All of the built-in Jinja2 blocks and filters are available, as well as the filters from the <code>jinja2-humanize-extensions</code> package.</p> <p>Your goal when defining your event template is to produce a valid JSON object that defines (at minimum) the <code>event</code> name and the <code>resource[\"prefect.resource.id\"]</code>, which are required of all events.  The simplest template is one in which these are statically defined.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#static-webhook-events","title":"Static webhook events","text":"<p>Let's see a static webhook template example.  Say you want to configure a webhook that will notify Prefect when your <code>recommendations</code> machine learning model has been updated, so you can then send a Slack notification to your team and run a few subsequent deployments.  Those models are produced on a daily schedule by another team that is using <code>cron</code> for scheduling. They aren't able to use Prefect for their flows (yet!), but they are happy to add a <code>curl</code> to the end of their daily script to notify you. Because this webhook will only be used for a single event from a single resource, your template can be entirely static:</p> <pre><code>{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.recommendations\",\n        \"prefect.resource.name\": \"Recommendations [Products]\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>Make sure to produce valid JSON</p> <p>The output of your template, when rendered, should be a valid string that can be parsed, for example, with <code>json.loads</code>.</p> <p>A webhook with this template may be invoked via any of the HTTP methods, including a <code>GET</code> request with no body, so the team you are integrating with can include this line at the end of their daily script:</p> <pre><code>curl https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ\n</code></pre> <p>Each time the script hits the webhook, the webhook will produce a single Prefect event with that name and resource in your workspace.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#event-fields-that-prefect-cloud-populates-for-you","title":"Event fields that Prefect Cloud populates for you","text":"<p>You may notice that you only had to provide the <code>event</code> and <code>resource</code> definition, which is not a completely fleshed out event.  Prefect Cloud will set default values for any missing fields, such as <code>occurred</code> and <code>id</code>, so you don't need to set them in your template.  Additionally, Prefect Cloud will add the webhook itself as a related resource on all of the events it produces.</p> <p>If your template does not produce a <code>payload</code> field, the <code>payload</code> will default to a standard set of debugging information, including the HTTP method, headers, and body.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#dynamic-webhook-events","title":"Dynamic webhook events","text":"<p>Now let's say that after a few days you and the Data Science team are getting a lot of value from the automations you have set up with the static webhook.  You've agreed to upgrade this webhook to handle all of the various models that the team produces.  It's time to add some dynamic information to your webhook template.</p> <p>Your colleagues on the team have adjusted their daily <code>cron</code> scripts to <code>POST</code> a small body that includes the ID and name of the model that was updated:</p> <pre><code>curl \\\n    -d \"model=recommendations\" \\\n    -d \"friendly_name=Recommendations%20[Products]\" \\\n    -X POST https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ\n</code></pre> <p>This script will send a <code>POST</code> request and the body will include a traditional URL-encoded form with two fields describing the model that was updated: <code>model</code> and <code>friendly_name</code>. Here's the webhook code that uses Jinja to receive these values in your template and produce different events for the different models:</p> <pre><code>{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.{{ body.model }}\",\n        \"prefect.resource.name\": \"{{ body.friendly_name }}\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>All subsequent <code>POST</code> requests will produce events with those variable resource IDs and names.  The other statically-defined parts, such as <code>event</code> or the <code>producing-team</code> label you included earlier will still be used.</p> <p>Use Jinja2's <code>default</code> filter to handle missing values</p> <p>Jinja2 has a helpful <code>default</code> filter that can compensate for missing values in the request.  In this example, you may want to use the model's ID in place of the friendly name when the friendly name is not provided: <code>{{ body.friendly_name|default(body.model) }}</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#how-http-request-components-are-handled","title":"How HTTP request components are handled","text":"<p>The Jinja2 template context includes the three parts of the incoming HTTP request:</p> <ul> <li><code>method</code> is the uppercased string of the HTTP method, like <code>GET</code> or <code>POST</code>.</li> <li><code>headers</code> is a case-insensitive dictionary of the HTTP headers included with the   request.  To prevent accidental disclosures, the <code>Authorization</code> header is removed.</li> <li><code>body</code> represents the body that was posted to the webhook, with a best-effort approach   to parse it into an object you can access.</li> </ul> <p>HTTP headers are available without any alteration as a <code>dict</code>-like object, but you may access them with header names in any case.  For example, these template expressions all return the value of the <code>Content-Length</code> header:</p> <pre><code>{{ headers['Content-Length'] }}\n\n{{ headers['content-length'] }}\n\n{{ headers['CoNtEnt-LeNgTh'] }}\n</code></pre> <p>The HTTP request body goes through some light preprocessing to make it more useful in templates.  If the <code>Content-Type</code> of the request is <code>application/json</code>, the body will be parsed as a JSON object and made available to the webhook templates.  If the <code>Content-Type</code> is <code>application/x-www-form-urlencoded</code> (as in our example above), the body is parsed into a flat <code>dict</code>-like object of key-value pairs.  Jinja2 supports both index and attribute access to the fields of these objects, so the following two expressions are equivalent:</p> <pre><code>{{ body['friendly_name'] }}\n\n{{ body.friendly_name }}\n</code></pre> <p>Only for Python identifiers</p> <p>Jinja2's syntax only allows attribute-like access if the key is a valid Python identifier, so <code>body.friendly-name</code> will not work.  Use <code>body['friendly-name']</code> in those cases.</p> <p>You may not have much control over the client invoking your webhook, but would still like for bodies that look like JSON to be parsed as such.  Prefect Cloud will attempt to parse any other content type (like <code>text/plain</code>) as if it were JSON first.  In any case where the body cannot be transformed into JSON, it will be made available to your templates as a Python <code>str</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#accepting-prefect-events-directly","title":"Accepting Prefect events directly","text":"<p>In cases where you have more control over the client, your webhook can accept Prefect events directly with a simple pass-through template:</p> <pre><code>{{ body|tojson }}\n</code></pre> <p>This template accepts the incoming body (assuming it was in JSON format) and just passes it through unmodified.  This allows a <code>POST</code> of a partial Prefect event as in this example:</p> <pre><code>POST /hooks/AERylZ_uewzpDx-8fcweHQ HTTP/1.1\nHost: api.prefect.cloud\nContent-Type: application/json\nContent-Length: 228\n\n{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.recommendations\",\n        \"prefect.resource.name\": \"Recommendations [Products]\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>The resulting event will be filled out with the default values for <code>occurred</code>, <code>id</code>, and other fields as described above.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#accepting-cloudevents","title":"Accepting CloudEvents","text":"<p>The Cloud Native Computing Foundation has standardized CloudEvents for use by systems to exchange event information in a common format.  These events are supported by major cloud providers and a growing number of cloud-native systems.  Prefect Cloud can interpret a webhook containing a CloudEvent natively with the following template:</p> <pre><code>{{ body|from_cloud_event(headers) }}\n</code></pre> <p>The resulting event will use the CloudEvent's <code>subject</code> as the resource (or the <code>source</code> if no <code>subject</code> is available).  The CloudEvent's <code>data</code> attribute will become the Prefect event's <code>payload['data']</code>, and the other CloudEvent metadata will be at <code>payload['cloudevents']</code>.  If you would like to handle CloudEvents in a more specific way tailored to your use case, use a dynamic template to interpret the incoming <code>body</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#troubleshooting","title":"Troubleshooting","text":"<p>The initial configuration of your webhook may require some trial and error as you get the sender and your receiving webhook speaking a compatible language.  While you are in this phase, you may find the Event Feed in the UI to be indispensable for seeing the events as they are happening.</p> <p>When Prefect Cloud encounters an error during receipt of a webhook, it will produce a <code>prefect-cloud.webhook.failed</code> event in your workspace.  This event will include critical information about the HTTP method, headers, and body it received, as well as what the template rendered.  Keep an eye out for these events when something goes wrong.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/deployment/aci/","title":"Run an Agent with Azure Container Instances","text":"<p>Microsoft Azure Container Instances (ACI) provides a convenient and simple service for quickly spinning up a Docker container that can host a Prefect Agent and execute flow runs.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#prerequisites","title":"Prerequisites","text":"<p>To follow this quickstart, you'll need the following:</p> <ul> <li>A Prefect Cloud account</li> <li>A Prefect Cloud API key (Prefect Cloud Pro and Custom tier accounts can use a service account API key)</li> <li>A Microsoft Azure account</li> <li>Azure CLI installed and authenticated</li> </ul>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-a-resource-group","title":"Create a resource group","text":"<p>Like most Azure resources, ACI applications must live in a resource group. If you don\u2019t already have a resource group you\u2019d like to use, create a new one by running the <code>az group create</code> command. For example, this example creates a resource group called <code>prefect-agents</code> in the <code>eastus</code> region:</p> <pre><code>az group create --name prefect-agents --location eastus\n</code></pre> <p>Feel free to change the group name or location to match your use case. You can also run <code>az account list-locations -o table</code> to see all available resource group locations for your account.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-the-container-instance","title":"Create the container instance","text":"<p>Prefect provides pre-configured Docker images you can use to quickly stand up a container instance. These Docker images include Python and Prefect. For example, the image <code>prefecthq/prefect:2-python3.10</code> includes the latest release version of Prefect and Python 3.10.</p> <p>To create the container instance, use the <code>az container create</code> command. This example shows the syntax, but you'll need to provide the correct values for <code>[ACCOUNT-ID]</code>,<code>[WORKSPACE-ID]</code>, <code>[API-KEY]</code>, and any dependencies you need to <code>pip install</code> on the instance. These options are discussed below.</p> <pre><code>az container create \\\n--resource-group prefect-agents \\\n--name prefect-agent-example \\\n--image prefecthq/prefect:2-python3.10 \\\n--secure-environment-variables PREFECT_API_URL='https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]' PREFECT_API_KEY='[API-KEY]' \\\n--command-line \"/bin/bash -c 'pip install adlfs s3fs requests pandas; prefect agent start -p default-agent-pool -q test'\"\n</code></pre> <p>When the container instance is running, go to Prefect Cloud and select the Work Pools page. Select default-agent-pool, then select the Queues tab to see work queues configured on this work pool. When the container instance is running and the agent has started, the <code>test</code> work queue displays \"Healthy\" status. This work queue and agent are ready to execute deployments configured to run on the <code>test</code> queue.</p> <p></p> <p>Agents and queues</p> <p>The agent running in this container instance can now pick up and execute flow runs for any deployment configured to use the <code>test</code> queue on the <code>default-agent-pool</code> work pool.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#container-create-options","title":"Container create options","text":"<p>Let's break down the details of the <code>az container create</code> command used here.</p> <p>The <code>az container create command</code> creates a new ACI container.</p> <p><code>--resource-group prefect-agents</code> tells Azure which resource group the new container is created in. Here, the examples uses the <code>prefect-agents</code> resource group created earlier.</p> <p><code>--name prefect-agent-example</code> determines the container name you will see in the Azure Portal. You can set any name you\u2019d like here to suit your use case, but container instance names must be unique in your resource group.</p> <p><code>--image prefecthq/prefect:2-python3.10</code> tells ACI which Docker images to run. The script above pulls a public Prefect image from Docker Hub. You can also build custom images and push them to a public container registry so ACI can access them. Or you can push your image to a private Azure Container Registry and use it to create a container instance.</p> <p><code>--secure-environment-variables</code> sets environment variables that are only visible from inside the container. They do not show up when viewing the container\u2019s metadata. You'll populate these environment variables with a few pieces of information to configure the execution environment of the container instance so it can communicate with your Prefect Cloud workspace:</p> <ul> <li>A Prefect Cloud [<code>PREFECT_API_KEY</code>]/concepts/settings/#prefect_api_key) value specifying the API key used to authenticate with your Prefect Cloud workspace. (Pro and Custom tier accounts can use a service account API key.)</li> <li>The <code>PREFECT_API_URL</code> value specifying the API endpoint of your Prefect Cloud workspace.</li> </ul> <p><code>--command-line</code> lets you override the container\u2019s normal entry point and run a command instead. The script above uses this section to install the <code>adlfs</code> pip package so it can read flow code from Azure Blob Storage, along with <code>s3fs</code>, <code>pandas</code>, and <code>requests</code>. It then runs the Prefect agent, in this case using the default work pool and a <code>test</code> work queue. If you want to use a different work pool or queue, make sure to change these values appropriately.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-a-deployment","title":"Create a deployment","text":"<p>Following the example of the Flow deployments tutorial, let's create a deployment that can be executed by the agent on this container instance.</p> <p>In an environment where you have installed Prefect, create a new folder called <code>health_test</code>, and within it create a new file called <code>health_flow.py</code> containing the following code.</p> <pre><code>import prefect\nfrom prefect import task, flow\nfrom prefect import get_run_logger\n\n\n@task\ndef say_hi():\n    logger = get_run_logger()\n    logger.info(\"Hello from the Health Check Flow! \ud83d\udc4b\")\n\n\n@task\ndef log_platform_info():\n    import platform\n    import sys\n    from prefect.server.api.server import SERVER_API_VERSION\n\n    logger = get_run_logger()\n    logger.info(\"Host's network name = %s\", platform.node())\n    logger.info(\"Python version = %s\", platform.python_version())\n    logger.info(\"Platform information (instance type) = %s \", platform.platform())\n    logger.info(\"OS/Arch = %s/%s\", sys.platform, platform.machine())\n    logger.info(\"Prefect Version = %s \ud83d\ude80\", prefect.__version__)\n    logger.info(\"Prefect API Version = %s\", SERVER_API_VERSION)\n\n\n@flow(name=\"Health Check Flow\")\ndef health_check_flow():\n    hi = say_hi()\n    log_platform_info(wait_for=[hi])\n</code></pre> <p>Now create a deployment for this flow script, making sure that it's configured to use the <code>test</code> queue on the <code>default-agent-pool</code> work pool.</p> <pre><code>prefect deployment build --infra process --storage-block azure/flowsville/health_test --name health-test --pool default-agent-pool --work-queue test --apply health_flow.py:health_check_flow\n</code></pre> <p>Once created, any flow runs for this deployment will be picked up by the agent running on this container instance.</p> <p>Infrastructure and storage</p> <p>This Prefect deployment example was built using the <code>Process</code> infrastructure type and Azure Blob Storage.</p> <p>You might wonder why your deployment needs process infrastructure rather than <code>DockerContainer</code> infrastructure when you are deploying a Docker image to ACI.</p> <p>A Prefect deployment\u2019s infrastructure type describes how you want Prefect agents to run flows for the deployment. With <code>DockerContainer</code> infrastructure, the agent will try to use Docker to spin up a new container for each flow run. Since you\u2019ll be starting your own container on ACI, you don\u2019t need Prefect to do it for you. Specifying process infrastructure on the deployment tells Prefect you want to agent to run flows by starting a process in your ACI container.</p> <p>You can use any storage type as long as you've configured a block for it before creating the deployment.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#cleaning-up","title":"Cleaning up","text":"<p>Note that ACI instances may incur usage charges while running, but must be running for the agent to pick up and execute flow runs.</p> <p>To stop a container, use the <code>az container stop</code> command:</p> <pre><code>az container stop --resource-group prefect-agents --name prefect-agent-example\n</code></pre> <p>To delete a container, use the <code>az container delete</code> command:</p> <pre><code>az container delete --resource-group prefect-agents --name prefect-agent-example\n</code></pre>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/daemonize/","title":"Daemonize Processes for Prefect Deployments","text":"<p>When running workflow applications, it can be helpful to create long-running processes that run at startup and are robust to failure. In this guide you'll learn how to set up a systemd service to create long-running Prefect processes that poll for scheduled flow runs.</p> <p>A systemd service is ideal for running a long-lived process on a Linux VM or physical Linux server. We will leverage systemd and see how to automatically start a Prefect worker or long-lived <code>serve</code> process when Linux starts. This approach provides resilience by automatically restarting the process if it crashes.</p> <p>In this guide we will:</p> <ul> <li>Create a Linux user</li> <li>Install and configure Prefect</li> <li>Set up a systemd service for the Prefect worker or <code>.serve</code> process</li> </ul>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#prerequisites","title":"Prerequisites","text":"<ul> <li>An environment with a linux operating system with systemd and Python 3.8 or later.</li> <li>A superuser account (you can run <code>sudo</code> commands).</li> <li>A Prefect Cloud account, or a local instance of a Prefect server running on your network.</li> <li>If daemonizing a worker, you'll need a Prefect deployment with a work pool your worker can connect to.</li> </ul> <p>If using an AWS t2-micro EC2 instance with an AWS Linux image, you can install Python and pip with <code>sudo yum install -y python3 python3-pip</code>.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-1-add-a-user","title":"Step 1: Add a user","text":"<p>Create a user account on your linux system for the Prefect process. While you can run a worker or serve process as root, it's good security practice to avoid doing so unless you are sure you need to.</p> <p>In a terminal, run:</p> <pre><code>sudo useradd -m prefect\nsudo passwd prefect\n</code></pre> <p>When prompted, enter a password for the <code>prefect</code> account.</p> <p>Next, log in to the <code>prefect</code> account by running:</p> <pre><code>sudo su prefect\n</code></pre>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-2-install-prefect","title":"Step 2: Install Prefect","text":"<p>Run:</p> <pre><code>pip3 install prefect\n</code></pre> <p>This guide assumes you are installing Prefect globally, not in a virtual environment. If running a systemd service in a virtual environment, you'll just need to change the ExecPath. For example, if using venv, change the ExecPath to target the <code>prefect</code> application in the <code>bin</code> subdirectory of your virtual environment.</p> <p>Next, set up your environment so that the Prefect client will know which server to connect to.</p> <p>If connecting to Prefect Cloud, follow the instructions to obtain an API key and then run the following:</p> <pre><code>prefect cloud login -k YOUR_API_KEY\n</code></pre> <p>When prompted, choose the Prefect workspace you'd like to log in to.</p> <p>If connecting to a self-hosted Prefect server instance instead of Prefect Cloud, run the following and substitute the IP address of your server:</p> <pre><code>prefect config set PREFECT_API_URL=http://your-prefect-server-IP:4200\n</code></pre> <p>Finally, run the <code>exit</code> command to sign out of the <code>prefect</code> Linux account. This command switches you back to your sudo-enabled account so you will can run the commands in the next section.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-3-set-up-a-systemd-service","title":"Step 3: Set up a systemd service","text":"<p>See the section below if you are setting up a Prefect worker. Skip to the next section if you are setting up a Prefect <code>.serve</code> process.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#setting-up-a-systemd-service-for-a-prefect-worker","title":"Setting up a systemd service for a Prefect worker","text":"<p>Move into the <code>/etc/systemd/system</code> folder and open a file for editing. We use the Vim text editor below.</p> <pre><code>cd /etc/systemd/system\nsudo vim my-prefect-service.service\n</code></pre> my-prefect-service.service<pre><code>[Unit]\nDescription=Prefect worker\n\n[Service]\nUser=prefect\nWorkingDirectory=/home\nExecStart=prefect worker start --pool YOUR_WORK_POOL_NAME\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Make sure you substitute your own work pool name.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#setting-up-a-systemd-service-for-serve","title":"Setting up a systemd service for <code>.serve</code>","text":"<p>Copy your flow entrypoint Python file and any other files needed for your flow to run into the <code>/home</code> directory (or the directory of your choice).</p> <p>Here's a basic example flow:</p> my_file.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef say_hi():\n    print(\"Hello!\")\n\nif __name__==\"__main__\":\n    say_hi.serve(name=\"Greeting from daemonized .serve\")\n</code></pre> <p>If you want to make changes to your flow code without restarting your process, you can push your code to git-based cloud storage (GitHub, BitBucket, GitLab) and use <code>flow.from_source().serve()</code>, as in the example below.</p> my_remote_flow_code_file.py<pre><code>if __name__ == \"__main__\":\nflow.from_source(\n    source=\"https://github.com/org/repo.git\",\n    entrypoint=\"path/to/my_remote_flow_code_file.py:say_hi\",\n).serve(name=\"deployment-with-github-storage\")\n</code></pre> <p>Make sure you substitute your own flow code entrypoint path.</p> <p>Note that if you change the flow entrypoint parameters, you will need to restart the process.</p> <p>Move into the <code>/etc/systemd/system</code> folder and open a file for editing. We use the Vim text editor below.</p> <pre><code>cd /etc/systemd/system\nsudo vim my-prefect-service.service\n</code></pre> my-prefect-service.service<pre><code>[Unit]\nDescription=Prefect serve \n\n[Service]\nUser=prefect\nWorkingDirectory=/home\nExecStart=python3 my_file.py\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n</code></pre>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#save-enable-and-start-the-service","title":"Save, enable, and start the service","text":"<p>To save the file and exit Vim hit the escape key, type <code>:wq!</code>, then press the return key.</p> <p>Next, run <code>sudo systemctl daemon-reload</code> to make systemd aware of your new service.</p> <p>Then, run <code>sudo systemctl enable my-prefect-service</code> to enable the service. This command will ensure it runs when your system boots.</p> <p>Next, run <code>sudo systemctl start my-prefect-service</code> to start the service.</p> <p>Run your deployment from UI and check out the logs on the Flow Runs page.</p> <p>You can see if your daemonized Prefect worker or serve process is running and see the Prefect logs with <code>systemctl status my-prefect-service</code>.</p> <p>That's it! You now have a systemd service that starts when your system boots, and will restart if it ever crashes.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#next-steps","title":"Next steps","text":"<p>If you want to set up a long-lived process on a Windows machine the pattern is similar. Instead of systemd, you can use NSSM.</p> <p>Check out other Prefect guides to see what else you can do with Prefect!</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/","title":"Developing a New Worker Type","text":"<p>Advanced Topic</p> <p>This tutorial is for users who want to extend the Prefect framework and completing this successfully will require deep knowledge of Prefect concepts. For standard use cases, we recommend using one of the available workers instead.</p> <p>Prefect workers are responsible for setting up execution infrastructure and starting flow runs on that infrastructure.</p> <p>A list of available workers can be found here. What if you want to execute your flow runs on infrastructure that doesn't have an available worker type? This tutorial will walk you through creating a custom worker that can run your flows on your chosen infrastructure.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-configuration","title":"Worker configuration","text":"<p>When setting up an execution environment for a flow run, a worker receives configuration for the infrastructure it is designed to work with. Examples of configuration values include memory allocation, CPU allocation, credentials, image name, etc. The worker then uses this configuration to create the execution environment and start the flow run.</p> <p>How are the configuration values populated?</p> <p>The work pool that a worker polls for flow runs has a base job template associated with it. The template is the contract for how configuration values populate for each flow run.</p> <p>The keys in the <code>job_configuration</code> section of this base job template match the worker's configuration class attributes. The values in the <code>job_configuration</code> section of the base job template are used to populate the attributes of the worker's configuration class.</p> <p>The work pool creator gets to decide how they want to populate the values in the <code>job_configuration</code> section of the base job template. The values can be hard-coded, templated using placeholders, or a mix of these two approaches. Because you, as the worker developer, don't know how the work pool creator will populate the values, you should set sensible defaults for your configuration class attributes as a matter of best practice.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#implementing-a-basejobconfiguration-subclass","title":"Implementing a <code>BaseJobConfiguration</code> subclass","text":"<p>A worker developer defines their worker's configuration to function with a class extending <code>BaseJobConfiguration</code>.</p> <p><code>BaseJobConfiguration</code> has attributes that are common to all workers:</p> Attribute Description <code>name</code> The name to assign to the created execution environment. <code>env</code> Environment variables to set in the created execution environment. <code>labels</code> The labels assigned to the created execution environment for metadata purposes. <code>command</code> The command to use when starting a flow run. <p>Prefect sets values for each attribute before giving the configuration to the worker. If you want to customize the values of these attributes, use the <code>prepare_for_flow_run</code> method.</p> <p>Here's an example <code>prepare_for_flow_run</code> method that adds a label to the execution environment:</p> <pre><code>def prepare_for_flow_run(\n    self, flow_run, deployment = None, flow = None,\n):  \n    super().prepare_for_flow_run(flow_run, deployment, flow)  \n    self.labels.append(\"my-custom-label\")\n</code></pre> <p>A worker configuration class is a Pydantic model, so you can add additional attributes to your configuration class as Pydantic fields. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseJobConfiguration\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n</code></pre> <p>This configuration class will populate the <code>job_configuration</code> section of the resulting base job template.</p> <p>For this example, the base job template would look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory }}\"\n    cpu: \"{{ cpu }}\"\nvariables:\n    type: object\n    properties:\n        name:\n          title: Name\n          description: Name given to infrastructure created by a worker.\n          type: string\n        env:\n          title: Environment Variables\n          description: Environment variables to set when starting a flow run.\n          type: object\n          additionalProperties:\n            type: string\n        labels:\n          title: Labels\n          description: Labels applied to infrastructure created by a worker.\n          type: object\n          additionalProperties:\n            type: string\n        command:\n          title: Command\n          description: The command to use when starting a flow run. In most cases,\n            this should be left blank and the command will be automatically generated\n            by the worker.\n          type: string\n        memory:\n            title: Memory\n            description: Memory allocation for the execution environment.\n            type: integer\n            default: 1024\n        cpu:\n            title: CPU\n            description: CPU allocation for the execution environment.\n            type: integer\n            default: 500\n</code></pre> <p>This base job template defines what values can be provided by deployment creators on a per-deployment basis and how those provided values will be translated into the configuration values that the worker will use to create the execution environment.</p> <p>Notice that each attribute for the class was added in the <code>job_configuration</code> section with placeholders whose name matches the attribute name. The <code>variables</code> section was also populated with the OpenAPI schema for each attribute. If a configuration class is used without explicitly declaring any template variables, the template variables will be inferred from the configuration class attributes.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#customizing-configuration-attribute-templates","title":"Customizing Configuration Attribute Templates","text":"<p>You can customize the template for each attribute for situations where the configuration values should use more sophisticated templating. For example, if you want to add units for the <code>memory</code> attribute, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseJobConfiguration\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: str = Field(\n            default=\"1024Mi\",\n            description=\"Memory allocation for the execution environment.\"\n            template=\"{{ memory_request }}Mi\"\n        )\n    cpu: str = Field(\n            default=\"500m\", \n            description=\"CPU allocation for the execution environment.\"\n            template=\"{{ cpu_request }}m\"\n        )\n</code></pre> <p>Notice that we changed the type of each attribute to <code>str</code> to accommodate the units, and we added a new <code>template</code> attribute to each attribute. The <code>template</code> attribute is used to populate the <code>job_configuration</code> section of the resulting base job template.</p> <p>For this example, the <code>job_configuration</code> section of the resulting base job template would look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory_request }}Mi\"\n    cpu: \"{{ cpu_request }}m\"\n</code></pre> <p>Note that to use custom templates, you will need to declare the template variables used in the template because the names of those variables can no longer be inferred from the configuration class attributes. We will cover how to declare the default variable schema in the Worker Template Variables section.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#rules-for-template-variable-interpolation","title":"Rules for template variable interpolation","text":"<p>When defining a job configuration model, it's useful to understand how template variables are interpolated into the job configuration. The templating engine follows a few simple rules:</p> <ol> <li>If a template variable is the only value for a key in the <code>job_configuration</code> section, the key will be replaced with the value template variable.</li> <li>If a template variable is part of a string (i.e., there is text before or after the template variable), the value of the template variable will be interpolated into the string.</li> <li>If a template variable is the only value for a key in the <code>job_configuration</code> section and no value is provided for the template variable, the key will be removed from the <code>job_configuration</code> section.</li> </ol> <p>These rules allow worker developers and work pool maintainers to define template variables that can be complex types like dictionaries and lists. These rules also mean that worker developers should give reasonable default values to job configuration fields whenever possible because values are not guaranteed to be provided if template variables are unset.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#template-variable-usage-strategies","title":"Template variable usage strategies","text":"<p>Template variables define the interface that deployment creators interact with to configure the execution environments of their deployments. The complexity of this interface can be controlled via the template variables that are defined for a base job template. This control allows work pool maintainers to find a point along the spectrum of flexibility and simplicity appropriate for their organization.</p> <p>There are two patterns that are represented in current worker implementations:</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#pass-through","title":"Pass-through","text":"<p>In the pass-through pattern, template variables are passed through to the job configuration with little change. This pattern exposes complete control to deployment creators but also requires them to understand the details of the execution environment.</p> <p>This pattern is useful when the execution environment is simple, and the deployment creators are expected to have high technical knowledge.</p> <p>The Docker worker is an example of a worker that uses this pattern.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#infrastructure-as-code-templating","title":"Infrastructure as code templating","text":"<p>Depending on the infrastructure they interact with, workers can sometimes employ a declarative infrastructure syntax (i.e., infrastructure as code) to create execution environments (e.g., a Kubernetes manifest or an ECS task definition).</p> <p>In the IaC pattern, it's often useful to use template variables to template portions of the declarative syntax which then can be used to generate the declarative syntax into a final form.</p> <p>This approach allows work pool creators to provide a simpler interface to deployment creators while also controlling which portions of infrastructure are configurable by deployment creators.</p> <p>The Kubernetes worker is an example of a worker that uses this pattern.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#configuring-credentials","title":"Configuring credentials","text":"<p>When executing flow runs within cloud services, workers will often need credentials to authenticate with those services. For example, a worker that executes flow runs in AWS Fargate will need AWS credentials. As a worker developer, you can use blocks to accept credentials configuration from the user.</p> <p>For example, if you want to allow the user to configure AWS credentials, you can do so like this:</p> <pre><code>from prefect_aws import AwsCredentials\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    aws_credentials: AwsCredentials = Field(\n        default=None,\n        description=\"AWS credentials to use when creating AWS resources.\"\n    )\n</code></pre> <p>Users can create and assign a block to the <code>aws_credentials</code> attribute in the UI and the worker will use these credentials when interacting with AWS resources.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-template-variables","title":"Worker template variables","text":"<p>Providing template variables for a base job template defines the fields that deployment creators can override per deployment. The work pool creator ultimately defines the template variables for a base job template, but the worker developer is able to define default template variables for the worker to make it easier to use.</p> <p>Default template variables for a worker are defined by implementing the <code>BaseVariables</code> class. Like the <code>BaseJobConfiguration</code> class, the <code>BaseVariables</code> class has attributes that are common to all workers:</p> Attribute Description <code>name</code> The name to assign to the created execution environment. <code>env</code> Environment variables to set in the created execution environment. <code>labels</code> The labels assigned the created execution environment for metadata purposes. <code>command</code> The command to use when starting a flow run. <p>Additional attributes can be added to the <code>BaseVariables</code> class to define additional template variables. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseVariables\n\nclass MyWorkerTemplateVariables(BaseVariables):\n    memory_request: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu_request: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n</code></pre> <p>When <code>MyWorkerTemplateVariables</code> is used in conjunction with <code>MyWorkerConfiguration</code> from the Customizing Configuration Attribute Templates section, the resulting base job template will look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory_request }}Mi\"\n    cpu: \"{{ cpu_request }}m\"\nvariables:\n    type: object\n    properties:\n        name:\n          title: Name\n          description: Name given to infrastructure created by a worker.\n          type: string\n        env:\n          title: Environment Variables\n          description: Environment variables to set when starting a flow run.\n          type: object\n          additionalProperties:\n            type: string\n        labels:\n          title: Labels\n          description: Labels applied to infrastructure created by a worker.\n          type: object\n          additionalProperties:\n            type: string\n        command:\n          title: Command\n          description: The command to use when starting a flow run. In most cases,\n            this should be left blank and the command will be automatically generated\n            by the worker.\n          type: string\n        memory_request:\n            title: Memory Request\n            description: Memory allocation for the execution environment.\n            type: integer\n            default: 1024\n        cpu_request:\n            title: CPU Request\n            description: CPU allocation for the execution environment.\n            type: integer\n            default: 500\n</code></pre> <p>Note that template variable classes are never used directly. Instead, they are used to generate a schema that is used to populate the <code>variables</code> section of a base job template and validate the template variables provided by the user.</p> <p>We don't recommend using template variable classes within your worker implementation for validation purposes because the work pool creator ultimately defines the template variables. The configuration class should handle any necessary run-time validation.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-implementation","title":"Worker implementation","text":"<p>Workers set up execution environments using provided configuration. Workers also observe the execution environment as the flow run executes and report any crashes to the Prefect API.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#attributes","title":"Attributes","text":"<p>To implement a worker, you must implement the <code>BaseWorker</code> class and provide it with the following attributes:</p> Attribute Description Required <code>type</code> The type of the worker. Yes <code>job_configuration</code> The configuration class for the worker. Yes <code>job_configuration_variables</code> The template variables class for the worker. No <code>_documentation_url</code> Link to documentation for the worker. No <code>_logo_url</code> Link to a logo for the worker. No <code>_description</code> A description of the worker. No","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#methods","title":"Methods","text":"","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#run","title":"<code>run</code>","text":"<p>In addition to the attributes above, you must also implement a <code>run</code> method. The <code>run</code> method is called for each flow run the worker receives for execution from the work pool.</p> <p>The <code>run</code> method has the following signature:</p> <pre><code> async def run(\n        self, flow_run: FlowRun, configuration: BaseJobConfiguration, task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        ...\n</code></pre> <p>The <code>run</code> method is passed: the flow run to execute, the execution environment configuration for the flow run, and a task status object that allows the worker to track whether the flow run was submitted successfully.</p> <p>The <code>run</code> method must also return a <code>BaseWorkerResult</code> object. The <code>BaseWorkerResult</code> object returned contains information about the flow run execution. For the most part, you can implement the <code>BaseWorkerResult</code> with no modifications like so:</p> <pre><code>from prefect.workers.base import BaseWorkerResult\n\nclass MyWorkerResult(BaseWorkerResult):\n    \"\"\"Result returned by the MyWorker.\"\"\"\n</code></pre> <p>If you would like to return more information about a flow run, then additional attributes can be added to the <code>BaseWorkerResult</code> class.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#kill_infrastructure","title":"<code>kill_infrastructure</code>","text":"<p>Workers must implement a <code>kill_infrastructure</code> method to support flow run cancellation. The <code>kill_infrastructure</code> method is called when a flow run is canceled and is passed an identifier for the infrastructure to tear down and the execution environment configuration for the flow run.</p> <p>The <code>infrastructure_pid</code> passed to the <code>kill_infrastructure</code> method is the same identifier used to mark a flow run execution as started in the <code>run</code> method. The <code>infrastructure_pid</code> must be a string, but it can take on any format you choose.</p> <p>The <code>infrastructure_pid</code> should contain enough information to uniquely identify the infrastructure created for a flow run when used with the <code>job_configuration</code> passed to the <code>kill_infrastructure</code> method. Examples of useful information include: the cluster name, the hostname, the process ID, the container ID, etc.</p> <p>If a worker cannot tear down infrastructure created for a flow run, the <code>kill_infrastructure</code> command should raise an <code>InfrastructureNotFound</code> or <code>InfrastructureNotAvailable</code> exception.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-implementation-example","title":"Worker implementation example","text":"<p>Below is an example of a worker implementation. This example is not intended to be a complete implementation but to illustrate the aforementioned concepts.</p> <pre><code>from prefect.workers.base import BaseWorker, BaseWorkerResult, BaseJobConfiguration, BaseVariables\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: str = Field(\n            default=\"1024Mi\",\n            description=\"Memory allocation for the execution environment.\"\n            template=\"{{ memory_request }}Mi\"\n        )\n    cpu: str = Field(\n            default=\"500m\", \n            description=\"CPU allocation for the execution environment.\"\n            template=\"{{ cpu_request }}m\"\n        )\n\nclass MyWorkerTemplateVariables(BaseVariables):\n    memory_request: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu_request: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n\nclass MyWorkerResult(BaseWorkerResult):\n    \"\"\"Result returned by the MyWorker.\"\"\"\n\nclass MyWorker(BaseWorker):\n    type = \"my-worker\"\n    job_configuration = MyWorkerConfiguration\n    job_configuration_variables = MyWorkerTemplateVariables\n    _documentation_url = \"https://example.com/docs\"\n    _logo_url = \"https://example.com/logo\"\n    _description = \"My worker description.\"\n\n    async def run(\n        self, flow_run: FlowRun, configuration: BaseJobConfiguration, task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        # Create the execution environment and start execution\n        job = await self._create_and_start_job(configuration)\n\n        if task_status:\n            # Use a unique ID to mark the run as started. This ID is later used to tear down infrastructure\n            # if the flow run is cancelled.\n            task_status.started(job.id) \n\n        # Monitor the execution\n        job_status = await self._watch_job(job, configuration)\n\n        exit_code = job_status.exit_code if job_status else -1 # Get result of execution for reporting\n        return MyWorkerResult(\n            status_code=exit_code,\n            identifier=job.id,\n        )\n\n    async def kill_infrastructure(self, infrastructure_pid: str, configuration: BaseJobConfiguration) -&gt; None:\n        # Tear down the execution environment\n        await self._kill_job(infrastructure_pid, configuration)\n</code></pre> <p>Most of the execution logic is omitted from the example above, but it shows that the typical order of operations in the <code>run</code> method is:     1. Create the execution environment and start the flow run execution     2. Mark the flow run as started via the passed <code>task_status</code> object     3. Monitor the execution     4. Get the execution's final status from the infrastructure and return a <code>BaseWorkerResult</code> object</p> <p>To see other examples of worker implementations, see the <code>ProcessWorker</code> and <code>KubernetesWorker</code> implementations.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#integrating-with-the-prefect-cli","title":"Integrating with the Prefect CLI","text":"<p>Workers can be started via the Prefect CLI by providing the <code>--type</code> option to the <code>prefect worker start</code> CLI command. To make your worker type available via the CLI, it must be available at import time.</p> <p>If your worker is in a package, you can add an entry point to your setup file in the following format:</p> <pre><code>entry_points={\n    \"prefect.collections\": [\n        \"my_package_name = my_worker_module\",\n    ]\n},\n</code></pre> <p>Prefect will discover this entry point and load your work module in the specified module. The entry point will allow the worker to be available via the CLI.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/kubernetes/","title":"Running Flows with Kubernetes","text":"<p>This guide will walk you through running your flows on Kubernetes. Though much of the guide is general to any Kubernetes cluster, there are differences between the managed Kubernetes offerings between cloud providers, especially when it comes to container registries and access management. We'll focus on Amazon Elastic Kubernetes Service (EKS).</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#prerequisites","title":"Prerequisites","text":"<p>Before we begin, there are a few pre-requisites:</p> <ol> <li>A Prefect Cloud account</li> <li>A cloud provider (AWS, GCP, or Azure) account</li> <li>Install Python and Prefect</li> <li>Install Helm</li> <li>Install the Kubernetes CLI (kubectl)</li> </ol> <p>Prefect is tested against Kubernetes 1.26.0 and newer minor versions.</p> <p>Administrator Access</p> <p>Though not strictly necessary, you may want to ensure you have admin access, both in Prefect Cloud and in your cloud provider. Admin access is only necessary during the initial setup and can be downgraded after.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-cluster","title":"Create a cluster","text":"<p>Let's start by creating a new cluster. If you already have one, skip ahead to the next section.</p> AWSGCPAzure <p>One easy way to get set up with a cluster in EKS is with <code>eksctl</code>.  Node pools can be backed by either EC2 instances or FARGATE.  Let's choose FARGATE so there's less to manage.  The following command takes around 15 minutes and must not be interrupted:</p> <pre><code># Replace the cluster name with your own value\neksctl create cluster --fargate --name &lt;CLUSTER-NAME&gt;\n\n# Authenticate to the cluster.\naws eks update-kubeconfig --name &lt;CLUSTER-NAME&gt;\n</code></pre> <p>You can get a GKE cluster up and running with a few commands using the <code>gcloud</code> CLI.  We'll build a bare-bones cluster that is accessible over the open internet - this should not be used in a production environment.  To deploy the cluster, your project must have a VPC network configured.</p> <p>First, authenticate to GCP by setting the following configuration options.</p> <pre><code># Authenticate to gcloud\ngcloud auth login\n\n# Specify the project &amp; zone to deploy the cluster to\n# Replace the project name with your GCP project name\ngcloud config set project &lt;GCP-PROJECT-NAME&gt;\ngcloud config set compute/zone &lt;AVAILABILITY-ZONE&gt;\n</code></pre> <p>Next, deploy the cluster - this command will take ~15 minutes to complete.  Once the cluster has been created, authenticate to the cluster.</p> <pre><code># Create cluster\n# Replace the cluster name with your own value\ngcloud container clusters create &lt;CLUSTER-NAME&gt; --num-nodes=1 \\\n--machine-type=n1-standard-2\n\n# Authenticate to the cluster\ngcloud container clusters &lt;CLUSTER-NAME&gt; --region &lt;AVAILABILITY-ZONE&gt;\n</code></pre> <p>GCP Gotchas</p> <ul> <li>You'll need to enable the default service account in the IAM console, or specify a different service account with the appropriate permissions to be used.</li> </ul> <pre><code>ERROR: (gcloud.container.clusters.create) ResponseError: code=400, message=Service account \"000000000000-compute@developer.gserviceaccount.com\" is disabled.\n</code></pre> <ul> <li>Organization policy blocks creation of external (public) IPs. You can override this policy (if you have the appropriate permissions) under the <code>Organizational Policy</code> page within IAM.</li> </ul> <pre><code>creation failed: Constraint constraints/compute.vmExternalIpAccess violated for project 000000000000. Add instance projects/&lt;GCP-PROJECT-NAME&gt;/zones/us-east1-b/instances/gke-gke-guide-1-default-pool-c369c84d-wcfl to the constraint to use external IP with it.\"\n</code></pre> <p>You can quickly create an AKS cluster using the Azure CLI, or use the Cloud Shell directly from the Azure portal shell.azure.com.</p> <p>First, authenticate to Azure if not already done.</p> <pre><code>  az login\n</code></pre> <p>Next, deploy the cluster - this command will take ~4 minutes to complete. Once the cluster has been created, authenticate to the cluster.</p> <pre><code>  # Create a Resource Group at the desired location, e.g. westus\n  az group create --name &lt;RESOURCE-GROUP-NAME&gt; --location &lt;LOCATION&gt;\n\n  # Create a kubernetes cluster with default kubernetes version, default SKU load balancer (Standard) and default vm set type (VirtualMachineScaleSets)\n  az aks create --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt;\n\n  # Configure kubectl to connect to your Kubernetes cluster\n  az aks get-credentials --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt;\n\n  # Verify the connection by listing the cluster nodes\n  kubectl get nodes\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-container-registry","title":"Create a container registry","text":"<p>Besides a cluster, the other critical resource we'll need is a container registry. A registry is not strictly required, but in most cases you'll want to use custom images and/or have more control over where images are stored. If you already have a registry, skip ahead to the next section.</p> AWSGCPAzure <p>Let's create a registry using the AWS CLI and authenticate the docker daemon to said registry:</p> <pre><code># Replace the image name with your own value\naws ecr create-repository --repository-name &lt;IMAGE-NAME&gt;\n\n# Login to ECR\n# Replace the region and account ID with your own values\naws ecr get-login-password --region &lt;REGION&gt; | docker login \\\n  --username AWS --password-stdin &lt;AWS_ACCOUNT_ID&gt;.dkr.ecr.&lt;REGION&gt;.amazonaws.com\n</code></pre> <p>Let's create a registry using the gcloud CLI and authenticate the docker daemon to said registry:</p> <pre><code># Create artifact registry repository to host your custom image\n# Replace the repository name with your own value; it can be the \n# same name as your image\ngcloud artifacts repositories create &lt;REPOSITORY-NAME&gt; \\\n--repository-format=docker --location=us\n\n# Authenticate to artifact registry\ngcloud auth configure-docker us-docker.pkg.dev\n</code></pre> <p>Let's create a registry using the Azure CLI and authenticate the docker daemon to said registry:</p> <pre><code># Name must be a lower-case alphanumeric\n# Tier SKU can easily be updated later, e.g. az acr update --name &lt;REPOSITORY-NAME&gt; --sku Standard\naz acr create --resource-group &lt;RESOURCE-GROUP-NAME&gt; \\\n  --name &lt;REPOSITORY-NAME&gt; \\\n  --sku Basic\n\n# Attach ACR to AKS cluster\n# You need Owner, Account Administrator, or Co-Administrator role on your Azure subscription as per Azure docs\naz aks update --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt; --attach-acr &lt;REPOSITORY-NAME&gt;\n\n# You can verify AKS can now reach ACR\naz aks check-acr --resource-group RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt; --acr &lt;REPOSITORY-NAME&gt;.azurecr.io\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-kubernetes-work-pool","title":"Create a Kubernetes work pool","text":"<p>Work pools allow you to manage deployment infrastructure. We'll configure the default values for our Kubernetes base job template. Note that these values can be overridden by individual deployments.</p> <p>Let's switch to the Prefect Cloud UI, where we'll create a new Kubernetes work pool (alternatively, you could use the Prefect CLI to create a work pool).</p> <ol> <li>Click on the Work Pools tab on the left sidebar</li> <li>Click the + button at the top of the page</li> <li>Select Kubernetes as the work pool type</li> <li>Click Next to configure the work pool settings</li> </ol> <p>Let's look at a few popular configuration options.</p> <p>Environment Variables</p> <p>Add environment variables to set when starting a flow run. So long as you are using a Prefect-maintained image and haven't overwritten the image's entrypoint, you can specify Python packages to install at runtime with <code>{\"EXTRA_PIP_PACKAGES\":\"my_package\"}</code>. For example <code>{\"EXTRA_PIP_PACKAGES\":\"pandas==1.2.3\"}</code> will install pandas version 1.2.3. Alternatively, you can specify package installation in a custom Dockerfile, which can allow you to take advantage of image caching. As we'll see below, Prefect can help us create a Dockerfile with our flow code and the packages specified in a <code>requirements.txt</code> file baked in.</p> <p>Namespace</p> <p>Set the Kubernetes namespace to create jobs within, such as <code>prefect</code>. By default, set to default.</p> <p>Image</p> <p>Specify the Docker container image for created jobs. If not set, the latest Prefect 2 image will be used (i.e. <code>prefecthq/prefect:2-latest</code>). Note that you can override this on each deployment through <code>job_variables</code>.</p> <p>Image Pull Policy</p> <p>Select from the dropdown options to specify when to pull the image. When using the <code>IfNotPresent</code> policy, make sure to use unique image tags, as otherwise old images could get cached on your nodes.</p> <p>Finished Job TTL</p> <p>Number of seconds before finished jobs are automatically cleaned up by Kubernetes' controller. You may want to set to 60 so that completed flow runs are cleaned up after a minute.</p> <p>Pod Watch Timeout Seconds</p> <p>Number of seconds for pod creation to complete before timing out. Consider setting to 300, especially if using a serverless type node pool, as these tend to have longer startup times.</p> <p>Kubernetes Cluster Config</p> <p>You can configure the Kubernetes cluster to use for job creation by specifying a <code>KubernetesClusterConfig</code> block. Generally you should leave the cluster config blank as the worker should be provisioned with appropriate access and permissions. Typically this setting is used when a worker is deployed to a cluster that is different from the cluster where flow runs are executed.</p> <p>Advanced Settings</p> <p>Want to modify the default base job template to add other fields or delete existing fields?</p> <p>Select the Advanced tab and edit the JSON representation of the base job template.</p> <p>For example, to set a CPU request, add the following section under variables:</p> <pre><code>\"cpu_request\": {\n  \"title\": \"CPU Request\",\n  \"description\": \"The CPU allocation to request for this pod.\",\n  \"default\": \"default\",\n  \"type\": \"string\"\n},\n</code></pre> <p>Next add the following to the first <code>containers</code> item under <code>job_configuration</code>:</p> <pre><code>...\n\"containers\": [\n  {\n    ...,\n    \"resources\": {\n      \"requests\": {\n        \"cpu\": \"{{ cpu_request }}\"\n      }\n    }\n  }\n],\n...\n</code></pre> <p>Running deployments with this work pool will now request the specified CPU.</p> <p>After configuring the work pool settings, move to the next screen.</p> <p>Give the work pool a name and save.</p> <p>Our new Kubernetes work pool should now appear in the list of work pools.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-prefect-cloud-api-key","title":"Create a Prefect Cloud API key","text":"<p>While in the Prefect Cloud UI, create a Prefect Cloud API key if you don't already have one. Click on your profile avatar picture, then click your name to go to your profile settings, click API Keys and hit the plus button to create a new API key here. Make sure to store it safely along with your other passwords, ideally via a password manager.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#deploy-a-worker-using-helm","title":"Deploy a worker using Helm","text":"<p>With our cluster and work pool created, it's time to deploy a worker, which will set up Kubernetes infrastructure to run our flows. The best way to deploy a worker is using the Prefect Helm Chart.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#add-the-prefect-helm-repository","title":"Add the Prefect Helm repository","text":"<p>Add the Prefect Helm repository to your Helm client:</p> <pre><code>helm repo add prefect https://prefecthq.github.io/prefect-helm\nhelm repo update\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-namespace","title":"Create a namespace","text":"<p>Create a new namespace in your Kubernetes cluster to deploy the Prefect worker:</p> <pre><code>kubectl create namespace prefect\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-kubernetes-secret-for-the-prefect-api-key","title":"Create a Kubernetes secret for the Prefect API key","text":"<pre><code>kubectl create secret generic prefect-api-key \\\n--namespace=prefect --from-literal=key=your-prefect-cloud-api-key\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#configure-helm-chart-values","title":"Configure Helm chart values","text":"<p>Create a <code>values.yaml</code> file to customize the Prefect worker configuration. Add the following contents to the file:</p> <pre><code>worker:\n  cloudApiConfig:\n    accountId: &lt;target account ID&gt;\n    workspaceId: &lt;target workspace ID&gt;\n  config:\n    workPool: &lt;target work pool name&gt;\n</code></pre> <p>These settings will ensure that the worker connects to the proper account, workspace, and work pool.</p> <p>View your Account ID and Workspace ID in your browser URL when logged into Prefect Cloud. For example: https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-helm-release","title":"Create a Helm release","text":"<p>Let's install the Prefect worker using the Helm chart with your custom <code>values.yaml</code> file:</p> <pre><code>helm install prefect-worker prefect/prefect-worker \\\n  --namespace=prefect \\\n  -f values.yaml\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#verify-deployment","title":"Verify deployment","text":"<p>Check the status of your Prefect worker deployment:</p> <pre><code>kubectl get pods -n prefect\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#define-a-flow","title":"Define a flow","text":"<p>Let's start simple with a flow that just logs a message. In a directory named <code>flows</code>, create a file named <code>hello.py</code> with the following contents:</p> <pre><code>from prefect import flow, get_run_logger, tags\n\n@flow\ndef hello(name: str = \"Marvin\"):\n    logger = get_run_logger()\n    logger.info(f\"Hello, {name}!\")\n\nif __name__ == \"__main__\":\n    with tags(\"local\"):\n        hello()\n</code></pre> <p>Run the flow locally with <code>python hello.py</code> to verify that it works. Note that we use the <code>tags</code> context manager to tag the flow run as <code>local</code>. This step is not required, but does add some helpful metadata.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#define-a-prefect-deployment","title":"Define a Prefect deployment","text":"<p>Prefect has two recommended options for creating a deployment with dynamic infrastructure. You can define a deployment in a Python script using the <code>flow.deploy</code> mechanics or in a <code>prefect.yaml</code> definition file. The <code>prefect.yaml</code> file currently allows for more customization in terms of push and pull steps. Kubernetes objects are defined in YAML, so we expect many teams using Kubernetes work pools to create their deployments with YAML as well. To learn about the Python deployment creation method with <code>flow.deploy</code> refer to the Workers &amp; Work Pools tutorial page.</p> <p>The <code>prefect.yaml</code> file is used by the <code>prefect deploy</code> command to deploy our flows. As a part of that process it will also build and push our image. Create a new file named <code>prefect.yaml</code> with the following contents:</p> <pre><code># Generic metadata about this project\nname: flows\nprefect-version: 2.13.8\n\n# build section allows you to manage and build docker images\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ $PREFECT_IMAGE_NAME }}\"\n    tag: latest\n    dockerfile: auto\n    platform: \"linux/amd64\"\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ build-image.image_name }}\"\n    tag: \"{{ build-image.tag }}\"\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /opt/prefect/flows\n\n# the definitions section allows you to define reusable components for your deployments\ndefinitions:\n  tags: &amp;common_tags\n    - \"eks\"\n  work_pool: &amp;common_work_pool\n    name: \"kubernetes\"\n    job_variables:\n      image: \"{{ build-image.image }}\"\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: \"default\"\n  tags: *common_tags\n  schedule: null\n  entrypoint: \"flows/hello.py:hello\"\n  work_pool: *common_work_pool\n\n- name: \"arthur\"\n  tags: *common_tags\n  schedule: null\n  entrypoint: \"flows/hello.py:hello\"\n  parameters:\n    name: \"Arthur\"\n  work_pool: *common_work_pool\n</code></pre> <p>We define two deployments of the <code>hello</code> flow: <code>default</code> and <code>arthur</code>. Note that by specifying <code>dockerfile: auto</code>, Prefect will automatically create a dockerfile that installs any <code>requirements.txt</code> and copies over the current directory. You can pass a custom Dockerfile instead with <code>dockerfile: Dockerfile</code> or <code>dockerfile: path/to/Dockerfile</code>. Also note that we are specifically building for the <code>linux/amd64</code> platform. This specification is often necessary when images are built on Macs with M series chips but run on cloud provider instances.</p> <p>Deployment specific build, push, and pull</p> <p>The build, push, and pull steps can be overridden for each deployment. This allows for more custom behavior, such as specifying a different image for each deployment.</p> <p>Let's make sure we define our requirements in a <code>requirements.txt</code> file:</p> <pre><code>prefect&gt;=2.13.8\nprefect-docker&gt;=0.4.0\nprefect-kubernetes&gt;=0.3.1\n</code></pre> <p>The directory should now look something like this:</p> <pre><code>.\n\u251c\u2500\u2500 prefect.yaml\n\u2514\u2500\u2500 flows\n    \u251c\u2500\u2500 requirements.txt\n    \u2514\u2500\u2500 hello.py\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#tag-images-with-a-git-sha","title":"Tag images with a Git SHA","text":"<p>If your code is stored in a GitHub repository, it's good practice to tag your images with the Git SHA of the code used to build it. This can be done in the <code>prefect.yaml</code> file with a few minor modifications, and isn't yet an option with the Python deployment creation method. Let's use the <code>run_shell_script</code> command to grab the SHA and pass it to the <code>tag</code> parameter of <code>build_docker_image</code>:</p> <pre><code>build:\n- prefect.deployments.steps.run_shell_script:\n    id: get-commit-hash\n    script: git rev-parse --short HEAD\n    stream_output: false\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ $PREFECT_IMAGE_NAME }}\"\n    tag: \"{{ get-commit-hash.stdout }}\"\n    dockerfile: auto\n    platform: \"linux/amd64\"\n</code></pre> <p>Let's also set the SHA as a tag for easy identification in the UI:</p> <pre><code>definitions:\n  tags: &amp;common_tags\n    - \"eks\"\n    - \"{{ get-commit-hash.stdout }}\"\n  work_pool: &amp;common_work_pool\n    name: \"kubernetes\"\n    job_variables:\n      image: \"{{ build-image.image }}\"\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#authenticate-to-prefect","title":"Authenticate to Prefect","text":"<p>Before we deploy the flows to Prefect, we will need to authenticate via the Prefect CLI. We will also need to ensure that all of our flow's dependencies are present at <code>deploy</code> time.</p> <p>This example uses a virtual environment to ensure consistency across environments.</p> <pre><code># Create a virtualenv &amp; activate it\nvirtualenv prefect-demo\nsource prefect-demo/bin/activate\n\n# Install dependencies of your flow\nprefect-demo/bin/pip install -r requirements.txt\n\n# Authenticate to Prefect &amp; select the appropriate \n# workspace to deploy your flows to\nprefect-demo/bin/prefect cloud login\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#deploy-the-flows","title":"Deploy the flows","text":"<p>Now we're ready to deploy our flows which will build our images. The image name determines which registry it will end up in. We have configured our <code>prefect.yaml</code> file to get the image name from the <code>PREFECT_IMAGE_NAME</code> environment variable, so let's set that first:</p> AWSGCPAzure <pre><code>export PREFECT_IMAGE_NAME=&lt;AWS_ACCOUNT_ID&gt;.dkr.ecr.&lt;REGION&gt;.amazonaws.com/&lt;IMAGE-NAME&gt;\n</code></pre> <pre><code>export PREFECT_IMAGE_NAME=us-docker.pkg.dev/&lt;GCP-PROJECT-NAME&gt;/&lt;REPOSITORY-NAME&gt;/&lt;IMAGE-NAME&gt;\n</code></pre> <pre><code>export PREFECT_IMAGE_NAME=&lt;REPOSITORY-NAME&gt;.azurecr.io/&lt;IMAGE-NAME&gt;\n</code></pre> <p>To deploy your flows, ensure your Docker daemon is running first. Deploy all the flows with <code>prefect deploy --all</code> or deploy them individually by name: <code>prefect deploy -n hello/default</code> or <code>prefect deploy -n hello/arthur</code>.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#run-the-flows","title":"Run the flows","text":"<p>Once the deployments are successfully created, we can run them from the UI or the CLI:</p> <pre><code>prefect deployment run hello/default\nprefect deployment run hello/arthur\n</code></pre> <p>Congratulations! You just ran two deployments in Kubernetes. Head over to the UI to check their status!</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/overriding-job-variables/","title":"Deeper Dive: Overriding Work Pool Job Variables","text":"<p>As described in the Deploying Flows to Work Pools and Workers guide, there are two ways to deploy flows to work pools: using a <code>prefect.yaml</code> file or using the <code>.deploy()</code> method.</p> <p>In both cases, you can override job variables on a work pool for a given deployment.</p> <p>While exactly which job variables are available to be overridden depends on the type of work pool you're using at a given time, this guide will explore some common patterns for overriding job variables in both deployment methods.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#background","title":"Background","text":"<p>First of all, what are \"job variables\"?</p> <p>Job variables are infrastructure related values that are configurable on a work pool, which may be relevant to how your flow run executes on your infrastructure. Job variables can be overridden on a per-deployment or per-flow run basis, allowing you to dynamically change infrastructure from the work pools defaults depending on your needs.</p> <p>Let's use <code>env</code> - the only job variable that is configurable for all work pool types - as an example.</p> <p>When you create or edit a work pool, you can specify a set of environment variables that will be set in the runtime environment of the flow run.</p> <p>For example, you might want a certain deployment to have the following environment variables available: <pre><code>{\n  \"EXECUTION_ENV\": \"staging\",\n  \"MY_NOT_SO_SECRET_CONFIG\": \"plumbus\",\n}\n</code></pre></p> <p>Rather than hardcoding these values into your work pool in the UI and making them available to all deployments associated with that work pool, you can override these values on a per-deployment basis.</p> <p>Let's look at how to do that.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#how-to-override-job-variables-on-a-deployment","title":"How to override job variables on a deployment","text":"<p>Say we have the following repo structure: <pre><code>\u00bb tree\n.\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 demo_project\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 daily_flow.py\n</code></pre></p> <p>... and we have some <code>demo_flow.py</code> file like this:</p> <pre><code>import os\nfrom prefect import flow, task\n\n@task\ndef do_something_important(not_so_secret_value: str) -&gt; None:\n    print(f\"Doing something important with {not_so_secret_value}!\")\n\n@flow(log_prints=True)\ndef some_work():\n    environment = os.environ.get(\"EXECUTION_ENVIRONMENT\", \"local\")\n\n    print(f\"Coming to you live from {environment}!\")\n\n    not_so_secret_value = os.environ.get(\"MY_NOT_SO_SECRET_CONFIG\")\n\n    if not_so_secret_value is None:\n        raise ValueError(\"You forgot to set MY_NOT_SO_SECRET_CONFIG!\")\n\n    do_something_important(not_so_secret_value)\n</code></pre>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-a-prefectyaml-file","title":"Using a <code>prefect.yaml</code> file","text":"<p>In this case, let's also say we have the following deployment definition in a <code>prefect.yaml</code> file at the root of our repository: <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n  schedule: null\n</code></pre></p> <p>Note</p> <p>While not the focus of this guide, note that this deployment definition uses a default \"global\" <code>pull</code> step, because one is not explicitly defined on the deployment. For reference, here's what that would look like at the top of the <code>prefect.yaml</code> file: <pre><code>pull:\n- prefect.deployments.steps.git_clone: &amp;clone_repo\n    repository: https://github.com/some-user/prefect-monorepo\n    branch: main\n</code></pre></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#hard-coded-job-variables","title":"Hard-coded job variables","text":"<p>To provide the <code>EXECUTION_ENVIRONMENT</code> and <code>MY_NOT_SO_SECRET_CONFIG</code> environment variables to this deployment, we can add a <code>job_variables</code> section to our deployment definition in the <code>prefect.yaml</code> file:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n    job_variables:\n        env:\n            EXECUTION_ENVIRONMENT: staging\n            MY_NOT_SO_SECRET_CONFIG: plumbus\n  schedule: null\n</code></pre> <p>... and then run <code>prefect deploy -n demo-deployment</code> to deploy the flow with these job variables.</p> <p>We should then be able to see the job variables in the <code>Configuration</code> tab of the deployment in the UI:</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-existing-environment-variables","title":"Using existing environment variables","text":"<p>If you want to use environment variables that are already set in your local environment, you can template these in the <code>prefect.yaml</code> file using the <code>{{ $ENV_VAR_NAME }}</code> syntax:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n    job_variables:\n        env:\n            EXECUTION_ENVIRONMENT: \"{{ $EXECUTION_ENVIRONMENT }}\"\n            MY_NOT_SO_SECRET_CONFIG: \"{{ $MY_NOT_SO_SECRET_CONFIG }}\"\n  schedule: null\n</code></pre> <p>Note</p> <p>This assumes that the machine where <code>prefect deploy</code> is run would have these environment variables set.</p> <p> <pre><code>export EXECUTION_ENVIRONMENT=staging\nexport MY_NOT_SO_SECRET_CONFIG=plumbus\n</code></pre> </p> <p>As before, run <code>prefect deploy -n demo-deployment</code> to deploy the flow with these job variables, and you should see them in the UI under the <code>Configuration</code> tab.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-deploy-method","title":"Using the <code>.deploy()</code> method","text":"<p>If you're using the <code>.deploy()</code> method to deploy your flow, the process is similar, but instead of having your <code>prefect.yaml</code> file define the job variables, you can pass them as a dictionary to the <code>job_variables</code> argument of the <code>.deploy()</code> method.</p> <p>We could add the following block to our <code>demo_project/daily_flow.py</code> file from the setup section: <pre><code>if __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/zzstoatzz/prefect-monorepo.git\",\n        entrypoint=\"src/demo_project/demo_flow.py:some_work\"\n    ).deploy(\n        name=\"demo-deployment\",\n        work_pool_name=\"local\", # can only .deploy() to a local work pool in prefect&gt;=2.15.1\n        job_variables={\n            \"env\": {\n                \"EXECUTION_ENVIRONMENT\": os.environ.get(\"EXECUTION_ENVIRONMENT\", \"local\"),\n                \"MY_NOT_SO_SECRET_CONFIG\": os.environ.get(\"MY_NOT_SO_SECRET_CONFIG\")\n            }\n        }\n    )\n</code></pre></p> <p>Note</p> <p>The above example works assuming a couple things: - the machine where this script is run would have these environment variables set.  <pre><code>export EXECUTION_ENVIRONMENT=staging\nexport MY_NOT_SO_SECRET_CONFIG=plumbus\n</code></pre> </p> <ul> <li><code>demo_project/daily_flow.py</code> already exists in the repository at the specified path</li> </ul> <p>Running this script with something like:</p> <pre><code>python demo_project/daily_flow.py\n</code></pre> <p>... will deploy the flow with the specified job variables, which should then be visible in the UI under the <code>Configuration</code> tab.</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#how-to-override-job-variables-on-a-flow-run","title":"How to override job variables on a flow run","text":"<p>When running flows, you can pass in job variables that override any values set on the work pool or deployment. Any interface that runs deployments can accept job variables.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-custom-run-form-in-the-ui","title":"Using the custom run form in the UI","text":"<p>Custom runs allow you to pass in a dictionary of variables into your flow run infrastructure. Using the same <code>env</code> example from above, we could do the following:</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-cli","title":"Using the CLI","text":"<p>Similarly, runs kicked off via CLI accept job variables with the <code>-jv</code> or <code>--job-variable</code> flag.</p> <pre><code>prefect deployment run \\\n  --id \"fb8e3073-c449-474b-b993-851fe5e80e53\" \\\n  --job-variable MY_NEW_ENV_VAR=42 \\\n  --job-variable HELLO=THERE\n</code></pre>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-job-variables-in-automations","title":"Using job variables in automations","text":"<p>Additionally, runs kicked off via automation actions can use job variables, including ones rendered from Jinja templates.</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/push-work-pools/","title":"Push Work to Serverless Computing Infrastructure","text":"<p>Push work pools are a special type of work pool that allows Prefect Cloud to submit flow runs for execution to serverless computing infrastructure without running a worker. Push work pools currently support execution in AWS ECS tasks, Azure Container Instances, Google Cloud Run jobs, and Modal.</p> <p>In this guide you will:</p> <ul> <li>Create a push work pool that sends work to Amazon Elastic Container Service (AWS ECS), Azure Container Instances (ACI), Google Cloud Run, or Modal</li> <li>Deploy a flow to that work pool</li> <li>Execute a flow without having to run a worker or agent process to poll for flow runs</li> </ul> <p>You can automatically provision infrastructure and create your push work pool using the <code>prefect work-pool create</code> CLI command with the <code>--provision-infra</code> flag. This approach greatly simplifies the setup process.</p> <p>Let's explore automatic infrastructure provisioning for push work pools first, and then we'll cover how to manually set up your push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#automatic-infrastructure-provisioning","title":"Automatic infrastructure provisioning","text":"<p>With Perfect Cloud you can provision infrastructure for use with an AWS ECS, Google Cloud Run, ACI push work pool. Push work pools in Prefect Cloud simplify the setup and management of the infrastructure necessary to run your flows. However, setting up infrastructure on your cloud provider can still be a time-consuming process. Prefect can dramatically simplify this process by automatically provisioning the necessary infrastructure for you.</p> <p>We'll use the <code>prefect work-pool create</code> CLI command with the <code>--provision-infra</code> flag to automatically provision your serverless cloud resources and set up your Prefect workspace to use a new push pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#prerequisites","title":"Prerequisites","text":"<p>To use automatic infrastructure provisioning, you'll need to have the relevant cloud CLI library installed and to have authenticated with your cloud provider.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Install the AWS CLI, authenticate with your AWS account, and set a default region.</p> <p>If you already have the AWS CLI installed, be sure to update to the latest version. </p> <p>You will need the following permissions in your authenticated AWS account:</p> <p>IAM Permissions:</p> <ul> <li>iam:CreatePolicy</li> <li>iam:GetPolicy</li> <li>iam:ListPolicies</li> <li>iam:CreateUser</li> <li>iam:GetUser</li> <li>iam:AttachUserPolicy</li> <li>iam:CreateRole</li> <li>iam:GetRole</li> <li>iam:AttachRolePolicy</li> <li>iam:ListRoles</li> <li>iam:PassRole</li> </ul> <p>Amazon ECS Permissions:</p> <ul> <li>ecs:CreateCluster</li> <li>ecs:DescribeClusters</li> </ul> <p>Amazon EC2 Permissions:</p> <ul> <li>ec2:CreateVpc</li> <li>ec2:DescribeVpcs</li> <li>ec2:CreateInternetGateway</li> <li>ec2:AttachInternetGateway</li> <li>ec2:CreateRouteTable</li> <li>ec2:CreateRoute</li> <li>ec2:CreateSecurityGroup</li> <li>ec2:DescribeSubnets</li> <li>ec2:CreateSubnet</li> <li>ec2:DescribeAvailabilityZones</li> <li>ec2:AuthorizeSecurityGroupIngress</li> <li>ec2:AuthorizeSecurityGroupEgress</li> </ul> <p>Amazon ECR Permissions:</p> <ul> <li>ecr:CreateRepository</li> <li>ecr:DescribeRepositories</li> <li>ecr:GetAuthorizationToken</li> </ul> <p>If you want to use AWS managed policies, you can use the following:</p> <ul> <li>AmazonECS_FullAccess</li> <li>AmazonEC2FullAccess</li> <li>IAMFullAccess</li> <li>AmazonEC2ContainerRegistryFullAccess</li> </ul> <p>Note that the above policies will give you all the permissions needed, but are more permissive than necessary.</p> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install the Azure CLI and authenticate with your Azure account.</p> <p>If you already have the Azure CLI installed, be sure to update to the latest version with <code>az upgrade</code>.</p> <p>You will also need the following roles in your Azure subscription:</p> <ul> <li>Contributor</li> <li>User Access Administrator</li> <li>Application Administrator</li> <li>Managed Identity Operator</li> <li>Azure Container Registry Contributor</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install the gcloud CLI and authenticate with your GCP project.</p> <p>If you already have the gcloud CLI installed, be sure to update to the latest version with <code>gcloud components update</code>.</p> <p>You will also need the following permissions in your GCP project:</p> <ul> <li>resourcemanager.projects.list</li> <li>serviceusage.services.enable</li> <li>iam.serviceAccounts.create</li> <li>iam.serviceAccountKeys.create</li> <li>resourcemanager.projects.setIamPolicy</li> <li>artifactregistry.repositories.create</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install <code>modal</code> by running:</p> <p> <pre><code>pip install modal\n</code></pre> </p> <p>Create a Modal API token by running:</p> <p> <pre><code>modal token new\n</code></pre> </p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#automatically-creating-a-new-push-work-pool-and-provisioning-infrastructure","title":"Automatically creating a new push work pool and provisioning infrastructure","text":"<p>Here's the command to create a new push work pool and configure the necessary infrastructure.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <pre><code>prefect work-pool create --type ecs:push --provision-infra my-ecs-pool\n</code></pre> <p>Using the <code>--provision-infra</code> flag will automatically set up your default AWS account to be ready to execute flows via ECS tasks.  In your AWS account, this command will create a new IAM user, IAM policy, ECS cluster that uses AWS Fargate, VPC, and ECR repository if they don't already exist. In your Prefect workspace, this command will create an <code>AWSCredentials</code> block for storing the generated credentials.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-ecs-pool will require:                                          \u2502\n\u2502                                                                                                                   \u2502\n\u2502          - Creating an IAM user for managing ECS tasks: prefect-ecs-user                                          \u2502\n\u2502          - Creating and attaching an IAM policy for managing ECS tasks: prefect-ecs-policy                        \u2502\n\u2502          - Storing generated AWS credentials in a block                                                           \u2502\n\u2502          - Creating an ECS cluster for running Prefect flows: prefect-ecs-cluster                                 \u2502\n\u2502          - Creating a VPC with CIDR 172.31.0.0/16 for running ECS tasks: prefect-ecs-vpc                          \u2502\n\u2502          - Creating an ECR repository for storing Prefect images: prefect-flows                                   \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nProvisioning IAM user\nCreating IAM policy\nGenerating AWS credentials\nCreating AWS credentials block\nProvisioning ECS cluster\nProvisioning VPC\nCreating internet gateway\nSetting up subnets\nSetting up security group\nProvisioning ECR repository\nAuthenticating with ECR\nSetting default Docker build namespace\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-ecs-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new ECR repository and the default Docker build namespace will be set to the URL of the registry.</p> <p>While the default namespace is set, you will not need to provide the registry URL when building images as part of your deployment process.</p> <p>To take advantage of this, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n@flow(log_prints=True)            \ndef my_flow(name: str = \"world\"):                          \n    print(f\"Hello {name}! I'm a flow running in a ECS task!\") \n\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"my-deployment\", \n        work_pool_name=\"my-work-pool\",\n        image=DeploymentImage(                                                 \n            name=\"my-repository:latest\",\n            platform=\"linux/amd64\",\n        )                                                                      \n    )       \n</code></pre> <p>This will build an image with the tag <code>&lt;ecr-registry-url&gt;/my-image:latest</code> and push it to the registry.</p> <p>Your image name will need to match the name of the repository created with your work pool. You can create new repositories in the ECR console.</p> <p><pre><code>prefect work-pool create --type azure-container-instance:push --provision-infra my-aci-pool\n</code></pre> </p> <p>Using the <code>--provision-infra</code> flag will automatically set up your default Azure account to be ready to execute flows via Azure Container Instances. In your Azure account, this command will create a resource group, app registration, service account with necessary permission, generate a secret for the app registration, and create an Azure Container Registry, if they don't already exist. In your Prefect workspace, this command will create an <code>AzureContainerInstanceCredentials</code> block for storing the client secret value from the generated secret.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-aci-work-pool will require:                     \u2502\n\u2502                                                                                           \u2502\n\u2502     Updates in subscription Azure subscription 1                                          \u2502\n\u2502                                                                                           \u2502\n\u2502         - Create a resource group in location eastus                                      \u2502\n\u2502         - Create an app registration in Azure AD prefect-aci-push-pool-app                \u2502\n\u2502         - Create/use a service principal for app registration                             \u2502\n\u2502         - Generate a secret for app registration                                          \u2502\n\u2502         - Create an Azure Container Registry with prefix prefect                          \u2502\n\u2502         - Create an identity prefect-acr-identity to allow access to the created registry \u2502\n\u2502         - Assign Contributor role to service account                                      \u2502\n\u2502         - Create an ACR registry for image hosting                                        \u2502\n\u2502         - Create an identity for Azure Container Instance to allow access to the registry \u2502\n\u2502                                                                                           \u2502\n\u2502     Updates in Prefect workspace                                                          \u2502\n\u2502                                                                                           \u2502\n\u2502         - Create Azure Container Instance credentials block aci-push-pool-credentials     \u2502\n\u2502                                                                                           \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]:     \nCreating resource group\nCreating app registration\nGenerating secret for app registration\nCreating ACI credentials block\nACI credentials block 'aci-push-pool-credentials' created in Prefect Cloud\nAssigning Contributor role to service account\nCreating Azure Container Registry\nCreating identity\nProvisioning infrastructure... \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned for 'my-aci-work-pool' work pool!\nCreated work pool 'my-aci-work-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new Azure Container Registry and the default Docker build namespace will be set to the URL of the registry.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the registry.</p> <p>To take advantage of this functionality, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)                                                         \ndef my_flow(name: str = \"world\"):                                              \n    print(f\"Hello {name}! I'm a flow running on an Azure Container Instance!\") \n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"my-work-pool\",                                                \n        image=DeploymentImage(                                                 \n            name=\"my-image:latest\",                                            \n            platform=\"linux/amd64\",                                            \n        )                                                                      \n    )       \n</code></pre> <p>This will build an image with the tag <code>&lt;acr-registry-url&gt;/my-image:latest</code> and push it to the registry.</p> <pre><code>prefect work-pool create --type cloud-run:push --provision-infra my-cloud-run-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag will allow you to select a GCP project to use for your work pool and automatically configure it to be ready to execute flows via Cloud Run. In your GCP project, this command will activate the Cloud Run API, create a service account, and create a key for the service account, if they don't already exist. In your Prefect workspace, this command will create a <code>GCPCredentials</code> block for storing the service account key.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-cloud-run-pool will require:                           \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in GCP project central-kit-405415 in region us-central1                                      \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Activate the Cloud Run API for your project                                                    \u2502\n\u2502         - Activate the Artifact Registry API for your project                                            \u2502\n\u2502         - Create an Artifact Registry repository named prefect-images                                    \u2502\n\u2502         - Create a service account for managing Cloud Run jobs: prefect-cloud-run                        \u2502\n\u2502             - Service account will be granted the following roles:                                       \u2502\n\u2502                 - Service Account User                                                                   \u2502\n\u2502                 - Cloud Run Developer                                                                    \u2502\n\u2502         - Create a key for service account prefect-cloud-run                                             \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in Prefect workspace                                                                         \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Create GCP credentials block my--pool-push-pool-credentials to store the service account key   \u2502\n\u2502                                                                                                          \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nActivating Cloud Run API\nActivating Artifact Registry API\nCreating Artifact Registry repository\nConfiguring authentication to Artifact Registry\nSetting default Docker build namespace\nCreating service account\nAssigning roles to service account\nCreating service account key\nCreating GCP credentials block\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-cloud-run-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new Artifact Registry repository and the default Docker build namespace will be set to the URL of the repository.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the repository.</p> <p>To take advantage of this functionality, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow running on Cloud Run!\")\n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"above-ground\",\n        image=DeploymentImage(\n            name=\"my-image:latest\",\n            platform=\"linux/amd64\",\n        )\n    )\n</code></pre> <p>This will build an image with the tag <code>&lt;region&gt;-docker.pkg.dev/&lt;project&gt;/&lt;repository-name&gt;/my-image:latest</code> and push it to the repository.</p> <pre><code>prefect work-pool create --type modal:push --provision-infra my-modal-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag will trigger the creation of a <code>ModalCredentials</code> block in your Prefect Cloud workspace. This block will store your Modal API token, which is used to authenticate with Modal's API. By default, the token for your current Modal profile will be used for the new <code>ModalCredentials</code> block. If Prefect is unable to discover a Modal API token for your current profile, you will be prompted to create a new one.</p> <p>That's it! You're ready to create and schedule deployments that use your new push work pool. Reminder that no worker is needed to run flows with a push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#using-existing-resources-with-automatic-infrastructure-provisioning","title":"Using existing resources with automatic infrastructure provisioning","text":"<p>If you already have the necessary infrastructure set up, Prefect will detect that upon work pool creation and the infrastructure provisioning for that resource will be skipped.</p> <p>For example, here's how <code>prefect work-pool create my-work-pool --provision-infra</code> looks when existing Azure resources are detected:</p> <pre><code>Proceed with infrastructure provisioning? [y/n]: y\nCreating resource group\nResource group 'prefect-aci-push-pool-rg' already exists in location 'eastus'.\nCreating app registration\nApp registration 'prefect-aci-push-pool-app' already exists.\nGenerating secret for app registration\nProvisioning infrastructure\nACI credentials block 'bb-push-pool-credentials' created\nAssigning Contributor role to service account...\nService principal with object ID '4be6fed7-...' already has the 'Contributor' role assigned in \n'/subscriptions/.../'\nCreating Azure Container Instance\nContainer instance 'prefect-aci-push-pool-container' already exists.\nCreating Azure Container Instance credentials block\nProvisioning infrastructure... \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-work-pool'!\n</code></pre>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#provisioning-infrastructure-for-an-existing-push-work-pool","title":"Provisioning infrastructure for an existing push work pool","text":"<p>If you already have a push work pool set up, but haven't configured the necessary infrastructure, you can use the <code>provision-infra</code> sub-command to provision the infrastructure for that work pool. For example, you can run the following command if you have a work pool named \"my-work-pool\".</p> <pre><code>prefect work-pool provision-infra my-work-pool\n</code></pre> <p>Prefect will create the necessary infrastructure for the <code>my-work-pool</code> work pool and provide you with a summary of the changes to be made:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-work-pool will require:                                      \u2502\n\u2502                                                                                                                \u2502\n\u2502     Updates in subscription Azure subscription 1                                                               \u2502\n\u2502                                                                                                                \u2502\n\u2502         - Create a resource group in location eastus                                                           \u2502\n\u2502         - Create an app registration in Azure AD prefect-aci-push-pool-app                                     \u2502\n\u2502         - Create/use a service principal for app registration                                                  \u2502\n\u2502         - Generate a secret for app registration                                                               \u2502\n\u2502         - Assign Contributor role to service account                                                           \u2502\n\u2502         - Create Azure Container Instance 'aci-push-pool-container' in resource group prefect-aci-push-pool-rg \u2502\n\u2502                                                                                                                \u2502\n\u2502     Updates in Prefect workspace                                                                               \u2502\n\u2502                                                                                                                \u2502\n\u2502         - Create Azure Container Instance credentials block aci-push-pool-credentials                          \u2502\n\u2502                                                                                                                \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\n</code></pre> <p>This command can speed up your infrastructure setup process.</p> <p>As with the examples above, you will need to have the related cloud CLI library installed and be authenticated with your cloud provider.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#manual-infrastructure-provisioning","title":"Manual infrastructure provisioning","text":"<p>If you prefer to set up your infrastructure manually, don't include the <code>--provision-infra</code> flag in the CLI command. In the examples below, we'll create a push work pool via the Prefect Cloud UI.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>To push work to ECS, AWS credentials are required.</p> <p>Create a user and attach the AmazonECS_FullAccess permissions.</p> <p>From that user's page create credentials and store them somewhere safe for use in the next section.</p> <p>To push work to Azure, an Azure subscription, resource group and tenant secret are required. </p> <p>Create Subscription and Resource Group</p> <ol> <li>In the Azure portal, create a subscription.</li> <li>Create a resource group within your subscription.</li> </ol> <p>Create App Registration</p> <ol> <li>In the Azure portal, create an app registration.</li> <li>In the app registration, create a client secret. Copy the value and store it somewhere safe.</li> </ol> <p>Add App Registration to Resource Group</p> <ol> <li>Navigate to the resource group you created earlier.</li> <li>Choose the \"Access control (IAM)\" blade in the left-hand side menu. Click \"+ Add\" button at the top, then \"Add role assignment\".</li> <li>Go to the \"Privileged administrator roles\" tab, click on \"Contributor\", then click \"Next\" at the bottom of the page.</li> <li>Click on \"+ Select members\". Type the name of the app registration (otherwise it may not autopopulate) and click to add it. Then hit \"Select\" and click \"Next\". The default permissions associated with a role like \"Contributor\" might not always be sufficient for all operations related to Azure Container Instances (ACI). The specific permissions required can depend on the operations you need to perform (like creating, running, and deleting ACI container groups) and your organization's security policies. In some cases, additional permissions or custom roles might be necessary.</li> <li>Click \"Review + assign\" to finish.</li> </ol> <p>A GCP service account and an API Key are required, to push work to Cloud Run.</p> <p>Create a service account by navigating to the service accounts page and clicking Create. Name and describe your service account, and click continue to configure permissions.</p> <p>The service account must have two roles at a minimum, Cloud Run Developer, and Service Account User.</p> <p></p> <p>Once the Service account is created, navigate to its Keys page to add an API key. Create a JSON type key, download it, and store it somewhere safe for use in the next section.</p> <p>A Modal API token is required to push work to Modal.</p> <p>Create a Modal API token by navigating to Settings in the Modal UI. In the API Tokens section of the Settings page, click New Token.</p> <p>Copy the token ID and token secret and store them somewhere safe for use in the next section.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#work-pool-configuration","title":"Work pool configuration","text":"<p>Our push work pool will store information about what type of infrastructure our flow will run on, what default values to provide to compute jobs, and other important execution environment parameters. Because our push work pool needs to integrate securely with your serverless infrastructure, we need to start by storing our credentials in Prefect Cloud, which we'll do by making a block.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#creating-a-credentials-block","title":"Creating a Credentials block","text":"AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Navigate to the blocks page, click create new block, and select AWS Credentials for the type.</p> <p>For use in a push work pool, region, access key, and access key secret must be set.</p> <p>Provide any other optional information and create your block.</p> <p>Navigate to the blocks page and click the \"+\" at the top to create a new block. Find the Azure Container Instance Credentials block and click \"Add +\".</p> <p>Locate the client ID and tenant ID on your app registration and use the client secret you saved earlier. Be sure to use the value of the secret, not the secret ID!</p> <p>Provide any other optional information and click \"Create\".</p> <p>Navigate to the blocks page, click create new block, and select GCP Credentials for the type.</p> <p>For use in a push work pool, this block must have the contents of the JSON key stored in the Service Account Info field, as such:</p> <p></p> <p>Provide any other optional information and create your block.</p> <p>Navigate to the blocks page, click create new block, and select Modal Credentials for the type.</p> <p>For use in a push work pool, this block must have the token ID and token secret stored in the Token ID and Token Secret fields, respectively.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#creating-a-push-work-pool","title":"Creating a push work pool","text":"<p>Now navigate to the work pools page. Click Create to start configuring your push work pool by selecting a push option in the infrastructure type step.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the AWS Credentials field.  This will allow Prefect Cloud to securely interact with your ECS cluster.</p> <p>Fill in the subscription ID and resource group name from the resource group you created. Add the Azure Container Instance Credentials block you created in the step above. </p> <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the GCP Credentials field.  This will allow Prefect Cloud to securely interact with your GCP project.</p> <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the Modal Credentials field.  This will allow Prefect Cloud to securely interact with your Modal account.</p> <p>Create your pool and you are ready to deploy flows to your Push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#deployment","title":"Deployment","text":"<p>Deployment details are described in the deployments concept section. Your deployment needs to be configured to send flow runs to our push work pool. For example, if you create a deployment through the interactive command line experience, choose the work pool you just created. If you are deploying an existing <code>prefect.yaml</code> file, the deployment would contain:</p> <pre><code>  work_pool:\n    name: my-push-pool\n</code></pre> <p>Deploying your flow to the <code>my-push-pool</code> work pool will ensure that runs that are ready for execution will be submitted immediately, without the need for a worker to poll for them.</p> <p>Serverless infrastructure may require a certain image architecture</p> <p>Note that serverless infrastructure may assume a certain Docker image architecture; for example, Google Cloud Run will fail to run images built with <code>linux/arm64</code> architecture. If using Prefect to build your image, you can change the image architecture through the <code>platform</code> keyword (e.g., <code>platform=\"linux/amd64\"</code>).</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#putting-it-all-together","title":"Putting it all together","text":"<p>With your deployment created, navigate to its detail page and create a new flow run. You'll see the flow start running without ever having to poll the work pool, because Prefect Cloud securely connected to your serverless infrastructure, created a job, ran the job, and began reporting on its execution.</p> <p></p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#next-steps","title":"Next steps","text":"<p>Learn more about workers and work pools in the Prefect concept documentation.</p> <p>Learn about installing dependencies at runtime or baking them into your Docker image in the Deploying Flows to Work Pools and Workers guide.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/serverless-workers/","title":"Run Deployments on Serverless Infrastructure with Prefect Workers","text":"<p>Prefect provides hybrid work pools for workers to run flows on the serverless platforms of major cloud providers. The following options are available:</p> <ul> <li>AWS Elastic Container Service (ECS)</li> <li>Azure Container Instances (ACI)</li> <li>Google Cloud Run</li> <li>Google Cloud Run V2</li> <li>Google Vertex AI</li> </ul> <p></p> <ul> <li>Create a work pool that sends work to your chosen serverless infrastructure</li> <li>Deploy a flow to that work pool</li> <li>Start a worker in your serverless cloud provider that will poll its matched work pool for scheduled runs</li> <li>Schedule a deployment run that a worker will pick up from the work pool and run on your serverless infrastructure</li> </ul> <p>Push work pools don't require a worker</p> <p>Options for push work pool versions of AWS ECS, Azure Container Instances, and Google Cloud Run that do not require a worker are available with Prefect Cloud. These push work pool options require connection configuration information to be stored on Prefect Cloud. Read more in the Serverless Push Work Pool Guide.</p> <p>This is a brief overview of the options to run workflows on serverless infrastructure. For in-depth guides, see the Prefect integration libraries:</p> <ul> <li>AWS ECS guide in the <code>prefect-aws</code> docs</li> <li>Azure Container Instances guide</li> <li>Google Cloud Run guide in the <code>prefect-gcp</code> docs.</li> <li>For Google Vertex AI, follow the Cloud Run guide, substituting Google Vertex AI where Google Cloud Run is mentioned.</li> </ul> <p>Choosing between Google Cloud Run and Google Vertex AI</p> <p>Google Vertex AI is well-suited for machine learning model training applications in which GPUs or TPUs and high resource levels are desired.</p>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/serverless-workers/#steps","title":"Steps","text":"<ol> <li>Make sure you have an user or service account on your chosen cloud provider with the necessary permissions to run serverless jobs</li> <li>Create the appropriate serverless work pool that uses a worker in the Prefect UI</li> <li>Create a deployment that references the work pool</li> <li>Start a worker in your chose serverless cloud provider infrastructure</li> <li>Run the deployment</li> </ol>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/serverless-workers/#next-steps","title":"Next steps","text":"<p>Options for push versions on AWS ECS, Azure Container Instances, and Google Cloud Run work pools that do not require a worker are available with Prefect Cloud. Read more in the Serverless Push Work Pool Guide.</p> <p>Learn more about workers and work pools in the Prefect concept documentation.</p> <p>Learn about installing dependencies at runtime or baking them into your Docker image in the Deploying Flows to Work Pools and Workers guide.</p>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/storage-guide/","title":"Where to Store Your Flow Code","text":"<p>When a deployment is run, the execution environment needs access to the flow code. Flow code is not stored in a Prefect server instance or in Prefect Cloud.</p> <p>You have several flow code storage options.</p> <p>This guide focusses on deployments created with the interactive CLI experience or a prefect.yaml file. If you'd like to create your deployments using Python code, see the discussion of flow code storage in the <code>.deploy</code> section of Deploying Flows to Work pools and Workers guide.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-1-git-based-storage","title":"Option 1: Git-based storage","text":"<p>Git-based version control platforms are popular locations for code storage.  They provide redundancy, version control, and easier collaboration.</p> <p>GitHub is the most popular cloud-based repository hosting provider.  GitLab and Bitbucket are other popular options.  Prefect supports each of these platforms.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#creating-a-deployment-with-git-based-storage","title":"Creating a deployment with git-based storage","text":"<p>Run <code>prefect deploy</code> from the root directory of the git repository and create a new deployment. You will see a series of prompts. Select that you want to create a new deployment, select the flow code entrypoint, and name your deployment.</p> <p>Prefect detects that you are in a git repository and asks if you want to store your flow code in a git repository. Select \"y\" and you will be prompted to confirm the URL of your git repository and the branch name, as in the example below:</p> <pre><code>? Your Prefect workers will need access to this flow's code in order to run it. \nWould you like your workers to pull your flow code from its remote repository when running this flow? [y/n] (y): \n? Is https://github.com/my_username/my_repo.git the correct URL to pull your flow code from? [y/n] (y): \n? Is main the correct branch to pull your flow code from? [y/n] (y): \n? Is this a private repository? [y/n]: y\n</code></pre> <p>In this example, the git repository is hosted on GitHub. If you are using Bitbucket or GitLab, the URL will match your provider. If the repository is public, enter \"n\" and you are on your way.</p> <p>If the repository is private, you can enter a token to access your private repository. This token will be saved in an encrypted Prefect Secret block.</p> <pre><code>? Please enter a token that can be used to access your private repository. This token will be saved as a Secret block via the Prefect API: \"123_abc_this_is_my_token\"\n</code></pre> <p>Verify that you have a new Secret block in your active workspace named in the format \"deployment-my-deployment-my-flow-name-repo-token\".</p> <p>Creating access tokens differs for each provider.</p> GitHubBitbucketGitLab <p>We recommend using HTTPS with fine-grained Personal Access Tokens so that you can limit access by repository.  See the GitHub docs for Personal Access Tokens (PATs).</p> <p>Under Your Profile-&gt;Developer Settings-&gt;Personal access tokens-&gt;Fine-grained token choose Generate New Token and fill in the required fields.  Under Repository access choose Only select repositories and grant the token permissions for Contents.</p> <p>We recommend using HTTPS with Repository, Project, or Workspace Access Tokens. </p> <p>You can create a Repository Access Token with Scopes-&gt;Repositories-&gt;Read.</p> <p>Bitbucket requires you prepend the token string with <code>x-token-auth:</code> So the full string looks like <code>x-token-auth:abc_123_this_is_my_token</code>. </p> <p>We recommend using HTTPS with Project Access Tokens.</p> <p>In your repository in the GitLab UI, select Settings-&gt;Repository-&gt;Project Access Tokens and check read_repository under Select scopes.</p> <p>If you want to configure a Secret block ahead of time, create the block via code or the Prefect UI and reference it in your <code>prefect.yaml</code> file.</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://gitlab.com/org/my-private-repo.git\n        access_token: \"{{ prefect.blocks.secret.my-block-name }}\"\n</code></pre> <p>Alternatively, you can create a Credentials block ahead of time and reference it in the <code>prefect.yaml</code> pull step.</p> GitHubBitbucketGitLab <ol> <li>Install the Prefect-Github library with <code>pip install -U prefect-github</code></li> <li>Register the blocks in that library to make them available on the server with <code>prefect block register -m prefect_github</code>.</li> <li>Create a GitHub Credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-block-name }}\"\n</code></pre> <ol> <li>Install the relevant library with <code>pip install -U prefect-bitbucket</code></li> <li>Register the blocks in that library with <code>prefect block register -m prefect_bitbucket</code> </li> <li>Create a Bitbucket credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://bitbucket.org/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.bitbucket-credentials.my-block-name }}\"\n</code></pre> <ol> <li>Install the relevant library with <code>pip install -U prefect-gitlab</code></li> <li>Register the blocks in that library with <code>prefect block register -m prefect_gitlab</code> </li> <li>Create a GitLab credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://gitlab.com/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.gitlab-credentials.my-block-name }}\"\n</code></pre> <p>Push your code</p> <p>When you make a change to your code, Prefect does not push your code to your git-based version control platform. You need to push your code manually or as part of your CI/CD pipeline. This design decision is an intentional one to avoid confusion about the git history and push process.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-2-docker-based-storage","title":"Option 2: Docker-based storage","text":"<p>Another popular way to store your flow code is to include it in a Docker image.  All work pool options except Process and Prefect Managed work pools allow you to bake your code into a Docker image.</p> <ol> <li>Run <code>prefect init</code> in the root of your repository and choose <code>docker</code> for the project name and answer the prompts to create a <code>prefect.yaml</code> file with a build step that will create a Docker image with the flow code built in. See the Workers and Work Pools page of the tutorial for more info.</li> <li>Run <code>prefect deploy</code> from the root of your repository to create a deployment.</li> <li>When a deployment runs the worker pulls the Docker image and spins up a container.</li> <li>The flow code baked into the image runs inside the container.</li> </ol> <p>CI/CD may not require push or pull steps</p> <p>You don't need push or pull steps in the <code>prefect.yaml</code> file if using CI/CD to build a Docker image outside of Prefect. Instead, the work pool can reference the image directly.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-3-cloud-provider-storage","title":"Option 3: Cloud-provider storage","text":"<p>You can store your code in an AWS S3 bucket, Azure Blob Storage container, or GCP GCS bucket and specify the destination directly in the <code>push</code> and <code>pull</code> steps of your <code>prefect.yaml</code> file.</p> <p>To create a templated <code>prefect.yaml</code> file run <code>prefect init</code> and select the recipe for the applicable cloud-provider storage. Below are the recipe options and the relevant portions of the <code>prefect.yaml</code> file.</p> AWS S3 bucketAzure Blob Storage containerGCP GCS bucket <p>Choose <code>s3Bucket</code> as the recipe and enter the bucket name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_aws.deployments.steps.push_to_s3:\n    id: push_code\n    requires: prefect-aws&gt;=0.3.4\n    bucket: my-bucket\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.aws-credentials.my-credentials-block }}\" # if private\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_aws.deployments.steps.pull_from_s3:\n    id: pull_code\n    requires: prefect-aws&gt;=0.3.4\n    bucket: '{{ push_code.bucket }}'\n    folder: '{{ push_code.folder }}'\n    credentials: \"{{ prefect.blocks.aws-credentials.my-credentials-block }}\" # if private \n</code></pre> <p>If the bucket requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-AWS library with <code>pip install -U prefect-aws</code></li> <li>Register the blocks in Prefect-AWS with <code>prefect block register -m prefect_aws</code> </li> <li>Create a user with a role with read and write permissions to access the bucket. If using the UI, create an access key pair with IAM-&gt;Users-&gt;Security credentials-&gt;Access keys-&gt;Create access key. Choose Use case-&gt;Other and then copy the Access key and Secret access key values.</li> <li>Create an AWS Credentials block via code or the Prefect UI. In addition to the block name, most users will fill in the AWS Access Key ID and AWS Access Key Secret fields.</li> <li>Reference the block as shown in the push and pull steps </li> </ol> <p>Choose <code>azure</code> as the recipe and enter the container name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_azure.deployments.steps.push_to_azure_blob_storage:\n    id: push_code\n    requires: prefect-azure&gt;=0.2.8\n    container: my-prefect-azure-container\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}\" # if private\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n    id: pull_code\n    requires: prefect-azure&gt;=0.2.8\n    container: '{{ push_code.container }}'\n    folder: '{{ push_code.folder }}'\n    credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}\" # if private\n</code></pre> <p>If the blob requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-Azure library with <code>pip install -U prefect-azure</code></li> <li>Register the blocks in Prefect-Azure with <code>prefect block register -m prefect_azure</code> </li> <li>Create an access key for a role with sufficient (read and write) permissions to access the blob. A connection string that will contain all needed information can be created in the UI under Storage Account-&gt;Access keys.</li> <li>Create an Azure Blob Storage Credentials block via code or the Prefect UI. Enter a name for the block and paste the connection string into the Connection String field.</li> <li>Reference the block as shown in the push and pull steps above. </li> </ol> <p>Choose `gcs`` as the recipe and enter the bucket name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_gcp.deployment.steps.push_to_gcs:\n    id: push_code\n    requires: prefect-gcp&gt;=0.4.3\n    bucket: my-bucket\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.gcp-credentials.my-credentials-block }}\" # if private \n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_gcp.deployment.steps.pull_from_gcs:\n    id: pull_code\n    requires: prefect-gcp&gt;=0.4.3\n    bucket: '{{ push_code.bucket }}'\n    folder: '{{ pull_code.folder }}'\n    credentials: \"{{ prefect.blocks.gcp-credentials.my-credentials-block }}\" # if private \n</code></pre> <p>If the bucket requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-GCP library with <code>pip install -U prefect-gcp</code></li> <li>Register the blocks in Prefect-GCP with <code>prefect block register -m prefect_gcp</code> </li> <li>Create a service account in GCP for a role with read and write permissions to access the bucket contents. If using the GCP  console, go to IAM &amp; Admin-&gt;Service accounts-&gt;Create service account. After choosing a role with the required permissions, see your service account and click on the three dot menu in the Actions column. Select Manage Keys-&gt;ADD KEY-&gt;Create new key-&gt;JSON. Download the JSON file.</li> <li>Create a GCP Credentials block via code or the Prefect UI. Enter a name for the block and paste the entire contents of the JSON key file into the Service Account Info field.</li> <li>Reference the block as shown in the push and pull steps above. </li> </ol> <p>Another option for authentication is for the worker to have access to the storage location at runtime via SSH keys.</p> <p>Alternatively, you can inject environment variables into your deployment like this example that uses an environment variable named <code>CUSTOM_FOLDER</code>:</p> <pre><code> push:\n    - prefect_gcp.deployment.steps.push_to_gcs:\n        id: push_code\n        requires: prefect-gcp&gt;=0.4.3\n        bucket: my-bucket\n        folder: '{{ $CUSTOM_FOLDER }}'\n</code></pre>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#include-or-exclude-files-from-storage","title":"Include or exclude files from storage","text":"<p>By default, Prefect uploads all files in the current folder to the configured storage location when you create a deployment.</p> <p>When using a git repository, Docker image, or cloud-provider storage location, you may want to exclude certain files or directories.</p> <ul> <li>If you are familiar with git you are likely familiar with the <code>.gitignore</code> file.</li> <li>If you are familiar with Docker you are likely familiar with the <code>.dockerignore</code> file.</li> <li>For cloud-provider storage the <code>.prefectignore</code> file serves the same purpose and follows a similar syntax as those files. So an entry of <code>*.pyc</code> will exclude all <code>.pyc</code> files from upload.</li> </ul>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#other-code-storage-creation-methods","title":"Other code storage creation methods","text":"<p>In earlier versions of Prefect storage blocks were the recommended way to store flow code. Storage blocks are deprecated.</p> <p>As shown above, repositories can be referenced directly through interactive prompts with <code>prefect deploy</code> or in a <code>prefect.yaml</code>. When authentication is needed, Secret or Credential blocks can be referenced, and in some cases, created automatically through interactive deployment creation prompts.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#conclusion","title":"Conclusion","text":"<p>You've seen options for storing your flow code. For easier version control, we recommend using Docker-based storage or git-based storage for your production deployments.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"integrations/","title":"Integrations","text":"<p>You can install the following integrations of pre-built tasks, flows, blocks and more as PyPI packages:</p> <p>                         Alert                     </p> <p>                     Maintained by Khuyen Tran </p> <p>                         AWS                     </p> <p>                     Maintained by Prefect </p> <p>                         Azure                     </p> <p>                     Maintained by Prefect </p> <p>                         Bitbucket                     </p> <p>                     Maintained by Prefect </p> <p>                         Coiled                     </p> <p>                     Maintained by Coiled </p> <p>                         CubeJS                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Dask                     </p> <p>                     Maintained by Prefect </p> <p>                         Databricks                     </p> <p>                     Maintained by Prefect </p> <p>                         dbt                     </p> <p>                     Maintained by Prefect </p> <p>                         Docker                     </p> <p>                     Maintained by Prefect </p> <p>                         Earthdata                     </p> <p>                     Maintained by Giorgio Basile </p> <p>                         Email                     </p> <p>                     Maintained by Prefect </p> <p>                         Fivetran                     </p> <p>                     Maintained by Fivetran </p> <p>                         Fugue                     </p> <p>                     Maintained by The Fugue Development Team </p> <p>                         GCP                     </p> <p>                     Maintained by Prefect </p> <p>                         GitHub                     </p> <p>                     Maintained by Prefect </p> <p>                         GitLab                     </p> <p>                     Maintained by Prefect </p> <p>                         Google Sheets                     </p> <p>                     Maintained by Stefano Cascavilla </p> <p>                         HashiCorp Vault                     </p> <p>                     Maintained by Pavel Chekin </p> <p>                         Kubernetes                     </p> <p>                     Maintained by Prefect </p> <p>                         KV                     </p> <p>                     Maintained by Zanie Blue </p> <p>                         MetricFlow                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Planetary Computer                     </p> <p>                     Maintained by Giorgio Basile </p> <p>                         Ray                     </p> <p>                     Maintained by Prefect </p> <p>                         Shell                     </p> <p>                     Maintained by Prefect </p> <p>                         Sifflet                     </p> <p>                     Maintained by Sifflet and Alessandro Lollo </p> <p>                         Slack                     </p> <p>                     Maintained by Prefect </p> <p>                         Snowflake                     </p> <p>                     Maintained by Prefect </p> <p>                         Soda Cloud                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Soda Core                     </p> <p>                     Maintained by Soda and Alessandro Lollo </p> <p>                         Spark on Kubernetes                     </p> <p>                     Maintained by Manoj Babu Katragadda </p> <p>                         SQLAlchemy                     </p> <p>                     Maintained by Prefect </p> <p>                         Stitch                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Transform                     </p> <p>                     Maintained by Alessandro Lollo </p>","tags":["tasks","flows","blocks","collections","task library","integrations","Alert","AWS","Azure","Bitbucket","Coiled","CubeJS","Dask","Databricks","dbt","Docker","Earthdata","Email","Fivetran","Fugue","GCP","GitHub","GitLab","Google Sheets","HashiCorp Vault","Kubernetes","KV","MetricFlow","Planetary Computer","Ray","Shell","Sifflet","Slack","Snowflake","Soda Cloud","Soda Core","Spark on Kubernetes","SQLAlchemy","Stitch","Transform"],"boost":2},{"location":"integrations/contribute/","title":"Contribute","text":"<p>We welcome contributors! You can help contribute blocks and integrations by following these steps.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contributing-blocks","title":"Contributing Blocks","text":"<p>Building your own custom block is simple!</p> <ol> <li>Subclass from <code>Block</code>.</li> <li>Add a description alongside an <code>Attributes</code> and <code>Example</code> section in the docstring.</li> <li>Set a <code>_logo_url</code> to point to a relevant image.</li> <li>Create the <code>pydantic.Field</code>s of the block with a type annotation, <code>default</code> or <code>default_factory</code>, and a short description about the field.</li> <li>Define the methods of the block.</li> </ol> <p>For example, this is how the Secret block is implemented: <pre><code>from pydantic import Field, SecretStr\nfrom prefect.blocks.core import Block\n\nclass Secret(Block):\n    \"\"\"\n    A block that represents a secret value. The value stored in this block will be obfuscated when\n    this block is logged or shown in the UI.\n\n    Attributes:\n        value: A string value that should be kept secret.\n\n    Example:\n        ```python\n        from prefect.blocks.system import Secret\n        secret_block = Secret.load(\"BLOCK_NAME\")\n\n        # Access the stored secret\n        secret_block.get()\n        ```\n    \"\"\"\n\n    _logo_url = \"https://example.com/logo.png\"\n\n    value: SecretStr = Field(\n        default=..., description=\"A string value that should be kept secret.\"\n    )  # ... indicates it's a required field\n\n    def get(self):\n        return self.value.get_secret_value()\n</code></pre></p> <p>To view in Prefect Cloud or the Prefect server UI, register the block.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contributing-integrations","title":"Contributing Integrations","text":"<p>Anyone can create and share a Prefect Integration and we encourage anyone interested in creating an integration to do so!</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#generate-a-project","title":"Generate a project","text":"<p>To help you get started with your integration, we've created a template that gives the tools you need to create and publish your integration.</p> <p>Use the Prefect Integration template to get started creating an integration with a bootstrapped project!</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#list-a-project-in-the-integrations-catalog","title":"List a project in the Integrations Catalog","text":"<p>To list your integration in the Prefect Integrations Catalog, submit a PR to the Prefect repository adding a file to the <code>docs/integrations/catalog</code> directory with details about your integration. Please use <code>TEMPLATE.yaml</code> in that folder as a guide.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contribute-fixes-or-enhancements-to-integrations","title":"Contribute fixes or enhancements to Integrations","text":"<p>If you'd like to help contribute to fix an issue or add a feature to any of our Integrations, please propose changes through a pull request from a fork of the repository.</p> <ol> <li>Fork the repository</li> <li>Clone the forked repository</li> <li>Install the repository and its dependencies: <pre><code>pip install -e \".[dev]\"\n</code></pre></li> <li>Make desired changes</li> <li>Add tests</li> <li>Insert an entry to the Integration's CHANGELOG.md</li> <li>Install <code>pre-commit</code> to perform quality checks prior to commit: <pre><code>pre-commit install\n</code></pre></li> <li><code>git commit</code>, <code>git push</code>, and create a pull request</li> </ol>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/usage/","title":"Using Integrations","text":"","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#installing-an-integration","title":"Installing an Integration","text":"<p>Install the Integration via <code>pip</code>.</p> <p>For example, to use <code>prefect-aws</code>:</p> <pre><code>pip install prefect-aws\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#registering-blocks-from-an-integration","title":"Registering Blocks from an Integration","text":"<p>Once the Prefect Integration is installed, register the blocks within the integration to view them in the Prefect Cloud UI:</p> <p>For example, to register the blocks available in <code>prefect-aws</code>:</p> <pre><code>prefect block register -m prefect_aws\n</code></pre> <p>Updating blocks from an integrations</p> <p>If you install an updated Prefect integration that adds fields to a block type, you will need to re-register that block type.</p> <p>Loading a block in code</p> <p>To use the <code>load</code> method on a Block, you must already have a block document saved either through code or through the Prefect UI.</p> <p>Learn more about Blocks here!</p>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#using-tasks-and-flows-from-an-integration","title":"Using Tasks and Flows from an Integration","text":"<p>Integrations also contain pre-built tasks and flows that can be imported and called within your code.</p> <p>As an example, to read a secret from AWS Secrets Manager with the <code>read_secret</code> task:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import read_secret\n\n@flow\ndef connect_to_database():\n    aws_credentials = AwsCredentials.load(\"MY_BLOCK_NAME\")\n    secret_value = read_secret(\n        secret_name=\"db_password\",\n        aws_credentials=aws_credentials\n    )\n\n    # Use secret_value to connect to a database\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#customizing-tasks-and-flows-from-an-integration","title":"Customizing Tasks and Flows from an Integration","text":"<p>To customize the settings of a task or flow pre-configured in a collection, use <code>with_options</code>:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\ncustom_run_dbt_cloud_job = trigger_dbt_cloud_job_run_and_wait_for_completion.with_options(\n    name=\"Run My DBT Cloud Job\",\n    retries=2,\n    retry_delay_seconds=10\n)\n\n@flow\ndef run_dbt_job_flow():\n    run_result = custom_run_dbt_cloud_job(\n        dbt_cloud_credentials=DbtCloudCredentials.load(\"my-dbt-cloud-credentials\"),\n        job_id=1\n    )\n\nrun_dbt_job_flow()\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#recipes-and-tutorials","title":"Recipes and Tutorials","text":"<p>To learn more about how to use Integrations, check out Prefect recipes on GitHub. These recipes provide examples of how Integrations can be used in various scenarios.</p>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/prefect-aws/","title":"prefect-aws","text":"<p>The prefect-aws library makes it easy to leverage the capabilities of AWS in your workflows. For example, you can retrieve secrets using AWS Secrets Manager, read and write objects with AWS S3, and deploy your flows on AWS ECS.</p>"},{"location":"integrations/prefect-aws/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-aws/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>An AWS account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-aws/#install-prefect-aws","title":"Install prefect-aws","text":"<pre><code>pip install -U prefect-aws\n</code></pre>"},{"location":"integrations/prefect-aws/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-aws module to make them available for use.</p> <pre><code>prefect block register -m prefect_aws\n</code></pre>"},{"location":"integrations/prefect-aws/#examples","title":"Examples","text":""},{"location":"integrations/prefect-aws/#run-flows-on-aws-ecs","title":"Run flows on AWS ECS","text":"<p>Run flows on AWS Elastic Container Service (ECS) to dynamically scale your infrastructure.</p> <p>See the ECS guide for a walkthrough of using ECS in a hybrid work pool.</p> <p>If you're using Prefect Cloud, ECS push work pools provide all the benefits of ECS with a quick setup and no worker needed.</p> <p>In the examples below, you create blocks with Python code. Alternatively, each block can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-aws/#save-credentials-to-an-aws-credentials-block","title":"Save credentials to an AWS Credentials block","text":"<p>Use of most AWS services requires an authenticated session. Prefect makes it simple to provide credentials via a AWS Credentials block.</p> <p>Steps:</p> <ol> <li>Refer to the AWS Configuration documentation to retrieve your access key ID and secret access key.</li> <li>Copy the access key ID and secret access key.</li> <li>Create an <code>AWSCredenitals</code> block in the Prefect UI or use a Python script like the one below.</li> </ol> <pre><code>from prefect_aws import AwsCredentials\n\n\nAwsCredentials(\n    aws_access_key_id=\"PLACEHOLDER\",\n    aws_secret_access_key=\"PLACEHOLDER\",\n    aws_session_token=None,  # replace this with token if necessary\n    region_name=\"us-east-2\"\n).save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Prefect is using the Boto3 library under the hood. To find credentials for authentication, any data not provided to the block are sourced at runtime in the order shown in the Boto3 docs. Prefect creates the session object using the values in the block and then, any missing values follow the sequence in the Boto3 docs.</p> <p>See an example of using the <code>AwsCredentials</code> block with AWS Secrets Manager with third-party services without storing credentials in the block itself in this guide.</p> <p>Here's how to load the saved credentials:</p> <pre><code>from prefect_aws import AwsCredentials\n\n\nAwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>The AWS Credentials block is often nested within other blocks, such as <code>S3Bucket</code> or <code>AwsSecret</code>, and provides authentication for those services.</p>"},{"location":"integrations/prefect-aws/#read-and-write-files-to-aws-s3","title":"Read and write files to AWS S3","text":"<p>Upload a file to an AWS S3 bucket and download the same file under a different file name. The following code assumes that the bucket already exists:</p> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials, S3Bucket\n\n\n@flow\ndef s3_flow():\n    # create a dummy file to upload\n    file_path = Path(\"test-example.txt\")\n    file_path.write_text(\"Hello, Prefect!\")\n\n    aws_credentials = AwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    s3_bucket = S3Bucket(\n        bucket_name=\"BUCKET-NAME-PLACEHOLDER\",\n        credentials=aws_credentials\n    )\n\n    s3_bucket_path = s3_bucket.upload_from_path(file_path)\n    downloaded_file_path = s3_bucket.download_object_to_path(\n        s3_bucket_path, \"downloaded-test-example.txt\"\n    )\n    return downloaded_file_path.read_text()\n\n\nif __name__ == \"__main__\":\n    s3_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/#access-secrets-with-aws-secrets-manager","title":"Access secrets with AWS Secrets Manager","text":"<p>Write a secret to AWS Secrets Manager, read the secret data, delete the secret, and return the secret data.</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials, AwsSecret\n\n\n@flow\ndef secrets_manager_flow():\n    aws_credentials = AwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    aws_secret = AwsSecret(secret_name=\"test-example\", aws_credentials=aws_credentials)\n    aws_secret.write_secret(secret_data=b\"Hello, Prefect!\")\n    secret_data = aws_secret.read_secret()\n    aws_secret.delete_secret()\n    return secret_data\n\n\nif __name__ == \"__main__\":\n    secrets_manager_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/#resources","title":"Resources","text":"<p>For assistance using AWS, consult the AWS documentation and, in particular, the Boto3 documentation.</p> <p>Refer to the prefect-aws API documentation linked in the sidebar to explore all the capabilities of the prefect-aws library.</p>"},{"location":"integrations/prefect-aws/batch/","title":"Batch","text":""},{"location":"integrations/prefect-aws/batch/#prefect_aws.batch","title":"<code>prefect_aws.batch</code>","text":"<p>Tasks for interacting with AWS Batch</p>"},{"location":"integrations/prefect-aws/batch/#prefect_aws.batch.batch_submit","title":"<code>batch_submit</code>  <code>async</code>","text":"<p>Submit a job to the AWS Batch job service.</p> <p>Parameters:</p> Name Type Description Default <code>job_name</code> <code>str</code> <p>The AWS batch job name.</p> required <code>job_queue</code> <code>str</code> <p>Name of the AWS batch job queue.</p> required <code>job_definition</code> <code>str</code> <p>The AWS batch job definition.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>**batch_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to the boto3 <code>submit_job</code> function. See the documentation for submit_job for more details.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The id corresponding to the job.</p> Example <p>Submits a job to batch.</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.batch import batch_submit\n\n\n@flow\ndef example_batch_submit_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    job_id = batch_submit(\n        \"job_name\",\n        \"job_queue\",\n        \"job_definition\",\n        aws_credentials\n    )\n    return job_id\n\nexample_batch_submit_flow()\n</code></pre> Source code in <code>prefect_aws/batch.py</code> <pre><code>@task\nasync def batch_submit(\n    job_name: str,\n    job_queue: str,\n    job_definition: str,\n    aws_credentials: AwsCredentials,\n    **batch_kwargs: Optional[Dict[str, Any]],\n) -&gt; str:\n    \"\"\"\n    Submit a job to the AWS Batch job service.\n\n    Args:\n        job_name: The AWS batch job name.\n        job_queue: Name of the AWS batch job queue.\n        job_definition: The AWS batch job definition.\n        aws_credentials: Credentials to use for authentication with AWS.\n        **batch_kwargs: Additional keyword arguments to pass to the boto3\n            `submit_job` function. See the documentation for\n            [submit_job](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/batch.html#Batch.Client.submit_job)\n            for more details.\n\n    Returns:\n        The id corresponding to the job.\n\n    Example:\n        Submits a job to batch.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.batch import batch_submit\n\n\n        @flow\n        def example_batch_submit_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            job_id = batch_submit(\n                \"job_name\",\n                \"job_queue\",\n                \"job_definition\",\n                aws_credentials\n            )\n            return job_id\n\n        example_batch_submit_flow()\n        ```\n\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Preparing to submit %s job to %s job queue\", job_name, job_queue)\n\n    batch_client = aws_credentials.get_boto3_session().client(\"batch\")\n\n    response = await run_sync_in_worker_thread(\n        batch_client.submit_job,\n        jobName=job_name,\n        jobQueue=job_queue,\n        jobDefinition=job_definition,\n        **batch_kwargs,\n    )\n    return response[\"jobId\"]\n</code></pre>"},{"location":"integrations/prefect-aws/client_waiter/","title":"Client Waiter","text":""},{"location":"integrations/prefect-aws/client_waiter/#prefect_aws.client_waiter","title":"<code>prefect_aws.client_waiter</code>","text":"<p>Task for waiting on a long-running AWS job</p>"},{"location":"integrations/prefect-aws/client_waiter/#prefect_aws.client_waiter.client_waiter","title":"<code>client_waiter</code>  <code>async</code>","text":"<p>Uses the underlying boto3 waiter functionality.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>str</code> <p>The AWS client on which to wait (e.g., 'client_wait', 'ec2', etc).</p> required <code>waiter_name</code> <code>str</code> <p>The name of the waiter to instantiate. You may also use a custom waiter name, if you supply an accompanying waiter definition dict.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>waiter_definition</code> <code>Optional[Dict[str, Any]]</code> <p>A valid custom waiter model, as a dict. Note that if you supply a custom definition, it is assumed that the provided 'waiter_name' is contained within the waiter definition dict.</p> <code>None</code> <code>**waiter_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Arguments to pass to the <code>waiter.wait(...)</code> method. Will depend upon the specific waiter being called.</p> <code>{}</code> Example <p>Run an ec2 waiter until instance_exists. <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.client_wait import client_waiter\n\n@flow\ndef example_client_wait_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n\n    waiter = client_waiter(\n        \"ec2\",\n        \"instance_exists\",\n        aws_credentials\n    )\n\n    return waiter\nexample_client_wait_flow()\n</code></pre></p> Source code in <code>prefect_aws/client_waiter.py</code> <pre><code>@task\nasync def client_waiter(\n    client: str,\n    waiter_name: str,\n    aws_credentials: AwsCredentials,\n    waiter_definition: Optional[Dict[str, Any]] = None,\n    **waiter_kwargs: Optional[Dict[str, Any]],\n):\n    \"\"\"\n    Uses the underlying boto3 waiter functionality.\n\n    Args:\n        client: The AWS client on which to wait (e.g., 'client_wait', 'ec2', etc).\n        waiter_name: The name of the waiter to instantiate.\n            You may also use a custom waiter name, if you supply\n            an accompanying waiter definition dict.\n        aws_credentials: Credentials to use for authentication with AWS.\n        waiter_definition: A valid custom waiter model, as a dict. Note that if\n            you supply a custom definition, it is assumed that the provided\n            'waiter_name' is contained within the waiter definition dict.\n        **waiter_kwargs: Arguments to pass to the `waiter.wait(...)` method. Will\n            depend upon the specific waiter being called.\n\n    Example:\n        Run an ec2 waiter until instance_exists.\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.client_wait import client_waiter\n\n        @flow\n        def example_client_wait_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n\n            waiter = client_waiter(\n                \"ec2\",\n                \"instance_exists\",\n                aws_credentials\n            )\n\n            return waiter\n        example_client_wait_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Waiting on %s job\", client)\n\n    boto_client = aws_credentials.get_boto3_session().client(client)\n\n    if waiter_definition is not None:\n        # Use user-provided waiter definition\n        waiter_model = WaiterModel(waiter_definition)\n        waiter = create_waiter_with_client(waiter_name, waiter_model, boto_client)\n    elif waiter_name in boto_client.waiter_names:\n        waiter = boto_client.get_waiter(waiter_name)\n    else:\n        raise ValueError(\n            f\"The waiter name, {waiter_name}, is not a valid boto waiter; \"\n            \"if using a custom waiter, you must provide a waiter definition\"\n        )\n\n    await run_sync_in_worker_thread(waiter.wait, **waiter_kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials","title":"<code>prefect_aws.credentials</code>","text":"<p>Module handling AWS credentials</p>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials","title":"<code>AwsCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with AWS. AWS authentication is handled via the <code>boto3</code> module. Refer to the boto3 docs for more info about the possible credential configurations.</p> Example <p>Load stored AWS credentials: <pre><code>from prefect_aws import AwsCredentials\n\naws_credentials_block = AwsCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class AwsCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with AWS. AWS authentication is\n    handled via the `boto3` module. Refer to the\n    [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)\n    for more info about the possible credential configurations.\n\n    Example:\n        Load stored AWS credentials:\n        ```python\n        from prefect_aws import AwsCredentials\n\n        aws_credentials_block = AwsCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"AWS Credentials\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials\"  # noqa\n\n    aws_access_key_id: Optional[str] = Field(\n        default=None,\n        description=\"A specific AWS access key ID.\",\n        title=\"AWS Access Key ID\",\n    )\n    aws_secret_access_key: Optional[SecretStr] = Field(\n        default=None,\n        description=\"A specific AWS secret access key.\",\n        title=\"AWS Access Key Secret\",\n    )\n    aws_session_token: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The session key for your AWS account. \"\n            \"This is only needed when you are using temporary credentials.\"\n        ),\n        title=\"AWS Session Token\",\n    )\n    profile_name: Optional[str] = Field(\n        default=None, description=\"The profile to use when creating your session.\"\n    )\n    region_name: Optional[str] = Field(\n        default=None,\n        description=\"The AWS Region where you want to create new connections.\",\n    )\n    aws_client_parameters: AwsClientParameters = Field(\n        default_factory=AwsClientParameters,\n        description=\"Extra parameters to initialize the Client.\",\n        title=\"AWS Client Parameters\",\n    )\n\n    class Config:\n        \"\"\"Config class for pydantic model.\"\"\"\n\n        arbitrary_types_allowed = True\n\n    def __hash__(self):\n        field_hashes = (\n            hash(self.aws_access_key_id),\n            hash(self.aws_secret_access_key),\n            hash(self.aws_session_token),\n            hash(self.profile_name),\n            hash(self.region_name),\n            hash(self.aws_client_parameters),\n        )\n        return hash(field_hashes)\n\n    def get_boto3_session(self) -&gt; boto3.Session:\n        \"\"\"\n        Returns an authenticated boto3 session that can be used to create clients\n        for AWS services\n\n        Example:\n            Create an S3 client from an authorized boto3 session:\n            ```python\n            aws_credentials = AwsCredentials(\n                aws_access_key_id = \"access_key_id\",\n                aws_secret_access_key = \"secret_access_key\"\n                )\n            s3_client = aws_credentials.get_boto3_session().client(\"s3\")\n            ```\n        \"\"\"\n\n        if self.aws_secret_access_key:\n            aws_secret_access_key = self.aws_secret_access_key.get_secret_value()\n        else:\n            aws_secret_access_key = None\n\n        return boto3.Session(\n            aws_access_key_id=self.aws_access_key_id,\n            aws_secret_access_key=aws_secret_access_key,\n            aws_session_token=self.aws_session_token,\n            profile_name=self.profile_name,\n            region_name=self.region_name,\n        )\n\n    def get_client(self, client_type: Union[str, ClientType]):\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The client's service name.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, ClientType):\n            client_type = client_type.value\n\n        return _get_client_cached(ctx=self, client_type=client_type)\n\n    def get_s3_client(self) -&gt; S3Client:\n        \"\"\"\n        Gets an authenticated S3 client.\n\n        Returns:\n            An authenticated S3 client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.S3)\n\n    def get_secrets_manager_client(self) -&gt; SecretsManagerClient:\n        \"\"\"\n        Gets an authenticated Secrets Manager client.\n\n        Returns:\n            An authenticated Secrets Manager client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.SECRETS_MANAGER)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.Config","title":"<code>Config</code>","text":"<p>Config class for pydantic model.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class Config:\n    \"\"\"Config class for pydantic model.\"\"\"\n\n    arbitrary_types_allowed = True\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_boto3_session","title":"<code>get_boto3_session</code>","text":"<p>Returns an authenticated boto3 session that can be used to create clients for AWS services</p> Example <p>Create an S3 client from an authorized boto3 session: <pre><code>aws_credentials = AwsCredentials(\n    aws_access_key_id = \"access_key_id\",\n    aws_secret_access_key = \"secret_access_key\"\n    )\ns3_client = aws_credentials.get_boto3_session().client(\"s3\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_boto3_session(self) -&gt; boto3.Session:\n    \"\"\"\n    Returns an authenticated boto3 session that can be used to create clients\n    for AWS services\n\n    Example:\n        Create an S3 client from an authorized boto3 session:\n        ```python\n        aws_credentials = AwsCredentials(\n            aws_access_key_id = \"access_key_id\",\n            aws_secret_access_key = \"secret_access_key\"\n            )\n        s3_client = aws_credentials.get_boto3_session().client(\"s3\")\n        ```\n    \"\"\"\n\n    if self.aws_secret_access_key:\n        aws_secret_access_key = self.aws_secret_access_key.get_secret_value()\n    else:\n        aws_secret_access_key = None\n\n    return boto3.Session(\n        aws_access_key_id=self.aws_access_key_id,\n        aws_secret_access_key=aws_secret_access_key,\n        aws_session_token=self.aws_session_token,\n        profile_name=self.profile_name,\n        region_name=self.region_name,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The client's service name.</p> required <p>Returns:</p> Type Description <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_client(self, client_type: Union[str, ClientType]):\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The client's service name.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, ClientType):\n        client_type = client_type.value\n\n    return _get_client_cached(ctx=self, client_type=client_type)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_s3_client","title":"<code>get_s3_client</code>","text":"<p>Gets an authenticated S3 client.</p> <p>Returns:</p> Type Description <code>S3Client</code> <p>An authenticated S3 client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_s3_client(self) -&gt; S3Client:\n    \"\"\"\n    Gets an authenticated S3 client.\n\n    Returns:\n        An authenticated S3 client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_secrets_manager_client","title":"<code>get_secrets_manager_client</code>","text":"<p>Gets an authenticated Secrets Manager client.</p> <p>Returns:</p> Type Description <code>SecretsManagerClient</code> <p>An authenticated Secrets Manager client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_secrets_manager_client(self) -&gt; SecretsManagerClient:\n    \"\"\"\n    Gets an authenticated Secrets Manager client.\n\n    Returns:\n        An authenticated Secrets Manager client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.SECRETS_MANAGER)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.ClientType","title":"<code>ClientType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>The supported boto3 clients.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class ClientType(Enum):\n    \"\"\"The supported boto3 clients.\"\"\"\n\n    S3 = \"s3\"\n    ECS = \"ecs\"\n    BATCH = \"batch\"\n    SECRETS_MANAGER = \"secretsmanager\"\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials","title":"<code>MinIOCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with MinIO. Refer to the MinIO docs for more info about the possible credential configurations.</p> <p>Attributes:</p> Name Type Description <code>minio_root_user</code> <code>str</code> <p>Admin or root user.</p> <code>minio_root_password</code> <code>SecretStr</code> <p>Admin or root password.</p> <code>region_name</code> <code>Optional[str]</code> <p>Location of server, e.g. \"us-east-1\".</p> Example <p>Load stored MinIO credentials: <pre><code>from prefect_aws import MinIOCredentials\n\nminio_credentials_block = MinIOCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class MinIOCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with MinIO. Refer to the\n    [MinIO docs](https://docs.min.io/docs/minio-server-configuration-guide.html)\n    for more info about the possible credential configurations.\n\n    Attributes:\n        minio_root_user: Admin or root user.\n        minio_root_password: Admin or root password.\n        region_name: Location of server, e.g. \"us-east-1\".\n\n    Example:\n        Load stored MinIO credentials:\n        ```python\n        from prefect_aws import MinIOCredentials\n\n        minio_credentials_block = MinIOCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/676cb17bcbdff601f97e0a02ff8bcb480e91ff40-250x250.png\"  # noqa\n    _block_type_name = \"MinIO Credentials\"\n    _description = (\n        \"Block used to manage authentication with MinIO. Refer to the MinIO \"\n        \"docs: https://docs.min.io/docs/minio-server-configuration-guide.html \"\n        \"for more info about the possible credential configurations.\"\n    )\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials\"  # noqa\n\n    minio_root_user: str = Field(default=..., description=\"Admin or root user.\")\n    minio_root_password: SecretStr = Field(\n        default=..., description=\"Admin or root password.\"\n    )\n    region_name: Optional[str] = Field(\n        default=None,\n        description=\"The AWS Region where you want to create new connections.\",\n    )\n    aws_client_parameters: AwsClientParameters = Field(\n        default_factory=AwsClientParameters,\n        description=\"Extra parameters to initialize the Client.\",\n    )\n\n    class Config:\n        \"\"\"Config class for pydantic model.\"\"\"\n\n        arbitrary_types_allowed = True\n\n    def __hash__(self):\n        return hash(\n            (\n                hash(self.minio_root_user),\n                hash(self.minio_root_password),\n                hash(self.region_name),\n                hash(frozenset(self.aws_client_parameters.dict().items())),\n            )\n        )\n\n    def get_boto3_session(self) -&gt; boto3.Session:\n        \"\"\"\n        Returns an authenticated boto3 session that can be used to create clients\n        and perform object operations on MinIO server.\n\n        Example:\n            Create an S3 client from an authorized boto3 session\n\n            ```python\n            minio_credentials = MinIOCredentials(\n                minio_root_user = \"minio_root_user\",\n                minio_root_password = \"minio_root_password\"\n            )\n            s3_client = minio_credentials.get_boto3_session().client(\n                service=\"s3\",\n                endpoint_url=\"http://localhost:9000\"\n            )\n            ```\n        \"\"\"\n\n        minio_root_password = (\n            self.minio_root_password.get_secret_value()\n            if self.minio_root_password\n            else None\n        )\n\n        return boto3.Session(\n            aws_access_key_id=self.minio_root_user,\n            aws_secret_access_key=minio_root_password,\n            region_name=self.region_name,\n        )\n\n    def get_client(self, client_type: Union[str, ClientType]):\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The client's service name.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, ClientType):\n            client_type = client_type.value\n\n        return _get_client_cached(ctx=self, client_type=client_type)\n\n    def get_s3_client(self) -&gt; S3Client:\n        \"\"\"\n        Gets an authenticated S3 client.\n\n        Returns:\n            An authenticated S3 client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.Config","title":"<code>Config</code>","text":"<p>Config class for pydantic model.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class Config:\n    \"\"\"Config class for pydantic model.\"\"\"\n\n    arbitrary_types_allowed = True\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_boto3_session","title":"<code>get_boto3_session</code>","text":"<p>Returns an authenticated boto3 session that can be used to create clients and perform object operations on MinIO server.</p> Example <p>Create an S3 client from an authorized boto3 session</p> <pre><code>minio_credentials = MinIOCredentials(\n    minio_root_user = \"minio_root_user\",\n    minio_root_password = \"minio_root_password\"\n)\ns3_client = minio_credentials.get_boto3_session().client(\n    service=\"s3\",\n    endpoint_url=\"http://localhost:9000\"\n)\n</code></pre> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_boto3_session(self) -&gt; boto3.Session:\n    \"\"\"\n    Returns an authenticated boto3 session that can be used to create clients\n    and perform object operations on MinIO server.\n\n    Example:\n        Create an S3 client from an authorized boto3 session\n\n        ```python\n        minio_credentials = MinIOCredentials(\n            minio_root_user = \"minio_root_user\",\n            minio_root_password = \"minio_root_password\"\n        )\n        s3_client = minio_credentials.get_boto3_session().client(\n            service=\"s3\",\n            endpoint_url=\"http://localhost:9000\"\n        )\n        ```\n    \"\"\"\n\n    minio_root_password = (\n        self.minio_root_password.get_secret_value()\n        if self.minio_root_password\n        else None\n    )\n\n    return boto3.Session(\n        aws_access_key_id=self.minio_root_user,\n        aws_secret_access_key=minio_root_password,\n        region_name=self.region_name,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The client's service name.</p> required <p>Returns:</p> Type Description <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_client(self, client_type: Union[str, ClientType]):\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The client's service name.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, ClientType):\n        client_type = client_type.value\n\n    return _get_client_cached(ctx=self, client_type=client_type)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_s3_client","title":"<code>get_s3_client</code>","text":"<p>Gets an authenticated S3 client.</p> <p>Returns:</p> Type Description <code>S3Client</code> <p>An authenticated S3 client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_s3_client(self) -&gt; S3Client:\n    \"\"\"\n    Gets an authenticated S3 client.\n\n    Returns:\n        An authenticated S3 client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/","title":"ECS (deprecated)","text":""},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs","title":"<code>prefect_aws.ecs</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the ECS worker, which offers enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with the Amazon Elastic Container Service.</p> <p>Examples:</p> <pre><code>Run a task using ECS Fargate\n```python\nECSTask(command=[\"echo\", \"hello world\"]).run()\n```\n\nRun a task using ECS Fargate with a spot container instance\n```python\nECSTask(command=[\"echo\", \"hello world\"], launch_type=\"FARGATE_SPOT\").run()\n```\n\nRun a task using ECS with an EC2 container instance\n```python\nECSTask(command=[\"echo\", \"hello world\"], launch_type=\"EC2\").run()\n```\n\nRun a task on a specific VPC using ECS Fargate\n```python\nECSTask(command=[\"echo\", \"hello world\"], vpc_id=\"vpc-01abcdf123456789a\").run()\n```\n\nRun a task and stream the container's output to the local terminal. Note an\nexecution role must be provided with permissions: logs:CreateLogStream,\nlogs:CreateLogGroup, and logs:PutLogEvents.\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    stream_output=True,\n    execution_role_arn=\"...\"\n)\n```\n\nRun a task using an existing task definition as a base\n```python\nECSTask(command=[\"echo\", \"hello world\"], task_definition_arn=\"arn:aws:ecs:...\")\n```\n\nRun a task with a specific image\n```python\nECSTask(command=[\"echo\", \"hello world\"], image=\"alpine:latest\")\n```\n\nRun a task with custom memory and CPU requirements\n```python\nECSTask(command=[\"echo\", \"hello world\"], memory=4096, cpu=2048)\n```\n\nRun a task with custom environment variables\n```python\nECSTask(command=[\"echo\", \"hello $PLANET\"], env={\"PLANET\": \"earth\"})\n```\n\nRun a task in a specific ECS cluster\n```python\nECSTask(command=[\"echo\", \"hello world\"], cluster=\"my-cluster-name\")\n```\n\nRun a task with custom VPC subnets\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    task_customizations=[\n        {\n            \"op\": \"add\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/subnets\",\n            \"value\": [\"subnet-80b6fbcd\", \"subnet-42a6fdgd\"],\n        },\n    ]\n)\n```\n\nRun a task without a public IP assigned\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    vpc_id=\"vpc-01abcdf123456789a\",\n    task_customizations=[\n        {\n            \"op\": \"replace\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/assignPublicIp\",\n            \"value\": \"DISABLED\",\n        },\n    ]\n)\n```\n\nRun a task with custom VPC security groups\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    vpc_id=\"vpc-01abcdf123456789a\",\n    task_customizations=[\n        {\n            \"op\": \"add\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/securityGroups\",\n            \"value\": [\"sg-d72e9599956a084f5\"],\n        },\n    ],\n)\n```\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask","title":"<code>ECSTask</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Run a command as an ECS task.</p> <p>Attributes:</p> Name Type Description <code>type</code> <code>Literal['ecs-task']</code> <p>The slug for this task type with a default value of \"ecs-task\".</p> <code>aws_credentials</code> <code>AwsCredentials</code> <p>The AWS credentials to use to connect to ECS with a default factory of AwsCredentials.</p> <code>task_definition_arn</code> <code>Optional[str]</code> <p>An optional identifier for an existing task definition to use. If fields are set on the ECSTask that conflict with the task definition, a new copy will be registered with the required values. Cannot be used with task_definition. If not provided, Prefect will generate and register a minimal task definition.</p> <code>task_definition</code> <code>Optional[dict]</code> <p>An optional ECS task definition to use. Prefect may set defaults or override fields on this task definition to match other ECSTask fields. Cannot be used with task_definition_arn. If not provided, Prefect will generate and register a minimal task definition.</p> <code>family</code> <code>Optional[str]</code> <p>An optional family for the task definition. If not provided, it will be inferred from the task definition. If the task definition does not have a family, the name will be generated. When flow and deployment metadata is available, the generated name will include their names. Values for this field will be slugified to match AWS character requirements.</p> <code>image</code> <code>Optional[str]</code> <p>An optional image to use for the Prefect container in the task. If this value is not null, it will override the value in the task definition. This value defaults to a Prefect base image matching your local versions.</p> <code>auto_deregister_task_definition</code> <code>bool</code> <p>A boolean that controls if any task definitions that are created by this block will be deregistered or not. Existing task definitions linked by ARN will never be deregistered. Deregistering a task definition does not remove it from your AWS account, instead it will be marked as INACTIVE.</p> <code>cpu</code> <code>int</code> <p>The amount of CPU to provide to the ECS task. Valid amounts are specified in the AWS documentation. If not provided, a default value of ECS_DEFAULT_CPU will be used unless present on the task definition.</p> <code>memory</code> <code>int</code> <p>The amount of memory to provide to the ECS task. Valid amounts are specified in the AWS documentation. If not provided, a default value of ECS_DEFAULT_MEMORY will be used unless present on the task definition.</p> <code>execution_role_arn</code> <code>str</code> <p>An execution role to use for the task. This controls the permissions of the task when it is launching. If this value is not null, it will override the value in the task definition. An execution role must be provided to capture logs from the container.</p> <code>configure_cloudwatch_logs</code> <code>bool</code> <p>A boolean that controls if the Prefect container will be configured to send its output to the AWS CloudWatch logs service or not. This functionality requires an execution role with permissions to create log streams and groups.</p> <code>cloudwatch_logs_options</code> <code>Dict[str, str]</code> <p>A dictionary of options to pass to the CloudWatch logs configuration.</p> <code>stream_output</code> <code>bool</code> <p>A boolean indicating whether logs will be streamed from the Prefect container to the local console.</p> <code>launch_type</code> <code>Optional[Literal['FARGATE', 'EC2', 'EXTERNAL', 'FARGATE_SPOT']]</code> <p>An optional launch type for the ECS task run infrastructure.</p> <code>vpc_id</code> <code>Optional[str]</code> <p>An optional VPC ID to link the task run to. This is only applicable when using the 'awsvpc' network mode for your task.</p> <code>cluster</code> <code>Optional[str]</code> <p>An optional ECS cluster to run the task in. The ARN or name may be provided. If not provided, the default cluster will be used.</p> <code>env</code> <code>Dict[str, Optional[str]]</code> <p>A dictionary of environment variables to provide to the task run. These variables are set on the Prefect container at task runtime.</p> <code>task_role_arn</code> <code>str</code> <p>An optional role to attach to the task run. This controls the permissions of the task while it is running.</p> <code>task_customizations</code> <code>JsonPatch</code> <p>A list of JSON 6902 patches to apply to the task run request. If a string is given, it will parsed as a JSON expression.</p> <code>task_start_timeout_seconds</code> <code>int</code> <p>The amount of time to watch for the start of the ECS task before marking it as failed. The task must enter a RUNNING state to be considered started.</p> <code>task_watch_poll_interval</code> <code>float</code> <p>The amount of time to wait between AWS API calls while monitoring the state of an ECS task.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the ECS worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass ECSTask(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Run a command as an ECS task.\n\n    Attributes:\n        type: The slug for this task type with a default value of \"ecs-task\".\n        aws_credentials: The AWS credentials to use to connect to ECS with a\n            default factory of AwsCredentials.\n        task_definition_arn: An optional identifier for an existing task definition\n            to use. If fields are set on the ECSTask that conflict with the task\n            definition, a new copy will be registered with the required values.\n            Cannot be used with task_definition. If not provided, Prefect will\n            generate and register a minimal task definition.\n        task_definition: An optional ECS task definition to use. Prefect may set\n            defaults or override fields on this task definition to match other\n            ECSTask fields. Cannot be used with task_definition_arn.\n            If not provided, Prefect will generate and register\n            a minimal task definition.\n        family: An optional family for the task definition. If not provided,\n            it will be inferred from the task definition. If the task definition\n            does not have a family, the name will be generated. When flow and\n            deployment metadata is available, the generated name will include\n            their names. Values for this field will be slugified to match\n            AWS character requirements.\n        image: An optional image to use for the Prefect container in the task.\n            If this value is not null, it will override the value in the task\n            definition. This value defaults to a Prefect base image matching\n            your local versions.\n        auto_deregister_task_definition: A boolean that controls if any task\n            definitions that are created by this block will be deregistered\n            or not. Existing task definitions linked by ARN will never be\n            deregistered. Deregistering a task definition does not remove\n            it from your AWS account, instead it will be marked as INACTIVE.\n        cpu: The amount of CPU to provide to the ECS task. Valid amounts are\n            specified in the AWS documentation. If not provided, a default\n            value of ECS_DEFAULT_CPU will be used unless present on\n            the task definition.\n        memory: The amount of memory to provide to the ECS task.\n            Valid amounts are specified in the AWS documentation.\n            If not provided, a default value of ECS_DEFAULT_MEMORY\n            will be used unless present on the task definition.\n        execution_role_arn: An execution role to use for the task.\n            This controls the permissions of the task when it is launching.\n            If this value is not null, it will override the value in the task\n            definition. An execution role must be provided to capture logs\n            from the container.\n        configure_cloudwatch_logs: A boolean that controls if the Prefect\n            container will be configured to send its output to the\n            AWS CloudWatch logs service or not. This functionality requires\n            an execution role with permissions to create log streams and groups.\n        cloudwatch_logs_options: A dictionary of options to pass to\n            the CloudWatch logs configuration.\n        stream_output: A boolean indicating whether logs will be\n            streamed from the Prefect container to the local console.\n        launch_type: An optional launch type for the ECS task run infrastructure.\n        vpc_id: An optional VPC ID to link the task run to.\n            This is only applicable when using the 'awsvpc' network mode for your task.\n        cluster: An optional ECS cluster to run the task in.\n            The ARN or name may be provided. If not provided,\n            the default cluster will be used.\n        env: A dictionary of environment variables to provide to\n            the task run. These variables are set on the\n            Prefect container at task runtime.\n        task_role_arn: An optional role to attach to the task run.\n            This controls the permissions of the task while it is running.\n        task_customizations: A list of JSON 6902 patches to apply to the task\n            run request. If a string is given, it will parsed as a JSON expression.\n        task_start_timeout_seconds: The amount of time to watch for the\n            start of the ECS task before marking it as failed. The task must\n            enter a RUNNING state to be considered started.\n        task_watch_poll_interval: The amount of time to wait between AWS API\n            calls while monitoring the state of an ECS task.\n    \"\"\"\n\n    _block_type_slug = \"ecs-task\"\n    _block_type_name = \"ECS Task\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _description = \"Run a command as an ECS task.\"  # noqa\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-aws/ecs/#prefect_aws.ecs.ECSTask\"  # noqa\n    )\n\n    type: Literal[\"ecs-task\"] = Field(\n        \"ecs-task\", description=\"The slug for this task type.\"\n    )\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to ECS.\",\n    )\n\n    # Task definition settings\n    task_definition_arn: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier for an existing task definition to use. If fields are set \"\n            \"on the `ECSTask` that conflict with the task definition, a new copy \"\n            \"will be registered with the required values. \"\n            \"Cannot be used with `task_definition`. If not provided, Prefect will \"\n            \"generate and register a minimal task definition.\"\n        ),\n    )\n    task_definition: Optional[dict] = Field(\n        default=None,\n        description=(\n            \"An ECS task definition to use. Prefect may set defaults or override \"\n            \"fields on this task definition to match other `ECSTask` fields. \"\n            \"Cannot be used with `task_definition_arn`. If not provided, Prefect will \"\n            \"generate and register a minimal task definition.\"\n        ),\n    )\n    family: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A family for the task definition. If not provided, it will be inferred \"\n            \"from the task definition. If the task definition does not have a family, \"\n            \"the name will be generated. When flow and deployment metadata is \"\n            \"available, the generated name will include their names. Values for this \"\n            \"field will be slugified to match AWS character requirements.\"\n        ),\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. If this value is \"\n            \"not null, it will override the value in the task definition. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    auto_deregister_task_definition: bool = Field(\n        default=True,\n        description=(\n            \"If set, any task definitions that are created by this block will be \"\n            \"deregistered. Existing task definitions linked by ARN will never be \"\n            \"deregistered. Deregistering a task definition does not remove it from \"\n            \"your AWS account, instead it will be marked as INACTIVE.\"\n        ),\n    )\n\n    # Mixed task definition / run settings\n    cpu: int = Field(\n        title=\"CPU\",\n        default=None,\n        description=(\n            \"The amount of CPU to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_CPU} will be used unless present on the task definition.\"\n        ),\n    )\n    memory: int = Field(\n        default=None,\n        description=(\n            \"The amount of memory to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_MEMORY} will be used unless present on the task definition.\"\n        ),\n    )\n    execution_role_arn: str = Field(\n        title=\"Execution Role ARN\",\n        default=None,\n        description=(\n            \"An execution role to use for the task. This controls the permissions of \"\n            \"the task when it is launching. If this value is not null, it will \"\n            \"override the value in the task definition. An execution role must be \"\n            \"provided to capture logs from the container.\"\n        ),\n    )\n    configure_cloudwatch_logs: bool = Field(\n        default=None,\n        description=(\n            \"If `True`, the Prefect container will be configured to send its output \"\n            \"to the AWS CloudWatch logs service. This functionality requires an \"\n            \"execution role with logs:CreateLogStream, logs:CreateLogGroup, and \"\n            \"logs:PutLogEvents permissions. The default for this field is `False` \"\n            \"unless `stream_output` is set.\"\n        ),\n    )\n    cloudwatch_logs_options: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to \"\n            \"pass additional options to the CloudWatch logs configuration or override \"\n            \"the default options. See the AWS documentation for available options. \"\n            \"https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html#create_awslogs_logdriver_options.\"  # noqa\n        ),\n    )\n    stream_output: bool = Field(\n        default=None,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console. Unless you have configured AWS CloudWatch logs manually on your \"\n            \"task definition, this requires the same prerequisites outlined in \"\n            \"`configure_cloudwatch_logs`.\"\n        ),\n    )\n\n    # Task run settings\n    launch_type: Optional[\n        Literal[\"FARGATE\", \"EC2\", \"EXTERNAL\", \"FARGATE_SPOT\"]\n    ] = Field(\n        default=\"FARGATE\",\n        description=(\n            \"The type of ECS task run infrastructure that should be used. Note that\"\n            \" 'FARGATE_SPOT' is not a formal ECS launch type, but we will configure\"\n            \" the proper capacity provider strategy if set here.\"\n        ),\n    )\n    vpc_id: Optional[str] = Field(\n        title=\"VPC ID\",\n        default=None,\n        description=(\n            \"The AWS VPC to link the task run to. This is only applicable when using \"\n            \"the 'awsvpc' network mode for your task. FARGATE tasks require this \"\n            \"network  mode, but for EC2 tasks the default network mode is 'bridge'. \"\n            \"If using the 'awsvpc' network mode and this field is null, your default \"\n            \"VPC will be used. If no default VPC can be found, the task run will fail.\"\n        ),\n    )\n    cluster: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The ECS cluster to run the task in. The ARN or name may be provided. If \"\n            \"not provided, the default cluster will be used.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    task_role_arn: str = Field(\n        title=\"Task Role ARN\",\n        default=None,\n        description=(\n            \"A role to attach to the task run. This controls the permissions of the \"\n            \"task while it is running.\"\n        ),\n    )\n    task_customizations: JsonPatch = Field(\n        default_factory=lambda: JsonPatch([]),\n        description=(\n            \"A list of JSON 6902 patches to apply to the task run request. \"\n            \"If a string is given, it will parsed as a JSON expression.\"\n        ),\n    )\n\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=120,\n        description=(\n            \"The amount of time to watch for the start of the ECS task \"\n            \"before marking it as failed. The task must enter a RUNNING state to be \"\n            \"considered started.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an ECS task.\"\n        ),\n    )\n\n    @root_validator(pre=True)\n    def set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Streaming output generally requires CloudWatch logs to be configured.\n\n        To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n        defaults to matching the value of `stream_output`.\n        \"\"\"\n        configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n        if configure_cloudwatch_logs is None:\n            values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n        return values\n\n    @root_validator\n    def configure_cloudwatch_logs_requires_execution_role_arn(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if (\n            values.get(\"configure_cloudwatch_logs\")\n            and not values.get(\"execution_role_arn\")\n            # Do not raise if they've linked to another task definition or provided\n            # it without using our shortcuts\n            and not values.get(\"task_definition_arn\")\n            and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n        ):\n            raise ValueError(\n                \"An `execution_role_arn` must be provided to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs`.\"\n            )\n        return values\n\n    @root_validator\n    def cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if values.get(\"cloudwatch_logs_options\") and not values.get(\n            \"configure_cloudwatch_logs\"\n        ):\n            raise ValueError(\n                \"`configure_cloudwatch_log` must be enabled to use \"\n                \"`cloudwatch_logs_options`.\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def image_is_required(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Enforces that an image is available if image is `None`.\n        \"\"\"\n        has_image = bool(values.get(\"image\"))\n        has_task_definition_arn = bool(values.get(\"task_definition_arn\"))\n\n        # The image can only be null when the task_definition_arn is set\n        if has_image or has_task_definition_arn:\n            return values\n\n        prefect_container = (\n            get_prefect_container(\n                (values.get(\"task_definition\") or {}).get(\"containerDefinitions\", [])\n            )\n            or {}\n        )\n        image_in_task_definition = prefect_container.get(\"image\")\n\n        # If a task_definition is given with a prefect container image, use that value\n        if image_in_task_definition:\n            values[\"image\"] = image_in_task_definition\n        # Otherwise, it should default to the Prefect base image\n        else:\n            values[\"image\"] = get_prefect_image_name()\n        return values\n\n    @validator(\"task_customizations\", pre=True)\n    def cast_customizations_to_a_json_patch(\n        cls, value: Union[List[Dict], JsonPatch, str]\n    ) -&gt; JsonPatch:\n        \"\"\"\n        Casts lists to JsonPatch instances.\n        \"\"\"\n        if isinstance(value, str):\n            value = json.loads(value)\n        if isinstance(value, list):\n            return JsonPatch(value)\n        return value  # type: ignore\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'JsonPatch' type\n        arbitrary_types_allowed = True\n        json_encoders = {JsonPatch: lambda p: p.patch}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'JsonPatch' type\n        d = super().dict(*args, **kwargs)\n        d[\"task_customizations\"] = self.task_customizations.patch\n        return d\n\n    def prepare_for_flow_run(\n        self: Self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"Deployment\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Return an copy of the block that is prepared to execute a flow run.\n        \"\"\"\n        new_family = None\n\n        # Update the family if not specified elsewhere\n        if (\n            not self.family\n            and not self.task_definition_arn\n            and not (self.task_definition and self.task_definition.get(\"family\"))\n        ):\n            if flow and deployment:\n                new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}__{deployment.name}\"\n            elif flow and not deployment:\n                new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}\"\n            elif deployment and not flow:\n                # This is a weird case and should not be see in the wild\n                new_family = f\"{ECS_DEFAULT_FAMILY}__unknown-flow__{deployment.name}\"\n\n        new = super().prepare_for_flow_run(flow_run, deployment=deployment, flow=flow)\n\n        if new_family:\n            return new.copy(update={\"family\": new_family})\n        else:\n            # Avoid an extra copy if not needed\n            return new\n\n    @sync_compatible\n    async def run(self, task_status: Optional[TaskStatus] = None) -&gt; ECSTaskResult:\n        \"\"\"\n        Run the configured task on ECS.\n        \"\"\"\n        boto_session, ecs_client = await run_sync_in_worker_thread(\n            self._get_session_and_client\n        )\n\n        (\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition,\n        ) = await run_sync_in_worker_thread(\n            self._create_task_and_wait_for_start, boto_session, ecs_client\n        )\n\n        # Display a nice message indicating the command and image\n        command = self.command or get_prefect_container(\n            task_definition[\"containerDefinitions\"]\n        ).get(\"command\", [])\n        self.logger.info(\n            f\"{self._log_prefix}: Running command {' '.join(command)!r} \"\n            f\"in container {PREFECT_ECS_CONTAINER_NAME!r} ({self.image})...\"\n        )\n\n        # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n        # if set to preserve matching by name rather than arn\n        # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n        # single colons.\n        identifier = (self.cluster if self.cluster else cluster_arn) + \"::\" + task_arn\n\n        if task_status:\n            task_status.started(identifier)\n\n        status_code = await run_sync_in_worker_thread(\n            self._watch_task_and_get_exit_code,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition and self.auto_deregister_task_definition,\n            boto_session,\n            ecs_client,\n        )\n\n        return ECSTaskResult(\n            identifier=identifier,\n            # If the container does not start the exit code can be null but we must\n            # still report a status code. We use a -1 to indicate a special code.\n            status_code=status_code if status_code is not None else -1,\n        )\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a task running on ECS.\n\n        Args:\n            identifier: A cluster and task arn combination. This should match a value\n                yielded by `ECSTask.run`.\n        \"\"\"\n        if grace_seconds != 30:\n            self.logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n                \"support dynamic grace period configuration so 30s will be used. \"\n                \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n            )\n        cluster, task = parse_task_identifier(identifier)\n        await run_sync_in_worker_thread(self._stop_task, cluster, task)\n\n    @staticmethod\n    def get_corresponding_worker_type() -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return ECSWorker.type\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a cloud-run work pool with the same\n        configuration as this block.\n\n        Returns:\n            - dict: a base job template for a cloud-run work pool\n        \"\"\"\n        base_job_template = copy.deepcopy(ECSWorker.get_default_base_job_template())\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"task_customizations\",\n            ]:\n                continue\n            elif key == \"aws_credentials\":\n                if not self.aws_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"aws_credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.aws_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"task_definition\":\n                base_job_template[\"job_configuration\"][\"task_definition\"] = value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                    \" Skipping.\"\n                )\n\n        if self.task_customizations:\n            network_config_patches = JsonPatch(\n                [\n                    patch\n                    for patch in self.task_customizations\n                    if \"networkConfiguration\" in patch[\"path\"]\n                ]\n            )\n            minimal_network_config = assemble_document_for_patches(\n                network_config_patches\n            )\n            if minimal_network_config:\n                minimal_network_config_with_patches = network_config_patches.apply(\n                    minimal_network_config\n                )\n                base_job_template[\"variables\"][\"properties\"][\"network_configuration\"][\n                    \"default\"\n                ] = minimal_network_config_with_patches[\"networkConfiguration\"][\n                    \"awsvpcConfiguration\"\n                ]\n            try:\n                base_job_template[\"job_configuration\"][\n                    \"task_run_request\"\n                ] = self.task_customizations.apply(\n                    base_job_template[\"job_configuration\"][\"task_run_request\"]\n                )\n            except JsonPointerException:\n                self.logger.warning(\n                    \"Unable to apply task customizations to the base job template.\"\n                    \"You may need to update the template manually.\"\n                )\n\n        return base_job_template\n\n    def _stop_task(self, cluster: str, task: str) -&gt; None:\n        \"\"\"\n        Stop a running ECS task.\n        \"\"\"\n        if self.cluster is not None and cluster != self.cluster:\n            raise InfrastructureNotAvailable(\n                \"Cannot stop ECS task: this infrastructure block has access to \"\n                f\"cluster {self.cluster!r} but the task is running in cluster \"\n                f\"{cluster!r}.\"\n            )\n\n        _, ecs_client = self._get_session_and_client()\n        try:\n            ecs_client.stop_task(cluster=cluster, task=task)\n        except Exception as exc:\n            # Raise a special exception if the task does not exist\n            if \"ClusterNotFound\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} could not be found.\"\n                ) from exc\n            if \"not find task\" in str(exc) or \"referenced task was not found\" in str(\n                exc\n            ):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the task {task!r} could not be found in \"\n                    f\"cluster {cluster!r}.\"\n                ) from exc\n            if \"no registered tasks\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} has no tasks.\"\n                ) from exc\n\n            # Reraise unknown exceptions\n            raise\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"ECSTask {self.name!r}\"\n        else:\n            return \"ECSTask\"\n\n    def _get_session_and_client(self) -&gt; Tuple[boto3.Session, _ECSClient]:\n        \"\"\"\n        Retrieve a boto3 session and ECS client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        ecs_client = boto_session.client(\"ecs\")\n        return boto_session, ecs_client\n\n    def _create_task_and_wait_for_start(\n        self, boto_session: boto3.Session, ecs_client: _ECSClient\n    ) -&gt; Tuple[str, str, dict, bool]:\n        \"\"\"\n        Register the task definition, create the task run, and wait for it to start.\n\n        Returns a tuple of\n        - The task ARN\n        - The task's cluster ARN\n        - The task definition\n        - A bool indicating if the task definition is newly registered\n        \"\"\"\n        new_task_definition_registered = False\n        requested_task_definition = (\n            self._retrieve_task_definition(ecs_client, self.task_definition_arn)\n            if self.task_definition_arn\n            else self.task_definition\n        ) or {}\n        task_definition_arn = requested_task_definition.get(\"taskDefinitionArn\", None)\n\n        task_definition = self._prepare_task_definition(\n            requested_task_definition, region=ecs_client.meta.region_name\n        )\n\n        # We must register the task definition if the arn is null or changes were made\n        if task_definition != requested_task_definition or not task_definition_arn:\n            # Before registering, check if the latest task definition in the family\n            # can be used\n            latest_task_definition = self._retrieve_latest_task_definition(\n                ecs_client, task_definition[\"family\"]\n            )\n            if self._task_definitions_equal(latest_task_definition, task_definition):\n                self.logger.debug(\n                    f\"{self._log_prefix}: The latest task definition matches the \"\n                    \"required task definition; using that instead of registering a new \"\n                    \" one.\"\n                )\n                task_definition_arn = latest_task_definition[\"taskDefinitionArn\"]\n            else:\n                if task_definition_arn:\n                    self.logger.warning(\n                        f\"{self._log_prefix}: Settings require changes to the linked \"\n                        \"task definition. A new task definition will be registered. \"\n                        + (\n                            \"Enable DEBUG level logs to see the difference.\"\n                            if self.logger.level &gt; logging.DEBUG\n                            else \"\"\n                        )\n                    )\n                    self.logger.debug(\n                        f\"{self._log_prefix}: Diff for requested task definition\"\n                        + _pretty_diff(requested_task_definition, task_definition)\n                    )\n                else:\n                    self.logger.info(\n                        f\"{self._log_prefix}: Registering task definition...\"\n                    )\n                    self.logger.debug(\n                        \"Task definition payload\\n\" + yaml.dump(task_definition)\n                    )\n\n                task_definition_arn = self._register_task_definition(\n                    ecs_client, task_definition\n                )\n                new_task_definition_registered = True\n\n        if task_definition.get(\"networkMode\") == \"awsvpc\":\n            network_config = self._load_vpc_network_config(self.vpc_id, boto_session)\n        else:\n            network_config = None\n\n        task_run = self._prepare_task_run(\n            network_config=network_config,\n            task_definition_arn=task_definition_arn,\n        )\n        self.logger.info(f\"{self._log_prefix}: Creating task run...\")\n        self.logger.debug(\"Task run payload\\n\" + yaml.dump(task_run))\n\n        try:\n            task = self._run_task(ecs_client, task_run)\n            task_arn = task[\"taskArn\"]\n            cluster_arn = task[\"clusterArn\"]\n        except Exception as exc:\n            self._report_task_run_creation_failure(task_run, exc)\n\n        # Raises an exception if the task does not start\n        self.logger.info(f\"{self._log_prefix}: Waiting for task run to start...\")\n        self._wait_for_task_start(\n            task_arn, cluster_arn, ecs_client, timeout=self.task_start_timeout_seconds\n        )\n\n        return task_arn, cluster_arn, task_definition, new_task_definition_registered\n\n    def _watch_task_and_get_exit_code(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        deregister_task_definition: bool,\n        boto_session: boto3.Session,\n        ecs_client: _ECSClient,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Wait for the task run to complete and retrieve the exit code of the Prefect\n        container.\n        \"\"\"\n\n        # Wait for completion and stream logs\n        task = self._wait_for_task_finish(\n            task_arn, cluster_arn, task_definition, ecs_client, boto_session\n        )\n\n        if deregister_task_definition:\n            ecs_client.deregister_task_definition(\n                taskDefinition=task[\"taskDefinitionArn\"]\n            )\n\n        # Check the status code of the Prefect container\n        prefect_container = get_prefect_container(task[\"containers\"])\n        assert (\n            prefect_container is not None\n        ), f\"'prefect' container missing from task: {task}\"\n        status_code = prefect_container.get(\"exitCode\")\n        self._report_container_status_code(PREFECT_ECS_CONTAINER_NAME, status_code)\n\n        return status_code\n\n    def _task_definitions_equal(self, taskdef_1, taskdef_2) -&gt; bool:\n        \"\"\"\n        Compare two task definitions.\n\n        Since one may come from the AWS API and have populated defaults, we do our best\n        to homogenize the definitions without changing their meaning.\n        \"\"\"\n        if taskdef_1 == taskdef_2:\n            return True\n\n        if taskdef_1 is None or taskdef_2 is None:\n            return False\n\n        taskdef_1 = copy.deepcopy(taskdef_1)\n        taskdef_2 = copy.deepcopy(taskdef_2)\n\n        def _set_aws_defaults(taskdef):\n            \"\"\"Set defaults that AWS would set after registration\"\"\"\n            container_definitions = taskdef.get(\"containerDefinitions\", [])\n            essential = any(\n                container.get(\"essential\") for container in container_definitions\n            )\n            if not essential:\n                container_definitions[0].setdefault(\"essential\", True)\n\n            taskdef.setdefault(\"networkMode\", \"bridge\")\n\n        _set_aws_defaults(taskdef_1)\n        _set_aws_defaults(taskdef_2)\n\n        def _drop_empty_keys(dict_):\n            \"\"\"Recursively drop keys with 'empty' values\"\"\"\n            for key, value in tuple(dict_.items()):\n                if not value:\n                    dict_.pop(key)\n                if isinstance(value, dict):\n                    _drop_empty_keys(value)\n                if isinstance(value, list):\n                    for v in value:\n                        if isinstance(v, dict):\n                            _drop_empty_keys(v)\n\n        _drop_empty_keys(taskdef_1)\n        _drop_empty_keys(taskdef_2)\n\n        # Clear fields that change on registration for comparison\n        for field in POST_REGISTRATION_FIELDS:\n            taskdef_1.pop(field, None)\n            taskdef_2.pop(field, None)\n\n        return taskdef_1 == taskdef_2\n\n    def preview(self) -&gt; str:\n        \"\"\"\n        Generate a preview of the task definition and task run that will be sent to AWS.\n        \"\"\"\n        preview = \"\"\n\n        task_definition_arn = self.task_definition_arn or \"&lt;registered at runtime&gt;\"\n\n        if self.task_definition or not self.task_definition_arn:\n            task_definition = self._prepare_task_definition(\n                self.task_definition or {},\n                region=self.aws_credentials.region_name\n                or \"&lt;loaded from client at runtime&gt;\",\n            )\n            preview += \"---\\n# Task definition\\n\"\n            preview += yaml.dump(task_definition)\n            preview += \"\\n\"\n        else:\n            task_definition = None\n\n        if task_definition and task_definition.get(\"networkMode\") == \"awsvpc\":\n            vpc = \"the default VPC\" if not self.vpc_id else self.vpc_id\n            network_config = {\n                \"awsvpcConfiguration\": {\n                    \"subnets\": f\"&lt;loaded from {vpc} at runtime&gt;\",\n                    \"assignPublicIp\": \"ENABLED\",\n                }\n            }\n        else:\n            network_config = None\n\n        task_run = self._prepare_task_run(network_config, task_definition_arn)\n        preview += \"---\\n# Task run request\\n\"\n        preview += yaml.dump(task_run)\n\n        return preview\n\n    def _report_container_status_code(\n        self, name: str, status_code: Optional[int]\n    ) -&gt; None:\n        \"\"\"\n        Display a log for the given container status code.\n        \"\"\"\n        if status_code is None:\n            self.logger.error(\n                f\"{self._log_prefix}: Task exited without reporting an exit status \"\n                f\"for container {name!r}.\"\n            )\n        elif status_code == 0:\n            self.logger.info(\n                f\"{self._log_prefix}: Container {name!r} exited successfully.\"\n            )\n        else:\n            self.logger.warning(\n                f\"{self._log_prefix}: Container {name!r} exited with non-zero exit \"\n                f\"code {status_code}.\"\n            )\n\n    def _report_task_run_creation_failure(self, task_run: dict, exc: Exception) -&gt; None:\n        \"\"\"\n        Wrap common AWS task run creation failures with nicer user-facing messages.\n        \"\"\"\n        # AWS generates exception types at runtime so they must be captured a bit\n        # differently than normal.\n        if \"ClusterNotFoundException\" in str(exc):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} not found. \"\n                \"Confirm that the cluster is configured in your region.\"\n            ) from exc\n        elif \"No Container Instances\" in str(exc) and self.launch_type == \"EC2\":\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} does not appear to \"\n                \"have any container instances associated with it. Confirm that you \"\n                \"have EC2 container instances available.\"\n            ) from exc\n        elif (\n            \"failed to validate logger args\" in str(exc)\n            and \"AccessDeniedException\" in str(exc)\n            and self.configure_cloudwatch_logs\n        ):\n            raise RuntimeError(\n                \"Failed to run ECS task, the attached execution role does not appear \"\n                \"to have sufficient permissions. Ensure that the execution role \"\n                f\"{self.execution_role!r} has permissions logs:CreateLogStream, \"\n                \"logs:CreateLogGroup, and logs:PutLogEvents.\"\n            )\n        else:\n            raise\n\n    def _watch_task_run(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        current_status: str = \"UNKNOWN\",\n        until_status: str = None,\n        timeout: int = None,\n    ) -&gt; Generator[None, None, dict]:\n        \"\"\"\n        Watches an ECS task run by querying every `poll_interval` seconds. After each\n        query, the retrieved task is yielded. This function returns when the task run\n        reaches a STOPPED status or the provided `until_status`.\n\n        Emits a log each time the status changes.\n        \"\"\"\n        last_status = status = current_status\n        t0 = time.time()\n        while status != until_status:\n            tasks = ecs_client.describe_tasks(\n                tasks=[task_arn], cluster=cluster_arn, include=[\"TAGS\"]\n            )[\"tasks\"]\n\n            if tasks:\n                task = tasks[0]\n\n                status = task[\"lastStatus\"]\n                if status != last_status:\n                    self.logger.info(f\"{self._log_prefix}: Status is {status}.\")\n\n                yield task\n\n                # No point in continuing if the status is final\n                if status == \"STOPPED\":\n                    break\n\n                last_status = status\n\n            else:\n                # Intermittently, the task will not be described. We wat to respect the\n                # watch timeout though.\n                self.logger.debug(f\"{self._log_prefix}: Task not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching task for status \"\n                    f\"{until_status or 'STOPPED'}\"\n                )\n            time.sleep(self.task_watch_poll_interval)\n\n    def _wait_for_task_start(\n        self, task_arn: str, cluster_arn: str, ecs_client: _ECSClient, timeout: int\n    ) -&gt; dict:\n        \"\"\"\n        Waits for an ECS task run to reach a RUNNING status.\n\n        If a STOPPED status is reached instead, an exception is raised indicating the\n        reason that the task run did not start.\n        \"\"\"\n        for task in self._watch_task_run(\n            task_arn, cluster_arn, ecs_client, until_status=\"RUNNING\", timeout=timeout\n        ):\n            # TODO: It is possible that the task has passed _through_ a RUNNING\n            #       status during the polling interval. In this case, there is not an\n            #       exception to raise.\n            if task[\"lastStatus\"] == \"STOPPED\":\n                code = task.get(\"stopCode\")\n                reason = task.get(\"stoppedReason\")\n                # Generate a dynamic exception type from the AWS name\n                raise type(code, (RuntimeError,), {})(reason)\n\n        return task\n\n    def _wait_for_task_finish(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        ecs_client: _ECSClient,\n        boto_session: boto3.Session,\n    ):\n        \"\"\"\n        Watch an ECS task until it reaches a STOPPED status.\n\n        If configured, logs from the Prefect container are streamed to stderr.\n\n        Returns a description of the task on completion.\n        \"\"\"\n        can_stream_output = False\n\n        if self.stream_output:\n            container_def = get_prefect_container(\n                task_definition[\"containerDefinitions\"]\n            )\n            if not container_def:\n                self.logger.warning(\n                    f\"{self._log_prefix}: Prefect container definition not found in \"\n                    \"task definition. Output cannot be streamed.\"\n                )\n            elif not container_def.get(\"logConfiguration\"):\n                self.logger.warning(\n                    f\"{self._log_prefix}: Logging configuration not found on task. \"\n                    \"Output cannot be streamed.\"\n                )\n            elif not container_def[\"logConfiguration\"].get(\"logDriver\") == \"awslogs\":\n                self.logger.warning(\n                    f\"{self._log_prefix}: Logging configuration uses unsupported \"\n                    \" driver {container_def['logConfiguration'].get('logDriver')!r}. \"\n                    \"Output cannot be streamed.\"\n                )\n            else:\n                # Prepare to stream the output\n                log_config = container_def[\"logConfiguration\"][\"options\"]\n                logs_client = boto_session.client(\"logs\")\n                can_stream_output = True\n                # Track the last log timestamp to prevent double display\n                last_log_timestamp: Optional[int] = None\n                # Determine the name of the stream as \"prefix/container/run-id\"\n                stream_name = \"/\".join(\n                    [\n                        log_config[\"awslogs-stream-prefix\"],\n                        PREFECT_ECS_CONTAINER_NAME,\n                        task_arn.rsplit(\"/\")[-1],\n                    ]\n                )\n                self.logger.info(\n                    f\"{self._log_prefix}: Streaming output from container \"\n                    f\"{PREFECT_ECS_CONTAINER_NAME!r}...\"\n                )\n\n        for task in self._watch_task_run(\n            task_arn, cluster_arn, ecs_client, current_status=\"RUNNING\"\n        ):\n            if self.stream_output and can_stream_output:\n                # On each poll for task run status, also retrieve available logs\n                last_log_timestamp = self._stream_available_logs(\n                    logs_client,\n                    log_group=log_config[\"awslogs-group\"],\n                    log_stream=stream_name,\n                    last_log_timestamp=last_log_timestamp,\n                )\n\n        return task\n\n    def _stream_available_logs(\n        self,\n        logs_client: Any,\n        log_group: str,\n        log_stream: str,\n        last_log_timestamp: Optional[int] = None,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Stream logs from the given log group and stream since the last log timestamp.\n\n        Will continue on paginated responses until all logs are returned.\n\n        Returns the last log timestamp which can be used to call this method in the\n        future.\n        \"\"\"\n        last_log_stream_token = \"NO-TOKEN\"\n        next_log_stream_token = None\n\n        # AWS will return the same token that we send once the end of the paginated\n        # response is reached\n        while last_log_stream_token != next_log_stream_token:\n            last_log_stream_token = next_log_stream_token\n\n            request = {\n                \"logGroupName\": log_group,\n                \"logStreamName\": log_stream,\n            }\n\n            if last_log_stream_token is not None:\n                request[\"nextToken\"] = last_log_stream_token\n\n            if last_log_timestamp is not None:\n                # Bump the timestamp by one ms to avoid retrieving the last log again\n                request[\"startTime\"] = last_log_timestamp + 1\n\n            try:\n                response = logs_client.get_log_events(**request)\n            except Exception:\n                self.logger.error(\n                    (\n                        f\"{self._log_prefix}: Failed to read log events with request \"\n                        f\"{request}\"\n                    ),\n                    exc_info=True,\n                )\n                return last_log_timestamp\n\n            log_events = response[\"events\"]\n            for log_event in log_events:\n                # TODO: This doesn't forward to the local logger, which can be\n                #       bad for customizing handling and understanding where the\n                #       log is coming from, but it avoid nesting logger information\n                #       when the content is output from a Prefect logger on the\n                #       running infrastructure\n                print(log_event[\"message\"], file=sys.stderr)\n\n                if (\n                    last_log_timestamp is None\n                    or log_event[\"timestamp\"] &gt; last_log_timestamp\n                ):\n                    last_log_timestamp = log_event[\"timestamp\"]\n\n            next_log_stream_token = response.get(\"nextForwardToken\")\n            if not log_events:\n                # Stop reading pages if there was no data\n                break\n\n        return last_log_timestamp\n\n    def _retrieve_latest_task_definition(\n        self, ecs_client: _ECSClient, task_definition_family: str\n    ) -&gt; Optional[dict]:\n        try:\n            latest_task_definition = self._retrieve_task_definition(\n                ecs_client, task_definition_family\n            )\n        except Exception:\n            # The family does not exist...\n            return None\n\n        return latest_task_definition\n\n    def _retrieve_task_definition(\n        self, ecs_client: _ECSClient, task_definition_arn: str\n    ):\n        \"\"\"\n        Retrieve an existing task definition from AWS.\n        \"\"\"\n        self.logger.info(\n            f\"{self._log_prefix}: Retrieving task definition {task_definition_arn!r}...\"\n        )\n        response = ecs_client.describe_task_definition(\n            taskDefinition=task_definition_arn\n        )\n        return response[\"taskDefinition\"]\n\n    def _register_task_definition(\n        self, ecs_client: _ECSClient, task_definition: dict\n    ) -&gt; str:\n        \"\"\"\n        Register a new task definition with AWS.\n        \"\"\"\n        # TODO: Consider including a global cache for this task definition since\n        #       registration of task definitions is frequently rate limited\n        task_definition_request = copy.deepcopy(task_definition)\n\n        # We need to remove some fields here if copying an existing task definition\n        for field in POST_REGISTRATION_FIELDS:\n            task_definition_request.pop(field, None)\n\n        response = ecs_client.register_task_definition(**task_definition_request)\n        return response[\"taskDefinition\"][\"taskDefinitionArn\"]\n\n    def _prepare_task_definition(self, task_definition: dict, region: str) -&gt; dict:\n        \"\"\"\n        Prepare a task definition by inferring any defaults and merging overrides.\n        \"\"\"\n        task_definition = copy.deepcopy(task_definition)\n\n        # Configure the Prefect runtime container\n        task_definition.setdefault(\"containerDefinitions\", [])\n        container = get_prefect_container(task_definition[\"containerDefinitions\"])\n        if container is None:\n            container = {\"name\": PREFECT_ECS_CONTAINER_NAME}\n            task_definition[\"containerDefinitions\"].append(container)\n\n        if self.image:\n            container[\"image\"] = self.image\n\n        # Remove any keys that have been explicitly \"unset\"\n        unset_keys = {key for key, value in self.env.items() if value is None}\n        for item in tuple(container.get(\"environment\", [])):\n            if item[\"name\"] in unset_keys:\n                container[\"environment\"].remove(item)\n\n        if self.configure_cloudwatch_logs:\n            container[\"logConfiguration\"] = {\n                \"logDriver\": \"awslogs\",\n                \"options\": {\n                    \"awslogs-create-group\": \"true\",\n                    \"awslogs-group\": \"prefect\",\n                    \"awslogs-region\": region,\n                    \"awslogs-stream-prefix\": self.name or \"prefect\",\n                    **self.cloudwatch_logs_options,\n                },\n            }\n\n        family = self.family or task_definition.get(\"family\") or ECS_DEFAULT_FAMILY\n        task_definition[\"family\"] = slugify(\n            family,\n            max_length=255,\n            regex_pattern=r\"[^a-zA-Z0-9-_]+\",\n        )\n\n        # CPU and memory are required in some cases, retrieve the value to use\n        cpu = self.cpu or task_definition.get(\"cpu\") or ECS_DEFAULT_CPU\n        memory = self.memory or task_definition.get(\"memory\") or ECS_DEFAULT_MEMORY\n\n        if self.launch_type == \"FARGATE\" or self.launch_type == \"FARGATE_SPOT\":\n            # Task level memory and cpu are required when using fargate\n            task_definition[\"cpu\"] = str(cpu)\n            task_definition[\"memory\"] = str(memory)\n\n            # The FARGATE compatibility is required if it will be used as as launch type\n            requires_compatibilities = task_definition.setdefault(\n                \"requiresCompatibilities\", []\n            )\n            if \"FARGATE\" not in requires_compatibilities:\n                task_definition[\"requiresCompatibilities\"].append(\"FARGATE\")\n\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            # However, we will not enforce that here if the user has set it\n            network_mode = task_definition.setdefault(\"networkMode\", \"awsvpc\")\n\n            if network_mode != \"awsvpc\":\n                warnings.warn(\n                    f\"Found network mode {network_mode!r} which is not compatible with \"\n                    f\"launch type {self.launch_type!r}. Use either the 'EC2' launch \"\n                    \"type or the 'awsvpc' network mode.\"\n                )\n\n        elif self.launch_type == \"EC2\":\n            # Container level memory and cpu are required when using ec2\n            container.setdefault(\"cpu\", int(cpu))\n            container.setdefault(\"memory\", int(memory))\n\n        if self.execution_role_arn and not self.task_definition_arn:\n            task_definition[\"executionRoleArn\"] = self.execution_role_arn\n\n        if self.configure_cloudwatch_logs and not task_definition.get(\n            \"executionRoleArn\"\n        ):\n            raise ValueError(\n                \"An execution role arn must be set on the task definition to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs` but no execution role \"\n                \"was found on the task definition.\"\n            )\n\n        return task_definition\n\n    def _prepare_task_run_overrides(self) -&gt; dict:\n        \"\"\"\n        Prepare the 'overrides' payload for a task run request.\n        \"\"\"\n        overrides = {\n            \"containerOverrides\": [\n                {\n                    \"name\": PREFECT_ECS_CONTAINER_NAME,\n                    \"environment\": [\n                        {\"name\": key, \"value\": value}\n                        for key, value in {\n                            **self._base_environment(),\n                            **self.env,\n                        }.items()\n                        if value is not None\n                    ],\n                }\n            ],\n        }\n\n        prefect_container_overrides = overrides[\"containerOverrides\"][0]\n\n        if self.command:\n            prefect_container_overrides[\"command\"] = self.command\n\n        if self.execution_role_arn:\n            overrides[\"executionRoleArn\"] = self.execution_role_arn\n\n        if self.task_role_arn:\n            overrides[\"taskRoleArn\"] = self.task_role_arn\n\n        if self.memory:\n            overrides[\"memory\"] = str(self.memory)\n            prefect_container_overrides.setdefault(\"memory\", self.memory)\n\n        if self.cpu:\n            overrides[\"cpu\"] = str(self.cpu)\n            prefect_container_overrides.setdefault(\"cpu\", self.cpu)\n\n        return overrides\n\n    def _load_vpc_network_config(\n        self, vpc_id: Optional[str], boto_session: boto3.Session\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = boto_session.client(\"ec2\")\n        vpc_message = \"the default VPC\" if not vpc_id else f\"VPC with ID {vpc_id}\"\n\n        if not vpc_id:\n            # Retrieve the default VPC\n            describe = {\"Filters\": [{\"Name\": \"isDefault\", \"Values\": [\"true\"]}]}\n        else:\n            describe = {\"VpcIds\": [vpc_id]}\n\n        vpcs = ec2_client.describe_vpcs(**describe)[\"Vpcs\"]\n        if not vpcs:\n            help_message = (\n                \"Pass an explicit `vpc_id` or configure a default VPC.\"\n                if not vpc_id\n                else \"Check that the VPC exists in the current region.\"\n            )\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                \"Network configuration cannot be inferred. \" + help_message\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                \"Network configuration cannot be inferred.\"\n            )\n\n        return {\n            \"awsvpcConfiguration\": {\n                \"subnets\": [s[\"SubnetId\"] for s in subnets],\n                \"assignPublicIp\": \"ENABLED\",\n                \"securityGroups\": [],\n            }\n        }\n\n    def _prepare_task_run(\n        self,\n        network_config: Optional[dict],\n        task_definition_arn: str,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task run request payload.\n        \"\"\"\n        task_run = {\n            \"overrides\": self._prepare_task_run_overrides(),\n            \"tags\": [\n                {\n                    \"key\": slugify(\n                        key,\n                        regex_pattern=_TAG_REGEX,\n                        allow_unicode=True,\n                        lowercase=False,\n                    ),\n                    \"value\": slugify(\n                        value,\n                        regex_pattern=_TAG_REGEX,\n                        allow_unicode=True,\n                        lowercase=False,\n                    ),\n                }\n                for key, value in self.labels.items()\n            ],\n            \"taskDefinition\": task_definition_arn,\n        }\n\n        if self.cluster:\n            task_run[\"cluster\"] = self.cluster\n\n        if self.launch_type:\n            if self.launch_type == \"FARGATE_SPOT\":\n                task_run[\"capacityProviderStrategy\"] = [\n                    {\"capacityProvider\": \"FARGATE_SPOT\", \"weight\": 1}\n                ]\n            else:\n                task_run[\"launchType\"] = self.launch_type\n\n        if network_config:\n            task_run[\"networkConfiguration\"] = network_config\n\n        task_run = self.task_customizations.apply(task_run)\n        return task_run\n\n    def _run_task(self, ecs_client: _ECSClient, task_run: dict):\n        \"\"\"\n        Run the task using the ECS client.\n\n        This is isolated as a separate method for testing purposes.\n        \"\"\"\n        return ecs_client.run_task(**task_run)[\"tasks\"][0]\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'JsonPatch' type\n    arbitrary_types_allowed = True\n    json_encoders = {JsonPatch: lambda p: p.patch}\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.cast_customizations_to_a_json_patch","title":"<code>cast_customizations_to_a_json_patch</code>","text":"<p>Casts lists to JsonPatch instances.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@validator(\"task_customizations\", pre=True)\ndef cast_customizations_to_a_json_patch(\n    cls, value: Union[List[Dict], JsonPatch, str]\n) -&gt; JsonPatch:\n    \"\"\"\n    Casts lists to JsonPatch instances.\n    \"\"\"\n    if isinstance(value, str):\n        value = json.loads(value)\n    if isinstance(value, list):\n        return JsonPatch(value)\n    return value  # type: ignore\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.cloudwatch_logs_options_requires_configure_cloudwatch_logs","title":"<code>cloudwatch_logs_options_requires_configure_cloudwatch_logs</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator\ndef cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if values.get(\"cloudwatch_logs_options\") and not values.get(\n        \"configure_cloudwatch_logs\"\n    ):\n        raise ValueError(\n            \"`configure_cloudwatch_log` must be enabled to use \"\n            \"`cloudwatch_logs_options`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.configure_cloudwatch_logs_requires_execution_role_arn","title":"<code>configure_cloudwatch_logs_requires_execution_role_arn</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator\ndef configure_cloudwatch_logs_requires_execution_role_arn(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if (\n        values.get(\"configure_cloudwatch_logs\")\n        and not values.get(\"execution_role_arn\")\n        # Do not raise if they've linked to another task definition or provided\n        # it without using our shortcuts\n        and not values.get(\"task_definition_arn\")\n        and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n    ):\n        raise ValueError(\n            \"An `execution_role_arn` must be provided to use \"\n            \"`configure_cloudwatch_logs` or `stream_logs`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'JsonPatch' type\n    d = super().dict(*args, **kwargs)\n    d[\"task_customizations\"] = self.task_customizations.patch\n    return d\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a cloud-run work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for a cloud-run work pool</li> </ul> Source code in <code>prefect_aws/ecs.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a cloud-run work pool with the same\n    configuration as this block.\n\n    Returns:\n        - dict: a base job template for a cloud-run work pool\n    \"\"\"\n    base_job_template = copy.deepcopy(ECSWorker.get_default_base_job_template())\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n            \"task_customizations\",\n        ]:\n            continue\n        elif key == \"aws_credentials\":\n            if not self.aws_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"aws_credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.aws_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"task_definition\":\n            base_job_template[\"job_configuration\"][\"task_definition\"] = value\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                \" Skipping.\"\n            )\n\n    if self.task_customizations:\n        network_config_patches = JsonPatch(\n            [\n                patch\n                for patch in self.task_customizations\n                if \"networkConfiguration\" in patch[\"path\"]\n            ]\n        )\n        minimal_network_config = assemble_document_for_patches(\n            network_config_patches\n        )\n        if minimal_network_config:\n            minimal_network_config_with_patches = network_config_patches.apply(\n                minimal_network_config\n            )\n            base_job_template[\"variables\"][\"properties\"][\"network_configuration\"][\n                \"default\"\n            ] = minimal_network_config_with_patches[\"networkConfiguration\"][\n                \"awsvpcConfiguration\"\n            ]\n        try:\n            base_job_template[\"job_configuration\"][\n                \"task_run_request\"\n            ] = self.task_customizations.apply(\n                base_job_template[\"job_configuration\"][\"task_run_request\"]\n            )\n        except JsonPointerException:\n            self.logger.warning(\n                \"Unable to apply task customizations to the base job template.\"\n                \"You may need to update the template manually.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>  <code>staticmethod</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@staticmethod\ndef get_corresponding_worker_type() -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return ECSWorker.type\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.image_is_required","title":"<code>image_is_required</code>","text":"<p>Enforces that an image is available if image is <code>None</code>.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator(pre=True)\ndef image_is_required(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Enforces that an image is available if image is `None`.\n    \"\"\"\n    has_image = bool(values.get(\"image\"))\n    has_task_definition_arn = bool(values.get(\"task_definition_arn\"))\n\n    # The image can only be null when the task_definition_arn is set\n    if has_image or has_task_definition_arn:\n        return values\n\n    prefect_container = (\n        get_prefect_container(\n            (values.get(\"task_definition\") or {}).get(\"containerDefinitions\", [])\n        )\n        or {}\n    )\n    image_in_task_definition = prefect_container.get(\"image\")\n\n    # If a task_definition is given with a prefect container image, use that value\n    if image_in_task_definition:\n        values[\"image\"] = image_in_task_definition\n    # Otherwise, it should default to the Prefect base image\n    else:\n        values[\"image\"] = get_prefect_image_name()\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a task running on ECS.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>A cluster and task arn combination. This should match a value yielded by <code>ECSTask.run</code>.</p> required Source code in <code>prefect_aws/ecs.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a task running on ECS.\n\n    Args:\n        identifier: A cluster and task arn combination. This should match a value\n            yielded by `ECSTask.run`.\n    \"\"\"\n    if grace_seconds != 30:\n        self.logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n            \"support dynamic grace period configuration so 30s will be used. \"\n            \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n        )\n    cluster, task = parse_task_identifier(identifier)\n    await run_sync_in_worker_thread(self._stop_task, cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Return an copy of the block that is prepared to execute a flow run.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def prepare_for_flow_run(\n    self: Self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"Deployment\"] = None,\n    flow: Optional[\"Flow\"] = None,\n) -&gt; Self:\n    \"\"\"\n    Return an copy of the block that is prepared to execute a flow run.\n    \"\"\"\n    new_family = None\n\n    # Update the family if not specified elsewhere\n    if (\n        not self.family\n        and not self.task_definition_arn\n        and not (self.task_definition and self.task_definition.get(\"family\"))\n    ):\n        if flow and deployment:\n            new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}__{deployment.name}\"\n        elif flow and not deployment:\n            new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}\"\n        elif deployment and not flow:\n            # This is a weird case and should not be see in the wild\n            new_family = f\"{ECS_DEFAULT_FAMILY}__unknown-flow__{deployment.name}\"\n\n    new = super().prepare_for_flow_run(flow_run, deployment=deployment, flow=flow)\n\n    if new_family:\n        return new.copy(update={\"family\": new_family})\n    else:\n        # Avoid an extra copy if not needed\n        return new\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the task definition and task run that will be sent to AWS.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"\n    Generate a preview of the task definition and task run that will be sent to AWS.\n    \"\"\"\n    preview = \"\"\n\n    task_definition_arn = self.task_definition_arn or \"&lt;registered at runtime&gt;\"\n\n    if self.task_definition or not self.task_definition_arn:\n        task_definition = self._prepare_task_definition(\n            self.task_definition or {},\n            region=self.aws_credentials.region_name\n            or \"&lt;loaded from client at runtime&gt;\",\n        )\n        preview += \"---\\n# Task definition\\n\"\n        preview += yaml.dump(task_definition)\n        preview += \"\\n\"\n    else:\n        task_definition = None\n\n    if task_definition and task_definition.get(\"networkMode\") == \"awsvpc\":\n        vpc = \"the default VPC\" if not self.vpc_id else self.vpc_id\n        network_config = {\n            \"awsvpcConfiguration\": {\n                \"subnets\": f\"&lt;loaded from {vpc} at runtime&gt;\",\n                \"assignPublicIp\": \"ENABLED\",\n            }\n        }\n    else:\n        network_config = None\n\n    task_run = self._prepare_task_run(network_config, task_definition_arn)\n    preview += \"---\\n# Task run request\\n\"\n    preview += yaml.dump(task_run)\n\n    return preview\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured task on ECS.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@sync_compatible\nasync def run(self, task_status: Optional[TaskStatus] = None) -&gt; ECSTaskResult:\n    \"\"\"\n    Run the configured task on ECS.\n    \"\"\"\n    boto_session, ecs_client = await run_sync_in_worker_thread(\n        self._get_session_and_client\n    )\n\n    (\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition,\n    ) = await run_sync_in_worker_thread(\n        self._create_task_and_wait_for_start, boto_session, ecs_client\n    )\n\n    # Display a nice message indicating the command and image\n    command = self.command or get_prefect_container(\n        task_definition[\"containerDefinitions\"]\n    ).get(\"command\", [])\n    self.logger.info(\n        f\"{self._log_prefix}: Running command {' '.join(command)!r} \"\n        f\"in container {PREFECT_ECS_CONTAINER_NAME!r} ({self.image})...\"\n    )\n\n    # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n    # if set to preserve matching by name rather than arn\n    # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n    # single colons.\n    identifier = (self.cluster if self.cluster else cluster_arn) + \"::\" + task_arn\n\n    if task_status:\n        task_status.started(identifier)\n\n    status_code = await run_sync_in_worker_thread(\n        self._watch_task_and_get_exit_code,\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition and self.auto_deregister_task_definition,\n        boto_session,\n        ecs_client,\n    )\n\n    return ECSTaskResult(\n        identifier=identifier,\n        # If the container does not start the exit code can be null but we must\n        # still report a status code. We use a -1 to indicate a special code.\n        status_code=status_code if status_code is not None else -1,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.set_default_configure_cloudwatch_logs","title":"<code>set_default_configure_cloudwatch_logs</code>","text":"<p>Streaming output generally requires CloudWatch logs to be configured.</p> <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code> defaults to matching the value of <code>stream_output</code>.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator(pre=True)\ndef set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Streaming output generally requires CloudWatch logs to be configured.\n\n    To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n    defaults to matching the value of `stream_output`.\n    \"\"\"\n    configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n    if configure_cloudwatch_logs is None:\n        values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTaskResult","title":"<code>ECSTaskResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>The result of a run of an ECS task</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>class ECSTaskResult(InfrastructureResult):\n    \"\"\"The result of a run of an ECS task\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.get_container","title":"<code>get_container</code>","text":"<p>Extract a container from a list of containers or container definitions. If not found, <code>None</code> is returned.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def get_container(containers: List[dict], name: str) -&gt; Optional[dict]:\n    \"\"\"\n    Extract a container from a list of containers or container definitions.\n    If not found, `None` is returned.\n    \"\"\"\n    for container in containers:\n        if container.get(\"name\") == name:\n            return container\n    return None\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.get_prefect_container","title":"<code>get_prefect_container</code>","text":"<p>Extract the Prefect container from a list of containers or container definitions. If not found, <code>None</code> is returned.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def get_prefect_container(containers: List[dict]) -&gt; Optional[dict]:\n    \"\"\"\n    Extract the Prefect container from a list of containers or container definitions.\n    If not found, `None` is returned.\n    \"\"\"\n    return get_container(containers, PREFECT_ECS_CONTAINER_NAME)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.parse_task_identifier","title":"<code>parse_task_identifier</code>","text":"<p>Splits identifier into its cluster and task components, e.g. input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def parse_task_identifier(identifier: str) -&gt; Tuple[str, str]:\n    \"\"\"\n    Splits identifier into its cluster and task components, e.g.\n    input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").\n    \"\"\"\n    cluster, task = identifier.split(\"::\", maxsplit=1)\n    return cluster, task\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/","title":"ECS Worker Guide","text":""},{"location":"integrations/prefect-aws/ecs_guide/#why-use-ecs-for-flow-run-execution","title":"Why use ECS for flow run execution?","text":"<p>ECS (Elastic Container Service) tasks are a good option for executing Prefect flow runs for several reasons:</p> <ol> <li>Scalability: ECS scales your infrastructure in response to demand, effectively managing Prefect flow runs. ECS automatically administers container distribution across multiple instances based on demand.</li> <li>Flexibility: ECS lets you choose between AWS Fargate and Amazon EC2 for container operation. Fargate abstracts the underlying infrastructure, while EC2 has faster job start times and offers additional control over instance management and configuration.</li> <li>AWS Integration: Easily connect with other AWS services, such as AWS IAM and CloudWatch.</li> <li>Containerization: ECS supports Docker containers and offers managed execution. Containerization encourages reproducible deployments.</li> </ol>"},{"location":"integrations/prefect-aws/ecs_guide/#ecs-flow-run-execution","title":"ECS flow run execution","text":"<p>Prefect enables remote flow execution via workers and work pools. To learn more about these concepts please see our deployment tutorial.</p> <p>For details on how workers and work pools are implemented for ECS, see the diagram below.</p> <pre><code>%%{\n  init: {\n    'theme': 'base',\n    'themeVariables': {\n      'primaryColor': '#2D6DF6',\n      'primaryTextColor': '#fff',\n      'lineColor': '#FE5A14',\n      'secondaryColor': '#E04BF0',\n      'tertiaryColor': '#fff'\n    }\n  }\n}%%\ngraph TB\n\n  subgraph ecs_cluster[ECS cluster]\n    subgraph ecs_service[ECS service]\n      td_worker[Worker task definition] --&gt; |defines| prefect_worker((Prefect worker))\n    end\n    prefect_worker --&gt;|kicks off| ecs_task\n    fr_task_definition[Flow run task definition]\n\n\n    subgraph ecs_task[\"ECS task execution\"]\n    style ecs_task text-align:center,display:flex\n\n\n    flow_run((Flow run))\n\n    end\n    fr_task_definition --&gt;|defines| ecs_task\n  end\n\n  subgraph prefect_cloud[Prefect Cloud]\n    subgraph prefect_workpool[ECS work pool]\n      workqueue[Work queue]\n    end\n  end\n\n  subgraph github[\"ECR\"]\n    flow_code{{\"Flow code\"}}\n  end\n  flow_code --&gt; |pulls| ecs_task\n  prefect_worker --&gt;|polls| workqueue\n  prefect_workpool --&gt;|configures| fr_task_definition</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#ecs-and-prefect","title":"ECS and Prefect","text":"<p>ECS tasks != Prefect tasks</p> <p>An ECS task is not the same thing as a Prefect task.</p> <p>ECS tasks are groupings of containers that run within an ECS Cluster. An ECS task's behavior is determined by its task definition. </p> <p>An ECS task definition is the blueprint for the ECS task. It describes which Docker containers to run and what you want to have happen inside these containers.</p> <p>ECS tasks are instances of a task definition. A Task Execution launches container(s) as defined in the task definition until they are stopped or exit on their own. This setup is ideal for ephemeral processes such as a Prefect flow run.</p> <p>The ECS task running the Prefect worker should be an ECS Service, given its long-running nature and need for auto-recovery in case of failure. An ECS service automatically replaces any task that fails, which is ideal for managing a long-running process such as a Prefect worker.</p> <p>When a Prefect flow is scheduled to run it goes into the work pool specified in the flow's deployment. Work pools are typed according to the infrastructure the flow will run on. Flow runs scheduled in an <code>ecs</code> typed work pool are executed as ECS tasks. Only Prefect ECS workers can poll an <code>ecs</code> typed work pool.</p> <p>When the ECS worker receives a scheduled flow run from the ECS work pool it is polling, it spins up the specified infrastructure on AWS ECS. The worker knows to build an ECS task definition for each flow run based on the configuration specified in the work pool.</p> <p>Once the flow run completes, the ECS containers of the cluster are spun down to a single container that continues to run the Prefect worker. This worker continues polling for work from the Prefect work pool.</p> <p>If you specify a task definition ARN (Amazon Resource Name) in the work pool, the worker will use that ARN when spinning up the ECS Task, rather than creating a task definition from the fields supplied in the work pool configuration.</p> <p>You can use either EC2 or Fargate as the capacity provider. Fargate simplifies initiation, but lengthens infrastructure setup time for each flow run. Using EC2 for the ECS cluster can reduce setup time. In this example, we will show how to use Fargate.</p> <p>Tip</p> <p>If you prefer infrastructure as code check out this Terraform module to provision an ECS cluster with a worker.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#prerequisites","title":"Prerequisites","text":"<ul> <li>An AWS account with permissions to create ECS services and IAM roles.</li> <li>The AWS CLI installed on your local machine. You can download it from the AWS website.</li> <li>An ECS Cluster to host both the worker and the flow runs it submits. This guide uses the default cluster. To create your own follow this guide.</li> <li>A VPC configured for your ECS tasks. This guide uses the default VPC.</li> <li>Prefect Cloud account or Prefect self-managed instance.</li> </ul>"},{"location":"integrations/prefect-aws/ecs_guide/#step-1-set-up-an-ecs-work-pool","title":"Step 1: Set up an ECS work pool","text":"<p>Before setting up the worker, create a work pool of type ECS for the worker to pull work from. If doing so from the CLI, be sure to authenticate with Prefect Cloud.</p> <p>Create a work pool from the CLI:</p> <pre><code>prefect work-pool create --type ecs my-ecs-pool\n</code></pre> <p>Or from the Prefect UI: </p> <p>!!!     Because this guide uses Fargate as the capacity provider and the default VPC and ECS cluster, no further configuration is needed.</p> <p>Next, set up a Prefect ECS worker that will discover and pull work from this work pool.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-2-start-a-prefect-worker-in-your-ecs-cluster","title":"Step 2: Start a Prefect worker in your ECS cluster","text":"<p>First start by creating the IAM role required in order for your worker and flows to run. The sample flow in this guide doesn't interact with many other AWS services, so you will only be creating one role, <code>taskExecutionRole</code>.  To create an IAM role for the ECS task using the AWS CLI, follow these steps:</p>"},{"location":"integrations/prefect-aws/ecs_guide/#1-create-a-trust-policy","title":"1. Create a trust policy","text":"<p>The trust policy will specify that the ECS service containing the Prefect worker will be able to assume the role required for calling other AWS services.</p> <p>Save this policy to a file, such as <code>ecs-trust-policy.json</code>:</p> <pre><code>{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Principal\": {\n                \"Service\": \"ecs-tasks.amazonaws.com\"\n            },\n            \"Action\": \"sts:AssumeRole\"\n        }\n    ]\n}\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#2-create-the-iam-roles","title":"2. Create the IAM roles","text":"<p>Use the <code>aws iam create-role</code> command to create the roles that you will be using. For this guide, the <code>ecsTaskExecutionRole</code> will be used by the worker to start ECS tasks, and will also be the role assigned to the ECS tasks running your Prefect flows.</p> <pre><code>    aws iam create-role \\\n    --role-name ecsTaskExecutionRole \\\n    --assume-role-policy-document file://ecs-trust-policy.json\n</code></pre> <p>Tip</p> <p>Depending on the requirements of your flows, it is advised to create a second role for your ECS tasks. This role will contain the permissions required by the ECS tasks in which your flows will run. For example, if your workflow loads data into an S3 bucket, you would need a role with additional permissions to access S3.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#3-attach-the-policy-to-the-role","title":"3. Attach the policy to the role","text":"<p>For this guide the ECS worker will require permissions to pull images from ECR and publish logs to CloudWatch. Amazon has a managed policy named <code>AmazonECSTaskExecutionRolePolicy</code> that grants the permissions necessary for starting ECS tasks. See here for other common execution role permissions. Attach this policy to your task execution role:</p> <pre><code>    aws iam attach-role-policy \\\n    --role-name ecsTaskExecutionRole \\\n    --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy\n</code></pre> <p>Remember to replace the <code>--role-name</code> and <code>--policy-arn</code> with the actual role name and policy Amazon Resource Name (ARN) you want to use.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-3-creating-an-ecs-worker-service","title":"Step 3: Creating an ECS worker service","text":""},{"location":"integrations/prefect-aws/ecs_guide/#1-launch-an-ecs-service-to-host-the-worker","title":"1. Launch an ECS Service to host the worker","text":"<p>Next, create an ECS task definition that specifies the Docker image for the Prefect worker, the resources it requires, and the command it should run. In this example, the command to start the worker is <code>prefect worker start --pool my-ecs-pool</code>.</p> <p>Create a JSON file with the following contents:</p> <pre><code>{\n    \"family\": \"prefect-worker-task\",\n    \"networkMode\": \"awsvpc\",\n    \"requiresCompatibilities\": [\n        \"FARGATE\"\n    ],\n    \"cpu\": \"512\",\n    \"memory\": \"1024\",\n    \"executionRoleArn\": \"&lt;ecs-task-role-arn&gt;\",\n    \"taskRoleArn\": \"&lt;ecs-task-role-arn&gt;\",\n    \"containerDefinitions\": [\n        {\n            \"name\": \"prefect-worker\",\n            \"image\": \"prefecthq/prefect:2-latest\",\n            \"cpu\": 512,\n            \"memory\": 1024,\n            \"essential\": true,\n            \"command\": [\n                \"/bin/sh\",\n                \"-c\",\n                \"pip install prefect-aws &amp;&amp; prefect worker start --pool my-ecs-pool --type ecs\"\n            ],\n            \"environment\": [\n                {\n                    \"name\": \"PREFECT_API_URL\",\n                    \"value\": \"prefect-api-url&gt;\"\n                },\n                {\n                    \"name\": \"PREFECT_API_KEY\",\n                    \"value\": \"&lt;prefect-api-key&gt;\"\n                }\n            ]\n        }\n    ]\n}\n</code></pre> <ul> <li> <p>Use <code>prefect config view</code> to view the <code>PREFECT_API_URL</code> for your current Prefect profile. Use this to replace <code>&lt;prefect-api-url&gt;</code>.</p> </li> <li> <p>For the <code>PREFECT_API_KEY</code>, if you are on a paid plan you can create a service account for the worker. If your are on a free plan, you can pass a user\u2019s API key.</p> </li> <li> <p>Replace both instances of <code>&lt;ecs-task-role-arn&gt;</code> with the ARN of the IAM role you created in Step 2. You can grab this by running: <pre><code>aws iam get-role --role-name taskExecutionRole --query 'Role.[RoleName, Arn]' --output text\n</code></pre></p> </li> <li> <p>Notice that the CPU and Memory allocations are relatively small. The worker's main responsibility is to submit work through API calls to AWS, not to execute your Prefect flow code.</p> </li> </ul> <p>Tip</p> <p>To avoid hardcoding your API key into the task definition JSON see how to add sensitive data using AWS secrets manager to the container definition.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#2-register-the-task-definition","title":"2. Register the task definition","text":"<p>Before creating a service, you first need to register a task definition. You can do that using the <code>register-task-definition</code> command in the AWS CLI. Here is an example:</p> <pre><code>aws ecs register-task-definition --cli-input-json file://task-definition.json\n</code></pre> <p>Replace <code>task-definition.json</code> with the name of your JSON file.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#3-create-an-ecs-service-to-host-your-worker","title":"3. Create an ECS service to host your worker","text":"<p>Finally, create a service that will manage your Prefect worker:</p> <p>Open a terminal window and run the following command to create an ECS Fargate service:</p> <pre><code>aws ecs create-service \\\n    --service-name prefect-worker-service \\\n    --cluster &lt;ecs-cluster&gt; \\\n    --task-definition &lt;task-definition-arn&gt; \\\n    --launch-type FARGATE \\\n    --desired-count 1 \\\n    --network-configuration \"awsvpcConfiguration={subnets=[&lt;subnet-ids&gt;],securityGroups=[&lt;security-group-ids&gt;],assignPublicIp='ENABLED'}\"\n</code></pre> <ul> <li>Replace <code>&lt;ecs-cluster&gt;</code> with the name of your ECS cluster.</li> <li>Replace <code>&lt;task-definition-arn&gt;</code> with the ARN of the task definition you just registered.</li> <li>Replace <code>&lt;subnet-ids&gt;</code> with a comma-separated list of your VPC subnet IDs. Ensure that these subnets are aligned with the vpc specified on the work pool in step 1. You can view subnet ids with the following command:     <code>aws ec2 describe-subnets --filter Name=&lt;vpc-id&gt;</code></li> <li>Replace <code>&lt;security-group-ids&gt;</code> with a comma-separated list of your VPC security group IDs.</li> </ul> <p>Sanity check</p> <p>The work pool page in the Prefect UI allows you to check the health of your workers - make sure your new worker is live! Note that it can take a few minutes for an ECS service to come online. If your worker does not come online and you are using the command from this guide, you may not be using the default VPC. For connectivity issues, check your VPC's configuration and refer to the ECS outbound networking guide.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-4-pick-up-a-flow-run-with-your-new-worker","title":"Step 4: Pick up a flow run with your new worker","text":"<p>This guide uses ECR to store a Docker image containing your flow code. To do this, we will write a flow, then deploy it using build and push steps that copy flow code into a Docker image and push that image to an ECR repository.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#1-write-a-simple-test-flow","title":"1. Write a simple test flow","text":"<p><code>my_flow.py</code></p> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"Hello from ECS!!\")\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#2-create-an-ecr-repository","title":"2. Create an ECR repository","text":"<p>Use the following AWS CLI command to create an ECR repository. The name you choose for your repository will be reused in the next step when defining your Prefect deployment.</p> <pre><code>aws ecr create-repository \\\n--repository-name &lt;my-ecr-repo&gt; \\\n--region &lt;region&gt;\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#3-create-a-prefectyaml-file","title":"3. Create a <code>prefect.yaml</code> file","text":"<p>To have Prefect build your image when deploying your flow create a <code>prefect.yaml</code> file with the following specification:</p> <pre><code>name: ecs-worker-guide\n# this is pre-populated by running prefect init\nprefect-version: 2.14.20 \n\n# build section allows you to manage and build docker images\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build_image\n    requires: prefect-docker&gt;=0.3.1\n    image_name: &lt;my-ecr-repo&gt;\n    tag: latest\n    dockerfile: auto\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.3.1\n    image_name: '{{ build_image.image_name }}'\n    tag: '{{ build_image.tag }}'\n\n # the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: my_ecs_deployment\n    version:\n    tags: []\n    description:\n    entrypoint: flow.py:my_flow\n    parameters: {}\n    work_pool:\n        name: ecs-dev-pool\n        work_queue_name:\n        job_variables:\n        image: '{{ build_image.image }}'\n    schedules: []\npull:\n    - prefect.deployments.steps.set_working_directory:\n        directory: /opt/prefect/ecs-worker-guide\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#4-deploy-the-flow-to-the-prefect-cloud-or-your-self-managed-server-instance-specifying-the-ecs-work-pool-when-prompted","title":"4. Deploy the flow to the Prefect Cloud or your self-managed server instance, specifying the ECS work pool when prompted","text":"<pre><code>prefect deploy my_flow.py:my_ecs_deployment\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#5-find-the-deployment-in-the-ui-and-click-the-quick-run-button","title":"5. Find the deployment in the UI and click the Quick Run button!","text":""},{"location":"integrations/prefect-aws/ecs_guide/#optional-next-steps","title":"Optional next steps","text":"<ol> <li> <p>Now that you are confident your ECS worker is healthy, you can experiment with different work pool configurations.</p> <ul> <li>Do your flow runs require higher <code>CPU</code>?</li> <li>Would an EC2 <code>Launch Type</code> speed up your flow run execution?</li> </ul> <p>These infrastructure configuration values can be set on your ECS work pool or they can be overridden on the deployment level through job_variables if desired.</p> </li> </ol>"},{"location":"integrations/prefect-aws/ecs_worker/","title":"ECS Worker","text":""},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker","title":"<code>prefect_aws.workers.ecs_worker</code>","text":"<p>Prefect worker for executing flow runs as ECS tasks.</p> <p>Get started by creating a work pool:</p> <pre><code>$ prefect work-pool create --type ecs my-ecs-pool\n</code></pre> <p>Then, you can start a worker for the pool:</p> <pre><code>$ prefect worker start --pool my-ecs-pool\n</code></pre> <p>It's common to deploy the worker as an ECS task as well. However, you can run the worker locally to get started.</p> <p>The worker may work without any additional configuration, but it is dependent on your specific AWS setup and we'd recommend opening the work pool editor in the UI to see the available options.</p> <p>By default, the worker will register a task definition for each flow run and run a task in your default ECS cluster using AWS Fargate. Fargate requires tasks to configure subnets, which we will infer from your default VPC. If you do not have a default VPC, you must provide a VPC ID or manually setup the network configuration for your tasks.</p> <p>Note, the worker caches task definitions for each deployment to avoid excessive registration. The worker will check that the cached task definition is compatible with your configuration before using it.</p> <p>The launch type option can be used to run your tasks in different modes. For example, <code>FARGATE_SPOT</code> can be used to use spot instances for your Fargate tasks or <code>EC2</code> can be used to run your tasks on a cluster backed by EC2 instances.</p> <p>Generally, it is very useful to enable CloudWatch logging for your ECS tasks; this can help you debug task failures. To enable CloudWatch logging, you must provide an execution role ARN with permissions to create and write to log streams. See the <code>configure_cloudwatch_logs</code> field documentation for details.</p> <p>The worker can be configured to use an existing task definition by setting the task definition arn variable or by providing a \"taskDefinition\" in the task run request. When a task definition is provided, the worker will never create a new task definition which may result in variables that are templated into the task definition payload being ignored.</p>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.CapacityProvider","title":"<code>CapacityProvider</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>The capacity provider strategy to use when running the task.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class CapacityProvider(BaseModel):\n    \"\"\"\n    The capacity provider strategy to use when running the task.\n    \"\"\"\n\n    capacityProvider: str\n    weight: int\n    base: int\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSIdentifier","title":"<code>ECSIdentifier</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>The identifier for a running ECS task.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSIdentifier(NamedTuple):\n    \"\"\"\n    The identifier for a running ECS task.\n    \"\"\"\n\n    cluster: str\n    task_arn: str\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration","title":"<code>ECSJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Job configuration for an ECS worker.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Job configuration for an ECS worker.\n    \"\"\"\n\n    aws_credentials: Optional[AwsCredentials] = Field(default_factory=AwsCredentials)\n    task_definition: Optional[Dict[str, Any]] = Field(\n        template=_default_task_definition_template()\n    )\n    task_run_request: Dict[str, Any] = Field(\n        template=_default_task_run_request_template()\n    )\n    configure_cloudwatch_logs: Optional[bool] = Field(default=None)\n    cloudwatch_logs_options: Dict[str, str] = Field(default_factory=dict)\n    cloudwatch_logs_prefix: Optional[str] = Field(default=None)\n    network_configuration: Dict[str, Any] = Field(default_factory=dict)\n    stream_output: Optional[bool] = Field(default=None)\n    task_start_timeout_seconds: int = Field(default=300)\n    task_watch_poll_interval: float = Field(default=5.0)\n    auto_deregister_task_definition: bool = Field(default=False)\n    vpc_id: Optional[str] = Field(default=None)\n    container_name: Optional[str] = Field(default=None)\n    cluster: Optional[str] = Field(default=None)\n    match_latest_revision_in_family: bool = Field(default=False)\n\n    @root_validator\n    def task_run_request_requires_arn_if_no_task_definition_given(cls, values) -&gt; dict:\n        \"\"\"\n        If no task definition is provided, a task definition ARN must be present on the\n        task run request.\n        \"\"\"\n        if not values.get(\"task_run_request\", {}).get(\n            \"taskDefinition\"\n        ) and not values.get(\"task_definition\"):\n            raise ValueError(\n                \"A task definition must be provided if a task definition ARN is not \"\n                \"present on the task run request.\"\n            )\n        return values\n\n    @root_validator\n    def container_name_default_from_task_definition(cls, values) -&gt; dict:\n        \"\"\"\n        Infers the container name from the task definition if not provided.\n        \"\"\"\n        if values.get(\"container_name\") is None:\n            values[\"container_name\"] = _container_name_from_task_definition(\n                values.get(\"task_definition\")\n            )\n\n            # We may not have a name here still; for example if someone is using a task\n            # definition arn. In that case, we'll perform similar logic later to find\n            # the name to treat as the \"orchestration\" container.\n\n        return values\n\n    @root_validator(pre=True)\n    def set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Streaming output generally requires CloudWatch logs to be configured.\n\n        To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n        defaults to matching the value of `stream_output`.\n        \"\"\"\n        configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n        if configure_cloudwatch_logs is None:\n            values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n        return values\n\n    @root_validator\n    def configure_cloudwatch_logs_requires_execution_role_arn(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if (\n            values.get(\"configure_cloudwatch_logs\")\n            and not values.get(\"execution_role_arn\")\n            # TODO: Does not match\n            # Do not raise if they've linked to another task definition or provided\n            # it without using our shortcuts\n            and not values.get(\"task_run_request\", {}).get(\"taskDefinition\")\n            and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n        ):\n            raise ValueError(\n                \"An `execution_role_arn` must be provided to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs`.\"\n            )\n        return values\n\n    @root_validator\n    def cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if values.get(\"cloudwatch_logs_options\") and not values.get(\n            \"configure_cloudwatch_logs\"\n        ):\n            raise ValueError(\n                \"`configure_cloudwatch_log` must be enabled to use \"\n                \"`cloudwatch_logs_options`.\"\n            )\n        return values\n\n    @root_validator\n    def network_configuration_requires_vpc_id(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Enforces a `vpc_id` is provided when custom network configuration mode is\n        enabled for network settings.\n        \"\"\"\n        if values.get(\"network_configuration\") and not values.get(\"vpc_id\"):\n            raise ValueError(\n                \"You must provide a `vpc_id` to enable custom `network_configuration`.\"\n            )\n        return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.cloudwatch_logs_options_requires_configure_cloudwatch_logs","title":"<code>cloudwatch_logs_options_requires_configure_cloudwatch_logs</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if values.get(\"cloudwatch_logs_options\") and not values.get(\n        \"configure_cloudwatch_logs\"\n    ):\n        raise ValueError(\n            \"`configure_cloudwatch_log` must be enabled to use \"\n            \"`cloudwatch_logs_options`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.configure_cloudwatch_logs_requires_execution_role_arn","title":"<code>configure_cloudwatch_logs_requires_execution_role_arn</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef configure_cloudwatch_logs_requires_execution_role_arn(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if (\n        values.get(\"configure_cloudwatch_logs\")\n        and not values.get(\"execution_role_arn\")\n        # TODO: Does not match\n        # Do not raise if they've linked to another task definition or provided\n        # it without using our shortcuts\n        and not values.get(\"task_run_request\", {}).get(\"taskDefinition\")\n        and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n    ):\n        raise ValueError(\n            \"An `execution_role_arn` must be provided to use \"\n            \"`configure_cloudwatch_logs` or `stream_logs`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.container_name_default_from_task_definition","title":"<code>container_name_default_from_task_definition</code>","text":"<p>Infers the container name from the task definition if not provided.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef container_name_default_from_task_definition(cls, values) -&gt; dict:\n    \"\"\"\n    Infers the container name from the task definition if not provided.\n    \"\"\"\n    if values.get(\"container_name\") is None:\n        values[\"container_name\"] = _container_name_from_task_definition(\n            values.get(\"task_definition\")\n        )\n\n        # We may not have a name here still; for example if someone is using a task\n        # definition arn. In that case, we'll perform similar logic later to find\n        # the name to treat as the \"orchestration\" container.\n\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.network_configuration_requires_vpc_id","title":"<code>network_configuration_requires_vpc_id</code>","text":"<p>Enforces a <code>vpc_id</code> is provided when custom network configuration mode is enabled for network settings.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef network_configuration_requires_vpc_id(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Enforces a `vpc_id` is provided when custom network configuration mode is\n    enabled for network settings.\n    \"\"\"\n    if values.get(\"network_configuration\") and not values.get(\"vpc_id\"):\n        raise ValueError(\n            \"You must provide a `vpc_id` to enable custom `network_configuration`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.set_default_configure_cloudwatch_logs","title":"<code>set_default_configure_cloudwatch_logs</code>","text":"<p>Streaming output generally requires CloudWatch logs to be configured.</p> <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code> defaults to matching the value of <code>stream_output</code>.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator(pre=True)\ndef set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Streaming output generally requires CloudWatch logs to be configured.\n\n    To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n    defaults to matching the value of `stream_output`.\n    \"\"\"\n    configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n    if configure_cloudwatch_logs is None:\n        values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.task_run_request_requires_arn_if_no_task_definition_given","title":"<code>task_run_request_requires_arn_if_no_task_definition_given</code>","text":"<p>If no task definition is provided, a task definition ARN must be present on the task run request.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef task_run_request_requires_arn_if_no_task_definition_given(cls, values) -&gt; dict:\n    \"\"\"\n    If no task definition is provided, a task definition ARN must be present on the\n    task run request.\n    \"\"\"\n    if not values.get(\"task_run_request\", {}).get(\n        \"taskDefinition\"\n    ) and not values.get(\"task_definition\"):\n        raise ValueError(\n            \"A task definition must be provided if a task definition ARN is not \"\n            \"present on the task run request.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSVariables","title":"<code>ECSVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Variables for templating an ECS job.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSVariables(BaseVariables):\n    \"\"\"\n    Variables for templating an ECS job.\n    \"\"\"\n\n    task_definition_arn: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier for an existing task definition to use. If set, options that\"\n            \" require changes to the task definition will be ignored. All contents of \"\n            \"the task definition in the job configuration will be ignored.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=(\n            \"The AWS credentials to use to connect to ECS. If not provided, credentials\"\n            \" will be inferred from the local environment following AWS's boto client's\"\n            \" rules.\"\n        ),\n    )\n    cluster: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The ECS cluster to run the task in. An ARN or name may be provided. If \"\n            \"not provided, the default cluster will be used.\"\n        ),\n    )\n    family: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A family for the task definition. If not provided, it will be inferred \"\n            \"from the task definition. If the task definition does not have a family, \"\n            \"the name will be generated. When flow and deployment metadata is \"\n            \"available, the generated name will include their names. Values for this \"\n            \"field will be slugified to match AWS character requirements.\"\n        ),\n    )\n    launch_type: Optional[\n        Literal[\"FARGATE\", \"EC2\", \"EXTERNAL\", \"FARGATE_SPOT\"]\n    ] = Field(\n        default=ECS_DEFAULT_LAUNCH_TYPE,\n        description=(\n            \"The type of ECS task run infrastructure that should be used. Note that\"\n            \" 'FARGATE_SPOT' is not a formal ECS launch type, but we will configure\"\n            \" the proper capacity provider strategy if set here.\"\n        ),\n    )\n    capacity_provider_strategy: Optional[List[CapacityProvider]] = Field(\n        default_factory=list,\n        description=(\n            \"The capacity provider strategy to use when running the task. \"\n            \"If a capacity provider strategy is specified, the selected launch\"\n            \" type will be ignored.\"\n        ),\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. If this value is \"\n            \"not null, it will override the value in the task definition. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    cpu: int = Field(\n        title=\"CPU\",\n        default=None,\n        description=(\n            \"The amount of CPU to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_CPU} will be used unless present on the task definition.\"\n        ),\n    )\n    memory: int = Field(\n        default=None,\n        description=(\n            \"The amount of memory to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_MEMORY} will be used unless present on the task definition.\"\n        ),\n    )\n    container_name: str = Field(\n        default=None,\n        description=(\n            \"The name of the container flow run orchestration will occur in. If not \"\n            f\"specified, a default value of {ECS_DEFAULT_CONTAINER_NAME} will be used \"\n            \"and if that is not found in the task definition the first container will \"\n            \"be used.\"\n        ),\n    )\n    task_role_arn: str = Field(\n        title=\"Task Role ARN\",\n        default=None,\n        description=(\n            \"A role to attach to the task run. This controls the permissions of the \"\n            \"task while it is running.\"\n        ),\n    )\n    execution_role_arn: str = Field(\n        title=\"Execution Role ARN\",\n        default=None,\n        description=(\n            \"An execution role to use for the task. This controls the permissions of \"\n            \"the task when it is launching. If this value is not null, it will \"\n            \"override the value in the task definition. An execution role must be \"\n            \"provided to capture logs from the container.\"\n        ),\n    )\n    vpc_id: Optional[str] = Field(\n        title=\"VPC ID\",\n        default=None,\n        description=(\n            \"The AWS VPC to link the task run to. This is only applicable when using \"\n            \"the 'awsvpc' network mode for your task. FARGATE tasks require this \"\n            \"network  mode, but for EC2 tasks the default network mode is 'bridge'. \"\n            \"If using the 'awsvpc' network mode and this field is null, your default \"\n            \"VPC will be used. If no default VPC can be found, the task run will fail.\"\n        ),\n    )\n    configure_cloudwatch_logs: bool = Field(\n        default=None,\n        description=(\n            \"If enabled, the Prefect container will be configured to send its output \"\n            \"to the AWS CloudWatch logs service. This functionality requires an \"\n            \"execution role with logs:CreateLogStream, logs:CreateLogGroup, and \"\n            \"logs:PutLogEvents permissions. The default for this field is `False` \"\n            \"unless `stream_output` is set.\"\n        ),\n    )\n    cloudwatch_logs_options: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to\"\n            \" pass additional options to the CloudWatch logs configuration or override\"\n            \" the default options. See the [AWS\"\n            \" documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html#create_awslogs_logdriver_options)\"  # noqa\n            \" for available options. \"\n        ),\n    )\n    cloudwatch_logs_prefix: Optional[str] = Field(\n        default=None,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to\"\n            \" set a prefix for the log group. If not provided, the default prefix will\"\n            \" be `prefect-logs_&lt;work_pool_name&gt;_&lt;deployment_id&gt;`. If\"\n            \" `awslogs-stream-prefix` is present in `Cloudwatch logs options` this\"\n            \" setting will be ignored.\"\n        ),\n    )\n\n    network_configuration: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=(\n            \"When `network_configuration` is supplied it will override ECS Worker's\"\n            \"awsvpcConfiguration that defined in the ECS task executing your workload. \"\n            \"See the [AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-awsvpcconfiguration.html)\"  # noqa\n            \" for available options.\"\n        ),\n    )\n\n    stream_output: bool = Field(\n        default=None,\n        description=(\n            \"If enabled, logs will be streamed from the Prefect container to the local \"\n            \"console. Unless you have configured AWS CloudWatch logs manually on your \"\n            \"task definition, this requires the same prerequisites outlined in \"\n            \"`configure_cloudwatch_logs`.\"\n        ),\n    )\n    task_start_timeout_seconds: int = Field(\n        default=300,\n        description=(\n            \"The amount of time to watch for the start of the ECS task \"\n            \"before marking it as failed. The task must enter a RUNNING state to be \"\n            \"considered started.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an ECS task.\"\n        ),\n    )\n    auto_deregister_task_definition: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, any task definitions that are created by this block will be \"\n            \"deregistered. Existing task definitions linked by ARN will never be \"\n            \"deregistered. Deregistering a task definition does not remove it from \"\n            \"your AWS account, instead it will be marked as INACTIVE.\"\n        ),\n    )\n    match_latest_revision_in_family: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, the most recent active revision in the task definition \"\n            \"family will be compared against the desired ECS task configuration. \"\n            \"If they are equal, the existing task definition will be used instead \"\n            \"of registering a new one. If no family is specified the default family \"\n            f'\"{ECS_DEFAULT_FAMILY}\" will be used.'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker","title":"<code>ECSWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>A Prefect worker to run flow runs as ECS tasks.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSWorker(BaseWorker):\n    \"\"\"\n    A Prefect worker to run flow runs as ECS tasks.\n    \"\"\"\n\n    type = \"ecs\"\n    job_configuration = ECSJobConfiguration\n    job_configuration_variables = ECSVariables\n    _description = (\n        \"Execute flow runs within containers on AWS ECS. Works with EC2 \"\n        \"and Fargate clusters. Requires an AWS account.\"\n    )\n    _display_name = \"AWS Elastic Container Service\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/ecs_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: ECSJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; ECSWorkerResult:\n        \"\"\"\n        Runs a given flow run on the current worker.\n        \"\"\"\n        ecs_client = await run_sync_in_worker_thread(\n            self._get_client, configuration, \"ecs\"\n        )\n\n        logger = self.get_flow_run_logger(flow_run)\n\n        (\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition,\n        ) = await run_sync_in_worker_thread(\n            self._create_task_and_wait_for_start,\n            logger,\n            ecs_client,\n            configuration,\n            flow_run,\n        )\n\n        # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n        # if set to preserve matching by name rather than arn\n        # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n        # single colons.\n        identifier = (\n            (configuration.cluster if configuration.cluster else cluster_arn)\n            + \"::\"\n            + task_arn\n        )\n\n        if task_status:\n            task_status.started(identifier)\n\n        status_code = await run_sync_in_worker_thread(\n            self._watch_task_and_get_exit_code,\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition and configuration.auto_deregister_task_definition,\n            ecs_client,\n        )\n\n        return ECSWorkerResult(\n            identifier=identifier,\n            # If the container does not start the exit code can be null but we must\n            # still report a status code. We use a -1 to indicate a special code.\n            status_code=status_code if status_code is not None else -1,\n        )\n\n    def _get_client(\n        self, configuration: ECSJobConfiguration, client_type: Union[str, ClientType]\n    ) -&gt; _ECSClient:\n        \"\"\"\n        Get a boto3 client of client_type. Will use a cached client if one exists.\n        \"\"\"\n        return configuration.aws_credentials.get_client(client_type)\n\n    def _create_task_and_wait_for_start(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        configuration: ECSJobConfiguration,\n        flow_run: FlowRun,\n    ) -&gt; Tuple[str, str, dict, bool]:\n        \"\"\"\n        Register the task definition, create the task run, and wait for it to start.\n\n        Returns a tuple of\n        - The task ARN\n        - The task's cluster ARN\n        - The task definition\n        - A bool indicating if the task definition is newly registered\n        \"\"\"\n        task_definition_arn = configuration.task_run_request.get(\"taskDefinition\")\n        new_task_definition_registered = False\n\n        if not task_definition_arn:\n            task_definition = self._prepare_task_definition(\n                configuration, region=ecs_client.meta.region_name, flow_run=flow_run\n            )\n            (\n                task_definition_arn,\n                new_task_definition_registered,\n            ) = self._get_or_register_task_definition(\n                logger, ecs_client, configuration, flow_run, task_definition\n            )\n        else:\n            task_definition = self._retrieve_task_definition(\n                logger, ecs_client, task_definition_arn\n            )\n            if configuration.task_definition:\n                logger.warning(\n                    \"Ignoring task definition in configuration since task definition\"\n                    \" ARN is provided on the task run request.\"\n                )\n\n        self._validate_task_definition(task_definition, configuration)\n\n        _TASK_DEFINITION_CACHE[flow_run.deployment_id] = task_definition_arn\n\n        logger.info(f\"Using ECS task definition {task_definition_arn!r}...\")\n        logger.debug(\n            f\"Task definition {json.dumps(task_definition, indent=2, default=str)}\"\n        )\n\n        task_run_request = self._prepare_task_run_request(\n            configuration,\n            task_definition,\n            task_definition_arn,\n        )\n\n        logger.info(\"Creating ECS task run...\")\n        logger.debug(\n            \"Task run request\"\n            f\"{json.dumps(mask_api_key(task_run_request), indent=2, default=str)}\"\n        )\n\n        try:\n            task = self._create_task_run(ecs_client, task_run_request)\n            task_arn = task[\"taskArn\"]\n            cluster_arn = task[\"clusterArn\"]\n        except Exception as exc:\n            self._report_task_run_creation_failure(configuration, task_run_request, exc)\n            raise\n\n        logger.info(\"Waiting for ECS task run to start...\")\n        self._wait_for_task_start(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            timeout=configuration.task_start_timeout_seconds,\n        )\n\n        return task_arn, cluster_arn, task_definition, new_task_definition_registered\n\n    def _get_or_register_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        configuration: ECSJobConfiguration,\n        flow_run: FlowRun,\n        task_definition: dict,\n    ) -&gt; Tuple[str, bool]:\n        \"\"\"Get or register a task definition for the given flow run.\n\n        Returns a tuple of the task definition ARN and a bool indicating if the task\n        definition is newly registered.\n        \"\"\"\n\n        cached_task_definition_arn = _TASK_DEFINITION_CACHE.get(flow_run.deployment_id)\n        new_task_definition_registered = False\n\n        if cached_task_definition_arn:\n            try:\n                cached_task_definition = self._retrieve_task_definition(\n                    logger, ecs_client, cached_task_definition_arn\n                )\n                if not cached_task_definition[\n                    \"status\"\n                ] == \"ACTIVE\" or not self._task_definitions_equal(\n                    task_definition, cached_task_definition\n                ):\n                    cached_task_definition_arn = None\n            except Exception:\n                cached_task_definition_arn = None\n\n        if (\n            not cached_task_definition_arn\n            and configuration.match_latest_revision_in_family\n        ):\n            family_name = task_definition.get(\"family\", ECS_DEFAULT_FAMILY)\n            try:\n                task_definition_from_family = self._retrieve_task_definition(\n                    logger, ecs_client, family_name\n                )\n                if task_definition_from_family and self._task_definitions_equal(\n                    task_definition, task_definition_from_family\n                ):\n                    cached_task_definition_arn = task_definition_from_family[\n                        \"taskDefinitionArn\"\n                    ]\n            except Exception:\n                cached_task_definition_arn = None\n\n        if not cached_task_definition_arn:\n            task_definition_arn = self._register_task_definition(\n                logger, ecs_client, task_definition\n            )\n            new_task_definition_registered = True\n        else:\n            task_definition_arn = cached_task_definition_arn\n\n        return task_definition_arn, new_task_definition_registered\n\n    def _watch_task_and_get_exit_code(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        deregister_task_definition: bool,\n        ecs_client: _ECSClient,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Wait for the task run to complete and retrieve the exit code of the Prefect\n        container.\n        \"\"\"\n\n        # Wait for completion and stream logs\n        task = self._wait_for_task_finish(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            ecs_client,\n        )\n\n        if deregister_task_definition:\n            ecs_client.deregister_task_definition(\n                taskDefinition=task[\"taskDefinitionArn\"]\n            )\n\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        # Check the status code of the Prefect container\n        container = _get_container(task[\"containers\"], container_name)\n        assert (\n            container is not None\n        ), f\"'{container_name}' container missing from task: {task}\"\n        status_code = container.get(\"exitCode\")\n        self._report_container_status_code(logger, container_name, status_code)\n\n        return status_code\n\n    def _report_container_status_code(\n        self, logger: logging.Logger, name: str, status_code: Optional[int]\n    ) -&gt; None:\n        \"\"\"\n        Display a log for the given container status code.\n        \"\"\"\n        if status_code is None:\n            logger.error(\n                f\"Task exited without reporting an exit status for container {name!r}.\"\n            )\n        elif status_code == 0:\n            logger.info(f\"Container {name!r} exited successfully.\")\n        else:\n            logger.warning(\n                f\"Container {name!r} exited with non-zero exit code {status_code}.\"\n            )\n\n    def _report_task_run_creation_failure(\n        self, configuration: ECSJobConfiguration, task_run: dict, exc: Exception\n    ) -&gt; None:\n        \"\"\"\n        Wrap common AWS task run creation failures with nicer user-facing messages.\n        \"\"\"\n        # AWS generates exception types at runtime so they must be captured a bit\n        # differently than normal.\n        if \"ClusterNotFoundException\" in str(exc):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} not found. \"\n                \"Confirm that the cluster is configured in your region.\"\n            ) from exc\n        elif (\n            \"No Container Instances\" in str(exc) and task_run.get(\"launchType\") == \"EC2\"\n        ):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} does not appear to \"\n                \"have any container instances associated with it. Confirm that you \"\n                \"have EC2 container instances available.\"\n            ) from exc\n        elif (\n            \"failed to validate logger args\" in str(exc)\n            and \"AccessDeniedException\" in str(exc)\n            and configuration.configure_cloudwatch_logs\n        ):\n            raise RuntimeError(\n                \"Failed to run ECS task, the attached execution role does not appear\"\n                \" to have sufficient permissions. Ensure that the execution role\"\n                f\" {configuration.execution_role!r} has permissions\"\n                \" logs:CreateLogStream, logs:CreateLogGroup, and logs:PutLogEvents.\"\n            )\n        else:\n            raise\n\n    def _validate_task_definition(\n        self, task_definition: dict, configuration: ECSJobConfiguration\n    ) -&gt; None:\n        \"\"\"\n        Ensure that the task definition is compatible with the configuration.\n\n        Raises `ValueError` on incompatibility. Returns `None` on success.\n        \"\"\"\n        launch_type = configuration.task_run_request.get(\n            \"launchType\", ECS_DEFAULT_LAUNCH_TYPE\n        )\n        if (\n            launch_type != \"EC2\"\n            and \"FARGATE\" not in task_definition[\"requiresCompatibilities\"]\n        ):\n            raise ValueError(\n                \"Task definition does not have 'FARGATE' in 'requiresCompatibilities'\"\n                f\" and cannot be used with launch type {launch_type!r}\"\n            )\n\n        if launch_type == \"FARGATE\" or launch_type == \"FARGATE_SPOT\":\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            network_mode = task_definition.get(\"networkMode\")\n            if network_mode != \"awsvpc\":\n                raise ValueError(\n                    f\"Found network mode {network_mode!r} which is not compatible with \"\n                    f\"launch type {launch_type!r}. Use either the 'EC2' launch \"\n                    \"type or the 'awsvpc' network mode.\"\n                )\n\n        if configuration.configure_cloudwatch_logs and not task_definition.get(\n            \"executionRoleArn\"\n        ):\n            raise ValueError(\n                \"An execution role arn must be set on the task definition to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs` but no execution role \"\n                \"was found on the task definition.\"\n            )\n\n    def _register_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        task_definition: dict,\n    ) -&gt; str:\n        \"\"\"\n        Register a new task definition with AWS.\n\n        Returns the ARN.\n        \"\"\"\n        logger.info(\"Registering ECS task definition...\")\n        logger.debug(\n            \"Task definition request\"\n            f\"{json.dumps(task_definition, indent=2, default=str)}\"\n        )\n        response = ecs_client.register_task_definition(**task_definition)\n        return response[\"taskDefinition\"][\"taskDefinitionArn\"]\n\n    def _retrieve_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        task_definition: str,\n    ):\n        \"\"\"\n        Retrieve an existing task definition from AWS.\n        \"\"\"\n        if task_definition.startswith(\"arn:aws:ecs:\"):\n            logger.info(f\"Retrieving ECS task definition {task_definition!r}...\")\n        else:\n            logger.info(\n                \"Retrieving most recent active revision from \"\n                f\"ECS task family {task_definition!r}...\"\n            )\n        response = ecs_client.describe_task_definition(taskDefinition=task_definition)\n        return response[\"taskDefinition\"]\n\n    def _wait_for_task_start(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        timeout: int,\n    ) -&gt; dict:\n        \"\"\"\n        Waits for an ECS task run to reach a RUNNING status.\n\n        If a STOPPED status is reached instead, an exception is raised indicating the\n        reason that the task run did not start.\n        \"\"\"\n        for task in self._watch_task_run(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            until_status=\"RUNNING\",\n            timeout=timeout,\n        ):\n            # TODO: It is possible that the task has passed _through_ a RUNNING\n            #       status during the polling interval. In this case, there is not an\n            #       exception to raise.\n            if task[\"lastStatus\"] == \"STOPPED\":\n                code = task.get(\"stopCode\")\n                reason = task.get(\"stoppedReason\")\n                # Generate a dynamic exception type from the AWS name\n                raise type(code, (RuntimeError,), {})(reason)\n\n        return task\n\n    def _wait_for_task_finish(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        ecs_client: _ECSClient,\n    ):\n        \"\"\"\n        Watch an ECS task until it reaches a STOPPED status.\n\n        If configured, logs from the Prefect container are streamed to stderr.\n\n        Returns a description of the task on completion.\n        \"\"\"\n        can_stream_output = False\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        if configuration.stream_output:\n            container_def = _get_container(\n                task_definition[\"containerDefinitions\"], container_name\n            )\n            if not container_def:\n                logger.warning(\n                    \"Prefect container definition not found in \"\n                    \"task definition. Output cannot be streamed.\"\n                )\n            elif not container_def.get(\"logConfiguration\"):\n                logger.warning(\n                    \"Logging configuration not found on task. \"\n                    \"Output cannot be streamed.\"\n                )\n            elif not container_def[\"logConfiguration\"].get(\"logDriver\") == \"awslogs\":\n                logger.warning(\n                    \"Logging configuration uses unsupported \"\n                    \" driver {container_def['logConfiguration'].get('logDriver')!r}. \"\n                    \"Output cannot be streamed.\"\n                )\n            else:\n                # Prepare to stream the output\n                log_config = container_def[\"logConfiguration\"][\"options\"]\n                logs_client = self._get_client(configuration, \"logs\")\n                can_stream_output = True\n                # Track the last log timestamp to prevent double display\n                last_log_timestamp: Optional[int] = None\n                # Determine the name of the stream as \"prefix/container/run-id\"\n                stream_name = \"/\".join(\n                    [\n                        log_config[\"awslogs-stream-prefix\"],\n                        container_name,\n                        task_arn.rsplit(\"/\")[-1],\n                    ]\n                )\n                self._logger.info(\n                    f\"Streaming output from container {container_name!r}...\"\n                )\n\n        for task in self._watch_task_run(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            current_status=\"RUNNING\",\n        ):\n            if configuration.stream_output and can_stream_output:\n                # On each poll for task run status, also retrieve available logs\n                last_log_timestamp = self._stream_available_logs(\n                    logger,\n                    logs_client,\n                    log_group=log_config[\"awslogs-group\"],\n                    log_stream=stream_name,\n                    last_log_timestamp=last_log_timestamp,\n                )\n\n        return task\n\n    def _stream_available_logs(\n        self,\n        logger: logging.Logger,\n        logs_client: Any,\n        log_group: str,\n        log_stream: str,\n        last_log_timestamp: Optional[int] = None,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Stream logs from the given log group and stream since the last log timestamp.\n\n        Will continue on paginated responses until all logs are returned.\n\n        Returns the last log timestamp which can be used to call this method in the\n        future.\n        \"\"\"\n        last_log_stream_token = \"NO-TOKEN\"\n        next_log_stream_token = None\n\n        # AWS will return the same token that we send once the end of the paginated\n        # response is reached\n        while last_log_stream_token != next_log_stream_token:\n            last_log_stream_token = next_log_stream_token\n\n            request = {\n                \"logGroupName\": log_group,\n                \"logStreamName\": log_stream,\n            }\n\n            if last_log_stream_token is not None:\n                request[\"nextToken\"] = last_log_stream_token\n\n            if last_log_timestamp is not None:\n                # Bump the timestamp by one ms to avoid retrieving the last log again\n                request[\"startTime\"] = last_log_timestamp + 1\n\n            try:\n                response = logs_client.get_log_events(**request)\n            except Exception:\n                logger.error(\n                    f\"Failed to read log events with request {request}\",\n                    exc_info=True,\n                )\n                return last_log_timestamp\n\n            log_events = response[\"events\"]\n            for log_event in log_events:\n                # TODO: This doesn't forward to the local logger, which can be\n                #       bad for customizing handling and understanding where the\n                #       log is coming from, but it avoid nesting logger information\n                #       when the content is output from a Prefect logger on the\n                #       running infrastructure\n                print(log_event[\"message\"], file=sys.stderr)\n\n                if (\n                    last_log_timestamp is None\n                    or log_event[\"timestamp\"] &gt; last_log_timestamp\n                ):\n                    last_log_timestamp = log_event[\"timestamp\"]\n\n            next_log_stream_token = response.get(\"nextForwardToken\")\n            if not log_events:\n                # Stop reading pages if there was no data\n                break\n\n        return last_log_timestamp\n\n    def _watch_task_run(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        current_status: str = \"UNKNOWN\",\n        until_status: str = None,\n        timeout: int = None,\n    ) -&gt; Generator[None, None, dict]:\n        \"\"\"\n        Watches an ECS task run by querying every `poll_interval` seconds. After each\n        query, the retrieved task is yielded. This function returns when the task run\n        reaches a STOPPED status or the provided `until_status`.\n\n        Emits a log each time the status changes.\n        \"\"\"\n        last_status = status = current_status\n        t0 = time.time()\n        while status != until_status:\n            tasks = ecs_client.describe_tasks(\n                tasks=[task_arn], cluster=cluster_arn, include=[\"TAGS\"]\n            )[\"tasks\"]\n\n            if tasks:\n                task = tasks[0]\n\n                status = task[\"lastStatus\"]\n                if status != last_status:\n                    logger.info(f\"ECS task status is {status}.\")\n\n                yield task\n\n                # No point in continuing if the status is final\n                if status == \"STOPPED\":\n                    break\n\n                last_status = status\n\n            else:\n                # Intermittently, the task will not be described. We wat to respect the\n                # watch timeout though.\n                logger.debug(\"Task not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching task for status \"\n                    f\"{until_status or 'STOPPED'}.\"\n                )\n            time.sleep(configuration.task_watch_poll_interval)\n\n    def _get_or_generate_family(self, task_definition: dict, flow_run: FlowRun) -&gt; str:\n        \"\"\"\n        Gets or generate a family for the task definition.\n        \"\"\"\n        family = task_definition.get(\"family\")\n        if not family:\n            assert self._work_pool_name and flow_run.deployment_id\n            family = (\n                f\"{ECS_DEFAULT_FAMILY}_{self._work_pool_name}_{flow_run.deployment_id}\"\n            )\n        slugify(\n            family,\n            max_length=255,\n            regex_pattern=r\"[^a-zA-Z0-9-_]+\",\n        )\n        return family\n\n    def _prepare_task_definition(\n        self,\n        configuration: ECSJobConfiguration,\n        region: str,\n        flow_run: FlowRun,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task definition by inferring any defaults and merging overrides.\n        \"\"\"\n        task_definition = copy.deepcopy(configuration.task_definition)\n\n        # Configure the Prefect runtime container\n        task_definition.setdefault(\"containerDefinitions\", [])\n\n        # Remove empty container definitions\n        task_definition[\"containerDefinitions\"] = [\n            d for d in task_definition[\"containerDefinitions\"] if d\n        ]\n\n        container_name = configuration.container_name\n        if not container_name:\n            container_name = (\n                _container_name_from_task_definition(task_definition)\n                or ECS_DEFAULT_CONTAINER_NAME\n            )\n\n        container = _get_container(\n            task_definition[\"containerDefinitions\"], container_name\n        )\n        if container is None:\n            if container_name != ECS_DEFAULT_CONTAINER_NAME:\n                raise ValueError(\n                    f\"Container {container_name!r} not found in task definition.\"\n                )\n\n            # Look for a container without a name\n            for container in task_definition[\"containerDefinitions\"]:\n                if \"name\" not in container:\n                    container[\"name\"] = container_name\n                    break\n            else:\n                container = {\"name\": container_name}\n                task_definition[\"containerDefinitions\"].append(container)\n\n        # Image is required so make sure it's present\n        container.setdefault(\"image\", get_prefect_image_name())\n\n        # Remove any keys that have been explicitly \"unset\"\n        unset_keys = {key for key, value in configuration.env.items() if value is None}\n        for item in tuple(container.get(\"environment\", [])):\n            if item[\"name\"] in unset_keys or item[\"value\"] is None:\n                container[\"environment\"].remove(item)\n\n        if configuration.configure_cloudwatch_logs:\n            prefix = f\"prefect-logs_{self._work_pool_name}_{flow_run.deployment_id}\"\n            container[\"logConfiguration\"] = {\n                \"logDriver\": \"awslogs\",\n                \"options\": {\n                    \"awslogs-create-group\": \"true\",\n                    \"awslogs-group\": \"prefect\",\n                    \"awslogs-region\": region,\n                    \"awslogs-stream-prefix\": (\n                        configuration.cloudwatch_logs_prefix or prefix\n                    ),\n                    **configuration.cloudwatch_logs_options,\n                },\n            }\n\n        task_definition[\"family\"] = self._get_or_generate_family(\n            task_definition, flow_run\n        )\n        # CPU and memory are required in some cases, retrieve the value to use\n        cpu = task_definition.get(\"cpu\") or ECS_DEFAULT_CPU\n        memory = task_definition.get(\"memory\") or ECS_DEFAULT_MEMORY\n\n        launch_type = configuration.task_run_request.get(\n            \"launchType\", ECS_DEFAULT_LAUNCH_TYPE\n        )\n\n        if launch_type == \"FARGATE\" or launch_type == \"FARGATE_SPOT\":\n            # Task level memory and cpu are required when using fargate\n            task_definition[\"cpu\"] = str(cpu)\n            task_definition[\"memory\"] = str(memory)\n\n            # The FARGATE compatibility is required if it will be used as as launch type\n            requires_compatibilities = task_definition.setdefault(\n                \"requiresCompatibilities\", []\n            )\n            if \"FARGATE\" not in requires_compatibilities:\n                task_definition[\"requiresCompatibilities\"].append(\"FARGATE\")\n\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            # However, we will not enforce that here if the user has set it\n            task_definition.setdefault(\"networkMode\", \"awsvpc\")\n\n        elif launch_type == \"EC2\":\n            # Container level memory and cpu are required when using ec2\n            container.setdefault(\"cpu\", cpu)\n            container.setdefault(\"memory\", memory)\n\n            # Ensure set values are cast to integers\n            container[\"cpu\"] = int(container[\"cpu\"])\n            container[\"memory\"] = int(container[\"memory\"])\n\n        # Ensure set values are cast to strings\n        if task_definition.get(\"cpu\"):\n            task_definition[\"cpu\"] = str(task_definition[\"cpu\"])\n        if task_definition.get(\"memory\"):\n            task_definition[\"memory\"] = str(task_definition[\"memory\"])\n\n        return task_definition\n\n    def _load_network_configuration(\n        self, vpc_id: Optional[str], configuration: ECSJobConfiguration\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = self._get_client(configuration, \"ec2\")\n        vpc_message = \"the default VPC\" if not vpc_id else f\"VPC with ID {vpc_id}\"\n\n        if not vpc_id:\n            # Retrieve the default VPC\n            describe = {\"Filters\": [{\"Name\": \"isDefault\", \"Values\": [\"true\"]}]}\n        else:\n            describe = {\"VpcIds\": [vpc_id]}\n\n        vpcs = ec2_client.describe_vpcs(**describe)[\"Vpcs\"]\n        if not vpcs:\n            help_message = (\n                \"Pass an explicit `vpc_id` or configure a default VPC.\"\n                if not vpc_id\n                else \"Check that the VPC exists in the current region.\"\n            )\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                \"Network configuration cannot be inferred. \" + help_message\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                \"Network configuration cannot be inferred.\"\n            )\n\n        return {\n            \"awsvpcConfiguration\": {\n                \"subnets\": [s[\"SubnetId\"] for s in subnets],\n                \"assignPublicIp\": \"ENABLED\",\n                \"securityGroups\": [],\n            }\n        }\n\n    def _custom_network_configuration(\n        self,\n        vpc_id: str,\n        network_configuration: dict,\n        configuration: ECSJobConfiguration,\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = self._get_client(configuration, \"ec2\")\n        vpc_message = f\"VPC with ID {vpc_id}\"\n\n        vpcs = ec2_client.describe_vpcs(VpcIds=[vpc_id]).get(\"Vpcs\")\n\n        if not vpcs:\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                + \"Network configuration cannot be inferred. \"\n                + \"Pass an explicit `vpc_id`.\"\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                + \"Network configuration cannot be inferred.\"\n            )\n\n        subnet_ids = [subnet[\"SubnetId\"] for subnet in subnets]\n\n        config_subnets = network_configuration.get(\"subnets\", [])\n        if not all(conf_sn in subnet_ids for conf_sn in config_subnets):\n            raise ValueError(\n                f\"Subnets {config_subnets} not found within {vpc_message}.\"\n                + \" Please check that VPC is associated with supplied subnets.\"\n            )\n\n        return {\"awsvpcConfiguration\": network_configuration}\n\n    def _prepare_task_run_request(\n        self,\n        configuration: ECSJobConfiguration,\n        task_definition: dict,\n        task_definition_arn: str,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task run request payload.\n        \"\"\"\n        task_run_request = deepcopy(configuration.task_run_request)\n\n        task_run_request.setdefault(\"taskDefinition\", task_definition_arn)\n        assert task_run_request[\"taskDefinition\"] == task_definition_arn\n        capacityProviderStrategy = task_run_request.get(\"capacityProviderStrategy\")\n\n        if capacityProviderStrategy:\n            # Should not be provided at all if capacityProviderStrategy is set, see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html#ECS-RunTask-request-capacityProviderStrategy  # noqa\n            self._logger.warning(\n                \"Found capacityProviderStrategy. \"\n                \"Removing launchType from task run request.\"\n            )\n            task_run_request.pop(\"launchType\", None)\n\n        elif task_run_request.get(\"launchType\") == \"FARGATE_SPOT\":\n            # Should not be provided at all for FARGATE SPOT\n            task_run_request.pop(\"launchType\", None)\n\n            # A capacity provider strategy is required for FARGATE SPOT\n            task_run_request[\"capacityProviderStrategy\"] = [\n                {\"capacityProvider\": \"FARGATE_SPOT\", \"weight\": 1}\n            ]\n        overrides = task_run_request.get(\"overrides\", {})\n        container_overrides = overrides.get(\"containerOverrides\", [])\n\n        # Ensure the network configuration is present if using awsvpc for network mode\n        if (\n            task_definition.get(\"networkMode\") == \"awsvpc\"\n            and not task_run_request.get(\"networkConfiguration\")\n            and not configuration.network_configuration\n        ):\n            task_run_request[\"networkConfiguration\"] = self._load_network_configuration(\n                configuration.vpc_id, configuration\n            )\n\n        # Use networkConfiguration if supplied by user\n        if (\n            task_definition.get(\"networkMode\") == \"awsvpc\"\n            and configuration.network_configuration\n            and configuration.vpc_id\n        ):\n            task_run_request[\n                \"networkConfiguration\"\n            ] = self._custom_network_configuration(\n                configuration.vpc_id,\n                configuration.network_configuration,\n                configuration,\n            )\n\n        # Ensure the container name is set if not provided at template time\n\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        if container_overrides and not container_overrides[0].get(\"name\"):\n            container_overrides[0][\"name\"] = container_name\n\n        # Ensure configuration command is respected post-templating\n\n        orchestration_container = _get_container(container_overrides, container_name)\n\n        if orchestration_container:\n            # Override the command if given on the configuration\n            if configuration.command:\n                orchestration_container[\"command\"] = configuration.command\n\n        # Clean up templated variable formatting\n\n        for container in container_overrides:\n            if isinstance(container.get(\"command\"), str):\n                container[\"command\"] = shlex.split(container[\"command\"])\n            if isinstance(container.get(\"environment\"), dict):\n                container[\"environment\"] = [\n                    {\"name\": k, \"value\": v} for k, v in container[\"environment\"].items()\n                ]\n\n            # Remove null values \u2014 they're not allowed by AWS\n            container[\"environment\"] = [\n                item\n                for item in container.get(\"environment\", [])\n                if item[\"value\"] is not None\n            ]\n\n        if isinstance(task_run_request.get(\"tags\"), dict):\n            task_run_request[\"tags\"] = [\n                {\"key\": k, \"value\": v} for k, v in task_run_request[\"tags\"].items()\n            ]\n\n        if overrides.get(\"cpu\"):\n            overrides[\"cpu\"] = str(overrides[\"cpu\"])\n\n        if overrides.get(\"memory\"):\n            overrides[\"memory\"] = str(overrides[\"memory\"])\n\n        # Ensure configuration tags and env are respected post-templating\n\n        tags = [\n            item\n            for item in task_run_request.get(\"tags\", [])\n            if item[\"key\"] not in configuration.labels.keys()\n        ] + [\n            {\"key\": k, \"value\": v}\n            for k, v in configuration.labels.items()\n            if v is not None\n        ]\n\n        # Slugify tags keys and values\n        tags = [\n            {\n                \"key\": slugify(\n                    item[\"key\"],\n                    regex_pattern=_TAG_REGEX,\n                    allow_unicode=True,\n                    lowercase=False,\n                ),\n                \"value\": slugify(\n                    item[\"value\"],\n                    regex_pattern=_TAG_REGEX,\n                    allow_unicode=True,\n                    lowercase=False,\n                ),\n            }\n            for item in tags\n        ]\n\n        if tags:\n            task_run_request[\"tags\"] = tags\n\n        if orchestration_container:\n            environment = [\n                item\n                for item in orchestration_container.get(\"environment\", [])\n                if item[\"name\"] not in configuration.env.keys()\n            ] + [\n                {\"name\": k, \"value\": v}\n                for k, v in configuration.env.items()\n                if v is not None\n            ]\n            if environment:\n                orchestration_container[\"environment\"] = environment\n\n        # Remove empty container overrides\n\n        overrides[\"containerOverrides\"] = [v for v in container_overrides if v]\n\n        return task_run_request\n\n    @retry(\n        stop=stop_after_attempt(MAX_CREATE_TASK_RUN_ATTEMPTS),\n        wait=wait_fixed(CREATE_TASK_RUN_MIN_DELAY_SECONDS)\n        + wait_random(\n            CREATE_TASK_RUN_MIN_DELAY_JITTER_SECONDS,\n            CREATE_TASK_RUN_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    def _create_task_run(self, ecs_client: _ECSClient, task_run_request: dict) -&gt; str:\n        \"\"\"\n        Create a run of a task definition.\n\n        Returns the task run ARN.\n        \"\"\"\n        task = ecs_client.run_task(**task_run_request)\n        if task[\"failures\"]:\n            raise RuntimeError(\n                f\"Failed to run ECS task: {task['failures'][0]['reason']}\"\n            )\n        elif not task[\"tasks\"]:\n            raise RuntimeError(\n                \"Failed to run ECS task: no tasks or failures were returned.\"\n            )\n        return task[\"tasks\"][0]\n\n    def _task_definitions_equal(self, taskdef_1, taskdef_2) -&gt; bool:\n        \"\"\"\n        Compare two task definitions.\n\n        Since one may come from the AWS API and have populated defaults, we do our best\n        to homogenize the definitions without changing their meaning.\n        \"\"\"\n        if taskdef_1 == taskdef_2:\n            return True\n\n        if taskdef_1 is None or taskdef_2 is None:\n            return False\n\n        taskdef_1 = copy.deepcopy(taskdef_1)\n        taskdef_2 = copy.deepcopy(taskdef_2)\n\n        for taskdef in (taskdef_1, taskdef_2):\n            # Set defaults that AWS would set after registration\n            container_definitions = taskdef.get(\"containerDefinitions\", [])\n            essential = any(\n                container.get(\"essential\") for container in container_definitions\n            )\n            if not essential:\n                container_definitions[0].setdefault(\"essential\", True)\n\n            taskdef.setdefault(\"networkMode\", \"bridge\")\n\n        _drop_empty_keys_from_task_definition(taskdef_1)\n        _drop_empty_keys_from_task_definition(taskdef_2)\n\n        # Clear fields that change on registration for comparison\n        for field in ECS_POST_REGISTRATION_FIELDS:\n            taskdef_1.pop(field, None)\n            taskdef_2.pop(field, None)\n\n        return taskdef_1 == taskdef_2\n\n    async def kill_infrastructure(\n        self,\n        configuration: ECSJobConfiguration,\n        infrastructure_pid: str,\n        grace_seconds: int = 30,\n    ) -&gt; None:\n        \"\"\"\n        Kill a task running on ECS.\n\n        Args:\n            infrastructure_pid: A cluster and task arn combination. This should match a\n                value yielded by `ECSWorker.run`.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n                \"support dynamic grace period configuration so 30s will be used. \"\n                \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n            )\n        cluster, task = parse_identifier(infrastructure_pid)\n        await run_sync_in_worker_thread(self._stop_task, configuration, cluster, task)\n\n    def _stop_task(\n        self, configuration: ECSJobConfiguration, cluster: str, task: str\n    ) -&gt; None:\n        \"\"\"\n        Stop a running ECS task.\n        \"\"\"\n        if configuration.cluster is not None and cluster != configuration.cluster:\n            raise InfrastructureNotAvailable(\n                \"Cannot stop ECS task: this infrastructure block has access to \"\n                f\"cluster {configuration.cluster!r} but the task is running in cluster \"\n                f\"{cluster!r}.\"\n            )\n\n        ecs_client = self._get_client(configuration, \"ecs\")\n        try:\n            ecs_client.stop_task(cluster=cluster, task=task)\n        except Exception as exc:\n            # Raise a special exception if the task does not exist\n            if \"ClusterNotFound\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} could not be found.\"\n                ) from exc\n            if \"not find task\" in str(exc) or \"referenced task was not found\" in str(\n                exc\n            ):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the task {task!r} could not be found in \"\n                    f\"cluster {cluster!r}.\"\n                ) from exc\n            if \"no registered tasks\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} has no tasks.\"\n                ) from exc\n\n            # Reraise unknown exceptions\n            raise\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Kill a task running on ECS.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>A cluster and task arn combination. This should match a value yielded by <code>ECSWorker.run</code>.</p> required Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    configuration: ECSJobConfiguration,\n    infrastructure_pid: str,\n    grace_seconds: int = 30,\n) -&gt; None:\n    \"\"\"\n    Kill a task running on ECS.\n\n    Args:\n        infrastructure_pid: A cluster and task arn combination. This should match a\n            value yielded by `ECSWorker.run`.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n            \"support dynamic grace period configuration so 30s will be used. \"\n            \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n        )\n    cluster, task = parse_identifier(infrastructure_pid)\n    await run_sync_in_worker_thread(self._stop_task, configuration, cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs a given flow run on the current worker.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: ECSJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; ECSWorkerResult:\n    \"\"\"\n    Runs a given flow run on the current worker.\n    \"\"\"\n    ecs_client = await run_sync_in_worker_thread(\n        self._get_client, configuration, \"ecs\"\n    )\n\n    logger = self.get_flow_run_logger(flow_run)\n\n    (\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition,\n    ) = await run_sync_in_worker_thread(\n        self._create_task_and_wait_for_start,\n        logger,\n        ecs_client,\n        configuration,\n        flow_run,\n    )\n\n    # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n    # if set to preserve matching by name rather than arn\n    # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n    # single colons.\n    identifier = (\n        (configuration.cluster if configuration.cluster else cluster_arn)\n        + \"::\"\n        + task_arn\n    )\n\n    if task_status:\n        task_status.started(identifier)\n\n    status_code = await run_sync_in_worker_thread(\n        self._watch_task_and_get_exit_code,\n        logger,\n        configuration,\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition and configuration.auto_deregister_task_definition,\n        ecs_client,\n    )\n\n    return ECSWorkerResult(\n        identifier=identifier,\n        # If the container does not start the exit code can be null but we must\n        # still report a status code. We use a -1 to indicate a special code.\n        status_code=status_code if status_code is not None else -1,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorkerResult","title":"<code>ECSWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>The result of an ECS job.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSWorkerResult(BaseWorkerResult):\n    \"\"\"\n    The result of an ECS job.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.parse_identifier","title":"<code>parse_identifier</code>","text":"<p>Splits identifier into its cluster and task components, e.g. input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>def parse_identifier(identifier: str) -&gt; ECSIdentifier:\n    \"\"\"\n    Splits identifier into its cluster and task components, e.g.\n    input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").\n    \"\"\"\n    cluster, task = identifier.split(\"::\", maxsplit=1)\n    return ECSIdentifier(cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/","title":"Glue Job","text":""},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job","title":"<code>prefect_aws.glue_job</code>","text":"<p>Integrations with the AWS Glue Job.</p>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobBlock","title":"<code>GlueJobBlock</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>Execute a job to the AWS Glue Job service.</p> <p>Attributes:</p> Name Type Description <code>job_name</code> <code>str</code> <p>The name of the job definition to use.</p> <code>arguments</code> <code>Optional[dict]</code> <p>The job arguments associated with this run. For this job run, they replace the default arguments set in the job definition itself. You can specify arguments here that your own job-execution script consumes, as well as arguments that Glue itself consumes. Job arguments may be logged. Do not pass plaintext secrets as arguments. Retrieve secrets from a Glue Connection, Secrets Manager or other secret management mechanism if you intend to keep them within the Job. doc</p> <code>job_watch_poll_interval</code> <code>float</code> <p>The amount of time to wait between AWS API calls while monitoring the state of a Glue Job. default is 60s because of jobs that use AWS Glue versions 2.0 and later have a 1-minute minimum. AWS Glue Pricing</p> Example <p>Start a job to AWS Glue Job. <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.glue_job import GlueJobBlock\n\n\n@flow\ndef example_run_glue_job():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"your_access_key_id\",\n        aws_secret_access_key=\"your_secret_access_key\"\n    )\n    glue_job_run = GlueJobBlock(\n        job_name=\"your_glue_job_name\",\n        arguments={\"--YOUR_EXTRA_ARGUMENT\": \"YOUR_EXTRA_ARGUMENT_VALUE\"},\n    ).trigger()\n\n    return glue_job_run.wait_for_completion()\n\n\nexample_run_glue_job()\n</code></pre></p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>class GlueJobBlock(JobBlock):\n    \"\"\"Execute a job to the AWS Glue Job service.\n\n    Attributes:\n        job_name: The name of the job definition to use.\n        arguments: The job arguments associated with this run.\n            For this job run, they replace the default arguments set in the job\n            definition itself.\n            You can specify arguments here that your own job-execution script consumes,\n            as well as arguments that Glue itself consumes.\n            Job arguments may be logged. Do not pass plaintext secrets as arguments.\n            Retrieve secrets from a Glue Connection, Secrets Manager or other secret\n            management mechanism if you intend to keep them within the Job.\n            [doc](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)\n        job_watch_poll_interval: The amount of time to wait between AWS API\n            calls while monitoring the state of a Glue Job.\n            default is 60s because of jobs that use AWS Glue versions 2.0 and later\n            have a 1-minute minimum.\n            [AWS Glue Pricing](https://aws.amazon.com/glue/pricing/?nc1=h_ls)\n\n    Example:\n        Start a job to AWS Glue Job.\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.glue_job import GlueJobBlock\n\n\n        @flow\n        def example_run_glue_job():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"your_access_key_id\",\n                aws_secret_access_key=\"your_secret_access_key\"\n            )\n            glue_job_run = GlueJobBlock(\n                job_name=\"your_glue_job_name\",\n                arguments={\"--YOUR_EXTRA_ARGUMENT\": \"YOUR_EXTRA_ARGUMENT_VALUE\"},\n            ).trigger()\n\n            return glue_job_run.wait_for_completion()\n\n\n        example_run_glue_job()\n        ```\n    \"\"\"\n\n    job_name: str = Field(\n        ...,\n        title=\"AWS Glue Job Name\",\n        description=\"The name of the job definition to use.\",\n    )\n\n    arguments: Optional[dict] = Field(\n        default=None,\n        title=\"AWS Glue Job Arguments\",\n        description=\"The job arguments associated with this run.\",\n    )\n    job_watch_poll_interval: float = Field(\n        default=60.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an Glue Job.\"\n        ),\n    )\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to Glue.\",\n    )\n\n    async def trigger(self) -&gt; GlueJobRun:\n        \"\"\"trigger for GlueJobRun\"\"\"\n        client = self._get_client()\n        job_run_id = self._start_job(client)\n        return GlueJobRun(\n            job_name=self.job_name,\n            job_id=job_run_id,\n            job_watch_poll_interval=self.job_watch_poll_interval,\n        )\n\n    def _start_job(self, client: _GlueJobClient) -&gt; str:\n        \"\"\"\n        Start the AWS Glue Job\n        [doc](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/glue/client/start_job_run.html)\n        \"\"\"\n        self.logger.info(\n            f\"starting job {self.job_name} with arguments {self.arguments}\"\n        )\n        try:\n            response = client.start_job_run(\n                JobName=self.job_name,\n                Arguments=self.arguments,\n            )\n            job_run_id = str(response[\"JobRunId\"])\n            self.logger.info(f\"job started with job run id: {job_run_id}\")\n            return job_run_id\n        except Exception as e:\n            self.logger.error(f\"failed to start job: {e}\")\n            raise RuntimeError\n\n    def _get_client(self) -&gt; _GlueJobClient:\n        \"\"\"\n        Retrieve a Glue Job Client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        return boto_session.client(\"glue\")\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobBlock.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>trigger for GlueJobRun</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>async def trigger(self) -&gt; GlueJobRun:\n    \"\"\"trigger for GlueJobRun\"\"\"\n    client = self._get_client()\n    job_run_id = self._start_job(client)\n    return GlueJobRun(\n        job_name=self.job_name,\n        job_id=job_run_id,\n        job_watch_poll_interval=self.job_watch_poll_interval,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun","title":"<code>GlueJobRun</code>","text":"<p>               Bases: <code>JobRun</code>, <code>BaseModel</code></p> <p>Execute a Glue Job</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>class GlueJobRun(JobRun, BaseModel):\n    \"\"\"Execute a Glue Job\"\"\"\n\n    job_name: str = Field(\n        ...,\n        title=\"AWS Glue Job Name\",\n        description=\"The name of the job definition to use.\",\n    )\n\n    job_id: str = Field(\n        ...,\n        title=\"AWS Glue Job ID\",\n        description=\"The ID of the job run.\",\n    )\n\n    job_watch_poll_interval: float = Field(\n        default=60.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an Glue Job.\"\n        ),\n    )\n\n    _error_states = [\"FAILED\", \"STOPPED\", \"ERROR\", \"TIMEOUT\"]\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to Glue.\",\n    )\n\n    client: _GlueJobClient = Field(default=None, description=\"\")\n\n    async def fetch_result(self) -&gt; str:\n        \"\"\"fetch glue job state\"\"\"\n        job = self._get_job_run()\n        return job[\"JobRun\"][\"JobRunState\"]\n\n    def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Wait for the job run to complete and get exit code\n        \"\"\"\n        self.logger.info(f\"watching job {self.job_name} with run id {self.job_id}\")\n        while True:\n            job = self._get_job_run()\n            job_state = job[\"JobRun\"][\"JobRunState\"]\n            if job_state in self._error_states:\n                # Generate a dynamic exception type from the AWS name\n                self.logger.error(f\"job failed: {job['JobRun']['ErrorMessage']}\")\n                raise RuntimeError(job[\"JobRun\"][\"ErrorMessage\"])\n            elif job_state == \"SUCCEEDED\":\n                self.logger.info(f\"job succeeded: {self.job_id}\")\n                break\n\n            time.sleep(self.job_watch_poll_interval)\n\n    def _get_job_run(self):\n        \"\"\"get glue job\"\"\"\n        return self.client.get_job_run(JobName=self.job_name, RunId=self.job_id)\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>fetch glue job state</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>async def fetch_result(self) -&gt; str:\n    \"\"\"fetch glue job state\"\"\"\n    job = self._get_job_run()\n    return job[\"JobRun\"][\"JobRunState\"]\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun.wait_for_completion","title":"<code>wait_for_completion</code>","text":"<p>Wait for the job run to complete and get exit code</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Wait for the job run to complete and get exit code\n    \"\"\"\n    self.logger.info(f\"watching job {self.job_name} with run id {self.job_id}\")\n    while True:\n        job = self._get_job_run()\n        job_state = job[\"JobRun\"][\"JobRunState\"]\n        if job_state in self._error_states:\n            # Generate a dynamic exception type from the AWS name\n            self.logger.error(f\"job failed: {job['JobRun']['ErrorMessage']}\")\n            raise RuntimeError(job[\"JobRun\"][\"ErrorMessage\"])\n        elif job_state == \"SUCCEEDED\":\n            self.logger.info(f\"job succeeded: {self.job_id}\")\n            break\n\n        time.sleep(self.job_watch_poll_interval)\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/","title":"Lambda","text":""},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function","title":"<code>prefect_aws.lambda_function</code>","text":"<p>Integrations with AWS Lambda.</p> <p>Examples:</p> <pre><code>Run a lambda function with a payload\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(payload={\"foo\": \"bar\"})\n```\n\nSpecify a version of a lambda function\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    qualifier=\"1\",\n    aws_credentials=aws_credentials,\n).invoke()\n```\n\nInvoke a lambda function asynchronously\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(invocation_type=\"Event\")\n```\n\nInvoke a lambda function and return the last 4 KB of logs\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(tail=True)\n```\n\nInvoke a lambda function with a client context\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(client_context={\"bar\": \"foo\"})\n```\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction","title":"<code>LambdaFunction</code>","text":"<p>               Bases: <code>Block</code></p> <p>Invoke a Lambda function. This block is part of the prefect-aws collection. Install prefect-aws with <code>pip install prefect-aws</code> to use this block.</p> <p>Attributes:</p> Name Type Description <code>function_name</code> <code>str</code> <p>The name, ARN, or partial ARN of the Lambda function to run. This must be the name of a function that is already deployed to AWS Lambda.</p> <code>qualifier</code> <code>Optional[str]</code> <p>The version or alias of the Lambda function to use when invoked. If not specified, the latest (unqualified) version of the Lambda function will be used.</p> <code>aws_credentials</code> <code>AwsCredentials</code> <p>The AWS credentials to use to connect to AWS Lambda with a default factory of AwsCredentials.</p> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>class LambdaFunction(Block):\n    \"\"\"Invoke a Lambda function. This block is part of the prefect-aws\n    collection. Install prefect-aws with `pip install prefect-aws` to use this\n    block.\n\n    Attributes:\n        function_name: The name, ARN, or partial ARN of the Lambda function to\n            run. This must be the name of a function that is already deployed\n            to AWS Lambda.\n        qualifier: The version or alias of the Lambda function to use when\n            invoked. If not specified, the latest (unqualified) version of the\n            Lambda function will be used.\n        aws_credentials: The AWS credentials to use to connect to AWS Lambda\n            with a default factory of AwsCredentials.\n\n    \"\"\"\n\n    _block_type_name = \"Lambda Function\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/s3/#prefect_aws.lambda_function.LambdaFunction\"  # noqa\n\n    function_name: str = Field(\n        title=\"Function Name\",\n        description=(\n            \"The name, ARN, or partial ARN of the Lambda function to run. This\"\n            \" must be the name of a function that is already deployed to AWS\"\n            \" Lambda.\"\n        ),\n    )\n    qualifier: Optional[str] = Field(\n        default=None,\n        title=\"Qualifier\",\n        description=(\n            \"The version or alias of the Lambda function to use when invoked. \"\n            \"If not specified, the latest (unqualified) version of the Lambda \"\n            \"function will be used.\"\n        ),\n    )\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to invoke the Lambda with.\",\n    )\n\n    class Config:\n        \"\"\"Lambda's pydantic configuration.\"\"\"\n\n        smart_union = True\n\n    def _get_lambda_client(self):\n        \"\"\"\n        Retrieve a boto3 session and Lambda client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        lambda_client = boto_session.client(\"lambda\")\n        return lambda_client\n\n    @sync_compatible\n    async def invoke(\n        self,\n        payload: dict = None,\n        invocation_type: Literal[\n            \"RequestResponse\", \"Event\", \"DryRun\"\n        ] = \"RequestResponse\",\n        tail: bool = False,\n        client_context: Optional[dict] = None,\n    ) -&gt; dict:\n        \"\"\"\n        [Invoke](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html)\n        the Lambda function with the given payload.\n\n        Args:\n            payload: The payload to send to the Lambda function.\n            invocation_type: The invocation type of the Lambda function. This\n                can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses\n                \"RequestResponse\" by default.\n            tail: If True, the response will include the base64-encoded last 4\n                KB of log data produced by the Lambda function.\n            client_context: The client context to send to the Lambda function.\n                Limited to 3583 bytes.\n\n        Returns:\n            The response from the Lambda function.\n\n        Examples:\n\n            ```python\n            from prefect_aws.lambda_function import LambdaFunction\n            from prefect_aws.credentials import AwsCredentials\n\n            credentials = AwsCredentials()\n            lambda_function = LambdaFunction(\n                function_name=\"test_lambda_function\",\n                aws_credentials=credentials,\n            )\n            response = lambda_function.invoke(\n                payload={\"foo\": \"bar\"},\n                invocation_type=\"RequestResponse\",\n            )\n            response[\"Payload\"].read()\n            ```\n            ```txt\n            b'{\"foo\": \"bar\"}'\n            ```\n\n        \"\"\"\n        # Add invocation arguments\n        kwargs = dict(FunctionName=self.function_name)\n\n        if payload:\n            kwargs[\"Payload\"] = json.dumps(payload).encode()\n\n        # Let boto handle invalid invocation types\n        kwargs[\"InvocationType\"] = invocation_type\n\n        if self.qualifier is not None:\n            kwargs[\"Qualifier\"] = self.qualifier\n\n        if tail:\n            kwargs[\"LogType\"] = \"Tail\"\n\n        if client_context is not None:\n            # For some reason this is string, but payload is bytes\n            kwargs[\"ClientContext\"] = json.dumps(client_context)\n\n        # Get client and invoke\n        lambda_client = await run_sync_in_worker_thread(self._get_lambda_client)\n        return await run_sync_in_worker_thread(lambda_client.invoke, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction.Config","title":"<code>Config</code>","text":"<p>Lambda's pydantic configuration.</p> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>class Config:\n    \"\"\"Lambda's pydantic configuration.\"\"\"\n\n    smart_union = True\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction.invoke","title":"<code>invoke</code>  <code>async</code>","text":"<p>Invoke the Lambda function with the given payload.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>dict</code> <p>The payload to send to the Lambda function.</p> <code>None</code> <code>invocation_type</code> <code>Literal['RequestResponse', 'Event', 'DryRun']</code> <p>The invocation type of the Lambda function. This can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses \"RequestResponse\" by default.</p> <code>'RequestResponse'</code> <code>tail</code> <code>bool</code> <p>If True, the response will include the base64-encoded last 4 KB of log data produced by the Lambda function.</p> <code>False</code> <code>client_context</code> <code>Optional[dict]</code> <p>The client context to send to the Lambda function. Limited to 3583 bytes.</p> <code>None</code> <p>Returns:</p> Type Description <code>dict</code> <p>The response from the Lambda function.</p> <pre><code>```python\nfrom prefect_aws.lambda_function import LambdaFunction\nfrom prefect_aws.credentials import AwsCredentials\n\ncredentials = AwsCredentials()\nlambda_function = LambdaFunction(\n    function_name=\"test_lambda_function\",\n    aws_credentials=credentials,\n)\nresponse = lambda_function.invoke(\n    payload={\"foo\": \"bar\"},\n    invocation_type=\"RequestResponse\",\n)\nresponse[\"Payload\"].read()\n```\n```txt\nb'{\"foo\": \"bar\"}'\n```\n</code></pre> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>@sync_compatible\nasync def invoke(\n    self,\n    payload: dict = None,\n    invocation_type: Literal[\n        \"RequestResponse\", \"Event\", \"DryRun\"\n    ] = \"RequestResponse\",\n    tail: bool = False,\n    client_context: Optional[dict] = None,\n) -&gt; dict:\n    \"\"\"\n    [Invoke](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html)\n    the Lambda function with the given payload.\n\n    Args:\n        payload: The payload to send to the Lambda function.\n        invocation_type: The invocation type of the Lambda function. This\n            can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses\n            \"RequestResponse\" by default.\n        tail: If True, the response will include the base64-encoded last 4\n            KB of log data produced by the Lambda function.\n        client_context: The client context to send to the Lambda function.\n            Limited to 3583 bytes.\n\n    Returns:\n        The response from the Lambda function.\n\n    Examples:\n\n        ```python\n        from prefect_aws.lambda_function import LambdaFunction\n        from prefect_aws.credentials import AwsCredentials\n\n        credentials = AwsCredentials()\n        lambda_function = LambdaFunction(\n            function_name=\"test_lambda_function\",\n            aws_credentials=credentials,\n        )\n        response = lambda_function.invoke(\n            payload={\"foo\": \"bar\"},\n            invocation_type=\"RequestResponse\",\n        )\n        response[\"Payload\"].read()\n        ```\n        ```txt\n        b'{\"foo\": \"bar\"}'\n        ```\n\n    \"\"\"\n    # Add invocation arguments\n    kwargs = dict(FunctionName=self.function_name)\n\n    if payload:\n        kwargs[\"Payload\"] = json.dumps(payload).encode()\n\n    # Let boto handle invalid invocation types\n    kwargs[\"InvocationType\"] = invocation_type\n\n    if self.qualifier is not None:\n        kwargs[\"Qualifier\"] = self.qualifier\n\n    if tail:\n        kwargs[\"LogType\"] = \"Tail\"\n\n    if client_context is not None:\n        # For some reason this is string, but payload is bytes\n        kwargs[\"ClientContext\"] = json.dumps(client_context)\n\n    # Get client and invoke\n    lambda_client = await run_sync_in_worker_thread(self._get_lambda_client)\n    return await run_sync_in_worker_thread(lambda_client.invoke, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/","title":"S3","text":""},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3","title":"<code>prefect_aws.s3</code>","text":"<p>Tasks for interacting with AWS S3</p>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket","title":"<code>S3Bucket</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code>, <code>ObjectStorageBlock</code></p> <p>Block used to store data using AWS S3 or S3-compatible object storage like MinIO.</p> <p>Attributes:</p> Name Type Description <code>bucket_name</code> <code>str</code> <p>Name of your bucket.</p> <code>credentials</code> <code>Union[MinIOCredentials, AwsCredentials]</code> <p>A block containing your credentials to AWS or MinIO.</p> <code>bucket_folder</code> <code>str</code> <p>A default path to a folder within the S3 bucket to use for reading and writing objects.</p> Source code in <code>prefect_aws/s3.py</code> <pre><code>class S3Bucket(WritableFileSystem, WritableDeploymentStorage, ObjectStorageBlock):\n\n    \"\"\"\n    Block used to store data using AWS S3 or S3-compatible object storage like MinIO.\n\n    Attributes:\n        bucket_name: Name of your bucket.\n        credentials: A block containing your credentials to AWS or MinIO.\n        bucket_folder: A default path to a folder within the S3 bucket to use\n            for reading and writing objects.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"S3 Bucket\"\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-aws/s3/#prefect_aws.s3.S3Bucket\"  # noqa\n    )\n\n    bucket_name: str = Field(default=..., description=\"Name of your bucket.\")\n\n    credentials: Union[MinIOCredentials, AwsCredentials] = Field(\n        default_factory=AwsCredentials,\n        description=\"A block containing your credentials to AWS or MinIO.\",\n    )\n\n    bucket_folder: str = Field(\n        default=\"\",\n        description=(\n            \"A default path to a folder within the S3 bucket to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    @root_validator\n    def validate_credentials(cls, values):\n        creds = values[\"credentials\"]\n        if isinstance(creds, AwsCredentials) and isinstance(\n            creds.aws_client_parameters, dict\n        ):\n            # There's an issue with pydantic and nested blocks in a Union\n            # that is causing `aws_client_parameters` to be a dict in some\n            # cases instead of an `AwsClientParameters` object. Here we\n            # convert it to the correct type.\n            creds.aws_client_parameters = AwsClientParameters(\n                **creds.aws_client_parameters\n            )\n\n        return values\n\n    # Property to maintain compatibility with storage block based deployments\n    @property\n    def basepath(self) -&gt; str:\n        \"\"\"\n        The base path of the S3 bucket.\n\n        Returns:\n            str: The base path of the S3 bucket.\n        \"\"\"\n        return self.bucket_folder\n\n    @basepath.setter\n    def basepath(self, value: str) -&gt; None:\n        self.bucket_folder = value\n\n    def _resolve_path(self, path: str) -&gt; str:\n        \"\"\"\n        A helper function used in write_path to join `self.basepath` and `path`.\n\n        Args:\n\n            path: Name of the key, e.g. \"file1\". Each object in your\n                bucket has a unique key (or key name).\n\n        \"\"\"\n        # If bucket_folder provided, it means we won't write to the root dir of\n        # the bucket. So we need to add it on the front of the path.\n        #\n        # AWS object key naming guidelines require '/' for bucket folders.\n        # Get POSIX path to prevent `pathlib` from inferring '\\' on Windows OS\n        path = (\n            (Path(self.bucket_folder) / path).as_posix() if self.bucket_folder else path\n        )\n\n        return path\n\n    def _get_s3_client(self) -&gt; boto3.client:\n        \"\"\"\n        Authenticate MinIO credentials or AWS credentials and return an S3 client.\n        This is a helper function called by read_path() or write_path().\n        \"\"\"\n        return self.credentials.get_client(\"s3\")\n\n    def _get_bucket_resource(self) -&gt; boto3.resource:\n        \"\"\"\n        Retrieves boto3 resource object for the configured bucket\n        \"\"\"\n        params_override = self.credentials.aws_client_parameters.get_params_override()\n        bucket = (\n            self.credentials.get_boto3_session()\n            .resource(\"s3\", **params_override)\n            .Bucket(self.bucket_name)\n        )\n        return bucket\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a folder from the configured S3 bucket to a local directory.\n\n        Defaults to copying the entire contents of the block's basepath to the current\n        working directory.\n\n        Args:\n            from_path: Path in S3 bucket to download from. Defaults to the block's\n                configured basepath.\n            local_path: Local path to download S3 contents to. Defaults to the current\n                working directory.\n        \"\"\"\n        bucket_folder = self.bucket_folder\n        if from_path is None:\n            from_path = str(bucket_folder) if bucket_folder else \"\"\n\n        if local_path is None:\n            local_path = str(Path(\".\").absolute())\n        else:\n            local_path = str(Path(local_path).expanduser())\n\n        bucket = self._get_bucket_resource()\n        for obj in bucket.objects.filter(Prefix=from_path):\n            if obj.key[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n            target = os.path.join(\n                local_path,\n                os.path.relpath(obj.key, from_path),\n            )\n            os.makedirs(os.path.dirname(target), exist_ok=True)\n            bucket.download_file(obj.key, target)\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to the configured S3 bucket in a\n        given folder.\n\n        Defaults to uploading the entire contents the current working directory to the\n        block's basepath.\n\n        Args:\n            local_path: Path to local directory to upload from.\n            to_path: Path in S3 bucket to upload to. Defaults to block's configured\n                basepath.\n            ignore_file: Path to file containing gitignore style expressions for\n                filepaths to ignore.\n\n        \"\"\"\n        to_path = \"\" if to_path is None else to_path\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(local_path, ignore_patterns)\n\n        uploaded_file_count = 0\n        for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(to_path) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as local_file:\n                    local_file_content = local_file.read()\n\n                await self.write_path(\n                    remote_file_path.as_posix(), content=local_file_content\n                )\n                uploaded_file_count += 1\n\n        return uploaded_file_count\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Read specified path from S3 and return contents. Provide the entire\n        path to the key in S3.\n\n        Args:\n            path: Entire path to (and including) the key.\n\n        Example:\n            Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\":\n            ```python\n            from prefect_aws import AwsCredentials\n            from prefect_aws.s3 import S3Bucket\n\n            aws_creds = AwsCredentials(\n                aws_access_key_id=AWS_ACCESS_KEY_ID,\n                aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n            )\n\n            s3_bucket_block = S3Bucket(\n                bucket_name=\"bucket\",\n                credentials=aws_creds,\n                bucket_folder=\"subfolder\"\n            )\n\n            key_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n            ```\n        \"\"\"\n        path = self._resolve_path(path)\n\n        return await run_sync_in_worker_thread(self._read_sync, path)\n\n    def _read_sync(self, key: str) -&gt; bytes:\n        \"\"\"\n        Called by read_path(). Creates an S3 client and retrieves the\n        contents from  a specified path.\n        \"\"\"\n\n        s3_client = self._get_s3_client()\n\n        with io.BytesIO() as stream:\n            s3_client.download_fileobj(Bucket=self.bucket_name, Key=key, Fileobj=stream)\n            stream.seek(0)\n            output = stream.read()\n            return output\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        \"\"\"\n        Writes to an S3 bucket.\n\n        Args:\n\n            path: The key name. Each object in your bucket has a unique\n                key (or key name).\n            content: What you are uploading to S3.\n\n        Example:\n\n            Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n            ```python\n            from prefect_aws import MinioCredentials\n            from prefect_aws.s3 import S3Bucket\n\n            minio_creds = MinIOCredentials(\n                minio_root_user = \"minioadmin\",\n                minio_root_password = \"minioadmin\",\n            )\n\n            s3_bucket_block = S3Bucket(\n                bucket_name=\"bucket\",\n                minio_credentials=minio_creds,\n                bucket_folder=\"dogs/smalldogs\",\n                endpoint_url=\"http://localhost:9000\",\n            )\n            s3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n            ```\n        \"\"\"\n\n        path = self._resolve_path(path)\n\n        await run_sync_in_worker_thread(self._write_sync, path, content)\n\n        return path\n\n    def _write_sync(self, key: str, data: bytes) -&gt; None:\n        \"\"\"\n        Called by write_path(). Creates an S3 client and uploads a file\n        object.\n        \"\"\"\n\n        s3_client = self._get_s3_client()\n\n        with io.BytesIO(data) as stream:\n            s3_client.upload_fileobj(Fileobj=stream, Bucket=self.bucket_name, Key=key)\n\n    # NEW BLOCK INTERFACE METHODS BELOW\n    @staticmethod\n    def _list_objects_sync(page_iterator: PageIterator) -&gt; List[Dict[str, Any]]:\n        \"\"\"\n        Synchronous method to collect S3 objects into a list\n\n        Args:\n            page_iterator: AWS Paginator for S3 objects\n\n        Returns:\n            List[Dict]: List of object information\n        \"\"\"\n        return [\n            content for page in page_iterator for content in page.get(\"Contents\", [])\n        ]\n\n    def _join_bucket_folder(self, bucket_path: str = \"\") -&gt; str:\n        \"\"\"\n        Joins the base bucket folder to the bucket path.\n        NOTE: If a method reuses another method in this class, be careful to not\n        call this  twice because it'll join the bucket folder twice.\n        See https://github.com/PrefectHQ/prefect-aws/issues/141 for a past issue.\n        \"\"\"\n        if not self.bucket_folder and not bucket_path:\n            # there's a difference between \".\" and \"\", at least in the tests\n            return \"\"\n\n        bucket_path = str(bucket_path)\n        if self.bucket_folder != \"\" and bucket_path.startswith(self.bucket_folder):\n            self.logger.info(\n                f\"Bucket path {bucket_path!r} is already prefixed with \"\n                f\"bucket folder {self.bucket_folder!r}; is this intentional?\"\n            )\n\n        return (Path(self.bucket_folder) / bucket_path).as_posix() + (\n            \"\" if not bucket_path.endswith(\"/\") else \"/\"\n        )\n\n    @sync_compatible\n    async def list_objects(\n        self,\n        folder: str = \"\",\n        delimiter: str = \"\",\n        page_size: Optional[int] = None,\n        max_items: Optional[int] = None,\n        jmespath_query: Optional[str] = None,\n    ) -&gt; List[Dict[str, Any]]:\n        \"\"\"\n        Args:\n            folder: Folder to list objects from.\n            delimiter: Character used to group keys of listed objects.\n            page_size: Number of objects to return in each request to the AWS API.\n            max_items: Maximum number of objects that to be returned by task.\n            jmespath_query: Query used to filter objects based on object attributes refer to\n                the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n                for more information on how to construct queries.\n\n        Returns:\n            List of objects and their metadata in the bucket.\n\n        Examples:\n            List objects under the `base_folder`.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.list_objects(\"base_folder\")\n            ```\n        \"\"\"  # noqa: E501\n        bucket_path = self._join_bucket_folder(folder)\n        client = self.credentials.get_s3_client()\n        paginator = client.get_paginator(\"list_objects_v2\")\n        page_iterator = paginator.paginate(\n            Bucket=self.bucket_name,\n            Prefix=bucket_path,\n            Delimiter=delimiter,\n            PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n        )\n        if jmespath_query:\n            page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n        self.logger.info(f\"Listing objects in bucket {bucket_path}.\")\n        objects = await run_sync_in_worker_thread(\n            self._list_objects_sync, page_iterator\n        )\n        return objects\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Optional[Union[str, Path]],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads an object from the S3 bucket to a path.\n\n        Args:\n            from_path: The path to the object to download; this gets prefixed\n                with the bucket_folder.\n            to_path: The path to download the object to. If not provided, the\n                object's name will be used.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_file`.\n\n        Returns:\n            The absolute path that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # making path absolute, but converting back to str here\n        # since !r looks nicer that way and filename arg expects str\n        to_path = str(Path(to_path).absolute())\n        bucket_path = self._join_bucket_folder(from_path)\n        client = self.credentials.get_s3_client()\n\n        self.logger.debug(\n            f\"Preparing to download object from bucket {self.bucket_name!r} \"\n            f\"path {bucket_path!r} to {to_path!r}.\"\n        )\n        await run_sync_in_worker_thread(\n            client.download_file,\n            Bucket=self.bucket_name,\n            Key=from_path,\n            Filename=to_path,\n            **download_kwargs,\n        )\n        self.logger.info(\n            f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n            f\"to {to_path!r}.\"\n        )\n        return Path(to_path)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; BinaryIO:\n        \"\"\"\n        Downloads an object from the object storage service to a file-like object,\n        which can be a BytesIO object or a BufferedWriter.\n\n        Args:\n            from_path: The path to the object to download from; this gets prefixed\n                with the bucket_folder.\n            to_file_object: The file-like object to download the object to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_fileobj`.\n\n        Returns:\n            The file-like object that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with BytesIO() as buf:\n                s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n            ```\n\n            Download my_folder/notes.txt object to a BufferedWriter.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"wb\") as f:\n                s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n            ```\n        \"\"\"\n        client = self.credentials.get_s3_client()\n        bucket_path = self._join_bucket_folder(from_path)\n\n        self.logger.debug(\n            f\"Preparing to download object from bucket {self.bucket_name!r} \"\n            f\"path {bucket_path!r} to file object.\"\n        )\n        await run_sync_in_worker_thread(\n            client.download_fileobj,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            Fileobj=to_file_object,\n            **download_kwargs,\n        )\n        self.logger.info(\n            f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n            \"to file object.\"\n        )\n        return to_file_object\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads objects *within* a folder (excluding the folder itself)\n        from the S3 bucket to a folder.\n\n        Args:\n            from_folder: The path to the folder to download from.\n            to_folder: The path to download the folder to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_file`.\n\n        Returns:\n            The absolute path that the folder was downloaded to.\n\n        Examples:\n            Download my_folder to a local folder named my_folder.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n            ```\n        \"\"\"\n        if to_folder is None:\n            to_folder = \"\"\n        to_folder = Path(to_folder).absolute()\n\n        client = self.credentials.get_s3_client()\n        objects = await self.list_objects(folder=from_folder)\n\n        # do not call self._join_bucket_folder for filter\n        # because it's built-in to that method already!\n        # however, we still need to do it because we're using relative_to\n        bucket_folder = self._join_bucket_folder(from_folder)\n\n        async_coros = []\n        for object in objects:\n            bucket_path = Path(object[\"Key\"]).relative_to(bucket_folder)\n            # this skips the actual directory itself, e.g.\n            # `my_folder/` will be skipped\n            # `my_folder/notes.txt` will be downloaded\n            if bucket_path.is_dir():\n                continue\n            to_path = to_folder / bucket_path\n            to_path.parent.mkdir(parents=True, exist_ok=True)\n            to_path = str(to_path)  # must be string\n            self.logger.info(\n                f\"Downloading object from bucket {self.bucket_name!r} path \"\n                f\"{bucket_path.as_posix()!r} to {to_path!r}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    client.download_file,\n                    Bucket=self.bucket_name,\n                    Key=object[\"Key\"],\n                    Filename=to_path,\n                    **download_kwargs,\n                )\n            )\n        await asyncio.gather(*async_coros)\n\n        return Path(to_folder)\n\n    @sync_compatible\n    async def stream_from(\n        self,\n        bucket: \"S3Bucket\",\n        from_path: str,\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"Streams an object from another bucket to this bucket. Requires the\n        object to be downloaded and uploaded in chunks. If `self`'s credentials\n        allow for writes to the other bucket, try using `S3Bucket.copy_object`.\n\n        Args:\n            bucket: The bucket to stream from.\n            from_path: The path of the object to stream.\n            to_path: The path to stream the object to. Defaults to the object's name.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            your_s3_bucket = S3Bucket.load(\"your-bucket\")\n            my_s3_bucket = S3Bucket.load(\"my-bucket\")\n\n            my_s3_bucket.stream_from(\n                your_s3_bucket,\n                \"notes.txt\",\n                to_path=\"landed/notes.txt\"\n            )\n            ```\n\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # Get the source object's StreamingBody\n        from_path: str = bucket._join_bucket_folder(from_path)\n        from_client = bucket.credentials.get_s3_client()\n        obj = await run_sync_in_worker_thread(\n            from_client.get_object, Bucket=bucket.bucket_name, Key=from_path\n        )\n        body: StreamingBody = obj[\"Body\"]\n\n        # Upload the StreamingBody to this bucket\n        bucket_path = str(self._join_bucket_folder(to_path))\n        to_client = self.credentials.get_s3_client()\n        await run_sync_in_worker_thread(\n            to_client.upload_fileobj,\n            Fileobj=body,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            f\"Streamed s3://{bucket.bucket_name}/{from_path} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_path(\n        self,\n        from_path: Union[str, Path],\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object from a path to the S3 bucket.\n\n        Args:\n            from_path: The path to the file to upload from.\n            to_path: The path to upload the file to.\n            **upload_kwargs: Additional keyword arguments to pass to `Client.upload`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload notes.txt to my_folder/notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n            ```\n        \"\"\"\n        from_path = str(Path(from_path).absolute())\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        bucket_path = str(self._join_bucket_folder(to_path))\n        client = self.credentials.get_s3_client()\n\n        await run_sync_in_worker_thread(\n            client.upload_file,\n            Filename=from_path,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            f\"Uploaded from {from_path!r} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object to the S3 bucket from a file-like object,\n        which can be a BytesIO object or a BufferedReader.\n\n        Args:\n            from_file_object: The file-like object to upload from.\n            to_path: The path to upload the object to.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload BytesIO object to my_folder/notes.txt.\n            ```python\n            from io import BytesIO\n\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n            ```\n\n            Upload BufferedReader object to my_folder/notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                s3_bucket.upload_from_file_object(\n                    f, \"my_folder/notes.txt\"\n                )\n            ```\n        \"\"\"\n        bucket_path = str(self._join_bucket_folder(to_path))\n        client = self.credentials.get_s3_client()\n        await run_sync_in_worker_thread(\n            client.upload_fileobj,\n            Fileobj=from_file_object,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            \"Uploaded from file object to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads files *within* a folder (excluding the folder itself)\n        to the object storage service folder.\n\n        Args:\n            from_folder: The path to the folder to upload from.\n            to_folder: The path to upload the folder to.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the folder was uploaded to.\n\n        Examples:\n            Upload contents from my_folder to new_folder.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n            ```\n        \"\"\"\n        from_folder = Path(from_folder)\n        bucket_folder = self._join_bucket_folder(to_folder or \"\")\n\n        num_uploaded = 0\n        client = self.credentials.get_s3_client()\n\n        async_coros = []\n        for from_path in from_folder.rglob(\"**/*\"):\n            # this skips the actual directory itself, e.g.\n            # `my_folder/` will be skipped\n            # `my_folder/notes.txt` will be uploaded\n            if from_path.is_dir():\n                continue\n            bucket_path = (\n                Path(bucket_folder) / from_path.relative_to(from_folder)\n            ).as_posix()\n            self.logger.info(\n                f\"Uploading from {str(from_path)!r} to the bucket \"\n                f\"{self.bucket_name!r} path {bucket_path!r}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    client.upload_file,\n                    Filename=str(from_path),\n                    Bucket=self.bucket_name,\n                    Key=bucket_path,\n                    **upload_kwargs,\n                )\n            )\n            num_uploaded += 1\n        await asyncio.gather(*async_coros)\n\n        if num_uploaded == 0:\n            self.logger.warning(f\"No files were uploaded from {str(from_folder)!r}.\")\n        else:\n            self.logger.info(\n                f\"Uploaded {num_uploaded} files from {str(from_folder)!r} to \"\n                f\"the bucket {self.bucket_name!r} path {bucket_path!r}\"\n            )\n\n        return to_folder\n\n    @sync_compatible\n    async def copy_object(\n        self,\n        from_path: Union[str, Path],\n        to_path: Union[str, Path],\n        to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n        **copy_kwargs,\n    ) -&gt; str:\n        \"\"\"Uses S3's internal\n        [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n        to copy objects within or between buckets. To copy objects between buckets,\n        `self`'s credentials must have permission to read the source object and write\n        to the target object. If the credentials do not have those permissions, try\n        using `S3Bucket.stream_from`.\n\n        Args:\n            from_path: The path of the object to copy.\n            to_path: The path to copy the object to.\n            to_bucket: The bucket to copy to. Defaults to the current bucket.\n            **copy_kwargs: Additional keyword arguments to pass to\n                `S3Client.copy_object`.\n\n        Returns:\n            The path that the object was copied to. Excludes the bucket name.\n\n        Examples:\n\n            Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n            ```\n\n            Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n            another bucket.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.copy_object(\n                \"my_folder/notes.txt\",\n                \"my_folder/notes_copy.txt\",\n                to_bucket=\"other-bucket\"\n            )\n            ```\n        \"\"\"\n        s3_client = self.credentials.get_s3_client()\n\n        source_bucket_name = self.bucket_name\n        source_path = self._resolve_path(Path(from_path).as_posix())\n\n        # Default to copying within the same bucket\n        to_bucket = to_bucket or self\n\n        target_bucket_name: str\n        target_path: str\n        if isinstance(to_bucket, S3Bucket):\n            target_bucket_name = to_bucket.bucket_name\n            target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n        elif isinstance(to_bucket, str):\n            target_bucket_name = to_bucket\n            target_path = Path(to_path).as_posix()\n        else:\n            raise TypeError(\n                f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n            )\n\n        self.logger.info(\n            \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n            source_bucket_name,\n            source_path,\n            target_bucket_name,\n            target_path,\n        )\n\n        s3_client.copy_object(\n            CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n            Bucket=target_bucket_name,\n            Key=target_path,\n            **copy_kwargs,\n        )\n\n        return target_path\n\n    @sync_compatible\n    async def move_object(\n        self,\n        from_path: Union[str, Path],\n        to_path: Union[str, Path],\n        to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n    ) -&gt; str:\n        \"\"\"Uses S3's internal CopyObject and DeleteObject to move objects within or\n        between buckets. To move objects between buckets, `self`'s credentials must\n        have permission to read and delete the source object and write to the target\n        object. If the credentials do not have those permissions, this method will\n        raise an error. If the credentials have permission to read the source object\n        but not delete it, the object will be copied but not deleted.\n\n        Args:\n            from_path: The path of the object to move.\n            to_path: The path to move the object to.\n            to_bucket: The bucket to move to. Defaults to the current bucket.\n\n        Returns:\n            The path that the object was moved to. Excludes the bucket name.\n\n        Examples:\n\n            Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n            ```\n\n            Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n            another bucket.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.move_object(\n                \"my_folder/notes.txt\",\n                \"my_folder/notes_copy.txt\",\n                to_bucket=\"other-bucket\"\n            )\n            ```\n        \"\"\"\n        s3_client = self.credentials.get_s3_client()\n\n        source_bucket_name = self.bucket_name\n        source_path = self._resolve_path(Path(from_path).as_posix())\n\n        # Default to moving within the same bucket\n        to_bucket = to_bucket or self\n\n        target_bucket_name: str\n        target_path: str\n        if isinstance(to_bucket, S3Bucket):\n            target_bucket_name = to_bucket.bucket_name\n            target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n        elif isinstance(to_bucket, str):\n            target_bucket_name = to_bucket\n            target_path = Path(to_path).as_posix()\n        else:\n            raise TypeError(\n                f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n            )\n\n        self.logger.info(\n            \"Moving object from s3://%s/%s to s3://%s/%s\",\n            source_bucket_name,\n            source_path,\n            target_bucket_name,\n            target_path,\n        )\n\n        # If invalid, should error and prevent next operation\n        s3_client.copy(\n            CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n            Bucket=target_bucket_name,\n            Key=target_path,\n        )\n        s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n        return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.basepath","title":"<code>basepath: str</code>  <code>property</code> <code>writable</code>","text":"<p>The base path of the S3 bucket.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The base path of the S3 bucket.</p>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.copy_object","title":"<code>copy_object</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject to copy objects within or between buckets. To copy objects between buckets, <code>self</code>'s credentials must have permission to read the source object and write to the target object. If the credentials do not have those permissions, try using <code>S3Bucket.stream_from</code>.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path of the object to copy.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path to copy the object to.</p> required <code>to_bucket</code> <code>Optional[Union[S3Bucket, str]]</code> <p>The bucket to copy to. Defaults to the current bucket.</p> <code>None</code> <code>**copy_kwargs</code> <p>Additional keyword arguments to pass to <code>S3Client.copy_object</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was copied to. Excludes the bucket name.</p> <pre><code>Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n```\n\nCopy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\nanother bucket.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.copy_object(\n    \"my_folder/notes.txt\",\n    \"my_folder/notes_copy.txt\",\n    to_bucket=\"other-bucket\"\n)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def copy_object(\n    self,\n    from_path: Union[str, Path],\n    to_path: Union[str, Path],\n    to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n    **copy_kwargs,\n) -&gt; str:\n    \"\"\"Uses S3's internal\n    [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n    to copy objects within or between buckets. To copy objects between buckets,\n    `self`'s credentials must have permission to read the source object and write\n    to the target object. If the credentials do not have those permissions, try\n    using `S3Bucket.stream_from`.\n\n    Args:\n        from_path: The path of the object to copy.\n        to_path: The path to copy the object to.\n        to_bucket: The bucket to copy to. Defaults to the current bucket.\n        **copy_kwargs: Additional keyword arguments to pass to\n            `S3Client.copy_object`.\n\n    Returns:\n        The path that the object was copied to. Excludes the bucket name.\n\n    Examples:\n\n        Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n        ```\n\n        Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n        another bucket.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.copy_object(\n            \"my_folder/notes.txt\",\n            \"my_folder/notes_copy.txt\",\n            to_bucket=\"other-bucket\"\n        )\n        ```\n    \"\"\"\n    s3_client = self.credentials.get_s3_client()\n\n    source_bucket_name = self.bucket_name\n    source_path = self._resolve_path(Path(from_path).as_posix())\n\n    # Default to copying within the same bucket\n    to_bucket = to_bucket or self\n\n    target_bucket_name: str\n    target_path: str\n    if isinstance(to_bucket, S3Bucket):\n        target_bucket_name = to_bucket.bucket_name\n        target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n    elif isinstance(to_bucket, str):\n        target_bucket_name = to_bucket\n        target_path = Path(to_path).as_posix()\n    else:\n        raise TypeError(\n            f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n        )\n\n    self.logger.info(\n        \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    s3_client.copy_object(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n        **copy_kwargs,\n    )\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Downloads objects within a folder (excluding the folder itself) from the S3 bucket to a folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The path to the folder to download from.</p> required <code>to_folder</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the folder to.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the folder was downloaded to.</p> <p>Examples:</p> <p>Download my_folder to a local folder named my_folder. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads objects *within* a folder (excluding the folder itself)\n    from the S3 bucket to a folder.\n\n    Args:\n        from_folder: The path to the folder to download from.\n        to_folder: The path to download the folder to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_file`.\n\n    Returns:\n        The absolute path that the folder was downloaded to.\n\n    Examples:\n        Download my_folder to a local folder named my_folder.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n        ```\n    \"\"\"\n    if to_folder is None:\n        to_folder = \"\"\n    to_folder = Path(to_folder).absolute()\n\n    client = self.credentials.get_s3_client()\n    objects = await self.list_objects(folder=from_folder)\n\n    # do not call self._join_bucket_folder for filter\n    # because it's built-in to that method already!\n    # however, we still need to do it because we're using relative_to\n    bucket_folder = self._join_bucket_folder(from_folder)\n\n    async_coros = []\n    for object in objects:\n        bucket_path = Path(object[\"Key\"]).relative_to(bucket_folder)\n        # this skips the actual directory itself, e.g.\n        # `my_folder/` will be skipped\n        # `my_folder/notes.txt` will be downloaded\n        if bucket_path.is_dir():\n            continue\n        to_path = to_folder / bucket_path\n        to_path.parent.mkdir(parents=True, exist_ok=True)\n        to_path = str(to_path)  # must be string\n        self.logger.info(\n            f\"Downloading object from bucket {self.bucket_name!r} path \"\n            f\"{bucket_path.as_posix()!r} to {to_path!r}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                client.download_file,\n                Bucket=self.bucket_name,\n                Key=object[\"Key\"],\n                Filename=to_path,\n                **download_kwargs,\n            )\n        )\n    await asyncio.gather(*async_coros)\n\n    return Path(to_folder)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a file-like object, which can be a BytesIO object or a BufferedWriter.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the object to download from; this gets prefixed with the bucket_folder.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file-like object to download the object to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BinaryIO</code> <p>The file-like object that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\n\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith BytesIO() as buf:\n    s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n</code></pre></p> <p>Download my_folder/notes.txt object to a BufferedWriter. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"wb\") as f:\n    s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; BinaryIO:\n    \"\"\"\n    Downloads an object from the object storage service to a file-like object,\n    which can be a BytesIO object or a BufferedWriter.\n\n    Args:\n        from_path: The path to the object to download from; this gets prefixed\n            with the bucket_folder.\n        to_file_object: The file-like object to download the object to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_fileobj`.\n\n    Returns:\n        The file-like object that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with BytesIO() as buf:\n            s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n        ```\n\n        Download my_folder/notes.txt object to a BufferedWriter.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"wb\") as f:\n            s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n        ```\n    \"\"\"\n    client = self.credentials.get_s3_client()\n    bucket_path = self._join_bucket_folder(from_path)\n\n    self.logger.debug(\n        f\"Preparing to download object from bucket {self.bucket_name!r} \"\n        f\"path {bucket_path!r} to file object.\"\n    )\n    await run_sync_in_worker_thread(\n        client.download_fileobj,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        Fileobj=to_file_object,\n        **download_kwargs,\n    )\n    self.logger.info(\n        f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n        \"to file object.\"\n    )\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from the S3 bucket to a path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the object to download; this gets prefixed with the bucket_folder.</p> required <code>to_path</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the object to. If not provided, the object's name will be used.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Optional[Union[str, Path]],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads an object from the S3 bucket to a path.\n\n    Args:\n        from_path: The path to the object to download; this gets prefixed\n            with the bucket_folder.\n        to_path: The path to download the object to. If not provided, the\n            object's name will be used.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_file`.\n\n    Returns:\n        The absolute path that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # making path absolute, but converting back to str here\n    # since !r looks nicer that way and filename arg expects str\n    to_path = str(Path(to_path).absolute())\n    bucket_path = self._join_bucket_folder(from_path)\n    client = self.credentials.get_s3_client()\n\n    self.logger.debug(\n        f\"Preparing to download object from bucket {self.bucket_name!r} \"\n        f\"path {bucket_path!r} to {to_path!r}.\"\n    )\n    await run_sync_in_worker_thread(\n        client.download_file,\n        Bucket=self.bucket_name,\n        Key=from_path,\n        Filename=to_path,\n        **download_kwargs,\n    )\n    self.logger.info(\n        f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n        f\"to {to_path!r}.\"\n    )\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a folder from the configured S3 bucket to a local directory.</p> <p>Defaults to copying the entire contents of the block's basepath to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>Path in S3 bucket to download from. Defaults to the block's configured basepath.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>Local path to download S3 contents to. Defaults to the current working directory.</p> <code>None</code> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Copies a folder from the configured S3 bucket to a local directory.\n\n    Defaults to copying the entire contents of the block's basepath to the current\n    working directory.\n\n    Args:\n        from_path: Path in S3 bucket to download from. Defaults to the block's\n            configured basepath.\n        local_path: Local path to download S3 contents to. Defaults to the current\n            working directory.\n    \"\"\"\n    bucket_folder = self.bucket_folder\n    if from_path is None:\n        from_path = str(bucket_folder) if bucket_folder else \"\"\n\n    if local_path is None:\n        local_path = str(Path(\".\").absolute())\n    else:\n        local_path = str(Path(local_path).expanduser())\n\n    bucket = self._get_bucket_resource()\n    for obj in bucket.objects.filter(Prefix=from_path):\n        if obj.key[-1] == \"/\":\n            # object is a folder and will be created if it contains any objects\n            continue\n        target = os.path.join(\n            local_path,\n            os.path.relpath(obj.key, from_path),\n        )\n        os.makedirs(os.path.dirname(target), exist_ok=True)\n        bucket.download_file(obj.key, target)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.list_objects","title":"<code>list_objects</code>  <code>async</code>","text":"<p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>Folder to list objects from.</p> <code>''</code> <code>delimiter</code> <code>str</code> <p>Character used to group keys of listed objects.</p> <code>''</code> <code>page_size</code> <code>Optional[int]</code> <p>Number of objects to return in each request to the AWS API.</p> <code>None</code> <code>max_items</code> <code>Optional[int]</code> <p>Maximum number of objects that to be returned by task.</p> <code>None</code> <code>jmespath_query</code> <code>Optional[str]</code> <p>Query used to filter objects based on object attributes refer to the boto3 docs for more information on how to construct queries.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Dict[str, Any]]</code> <p>List of objects and their metadata in the bucket.</p> <p>Examples:</p> <p>List objects under the <code>base_folder</code>. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.list_objects(\"base_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def list_objects(\n    self,\n    folder: str = \"\",\n    delimiter: str = \"\",\n    page_size: Optional[int] = None,\n    max_items: Optional[int] = None,\n    jmespath_query: Optional[str] = None,\n) -&gt; List[Dict[str, Any]]:\n    \"\"\"\n    Args:\n        folder: Folder to list objects from.\n        delimiter: Character used to group keys of listed objects.\n        page_size: Number of objects to return in each request to the AWS API.\n        max_items: Maximum number of objects that to be returned by task.\n        jmespath_query: Query used to filter objects based on object attributes refer to\n            the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n            for more information on how to construct queries.\n\n    Returns:\n        List of objects and their metadata in the bucket.\n\n    Examples:\n        List objects under the `base_folder`.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.list_objects(\"base_folder\")\n        ```\n    \"\"\"  # noqa: E501\n    bucket_path = self._join_bucket_folder(folder)\n    client = self.credentials.get_s3_client()\n    paginator = client.get_paginator(\"list_objects_v2\")\n    page_iterator = paginator.paginate(\n        Bucket=self.bucket_name,\n        Prefix=bucket_path,\n        Delimiter=delimiter,\n        PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n    )\n    if jmespath_query:\n        page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n    self.logger.info(f\"Listing objects in bucket {bucket_path}.\")\n    objects = await run_sync_in_worker_thread(\n        self._list_objects_sync, page_iterator\n    )\n    return objects\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.move_object","title":"<code>move_object</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject and DeleteObject to move objects within or between buckets. To move objects between buckets, <code>self</code>'s credentials must have permission to read and delete the source object and write to the target object. If the credentials do not have those permissions, this method will raise an error. If the credentials have permission to read the source object but not delete it, the object will be copied but not deleted.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path of the object to move.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path to move the object to.</p> required <code>to_bucket</code> <code>Optional[Union[S3Bucket, str]]</code> <p>The bucket to move to. Defaults to the current bucket.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was moved to. Excludes the bucket name.</p> <pre><code>Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n```\n\nMove notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\nanother bucket.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.move_object(\n    \"my_folder/notes.txt\",\n    \"my_folder/notes_copy.txt\",\n    to_bucket=\"other-bucket\"\n)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def move_object(\n    self,\n    from_path: Union[str, Path],\n    to_path: Union[str, Path],\n    to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n) -&gt; str:\n    \"\"\"Uses S3's internal CopyObject and DeleteObject to move objects within or\n    between buckets. To move objects between buckets, `self`'s credentials must\n    have permission to read and delete the source object and write to the target\n    object. If the credentials do not have those permissions, this method will\n    raise an error. If the credentials have permission to read the source object\n    but not delete it, the object will be copied but not deleted.\n\n    Args:\n        from_path: The path of the object to move.\n        to_path: The path to move the object to.\n        to_bucket: The bucket to move to. Defaults to the current bucket.\n\n    Returns:\n        The path that the object was moved to. Excludes the bucket name.\n\n    Examples:\n\n        Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n        ```\n\n        Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n        another bucket.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.move_object(\n            \"my_folder/notes.txt\",\n            \"my_folder/notes_copy.txt\",\n            to_bucket=\"other-bucket\"\n        )\n        ```\n    \"\"\"\n    s3_client = self.credentials.get_s3_client()\n\n    source_bucket_name = self.bucket_name\n    source_path = self._resolve_path(Path(from_path).as_posix())\n\n    # Default to moving within the same bucket\n    to_bucket = to_bucket or self\n\n    target_bucket_name: str\n    target_path: str\n    if isinstance(to_bucket, S3Bucket):\n        target_bucket_name = to_bucket.bucket_name\n        target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n    elif isinstance(to_bucket, str):\n        target_bucket_name = to_bucket\n        target_path = Path(to_path).as_posix()\n    else:\n        raise TypeError(\n            f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n        )\n\n    self.logger.info(\n        \"Moving object from s3://%s/%s to s3://%s/%s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    # If invalid, should error and prevent next operation\n    s3_client.copy(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n    )\n    s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to the configured S3 bucket in a given folder.</p> <p>Defaults to uploading the entire contents the current working directory to the block's basepath.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>Optional[str]</code> <p>Path to local directory to upload from.</p> <code>None</code> <code>to_path</code> <code>Optional[str]</code> <p>Path in S3 bucket to upload to. Defaults to block's configured basepath.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>Path to file containing gitignore style expressions for filepaths to ignore.</p> <code>None</code> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to the configured S3 bucket in a\n    given folder.\n\n    Defaults to uploading the entire contents the current working directory to the\n    block's basepath.\n\n    Args:\n        local_path: Path to local directory to upload from.\n        to_path: Path in S3 bucket to upload to. Defaults to block's configured\n            basepath.\n        ignore_file: Path to file containing gitignore style expressions for\n            filepaths to ignore.\n\n    \"\"\"\n    to_path = \"\" if to_path is None else to_path\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(local_path, ignore_patterns)\n\n    uploaded_file_count = 0\n    for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(to_path) / local_file_path.relative_to(\n                local_path\n            )\n            with open(local_file_path, \"rb\") as local_file:\n                local_file_content = local_file.read()\n\n            await self.write_path(\n                remote_file_path.as_posix(), content=local_file_content\n            )\n            uploaded_file_count += 1\n\n    return uploaded_file_count\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Read specified path from S3 and return contents. Provide the entire path to the key in S3.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Entire path to (and including) the key.</p> required Example <p>Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\": <pre><code>from prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import S3Bucket\n\naws_creds = AwsCredentials(\n    aws_access_key_id=AWS_ACCESS_KEY_ID,\n    aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n)\n\ns3_bucket_block = S3Bucket(\n    bucket_name=\"bucket\",\n    credentials=aws_creds,\n    bucket_folder=\"subfolder\"\n)\n\nkey_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Read specified path from S3 and return contents. Provide the entire\n    path to the key in S3.\n\n    Args:\n        path: Entire path to (and including) the key.\n\n    Example:\n        Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\":\n        ```python\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import S3Bucket\n\n        aws_creds = AwsCredentials(\n            aws_access_key_id=AWS_ACCESS_KEY_ID,\n            aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n        )\n\n        s3_bucket_block = S3Bucket(\n            bucket_name=\"bucket\",\n            credentials=aws_creds,\n            bucket_folder=\"subfolder\"\n        )\n\n        key_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n        ```\n    \"\"\"\n    path = self._resolve_path(path)\n\n    return await run_sync_in_worker_thread(self._read_sync, path)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.stream_from","title":"<code>stream_from</code>  <code>async</code>","text":"<p>Streams an object from another bucket to this bucket. Requires the object to be downloaded and uploaded in chunks. If <code>self</code>'s credentials allow for writes to the other bucket, try using <code>S3Bucket.copy_object</code>.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>S3Bucket</code> <p>The bucket to stream from.</p> required <code>from_path</code> <code>str</code> <p>The path of the object to stream.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to stream the object to. Defaults to the object's name.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.</p> <pre><code>from prefect_aws.s3 import S3Bucket\n\nyour_s3_bucket = S3Bucket.load(\"your-bucket\")\nmy_s3_bucket = S3Bucket.load(\"my-bucket\")\n\nmy_s3_bucket.stream_from(\n    your_s3_bucket,\n    \"notes.txt\",\n    to_path=\"landed/notes.txt\"\n)\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def stream_from(\n    self,\n    bucket: \"S3Bucket\",\n    from_path: str,\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"Streams an object from another bucket to this bucket. Requires the\n    object to be downloaded and uploaded in chunks. If `self`'s credentials\n    allow for writes to the other bucket, try using `S3Bucket.copy_object`.\n\n    Args:\n        bucket: The bucket to stream from.\n        from_path: The path of the object to stream.\n        to_path: The path to stream the object to. Defaults to the object's name.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        your_s3_bucket = S3Bucket.load(\"your-bucket\")\n        my_s3_bucket = S3Bucket.load(\"my-bucket\")\n\n        my_s3_bucket.stream_from(\n            your_s3_bucket,\n            \"notes.txt\",\n            to_path=\"landed/notes.txt\"\n        )\n        ```\n\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # Get the source object's StreamingBody\n    from_path: str = bucket._join_bucket_folder(from_path)\n    from_client = bucket.credentials.get_s3_client()\n    obj = await run_sync_in_worker_thread(\n        from_client.get_object, Bucket=bucket.bucket_name, Key=from_path\n    )\n    body: StreamingBody = obj[\"Body\"]\n\n    # Upload the StreamingBody to this bucket\n    bucket_path = str(self._join_bucket_folder(to_path))\n    to_client = self.credentials.get_s3_client()\n    await run_sync_in_worker_thread(\n        to_client.upload_fileobj,\n        Fileobj=body,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        f\"Streamed s3://{bucket.bucket_name}/{from_path} to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object to the S3 bucket from a file-like object, which can be a BytesIO object or a BufferedReader.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file-like object to upload from.</p> required <code>to_path</code> <code>str</code> <p>The path to upload the object to.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload BytesIO object to my_folder/notes.txt. <pre><code>from io import BytesIO\n\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n</code></pre></p> <p>Upload BufferedReader object to my_folder/notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    s3_bucket.upload_from_file_object(\n        f, \"my_folder/notes.txt\"\n    )\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; str:\n    \"\"\"\n    Uploads an object to the S3 bucket from a file-like object,\n    which can be a BytesIO object or a BufferedReader.\n\n    Args:\n        from_file_object: The file-like object to upload from.\n        to_path: The path to upload the object to.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload BytesIO object to my_folder/notes.txt.\n        ```python\n        from io import BytesIO\n\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n        ```\n\n        Upload BufferedReader object to my_folder/notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            s3_bucket.upload_from_file_object(\n                f, \"my_folder/notes.txt\"\n            )\n        ```\n    \"\"\"\n    bucket_path = str(self._join_bucket_folder(to_path))\n    client = self.credentials.get_s3_client()\n    await run_sync_in_worker_thread(\n        client.upload_fileobj,\n        Fileobj=from_file_object,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        \"Uploaded from file object to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files within a folder (excluding the folder itself) to the object storage service folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the folder to upload from.</p> required <code>to_folder</code> <code>Optional[str]</code> <p>The path to upload the folder to.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the folder was uploaded to.</p> <p>Examples:</p> <p>Upload contents from my_folder to new_folder. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads files *within* a folder (excluding the folder itself)\n    to the object storage service folder.\n\n    Args:\n        from_folder: The path to the folder to upload from.\n        to_folder: The path to upload the folder to.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the folder was uploaded to.\n\n    Examples:\n        Upload contents from my_folder to new_folder.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n        ```\n    \"\"\"\n    from_folder = Path(from_folder)\n    bucket_folder = self._join_bucket_folder(to_folder or \"\")\n\n    num_uploaded = 0\n    client = self.credentials.get_s3_client()\n\n    async_coros = []\n    for from_path in from_folder.rglob(\"**/*\"):\n        # this skips the actual directory itself, e.g.\n        # `my_folder/` will be skipped\n        # `my_folder/notes.txt` will be uploaded\n        if from_path.is_dir():\n            continue\n        bucket_path = (\n            Path(bucket_folder) / from_path.relative_to(from_folder)\n        ).as_posix()\n        self.logger.info(\n            f\"Uploading from {str(from_path)!r} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                client.upload_file,\n                Filename=str(from_path),\n                Bucket=self.bucket_name,\n                Key=bucket_path,\n                **upload_kwargs,\n            )\n        )\n        num_uploaded += 1\n    await asyncio.gather(*async_coros)\n\n    if num_uploaded == 0:\n        self.logger.warning(f\"No files were uploaded from {str(from_folder)!r}.\")\n    else:\n        self.logger.info(\n            f\"Uploaded {num_uploaded} files from {str(from_folder)!r} to \"\n            f\"the bucket {self.bucket_name!r} path {bucket_path!r}\"\n        )\n\n    return to_folder\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a path to the S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path to the file to upload from.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to upload the file to.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload notes.txt to my_folder/notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self,\n    from_path: Union[str, Path],\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads an object from a path to the S3 bucket.\n\n    Args:\n        from_path: The path to the file to upload from.\n        to_path: The path to upload the file to.\n        **upload_kwargs: Additional keyword arguments to pass to `Client.upload`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload notes.txt to my_folder/notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n        ```\n    \"\"\"\n    from_path = str(Path(from_path).absolute())\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    bucket_path = str(self._join_bucket_folder(to_path))\n    client = self.credentials.get_s3_client()\n\n    await run_sync_in_worker_thread(\n        client.upload_file,\n        Filename=from_path,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        f\"Uploaded from {from_path!r} to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes to an S3 bucket.</p> <p>Args:</p> <pre><code>path: The key name. Each object in your bucket has a unique\n    key (or key name).\ncontent: What you are uploading to S3.\n</code></pre> <p>Example:</p> <pre><code>Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n```python\nfrom prefect_aws import MinioCredentials\nfrom prefect_aws.s3 import S3Bucket\n\nminio_creds = MinIOCredentials(\n    minio_root_user = \"minioadmin\",\n    minio_root_password = \"minioadmin\",\n)\n\ns3_bucket_block = S3Bucket(\n    bucket_name=\"bucket\",\n    minio_credentials=minio_creds,\n    bucket_folder=\"dogs/smalldogs\",\n    endpoint_url=\"http://localhost:9000\",\n)\ns3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; str:\n    \"\"\"\n    Writes to an S3 bucket.\n\n    Args:\n\n        path: The key name. Each object in your bucket has a unique\n            key (or key name).\n        content: What you are uploading to S3.\n\n    Example:\n\n        Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n        ```python\n        from prefect_aws import MinioCredentials\n        from prefect_aws.s3 import S3Bucket\n\n        minio_creds = MinIOCredentials(\n            minio_root_user = \"minioadmin\",\n            minio_root_password = \"minioadmin\",\n        )\n\n        s3_bucket_block = S3Bucket(\n            bucket_name=\"bucket\",\n            minio_credentials=minio_creds,\n            bucket_folder=\"dogs/smalldogs\",\n            endpoint_url=\"http://localhost:9000\",\n        )\n        s3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n        ```\n    \"\"\"\n\n    path = self._resolve_path(path)\n\n    await run_sync_in_worker_thread(self._write_sync, path, content)\n\n    return path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_copy","title":"<code>s3_copy</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject to copy objects within or between buckets. To copy objects between buckets, the credentials must have permission to read the source object and write to the target object. If the credentials do not have those permissions, try using <code>S3Bucket.stream_from</code>.</p> <p>Parameters:</p> Name Type Description Default <code>source_path</code> <code>str</code> <p>The path to the object to copy. Can be a string or <code>Path</code>.</p> required <code>target_path</code> <code>str</code> <p>The path to copy the object to. Can be a string or <code>Path</code>.</p> required <code>source_bucket_name</code> <code>str</code> <p>The bucket to copy the object from.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>target_bucket_name</code> <code>Optional[str]</code> <p>The bucket to copy the object to. If not provided, defaults to <code>source_bucket</code>.</p> <code>None</code> <code>**copy_kwargs</code> <p>Additional keyword arguments to pass to <code>S3Client.copy_object</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was copied to. Excludes the bucket name.</p> <pre><code>Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\ns3://my-bucket/my_folder/notes_copy.txt.\n\n```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_copy\n\naws_credentials = AwsCredentials.load(\"my-creds\")\n\n@flow\nasync def example_copy_flow():\n    await s3_copy(\n        source_path=\"my_folder/notes.txt\",\n        target_path=\"my_folder/notes_copy.txt\",\n        source_bucket_name=\"my-bucket\",\n        aws_credentials=aws_credentials,\n    )\n\nexample_copy_flow()\n```\n\nCopy notes.txt from s3://my-bucket/my_folder/notes.txt to\ns3://other-bucket/notes_copy.txt.\n\n```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_copy\n\naws_credentials = AwsCredentials.load(\"shared-creds\")\n\n@flow\nasync def example_copy_flow():\n    await s3_copy(\n        source_path=\"my_folder/notes.txt\",\n        target_path=\"notes_copy.txt\",\n        source_bucket_name=\"my-bucket\",\n        aws_credentials=aws_credentials,\n        target_bucket_name=\"other-bucket\",\n    )\n\nexample_copy_flow()\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_copy(\n    source_path: str,\n    target_path: str,\n    source_bucket_name: str,\n    aws_credentials: AwsCredentials,\n    target_bucket_name: Optional[str] = None,\n    **copy_kwargs,\n) -&gt; str:\n    \"\"\"Uses S3's internal\n    [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n    to copy objects within or between buckets. To copy objects between buckets, the\n    credentials must have permission to read the source object and write to the target\n    object. If the credentials do not have those permissions, try using\n    `S3Bucket.stream_from`.\n\n    Args:\n        source_path: The path to the object to copy. Can be a string or `Path`.\n        target_path: The path to copy the object to. Can be a string or `Path`.\n        source_bucket_name: The bucket to copy the object from.\n        aws_credentials: Credentials to use for authentication with AWS.\n        target_bucket_name: The bucket to copy the object to. If not provided, defaults\n            to `source_bucket`.\n        **copy_kwargs: Additional keyword arguments to pass to `S3Client.copy_object`.\n\n    Returns:\n        The path that the object was copied to. Excludes the bucket name.\n\n    Examples:\n\n        Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\n        s3://my-bucket/my_folder/notes_copy.txt.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_copy\n\n        aws_credentials = AwsCredentials.load(\"my-creds\")\n\n        @flow\n        async def example_copy_flow():\n            await s3_copy(\n                source_path=\"my_folder/notes.txt\",\n                target_path=\"my_folder/notes_copy.txt\",\n                source_bucket_name=\"my-bucket\",\n                aws_credentials=aws_credentials,\n            )\n\n        example_copy_flow()\n        ```\n\n        Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\n        s3://other-bucket/notes_copy.txt.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_copy\n\n        aws_credentials = AwsCredentials.load(\"shared-creds\")\n\n        @flow\n        async def example_copy_flow():\n            await s3_copy(\n                source_path=\"my_folder/notes.txt\",\n                target_path=\"notes_copy.txt\",\n                source_bucket_name=\"my-bucket\",\n                aws_credentials=aws_credentials,\n                target_bucket_name=\"other-bucket\",\n            )\n\n        example_copy_flow()\n        ```\n\n    \"\"\"\n    logger = get_run_logger()\n\n    s3_client = aws_credentials.get_s3_client()\n\n    target_bucket_name = target_bucket_name or source_bucket_name\n\n    logger.info(\n        \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    s3_client.copy_object(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n        **copy_kwargs,\n    )\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_download","title":"<code>s3_download</code>  <code>async</code>","text":"<p>Downloads an object with a given key from a given S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of bucket to download object from. Required if a default value was not supplied when creating the task.</p> required <code>key</code> <code>str</code> <p>Key of object to download. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization.</p> <code>AwsClientParameters()</code> <p>Returns:</p> Type Description <code>bytes</code> <p>A <code>bytes</code> representation of the downloaded object.</p> Example <p>Download a file from an S3 bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_download\n\n\n@flow\nasync def example_s3_download_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    data = await s3_download(\n        bucket=\"bucket\",\n        key=\"key\",\n        aws_credentials=aws_credentials,\n    )\n\nexample_s3_download_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_download(\n    bucket: str,\n    key: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n) -&gt; bytes:\n    \"\"\"\n    Downloads an object with a given key from a given S3 bucket.\n\n    Args:\n        bucket: Name of bucket to download object from. Required if a default value was\n            not supplied when creating the task.\n        key: Key of object to download. Required if a default value was not supplied\n            when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization.\n\n\n    Returns:\n        A `bytes` representation of the downloaded object.\n\n    Example:\n        Download a file from an S3 bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_download\n\n\n        @flow\n        async def example_s3_download_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            data = await s3_download(\n                bucket=\"bucket\",\n                key=\"key\",\n                aws_credentials=aws_credentials,\n            )\n\n        example_s3_download_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading object from bucket %s with key %s\", bucket, key)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    stream = io.BytesIO()\n    await run_sync_in_worker_thread(\n        s3_client.download_fileobj, Bucket=bucket, Key=key, Fileobj=stream\n    )\n    stream.seek(0)\n    output = stream.read()\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_list_objects","title":"<code>s3_list_objects</code>  <code>async</code>","text":"<p>Lists details of objects in a given S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of bucket to list items from. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization..</p> <code>AwsClientParameters()</code> <code>prefix</code> <code>str</code> <p>Used to filter objects with keys starting with the specified prefix.</p> <code>''</code> <code>delimiter</code> <code>str</code> <p>Character used to group keys of listed objects.</p> <code>''</code> <code>page_size</code> <code>Optional[int]</code> <p>Number of objects to return in each request to the AWS API.</p> <code>None</code> <code>max_items</code> <code>Optional[int]</code> <p>Maximum number of objects that to be returned by task.</p> <code>None</code> <code>jmespath_query</code> <code>Optional[str]</code> <p>Query used to filter objects based on object attributes refer to the boto3 docs for more information on how to construct queries.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Dict[str, Any]]</code> <p>A list of dictionaries containing information about the objects retrieved. Refer to the boto3 docs for an example response.</p> Example <p>List all objects in a bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_list_objects\n\n\n@flow\nasync def example_s3_list_objects_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    objects = await s3_list_objects(\n        bucket=\"data_bucket\",\n        aws_credentials=aws_credentials\n    )\n\nexample_s3_list_objects_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_list_objects(\n    bucket: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n    prefix: str = \"\",\n    delimiter: str = \"\",\n    page_size: Optional[int] = None,\n    max_items: Optional[int] = None,\n    jmespath_query: Optional[str] = None,\n) -&gt; List[Dict[str, Any]]:\n    \"\"\"\n    Lists details of objects in a given S3 bucket.\n\n    Args:\n        bucket: Name of bucket to list items from. Required if a default value was not\n            supplied when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization..\n        prefix: Used to filter objects with keys starting with the specified prefix.\n        delimiter: Character used to group keys of listed objects.\n        page_size: Number of objects to return in each request to the AWS API.\n        max_items: Maximum number of objects that to be returned by task.\n        jmespath_query: Query used to filter objects based on object attributes refer to\n            the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n            for more information on how to construct queries.\n\n    Returns:\n        A list of dictionaries containing information about the objects retrieved. Refer\n            to the boto3 docs for an example response.\n\n    Example:\n        List all objects in a bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_list_objects\n\n\n        @flow\n        async def example_s3_list_objects_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            objects = await s3_list_objects(\n                bucket=\"data_bucket\",\n                aws_credentials=aws_credentials\n            )\n\n        example_s3_list_objects_flow()\n        ```\n    \"\"\"  # noqa E501\n    logger = get_run_logger()\n    logger.info(\"Listing objects in bucket %s with prefix %s\", bucket, prefix)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    paginator = s3_client.get_paginator(\"list_objects_v2\")\n    page_iterator = paginator.paginate(\n        Bucket=bucket,\n        Prefix=prefix,\n        Delimiter=delimiter,\n        PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n    )\n    if jmespath_query:\n        page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n    return await run_sync_in_worker_thread(_list_objects_sync, page_iterator)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_move","title":"<code>s3_move</code>  <code>async</code>","text":"<p>Move an object from one S3 location to another. To move objects between buckets, the credentials must have permission to read and delete the source object and write to the target object. If the credentials do not have those permissions, this method will raise an error. If the credentials have permission to read the source object but not delete it, the object will be copied but not deleted.</p> <p>Parameters:</p> Name Type Description Default <code>source_path</code> <code>str</code> <p>The path of the object to move</p> required <code>target_path</code> <code>str</code> <p>The path to move the object to</p> required <code>source_bucket_name</code> <code>str</code> <p>The name of the bucket containing the source object</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>target_bucket_name</code> <code>Optional[str]</code> <p>The bucket to copy the object to. If not provided, defaults to <code>source_bucket</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was moved to. Excludes the bucket name.</p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_move(\n    source_path: str,\n    target_path: str,\n    source_bucket_name: str,\n    aws_credentials: AwsCredentials,\n    target_bucket_name: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Move an object from one S3 location to another. To move objects between buckets,\n    the credentials must have permission to read and delete the source object and write\n    to the target object. If the credentials do not have those permissions, this method\n    will raise an error. If the credentials have permission to read the source object\n    but not delete it, the object will be copied but not deleted.\n\n    Args:\n        source_path: The path of the object to move\n        target_path: The path to move the object to\n        source_bucket_name: The name of the bucket containing the source object\n        aws_credentials: Credentials to use for authentication with AWS.\n        target_bucket_name: The bucket to copy the object to. If not provided, defaults\n            to `source_bucket`.\n\n    Returns:\n        The path that the object was moved to. Excludes the bucket name.\n    \"\"\"\n    logger = get_run_logger()\n\n    s3_client = aws_credentials.get_s3_client()\n\n    # If target bucket is not provided, assume it's the same as the source bucket\n    target_bucket_name = target_bucket_name or source_bucket_name\n\n    logger.info(\n        \"Moving object from s3://%s/%s s3://%s/%s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    # Copy the object to the new location\n    s3_client.copy_object(\n        Bucket=target_bucket_name,\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Key=target_path,\n    )\n\n    # Delete the original object\n    s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_upload","title":"<code>s3_upload</code>  <code>async</code>","text":"<p>Uploads data to an S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>bytes</code> <p>Bytes representation of data to upload to S3.</p> required <code>bucket</code> <code>str</code> <p>Name of bucket to upload data to. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization..</p> <code>AwsClientParameters()</code> <code>key</code> <code>Optional[str]</code> <p>Key of object to download. Defaults to a UUID string.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The key of the uploaded object</p> Example <p>Read and upload a file to an S3 bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_upload\n\n\n@flow\nasync def example_s3_upload_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    with open(\"data.csv\", \"rb\") as file:\n        key = await s3_upload(\n            bucket=\"bucket\",\n            key=\"data.csv\",\n            data=file.read(),\n            aws_credentials=aws_credentials,\n        )\n\nexample_s3_upload_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_upload(\n    data: bytes,\n    bucket: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n    key: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Uploads data to an S3 bucket.\n\n    Args:\n        data: Bytes representation of data to upload to S3.\n        bucket: Name of bucket to upload data to. Required if a default value was not\n            supplied when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization..\n        key: Key of object to download. Defaults to a UUID string.\n\n    Returns:\n        The key of the uploaded object\n\n    Example:\n        Read and upload a file to an S3 bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_upload\n\n\n        @flow\n        async def example_s3_upload_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            with open(\"data.csv\", \"rb\") as file:\n                key = await s3_upload(\n                    bucket=\"bucket\",\n                    key=\"data.csv\",\n                    data=file.read(),\n                    aws_credentials=aws_credentials,\n                )\n\n        example_s3_upload_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    key = key or str(uuid.uuid4())\n\n    logger.info(\"Uploading object to bucket %s with key %s\", bucket, key)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    stream = io.BytesIO(data)\n    await run_sync_in_worker_thread(\n        s3_client.upload_fileobj, stream, Bucket=bucket, Key=key\n    )\n\n    return key\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/","title":"Secrets Manager","text":""},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager","title":"<code>prefect_aws.secrets_manager</code>","text":"<p>Tasks for interacting with AWS Secrets Manager</p>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret","title":"<code>AwsSecret</code>","text":"<p>               Bases: <code>SecretBlock</code></p> <p>Manages a secret in AWS's Secrets Manager.</p> <p>Attributes:</p> Name Type Description <code>aws_credentials</code> <code>AwsCredentials</code> <p>The credentials to use for authentication with AWS.</p> <code>secret_name</code> <code>str</code> <p>The name of the secret.</p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>class AwsSecret(SecretBlock):\n    \"\"\"\n    Manages a secret in AWS's Secrets Manager.\n\n    Attributes:\n        aws_credentials: The credentials to use for authentication with AWS.\n        secret_name: The name of the secret.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"AWS Secret\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret\"  # noqa\n\n    aws_credentials: AwsCredentials\n    secret_name: str = Field(default=..., description=\"The name of the secret.\")\n\n    @sync_compatible\n    async def read_secret(\n        self,\n        version_id: str = None,\n        version_stage: str = None,\n        **read_kwargs: Dict[str, Any],\n    ) -&gt; bytes:\n        \"\"\"\n        Reads the secret from the secret storage service.\n\n        Args:\n            version_id: The version of the secret to read. If not provided, the latest\n                version will be read.\n            version_stage: The version stage of the secret to read. If not provided,\n                the latest version will be read.\n            read_kwargs: Additional keyword arguments to pass to the\n                `get_secret_value` method of the boto3 client.\n\n        Returns:\n            The secret data.\n\n        Examples:\n            Reads a secret.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.read_secret()\n            ```\n        \"\"\"\n        client = self.aws_credentials.get_secrets_manager_client()\n        if version_id is not None:\n            read_kwargs[\"VersionId\"] = version_id\n        if version_stage is not None:\n            read_kwargs[\"VersionStage\"] = version_stage\n        response = await run_sync_in_worker_thread(\n            client.get_secret_value, SecretId=self.secret_name, **read_kwargs\n        )\n        if \"SecretBinary\" in response:\n            secret = response[\"SecretBinary\"]\n        elif \"SecretString\" in response:\n            secret = response[\"SecretString\"]\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret {arn!r} data was successfully read.\")\n        return secret\n\n    @sync_compatible\n    async def write_secret(\n        self, secret_data: bytes, **put_or_create_secret_kwargs: Dict[str, Any]\n    ) -&gt; str:\n        \"\"\"\n        Writes the secret to the secret storage service as a SecretBinary;\n        if it doesn't exist, it will be created.\n\n        Args:\n            secret_data: The secret data to write.\n            **put_or_create_secret_kwargs: Additional keyword arguments to pass to\n                put_secret_value or create_secret method of the boto3 client.\n\n        Returns:\n            The path that the secret was written to.\n\n        Examples:\n            Write some secret data.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.write_secret(b\"my_secret_data\")\n            ```\n        \"\"\"\n        client = self.aws_credentials.get_secrets_manager_client()\n        try:\n            response = await run_sync_in_worker_thread(\n                client.put_secret_value,\n                SecretId=self.secret_name,\n                SecretBinary=secret_data,\n                **put_or_create_secret_kwargs,\n            )\n        except client.exceptions.ResourceNotFoundException:\n            self.logger.info(\n                f\"The secret {self.secret_name!r} does not exist yet, creating it now.\"\n            )\n            response = await run_sync_in_worker_thread(\n                client.create_secret,\n                Name=self.secret_name,\n                SecretBinary=secret_data,\n                **put_or_create_secret_kwargs,\n            )\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret data was written successfully to {arn!r}.\")\n        return arn\n\n    @sync_compatible\n    async def delete_secret(\n        self,\n        recovery_window_in_days: int = 30,\n        force_delete_without_recovery: bool = False,\n        **delete_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Deletes the secret from the secret storage service.\n\n        Args:\n            recovery_window_in_days: The number of days to wait before permanently\n                deleting the secret. Must be between 7 and 30 days.\n            force_delete_without_recovery: If True, the secret will be deleted\n                immediately without a recovery window.\n            **delete_kwargs: Additional keyword arguments to pass to the\n                delete_secret method of the boto3 client.\n\n        Returns:\n            The path that the secret was deleted from.\n\n        Examples:\n            Deletes the secret with a recovery window of 15 days.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.delete_secret(recovery_window_in_days=15)\n            ```\n        \"\"\"\n        if force_delete_without_recovery and recovery_window_in_days:\n            raise ValueError(\n                \"Cannot specify recovery window and force delete without recovery.\"\n            )\n        elif not (7 &lt;= recovery_window_in_days &lt;= 30):\n            raise ValueError(\n                \"Recovery window must be between 7 and 30 days, got \"\n                f\"{recovery_window_in_days}.\"\n            )\n\n        client = self.aws_credentials.get_secrets_manager_client()\n        response = await run_sync_in_worker_thread(\n            client.delete_secret,\n            SecretId=self.secret_name,\n            RecoveryWindowInDays=recovery_window_in_days,\n            ForceDeleteWithoutRecovery=force_delete_without_recovery,\n            **delete_kwargs,\n        )\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret {arn} was deleted successfully.\")\n        return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the secret from the secret storage service.</p> <p>Parameters:</p> Name Type Description Default <code>recovery_window_in_days</code> <code>int</code> <p>The number of days to wait before permanently deleting the secret. Must be between 7 and 30 days.</p> <code>30</code> <code>force_delete_without_recovery</code> <code>bool</code> <p>If True, the secret will be deleted immediately without a recovery window.</p> <code>False</code> <code>**delete_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the delete_secret method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was deleted from.</p> <p>Examples:</p> <p>Deletes the secret with a recovery window of 15 days. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.delete_secret(recovery_window_in_days=15)\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def delete_secret(\n    self,\n    recovery_window_in_days: int = 30,\n    force_delete_without_recovery: bool = False,\n    **delete_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Deletes the secret from the secret storage service.\n\n    Args:\n        recovery_window_in_days: The number of days to wait before permanently\n            deleting the secret. Must be between 7 and 30 days.\n        force_delete_without_recovery: If True, the secret will be deleted\n            immediately without a recovery window.\n        **delete_kwargs: Additional keyword arguments to pass to the\n            delete_secret method of the boto3 client.\n\n    Returns:\n        The path that the secret was deleted from.\n\n    Examples:\n        Deletes the secret with a recovery window of 15 days.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.delete_secret(recovery_window_in_days=15)\n        ```\n    \"\"\"\n    if force_delete_without_recovery and recovery_window_in_days:\n        raise ValueError(\n            \"Cannot specify recovery window and force delete without recovery.\"\n        )\n    elif not (7 &lt;= recovery_window_in_days &lt;= 30):\n        raise ValueError(\n            \"Recovery window must be between 7 and 30 days, got \"\n            f\"{recovery_window_in_days}.\"\n        )\n\n    client = self.aws_credentials.get_secrets_manager_client()\n    response = await run_sync_in_worker_thread(\n        client.delete_secret,\n        SecretId=self.secret_name,\n        RecoveryWindowInDays=recovery_window_in_days,\n        ForceDeleteWithoutRecovery=force_delete_without_recovery,\n        **delete_kwargs,\n    )\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret {arn} was deleted successfully.\")\n    return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the secret from the secret storage service.</p> <p>Parameters:</p> Name Type Description Default <code>version_id</code> <code>str</code> <p>The version of the secret to read. If not provided, the latest version will be read.</p> <code>None</code> <code>version_stage</code> <code>str</code> <p>The version stage of the secret to read. If not provided, the latest version will be read.</p> <code>None</code> <code>read_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>get_secret_value</code> method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>bytes</code> <p>The secret data.</p> <p>Examples:</p> <p>Reads a secret. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.read_secret()\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def read_secret(\n    self,\n    version_id: str = None,\n    version_stage: str = None,\n    **read_kwargs: Dict[str, Any],\n) -&gt; bytes:\n    \"\"\"\n    Reads the secret from the secret storage service.\n\n    Args:\n        version_id: The version of the secret to read. If not provided, the latest\n            version will be read.\n        version_stage: The version stage of the secret to read. If not provided,\n            the latest version will be read.\n        read_kwargs: Additional keyword arguments to pass to the\n            `get_secret_value` method of the boto3 client.\n\n    Returns:\n        The secret data.\n\n    Examples:\n        Reads a secret.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.read_secret()\n        ```\n    \"\"\"\n    client = self.aws_credentials.get_secrets_manager_client()\n    if version_id is not None:\n        read_kwargs[\"VersionId\"] = version_id\n    if version_stage is not None:\n        read_kwargs[\"VersionStage\"] = version_stage\n    response = await run_sync_in_worker_thread(\n        client.get_secret_value, SecretId=self.secret_name, **read_kwargs\n    )\n    if \"SecretBinary\" in response:\n        secret = response[\"SecretBinary\"]\n    elif \"SecretString\" in response:\n        secret = response[\"SecretString\"]\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret {arn!r} data was successfully read.\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.write_secret","title":"<code>write_secret</code>  <code>async</code>","text":"<p>Writes the secret to the secret storage service as a SecretBinary; if it doesn't exist, it will be created.</p> <p>Parameters:</p> Name Type Description Default <code>secret_data</code> <code>bytes</code> <p>The secret data to write.</p> required <code>**put_or_create_secret_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to put_secret_value or create_secret method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was written to.</p> <p>Examples:</p> <p>Write some secret data. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.write_secret(b\"my_secret_data\")\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def write_secret(\n    self, secret_data: bytes, **put_or_create_secret_kwargs: Dict[str, Any]\n) -&gt; str:\n    \"\"\"\n    Writes the secret to the secret storage service as a SecretBinary;\n    if it doesn't exist, it will be created.\n\n    Args:\n        secret_data: The secret data to write.\n        **put_or_create_secret_kwargs: Additional keyword arguments to pass to\n            put_secret_value or create_secret method of the boto3 client.\n\n    Returns:\n        The path that the secret was written to.\n\n    Examples:\n        Write some secret data.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.write_secret(b\"my_secret_data\")\n        ```\n    \"\"\"\n    client = self.aws_credentials.get_secrets_manager_client()\n    try:\n        response = await run_sync_in_worker_thread(\n            client.put_secret_value,\n            SecretId=self.secret_name,\n            SecretBinary=secret_data,\n            **put_or_create_secret_kwargs,\n        )\n    except client.exceptions.ResourceNotFoundException:\n        self.logger.info(\n            f\"The secret {self.secret_name!r} does not exist yet, creating it now.\"\n        )\n        response = await run_sync_in_worker_thread(\n            client.create_secret,\n            Name=self.secret_name,\n            SecretBinary=secret_data,\n            **put_or_create_secret_kwargs,\n        )\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret data was written successfully to {arn!r}.\")\n    return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.create_secret","title":"<code>create_secret</code>  <code>async</code>","text":"<p>Creates a secret in AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>The name of the secret to create.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>The value to store in the created secret.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>description</code> <code>Optional[str]</code> <p>A description for the created secret.</p> <code>None</code> <code>tags</code> <code>Optional[List[Dict[str, str]]]</code> <p>A list of tags to attach to the secret. Each tag should be specified as a dictionary in the following format: <pre><code>{\n    \"Key\": str,\n    \"Value\": str\n}\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and current version ID. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"VersionId\": str\n}\n</code></pre></p> <pre><code>```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import create_secret\n\n@flow\ndef example_create_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    create_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        secret_value=\"42\",\n        aws_credentials=aws_credentials\n    )\n\nexample_create_secret()\n```\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def create_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    aws_credentials: AwsCredentials,\n    description: Optional[str] = None,\n    tags: Optional[List[Dict[str, str]]] = None,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Creates a secret in AWS Secrets Manager.\n\n    Args:\n        secret_name: The name of the secret to create.\n        secret_value: The value to store in the created secret.\n        aws_credentials: Credentials to use for authentication with AWS.\n        description: A description for the created secret.\n        tags: A list of tags to attach to the secret. Each tag should be specified as a\n            dictionary in the following format:\n            ```python\n            {\n                \"Key\": str,\n                \"Value\": str\n            }\n            ```\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and current version ID.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"VersionId\": str\n            }\n            ```\n    Example:\n        Create a secret:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import create_secret\n\n        @flow\n        def example_create_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            create_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                secret_value=\"42\",\n                aws_credentials=aws_credentials\n            )\n\n        example_create_secret()\n        ```\n\n\n    \"\"\"\n    create_secret_kwargs: Dict[str, Union[str, bytes, List[Dict[str, str]]]] = dict(\n        Name=secret_name\n    )\n    if description is not None:\n        create_secret_kwargs[\"Description\"] = description\n    if tags is not None:\n        create_secret_kwargs[\"Tags\"] = tags\n    if isinstance(secret_value, bytes):\n        create_secret_kwargs[\"SecretBinary\"] = secret_value\n    elif isinstance(secret_value, str):\n        create_secret_kwargs[\"SecretString\"] = secret_value\n    else:\n        raise ValueError(\"Please provide a bytes or str value for secret_value\")\n\n    logger = get_run_logger()\n    logger.info(\"Creating secret named %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.create_secret, **create_secret_kwargs\n        )\n        print(response.pop(\"ResponseMetadata\", None))\n        return response\n    except ClientError:\n        logger.exception(\"Unable to create secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes a secret from AWS Secrets Manager.</p> <p>Secrets can either be deleted immediately by setting <code>force_delete_without_recovery</code> equal to <code>True</code>. Otherwise, secrets will be marked for deletion and available for recovery for the number of days specified in <code>recovery_window_in_days</code></p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to be deleted.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>recovery_window_in_days</code> <code>int</code> <p>Number of days a secret should be recoverable for before permanent deletion. Minimum window is 7 days and maximum window is 30 days. If <code>force_delete_without_recovery</code> is set to <code>True</code>, this value will be ignored.</p> <code>30</code> <code>force_delete_without_recovery</code> <code>bool</code> <p>If <code>True</code>, the secret will be immediately deleted and will not be recoverable.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and deletion date of the secret. DeletionDate is the date and time of the delete request plus the number of days in <code>recovery_window_in_days</code>. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"DeletionDate\": datetime.datetime\n}\n</code></pre></p> <p>Examples:</p> <p>Delete a secret immediately:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import delete_secret\n\n@flow\ndef example_delete_secret_immediately():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    delete_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        aws_credentials=aws_credentials,\n        force_delete_without_recovery: True\n    )\n\nexample_delete_secret_immediately()\n</code></pre> <p>Delete a secret with a 90 day recovery window:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import delete_secret\n\n@flow\ndef example_delete_secret_with_recovery_window():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    delete_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        aws_credentials=aws_credentials,\n        recovery_window_in_days=90\n    )\n\nexample_delete_secret_with_recovery_window()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def delete_secret(\n    secret_name: str,\n    aws_credentials: AwsCredentials,\n    recovery_window_in_days: int = 30,\n    force_delete_without_recovery: bool = False,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Deletes a secret from AWS Secrets Manager.\n\n    Secrets can either be deleted immediately by setting `force_delete_without_recovery`\n    equal to `True`. Otherwise, secrets will be marked for deletion and available for\n    recovery for the number of days specified in `recovery_window_in_days`\n\n    Args:\n        secret_name: Name of the secret to be deleted.\n        aws_credentials: Credentials to use for authentication with AWS.\n        recovery_window_in_days: Number of days a secret should be recoverable for\n            before permanent deletion. Minimum window is 7 days and maximum window\n            is 30 days. If `force_delete_without_recovery` is set to `True`, this\n            value will be ignored.\n        force_delete_without_recovery: If `True`, the secret will be immediately\n            deleted and will not be recoverable.\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and deletion date of the secret. DeletionDate is the date and\n            time of the delete request plus the number of days in\n            `recovery_window_in_days`.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"DeletionDate\": datetime.datetime\n            }\n            ```\n\n    Examples:\n        Delete a secret immediately:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import delete_secret\n\n        @flow\n        def example_delete_secret_immediately():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            delete_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                aws_credentials=aws_credentials,\n                force_delete_without_recovery: True\n            )\n\n        example_delete_secret_immediately()\n        ```\n\n        Delete a secret with a 90 day recovery window:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import delete_secret\n\n        @flow\n        def example_delete_secret_with_recovery_window():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            delete_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                aws_credentials=aws_credentials,\n                recovery_window_in_days=90\n            )\n\n        example_delete_secret_with_recovery_window()\n        ```\n\n\n    \"\"\"\n    if not force_delete_without_recovery and not (7 &lt;= recovery_window_in_days &lt;= 30):\n        raise ValueError(\"Recovery window must be between 7 and 30 days.\")\n\n    delete_secret_kwargs: Dict[str, Union[str, int, bool]] = dict(SecretId=secret_name)\n    if force_delete_without_recovery:\n        delete_secret_kwargs[\n            \"ForceDeleteWithoutRecovery\"\n        ] = force_delete_without_recovery\n    else:\n        delete_secret_kwargs[\"RecoveryWindowInDays\"] = recovery_window_in_days\n\n    logger = get_run_logger()\n    logger.info(\"Deleting secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.delete_secret, **delete_secret_kwargs\n        )\n        response.pop(\"ResponseMetadata\", None)\n        return response\n    except ClientError:\n        logger.exception(\"Unable to delete secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the value of a given secret from AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of stored secret.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>version_id</code> <code>Optional[str]</code> <p>Specifies version of secret to read. Defaults to the most recent version if not given.</p> <code>None</code> <code>version_stage</code> <code>Optional[str]</code> <p>Specifies the version stage of the secret to read. Defaults to AWS_CURRENT if not given.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[str, bytes]</code> <p>The secret values as a <code>str</code> or <code>bytes</code> depending on the format in which the secret was stored.</p> Example <p>Read a secret value:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import read_secret\n\n@flow\ndef example_read_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    secret_value = read_secret(\n        secret_name=\"db_password\",\n        aws_credentials=aws_credentials\n    )\n\nexample_read_secret()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def read_secret(\n    secret_name: str,\n    aws_credentials: AwsCredentials,\n    version_id: Optional[str] = None,\n    version_stage: Optional[str] = None,\n) -&gt; Union[str, bytes]:\n    \"\"\"\n    Reads the value of a given secret from AWS Secrets Manager.\n\n    Args:\n        secret_name: Name of stored secret.\n        aws_credentials: Credentials to use for authentication with AWS.\n        version_id: Specifies version of secret to read. Defaults to the most recent\n            version if not given.\n        version_stage: Specifies the version stage of the secret to read. Defaults to\n            AWS_CURRENT if not given.\n\n    Returns:\n        The secret values as a `str` or `bytes` depending on the format in which the\n            secret was stored.\n\n    Example:\n        Read a secret value:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import read_secret\n\n        @flow\n        def example_read_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            secret_value = read_secret(\n                secret_name=\"db_password\",\n                aws_credentials=aws_credentials\n            )\n\n        example_read_secret()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Getting value for secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    get_secret_value_kwargs = dict(SecretId=secret_name)\n    if version_id is not None:\n        get_secret_value_kwargs[\"VersionId\"] = version_id\n    if version_stage is not None:\n        get_secret_value_kwargs[\"VersionStage\"] = version_stage\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.get_secret_value, **get_secret_value_kwargs\n        )\n    except ClientError:\n        logger.exception(\"Unable to get value for secret %s\", secret_name)\n        raise\n    else:\n        return response.get(\"SecretString\") or response.get(\"SecretBinary\")\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.update_secret","title":"<code>update_secret</code>  <code>async</code>","text":"<p>Updates the value of a given secret in AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of secret to update.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>Desired value of the secret. Can be either <code>str</code> or <code>bytes</code>.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>description</code> <code>Optional[str]</code> <p>Desired description of the secret.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and current version ID. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"VersionId\": str\n}\n</code></pre></p> Example <p>Update a secret value:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import update_secret\n\n@flow\ndef example_update_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    update_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        secret_value=\"42\",\n        aws_credentials=aws_credentials\n    )\n\nexample_update_secret()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def update_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    aws_credentials: AwsCredentials,\n    description: Optional[str] = None,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Updates the value of a given secret in AWS Secrets Manager.\n\n    Args:\n        secret_name: Name of secret to update.\n        secret_value: Desired value of the secret. Can be either `str` or `bytes`.\n        aws_credentials: Credentials to use for authentication with AWS.\n        description: Desired description of the secret.\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and current version ID.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"VersionId\": str\n            }\n            ```\n\n    Example:\n        Update a secret value:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import update_secret\n\n        @flow\n        def example_update_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            update_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                secret_value=\"42\",\n                aws_credentials=aws_credentials\n            )\n\n        example_update_secret()\n        ```\n\n    \"\"\"\n    update_secret_kwargs: Dict[str, Union[str, bytes]] = dict(SecretId=secret_name)\n    if description is not None:\n        update_secret_kwargs[\"Description\"] = description\n    if isinstance(secret_value, bytes):\n        update_secret_kwargs[\"SecretBinary\"] = secret_value\n    elif isinstance(secret_value, str):\n        update_secret_kwargs[\"SecretString\"] = secret_value\n    else:\n        raise ValueError(\"Please provide a bytes or str value for secret_value\")\n\n    logger = get_run_logger()\n    logger.info(\"Updating value for secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.update_secret, **update_secret_kwargs\n        )\n        response.pop(\"ResponseMetadata\", None)\n        return response\n    except ClientError:\n        logger.exception(\"Unable to update secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps","title":"<code>prefect_aws.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage and retrieval in S3 and S3 compatible services.</p>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PullFromS3Output","title":"<code>PullFromS3Output</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>pull_from_s3</code> step.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>class PullFromS3Output(TypedDict):\n    \"\"\"\n    The output of the `pull_from_s3` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n    directory: str\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PullProjectFromS3Output","title":"<code>PullProjectFromS3Output</code>","text":"<p>               Bases: <code>PullFromS3Output</code></p> <p>Deprecated. Use <code>PullFromS3Output</code> instead..</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PullFromS3Output` instead.\")\nclass PullProjectFromS3Output(PullFromS3Output):\n    \"\"\"Deprecated. Use `PullFromS3Output` instead..\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PushProjectToS3Output","title":"<code>PushProjectToS3Output</code>","text":"<p>               Bases: <code>PushToS3Output</code></p> <p>Deprecated. Use <code>PushToS3Output</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PushToS3Output` instead.\")\nclass PushProjectToS3Output(PushToS3Output):\n    \"\"\"Deprecated. Use `PushToS3Output` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PushToS3Output","title":"<code>PushToS3Output</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>push_to_s3</code> step.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>class PushToS3Output(TypedDict):\n    \"\"\"\n    The output of the `push_to_s3` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.pull_from_s3","title":"<code>pull_from_s3</code>","text":"<p>Pulls the contents of an S3 bucket folder to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the S3 bucket where files are stored.</p> required <code>folder</code> <code>str</code> <p>The folder in the S3 bucket where files are stored.</p> required <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary of AWS credentials (aws_access_key_id, aws_secret_access_key, aws_session_token) or MinIO credentials (minio_root_user, minio_root_password).</p> <code>None</code> <code>client_parameters</code> <code>Optional[Dict]</code> <p>A dictionary of additional parameters to pass to the boto3 client.</p> <code>None</code> <p>Returns:</p> Type Description <code>PullFromS3Output</code> <p>A dictionary containing the bucket, folder, and local directory where files were downloaded.</p> <p>Examples:</p> <p>Pull files from S3 using the default credentials and client parameters: <pre><code>pull:\n    - prefect_aws.deployments.steps.pull_from_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Pull files from S3 using credentials stored in a block: <pre><code>pull:\n    - prefect_aws.deployments.steps.pull_from_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n        credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre></p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>def pull_from_s3(\n    bucket: str,\n    folder: str,\n    credentials: Optional[Dict] = None,\n    client_parameters: Optional[Dict] = None,\n) -&gt; PullFromS3Output:\n    \"\"\"\n    Pulls the contents of an S3 bucket folder to the current working directory.\n\n    Args:\n        bucket: The name of the S3 bucket where files are stored.\n        folder: The folder in the S3 bucket where files are stored.\n        credentials: A dictionary of AWS credentials (aws_access_key_id,\n            aws_secret_access_key, aws_session_token) or MinIO credentials\n            (minio_root_user, minio_root_password).\n        client_parameters: A dictionary of additional parameters to pass to the\n            boto3 client.\n\n    Returns:\n        A dictionary containing the bucket, folder, and local directory where\n            files were downloaded.\n\n    Examples:\n        Pull files from S3 using the default credentials and client parameters:\n        ```yaml\n        pull:\n            - prefect_aws.deployments.steps.pull_from_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Pull files from S3 using credentials stored in a block:\n        ```yaml\n        pull:\n            - prefect_aws.deployments.steps.pull_from_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n                credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n        ```\n    \"\"\"\n    s3 = get_s3_client(credentials=credentials, client_parameters=client_parameters)\n\n    local_path = Path.cwd()\n\n    paginator = s3.get_paginator(\"list_objects_v2\")\n    for result in paginator.paginate(Bucket=bucket, Prefix=folder):\n        for obj in result.get(\"Contents\", []):\n            remote_key = obj[\"Key\"]\n\n            if remote_key[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n\n            target = PurePosixPath(\n                local_path\n                / relative_path_to_current_platform(remote_key).relative_to(folder)\n            )\n            Path.mkdir(Path(target.parent), parents=True, exist_ok=True)\n            s3.download_file(bucket, remote_key, str(target))\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n        \"directory\": str(local_path),\n    }\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.pull_project_from_s3","title":"<code>pull_project_from_s3</code>","text":"<p>Deprecated. Use <code>pull_from_s3</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `pull_from_s3` instead.\")\ndef pull_project_from_s3(*args, **kwargs):\n    \"\"\"Deprecated. Use `pull_from_s3` instead.\"\"\"\n    pull_from_s3(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.push_project_to_s3","title":"<code>push_project_to_s3</code>","text":"<p>Deprecated. Use <code>push_to_s3</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `push_to_s3` instead.\")\ndef push_project_to_s3(*args, **kwargs):\n    \"\"\"Deprecated. Use `push_to_s3` instead.\"\"\"\n    push_to_s3(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.push_to_s3","title":"<code>push_to_s3</code>","text":"<p>Pushes the contents of the current working directory to an S3 bucket, excluding files and folders specified in the ignore_file.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the S3 bucket where files will be uploaded.</p> required <code>folder</code> <code>str</code> <p>The folder in the S3 bucket where files will be uploaded.</p> required <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary of AWS credentials (aws_access_key_id, aws_secret_access_key, aws_session_token) or MinIO credentials (minio_root_user, minio_root_password).</p> <code>None</code> <code>client_parameters</code> <code>Optional[Dict]</code> <p>A dictionary of additional parameters to pass to the boto3 client.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>The name of the file containing ignore patterns.</p> <code>'.prefectignore'</code> <p>Returns:</p> Type Description <code>PushToS3Output</code> <p>A dictionary containing the bucket and folder where files were uploaded.</p> <p>Examples:</p> <p>Push files to an S3 bucket: <pre><code>push:\n    - prefect_aws.deployments.steps.push_to_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Push files to an S3 bucket using credentials stored in a block: <pre><code>push:\n    - prefect_aws.deployments.steps.push_to_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n        credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre></p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>def push_to_s3(\n    bucket: str,\n    folder: str,\n    credentials: Optional[Dict] = None,\n    client_parameters: Optional[Dict] = None,\n    ignore_file: Optional[str] = \".prefectignore\",\n) -&gt; PushToS3Output:\n    \"\"\"\n    Pushes the contents of the current working directory to an S3 bucket,\n    excluding files and folders specified in the ignore_file.\n\n    Args:\n        bucket: The name of the S3 bucket where files will be uploaded.\n        folder: The folder in the S3 bucket where files will be uploaded.\n        credentials: A dictionary of AWS credentials (aws_access_key_id,\n            aws_secret_access_key, aws_session_token) or MinIO credentials\n            (minio_root_user, minio_root_password).\n        client_parameters: A dictionary of additional parameters to pass to the boto3\n            client.\n        ignore_file: The name of the file containing ignore patterns.\n\n    Returns:\n        A dictionary containing the bucket and folder where files were uploaded.\n\n    Examples:\n        Push files to an S3 bucket:\n        ```yaml\n        push:\n            - prefect_aws.deployments.steps.push_to_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Push files to an S3 bucket using credentials stored in a block:\n        ```yaml\n        push:\n            - prefect_aws.deployments.steps.push_to_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n                credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n        ```\n\n    \"\"\"\n    s3 = get_s3_client(credentials=credentials, client_parameters=client_parameters)\n\n    local_path = Path.cwd()\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    for local_file_path in local_path.expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(folder) / local_file_path.relative_to(local_path)\n            s3.upload_file(\n                str(local_file_path), bucket, str(remote_file_path.as_posix())\n            )\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-azure/","title":"prefect-azure","text":"<p><code>prefect-azure</code> makes it easy to leverage the capabilities of Azure in your workflows. For example, you can retrieve secrets, read and write Blob Storage objects, and deploy your flows on Azure Container Instances (ACI).</p>"},{"location":"integrations/prefect-azure/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-azure/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>An Azure account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-azure/#install-prefect-azure","title":"Install prefect-azure","text":"<pre><code>pip install -U prefect-azure\n</code></pre> <p>If necessary, see additional installation options for Blob Storage, Cosmos DB, and ML Datastore.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-azure[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-azure/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the module to make them available for use.</p> <pre><code>prefect block register -m prefect_azure\n</code></pre>"},{"location":"integrations/prefect-azure/#examples","title":"Examples","text":""},{"location":"integrations/prefect-azure/#download-a-blob","title":"Download a blob","text":"<pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef example_blob_storage_download_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    data = blob_storage_download(\n        blob=\"prefect.txt\",\n        container=\"prefect\",\n        azure_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_download_flow()\n</code></pre> <p>Use <code>with_options</code> to customize options on any existing task or flow:</p> <pre><code>custom_blob_storage_download_flow = example_blob_storage_download_flow.with_options(\n    name=\"My custom task name\",\n    retries=2,\n    retry_delay_seconds=10,\n)\n</code></pre>"},{"location":"integrations/prefect-azure/#run-flows-on-azure-container-instances","title":"Run flows on Azure Container Instances","text":"<p>Run flows on Azure Container Instances (ACI) to dynamically scale your infrastructure.</p> <p>See the Azure Container Instances Worker Guide for a walkthrough of using ACI in a hybrid work pool.</p> <p>If you're using Prefect Cloud, ACI push work pools provide all the benefits of ACI with a quick setup and no worker needed.</p>"},{"location":"integrations/prefect-azure/#resources","title":"Resources","text":"<p>For assistance using Azure, consult the Azure documentation.</p> <p>Refer to the prefect-azure API documentation linked in the sidebar to explore all the capabilities of the prefect-azure library.</p>"},{"location":"integrations/prefect-azure/#additional-installation-options","title":"Additional installation options","text":"<p>To use Blob Storage:</p> <pre><code>pip install -U \"prefect-azure[blob_storage]\"\n</code></pre> <p>To use Cosmos DB:</p> <pre><code>pip install -U \"prefect-azure[cosmos_db]\"\n</code></pre> <p>To use ML Datastore:</p> <pre><code>pip install -U \"prefect-azure[ml_datastore]\"\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/","title":"Azure Container Instances Worker Guide","text":""},{"location":"integrations/prefect-azure/aci_worker/#why-use-aci-for-flow-run-execution","title":"Why use ACI for flow run execution?","text":"<p>ACI (Azure Container Instances) is a fully managed compute platform that streamlines running your Prefect flows on scalable, on-demand infrastructure on Azure.</p>"},{"location":"integrations/prefect-azure/aci_worker/#prerequisites","title":"Prerequisites","text":"<p>Before starting this guide, make sure you have:</p> <ul> <li>An Azure account and user permissions for provisioning resource groups and container instances.</li> <li>The <code>azure</code> CLI installed on your local machine. You can follow Microsoft's installation guide.</li> <li>Docker installed on your local machine.</li> </ul>"},{"location":"integrations/prefect-azure/aci_worker/#step-1-create-a-resource-group","title":"Step 1. Create a resource group","text":"<p>Azure resource groups serve as containers for managing groupings of Azure resources.</p> <p>Replace <code>&lt;resource-group-name&gt;</code> with the name of your choosing, and <code>&lt;location&gt;</code> with a valid Azure location name, such as<code>eastus</code>.</p> <pre><code>export RG_NAME=&lt;resource-group-name&gt; &amp;&amp; \\\naz group create --name $RG_NAME --location &lt;location&gt;\n</code></pre> <p>Throughout the rest of the guide, we'll need to refer to the scope of the created resource group, which is a string describing where the resource group lives in the hierarchy of your Azure account. To save the scope of your resource group as an environment variable, run the following command:</p> <pre><code>RG_SCOPE=$(az group show --name $RG_NAME --query id --output tsv)\n</code></pre> <p>You can check that the scope is correct before moving on by running <code>echo $RG_SCOPE</code> in your terminal. It should be formatted as follows:</p> <pre><code>/subscriptions/&lt;subscription-id&gt;/resourceGroups/&lt;resource-group-name&gt;\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-2-prepare-aci-permissions","title":"Step 2. Prepare ACI permissions","text":"<p>In order for the worker to create, monitor, and delete the other container instances in which flows will run, we'll need to create a custom role and an identity, and then affiliate that role to the identity with a role assignment. When we start our worker, we'll assign that identity to the container instance it's running in.</p>"},{"location":"integrations/prefect-azure/aci_worker/#1-create-a-role","title":"1. Create a role","text":"<p>The custom <code>Container Instances Contributor</code> role has all the permissions your worker will need to run flows in other container instances. Create it by running the following command:</p> <pre><code>az role definition create --role-definition '{\n  \"Name\": \"Container Instances Contributor\",\n  \"IsCustom\": true,\n  \"Description\": \"Can create, delete, and monitor container instances.\",\n  \"Actions\": [\n    \"Microsoft.ManagedIdentity/userAssignedIdentities/assign/action\",\n    \"Microsoft.Resources/deployments/*\",\n    \"Microsoft.ContainerInstance/containerGroups/*\"\n  ],\n  \"NotActions\": [\n  ],\n  \"AssignableScopes\": [\n    '\"\\\"$RG_SCOPE\\\"\"'\n  ]\n}'\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#2-create-an-identity","title":"2. Create an identity","text":"<p>Create a user-managed identity with the following command, replacing <code>&lt;identity-name&gt;</code> with the name you'd like to use for the identity:</p> <pre><code>export IDENTITY_NAME=&lt;identity_name&gt; &amp;&amp; \\\naz identity create -g $RG_NAME -n $IDENTITY_NAME\n</code></pre> <p>We'll also need to save the principal ID and full object ID of the identity for the role assignment and container creation steps, respectively:</p> <pre><code>IDENTITY_PRINCIPAL_ID=$(az identity list --query \"[?name=='$IDENTITY_NAME'].principalId\" --output tsv) &amp;&amp; \\\nIDENTITY_ID=$(az identity list --query \"[?name=='$IDENTITY_NAME'].id\" --output tsv)\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#3-assign-roles-to-the-identity","title":"3. Assign roles to the identity","text":"<p>Now let's assign the <code>Container Instances Contributor</code> role we created earlier to the new identity:</p> <pre><code>az role assignment create \\\n    --assignee $IDENTITY_PRINCIPAL_ID \\\n    --role \"Container Instances Contributor\" \\\n    --scope $RG_SCOPE\n</code></pre> <p>Since we'll be using ACR to host a custom Docker image containing a Prefect flow later in the guide, let's also assign the built in <code>AcrPull</code> role to the identity:</p> <pre><code>az role assignment create \\\n    --assignee $IDENTITY_PRINCIPAL_ID \\\n    --role \"AcrPull\" \\\n    --scope $RG_SCOPE\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-3-create-the-worker-container-instance","title":"Step 3. Create the worker container instance","text":"<p>Before running this command, set your <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as environment variables:</p> <pre><code>export PREFECT_API_URL=&lt;PREFECT_API_URL_HERE&gt; PREFECT_API_KEY=&lt;PREFECT_API_KEY_HERE&gt;\n</code></pre> <p>Running the following command will create a container instance in your Azure resource group that will start a Prefect ACI worker. If there is not already a work pool in Prefect with the name you chose, a work pool will also be created.</p> <p>Replace <code>&lt;work-pool-name&gt;</code> with the name of the ACI work pool you want to create in Prefect. Here we're using the work pool name as the name of the container instance in Azure as well, but you may name it something else if you prefer.</p> <pre><code>az container create \\\n    --name &lt;work-pool-name&gt; \\\n    --resource-group $RG_NAME \\\n    --assign-identity $IDENTITY_ID \\\n    --image \"prefecthq/prefect:2-python3.11\" \\\n    --secure-environment-variables PREFECT_API_URL=$PREFECT_API_URL PREFECT_API_KEY=$PREFECT_API_KEY \\\n    --command-line \"/bin/bash -c 'pip install prefect-azure &amp;&amp; prefect worker start --pool &lt;work-pool-name&gt; --type azure-container-instance'\" \n</code></pre> <p>This container instance uses default networking and security settings. For advanced configuration, refer the <code>az container create</code> CLI reference.</p>"},{"location":"integrations/prefect-azure/aci_worker/#step-4-create-an-acr-registry","title":"Step 4. Create an ACR registry","text":"<p>In order to build and push images containing flow code to Azure, we'll need a container registry. Create one with the following command, replacing <code>&lt;registry-name&gt;</code> with the registry name of your choosing:</p> <pre><code>export REGISTRY_NAME=&lt;registry-name&gt; &amp;&amp; \\\naz acr create --resource-group $RG_NAME \\\n  --name &lt;registry-name&gt; --sku Basic\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-5-update-your-aci-work-pool-configuration","title":"Step 5. Update your ACI work pool configuration","text":"<p>Once your work pool is created, navigate to the Edit page of your ACI work pool. You will need to update the following fields:</p>"},{"location":"integrations/prefect-azure/aci_worker/#identities","title":"Identities","text":"<p>This will be your <code>IDENTITY_ID</code>. You can get it from your terminal by running <code>echo $IDENTITY_ID</code>. When adding it to your work pool, it should be formatted as a JSON array:</p> <pre><code>[\"/subscriptions/&lt;subscription-id&gt;/resourcegroups/&lt;resource-group-name&gt;/providers/Microsoft.ManagedIdentity/userAssignedIdentities/&lt;identity-name&gt;\"]\n</code></pre> <p></p>"},{"location":"integrations/prefect-azure/aci_worker/#acrmanagedidentity","title":"ACRManagedIdentity","text":"<p>ACRManagedIdentity is required for your flow code containers to be pulled from ACR. It consists of the following:</p> <ul> <li>Identity: the same <code>IDENTITY_ID</code> as above, as a string <pre><code>/subscriptions/&lt;subscription-id&gt;/resourcegroups/&lt;resource-group-name&gt;/providers/Microsoft.ManagedIdentity/userAssignedIdentities/&lt;identity-name&gt;\n</code></pre></li> <li>Registry URL: your <code>&lt;registry-name&gt;</code>, followed by <code>.azurecr.io</code> <pre><code>&lt;registry-name&gt;.azurecr.io\n</code></pre></li> </ul> <p></p>"},{"location":"integrations/prefect-azure/aci_worker/#subscription-id-and-resource-group-name","title":"Subscription ID and resource group name","text":"<p>Both the subscription ID and resource group name can be found in in the <code>RG_SCOPE</code> environment variable created earlier in the guide. View their values by running <code>echo $RG_SCOPE</code>:</p> <pre><code>/subscriptions/&lt;subscription-id&gt;/resourceGroups/&lt;resource-group-name&gt;\n</code></pre> <p></p> <p>Then click Save.</p>"},{"location":"integrations/prefect-azure/aci_worker/#step-6-pick-up-a-flow-run-with-your-new-worker","title":"Step 6. Pick up a flow run with your new worker","text":"<p>This guide uses ACR to store a Docker image containing your flow code. Write a flow, then deploy it using <code>flow.deploy()</code>, which will copy flow code into a Docker image and push that image to an ACR registry.</p>"},{"location":"integrations/prefect-azure/aci_worker/#1-log-in-to-acr","title":"1. Log in to ACR","text":"<p>Use the following commands to log in to ACR:</p> <pre><code>TOKEN=$(az acr login --name $REGISTRY_NAME --expose-token --output tsv --query accessToken)\n</code></pre> <pre><code>docker login $REGISTRY_NAME.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin &lt;&lt;&lt; $TOKEN\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#2-write-and-deploy-a-simple-test-flow","title":"2. Write and deploy a simple test flow","text":"<p>Create and run the following script to deploy your flow. Be sure to replace <code>&lt;registry-name&gt;</code> and <code>&lt;work-pool-name&gt;</code> with the appropriate values.</p> <p><code>my_flow.py</code></p> <pre><code>from prefect import flow, get_run_logger\nfrom prefect.deployments import DeploymentImage\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"Hello from ACI!\")\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"aci-deployment\",\n        image=DeploymentImage(\n            name=\"&lt;registry-name&gt;.azurecr.io/example:latest\",\n            platform=\"linux/amd64\",\n        ),\n        work_pool_name=\"&lt;work-pool-name&gt;\",\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#3-find-the-deployment-in-the-ui-and-click-the-quick-run-button","title":"3. Find the deployment in the UI and click the Quick Run button!","text":""},{"location":"integrations/prefect-azure/blob_storage/","title":"Blob Storage","text":""},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage","title":"<code>prefect_azure.blob_storage</code>","text":"<p>Integrations for interacting with Azure Blob Storage</p>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer","title":"<code>AzureBlobStorageContainer</code>","text":"<p>               Bases: <code>ObjectStorageBlock</code>, <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Represents a container in Azure Blob Storage.</p> <p>This class provides methods for downloading and uploading files and folders to and from the Azure Blob Storage container.</p> <p>Attributes:</p> Name Type Description <code>container_name</code> <code>str</code> <p>The name of the Azure Blob Storage container.</p> <code>credentials</code> <code>AzureBlobStorageCredentials</code> <p>The credentials to use for authentication with Azure.</p> <code>base_folder</code> <code>Optional[str]</code> <p>A base path to a folder within the container to use for reading and writing objects.</p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>class AzureBlobStorageContainer(\n    ObjectStorageBlock, WritableFileSystem, WritableDeploymentStorage\n):\n    \"\"\"\n    Represents a container in Azure Blob Storage.\n\n    This class provides methods for downloading and uploading files and folders\n    to and from the Azure Blob Storage container.\n\n    Attributes:\n        container_name: The name of the Azure Blob Storage container.\n        credentials: The credentials to use for authentication with Azure.\n        base_folder: A base path to a folder within the container to use\n            for reading and writing objects.\n    \"\"\"\n\n    _block_type_name = \"Azure Blob Storage Container\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/blob_storage/#prefect_azure.blob_storabe.AzureBlobStorageContainer\"  # noqa\n\n    container_name: str = Field(\n        default=..., description=\"The name of a Azure Blob Storage container.\"\n    )\n    credentials: AzureBlobStorageCredentials = Field(\n        default_factory=AzureBlobStorageCredentials,\n        description=\"The credentials to use for authentication with Azure.\",\n    )\n    base_folder: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A base path to a folder within the container to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    def _get_path_relative_to_base_folder(self, path: Optional[str] = None) -&gt; str:\n        if path is None and self.base_folder is None:\n            return \"\"\n        if path is None:\n            return self.base_folder\n        if self.base_folder is None:\n            return path\n        return (Path(self.base_folder) / Path(path)).as_posix()\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Union[str, Path],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, Path]:\n        \"\"\"Download a folder from the container to a local path.\n\n        Args:\n            from_folder: The folder path in the container to download.\n            to_folder: The local path to download the folder to.\n            **download_kwargs: Additional keyword arguments passed into\n                `BlobClient.download_blob`.\n\n        Returns:\n            The local path where the folder was downloaded.\n\n        Example:\n            Download the contents of container folder `folder` from the container\n                to the local folder `local_folder`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.download_folder_to_path(\n                from_folder=\"folder\",\n                to_folder=\"local_folder\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading folder from container %s to path %s\",\n            self.container_name,\n            to_folder,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_folder)\n        async with self.credentials.get_container_client(\n            self.container_name\n        ) as container_client:\n            try:\n                async for blob in container_client.list_blobs(\n                    name_starts_with=full_container_path\n                ):\n                    blob_path = blob.name\n                    local_path = Path(to_folder) / Path(blob_path).relative_to(\n                        full_container_path\n                    )\n                    local_path.parent.mkdir(parents=True, exist_ok=True)\n                    async with container_client.get_blob_client(\n                        blob_path\n                    ) as blob_client:\n                        blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                    with local_path.open(mode=\"wb\") as to_file:\n                        await blob_obj.readinto(to_file)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return Path(to_folder)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, BinaryIO]:\n        \"\"\"\n        Downloads an object from the container to a file object.\n\n        Args:\n            from_path : The path of the object to download within the container.\n            to_file_object: The file object to download the object to.\n            **download_kwargs: Additional keyword arguments for the download\n                operation.\n\n        Returns:\n            The file object that the object was downloaded to.\n\n        Example:\n            Download the object `object` from the container to a file object:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            with open(\"file.txt\", \"wb\") as f:\n                block.download_object_to_file_object(\n                    from_path=\"object\",\n                    to_file_object=f\n                )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading object from container %s to file object\", self.container_name\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                blob_obj = await blob_client.download_blob(**download_kwargs)\n                await blob_obj.download_to_stream(to_file_object)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_file_object\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Union[str, Path],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, Path]:\n        \"\"\"\n        Downloads an object from a container to a specified path.\n\n        Args:\n            from_path: The path of the object in the container.\n            to_path: The path where the object will be downloaded to.\n            **download_kwargs (Dict[str, Any]): Additional keyword arguments\n                for the download operation.\n\n        Returns:\n            The path where the object was downloaded to.\n\n        Example:\n            Download the object `object` from the container to the local path\n                `file.txt`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.download_object_to_path(\n                from_path=\"object\",\n                to_path=\"file.txt\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading object from container %s to path %s\",\n            self.container_name,\n            to_path,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                path = Path(to_path)\n\n                path.parent.mkdir(parents=True, exist_ok=True)\n\n                with path.open(mode=\"wb\") as to_file:\n                    await blob_obj.readinto(to_file)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n        return Path(to_path)\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads an object from a file object to the specified path in the blob\n            storage container.\n\n        Args:\n            from_file_object: The file object to upload.\n            to_path: The path in the blob storage container to upload the\n                object to.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                upload_blob method.\n\n        Returns:\n            The path where the object was uploaded to.\n\n        Example:\n            Upload a file object to the container at the path `object`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            with open(\"file.txt\", \"rb\") as f:\n                block.upload_from_file_object(\n                    from_file_object=f,\n                    to_path=\"object\"\n                )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading object to container %s with key %s\", self.container_name, to_path\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                await blob_client.upload_blob(from_file_object, **upload_kwargs)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to upload from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_path\n\n    @sync_compatible\n    async def upload_from_path(\n        self, from_path: Union[str, Path], to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads an object from a local path to the specified destination path in the\n            blob storage container.\n\n        Args:\n            from_path: The local path of the object to upload.\n            to_path: The destination path in the blob storage container.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                `upload_blob` method.\n\n        Returns:\n            The destination path in the blob storage container.\n\n        Example:\n            Upload a file from the local path `file.txt` to the container\n                at the path `object`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.upload_from_path(\n                from_path=\"file.txt\",\n                to_path=\"object\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading object to container %s with key %s\", self.container_name, to_path\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                with open(from_path, \"rb\") as f:\n                    await blob_client.upload_blob(f, **upload_kwargs)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to upload to container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: str,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads files from a local folder to a specified folder in the Azure\n            Blob Storage container.\n\n        Args:\n            from_folder: The path to the local folder containing the files to upload.\n            to_folder: The destination folder in the Azure Blob Storage container.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                `upload_blob` method.\n\n        Returns:\n            The full path of the destination folder in the container.\n\n        Example:\n            Upload the contents of the local folder `local_folder` to the container\n                folder `folder`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.upload_from_folder(\n                from_folder=\"local_folder\",\n                to_folder=\"folder\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading folder to container %s with key %s\",\n            self.container_name,\n            to_folder,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_folder)\n        async with self.credentials.get_container_client(\n            self.container_name\n        ) as container_client:\n            if not Path(from_folder).is_dir():\n                raise ValueError(f\"{from_folder} is not a directory\")\n            for path in Path(from_folder).rglob(\"*\"):\n                if path.is_file():\n                    blob_path = Path(full_container_path) / path.relative_to(\n                        from_folder\n                    )\n                    async with container_client.get_blob_client(\n                        blob_path.as_posix()\n                    ) as blob_client:\n                        try:\n                            await blob_client.upload_blob(\n                                path.read_bytes(), **upload_kwargs\n                            )\n                        except ResourceNotFoundError as exc:\n                            raise RuntimeError(\n                                \"An error occurred when attempting to upload to \"\n                                f\"container {self.container_name}: {exc.reason}\"\n                            ) from exc\n        return full_container_path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: str = None, local_path: str = None\n    ) -&gt; None:\n        \"\"\"\n        Downloads the contents of a direry from the blob storage to a local path.\n\n        Used to enable flow code storage for deployments.\n\n        Args:\n            from_path: The path of the directory in the blob storage.\n            local_path: The local path where the directory will be downloaded.\n        \"\"\"\n        await self.download_folder_to_path(from_path, local_path)\n\n    @sync_compatible\n    async def put_directory(\n        self, local_path: str = None, to_path: str = None, ignore_file: str = None\n    ) -&gt; None:\n        \"\"\"\n        Uploads a directory to the blob storage.\n\n        Used to enable flow code storage for deployments.\n\n        Args:\n            local_path: The local path of the directory to upload. Defaults to\n                current directory.\n            to_path: The destination path in the blob storage. Defaults to\n                root directory.\n            ignore_file: The path to a file containing patterns to ignore\n                during upload.\n        \"\"\"\n        to_path = \"\" if to_path is None else to_path\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(local_path, ignore_patterns)\n\n        for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(to_path) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as local_file:\n                    local_file_content = local_file.read()\n\n                await self.write_path(\n                    remote_file_path.as_posix(), content=local_file_content\n                )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Reads the contents of a file at the specified path and returns it as bytes.\n\n        Used to enable results storage.\n\n        Args:\n            path: The path of the file to read.\n\n        Returns:\n            The contents of the file as bytes.\n        \"\"\"\n        file_obj = BytesIO()\n        await self.download_object_to_file_object(path, file_obj)\n        return file_obj.getvalue()\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; None:\n        \"\"\"\n        Writes the content to the specified path in the blob storage.\n\n        Used to enable results storage.\n\n        Args:\n            path: The path where the content will be written.\n            content: The content to be written.\n        \"\"\"\n        await self.upload_from_file_object(BytesIO(content), path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Download a folder from the container to a local path.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The folder path in the container to download.</p> required <code>to_folder</code> <code>Union[str, Path]</code> <p>The local path to download the folder to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments passed into <code>BlobClient.download_blob</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, Path]</code> <p>The local path where the folder was downloaded.</p> Example <p>Download the contents of container folder <code>folder</code> from the container     to the local folder <code>local_folder</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.download_folder_to_path(\n    from_folder=\"folder\",\n    to_folder=\"local_folder\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Union[str, Path],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, Path]:\n    \"\"\"Download a folder from the container to a local path.\n\n    Args:\n        from_folder: The folder path in the container to download.\n        to_folder: The local path to download the folder to.\n        **download_kwargs: Additional keyword arguments passed into\n            `BlobClient.download_blob`.\n\n    Returns:\n        The local path where the folder was downloaded.\n\n    Example:\n        Download the contents of container folder `folder` from the container\n            to the local folder `local_folder`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.download_folder_to_path(\n            from_folder=\"folder\",\n            to_folder=\"local_folder\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading folder from container %s to path %s\",\n        self.container_name,\n        to_folder,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_folder)\n    async with self.credentials.get_container_client(\n        self.container_name\n    ) as container_client:\n        try:\n            async for blob in container_client.list_blobs(\n                name_starts_with=full_container_path\n            ):\n                blob_path = blob.name\n                local_path = Path(to_folder) / Path(blob_path).relative_to(\n                    full_container_path\n                )\n                local_path.parent.mkdir(parents=True, exist_ok=True)\n                async with container_client.get_blob_client(\n                    blob_path\n                ) as blob_client:\n                    blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                with local_path.open(mode=\"wb\") as to_file:\n                    await blob_obj.readinto(to_file)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return Path(to_folder)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the container to a file object.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <p>The path of the object to download within the container.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file object to download the object to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments for the download operation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, BinaryIO]</code> <p>The file object that the object was downloaded to.</p> Example <p>Download the object <code>object</code> from the container to a file object:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nwith open(\"file.txt\", \"wb\") as f:\n    block.download_object_to_file_object(\n        from_path=\"object\",\n        to_file_object=f\n    )\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, BinaryIO]:\n    \"\"\"\n    Downloads an object from the container to a file object.\n\n    Args:\n        from_path : The path of the object to download within the container.\n        to_file_object: The file object to download the object to.\n        **download_kwargs: Additional keyword arguments for the download\n            operation.\n\n    Returns:\n        The file object that the object was downloaded to.\n\n    Example:\n        Download the object `object` from the container to a file object:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        with open(\"file.txt\", \"wb\") as f:\n            block.download_object_to_file_object(\n                from_path=\"object\",\n                to_file_object=f\n            )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading object from container %s to file object\", self.container_name\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            blob_obj = await blob_client.download_blob(**download_kwargs)\n            await blob_obj.download_to_stream(to_file_object)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from a container to a specified path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path of the object in the container.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path where the object will be downloaded to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments for the download operation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, Path]</code> <p>The path where the object was downloaded to.</p> Example <p>Download the object <code>object</code> from the container to the local path     <code>file.txt</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.download_object_to_path(\n    from_path=\"object\",\n    to_path=\"file.txt\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Union[str, Path],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, Path]:\n    \"\"\"\n    Downloads an object from a container to a specified path.\n\n    Args:\n        from_path: The path of the object in the container.\n        to_path: The path where the object will be downloaded to.\n        **download_kwargs (Dict[str, Any]): Additional keyword arguments\n            for the download operation.\n\n    Returns:\n        The path where the object was downloaded to.\n\n    Example:\n        Download the object `object` from the container to the local path\n            `file.txt`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.download_object_to_path(\n            from_path=\"object\",\n            to_path=\"file.txt\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading object from container %s to path %s\",\n        self.container_name,\n        to_path,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            blob_obj = await blob_client.download_blob(**download_kwargs)\n\n            path = Path(to_path)\n\n            path.parent.mkdir(parents=True, exist_ok=True)\n\n            with path.open(mode=\"wb\") as to_file:\n                await blob_obj.readinto(to_file)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads the contents of a direry from the blob storage to a local path.</p> <p>Used to enable flow code storage for deployments.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path of the directory in the blob storage.</p> <code>None</code> <code>local_path</code> <code>str</code> <p>The local path where the directory will be downloaded.</p> <code>None</code> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: str = None, local_path: str = None\n) -&gt; None:\n    \"\"\"\n    Downloads the contents of a direry from the blob storage to a local path.\n\n    Used to enable flow code storage for deployments.\n\n    Args:\n        from_path: The path of the directory in the blob storage.\n        local_path: The local path where the directory will be downloaded.\n    \"\"\"\n    await self.download_folder_to_path(from_path, local_path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory to the blob storage.</p> <p>Used to enable flow code storage for deployments.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>str</code> <p>The local path of the directory to upload. Defaults to current directory.</p> <code>None</code> <code>to_path</code> <code>str</code> <p>The destination path in the blob storage. Defaults to root directory.</p> <code>None</code> <code>ignore_file</code> <code>str</code> <p>The path to a file containing patterns to ignore during upload.</p> <code>None</code> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self, local_path: str = None, to_path: str = None, ignore_file: str = None\n) -&gt; None:\n    \"\"\"\n    Uploads a directory to the blob storage.\n\n    Used to enable flow code storage for deployments.\n\n    Args:\n        local_path: The local path of the directory to upload. Defaults to\n            current directory.\n        to_path: The destination path in the blob storage. Defaults to\n            root directory.\n        ignore_file: The path to a file containing patterns to ignore\n            during upload.\n    \"\"\"\n    to_path = \"\" if to_path is None else to_path\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(local_path, ignore_patterns)\n\n    for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(to_path) / local_file_path.relative_to(\n                local_path\n            )\n            with open(local_file_path, \"rb\") as local_file:\n                local_file_content = local_file.read()\n\n            await self.write_path(\n                remote_file_path.as_posix(), content=local_file_content\n            )\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Reads the contents of a file at the specified path and returns it as bytes.</p> <p>Used to enable results storage.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path of the file to read.</p> required <p>Returns:</p> Type Description <code>bytes</code> <p>The contents of the file as bytes.</p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Reads the contents of a file at the specified path and returns it as bytes.\n\n    Used to enable results storage.\n\n    Args:\n        path: The path of the file to read.\n\n    Returns:\n        The contents of the file as bytes.\n    \"\"\"\n    file_obj = BytesIO()\n    await self.download_object_to_file_object(path, file_obj)\n    return file_obj.getvalue()\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object from a file object to the specified path in the blob     storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file object to upload.</p> required <code>to_path</code> <code>str</code> <p>The path in the blob storage container to upload the object to.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the upload_blob method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The path where the object was uploaded to.</p> Example <p>Upload a file object to the container at the path <code>object</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nwith open(\"file.txt\", \"rb\") as f:\n    block.upload_from_file_object(\n        from_file_object=f,\n        to_path=\"object\"\n    )\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads an object from a file object to the specified path in the blob\n        storage container.\n\n    Args:\n        from_file_object: The file object to upload.\n        to_path: The path in the blob storage container to upload the\n            object to.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            upload_blob method.\n\n    Returns:\n        The path where the object was uploaded to.\n\n    Example:\n        Upload a file object to the container at the path `object`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        with open(\"file.txt\", \"rb\") as f:\n            block.upload_from_file_object(\n                from_file_object=f,\n                to_path=\"object\"\n            )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading object to container %s with key %s\", self.container_name, to_path\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            await blob_client.upload_blob(from_file_object, **upload_kwargs)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to upload from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files from a local folder to a specified folder in the Azure     Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the local folder containing the files to upload.</p> required <code>to_folder</code> <code>str</code> <p>The destination folder in the Azure Blob Storage container.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>upload_blob</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The full path of the destination folder in the container.</p> Example <p>Upload the contents of the local folder <code>local_folder</code> to the container     folder <code>folder</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.upload_from_folder(\n    from_folder=\"local_folder\",\n    to_folder=\"folder\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: str,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads files from a local folder to a specified folder in the Azure\n        Blob Storage container.\n\n    Args:\n        from_folder: The path to the local folder containing the files to upload.\n        to_folder: The destination folder in the Azure Blob Storage container.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            `upload_blob` method.\n\n    Returns:\n        The full path of the destination folder in the container.\n\n    Example:\n        Upload the contents of the local folder `local_folder` to the container\n            folder `folder`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.upload_from_folder(\n            from_folder=\"local_folder\",\n            to_folder=\"folder\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading folder to container %s with key %s\",\n        self.container_name,\n        to_folder,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_folder)\n    async with self.credentials.get_container_client(\n        self.container_name\n    ) as container_client:\n        if not Path(from_folder).is_dir():\n            raise ValueError(f\"{from_folder} is not a directory\")\n        for path in Path(from_folder).rglob(\"*\"):\n            if path.is_file():\n                blob_path = Path(full_container_path) / path.relative_to(\n                    from_folder\n                )\n                async with container_client.get_blob_client(\n                    blob_path.as_posix()\n                ) as blob_client:\n                    try:\n                        await blob_client.upload_blob(\n                            path.read_bytes(), **upload_kwargs\n                        )\n                    except ResourceNotFoundError as exc:\n                        raise RuntimeError(\n                            \"An error occurred when attempting to upload to \"\n                            f\"container {self.container_name}: {exc.reason}\"\n                        ) from exc\n    return full_container_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a local path to the specified destination path in the     blob storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The local path of the object to upload.</p> required <code>to_path</code> <code>str</code> <p>The destination path in the blob storage container.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>upload_blob</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The destination path in the blob storage container.</p> Example <p>Upload a file from the local path <code>file.txt</code> to the container     at the path <code>object</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.upload_from_path(\n    from_path=\"file.txt\",\n    to_path=\"object\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self, from_path: Union[str, Path], to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads an object from a local path to the specified destination path in the\n        blob storage container.\n\n    Args:\n        from_path: The local path of the object to upload.\n        to_path: The destination path in the blob storage container.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            `upload_blob` method.\n\n    Returns:\n        The destination path in the blob storage container.\n\n    Example:\n        Upload a file from the local path `file.txt` to the container\n            at the path `object`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.upload_from_path(\n            from_path=\"file.txt\",\n            to_path=\"object\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading object to container %s with key %s\", self.container_name, to_path\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            with open(from_path, \"rb\") as f:\n                await blob_client.upload_blob(f, **upload_kwargs)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to upload to container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes the content to the specified path in the blob storage.</p> <p>Used to enable results storage.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path where the content will be written.</p> required <code>content</code> <code>bytes</code> <p>The content to be written.</p> required Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; None:\n    \"\"\"\n    Writes the content to the specified path in the blob storage.\n\n    Used to enable results storage.\n\n    Args:\n        path: The path where the content will be written.\n        content: The content to be written.\n    \"\"\"\n    await self.upload_from_file_object(BytesIO(content), path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_download","title":"<code>blob_storage_download</code>  <code>async</code>","text":"<p>Downloads a blob with a given key from a given Blob Storage container. Args:     blob: Name of the blob within this container to retrieve.     container: Name of the Blob Storage container to retrieve from.     blob_storage_credentials: Credentials to use for authentication with Azure. Returns:     A <code>bytes</code> representation of the downloaded blob. Example:     Download a file from a Blob Storage container     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef example_blob_storage_download_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    data = blob_storage_download(\n        container=\"prefect\",\n        blob=\"prefect.txt\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_download_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_download(\n    container: str,\n    blob: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n) -&gt; bytes:\n    \"\"\"\n    Downloads a blob with a given key from a given Blob Storage container.\n    Args:\n        blob: Name of the blob within this container to retrieve.\n        container: Name of the Blob Storage container to retrieve from.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n    Returns:\n        A `bytes` representation of the downloaded blob.\n    Example:\n        Download a file from a Blob Storage container\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_download\n\n        @flow\n        def example_blob_storage_download_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            data = blob_storage_download(\n                container=\"prefect\",\n                blob=\"prefect.txt\",\n                blob_storage_credentials=blob_storage_credentials,\n            )\n            return data\n\n        example_blob_storage_download_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading blob from container %s with key %s\", container, blob)\n\n    async with blob_storage_credentials.get_blob_client(container, blob) as blob_client:\n        blob_obj = await blob_client.download_blob()\n        output = await blob_obj.content_as_bytes()\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_list","title":"<code>blob_storage_list</code>  <code>async</code>","text":"<p>List objects from a given Blob Storage container. Args:     container: Name of the Blob Storage container to retrieve from.     blob_storage_credentials: Credentials to use for authentication with Azure.     name_starts_with: Filters the results to return only blobs whose names         begin with the specified prefix.     include: Specifies one or more additional datasets to include in the response.         Options include: 'snapshots', 'metadata', 'uncommittedblobs', 'copy',         'deleted', 'deletedwithversions', 'tags', 'versions', 'immutabilitypolicy',         'legalhold'.     **kwargs: Additional kwargs passed to <code>ContainerClient.list_blobs()</code> Returns:     A <code>list</code> of <code>dict</code>s containing metadata about the blob. Example:     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_list\n\n@flow\ndef example_blob_storage_list_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=\"connection_string\",\n    )\n    data = blob_storage_list(\n        container=\"container\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_list_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_list(\n    container: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    name_starts_with: str = None,\n    include: Union[str, List[str]] = None,\n    **kwargs,\n) -&gt; List[\"BlobProperties\"]:\n    \"\"\"\n    List objects from a given Blob Storage container.\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n        name_starts_with: Filters the results to return only blobs whose names\n            begin with the specified prefix.\n        include: Specifies one or more additional datasets to include in the response.\n            Options include: 'snapshots', 'metadata', 'uncommittedblobs', 'copy',\n            'deleted', 'deletedwithversions', 'tags', 'versions', 'immutabilitypolicy',\n            'legalhold'.\n        **kwargs: Additional kwargs passed to `ContainerClient.list_blobs()`\n    Returns:\n        A `list` of `dict`s containing metadata about the blob.\n    Example:\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_list\n\n        @flow\n        def example_blob_storage_list_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            data = blob_storage_list(\n                container=\"container\",\n                blob_storage_credentials=blob_storage_credentials,\n            )\n            return data\n\n        example_blob_storage_list_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Listing blobs from container %s\", container)\n\n    async with blob_storage_credentials.get_container_client(\n        container\n    ) as container_client:\n        blobs = [\n            blob\n            async for blob in container_client.list_blobs(\n                name_starts_with=name_starts_with, include=include, **kwargs\n            )\n        ]\n\n    return blobs\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_upload","title":"<code>blob_storage_upload</code>  <code>async</code>","text":"<p>Uploads data to an Blob Storage container. Args:     data: Bytes representation of data to upload to Blob Storage.     container: Name of the Blob Storage container to upload to.     blob_storage_credentials: Credentials to use for authentication with Azure.     blob: Name of the blob within this container to retrieve.     overwrite: If <code>True</code>, an existing blob with the same name will be overwritten.         Defaults to <code>False</code> and an error will be thrown if the blob already exists. Returns:     The blob name of the uploaded object Example:     Read and upload a file to a Blob Storage container     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_upload\n\n@flow\ndef example_blob_storage_upload_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    with open(\"data.csv\", \"rb\") as f:\n        blob = blob_storage_upload(\n            data=f.read(),\n            container=\"container\",\n            blob=\"data.csv\",\n            blob_storage_credentials=blob_storage_credentials,\n            overwrite=False,\n        )\n    return blob\n\nexample_blob_storage_upload_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_upload(\n    data: bytes,\n    container: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    blob: str = None,\n    overwrite: bool = False,\n) -&gt; str:\n    \"\"\"\n    Uploads data to an Blob Storage container.\n    Args:\n        data: Bytes representation of data to upload to Blob Storage.\n        container: Name of the Blob Storage container to upload to.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n        blob: Name of the blob within this container to retrieve.\n        overwrite: If `True`, an existing blob with the same name will be overwritten.\n            Defaults to `False` and an error will be thrown if the blob already exists.\n    Returns:\n        The blob name of the uploaded object\n    Example:\n        Read and upload a file to a Blob Storage container\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_upload\n\n        @flow\n        def example_blob_storage_upload_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            with open(\"data.csv\", \"rb\") as f:\n                blob = blob_storage_upload(\n                    data=f.read(),\n                    container=\"container\",\n                    blob=\"data.csv\",\n                    blob_storage_credentials=blob_storage_credentials,\n                    overwrite=False,\n                )\n            return blob\n\n        example_blob_storage_upload_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob to container %s with key %s\", container, blob)\n\n    # create key if not provided\n    if blob is None:\n        blob = str(uuid.uuid4())\n\n    async with blob_storage_credentials.get_blob_client(container, blob) as blob_client:\n        await blob_client.upload_blob(data, overwrite=overwrite)\n\n    return blob\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/","title":"Container Instance Block","text":""},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance","title":"<code>prefect_azure.container_instance</code>","text":"<p>Integrations with the Azure Container Instances service. Note this module is experimental. The interfaces within may change without notice.</p> <p>The <code>AzureContainerInstanceJob</code> infrastructure block in this module is ideally configured via the Prefect UI and run via a Prefect agent, but it can be called directly as demonstrated in the following examples.</p> <p>Examples:</p> <p>Run a command using an Azure Container Instances container. <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"]).run()\n</code></pre></p> <p>Run a command and stream the container's output to the local terminal. <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello world\"],\n    stream_output=True,\n)\n</code></pre></p> <p>Run a command with a specific image <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], image=\"alpine:latest\")\n</code></pre></p> <p>Run a task with custom memory and CPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0)\n</code></pre></p> <p>Run a task with custom memory and CPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0)\n</code></pre></p> <p>Run a task with custom memory, CPU, and GPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0,\ngpu_count=1, gpu_sku=\"V100\")\n</code></pre></p> <p>Run a task with custom environment variables <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello $PLANET\"],\n    env={\"PLANET\": \"earth\"}\n)\n</code></pre></p> <p>Run a task that uses a private ACR registry with a managed identity <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello $PLANET\"],\n    image=\"my-registry.azurecr.io/my-image\",\n    image_registry=ACRManagedIdentity(\n        registry_url=\"my-registry.azurecr.io\",\n        identity=\"/my/managed/identity/123abc\"\n    )\n)\n</code></pre></p>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ACRManagedIdentity","title":"<code>ACRManagedIdentity</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Use a Managed Identity to access Azure Container registry. Requires the user-assigned managed identity be available to the ACI container group.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ACRManagedIdentity(BaseModel):\n    \"\"\"\n    Use a Managed Identity to access Azure Container registry. Requires the\n    user-assigned managed identity be available to the ACI container group.\n    \"\"\"\n\n    registry_url: str = Field(\n        default=...,\n        title=\"Registry URL\",\n        description=(\n            \"The URL to the registry, such as myregistry.azurecr.io. Generally, 'http' \"\n            \"or 'https' can be omitted.\"\n        ),\n    )\n    identity: str = Field(\n        default=...,\n        description=(\n            \"The user-assigned Azure managed identity for the private registry.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob","title":"<code>AzureContainerInstanceJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Run a command using a container on Azure Container Instances. Note this block is experimental. The interface may change without notice.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the AzureContainerWorker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass AzureContainerInstanceJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Run a command using a container on Azure Container Instances.\n    Note this block is experimental. The interface may change without notice.\n    \"\"\"\n\n    _block_type_name = \"Azure Container Instance Job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob\"  # noqa\n\n    type: Literal[\"container-instance-job\"] = Field(\n        default=\"container-instance-job\", description=\"The slug for this task type.\"\n    )\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        default_factory=AzureContainerInstanceCredentials,\n        description=(\n            \"Credentials for Azure Container Instances; \"\n            \"if not provided will attempt to use DefaultAzureCredentials.\"\n        ),\n    )\n    resource_group_name: str = Field(\n        default=...,\n        title=\"Azure Resource Group Name\",\n        description=(\n            \"The name of the Azure Resource Group in which to run Prefect ACI tasks.\"\n        ),\n    )\n    subscription_id: SecretStr = Field(\n        default=...,\n        title=\"Azure Subscription ID\",\n        description=\"The ID of the Azure subscription to create containers under.\",\n    )\n    identities: Optional[List[str]] = Field(\n        title=\"Identities\",\n        default=None,\n        description=(\n            \"A list of user-assigned identities to associate with the container group. \"\n            \"The identities should be an ARM resource IDs in the form: \"\n            \"'/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.\"  # noqa\n        ),\n    )\n    image: Optional[str] = Field(\n        default_factory=get_prefect_image_name,\n        description=(\n            \"The image to use for the Prefect container in the task. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=DEFAULT_CONTAINER_ENTRYPOINT,\n        description=(\n            \"The entrypoint of the container you wish you run. This value \"\n            \"defaults to the entrypoint used by Prefect images and should only be \"\n            \"changed when using a custom image that is not based on an official \"\n            \"Prefect image. Any commands set on deployments will be passed \"\n            \"to the entrypoint as parameters.\"\n        ),\n    )\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(\n        default=None,\n        title=\"Image Registry (Optional)\",\n        description=(\n            \"To use any private container registry with a username and password, \"\n            \"choose DockerRegistry. To use a private Azure Container Registry \"\n            \"with a managed identity, choose ACRManagedIdentity.\"\n        ),\n    )\n    cpu: float = Field(\n        title=\"CPU\",\n        default=ACI_DEFAULT_CPU,\n        description=(\n            \"The number of virtual CPUs to assign to the task container. \"\n            f\"If not provided, a default value of {ACI_DEFAULT_CPU} will be used.\"\n        ),\n    )\n    gpu_count: Optional[int] = Field(\n        title=\"GPU Count\",\n        default=None,\n        description=(\n            \"The number of GPUs to assign to the task container. \"\n            \"If not provided, no GPU will be used.\"\n        ),\n    )\n    gpu_sku: Optional[str] = Field(\n        title=\"GPU SKU\",\n        default=None,\n        description=(\n            \"The Azure GPU SKU to use. See the ACI documentation for a list of \"\n            \"GPU SKUs available in each Azure region.\"\n        ),\n    )\n    memory: float = Field(\n        default=ACI_DEFAULT_MEMORY,\n        description=(\n            \"The amount of memory in gigabytes to provide to the ACI task. Valid \"\n            \"amounts are specified in the Azure documentation. If not provided, a \"\n            f\"default value of  {ACI_DEFAULT_MEMORY} will be used unless present \"\n            \"on the task definition.\"\n        ),\n    )\n    subnet_ids: Optional[List[str]] = Field(\n        default=None,\n        title=\"Subnet IDs\",\n        description=\"A list of Azure subnet IDs the container should be connected to.\",\n    )\n    dns_servers: Optional[List[str]] = Field(\n        default=None,\n        title=\"DNS Servers\",\n        description=\"A list of custom DNS Servers the container should use.\",\n    )\n    stream_output: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=240,\n        description=(\n            \"The amount of time to watch for the start of the ACI container. \"\n            \"before marking it as failed.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The number of seconds to wait between Azure API calls while monitoring \"\n            \"the state of an Azure Container Instances task.\"\n        ),\n    )\n\n    @sync_compatible\n    async def run(\n        self, task_status: Optional[TaskStatus] = None\n    ) -&gt; AzureContainerInstanceJobResult:\n        \"\"\"\n        Runs the configured task using an ACI container.\n\n        Args:\n            task_status: An optional `TaskStatus` to update when the container starts.\n\n        Returns:\n            An `AzureContainerInstanceJobResult` with the container's exit code.\n        \"\"\"\n\n        run_start_time = datetime.datetime.now(datetime.timezone.utc)\n\n        container = self._configure_container()\n        container_group = self._configure_container_group(container)\n        created_container_group = None\n\n        aci_client = self.aci_credentials.get_container_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        self.logger.info(\n            f\"{self._log_prefix}: Preparing to run command {' '.join(self.command)!r} \"\n            f\"in container {container.name!r} ({self.image})...\"\n        )\n        try:\n            self.logger.info(f\"{self._log_prefix}: Waiting for container creation...\")\n            # Create the container group and wait for it to start\n            creation_status_poller = await run_sync_in_worker_thread(\n                aci_client.container_groups.begin_create_or_update,\n                self.resource_group_name,\n                container.name,\n                container_group,\n            )\n            created_container_group = await run_sync_in_worker_thread(\n                self._wait_for_task_container_start, creation_status_poller\n            )\n\n            # If creation succeeded, group provisioning state should be 'Succeeded'\n            # and the group should have a single container\n            if self._provisioning_succeeded(created_container_group):\n                self.logger.info(f\"{self._log_prefix}: Running command...\")\n                if task_status:\n                    task_status.started(value=created_container_group.name)\n                status_code = await run_sync_in_worker_thread(\n                    self._watch_task_and_get_exit_code,\n                    aci_client,\n                    created_container_group,\n                    run_start_time,\n                )\n                self.logger.info(f\"{self._log_prefix}: Completed command run.\")\n            else:\n                raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n        finally:\n            if created_container_group:\n                await self._wait_for_container_group_deletion(\n                    aci_client, created_container_group\n                )\n\n        return AzureContainerInstanceJobResult(\n            identifier=created_container_group.name, status_code=status_code\n        )\n\n    async def kill(\n        self,\n        container_group_name: str,\n        grace_seconds: int = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS,\n    ):\n        \"\"\"\n        Kill a flow running in an ACI container group.\n\n        Args:\n            container_group_name: The container group name yielded by\n                `AzureContainerInstanceJob.run`.\n        \"\"\"\n        # ACI does not provide a way to specify grace period, but it gives\n        # applications ~30 seconds to gracefully terminate before killing\n        # a container group.\n        if grace_seconds != CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS:\n            self.logger.warning(\n                f\"{self._log_prefix}: Kill grace period of {grace_seconds}s requested, \"\n                f\"but ACI does not support grace period configuration.\"\n            )\n\n        aci_client = self.aci_credentials.get_container_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        # get the container group to check that it still exists\n        try:\n            container_group = aci_client.container_groups.get(\n                resource_group_name=self.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        except ResourceNotFoundError as exc:\n            # the container group no longer exists, so there's nothing to cancel\n            raise InfrastructureNotFound(\n                f\"Cannot stop ACI job: container group {container_group_name} \"\n                \"no longer exists.\"\n            ) from exc\n\n        # get the container state to check if the container has terminated\n        container = self._get_container(container_group)\n        container_state = container.instance_view.current_state.state\n\n        # the container group needs to be deleted regardless of whether the container\n        # already terminated\n        await self._wait_for_container_group_deletion(aci_client, container_group)\n\n        # if the container had already terminated, raise an exception to let the agent\n        # know the flow was not cancelled\n        if container_state == ContainerRunState.TERMINATED:\n            raise InfrastructureNotAvailable(\n                f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n                f\"but container {container.name} has already terminated.\"\n            )\n\n    def preview(self) -&gt; str:\n        \"\"\"\n        Provides a summary of how the container will be created when `run` is called.\n\n        Returns:\n           A string containing the summary.\n        \"\"\"\n        preview = {\n            \"container_name\": \"&lt;generated when run&gt;\",\n            \"resource_group_name\": self.resource_group_name,\n            \"memory\": self.memory,\n            \"cpu\": self.cpu,\n            \"gpu_count\": self.gpu_count,\n            \"gpu_sku\": self.gpu_sku,\n            \"env\": self._get_environment(),\n        }\n\n        return json.dumps(preview)\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        from prefect_azure.workers.container_instance import AzureContainerWorker\n\n        return AzureContainerWorker.type\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for an `Azure Container Instance` work pool\n        with the same configuration as this block.\n\n        Returns:\n            - dict: a base job template for an `Azure Container Instance` work pool\n        \"\"\"\n        from prefect_azure.workers.container_instance import AzureContainerWorker\n\n        base_job_template = deepcopy(\n            AzureContainerWorker.get_default_base_job_template()\n        )\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"subscription_id\":\n                base_job_template[\"variables\"][\"properties\"][\"subscription_id\"][\n                    \"default\"\n                ] = value.get_secret_value()\n            elif key == \"aci_credentials\":\n                if not self.aci_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"aci_credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.aci_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"image_registry\":\n                if not self.image_registry._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"image_registry\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.image_registry._block_document_id)\n                    }\n                }\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by `Azure Container Instance`\"\n                    \" work pools. Skipping.\"\n                )\n\n        return base_job_template\n\n    def _configure_container(self) -&gt; Container:\n        \"\"\"\n        Configures an Azure `Container` using data from the block's fields.\n\n        Returns:\n            An instance of `Container` ready to submit to Azure.\n        \"\"\"\n\n        # setup container environment variables\n        environment = [\n            EnvironmentVariable(name=k, secure_value=v)\n            if k in ENV_SECRETS\n            else EnvironmentVariable(name=k, value=v)\n            for (k, v) in self._get_environment().items()\n        ]\n\n        # all container names in a resource group must be unique\n        if self.name:\n            slugified_name = slugify(\n                self.name,\n                max_length=52,\n                regex_pattern=r\"[^a-zA-Z0-9-]+\",\n            )\n            random_suffix = \"\".join(\n                random.choices(string.ascii_lowercase + string.digits, k=10)\n            )\n            container_name = slugified_name + \"-\" + random_suffix\n        else:\n            container_name = str(uuid.uuid4())\n\n        container_resource_requirements = self._configure_container_resources()\n\n        # add the entrypoint if provided, because creating an ACI container with a\n        # command overrides the container's built-in entrypoint.\n        if self.entrypoint:\n            self.command.insert(0, self.entrypoint)\n\n        return Container(\n            name=container_name,\n            image=self.image,\n            command=self.command,\n            resources=container_resource_requirements,\n            environment_variables=environment,\n        )\n\n    def _configure_container_resources(self) -&gt; ResourceRequirements:\n        \"\"\"\n        Configures the container's memory, CPU, and GPU resources.\n\n        Returns:\n            A `ResourceRequirements` instance initialized with data from this\n            `AzureContainerInstanceJob` block.\n        \"\"\"\n\n        gpu_resource = (\n            GpuResource(count=self.gpu_count, sku=self.gpu_sku)\n            if self.gpu_count and self.gpu_sku\n            else None\n        )\n        container_resource_requests = ResourceRequests(\n            memory_in_gb=self.memory, cpu=self.cpu, gpu=gpu_resource\n        )\n\n        return ResourceRequirements(requests=container_resource_requests)\n\n    def _configure_container_group(self, container: Container) -&gt; ContainerGroup:\n        \"\"\"\n        Configures the container group needed to start a container on ACI.\n\n        Args:\n            container: An initialized instance of `Container`.\n\n        Returns:\n            An initialized `ContainerGroup` ready to submit to Azure.\n        \"\"\"\n\n        # Load the resource group, so we can set the container group location\n        # correctly.\n\n        resource_group_client = self.aci_credentials.get_resource_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        resource_group = resource_group_client.resource_groups.get(\n            self.resource_group_name\n        )\n\n        image_registry_credentials = self._create_image_registry_credentials(\n            self.image_registry\n        )\n\n        identity = (\n            ContainerGroupIdentity(\n                type=\"UserAssigned\",\n                # The Azure API only uses the dict keys and ignores values when\n                # creating a container group. Using empty `UserAssignedIdentities`\n                # instances as dict values satisfies Python type checkers.\n                user_assigned_identities={\n                    identity: UserAssignedIdentities() for identity in self.identities\n                },\n            )\n            if self.identities\n            else None\n        )\n\n        subnet_ids = (\n            [ContainerGroupSubnetId(id=subnet_id) for subnet_id in self.subnet_ids]\n            if self.subnet_ids\n            else None\n        )\n\n        dns_config = (\n            DnsConfiguration(name_servers=self.dns_servers)\n            if self.dns_servers\n            else None\n        )\n\n        return ContainerGroup(\n            location=resource_group.location,\n            identity=identity,\n            containers=[container],\n            os_type=OperatingSystemTypes.linux,\n            restart_policy=ContainerGroupRestartPolicy.never,\n            image_registry_credentials=image_registry_credentials,\n            subnet_ids=subnet_ids,\n            dns_config=dns_config,\n        )\n\n    @staticmethod\n    def _create_image_registry_credentials(\n        image_registry: Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n            None,\n        ],\n    ):\n        \"\"\"\n        Create image registry credentials based on the type of image_registry provided.\n\n        Args:\n            image_registry: An instance of a DockerRegistry or\n            ACRManagedIdentity object.\n\n        Returns:\n            A list containing an ImageRegistryCredential object if the input is a\n            `DockerRegistry` or `ACRManagedIdentity`, or None if the\n            input doesn't match any of the expected types.\n        \"\"\"\n        if image_registry and isinstance(\n            image_registry, prefect.infrastructure.container.DockerRegistry\n        ):\n            return [\n                ImageRegistryCredential(\n                    server=image_registry.registry_url,\n                    username=image_registry.username,\n                    password=image_registry.password.get_secret_value(),\n                )\n            ]\n        elif image_registry and isinstance(image_registry, ACRManagedIdentity):\n            return [\n                ImageRegistryCredential(\n                    server=image_registry.registry_url,\n                    identity=image_registry.identity,\n                )\n            ]\n        else:\n            return None\n\n    def _wait_for_task_container_start(\n        self, creation_status_poller: LROPoller[ContainerGroup]\n    ) -&gt; ContainerGroup:\n        \"\"\"\n        Wait for the result of group and container creation.\n\n        Args:\n            creation_status_poller: Poller returned by the Azure SDK.\n\n        Raises:\n            RuntimeError: Raised if the timeout limit is exceeded before the\n            container starts.\n\n        Returns:\n            A `ContainerGroup` representing the current status of the group being\n            watched.\n        \"\"\"\n\n        t0 = time.time()\n        timeout = self.task_start_timeout_seconds\n\n        while not creation_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while watching waiting for \"\n                        \"container start.\"\n                    )\n                )\n            time.sleep(self.task_watch_poll_interval)\n\n        return creation_status_poller.result()\n\n    def _watch_task_and_get_exit_code(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        run_start_time: datetime.datetime,\n    ) -&gt; int:\n        \"\"\"\n        Waits until the container finishes running and obtains its exit code.\n\n        Args:\n            client: An initialized Azure `ContainerInstanceManagementClient`\n            container_group: The `ContainerGroup` in which the container resides.\n\n        Returns:\n            An `int` representing the container's exit code.\n        \"\"\"\n\n        status_code = -1\n        running_container = self._get_container(container_group)\n        current_state = running_container.instance_view.current_state.state\n\n        # get any logs the container has already generated\n        last_log_time = run_start_time\n        if self.stream_output:\n            last_log_time = self._get_and_stream_output(\n                client, container_group, last_log_time\n            )\n\n        # set exit code if flow run already finished:\n        if current_state == ContainerRunState.TERMINATED:\n            status_code = running_container.instance_view.current_state.exit_code\n\n        while current_state != ContainerRunState.TERMINATED:\n            try:\n                container_group = client.container_groups.get(\n                    resource_group_name=self.resource_group_name,\n                    container_group_name=container_group.name,\n                )\n            except ResourceNotFoundError:\n                self.logger.exception(\n                    f\"{self._log_prefix}: Container group was deleted before flow run \"\n                    \"completed, likely due to flow cancellation.\"\n                )\n\n                # since the flow was cancelled, exit early instead of raising an\n                # exception\n                return status_code\n\n            container = self._get_container(container_group)\n            current_state = container.instance_view.current_state.state\n\n            if current_state == ContainerRunState.TERMINATED:\n                status_code = container.instance_view.current_state.exit_code\n                # break instead of waiting for next loop iteration because\n                # trying to read logs from a terminated container raises an exception\n                break\n\n            if self.stream_output:\n                last_log_time = self._get_and_stream_output(\n                    client, container_group, last_log_time\n                )\n\n            time.sleep(self.task_watch_poll_interval)\n\n        return status_code\n\n    async def _wait_for_container_group_deletion(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n    ):\n        self.logger.info(f\"{self._log_prefix}: Deleting container...\")\n\n        deletion_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_delete,\n            resource_group_name=self.resource_group_name,\n            container_group_name=container_group.name,\n        )\n\n        t0 = time.time()\n        timeout = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS\n\n        while not deletion_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while waiting for deletion of\"\n                        f\" container group {container_group.name}. To verify the group \"\n                        \"has been deleted, check the Azure Portal or run \"\n                        f\"az container show --name {container_group.name} --resource-group {self.resource_group_name}\"  # noqa\n                    )\n                )\n            await anyio.sleep(self.task_watch_poll_interval)\n\n        self.logger.info(f\"{self._log_prefix}: Container deleted.\")\n\n    def _get_container(self, container_group: ContainerGroup) -&gt; Container:\n        \"\"\"\n        Extracts the job container from a container group.\n        \"\"\"\n        return container_group.containers[0]\n\n    def _get_and_stream_output(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        last_log_time: datetime.datetime,\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Fetches logs output from the job container and writes all entries after\n        a given time to stderr.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        logs = self._get_logs(client, container_group)\n        return self._stream_output(logs, last_log_time)\n\n    def _get_logs(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        max_lines: int = 100,\n    ) -&gt; str:\n        \"\"\"\n        Gets the most container logs up to a given maximum.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            max_lines: The number of log lines to pull. Defaults to 100.\n\n        Returns:\n            A string containing the requested log entries, one per line.\n        \"\"\"\n        container = self._get_container(container_group)\n\n        logs: Union[Logs, None] = None\n        try:\n            logs = client.containers.list_logs(\n                resource_group_name=self.resource_group_name,\n                container_group_name=container_group.name,\n                container_name=container.name,\n                tail=max_lines,\n                timestamps=True,\n            )\n        except HttpResponseError:\n            # Trying to get logs when the container is under heavy CPU load sometimes\n            # results in an error, but we won't want to raise an exception and stop\n            # monitoring the flow. Instead, log the error and carry on so we can try to\n            # get all missed logs on the next check.\n            self.logger.warning(\n                f\"{self._log_prefix}: Unable to retrieve logs from container \"\n                f\"{container.name}. Trying again in {self.task_watch_poll_interval}s\"\n            )\n\n        return logs.content if logs else \"\"\n\n    def _stream_output(\n        self, log_content: Union[str, None], last_log_time: datetime.datetime\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Writes each entry from a string of log lines to stderr.\n\n        Args:\n            log_content: A string containing Azure container logs.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        if not log_content:\n            # nothing to stream\n            return last_log_time\n\n        log_lines = log_content.split(\"\\n\")\n\n        last_written_time = last_log_time\n\n        for log_line in log_lines:\n            # skip if the line is blank or whitespace\n            if not log_line.strip():\n                continue\n\n            line_parts = log_line.split(\" \")\n            # timestamp should always be before first space in line\n            line_timestamp = line_parts[0]\n            line = \" \".join(line_parts[1:])\n\n            try:\n                line_time = dateutil.parser.parse(line_timestamp)\n                if line_time &gt; last_written_time:\n                    self._write_output_line(line)\n                    last_written_time = line_time\n            except dateutil.parser.ParserError as e:\n                self.logger.debug(\n                    (\n                        f\"{self._log_prefix}: Unable to parse timestamp from Azure \"\n                        \"log line: %s\"\n                    ),\n                    log_line,\n                    exc_info=e,\n                )\n\n        return last_written_time\n\n    def _get_environment(self):\n        \"\"\"\n        Generates a dictionary of all environment variables to send to the\n        ACI container.\n        \"\"\"\n        return {**self._base_environment(), **self.env}\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"AzureContainerInstanceJob {self.name!r}\"\n        else:\n            return \"AzureContainerInstanceJob\"\n\n    @staticmethod\n    def _provisioning_succeeded(container_group: ContainerGroup) -&gt; bool:\n        \"\"\"\n        Determines whether ACI container group provisioning was successful.\n\n        Args:\n            container_group: a container group returned by the Azure SDK.\n\n        Returns:\n            True if provisioning was successful, False otherwise.\n        \"\"\"\n        if not container_group:\n            return False\n\n        return (\n            container_group.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n            and len(container_group.containers) == 1\n        )\n\n    @staticmethod\n    def _write_output_line(line: str):\n        \"\"\"\n        Writes a line of output to stderr.\n        \"\"\"\n        print(line, file=sys.stderr)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for an <code>Azure Container Instance</code> work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for an <code>Azure Container Instance</code> work pool</li> </ul> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for an `Azure Container Instance` work pool\n    with the same configuration as this block.\n\n    Returns:\n        - dict: a base job template for an `Azure Container Instance` work pool\n    \"\"\"\n    from prefect_azure.workers.container_instance import AzureContainerWorker\n\n    base_job_template = deepcopy(\n        AzureContainerWorker.get_default_base_job_template()\n    )\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n        ]:\n            continue\n        elif key == \"subscription_id\":\n            base_job_template[\"variables\"][\"properties\"][\"subscription_id\"][\n                \"default\"\n            ] = value.get_secret_value()\n        elif key == \"aci_credentials\":\n            if not self.aci_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"aci_credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.aci_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"image_registry\":\n            if not self.image_registry._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"image_registry\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(self.image_registry._block_document_id)\n                }\n            }\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by `Azure Container Instance`\"\n                \" work pools. Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    from prefect_azure.workers.container_instance import AzureContainerWorker\n\n    return AzureContainerWorker.type\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a flow running in an ACI container group.</p> <p>Parameters:</p> Name Type Description Default <code>container_group_name</code> <code>str</code> <p>The container group name yielded by <code>AzureContainerInstanceJob.run</code>.</p> required Source code in <code>prefect_azure/container_instance.py</code> <pre><code>async def kill(\n    self,\n    container_group_name: str,\n    grace_seconds: int = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS,\n):\n    \"\"\"\n    Kill a flow running in an ACI container group.\n\n    Args:\n        container_group_name: The container group name yielded by\n            `AzureContainerInstanceJob.run`.\n    \"\"\"\n    # ACI does not provide a way to specify grace period, but it gives\n    # applications ~30 seconds to gracefully terminate before killing\n    # a container group.\n    if grace_seconds != CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS:\n        self.logger.warning(\n            f\"{self._log_prefix}: Kill grace period of {grace_seconds}s requested, \"\n            f\"but ACI does not support grace period configuration.\"\n        )\n\n    aci_client = self.aci_credentials.get_container_client(\n        self.subscription_id.get_secret_value()\n    )\n\n    # get the container group to check that it still exists\n    try:\n        container_group = aci_client.container_groups.get(\n            resource_group_name=self.resource_group_name,\n            container_group_name=container_group_name,\n        )\n    except ResourceNotFoundError as exc:\n        # the container group no longer exists, so there's nothing to cancel\n        raise InfrastructureNotFound(\n            f\"Cannot stop ACI job: container group {container_group_name} \"\n            \"no longer exists.\"\n        ) from exc\n\n    # get the container state to check if the container has terminated\n    container = self._get_container(container_group)\n    container_state = container.instance_view.current_state.state\n\n    # the container group needs to be deleted regardless of whether the container\n    # already terminated\n    await self._wait_for_container_group_deletion(aci_client, container_group)\n\n    # if the container had already terminated, raise an exception to let the agent\n    # know the flow was not cancelled\n    if container_state == ContainerRunState.TERMINATED:\n        raise InfrastructureNotAvailable(\n            f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n            f\"but container {container.name} has already terminated.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.preview","title":"<code>preview</code>","text":"<p>Provides a summary of how the container will be created when <code>run</code> is called.</p> <p>Returns:</p> Type Description <code>str</code> <p>A string containing the summary.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"\n    Provides a summary of how the container will be created when `run` is called.\n\n    Returns:\n       A string containing the summary.\n    \"\"\"\n    preview = {\n        \"container_name\": \"&lt;generated when run&gt;\",\n        \"resource_group_name\": self.resource_group_name,\n        \"memory\": self.memory,\n        \"cpu\": self.cpu,\n        \"gpu_count\": self.gpu_count,\n        \"gpu_sku\": self.gpu_sku,\n        \"env\": self._get_environment(),\n    }\n\n    return json.dumps(preview)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs the configured task using an ACI container.</p> <p>Parameters:</p> Name Type Description Default <code>task_status</code> <code>Optional[TaskStatus]</code> <p>An optional <code>TaskStatus</code> to update when the container starts.</p> <code>None</code> <p>Returns:</p> Type Description <code>AzureContainerInstanceJobResult</code> <p>An <code>AzureContainerInstanceJobResult</code> with the container's exit code.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>@sync_compatible\nasync def run(\n    self, task_status: Optional[TaskStatus] = None\n) -&gt; AzureContainerInstanceJobResult:\n    \"\"\"\n    Runs the configured task using an ACI container.\n\n    Args:\n        task_status: An optional `TaskStatus` to update when the container starts.\n\n    Returns:\n        An `AzureContainerInstanceJobResult` with the container's exit code.\n    \"\"\"\n\n    run_start_time = datetime.datetime.now(datetime.timezone.utc)\n\n    container = self._configure_container()\n    container_group = self._configure_container_group(container)\n    created_container_group = None\n\n    aci_client = self.aci_credentials.get_container_client(\n        self.subscription_id.get_secret_value()\n    )\n\n    self.logger.info(\n        f\"{self._log_prefix}: Preparing to run command {' '.join(self.command)!r} \"\n        f\"in container {container.name!r} ({self.image})...\"\n    )\n    try:\n        self.logger.info(f\"{self._log_prefix}: Waiting for container creation...\")\n        # Create the container group and wait for it to start\n        creation_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_create_or_update,\n            self.resource_group_name,\n            container.name,\n            container_group,\n        )\n        created_container_group = await run_sync_in_worker_thread(\n            self._wait_for_task_container_start, creation_status_poller\n        )\n\n        # If creation succeeded, group provisioning state should be 'Succeeded'\n        # and the group should have a single container\n        if self._provisioning_succeeded(created_container_group):\n            self.logger.info(f\"{self._log_prefix}: Running command...\")\n            if task_status:\n                task_status.started(value=created_container_group.name)\n            status_code = await run_sync_in_worker_thread(\n                self._watch_task_and_get_exit_code,\n                aci_client,\n                created_container_group,\n                run_start_time,\n            )\n            self.logger.info(f\"{self._log_prefix}: Completed command run.\")\n        else:\n            raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n    finally:\n        if created_container_group:\n            await self._wait_for_container_group_deletion(\n                aci_client, created_container_group\n            )\n\n    return AzureContainerInstanceJobResult(\n        identifier=created_container_group.name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJobResult","title":"<code>AzureContainerInstanceJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>The result of an <code>AzureContainerInstanceJob</code> run.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class AzureContainerInstanceJobResult(InfrastructureResult):\n    \"\"\"\n    The result of an `AzureContainerInstanceJob` run.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ContainerGroupProvisioningState","title":"<code>ContainerGroupProvisioningState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal provisioning states for ACI container groups. Per the Azure docs, the states in this Enum are the only ones that can be relied on as dependencies.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ContainerGroupProvisioningState(str, Enum):\n    \"\"\"\n    Terminal provisioning states for ACI container groups. Per the Azure docs,\n    the states in this Enum are the only ones that can be relied on as dependencies.\n    \"\"\"\n\n    SUCCEEDED = \"Succeeded\"\n    FAILED = \"Failed\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ContainerRunState","title":"<code>ContainerRunState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal run states for ACI containers.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ContainerRunState(str, Enum):\n    \"\"\"\n    Terminal run states for ACI containers.\n    \"\"\"\n\n    RUNNING = \"Running\"\n    TERMINATED = \"Terminated\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/","title":"Container Instance Worker","text":""},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance","title":"<code>prefect_azure.workers.container_instance</code>","text":"<p>Module containing the Azure Container Instances worker used for executing flow runs in ACI containers.</p> <p>To start an ACI worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type azure-container-instance\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>Using a custom ARM template</p> <p>To facilitate easy customization, the Azure Container worker provisions a containing group using an ARM template. The default ARM template is represented in YAML as follows: <pre><code>---\narm_template:\n  \"$schema\": https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#\n  contentVersion: 1.0.0.0\n  parameters:\n    location:\n      type: string\n      defaultValue: \"[resourceGroup().location]\"\n      metadata:\n        description: Location for all resources.\n    container_group_name:\n      type: string\n      defaultValue: \"[uniqueString(resourceGroup().id)]\"\n      metadata:\n        description: The name of the container group to create.\n    container_name:\n      type: string\n      defaultValue: \"[uniqueString(resourceGroup().id)]\"\n      metadata:\n        description: The name of the container to create.\n  resources:\n  - type: Microsoft.ContainerInstance/containerGroups\n    apiVersion: '2022-09-01'\n    name: \"[parameters('container_group_name')]\"\n    location: \"[parameters('location')]\"\n    properties:\n      containers:\n      - name: \"[parameters('container_name')]\"\n        properties:\n          image: rpeden/my-aci-flow:latest\n          command: \"{{ command }}\"\n          resources:\n            requests:\n              cpu: \"{{ cpu }}\"\n              memoryInGB: \"{{ memory }}\"\n          environmentVariables: []\n      osType: Linux\n      restartPolicy: Never\n</code></pre></p> <p>Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job manifest and available variables can be customized on a work pool by work pool basis. These customizations can be made via the Prefect UI when creating or editing a work pool.</p> <p>Using an ARM template makes the worker flexible; you're not limited to using the features the worker provides out of the box. Instead, you can modify the ARM template to use any features available in Azure Container Instances.</p>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerJobConfiguration","title":"<code>AzureContainerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration for an Azure Container Instance flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration for an Azure Container Instance flow run.\n    \"\"\"\n\n    image: str = Field(default_factory=get_prefect_image_name)\n    resource_group_name: str = Field(default=...)\n    subscription_id: SecretStr = Field(default=...)\n    identities: Optional[List[str]] = Field(default=None)\n    entrypoint: Optional[str] = Field(default=DEFAULT_CONTAINER_ENTRYPOINT)\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(default=None)\n    cpu: float = Field(default=ACI_DEFAULT_CPU)\n    gpu_count: Optional[int] = Field(default=None)\n    gpu_sku: Optional[str] = Field(default=None)\n    memory: float = Field(default=ACI_DEFAULT_MEMORY)\n    subnet_ids: Optional[List[str]] = Field(default=None)\n    dns_servers: Optional[List[str]] = Field(default=None)\n    stream_output: bool = Field(default=False)\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        # default to an empty credentials object that will use\n        # `DefaultAzureCredential` to authenticate.\n        default_factory=AzureContainerInstanceCredentials\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(default=240)\n    task_watch_poll_interval: float = Field(default=5.0)\n    arm_template: Dict[str, Any] = Field(template=_get_default_arm_template())\n    keep_container_group: bool = Field(default=False)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        # expectations:\n        # - the first resource in the template is the container group\n        # - the container group has a single container\n        container_group = self.arm_template[\"resources\"][0]\n        container = container_group[\"properties\"][\"containers\"][0]\n\n        # set the container's environment variables\n        container[\"properties\"][\"environmentVariables\"] = self._get_arm_environment()\n\n        # convert the command from a string to a list, because that's what ACI expects\n        if self.command:\n            container[\"properties\"][\"command\"] = self.command.split(\" \")\n\n        self._add_image()\n\n        # Add the entrypoint if provided. Creating an ACI container with a\n        # command overrides the container's built-in entrypoint. Prefect base images\n        # use entrypoint.sh as the entrypoint, so we need to add to the beginning of\n        # the command list to avoid breaking EXTRA_PIP_PACKAGES installation on\n        # container startup.\n        if self.entrypoint:\n            container[\"properties\"][\"command\"].insert(0, self.entrypoint)\n\n        if self.image_registry:\n            self._add_image_registry_credentials(self.image_registry)\n\n        if self.identities:\n            self._add_identities(self.identities)\n\n        if self.subnet_ids:\n            self._add_subnets(self.subnet_ids)\n\n        if self.dns_servers:\n            self._add_dns_servers(self.dns_servers)\n\n    def _add_image(self):\n        \"\"\"\n        Add the image to the arm template.\n        \"\"\"\n        try:\n            self.arm_template[\"resources\"][0][\"properties\"][\"containers\"][0][\n                \"properties\"\n            ][\"image\"] = self.image\n        except KeyError:\n            raise ValueError(\"Unable to add image due to invalid job ARM template.\")\n\n    def _add_image_registry_credentials(\n        self,\n        image_registry: Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n            None,\n        ],\n    ):\n        \"\"\"\n        Create image registry credentials based on the type of image_registry provided.\n\n        Args:\n            image_registry: An instance of a DockerRegistry or\n            ACRManagedIdentity object.\n        \"\"\"\n        if image_registry and isinstance(\n            image_registry, prefect.infrastructure.container.DockerRegistry\n        ):\n            self.arm_template[\"resources\"][0][\"properties\"][\n                \"imageRegistryCredentials\"\n            ] = [\n                {\n                    \"server\": image_registry.registry_url,\n                    \"username\": image_registry.username,\n                    \"password\": image_registry.password.get_secret_value(),\n                }\n            ]\n        elif image_registry and isinstance(image_registry, ACRManagedIdentity):\n            self.arm_template[\"resources\"][0][\"properties\"][\n                \"imageRegistryCredentials\"\n            ] = [\n                {\n                    \"server\": image_registry.registry_url,\n                    \"identity\": image_registry.identity,\n                }\n            ]\n\n    def _add_identities(self, identities: List[str]):\n        \"\"\"\n        Add identities to the container group.\n\n        Args:\n            identities: A list of user-assigned identities to add to\n            the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"identity\"] = {\n            \"type\": \"UserAssigned\",\n            \"userAssignedIdentities\": {\n                # note: For user-assigned identities, the key is the resource ID\n                # of the identity and the value is an empty object. See:\n                # https://docs.microsoft.com/en-us/azure/templates/microsoft.containerinstance/containergroups?tabs=bicep#identity-object # noqa\n                identity: {}\n                for identity in identities\n            },\n        }\n\n    def _add_subnets(self, subnet_ids: List[str]):\n        \"\"\"\n        Add subnets to the container group.\n\n        Args:\n            subnet_ids: A list of subnet ids to add to the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"properties\"][\"subnetIds\"] = [\n            {\"id\": subnet_id} for subnet_id in subnet_ids\n        ]\n\n    def _add_dns_servers(self, dns_servers: List[str]):\n        \"\"\"\n        Add dns servers to the container group.\n\n        Args:\n            dns_servers: A list of dns servers to add to the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"properties\"][\"dnsConfig\"] = {\n            \"nameServers\": dns_servers\n        }\n\n    def _get_arm_environment(self):\n        \"\"\"\n        Returns the environment variables to pass to the ARM template.\n        \"\"\"\n        env = {**self._base_environment(), **self.env}\n\n        azure_env = [\n            {\"name\": key, \"secureValue\": value}\n            if key in ENV_SECRETS\n            else {\"name\": key, \"value\": value}\n            for key, value in env.items()\n        ]\n        return azure_env\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    # expectations:\n    # - the first resource in the template is the container group\n    # - the container group has a single container\n    container_group = self.arm_template[\"resources\"][0]\n    container = container_group[\"properties\"][\"containers\"][0]\n\n    # set the container's environment variables\n    container[\"properties\"][\"environmentVariables\"] = self._get_arm_environment()\n\n    # convert the command from a string to a list, because that's what ACI expects\n    if self.command:\n        container[\"properties\"][\"command\"] = self.command.split(\" \")\n\n    self._add_image()\n\n    # Add the entrypoint if provided. Creating an ACI container with a\n    # command overrides the container's built-in entrypoint. Prefect base images\n    # use entrypoint.sh as the entrypoint, so we need to add to the beginning of\n    # the command list to avoid breaking EXTRA_PIP_PACKAGES installation on\n    # container startup.\n    if self.entrypoint:\n        container[\"properties\"][\"command\"].insert(0, self.entrypoint)\n\n    if self.image_registry:\n        self._add_image_registry_credentials(self.image_registry)\n\n    if self.identities:\n        self._add_identities(self.identities)\n\n    if self.subnet_ids:\n        self._add_subnets(self.subnet_ids)\n\n    if self.dns_servers:\n        self._add_dns_servers(self.dns_servers)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerVariables","title":"<code>AzureContainerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Variables for an Azure Container Instance flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerVariables(BaseVariables):\n    \"\"\"\n    Variables for an Azure Container Instance flow run.\n    \"\"\"\n\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    resource_group_name: str = Field(\n        default=...,\n        title=\"Azure Resource Group Name\",\n        description=(\n            \"The name of the Azure Resource Group in which to run Prefect ACI tasks.\"\n        ),\n    )\n    subscription_id: SecretStr = Field(\n        default=...,\n        title=\"Azure Subscription ID\",\n        description=\"The ID of the Azure subscription to create containers under.\",\n    )\n    identities: Optional[List[str]] = Field(\n        title=\"Identities\",\n        default=None,\n        description=(\n            \"A list of user-assigned identities to associate with the container group. \"\n            \"The identities should be an ARM resource IDs in the form: \"\n            \"'/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.\"  # noqa\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=DEFAULT_CONTAINER_ENTRYPOINT,\n        description=(\n            \"The entrypoint of the container you wish you run. This value \"\n            \"defaults to the entrypoint used by Prefect images and should only be \"\n            \"changed when using a custom image that is not based on an official \"\n            \"Prefect image. Any commands set on deployments will be passed \"\n            \"to the entrypoint as parameters.\"\n        ),\n    )\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(\n        default=None,\n        title=\"Image Registry (Optional)\",\n        description=(\n            \"To use any private container registry with a username and password, \"\n            \"choose DockerRegistry. To use a private Azure Container Registry \"\n            \"with a managed identity, choose ACRManagedIdentity.\"\n        ),\n    )\n    cpu: float = Field(\n        title=\"CPU\",\n        default=ACI_DEFAULT_CPU,\n        description=(\n            \"The number of virtual CPUs to assign to the task container. \"\n            f\"If not provided, a default value of {ACI_DEFAULT_CPU} will be used.\"\n        ),\n    )\n    gpu_count: Optional[int] = Field(\n        title=\"GPU Count\",\n        default=None,\n        description=(\n            \"The number of GPUs to assign to the task container. \"\n            \"If not provided, no GPU will be used.\"\n        ),\n    )\n    gpu_sku: Optional[str] = Field(\n        title=\"GPU SKU\",\n        default=None,\n        description=(\n            \"The Azure GPU SKU to use. See the ACI documentation for a list of \"\n            \"GPU SKUs available in each Azure region.\"\n        ),\n    )\n    memory: float = Field(\n        default=ACI_DEFAULT_MEMORY,\n        description=(\n            \"The amount of memory in gigabytes to provide to the ACI task. Valid \"\n            \"amounts are specified in the Azure documentation. If not provided, a \"\n            f\"default value of  {ACI_DEFAULT_MEMORY} will be used unless present \"\n            \"on the task definition.\"\n        ),\n    )\n    subnet_ids: Optional[List[str]] = Field(\n        title=\"Subnet IDs\",\n        default=None,\n        description=(\"A list of subnet IDs to associate with the container group. \"),\n    )\n    dns_servers: Optional[List[str]] = Field(\n        title=\"DNS Servers\",\n        default=None,\n        description=(\"A list of DNS servers to associate with the container group.\"),\n    )\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        default_factory=AzureContainerInstanceCredentials,\n        description=(\"The credentials to use to authenticate with Azure.\"),\n    )\n    stream_output: bool = Field(\n        default=False,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console.\"\n        ),\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=240,\n        description=(\n            \"The amount of time to watch for the start of the ACI container. \"\n            \"before marking it as failed.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The number of seconds to wait between Azure API calls while monitoring \"\n            \"the state of an Azure Container Instances task.\"\n        ),\n    )\n    keep_container_group: bool = Field(\n        default=False,\n        title=\"Keep Container Group After Completion\",\n        description=\"Keep the completed container group on Azure.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker","title":"<code>AzureContainerWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>A Prefect worker that runs flows in an Azure Container Instance.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerWorker(BaseWorker):\n    \"\"\"\n    A Prefect worker that runs flows in an Azure Container Instance.\n    \"\"\"\n\n    type = \"azure-container-instance\"\n    job_configuration = AzureContainerJobConfiguration\n    job_configuration_variables = AzureContainerVariables\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _display_name = \"Azure Container Instances\"\n    _description = (\n        \"Execute flow runs within containers on Azure's Container Instances \"\n        \"service. Requires an Azure account.\"\n    )\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-azure/container_instance_worker/\"\n    )\n\n    async def run(\n        self,\n        flow_run: FlowRun,\n        configuration: AzureContainerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ):\n        \"\"\"\n        Run a flow in an Azure Container Instance.\n        Args:\n            flow_run: The flow run to run.\n            configuration: The configuration for the flow run.\n            task_status: The task status object for the current task. Used\n            to provide an identifier that can be used to cancel the task.\n\n        Returns:\n            The result of the flow run.\n        \"\"\"\n        run_start_time = datetime.datetime.now(datetime.timezone.utc)\n        prefect_client = get_client()\n\n        # Get the flow, so we can use its name in the container group name\n        # to make it easier to identify and debug.\n        flow = await prefect_client.read_flow(flow_run.flow_id)\n        container_group_name = f\"{flow.name}-{flow_run.id}\"\n\n        # Slugify flow.name if the generated name will be too long for the\n        # max deployment name length (64) including \"prefect-\"\n        if len(container_group_name) &gt; 55:\n            slugified_flow_name = slugify(\n                flow.name,\n                max_length=55 - len(str(flow_run.id)),\n                regex_pattern=r\"[^a-zA-Z0-9-]+\",\n            )\n            container_group_name = f\"{slugified_flow_name}-{flow_run.id}\"\n\n        self._logger.info(\n            f\"{self._log_prefix}: Preparing to run command {configuration.command} \"\n            f\"in container  {configuration.image})...\"\n        )\n\n        aci_client = configuration.aci_credentials.get_container_client(\n            configuration.subscription_id.get_secret_value()\n        )\n        resource_client = configuration.aci_credentials.get_resource_client(\n            configuration.subscription_id.get_secret_value()\n        )\n\n        created_container_group: Union[ContainerGroup, None] = None\n        try:\n            self._logger.info(f\"{self._log_prefix}: Creating container group...\")\n\n            created_container_group = await self._provision_container_group(\n                aci_client,\n                resource_client,\n                configuration,\n                container_group_name,\n            )\n            # Both the flow ID and container group name will be needed to\n            # cancel the flow run if needed.\n            identifier = f\"{flow_run.id}:{container_group_name}\"\n\n            if self._provisioning_succeeded(created_container_group):\n                self._logger.info(f\"{self._log_prefix}: Running command...\")\n                if task_status is not None:\n                    task_status.started(value=identifier)\n\n                status_code = await run_sync_in_worker_thread(\n                    self._watch_task_and_get_exit_code,\n                    aci_client,\n                    configuration,\n                    created_container_group,\n                    run_start_time,\n                )\n\n                self._logger.info(f\"{self._log_prefix}: Completed command run.\")\n\n            else:\n                raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n        finally:\n            if configuration.keep_container_group:\n                self._logger.info(f\"{self._log_prefix}: Stopping container group...\")\n                aci_client.container_groups.stop(\n                    resource_group_name=configuration.resource_group_name,\n                    container_group_name=container_group_name,\n                )\n            else:\n                await self._wait_for_container_group_deletion(\n                    aci_client, configuration, container_group_name\n                )\n\n        return AzureContainerWorkerResult(\n            identifier=created_container_group.name, status_code=status_code\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: AzureContainerJobConfiguration,\n    ):\n        \"\"\"\n        Kill a flow running in an ACI container group.\n\n        Args:\n            infrastructure_pid: The container group identification data yielded by\n                `AzureContainerInstanceJob.run`.\n            configuration: The job configuration.\n        \"\"\"\n        (flow_run_id, container_group_name) = infrastructure_pid.split(\":\")\n\n        aci_client = configuration.aci_credentials.get_container_client(\n            configuration.subscription_id.get_secret_value()\n        )\n\n        # get the container group to check that it still exists\n        try:\n            container_group = aci_client.container_groups.get(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        except ResourceNotFoundError as exc:\n            # the container group no longer exists, so there's nothing to cancel\n            raise InfrastructureNotFound(\n                f\"Cannot stop ACI job: container group \"\n                f\"{container_group_name} no longer exists.\"\n            ) from exc\n\n        # get the container state to check if the container has terminated\n        container = self._get_container(container_group)\n        container_state = container.instance_view.current_state.state\n\n        # the container group needs to be deleted regardless of whether the container\n        # already terminated\n        await self._wait_for_container_group_deletion(\n            aci_client, configuration, container_group_name\n        )\n\n        # if the container has already terminated, raise an exception to let the agent\n        # know the flow was not cancelled\n        if container_state == ContainerRunState.TERMINATED:\n            raise InfrastructureNotAvailable(\n                f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n                f\"but container {container.name} has already terminated.\"\n            )\n\n    def _wait_for_task_container_start(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n        creation_status_poller: LROPoller[DeploymentExtended],\n    ) -&gt; Optional[ContainerGroup]:\n        \"\"\"\n        Wait for the result of group and container creation.\n\n        Args:\n            creation_status_poller: Poller returned by the Azure SDK.\n\n        Raises:\n            RuntimeError: Raised if the timeout limit is exceeded before the\n            container starts.\n\n        Returns:\n            A `ContainerGroup` representing the current status of the group being\n            watched, or None if creation failed.\n        \"\"\"\n        t0 = time.time()\n        timeout = configuration.task_start_timeout_seconds\n\n        while not creation_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while watching waiting for \"\n                        \"container start.\"\n                    )\n                )\n            time.sleep(configuration.task_watch_poll_interval)\n\n        deployment = creation_status_poller.result()\n\n        provisioning_succeeded = (\n            deployment.properties.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n        )\n\n        if provisioning_succeeded:\n            return self._get_container_group(\n                client, configuration.resource_group_name, container_group_name\n            )\n        else:\n            return None\n\n    async def _provision_container_group(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        resource_client: ResourceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n    ):\n        \"\"\"\n        Create a container group and wait for it to start.\n        Args:\n            aci_client: An authenticated ACI client.\n            resource_client: An authenticated resource client.\n            configuration: The job configuration.\n            container_group_name: The name of the container group to create.\n\n        Returns:\n            A `ContainerGroup` representing the container group that was created.\n        \"\"\"\n        properties = DeploymentProperties(\n            mode=DeploymentMode.INCREMENTAL,\n            template=configuration.arm_template,\n            parameters={\"container_group_name\": {\"value\": container_group_name}},\n        )\n        deployment = Deployment(properties=properties)\n\n        creation_status_poller = await run_sync_in_worker_thread(\n            resource_client.deployments.begin_create_or_update,\n            resource_group_name=configuration.resource_group_name,\n            deployment_name=f\"prefect-{container_group_name}\",\n            parameters=deployment,\n        )\n\n        created_container_group = await run_sync_in_worker_thread(\n            self._wait_for_task_container_start,\n            aci_client,\n            configuration,\n            container_group_name,\n            creation_status_poller,\n        )\n\n        return created_container_group\n\n    def _watch_task_and_get_exit_code(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        run_start_time: datetime.datetime,\n    ) -&gt; int:\n        \"\"\"\n        Waits until the container finishes running and obtains its exit code.\n\n        Args:\n            client: An initialized Azure `ContainerInstanceManagementClient`\n            container_group: The `ContainerGroup` in which the container resides.\n\n        Returns:\n            An `int` representing the container's exit code.\n        \"\"\"\n        status_code = -1\n        running_container = self._get_container(container_group)\n        current_state = running_container.instance_view.current_state.state\n\n        # get any logs the container has already generated\n        last_log_time = run_start_time\n        if configuration.stream_output:\n            last_log_time = self._get_and_stream_output(\n                client=client,\n                configuration=configuration,\n                container_group=container_group,\n                last_log_time=last_log_time,\n            )\n\n        # set exit code if flow run already finished:\n        if current_state == ContainerRunState.TERMINATED:\n            status_code = running_container.instance_view.current_state.exit_code\n\n        while current_state != ContainerRunState.TERMINATED:\n            try:\n                container_group = self._get_container_group(\n                    client,\n                    configuration.resource_group_name,\n                    container_group.name,\n                )\n            except ResourceNotFoundError:\n                self._logger.exception(\n                    f\"{self._log_prefix}: Container group was deleted before flow run \"\n                    \"completed, likely due to flow cancellation.\"\n                )\n\n                # since the flow was cancelled, exit early instead of raising an\n                # exception\n                return status_code\n\n            container = self._get_container(container_group)\n            current_state = container.instance_view.current_state.state\n\n            if current_state == ContainerRunState.TERMINATED:\n                status_code = container.instance_view.current_state.exit_code\n                # break instead of waiting for next loop iteration because\n                # trying to read logs from a terminated container raises an exception\n                break\n\n            if configuration.stream_output:\n                last_log_time = self._get_and_stream_output(\n                    client=client,\n                    configuration=configuration,\n                    container_group=container_group,\n                    last_log_time=last_log_time,\n                )\n\n            time.sleep(configuration.task_watch_poll_interval)\n\n        return status_code\n\n    async def _wait_for_container_group_deletion(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n    ):\n        \"\"\"\n        Wait for the container group to be deleted.\n        Args:\n            aci_client: An authenticated ACI client.\n            configuration: The job configuration.\n            container_group_name: The name of the container group to delete.\n        \"\"\"\n        self._logger.info(f\"{self._log_prefix}: Deleting container...\")\n\n        deletion_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_delete,\n            resource_group_name=configuration.resource_group_name,\n            container_group_name=container_group_name,\n        )\n\n        t0 = time.time()\n        timeout = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS\n\n        while not deletion_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while waiting for deletion of\"\n                        f\" container group {container_group_name}. To verify the group \"\n                        \"has been deleted, check the Azure Portal or run \"\n                        f\"az container show --name {container_group_name} --resource-group {configuration.resource_group_name}\"  # noqa\n                    )\n                )\n            await anyio.sleep(configuration.task_watch_poll_interval)\n\n        self._logger.info(f\"{self._log_prefix}: Container deleted.\")\n\n    def _get_container(self, container_group: ContainerGroup) -&gt; Container:\n        \"\"\"\n        Extracts the job container from a container group.\n        \"\"\"\n        return container_group.containers[0]\n\n    @staticmethod\n    def _get_container_group(\n        client: ContainerInstanceManagementClient,\n        resource_group_name: str,\n        container_group_name: str,\n    ) -&gt; ContainerGroup:\n        \"\"\"\n        Gets the container group from Azure.\n        \"\"\"\n        return client.container_groups.get(\n            resource_group_name=resource_group_name,\n            container_group_name=container_group_name,\n        )\n\n    def _get_and_stream_output(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        last_log_time: datetime.datetime,\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Fetches logs output from the job container and writes all entries after\n        a given time to stderr.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        logs = self._get_logs(\n            client=client, configuration=configuration, container_group=container_group\n        )\n        return self._stream_output(logs, last_log_time)\n\n    def _get_logs(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        max_lines: int = 100,\n    ) -&gt; str:\n        \"\"\"\n        Gets the most container logs up to a given maximum.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            max_lines: The number of log lines to pull. Defaults to 100.\n\n        Returns:\n            A string containing the requested log entries, one per line.\n        \"\"\"\n        container = self._get_container(container_group)\n\n        logs: Union[Logs, None] = None\n        try:\n            logs = client.containers.list_logs(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group.name,\n                container_name=container.name,\n                tail=max_lines,\n                timestamps=True,\n            )\n        except HttpResponseError:\n            # Trying to get logs when the container is under heavy CPU load sometimes\n            # results in an error, but we won't want to raise an exception and stop\n            # monitoring the flow. Instead, log the error and carry on so we can try to\n            # get all missed logs on the next check.\n            self._logger.warning(\n                f\"{self._log_prefix}: Unable to retrieve logs from container \"\n                f\"{container.name}. Trying again in \"\n                f\"{configuration.task_watch_poll_interval}s\"\n            )\n\n        return logs.content if logs else \"\"\n\n    def _stream_output(\n        self, log_content: Union[str, None], last_log_time: datetime.datetime\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Writes each entry from a string of log lines to stderr.\n\n        Args:\n            log_content: A string containing Azure container logs.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        if not log_content:\n            # nothing to stream\n            return last_log_time\n\n        log_lines = log_content.split(\"\\n\")\n\n        last_written_time = last_log_time\n\n        for log_line in log_lines:\n            # skip if the line is blank or whitespace\n            if not log_line.strip():\n                continue\n\n            line_parts = log_line.split(\" \")\n            # timestamp should always be before first space in line\n            line_timestamp = line_parts[0]\n            line = \" \".join(line_parts[1:])\n\n            try:\n                line_time = dateutil.parser.parse(line_timestamp)\n                if line_time &gt; last_written_time:\n                    self._write_output_line(line)\n                    last_written_time = line_time\n            except dateutil.parser.ParserError as e:\n                self._logger.debug(\n                    (\n                        f\"{self._log_prefix}: Unable to parse timestamp from Azure \"\n                        \"log line: %s\"\n                    ),\n                    log_line,\n                    exc_info=e,\n                )\n\n        return last_written_time\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"AzureContainerInstanceJob {self.name!r}\"\n        else:\n            return \"AzureContainerInstanceJob\"\n\n    @staticmethod\n    def _provisioning_succeeded(container_group: Union[ContainerGroup, None]) -&gt; bool:\n        \"\"\"\n        Determines whether ACI container group provisioning was successful.\n\n        Args:\n            container_group: a container group returned by the Azure SDK.\n\n        Returns:\n            True if provisioning was successful, False otherwise.\n        \"\"\"\n        if not container_group:\n            return False\n\n        return (\n            container_group.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n            and len(container_group.containers) == 1\n        )\n\n    @staticmethod\n    def _write_output_line(line: str):\n        \"\"\"\n        Writes a line of output to stderr.\n        \"\"\"\n        print(line, file=sys.stderr)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Kill a flow running in an ACI container group.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>The container group identification data yielded by <code>AzureContainerInstanceJob.run</code>.</p> required <code>configuration</code> <code>AzureContainerJobConfiguration</code> <p>The job configuration.</p> required Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: AzureContainerJobConfiguration,\n):\n    \"\"\"\n    Kill a flow running in an ACI container group.\n\n    Args:\n        infrastructure_pid: The container group identification data yielded by\n            `AzureContainerInstanceJob.run`.\n        configuration: The job configuration.\n    \"\"\"\n    (flow_run_id, container_group_name) = infrastructure_pid.split(\":\")\n\n    aci_client = configuration.aci_credentials.get_container_client(\n        configuration.subscription_id.get_secret_value()\n    )\n\n    # get the container group to check that it still exists\n    try:\n        container_group = aci_client.container_groups.get(\n            resource_group_name=configuration.resource_group_name,\n            container_group_name=container_group_name,\n        )\n    except ResourceNotFoundError as exc:\n        # the container group no longer exists, so there's nothing to cancel\n        raise InfrastructureNotFound(\n            f\"Cannot stop ACI job: container group \"\n            f\"{container_group_name} no longer exists.\"\n        ) from exc\n\n    # get the container state to check if the container has terminated\n    container = self._get_container(container_group)\n    container_state = container.instance_view.current_state.state\n\n    # the container group needs to be deleted regardless of whether the container\n    # already terminated\n    await self._wait_for_container_group_deletion(\n        aci_client, configuration, container_group_name\n    )\n\n    # if the container has already terminated, raise an exception to let the agent\n    # know the flow was not cancelled\n    if container_state == ContainerRunState.TERMINATED:\n        raise InfrastructureNotAvailable(\n            f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n            f\"but container {container.name} has already terminated.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run a flow in an Azure Container Instance. Args:     flow_run: The flow run to run.     configuration: The configuration for the flow run.     task_status: The task status object for the current task. Used     to provide an identifier that can be used to cancel the task.</p> <p>Returns:</p> Type Description <p>The result of the flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>async def run(\n    self,\n    flow_run: FlowRun,\n    configuration: AzureContainerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n):\n    \"\"\"\n    Run a flow in an Azure Container Instance.\n    Args:\n        flow_run: The flow run to run.\n        configuration: The configuration for the flow run.\n        task_status: The task status object for the current task. Used\n        to provide an identifier that can be used to cancel the task.\n\n    Returns:\n        The result of the flow run.\n    \"\"\"\n    run_start_time = datetime.datetime.now(datetime.timezone.utc)\n    prefect_client = get_client()\n\n    # Get the flow, so we can use its name in the container group name\n    # to make it easier to identify and debug.\n    flow = await prefect_client.read_flow(flow_run.flow_id)\n    container_group_name = f\"{flow.name}-{flow_run.id}\"\n\n    # Slugify flow.name if the generated name will be too long for the\n    # max deployment name length (64) including \"prefect-\"\n    if len(container_group_name) &gt; 55:\n        slugified_flow_name = slugify(\n            flow.name,\n            max_length=55 - len(str(flow_run.id)),\n            regex_pattern=r\"[^a-zA-Z0-9-]+\",\n        )\n        container_group_name = f\"{slugified_flow_name}-{flow_run.id}\"\n\n    self._logger.info(\n        f\"{self._log_prefix}: Preparing to run command {configuration.command} \"\n        f\"in container  {configuration.image})...\"\n    )\n\n    aci_client = configuration.aci_credentials.get_container_client(\n        configuration.subscription_id.get_secret_value()\n    )\n    resource_client = configuration.aci_credentials.get_resource_client(\n        configuration.subscription_id.get_secret_value()\n    )\n\n    created_container_group: Union[ContainerGroup, None] = None\n    try:\n        self._logger.info(f\"{self._log_prefix}: Creating container group...\")\n\n        created_container_group = await self._provision_container_group(\n            aci_client,\n            resource_client,\n            configuration,\n            container_group_name,\n        )\n        # Both the flow ID and container group name will be needed to\n        # cancel the flow run if needed.\n        identifier = f\"{flow_run.id}:{container_group_name}\"\n\n        if self._provisioning_succeeded(created_container_group):\n            self._logger.info(f\"{self._log_prefix}: Running command...\")\n            if task_status is not None:\n                task_status.started(value=identifier)\n\n            status_code = await run_sync_in_worker_thread(\n                self._watch_task_and_get_exit_code,\n                aci_client,\n                configuration,\n                created_container_group,\n                run_start_time,\n            )\n\n            self._logger.info(f\"{self._log_prefix}: Completed command run.\")\n\n        else:\n            raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n    finally:\n        if configuration.keep_container_group:\n            self._logger.info(f\"{self._log_prefix}: Stopping container group...\")\n            aci_client.container_groups.stop(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        else:\n            await self._wait_for_container_group_deletion(\n                aci_client, configuration, container_group_name\n            )\n\n    return AzureContainerWorkerResult(\n        identifier=created_container_group.name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorkerResult","title":"<code>AzureContainerWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.ContainerGroupProvisioningState","title":"<code>ContainerGroupProvisioningState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal provisioning states for ACI container groups. Per the Azure docs, the states in this Enum are the only ones that can be relied on as dependencies.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class ContainerGroupProvisioningState(str, Enum):\n    \"\"\"\n    Terminal provisioning states for ACI container groups. Per the Azure docs,\n    the states in this Enum are the only ones that can be relied on as dependencies.\n    \"\"\"\n\n    SUCCEEDED = \"Succeeded\"\n    FAILED = \"Failed\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.ContainerRunState","title":"<code>ContainerRunState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal run states for ACI containers.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class ContainerRunState(str, Enum):\n    \"\"\"\n    Terminal run states for ACI containers.\n    \"\"\"\n\n    RUNNING = \"Running\"\n    TERMINATED = \"Terminated\"\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/","title":"Cosmos DB","text":""},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db","title":"<code>prefect_azure.cosmos_db</code>","text":"<p>Tasks for interacting with Azure Cosmos DB</p>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_create_item","title":"<code>cosmos_db_create_item</code>  <code>async</code>","text":"<p>Create an item in the container.</p> <p>To update or replace an existing item, use the upsert_item method.</p> <p>Parameters:</p> Name Type Description Default <code>body</code> <code>Dict[str, Any]</code> <p>A dict-like object representing the item to create.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict representing the new item.</p> Example <p>Create an item in the container.</p> <p>To update or replace an existing item, use the upsert_item method. <pre><code>import uuid\n\nfrom prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_create_item\n\n@flow\ndef example_cosmos_db_create_item_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    body = {\n        \"firstname\": \"Olivia\",\n        \"age\": 3,\n        \"id\": str(uuid.uuid4())\n    }\n    container = \"Persons\"\n    database = \"SampleDB\"\n\n    result = cosmos_db_create_item(\n        body,\n        container,\n        database,\n        cosmos_db_credentials\n    )\n    return result\n\nexample_cosmos_db_create_item_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_create_item(\n    body: Dict[str, Any],\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    **kwargs: Any,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Create an item in the container.\n\n    To update or replace an existing item, use the upsert_item method.\n\n    Args:\n        body: A dict-like object representing the item to create.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        A dict representing the new item.\n\n    Example:\n        Create an item in the container.\n\n        To update or replace an existing item, use the upsert_item method.\n        ```python\n        import uuid\n\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_create_item\n\n        @flow\n        def example_cosmos_db_create_item_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            body = {\n                \"firstname\": \"Olivia\",\n                \"age\": 3,\n                \"id\": str(uuid.uuid4())\n            }\n            container = \"Persons\"\n            database = \"SampleDB\"\n\n            result = cosmos_db_create_item(\n                body,\n                container,\n                database,\n                cosmos_db_credentials\n            )\n            return result\n\n        example_cosmos_db_create_item_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Creating the item within container %s under %s database\",\n        container,\n        database,\n    )\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    create_item = partial(container_client.create_item, body, **kwargs)\n    result = await to_thread.run_sync(create_item)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_query_items","title":"<code>cosmos_db_query_items</code>  <code>async</code>","text":"<p>Return all results matching the given query.</p> <p>You can use any value for the container name in the FROM clause, but often the container name is used. In the examples below, the container name is \"products,\" and is aliased as \"p\" for easier referencing in the WHERE clause.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The Azure Cosmos DB SQL query to execute.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>parameters</code> <code>Optional[List[Dict[str, object]]]</code> <p>Optional array of parameters to the query. Each parameter is a dict() with 'name' and 'value' keys.</p> <code>None</code> <code>partition_key</code> <code>Optional[Any]</code> <p>Partition key for the item to retrieve.</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Union[str, dict]]</code> <p>An <code>list</code> of results.</p> Example <p>Query SampleDB Persons container where age &gt;= 44 <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_query_items\n\n@flow\ndef example_cosmos_db_query_items_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    query = \"SELECT * FROM c where c.age &gt;= @age\"\n    container = \"Persons\"\n    database = \"SampleDB\"\n    parameters = [dict(name=\"@age\", value=44)]\n\n    results = cosmos_db_query_items(\n        query,\n        container,\n        database,\n        cosmos_db_credentials,\n        parameters=parameters,\n        enable_cross_partition_query=True,\n    )\n    return results\n\nexample_cosmos_db_query_items_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_query_items(\n    query: str,\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    parameters: Optional[List[Dict[str, object]]] = None,\n    partition_key: Optional[Any] = None,\n    **kwargs: Any,\n) -&gt; List[Union[str, dict]]:\n    \"\"\"\n    Return all results matching the given query.\n\n    You can use any value for the container name in the FROM clause,\n    but often the container name is used.\n    In the examples below, the container name is \"products,\"\n    and is aliased as \"p\" for easier referencing in the WHERE clause.\n\n    Args:\n        query: The Azure Cosmos DB SQL query to execute.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        parameters: Optional array of parameters to the query.\n            Each parameter is a dict() with 'name' and 'value' keys.\n        partition_key: Partition key for the item to retrieve.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        An `list` of results.\n\n    Example:\n        Query SampleDB Persons container where age &gt;= 44\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_query_items\n\n        @flow\n        def example_cosmos_db_query_items_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            query = \"SELECT * FROM c where c.age &gt;= @age\"\n            container = \"Persons\"\n            database = \"SampleDB\"\n            parameters = [dict(name=\"@age\", value=44)]\n\n            results = cosmos_db_query_items(\n                query,\n                container,\n                database,\n                cosmos_db_credentials,\n                parameters=parameters,\n                enable_cross_partition_query=True,\n            )\n            return results\n\n        example_cosmos_db_query_items_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Running query from container %s in %s database\", container, database)\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    partial_query_items = partial(\n        container_client.query_items,\n        query,\n        parameters=parameters,\n        partition_key=partition_key,\n        **kwargs,\n    )\n    results = await to_thread.run_sync(partial_query_items)\n    return results\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_read_item","title":"<code>cosmos_db_read_item</code>  <code>async</code>","text":"<p>Get the item identified by item.</p> <p>Parameters:</p> Name Type Description Default <code>item</code> <code>Union[str, Dict[str, Any]]</code> <p>The ID (name) or dict representing item to retrieve.</p> required <code>partition_key</code> <code>Any</code> <p>Partition key for the item to retrieve.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Union[str, dict]]</code> <p>Dict representing the item to be retrieved.</p> Example <p>Read an item using a partition key from Cosmos DB. <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_read_item\n\n@flow\ndef example_cosmos_db_read_item_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    item = \"item\"\n    partition_key = \"partition_key\"\n    container = \"container\"\n    database = \"database\"\n\n    result = cosmos_db_read_item(\n        item,\n        partition_key,\n        container,\n        database,\n        cosmos_db_credentials\n    )\n    return result\n\nexample_cosmos_db_read_item_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_read_item(\n    item: Union[str, Dict[str, Any]],\n    partition_key: Any,\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    **kwargs: Any,\n) -&gt; List[Union[str, dict]]:\n    \"\"\"\n    Get the item identified by item.\n\n    Args:\n        item: The ID (name) or dict representing item to retrieve.\n        partition_key: Partition key for the item to retrieve.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        Dict representing the item to be retrieved.\n\n    Example:\n        Read an item using a partition key from Cosmos DB.\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_read_item\n\n        @flow\n        def example_cosmos_db_read_item_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            item = \"item\"\n            partition_key = \"partition_key\"\n            container = \"container\"\n            database = \"database\"\n\n            result = cosmos_db_read_item(\n                item,\n                partition_key,\n                container,\n                database,\n                cosmos_db_credentials\n            )\n            return result\n\n        example_cosmos_db_read_item_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Reading item %s with partition_key %s from container %s in %s database\",\n        item,\n        partition_key,\n        container,\n        database,\n    )\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    read_item = partial(container_client.read_item, item, partition_key, **kwargs)\n    result = await to_thread.run_sync(read_item)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials","title":"<code>prefect_azure.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with Azure</p>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials","title":"<code>AzureBlobStorageCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores credentials for authenticating with Azure Blob Storage.</p> <p>Parameters:</p> Name Type Description Default <code>account_url</code> <p>The URL for your Azure storage account. If provided, the account URL will be used to authenticate with the discovered default Azure credentials.</p> required <code>connection_string</code> <p>The connection string to your Azure storage account. If provided, the connection string will take precedence over the account URL.</p> required Example <p>Load stored Azure Blob Storage credentials and retrieve a blob service client: <pre><code>from prefect_azure import AzureBlobStorageCredentials\n\nazure_credentials_block = AzureBlobStorageCredentials.load(\"BLOCK_NAME\")\n\nblob_service_client = azure_credentials_block.get_blob_client()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureBlobStorageCredentials(Block):\n    \"\"\"\n    Stores credentials for authenticating with Azure Blob Storage.\n\n    Args:\n        account_url: The URL for your Azure storage account. If provided, the account\n            URL will be used to authenticate with the discovered default Azure\n            credentials.\n        connection_string: The connection string to your Azure storage account. If\n            provided, the connection string will take precedence over the account URL.\n\n    Example:\n        Load stored Azure Blob Storage credentials and retrieve a blob service client:\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n\n        azure_credentials_block = AzureBlobStorageCredentials.load(\"BLOCK_NAME\")\n\n        blob_service_client = azure_credentials_block.get_blob_client()\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure Blob Storage Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials\"  # noqa\n\n    connection_string: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The connection string to your Azure storage account. If provided, the \"\n            \"connection string will take precedence over the account URL.\"\n        ),\n    )\n    account_url: Optional[str] = Field(\n        default=None,\n        title=\"Account URL\",\n        description=(\n            \"The URL for your Azure storage account. If provided, the account \"\n            \"URL will be used to authenticate with the discovered default \"\n            \"Azure credentials.\"\n        ),\n    )\n\n    @root_validator\n    def check_connection_string_or_account_url(\n        cls, values: Dict[str, Any]\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Checks that either a connection string or account URL is provided, not both.\n        \"\"\"\n        has_account_url = values.get(\"account_url\") is not None\n        has_conn_str = values.get(\"connection_string\") is not None\n        if not has_account_url and not has_conn_str:\n            raise ValueError(\n                \"Must provide either a connection string or an account URL.\"\n            )\n        if has_account_url and has_conn_str:\n            raise ValueError(\n                \"Must provide either a connection string or account URL, but not both.\"\n            )\n        return values\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_client(self) -&gt; \"BlobServiceClient\":\n        \"\"\"\n        Returns an authenticated base Blob Service client that can be used to create\n        other clients for Azure services.\n\n        Example:\n            Create an authorized Blob Service session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_client() as blob_service_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return BlobServiceClient(\n                account_url=self.account_url,\n                credential=ADefaultAzureCredential(),\n            )\n\n        return BlobServiceClient.from_connection_string(\n            self.connection_string.get_secret_value()\n        )\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_blob_client(self, container, blob) -&gt; \"BlobClient\":\n        \"\"\"\n        Returns an authenticated Blob client that can be used to\n        download and upload blobs.\n\n        Args:\n            container: Name of the Blob Storage container to retrieve from.\n            blob: Name of the blob within this container to retrieve.\n\n        Example:\n            Create an authorized Blob session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_blob_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_blob_client(\n                    \"container\", \"blob\"\n                ) as blob_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_blob_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return BlobClient(\n                account_url=self.account_url,\n                container_name=container,\n                credential=ADefaultAzureCredential(),\n                blob_name=blob,\n            )\n\n        blob_client = BlobClient.from_connection_string(\n            self.connection_string.get_secret_value(), container, blob\n        )\n        return blob_client\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_container_client(self, container) -&gt; \"ContainerClient\":\n        \"\"\"\n        Returns an authenticated Container client that can be used to create clients\n        for Azure services.\n\n        Args:\n            container: Name of the Blob Storage container to retrieve from.\n\n        Example:\n            Create an authorized Container session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_container_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_container_client(\n                    \"container\"\n                ) as container_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_container_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return ContainerClient(\n                account_url=self.account_url,\n                container_name=container,\n                credential=ADefaultAzureCredential(),\n            )\n\n        container_client = ContainerClient.from_connection_string(\n            self.connection_string.get_secret_value(), container\n        )\n        return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.check_connection_string_or_account_url","title":"<code>check_connection_string_or_account_url</code>","text":"<p>Checks that either a connection string or account URL is provided, not both.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@root_validator\ndef check_connection_string_or_account_url(\n    cls, values: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Checks that either a connection string or account URL is provided, not both.\n    \"\"\"\n    has_account_url = values.get(\"account_url\") is not None\n    has_conn_str = values.get(\"connection_string\") is not None\n    if not has_account_url and not has_conn_str:\n        raise ValueError(\n            \"Must provide either a connection string or an account URL.\"\n        )\n    if has_account_url and has_conn_str:\n        raise ValueError(\n            \"Must provide either a connection string or account URL, but not both.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_blob_client","title":"<code>get_blob_client</code>","text":"<p>Returns an authenticated Blob client that can be used to download and upload blobs.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <p>Name of the Blob Storage container to retrieve from.</p> required <code>blob</code> <p>Name of the blob within this container to retrieve.</p> required Example <p>Create an authorized Blob session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_blob_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_blob_client(\n        \"container\", \"blob\"\n    ) as blob_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_blob_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_blob_client(self, container, blob) -&gt; \"BlobClient\":\n    \"\"\"\n    Returns an authenticated Blob client that can be used to\n    download and upload blobs.\n\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n        blob: Name of the blob within this container to retrieve.\n\n    Example:\n        Create an authorized Blob session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_blob_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_blob_client(\n                \"container\", \"blob\"\n            ) as blob_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_blob_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return BlobClient(\n            account_url=self.account_url,\n            container_name=container,\n            credential=ADefaultAzureCredential(),\n            blob_name=blob,\n        )\n\n    blob_client = BlobClient.from_connection_string(\n        self.connection_string.get_secret_value(), container, blob\n    )\n    return blob_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated base Blob Service client that can be used to create other clients for Azure services.</p> Example <p>Create an authorized Blob Service session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_client() as blob_service_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_client(self) -&gt; \"BlobServiceClient\":\n    \"\"\"\n    Returns an authenticated base Blob Service client that can be used to create\n    other clients for Azure services.\n\n    Example:\n        Create an authorized Blob Service session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_client() as blob_service_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return BlobServiceClient(\n            account_url=self.account_url,\n            credential=ADefaultAzureCredential(),\n        )\n\n    return BlobServiceClient.from_connection_string(\n        self.connection_string.get_secret_value()\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Returns an authenticated Container client that can be used to create clients for Azure services.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <p>Name of the Blob Storage container to retrieve from.</p> required Example <p>Create an authorized Container session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_container_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_container_client(\n        \"container\"\n    ) as container_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_container_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_container_client(self, container) -&gt; \"ContainerClient\":\n    \"\"\"\n    Returns an authenticated Container client that can be used to create clients\n    for Azure services.\n\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n\n    Example:\n        Create an authorized Container session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_container_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_container_client(\n                \"container\"\n            ) as container_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_container_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return ContainerClient(\n            account_url=self.account_url,\n            container_name=container,\n            credential=ADefaultAzureCredential(),\n        )\n\n    container_client = ContainerClient.from_connection_string(\n        self.connection_string.get_secret_value(), container\n    )\n    return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials","title":"<code>AzureContainerInstanceCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Azure Container Instances authentication. Stores Azure Service Principal authentication data.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureContainerInstanceCredentials(Block):\n    \"\"\"\n    Block used to manage Azure Container Instances authentication. Stores Azure Service\n    Principal authentication data.\n    \"\"\"\n\n    _block_type_name = \"Azure Container Instance Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials\"  # noqa\n\n    client_id: Optional[str] = Field(\n        default=None,\n        title=\"Client ID\",\n        description=(\n            \"The service principal client ID. \"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    tenant_id: Optional[str] = Field(\n        default=None,\n        title=\"Tenant ID\",\n        description=(\n            \"The service principal tenant ID.\"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    client_secret: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The service principal client secret.\"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    credential_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional Credential Keyword Arguments\",\n        description=(\n            \"Additional keyword arguments to pass to \"\n            \"`ClientSecretCredential` or `DefaultAzureCredential`.\"\n        ),\n    )\n\n    @root_validator\n    def validate_credential_kwargs(cls, values):\n        \"\"\"\n        Validates that if any of `client_id`, `tenant_id`, or `client_secret` are\n        provided, all must be provided.\n        \"\"\"\n        auth_args = (\"client_id\", \"tenant_id\", \"client_secret\")\n        has_any = any(values.get(key) is not None for key in auth_args)\n        has_all = all(values.get(key) is not None for key in auth_args)\n        if has_any and not has_all:\n            raise ValueError(\n                \"If any of `client_id`, `tenant_id`, or `client_secret` are provided, \"\n                \"all must be provided.\"\n            )\n        return values\n\n    def get_container_client(self, subscription_id: str):\n        \"\"\"\n        Creates an Azure Container Instances client initialized with data from\n        this block's fields and a provided Azure subscription ID.\n\n        Args:\n            subscription_id: A valid Azure subscription ID.\n\n        Returns:\n            An initialized `ContainerInstanceManagementClient`\n        \"\"\"\n\n        return ContainerInstanceManagementClient(\n            credential=self._create_credential(),\n            subscription_id=subscription_id,\n        )\n\n    def get_resource_client(self, subscription_id: str):\n        \"\"\"\n        Creates an Azure resource management client initialized with data from\n        this block's fields and a provided Azure subscription ID.\n\n        Args:\n            subscription_id: A valid Azure subscription ID.\n\n        Returns:\n            An initialized `ResourceManagementClient`\n        \"\"\"\n\n        return ResourceManagementClient(\n            credential=self._create_credential(),\n            subscription_id=subscription_id,\n        )\n\n    def _create_credential(self):\n        \"\"\"\n        Creates an Azure credential initialized with data from this block's fields.\n\n        Returns:\n            An initialized Azure `TokenCredential` ready to use with Azure SDK client\n            classes.\n        \"\"\"\n        auth_args = (self.client_id, self.tenant_id, self.client_secret)\n        if auth_args == (None, None, None):\n            return DefaultAzureCredential(**self.credential_kwargs)\n\n        return ClientSecretCredential(\n            tenant_id=self.tenant_id,\n            client_id=self.client_id,\n            client_secret=self.client_secret.get_secret_value(),\n            **self.credential_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Creates an Azure Container Instances client initialized with data from this block's fields and a provided Azure subscription ID.</p> <p>Parameters:</p> Name Type Description Default <code>subscription_id</code> <code>str</code> <p>A valid Azure subscription ID.</p> required <p>Returns:</p> Type Description <p>An initialized <code>ContainerInstanceManagementClient</code></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_container_client(self, subscription_id: str):\n    \"\"\"\n    Creates an Azure Container Instances client initialized with data from\n    this block's fields and a provided Azure subscription ID.\n\n    Args:\n        subscription_id: A valid Azure subscription ID.\n\n    Returns:\n        An initialized `ContainerInstanceManagementClient`\n    \"\"\"\n\n    return ContainerInstanceManagementClient(\n        credential=self._create_credential(),\n        subscription_id=subscription_id,\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.get_resource_client","title":"<code>get_resource_client</code>","text":"<p>Creates an Azure resource management client initialized with data from this block's fields and a provided Azure subscription ID.</p> <p>Parameters:</p> Name Type Description Default <code>subscription_id</code> <code>str</code> <p>A valid Azure subscription ID.</p> required <p>Returns:</p> Type Description <p>An initialized <code>ResourceManagementClient</code></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_resource_client(self, subscription_id: str):\n    \"\"\"\n    Creates an Azure resource management client initialized with data from\n    this block's fields and a provided Azure subscription ID.\n\n    Args:\n        subscription_id: A valid Azure subscription ID.\n\n    Returns:\n        An initialized `ResourceManagementClient`\n    \"\"\"\n\n    return ResourceManagementClient(\n        credential=self._create_credential(),\n        subscription_id=subscription_id,\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.validate_credential_kwargs","title":"<code>validate_credential_kwargs</code>","text":"<p>Validates that if any of <code>client_id</code>, <code>tenant_id</code>, or <code>client_secret</code> are provided, all must be provided.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@root_validator\ndef validate_credential_kwargs(cls, values):\n    \"\"\"\n    Validates that if any of `client_id`, `tenant_id`, or `client_secret` are\n    provided, all must be provided.\n    \"\"\"\n    auth_args = (\"client_id\", \"tenant_id\", \"client_secret\")\n    has_any = any(values.get(key) is not None for key in auth_args)\n    has_all = all(values.get(key) is not None for key in auth_args)\n    if has_any and not has_all:\n        raise ValueError(\n            \"If any of `client_id`, `tenant_id`, or `client_secret` are provided, \"\n            \"all must be provided.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials","title":"<code>AzureCosmosDbCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Cosmos DB authentication with Azure. Azure authentication is handled via the <code>azure</code> module through a connection string.</p> <p>Parameters:</p> Name Type Description Default <code>connection_string</code> <p>Includes the authorization information required.</p> required Example <p>Load stored Azure Cosmos DB credentials: <pre><code>from prefect_azure import AzureCosmosDbCredentials\nazure_credentials_block = AzureCosmosDbCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureCosmosDbCredentials(Block):\n    \"\"\"\n    Block used to manage Cosmos DB authentication with Azure.\n    Azure authentication is handled via the `azure` module through\n    a connection string.\n\n    Args:\n        connection_string: Includes the authorization information required.\n\n    Example:\n        Load stored Azure Cosmos DB credentials:\n        ```python\n        from prefect_azure import AzureCosmosDbCredentials\n        azure_credentials_block = AzureCosmosDbCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure Cosmos DB Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials\"  # noqa\n\n    connection_string: SecretStr = Field(\n        default=..., description=\"Includes the authorization information required.\"\n    )\n\n    @_raise_help_msg(\"cosmos_db\")\n    def get_client(self) -&gt; \"CosmosClient\":\n        \"\"\"\n        Returns an authenticated Cosmos client that can be used to create\n        other clients for Azure services.\n\n        Example:\n            Create an authorized Cosmos session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureCosmosDbCredentials\n\n            @flow\n            def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                cosmos_client = azure_credentials.get_client()\n                return cosmos_client\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        return CosmosClient.from_connection_string(\n            self.connection_string.get_secret_value()\n        )\n\n    def get_database_client(self, database: str) -&gt; \"DatabaseProxy\":\n        \"\"\"\n        Returns an authenticated Database client.\n\n        Args:\n            database: Name of the database.\n\n        Example:\n            Create an authorized Cosmos session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureCosmosDbCredentials\n\n            @flow\n            def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                cosmos_client = azure_credentials.get_database_client()\n                return cosmos_client\n\n            example_get_database_client_flow()\n            ```\n        \"\"\"\n        cosmos_client = self.get_client()\n        database_client = cosmos_client.get_database_client(database=database)\n        return database_client\n\n    def get_container_client(self, container: str, database: str) -&gt; \"ContainerProxy\":\n        \"\"\"\n        Returns an authenticated Container client used for querying.\n\n        Args:\n            container: Name of the Cosmos DB container to retrieve from.\n            database: Name of the Cosmos DB database.\n\n        Example:\n            Create an authorized Container session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            def example_get_container_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                container_client = azure_credentials.get_container_client(container)\n                return container_client\n\n            example_get_container_client_flow()\n            ```\n        \"\"\"\n        database_client = self.get_database_client(database)\n        container_client = database_client.get_container_client(container=container)\n        return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated Cosmos client that can be used to create other clients for Azure services.</p> Example <p>Create an authorized Cosmos session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureCosmosDbCredentials\n\n@flow\ndef example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    cosmos_client = azure_credentials.get_client()\n    return cosmos_client\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"cosmos_db\")\ndef get_client(self) -&gt; \"CosmosClient\":\n    \"\"\"\n    Returns an authenticated Cosmos client that can be used to create\n    other clients for Azure services.\n\n    Example:\n        Create an authorized Cosmos session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureCosmosDbCredentials\n\n        @flow\n        def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            cosmos_client = azure_credentials.get_client()\n            return cosmos_client\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    return CosmosClient.from_connection_string(\n        self.connection_string.get_secret_value()\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Returns an authenticated Container client used for querying.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>Name of the Cosmos DB container to retrieve from.</p> required <code>database</code> <code>str</code> <p>Name of the Cosmos DB database.</p> required Example <p>Create an authorized Container session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\ndef example_get_container_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    container_client = azure_credentials.get_container_client(container)\n    return container_client\n\nexample_get_container_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_container_client(self, container: str, database: str) -&gt; \"ContainerProxy\":\n    \"\"\"\n    Returns an authenticated Container client used for querying.\n\n    Args:\n        container: Name of the Cosmos DB container to retrieve from.\n        database: Name of the Cosmos DB database.\n\n    Example:\n        Create an authorized Container session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        def example_get_container_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            container_client = azure_credentials.get_container_client(container)\n            return container_client\n\n        example_get_container_client_flow()\n        ```\n    \"\"\"\n    database_client = self.get_database_client(database)\n    container_client = database_client.get_container_client(container=container)\n    return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_database_client","title":"<code>get_database_client</code>","text":"<p>Returns an authenticated Database client.</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>str</code> <p>Name of the database.</p> required Example <p>Create an authorized Cosmos session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureCosmosDbCredentials\n\n@flow\ndef example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    cosmos_client = azure_credentials.get_database_client()\n    return cosmos_client\n\nexample_get_database_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_database_client(self, database: str) -&gt; \"DatabaseProxy\":\n    \"\"\"\n    Returns an authenticated Database client.\n\n    Args:\n        database: Name of the database.\n\n    Example:\n        Create an authorized Cosmos session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureCosmosDbCredentials\n\n        @flow\n        def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            cosmos_client = azure_credentials.get_database_client()\n            return cosmos_client\n\n        example_get_database_client_flow()\n        ```\n    \"\"\"\n    cosmos_client = self.get_client()\n    database_client = cosmos_client.get_database_client(database=database)\n    return database_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials","title":"<code>AzureMlCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage authentication with AzureML. Azure authentication is handled via the <code>azure</code> module.</p> <p>Parameters:</p> Name Type Description Default <code>tenant_id</code> <p>The active directory tenant that the service identity belongs to.</p> required <code>service_principal_id</code> <p>The service principal ID.</p> required <code>service_principal_password</code> <p>The service principal password/key.</p> required <code>subscription_id</code> <p>The Azure subscription ID containing the workspace.</p> required <code>resource_group</code> <p>The resource group containing the workspace.</p> required <code>workspace_name</code> <p>The existing workspace name.</p> required Example <p>Load stored AzureML credentials: <pre><code>from prefect_azure import AzureMlCredentials\nazure_ml_credentials_block = AzureMlCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureMlCredentials(Block):\n    \"\"\"\n    Block used to manage authentication with AzureML. Azure authentication is\n    handled via the `azure` module.\n\n    Args:\n        tenant_id: The active directory tenant that the service identity belongs to.\n        service_principal_id: The service principal ID.\n        service_principal_password: The service principal password/key.\n        subscription_id: The Azure subscription ID containing the workspace.\n        resource_group: The resource group containing the workspace.\n        workspace_name: The existing workspace name.\n\n    Example:\n        Load stored AzureML credentials:\n        ```python\n        from prefect_azure import AzureMlCredentials\n        azure_ml_credentials_block = AzureMlCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"AzureML Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials\"  # noqa\n\n    tenant_id: str = Field(\n        default=...,\n        description=\"The active directory tenant that the service identity belongs to.\",\n    )\n    service_principal_id: str = Field(\n        default=..., description=\"The service principal ID.\"\n    )\n    service_principal_password: SecretStr = Field(\n        default=..., description=\"The service principal password/key.\"\n    )\n    subscription_id: str = Field(\n        default=...,\n        description=\"The Azure subscription ID containing the workspace, in format: '00000000-0000-0000-0000-000000000000'.\",  # noqa\n    )\n    resource_group: str = Field(\n        default=..., description=\"The resource group containing the workspace.\"\n    )\n    workspace_name: str = Field(default=..., description=\"The existing workspace name.\")\n\n    @_raise_help_msg(\"ml_datastore\")\n    def get_workspace(self) -&gt; \"Workspace\":\n        \"\"\"\n        Returns an authenticated base Workspace that can be used in\n        Azure's Datasets and Datastores.\n\n        Example:\n            Create an authorized workspace\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureMlCredentials\n            @flow\n            def example_get_workspace_flow():\n                azure_credentials = AzureMlCredentials(\n                    tenant_id=\"tenant_id\",\n                    service_principal_id=\"service_principal_id\",\n                    service_principal_password=\"service_principal_password\",\n                    subscription_id=\"subscription_id\",\n                    resource_group=\"resource_group\",\n                    workspace_name=\"workspace_name\"\n                )\n                workspace_client = azure_credentials.get_workspace()\n                return workspace_client\n            example_get_workspace_flow()\n            ```\n        \"\"\"\n        service_principal_password = self.service_principal_password.get_secret_value()\n        service_principal_authentication = ServicePrincipalAuthentication(\n            tenant_id=self.tenant_id,\n            service_principal_id=self.service_principal_id,\n            service_principal_password=service_principal_password,\n        )\n\n        workspace = Workspace(\n            subscription_id=self.subscription_id,\n            resource_group=self.resource_group,\n            workspace_name=self.workspace_name,\n            auth=service_principal_authentication,\n        )\n\n        return workspace\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials.get_workspace","title":"<code>get_workspace</code>","text":"<p>Returns an authenticated base Workspace that can be used in Azure's Datasets and Datastores.</p> Example <p>Create an authorized workspace <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureMlCredentials\n@flow\ndef example_get_workspace_flow():\n    azure_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\"\n    )\n    workspace_client = azure_credentials.get_workspace()\n    return workspace_client\nexample_get_workspace_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"ml_datastore\")\ndef get_workspace(self) -&gt; \"Workspace\":\n    \"\"\"\n    Returns an authenticated base Workspace that can be used in\n    Azure's Datasets and Datastores.\n\n    Example:\n        Create an authorized workspace\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        @flow\n        def example_get_workspace_flow():\n            azure_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\"\n            )\n            workspace_client = azure_credentials.get_workspace()\n            return workspace_client\n        example_get_workspace_flow()\n        ```\n    \"\"\"\n    service_principal_password = self.service_principal_password.get_secret_value()\n    service_principal_authentication = ServicePrincipalAuthentication(\n        tenant_id=self.tenant_id,\n        service_principal_id=self.service_principal_id,\n        service_principal_password=service_principal_password,\n    )\n\n    workspace = Workspace(\n        subscription_id=self.subscription_id,\n        resource_group=self.resource_group,\n        workspace_name=self.workspace_name,\n        auth=service_principal_authentication,\n    )\n\n    return workspace\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/","title":"ML Datastore","text":""},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore","title":"<code>prefect_azure.ml_datastore</code>","text":"<p>Tasks for interacting with Azure ML Datastore</p>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_get_datastore","title":"<code>ml_get_datastore</code>  <code>async</code>","text":"<p>Gets the Datastore within the Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>datastore_name</code> <code>str</code> <p>The name of the Datastore. If <code>None</code>, then the default Datastore of the Workspace is returned.</p> <code>None</code> Example <p>Get Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_get_datastore\n\n@flow\ndef example_ml_get_datastore_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    results = ml_get_datastore(ml_credentials, datastore_name=\"datastore_name\")\n    return results\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_get_datastore(\n    ml_credentials: \"AzureMlCredentials\", datastore_name: str = None\n) -&gt; Datastore:\n    \"\"\"\n    Gets the Datastore within the Workspace.\n\n    Args:\n        ml_credentials: Credentials to use for authentication with Azure.\n        datastore_name: The name of the Datastore. If `None`, then the\n            default Datastore of the Workspace is returned.\n\n    Example:\n        Get Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_get_datastore\n\n        @flow\n        def example_ml_get_datastore_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            results = ml_get_datastore(ml_credentials, datastore_name=\"datastore_name\")\n            return results\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Getting datastore %s\", datastore_name)\n\n    result = await _get_datastore(ml_credentials, datastore_name)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_list_datastores","title":"<code>ml_list_datastores</code>","text":"<p>Lists the Datastores in the Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required Example <p>List Datastore objects <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_list_datastores\n\n@flow\ndef example_ml_list_datastores_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    results = ml_list_datastores(ml_credentials)\n    return results\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\ndef ml_list_datastores(ml_credentials: \"AzureMlCredentials\") -&gt; Dict:\n    \"\"\"\n    Lists the Datastores in the Workspace.\n\n    Args:\n        ml_credentials: Credentials to use for authentication with Azure.\n\n    Example:\n        List Datastore objects\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_list_datastores\n\n        @flow\n        def example_ml_list_datastores_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            results = ml_list_datastores(ml_credentials)\n            return results\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Listing datastores\")\n\n    workspace = ml_credentials.get_workspace()\n    results = workspace.datastores\n    return results\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_register_datastore_blob_container","title":"<code>ml_register_datastore_blob_container</code>  <code>async</code>","text":"<p>Registers a Azure Blob Storage container as a Datastore in a Azure ML service Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>container_name</code> <code>str</code> <p>The name of the container.</p> required <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure ML.</p> required <code>blob_storage_credentials</code> <code>AzureBlobStorageCredentials</code> <p>Credentials to use for authentication with Azure Blob Storage.</p> required <code>datastore_name</code> <code>str</code> <p>The name of the datastore. If not defined, the container name will be used.</p> <code>None</code> <code>create_container_if_not_exists</code> <code>bool</code> <p>Create a container, if one does not exist with the given name.</p> <code>False</code> <code>overwrite</code> <code>bool</code> <p>Overwrite an existing datastore. If the datastore does not exist, it will be created.</p> <code>False</code> <code>set_as_default</code> <code>bool</code> <p>Set the created Datastore as the default datastore for the Workspace.</p> <code>False</code> Example <p>Upload Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_register_datastore_blob_container\n\n@flow\ndef example_ml_register_datastore_blob_container_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    blob_storage_credentials = AzureBlobStorageCredentials(\"connection_string\")\n    result = ml_register_datastore_blob_container(\n        \"container\",\n        ml_credentials,\n        blob_storage_credentials,\n        datastore_name=\"datastore_name\"\n    )\n    return result\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_register_datastore_blob_container(\n    container_name: str,\n    ml_credentials: \"AzureMlCredentials\",\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    datastore_name: str = None,\n    create_container_if_not_exists: bool = False,\n    overwrite: bool = False,\n    set_as_default: bool = False,\n) -&gt; \"AzureBlobDatastore\":\n    \"\"\"\n    Registers a Azure Blob Storage container as a\n    Datastore in a Azure ML service Workspace.\n\n    Args:\n        container_name: The name of the container.\n        ml_credentials: Credentials to use for authentication with Azure ML.\n        blob_storage_credentials: Credentials to use for authentication\n            with Azure Blob Storage.\n        datastore_name: The name of the datastore. If not defined, the\n            container name will be used.\n        create_container_if_not_exists: Create a container, if one does not\n            exist with the given name.\n        overwrite: Overwrite an existing datastore. If\n            the datastore does not exist, it will be created.\n        set_as_default: Set the created Datastore as the default datastore\n            for the Workspace.\n\n    Example:\n        Upload Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_register_datastore_blob_container\n\n        @flow\n        def example_ml_register_datastore_blob_container_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            blob_storage_credentials = AzureBlobStorageCredentials(\"connection_string\")\n            result = ml_register_datastore_blob_container(\n                \"container\",\n                ml_credentials,\n                blob_storage_credentials,\n                datastore_name=\"datastore_name\"\n            )\n            return result\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    if datastore_name is None:\n        datastore_name = container_name\n\n    logger.info(\n        \"Registering %s container into %s datastore\", container_name, datastore_name\n    )\n\n    workspace = ml_credentials.get_workspace()\n    async with blob_storage_credentials.get_client() as blob_service_client:\n        credential = blob_service_client.credential\n        account_name = credential.account_name\n        account_key = credential.account_key\n\n    partial_register = partial(\n        Datastore.register_azure_blob_container,\n        workspace=workspace,\n        datastore_name=datastore_name,\n        container_name=container_name,\n        account_name=account_name,\n        account_key=account_key,\n        overwrite=overwrite,\n        create_if_not_exists=create_container_if_not_exists,\n    )\n    result = await to_thread.run_sync(partial_register)\n\n    if set_as_default:\n        result.set_as_default()\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_upload_datastore","title":"<code>ml_upload_datastore</code>  <code>async</code>","text":"<p>Uploads local files to a Datastore.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Union[str, Path, List[Union[str, Path]]]</code> <p>The path to a single file, single directory, or a list of path to files to be uploaded.</p> required <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>target_path</code> <code>Union[str, Path]</code> <p>The location in the blob container to upload to. If None, then upload to root.</p> <code>None</code> <code>relative_root</code> <code>Union[str, Path]</code> <p>The root from which is used to determine the path of the files in the blob. For example, if we upload /path/to/file.txt, and we define base path to be /path, when file.txt is uploaded to the blob storage, it will have the path of /to/file.txt.</p> <code>None</code> <code>datastore_name</code> <code>str</code> <p>The name of the Datastore. If <code>None</code>, then the default Datastore of the Workspace is returned.</p> <code>None</code> <code>overwrite</code> <code>bool</code> <p>Overwrite existing file(s).</p> <code>False</code> Example <p>Upload Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_upload_datastore\n\n@flow\ndef example_ml_upload_datastore_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    result = ml_upload_datastore(\n        \"path/to/dir/or/file\",\n        ml_credentials,\n        datastore_name=\"datastore_name\"\n    )\n    return result\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_upload_datastore(\n    path: Union[str, Path, List[Union[str, Path]]],\n    ml_credentials: \"AzureMlCredentials\",\n    target_path: Union[str, Path] = None,\n    relative_root: Union[str, Path] = None,\n    datastore_name: str = None,\n    overwrite: bool = False,\n) -&gt; \"DataReference\":\n    \"\"\"\n    Uploads local files to a Datastore.\n\n    Args:\n        path: The path to a single file, single directory,\n            or a list of path to files to be uploaded.\n        ml_credentials: Credentials to use for authentication with Azure.\n        target_path: The location in the blob container to upload to. If\n            None, then upload to root.\n        relative_root: The root from which is used to determine the path of\n            the files in the blob. For example, if we upload /path/to/file.txt,\n            and we define base path to be /path, when file.txt is uploaded\n            to the blob storage, it will have the path of /to/file.txt.\n        datastore_name: The name of the Datastore. If `None`, then the\n            default Datastore of the Workspace is returned.\n        overwrite: Overwrite existing file(s).\n\n    Example:\n        Upload Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_upload_datastore\n\n        @flow\n        def example_ml_upload_datastore_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            result = ml_upload_datastore(\n                \"path/to/dir/or/file\",\n                ml_credentials,\n                datastore_name=\"datastore_name\"\n            )\n            return result\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading %s into %s datastore\", path, datastore_name)\n\n    datastore = await _get_datastore(ml_credentials, datastore_name)\n\n    if isinstance(path, Path):\n        path = str(path)\n    elif isinstance(path, list) and isinstance(path[0], Path):\n        path = [str(p) for p in path]\n\n    if isinstance(target_path, Path):\n        target_path = str(target_path)\n\n    if isinstance(relative_root, Path):\n        relative_root = str(relative_root)\n\n    if isinstance(path, str) and os.path.isdir(path):\n        partial_upload = partial(\n            datastore.upload,\n            src_dir=path,\n            target_path=target_path,\n            overwrite=overwrite,\n            show_progress=False,\n        )\n    else:\n        partial_upload = partial(\n            datastore.upload_files,\n            files=path if isinstance(path, list) else [path],\n            relative_root=relative_root,\n            target_path=target_path,\n            overwrite=overwrite,\n            show_progress=False,\n        )\n\n    result = await to_thread.run_sync(partial_upload)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps","title":"<code>prefect_azure.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage and retrieval in Azure Blob Storage.</p> <p>These steps can be used in a <code>prefect.yaml</code> file to define the default  push and pull steps for a group of deployments, or they can be used to  define the push and pull steps for a specific deployment.</p> <p>Example</p> <p>Sample <code>prefect.yaml</code> file that is configured to push and pull to and  from an Azure Blob Storage container:</p> <pre><code>prefect_version: ...\nname: ...\n\npush:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n\npull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: \"{{ container }}\"\n        folder: \"{{ folder }}\"\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre> <p>Note</p> <p>Azure Storage account needs to have Hierarchical Namespace disabled.</p> <p>For more information about using deployment steps, check out out the Prefect docs.</p>"},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps.pull_from_azure_blob_storage","title":"<code>pull_from_azure_blob_storage</code>","text":"<p>Pulls from an Azure Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>The name of the container to pull files from</p> required <code>folder</code> <code>str</code> <p>The folder within the container to pull from</p> required <code>credentials</code> <code>Dict[str, str]</code> <p>A dictionary of credentials with keys <code>connection_string</code> or <code>account_url</code> and values of the corresponding connection string or account url. If both are provided, <code>connection_string</code> will be used.</p> required Note <p>Azure Storage account needs to have Hierarchical Namespace disabled.</p> Example <p>Pull from an Azure Blob Storage container using credentials stored in a block: <pre><code>pull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre></p> <p>Pull from an Azure Blob Storage container using an account URL and default credentials: <pre><code>pull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials:\n            account_url: https://myaccount.blob.core.windows.net/\n</code></pre></p> Source code in <code>prefect_azure/deployments/steps.py</code> <pre><code>def pull_from_azure_blob_storage(\n    container: str,\n    folder: str,\n    credentials: Dict[str, str],\n):\n    \"\"\"\n    Pulls from an Azure Blob Storage container.\n\n    Args:\n        container: The name of the container to pull files from\n        folder: The folder within the container to pull from\n        credentials: A dictionary of credentials with keys `connection_string` or\n            `account_url` and values of the corresponding connection string or\n            account url. If both are provided, `connection_string` will be used.\n\n    Note:\n        Azure Storage account needs to have Hierarchical Namespace disabled.\n\n    Example:\n        Pull from an Azure Blob Storage container using credentials stored in\n        a block:\n        ```yaml\n        pull:\n            - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n        ```\n\n        Pull from an Azure Blob Storage container using an account URL and\n        default credentials:\n        ```yaml\n        pull:\n            - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials:\n                    account_url: https://myaccount.blob.core.windows.net/\n        ```\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    if credentials.get(\"connection_string\") is not None:\n        container_client = ContainerClient.from_connection_string(\n            credentials[\"connection_string\"], container_name=container\n        )\n    elif credentials.get(\"account_url\") is not None:\n        container_client = ContainerClient(\n            account_url=credentials[\"account_url\"],\n            container_name=container,\n            credential=DefaultAzureCredential(),\n        )\n    else:\n        raise ValueError(\n            \"Credentials must contain either connection_string or account_url\"\n        )\n\n    with container_client as client:\n        for blob in client.list_blobs(name_starts_with=folder):\n            target = PurePosixPath(\n                local_path\n                / relative_path_to_current_platform(blob.name).relative_to(folder)\n            )\n            Path.mkdir(Path(target.parent), parents=True, exist_ok=True)\n            with open(target, \"wb\") as f:\n                client.download_blob(blob).readinto(f)\n\n    return {\n        \"container\": container,\n        \"folder\": folder,\n        \"directory\": local_path,\n    }\n</code></pre>"},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps.push_to_azure_blob_storage","title":"<code>push_to_azure_blob_storage</code>","text":"<p>Pushes to an Azure Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>The name of the container to push files to</p> required <code>folder</code> <code>str</code> <p>The folder within the container to push to</p> required <code>credentials</code> <code>Dict[str, str]</code> <p>A dictionary of credentials with keys <code>connection_string</code> or <code>account_url</code> and values of the corresponding connection string or account url. If both are provided, <code>connection_string</code> will be used.</p> required <code>ignore_file</code> <code>Optional[str]</code> <p>The path to a file containing patterns of files to ignore when pushing to Azure Blob Storage. If not provided, the default <code>.prefectignore</code> file will be used.</p> <code>'.prefectignore'</code> Example <p>Push to an Azure Blob Storage container using credentials stored in a block: <pre><code>push:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre></p> <p>Push to an Azure Blob Storage container using an account URL and default credentials: <pre><code>push:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials:\n            account_url: https://myaccount.blob.core.windows.net/\n</code></pre></p> Source code in <code>prefect_azure/deployments/steps.py</code> <pre><code>def push_to_azure_blob_storage(\n    container: str,\n    folder: str,\n    credentials: Dict[str, str],\n    ignore_file: Optional[str] = \".prefectignore\",\n):\n    \"\"\"\n    Pushes to an Azure Blob Storage container.\n\n    Args:\n        container: The name of the container to push files to\n        folder: The folder within the container to push to\n        credentials: A dictionary of credentials with keys `connection_string` or\n            `account_url` and values of the corresponding connection string or\n            account url. If both are provided, `connection_string` will be used.\n        ignore_file: The path to a file containing patterns of files to ignore when\n            pushing to Azure Blob Storage. If not provided, the default `.prefectignore`\n            file will be used.\n\n    Example:\n        Push to an Azure Blob Storage container using credentials stored in a\n        block:\n        ```yaml\n        push:\n            - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n        ```\n\n        Push to an Azure Blob Storage container using an account URL and\n        default credentials:\n        ```yaml\n        push:\n            - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials:\n                    account_url: https://myaccount.blob.core.windows.net/\n        ```\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    if credentials.get(\"connection_string\") is not None:\n        container_client = ContainerClient.from_connection_string(\n            credentials[\"connection_string\"], container_name=container\n        )\n    elif credentials.get(\"account_url\") is not None:\n        container_client = ContainerClient(\n            account_url=credentials[\"account_url\"],\n            container_name=container,\n            credential=DefaultAzureCredential(),\n        )\n    else:\n        raise ValueError(\n            \"Credentials must contain either connection_string or account_url\"\n        )\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    with container_client as client:\n        for local_file_path in local_path.expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(folder) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as f:\n                    client.upload_blob(str(remote_file_path), f, overwrite=True)\n\n    return {\n        \"container\": container,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-bitbucket/","title":"prefect-bitbucket","text":"<p>The prefect-bitbucket library makes it easy to interact with Bitbucket repositories and credentials.</p>"},{"location":"integrations/prefect-bitbucket/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-bitbucket/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A Bitbucket account.</li> </ul>"},{"location":"integrations/prefect-bitbucket/#install-prefect-bitbucket","title":"Install prefect-bitbucket","text":"<pre><code>pip install -U prefect-bitbucket\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-bitbucket module to make them available for use.</p> <pre><code>prefect block register -m prefect_bitbucket\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-bitbucket/#store-deployment-flow-code-in-a-private-bitbucket-repository","title":"Store deployment flow code in a private Bitbucket repository","text":"<p>To create a deployment and run a deployment where the flow code is stored in a private Bitbucket repository, you can use the <code>BitbucketCredentials</code> block.</p> <p>A deployment can use flow code stored in a Bitbucket repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Create a Bitbucket Credentials block:</p> <pre><code>from prefect_bitbucket import BitbucketCredentials\n\nbitbucket_credentials_block = BitbucketCredentials(token=\"x-token-auth:my-token\")\n\nbitbucket_credentials_block.save(name=\"my-bitbucket-credentials-block\")\n</code></pre> <p>Difference between Bitbucket Server and Bitbucket Cloud authentication</p> <p>If using a token to authenticate to Bitbucket Cloud, only set the <code>token</code> to authenticate. Do not include a value in the <code>username</code> field or authentication will fail. If using Bitbucket Server, provide both the <code>token</code> and <code>username</code> values.</p>"},{"location":"integrations/prefect-bitbucket/#access-flow-code-stored-in-a-private-bitbucket-repository-in-a-deployment","title":"Access flow code stored in a private Bitbucket repository in a deployment","text":"<p>Use the credentials block you created above to pass the Bitbucket access token during deployment creation. The code below assumes there's flow code stored in a private Bitbucket repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_bitbucket import BitbucketCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n            url=\"https://bitbucket.com/org/private-repo.git\",\n            credentials=BitbucketCredentials.load(\"my-bitbucket-credentials-block\")\n        ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-bitbucket-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the Bitbucket Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        credentials: https://bitbucket.org/org/private-repo.git\n        credentials: \"{{ prefect.blocks.bitbucket-credentials.my-bitbucket-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#interact-with-a-bitbucket-repository","title":"Interact with a Bitbucket repository","text":"<p>The code below shows how to reference a particular branch or tag of a Bitbucket repository.</p> <pre><code>from prefect_bitbucket import BitbucketRepository\n\ndef save_bitbucket_block():\n    bitbucket_block = BitbucketRepository(\n        repository=\"https://bitbucket.org/testing/my-repository.git\",\n        reference=\"branch-or-tag-name\",\n    )\n\n    bitbucket_block.save(\"my-bitbucket-block\")\n\n\nif __name__ == \"__main__\":\n    save_bitbucket_block()\n</code></pre> <p>Exclude the <code>reference</code> field to use the default branch. Reference a BitbucketCredentials block for authentication if the repository is private.</p> <p>Use the newly created block to interact with the Bitbucket repository.</p> <p>For example, download the repository contents with the <code>.get_directory()</code> method like this:</p> <pre><code>from prefect_bitbucket.repositories import BitbucketRepository\n\ndef fetch_repo():\n    bitbucket_block = BitbucketRepository.load(\"my-bitbucket-block\")\n    bitbucket_block.get_directory()\n\nif __name__ == \"__main__\":\n    fetch_repo()\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#resources","title":"Resources","text":"<p>For assistance using Bitbucket, consult the Bitbucket documentation.</p> <p>Refer to the prefect-bitbucket API documentation linked in the sidebar to explore all the capabilities of the prefect-bitbucket library.</p>"},{"location":"integrations/prefect-bitbucket/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials","title":"<code>prefect_bitbucket.credentials</code>","text":"<p>Module to enable authenticate interactions with BitBucket.</p>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.BitBucketCredentials","title":"<code>BitBucketCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Store BitBucket credentials to interact with private BitBucket repositories.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>Optional[SecretStr]</code> <p>An access token to authenticate with BitBucket. This is required for accessing private repositories.</p> <code>username</code> <code>Optional[str]</code> <p>Identification name unique across entire BitBucket site.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password to authenticate to BitBucket.</p> <code>url</code> <code>str</code> <p>The base URL of your BitBucket instance.</p> <p>Examples:</p> <p>Load stored BitBucket credentials: <pre><code>from prefect_bitbucket import BitBucketCredentials\nbitbucket_credentials_block = BitBucketCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>class BitBucketCredentials(CredentialsBlock):\n    \"\"\"Store BitBucket credentials to interact with private BitBucket repositories.\n\n    Attributes:\n        token: An access token to authenticate with BitBucket. This is required\n            for accessing private repositories.\n        username: Identification name unique across entire BitBucket site.\n        password: The password to authenticate to BitBucket.\n        url: The base URL of your BitBucket instance.\n\n\n    Examples:\n        Load stored BitBucket credentials:\n        ```python\n        from prefect_bitbucket import BitBucketCredentials\n        bitbucket_credentials_block = BitBucketCredentials.load(\"BLOCK_NAME\")\n        ```\n\n\n    \"\"\"\n\n    _block_type_name = \"BitBucket Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/5d729f7355fb6828c4b605268ded9cfafab3ae4f-250x250.png\"  # noqa\n    token: Optional[SecretStr] = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=(\n            \"A BitBucket Personal Access Token - required for private repositories.\"\n        ),\n        example=\"x-token-auth:my-token\",\n    )\n    username: Optional[str] = Field(\n        default=None,\n        description=\"Identification name unique across entire BitBucket site.\",\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password to authenticate to BitBucket.\"\n    )\n    url: str = Field(\n        default=\"https://api.bitbucket.org/\",\n        description=\"The base URL of your BitBucket instance.\",\n        title=\"URL\",\n    )\n\n    @validator(\"username\")\n    def _validate_username(cls, value: str) -&gt; str:\n        \"\"\"When username provided, will validate it.\"\"\"\n        pattern = \"^[A-Za-z0-9_-]*$\"\n\n        if not re.match(pattern, value):\n            raise ValueError(\n                \"Username must be alpha, num, dash and/or underscore only.\"\n            )\n        if not len(value) &lt;= 30:\n            raise ValueError(\"Username cannot be longer than 30 chars.\")\n        return value\n\n    def get_client(\n        self, client_type: Union[str, ClientType], **client_kwargs\n    ) -&gt; Union[Cloud, Bitbucket]:\n        \"\"\"Get an authenticated local or cloud Bitbucket client.\n\n        Args:\n            client_type: Whether to use a local or cloud client.\n\n        Returns:\n            An authenticated Bitbucket client.\n\n        \"\"\"\n        # ref: https://atlassian-python-api.readthedocs.io/\n        if isinstance(client_type, str):\n            client_type = ClientType(client_type.lower())\n\n        password = self.password.get_secret_value()\n        input_client_kwargs = dict(\n            url=self.url, username=self.username, password=password\n        )\n        input_client_kwargs.update(**client_kwargs)\n\n        if client_type == ClientType.CLOUD:\n            client = Cloud(**input_client_kwargs)\n        else:\n            client = Bitbucket(**input_client_kwargs)\n        return client\n</code></pre>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.BitBucketCredentials.get_client","title":"<code>get_client</code>","text":"<p>Get an authenticated local or cloud Bitbucket client.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>Whether to use a local or cloud client.</p> required <p>Returns:</p> Type Description <code>Union[Cloud, Bitbucket]</code> <p>An authenticated Bitbucket client.</p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>def get_client(\n    self, client_type: Union[str, ClientType], **client_kwargs\n) -&gt; Union[Cloud, Bitbucket]:\n    \"\"\"Get an authenticated local or cloud Bitbucket client.\n\n    Args:\n        client_type: Whether to use a local or cloud client.\n\n    Returns:\n        An authenticated Bitbucket client.\n\n    \"\"\"\n    # ref: https://atlassian-python-api.readthedocs.io/\n    if isinstance(client_type, str):\n        client_type = ClientType(client_type.lower())\n\n    password = self.password.get_secret_value()\n    input_client_kwargs = dict(\n        url=self.url, username=self.username, password=password\n    )\n    input_client_kwargs.update(**client_kwargs)\n\n    if client_type == ClientType.CLOUD:\n        client = Cloud(**input_client_kwargs)\n    else:\n        client = Bitbucket(**input_client_kwargs)\n    return client\n</code></pre>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.ClientType","title":"<code>ClientType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>The client type to use.</p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>class ClientType(Enum):\n    \"\"\"The client type to use.\"\"\"\n\n    LOCAL = \"local\"\n    CLOUD = \"cloud\"\n</code></pre>"},{"location":"integrations/prefect-bitbucket/repository/","title":"Repository","text":""},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository","title":"<code>prefect_bitbucket.repository</code>","text":"<p>Allows for interaction with a BitBucket repository.</p> <p>The <code>BitBucket</code> class in this collection is a storage block that lets Prefect agents pull Prefect flow code from BitBucket repositories.</p> <p>The <code>BitBucket</code> block is ideally configured via the Prefect UI, but can also be used in Python as the following examples demonstrate.</p> <p>Examples ```python from prefect_bitbucket.repository import BitBucketRepository</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--public-bitbucket-repository","title":"public BitBucket repository","text":"<p>public_bitbucket_block = BitBucketRepository(     repository=\"https://bitbucket.com/my-project/my-repository.git\" )</p> <p>public_bitbucket_block.save(name=\"my-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--specific-branch-or-tag","title":"specific branch or tag","text":"<p>branch_bitbucket_block = BitBucketRepository(     reference=\"branch-or-tag-name\",     repository=\"https://bitbucket.com/my-project/my-repository.git\" )</p> <p>branch_bitbucket_block.save(name=\"my-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--private-bitbucket-repository","title":"private BitBucket repository","text":"<p>private_bitbucket_block = BitBucketRepository(     repository=\"https://bitbucket.com/my-project/my-repository.git\",     bitbucket_credentials=BitBucketCredentials.load(\"my-bitbucket-credentials-block\") )</p> <p>private_bitbucket_block.save(name=\"my-private-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository.BitBucketRepository","title":"<code>BitBucketRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored in BitBucket repositories.</p> <p>An accessible installation of git is required for this block to function properly.</p> Source code in <code>prefect_bitbucket/repository.py</code> <pre><code>class BitBucketRepository(ReadableDeploymentStorage):\n    \"\"\"Interact with files stored in BitBucket repositories.\n\n    An accessible installation of git is required for this block to function\n    properly.\n    \"\"\"\n\n    _block_type_name = \"BitBucket Repository\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/5d729f7355fb6828c4b605268ded9cfafab3ae4f-250x250.png\"  # noqa\n    _description = \"Interact with files stored in BitBucket repositories.\"\n\n    repository: str = Field(\n        default=...,\n        description=\"The URL of a BitBucket repository to read from in HTTPS format\",\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch or tag.\",\n    )\n    bitbucket_credentials: Optional[BitBucketCredentials] = Field(\n        default=None,\n        description=(\n            \"An optional BitBucketCredentials block for authenticating with \"\n            \"private BitBucket repos.\"\n        ),\n    )\n\n    @validator(\"bitbucket_credentials\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict) -&gt; str:\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted BitBucket URLs.\n\n        Validators are by default only called on provided arguments.\n\n        Note: validates `credentials` specifically so that it only fires when private\n        repositories are used.\n        \"\"\"\n        if v is not None:\n            if urlparse(values[\"repository\"]).scheme != \"https\":\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Credentials can only be used with BitBucket repositories \"\n                        \"using the 'HTTPS' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"URL to the 'HTTPS' format.\"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos in the cloud:\n        https://x-token-auth:&lt;access-token&gt;@bitbucket.org/&lt;user&gt;/&lt;repo&gt;.git\n        For private repos with a local bitbucket server:\n        https://&lt;username&gt;:&lt;access-token&gt;@&lt;server&gt;/scm/&lt;project&gt;/&lt;repo&gt;.git\n\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urlparse(self.repository)\n        token_is_set = (\n            self.bitbucket_credentials is not None and self.bitbucket_credentials.token\n        )\n\n        # Need a token for private repos\n        if url_components.scheme == \"https\" and token_is_set:\n            token = self.bitbucket_credentials.token.get_secret_value()\n            username = self.bitbucket_credentials.username\n            if username is None:\n                username = \"x-token-auth\"\n            updated_components = url_components._replace(\n                netloc=f\"{username}:{token}@{url_components.netloc}\"\n            )\n            full_url = urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: Optional[str]\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Return the fully formed paths for BitBucketRepository contents.\n\n        Return will take the form of (content_source, content_destination).\n\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"Clones a BitBucket project within `from_path` to the provided `local_path`.\n\n        This defaults to cloning the repository reference configured on the\n        Block to the present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n\n        \"\"\"\n        # Construct command\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        cmd += [\"--depth\", \"1\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository.BitBucketRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a BitBucket project within <code>from_path</code> to the provided <code>local_path</code>.</p> <p>This defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect_bitbucket/repository.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"Clones a BitBucket project within `from_path` to the provided `local_path`.\n\n    This defaults to cloning the repository reference configured on the\n    Block to the present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n\n    \"\"\"\n    # Construct command\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    cmd += [\"--depth\", \"1\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-dask/","title":"prefect-dask","text":"<p>Dask helps you run your flow in parallel and distribute runs over multiple machines. The <code>prefect-dask</code> integration makes it easy speed up your flow runs by integrating Dask into your code.</p>"},{"location":"integrations/prefect-dask/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-dask/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> </ul>"},{"location":"integrations/prefect-dask/#install-prefect-dask","title":"Install prefect-dask","text":"<pre><code>pip install -U prefect-dask\n</code></pre>"},{"location":"integrations/prefect-dask/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Say your flow downloads many images to train a machine learning model. It can take longer than you'd like for the code to run because the code runs sequentially.</p> <p>Parallelize your flow code with <code>prefect-dask</code> in three steps:</p> <ol> <li>Add the import: <code>from prefect_dask import DaskTaskRunner</code></li> <li>Specify the task runner in the flow decorator: <code>@flow(task_runner=DaskTaskRunner)</code></li> <li>Submit tasks to the flow's task runner: <code>a_task.submit(*args, **kwargs)</code></li> </ol> <p>Below is code with and without the DaskTaskRunner:</p> SequentialParallel <pre><code># Completed in 15.2 seconds\n\nfrom typing import List\nfrom pathlib import Path\n\nimport httpx\nfrom prefect import flow, task\n\nURL_FORMAT = (\n    \"https://www.cpc.ncep.noaa.gov/products/NMME/archive/\"\n    \"{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png\"\n)\n\n@task\ndef download_image(year: int, month: int, directory: Path) -&gt; Path:\n    # download image from URL\n    url = URL_FORMAT.format(year=year, month=month)\n    resp = httpx.get(url)\n\n    # save content to directory/YYYYMM.png\n    file_path = (directory / url.split(\"/\")[-1]).with_stem(f\"{year:04d}{month:02d}\")\n    file_path.write_bytes(resp.content)\n    return file_path\n\n@flow\ndef download_nino_34_plumes_from_year(year: int) -&gt; List[Path]:\n    # create a directory to hold images\n    directory = Path(\"data\")\n    directory.mkdir(exist_ok=True)\n\n    # download all images\n    file_paths = []\n    for month in range(1, 12 + 1):\n        file_path = download_image(year, month, directory)\n        file_paths.append(file_path)\n    return file_paths\n\nif __name__ == \"__main__\":\n    download_nino_34_plumes_from_year(2022)\n</code></pre> <pre><code># Completed in 5.7 seconds\n\nfrom typing import List\nfrom pathlib import Path\n\nimport httpx\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\nURL_FORMAT = (\n    \"https://www.cpc.ncep.noaa.gov/products/NMME/archive/\"\n    \"{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png\"\n)\n\n@task\ndef download_image(year: int, month: int, directory: Path) -&gt; Path:\n    # download image from URL\n    url = URL_FORMAT.format(year=year, month=month)\n    resp = httpx.get(url)\n\n    # save content to directory/YYYYMM.png\n    file_path = (directory / url.split(\"/\")[-1]).with_stem(f\"{year:04d}{month:02d}\")\n    file_path.write_bytes(resp.content)\n    return file_path\n\n@flow(task_runner=DaskTaskRunner(cluster_kwargs={\"processes\": False}))\ndef download_nino_34_plumes_from_year(year: int) -&gt; List[Path]:\n    # create a directory to hold images\n    directory = Path(\"data\")\n    directory.mkdir(exist_ok=True)\n\n    # download all images\n    file_paths = []\n    for month in range(1, 12 + 1):\n        file_path = download_image.submit(year, month, directory)\n        file_paths.append(file_path)\n    return file_paths\n\nif __name__ == \"__main__\":\n    download_nino_34_plumes_from_year(2022)\n</code></pre> <p>In our tests, the sequential flow run took 15.2 seconds. The version with <code>DaskTaskRunner</code> reduced the runtime to 5.7 seconds!</p> <p>For additional time savings with Dask, you could distribute large workloads over multiple machines.</p>"},{"location":"integrations/prefect-dask/#integrate-with-dask-clientcluster","title":"Integrate with Dask client/cluster","text":"<p>Suppose you have an existing Dask client/cluster such as a <code>dask.dataframe.DataFrame</code>, and you want to add observability.</p> <p>With <code>prefect-dask</code>, it takes just a few steps:</p> <ol> <li>Add imports</li> <li>Add <code>task</code> and <code>flow</code> decorators</li> <li>Use <code>get_dask_client</code> context manager to distribute work across Dask workers</li> <li>Specify the task runner and client's address in the flow decorator</li> <li>Submit the tasks to the flow's task runner</li> </ol> SequentialParallel <pre><code>import dask.dataframe\nimport dask.distributed\n\n\nclient = dask.distributed.Client()\n\ndef read_data(start: str, end: str) -&gt; dask.dataframe.DataFrame:\n    df = dask.datasets.timeseries(start, end, partition_freq=\"4w\")\n    return df\n\n\ndef process_data(df: dask.dataframe.DataFrame) -&gt; dask.dataframe.DataFrame:\n\n    df_yearly_avg = df.groupby(df.index.year).mean()\n    return df_yearly_avg.compute()\n\n\ndef dask_pipeline():\n    df = read_data(\"1988\", \"2022\")\n    df_yearly_average = process_data(df)\n    return df_yearly_average\n\nif __name__ == \"__main__\":\n    dask_pipeline()\n</code></pre> <pre><code>import dask.dataframe\nimport dask.distributed\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\nclient = dask.distributed.Client()\n\n@task\ndef read_data(start: str, end: str) -&gt; dask.dataframe.DataFrame:\n    df = dask.datasets.timeseries(start, end, partition_freq=\"4w\")\n    return df\n\n@task\ndef process_data(df: dask.dataframe.DataFrame) -&gt; dask.dataframe.DataFrame:\n    with get_dask_client():\n        df_yearly_avg = df.groupby(df.index.year).mean()\n        return df_yearly_avg.compute()\n\n@flow(task_runner=DaskTaskRunner(address=client.scheduler.address))\ndef dask_pipeline():\n    df = read_data.submit(\"1988\", \"2022\")\n    df_yearly_average = process_data.submit(df)\n    return df_yearly_average\n\nif __name__ == \"__main__\":\n    dask_pipeline()\n</code></pre> <p>Run the code and check how long it takes each task to complete.</p>"},{"location":"integrations/prefect-dask/#resources","title":"Resources","text":"<p>For additional examples, check out the Usage Guide. Refer to the prefect-dask API documentation linked in the sidebar to explore all the capabilities of the prefect-dask library.</p> <p>For assistance using Dask, consult the Dask documentation.</p>"},{"location":"integrations/prefect-dask/task_runners/","title":"Task Runners","text":""},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners","title":"<code>prefect_dask.task_runners</code>","text":"<p>Interface and implementations of the Dask Task Runner. Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>import time\n\nfrom prefect import flow, task\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#0\n#1\n#2\n#3\n#4\n#5\n#6\n#7\n#8\n#9\n</code></pre> <p>Switching to a <code>DaskTaskRunner</code>: <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=DaskTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre></p>"},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners.DaskTaskRunner","title":"<code>DaskTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A parallel task_runner that submits tasks to the <code>dask.distributed</code> scheduler. By default a temporary <code>distributed.LocalCluster</code> is created (and subsequently torn down) within the <code>start()</code> contextmanager. To use a different cluster class (e.g. <code>dask_kubernetes.KubeCluster</code>), you can specify <code>cluster_class</code>/<code>cluster_kwargs</code>.</p> <p>Alternatively, if you already have a dask cluster running, you can provide the cluster object via the <code>cluster</code> kwarg or the address of the scheduler via the <code>address</code> kwarg.</p> <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or warnings will be displayed.</p> <p>Parameters:</p> Name Type Description Default <code>cluster</code> <code>Cluster</code> <p>Currently running dask cluster; if one is not provider (or specified via <code>address</code> kwarg), a temporary cluster will be created in <code>DaskTaskRunner.start()</code>. Defaults to <code>None</code>.</p> <code>None</code> <code>address</code> <code>string</code> <p>Address of a currently running dask scheduler. Defaults to <code>None</code>.</p> <code>None</code> <code>cluster_class</code> <code>string or callable</code> <p>The cluster class to use when creating a temporary dask cluster. Can be either the full class name (e.g. <code>\"distributed.LocalCluster\"</code>), or the class itself.</p> <code>None</code> <code>cluster_kwargs</code> <code>dict</code> <p>Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary dask cluster.</p> <code>None</code> <code>adapt_kwargs</code> <code>dict</code> <p>Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided.</p> <code>None</code> <code>client_kwargs</code> <code>dict</code> <p>Additional kwargs to use when creating a <code>dask.distributed.Client</code>.</p> <code>None</code> <p>Examples:</p> <p>Using a temporary local dask cluster: <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner)\ndef my_flow():\n    ...\n</code></pre></p> <p>Using a temporary cluster running elsewhere. Any Dask cluster class should work, here we use dask-cloudprovider: <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.FargateCluster\",\n    cluster_kwargs={\n        \"image\": \"prefecthq/prefect:latest\",\n        \"n_workers\": 5,\n    },\n)\n</code></pre></p> <p>Connecting to an existing dask cluster: <pre><code>DaskTaskRunner(address=\"192.0.2.255:8786\")\n</code></pre></p> Source code in <code>prefect_dask/task_runners.py</code> <pre><code>class DaskTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A parallel task_runner that submits tasks to the `dask.distributed` scheduler.\n    By default a temporary `distributed.LocalCluster` is created (and\n    subsequently torn down) within the `start()` contextmanager. To use a\n    different cluster class (e.g.\n    [`dask_kubernetes.KubeCluster`](https://kubernetes.dask.org/)), you can\n    specify `cluster_class`/`cluster_kwargs`.\n\n    Alternatively, if you already have a dask cluster running, you can provide\n    the cluster object via the `cluster` kwarg or the address of the scheduler\n    via the `address` kwarg.\n    !!! warning \"Multiprocessing safety\"\n        Note that, because the `DaskTaskRunner` uses multiprocessing, calls to flows\n        in scripts must be guarded with `if __name__ == \"__main__\":` or warnings will\n        be displayed.\n\n    Args:\n        cluster (distributed.deploy.Cluster, optional): Currently running dask cluster;\n            if one is not provider (or specified via `address` kwarg), a temporary\n            cluster will be created in `DaskTaskRunner.start()`. Defaults to `None`.\n        address (string, optional): Address of a currently running dask\n            scheduler. Defaults to `None`.\n        cluster_class (string or callable, optional): The cluster class to use\n            when creating a temporary dask cluster. Can be either the full\n            class name (e.g. `\"distributed.LocalCluster\"`), or the class itself.\n        cluster_kwargs (dict, optional): Additional kwargs to pass to the\n            `cluster_class` when creating a temporary dask cluster.\n        adapt_kwargs (dict, optional): Additional kwargs to pass to `cluster.adapt`\n            when creating a temporary dask cluster. Note that adaptive scaling\n            is only enabled if `adapt_kwargs` are provided.\n        client_kwargs (dict, optional): Additional kwargs to use when creating a\n            [`dask.distributed.Client`](https://distributed.dask.org/en/latest/api.html#client).\n\n    Examples:\n        Using a temporary local dask cluster:\n        ```python\n        from prefect import flow\n        from prefect_dask.task_runners import DaskTaskRunner\n\n        @flow(task_runner=DaskTaskRunner)\n        def my_flow():\n            ...\n        ```\n\n        Using a temporary cluster running elsewhere. Any Dask cluster class should\n        work, here we use [dask-cloudprovider](https://cloudprovider.dask.org):\n        ```python\n        DaskTaskRunner(\n            cluster_class=\"dask_cloudprovider.FargateCluster\",\n            cluster_kwargs={\n                \"image\": \"prefecthq/prefect:latest\",\n                \"n_workers\": 5,\n            },\n        )\n        ```\n\n        Connecting to an existing dask cluster:\n        ```python\n        DaskTaskRunner(address=\"192.0.2.255:8786\")\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        cluster: Optional[distributed.deploy.Cluster] = None,\n        address: str = None,\n        cluster_class: Union[str, Callable] = None,\n        cluster_kwargs: dict = None,\n        adapt_kwargs: dict = None,\n        client_kwargs: dict = None,\n    ):\n        # Validate settings and infer defaults\n        if address:\n            if cluster or cluster_class or cluster_kwargs or adapt_kwargs:\n                raise ValueError(\n                    \"Cannot specify `address` and \"\n                    \"`cluster`/`cluster_class`/`cluster_kwargs`/`adapt_kwargs`\"\n                )\n        elif cluster:\n            if cluster_class or cluster_kwargs:\n                raise ValueError(\n                    \"Cannot specify `cluster` and `cluster_class`/`cluster_kwargs`\"\n                )\n            if not cluster.asynchronous:\n                raise ValueError(\n                    \"The cluster must have `asynchronous=True` to be \"\n                    \"used with `DaskTaskRunner`.\"\n                )\n        else:\n            if isinstance(cluster_class, str):\n                cluster_class = from_qualified_name(cluster_class)\n            else:\n                cluster_class = cluster_class\n\n        # Create a copies of incoming kwargs since we may mutate them\n        cluster_kwargs = cluster_kwargs.copy() if cluster_kwargs else {}\n        adapt_kwargs = adapt_kwargs.copy() if adapt_kwargs else {}\n        client_kwargs = client_kwargs.copy() if client_kwargs else {}\n\n        # Update kwargs defaults\n        client_kwargs.setdefault(\"set_as_default\", False)\n\n        # The user cannot specify async/sync themselves\n        if \"asynchronous\" in client_kwargs:\n            raise ValueError(\n                \"`client_kwargs` cannot set `asynchronous`. \"\n                \"This option is managed by Prefect.\"\n            )\n        if \"asynchronous\" in cluster_kwargs:\n            raise ValueError(\n                \"`cluster_kwargs` cannot set `asynchronous`. \"\n                \"This option is managed by Prefect.\"\n            )\n\n        # Store settings\n        self.address = address\n        self.cluster_class = cluster_class\n        self.cluster_kwargs = cluster_kwargs\n        self.adapt_kwargs = adapt_kwargs\n        self.client_kwargs = client_kwargs\n\n        # Runtime attributes\n        self._client: \"distributed.Client\" = None\n        self._cluster: \"distributed.deploy.Cluster\" = cluster\n        self._dask_futures: Dict[str, \"distributed.Future\"] = {}\n\n        super().__init__()\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return (\n            TaskConcurrencyType.PARALLEL\n            if self.cluster_kwargs.get(\"processes\")\n            else TaskConcurrencyType.CONCURRENT\n        )\n\n    def duplicate(self):\n        \"\"\"\n        Create a new instance of the task runner with the same settings.\n        \"\"\"\n        return type(self)(\n            address=self.address,\n            cluster_class=self.cluster_class,\n            cluster_kwargs=self.cluster_kwargs,\n            adapt_kwargs=self.adapt_kwargs,\n            client_kwargs=self.client_kwargs,\n        )\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Check if an instance has the same settings as this task runner.\n        \"\"\"\n        if type(self) == type(other):\n            return (\n                self.address == other.address\n                and self.cluster_class == other.cluster_class\n                and self.cluster_kwargs == other.cluster_kwargs\n                and self.adapt_kwargs == other.adapt_kwargs\n                and self.client_kwargs == other.client_kwargs\n            )\n        else:\n            return NotImplemented\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        # unpack the upstream call in order to cast Prefect futures to Dask futures\n        # where possible to optimize Dask task scheduling\n        call_kwargs = self._optimize_futures(call.keywords)\n\n        if \"task_run\" in call_kwargs:\n            task_run = call_kwargs[\"task_run\"]\n            flow_run = FlowRunContext.get().flow_run\n            # Dask displays the text up to the first '-' as the name; the task run key\n            # should include the task run name for readability in the Dask console.\n            # For cases where the task run fails and reruns for a retried flow run,\n            # the flow run count is included so that the new key will not match\n            # the failed run's key, therefore not retrieving from the Dask cache.\n            dask_key = f\"{task_run.name}-{task_run.id.hex}-{flow_run.run_count}\"\n        else:\n            dask_key = str(key)\n\n        self._dask_futures[key] = self._client.submit(\n            call.func,\n            key=dask_key,\n            # Dask defaults to treating functions are pure, but we set this here for\n            # explicit expectations. If this task run is submitted to Dask twice, the\n            # result of the first run should be returned. Subsequent runs would return\n            # `Abort` exceptions if they were submitted again.\n            pure=True,\n            **call_kwargs,\n        )\n\n    def _get_dask_future(self, key: UUID) -&gt; \"distributed.Future\":\n        \"\"\"\n        Retrieve the dask future corresponding to a Prefect future.\n        The Dask future is for the `run_fn`, which should return a `State`.\n        \"\"\"\n        return self._dask_futures[key]\n\n    def _optimize_futures(self, expr):\n        def visit_fn(expr):\n            if isinstance(expr, PrefectFuture):\n                dask_future = self._dask_futures.get(expr.key)\n                if dask_future is not None:\n                    return dask_future\n            # Fallback to return the expression unaltered\n            return expr\n\n        return visit_collection(expr, visit_fn=visit_fn, return_data=True)\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        future = self._get_dask_future(key)\n        try:\n            return await future.result(timeout=timeout)\n        except distributed.TimeoutError:\n            return None\n        except BaseException as exc:\n            return await exception_to_crashed_state(exc)\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the task runner and prep for context exit.\n        - Creates a cluster if an external address is not set.\n        - Creates a client to connect to the cluster.\n        - Pushes a call to wait for all running futures to complete on exit.\n        \"\"\"\n\n        if self._cluster:\n            self.logger.info(f\"Connecting to existing Dask cluster {self._cluster}\")\n            self._connect_to = self._cluster\n            if self.adapt_kwargs:\n                self._cluster.adapt(**self.adapt_kwargs)\n        elif self.address:\n            self.logger.info(\n                f\"Connecting to an existing Dask cluster at {self.address}\"\n            )\n            self._connect_to = self.address\n        else:\n            self.cluster_class = self.cluster_class or distributed.LocalCluster\n\n            self.logger.info(\n                f\"Creating a new Dask cluster with \"\n                f\"`{to_qualified_name(self.cluster_class)}`\"\n            )\n            self._connect_to = self._cluster = await exit_stack.enter_async_context(\n                self.cluster_class(asynchronous=True, **self.cluster_kwargs)\n            )\n            if self.adapt_kwargs:\n                adapt_response = self._cluster.adapt(**self.adapt_kwargs)\n                if inspect.isawaitable(adapt_response):\n                    await adapt_response\n\n        self._client = await exit_stack.enter_async_context(\n            distributed.Client(\n                self._connect_to, asynchronous=True, **self.client_kwargs\n            )\n        )\n\n        if self._client.dashboard_link:\n            self.logger.info(\n                f\"The Dask dashboard is available at {self._client.dashboard_link}\",\n            )\n\n    def __getstate__(self):\n        \"\"\"\n        Allow the `DaskTaskRunner` to be serialized by dropping\n        the `distributed.Client`, which contains locks.\n        Must be deserialized on a dask worker.\n        \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_client\", \"_cluster\", \"_connect_to\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"\n        Restore the `distributed.Client` by loading the client on a dask worker.\n        \"\"\"\n        self.__dict__.update(data)\n        self._client = distributed.get_client()\n</code></pre>"},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners.DaskTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Create a new instance of the task runner with the same settings.</p> Source code in <code>prefect_dask/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Create a new instance of the task runner with the same settings.\n    \"\"\"\n    return type(self)(\n        address=self.address,\n        cluster_class=self.cluster_class,\n        cluster_kwargs=self.cluster_kwargs,\n        adapt_kwargs=self.adapt_kwargs,\n        client_kwargs=self.client_kwargs,\n    )\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/","title":"Usage Guide","text":"<p>Use <code>prefect-dask</code> to speed up code with parallelization.</p>"},{"location":"integrations/prefect-dask/usage_guide/#run-tasks-on-dask","title":"Run tasks on Dask","text":"<p>The <code>DaskTaskRunner</code> is a parallel task runner that submits tasks to the <code>dask.distributed</code> scheduler.</p> <p>By default, a temporary Dask cluster is created for the duration of the flow run.</p> <p>For example, this flow counts up to 10 in parallel (note that the output is not sequential).</p> <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=DaskTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre> <p>If you already have a Dask cluster running, either local or cloud hosted, you can provide the connection URL via an <code>address</code> argument.</p> <p>To configure your flow to use the <code>DaskTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed as described earlier: <code>pip install prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>DaskTaskRunner</code> configured to access an existing Dask cluster at <code>http://my-dask-cluster</code>.</p> <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner(address=\"http://my-dask-cluster\"))\ndef my_flow():\n    ...\n</code></pre> <p><code>DaskTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Dask scheduler. cluster_class The cluster class to use when creating a temporary Dask cluster. It can be either the full class name (for example, <code>\"distributed.LocalCluster\"</code>), or the class itself. cluster_kwargs Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary Dask cluster. adapt_kwargs Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary Dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided. client_kwargs Additional kwargs to use when creating a <code>dask.distributed.Client</code>. <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or you will encounter warnings and errors.</p> <p>If you don't provide the <code>address</code> of a Dask scheduler, Prefect creates a temporary local cluster automatically. The number of workers used is based on the number of cores available to your execution environment. The default provides a mix of processes and threads that should work well for most workloads. If you want to specify this explicitly, you can pass values for <code>n_workers</code> or <code>threads_per_worker</code> to <code>cluster_kwargs</code>.</p> <pre><code># Use 4 worker processes, each with 2 threads\nDaskTaskRunner(\n    cluster_kwargs={\"n_workers\": 4, \"threads_per_worker\": 2}\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#distributing-dask-collections-across-workers","title":"Distributing Dask collections across workers","text":"<p>If you use a Dask collection, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>, to distribute the work across workers and achieve parallel computations, use one of the context managers <code>get_dask_client</code> or <code>get_async_dask_client</code>:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\n@task\ndef compute_task():\n    with get_dask_client() as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = df.describe().compute()\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_flow():\n    prefect_future = compute_task.submit()\n    return prefect_future.result()\n\ndask_flow()\n</code></pre> <p>The context managers can be used the same way in both <code>flow</code> run contexts and <code>task</code> run contexts.</p> <p>Resolving futures in sync client</p> <p>Note, by default, <code>dask_collection.compute()</code> returns concrete values while <code>client.compute(dask_collection)</code> returns Dask Futures. Therefore, if you call <code>client.compute</code>, you must resolve all futures before exiting out of the context manager by either:</p> <ol> <li> <p>setting <code>sync=True</code> <pre><code>with get_dask_client() as client:\n    df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n    summary_df = client.compute(df.describe(), sync=True)\n</code></pre></p> </li> <li> <p>calling <code>result()</code> <pre><code>with get_dask_client() as client:\n    df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n    summary_df = client.compute(df.describe()).result()\n</code></pre> For more information, visit the docs on Waiting on Futures.</p> </li> </ol> <p>There is also an equivalent context manager for asynchronous tasks and flows: <code>get_async_dask_client</code>.</p> <pre><code>import asyncio\n\nimport dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_async_dask_client\n\n@task\nasync def compute_task():\n    async with get_async_dask_client() as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = await client.compute(df.describe())\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\nasync def dask_flow():\n    prefect_future = await compute_task.submit()\n    return await prefect_future.result()\n\nasyncio.run(dask_flow())\n</code></pre> <p>Resolving futures in async client</p> <p>With the async client, you do not need to set <code>sync=True</code> or call <code>result()</code>.</p> <p>However, you must <code>await client.compute(dask_collection)</code> before exiting the context manager.</p> <p>To invoke <code>compute</code> from the Dask collection, set <code>sync=False</code> and call <code>result()</code> before exiting out of the context manager: <code>await dask_collection.compute(sync=False)</code>.</p>"},{"location":"integrations/prefect-dask/usage_guide/#use-a-temporary-cluster","title":"Use a temporary cluster","text":"<p>The <code>DaskTaskRunner</code> is capable of creating a temporary cluster using any of Dask's cluster-manager options. This can be useful when you want each flow run to have its own Dask cluster, allowing for per-flow adaptive scaling.</p> <p>To configure, you need to provide a <code>cluster_class</code>. This can be:</p> <ul> <li>A string specifying the import path to the cluster class (for example, <code>\"dask_cloudprovider.aws.FargateCluster\"</code>)</li> <li>The cluster class itself</li> <li>A function for creating a custom cluster</li> </ul> <p>You can also configure <code>cluster_kwargs</code>, which takes a dictionary of keyword arguments to pass to <code>cluster_class</code> when starting the flow run.</p> <p>For example, to configure a flow to use a temporary <code>dask_cloudprovider.aws.FargateCluster</code> with 4 workers running with an image named <code>my-prefect-image</code>:</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    cluster_kwargs={\"n_workers\": 4, \"image\": \"my-prefect-image\"},\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#connect-to-an-existing-cluster","title":"Connect to an existing cluster","text":"<p>Multiple Prefect flow runs can all use the same existing Dask cluster. You might manage a single long-running Dask cluster (maybe using the Dask Helm Chart) and configure flows to connect to it during execution. This has a few downsides when compared to using a temporary cluster (as described above):</p> <ul> <li>All workers in the cluster must have dependencies installed for all flows you intend to run.</li> <li>Multiple flow runs may compete for resources. Dask tries to do a good job sharing resources between tasks, but you may still run into issues.</li> </ul> <p>That said, you may prefer managing a single long-running cluster.</p> <p>To configure a <code>DaskTaskRunner</code> to connect to an existing cluster, pass in the address of the scheduler to the <code>address</code> argument:</p> <pre><code># Connect to an existing cluster running at a specified address\nDaskTaskRunner(address=\"tcp://...\")\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#adaptive-scaling","title":"Adaptive scaling","text":"<p>One nice feature of using a <code>DaskTaskRunner</code> is the ability to scale adaptively to the workload. Instead of specifying <code>n_workers</code> as a fixed number, this lets you specify a minimum and maximum number of workers to use, and the dask cluster will scale up and down as needed.</p> <p>To do this, you can pass <code>adapt_kwargs</code> to <code>DaskTaskRunner</code>. This takes the following fields:</p> <ul> <li><code>maximum</code> (<code>int</code> or <code>None</code>, optional): the maximum number of workers to scale to. Set to <code>None</code> for no maximum.</li> <li><code>minimum</code> (<code>int</code> or <code>None</code>, optional): the minimum number of workers to scale to. Set to <code>None</code> for no minimum.</li> </ul> <p>For example, here we configure a flow to run on a <code>FargateCluster</code> scaling up to at most 10 workers.</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    adapt_kwargs={\"maximum\": 10}\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#dask-annotations","title":"Dask annotations","text":"<p>Dask annotations can be used to further control the behavior of tasks.</p> <p>For example, we can set the priority of tasks in the Dask scheduler:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n\n@flow(task_runner=DaskTaskRunner())\ndef my_flow():\n    with dask.annotate(priority=-10):\n        future = show(1)  # low priority task\n\n    with dask.annotate(priority=10):\n        future = show(2)  # high priority task\n</code></pre> <p>Another common use case is resource annotations:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n# Create a `LocalCluster` with some resource annotations\n# Annotations are abstract in dask and not inferred from your system.\n# Here, we claim that our system has 1 GPU and 1 process available per worker\n@flow(\n    task_runner=DaskTaskRunner(\n        cluster_kwargs={\"n_workers\": 1, \"resources\": {\"GPU\": 1, \"process\": 1}}\n    )\n)\ndef my_flow():\n    with dask.annotate(resources={'GPU': 1}):\n        future = show(0)  # this task requires 1 GPU resource on a worker\n\n    with dask.annotate(resources={'process': 1}):\n        # These tasks each require 1 process on a worker; because we've \n        # specified that our cluster has 1 process per worker and 1 worker,\n        # these tasks will run sequentially\n        future = show(1)\n        future = show(2)\n        future = show(3)\n</code></pre>"},{"location":"integrations/prefect-dask/utils/","title":"Utils","text":""},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils","title":"<code>prefect_dask.utils</code>","text":"<p>Utils to use alongside prefect-dask.</p>"},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils.get_async_dask_client","title":"<code>get_async_dask_client</code>  <code>async</code>","text":"<p>Yields a temporary asynchronous dask client; this is useful for parallelizing operations on dask collections, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p> <p>Without invoking this, workers do not automatically get a client to connect to the full cluster. Therefore, it will attempt perform work within the worker itself serially, and potentially overwhelming the single worker.</p> <p>Parameters:</p> Name Type Description Default <code>timeout</code> <code>Optional[Union[int, float, str, timedelta]]</code> <p>Timeout after which to error out; has no effect in flow run contexts because the client has already started; Defaults to the <code>distributed.comm.timeouts.connect</code> configuration value.</p> <code>None</code> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>distributed.Client</code>, and overwrites inherited keyword arguments from the task runner, if any.</p> <code>{}</code> <p>Yields:</p> Type Description <code>AsyncGenerator[Client, None]</code> <p>A temporary asynchronous dask client.</p> <p>Examples:</p> <p>Use <code>get_async_dask_client</code> to distribute work across workers. <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_async_dask_client\n\n@task\nasync def compute_task():\n    async with get_async_dask_client(timeout=\"120s\") as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = await client.compute(df.describe())\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\nasync def dask_flow():\n    prefect_future = await compute_task.submit()\n    return await prefect_future.result()\n\nasyncio.run(dask_flow())\n</code></pre></p> Source code in <code>prefect_dask/utils.py</code> <pre><code>@asynccontextmanager\nasync def get_async_dask_client(\n    timeout: Optional[Union[int, float, str, timedelta]] = None,\n    **client_kwargs: Dict[str, Any],\n) -&gt; AsyncGenerator[Client, None]:\n    \"\"\"\n    Yields a temporary asynchronous dask client; this is useful\n    for parallelizing operations on dask collections,\n    such as a `dask.DataFrame` or `dask.Bag`.\n\n    Without invoking this, workers do not automatically get a client to connect\n    to the full cluster. Therefore, it will attempt perform work within the\n    worker itself serially, and potentially overwhelming the single worker.\n\n    Args:\n        timeout: Timeout after which to error out; has no effect in\n            flow run contexts because the client has already started;\n            Defaults to the `distributed.comm.timeouts.connect`\n            configuration value.\n        client_kwargs: Additional keyword arguments to pass to\n            `distributed.Client`, and overwrites inherited keyword arguments\n            from the task runner, if any.\n\n    Yields:\n        A temporary asynchronous dask client.\n\n    Examples:\n        Use `get_async_dask_client` to distribute work across workers.\n        ```python\n        import dask\n        from prefect import flow, task\n        from prefect_dask import DaskTaskRunner, get_async_dask_client\n\n        @task\n        async def compute_task():\n            async with get_async_dask_client(timeout=\"120s\") as client:\n                df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n                summary_df = await client.compute(df.describe())\n            return summary_df\n\n        @flow(task_runner=DaskTaskRunner())\n        async def dask_flow():\n            prefect_future = await compute_task.submit()\n            return await prefect_future.result()\n\n        asyncio.run(dask_flow())\n        ```\n    \"\"\"\n    client_kwargs = _generate_client_kwargs(\n        async_client=True, timeout=timeout, **client_kwargs\n    )\n    async with Client(**client_kwargs) as client:\n        yield client\n</code></pre>"},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils.get_dask_client","title":"<code>get_dask_client</code>","text":"<p>Yields a temporary synchronous dask client; this is useful for parallelizing operations on dask collections, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p> <p>Without invoking this, workers do not automatically get a client to connect to the full cluster. Therefore, it will attempt perform work within the worker itself serially, and potentially overwhelming the single worker.</p> <p>When in an async context, we recommend using <code>get_async_dask_client</code> instead.</p> <p>Parameters:</p> Name Type Description Default <code>timeout</code> <code>Optional[Union[int, float, str, timedelta]]</code> <p>Timeout after which to error out; has no effect in flow run contexts because the client has already started; Defaults to the <code>distributed.comm.timeouts.connect</code> configuration value.</p> <code>None</code> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>distributed.Client</code>, and overwrites inherited keyword arguments from the task runner, if any.</p> <code>{}</code> <p>Yields:</p> Type Description <code>Client</code> <p>A temporary synchronous dask client.</p> <p>Examples:</p> <p>Use <code>get_dask_client</code> to distribute work across workers. <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\n@task\ndef compute_task():\n    with get_dask_client(timeout=\"120s\") as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = client.compute(df.describe()).result()\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_flow():\n    prefect_future = compute_task.submit()\n    return prefect_future.result()\n\ndask_flow()\n</code></pre></p> Source code in <code>prefect_dask/utils.py</code> <pre><code>@contextmanager\ndef get_dask_client(\n    timeout: Optional[Union[int, float, str, timedelta]] = None,\n    **client_kwargs: Dict[str, Any],\n) -&gt; Generator[Client, None, None]:\n    \"\"\"\n    Yields a temporary synchronous dask client; this is useful\n    for parallelizing operations on dask collections,\n    such as a `dask.DataFrame` or `dask.Bag`.\n\n    Without invoking this, workers do not automatically get a client to connect\n    to the full cluster. Therefore, it will attempt perform work within the\n    worker itself serially, and potentially overwhelming the single worker.\n\n    When in an async context, we recommend using `get_async_dask_client` instead.\n\n    Args:\n        timeout: Timeout after which to error out; has no effect in\n            flow run contexts because the client has already started;\n            Defaults to the `distributed.comm.timeouts.connect`\n            configuration value.\n        client_kwargs: Additional keyword arguments to pass to\n            `distributed.Client`, and overwrites inherited keyword arguments\n            from the task runner, if any.\n\n    Yields:\n        A temporary synchronous dask client.\n\n    Examples:\n        Use `get_dask_client` to distribute work across workers.\n        ```python\n        import dask\n        from prefect import flow, task\n        from prefect_dask import DaskTaskRunner, get_dask_client\n\n        @task\n        def compute_task():\n            with get_dask_client(timeout=\"120s\") as client:\n                df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n                summary_df = client.compute(df.describe()).result()\n            return summary_df\n\n        @flow(task_runner=DaskTaskRunner())\n        def dask_flow():\n            prefect_future = compute_task.submit()\n            return prefect_future.result()\n\n        dask_flow()\n        ```\n    \"\"\"\n    client_kwargs = _generate_client_kwargs(\n        async_client=False, timeout=timeout, **client_kwargs\n    )\n    with Client(**client_kwargs) as client:\n        yield client\n</code></pre>"},{"location":"integrations/prefect-databricks/","title":"prefect-databricks","text":"<p>Prefect integrations for interacting with Databricks</p> <p>The tasks within this collection were created by a code generator using the service's OpenAPI spec.</p> <p>The service's REST API documentation can be found here.</p>"},{"location":"integrations/prefect-databricks/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-databricks/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>A Databricks account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-databricks/#install-prefect-databricks","title":"Install <code>prefect-databricks</code>","text":"<pre><code>pip install prefect-databricks\n</code></pre>"},{"location":"integrations/prefect-databricks/#list-jobs-on-the-databricks-instance","title":"List jobs on the Databricks instance","text":"<pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.jobs import jobs_list\n\n\n@flow\ndef example_execute_endpoint_flow():\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n    jobs = jobs_list(\n        databricks_credentials,\n        limit=5\n    )\n    return jobs\n\nexample_execute_endpoint_flow()\n</code></pre>"},{"location":"integrations/prefect-databricks/#use-with_options-to-customize-options-on-any-existing-task-or-flow","title":"Use <code>with_options</code> to customize options on any existing task or flow","text":"<pre><code>custom_example_execute_endpoint_flow = example_execute_endpoint_flow.with_options(\n    name=\"My custom flow name\",\n    retries=2,\n    retry_delay_seconds=10,\n)\n</code></pre>"},{"location":"integrations/prefect-databricks/#launch-a-new-cluster-and-run-a-databricks-notebook","title":"Launch a new cluster and run a Databricks notebook","text":"<p>Notebook named <code>example.ipynb</code> on Databricks which accepts a name parameter:</p> <pre><code>name = dbutils.widgets.get(\"name\")\nmessage = f\"Don't worry {name}, I got your request! Welcome to prefect-databricks!\"\nprint(message)\n</code></pre> <p>Prefect flow that launches a new cluster to run <code>example.ipynb</code>:</p> <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.jobs import jobs_runs_submit\nfrom prefect_databricks.models.jobs import (\n    AutoScale,\n    AwsAttributes,\n    JobTaskSettings,\n    NotebookTask,\n    NewCluster,\n)\n\n\n@flow\ndef jobs_runs_submit_flow(notebook_path, **base_parameters):\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n\n    # specify new cluster settings\n    aws_attributes = AwsAttributes(\n        availability=\"SPOT\",\n        zone_id=\"us-west-2a\",\n        ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n        ebs_volume_count=3,\n        ebs_volume_size=100,\n    )\n    auto_scale = AutoScale(min_workers=1, max_workers=2)\n    new_cluster = NewCluster(\n        aws_attributes=aws_attributes,\n        autoscale=auto_scale,\n        node_type_id=\"m4.large\",\n        spark_version=\"10.4.x-scala2.12\",\n        spark_conf={\"spark.speculation\": True},\n    )\n\n    # specify notebook to use and parameters to pass\n    notebook_task = NotebookTask(\n        notebook_path=notebook_path,\n        base_parameters=base_parameters,\n    )\n\n    # compile job task settings\n    job_task_settings = JobTaskSettings(\n        new_cluster=new_cluster,\n        notebook_task=notebook_task,\n        task_key=\"prefect-task\"\n    )\n\n    run = jobs_runs_submit(\n        databricks_credentials=databricks_credentials,\n        run_name=\"prefect-job\",\n        tasks=[job_task_settings]\n    )\n\n    return run\n\n\njobs_runs_submit_flow(\"/Users/username@gmail.com/example.ipynb\", name=\"Marvin\")\n</code></pre> <p>Note, instead of using the built-in models, you may also input valid JSON. For example, <code>AutoScale(min_workers=1, max_workers=2)</code> is equivalent to <code>{\"min_workers\": 1, \"max_workers\": 2}</code>.</p>"},{"location":"integrations/prefect-databricks/#resources","title":"Resources","text":"<p>For assistance using Databricks, consult the Databricks documentation.</p> <p>Refer to the prefect-databricks API documentation linked in the sidebar to explore all the capabilities of the prefect-databricks library.</p>"},{"location":"integrations/prefect-databricks/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials","title":"<code>prefect_databricks.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with Databricks</p>"},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials.DatabricksCredentials","title":"<code>DatabricksCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Databricks authentication.</p> <p>Attributes:</p> Name Type Description <code>databricks_instance</code> <code>str</code> <p>Databricks instance used in formatting the endpoint URL.</p> <code>token</code> <code>SecretStr</code> <p>The token to authenticate with Databricks.</p> <code>client_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to AsyncClient.</p> <p>Examples:</p> <p>Load stored Databricks credentials: <pre><code>from prefect_databricks import DatabricksCredentials\ndatabricks_credentials_block = DatabricksCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_databricks/credentials.py</code> <pre><code>class DatabricksCredentials(Block):\n    \"\"\"\n    Block used to manage Databricks authentication.\n\n    Attributes:\n        databricks_instance:\n            Databricks instance used in formatting the endpoint URL.\n        token: The token to authenticate with Databricks.\n        client_kwargs: Additional keyword arguments to pass to AsyncClient.\n\n    Examples:\n        Load stored Databricks credentials:\n        ```python\n        from prefect_databricks import DatabricksCredentials\n        databricks_credentials_block = DatabricksCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Databricks Credentials\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5GTHI1PH2dTiantfps6Fnc/1c750fab7f4c14ea1b93a62b9fea6a94/databricks_logo_icon_170295.png?h=250\"  # noqa\n\n    databricks_instance: str = Field(\n        default=...,\n        description=\"Databricks instance used in formatting the endpoint URL.\",\n    )\n    token: SecretStr = Field(\n        default=..., description=\"The token to authenticate with Databricks.\"\n    )\n    client_kwargs: Optional[Dict[str, Any]] = Field(\n        default=None, description=\"Additional keyword arguments to pass to AsyncClient.\"\n    )\n\n    def get_client(self) -&gt; AsyncClient:\n        \"\"\"\n        Gets an Databricks REST AsyncClient.\n\n        Returns:\n            An Databricks REST AsyncClient.\n\n        Example:\n            Gets a Databricks REST AsyncClient.\n            ```python\n            from prefect import flow\n            from prefect_databricks import DatabricksCredentials\n\n            @flow\n            def example_get_client_flow():\n                token = \"consumer_key\"\n                databricks_credentials = DatabricksCredentials(token=token)\n                client = databricks_credentials.get_client()\n                return client\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        base_url = f\"https://{self.databricks_instance}/api/\"\n\n        client_kwargs = self.client_kwargs or {}\n        client_kwargs[\"headers\"] = {\n            \"Authorization\": f\"Bearer {self.token.get_secret_value()}\"\n        }\n        client = AsyncClient(base_url=base_url, **client_kwargs)\n        return client\n</code></pre>"},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials.DatabricksCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an Databricks REST AsyncClient.</p> <p>Returns:</p> Type Description <code>AsyncClient</code> <p>An Databricks REST AsyncClient.</p> Example <p>Gets a Databricks REST AsyncClient. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\n\n@flow\ndef example_get_client_flow():\n    token = \"consumer_key\"\n    databricks_credentials = DatabricksCredentials(token=token)\n    client = databricks_credentials.get_client()\n    return client\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_databricks/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncClient:\n    \"\"\"\n    Gets an Databricks REST AsyncClient.\n\n    Returns:\n        An Databricks REST AsyncClient.\n\n    Example:\n        Gets a Databricks REST AsyncClient.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n\n        @flow\n        def example_get_client_flow():\n            token = \"consumer_key\"\n            databricks_credentials = DatabricksCredentials(token=token)\n            client = databricks_credentials.get_client()\n            return client\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    base_url = f\"https://{self.databricks_instance}/api/\"\n\n    client_kwargs = self.client_kwargs or {}\n    client_kwargs[\"headers\"] = {\n        \"Authorization\": f\"Bearer {self.token.get_secret_value()}\"\n    }\n    client = AsyncClient(base_url=base_url, **client_kwargs)\n    return client\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/","title":"Flows","text":""},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows","title":"<code>prefect_databricks.flows</code>","text":"<p>Module containing flows for interacting with Databricks</p>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobInternalError","title":"<code>DatabricksJobInternalError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit encounters internal error</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobInternalError(Exception):\n    \"\"\"Raised when Databricks jobs runs submit encounters internal error\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobRunTimedOut","title":"<code>DatabricksJobRunTimedOut</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs does not complete in the configured max wait seconds</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobRunTimedOut(Exception):\n    \"\"\"\n    Raised when Databricks jobs runs does not complete in the configured max\n    wait seconds\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobSkipped","title":"<code>DatabricksJobSkipped</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit skips</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobSkipped(Exception):\n    \"\"\"Raised when Databricks jobs runs submit skips\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobTerminated","title":"<code>DatabricksJobTerminated</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit terminates</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobTerminated(Exception):\n    \"\"\"Raised when Databricks jobs runs submit terminates\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion","title":"<code>jobs_runs_submit_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>tasks</code> <code>List[RunSubmitTaskSettings]</code> <p>Tasks to run, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n    },\n]\n</code></pre></p> <code>None</code> <code>run_name</code> <code>Optional[str]</code> <p>An optional name for the run. The default value is <code>Untitled</code>, e.g. <code>A multitask job run</code>.</p> <code>None</code> <code>git_source</code> <code>Optional[GitSource]</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks. Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>return_metadata</code> <code>bool</code> <p>When True, method will return a tuple of notebook output as well as job run metadata; by default though, the method only returns notebook output</p> <code>False</code> <code>**jobs_runs_submit_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>jobs_runs_submit</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata]]</code> <p>Either a dict or a tuple (depends on <code>return_metadata</code>) comprised of</p> <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata]]</code> <ul> <li>task_notebook_outputs: dictionary of task keys to its corresponding notebook output; this is the only object returned by default from this method</li> </ul> <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata]]</code> <ul> <li>jobs_runs_metadata: dictionary containing IDs of the jobs runs tasks; this is only returned if <code>return_metadata=True</code>.</li> </ul> <p>Examples:</p> <p>Submit jobs runs and wait. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import jobs_runs_submit_and_wait_for_completion\nfrom prefect_databricks.models.jobs import (\n    AutoScale,\n    AwsAttributes,\n    JobTaskSettings,\n    NotebookTask,\n    NewCluster,\n)\n\n@flow\ndef jobs_runs_submit_and_wait_for_completion_flow(notebook_path, **base_parameters):\n    databricks_credentials = await DatabricksCredentials.load(\"BLOCK_NAME\")\n\n    # specify new cluster settings\n    aws_attributes = AwsAttributes(\n        availability=\"SPOT\",\n        zone_id=\"us-west-2a\",\n        ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n        ebs_volume_count=3,\n        ebs_volume_size=100,\n    )\n    auto_scale = AutoScale(min_workers=1, max_workers=2)\n    new_cluster = NewCluster(\n        aws_attributes=aws_attributes,\n        autoscale=auto_scale,\n        node_type_id=\"m4.large\",\n        spark_version=\"10.4.x-scala2.12\",\n        spark_conf={\"spark.speculation\": True},\n    )\n\n    # specify notebook to use and parameters to pass\n    notebook_task = NotebookTask(\n        notebook_path=notebook_path,\n        base_parameters=base_parameters,\n    )\n\n    # compile job task settings\n    job_task_settings = JobTaskSettings(\n        new_cluster=new_cluster,\n        notebook_task=notebook_task,\n        task_key=\"prefect-task\"\n    )\n\n    multi_task_runs = jobs_runs_submit_and_wait_for_completion(\n        databricks_credentials=databricks_credentials,\n        run_name=\"prefect-job\",\n        tasks=[job_task_settings]\n    )\n\n    return multi_task_runs\n</code></pre></p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Submit jobs runs and wait for completion\",\n    description=(\n        \"Triggers a Databricks jobs runs and waits for the \"\n        \"triggered runs to complete.\"\n    ),\n)\nasync def jobs_runs_submit_and_wait_for_completion(\n    databricks_credentials: DatabricksCredentials,\n    tasks: List[RunSubmitTaskSettings] = None,\n    run_name: Optional[str] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    git_source: Optional[GitSource] = None,\n    timeout_seconds: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    access_control_list: Optional[List[AccessControlRequest]] = None,\n    return_metadata: bool = False,\n    **jobs_runs_submit_kwargs: Dict[str, Any],\n) -&gt; Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata]]:\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        tasks: Tasks to run, e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                },\n            ]\n            ```\n        run_name:\n            An optional name for the run. The default value is `Untitled`, e.g. `A\n            multitask job run`.\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks. Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        access_control_list:\n            List of permissions to set on the job.\n        max_wait_seconds: Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        return_metadata: When True, method will return a tuple of notebook output as well as\n            job run metadata; by default though, the method only returns notebook output\n        **jobs_runs_submit_kwargs: Additional keyword arguments to pass to `jobs_runs_submit`.\n\n    Returns:\n        Either a dict or a tuple (depends on `return_metadata`) comprised of\n        * task_notebook_outputs: dictionary of task keys to its corresponding notebook output;\n          this is the only object returned by default from this method\n        * jobs_runs_metadata: dictionary containing IDs of the jobs runs tasks; this is only\n          returned if `return_metadata=True`.\n\n    Examples:\n        Submit jobs runs and wait.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import jobs_runs_submit_and_wait_for_completion\n        from prefect_databricks.models.jobs import (\n            AutoScale,\n            AwsAttributes,\n            JobTaskSettings,\n            NotebookTask,\n            NewCluster,\n        )\n\n        @flow\n        def jobs_runs_submit_and_wait_for_completion_flow(notebook_path, **base_parameters):\n            databricks_credentials = await DatabricksCredentials.load(\"BLOCK_NAME\")\n\n            # specify new cluster settings\n            aws_attributes = AwsAttributes(\n                availability=\"SPOT\",\n                zone_id=\"us-west-2a\",\n                ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n                ebs_volume_count=3,\n                ebs_volume_size=100,\n            )\n            auto_scale = AutoScale(min_workers=1, max_workers=2)\n            new_cluster = NewCluster(\n                aws_attributes=aws_attributes,\n                autoscale=auto_scale,\n                node_type_id=\"m4.large\",\n                spark_version=\"10.4.x-scala2.12\",\n                spark_conf={\"spark.speculation\": True},\n            )\n\n            # specify notebook to use and parameters to pass\n            notebook_task = NotebookTask(\n                notebook_path=notebook_path,\n                base_parameters=base_parameters,\n            )\n\n            # compile job task settings\n            job_task_settings = JobTaskSettings(\n                new_cluster=new_cluster,\n                notebook_task=notebook_task,\n                task_key=\"prefect-task\"\n            )\n\n            multi_task_runs = jobs_runs_submit_and_wait_for_completion(\n                databricks_credentials=databricks_credentials,\n                run_name=\"prefect-job\",\n                tasks=[job_task_settings]\n            )\n\n            return multi_task_runs\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    # submit the jobs runs\n    multi_task_jobs_runs_future = await jobs_runs_submit.submit(\n        databricks_credentials=databricks_credentials,\n        tasks=tasks,\n        run_name=run_name,\n        git_source=git_source,\n        timeout_seconds=timeout_seconds,\n        idempotency_token=idempotency_token,\n        access_control_list=access_control_list,\n        **jobs_runs_submit_kwargs,\n    )\n    multi_task_jobs_runs = await multi_task_jobs_runs_future.result()\n    multi_task_jobs_runs_id = multi_task_jobs_runs[\"run_id\"]\n\n    # wait for all the jobs runs to complete in a separate flow\n    # for a cleaner radar interface\n    jobs_runs_state, jobs_runs_metadata = await jobs_runs_wait_for_completion(\n        multi_task_jobs_runs_id=multi_task_jobs_runs_id,\n        databricks_credentials=databricks_credentials,\n        run_name=run_name,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    # fetch the state results\n    jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n    jobs_runs_state_message = jobs_runs_state[\"state_message\"]\n\n    # return results or raise error\n    if jobs_runs_life_cycle_state == RunLifeCycleState.terminated.value:\n        jobs_runs_result_state = jobs_runs_state.get(\"result_state\", None)\n        if jobs_runs_result_state == RunResultState.success.value:\n            task_notebook_outputs = {}\n            for task in jobs_runs_metadata[\"tasks\"]:\n                task_key = task[\"task_key\"]\n                task_run_id = task[\"run_id\"]\n                task_run_output_future = await jobs_runs_get_output.submit(\n                    run_id=task_run_id,\n                    databricks_credentials=databricks_credentials,\n                )\n                task_run_output = await task_run_output_future.result()\n                task_run_notebook_output = task_run_output.get(\"notebook_output\", {})\n                task_notebook_outputs[task_key] = task_run_notebook_output\n            logger.info(\n                \"Databricks Jobs Runs Submit (%s ID %s) completed successfully!\",\n                run_name,\n                multi_task_jobs_runs_id,\n            )\n            if return_metadata:\n                return task_notebook_outputs, jobs_runs_metadata\n            return task_notebook_outputs\n        else:\n            raise DatabricksJobTerminated(\n                f\"Databricks Jobs Runs Submit \"\n                f\"({run_name} ID {multi_task_jobs_runs_id}) \"\n                f\"terminated with result state, {jobs_runs_result_state}: \"\n                f\"{jobs_runs_state_message}\"\n            )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.skipped.value:\n        raise DatabricksJobSkipped(\n            f\"Databricks Jobs Runs Submit ({run_name} ID \"\n            f\"{multi_task_jobs_runs_id}) was skipped: {jobs_runs_state_message}.\",\n        )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.internalerror.value:\n        raise DatabricksJobInternalError(\n            f\"Databricks Jobs Runs Submit ({run_name} ID \"\n            f\"{multi_task_jobs_runs_id}) \"\n            f\"encountered an internal error: {jobs_runs_state_message}.\",\n        )\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_submit_by_id_and_wait_for_completion","title":"<code>jobs_runs_submit_by_id_and_wait_for_completion</code>  <code>async</code>","text":"<p>flow that triggers an existing job and waits for its completion</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>int</code> <p>Id of the databricks job.</p> required <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example \"jar_params\" : [\"john doe\", \"35\"]. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon run- now, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example {\"jar_params\": [\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example \"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The map is passed to the notebook and is accessible through the dbutils.widgets.get function. If not specified upon run-now, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params. Use Task parameter variables to set parameters containing information about job runs. The JSON representation of this field (for example {\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}) cannot exceed 10,000 bytes.</p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example \"python_params\" :[\"john doe\", \"35\"]. The parameters are passed to Python file as command- line parameters. If specified upon run-now, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes Use Task parameter variables to set parameters containing information about job runs. These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.</p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example \"spark_submit_params\": [\"--class\", \"org.apache.spark.examples.SparkPi\"]. The parameters are passed to spark-submit script as command-line parameters. If specified upon run-now, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes. Use Task parameter variables to set parameters containing information about job runs. These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.</p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example \"python_named_params\": {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}.</p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <p>If <code>full_refresh</code> is set to true, trigger a full refresh on the delta live table e.g. <pre><code>    \"pipeline_params\": {\"full_refresh\": true}\n</code></pre></p> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example \"sql_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The SQL alert task does not support custom parameters.</p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example \"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]</p> <code>None</code> <code>job_submission_handler</code> <code>Optional[Callable]</code> <p>An optional callable to intercept job submission</p> <code>None</code> <p>Raises:</p> Type Description <code>DatabricksJobTerminated</code> <p>Raised when the Databricks job run is terminated with a non-successful result state.</p> <code>DatabricksJobSkipped</code> <p>Raised when the Databricks job run is skipped.</p> <code>DatabricksJobInternalError</code> <p>Raised when the Databricks job run encounters an internal error.</p> <p>Returns:</p> Name Type Description <code>Dict</code> <code>Dict</code> <p>A dictionary containing information about the completed job run.</p> Example <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import (\n    jobs_runs_submit_by_id_and_wait_for_completion,\n)\n\n\n@flow\ndef submit_existing_job(block_name: str, job_id):\n    databricks_credentials = DatabricksCredentials.load(block_name)\n\n    run = jobs_runs_submit_by_id_and_wait_for_completion(\n        databricks_credentials=databricks_credentials, job_id=job_id\n    )\n\n    return run\n\n\nsubmit_existing_job(block_name=\"db-creds\", job_id=db_job_id)\n</code></pre> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Submit existing job runs and wait for completion\",\n    description=(\n        \"Triggers a Databricks jobs runs and waits for the \"\n        \"triggered runs to complete.\"\n    ),\n)\nasync def jobs_runs_submit_by_id_and_wait_for_completion(\n    databricks_credentials: DatabricksCredentials,\n    job_id: int,\n    idempotency_token: Optional[str] = None,\n    jar_params: Optional[List[str]] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n    job_submission_handler: Optional[Callable] = None,\n    **jobs_runs_submit_kwargs: Dict[str, Any],\n) -&gt; Dict:\n    \"\"\"flow that triggers an existing job and waits for its completion\n\n    Args:\n        databricks_credentials: Credentials to use for authentication with Databricks.\n        job_id: Id of the databricks job.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example \"jar_params\"\n            : [\"john doe\", \"35\"]. The parameters are used to invoke the main function of\n            the main class specified in the Spark JAR task. If not specified upon run-\n            now, it defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of this field (for\n            example {\"jar_params\": [\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.\n        max_wait_seconds:\n            Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            \"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The map is\n            passed to the notebook and is accessible through the dbutils.widgets.get\n            function. If not specified upon run-now, the triggered run uses the job\u2019s\n            base parameters. notebook_params cannot be specified in conjunction with\n            jar_params. Use Task parameter variables to set parameters containing\n            information about job runs. The JSON representation of this field\n            (for example {\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}) cannot\n            exceed 10,000 bytes.\n        python_params:\n            A list of parameters for jobs with Python tasks, for example \"python_params\"\n            :[\"john doe\", \"35\"]. The parameters are passed to Python file as command-\n            line parameters. If specified upon run-now, it would overwrite the\n            parameters specified in job setting. The JSON representation of this field\n            (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes\n            Use Task parameter variables to set parameters containing information\n            about job runs. These parameters accept only Latin characters (ASCII\n            character set). Using non-ASCII characters returns an error. Examples of\n            invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            \"spark_submit_params\": [\"--class\", \"org.apache.spark.examples.SparkPi\"].\n            The parameters are passed to spark-submit script as command-line parameters.\n            If specified upon run-now, it would overwrite the parameters specified in\n            job setting. The JSON representation of this field (for example\n            {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.\n            Use Task parameter variables to set parameters containing information about\n            job runs. These parameters accept only Latin characters (ASCII character\n            set). Using non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and emojis.\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            \"python_named_params\": {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}.\n        pipeline_params:\n            If `full_refresh` is set to true, trigger a full refresh on the\n            delta live table e.g.\n            ```\n                \"pipeline_params\": {\"full_refresh\": true}\n            ```\n        sql_params:\n            A map from keys to values for SQL tasks, for example \"sql_params\":\n            {\"name\": \"john doe\", \"age\": \"35\"}. The SQL alert task does not support\n            custom parameters.\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task,\n            for example \"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n        job_submission_handler: An optional callable to intercept job submission\n\n    Raises:\n        DatabricksJobTerminated:\n            Raised when the Databricks job run is terminated with a non-successful\n            result state.\n        DatabricksJobSkipped: Raised when the Databricks job run is skipped.\n        DatabricksJobInternalError:\n            Raised when the Databricks job run encounters an internal error.\n\n    Returns:\n        Dict: A dictionary containing information about the completed job run.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import (\n            jobs_runs_submit_by_id_and_wait_for_completion,\n        )\n\n\n        @flow\n        def submit_existing_job(block_name: str, job_id):\n            databricks_credentials = DatabricksCredentials.load(block_name)\n\n            run = jobs_runs_submit_by_id_and_wait_for_completion(\n                databricks_credentials=databricks_credentials, job_id=job_id\n            )\n\n            return run\n\n\n        submit_existing_job(block_name=\"db-creds\", job_id=db_job_id)\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    # submit the jobs runs\n\n    jobs_runs_future = await jobs_run_now.submit(\n        databricks_credentials=databricks_credentials,\n        job_id=job_id,\n        idempotency_token=idempotency_token,\n        jar_params=jar_params,\n        notebook_params=notebook_params,\n        python_params=python_params,\n        spark_submit_params=spark_submit_params,\n        python_named_params=python_named_params,\n        pipeline_params=pipeline_params,\n        sql_params=sql_params,\n        dbt_commands=dbt_commands,\n        **jobs_runs_submit_kwargs,\n    )\n\n    jobs_runs = await jobs_runs_future.result()\n\n    if job_submission_handler:\n        result = job_submission_handler(jobs_runs)\n        if inspect.isawaitable(result):\n            await result\n    job_run_id = jobs_runs[\"run_id\"]\n\n    # wait for all the jobs runs to complete in a separate flow\n    # for a cleaner radar interface\n    jobs_runs_state, jobs_runs_metadata = await jobs_runs_wait_for_completion(\n        multi_task_jobs_runs_id=job_run_id,\n        databricks_credentials=databricks_credentials,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    # fetch the state results\n    jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n    jobs_runs_state_message = jobs_runs_state[\"state_message\"]\n\n    # return results or raise error\n    if jobs_runs_life_cycle_state == RunLifeCycleState.terminated.value:\n        jobs_runs_result_state = jobs_runs_state.get(\"result_state\", None)\n        if jobs_runs_result_state == RunResultState.success.value:\n            task_notebook_outputs = {}\n            for task in jobs_runs_metadata[\"tasks\"]:\n                task_key = task[\"task_key\"]\n                task_run_id = task[\"run_id\"]\n                task_run_output_future = await jobs_runs_get_output.submit(\n                    run_id=task_run_id,\n                    databricks_credentials=databricks_credentials,\n                )\n                task_run_output = await task_run_output_future.result()\n                task_run_notebook_output = task_run_output.get(\"notebook_output\", {})\n                task_notebook_outputs[task_key] = task_run_notebook_output\n            logger.info(\n                f\"Databricks Jobs Runs Submit {job_id} completed successfully!\",\n            )\n            return task_notebook_outputs\n        else:\n            raise DatabricksJobTerminated(\n                f\"Databricks Jobs Runs Submit ID {job_id} \"\n                f\"terminated with result state, {jobs_runs_result_state}: \"\n                f\"{jobs_runs_state_message}\"\n            )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.skipped.value:\n        raise DatabricksJobSkipped(\n            f\"Databricks Jobs Runs Submit ID \"\n            f\"{job_id} was skipped: {jobs_runs_state_message}.\",\n        )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.internalerror.value:\n        raise DatabricksJobInternalError(\n            f\"Databricks Jobs Runs Submit ID \"\n            f\"{job_id} \"\n            f\"encountered an internal error: {jobs_runs_state_message}.\",\n        )\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_wait_for_completion","title":"<code>jobs_runs_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>run_name</code> <code>Optional[str]</code> <p>The name of the jobs runs task.</p> <code>None</code> <code>multi_task_jobs_run_id</code> <p>The ID of the jobs runs task to watch.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <p>Returns:</p> Name Type Description <code>jobs_runs_state</code> <p>A dict containing the jobs runs life cycle state and message.</p> <code>jobs_runs_metadata</code> <p>A dict containing IDs of the jobs runs tasks.</p> Example <p>Waits for completion on jobs runs. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import jobs_runs_wait_for_completion\n\n@flow\ndef jobs_runs_wait_for_completion_flow():\n    databricks_credentials = DatabricksCredentials.load(\"BLOCK_NAME\")\n    return jobs_runs_wait_for_completion(\n        multi_task_jobs_run_id=45429,\n        databricks_credentials=databricks_credentials,\n        run_name=\"my_run_name\",\n        max_wait_seconds=1800,  # 30 minutes\n        poll_frequency_seconds=120,  # 2 minutes\n    )\n</code></pre></p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Wait for completion of jobs runs\",\n    description=\"Waits for the jobs runs to finish running\",\n)\nasync def jobs_runs_wait_for_completion(\n    multi_task_jobs_runs_id: int,\n    databricks_credentials: DatabricksCredentials,\n    run_name: Optional[str] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n):\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        run_name: The name of the jobs runs task.\n        multi_task_jobs_run_id: The ID of the jobs runs task to watch.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        max_wait_seconds:\n            Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        jobs_runs_state: A dict containing the jobs runs life cycle state and message.\n        jobs_runs_metadata: A dict containing IDs of the jobs runs tasks.\n\n    Example:\n        Waits for completion on jobs runs.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import jobs_runs_wait_for_completion\n\n        @flow\n        def jobs_runs_wait_for_completion_flow():\n            databricks_credentials = DatabricksCredentials.load(\"BLOCK_NAME\")\n            return jobs_runs_wait_for_completion(\n                multi_task_jobs_run_id=45429,\n                databricks_credentials=databricks_credentials,\n                run_name=\"my_run_name\",\n                max_wait_seconds=1800,  # 30 minutes\n                poll_frequency_seconds=120,  # 2 minutes\n            )\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    seconds_waited_for_run_completion = 0\n    wait_for = []\n\n    jobs_status = {}\n    tasks_status = {}\n    while seconds_waited_for_run_completion &lt;= max_wait_seconds:\n        jobs_runs_metadata_future = await jobs_runs_get.submit(\n            run_id=multi_task_jobs_runs_id,\n            databricks_credentials=databricks_credentials,\n            wait_for=wait_for,\n        )\n        wait_for = [jobs_runs_metadata_future]\n\n        jobs_runs_metadata = await jobs_runs_metadata_future.result()\n        jobs_status = _update_and_log_state_changes(\n            jobs_status, jobs_runs_metadata, logger, \"Job\"\n        )\n        jobs_runs_metadata_tasks = jobs_runs_metadata.get(\"tasks\", [])\n        for task_metadata in jobs_runs_metadata_tasks:\n            tasks_status = _update_and_log_state_changes(\n                tasks_status, task_metadata, logger, \"Task\"\n            )\n\n        jobs_runs_state = jobs_runs_metadata.get(\"state\", {})\n        jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n        if jobs_runs_life_cycle_state in TERMINAL_STATUS_CODES:\n            return jobs_runs_state, jobs_runs_metadata\n\n        logger.info(\"Waiting for %s seconds.\", poll_frequency_seconds)\n        await asyncio.sleep(poll_frequency_seconds)\n        seconds_waited_for_run_completion += poll_frequency_seconds\n\n    raise DatabricksJobRunTimedOut(\n        f\"Max wait time of {max_wait_seconds} seconds exceeded while waiting \"\n        f\"for job run ({run_name} ID {multi_task_jobs_runs_id})\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs","title":"<code>prefect_databricks.jobs</code>","text":"<p>This is a module containing tasks for interacting with: Databricks jobs</p>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_create","title":"<code>jobs_create</code>  <code>async</code>","text":"<p>Create a new job.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>name</code> <code>str</code> <p>An optional name for the job, e.g. <code>A multitask job</code>.</p> <code>'Untitled'</code> <code>tags</code> <code>Dict</code> <p>A map of tags associated with the job. These are forwarded to the cluster as cluster tags for jobs clusters, and are subject to the same limitations as cluster tags. A maximum of 25 tags can be added to the job, e.g. <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre></p> <code>None</code> <code>tasks</code> <code>Optional[List[JobTaskSettings]]</code> <p>A list of task specifications to be executed by this job, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre></p> <code>None</code> <code>job_clusters</code> <code>Optional[List[JobCluster]]</code> <p>A list of job cluster specifications that can be shared and reused by tasks of this job. Libraries cannot be declared in a shared job cluster. You must declare dependent libraries in task settings, e.g. <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n    }\n]\n</code></pre></p> <code>None</code> <code>email_notifications</code> <code>JobEmailNotifications</code> <p>An optional set of email addresses that is notified when runs of this job begin or complete as well as when this job is deleted. The default behavior is to not send any emails. Key-values: - on_start:     A list of email addresses to be notified when a run begins.     If not specified on job creation, reset, or update, the list     is empty, and notifications are not sent, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - on_success:     A list of email addresses to be notified when a run     successfully completes. A run is considered to have     completed successfully if it ends with a <code>TERMINATED</code> <code>life_cycle_state</code> and a <code>SUCCESSFUL</code> result_state. If not     specified on job creation, reset, or update, the list is     empty, and notifications are not sent, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - on_failure:     A list of email addresses to notify when a run completes     unsuccessfully. A run is considered unsuccessful if it ends     with an <code>INTERNAL_ERROR</code> <code>life_cycle_state</code> or a <code>SKIPPED</code>,     <code>FAILED</code>, or <code>TIMED_OUT</code> <code>result_state</code>. If not specified on     job creation, reset, or update, or the list is empty, then     notifications are not sent. Job-level failure notifications     are sent only once after the entire job run (including all     of its retries) has failed. Notifications are not sent when     failed job runs are retried. To receive a failure     notification after every failed task (including every failed     retry), use task-level notifications instead, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - no_alert_for_skipped_runs:     If true, do not send email to recipients specified in     <code>on_failure</code> if the run is skipped.</p> <code>None</code> <code>webhook_notifications</code> <code>WebhookNotifications</code> <p>A collection of system notification IDs to notify when runs of this job begin or complete. The default behavior is to not send any system notifications. Key-values: - on_start:     An optional list of notification IDs to call when the run     starts. A maximum of 3 destinations can be specified for the     <code>on_start</code> property, e.g.     <pre><code>[\n    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n]\n</code></pre> - on_success:     An optional list of notification IDs to call when the run     completes successfully. A maximum of 3 destinations can be     specified for the <code>on_success</code> property, e.g.     <pre><code>[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n</code></pre> - on_failure:     An optional list of notification IDs to call when the run     fails. A maximum of 3 destinations can be specified for the     <code>on_failure</code> property, e.g.     <pre><code>[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n</code></pre></p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>schedule</code> <code>CronSchedule</code> <p>An optional periodic schedule for this job. The default behavior is that the job only runs when triggered by clicking \u201cRun Now\u201d in the Jobs UI or sending an API request to <code>runNow</code>. Key-values: - quartz_cron_expression:     A Cron expression using Quartz syntax that describes the     schedule for a job. See Cron Trigger     for details. This field is required, e.g. <code>20 30 * * * ?</code>. - timezone_id:     A Java timezone ID. The schedule for a job is resolved with     respect to this timezone. See Java     TimeZone     for details. This field is required, e.g. <code>Europe/London</code>. - pause_status:     Indicate whether this schedule is paused or not, e.g.     <code>PAUSED</code>.</p> <code>None</code> <code>max_concurrent_runs</code> <code>Optional[int]</code> <p>An optional maximum allowed number of concurrent runs of the job.  Set this value if you want to be able to execute multiple runs of the same job concurrently. This is useful for example if you trigger your job on a frequent schedule and want to allow consecutive runs to overlap with each other, or if you want to trigger multiple runs which differ by their input parameters.  This setting affects only new runs. For example, suppose the job\u2019s concurrency is 4 and there are 4 concurrent active runs. Then setting the concurrency to 3 won\u2019t kill any of the active runs. However, from then on, new runs are skipped unless there are fewer than 3 active runs.  This value cannot exceed 1000. Setting this value to 0 causes all new runs to be skipped. The default behavior is to allow only 1 concurrent run, e.g. <code>10</code>.</p> <code>None</code> <code>git_source</code> <code>GitSource</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks, e.g. <code>{     \"git_url\": \"https://github.com/databricks/databricks-cli\",     \"git_branch\": \"main\",     \"git_provider\": \"gitHub\", }</code> Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>format</code> <code>Optional[str]</code> <p>Used to tell what is the format of the job. This field is ignored in Create/Update/Reset calls. When using the Jobs API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g. <code>MULTI_TASK</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/create</code></p> API Responses: Response Description 200 Job was created successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_create(\n    databricks_credentials: \"DatabricksCredentials\",\n    name: str = \"Untitled\",\n    tags: Dict = None,\n    tasks: Optional[List[\"models.JobTaskSettings\"]] = None,\n    job_clusters: Optional[List[\"models.JobCluster\"]] = None,\n    email_notifications: \"models.JobEmailNotifications\" = None,\n    webhook_notifications: \"models.WebhookNotifications\" = None,\n    timeout_seconds: Optional[int] = None,\n    schedule: \"models.CronSchedule\" = None,\n    max_concurrent_runs: Optional[int] = None,\n    git_source: \"models.GitSource\" = None,\n    format: Optional[str] = None,\n    access_control_list: Optional[List[\"models.AccessControlRequest\"]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Create a new job.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        name:\n            An optional name for the job, e.g. `A multitask job`.\n        tags:\n            A map of tags associated with the job. These are forwarded to the\n            cluster as cluster tags for jobs clusters, and are subject\n            to the same limitations as cluster tags. A maximum of 25\n            tags can be added to the job, e.g.\n            ```\n            {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n            ```\n        tasks:\n            A list of task specifications to be executed by this job, e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"job_cluster_key\": \"auto_scaling_cluster\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"source\": \"WORKSPACE\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n            ]\n            ```\n        job_clusters:\n            A list of job cluster specifications that can be shared and reused by\n            tasks of this job. Libraries cannot be declared in a shared\n            job cluster. You must declare dependent libraries in task\n            settings, e.g.\n            ```\n            [\n                {\n                    \"job_cluster_key\": \"auto_scaling_cluster\",\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                }\n            ]\n            ```\n        email_notifications:\n            An optional set of email addresses that is notified when runs of this\n            job begin or complete as well as when this job is deleted.\n            The default behavior is to not send any emails. Key-values:\n            - on_start:\n                A list of email addresses to be notified when a run begins.\n                If not specified on job creation, reset, or update, the list\n                is empty, and notifications are not sent, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - on_success:\n                A list of email addresses to be notified when a run\n                successfully completes. A run is considered to have\n                completed successfully if it ends with a `TERMINATED`\n                `life_cycle_state` and a `SUCCESSFUL` result_state. If not\n                specified on job creation, reset, or update, the list is\n                empty, and notifications are not sent, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - on_failure:\n                A list of email addresses to notify when a run completes\n                unsuccessfully. A run is considered unsuccessful if it ends\n                with an `INTERNAL_ERROR` `life_cycle_state` or a `SKIPPED`,\n                `FAILED`, or `TIMED_OUT` `result_state`. If not specified on\n                job creation, reset, or update, or the list is empty, then\n                notifications are not sent. Job-level failure notifications\n                are sent only once after the entire job run (including all\n                of its retries) has failed. Notifications are not sent when\n                failed job runs are retried. To receive a failure\n                notification after every failed task (including every failed\n                retry), use task-level notifications instead, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - no_alert_for_skipped_runs:\n                If true, do not send email to recipients specified in\n                `on_failure` if the run is skipped.\n        webhook_notifications:\n            A collection of system notification IDs to notify when runs of this job\n            begin or complete. The default behavior is to not send any\n            system notifications. Key-values:\n            - on_start:\n                An optional list of notification IDs to call when the run\n                starts. A maximum of 3 destinations can be specified for the\n                `on_start` property, e.g.\n                ```\n                [\n                    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n                    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n                ]\n                ```\n            - on_success:\n                An optional list of notification IDs to call when the run\n                completes successfully. A maximum of 3 destinations can be\n                specified for the `on_success` property, e.g.\n                ```\n                [{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n                ```\n            - on_failure:\n                An optional list of notification IDs to call when the run\n                fails. A maximum of 3 destinations can be specified for the\n                `on_failure` property, e.g.\n                ```\n                [{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n                ```\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        schedule:\n            An optional periodic schedule for this job. The default behavior is that\n            the job only runs when triggered by clicking \u201cRun Now\u201d in\n            the Jobs UI or sending an API request to `runNow`. Key-values:\n            - quartz_cron_expression:\n                A Cron expression using Quartz syntax that describes the\n                schedule for a job. See [Cron Trigger](http://www.quartz-\n                scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)\n                for details. This field is required, e.g. `20 30 * * * ?`.\n            - timezone_id:\n                A Java timezone ID. The schedule for a job is resolved with\n                respect to this timezone. See [Java\n                TimeZone](https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html)\n                for details. This field is required, e.g. `Europe/London`.\n            - pause_status:\n                Indicate whether this schedule is paused or not, e.g.\n                `PAUSED`.\n        max_concurrent_runs:\n            An optional maximum allowed number of concurrent runs of the job.  Set\n            this value if you want to be able to execute multiple runs\n            of the same job concurrently. This is useful for example if\n            you trigger your job on a frequent schedule and want to\n            allow consecutive runs to overlap with each other, or if you\n            want to trigger multiple runs which differ by their input\n            parameters.  This setting affects only new runs. For\n            example, suppose the job\u2019s concurrency is 4 and there are 4\n            concurrent active runs. Then setting the concurrency to 3\n            won\u2019t kill any of the active runs. However, from then on,\n            new runs are skipped unless there are fewer than 3 active\n            runs.  This value cannot exceed 1000\\. Setting this value to\n            0 causes all new runs to be skipped. The default behavior is\n            to allow only 1 concurrent run, e.g. `10`.\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks, e.g.\n            ```\n            {\n                \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                \"git_branch\": \"main\",\n                \"git_provider\": \"gitHub\",\n            }\n            ``` Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        format:\n            Used to tell what is the format of the job. This field is ignored in\n            Create/Update/Reset calls. When using the Jobs API 2.1 this\n            value is always set to `'MULTI_TASK'`, e.g. `MULTI_TASK`.\n        access_control_list:\n            List of permissions to set on the job.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/create`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was created successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/create\"  # noqa\n\n    responses = {\n        200: \"Job was created successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"name\": name,\n        \"tags\": tags,\n        \"tasks\": tasks,\n        \"job_clusters\": job_clusters,\n        \"email_notifications\": email_notifications,\n        \"webhook_notifications\": webhook_notifications,\n        \"timeout_seconds\": timeout_seconds,\n        \"schedule\": schedule,\n        \"max_concurrent_runs\": max_concurrent_runs,\n        \"git_source\": git_source,\n        \"format\": format,\n        \"access_control_list\": access_control_list,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_delete","title":"<code>jobs_delete</code>  <code>async</code>","text":"<p>Deletes a job.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to delete. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/delete</code></p> API Responses: Response Description 200 Job was deleted successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_delete(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deletes a job.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to delete. This field is required,\n            e.g. `11223344`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/delete`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was deleted successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/delete\"  # noqa\n\n    responses = {\n        200: \"Job was deleted successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_get","title":"<code>jobs_get</code>  <code>async</code>","text":"<p>Retrieves the details for a single job.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>The canonical identifier of the job to retrieve information about. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code>- <code>creator_user_name: str</code>- <code>run_as_user_name: str</code>- <code>settings: \"models.JobSettings\"</code>- <code>created_time: int</code></p> API Endpoint: <p><code>/2.1/jobs/get</code></p> API Responses: Response Description 200 Job was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_get(\n    job_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieves the details for a single job.\n\n    Args:\n        job_id:\n            The canonical identifier of the job to retrieve information about. This\n            field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;- `creator_user_name: str`&lt;/br&gt;- `run_as_user_name: str`&lt;/br&gt;- `settings: \"models.JobSettings\"`&lt;/br&gt;- `created_time: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/get`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/get\"  # noqa\n\n    responses = {\n        200: \"Job was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_list","title":"<code>jobs_list</code>  <code>async</code>","text":"<p>Retrieves a list of jobs.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>limit</code> <code>int</code> <p>The number of jobs to return. This value must be greater than 0 and less or equal to 25. The default value is 20.</p> <code>20</code> <code>offset</code> <code>int</code> <p>The offset of the first job to return, relative to the most recently created job.</p> <code>0</code> <code>name</code> <code>Optional[str]</code> <p>A filter on the list based on the exact (case insensitive) job name.</p> <code>None</code> <code>expand_tasks</code> <code>bool</code> <p>Whether to include task and cluster details in the response.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>jobs: List[\"models.Job\"]</code>- <code>has_more: bool</code></p> API Endpoint: <p><code>/2.1/jobs/list</code></p> API Responses: Response Description 200 List of jobs was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_list(\n    databricks_credentials: \"DatabricksCredentials\",\n    limit: int = 20,\n    offset: int = 0,\n    name: Optional[str] = None,\n    expand_tasks: bool = False,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieves a list of jobs.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        limit:\n            The number of jobs to return. This value must be greater than 0 and less\n            or equal to 25. The default value is 20.\n        offset:\n            The offset of the first job to return, relative to the most recently\n            created job.\n        name:\n            A filter on the list based on the exact (case insensitive) job name.\n        expand_tasks:\n            Whether to include task and cluster details in the response.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `jobs: List[\"models.Job\"]`&lt;/br&gt;- `has_more: bool`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/list`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | List of jobs was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/list\"  # noqa\n\n    responses = {\n        200: \"List of jobs was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"limit\": limit,\n        \"offset\": offset,\n        \"name\": name,\n        \"expand_tasks\": expand_tasks,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_reset","title":"<code>jobs_reset</code>  <code>async</code>","text":"<p>Overwrites all the settings for a specific job. Use the Update endpoint to update job settings partially.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to reset. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <code>new_settings</code> <code>JobSettings</code> <p>The new settings of the job. These settings completely replace the old settings.  Changes to the field <code>JobSettings.timeout_seconds</code> are applied to active runs. Changes to other fields are applied to future runs only. Key-values: - name:     An optional name for the job, e.g. <code>A multitask job</code>. - tags:     A map of tags associated with the job. These are forwarded     to the cluster as cluster tags for jobs clusters, and are     subject to the same limitations as cluster tags. A maximum     of 25 tags can be added to the job, e.g.     <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre> - tasks:     A list of task specifications to be executed by this job, e.g.     <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/order-data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\n                \"name\": \"John Doe\",\n                \"age\": \"35\",\n            },\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre> - job_clusters:     A list of job cluster specifications that can be shared and     reused by tasks of this job. Libraries cannot be declared in     a shared job cluster. You must declare dependent libraries     in task settings, e.g.     <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n    }\n]\n</code></pre> - email_notifications:     An optional set of email addresses that is notified when     runs of this job begin or complete as well as when this job     is deleted. The default behavior is to not send any emails. - webhook_notifications:     A collection of system notification IDs to notify when runs     of this job begin or complete. The default behavior is to     not send any system notifications. - timeout_seconds:     An optional timeout applied to each run of this job. The     default behavior is to have no timeout, e.g. <code>86400</code>. - schedule:     An optional periodic schedule for this job. The default     behavior is that the job only runs when triggered by     clicking \u201cRun Now\u201d in the Jobs UI or sending an API request     to <code>runNow</code>. - max_concurrent_runs:     An optional maximum allowed number of concurrent runs of the     job.  Set this value if you want to be able to execute     multiple runs of the same job concurrently. This is useful     for example if you trigger your job on a frequent schedule     and want to allow consecutive runs to overlap with each     other, or if you want to trigger multiple runs which differ     by their input parameters.  This setting affects only new     runs. For example, suppose the job\u2019s concurrency is 4 and     there are 4 concurrent active runs. Then setting the     concurrency to 3 won\u2019t kill any of the active runs. However,     from then on, new runs are skipped unless there are fewer     than 3 active runs.  This value cannot exceed 1000. Setting     this value to 0 causes all new runs to be skipped. The     default behavior is to allow only 1 concurrent run, e.g.     <code>10</code>. - git_source:     This functionality is in Public Preview.  An optional     specification for a remote repository containing the     notebooks used by this job's notebook tasks, e.g.     <pre><code>{\n    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n    \"git_branch\": \"main\",\n    \"git_provider\": \"gitHub\",\n}\n</code></pre> - format:     Used to tell what is the format of the job. This field is     ignored in Create/Update/Reset calls. When using the Jobs     API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g.     <code>MULTI_TASK</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/reset</code></p> API Responses: Response Description 200 Job was overwritten successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_reset(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    new_settings: \"models.JobSettings\" = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Overwrites all the settings for a specific job. Use the Update endpoint to\n    update job settings partially.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to reset. This field is required,\n            e.g. `11223344`.\n        new_settings:\n            The new settings of the job. These settings completely replace the old\n            settings.  Changes to the field\n            `JobSettings.timeout_seconds` are applied to active runs.\n            Changes to other fields are applied to future runs only. Key-values:\n            - name:\n                An optional name for the job, e.g. `A multitask job`.\n            - tags:\n                A map of tags associated with the job. These are forwarded\n                to the cluster as cluster tags for jobs clusters, and are\n                subject to the same limitations as cluster tags. A maximum\n                of 25 tags can be added to the job, e.g.\n                ```\n                {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n                ```\n            - tasks:\n                A list of task specifications to be executed by this job, e.g.\n                ```\n                [\n                    {\n                        \"task_key\": \"Sessionize\",\n                        \"description\": \"Extracts session data from events\",\n                        \"depends_on\": [],\n                        \"existing_cluster_id\": \"0923-164208-meows279\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.Sessionize\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Orders_Ingest\",\n                        \"description\": \"Ingests order data\",\n                        \"depends_on\": [],\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.OrdersIngest\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/order-data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Match\",\n                        \"description\": \"Matches orders with user sessions\",\n                        \"depends_on\": [\n                            {\"task_key\": \"Orders_Ingest\"},\n                            {\"task_key\": \"Sessionize\"},\n                        ],\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                        \"notebook_task\": {\n                            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                            \"source\": \"WORKSPACE\",\n                            \"base_parameters\": {\n                                \"name\": \"John Doe\",\n                                \"age\": \"35\",\n                            },\n                        },\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                ]\n                ```\n            - job_clusters:\n                A list of job cluster specifications that can be shared and\n                reused by tasks of this job. Libraries cannot be declared in\n                a shared job cluster. You must declare dependent libraries\n                in task settings, e.g.\n                ```\n                [\n                    {\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                    }\n                ]\n                ```\n            - email_notifications:\n                An optional set of email addresses that is notified when\n                runs of this job begin or complete as well as when this job\n                is deleted. The default behavior is to not send any emails.\n            - webhook_notifications:\n                A collection of system notification IDs to notify when runs\n                of this job begin or complete. The default behavior is to\n                not send any system notifications.\n            - timeout_seconds:\n                An optional timeout applied to each run of this job. The\n                default behavior is to have no timeout, e.g. `86400`.\n            - schedule:\n                An optional periodic schedule for this job. The default\n                behavior is that the job only runs when triggered by\n                clicking \u201cRun Now\u201d in the Jobs UI or sending an API request\n                to `runNow`.\n            - max_concurrent_runs:\n                An optional maximum allowed number of concurrent runs of the\n                job.  Set this value if you want to be able to execute\n                multiple runs of the same job concurrently. This is useful\n                for example if you trigger your job on a frequent schedule\n                and want to allow consecutive runs to overlap with each\n                other, or if you want to trigger multiple runs which differ\n                by their input parameters.  This setting affects only new\n                runs. For example, suppose the job\u2019s concurrency is 4 and\n                there are 4 concurrent active runs. Then setting the\n                concurrency to 3 won\u2019t kill any of the active runs. However,\n                from then on, new runs are skipped unless there are fewer\n                than 3 active runs.  This value cannot exceed 1000\\. Setting\n                this value to 0 causes all new runs to be skipped. The\n                default behavior is to allow only 1 concurrent run, e.g.\n                `10`.\n            - git_source:\n                This functionality is in Public Preview.  An optional\n                specification for a remote repository containing the\n                notebooks used by this job's notebook tasks, e.g.\n                ```\n                {\n                    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                    \"git_branch\": \"main\",\n                    \"git_provider\": \"gitHub\",\n                }\n                ```\n            - format:\n                Used to tell what is the format of the job. This field is\n                ignored in Create/Update/Reset calls. When using the Jobs\n                API 2.1 this value is always set to `'MULTI_TASK'`, e.g.\n                `MULTI_TASK`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/reset`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was overwritten successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/reset\"  # noqa\n\n    responses = {\n        200: \"Job was overwritten successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"new_settings\": new_settings,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_run_now","title":"<code>jobs_run_now</code>  <code>async</code>","text":"<p>Run a job and return the <code>run_id</code> of the triggered run.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The ID of the job to be executed, e.g. <code>11223344</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token.  This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example <code>'jar_params': ['john doe', '35']</code>. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon <code>run-now</code>, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example <code>{'jar_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs, e.g. <pre><code>[\"john\", \"doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example <code>'notebook_params': {'name': 'john doe', 'age': '35'}</code>. The map is passed to the notebook and is accessible through the dbutils.widgets.get function.  If not specified upon <code>run-now</code>, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params.  Use Task parameter variables to set parameters containing information about job runs.  The JSON representation of this field (for example <code>{'notebook_params':{'name':'john doe','age':'35'}}</code>) cannot exceed 10,000 bytes, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example <code>'python_params': ['john doe', '35']</code>. The parameters are passed to Python file as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"john doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example <code>'spark_submit_params': ['--class', 'org.apache.spark.examples.SparkPi']</code>. The parameters are passed to spark-submit script as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"--class\", \"org.apache.spark.examples.SparkPi\"]\n</code></pre></p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example <code>'python_named_params': {'name': 'task', 'data': 'dbfs:/path/to/data.json'}</code>, e.g. <pre><code>{\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n</code></pre></p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example <code>'sql_params': {'name': 'john doe', 'age': '35'}</code>. The SQL alert task does not support custom parameters, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example <code>'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']</code>, e.g. <pre><code>[\"dbt deps\", \"dbt seed\", \"dbt run\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>run_id: int</code>- <code>number_in_job: int</code></p> API Endpoint: <p><code>/2.1/jobs/run-now</code></p> API Responses: Response Description 200 Run was started successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_run_now(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    jar_params: Optional[List[str]] = None,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Run a job and return the `run_id` of the triggered run.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The ID of the job to be executed, e.g. `11223344`.\n        idempotency_token:\n            An optional token to guarantee the idempotency of job run requests. If a\n            run with the provided token already exists, the request does\n            not create a new run but returns the ID of the existing run\n            instead. If a run with the provided token is deleted, an\n            error is returned.  If you specify the idempotency token,\n            upon failure you can retry until the request succeeds.\n            Databricks guarantees that exactly one run is launched with\n            that idempotency token.  This token must have at most 64\n            characters.  For more information, see [How to ensure\n            idempotency for jobs](https://kb.databricks.com/jobs/jobs-\n            idempotency.html), e.g.\n            `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example\n            `'jar_params': ['john doe', '35']`. The parameters are used\n            to invoke the main function of the main class specified in\n            the Spark JAR task. If not specified upon `run-now`, it\n            defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of\n            this field (for example `{'jar_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs, e.g.\n            ```\n            [\"john\", \"doe\", \"35\"]\n            ```\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            `'notebook_params': {'name': 'john doe', 'age': '35'}`. The\n            map is passed to the notebook and is accessible through the\n            [dbutils.widgets.get](https://docs.databricks.com/dev-\n            tools/databricks-utils.html\n            dbutils-widgets) function.  If not specified upon `run-now`,\n            the triggered run uses the job\u2019s base parameters.\n            notebook_params cannot be specified in conjunction with\n            jar_params.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  The JSON representation of this\n            field (for example `{'notebook_params':{'name':'john\n            doe','age':'35'}}`) cannot exceed 10,000 bytes, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        python_params:\n            A list of parameters for jobs with Python tasks, for example\n            `'python_params': ['john doe', '35']`. The parameters are\n            passed to Python file as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"john doe\", \"35\"]\n            ```\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            `'spark_submit_params': ['--class',\n            'org.apache.spark.examples.SparkPi']`. The parameters are\n            passed to spark-submit script as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"--class\", \"org.apache.spark.examples.SparkPi\"]\n            ```\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            `'python_named_params': {'name': 'task', 'data':\n            'dbfs:/path/to/data.json'}`, e.g.\n            ```\n            {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n            ```\n        pipeline_params:\n\n        sql_params:\n            A map from keys to values for SQL tasks, for example `'sql_params':\n            {'name': 'john doe', 'age': '35'}`. The SQL alert task does\n            not support custom parameters, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task, for example\n            `'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']`, e.g.\n            ```\n            [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n            ```\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `run_id: int`&lt;/br&gt;- `number_in_job: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/run-now`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was started successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/run-now\"  # noqa\n\n    responses = {\n        200: \"Run was started successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"idempotency_token\": idempotency_token,\n        \"jar_params\": jar_params,\n        \"notebook_params\": notebook_params,\n        \"python_params\": python_params,\n        \"spark_submit_params\": spark_submit_params,\n        \"python_named_params\": python_named_params,\n        \"pipeline_params\": pipeline_params,\n        \"sql_params\": sql_params,\n        \"dbt_commands\": dbt_commands,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_cancel","title":"<code>jobs_runs_cancel</code>  <code>async</code>","text":"<p>Cancels a job run. The run is canceled asynchronously, so it may still be running when this request completes.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>This field is required, e.g. <code>455644833</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/cancel</code></p> API Responses: Response Description 200 Run was cancelled successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_cancel(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Cancels a job run. The run is canceled asynchronously, so it may still be\n    running when this request completes.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            This field is required, e.g. `455644833`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/cancel`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was cancelled successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/cancel\"  # noqa\n\n    responses = {\n        200: \"Run was cancelled successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_cancel_all","title":"<code>jobs_runs_cancel_all</code>  <code>async</code>","text":"<p>Cancels all active runs of a job. The runs are canceled asynchronously, so it doesn't prevent new runs from being started.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to cancel all runs of. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/cancel-all</code></p> API Responses: Response Description 200 All runs were cancelled successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_cancel_all(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Cancels all active runs of a job. The runs are canceled asynchronously, so it\n    doesn't prevent new runs from being started.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to cancel all runs of. This field is\n            required, e.g. `11223344`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/cancel-all`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | All runs were cancelled successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/cancel-all\"  # noqa\n\n    responses = {\n        200: \"All runs were cancelled successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_delete","title":"<code>jobs_runs_delete</code>  <code>async</code>","text":"<p>Deletes a non-active run. Returns an error if the run is active.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>The canonical identifier of the run for which to retrieve the metadata, e.g. <code>455644833</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/delete</code></p> API Responses: Response Description 200 Run was deleted successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_delete(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deletes a non-active run. Returns an error if the run is active.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            The canonical identifier of the run for which to retrieve the metadata,\n            e.g. `455644833`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/delete`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was deleted successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/delete\"  # noqa\n\n    responses = {\n        200: \"Run was deleted successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_export","title":"<code>jobs_runs_export</code>  <code>async</code>","text":"<p>Export and retrieve the job run task.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier for the run. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>views_to_export</code> <code>Optional[ViewsToExport]</code> <p>Which views to export (CODE, DASHBOARDS, or ALL). Defaults to CODE.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>views: List[\"models.ViewItem\"]</code></p> API Endpoint: <p><code>/2.0/jobs/runs/export</code></p> API Responses: Response Description 200 Run was exported successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_export(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n    views_to_export: Optional[\"models.ViewsToExport\"] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Export and retrieve the job run task.\n\n    Args:\n        run_id:\n            The canonical identifier for the run. This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        views_to_export:\n            Which views to export (CODE, DASHBOARDS, or ALL). Defaults to CODE.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `views: List[\"models.ViewItem\"]`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.0/jobs/runs/export`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was exported successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.0/jobs/runs/export\"  # noqa\n\n    responses = {\n        200: \"Run was exported successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n        \"views_to_export\": views_to_export,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_get","title":"<code>jobs_runs_get</code>  <code>async</code>","text":"<p>Retrieve the metadata of a run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier of the run for which to retrieve the metadata. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>include_history</code> <code>Optional[bool]</code> <p>Whether to include the repair history in the response.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code>- <code>run_id: int</code>- <code>number_in_job: int</code>- <code>creator_user_name: str</code>- <code>original_attempt_run_id: int</code>- <code>state: \"models.RunState\"</code>- <code>schedule: \"models.CronSchedule\"</code>- <code>tasks: List[\"models.RunTask\"]</code>- <code>job_clusters: List[\"models.JobCluster\"]</code>- <code>cluster_spec: \"models.ClusterSpec\"</code>- <code>cluster_instance: \"models.ClusterInstance\"</code>- <code>git_source: \"models.GitSource\"</code>- <code>overriding_parameters: \"models.RunParameters\"</code>- <code>start_time: int</code>- <code>setup_duration: int</code>- <code>execution_duration: int</code>- <code>cleanup_duration: int</code>- <code>end_time: int</code>- <code>trigger: \"models.TriggerType\"</code>- <code>run_name: str</code>- <code>run_page_url: str</code>- <code>run_type: \"models.RunType\"</code>- <code>attempt_number: int</code>- <code>repair_history: List[\"models.RepairHistoryItem\"]</code></p> API Endpoint: <p><code>/2.1/jobs/runs/get</code></p> API Responses: Response Description 200 Run was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_get(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n    include_history: Optional[bool] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieve the metadata of a run.\n\n    Args:\n        run_id:\n            The canonical identifier of the run for which to retrieve the metadata.\n            This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        include_history:\n            Whether to include the repair history in the response.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;- `run_id: int`&lt;/br&gt;- `number_in_job: int`&lt;/br&gt;- `creator_user_name: str`&lt;/br&gt;- `original_attempt_run_id: int`&lt;/br&gt;- `state: \"models.RunState\"`&lt;/br&gt;- `schedule: \"models.CronSchedule\"`&lt;/br&gt;- `tasks: List[\"models.RunTask\"]`&lt;/br&gt;- `job_clusters: List[\"models.JobCluster\"]`&lt;/br&gt;- `cluster_spec: \"models.ClusterSpec\"`&lt;/br&gt;- `cluster_instance: \"models.ClusterInstance\"`&lt;/br&gt;- `git_source: \"models.GitSource\"`&lt;/br&gt;- `overriding_parameters: \"models.RunParameters\"`&lt;/br&gt;- `start_time: int`&lt;/br&gt;- `setup_duration: int`&lt;/br&gt;- `execution_duration: int`&lt;/br&gt;- `cleanup_duration: int`&lt;/br&gt;- `end_time: int`&lt;/br&gt;- `trigger: \"models.TriggerType\"`&lt;/br&gt;- `run_name: str`&lt;/br&gt;- `run_page_url: str`&lt;/br&gt;- `run_type: \"models.RunType\"`&lt;/br&gt;- `attempt_number: int`&lt;/br&gt;- `repair_history: List[\"models.RepairHistoryItem\"]`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/get`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/get\"  # noqa\n\n    responses = {\n        200: \"Run was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n        \"include_history\": include_history,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_get_output","title":"<code>jobs_runs_get_output</code>  <code>async</code>","text":"<p>Retrieve the output and metadata of a single task run. When a notebook task returns a value through the dbutils.notebook.exit() call, you can use this endpoint to retrieve that value. Databricks restricts this API to return the first 5 MB of the output. To return a larger result, you can store job results in a cloud storage service. This endpoint validates that the run_id parameter is valid and returns an HTTP status code 400 if the run_id parameter is invalid. Runs are automatically removed after 60 days. If you to want to reference them beyond 60 days, you must save old run results before they expire. To export using the UI, see Export job run results. To export using the Jobs API, see Runs export.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier for the run. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>notebook_output: \"models.NotebookOutput\"</code>- <code>sql_output: \"models.SqlOutput\"</code>- <code>dbt_output: \"models.DbtOutput\"</code>- <code>logs: str</code>- <code>logs_truncated: bool</code>- <code>error: str</code>- <code>error_trace: str</code>- <code>metadata: \"models.Run\"</code></p> API Endpoint: <p><code>/2.1/jobs/runs/get-output</code></p> API Responses: Response Description 200 Run output was retrieved successfully. 400 A job run with multiple tasks was provided. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_get_output(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieve the output and metadata of a single task run. When a notebook task\n    returns a value through the dbutils.notebook.exit() call, you can use this\n    endpoint to retrieve that value. Databricks restricts this API to return the\n    first 5 MB of the output. To return a larger result, you can store job\n    results in a cloud storage service. This endpoint validates that the run_id\n    parameter is valid and returns an HTTP status code 400 if the run_id\n    parameter is invalid. Runs are automatically removed after 60 days. If you\n    to want to reference them beyond 60 days, you must save old run results\n    before they expire. To export using the UI, see Export job run results. To\n    export using the Jobs API, see Runs export.\n\n    Args:\n        run_id:\n            The canonical identifier for the run. This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `notebook_output: \"models.NotebookOutput\"`&lt;/br&gt;- `sql_output: \"models.SqlOutput\"`&lt;/br&gt;- `dbt_output: \"models.DbtOutput\"`&lt;/br&gt;- `logs: str`&lt;/br&gt;- `logs_truncated: bool`&lt;/br&gt;- `error: str`&lt;/br&gt;- `error_trace: str`&lt;/br&gt;- `metadata: \"models.Run\"`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/get-output`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run output was retrieved successfully. |\n    | 400 | A job run with multiple tasks was provided. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/get-output\"  # noqa\n\n    responses = {\n        200: \"Run output was retrieved successfully.\",  # noqa\n        400: \"A job run with multiple tasks was provided.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_list","title":"<code>jobs_runs_list</code>  <code>async</code>","text":"<p>List runs in descending order by start time.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>active_only</code> <code>bool</code> <p>If active_only is <code>true</code>, only active runs are included in the results; otherwise, lists both active and completed runs. An active run is a run in the <code>PENDING</code>, <code>RUNNING</code>, or <code>TERMINATING</code>. This field cannot be <code>true</code> when completed_only is <code>true</code>.</p> <code>False</code> <code>completed_only</code> <code>bool</code> <p>If completed_only is <code>true</code>, only completed runs are included in the results; otherwise, lists both active and completed runs. This field cannot be <code>true</code> when active_only is <code>true</code>.</p> <code>False</code> <code>job_id</code> <code>Optional[int]</code> <p>The job for which to list runs. If omitted, the Jobs service lists runs from all jobs.</p> <code>None</code> <code>offset</code> <code>int</code> <p>The offset of the first run to return, relative to the most recent run.</p> <code>0</code> <code>limit</code> <code>int</code> <p>The number of runs to return. This value must be greater than 0 and less than 25. The default value is 25. If a request specifies a limit of 0, the service instead uses the maximum limit.</p> <code>25</code> <code>run_type</code> <code>Optional[str]</code> <p>The type of runs to return. For a description of run types, see Run.</p> <code>None</code> <code>expand_tasks</code> <code>bool</code> <p>Whether to include task and cluster details in the response.</p> <code>False</code> <code>start_time_from</code> <code>Optional[int]</code> <p>Show runs that started at or after this value. The value must be a UTC timestamp in milliseconds. Can be combined with start_time_to to filter by a time range.</p> <code>None</code> <code>start_time_to</code> <code>Optional[int]</code> <p>Show runs that started at or before this value. The value must be a UTC timestamp in milliseconds. Can be combined with start_time_from to filter by a time range.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>runs: List[\"models.Run\"]</code>- <code>has_more: bool</code></p> API Endpoint: <p><code>/2.1/jobs/runs/list</code></p> API Responses: Response Description 200 List of runs was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_list(\n    databricks_credentials: \"DatabricksCredentials\",\n    active_only: bool = False,\n    completed_only: bool = False,\n    job_id: Optional[int] = None,\n    offset: int = 0,\n    limit: int = 25,\n    run_type: Optional[str] = None,\n    expand_tasks: bool = False,\n    start_time_from: Optional[int] = None,\n    start_time_to: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List runs in descending order by start time.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        active_only:\n            If active_only is `true`, only active runs are included in the results;\n            otherwise, lists both active and completed runs. An active\n            run is a run in the `PENDING`, `RUNNING`, or `TERMINATING`.\n            This field cannot be `true` when completed_only is `true`.\n        completed_only:\n            If completed_only is `true`, only completed runs are included in the\n            results; otherwise, lists both active and completed runs.\n            This field cannot be `true` when active_only is `true`.\n        job_id:\n            The job for which to list runs. If omitted, the Jobs service lists runs\n            from all jobs.\n        offset:\n            The offset of the first run to return, relative to the most recent run.\n        limit:\n            The number of runs to return. This value must be greater than 0 and less\n            than 25\\. The default value is 25\\. If a request specifies a\n            limit of 0, the service instead uses the maximum limit.\n        run_type:\n            The type of runs to return. For a description of run types, see\n            [Run](https://docs.databricks.com/dev-\n            tools/api/latest/jobs.html\n            operation/JobsRunsGet).\n        expand_tasks:\n            Whether to include task and cluster details in the response.\n        start_time_from:\n            Show runs that started _at or after_ this value. The value must be a UTC\n            timestamp in milliseconds. Can be combined with\n            _start_time_to_ to filter by a time range.\n        start_time_to:\n            Show runs that started _at or before_ this value. The value must be a\n            UTC timestamp in milliseconds. Can be combined with\n            _start_time_from_ to filter by a time range.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `runs: List[\"models.Run\"]`&lt;/br&gt;- `has_more: bool`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/list`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | List of runs was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/list\"  # noqa\n\n    responses = {\n        200: \"List of runs was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"active_only\": active_only,\n        \"completed_only\": completed_only,\n        \"job_id\": job_id,\n        \"offset\": offset,\n        \"limit\": limit,\n        \"run_type\": run_type,\n        \"expand_tasks\": expand_tasks,\n        \"start_time_from\": start_time_from,\n        \"start_time_to\": start_time_to,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_repair","title":"<code>jobs_runs_repair</code>  <code>async</code>","text":"<p>Re-run one or more tasks. Tasks are re-run as part of the original job run, use the current job and task settings, and can be viewed in the history for the original job run.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>The job run ID of the run to repair. The run must not be in progress, e.g. <code>455644833</code>.</p> <code>None</code> <code>rerun_tasks</code> <code>Optional[List[str]]</code> <p>The task keys of the task runs to repair, e.g. <pre><code>[\"task0\", \"task1\"]\n</code></pre></p> <code>None</code> <code>latest_repair_id</code> <code>Optional[int]</code> <p>The ID of the latest repair. This parameter is not required when repairing a run for the first time, but must be provided on subsequent requests to repair the same run, e.g. <code>734650698524280</code>.</p> <code>None</code> <code>rerun_all_failed_tasks</code> <code>bool</code> <p>If true, repair all failed tasks. Only one of rerun_tasks or rerun_all_failed_tasks can be used.</p> <code>False</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example <code>'jar_params': ['john doe', '35']</code>. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon <code>run-now</code>, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example <code>{'jar_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs, e.g. <pre><code>[\"john\", \"doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example <code>'notebook_params': {'name': 'john doe', 'age': '35'}</code>. The map is passed to the notebook and is accessible through the dbutils.widgets.get function.  If not specified upon <code>run-now</code>, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params.  Use Task parameter variables to set parameters containing information about job runs.  The JSON representation of this field (for example <code>{'notebook_params':{'name':'john doe','age':'35'}}</code>) cannot exceed 10,000 bytes, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example <code>'python_params': ['john doe', '35']</code>. The parameters are passed to Python file as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"john doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example <code>'spark_submit_params': ['--class', 'org.apache.spark.examples.SparkPi']</code>. The parameters are passed to spark-submit script as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"--class\", \"org.apache.spark.examples.SparkPi\"]\n</code></pre></p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example <code>'python_named_params': {'name': 'task', 'data': 'dbfs:/path/to/data.json'}</code>, e.g. <pre><code>{\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n</code></pre></p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example <code>'sql_params': {'name': 'john doe', 'age': '35'}</code>. The SQL alert task does not support custom parameters, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example <code>'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']</code>, e.g. <pre><code>[\"dbt deps\", \"dbt seed\", \"dbt run\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>repair_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/runs/repair</code></p> API Responses: Response Description 200 Run repair was initiated. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_repair(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n    rerun_tasks: Optional[List[str]] = None,\n    latest_repair_id: Optional[int] = None,\n    rerun_all_failed_tasks: bool = False,\n    jar_params: Optional[List[str]] = None,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Re-run one or more tasks. Tasks are re-run as part of the original job run, use\n    the current job and task settings, and can be viewed in the history for the\n    original job run.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            The job run ID of the run to repair. The run must not be in progress,\n            e.g. `455644833`.\n        rerun_tasks:\n            The task keys of the task runs to repair, e.g.\n            ```\n            [\"task0\", \"task1\"]\n            ```\n        latest_repair_id:\n            The ID of the latest repair. This parameter is not required when\n            repairing a run for the first time, but must be provided on\n            subsequent requests to repair the same run, e.g.\n            `734650698524280`.\n        rerun_all_failed_tasks:\n            If true, repair all failed tasks. Only one of rerun_tasks or\n            rerun_all_failed_tasks can be used.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example\n            `'jar_params': ['john doe', '35']`. The parameters are used\n            to invoke the main function of the main class specified in\n            the Spark JAR task. If not specified upon `run-now`, it\n            defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of\n            this field (for example `{'jar_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs, e.g.\n            ```\n            [\"john\", \"doe\", \"35\"]\n            ```\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            `'notebook_params': {'name': 'john doe', 'age': '35'}`. The\n            map is passed to the notebook and is accessible through the\n            [dbutils.widgets.get](https://docs.databricks.com/dev-\n            tools/databricks-utils.html\n            dbutils-widgets) function.  If not specified upon `run-now`,\n            the triggered run uses the job\u2019s base parameters.\n            notebook_params cannot be specified in conjunction with\n            jar_params.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  The JSON representation of this\n            field (for example `{'notebook_params':{'name':'john\n            doe','age':'35'}}`) cannot exceed 10,000 bytes, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        python_params:\n            A list of parameters for jobs with Python tasks, for example\n            `'python_params': ['john doe', '35']`. The parameters are\n            passed to Python file as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"john doe\", \"35\"]\n            ```\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            `'spark_submit_params': ['--class',\n            'org.apache.spark.examples.SparkPi']`. The parameters are\n            passed to spark-submit script as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"--class\", \"org.apache.spark.examples.SparkPi\"]\n            ```\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            `'python_named_params': {'name': 'task', 'data':\n            'dbfs:/path/to/data.json'}`, e.g.\n            ```\n            {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n            ```\n        pipeline_params:\n\n        sql_params:\n            A map from keys to values for SQL tasks, for example `'sql_params':\n            {'name': 'john doe', 'age': '35'}`. The SQL alert task does\n            not support custom parameters, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task, for example\n            `'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']`, e.g.\n            ```\n            [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n            ```\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `repair_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/repair`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run repair was initiated. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/repair\"  # noqa\n\n    responses = {\n        200: \"Run repair was initiated.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n        \"rerun_tasks\": rerun_tasks,\n        \"latest_repair_id\": latest_repair_id,\n        \"rerun_all_failed_tasks\": rerun_all_failed_tasks,\n        \"jar_params\": jar_params,\n        \"notebook_params\": notebook_params,\n        \"python_params\": python_params,\n        \"spark_submit_params\": spark_submit_params,\n        \"python_named_params\": python_named_params,\n        \"pipeline_params\": pipeline_params,\n        \"sql_params\": sql_params,\n        \"dbt_commands\": dbt_commands,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_submit","title":"<code>jobs_runs_submit</code>  <code>async</code>","text":"<p>Submit a one-time run. This endpoint allows you to submit a workload directly without creating a job. Use the <code>jobs/runs/get</code> API to check the run state after the job is submitted.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>tasks</code> <code>Optional[List[RunSubmitTaskSettings]]</code> <p>, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n    },\n]\n</code></pre></p> <code>None</code> <code>run_name</code> <code>Optional[str]</code> <p>An optional name for the run. The default value is <code>Untitled</code>, e.g. <code>A multitask job run</code>.</p> <code>None</code> <code>webhook_notifications</code> <code>WebhookNotifications</code> <p>A collection of system notification IDs to notify when runs of this job begin or complete. The default behavior is to not send any system notifications. Key-values: - on_start:     An optional list of notification IDs to call when the run     starts. A maximum of 3 destinations can be specified for the     <code>on_start</code> property, e.g.     <pre><code>[\n    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n]\n</code></pre> - on_success:     An optional list of notification IDs to call when the run     completes successfully. A maximum of 3 destinations can be     specified for the <code>on_success</code> property, e.g.     <pre><code>[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n</code></pre> - on_failure:     An optional list of notification IDs to call when the run     fails. A maximum of 3 destinations can be specified for the     <code>on_failure</code> property, e.g.     <pre><code>[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n</code></pre></p> <code>None</code> <code>git_source</code> <code>GitSource</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks, e.g. <code>{     \"git_url\": \"https://github.com/databricks/databricks-cli\",     \"git_branch\": \"main\",     \"git_provider\": \"gitHub\", }</code> Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>run_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/runs/submit</code></p> API Responses: Response Description 200 Run was created and started successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_submit(\n    databricks_credentials: \"DatabricksCredentials\",\n    tasks: Optional[List[\"models.RunSubmitTaskSettings\"]] = None,\n    run_name: Optional[str] = None,\n    webhook_notifications: \"models.WebhookNotifications\" = None,\n    git_source: \"models.GitSource\" = None,\n    timeout_seconds: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    access_control_list: Optional[List[\"models.AccessControlRequest\"]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Submit a one-time run. This endpoint allows you to submit a workload directly\n    without creating a job. Use the `jobs/runs/get` API to check the run state\n    after the job is submitted.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        tasks:\n            , e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"source\": \"WORKSPACE\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                },\n            ]\n            ```\n        run_name:\n            An optional name for the run. The default value is `Untitled`, e.g. `A\n            multitask job run`.\n        webhook_notifications:\n            A collection of system notification IDs to notify when runs of this job\n            begin or complete. The default behavior is to not send any\n            system notifications. Key-values:\n            - on_start:\n                An optional list of notification IDs to call when the run\n                starts. A maximum of 3 destinations can be specified for the\n                `on_start` property, e.g.\n                ```\n                [\n                    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n                    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n                ]\n                ```\n            - on_success:\n                An optional list of notification IDs to call when the run\n                completes successfully. A maximum of 3 destinations can be\n                specified for the `on_success` property, e.g.\n                ```\n                [{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n                ```\n            - on_failure:\n                An optional list of notification IDs to call when the run\n                fails. A maximum of 3 destinations can be specified for the\n                `on_failure` property, e.g.\n                ```\n                [{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n                ```\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks, e.g.\n            ```\n            {\n                \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                \"git_branch\": \"main\",\n                \"git_provider\": \"gitHub\",\n            }\n            ``` Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        access_control_list:\n            List of permissions to set on the job.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `run_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/submit`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was created and started successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/submit\"  # noqa\n\n    responses = {\n        200: \"Run was created and started successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"tasks\": tasks,\n        \"run_name\": run_name,\n        \"webhook_notifications\": webhook_notifications,\n        \"git_source\": git_source,\n        \"timeout_seconds\": timeout_seconds,\n        \"idempotency_token\": idempotency_token,\n        \"access_control_list\": access_control_list,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_update","title":"<code>jobs_update</code>  <code>async</code>","text":"<p>Add, update, or remove specific settings of an existing job. Use the Reset endpoint to overwrite all job settings.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to update. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <code>new_settings</code> <code>JobSettings</code> <p>The new settings for the job. Any top-level fields specified in <code>new_settings</code> are completely replaced. Partially updating nested fields is not supported.  Changes to the field <code>JobSettings.timeout_seconds</code> are applied to active runs. Changes to other fields are applied to future runs only. Key-values: - name:     An optional name for the job, e.g. <code>A multitask job</code>. - tags:     A map of tags associated with the job. These are forwarded     to the cluster as cluster tags for jobs clusters, and are     subject to the same limitations as cluster tags. A maximum     of 25 tags can be added to the job, e.g.     <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre> - tasks:     A list of task specifications to be executed by this job, e.g.     <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/order-data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\n                \"name\": \"John Doe\",\n                \"age\": \"35\",\n            },\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre> - job_clusters:     A list of job cluster specifications that can be shared and     reused by tasks of this job. Libraries cannot be declared in     a shared job cluster. You must declare dependent libraries     in task settings, e.g.     <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n    }\n]\n</code></pre> - email_notifications:     An optional set of email addresses that is notified when     runs of this job begin or complete as well as when this job     is deleted. The default behavior is to not send any emails. - webhook_notifications:     A collection of system notification IDs to notify when runs     of this job begin or complete. The default behavior is to     not send any system notifications. - timeout_seconds:     An optional timeout applied to each run of this job. The     default behavior is to have no timeout, e.g. <code>86400</code>. - schedule:     An optional periodic schedule for this job. The default     behavior is that the job only runs when triggered by     clicking \u201cRun Now\u201d in the Jobs UI or sending an API request     to <code>runNow</code>. - max_concurrent_runs:     An optional maximum allowed number of concurrent runs of the     job.  Set this value if you want to be able to execute     multiple runs of the same job concurrently. This is useful     for example if you trigger your job on a frequent schedule     and want to allow consecutive runs to overlap with each     other, or if you want to trigger multiple runs which differ     by their input parameters.  This setting affects only new     runs. For example, suppose the job\u2019s concurrency is 4 and     there are 4 concurrent active runs. Then setting the     concurrency to 3 won\u2019t kill any of the active runs. However,     from then on, new runs are skipped unless there are fewer     than 3 active runs.  This value cannot exceed 1000. Setting     this value to 0 causes all new runs to be skipped. The     default behavior is to allow only 1 concurrent run, e.g.     <code>10</code>. - git_source:     This functionality is in Public Preview.  An optional     specification for a remote repository containing the     notebooks used by this job's notebook tasks, e.g.     <pre><code>{\n    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n    \"git_branch\": \"main\",\n    \"git_provider\": \"gitHub\",\n}\n</code></pre> - format:     Used to tell what is the format of the job. This field is     ignored in Create/Update/Reset calls. When using the Jobs     API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g.     <code>MULTI_TASK</code>.</p> <code>None</code> <code>fields_to_remove</code> <code>Optional[List[str]]</code> <p>Remove top-level fields in the job settings. Removing nested fields is not supported. This field is optional, e.g. <pre><code>[\"libraries\", \"schedule\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/update</code></p> API Responses: Response Description 200 Job was updated successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_update(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    new_settings: \"models.JobSettings\" = None,\n    fields_to_remove: Optional[List[str]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Add, update, or remove specific settings of an existing job. Use the Reset\n    endpoint to overwrite all job settings.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to update. This field is required,\n            e.g. `11223344`.\n        new_settings:\n            The new settings for the job. Any top-level fields specified in\n            `new_settings` are completely replaced. Partially updating\n            nested fields is not supported.  Changes to the field\n            `JobSettings.timeout_seconds` are applied to active runs.\n            Changes to other fields are applied to future runs only. Key-values:\n            - name:\n                An optional name for the job, e.g. `A multitask job`.\n            - tags:\n                A map of tags associated with the job. These are forwarded\n                to the cluster as cluster tags for jobs clusters, and are\n                subject to the same limitations as cluster tags. A maximum\n                of 25 tags can be added to the job, e.g.\n                ```\n                {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n                ```\n            - tasks:\n                A list of task specifications to be executed by this job, e.g.\n                ```\n                [\n                    {\n                        \"task_key\": \"Sessionize\",\n                        \"description\": \"Extracts session data from events\",\n                        \"depends_on\": [],\n                        \"existing_cluster_id\": \"0923-164208-meows279\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.Sessionize\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Orders_Ingest\",\n                        \"description\": \"Ingests order data\",\n                        \"depends_on\": [],\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.OrdersIngest\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/order-data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Match\",\n                        \"description\": \"Matches orders with user sessions\",\n                        \"depends_on\": [\n                            {\"task_key\": \"Orders_Ingest\"},\n                            {\"task_key\": \"Sessionize\"},\n                        ],\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                        \"notebook_task\": {\n                            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                            \"source\": \"WORKSPACE\",\n                            \"base_parameters\": {\n                                \"name\": \"John Doe\",\n                                \"age\": \"35\",\n                            },\n                        },\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                ]\n                ```\n            - job_clusters:\n                A list of job cluster specifications that can be shared and\n                reused by tasks of this job. Libraries cannot be declared in\n                a shared job cluster. You must declare dependent libraries\n                in task settings, e.g.\n                ```\n                [\n                    {\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                    }\n                ]\n                ```\n            - email_notifications:\n                An optional set of email addresses that is notified when\n                runs of this job begin or complete as well as when this job\n                is deleted. The default behavior is to not send any emails.\n            - webhook_notifications:\n                A collection of system notification IDs to notify when runs\n                of this job begin or complete. The default behavior is to\n                not send any system notifications.\n            - timeout_seconds:\n                An optional timeout applied to each run of this job. The\n                default behavior is to have no timeout, e.g. `86400`.\n            - schedule:\n                An optional periodic schedule for this job. The default\n                behavior is that the job only runs when triggered by\n                clicking \u201cRun Now\u201d in the Jobs UI or sending an API request\n                to `runNow`.\n            - max_concurrent_runs:\n                An optional maximum allowed number of concurrent runs of the\n                job.  Set this value if you want to be able to execute\n                multiple runs of the same job concurrently. This is useful\n                for example if you trigger your job on a frequent schedule\n                and want to allow consecutive runs to overlap with each\n                other, or if you want to trigger multiple runs which differ\n                by their input parameters.  This setting affects only new\n                runs. For example, suppose the job\u2019s concurrency is 4 and\n                there are 4 concurrent active runs. Then setting the\n                concurrency to 3 won\u2019t kill any of the active runs. However,\n                from then on, new runs are skipped unless there are fewer\n                than 3 active runs.  This value cannot exceed 1000\\. Setting\n                this value to 0 causes all new runs to be skipped. The\n                default behavior is to allow only 1 concurrent run, e.g.\n                `10`.\n            - git_source:\n                This functionality is in Public Preview.  An optional\n                specification for a remote repository containing the\n                notebooks used by this job's notebook tasks, e.g.\n                ```\n                {\n                    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                    \"git_branch\": \"main\",\n                    \"git_provider\": \"gitHub\",\n                }\n                ```\n            - format:\n                Used to tell what is the format of the job. This field is\n                ignored in Create/Update/Reset calls. When using the Jobs\n                API 2.1 this value is always set to `'MULTI_TASK'`, e.g.\n                `MULTI_TASK`.\n        fields_to_remove:\n            Remove top-level fields in the job settings. Removing nested fields is\n            not supported. This field is optional, e.g.\n            ```\n            [\"libraries\", \"schedule\"]\n            ```\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/update`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was updated successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/update\"  # noqa\n\n    responses = {\n        200: \"Job was updated successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"new_settings\": new_settings,\n        \"fields_to_remove\": fields_to_remove,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/","title":"Rest","text":""},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest","title":"<code>prefect_databricks.rest</code>","text":"<p>This is a module containing generic REST tasks.</p>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.HTTPMethod","title":"<code>HTTPMethod</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Available HTTP request methods.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>class HTTPMethod(Enum):\n    \"\"\"\n    Available HTTP request methods.\n    \"\"\"\n\n    GET = \"get\"\n    POST = \"post\"\n    PUT = \"put\"\n    DELETE = \"delete\"\n    PATCH = \"patch\"\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.execute_endpoint","title":"<code>execute_endpoint</code>  <code>async</code>","text":"<p>Generic function for executing REST endpoints.</p> <p>Parameters:</p> Name Type Description Default <code>endpoint</code> <code>str</code> <p>The endpoint route.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>http_method</code> <code>HTTPMethod</code> <p>Either GET, POST, PUT, DELETE, or PATCH.</p> <code>GET</code> <code>params</code> <code>Dict[str, Any]</code> <p>URL query parameters in the request.</p> <code>None</code> <code>json</code> <code>Dict[str, Any]</code> <p>JSON serializable object to include in the body of the request.</p> <code>None</code> <code>**kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Response</code> <p>The httpx.Response from interacting with the endpoint.</p> <p>Examples:</p> <p>Lists jobs on the Databricks instance. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.rest import execute_endpoint\n@flow\ndef example_execute_endpoint_flow():\n    endpoint = \"/2.1/jobs/list\"\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n    params = {\n        \"limit\": 5,\n        \"offset\": None,\n        \"expand_tasks\": True,\n    }\n    response = execute_endpoint(\n        endpoint,\n        databricks_credentials,\n        params=params\n    )\n    return response.json()\n</code></pre></p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>@task\nasync def execute_endpoint(\n    endpoint: str,\n    databricks_credentials: \"DatabricksCredentials\",\n    http_method: HTTPMethod = HTTPMethod.GET,\n    params: Dict[str, Any] = None,\n    json: Dict[str, Any] = None,\n    **kwargs: Dict[str, Any],\n) -&gt; httpx.Response:\n    \"\"\"\n    Generic function for executing REST endpoints.\n\n    Args:\n        endpoint: The endpoint route.\n        databricks_credentials: Credentials to use for authentication with Databricks.\n        http_method: Either GET, POST, PUT, DELETE, or PATCH.\n        params: URL query parameters in the request.\n        json: JSON serializable object to include in the body of the request.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        The httpx.Response from interacting with the endpoint.\n\n    Examples:\n        Lists jobs on the Databricks instance.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.rest import execute_endpoint\n        @flow\n        def example_execute_endpoint_flow():\n            endpoint = \"/2.1/jobs/list\"\n            databricks_credentials = DatabricksCredentials.load(\"my-block\")\n            params = {\n                \"limit\": 5,\n                \"offset\": None,\n                \"expand_tasks\": True,\n            }\n            response = execute_endpoint(\n                endpoint,\n                databricks_credentials,\n                params=params\n            )\n            return response.json()\n        ```\n    \"\"\"\n    if isinstance(http_method, HTTPMethod):\n        http_method = http_method.value\n\n    if params is not None:\n        stripped_params = strip_kwargs(**params)\n    else:\n        stripped_params = None\n\n    if json is not None:\n        kwargs[\"json\"] = strip_kwargs(**json)\n\n    async with databricks_credentials.get_client() as client:\n        response = await getattr(client, http_method)(\n            endpoint, params=stripped_params, **kwargs\n        )\n\n    return response\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.serialize_model","title":"<code>serialize_model</code>","text":"<p>Recursively serializes <code>pydantic.BaseModel</code> into JSON; returns original obj if not a <code>BaseModel</code>.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Any</code> <p>Input object to serialize.</p> required <p>Returns:</p> Type Description <code>Any</code> <p>Serialized version of object.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>def serialize_model(obj: Any) -&gt; Any:\n    \"\"\"\n    Recursively serializes `pydantic.BaseModel` into JSON;\n    returns original obj if not a `BaseModel`.\n\n    Args:\n        obj: Input object to serialize.\n\n    Returns:\n        Serialized version of object.\n    \"\"\"\n    if isinstance(obj, list):\n        return [serialize_model(o) for o in obj]\n    elif isinstance(obj, Dict):\n        return {k: serialize_model(v) for k, v in obj.items()}\n\n    if isinstance(obj, MODELS):\n        return model_dump(obj, mode=\"json\")\n    elif isinstance(obj, Enum):\n        return obj.value\n    return obj\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.strip_kwargs","title":"<code>strip_kwargs</code>","text":"<p>Recursively drops keyword arguments if value is None, and serializes any <code>pydantic.BaseModel</code> types.</p> <p>Parameters:</p> Name Type Description Default <code>**kwargs</code> <code>Dict</code> <p>Input keyword arguments.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict</code> <p>Stripped version of kwargs.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>def strip_kwargs(**kwargs: Dict) -&gt; Dict:\n    \"\"\"\n    Recursively drops keyword arguments if value is None,\n    and serializes any `pydantic.BaseModel` types.\n\n    Args:\n        **kwargs: Input keyword arguments.\n\n    Returns:\n        Stripped version of kwargs.\n    \"\"\"\n    stripped_dict = {}\n    for k, v in kwargs.items():\n        v = serialize_model(v)\n        if isinstance(v, dict):\n            v = strip_kwargs(**v)\n        if v is not None:\n            stripped_dict[k] = v\n    return stripped_dict or {}\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs","title":"<code>prefect_databricks.models.jobs</code>","text":""},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlList","title":"<code>AccessControlList</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlList(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    access_control_list: Optional[List[AccessControlRequest]] = Field(\n        None, description=\"List of permissions to set on the job.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequest","title":"<code>AccessControlRequest</code>","text":"<p>               Bases: <code>AccessControlRequestForUser</code>, <code>AccessControlRequestForGroup</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequest(AccessControlRequestForUser, AccessControlRequestForGroup):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForGroup","title":"<code>AccessControlRequestForGroup</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForGroup(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    group_name: Optional[GroupName] = None\n    permission_level: Optional[PermissionLevelForGroup] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForServicePrincipal","title":"<code>AccessControlRequestForServicePrincipal</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForServicePrincipal(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    permission_level: Optional[PermissionLevel] = None\n    service_principal_name: Optional[ServicePrincipalName] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForUser","title":"<code>AccessControlRequestForUser</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForUser(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    permission_level: Optional[PermissionLevel] = None\n    user_name: Optional[UserName] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AutoScale","title":"<code>AutoScale</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AutoScale(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    max_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"The maximum number of workers to which the cluster can scale up when\"\n            \" overloaded. max_workers must be strictly greater than min_workers.\"\n        ),\n    )\n    min_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"The minimum number of workers to which the cluster can scale down when\"\n            \" underutilized. It is also the initial number of workers the cluster has\"\n            \" after creation.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AwsAttributes","title":"<code>AwsAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AwsAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    availability: Optional[Literal[\"SPOT\", \"ON_DEMAND\", \"SPOT_WITH_FALLBACK\"]] = Field(\n        None,\n        description=(\n            \"Availability type used for all subsequent nodes past the `first_on_demand`\"\n            \" ones. **Note:** If `first_on_demand` is zero, this availability type is\"\n            \" used for the entire cluster.\\n\\n`SPOT`: use spot instances.\\n`ON_DEMAND`:\"\n            \" use on-demand instances.\\n`SPOT_WITH_FALLBACK`: preferably use spot\"\n            \" instances, but fall back to on-demand instances if spot instances cannot\"\n            \" be acquired (for example, if AWS spot prices are too high).\"\n        ),\n    )\n    ebs_volume_count: Optional[int] = Field(\n        None,\n        description=(\n            \"The number of volumes launched for each instance. You can choose up to 10\"\n            \" volumes. This feature is only enabled for supported node types. Legacy\"\n            \" node types cannot specify custom EBS volumes. For node types with no\"\n            \" instance store, at least one EBS volume needs to be specified; otherwise,\"\n            \" cluster creation fails.\\n\\nThese EBS volumes are mounted at `/ebs0`,\"\n            \" `/ebs1`, and etc. Instance store volumes are mounted at `/local_disk0`,\"\n            \" `/local_disk1`, and etc.\\n\\nIf EBS volumes are attached, Databricks\"\n            \" configures Spark to use only the EBS volumes for scratch storage because\"\n            \" heterogeneously sized scratch devices can lead to inefficient disk\"\n            \" utilization. If no EBS volumes are attached, Databricks configures Spark\"\n            \" to use instance store volumes.\\n\\nIf EBS volumes are specified, then the\"\n            \" Spark configuration `spark.local.dir` is overridden.\"\n        ),\n    )\n    ebs_volume_iops: Optional[int] = Field(\n        None,\n        description=(\n            \"The number of IOPS per EBS gp3 volume.\\n\\nThis value must be between 3000\"\n            \" and 16000.\\n\\nThe value of IOPS and throughput is calculated based on AWS\"\n            \" documentation to match the maximum performance of a gp2 volume with the\"\n            \" same volume size.\\n\\nFor more information, see the [EBS volume limit\"\n            \" calculator](https://github.com/awslabs/aws-support-tools/tree/master/EBS/VolumeLimitCalculator).\"\n        ),\n    )\n    ebs_volume_size: Optional[int] = Field(\n        None,\n        description=(\n            \"The size of each EBS volume (in GiB) launched for each instance. For\"\n            \" general purpose SSD, this value must be within the range 100 - 4096\\\\.\"\n            \" For throughput optimized HDD, this value must be within the range 500 -\"\n            \" 4096\\\\. Custom EBS volumes cannot be specified for the legacy node types\"\n            \" (_memory-optimized_ and _compute-optimized_).\"\n        ),\n    )\n    ebs_volume_throughput: Optional[int] = Field(\n        None,\n        description=(\n            \"The throughput per EBS gp3 volume, in MiB per second.\\n\\nThis value must\"\n            \" be between 125 and 1000.\"\n        ),\n    )\n    ebs_volume_type: Optional[\n        Literal[\"GENERAL_PURPOSE_SSD\", \"THROUGHPUT_OPTIMIZED_HDD\"]\n    ] = Field(\n        None,\n        description=(\n            \"The type of EBS volume that is launched with this\"\n            \" cluster.\\n\\n`GENERAL_PURPOSE_SSD`: provision extra storage using AWS gp2\"\n            \" EBS volumes.\\n`THROUGHPUT_OPTIMIZED_HDD`: provision extra storage using\"\n            \" AWS st1 volumes.\"\n        ),\n    )\n    first_on_demand: Optional[int] = Field(\n        None,\n        description=(\n            \"The first first_on_demand nodes of the cluster are placed on on-demand\"\n            \" instances. If this value is greater than 0, the cluster driver node is\"\n            \" placed on an on-demand instance. If this value is greater than or equal\"\n            \" to the current cluster size, all nodes are placed on on-demand instances.\"\n            \" If this value is less than the current cluster size, first_on_demand\"\n            \" nodes are placed on on-demand instances and the remainder are placed on\"\n            \" `availability` instances. This value does not affect cluster size and\"\n            \" cannot be mutated over the lifetime of a cluster.\"\n        ),\n    )\n    instance_profile_arn: Optional[str] = Field(\n        None,\n        description=(\n            \"Nodes for this cluster are only be placed on AWS instances with this\"\n            \" instance profile. If omitted, nodes are placed on instances without an\"\n            \" instance profile. The instance profile must have previously been added to\"\n            \" the Databricks environment by an account administrator.\\n\\nThis feature\"\n            \" may only be available to certain customer plans.\"\n        ),\n    )\n    spot_bid_price_percent: Optional[int] = Field(\n        None,\n        description=(\n            \"The max price for AWS spot instances, as a percentage of the corresponding\"\n            \" instance type\u2019s on-demand price. For example, if this field is set to 50,\"\n            \" and the cluster needs a new `i3.xlarge` spot instance, then the max price\"\n            \" is half of the price of on-demand `i3.xlarge` instances. Similarly, if\"\n            \" this field is set to 200, the max price is twice the price of on-demand\"\n            \" `i3.xlarge` instances. If not specified, the default value is 100\\\\. When\"\n            \" spot instances are requested for this cluster, only spot instances whose\"\n            \" max price percentage matches this field is considered. For safety, we\"\n            \" enforce this field to be no more than 10000.\"\n        ),\n    )\n    zone_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Identifier for the availability zone/datacenter in which the cluster\"\n            \" resides. You have three options:\\n\\n**Specify an availability zone as a\"\n            \" string**, for example: \u201cus-west-2a\u201d. The provided availability zone must\"\n            \" be in the same region as the Databricks deployment. For example,\"\n            \" \u201cus-west-2a\u201d is not a valid zone ID if the Databricks deployment resides\"\n            \" in the \u201cus-east-1\u201d region.\\n\\n**Enable automatic availability zone\"\n            \" selection (\u201cAuto-AZ\u201d)**, by setting the value \u201cauto\u201d. Databricks selects\"\n            \" the AZ based on available IPs in the workspace subnets and retries in\"\n            \" other availability zones if AWS returns insufficient capacity\"\n            \" errors.\\n\\n**Do not specify a value**. If not specified, a default zone\"\n            \" is used.\\n\\nThe list of available zones as well as the default value can\"\n            \" be found by using the [List\"\n            \" zones](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-zones)\"\n            \" API.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanManage","title":"<code>CanManage</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to manage the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanManage(str, Enum):\n    \"\"\"\n    Permission to manage the job.\n    \"\"\"\n\n    canmanage = \"CAN_MANAGE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanManageRun","title":"<code>CanManageRun</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to run and/or manage runs for the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanManageRun(str, Enum):\n    \"\"\"\n    Permission to run and/or manage runs for the job.\n    \"\"\"\n\n    canmanagerun = \"CAN_MANAGE_RUN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanView","title":"<code>CanView</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to view the settings of the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanView(str, Enum):\n    \"\"\"\n    Permission to view the settings of the job.\n    \"\"\"\n\n    canview = \"CAN_VIEW\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterAttributes","title":"<code>ClusterAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autotermination_minutes: Optional[int] = Field(\n        None,\n        description=(\n            \"Automatically terminates the cluster after it is inactive for this time in\"\n            \" minutes. If not set, this cluster is not be automatically terminated. If\"\n            \" specified, the threshold must be between 10 and 10000 minutes. You can\"\n            \" also set this value to 0 to explicitly disable automatic termination.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values are used.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs is delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-ID&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-ID&gt;/executor`.\"\n        ),\n    )\n    cluster_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Cluster name requested by the user. This doesn\u2019t have to be unique. If not\"\n            \" specified at creation, the cluster name is an empty string.\"\n        ),\n    )\n    cluster_source: Optional[ClusterSource] = Field(\n        None,\n        description=(\n            \"Determines whether the cluster was created by a user through the UI,\"\n            \" created by the Databricks Jobs scheduler, or through an API request.\"\n        ),\n    )\n    custom_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    docker_image: Optional[DockerImage] = Field(\n        None,\n        description=(\n            \"Docker image for a [custom\"\n            \" container](https://docs.databricks.com/clusters/custom-containers.html).\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly. Refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    enable_local_disk_encryption: Optional[bool] = Field(\n        None,\n        description=(\n            \"Determines whether encryption of the disks attached to the cluster locally\"\n            \" is enabled.\"\n        ),\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of destinations can\"\n            \" be specified. The scripts are executed sequentially in the order\"\n            \" provided. If `cluster_log_conf` is specified, init script logs are sent\"\n            \" to `&lt;destination&gt;/&lt;cluster-ID&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to which the cluster belongs. Refer\"\n            \" to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html)\"\n            \" for details.\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    policy_id: Optional[str] = Field(\n        None,\n        description=(\n            \"A [cluster\"\n            \" policy](https://docs.databricks.com/dev-tools/api/latest/policies.html) ID.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pairs of the form (X,Y) are exported\"\n            \" as is (that is, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nIn order to specify an additional set of\"\n            \" `SPARK_DAEMON_JAVA_OPTS`, we recommend appending them to\"\n            \" `$SPARK_DAEMON_JAVA_OPTS` as shown in the following example. This ensures\"\n            \" that all default databricks managed environmental variables are included\"\n            ' as well.\\n\\nExample Spark environment variables: `{\"SPARK_WORKER_MEMORY\":'\n            ' \"28000m\", \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or'\n            ' `{\"SPARK_DAEMON_JAVA_OPTS\": \"$SPARK_DAEMON_JAVA_OPTS'\n            ' -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: Optional[str] = Field(\n        None,\n        description=(\n            \"The runtime version of the cluster, for example \u201c5.0.x-scala2.11\u201d. You can\"\n            \" retrieve a list of available runtime versions by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that is added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterCloudProviderNodeInfo","title":"<code>ClusterCloudProviderNodeInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterCloudProviderNodeInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    available_core_quota: Optional[int] = Field(\n        None, description=\"Available CPU core quota.\"\n    )\n    status: Optional[ClusterCloudProviderNodeStatus] = Field(\n        None, description=\"Status as reported by the cloud provider.\"\n    )\n    total_core_quota: Optional[int] = Field(None, description=\"Total CPU core quota.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterCloudProviderNodeStatus","title":"<code>ClusterCloudProviderNodeStatus</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* NotEnabledOnSubscription: Node type not available for subscription.\n</code></pre> <ul> <li>NotAvailableInRegion: Node type not available in region.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterCloudProviderNodeStatus(str, Enum):\n    \"\"\"\n        * NotEnabledOnSubscription: Node type not available for subscription.\n    * NotAvailableInRegion: Node type not available in region.\n\n    \"\"\"\n\n    not_enabled_on_subscription = \"NotEnabledOnSubscription\"\n    not_available_in_region = \"NotAvailableInRegion\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterEvent","title":"<code>ClusterEvent</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterEvent(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: str = Field(\n        ..., description=\"Canonical identifier for the cluster. This field is required.\"\n    )\n    details: EventDetails = Field(\n        ..., description=\"The event details. This field is required.\"\n    )\n    timestamp: Optional[int] = Field(\n        None,\n        description=(\n            \"The timestamp when the event occurred, stored as the number of\"\n            \" milliseconds since the unix epoch. Assigned by the Timeline service.\"\n        ),\n    )\n    type: ClusterEventType = Field(\n        ..., description=\"The event type. This field is required.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterEventType","title":"<code>ClusterEventType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `CREATING`: Indicates that the cluster is being created.\n</code></pre> <ul> <li><code>DID_NOT_EXPAND_DISK</code>: Indicates that a disk is low on space, but adding disks would put it over the max capacity.</li> <li><code>EXPANDED_DISK</code>: Indicates that a disk was low on space and the disks were expanded.</li> <li><code>FAILED_TO_EXPAND_DISK</code>: Indicates that a disk was low on space and disk space could not be expanded.</li> <li><code>INIT_SCRIPTS_STARTING</code>: Indicates that the cluster scoped init script has started.</li> <li><code>INIT_SCRIPTS_FINISHED</code>: Indicates that the cluster scoped init script has finished.</li> <li><code>STARTING</code>: Indicates that the cluster is being started.</li> <li><code>RESTARTING</code>: Indicates that the cluster is being started.</li> <li><code>TERMINATING</code>: Indicates that the cluster is being terminated.</li> <li><code>EDITED</code>: Indicates that the cluster has been edited.</li> <li><code>RUNNING</code>: Indicates the cluster has finished being created. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.</li> <li><code>RESIZING</code>: Indicates a change in the target size of the cluster (upsize or downsize).</li> <li><code>UPSIZE_COMPLETED</code>: Indicates that nodes finished being added to the cluster. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.</li> <li><code>NODES_LOST</code>: Indicates that some nodes were lost from the cluster.</li> <li><code>DRIVER_HEALTHY</code>: Indicates that the driver is healthy and the cluster is ready for use.</li> <li><code>DRIVER_UNAVAILABLE</code>: Indicates that the driver is unavailable.</li> <li><code>SPARK_EXCEPTION</code>: Indicates that a Spark exception was thrown from the driver.</li> <li><code>DRIVER_NOT_RESPONDING</code>: Indicates that the driver is up but is not responsive, likely due to GC.</li> <li><code>DBFS_DOWN</code>: Indicates that the driver is up but DBFS is down.</li> <li><code>METASTORE_DOWN</code>: Indicates that the driver is up but the metastore is down.</li> <li><code>NODE_BLACKLISTED</code>: Indicates that a node is not allowed by Spark.</li> <li><code>PINNED</code>: Indicates that the cluster was pinned.</li> <li><code>UNPINNED</code>: Indicates that the cluster was unpinned.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterEventType(str, Enum):\n    \"\"\"\n        * `CREATING`: Indicates that the cluster is being created.\n    * `DID_NOT_EXPAND_DISK`: Indicates that a disk is low on space, but adding disks would put it over the max capacity.\n    * `EXPANDED_DISK`: Indicates that a disk was low on space and the disks were expanded.\n    * `FAILED_TO_EXPAND_DISK`: Indicates that a disk was low on space and disk space could not be expanded.\n    * `INIT_SCRIPTS_STARTING`: Indicates that the cluster scoped init script has started.\n    * `INIT_SCRIPTS_FINISHED`: Indicates that the cluster scoped init script has finished.\n    * `STARTING`: Indicates that the cluster is being started.\n    * `RESTARTING`: Indicates that the cluster is being started.\n    * `TERMINATING`: Indicates that the cluster is being terminated.\n    * `EDITED`: Indicates that the cluster has been edited.\n    * `RUNNING`: Indicates the cluster has finished being created. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.\n    * `RESIZING`: Indicates a change in the target size of the cluster (upsize or downsize).\n    * `UPSIZE_COMPLETED`: Indicates that nodes finished being added to the cluster. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.\n    * `NODES_LOST`: Indicates that some nodes were lost from the cluster.\n    * `DRIVER_HEALTHY`: Indicates that the driver is healthy and the cluster is ready for use.\n    * `DRIVER_UNAVAILABLE`: Indicates that the driver is unavailable.\n    * `SPARK_EXCEPTION`: Indicates that a Spark exception was thrown from the driver.\n    * `DRIVER_NOT_RESPONDING`: Indicates that the driver is up but is not responsive, likely due to GC.\n    * `DBFS_DOWN`: Indicates that the driver is up but DBFS is down.\n    * `METASTORE_DOWN`: Indicates that the driver is up but the metastore is down.\n    * `NODE_BLACKLISTED`: Indicates that a node is not allowed by Spark.\n    * `PINNED`: Indicates that the cluster was pinned.\n    * `UNPINNED`: Indicates that the cluster was unpinned.\n    \"\"\"\n\n    creating = \"CREATING\"\n    didnotexpanddisk = \"DID_NOT_EXPAND_DISK\"\n    expandeddisk = \"EXPANDED_DISK\"\n    failedtoexpanddisk = \"FAILED_TO_EXPAND_DISK\"\n    initscriptsstarting = \"INIT_SCRIPTS_STARTING\"\n    initscriptsfinished = \"INIT_SCRIPTS_FINISHED\"\n    starting = \"STARTING\"\n    restarting = \"RESTARTING\"\n    terminating = \"TERMINATING\"\n    edited = \"EDITED\"\n    running = \"RUNNING\"\n    resizing = \"RESIZING\"\n    upsizecompleted = \"UPSIZE_COMPLETED\"\n    nodeslost = \"NODES_LOST\"\n    driverhealthy = \"DRIVER_HEALTHY\"\n    driverunavailable = \"DRIVER_UNAVAILABLE\"\n    sparkexception = \"SPARK_EXCEPTION\"\n    drivernotresponding = \"DRIVER_NOT_RESPONDING\"\n    dbfsdown = \"DBFS_DOWN\"\n    metastoredown = \"METASTORE_DOWN\"\n    nodeblacklisted = \"NODE_BLACKLISTED\"\n    pinned = \"PINNED\"\n    unpinned = \"UNPINNED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterInfo","title":"<code>ClusterInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, parameters needed in order to automatically scale clusters\"\n            \" up and down based on load.\"\n        ),\n    )\n    autotermination_minutes: Optional[int] = Field(\n        None,\n        description=(\n            \"Automatically terminates the cluster after it is inactive for this time in\"\n            \" minutes. If not set, this cluster is not be automatically terminated. If\"\n            \" specified, the threshold must be between 10 and 10000 minutes. You can\"\n            \" also set this value to 0 to explicitly disable automatic termination.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values is used.\"\n        ),\n    )\n    cluster_cores: Optional[float] = Field(\n        None,\n        description=(\n            \"Number of CPU cores available for this cluster. This can be fractional\"\n            \" since certain node types are configured to share cores between Spark\"\n            \" nodes on the same instance.\"\n        ),\n    )\n    cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Canonical identifier for the cluster. This ID is retained during cluster\"\n            \" restarts and resizes, while each new cluster has a globally unique ID.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs are delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-ID&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-ID&gt;/executor`.\"\n        ),\n    )\n    cluster_log_status: Optional[LogSyncStatus] = Field(\n        None, description=\"Cluster log delivery status.\"\n    )\n    cluster_memory_mb: Optional[int] = Field(\n        None, description=\"Total amount of cluster memory, in megabytes.\"\n    )\n    cluster_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Cluster name requested by the user. This doesn\u2019t have to be unique. If not\"\n            \" specified at creation, the cluster name is an empty string.\"\n        ),\n    )\n    cluster_source: Optional[ClusterSource] = Field(\n        None,\n        description=(\n            \"Determines whether the cluster was created by a user through the UI, by\"\n            \" the Databricks Jobs scheduler, or through an API request.\"\n        ),\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Creator user name. The field won\u2019t be included in the response if the user\"\n            \" has already been deleted.\"\n        ),\n    )\n    custom_tags: Optional[List[ClusterTag]] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    default_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags that are added by Databricks regardless\"\n            \" of any custom_tags, including:\\n\\n* Vendor: Databricks\\n* Creator:\"\n            \" &lt;username-of-creator&gt;\\n* ClusterName: &lt;name-of-cluster&gt;\\n* ClusterId:\"\n            \" &lt;id-of-cluster&gt;\\n* Name: &lt;Databricks internal use&gt;  \\nOn job clusters:\\n*\"\n            \" RunName: &lt;name-of-job&gt;\\n* JobId: &lt;id-of-job&gt;  \\nOn resources used by\"\n            \" Databricks SQL:\\n* SqlEndpointId: &lt;id-of-endpoint&gt;\"\n        ),\n    )\n    docker_image: Optional[DockerImage] = Field(\n        None,\n        description=(\n            \"Docker image for a [custom\"\n            \" container](https://docs.databricks.com/clusters/custom-containers.html).\"\n        ),\n    )\n    driver: Optional[SparkNode] = Field(\n        None,\n        description=(\n            \"Node on which the Spark driver resides. The driver node contains the Spark\"\n            \" master and the Databricks application that manages the per-notebook Spark\"\n            \" REPLs.\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly - refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    executors: Optional[List[SparkNode]] = Field(\n        None, description=\"Nodes on which the Spark executors reside.\"\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of destinations can\"\n            \" be specified. The scripts are executed sequentially in the order\"\n            \" provided. If `cluster_log_conf` is specified, init script logs are sent\"\n            \" to `&lt;destination&gt;/&lt;cluster-ID&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to which the cluster belongs. Refer\"\n            \" to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html)\"\n            \" for details.\"\n        ),\n    )\n    jdbc_port: Optional[int] = Field(\n        None,\n        description=(\n            \"Port on which Spark JDBC server is listening in the driver node. No\"\n            \" service listens on this port in executor nodes.\"\n        ),\n    )\n    last_activity_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster was last active. A cluster\"\n            \" is active if there is at least one command that has not finished on the\"\n            \" cluster. This field is available after the cluster has reached a\"\n            \" `RUNNING` state. Updates to this field are made as best-effort attempts.\"\n            \" Certain versions of Spark do not support reporting of cluster activity.\"\n            \" Refer to [Automatic\"\n            \" termination](https://docs.databricks.com/clusters/clusters-manage.html#automatic-termination)\"\n            \" for details.\"\n        ),\n    )\n    last_state_loss_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time when the cluster driver last lost its state (due to a restart or\"\n            \" driver failure).\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads. A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. **Note:** When reading the properties of a\"\n            \" cluster, this field reflects the desired number of workers rather than\"\n            \" the actual number of workers. For instance, if a cluster is resized from\"\n            \" 5 to 10 workers, this field is immediately updated to reflect the target\"\n            \" size of 10 workers, whereas the workers listed in `executors` gradually\"\n            \" increase from 5 to 10 as the new nodes are provisioned.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_context_id: Optional[int] = Field(\n        None,\n        description=(\n            \"A canonical SparkContext identifier. This value _does_ change when the\"\n            \" Spark driver restarts. The pair `(cluster_id, spark_context_id)` is a\"\n            \" globally unique identifier over all Spark contexts.\"\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pairs of the form (X,Y) are exported\"\n            \" as is (that is, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nTo specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we\"\n            \" recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the\"\n            \" following example. This ensures that all default databricks managed\"\n            \" environmental variables are included as well.\\n\\nExample Spark\"\n            ' environment variables: `{\"SPARK_WORKER_MEMORY\": \"28000m\",'\n            ' \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or `{\"SPARK_DAEMON_JAVA_OPTS\":'\n            ' \"$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: Optional[str] = Field(\n        None,\n        description=(\n            \"The runtime version of the cluster. You can retrieve a list of available\"\n            \" runtime versions by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that are added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster creation request was\"\n            \" received (when the cluster entered a `PENDING` state).\"\n        ),\n    )\n    state: Optional[ClusterState] = Field(None, description=\"State of the cluster.\")\n    state_message: Optional[str] = Field(\n        None,\n        description=(\n            \"A message associated with the most recent state transition (for example,\"\n            \" the reason why the cluster entered a `TERMINATED` state). This field is\"\n            \" unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    terminated_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster was terminated, if\"\n            \" applicable.\"\n        ),\n    )\n    termination_reason: Optional[TerminationReason] = Field(\n        None,\n        description=(\n            \"Information about why the cluster was terminated. This field only appears\"\n            \" when the cluster is in a `TERMINATING` or `TERMINATED` state.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterInstance","title":"<code>ClusterInstance</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterInstance(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The canonical identifier for the cluster used by a run. This field is\"\n            \" always available for runs on existing clusters. For runs on new clusters,\"\n            \" it becomes available once the cluster is created. This value can be used\"\n            \" to view logs by browsing to `/#setting/sparkui/$cluster_id/driver-logs`.\"\n            \" The logs continue to be available after the run completes.\\n\\nThe\"\n            \" response won\u2019t include this field if the identifier is not available yet.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    spark_context_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The canonical identifier for the Spark context used by a run. This field\"\n            \" is filled in once the run begins execution. This value can be used to\"\n            \" view the Spark UI by browsing to\"\n            \" `/#setting/sparkui/$cluster_id/$spark_context_id`. The Spark UI continues\"\n            \" to be available after the run has completed.\\n\\nThe response won\u2019t\"\n            \" include this field if the identifier is not available yet.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterLibraryStatuses","title":"<code>ClusterLibraryStatuses</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterLibraryStatuses(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: Optional[str] = Field(\n        None, description=\"Unique identifier for the cluster.\"\n    )\n    library_statuses: Optional[List[LibraryFullStatus]] = Field(\n        None, description=\"Status of all libraries on the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterLogConf","title":"<code>ClusterLogConf</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterLogConf(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbfs: Optional[DbfsStorageInfo] = Field(\n        None,\n        description=(\n            \"DBFS location of cluster log. Destination must be provided. For example,\"\n            ' `{ \"dbfs\" : { \"destination\" : \"dbfs:/home/cluster_log\" } }`'\n        ),\n    )\n    s3: Optional[S3StorageInfo] = Field(\n        None,\n        description=(\n            \"S3 location of cluster log. `destination` and either `region` or\"\n            ' `endpoint` must be provided. For example, `{ \"s3\": { \"destination\" :'\n            ' \"s3://cluster_log_bucket/prefix\", \"region\" : \"us-west-2\" } }`'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSize","title":"<code>ClusterSize</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSize(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, parameters needed in order to automatically scale clusters\"\n            \" up and down based on load.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. When reading the properties of a cluster,\"\n            \" this field reflects the desired number of workers rather than the actual\"\n            \" number of workers. For instance, if a cluster is resized from 5 to 10\"\n            \" workers, this field is updated to reflect the target size of 10 workers,\"\n            \" whereas the workers listed in executors gradually increase from 5 to 10\"\n            \" as the new nodes are provisioned.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSource","title":"<code>ClusterSource</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* UI: Cluster created through the UI.\n</code></pre> <ul> <li>JOB: Cluster created by the Databricks job scheduler.</li> <li>API: Cluster created through an API call.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSource(str, Enum):\n    \"\"\"\n        * UI: Cluster created through the UI.\n    * JOB: Cluster created by the Databricks job scheduler.\n    * API: Cluster created through an API call.\n\n    \"\"\"\n\n    ui = \"UI\"\n    job = \"JOB\"\n    api = \"API\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSpec","title":"<code>ClusterSpec</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSpec(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this job. When running jobs on an existing cluster, you may need\"\n            \" to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the job. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterState","title":"<code>ClusterState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* PENDING: Indicates that a cluster is in the process of being created.\n</code></pre> <ul> <li>RUNNING: Indicates that a cluster has been started and is ready for use.</li> <li>RESTARTING: Indicates that a cluster is in the process of restarting.</li> <li>RESIZING: Indicates that a cluster is in the process of adding or removing nodes.</li> <li>TERMINATING: Indicates that a cluster is in the process of being destroyed.</li> <li>TERMINATED: Indicates that a cluster has been successfully destroyed.</li> <li>ERROR: This state is no longer used. It was used to indicate a cluster that failed to be created. <code>TERMINATING</code> and <code>TERMINATED</code> are used instead.</li> <li>UNKNOWN: Indicates that a cluster is in an unknown state. A cluster should never be in this state.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterState(str, Enum):\n    \"\"\"\n        * PENDING: Indicates that a cluster is in the process of being created.\n    * RUNNING: Indicates that a cluster has been started and is ready for use.\n    * RESTARTING: Indicates that a cluster is in the process of restarting.\n    * RESIZING: Indicates that a cluster is in the process of adding or removing nodes.\n    * TERMINATING: Indicates that a cluster is in the process of being destroyed.\n    * TERMINATED: Indicates that a cluster has been successfully destroyed.\n    * ERROR: This state is no longer used. It was used to indicate a cluster that failed to be created. `TERMINATING` and `TERMINATED` are used instead.\n    * UNKNOWN: Indicates that a cluster is in an unknown state. A cluster should never be in this state.\n\n    \"\"\"\n\n    pending = \"PENDING\"\n    running = \"RUNNING\"\n    restarting = \"RESTARTING\"\n    resizing = \"RESIZING\"\n    terminating = \"TERMINATING\"\n    terminated = \"TERMINATED\"\n    error = \"ERROR\"\n    unknown = \"UNKNOWN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterTag","title":"<code>ClusterTag</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An object with key value pairs. The key length must be between 1 and 127 UTF-8 characters, inclusive. The value length must be less than or equal to 255 UTF-8 characters. For a list of all restrictions, see AWS Tag Restrictions: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterTag(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An object with key value pairs. The key length must be between 1 and 127 UTF-8 characters, inclusive. The value length must be less than or equal to 255 UTF-8 characters. For a list of all restrictions, see AWS Tag Restrictions: &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions&gt;\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CronSchedule(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    pause_status: Optional[Literal[\"PAUSED\", \"UNPAUSED\"]] = Field(\n        None,\n        description=\"Indicate whether this schedule is paused or not.\",\n        example=\"PAUSED\",\n    )\n    quartz_cron_expression: str = Field(\n        ...,\n        description=(\n            \"A Cron expression using Quartz syntax that describes the schedule for a\"\n            \" job. See [Cron\"\n            \" Trigger](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)\"\n            \" for details. This field is required.\"\n        ),\n        example=\"20 30 * * * ?\",\n    )\n    timezone_id: str = Field(\n        ...,\n        description=(\n            \"A Java timezone ID. The schedule for a job is resolved with respect to\"\n            \" this timezone. See [Java\"\n            \" TimeZone](https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html)\"\n            \" for details. This field is required.\"\n        ),\n        example=\"Europe/London\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbfsStorageInfo","title":"<code>DbfsStorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbfsStorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    destination: Optional[str] = Field(\n        None, description=\"DBFS destination. Example: `dbfs:/my/path`\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbtOutput","title":"<code>DbtOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbtOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    artifacts_headers: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"An optional map of headers to send when retrieving the artifact from the\"\n            \" `artifacts_link`.\"\n        ),\n    )\n    artifacts_link: Optional[str] = Field(\n        None,\n        description=(\n            \"A pre-signed URL to download the (compressed) dbt artifacts. This link is\"\n            \" valid for a limited time (30 minutes). This information is only available\"\n            \" after the run has finished.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbtTask","title":"<code>DbtTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbtTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    catalog: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional name of the catalog to use. The value is the top level in the\"\n            \" 3-level namespace of Unity Catalog (catalog / schema / relation). The\"\n            \" catalog value can only be specified if a warehouse_id is specified.\"\n            \" Requires dbt-databricks &gt;= 1.1.1.\"\n        ),\n        example=\"main\",\n    )\n    commands: List = Field(\n        ...,\n        description=(\n            \"A list of dbt commands to execute. All commands must start with `dbt`.\"\n            \" This parameter must not be empty. A maximum of up to 10 commands can be\"\n            \" provided.\"\n        ),\n        example=[\"dbt deps\", \"dbt seed\", \"dbt run --models 123\"],\n    )\n    profiles_directory: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional (relative) path to the profiles directory. Can only be specified\"\n            \" if no warehouse_id is specified. If no warehouse_id is specified and this\"\n            \" folder is unset, the root directory is used.\"\n        ),\n    )\n    project_directory: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional (relative) path to the project directory, if no value is\"\n            \" provided, the root of the git repository is used.\"\n        ),\n    )\n    schema_: Optional[str] = Field(\n        None,\n        alias=\"schema\",\n        description=(\n            \"Optional schema to write to. This parameter is only used when a\"\n            \" warehouse_id is also provided. If not provided, the `default` schema is\"\n            \" used.\"\n        ),\n    )\n    warehouse_id: Optional[str] = Field(\n        None,\n        description=(\n            \"ID of the SQL warehouse to connect to. If provided, we automatically\"\n            \" generate and provide the profile and connection details to dbt. It can be\"\n            \" overridden on a per-command basis by using the `--profiles-dir` command\"\n            \" line argument.\"\n        ),\n        example=\"30dade0507d960d1\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DockerBasicAuth","title":"<code>DockerBasicAuth</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DockerBasicAuth(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    password: Optional[str] = Field(\n        None, description=\"Password for the Docker repository.\"\n    )\n    username: Optional[str] = Field(\n        None, description=\"User name for the Docker repository.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DockerImage","title":"<code>DockerImage</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DockerImage(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    basic_auth: Optional[DockerBasicAuth] = Field(\n        None, description=\"Basic authentication information for Docker repository.\"\n    )\n    url: Optional[str] = Field(None, description=\"URL for the Docker image.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Error","title":"<code>Error</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Error(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    error_code: Optional[str] = Field(\n        None, description=\"Error code\", example=\"INTERNAL_ERROR\"\n    )\n    message: Optional[str] = Field(\n        None,\n        description=(\n            \"Human-readable error message that describes the cause of the error.\"\n        ),\n        example=\"Unexpected error.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.EventDetails","title":"<code>EventDetails</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class EventDetails(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"* For created clusters, the attributes of the cluster.\\n* For edited\"\n            \" clusters, the new attributes of the cluster.\"\n        ),\n    )\n    cause: Optional[ResizeCause] = Field(\n        None, description=\"The cause of a change in target size.\"\n    )\n    cluster_size: Optional[ClusterSize] = Field(\n        None,\n        description=\"The cluster size that was set in the cluster creation or edit.\",\n    )\n    current_num_workers: Optional[int] = Field(\n        None, description=\"The number of nodes in the cluster.\"\n    )\n    previous_attributes: Optional[AwsAttributes] = Field(\n        None, description=\"The cluster attributes before a cluster was edited.\"\n    )\n    previous_cluster_size: Optional[ClusterSize] = Field(\n        None, description=\"The size of the cluster before an edit or resize.\"\n    )\n    reason: Optional[TerminationReason] = Field(\n        None,\n        description=(\n            \"A termination reason:\\n\\n* On a `TERMINATED` event, the reason for the\"\n            \" termination.\\n* On a `RESIZE_COMPLETE` event, indicates the reason that\"\n            \" we failed to acquire some nodes.\"\n        ),\n    )\n    target_num_workers: Optional[int] = Field(\n        None, description=\"The targeted number of nodes in the cluster.\"\n    )\n    user: Optional[str] = Field(\n        None,\n        description=(\n            \"The user that caused the event to occur. (Empty if it was done by\"\n            \" Databricks.)\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.FileStorageInfo","title":"<code>FileStorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class FileStorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    destination: Optional[str] = Field(\n        None, description=\"File destination. Example: `file:/my/file.sh`\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSnapshot","title":"<code>GitSnapshot</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>Read-only state of the remote repository at the time the job was run. This field is only included on job runs.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSnapshot(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    Read-only state of the remote repository at the time the job was run. This field is only included on job runs.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    used_commit: Optional[str] = Field(\n        None,\n        description=(\n            \"Commit that was used to execute the run. If git_branch was specified, this\"\n            \" points to the HEAD of the branch at the time of the run; if git_tag was\"\n            \" specified, this points to the commit the tag points to.\"\n        ),\n        example=\"4506fdf41e9fa98090570a34df7a5bce163ff15f\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSource","title":"<code>GitSource</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <pre><code>This functionality is in Public Preview.\n</code></pre> <p>An optional specification for a remote repository containing the notebooks used by this job's notebook tasks.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSource(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n        This functionality is in Public Preview.\n\n    An optional specification for a remote repository containing the notebooks used by this job's notebook tasks.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    git_branch: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the branch to be checked out and used by this job. This field\"\n            \" cannot be specified in conjunction with git_tag or git_commit.\\nThe\"\n            \" maximum length is 255 characters.\"\n        ),\n        example=\"main\",\n    )\n    git_commit: Optional[str] = Field(\n        None,\n        description=(\n            \"Commit to be checked out and used by this job. This field cannot be\"\n            \" specified in conjunction with git_branch or git_tag.\\nThe maximum length\"\n            \" is 64 characters.\"\n        ),\n        example=\"e0056d01\",\n    )\n    git_provider: Optional[\n        Literal[\n            \"gitHub\",\n            \"bitbucketCloud\",\n            \"azureDevOpsServices\",\n            \"gitHubEnterprise\",\n            \"bitbucketServer\",\n            \"gitLab\",\n            \"gitLabEnterpriseEdition\",\n            \"awsCodeCommit\",\n        ]\n    ] = Field(\n        None,\n        description=(\n            \"Unique identifier of the service used to host the Git repository. The\"\n            \" value is case insensitive.\"\n        ),\n        example=\"github\",\n    )\n    git_snapshot: Optional[GitSnapshot] = None\n    git_tag: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the tag to be checked out and used by this job. This field cannot\"\n            \" be specified in conjunction with git_branch or git_commit.\\nThe maximum\"\n            \" length is 255 characters.\"\n        ),\n        example=\"release-1.0.0\",\n    )\n    git_url: Optional[str] = Field(\n        None,\n        description=(\n            \"URL of the repository to be cloned by this job.\\nThe maximum length is 300\"\n            \" characters.\"\n        ),\n        example=\"https://github.com/databricks/databricks-cli\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSource1","title":"<code>GitSource1</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSource1(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[GitSource, Any, Any, Any] = Field(\n        ...,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GroupName","title":"<code>GroupName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GroupName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"Group name. There are two built-in groups: `users` for all users, and\"\n            \" `admins` for administrators.\"\n        ),\n        example=\"users\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.InitScriptInfo","title":"<code>InitScriptInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class InitScriptInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    s3: Optional[S3StorageInfo] = Field(\n        None,\n        alias=\"S3\",\n        description=(\n            \"S3 location of init script. Destination and either region or endpoint must\"\n            ' be provided. For example, `{ \"s3\": { \"destination\" :'\n            ' \"s3://init_script_bucket/prefix\", \"region\" : \"us-west-2\" } }`'\n        ),\n    )\n    dbfs: Optional[DbfsStorageInfo] = Field(\n        None,\n        description=(\n            \"DBFS location of init script. Destination must be provided. For example,\"\n            ' `{ \"dbfs\" : { \"destination\" : \"dbfs:/home/init_script\" } }`'\n        ),\n    )\n    file: Optional[FileStorageInfo] = Field(\n        None,\n        description=(\n            \"File location of init script. Destination must be provided. For example,\"\n            ' `{ \"file\" : { \"destination\" : \"file:/my/local/file.sh\" } }`'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.IsOwner","title":"<code>IsOwner</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Perimssion that represents ownership of the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class IsOwner(str, Enum):\n    \"\"\"\n    Perimssion that represents ownership of the job.\n    \"\"\"\n\n    isowner = \"IS_OWNER\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Job","title":"<code>Job</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Job(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    created_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this job was created in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC).\"\n        ),\n        example=1601370337343,\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The creator user name. This field won\u2019t be included in the response if the\"\n            \" user has already been deleted.\"\n        ),\n        example=\"user.name@databricks.com\",\n    )\n    job_id: Optional[int] = Field(\n        None, description=\"The canonical identifier for this job.\", example=11223344\n    )\n    settings: Optional[JobSettings] = Field(\n        None,\n        description=(\n            \"Settings for this job and all of its runs. These settings can be updated\"\n            \" using the `resetJob` method.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobCluster","title":"<code>JobCluster</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobCluster(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    job_cluster_key: str = Field(\n        ...,\n        description=(\n            \"A unique name for the job cluster. This field is required and must be\"\n            \" unique within the job.\\n`JobTaskSettings` may refer to this field to\"\n            \" determine which cluster to launch for the task execution.\"\n        ),\n        example=\"auto_scaling_cluster\",\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n    new_cluster: Optional[NewCluster] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobEmailNotifications","title":"<code>JobEmailNotifications</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobEmailNotifications(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    no_alert_for_skipped_runs: Optional[bool] = Field(\n        None,\n        description=(\n            \"If true, do not send email to recipients specified in `on_failure` if the\"\n            \" run is skipped.\"\n        ),\n        example=False,\n    )\n    on_failure: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to notify when a run completes unsuccessfully. A\"\n            \" run is considered unsuccessful if it ends with an `INTERNAL_ERROR`\"\n            \" `life_cycle_state` or a `SKIPPED`, `FAILED`, or `TIMED_OUT`\"\n            \" `result_state`. If not specified on job creation, reset, or update, or\"\n            \" the list is empty, then notifications are not sent. Job-level failure\"\n            \" notifications are sent only once after the entire job run (including all\"\n            \" of its retries) has failed. Notifications are not sent when failed job\"\n            \" runs are retried. To receive a failure notification after every failed\"\n            \" task (including every failed retry), use task-level notifications\"\n            \" instead.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n    on_start: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to be notified when a run begins. If not\"\n            \" specified on job creation, reset, or update, the list is empty, and\"\n            \" notifications are not sent.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n    on_success: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to be notified when a run successfully\"\n            \" completes. A run is considered to have completed successfully if it ends\"\n            \" with a `TERMINATED` `life_cycle_state` and a `SUCCESSFUL` result_state.\"\n            \" If not specified on job creation, reset, or update, the list is empty,\"\n            \" and notifications are not sent.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobSettings","title":"<code>JobSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    email_notifications: Optional[JobEmailNotifications] = Field(\n        None,\n        description=(\n            \"An optional set of email addresses that is notified when runs of this job\"\n            \" begin or complete as well as when this job is deleted. The default\"\n            \" behavior is to not send any emails.\"\n        ),\n    )\n    format: Optional[Literal[\"SINGLE_TASK\", \"MULTI_TASK\"]] = Field(\n        None,\n        description=(\n            \"Used to tell what is the format of the job. This field is ignored in\"\n            \" Create/Update/Reset calls. When using the Jobs API 2.1 this value is\"\n            ' always set to `\"MULTI_TASK\"`.'\n        ),\n        example=\"MULTI_TASK\",\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    job_clusters: Optional[List[JobCluster]] = Field(\n        None,\n        description=(\n            \"A list of job cluster specifications that can be shared and reused by\"\n            \" tasks of this job. Libraries cannot be declared in a shared job cluster.\"\n            \" You must declare dependent libraries in task settings.\"\n        ),\n        example=[\n            {\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n            }\n        ],\n        max_items=100,\n    )\n    max_concurrent_runs: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional maximum allowed number of concurrent runs of the job.\\n\\nSet\"\n            \" this value if you want to be able to execute multiple runs of the same\"\n            \" job concurrently. This is useful for example if you trigger your job on a\"\n            \" frequent schedule and want to allow consecutive runs to overlap with each\"\n            \" other, or if you want to trigger multiple runs which differ by their\"\n            \" input parameters.\\n\\nThis setting affects only new runs. For example,\"\n            \" suppose the job\u2019s concurrency is 4 and there are 4 concurrent active\"\n            \" runs. Then setting the concurrency to 3 won\u2019t kill any of the active\"\n            \" runs. However, from then on, new runs are skipped unless there are fewer\"\n            \" than 3 active runs.\\n\\nThis value cannot exceed 1000\\\\. Setting this\"\n            \" value to 0 causes all new runs to be skipped. The default behavior is to\"\n            \" allow only 1 concurrent run.\"\n        ),\n        example=10,\n    )\n    name: Optional[str] = Field(\n        \"Untitled\",\n        description=\"An optional name for the job.\",\n        example=\"A multitask job\",\n    )\n    schedule: Optional[CronSchedule] = Field(\n        None,\n        description=(\n            \"An optional periodic schedule for this job. The default behavior is that\"\n            \" the job only runs when triggered by clicking \u201cRun Now\u201d in the Jobs UI or\"\n            \" sending an API request to `runNow`.\"\n        ),\n    )\n    tags: Optional[Dict[str, Any]] = Field(\n        \"{}\",\n        description=(\n            \"A map of tags associated with the job. These are forwarded to the cluster\"\n            \" as cluster tags for jobs clusters, and are subject to the same\"\n            \" limitations as cluster tags. A maximum of 25 tags can be added to the\"\n            \" job.\"\n        ),\n        example={\"cost-center\": \"engineering\", \"team\": \"jobs\"},\n    )\n    tasks: Optional[List[JobTaskSettings]] = Field(\n        None,\n        description=\"A list of task specifications to be executed by this job.\",\n        example=[\n            {\n                \"depends_on\": [],\n                \"description\": \"Extracts session data from events\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"retry_on_timeout\": False,\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.Sessionize\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                },\n                \"task_key\": \"Sessionize\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [],\n                \"description\": \"Ingests order data\",\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"retry_on_timeout\": False,\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.OrdersIngest\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                },\n                \"task_key\": \"Orders_Ingest\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"base_parameters\": {\"age\": \"35\", \"name\": \"John Doe\"},\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"retry_on_timeout\": False,\n                \"task_key\": \"Match\",\n                \"timeout_seconds\": 86400,\n            },\n        ],\n        max_items=100,\n    )\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job. The default behavior\"\n            \" is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when runs of this job\"\n            \" begin or complete. The default behavior is to not send any system\"\n            \" notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobTask","title":"<code>JobTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this job must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this job must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None,\n        description=\"If spark_jar_task, indicates that this job must run a JAR.\",\n        example=\"\",\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this job must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this job must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobTaskSettings","title":"<code>JobTaskSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobTaskSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    description: Optional[TaskDescription] = None\n    email_notifications: Optional[JobEmailNotifications] = Field(\n        None,\n        description=(\n            \"An optional set of email addresses that is notified when runs of this task\"\n            \" begin or complete as well as when this task is deleted. The default\"\n            \" behavior is to not send any emails.\"\n        ),\n    )\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this task. When running tasks on an existing cluster, you may\"\n            \" need to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    job_cluster_key: Optional[str] = Field(\n        None,\n        description=(\n            \"If job_cluster_key, this task is executed reusing the cluster specified in\"\n            \" `job.settings.job_clusters`.\"\n        ),\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the task. The default value is an empty list.\"\n        ),\n    )\n    max_retries: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional maximum number of times to retry an unsuccessful run. A run is\"\n            \" considered to be unsuccessful if it completes with the `FAILED`\"\n            \" result_state or `INTERNAL_ERROR` `life_cycle_state`. The value -1 means\"\n            \" to retry indefinitely and the value 0 means to never retry. The default\"\n            \" behavior is to never retry.\"\n        ),\n        example=10,\n    )\n    min_retry_interval_millis: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional minimal interval in milliseconds between the start of the\"\n            \" failed run and the subsequent retry run. The default behavior is that\"\n            \" unsuccessful runs are immediately retried.\"\n        ),\n        example=2000,\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this task must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this task must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    retry_on_timeout: Optional[bool] = Field(\n        None,\n        description=(\n            \"An optional policy to specify whether to retry a task when it times out.\"\n            \" The default behavior is to not retry on timeout.\"\n        ),\n        example=True,\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this task must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this task must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this task must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    task_key: TaskKey\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job task. The default\"\n            \" behavior is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when the run begins or\"\n            \" completes. The default behavior is to not send any system notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Library","title":"<code>Library</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Library(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cran: Optional[RCranLibrary] = Field(\n        None, description=\"If cran, specification of a CRAN library to be installed.\"\n    )\n    egg: Optional[str] = Field(\n        None,\n        description=(\n            \"If egg, URI of the egg to be installed. DBFS and S3 URIs are supported.\"\n            ' For example: `{ \"egg\": \"dbfs:/my/egg\" }` or `{ \"egg\":'\n            ' \"s3://my-bucket/egg\" }`. If S3 is used, make sure the cluster has read'\n            \" access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI.\"\n        ),\n        example=\"dbfs:/my/egg\",\n    )\n    jar: Optional[str] = Field(\n        None,\n        description=(\n            \"If jar, URI of the JAR to be installed. DBFS and S3 URIs are supported.\"\n            ' For example: `{ \"jar\": \"dbfs:/mnt/databricks/library.jar\" }` or `{ \"jar\":'\n            ' \"s3://my-bucket/library.jar\" }`. If S3 is used, make sure the cluster has'\n            \" read access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI.\"\n        ),\n        example=\"dbfs:/my-jar.jar\",\n    )\n    maven: Optional[MavenLibrary] = Field(\n        None,\n        description=(\n            \"If maven, specification of a Maven library to be installed. For example:\"\n            ' `{ \"coordinates\": \"org.jsoup:jsoup:1.7.2\" }`'\n        ),\n    )\n    pypi: Optional[PythonPyPiLibrary] = Field(\n        None,\n        description=(\n            \"If pypi, specification of a PyPI library to be installed. Specifying the\"\n            \" `repo` field is optional and if not specified, the default pip index is\"\n            ' used. For example: `{ \"package\": \"simplejson\", \"repo\":'\n            ' \"https://my-repo.com\" }`'\n        ),\n    )\n    whl: Optional[str] = Field(\n        None,\n        description=(\n            \"If whl, URI of the wheel or zipped wheels to be installed. DBFS and S3\"\n            ' URIs are supported. For example: `{ \"whl\": \"dbfs:/my/whl\" }` or `{ \"whl\":'\n            ' \"s3://my-bucket/whl\" }`. If S3 is used, make sure the cluster has read'\n            \" access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI. Also the wheel file name needs to\"\n            \" use the [correct\"\n            \" convention](https://www.python.org/dev/peps/pep-0427/#file-format). If\"\n            \" zipped wheels are to be installed, the file name suffix should be\"\n            \" `.wheelhouse.zip`.\"\n        ),\n        example=\"dbfs:/my/whl\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LibraryFullStatus","title":"<code>LibraryFullStatus</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LibraryFullStatus(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    is_library_for_all_clusters: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether the library was set to be installed on all clusters via the\"\n            \" libraries UI.\"\n        ),\n    )\n    library: Optional[Library] = Field(\n        None, description=\"Unique identifier for the library.\"\n    )\n    messages: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"All the info and warning messages that have occurred so far for this\"\n            \" library.\"\n        ),\n    )\n    status: Optional[LibraryInstallStatus] = Field(\n        None, description=\"Status of installing the library on the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LibraryInstallStatus","title":"<code>LibraryInstallStatus</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PENDING`: No action has yet been taken to install the library. This state should be very short lived.\n</code></pre> <ul> <li><code>RESOLVING</code>: Metadata necessary to install the library is being retrieved from the provided repository. For Jar, Egg, and Whl libraries, this step is a no-op.</li> <li><code>INSTALLING</code>: The library is actively being installed, either by adding resources to Spark or executing system commands inside the Spark nodes.</li> <li><code>INSTALLED</code>: The library has been successfully instally.</li> <li><code>SKIPPED</code>: Installation on a Databricks Runtime 7.0 or above cluster was skipped due to Scala version incompatibility.</li> <li><code>FAILED</code>: Some step in installation failed. More information can be found in the messages field.</li> <li><code>UNINSTALL_ON_RESTART</code>: The library has been marked for removal. Libraries can be removed only when clusters are restarted, so libraries that enter this state remains until the cluster is restarted.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LibraryInstallStatus(str, Enum):\n    \"\"\"\n        * `PENDING`: No action has yet been taken to install the library. This state should be very short lived.\n    * `RESOLVING`: Metadata necessary to install the library is being retrieved from the provided repository. For Jar, Egg, and Whl libraries, this step is a no-op.\n    * `INSTALLING`: The library is actively being installed, either by adding resources to Spark or executing system commands inside the Spark nodes.\n    * `INSTALLED`: The library has been successfully instally.\n    * `SKIPPED`: Installation on a Databricks Runtime 7.0 or above cluster was skipped due to Scala version incompatibility.\n    * `FAILED`: Some step in installation failed. More information can be found in the messages field.\n    * `UNINSTALL_ON_RESTART`: The library has been marked for removal. Libraries can be removed only when clusters are restarted, so libraries that enter this state remains until the cluster is restarted.\n    \"\"\"\n\n    pending = \"PENDING\"\n    resolving = \"RESOLVING\"\n    installing = \"INSTALLING\"\n    installed = \"INSTALLED\"\n    skipped = \"SKIPPED\"\n    failed = \"FAILED\"\n    uninstallonrestart = \"UNINSTALL_ON_RESTART\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ListOrder","title":"<code>ListOrder</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `DESC`: Descending order.\n</code></pre> <ul> <li><code>ASC</code>: Ascending order.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ListOrder(str, Enum):\n    \"\"\"\n        * `DESC`: Descending order.\n    * `ASC`: Ascending order.\n    \"\"\"\n\n    desc = \"DESC\"\n    asc = \"ASC\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LogSyncStatus","title":"<code>LogSyncStatus</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LogSyncStatus(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    last_attempted: Optional[int] = Field(\n        None,\n        description=(\n            \"The timestamp of last attempt. If the last attempt fails, last_exception\"\n            \" contains the exception in the last attempt.\"\n        ),\n    )\n    last_exception: Optional[str] = Field(\n        None,\n        description=(\n            \"The exception thrown in the last attempt, it would be null (omitted in the\"\n            \" response) if there is no exception in last attempted.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.MavenLibrary","title":"<code>MavenLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class MavenLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    coordinates: str = Field(\n        ...,\n        description=(\n            \"Gradle-style Maven coordinates. For example: `org.jsoup:jsoup:1.7.2`. This\"\n            \" field is required.\"\n        ),\n        example=\"org.jsoup:jsoup:1.7.2\",\n    )\n    exclusions: Optional[List[str]] = Field(\n        None,\n        description=(\n            'List of dependences to exclude. For example: `[\"slf4j:slf4j\",'\n            ' \"*:hadoop-client\"]`.\\n\\nMaven dependency exclusions:'\n            \" &lt;https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html&gt;.\"\n        ),\n        example=[\"slf4j:slf4j\", \"*:hadoop-client\"],\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"Maven repo to install the Maven package from. If omitted, both Maven\"\n            \" Central Repository and Spark Packages are searched.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NewCluster","title":"<code>NewCluster</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NewCluster(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, the required parameters to automatically scale clusters up\"\n            \" and down based on load.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values is used.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs are delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-id&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-id&gt;/executor`.\"\n        ),\n    )\n    custom_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    driver_instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to use for the driver node. You must\"\n            \" also specify `instance_pool_id`. Refer to [Instance Pools\"\n            \" API](https://docs.databricks.com/dev-tools/api/latest/instance-pools.html)\"\n            \" for details.\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly - refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    enable_local_disk_encryption: Optional[bool] = Field(\n        None,\n        description=(\n            \"Determines whether encryption of disks locally attached to the cluster is\"\n            \" enabled.\"\n        ),\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of scripts can be\"\n            \" specified. The scripts are executed sequentially in the order provided.\"\n            \" If `cluster_log_conf` is specified, init script logs are sent to\"\n            \" `&lt;destination&gt;/&lt;cluster-id&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to use for cluster nodes. If\"\n            \" `driver_instance_pool_id` is present, `instance_pool_id` is used for\"\n            \" worker nodes only. Otherwise, it is used for both the driver node and\"\n            \" worker nodes. Refer to [Instance Pools\"\n            \" API](https://docs.databricks.com/dev-tools/api/latest/instance-pools.html)\"\n            \" for details.\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. When reading the properties of a cluster,\"\n            \" this field reflects the desired number of workers rather than the actual\"\n            \" current number of workers. For example, if a cluster is resized from 5 to\"\n            \" 10 workers, this field immediately updates to reflect the target size of\"\n            \" 10 workers, whereas the workers listed in `spark_info` gradually increase\"\n            \" from 5 to 10 as the new nodes are provisioned.\"\n        ),\n    )\n    policy_id: Optional[str] = Field(\n        None,\n        description=(\n            \"A [cluster\"\n            \" policy](https://docs.databricks.com/dev-tools/api/latest/policies.html)\"\n            \" ID. Either `node_type_id` or `instance_pool_id` must be specified in the\"\n            \" cluster policy if they are not specified in this job cluster object.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pair of the form (X,Y) are exported\"\n            \" as is (for example, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nTo specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we\"\n            \" recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the\"\n            \" following example. This ensures that all default databricks managed\"\n            \" environmental variables are included as well.\\n\\nExample Spark\"\n            ' environment variables: `{\"SPARK_WORKER_MEMORY\": \"28000m\",'\n            ' \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or `{\"SPARK_DAEMON_JAVA_OPTS\":'\n            ' \"$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: str = Field(\n        ...,\n        description=(\n            \"The Spark version of the cluster. A list of available Spark versions can\"\n            \" be retrieved by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that are added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NodeType","title":"<code>NodeType</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NodeType(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    description: str = Field(\n        ...,\n        description=(\n            \"A string description associated with this node type. This field is\"\n            \" required.\"\n        ),\n    )\n    instance_type_id: str = Field(\n        ...,\n        description=(\n            \"An identifier for the type of hardware that this node runs on. This field\"\n            \" is required.\"\n        ),\n    )\n    is_deprecated: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether the node type is deprecated. Non-deprecated node types offer\"\n            \" greater performance.\"\n        ),\n    )\n    memory_mb: int = Field(\n        ...,\n        description=(\n            \"Memory (in MB) available for this node type. This field is required.\"\n        ),\n    )\n    node_info: Optional[ClusterCloudProviderNodeInfo] = Field(\n        None, description=\"Node type info reported by the cloud provider.\"\n    )\n    node_type_id: str = Field(\n        ..., description=\"Unique identifier for this node type. This field is required.\"\n    )\n    num_cores: Optional[float] = Field(\n        None,\n        description=(\n            \"Number of CPU cores available for this node type. This can be fractional\"\n            \" if the number of cores on a machine instance is not divisible by the\"\n            \" number of Spark nodes on that machine. This field is required.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NotebookOutput","title":"<code>NotebookOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NotebookOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    result: Optional[str] = Field(\n        None,\n        description=(\n            \"The value passed to\"\n            \" [dbutils.notebook.exit()](https://docs.databricks.com/notebooks/notebook-workflows.html#notebook-workflows-exit).\"\n            \" Databricks restricts this API to return the first 5 MB of the value. For\"\n            \" a larger result, your job can store the results in a cloud storage\"\n            \" service. This field is absent if `dbutils.notebook.exit()` was never\"\n            \" called.\"\n        ),\n        example=\"An arbitrary string passed by calling dbutils.notebook.exit(...)\",\n    )\n    truncated: Optional[bool] = Field(\n        None, description=\"Whether or not the result was truncated.\", example=False\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NotebookTask","title":"<code>NotebookTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NotebookTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    base_parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Base parameters to be used for each run of this job. If the run is\"\n            \" initiated by a call to\"\n            \" [`run-now`](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunNow)\"\n            \" with parameters specified, the two parameters maps are merged. If the\"\n            \" same key is specified in `base_parameters` and in `run-now`, the value\"\n            \" from `run-now` is used.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\\n\\nIf the notebook\"\n            \" takes a parameter that is not specified in the job\u2019s `base_parameters` or\"\n            \" the `run-now` override parameters, the default value from the notebook is\"\n            \" used.\\n\\nRetrieve these parameters in a notebook using\"\n            \" [dbutils.widgets.get](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-widgets).\"\n        ),\n        example={\"age\": 35, \"name\": \"John Doe\"},\n    )\n    notebook_path: str = Field(\n        ...,\n        description=(\n            \"The path of the notebook to be run in the Databricks workspace or remote\"\n            \" repository. For notebooks stored in the Databricks workspace, the path\"\n            \" must be absolute and begin with a slash. For notebooks stored in a remote\"\n            \" repository, the path must be relative. This field is required.\"\n        ),\n        example=\"/Users/user.name@databricks.com/notebook_to_run\",\n    )\n    source: Optional[Literal[\"WORKSPACE\", \"GIT\"]] = Field(\n        None,\n        description=(\n            \"Optional location type of the notebook. When set to `WORKSPACE`, the\"\n            \" notebook will be retrieved from the local Databricks workspace. When set\"\n            \" to `GIT`, the notebook will be retrieved from a Git repository defined in\"\n            \" `git_source`. If the value is empty, the task will use `GIT` if\"\n            \" `git_source` is defined and `WORKSPACE` otherwise.\"\n        ),\n        example=\"WORKSPACE\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnFailureItem","title":"<code>OnFailureItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnFailureItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnStartItem","title":"<code>OnStartItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnStartItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnSucces","title":"<code>OnSucces</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnSucces(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ParameterPair","title":"<code>ParameterPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An object with additional information about why a cluster was terminated. The object keys are one of <code>TerminationParameter</code> and the value is the termination information.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ParameterPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An object with additional information about why a cluster was terminated. The object keys are one of `TerminationParameter` and the value is the termination information.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PermissionLevel","title":"<code>PermissionLevel</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PermissionLevel(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[CanManage, CanManageRun, CanView, IsOwner] = Field(\n        ..., description=\"Permission level to grant.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PermissionLevelForGroup","title":"<code>PermissionLevelForGroup</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PermissionLevelForGroup(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[CanManage, CanManageRun, CanView] = Field(\n        ..., description=\"Permission level to grant.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PipelineParams","title":"<code>PipelineParams</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PipelineParams(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    full_refresh: Optional[bool] = Field(\n        None, description=\"If true, triggers a full refresh on the delta live table.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PipelineTask","title":"<code>PipelineTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PipelineTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    full_refresh: Optional[bool] = Field(\n        False,\n        description=(\n            \"If true, a full refresh will be triggered on the delta live table.\"\n        ),\n    )\n    pipeline_id: Optional[str] = Field(\n        None,\n        description=\"The full name of the pipeline task to execute.\",\n        example=\"a12cd3e4-0ab1-1abc-1a2b-1a2bcd3e4fg5\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PoolClusterTerminationCode","title":"<code>PoolClusterTerminationCode</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.\n</code></pre> <ul> <li>INSTANCE_POOL_NOT_FOUND_FAILURE: The pool specified by the cluster is no longer active or doesn\u2019t exist.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PoolClusterTerminationCode(str, Enum):\n    \"\"\"\n        * INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.\n    * INSTANCE_POOL_NOT_FOUND_FAILURE: The pool specified by the cluster is no longer active or doesn\u2019t exist.\n    \"\"\"\n\n    instancepoolmaxcapacityfailure = \"INSTANCE_POOL_MAX_CAPACITY_FAILURE\"\n    instancepoolnotfoundfailure = \"INSTANCE_POOL_NOT_FOUND_FAILURE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PythonPyPiLibrary","title":"<code>PythonPyPiLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PythonPyPiLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    package: str = Field(\n        ...,\n        description=(\n            \"The name of the PyPI package to install. An optional exact version\"\n            \" specification is also supported. Examples: `simplejson` and\"\n            \" `simplejson==3.8.0`. This field is required.\"\n        ),\n        example=\"simplejson==3.8.0\",\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"The repository where the package can be found. If not specified, the\"\n            \" default pip index is used.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PythonWheelTask","title":"<code>PythonWheelTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PythonWheelTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    entry_point: Optional[str] = Field(\n        None,\n        description=(\n            \"Named entry point to use, if it does not exist in the metadata of the\"\n            \" package it executes the function from the package directly using\"\n            \" `$packageName.$entryPoint()`\"\n        ),\n    )\n    named_parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to Python wheel task in the form of\"\n            ' `[\"--name=task\", \"--data=dbfs:/path/to/data.json\"]`. Leave it empty if'\n            \" `parameters` is not null.\"\n        ),\n        example={\"data\": \"dbfs:/path/to/data.json\", \"name\": \"task\"},\n    )\n    package_name: Optional[str] = Field(\n        None, description=\"Name of the package to execute\"\n    )\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to Python wheel task. Leave it empty if\"\n            \" `named_parameters` is not null.\"\n        ),\n        example=[\"--name=task\", \"one\", \"two\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RCranLibrary","title":"<code>RCranLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RCranLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    package: str = Field(\n        ...,\n        description=\"The name of the CRAN package to install. This field is required.\",\n        example=\"geojson\",\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"The repository where the package can be found. If not specified, the\"\n            \" default CRAN repo is used.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairHistory","title":"<code>RepairHistory</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairHistory(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    repair_history: Optional[List[RepairHistoryItem]] = Field(\n        None, description=\"The repair history of the run.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairHistoryItem","title":"<code>RepairHistoryItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairHistoryItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    end_time: Optional[int] = Field(\n        None, description=\"The end time of the (repaired) run.\", example=1625060863413\n    )\n    id: Optional[int] = Field(\n        None,\n        description=(\n            \"The ID of the repair. Only returned for the items that represent a repair\"\n            \" in `repair_history`.\"\n        ),\n        example=734650698524280,\n    )\n    start_time: Optional[int] = Field(\n        None, description=\"The start time of the (repaired) run.\", example=1625060460483\n    )\n    state: Optional[RunState] = None\n    task_run_ids: Optional[List[int]] = Field(\n        None,\n        description=(\n            \"The run IDs of the task runs that ran as part of this repair history item.\"\n        ),\n        example=[1106460542112844, 988297789683452],\n    )\n    type: Optional[Literal[\"ORIGINAL\", \"REPAIR\"]] = Field(\n        None,\n        description=(\n            \"The repair history item type. Indicates whether a run is the original run\"\n            \" or a repair run.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairRunInput","title":"<code>RepairRunInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairRunInput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    latest_repair_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The ID of the latest repair. This parameter is not required when repairing\"\n            \" a run for the first time, but must be provided on subsequent requests to\"\n            \" repair the same run.\"\n        ),\n        example=734650698524280,\n    )\n    rerun_all_failed_tasks: Optional[bool] = Field(\n        False,\n        description=(\n            \"If true, repair all failed tasks. Only one of rerun_tasks or\"\n            \" rerun_all_failed_tasks can be used.\"\n        ),\n    )\n    rerun_tasks: Optional[List[str]] = Field(\n        None,\n        description=\"The task keys of the task runs to repair.\",\n        example=[\"task0\", \"task1\"],\n    )\n    run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The job run ID of the run to repair. The run must not be in progress.\"\n        ),\n        example=455644833,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ResizeCause","title":"<code>ResizeCause</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `AUTOSCALE`: Automatically resized based on load.\n</code></pre> <ul> <li><code>USER_REQUEST</code>: User requested a new size.</li> <li><code>AUTORECOVERY</code>: Autorecovery monitor resized the cluster after it lost a node.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ResizeCause(str, Enum):\n    \"\"\"\n        * `AUTOSCALE`: Automatically resized based on load.\n    * `USER_REQUEST`: User requested a new size.\n    * `AUTORECOVERY`: Autorecovery monitor resized the cluster after it lost a node.\n    \"\"\"\n\n    autoscale = \"AUTOSCALE\"\n    userrequest = \"USER_REQUEST\"\n    autorecovery = \"AUTORECOVERY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Run","title":"<code>Run</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Run(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attempt_number: Optional[int] = Field(\n        None,\n        description=(\n            \"The sequence number of this run attempt for a triggered job run. The\"\n            \" initial attempt of a run has an attempt_number of 0\\\\. If the initial run\"\n            \" attempt fails, and the job has a retry policy (`max_retries` \\\\&gt; 0),\"\n            \" subsequent runs are created with an `original_attempt_run_id` of the\"\n            \" original attempt\u2019s ID and an incrementing `attempt_number`. Runs are\"\n            \" retried only until they succeed, and the maximum `attempt_number` is the\"\n            \" same as the `max_retries` value for the job.\"\n        ),\n        example=0,\n    )\n    cleanup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to terminate the cluster and clean up any\"\n            \" associated artifacts. The total duration of the run is the sum of the\"\n            \" setup_duration, the execution_duration, and the cleanup_duration.\"\n        ),\n        example=0,\n    )\n    cluster_instance: Optional[ClusterInstance] = Field(\n        None,\n        description=(\n            \"The cluster used for this run. If the run is specified to use a new\"\n            \" cluster, this field is set once the Jobs service has requested a cluster\"\n            \" for the run.\"\n        ),\n    )\n    cluster_spec: Optional[ClusterSpec] = Field(\n        None,\n        description=(\n            \"A snapshot of the job\u2019s cluster specification when this run was created.\"\n        ),\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The creator user name. This field won\u2019t be included in the response if the\"\n            \" user has already been deleted.\"\n        ),\n        example=\"user.name@databricks.com\",\n    )\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run ended in epoch milliseconds (milliseconds since\"\n            \" 1/1/1970 UTC). This field is set to 0 if the job is still running.\"\n        ),\n        example=1625060863413,\n    )\n    execution_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to execute the commands in the JAR or\"\n            \" notebook until they completed, failed, timed out, were cancelled, or\"\n            \" encountered an unexpected error.\"\n        ),\n        example=0,\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    job_clusters: Optional[List[JobCluster]] = Field(\n        None,\n        description=(\n            \"A list of job cluster specifications that can be shared and reused by\"\n            \" tasks of this job. Libraries cannot be declared in a shared job cluster.\"\n            \" You must declare dependent libraries in task settings.\"\n        ),\n        example=[\n            {\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n            }\n        ],\n        max_items=100,\n    )\n    job_id: Optional[int] = Field(\n        None,\n        description=\"The canonical identifier of the job that contains this run.\",\n        example=11223344,\n    )\n    number_in_job: Optional[int] = Field(\n        None,\n        deprecated=True,\n        description=(\n            \"A unique identifier for this job run. This is set to the same value as\"\n            \" `run_id`.\"\n        ),\n        example=455644833,\n    )\n    original_attempt_run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"If this run is a retry of a prior run attempt, this field contains the\"\n            \" run_id of the original attempt; otherwise, it is the same as the run_id.\"\n        ),\n        example=455644833,\n    )\n    overriding_parameters: Optional[RunParameters] = Field(\n        None, description=\"The parameters used for this run.\"\n    )\n    run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The canonical identifier of the run. This ID is unique across all runs of\"\n            \" all jobs.\"\n        ),\n        example=455644833,\n    )\n    run_name: Optional[str] = Field(\n        \"Untitled\",\n        description=(\n            \"An optional name for the run. The maximum allowed length is 4096 bytes in\"\n            \" UTF-8 encoding.\"\n        ),\n        example=\"A multitask job run\",\n    )\n    run_page_url: Optional[str] = Field(\n        None,\n        description=\"The URL to the detail page of the run.\",\n        example=\"https://my-workspace.cloud.databricks.com/#job/11223344/run/123\",\n    )\n    run_type: Optional[RunType] = None\n    schedule: Optional[CronSchedule] = Field(\n        None,\n        description=(\n            \"The cron schedule that triggered this run if it was triggered by the\"\n            \" periodic scheduler.\"\n        ),\n    )\n    setup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time it took to set up the cluster in milliseconds. For runs that run\"\n            \" on new clusters this is the cluster creation time, for runs that run on\"\n            \" existing clusters this time should be very short.\"\n        ),\n        example=0,\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run was started in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC). This may not be the time when the job task starts\"\n            \" executing, for example, if the job is scheduled to run on a new cluster,\"\n            \" this is the time the cluster creation call is issued.\"\n        ),\n        example=1625060460483,\n    )\n    state: Optional[RunState] = Field(\n        None, description=\"The result and lifecycle states of the run.\"\n    )\n    tasks: Optional[List[RunTask]] = Field(\n        None,\n        description=(\n            \"The list of tasks performed by the run. Each task has its own `run_id`\"\n            \" which you can use to call `JobsGetOutput` to retrieve the run resutls.\"\n        ),\n        example=[\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\n                    \"cluster_id\": \"0923-164208-meows279\",\n                    \"spark_context_id\": \"4348585301701786933\",\n                },\n                \"description\": \"Ingests order data\",\n                \"end_time\": 1629989930171,\n                \"execution_duration\": 0,\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"run_id\": 2112892,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/20\"\n                ),\n                \"setup_duration\": 0,\n                \"spark_jar_task\": {\"main_class_name\": \"com.databricks.OrdersIngest\"},\n                \"start_time\": 1629989929660,\n                \"state\": {\n                    \"life_cycle_state\": \"INTERNAL_ERROR\",\n                    \"result_state\": \"FAILED\",\n                    \"state_message\": (\n                        \"Library installation failed for library due to user error.\"\n                        \" Error messages:\\n'Manage' permissions are required to install\"\n                        \" libraries on a cluster\"\n                    ),\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Orders_Ingest\",\n            },\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\"cluster_id\": \"0923-164208-meows279\"},\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"end_time\": 1629989930238,\n                \"execution_duration\": 0,\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"run_id\": 2112897,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/21\"\n                ),\n                \"setup_duration\": 0,\n                \"start_time\": 0,\n                \"state\": {\n                    \"life_cycle_state\": \"SKIPPED\",\n                    \"state_message\": \"An upstream task failed.\",\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Match\",\n            },\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\n                    \"cluster_id\": \"0923-164208-meows279\",\n                    \"spark_context_id\": \"4348585301701786933\",\n                },\n                \"description\": \"Extracts session data from events\",\n                \"end_time\": 1629989930144,\n                \"execution_duration\": 0,\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"run_id\": 2112902,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/22\"\n                ),\n                \"setup_duration\": 0,\n                \"spark_jar_task\": {\"main_class_name\": \"com.databricks.Sessionize\"},\n                \"start_time\": 1629989929668,\n                \"state\": {\n                    \"life_cycle_state\": \"INTERNAL_ERROR\",\n                    \"result_state\": \"FAILED\",\n                    \"state_message\": (\n                        \"Library installation failed for library due to user error.\"\n                        \" Error messages:\\n'Manage' permissions are required to install\"\n                        \" libraries on a cluster\"\n                    ),\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Sessionize\",\n            },\n        ],\n        max_items=100,\n    )\n    trigger: Optional[TriggerType] = Field(\n        None, description=\"The type of trigger that fired this run.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunLifeCycleState","title":"<code>RunLifeCycleState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PENDING`: The run has been triggered. If there is not already an active run of the same job, the cluster and execution context are being prepared. If there is already an active run of the same job, the run immediately transitions into the `SKIPPED` state without preparing any resources.\n</code></pre> <ul> <li><code>RUNNING</code>: The task of this run is being executed.</li> <li><code>TERMINATING</code>: The task of this run has completed, and the cluster and execution context are being cleaned up.</li> <li><code>TERMINATED</code>: The task of this run has completed, and the cluster and execution context have been cleaned up. This state is terminal.</li> <li><code>SKIPPED</code>: This run was aborted because a previous run of the same job was already active. This state is terminal.</li> <li><code>INTERNAL_ERROR</code>: An exceptional state that indicates a failure in the Jobs service, such as network failure over a long period. If a run on a new cluster ends in the <code>INTERNAL_ERROR</code> state, the Jobs service terminates the cluster as soon as possible. This state is terminal.</li> <li><code>BLOCKED</code>: The run is blocked on an upstream dependency.</li> <li><code>WAITING_FOR_RETRY</code>: The run is waiting for a retry.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunLifeCycleState(str, Enum):\n    \"\"\"\n        * `PENDING`: The run has been triggered. If there is not already an active run of the same job, the cluster and execution context are being prepared. If there is already an active run of the same job, the run immediately transitions into the `SKIPPED` state without preparing any resources.\n    * `RUNNING`: The task of this run is being executed.\n    * `TERMINATING`: The task of this run has completed, and the cluster and execution context are being cleaned up.\n    * `TERMINATED`: The task of this run has completed, and the cluster and execution context have been cleaned up. This state is terminal.\n    * `SKIPPED`: This run was aborted because a previous run of the same job was already active. This state is terminal.\n    * `INTERNAL_ERROR`: An exceptional state that indicates a failure in the Jobs service, such as network failure over a long period. If a run on a new cluster ends in the `INTERNAL_ERROR` state, the Jobs service terminates the cluster as soon as possible. This state is terminal.\n    * `BLOCKED`: The run is blocked on an upstream dependency.\n    * `WAITING_FOR_RETRY`: The run is waiting for a retry.\n    \"\"\"\n\n    terminated = \"TERMINATED\"\n    pending = \"PENDING\"\n    running = \"RUNNING\"\n    terminating = \"TERMINATING\"\n    skipped = \"SKIPPED\"\n    internalerror = \"INTERNAL_ERROR\"\n    blocked = \"BLOCKED\"\n    waitingforretry = \"WAITING_FOR_RETRY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunNowInput","title":"<code>RunNowInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunNowInput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    idempotency_token: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional token to guarantee the idempotency of job run requests. If a\"\n            \" run with the provided token already exists, the request does not create a\"\n            \" new run but returns the ID of the existing run instead. If a run with the\"\n            \" provided token is deleted, an error is returned.\\n\\nIf you specify the\"\n            \" idempotency token, upon failure you can retry until the request succeeds.\"\n            \" Databricks guarantees that exactly one run is launched with that\"\n            \" idempotency token.\\n\\nThis token must have at most 64 characters.\\n\\nFor\"\n            \" more information, see [How to ensure idempotency for\"\n            \" jobs](https://kb.databricks.com/jobs/jobs-idempotency.html).\"\n        ),\n        example=\"8f018174-4792-40d5-bcbc-3e6a527352c8\",\n    )\n    job_id: Optional[int] = Field(\n        None, description=\"The ID of the job to be executed\", example=11223344\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunParameters","title":"<code>RunParameters</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunParameters(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_commands: Optional[List] = Field(\n        None,\n        description=(\n            \"An array of commands to execute for jobs with the dbt task, for example\"\n            ' `\"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]`'\n        ),\n        example=[\"dbt deps\", \"dbt seed\", \"dbt run\"],\n    )\n    jar_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with Spark JAR tasks, for example\"\n            ' `\"jar_params\": [\"john doe\", \"35\"]`. The parameters are used to invoke the'\n            \" main function of the main class specified in the Spark JAR task. If not\"\n            \" specified upon `run-now`, it defaults to an empty list. jar_params cannot\"\n            \" be specified in conjunction with notebook_params. The JSON representation\"\n            ' of this field (for example `{\"jar_params\":[\"john doe\",\"35\"]}`) cannot'\n            \" exceed 10,000 bytes.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"john\", \"doe\", \"35\"],\n    )\n    notebook_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"A map from keys to values for jobs with notebook task, for example\"\n            ' `\"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}`. The map is passed'\n            \" to the notebook and is accessible through the\"\n            \" [dbutils.widgets.get](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-widgets)\"\n            \" function.\\n\\nIf not specified upon `run-now`, the triggered run uses the\"\n            \" job\u2019s base parameters.\\n\\nnotebook_params cannot be specified in\"\n            \" conjunction with jar_params.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\\n\\nThe JSON\"\n            \" representation of this field (for example\"\n            ' `{\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}`) cannot exceed'\n            \" 10,000 bytes.\"\n        ),\n        example={\"age\": \"35\", \"name\": \"john doe\"},\n    )\n    pipeline_params: Optional[PipelineParams] = None\n    python_named_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"A map from keys to values for jobs with Python wheel task, for example\"\n            ' `\"python_named_params\": {\"name\": \"task\", \"data\":'\n            ' \"dbfs:/path/to/data.json\"}`.'\n        ),\n        example={\"data\": \"dbfs:/path/to/data.json\", \"name\": \"task\"},\n    )\n    python_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with Python tasks, for example\"\n            ' `\"python_params\": [\"john doe\", \"35\"]`. The parameters are passed to'\n            \" Python file as command-line parameters. If specified upon `run-now`, it\"\n            \" would overwrite the parameters specified in job setting. The JSON\"\n            ' representation of this field (for example `{\"python_params\":[\"john'\n            ' doe\",\"35\"]}`) cannot exceed 10,000 bytes.\\n\\nUse [Task parameter'\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job\"\n            \" runs.\\n\\nImportant\\n\\nThese parameters accept only Latin characters\"\n            \" (ASCII character set). Using non-ASCII characters returns an error.\"\n            \" Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis,\"\n            \" and emojis.\"\n        ),\n        example=[\"john doe\", \"35\"],\n    )\n    spark_submit_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with spark submit task, for example\"\n            ' `\"spark_submit_params\": [\"--class\",'\n            ' \"org.apache.spark.examples.SparkPi\"]`. The parameters are passed to'\n            \" spark-submit script as command-line parameters. If specified upon\"\n            \" `run-now`, it would overwrite the parameters specified in job setting.\"\n            \" The JSON representation of this field (for example\"\n            ' `{\"python_params\":[\"john doe\",\"35\"]}`) cannot exceed 10,000 bytes.\\n\\nUse'\n            \" [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job\"\n            \" runs.\\n\\nImportant\\n\\nThese parameters accept only Latin characters\"\n            \" (ASCII character set). Using non-ASCII characters returns an error.\"\n            \" Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis,\"\n            \" and emojis.\"\n        ),\n        example=[\"--class\", \"org.apache.spark.examples.SparkPi\"],\n    )\n    sql_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            'A map from keys to values for SQL tasks, for example `\"sql_params\":'\n            ' {\"name\": \"john doe\", \"age\": \"35\"}`. The SQL alert task does not support'\n            \" custom parameters.\"\n        ),\n        example={\"age\": \"35\", \"name\": \"john doe\"},\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunResultState","title":"<code>RunResultState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `SUCCESS`: The task completed successfully.\n</code></pre> <ul> <li><code>FAILED</code>: The task completed with an error.</li> <li><code>TIMEDOUT</code>: The run was stopped after reaching the timeout.</li> <li><code>CANCELED</code>: The run was canceled at user request.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunResultState(str, Enum):\n    \"\"\"\n        * `SUCCESS`: The task completed successfully.\n    * `FAILED`: The task completed with an error.\n    * `TIMEDOUT`: The run was stopped after reaching the timeout.\n    * `CANCELED`: The run was canceled at user request.\n    \"\"\"\n\n    success = \"SUCCESS\"\n    failed = \"FAILED\"\n    timedout = \"TIMEDOUT\"\n    canceled = \"CANCELED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunState","title":"<code>RunState</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>The result and lifecycle state of the run.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunState(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    The result and lifecycle state of the run.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    life_cycle_state: Optional[RunLifeCycleState] = Field(\n        None,\n        description=(\n            \"A description of a run\u2019s current location in the run lifecycle. This field\"\n            \" is always available in the response.\"\n        ),\n    )\n    result_state: Optional[RunResultState] = None\n    state_message: Optional[str] = Field(\n        None,\n        description=(\n            \"A descriptive message for the current state. This field is unstructured,\"\n            \" and its exact format is subject to change.\"\n        ),\n        example=\"\",\n    )\n    user_cancelled_or_timedout: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether a run was canceled manually by a user or by the scheduler because\"\n            \" the run timed out.\"\n        ),\n        example=False,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunSubmitSettings","title":"<code>RunSubmitSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunSubmitSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    idempotency_token: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional token that can be used to guarantee the idempotency of job run\"\n            \" requests. If a run with the provided token already exists, the request\"\n            \" does not create a new run but returns the ID of the existing run instead.\"\n            \" If a run with the provided token is deleted, an error is returned.\\n\\nIf\"\n            \" you specify the idempotency token, upon failure you can retry until the\"\n            \" request succeeds. Databricks guarantees that exactly one run is launched\"\n            \" with that idempotency token.\\n\\nThis token must have at most 64\"\n            \" characters.\\n\\nFor more information, see [How to ensure idempotency for\"\n            \" jobs](https://kb.databricks.com/jobs/jobs-idempotency.html).\"\n        ),\n        example=\"8f018174-4792-40d5-bcbc-3e6a527352c8\",\n    )\n    run_name: Optional[str] = Field(\n        None,\n        description=\"An optional name for the run. The default value is `Untitled`.\",\n        example=\"A multitask job run\",\n    )\n    tasks: Optional[List[RunSubmitTaskSettings]] = Field(\n        None,\n        example=[\n            {\n                \"depends_on\": [],\n                \"description\": \"Extracts session data from events\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.Sessionize\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                },\n                \"task_key\": \"Sessionize\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [],\n                \"description\": \"Ingests order data\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.OrdersIngest\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                },\n                \"task_key\": \"Orders_Ingest\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"base_parameters\": {\"age\": \"35\", \"name\": \"John Doe\"},\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"task_key\": \"Match\",\n                \"timeout_seconds\": 86400,\n            },\n        ],\n        max_items=100,\n    )\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job. The default behavior\"\n            \" is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when runs of this job\"\n            \" begin or complete. The default behavior is to not send any system\"\n            \" notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunSubmitTaskSettings","title":"<code>RunSubmitTaskSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunSubmitTaskSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this task. When running tasks on an existing cluster, you may\"\n            \" need to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the task. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this task must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this task must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this task must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this task must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this task must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    task_key: TaskKey\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job task. The default\"\n            \" behavior is to have no timeout.\"\n        ),\n        example=86400,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunTask","title":"<code>RunTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attempt_number: Optional[int] = Field(\n        None,\n        description=(\n            \"The sequence number of this run attempt for a triggered job run. The\"\n            \" initial attempt of a run has an attempt_number of 0\\\\. If the initial run\"\n            \" attempt fails, and the job has a retry policy (`max_retries` \\\\&gt; 0),\"\n            \" subsequent runs are created with an `original_attempt_run_id` of the\"\n            \" original attempt\u2019s ID and an incrementing `attempt_number`. Runs are\"\n            \" retried only until they succeed, and the maximum `attempt_number` is the\"\n            \" same as the `max_retries` value for the job.\"\n        ),\n        example=0,\n    )\n    cleanup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to terminate the cluster and clean up any\"\n            \" associated artifacts. The total duration of the run is the sum of the\"\n            \" setup_duration, the execution_duration, and the cleanup_duration.\"\n        ),\n        example=0,\n    )\n    cluster_instance: Optional[ClusterInstance] = Field(\n        None,\n        description=(\n            \"The cluster used for this run. If the run is specified to use a new\"\n            \" cluster, this field is set once the Jobs service has requested a cluster\"\n            \" for the run.\"\n        ),\n    )\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    description: Optional[TaskDescription] = None\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run ended in epoch milliseconds (milliseconds since\"\n            \" 1/1/1970 UTC). This field is set to 0 if the job is still running.\"\n        ),\n        example=1625060863413,\n    )\n    execution_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to execute the commands in the JAR or\"\n            \" notebook until they completed, failed, timed out, were cancelled, or\"\n            \" encountered an unexpected error.\"\n        ),\n        example=0,\n    )\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this job. When running jobs on an existing cluster, you may need\"\n            \" to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the job. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this job must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this job must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    run_id: Optional[int] = Field(\n        None, description=\"The ID of the task run.\", example=99887766\n    )\n    setup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time it took to set up the cluster in milliseconds. For runs that run\"\n            \" on new clusters this is the cluster creation time, for runs that run on\"\n            \" existing clusters this time should be very short.\"\n        ),\n        example=0,\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this job must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this job must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this job must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run was started in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC). This may not be the time when the job task starts\"\n            \" executing, for example, if the job is scheduled to run on a new cluster,\"\n            \" this is the time the cluster creation call is issued.\"\n        ),\n        example=1625060460483,\n    )\n    state: Optional[RunState] = Field(\n        None, description=\"The result and lifecycle states of the run.\"\n    )\n    task_key: Optional[TaskKey] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunType","title":"<code>RunType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>The type of the run.\n</code></pre> <ul> <li><code>JOB_RUN</code> - Normal job run. A run created with Run now.</li> <li><code>WORKFLOW_RUN</code> - Workflow run. A run created with dbutils.notebook.run.</li> <li><code>SUBMIT_RUN</code> - Submit run. A run created with Run Submit.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunType(str, Enum):\n    \"\"\"\n        The type of the run.\n    * `JOB_RUN` \\- Normal job run. A run created with [Run now](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunNow).\n    * `WORKFLOW_RUN` \\- Workflow run. A run created with [dbutils.notebook.run](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-workflow).\n    * `SUBMIT_RUN` \\- Submit run. A run created with [Run Submit](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunsSubmit).\n    \"\"\"\n\n    jobrun = \"JOB_RUN\"\n    workflowrun = \"WORKFLOW_RUN\"\n    submitrun = \"SUBMIT_RUN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.S3StorageInfo","title":"<code>S3StorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class S3StorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    canned_acl: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) Set canned access control list. For example:\"\n            \" `bucket-owner-full-control`. If canned_acl is set, the cluster instance\"\n            \" profile must have `s3:PutObjectAcl` permission on the destination bucket\"\n            \" and prefix. The full list of possible canned ACLs can be found at\"\n            \" &lt;https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl&gt;.\"\n            \" By default only the object owner gets full control. If you are using\"\n            \" cross account role for writing data, you may want to set\"\n            \" `bucket-owner-full-control` to make bucket owner able to read the logs.\"\n        ),\n    )\n    destination: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 destination. For example: `s3://my-bucket/some-prefix` You must\"\n            \" configure the cluster with an instance profile and the instance profile\"\n            \" must have write access to the destination. You _cannot_ use AWS keys.\"\n        ),\n    )\n    enable_encryption: Optional[bool] = Field(\n        None, description=\"(Optional)Enable server side encryption, `false` by default.\"\n    )\n    encryption_type: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) The encryption type, it could be `sse-s3` or `sse-kms`. It is\"\n            \" used only when encryption is enabled and the default type is `sse-s3`.\"\n        ),\n    )\n    endpoint: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 endpoint. For example: `https://s3-us-west-2.amazonaws.com`. Either\"\n            \" region or endpoint must be set. If both are set, endpoint is used.\"\n        ),\n    )\n    kms_key: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) KMS key used if encryption is enabled and encryption type is\"\n            \" set to `sse-kms`.\"\n        ),\n    )\n    region: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 region. For example: `us-west-2`. Either region or endpoint must be\"\n            \" set. If both are set, endpoint is used.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ServicePrincipalName","title":"<code>ServicePrincipalName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ServicePrincipalName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=\"Name of an Azure service principal.\",\n        example=\"9f0621ee-b52b-11ea-b3de-0242ac130004\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkConfPair","title":"<code>SparkConfPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An arbitrary object where the object key is a configuration property name and the value is a configuration property value.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkConfPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An arbitrary object where the object key is a configuration property name and the value is a configuration property value.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkEnvPair","title":"<code>SparkEnvPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An arbitrary object where the object key is an environment variable name and the value is an environment variable value.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkEnvPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An arbitrary object where the object key is an environment variable name and the value is an environment variable value.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkJarTask","title":"<code>SparkJarTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkJarTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    jar_uri: Optional[str] = Field(\n        None,\n        deprecated=True,\n        description=(\n            \"Deprecated since 04/2016\\\\. Provide a `jar` through the `libraries` field\"\n            \" instead. For an example, see\"\n            \" [Create](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsCreate).\"\n        ),\n    )\n    main_class_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The full name of the class containing the main method to be executed. This\"\n            \" class must be contained in a JAR provided as a library.\\n\\nThe code must\"\n            \" use `SparkContext.getOrCreate` to obtain a Spark context; otherwise, runs\"\n            \" of the job fail.\"\n        ),\n        example=\"com.databricks.ComputeModels\",\n    )\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Parameters passed to the main method.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"--data\", \"dbfs:/path/to/data.json\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkNode","title":"<code>SparkNode</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkNode(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    host_private_ip: Optional[str] = Field(\n        None, description=\"The private IP address of the host instance.\"\n    )\n    instance_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Globally unique identifier for the host instance from the cloud provider.\"\n        ),\n    )\n    node_aws_attributes: Optional[SparkNodeAwsAttributes] = Field(\n        None, description=\"Attributes specific to AWS for a Spark node.\"\n    )\n    node_id: Optional[str] = Field(\n        None, description=\"Globally unique identifier for this node.\"\n    )\n    private_ip: Optional[str] = Field(\n        None,\n        description=(\n            \"Private IP address (typically a 10.x.x.x address) of the Spark node. This\"\n            \" is different from the private IP address of the host instance.\"\n        ),\n    )\n    public_dns: Optional[str] = Field(\n        None,\n        description=(\n            \"Public DNS address of this node. This address can be used to access the\"\n            \" Spark JDBC server on the driver node. To communicate with the JDBC\"\n            \" server, traffic must be manually authorized by adding security group\"\n            \" rules to the \u201cworker-unmanaged\u201d security group via the AWS console.\"\n        ),\n    )\n    start_timestamp: Optional[int] = Field(\n        None,\n        description=\"The timestamp (in millisecond) when the Spark node is launched.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkNodeAwsAttributes","title":"<code>SparkNodeAwsAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkNodeAwsAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    is_spot: Optional[bool] = Field(\n        None, description=\"Whether this node is on an Amazon spot instance.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkPythonTask","title":"<code>SparkPythonTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkPythonTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command line parameters passed to the Python file.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"--data\", \"dbfs:/path/to/data.json\"],\n    )\n    python_file: str = Field(\n        ...,\n        description=(\n            \"The Python file to be executed. Cloud file URIs (such as dbfs:/, s3:/,\"\n            \" adls:/, gcs:/) and workspace paths are supported. For python files stored\"\n            \" in the Databricks workspace, the path must be absolute and begin with\"\n            \" `/Repos`. This field is required.\"\n        ),\n        example=\"dbfs:/path/to/file.py\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkSubmitTask","title":"<code>SparkSubmitTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkSubmitTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to spark submit.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\n            \"--class\",\n            \"org.apache.spark.examples.SparkPi\",\n            \"dbfs:/path/to/examples.jar\",\n            \"10\",\n        ],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkVersion","title":"<code>SparkVersion</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkVersion(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    key: Optional[str] = Field(\n        None,\n        description=(\n            \"[Databricks Runtime\"\n            \" version](https://docs.databricks.com/dev-tools/api/latest/index.html#programmatic-version)\"\n            \" key, for example `7.3.x-scala2.12`. The value that must be provided as\"\n            \" the `spark_version` when creating a new cluster. The exact runtime\"\n            \" version may change over time for a \u201cwildcard\u201d version (that is,\"\n            \" `7.3.x-scala2.12` is a \u201cwildcard\u201d version) with minor bug fixes.\"\n        ),\n    )\n    name: Optional[str] = Field(\n        None,\n        description=(\n            \"A descriptive name for the runtime version, for example \u201cDatabricks\"\n            \" Runtime 7.3 LTS\u201d.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlAlertOutput","title":"<code>SqlAlertOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlAlertOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    query_text: Optional[str] = Field(\n        None,\n        description=(\n            \"The text of the SQL query. Can Run permission of the SQL query associated\"\n            \" with the SQL alert is required to view this field.\"\n        ),\n    )\n    sql_statements: Optional[SqlStatementOutput] = Field(\n        None, description=\"Information about SQL statements executed in the run.\"\n    )\n    warehouse_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL warehouse.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlDashboardOutput","title":"<code>SqlDashboardOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlDashboardOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    widgets: Optional[SqlDashboardWidgetOutput] = Field(\n        None,\n        description=(\n            \"Widgets executed in the run. Only SQL query based widgets are listed.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlDashboardWidgetOutput","title":"<code>SqlDashboardWidgetOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlDashboardWidgetOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when execution of the SQL widget ends.\"\n        ),\n    )\n    error: Optional[SqlOutputError] = Field(\n        None, description=\"The information about the error when execution fails.\"\n    )\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when execution of the SQL widget starts.\"\n        ),\n    )\n    status: Optional[\n        Literal[\"PENDING\", \"RUNNING\", \"SUCCESS\", \"FAILED\", \"CANCELLED\"]\n    ] = Field(None, description=\"The execution status of the SQL widget.\")\n    widget_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL widget.\"\n    )\n    widget_title: Optional[str] = Field(\n        None, description=\"The title of the SQL widget.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlOutput","title":"<code>SqlOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert_output: Optional[SqlAlertOutput] = Field(\n        None, description=\"The output of a SQL alert task, if available.\"\n    )\n    dashboard_output: Optional[SqlDashboardOutput] = Field(\n        None, description=\"The output of a SQL dashboard task, if available.\"\n    )\n    query_output: Optional[SqlQueryOutput] = Field(\n        None, description=\"The output of a SQL query task, if available.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlOutputError","title":"<code>SqlOutputError</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlOutputError(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    message: Optional[str] = Field(\n        None, description=\"The error message when execution fails.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlQueryOutput","title":"<code>SqlQueryOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlQueryOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    query_text: Optional[str] = Field(\n        None,\n        description=(\n            \"The text of the SQL query. Can Run permission of the SQL query is required\"\n            \" to view this field.\"\n        ),\n    )\n    sql_statements: Optional[SqlStatementOutput] = Field(\n        None, description=\"Information about SQL statements executed in the run.\"\n    )\n    warehouse_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL warehouse.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlStatementOutput","title":"<code>SqlStatementOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlStatementOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    lookup_key: Optional[str] = Field(\n        None, description=\"A key that can be used to look up query details.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTask","title":"<code>SqlTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert: Optional[SqlTaskAlert] = Field(\n        None, description=\"If alert, indicates that this job must refresh a SQL alert.\"\n    )\n    dashboard: Optional[SqlTaskDashboard] = Field(\n        None,\n        description=(\n            \"If dashboard, indicates that this job must refresh a SQL dashboard.\"\n        ),\n    )\n    parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Parameters to be used for each run of this job. The SQL alert task does\"\n            \" not support custom parameters.\"\n        ),\n        example={\"age\": 35, \"name\": \"John Doe\"},\n    )\n    query: Optional[SqlTaskQuery] = Field(\n        None, description=\"If query, indicates that this job must execute a SQL query.\"\n    )\n    warehouse_id: str = Field(\n        ...,\n        description=(\n            \"The canonical identifier of the SQL warehouse. Only serverless and pro SQL\"\n            \" warehouses are supported.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskAlert","title":"<code>SqlTaskAlert</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskAlert(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert_id: str = Field(..., description=\"The canonical identifier of the SQL alert.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskDashboard","title":"<code>SqlTaskDashboard</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskDashboard(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dashboard_id: str = Field(\n        ..., description=\"The canonical identifier of the SQL dashboard.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskQuery","title":"<code>SqlTaskQuery</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskQuery(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    query_id: str = Field(..., description=\"The canonical identifier of the SQL query.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDependencies","title":"<code>TaskDependencies</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <pre><code>An optional array of objects specifying the dependency graph of the task. All tasks specified in this field must complete successfully before executing this task.\n</code></pre> <p>The key is <code>task_key</code>, and the value is the name assigned to the dependent task. This field is required when a job consists of more than one task.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDependencies(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n        An optional array of objects specifying the dependency graph of the task. All tasks specified in this field must complete successfully before executing this task.\n    The key is `task_key`, and the value is the name assigned to the dependent task.\n    This field is required when a job consists of more than one task.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: List[TaskDependency] = Field(\n        ...,\n        description=(\n            \"An optional array of objects specifying the dependency graph of the task.\"\n            \" All tasks specified in this field must complete successfully before\"\n            \" executing this task.\\nThe key is `task_key`, and the value is the name\"\n            \" assigned to the dependent task.\\nThis field is required when a job\"\n            \" consists of more than one task.\"\n        ),\n        example=[{\"task_key\": \"Previous_Task_Key\"}, {\"task_key\": \"Other_Task_Key\"}],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDependency","title":"<code>TaskDependency</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDependency(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    task_key: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDescription","title":"<code>TaskDescription</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDescription(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"An optional description for this task.\\nThe maximum length is 4096 bytes.\"\n        ),\n        example=\"This is the description for this task.\",\n        max_length=4096,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskKey","title":"<code>TaskKey</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskKey(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"A unique name for the task. This field is used to refer to this task from\"\n            \" other tasks.\\nThis field is required and must be unique within its parent\"\n            \" job.\\nOn Update or Reset, this field is used to reference the tasks to be\"\n            \" updated or reset.\\nThe maximum length is 100 characters.\"\n        ),\n        example=\"Task_Key\",\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationCode","title":"<code>TerminationCode</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* USER_REQUEST: A user terminated the cluster directly. Parameters should include a `username` field that indicates the specific user who terminated the cluster.\n</code></pre> <ul> <li>JOB_FINISHED: The cluster was launched by a job, and terminated when the job completed.</li> <li>INACTIVITY: The cluster was terminated since it was idle.</li> <li>CLOUD_PROVIDER_SHUTDOWN: The instance that hosted the Spark driver was terminated by the cloud provider. In AWS, for example, AWS may retire instances and directly shut them down. Parameters should include an <code>aws_instance_state_reason</code> field indicating the AWS-provided reason why the instance was terminated.</li> <li>COMMUNICATION_LOST: Databricks lost connection to services on the driver instance. For example, this can happen when problems arise in cloud networking infrastructure, or when the instance itself becomes unhealthy.</li> <li>CLOUD_PROVIDER_LAUNCH_FAILURE: Databricks experienced a cloud provider failure when requesting instances to launch clusters. For example, AWS limits the number of running instances and EBS volumes. If you ask Databricks to launch a cluster that requires instances or EBS volumes that exceed your AWS limit, the cluster fails with this status code. Parameters should include one of <code>aws_api_error_code</code>, <code>aws_instance_state_reason</code>, or <code>aws_spot_request_status</code> to indicate the AWS-provided reason why Databricks could not request the required instances for the cluster.</li> <li>SPARK_STARTUP_FAILURE: The cluster failed to initialize. Possible reasons may include failure to create the environment for Spark or issues launching the Spark master and worker processes.</li> <li>INVALID_ARGUMENT: Cannot launch the cluster because the user specified an invalid argument. For example, the user might specify an invalid runtime version for the cluster.</li> <li>UNEXPECTED_LAUNCH_FAILURE: While launching this cluster, Databricks failed to complete critical setup steps, terminating the cluster.</li> <li>INTERNAL_ERROR: Databricks encountered an unexpected error that forced the running cluster to be terminated. Contact Databricks support for additional details.</li> <li>SPARK_ERROR: The Spark driver failed to start. Possible reasons may include incompatible libraries and initialization scripts that corrupted the Spark container.</li> <li>METASTORE_COMPONENT_UNHEALTHY: The cluster failed to start because the external metastore could not be reached. Refer to Troubleshooting.</li> <li>DBFS_COMPONENT_UNHEALTHY: The cluster failed to start because Databricks File System (DBFS) could not be reached.</li> <li>DRIVER_UNREACHABLE: Databricks was not able to access the Spark driver, because it was not reachable.</li> <li>DRIVER_UNRESPONSIVE: Databricks was not able to access the Spark driver, because it was unresponsive.</li> <li>INSTANCE_UNREACHABLE: Databricks was not able to access instances in order to start the cluster. This can be a transient networking issue. If the problem persists, this usually indicates a networking environment misconfiguration.</li> <li>CONTAINER_LAUNCH_FAILURE: Databricks was unable to launch containers on worker nodes for the cluster. Have your admin check your network configuration.</li> <li>INSTANCE_POOL_CLUSTER_FAILURE: Pool backed cluster specific failure. Refer to Pools for details.</li> <li>REQUEST_REJECTED: Databricks cannot handle the request at this moment. Try again later and contact Databricks if the problem persists.</li> <li>INIT_SCRIPT_FAILURE: Databricks cannot load and run a cluster-scoped init script on one of the cluster\u2019s nodes, or the init script terminates with a non-zero exit code. Refer to Init script logs.</li> <li>TRIAL_EXPIRED: The Databricks trial subscription expired.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationCode(str, Enum):\n    \"\"\"\n        * USER_REQUEST: A user terminated the cluster directly. Parameters should include a `username` field that indicates the specific user who terminated the cluster.\n    * JOB_FINISHED: The cluster was launched by a job, and terminated when the job completed.\n    * INACTIVITY: The cluster was terminated since it was idle.\n    * CLOUD_PROVIDER_SHUTDOWN: The instance that hosted the Spark driver was terminated by the cloud provider. In AWS, for example, AWS may retire instances and directly shut them down. Parameters should include an `aws_instance_state_reason` field indicating the AWS-provided reason why the instance was terminated.\n    * COMMUNICATION_LOST: Databricks lost connection to services on the driver instance. For example, this can happen when problems arise in cloud networking infrastructure, or when the instance itself becomes unhealthy.\n    * CLOUD_PROVIDER_LAUNCH_FAILURE: Databricks experienced a cloud provider failure when requesting instances to launch clusters. For example, AWS limits the number of running instances and EBS volumes. If you ask Databricks to launch a cluster that requires instances or EBS volumes that exceed your AWS limit, the cluster fails with this status code. Parameters should include one of `aws_api_error_code`, `aws_instance_state_reason`, or `aws_spot_request_status` to indicate the AWS-provided reason why Databricks could not request the required instances for the cluster.\n    * SPARK_STARTUP_FAILURE: The cluster failed to initialize. Possible reasons may include failure to create the environment for Spark or issues launching the Spark master and worker processes.\n    * INVALID_ARGUMENT: Cannot launch the cluster because the user specified an invalid argument. For example, the user might specify an invalid runtime version for the cluster.\n    * UNEXPECTED_LAUNCH_FAILURE: While launching this cluster, Databricks failed to complete critical setup steps, terminating the cluster.\n    * INTERNAL_ERROR: Databricks encountered an unexpected error that forced the running cluster to be terminated. Contact Databricks support for additional details.\n    * SPARK_ERROR: The Spark driver failed to start. Possible reasons may include incompatible libraries and initialization scripts that corrupted the Spark container.\n    * METASTORE_COMPONENT_UNHEALTHY: The cluster failed to start because the external metastore could not be reached. Refer to [Troubleshooting](https://docs.databricks.com/data/metastores/external-hive-metastore.html#troubleshooting).\n    * DBFS_COMPONENT_UNHEALTHY: The cluster failed to start because Databricks File System (DBFS) could not be reached.\n    * DRIVER_UNREACHABLE: Databricks was not able to access the Spark driver, because it was not reachable.\n    * DRIVER_UNRESPONSIVE: Databricks was not able to access the Spark driver, because it was unresponsive.\n    * INSTANCE_UNREACHABLE: Databricks was not able to access instances in order to start the cluster. This can be a transient networking issue. If the problem persists, this usually indicates a networking environment misconfiguration.\n    * CONTAINER_LAUNCH_FAILURE: Databricks was unable to launch containers on worker nodes for the cluster. Have your admin check your network configuration.\n    * INSTANCE_POOL_CLUSTER_FAILURE: Pool backed cluster specific failure. Refer to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html) for details.\n    * REQUEST_REJECTED: Databricks cannot handle the request at this moment. Try again later and contact Databricks if the problem persists.\n    * INIT_SCRIPT_FAILURE: Databricks cannot load and run a cluster-scoped init script on one of the cluster\u2019s nodes, or the init script terminates with a non-zero exit code. Refer to [Init script logs](https://docs.databricks.com/clusters/init-scripts.html#init-script-log).\n    * TRIAL_EXPIRED: The Databricks trial subscription expired.\n    \"\"\"\n\n    userrequest = \"USER_REQUEST\"\n    jobfinished = \"JOB_FINISHED\"\n    inactivity = \"INACTIVITY\"\n    cloudprovidershutdown = \"CLOUD_PROVIDER_SHUTDOWN\"\n    communicationlost = \"COMMUNICATION_LOST\"\n    cloudproviderlaunchfailure = \"CLOUD_PROVIDER_LAUNCH_FAILURE\"\n    sparkstartupfailure = \"SPARK_STARTUP_FAILURE\"\n    invalidargument = \"INVALID_ARGUMENT\"\n    unexpectedlaunchfailure = \"UNEXPECTED_LAUNCH_FAILURE\"\n    internalerror = \"INTERNAL_ERROR\"\n    sparkerror = \"SPARK_ERROR\"\n    metastorecomponentunhealthy = \"METASTORE_COMPONENT_UNHEALTHY\"\n    dbfscomponentunhealthy = \"DBFS_COMPONENT_UNHEALTHY\"\n    driverunreachable = \"DRIVER_UNREACHABLE\"\n    driverunresponsive = \"DRIVER_UNRESPONSIVE\"\n    instanceunreachable = \"INSTANCE_UNREACHABLE\"\n    containerlaunchfailure = \"CONTAINER_LAUNCH_FAILURE\"\n    instancepoolclusterfailure = \"INSTANCE_POOL_CLUSTER_FAILURE\"\n    requestrejected = \"REQUEST_REJECTED\"\n    initscriptfailure = \"INIT_SCRIPT_FAILURE\"\n    trialexpired = \"TRIAL_EXPIRED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationParameter","title":"<code>TerminationParameter</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationParameter(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    aws_api_error_code: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided error code describing why cluster nodes could not be\"\n            \" provisioned. For example, `InstanceLimitExceeded` indicates that the\"\n            \" limit of EC2 instances for a specific instance type has been exceeded.\"\n            \" For reference, see:\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-api-troubleshooting.html&gt;.\"\n        ),\n    )\n    aws_error_message: Optional[str] = Field(\n        None,\n        description=(\n            \"Human-readable context of various failures from AWS. This field is\"\n            \" unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    aws_impaired_status_details: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided status check which failed and induced a node loss. This\"\n            \" status may correspond to a failed instance or system check. For\"\n            \" reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html&gt;.\"\n        ),\n    )\n    aws_instance_state_reason: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided state reason describing why the driver node was\"\n            \" terminated. For example, `Client.VolumeLimitExceeded` indicates that the\"\n            \" limit of EBS volumes or total EBS volume storage has been exceeded. For\"\n            \" reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StateReason.html&gt;.\"\n        ),\n    )\n    aws_instance_status_event: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided scheduled event (for example reboot) which induced a node\"\n            \" loss. For reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-instances-status-check_sched.html&gt;.\"\n        ),\n    )\n    aws_spot_request_fault_code: Optional[str] = Field(\n        None,\n        description=(\n            \"Provides additional details when a spot request fails. For example\"\n            \" `InsufficientFreeAddressesInSubnet` indicates the subnet does not have\"\n            \" free IP addresses to accommodate the new instance. For reference, see\"\n            \" &lt;https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-spot-instance-requests.html&gt;.\"\n        ),\n    )\n    aws_spot_request_status: Optional[str] = Field(\n        None,\n        description=(\n            \"Describes why a spot request could not be fulfilled. For example,\"\n            \" `price-too-low` indicates that the max price was lower than the current\"\n            \" spot price. For reference, see:\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-bid-status.html#spot-instance-bid-status-understand&gt;.\"\n        ),\n    )\n    databricks_error_message: Optional[str] = Field(\n        None,\n        description=(\n            \"Additional context that may explain the reason for cluster termination.\"\n            \" This field is unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    inactivity_duration_min: Optional[str] = Field(\n        None,\n        description=(\n            \"An idle cluster was shut down after being inactive for this duration.\"\n        ),\n    )\n    instance_id: Optional[str] = Field(\n        None, description=\"The ID of the instance that was hosting the Spark driver.\"\n    )\n    instance_pool_error_code: Optional[str] = Field(\n        None,\n        description=(\n            \"The [error\"\n            \" code](https://docs.databricks.com/dev-tools/api/latest/clusters.html#clusterterminationreasonpoolclusterterminationcode)\"\n            \" for cluster failures specific to a pool.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None, description=\"The ID of the instance pool the cluster is using.\"\n    )\n    username: Optional[str] = Field(\n        None, description=\"The username of the user who terminated the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationReason","title":"<code>TerminationReason</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationReason(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    code: Optional[TerminationCode] = Field(\n        None, description=\"Status code indicating why a cluster was terminated.\"\n    )\n    parameters: Optional[ParameterPair] = Field(\n        None,\n        description=(\n            \"Object containing a set of parameters that provide information about why a\"\n            \" cluster was terminated.\"\n        ),\n    )\n    type: Optional[TerminationType] = Field(\n        None, description=\"Reason indicating why a cluster was terminated.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationType","title":"<code>TerminationType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* SUCCESS: Termination succeeded.\n</code></pre> <ul> <li>CLIENT_ERROR: Non-retriable. Client must fix parameters before reattempting the cluster creation.</li> <li>SERVICE_FAULT: Databricks service issue. Client can retry.</li> <li>CLOUD_FAILURECloud provider infrastructure issue. Client can retry after the underlying issue is resolved.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationType(str, Enum):\n    \"\"\"\n        * SUCCESS: Termination succeeded.\n    * CLIENT_ERROR: Non-retriable. Client must fix parameters before reattempting the cluster creation.\n    * SERVICE_FAULT: Databricks service issue. Client can retry.\n    * CLOUD_FAILURECloud provider infrastructure issue. Client can retry after the underlying issue is resolved.\n\n    \"\"\"\n\n    success = \"SUCCESS\"\n    clienterror = \"CLIENT_ERROR\"\n    servicefault = \"SERVICE_FAULT\"\n    cloudfailure = \"CLOUD_FAILURE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TriggerType","title":"<code>TriggerType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler.\n</code></pre> <ul> <li><code>ONE_TIME</code>: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API.</li> <li><code>RETRY</code>: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TriggerType(str, Enum):\n    \"\"\"\n        * `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler.\n    * `ONE_TIME`: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API.\n    * `RETRY`: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures.\n    \"\"\"\n\n    periodic = \"PERIODIC\"\n    onetime = \"ONE_TIME\"\n    retry = \"RETRY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.UserName","title":"<code>UserName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class UserName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ..., description=\"Email address for the user.\", example=\"jsmith@example.com\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewItem","title":"<code>ViewItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    content: Optional[str] = Field(None, description=\"Content of the view.\")\n    name: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the view item. In the case of code view, it would be the\"\n            \" notebook\u2019s name. In the case of dashboard view, it would be the\"\n            \" dashboard\u2019s name.\"\n        ),\n    )\n    type: Optional[ViewType] = Field(None, description=\"Type of the view item.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewType","title":"<code>ViewType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `NOTEBOOK`: Notebook view item.\n</code></pre> <ul> <li><code>DASHBOARD</code>: Dashboard view item.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewType(str, Enum):\n    \"\"\"\n        * `NOTEBOOK`: Notebook view item.\n    * `DASHBOARD`: Dashboard view item.\n    \"\"\"\n\n    notebook = \"NOTEBOOK\"\n    dashboard = \"DASHBOARD\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewsToExport","title":"<code>ViewsToExport</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `CODE`: Code view of the notebook.\n</code></pre> <ul> <li><code>DASHBOARDS</code>: All dashboard views of the notebook.</li> <li><code>ALL</code>: All views of the notebook.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewsToExport(str, Enum):\n    \"\"\"\n        * `CODE`: Code view of the notebook.\n    * `DASHBOARDS`: All dashboard views of the notebook.\n    * `ALL`: All views of the notebook.\n    \"\"\"\n\n    code = \"CODE\"\n    dashboards = \"DASHBOARDS\"\n    all = \"ALL\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.WebhookNotifications","title":"<code>WebhookNotifications</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class WebhookNotifications(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    on_failure: Optional[List[OnFailureItem]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run fails. A maximum\"\n            \" of 3 destinations can be specified for the `on_failure` property.\"\n        ),\n        example=[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}],\n    )\n    on_start: Optional[List[OnStartItem]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run starts. A\"\n            \" maximum of 3 destinations can be specified for the `on_start` property.\"\n        ),\n        example=[\n            {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n            {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n        ],\n    )\n    on_success: Optional[List[OnSucces]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run completes\"\n            \" successfully. A maximum of 3 destinations can be specified for the\"\n            \" `on_success` property.\"\n        ),\n        example=[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}],\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/","title":"prefect-dbt","text":"<p>With prefect-dbt you can trigger and observe dbt Cloud jobs, execute dbt Core CLI commands, and incorporate other tools, such as Snowflake, into your dbt runs. Prefect provides a global view of the state of your workflows and allows you to take action based on state changes.</p>"},{"location":"integrations/prefect-dbt/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-dbt/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A dbt Cloud account if using dbt Cloud.</li> </ul>"},{"location":"integrations/prefect-dbt/#install-prefect-dbt","title":"Install prefect-dbt","text":"<p>Install <code>prefect-dbt</code>:</p> <pre><code>pip install -U prefect-dbt\n</code></pre> <p>If necessary, see additional installation options for dbt Core with BigQuery, Snowflake, and Postgres.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-dbt[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#register-newly-installed-blocks-types","title":"Register newly installed blocks types","text":"<p>Register the block types in the prefect-dbt module to make them available for use.</p> <pre><code>prefect block register -m prefect_dbt\n</code></pre> <p>Explore the examples below to use Prefect with dbt.</p>"},{"location":"integrations/prefect-dbt/#integrate-dbt-cloud-jobs-with-prefect-flows","title":"Integrate dbt Cloud jobs with Prefect flows","text":"<p>If you have an existing dbt Cloud job, use the pre-built flow <code>run_dbt_cloud_job</code> to trigger a job run and wait until the job run is finished.</p> <p>If some nodes fail, <code>run_dbt_cloud_job</code> efficiently retries the unsuccessful nodes.</p> <p>Prior to running this flow, save your dbt Cloud credentials to a DbtCloudCredentials block:</p> <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudJob\nfrom prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n@flow\ndef run_dbt_job_flow():\n    result = run_dbt_cloud_job(\n        dbt_cloud_job=DbtCloudJob.load(\"my-block-name\"),\n        targeted_retries=5,\n    )\n    return result\n\nrun_dbt_job_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#integrate-dbt-core-cli-commands-with-prefect-flows","title":"Integrate dbt Core CLI commands with Prefect flows","text":"<p>Prefect-dbt supports execution of dbt Core CLI commands. If you don't have a <code>DbtCoreOperation</code> block saved, create one and set the commands that you want to run.</p> <p>Optionally, specify the <code>project_dir</code>. If <code>profiles_dir</code> is not set, the <code>DBT_PROFILES_DIR</code> environment variable will be used. If <code>DBT_PROFILES_DIR</code> is not set, the default directory will be used <code>$HOME/.dbt/</code>.</p>"},{"location":"integrations/prefect-dbt/#use-an-existing-profile","title":"Use an existing profile","text":"<p>If you have an existing dbt profile, specify the <code>profiles_dir</code> where <code>profiles.yml</code> is located:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cli.commands import DbtCoreOperation\n\n\n@flow\ndef trigger_dbt_flow() -&gt; str:\n    result = DbtCoreOperation(\n        commands=[\"pwd\", \"dbt debug\", \"dbt run\"],\n        project_dir=\"PROJECT-DIRECTORY-PLACEHOLDER\",\n        profiles_dir=\"PROFILES-DIRECTORY-PLACEHOLDER\"\n    ).run()\n    return result\n\n\nif __name__ == \"__main__\":\n    trigger_dbt_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#set-up-a-new-profile","title":"Set up a new profile","text":"<p>To setup a new profile, first save and load a DbtCliProfile block and use it in <code>DbtCoreOperation</code>.</p> <p>Then, specify<code>profiles_dir</code> where <code>profiles.yml</code> will be written. Here's example code with placeholders:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cli import DbtCliProfile, DbtCoreOperation\n\n\n@flow\ndef trigger_dbt_flow():\n    dbt_cli_profile = DbtCliProfile.load(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n    with DbtCoreOperation(\n        commands=[\"dbt debug\", \"dbt run\"],\n        project_dir=\"PROJECT-DIRECTORY-PLACEHOLDER\",\n        profiles_dir=\"PROFILES-DIRECTORY-PLACEHOLDER\",\n        dbt_cli_profile=dbt_cli_profile,\n    ) as dbt_operation:\n        dbt_process = dbt_operation.trigger()\n        # do other things before waiting for completion\n        dbt_process.wait_for_completion()\n        result = dbt_process.fetch_result()\n    return result\n\nif __name__ == \"__main__\":\n    trigger_dbt_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#save-credentials-to-a-block","title":"Save credentials to a block","text":"<p>Blocks can be created through code or through the UI.</p>"},{"location":"integrations/prefect-dbt/#dbt-cloud","title":"dbt Cloud","text":"<p>To create a dbt Cloud Credentials block do the following:</p> <ol> <li>Go to your dbt Cloud profile.</li> <li>Log in to your dbt Cloud account.</li> <li>Scroll to API or click API Access on the sidebar.</li> <li>Copy the API Key.</li> <li>Click Projects on the sidebar.</li> <li>Copy the account ID from the URL: <code>https://cloud.getdbt.com/settings/accounts/&lt;ACCOUNT_ID&gt;</code>.</li> <li>Create and run the following script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\nDbtCloudCredentials(\n    api_key=\"API-KEY-PLACEHOLDER\",\n    account_id=\"ACCOUNT-ID-PLACEHOLDER\"\n).save(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Then, to create a dbt Cloud job block do the following:</p> <ol> <li>Navigate to your dbt home page.</li> <li>On the top nav bar, click on Deploy -&gt; Jobs.</li> <li>Select a job.</li> <li>Copy the job ID from the URL: <code>https://cloud.getdbt.com/deploy/&lt;ACCOUNT_ID&gt;/projects/&lt;PROJECT_ID&gt;/jobs/&lt;JOB_ID&gt;</code></li> <li>Create and run the following script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\ndbt_cloud_credentials = DbtCloudCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\ndbt_cloud_job = DbtCloudJob(\n    dbt_cloud_credentials=dbt_cloud_credentials,\n    job_id=\"JOB-ID-PLACEHOLDER\"\n).save(\"JOB-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Load the saved block, which can access your credentials:</p> <pre><code>from prefect_dbt.cloud import DbtCloudJob\n\nDbtCloudJob.load(\"JOB-BLOCK-NAME-PLACEHOLDER\")\n</code></pre>"},{"location":"integrations/prefect-dbt/#dbt-core-cli","title":"dbt Core CLI","text":"<p>Available <code>TargetConfigs</code> blocks</p> <p>Visit the API Reference to see other built-in <code>TargetConfigs</code> blocks.</p> <p>If the desired service profile is not available, check out the Examples Catalog to see how you can  build one from the generic <code>TargetConfigs</code> class.</p> <p>To create dbt Core target config and profile blocks for BigQuery:</p> <ol> <li>Save and load a <code>GcpCredentials</code> block.</li> <li>Determine the schema / dataset you want to use in BigQuery.</li> <li>Create a short script, replacing the placeholders.</li> </ol> <pre><code>from prefect_gcp.credentials import GcpCredentials\nfrom prefect_dbt.cli import BigQueryTargetConfigs, DbtCliProfile\n\ncredentials = GcpCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\ntarget_configs = BigQueryTargetConfigs(\n    schema=\"SCHEMA-NAME-PLACEHOLDER\",  # also known as dataset\n    credentials=credentials,\n)\ntarget_configs.save(\"TARGET-CONFIGS-BLOCK-NAME-PLACEHOLDER\")\n\ndbt_cli_profile = DbtCliProfile(\n    name=\"PROFILE-NAME-PLACEHOLDER\",\n    target=\"TARGET-NAME-placeholder\",\n    target_configs=target_configs,\n)\ndbt_cli_profile.save(\"DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>To create a dbt Core operation block:</p> <ol> <li>Determine the dbt commands you want to run.</li> <li>Create a short script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cli import DbtCliProfile, DbtCoreOperation\n\ndbt_cli_profile = DbtCliProfile.load(\"DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER\")\ndbt_core_operation = DbtCoreOperation(\n    commands=[\"DBT-CLI-COMMANDS-PLACEHOLDER\"],\n    dbt_cli_profile=dbt_cli_profile,\n    overwrite_profiles=True,\n)\ndbt_core_operation.save(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Load the saved block that holds your credentials:</p> <pre><code>from prefect_dbt.cloud import DbtCoreOperation\n\nDbtCoreOperation.load(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n</code></pre>"},{"location":"integrations/prefect-dbt/#resources","title":"Resources","text":"<p>For assistance using dbt, consult the dbt documentation.</p> <p>Refer to the prefect-dbt API documentation linked in the sidebar to explore all the capabilities of the prefect-dbt library.</p>"},{"location":"integrations/prefect-dbt/#additional-installation-options","title":"Additional installation options","text":"<p>Additional installation options for dbt Core with BigQuery, Snowflake, and Postgres are shown below.</p>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-snowflake-profiles","title":"Additional functionality for dbt Core and Snowflake profiles","text":"<pre><code>pip install -U \"prefect-dbt[snowflake]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-bigquery-profiles","title":"Additional functionality for dbt Core and BigQuery profiles","text":"<pre><code>pip install -U \"prefect-dbt[bigquery]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-postgres-profiles","title":"Additional functionality for dbt Core and Postgres profiles","text":"<pre><code>pip install -U \"prefect-dbt[postgres]\"\n</code></pre> <p>Some dbt Core profiles require additional installation</p> <p>According to dbt's Databricks setup page, users must first install the adapter:</p> <p> <pre><code>pip install dbt-databricks\n</code></pre> </p> <p>Check out the desired profile setup page on the sidebar for others.</p>"},{"location":"integrations/prefect-dbt/cli/commands/","title":"Commands","text":""},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands","title":"<code>prefect_dbt.cli.commands</code>","text":"<p>Module containing tasks and flows for interacting with dbt CLI</p>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.DbtCoreOperation","title":"<code>DbtCoreOperation</code>","text":"<p>               Bases: <code>ShellOperation</code></p> <p>A block representing a dbt operation, containing multiple dbt and shell commands.</p> <p>For long-lasting operations, use the trigger method and utilize the block as a context manager for automatic closure of processes when context is exited. If not, manually call the close method to close processes.</p> <p>For short-lasting operations, use the run method. Context is automatically managed with this method.</p> <p>Attributes:</p> Name Type Description <code>commands</code> <p>A list of commands to execute sequentially.</p> <code>stream_output</code> <p>Whether to stream output.</p> <code>env</code> <p>A dictionary of environment variables to set for the shell operation.</p> <code>working_directory</code> <p>The working directory context the commands will be executed within.</p> <code>shell</code> <p>The shell to use to execute the commands.</p> <code>extension</code> <p>The extension to use for the temporary file. if unset defaults to <code>.ps1</code> on Windows and <code>.sh</code> on other platforms.</p> <code>profiles_dir</code> <code>Optional[Path]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the dbt commands provided. If this is not set, will try using the DBT_PROFILES_DIR environment variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>project_dir</code> <code>Optional[Path]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <p>Examples:</p> <p>Load a configured block. <pre><code>from prefect_dbt import DbtCoreOperation\n\ndbt_op = DbtCoreOperation.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Execute short-lasting dbt debug and list with a custom DbtCliProfile. <pre><code>from prefect_dbt import DbtCoreOperation, DbtCliProfile\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake import SnowflakeConnector\n\nsnowflake_connector = await SnowflakeConnector.load(\"snowflake-connector\")\ntarget_configs = SnowflakeTargetConfigs(connector=snowflake_connector)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\ndbt_init = DbtCoreOperation(\n    commands=[\"dbt debug\", \"dbt list\"],\n    dbt_cli_profile=dbt_cli_profile,\n    overwrite_profiles=True\n)\ndbt_init.run()\n</code></pre></p> <p>Execute a longer-lasting dbt run as a context manager. <pre><code>with DbtCoreOperation(commands=[\"dbt run\"]) as dbt_run:\n    dbt_process = dbt_run.trigger()\n    # do other things\n    dbt_process.wait_for_completion()\n    dbt_output = dbt_process.fetch_result()\n</code></pre></p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>class DbtCoreOperation(ShellOperation):\n    \"\"\"\n    A block representing a dbt operation, containing multiple dbt and shell commands.\n\n    For long-lasting operations, use the trigger method and utilize the block as a\n    context manager for automatic closure of processes when context is exited.\n    If not, manually call the close method to close processes.\n\n    For short-lasting operations, use the run method. Context is automatically managed\n    with this method.\n\n    Attributes:\n        commands: A list of commands to execute sequentially.\n        stream_output: Whether to stream output.\n        env: A dictionary of environment variables to set for the shell operation.\n        working_directory: The working directory context the commands\n            will be executed within.\n        shell: The shell to use to execute the commands.\n        extension: The extension to use for the temporary file.\n            if unset defaults to `.ps1` on Windows and `.sh` on other platforms.\n        profiles_dir: The directory to search for the profiles.yml file.\n            Setting this appends the `--profiles-dir` option to the dbt commands\n            provided. If this is not set, will try using the DBT_PROFILES_DIR\n            environment variable, but if that's also not\n            set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error if profiles.yml already\n            exists under profile_dir and overwrite_profiles is set to False.\n\n    Examples:\n        Load a configured block.\n        ```python\n        from prefect_dbt import DbtCoreOperation\n\n        dbt_op = DbtCoreOperation.load(\"BLOCK_NAME\")\n        ```\n\n        Execute short-lasting dbt debug and list with a custom DbtCliProfile.\n        ```python\n        from prefect_dbt import DbtCoreOperation, DbtCliProfile\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake import SnowflakeConnector\n\n        snowflake_connector = await SnowflakeConnector.load(\"snowflake-connector\")\n        target_configs = SnowflakeTargetConfigs(connector=snowflake_connector)\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        dbt_init = DbtCoreOperation(\n            commands=[\"dbt debug\", \"dbt list\"],\n            dbt_cli_profile=dbt_cli_profile,\n            overwrite_profiles=True\n        )\n        dbt_init.run()\n        ```\n\n        Execute a longer-lasting dbt run as a context manager.\n        ```python\n        with DbtCoreOperation(commands=[\"dbt run\"]) as dbt_run:\n            dbt_process = dbt_run.trigger()\n            # do other things\n            dbt_process.wait_for_completion()\n            dbt_output = dbt_process.fetch_result()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Core Operation\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.DbtCoreOperation\"  # noqa\n\n    profiles_dir: Optional[Path] = Field(\n        default=None,\n        description=(\n            \"The directory to search for the profiles.yml file. \"\n            \"Setting this appends the `--profiles-dir` option to the dbt commands \"\n            \"provided. If this is not set, will try using the DBT_PROFILES_DIR \"\n            \"environment variable, but if that's also not \"\n            \"set, will use the default directory `$HOME/.dbt/`.\"\n        ),\n    )\n    project_dir: Optional[Path] = Field(\n        default=None,\n        description=(\n            \"The directory to search for the dbt_project.yml file. \"\n            \"Default is the current working directory and its parents.\"\n        ),\n    )\n    overwrite_profiles: bool = Field(\n        default=False,\n        description=(\n            \"Whether the existing profiles.yml file under profiles_dir \"\n            \"should be overwritten with a new profile.\"\n        ),\n    )\n    dbt_cli_profile: Optional[DbtCliProfile] = Field(\n        default=None,\n        description=(\n            \"Profiles class containing the profile written to profiles.yml. \"\n            \"Note! This is optional and will raise an error if profiles.yml already \"\n            \"exists under profile_dir and overwrite_profiles is set to False.\"\n        ),\n    )\n\n    @validator(\"commands\", always=True)\n    def _has_a_dbt_command(cls, commands):\n        \"\"\"\n        Check that the commands contain a dbt command.\n        \"\"\"\n        if not any(\"dbt \" in command for command in commands):\n            raise ValueError(\n                \"None of the commands are a valid dbt sub-command; see dbt --help, \"\n                \"or use prefect_shell.ShellOperation for non-dbt related \"\n                \"commands instead\"\n            )\n        return commands\n\n    def _find_valid_profiles_dir(self) -&gt; PosixPath:\n        \"\"\"\n        Ensure that there is a profiles.yml available for use.\n        \"\"\"\n        profiles_dir = self.profiles_dir\n        if profiles_dir is None:\n            if self.env.get(\"DBT_PROFILES_DIR\") is not None:\n                # get DBT_PROFILES_DIR from the user input env\n                profiles_dir = self.env[\"DBT_PROFILES_DIR\"]\n            else:\n                # get DBT_PROFILES_DIR from the system env, or default to ~/.dbt\n                profiles_dir = os.getenv(\"DBT_PROFILES_DIR\", Path.home() / \".dbt\")\n        profiles_dir = relative_path_to_current_platform(\n            Path(profiles_dir).expanduser()\n        )\n\n        # https://docs.getdbt.com/dbt-cli/configure-your-profile\n        # Note that the file always needs to be called profiles.yml,\n        # regardless of which directory it is in.\n        profiles_path = profiles_dir / \"profiles.yml\"\n        overwrite_profiles = self.overwrite_profiles\n        dbt_cli_profile = self.dbt_cli_profile\n        if not profiles_path.exists() or overwrite_profiles:\n            if dbt_cli_profile is None:\n                raise ValueError(\n                    \"Since overwrite_profiles is True or profiles_path is empty, \"\n                    \"need `dbt_cli_profile` to write a profile\"\n                )\n            profile = dbt_cli_profile.get_profile()\n            profiles_dir.mkdir(exist_ok=True)\n            with open(profiles_path, \"w+\") as f:\n                yaml.dump(profile, f, default_flow_style=False)\n        elif dbt_cli_profile is not None:\n            raise ValueError(\n                f\"Since overwrite_profiles is False and profiles_path {profiles_path} \"\n                f\"already exists, the profile within dbt_cli_profile couldn't be used; \"\n                f\"if the existing profile is satisfactory, do not set dbt_cli_profile\"\n            )\n        return profiles_dir\n\n    def _append_dirs_to_commands(self, profiles_dir) -&gt; List[str]:\n        \"\"\"\n        Append profiles_dir and project_dir options to dbt commands.\n        \"\"\"\n        project_dir = self.project_dir\n\n        commands = []\n        for command in self.commands:\n            command += f\" --profiles-dir {profiles_dir}\"\n            if project_dir is not None:\n                project_dir = Path(project_dir).expanduser()\n                command += f\" --project-dir {project_dir}\"\n            commands.append(command)\n        return commands\n\n    def _compile_kwargs(self, **open_kwargs: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Helper method to compile the kwargs for `open_process` so it's not repeated\n        across the run and trigger methods.\n        \"\"\"\n        profiles_dir = self._find_valid_profiles_dir()\n        commands = self._append_dirs_to_commands(profiles_dir=profiles_dir)\n\n        # _compile_kwargs is called within trigger() and run(), prior to execution.\n        # However _compile_kwargs directly uses self.commands, but here we modified\n        # the commands without saving back to self.commands so we need to create a copy.\n        # was also thinking of using env vars but DBT_PROJECT_DIR is not supported yet.\n        modified_self = self.copy()\n        modified_self.commands = commands\n        return super(type(self), modified_self)._compile_kwargs(**open_kwargs)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.create_summary_markdown","title":"<code>create_summary_markdown</code>","text":"<p>Creates a Prefect task artifact summarizing the results of the above predefined prefrect-dbt task.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>def create_summary_markdown(run_results: dict, command: str) -&gt; str:\n    \"\"\"\n    Creates a Prefect task artifact summarizing the results\n    of the above predefined prefrect-dbt task.\n    \"\"\"\n    markdown = f\"# dbt {command} Task Summary\\n\"\n    markdown += _create_node_summary_table_md(run_results=run_results)\n\n    if (\n        run_results[\"Error\"] != []\n        or run_results[\"Fail\"] != []\n        or run_results[\"Skipped\"] != []\n        or run_results[\"Warn\"] != []\n    ):\n        markdown += \"\\n\\n ## Unsuccessful Nodes \u274c\\n\\n\"\n        markdown += _create_unsuccessful_markdown(run_results=run_results)\n\n    if run_results[\"Success\"] != []:\n        successful_runs_str = \"\\n\".join(\n            [f\"* {r.node.name}\" for r in run_results[\"Success\"]]\n        )\n        markdown += f\"\"\"\\n## Successful Nodes \u2705\\n\\n{successful_runs_str}\\n\\n\"\"\"\n\n    return markdown\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_build","title":"<code>run_dbt_build</code>  <code>async</code>","text":"<p>Executes the 'dbt build' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-build-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt build command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_build_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_build_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_build(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-build-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt build' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-build-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt build command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_build_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_build_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"build\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_model","title":"<code>run_dbt_model</code>  <code>async</code>","text":"<p>Executes the 'dbt run' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt run results artifact in Prefect. Defaults to 'dbt-run-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt run command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_run_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_run_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_model(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-run-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt run' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt run results artifact in Prefect.\n            Defaults to 'dbt-run-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt run command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_run_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_run_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"run\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_seed","title":"<code>run_dbt_seed</code>  <code>async</code>","text":"<p>Executes the 'dbt seed' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-seed-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt seed command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_seed_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_seed_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--fail-fast\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_seed(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-seed-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt seed' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-seed-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt seed command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_seed_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_seed_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--fail-fast\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"seed\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_snapshot","title":"<code>run_dbt_snapshot</code>  <code>async</code>","text":"<p>Executes the 'dbt snapshot' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-snapshot-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt snapshot command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_snapshot_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_snapshot_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--fail-fast\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_snapshot(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-snapshot-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt snapshot' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-snapshot-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt snapshot command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_snapshot_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_snapshot_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--fail-fast\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"snapshot\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_test","title":"<code>run_dbt_test</code>  <code>async</code>","text":"<p>Executes the 'dbt test' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt test results artifact in Prefect. Defaults to 'dbt-test-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt test command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_test_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_test_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_test(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-test-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt test' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt test results artifact in Prefect.\n            Defaults to 'dbt-test-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt test command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_test_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_test_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"test\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.trigger_dbt_cli_command","title":"<code>trigger_dbt_cli_command</code>  <code>async</code>","text":"<p>Task for running dbt commands.</p> <p>If no profiles.yml file is found or if overwrite_profiles flag is set to True, this will first generate a profiles.yml file in the profiles_dir directory. Then run the dbt CLI shell command.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The dbt command to be executed.</p> required <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR environment variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-seed-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt command. These arguments get appended to the command that gets passed to the dbtRunner client. Example: extra_command_args=[\"--model\", \"foo_model\"]</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <p>Returns:</p> Name Type Description <code>last_line_cli_output</code> <code>str</code> <p>The last line of the CLI output will be returned if <code>return_all</code> in <code>shell_run_command_kwargs</code> is False. This is the default behavior.</p> <code>full_cli_output</code> <code>List[str]</code> <p>Full CLI output will be returned if <code>return_all</code> in <code>shell_run_command_kwargs</code> is True.</p> <p>Examples:</p> <p>Execute <code>dbt debug</code> with a pre-populated profiles.yml. <pre><code>from prefect import flow\nfrom prefect_dbt.cli.commands import trigger_dbt_cli_command\n\n@flow\ndef trigger_dbt_cli_command_flow():\n    result = trigger_dbt_cli_command(\"dbt debug\")\n    return result\n\ntrigger_dbt_cli_command_flow()\n</code></pre></p> <p>Execute <code>dbt debug</code> without a pre-populated profiles.yml. <pre><code>from prefect import flow\nfrom prefect_dbt.cli.credentials import DbtCliProfile\nfrom prefect_dbt.cli.commands import trigger_dbt_cli_command\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\n\n@flow\ndef trigger_dbt_cli_command_flow():\n    credentials = SnowflakeCredentials(\n        user=\"user\",\n        password=\"password\",\n        account=\"account.region.aws\",\n        role=\"role\",\n    )\n    connector = SnowflakeConnector(\n        schema=\"public\",\n        database=\"database\",\n        warehouse=\"warehouse\",\n        credentials=credentials,\n    )\n    target_configs = SnowflakeTargetConfigs(\n        connector=connector\n    )\n    dbt_cli_profile = DbtCliProfile(\n        name=\"jaffle_shop\",\n        target=\"dev\",\n        target_configs=target_configs,\n    )\n    result = trigger_dbt_cli_command(\n        \"dbt run\",\n        overwrite_profiles=True,\n        dbt_cli_profile=dbt_cli_profile,\n        extra_command_args=[\"--model\", \"foo_model\"]\n    )\n    return result\n\ntrigger_dbt_cli_command_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def trigger_dbt_cli_command(\n    command: str,\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: Optional[str] = \"dbt-cli-command-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n) -&gt; Optional[dbtRunnerResult]:\n    \"\"\"\n    Task for running dbt commands.\n\n    If no profiles.yml file is found or if overwrite_profiles flag is set to True, this\n    will first generate a profiles.yml file in the profiles_dir directory. Then run the dbt\n    CLI shell command.\n\n    Args:\n        command: The dbt command to be executed.\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided. If this is not set,\n            will try using the DBT_PROFILES_DIR environment variable, but if that's also not\n            set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error if profiles.yml already exists\n            under profile_dir and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-seed-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt command.\n            These arguments get appended to the command that gets passed to the dbtRunner client.\n            Example: extra_command_args=[\"--model\", \"foo_model\"]\n        stream_output: Whether to stream output.\n\n    Returns:\n        last_line_cli_output (str): The last line of the CLI output will be returned\n            if `return_all` in `shell_run_command_kwargs` is False. This is the default\n            behavior.\n        full_cli_output (List[str]): Full CLI output will be returned if `return_all`\n            in `shell_run_command_kwargs` is True.\n\n    Examples:\n        Execute `dbt debug` with a pre-populated profiles.yml.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cli.commands import trigger_dbt_cli_command\n\n        @flow\n        def trigger_dbt_cli_command_flow():\n            result = trigger_dbt_cli_command(\"dbt debug\")\n            return result\n\n        trigger_dbt_cli_command_flow()\n        ```\n\n        Execute `dbt debug` without a pre-populated profiles.yml.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cli.credentials import DbtCliProfile\n        from prefect_dbt.cli.commands import trigger_dbt_cli_command\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n\n        @flow\n        def trigger_dbt_cli_command_flow():\n            credentials = SnowflakeCredentials(\n                user=\"user\",\n                password=\"password\",\n                account=\"account.region.aws\",\n                role=\"role\",\n            )\n            connector = SnowflakeConnector(\n                schema=\"public\",\n                database=\"database\",\n                warehouse=\"warehouse\",\n                credentials=credentials,\n            )\n            target_configs = SnowflakeTargetConfigs(\n                connector=connector\n            )\n            dbt_cli_profile = DbtCliProfile(\n                name=\"jaffle_shop\",\n                target=\"dev\",\n                target_configs=target_configs,\n            )\n            result = trigger_dbt_cli_command(\n                \"dbt run\",\n                overwrite_profiles=True,\n                dbt_cli_profile=dbt_cli_profile,\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n            return result\n\n        trigger_dbt_cli_command_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    if profiles_dir is None:\n        profiles_dir = os.getenv(\"DBT_PROFILES_DIR\", str(Path.home()) + \"/.dbt\")\n\n    if command.startswith(\"dbt\"):\n        command = command.split(\" \", 1)[1]\n\n    # https://docs.getdbt.com/dbt-cli/configure-your-profile\n    # Note that the file always needs to be called profiles.yml,\n    # regardless of which directory it is in.\n    profiles_path = profiles_dir + \"/profiles.yml\"\n    logger.debug(f\"Using this profiles path: {profiles_path}\")\n\n    # write the profile if overwrite or no profiles exist\n    if overwrite_profiles or not Path(profiles_path).expanduser().exists():\n        if dbt_cli_profile is None:\n            raise ValueError(\"Provide `dbt_cli_profile` keyword for writing profiles\")\n        profile = dbt_cli_profile.get_profile()\n        Path(profiles_dir).expanduser().mkdir(exist_ok=True)\n        with open(profiles_path, \"w+\") as f:\n            yaml.dump(profile, f, default_flow_style=False)\n        logger.info(f\"Wrote profile to {profiles_path}\")\n    elif dbt_cli_profile is not None:\n        raise ValueError(\n            f\"Since overwrite_profiles is False and profiles_path ({profiles_path}) \"\n            f\"already exists, the profile within dbt_cli_profile could not be used; \"\n            f\"if the existing profile is satisfactory, do not pass dbt_cli_profile\"\n        )\n\n    # append the options\n    cli_args = command.split(\" \")\n    cli_args.append(\"--profiles-dir\")\n    cli_args.append(profiles_dir)\n    if project_dir is not None:\n        project_dir = Path(project_dir).expanduser()\n        cli_args.append(\"--project-dir\")\n        cli_args.append(project_dir)\n\n    if extra_command_args:\n        for value in extra_command_args:\n            cli_args.append(value)\n\n    # Add the dbt event log callback if enabled\n    callbacks = []\n    if stream_output:\n\n        def _stream_output(event):\n            if event.info.level != \"debug\":\n                logger.info(event.info.msg)\n\n        callbacks.append(_stream_output)\n\n    # fix up empty shell_run_command_kwargs\n    dbt_runner_client = dbtRunner(callbacks=callbacks)\n    logger.info(f\"Running dbt command: {cli_args}\")\n    result: dbtRunnerResult = dbt_runner_client.invoke(cli_args)\n\n    if result.exception is not None:\n        logger.error(f\"dbt task failed with exception: {result.exception}\")\n        raise result.exception\n\n    # Creating the dbt Summary Markdown if enabled\n    if create_summary_artifact and isinstance(result.result, RunExecutionResult):\n        run_results = consolidate_run_results(result)\n        markdown = create_summary_markdown(run_results, command)\n        artifact_id = await create_markdown_artifact(\n            markdown=markdown,\n            key=summary_artifact_key,\n        )\n        if not artifact_id:\n            logger.error(f\"Summary Artifact was not created for dbt {command} task\")\n        else:\n            logger.info(\n                f\"dbt {command} task completed successfully with artifact {artifact_id}\"\n            )\n    else:\n        logger.debug(\n            f\"Artifacts were not created for dbt {command} this task \\\n                     due to create_artifact=False or the dbt command did not \\\n                     return any RunExecutionResults. \\\n                     See https://docs.getdbt.com/reference/programmatic-invocations \\\n                     for more details on dbtRunnerResult.\"\n        )\n    if isinstance(result.result, RunExecutionResult) and not result.success:\n        return Failed(\n            message=f\"dbt task result unsuccessful with exception: {result.exception}\"\n        )\n    return result\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials","title":"<code>prefect_dbt.cli.credentials</code>","text":"<p>Module containing credentials for interacting with dbt CLI</p>"},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile","title":"<code>DbtCliProfile</code>","text":"<p>               Bases: <code>Block</code></p> <p>Profile for use across dbt CLI tasks and flows.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Profile name used for populating profiles.yml.</p> <code>target</code> <code>str</code> <p>The default target your dbt project will use.</p> <code>target_configs</code> <code>TargetConfigs</code> <p>Target configs contain credentials and settings, specific to the warehouse you're connecting to. To find valid keys, head to the Available adapters page and click the desired adapter's \"Profile Setup\" hyperlink.</p> <code>global_configs</code> <code>GlobalConfigs</code> <p>Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model. Valid keys can be found here.</p> <p>Examples:</p> <p>Load stored dbt CLI profile: <pre><code>from prefect_dbt.cli import DbtCliProfile\ndbt_cli_profile = DbtCliProfile.load(\"BLOCK_NAME\").get_profile()\n</code></pre></p> <p>Get a dbt Snowflake profile from DbtCliProfile by using SnowflakeTargetConfigs: <pre><code>from prefect_dbt.cli import DbtCliProfile\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\ncredentials = SnowflakeCredentials(\n    user=\"user\",\n    password=\"password\",\n    account=\"account.region.aws\",\n    role=\"role\",\n)\nconnector = SnowflakeConnector(\n    schema=\"public\",\n    database=\"database\",\n    warehouse=\"warehouse\",\n    credentials=credentials,\n)\ntarget_configs = SnowflakeTargetConfigs(\n    connector=connector\n)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\nprofile = dbt_cli_profile.get_profile()\n</code></pre></p> <p>Get a dbt Redshift profile from DbtCliProfile by using generic TargetConfigs: <pre><code>from prefect_dbt.cli import DbtCliProfile\nfrom prefect_dbt.cli.configs import GlobalConfigs, TargetConfigs\n\ntarget_configs_extras = dict(\n    host=\"hostname.region.redshift.amazonaws.com\",\n    user=\"username\",\n    password=\"password1\",\n    port=5439,\n    dbname=\"analytics\",\n)\ntarget_configs = TargetConfigs(\n    type=\"redshift\",\n    schema=\"schema\",\n    threads=4,\n    extras=target_configs_extras\n)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\nprofile = dbt_cli_profile.get_profile()\n</code></pre></p> Source code in <code>prefect_dbt/cli/credentials.py</code> <pre><code>class DbtCliProfile(Block):\n    \"\"\"\n    Profile for use across dbt CLI tasks and flows.\n\n    Attributes:\n        name (str): Profile name used for populating profiles.yml.\n        target (str): The default target your dbt project will use.\n        target_configs (TargetConfigs): Target configs contain credentials and\n            settings, specific to the warehouse you're connecting to.\n            To find valid keys, head to the [Available adapters](\n            https://docs.getdbt.com/docs/available-adapters) page and\n            click the desired adapter's \"Profile Setup\" hyperlink.\n        global_configs (GlobalConfigs): Global configs control\n            things like the visual output of logs, the manner\n            in which dbt parses your project, and what to do when\n            dbt finds a version mismatch or a failing model.\n            Valid keys can be found [here](\n            https://docs.getdbt.com/reference/global-configs).\n\n    Examples:\n        Load stored dbt CLI profile:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        dbt_cli_profile = DbtCliProfile.load(\"BLOCK_NAME\").get_profile()\n        ```\n\n        Get a dbt Snowflake profile from DbtCliProfile by using SnowflakeTargetConfigs:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        credentials = SnowflakeCredentials(\n            user=\"user\",\n            password=\"password\",\n            account=\"account.region.aws\",\n            role=\"role\",\n        )\n        connector = SnowflakeConnector(\n            schema=\"public\",\n            database=\"database\",\n            warehouse=\"warehouse\",\n            credentials=credentials,\n        )\n        target_configs = SnowflakeTargetConfigs(\n            connector=connector\n        )\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        profile = dbt_cli_profile.get_profile()\n        ```\n\n        Get a dbt Redshift profile from DbtCliProfile by using generic TargetConfigs:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        from prefect_dbt.cli.configs import GlobalConfigs, TargetConfigs\n\n        target_configs_extras = dict(\n            host=\"hostname.region.redshift.amazonaws.com\",\n            user=\"username\",\n            password=\"password1\",\n            port=5439,\n            dbname=\"analytics\",\n        )\n        target_configs = TargetConfigs(\n            type=\"redshift\",\n            schema=\"schema\",\n            threads=4,\n            extras=target_configs_extras\n        )\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        profile = dbt_cli_profile.get_profile()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Profile\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile\"  # noqa\n\n    name: str = Field(\n        default=..., description=\"Profile name used for populating profiles.yml.\"\n    )\n    target: str = Field(\n        default=..., description=\"The default target your dbt project will use.\"\n    )\n    target_configs: Union[\n        SnowflakeTargetConfigs,\n        BigQueryTargetConfigs,\n        PostgresTargetConfigs,\n        TargetConfigs,\n    ] = Field(\n        default=...,\n        description=(\n            \"Target configs contain credentials and settings, specific to the \"\n            \"warehouse you're connecting to.\"\n        ),\n    )\n    global_configs: Optional[GlobalConfigs] = Field(\n        default=None,\n        description=(\n            \"Global configs control things like the visual output of logs, the manner \"\n            \"in which dbt parses your project, and what to do when dbt finds a version \"\n            \"mismatch or a failing model.\"\n        ),\n    )\n\n    def get_profile(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt profile, likely used for writing to profiles.yml.\n\n        Returns:\n            A JSON compatible dictionary with the expected format of profiles.yml.\n        \"\"\"\n        profile = {\n            \"config\": self.global_configs.get_configs() if self.global_configs else {},\n            self.name: {\n                \"target\": self.target,\n                \"outputs\": {self.target: self.target_configs.get_configs()},\n            },\n        }\n        return profile\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile.get_profile","title":"<code>get_profile</code>","text":"<p>Returns the dbt profile, likely used for writing to profiles.yml.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A JSON compatible dictionary with the expected format of profiles.yml.</p> Source code in <code>prefect_dbt/cli/credentials.py</code> <pre><code>def get_profile(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt profile, likely used for writing to profiles.yml.\n\n    Returns:\n        A JSON compatible dictionary with the expected format of profiles.yml.\n    \"\"\"\n    profile = {\n        \"config\": self.global_configs.get_configs() if self.global_configs else {},\n        self.name: {\n            \"target\": self.target,\n            \"outputs\": {self.target: self.target_configs.get_configs()},\n        },\n    }\n    return profile\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/","title":"Base","text":""},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base","title":"<code>prefect_dbt.cli.configs.base</code>","text":"<p>Module containing models for base configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs","title":"<code>DbtConfigs</code>","text":"<p>               Bases: <code>Block</code>, <code>ABC</code></p> <p>Abstract class for other dbt Configs.</p> <p>Attributes:</p> Name Type Description <code>extras</code> <code>Optional[Dict[str, Any]]</code> <p>Extra target configs' keywords, not yet exposed in prefect-dbt, but available in dbt; if there are duplicate keys between extras and TargetConfigs, an error will be raised.</p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class DbtConfigs(Block, abc.ABC):\n    \"\"\"\n    Abstract class for other dbt Configs.\n\n    Attributes:\n        extras: Extra target configs' keywords, not yet exposed\n            in prefect-dbt, but available in dbt; if there are\n            duplicate keys between extras and TargetConfigs,\n            an error will be raised.\n    \"\"\"\n\n    extras: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=(\n            \"Extra target configs' keywords, not yet exposed in prefect-dbt, \"\n            \"but available in dbt.\"\n        ),\n    )\n    allow_field_overrides: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, fields from dbt target configs will override \"\n            \"fields provided in extras and credentials.\"\n        ),\n    )\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs\"  # noqa\n\n    def _populate_configs_json(\n        self,\n        configs_json: Dict[str, Any],\n        fields: Dict[str, Any],\n        model: BaseModel = None,\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Recursively populate configs_json.\n        \"\"\"\n        # if allow_field_overrides is True keys from TargetConfigs take precedence\n        override_configs_json = {}\n\n        for field_name, field in fields.items():\n            if model is not None:\n                # get actual value from model\n                try:\n                    field_value = getattr(model, field_name)\n                except AttributeError:\n                    field_value = getattr(model, field.alias)\n                # override the name with alias so dbt parser can recognize the keyword;\n                # e.g. schema_ -&gt; schema, returns the original name if no alias is set\n                field_name = field.alias\n            else:\n                field_value = field\n\n            if field_value is None or field_name == \"allow_field_overrides\":\n                # do not add to configs json if no value or default is set\n                continue\n\n            if isinstance(field_value, BaseModel):\n                configs_json = self._populate_configs_json(\n                    configs_json, field_value.__fields__, model=field_value\n                )\n            elif field_name == \"extras\":\n                configs_json = self._populate_configs_json(\n                    configs_json,\n                    field_value,\n                )\n                override_configs_json.update(configs_json)\n            else:\n                if field_name in configs_json.keys() and not self.allow_field_overrides:\n                    raise ValueError(\n                        f\"The keyword, {field_name}, has already been provided in \"\n                        f\"TargetConfigs; remove duplicated keywords to continue\"\n                    )\n                if isinstance(field_value, SecretField):\n                    field_value = field_value.get_secret_value()\n                elif isinstance(field_value, Path):\n                    field_value = str(field_value)\n                configs_json[field_name] = field_value\n\n                if self.allow_field_overrides and model is self or model is None:\n                    override_configs_json[field_name] = field_value\n\n        configs_json.update(override_configs_json)\n        return configs_json\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs, likely used eventually for writing to profiles.yml.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        return self._populate_configs_json({}, self.__fields__, model=self)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs, likely used eventually for writing to profiles.yml.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs, likely used eventually for writing to profiles.yml.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    return self._populate_configs_json({}, self.__fields__, model=self)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.GlobalConfigs","title":"<code>GlobalConfigs</code>","text":"<p>               Bases: <code>DbtConfigs</code></p> <p>Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model. Docs can be found here.</p> <p>Attributes:</p> Name Type Description <code>send_anonymous_usage_stats</code> <code>Optional[bool]</code> <p>Whether usage stats are sent to dbt.</p> <code>use_colors</code> <code>Optional[bool]</code> <p>Colorize the output it prints in your terminal.</p> <code>partial_parse</code> <code>Optional[bool]</code> <p>When partial parsing is enabled, dbt will use an stored internal manifest to determine which files have been changed (if any) since it last parsed the project.</p> <code>printer_width</code> <code>Optional[int]</code> <p>Length of characters before starting a new line.</p> <code>write_json</code> <code>Optional[bool]</code> <p>Determines whether dbt writes JSON artifacts to the target/ directory.</p> <code>warn_error</code> <code>Optional[bool]</code> <p>Whether to convert dbt warnings into errors.</p> <code>log_format</code> <code>Optional[str]</code> <p>The LOG_FORMAT config specifies how dbt's logs should be formatted. If the value of this config is json, dbt will output fully structured logs in JSON format.</p> <code>debug</code> <code>Optional[bool]</code> <p>Whether to redirect dbt's debug logs to standard out.</p> <code>version_check</code> <code>Optional[bool]</code> <p>Whether to raise an error if a project's version is used with an incompatible dbt version.</p> <code>fail_fast</code> <code>Optional[bool]</code> <p>Make dbt exit immediately if a single resource fails to build.</p> <code>use_experimental_parser</code> <code>Optional[bool]</code> <p>Opt into the latest experimental version of the static parser.</p> <code>static_parser</code> <code>Optional[bool]</code> <p>Whether to use the static parser.</p> <p>Examples:</p> <p>Load stored GlobalConfigs: <pre><code>from prefect_dbt.cli.configs import GlobalConfigs\n\ndbt_cli_global_configs = GlobalConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class GlobalConfigs(DbtConfigs):\n    \"\"\"\n    Global configs control things like the visual output\n    of logs, the manner in which dbt parses your project,\n    and what to do when dbt finds a version mismatch\n    or a failing model. Docs can be found [here](\n    https://docs.getdbt.com/reference/global-configs).\n\n    Attributes:\n        send_anonymous_usage_stats: Whether usage stats are sent to dbt.\n        use_colors: Colorize the output it prints in your terminal.\n        partial_parse: When partial parsing is enabled, dbt will use an\n            stored internal manifest to determine which files have been changed\n            (if any) since it last parsed the project.\n        printer_width: Length of characters before starting a new line.\n        write_json: Determines whether dbt writes JSON artifacts to\n            the target/ directory.\n        warn_error: Whether to convert dbt warnings into errors.\n        log_format: The LOG_FORMAT config specifies how dbt's logs should\n            be formatted. If the value of this config is json, dbt will\n            output fully structured logs in JSON format.\n        debug: Whether to redirect dbt's debug logs to standard out.\n        version_check: Whether to raise an error if a project's version\n            is used with an incompatible dbt version.\n        fail_fast: Make dbt exit immediately if a single resource fails to build.\n        use_experimental_parser: Opt into the latest experimental version\n            of the static parser.\n        static_parser: Whether to use the [static parser](\n            https://docs.getdbt.com/reference/parsing#static-parser).\n\n    Examples:\n        Load stored GlobalConfigs:\n        ```python\n        from prefect_dbt.cli.configs import GlobalConfigs\n\n        dbt_cli_global_configs = GlobalConfigs.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Global Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.GlobalConfigs\"  # noqa\n\n    send_anonymous_usage_stats: Optional[bool] = Field(\n        default=None,\n        description=\"Whether usage stats are sent to dbt.\",\n    )\n    use_colors: Optional[bool] = Field(\n        default=None,\n        description=\"Colorize the output it prints in your terminal.\",\n    )\n    partial_parse: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"When partial parsing is enabled, dbt will use an \"\n            \"stored internal manifest to determine which files have been changed \"\n            \"(if any) since it last parsed the project.\"\n        ),\n    )\n    printer_width: Optional[int] = Field(\n        default=None,\n        description=\"Length of characters before starting a new line.\",\n    )\n    write_json: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Determines whether dbt writes JSON artifacts to \" \"the target/ directory.\"\n        ),\n    )\n    warn_error: Optional[bool] = Field(\n        default=None,\n        description=\"Whether to convert dbt warnings into errors.\",\n    )\n    log_format: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The LOG_FORMAT config specifies how dbt's logs should \"\n            \"be formatted. If the value of this config is json, dbt will \"\n            \"output fully structured logs in JSON format.\"\n        ),\n    )\n    debug: Optional[bool] = Field(\n        default=None,\n        description=\"Whether to redirect dbt's debug logs to standard out.\",\n    )\n    version_check: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether to raise an error if a project's version \"\n            \"is used with an incompatible dbt version.\"\n        ),\n    )\n    fail_fast: Optional[bool] = Field(\n        default=None,\n        description=(\"Make dbt exit immediately if a single resource fails to build.\"),\n    )\n    use_experimental_parser: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Opt into the latest experimental version \" \"of the static parser.\"\n        ),\n    )\n    static_parser: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether to use the [static parser](https://docs.getdbt.com/reference/parsing#static-parser).\"  # noqa\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.TargetConfigs","title":"<code>TargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to the warehouse you're connecting to. To find valid keys, head to the Available adapters page and click the desired adapter's \"Profile Setup\" hyperlink.</p> <p>Attributes:</p> Name Type Description <code>type</code> <p>The name of the database warehouse.</p> <code>schema</code> <p>The schema that dbt will build objects into; in BigQuery, a schema is actually a dataset.</p> <code>threads</code> <p>The number of threads representing the max number of paths through the graph dbt may work on at once.</p> <p>Examples:</p> <p>Load stored TargetConfigs: <pre><code>from prefect_dbt.cli.configs import TargetConfigs\n\ndbt_cli_target_configs = TargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class TargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to the warehouse you're connecting to.\n    To find valid keys, head to the [Available adapters](\n    https://docs.getdbt.com/docs/available-adapters) page and\n    click the desired adapter's \"Profile Setup\" hyperlink.\n\n    Attributes:\n        type: The name of the database warehouse.\n        schema: The schema that dbt will build objects into;\n            in BigQuery, a schema is actually a dataset.\n        threads: The number of threads representing the max number\n            of paths through the graph dbt may work on at once.\n\n    Examples:\n        Load stored TargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import TargetConfigs\n\n        dbt_cli_target_configs = TargetConfigs.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.TargetConfigs\"  # noqa\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/","title":"BigQuery","text":""},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery","title":"<code>prefect_dbt.cli.configs.bigquery</code>","text":"<p>Module containing models for BigQuery configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs","title":"<code>BigQueryTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to BigQuery. To find valid keys, head to the BigQuery Profile page.</p> <p>Attributes:</p> Name Type Description <code>credentials</code> <code>GcpCredentials</code> <p>The credentials to use to authenticate; if there are duplicate keys between credentials and TargetConfigs, e.g. schema, an error will be raised.</p> <p>Examples:</p> <p>Load stored BigQueryTargetConfigs. <pre><code>from prefect_dbt.cli.configs import BigQueryTargetConfigs\n\nbigquery_target_configs = BigQueryTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate BigQueryTargetConfigs. <pre><code>from prefect_dbt.cli.configs import BigQueryTargetConfigs\nfrom prefect_gcp.credentials import GcpCredentials\n\ncredentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\ntarget_configs = BigQueryTargetConfigs(\n    schema=\"schema\",  # also known as dataset\n    credentials=credentials,\n)\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/bigquery.py</code> <pre><code>class BigQueryTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to BigQuery.\n    To find valid keys, head to the [BigQuery Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/bigquery-profile)\n    page.\n\n    Attributes:\n        credentials: The credentials to use to authenticate; if there are\n            duplicate keys between credentials and TargetConfigs,\n            e.g. schema, an error will be raised.\n\n    Examples:\n        Load stored BigQueryTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import BigQueryTargetConfigs\n\n        bigquery_target_configs = BigQueryTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate BigQueryTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import BigQueryTargetConfigs\n        from prefect_gcp.credentials import GcpCredentials\n\n        credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n        target_configs = BigQueryTargetConfigs(\n            schema=\"schema\",  # also known as dataset\n            credentials=credentials,\n        )\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI BigQuery Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _description = \"dbt CLI target configs containing credentials and settings, specific to BigQuery.\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs\"  # noqa\n\n    type: Literal[\"bigquery\"] = Field(\n        default=\"bigquery\", description=\"The type of target.\"\n    )\n    project: Optional[str] = Field(default=None, description=\"The project to use.\")\n    credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=\"The credentials to use to authenticate.\",\n    )\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to BigQuery profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        # since GcpCredentials will always define a project\n        self_copy = self.copy()\n        if self_copy.project is not None:\n            self_copy.credentials.project = None\n        all_configs_json = self._populate_configs_json(\n            {}, self_copy.__fields__, model=self_copy\n        )\n\n        # decouple prefect-gcp from prefect-dbt\n        # by mapping all the keys dbt gcp accepts\n        # https://docs.getdbt.com/reference/warehouse-setups/bigquery-setup\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"dataset\": \"schema\",\n            \"method\": \"method\",\n            \"project\": \"project\",\n            # service-account\n            \"service_account_file\": \"keyfile\",\n            # service-account json\n            \"service_account_info\": \"keyfile_json\",\n            # oauth secrets\n            \"refresh_token\": \"refresh_token\",\n            \"client_id\": \"client_id\",\n            \"client_secret\": \"client_secret\",\n            \"token_uri\": \"token_uri\",\n            # optional\n            \"priority\": \"priority\",\n            \"timeout_seconds\": \"timeout_seconds\",\n            \"location\": \"location\",\n            \"maximum_bytes_billed\": \"maximum_bytes_billed\",\n            \"scopes\": \"scopes\",\n            \"impersonate_service_account\": \"impersonate_service_account\",\n            \"execution_project\": \"execution_project\",\n        }\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n\n        if \"keyfile_json\" in configs_json:\n            configs_json[\"method\"] = \"service-account-json\"\n        elif \"keyfile\" in configs_json:\n            configs_json[\"method\"] = \"service-account\"\n            configs_json[\"keyfile\"] = str(configs_json[\"keyfile\"])\n        else:\n            configs_json[\"method\"] = \"oauth-secrets\"\n            # through gcloud application-default login\n            google_credentials = (\n                self_copy.credentials.get_credentials_from_service_account()\n            )\n            if hasattr(google_credentials, \"token\"):\n                request = Request()\n                google_credentials.refresh(request)\n                configs_json[\"token\"] = google_credentials.token\n            else:\n                for key in (\"refresh_token\", \"client_id\", \"client_secret\", \"token_uri\"):\n                    configs_json[key] = getattr(google_credentials, key)\n\n        if \"project\" not in configs_json:\n            raise ValueError(\n                \"The keyword, project, must be provided in either \"\n                \"GcpCredentials or BigQueryTargetConfigs\"\n            )\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to BigQuery profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/bigquery.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to BigQuery profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    # since GcpCredentials will always define a project\n    self_copy = self.copy()\n    if self_copy.project is not None:\n        self_copy.credentials.project = None\n    all_configs_json = self._populate_configs_json(\n        {}, self_copy.__fields__, model=self_copy\n    )\n\n    # decouple prefect-gcp from prefect-dbt\n    # by mapping all the keys dbt gcp accepts\n    # https://docs.getdbt.com/reference/warehouse-setups/bigquery-setup\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"dataset\": \"schema\",\n        \"method\": \"method\",\n        \"project\": \"project\",\n        # service-account\n        \"service_account_file\": \"keyfile\",\n        # service-account json\n        \"service_account_info\": \"keyfile_json\",\n        # oauth secrets\n        \"refresh_token\": \"refresh_token\",\n        \"client_id\": \"client_id\",\n        \"client_secret\": \"client_secret\",\n        \"token_uri\": \"token_uri\",\n        # optional\n        \"priority\": \"priority\",\n        \"timeout_seconds\": \"timeout_seconds\",\n        \"location\": \"location\",\n        \"maximum_bytes_billed\": \"maximum_bytes_billed\",\n        \"scopes\": \"scopes\",\n        \"impersonate_service_account\": \"impersonate_service_account\",\n        \"execution_project\": \"execution_project\",\n    }\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n\n    if \"keyfile_json\" in configs_json:\n        configs_json[\"method\"] = \"service-account-json\"\n    elif \"keyfile\" in configs_json:\n        configs_json[\"method\"] = \"service-account\"\n        configs_json[\"keyfile\"] = str(configs_json[\"keyfile\"])\n    else:\n        configs_json[\"method\"] = \"oauth-secrets\"\n        # through gcloud application-default login\n        google_credentials = (\n            self_copy.credentials.get_credentials_from_service_account()\n        )\n        if hasattr(google_credentials, \"token\"):\n            request = Request()\n            google_credentials.refresh(request)\n            configs_json[\"token\"] = google_credentials.token\n        else:\n            for key in (\"refresh_token\", \"client_id\", \"client_secret\", \"token_uri\"):\n                configs_json[key] = getattr(google_credentials, key)\n\n    if \"project\" not in configs_json:\n        raise ValueError(\n            \"The keyword, project, must be provided in either \"\n            \"GcpCredentials or BigQueryTargetConfigs\"\n        )\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/","title":"Postgres","text":""},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres","title":"<code>prefect_dbt.cli.configs.postgres</code>","text":"<p>Module containing models for Postgres configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs","title":"<code>PostgresTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to Postgres. To find valid keys, head to the Postgres Profile page.</p> <p>Attributes:</p> Name Type Description <code>credentials</code> <code>Union[SqlAlchemyConnector, DatabaseCredentials]</code> <p>The credentials to use to authenticate; if there are duplicate keys between credentials and TargetConfigs, e.g. schema, an error will be raised.</p> <p>Examples:</p> <p>Load stored PostgresTargetConfigs: <pre><code>from prefect_dbt.cli.configs import PostgresTargetConfigs\n\npostgres_target_configs = PostgresTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate PostgresTargetConfigs with DatabaseCredentials. <pre><code>from prefect_dbt.cli.configs import PostgresTargetConfigs\nfrom prefect_sqlalchemy import DatabaseCredentials, SyncDriver\n\ncredentials = DatabaseCredentials(\n    driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n    username=\"prefect\",\n    password=\"prefect_password\",\n    database=\"postgres\",\n    host=\"host\",\n    port=8080\n)\ntarget_configs = PostgresTargetConfigs(credentials=credentials, schema=\"schema\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/postgres.py</code> <pre><code>class PostgresTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to Postgres.\n    To find valid keys, head to the [Postgres Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/postgres-profile)\n    page.\n\n    Attributes:\n        credentials: The credentials to use to authenticate; if there are\n            duplicate keys between credentials and TargetConfigs,\n            e.g. schema, an error will be raised.\n\n    Examples:\n        Load stored PostgresTargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import PostgresTargetConfigs\n\n        postgres_target_configs = PostgresTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate PostgresTargetConfigs with DatabaseCredentials.\n        ```python\n        from prefect_dbt.cli.configs import PostgresTargetConfigs\n        from prefect_sqlalchemy import DatabaseCredentials, SyncDriver\n\n        credentials = DatabaseCredentials(\n            driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n            username=\"prefect\",\n            password=\"prefect_password\",\n            database=\"postgres\",\n            host=\"host\",\n            port=8080\n        )\n        target_configs = PostgresTargetConfigs(credentials=credentials, schema=\"schema\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Postgres Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _description = \"dbt CLI target configs containing credentials and settings specific to Postgres.\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs\"  # noqa\n\n    type: Literal[\"postgres\"] = Field(\n        default=\"postgres\", description=\"The type of the target.\"\n    )\n    credentials: Union[SqlAlchemyConnector, DatabaseCredentials] = Field(\n        default=...,\n        description=(\n            \"The credentials to use to authenticate; if there are duplicate keys \"\n            \"between credentials and TargetConfigs, e.g. schema, \"\n            \"an error will be raised.\"\n        ),\n    )  # noqa\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to Postgres profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        if isinstance(self.credentials, DatabaseCredentials):\n            warnings.warn(\n                \"Using DatabaseCredentials is deprecated and will be removed \"\n                \"on May 7th, 2023, use SqlAlchemyConnector instead.\",\n                DeprecationWarning,\n            )\n        all_configs_json = super().get_configs()\n\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"host\": \"host\",\n            \"username\": \"user\",\n            \"password\": \"password\",\n            \"port\": \"port\",\n            \"database\": \"dbname\",\n            # optional\n            \"keepalives_idle\": \"keepalives_idle\",\n            \"connect_timeout\": \"connect_timeout\",\n            \"retries\": \"retries\",\n            \"search_path\": \"search_path\",\n            \"role\": \"role\",\n            \"sslmode\": \"sslmode\",\n        }\n\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys, like fetch_size + poll_frequency_s\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n        port = configs_json.get(\"port\")\n        if port is not None:\n            configs_json[\"port\"] = int(port)\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to Postgres profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/postgres.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to Postgres profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    if isinstance(self.credentials, DatabaseCredentials):\n        warnings.warn(\n            \"Using DatabaseCredentials is deprecated and will be removed \"\n            \"on May 7th, 2023, use SqlAlchemyConnector instead.\",\n            DeprecationWarning,\n        )\n    all_configs_json = super().get_configs()\n\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"host\": \"host\",\n        \"username\": \"user\",\n        \"password\": \"password\",\n        \"port\": \"port\",\n        \"database\": \"dbname\",\n        # optional\n        \"keepalives_idle\": \"keepalives_idle\",\n        \"connect_timeout\": \"connect_timeout\",\n        \"retries\": \"retries\",\n        \"search_path\": \"search_path\",\n        \"role\": \"role\",\n        \"sslmode\": \"sslmode\",\n    }\n\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys, like fetch_size + poll_frequency_s\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n    port = configs_json.get(\"port\")\n    if port is not None:\n        configs_json[\"port\"] = int(port)\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/","title":"Snowflake","text":""},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake","title":"<code>prefect_dbt.cli.configs.snowflake</code>","text":"<p>Module containing models for Snowflake configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs","title":"<code>SnowflakeTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to Snowflake. To find valid keys, head to the Snowflake Profile page.</p> <p>Attributes:</p> Name Type Description <code>connector</code> <code>SnowflakeConnector</code> <p>The connector to use.</p> <p>Examples:</p> <p>Load stored SnowflakeTargetConfigs: <pre><code>from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n\nsnowflake_target_configs = SnowflakeTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate SnowflakeTargetConfigs. <pre><code>from prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\ncredentials = SnowflakeCredentials(\n    user=\"user\",\n    password=\"password\",\n    account=\"account.region.aws\",\n    role=\"role\",\n)\nconnector = SnowflakeConnector(\n    schema=\"public\",\n    database=\"database\",\n    warehouse=\"warehouse\",\n    credentials=credentials,\n)\ntarget_configs = SnowflakeTargetConfigs(\n    connector=connector,\n    extras={\"retry_on_database_errors\": True},\n)\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/snowflake.py</code> <pre><code>class SnowflakeTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to Snowflake.\n    To find valid keys, head to the [Snowflake Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/snowflake-profile)\n    page.\n\n    Attributes:\n        connector: The connector to use.\n\n    Examples:\n        Load stored SnowflakeTargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n\n        snowflake_target_configs = SnowflakeTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate SnowflakeTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        credentials = SnowflakeCredentials(\n            user=\"user\",\n            password=\"password\",\n            account=\"account.region.aws\",\n            role=\"role\",\n        )\n        connector = SnowflakeConnector(\n            schema=\"public\",\n            database=\"database\",\n            warehouse=\"warehouse\",\n            credentials=credentials,\n        )\n        target_configs = SnowflakeTargetConfigs(\n            connector=connector,\n            extras={\"retry_on_database_errors\": True},\n        )\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Snowflake Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs\"  # noqa\n\n    type: Literal[\"snowflake\"] = Field(\n        default=\"snowflake\", description=\"The type of the target configs.\"\n    )\n    schema_: Optional[str] = Field(\n        default=None,\n        alias=\"schema\",\n        description=\"The schema to use for the target configs.\",\n    )\n    connector: SnowflakeConnector = Field(\n        default=..., description=\"The connector to use.\"\n    )\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to Snowflake profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        all_configs_json = super().get_configs()\n\n        # decouple prefect-snowflake from prefect-dbt\n        # by mapping all the keys dbt snowflake accepts\n        # https://docs.getdbt.com/reference/warehouse-setups/snowflake-setup\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"account\": \"account\",\n            \"user\": \"user\",\n            \"role\": \"role\",\n            \"database\": \"database\",\n            \"warehouse\": \"warehouse\",\n            # user and password\n            \"password\": \"password\",\n            # duo mfa / sso\n            \"authenticator\": \"authenticator\",\n            # key pair\n            \"private_key_path\": \"private_key_path\",\n            \"private_key_passphrase\": \"private_key_passphrase\",\n            # optional\n            \"client_session_keep_alive\": \"client_session_keep_alive\",\n            \"query_tag\": \"query_tag\",\n            \"connect_retries\": \"connect_retries\",\n            \"connect_timeout\": \"connect_timeout\",\n            \"retry_on_database_errors\": \"retry_on_database_errors\",\n            \"retry_all\": \"retry_all\",\n        }\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys, like fetch_size + poll_frequency_s\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to Snowflake profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/snowflake.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to Snowflake profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    all_configs_json = super().get_configs()\n\n    # decouple prefect-snowflake from prefect-dbt\n    # by mapping all the keys dbt snowflake accepts\n    # https://docs.getdbt.com/reference/warehouse-setups/snowflake-setup\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"account\": \"account\",\n        \"user\": \"user\",\n        \"role\": \"role\",\n        \"database\": \"database\",\n        \"warehouse\": \"warehouse\",\n        # user and password\n        \"password\": \"password\",\n        # duo mfa / sso\n        \"authenticator\": \"authenticator\",\n        # key pair\n        \"private_key_path\": \"private_key_path\",\n        \"private_key_passphrase\": \"private_key_passphrase\",\n        # optional\n        \"client_session_keep_alive\": \"client_session_keep_alive\",\n        \"query_tag\": \"query_tag\",\n        \"connect_retries\": \"connect_retries\",\n        \"connect_timeout\": \"connect_timeout\",\n        \"retry_on_database_errors\": \"retry_on_database_errors\",\n        \"retry_all\": \"retry_all\",\n    }\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys, like fetch_size + poll_frequency_s\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/","title":"Clients","text":""},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients","title":"<code>prefect_dbt.cloud.clients</code>","text":"<p>Module containing clients for interacting with the dbt Cloud API</p>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient","title":"<code>DbtCloudAdministrativeClient</code>","text":"<p>Client for interacting with the dbt cloud Administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>api_key</code> <code>str</code> <p>API key to authenticate with the dbt Cloud administrative API.</p> required <code>account_id</code> <code>int</code> <p>ID of dbt Cloud account with which to interact.</p> required <code>domain</code> <code>str</code> <p>Domain at which the dbt Cloud API is hosted.</p> <code>'cloud.getdbt.com'</code> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>class DbtCloudAdministrativeClient:\n    \"\"\"\n    Client for interacting with the dbt cloud Administrative API.\n\n    Args:\n        api_key: API key to authenticate with the dbt Cloud administrative API.\n        account_id: ID of dbt Cloud account with which to interact.\n        domain: Domain at which the dbt Cloud API is hosted.\n    \"\"\"\n\n    def __init__(self, api_key: str, account_id: int, domain: str = \"cloud.getdbt.com\"):\n        self._closed = False\n        self._started = False\n\n        self._admin_client = AsyncClient(\n            headers={\n                \"Authorization\": f\"Bearer {api_key}\",\n                \"user-agent\": f\"prefect-{prefect.__version__}\",\n                \"x-dbt-partner-source\": \"prefect\",\n            },\n            base_url=f\"https://{domain}/api/v2/accounts/{account_id}\",\n        )\n\n    async def call_endpoint(\n        self,\n        http_method: str,\n        path: str,\n        params: Optional[Dict[str, Any]] = None,\n        json: Optional[Dict[str, Any]] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Call an endpoint in the dbt Cloud API.\n\n        Args:\n            path: The partial path for the request (e.g. /projects/). Will be appended\n                onto the base URL as determined by the client configuration.\n            http_method: HTTP method to call on the endpoint.\n            params: Query parameters to include in the request.\n            json: JSON serializable body to send in the request.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"\n        response = await self._admin_client.request(\n            method=http_method, url=path, params=params, json=json\n        )\n\n        response.raise_for_status()\n\n        return response\n\n    async def get_job(\n        self,\n        job_id: int,\n        order_by: Optional[str] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Return job details for a job on an account.\n\n        Args:\n            job_id: Numeric ID of the job.\n            order_by: Field to order the result by. Use - to indicate reverse order.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"order_by\": order_by} if order_by else None\n        return await self.call_endpoint(\n            path=f\"/jobs/{job_id}/\", http_method=\"GET\", params=params\n        )\n\n    async def trigger_job_run(\n        self, job_id: int, options: Optional[TriggerJobRunOptions] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [trigger job run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun)\n        to initiate a job run.\n\n        Args:\n            job_id: The ID of the job to trigger.\n            options: An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        if options is None:\n            options = TriggerJobRunOptions()\n\n        return await self.call_endpoint(\n            path=f\"/jobs/{job_id}/run/\",\n            http_method=\"POST\",\n            json=options.dict(exclude_none=True),\n        )\n\n    async def get_run(\n        self,\n        run_id: int,\n        include_related: Optional[\n            List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n        ] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [get run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById)\n        to get details about a job run.\n\n        Args:\n            run_id: The ID of the run to get details for.\n            include_related: List of related fields to pull with the run.\n                Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n                If \"debug_logs\" is not provided in a request, then the included debug\n                logs will be truncated to the last 1,000 lines of the debug log output file.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"include_related\": include_related} if include_related else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/\", http_method=\"GET\", params=params\n        )\n\n    async def list_run_artifacts(\n        self, run_id: int, step: Optional[int] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [list run artifacts endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId)\n        to fetch a list of paths of artifacts generated for a completed run.\n\n        Args:\n            run_id: The ID of the run to list run artifacts for.\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"step\": step} if step else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/artifacts/\", http_method=\"GET\", params=params\n        )\n\n    async def get_run_artifact(\n        self, run_id: int, path: str, step: Optional[int] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [get run artifact endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId)\n        to fetch an artifact generated for a completed run.\n\n        Args:\n            run_id: The ID of the run to list run artifacts for.\n            path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n                run_results.json)\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"step\": step} if step else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/artifacts/{path}\", http_method=\"GET\", params=params\n        )\n\n    async def __aenter__(self):\n        if self._closed:\n            raise RuntimeError(\n                \"The client cannot be started again after it has been closed.\"\n            )\n        if self._started:\n            raise RuntimeError(\"The client cannot be started more than once.\")\n\n        self._started = True\n\n        return self\n\n    async def __aexit__(self, *exc):\n        self._closed = True\n        await self._admin_client.__aexit__()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.call_endpoint","title":"<code>call_endpoint</code>  <code>async</code>","text":"<p>Call an endpoint in the dbt Cloud API.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The partial path for the request (e.g. /projects/). Will be appended onto the base URL as determined by the client configuration.</p> required <code>http_method</code> <code>str</code> <p>HTTP method to call on the endpoint.</p> required <code>params</code> <code>Optional[Dict[str, Any]]</code> <p>Query parameters to include in the request.</p> <code>None</code> <code>json</code> <code>Optional[Dict[str, Any]]</code> <p>JSON serializable body to send in the request.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def call_endpoint(\n    self,\n    http_method: str,\n    path: str,\n    params: Optional[Dict[str, Any]] = None,\n    json: Optional[Dict[str, Any]] = None,\n) -&gt; Response:\n    \"\"\"\n    Call an endpoint in the dbt Cloud API.\n\n    Args:\n        path: The partial path for the request (e.g. /projects/). Will be appended\n            onto the base URL as determined by the client configuration.\n        http_method: HTTP method to call on the endpoint.\n        params: Query parameters to include in the request.\n        json: JSON serializable body to send in the request.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"\n    response = await self._admin_client.request(\n        method=http_method, url=path, params=params, json=json\n    )\n\n    response.raise_for_status()\n\n    return response\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_job","title":"<code>get_job</code>  <code>async</code>","text":"<p>Return job details for a job on an account.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>Numeric ID of the job.</p> required <code>order_by</code> <code>Optional[str]</code> <p>Field to order the result by. Use - to indicate reverse order.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_job(\n    self,\n    job_id: int,\n    order_by: Optional[str] = None,\n) -&gt; Response:\n    \"\"\"\n    Return job details for a job on an account.\n\n    Args:\n        job_id: Numeric ID of the job.\n        order_by: Field to order the result by. Use - to indicate reverse order.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"order_by\": order_by} if order_by else None\n    return await self.call_endpoint(\n        path=f\"/jobs/{job_id}/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run","title":"<code>get_run</code>  <code>async</code>","text":"<p>Sends a request to the get run endpoint to get details about a job run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to get details for.</p> required <code>include_related</code> <code>Optional[List[Literal['trigger', 'job', 'debug_logs', 'run_steps']]]</code> <p>List of related fields to pull with the run. Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\". If \"debug_logs\" is not provided in a request, then the included debug logs will be truncated to the last 1,000 lines of the debug log output file.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_run(\n    self,\n    run_id: int,\n    include_related: Optional[\n        List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n    ] = None,\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [get run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById)\n    to get details about a job run.\n\n    Args:\n        run_id: The ID of the run to get details for.\n        include_related: List of related fields to pull with the run.\n            Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n            If \"debug_logs\" is not provided in a request, then the included debug\n            logs will be truncated to the last 1,000 lines of the debug log output file.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"include_related\": include_related} if include_related else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run_artifact","title":"<code>get_run_artifact</code>  <code>async</code>","text":"<p>Sends a request to the get run artifact endpoint to fetch an artifact generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>path</code> <code>str</code> <p>The relative path to the run artifact (e.g. manifest.json, catalog.json, run_results.json)</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_run_artifact(\n    self, run_id: int, path: str, step: Optional[int] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [get run artifact endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId)\n    to fetch an artifact generated for a completed run.\n\n    Args:\n        run_id: The ID of the run to list run artifacts for.\n        path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n            run_results.json)\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"step\": step} if step else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/artifacts/{path}\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.list_run_artifacts","title":"<code>list_run_artifacts</code>  <code>async</code>","text":"<p>Sends a request to the list run artifacts endpoint to fetch a list of paths of artifacts generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def list_run_artifacts(\n    self, run_id: int, step: Optional[int] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [list run artifacts endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId)\n    to fetch a list of paths of artifacts generated for a completed run.\n\n    Args:\n        run_id: The ID of the run to list run artifacts for.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"step\": step} if step else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/artifacts/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.trigger_job_run","title":"<code>trigger_job_run</code>  <code>async</code>","text":"<p>Sends a request to the trigger job run endpoint to initiate a job run.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def trigger_job_run(\n    self, job_id: int, options: Optional[TriggerJobRunOptions] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [trigger job run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun)\n    to initiate a job run.\n\n    Args:\n        job_id: The ID of the job to trigger.\n        options: An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    if options is None:\n        options = TriggerJobRunOptions()\n\n    return await self.call_endpoint(\n        path=f\"/jobs/{job_id}/run/\",\n        http_method=\"POST\",\n        json=options.dict(exclude_none=True),\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudMetadataClient","title":"<code>DbtCloudMetadataClient</code>","text":"<p>Client for interacting with the dbt cloud Administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>api_key</code> <code>str</code> <p>API key to authenticate with the dbt Cloud administrative API.</p> required <code>domain</code> <code>str</code> <p>Domain at which the dbt Cloud API is hosted.</p> <code>'metadata.cloud.getdbt.com'</code> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>class DbtCloudMetadataClient:\n    \"\"\"\n    Client for interacting with the dbt cloud Administrative API.\n\n    Args:\n        api_key: API key to authenticate with the dbt Cloud administrative API.\n        domain: Domain at which the dbt Cloud API is hosted.\n    \"\"\"\n\n    def __init__(self, api_key: str, domain: str = \"metadata.cloud.getdbt.com\"):\n        self._http_endpoint = HTTPEndpoint(\n            base_headers={\n                \"Authorization\": f\"Bearer {api_key}\",\n                \"user-agent\": f\"prefect-{prefect.__version__}\",\n                \"x-dbt-partner-source\": \"prefect\",\n                \"content-type\": \"application/json\",\n            },\n            url=f\"https://{domain}/graphql\",\n        )\n\n    def query(\n        self,\n        query: str,\n        variables: Optional[Dict] = None,\n        operation_name: Optional[str] = None,\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Run a GraphQL query against the dbt Cloud metadata API.\n\n        Args:\n            query: The GraphQL query to run.\n            variables: The values of any variables defined in the GraphQL query.\n            operation_name: The name of the operation to run if multiple operations\n                are defined in the provided query.\n\n        Returns:\n            The result of the GraphQL query.\n        \"\"\"\n        return self._http_endpoint(\n            query=query, variables=variables, operation_name=operation_name\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudMetadataClient.query","title":"<code>query</code>","text":"<p>Run a GraphQL query against the dbt Cloud metadata API.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The GraphQL query to run.</p> required <code>variables</code> <code>Optional[Dict]</code> <p>The values of any variables defined in the GraphQL query.</p> <code>None</code> <code>operation_name</code> <code>Optional[str]</code> <p>The name of the operation to run if multiple operations are defined in the provided query.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The result of the GraphQL query.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>def query(\n    self,\n    query: str,\n    variables: Optional[Dict] = None,\n    operation_name: Optional[str] = None,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Run a GraphQL query against the dbt Cloud metadata API.\n\n    Args:\n        query: The GraphQL query to run.\n        variables: The values of any variables defined in the GraphQL query.\n        operation_name: The name of the operation to run if multiple operations\n            are defined in the provided query.\n\n    Returns:\n        The result of the GraphQL query.\n    \"\"\"\n    return self._http_endpoint(\n        query=query, variables=variables, operation_name=operation_name\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials","title":"<code>prefect_dbt.cloud.credentials</code>","text":"<p>Module containing credentials for interacting with dbt Cloud</p>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials","title":"<code>DbtCloudCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Credentials block for credential use across dbt Cloud tasks and flows.</p> <p>Attributes:</p> Name Type Description <code>api_key</code> <code>SecretStr</code> <p>API key to authenticate with the dbt Cloud administrative API. Refer to the Authentication docs for retrieving the API key.</p> <code>account_id</code> <code>int</code> <p>ID of dbt Cloud account with which to interact.</p> <code>domain</code> <code>Optional[str]</code> <p>Domain at which the dbt Cloud API is hosted.</p> <p>Examples:</p> <p>Load stored dbt Cloud credentials: <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\ndbt_cloud_credentials = DbtCloudCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Use DbtCloudCredentials instance to trigger a job run: <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\ncredentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\nasync with dbt_cloud_credentials.get_administrative_client() as client:\n    client.trigger_job_run(job_id=1)\n</code></pre></p> <p>Load saved dbt Cloud credentials within a flow: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials.load(\"my-dbt-credentials\")\n    trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\ntrigger_dbt_cloud_job_run_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>class DbtCloudCredentials(CredentialsBlock):\n    \"\"\"\n    Credentials block for credential use across dbt Cloud tasks and flows.\n\n    Attributes:\n        api_key (SecretStr): API key to authenticate with the dbt Cloud\n            administrative API. Refer to the [Authentication docs](\n            https://docs.getdbt.com/dbt-cloud/api-v2#section/Authentication)\n            for retrieving the API key.\n        account_id (int): ID of dbt Cloud account with which to interact.\n        domain (Optional[str]): Domain at which the dbt Cloud API is hosted.\n\n    Examples:\n        Load stored dbt Cloud credentials:\n        ```python\n        from prefect_dbt.cloud import DbtCloudCredentials\n\n        dbt_cloud_credentials = DbtCloudCredentials.load(\"BLOCK_NAME\")\n        ```\n\n        Use DbtCloudCredentials instance to trigger a job run:\n        ```python\n        from prefect_dbt.cloud import DbtCloudCredentials\n\n        credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            client.trigger_job_run(job_id=1)\n        ```\n\n        Load saved dbt Cloud credentials within a flow:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials.load(\"my-dbt-credentials\")\n            trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n        trigger_dbt_cloud_job_run_flow()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Cloud Credentials\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials\"  # noqa\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"A dbt Cloud API key to use for authentication.\",\n    )\n    account_id: int = Field(\n        default=..., title=\"Account ID\", description=\"The ID of your dbt Cloud account.\"\n    )\n    domain: str = Field(\n        default=\"cloud.getdbt.com\",\n        description=\"The base domain of your dbt Cloud instance.\",\n    )\n\n    def get_administrative_client(self) -&gt; DbtCloudAdministrativeClient:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud\n        administrative API.\n\n        Returns:\n            An authenticated dbt Cloud administrative API client.\n        \"\"\"\n        return DbtCloudAdministrativeClient(\n            api_key=self.api_key.get_secret_value(),\n            account_id=self.account_id,\n            domain=self.domain,\n        )\n\n    def get_metadata_client(self) -&gt; DbtCloudMetadataClient:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud\n        metadata API.\n\n        Example:\n            Sending queries via the returned metadata client:\n            ```python\n            from prefect_dbt import DbtCloudCredentials\n\n            credentials_block = DbtCloudCredentials.load(\"test-account\")\n            metadata_client = credentials_block.get_metadata_client()\n            query = \\\"\\\"\\\"\n            {\n                metrics(jobId: 123) {\n                    uniqueId\n                    name\n                    packageName\n                    tags\n                    label\n                    runId\n                    description\n                    type\n                    sql\n                    timestamp\n                    timeGrains\n                    dimensions\n                    meta\n                    resourceType\n                    filters {\n                        field\n                        operator\n                        value\n                    }\n                    model {\n                        name\n                    }\n                }\n            }\n            \\\"\\\"\\\"\n            metadata_client.query(query)\n            # Result:\n            # {\n            #   \"data\": {\n            #     \"metrics\": [\n            #       {\n            #         \"uniqueId\": \"metric.tpch.total_revenue\",\n            #         \"name\": \"total_revenue\",\n            #         \"packageName\": \"tpch\",\n            #         \"tags\": [],\n            #         \"label\": \"Total Revenue ($)\",\n            #         \"runId\": 108952046,\n            #         \"description\": \"\",\n            #         \"type\": \"sum\",\n            #         \"sql\": \"net_item_sales_amount\",\n            #         \"timestamp\": \"order_date\",\n            #         \"timeGrains\": [\"day\", \"week\", \"month\"],\n            #         \"dimensions\": [\"status_code\", \"priority_code\"],\n            #         \"meta\": {},\n            #         \"resourceType\": \"metric\",\n            #         \"filters\": [],\n            #         \"model\": { \"name\": \"fct_orders\" }\n            #       }\n            #     ]\n            #   }\n            # }\n            ```\n\n        Returns:\n            An authenticated dbt Cloud metadata API client.\n        \"\"\"\n        return DbtCloudMetadataClient(\n            api_key=self.api_key.get_secret_value(),\n            domain=f\"metadata.{self.domain}\",\n        )\n\n    def get_client(\n        self, client_type: Literal[\"administrative\", \"metadata\"]\n    ) -&gt; Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud API.\n\n        Args:\n            client_type: Type of client to return. Accepts either 'administrative'\n                or 'metadata'.\n\n        Returns:\n            The authenticated client of the requested type.\n        \"\"\"\n        get_client_method = getattr(self, f\"get_{client_type}_client\", None)\n        if get_client_method is None:\n            raise ValueError(f\"'{client_type}' is not a supported client type.\")\n        return get_client_method()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_administrative_client","title":"<code>get_administrative_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud administrative API.</p> <p>Returns:</p> Type Description <code>DbtCloudAdministrativeClient</code> <p>An authenticated dbt Cloud administrative API client.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_administrative_client(self) -&gt; DbtCloudAdministrativeClient:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud\n    administrative API.\n\n    Returns:\n        An authenticated dbt Cloud administrative API client.\n    \"\"\"\n    return DbtCloudAdministrativeClient(\n        api_key=self.api_key.get_secret_value(),\n        account_id=self.account_id,\n        domain=self.domain,\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud API.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['administrative', 'metadata']</code> <p>Type of client to return. Accepts either 'administrative' or 'metadata'.</p> required <p>Returns:</p> Type Description <code>Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]</code> <p>The authenticated client of the requested type.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_client(\n    self, client_type: Literal[\"administrative\", \"metadata\"]\n) -&gt; Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud API.\n\n    Args:\n        client_type: Type of client to return. Accepts either 'administrative'\n            or 'metadata'.\n\n    Returns:\n        The authenticated client of the requested type.\n    \"\"\"\n    get_client_method = getattr(self, f\"get_{client_type}_client\", None)\n    if get_client_method is None:\n        raise ValueError(f\"'{client_type}' is not a supported client type.\")\n    return get_client_method()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_metadata_client","title":"<code>get_metadata_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud metadata API.</p> Example <p>Sending queries via the returned metadata client: <pre><code>from prefect_dbt import DbtCloudCredentials\n\ncredentials_block = DbtCloudCredentials.load(\"test-account\")\nmetadata_client = credentials_block.get_metadata_client()\nquery = \"\"\"\n{\n    metrics(jobId: 123) {\n        uniqueId\n        name\n        packageName\n        tags\n        label\n        runId\n        description\n        type\n        sql\n        timestamp\n        timeGrains\n        dimensions\n        meta\n        resourceType\n        filters {\n            field\n            operator\n            value\n        }\n        model {\n            name\n        }\n    }\n}\n\"\"\"\nmetadata_client.query(query)\n# Result:\n# {\n#   \"data\": {\n#     \"metrics\": [\n#       {\n#         \"uniqueId\": \"metric.tpch.total_revenue\",\n#         \"name\": \"total_revenue\",\n#         \"packageName\": \"tpch\",\n#         \"tags\": [],\n#         \"label\": \"Total Revenue ($)\",\n#         \"runId\": 108952046,\n#         \"description\": \"\",\n#         \"type\": \"sum\",\n#         \"sql\": \"net_item_sales_amount\",\n#         \"timestamp\": \"order_date\",\n#         \"timeGrains\": [\"day\", \"week\", \"month\"],\n#         \"dimensions\": [\"status_code\", \"priority_code\"],\n#         \"meta\": {},\n#         \"resourceType\": \"metric\",\n#         \"filters\": [],\n#         \"model\": { \"name\": \"fct_orders\" }\n#       }\n#     ]\n#   }\n# }\n</code></pre></p> <p>Returns:</p> Type Description <code>DbtCloudMetadataClient</code> <p>An authenticated dbt Cloud metadata API client.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_metadata_client(self) -&gt; DbtCloudMetadataClient:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud\n    metadata API.\n\n    Example:\n        Sending queries via the returned metadata client:\n        ```python\n        from prefect_dbt import DbtCloudCredentials\n\n        credentials_block = DbtCloudCredentials.load(\"test-account\")\n        metadata_client = credentials_block.get_metadata_client()\n        query = \\\"\\\"\\\"\n        {\n            metrics(jobId: 123) {\n                uniqueId\n                name\n                packageName\n                tags\n                label\n                runId\n                description\n                type\n                sql\n                timestamp\n                timeGrains\n                dimensions\n                meta\n                resourceType\n                filters {\n                    field\n                    operator\n                    value\n                }\n                model {\n                    name\n                }\n            }\n        }\n        \\\"\\\"\\\"\n        metadata_client.query(query)\n        # Result:\n        # {\n        #   \"data\": {\n        #     \"metrics\": [\n        #       {\n        #         \"uniqueId\": \"metric.tpch.total_revenue\",\n        #         \"name\": \"total_revenue\",\n        #         \"packageName\": \"tpch\",\n        #         \"tags\": [],\n        #         \"label\": \"Total Revenue ($)\",\n        #         \"runId\": 108952046,\n        #         \"description\": \"\",\n        #         \"type\": \"sum\",\n        #         \"sql\": \"net_item_sales_amount\",\n        #         \"timestamp\": \"order_date\",\n        #         \"timeGrains\": [\"day\", \"week\", \"month\"],\n        #         \"dimensions\": [\"status_code\", \"priority_code\"],\n        #         \"meta\": {},\n        #         \"resourceType\": \"metric\",\n        #         \"filters\": [],\n        #         \"model\": { \"name\": \"fct_orders\" }\n        #       }\n        #     ]\n        #   }\n        # }\n        ```\n\n    Returns:\n        An authenticated dbt Cloud metadata API client.\n    \"\"\"\n    return DbtCloudMetadataClient(\n        api_key=self.api_key.get_secret_value(),\n        domain=f\"metadata.{self.domain}\",\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs","title":"<code>prefect_dbt.cloud.jobs</code>","text":"<p>Module containing tasks and flows for interacting with dbt Cloud jobs</p>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob","title":"<code>DbtCloudJob</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>Block that holds the information and methods to interact with a dbt Cloud job.</p> <p>Attributes:</p> Name Type Description <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>The credentials to use to authenticate with dbt Cloud.</p> <code>job_id</code> <code>int</code> <p>The id of the dbt Cloud job.</p> <code>timeout_seconds</code> <code>int</code> <p>The number of seconds to wait for the job to complete.</p> <code>interval_seconds</code> <code>int</code> <p>The number of seconds to wait between polling for job completion.</p> <code>trigger_job_run_options</code> <code>TriggerJobRunOptions</code> <p>The options to use when triggering a job run.</p> <p>Examples:</p> <p>Load a configured dbt Cloud job block. <pre><code>from prefect_dbt.cloud import DbtCloudJob\n\ndbt_cloud_job = DbtCloudJob.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Triggers a dbt Cloud job, waits for completion, and fetches the results. <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\n@flow\ndef dbt_cloud_job_flow():\n    dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n    dbt_cloud_job = DbtCloudJob.load(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=154217\n    )\n    dbt_cloud_job_run = dbt_cloud_job.trigger()\n    dbt_cloud_job_run.wait_for_completion()\n    dbt_cloud_job_run.fetch_result()\n    return dbt_cloud_job_run\n\ndbt_cloud_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>class DbtCloudJob(JobBlock):\n    \"\"\"\n    Block that holds the information and methods to interact with a dbt Cloud job.\n\n    Attributes:\n        dbt_cloud_credentials: The credentials to use to authenticate with dbt Cloud.\n        job_id: The id of the dbt Cloud job.\n        timeout_seconds: The number of seconds to wait for the job to complete.\n        interval_seconds:\n            The number of seconds to wait between polling for job completion.\n        trigger_job_run_options: The options to use when triggering a job run.\n\n    Examples:\n        Load a configured dbt Cloud job block.\n        ```python\n        from prefect_dbt.cloud import DbtCloudJob\n\n        dbt_cloud_job = DbtCloudJob.load(\"BLOCK_NAME\")\n        ```\n\n        Triggers a dbt Cloud job, waits for completion, and fetches the results.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\n        @flow\n        def dbt_cloud_job_flow():\n            dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n            dbt_cloud_job = DbtCloudJob.load(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                job_id=154217\n            )\n            dbt_cloud_job_run = dbt_cloud_job.trigger()\n            dbt_cloud_job_run.wait_for_completion()\n            dbt_cloud_job_run.fetch_result()\n            return dbt_cloud_job_run\n\n        dbt_cloud_job_flow()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Cloud Job\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob\"  # noqa\n\n    dbt_cloud_credentials: DbtCloudCredentials = Field(\n        default=...,\n        description=\"The dbt Cloud credentials to use to authenticate with dbt Cloud.\",\n    )  # noqa: E501\n    job_id: int = Field(\n        default=..., description=\"The id of the dbt Cloud job.\", title=\"Job ID\"\n    )\n    timeout_seconds: int = Field(\n        default=900,\n        description=\"The number of seconds to wait for the job to complete.\",\n    )\n    interval_seconds: int = Field(\n        default=10,\n        description=\"The number of seconds to wait between polling for job completion.\",\n    )\n    trigger_job_run_options: TriggerJobRunOptions = Field(\n        default_factory=TriggerJobRunOptions,\n        description=\"The options to use when triggering a job run.\",\n    )\n\n    @sync_compatible\n    async def get_job(self, order_by: Optional[str] = None) -&gt; Dict[str, Any]:\n        \"\"\"\n        Retrieve information about a dbt Cloud job.\n\n        Args:\n            order_by: The field to order the results by.\n\n        Returns:\n            The job data.\n        \"\"\"\n        try:\n            async with self.dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_job(\n                    job_id=self.job_id,\n                    order_by=order_by,\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n        return response.json()[\"data\"]\n\n    @sync_compatible\n    async def trigger(\n        self, trigger_job_run_options: Optional[TriggerJobRunOptions] = None\n    ) -&gt; DbtCloudJobRun:\n        \"\"\"\n        Triggers a dbt Cloud job.\n\n        Returns:\n            A representation of the dbt Cloud job run.\n        \"\"\"\n        try:\n            trigger_job_run_options = (\n                trigger_job_run_options or self.trigger_job_run_options\n            )\n            async with self.dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.trigger_job_run(\n                    job_id=self.job_id, options=trigger_job_run_options\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n        run_data = response.json()[\"data\"]\n        run_id = run_data.get(\"id\")\n        run = DbtCloudJobRun(\n            dbt_cloud_job=self,\n            run_id=run_id,\n        )\n        self.logger.info(\n            f\"dbt Cloud job {self.job_id} run {run_id} successfully triggered. \"\n            f\"You can view the status of this run at \"\n            f\"https://{self.dbt_cloud_credentials.domain}/#/accounts/\"\n            f\"{self.dbt_cloud_credentials.account_id}/projects/\"\n            f\"{run_data['project_id']}/runs/{run_id}/\"\n        )\n        return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob.get_job","title":"<code>get_job</code>  <code>async</code>","text":"<p>Retrieve information about a dbt Cloud job.</p> <p>Parameters:</p> Name Type Description Default <code>order_by</code> <code>Optional[str]</code> <p>The field to order the results by.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The job data.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_job(self, order_by: Optional[str] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Retrieve information about a dbt Cloud job.\n\n    Args:\n        order_by: The field to order the results by.\n\n    Returns:\n        The job data.\n    \"\"\"\n    try:\n        async with self.dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_job(\n                job_id=self.job_id,\n                order_by=order_by,\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Triggers a dbt Cloud job.</p> <p>Returns:</p> Type Description <code>DbtCloudJobRun</code> <p>A representation of the dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def trigger(\n    self, trigger_job_run_options: Optional[TriggerJobRunOptions] = None\n) -&gt; DbtCloudJobRun:\n    \"\"\"\n    Triggers a dbt Cloud job.\n\n    Returns:\n        A representation of the dbt Cloud job run.\n    \"\"\"\n    try:\n        trigger_job_run_options = (\n            trigger_job_run_options or self.trigger_job_run_options\n        )\n        async with self.dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.trigger_job_run(\n                job_id=self.job_id, options=trigger_job_run_options\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n    run_data = response.json()[\"data\"]\n    run_id = run_data.get(\"id\")\n    run = DbtCloudJobRun(\n        dbt_cloud_job=self,\n        run_id=run_id,\n    )\n    self.logger.info(\n        f\"dbt Cloud job {self.job_id} run {run_id} successfully triggered. \"\n        f\"You can view the status of this run at \"\n        f\"https://{self.dbt_cloud_credentials.domain}/#/accounts/\"\n        f\"{self.dbt_cloud_credentials.account_id}/projects/\"\n        f\"{run_data['project_id']}/runs/{run_id}/\"\n    )\n    return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun","title":"<code>DbtCloudJobRun</code>","text":"<p>               Bases: <code>JobRun</code></p> <p>Class that holds the information and methods to interact with the resulting run of a dbt Cloud job.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>class DbtCloudJobRun(JobRun):  # NOT A BLOCK\n    \"\"\"\n    Class that holds the information and methods to interact\n    with the resulting run of a dbt Cloud job.\n    \"\"\"\n\n    def __init__(self, run_id: int, dbt_cloud_job: \"DbtCloudJob\"):\n        self.run_id = run_id\n        self._dbt_cloud_job = dbt_cloud_job\n        self._dbt_cloud_credentials = dbt_cloud_job.dbt_cloud_credentials\n\n    @property\n    def _log_prefix(self):\n        return f\"dbt Cloud job {self._dbt_cloud_job.job_id} run {self.run_id}.\"\n\n    async def _wait_until_state(\n        self,\n        in_final_state_fn: Awaitable[Callable],\n        get_state_fn: Awaitable[Callable],\n        log_state_fn: Callable = None,\n        timeout_seconds: int = 60,\n        interval_seconds: int = 1,\n    ):\n        \"\"\"\n        Wait until the job run reaches a specific state.\n\n        Args:\n            in_final_state_fn: An async function that accepts a run state\n                and returns a boolean indicating whether the job run is\n                in a final state.\n            get_state_fn: An async function that returns\n                the current state of the job run.\n            log_state_fn: A callable that accepts a run\n                state and makes it human readable.\n            timeout_seconds: The maximum amount of time, in seconds, to wait\n                for the job run to reach the final state.\n            interval_seconds: The number of seconds to wait between checks of\n                the job run's state.\n        \"\"\"\n        start_time = time.time()\n        last_state = run_state = None\n        while not in_final_state_fn(run_state):\n            run_state = await get_state_fn()\n            if run_state != last_state:\n                if self.logger is not None:\n                    self.logger.info(\n                        \"%s has new state: %s\",\n                        self._log_prefix,\n                        log_state_fn(run_state),\n                    )\n                last_state = run_state\n\n            elapsed_time_seconds = time.time() - start_time\n            if elapsed_time_seconds &gt; timeout_seconds:\n                raise DbtCloudJobRunTimedOut(\n                    f\"Max wait time of {timeout_seconds} \"\n                    \"seconds exceeded while waiting\"\n                )\n            await asyncio.sleep(interval_seconds)\n\n    @sync_compatible\n    async def get_run(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Makes a request to the dbt Cloud API to get the run data.\n\n        Returns:\n            The run data.\n        \"\"\"\n        try:\n            dbt_cloud_credentials = self._dbt_cloud_credentials\n            async with dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_run(self.run_id)\n        except HTTPStatusError as ex:\n            raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n        run_data = response.json()[\"data\"]\n        return run_data\n\n    @sync_compatible\n    async def get_status_code(self) -&gt; int:\n        \"\"\"\n        Makes a request to the dbt Cloud API to get the run status.\n\n        Returns:\n            The run status code.\n        \"\"\"\n        run_data = await self.get_run()\n        run_status_code = run_data.get(\"status\")\n        return run_status_code\n\n    @sync_compatible\n    async def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Waits for the job run to reach a terminal state.\n        \"\"\"\n        await self._wait_until_state(\n            in_final_state_fn=DbtCloudJobRunStatus.is_terminal_status_code,\n            get_state_fn=self.get_status_code,\n            log_state_fn=DbtCloudJobRunStatus,\n            timeout_seconds=self._dbt_cloud_job.timeout_seconds,\n            interval_seconds=self._dbt_cloud_job.interval_seconds,\n        )\n\n    @sync_compatible\n    async def fetch_result(self, step: Optional[int] = None) -&gt; Dict[str, Any]:\n        \"\"\"\n        Gets the results from the job run. Since the results\n        may not be ready, use wait_for_completion before calling this method.\n\n        Args:\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n        \"\"\"\n        run_data = await self.get_run()\n        run_status = DbtCloudJobRunStatus(run_data.get(\"status\"))\n        if run_status == DbtCloudJobRunStatus.SUCCESS:\n            try:\n                async with self._dbt_cloud_credentials.get_administrative_client() as client:  # noqa\n                    response = await client.list_run_artifacts(\n                        run_id=self.run_id, step=step\n                    )\n                run_data[\"artifact_paths\"] = response.json()[\"data\"]\n                self.logger.info(\"%s completed successfully!\", self._log_prefix)\n            except HTTPStatusError as ex:\n                raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n            return run_data\n        elif run_status == DbtCloudJobRunStatus.CANCELLED:\n            raise DbtCloudJobRunCancelled(f\"{self._log_prefix} was cancelled.\")\n        elif run_status == DbtCloudJobRunStatus.FAILED:\n            raise DbtCloudJobRunFailed(f\"{self._log_prefix} has failed.\")\n        else:\n            raise DbtCloudJobRunIncomplete(\n                f\"{self._log_prefix} is still running; \"\n                \"use wait_for_completion() to wait until results are ready.\"\n            )\n\n    @sync_compatible\n    async def get_run_artifacts(\n        self,\n        path: Literal[\"manifest.json\", \"catalog.json\", \"run_results.json\"],\n        step: Optional[int] = None,\n    ) -&gt; Union[Dict[str, Any], str]:\n        \"\"\"\n        Get an artifact generated for a completed run.\n\n        Args:\n            path: The relative path to the run artifact.\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The contents of the requested manifest. Returns a `Dict` if the\n                requested artifact is a JSON file and a `str` otherwise.\n        \"\"\"\n        try:\n            dbt_cloud_credentials = self._dbt_cloud_credentials\n            async with dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_run_artifact(\n                    run_id=self.run_id, path=path, step=step\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n        if path.endswith(\".json\"):\n            artifact_contents = response.json()\n        else:\n            artifact_contents = response.text\n        return artifact_contents\n\n    def _select_unsuccessful_commands(\n        self,\n        run_results: List[Dict[str, Any]],\n        command_components: List[str],\n        command: str,\n        exe_command: str,\n    ) -&gt; List[str]:\n        \"\"\"\n        Select nodes that were not successful and rebuild a command.\n        \"\"\"\n        # note \"fail\" here instead of \"cancelled\" because\n        # nodes do not have a cancelled state\n        run_nodes = \" \".join(\n            run_result[\"unique_id\"].split(\".\")[2]\n            for run_result in run_results\n            if run_result[\"status\"] in (\"error\", \"skipped\", \"fail\")\n        )\n\n        select_arg = None\n        if \"-s\" in command_components:\n            select_arg = \"-s\"\n        elif \"--select\" in command_components:\n            select_arg = \"--select\"\n\n        # prevent duplicate --select/-s statements\n        if select_arg is not None:\n            # dbt --fail-fast run, -s, bad_mod --vars '{\"env\": \"prod\"}' to:\n            # dbt --fail-fast run -s other_mod bad_mod --vars '{\"env\": \"prod\"}'\n            command_start, select_arg, command_end = command.partition(select_arg)\n            modified_command = f\"{command_start} {select_arg} {run_nodes} {command_end}\"  # noqa\n        else:\n            # dbt --fail-fast, build, --vars '{\"env\": \"prod\"}' to:\n            # dbt --fail-fast build --select bad_model --vars '{\"env\": \"prod\"}'\n            dbt_global_args, exe_command, exe_args = command.partition(exe_command)\n            modified_command = (\n                f\"{dbt_global_args} {exe_command} -s {run_nodes} {exe_args}\"\n            )\n        return modified_command\n\n    async def _build_trigger_job_run_options(\n        self,\n        job: Dict[str, Any],\n        run: Dict[str, Any],\n    ) -&gt; TriggerJobRunOptions:\n        \"\"\"\n        Compiles a list of steps (commands) to retry, then either build trigger job\n        run options from scratch if it does not exist, else overrides the existing.\n        \"\"\"\n        generate_docs = job.get(\"generate_docs\", False)\n        generate_sources = job.get(\"generate_sources\", False)\n\n        steps_override = []\n        for run_step in run[\"run_steps\"]:\n            status = run_step[\"status_humanized\"].lower()\n            # Skipping cloning, profile setup, and dbt deps - always the first three\n            # steps in any run, and note, index starts at 1 instead of 0\n            if run_step[\"index\"] &lt;= 3 or status == \"success\":\n                continue\n            # get dbt build from \"Invoke dbt with `dbt build`\"\n            command = run_step[\"name\"].partition(\"`\")[2].partition(\"`\")[0]\n\n            # These steps will be re-run regardless if\n            # generate_docs or generate_sources are enabled for a given job\n            # so if we don't skip, it'll run twice\n            freshness_in_command = (\n                \"dbt source snapshot-freshness\" in command\n                or \"dbt source freshness\" in command\n            )\n            if \"dbt docs generate\" in command and generate_docs:\n                continue\n            elif freshness_in_command and generate_sources:\n                continue\n\n            # find an executable command like `build` or `run`\n            # search in a list so that there aren't false positives, like\n            # `\"run\" in \"dbt run-operation\"`, which is True; we actually want\n            # `\"run\" in [\"dbt\", \"run-operation\"]` which is False\n            command_components = shlex.split(command)\n            for exe_command in EXE_COMMANDS:\n                if exe_command in command_components:\n                    break\n            else:\n                exe_command = \"\"\n\n            is_exe_command = exe_command in EXE_COMMANDS\n            is_not_success = status in (\"error\", \"skipped\", \"cancelled\")\n            is_skipped = status == \"skipped\"\n            if (not is_exe_command and is_not_success) or (\n                is_exe_command and is_skipped\n            ):\n                # if no matches like `run-operation`, we will be rerunning entirely\n                # or if it's one of the expected commands and is skipped\n                steps_override.append(command)\n            else:\n                # errors and failures are when we need to inspect to figure\n                # out the point of failure\n                try:\n                    run_artifact = await self.get_run_artifacts(\n                        \"run_results.json\", run_step[\"index\"]\n                    )\n                except JSONDecodeError:\n                    # get the run results scoped to the step which had an error\n                    # an error here indicates that either:\n                    # 1) the fail-fast flag was set, in which case\n                    #    the run_results.json file was never created; or\n                    # 2) there was a problem on dbt Cloud's side saving\n                    #    this artifact\n                    steps_override.append(command)\n                else:\n                    # we only need to find the individual nodes\n                    # for those run commands\n                    run_results = run_artifact[\"results\"]\n                    modified_command = self._select_unsuccessful_commands(\n                        run_results=run_results,\n                        command_components=command_components,\n                        command=command,\n                        exe_command=exe_command,\n                    )\n                    steps_override.append(modified_command)\n\n        if self._dbt_cloud_job.trigger_job_run_options is None:\n            trigger_job_run_options_override = TriggerJobRunOptions(\n                steps_override=steps_override\n            )\n        else:\n            trigger_job_run_options_override = (\n                self._dbt_cloud_job.trigger_job_run_options.copy()\n            )\n            trigger_job_run_options_override.steps_override = steps_override\n        return trigger_job_run_options_override\n\n    @sync_compatible\n    async def retry_failed_steps(self) -&gt; \"DbtCloudJobRun\":  # noqa: F821\n        \"\"\"\n        Retries steps that did not complete successfully in a run.\n\n        Returns:\n            A representation of the dbt Cloud job run.\n        \"\"\"\n        job = await self._dbt_cloud_job.get_job()\n        run = await self.get_run()\n\n        trigger_job_run_options_override = await self._build_trigger_job_run_options(\n            job=job, run=run\n        )\n\n        num_steps = len(trigger_job_run_options_override.steps_override)\n        if num_steps == 0:\n            self.logger.info(f\"{self._log_prefix} does not have any steps to retry.\")\n        else:\n            self.logger.info(f\"{self._log_prefix} has {num_steps} steps to retry.\")\n            run = await self._dbt_cloud_job.trigger(\n                trigger_job_run_options=trigger_job_run_options_override,\n            )\n        return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Gets the results from the job run. Since the results may not be ready, use wait_for_completion before calling this method.</p> <p>Parameters:</p> Name Type Description Default <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self, step: Optional[int] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Gets the results from the job run. Since the results\n    may not be ready, use wait_for_completion before calling this method.\n\n    Args:\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n    \"\"\"\n    run_data = await self.get_run()\n    run_status = DbtCloudJobRunStatus(run_data.get(\"status\"))\n    if run_status == DbtCloudJobRunStatus.SUCCESS:\n        try:\n            async with self._dbt_cloud_credentials.get_administrative_client() as client:  # noqa\n                response = await client.list_run_artifacts(\n                    run_id=self.run_id, step=step\n                )\n            run_data[\"artifact_paths\"] = response.json()[\"data\"]\n            self.logger.info(\"%s completed successfully!\", self._log_prefix)\n        except HTTPStatusError as ex:\n            raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n        return run_data\n    elif run_status == DbtCloudJobRunStatus.CANCELLED:\n        raise DbtCloudJobRunCancelled(f\"{self._log_prefix} was cancelled.\")\n    elif run_status == DbtCloudJobRunStatus.FAILED:\n        raise DbtCloudJobRunFailed(f\"{self._log_prefix} has failed.\")\n    else:\n        raise DbtCloudJobRunIncomplete(\n            f\"{self._log_prefix} is still running; \"\n            \"use wait_for_completion() to wait until results are ready.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run","title":"<code>get_run</code>  <code>async</code>","text":"<p>Makes a request to the dbt Cloud API to get the run data.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The run data.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_run(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Makes a request to the dbt Cloud API to get the run data.\n\n    Returns:\n        The run data.\n    \"\"\"\n    try:\n        dbt_cloud_credentials = self._dbt_cloud_credentials\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run(self.run_id)\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n    run_data = response.json()[\"data\"]\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run_artifacts","title":"<code>get_run_artifacts</code>  <code>async</code>","text":"<p>Get an artifact generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Literal['manifest.json', 'catalog.json', 'run_results.json']</code> <p>The relative path to the run artifact.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[Dict[str, Any], str]</code> <p>The contents of the requested manifest. Returns a <code>Dict</code> if the requested artifact is a JSON file and a <code>str</code> otherwise.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_run_artifacts(\n    self,\n    path: Literal[\"manifest.json\", \"catalog.json\", \"run_results.json\"],\n    step: Optional[int] = None,\n) -&gt; Union[Dict[str, Any], str]:\n    \"\"\"\n    Get an artifact generated for a completed run.\n\n    Args:\n        path: The relative path to the run artifact.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The contents of the requested manifest. Returns a `Dict` if the\n            requested artifact is a JSON file and a `str` otherwise.\n    \"\"\"\n    try:\n        dbt_cloud_credentials = self._dbt_cloud_credentials\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run_artifact(\n                run_id=self.run_id, path=path, step=step\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n    if path.endswith(\".json\"):\n        artifact_contents = response.json()\n    else:\n        artifact_contents = response.text\n    return artifact_contents\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_status_code","title":"<code>get_status_code</code>  <code>async</code>","text":"<p>Makes a request to the dbt Cloud API to get the run status.</p> <p>Returns:</p> Type Description <code>int</code> <p>The run status code.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_status_code(self) -&gt; int:\n    \"\"\"\n    Makes a request to the dbt Cloud API to get the run status.\n\n    Returns:\n        The run status code.\n    \"\"\"\n    run_data = await self.get_run()\n    run_status_code = run_data.get(\"status\")\n    return run_status_code\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.retry_failed_steps","title":"<code>retry_failed_steps</code>  <code>async</code>","text":"<p>Retries steps that did not complete successfully in a run.</p> <p>Returns:</p> Type Description <code>DbtCloudJobRun</code> <p>A representation of the dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def retry_failed_steps(self) -&gt; \"DbtCloudJobRun\":  # noqa: F821\n    \"\"\"\n    Retries steps that did not complete successfully in a run.\n\n    Returns:\n        A representation of the dbt Cloud job run.\n    \"\"\"\n    job = await self._dbt_cloud_job.get_job()\n    run = await self.get_run()\n\n    trigger_job_run_options_override = await self._build_trigger_job_run_options(\n        job=job, run=run\n    )\n\n    num_steps = len(trigger_job_run_options_override.steps_override)\n    if num_steps == 0:\n        self.logger.info(f\"{self._log_prefix} does not have any steps to retry.\")\n    else:\n        self.logger.info(f\"{self._log_prefix} has {num_steps} steps to retry.\")\n        run = await self._dbt_cloud_job.trigger(\n            trigger_job_run_options=trigger_job_run_options_override,\n        )\n    return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Waits for the job run to reach a terminal state.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Waits for the job run to reach a terminal state.\n    \"\"\"\n    await self._wait_until_state(\n        in_final_state_fn=DbtCloudJobRunStatus.is_terminal_status_code,\n        get_state_fn=self.get_status_code,\n        log_state_fn=DbtCloudJobRunStatus,\n        timeout_seconds=self._dbt_cloud_job.timeout_seconds,\n        interval_seconds=self._dbt_cloud_job.interval_seconds,\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.get_dbt_cloud_job_info","title":"<code>get_dbt_cloud_job_info</code>  <code>async</code>","text":"<p>A task to retrieve information about a dbt Cloud job.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to get.</p> required <p>Returns:</p> Type Description <code>Dict</code> <p>The job data returned by the dbt Cloud administrative API.</p> Example <p>Get status of a dbt Cloud job: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_job\n\n@flow\ndef get_job_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_job(\n        dbt_cloud_credentials=credentials,\n        job_id=42\n    )\n\nget_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job details\",\n    description=\"Retrieves details of a dbt Cloud job \"\n    \"for the job with the given job_id.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_job_info(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    order_by: Optional[str] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to retrieve information about a dbt Cloud job.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to get.\n\n    Returns:\n        The job data returned by the dbt Cloud administrative API.\n\n    Example:\n        Get status of a dbt Cloud job:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_job\n\n        @flow\n        def get_job_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_job(\n                dbt_cloud_credentials=credentials,\n                job_id=42\n            )\n\n        get_job_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_job(\n                job_id=job_id,\n                order_by=order_by,\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.get_run_id","title":"<code>get_run_id</code>","text":"<p>Task that extracts the run ID from a trigger job run API response,</p> <p>This task is mainly used to maintain dependency tracking between the <code>trigger_dbt_cloud_job_run</code> task and downstream tasks/flows that use the run ID.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Dict</code> <p>The JSON body from the trigger job run response.</p> required Example <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run, get_run_id\n\n\n@flow\ndef trigger_run_and_get_id():\n    dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        )\n\n    triggered_run_data = trigger_dbt_cloud_job_run(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        options=trigger_job_run_options,\n    )\n    run_id = get_run_id.submit(triggered_run_data)\n    return run_id\n\ntrigger_run_and_get_id()\n</code></pre> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job run ID\",\n    description=\"Extracts the run ID from a trigger job run API response\",\n)\ndef get_run_id(obj: Dict):\n    \"\"\"\n    Task that extracts the run ID from a trigger job run API response,\n\n    This task is mainly used to maintain dependency tracking between the\n    `trigger_dbt_cloud_job_run` task and downstream tasks/flows that use the run ID.\n\n    Args:\n        obj: The JSON body from the trigger job run response.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run, get_run_id\n\n\n        @flow\n        def trigger_run_and_get_id():\n            dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                )\n\n            triggered_run_data = trigger_dbt_cloud_job_run(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                job_id=job_id,\n                options=trigger_job_run_options,\n            )\n            run_id = get_run_id.submit(triggered_run_data)\n            return run_id\n\n        trigger_run_and_get_id()\n        ```\n    \"\"\"\n    id = obj.get(\"id\")\n    if id is None:\n        raise RuntimeError(\"Unable to determine run ID for triggered job.\")\n    return id\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.retry_dbt_cloud_job_run_subset_and_wait_for_completion","title":"<code>retry_dbt_cloud_job_run_subset_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that retrys a subset of dbt Cloud job run, filtered by select statuses, and waits for the triggered retry to complete.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>trigger_job_run_options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>run_id</code> <code>int</code> <p>The ID of the job run to retry.</p> required <p>Raises:</p> Type Description <code>ValueError</code> <p>If <code>trigger_job_run_options.steps_override</code> is set by the user.</p> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Retry a subset of models in a dbt Cloud job run and wait for completion: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import retry_dbt_cloud_job_run_subset_and_wait_for_completion\n\n@flow\ndef retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow():\n    credentials = DbtCloudCredentials.load(\"MY_BLOCK_NAME\")\n    retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n        dbt_cloud_credentials=credentials,\n        run_id=88640123,\n    )\n\nretry_dbt_cloud_job_run_subset_and_wait_for_completion_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow(\n    name=\"Retry subset of dbt Cloud job run and wait for completion\",\n    description=(\n        \"Retries a subset of dbt Cloud job run, filtered by select statuses, \"\n        \"and waits for the triggered retry to complete.\"\n    ),\n)\nasync def retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    trigger_job_run_options: Optional[TriggerJobRunOptions] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n) -&gt; Dict:\n    \"\"\"\n    Flow that retrys a subset of dbt Cloud job run, filtered by select statuses,\n    and waits for the triggered retry to complete.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        trigger_job_run_options: An optional TriggerJobRunOptions instance to\n            specify overrides for the triggered job run.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        run_id: The ID of the job run to retry.\n\n    Raises:\n        ValueError: If `trigger_job_run_options.steps_override` is set by the user.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Examples:\n        Retry a subset of models in a dbt Cloud job run and wait for completion:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import retry_dbt_cloud_job_run_subset_and_wait_for_completion\n\n        @flow\n        def retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow():\n            credentials = DbtCloudCredentials.load(\"MY_BLOCK_NAME\")\n            retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n                dbt_cloud_credentials=credentials,\n                run_id=88640123,\n            )\n\n        retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow()\n        ```\n    \"\"\"  # noqa\n    if trigger_job_run_options and trigger_job_run_options.steps_override is not None:\n        raise ValueError(\n            \"Do not set `steps_override` in `trigger_job_run_options` \"\n            \"because this flow will automatically set it\"\n        )\n\n    run_info_future = await get_dbt_cloud_run_info.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        run_id=run_id,\n        include_related=[\"run_steps\"],\n    )\n    run_info = await run_info_future.result()\n\n    job_id = run_info[\"job_id\"]\n    job_info_future = await get_dbt_cloud_job_info.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n    )\n    job_info = await job_info_future.result()\n\n    trigger_job_run_options_override = await _build_trigger_job_run_options(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        trigger_job_run_options=trigger_job_run_options,\n        run_id=run_id,\n        run_info=run_info,\n        job_info=job_info,\n    )\n\n    # to circumvent `RuntimeError: The task runner is already started!`\n    flow_run_context = FlowRunContext.get()\n    task_runner_type = type(flow_run_context.task_runner)\n\n    run_data = await trigger_dbt_cloud_job_run_and_wait_for_completion.with_options(\n        task_runner=task_runner_type()\n    )(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        retry_filtered_models_attempts=0,\n        trigger_job_run_options=trigger_job_run_options_override,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.run_dbt_cloud_job","title":"<code>run_dbt_cloud_job</code>  <code>async</code>","text":"<p>Flow that triggers and waits for a dbt Cloud job run, retrying a subset of failed nodes if necessary.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_job</code> <code>DbtCloudJob</code> <p>Block that holds the information and methods to interact with a dbt Cloud job.</p> required <code>targeted_retries</code> <code>int</code> <p>The number of times to retry failed steps.</p> <code>3</code> <p>Examples:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\nfrom prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n@flow\ndef run_dbt_cloud_job_flow():\n    dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n    dbt_cloud_job = DbtCloudJob(\n        dbt_cloud_credentials=dbt_cloud_credentials, job_id=154217\n    )\n    return run_dbt_cloud_job(dbt_cloud_job=dbt_cloud_job)\n\nrun_dbt_cloud_job_flow()\n</code></pre> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow\nasync def run_dbt_cloud_job(\n    dbt_cloud_job: DbtCloudJob,\n    targeted_retries: int = 3,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Flow that triggers and waits for a dbt Cloud job run, retrying a\n    subset of failed nodes if necessary.\n\n    Args:\n        dbt_cloud_job: Block that holds the information and\n            methods to interact with a dbt Cloud job.\n        targeted_retries: The number of times to retry failed steps.\n\n    Examples:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n        from prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n        @flow\n        def run_dbt_cloud_job_flow():\n            dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n            dbt_cloud_job = DbtCloudJob(\n                dbt_cloud_credentials=dbt_cloud_credentials, job_id=154217\n            )\n            return run_dbt_cloud_job(dbt_cloud_job=dbt_cloud_job)\n\n        run_dbt_cloud_job_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    run = await task(dbt_cloud_job.trigger.aio)(dbt_cloud_job)\n    while targeted_retries &gt; 0:\n        try:\n            await task(run.wait_for_completion.aio)(run)\n            result = await task(run.fetch_result.aio)(run)\n            return result\n        except DbtCloudJobRunFailed:\n            logger.info(\n                f\"Retrying job run with ID: {run.run_id} \"\n                f\"{targeted_retries} more times\"\n            )\n            run = await task(run.retry_failed_steps.aio)(run)\n            targeted_retries -= 1\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run","title":"<code>trigger_dbt_cloud_job_run</code>  <code>async</code>","text":"<p>A task to trigger a dbt Cloud job run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned from the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Trigger a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n\ntrigger_dbt_cloud_job_run_flow()\n</code></pre></p> <p>Trigger a dbt Cloud job run with overrides: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\nfrom prefect_dbt.cloud.models import TriggerJobRunOptions\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    trigger_dbt_cloud_job_run(\n        dbt_cloud_credentials=credentials,\n        job_id=1,\n        options=TriggerJobRunOptions(\n            git_branch=\"staging\",\n            schema_override=\"dbt_cloud_pr_123\",\n            dbt_version_override=\"0.18.0\",\n            target_name_override=\"staging\",\n            timeout_seconds_override=3000,\n            generate_docs_override=True,\n            threads_override=8,\n            steps_override=[\n                \"dbt seed\",\n                \"dbt run --fail-fast\",\n                \"dbt test --fail-fast\",\n            ],\n        ),\n    )\n\n\ntrigger_dbt_cloud_job_run()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Trigger dbt Cloud job run\",\n    description=\"Triggers a dbt Cloud job run for the job \"\n    \"with the given job_id and optional overrides.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def trigger_dbt_cloud_job_run(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    options: Optional[TriggerJobRunOptions] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to trigger a dbt Cloud job run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to trigger.\n        options: An optional TriggerJobRunOptions instance to specify overrides\n            for the triggered job run.\n\n    Returns:\n        The run data returned from the dbt Cloud administrative API.\n\n    Examples:\n        Trigger a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n\n        trigger_dbt_cloud_job_run_flow()\n        ```\n\n        Trigger a dbt Cloud job run with overrides:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n        from prefect_dbt.cloud.models import TriggerJobRunOptions\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            trigger_dbt_cloud_job_run(\n                dbt_cloud_credentials=credentials,\n                job_id=1,\n                options=TriggerJobRunOptions(\n                    git_branch=\"staging\",\n                    schema_override=\"dbt_cloud_pr_123\",\n                    dbt_version_override=\"0.18.0\",\n                    target_name_override=\"staging\",\n                    timeout_seconds_override=3000,\n                    generate_docs_override=True,\n                    threads_override=8,\n                    steps_override=[\n                        \"dbt seed\",\n                        \"dbt run --fail-fast\",\n                        \"dbt test --fail-fast\",\n                    ],\n                ),\n            )\n\n\n        trigger_dbt_cloud_job_run()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    logger.info(f\"Triggering run for job with ID {job_id}\")\n\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.trigger_job_run(job_id=job_id, options=options)\n    except HTTPStatusError as ex:\n        raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n    run_data = response.json()[\"data\"]\n\n    if \"project_id\" in run_data and \"id\" in run_data:\n        logger.info(\n            f\"Run successfully triggered for job with ID {job_id}. \"\n            \"You can view the status of this run at \"\n            f\"https://{dbt_cloud_credentials.domain}/#/accounts/\"\n            f\"{dbt_cloud_credentials.account_id}/projects/{run_data['project_id']}/\"\n            f\"runs/{run_data['id']}/\"\n        )\n\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run_and_wait_for_completion","title":"<code>trigger_dbt_cloud_job_run_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>trigger_job_run_options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>retry_filtered_models_attempts</code> <code>int</code> <p>Number of times to retry models selected by <code>retry_status_filters</code>.</p> <code>3</code> <p>Raises:</p> Type Description <code>DbtCloudJobRunCancelled</code> <p>The triggered dbt Cloud job run was cancelled.</p> <code>DbtCloudJobRunFailed</code> <p>The triggered dbt Cloud job run failed.</p> <code>RuntimeError</code> <p>The triggered dbt Cloud job run ended in an unexpected state.</p> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Trigger a dbt Cloud job and wait for completion as a stand alone flow: <pre><code>import asyncio\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\nasyncio.run(\n    trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1\n    )\n)\n</code></pre></p> <p>Trigger a dbt Cloud job and wait for completion as a sub-flow: <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n@flow\ndef my_flow():\n    ...\n    run_result = trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1\n    )\n    ...\n\nmy_flow()\n</code></pre></p> <p>Trigger a dbt Cloud job with overrides: <pre><code>import asyncio\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\nfrom prefect_dbt.cloud.models import TriggerJobRunOptions\n\nasyncio.run(\n    trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1,\n        trigger_job_run_options=TriggerJobRunOptions(\n            git_branch=\"staging\",\n            schema_override=\"dbt_cloud_pr_123\",\n            dbt_version_override=\"0.18.0\",\n            target_name_override=\"staging\",\n            timeout_seconds_override=3000,\n            generate_docs_override=True,\n            threads_override=8,\n            steps_override=[\n                \"dbt seed\",\n                \"dbt run --fail-fast\",\n                \"dbt test --fail fast\",\n            ],\n        ),\n    )\n)\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow(\n    name=\"Trigger dbt Cloud job run and wait for completion\",\n    description=\"Triggers a dbt Cloud job run and waits for the\"\n    \"triggered run to complete.\",\n)\nasync def trigger_dbt_cloud_job_run_and_wait_for_completion(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    trigger_job_run_options: Optional[TriggerJobRunOptions] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    retry_filtered_models_attempts: int = 3,\n) -&gt; Dict:\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to trigger.\n        trigger_job_run_options: An optional TriggerJobRunOptions instance to\n            specify overrides for the triggered job run.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        retry_filtered_models_attempts: Number of times to retry models selected by `retry_status_filters`.\n\n    Raises:\n        DbtCloudJobRunCancelled: The triggered dbt Cloud job run was cancelled.\n        DbtCloudJobRunFailed: The triggered dbt Cloud job run failed.\n        RuntimeError: The triggered dbt Cloud job run ended in an unexpected state.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Examples:\n        Trigger a dbt Cloud job and wait for completion as a stand alone flow:\n        ```python\n        import asyncio\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n        asyncio.run(\n            trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1\n            )\n        )\n        ```\n\n        Trigger a dbt Cloud job and wait for completion as a sub-flow:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n        @flow\n        def my_flow():\n            ...\n            run_result = trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1\n            )\n            ...\n\n        my_flow()\n        ```\n\n        Trigger a dbt Cloud job with overrides:\n        ```python\n        import asyncio\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n        from prefect_dbt.cloud.models import TriggerJobRunOptions\n\n        asyncio.run(\n            trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1,\n                trigger_job_run_options=TriggerJobRunOptions(\n                    git_branch=\"staging\",\n                    schema_override=\"dbt_cloud_pr_123\",\n                    dbt_version_override=\"0.18.0\",\n                    target_name_override=\"staging\",\n                    timeout_seconds_override=3000,\n                    generate_docs_override=True,\n                    threads_override=8,\n                    steps_override=[\n                        \"dbt seed\",\n                        \"dbt run --fail-fast\",\n                        \"dbt test --fail fast\",\n                    ],\n                ),\n            )\n        )\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    triggered_run_data_future = await trigger_dbt_cloud_job_run.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        options=trigger_job_run_options,\n    )\n    run_id = (await triggered_run_data_future.result()).get(\"id\")\n    if run_id is None:\n        raise RuntimeError(\"Unable to determine run ID for triggered job.\")\n\n    final_run_status, run_data = await wait_for_dbt_cloud_job_run(\n        run_id=run_id,\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    if final_run_status == DbtCloudJobRunStatus.SUCCESS:\n        try:\n            list_run_artifacts_future = await list_dbt_cloud_run_artifacts.submit(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                run_id=run_id,\n            )\n            run_data[\"artifact_paths\"] = await list_run_artifacts_future.result()\n        except DbtCloudListRunArtifactsFailed as ex:\n            logger.warning(\n                \"Unable to retrieve artifacts for job run with ID %s. Reason: %s\",\n                run_id,\n                ex,\n            )\n        logger.info(\n            \"dbt Cloud job run with ID %s completed successfully!\",\n            run_id,\n        )\n        return run_data\n    elif final_run_status == DbtCloudJobRunStatus.CANCELLED:\n        raise DbtCloudJobRunCancelled(\n            f\"Triggered job run with ID {run_id} was cancelled.\"\n        )\n    elif final_run_status == DbtCloudJobRunStatus.FAILED:\n        while retry_filtered_models_attempts &gt; 0:\n            logger.info(\n                f\"Retrying job run with ID: {run_id} \"\n                f\"{retry_filtered_models_attempts} more times\"\n            )\n            try:\n                retry_filtered_models_attempts -= 1\n                run_data = await retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n                    dbt_cloud_credentials=dbt_cloud_credentials,\n                    run_id=run_id,\n                    trigger_job_run_options=trigger_job_run_options,\n                    max_wait_seconds=max_wait_seconds,\n                    poll_frequency_seconds=poll_frequency_seconds,\n                )\n                return run_data\n            except Exception:\n                pass\n        else:\n            raise DbtCloudJobRunFailed(f\"Triggered job run with ID: {run_id} failed.\")\n    else:\n        raise RuntimeError(\n            f\"Triggered job run with ID: {run_id} ended with unexpected\"\n            f\"status {final_run_status.value}.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/models/","title":"Models","text":""},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models","title":"<code>prefect_dbt.cloud.models</code>","text":"<p>Module containing models used for passing data to dbt Cloud</p>"},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models.TriggerJobRunOptions","title":"<code>TriggerJobRunOptions</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Defines options that can be defined when triggering a dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/models.py</code> <pre><code>class TriggerJobRunOptions(BaseModel):\n    \"\"\"\n    Defines options that can be defined when triggering a dbt Cloud job run.\n    \"\"\"\n\n    cause: str = Field(\n        default_factory=default_cause_factory,\n        description=\"A text description of the reason for running this job.\",\n    )\n    git_sha: Optional[str] = Field(\n        default=None, description=\"The git sha to check out before running this job.\"\n    )\n    git_branch: Optional[str] = Field(\n        default=None, description=\"The git branch to check out before running this job.\"\n    )\n    schema_override: Optional[str] = Field(\n        default=None,\n        description=\"Override the destination schema in the configured \"\n        \"target for this job.\",\n    )\n    dbt_version_override: Optional[str] = Field(\n        default=None, description=\"Override the version of dbt used to run this job.\"\n    )\n    threads_override: Optional[int] = Field(\n        default=None, description=\"Override the number of threads used to run this job.\"\n    )\n    target_name_override: Optional[str] = Field(\n        default=None,\n        description=\"Override the target.name context variable used when \"\n        \"running this job\",\n    )\n    generate_docs_override: Optional[bool] = Field(\n        default=None,\n        description=\"Override whether or not this job generates docs \"\n        \"(true=yes, false=no).\",\n    )\n    timeout_seconds_override: Optional[int] = Field(\n        default=None, description=\"Override the timeout in seconds for this job.\"\n    )\n    steps_override: Optional[List[str]] = Field(\n        default=None, description=\"Override the list of steps for this job.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models.default_cause_factory","title":"<code>default_cause_factory</code>","text":"<p>Factory function to populate the default cause for a job run to include information from the Prefect run context.</p> Source code in <code>prefect_dbt/cloud/models.py</code> <pre><code>def default_cause_factory():\n    \"\"\"\n    Factory function to populate the default cause for a job run to include information\n    from the Prefect run context.\n    \"\"\"\n    cause = \"Triggered via Prefect\"\n\n    try:\n        context = get_run_context()\n        if isinstance(context, FlowRunContext):\n            cause = f\"{cause} in flow run {context.flow_run.name}\"\n        elif isinstance(context, TaskRunContext):\n            cause = f\"{cause} in task run {context.task_run.name}\"\n    except RuntimeError:\n        pass\n\n    return cause\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/","title":"Runs","text":""},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs","title":"<code>prefect_dbt.cloud.runs</code>","text":"<p>Module containing tasks and flows for interacting with dbt Cloud job runs</p>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.DbtCloudJobRunStatus","title":"<code>DbtCloudJobRunStatus</code>","text":"<p>               Bases: <code>Enum</code></p> <p>dbt Cloud Job statuses.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>class DbtCloudJobRunStatus(Enum):\n    \"\"\"dbt Cloud Job statuses.\"\"\"\n\n    QUEUED = 1\n    STARTING = 2\n    RUNNING = 3\n    SUCCESS = 10\n    FAILED = 20\n    CANCELLED = 30\n\n    @classmethod\n    def is_terminal_status_code(cls, status_code: Any) -&gt; bool:\n        \"\"\"\n        Returns True if a status code is terminal for a job run.\n        Returns False otherwise.\n        \"\"\"\n        return status_code in [cls.SUCCESS.value, cls.FAILED.value, cls.CANCELLED.value]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.DbtCloudJobRunStatus.is_terminal_status_code","title":"<code>is_terminal_status_code</code>  <code>classmethod</code>","text":"<p>Returns True if a status code is terminal for a job run. Returns False otherwise.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@classmethod\ndef is_terminal_status_code(cls, status_code: Any) -&gt; bool:\n    \"\"\"\n    Returns True if a status code is terminal for a job run.\n    Returns False otherwise.\n    \"\"\"\n    return status_code in [cls.SUCCESS.value, cls.FAILED.value, cls.CANCELLED.value]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.get_dbt_cloud_run_artifact","title":"<code>get_dbt_cloud_run_artifact</code>  <code>async</code>","text":"<p>A task to get an artifact generated for a completed run. The requested artifact is saved to a file in the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>path</code> <code>str</code> <p>The relative path to the run artifact (e.g. manifest.json, catalog.json, run_results.json)</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[Dict, str]</code> <p>The contents of the requested manifest. Returns a <code>Dict</code> if the requested artifact is a JSON file and a <code>str</code> otherwise.</p> <p>Examples:</p> <p>Get an artifact of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.runs import get_dbt_cloud_run_artifact\n\n@flow\ndef get_artifact_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_dbt_cloud_run_artifact(\n        dbt_cloud_credentials=credentials,\n        run_id=42,\n        path=\"manifest.json\"\n    )\n\nget_artifact_flow()\n</code></pre></p> <p>Get an artifact of a dbt Cloud job run and write it to a file: <pre><code>import json\n\nfrom prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_dbt_cloud_run_artifact\n\n@flow\ndef get_artifact_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    get_run_artifact_result = get_dbt_cloud_run_artifact(\n        dbt_cloud_credentials=credentials,\n        run_id=42,\n        path=\"manifest.json\"\n    )\n\n    with open(\"manifest.json\", \"w\") as file:\n        json.dump(get_run_artifact_result, file)\n\nget_artifact_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job artifact\",\n    description=\"Fetches an artifact from a completed run.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_run_artifact(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    path: str,\n    step: Optional[int] = None,\n) -&gt; Union[Dict, str]:\n    \"\"\"\n    A task to get an artifact generated for a completed run. The requested artifact\n    is saved to a file in the current working directory.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the run to list run artifacts for.\n        path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n            run_results.json)\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The contents of the requested manifest. Returns a `Dict` if the\n            requested artifact is a JSON file and a `str` otherwise.\n\n    Examples:\n        Get an artifact of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.runs import get_dbt_cloud_run_artifact\n\n        @flow\n        def get_artifact_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_dbt_cloud_run_artifact(\n                dbt_cloud_credentials=credentials,\n                run_id=42,\n                path=\"manifest.json\"\n            )\n\n        get_artifact_flow()\n        ```\n\n        Get an artifact of a dbt Cloud job run and write it to a file:\n        ```python\n        import json\n\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_dbt_cloud_run_artifact\n\n        @flow\n        def get_artifact_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            get_run_artifact_result = get_dbt_cloud_run_artifact(\n                dbt_cloud_credentials=credentials,\n                run_id=42,\n                path=\"manifest.json\"\n            )\n\n            with open(\"manifest.json\", \"w\") as file:\n                json.dump(get_run_artifact_result, file)\n\n        get_artifact_flow()\n        ```\n    \"\"\"  # noqa\n\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run_artifact(\n                run_id=run_id, path=path, step=step\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n    if path.endswith(\".json\"):\n        artifact_contents = response.json()\n    else:\n        artifact_contents = response.text\n\n    return artifact_contents\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.get_dbt_cloud_run_info","title":"<code>get_dbt_cloud_run_info</code>  <code>async</code>","text":"<p>A task to retrieve information about a dbt Cloud job run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>include_related</code> <code>Optional[List[Literal['trigger', 'job', 'debug_logs', 'run_steps']]]</code> <p>List of related fields to pull with the run. Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\". If \"debug_logs\" is not provided in a request, then the included debug logs will be truncated to the last 1,000 lines of the debug log output file.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> Example <p>Get status of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_run\n\n@flow\ndef get_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_run(\n        dbt_cloud_credentials=credentials,\n        run_id=42\n    )\n\nget_run_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job run details\",\n    description=\"Retrieves details of a dbt Cloud job run \"\n    \"for the run with the given run_id.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_run_info(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    include_related: Optional[\n        List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n    ] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to retrieve information about a dbt Cloud job run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the job to trigger.\n        include_related: List of related fields to pull with the run.\n            Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n            If \"debug_logs\" is not provided in a request, then the included debug\n            logs will be truncated to the last 1,000 lines of the debug log output file.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Example:\n        Get status of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_run\n\n        @flow\n        def get_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_run(\n                dbt_cloud_credentials=credentials,\n                run_id=42\n            )\n\n        get_run_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run(\n                run_id=run_id, include_related=include_related\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.list_dbt_cloud_run_artifacts","title":"<code>list_dbt_cloud_run_artifacts</code>  <code>async</code>","text":"<p>A task to list the artifact files generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>A list of paths to artifact files that can be used to retrieve the generated artifacts.</p> Example <p>List artifacts of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import list_dbt_cloud_run_artifacts\n\n@flow\ndef list_artifacts_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return list_dbt_cloud_run_artifacts(\n        dbt_cloud_credentials=credentials,\n        run_id=42\n    )\n\nlist_artifacts_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"List dbt Cloud job artifacts\",\n    description=\"Fetches a list of artifact files generated for a completed run.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def list_dbt_cloud_run_artifacts(\n    dbt_cloud_credentials: DbtCloudCredentials, run_id: int, step: Optional[int] = None\n) -&gt; List[str]:\n    \"\"\"\n    A task to list the artifact files generated for a completed run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the run to list run artifacts for.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        A list of paths to artifact files that can be used to retrieve the generated artifacts.\n\n    Example:\n        List artifacts of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import list_dbt_cloud_run_artifacts\n\n        @flow\n        def list_artifacts_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return list_dbt_cloud_run_artifacts(\n                dbt_cloud_credentials=credentials,\n                run_id=42\n            )\n\n        list_artifacts_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.list_run_artifacts(run_id=run_id, step=step)\n    except HTTPStatusError as ex:\n        raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.wait_for_dbt_cloud_job_run","title":"<code>wait_for_dbt_cloud_job_run</code>  <code>async</code>","text":"<p>Waits for the given dbt Cloud job run to finish running.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to wait for.</p> required <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <p>Raises:</p> Type Description <code>DbtCloudJobRunTimedOut</code> <p>When the elapsed wait time exceeds <code>max_wait_seconds</code>.</p> <p>Returns:</p> Name Type Description <code>run_status</code> <code>DbtCloudJobRunStatus</code> <p>An enum representing the final dbt Cloud job run status</p> <code>run_data</code> <code>Dict</code> <p>A dictionary containing information about the run after completion.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@flow(\n    name=\"Wait for dbt Cloud job run\",\n    description=\"Waits for a dbt Cloud job run to finish running.\",\n)\nasync def wait_for_dbt_cloud_job_run(\n    run_id: int,\n    dbt_cloud_credentials: DbtCloudCredentials,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n) -&gt; Tuple[DbtCloudJobRunStatus, Dict]:\n    \"\"\"\n    Waits for the given dbt Cloud job run to finish running.\n\n    Args:\n        run_id: The ID of the run to wait for.\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Raises:\n        DbtCloudJobRunTimedOut: When the elapsed wait time exceeds `max_wait_seconds`.\n\n    Returns:\n        run_status: An enum representing the final dbt Cloud job run status\n        run_data: A dictionary containing information about the run after completion.\n\n\n    Example:\n\n\n    \"\"\"\n    logger = get_run_logger()\n    seconds_waited_for_run_completion = 0\n    wait_for = []\n    while seconds_waited_for_run_completion &lt;= max_wait_seconds:\n        run_data_future = await get_dbt_cloud_run_info.submit(\n            dbt_cloud_credentials=dbt_cloud_credentials,\n            run_id=run_id,\n            wait_for=wait_for,\n        )\n        run_data = await run_data_future.result()\n        run_status_code = run_data.get(\"status\")\n\n        if DbtCloudJobRunStatus.is_terminal_status_code(run_status_code):\n            return DbtCloudJobRunStatus(run_status_code), run_data\n\n        wait_for = [run_data_future]\n        logger.debug(\n            \"dbt Cloud job run with ID %i has status %s. Waiting for %i seconds.\",\n            run_id,\n            DbtCloudJobRunStatus(run_status_code).name,\n            poll_frequency_seconds,\n        )\n        await asyncio.sleep(poll_frequency_seconds)\n        seconds_waited_for_run_completion += poll_frequency_seconds\n\n    raise DbtCloudJobRunTimedOut(\n        f\"Max wait time of {max_wait_seconds} seconds exceeded while waiting \"\n        \"for job run with ID {run_id}\"\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/","title":"Utils","text":""},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils","title":"<code>prefect_dbt.cloud.utils</code>","text":"<p>Utilities for common interactions with the dbt Cloud API</p>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.DbtCloudAdministrativeApiCallFailed","title":"<code>DbtCloudAdministrativeApiCallFailed</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a call to dbt Cloud administrative API fails.</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>class DbtCloudAdministrativeApiCallFailed(Exception):\n    \"\"\"Raised when a call to dbt Cloud administrative API fails.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.call_dbt_cloud_administrative_api_endpoint","title":"<code>call_dbt_cloud_administrative_api_endpoint</code>  <code>async</code>","text":"<p>Task that calls a specified endpoint in the dbt Cloud administrative API. Use this task if a prebuilt one is not yet available.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>path</code> <code>str</code> <p>The partial path for the request (e.g. /projects/). Will be appended onto the base URL as determined by the client configuration.</p> required <code>http_method</code> <code>str</code> <p>HTTP method to call on the endpoint.</p> required <code>params</code> <code>Optional[Dict[str, Any]]</code> <p>Query parameters to include in the request.</p> <code>None</code> <code>json</code> <code>Optional[Dict[str, Any]]</code> <p>JSON serializable body to send in the request.</p> <code>None</code> <p>Returns:</p> Type Description <code>Any</code> <p>The body of the response. If the body is JSON serializable, then the result of <code>json.loads</code> with the body as the input will be returned. Otherwise, the body will be returned directly.</p> <p>Examples:</p> <p>List projects for an account: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n@flow\ndef get_projects_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    result = call_dbt_cloud_administrative_api_endpoint(\n        dbt_cloud_credentials=credentials,\n        path=\"/projects/\",\n        http_method=\"GET\",\n    )\n    return result[\"data\"]\n\nget_projects_flow()\n</code></pre></p> <p>Create a new job: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n\n@flow\ndef create_job_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    result = call_dbt_cloud_administrative_api_endpoint(\n        dbt_cloud_credentials=credentials,\n        path=\"/jobs/\",\n        http_method=\"POST\",\n        json={\n            \"id\": None,\n            \"account_id\": 123456789,\n            \"project_id\": 100,\n            \"environment_id\": 10,\n            \"name\": \"Nightly run\",\n            \"dbt_version\": None,\n            \"triggers\": {\"github_webhook\": True, \"schedule\": True},\n            \"execute_steps\": [\"dbt run\", \"dbt test\", \"dbt source snapshot-freshness\"],\n            \"settings\": {\"threads\": 4, \"target_name\": \"prod\"},\n            \"state\": 1,\n            \"schedule\": {\n                \"date\": {\"type\": \"every_day\"},\n                \"time\": {\"type\": \"every_hour\", \"interval\": 1},\n            },\n        },\n    )\n    return result[\"data\"]\n\ncreate_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>@task(\n    name=\"Call dbt Cloud administrative API endpoint\",\n    description=\"Calls a dbt Cloud administrative API endpoint\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def call_dbt_cloud_administrative_api_endpoint(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    path: str,\n    http_method: str,\n    params: Optional[Dict[str, Any]] = None,\n    json: Optional[Dict[str, Any]] = None,\n) -&gt; Any:\n    \"\"\"\n    Task that calls a specified endpoint in the dbt Cloud administrative API. Use this\n    task if a prebuilt one is not yet available.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        path: The partial path for the request (e.g. /projects/). Will be appended\n            onto the base URL as determined by the client configuration.\n        http_method: HTTP method to call on the endpoint.\n        params: Query parameters to include in the request.\n        json: JSON serializable body to send in the request.\n\n    Returns:\n        The body of the response. If the body is JSON serializable, then the result of\n            `json.loads` with the body as the input will be returned. Otherwise, the\n            body will be returned directly.\n\n    Examples:\n        List projects for an account:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n        @flow\n        def get_projects_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            result = call_dbt_cloud_administrative_api_endpoint(\n                dbt_cloud_credentials=credentials,\n                path=\"/projects/\",\n                http_method=\"GET\",\n            )\n            return result[\"data\"]\n\n        get_projects_flow()\n        ```\n\n        Create a new job:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n\n        @flow\n        def create_job_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            result = call_dbt_cloud_administrative_api_endpoint(\n                dbt_cloud_credentials=credentials,\n                path=\"/jobs/\",\n                http_method=\"POST\",\n                json={\n                    \"id\": None,\n                    \"account_id\": 123456789,\n                    \"project_id\": 100,\n                    \"environment_id\": 10,\n                    \"name\": \"Nightly run\",\n                    \"dbt_version\": None,\n                    \"triggers\": {\"github_webhook\": True, \"schedule\": True},\n                    \"execute_steps\": [\"dbt run\", \"dbt test\", \"dbt source snapshot-freshness\"],\n                    \"settings\": {\"threads\": 4, \"target_name\": \"prod\"},\n                    \"state\": 1,\n                    \"schedule\": {\n                        \"date\": {\"type\": \"every_day\"},\n                        \"time\": {\"type\": \"every_hour\", \"interval\": 1},\n                    },\n                },\n            )\n            return result[\"data\"]\n\n        create_job_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.call_endpoint(\n                http_method=http_method, path=path, params=params, json=json\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudAdministrativeApiCallFailed(extract_developer_message(ex)) from ex\n    try:\n        return response.json()\n    except JSONDecodeError:\n        return response.text\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.extract_developer_message","title":"<code>extract_developer_message</code>","text":"<p>Extracts developer message from a error response from the dbt Cloud administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>ex</code> <code>HTTPStatusError</code> <p>An HTTPStatusError raised by httpx</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>developer_message from dbt Cloud administrative API response or None if a</p> <code>Optional[str]</code> <p>developer_message cannot be extracted</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>def extract_developer_message(ex: HTTPStatusError) -&gt; Optional[str]:\n    \"\"\"\n    Extracts developer message from a error response from the dbt Cloud\n    administrative API.\n\n    Args:\n        ex: An HTTPStatusError raised by httpx\n\n    Returns:\n        developer_message from dbt Cloud administrative API response or None if a\n        developer_message cannot be extracted\n    \"\"\"\n    response_payload = ex.response.json()\n    status = response_payload.get(\"status\", {})\n    return status.get(\"developer_message\")\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.extract_user_message","title":"<code>extract_user_message</code>","text":"<p>Extracts user message from a error response from the dbt Cloud administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>ex</code> <code>HTTPStatusError</code> <p>An HTTPStatusError raised by httpx</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>user_message from dbt Cloud administrative API response or None if a</p> <code>Optional[str]</code> <p>user_message cannot be extracted</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>def extract_user_message(ex: HTTPStatusError) -&gt; Optional[str]:\n    \"\"\"\n    Extracts user message from a error response from the dbt Cloud administrative API.\n\n    Args:\n        ex: An HTTPStatusError raised by httpx\n\n    Returns:\n        user_message from dbt Cloud administrative API response or None if a\n        user_message cannot be extracted\n    \"\"\"\n    response_payload = ex.response.json()\n    status = response_payload.get(\"status\", {})\n    return status.get(\"user_message\")\n</code></pre>"},{"location":"integrations/prefect-docker/","title":"prefect-docker","text":"<p>The prefect-docker library is required to create deployments that will submit runs to most Prefect work pool infrastructure types. See the Prefect tutorial and the Docker guide to learn how to create and run deployments that use Docker.</p>"},{"location":"integrations/prefect-docker/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-docker/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Docker installed and running.</li> </ul>"},{"location":"integrations/prefect-docker/#install-prefect-docker","title":"Install prefect-docker","text":"<pre><code>pip install prefect-docker\n</code></pre>"},{"location":"integrations/prefect-docker/#resources","title":"Resources","text":"<p>For assistance using Docker, consult the Docker documentation.</p> <p>Refer to the prefect-docker API documentation linked in the sidebar to explore all the capabilities of the prefect-docker library.</p>"},{"location":"integrations/prefect-docker/containers/","title":"Containers","text":""},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers","title":"<code>prefect_docker.containers</code>","text":"<p>Integrations with Docker Containers.</p>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.create_docker_container","title":"<code>create_docker_container</code>  <code>async</code>","text":"<p>Create a container without starting it. Similar to docker create.</p> <p>Parameters:</p> Name Type Description Default <code>image</code> <code>str</code> <p>The image to run.</p> required <code>command</code> <code>Optional[Union[str, List[str]]]</code> <p>The command(s) to run in the container.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>The name for this container.</p> <code>None</code> <code>detach</code> <code>Optional[bool]</code> <p>Run container in the background.</p> <code>None</code> <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>entrypoint</code> <code>Optional[Union[str, List[str]]]</code> <p>The entrypoint for the container.</p> <code>None</code> <code>environment</code> <code>Optional[Union[Dict[str, str], List[str]]]</code> <p>Environment variables to set inside the container, as a dictionary or a list of strings in the format [\"SOMEVARIABLE=xxx\"].</p> <code>None</code> <code>**create_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.create</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>A Docker Container object.</p> <p>Examples:</p> <p>Create a container with the Prefect image. <pre><code>from prefect import flow\nfrom prefect_docker.containers import create_docker_container\n\n@flow\ndef create_docker_container_flow():\n    container = create_docker_container(\n        image=\"prefecthq/prefect\",\n        command=\"echo 'hello world!'\"\n    )\n\ncreate_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def create_docker_container(\n    image: str,\n    command: Optional[Union[str, List[str]]] = None,\n    name: Optional[str] = None,\n    detach: Optional[bool] = None,\n    entrypoint: Optional[Union[str, List[str]]] = None,\n    environment: Optional[Union[Dict[str, str], List[str]]] = None,\n    docker_host: Optional[DockerHost] = None,\n    **create_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Create a container without starting it. Similar to docker create.\n\n    Args:\n        image: The image to run.\n        command: The command(s) to run in the container.\n        name: The name for this container.\n        detach: Run container in the background.\n        docker_host: Settings for interacting with a Docker host.\n        entrypoint: The entrypoint for the container.\n        environment: Environment variables to set inside the container,\n            as a dictionary or a list of strings in the format [\"SOMEVARIABLE=xxx\"].\n        **create_kwargs: Additional keyword arguments to pass to\n            [`client.containers.create`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.ContainerCollection.create).\n\n    Returns:\n        A Docker Container object.\n\n    Examples:\n        Create a container with the Prefect image.\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import create_docker_container\n\n        @flow\n        def create_docker_container_flow():\n            container = create_docker_container(\n                image=\"prefecthq/prefect\",\n                command=\"echo 'hello world!'\"\n            )\n\n        create_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        logger.info(f\"Creating container with {image!r} image.\")\n        container = await run_sync_in_worker_thread(\n            client.containers.create,\n            image=image,\n            command=command,\n            name=name,\n            detach=detach,\n            entrypoint=entrypoint,\n            environment=environment,\n            **create_kwargs,\n        )\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.get_docker_container_logs","title":"<code>get_docker_container_logs</code>  <code>async</code>","text":"<p>Get logs from this container. Similar to the docker logs command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to pull logs from.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**logs_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).logs</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The Container's logs.</p> <p>Examples:</p> <p>Gets logs from a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import get_docker_container_logs\n\n@flow\ndef get_docker_container_logs_flow():\n    logs = get_docker_container_logs(container_id=\"c157\")\n    return logs\n\nget_docker_container_logs_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def get_docker_container_logs(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **logs_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Get logs from this container. Similar to the docker logs command.\n\n    Args:\n        container_id: The container ID to pull logs from.\n        docker_host: Settings for interacting with a Docker host.\n        **logs_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).logs`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.logs).\n\n    Returns:\n        The Container's logs.\n\n    Examples:\n        Gets logs from a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import get_docker_container_logs\n\n        @flow\n        def get_docker_container_logs_flow():\n            logs = get_docker_container_logs(container_id=\"c157\")\n            return logs\n\n        get_docker_container_logs_flow()\n        ```\n\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Retrieving logs from {container.id!r} container.\")\n        logs = await run_sync_in_worker_thread(container.logs, **logs_kwargs)\n\n    return logs.decode()\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.remove_docker_container","title":"<code>remove_docker_container</code>  <code>async</code>","text":"<p>Remove this container. Similar to the docker rm command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to remove.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**remove_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).remove</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Removes a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import remove_docker_container\n\n@flow\ndef remove_docker_container_flow():\n    container = remove_docker_container(container_id=\"c157\")\n    return container\n\nremove_docker_container()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def remove_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **remove_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Remove this container. Similar to the docker rm command.\n\n    Args:\n        container_id: The container ID to remove.\n        docker_host: Settings for interacting with a Docker host.\n        **remove_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).remove`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.remove).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Removes a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import remove_docker_container\n\n        @flow\n        def remove_docker_container_flow():\n            container = remove_docker_container(container_id=\"c157\")\n            return container\n\n        remove_docker_container()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Removing container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.remove, **remove_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.start_docker_container","title":"<code>start_docker_container</code>  <code>async</code>","text":"<p>Start this container. Similar to the docker start command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to start.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**start_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).start</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Start a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import start_docker_container\n\n@flow\ndef start_docker_container_flow():\n    container = start_docker_container(container_id=\"c157\")\n    return container\n\nstart_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def start_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **start_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Start this container. Similar to the docker start command.\n\n    Args:\n        container_id: The container ID to start.\n        docker_host: Settings for interacting with a Docker host.\n        **start_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).start`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.start).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Start a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import start_docker_container\n\n        @flow\n        def start_docker_container_flow():\n            container = start_docker_container(container_id=\"c157\")\n            return container\n\n        start_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Starting container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.start, **start_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.stop_docker_container","title":"<code>stop_docker_container</code>  <code>async</code>","text":"<p>Stops a container. Similar to the docker stop command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to stop.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**stop_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).stop</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Stop a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import stop_docker_container\n\n@flow\ndef stop_docker_container_flow():\n    container = stop_docker_container(container_id=\"c157\")\n    return container\n\nstop_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def stop_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **stop_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Stops a container. Similar to the docker stop command.\n\n    Args:\n        container_id: The container ID to stop.\n        docker_host: Settings for interacting with a Docker host.\n        **stop_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).stop`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.stop).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Stop a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import stop_docker_container\n\n        @flow\n        def stop_docker_container_flow():\n            container = stop_docker_container(container_id=\"c157\")\n            return container\n\n        stop_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Stopping container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.stop, **stop_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials","title":"<code>prefect_docker.credentials</code>","text":"<p>Module containing docker credentials.</p>"},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials.DockerRegistryCredentials","title":"<code>DockerRegistryCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage credentials for interacting with a Docker Registry.</p> <p>Examples:</p> <p>Log into Docker Registry. <pre><code>from prefect_docker import DockerHost, DockerRegistryCredentials\n\ndocker_host = DockerHost()\ndocker_registry_credentials = DockerRegistryCredentials(\n    username=\"my_username\",\n    password=\"my_password\",\n    registry_url=\"registry.hub.docker.com\",\n)\nwith docker_host.get_client() as client:\n    docker_registry_credentials.login(client)\n</code></pre></p> Source code in <code>prefect_docker/credentials.py</code> <pre><code>class DockerRegistryCredentials(Block):\n    \"\"\"\n    Block used to manage credentials for interacting with a Docker Registry.\n\n    Examples:\n        Log into Docker Registry.\n        ```python\n        from prefect_docker import DockerHost, DockerRegistryCredentials\n\n        docker_host = DockerHost()\n        docker_registry_credentials = DockerRegistryCredentials(\n            username=\"my_username\",\n            password=\"my_password\",\n            registry_url=\"registry.hub.docker.com\",\n        )\n        with docker_host.get_client() as client:\n            docker_registry_credentials.login(client)\n        ```\n    \"\"\"\n\n    _block_type_name = \"Docker Registry Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"  # noqa\n    _description = \"Store credentials for interacting with a Docker Registry.\"\n\n    username: str = Field(\n        default=..., description=\"The username to log into the registry with.\"\n    )\n    password: SecretStr = Field(\n        default=..., description=\"The password to log into the registry with.\"\n    )\n    registry_url: str = Field(\n        default=...,\n        description=(\n            'The URL to the registry. Generally, \"http\" or \"https\" can be omitted.'\n        ),\n        example=\"index.docker.io\",\n    )\n    reauth: bool = Field(\n        default=True,\n        description=\"Whether or not to reauthenticate on each interaction.\",\n    )\n\n    async def login(self, client: docker.DockerClient):\n        \"\"\"\n        Authenticates a given Docker client with the configured Docker registry.\n\n        Args:\n            client: A Docker Client.\n        \"\"\"\n        logger = get_run_logger()\n        logger.debug(f\"Logging into {self.registry_url}.\")\n        await run_sync_in_worker_thread(\n            client.login,\n            username=self.username,\n            password=self.password.get_secret_value(),\n            registry=self.registry_url,\n            # See https://github.com/docker/docker-py/issues/2256 for information on\n            # the default value for reauth.\n            reauth=self.reauth,\n        )\n</code></pre>"},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials.DockerRegistryCredentials.login","title":"<code>login</code>  <code>async</code>","text":"<p>Authenticates a given Docker client with the configured Docker registry.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>DockerClient</code> <p>A Docker Client.</p> required Source code in <code>prefect_docker/credentials.py</code> <pre><code>async def login(self, client: docker.DockerClient):\n    \"\"\"\n    Authenticates a given Docker client with the configured Docker registry.\n\n    Args:\n        client: A Docker Client.\n    \"\"\"\n    logger = get_run_logger()\n    logger.debug(f\"Logging into {self.registry_url}.\")\n    await run_sync_in_worker_thread(\n        client.login,\n        username=self.username,\n        password=self.password.get_secret_value(),\n        registry=self.registry_url,\n        # See https://github.com/docker/docker-py/issues/2256 for information on\n        # the default value for reauth.\n        reauth=self.reauth,\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/host/","title":"Host","text":""},{"location":"integrations/prefect-docker/host/#prefect_docker.host","title":"<code>prefect_docker.host</code>","text":"<p>Module containing Docker host settings.</p>"},{"location":"integrations/prefect-docker/host/#prefect_docker.host.DockerHost","title":"<code>DockerHost</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage settings for interacting with a Docker host.</p> <p>Attributes:</p> Name Type Description <code>base_url</code> <code>Optional[str]</code> <p>URL to the Docker server, e.g. <code>unix:///var/run/docker.sock</code> or <code>tcp://127.0.0.1:1234</code>. If this is not set, the client will be configured from environment variables.</p> <code>version</code> <code>str</code> <p>The version of the API to use. Set to auto to automatically detect the server's version.</p> <code>timeout</code> <code>Optional[int]</code> <p>Default timeout for API calls, in seconds.</p> <code>max_pool_size</code> <code>Optional[int]</code> <p>The maximum number of connections to save in the pool.</p> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>docker.from_env()</code> or <code>DockerClient</code>.</p> <p>Examples:</p> <p>Get a Docker Host client. <pre><code>from prefect_docker import DockerHost\n\ndocker_host = DockerHost(\nbase_url=\"tcp://127.0.0.1:1234\",\n    max_pool_size=4\n)\nwith docker_host.get_client() as client:\n    ... # Use the client for Docker operations\n</code></pre></p> Source code in <code>prefect_docker/host.py</code> <pre><code>class DockerHost(Block):\n    \"\"\"\n    Block used to manage settings for interacting with a Docker host.\n\n    Attributes:\n        base_url: URL to the Docker server, e.g. `unix:///var/run/docker.sock`\n            or `tcp://127.0.0.1:1234`. If this is not set, the client will\n            be configured from environment variables.\n        version: The version of the API to use. Set to auto to\n            automatically detect the server's version.\n        timeout: Default timeout for API calls, in seconds.\n        max_pool_size: The maximum number of connections to save in the pool.\n        client_kwargs: Additional keyword arguments to pass to\n            `docker.from_env()` or `DockerClient`.\n\n    Examples:\n        Get a Docker Host client.\n        ```python\n        from prefect_docker import DockerHost\n\n        docker_host = DockerHost(\n        base_url=\"tcp://127.0.0.1:1234\",\n            max_pool_size=4\n        )\n        with docker_host.get_client() as client:\n            ... # Use the client for Docker operations\n        ```\n    \"\"\"\n\n    _block_type_name = \"Docker Host\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"  # noqa\n    _description = \"Store settings for interacting with a Docker host.\"\n\n    base_url: Optional[str] = Field(\n        default=None,\n        description=\"URL to the Docker host.\",\n        title=\"Base URL\",\n        example=\"unix:///var/run/docker.sock\",\n    )\n    version: str = Field(default=\"auto\", description=\"The version of the API to use\")\n    timeout: Optional[int] = Field(\n        default=None, description=\"Default timeout for API calls, in seconds.\"\n    )\n    max_pool_size: Optional[int] = Field(\n        default=None,\n        description=\"The maximum number of connections to save in the pool.\",\n    )\n    client_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional Configuration\",\n        description=(\n            \"Additional keyword arguments to pass to \"\n            \"`docker.from_env()` or `DockerClient`.\"\n        ),\n    )\n\n    def get_client(self) -&gt; docker.DockerClient:\n        \"\"\"\n        Gets a Docker Client to communicate with a Docker host.\n\n        Returns:\n            A Docker Client.\n        \"\"\"\n        logger = get_run_logger()\n        client_kwargs = {\n            \"version\": self.version,\n            \"timeout\": self.timeout,\n            \"max_pool_size\": self.max_pool_size,\n            **self.client_kwargs,\n        }\n        client_kwargs = {\n            key: value for key, value in client_kwargs.items() if value is not None\n        }\n        if self.base_url is None:\n            logger.debug(\n                f\"Creating a Docker client from \"\n                f\"environment variables, using {self.version} version.\"\n            )\n            client = _ContextManageableDockerClient.from_env(**client_kwargs)\n        else:\n            logger.debug(\n                f\"Creating a Docker client to {self.base_url} \"\n                f\"using {self.version} version.\"\n            )\n            client = _ContextManageableDockerClient(\n                base_url=self.base_url, **client_kwargs\n            )\n        return client\n</code></pre>"},{"location":"integrations/prefect-docker/host/#prefect_docker.host.DockerHost.get_client","title":"<code>get_client</code>","text":"<p>Gets a Docker Client to communicate with a Docker host.</p> <p>Returns:</p> Type Description <code>DockerClient</code> <p>A Docker Client.</p> Source code in <code>prefect_docker/host.py</code> <pre><code>def get_client(self) -&gt; docker.DockerClient:\n    \"\"\"\n    Gets a Docker Client to communicate with a Docker host.\n\n    Returns:\n        A Docker Client.\n    \"\"\"\n    logger = get_run_logger()\n    client_kwargs = {\n        \"version\": self.version,\n        \"timeout\": self.timeout,\n        \"max_pool_size\": self.max_pool_size,\n        **self.client_kwargs,\n    }\n    client_kwargs = {\n        key: value for key, value in client_kwargs.items() if value is not None\n    }\n    if self.base_url is None:\n        logger.debug(\n            f\"Creating a Docker client from \"\n            f\"environment variables, using {self.version} version.\"\n        )\n        client = _ContextManageableDockerClient.from_env(**client_kwargs)\n    else:\n        logger.debug(\n            f\"Creating a Docker client to {self.base_url} \"\n            f\"using {self.version} version.\"\n        )\n        client = _ContextManageableDockerClient(\n            base_url=self.base_url, **client_kwargs\n        )\n    return client\n</code></pre>"},{"location":"integrations/prefect-docker/images/","title":"Images","text":""},{"location":"integrations/prefect-docker/images/#prefect_docker.images","title":"<code>prefect_docker.images</code>","text":"<p>Integrations with Docker Images.</p>"},{"location":"integrations/prefect-docker/images/#prefect_docker.images.pull_docker_image","title":"<code>pull_docker_image</code>  <code>async</code>","text":"<p>Pull an image of the given name and return it. Similar to the docker pull command.</p> <p>If all_tags is set, the tag parameter is ignored and all image tags will be pulled.</p> <p>Parameters:</p> Name Type Description Default <code>repository</code> <code>str</code> <p>The repository to pull.</p> required <code>tag</code> <code>Optional[str]</code> <p>The tag to pull; if not provided, it is set to latest.</p> <code>None</code> <code>platform</code> <code>Optional[str]</code> <p>Platform in the format os[/arch[/variant]].</p> <code>None</code> <code>all_tags</code> <code>bool</code> <p>Pull all image tags which will return a list of Images.</p> <code>False</code> <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host; if not provided, will automatically instantiate a <code>DockerHost</code> from env.</p> <code>None</code> <code>docker_registry_credentials</code> <code>Optional[DockerRegistryCredentials]</code> <p>Docker credentials used to log in to a registry before pulling the image.</p> <code>None</code> <code>**pull_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.images.pull</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Image, List[Image]]</code> <p>The image that has been pulled, or a list of images if <code>all_tags</code> is <code>True</code>.</p> <p>Examples:</p> <p>Pull prefecthq/prefect image with the tag latest-python3.10. <pre><code>from prefect import flow\nfrom prefect_docker.images import pull_docker_image\n\n@flow\ndef pull_docker_image_flow():\n    image = pull_docker_image(\n        repository=\"prefecthq/prefect\",\n        tag=\"latest-python3.10\"\n    )\n    return image\n\npull_docker_image_flow()\n</code></pre></p> Source code in <code>prefect_docker/images.py</code> <pre><code>@task\nasync def pull_docker_image(\n    repository: str,\n    tag: Optional[str] = None,\n    platform: Optional[str] = None,\n    all_tags: bool = False,\n    docker_host: Optional[DockerHost] = None,\n    docker_registry_credentials: Optional[DockerRegistryCredentials] = None,\n    **pull_kwargs: Dict[str, Any],\n) -&gt; Union[Image, List[Image]]:\n    \"\"\"\n    Pull an image of the given name and return it. Similar to the docker pull command.\n\n    If all_tags is set, the tag parameter is ignored and all image tags will be pulled.\n\n    Args:\n        repository: The repository to pull.\n        tag: The tag to pull; if not provided, it is set to latest.\n        platform: Platform in the format os[/arch[/variant]].\n        all_tags: Pull all image tags which will return a list of Images.\n        docker_host: Settings for interacting with a Docker host; if not\n            provided, will automatically instantiate a `DockerHost` from env.\n        docker_registry_credentials: Docker credentials used to log in to\n            a registry before pulling the image.\n        **pull_kwargs: Additional keyword arguments to pass to `client.images.pull`.\n\n    Returns:\n        The image that has been pulled, or a list of images if `all_tags` is `True`.\n\n    Examples:\n        Pull prefecthq/prefect image with the tag latest-python3.10.\n        ```python\n        from prefect import flow\n        from prefect_docker.images import pull_docker_image\n\n        @flow\n        def pull_docker_image_flow():\n            image = pull_docker_image(\n                repository=\"prefecthq/prefect\",\n                tag=\"latest-python3.10\"\n            )\n            return image\n\n        pull_docker_image_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    if tag and all_tags:\n        raise ValueError(\"Cannot pass `tags` and `all_tags` together\")\n\n    pull_kwargs = {\n        \"repository\": repository,\n        \"tag\": tag,\n        \"platform\": platform,\n        \"all_tags\": all_tags,\n        **pull_kwargs,\n    }\n    pull_kwargs = {\n        key: value for key, value in pull_kwargs.items() if value is not None\n    }\n\n    with (docker_host or DockerHost()).get_client() as client:\n        if docker_registry_credentials is not None:\n            await docker_registry_credentials.login(client=client)\n\n        if tag:\n            logger.info(f\"Pulling image: {repository}:{tag}.\")\n        elif all_tags:\n            logger.info(f\"Pulling all images from: {repository}\")\n\n        image = await run_sync_in_worker_thread(client.images.pull, **pull_kwargs)\n\n    return image\n</code></pre>"},{"location":"integrations/prefect-docker/worker/","title":"Worker","text":""},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker","title":"<code>prefect_docker.worker</code>","text":"<p>Module containing the Docker worker used for executing flow runs as Docker containers.</p> <p>To start a Docker worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type docker\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker","title":"<code>DockerWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Docker containers.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Docker containers.\"\"\"\n\n    type = \"docker\"\n    job_configuration = DockerWorkerJobConfiguration\n    _description = (\n        \"Execute flow runs within Docker containers. Works well for managing flow \"\n        \"execution environments via Docker images. Requires access to a running \"\n        \"Docker daemon.\"\n    )\n    _display_name = \"Docker\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-docker/worker/\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/2IfXXfMq66mrzJBDFFCHTp/6d8f320d9e4fc4393f045673d61ab612/Moby-logo.png?h=250\"  # noqa\n\n    def __init__(self, *args: Any, test_mode: bool = None, **kwargs: Any) -&gt; None:\n        if test_mode is None:\n            self.test_mode = bool(os.getenv(\"PREFECT_DOCKER_TEST_MODE\", False))\n        else:\n            self.test_mode = test_mode\n        super().__init__(*args, **kwargs)\n\n    async def setup(self):\n        if not self.test_mode:\n            self._client = get_client()\n            if self._client.server_type == ServerType.EPHEMERAL:\n                raise RuntimeError(\n                    \"Docker worker cannot be used with an ephemeral server. Please set\"\n                    \" PREFECT_API_URL to the URL for your Prefect API instance. You\"\n                    \" can use a local Prefect API instance by running `prefect server\"\n                    \" start`.\"\n                )\n\n        return await super().setup()\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: BaseJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        \"\"\"\n        Executes a flow run within a Docker container and waits for the flow run\n        to complete.\n        \"\"\"\n        # The `docker` library uses requests instead of an async http library so it must\n        # be run in a thread to avoid blocking the event loop.\n        container, created_event = await run_sync_in_worker_thread(\n            self._create_and_start_container, configuration\n        )\n        container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n        # Mark as started and return the infrastructure id\n        if task_status:\n            task_status.started(container_pid)\n\n        # Monitor the container\n        container = await run_sync_in_worker_thread(\n            self._watch_container_safe, container, configuration, created_event\n        )\n\n        exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n        return DockerWorkerResult(\n            status_code=exit_code if exit_code is not None else -1,\n            identifier=container_pid,\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: DockerWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a container for a cancelled flow run based on the provided infrastructure\n        PID.\n        \"\"\"\n        docker_client = self._get_client()\n\n        base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n        if docker_client.api.base_url != base_url:\n            raise InfrastructureNotAvailable(\n                \"\".join(\n                    [\n                        (\n                            f\"Unable to stop container {container_id!r}: the current\"\n                            \" Docker API \"\n                        ),\n                        (\n                            f\"URL {docker_client.api.base_url!r} does not match the\"\n                            \" expected \"\n                        ),\n                        f\"API base URL {base_url}.\",\n                    ]\n                )\n            )\n        await run_sync_in_worker_thread(\n            self._stop_container, container_id, docker_client, grace_seconds\n        )\n\n    def _stop_container(\n        self,\n        container_id: str,\n        client: \"DockerClient\",\n        grace_seconds: int = 30,\n    ):\n        try:\n            container = client.containers.get(container_id=container_id)\n        except docker.errors.NotFound:\n            raise InfrastructureNotFound(\n                f\"Unable to stop container {container_id!r}: The container was not\"\n                \" found.\"\n            )\n\n        container.stop(timeout=grace_seconds)\n\n    def _get_client(self):\n        \"\"\"Returns a docker client.\"\"\"\n        try:\n            with warnings.catch_warnings():\n                # Silence warnings due to use of deprecated methods within dockerpy\n                # See https://github.com/docker/docker-py/pull/2931\n                warnings.filterwarnings(\n                    \"ignore\",\n                    message=\"distutils Version classes are deprecated.*\",\n                    category=DeprecationWarning,\n                )\n\n                docker_client = docker.from_env()\n\n        except docker.errors.DockerException as exc:\n            raise RuntimeError(\"Could not connect to Docker.\") from exc\n\n        return docker_client\n\n    def _get_infrastructure_pid(self, container_id: str) -&gt; str:\n        \"\"\"Generates a Docker infrastructure_pid string in the form of\n        `&lt;docker_host_base_url&gt;:&lt;container_id&gt;`.\n        \"\"\"\n        docker_client = self._get_client()\n        base_url = docker_client.api.base_url\n        docker_client.close()\n        return f\"{base_url}:{container_id}\"\n\n    def _parse_infrastructure_pid(self, infrastructure_pid: str) -&gt; Tuple[str, str]:\n        \"\"\"Splits a Docker infrastructure_pid into its component parts\"\"\"\n\n        # base_url can contain `:` so we only want the last item of the split\n        base_url, container_id = infrastructure_pid.rsplit(\":\", 1)\n        return base_url, str(container_id)\n\n    def _build_container_settings(\n        self,\n        docker_client: \"DockerClient\",\n        configuration: DockerWorkerJobConfiguration,\n    ) -&gt; Dict:\n        \"\"\"Builds a dictionary of container settings to pass to the Docker API.\"\"\"\n        network_mode = configuration.get_network_mode()\n\n        container_create_kwargs = (\n            configuration.container_create_kwargs\n            if configuration.container_create_kwargs\n            else {}\n        )\n        container_create_kwargs = {\n            k: v\n            for k, v in container_create_kwargs.items()\n            if k not in configuration.__fields__\n        }\n\n        return dict(\n            image=configuration.image,\n            network=configuration.networks[0] if configuration.networks else None,\n            network_mode=network_mode,\n            command=configuration.command,\n            environment=configuration.env,\n            auto_remove=configuration.auto_remove,\n            labels=configuration.labels,\n            extra_hosts=configuration.get_extra_hosts(docker_client),\n            name=configuration.name,\n            volumes=configuration.volumes,\n            mem_limit=configuration.mem_limit,\n            memswap_limit=configuration.memswap_limit,\n            privileged=configuration.privileged,\n            **container_create_kwargs,\n        )\n\n    def _create_and_start_container(\n        self, configuration: DockerWorkerJobConfiguration\n    ) -&gt; Tuple[\"Container\", Event]:\n        \"\"\"Creates and starts a Docker container.\"\"\"\n        docker_client = self._get_client()\n        if configuration.registry_credentials:\n            self._logger.info(\"Logging into Docker registry...\")\n            docker_client.login(\n                username=configuration.registry_credentials.username,\n                password=configuration.registry_credentials.password.get_secret_value(),\n                registry=configuration.registry_credentials.registry_url,\n                reauth=configuration.registry_credentials.reauth,\n            )\n        container_settings = self._build_container_settings(\n            docker_client, configuration\n        )\n\n        if self._should_pull_image(docker_client, configuration=configuration):\n            self._logger.info(f\"Pulling image {configuration.image!r}...\")\n            self._pull_image(docker_client, configuration)\n\n        try:\n            container = self._create_container(docker_client, **container_settings)\n        except Exception as exc:\n            self._emit_container_creation_failed_event(configuration)\n            raise exc\n\n        created_event = self._emit_container_status_change_event(\n            container, configuration\n        )\n\n        # Add additional networks after the container is created; only one network can\n        # be attached at creation time\n        if len(configuration.networks) &gt; 1:\n            for network_name in configuration.networks[1:]:\n                network = docker_client.networks.get(network_name)\n                network.connect(container)\n\n        # Start the container\n        container.start()\n\n        docker_client.close()\n\n        return container, created_event\n\n    def _watch_container_safe(\n        self,\n        container: \"Container\",\n        configuration: DockerWorkerJobConfiguration,\n        created_event: Event,\n    ) -&gt; \"Container\":\n        \"\"\"Watches a container for completion, handling any errors that may occur.\"\"\"\n        # Monitor the container capturing the latest snapshot while capturing\n        # not found errors\n        docker_client = self._get_client()\n\n        try:\n            seen_statuses = {container.status}\n            last_event = created_event\n            for latest_container in self._watch_container(\n                docker_client, container.id, configuration\n            ):\n                container = latest_container\n                if container.status not in seen_statuses:\n                    seen_statuses.add(container.status)\n                    last_event = self._emit_container_status_change_event(\n                        container, configuration, last_event=last_event\n                    )\n\n        except docker.errors.NotFound:\n            # The container was removed during watching\n            self._logger.warning(\n                f\"Docker container {container.name} was removed before we could wait \"\n                \"for its completion.\"\n            )\n        finally:\n            docker_client.close()\n\n        return container\n\n    def _watch_container(\n        self,\n        docker_client: \"DockerClient\",\n        container_id: str,\n        configuration: DockerWorkerJobConfiguration,\n    ) -&gt; Generator[None, None, \"Container\"]:\n        \"\"\"\n        Watches a container for completion, yielding the latest container\n        snapshot on each iteration.\n        \"\"\"\n        container: \"Container\" = docker_client.containers.get(container_id)\n\n        status = container.status\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n        if configuration.stream_output:\n            try:\n                for log in container.logs(stream=True):\n                    log: bytes\n                    print(log.decode().rstrip())\n            except docker.errors.APIError as exc:\n                if \"marked for removal\" in str(exc):\n                    self._logger.warning(\n                        f\"Docker container {container.name} was marked for removal\"\n                        \" before logs could be retrieved. Output will not be\"\n                        \" streamed. \"\n                    )\n                else:\n                    self._logger.exception(\n                        \"An unexpected Docker API error occurred while streaming output \"\n                        f\"from container {container.name}.\"\n                    )\n\n            container.reload()\n            if container.status != status:\n                self._logger.info(\n                    f\"Docker container {container.name!r} has status\"\n                    f\" {container.status!r}\"\n                )\n            yield container\n\n        container.wait()\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n    def _should_pull_image(\n        self, docker_client: \"DockerClient\", configuration: DockerWorkerJobConfiguration\n    ) -&gt; bool:\n        \"\"\"\n        Decide whether we need to pull the Docker image.\n        \"\"\"\n        image_pull_policy = configuration._determine_image_pull_policy()\n\n        if image_pull_policy is ImagePullPolicy.ALWAYS:\n            return True\n        elif image_pull_policy is ImagePullPolicy.NEVER:\n            return False\n        elif image_pull_policy is ImagePullPolicy.IF_NOT_PRESENT:\n            try:\n                # NOTE: images.get() wants the tag included with the image\n                # name, while images.pull() wants them split.\n                docker_client.images.get(configuration.image)\n            except docker.errors.ImageNotFound:\n                self._logger.debug(\n                    f\"Could not find Docker image locally: {configuration.image}\"\n                )\n                return True\n        return False\n\n    def _pull_image(\n        self, docker_client: \"DockerClient\", configuration: DockerWorkerJobConfiguration\n    ):\n        \"\"\"\n        Pull the image we're going to use to create the container.\n        \"\"\"\n        image, tag = parse_image_tag(configuration.image)\n\n        return docker_client.images.pull(image, tag)\n\n    def _create_container(self, docker_client: \"DockerClient\", **kwargs) -&gt; \"Container\":\n        \"\"\"\n        Create a docker container with retries on name conflicts.\n\n        If the container already exists with the given name, an incremented index is\n        added.\n        \"\"\"\n        # Create the container with retries on name conflicts (with an incremented idx)\n        index = 0\n        container = None\n        name = original_name = kwargs.pop(\"name\")\n\n        while not container:\n            try:\n                display_name = repr(name) if name else \"with auto-generated name\"\n                self._logger.info(f\"Creating Docker container {display_name}...\")\n                container = docker_client.containers.create(name=name, **kwargs)\n            except docker.errors.APIError as exc:\n                if \"Conflict\" in str(exc) and \"container name\" in str(exc):\n                    self._logger.info(\n                        f\"Docker container name {display_name} already exists; \"\n                        \"retrying...\"\n                    )\n                    index += 1\n                    name = f\"{original_name}-{index}\"\n                else:\n                    raise\n\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        return container\n\n    def _container_as_resource(self, container: \"Container\") -&gt; Dict[str, str]:\n        \"\"\"Convert a container to a resource dictionary\"\"\"\n        return {\n            \"prefect.resource.id\": f\"prefect.docker.container.{container.id}\",\n            \"prefect.resource.name\": container.name,\n        }\n\n    def _emit_container_creation_failed_event(\n        self, configuration: DockerWorkerJobConfiguration\n    ) -&gt; Event:\n        \"\"\"Emit a Prefect event when a docker container fails to be created.\"\"\"\n        return emit_event(\n            event=\"prefect.docker.container.creation-failed\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(configuration=configuration),\n        )\n\n    def _emit_container_status_change_event(\n        self,\n        container: \"Container\",\n        configuration: DockerWorkerJobConfiguration,\n        last_event: Optional[Event] = None,\n    ) -&gt; Event:\n        \"\"\"Emit a Prefect event for a Docker container event.\"\"\"\n        related = self._event_related_resources(configuration=configuration)\n\n        worker_resource = self._event_resource()\n        worker_resource[\"prefect.resource.role\"] = \"worker\"\n        worker_related_resource = RelatedResource(__root__=worker_resource)\n\n        return emit_event(\n            event=f\"prefect.docker.container.{container.status.lower()}\",\n            resource=self._container_as_resource(container),\n            related=related + [worker_related_resource],\n            follows=last_event,\n        )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a container for a cancelled flow run based on the provided infrastructure PID.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: DockerWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a container for a cancelled flow run based on the provided infrastructure\n    PID.\n    \"\"\"\n    docker_client = self._get_client()\n\n    base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n    if docker_client.api.base_url != base_url:\n        raise InfrastructureNotAvailable(\n            \"\".join(\n                [\n                    (\n                        f\"Unable to stop container {container_id!r}: the current\"\n                        \" Docker API \"\n                    ),\n                    (\n                        f\"URL {docker_client.api.base_url!r} does not match the\"\n                        \" expected \"\n                    ),\n                    f\"API base URL {base_url}.\",\n                ]\n            )\n        )\n    await run_sync_in_worker_thread(\n        self._stop_container, container_id, docker_client, grace_seconds\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Docker container and waits for the flow run to complete.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: BaseJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; BaseWorkerResult:\n    \"\"\"\n    Executes a flow run within a Docker container and waits for the flow run\n    to complete.\n    \"\"\"\n    # The `docker` library uses requests instead of an async http library so it must\n    # be run in a thread to avoid blocking the event loop.\n    container, created_event = await run_sync_in_worker_thread(\n        self._create_and_start_container, configuration\n    )\n    container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n    # Mark as started and return the infrastructure id\n    if task_status:\n        task_status.started(container_pid)\n\n    # Monitor the container\n    container = await run_sync_in_worker_thread(\n        self._watch_container_safe, container, configuration, created_event\n    )\n\n    exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n    return DockerWorkerResult(\n        status_code=exit_code if exit_code is not None else -1,\n        identifier=container_pid,\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration","title":"<code>DockerWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Docker worker.</p> <p>An instance of this class is passed to the Docker worker's <code>run</code> method for each flow run. It contains all the information necessary to execute the flow run as a Docker container.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name to give to created Docker containers.</p> <code>command</code> <p>The command executed in created Docker containers to kick off flow run execution.</p> <code>env</code> <p>The environment variables to set in created Docker containers.</p> <code>labels</code> <p>The labels to set on created Docker containers.</p> <code>image</code> <code>str</code> <p>The image reference of a container image to use for created jobs. If not set, the latest Prefect image will be used.</p> <code>image_pull_policy</code> <code>Optional[Literal['IfNotPresent', 'Always', 'Never']]</code> <p>The image pull policy to use when pulling images.</p> <code>networks</code> <code>List[str]</code> <p>Docker networks that created containers should be connected to.</p> <code>network_mode</code> <code>Optional[str]</code> <p>The network mode for the created containers (e.g. host, bridge). If 'networks' is set, this cannot be set.</p> <code>auto_remove</code> <code>bool</code> <p>If set, containers will be deleted on completion.</p> <code>volumes</code> <code>List[str]</code> <p>Docker volumes that should be mounted in created containers.</p> <code>stream_output</code> <code>bool</code> <p>If set, the output from created containers will be streamed to local standard output.</p> <code>mem_limit</code> <code>Optional[str]</code> <p>Memory limit of created containers. Accepts a value with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) If a value is given without a unit, bytes are assumed.</p> <code>memswap_limit</code> <code>Optional[str]</code> <p>Total memory (memory + swap), -1 to disable swap. Should only be set if <code>mem_limit</code> is also set. If <code>mem_limit</code> is set, this defaults to allowing the container to use as much swap as memory. For example, if <code>mem_limit</code> is 300m and <code>memswap_limit</code> is not set, containers can use 600m in total of memory and swap.</p> <code>privileged</code> <code>bool</code> <p>Give extended privileges to created containers.</p> <code>container_create_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Extra args for docker py when creating container.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Docker worker.\n\n    An instance of this class is passed to the Docker worker's `run` method\n    for each flow run. It contains all the information necessary to execute the\n    flow run as a Docker container.\n\n    Attributes:\n        name: The name to give to created Docker containers.\n        command: The command executed in created Docker containers to kick off\n            flow run execution.\n        env: The environment variables to set in created Docker containers.\n        labels: The labels to set on created Docker containers.\n        image: The image reference of a container image to use for created jobs.\n            If not set, the latest Prefect image will be used.\n        image_pull_policy: The image pull policy to use when pulling images.\n        networks: Docker networks that created containers should be connected to.\n        network_mode: The network mode for the created containers (e.g. host, bridge).\n            If 'networks' is set, this cannot be set.\n        auto_remove: If set, containers will be deleted on completion.\n        volumes: Docker volumes that should be mounted in created containers.\n        stream_output: If set, the output from created containers will be streamed\n            to local standard output.\n        mem_limit: Memory limit of created containers. Accepts a value\n            with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) If a value is\n            given without a unit, bytes are assumed.\n        memswap_limit: Total memory (memory + swap), -1 to disable swap. Should only be\n            set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\n            allowing the container to use as much swap as memory. For example, if\n            `mem_limit` is 300m and `memswap_limit` is not set, containers can use\n            600m in total of memory and swap.\n        privileged: Give extended privileges to created containers.\n        container_create_kwargs: Extra args for docker py when creating container.\n    \"\"\"\n\n    image: str = Field(\n        default_factory=get_prefect_image_name,\n        description=\"The image reference of a container image to use for created jobs. \"\n        \"If not set, the latest Prefect image will be used.\",\n        example=\"docker.io/prefecthq/prefect:2-latest\",\n    )\n    registry_credentials: Optional[DockerRegistryCredentials] = Field(\n        default=None,\n        description=\"Credentials for logging into a Docker registry to pull\"\n        \" images from.\",\n    )\n    image_pull_policy: Optional[Literal[\"IfNotPresent\", \"Always\", \"Never\"]] = Field(\n        default=None,\n        description=\"The image pull policy to use when pulling images.\",\n    )\n    networks: List[str] = Field(\n        default_factory=list,\n        description=\"Docker networks that created containers should be connected to.\",\n    )\n    network_mode: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The network mode for the created containers (e.g. host, bridge). If\"\n            \" 'networks' is set, this cannot be set.\"\n        ),\n    )\n    auto_remove: bool = Field(\n        default=False,\n        description=\"If set, containers will be deleted on completion.\",\n    )\n    volumes: List[str] = Field(\n        default_factory=list,\n        description=\"A list of volume to mount into created containers.\",\n        example=[\"/my/local/path:/path/in/container\"],\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, the output from created containers will be streamed to local \"\n            \"standard output.\"\n        ),\n    )\n    mem_limit: Optional[str] = Field(\n        default=None,\n        title=\"Memory Limit\",\n        description=(\n            \"Memory limit of created containers. Accepts a value \"\n            \"with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) \"\n            \"If a value is given without a unit, bytes are assumed.\"\n        ),\n    )\n    memswap_limit: Optional[str] = Field(\n        default=None,\n        title=\"Memory Swap Limit\",\n        description=(\n            \"Total memory (memory + swap), -1 to disable swap. Should only be \"\n            \"set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\"\n            \"allowing the container to use as much swap as memory. For example, if \"\n            \"`mem_limit` is 300m and `memswap_limit` is not set, containers can use \"\n            \"600m in total of memory and swap.\"\n        ),\n    )\n    privileged: bool = Field(\n        default=False,\n        description=\"Give extended privileges to created container.\",\n    )\n    container_create_kwargs: Optional[Dict[str, Any]] = Field(\n        default=None,\n        title=\"Container Configuration\",\n        description=(\n            \"Configuration for containers created by workers. See the [`docker-py` documentation](https://docker-py.readthedocs.io/en/stable/containers.html) for accepted values.\"\n        ),\n    )\n\n    @validator(\"volumes\")\n    def _validate_volume_format(cls, volumes):\n        \"\"\"Validates that provided volume strings are in the correct format.\"\"\"\n        for volume in volumes:\n            if \":\" not in volume:\n                raise ValueError(\n                    \"Invalid volume specification. \"\n                    f\"Expected format 'path:container_path', but got {volume!r}\"\n                )\n\n        return volumes\n\n    def _convert_labels_to_docker_format(self, labels: Dict[str, str]):\n        \"\"\"Converts labels to the format expected by Docker.\"\"\"\n        labels = labels or {}\n        new_labels = {}\n        for name, value in labels.items():\n            if \"/\" in name:\n                namespace, key = name.split(\"/\", maxsplit=1)\n                new_namespace = \".\".join(reversed(namespace.split(\".\")))\n                new_labels[f\"{new_namespace}.{key}\"] = value\n            else:\n                new_labels[name] = value\n        return new_labels\n\n    def _slugify_container_name(self) -&gt; Optional[str]:\n        \"\"\"\n        Generates a container name to match the configured name, ensuring it is Docker\n        compatible.\n        \"\"\"\n        # Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+` in the end\n        if not self.name:\n            return None\n\n        return (\n            slugify(\n                self.name,\n                lowercase=False,\n                # Docker does not limit length but URL limits apply eventually so\n                # limit the length for safety\n                max_length=250,\n                # Docker allows these characters for container names\n                regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n            ).lstrip(\n                # Docker does not allow leading underscore, dash, or period\n                \"_-.\"\n            )\n            # Docker does not allow 0 character names so cast to null if the name is\n            # empty after slufification\n            or None\n        )\n\n    def _base_environment(self):\n        \"\"\"\n        If the API URL has been set update the value to ensure connectivity\n        when using a bridge network by updating local connections to use the\n        docker internal host unless the network mode is \"host\" where localhost\n        is available already.\n        \"\"\"\n\n        base_env = super()._base_environment()\n        network_mode = self.get_network_mode()\n        if (\n            \"PREFECT_API_URL\" in base_env\n            and base_env[\"PREFECT_API_URL\"] is not None\n            and network_mode != \"host\"\n        ):\n            base_env[\"PREFECT_API_URL\"] = (\n                base_env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", \"host.docker.internal\")\n                .replace(\"127.0.0.1\", \"host.docker.internal\")\n            )\n        return base_env\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the agent for a flow run by setting the image, labels, and name\n        attributes.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self.image = self.image or get_prefect_image_name()\n        self.labels = self._convert_labels_to_docker_format(\n            {**self.labels, **CONTAINER_LABELS}\n        )\n        self.name = self._slugify_container_name()\n\n    def get_network_mode(self) -&gt; Optional[str]:\n        \"\"\"\n        Returns the network mode to use for the container based on the configured\n        options and the platform.\n        \"\"\"\n        # User's value takes precedence; this may collide with the incompatible options\n        # mentioned below.\n        if self.network_mode:\n            if sys.platform != \"linux\" and self.network_mode == \"host\":\n                warnings.warn(\n                    f\"{self.network_mode!r} network mode is not supported on platform \"\n                    f\"{sys.platform!r} and may not work as intended.\"\n                )\n            return self.network_mode\n\n        # Network mode is not compatible with networks or ports (we do not support ports\n        # yet though)\n        if self.networks:\n            return None\n\n        # Check for a local API connection\n        api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n        if api_url:\n            try:\n                _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n            except Exception as exc:\n                warnings.warn(\n                    f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                    f\"{exc}\\nThe network mode will not be inferred.\"\n                )\n                return None\n\n            host = netloc.split(\":\")[0]\n\n            # If using a locally hosted API, use a host network on linux\n            if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n                return \"host\"\n\n        # Default to unset\n        return None\n\n    def get_extra_hosts(self, docker_client) -&gt; Optional[Dict[str, str]]:\n        \"\"\"\n        A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n        with the API on Linux machines. Docker Desktop on macOS will automatically\n        already have this mapping.\n        \"\"\"\n        if sys.platform == \"linux\" and (\n            # Do not warn if the user has specified a host manually that does not use\n            # a local address\n            \"PREFECT_API_URL\" not in self.env\n            or re.search(\n                \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n                self.env[\"PREFECT_API_URL\"],\n            )\n        ):\n            user_version = packaging.version.parse(\n                format_outlier_version_name(docker_client.version()[\"Version\"])\n            )\n            required_version = packaging.version.parse(\"20.10.0\")\n\n            if user_version &lt; required_version:\n                warnings.warn(\n                    \"`host.docker.internal` could not be automatically resolved to\"\n                    \" your local ip address. This feature is not supported on Docker\"\n                    f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                    \" encounter issues.\"\n                )\n                return {}\n            else:\n                # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n                # Only supported by Docker v20.10.0+ which is our minimum recommend\n                # version\n                return {\"host.docker.internal\": \"host-gateway\"}\n\n    def _determine_image_pull_policy(self) -&gt; ImagePullPolicy:\n        \"\"\"\n        Determine the appropriate image pull policy.\n\n        1. If they specified an image pull policy, use that.\n\n        2. If they did not specify an image pull policy and gave us\n           the \"latest\" tag, use ImagePullPolicy.always.\n\n        3. If they did not specify an image pull policy and did not\n           specify a tag, use ImagePullPolicy.always.\n\n        4. If they did not specify an image pull policy and gave us\n           a tag other than \"latest\", use ImagePullPolicy.if_not_present.\n\n        This logic matches the behavior of Kubernetes.\n        See:https://kubernetes.io/docs/concepts/containers/images/#imagepullpolicy-defaulting\n        \"\"\"\n        if not self.image_pull_policy:\n            _, tag = parse_image_tag(self.image)\n            if tag == \"latest\" or not tag:\n                return ImagePullPolicy.ALWAYS\n            return ImagePullPolicy.IF_NOT_PRESENT\n        return ImagePullPolicy(self.image_pull_policy)\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.get_extra_hosts","title":"<code>get_extra_hosts</code>","text":"<p>A host.docker.internal -&gt; host-gateway mapping is necessary for communicating with the API on Linux machines. Docker Desktop on macOS will automatically already have this mapping.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def get_extra_hosts(self, docker_client) -&gt; Optional[Dict[str, str]]:\n    \"\"\"\n    A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n    with the API on Linux machines. Docker Desktop on macOS will automatically\n    already have this mapping.\n    \"\"\"\n    if sys.platform == \"linux\" and (\n        # Do not warn if the user has specified a host manually that does not use\n        # a local address\n        \"PREFECT_API_URL\" not in self.env\n        or re.search(\n            \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n            self.env[\"PREFECT_API_URL\"],\n        )\n    ):\n        user_version = packaging.version.parse(\n            format_outlier_version_name(docker_client.version()[\"Version\"])\n        )\n        required_version = packaging.version.parse(\"20.10.0\")\n\n        if user_version &lt; required_version:\n            warnings.warn(\n                \"`host.docker.internal` could not be automatically resolved to\"\n                \" your local ip address. This feature is not supported on Docker\"\n                f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                \" encounter issues.\"\n            )\n            return {}\n        else:\n            # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n            # Only supported by Docker v20.10.0+ which is our minimum recommend\n            # version\n            return {\"host.docker.internal\": \"host-gateway\"}\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.get_network_mode","title":"<code>get_network_mode</code>","text":"<p>Returns the network mode to use for the container based on the configured options and the platform.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def get_network_mode(self) -&gt; Optional[str]:\n    \"\"\"\n    Returns the network mode to use for the container based on the configured\n    options and the platform.\n    \"\"\"\n    # User's value takes precedence; this may collide with the incompatible options\n    # mentioned below.\n    if self.network_mode:\n        if sys.platform != \"linux\" and self.network_mode == \"host\":\n            warnings.warn(\n                f\"{self.network_mode!r} network mode is not supported on platform \"\n                f\"{sys.platform!r} and may not work as intended.\"\n            )\n        return self.network_mode\n\n    # Network mode is not compatible with networks or ports (we do not support ports\n    # yet though)\n    if self.networks:\n        return None\n\n    # Check for a local API connection\n    api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n    if api_url:\n        try:\n            _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n        except Exception as exc:\n            warnings.warn(\n                f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                f\"{exc}\\nThe network mode will not be inferred.\"\n            )\n            return None\n\n        host = netloc.split(\":\")[0]\n\n        # If using a locally hosted API, use a host network on linux\n        if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n            return \"host\"\n\n    # Default to unset\n    return None\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the agent for a flow run by setting the image, labels, and name attributes.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the agent for a flow run by setting the image, labels, and name\n    attributes.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    self.image = self.image or get_prefect_image_name()\n    self.labels = self._convert_labels_to_docker_format(\n        {**self.labels, **CONTAINER_LABELS}\n    )\n    self.name = self._slugify_container_name()\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerResult","title":"<code>DockerWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about a completed Docker container</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about a completed Docker container\"\"\"\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.ImagePullPolicy","title":"<code>ImagePullPolicy</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing the image pull policy options for a Docker container.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class ImagePullPolicy(enum.Enum):\n    \"\"\"Enum representing the image pull policy options for a Docker container.\"\"\"\n\n    IF_NOT_PRESENT = \"IfNotPresent\"\n    ALWAYS = \"Always\"\n    NEVER = \"Never\"\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps","title":"<code>prefect_docker.deployments.steps</code>","text":"<p>Prefect deployment steps for building and pushing Docker images.</p> <p>These steps can be used in a <code>prefect.yaml</code> file to define the default build steps for a group of deployments, or they can be used to define the build step for a specific deployment.</p> <p>Example</p> <p>Build a Docker image before deploying a flow: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n</code></pre></p>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.BuildDockerImageResult","title":"<code>BuildDockerImageResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>build_docker_image</code> step.</p> <p>Attributes:</p> Name Type Description <code>image_name</code> <code>str</code> <p>The name of the built image.</p> <code>tag</code> <code>str</code> <p>The tag of the built image.</p> <code>image</code> <code>str</code> <p>The name and tag of the built image.</p> <code>image_id</code> <code>str</code> <p>The ID of the built image.</p> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>The additional tags on the image, in addition to <code>tag</code>.</p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>class BuildDockerImageResult(TypedDict):\n    \"\"\"\n    The result of a `build_docker_image` step.\n\n    Attributes:\n        image_name: The name of the built image.\n        tag: The tag of the built image.\n        image: The name and tag of the built image.\n        image_id: The ID of the built image.\n        additional_tags: The additional tags on the image, in addition to `tag`.\n    \"\"\"\n\n    image_name: str\n    tag: str\n    image: str\n    image_id: str\n    additional_tags: Optional[List[str]]\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.PushDockerImageResult","title":"<code>PushDockerImageResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>push_docker_image</code> step.</p> <p>Attributes:</p> Name Type Description <code>image_name</code> <code>str</code> <p>The name of the pushed image.</p> <code>tag</code> <code>Optional[str]</code> <p>The tag of the pushed image.</p> <code>image</code> <code>str</code> <p>The name and tag of the pushed image.</p> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>The additional tags on the image, in addition to <code>tag</code>.</p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>class PushDockerImageResult(TypedDict):\n    \"\"\"\n    The result of a `push_docker_image` step.\n\n    Attributes:\n        image_name: The name of the pushed image.\n        tag: The tag of the pushed image.\n        image: The name and tag of the pushed image.\n        additional_tags: The additional tags on the image, in addition to `tag`.\n    \"\"\"\n\n    image_name: str\n    tag: Optional[str]\n    image: str\n    additional_tags: Optional[List[str]]\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.build_docker_image","title":"<code>build_docker_image</code>","text":"<p>Builds a Docker image for a Prefect deployment.</p> <p>Can be used within a <code>prefect.yaml</code> file to build a Docker image prior to creating or updating a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>image_name</code> <code>str</code> <p>The name of the Docker image to build, including the registry and repository.</p> required <code>dockerfile</code> <code>str</code> <p>The path to the Dockerfile used to build the image. If \"auto\" is passed, a temporary Dockerfile will be created to build the image.</p> <code>'Dockerfile'</code> <code>tag</code> <code>Optional[str]</code> <p>The tag to apply to the built image.</p> <code>None</code> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>Additional tags on the image, in addition to <code>tag</code>, to apply to the built image.</p> <code>None</code> <code>**build_kwargs</code> <p>Additional keyword arguments to pass to Docker when building the image. Available options can be found in the <code>docker-py</code> documentation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BuildDockerImageResult</code> <p>A dictionary containing the image name and tag of the built image.</p> Example <p>Build a Docker image prior to creating a deployment: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n</code></pre></p> <p>Build a Docker image with multiple tags: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        additional_tags:\n            - v0.1.0,\n            - dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n</code></pre></p> <p>Build a Docker image using an auto-generated Dockerfile: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n</code></pre></p> <p>Build a Docker image for a different platform: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: Dockerfile\n        platform: amd64\n</code></pre></p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>@cacheable\ndef build_docker_image(\n    image_name: str,\n    dockerfile: str = \"Dockerfile\",\n    tag: Optional[str] = None,\n    additional_tags: Optional[List[str]] = None,\n    ignore_cache: bool = False,\n    **build_kwargs,\n) -&gt; BuildDockerImageResult:\n    \"\"\"\n    Builds a Docker image for a Prefect deployment.\n\n    Can be used within a `prefect.yaml` file to build a Docker\n    image prior to creating or updating a deployment.\n\n    Args:\n        image_name: The name of the Docker image to build, including the registry and\n            repository.\n        dockerfile: The path to the Dockerfile used to build the image. If \"auto\" is\n            passed, a temporary Dockerfile will be created to build the image.\n        tag: The tag to apply to the built image.\n        additional_tags: Additional tags on the image, in addition to `tag`, to apply to the built image.\n        **build_kwargs: Additional keyword arguments to pass to Docker when building\n            the image. Available options can be found in the [`docker-py`](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build)\n            documentation.\n\n    Returns:\n        A dictionary containing the image name and tag of the\n            built image.\n\n    Example:\n        Build a Docker image prior to creating a deployment:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n        ```\n\n        Build a Docker image with multiple tags:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                additional_tags:\n                    - v0.1.0,\n                    - dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n        ```\n\n        Build a Docker image using an auto-generated Dockerfile:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n        ```\n\n\n        Build a Docker image for a different platform:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: Dockerfile\n                platform: amd64\n        ```\n    \"\"\"  # noqa\n    auto_build = dockerfile == \"auto\"\n    if auto_build:\n        lines = []\n        base_image = get_prefect_image_name()\n        lines.append(f\"FROM {base_image}\")\n        dir_name = os.path.basename(os.getcwd())\n\n        if Path(\"requirements.txt\").exists():\n            lines.append(\n                f\"COPY requirements.txt /opt/prefect/{dir_name}/requirements.txt\"\n            )\n            lines.append(\n                f\"RUN python -m pip install -r /opt/prefect/{dir_name}/requirements.txt\"\n            )\n\n        lines.append(f\"COPY . /opt/prefect/{dir_name}/\")\n        lines.append(f\"WORKDIR /opt/prefect/{dir_name}/\")\n\n        temp_dockerfile = Path(\"Dockerfile\")\n        if Path(temp_dockerfile).exists():\n            raise ValueError(\"Dockerfile already exists.\")\n\n        with Path(temp_dockerfile).open(\"w\") as f:\n            f.writelines(line + \"\\n\" for line in lines)\n\n        dockerfile = str(temp_dockerfile)\n\n    build_kwargs[\"path\"] = build_kwargs.get(\"path\", os.getcwd())\n    build_kwargs[\"dockerfile\"] = dockerfile\n    build_kwargs[\"pull\"] = build_kwargs.get(\"pull\", True)\n    build_kwargs[\"decode\"] = True\n    build_kwargs[\"labels\"] = {**build_kwargs.get(\"labels\", {}), **IMAGE_LABELS}\n    image_id = None\n\n    with docker_client() as client:\n        try:\n            events = client.api.build(**build_kwargs)\n\n            try:\n                for event in events:\n                    if \"stream\" in event:\n                        sys.stdout.write(event[\"stream\"])\n                        sys.stdout.flush()\n                    elif \"aux\" in event:\n                        image_id = event[\"aux\"][\"ID\"]\n                    elif \"error\" in event:\n                        raise BuildError(event[\"error\"])\n                    elif \"message\" in event:\n                        raise BuildError(event[\"message\"])\n            except docker.errors.APIError as e:\n                raise BuildError(e.explanation) from e\n\n        finally:\n            if auto_build:\n                os.unlink(dockerfile)\n\n        if not isinstance(image_id, str):\n            raise BuildError(\"Docker did not return an image ID for built image.\")\n\n        if not tag:\n            tag = slugify(pendulum.now(\"utc\").isoformat())\n\n        image: Image = client.images.get(image_id)\n        image.tag(repository=image_name, tag=tag)\n\n        additional_tags = additional_tags or []\n        for tag_ in additional_tags:\n            image.tag(repository=image_name, tag=tag_)\n\n    return {\n        \"image_name\": image_name,\n        \"tag\": tag,\n        \"image\": f\"{image_name}:{tag}\",\n        \"image_id\": image_id,\n        \"additional_tags\": additional_tags,\n    }\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.push_docker_image","title":"<code>push_docker_image</code>","text":"<p>Push a Docker image to a remote registry.</p> <p>Parameters:</p> Name Type Description Default <code>image_name</code> <code>str</code> <p>The name of the Docker image to push, including the registry and repository.</p> required <code>tag</code> <code>Optional[str]</code> <p>The tag of the Docker image to push.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the username, password, and URL for the registry to push the image to.</p> <code>None</code> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>Additional tags on the image, in addition to <code>tag</code>, to apply to the built image.</p> <code>None</code> <p>Returns:</p> Type Description <code>PushDockerImageResult</code> <p>A dictionary containing the image name and tag of the pushed image.</p> <p>Examples:</p> <p>Build and push a Docker image to a private repository: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n        credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n</code></pre></p> <p>Build and push a Docker image to a private repository with multiple tags <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n        additional_tags: [\n            v0.1.0,\n            dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n        ]\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n        credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n        additional_tags: \"{{ build-image.additional_tags }}\"\n</code></pre></p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>@cacheable\ndef push_docker_image(\n    image_name: str,\n    tag: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n    additional_tags: Optional[List[str]] = None,\n    ignore_cache: bool = False,\n) -&gt; PushDockerImageResult:\n    \"\"\"\n    Push a Docker image to a remote registry.\n\n    Args:\n        image_name: The name of the Docker image to push, including the registry and\n            repository.\n        tag: The tag of the Docker image to push.\n        credentials: A dictionary containing the username, password, and URL for the\n            registry to push the image to.\n        additional_tags: Additional tags on the image, in addition to `tag`, to apply to the built image.\n\n    Returns:\n        A dictionary containing the image name and tag of the\n            pushed image.\n\n    Examples:\n        Build and push a Docker image to a private repository:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                id: build-image\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n\n        push:\n            - prefect_docker.deployments.steps.push_docker_image:\n                requires: prefect-docker\n                image_name: \"{{ build-image.image_name }}\"\n                tag: \"{{ build-image.tag }}\"\n                credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n        ```\n\n        Build and push a Docker image to a private repository with multiple tags\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                id: build-image\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n                additional_tags: [\n                    v0.1.0,\n                    dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n                ]\n\n        push:\n            - prefect_docker.deployments.steps.push_docker_image:\n                requires: prefect-docker\n                image_name: \"{{ build-image.image_name }}\"\n                tag: \"{{ build-image.tag }}\"\n                credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n                additional_tags: \"{{ build-image.additional_tags }}\"\n        ```\n    \"\"\"  # noqa\n    with docker_client() as client:\n        if credentials is not None:\n            client.login(\n                username=credentials.get(\"username\"),\n                password=credentials.get(\"password\"),\n                registry=credentials.get(\"registry_url\"),\n                reauth=credentials.get(\"reauth\", True),\n            )\n        events = list(\n            client.api.push(repository=image_name, tag=tag, stream=True, decode=True)\n        )\n        additional_tags = additional_tags or []\n        for i, tag_ in enumerate(additional_tags):\n            event = list(\n                client.api.push(\n                    repository=image_name, tag=tag_, stream=True, decode=True\n                )\n            )\n            events = events + event\n\n        for event in events:\n            if \"status\" in event:\n                sys.stdout.write(event[\"status\"])\n                if \"progress\" in event:\n                    sys.stdout.write(\" \" + event[\"progress\"])\n                sys.stdout.write(\"\\n\")\n                sys.stdout.flush()\n            elif \"error\" in event:\n                raise OSError(event[\"error\"])\n\n    return {\n        \"image_name\": image_name,\n        \"tag\": tag,\n        \"image\": f\"{image_name}:{tag}\",\n        \"additional_tags\": additional_tags,\n    }\n</code></pre>"},{"location":"integrations/prefect-email/","title":"prefect-email","text":"<p>The <code>prefect-email</code> library helps you send emails from your Prefect flows.</p>"},{"location":"integrations/prefect-email/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-email/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Many email services, such as Gmail, require an App Password to successfully send emails.     If you encounter an error similar to <code>smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted...</code>, it's likely you are not using an App Password.</li> </ul>"},{"location":"integrations/prefect-email/#install-prefect-email","title":"Install prefect-email","text":"<pre><code>pip install -U prefect-email\n</code></pre>"},{"location":"integrations/prefect-email/#register-newly-installed-blocks-types","title":"Register newly installed blocks types","text":"<p>Register the block types in the prefect-email module to make them available for use.</p> <pre><code>prefect block register -m prefect_email\n</code></pre>"},{"location":"integrations/prefect-email/#save-credentials-to-an-emailservercredentials-block","title":"Save credentials to an EmailServerCredentials block","text":"<p>Save your email credentials to a block. Replace the placeholders with your email address and password.</p> <pre><code>from prefect_email import EmailServerCredentials\n\ncredentials = EmailServerCredentials(\n    username=\"EMAIL-ADDRESS-PLACEHOLDER\",\n    password=\"PASSWORD-PLACEHOLDER\",  # must be an app password\n)\ncredentials.save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>In the examples below you load a credentials block to authenticate with the email server.</p>"},{"location":"integrations/prefect-email/#send-emails","title":"Send emails","text":"<p>The code below shows how to send an email using the pre-built <code>email_send_message</code> task.</p> <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials, email_send_message\n\n@flow\ndef example_email_send_message_flow(email_addresses):\n    email_server_credentials = EmailServerCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    for email_address in email_addresses:\n        subject = email_send_message.with_options(name=f\"email {email_address}\").submit(\n            email_server_credentials=email_server_credentials,\n            subject=\"Example Flow Notification using Gmail\",\n            msg=\"This proves email_send_message works!\",\n            email_to=email_address,\n        )\n\nif __name__ == \"__main__\":\n    example_email_send_message_flow([\"EMAIL-ADDRESS-PLACEHOLDER\"])\n</code></pre>"},{"location":"integrations/prefect-email/#capture-exceptions-and-send-an-email","title":"Capture exceptions and send an email","text":"<p>This example demonstrates how to send an email notification with the details of the exception when a flow run fails.</p> <p><code>prefect-email</code> can be wrapped in an <code>except</code> statement to do just that!</p> <pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_email import EmailServerCredentials, email_send_message\n\ndef notify_exc_by_email(exc):\n    context = get_run_context()\n    flow_run_name = context.flow_run.name\n    email_server_credentials = EmailServerCredentials.load(\"email-server-credentials\")\n    email_send_message(\n        email_server_credentials=email_server_credentials,\n        subject=f\"Flow run {flow_run_name!r} failed\",\n        msg=f\"Flow run {flow_run_name!r} failed due to {exc}.\",\n        email_to=email_server_credentials.username,\n    )\n\n@flow\ndef example_flow():\n    try:\n        1 / 0\n    except Exception as exc:\n        notify_exc_by_email(exc)\n        raise\n\nif __name__ == \"__main__\":\n    example_flow()\n</code></pre>"},{"location":"integrations/prefect-email/#resources","title":"Resources","text":"<p>Refer to the prefect-email API documentation linked in the sidebar to explore all the capabilities of the prefect-email library.</p>"},{"location":"integrations/prefect-email/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials","title":"<code>prefect_email.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with email services</p>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials","title":"<code>EmailServerCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage generic email server authentication. It is recommended you use a Google App Password if you use Gmail.</p> <p>Attributes:</p> Name Type Description <code>username</code> <code>Optional[str]</code> <p>The username to use for authentication to the server. Unnecessary if SMTP login is not required.</p> <code>password</code> <code>SecretStr</code> <p>The password to use for authentication to the server. Unnecessary if SMTP login is not required.</p> <code>smtp_server</code> <code>Union[SMTPServer, str]</code> <p>Either the hostname of the SMTP server, or one of the keys from the built-in SMTPServer Enum members, like \"gmail\".</p> <code>smtp_type</code> <code>Union[SMTPType, str]</code> <p>Either \"SSL\", \"STARTTLS\", or \"INSECURE\".</p> <code>smtp_port</code> <code>Optional[int]</code> <p>If provided, overrides the smtp_type's default port number.</p> Example <p>Load stored email server credentials: <pre><code>from prefect_email import EmailServerCredentials\nemail_credentials_block = EmailServerCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class EmailServerCredentials(Block):\n    \"\"\"\n    Block used to manage generic email server authentication.\n    It is recommended you use a\n    [Google App Password](https://support.google.com/accounts/answer/185833)\n    if you use Gmail.\n\n    Attributes:\n        username: The username to use for authentication to the server.\n            Unnecessary if SMTP login is not required.\n        password: The password to use for authentication to the server.\n            Unnecessary if SMTP login is not required.\n        smtp_server: Either the hostname of the SMTP server, or one of the\n            keys from the built-in SMTPServer Enum members, like \"gmail\".\n        smtp_type: Either \"SSL\", \"STARTTLS\", or \"INSECURE\".\n        smtp_port: If provided, overrides the smtp_type's default port number.\n\n    Example:\n        Load stored email server credentials:\n        ```python\n        from prefect_email import EmailServerCredentials\n        email_credentials_block = EmailServerCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Email Server Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/82bc6ed16ca42a2252a5512c72233a253b8a58eb-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials\"  # noqa\n\n    username: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The username to use for authentication to the server. \"\n            \"Unnecessary if SMTP login is not required.\"\n        ),\n    )\n    password: SecretStr = Field(\n        default_factory=partial(SecretStr, \"\"),\n        description=(\n            \"The password to use for authentication to the server. \"\n            \"Unnecessary if SMTP login is not required.\"\n        ),\n    )\n    smtp_server: Union[SMTPServer, str] = Field(\n        default=SMTPServer.GMAIL,\n        description=(\n            \"Either the hostname of the SMTP server, or one of the \"\n            \"keys from the built-in SMTPServer Enum members, like 'gmail'.\"\n        ),\n        title=\"SMTP Server\",\n    )\n    smtp_type: Union[SMTPType, str] = Field(\n        default=SMTPType.SSL,\n        description=(\"Either 'SSL', 'STARTTLS', or 'INSECURE'.\"),\n        title=\"SMTP Type\",\n    )\n    smtp_port: Optional[int] = Field(\n        default=None,\n        description=(\"If provided, overrides the smtp_type's default port number.\"),\n        title=\"SMTP Port\",\n    )\n\n    @validator(\"smtp_server\", pre=True)\n    def _cast_smtp_server(cls, value):\n        \"\"\"\n        Cast the smtp_server to an SMTPServer Enum member, if valid.\n        \"\"\"\n        return _cast_to_enum(value, SMTPServer)\n\n    @validator(\"smtp_type\", pre=True)\n    def _cast_smtp_type(cls, value):\n        \"\"\"\n        Cast the smtp_type to an SMTPType Enum member, if valid.\n        \"\"\"\n        if isinstance(value, int):\n            return SMTPType(value)\n        return _cast_to_enum(value, SMTPType, restrict=True)\n\n    def get_server(self) -&gt; SMTP:\n        \"\"\"\n        Gets an authenticated SMTP server.\n\n        Returns:\n            SMTP: An authenticated SMTP server.\n\n        Example:\n            Gets a GMail SMTP server through defaults.\n            ```python\n            from prefect import flow\n            from prefect_email import EmailServerCredentials\n\n            @flow\n            def example_get_server_flow():\n                email_server_credentials = EmailServerCredentials(\n                    username=\"username@gmail.com\",\n                    password=\"password\",\n                )\n                server = email_server_credentials.get_server()\n                return server\n\n            example_get_server_flow()\n            ```\n        \"\"\"\n        smtp_server = self.smtp_server\n        if isinstance(smtp_server, SMTPServer):\n            smtp_server = smtp_server.value\n\n        smtp_type = self.smtp_type\n        smtp_port = self.smtp_port\n        if smtp_port is None:\n            smtp_port = smtp_type.value\n\n        if smtp_type == SMTPType.INSECURE:\n            server = SMTP(smtp_server, smtp_port)\n        else:\n            context = ssl.create_default_context()\n            if smtp_type == SMTPType.SSL:\n                server = SMTP_SSL(smtp_server, smtp_port, context=context)\n            elif smtp_type == SMTPType.STARTTLS:\n                server = SMTP(smtp_server, smtp_port)\n                server.starttls(context=context)\n            if self.username is not None:\n                server.login(self.username, self.password.get_secret_value())\n\n        return server\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials.get_server","title":"<code>get_server</code>","text":"<p>Gets an authenticated SMTP server.</p> <p>Returns:</p> Name Type Description <code>SMTP</code> <code>SMTP</code> <p>An authenticated SMTP server.</p> Example <p>Gets a GMail SMTP server through defaults. <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials\n\n@flow\ndef example_get_server_flow():\n    email_server_credentials = EmailServerCredentials(\n        username=\"username@gmail.com\",\n        password=\"password\",\n    )\n    server = email_server_credentials.get_server()\n    return server\n\nexample_get_server_flow()\n</code></pre></p> Source code in <code>prefect_email/credentials.py</code> <pre><code>def get_server(self) -&gt; SMTP:\n    \"\"\"\n    Gets an authenticated SMTP server.\n\n    Returns:\n        SMTP: An authenticated SMTP server.\n\n    Example:\n        Gets a GMail SMTP server through defaults.\n        ```python\n        from prefect import flow\n        from prefect_email import EmailServerCredentials\n\n        @flow\n        def example_get_server_flow():\n            email_server_credentials = EmailServerCredentials(\n                username=\"username@gmail.com\",\n                password=\"password\",\n            )\n            server = email_server_credentials.get_server()\n            return server\n\n        example_get_server_flow()\n        ```\n    \"\"\"\n    smtp_server = self.smtp_server\n    if isinstance(smtp_server, SMTPServer):\n        smtp_server = smtp_server.value\n\n    smtp_type = self.smtp_type\n    smtp_port = self.smtp_port\n    if smtp_port is None:\n        smtp_port = smtp_type.value\n\n    if smtp_type == SMTPType.INSECURE:\n        server = SMTP(smtp_server, smtp_port)\n    else:\n        context = ssl.create_default_context()\n        if smtp_type == SMTPType.SSL:\n            server = SMTP_SSL(smtp_server, smtp_port, context=context)\n        elif smtp_type == SMTPType.STARTTLS:\n            server = SMTP(smtp_server, smtp_port)\n            server.starttls(context=context)\n        if self.username is not None:\n            server.login(self.username, self.password.get_secret_value())\n\n    return server\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.SMTPServer","title":"<code>SMTPServer</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Server used to send email.</p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class SMTPServer(Enum):\n    \"\"\"\n    Server used to send email.\n    \"\"\"\n\n    AOL = \"smtp.aol.com\"\n    ATT = \"smtp.mail.att.net\"\n    COMCAST = \"smtp.comcast.net\"\n    ICLOUD = \"smtp.mail.me.com\"\n    GMAIL = \"smtp.gmail.com\"\n    OUTLOOK = \"smtp-mail.outlook.com\"\n    YAHOO = \"smtp.mail.yahoo.com\"\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.SMTPType","title":"<code>SMTPType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Protocols used to secure email transmissions.</p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class SMTPType(Enum):\n    \"\"\"\n    Protocols used to secure email transmissions.\n    \"\"\"\n\n    SSL = 465\n    STARTTLS = 587\n    INSECURE = 25\n</code></pre>"},{"location":"integrations/prefect-email/message/","title":"Message","text":""},{"location":"integrations/prefect-email/message/#prefect_email.message","title":"<code>prefect_email.message</code>","text":"<p>Tasks for interacting with email message services</p>"},{"location":"integrations/prefect-email/message/#prefect_email.message.email_send_message","title":"<code>email_send_message</code>  <code>async</code>","text":"<p>Sends an email message from an authenticated email service over SMTP. Sending messages containing HTML code is supported - the default MIME type is set to the text/html.</p> <p>Parameters:</p> Name Type Description Default <code>subject</code> <code>str</code> <p>The subject line of the email.</p> required <code>msg</code> <code>str</code> <p>The contents of the email, added as html; can be used in combination with msg_plain.</p> required <code>msg_plain</code> <code>Optional[str]</code> <p>The contents of the email as plain text, can be used in combination with msg.</p> <code>None</code> <code>email_to</code> <code>Optional[Union[str, List[str]]]</code> <p>The email addresses to send the message to, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>email_to_cc</code> <code>Optional[Union[str, List[str]]]</code> <p>Additional email addresses to send the message to as cc, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>email_to_bcc</code> <code>Optional[Union[str, List[str]]]</code> <p>Additional email addresses to send the message to as bcc, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>attachments</code> <code>Optional[List[str]]</code> <p>Names of files that should be sent as attachment.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>MimeText</code> <p>The MIME Multipart message of the email.</p> Example <p>Sends a notification email to someone@gmail.com. <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials, email_send_message\n\n@flow\ndef example_email_send_message_flow():\n    email_server_credentials = EmailServerCredentials(\n        username=\"username@email.com\",\n        password=\"password\",\n    )\n    subject = email_send_message(\n        email_server_credentials=email_server_credentials,\n        subject=\"Example Flow Notification\",\n        msg=\"This proves email_send_message works!\",\n        email_to=\"someone@email.com\",\n    )\n    return subject\n\nexample_email_send_message_flow()\n</code></pre></p> Source code in <code>prefect_email/message.py</code> <pre><code>@task\nasync def email_send_message(\n    subject: str,\n    msg: str,\n    email_server_credentials: \"EmailServerCredentials\",\n    msg_plain: Optional[str] = None,\n    email_from: Optional[str] = None,\n    email_to: Optional[Union[str, List[str]]] = None,\n    email_to_cc: Optional[Union[str, List[str]]] = None,\n    email_to_bcc: Optional[Union[str, List[str]]] = None,\n    attachments: Optional[List[str]] = None,\n):\n    \"\"\"\n    Sends an email message from an authenticated email service over SMTP.\n    Sending messages containing HTML code is supported - the default MIME\n    type is set to the text/html.\n\n    Args:\n        subject: The subject line of the email.\n        msg: The contents of the email, added as html; can be used in\n            combination with msg_plain.\n        msg_plain: The contents of the email as plain text,\n            can be used in combination with msg.\n        email_to: The email addresses to send the message to, separated by commas.\n            If a list is provided, will join the items, separated by commas.\n        email_to_cc: Additional email addresses to send the message to as cc,\n            separated by commas. If a list is provided, will join the items,\n            separated by commas.\n        email_to_bcc: Additional email addresses to send the message to as bcc,\n            separated by commas. If a list is provided, will join the items,\n            separated by commas.\n        attachments: Names of files that should be sent as attachment.\n\n    Returns:\n        MimeText: The MIME Multipart message of the email.\n\n    Example:\n        Sends a notification email to someone@gmail.com.\n        ```python\n        from prefect import flow\n        from prefect_email import EmailServerCredentials, email_send_message\n\n        @flow\n        def example_email_send_message_flow():\n            email_server_credentials = EmailServerCredentials(\n                username=\"username@email.com\",\n                password=\"password\",\n            )\n            subject = email_send_message(\n                email_server_credentials=email_server_credentials,\n                subject=\"Example Flow Notification\",\n                msg=\"This proves email_send_message works!\",\n                email_to=\"someone@email.com\",\n            )\n            return subject\n\n        example_email_send_message_flow()\n        ```\n    \"\"\"\n    message = MIMEMultipart()\n    message[\"Subject\"] = subject\n    message[\"From\"] = email_from or email_server_credentials.username\n\n    email_to_dict = {\"To\": email_to, \"Cc\": email_to_cc, \"Bcc\": email_to_bcc}\n    if all(val is None for val in email_to_dict.values()):\n        raise ValueError(\n            \"One of email_to, email_to_cc, or email_to_bcc must be specified\"\n        )\n\n    for key, val in email_to_dict.items():\n        if isinstance(val, list):\n            val = \", \".join(val)\n        message[key] = val\n\n    # First add the message in plain text, then the HTML version;\n    # email clients try to render the last part first\n    if msg_plain:\n        message.attach(MIMEText(msg_plain, \"plain\"))\n    if msg:\n        message.attach(MIMEText(msg, \"html\"))\n\n    for filepath in attachments or []:\n        with open(filepath, \"rb\") as attachment:\n            part = MIMEBase(\"application\", \"octet-stream\")\n            part.set_payload(attachment.read())\n\n        encoders.encode_base64(part)\n        filename = os.path.basename(filepath)\n        part.add_header(\n            \"Content-Disposition\",\n            f\"attachment; filename= {filename}\",\n        )\n        message.attach(part)\n\n    with email_server_credentials.get_server() as server:\n        partial_send_message = partial(server.send_message, message)\n        await to_thread.run_sync(partial_send_message)\n\n    return message\n</code></pre>"},{"location":"integrations/prefect-gcp/","title":"<code>prefect-gcp</code>","text":"<p><code>prefect-gcp</code> helps you leverage the capabilities of Google Cloud Platform (GCP) in your workflows. For example, you can run flow on Vertex AI or Cloud Run, read and write data to BigQuery and Cloud Storage, retrieve secrets with Secret Manager.</p>"},{"location":"integrations/prefect-gcp/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-gcp/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>An GCP account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-gcp/#install-prefect-gcp","title":"Install prefect-gcp","text":"<pre><code>pip install -U prefect-gcp\n</code></pre> <p>If using BigQuery, Cloud Storage, Secret Manager, or Vertex AI, see additional installation options.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-gcp[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the module to make them available for use.</p> <pre><code>prefect block register -m prefect_gcp\n</code></pre>"},{"location":"integrations/prefect-gcp/#authenticate-using-a-gcp-credentials-block","title":"Authenticate using a GCP Credentials block","text":"<p>Authenticate with a service account to use <code>prefect-gcp</code> services.</p> <ol> <li>Refer to the GCP service account documentation to create and download a service account key file.</li> <li>Copy the JSON contents.</li> <li>Use the Python code below, replace the placeholders with your information.</li> </ol> <pre><code>from prefect_gcp import GcpCredentials\n\n# replace this PLACEHOLDER dict with your own service account info\nservice_account_info = {\n  \"type\": \"service_account\",\n  \"project_id\": \"PROJECT_ID\",\n  \"private_key_id\": \"KEY_ID\",\n  \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nPRIVATE_KEY\\n-----END PRIVATE KEY-----\\n\",\n  \"client_email\": \"SERVICE_ACCOUNT_EMAIL\",\n  \"client_id\": \"CLIENT_ID\",\n  \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n  \"token_uri\": \"https://accounts.google.com/o/oauth2/token\",\n  \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n  \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL\"\n}\n\nGcpCredentials(\n    service_account_info=service_account_info\n).save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p><code>service_account_info</code> vs <code>service_account_file</code></p> <p>The advantage of using <code>service_account_info</code>, instead of <code>service_account_file</code>, is that it is accessible across containers.</p> <p>If <code>service_account_file</code> is used, the provided file path must be available in the container executing the flow.</p> <p>Alternatively, GCP can authenticate without storing credentials in a block. See the Third-pary Screts Guide for an analogous example that uses AWS Secrets Manager and Snowflake.</p>"},{"location":"integrations/prefect-gcp/#run-flows-on-google-cloud-run-or-vertex-ai","title":"Run flows on Google Cloud Run or Vertex AI","text":"<p>Run flows on Google Cloud Run or Vertex AI to dynamically scale your infrastructure.</p> <p>See the Google Cloud Run Worker Guide for a walkthrough of using Google Cloud Run to run workflows with a hybrid work pool.</p> <p>If you're using Prefect Cloud, Google Cloud Run push work pools provide all the benefits of Google Cloud Run along with a quick setup and no worker needed.</p>"},{"location":"integrations/prefect-gcp/#use-prefect-with-google-bigquery","title":"Use Prefect with Google BigQuery","text":"<p>Read data from and write to Google BigQuery within your Prefect flows.</p> <p>Be sure to install <code>prefect-gcp</code> with the BigQuery extra.</p> <p>This code creates a new dataset in BigQuery, define a table, insert rows, and fetch data from the table:</p> <pre><code>from prefect import flow\nfrom prefect_gcp.bigquery import GcpCredentials, BigQueryWarehouse\n\n@flow\ndef bigquery_flow():\n    all_rows = []\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n\n    client = gcp_credentials.get_bigquery_client()\n    client.create_dataset(\"test_example\", exists_ok=True)\n\n    with BigQueryWarehouse(gcp_credentials=gcp_credentials) as warehouse:\n        warehouse.execute(\n            \"CREATE TABLE IF NOT EXISTS test_example.customers (name STRING, address STRING);\"\n        )\n        warehouse.execute_many(\n            \"INSERT INTO test_example.customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = warehouse.fetch_many(\"SELECT * FROM test_example.customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.extend(new_rows)\n    return all_rows\n\n\nif __name__ == \"__main__\":\n    bigquery_flow()\n</code></pre>"},{"location":"integrations/prefect-gcp/#use-prefect-with-google-cloud-storage","title":"Use Prefect with Google Cloud Storage","text":"<p>Interact with Google Cloud Storage.</p> <p>Be sure to install <code>prefect-gcp</code> with the Cloud Storage extra.</p> <p>The code below uses <code>prefect_gcp</code> to upload a file to a Google Cloud Storage bucket and download the same file under a different file name.</p> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_gcp import GcpCredentials, GcsBucket\n\n\n@flow\ndef cloud_storage_flow():\n    # create a dummy file to upload\n    file_path = Path(\"test-example.txt\")\n    file_path.write_text(\"Hello, Prefect!\")\n\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    gcs_bucket = GcsBucket(\n        bucket=\"BUCKET-NAME-PLACEHOLDER\",\n        gcp_credentials=gcp_credentials\n    )\n\n    gcs_bucket_path = gcs_bucket.upload_from_path(file_path)\n    downloaded_file_path = gcs_bucket.download_object_to_path(\n        gcs_bucket_path, \"downloaded-test-example.txt\"\n    )\n    return downloaded_file_path.read_text()\n\n\nif __name__ == \"__main__\":\n    cloud_storage_flow()\n</code></pre> <p>Upload and download directories</p> <p><code>GcsBucket</code> supports uploading and downloading entire directories. To view examples, check out the Examples Catalog!</p>"},{"location":"integrations/prefect-gcp/#save-secrets-with-google-secret-manager","title":"Save secrets with Google Secret Manager","text":"<p>Read and write secrets with Google Secret Manager.</p> <p>Be sure to install <code>prefect-gcp</code> with the Secret Manager extra.</p> <p>The code below writes a secret to the Secret Manager, reads the secret data, and deletes the secret.</p> <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials, GcpSecret\n\n\n@flow\ndef secret_manager_flow():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    gcp_secret = GcpSecret(secret_name=\"test-example\", gcp_credentials=gcp_credentials)\n    gcp_secret.write_secret(secret_data=b\"Hello, Prefect!\")\n    secret_data = gcp_secret.read_secret()\n    gcp_secret.delete_secret()\n    return secret_data\n\n\nif __name__ == \"__main__\":\n    secret_manager_flow()\n</code></pre>"},{"location":"integrations/prefect-gcp/#access-google-credentials-or-clients-from-gcpcredentials","title":"Access Google credentials or clients from GcpCredentials","text":"<p>You can instantiate a Google Cloud client, such as <code>bigquery.Client</code>.</p> <p>Note that a <code>GcpCredentials</code> object is NOT a valid input to the underlying BigQuery client - use the <code>get_credentials_from_service_account</code> method to access and pass a <code>google.auth.Credentials</code> object.</p> <pre><code>import google.cloud.bigquery\nfrom prefect import flow\nfrom prefect_gcp import GcpCredentials\n\n@flow\ndef create_bigquery_client():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    google_auth_credentials = gcp_credentials.get_credentials_from_service_account()\n    bigquery_client = bigquery.Client(credentials=google_auth_credentials)\n</code></pre> <p>To access the underlying client, use the <code>get_client</code> method from <code>GcpCredentials</code>.</p> <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\n\n@flow\ndef create_bigquery_client():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    bigquery_client = gcp_credentials.get_client(\"bigquery\")\n</code></pre>"},{"location":"integrations/prefect-gcp/#resources","title":"Resources","text":"<p>For assistance using GCP, consult the Google Cloud documentation.</p> <p>Refer to the prefect-gcp API documentation linked in the sidebar to explore all the capabilities of the prefect-gcp library.</p>"},{"location":"integrations/prefect-gcp/#additional-installation-options","title":"Additional installation options","text":"<p>Additional installation options for GCP services are shown below.</p>"},{"location":"integrations/prefect-gcp/#to-use-cloud-storage","title":"To use Cloud Storage","text":"<pre><code>pip install \"prefect-gcp[cloud_storage]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-bigquery","title":"To use BigQuery","text":"<pre><code>pip install \"prefect-gcp[bigquery]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-secret-manager","title":"To use Secret Manager","text":"<pre><code>pip install \"prefect-gcp[secret_manager]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-vertex-ai","title":"To use Vertex AI","text":"<pre><code>pip install \"prefect-gcp[aiplatform]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/","title":"AI Platform","text":""},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform","title":"<code>prefect_gcp.aiplatform</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the Vertex AI worker, which offers enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with Google AI Platform.</p> <p>Examples:</p> <pre><code>Run a job using Vertex AI Custom Training:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.run()\n```\n\nRun a job that runs the command `echo hello world` using Google Cloud Run Jobs:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    command=[\"echo\", \"hello world\"],\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.run()\n```\n\nPreview job specs:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    command=[\"echo\", \"hello world\"],\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.preview()\n```\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob","title":"<code>VertexAICustomTrainingJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Infrastructure block used to run Vertex AI custom training jobs.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the Vertex AI worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass VertexAICustomTrainingJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Infrastructure block used to run Vertex AI custom training jobs.\n    \"\"\"\n\n    _block_type_name = \"Vertex AI Custom Training Job\"\n    _block_type_slug = \"vertex-ai-custom-training-job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob\"  # noqa: E501\n\n    type: Literal[\"vertex-ai-custom-training-job\"] = Field(\n        \"vertex-ai-custom-training-job\", description=\"The slug for this task type.\"\n    )\n\n    gcp_credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=(\n            \"GCP credentials to use when running the configured Vertex AI custom \"\n            \"training job. If not provided, credentials will be inferred from the \"\n            \"environment. See `GcpCredentials` for details.\"\n        ),\n    )\n    region: str = Field(\n        default=...,\n        description=\"The region where the Vertex AI custom training job resides.\",\n    )\n    image: str = Field(\n        default=...,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Vertex AI custom training job. This value must \"\n            \"refer to an image within either Google Container Registry \"\n            \"or Google Artifact Registry, like `gcr.io/&lt;project_name&gt;/&lt;repo&gt;/`.\"\n        ),\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to be passed to your Cloud Run Job.\",\n    )\n    machine_type: str = Field(\n        default=\"n1-standard-4\",\n        description=\"The machine type to use for the run, which controls the available \"\n        \"CPU and memory.\",\n    )\n    accelerator_type: Optional[str] = Field(\n        default=None, description=\"The type of accelerator to attach to the machine.\"\n    )\n    accelerator_count: Optional[int] = Field(\n        default=None, description=\"The number of accelerators to attach to the machine.\"\n    )\n    boot_disk_type: str = Field(\n        default=\"pd-ssd\",\n        title=\"Boot Disk Type\",\n        description=\"The type of boot disk to attach to the machine.\",\n    )\n    boot_disk_size_gb: int = Field(\n        default=100,\n        title=\"Boot Disk Size\",\n        description=\"The size of the boot disk to attach to the machine, in gigabytes.\",\n    )\n    maximum_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(days=7), description=\"The maximum job running time.\"\n    )\n    network: Optional[str] = Field(\n        default=None,\n        description=\"The full name of the Compute Engine network\"\n        \"to which the Job should be peered. Private services access must \"\n        \"already be configured for the network. If left unspecified, the job \"\n        \"is not peered with any network.\",\n    )\n    reserved_ip_ranges: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of names for the reserved ip ranges under the VPC \"\n        \"network that can be used for this job. If set, we will deploy the job \"\n        \"within the provided ip ranges. Otherwise, the job will be deployed to \"\n        \"any ip ranges under the provided VPC network.\",\n    )\n    service_account: Optional[str] = Field(\n        default=None,\n        description=(\n            \"Specifies the service account to use \"\n            \"as the run-as account in Vertex AI. The agent submitting jobs must have \"\n            \"act-as permission on this run-as account. If unspecified, the AI \"\n            \"Platform Custom Code Service Agent for the CustomJob's project is \"\n            \"used. Takes precedence over the service account found in gcp_credentials, \"\n            \"and required if a service account cannot be detected in gcp_credentials.\"\n        ),\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n\n    @property\n    def job_name(self):\n        \"\"\"\n        The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:\n        https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name\n        \"\"\"  # noqa\n        try:\n            base_name = self.name or self.image.split(\"/\")[2]\n            return f\"{base_name}-{uuid4().hex}\"\n        except IndexError:\n            raise ValueError(\n                \"The provided image must be from either Google Container Registry \"\n                \"or Google Artifact Registry\"\n            )\n\n    def _get_compatible_labels(self) -&gt; Dict[str, str]:\n        \"\"\"\n        Ensures labels are compatible with GCP label requirements.\n        https://cloud.google.com/resource-manager/docs/creating-managing-labels\n\n        Ex: the Prefect provided key of prefect.io/flow-name -&gt; prefect-io_flow-name\n        \"\"\"\n        compatible_labels = {}\n        for key, val in self.labels.items():\n            new_key = slugify(\n                key,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n            compatible_labels[new_key] = slugify(\n                val,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n        return compatible_labels\n\n    def preview(self) -&gt; str:\n        \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n        job_spec = self._build_job_spec()\n        custom_job = CustomJob(\n            display_name=self.job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(),\n        )\n        return str(custom_job)  # outputs a json string\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return \"vertex-ai\"\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a `Vertex AI` work pool with the same\n        configuration as this block.\n        Returns:\n            - dict: a base job template for a `Vertex AI` work pool\n        \"\"\"\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Cloud Run worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"gcp_credentials\":\n                if not self.gcp_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.gcp_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"maximum_run_time\":\n                base_job_template[\"variables\"][\"properties\"][\"maximum_run_time_hours\"][\n                    \"default\"\n                ] = round(value.total_seconds() / 3600)\n            elif key == \"service_account\":\n                base_job_template[\"variables\"][\"properties\"][\"service_account_name\"][\n                    \"default\"\n                ] = value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by `Vertex AI` work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n\n    def _build_job_spec(self) -&gt; \"CustomJobSpec\":\n        \"\"\"\n        Builds a job spec by gathering details.\n        \"\"\"\n        # gather worker pool spec\n        env_list = [\n            {\"name\": name, \"value\": value}\n            for name, value in {\n                **self._base_environment(),\n                **self.env,\n            }.items()\n        ]\n        container_spec = ContainerSpec(\n            image_uri=self.image, command=self.command, args=[], env=env_list\n        )\n        machine_spec = MachineSpec(\n            machine_type=self.machine_type,\n            accelerator_type=self.accelerator_type,\n            accelerator_count=self.accelerator_count,\n        )\n        worker_pool_spec = WorkerPoolSpec(\n            container_spec=container_spec,\n            machine_spec=machine_spec,\n            replica_count=1,\n            disk_spec=DiskSpec(\n                boot_disk_type=self.boot_disk_type,\n                boot_disk_size_gb=self.boot_disk_size_gb,\n            ),\n        )\n        # look for service account\n        service_account = (\n            self.service_account or self.gcp_credentials._service_account_email\n        )\n        if service_account is None:\n            raise ValueError(\n                \"A service account is required for the Vertex job. \"\n                \"A service account could not be detected in the attached credentials; \"\n                \"please set a service account explicitly, e.g. \"\n                '`VertexAICustomTrainingJob(service_acount=\"...\")`'\n            )\n\n        # build custom job specs\n        timeout = Duration().FromTimedelta(td=self.maximum_run_time)\n        scheduling = Scheduling(timeout=timeout)\n        job_spec = CustomJobSpec(\n            worker_pool_specs=[worker_pool_spec],\n            service_account=service_account,\n            scheduling=scheduling,\n            network=self.network,\n            reserved_ip_ranges=self.reserved_ip_ranges,\n        )\n        return job_spec\n\n    async def _create_and_begin_job(\n        self,\n        job_spec: \"CustomJobSpec\",\n        job_service_async_client: \"JobServiceAsyncClient\",\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Builds a custom job and begins running it.\n        \"\"\"\n        # create custom job\n        custom_job = CustomJob(\n            display_name=self.job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(),\n        )\n\n        # run job\n        self.logger.info(\n            f\"{self._log_prefix}: Creating job {self.job_name!r} \"\n            f\"with command {' '.join(self.command)!r} in region \"\n            f\"{self.region!r} using image {self.image!r}\"\n        )\n\n        project = self.gcp_credentials.project\n        resource_name = f\"projects/{project}/locations/{self.region}\"\n\n        async for attempt in AsyncRetrying(\n            stop=stop_after_attempt(3), wait=wait_fixed(1) + wait_random(0, 3)\n        ):\n            with attempt:\n                custom_job_run = await job_service_async_client.create_custom_job(\n                    parent=resource_name,\n                    custom_job=custom_job,\n                )\n\n        self.logger.info(\n            f\"{self._log_prefix}: Job {self.job_name!r} created. \"\n            f\"The full job name is {custom_job_run.name!r}\"\n        )\n\n        return custom_job_run\n\n    async def _watch_job_run(\n        self,\n        full_job_name: str,  # different from self.job_name\n        job_service_async_client: \"JobServiceAsyncClient\",\n        current_state: \"JobState\",\n        until_states: Tuple[\"JobState\"],\n        timeout: int = None,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Polls job run to see if status changed.\n\n        State changes reported by the Vertex AI API may sometimes be inaccurate\n        immediately upon startup, but should eventually report a correct running\n        and then terminal state. The minimum training duration for a custom job is\n        30 seconds, so short-lived jobs may be marked as successful some time\n        after a flow run has completed.\n        \"\"\"\n        state = JobState.JOB_STATE_UNSPECIFIED\n        last_state = current_state\n        t0 = time.time()\n\n        while state not in until_states:\n            job_run = await job_service_async_client.get_custom_job(\n                name=full_job_name,\n            )\n            state = job_run.state\n            if state != last_state:\n                state_label = (\n                    state.name.replace(\"_\", \" \")\n                    .lower()\n                    .replace(\"state\", \"state is now:\")\n                )\n                # results in \"New job state is now: succeeded\"\n                self.logger.debug(\n                    f\"{self._log_prefix}: {self.job_name} has new {state_label}\"\n                )\n                last_state = state\n            else:\n                # Intermittently, the job will not be described. We want to respect the\n                # watch timeout though.\n                self.logger.debug(f\"{self._log_prefix}: Job not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching job for states \"\n                    \"{until_states!r}\"\n                )\n            await asyncio.sleep(self.job_watch_poll_interval)\n\n        return job_run\n\n    @sync_compatible\n    async def run(\n        self, task_status: Optional[\"TaskStatus\"] = None\n    ) -&gt; VertexAICustomTrainingJobResult:\n        \"\"\"\n        Run the configured task on VertexAI.\n\n        Args:\n            task_status: An optional `TaskStatus` to update when the container starts.\n\n        Returns:\n            The `VertexAICustomTrainingJobResult`.\n        \"\"\"\n        client_options = ClientOptions(\n            api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n        )\n\n        job_spec = self._build_job_spec()\n        job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n        job_run = await self._create_and_begin_job(\n            job_spec,\n            job_service_async_client,\n        )\n\n        if task_status:\n            task_status.started(self.job_name)\n\n        final_job_run = await self._watch_job_run(\n            full_job_name=job_run.name,\n            job_service_async_client=job_service_async_client,\n            current_state=job_run.state,\n            until_states=(\n                JobState.JOB_STATE_SUCCEEDED,\n                JobState.JOB_STATE_FAILED,\n                JobState.JOB_STATE_CANCELLED,\n                JobState.JOB_STATE_EXPIRED,\n            ),\n            timeout=self.maximum_run_time.total_seconds(),\n        )\n\n        error_msg = final_job_run.error.message\n        if error_msg:\n            raise RuntimeError(f\"{self._log_prefix}: {error_msg}\")\n\n        status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n        return VertexAICustomTrainingJobResult(\n            identifier=final_job_run.display_name, status_code=status_code\n        )\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a job running Cloud Run.\n\n        Args:\n            identifier: The Vertex AI full job name, formatted like\n                \"projects/{project}/locations/{location}/customJobs/{custom_job}\".\n\n        Returns:\n            The `VertexAICustomTrainingJobResult`.\n        \"\"\"\n        client_options = ClientOptions(\n            api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n        )\n        job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n        await self._kill_job(\n            job_service_async_client=job_service_async_client,\n            full_job_name=identifier,\n        )\n        self.logger.info(f\"Requested to cancel {identifier}...\")\n\n    async def _kill_job(\n        self, job_service_async_client: \"JobServiceAsyncClient\", full_job_name: str\n    ) -&gt; None:\n        \"\"\"\n        Thin wrapper around Job.delete, wrapping a try/except since\n        Job is an independent class that doesn't have knowledge of\n        CloudRunJob and its associated logic.\n        \"\"\"\n        cancel_custom_job_request = CancelCustomJobRequest(name=full_job_name)\n        try:\n            await job_service_async_client.cancel_custom_job(\n                request=cancel_custom_job_request,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Vertex AI job; the job name {full_job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"VertexAICustomTrainingJob {self.name!r}\"\n        else:\n            return \"VertexAICustomTrainingJob\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.job_name","title":"<code>job_name</code>  <code>property</code>","text":"<p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference: https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a <code>Vertex AI</code> work pool with the same configuration as this block. Returns:     - dict: a base job template for a <code>Vertex AI</code> work pool</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a `Vertex AI` work pool with the same\n    configuration as this block.\n    Returns:\n        - dict: a base job template for a `Vertex AI` work pool\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        self.get_corresponding_worker_type(),\n    )\n    assert (\n        base_job_template is not None\n    ), \"Failed to generate default base job template for Cloud Run worker.\"\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n        ]:\n            continue\n        elif key == \"gcp_credentials\":\n            if not self.gcp_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.gcp_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"maximum_run_time\":\n            base_job_template[\"variables\"][\"properties\"][\"maximum_run_time_hours\"][\n                \"default\"\n            ] = round(value.total_seconds() / 3600)\n        elif key == \"service_account\":\n            base_job_template[\"variables\"][\"properties\"][\"service_account_name\"][\n                \"default\"\n            ] = value\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by `Vertex AI` work pools.\"\n                \" Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return \"vertex-ai\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a job running Cloud Run.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>The Vertex AI full job name, formatted like \"projects/{project}/locations/{location}/customJobs/{custom_job}\".</p> required <p>Returns:</p> Type Description <code>None</code> <p>The <code>VertexAICustomTrainingJobResult</code>.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a job running Cloud Run.\n\n    Args:\n        identifier: The Vertex AI full job name, formatted like\n            \"projects/{project}/locations/{location}/customJobs/{custom_job}\".\n\n    Returns:\n        The `VertexAICustomTrainingJobResult`.\n    \"\"\"\n    client_options = ClientOptions(\n        api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n    )\n    job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n        client_options=client_options\n    )\n    await self._kill_job(\n        job_service_async_client=job_service_async_client,\n        full_job_name=identifier,\n    )\n    self.logger.info(f\"Requested to cancel {identifier}...\")\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the job definition that will be sent to GCP.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n    job_spec = self._build_job_spec()\n    custom_job = CustomJob(\n        display_name=self.job_name,\n        job_spec=job_spec,\n        labels=self._get_compatible_labels(),\n    )\n    return str(custom_job)  # outputs a json string\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured task on VertexAI.</p> <p>Parameters:</p> Name Type Description Default <code>task_status</code> <code>Optional[TaskStatus]</code> <p>An optional <code>TaskStatus</code> to update when the container starts.</p> <code>None</code> <p>Returns:</p> Type Description <code>VertexAICustomTrainingJobResult</code> <p>The <code>VertexAICustomTrainingJobResult</code>.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@sync_compatible\nasync def run(\n    self, task_status: Optional[\"TaskStatus\"] = None\n) -&gt; VertexAICustomTrainingJobResult:\n    \"\"\"\n    Run the configured task on VertexAI.\n\n    Args:\n        task_status: An optional `TaskStatus` to update when the container starts.\n\n    Returns:\n        The `VertexAICustomTrainingJobResult`.\n    \"\"\"\n    client_options = ClientOptions(\n        api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n    )\n\n    job_spec = self._build_job_spec()\n    job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n        client_options=client_options\n    )\n    job_run = await self._create_and_begin_job(\n        job_spec,\n        job_service_async_client,\n    )\n\n    if task_status:\n        task_status.started(self.job_name)\n\n    final_job_run = await self._watch_job_run(\n        full_job_name=job_run.name,\n        job_service_async_client=job_service_async_client,\n        current_state=job_run.state,\n        until_states=(\n            JobState.JOB_STATE_SUCCEEDED,\n            JobState.JOB_STATE_FAILED,\n            JobState.JOB_STATE_CANCELLED,\n            JobState.JOB_STATE_EXPIRED,\n        ),\n        timeout=self.maximum_run_time.total_seconds(),\n    )\n\n    error_msg = final_job_run.error.message\n    if error_msg:\n        raise RuntimeError(f\"{self._log_prefix}: {error_msg}\")\n\n    status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n    return VertexAICustomTrainingJobResult(\n        identifier=final_job_run.display_name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJobResult","title":"<code>VertexAICustomTrainingJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Result from a Vertex AI custom training job.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>class VertexAICustomTrainingJobResult(InfrastructureResult):\n    \"\"\"Result from a Vertex AI custom training job.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/","title":"BigQuery","text":""},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery","title":"<code>prefect_gcp.bigquery</code>","text":"<p>Tasks for interacting with GCP BigQuery</p>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse","title":"<code>BigQueryWarehouse</code>","text":"<p>               Bases: <code>DatabaseBlock</code></p> <p>A block for querying a database with BigQuery.</p> <p>Upon instantiating, a connection to BigQuery is established and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the connection and its cursors when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor could be lost.</p> <p>Attributes:</p> Name Type Description <code>gcp_credentials</code> <code>GcpCredentials</code> <p>The credentials to use to authenticate.</p> <code>fetch_size</code> <code>int</code> <p>The number of rows to fetch at a time when calling fetch_many. Note, this parameter is executed on the client side and is not passed to the database. To limit on the server side, add the <code>LIMIT</code> clause, or the dialect's equivalent clause, like <code>TOP</code>, to the query.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>class BigQueryWarehouse(DatabaseBlock):\n    \"\"\"\n    A block for querying a database with BigQuery.\n\n    Upon instantiating, a connection to BigQuery is established\n    and maintained for the life of the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the connection and its cursors when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor could be lost.\n\n    Attributes:\n        gcp_credentials: The credentials to use to authenticate.\n        fetch_size: The number of rows to fetch at a time when calling fetch_many.\n            Note, this parameter is executed on the client side and is not\n            passed to the database. To limit on the server side, add the `LIMIT`\n            clause, or the dialect's equivalent clause, like `TOP`, to the query.\n    \"\"\"  # noqa\n\n    _block_type_name = \"BigQuery Warehouse\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse\"  # noqa: E501\n\n    gcp_credentials: GcpCredentials\n    fetch_size: int = Field(\n        default=1, description=\"The number of rows to fetch at a time.\"\n    )\n\n    _connection: Optional[\"Connection\"] = None\n    _unique_cursors: Dict[str, \"Cursor\"] = None\n\n    def _start_connection(self):\n        \"\"\"\n        Starts a connection.\n        \"\"\"\n        with self.gcp_credentials.get_bigquery_client() as client:\n            self._connection = Connection(client=client)\n\n    def block_initialization(self) -&gt; None:\n        super().block_initialization()\n        if self._connection is None:\n            self._start_connection()\n\n        if self._unique_cursors is None:\n            self._unique_cursors = {}\n\n    def get_connection(self) -&gt; \"Connection\":\n        \"\"\"\n        Get the opened connection to BigQuery.\n        \"\"\"\n        return self._connection\n\n    def _get_cursor(self, inputs: Dict[str, Any]) -&gt; Tuple[bool, \"Cursor\"]:\n        \"\"\"\n        Get a BigQuery cursor.\n\n        Args:\n            inputs: The inputs to generate a unique hash, used to decide\n                whether a new cursor should be used.\n\n        Returns:\n            Whether a cursor is new and a BigQuery cursor.\n        \"\"\"\n        input_hash = hash_objects(inputs)\n        assert input_hash is not None, (\n            \"We were not able to hash your inputs, \"\n            \"which resulted in an unexpected data return; \"\n            \"please open an issue with a reproducible example.\"\n        )\n        if input_hash not in self._unique_cursors.keys():\n            new_cursor = self._connection.cursor()\n            self._unique_cursors[input_hash] = new_cursor\n            return True, new_cursor\n        else:\n            existing_cursor = self._unique_cursors[input_hash]\n            return False, existing_cursor\n\n    def reset_cursors(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened cursors.\n        \"\"\"\n        input_hashes = tuple(self._unique_cursors.keys())\n        for input_hash in input_hashes:\n            cursor = self._unique_cursors.pop(input_hash)\n            try:\n                cursor.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n                )\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; \"Row\":\n        \"\"\"\n        Fetch a single result from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A tuple containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching one new row at a time:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 3;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                for _ in range(0, 3):\n                    result = warehouse.fetch_one(operation, parameters=parameters)\n                    print(result)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        result = await run_sync_in_worker_thread(cursor.fetchone)\n        return result\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[\"Row\"]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching two new rows at a time:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 6;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                for _ in range(0, 3):\n                    result = warehouse.fetch_many(\n                        operation,\n                        parameters=parameters,\n                        size=2\n                    )\n                    print(result)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        size = size or self.fetch_size\n        result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n        return result\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[\"Row\"]:\n        \"\"\"\n        Fetch all results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching all rows:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 3;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                result = warehouse.fetch_all(operation, parameters=parameters)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        result = await run_sync_in_worker_thread(cursor.fetchall)\n        return result\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Examples:\n            Execute operation with parameters:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    CREATE TABLE mydataset.trips AS (\n                    SELECT\n                        bikeid,\n                        start_time,\n                        duration_minutes\n                    FROM\n                        bigquery-public-data.austin_bikeshare.bikeshare_trips\n                    LIMIT %(limit)s\n                    );\n                '''\n                warehouse.execute(operation, parameters={\"limit\": 5})\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        cursor = self._get_cursor(inputs)[1]\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operations\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n\n        Examples:\n            Create mytable in mydataset and insert two rows into it:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"bigquery\") as warehouse:\n                create_operation = '''\n                CREATE TABLE IF NOT EXISTS mydataset.mytable (\n                    col1 STRING,\n                    col2 INTEGER,\n                    col3 BOOLEAN\n                )\n                '''\n                warehouse.execute(create_operation)\n                insert_operation = '''\n                INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n                '''\n                seq_of_parameters = [\n                    (\"a\", 1, True),\n                    (\"b\", 2, False),\n                ]\n                warehouse.execute_many(\n                    insert_operation,\n                    seq_of_parameters=seq_of_parameters\n                )\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            seq_of_parameters=seq_of_parameters,\n        )\n        cursor = self._get_cursor(inputs)[1]\n        await run_sync_in_worker_thread(cursor.executemany, **inputs)\n\n    def close(self):\n        \"\"\"\n        Closes connection and its cursors.\n        \"\"\"\n        try:\n            self.reset_cursors()\n        finally:\n            if self._connection is not None:\n                self._connection.close()\n                self._connection = None\n\n    def __enter__(self):\n        \"\"\"\n        Start a connection upon entry.\n        \"\"\"\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Closes connection and its cursors upon exit.\n        \"\"\"\n        self.close()\n\n    def __getstate__(self):\n        \"\"\" \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_connection\", \"_unique_cursors\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\" \"\"\"\n        self.__dict__.update(data)\n        self._unique_cursors = {}\n        self._start_connection()\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.close","title":"<code>close</code>","text":"<p>Closes connection and its cursors.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes connection and its cursors.\n    \"\"\"\n    try:\n        self.reset_cursors()\n    finally:\n        if self._connection is not None:\n            self._connection.close()\n            self._connection = None\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Examples:</p> <p>Execute operation with parameters: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        CREATE TABLE mydataset.trips AS (\n        SELECT\n            bikeid,\n            start_time,\n            duration_minutes\n        FROM\n            bigquery-public-data.austin_bikeshare.bikeshare_trips\n        LIMIT %(limit)s\n        );\n    '''\n    warehouse.execute(operation, parameters={\"limit\": 5})\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Examples:\n        Execute operation with parameters:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                CREATE TABLE mydataset.trips AS (\n                SELECT\n                    bikeid,\n                    start_time,\n                    duration_minutes\n                FROM\n                    bigquery-public-data.austin_bikeshare.bikeshare_trips\n                LIMIT %(limit)s\n                );\n            '''\n            warehouse.execute(operation, parameters={\"limit\": 5})\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    cursor = self._get_cursor(inputs)[1]\n    await run_sync_in_worker_thread(cursor.execute, **inputs)\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operations upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <p>Examples:</p> <p>Create mytable in mydataset and insert two rows into it: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"bigquery\") as warehouse:\n    create_operation = '''\n    CREATE TABLE IF NOT EXISTS mydataset.mytable (\n        col1 STRING,\n        col2 INTEGER,\n        col3 BOOLEAN\n    )\n    '''\n    warehouse.execute(create_operation)\n    insert_operation = '''\n    INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n    '''\n    seq_of_parameters = [\n        (\"a\", 1, True),\n        (\"b\", 2, False),\n    ]\n    warehouse.execute_many(\n        insert_operation,\n        seq_of_parameters=seq_of_parameters\n    )\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operations\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n\n    Examples:\n        Create mytable in mydataset and insert two rows into it:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"bigquery\") as warehouse:\n            create_operation = '''\n            CREATE TABLE IF NOT EXISTS mydataset.mytable (\n                col1 STRING,\n                col2 INTEGER,\n                col3 BOOLEAN\n            )\n            '''\n            warehouse.execute(create_operation)\n            insert_operation = '''\n            INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n            '''\n            seq_of_parameters = [\n                (\"a\", 1, True),\n                (\"b\", 2, False),\n            ]\n            warehouse.execute_many(\n                insert_operation,\n                seq_of_parameters=seq_of_parameters\n            )\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        seq_of_parameters=seq_of_parameters,\n    )\n    cursor = self._get_cursor(inputs)[1]\n    await run_sync_in_worker_thread(cursor.executemany, **inputs)\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Row]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching all rows: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 3;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    result = warehouse.fetch_all(operation, parameters=parameters)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[\"Row\"]:\n    \"\"\"\n    Fetch all results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching all rows:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 3;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            result = warehouse.fetch_all(operation, parameters=parameters)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    result = await run_sync_in_worker_thread(cursor.fetchall)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Row]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching two new rows at a time: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 6;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    for _ in range(0, 3):\n        result = warehouse.fetch_many(\n            operation,\n            parameters=parameters,\n            size=2\n        )\n        print(result)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[\"Row\"]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching two new rows at a time:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 6;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            for _ in range(0, 3):\n                result = warehouse.fetch_many(\n                    operation,\n                    parameters=parameters,\n                    size=2\n                )\n                print(result)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    size = size or self.fetch_size\n    result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Row</code> <p>A tuple containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching one new row at a time: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 3;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    for _ in range(0, 3):\n        result = warehouse.fetch_one(operation, parameters=parameters)\n        print(result)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; \"Row\":\n    \"\"\"\n    Fetch a single result from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A tuple containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching one new row at a time:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 3;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            for _ in range(0, 3):\n                result = warehouse.fetch_one(operation, parameters=parameters)\n                print(result)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    result = await run_sync_in_worker_thread(cursor.fetchone)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.get_connection","title":"<code>get_connection</code>","text":"<p>Get the opened connection to BigQuery.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def get_connection(self) -&gt; \"Connection\":\n    \"\"\"\n    Get the opened connection to BigQuery.\n    \"\"\"\n    return self._connection\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.reset_cursors","title":"<code>reset_cursors</code>","text":"<p>Tries to close all opened cursors.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def reset_cursors(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened cursors.\n    \"\"\"\n    input_hashes = tuple(self._unique_cursors.keys())\n    for input_hash in input_hashes:\n        cursor = self._unique_cursors.pop(input_hash)\n        try:\n            cursor.close()\n        except Exception as exc:\n            self.logger.warning(\n                f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n            )\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_create_table","title":"<code>bigquery_create_table</code>  <code>async</code>","text":"<p>Creates table in BigQuery. Args:     dataset: Name of a dataset in that the table will be created.     table: Name of a table to create.     schema: Schema to use when creating the table.     gcp_credentials: Credentials to use for authentication with GCP.     clustering_fields: List of fields to cluster the table by.     time_partitioning: <code>bigquery.TimePartitioning</code> object specifying a partitioning         of the newly created table     project: Project to initialize the BigQuery Client with; if         not provided, will default to the one inferred from your credentials.     location: The location of the dataset that will be written to.     external_config: The external data source.  # noqa Returns:     Table name. Example:     <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_create_table\nfrom google.cloud.bigquery import SchemaField\n@flow\ndef example_bigquery_create_table_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    schema = [\n        SchemaField(\"number\", field_type=\"INTEGER\", mode=\"REQUIRED\"),\n        SchemaField(\"text\", field_type=\"STRING\", mode=\"REQUIRED\"),\n        SchemaField(\"bool\", field_type=\"BOOLEAN\")\n    ]\n    result = bigquery_create_table(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        schema=schema,\n        gcp_credentials=gcp_credentials\n    )\n    return result\nexample_bigquery_create_table_flow()\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_create_table(\n    dataset: str,\n    table: str,\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    clustering_fields: List[str] = None,\n    time_partitioning: \"TimePartitioning\" = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n    external_config: Optional[\"ExternalConfig\"] = None,\n) -&gt; str:\n    \"\"\"\n    Creates table in BigQuery.\n    Args:\n        dataset: Name of a dataset in that the table will be created.\n        table: Name of a table to create.\n        schema: Schema to use when creating the table.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        clustering_fields: List of fields to cluster the table by.\n        time_partitioning: `bigquery.TimePartitioning` object specifying a partitioning\n            of the newly created table\n        project: Project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: The location of the dataset that will be written to.\n        external_config: The [external data source](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#nested_external_data_configuration).  # noqa\n    Returns:\n        Table name.\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_create_table\n        from google.cloud.bigquery import SchemaField\n        @flow\n        def example_bigquery_create_table_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            schema = [\n                SchemaField(\"number\", field_type=\"INTEGER\", mode=\"REQUIRED\"),\n                SchemaField(\"text\", field_type=\"STRING\", mode=\"REQUIRED\"),\n                SchemaField(\"bool\", field_type=\"BOOLEAN\")\n            ]\n            result = bigquery_create_table(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                schema=schema,\n                gcp_credentials=gcp_credentials\n            )\n            return result\n        example_bigquery_create_table_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating %s.%s\", dataset, table)\n\n    if not external_config and not schema:\n        raise ValueError(\"Either a schema or an external config must be provided.\")\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    try:\n        partial_get_dataset = partial(client.get_dataset, dataset)\n        dataset_ref = await to_thread.run_sync(partial_get_dataset)\n    except NotFound:\n        logger.debug(\"Dataset %s not found, creating\", dataset)\n        partial_create_dataset = partial(client.create_dataset, dataset)\n        dataset_ref = await to_thread.run_sync(partial_create_dataset)\n\n    table_ref = dataset_ref.table(table)\n    try:\n        partial_get_table = partial(client.get_table, table_ref)\n        await to_thread.run_sync(partial_get_table)\n        logger.info(\"%s.%s already exists\", dataset, table)\n    except NotFound:\n        logger.debug(\"Table %s not found, creating\", table)\n        table_obj = Table(table_ref, schema=schema)\n\n        # external data configuration\n        if external_config:\n            table_obj.external_data_configuration = external_config\n\n        # cluster for optimal data sorting/access\n        if clustering_fields:\n            table_obj.clustering_fields = clustering_fields\n\n        # partitioning\n        if time_partitioning:\n            table_obj.time_partitioning = time_partitioning\n\n        partial_create_table = partial(client.create_table, table_obj)\n        await to_thread.run_sync(partial_create_table)\n\n    return table\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_insert_stream","title":"<code>bigquery_insert_stream</code>  <code>async</code>","text":"<p>Insert records in a Google BigQuery table via the streaming API.</p> <p>Parameters:</p> Name Type Description Default <code>dataset</code> <code>str</code> <p>Name of a dataset where the records will be written to.</p> required <code>table</code> <code>str</code> <p>Name of a table to write to.</p> required <code>records</code> <code>List[dict]</code> <p>The list of records to insert as rows into the BigQuery table; each item in the list should be a dictionary whose keys correspond to columns in the table.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>project</code> <code>Optional[str]</code> <p>The project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location of the dataset that will be written to.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>List</code> <p>List of inserted rows.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_insert_stream\nfrom google.cloud.bigquery import SchemaField\n\n@flow\ndef example_bigquery_insert_stream_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    records = [\n        {\"number\": 1, \"text\": \"abc\", \"bool\": True},\n        {\"number\": 2, \"text\": \"def\", \"bool\": False},\n    ]\n    result = bigquery_insert_stream(\n        dataset=\"integrations\",\n        table=\"test_table\",\n        records=records,\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_insert_stream_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_insert_stream(\n    dataset: str,\n    table: str,\n    records: List[dict],\n    gcp_credentials: GcpCredentials,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; List:\n    \"\"\"\n    Insert records in a Google BigQuery table via the [streaming\n    API](https://cloud.google.com/bigquery/streaming-data-into-bigquery).\n\n    Args:\n        dataset: Name of a dataset where the records will be written to.\n        table: Name of a table to write to.\n        records: The list of records to insert as rows into the BigQuery table;\n            each item in the list should be a dictionary whose keys correspond to\n            columns in the table.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        project: The project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: Location of the dataset that will be written to.\n\n    Returns:\n        List of inserted rows.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_insert_stream\n        from google.cloud.bigquery import SchemaField\n\n        @flow\n        def example_bigquery_insert_stream_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            records = [\n                {\"number\": 1, \"text\": \"abc\", \"bool\": True},\n                {\"number\": 2, \"text\": \"def\", \"bool\": False},\n            ]\n            result = bigquery_insert_stream(\n                dataset=\"integrations\",\n                table=\"test_table\",\n                records=records,\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_insert_stream_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Inserting into %s.%s as a stream\", dataset, table)\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    table_ref = client.dataset(dataset).table(table)\n    partial_insert = partial(\n        client.insert_rows_json, table=table_ref, json_rows=records\n    )\n    response = await to_thread.run_sync(partial_insert)\n\n    errors = []\n    output = []\n    for row in response:\n        output.append(row)\n        if \"errors\" in row:\n            errors.append(row[\"errors\"])\n\n    if errors:\n        raise ValueError(errors)\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_load_cloud_storage","title":"<code>bigquery_load_cloud_storage</code>  <code>async</code>","text":"<p>Run method for this Task.  Invoked by calling this Task within a Flow context, after initialization. Args:     uri: GCS path to load data from.     dataset: The id of a destination dataset to write the records to.     table: The name of a destination table to write the records to.     gcp_credentials: Credentials to use for authentication with GCP.     schema: The schema to use when creating the table.     job_config: Dictionary of job configuration parameters;         note that the parameters provided here must be pickleable         (e.g., dataset references will be rejected).     project: The project to initialize the BigQuery Client with; if         not provided, will default to the one inferred from your credentials.     location: Location of the dataset that will be written to.</p> <p>Returns:</p> Type Description <code>LoadJob</code> <p>The response from <code>load_table_from_uri</code>.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_load_cloud_storage\n\n@flow\ndef example_bigquery_load_cloud_storage_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    result = bigquery_load_cloud_storage(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        uri=\"uri\",\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_load_cloud_storage_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_load_cloud_storage(\n    dataset: str,\n    table: str,\n    uri: str,\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    job_config: Optional[dict] = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; \"LoadJob\":\n    \"\"\"\n    Run method for this Task.  Invoked by _calling_ this\n    Task within a Flow context, after initialization.\n    Args:\n        uri: GCS path to load data from.\n        dataset: The id of a destination dataset to write the records to.\n        table: The name of a destination table to write the records to.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        schema: The schema to use when creating the table.\n        job_config: Dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        project: The project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: Location of the dataset that will be written to.\n\n    Returns:\n        The response from `load_table_from_uri`.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_load_cloud_storage\n\n        @flow\n        def example_bigquery_load_cloud_storage_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            result = bigquery_load_cloud_storage(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                uri=\"uri\",\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_load_cloud_storage_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Loading into %s.%s from cloud storage\", dataset, table)\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    table_ref = client.dataset(dataset).table(table)\n\n    job_config = job_config or {}\n    if \"autodetect\" not in job_config:\n        job_config[\"autodetect\"] = True\n    job_config = LoadJobConfig(**job_config)\n    if schema:\n        job_config.schema = schema\n\n    result = None\n    try:\n        partial_load = partial(\n            _result_sync,\n            client.load_table_from_uri,\n            uri,\n            table_ref,\n            job_config=job_config,\n        )\n        result = await to_thread.run_sync(partial_load)\n    except Exception as exception:\n        logger.exception(exception)\n        if result is not None and result.errors is not None:\n            for error in result.errors:\n                logger.exception(error)\n        raise\n\n    if result is not None:\n        # remove unpickleable attributes\n        result._client = None\n        result._completion_lock = None\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_load_file","title":"<code>bigquery_load_file</code>  <code>async</code>","text":"<p>Loads file into BigQuery.</p> <p>Parameters:</p> Name Type Description Default <code>dataset</code> <code>str</code> <p>ID of a destination dataset to write the records to; if not provided here, will default to the one provided at initialization.</p> required <code>table</code> <code>str</code> <p>Name of a destination table to write the records to; if not provided here, will default to the one provided at initialization.</p> required <code>path</code> <code>Union[str, Path]</code> <p>A string or path-like object of the file to be loaded.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>schema</code> <code>Optional[List[SchemaField]]</code> <p>Schema to use when creating the table.</p> <code>None</code> <code>job_config</code> <code>Optional[dict]</code> <p>An optional dictionary of job configuration parameters; note that the parameters provided here must be pickleable (e.g., dataset references will be rejected).</p> <code>None</code> <code>rewind</code> <code>bool</code> <p>if True, seek to the beginning of the file handle before reading the file.</p> <code>False</code> <code>size</code> <code>Optional[int]</code> <p>Number of bytes to read from the file handle. If size is None or large, resumable upload will be used. Otherwise, multipart upload will be used.</p> <code>None</code> <code>project</code> <code>Optional[str]</code> <p>Project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>location</code> <code>str</code> <p>location of the dataset that will be written to.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>LoadJob</code> <p>The response from <code>load_table_from_file</code>.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_load_file\nfrom google.cloud.bigquery import SchemaField\n\n@flow\ndef example_bigquery_load_file_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    result = bigquery_load_file(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        path=\"path\",\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_load_file_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_load_file(\n    dataset: str,\n    table: str,\n    path: Union[str, Path],\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    job_config: Optional[dict] = None,\n    rewind: bool = False,\n    size: Optional[int] = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; \"LoadJob\":\n    \"\"\"\n    Loads file into BigQuery.\n\n    Args:\n        dataset: ID of a destination dataset to write the records to;\n            if not provided here, will default to the one provided at initialization.\n        table: Name of a destination table to write the records to;\n            if not provided here, will default to the one provided at initialization.\n        path: A string or path-like object of the file to be loaded.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        schema: Schema to use when creating the table.\n        job_config: An optional dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        rewind: if True, seek to the beginning of the file handle\n            before reading the file.\n        size: Number of bytes to read from the file handle. If size is None or large,\n            resumable upload will be used. Otherwise, multipart upload will be used.\n        project: Project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: location of the dataset that will be written to.\n\n    Returns:\n        The response from `load_table_from_file`.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_load_file\n        from google.cloud.bigquery import SchemaField\n\n        @flow\n        def example_bigquery_load_file_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            result = bigquery_load_file(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                path=\"path\",\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_load_file_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Loading into %s.%s from file\", dataset, table)\n\n    if not os.path.exists(path):\n        raise ValueError(f\"{path} does not exist\")\n    elif not os.path.isfile(path):\n        raise ValueError(f\"{path} is not a file\")\n\n    client = gcp_credentials.get_bigquery_client(project=project)\n    table_ref = client.dataset(dataset).table(table)\n\n    job_config = job_config or {}\n    if \"autodetect\" not in job_config:\n        job_config[\"autodetect\"] = True\n        # TODO: test if autodetect is needed when schema is passed\n    job_config = LoadJobConfig(**job_config)\n    if schema:\n        # TODO: test if schema can be passed directly in job_config\n        job_config.schema = schema\n\n    try:\n        with open(path, \"rb\") as file_obj:\n            partial_load = partial(\n                _result_sync,\n                client.load_table_from_file,\n                file_obj,\n                table_ref,\n                rewind=rewind,\n                size=size,\n                location=location,\n                job_config=job_config,\n            )\n            result = await to_thread.run_sync(partial_load)\n    except IOError:\n        logger.exception(f\"Could not open and read from {path}\")\n        raise\n\n    if result is not None:\n        # remove unpickleable attributes\n        result._client = None\n        result._completion_lock = None\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_query","title":"<code>bigquery_query</code>  <code>async</code>","text":"<p>Runs a BigQuery query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>String of the query to execute.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>query_params</code> <code>Optional[List[tuple]]</code> <p>List of 3-tuples specifying BigQuery query parameters; currently only scalar query parameters are supported.  See the Google documentation for more details on how both the query and the query parameters should be formatted.</p> <code>None</code> <code>dry_run_max_bytes</code> <code>Optional[int]</code> <p>If provided, the maximum number of bytes the query is allowed to process; this will be determined by executing a dry run and raising a <code>ValueError</code> if the maximum is exceeded.</p> <code>None</code> <code>dataset</code> <code>Optional[str]</code> <p>Name of a destination dataset to write the query results to, if you don't want them returned; if provided, <code>table</code> must also be provided.</p> <code>None</code> <code>table</code> <code>Optional[str]</code> <p>Name of a destination table to write the query results to, if you don't want them returned; if provided, <code>dataset</code> must also be provided.</p> <code>None</code> <code>to_dataframe</code> <code>bool</code> <p>If provided, returns the results of the query as a pandas dataframe instead of a list of <code>bigquery.table.Row</code> objects.</p> <code>False</code> <code>job_config</code> <code>Optional[dict]</code> <p>Dictionary of job configuration parameters; note that the parameters provided here must be pickleable (e.g., dataset references will be rejected).</p> <code>None</code> <code>project</code> <code>Optional[str]</code> <p>The project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>result_transformer</code> <code>Optional[Callable[[List[Row]], Any]]</code> <p>Function that can be passed to transform the result of a query before returning. The function will be passed the list of rows returned by BigQuery for the given query.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location of the dataset that will be queried.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>Any</code> <p>A list of rows, or pandas DataFrame if to_dataframe,</p> <code>Any</code> <p>matching the query criteria.</p> Example <p>Queries the public names database, returning 10 results. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_query\n\n@flow\ndef example_bigquery_query_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\",\n        project=\"project\"\n    )\n    query = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = @corpus\n        AND word_count &gt;= @min_word_count\n        ORDER BY word_count DESC;\n    '''\n    query_params = [\n        (\"corpus\", \"STRING\", \"romeoandjuliet\"),\n        (\"min_word_count\", \"INT64\", 250)\n    ]\n    result = bigquery_query(\n        query, gcp_credentials, query_params=query_params\n    )\n    return result\n\nexample_bigquery_query_flow()\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_query(\n    query: str,\n    gcp_credentials: GcpCredentials,\n    query_params: Optional[List[tuple]] = None,  # 3-tuples\n    dry_run_max_bytes: Optional[int] = None,\n    dataset: Optional[str] = None,\n    table: Optional[str] = None,\n    to_dataframe: bool = False,\n    job_config: Optional[dict] = None,\n    project: Optional[str] = None,\n    result_transformer: Optional[Callable[[List[\"Row\"]], Any]] = None,\n    location: str = \"US\",\n) -&gt; Any:\n    \"\"\"\n    Runs a BigQuery query.\n\n    Args:\n        query: String of the query to execute.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        query_params: List of 3-tuples specifying BigQuery query parameters; currently\n            only scalar query parameters are supported.  See the\n            [Google documentation](https://cloud.google.com/bigquery/docs/parameterized-queries#bigquery-query-params-python)\n            for more details on how both the query and the query parameters should be formatted.\n        dry_run_max_bytes: If provided, the maximum number of bytes the query\n            is allowed to process; this will be determined by executing a dry run\n            and raising a `ValueError` if the maximum is exceeded.\n        dataset: Name of a destination dataset to write the query results to,\n            if you don't want them returned; if provided, `table` must also be provided.\n        table: Name of a destination table to write the query results to,\n            if you don't want them returned; if provided, `dataset` must also be provided.\n        to_dataframe: If provided, returns the results of the query as a pandas\n            dataframe instead of a list of `bigquery.table.Row` objects.\n        job_config: Dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        project: The project to initialize the BigQuery Client with; if not\n            provided, will default to the one inferred from your credentials.\n        result_transformer: Function that can be passed to transform the result of a query before returning. The function will be passed the list of rows returned by BigQuery for the given query.\n        location: Location of the dataset that will be queried.\n\n    Returns:\n        A list of rows, or pandas DataFrame if to_dataframe,\n        matching the query criteria.\n\n    Example:\n        Queries the public names database, returning 10 results.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_query\n\n        @flow\n        def example_bigquery_query_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\",\n                project=\"project\"\n            )\n            query = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = @corpus\n                AND word_count &gt;= @min_word_count\n                ORDER BY word_count DESC;\n            '''\n            query_params = [\n                (\"corpus\", \"STRING\", \"romeoandjuliet\"),\n                (\"min_word_count\", \"INT64\", 250)\n            ]\n            result = bigquery_query(\n                query, gcp_credentials, query_params=query_params\n            )\n            return result\n\n        example_bigquery_query_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Running BigQuery query\")\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n\n    # setup job config\n    job_config = QueryJobConfig(**job_config or {})\n    if query_params is not None:\n        job_config.query_parameters = [ScalarQueryParameter(*qp) for qp in query_params]\n\n    # perform dry_run if requested\n    if dry_run_max_bytes is not None:\n        saved_info = dict(\n            dry_run=job_config.dry_run, use_query_cache=job_config.use_query_cache\n        )\n        job_config.dry_run = True\n        job_config.use_query_cache = False\n        partial_query = partial(client.query, query, job_config=job_config)\n        response = await to_thread.run_sync(partial_query)\n        total_bytes_processed = response.total_bytes_processed\n        if total_bytes_processed &gt; dry_run_max_bytes:\n            raise RuntimeError(\n                f\"Query will process {total_bytes_processed} bytes which is above \"\n                f\"the set maximum of {dry_run_max_bytes} for this task.\"\n            )\n        job_config.dry_run = saved_info[\"dry_run\"]\n        job_config.use_query_cache = saved_info[\"use_query_cache\"]\n\n    # if writing to a destination table\n    if dataset is not None:\n        table_ref = client.dataset(dataset).table(table)\n        job_config.destination = table_ref\n\n    partial_query = partial(\n        _result_sync,\n        client.query,\n        query,\n        job_config=job_config,\n    )\n    result = await to_thread.run_sync(partial_query)\n\n    if to_dataframe:\n        return result.to_dataframe()\n    else:\n        if result_transformer:\n            return result_transformer(result)\n        else:\n            return list(result)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/","title":"Cloud Run","text":""},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run","title":"<code>prefect_gcp.cloud_run</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the Cloud Run and Cloud Run V2 workers, which offer enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with Google Cloud Run Job.</p> <p>Examples:</p> <pre><code>Run a job using Google Cloud Run Jobs:\n```python\nCloudRunJob(\n    image=\"gcr.io/my-project/my-image\",\n    region=\"us-east1\",\n    credentials=my_gcp_credentials\n).run()\n```\n\nRun a job that runs the command `echo hello world` using Google Cloud Run Jobs:\n```python\nCloudRunJob(\n    image=\"gcr.io/my-project/my-image\",\n    region=\"us-east1\",\n    credentials=my_gcp_credentials\n    command=[\"echo\", \"hello world\"]\n).run()\n```\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob","title":"<code>CloudRunJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p></p> <p>Infrastructure block used to run GCP Cloud Run Jobs.</p> <p>Project name information is provided by the Credentials object, and should always be correct as long as the Credentials object is for the correct project.</p> <p>Note this block is experimental. The interface may change without notice.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the Cloud Run or Cloud Run v2 worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass CloudRunJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    &lt;span class=\"badge-api experimental\"/&gt;\n\n    Infrastructure block used to run GCP Cloud Run Jobs.\n\n    Project name information is provided by the Credentials object, and should always\n    be correct as long as the Credentials object is for the correct project.\n\n    Note this block is experimental. The interface may change without notice.\n    \"\"\"\n\n    _block_type_slug = \"cloud-run-job\"\n    _block_type_name = \"GCP Cloud Run Job\"\n    _description = \"Infrastructure block used to run GCP Cloud Run Jobs. Note this block is experimental. The interface may change without notice.\"  # noqa\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob\"  # noqa: E501\n\n    type: Literal[\"cloud-run-job\"] = Field(\n        \"cloud-run-job\", description=\"The slug for this task type.\"\n    )\n    image: str = Field(\n        ...,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Cloud Run Job. This value must \"\n            \"refer to an image within either Google Container Registry \"\n            \"or Google Artifact Registry, like `gcr.io/&lt;project_name&gt;/&lt;repo&gt;/`.\"\n        ),\n    )\n    region: str = Field(..., description=\"The region where the Cloud Run Job resides.\")\n    credentials: GcpCredentials  # cannot be Field; else it shows as Json\n\n    # Job settings\n    cpu: Optional[int] = Field(\n        default=None,\n        title=\"CPU\",\n        description=(\n            \"The amount of compute allocated to the Cloud Run Job. \"\n            \"The int must be valid based on the rules specified at \"\n            \"https://cloud.google.com/run/docs/configuring/cpu#setting-jobs .\"\n        ),\n    )\n    memory: Optional[int] = Field(\n        default=None,\n        title=\"Memory\",\n        description=\"The amount of memory allocated to the Cloud Run Job.\",\n    )\n    memory_unit: Optional[Literal[\"G\", \"Gi\", \"M\", \"Mi\"]] = Field(\n        default=None,\n        title=\"Memory Units\",\n        description=(\n            \"The unit of memory. See \"\n            \"https://cloud.google.com/run/docs/configuring/memory-limits#setting \"\n            \"for additional details.\"\n        ),\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run Job.\",\n    )\n    args: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"Arguments to be passed to your Cloud Run Job's entrypoint command.\"\n        ),\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"Environment variables to be passed to your Cloud Run Job.\",\n    )\n\n    # Cleanup behavior\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job on Google Cloud Platform.\",\n    )\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"The length of time that Prefect will wait for a Cloud Run Job to complete \"\n            \"before raising an exception.\"\n        ),\n    )\n    max_retries: Optional[int] = Field(\n        default=3,\n        ge=0,\n        le=10,\n        title=\"Max Retries\",\n        description=(\n            \"The maximum retries setting specifies the number of times a task is \"\n            \"allowed to restart in case of failure before being failed permanently.\"\n        ),\n    )\n    # For private use\n    _job_name: str = None\n    _execution: Optional[Execution] = None\n\n    @property\n    def job_name(self):\n        \"\"\"Create a unique and valid job name.\"\"\"\n\n        if self._job_name is None:\n            # get `repo` from `gcr.io/&lt;project_name&gt;/repo/other`\n            components = self.image.split(\"/\")\n            image_name = components[2]\n            # only alphanumeric and '-' allowed for a job name\n            modified_image_name = image_name.replace(\":\", \"-\").replace(\".\", \"-\")\n            # make 50 char limit for final job name, which will be '&lt;name&gt;-&lt;uuid&gt;'\n            if len(modified_image_name) &gt; 17:\n                modified_image_name = modified_image_name[:17]\n            name = f\"{modified_image_name}-{uuid4().hex}\"\n            self._job_name = name\n\n        return self._job_name\n\n    @property\n    def memory_string(self):\n        \"\"\"Returns the string expected for memory resources argument.\"\"\"\n        if self.memory and self.memory_unit:\n            return str(self.memory) + self.memory_unit\n        return None\n\n    @validator(\"image\")\n    def _remove_image_spaces(cls, value):\n        \"\"\"Deal with spaces in image names.\"\"\"\n        if value is not None:\n            return value.strip()\n\n    @root_validator\n    def _check_valid_memory(cls, values):\n        \"\"\"Make sure memory conforms to expected values for API.\n        See: https://cloud.google.com/run/docs/configuring/memory-limits#setting\n        \"\"\"  # noqa\n        if (values.get(\"memory\") is not None and values.get(\"memory_unit\") is None) or (\n            values.get(\"memory_unit\") is not None and values.get(\"memory\") is None\n        ):\n            raise ValueError(\n                \"A memory value and unit must both be supplied to specify a memory\"\n                \" value other than the default memory value.\"\n            )\n        return values\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return \"cloud-run\"\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a cloud-run work pool with the same\n        configuration as this block.\n\n        Returns:\n            - dict: a base job template for a cloud-run work pool\n        \"\"\"\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Cloud Run worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"memory_unit\",\n            ]:\n                continue\n            elif key == \"credentials\":\n                if not self.credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.credentials._block_document_id)\n                    }\n                }\n            elif key == \"memory\" and self.memory_string:\n                base_job_template[\"variables\"][\"properties\"][\"memory\"][\n                    \"default\"\n                ] = self.memory_string\n            elif key == \"cpu\" and self.cpu is not None:\n                base_job_template[\"variables\"][\"properties\"][\"cpu\"][\n                    \"default\"\n                ] = f\"{self.cpu * 1000}m\"\n            elif key == \"args\":\n                # Not a default variable, but we can add it to the template\n                base_job_template[\"variables\"][\"properties\"][\"args\"] = {\n                    \"title\": \"Arguments\",\n                    \"type\": \"string\",\n                    \"description\": \"Arguments to be passed to your Cloud Run Job's entrypoint command.\",  # noqa\n                    \"default\": value,\n                }\n                base_job_template[\"job_configuration\"][\"job_body\"][\"spec\"][\"template\"][\n                    \"spec\"\n                ][\"template\"][\"spec\"][\"containers\"][0][\"args\"] = \"{{ args }}\"\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n\n    def _create_job_error(self, exc):\n        \"\"\"Provides a nicer error for 404s when trying to create a Cloud Run Job.\"\"\"\n        # TODO consider lookup table instead of the if/else,\n        # also check for documented errors\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{self.region}' is the correct region for your Cloud Run Job and\"\n                f\" that {self.credentials.project} is the correct GCP project. If\"\n                f\" your project ID is not correct, you are using a Credentials block\"\n                f\" with permissions for the wrong project.\"\n            ) from exc\n        raise exc\n\n    def _job_run_submission_error(self, exc):\n        \"\"\"Provides a nicer error for 404s when submitting job runs.\"\"\"\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n            # pat2 = (\n            #     r\"Resource '[^ ]+' of kind 'JOB' in region '[\\w\\-0-9]+' \"\n            #     r\"in project '[\\w\\-0-9]+' does not exist\"\n            # )\n            if re.findall(pat1, str(exc)):\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{self.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{self.credentials.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n        raise exc\n\n    def _cpu_as_k8s_quantity(self) -&gt; str:\n        \"\"\"Return the CPU integer in the format expected by GCP Cloud Run Jobs API.\n        See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/\n        See also: https://cloud.google.com/run/docs/configuring/cpu#setting-jobs\n        \"\"\"  # noqa\n        return str(self.cpu * 1000) + \"m\"\n\n    @sync_compatible\n    async def run(self, task_status: Optional[TaskStatus] = None):\n        \"\"\"Run the configured job on a Google Cloud Run Job.\"\"\"\n        with self._get_client() as client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration, client\n            )\n            job_execution = await run_sync_in_worker_thread(\n                self._begin_job_execution, client\n            )\n\n            if task_status:\n                task_status.started(self.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                client,\n                job_execution,\n                5,\n            )\n            return result\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a task running Cloud Run.\n\n        Args:\n            identifier: The Cloud Run Job name. This should match a\n                value yielded by CloudRunJob.run.\n        \"\"\"\n        if grace_seconds != 30:\n            self.logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client() as client:\n            await run_sync_in_worker_thread(\n                self._kill_job,\n                client=client,\n                namespace=self.credentials.project,\n                job_name=identifier,\n            )\n\n    def _kill_job(self, client: Resource, namespace: str, job_name: str) -&gt; None:\n        \"\"\"\n        Thin wrapper around Job.delete, wrapping a try/except since\n        Job is an independent class that doesn't have knowledge of\n        CloudRunJob and its associated logic.\n        \"\"\"\n        try:\n            Job.delete(client=client, namespace=namespace, job_name=job_name)\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n\n    def _create_job_and_wait_for_registration(self, client: Resource) -&gt; None:\n        \"\"\"Create a new job wait for it to finish registering.\"\"\"\n        try:\n            self.logger.info(f\"Creating Cloud Run Job {self.job_name}\")\n            Job.create(\n                client=client,\n                namespace=self.credentials.project,\n                body=self._jobs_body(),\n            )\n        except googleapiclient.errors.HttpError as exc:\n            self._create_job_error(exc)\n\n        try:\n            self._wait_for_job_creation(client=client, timeout=self.timeout)\n        except Exception:\n            self.logger.exception(\n                \"Encountered an exception while waiting for job run creation\"\n            )\n            if not self.keep_job:\n                self.logger.info(\n                    f\"Deleting Cloud Run Job {self.job_name} from Google Cloud Run.\"\n                )\n                try:\n                    Job.delete(\n                        client=client,\n                        namespace=self.credentials.project,\n                        job_name=self.job_name,\n                    )\n                except Exception:\n                    self.logger.exception(\n                        \"Received an unexpected exception while attempting to delete\"\n                        f\" Cloud Run Job {self.job_name!r}\"\n                    )\n            raise\n\n    def _begin_job_execution(self, client: Resource) -&gt; Execution:\n        \"\"\"Submit a job run for execution and return the execution object.\"\"\"\n        try:\n            self.logger.info(\n                f\"Submitting Cloud Run Job {self.job_name!r} for execution.\"\n            )\n            submission = Job.run(\n                client=client,\n                namespace=self.credentials.project,\n                job_name=self.job_name,\n            )\n\n            job_execution = Execution.get(\n                client=client,\n                namespace=submission[\"metadata\"][\"namespace\"],\n                execution_name=submission[\"metadata\"][\"name\"],\n            )\n\n            command = (\n                \" \".join(self.command) if self.command else \"default container command\"\n            )\n\n            self.logger.info(\n                f\"Cloud Run Job {self.job_name!r}: Running command {command!r}\"\n            )\n        except Exception as exc:\n            self._job_run_submission_error(exc)\n\n        return job_execution\n\n    def _watch_job_execution_and_get_result(\n        self, client: Resource, execution: Execution, poll_interval: int\n    ) -&gt; CloudRunJobResult:\n        \"\"\"Wait for execution to complete and then return result.\"\"\"\n        try:\n            job_execution = self._watch_job_execution(\n                client=client,\n                job_execution=execution,\n                timeout=self.timeout,\n                poll_interval=poll_interval,\n            )\n        except Exception:\n            self.logger.exception(\n                \"Received an unexpected exception while monitoring Cloud Run Job \"\n                f\"{self.job_name!r}\"\n            )\n            raise\n\n        if job_execution.succeeded():\n            status_code = 0\n            self.logger.info(f\"Job Run {self.job_name} completed successfully\")\n        else:\n            status_code = 1\n            error_msg = job_execution.condition_after_completion()[\"message\"]\n            self.logger.error(\n                f\"Job Run {self.job_name} did not complete successfully. {error_msg}\"\n            )\n\n        self.logger.info(\n            f\"Job Run logs can be found on GCP at: {job_execution.log_uri}\"\n        )\n\n        if not self.keep_job:\n            self.logger.info(\n                f\"Deleting completed Cloud Run Job {self.job_name!r} from Google Cloud\"\n                \" Run...\"\n            )\n            try:\n                Job.delete(\n                    client=client,\n                    namespace=self.credentials.project,\n                    job_name=self.job_name,\n                )\n            except Exception:\n                self.logger.exception(\n                    \"Received an unexpected exception while attempting to delete Cloud\"\n                    f\" Run Job {self.job_name}\"\n                )\n\n        return CloudRunJobResult(identifier=self.job_name, status_code=status_code)\n\n    def _jobs_body(self) -&gt; dict:\n        \"\"\"Create properly formatted body used for a Job CREATE request.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs\n        \"\"\"\n        jobs_metadata = {\"name\": self.job_name}\n\n        annotations = {\n            # See: https://cloud.google.com/run/docs/troubleshooting#launch-stage-validation  # noqa\n            \"run.googleapis.com/launch-stage\": \"BETA\",\n        }\n        # add vpc connector if specified\n        if self.vpc_connector_name:\n            annotations[\n                \"run.googleapis.com/vpc-access-connector\"\n            ] = self.vpc_connector_name\n\n        # env and command here\n        containers = [self._add_container_settings({\"image\": self.image})]\n\n        # apply this timeout to each task\n        timeout_seconds = str(self.timeout)\n\n        body = {\n            \"apiVersion\": \"run.googleapis.com/v1\",\n            \"kind\": \"Job\",\n            \"metadata\": jobs_metadata,\n            \"spec\": {  # JobSpec\n                \"template\": {  # ExecutionTemplateSpec\n                    \"metadata\": {\"annotations\": annotations},\n                    \"spec\": {  # ExecutionSpec\n                        \"template\": {  # TaskTemplateSpec\n                            \"spec\": {\n                                \"containers\": containers,\n                                \"timeoutSeconds\": timeout_seconds,\n                                \"maxRetries\": self.max_retries,\n                            }  # TaskSpec\n                        }\n                    },\n                }\n            },\n        }\n        return body\n\n    def preview(self) -&gt; str:\n        \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n        body = self._jobs_body()\n        container_settings = body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n            \"containers\"\n        ][0][\"env\"]\n        body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n            container_setting\n            for container_setting in container_settings\n            if container_setting[\"name\"] != \"PREFECT_API_KEY\"\n        ]\n        return json.dumps(body, indent=2)\n\n    def _watch_job_execution(\n        self, client, job_execution: Execution, timeout: int, poll_interval: int = 5\n    ):\n        \"\"\"\n        Update job_execution status until it is no longer running or timeout is reached.\n        \"\"\"\n        t0 = time.time()\n        while job_execution.is_running():\n            job_execution = Execution.get(\n                client=client,\n                namespace=job_execution.namespace,\n                execution_name=job_execution.name,\n            )\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while waiting for Cloud Run Job \"\n                    \"execution to complete. Your job may still be running on GCP.\"\n                )\n\n            time.sleep(poll_interval)\n\n        return job_execution\n\n    def _wait_for_job_creation(\n        self, client: Resource, timeout: int, poll_interval: int = 5\n    ):\n        \"\"\"Give created job time to register.\"\"\"\n        job = Job.get(\n            client=client, namespace=self.credentials.project, job_name=self.job_name\n        )\n\n        t0 = time.time()\n        while not job.is_ready():\n            ready_condition = (\n                job.ready_condition\n                if job.ready_condition\n                else \"waiting for condition update\"\n            )\n            self.logger.info(\n                f\"Job is not yet ready... Current condition: {ready_condition}\"\n            )\n            job = Job.get(\n                client=client,\n                namespace=self.credentials.project,\n                job_name=self.job_name,\n            )\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while waiting for Cloud Run Job \"\n                    \"execution to complete. Your job may still be running on GCP.\"\n                )\n\n            time.sleep(poll_interval)\n\n    def _get_client(self) -&gt; Resource:\n        \"\"\"Get the base client needed for interacting with GCP APIs.\"\"\"\n        # region needed for 'v1' API\n        api_endpoint = f\"https://{self.region}-run.googleapis.com\"\n        gcp_creds = self.credentials.get_credentials_from_service_account()\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return discovery.build(\n            \"run\", \"v1\", client_options=options, credentials=gcp_creds\n        ).namespaces()\n\n    # CONTAINER SETTINGS\n    def _add_container_settings(self, base_settings: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Add settings related to containers for Cloud Run Jobs to a dictionary.\n        Includes environment variables, entrypoint command, entrypoint arguments,\n        and cpu and memory limits.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        and https://cloud.google.com/run/docs/reference/rest/v1/Container#ResourceRequirements\n        \"\"\"  # noqa\n        container_settings = base_settings.copy()\n        container_settings.update(self._add_env())\n        container_settings.update(self._add_resources())\n        container_settings.update(self._add_command())\n        container_settings.update(self._add_args())\n        return container_settings\n\n    def _add_args(self) -&gt; dict:\n        \"\"\"Set the arguments that will be passed to the entrypoint for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        \"\"\"  # noqa\n        return {\"args\": self.args} if self.args else {}\n\n    def _add_command(self) -&gt; dict:\n        \"\"\"Set the command that a container will run for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        \"\"\"  # noqa\n        return {\"command\": self.command}\n\n    def _add_resources(self) -&gt; dict:\n        \"\"\"Set specified resources limits for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container#ResourceRequirements\n        See also: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/\n        \"\"\"  # noqa\n        resources = {\"limits\": {}, \"requests\": {}}\n\n        if self.cpu is not None:\n            cpu = self._cpu_as_k8s_quantity()\n            resources[\"limits\"][\"cpu\"] = cpu\n            resources[\"requests\"][\"cpu\"] = cpu\n        if self.memory_string is not None:\n            resources[\"limits\"][\"memory\"] = self.memory_string\n            resources[\"requests\"][\"memory\"] = self.memory_string\n\n        return {\"resources\": resources} if resources[\"requests\"] else {}\n\n    def _add_env(self) -&gt; dict:\n        \"\"\"Add environment variables for a Cloud Run Job.\n\n        Method `self._base_environment()` gets necessary Prefect environment variables\n        from the config.\n\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container#envvar for\n        how environment variables are specified for Cloud Run Jobs.\n        \"\"\"  # noqa\n        env = {**self._base_environment(), **self.env}\n        cloud_run_env = [{\"name\": k, \"value\": v} for k, v in env.items()]\n        return {\"env\": cloud_run_env}\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.job_name","title":"<code>job_name</code>  <code>property</code>","text":"<p>Create a unique and valid job name.</p>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.memory_string","title":"<code>memory_string</code>  <code>property</code>","text":"<p>Returns the string expected for memory resources argument.</p>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a cloud-run work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for a cloud-run work pool</li> </ul> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a cloud-run work pool with the same\n    configuration as this block.\n\n    Returns:\n        - dict: a base job template for a cloud-run work pool\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        self.get_corresponding_worker_type(),\n    )\n    assert (\n        base_job_template is not None\n    ), \"Failed to generate default base job template for Cloud Run worker.\"\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n            \"memory_unit\",\n        ]:\n            continue\n        elif key == \"credentials\":\n            if not self.credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(self.credentials._block_document_id)\n                }\n            }\n        elif key == \"memory\" and self.memory_string:\n            base_job_template[\"variables\"][\"properties\"][\"memory\"][\n                \"default\"\n            ] = self.memory_string\n        elif key == \"cpu\" and self.cpu is not None:\n            base_job_template[\"variables\"][\"properties\"][\"cpu\"][\n                \"default\"\n            ] = f\"{self.cpu * 1000}m\"\n        elif key == \"args\":\n            # Not a default variable, but we can add it to the template\n            base_job_template[\"variables\"][\"properties\"][\"args\"] = {\n                \"title\": \"Arguments\",\n                \"type\": \"string\",\n                \"description\": \"Arguments to be passed to your Cloud Run Job's entrypoint command.\",  # noqa\n                \"default\": value,\n            }\n            base_job_template[\"job_configuration\"][\"job_body\"][\"spec\"][\"template\"][\n                \"spec\"\n            ][\"template\"][\"spec\"][\"containers\"][0][\"args\"] = \"{{ args }}\"\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                \" Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return \"cloud-run\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a task running Cloud Run.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>The Cloud Run Job name. This should match a value yielded by CloudRunJob.run.</p> required Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a task running Cloud Run.\n\n    Args:\n        identifier: The Cloud Run Job name. This should match a\n            value yielded by CloudRunJob.run.\n    \"\"\"\n    if grace_seconds != 30:\n        self.logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client() as client:\n        await run_sync_in_worker_thread(\n            self._kill_job,\n            client=client,\n            namespace=self.credentials.project,\n            job_name=identifier,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the job definition that will be sent to GCP.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n    body = self._jobs_body()\n    container_settings = body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n        \"containers\"\n    ][0][\"env\"]\n    body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n        container_setting\n        for container_setting in container_settings\n        if container_setting[\"name\"] != \"PREFECT_API_KEY\"\n    ]\n    return json.dumps(body, indent=2)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured job on a Google Cloud Run Job.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@sync_compatible\nasync def run(self, task_status: Optional[TaskStatus] = None):\n    \"\"\"Run the configured job on a Google Cloud Run Job.\"\"\"\n    with self._get_client() as client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration, client\n        )\n        job_execution = await run_sync_in_worker_thread(\n            self._begin_job_execution, client\n        )\n\n        if task_status:\n            task_status.started(self.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            client,\n            job_execution,\n            5,\n        )\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJobResult","title":"<code>CloudRunJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Result from a Cloud Run Job.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class CloudRunJobResult(InfrastructureResult):\n    \"\"\"Result from a Cloud Run Job.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution","title":"<code>Execution</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Utility class to call GCP <code>executions</code> API and interact with the returned objects.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class Execution(BaseModel):\n    \"\"\"\n    Utility class to call GCP `executions` API and\n    interact with the returned objects.\n    \"\"\"\n\n    name: str\n    namespace: str\n    metadata: dict\n    spec: dict\n    status: dict\n    log_uri: str\n\n    def is_running(self) -&gt; bool:\n        \"\"\"Returns True if Execution is not completed.\"\"\"\n        return self.status.get(\"completionTime\") is None\n\n    def condition_after_completion(self):\n        \"\"\"Returns Execution condition if Execution has completed.\"\"\"\n        for condition in self.status[\"conditions\"]:\n            if condition[\"type\"] == \"Completed\":\n                return condition\n\n    def succeeded(self):\n        \"\"\"Whether or not the Execution completed is a successful state.\"\"\"\n        completed_condition = self.condition_after_completion()\n        if completed_condition and completed_condition[\"status\"] == \"True\":\n            return True\n\n        return False\n\n    @classmethod\n    def get(cls, client: Resource, namespace: str, execution_name: str):\n        \"\"\"\n        Make a get request to the GCP executions API\n        and return an Execution instance.\n        \"\"\"\n        request = client.executions().get(\n            name=f\"namespaces/{namespace}/executions/{execution_name}\"\n        )\n        response = request.execute()\n\n        return cls(\n            name=response[\"metadata\"][\"name\"],\n            namespace=response[\"metadata\"][\"namespace\"],\n            metadata=response[\"metadata\"],\n            spec=response[\"spec\"],\n            status=response[\"status\"],\n            log_uri=response[\"status\"][\"logUri\"],\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.condition_after_completion","title":"<code>condition_after_completion</code>","text":"<p>Returns Execution condition if Execution has completed.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def condition_after_completion(self):\n    \"\"\"Returns Execution condition if Execution has completed.\"\"\"\n    for condition in self.status[\"conditions\"]:\n        if condition[\"type\"] == \"Completed\":\n            return condition\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.get","title":"<code>get</code>  <code>classmethod</code>","text":"<p>Make a get request to the GCP executions API and return an Execution instance.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@classmethod\ndef get(cls, client: Resource, namespace: str, execution_name: str):\n    \"\"\"\n    Make a get request to the GCP executions API\n    and return an Execution instance.\n    \"\"\"\n    request = client.executions().get(\n        name=f\"namespaces/{namespace}/executions/{execution_name}\"\n    )\n    response = request.execute()\n\n    return cls(\n        name=response[\"metadata\"][\"name\"],\n        namespace=response[\"metadata\"][\"namespace\"],\n        metadata=response[\"metadata\"],\n        spec=response[\"spec\"],\n        status=response[\"status\"],\n        log_uri=response[\"status\"][\"logUri\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.is_running","title":"<code>is_running</code>","text":"<p>Returns True if Execution is not completed.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def is_running(self) -&gt; bool:\n    \"\"\"Returns True if Execution is not completed.\"\"\"\n    return self.status.get(\"completionTime\") is None\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.succeeded","title":"<code>succeeded</code>","text":"<p>Whether or not the Execution completed is a successful state.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def succeeded(self):\n    \"\"\"Whether or not the Execution completed is a successful state.\"\"\"\n    completed_condition = self.condition_after_completion()\n    if completed_condition and completed_condition[\"status\"] == \"True\":\n        return True\n\n    return False\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job","title":"<code>Job</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Utility class to call GCP <code>jobs</code> API and interact with the returned objects.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class Job(BaseModel):\n    \"\"\"\n    Utility class to call GCP `jobs` API and\n    interact with the returned objects.\n    \"\"\"\n\n    metadata: dict\n    spec: dict\n    status: dict\n    name: str\n    ready_condition: dict\n    execution_status: dict\n\n    def _is_missing_container(self):\n        \"\"\"\n        Check if Job status is not ready because\n        the specified container cannot be found.\n        \"\"\"\n        if (\n            self.ready_condition.get(\"status\") == \"False\"\n            and self.ready_condition.get(\"reason\") == \"ContainerMissing\"\n        ):\n            return True\n        return False\n\n    def is_ready(self) -&gt; bool:\n        \"\"\"Whether a job is finished registering and ready to be executed\"\"\"\n        if self._is_missing_container():\n            raise Exception(f\"{self.ready_condition['message']}\")\n        return self.ready_condition.get(\"status\") == \"True\"\n\n    def has_execution_in_progress(self) -&gt; bool:\n        \"\"\"See if job has a run in progress.\"\"\"\n        return (\n            self.execution_status == {}\n            or self.execution_status.get(\"completionTimestamp\") is None\n        )\n\n    @staticmethod\n    def _get_ready_condition(job: dict) -&gt; dict:\n        \"\"\"Utility to access JSON field containing ready condition.\"\"\"\n        if job[\"status\"].get(\"conditions\"):\n            for condition in job[\"status\"][\"conditions\"]:\n                if condition[\"type\"] == \"Ready\":\n                    return condition\n\n        return {}\n\n    @staticmethod\n    def _get_execution_status(job: dict):\n        \"\"\"Utility to access JSON field containing execution status.\"\"\"\n        if job[\"status\"].get(\"latestCreatedExecution\"):\n            return job[\"status\"][\"latestCreatedExecution\"]\n\n        return {}\n\n    @classmethod\n    def get(cls, client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a get request to the GCP jobs API and return a Job instance.\"\"\"\n        request = client.jobs().get(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n\n        return cls(\n            metadata=response[\"metadata\"],\n            spec=response[\"spec\"],\n            status=response[\"status\"],\n            name=response[\"metadata\"][\"name\"],\n            ready_condition=cls._get_ready_condition(response),\n            execution_status=cls._get_execution_status(response),\n        )\n\n    @staticmethod\n    def create(client: Resource, namespace: str, body: dict):\n        \"\"\"Make a create request to the GCP jobs API.\"\"\"\n        request = client.jobs().create(parent=f\"namespaces/{namespace}\", body=body)\n        response = request.execute()\n        return response\n\n    @staticmethod\n    def delete(client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a delete request to the GCP jobs API.\"\"\"\n        request = client.jobs().delete(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n        return response\n\n    @staticmethod\n    def run(client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a run request to the GCP jobs API.\"\"\"\n        request = client.jobs().run(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n        return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.create","title":"<code>create</code>  <code>staticmethod</code>","text":"<p>Make a create request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef create(client: Resource, namespace: str, body: dict):\n    \"\"\"Make a create request to the GCP jobs API.\"\"\"\n    request = client.jobs().create(parent=f\"namespaces/{namespace}\", body=body)\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.delete","title":"<code>delete</code>  <code>staticmethod</code>","text":"<p>Make a delete request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef delete(client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a delete request to the GCP jobs API.\"\"\"\n    request = client.jobs().delete(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.get","title":"<code>get</code>  <code>classmethod</code>","text":"<p>Make a get request to the GCP jobs API and return a Job instance.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@classmethod\ndef get(cls, client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a get request to the GCP jobs API and return a Job instance.\"\"\"\n    request = client.jobs().get(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n\n    return cls(\n        metadata=response[\"metadata\"],\n        spec=response[\"spec\"],\n        status=response[\"status\"],\n        name=response[\"metadata\"][\"name\"],\n        ready_condition=cls._get_ready_condition(response),\n        execution_status=cls._get_execution_status(response),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.has_execution_in_progress","title":"<code>has_execution_in_progress</code>","text":"<p>See if job has a run in progress.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def has_execution_in_progress(self) -&gt; bool:\n    \"\"\"See if job has a run in progress.\"\"\"\n    return (\n        self.execution_status == {}\n        or self.execution_status.get(\"completionTimestamp\") is None\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.is_ready","title":"<code>is_ready</code>","text":"<p>Whether a job is finished registering and ready to be executed</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def is_ready(self) -&gt; bool:\n    \"\"\"Whether a job is finished registering and ready to be executed\"\"\"\n    if self._is_missing_container():\n        raise Exception(f\"{self.ready_condition['message']}\")\n    return self.ready_condition.get(\"status\") == \"True\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.run","title":"<code>run</code>  <code>staticmethod</code>","text":"<p>Make a run request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef run(client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a run request to the GCP jobs API.\"\"\"\n    request = client.jobs().run(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/","title":"Cloud Run","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run","title":"<code>prefect_gcp.workers.cloud_run</code>","text":"<p>Module containing the Cloud Run worker used for executing flow runs as Cloud Run jobs.</p> <p>Get started by creating a Cloud Run work pool:</p> <pre><code>prefect work-pool create 'my-cloud-run-pool' --type cloud-run\n</code></pre> <p>Then start a Cloud Run worker with the following command:</p> <pre><code>prefect worker start --pool 'my-cloud-run-pool'\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--configuration","title":"Configuration","text":"<p>Read more about configuring work pools here.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--advanced-configuration","title":"Advanced Configuration","text":"<p>Using a custom Cloud Run job template</p> <p>Below is the default job body template used by the Cloud Run Worker: <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"metadata\":\n        {\n            \"name\": \"{{ name }}\",\n            \"annotations\":\n            {\n                \"run.googleapis.com/launch-stage\": \"BETA\",\n            }\n        },\n        \"spec\":\n        {\n            \"template\":\n            {\n                \"spec\":\n                {\n                    \"template\":\n                    {\n                        \"spec\":\n                        {\n                            \"containers\":\n                            [\n                                {\n                                    \"image\": \"{{ image }}\",\n                                    \"args\": \"{{ args }}\",\n                                    \"resources\":\n                                    {\n                                        \"limits\":\n                                        {\n                                            \"cpu\": \"{{ cpu }}\",\n                                            \"memory\": \"{{ memory }}\"\n                                        },\n                                        \"requests\":\n                                        {\n                                            \"cpu\": \"{{ cpu }}\",\n                                            \"memory\": \"{{ memory }}\"\n                                        }\n                                    }\n                                }\n                            ],\n                            \"timeoutSeconds\": \"{{ timeout }}\",\n                            \"serviceAccountName\": \"{{ service_account_name }}\"\n                        }\n                    }\n                }\n                }\n            },\n            \"metadata\":\n            {\n                \"annotations\":\n                {\n                    \"run.googleapis.com/vpc-access-connector\": \"{{ vpc_connector_name }}\"\n                }\n            }\n        },\n    },\n    \"keep_job\": \"{{ keep_job }}\"\n}\n</code></pre> Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime on a per-deployment basis. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job body template and available variables can be customized on a work pool by work pool basis. By editing the default job body template you can:</p> <ul> <li>Add additional placeholders to the default job template</li> <li>Remove placeholders from the default job template</li> <li>Pass values to Cloud Run that are not defined in the <code>variables</code> schema</li> </ul>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--adding-additional-placeholders","title":"Adding additional placeholders","text":"<p>For example, to allow for extra customization of a new annotation not described in the default job template, you can add the following: <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"metadata\":\n    {\n        \"name\": \"{{ name }}\",\n        \"annotations\":\n        {\n            \"run.googleapis.com/my-custom-annotation\": \"{{ my_custom_annotation }}\",\n            \"run.googleapis.com/launch-stage\": \"BETA\",\n        },\n      ...\n    },\n  ...\n}\n</code></pre> <code>my_custom_annotation</code> can now be used as a placeholder in the job template and set on a per-deployment basis.</p> <pre><code># deployment.yaml\n...\ninfra_overrides: {\"my_custom_annotation\": \"my-custom-value\"}\n</code></pre> <p>Additionally, fields can be set to prevent configuration at the deployment level. For example to configure the <code>vpc_connector_name</code> field, the placeholder can be removed and replaced with an actual value. Now all deployments that point to this work pool will use the same <code>vpc_connector_name</code> value.</p> <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"spec\":\n    {\n        \"template\":\n        {\n            \"metadata\":\n            {\n                \"annotations\":\n                {\n                    \"run.googleapis.com/vpc-access-connector\": \"my-vpc-connector\"\n                }\n            },\n            ...\n        },\n        ...\n    }\n}\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker","title":"<code>CloudRunWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Cloud Run Jobs.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Cloud Run Jobs.\"\"\"\n\n    type = \"cloud-run\"\n    job_configuration = CloudRunWorkerJobConfiguration\n    job_configuration_variables = CloudRunWorkerVariables\n    _description = (\n        \"Execute flow runs within containers on Google Cloud Run. Requires \"\n        \"a Google Cloud Platform account.\"\n    )\n    _display_name = \"Google Cloud Run\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_run_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n\n    def _create_job_error(self, exc, configuration):\n        \"\"\"Provides a nicer error for 404s when trying to create a Cloud Run Job.\"\"\"\n        # TODO consider lookup table instead of the if/else,\n        # also check for documented errors\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{self.region}' is the correct region for your Cloud Run Job and\"\n                f\" that {configuration.project} is the correct GCP project. If\"\n                f\" your project ID is not correct, you are using a Credentials block\"\n                f\" with permissions for the wrong project.\"\n            ) from exc\n        raise exc\n\n    def _job_run_submission_error(self, exc, configuration):\n        \"\"\"Provides a nicer error for 404s when submitting job runs.\"\"\"\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n            # pat2 = (\n            #     r\"Resource '[^ ]+' of kind 'JOB' in region '[\\w\\-0-9]+' \"\n            #     r\"in project '[\\w\\-0-9]+' does not exist\"\n            # )\n            if re.findall(pat1, str(exc)):\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{self.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{configuration.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n        raise exc\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: CloudRunWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; CloudRunWorkerResult:\n        \"\"\"\n        Executes a flow run within a Cloud Run Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            CloudRunWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n\n        logger = self.get_flow_run_logger(flow_run)\n\n        with self._get_client(configuration) as client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration,\n                configuration,\n                client,\n                logger,\n            )\n            job_execution = await run_sync_in_worker_thread(\n                self._begin_job_execution, configuration, client, logger\n            )\n\n            if task_status:\n                task_status.started(configuration.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                configuration,\n                client,\n                job_execution,\n                logger,\n            )\n            return result\n\n    def _get_client(self, configuration: CloudRunWorkerJobConfiguration) -&gt; Resource:\n        \"\"\"Get the base client needed for interacting with GCP APIs.\"\"\"\n        # region needed for 'v1' API\n        api_endpoint = f\"https://{configuration.region}-run.googleapis.com\"\n        gcp_creds = configuration.credentials.get_credentials_from_service_account()\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return discovery.build(\n            \"run\", \"v1\", client_options=options, credentials=gcp_creds\n        ).namespaces()\n\n    def _create_job_and_wait_for_registration(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        logger: PrefectLogAdapter,\n    ) -&gt; None:\n        \"\"\"Create a new job wait for it to finish registering.\"\"\"\n        try:\n            logger.info(f\"Creating Cloud Run Job {configuration.job_name}\")\n\n            Job.create(\n                client=client,\n                namespace=configuration.credentials.project,\n                body=configuration.job_body,\n            )\n        except googleapiclient.errors.HttpError as exc:\n            self._create_job_error(exc, configuration)\n\n        try:\n            self._wait_for_job_creation(\n                client=client, configuration=configuration, logger=logger\n            )\n        except Exception:\n            logger.exception(\n                \"Encountered an exception while waiting for job run creation\"\n            )\n            if not configuration.keep_job:\n                logger.info(\n                    f\"Deleting Cloud Run Job {configuration.job_name} from \"\n                    \"Google Cloud Run.\"\n                )\n                try:\n                    Job.delete(\n                        client=client,\n                        namespace=configuration.credentials.project,\n                        job_name=configuration.job_name,\n                    )\n                except Exception:\n                    logger.exception(\n                        \"Received an unexpected exception while attempting to delete\"\n                        f\" Cloud Run Job {configuration.job_name!r}\"\n                    )\n            raise\n\n    def _begin_job_execution(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        logger: PrefectLogAdapter,\n    ) -&gt; Execution:\n        \"\"\"Submit a job run for execution and return the execution object.\"\"\"\n        try:\n            logger.info(\n                f\"Submitting Cloud Run Job {configuration.job_name!r} for execution.\"\n            )\n            submission = Job.run(\n                client=client,\n                namespace=configuration.project,\n                job_name=configuration.job_name,\n            )\n\n            job_execution = Execution.get(\n                client=client,\n                namespace=submission[\"metadata\"][\"namespace\"],\n                execution_name=submission[\"metadata\"][\"name\"],\n            )\n        except Exception as exc:\n            self._job_run_submission_error(exc, configuration)\n\n        return job_execution\n\n    def _watch_job_execution_and_get_result(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        execution: Execution,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ) -&gt; CloudRunWorkerResult:\n        \"\"\"Wait for execution to complete and then return result.\"\"\"\n        try:\n            job_execution = self._watch_job_execution(\n                client=client,\n                job_execution=execution,\n                poll_interval=poll_interval,\n            )\n        except Exception:\n            logger.exception(\n                \"Received an unexpected exception while monitoring Cloud Run Job \"\n                f\"{configuration.job_name!r}\"\n            )\n            raise\n\n        if job_execution.succeeded():\n            status_code = 0\n            logger.info(f\"Job Run {configuration.job_name} completed successfully\")\n        else:\n            status_code = 1\n            error_msg = job_execution.condition_after_completion()[\"message\"]\n            logger.error(\n                f\"Job Run {configuration.job_name} did not complete successfully. \"\n                f\"{error_msg}\"\n            )\n\n        logger.info(f\"Job Run logs can be found on GCP at: {job_execution.log_uri}\")\n\n        if not configuration.keep_job:\n            logger.info(\n                f\"Deleting completed Cloud Run Job {configuration.job_name!r} \"\n                \"from Google Cloud Run...\"\n            )\n            try:\n                Job.delete(\n                    client=client,\n                    namespace=configuration.project,\n                    job_name=configuration.job_name,\n                )\n            except Exception:\n                logger.exception(\n                    \"Received an unexpected exception while attempting to delete Cloud\"\n                    f\" Run Job {configuration.job_name}\"\n                )\n\n        return CloudRunWorkerResult(\n            identifier=configuration.job_name, status_code=status_code\n        )\n\n    def _watch_job_execution(\n        self, client, job_execution: Execution, poll_interval: int = 5\n    ):\n        \"\"\"\n        Update job_execution status until it is no longer running.\n        \"\"\"\n        while job_execution.is_running():\n            job_execution = Execution.get(\n                client=client,\n                namespace=job_execution.namespace,\n                execution_name=job_execution.name,\n            )\n\n            time.sleep(poll_interval)\n\n        return job_execution\n\n    def _wait_for_job_creation(\n        self,\n        client: Resource,\n        configuration: CloudRunWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ):\n        \"\"\"Give created job time to register.\"\"\"\n        job = Job.get(\n            client=client,\n            namespace=configuration.project,\n            job_name=configuration.job_name,\n        )\n\n        while not job.is_ready():\n            ready_condition = (\n                job.ready_condition\n                if job.ready_condition\n                else \"waiting for condition update\"\n            )\n            logger.info(f\"Job is not yet ready... Current condition: {ready_condition}\")\n            job = Job.get(\n                client=client,\n                namespace=configuration.project,\n                job_name=configuration.job_name,\n            )\n\n            time.sleep(poll_interval)\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: CloudRunWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a job for a cancelled flow run based on the provided infrastructure PID\n        and run configuration.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client(configuration) as client:\n            await run_sync_in_worker_thread(\n                self._stop_job,\n                client=client,\n                namespace=configuration.project,\n                job_name=infrastructure_pid,\n            )\n\n    def _stop_job(self, client: Resource, namespace: str, job_name: str):\n        try:\n            Job.delete(client=client, namespace=namespace, job_name=job_name)\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a job for a cancelled flow run based on the provided infrastructure PID and run configuration.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: CloudRunWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a job for a cancelled flow run based on the provided infrastructure PID\n    and run configuration.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client(configuration) as client:\n        await run_sync_in_worker_thread(\n            self._stop_job,\n            client=client,\n            namespace=configuration.project,\n            job_name=infrastructure_pid,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Cloud Run Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>CloudRunWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>CloudRunWorkerResult</code> <code>CloudRunWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: CloudRunWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; CloudRunWorkerResult:\n    \"\"\"\n    Executes a flow run within a Cloud Run Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        CloudRunWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n\n    logger = self.get_flow_run_logger(flow_run)\n\n    with self._get_client(configuration) as client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration,\n            configuration,\n            client,\n            logger,\n        )\n        job_execution = await run_sync_in_worker_thread(\n            self._begin_job_execution, configuration, client, logger\n        )\n\n        if task_status:\n            task_status.started(configuration.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            configuration,\n            client,\n            job_execution,\n            logger,\n        )\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration","title":"<code>CloudRunWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Cloud Run Worker to create a Cloud Run Job.</p> <p>An instance of this class is passed to the Cloud Run worker's <code>run</code> method for each flow run. It contains all information necessary to execute the flow run as a Cloud Run Job.</p> <p>Attributes:</p> Name Type Description <code>region</code> <code>str</code> <p>The region where the Cloud Run Job resides.</p> <code>credentials</code> <code>Optional[GcpCredentials]</code> <p>The GCP Credentials used to connect to Cloud Run.</p> <code>job_body</code> <code>Dict[str, Any]</code> <p>The job body used to create the Cloud Run Job.</p> <code>timeout</code> <code>Optional[int]</code> <p>Max allowed duration the job may be active before Cloud Run will actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).</p> <code>keep_job</code> <code>Optional[bool]</code> <p>Whether to delete the Cloud Run Job after it completes.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Cloud Run Worker to create a Cloud Run Job.\n\n    An instance of this class is passed to the Cloud Run worker's `run` method\n    for each flow run. It contains all information necessary to execute\n    the flow run as a Cloud Run Job.\n\n    Attributes:\n        region: The region where the Cloud Run Job resides.\n        credentials: The GCP Credentials used to connect to Cloud Run.\n        job_body: The job body used to create the Cloud Run Job.\n        timeout: Max allowed duration the job may be active before Cloud Run\n            will actively try to mark it failed and kill associated containers\n            (maximum of 3600 seconds, 1 hour).\n        keep_job: Whether to delete the Cloud Run Job after it completes.\n    \"\"\"\n\n    region: str = Field(\n        default=\"us-central1\", description=\"The region where the Cloud Run Job resides.\"\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to connect to Cloud Run. \"\n        \"If not provided credentials will be inferred from \"\n        \"the local environment.\",\n    )\n    job_body: Dict[str, Any] = Field(template=_get_default_job_body_template())\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the Job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).\"\n        ),\n    )\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job on Google Cloud Platform.\",\n    )\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"property for accessing the project from the credentials.\"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"property for accessing the name from the job metadata.\"\"\"\n        return self.job_body[\"metadata\"][\"name\"]\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job body and that the\n        job body is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self._populate_envs()\n        self._populate_or_format_command()\n        self._format_args_if_present()\n        self._populate_image_if_not_present()\n        self._populate_name_if_not_present()\n\n    def _populate_envs(self):\n        \"\"\"Populate environment variables. BaseWorker.prepare_for_flow_run handles\n        putting the environment variables in the `env` attribute. This method\n        moves them into the jobs body\"\"\"\n        envs = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n        self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n            \"env\"\n        ] = envs\n\n    def _populate_name_if_not_present(self):\n        \"\"\"Adds the flow run name to the job if one is not already provided.\"\"\"\n        try:\n            if \"name\" not in self.job_body[\"metadata\"]:\n                base_job_name = slugify_name(self.name)\n                job_name = f\"{base_job_name}-{uuid4().hex}\"\n                self.job_body[\"metadata\"][\"name\"] = job_name\n        except KeyError:\n            raise ValueError(\"Unable to verify name due to invalid job body template.\")\n\n    def _populate_image_if_not_present(self):\n        \"\"\"Adds the latest prefect image to the job if one is not already provided.\"\"\"\n        try:\n            if (\n                \"image\"\n                not in self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0]\n            ):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"image\"] = f\"docker.io/{get_prefect_image_name()}\"\n        except KeyError:\n            raise ValueError(\"Unable to verify image due to invalid job body template.\")\n\n    def _populate_or_format_command(self):\n        \"\"\"\n        Ensures that the command is present in the job manifest. Populates the command\n        with the `prefect -m prefect.engine` if a command is not present.\n        \"\"\"\n        try:\n            command = self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                \"containers\"\n            ][0].get(\"command\")\n            if command is None:\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"command\"] = shlex.split(self._base_flow_run_command())\n            elif isinstance(command, str):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"command\"] = shlex.split(command)\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify command due to invalid job body template.\"\n            )\n\n    def _format_args_if_present(self):\n        try:\n            args = self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                \"containers\"\n            ][0].get(\"args\")\n            if args is not None and isinstance(args, str):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"args\"] = shlex.split(args)\n        except KeyError:\n            raise ValueError(\"Unable to verify args due to invalid job body template.\")\n\n    @validator(\"job_body\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job body includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n\n    @validator(\"job_body\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        \"\"\"Ensure that the job body has compatible values.\"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>property for accessing the name from the job metadata.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>property for accessing the project from the credentials.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job body and that the job body is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job body and that the\n    job body is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    self._populate_envs()\n    self._populate_or_format_command()\n    self._format_args_if_present()\n    self._populate_image_if_not_present()\n    self._populate_name_if_not_present()\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerResult","title":"<code>CloudRunWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerVariables","title":"<code>CloudRunWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Cloud Run worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Cloud Run worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region where the Cloud Run Job resides.\",\n        example=\"us-central1\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Cloud Run Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n    image: Optional[str] = Field(\n        default=None,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Cloud Run Job. \"\n            \"If not set, the latest Prefect image will be used. \"\n            \"See https://cloud.google.com/run/docs/deploying#images.\"\n        ),\n        example=\"docker.io/prefecthq/prefect:2-latest\",\n    )\n    cpu: Optional[str] = Field(\n        default=None,\n        title=\"CPU\",\n        description=(\n            \"The amount of compute allocated to the Cloud Run Job. \"\n            \"(1000m = 1 CPU). See \"\n            \"https://cloud.google.com/run/docs/configuring/cpu#setting-jobs.\"\n        ),\n        example=\"1000m\",\n        regex=r\"^(\\d*000)m$\",\n    )\n    memory: Optional[str] = Field(\n        default=None,\n        title=\"Memory\",\n        description=(\n            \"The amount of memory allocated to the Cloud Run Job. \"\n            \"Must be specified in units of 'G', 'Gi', 'M', or 'Mi'. \"\n            \"See https://cloud.google.com/run/docs/configuring/memory-limits#setting.\"\n        ),\n        example=\"512Mi\",\n        regex=r\"^\\d+(?:G|Gi|M|Mi)$\",\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run Job.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=\"The name of the service account to use for the task execution \"\n        \"of Cloud Run Job. By default Cloud Run jobs run as the default \"\n        \"Compute Engine Service Account. \",\n        example=\"service-account@example.iam.gserviceaccount.com\",\n    )\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job after it has run.\",\n    )\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the Job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/","title":"Cloud Run V2","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2","title":"<code>prefect_gcp.workers.cloud_run_v2</code>","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration","title":"<code>CloudRunWorkerJobV2Configuration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>The configuration for the Cloud Run worker V2.</p> <p>The schema for this class is used to populate the <code>job_body</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerJobV2Configuration(BaseJobConfiguration):\n    \"\"\"\n    The configuration for the Cloud Run worker V2.\n\n    The schema for this class is used to populate the `job_body` section of the\n    default base job template.\n    \"\"\"\n\n    credentials: GcpCredentials = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=(\n            \"The GCP Credentials used to connect to Cloud Run. \"\n            \"If not provided credentials will be inferred from \"\n            \"the local environment.\"\n        ),\n    )\n    job_body: Dict[str, Any] = Field(\n        template=_get_default_job_body_template(),\n    )\n    keep_job: bool = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud run job on Google Cloud Platform.\",\n    )\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region in which to run the Cloud Run job\",\n    )\n    timeout: int = Field(\n        default=600,\n        gt=0,\n        le=86400,\n        description=(\n            \"Max allowed duration the job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 86400 seconds, 1 day).\"\n        ),\n    )\n    _job_name: str = PrivateAttr(default=None)\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"\n        Returns the GCP project associated with the credentials.\n\n        Returns:\n            str: The GCP project associated with the credentials.\n        \"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"\n        Returns the name of the job.\n\n        Returns:\n            str: The name of the job.\n        \"\"\"\n        if self._job_name is None:\n            base_job_name = slugify_name(self.name)\n            job_name = f\"{base_job_name}-{uuid4().hex}\"\n            self._job_name = job_name\n\n        return self._job_name\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job body and that the\n        job body is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n        super().prepare_for_flow_run(\n            flow_run=flow_run,\n            deployment=deployment,\n            flow=flow,\n        )\n\n        self._populate_env()\n        self._populate_or_format_command()\n        self._format_args_if_present()\n        self._populate_image_if_not_present()\n        self._populate_timeout()\n        self._remove_vpc_access_if_unset()\n\n    def _populate_timeout(self):\n        \"\"\"\n        Populates the job body with the timeout.\n        \"\"\"\n        self.job_body[\"template\"][\"template\"][\"timeout\"] = f\"{self.timeout}s\"\n\n    def _populate_env(self):\n        \"\"\"\n        Populates the job body with environment variables.\n        \"\"\"\n        envs = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n\n        self.job_body[\"template\"][\"template\"][\"containers\"][0][\"env\"] = envs\n\n    def _populate_image_if_not_present(self):\n        \"\"\"\n        Populates the job body with the image if not present.\n        \"\"\"\n        if \"image\" not in self.job_body[\"template\"][\"template\"][\"containers\"][0]:\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"image\"\n            ] = f\"docker.io/{get_prefect_image_name()}\"\n\n    def _populate_or_format_command(self):\n        \"\"\"\n        Populates the job body with the command if not present.\n        \"\"\"\n        command = self.job_body[\"template\"][\"template\"][\"containers\"][0].get(\"command\")\n\n        if command is None:\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"command\"\n            ] = shlex.split(self._base_flow_run_command())\n        elif isinstance(command, str):\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"command\"\n            ] = shlex.split(command)\n\n    def _format_args_if_present(self):\n        \"\"\"\n        Formats the job body args if present.\n        \"\"\"\n        args = self.job_body[\"template\"][\"template\"][\"containers\"][0].get(\"args\")\n\n        if args is not None and isinstance(args, str):\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"args\"\n            ] = shlex.split(args)\n\n    def _remove_vpc_access_if_unset(self):\n        \"\"\"\n        Removes vpcAccess if unset.\n        \"\"\"\n\n        if \"vpcAccess\" not in self.job_body[\"template\"][\"template\"]:\n            return\n\n        vpc_access = self.job_body[\"template\"][\"template\"][\"vpcAccess\"]\n\n        # if vpcAccess is unset or connector is unset, remove the entire vpcAccess block\n        # otherwise leave the user provided value.\n        if not vpc_access or (\n            len(vpc_access) == 1\n            and \"connector\" in vpc_access\n            and vpc_access[\"connector\"] is None\n        ):\n            self.job_body[\"template\"][\"template\"].pop(\"vpcAccess\")\n\n    # noinspection PyMethodParameters\n    @validator(\"job_body\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job body includes all required components.\n\n        Args:\n            value: The job body to validate.\n        Returns:\n            The validated job body.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n\n        if missing_paths:\n            raise ValueError(\n                f\"Job body is missing required components: {', '.join(missing_paths)}\"\n            )\n\n        return value\n\n    # noinspection PyMethodParameters\n    @validator(\"job_body\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        \"\"\"Ensure that the job body has compatible values.\"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>Returns the name of the job.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The name of the job.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>Returns the GCP project associated with the credentials.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The GCP project associated with the credentials.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job body and that the job body is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job body and that the\n    job body is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n    super().prepare_for_flow_run(\n        flow_run=flow_run,\n        deployment=deployment,\n        flow=flow,\n    )\n\n    self._populate_env()\n    self._populate_or_format_command()\n    self._format_args_if_present()\n    self._populate_image_if_not_present()\n    self._populate_timeout()\n    self._remove_vpc_access_if_unset()\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2","title":"<code>CloudRunWorkerV2</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>The Cloud Run worker V2.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2(BaseWorker):\n    \"\"\"\n    The Cloud Run worker V2.\n    \"\"\"\n\n    type = \"cloud-run-v2\"\n    job_configuration = CloudRunWorkerJobV2Configuration\n    job_configuration_variables = CloudRunWorkerV2Variables\n    _description = \"Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account.\"  # noqa\n    _display_name = \"Google Cloud Run V2\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/worker_v2/\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/4SpnOBvMYkHp6z939MDKP6/549a91bc1ce9afd4fb12c68db7b68106/social-icon-google-cloud-1200-630.png?h=250\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: CloudRunWorkerJobV2Configuration,\n        task_status: Optional[TaskStatus] = None,\n    ) -&gt; CloudRunWorkerV2Result:\n        \"\"\"\n        Runs the flow run on Cloud Run and waits for it to complete.\n\n        Args:\n            flow_run: The flow run to run.\n            configuration: The configuration for the job.\n            task_status: The task status to update.\n\n        Returns:\n            The result of the job.\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n\n        with self._get_client(configuration=configuration) as cr_client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration,\n                configuration=configuration,\n                cr_client=cr_client,\n                logger=logger,\n            )\n\n            execution = await run_sync_in_worker_thread(\n                self._begin_job_execution,\n                configuration=configuration,\n                cr_client=cr_client,\n                logger=logger,\n            )\n\n            if task_status:\n                task_status.started(configuration.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                configuration=configuration,\n                cr_client=cr_client,\n                execution=execution,\n                logger=logger,\n            )\n\n            return result\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: CloudRunWorkerJobV2Configuration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops the Cloud Run job.\n\n        Args:\n            infrastructure_pid: The ID of the infrastructure to stop.\n            configuration: The configuration for the job.\n            grace_seconds: The number of seconds to wait before stopping the job.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client(configuration=configuration) as cr_client:\n            await run_sync_in_worker_thread(\n                self._stop_job,\n                cr_client=cr_client,\n                configuration=configuration,\n                job_name=infrastructure_pid,\n            )\n\n    @staticmethod\n    def _get_client(\n        configuration: CloudRunWorkerJobV2Configuration,\n    ) -&gt; ResourceWarning:\n        \"\"\"\n        Get the base client needed for interacting with GCP Cloud Run V2 API.\n\n        Returns:\n            Resource: The base client needed for interacting with GCP Cloud Run V2 API.\n        \"\"\"\n        api_endpoint = \"https://run.googleapis.com\"\n        gcp_creds = configuration.credentials.get_credentials_from_service_account()\n\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return (\n            discovery.build(\n                \"run\",\n                \"v2\",\n                client_options=options,\n                credentials=gcp_creds,\n                num_retries=3,  # Set to 3 in case of intermittent/connection issues\n            )\n            .projects()\n            .locations()\n        )\n\n    def _create_job_and_wait_for_registration(\n        self,\n        configuration: CloudRunWorkerJobV2Configuration,\n        cr_client: Resource,\n        logger: PrefectLogAdapter,\n    ):\n        \"\"\"\n        Creates the Cloud Run job and waits for it to register.\n\n        Args:\n            configuration: The configuration for the job.\n            cr_client: The Cloud Run client.\n            logger: The logger to use.\n        \"\"\"\n        try:\n            logger.info(f\"Creating Cloud Run JobV2 {configuration.job_name}\")\n\n            JobV2.create(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_id=configuration.job_name,\n                body=configuration.job_body,\n            )\n        except HttpError as exc:\n            self._create_job_error(\n                exc=exc,\n                configuration=configuration,\n            )\n\n        try:\n            self._wait_for_job_creation(\n                cr_client=cr_client,\n                configuration=configuration,\n                logger=logger,\n            )\n        except Exception as exc:\n            logger.critical(\n                f\"Failed to create Cloud Run JobV2 {configuration.job_name}.\\n{exc}\"\n            )\n\n            if not configuration.keep_job:\n                try:\n                    JobV2.delete(\n                        cr_client=cr_client,\n                        project=configuration.project,\n                        location=configuration.region,\n                        job_name=configuration.job_name,\n                    )\n                except Exception as exc2:\n                    logger.critical(\n                        f\"Failed to delete Cloud Run JobV2 {configuration.job_name}.\"\n                        f\"\\n{exc2}\"\n                    )\n\n            raise\n\n    @staticmethod\n    def _wait_for_job_creation(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ):\n        \"\"\"\n        Waits for the Cloud Run job to be created.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            logger: The logger to use.\n            poll_interval: The interval to poll the Cloud Run job, defaults to 5\n                seconds.\n        \"\"\"\n        job = JobV2.get(\n            cr_client=cr_client,\n            project=configuration.project,\n            location=configuration.region,\n            job_name=configuration.job_name,\n        )\n\n        while not job.is_ready():\n            if not (ready_condition := job.get_ready_condition()):\n                ready_condition = \"waiting for condition update\"\n\n            logger.info(f\"Current Job Condition: {ready_condition}\")\n\n            job = JobV2.get(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=configuration.job_name,\n            )\n\n            time.sleep(poll_interval)\n\n    @staticmethod\n    def _create_job_error(\n        exc: HttpError,\n        configuration: CloudRunWorkerJobV2Configuration,\n    ):\n        \"\"\"\n        Creates a formatted error message for the Cloud Run V2 API errors\n        \"\"\"\n        # noinspection PyUnresolvedReferences\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{configuration.region}' is the correct region for your Cloud\"\n                f\" Run Job and that {configuration.project} is the correct GCP \"\n                f\" project. If your project ID is not correct, you are using a \"\n                f\"Credentials block with permissions for the wrong project.\"\n            ) from exc\n\n        raise exc\n\n    def _begin_job_execution(\n        self,\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        logger: PrefectLogAdapter,\n    ) -&gt; ExecutionV2:\n        \"\"\"\n        Begins the Cloud Run job execution.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            logger: The logger to use.\n\n        Returns:\n            The Cloud Run job execution.\n        \"\"\"\n        try:\n            logger.info(\n                f\"Submitting Cloud Run Job V2 {configuration.job_name} for execution...\"\n            )\n\n            submission = JobV2.run(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=configuration.job_name,\n            )\n\n            job_execution = ExecutionV2.get(\n                cr_client=cr_client,\n                execution_id=submission[\"metadata\"][\"name\"],\n            )\n\n            command = (\n                \" \".join(configuration.command)\n                if configuration.command\n                else \"default container command\"\n            )\n\n            logger.info(\n                f\"Cloud Run Job V2 {configuration.job_name} submitted for execution \"\n                f\"with command: {command}\"\n            )\n\n            return job_execution\n        except Exception as exc:\n            self._job_run_submission_error(\n                exc=exc,\n                configuration=configuration,\n            )\n            raise\n\n    def _watch_job_execution_and_get_result(\n        self,\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        execution: ExecutionV2,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ) -&gt; CloudRunWorkerV2Result:\n        \"\"\"\n        Watch the job execution and get the result.\n\n        Args:\n            cr_client (Resource): The base client needed for interacting with GCP\n                Cloud Run V2 API.\n            configuration (CloudRunWorkerJobV2Configuration): The configuration for\n                the job.\n            execution (ExecutionV2): The execution to watch.\n            logger (PrefectLogAdapter): The logger to use.\n            poll_interval (int): The number of seconds to wait between polls.\n                Defaults to 5 seconds.\n\n        Returns:\n            The result of the job.\n        \"\"\"\n        try:\n            execution = self._watch_job_execution(\n                cr_client=cr_client,\n                configuration=configuration,\n                execution=execution,\n                poll_interval=poll_interval,\n            )\n        except Exception as exc:\n            logger.critical(\n                f\"Encountered an exception while waiting for job run completion - \"\n                f\"{exc}\"\n            )\n            raise\n\n        if execution.succeeded():\n            status_code = 0\n            logger.info(f\"Cloud Run Job V2 {configuration.job_name} succeeded\")\n        else:\n            status_code = 1\n            error_mg = execution.condition_after_completion().get(\"message\")\n            logger.error(\n                f\"Cloud Run Job V2 {configuration.job_name} failed - {error_mg}\"\n            )\n\n        logger.info(f\"Job run logs can be found on GCP at: {execution.logUri}\")\n\n        if not configuration.keep_job:\n            logger.info(\n                f\"Deleting completed Cloud Run Job {configuration.job_name!r} from \"\n                \"Google Cloud Run...\"\n            )\n\n            try:\n                JobV2.delete(\n                    cr_client=cr_client,\n                    project=configuration.project,\n                    location=configuration.region,\n                    job_name=configuration.job_name,\n                )\n            except Exception as exc:\n                logger.critical(\n                    \"Received an exception while deleting the Cloud Run Job V2 \"\n                    f\"- {configuration.job_name} - {exc}\"\n                )\n\n        return CloudRunWorkerV2Result(\n            identifier=configuration.job_name,\n            status_code=status_code,\n        )\n\n    # noinspection DuplicatedCode\n    @staticmethod\n    def _watch_job_execution(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        execution: ExecutionV2,\n        poll_interval: int,\n    ) -&gt; ExecutionV2:\n        \"\"\"\n        Update execution status until it is no longer running.\n\n        Args:\n            cr_client (Resource): The base client needed for interacting with GCP\n                Cloud Run V2 API.\n            configuration (CloudRunWorkerJobV2Configuration): The configuration for\n                the job.\n            execution (ExecutionV2): The execution to watch.\n            poll_interval (int): The number of seconds to wait between polls.\n\n        Returns:\n            The execution.\n        \"\"\"\n\n        while execution.is_running():\n            execution = ExecutionV2.get(\n                cr_client=cr_client,\n                execution_id=execution.name,\n            )\n\n            time.sleep(poll_interval)\n\n        return execution\n\n    @staticmethod\n    def _job_run_submission_error(\n        exc: Exception,\n        configuration: CloudRunWorkerJobV2Configuration,\n    ):\n        \"\"\"\n        Creates a formatted error message for the Cloud Run V2 API errors\n\n        Args:\n            exc: The exception to format.\n            configuration: The configuration for the job.\n        \"\"\"\n        # noinspection PyUnresolvedReferences\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n\n            if re.findall(pat1, str(exc)):\n                # noinspection PyUnresolvedReferences\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{configuration.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{configuration.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n    @staticmethod\n    def _stop_job(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        job_name: str,\n    ):\n        \"\"\"\n        Stops/deletes the Cloud Run job.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            job_name: The name of the job to stop.\n        \"\"\"\n        try:\n            JobV2.delete(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=job_name,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops the Cloud Run job.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>The ID of the infrastructure to stop.</p> required <code>configuration</code> <code>CloudRunWorkerJobV2Configuration</code> <p>The configuration for the job.</p> required <code>grace_seconds</code> <code>int</code> <p>The number of seconds to wait before stopping the job.</p> <code>30</code> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: CloudRunWorkerJobV2Configuration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops the Cloud Run job.\n\n    Args:\n        infrastructure_pid: The ID of the infrastructure to stop.\n        configuration: The configuration for the job.\n        grace_seconds: The number of seconds to wait before stopping the job.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client(configuration=configuration) as cr_client:\n        await run_sync_in_worker_thread(\n            self._stop_job,\n            cr_client=cr_client,\n            configuration=configuration,\n            job_name=infrastructure_pid,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs the flow run on Cloud Run and waits for it to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to run.</p> required <code>configuration</code> <code>CloudRunWorkerJobV2Configuration</code> <p>The configuration for the job.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status to update.</p> <code>None</code> <p>Returns:</p> Type Description <code>CloudRunWorkerV2Result</code> <p>The result of the job.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: CloudRunWorkerJobV2Configuration,\n    task_status: Optional[TaskStatus] = None,\n) -&gt; CloudRunWorkerV2Result:\n    \"\"\"\n    Runs the flow run on Cloud Run and waits for it to complete.\n\n    Args:\n        flow_run: The flow run to run.\n        configuration: The configuration for the job.\n        task_status: The task status to update.\n\n    Returns:\n        The result of the job.\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n\n    with self._get_client(configuration=configuration) as cr_client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration,\n            configuration=configuration,\n            cr_client=cr_client,\n            logger=logger,\n        )\n\n        execution = await run_sync_in_worker_thread(\n            self._begin_job_execution,\n            configuration=configuration,\n            cr_client=cr_client,\n            logger=logger,\n        )\n\n        if task_status:\n            task_status.started(configuration.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            configuration=configuration,\n            cr_client=cr_client,\n            execution=execution,\n            logger=logger,\n        )\n\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Result","title":"<code>CloudRunWorkerV2Result</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>The result of a Cloud Run worker V2 job.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2Result(BaseWorkerResult):\n    \"\"\"\n    The result of a Cloud Run worker V2 job.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Variables","title":"<code>CloudRunWorkerV2Variables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Cloud Run worker V2.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2Variables(BaseVariables):\n    \"\"\"\n    Default variables for the Cloud Run worker V2.\n\n    The schema for this class is used to populate the `variables` section of the\n    default base job template.\n    \"\"\"\n\n    credentials: GcpCredentials = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=(\n            \"The GCP Credentials used to connect to Cloud Run. \"\n            \"If not provided credentials will be inferred from \"\n            \"the local environment.\"\n        ),\n    )\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region in which to run the Cloud Run job\",\n    )\n    image: Optional[str] = Field(\n        default=\"prefecthq/prefect:2-latest\",\n        title=\"Image Name\",\n        description=(\n            \"The image to use for the Cloud Run job. \"\n            \"If not provided the default Prefect image will be used.\"\n        ),\n    )\n    args: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"The arguments to pass to the Cloud Run Job V2's entrypoint command.\"\n        ),\n    )\n    keep_job: bool = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud run job on Google Cloud Platform.\",\n    )\n    launch_stage: Literal[\n        \"ALPHA\",\n        \"BETA\",\n        \"GA\",\n        \"DEPRECATED\",\n        \"EARLY_ACCESS\",\n        \"PRELAUNCH\",\n        \"UNIMPLEMENTED\",\n        \"LAUNCH_TAG_UNSPECIFIED\",\n    ] = Field(\n        \"BETA\",\n        description=(\n            \"The launch stage of the Cloud Run Job V2. \"\n            \"See https://cloud.google.com/run/docs/about-features-categories \"\n            \"for additional details.\"\n        ),\n    )\n    max_retries: int = Field(\n        default=0,\n        title=\"Max Retries\",\n        description=\"The number of times to retry the Cloud Run job.\",\n    )\n    cpu: str = Field(\n        default=\"1000m\",\n        title=\"CPU\",\n        description=\"The CPU to allocate to the Cloud Run job.\",\n    )\n    memory: str = Field(\n        default=\"512Mi\",\n        title=\"Memory\",\n        description=(\n            \"The memory to allocate to the Cloud Run job along with the units, which\"\n            \"could be: G, Gi, M, Mi.\"\n        ),\n        example=\"512Mi\",\n        pattern=r\"^\\d+(?:G|Gi|M|Mi)$\",\n    )\n    timeout: int = Field(\n        default=600,\n        gt=0,\n        le=86400,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 86400 seconds, 1 day).\"\n        ),\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run job.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=(\n            \"The name of the service account to use for the task execution \"\n            \"of Cloud Run Job. By default Cloud Run jobs run as the default \"\n            \"Compute Engine Service Account.\"\n        ),\n        example=\"service-account@example.iam.gserviceaccount.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/","title":"Cloud Storage","text":""},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage","title":"<code>prefect_gcp.cloud_storage</code>","text":"<p>Tasks for interacting with GCP Cloud Storage.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat","title":"<code>DataFrameSerializationFormat</code>","text":"<p>               Bases: <code>Enum</code></p> <p>An enumeration class to represent different file formats, compression options for upload_from_dataframe</p> <p>Attributes:</p> Name Type Description <code>CSV</code> <p>Representation for 'csv' file format with no compression and its related content type and suffix.</p> <code>CSV_GZIP</code> <p>Representation for 'csv' file format with 'gzip' compression and its related content type and suffix.</p> <code>PARQUET</code> <p>Representation for 'parquet' file format with no compression and its related content type and suffix.</p> <code>PARQUET_SNAPPY</code> <p>Representation for 'parquet' file format with 'snappy' compression and its related content type and suffix.</p> <code>PARQUET_GZIP</code> <p>Representation for 'parquet' file format with 'gzip' compression and its related content type and suffix.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>class DataFrameSerializationFormat(Enum):\n    \"\"\"\n    An enumeration class to represent different file formats,\n    compression options for upload_from_dataframe\n\n    Attributes:\n        CSV: Representation for 'csv' file format with no compression\n            and its related content type and suffix.\n\n        CSV_GZIP: Representation for 'csv' file format with 'gzip' compression\n            and its related content type and suffix.\n\n        PARQUET: Representation for 'parquet' file format with no compression\n            and its related content type and suffix.\n\n        PARQUET_SNAPPY: Representation for 'parquet' file format\n            with 'snappy' compression and its related content type and suffix.\n\n        PARQUET_GZIP: Representation for 'parquet' file format\n            with 'gzip' compression and its related content type and suffix.\n    \"\"\"\n\n    CSV = (\"csv\", None, \"text/csv\", \".csv\")\n    CSV_GZIP = (\"csv\", \"gzip\", \"application/x-gzip\", \".csv.gz\")\n    PARQUET = (\"parquet\", None, \"application/octet-stream\", \".parquet\")\n    PARQUET_SNAPPY = (\n        \"parquet\",\n        \"snappy\",\n        \"application/octet-stream\",\n        \".snappy.parquet\",\n    )\n    PARQUET_GZIP = (\"parquet\", \"gzip\", \"application/octet-stream\", \".gz.parquet\")\n\n    @property\n    def format(self) -&gt; str:\n        \"\"\"The file format of the current instance.\"\"\"\n        return self.value[0]\n\n    @property\n    def compression(self) -&gt; Union[str, None]:\n        \"\"\"The compression type of the current instance.\"\"\"\n        return self.value[1]\n\n    @property\n    def content_type(self) -&gt; str:\n        \"\"\"The content type of the current instance.\"\"\"\n        return self.value[2]\n\n    @property\n    def suffix(self) -&gt; str:\n        \"\"\"The suffix of the file format of the current instance.\"\"\"\n        return self.value[3]\n\n    def fix_extension_with(self, gcs_blob_path: str) -&gt; str:\n        \"\"\"Fix the extension of a GCS blob.\n\n        Args:\n            gcs_blob_path: The path to the GCS blob to be modified.\n\n        Returns:\n            The modified path to the GCS blob with the new extension.\n        \"\"\"\n        gcs_blob_path = PurePosixPath(gcs_blob_path)\n        folder = gcs_blob_path.parent\n        filename = PurePosixPath(gcs_blob_path.stem).with_suffix(self.suffix)\n        return str(folder.joinpath(filename))\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.compression","title":"<code>compression: Union[str, None]</code>  <code>property</code>","text":"<p>The compression type of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.content_type","title":"<code>content_type: str</code>  <code>property</code>","text":"<p>The content type of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.format","title":"<code>format: str</code>  <code>property</code>","text":"<p>The file format of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.suffix","title":"<code>suffix: str</code>  <code>property</code>","text":"<p>The suffix of the file format of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.fix_extension_with","title":"<code>fix_extension_with</code>","text":"<p>Fix the extension of a GCS blob.</p> <p>Parameters:</p> Name Type Description Default <code>gcs_blob_path</code> <code>str</code> <p>The path to the GCS blob to be modified.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The modified path to the GCS blob with the new extension.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>def fix_extension_with(self, gcs_blob_path: str) -&gt; str:\n    \"\"\"Fix the extension of a GCS blob.\n\n    Args:\n        gcs_blob_path: The path to the GCS blob to be modified.\n\n    Returns:\n        The modified path to the GCS blob with the new extension.\n    \"\"\"\n    gcs_blob_path = PurePosixPath(gcs_blob_path)\n    folder = gcs_blob_path.parent\n    filename = PurePosixPath(gcs_blob_path.stem).with_suffix(self.suffix)\n    return str(folder.joinpath(filename))\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket","title":"<code>GcsBucket</code>","text":"<p>               Bases: <code>WritableDeploymentStorage</code>, <code>WritableFileSystem</code>, <code>ObjectStorageBlock</code></p> <p>Block used to store data using GCP Cloud Storage Buckets.</p> <p>Note! <code>GcsBucket</code> in <code>prefect-gcp</code> is a unique block, separate from <code>GCS</code> in core Prefect. <code>GcsBucket</code> does not use <code>gcsfs</code> under the hood, instead using the <code>google-cloud-storage</code> package, and offers more configuration and functionality.</p> <p>Attributes:</p> Name Type Description <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> <code>gcp_credentials</code> <code>GcpCredentials</code> <p>The credentials to authenticate with GCP.</p> <code>bucket_folder</code> <code>str</code> <p>A default path to a folder within the GCS bucket to use for reading and writing objects.</p> Example <p>Load stored GCP Cloud Storage Bucket: <pre><code>from prefect_gcp.cloud_storage import GcsBucket\ngcp_cloud_storage_bucket_block = GcsBucket.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>class GcsBucket(WritableDeploymentStorage, WritableFileSystem, ObjectStorageBlock):\n    \"\"\"\n    Block used to store data using GCP Cloud Storage Buckets.\n\n    Note! `GcsBucket` in `prefect-gcp` is a unique block, separate from `GCS`\n    in core Prefect. `GcsBucket` does not use `gcsfs` under the hood,\n    instead using the `google-cloud-storage` package, and offers more configuration\n    and functionality.\n\n    Attributes:\n        bucket: Name of the bucket.\n        gcp_credentials: The credentials to authenticate with GCP.\n        bucket_folder: A default path to a folder within the GCS bucket to use\n            for reading and writing objects.\n\n    Example:\n        Load stored GCP Cloud Storage Bucket:\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n        gcp_cloud_storage_bucket_block = GcsBucket.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _block_type_name = \"GCS Bucket\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket\"  # noqa: E501\n\n    bucket: str = Field(..., description=\"Name of the bucket.\")\n    gcp_credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=\"The credentials to authenticate with GCP.\",\n    )\n    bucket_folder: str = Field(\n        default=\"\",\n        description=(\n            \"A default path to a folder within the GCS bucket to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    @property\n    def basepath(self) -&gt; str:\n        \"\"\"\n        Read-only property that mirrors the bucket folder.\n\n        Used for deployment.\n        \"\"\"\n        return self.bucket_folder\n\n    @validator(\"bucket_folder\", pre=True, always=True)\n    def _bucket_folder_suffix(cls, value):\n        \"\"\"\n        Ensures that the bucket folder is suffixed with a forward slash.\n        \"\"\"\n        if value != \"\" and not value.endswith(\"/\"):\n            value = f\"{value}/\"\n        return value\n\n    def _resolve_path(self, path: str) -&gt; str:\n        \"\"\"\n        A helper function used in write_path to join `self.bucket_folder` and `path`.\n\n        Args:\n            path: Name of the key, e.g. \"file1\". Each object in your\n                bucket has a unique key (or key name).\n\n        Returns:\n            The joined path.\n        \"\"\"\n        # If bucket_folder provided, it means we won't write to the root dir of\n        # the bucket. So we need to add it on the front of the path.\n        path = (\n            str(PurePosixPath(self.bucket_folder, path)) if self.bucket_folder else path\n        )\n        if path in [\"\", \".\", \"/\"]:\n            # client.bucket.list_blobs(prefix=None) is the proper way\n            # of specifying the root folder of the bucket\n            path = None\n        return path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; List[Union[str, Path]]:\n        \"\"\"\n        Copies a folder from the configured GCS bucket to a local directory.\n        Defaults to copying the entire contents of the block's bucket_folder\n        to the current working directory.\n\n        Args:\n            from_path: Path in GCS bucket to download from. Defaults to the block's\n                configured bucket_folder.\n            local_path: Local path to download GCS bucket contents to.\n                Defaults to the current working directory.\n\n        Returns:\n            A list of downloaded file paths.\n        \"\"\"\n        from_path = (\n            self.bucket_folder if from_path is None else self._resolve_path(from_path)\n        )\n\n        if local_path is None:\n            local_path = os.path.abspath(\".\")\n        else:\n            local_path = os.path.abspath(os.path.expanduser(local_path))\n\n        project = self.gcp_credentials.project\n        client = self.gcp_credentials.get_cloud_storage_client(project=project)\n\n        blobs = await run_sync_in_worker_thread(\n            client.list_blobs, self.bucket, prefix=from_path\n        )\n\n        file_paths = []\n        for blob in blobs:\n            blob_path = blob.name\n            if blob_path[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n            relative_blob_path = os.path.relpath(blob_path, from_path)\n            local_file_path = os.path.join(local_path, relative_blob_path)\n            os.makedirs(os.path.dirname(local_file_path), exist_ok=True)\n\n            with disable_run_logger():\n                file_path = await cloud_storage_download_blob_to_file.fn(\n                    bucket=self.bucket,\n                    blob=blob_path,\n                    path=local_file_path,\n                    gcp_credentials=self.gcp_credentials,\n                )\n                file_paths.append(file_path)\n        return file_paths\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to the configured GCS bucket in a\n        given folder.\n\n        Defaults to uploading the entire contents the current working directory to the\n        block's bucket_folder.\n\n        Args:\n            local_path: Path to local directory to upload from.\n            to_path: Path in GCS bucket to upload to. Defaults to block's configured\n                bucket_folder.\n            ignore_file: Path to file containing gitignore style expressions for\n                filepaths to ignore.\n\n        Returns:\n            The number of files uploaded.\n        \"\"\"\n        if local_path is None:\n            local_path = os.path.abspath(\".\")\n        else:\n            local_path = os.path.expanduser(local_path)\n\n        to_path = self.bucket_folder if to_path is None else self._resolve_path(to_path)\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n            included_files = filter_files(local_path, ignore_patterns)\n\n        uploaded_file_count = 0\n        for local_file_path in Path(local_path).rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = str(\n                    PurePosixPath(to_path, local_file_path.relative_to(local_path))\n                )\n                local_file_content = local_file_path.read_bytes()\n                await self.write_path(remote_file_path, content=local_file_content)\n                uploaded_file_count += 1\n\n        return uploaded_file_count\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Read specified path from GCS and return contents. Provide the entire\n        path to the key in GCS.\n\n        Args:\n            path: Entire path to (and including) the key.\n\n        Returns:\n            A bytes or string representation of the blob object.\n        \"\"\"\n        path = self._resolve_path(path)\n        with disable_run_logger():\n            contents = await cloud_storage_download_blob_as_bytes.fn(\n                bucket=self.bucket, blob=path, gcp_credentials=self.gcp_credentials\n            )\n        return contents\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        \"\"\"\n        Writes to an GCS bucket.\n\n        Args:\n            path: The key name. Each object in your bucket has a unique\n                key (or key name).\n            content: What you are uploading to GCS Bucket.\n\n        Returns:\n            The path that the contents were written to.\n        \"\"\"\n        path = self._resolve_path(path)\n        with disable_run_logger():\n            await cloud_storage_upload_blob_from_string.fn(\n                data=content,\n                bucket=self.bucket,\n                blob=path,\n                gcp_credentials=self.gcp_credentials,\n            )\n        return path\n\n    # NEW BLOCK INTERFACE METHODS BELOW\n    def _join_bucket_folder(self, bucket_path: str = \"\") -&gt; str:\n        \"\"\"\n        Joins the base bucket folder to the bucket path.\n\n        NOTE: If a method reuses another method in this class, be careful to not\n        call this  twice because it'll join the bucket folder twice.\n        See https://github.com/PrefectHQ/prefect-aws/issues/141 for a past issue.\n        \"\"\"\n        bucket_path = str(bucket_path)\n        if self.bucket_folder != \"\" and bucket_path.startswith(self.bucket_folder):\n            self.logger.info(\n                f\"Bucket path {bucket_path!r} is already prefixed with \"\n                f\"bucket folder {self.bucket_folder!r}; is this intentional?\"\n            )\n\n        bucket_path = str(PurePosixPath(self.bucket_folder) / bucket_path)\n        if bucket_path in [\"\", \".\", \"/\"]:\n            # client.bucket.list_blobs(prefix=None) is the proper way\n            # of specifying the root folder of the bucket\n            bucket_path = None\n        return bucket_path\n\n    @sync_compatible\n    async def create_bucket(\n        self, location: Optional[str] = None, **create_kwargs\n    ) -&gt; \"Bucket\":\n        \"\"\"\n        Creates a bucket.\n\n        Args:\n            location: The location of the bucket.\n            **create_kwargs: Additional keyword arguments to pass to the\n                `create_bucket` method.\n\n        Returns:\n            The bucket object.\n\n        Examples:\n            Create a bucket.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket(bucket=\"my-bucket\")\n            gcs_bucket.create_bucket()\n            ```\n        \"\"\"\n        self.logger.info(f\"Creating bucket {self.bucket!r}.\")\n        client = self.gcp_credentials.get_cloud_storage_client()\n        bucket = await run_sync_in_worker_thread(\n            client.create_bucket, self.bucket, location=location, **create_kwargs\n        )\n        return bucket\n\n    @sync_compatible\n    async def get_bucket(self) -&gt; \"Bucket\":\n        \"\"\"\n        Returns the bucket object.\n\n        Returns:\n            The bucket object.\n\n        Examples:\n            Get the bucket object.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.get_bucket()\n            ```\n        \"\"\"\n        self.logger.info(f\"Getting bucket {self.bucket!r}.\")\n        client = self.gcp_credentials.get_cloud_storage_client()\n        bucket = await run_sync_in_worker_thread(client.get_bucket, self.bucket)\n        return bucket\n\n    @sync_compatible\n    async def list_blobs(self, folder: str = \"\") -&gt; List[\"Blob\"]:\n        \"\"\"\n        Lists all blobs in the bucket that are in a folder.\n        Folders are not included in the output.\n\n        Args:\n            folder: The folder to list blobs from.\n\n        Returns:\n            A list of Blob objects.\n\n        Examples:\n            Get all blobs from a folder named \"prefect\".\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_blobs(\"prefect\")\n            ```\n        \"\"\"\n        client = self.gcp_credentials.get_cloud_storage_client()\n\n        bucket_path = self._join_bucket_folder(folder)\n        if bucket_path is None:\n            self.logger.info(f\"Listing blobs in bucket {self.bucket!r}.\")\n        else:\n            self.logger.info(\n                f\"Listing blobs in folder {bucket_path!r} in bucket {self.bucket!r}.\"\n            )\n        blobs = await run_sync_in_worker_thread(\n            client.list_blobs, self.bucket, prefix=bucket_path\n        )\n\n        # Ignore folders\n        return [blob for blob in blobs if not blob.name.endswith(\"/\")]\n\n    @sync_compatible\n    async def list_folders(self, folder: str = \"\") -&gt; List[str]:\n        \"\"\"\n        Lists all folders and subfolders in the bucket.\n\n        Args:\n            folder: List all folders and subfolders inside given folder.\n\n        Returns:\n            A list of folders.\n\n        Examples:\n            Get all folders from a bucket named \"my-bucket\".\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_folders()\n            ```\n\n            Get all folders from a folder called years\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_folders(\"years\")\n            ```\n        \"\"\"\n\n        # Beware of calling _join_bucket_folder twice, see note in method.\n        # However, we just want to use it to check if we are listing the root folder\n        bucket_path = self._join_bucket_folder(folder)\n        if bucket_path is None:\n            self.logger.info(f\"Listing folders in bucket {self.bucket!r}.\")\n        else:\n            self.logger.info(\n                f\"Listing folders in {bucket_path!r} in bucket {self.bucket!r}.\"\n            )\n\n        blobs = await self.list_blobs(folder)\n        # gets all folders with full path\n        folders = {str(PurePosixPath(blob.name).parent) for blob in blobs}\n\n        return [folder for folder in folders if folder != \".\"]\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads an object from the object storage service to a path.\n\n        Args:\n            from_path: The path to the blob to download; this gets prefixed\n                with the bucket_folder.\n            to_path: The path to download the blob to. If not provided, the\n                blob's name will be used.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_filename`.\n\n        Returns:\n            The absolute path that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to notes.txt.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # making path absolute, but converting back to str here\n        # since !r looks nicer that way and filename arg expects str\n        to_path = str(Path(to_path).absolute())\n\n        bucket = await self.get_bucket()\n        bucket_path = self._join_bucket_folder(from_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n            f\"to {to_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.download_to_filename, filename=to_path, **download_kwargs\n        )\n        return Path(to_path)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; BinaryIO:\n        \"\"\"\n        Downloads an object from the object storage service to a file-like object,\n        which can be a BytesIO object or a BufferedWriter.\n\n        Args:\n            from_path: The path to the blob to download from; this gets prefixed\n                with the bucket_folder.\n            to_file_object: The file-like object to download the blob to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_file`.\n\n        Returns:\n            The file-like object that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with BytesIO() as buf:\n                gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n            ```\n\n            Download my_folder/notes.txt object to a BufferedWriter.\n            ```python\n                from prefect_gcp.cloud_storage import GcsBucket\n\n                gcs_bucket = GcsBucket.load(\"my-bucket\")\n                with open(\"notes.txt\", \"wb\") as f:\n                    gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n            ```\n        \"\"\"\n        bucket = await self.get_bucket()\n\n        bucket_path = self._join_bucket_folder(from_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n            f\"to file object.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.download_to_file, file_obj=to_file_object, **download_kwargs\n        )\n        return to_file_object\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads objects *within* a folder (excluding the folder itself)\n        from the object storage service to a folder.\n\n        Args:\n            from_folder: The path to the folder to download from; this gets prefixed\n                with the bucket_folder.\n            to_folder: The path to download the folder to. If not provided, will default\n                to the current directory.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_filename`.\n\n        Returns:\n            The absolute path that the folder was downloaded to.\n\n        Examples:\n            Download my_folder to a local folder named my_folder.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n            ```\n        \"\"\"\n        if to_folder is None:\n            to_folder = \"\"\n        to_folder = Path(to_folder).absolute()\n\n        blobs = await self.list_blobs(folder=from_folder)\n        if len(blobs) == 0:\n            self.logger.warning(\n                f\"No blobs were downloaded from \"\n                f\"bucket {self.bucket!r} path {from_folder!r}.\"\n            )\n            return to_folder\n\n        # do not call self._join_bucket_folder for list_blobs\n        # because it's built-in to that method already!\n        # however, we still need to do it because we're using relative_to\n        bucket_folder = self._join_bucket_folder(from_folder)\n\n        async_coros = []\n        for blob in blobs:\n            bucket_path = PurePosixPath(blob.name).relative_to(bucket_folder)\n            if str(bucket_path).endswith(\"/\"):\n                continue\n            to_path = to_folder / bucket_path\n            to_path.parent.mkdir(parents=True, exist_ok=True)\n            self.logger.info(\n                f\"Downloading blob from bucket {self.bucket!r} path \"\n                f\"{str(bucket_path)!r} to {to_path}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    blob.download_to_filename, filename=str(to_path), **download_kwargs\n                )\n            )\n        await asyncio.gather(*async_coros)\n\n        return to_folder\n\n    @sync_compatible\n    async def upload_from_path(\n        self,\n        from_path: Union[str, Path],\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object from a path to the object storage service.\n\n        Args:\n            from_path: The path to the file to upload from.\n            to_path: The path to upload the file to. If not provided, will use\n                the file name of from_path; this gets prefixed\n                with the bucket_folder.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_filename`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload notes.txt to my_folder/notes.txt.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        bucket_path = self._join_bucket_folder(to_path)\n        bucket = await self.get_bucket()\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Uploading from {from_path!r} to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.upload_from_filename, filename=from_path, **upload_kwargs\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object to the object storage service from a file-like object,\n        which can be a BytesIO object or a BufferedReader.\n\n        Args:\n            from_file_object: The file-like object to upload from.\n            to_path: The path to upload the object to; this gets prefixed\n                with the bucket_folder.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_file`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n            ```\n\n            Upload BufferedReader object to my_folder/notes.txt.\n            ```python\n            from io import BufferedReader\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                gcs_bucket.upload_from_file_object(\n                    BufferedReader(f), \"my_folder/notes.txt\"\n                )\n            ```\n        \"\"\"\n        bucket = await self.get_bucket()\n\n        bucket_path = self._join_bucket_folder(to_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Uploading from file object to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.upload_from_file, from_file_object, **upload_kwargs\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads files *within* a folder (excluding the folder itself)\n        to the object storage service folder.\n\n        Args:\n            from_folder: The path to the folder to upload from.\n            to_folder: The path to upload the folder to. If not provided, will default\n                to bucket_folder or the base directory of the bucket.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_filename`.\n\n        Returns:\n            The path that the folder was uploaded to.\n\n        Examples:\n            Upload local folder my_folder to the bucket's folder my_folder.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.upload_from_folder(\"my_folder\")\n            ```\n        \"\"\"\n        from_folder = Path(from_folder)\n        # join bucket folder expects string for the first input\n        # when it returns None, we need to convert it back to empty string\n        # so relative_to works\n        bucket_folder = self._join_bucket_folder(to_folder or \"\") or \"\"\n\n        num_uploaded = 0\n        bucket = await self.get_bucket()\n\n        async_coros = []\n        for from_path in from_folder.rglob(\"**/*\"):\n            if from_path.is_dir():\n                continue\n            bucket_path = str(Path(bucket_folder) / from_path.relative_to(from_folder))\n            self.logger.info(\n                f\"Uploading from {str(from_path)!r} to the bucket \"\n                f\"{self.bucket!r} path {bucket_path!r}.\"\n            )\n            blob = bucket.blob(bucket_path)\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    blob.upload_from_filename, filename=from_path, **upload_kwargs\n                )\n            )\n            num_uploaded += 1\n        await asyncio.gather(*async_coros)\n        if num_uploaded == 0:\n            self.logger.warning(f\"No files were uploaded from {from_folder}.\")\n        return bucket_folder\n\n    @sync_compatible\n    async def upload_from_dataframe(\n        self,\n        df: \"DataFrame\",\n        to_path: str,\n        serialization_format: Union[\n            str, DataFrameSerializationFormat\n        ] = DataFrameSerializationFormat.CSV_GZIP,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"Upload a Pandas DataFrame to Google Cloud Storage in various formats.\n\n        This function uploads the data in a Pandas DataFrame to Google Cloud Storage\n        in a specified format, such as .csv, .csv.gz, .parquet,\n        .parquet.snappy, and .parquet.gz.\n\n        Args:\n            df: The Pandas DataFrame to be uploaded.\n            to_path: The destination path for the uploaded DataFrame.\n            serialization_format: The format to serialize the DataFrame into.\n                When passed as a `str`, the valid options are:\n                'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'.\n                Defaults to `DataFrameSerializationFormat.CSV_GZIP`.\n            **upload_kwargs: Additional keyword arguments to pass to the underlying\n            `Blob.upload_from_dataframe` method.\n\n        Returns:\n            The path that the object was uploaded to.\n        \"\"\"\n        if isinstance(serialization_format, str):\n            serialization_format = DataFrameSerializationFormat[\n                serialization_format.upper()\n            ]\n\n        with BytesIO() as bytes_buffer:\n            if serialization_format.format == \"parquet\":\n                df.to_parquet(\n                    path=bytes_buffer,\n                    compression=serialization_format.compression,\n                    index=False,\n                )\n            elif serialization_format.format == \"csv\":\n                df.to_csv(\n                    path_or_buf=bytes_buffer,\n                    compression=serialization_format.compression,\n                    index=False,\n                )\n\n            bytes_buffer.seek(0)\n            to_path = serialization_format.fix_extension_with(gcs_blob_path=to_path)\n\n            return await self.upload_from_file_object(\n                from_file_object=bytes_buffer,\n                to_path=to_path,\n                **{\"content_type\": serialization_format.content_type, **upload_kwargs},\n            )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.basepath","title":"<code>basepath: str</code>  <code>property</code>","text":"<p>Read-only property that mirrors the bucket folder.</p> <p>Used for deployment.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.create_bucket","title":"<code>create_bucket</code>  <code>async</code>","text":"<p>Creates a bucket.</p> <p>Parameters:</p> Name Type Description Default <code>location</code> <code>Optional[str]</code> <p>The location of the bucket.</p> <code>None</code> <code>**create_kwargs</code> <p>Additional keyword arguments to pass to the <code>create_bucket</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Bucket</code> <p>The bucket object.</p> <p>Examples:</p> <p>Create a bucket. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket(bucket=\"my-bucket\")\ngcs_bucket.create_bucket()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def create_bucket(\n    self, location: Optional[str] = None, **create_kwargs\n) -&gt; \"Bucket\":\n    \"\"\"\n    Creates a bucket.\n\n    Args:\n        location: The location of the bucket.\n        **create_kwargs: Additional keyword arguments to pass to the\n            `create_bucket` method.\n\n    Returns:\n        The bucket object.\n\n    Examples:\n        Create a bucket.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket(bucket=\"my-bucket\")\n        gcs_bucket.create_bucket()\n        ```\n    \"\"\"\n    self.logger.info(f\"Creating bucket {self.bucket!r}.\")\n    client = self.gcp_credentials.get_cloud_storage_client()\n    bucket = await run_sync_in_worker_thread(\n        client.create_bucket, self.bucket, location=location, **create_kwargs\n    )\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Downloads objects within a folder (excluding the folder itself) from the object storage service to a folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The path to the folder to download from; this gets prefixed with the bucket_folder.</p> required <code>to_folder</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the folder to. If not provided, will default to the current directory.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the folder was downloaded to.</p> <p>Examples:</p> <p>Download my_folder to a local folder named my_folder. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads objects *within* a folder (excluding the folder itself)\n    from the object storage service to a folder.\n\n    Args:\n        from_folder: The path to the folder to download from; this gets prefixed\n            with the bucket_folder.\n        to_folder: The path to download the folder to. If not provided, will default\n            to the current directory.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The absolute path that the folder was downloaded to.\n\n    Examples:\n        Download my_folder to a local folder named my_folder.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n        ```\n    \"\"\"\n    if to_folder is None:\n        to_folder = \"\"\n    to_folder = Path(to_folder).absolute()\n\n    blobs = await self.list_blobs(folder=from_folder)\n    if len(blobs) == 0:\n        self.logger.warning(\n            f\"No blobs were downloaded from \"\n            f\"bucket {self.bucket!r} path {from_folder!r}.\"\n        )\n        return to_folder\n\n    # do not call self._join_bucket_folder for list_blobs\n    # because it's built-in to that method already!\n    # however, we still need to do it because we're using relative_to\n    bucket_folder = self._join_bucket_folder(from_folder)\n\n    async_coros = []\n    for blob in blobs:\n        bucket_path = PurePosixPath(blob.name).relative_to(bucket_folder)\n        if str(bucket_path).endswith(\"/\"):\n            continue\n        to_path = to_folder / bucket_path\n        to_path.parent.mkdir(parents=True, exist_ok=True)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path \"\n            f\"{str(bucket_path)!r} to {to_path}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                blob.download_to_filename, filename=str(to_path), **download_kwargs\n            )\n        )\n    await asyncio.gather(*async_coros)\n\n    return to_folder\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a file-like object, which can be a BytesIO object or a BufferedWriter.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the blob to download from; this gets prefixed with the bucket_folder.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file-like object to download the blob to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BinaryIO</code> <p>The file-like object that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith BytesIO() as buf:\n    gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n</code></pre></p> <p>Download my_folder/notes.txt object to a BufferedWriter. <pre><code>    from prefect_gcp.cloud_storage import GcsBucket\n\n    gcs_bucket = GcsBucket.load(\"my-bucket\")\n    with open(\"notes.txt\", \"wb\") as f:\n        gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; BinaryIO:\n    \"\"\"\n    Downloads an object from the object storage service to a file-like object,\n    which can be a BytesIO object or a BufferedWriter.\n\n    Args:\n        from_path: The path to the blob to download from; this gets prefixed\n            with the bucket_folder.\n        to_file_object: The file-like object to download the blob to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_file`.\n\n    Returns:\n        The file-like object that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with BytesIO() as buf:\n            gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n        ```\n\n        Download my_folder/notes.txt object to a BufferedWriter.\n        ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"wb\") as f:\n                gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n        ```\n    \"\"\"\n    bucket = await self.get_bucket()\n\n    bucket_path = self._join_bucket_folder(from_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n        f\"to file object.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.download_to_file, file_obj=to_file_object, **download_kwargs\n    )\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the blob to download; this gets prefixed with the bucket_folder.</p> required <code>to_path</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the blob to. If not provided, the blob's name will be used.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to notes.txt. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads an object from the object storage service to a path.\n\n    Args:\n        from_path: The path to the blob to download; this gets prefixed\n            with the bucket_folder.\n        to_path: The path to download the blob to. If not provided, the\n            blob's name will be used.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The absolute path that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to notes.txt.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # making path absolute, but converting back to str here\n    # since !r looks nicer that way and filename arg expects str\n    to_path = str(Path(to_path).absolute())\n\n    bucket = await self.get_bucket()\n    bucket_path = self._join_bucket_folder(from_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n        f\"to {to_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.download_to_filename, filename=to_path, **download_kwargs\n    )\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.get_bucket","title":"<code>get_bucket</code>  <code>async</code>","text":"<p>Returns the bucket object.</p> <p>Returns:</p> Type Description <code>Bucket</code> <p>The bucket object.</p> <p>Examples:</p> <p>Get the bucket object. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.get_bucket()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def get_bucket(self) -&gt; \"Bucket\":\n    \"\"\"\n    Returns the bucket object.\n\n    Returns:\n        The bucket object.\n\n    Examples:\n        Get the bucket object.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.get_bucket()\n        ```\n    \"\"\"\n    self.logger.info(f\"Getting bucket {self.bucket!r}.\")\n    client = self.gcp_credentials.get_cloud_storage_client()\n    bucket = await run_sync_in_worker_thread(client.get_bucket, self.bucket)\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a folder from the configured GCS bucket to a local directory. Defaults to copying the entire contents of the block's bucket_folder to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>Path in GCS bucket to download from. Defaults to the block's configured bucket_folder.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>Local path to download GCS bucket contents to. Defaults to the current working directory.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Union[str, Path]]</code> <p>A list of downloaded file paths.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; List[Union[str, Path]]:\n    \"\"\"\n    Copies a folder from the configured GCS bucket to a local directory.\n    Defaults to copying the entire contents of the block's bucket_folder\n    to the current working directory.\n\n    Args:\n        from_path: Path in GCS bucket to download from. Defaults to the block's\n            configured bucket_folder.\n        local_path: Local path to download GCS bucket contents to.\n            Defaults to the current working directory.\n\n    Returns:\n        A list of downloaded file paths.\n    \"\"\"\n    from_path = (\n        self.bucket_folder if from_path is None else self._resolve_path(from_path)\n    )\n\n    if local_path is None:\n        local_path = os.path.abspath(\".\")\n    else:\n        local_path = os.path.abspath(os.path.expanduser(local_path))\n\n    project = self.gcp_credentials.project\n    client = self.gcp_credentials.get_cloud_storage_client(project=project)\n\n    blobs = await run_sync_in_worker_thread(\n        client.list_blobs, self.bucket, prefix=from_path\n    )\n\n    file_paths = []\n    for blob in blobs:\n        blob_path = blob.name\n        if blob_path[-1] == \"/\":\n            # object is a folder and will be created if it contains any objects\n            continue\n        relative_blob_path = os.path.relpath(blob_path, from_path)\n        local_file_path = os.path.join(local_path, relative_blob_path)\n        os.makedirs(os.path.dirname(local_file_path), exist_ok=True)\n\n        with disable_run_logger():\n            file_path = await cloud_storage_download_blob_to_file.fn(\n                bucket=self.bucket,\n                blob=blob_path,\n                path=local_file_path,\n                gcp_credentials=self.gcp_credentials,\n            )\n            file_paths.append(file_path)\n    return file_paths\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.list_blobs","title":"<code>list_blobs</code>  <code>async</code>","text":"<p>Lists all blobs in the bucket that are in a folder. Folders are not included in the output.</p> <p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>The folder to list blobs from.</p> <code>''</code> <p>Returns:</p> Type Description <code>List[Blob]</code> <p>A list of Blob objects.</p> <p>Examples:</p> <p>Get all blobs from a folder named \"prefect\". <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_blobs(\"prefect\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def list_blobs(self, folder: str = \"\") -&gt; List[\"Blob\"]:\n    \"\"\"\n    Lists all blobs in the bucket that are in a folder.\n    Folders are not included in the output.\n\n    Args:\n        folder: The folder to list blobs from.\n\n    Returns:\n        A list of Blob objects.\n\n    Examples:\n        Get all blobs from a folder named \"prefect\".\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_blobs(\"prefect\")\n        ```\n    \"\"\"\n    client = self.gcp_credentials.get_cloud_storage_client()\n\n    bucket_path = self._join_bucket_folder(folder)\n    if bucket_path is None:\n        self.logger.info(f\"Listing blobs in bucket {self.bucket!r}.\")\n    else:\n        self.logger.info(\n            f\"Listing blobs in folder {bucket_path!r} in bucket {self.bucket!r}.\"\n        )\n    blobs = await run_sync_in_worker_thread(\n        client.list_blobs, self.bucket, prefix=bucket_path\n    )\n\n    # Ignore folders\n    return [blob for blob in blobs if not blob.name.endswith(\"/\")]\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.list_folders","title":"<code>list_folders</code>  <code>async</code>","text":"<p>Lists all folders and subfolders in the bucket.</p> <p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>List all folders and subfolders inside given folder.</p> <code>''</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>A list of folders.</p> <p>Examples:</p> <p>Get all folders from a bucket named \"my-bucket\". <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_folders()\n</code></pre></p> <p>Get all folders from a folder called years <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_folders(\"years\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def list_folders(self, folder: str = \"\") -&gt; List[str]:\n    \"\"\"\n    Lists all folders and subfolders in the bucket.\n\n    Args:\n        folder: List all folders and subfolders inside given folder.\n\n    Returns:\n        A list of folders.\n\n    Examples:\n        Get all folders from a bucket named \"my-bucket\".\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_folders()\n        ```\n\n        Get all folders from a folder called years\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_folders(\"years\")\n        ```\n    \"\"\"\n\n    # Beware of calling _join_bucket_folder twice, see note in method.\n    # However, we just want to use it to check if we are listing the root folder\n    bucket_path = self._join_bucket_folder(folder)\n    if bucket_path is None:\n        self.logger.info(f\"Listing folders in bucket {self.bucket!r}.\")\n    else:\n        self.logger.info(\n            f\"Listing folders in {bucket_path!r} in bucket {self.bucket!r}.\"\n        )\n\n    blobs = await self.list_blobs(folder)\n    # gets all folders with full path\n    folders = {str(PurePosixPath(blob.name).parent) for blob in blobs}\n\n    return [folder for folder in folders if folder != \".\"]\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to the configured GCS bucket in a given folder.</p> <p>Defaults to uploading the entire contents the current working directory to the block's bucket_folder.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>Optional[str]</code> <p>Path to local directory to upload from.</p> <code>None</code> <code>to_path</code> <code>Optional[str]</code> <p>Path in GCS bucket to upload to. Defaults to block's configured bucket_folder.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>Path to file containing gitignore style expressions for filepaths to ignore.</p> <code>None</code> <p>Returns:</p> Type Description <code>int</code> <p>The number of files uploaded.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to the configured GCS bucket in a\n    given folder.\n\n    Defaults to uploading the entire contents the current working directory to the\n    block's bucket_folder.\n\n    Args:\n        local_path: Path to local directory to upload from.\n        to_path: Path in GCS bucket to upload to. Defaults to block's configured\n            bucket_folder.\n        ignore_file: Path to file containing gitignore style expressions for\n            filepaths to ignore.\n\n    Returns:\n        The number of files uploaded.\n    \"\"\"\n    if local_path is None:\n        local_path = os.path.abspath(\".\")\n    else:\n        local_path = os.path.expanduser(local_path)\n\n    to_path = self.bucket_folder if to_path is None else self._resolve_path(to_path)\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(local_path, ignore_patterns)\n\n    uploaded_file_count = 0\n    for local_file_path in Path(local_path).rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = str(\n                PurePosixPath(to_path, local_file_path.relative_to(local_path))\n            )\n            local_file_content = local_file_path.read_bytes()\n            await self.write_path(remote_file_path, content=local_file_content)\n            uploaded_file_count += 1\n\n    return uploaded_file_count\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Read specified path from GCS and return contents. Provide the entire path to the key in GCS.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Entire path to (and including) the key.</p> required <p>Returns:</p> Type Description <code>bytes</code> <p>A bytes or string representation of the blob object.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Read specified path from GCS and return contents. Provide the entire\n    path to the key in GCS.\n\n    Args:\n        path: Entire path to (and including) the key.\n\n    Returns:\n        A bytes or string representation of the blob object.\n    \"\"\"\n    path = self._resolve_path(path)\n    with disable_run_logger():\n        contents = await cloud_storage_download_blob_as_bytes.fn(\n            bucket=self.bucket, blob=path, gcp_credentials=self.gcp_credentials\n        )\n    return contents\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_dataframe","title":"<code>upload_from_dataframe</code>  <code>async</code>","text":"<p>Upload a Pandas DataFrame to Google Cloud Storage in various formats.</p> <p>This function uploads the data in a Pandas DataFrame to Google Cloud Storage in a specified format, such as .csv, .csv.gz, .parquet, .parquet.snappy, and .parquet.gz.</p> <p>Parameters:</p> Name Type Description Default <code>df</code> <code>DataFrame</code> <p>The Pandas DataFrame to be uploaded.</p> required <code>to_path</code> <code>str</code> <p>The destination path for the uploaded DataFrame.</p> required <code>serialization_format</code> <code>Union[str, DataFrameSerializationFormat]</code> <p>The format to serialize the DataFrame into. When passed as a <code>str</code>, the valid options are: 'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'. Defaults to <code>DataFrameSerializationFormat.CSV_GZIP</code>.</p> <code>CSV_GZIP</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the underlying</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_dataframe(\n    self,\n    df: \"DataFrame\",\n    to_path: str,\n    serialization_format: Union[\n        str, DataFrameSerializationFormat\n    ] = DataFrameSerializationFormat.CSV_GZIP,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"Upload a Pandas DataFrame to Google Cloud Storage in various formats.\n\n    This function uploads the data in a Pandas DataFrame to Google Cloud Storage\n    in a specified format, such as .csv, .csv.gz, .parquet,\n    .parquet.snappy, and .parquet.gz.\n\n    Args:\n        df: The Pandas DataFrame to be uploaded.\n        to_path: The destination path for the uploaded DataFrame.\n        serialization_format: The format to serialize the DataFrame into.\n            When passed as a `str`, the valid options are:\n            'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'.\n            Defaults to `DataFrameSerializationFormat.CSV_GZIP`.\n        **upload_kwargs: Additional keyword arguments to pass to the underlying\n        `Blob.upload_from_dataframe` method.\n\n    Returns:\n        The path that the object was uploaded to.\n    \"\"\"\n    if isinstance(serialization_format, str):\n        serialization_format = DataFrameSerializationFormat[\n            serialization_format.upper()\n        ]\n\n    with BytesIO() as bytes_buffer:\n        if serialization_format.format == \"parquet\":\n            df.to_parquet(\n                path=bytes_buffer,\n                compression=serialization_format.compression,\n                index=False,\n            )\n        elif serialization_format.format == \"csv\":\n            df.to_csv(\n                path_or_buf=bytes_buffer,\n                compression=serialization_format.compression,\n                index=False,\n            )\n\n        bytes_buffer.seek(0)\n        to_path = serialization_format.fix_extension_with(gcs_blob_path=to_path)\n\n        return await self.upload_from_file_object(\n            from_file_object=bytes_buffer,\n            to_path=to_path,\n            **{\"content_type\": serialization_format.content_type, **upload_kwargs},\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object to the object storage service from a file-like object, which can be a BytesIO object or a BufferedReader.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file-like object to upload from.</p> required <code>to_path</code> <code>str</code> <p>The path to upload the object to; this gets prefixed with the bucket_folder.</p> required <code>**upload_kwargs</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n</code></pre></p> <p>Upload BufferedReader object to my_folder/notes.txt. <pre><code>from io import BufferedReader\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    gcs_bucket.upload_from_file_object(\n        BufferedReader(f), \"my_folder/notes.txt\"\n    )\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs\n) -&gt; str:\n    \"\"\"\n    Uploads an object to the object storage service from a file-like object,\n    which can be a BytesIO object or a BufferedReader.\n\n    Args:\n        from_file_object: The file-like object to upload from.\n        to_path: The path to upload the object to; this gets prefixed\n            with the bucket_folder.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_file`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n        ```\n\n        Upload BufferedReader object to my_folder/notes.txt.\n        ```python\n        from io import BufferedReader\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            gcs_bucket.upload_from_file_object(\n                BufferedReader(f), \"my_folder/notes.txt\"\n            )\n        ```\n    \"\"\"\n    bucket = await self.get_bucket()\n\n    bucket_path = self._join_bucket_folder(to_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Uploading from file object to the bucket \"\n        f\"{self.bucket!r} path {bucket_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.upload_from_file, from_file_object, **upload_kwargs\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files within a folder (excluding the folder itself) to the object storage service folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the folder to upload from.</p> required <code>to_folder</code> <code>Optional[str]</code> <p>The path to upload the folder to. If not provided, will default to bucket_folder or the base directory of the bucket.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the folder was uploaded to.</p> <p>Examples:</p> <p>Upload local folder my_folder to the bucket's folder my_folder. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.upload_from_folder(\"my_folder\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads files *within* a folder (excluding the folder itself)\n    to the object storage service folder.\n\n    Args:\n        from_folder: The path to the folder to upload from.\n        to_folder: The path to upload the folder to. If not provided, will default\n            to bucket_folder or the base directory of the bucket.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_filename`.\n\n    Returns:\n        The path that the folder was uploaded to.\n\n    Examples:\n        Upload local folder my_folder to the bucket's folder my_folder.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.upload_from_folder(\"my_folder\")\n        ```\n    \"\"\"\n    from_folder = Path(from_folder)\n    # join bucket folder expects string for the first input\n    # when it returns None, we need to convert it back to empty string\n    # so relative_to works\n    bucket_folder = self._join_bucket_folder(to_folder or \"\") or \"\"\n\n    num_uploaded = 0\n    bucket = await self.get_bucket()\n\n    async_coros = []\n    for from_path in from_folder.rglob(\"**/*\"):\n        if from_path.is_dir():\n            continue\n        bucket_path = str(Path(bucket_folder) / from_path.relative_to(from_folder))\n        self.logger.info(\n            f\"Uploading from {str(from_path)!r} to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n        blob = bucket.blob(bucket_path)\n        async_coros.append(\n            run_sync_in_worker_thread(\n                blob.upload_from_filename, filename=from_path, **upload_kwargs\n            )\n        )\n        num_uploaded += 1\n    await asyncio.gather(*async_coros)\n    if num_uploaded == 0:\n        self.logger.warning(f\"No files were uploaded from {from_folder}.\")\n    return bucket_folder\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a path to the object storage service.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path to the file to upload from.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to upload the file to. If not provided, will use the file name of from_path; this gets prefixed with the bucket_folder.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload notes.txt to my_folder/notes.txt. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self,\n    from_path: Union[str, Path],\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads an object from a path to the object storage service.\n\n    Args:\n        from_path: The path to the file to upload from.\n        to_path: The path to upload the file to. If not provided, will use\n            the file name of from_path; this gets prefixed\n            with the bucket_folder.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_filename`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload notes.txt to my_folder/notes.txt.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    bucket_path = self._join_bucket_folder(to_path)\n    bucket = await self.get_bucket()\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Uploading from {from_path!r} to the bucket \"\n        f\"{self.bucket!r} path {bucket_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.upload_from_filename, filename=from_path, **upload_kwargs\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes to an GCS bucket.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The key name. Each object in your bucket has a unique key (or key name).</p> required <code>content</code> <code>bytes</code> <p>What you are uploading to GCS Bucket.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The path that the contents were written to.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; str:\n    \"\"\"\n    Writes to an GCS bucket.\n\n    Args:\n        path: The key name. Each object in your bucket has a unique\n            key (or key name).\n        content: What you are uploading to GCS Bucket.\n\n    Returns:\n        The path that the contents were written to.\n    \"\"\"\n    path = self._resolve_path(path)\n    with disable_run_logger():\n        await cloud_storage_upload_blob_from_string.fn(\n            data=content,\n            bucket=self.bucket,\n            blob=path,\n            gcp_credentials=self.gcp_credentials,\n        )\n    return path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_copy_blob","title":"<code>cloud_storage_copy_blob</code>  <code>async</code>","text":"<p>Copies data from one Google Cloud Storage bucket to another, without downloading it locally.</p> <p>Parameters:</p> Name Type Description Default <code>source_bucket</code> <code>str</code> <p>Source bucket name.</p> required <code>dest_bucket</code> <code>str</code> <p>Destination bucket name.</p> required <code>source_blob</code> <code>str</code> <p>Source blob name.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>dest_blob</code> <code>Optional[str]</code> <p>Destination blob name; if not provided, defaults to source_blob.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**copy_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Bucket.copy_blob</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>Destination blob name.</p> Example <p>Copies blob from one bucket to another. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_copy_blob\n\n@flow()\ndef example_cloud_storage_copy_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_copy_blob(\n        \"source_bucket\",\n        \"dest_bucket\",\n        \"source_blob\",\n        gcp_credentials\n    )\n    return blob\n\nexample_cloud_storage_copy_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_copy_blob(\n    source_bucket: str,\n    dest_bucket: str,\n    source_blob: str,\n    gcp_credentials: GcpCredentials,\n    dest_blob: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **copy_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Copies data from one Google Cloud Storage bucket to another,\n    without downloading it locally.\n\n    Args:\n        source_bucket: Source bucket name.\n        dest_bucket: Destination bucket name.\n        source_blob: Source blob name.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        dest_blob: Destination blob name; if not provided, defaults to source_blob.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **copy_kwargs: Additional keyword arguments to pass to\n            `Bucket.copy_blob`.\n\n    Returns:\n        Destination blob name.\n\n    Example:\n        Copies blob from one bucket to another.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_copy_blob\n\n        @flow()\n        def example_cloud_storage_copy_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_copy_blob(\n                \"source_bucket\",\n                \"dest_bucket\",\n                \"source_blob\",\n                gcp_credentials\n            )\n            return blob\n\n        example_cloud_storage_copy_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Copying blob named %s from the %s bucket to the %s bucket\",\n        source_blob,\n        source_bucket,\n        dest_bucket,\n    )\n\n    source_bucket_obj = await _get_bucket(\n        source_bucket, gcp_credentials, project=project\n    )\n\n    dest_bucket_obj = await _get_bucket(dest_bucket, gcp_credentials, project=project)\n    if dest_blob is None:\n        dest_blob = source_blob\n\n    source_blob_obj = source_bucket_obj.blob(source_blob)\n    await run_sync_in_worker_thread(\n        source_bucket_obj.copy_blob,\n        blob=source_blob_obj,\n        destination_bucket=dest_bucket_obj,\n        new_name=dest_blob,\n        timeout=timeout,\n        **copy_kwargs,\n    )\n\n    return dest_blob\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_create_bucket","title":"<code>cloud_storage_create_bucket</code>  <code>async</code>","text":"<p>Creates a bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>location</code> <code>Optional[str]</code> <p>Location of the bucket.</p> <code>None</code> <code>**create_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.create_bucket</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The bucket name.</p> Example <p>Creates a bucket named \"prefect\". <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_create_bucket\n\n@flow()\ndef example_cloud_storage_create_bucket_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    bucket = cloud_storage_create_bucket(\"prefect\", gcp_credentials)\n\nexample_cloud_storage_create_bucket_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_create_bucket(\n    bucket: str,\n    gcp_credentials: GcpCredentials,\n    project: Optional[str] = None,\n    location: Optional[str] = None,\n    **create_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Creates a bucket.\n\n    Args:\n        bucket: Name of the bucket.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        location: Location of the bucket.\n        **create_kwargs: Additional keyword arguments to pass to `client.create_bucket`.\n\n    Returns:\n        The bucket name.\n\n    Example:\n        Creates a bucket named \"prefect\".\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_create_bucket\n\n        @flow()\n        def example_cloud_storage_create_bucket_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            bucket = cloud_storage_create_bucket(\"prefect\", gcp_credentials)\n\n        example_cloud_storage_create_bucket_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating %s bucket\", bucket)\n\n    client = gcp_credentials.get_cloud_storage_client(project=project)\n    await run_sync_in_worker_thread(\n        client.create_bucket, bucket, location=location, **create_kwargs\n    )\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_download_blob_as_bytes","title":"<code>cloud_storage_download_blob_as_bytes</code>  <code>async</code>","text":"<p>Downloads a blob as bytes.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>chunk_size</code> <code>int</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_as_bytes</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>bytes</code> <p>A bytes or string representation of the blob object.</p> Example <p>Downloads blob from bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_download_blob_as_bytes\n\n@flow()\ndef example_cloud_storage_download_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    contents = cloud_storage_download_blob_as_bytes(\n        \"bucket\", \"blob\", gcp_credentials)\n    return contents\n\nexample_cloud_storage_download_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_download_blob_as_bytes(\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; bytes:\n    \"\"\"\n    Downloads a blob as bytes.\n\n    Args:\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        chunk_size (int, optional): The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_as_bytes`.\n\n    Returns:\n        A bytes or string representation of the blob object.\n\n    Example:\n        Downloads blob from bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_download_blob_as_bytes\n\n        @flow()\n        def example_cloud_storage_download_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            contents = cloud_storage_download_blob_as_bytes(\n                \"bucket\", \"blob\", gcp_credentials)\n            return contents\n\n        example_cloud_storage_download_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading blob named %s from the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    contents = await run_sync_in_worker_thread(\n        blob_obj.download_as_bytes, timeout=timeout, **download_kwargs\n    )\n    return contents\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_download_blob_to_file","title":"<code>cloud_storage_download_blob_to_file</code>  <code>async</code>","text":"<p>Downloads a blob to a file path.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>path</code> <code>Union[str, Path]</code> <p>Downloads the contents to the provided file path; if the path is a directory, automatically joins the blob name.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>chunk_size</code> <code>int</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[str, Path]</code> <p>The path to the blob object.</p> Example <p>Downloads blob from bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_download_blob_to_file\n\n@flow()\ndef example_cloud_storage_download_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    path = cloud_storage_download_blob_to_file(\n        \"bucket\", \"blob\", \"file_path\", gcp_credentials)\n    return path\n\nexample_cloud_storage_download_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_download_blob_to_file(\n    bucket: str,\n    blob: str,\n    path: Union[str, Path],\n    gcp_credentials: GcpCredentials,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Union[str, Path]:\n    \"\"\"\n    Downloads a blob to a file path.\n\n    Args:\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        path: Downloads the contents to the provided file path;\n            if the path is a directory, automatically joins the blob name.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        chunk_size (int, optional): The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The path to the blob object.\n\n    Example:\n        Downloads blob from bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_download_blob_to_file\n\n        @flow()\n        def example_cloud_storage_download_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            path = cloud_storage_download_blob_to_file(\n                \"bucket\", \"blob\", \"file_path\", gcp_credentials)\n            return path\n\n        example_cloud_storage_download_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Downloading blob named %s from the %s bucket to %s\", blob, bucket, path\n    )\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    if os.path.isdir(path):\n        if isinstance(path, Path):\n            path = path.joinpath(blob)  # keep as Path if Path is passed\n        else:\n            path = os.path.join(path, blob)  # keep as str if a str is passed\n\n    await run_sync_in_worker_thread(\n        blob_obj.download_to_filename, path, timeout=timeout, **download_kwargs\n    )\n    return path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_file","title":"<code>cloud_storage_upload_blob_from_file</code>  <code>async</code>","text":"<p>Uploads a blob from file path or file-like object. Usage for passing in file-like object is if the data was downloaded from the web; can bypass writing to disk and directly upload to Cloud Storage.</p> <p>Parameters:</p> Name Type Description Default <code>file</code> <code>Union[str, Path, BytesIO]</code> <p>Path to data or file like object to upload.</p> required <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>content_type</code> <code>Optional[str]</code> <p>Type of content being uploaded.</p> <code>None</code> <code>chunk_size</code> <code>Optional[int]</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_file</code> or <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The blob name.</p> Example <p>Uploads blob to bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_file\n\n@flow()\ndef example_cloud_storage_upload_blob_from_file_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_upload_blob_from_file(\n        \"/path/somewhere\", \"bucket\", \"blob\", gcp_credentials)\n    return blob\n\nexample_cloud_storage_upload_blob_from_file_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_upload_blob_from_file(\n    file: Union[str, Path, BytesIO],\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    content_type: Optional[str] = None,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads a blob from file path or file-like object. Usage for passing in\n    file-like object is if the data was downloaded from the web;\n    can bypass writing to disk and directly upload to Cloud Storage.\n\n    Args:\n        file: Path to data or file like object to upload.\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        content_type: Type of content being uploaded.\n        chunk_size: The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_file` or `Blob.upload_from_filename`.\n\n    Returns:\n        The blob name.\n\n    Example:\n        Uploads blob to bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_file\n\n        @flow()\n        def example_cloud_storage_upload_blob_from_file_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_upload_blob_from_file(\n                \"/path/somewhere\", \"bucket\", \"blob\", gcp_credentials)\n            return blob\n\n        example_cloud_storage_upload_blob_from_file_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob named %s to the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    if isinstance(file, BytesIO):\n        await run_sync_in_worker_thread(\n            blob_obj.upload_from_file,\n            file,\n            content_type=content_type,\n            timeout=timeout,\n            **upload_kwargs,\n        )\n    else:\n        await run_sync_in_worker_thread(\n            blob_obj.upload_from_filename,\n            file,\n            content_type=content_type,\n            timeout=timeout,\n            **upload_kwargs,\n        )\n    return blob\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_string","title":"<code>cloud_storage_upload_blob_from_string</code>  <code>async</code>","text":"<p>Uploads a blob from a string or bytes representation of data.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Union[str, bytes]</code> <p>String or bytes representation of data to upload.</p> required <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>content_type</code> <code>Optional[str]</code> <p>Type of content being uploaded.</p> <code>None</code> <code>chunk_size</code> <code>Optional[int]</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_string</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The blob name.</p> Example <p>Uploads blob to bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_string\n\n@flow()\ndef example_cloud_storage_upload_blob_from_string_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_upload_blob_from_string(\n        \"data\", \"bucket\", \"blob\", gcp_credentials)\n    return blob\n\nexample_cloud_storage_upload_blob_from_string_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_upload_blob_from_string(\n    data: Union[str, bytes],\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    content_type: Optional[str] = None,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads a blob from a string or bytes representation of data.\n\n    Args:\n        data: String or bytes representation of data to upload.\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        content_type: Type of content being uploaded.\n        chunk_size: The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_string`.\n\n    Returns:\n        The blob name.\n\n    Example:\n        Uploads blob to bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_string\n\n        @flow()\n        def example_cloud_storage_upload_blob_from_string_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_upload_blob_from_string(\n                \"data\", \"bucket\", \"blob\", gcp_credentials)\n            return blob\n\n        example_cloud_storage_upload_blob_from_string_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob named %s to the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    await run_sync_in_worker_thread(\n        blob_obj.upload_from_string,\n        data,\n        content_type=content_type,\n        timeout=timeout,\n        **upload_kwargs,\n    )\n    return blob\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials","title":"<code>prefect_gcp.credentials</code>","text":"<p>Module handling GCP credentials.</p>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials","title":"<code>GcpCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with GCP. Google authentication is handled via the <code>google.oauth2</code> module or through the CLI. Specify either one of service <code>account_file</code> or <code>service_account_info</code>; if both are not specified, the client will try to detect the credentials following Google's Application Default Credentials. See Google's Authentication documentation for details on inference and recommended authentication patterns.</p> <p>Attributes:</p> Name Type Description <code>service_account_file</code> <code>Optional[Path]</code> <p>Path to the service account JSON keyfile.</p> <code>service_account_info</code> <code>Optional[SecretDict]</code> <p>The contents of the keyfile as a dict.</p> Example <p>Load GCP credentials stored in a <code>GCP Credentials</code> Block: <pre><code>from prefect_gcp import GcpCredentials\ngcp_credentials_block = GcpCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>class GcpCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with GCP. Google authentication is\n    handled via the `google.oauth2` module or through the CLI.\n    Specify either one of service `account_file` or `service_account_info`; if both\n    are not specified, the client will try to detect the credentials following Google's\n    [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials).\n    See Google's [Authentication documentation](https://cloud.google.com/docs/authentication#service-accounts)\n    for details on inference and recommended authentication patterns.\n\n    Attributes:\n        service_account_file: Path to the service account JSON keyfile.\n        service_account_info: The contents of the keyfile as a dict.\n\n    Example:\n        Load GCP credentials stored in a `GCP Credentials` Block:\n        ```python\n        from prefect_gcp import GcpCredentials\n        gcp_credentials_block = GcpCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _block_type_name = \"GCP Credentials\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials\"  # noqa: E501\n\n    service_account_file: Optional[Path] = Field(\n        default=None, description=\"Path to the service account JSON keyfile.\"\n    )\n    service_account_info: Optional[SecretDict] = Field(\n        default=None, description=\"The contents of the keyfile as a dict.\"\n    )\n    project: Optional[str] = Field(\n        default=None, description=\"The GCP project to use for the client.\"\n    )\n\n    _service_account_email: Optional[str] = None\n\n    def __hash__(self):\n        return hash(\n            (\n                hash(self.service_account_file),\n                hash(frozenset(self.service_account_info.dict().items()))\n                if self.service_account_info\n                else None,\n                hash(self.project),\n                hash(self._service_account_email),\n            )\n        )\n\n    @root_validator\n    def _provide_one_service_account_source(cls, values):\n        \"\"\"\n        Ensure that only a service account file or service account info ias provided.\n        \"\"\"\n        both_service_account = (\n            values.get(\"service_account_info\") is not None\n            and values.get(\"service_account_file\") is not None\n        )\n        if both_service_account:\n            raise ValueError(\n                \"Only one of service_account_info or service_account_file \"\n                \"can be specified at once\"\n            )\n        return values\n\n    @validator(\"service_account_file\")\n    def _check_service_account_file(cls, file):\n        \"\"\"Get full path of provided file and make sure that it exists.\"\"\"\n        if not file:\n            return file\n\n        service_account_file = Path(file).expanduser()\n        if not service_account_file.exists():\n            raise ValueError(\"The provided path to the service account is invalid\")\n        return service_account_file\n\n    @validator(\"service_account_info\", pre=True)\n    def _convert_json_string_json_service_account_info(cls, value):\n        \"\"\"\n        Converts service account info provided as a json formatted string\n        to a dictionary\n        \"\"\"\n        if isinstance(value, str):\n            try:\n                service_account_info = json.loads(value)\n                return service_account_info\n            except Exception:\n                raise ValueError(\"Unable to decode service_account_info\")\n        else:\n            return value\n\n    def block_initialization(self):\n        credentials = self.get_credentials_from_service_account()\n        if self.project is None:\n            if self.service_account_info or self.service_account_file:\n                credentials_project = credentials.project_id\n            # google.auth.default using gcloud auth application-default login\n            elif credentials.quota_project_id:\n                credentials_project = credentials.quota_project_id\n            # compute-assigned service account via GCP metadata server\n            else:\n                _, credentials_project = google.auth.default()\n            self.project = credentials_project\n\n        if hasattr(credentials, \"service_account_email\"):\n            self._service_account_email = credentials.service_account_email\n\n    def get_credentials_from_service_account(self) -&gt; Credentials:\n        \"\"\"\n        Helper method to serialize credentials by using either\n        service_account_file or service_account_info.\n        \"\"\"\n        if self.service_account_info:\n            credentials = Credentials.from_service_account_info(\n                self.service_account_info.get_secret_value(),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif self.service_account_file:\n            credentials = Credentials.from_service_account_file(\n                self.service_account_file,\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        else:\n            credentials, _ = google.auth.default()\n        return credentials\n\n    @sync_compatible\n    async def get_access_token(self):\n        \"\"\"\n        See: https://stackoverflow.com/a/69107745\n        Also: https://www.jhanley.com/google-cloud-creating-oauth-access-tokens-for-rest-api-calls/\n        \"\"\"  # noqa\n        request = google.auth.transport.requests.Request()\n        credentials = self.get_credentials_from_service_account()\n        await run_sync_in_worker_thread(credentials.refresh, request)\n        return credentials.token\n\n    def get_client(\n        self,\n        client_type: Union[str, ClientType],\n        **get_client_kwargs: Dict[str, Any],\n    ) -&gt; Any:\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The name of the client to get.\n            **get_client_kwargs: Additional keyword arguments to pass to the\n                `get_*_client` method.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, str):\n            client_type = ClientType(client_type)\n        client_type = client_type.value\n        get_client_method = getattr(self, f\"get_{client_type}_client\")\n        return get_client_method(**get_client_kwargs)\n\n    @_raise_help_msg(\"cloud_storage\")\n    def get_cloud_storage_client(\n        self, project: Optional[str] = None\n    ) -&gt; \"StorageClient\":\n        \"\"\"\n        Gets an authenticated Cloud Storage client.\n\n        Args:\n            project: Name of the project to use; overrides the base\n                class's project if provided.\n\n        Returns:\n            An authenticated Cloud Storage client.\n\n        Examples:\n            Gets a GCP Cloud Storage client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_cloud_storage_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_cloud_storage_client()\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # override class project if method project is provided\n        project = project or self.project\n        storage_client = StorageClient(credentials=credentials, project=project)\n        return storage_client\n\n    @_raise_help_msg(\"bigquery\")\n    def get_bigquery_client(\n        self, project: str = None, location: str = None\n    ) -&gt; \"BigQueryClient\":\n        \"\"\"\n        Gets an authenticated BigQuery client.\n\n        Args:\n            project: Name of the project to use; overrides the base\n                class's project if provided.\n            location: Location to use.\n\n        Returns:\n            An authenticated BigQuery client.\n\n        Examples:\n            Gets a GCP BigQuery client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_bigquery_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP BigQuery client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_bigquery_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # override class project if method project is provided\n        project = project or self.project\n        big_query_client = BigQueryClient(\n            credentials=credentials, project=project, location=location\n        )\n        return big_query_client\n\n    @_raise_help_msg(\"secret_manager\")\n    def get_secret_manager_client(self) -&gt; \"SecretManagerServiceClient\":\n        \"\"\"\n        Gets an authenticated Secret Manager Service client.\n\n        Returns:\n            An authenticated Secret Manager Service client.\n\n        Examples:\n            Gets a GCP Secret Manager client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_secret_manager_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_secret_manager_client()\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # doesn't accept project; must pass in project in tasks\n        secret_manager_client = SecretManagerServiceClient(credentials=credentials)\n        return secret_manager_client\n\n    @_raise_help_msg(\"aiplatform\")\n    def get_job_service_client(\n        self, client_options: Union[Dict[str, Any], ClientOptions] = None\n    ) -&gt; \"JobServiceClient\":\n        \"\"\"\n        Gets an authenticated Job Service client for Vertex AI.\n\n        Returns:\n            An authenticated Job Service client.\n\n        Examples:\n            Gets a GCP Job Service client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_job_service_client()\n\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_job_service_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        if isinstance(client_options, dict):\n            client_options = from_dict(client_options)\n\n        credentials = self.get_credentials_from_service_account()\n        return JobServiceClient(credentials=credentials, client_options=client_options)\n\n    @_raise_help_msg(\"aiplatform\")\n    def get_job_service_async_client(\n        self, client_options: Union[Dict[str, Any], ClientOptions] = None\n    ) -&gt; \"JobServiceAsyncClient\":\n        \"\"\"\n        Gets an authenticated Job Service async client for Vertex AI.\n\n        Returns:\n            An authenticated Job Service async client.\n\n        Examples:\n            Gets a GCP Job Service client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_job_service_async_client()\n\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_job_service_async_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        if isinstance(client_options, dict):\n            client_options = from_dict(client_options)\n\n        return _get_job_service_async_client_cached(\n            self, tuple(client_options.__dict__.items())\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_access_token","title":"<code>get_access_token</code>  <code>async</code>","text":"Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@sync_compatible\nasync def get_access_token(self):\n    \"\"\"\n    See: https://stackoverflow.com/a/69107745\n    Also: https://www.jhanley.com/google-cloud-creating-oauth-access-tokens-for-rest-api-calls/\n    \"\"\"  # noqa\n    request = google.auth.transport.requests.Request()\n    credentials = self.get_credentials_from_service_account()\n    await run_sync_in_worker_thread(credentials.refresh, request)\n    return credentials.token\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_bigquery_client","title":"<code>get_bigquery_client</code>","text":"<p>Gets an authenticated BigQuery client.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>str</code> <p>Name of the project to use; overrides the base class's project if provided.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location to use.</p> <code>None</code> <p>Returns:</p> Type Description <code>Client</code> <p>An authenticated BigQuery client.</p> <p>Examples:</p> <p>Gets a GCP BigQuery client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_bigquery_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP BigQuery client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_bigquery_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"bigquery\")\ndef get_bigquery_client(\n    self, project: str = None, location: str = None\n) -&gt; \"BigQueryClient\":\n    \"\"\"\n    Gets an authenticated BigQuery client.\n\n    Args:\n        project: Name of the project to use; overrides the base\n            class's project if provided.\n        location: Location to use.\n\n    Returns:\n        An authenticated BigQuery client.\n\n    Examples:\n        Gets a GCP BigQuery client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_bigquery_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP BigQuery client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_bigquery_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # override class project if method project is provided\n    project = project or self.project\n    big_query_client = BigQueryClient(\n        credentials=credentials, project=project, location=location\n    )\n    return big_query_client\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The name of the client to get.</p> required <code>**get_client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>get_*_client</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Any</code> <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>def get_client(\n    self,\n    client_type: Union[str, ClientType],\n    **get_client_kwargs: Dict[str, Any],\n) -&gt; Any:\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The name of the client to get.\n        **get_client_kwargs: Additional keyword arguments to pass to the\n            `get_*_client` method.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, str):\n        client_type = ClientType(client_type)\n    client_type = client_type.value\n    get_client_method = getattr(self, f\"get_{client_type}_client\")\n    return get_client_method(**get_client_kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_cloud_storage_client","title":"<code>get_cloud_storage_client</code>","text":"<p>Gets an authenticated Cloud Storage client.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the base class's project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>Client</code> <p>An authenticated Cloud Storage client.</p> <p>Examples:</p> <p>Gets a GCP Cloud Storage client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_cloud_storage_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_cloud_storage_client()\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"cloud_storage\")\ndef get_cloud_storage_client(\n    self, project: Optional[str] = None\n) -&gt; \"StorageClient\":\n    \"\"\"\n    Gets an authenticated Cloud Storage client.\n\n    Args:\n        project: Name of the project to use; overrides the base\n            class's project if provided.\n\n    Returns:\n        An authenticated Cloud Storage client.\n\n    Examples:\n        Gets a GCP Cloud Storage client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_cloud_storage_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_cloud_storage_client()\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # override class project if method project is provided\n    project = project or self.project\n    storage_client = StorageClient(credentials=credentials, project=project)\n    return storage_client\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_credentials_from_service_account","title":"<code>get_credentials_from_service_account</code>","text":"<p>Helper method to serialize credentials by using either service_account_file or service_account_info.</p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>def get_credentials_from_service_account(self) -&gt; Credentials:\n    \"\"\"\n    Helper method to serialize credentials by using either\n    service_account_file or service_account_info.\n    \"\"\"\n    if self.service_account_info:\n        credentials = Credentials.from_service_account_info(\n            self.service_account_info.get_secret_value(),\n            scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n        )\n    elif self.service_account_file:\n        credentials = Credentials.from_service_account_file(\n            self.service_account_file,\n            scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n        )\n    else:\n        credentials, _ = google.auth.default()\n    return credentials\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_job_service_async_client","title":"<code>get_job_service_async_client</code>","text":"<p>Gets an authenticated Job Service async client for Vertex AI.</p> <p>Returns:</p> Type Description <code>JobServiceAsyncClient</code> <p>An authenticated Job Service async client.</p> <p>Examples:</p> <p>Gets a GCP Job Service client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_job_service_async_client()\n\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_job_service_async_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"aiplatform\")\ndef get_job_service_async_client(\n    self, client_options: Union[Dict[str, Any], ClientOptions] = None\n) -&gt; \"JobServiceAsyncClient\":\n    \"\"\"\n    Gets an authenticated Job Service async client for Vertex AI.\n\n    Returns:\n        An authenticated Job Service async client.\n\n    Examples:\n        Gets a GCP Job Service client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_job_service_async_client()\n\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_job_service_async_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    if isinstance(client_options, dict):\n        client_options = from_dict(client_options)\n\n    return _get_job_service_async_client_cached(\n        self, tuple(client_options.__dict__.items())\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_job_service_client","title":"<code>get_job_service_client</code>","text":"<p>Gets an authenticated Job Service client for Vertex AI.</p> <p>Returns:</p> Type Description <code>JobServiceClient</code> <p>An authenticated Job Service client.</p> <p>Examples:</p> <p>Gets a GCP Job Service client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_job_service_client()\n\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_job_service_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"aiplatform\")\ndef get_job_service_client(\n    self, client_options: Union[Dict[str, Any], ClientOptions] = None\n) -&gt; \"JobServiceClient\":\n    \"\"\"\n    Gets an authenticated Job Service client for Vertex AI.\n\n    Returns:\n        An authenticated Job Service client.\n\n    Examples:\n        Gets a GCP Job Service client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_job_service_client()\n\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_job_service_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    if isinstance(client_options, dict):\n        client_options = from_dict(client_options)\n\n    credentials = self.get_credentials_from_service_account()\n    return JobServiceClient(credentials=credentials, client_options=client_options)\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_secret_manager_client","title":"<code>get_secret_manager_client</code>","text":"<p>Gets an authenticated Secret Manager Service client.</p> <p>Returns:</p> Type Description <code>SecretManagerServiceClient</code> <p>An authenticated Secret Manager Service client.</p> <p>Examples:</p> <p>Gets a GCP Secret Manager client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_secret_manager_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_secret_manager_client()\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"secret_manager\")\ndef get_secret_manager_client(self) -&gt; \"SecretManagerServiceClient\":\n    \"\"\"\n    Gets an authenticated Secret Manager Service client.\n\n    Returns:\n        An authenticated Secret Manager Service client.\n\n    Examples:\n        Gets a GCP Secret Manager client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_secret_manager_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_secret_manager_client()\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # doesn't accept project; must pass in project in tasks\n    secret_manager_client = SecretManagerServiceClient(credentials=credentials)\n    return secret_manager_client\n</code></pre>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/","title":"Google Cloud Run Worker Guide","text":""},{"location":"integrations/prefect-gcp/gcp-worker-guide/#why-use-google-cloud-run-for-flow-run-execution","title":"Why use Google Cloud Run for flow run execution?","text":"<p>Google Cloud Run is a fully managed compute platform that automatically scales your containerized applications.</p> <ol> <li> <p>Serverless architecture: Cloud Run follows a serverless architecture, which means you don't need to manage any underlying infrastructure. Google Cloud Run automatically handles the scaling and availability of your flow run infrastructure, allowing you to focus on developing and deploying your code.</p> </li> <li> <p>Scalability: Cloud Run can automatically scale your pipeline to handle varying workloads and traffic. It can quickly respond to increased demand and scale back down during low activity periods, ensuring efficient resource utilization.</p> </li> <li> <p>Integration with Google Cloud services: Google Cloud Run easily integrates with other Google Cloud services, such as Google Cloud Storage, Google Cloud Pub/Sub, and Google Cloud Build. This interoperability enables you to build end-to-end data pipelines that use a variety of services.</p> </li> <li> <p>Portability: Since Cloud Run uses container images, you can develop your pipelines locally using Docker and then deploy them on Google Cloud Run without significant modifications. This portability allows you to run the same pipeline in different environments.</p> </li> </ol>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#google-cloud-run-guide","title":"Google Cloud Run guide","text":"<p>After completing this guide, you will have:</p> <ol> <li>Created a Google Cloud Service Account</li> <li>Created a Prefect Work Pool</li> <li>Deployed a Prefect Worker as a Cloud Run Service</li> <li>Deployed a Flow</li> <li>Executed the Flow as a Google Cloud Run Job</li> </ol> <p>If you're looking for a general introduction to workers, work pools, and deployments, check out the workers and work pools tutorial.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#prerequisites","title":"Prerequisites","text":"<p>Before starting this guide, make sure you have:</p> <ul> <li>A Google Cloud Platform (GCP) account.</li> <li>A project on your GCP account where you have the necessary permissions to create Cloud Run Services and Service Accounts.</li> <li>The <code>gcloud</code> CLI installed on your local machine. You can follow Google Cloud's installation guide. If you're using Apple (or a Linux system) you can also use Homebrew for installation.</li> <li>Docker installed on your local machine.</li> <li>A Prefect server instance. You can sign up for a forever free Prefect Cloud Account or, alternatively, self-host a Prefect server.</li> </ul>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-1-create-a-google-cloud-service-account","title":"Step 1. Create a Google Cloud service account","text":"<p>First, open a terminal or command prompt on your local machine where <code>gcloud</code> is installed. If you haven't already authenticated with <code>gcloud</code>, run the following command and follow the instructions to log in to your GCP account.</p> <pre><code>gcloud auth login\n</code></pre> <p>Next, you'll set your project where you'd like to create the service account. Use the following command and replace <code>&lt;PROJECT_ID&gt;</code> with your GCP project's ID.</p> <pre><code>gcloud config set project &lt;PROJECT-ID&gt;\n</code></pre> <p>For example, if your project's ID is <code>prefect-project</code> the command will look like this:</p> <pre><code>gcloud config set project prefect-project\n</code></pre> <p>Now you're ready to make the service account. To do so, you'll need to run this command:</p> <pre><code>gcloud iam service-accounts create &lt;SERVICE-ACCOUNT-NAME&gt; --display-name=\"&lt;DISPLAY-NAME&gt;\"\n</code></pre> <p>Here's an example of the command above which you can use which already has the service account name and display name provided. An additional option to describe the service account has also been added:</p> <pre><code>gcloud iam service-accounts create prefect-service-account \\\n    --description=\"service account to use for the prefect worker\" \\\n    --display-name=\"prefect-service-account\"\n</code></pre> <p>The last step of this process is to make sure the service account has the proper permissions to execute flow runs as Cloud Run jobs. Run the following commands to grant the necessary permissions:</p> <p><pre><code>gcloud projects add-iam-policy-binding &lt;PROJECT-ID&gt; \\\n    --member=\"serviceAccount:&lt;SERVICE-ACCOUNT-NAME&gt;@&lt;PROJECT-ID&gt;.iam.gserviceaccount.com\" \\\n    --role=\"roles/iam.serviceAccountUser\"\n</code></pre> <pre><code>gcloud projects add-iam-policy-binding &lt;PROJECT-ID&gt; \\\n    --member=\"serviceAccount:&lt;SERVICE-ACCOUNT-NAME&gt;@&lt;PROJECT-ID&gt;.iam.gserviceaccount.com\" \\\n    --role=\"roles/run.admin\"\n</code></pre></p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-2-create-a-cloud-run-work-pool","title":"Step 2. Create a Cloud Run work pool","text":"<p>Let's walk through the process of creating a Cloud Run work pool.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#fill-out-the-work-pool-base-job-template","title":"Fill out the work pool base job template","text":"<p>You can create a new work pool using the Prefect UI or CLI. The following command creates a work pool of type <code>cloud-run</code> via the CLI (you'll want to replace the <code>&lt;WORK-POOL-NAME&gt;</code> with the name of your work pool): <pre><code>prefect work-pool create --type cloud-run &lt;WORK-POOL-NAME&gt;\n</code></pre></p> <p>Once the work pool is created, find the work pool in the UI and edit it.</p> <p>There are many ways to customize the base job template for the work pool. Modifying the template influences the infrastructure configuration that the worker provisions for flow runs submitted to the work pool. For this guide we are going to modify just a few of the available fields.</p> <p>Specify the region for the cloud run job.</p> <p></p> <p>Save the name of the service account created in first step of this guide.</p> <p></p> <p>Your work pool is now ready to receive scheduled flow runs!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-3-deploy-a-cloud-run-worker","title":"Step 3. Deploy a Cloud Run worker","text":"<p>Now you can launch a Cloud Run service to host the Cloud Run worker. This worker will poll the work pool that you created in the previous step.</p> <p>Navigate back to your terminal and run the following commands to set your Prefect API key and URL as environment variables. Be sure to replace <code>&lt;ACCOUNT-ID&gt;</code> and <code>&lt;WORKSPACE-ID&gt;</code> with your Prefect account and workspace IDs (both will be available in the URL of the UI when previewing the workspace dashboard). You'll want to replace <code>&lt;YOUR-API-KEY&gt;</code> with an active API key as well.</p> <pre><code>export PREFECT_API_URL='https://api.prefect.cloud/api/accounts/&lt;ACCOUNT-ID&gt;/workspaces/&lt;WORKSPACE-ID&gt;'\nexport PREFECT_API_KEY='&lt;YOUR-API-KEY&gt;'\n</code></pre> <p>Once those variables are set, run the following shell command to deploy your worker as a service. Don't forget to replace <code>&lt;YOUR-SERVICE-ACCOUNT-NAME&gt;</code> with the name of the service account you created in the first step of this guide, and replace <code>&lt;WORK-POOL-NAME&gt;</code> with the name of the work pool you created in the second step.</p> <pre><code>gcloud run deploy prefect-worker --image=prefecthq/prefect:2-latest \\\n--set-env-vars PREFECT_API_URL=$PREFECT_API_URL,PREFECT_API_KEY=$PREFECT_API_KEY \\\n--service-account &lt;YOUR-SERVICE-ACCOUNT-NAME&gt; \\\n--no-cpu-throttling \\\n--min-instances 1 \\\n--args \"prefect\",\"worker\",\"start\",\"--install-policy\",\"always\",\"--with-healthcheck\",\"-p\",\"&lt;WORK-POOL-NAME&gt;\",\"-t\",\"cloud-run\"\n</code></pre> <p>After running this command, you'll be prompted to specify a region. Choose the same region that you selected when creating the Cloud Run work pool in the second step of this guide. The next prompt will ask if you'd like to allow unauthentiated invocations to your worker. For this guide, you can select \"No\".</p> <p>After a few seconds, you'll be able to see your new <code>prefect-worker</code> service by navigating to the Cloud Run page of your Google Cloud console. Additionally, you should be able to see a record of this worker in the Prefect UI on the work pool's page by navigating to the <code>Worker</code> tab. Let's not leave our worker hanging, it's time to give it a job.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-4-deploy-a-flow","title":"Step 4. Deploy a flow","text":"<p>Let's prepare a flow to run as a Cloud Run job. In this section of the guide, we'll \"bake\" our code into a Docker image, and push that image to Google Artifact Registry.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#create-a-registry","title":"Create a registry","text":"<p>Let's create a docker repository in your Google Artifact Registry to host your custom image. If you already have a registry, and are authenticated to it, skip ahead to the Write a flow section.</p> <p>The following command creates a repository using the gcloud CLI. You'll want to replace the <code>&lt;REPOSITORY-NAME&gt;</code> with your own value. : <pre><code>gcloud artifacts repositories create &lt;REPOSITORY-NAME&gt; \\\n--repository-format=docker --location=us\n</code></pre></p> <p>Now you can authenticate to artifact registry: <pre><code>gcloud auth configure-docker us-docker.pkg.dev\n</code></pre></p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#write-a-flow","title":"Write a flow","text":"<p>First, create a new directory. This will serve as the root of your project's repository. Within the directory, create a sub-directory called <code>flows</code>. Navigate to the <code>flows</code> subdirectory and create a new file for your flow. Feel free to write your own flow, but here's a ready-made one for your convenience:</p> <pre><code>import httpx\nfrom prefect import flow, task\nfrom prefect.artifacts import create_markdown_artifact\n\n@task\ndef mark_it_down(temp):\n    markdown_report = f\"\"\"# Weather Report\n## Recent weather\n\n| Time        | Temperature |\n|:--------------|-------:|\n| Now | {temp} |\n| In 1 hour       | {temp + 2} |\n\"\"\"\n    create_markdown_artifact(\n        key=\"weather-report\",\n        markdown=markdown_report,\n        description=\"Very scientific weather report\",\n    )\n\n\n@flow\ndef fetch_weather(lat: float, lon: float):\n    base_url = \"https://api.open-meteo.com/v1/forecast/\"\n    weather = httpx.get(\n        base_url,\n        params=dict(latitude=lat, longitude=lon, hourly=\"temperature_2m\"),\n    )\n    most_recent_temp = float(weather.json()[\"hourly\"][\"temperature_2m\"][0])\n    mark_it_down(most_recent_temp)\n\n\nif __name__ == \"__main__\":\n    fetch_weather(38.9, -77.0)\n</code></pre> <p>In the remainder of this guide, this script will be referred to as <code>weather_flow.py</code>, but you can name yours whatever you'd like.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#creating-a-prefectyaml-file","title":"Creating a <code>prefect.yaml</code> file","text":"<p>Now we're ready to make a <code>prefect.yaml</code> file, which will be responsible for managing the deployments of this repository. Navigate back to the root of your directory, and run the following command to create a <code>prefect.yaml</code> file using Prefect's docker deployment recipe.</p> <pre><code>prefect init --recipe docker\n</code></pre> <p>You'll receive a prompt to put in values for the image name and tag. Since we will be pushing the image to Google Artifact Registry, the name of your image should be prefixed with the path to the docker repository you created within the registry. For example: <code>us-docker.pkg.dev/&lt;PROJECT-ID&gt;/&lt;REPOSITORY-NAME&gt;/</code>. You'll want to replace <code>&lt;PROJECT-ID&gt;</code> with the ID of your project in GCP. This should match the ID of the project you used in first step of this guide. Here is an example of what this could look like:</p> <pre><code>image_name: us-docker.pkg.dev/prefect-project/my-artifact-registry/gcp-weather-image\ntag: latest\n</code></pre> <p>At this point, there will be a new <code>prefect.yaml</code> file available at the root of your project. The contents will look similar to the example below, however, I've added in a combination of yaml templating options and prefect deployment actions to build out a simple CI/CD process. Feel free to copy the contents and paste them in your prefect.yaml:</p> <pre><code># Welcome to your prefect.yaml file! You can you this file for storing and managing\n# configuration for deploying your flows. We recommend committing this file to source\n# control along with your flow code.\n\n# Generic metadata about this project\nname: &lt;WORKING-DIRECTORY&gt;\nprefect-version: 2.13.4\n\n# build section allows you to manage and build docker image\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build_image\n    requires: prefect-docker&gt;=0.3.1\n    image_name: &lt;PATH-TO-ARTIFACT-REGISTRY&gt;/gcp-weather-image\n    tag: latest\n    dockerfile: auto\n    platform: linux/amd64\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.3.1\n    image_name: '{{ build_image.image_name }}'\n    tag: '{{ build_image.tag }}'\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /opt/prefect/&lt;WORKING-DIRECTORY&gt;\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: gcp-weather-deploy\n  version: null\n  tags: []\n  description: null\n  schedule: {}\n  flow_name: null\n  entrypoint: flows/weather_flow.py:fetch_weather\n  parameters:\n    lat: 14.5994\n    lon: 28.6731\n  work_pool:\n    name: my-cloud-run-pool\n    work_queue_name: default\n    job_variables:\n      image: '{{ build_image.image }}'\n</code></pre> <p>Tip</p> <p>After copying the example above, don't forget to replace <code>&lt;WORKING-DIRECTORY&gt;</code> with the name of the directory where your flow folder and <code>prefect.yaml</code> live. You'll also need to replace <code>&lt;PATH-TO-ARTIFACT-REGISTRY&gt;</code> with the path to the Docker repository in your Google Artifact Registry. </p> <p>To get a better understanding of the different components of the <code>prefect.yaml</code> file above and what they do, feel free to read this next section. Otherwise, you can skip ahead to Flow Deployment.</p> <p>In the <code>build</code> section of the <code>prefect.yaml</code> the following step is executed at deployment build time:</p> <ol> <li><code>prefect_docker.deployments.steps.build_docker_image</code> : builds a Docker image automatically which uses the name and tag chosen previously.</li> </ol> <p>Warning</p> <p>If you are using an ARM-based chip (such as an M1 or M2 Mac), you'll want to ensure that you add <code>platform: linux/amd64</code> to your <code>build_docker_image</code> step to ensure that your docker image uses an AMD architecture. For example:</p> <pre><code>- prefect_docker.deployments.steps.build_docker_image:\nid: build_image\nrequires: prefect-docker&gt;=0.3.1\nimage_name: us-docker.pkg.dev/prefect-project/my-docker-repository/gcp-weather-image\ntag: latest\ndockerfile: auto\nplatform: linux/amd64\n</code></pre> <p>The <code>push</code> section sends the Docker image to the Docker repository in your Google Artifact Registry, so that it can be easily accessed by the worker for flow run execution.</p> <p>The <code>pull</code> section sets the working directory for the process prior to importing your flow.</p> <p>In the <code>deployments</code> section of the <code>prefect.yaml</code> file above, you'll see that there is a deployment declaration named <code>gcp-weather-deploy</code>. Within the declaration, the entrypoint for the flow is specified along with some default parameters which will be passed to the flow at runtime. Last but not least, the name of the workpool that we created in step 2 of this guide is specified.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#flow-deployment","title":"Flow deployment","text":"<p>Once you're happy with the specifications in the <code>prefect.yaml</code> file, run the following command in the terminal to deploy your flow:</p> <pre><code>prefect deploy --name gcp-weather-deploy\n</code></pre> <p>Once the flow is deployed to Prefect Cloud or your local Prefect Server, it's time to queue up a flow run!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-5-flow-execution","title":"Step 5. Flow execution","text":"<p>Find your deployment in the UI, and hit the Quick Run button. You have now successfully submitted a flow run to your Cloud Run worker! If you used the flow script provided in this guide, check the Artifacts tab for the flow run once it completes. You'll have a nice little weather report waiting for you there. Hope your day is a sunny one!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#recap-and-next-steps","title":"Recap and next steps","text":"<p>Congratulations on completing this guide! Looking back on our journey, you have:</p> <ol> <li>Created a Google Cloud service account</li> <li>Created a Cloud Run work pool</li> <li>Deployed a Cloud Run worker</li> <li>Deployed a flow</li> <li>Executed a flow</li> </ol> <p>For next steps, you could:</p> <ul> <li>Take a look at some of the other work pools Prefect has to offer</li> <li>Do a deep drive on Prefect concepts</li> <li>Try out another guide to explore new deployment patterns and recipes</li> </ul> <p>The world is your oyster \ud83e\uddaa\u2728.</p>"},{"location":"integrations/prefect-gcp/secret_manager/","title":"Secret Manager","text":""},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager","title":"<code>prefect_gcp.secret_manager</code>","text":""},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret","title":"<code>GcpSecret</code>","text":"<p>               Bases: <code>SecretBlock</code></p> <p>Manages a secret in Google Cloud Platform's Secret Manager.</p> <p>Attributes:</p> Name Type Description <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> <code>secret_name</code> <code>str</code> <p>Name of the secret to manage.</p> <code>secret_version</code> <code>str</code> <p>Version number of the secret to use, or \"latest\".</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>class GcpSecret(SecretBlock):\n    \"\"\"\n    Manages a secret in Google Cloud Platform's Secret Manager.\n\n    Attributes:\n        gcp_credentials: Credentials to use for authentication with GCP.\n        secret_name: Name of the secret to manage.\n        secret_version: Version number of the secret to use, or \"latest\".\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret\"  # noqa: E501\n\n    gcp_credentials: GcpCredentials\n    secret_name: str = Field(default=..., description=\"Name of the secret to manage.\")\n    secret_version: str = Field(\n        default=\"latest\", description=\"Version number of the secret to use.\"\n    )\n\n    @sync_compatible\n    async def read_secret(self) -&gt; bytes:\n        \"\"\"\n        Reads the secret data from the secret storage service.\n\n        Returns:\n            The secret data as bytes.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n        name = f\"projects/{project}/secrets/{self.secret_name}/versions/{self.secret_version}\"  # noqa\n        request = AccessSecretVersionRequest(name=name)\n\n        self.logger.debug(f\"Preparing to read secret data from {name!r}.\")\n        response = await run_sync_in_worker_thread(\n            client.access_secret_version, request=request\n        )\n        secret = response.payload.data\n        self.logger.info(f\"The secret {name!r} data was successfully read.\")\n        return secret\n\n    @sync_compatible\n    async def write_secret(self, secret_data: bytes) -&gt; str:\n        \"\"\"\n        Writes the secret data to the secret storage service; if it doesn't exist\n        it will be created.\n\n        Args:\n            secret_data: The secret to write.\n\n        Returns:\n            The path that the secret was written to.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n        parent = f\"projects/{project}/secrets/{self.secret_name}\"\n        payload = SecretPayload(data=secret_data)\n        add_request = AddSecretVersionRequest(parent=parent, payload=payload)\n\n        self.logger.debug(f\"Preparing to write secret data to {parent!r}.\")\n        try:\n            response = await run_sync_in_worker_thread(\n                client.add_secret_version, request=add_request\n            )\n        except NotFound:\n            self.logger.info(\n                f\"The secret {parent!r} does not exist yet, creating it now.\"\n            )\n            create_parent = f\"projects/{project}\"\n            secret_id = self.secret_name\n            secret = Secret(replication=Replication(automatic=Replication.Automatic()))\n            create_request = CreateSecretRequest(\n                parent=create_parent, secret_id=secret_id, secret=secret\n            )\n            await run_sync_in_worker_thread(\n                client.create_secret, request=create_request\n            )\n\n            self.logger.debug(f\"Preparing to write secret data to {parent!r} again.\")\n            response = await run_sync_in_worker_thread(\n                client.add_secret_version, request=add_request\n            )\n\n        self.logger.info(f\"The secret data was written successfully to {parent!r}.\")\n        return response.name\n\n    @sync_compatible\n    async def delete_secret(self) -&gt; str:\n        \"\"\"\n        Deletes the secret from the secret storage service.\n\n        Returns:\n            The path that the secret was deleted from.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n\n        name = f\"projects/{project}/secrets/{self.secret_name}\"\n        request = DeleteSecretRequest(name=name)\n\n        self.logger.debug(f\"Preparing to delete the secret {name!r}.\")\n        await run_sync_in_worker_thread(client.delete_secret, request=request)\n        self.logger.info(f\"The secret {name!r} was successfully deleted.\")\n        return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the secret from the secret storage service.</p> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was deleted from.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def delete_secret(self) -&gt; str:\n    \"\"\"\n    Deletes the secret from the secret storage service.\n\n    Returns:\n        The path that the secret was deleted from.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{self.secret_name}\"\n    request = DeleteSecretRequest(name=name)\n\n    self.logger.debug(f\"Preparing to delete the secret {name!r}.\")\n    await run_sync_in_worker_thread(client.delete_secret, request=request)\n    self.logger.info(f\"The secret {name!r} was successfully deleted.\")\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the secret data from the secret storage service.</p> <p>Returns:</p> Type Description <code>bytes</code> <p>The secret data as bytes.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def read_secret(self) -&gt; bytes:\n    \"\"\"\n    Reads the secret data from the secret storage service.\n\n    Returns:\n        The secret data as bytes.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n    name = f\"projects/{project}/secrets/{self.secret_name}/versions/{self.secret_version}\"  # noqa\n    request = AccessSecretVersionRequest(name=name)\n\n    self.logger.debug(f\"Preparing to read secret data from {name!r}.\")\n    response = await run_sync_in_worker_thread(\n        client.access_secret_version, request=request\n    )\n    secret = response.payload.data\n    self.logger.info(f\"The secret {name!r} data was successfully read.\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.write_secret","title":"<code>write_secret</code>  <code>async</code>","text":"<p>Writes the secret data to the secret storage service; if it doesn't exist it will be created.</p> <p>Parameters:</p> Name Type Description Default <code>secret_data</code> <code>bytes</code> <p>The secret to write.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was written to.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def write_secret(self, secret_data: bytes) -&gt; str:\n    \"\"\"\n    Writes the secret data to the secret storage service; if it doesn't exist\n    it will be created.\n\n    Args:\n        secret_data: The secret to write.\n\n    Returns:\n        The path that the secret was written to.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n    parent = f\"projects/{project}/secrets/{self.secret_name}\"\n    payload = SecretPayload(data=secret_data)\n    add_request = AddSecretVersionRequest(parent=parent, payload=payload)\n\n    self.logger.debug(f\"Preparing to write secret data to {parent!r}.\")\n    try:\n        response = await run_sync_in_worker_thread(\n            client.add_secret_version, request=add_request\n        )\n    except NotFound:\n        self.logger.info(\n            f\"The secret {parent!r} does not exist yet, creating it now.\"\n        )\n        create_parent = f\"projects/{project}\"\n        secret_id = self.secret_name\n        secret = Secret(replication=Replication(automatic=Replication.Automatic()))\n        create_request = CreateSecretRequest(\n            parent=create_parent, secret_id=secret_id, secret=secret\n        )\n        await run_sync_in_worker_thread(\n            client.create_secret, request=create_request\n        )\n\n        self.logger.debug(f\"Preparing to write secret data to {parent!r} again.\")\n        response = await run_sync_in_worker_thread(\n            client.add_secret_version, request=add_request\n        )\n\n    self.logger.info(f\"The secret data was written successfully to {parent!r}.\")\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.create_secret","title":"<code>create_secret</code>  <code>async</code>","text":"<p>Creates a secret in Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the created secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import create_secret\n\n@flow()\ndef example_cloud_storage_create_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = create_secret(\"secret_name\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_create_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def create_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Creates a secret in Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the created secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import create_secret\n\n        @flow()\n        def example_cloud_storage_create_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = create_secret(\"secret_name\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_create_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating the %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    parent = f\"projects/{project}\"\n    secret_settings = {\"replication\": {\"automatic\": {}}}\n\n    partial_create = partial(\n        client.create_secret,\n        parent=parent,\n        secret_id=secret_name,\n        secret=secret_settings,\n        timeout=timeout,\n    )\n    response = await to_thread.run_sync(partial_create)\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the specified secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to delete.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the deleted secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import delete_secret\n\n@flow()\ndef example_cloud_storage_delete_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = delete_secret(\"secret_name\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_delete_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def delete_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Deletes the specified secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to delete.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the deleted secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import delete_secret\n\n        @flow()\n        def example_cloud_storage_delete_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = delete_secret(\"secret_name\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_delete_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Deleting %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{secret_name}/\"\n    partial_delete = partial(client.delete_secret, name=name, timeout=timeout)\n    await to_thread.run_sync(partial_delete)\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.delete_secret_version","title":"<code>delete_secret_version</code>  <code>async</code>","text":"<p>Deletes a version of a given secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>version_id</code> <code>int</code> <p>Version number of the secret to use; \"latest\" can NOT be used.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the deleted secret version.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import delete_secret_version\n\n@flow()\ndef example_cloud_storage_delete_secret_version_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_value = delete_secret_version(\"secret_name\", 1, gcp_credentials)\n    return secret_value\n\nexample_cloud_storage_delete_secret_version_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def delete_secret_version(\n    secret_name: str,\n    version_id: int,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Deletes a version of a given secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        version_id: Version number of the secret to use; \"latest\" can NOT be used.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the deleted secret version.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import delete_secret_version\n\n        @flow()\n        def example_cloud_storage_delete_secret_version_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_value = delete_secret_version(\"secret_name\", 1, gcp_credentials)\n            return secret_value\n\n        example_cloud_storage_delete_secret_version_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Reading %s version of %s secret\", version_id, secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    if version_id == \"latest\":\n        raise ValueError(\"The version_id cannot be 'latest'\")\n\n    name = f\"projects/{project}/secrets/{secret_name}/versions/{version_id}\"\n    partial_destroy = partial(client.destroy_secret_version, name=name, timeout=timeout)\n    await to_thread.run_sync(partial_destroy)\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the value of a given secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>Contents of the specified secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import read_secret\n\n@flow()\ndef example_cloud_storage_read_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_value = read_secret(\"secret_name\", gcp_credentials, version_id=1)\n    return secret_value\n\nexample_cloud_storage_read_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def read_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    version_id: Union[str, int] = \"latest\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Reads the value of a given secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        Contents of the specified secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import read_secret\n\n        @flow()\n        def example_cloud_storage_read_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_value = read_secret(\"secret_name\", gcp_credentials, version_id=1)\n            return secret_value\n\n        example_cloud_storage_read_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Reading %s version of %s secret\", version_id, secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{secret_name}/versions/{version_id}\"\n    partial_access = partial(client.access_secret_version, name=name, timeout=timeout)\n    response = await to_thread.run_sync(partial_access)\n    secret = response.payload.data.decode(\"UTF-8\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.update_secret","title":"<code>update_secret</code>  <code>async</code>","text":"<p>Updates a secret in Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>Desired value of the secret. Can be either <code>str</code> or <code>bytes</code>.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the updated secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import update_secret\n\n@flow()\ndef example_cloud_storage_update_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = update_secret(\"secret_name\", \"secret_value\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_update_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def update_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Updates a secret in Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        secret_value: Desired value of the secret. Can be either `str` or `bytes`.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the updated secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import update_secret\n\n        @flow()\n        def example_cloud_storage_update_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = update_secret(\"secret_name\", \"secret_value\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_update_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Updating the %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    parent = f\"projects/{project}/secrets/{secret_name}\"\n    if isinstance(secret_value, str):\n        secret_value = secret_value.encode(\"UTF-8\")\n    partial_add = partial(\n        client.add_secret_version,\n        parent=parent,\n        payload={\"data\": secret_value},\n        timeout=timeout,\n    )\n    response = await to_thread.run_sync(partial_add)\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/","title":"Vertex AI","text":""},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex","title":"<code>prefect_gcp.workers.vertex</code>","text":"<p>Module containing the custom worker used for executing flow runs as Vertex AI Custom Jobs.</p> <p>Get started by creating a Cloud Run work pool:</p> <pre><code>prefect work-pool create 'my-vertex-pool' --type vertex-ai\n</code></pre> <p>Then start a Cloud Run worker with the following command:</p> <pre><code>prefect worker start --pool 'my-vertex-pool'\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex--configuration","title":"Configuration","text":"<p>Read more about configuring work pools here.</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker","title":"<code>VertexAIWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Vertex AI Jobs.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Vertex AI Jobs.\"\"\"\n\n    type = \"vertex-ai\"\n    job_configuration = VertexAIWorkerJobConfiguration\n    job_configuration_variables = VertexAIWorkerVariables\n    _description = (\n        \"Execute flow runs within containers on Google Vertex AI. Requires \"\n        \"a Google Cloud Platform account.\"\n    )\n    _display_name = \"Google Vertex AI\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/vertex_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: VertexAIWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; VertexAIWorkerResult:\n        \"\"\"\n        Executes a flow run within a Vertex AI Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            VertexAIWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n\n        client_options = ClientOptions(\n            api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n        )\n\n        job_name = configuration.job_name\n\n        job_spec = self._build_job_spec(configuration)\n        job_service_async_client = (\n            configuration.credentials.get_job_service_async_client(\n                client_options=client_options\n            )\n        )\n\n        job_run = await self._create_and_begin_job(\n            job_name,\n            job_spec,\n            job_service_async_client,\n            configuration,\n            logger,\n        )\n\n        if task_status:\n            task_status.started(job_run.name)\n\n        final_job_run = await self._watch_job_run(\n            job_name=job_name,\n            full_job_name=job_run.name,\n            job_service_async_client=job_service_async_client,\n            current_state=job_run.state,\n            until_states=(\n                JobState.JOB_STATE_SUCCEEDED,\n                JobState.JOB_STATE_FAILED,\n                JobState.JOB_STATE_CANCELLED,\n                JobState.JOB_STATE_EXPIRED,\n            ),\n            configuration=configuration,\n            logger=logger,\n            timeout=int(\n                datetime.timedelta(\n                    hours=configuration.job_spec[\"maximum_run_time_hours\"]\n                ).total_seconds()\n            ),\n        )\n\n        error_msg = final_job_run.error.message\n\n        # Vertex will include an error message upon valid\n        # flow cancellations, so we'll avoid raising an error in that case\n        if error_msg and \"CANCELED\" not in error_msg:\n            raise RuntimeError(error_msg)\n\n        status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n        return VertexAIWorkerResult(\n            identifier=final_job_run.display_name, status_code=status_code\n        )\n\n    def _build_job_spec(\n        self, configuration: VertexAIWorkerJobConfiguration\n    ) -&gt; \"CustomJobSpec\":\n        \"\"\"\n        Builds a job spec by gathering details.\n        \"\"\"\n        # here, we extract the `worker_pool_specs` out of the job_spec\n        worker_pool_specs = [\n            WorkerPoolSpec(\n                container_spec=ContainerSpec(**spec[\"container_spec\"]),\n                machine_spec=MachineSpec(**spec[\"machine_spec\"]),\n                replica_count=spec[\"replica_count\"],\n                disk_spec=DiskSpec(**spec[\"disk_spec\"]),\n            )\n            for spec in configuration.job_spec.pop(\"worker_pool_specs\", [])\n        ]\n\n        timeout = Duration().FromTimedelta(\n            td=datetime.timedelta(\n                hours=configuration.job_spec[\"maximum_run_time_hours\"]\n            )\n        )\n        scheduling = Scheduling(timeout=timeout)\n\n        if \"service_account_name\" in configuration.job_spec:\n            service_account_name = configuration.job_spec.pop(\"service_account_name\")\n            configuration.job_spec[\"service_account\"] = service_account_name\n\n        # construct the final job spec that we will provide to Vertex AI\n        job_spec = CustomJobSpec(\n            worker_pool_specs=worker_pool_specs,\n            scheduling=scheduling,\n            ignore_unknown_fields=True,\n            **configuration.job_spec,\n        )\n        return job_spec\n\n    async def _create_and_begin_job(\n        self,\n        job_name: str,\n        job_spec: \"CustomJobSpec\",\n        job_service_async_client: \"JobServiceAsyncClient\",\n        configuration: VertexAIWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Builds a custom job and begins running it.\n        \"\"\"\n        # create custom job\n        custom_job = CustomJob(\n            display_name=job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(configuration=configuration),\n        )\n\n        # run job\n        logger.info(f\"Creating job {job_name!r}\")\n\n        project = configuration.project\n        resource_name = f\"projects/{project}/locations/{configuration.region}\"\n\n        async for attempt in AsyncRetrying(\n            stop=stop_after_attempt(3), wait=wait_fixed(1) + wait_random(0, 3)\n        ):\n            with attempt:\n                custom_job_run = await job_service_async_client.create_custom_job(\n                    parent=resource_name,\n                    custom_job=custom_job,\n                )\n\n        logger.info(\n            f\"Job {job_name!r} created. \"\n            f\"The full job name is {custom_job_run.name!r}\"\n        )\n\n        return custom_job_run\n\n    async def _watch_job_run(\n        self,\n        job_name: str,\n        full_job_name: str,  # different from job_name\n        job_service_async_client: \"JobServiceAsyncClient\",\n        current_state: \"JobState\",\n        until_states: Tuple[\"JobState\"],\n        configuration: VertexAIWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n        timeout: int = None,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Polls job run to see if status changed.\n\n        State changes reported by the Vertex AI API may sometimes be inaccurate\n        immediately upon startup, but should eventually report a correct running\n        and then terminal state. The minimum training duration for a custom job is\n        30 seconds, so short-lived jobs may be marked as successful some time\n        after a flow run has completed.\n        \"\"\"\n        state = JobState.JOB_STATE_UNSPECIFIED\n        last_state = current_state\n        t0 = time.time()\n\n        while state not in until_states:\n            job_run = await job_service_async_client.get_custom_job(\n                name=full_job_name,\n            )\n            state = job_run.state\n            if state != last_state:\n                state_label = (\n                    state.name.replace(\"_\", \" \")\n                    .lower()\n                    .replace(\"state\", \"state is now:\")\n                )\n                # results in \"New job state is now: succeeded\"\n                logger.debug(f\"{job_name} has new {state_label}\")\n                last_state = state\n            else:\n                # Intermittently, the job will not be described. We want to respect the\n                # watch timeout though.\n                logger.debug(f\"Job {job_name} not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching job for states \"\n                    \"{until_states!r}\"\n                )\n            await asyncio.sleep(configuration.job_watch_poll_interval)\n\n        return job_run\n\n    def _get_compatible_labels(\n        self, configuration: VertexAIWorkerJobConfiguration\n    ) -&gt; Dict[str, str]:\n        \"\"\"\n        Ensures labels are compatible with GCP label requirements.\n        https://cloud.google.com/resource-manager/docs/creating-managing-labels\n\n        Ex: the Prefect provided key of prefect.io/flow-name -&gt; prefect-io_flow-name\n        \"\"\"\n        compatible_labels = {}\n        for key, val in configuration.labels.items():\n            new_key = slugify(\n                key,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n            compatible_labels[new_key] = slugify(\n                val,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n        return compatible_labels\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: VertexAIWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a job running in Vertex AI upon flow cancellation,\n        based on the provided infrastructure PID + run configuration.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.customJobs/cancel\"  # noqa\n            )\n\n        client_options = ClientOptions(\n            api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n        )\n        job_service_async_client = (\n            configuration.credentials.get_job_service_async_client(\n                client_options=client_options\n            )\n        )\n        await self._stop_job(\n            client=job_service_async_client,\n            vertex_job_name=infrastructure_pid,\n        )\n\n    async def _stop_job(self, client: \"JobServiceAsyncClient\", vertex_job_name: str):\n        \"\"\"\n        Calls the `cancel_custom_job` method on the Vertex AI Job Service Client.\n        \"\"\"\n        cancel_custom_job_request = CancelCustomJobRequest(name=vertex_job_name)\n        try:\n            await client.cancel_custom_job(\n                request=cancel_custom_job_request,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Vertex AI job; the job name {vertex_job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a job running in Vertex AI upon flow cancellation, based on the provided infrastructure PID + run configuration.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: VertexAIWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a job running in Vertex AI upon flow cancellation,\n    based on the provided infrastructure PID + run configuration.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.customJobs/cancel\"  # noqa\n        )\n\n    client_options = ClientOptions(\n        api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n    )\n    job_service_async_client = (\n        configuration.credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n    )\n    await self._stop_job(\n        client=job_service_async_client,\n        vertex_job_name=infrastructure_pid,\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Vertex AI Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>VertexAIWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>VertexAIWorkerResult</code> <code>VertexAIWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: VertexAIWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; VertexAIWorkerResult:\n    \"\"\"\n    Executes a flow run within a Vertex AI Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        VertexAIWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n\n    client_options = ClientOptions(\n        api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n    )\n\n    job_name = configuration.job_name\n\n    job_spec = self._build_job_spec(configuration)\n    job_service_async_client = (\n        configuration.credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n    )\n\n    job_run = await self._create_and_begin_job(\n        job_name,\n        job_spec,\n        job_service_async_client,\n        configuration,\n        logger,\n    )\n\n    if task_status:\n        task_status.started(job_run.name)\n\n    final_job_run = await self._watch_job_run(\n        job_name=job_name,\n        full_job_name=job_run.name,\n        job_service_async_client=job_service_async_client,\n        current_state=job_run.state,\n        until_states=(\n            JobState.JOB_STATE_SUCCEEDED,\n            JobState.JOB_STATE_FAILED,\n            JobState.JOB_STATE_CANCELLED,\n            JobState.JOB_STATE_EXPIRED,\n        ),\n        configuration=configuration,\n        logger=logger,\n        timeout=int(\n            datetime.timedelta(\n                hours=configuration.job_spec[\"maximum_run_time_hours\"]\n            ).total_seconds()\n        ),\n    )\n\n    error_msg = final_job_run.error.message\n\n    # Vertex will include an error message upon valid\n    # flow cancellations, so we'll avoid raising an error in that case\n    if error_msg and \"CANCELED\" not in error_msg:\n        raise RuntimeError(error_msg)\n\n    status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n    return VertexAIWorkerResult(\n        identifier=final_job_run.display_name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration","title":"<code>VertexAIWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Vertex AI Worker to create a Job.</p> <p>An instance of this class is passed to the Vertex AI Worker's <code>run</code> method for each flow run. It contains all information necessary to execute the flow run as a Vertex AI Job.</p> <p>Attributes:</p> Name Type Description <code>region</code> <code>str</code> <p>The region where the Vertex AI Job resides.</p> <code>credentials</code> <code>Optional[GcpCredentials]</code> <p>The GCP Credentials used to connect to Vertex AI.</p> <code>job_spec</code> <code>Dict[str, Any]</code> <p>The Vertex AI Job spec used to create the Job.</p> <code>job_watch_poll_interval</code> <code>float</code> <p>The interval between GCP API calls to check Job state.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Vertex AI Worker to create a Job.\n\n    An instance of this class is passed to the Vertex AI Worker's `run` method\n    for each flow run. It contains all information necessary to execute\n    the flow run as a Vertex AI Job.\n\n    Attributes:\n        region: The region where the Vertex AI Job resides.\n        credentials: The GCP Credentials used to connect to Vertex AI.\n        job_spec: The Vertex AI Job spec used to create the Job.\n        job_watch_poll_interval: The interval between GCP API calls to check Job state.\n    \"\"\"\n\n    region: str = Field(\n        description=\"The region where the Vertex AI Job resides.\",\n        example=\"us-central1\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Vertex AI Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n\n    job_spec: Dict[str, Any] = Field(\n        template={\n            \"service_account_name\": \"{{ service_account_name }}\",\n            \"network\": \"{{ network }}\",\n            \"reserved_ip_ranges\": \"{{ reserved_ip_ranges }}\",\n            \"maximum_run_time_hours\": \"{{ maximum_run_time_hours }}\",\n            \"worker_pool_specs\": [\n                {\n                    \"replica_count\": 1,\n                    \"container_spec\": {\n                        \"image_uri\": \"{{ image }}\",\n                        \"command\": \"{{ command }}\",\n                        \"args\": [],\n                    },\n                    \"machine_spec\": {\n                        \"machine_type\": \"{{ machine_type }}\",\n                        \"accelerator_type\": \"{{ accelerator_type }}\",\n                        \"accelerator_count\": \"{{ accelerator_count }}\",\n                    },\n                    \"disk_spec\": {\n                        \"boot_disk_type\": \"{{ boot_disk_type }}\",\n                        \"boot_disk_size_gb\": \"{{ boot_disk_size_gb }}\",\n                    },\n                }\n            ],\n        }\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        title=\"Poll Interval (Seconds)\",\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"property for accessing the project from the credentials.\"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"\n        The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:\n        https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name\n        \"\"\"  # noqa\n        unique_suffix = uuid4().hex\n        job_name = f\"{self.name}-{unique_suffix}\"\n        return job_name\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self._inject_formatted_env_vars()\n        self._inject_formatted_command()\n        self._ensure_existence_of_service_account()\n\n    def _inject_formatted_env_vars(self):\n        \"\"\"Inject environment variables in the Vertex job_spec configuration,\n        in the correct format, which is sourced from the BaseJobConfiguration.\n        This method is invoked by `prepare_for_flow_run()`.\"\"\"\n        worker_pool_specs = self.job_spec[\"worker_pool_specs\"]\n        formatted_env_vars = [\n            {\"name\": key, \"value\": value} for key, value in self.env.items()\n        ]\n        worker_pool_specs[0][\"container_spec\"][\"env\"] = formatted_env_vars\n\n    def _inject_formatted_command(self):\n        \"\"\"Inject shell commands in the Vertex job_spec configuration,\n        in the correct format, which is sourced from the BaseJobConfiguration.\n        Here, we'll ensure that the default string format\n        is converted to a list of strings.\"\"\"\n        worker_pool_specs = self.job_spec[\"worker_pool_specs\"]\n\n        existing_command = worker_pool_specs[0][\"container_spec\"].get(\"command\")\n        if existing_command is None:\n            worker_pool_specs[0][\"container_spec\"][\"command\"] = shlex.split(\n                self._base_flow_run_command()\n            )\n        elif isinstance(existing_command, str):\n            worker_pool_specs[0][\"container_spec\"][\"command\"] = shlex.split(\n                existing_command\n            )\n\n    def _ensure_existence_of_service_account(self):\n        \"\"\"Verify that a service account was provided, either in the credentials\n        or as a standalone service account name override.\"\"\"\n\n        provided_service_account_name = self.job_spec.get(\"service_account_name\")\n        credential_service_account = self.credentials._service_account_email\n\n        service_account_to_use = (\n            provided_service_account_name or credential_service_account\n        )\n\n        if service_account_to_use is None:\n            raise ValueError(\n                \"A service account is required for the Vertex job. \"\n                \"A service account could not be detected in the attached credentials \"\n                \"or in the service_account_name input. \"\n                \"Please pass in valid GCP credentials or a valid service_account_name\"\n            )\n\n        self.job_spec[\"service_account_name\"] = service_account_to_use\n\n    @validator(\"job_spec\")\n    def _ensure_job_spec_includes_required_attributes(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job spec includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_spec())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference: https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>property for accessing the project from the credentials.</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerResult","title":"<code>VertexAIWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerVariables","title":"<code>VertexAIWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Vertex AI worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Vertex AI worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    region: str = Field(\n        description=\"The region where the Vertex AI Job resides.\",\n        example=\"us-central1\",\n    )\n    image: str = Field(\n        title=\"Image Name\",\n        description=(\n            \"The URI of a container image in the Container or Artifact Registry, \"\n            \"used to run your Vertex AI Job. Note that Vertex AI will need access\"\n            \"to the project and region where the container image is stored. See \"\n            \"https://cloud.google.com/vertex-ai/docs/training/create-custom-container\"\n        ),\n        example=\"gcr.io/your-project/your-repo:latest\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Vertex AI Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n    machine_type: str = Field(\n        title=\"Machine Type\",\n        description=(\n            \"The machine type to use for the run, which controls \"\n            \"the available CPU and memory. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        default=\"n1-standard-4\",\n    )\n    accelerator_type: Optional[str] = Field(\n        title=\"Accelerator Type\",\n        description=(\n            \"The type of accelerator to attach to the machine. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        example=\"NVIDIA_TESLA_K80\",\n        default=None,\n    )\n    accelerator_count: Optional[int] = Field(\n        title=\"Accelerator Count\",\n        description=(\n            \"The number of accelerators to attach to the machine. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        example=1,\n        default=None,\n    )\n    boot_disk_type: str = Field(\n        title=\"Boot Disk Type\",\n        description=\"The type of boot disk to attach to the machine.\",\n        default=\"pd-ssd\",\n    )\n    boot_disk_size_gb: int = Field(\n        title=\"Boot Disk Size (GB)\",\n        description=\"The size of the boot disk to attach to the machine, in gigabytes.\",\n        default=100,\n    )\n    maximum_run_time_hours: int = Field(\n        default=1,\n        title=\"Maximum Run Time (Hours)\",\n        description=\"The maximum job running time, in hours\",\n    )\n    network: Optional[str] = Field(\n        default=None,\n        title=\"Network\",\n        description=\"The full name of the Compute Engine network\"\n        \"to which the Job should be peered. Private services access must \"\n        \"already be configured for the network. If left unspecified, the job \"\n        \"is not peered with any network. \"\n        \"For example: projects/12345/global/networks/myVPC\",\n    )\n    reserved_ip_ranges: Optional[List[str]] = Field(\n        default=None,\n        title=\"Reserved IP Ranges\",\n        description=\"A list of names for the reserved ip ranges under the VPC \"\n        \"network that can be used for this job. If set, we will deploy the job \"\n        \"within the provided ip ranges. Otherwise, the job will be deployed to \"\n        \"any ip ranges under the provided VPC network.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=(\n            \"Specifies the service account to use \"\n            \"as the run-as account in Vertex AI. The worker submitting jobs must have \"\n            \"act-as permission on this run-as account. If unspecified, the AI \"\n            \"Platform Custom Code Service Agent for the CustomJob's project is \"\n            \"used. Takes precedence over the service account found in GCP credentials, \"\n            \"and required if a service account cannot be detected in GCP credentials.\"\n        ),\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        title=\"Poll Interval (Seconds)\",\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/","title":"Deployment Steps","text":""},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps","title":"<code>prefect_gcp.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage in and retrieval from Google Cloud Storage.</p>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PullFromGcsOutput","title":"<code>PullFromGcsOutput</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>pull_from_gcs</code> step.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>class PullFromGcsOutput(TypedDict):\n    \"\"\"\n    The output of the `pull_from_gcs` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n    directory: str\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PullProjectFromGcsOutput","title":"<code>PullProjectFromGcsOutput</code>","text":"<p>               Bases: <code>PullFromGcsOutput</code></p> <p>Deprecated. Use <code>PullFromGcsOutput</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PullFromGcsOutput` instead.\")\nclass PullProjectFromGcsOutput(PullFromGcsOutput):\n    \"\"\"Deprecated. Use `PullFromGcsOutput` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PushProjectToGcsOutput","title":"<code>PushProjectToGcsOutput</code>","text":"<p>               Bases: <code>PushToGcsOutput</code></p> <p>Deprecated. Use <code>PushToGcsOutput</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PushToGcsOutput` instead.\")\nclass PushProjectToGcsOutput(PushToGcsOutput):\n    \"\"\"Deprecated. Use `PushToGcsOutput` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PushToGcsOutput","title":"<code>PushToGcsOutput</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>push_to_gcs</code> step.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>class PushToGcsOutput(TypedDict):\n    \"\"\"\n    The output of the `push_to_gcs` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.pull_from_gcs","title":"<code>pull_from_gcs</code>","text":"<p>Pulls the contents of a project from an GCS bucket to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the GCS bucket where files are stored.</p> required <code>folder</code> <code>str</code> <p>The folder in the GCS bucket where files are stored.</p> required <code>project</code> <code>Optional[str]</code> <p>The GCP project the bucket belongs to. If not provided, the project will be inferred from the credentials or the local environment.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the service account information and project used for authentication. If not provided, the application default credentials will be used.</p> <code>None</code> <p>Returns:</p> Type Description <code>PullProjectFromGcsOutput</code> <p>A dictionary containing the bucket, folder, and local directory where files were downloaded.</p> <p>Examples:</p> <p>Pull from GCS using the default environment credentials: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n</code></pre></p> <p>Pull from GCS using credentials stored in a block: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n</code></pre></p> <p>Pull from to an GCS bucket using credentials stored in a service account file: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials:\n            project: my-project\n            service_account_file: /path/to/service_account.json\n</code></pre></p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>def pull_from_gcs(\n    bucket: str,\n    folder: str,\n    project: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n) -&gt; PullProjectFromGcsOutput:\n    \"\"\"\n    Pulls the contents of a project from an GCS bucket to the current working directory.\n\n    Args:\n        bucket: The name of the GCS bucket where files are stored.\n        folder: The folder in the GCS bucket where files are stored.\n        project: The GCP project the bucket belongs to. If not provided, the project will be\n            inferred from the credentials or the local environment.\n        credentials: A dictionary containing the service account information and project\n            used for authentication. If not provided, the application default\n            credentials will be used.\n\n    Returns:\n        A dictionary containing the bucket, folder, and local directory where files were downloaded.\n\n    Examples:\n        Pull from GCS using the default environment credentials:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n        ```\n\n        Pull from GCS using credentials stored in a block:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n        ```\n\n        Pull from to an GCS bucket using credentials stored in a service account file:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials:\n                    project: my-project\n                    service_account_file: /path/to/service_account.json\n        ```\n\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    project = credentials.get(\"project\") if credentials else None\n\n    gcp_creds = None\n    if credentials is not None:\n        if credentials.get(\"service_account_info\") is not None:\n            gcp_creds = Credentials.from_service_account_info(\n                credentials.get(\"service_account_info\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif credentials.get(\"service_account_file\") is not None:\n            gcp_creds = Credentials.from_service_account_file(\n                credentials.get(\"service_account_file\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n\n    gcp_creds = gcp_creds or google.auth.default()[0]\n\n    storage_client = StorageClient(credentials=gcp_creds, project=project)\n\n    blobs = storage_client.list_blobs(bucket, prefix=folder)\n\n    for blob in blobs:\n        if blob.name.endswith(\"/\"):\n            # object is a folder and will be created if it contains any objects\n            continue\n        local_blob_download_path = PurePosixPath(\n            local_path\n            / relative_path_to_current_platform(blob.name).relative_to(folder)\n        )\n        Path.mkdir(Path(local_blob_download_path.parent), parents=True, exist_ok=True)\n\n        blob.download_to_filename(local_blob_download_path)\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n        \"directory\": str(local_path),\n    }\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.pull_project_from_gcs","title":"<code>pull_project_from_gcs</code>","text":"<p>Deprecated. Use <code>pull_from_gcs</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `pull_from_gcs` instead.\")\ndef pull_project_from_gcs(*args, **kwargs) -&gt; PullProjectFromGcsOutput:\n    \"\"\"\n    Deprecated. Use `pull_from_gcs` instead.\n    \"\"\"\n    return pull_from_gcs(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.push_project_to_gcs","title":"<code>push_project_to_gcs</code>","text":"<p>Deprecated. Use <code>push_to_gcs</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `push_to_gcs` instead.\")\ndef push_project_to_gcs(*args, **kwargs) -&gt; PushToGcsOutput:\n    \"\"\"\n    Deprecated. Use `push_to_gcs` instead.\n    \"\"\"\n    return push_to_gcs(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.push_to_gcs","title":"<code>push_to_gcs</code>","text":"<p>Pushes the contents of the current working directory to a GCS bucket, excluding files and folders specified in the ignore_file.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the GCS bucket where files will be uploaded.</p> required <code>folder</code> <code>str</code> <p>The folder in the GCS bucket where files will be uploaded.</p> required <code>project</code> <code>Optional[str]</code> <p>The GCP project the bucket belongs to. If not provided, the project will be inferred from the credentials or the local environment.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the service account information and project used for authentication. If not provided, the application default credentials will be used.</p> <code>None</code> <code>ignore_file</code> <p>The name of the file containing ignore patterns.</p> <code>'.prefectignore'</code> <p>Returns:</p> Type Description <code>PushToGcsOutput</code> <p>A dictionary containing the bucket and folder where files were uploaded.</p> <p>Examples:</p> <p>Push to a GCS bucket: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Push  to a GCS bucket using credentials stored in a block: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n</code></pre></p> <p>Push to a GCS bucket using credentials stored in a service account file: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials:\n            project: my-project\n            service_account_file: /path/to/service_account.json\n</code></pre></p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>def push_to_gcs(\n    bucket: str,\n    folder: str,\n    project: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n    ignore_file=\".prefectignore\",\n) -&gt; PushToGcsOutput:\n    \"\"\"\n    Pushes the contents of the current working directory to a GCS bucket,\n    excluding files and folders specified in the ignore_file.\n\n    Args:\n        bucket: The name of the GCS bucket where files will be uploaded.\n        folder: The folder in the GCS bucket where files will be uploaded.\n        project: The GCP project the bucket belongs to. If not provided, the project\n            will be inferred from the credentials or the local environment.\n        credentials: A dictionary containing the service account information and project\n            used for authentication. If not provided, the application default\n            credentials will be used.\n        ignore_file: The name of the file containing ignore patterns.\n\n    Returns:\n        A dictionary containing the bucket and folder where files were uploaded.\n\n    Examples:\n        Push to a GCS bucket:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Push  to a GCS bucket using credentials stored in a block:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n        ```\n\n        Push to a GCS bucket using credentials stored in a service account\n        file:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials:\n                    project: my-project\n                    service_account_file: /path/to/service_account.json\n        ```\n\n    \"\"\"\n    project = credentials.get(\"project\") if credentials else None\n\n    gcp_creds = None\n    if credentials is not None:\n        if credentials.get(\"service_account_info\") is not None:\n            gcp_creds = Credentials.from_service_account_info(\n                credentials.get(\"service_account_info\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif credentials.get(\"service_account_file\") is not None:\n            gcp_creds = Credentials.from_service_account_file(\n                credentials.get(\"service_account_file\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n\n    gcp_creds = gcp_creds or google.auth.default()[0]\n\n    storage_client = StorageClient(credentials=gcp_creds, project=project)\n    bucket_resource = storage_client.bucket(bucket)\n\n    local_path = Path.cwd()\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    for local_file_path in local_path.expanduser().rglob(\"*\"):\n        relative_local_file_path = local_file_path.relative_to(local_path)\n        if (\n            included_files is not None\n            and str(relative_local_file_path) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = (folder / relative_local_file_path).as_posix()\n\n            blob_resource = bucket_resource.blob(remote_file_path)\n            blob_resource.upload_from_filename(local_file_path)\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-github/","title":"prefect-github","text":"<p>Prefect-github makes it easy to interact with GitHub repositories and credentials.</p>"},{"location":"integrations/prefect-github/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-github/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A GitHub account.</li> </ul>"},{"location":"integrations/prefect-github/#install-prefect-github","title":"Install prefect-github","text":"<pre><code>pip install prefect-github\n</code></pre>"},{"location":"integrations/prefect-github/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-github module to make them available for use.</p> <pre><code>prefect block register -m prefect_github\n</code></pre>"},{"location":"integrations/prefect-github/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p> <p>To create a deployment and run a deployment where the flow code is stored in a private GitHub repository, you can use the <code>GitHubCredentials</code> block.</p> <p>A deployment can use flow code stored in a GitHub repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Code to create a GitHub Credentials block:</p> <pre><code>from prefect_github import GitHubCredentials\n\ngithub_credentials_block = GitHubCredentials(token=\"my_token\")\ngithub_credentials_block.save(name=\"my-github-credentials-block\")\n</code></pre>"},{"location":"integrations/prefect-github/#access-flow-code-stored-in-a-private-github-repository-in-a-deployment","title":"Access flow code stored in a private GitHub repository in a deployment","text":"<p>Use the credentials block you created above to pass the GitHub access token during deployment creation. The code below assumes there's flow code stored in a private GitHub repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_github import GitHubCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        credentials=GitHubCredentials.load(\"my-github-credentials-block\")\n    ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-github-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the GitHub Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-github/#interact-with-a-github-repository","title":"Interact with a GitHub repository","text":"<p>You can use prefect-github to create and retrieve issues and PRs from a repository. Here's an example of adding a star to a GitHub repository:</p> <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.repository import query_repository\nfrom prefect_github.mutations import add_star_starrable\n\n\n@flow()\ndef github_add_star_flow():\n    github_credentials = GitHubCredentials.load(\"github-token\")\n    repository_id = query_repository(\n        \"PrefectHQ\",\n        \"Prefect\",\n        github_credentials=github_credentials,\n        return_fields=\"id\"\n    )[\"id\"]\n    starrable = add_star_starrable(\n        repository_id,\n        github_credentials\n    )\n    return starrable\n\n\nif __name__ == \"__main__\":\n    github_add_star_flow()\n</code></pre>"},{"location":"integrations/prefect-github/#resources","title":"Resources","text":"<p>For assistance using GitHub, consult the GitHub documentation.</p> <p>Refer to the prefect-github API documentation linked in the sidebar to explore all the capabilities of the prefect-github library.</p>"},{"location":"integrations/prefect-github/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials","title":"<code>prefect_github.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with GitHub</p>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials","title":"<code>GitHubCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage GitHub authentication.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>SecretStr</code> <p>the token to authenticate into GitHub.</p> <p>Examples:</p> <p>Load stored GitHub credentials: <pre><code>from prefect_github import GitHubCredentials\ngithub_credentials_block = GitHubCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>class GitHubCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage GitHub authentication.\n\n    Attributes:\n        token: the token to authenticate into GitHub.\n\n    Examples:\n        Load stored GitHub credentials:\n        ```python\n        from prefect_github import GitHubCredentials\n        github_credentials_block = GitHubCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"GitHub Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials\"  # noqa\n\n    token: SecretStr = Field(\n        default=None, description=\"A GitHub personal access token (PAT).\"\n    )\n\n    def get_client(self) -&gt; HTTPEndpoint:\n        \"\"\"\n        Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n\n        Returns:\n            An authenticated GitHub GraphQL HTTPEndpoint client.\n\n        Example:\n            Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n            ```python\n            from prefect_github import GitHubCredentials\n\n            github_credentials = GitHubCredentials(token=token)\n            client = github_credentials.get_client()\n            ```\n        \"\"\"\n\n        if self.token is not None:\n            base_headers = {\"Authorization\": f\"Bearer {self.token.get_secret_value()}\"}\n        else:\n            base_headers = None\n\n        endpoint = HTTPEndpoint(\n            \"https://api.github.com/graphql\", base_headers=base_headers\n        )\n        return endpoint\n\n    def get_endpoint(self) -&gt; HTTPEndpoint:\n        \"\"\"\n        Gets an authenticated GitHub GraphQL HTTPEndpoint.\n\n        Returns:\n            An authenticated GitHub GraphQL HTTPEndpoint\n\n        Example:\n            Gets an authenticated GitHub GraphQL HTTPEndpoint.\n            ```python\n            from prefect import flow\n            from prefect_github import GitHubCredentials\n\n            @flow\n            def example_get_endpoint_flow():\n                token = \"token_xxxxxxx\"\n                github_credentials = GitHubCredentials(token=token)\n                endpoint = github_credentials.get_endpoint()\n                return endpoint\n\n            example_get_endpoint_flow()\n            ```\n        \"\"\"\n        warnings.warn(\n            \"`get_endpoint` is deprecated and will be removed March 31st, 2023, \"\n            \"use `get_client` instead.\",\n            DeprecationWarning,\n        )\n        return self.get_client()\n</code></pre>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an authenticated GitHub GraphQL HTTPEndpoint client.</p> <p>Returns:</p> Type Description <code>HTTPEndpoint</code> <p>An authenticated GitHub GraphQL HTTPEndpoint client.</p> Example <p>Gets an authenticated GitHub GraphQL HTTPEndpoint client. <pre><code>from prefect_github import GitHubCredentials\n\ngithub_credentials = GitHubCredentials(token=token)\nclient = github_credentials.get_client()\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>def get_client(self) -&gt; HTTPEndpoint:\n    \"\"\"\n    Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n\n    Returns:\n        An authenticated GitHub GraphQL HTTPEndpoint client.\n\n    Example:\n        Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n        ```python\n        from prefect_github import GitHubCredentials\n\n        github_credentials = GitHubCredentials(token=token)\n        client = github_credentials.get_client()\n        ```\n    \"\"\"\n\n    if self.token is not None:\n        base_headers = {\"Authorization\": f\"Bearer {self.token.get_secret_value()}\"}\n    else:\n        base_headers = None\n\n    endpoint = HTTPEndpoint(\n        \"https://api.github.com/graphql\", base_headers=base_headers\n    )\n    return endpoint\n</code></pre>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials.get_endpoint","title":"<code>get_endpoint</code>","text":"<p>Gets an authenticated GitHub GraphQL HTTPEndpoint.</p> <p>Returns:</p> Type Description <code>HTTPEndpoint</code> <p>An authenticated GitHub GraphQL HTTPEndpoint</p> Example <p>Gets an authenticated GitHub GraphQL HTTPEndpoint. <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\n\n@flow\ndef example_get_endpoint_flow():\n    token = \"token_xxxxxxx\"\n    github_credentials = GitHubCredentials(token=token)\n    endpoint = github_credentials.get_endpoint()\n    return endpoint\n\nexample_get_endpoint_flow()\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>def get_endpoint(self) -&gt; HTTPEndpoint:\n    \"\"\"\n    Gets an authenticated GitHub GraphQL HTTPEndpoint.\n\n    Returns:\n        An authenticated GitHub GraphQL HTTPEndpoint\n\n    Example:\n        Gets an authenticated GitHub GraphQL HTTPEndpoint.\n        ```python\n        from prefect import flow\n        from prefect_github import GitHubCredentials\n\n        @flow\n        def example_get_endpoint_flow():\n            token = \"token_xxxxxxx\"\n            github_credentials = GitHubCredentials(token=token)\n            endpoint = github_credentials.get_endpoint()\n            return endpoint\n\n        example_get_endpoint_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"`get_endpoint` is deprecated and will be removed March 31st, 2023, \"\n        \"use `get_client` instead.\",\n        DeprecationWarning,\n    )\n    return self.get_client()\n</code></pre>"},{"location":"integrations/prefect-github/graphql/","title":"Graphql","text":""},{"location":"integrations/prefect-github/graphql/#prefect_github.graphql","title":"<code>prefect_github.graphql</code>","text":"<p>This is a module containing generic GraphQL tasks</p>"},{"location":"integrations/prefect-github/graphql/#prefect_github.graphql.execute_graphql","title":"<code>execute_graphql</code>  <code>async</code>","text":"<p>Generic function for executing GraphQL operations.</p> <p>Parameters:</p> Name Type Description Default <code>op</code> <code>Union[Operation, str]</code> <p>The operation, either as a valid GraphQL string or sgqlc.Operation.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>error_key</code> <code>str</code> <p>The key name to look out for in the response that indicates an error has occurred with the request.</p> <code>'errors'</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> <p>Examples:</p> <p>Queries the first three issues from the Prefect repository using a string query. <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.graphql import execute_graphql\n\n@flow()\ndef example_execute_graphql_flow():\n    op = '''\n        query GitHubRepoIssues($owner: String!, $name: String!) {\n            repository(owner: $owner, name: $name) {\n                issues(last: 3) {\n                    nodes {\n                        number\n                        title\n                    }\n                }\n            }\n        }\n    '''\n    token = \"ghp_...\"\n    github_credentials = GitHubCredentials(token=token)\n    params = dict(owner=\"PrefectHQ\", name=\"Prefect\")\n    result = execute_graphql(op, github_credentials, **params)\n    return result\n\nexample_execute_graphql_flow()\n</code></pre></p> <p>Queries the first three issues from Prefect repository using a sgqlc.Operation. <pre><code>from prefect import flow\nfrom sgqlc.operation import Operation\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.schemas import graphql_schema\nfrom prefect_github.graphql import execute_graphql\n\n@flow()\ndef example_execute_graphql_flow():\n    op = Operation(graphql_schema.Query)\n    op_settings = op.repository(\n        owner=\"PrefectHQ\", name=\"Prefect\"\n    ).issues(\n        first=3\n    ).nodes()\n    op_settings.__fields__(\"id\", \"title\")\n    token = \"ghp_...\"\n    github_credentials = GitHubCredentials(token=token)\n    result = execute_graphql(\n        op,\n        github_credentials,\n    )\n    return result\n\nexample_execute_graphql_flow()\n</code></pre></p> Source code in <code>prefect_github/graphql.py</code> <pre><code>@task\nasync def execute_graphql(\n    op: Union[Operation, str],\n    github_credentials: GitHubCredentials,\n    error_key: str = \"errors\",\n    **vars,\n) -&gt; Dict[str, Any]:\n    # NOTE: Maintainers can update these examples to match their collection!\n    \"\"\"\n    Generic function for executing GraphQL operations.\n\n    Args:\n        op: The operation, either as a valid GraphQL string or sgqlc.Operation.\n        github_credentials: Credentials to use for authentication with GitHub.\n        error_key: The key name to look out for in the response\n            that indicates an error has occurred with the request.\n\n    Returns:\n        A dict of the returned fields.\n\n    Examples:\n        Queries the first three issues from the Prefect repository\n        using a string query.\n        ```python\n        from prefect import flow\n        from prefect_github import GitHubCredentials\n        from prefect_github.graphql import execute_graphql\n\n        @flow()\n        def example_execute_graphql_flow():\n            op = '''\n                query GitHubRepoIssues($owner: String!, $name: String!) {\n                    repository(owner: $owner, name: $name) {\n                        issues(last: 3) {\n                            nodes {\n                                number\n                                title\n                            }\n                        }\n                    }\n                }\n            '''\n            token = \"ghp_...\"\n            github_credentials = GitHubCredentials(token=token)\n            params = dict(owner=\"PrefectHQ\", name=\"Prefect\")\n            result = execute_graphql(op, github_credentials, **params)\n            return result\n\n        example_execute_graphql_flow()\n        ```\n\n        Queries the first three issues from Prefect repository\n        using a sgqlc.Operation.\n        ```python\n        from prefect import flow\n        from sgqlc.operation import Operation\n        from prefect_github import GitHubCredentials\n        from prefect_github.schemas import graphql_schema\n        from prefect_github.graphql import execute_graphql\n\n        @flow()\n        def example_execute_graphql_flow():\n            op = Operation(graphql_schema.Query)\n            op_settings = op.repository(\n                owner=\"PrefectHQ\", name=\"Prefect\"\n            ).issues(\n                first=3\n            ).nodes()\n            op_settings.__fields__(\"id\", \"title\")\n            token = \"ghp_...\"\n            github_credentials = GitHubCredentials(token=token)\n            result = execute_graphql(\n                op,\n                github_credentials,\n            )\n            return result\n\n        example_execute_graphql_flow()\n        ```\n    \"\"\"\n    result = await _execute_graphql_op(\n        op, github_credentials, error_key=error_key, **vars\n    )\n    return result\n</code></pre>"},{"location":"integrations/prefect-github/mutations/","title":"Mutations","text":""},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations","title":"<code>prefect_github.mutations</code>","text":"<p>This is a module containing: GitHub mutation tasks</p>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_comment_subject","title":"<code>add_comment_subject</code>  <code>async</code>","text":"<p>Adds a comment to an Issue or Pull Request.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>body</code> <code>str</code> <p>The contents of the comment.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_comment_subject(  # noqa\n    subject_id: str,\n    body: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a comment to an Issue or Pull Request.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        body: The contents of the comment.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_comment(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                body=body,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"addComment\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addComment\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_pull_request_review","title":"<code>add_pull_request_review</code>  <code>async</code>","text":"<p>Adds a review to a Pull Request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>commit_oid</code> <code>datetime</code> <p>The commit OID the review pertains to.</p> <code>None</code> <code>body</code> <code>str</code> <p>The contents of the review body comment.</p> <code>None</code> <code>event</code> <code>PullRequestReviewEvent</code> <p>The event to perform on the pull request review.</p> <code>None</code> <code>comments</code> <code>Iterable[DraftPullRequestReviewComment]</code> <p>The review line comments.</p> <code>None</code> <code>threads</code> <code>Iterable[DraftPullRequestReviewThread]</code> <p>The review line comment threads.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_pull_request_review(  # noqa\n    pull_request_id: str,\n    github_credentials: GitHubCredentials,\n    commit_oid: datetime = None,\n    body: str = None,\n    event: graphql_schema.PullRequestReviewEvent = None,\n    comments: Iterable[graphql_schema.DraftPullRequestReviewComment] = None,\n    threads: Iterable[graphql_schema.DraftPullRequestReviewThread] = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a review to a Pull Request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        github_credentials: Credentials to use for authentication with GitHub.\n        commit_oid: The commit OID the review pertains to.\n        body: The contents of the review body comment.\n        event: The event to perform on the pull request review.\n        comments: The review line comments.\n        threads: The review line comment threads.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_pull_request_review(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                commit_oid=commit_oid,\n                body=body,\n                event=event,\n                comments=comments,\n                threads=threads,\n            )\n        )\n    ).pull_request_review(**strip_kwargs())\n\n    op_stack = (\n        \"addPullRequestReview\",\n        \"pullRequestReview\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addPullRequestReview\"][\"pullRequestReview\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_reaction","title":"<code>add_reaction</code>  <code>async</code>","text":"<p>Adds a reaction to a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji to react with.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_reaction(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a reaction to a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji to react with.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).reaction(**strip_kwargs())\n\n    op_stack = (\n        \"addReaction\",\n        \"reaction\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addReaction\"][\"reaction\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_reaction_subject","title":"<code>add_reaction_subject</code>  <code>async</code>","text":"<p>Adds a reaction to a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji to react with.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_reaction_subject(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a reaction to a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji to react with.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"addReaction\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addReaction\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_star_starrable","title":"<code>add_star_starrable</code>  <code>async</code>","text":"<p>Adds a star to a Starrable.</p> <p>Parameters:</p> Name Type Description Default <code>starrable_id</code> <code>str</code> <p>The Starrable ID to star.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_star_starrable(  # noqa\n    starrable_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a star to a Starrable.\n\n    Args:\n        starrable_id: The Starrable ID to star.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_star(\n        **strip_kwargs(\n            input=dict(\n                starrable_id=starrable_id,\n            )\n        )\n    ).starrable(**strip_kwargs())\n\n    op_stack = (\n        \"addStar\",\n        \"starrable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addStar\"][\"starrable\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.close_issue","title":"<code>close_issue</code>  <code>async</code>","text":"<p>Close an issue.</p> <p>Parameters:</p> Name Type Description Default <code>issue_id</code> <code>str</code> <p>ID of the issue to be closed.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>state_reason</code> <code>IssueClosedStateReason</code> <p>The reason the issue is to be closed.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def close_issue(  # noqa\n    issue_id: str,\n    github_credentials: GitHubCredentials,\n    state_reason: graphql_schema.IssueClosedStateReason = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Close an issue.\n\n    Args:\n        issue_id: ID of the issue to be closed.\n        github_credentials: Credentials to use for authentication with GitHub.\n        state_reason: The reason the issue is to be closed.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.close_issue(\n        **strip_kwargs(\n            input=dict(\n                issue_id=issue_id,\n                state_reason=state_reason,\n            )\n        )\n    ).issue(**strip_kwargs())\n\n    op_stack = (\n        \"closeIssue\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"closeIssue\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.close_pull_request","title":"<code>close_pull_request</code>  <code>async</code>","text":"<p>Close a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>ID of the pull request to be closed.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def close_pull_request(  # noqa\n    pull_request_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Close a pull request.\n\n    Args:\n        pull_request_id: ID of the pull request to be closed.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.close_pull_request(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"closePullRequest\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"closePullRequest\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.create_issue","title":"<code>create_issue</code>  <code>async</code>","text":"<p>Creates a new issue.</p> <p>Parameters:</p> Name Type Description Default <code>repository_id</code> <code>str</code> <p>The Node ID of the repository.</p> required <code>title</code> <code>str</code> <p>The title for the issue.</p> required <code>assignee_ids</code> <code>Iterable[str]</code> <p>The Node ID for the user assignee for this issue.</p> required <code>label_ids</code> <code>Iterable[str]</code> <p>An array of Node IDs of labels for this issue.</p> required <code>project_ids</code> <code>Iterable[str]</code> <p>An array of Node IDs for projects associated with this issue.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>body</code> <code>str</code> <p>The body for the issue description.</p> <code>None</code> <code>milestone_id</code> <code>str</code> <p>The Node ID of the milestone for this issue.</p> <code>None</code> <code>issue_template</code> <code>str</code> <p>The name of an issue template in the repository, assigns labels and assignees from the template to the issue.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def create_issue(  # noqa\n    repository_id: str,\n    title: str,\n    assignee_ids: Iterable[str],\n    label_ids: Iterable[str],\n    project_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    body: str = None,\n    milestone_id: str = None,\n    issue_template: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Creates a new issue.\n\n    Args:\n        repository_id: The Node ID of the repository.\n        title: The title for the issue.\n        assignee_ids: The Node ID for the user assignee for this issue.\n        label_ids: An array of Node IDs of labels for this issue.\n        project_ids: An array of Node IDs for projects associated with this\n            issue.\n        github_credentials: Credentials to use for authentication with GitHub.\n        body: The body for the issue description.\n        milestone_id: The Node ID of the milestone for this issue.\n        issue_template: The name of an issue template in the repository, assigns\n            labels and assignees from the template to the issue.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.create_issue(\n        **strip_kwargs(\n            input=dict(\n                repository_id=repository_id,\n                title=title,\n                assignee_ids=assignee_ids,\n                label_ids=label_ids,\n                project_ids=project_ids,\n                body=body,\n                milestone_id=milestone_id,\n                issue_template=issue_template,\n            )\n        )\n    ).issue(**strip_kwargs())\n\n    op_stack = (\n        \"createIssue\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"createIssue\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.create_pull_request","title":"<code>create_pull_request</code>  <code>async</code>","text":"<p>Create a new pull request.</p> <p>Parameters:</p> Name Type Description Default <code>repository_id</code> <code>str</code> <p>The Node ID of the repository.</p> required <code>base_ref_name</code> <code>str</code> <p>The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository.</p> required <code>head_ref_name</code> <code>str</code> <p>The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace <code>head_ref_name</code> with a user like this: <code>username:branch</code>.</p> required <code>title</code> <code>str</code> <p>The title of the pull request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>body</code> <code>str</code> <p>The contents of the pull request.</p> <code>None</code> <code>maintainer_can_modify</code> <code>bool</code> <p>Indicates whether maintainers can modify the pull request.</p> <code>None</code> <code>draft</code> <code>bool</code> <p>Indicates whether this pull request should be a draft.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def create_pull_request(  # noqa\n    repository_id: str,\n    base_ref_name: str,\n    head_ref_name: str,\n    title: str,\n    github_credentials: GitHubCredentials,\n    body: str = None,\n    maintainer_can_modify: bool = None,\n    draft: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Create a new pull request.\n\n    Args:\n        repository_id: The Node ID of the repository.\n        base_ref_name: The name of the branch you want your changes pulled into.\n            This should be an existing branch on the current repository.\n            You cannot update the base branch on a pull request to point\n            to another repository.\n        head_ref_name: The name of the branch where your changes are\n            implemented. For cross-repository pull requests in the same\n            network, namespace `head_ref_name` with a user like this:\n            `username:branch`.\n        title: The title of the pull request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        body: The contents of the pull request.\n        maintainer_can_modify: Indicates whether maintainers can modify the pull\n            request.\n        draft: Indicates whether this pull request should be a draft.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.create_pull_request(\n        **strip_kwargs(\n            input=dict(\n                repository_id=repository_id,\n                base_ref_name=base_ref_name,\n                head_ref_name=head_ref_name,\n                title=title,\n                body=body,\n                maintainer_can_modify=maintainer_can_modify,\n                draft=draft,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"createPullRequest\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"createPullRequest\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_reaction","title":"<code>remove_reaction</code>  <code>async</code>","text":"<p>Removes a reaction from a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji reaction to remove.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_reaction(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a reaction from a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji reaction to remove.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).reaction(**strip_kwargs())\n\n    op_stack = (\n        \"removeReaction\",\n        \"reaction\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeReaction\"][\"reaction\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_reaction_subject","title":"<code>remove_reaction_subject</code>  <code>async</code>","text":"<p>Removes a reaction from a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji reaction to remove.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_reaction_subject(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a reaction from a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji reaction to remove.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"removeReaction\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeReaction\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_star_starrable","title":"<code>remove_star_starrable</code>  <code>async</code>","text":"<p>Removes a star from a Starrable.</p> <p>Parameters:</p> Name Type Description Default <code>starrable_id</code> <code>str</code> <p>The Starrable ID to unstar.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_star_starrable(  # noqa\n    starrable_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a star from a Starrable.\n\n    Args:\n        starrable_id: The Starrable ID to unstar.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_star(\n        **strip_kwargs(\n            input=dict(\n                starrable_id=starrable_id,\n            )\n        )\n    ).starrable(**strip_kwargs())\n\n    op_stack = (\n        \"removeStar\",\n        \"starrable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeStar\"][\"starrable\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.request_reviews","title":"<code>request_reviews</code>  <code>async</code>","text":"<p>Set review requests on a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>user_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the user to request.</p> required <code>team_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the team to request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>union</code> <code>bool</code> <p>Add users to the set rather than replace.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def request_reviews(  # noqa\n    pull_request_id: str,\n    user_ids: Iterable[str],\n    team_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    union: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Set review requests on a pull request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        user_ids: The Node IDs of the user to request.\n        team_ids: The Node IDs of the team to request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        union: Add users to the set rather than replace.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.request_reviews(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                user_ids=user_ids,\n                team_ids=team_ids,\n                union=union,\n            )\n        )\n    )\n\n    op_stack = (\"requestReviews\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"requestReviews\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.request_reviews_pull_request","title":"<code>request_reviews_pull_request</code>  <code>async</code>","text":"<p>Set review requests on a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>user_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the user to request.</p> required <code>team_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the team to request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>union</code> <code>bool</code> <p>Add users to the set rather than replace.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def request_reviews_pull_request(  # noqa\n    pull_request_id: str,\n    user_ids: Iterable[str],\n    team_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    union: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Set review requests on a pull request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        user_ids: The Node IDs of the user to request.\n        team_ids: The Node IDs of the team to request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        union: Add users to the set rather than replace.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.request_reviews(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                user_ids=user_ids,\n                team_ids=team_ids,\n                union=union,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"requestReviews\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"requestReviews\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/","title":"Organization","text":""},{"location":"integrations/prefect-github/organization/#prefect_github.organization","title":"<code>prefect_github.organization</code>","text":"<p>This is a module containing: GitHub query_organization* tasks</p>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization","title":"<code>query_organization</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"organization\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_audit_log","title":"<code>query_organization_audit_log</code>  <code>async</code>","text":"<p>Audit log entries of the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>The query string to filter audit entries.</p> <code>None</code> <code>order_by</code> <code>AuditLogOrder</code> <p>Ordering options for the returned audit log entries.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_audit_log(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    order_by: graphql_schema.AuditLogOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Audit log entries of the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: The query string to filter audit entries.\n        order_by: Ordering options for the returned audit log entries.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).audit_log(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"auditLog\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"auditLog\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_domains","title":"<code>query_organization_domains</code>  <code>async</code>","text":"<p>A list of domains owned by the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_verified</code> <code>bool</code> <p>Filter by if the domain is verified.</p> <code>None</code> <code>is_approved</code> <code>bool</code> <p>Filter by if the domain is approved.</p> <code>None</code> <code>order_by</code> <code>VerifiableDomainOrder</code> <p>Ordering options for verifiable domains returned.</p> <code>{'field': 'DOMAIN', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_domains(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_verified: bool = None,\n    is_approved: bool = None,\n    order_by: graphql_schema.VerifiableDomainOrder = {\n        \"field\": \"DOMAIN\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of domains owned by the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_verified: Filter by if the domain is verified.\n        is_approved: Filter by if the domain is approved.\n        order_by: Ordering options for verifiable domains returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).domains(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_verified=is_verified,\n            is_approved=is_approved,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"domains\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"domains\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_enterprise_owners","title":"<code>query_organization_enterprise_owners</code>  <code>async</code>","text":"<p>A list of owners of the organization's enterprise account.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>The search string to look for.</p> <code>None</code> <code>organization_role</code> <code>RoleInOrganization</code> <p>The organization role to filter by.</p> <code>None</code> <code>order_by</code> <code>OrgEnterpriseOwnerOrder</code> <p>Ordering options for enterprise owners returned from the connection.</p> <code>{'field': 'LOGIN', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_enterprise_owners(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    organization_role: graphql_schema.RoleInOrganization = None,\n    order_by: graphql_schema.OrgEnterpriseOwnerOrder = {\n        \"field\": \"LOGIN\",\n        \"direction\": \"ASC\",\n    },\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of owners of the organization's enterprise account.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: The search string to look for.\n        organization_role: The organization role to filter by.\n        order_by: Ordering options for enterprise owners\n            returned from the connection.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).enterprise_owners(\n        **strip_kwargs(\n            query=query,\n            organization_role=organization_role,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"enterpriseOwners\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"enterpriseOwners\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_interaction_ability","title":"<code>query_organization_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_interaction_ability(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_ip_allow_list_entries","title":"<code>query_organization_ip_allow_list_entries</code>  <code>async</code>","text":"<p>The IP addresses that are allowed to access resources owned by the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>IpAllowListEntryOrder</code> <p>Ordering options for IP allow list entries returned.</p> <code>{'field': 'ALLOW_LIST_VALUE', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_ip_allow_list_entries(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.IpAllowListEntryOrder = {\n        \"field\": \"ALLOW_LIST_VALUE\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The IP addresses that are allowed to access resources owned by the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for IP allow list\n            entries returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).ip_allow_list_entries(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"ipAllowListEntries\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"ipAllowListEntries\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_item_showcase","title":"<code>query_organization_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_item_showcase(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_member_statuses","title":"<code>query_organization_member_statuses</code>  <code>async</code>","text":"<p>Get the status messages members of this entity have set that are either public or visible only to the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>UserStatusOrder</code> <p>Ordering options for user statuses returned from the connection.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_member_statuses(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.UserStatusOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Get the status messages members of this entity have set that are either public\n    or visible only to the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for user statuses returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).member_statuses(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"memberStatuses\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"memberStatuses\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_members_with_role","title":"<code>query_organization_members_with_role</code>  <code>async</code>","text":"<p>A list of users who are members of this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_members_with_role(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who are members of this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).members_with_role(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"membersWithRole\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"membersWithRole\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_packages","title":"<code>query_organization_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_packages(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pending_members","title":"<code>query_organization_pending_members</code>  <code>async</code>","text":"<p>A list of users who have been invited to join this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pending_members(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who have been invited to join this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pending_members(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pendingMembers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pendingMembers\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pinnable_items","title":"<code>query_organization_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pinnable_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        login: The organization's login.\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pinned_items","title":"<code>query_organization_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pinned_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        login: The organization's login.\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project","title":"<code>query_organization_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        login: The organization's login.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project_next","title":"<code>query_organization_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project_next(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        login: The organization's login.\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project_v2","title":"<code>query_organization_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project_v2(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        login: The organization's login.\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects","title":"<code>query_organization_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The organization's login.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects_next","title":"<code>query_organization_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects_next(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects_v2","title":"<code>query_organization_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects_v2(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_recent_projects","title":"<code>query_organization_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_recent_projects(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repositories","title":"<code>query_organization_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository","title":"<code>query_organization_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The organization's login.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_discussion_comments","title":"<code>query_organization_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_discussion_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_discussions","title":"<code>query_organization_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_discussions(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_migrations","title":"<code>query_organization_repository_migrations</code>  <code>async</code>","text":"<p>A list of all repository migrations for this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>state</code> <code>MigrationState</code> <p>Filter repository migrations by state.</p> <code>None</code> <code>repository_name</code> <code>str</code> <p>Filter repository migrations by repository name.</p> <code>None</code> <code>order_by</code> <code>RepositoryMigrationOrder</code> <p>Ordering options for repository migrations returned.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_migrations(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    state: graphql_schema.MigrationState = None,\n    repository_name: str = None,\n    order_by: graphql_schema.RepositoryMigrationOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of all repository migrations for this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        state: Filter repository migrations by state.\n        repository_name: Filter repository migrations by\n            repository name.\n        order_by: Ordering options for repository\n            migrations returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_migrations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            state=state,\n            repository_name=repository_name,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryMigrations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryMigrations\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_saml_identity_provider","title":"<code>query_organization_saml_identity_provider</code>  <code>async</code>","text":"<p>The Organization's SAML identity providers.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_saml_identity_provider(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The Organization's SAML identity providers.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).saml_identity_provider(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"samlIdentityProvider\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"samlIdentityProvider\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsoring","title":"<code>query_organization_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsoring(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors","title":"<code>query_organization_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors_activities","title":"<code>query_organization_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors_activities(  # noqa\n    login: str,\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        login: The organization's login.\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors_listing","title":"<code>query_organization_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors_listing(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_for_viewer_as_sponsor","title":"<code>query_organization_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_for_viewer_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsor(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_for_viewer_as_sponsorable","title":"<code>query_organization_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_for_viewer_as_sponsorable(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsorable(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_newsletters","title":"<code>query_organization_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_newsletters(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorships_as_maintainer","title":"<code>query_organization_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorships_as_maintainer(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorships_as_sponsor","title":"<code>query_organization_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorships_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_team","title":"<code>query_organization_team</code>  <code>async</code>","text":"<p>Find an organization's team by its slug.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>slug</code> <code>str</code> <p>The name or slug of the team to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_team(  # noqa\n    login: str,\n    slug: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization's team by its slug.\n\n    Args:\n        login: The organization's login.\n        slug: The name or slug of the team to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).team(\n        **strip_kwargs(\n            slug=slug,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"team\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"team\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_teams","title":"<code>query_organization_teams</code>  <code>async</code>","text":"<p>A list of teams in this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>user_logins</code> <code>Iterable[str]</code> <p>User logins to filter by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>TeamPrivacy</code> <p>If non-null, filters teams according to privacy.</p> <code>None</code> <code>role</code> <code>TeamRole</code> <p>If non-null, filters teams according to whether the viewer is an admin or member on team.</p> <code>None</code> <code>query</code> <code>str</code> <p>If non-null, filters teams with query on team name and team slug.</p> <code>None</code> <code>order_by</code> <code>TeamOrder</code> <p>Ordering options for teams returned from the connection.</p> <code>None</code> <code>ldap_mapped</code> <code>bool</code> <p>If true, filters teams that are mapped to an LDAP Group (Enterprise only).</p> <code>None</code> <code>root_teams_only</code> <code>bool</code> <p>If true, restrict to only root teams.</p> <code>False</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_teams(  # noqa\n    login: str,\n    user_logins: Iterable[str],\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.TeamPrivacy = None,\n    role: graphql_schema.TeamRole = None,\n    query: str = None,\n    order_by: graphql_schema.TeamOrder = None,\n    ldap_mapped: bool = None,\n    root_teams_only: bool = False,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of teams in this organization.\n\n    Args:\n        login: The organization's login.\n        user_logins: User logins to filter by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters teams according to privacy.\n        role: If non-null, filters teams according to whether the viewer\n            is an admin or member on team.\n        query: If non-null, filters teams with query on team name and team\n            slug.\n        order_by: Ordering options for teams returned from the connection.\n        ldap_mapped: If true, filters teams that are mapped to an LDAP\n            Group (Enterprise only).\n        root_teams_only: If true, restrict to only root teams.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).teams(\n        **strip_kwargs(\n            user_logins=user_logins,\n            privacy=privacy,\n            role=role,\n            query=query,\n            order_by=order_by,\n            ldap_mapped=ldap_mapped,\n            root_teams_only=root_teams_only,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"teams\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"teams\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/","title":"Repository","text":""},{"location":"integrations/prefect-github/repository/#prefect_github.repository","title":"<code>prefect_github.repository</code>","text":"<p>This is a module containing: GitHub query_repository* tasks and the GitHub storage block.</p>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.GitHubRepository","title":"<code>GitHubRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored on GitHub repositories.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>class GitHubRepository(ReadableDeploymentStorage):\n    \"\"\"\n    Interact with files stored on GitHub repositories.\n    \"\"\"\n\n    _block_type_name = \"GitHub Repository\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-github/repository/#prefect_github.repository.GitHubRepository\"  # noqa\n\n    repository_url: str = Field(\n        default=...,\n        title=\"Repository URL\",\n        description=(\n            \"The URL of a GitHub repository to read from, in either HTTPS or SSH \"\n            \"format. If you are using a private repo, it must be in the HTTPS format.\"\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    credentials: Optional[GitHubCredentials] = Field(\n        default=None,\n        description=\"An optional GitHubCredentials block for using private GitHub repos.\",  # noqa: E501\n    )\n\n    @validator(\"credentials\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict):\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted GitHub URLs.\"\"\"\n        if v is not None:\n            if urlparse(values[\"repository_url\"]).scheme != \"https\":\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Crendentials can only be used with GitHub repositories \"\n                        \"using the 'HTTPS' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"url to the 'HTTPS' format. \"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos: https://&lt;oauth-key&gt;@github.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urlparse(self.repository_url)\n        if url_components.scheme == \"https\" and self.credentials is not None:\n            token_value = self.credentials.token.get_secret_value()\n            updated_components = url_components._replace(\n                netloc=f\"{token_value}@{url_components.netloc}\"\n            )\n            full_url = urlunparse(updated_components)\n        else:\n            full_url = self.repository_url\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: str\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitHubRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitHub project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = f\"git clone {self._create_repo_url()}\"\n        if self.reference:\n            cmd += f\" -b {self.reference}\"\n\n        # Limit git history\n        cmd += \" --depth 1\"\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            tmp_path_str = tmp_dir\n            cmd += f\" {tmp_path_str}\"\n            cmd = shlex.split(cmd)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise RuntimeError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_path_str, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.GitHubRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect_github/repository.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitHub project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = f\"git clone {self._create_repo_url()}\"\n    if self.reference:\n        cmd += f\" -b {self.reference}\"\n\n    # Limit git history\n    cmd += \" --depth 1\"\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        tmp_path_str = tmp_dir\n        cmd += f\" {tmp_path_str}\"\n        cmd = shlex.split(cmd)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise RuntimeError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_path_str, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository","title":"<code>query_repository</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a repository\n            referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\"repository\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_assignable_users","title":"<code>query_repository_assignable_users</code>  <code>async</code>","text":"<p>A list of users that can be assigned to issues in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_assignable_users(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users that can be assigned to issues in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).assignable_users(\n        **strip_kwargs(\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"assignableUsers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"assignableUsers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_branch_protection_rules","title":"<code>query_repository_branch_protection_rules</code>  <code>async</code>","text":"<p>A list of branch protection rules for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_branch_protection_rules(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of branch protection rules for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).branch_protection_rules(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"branchProtectionRules\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"branchProtectionRules\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_code_of_conduct","title":"<code>query_repository_code_of_conduct</code>  <code>async</code>","text":"<p>Returns the code of conduct for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_code_of_conduct(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns the code of conduct for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).code_of_conduct(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"codeOfConduct\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"codeOfConduct\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_collaborators","title":"<code>query_repository_collaborators</code>  <code>async</code>","text":"<p>A list of collaborators associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>affiliation</code> <code>CollaboratorAffiliation</code> <p>Collaborators affiliation level with a repository.</p> <code>None</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_collaborators(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    affiliation: graphql_schema.CollaboratorAffiliation = None,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of collaborators associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        affiliation: Collaborators affiliation level with a\n            repository.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).collaborators(\n        **strip_kwargs(\n            affiliation=affiliation,\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"collaborators\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"collaborators\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_commit_comments","title":"<code>query_repository_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_commit_comments(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_contact_links","title":"<code>query_repository_contact_links</code>  <code>async</code>","text":"<p>Returns a list of contact links associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_contact_links(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of contact links associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).contact_links(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"contactLinks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"contactLinks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_default_branch_ref","title":"<code>query_repository_default_branch_ref</code>  <code>async</code>","text":"<p>The Ref associated with the repository's default branch.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_default_branch_ref(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The Ref associated with the repository's default branch.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).default_branch_ref(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"defaultBranchRef\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"defaultBranchRef\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_deploy_keys","title":"<code>query_repository_deploy_keys</code>  <code>async</code>","text":"<p>A list of deploy keys that are on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_deploy_keys(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of deploy keys that are on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).deploy_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"deployKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"deployKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_deployments","title":"<code>query_repository_deployments</code>  <code>async</code>","text":"<p>Deployments associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>environments</code> <code>Iterable[str]</code> <p>Environments to list deployments for.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>DeploymentOrder</code> <p>Ordering options for deployments returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_deployments(  # noqa\n    owner: str,\n    name: str,\n    environments: Iterable[str],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.DeploymentOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"ASC\",\n    },\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deployments associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        environments: Environments to list deployments for.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for deployments returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).deployments(\n        **strip_kwargs(\n            environments=environments,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"deployments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"deployments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion","title":"<code>query_repository_discussion</code>  <code>async</code>","text":"<p>Returns a single discussion from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the discussion to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single discussion from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the discussion to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussion\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussion\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion_categories","title":"<code>query_repository_discussion_categories</code>  <code>async</code>","text":"<p>A list of discussion categories that are available in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>filter_by_assignable</code> <code>bool</code> <p>Filter by categories that are assignable by the viewer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion_categories(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    filter_by_assignable: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussion categories that are available in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        filter_by_assignable: Filter by categories that\n            are assignable by the viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion_categories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            filter_by_assignable=filter_by_assignable,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussionCategories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussionCategories\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion_category","title":"<code>query_repository_discussion_category</code>  <code>async</code>","text":"<p>A discussion category by slug.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>slug</code> <code>str</code> <p>The slug of the discussion category to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion_category(  # noqa\n    owner: str,\n    name: str,\n    slug: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A discussion category by slug.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        slug: The slug of the discussion category to be\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion_category(\n        **strip_kwargs(\n            slug=slug,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussionCategory\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussionCategory\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussions","title":"<code>query_repository_discussions</code>  <code>async</code>","text":"<p>A list of discussions that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>category_id</code> <code>str</code> <p>Only include discussions that belong to the category with this ID.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussions(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    category_id: str = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussions that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        category_id: Only include discussions that belong to the\n            category with this ID.\n        order_by: Ordering options for discussions returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            category_id=category_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_environment","title":"<code>query_repository_environment</code>  <code>async</code>","text":"<p>Returns a single active environment from the current repository by name.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>environment_name</code> <code>str</code> <p>The name of the environment to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_environment(  # noqa\n    owner: str,\n    name: str,\n    environment_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single active environment from the current repository by name.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        environment_name: The name of the environment to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).environment(\n        **strip_kwargs(\n            name=environment_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"environment\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"environment\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_environments","title":"<code>query_repository_environments</code>  <code>async</code>","text":"<p>A list of environments that are in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_environments(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of environments that are in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).environments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"environments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"environments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_forks","title":"<code>query_repository_forks</code>  <code>async</code>","text":"<p>A list of direct forked repositories.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_forks(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of direct forked repositories.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to whether\n            they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).forks(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"forks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"forks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_funding_links","title":"<code>query_repository_funding_links</code>  <code>async</code>","text":"<p>The funding links for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_funding_links(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The funding links for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).funding_links(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"fundingLinks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"fundingLinks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_interaction_ability","title":"<code>query_repository_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_interaction_ability(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue","title":"<code>query_repository_issue</code>  <code>async</code>","text":"<p>Returns a single issue from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the issue to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single issue from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the issue to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue_or_pull_request","title":"<code>query_repository_issue_or_pull_request</code>  <code>async</code>","text":"<p>Returns a single issue-like object from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the issue to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue_or_pull_request(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single issue-like object from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the issue to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue_or_pull_request(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issueOrPullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issueOrPullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue_templates","title":"<code>query_repository_issue_templates</code>  <code>async</code>","text":"<p>Returns a list of issue templates associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue_templates(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of issue templates associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue_templates(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"issueTemplates\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issueTemplates\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issues","title":"<code>query_repository_issues</code>  <code>async</code>","text":"<p>A list of issues that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issues(  # noqa\n    owner: str,\n    name: str,\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_label","title":"<code>query_repository_label</code>  <code>async</code>","text":"<p>Returns a single label by name.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>label_name</code> <code>str</code> <p>Label name.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_label(  # noqa\n    owner: str,\n    name: str,\n    label_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single label by name.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        label_name: Label name.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).label(\n        **strip_kwargs(\n            name=label_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"label\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"label\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_labels","title":"<code>query_repository_labels</code>  <code>async</code>","text":"<p>A list of labels associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>LabelOrder</code> <p>Ordering options for labels returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>If provided, searches labels by name and description.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_labels(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.LabelOrder = {\"field\": \"CREATED_AT\", \"direction\": \"ASC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of labels associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for labels returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: If provided, searches labels by name and description.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).labels(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"labels\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"labels\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_languages","title":"<code>query_repository_languages</code>  <code>async</code>","text":"<p>A list containing a breakdown of the language composition of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>LanguageOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_languages(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.LanguageOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list containing a breakdown of the language composition of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).languages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"languages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"languages\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_latest_release","title":"<code>query_repository_latest_release</code>  <code>async</code>","text":"<p>Get the latest release for the repository if one exists.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_latest_release(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Get the latest release for the repository if one exists.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).latest_release(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"latestRelease\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"latestRelease\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_license_info","title":"<code>query_repository_license_info</code>  <code>async</code>","text":"<p>The license associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_license_info(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The license associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).license_info(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"licenseInfo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"licenseInfo\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_mentionable_users","title":"<code>query_repository_mentionable_users</code>  <code>async</code>","text":"<p>A list of Users that can be mentioned in the context of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_mentionable_users(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of Users that can be mentioned in the context of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).mentionable_users(\n        **strip_kwargs(\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"mentionableUsers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"mentionableUsers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_milestone","title":"<code>query_repository_milestone</code>  <code>async</code>","text":"<p>Returns a single milestone from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the milestone to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_milestone(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single milestone from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the milestone to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).milestone(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"milestone\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"milestone\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_milestones","title":"<code>query_repository_milestones</code>  <code>async</code>","text":"<p>A list of milestones associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[MilestoneState]</code> <p>Filter by the state of the milestones.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>MilestoneOrder</code> <p>Ordering options for milestones.</p> <code>None</code> <code>query</code> <code>str</code> <p>Filters milestones with a query on the title.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_milestones(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.MilestoneState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.MilestoneOrder = None,\n    query: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of milestones associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: Filter by the state of the milestones.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for milestones.\n        query: Filters milestones with a query on the title.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).milestones(\n        **strip_kwargs(\n            states=states,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            query=query,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"milestones\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"milestones\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_object","title":"<code>query_repository_object</code>  <code>async</code>","text":"<p>A Git object in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>oid</code> <code>datetime</code> <p>The Git object ID.</p> <code>None</code> <code>expression</code> <code>str</code> <p>A Git revision expression suitable for rev-parse.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_object(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    oid: datetime = None,\n    expression: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A Git object in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        oid: The Git object ID.\n        expression: A Git revision expression suitable for rev-parse.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).object(\n        **strip_kwargs(\n            oid=oid,\n            expression=expression,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"object\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"object\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_owner","title":"<code>query_repository_owner</code>  <code>async</code>","text":"<p>The User owner of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_owner(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The User owner of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).owner(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"owner\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"owner\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_packages","title":"<code>query_repository_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_packages(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pinned_discussions","title":"<code>query_repository_pinned_discussions</code>  <code>async</code>","text":"<p>A list of discussions that have been pinned in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pinned_discussions(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussions that have been pinned in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pinned_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pinnedDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pinnedDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pinned_issues","title":"<code>query_repository_pinned_issues</code>  <code>async</code>","text":"<p>A list of pinned issues for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pinned_issues(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pinned issues for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pinned_issues(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pinnedIssues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pinnedIssues\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_primary_language","title":"<code>query_repository_primary_language</code>  <code>async</code>","text":"<p>The primary language of the repository's code.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_primary_language(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The primary language of the repository's code.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).primary_language(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"primaryLanguage\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"primaryLanguage\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project","title":"<code>query_repository_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project_next","title":"<code>query_repository_project_next</code>  <code>async</code>","text":"<p>Finds and returns the Project (beta) according to the provided Project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The ProjectNext number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project_next(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Finds and returns the Project (beta) according to the provided Project (beta)\n    number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The ProjectNext number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project_v2","title":"<code>query_repository_project_v2</code>  <code>async</code>","text":"<p>Finds and returns the Project according to the provided Project number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The Project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project_v2(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Finds and returns the Project according to the provided Project number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The Project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects","title":"<code>query_repository_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects_next","title":"<code>query_repository_projects_next</code>  <code>async</code>","text":"<p>List of projects (beta) linked to this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>A project (beta) to search for linked to the repo.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned project (beta) objects.</p> <code>'TITLE'</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects_next(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of projects (beta) linked to this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: A project (beta) to search for linked to the repo.\n        sort_by: How to order the returned project (beta) objects.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            sort_by=sort_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects_v2","title":"<code>query_repository_projects_v2</code>  <code>async</code>","text":"<p>List of projects linked to this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>A project to search for linked to the repo.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects_v2(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of projects linked to this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: A project to search for linked to the repo.\n        order_by: How to order the returned projects.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_request","title":"<code>query_repository_pull_request</code>  <code>async</code>","text":"<p>Returns a single pull request from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the pull request to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_request(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single pull request from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the pull request to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_request(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_request_templates","title":"<code>query_repository_pull_request_templates</code>  <code>async</code>","text":"<p>Returns a list of pull request templates associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_request_templates(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of pull request templates associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_request_templates(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"pullRequestTemplates\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequestTemplates\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_requests","title":"<code>query_repository_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_requests(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_recent_projects","title":"<code>query_repository_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_recent_projects(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_ref","title":"<code>query_repository_ref</code>  <code>async</code>","text":"<p>Fetch a given ref from the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>qualified_name</code> <code>str</code> <p>The ref to retrieve. Fully qualified matches are checked in order (<code>refs/heads/master</code>) before falling back onto checks for short name matches (<code>master</code>).</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_ref(  # noqa\n    owner: str,\n    name: str,\n    qualified_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Fetch a given ref from the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        qualified_name: The ref to retrieve. Fully qualified matches are\n            checked in order (`refs/heads/master`) before falling back\n            onto checks for short name matches (`master`).\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).ref(\n        **strip_kwargs(\n            qualified_name=qualified_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"ref\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"ref\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_refs","title":"<code>query_repository_refs</code>  <code>async</code>","text":"<p>Fetch a list of refs from the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>ref_prefix</code> <code>str</code> <p>A ref name prefix like <code>refs/heads/</code>, <code>refs/tags/</code>, etc.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters refs with query on name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>direction</code> <code>OrderDirection</code> <code>None</code> <code>order_by</code> <code>RefOrder</code> <p>Ordering options for refs returned from the connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_refs(  # noqa\n    owner: str,\n    name: str,\n    ref_prefix: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    direction: graphql_schema.OrderDirection = None,\n    order_by: graphql_schema.RefOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Fetch a list of refs from the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        ref_prefix: A ref name prefix like `refs/heads/`, `refs/tags/`,\n            etc.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters refs with query on name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        direction: DEPRECATED: use orderBy. The ordering direction.\n        order_by: Ordering options for refs returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).refs(\n        **strip_kwargs(\n            ref_prefix=ref_prefix,\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            direction=direction,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"refs\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"refs\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_release","title":"<code>query_repository_release</code>  <code>async</code>","text":"<p>Lookup a single release given various criteria.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>tag_name</code> <code>str</code> <p>The name of the Tag the Release was created from.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_release(  # noqa\n    owner: str,\n    name: str,\n    tag_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Lookup a single release given various criteria.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        tag_name: The name of the Tag the Release was created from.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).release(\n        **strip_kwargs(\n            tag_name=tag_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"release\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"release\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_releases","title":"<code>query_repository_releases</code>  <code>async</code>","text":"<p>List of releases which are dependent on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>ReleaseOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_releases(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.ReleaseOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of releases which are dependent on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).releases(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"releases\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"releases\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_repository_topics","title":"<code>query_repository_repository_topics</code>  <code>async</code>","text":"<p>A list of applied repository-topic associations for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_repository_topics(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of applied repository-topic associations for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).repository_topics(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"repositoryTopics\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"repositoryTopics\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_stargazers","title":"<code>query_repository_stargazers</code>  <code>async</code>","text":"<p>A list of users who have starred this starrable.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_stargazers(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who have starred this starrable.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).stargazers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"stargazers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"stargazers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_submodules","title":"<code>query_repository_submodules</code>  <code>async</code>","text":"<p>Returns a list of all submodules in this repository parsed from the .gitmodules file as of the default branch's HEAD commit.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_submodules(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of all submodules in this repository parsed from the .gitmodules\n    file as of the default branch's HEAD commit.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).submodules(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"submodules\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"submodules\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_vulnerability_alerts","title":"<code>query_repository_vulnerability_alerts</code>  <code>async</code>","text":"<p>A list of vulnerability alerts that are on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[RepositoryVulnerabilityAlertState]</code> <p>Filter by the state of the alert.</p> required <code>dependency_scopes</code> <code>Iterable[RepositoryVulnerabilityAlertDependencyScope]</code> <p>Filter by the scope of the alert's dependency.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_vulnerability_alerts(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.RepositoryVulnerabilityAlertState],\n    dependency_scopes: Iterable[\n        graphql_schema.RepositoryVulnerabilityAlertDependencyScope\n    ],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of vulnerability alerts that are on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: Filter by the state of the alert.\n        dependency_scopes: Filter by the scope of the\n            alert's dependency.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).vulnerability_alerts(\n        **strip_kwargs(\n            states=states,\n            dependency_scopes=dependency_scopes,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"vulnerabilityAlerts\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"vulnerabilityAlerts\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_watchers","title":"<code>query_repository_watchers</code>  <code>async</code>","text":"<p>A list of users watching the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_watchers(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users watching the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).watchers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"watchers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"watchers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/","title":"Repository Owner","text":""},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner","title":"<code>prefect_github.repository_owner</code>","text":"<p>This is a module containing: GitHub query_repository_owner* tasks</p>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner","title":"<code>query_repository_owner</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The username to lookup the owner by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"repositoryOwner\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner_repositories","title":"<code>query_repository_owner_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The username to lookup the owner by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"repositoryOwner\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner_repository","title":"<code>query_repository_owner_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The username to lookup the owner by.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"repositoryOwner\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/","title":"User","text":""},{"location":"integrations/prefect-github/user/#prefect_github.user","title":"<code>prefect_github.user</code>","text":"<p>This is a module containing: GitHub query_user* tasks</p>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user","title":"<code>query_user</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"user\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_commit_comments","title":"<code>query_user_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_commit_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_contributions_collection","title":"<code>query_user_contributions_collection</code>  <code>async</code>","text":"<p>The collection of contributions this user has made to different repositories.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>organization_id</code> <code>str</code> <p>The ID of the organization used to filter contributions.</p> <code>None</code> <code>from_</code> <code>datetime</code> <p>Only contributions made at this time or later will be counted. If omitted, defaults to a year ago.</p> <code>None</code> <code>to</code> <code>datetime</code> <p>Only contributions made before and up to (including) this time will be counted. If omitted, defaults to the current time or one year from the provided from argument.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_contributions_collection(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    organization_id: str = None,\n    from_: datetime = None,\n    to: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The collection of contributions this user has made to different repositories.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        organization_id: The ID of the organization\n            used to filter contributions.\n        from_: Only contributions made at this time or\n            later will be counted. If omitted, defaults to a year ago.\n        to: Only contributions made before and up to\n            (including) this time will be counted. If omitted, defaults\n            to the current time or one year from the provided from\n            argument.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).contributions_collection(\n        **strip_kwargs(\n            organization_id=organization_id,\n            from_=from_,\n            to=to,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"contributionsCollection\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"contributionsCollection\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_followers","title":"<code>query_user_followers</code>  <code>async</code>","text":"<p>A list of users the given user is followed by.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_followers(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is followed by.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).followers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"followers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"followers\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_following","title":"<code>query_user_following</code>  <code>async</code>","text":"<p>A list of users the given user is following.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_following(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is following.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).following(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"following\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"following\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gist","title":"<code>query_user_gist</code>  <code>async</code>","text":"<p>Find gist by repo name.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>name</code> <code>str</code> <p>The gist name to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gist(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find gist by repo name.\n\n    Args:\n        login: The user's login.\n        name: The gist name to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gist(\n        **strip_kwargs(\n            name=name,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gist\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gist\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gist_comments","title":"<code>query_user_gist_comments</code>  <code>async</code>","text":"<p>A list of gist comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gist_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of gist comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gist_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gistComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gistComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gists","title":"<code>query_user_gists</code>  <code>async</code>","text":"<p>A list of the Gists the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>GistPrivacy</code> <p>Filters Gists according to privacy.</p> <code>None</code> <code>order_by</code> <code>GistOrder</code> <p>Ordering options for gists returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gists(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.GistPrivacy = None,\n    order_by: graphql_schema.GistOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of the Gists the user has created.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: Filters Gists according to privacy.\n        order_by: Ordering options for gists returned from the connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gists(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gists\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gists\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_interaction_ability","title":"<code>query_user_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_interaction_ability(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_issue_comments","title":"<code>query_user_issue_comments</code>  <code>async</code>","text":"<p>A list of issue comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueCommentOrder</code> <p>Ordering options for issue comments returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_issue_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueCommentOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issue comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issue comments returned\n            from the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).issue_comments(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"issueComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"issueComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_issues","title":"<code>query_user_issues</code>  <code>async</code>","text":"<p>A list of issues associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_issues(  # noqa\n    login: str,\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues associated with this user.\n\n    Args:\n        login: The user's login.\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_item_showcase","title":"<code>query_user_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_item_showcase(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_organization","title":"<code>query_user_organization</code>  <code>async</code>","text":"<p>Find an organization by its login that the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>organization_login</code> <code>str</code> <p>The login of the organization to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_organization(  # noqa\n    login: str,\n    organization_login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization by its login that the user belongs to.\n\n    Args:\n        login: The user's login.\n        organization_login: The login of the organization to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).organization(\n        **strip_kwargs(\n            login=organization_login,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"organization\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_organizations","title":"<code>query_user_organizations</code>  <code>async</code>","text":"<p>A list of organizations the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_organizations(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of organizations the user belongs to.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).organizations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"organizations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"organizations\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_packages","title":"<code>query_user_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_packages(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pinnable_items","title":"<code>query_user_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pinnable_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        login: The user's login.\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pinned_items","title":"<code>query_user_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pinned_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        login: The user's login.\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project","title":"<code>query_user_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        login: The user's login.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project_next","title":"<code>query_user_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project_next(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        login: The user's login.\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project_v2","title":"<code>query_user_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project_v2(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        login: The user's login.\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects","title":"<code>query_user_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The user's login.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects_next","title":"<code>query_user_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects_next(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects_v2","title":"<code>query_user_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects_v2(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_public_keys","title":"<code>query_user_public_keys</code>  <code>async</code>","text":"<p>A list of public keys associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_public_keys(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of public keys associated with this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).public_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"publicKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"publicKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pull_requests","title":"<code>query_user_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pull_requests(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests associated with this user.\n\n    Args:\n        login: The user's login.\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_recent_projects","title":"<code>query_user_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_recent_projects(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repositories","title":"<code>query_user_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repositories_contributed_to","title":"<code>query_user_repositories_contributed_to</code>  <code>async</code>","text":"<p>A list of repositories that the user recently contributed to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>include_user_repositories</code> <code>bool</code> <p>If true, include user repositories.</p> <code>None</code> <code>contribution_types</code> <code>Iterable[RepositoryContributionType]</code> <p>If non-null, include only the specified types of contributions. The GitHub.com UI uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repositories_contributed_to(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    is_locked: bool = None,\n    include_user_repositories: bool = None,\n    contribution_types: Iterable[graphql_schema.RepositoryContributionType] = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user recently contributed to.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories\n            according to privacy.\n        order_by: Ordering options for repositories\n            returned from the connection.\n        is_locked: If non-null, filters repositories\n            according to whether they have been locked.\n        include_user_repositories: If true, include\n            user repositories.\n        contribution_types: If non-null, include\n            only the specified types of contributions. The GitHub.com UI\n            uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories_contributed_to(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            is_locked=is_locked,\n            include_user_repositories=include_user_repositories,\n            contribution_types=contribution_types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoriesContributedTo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoriesContributedTo\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository","title":"<code>query_user_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The user's login.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository_discussion_comments","title":"<code>query_user_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository_discussion_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository_discussions","title":"<code>query_user_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository_discussions(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_saved_replies","title":"<code>query_user_saved_replies</code>  <code>async</code>","text":"<p>Replies this user has saved.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SavedReplyOrder</code> <p>The field to order saved replies by.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_saved_replies(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SavedReplyOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Replies this user has saved.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: The field to order saved replies by.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).saved_replies(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"savedReplies\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"savedReplies\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsoring","title":"<code>query_user_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsoring(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors","title":"<code>query_user_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors_activities","title":"<code>query_user_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors_activities(  # noqa\n    login: str,\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        login: The user's login.\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors_listing","title":"<code>query_user_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors_listing(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_for_viewer_as_sponsor","title":"<code>query_user_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_for_viewer_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsor(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_for_viewer_as_sponsorable","title":"<code>query_user_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_for_viewer_as_sponsorable(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsorable(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_newsletters","title":"<code>query_user_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_newsletters(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorships_as_maintainer","title":"<code>query_user_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorships_as_maintainer(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorships_as_sponsor","title":"<code>query_user_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorships_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_starred_repositories","title":"<code>query_user_starred_repositories</code>  <code>async</code>","text":"<p>Repositories the user has starred.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>owned_by_viewer</code> <code>bool</code> <p>Filters starred repositories to only return repositories owned by the viewer.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_starred_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    owned_by_viewer: bool = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has starred.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        owned_by_viewer: Filters starred repositories to\n            only return repositories owned by the viewer.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).starred_repositories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            owned_by_viewer=owned_by_viewer,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"starredRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"starredRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_status","title":"<code>query_user_status</code>  <code>async</code>","text":"<p>The user's description of what they're currently doing.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_status(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The user's description of what they're currently doing.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).status(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"status\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"status\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_top_repositories","title":"<code>query_user_top_repositories</code>  <code>async</code>","text":"<p>Repositories the user has contributed to, ordered by contribution rank, plus repositories the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>since</code> <code>datetime</code> <p>How far back in time to fetch contributed repositories.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_top_repositories(  # noqa\n    login: str,\n    order_by: graphql_schema.RepositoryOrder,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    since: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has contributed to, ordered by contribution rank, plus\n    repositories the user has created.\n\n    Args:\n        login: The user's login.\n        order_by: Ordering options for repositories returned\n            from the connection.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        since: How far back in time to fetch contributed\n            repositories.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).top_repositories(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            since=since,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"topRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"topRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_watching","title":"<code>query_user_watching</code>  <code>async</code>","text":"<p>A list of repositories the given user is watching.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Affiliation options for repositories returned from the connection. If none specified, the results will include repositories for which the current viewer is an owner or collaborator, or member.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_watching(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories the given user is watching.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Affiliation options for repositories returned\n            from the connection. If none specified, the results will\n            include repositories for which the current viewer is an\n            owner or collaborator, or member.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).watching(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"watching\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"watching\"]\n</code></pre>"},{"location":"integrations/prefect-github/utils/","title":"Utils","text":""},{"location":"integrations/prefect-github/utils/#prefect_github.utils","title":"<code>prefect_github.utils</code>","text":"<p>Utilities to assist with using generated collections.</p>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.camel_to_snake_case","title":"<code>camel_to_snake_case</code>","text":"<p>Converts CamelCase and lowerCamelCase to snake_case. Args:     string: The string in CamelCase or lowerCamelCase to convert. Returns:     A snake_case version of the string.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def camel_to_snake_case(string: str) -&gt; str:\n    \"\"\"\n    Converts CamelCase and lowerCamelCase to snake_case.\n    Args:\n        string: The string in CamelCase or lowerCamelCase to convert.\n    Returns:\n        A snake_case version of the string.\n    \"\"\"\n    string = SNAKE_CASE_REGEX1.sub(r\"\\1_\\2\", string)\n    return SNAKE_CASE_REGEX2.sub(r\"\\1_\\2\", string).lower()\n</code></pre>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.initialize_return_fields_defaults","title":"<code>initialize_return_fields_defaults</code>","text":"<p>Reads config_path to parse out the desired default fields to return. Args:     config_path: The path to the config file.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def initialize_return_fields_defaults(config_path: Union[Path, str]) -&gt; List:\n    \"\"\"\n    Reads config_path to parse out the desired default fields to return.\n    Args:\n        config_path: The path to the config file.\n    \"\"\"\n    with open(config_path, \"r\") as f:\n        config = json.load(f)\n\n    return_fields_defaults = defaultdict(lambda: [])\n    for op_type, sub_op_types in config.items():\n        for sub_op_type in sub_op_types:\n            if isinstance(sub_op_type, str):\n                return_fields_defaults[(op_type,)].append(\n                    camel_to_snake_case(sub_op_type)\n                )\n            elif isinstance(sub_op_type, dict):\n                sub_op_type_key = list(sub_op_type.keys())[0]\n                return_fields_defaults[(op_type, sub_op_type_key)] = [\n                    camel_to_snake_case(field) for field in sub_op_type[sub_op_type_key]\n                ]\n    return return_fields_defaults\n</code></pre>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.strip_kwargs","title":"<code>strip_kwargs</code>","text":"<p>Drops keyword arguments if value is None because sgqlc.Operation errors out if a keyword argument is provided, but set to None.</p> <p>Parameters:</p> Name Type Description Default <code>**kwargs</code> <code>Dict</code> <p>Input keyword arguments.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict</code> <p>Stripped version of kwargs.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def strip_kwargs(**kwargs: Dict) -&gt; Dict:\n    \"\"\"\n    Drops keyword arguments if value is None because sgqlc.Operation\n    errors out if a keyword argument is provided, but set to None.\n\n    Args:\n        **kwargs: Input keyword arguments.\n\n    Returns:\n        Stripped version of kwargs.\n    \"\"\"\n    stripped_dict = {}\n    for k, v in kwargs.items():\n        if isinstance(v, dict):\n            v = strip_kwargs(**v)\n        if v is not None:\n            stripped_dict[k] = v\n    return stripped_dict or {}\n</code></pre>"},{"location":"integrations/prefect-github/viewer/","title":"Viewer","text":""},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer","title":"<code>prefect_github.viewer</code>","text":"<p>This is a module containing: GitHub query_viewer* tasks</p>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer","title":"<code>query_viewer</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs())\n\n    op_stack = (\"viewer\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_commit_comments","title":"<code>query_viewer_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_commit_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_contributions_collection","title":"<code>query_viewer_contributions_collection</code>  <code>async</code>","text":"<p>The collection of contributions this user has made to different repositories.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>organization_id</code> <code>str</code> <p>The ID of the organization used to filter contributions.</p> <code>None</code> <code>from_</code> <code>datetime</code> <p>Only contributions made at this time or later will be counted. If omitted, defaults to a year ago.</p> <code>None</code> <code>to</code> <code>datetime</code> <p>Only contributions made before and up to (including) this time will be counted. If omitted, defaults to the current time or one year from the provided from argument.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_contributions_collection(  # noqa\n    github_credentials: GitHubCredentials,\n    organization_id: str = None,\n    from_: datetime = None,\n    to: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The collection of contributions this user has made to different repositories.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        organization_id: The ID of the organization\n            used to filter contributions.\n        from_: Only contributions made at this time or\n            later will be counted. If omitted, defaults to a year ago.\n        to: Only contributions made before and up to\n            (including) this time will be counted. If omitted, defaults\n            to the current time or one year from the provided from\n            argument.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).contributions_collection(\n        **strip_kwargs(\n            organization_id=organization_id,\n            from_=from_,\n            to=to,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"contributionsCollection\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"contributionsCollection\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_followers","title":"<code>query_viewer_followers</code>  <code>async</code>","text":"<p>A list of users the given user is followed by.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_followers(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is followed by.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).followers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"followers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"followers\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_following","title":"<code>query_viewer_following</code>  <code>async</code>","text":"<p>A list of users the given user is following.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_following(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is following.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).following(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"following\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"following\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gist","title":"<code>query_viewer_gist</code>  <code>async</code>","text":"<p>Find gist by repo name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The gist name to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gist(  # noqa\n    name: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find gist by repo name.\n\n    Args:\n        name: The gist name to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gist(\n        **strip_kwargs(\n            name=name,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gist\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gist\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gist_comments","title":"<code>query_viewer_gist_comments</code>  <code>async</code>","text":"<p>A list of gist comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gist_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of gist comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gist_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gistComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gistComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gists","title":"<code>query_viewer_gists</code>  <code>async</code>","text":"<p>A list of the Gists the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>GistPrivacy</code> <p>Filters Gists according to privacy.</p> <code>None</code> <code>order_by</code> <code>GistOrder</code> <p>Ordering options for gists returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gists(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.GistPrivacy = None,\n    order_by: graphql_schema.GistOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of the Gists the user has created.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: Filters Gists according to privacy.\n        order_by: Ordering options for gists returned from the connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gists(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gists\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gists\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_interaction_ability","title":"<code>query_viewer_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_interaction_ability(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_issue_comments","title":"<code>query_viewer_issue_comments</code>  <code>async</code>","text":"<p>A list of issue comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueCommentOrder</code> <p>Ordering options for issue comments returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_issue_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueCommentOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issue comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issue comments returned\n            from the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).issue_comments(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"issueComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"issueComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_issues","title":"<code>query_viewer_issues</code>  <code>async</code>","text":"<p>A list of issues associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_issues(  # noqa\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues associated with this user.\n\n    Args:\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_item_showcase","title":"<code>query_viewer_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_item_showcase(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_organization","title":"<code>query_viewer_organization</code>  <code>async</code>","text":"<p>Find an organization by its login that the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The login of the organization to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_organization(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization by its login that the user belongs to.\n\n    Args:\n        login: The login of the organization to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).organization(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"organization\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_organizations","title":"<code>query_viewer_organizations</code>  <code>async</code>","text":"<p>A list of organizations the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_organizations(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of organizations the user belongs to.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).organizations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"organizations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"organizations\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_packages","title":"<code>query_viewer_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_packages(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pinnable_items","title":"<code>query_viewer_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pinnable_items(  # noqa\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pinned_items","title":"<code>query_viewer_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pinned_items(  # noqa\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project","title":"<code>query_viewer_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project_next","title":"<code>query_viewer_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project_next(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project_v2","title":"<code>query_viewer_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project_v2(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects","title":"<code>query_viewer_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects(  # noqa\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects_next","title":"<code>query_viewer_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects_next(  # noqa\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects_v2","title":"<code>query_viewer_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects_v2(  # noqa\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_public_keys","title":"<code>query_viewer_public_keys</code>  <code>async</code>","text":"<p>A list of public keys associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_public_keys(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of public keys associated with this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).public_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"publicKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"publicKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pull_requests","title":"<code>query_viewer_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pull_requests(  # noqa\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests associated with this user.\n\n    Args:\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_recent_projects","title":"<code>query_viewer_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_recent_projects(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repositories","title":"<code>query_viewer_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repositories(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repositories_contributed_to","title":"<code>query_viewer_repositories_contributed_to</code>  <code>async</code>","text":"<p>A list of repositories that the user recently contributed to.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>include_user_repositories</code> <code>bool</code> <p>If true, include user repositories.</p> <code>None</code> <code>contribution_types</code> <code>Iterable[RepositoryContributionType]</code> <p>If non-null, include only the specified types of contributions. The GitHub.com UI uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repositories_contributed_to(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    is_locked: bool = None,\n    include_user_repositories: bool = None,\n    contribution_types: Iterable[graphql_schema.RepositoryContributionType] = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user recently contributed to.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories\n            according to privacy.\n        order_by: Ordering options for repositories\n            returned from the connection.\n        is_locked: If non-null, filters repositories\n            according to whether they have been locked.\n        include_user_repositories: If true, include\n            user repositories.\n        contribution_types: If non-null, include\n            only the specified types of contributions. The GitHub.com UI\n            uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repositories_contributed_to(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            is_locked=is_locked,\n            include_user_repositories=include_user_repositories,\n            contribution_types=contribution_types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoriesContributedTo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoriesContributedTo\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository","title":"<code>query_viewer_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository(  # noqa\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository_discussion_comments","title":"<code>query_viewer_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository_discussion_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository_discussions","title":"<code>query_viewer_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository_discussions(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_saved_replies","title":"<code>query_viewer_saved_replies</code>  <code>async</code>","text":"<p>Replies this user has saved.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SavedReplyOrder</code> <p>The field to order saved replies by.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_saved_replies(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SavedReplyOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Replies this user has saved.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: The field to order saved replies by.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).saved_replies(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"savedReplies\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"savedReplies\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsoring","title":"<code>query_viewer_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsoring(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors","title":"<code>query_viewer_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors_activities","title":"<code>query_viewer_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors_activities(  # noqa\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors_listing","title":"<code>query_viewer_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors_listing(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsor","title":"<code>query_viewer_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_for_viewer_as_sponsor(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_for_viewer_as_sponsor(\n        **strip_kwargs()\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsorable","title":"<code>query_viewer_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_for_viewer_as_sponsorable(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_for_viewer_as_sponsorable(\n        **strip_kwargs()\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_newsletters","title":"<code>query_viewer_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_newsletters(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorships_as_maintainer","title":"<code>query_viewer_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorships_as_maintainer(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorships_as_sponsor","title":"<code>query_viewer_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorships_as_sponsor(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_starred_repositories","title":"<code>query_viewer_starred_repositories</code>  <code>async</code>","text":"<p>Repositories the user has starred.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>owned_by_viewer</code> <code>bool</code> <p>Filters starred repositories to only return repositories owned by the viewer.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_starred_repositories(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    owned_by_viewer: bool = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has starred.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        owned_by_viewer: Filters starred repositories to\n            only return repositories owned by the viewer.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).starred_repositories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            owned_by_viewer=owned_by_viewer,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"starredRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"starredRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_status","title":"<code>query_viewer_status</code>  <code>async</code>","text":"<p>The user's description of what they're currently doing.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_status(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The user's description of what they're currently doing.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).status(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"status\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"status\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_top_repositories","title":"<code>query_viewer_top_repositories</code>  <code>async</code>","text":"<p>Repositories the user has contributed to, ordered by contribution rank, plus repositories the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>since</code> <code>datetime</code> <p>How far back in time to fetch contributed repositories.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_top_repositories(  # noqa\n    order_by: graphql_schema.RepositoryOrder,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    since: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has contributed to, ordered by contribution rank, plus\n    repositories the user has created.\n\n    Args:\n        order_by: Ordering options for repositories returned\n            from the connection.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        since: How far back in time to fetch contributed\n            repositories.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).top_repositories(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            since=since,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"topRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"topRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_watching","title":"<code>query_viewer_watching</code>  <code>async</code>","text":"<p>A list of repositories the given user is watching.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Affiliation options for repositories returned from the connection. If none specified, the results will include repositories for which the current viewer is an owner or collaborator, or member.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_watching(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories the given user is watching.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Affiliation options for repositories returned\n            from the connection. If none specified, the results will\n            include repositories for which the current viewer is an\n            owner or collaborator, or member.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).watching(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"watching\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"watching\"]\n</code></pre>"},{"location":"integrations/prefect-gitlab/","title":"prefect-gitlab","text":"<p>The prefect-gitlab library makes it easy to interact with GitLab repositories and credentials.</p>"},{"location":"integrations/prefect-gitlab/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-gitlab/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A GitLab account.</li> </ul>"},{"location":"integrations/prefect-gitlab/#install-prefect-gitlab","title":"Install prefect-gitlab","text":"<pre><code>pip install -U prefect-gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-gitlab module to make them available for use.</p> <pre><code>prefect block register -m prefect_gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-gitlab/#store-deployment-flow-code-in-a-private-gitlab-repository","title":"Store deployment flow code in a private GitLab repository","text":"<p>To create a deployment where the flow code is stored in a private GitLab repository, you can use the <code>GitLabCredentials</code> block.</p> <p>A deployment can use flow code stored in a GitLab repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Code to create a GitLab Credentials block:</p> <pre><code>from prefect_gitlab import GitLabCredentials\n\n\ngitlab_credentials_block = GitLabCredentials(token=\"my_token\")\ngitlab_credentials_block.save(name=\"my-gitlab-credentials-block\")\n</code></pre>"},{"location":"integrations/prefect-gitlab/#access-flow-code-stored-in-a-private-gitlab-repository-in-a-deployment","title":"Access flow code stored in a private GitLab repository in a deployment","text":"<p>Use the credentials block you created above to pass the GitLab access token during deployment creation. The code below assumes there's flow code in your private GitLab repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_gitlab import GitLabCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://gitlab.com/org/private-repo.git\",\n        credentials=GitLabCredentials.load(\"my-gitlab-credentials-block\")\n    ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-gitlab-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the GitLab Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.gitlab-credentials.my-gitlab-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-gitlab/#interact-with-a-gitlab-repository","title":"Interact with a GitLab repository","text":"<p>The code below shows how to reference a particular branch or tag of a GitLab repository.</p> <pre><code>from prefect_gitlab import GitLabRepository\n\ndef save_private_gitlab_block():\n    private_gitlab_block = GitLabRepository(\n        repository=\"https://gitlab.com/testing/my-repository.git\",\n        access_token=\"YOUR_GITLAB_PERSONAL_ACCESS_TOKEN\",\n        reference=\"branch-or-tag-name\",\n    )\n\n    private_gitlab_block.save(\"my-private-gitlab-block\")\n\n\nif __name__ == \"__main__\":\n    save_private_gitlab_block()\n</code></pre> <p>Exclude the <code>access_token</code> field if the repository is public and exclude the <code>reference</code> field to use the default branch.</p> <p>Use the newly created block to interact with the GitLab repository.</p> <p>For example, download the repository contents with the <code>.get_directory()</code> method like this:</p> <pre><code>from prefect_gitlab.repositories import GitLabRepository\n\ndef fetch_repo():\n    private_gitlab_block = GitLabRepository.load(\"my-gitlab-block\")\n    private_gitlab_block.get_directory()\n\nif __name__ == \"__main__\":\n    fetch_repo()\n</code></pre>"},{"location":"integrations/prefect-gitlab/#resources","title":"Resources","text":"<p>For assistance using GitLab, consult the GitLab documentation.</p> <p>Refer to the prefect-gitlab API documentation linked in the sidebar to explore all the capabilities of the prefect-gitlab library.</p>"},{"location":"integrations/prefect-gitlab/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials","title":"<code>prefect_gitlab.credentials</code>","text":"<p>Module used to enable authenticated interactions with GitLab</p>"},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials.GitLabCredentials","title":"<code>GitLabCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Store a GitLab personal access token to interact with private GitLab repositories.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>SecretStr</code> <p>The personal access token to authenticate with GitLab.</p> <code>url</code> <code>str</code> <p>URL to self-hosted GitLab instances.</p> <p>Examples:</p> <p>Load stored GitLab credentials: <pre><code>from prefect_gitlab import GitLabCredentials\ngitlab_credentials_block = GitLabCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gitlab/credentials.py</code> <pre><code>class GitLabCredentials(Block):\n    \"\"\"\n    Store a GitLab personal access token to interact with private GitLab\n    repositories.\n\n    Attributes:\n        token: The personal access token to authenticate with GitLab.\n        url: URL to self-hosted GitLab instances.\n\n    Examples:\n        Load stored GitLab credentials:\n        ```python\n        from prefect_gitlab import GitLabCredentials\n        gitlab_credentials_block = GitLabCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"GitLab Credentials\"\n    _logo_url = HttpUrl(\n        url=\"https://images.ctfassets.net/gm98wzqotmnx/55edIimT4g9gbjhkh5a3Sp/dfdb9391d8f45c2e93e72e3a4d350771/gitlab-logo-500.png?h=250\",  # noqa\n        scheme=\"https\",\n    )\n\n    token: SecretStr = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=\"A GitLab Personal Access Token with read_repository scope.\",\n    )\n    url: str = Field(\n        default=None, title=\"URL\", description=\"URL to self-hosted GitLab instances.\"\n    )\n\n    def get_client(self) -&gt; Gitlab:\n        \"\"\"\n        Gets an authenticated GitLab client.\n\n        Returns:\n            An authenticated GitLab client.\n        \"\"\"\n        # ref: https://python-gitlab.readthedocs.io/en/stable/\n        gitlab = Gitlab(url=self.url, oauth_token=self.token.get_secret_value())\n        gitlab.auth()\n        return gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials.GitLabCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an authenticated GitLab client.</p> <p>Returns:</p> Type Description <code>Gitlab</code> <p>An authenticated GitLab client.</p> Source code in <code>prefect_gitlab/credentials.py</code> <pre><code>def get_client(self) -&gt; Gitlab:\n    \"\"\"\n    Gets an authenticated GitLab client.\n\n    Returns:\n        An authenticated GitLab client.\n    \"\"\"\n    # ref: https://python-gitlab.readthedocs.io/en/stable/\n    gitlab = Gitlab(url=self.url, oauth_token=self.token.get_secret_value())\n    gitlab.auth()\n    return gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/","title":"Repositories","text":""},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories","title":"<code>prefect_gitlab.repositories</code>","text":"<p>Integrations with GitLab.</p> <p>The <code>GitLab</code> class in this collection is a storage block that lets Prefect agents pull Prefect flow code from GitLab repositories.</p> <p>The <code>GitLab</code> block is ideally configured via the Prefect UI, but can also be used in Python as the following examples demonstrate.</p> <p>Examples:</p> <pre><code>    from prefect_gitlab.repositories import GitLabRepository\n\n    # public GitLab repository\n    public_gitlab_block = GitLabRepository(\n        name=\"my-gitlab-block\",\n        repository=\"https://gitlab.com/testing/my-repository.git\"\n    )\n\n    public_gitlab_block.save()\n\n\n    # specific branch or tag of a GitLab repository\n    branch_gitlab_block = GitLabRepository(\n        name=\"my-gitlab-block\",\n        reference=\"branch-or-tag-name\"\n        repository=\"https://gitlab.com/testing/my-repository.git\"\n    )\n\n    branch_gitlab_block.save()\n\n\n    # private GitLab repository\n    private_gitlab_block = GitLabRepository(\n        name=\"my-private-gitlab-block\",\n        repository=\"https://gitlab.com/testing/my-repository.git\",\n        access_token=\"YOUR_GITLAB_PERSONAL_ACCESS_TOKEN\"\n    )\n\n    private_gitlab_block.save()\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories.GitLabRepository","title":"<code>GitLabRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored in GitLab repositories.</p> <p>An accessible installation of git is required for this block to function properly.</p> Source code in <code>prefect_gitlab/repositories.py</code> <pre><code>class GitLabRepository(ReadableDeploymentStorage):\n    \"\"\"\n    Interact with files stored in GitLab repositories.\n\n    An accessible installation of git is required for this block to function\n    properly.\n    \"\"\"\n\n    _block_type_name = \"GitLab Repository\"\n    _logo_url = HttpUrl(\n        url=\"https://images.ctfassets.net/gm98wzqotmnx/55edIimT4g9gbjhkh5a3Sp/dfdb9391d8f45c2e93e72e3a4d350771/gitlab-logo-500.png?h=250\",  # noqa\n        scheme=\"https\",\n    )\n    _description = \"Interact with files stored in GitLab repositories.\"\n\n    repository: str = Field(\n        default=...,\n        description=(\n            \"The URL of a GitLab repository to read from, in either HTTP/HTTPS or SSH format.\"  # noqa\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    git_depth: Optional[int] = Field(\n        default=1,\n        gte=1,\n        description=\"The number of commits that Git history is truncated to \"\n        \"during cloning. Set to None to fetch the entire history.\",\n    )\n    credentials: Optional[GitLabCredentials] = Field(\n        default=None,\n        description=\"An optional GitLab Credentials block for authenticating with \"\n        \"private GitLab repos.\",\n    )\n\n    @validator(\"credentials\")\n    def _ensure_credentials_go_with_http(cls, v: str, values: dict) -&gt; str:\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted GitLub URLs.\n        Note: validates `access_token` specifically so that it only fires when\n        private repositories are used.\n        \"\"\"\n        if v is not None:\n            if urllib.parse.urlparse(values[\"repository\"]).scheme not in [\n                \"https\",\n                \"http\",\n            ]:\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Credentials can only be used with GitLab repositories \"\n                        \"using the 'HTTPS'/'HTTP' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"URL to the 'HTTPS'/'HTTP' format.\"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n        For private repos: https://&lt;oauth-key&gt;@gitlab.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urllib.parse.urlparse(self.repository)\n        if url_components.scheme in [\"https\", \"http\"] and self.credentials is not None:\n            token = self.credentials.token.get_secret_value()\n            updated_components = url_components._replace(\n                netloc=f\"oauth2:{token}@{url_components.netloc}\"\n            )\n            full_url = urllib.parse.urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: Optional[str]\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitLabRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    @retry(\n        stop=stop_after_attempt(MAX_CLONE_ATTEMPTS),\n        wait=wait_fixed(CLONE_RETRY_MIN_DELAY_SECONDS)\n        + wait_random(\n            CLONE_RETRY_MIN_DELAY_JITTER_SECONDS,\n            CLONE_RETRY_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitLab project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        if self.git_depth is not None:\n            cmd += [\"--depth\", f\"{self.git_depth}\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories.GitLabRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitLab project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory. Args:     from_path: If provided, interpreted as a subdirectory of the underlying         repository that will be copied to the provided local path.     local_path: A local path to clone to; defaults to present working directory.</p> Source code in <code>prefect_gitlab/repositories.py</code> <pre><code>@sync_compatible\n@retry(\n    stop=stop_after_attempt(MAX_CLONE_ATTEMPTS),\n    wait=wait_fixed(CLONE_RETRY_MIN_DELAY_SECONDS)\n    + wait_random(\n        CLONE_RETRY_MIN_DELAY_JITTER_SECONDS,\n        CLONE_RETRY_MAX_DELAY_JITTER_SECONDS,\n    ),\n    reraise=True,\n)\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitLab project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    if self.git_depth is not None:\n        cmd += [\"--depth\", f\"{self.git_depth}\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/","title":"prefect-kubernetes","text":"<p><code>prefect-kubernetes</code> contains Prefect tasks, flows, and blocks enabling orchestration, observation and management of Kubernetes resources.</p> <p>This library is most commonly used to installation with a Kubernetes worker. See the Kubernetes guide to learn how to create and run deployments in Kubernetes. As noted in that guide, Prefect also provides a Helm chart for deploying a worker, a self-hosted server instance, and other resources to a Kubernetes cluster. See the Prefect Helm chart for more information.</p>"},{"location":"integrations/prefect-kubernetes/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-kubernetes/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Kubernetes installed.</li> </ul>"},{"location":"integrations/prefect-kubernetes/#install-prefect-kubernetes","title":"Install <code>prefect-kubernetes</code>","text":"<pre><code> pip install prefect-kubernetes\n ```\n &lt;/div&gt;\n\n### Register newly installed block types\n\nRegister the block types in the prefect-aws module to make them available for use.\n\n&lt;div class=\"terminal\"&gt;\n```bash\nprefect block register -m prefect_kubernetes\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#examples","title":"Examples","text":""},{"location":"integrations/prefect-kubernetes/#use-with_options-to-customize-options-on-an-existing-task-or-flow","title":"Use <code>with_options</code> to customize options on an existing task or flow","text":"<pre><code>from prefect_kubernetes.flows import run_namespaced_job\n\ncustomized_run_namespaced_job = run_namespaced_job.with_options(\n    name=\"My flow running a Kubernetes Job\",\n    retries=2,\n    retry_delay_seconds=10,\n) # this is now a new flow object that can be called\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#specify-and-run-a-kubernetes-job-from-a-yaml-file","title":"Specify and run a Kubernetes Job from a YAML file","text":"<pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.flows import run_namespaced_job # this is a flow\nfrom prefect_kubernetes.jobs import KubernetesJob\n\nk8s_creds = KubernetesCredentials.load(\"k8s-creds\")\n\njob = KubernetesJob.from_yaml_file( # or create in the UI with a dict manifest\n    credentials=k8s_creds,\n    manifest_path=\"path/to/job.yaml\",\n)\n\njob.save(\"my-k8s-job\", overwrite=True)\n\nif __name__ == \"__main__\":\n    # run the flow\n    run_namespaced_job(job)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#generate-a-resource-specific-client-from-kubernetesclusterconfig","title":"Generate a resource-specific client from <code>KubernetesClusterConfig</code>","text":"<pre><code># with minikube / docker desktop &amp; a valid ~/.kube/config this should ~just work~\nfrom prefect.blocks.kubernetes import KubernetesClusterConfig\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\nk8s_config = KubernetesClusterConfig.from_file('~/.kube/config')\n\nk8s_credentials = KubernetesCredentials(cluster_config=k8s_config)\n\nwith k8s_credentials.get_client(\"core\") as v1_core_client:\n    for namespace in v1_core_client.list_namespace().items:\n        print(namespace.metadata.name)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#list-jobs-in-a-namespace","title":"List jobs in a namespace","text":"<pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import list_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_list = list_namespaced_job(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        namespace=\"my-namespace\",\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#patch-an-existing-kubernetes-deployment","title":"Patch an existing Kubernetes deployment","text":"<pre><code>from kubernetes.client.models import V1Deployment\n\nfrom prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import patch_namespaced_deployment\nfrom prefect_kubernetes.utilities import convert_manifest_to_model\n\n@flow\ndef kubernetes_orchestrator():\n\n    v1_deployment_updates = convert_manifest_to_model(\n        manifest=\"path/to/manifest.yaml\",\n        v1_model_name=\"V1Deployment\",\n    )\n\n    v1_deployment = patch_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"my-deployment\",\n        deployment_updates=v1_deployment_updates,\n        namespace=\"my-namespace\"\n    )\n</code></pre> <p>For assistance using Kubernetes, consult the Kubernetes documentation.</p> <p>Refer to the prefect-kubernetes API documentation linked in the sidebar to explore all the capabilities of the prefect-kubernetes library.</p>"},{"location":"integrations/prefect-kubernetes/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials","title":"<code>prefect_kubernetes.credentials</code>","text":"<p>Module for defining Kubernetes credential handling and client generation.</p>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect_kubernetes.credentials import import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>class KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect_kubernetes.credentials import import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig\"  # noqa\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    @classmethod\n    def parse_yaml_config(cls, value):\n        if isinstance(value, str):\n            return yaml.safe_load(value)\n        return value\n\n    @classmethod\n    def from_file(\n        cls: Type[Self], path: Optional[Path] = None, context_name: Optional[str] = None\n    ) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n\n        path = Path(path or config.kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        (\n            existing_contexts,\n            current_context,\n        ) = config.kube_config.list_kube_config_contexts(config_file=str(path))\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n        return cls(config=config_dict, context_name=context_name)\n\n    async def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return await config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    async def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        await config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>  <code>async</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    await config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>@classmethod\ndef from_file(\n    cls: Type[Self], path: Optional[Path] = None, context_name: Optional[str] = None\n) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n\n    path = Path(path or config.kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    (\n        existing_contexts,\n        current_context,\n    ) = config.kube_config.list_kube_config_contexts(config_file=str(path))\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>  <code>async</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return await config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials","title":"<code>KubernetesCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Credentials block for generating configured Kubernetes API clients.</p> <p>Attributes:</p> Name Type Description <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>A <code>KubernetesClusterConfig</code> block holding a JSON kube config for a specific kubernetes context.</p> Example <p>Load stored Kubernetes credentials: <pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\n\nkubernetes_credentials = KubernetesCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>class KubernetesCredentials(Block):\n    \"\"\"Credentials block for generating configured Kubernetes API clients.\n\n    Attributes:\n        cluster_config: A `KubernetesClusterConfig` block holding a JSON kube\n            config for a specific kubernetes context.\n\n    Example:\n        Load stored Kubernetes credentials:\n        ```python\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        kubernetes_credentials = KubernetesCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials\"  # noqa\n\n    cluster_config: Optional[KubernetesClusterConfig] = None\n\n    @asynccontextmanager\n    async def get_client(\n        self,\n        client_type: Literal[\"apps\", \"batch\", \"core\", \"custom_objects\"],\n        configuration: Optional[Configuration] = None,\n    ) -&gt; AsyncGenerator[KubernetesClient, None]:\n        \"\"\"Convenience method for retrieving a Kubernetes API client for deployment resources.\n\n        Args:\n            client_type: The resource-specific type of Kubernetes client to retrieve.\n\n        Yields:\n            An authenticated, resource-specific Kubernetes API client.\n\n        Example:\n            ```python\n            from prefect_kubernetes.credentials import KubernetesCredentials\n\n            async with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n                pods = await core_v1_client.list_namespaced_pod()\n                for pod in pods.items:\n                    print(pod.metadata.name)\n            ```\n        \"\"\"\n        client_configuration = configuration or Configuration()\n        if self.cluster_config:\n            config_dict = self.cluster_config.config\n            context = self.cluster_config.context_name\n\n            # Use Configuration to load configuration from a dictionary\n\n            await config.load_kube_config_from_dict(\n                config_dict=config_dict,\n                context=context,\n                client_configuration=client_configuration,\n            )\n        async with ApiClient(configuration=client_configuration) as api_client:\n            try:\n                yield await self.get_resource_specific_client(\n                    client_type, api_client=api_client\n                )\n            finally:\n                await api_client.close()\n\n    async def get_resource_specific_client(\n        self,\n        client_type: str,\n        api_client: ApiClient,\n    ) -&gt; Union[AppsV1Api, BatchV1Api, CoreV1Api]:\n        \"\"\"\n        Utility function for configuring a generic Kubernetes client.\n        It will attempt to connect to a Kubernetes cluster in three steps with\n        the first successful connection attempt becoming the mode of communication with\n        a cluster:\n\n        1. It will first attempt to use a `KubernetesCredentials` block's\n        `cluster_config` to configure a client using\n        `KubernetesClusterConfig.configure_client`.\n\n        2. Attempt in-cluster connection (will only work when running on a pod).\n\n        3. Attempt out-of-cluster connection using the default location for a\n        kube config file.\n\n        Args:\n            client_type: The Kubernetes API client type for interacting with specific\n                Kubernetes resources.\n\n        Returns:\n            KubernetesClient: An authenticated, resource-specific Kubernetes Client.\n\n        Raises:\n            ValueError: If `client_type` is not a valid Kubernetes API client type.\n        \"\"\"\n\n        if self.cluster_config:\n            await self.cluster_config.configure_client()\n        else:\n            try:\n                config.load_incluster_config()\n            except ConfigException:\n                await config.load_kube_config()\n\n        try:\n            return K8S_CLIENT_TYPES[client_type](api_client)\n        except KeyError:\n            raise ValueError(\n                f\"Invalid client type provided '{client_type}'.\"\n                f\" Must be one of {listrepr(K8S_CLIENT_TYPES.keys())}.\"\n            )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials.get_client","title":"<code>get_client</code>  <code>async</code>","text":"<p>Convenience method for retrieving a Kubernetes API client for deployment resources.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['apps', 'batch', 'core', 'custom_objects']</code> <p>The resource-specific type of Kubernetes client to retrieve.</p> required <p>Yields:</p> Type Description <code>AsyncGenerator[KubernetesClient, None]</code> <p>An authenticated, resource-specific Kubernetes API client.</p> Example <pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\n\nasync with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n    pods = await core_v1_client.list_namespaced_pod()\n    for pod in pods.items:\n        print(pod.metadata.name)\n</code></pre> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>@asynccontextmanager\nasync def get_client(\n    self,\n    client_type: Literal[\"apps\", \"batch\", \"core\", \"custom_objects\"],\n    configuration: Optional[Configuration] = None,\n) -&gt; AsyncGenerator[KubernetesClient, None]:\n    \"\"\"Convenience method for retrieving a Kubernetes API client for deployment resources.\n\n    Args:\n        client_type: The resource-specific type of Kubernetes client to retrieve.\n\n    Yields:\n        An authenticated, resource-specific Kubernetes API client.\n\n    Example:\n        ```python\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        async with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n            pods = await core_v1_client.list_namespaced_pod()\n            for pod in pods.items:\n                print(pod.metadata.name)\n        ```\n    \"\"\"\n    client_configuration = configuration or Configuration()\n    if self.cluster_config:\n        config_dict = self.cluster_config.config\n        context = self.cluster_config.context_name\n\n        # Use Configuration to load configuration from a dictionary\n\n        await config.load_kube_config_from_dict(\n            config_dict=config_dict,\n            context=context,\n            client_configuration=client_configuration,\n        )\n    async with ApiClient(configuration=client_configuration) as api_client:\n        try:\n            yield await self.get_resource_specific_client(\n                client_type, api_client=api_client\n            )\n        finally:\n            await api_client.close()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials.get_resource_specific_client","title":"<code>get_resource_specific_client</code>  <code>async</code>","text":"<p>Utility function for configuring a generic Kubernetes client. It will attempt to connect to a Kubernetes cluster in three steps with the first successful connection attempt becoming the mode of communication with a cluster:</p> <ol> <li> <p>It will first attempt to use a <code>KubernetesCredentials</code> block's <code>cluster_config</code> to configure a client using <code>KubernetesClusterConfig.configure_client</code>.</p> </li> <li> <p>Attempt in-cluster connection (will only work when running on a pod).</p> </li> <li> <p>Attempt out-of-cluster connection using the default location for a kube config file.</p> </li> </ol> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>str</code> <p>The Kubernetes API client type for interacting with specific Kubernetes resources.</p> required <p>Returns:</p> Name Type Description <code>KubernetesClient</code> <code>Union[AppsV1Api, BatchV1Api, CoreV1Api]</code> <p>An authenticated, resource-specific Kubernetes Client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If <code>client_type</code> is not a valid Kubernetes API client type.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def get_resource_specific_client(\n    self,\n    client_type: str,\n    api_client: ApiClient,\n) -&gt; Union[AppsV1Api, BatchV1Api, CoreV1Api]:\n    \"\"\"\n    Utility function for configuring a generic Kubernetes client.\n    It will attempt to connect to a Kubernetes cluster in three steps with\n    the first successful connection attempt becoming the mode of communication with\n    a cluster:\n\n    1. It will first attempt to use a `KubernetesCredentials` block's\n    `cluster_config` to configure a client using\n    `KubernetesClusterConfig.configure_client`.\n\n    2. Attempt in-cluster connection (will only work when running on a pod).\n\n    3. Attempt out-of-cluster connection using the default location for a\n    kube config file.\n\n    Args:\n        client_type: The Kubernetes API client type for interacting with specific\n            Kubernetes resources.\n\n    Returns:\n        KubernetesClient: An authenticated, resource-specific Kubernetes Client.\n\n    Raises:\n        ValueError: If `client_type` is not a valid Kubernetes API client type.\n    \"\"\"\n\n    if self.cluster_config:\n        await self.cluster_config.configure_client()\n    else:\n        try:\n            config.load_incluster_config()\n        except ConfigException:\n            await config.load_kube_config()\n\n    try:\n        return K8S_CLIENT_TYPES[client_type](api_client)\n    except KeyError:\n        raise ValueError(\n            f\"Invalid client type provided '{client_type}'.\"\n            f\" Must be one of {listrepr(K8S_CLIENT_TYPES.keys())}.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/","title":"Custom Objects","text":""},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects","title":"<code>prefect_kubernetes.custom_objects</code>","text":""},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.create_namespaced_custom_object","title":"<code>create_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for creating a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create the custom object in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource created by this task.</p> Example <p>Create a custom object in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import create_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = create_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'crd-name',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def create_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    body: Dict[str, Any],\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for creating a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        body: A Dict containing the custom resource object's specification.\n        namespace: The Kubernetes namespace to create the custom object in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing the custom resource created by this task.\n\n    Example:\n        Create a custom object in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import create_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = create_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'crd-name',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.create_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.delete_namespaced_custom_object","title":"<code>delete_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for deleting a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to delete.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this custom object in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource deleted by this task.</p> Example <p>Delete \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import delete_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = delete_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def delete_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for deleting a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to delete.\n        namespace: The Kubernetes namespace to create this custom object in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n\n    Returns:\n        object containing the custom resource deleted by this task.\n\n    Example:\n        Delete \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import delete_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = delete_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.delete_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.get_namespaced_custom_object","title":"<code>get_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for reading a namespaced Kubernetes custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace the custom resource is in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification.</p> Example <p>Read \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import get_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = get_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def get_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for reading a namespaced Kubernetes custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to read.\n        namespace: The Kubernetes namespace the custom resource is in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `name` is `None`.\n\n    Returns:\n        object containing the custom resource specification.\n\n    Example:\n        Read \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import get_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = get_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.get_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.get_namespaced_custom_object_status","title":"<code>get_namespaced_custom_object_status</code>  <code>async</code>","text":"<p>Task for fetching status of a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to read.</p> required <code>namespace</code> <code>str</code> <p>The Kubernetes namespace the custom resource is in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom-object specification with status.</p> Example <p>Fetch status of \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import (\n    get_namespaced_custom_object_status,\n)\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = get_namespaced_custom_object_status(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def get_namespaced_custom_object_status(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for fetching status of a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to read.\n        namespace: The Kubernetes namespace the custom resource is in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing the custom-object specification with status.\n\n    Example:\n        Fetch status of \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import (\n            get_namespaced_custom_object_status,\n        )\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = get_namespaced_custom_object_status(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.get_namespaced_custom_object_status(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.list_namespaced_custom_object","title":"<code>list_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for listing namespaced custom objects.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>namespace</code> <code>str</code> <p>The Kubernetes namespace to list custom resources for.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing a list of custom resources.</p> Example <p>List custom resources in \"my-namespace\": <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import list_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    namespaced_custom_objects_list = list_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        namespace=\"my-namespace\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def list_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for listing namespaced custom objects.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        namespace: The Kubernetes namespace to list custom resources for.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing a list of custom resources.\n\n    Example:\n        List custom resources in \"my-namespace\":\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import list_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            namespaced_custom_objects_list = list_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.list_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.patch_namespaced_custom_object","title":"<code>patch_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for patching a namespaced custom resource.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to patch.</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's patch.</p> required <code>namespace</code> <code>str</code> <p>The custom resource's Kubernetes namespace.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>body</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification</p> <code>object</code> <p>after the patch gets applied.</p> Example <p>Patch \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import (\n    patch_namespaced_custom_object,\n)\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = patch_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'my-custom-object',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def patch_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    body: Dict[str, Any],\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for patching a namespaced custom resource.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to patch.\n        body: A Dict containing the custom resource object's patch.\n        namespace: The custom resource's Kubernetes namespace.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `body` is `None`.\n\n    Returns:\n        object containing the custom resource specification\n        after the patch gets applied.\n\n    Example:\n        Patch \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import (\n            patch_namespaced_custom_object,\n        )\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = patch_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'my-custom-object',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.patch_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.replace_namespaced_custom_object","title":"<code>replace_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for replacing a namespaced custom resource.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to replace.</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's specification.</p> required <code>namespace</code> <code>str</code> <p>The custom resource's Kubernetes namespace.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>body</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification after the replacement.</p> Example <p>Replace \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import replace_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = replace_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'my-custom-object',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def replace_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    body: Dict[str, Any],\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for replacing a namespaced custom resource.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to replace.\n        body: A Dict containing the custom resource object's specification.\n        namespace: The custom resource's Kubernetes namespace.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `body` is `None`.\n\n    Returns:\n        object containing the custom resource specification after the replacement.\n\n    Example:\n        Replace \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import replace_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = replace_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'my-custom-object',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.replace_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/","title":"Deployments","text":""},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments","title":"<code>prefect_kubernetes.deployments</code>","text":"<p>Module for interacting with Kubernetes deployments from Prefect flows.</p>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.create_namespaced_deployment","title":"<code>create_namespaced_deployment</code>  <code>async</code>","text":"<p>Create a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>new_deployment</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Create a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import create_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = create_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_deployment=V1Deployment(metadata={\"name\": \"test-deployment\"}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def create_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    new_deployment: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Create a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        new_deployment: A Kubernetes `V1Deployment` specification.\n        namespace: The Kubernetes namespace to create this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Create a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import create_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = create_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_deployment=V1Deployment(metadata={\"name\": \"test-deployment\"}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.create_namespaced_deployment(\n            namespace=namespace,\n            body=new_deployment,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.delete_namespaced_deployment","title":"<code>delete_namespaced_deployment</code>  <code>async</code>","text":"<p>Delete a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this deployment from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Delete a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import delete_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1DeleteOptions\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = delete_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        delete_options=V1DeleteOptions(grace_period_seconds=0),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def delete_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Delete a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this deployment from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Delete a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import delete_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = delete_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                delete_options=V1DeleteOptions(grace_period_seconds=0),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.delete_namespaced_deployment(\n            deployment_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.list_namespaced_deployment","title":"<code>list_namespaced_deployment</code>  <code>async</code>","text":"<p>List all deployments in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list deployments from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1DeploymentList</code> <p>A Kubernetes <code>V1DeploymentList</code> object.</p> Example <p>List all deployments in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import list_namespaced_deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_list = list_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def list_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1DeploymentList:\n    \"\"\"List all deployments in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The Kubernetes namespace to list deployments from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1DeploymentList` object.\n\n    Example:\n        List all deployments in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import list_namespaced_deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_list = list_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.list_namespaced_deployment(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.patch_namespaced_deployment","title":"<code>patch_namespaced_deployment</code>  <code>async</code>","text":"<p>Patch a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to patch.</p> required <code>deployment_updates</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Patch a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import patch_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = patch_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        deployment_updates=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def patch_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    deployment_updates: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Patch a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to patch.\n        deployment_updates: A Kubernetes `V1Deployment` object.\n        namespace: The Kubernetes namespace to patch this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Patch a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import patch_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = patch_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                deployment_updates=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.patch_namespaced_deployment(\n            name=deployment_name,\n            namespace=namespace,\n            body=deployment_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.read_namespaced_deployment","title":"<code>read_namespaced_deployment</code>  <code>async</code>","text":"<p>Read information on a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this deployment from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Read a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = read_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\"\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def read_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Read information on a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to read.\n        namespace: The Kubernetes namespace to read this deployment from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Read a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = read_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\"\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.read_namespaced_deployment(\n            name=deployment_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.replace_namespaced_deployment","title":"<code>replace_namespaced_deployment</code>  <code>async</code>","text":"<p>Replace a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to replace.</p> required <code>new_deployment</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Replace a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import replace_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = replace_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        new_deployment=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}})\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def replace_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    new_deployment: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Replace a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to replace.\n        new_deployment: A Kubernetes `V1Deployment` object.\n        namespace: The Kubernetes namespace to replace this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Replace a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import replace_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = replace_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                new_deployment=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}})\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.replace_namespaced_deployment(\n            body=new_deployment,\n            name=deployment_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/","title":"Exceptions","text":""},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions","title":"<code>prefect_kubernetes.exceptions</code>","text":"<p>Module to define common exceptions within <code>prefect_kubernetes</code>.</p>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobDefinitionError","title":"<code>KubernetesJobDefinitionError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job definition is invalid.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobDefinitionError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job definition is invalid.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobFailedError","title":"<code>KubernetesJobFailedError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job fails.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobFailedError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job fails.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobTimeoutError","title":"<code>KubernetesJobTimeoutError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job times out.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobTimeoutError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job times out.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesResourceNotFoundError","title":"<code>KubernetesResourceNotFoundError</code>","text":"<p>               Bases: <code>ApiException</code></p> <p>An exception for when a Kubernetes resource cannot be found by a client.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesResourceNotFoundError(ApiException):\n    \"\"\"An exception for when a Kubernetes resource cannot be found by a client.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/flows/","title":"Flows","text":""},{"location":"integrations/prefect-kubernetes/flows/#prefect_kubernetes.flows","title":"<code>prefect_kubernetes.flows</code>","text":"<p>A module to define flows interacting with Kubernetes resources.</p>"},{"location":"integrations/prefect-kubernetes/flows/#prefect_kubernetes.flows.run_namespaced_job","title":"<code>run_namespaced_job</code>  <code>async</code>","text":"<p>Flow for running a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_job</code> <code>KubernetesJob</code> <p>The <code>KubernetesJob</code> block that specifies the job to run.</p> required <code>print_func</code> <code>Optional[Callable]</code> <p>A function to print the logs from the job pods.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of logs from each pod in the job, e.g. {'pod_name': 'pod_log_str'}.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the created Kubernetes job attains a failed status.</p> <pre><code>```python\nfrom prefect_kubernetes import KubernetesJob, run_namespaced_job\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\nrun_namespaced_job(\n    kubernetes_job=KubernetesJob.from_yaml_file(\n        credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        manifest_path=\"path/to/job.yaml\",\n    )\n)\n```\n</code></pre> Source code in <code>prefect_kubernetes/flows.py</code> <pre><code>@flow\nasync def run_namespaced_job(\n    kubernetes_job: KubernetesJob, print_func: Optional[Callable] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"Flow for running a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_job: The `KubernetesJob` block that specifies the job to run.\n        print_func: A function to print the logs from the job pods.\n\n    Returns:\n        A dict of logs from each pod in the job, e.g. {'pod_name': 'pod_log_str'}.\n\n    Raises:\n        RuntimeError: If the created Kubernetes job attains a failed status.\n\n    Example:\n\n        ```python\n        from prefect_kubernetes import KubernetesJob, run_namespaced_job\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        run_namespaced_job(\n            kubernetes_job=KubernetesJob.from_yaml_file(\n                credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                manifest_path=\"path/to/job.yaml\",\n            )\n        )\n        ```\n    \"\"\"\n    kubernetes_job_run = task(kubernetes_job.trigger)()\n\n    await task(kubernetes_job_run.wait_for_completion.aio)(\n        kubernetes_job_run, print_func\n    )\n\n    return task(kubernetes_job_run.fetch_result)()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs","title":"<code>prefect_kubernetes.jobs</code>","text":"<p>Module to define tasks for interacting with Kubernetes jobs.</p>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob","title":"<code>KubernetesJob</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>A block representing a Kubernetes job configuration.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>class KubernetesJob(JobBlock):\n    \"\"\"A block representing a Kubernetes job configuration.\"\"\"\n\n    v1_job: Dict[str, Any] = Field(\n        default=...,\n        title=\"Job Manifest\",\n        description=(\n            \"The Kubernetes job manifest to run. This dictionary can be produced \"\n            \"using `yaml.safe_load`.\"\n        ),\n    )\n    api_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional API Arguments\",\n        description=\"Additional arguments to include in Kubernetes API calls.\",\n        examples=[{\"pretty\": \"true\"}],\n    )\n    credentials: KubernetesCredentials = Field(\n        default=..., description=\"The credentials to configure a client from.\"\n    )\n    delete_after_completion: bool = Field(\n        default=True,\n        description=\"Whether to delete the job after it has completed.\",\n    )\n    interval_seconds: int = Field(\n        default=5,\n        description=\"The number of seconds to wait between job status checks.\",\n    )\n    namespace: str = Field(\n        default=\"default\",\n        description=\"The namespace to create and run the job in.\",\n    )\n    timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=\"The number of seconds to wait for the job run before timing out.\",\n    )\n\n    _block_type_name = \"Kubernetes Job\"\n    _block_type_slug = \"k8s-job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob\"  # noqa\n\n    @sync_compatible\n    async def trigger(self):\n        \"\"\"Create a Kubernetes job and return a `KubernetesJobRun` object.\"\"\"\n\n        await create_namespaced_job.fn(\n            kubernetes_credentials=self.credentials,\n            new_job=self.v1_job,\n            namespace=self.namespace,\n            **self.api_kwargs,\n        )\n\n        return KubernetesJobRun(kubernetes_job=self, v1_job_model=self.v1_job)\n\n    @classmethod\n    def from_yaml_file(\n        cls: Type[Self], manifest_path: Union[Path, str], **kwargs\n    ) -&gt; Self:\n        \"\"\"Create a `KubernetesJob` from a YAML file.\n\n        Args:\n            manifest_path: The YAML file to create the `KubernetesJob` from.\n\n        Returns:\n            A KubernetesJob object.\n        \"\"\"\n        with open(manifest_path, \"r\") as yaml_stream:\n            yaml_dict = yaml.safe_load(yaml_stream)\n\n        return cls(v1_job=yaml_dict, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob.from_yaml_file","title":"<code>from_yaml_file</code>  <code>classmethod</code>","text":"<p>Create a <code>KubernetesJob</code> from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>manifest_path</code> <code>Union[Path, str]</code> <p>The YAML file to create the <code>KubernetesJob</code> from.</p> required <p>Returns:</p> Type Description <code>Self</code> <p>A KubernetesJob object.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@classmethod\ndef from_yaml_file(\n    cls: Type[Self], manifest_path: Union[Path, str], **kwargs\n) -&gt; Self:\n    \"\"\"Create a `KubernetesJob` from a YAML file.\n\n    Args:\n        manifest_path: The YAML file to create the `KubernetesJob` from.\n\n    Returns:\n        A KubernetesJob object.\n    \"\"\"\n    with open(manifest_path, \"r\") as yaml_stream:\n        yaml_dict = yaml.safe_load(yaml_stream)\n\n    return cls(v1_job=yaml_dict, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Create a Kubernetes job and return a <code>KubernetesJobRun</code> object.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def trigger(self):\n    \"\"\"Create a Kubernetes job and return a `KubernetesJobRun` object.\"\"\"\n\n    await create_namespaced_job.fn(\n        kubernetes_credentials=self.credentials,\n        new_job=self.v1_job,\n        namespace=self.namespace,\n        **self.api_kwargs,\n    )\n\n    return KubernetesJobRun(kubernetes_job=self, v1_job_model=self.v1_job)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun","title":"<code>KubernetesJobRun</code>","text":"<p>               Bases: <code>JobRun[Dict[str, Any]]</code></p> <p>A container representing a run of a Kubernetes job.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@deprecated_class(\n    start_date=\"Jun 2024\", help=\"Will be removed in Prefect 3. Use Workers instead.\"\n)\nclass KubernetesJobRun(JobRun[Dict[str, Any]]):\n    \"\"\"A container representing a run of a Kubernetes job.\"\"\"\n\n    def __init__(\n        self,\n        kubernetes_job: \"KubernetesJob\",\n        v1_job_model: Union[V1Job, Dict[str, Any]],\n    ):\n        self.pod_logs = None\n\n        self._completed = False\n        self._kubernetes_job = kubernetes_job\n        self._v1_job_model = v1_job_model\n\n    async def _cleanup(self):\n        \"\"\"Deletes the Kubernetes job resource.\"\"\"\n        job_name = self._v1_job_model.get(\"metadata\", {}).get(\"name\")\n\n        delete_options = V1DeleteOptions(propagation_policy=\"Foreground\")\n\n        deleted_v1_job = await delete_namespaced_job.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            job_name=job_name,\n            delete_options=delete_options,\n            namespace=self._kubernetes_job.namespace,\n            **self._kubernetes_job.api_kwargs,\n        )\n        self.logger.info(f\"Job {job_name} deleted \" f\"with {deleted_v1_job.status!r}.\")\n\n    @sync_compatible\n    async def wait_for_completion(self, print_func: Optional[Callable] = None):\n        \"\"\"Waits for the job to complete.\n\n        If the job has `delete_after_completion` set to `True`,\n        the job will be deleted if it is observed by this method\n        to enter a completed state.\n\n        Raises:\n            RuntimeError: If the Kubernetes job fails.\n            KubernetesJobTimeoutError: If the Kubernetes job times out.\n            ValueError: If `wait_for_completion` is never called.\n        \"\"\"\n        self.pod_logs = {}\n\n        elapsed_time = 0\n\n        while not self._completed:\n            job_expired = (\n                elapsed_time &gt; self._kubernetes_job.timeout_seconds\n                if self._kubernetes_job.timeout_seconds\n                else False\n            )\n            if job_expired:\n                raise KubernetesJobTimeoutError(\n                    f\"Job timed out after {elapsed_time} seconds.\"\n                )\n\n            v1_job_status = await read_namespaced_job_status.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                job_name=self._v1_job_model.get(\"metadata\", {}).get(\"name\"),\n                namespace=self._kubernetes_job.namespace,\n                **self._kubernetes_job.api_kwargs,\n            )\n            pod_selector = (\n                \"controller-uid=\" f\"{v1_job_status.metadata.labels['controller-uid']}\"\n            )\n            v1_pod_list = await list_namespaced_pod.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                namespace=self._kubernetes_job.namespace,\n                label_selector=pod_selector,\n                **self._kubernetes_job.api_kwargs,\n            )\n\n            for pod in v1_pod_list.items:\n                pod_name = pod.metadata.name\n\n                if pod.status.phase == \"Pending\" or pod_name in self.pod_logs.keys():\n                    continue\n\n                self.logger.info(f\"Capturing logs for pod {pod_name!r}.\")\n\n                self.pod_logs[pod_name] = await read_namespaced_pod_log.fn(\n                    kubernetes_credentials=self._kubernetes_job.credentials,\n                    pod_name=pod_name,\n                    container=v1_job_status.spec.template.spec.containers[0].name,\n                    namespace=self._kubernetes_job.namespace,\n                    print_func=print_func,\n                    **self._kubernetes_job.api_kwargs,\n                )\n\n            if v1_job_status.status.active:\n                await sleep(self._kubernetes_job.interval_seconds)\n                if self._kubernetes_job.timeout_seconds:\n                    elapsed_time += self._kubernetes_job.interval_seconds\n            elif v1_job_status.status.conditions:\n                final_completed_conditions = [\n                    condition.type == \"Complete\"\n                    for condition in v1_job_status.status.conditions\n                    if condition.status == \"True\"\n                ]\n                if final_completed_conditions and any(final_completed_conditions):\n                    self._completed = True\n                    self.logger.info(\n                        f\"Job {v1_job_status.metadata.name!r} has \"\n                        f\"completed with {v1_job_status.status.succeeded} pods.\"\n                    )\n                elif final_completed_conditions:\n                    failed_conditions = [\n                        condition.reason\n                        for condition in v1_job_status.status.conditions\n                        if condition.type == \"Failed\"\n                    ]\n                    raise RuntimeError(\n                        f\"Job {v1_job_status.metadata.name!r} failed due to \"\n                        f\"{failed_conditions}, check the Kubernetes pod logs \"\n                        f\"for more information.\"\n                    )\n\n        if self._kubernetes_job.delete_after_completion:\n            await self._cleanup()\n\n    @sync_compatible\n    async def fetch_result(self) -&gt; Dict[str, Any]:\n        \"\"\"Fetch the results of the job.\n\n        Returns:\n            The logs from each of the pods in the job.\n\n        Raises:\n            ValueError: If this method is called when the job has\n                a non-terminal state.\n        \"\"\"\n\n        if not self._completed:\n            raise ValueError(\n                \"The Kubernetes Job run is not in a completed state - \"\n                \"be sure to call `wait_for_completion` before attempting \"\n                \"to fetch the result.\"\n            )\n        return self.pod_logs\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Fetch the results of the job.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The logs from each of the pods in the job.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If this method is called when the job has a non-terminal state.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self) -&gt; Dict[str, Any]:\n    \"\"\"Fetch the results of the job.\n\n    Returns:\n        The logs from each of the pods in the job.\n\n    Raises:\n        ValueError: If this method is called when the job has\n            a non-terminal state.\n    \"\"\"\n\n    if not self._completed:\n        raise ValueError(\n            \"The Kubernetes Job run is not in a completed state - \"\n            \"be sure to call `wait_for_completion` before attempting \"\n            \"to fetch the result.\"\n        )\n    return self.pod_logs\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Waits for the job to complete.</p> <p>If the job has <code>delete_after_completion</code> set to <code>True</code>, the job will be deleted if it is observed by this method to enter a completed state.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the Kubernetes job fails.</p> <code>KubernetesJobTimeoutError</code> <p>If the Kubernetes job times out.</p> <code>ValueError</code> <p>If <code>wait_for_completion</code> is never called.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self, print_func: Optional[Callable] = None):\n    \"\"\"Waits for the job to complete.\n\n    If the job has `delete_after_completion` set to `True`,\n    the job will be deleted if it is observed by this method\n    to enter a completed state.\n\n    Raises:\n        RuntimeError: If the Kubernetes job fails.\n        KubernetesJobTimeoutError: If the Kubernetes job times out.\n        ValueError: If `wait_for_completion` is never called.\n    \"\"\"\n    self.pod_logs = {}\n\n    elapsed_time = 0\n\n    while not self._completed:\n        job_expired = (\n            elapsed_time &gt; self._kubernetes_job.timeout_seconds\n            if self._kubernetes_job.timeout_seconds\n            else False\n        )\n        if job_expired:\n            raise KubernetesJobTimeoutError(\n                f\"Job timed out after {elapsed_time} seconds.\"\n            )\n\n        v1_job_status = await read_namespaced_job_status.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            job_name=self._v1_job_model.get(\"metadata\", {}).get(\"name\"),\n            namespace=self._kubernetes_job.namespace,\n            **self._kubernetes_job.api_kwargs,\n        )\n        pod_selector = (\n            \"controller-uid=\" f\"{v1_job_status.metadata.labels['controller-uid']}\"\n        )\n        v1_pod_list = await list_namespaced_pod.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            namespace=self._kubernetes_job.namespace,\n            label_selector=pod_selector,\n            **self._kubernetes_job.api_kwargs,\n        )\n\n        for pod in v1_pod_list.items:\n            pod_name = pod.metadata.name\n\n            if pod.status.phase == \"Pending\" or pod_name in self.pod_logs.keys():\n                continue\n\n            self.logger.info(f\"Capturing logs for pod {pod_name!r}.\")\n\n            self.pod_logs[pod_name] = await read_namespaced_pod_log.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                pod_name=pod_name,\n                container=v1_job_status.spec.template.spec.containers[0].name,\n                namespace=self._kubernetes_job.namespace,\n                print_func=print_func,\n                **self._kubernetes_job.api_kwargs,\n            )\n\n        if v1_job_status.status.active:\n            await sleep(self._kubernetes_job.interval_seconds)\n            if self._kubernetes_job.timeout_seconds:\n                elapsed_time += self._kubernetes_job.interval_seconds\n        elif v1_job_status.status.conditions:\n            final_completed_conditions = [\n                condition.type == \"Complete\"\n                for condition in v1_job_status.status.conditions\n                if condition.status == \"True\"\n            ]\n            if final_completed_conditions and any(final_completed_conditions):\n                self._completed = True\n                self.logger.info(\n                    f\"Job {v1_job_status.metadata.name!r} has \"\n                    f\"completed with {v1_job_status.status.succeeded} pods.\"\n                )\n            elif final_completed_conditions:\n                failed_conditions = [\n                    condition.reason\n                    for condition in v1_job_status.status.conditions\n                    if condition.type == \"Failed\"\n                ]\n                raise RuntimeError(\n                    f\"Job {v1_job_status.metadata.name!r} failed due to \"\n                    f\"{failed_conditions}, check the Kubernetes pod logs \"\n                    f\"for more information.\"\n                )\n\n    if self._kubernetes_job.delete_after_completion:\n        await self._cleanup()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.create_namespaced_job","title":"<code>create_namespaced_job</code>  <code>async</code>","text":"<p>Task for creating a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>new_job</code> <code>Union[V1Job, Dict[str, Any]]</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Create a job in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import create_namespaced_job\nfrom kubernetes_asyncio.client.models import V1Job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = create_namespaced_job(\n        new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def create_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    new_job: Union[V1Job, Dict[str, Any]],\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for creating a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        new_job: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to create this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Create a job in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import create_namespaced_job\n        from kubernetes_asyncio.client.models import V1Job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = create_namespaced_job(\n                new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.create_namespaced_job(\n            namespace=namespace,\n            body=new_job,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.delete_namespaced_job","title":"<code>delete_namespaced_job</code>  <code>async</code>","text":"<p>Task for deleting a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Status</code> <p>A Kubernetes <code>V1Status</code> object.</p> Example <p>Delete \"my-job\" in the default namespace: <pre><code>from kubernetes_asyncio.client.models import V1DeleteOptions\nfrom prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import delete_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_status = delete_namespaced_job(\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        delete_options=V1DeleteOptions(propagation_policy=\"Foreground\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def delete_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Status:\n    \"\"\"Task for deleting a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n\n    Returns:\n        A Kubernetes `V1Status` object.\n\n    Example:\n        Delete \"my-job\" in the default namespace:\n        ```python\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import delete_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_status = delete_namespaced_job(\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                delete_options=V1DeleteOptions(propagation_policy=\"Foreground\"),\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.delete_namespaced_job(\n            name=job_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.list_namespaced_job","title":"<code>list_namespaced_job</code>  <code>async</code>","text":"<p>Task for listing namespaced Kubernetes jobs.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list jobs from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1JobList</code> <p>A Kubernetes <code>V1JobList</code> object.</p> Example <p>List jobs in \"my-namespace\": <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import list_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    namespaced_job_list = list_namespaced_job(\n        namespace=\"my-namespace\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def list_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1JobList:\n    \"\"\"Task for listing namespaced Kubernetes jobs.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        namespace: The Kubernetes namespace to list jobs from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1JobList` object.\n\n    Example:\n        List jobs in \"my-namespace\":\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import list_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            namespaced_job_list = list_namespaced_job(\n                namespace=\"my-namespace\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.list_namespaced_job(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.patch_namespaced_job","title":"<code>patch_namespaced_job</code>  <code>async</code>","text":"<p>Task for patching a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to patch.</p> required <code>job_updates</code> <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>job_name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Patch \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import patch_namespaced_job\n\nfrom kubernetes_asyncio.client.models import V1Job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = patch_namespaced_job(\n        job_name=\"my-job\",\n        job_updates=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}}),\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def patch_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    job_updates: V1Job,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for patching a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to patch.\n        job_updates: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to patch this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `job_name` is `None`.\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Patch \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import patch_namespaced_job\n\n        from kubernetes_asyncio.client.models import V1Job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = patch_namespaced_job(\n                job_name=\"my-job\",\n                job_updates=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}}),\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.patch_namespaced_job(\n            name=job_name,\n            namespace=namespace,\n            body=job_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.read_namespaced_job","title":"<code>read_namespaced_job</code>  <code>async</code>","text":"<p>Task for reading a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>job_name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Read \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import read_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = read_namespaced_job(\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def read_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for reading a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to read.\n        namespace: The Kubernetes namespace to read this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `job_name` is `None`.\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Read \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import read_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = read_namespaced_job(\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.read_namespaced_job(\n            name=job_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.read_namespaced_job_status","title":"<code>read_namespaced_job_status</code>  <code>async</code>","text":"<p>Task for fetching status of a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to fetch status for.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to fetch status of job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1JobStatus</code> object.</p> Example <p>Fetch status of a job in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import read_namespaced_job_status\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_status = read_namespaced_job_status(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        job_name=\"my-job\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def read_namespaced_job_status(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for fetching status of a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to fetch status for.\n        namespace: The Kubernetes namespace to fetch status of job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1JobStatus` object.\n\n    Example:\n        Fetch status of a job in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import read_namespaced_job_status\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_status = read_namespaced_job_status(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                job_name=\"my-job\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.read_namespaced_job_status(\n            name=job_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.replace_namespaced_job","title":"<code>replace_namespaced_job</code>  <code>async</code>","text":"<p>Task for replacing a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to replace.</p> required <code>new_job</code> <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Replace \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import replace_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = replace_namespaced_job(\n        new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def replace_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    new_job: V1Job,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for replacing a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to replace.\n        new_job: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to replace this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Replace \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import replace_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = replace_namespaced_job(\n                new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.replace_namespaced_job(\n            name=job_name,\n            body=new_job,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/","title":"Pods","text":""},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods","title":"<code>prefect_kubernetes.pods</code>","text":"<p>Module for interacting with Kubernetes pods from Prefect flows.</p>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.create_namespaced_pod","title":"<code>create_namespaced_pod</code>  <code>async</code>","text":"<p>Create a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>new_pod</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Create a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import create_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = create_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_pod=V1Pod(metadata={\"name\": \"test-pod\"}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def create_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    new_pod: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Create a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        new_pod: A Kubernetes `V1Pod` specification.\n        namespace: The Kubernetes namespace to create this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Create a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import create_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = create_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_pod=V1Pod(metadata={\"name\": \"test-pod\"}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.create_namespaced_pod(\n            namespace=namespace,\n            body=new_pod,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.delete_namespaced_pod","title":"<code>delete_namespaced_pod</code>  <code>async</code>","text":"<p>Delete a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this pod from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Delete a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import delete_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1DeleteOptions\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = delete_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        delete_options=V1DeleteOptions(grace_period_seconds=0),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def delete_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Delete a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this pod from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Delete a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import delete_namespaced_pod\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = delete_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                delete_options=V1DeleteOptions(grace_period_seconds=0),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.delete_namespaced_pod(\n            pod_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.list_namespaced_pod","title":"<code>list_namespaced_pod</code>  <code>async</code>","text":"<p>List all pods in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list pods from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1PodList</code> <p>A Kubernetes <code>V1PodList</code> object.</p> Example <p>List all pods in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import list_namespaced_pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_list = list_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def list_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1PodList:\n    \"\"\"List all pods in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The Kubernetes namespace to list pods from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1PodList` object.\n\n    Example:\n        List all pods in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import list_namespaced_pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_list = list_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.list_namespaced_pod(\n            namespace=namespace, **kube_kwargs\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.patch_namespaced_pod","title":"<code>patch_namespaced_pod</code>  <code>async</code>","text":"<p>Patch a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to patch.</p> required <code>pod_updates</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Patch a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import patch_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = patch_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        pod_updates=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def patch_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    pod_updates: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Patch a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to patch.\n        pod_updates: A Kubernetes `V1Pod` object.\n        namespace: The Kubernetes namespace to patch this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Patch a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import patch_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = patch_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                pod_updates=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.patch_namespaced_pod(\n            name=pod_name,\n            namespace=namespace,\n            body=pod_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.read_namespaced_pod","title":"<code>read_namespaced_pod</code>  <code>async</code>","text":"<p>Read information on a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this pod from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Read a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = read_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\"\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def read_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Read information on a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to read.\n        namespace: The Kubernetes namespace to read this pod from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Read a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = read_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\"\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.read_namespaced_pod(\n            name=pod_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.read_namespaced_pod_log","title":"<code>read_namespaced_pod_log</code>  <code>async</code>","text":"<p>Read logs from a Kubernetes pod in a given namespace.</p> <p>If <code>print_func</code> is provided, the logs will be streamed using that function. If the pod is no longer running, logs generated up to that point will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to read logs from.</p> required <code>container</code> <code>str</code> <p>The name of the container to read logs from.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this pod from.</p> <code>'default'</code> <code>print_func</code> <code>Optional[Callable]</code> <p>If provided, it will stream the pod logs by calling <code>print_func</code> for every line and returning <code>None</code>. If not provided, the current pod logs will be returned immediately.</p> <code>None</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[str, None]</code> <p>A string containing the logs from the pod's container.</p> Example <p>Read logs from a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect.logging import get_run_logger\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import read_namespaced_pod_logs\n\n@flow\ndef kubernetes_orchestrator():\n    logger = get_run_logger()\n\n    pod_logs = read_namespaced_pod_logs(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        container=\"test-container\",\n        print_func=logger.info\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def read_namespaced_pod_log(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    container: str,\n    namespace: Optional[str] = \"default\",\n    print_func: Optional[Callable] = None,\n    **kube_kwargs: Dict[str, Any],\n) -&gt; Union[str, None]:\n    \"\"\"Read logs from a Kubernetes pod in a given namespace.\n\n    If `print_func` is provided, the logs will be streamed using that function.\n    If the pod is no longer running, logs generated up to that point will be returned.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to read logs from.\n        container: The name of the container to read logs from.\n        namespace: The Kubernetes namespace to read this pod from.\n        print_func: If provided, it will stream the pod logs by calling `print_func`\n            for every line and returning `None`. If not provided, the current pod\n            logs will be returned immediately.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A string containing the logs from the pod's container.\n\n    Example:\n        Read logs from a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect.logging import get_run_logger\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import read_namespaced_pod_logs\n\n        @flow\n        def kubernetes_orchestrator():\n            logger = get_run_logger()\n\n            pod_logs = read_namespaced_pod_logs(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                container=\"test-container\",\n                print_func=logger.info\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        if print_func is not None:\n            # should no longer need to manually refresh on ApiException.status == 410\n            # as of https://github.com/kubernetes-client/python-base/pull/133\n            async with Watch() as watch:\n                async for log_line in watch.stream(\n                    core_v1_client.read_namespaced_pod_log,\n                    name=pod_name,\n                    namespace=namespace,\n                    container=container,\n                ):\n                    print_func(log_line)\n\n        return await core_v1_client.read_namespaced_pod_log(\n            name=pod_name,\n            namespace=namespace,\n            container=container,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.replace_namespaced_pod","title":"<code>replace_namespaced_pod</code>  <code>async</code>","text":"<p>Replace a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to replace.</p> required <code>new_pod</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Replace a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import replace_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = replace_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        new_pod=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}})\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def replace_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    new_pod: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Replace a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to replace.\n        new_pod: A Kubernetes `V1Pod` object.\n        namespace: The Kubernetes namespace to replace this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Replace a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import replace_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = replace_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                new_pod=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}})\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.replace_namespaced_pod(\n            body=new_pod,\n            name=pod_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/","title":"Services","text":""},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services","title":"<code>prefect_kubernetes.services</code>","text":"<p>Tasks for working with Kubernetes services.</p>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.create_namespaced_service","title":"<code>create_namespaced_service</code>  <code>async</code>","text":"<p>Create a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>A <code>KubernetesCredentials</code> block used to generate a <code>CoreV1Api</code> client.</p> required <code>new_service</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing the service to create.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to create the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to the <code>CoreV1Api</code> method call.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the created service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import create_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef create_service_flow():\n    v1_service = create_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_service=V1Service(metadata={...}, spec={...}),\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def create_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    new_service: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Create a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: A `KubernetesCredentials` block used to generate a\n            `CoreV1Api` client.\n        new_service: A `V1Service` object representing the service to create.\n        namespace: The namespace to create the service in.\n        **kube_kwargs: Additional keyword arguments to pass to the `CoreV1Api`\n            method call.\n\n    Returns:\n        A `V1Service` representing the created service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import create_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def create_service_flow():\n            v1_service = create_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_service=V1Service(metadata={...}, spec={...}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.create_namespaced_service(\n            body=new_service,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.delete_namespaced_service","title":"<code>delete_namespaced_service</code>  <code>async</code>","text":"<p>Delete a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A <code>V1DeleteOptions</code> object representing the options to delete the service with.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The namespace to delete the service from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the deleted service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import delete_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    delete_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def delete_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Delete a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to delete.\n        delete_options: A `V1DeleteOptions` object representing the options to\n            delete the service with.\n        namespace: The namespace to delete the service from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the deleted service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import delete_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            delete_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.delete_namespaced_service(\n            name=service_name,\n            namespace=namespace,\n            body=delete_options,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.list_namespaced_service","title":"<code>list_namespaced_service</code>  <code>async</code>","text":"<p>List namespaced Kubernetes services.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to list services from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1ServiceList</code> <p>A <code>V1ServiceList</code> representing the list of services in the given namespace.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import list_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    list_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def list_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1ServiceList:\n    \"\"\"List namespaced Kubernetes services.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The namespace to list services from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1ServiceList` representing the list of services in the given namespace.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import list_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            list_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.list_namespaced_service(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.patch_namespaced_service","title":"<code>patch_namespaced_service</code>  <code>async</code>","text":"<p>Patch a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to patch.</p> required <code>service_updates</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing patches to <code>service_name</code>.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to patch the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the patched service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import patch_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef kubernetes_orchestrator():\n    patch_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        new_service=V1Service(metadata={...}, spec={...}),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def patch_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    service_updates: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Patch a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to patch.\n        service_updates: A `V1Service` object representing patches to `service_name`.\n        namespace: The namespace to patch the service in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the patched service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import patch_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def kubernetes_orchestrator():\n            patch_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                new_service=V1Service(metadata={...}, spec={...}),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.patch_namespaced_service(\n            name=service_name,\n            body=service_updates,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.read_namespaced_service","title":"<code>read_namespaced_service</code>  <code>async</code>","text":"<p>Read a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to read the service from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> object representing the service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import read_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    read_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def read_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Read a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to read.\n        namespace: The namespace to read the service from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` object representing the service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import read_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            read_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.read_namespaced_service(\n            name=service_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.replace_namespaced_service","title":"<code>replace_namespaced_service</code>  <code>async</code>","text":"<p>Replace a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to replace.</p> required <code>new_service</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing the new service.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to replace the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the new service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import replace_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef kubernetes_orchestrator():\n    replace_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        new_service=V1Service(metadata={...}, spec={...}),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def replace_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    new_service: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Replace a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to replace.\n        new_service: A `V1Service` object representing the new service.\n        namespace: The namespace to replace the service in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the new service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import replace_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def kubernetes_orchestrator():\n            replace_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                new_service=V1Service(metadata={...}, spec={...}),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.replace_namespaced_service(\n            name=service_name,\n            body=new_service,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/utilities/","title":"Utilities","text":""},{"location":"integrations/prefect-kubernetes/utilities/#prefect_kubernetes.utilities","title":"<code>prefect_kubernetes.utilities</code>","text":"<p>Utilities for working with the Python Kubernetes API.</p>"},{"location":"integrations/prefect-kubernetes/utilities/#prefect_kubernetes.utilities.enable_socket_keep_alive","title":"<code>enable_socket_keep_alive</code>","text":"<p>Setting the keep-alive flags on the kubernetes client object. Unfortunately neither the kubernetes library nor the urllib3 library which kubernetes is using internally offer the functionality to enable keep-alive messages. Thus the flags are added to be used on the underlying sockets.</p> Source code in <code>prefect_kubernetes/utilities.py</code> <pre><code>def enable_socket_keep_alive(client: ApiClient) -&gt; None:\n    \"\"\"\n    Setting the keep-alive flags on the kubernetes client object.\n    Unfortunately neither the kubernetes library nor the urllib3 library which\n    kubernetes is using internally offer the functionality to enable keep-alive\n    messages. Thus the flags are added to be used on the underlying sockets.\n    \"\"\"\n\n    socket_options = [(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)]\n\n    if hasattr(socket, \"TCP_KEEPINTVL\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 30))\n\n    if hasattr(socket, \"TCP_KEEPCNT\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 6))\n\n    if hasattr(socket, \"TCP_KEEPIDLE\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 6))\n\n    if sys.platform == \"darwin\":\n        # TCP_KEEP_ALIVE not available on socket module in macOS, but defined in\n        # https://github.com/apple/darwin-xnu/blob/2ff845c2e033bd0ff64b5b6aa6063a1f8f65aa32/bsd/netinet/tcp.h#L215\n        TCP_KEEP_ALIVE = 0x10\n        socket_options.append((socket.IPPROTO_TCP, TCP_KEEP_ALIVE, 30))\n\n    client.rest_client.pool_manager.connection_pool_kw[\n        \"socket_options\"\n    ] = socket_options\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/","title":"Worker","text":""},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker","title":"<code>prefect_kubernetes.worker</code>","text":"<p>Module containing the Kubernetes worker used for executing flow runs as Kubernetes jobs.</p> <p>To start a Kubernetes worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type kubernetes\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker--securing-your-prefect-cloud-api-key","title":"Securing your Prefect Cloud API key","text":"<p>If you are using Prefect Cloud and would like to pass your Prefect Cloud API key to created jobs via a Kubernetes secret, set the <code>PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET</code> environment variable before starting your worker:</p> <pre><code>export PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET=\"true\"\nprefect worker start --pool 'my-work-pool' --type kubernetes\n</code></pre> <p>Note that your work will need permission to create secrets in the same namespace(s) that Kubernetes jobs are created in to execute flow runs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker--using-a-custom-kubernetes-job-manifest-template","title":"Using a custom Kubernetes job manifest template","text":"<p>The default template used for Kubernetes job manifests looks like this: <pre><code>---\napiVersion: batch/v1\nkind: Job\nmetadata:\nlabels: \"{{ labels }}\"\nnamespace: \"{{ namespace }}\"\ngenerateName: \"{{ name }}-\"\nspec:\nttlSecondsAfterFinished: \"{{ finished_job_ttl }}\"\ntemplate:\n    spec:\n    parallelism: 1\n    completions: 1\n    restartPolicy: Never\n    serviceAccountName: \"{{ service_account_name }}\"\n    containers:\n    - name: prefect-job\n        env: \"{{ env }}\"\n        image: \"{{ image }}\"\n        imagePullPolicy: \"{{ image_pull_policy }}\"\n        args: \"{{ command }}\"\n</code></pre></p> <p>Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job manifest and available variables can be customized on a work pool by work pool basis. These customizations can be made via the Prefect UI when creating or editing a work pool.</p> <p>For example, if you wanted to allow custom memory requests for a Kubernetes work pool you could update the job manifest template to look like this:</p> <pre><code>---\napiVersion: batch/v1\nkind: Job\nmetadata:\nlabels: \"{{ labels }}\"\nnamespace: \"{{ namespace }}\"\ngenerateName: \"{{ name }}-\"\nspec:\nttlSecondsAfterFinished: \"{{ finished_job_ttl }}\"\ntemplate:\n    spec:\n    parallelism: 1\n    completions: 1\n    restartPolicy: Never\n    serviceAccountName: \"{{ service_account_name }}\"\n    containers:\n    - name: prefect-job\n        env: \"{{ env }}\"\n        image: \"{{ image }}\"\n        imagePullPolicy: \"{{ image_pull_policy }}\"\n        args: \"{{ command }}\"\n        resources:\n            requests:\n                memory: \"{{ memory }}Mi\"\n            limits:\n                memory: 128Mi\n</code></pre> <p>In this new template, the <code>memory</code> placeholder allows customization of the memory allocated to Kubernetes jobs created by workers in this work pool, but the limit is hard-coded and cannot be changed by deployments.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.HashableKubernetesClusterConfig","title":"<code>HashableKubernetesClusterConfig</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A hashable version of the KubernetesClusterConfig class. Used for caching.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class HashableKubernetesClusterConfig(BaseModel, allow_mutation=False):\n    \"\"\"\n    A hashable version of the KubernetesClusterConfig class.\n    Used for caching.\n    \"\"\"\n\n    config: dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesImagePullPolicy","title":"<code>KubernetesImagePullPolicy</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing the image pull policy options for a Kubernetes job.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesImagePullPolicy(enum.Enum):\n    \"\"\"Enum representing the image pull policy options for a Kubernetes job.\"\"\"\n\n    IF_NOT_PRESENT = \"IfNotPresent\"\n    ALWAYS = \"Always\"\n    NEVER = \"Never\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker","title":"<code>KubernetesWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Kubernetes Jobs.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Kubernetes Jobs.\"\"\"\n\n    type: str = \"kubernetes\"\n    job_configuration = KubernetesWorkerJobConfiguration\n    job_configuration_variables = KubernetesWorkerVariables\n    _description = (\n        \"Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a \"\n        \"Kubernetes cluster.\"\n    )\n    _display_name = \"Kubernetes\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self._created_secrets = {}\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: KubernetesWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; KubernetesWorkerResult:\n        \"\"\"\n        Executes a flow run within a Kubernetes Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            KubernetesWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n        async with self._get_configured_kubernetes_client(configuration) as client:\n            logger.info(\"Creating Kubernetes job...\")\n\n            job = await self._create_job(configuration, client)\n\n            pid = await self._get_infrastructure_pid(job, client)\n            # Indicate that the job has started\n            if task_status is not None:\n                task_status.started(pid)\n\n            # Monitor the job until completion\n            events_replicator = KubernetesEventsReplicator(\n                client=client,\n                job_name=job.metadata.name,\n                namespace=configuration.namespace,\n                worker_resource=self._event_resource(),\n                related_resources=self._event_related_resources(\n                    configuration=configuration\n                ),\n                timeout_seconds=configuration.pod_watch_timeout_seconds,\n            )\n            async with events_replicator:\n                status_code = await self._watch_job(\n                    logger, job.metadata.name, configuration, client\n                )\n\n            return KubernetesWorkerResult(identifier=pid, status_code=status_code)\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n                Stops a job for a cancelled flow run based on the provided infrastructure PID\n                and run configuration.\n        att\"\"\"\n        await self._stop_job(infrastructure_pid, configuration, grace_seconds)\n\n    async def teardown(self, *exc_info):\n        await super().teardown(*exc_info)\n\n        await self._clean_up_created_secrets()\n\n    async def _clean_up_created_secrets(self):\n        \"\"\"Deletes any secrets created during the worker's operation.\"\"\"\n        for key, configuration in self._created_secrets.items():\n            async with self._get_configured_kubernetes_client(configuration) as client:\n                v1 = CoreV1Api(client)\n                result = await v1.delete_namespaced_secret(\n                    name=key[0],\n                    namespace=key[1],\n                )\n\n                if isinstance(result, Exception):\n                    self._logger.warning(\n                        \"Failed to delete created secret with exception: %s\", result\n                    )\n\n    async def _stop_job(\n        self,\n        infrastructure_pid: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"Removes the given Job from the Kubernetes cluster\"\"\"\n        async with self._get_configured_kubernetes_client(configuration) as client:\n            job_cluster_uid, job_namespace, job_name = self._parse_infrastructure_pid(\n                infrastructure_pid\n            )\n\n            if job_namespace != configuration.namespace:\n                raise InfrastructureNotAvailable(\n                    f\"Unable to kill job {job_name!r}: The job is running in namespace \"\n                    f\"{job_namespace!r} but this worker expected jobs to be running in \"\n                    f\"namespace {configuration.namespace!r} based on the work pool and \"\n                    \"deployment configuration.\"\n                )\n\n            current_cluster_uid = await self._get_cluster_uid(client)\n            if job_cluster_uid != current_cluster_uid:\n                raise InfrastructureNotAvailable(\n                    f\"Unable to kill job {job_name!r}: The job is running on another \"\n                    \"cluster than the one specified by the infrastructure PID.\"\n                )\n\n            async with self._get_batch_client(client) as batch_client:\n                try:\n                    await batch_client.delete_namespaced_job(\n                        name=job_name,\n                        namespace=job_namespace,\n                        grace_period_seconds=grace_seconds,\n                        # Foreground propagation deletes dependent objects before deleting # noqa\n                        # owner objects. This ensures that the pods are cleaned up before # noqa\n                        # the job is marked as deleted.\n                        # See: https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion # noqa\n                        propagation_policy=\"Foreground\",\n                    )\n                except kubernetes_asyncio.client.exceptions.ApiException as exc:\n                    if exc.status == 404:\n                        raise InfrastructureNotFound(\n                            f\"Unable to kill job {job_name!r}: The job was not found.\"\n                        ) from exc\n                    else:\n                        raise\n\n    @asynccontextmanager\n    async def _get_configured_kubernetes_client(\n        self, configuration: KubernetesWorkerJobConfiguration\n    ) -&gt; AsyncGenerator[\"ApiClient\", None]:\n        \"\"\"\n        Returns a configured Kubernetes client.\n        \"\"\"\n        client = None\n\n        if configuration.cluster_config:\n            config_dict = configuration.cluster_config.config\n            context = configuration.cluster_config.context_name\n            client = await config.new_client_from_config_dict(\n                config_dict=config_dict,\n                context=context,\n            )\n        else:\n            # Try to load in-cluster configuration\n            try:\n                config.load_incluster_config()\n                client = ApiClient()\n            except config.ConfigException:\n                # If in-cluster config fails, load the local kubeconfig\n                client = await config.new_client_from_config()\n        try:\n            yield client\n        finally:\n            await client.close()\n\n    async def _replace_api_key_with_secret(\n        self, configuration: KubernetesWorkerJobConfiguration, client: \"ApiClient\"\n    ):\n        \"\"\"Replaces the PREFECT_API_KEY environment variable with a Kubernetes secret\"\"\"\n        manifest_env = configuration.job_manifest[\"spec\"][\"template\"][\"spec\"][\n            \"containers\"\n        ][0].get(\"env\")\n        manifest_api_key_env = next(\n            (\n                env_entry\n                for env_entry in manifest_env\n                if env_entry.get(\"name\") == \"PREFECT_API_KEY\"\n            ),\n            {},\n        )\n        api_key = manifest_api_key_env.get(\"value\")\n        if api_key:\n            secret_name = f\"prefect-{_slugify_name(self.name)}-api-key\"\n            secret = await self._upsert_secret(\n                name=secret_name,\n                value=api_key,\n                namespace=configuration.namespace,\n                client=client,\n            )\n            # Store configuration so that we can delete the secret when the worker shuts\n            # down\n            self._created_secrets[\n                (secret.metadata.name, secret.metadata.namespace)\n            ] = configuration\n            new_api_env_entry = {\n                \"name\": \"PREFECT_API_KEY\",\n                \"valueFrom\": {\"secretKeyRef\": {\"name\": secret_name, \"key\": \"value\"}},\n            }\n            manifest_env = [\n                entry if entry.get(\"name\") != \"PREFECT_API_KEY\" else new_api_env_entry\n                for entry in manifest_env\n            ]\n            configuration.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                \"env\"\n            ] = manifest_env\n\n    @retry(\n        stop=stop_after_attempt(MAX_ATTEMPTS),\n        wait=wait_fixed(RETRY_MIN_DELAY_SECONDS)\n        + wait_random(\n            RETRY_MIN_DELAY_JITTER_SECONDS,\n            RETRY_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    async def _create_job(\n        self, configuration: KubernetesWorkerJobConfiguration, client: \"ApiClient\"\n    ) -&gt; \"V1Job\":\n        \"\"\"\n        Creates a Kubernetes job from a job manifest.\n        \"\"\"\n        if os.environ.get(\n            \"PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET\", \"\"\n        ).strip().lower() in (\"true\", \"1\"):\n            await self._replace_api_key_with_secret(\n                configuration=configuration, client=client\n            )\n\n        try:\n            batch_client = BatchV1Api(client)\n            job = await batch_client.create_namespaced_job(\n                configuration.namespace,\n                configuration.job_manifest,\n            )\n        except kubernetes_asyncio.client.exceptions.ApiException as exc:\n            # Parse the reason and message from the response if feasible\n            message = \"\"\n            if exc.reason:\n                message += \": \" + exc.reason\n            if exc.body and \"message\" in (body := json.loads(exc.body)):\n                message += \": \" + body[\"message\"]\n\n            raise InfrastructureError(\n                f\"Unable to create Kubernetes job{message}\"\n            ) from exc\n\n        return job\n\n    async def _upsert_secret(\n        self, name: str, value: str, namespace: str, client: \"ApiClient\"\n    ):\n        encoded_value = base64.b64encode(value.encode(\"utf-8\")).decode(\"utf-8\")\n        core_client = CoreV1Api(client)\n        try:\n            # Get the current version of the Secret and update it with the\n            # new value\n            current_secret = await core_client.read_namespaced_secret(\n                name=name, namespace=namespace\n            )\n            current_secret.data = {\"value\": encoded_value}\n            secret = await core_client.replace_namespaced_secret(\n                name=name, namespace=namespace, body=current_secret\n            )\n        except ApiException as exc:\n            if exc.status != 404:\n                raise\n            # Create the secret if it doesn't already exist\n            metadata = V1ObjectMeta(name=name, namespace=namespace)\n            secret = V1Secret(\n                api_version=\"v1\",\n                kind=\"Secret\",\n                metadata=metadata,\n                data={\"value\": encoded_value},\n            )\n            secret = await core_client.create_namespaced_secret(\n                namespace=namespace, body=secret\n            )\n        return secret\n\n    @asynccontextmanager\n    async def _get_batch_client(\n        self, client: \"ApiClient\"\n    ) -&gt; AsyncGenerator[\"BatchV1Api\", None]:\n        \"\"\"\n        Context manager for retrieving a Kubernetes batch client.\n        \"\"\"\n        try:\n            yield BatchV1Api(api_client=client)\n        finally:\n            await client.close()\n\n    async def _get_infrastructure_pid(self, job: \"V1Job\", client: \"ApiClient\") -&gt; str:\n        \"\"\"\n        Generates a Kubernetes infrastructure PID.\n\n        The PID is in the format: \"&lt;cluster uid&gt;:&lt;namespace&gt;:&lt;job name&gt;\".\n        \"\"\"\n        cluster_uid = await self._get_cluster_uid(client)\n        pid = f\"{cluster_uid}:{job.metadata.namespace}:{job.metadata.name}\"\n        return pid\n\n    def _parse_infrastructure_pid(\n        self, infrastructure_pid: str\n    ) -&gt; Tuple[str, str, str]:\n        \"\"\"\n        Parse a Kubernetes infrastructure PID into its component parts.\n\n        Returns a cluster UID, namespace, and job name.\n        \"\"\"\n        cluster_uid, namespace, job_name = infrastructure_pid.split(\":\", 2)\n        return cluster_uid, namespace, job_name\n\n    async def _get_cluster_uid(self, client: \"ApiClient\") -&gt; str:\n        \"\"\"\n        Gets a unique id for the current cluster being used.\n\n        There is no real unique identifier for a cluster. However, the `kube-system`\n        namespace is immutable and has a persistence UID that we use instead.\n\n        PREFECT_KUBERNETES_CLUSTER_UID can be set in cases where the `kube-system`\n        namespace cannot be read e.g. when a cluster role cannot be created. If set,\n        this variable will be used and we will not attempt to read the `kube-system`\n        namespace.\n\n        See https://github.com/kubernetes/kubernetes/issues/44954\n        \"\"\"\n        # Default to an environment variable\n        env_cluster_uid = os.environ.get(\"PREFECT_KUBERNETES_CLUSTER_UID\")\n        if env_cluster_uid:\n            return env_cluster_uid\n\n        # Read the UID from the cluster namespace\n        v1 = CoreV1Api(client)\n        namespace = await v1.read_namespace(\"kube-system\")\n        cluster_uid = namespace.metadata.uid\n        return cluster_uid\n\n    async def _stream_job_logs(\n        self,\n        logger: logging.Logger,\n        pod_name: str,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client,\n    ):\n        timeout = aiohttp.ClientTimeout(total=None)\n        core_client = CoreV1Api(client)\n\n        logs = await core_client.read_namespaced_pod_log(\n            pod_name,\n            configuration.namespace,\n            follow=True,\n            _preload_content=False,\n            container=\"prefect-job\",\n            _request_timeout=timeout,\n        )\n        try:\n            async for line in logs.content:\n                if not line:\n                    break\n                print(line.decode().rstrip())\n        except Exception:\n            logger.warning(\n                (\n                    \"Error occurred while streaming logs - \"\n                    \"Job will continue to run but logs will \"\n                    \"no longer be streamed to stdout.\"\n                ),\n                exc_info=True,\n            )\n\n    async def _job_events(\n        self,\n        batch_client: BatchV1Api,\n        job_name: str,\n        namespace: str,\n        watch_kwargs: dict,\n    ):\n        \"\"\"\n        Stream job events.\n\n        Pick up from the current resource version returned by the API\n        in the case of a 410.\n\n        See https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes  # noqa\n        \"\"\"\n        watch = kubernetes_asyncio.watch.Watch()\n        resource_version = None\n        async with watch:\n            while True:\n                try:\n                    async for event in watch.stream(\n                        func=batch_client.list_namespaced_job,\n                        namespace=namespace,\n                        field_selector=f\"metadata.name={job_name}\",\n                        **watch_kwargs,\n                    ):\n                        yield event\n                except ApiException as e:\n                    if e.status == 410:\n                        job_list = await batch_client.list_namespaced_job(\n                            namespace=namespace,\n                            field_selector=f\"metadata.name={job_name}\",\n                        )\n\n                        resource_version = job_list.metadata.resource_version\n                        watch_kwargs[\"resource_version\"] = resource_version\n                    else:\n                        raise\n\n    async def _monitor_job_events(self, batch_client, job_name, logger, configuration):\n        job = await batch_client.read_namespaced_job(\n            name=job_name, namespace=configuration.namespace\n        )\n        completed = job.status.completion_time is not None\n        watch_kwargs = (\n            {\"timeout_seconds\": configuration.job_watch_timeout_seconds}\n            if configuration.job_watch_timeout_seconds\n            else {}\n        )\n\n        while not completed:\n            async for event in self._job_events(\n                batch_client,\n                job_name,\n                configuration.namespace,\n                watch_kwargs,\n            ):\n                if event[\"type\"] == \"DELETED\":\n                    logger.error(f\"Job {job_name!r}: Job has been deleted.\")\n                    completed = True\n                elif event[\"object\"].status.completion_time:\n                    if not event[\"object\"].status.succeeded:\n                        # Job failed, exit while loop and return pod exit code\n                        logger.error(f\"Job {job_name!r}: Job failed.\")\n                    completed = True\n                # Check if the job has reached its backoff limit\n                # and stop watching if it has\n                elif (\n                    event[\"object\"].spec.backoff_limit is not None\n                    and event[\"object\"].status.failed is not None\n                    and event[\"object\"].status.failed\n                    &gt; event[\"object\"].spec.backoff_limit\n                ):\n                    logger.error(f\"Job {job_name!r}: Job reached backoff limit.\")\n                    completed = True\n                # If the job has no backoff limit, check if it has failed\n                # and stop watching if it has\n                elif (\n                    not event[\"object\"].spec.backoff_limit\n                    and event[\"object\"].status.failed\n                ):\n                    completed = True\n                if completed:\n                    break\n\n    async def _watch_job(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; int:\n        \"\"\"\n        Watch a job.\n\n        Return the final status code of the first container.\n        \"\"\"\n\n        logger.debug(f\"Job {job_name!r}: Monitoring job...\")\n\n        job = await self._get_job(logger, job_name, configuration, client)\n        if not job:\n            return -1\n\n        pod = await self._get_job_pod(logger, job_name, configuration, client)\n        if not pod:\n            return -1\n\n        # Create a list of tasks to run concurrently\n        async with self._get_batch_client(client) as batch_client:\n            tasks = [\n                self._monitor_job_events(\n                    batch_client,\n                    job_name,\n                    logger,\n                    configuration,\n                )\n            ]\n            try:\n                with timeout_async(seconds=configuration.job_watch_timeout_seconds):\n                    if configuration.stream_output:\n                        tasks.append(\n                            self._stream_job_logs(\n                                logger,\n                                pod.metadata.name,\n                                job_name,\n                                configuration,\n                                client,\n                            )\n                        )\n\n                    results = await asyncio.gather(*tasks, return_exceptions=True)\n                    if any(isinstance(result, Exception) for result in results):\n                        for result in results:\n                            if isinstance(result, Exception):\n                                logger.error(\n                                    f\"Error during task execution: {result}\",\n                                    exc_info=True,\n                                )\n            except TimeoutError:\n                logger.error(\n                    f\"Job {job_name!r}: Job did not complete within \"\n                    f\"timeout of {configuration.job_watch_timeout_seconds}s.\"\n                )\n                return -1\n\n            core_client = CoreV1Api(client)\n            # Get all pods for the job\n            pods = await core_client.list_namespaced_pod(\n                namespace=configuration.namespace, label_selector=f\"job-name={job_name}\"\n            )\n            # Get the status for only the most recently used pod\n            pods.items.sort(\n                key=lambda pod: pod.metadata.creation_timestamp, reverse=True\n            )\n            most_recent_pod = pods.items[0] if pods.items else None\n            first_container_status = (\n                most_recent_pod.status.container_statuses[0]\n                if most_recent_pod\n                else None\n            )\n\n        if not first_container_status:\n            logger.error(f\"Job {job_name!r}: No pods found for job.\")\n            return -1\n        # In some cases, such as spot instance evictions, the pod will be forcibly\n        # terminated and not report a status correctly.\n        elif (\n            first_container_status.state is None\n            or first_container_status.state.terminated is None\n            or first_container_status.state.terminated.exit_code is None\n        ):\n            logger.error(\n                f\"Could not determine exit code for {job_name!r}.\"\n                \"Exit code will be reported as -1.\"\n                f\"First container status info did not report an exit code.\"\n                f\"First container info: {first_container_status}.\"\n            )\n            return -1\n\n        return first_container_status.state.terminated.exit_code\n\n    async def _get_job(\n        self,\n        logger: logging.Logger,\n        job_id: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; Optional[\"V1Job\"]:\n        \"\"\"Get a Kubernetes job by id.\"\"\"\n\n        try:\n            batch_client = BatchV1Api(client)\n            job = await batch_client.read_namespaced_job(\n                name=job_id, namespace=configuration.namespace\n            )\n        except kubernetes_asyncio.client.exceptions.ApiException:\n            logger.error(f\"Job {job_id!r} was removed.\", exc_info=True)\n            return None\n        return job\n\n    async def _get_job_pod(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; Optional[\"V1Pod\"]:\n        \"\"\"Get the first running pod for a job.\"\"\"\n\n        watch = kubernetes_asyncio.watch.Watch()\n        logger.info(f\"Job {job_name!r}: Starting watch for pod start...\")\n        last_phase = None\n        last_pod_name: Optional[str] = None\n        core_client = CoreV1Api(client)\n        async with watch:\n            async for event in watch.stream(\n                func=core_client.list_namespaced_pod,\n                namespace=configuration.namespace,\n                label_selector=f\"job-name={job_name}\",\n                timeout_seconds=configuration.pod_watch_timeout_seconds,\n            ):\n                pod: V1Pod = event[\"object\"]\n                last_pod_name = pod.metadata.name\n                logger.info(f\"Job {job_name!r}: Pod {last_pod_name!r} has started.\")\n                phase = pod.status.phase\n                if phase != last_phase:\n                    logger.info(f\"Job {job_name!r}: Pod has status {phase!r}.\")\n\n                if phase != \"Pending\":\n                    return pod\n\n                last_phase = phase\n            # If we've gotten here, we never found the Pod that was created for the flow run\n            # Job, so let's inspect the situation and log what we can find.  It's possible\n            # that the Job ran into scheduling constraints it couldn't satisfy, like\n            # memory/CPU requests, or a volume that wasn't available, or a node with an\n            # available GPU.\n            logger.error(f\"Job {job_name!r}: Pod never started.\")\n            await self._log_recent_events(\n                logger, job_name, last_pod_name, configuration, client\n            )\n\n    async def _log_recent_events(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        pod_name: Optional[str],\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; None:\n        \"\"\"Look for reasons why a Job may not have been able to schedule a Pod, or why\n        a Pod may not have been able to start and log them to the provided logger.\"\"\"\n\n        def best_event_time(event: CoreV1Event) -&gt; datetime:\n            \"\"\"Choose the best timestamp from a Kubernetes event\"\"\"\n            return event.event_time or event.last_timestamp\n\n        def log_event(event: CoreV1Event):\n            \"\"\"Log an event in one of a few formats to the provided logger\"\"\"\n            if event.count and event.count &gt; 1:\n                logger.info(\n                    \"%s event %r (%s times) at %s: %s\",\n                    event.involved_object.kind,\n                    event.reason,\n                    event.count,\n                    best_event_time(event),\n                    event.message,\n                )\n            else:\n                logger.info(\n                    \"%s event %r at %s: %s\",\n                    event.involved_object.kind,\n                    event.reason,\n                    best_event_time(event),\n                    event.message,\n                )\n\n        core_client = CoreV1Api(client)\n\n        events: CoreV1EventList = await core_client.list_namespaced_event(\n            configuration.namespace\n        )\n\n        event: CoreV1Event\n        for event in sorted(events.items, key=best_event_time):\n            if (\n                event.involved_object.api_version == \"batch/v1\"\n                and event.involved_object.kind == \"Job\"\n                and event.involved_object.namespace == configuration.namespace\n                and event.involved_object.name == job_name\n            ):\n                log_event(event)\n\n            if (\n                pod_name\n                and event.involved_object.api_version == \"v1\"\n                and event.involved_object.kind == \"Pod\"\n                and event.involved_object.namespace == configuration.namespace\n                and event.involved_object.name == pod_name\n            ):\n                log_event(event)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<pre><code>    Stops a job for a cancelled flow run based on the provided infrastructure PID\n    and run configuration.\n</code></pre> <p>att</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: KubernetesWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n            Stops a job for a cancelled flow run based on the provided infrastructure PID\n            and run configuration.\n    att\"\"\"\n    await self._stop_job(infrastructure_pid, configuration, grace_seconds)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Kubernetes Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>KubernetesWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>KubernetesWorkerResult</code> <code>KubernetesWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: KubernetesWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; KubernetesWorkerResult:\n    \"\"\"\n    Executes a flow run within a Kubernetes Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        KubernetesWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n    async with self._get_configured_kubernetes_client(configuration) as client:\n        logger.info(\"Creating Kubernetes job...\")\n\n        job = await self._create_job(configuration, client)\n\n        pid = await self._get_infrastructure_pid(job, client)\n        # Indicate that the job has started\n        if task_status is not None:\n            task_status.started(pid)\n\n        # Monitor the job until completion\n        events_replicator = KubernetesEventsReplicator(\n            client=client,\n            job_name=job.metadata.name,\n            namespace=configuration.namespace,\n            worker_resource=self._event_resource(),\n            related_resources=self._event_related_resources(\n                configuration=configuration\n            ),\n            timeout_seconds=configuration.pod_watch_timeout_seconds,\n        )\n        async with events_replicator:\n            status_code = await self._watch_job(\n                logger, job.metadata.name, configuration, client\n            )\n\n        return KubernetesWorkerResult(identifier=pid, status_code=status_code)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerJobConfiguration","title":"<code>KubernetesWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Kubernetes worker.</p> <p>An instance of this class is passed to the Kubernetes worker's <code>run</code> method for each flow run. It contains all of the information necessary to execute the flow run as a Kubernetes job.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name to give to created Kubernetes job.</p> <code>command</code> <p>The command executed in created Kubernetes jobs to kick off flow run execution.</p> <code>env</code> <p>The environment variables to set in created Kubernetes jobs.</p> <code>labels</code> <p>The labels to set on created Kubernetes jobs.</p> <code>namespace</code> <code>str</code> <p>The Kubernetes namespace to create Kubernetes jobs in.</p> <code>job_manifest</code> <code>Dict[str, Any]</code> <p>The Kubernetes job manifest to use to create Kubernetes jobs.</p> <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>The Kubernetes cluster configuration to use for authentication to a Kubernetes cluster.</p> <code>job_watch_timeout_seconds</code> <code>Optional[int]</code> <p>The number of seconds to wait for the job to complete before timing out. If <code>None</code>, the worker will wait indefinitely.</p> <code>pod_watch_timeout_seconds</code> <code>int</code> <p>The number of seconds to wait for the pod to complete before timing out.</p> <code>stream_output</code> <code>bool</code> <p>Whether or not to stream the job's output.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Kubernetes worker.\n\n    An instance of this class is passed to the Kubernetes worker's `run` method\n    for each flow run. It contains all of the information necessary to execute\n    the flow run as a Kubernetes job.\n\n    Attributes:\n        name: The name to give to created Kubernetes job.\n        command: The command executed in created Kubernetes jobs to kick off\n            flow run execution.\n        env: The environment variables to set in created Kubernetes jobs.\n        labels: The labels to set on created Kubernetes jobs.\n        namespace: The Kubernetes namespace to create Kubernetes jobs in.\n        job_manifest: The Kubernetes job manifest to use to create Kubernetes jobs.\n        cluster_config: The Kubernetes cluster configuration to use for authentication\n            to a Kubernetes cluster.\n        job_watch_timeout_seconds: The number of seconds to wait for the job to\n            complete before timing out. If `None`, the worker will wait indefinitely.\n        pod_watch_timeout_seconds: The number of seconds to wait for the pod to\n            complete before timing out.\n        stream_output: Whether or not to stream the job's output.\n    \"\"\"\n\n    namespace: str = Field(default=\"default\")\n    job_manifest: Dict[str, Any] = Field(template=_get_default_job_manifest_template())\n    cluster_config: Optional[KubernetesClusterConfig] = Field(default=None)\n    job_watch_timeout_seconds: Optional[int] = Field(default=None)\n    pod_watch_timeout_seconds: int = Field(default=60)\n    stream_output: bool = Field(default=True)\n\n    # internal-use only\n    _api_dns_name: Optional[str] = None  # Replaces 'localhost' in API URL\n\n    @validator(\"job_manifest\")\n    def _ensure_metadata_is_present(cls, value: Dict[str, Any]):\n        \"\"\"Ensures that the metadata is present in the job manifest.\"\"\"\n        if \"metadata\" not in value:\n            value[\"metadata\"] = {}\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_labels_is_present(cls, value: Dict[str, Any]):\n        \"\"\"Ensures that the metadata is present in the job manifest.\"\"\"\n        if \"labels\" not in value[\"metadata\"]:\n            value[\"metadata\"][\"labels\"] = {}\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_namespace_is_present(cls, value: Dict[str, Any], values):\n        \"\"\"Ensures that the namespace is present in the job manifest.\"\"\"\n        if \"namespace\" not in value[\"metadata\"]:\n            value[\"metadata\"][\"namespace\"] = values[\"namespace\"]\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job manifest includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_manifest())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        patch = JsonPatch.from_diff(value, _get_base_job_manifest())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": _slugify_label_value(\n                prefect.__version__.split(\"+\")[0]\n            ),\n        }\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job manifest and that the\n        job manifest is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n        # Update configuration env and job manifest env\n        self._update_prefect_api_url_if_local_server()\n        self._populate_env_in_manifest()\n        # Update labels in job manifest\n        self._slugify_labels()\n        # Add defaults to job manifest if necessary\n        self._populate_image_if_not_present()\n        self._populate_command_if_not_present()\n        self._populate_generate_name_if_not_present()\n\n    def _populate_env_in_manifest(self):\n        \"\"\"\n        Populates environment variables in the job manifest.\n\n        When `env` is templated as a variable in the job manifest it comes in as a\n        dictionary. We need to convert it to a list of dictionaries to conform to the\n        Kubernetes job manifest schema.\n\n        This function also handles the case where the user has removed the `{{ env }}`\n        placeholder and hard coded a value for `env`. In this case, we need to prepend\n        our environment variables to the list to ensure Prefect setting propagation.\n        An example reason the a user would remove the `{{ env }}` placeholder to\n        hardcode Kubernetes secrets in the base job template.\n        \"\"\"\n        transformed_env = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n\n        template_env = self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][\n            0\n        ].get(\"env\")\n\n        # If user has removed `{{ env }}` placeholder and hard coded a value for `env`,\n        # we need to prepend our environment variables to the list to ensure Prefect\n        # setting propagation.\n        if isinstance(template_env, list):\n            self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n                *transformed_env,\n                *template_env,\n            ]\n        # Current templating adds `env` as a dict when the kubernetes manifest requires\n        # a list of dicts. Might be able to improve this in the future with a better\n        # default `env` value and better typing.\n        else:\n            self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                \"env\"\n            ] = transformed_env\n\n    def _update_prefect_api_url_if_local_server(self):\n        \"\"\"If the API URL has been set by the base environment rather than the by the\n        user, update the value to ensure connectivity when using a bridge network by\n        updating local connections to use the internal host\n        \"\"\"\n        if self.env.get(\"PREFECT_API_URL\") and self._api_dns_name:\n            self.env[\"PREFECT_API_URL\"] = (\n                self.env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", self._api_dns_name)\n                .replace(\"127.0.0.1\", self._api_dns_name)\n            )\n\n    def _slugify_labels(self):\n        \"\"\"Slugifies the labels in the job manifest.\"\"\"\n        all_labels = {**self.job_manifest[\"metadata\"].get(\"labels\", {}), **self.labels}\n        self.job_manifest[\"metadata\"][\"labels\"] = {\n            _slugify_label_key(k): _slugify_label_value(v)\n            for k, v in all_labels.items()\n        }\n\n    def _populate_image_if_not_present(self):\n        \"\"\"Ensures that the image is present in the job manifest. Populates the image\n        with the default Prefect image if it is not present.\"\"\"\n        try:\n            if (\n                \"image\"\n                not in self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0]\n            ):\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"image\"\n                ] = get_prefect_image_name()\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify image due to invalid job manifest template.\"\n            )\n\n    def _populate_command_if_not_present(self):\n        \"\"\"\n        Ensures that the command is present in the job manifest. Populates the command\n        with the `prefect -m prefect.engine` if a command is not present.\n        \"\"\"\n        try:\n            command = self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][\n                0\n            ].get(\"args\")\n            if command is None:\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"args\"\n                ] = shlex.split(self._base_flow_run_command())\n            elif isinstance(command, str):\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"args\"\n                ] = shlex.split(command)\n            elif not isinstance(command, list):\n                raise ValueError(\n                    \"Invalid job manifest template: 'command' must be a string or list.\"\n                )\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify command due to invalid job manifest template.\"\n            )\n\n    def _populate_generate_name_if_not_present(self):\n        \"\"\"Ensures that the generateName is present in the job manifest.\"\"\"\n        manifest_generate_name = self.job_manifest[\"metadata\"].get(\"generateName\", \"\")\n        has_placeholder = len(find_placeholders(manifest_generate_name)) &gt; 0\n        # if name wasn't present during template rendering, generateName will be\n        # just a hyphen\n\n        manifest_generate_name_templated_with_empty_string = (\n            manifest_generate_name == \"-\"\n        )\n        if (\n            not manifest_generate_name\n            or has_placeholder\n            or manifest_generate_name_templated_with_empty_string\n            or manifest_generate_name == \"None-\"\n        ):\n            generate_name = None\n            if self.name:\n                generate_name = _slugify_name(self.name)\n            # _slugify_name will return None if the slugified name in an exception\n            if not generate_name:\n                generate_name = \"prefect-job\"\n            self.job_manifest[\"metadata\"][\"generateName\"] = f\"{generate_name}-\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job manifest and that the job manifest is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job manifest and that the\n    job manifest is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n    # Update configuration env and job manifest env\n    self._update_prefect_api_url_if_local_server()\n    self._populate_env_in_manifest()\n    # Update labels in job manifest\n    self._slugify_labels()\n    # Add defaults to job manifest if necessary\n    self._populate_image_if_not_present()\n    self._populate_command_if_not_present()\n    self._populate_generate_name_if_not_present()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerResult","title":"<code>KubernetesWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerVariables","title":"<code>KubernetesWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Kubernetes worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Kubernetes worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    namespace: str = Field(\n        default=\"default\", description=\"The Kubernetes namespace to create jobs within.\"\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=\"The image reference of a container image to use for created jobs. \"\n        \"If not set, the latest Prefect image will be used.\",\n        examples=[\"docker.io/prefecthq/prefect:3-latest\"],\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        description=\"The Kubernetes service account to use for job creation.\",\n    )\n    image_pull_policy: Literal[\"IfNotPresent\", \"Always\", \"Never\"] = Field(\n        default=KubernetesImagePullPolicy.IF_NOT_PRESENT,\n        description=\"The Kubernetes image pull policy to use for job containers.\",\n    )\n    finished_job_ttl: Optional[int] = Field(\n        default=None,\n        title=\"Finished Job TTL\",\n        description=\"The number of seconds to retain jobs after completion. If set, \"\n        \"finished jobs will be cleaned up by Kubernetes after the given delay. If not \"\n        \"set, jobs will be retained indefinitely.\",\n    )\n    job_watch_timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"Number of seconds to wait for each event emitted by a job before \"\n            \"timing out. If not set, the worker will wait for each event indefinitely.\"\n        ),\n    )\n    pod_watch_timeout_seconds: int = Field(\n        default=60,\n        description=\"Number of seconds to watch for pod creation before timing out.\",\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the job to local standard output.\"\n        ),\n    )\n    cluster_config: Optional[KubernetesClusterConfig] = Field(\n        default=None,\n        description=\"The Kubernetes cluster config to use for job creation.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-ray/","title":"prefect-ray","text":"<p>Ray can run the tasks in your flow in parallel by distributing them over multiple machines. The <code>prefect-ray</code> integration makes it easy speed up your flow runs by integrating Ray into your code.</p>"},{"location":"integrations/prefect-ray/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-ray/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> </ul>"},{"location":"integrations/prefect-ray/#install-prefect-ray","title":"Install prefect-ray","text":"<pre><code>pip install prefect-ray\n</code></pre> <p>Ray environment limitations</p> <p>While we're excited about parallel task execution via Ray, there are a few limitations with Ray you should be aware of:</p> <ul> <li>Support for Python 3.11 is experimental.</li> <li>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</li> <li>Ray's Windows support is currently in beta.</li> </ul> <p>See the Ray installation documentation for further compatibility information.</p>"},{"location":"integrations/prefect-ray/#running-tasks-on-ray","title":"Running tasks on Ray","text":"<p>The <code>RayTaskRunner</code> is a Prefect task runner that submits tasks to Ray for parallel execution.</p> <p>By default, a temporary Ray instance is created for the duration of the flow run.</p> <p>For example, this flow counts to three in parallel.</p> <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_ray import RayTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=RayTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre> <p>If you already have a Ray instance running, you can provide the connection URL via an <code>address</code> argument.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-ray</code> collection is installed as described earlier: <code>pip install prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>RayTaskRunner</code> with a local, temporary Ray instance created by Prefect at flow run time.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    ... \n</code></pre> <p>This flow uses the <code>RayTaskRunner</code> configured to access an existing Ray instance at <code>ray://192.0.2.255:8786</code>.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner(address=\"ray://192.0.2.255:8786\"))\ndef my_flow():\n    ... \n</code></pre> <p><code>RayTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Ray instance, starting with the ray:// URI. init_kwargs Additional kwargs to use when calling <code>ray.init</code>. <p>Note that Ray Client uses the ray:// URI to indicate the address of a Ray instance. If you don't provide the <code>address</code> of a Ray instance, Prefect creates a temporary instance automatically.</p> <p>Ray environment limitations</p> <p>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</p> <p>See the Ray installation documentation for further compatibility information.</p>"},{"location":"integrations/prefect-ray/#running-tasks-on-a-ray-remote-cluster","title":"Running tasks on a Ray remote cluster","text":"<p>When using the <code>RayTaskRunner</code> with a remote Ray cluster, you may run into issues that are not seen when using a local Ray instance. To resolve these issues, we recommend taking the following steps when working with a remote Ray cluster:</p> <ol> <li>By default, Prefect will not persist any data to the filesystem of the remote ray worker. However, if you want to take advantage of Prefect's caching ability, you will need to configure a remote result storage to persist results across task runs.</li> </ol> <p>We recommend using the Prefect UI to configure a storage block to use for remote results storage.</p> <p>Here's an example of a flow that uses caching and remote result storage:</p> <pre><code>from typing import List\n\nfrom prefect import flow, get_run_logger, task\nfrom prefect.filesystems import S3\nfrom prefect.tasks import task_input_hash\nfrom prefect_ray.task_runners import RayTaskRunner\n\n\n# The result of this task will be cached in the configured result storage\n@task(cache_key_fn=task_input_hash)\ndef say_hello(name: str) -&gt; None:\n    logger = get_run_logger()\n    # This log statement will print only on the first run. Subsequent runs will be cached.\n    logger.info(f\"hello {name}!\")\n    return name\n\n\n@flow(\n    task_runner=RayTaskRunner(\n        address=\"ray://&lt;instance_public_ip_address&gt;:10001\",\n    ),\n    # Using an S3 block that has already been created via the Prefect UI\n    result_storage=\"s3/my-result-storage\",\n)\ndef greetings(names: List[str]) -&gt; None:\n    for name in names:\n        say_hello.submit(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <ol> <li>If you get an error stating that the module 'prefect' cannot be found, ensure <code>prefect</code> is installed on the remote cluster, with:</li> </ol> <pre><code>pip install prefect\n</code></pre> <ol> <li>If you get an error with a message similar to \"File system created with scheme 's3' could not be created\", ensure the required Python modules are installed on both local and remote machines. The required prerequisite modules can be found in the Prefect documentation. For example, if using S3 for storage:</li> </ol> <pre><code>pip install s3fs\n</code></pre> <ol> <li>If you are seeing timeout or other connection errors, double check the address provided to the <code>RayTaskRunner</code>. The address should look similar to: <code>address='ray://&lt;head_node_ip_address&gt;:10001'</code>:</li> </ol> <pre><code>RayTaskRunner(address=\"ray://1.23.199.255:10001\")\n</code></pre>"},{"location":"integrations/prefect-ray/#specifying-remote-options","title":"Specifying remote options","text":"<p>The <code>remote_options</code> context can be used to control the task\u2019s remote options.</p> <p>For example, we can set the number of CPUs and GPUs to use for the <code>process</code> task:</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\nfrom prefect_ray.context import remote_options\n\n@task\ndef process(x):\n    return x + 1\n\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    # equivalent to setting @ray.remote(num_cpus=4, num_gpus=2)\n    with remote_options(num_cpus=4, num_gpus=2):\n        process.submit(42)\n</code></pre>"},{"location":"integrations/prefect-ray/#resources","title":"Resources","text":"<p>Refer to the prefect-ray API documentation linked in the sidebar to explore all the capabilities of the prefect-ray library.</p> <p>For assistance using Dask, consult the Ray documentation.</p>"},{"location":"integrations/prefect-ray/task-runners/","title":"Task Runners","text":""},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners","title":"<code>prefect_ray.task_runners</code>","text":"<p>Interface and implementations of the Ray Task Runner. Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>import time\n\nfrom prefect import flow, task\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#0\n#1\n#2\n#3\n#4\n#5\n#6\n#7\n#8\n#9\n</code></pre> <p>Switching to a <code>RayTaskRunner</code>: <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_ray import RayTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=RayTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre></p>"},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners.RayTaskRunner","title":"<code>RayTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A parallel task_runner that submits tasks to <code>ray</code>. By default, a temporary Ray cluster is created for the duration of the flow run. Alternatively, if you already have a <code>ray</code> instance running, you can provide the connection URL via the <code>address</code> kwarg. Args:     address (string, optional): Address of a currently running <code>ray</code> instance; if         one is not provided, a temporary instance will be created.     init_kwargs (dict, optional): Additional kwargs to use when calling <code>ray.init</code>. Examples:     Using a temporary local ray cluster:     <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    ...\n</code></pre>     Connecting to an existing ray instance:     <pre><code>RayTaskRunner(address=\"ray://192.0.2.255:8786\")\n</code></pre></p> Source code in <code>prefect_ray/task_runners.py</code> <pre><code>class RayTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A parallel task_runner that submits tasks to `ray`.\n    By default, a temporary Ray cluster is created for the duration of the flow run.\n    Alternatively, if you already have a `ray` instance running, you can provide\n    the connection URL via the `address` kwarg.\n    Args:\n        address (string, optional): Address of a currently running `ray` instance; if\n            one is not provided, a temporary instance will be created.\n        init_kwargs (dict, optional): Additional kwargs to use when calling `ray.init`.\n    Examples:\n        Using a temporary local ray cluster:\n        ```python\n        from prefect import flow\n        from prefect_ray.task_runners import RayTaskRunner\n\n        @flow(task_runner=RayTaskRunner())\n        def my_flow():\n            ...\n        ```\n        Connecting to an existing ray instance:\n        ```python\n        RayTaskRunner(address=\"ray://192.0.2.255:8786\")\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        address: str = None,\n        init_kwargs: dict = None,\n    ):\n        # Store settings\n        self.address = address\n        self.init_kwargs = init_kwargs.copy() if init_kwargs else {}\n\n        self.init_kwargs.setdefault(\"namespace\", \"prefect\")\n\n        # Runtime attributes\n        self._ray_refs: Dict[str, \"ray.ObjectRef\"] = {}\n\n        super().__init__()\n\n    def duplicate(self):\n        \"\"\"\n        Return a new instance of with the same settings as this one.\n        \"\"\"\n        return type(self)(address=self.address, init_kwargs=self.init_kwargs)\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Check if an instance has the same settings as this task runner.\n        \"\"\"\n        if type(self) == type(other):\n            return (\n                self.address == other.address and self.init_kwargs == other.init_kwargs\n            )\n        else:\n            return NotImplemented\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.PARALLEL\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        call_kwargs, upstream_ray_obj_refs = self._exchange_prefect_for_ray_futures(\n            call.keywords\n        )\n\n        remote_options = RemoteOptionsContext.get().current_remote_options\n        # Ray does not support the submission of async functions and we must create a\n        # sync entrypoint\n        if remote_options:\n            ray_decorator = ray.remote(**remote_options)\n        else:\n            ray_decorator = ray.remote\n\n        self._ray_refs[key] = (\n            ray_decorator(self._run_prefect_task)\n            .options(name=call.keywords[\"task_run\"].name)\n            .remote(sync_compatible(call.func), *upstream_ray_obj_refs, **call_kwargs)\n        )\n\n    def _exchange_prefect_for_ray_futures(self, kwargs_prefect_futures):\n        \"\"\"Exchanges Prefect futures for Ray futures.\"\"\"\n\n        upstream_ray_obj_refs = []\n\n        def exchange_prefect_for_ray_future(expr):\n            \"\"\"Exchanges Prefect future for Ray future.\"\"\"\n            if isinstance(expr, PrefectFuture):\n                ray_future = self._ray_refs.get(expr.key)\n                if ray_future is not None:\n                    upstream_ray_obj_refs.append(ray_future)\n                    return ray_future\n            return expr\n\n        kwargs_ray_futures = visit_collection(\n            kwargs_prefect_futures,\n            visit_fn=exchange_prefect_for_ray_future,\n            return_data=True,\n        )\n\n        return kwargs_ray_futures, upstream_ray_obj_refs\n\n    @staticmethod\n    def _run_prefect_task(func, *upstream_ray_obj_refs, **kwargs):\n        \"\"\"Resolves Ray futures before calling the actual Prefect task function.\n\n        Passing upstream_ray_obj_refs directly as args enables Ray to wait for\n        upstream tasks before running this remote function.\n        This variable is otherwise unused as the ray object refs are also\n        contained in kwargs.\n        \"\"\"\n\n        def resolve_ray_future(expr):\n            \"\"\"Resolves Ray future.\"\"\"\n            if isinstance(expr, ray.ObjectRef):\n                return ray.get(expr)\n            return expr\n\n        kwargs = visit_collection(kwargs, visit_fn=resolve_ray_future, return_data=True)\n\n        return func(**kwargs)\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        ref = self._get_ray_ref(key)\n\n        result = None\n\n        with anyio.move_on_after(timeout):\n            # We await the reference directly instead of using `ray.get` so we can\n            # avoid blocking the event loop\n            try:\n                result = await ref\n            except RayTaskError as exc:\n                # unwrap the original exception that caused task failure, except for\n                # KeyboardInterrupt, which unwraps as TaskCancelledError\n                result = await exception_to_crashed_state(exc.cause)\n            except BaseException as exc:\n                result = await exception_to_crashed_state(exc)\n\n        return result\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the task runner and prep for context exit.\n\n        - Creates a cluster if an external address is not set.\n        - Creates a client to connect to the cluster.\n        - Pushes a call to wait for all running futures to complete on exit.\n        \"\"\"\n        if self.address and self.address != \"auto\":\n            self.logger.info(\n                f\"Connecting to an existing Ray instance at {self.address}\"\n            )\n            init_args = (self.address,)\n        elif ray.is_initialized():\n            self.logger.info(\n                \"Local Ray instance is already initialized. \"\n                \"Using existing local instance.\"\n            )\n            return\n        else:\n            self.logger.info(\"Creating a local Ray instance\")\n            init_args = ()\n\n        context = ray.init(*init_args, **self.init_kwargs)\n        dashboard_url = getattr(context, \"dashboard_url\", None)\n        exit_stack.push(context)\n\n        # Display some information about the cluster\n        nodes = ray.nodes()\n        living_nodes = [node for node in nodes if node.get(\"alive\")]\n        self.logger.info(f\"Using Ray cluster with {len(living_nodes)} nodes.\")\n\n        if dashboard_url:\n            self.logger.info(\n                f\"The Ray UI is available at {dashboard_url}\",\n            )\n\n    async def _shutdown_ray(self):\n        \"\"\"\n        Shuts down the cluster.\n        \"\"\"\n        self.logger.debug(\"Shutting down Ray cluster...\")\n        ray.shutdown()\n\n    def _get_ray_ref(self, key: UUID) -&gt; \"ray.ObjectRef\":\n        \"\"\"\n        Retrieve the ray object reference corresponding to a prefect future.\n        \"\"\"\n        return self._ray_refs[key]\n</code></pre>"},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners.RayTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Return a new instance of with the same settings as this one.</p> Source code in <code>prefect_ray/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Return a new instance of with the same settings as this one.\n    \"\"\"\n    return type(self)(address=self.address, init_kwargs=self.init_kwargs)\n</code></pre>"},{"location":"integrations/prefect-shell/","title":"prefect-shell","text":"<p>Execute shell commands from within Prefect flows.</p>"},{"location":"integrations/prefect-shell/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-shell/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> </ul>"},{"location":"integrations/prefect-shell/#install-prefect-shell","title":"Install <code>prefect-shell</code>","text":"<pre><code>pip install -U prefect-shell\n</code></pre>"},{"location":"integrations/prefect-shell/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-aws module to make them available for use.</p> <pre><code>prefect block register -m prefect_shell\n</code></pre>"},{"location":"integrations/prefect-shell/#examples","title":"Examples","text":""},{"location":"integrations/prefect-shell/#integrate-shell-commands-with-prefect-flows","title":"Integrate shell commands with Prefect flows","text":"<p>With prefect-shell, you can use shell commands (and/or scripts) in Prefect flows to provide observability and resiliency. Prefect-shell can be a useful tool if you're transitioning your orchestration from shell scripts to Prefect.</p> <p>Let's get the shell-abration started!</p> <p>The Python code below has shell commands embedded in a Prefect flow:</p> <pre><code>from prefect import flow\nfrom datetime import datetime\nfrom prefect_shell import ShellOperation\n\n\n@flow\ndef download_data():\n    today = datetime.today().strftime(\"%Y%m%d\")\n\n    # for short running operations, you can use the `run` method\n    # which automatically manages the context\n    ShellOperation(\n        commands=[\n            \"mkdir -p data\",\n            \"mkdir -p data/${today}\"\n        ],\n        env={\"today\": today}\n    ).run()\n\n    # for long running operations, you can use a context manager\n    with ShellOperation(\n        commands=[\n            \"curl -O https://masie_web.apps.nsidc.org/pub/DATASETS/NOAA/G02135/north/daily/data/N_seaice_extent_daily_v3.0.csv\",\n        ],\n        working_dir=f\"data/{today}\",\n    ) as download_csv_operation:\n\n        # trigger runs the process in the background\n        download_csv_process = download_csv_operation.trigger()\n\n        # then do other things here in the meantime, like download another file\n        ...\n\n        # when you're ready, wait for the process to finish\n        download_csv_process.wait_for_completion()\n\n        # if you'd like to get the output lines, you can use the `fetch_result` method\n        output_lines = download_csv_process.fetch_result()\n\n\nif __name__ == \"__main__\":\n    download_data()\n</code></pre> <p>Running this script results in output like this:</p> <pre><code>14:48:16.550 | INFO    | prefect.engine - Created flow run 'tentacled-chachalaca' for flow 'download-data'\n14:48:17.977 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 triggered with 2 commands running inside the '.' directory.\n14:48:17.987 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 completed with return code 0.\n14:48:17.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 triggered with 1 commands running inside the PosixPath('data/20230201') directory.\n14:48:18.009 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                 Dl\n14:48:18.010 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\noad  Upload   Total   Spent    Left  Speed\n  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n14:48:18.840 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n 11 1630k   11  192k    0     0   229k      0  0:00:07 --:--:--  0:00:07  231k\n14:48:19.839 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n 83 1630k   83 1368k    0     0   745k      0  0:00:02  0:00:01  0:00:01  747k\n14:48:19.993 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n100 1630k  100 1630k    0     0   819k      0  0\n14:48:19.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n:00:01  0:00:01 --:--:--  821k\n14:48:19.996 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 completed with return code 0.\n14:48:19.998 | INFO    | Flow run 'tentacled-chachalaca' - Successfully closed all open processes.\n14:48:20.203 | INFO    | Flow run 'tentacled-chachalaca' - Finished in state Completed()\n</code></pre>"},{"location":"integrations/prefect-shell/#save-shell-commands-in-prefect-blocks","title":"Save shell commands in Prefect Blocks","text":"<p>You can save commands within a <code>ShellOperation</code> block, then reuse them across multiple flows.</p> <p>Save the block with desired commands:</p> <pre><code>from prefect_shell import ShellOperation\n\n\nping_op = ShellOperation(commands=[\"ping -t 1 prefect.io\"])\nping_op.save(\"block-name\")\n\n# Load the saved block:\nping_op = ShellOperation.load(\"block-name\")\n</code></pre>"},{"location":"integrations/prefect-shell/#resources","title":"Resources","text":"<p>Refer to the prefect-shell API documentation linked in the sidebar to explore all the capabilities of the prefect-shell library.</p>"},{"location":"integrations/prefect-shell/commands/","title":"Commands","text":""},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands","title":"<code>prefect_shell.commands</code>","text":"<p>Tasks for interacting with shell commands</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation","title":"<code>ShellOperation</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>A block representing a shell operation, containing multiple commands.</p> <p>For long-lasting operations, use the trigger method and utilize the block as a context manager for automatic closure of processes when context is exited. If not, manually call the close method to close processes.</p> <p>For short-lasting operations, use the run method. Context is automatically managed with this method.</p> <p>Attributes:</p> Name Type Description <code>commands</code> <code>List[str]</code> <p>A list of commands to execute sequentially.</p> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>env</code> <code>Dict[str, str]</code> <p>A dictionary of environment variables to set for the shell operation.</p> <code>working_dir</code> <code>DirectoryPath</code> <p>The working directory context the commands will be executed within.</p> <code>shell</code> <code>str</code> <p>The shell to use to execute the commands.</p> <code>extension</code> <code>Optional[str]</code> <p>The extension to use for the temporary file. if unset defaults to <code>.ps1</code> on Windows and <code>.sh</code> on other platforms.</p> <p>Examples:</p> <p>Load a configured block: <pre><code>from prefect_shell import ShellOperation\n\nshell_operation = ShellOperation.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>class ShellOperation(JobBlock):\n    \"\"\"\n    A block representing a shell operation, containing multiple commands.\n\n    For long-lasting operations, use the trigger method and utilize the block as a\n    context manager for automatic closure of processes when context is exited.\n    If not, manually call the close method to close processes.\n\n    For short-lasting operations, use the run method. Context is automatically managed\n    with this method.\n\n    Attributes:\n        commands: A list of commands to execute sequentially.\n        stream_output: Whether to stream output.\n        env: A dictionary of environment variables to set for the shell operation.\n        working_dir: The working directory context the commands\n            will be executed within.\n        shell: The shell to use to execute the commands.\n        extension: The extension to use for the temporary file.\n            if unset defaults to `.ps1` on Windows and `.sh` on other platforms.\n\n    Examples:\n        Load a configured block:\n        ```python\n        from prefect_shell import ShellOperation\n\n        shell_operation = ShellOperation.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Shell Operation\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/0b47a017e1b40381de770c17647c49cdf6388d1c-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-shell/commands/#prefect_shell.commands.ShellOperation\"  # noqa: E501\n\n    commands: List[str] = Field(\n        default=..., description=\"A list of commands to execute sequentially.\"\n    )\n    stream_output: bool = Field(default=True, description=\"Whether to stream output.\")\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to use for the subprocess.\",\n    )\n    working_dir: DirectoryPath = Field(\n        default=None,\n        title=\"Working Directory\",\n        description=(\n            \"The absolute path to the working directory \"\n            \"the command will be executed within.\"\n        ),\n    )\n    shell: str = Field(\n        default=None,\n        description=(\n            \"The shell to run the command with; if unset, \"\n            \"defaults to `powershell` on Windows and `bash` on other platforms.\"\n        ),\n    )\n    extension: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The extension to use for the temporary file; if unset, \"\n            \"defaults to `.ps1` on Windows and `.sh` on other platforms.\"\n        ),\n    )\n\n    _exit_stack: AsyncExitStack = PrivateAttr(\n        default_factory=AsyncExitStack,\n    )\n\n    @contextmanager\n    def _prep_trigger_command(self) -&gt; Generator[str, None, None]:\n        \"\"\"\n        Write the commands to a temporary file, handling all the details of\n        creating the file and cleaning it up afterwards. Then, return the command\n        to run the temporary file.\n        \"\"\"\n        try:\n            extension = self.extension or (\".ps1\" if sys.platform == \"win32\" else \".sh\")\n            temp_file = tempfile.NamedTemporaryFile(\n                prefix=\"prefect-\",\n                suffix=extension,\n                delete=False,\n            )\n\n            joined_commands = os.linesep.join(self.commands)\n            self.logger.debug(\n                f\"Writing the following commands to \"\n                f\"{temp_file.name!r}:{os.linesep}{joined_commands}\"\n            )\n            temp_file.write(joined_commands.encode())\n\n            if self.shell is None and sys.platform == \"win32\" or extension == \".ps1\":\n                shell = \"powershell\"\n            elif self.shell is None:\n                shell = \"bash\"\n            else:\n                shell = self.shell.lower()\n\n            if shell == \"powershell\":\n                # if powershell, set exit code to that of command\n                temp_file.write(\"\\r\\nExit $LastExitCode\".encode())\n            temp_file.close()\n\n            trigger_command = [shell, temp_file.name]\n            yield trigger_command\n        finally:\n            if os.path.exists(temp_file.name):\n                os.remove(temp_file.name)\n\n    def _compile_kwargs(self, **open_kwargs: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Helper method to compile the kwargs for `open_process` so it's not repeated\n        across the run and trigger methods.\n        \"\"\"\n        trigger_command = self._exit_stack.enter_context(self._prep_trigger_command())\n        input_env = os.environ.copy()\n        input_env.update(self.env)\n        input_open_kwargs = dict(\n            command=trigger_command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.PIPE,\n            env=input_env,\n            cwd=self.working_dir,\n            **open_kwargs,\n        )\n        return input_open_kwargs\n\n    @sync_compatible\n    async def trigger(self, **open_kwargs: Dict[str, Any]) -&gt; ShellProcess:\n        \"\"\"\n        Triggers a shell command and returns the shell command run object\n        to track the execution of the run. This method is ideal for long-lasting\n        shell commands; for short-lasting shell commands, it is recommended\n        to use the `run` method instead.\n\n        Args:\n            **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n        Returns:\n            A `ShellProcess` object.\n\n        Examples:\n            Sleep for 5 seconds and then print \"Hello, world!\":\n            ```python\n            from prefect_shell import ShellOperation\n\n            with ShellOperation(\n                commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n            ) as shell_operation:\n                shell_process = shell_operation.trigger()\n                shell_process.wait_for_completion()\n                shell_output = shell_process.fetch_result()\n            ```\n        \"\"\"\n        input_open_kwargs = self._compile_kwargs(**open_kwargs)\n        process = await self._exit_stack.enter_async_context(\n            open_process(**input_open_kwargs)\n        )\n        num_commands = len(self.commands)\n        self.logger.info(\n            f\"PID {process.pid} triggered with {num_commands} commands running \"\n            f\"inside the {(self.working_dir or '.')!r} directory.\"\n        )\n        return ShellProcess(shell_operation=self, process=process)\n\n    @sync_compatible\n    async def run(self, **open_kwargs: Dict[str, Any]) -&gt; List[str]:\n        \"\"\"\n        Runs a shell command, but unlike the trigger method,\n        additionally waits and fetches the result directly, automatically managing\n        the context. This method is ideal for short-lasting shell commands;\n        for long-lasting shell commands, it is\n        recommended to use the `trigger` method instead.\n\n        Args:\n            **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n        Returns:\n            The lines output from the shell command as a list.\n\n        Examples:\n            Sleep for 5 seconds and then print \"Hello, world!\":\n            ```python\n            from prefect_shell import ShellOperation\n\n            shell_output = ShellOperation(\n                commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n            ).run()\n            ```\n        \"\"\"\n        input_open_kwargs = self._compile_kwargs(**open_kwargs)\n        async with open_process(**input_open_kwargs) as process:\n            shell_process = ShellProcess(shell_operation=self, process=process)\n            num_commands = len(self.commands)\n            self.logger.info(\n                f\"PID {process.pid} triggered with {num_commands} commands running \"\n                f\"inside the {(self.working_dir or '.')!r} directory.\"\n            )\n            await shell_process.wait_for_completion()\n            result = await shell_process.fetch_result()\n\n        return result\n\n    @sync_compatible\n    async def close(self):\n        \"\"\"\n        Close the job block.\n        \"\"\"\n        await self._exit_stack.aclose()\n        self.logger.info(\"Successfully closed all open processes.\")\n\n    async def aclose(self):\n        \"\"\"\n        Asynchronous version of the close method.\n        \"\"\"\n        await self.close()\n\n    async def __aenter__(self) -&gt; \"ShellOperation\":\n        \"\"\"\n        Asynchronous version of the enter method.\n        \"\"\"\n        return self\n\n    async def __aexit__(self, *exc_info):\n        \"\"\"\n        Asynchronous version of the exit method.\n        \"\"\"\n        await self.close()\n\n    def __enter__(self) -&gt; \"ShellOperation\":\n        \"\"\"\n        Enter the context of the job block.\n        \"\"\"\n        return self\n\n    def __exit__(self, *exc_info):\n        \"\"\"\n        Exit the context of the job block.\n        \"\"\"\n        self.close()\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.aclose","title":"<code>aclose</code>  <code>async</code>","text":"<p>Asynchronous version of the close method.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>async def aclose(self):\n    \"\"\"\n    Asynchronous version of the close method.\n    \"\"\"\n    await self.close()\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.close","title":"<code>close</code>  <code>async</code>","text":"<p>Close the job block.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def close(self):\n    \"\"\"\n    Close the job block.\n    \"\"\"\n    await self._exit_stack.aclose()\n    self.logger.info(\"Successfully closed all open processes.\")\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs a shell command, but unlike the trigger method, additionally waits and fetches the result directly, automatically managing the context. This method is ideal for short-lasting shell commands; for long-lasting shell commands, it is recommended to use the <code>trigger</code> method instead.</p> <p>Parameters:</p> Name Type Description Default <code>**open_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>open_process</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>The lines output from the shell command as a list.</p> <p>Examples:</p> <p>Sleep for 5 seconds and then print \"Hello, world!\": <pre><code>from prefect_shell import ShellOperation\n\nshell_output = ShellOperation(\n    commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n).run()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def run(self, **open_kwargs: Dict[str, Any]) -&gt; List[str]:\n    \"\"\"\n    Runs a shell command, but unlike the trigger method,\n    additionally waits and fetches the result directly, automatically managing\n    the context. This method is ideal for short-lasting shell commands;\n    for long-lasting shell commands, it is\n    recommended to use the `trigger` method instead.\n\n    Args:\n        **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n    Returns:\n        The lines output from the shell command as a list.\n\n    Examples:\n        Sleep for 5 seconds and then print \"Hello, world!\":\n        ```python\n        from prefect_shell import ShellOperation\n\n        shell_output = ShellOperation(\n            commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n        ).run()\n        ```\n    \"\"\"\n    input_open_kwargs = self._compile_kwargs(**open_kwargs)\n    async with open_process(**input_open_kwargs) as process:\n        shell_process = ShellProcess(shell_operation=self, process=process)\n        num_commands = len(self.commands)\n        self.logger.info(\n            f\"PID {process.pid} triggered with {num_commands} commands running \"\n            f\"inside the {(self.working_dir or '.')!r} directory.\"\n        )\n        await shell_process.wait_for_completion()\n        result = await shell_process.fetch_result()\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Triggers a shell command and returns the shell command run object to track the execution of the run. This method is ideal for long-lasting shell commands; for short-lasting shell commands, it is recommended to use the <code>run</code> method instead.</p> <p>Parameters:</p> Name Type Description Default <code>**open_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>open_process</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>ShellProcess</code> <p>A <code>ShellProcess</code> object.</p> <p>Examples:</p> <p>Sleep for 5 seconds and then print \"Hello, world!\": <pre><code>from prefect_shell import ShellOperation\n\nwith ShellOperation(\n    commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n) as shell_operation:\n    shell_process = shell_operation.trigger()\n    shell_process.wait_for_completion()\n    shell_output = shell_process.fetch_result()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def trigger(self, **open_kwargs: Dict[str, Any]) -&gt; ShellProcess:\n    \"\"\"\n    Triggers a shell command and returns the shell command run object\n    to track the execution of the run. This method is ideal for long-lasting\n    shell commands; for short-lasting shell commands, it is recommended\n    to use the `run` method instead.\n\n    Args:\n        **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n    Returns:\n        A `ShellProcess` object.\n\n    Examples:\n        Sleep for 5 seconds and then print \"Hello, world!\":\n        ```python\n        from prefect_shell import ShellOperation\n\n        with ShellOperation(\n            commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n        ) as shell_operation:\n            shell_process = shell_operation.trigger()\n            shell_process.wait_for_completion()\n            shell_output = shell_process.fetch_result()\n        ```\n    \"\"\"\n    input_open_kwargs = self._compile_kwargs(**open_kwargs)\n    process = await self._exit_stack.enter_async_context(\n        open_process(**input_open_kwargs)\n    )\n    num_commands = len(self.commands)\n    self.logger.info(\n        f\"PID {process.pid} triggered with {num_commands} commands running \"\n        f\"inside the {(self.working_dir or '.')!r} directory.\"\n    )\n    return ShellProcess(shell_operation=self, process=process)\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess","title":"<code>ShellProcess</code>","text":"<p>               Bases: <code>JobRun</code></p> <p>A class representing a shell process.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>class ShellProcess(JobRun):\n    \"\"\"\n    A class representing a shell process.\n    \"\"\"\n\n    def __init__(self, shell_operation: \"ShellOperation\", process: Process):\n        self._shell_operation = shell_operation\n        self._process = process\n        self._output = []\n\n    @property\n    def pid(self) -&gt; int:\n        \"\"\"\n        The PID of the process.\n\n        Returns:\n            The PID of the process.\n        \"\"\"\n        return self._process.pid\n\n    @property\n    def return_code(self) -&gt; Optional[int]:\n        \"\"\"\n        The return code of the process.\n\n        Returns:\n            The return code of the process, or `None` if the process is still running.\n        \"\"\"\n        return self._process.returncode\n\n    async def _capture_output(self, source):\n        \"\"\"\n        Capture output from source.\n        \"\"\"\n        async for output in TextReceiveStream(source):\n            text = output.rstrip()\n            if self._shell_operation.stream_output:\n                self.logger.info(f\"PID {self.pid} stream output:{os.linesep}{text}\")\n            self._output.extend(text.split(os.linesep))\n\n    @sync_compatible\n    async def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Wait for the shell command to complete after a process is triggered.\n        \"\"\"\n        self.logger.debug(f\"Waiting for PID {self.pid} to complete.\")\n\n        await asyncio.gather(\n            self._capture_output(self._process.stdout),\n            self._capture_output(self._process.stderr),\n        )\n        await self._process.wait()\n\n        if self.return_code != 0:\n            raise RuntimeError(\n                f\"PID {self.pid} failed with return code {self.return_code}.\"\n            )\n        self.logger.info(\n            f\"PID {self.pid} completed with return code {self.return_code}.\"\n        )\n\n    @sync_compatible\n    async def fetch_result(self) -&gt; List[str]:\n        \"\"\"\n        Retrieve the output of the shell operation.\n\n        Returns:\n            The lines output from the shell operation as a list.\n        \"\"\"\n        if self._process.returncode is None:\n            self.logger.info(\"Process is still running, result may be incomplete.\")\n        return self._output\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.pid","title":"<code>pid: int</code>  <code>property</code>","text":"<p>The PID of the process.</p> <p>Returns:</p> Type Description <code>int</code> <p>The PID of the process.</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.return_code","title":"<code>return_code: Optional[int]</code>  <code>property</code>","text":"<p>The return code of the process.</p> <p>Returns:</p> Type Description <code>Optional[int]</code> <p>The return code of the process, or <code>None</code> if the process is still running.</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Retrieve the output of the shell operation.</p> <p>Returns:</p> Type Description <code>List[str]</code> <p>The lines output from the shell operation as a list.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self) -&gt; List[str]:\n    \"\"\"\n    Retrieve the output of the shell operation.\n\n    Returns:\n        The lines output from the shell operation as a list.\n    \"\"\"\n    if self._process.returncode is None:\n        self.logger.info(\"Process is still running, result may be incomplete.\")\n    return self._output\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Wait for the shell command to complete after a process is triggered.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Wait for the shell command to complete after a process is triggered.\n    \"\"\"\n    self.logger.debug(f\"Waiting for PID {self.pid} to complete.\")\n\n    await asyncio.gather(\n        self._capture_output(self._process.stdout),\n        self._capture_output(self._process.stderr),\n    )\n    await self._process.wait()\n\n    if self.return_code != 0:\n        raise RuntimeError(\n            f\"PID {self.pid} failed with return code {self.return_code}.\"\n        )\n    self.logger.info(\n        f\"PID {self.pid} completed with return code {self.return_code}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.shell_run_command","title":"<code>shell_run_command</code>  <code>async</code>","text":"<p>Runs arbitrary shell commands.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>Shell command to be executed; can also be provided post-initialization by calling this task instance.</p> required <code>env</code> <code>Optional[dict]</code> <p>Dictionary of environment variables to use for the subprocess; can also be provided at runtime.</p> <code>None</code> <code>helper_command</code> <code>Optional[str]</code> <p>String representing a shell command, which will be executed prior to the <code>command</code> in the same process. Can be used to change directories, define helper functions, etc. for different commands in a flow.</p> <code>None</code> <code>shell</code> <code>Optional[str]</code> <p>Shell to run the command with.</p> <code>None</code> <code>extension</code> <code>Optional[str]</code> <p>File extension to be appended to the command to be executed.</p> <code>None</code> <code>return_all</code> <code>bool</code> <p>Whether this task should return all lines of stdout as a list, or just the last line as a string.</p> <code>False</code> <code>stream_level</code> <code>int</code> <p>The logging level of the stream; defaults to 20 equivalent to <code>logging.INFO</code>.</p> <code>INFO</code> <code>cwd</code> <code>Union[str, bytes, PathLike, None]</code> <p>The working directory context the command will be executed within</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[List, str]</code> <p>If return all, returns all lines as a list; else the last line as a string.</p> Example <p>List contents in the current directory. <pre><code>from prefect import flow\nfrom prefect_shell import shell_run_command\n\n@flow\ndef example_shell_run_command_flow():\n    return shell_run_command(command=\"ls .\", return_all=True)\n\nexample_shell_run_command_flow()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@task\nasync def shell_run_command(\n    command: str,\n    env: Optional[dict] = None,\n    helper_command: Optional[str] = None,\n    shell: Optional[str] = None,\n    extension: Optional[str] = None,\n    return_all: bool = False,\n    stream_level: int = logging.INFO,\n    cwd: Union[str, bytes, os.PathLike, None] = None,\n) -&gt; Union[List, str]:\n    \"\"\"\n    Runs arbitrary shell commands.\n\n    Args:\n        command: Shell command to be executed; can also be\n            provided post-initialization by calling this task instance.\n        env: Dictionary of environment variables to use for\n            the subprocess; can also be provided at runtime.\n        helper_command: String representing a shell command, which\n            will be executed prior to the `command` in the same process.\n            Can be used to change directories, define helper functions, etc.\n            for different commands in a flow.\n        shell: Shell to run the command with.\n        extension: File extension to be appended to the command to be executed.\n        return_all: Whether this task should return all lines of stdout as a list,\n            or just the last line as a string.\n        stream_level: The logging level of the stream;\n            defaults to 20 equivalent to `logging.INFO`.\n        cwd: The working directory context the command will be executed within\n\n    Returns:\n        If return all, returns all lines as a list; else the last line as a string.\n\n    Example:\n        List contents in the current directory.\n        ```python\n        from prefect import flow\n        from prefect_shell import shell_run_command\n\n        @flow\n        def example_shell_run_command_flow():\n            return shell_run_command(command=\"ls .\", return_all=True)\n\n        example_shell_run_command_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    current_env = os.environ.copy()\n    current_env.update(env or {})\n\n    if shell is None:\n        # if shell is not specified:\n        # use powershell for windows\n        # use bash for other platforms\n        shell = \"powershell\" if sys.platform == \"win32\" else \"bash\"\n\n    extension = \".ps1\" if shell.lower() == \"powershell\" else extension\n\n    tmp = tempfile.NamedTemporaryFile(prefix=\"prefect-\", suffix=extension, delete=False)\n    try:\n        if helper_command:\n            tmp.write(helper_command.encode())\n            tmp.write(os.linesep.encode())\n        tmp.write(command.encode())\n        if shell.lower() == \"powershell\":\n            # if powershell, set exit code to that of command\n            tmp.write(\"\\r\\nExit $LastExitCode\".encode())\n        tmp.close()\n\n        shell_command = [shell, tmp.name]\n\n        lines = []\n        async with await anyio.open_process(\n            shell_command, env=current_env, cwd=cwd\n        ) as process:\n            async for text in TextReceiveStream(process.stdout):\n                logger.log(level=stream_level, msg=text)\n                lines.extend(text.rstrip().split(\"\\n\"))\n\n            await process.wait()\n            if process.returncode:\n                stderr = \"\\n\".join(\n                    [text async for text in TextReceiveStream(process.stderr)]\n                )\n                if not stderr and lines:\n                    stderr = f\"{lines[-1]}\\n\"\n                msg = (\n                    f\"Command failed with exit code {process.returncode}:\\n\" f\"{stderr}\"\n                )\n                raise RuntimeError(msg)\n    finally:\n        if os.path.exists(tmp.name):\n            os.remove(tmp.name)\n\n    line = lines[-1] if lines else \"\"\n    return lines if return_all else line\n</code></pre>"},{"location":"integrations/prefect-slack/","title":"prefect-slack","text":""},{"location":"integrations/prefect-slack/#welcome","title":"Welcome!","text":"<p><code>prefect-slack</code> is a collection of prebuilt Prefect tasks that can be used to quickly construct Prefect flows.</p>"},{"location":"integrations/prefect-slack/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-slack/#python-setup","title":"Python setup","text":"<p>Requires an installation of Python 3.8+</p> <p>We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.</p> <p>These tasks are designed to work with Prefect 2.0. For more information about how to use Prefect, please refer to the Prefect documentation.</p>"},{"location":"integrations/prefect-slack/#installation","title":"Installation","text":"<p>Install <code>prefect-slack</code></p> <pre><code>pip install prefect-slack\n</code></pre>"},{"location":"integrations/prefect-slack/#slack-setup","title":"Slack setup","text":"<p>In order to use tasks in the collection, you'll first need to create an Slack app and install it in your Slack workspace. You can create a Slack app by navigating to the apps page for your Slack account and selecting 'Create New App'.</p> <p>For tasks that require a Bot user OAuth token, you can get a token for your app by navigating to your apps OAuth &amp; Permissions page.</p> <p>For tasks that require and Webhook URL, you get generate new Webhook URLs by navigating to you apps Incoming Webhooks page.</p> <p>Slack's Basic app setup guide provides additional details on setting up a Slack app.</p>"},{"location":"integrations/prefect-slack/#write-and-run-a-flow","title":"Write and run a flow","text":"<pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_slack import SlackCredentials\nfrom prefect_slack.messages import send_chat_message\n\n\n@flow\ndef example_send_message_flow():\n   context = get_run_context()\n\n   # Run other tasks and subflows here\n\n   token = \"xoxb-your-bot-token-here\"\n   send_chat_message(\n         slack_credentials=SlackCredentials(token),\n         channel=\"#prefect\",\n         text=f\"Flow run {context.flow_run.name} completed :tada:\"\n   )\n\nexample_send_message_flow()\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials","title":"<code>prefect_slack.credentials</code>","text":"<p>Credential classes use to store Slack credentials.</p>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials","title":"<code>SlackCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block holding Slack credentials for use in tasks and flows.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <p>Bot user OAuth token for the Slack app used to perform actions.</p> required <p>Examples:</p> <p>Load stored Slack credentials: <pre><code>from prefect_slack import SlackCredentials\nslack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Get a Slack client: <pre><code>from prefect_slack import SlackCredentials\nslack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\nclient = slack_credentials_block.get_client()\n</code></pre></p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>class SlackCredentials(Block):\n    \"\"\"\n    Block holding Slack credentials for use in tasks and flows.\n\n    Args:\n        token: Bot user OAuth token for the Slack app used to perform actions.\n\n    Examples:\n        Load stored Slack credentials:\n        ```python\n        from prefect_slack import SlackCredentials\n        slack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n        ```\n\n        Get a Slack client:\n        ```python\n        from prefect_slack import SlackCredentials\n        slack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n        client = slack_credentials_block.get_client()\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Slack Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c1965ecbf8704ee1ea20d77786de9a41ce1087d1-500x500.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials\"  # noqa\n\n    token: SecretStr = Field(\n        default=...,\n        description=\"Bot user OAuth token for the Slack app used to perform actions.\",\n    )\n\n    def get_client(self) -&gt; AsyncWebClient:\n        \"\"\"\n        Returns an authenticated `AsyncWebClient` to interact with the Slack API.\n        \"\"\"\n        return AsyncWebClient(token=self.token.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated <code>AsyncWebClient</code> to interact with the Slack API.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncWebClient:\n    \"\"\"\n    Returns an authenticated `AsyncWebClient` to interact with the Slack API.\n    \"\"\"\n    return AsyncWebClient(token=self.token.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook","title":"<code>SlackWebhook</code>","text":"<p>               Bases: <code>NotificationBlock</code></p> <p>Block holding a Slack webhook for use in tasks and flows.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <p>Slack webhook URL which can be used to send messages (e.g. <code>https://hooks.slack.com/XXX</code>).</p> required <p>Examples:</p> <p>Load stored Slack webhook: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Get a Slack webhook client: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nclient = slack_webhook_block.get_client()\n</code></pre></p> <p>Send a notification in Slack: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nslack_webhook_block.notify(\"Hello, world!\")\n</code></pre></p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>class SlackWebhook(NotificationBlock):\n    \"\"\"\n    Block holding a Slack webhook for use in tasks and flows.\n\n    Args:\n        url: Slack webhook URL which can be used to send messages\n            (e.g. `https://hooks.slack.com/XXX`).\n\n    Examples:\n        Load stored Slack webhook:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        ```\n\n        Get a Slack webhook client:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        client = slack_webhook_block.get_client()\n        ```\n\n        Send a notification in Slack:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        slack_webhook_block.notify(\"Hello, world!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Slack Incoming Webhook\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/7dkzINU9r6j44giEFuHuUC/85d4cd321ad60c1b1e898bc3fbd28580/5cb480cd5f1b6d3fbadece79.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook\"  # noqa\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Slack webhook URL which can be used to send messages.\",\n        example=\"https://hooks.slack.com/XXX\",\n    )\n\n    def get_client(self) -&gt; AsyncWebhookClient:\n        \"\"\"\n        Returns an authenticated `AsyncWebhookClient` to interact with the configured\n        Slack webhook.\n        \"\"\"\n        return AsyncWebhookClient(url=self.url.get_secret_value())\n\n    @sync_compatible\n    async def notify(self, body: str, subject: Optional[str] = None):\n        \"\"\"\n        Sends a message to the Slack channel.\n        \"\"\"\n        client = self.get_client()\n\n        response = await client.send(text=body)\n\n        # prefect&gt;=2.17.2 added a means for notification blocks to raise errors on\n        # failures. This is not available in older versions, so we need to check if the\n        # private base class attribute exists before using it.\n        if getattr(self, \"_raise_on_failure\", False):  # pragma: no cover\n            try:\n                from prefect.blocks.abstract import NotificationError\n            except ImportError:\n                NotificationError = Exception\n\n            if response.status_code &gt;= 400:\n                raise NotificationError(f\"Failed to send message: {response.body}\")\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated <code>AsyncWebhookClient</code> to interact with the configured Slack webhook.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncWebhookClient:\n    \"\"\"\n    Returns an authenticated `AsyncWebhookClient` to interact with the configured\n    Slack webhook.\n    \"\"\"\n    return AsyncWebhookClient(url=self.url.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook.notify","title":"<code>notify</code>  <code>async</code>","text":"<p>Sends a message to the Slack channel.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>@sync_compatible\nasync def notify(self, body: str, subject: Optional[str] = None):\n    \"\"\"\n    Sends a message to the Slack channel.\n    \"\"\"\n    client = self.get_client()\n\n    response = await client.send(text=body)\n\n    # prefect&gt;=2.17.2 added a means for notification blocks to raise errors on\n    # failures. This is not available in older versions, so we need to check if the\n    # private base class attribute exists before using it.\n    if getattr(self, \"_raise_on_failure\", False):  # pragma: no cover\n        try:\n            from prefect.blocks.abstract import NotificationError\n        except ImportError:\n            NotificationError = Exception\n\n        if response.status_code &gt;= 400:\n            raise NotificationError(f\"Failed to send message: {response.body}\")\n</code></pre>"},{"location":"integrations/prefect-slack/messages/","title":"Messages","text":""},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages","title":"<code>prefect_slack.messages</code>","text":"<p>Tasks for sending Slack messages.</p>"},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages.send_chat_message","title":"<code>send_chat_message</code>  <code>async</code>","text":"<p>Sends a message to a Slack channel.</p> <p>Parameters:</p> Name Type Description Default <code>channel</code> <code>str</code> <p>The name of the channel in which to post the chat message (e.g. #general).</p> required <code>slack_credentials</code> <code>SlackCredentials</code> <p>Instance of <code>SlackCredentials</code> initialized with a Slack bot token.</p> required <code>text</code> <code>Optional[str]</code> <p>Contents of the message. It's a best practice to always provide a <code>text</code> argument when posting a message. The <code>text</code> argument is used in places where content cannot be rendered such as: system push notifications, assistive technology such as screen readers, etc.</p> <code>None</code> <code>attachments</code> <code>Optional[Sequence[Union[Dict, Attachment]]]</code> <p>List of objects defining secondary context in the posted Slack message. The Slack API docs provide guidance on building attachments.</p> <code>None</code> <code>slack_blocks</code> <code>Optional[Sequence[Union[Dict, Block]]]</code> <p>List of objects defining the layout and formatting of the posted message. The Slack API docs provide guidance on building messages with blocks.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Dict</code> <code>Dict</code> <p>Response from the Slack API. Example response structures can be found in the Slack API docs.</p> Example <p>Post a message at the end of a flow run.</p> <pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_slack import SlackCredentials\nfrom prefect_slack.messages import send_chat_message\n\n\n@flow\ndef example_send_message_flow():\n    context = get_run_context()\n\n    # Run other tasks and subflows here\n\n    token = \"xoxb-your-bot-token-here\"\n    send_chat_message(\n        slack_credentials=SlackCredentials(token),\n        channel=\"#prefect\",\n        text=f\"Flow run {context.flow_run.name} completed :tada:\"\n    )\n\nexample_send_message_flow()\n</code></pre> Source code in <code>prefect_slack/messages.py</code> <pre><code>@task\nasync def send_chat_message(\n    channel: str,\n    slack_credentials: SlackCredentials,\n    text: Optional[str] = None,\n    attachments: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.attachments.Attachment\"]]\n    ] = None,\n    slack_blocks: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.blocks.Block\"]]\n    ] = None,\n) -&gt; Dict:\n    \"\"\"\n    Sends a message to a Slack channel.\n\n    Args:\n        channel: The name of the channel in which to post the chat message\n            (e.g. #general).\n        slack_credentials: Instance of `SlackCredentials` initialized with a Slack\n            bot token.\n        text: Contents of the message. It's a best practice to always provide a `text`\n            argument when posting a message. The `text` argument is used in places where\n            content cannot be rendered such as: system push notifications, assistive\n            technology such as screen readers, etc.\n        attachments: List of objects defining secondary context in the posted Slack\n            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)\n            provide guidance on building attachments.\n        slack_blocks: List of objects defining the layout and formatting of the posted\n            message. The [Slack API docs](https://api.slack.com/block-kit/building)\n            provide guidance on building messages with blocks.\n\n    Returns:\n        Dict: Response from the Slack API. Example response structures can be found in\n            the [Slack API docs](https://api.slack.com/methods/chat.postMessage#examples).\n\n    Example:\n        Post a message at the end of a flow run.\n\n        ```python\n        from prefect import flow\n        from prefect.context import get_run_context\n        from prefect_slack import SlackCredentials\n        from prefect_slack.messages import send_chat_message\n\n\n        @flow\n        def example_send_message_flow():\n            context = get_run_context()\n\n            # Run other tasks and subflows here\n\n            token = \"xoxb-your-bot-token-here\"\n            send_chat_message(\n                slack_credentials=SlackCredentials(token),\n                channel=\"#prefect\",\n                text=f\"Flow run {context.flow_run.name} completed :tada:\"\n            )\n\n        example_send_message_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Posting chat message to %s\", channel)\n\n    client = slack_credentials.get_client()\n    result = await client.chat_postMessage(\n        channel=channel, text=text, blocks=slack_blocks, attachments=attachments\n    )\n    return result.data\n</code></pre>"},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages.send_incoming_webhook_message","title":"<code>send_incoming_webhook_message</code>  <code>async</code>","text":"<p>Sends a message via an incoming webhook.</p> <p>Parameters:</p> Name Type Description Default <code>slack_webhook</code> <code>SlackWebhook</code> <p>Instance of <code>SlackWebhook</code> initialized with a Slack webhook URL.</p> required <code>text</code> <code>Optional[str]</code> <p>Contents of the message. It's a best practice to always provide a <code>text</code> argument when posting a message. The <code>text</code> argument is used in places where content cannot be rendered such as: system push notifications, assistive technology such as screen readers, etc.</p> <code>None</code> <code>attachments</code> <code>Optional[Sequence[Union[Dict, Attachment]]]</code> <p>List of objects defining secondary context in the posted Slack message. The Slack API docs provide guidance on building attachments.</p> <code>None</code> <code>slack_blocks</code> <code>Optional[Sequence[Union[Dict, Block]]]</code> <p>List of objects defining the layout and formatting of the posted message. The Slack API docs provide guidance on building messages with blocks.</p> <code>None</code> Example <p>Post a message at the end of a flow run.</p> <pre><code>from prefect import flow\nfrom prefect_slack import SlackWebhook\nfrom prefect_slack.messages import send_incoming_webhook_message\n\n\n@flow\ndef example_send_message_flow():\n    # Run other tasks and subflows here\n\n    webhook_url = \"https://hooks.slack.com/XXX\"\n    send_incoming_webhook_message(\n        slack_webhook=SlackWebhook(\n            url=webhook_url\n        ),\n        text=\"Warehouse loading flow completed :sparkles:\"\n    )\n\nexample_send_message_flow()\n</code></pre> Source code in <code>prefect_slack/messages.py</code> <pre><code>@task\nasync def send_incoming_webhook_message(\n    slack_webhook: SlackWebhook,\n    text: Optional[str] = None,\n    attachments: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.attachments.Attachment\"]]\n    ] = None,\n    slack_blocks: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.blocks.Block\"]]\n    ] = None,\n) -&gt; None:\n    \"\"\"\n    Sends a message via an incoming webhook.\n\n    Args:\n        slack_webhook: Instance of `SlackWebhook` initialized with a Slack\n            webhook URL.\n        text: Contents of the message. It's a best practice to always provide a `text`\n            argument when posting a message. The `text` argument is used in places where\n            content cannot be rendered such as: system push notifications, assistive\n            technology such as screen readers, etc.\n        attachments: List of objects defining secondary context in the posted Slack\n            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)\n            provide guidance on building attachments.\n        slack_blocks: List of objects defining the layout and formatting of the posted\n            message. The [Slack API docs](https://api.slack.com/block-kit/building)\n            provide guidance on building messages with blocks.\n\n    Example:\n        Post a message at the end of a flow run.\n\n        ```python\n        from prefect import flow\n        from prefect_slack import SlackWebhook\n        from prefect_slack.messages import send_incoming_webhook_message\n\n\n        @flow\n        def example_send_message_flow():\n            # Run other tasks and subflows here\n\n            webhook_url = \"https://hooks.slack.com/XXX\"\n            send_incoming_webhook_message(\n                slack_webhook=SlackWebhook(\n                    url=webhook_url\n                ),\n                text=\"Warehouse loading flow completed :sparkles:\"\n            )\n\n        example_send_message_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Posting message to provided webhook\")\n\n    client = slack_webhook.get_client()\n    await client.send(text=text, attachments=attachments, blocks=slack_blocks)\n</code></pre>"},{"location":"integrations/prefect-snowflake/","title":"prefect-snowflake","text":""},{"location":"integrations/prefect-snowflake/#welcome","title":"Welcome!","text":"<p>The prefect-snowflake collection makes it easy to connect to a Snowflake database in your Prefect flows. Check out the examples below to get started!</p>"},{"location":"integrations/prefect-snowflake/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-snowflake/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Prefect works with Snowflake by providing dataflow automation for faster, more efficient data pipeline creation, execution, and monitoring.</p> <p>This results in reduced errors, increased confidence in your data, and ultimately, faster insights.</p> <p>To set up a table, use the <code>execute</code> and <code>execute_many</code> methods. Then, use the <code>fetch_many</code> method to retrieve data in a stream until there's no more data.</p> <p>By using the <code>SnowflakeConnector</code> as a context manager, you can make sure that the Snowflake connection and cursors are closed properly after you're done with them.</p> <p>Be sure to install prefect-snowflake, register the blocks, and create a credentials block to run the examples below!</p> SyncAsync <pre><code>from prefect import flow, task\nfrom prefect_snowflake import SnowflakeConnector\n\n\n@task\ndef setup_table(block_name: str) -&gt; None:\n    with SnowflakeConnector.load(block_name) as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n@task\ndef fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with SnowflakeConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\ndef snowflake_flow(block_name: str) -&gt; list:\n    setup_table(block_name)\n    all_rows = fetch_data(block_name)\n    return all_rows\n\n\nif __name__==\"__main__\":\n    snowflake_flow()\n</code></pre> <pre><code>from prefect import flow, task\nfrom prefect_snowflake import SnowflakeConnector\nimport asyncio\n\n@task\nasync def setup_table(block_name: str) -&gt; None:\n    with await SnowflakeConnector.load(block_name) as connector:\n        await connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        await connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n@task\nasync def fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with await SnowflakeConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = await connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\nasync def snowflake_flow(block_name: str) -&gt; list:\n    await setup_table(block_name)\n    all_rows = await fetch_data(block_name)\n    return all_rows\n\n\nif __name__==\"__main__\":\n    asyncio.run(snowflake_flow(\"example\"))\n</code></pre>"},{"location":"integrations/prefect-snowflake/#access-underlying-snowflake-connection","title":"Access underlying Snowflake connection","text":"<p>If the native methods of the block don't meet your requirements, don't worry.</p> <p>You have the option to access the underlying Snowflake connection and utilize its built-in methods as well.</p> <pre><code>import pandas as pd\nfrom prefect import flow\nfrom prefect_snowflake.database import SnowflakeConnector\nfrom snowflake.connector.pandas_tools import write_pandas\n\n@flow\ndef snowflake_write_pandas_flow():\n    connector = SnowflakeConnector.load(\"my-block\")\n    with connector.get_connection() as connection:\n        table_name = \"TABLE_NAME\"\n        ddl = \"NAME STRING, NUMBER INT\"\n        statement = f'CREATE TABLE IF NOT EXISTS {table_name} ({ddl})'\n        with connection.cursor() as cursor:\n            cursor.execute(statement)\n\n        # case sensitivity matters here!\n        df = pd.DataFrame([('Marvin', 42), ('Ford', 88)], columns=['NAME', 'NUMBER'])\n        success, num_chunks, num_rows, _ = write_pandas(\n            conn=connection,\n            df=df,\n            table_name=table_name,\n            database=snowflake_connector.database,\n            schema=snowflake_connector.schema_  # note the \"_\" suffix\n        )\n</code></pre>"},{"location":"integrations/prefect-snowflake/#resources","title":"Resources","text":"<p>For more tips on how to use tasks and flows in an integration, check out Using Collections!</p>"},{"location":"integrations/prefect-snowflake/#installation","title":"Installation","text":"<p>Install <code>prefect-snowflake</code> with <code>pip</code>:</p> <pre><code>pip install prefect-snowflake\n</code></pre>"},{"location":"integrations/prefect-snowflake/#registering-blocks","title":"Registering blocks","text":"<p>Register blocks in this module to make them available for use.</p> <pre><code>prefect block register -m prefect_aws\n</code></pre>"},{"location":"integrations/prefect-snowflake/#saving-credentials-to-block","title":"Saving credentials to block","text":"<p>Note, to use the <code>load</code> method on a block, you must already have a block document saved through code or saved through the UI.</p> <p>Below is a walkthrough on saving a <code>SnowflakeCredentials</code> block through code.</p> <ol> <li>Head over to https://app.snowflake.com/.</li> <li>Login to your Snowflake account, e.g. nh12345.us-east-2.aws, with your username and password.</li> <li>Use those credentials to fill replace the placeholders below.</li> </ol> <pre><code>from prefect_snowflake import SnowflakeCredentials\n\ncredentials = SnowflakeCredentials(\n    account=\"ACCOUNT-PLACEHOLDER\",  # resembles nh12345.us-east-2.aws\n    user=\"USER-PLACEHOLDER\",\n    password=\"PASSWORD-PLACEHOLDER\"\n)\ncredentials.save(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Then, to create a <code>SnowflakeConnector</code> block:</p> <ol> <li>After logging in, click on any worksheet.</li> <li>On the left side, select a database and schema.</li> <li>On the top right, select a warehouse.</li> <li>Create a short script, replacing the placeholders below.</li> </ol> <pre><code>from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector\n\ncredentials = SnowflakeCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n\nconnector = SnowflakeConnector(\n    credentials=credentials,\n    database=\"DATABASE-PLACEHOLDER\",\n    schema=\"SCHEMA-PLACEHOLDER\",\n    warehouse=\"COMPUTE_WH\",\n)\nconnector.save(\"CONNECTOR-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Congrats! You can now easily load the saved block, which holds your credentials and connection info:</p> <pre><code>from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector\n\nSnowflakeCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\nSnowflakeConnector.load(\"CONNECTOR-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Registering blocks</p> <p>Register blocks in this module to view and edit them on Prefect Cloud:</p> <pre><code>prefect block register -m prefect_snowflake\n</code></pre> <p>A list of available blocks in <code>prefect-snowflake</code> and their setup instructions can be found here.</p>"},{"location":"integrations/prefect-snowflake/#feedback","title":"Feedback","text":"<p>If you encounter any bugs while using <code>prefect-snowflake</code>, feel free to open an issue in the prefect repository.</p> <p>If you have any questions or issues while using <code>prefect-snowflake</code>, you can find help in the Prefect Slack community.</p>"},{"location":"integrations/prefect-snowflake/#contributing","title":"Contributing","text":"<p>If you'd like to help contribute to fix an issue or add a feature to <code>prefect-snowflake</code>, please propose changes through a pull request from a fork of the Prefect repository.</p>"},{"location":"integrations/prefect-snowflake/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials","title":"<code>prefect_snowflake.credentials</code>","text":"<p>Credentials block for authenticating with Snowflake.</p>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.InvalidPemFormat","title":"<code>InvalidPemFormat</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Invalid PEM Format Certificate</p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>class InvalidPemFormat(Exception):\n    \"\"\"Invalid PEM Format Certificate\"\"\"\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials","title":"<code>SnowflakeCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with Snowflake.</p> <p>Parameters:</p> Name Type Description Default <code>account</code> <code>str</code> <p>The snowflake account name.</p> required <code>user</code> <code>str</code> <p>The user name used to authenticate.</p> required <code>password</code> <code>SecretStr</code> <p>The password used to authenticate.</p> required <code>private_key</code> <code>SecretStr</code> <p>The PEM used to authenticate.</p> required <code>authenticator</code> <code>str</code> <p>The type of authenticator to use for initializing connection (oauth, externalbrowser, etc); refer to Snowflake documentation for details, and note that <code>externalbrowser</code> will only work in an environment where a browser is available.</p> required <code>token</code> <code>SecretStr</code> <p>The OAuth or JWT Token to provide when authenticator is set to OAuth.</p> required <code>endpoint</code> <code>str</code> <p>The Okta endpoint to use when authenticator is set to <code>okta_endpoint</code>, e.g. <code>https://&lt;okta_account_name&gt;.okta.com</code>.</p> required <code>role</code> <code>str</code> <p>The name of the default role to use.</p> required <code>autocommit</code> <code>bool</code> <p>Whether to automatically commit.</p> required Example <p>Load stored Snowflake credentials: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>class SnowflakeCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with Snowflake.\n\n    Args:\n        account (str): The snowflake account name.\n        user (str): The user name used to authenticate.\n        password (SecretStr): The password used to authenticate.\n        private_key (SecretStr): The PEM used to authenticate.\n        authenticator (str): The type of authenticator to use for initializing\n            connection (oauth, externalbrowser, etc); refer to\n            [Snowflake documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect)\n            for details, and note that `externalbrowser` will only\n            work in an environment where a browser is available.\n        token (SecretStr): The OAuth or JWT Token to provide when\n            authenticator is set to OAuth.\n        endpoint (str): The Okta endpoint to use when authenticator is\n            set to `okta_endpoint`, e.g. `https://&lt;okta_account_name&gt;.okta.com`.\n        role (str): The name of the default role to use.\n        autocommit (bool): Whether to automatically commit.\n\n    Example:\n        Load stored Snowflake credentials:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Snowflake Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/bd359de0b4be76c2254bd329fe3a267a1a3879c2-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials\"  # noqa\n\n    account: str = Field(\n        ..., description=\"The snowflake account name.\", example=\"nh12345.us-east-2.aws\"\n    )\n    user: str = Field(..., description=\"The user name used to authenticate.\")\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    private_key: Optional[SecretBytes] = Field(\n        default=None, description=\"The PEM used to authenticate.\"\n    )\n    private_key_path: Optional[Path] = Field(\n        default=None, description=\"The path to the private key.\"\n    )\n    private_key_passphrase: Optional[SecretStr] = Field(\n        default=None, description=\"The password to use for the private key.\"\n    )\n    authenticator: Literal[\n        \"snowflake\",\n        \"snowflake_jwt\",\n        \"externalbrowser\",\n        \"okta_endpoint\",\n        \"oauth\",\n        \"username_password_mfa\",\n    ] = Field(  # noqa\n        default=\"snowflake\",\n        description=(\"The type of authenticator to use for initializing connection.\"),\n    )\n    token: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The OAuth or JWT Token to provide when authenticator is set to `oauth`.\"\n        ),\n    )\n    endpoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The Okta endpoint to use when authenticator is set to `okta_endpoint`.\"\n        ),\n    )\n    role: Optional[str] = Field(\n        default=None, description=\"The name of the default role to use.\"\n    )\n    autocommit: Optional[bool] = Field(\n        default=None, description=\"Whether to automatically commit.\"\n    )\n\n    @root_validator(pre=True)\n    def _validate_auth_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        auth_params = (\n            \"password\",\n            \"private_key\",\n            \"private_key_path\",\n            \"authenticator\",\n            \"token\",\n        )\n        if not any(values.get(param) for param in auth_params):\n            auth_str = \", \".join(auth_params)\n            raise ValueError(\n                f\"One of the authentication keys must be provided: {auth_str}\\n\"\n            )\n        elif values.get(\"private_key\") and values.get(\"private_key_path\"):\n            raise ValueError(\n                \"Do not provide both private_key and private_key_path; select one.\"\n            )\n        elif values.get(\"password\") and values.get(\"private_key_passphrase\"):\n            raise ValueError(\n                \"Do not provide both password and private_key_passphrase; \"\n                \"specify private_key_passphrase only instead.\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def _validate_token_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        authenticator = values.get(\"authenticator\")\n        token = values.get(\"token\")\n        if authenticator == \"oauth\" and not token:\n            raise ValueError(\n                \"If authenticator is set to `oauth`, `token` must be provided\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def _validate_okta_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        authenticator = values.get(\"authenticator\")\n\n        # did not want to make a breaking change so we will allow both\n        # see https://github.com/PrefectHQ/prefect-snowflake/issues/44\n        if \"okta_endpoint\" in values.keys():\n            warnings.warn(\n                \"Please specify `endpoint` instead of `okta_endpoint`; \"\n                \"`okta_endpoint` will be removed March 31, 2023.\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n            # remove okta endpoint from fields\n            okta_endpoint = values.pop(\"okta_endpoint\")\n            if \"endpoint\" not in values.keys():\n                values[\"endpoint\"] = okta_endpoint\n\n        endpoint = values.get(\"endpoint\")\n        if authenticator == \"okta_endpoint\" and not endpoint:\n            raise ValueError(\n                \"If authenticator is set to `okta_endpoint`, \"\n                \"`endpoint` must be provided\"\n            )\n        return values\n\n    def resolve_private_key(self) -&gt; Optional[bytes]:\n        \"\"\"\n        Converts a PEM encoded private key into a DER binary key.\n\n        Returns:\n            DER encoded key if private_key has been provided otherwise returns None.\n\n        Raises:\n            InvalidPemFormat: If private key is not in PEM format.\n        \"\"\"\n        if self.private_key_path is None and self.private_key is None:\n            return None\n        elif self.private_key_path:\n            private_key = self.private_key_path.read_bytes()\n        else:\n            private_key = self._decode_secret(self.private_key)\n\n        if self.private_key_passphrase is not None:\n            password = self._decode_secret(self.private_key_passphrase)\n        elif self.password is not None:\n            warnings.warn(\n                \"Using the password field for private_key is deprecated \"\n                \"and will not work after March 31, 2023; please use \"\n                \"private_key_passphrase instead\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n            password = self._decode_secret(self.password)\n        else:\n            password = None\n\n        composed_private_key = self._compose_pem(private_key)\n        return load_pem_private_key(\n            data=composed_private_key,\n            password=password,\n            backend=default_backend(),\n        ).private_bytes(\n            encoding=Encoding.DER,\n            format=PrivateFormat.PKCS8,\n            encryption_algorithm=NoEncryption(),\n        )\n\n    @staticmethod\n    def _decode_secret(secret: Union[SecretStr, SecretBytes]) -&gt; Optional[bytes]:\n        \"\"\"\n        Decode the provided secret into bytes. If the secret is not a\n        string or bytes, or it is whitespace, then return None.\n\n        Args:\n            secret: The value to decode.\n\n        Returns:\n            The decoded secret as bytes.\n\n        \"\"\"\n        if isinstance(secret, (SecretBytes, SecretStr)):\n            secret = secret.get_secret_value()\n\n        if not isinstance(secret, (bytes, str)) or len(secret) == 0 or secret.isspace():\n            return None\n\n        return secret if isinstance(secret, bytes) else secret.encode()\n\n    @staticmethod\n    def _compose_pem(private_key: bytes) -&gt; bytes:\n        \"\"\"Validate structure of PEM certificate.\n\n        The original key passed from Prefect is sometimes malformed.\n        This function recomposes the key into a valid key that will\n        pass the serialization step when resolving the key to a DER.\n\n        Args:\n            private_key: A valid PEM format byte encoded string.\n\n        Returns:\n            byte encoded certificate.\n\n        Raises:\n            InvalidPemFormat: if private key is an invalid format.\n        \"\"\"\n        pem_parts = re.match(_SIMPLE_PEM_CERTIFICATE_REGEX, private_key.decode())\n        if pem_parts is None:\n            raise InvalidPemFormat()\n\n        body = \"\\n\".join(re.split(r\"\\s+\", pem_parts[2].strip()))\n        # reassemble header+body+footer\n        return f\"{pem_parts[1]}\\n{body}\\n{pem_parts[3]}\".encode()\n\n    def get_client(\n        self, **connect_kwargs: Any\n    ) -&gt; snowflake.connector.SnowflakeConnection:\n        \"\"\"\n        Returns an authenticated connection that can be used to query\n        Snowflake databases.\n\n        Any additional arguments passed to this method will be used to configure\n        the SnowflakeConnection. For available parameters, please refer to the\n        [Snowflake Python connector documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect).\n\n        Args:\n            **connect_kwargs: Additional arguments to pass to\n                `snowflake.connector.connect`.\n\n        Returns:\n            An authenticated Snowflake connection.\n\n        Example:\n            Get Snowflake connection with only block configuration:\n            ```python\n            from prefect_snowflake import SnowflakeCredentials\n\n            snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n            connection = snowflake_credentials_block.get_client()\n            ```\n\n            Get Snowflake connector scoped to a specified database:\n            ```python\n            from prefect_snowflake import SnowflakeCredentials\n\n            snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n            connection = snowflake_credentials_block.get_client(database=\"my_database\")\n            ```\n        \"\"\"  # noqa\n        connect_params = {\n            # required to track task's usage in the Snowflake Partner Network Portal\n            \"application\": \"Prefect_Snowflake_Collection\",\n            **self.dict(exclude_unset=True, exclude={\"block_type_slug\"}),\n            **connect_kwargs,\n        }\n\n        for key, value in connect_params.items():\n            if isinstance(value, SecretField):\n                connect_params[key] = connect_params[key].get_secret_value()\n\n        # set authenticator to the actual okta_endpoint\n        if connect_params.get(\"authenticator\") == \"okta_endpoint\":\n            endpoint = connect_params.pop(\"endpoint\", None) or connect_params.pop(\n                \"okta_endpoint\", None\n            )  # okta_endpoint is deprecated\n            connect_params[\"authenticator\"] = endpoint\n\n        private_der_key = self.resolve_private_key()\n        if private_der_key is not None:\n            connect_params[\"private_key\"] = private_der_key\n            connect_params.pop(\"password\", None)\n            connect_params.pop(\"private_key_passphrase\", None)\n\n        return snowflake.connector.connect(**connect_params)\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated connection that can be used to query Snowflake databases.</p> <p>Any additional arguments passed to this method will be used to configure the SnowflakeConnection. For available parameters, please refer to the Snowflake Python connector documentation.</p> <p>Parameters:</p> Name Type Description Default <code>**connect_kwargs</code> <code>Any</code> <p>Additional arguments to pass to <code>snowflake.connector.connect</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>SnowflakeConnection</code> <p>An authenticated Snowflake connection.</p> Example <p>Get Snowflake connection with only block configuration: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\nconnection = snowflake_credentials_block.get_client()\n</code></pre></p> <p>Get Snowflake connector scoped to a specified database: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\nconnection = snowflake_credentials_block.get_client(database=\"my_database\")\n</code></pre></p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>def get_client(\n    self, **connect_kwargs: Any\n) -&gt; snowflake.connector.SnowflakeConnection:\n    \"\"\"\n    Returns an authenticated connection that can be used to query\n    Snowflake databases.\n\n    Any additional arguments passed to this method will be used to configure\n    the SnowflakeConnection. For available parameters, please refer to the\n    [Snowflake Python connector documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect).\n\n    Args:\n        **connect_kwargs: Additional arguments to pass to\n            `snowflake.connector.connect`.\n\n    Returns:\n        An authenticated Snowflake connection.\n\n    Example:\n        Get Snowflake connection with only block configuration:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n        connection = snowflake_credentials_block.get_client()\n        ```\n\n        Get Snowflake connector scoped to a specified database:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n        connection = snowflake_credentials_block.get_client(database=\"my_database\")\n        ```\n    \"\"\"  # noqa\n    connect_params = {\n        # required to track task's usage in the Snowflake Partner Network Portal\n        \"application\": \"Prefect_Snowflake_Collection\",\n        **self.dict(exclude_unset=True, exclude={\"block_type_slug\"}),\n        **connect_kwargs,\n    }\n\n    for key, value in connect_params.items():\n        if isinstance(value, SecretField):\n            connect_params[key] = connect_params[key].get_secret_value()\n\n    # set authenticator to the actual okta_endpoint\n    if connect_params.get(\"authenticator\") == \"okta_endpoint\":\n        endpoint = connect_params.pop(\"endpoint\", None) or connect_params.pop(\n            \"okta_endpoint\", None\n        )  # okta_endpoint is deprecated\n        connect_params[\"authenticator\"] = endpoint\n\n    private_der_key = self.resolve_private_key()\n    if private_der_key is not None:\n        connect_params[\"private_key\"] = private_der_key\n        connect_params.pop(\"password\", None)\n        connect_params.pop(\"private_key_passphrase\", None)\n\n    return snowflake.connector.connect(**connect_params)\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials.resolve_private_key","title":"<code>resolve_private_key</code>","text":"<p>Converts a PEM encoded private key into a DER binary key.</p> <p>Returns:</p> Type Description <code>Optional[bytes]</code> <p>DER encoded key if private_key has been provided otherwise returns None.</p> <p>Raises:</p> Type Description <code>InvalidPemFormat</code> <p>If private key is not in PEM format.</p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>def resolve_private_key(self) -&gt; Optional[bytes]:\n    \"\"\"\n    Converts a PEM encoded private key into a DER binary key.\n\n    Returns:\n        DER encoded key if private_key has been provided otherwise returns None.\n\n    Raises:\n        InvalidPemFormat: If private key is not in PEM format.\n    \"\"\"\n    if self.private_key_path is None and self.private_key is None:\n        return None\n    elif self.private_key_path:\n        private_key = self.private_key_path.read_bytes()\n    else:\n        private_key = self._decode_secret(self.private_key)\n\n    if self.private_key_passphrase is not None:\n        password = self._decode_secret(self.private_key_passphrase)\n    elif self.password is not None:\n        warnings.warn(\n            \"Using the password field for private_key is deprecated \"\n            \"and will not work after March 31, 2023; please use \"\n            \"private_key_passphrase instead\",\n            DeprecationWarning,\n            stacklevel=2,\n        )\n        password = self._decode_secret(self.password)\n    else:\n        password = None\n\n    composed_private_key = self._compose_pem(private_key)\n    return load_pem_private_key(\n        data=composed_private_key,\n        password=password,\n        backend=default_backend(),\n    ).private_bytes(\n        encoding=Encoding.DER,\n        format=PrivateFormat.PKCS8,\n        encryption_algorithm=NoEncryption(),\n    )\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/","title":"Database","text":""},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database","title":"<code>prefect_snowflake.database</code>","text":"<p>Module for querying against Snowflake databases.</p>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector","title":"<code>SnowflakeConnector</code>","text":"<p>               Bases: <code>DatabaseBlock</code></p> <p>Block used to manage connections with Snowflake.</p> <p>Upon instantiating, a connection is created and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the engine and its connections when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor will be lost.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <p>The credentials to authenticate with Snowflake.</p> required <code>database</code> <p>The name of the default database to use.</p> required <code>warehouse</code> <p>The name of the default warehouse to use.</p> required <code>schema</code> <p>The name of the default schema to use; this attribute is accessible through <code>SnowflakeConnector(...).schema_</code>.</p> required <code>fetch_size</code> <p>The number of rows to fetch at a time.</p> required <code>poll_frequency_s</code> <p>The number of seconds before checking query.</p> required <p>Examples:</p> <p>Load stored Snowflake connector as a context manager: <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nsnowflake_connector = SnowflakeConnector.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Insert data into database and fetch results. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = conn.fetch_all(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Space\"}\n    )\n    print(results)\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>class SnowflakeConnector(DatabaseBlock):\n    \"\"\"\n    Block used to manage connections with Snowflake.\n\n    Upon instantiating, a connection is created and maintained for the life of\n    the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the engine and its connections when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor will be lost.\n\n    Args:\n        credentials: The credentials to authenticate with Snowflake.\n        database: The name of the default database to use.\n        warehouse: The name of the default warehouse to use.\n        schema: The name of the default schema to use;\n            this attribute is accessible through `SnowflakeConnector(...).schema_`.\n        fetch_size: The number of rows to fetch at a time.\n        poll_frequency_s: The number of seconds before checking query.\n\n    Examples:\n        Load stored Snowflake connector as a context manager:\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        snowflake_connector = SnowflakeConnector.load(\"BLOCK_NAME\")\n        ```\n\n        Insert data into database and fetch results.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = conn.fetch_all(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Space\"}\n            )\n            print(results)\n        ```\n    \"\"\"  # noqa\n\n    _block_type_name = \"Snowflake Connector\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/bd359de0b4be76c2254bd329fe3a267a1a3879c2-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector\"  # noqa\n    _description = \"Perform data operations against a Snowflake database.\"\n\n    credentials: SnowflakeCredentials = Field(\n        default=..., description=\"The credentials to authenticate with Snowflake.\"\n    )\n    database: str = Field(\n        default=..., description=\"The name of the default database to use.\"\n    )\n    warehouse: str = Field(\n        default=..., description=\"The name of the default warehouse to use.\"\n    )\n    schema_: str = Field(\n        default=...,\n        alias=\"schema\",\n        description=\"The name of the default schema to use.\",\n    )\n    fetch_size: int = Field(\n        default=1, description=\"The default number of rows to fetch at a time.\"\n    )\n    poll_frequency_s: int = Field(\n        default=1,\n        title=\"Poll Frequency [seconds]\",\n        description=(\n            \"The number of seconds between checking query \"\n            \"status for long running queries.\"\n        ),\n    )\n\n    _connection: Optional[SnowflakeConnection] = None\n    _unique_cursors: Dict[str, SnowflakeCursor] = None\n\n    def get_connection(self, **connect_kwargs: Any) -&gt; SnowflakeConnection:\n        \"\"\"\n        Returns an authenticated connection that can be\n        used to query from Snowflake databases.\n\n        Args:\n            **connect_kwargs: Additional arguments to pass to\n                `snowflake.connector.connect`.\n\n        Returns:\n            The authenticated SnowflakeConnection.\n\n        Examples:\n            ```python\n            from prefect_snowflake.credentials import SnowflakeCredentials\n            from prefect_snowflake.database import SnowflakeConnector\n\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            with snowflake_connector.get_connection() as connection:\n                ...\n            ```\n        \"\"\"\n        if self._connection is not None:\n            return self._connection\n\n        connect_params = {\n            \"database\": self.database,\n            \"warehouse\": self.warehouse,\n            \"schema\": self.schema_,\n        }\n        connection = self.credentials.get_client(**connect_kwargs, **connect_params)\n        self._connection = connection\n        self.logger.info(\"Started a new connection to Snowflake.\")\n        return connection\n\n    def _start_connection(self):\n        \"\"\"\n        Starts Snowflake database connection.\n        \"\"\"\n        self.get_connection()\n        if self._unique_cursors is None:\n            self._unique_cursors = {}\n\n    def _get_cursor(\n        self,\n        inputs: Dict[str, Any],\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    ) -&gt; Tuple[bool, SnowflakeCursor]:\n        \"\"\"\n        Get a Snowflake cursor.\n\n        Args:\n            inputs: The inputs to generate a unique hash, used to decide\n                whether a new cursor should be used.\n            cursor_type: The class of the cursor to use when creating a\n                Snowflake cursor.\n\n        Returns:\n            Whether a cursor is new and a Snowflake cursor.\n        \"\"\"\n        self._start_connection()\n\n        input_hash = hash_objects(inputs)\n        if input_hash is None:\n            raise RuntimeError(\n                \"We were not able to hash your inputs, \"\n                \"which resulted in an unexpected data return; \"\n                \"please open an issue with a reproducible example.\"\n            )\n        if input_hash not in self._unique_cursors.keys():\n            new_cursor = self._connection.cursor(cursor_type)\n            self._unique_cursors[input_hash] = new_cursor\n            return True, new_cursor\n        else:\n            existing_cursor = self._unique_cursors[input_hash]\n            return False, existing_cursor\n\n    async def _execute_async(self, cursor: SnowflakeCursor, inputs: Dict[str, Any]):\n        \"\"\"Helper method to execute operations asynchronously.\"\"\"\n        response = await run_sync_in_worker_thread(cursor.execute_async, **inputs)\n        self.logger.info(\n            f\"Executing the operation, {inputs['command']!r}, asynchronously; \"\n            f\"polling for the result every {self.poll_frequency_s} seconds.\"\n        )\n\n        query_id = response[\"queryId\"]\n        while self._connection.is_still_running(\n            await run_sync_in_worker_thread(\n                self._connection.get_query_status_throw_if_error, query_id\n            )\n        ):\n            await asyncio.sleep(self.poll_frequency_s)\n        await run_sync_in_worker_thread(cursor.get_results_from_sfqid, query_id)\n\n    def reset_cursors(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened cursors.\n\n        Examples:\n            Reset the cursors to refresh cursor position.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n                conn.reset_cursors()\n                print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n            ```\n        \"\"\"  # noqa\n        if not self._unique_cursors:\n            self.logger.info(\"There were no cursors to reset.\")\n            return\n\n        input_hashes = tuple(self._unique_cursors.keys())\n        for input_hash in input_hashes:\n            cursor = self._unique_cursors.pop(input_hash)\n            try:\n                cursor.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n                )\n        self.logger.info(\"Successfully reset the cursors.\")\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; Tuple[Any]:\n        \"\"\"\n        Fetch a single result from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A tuple containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Fetch one row from the database where address is Space.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                result = conn.fetch_one(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Space\"}\n                )\n                print(result)\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type=cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        self.logger.debug(\"Preparing to fetch a row.\")\n        result = await run_sync_in_worker_thread(cursor.fetchone)\n        return result\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Repeatedly fetch two rows from the database where address is Highway 42.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Me\", \"address\": \"Highway 42\"},\n                    ],\n                )\n                result = conn.fetch_many(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                    size=2\n                )\n                print(result)  # Marvin, Ford\n                result = conn.fetch_many(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                    size=2\n                )\n                print(result)  # Unknown, Me\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        size = size or self.fetch_size\n        self.logger.debug(f\"Preparing to fetch {size} rows.\")\n        result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n        return result\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch all results from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Fetch all rows from the database where address is Highway 42.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                result = conn.fetch_all(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                )\n                print(result)  # Marvin, Ford, Unknown\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        self.logger.debug(\"Preparing to fetch all rows.\")\n        result = await run_sync_in_worker_thread(cursor.fetchall)\n        return result\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Examples:\n            Create table named customers with two columns, name and address.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n            ```\n        \"\"\"  # noqa\n        self._start_connection()\n\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        with self._connection.cursor(cursor_type) as cursor:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n        self.logger.info(f\"Executed the operation, {operation!r}.\")\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n        Unlike the fetch methods, this method will always execute the operations\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n\n        Examples:\n            Create table and insert three rows into it.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    ],\n                )\n            ```\n        \"\"\"  # noqa\n        self._start_connection()\n\n        inputs = dict(\n            command=operation,\n            seqparams=seq_of_parameters,\n        )\n        with self._connection.cursor() as cursor:\n            await run_sync_in_worker_thread(cursor.executemany, **inputs)\n        self.logger.info(\n            f\"Executed {len(seq_of_parameters)} operations off {operation!r}.\"\n        )\n\n    def close(self):\n        \"\"\"\n        Closes connection and its cursors.\n        \"\"\"\n        try:\n            self.reset_cursors()\n        finally:\n            if self._connection is None:\n                self.logger.info(\"There was no connection open to be closed.\")\n                return\n            self._connection.close()\n            self._connection = None\n            self.logger.info(\"Successfully closed the Snowflake connection.\")\n\n    def __enter__(self):\n        \"\"\"\n        Start a connection upon entry.\n        \"\"\"\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Closes connection and its cursors upon exit.\n        \"\"\"\n        self.close()\n\n    def __getstate__(self):\n        \"\"\"Allows block to be pickled and dumped.\"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_connection\", \"_unique_cursors\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"Reset connection and cursors upon loading.\"\"\"\n        self.__dict__.update(data)\n        self._start_connection()\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.close","title":"<code>close</code>","text":"<p>Closes connection and its cursors.</p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes connection and its cursors.\n    \"\"\"\n    try:\n        self.reset_cursors()\n    finally:\n        if self._connection is None:\n            self.logger.info(\"There was no connection open to be closed.\")\n            return\n        self._connection.close()\n        self._connection = None\n        self.logger.info(\"Successfully closed the Snowflake connection.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE. Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create table named customers with two columns, name and address. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Examples:\n        Create table named customers with two columns, name and address.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n        ```\n    \"\"\"  # noqa\n    self._start_connection()\n\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    with self._connection.cursor(cursor_type) as cursor:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n    self.logger.info(f\"Executed the operation, {operation!r}.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE. Unlike the fetch methods, this method will always execute the operations upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <p>Examples:</p> <p>Create table and insert three rows into it. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n        ],\n    )\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n    Unlike the fetch methods, this method will always execute the operations\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n\n    Examples:\n        Create table and insert three rows into it.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                ],\n            )\n        ```\n    \"\"\"  # noqa\n    self._start_connection()\n\n    inputs = dict(\n        command=operation,\n        seqparams=seq_of_parameters,\n    )\n    with self._connection.cursor() as cursor:\n        await run_sync_in_worker_thread(cursor.executemany, **inputs)\n    self.logger.info(\n        f\"Executed {len(seq_of_parameters)} operations off {operation!r}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Fetch all rows from the database where address is Highway 42. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    result = conn.fetch_all(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n    )\n    print(result)  # Marvin, Ford, Unknown\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch all results from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Fetch all rows from the database where address is Highway 42.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            result = conn.fetch_all(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n            )\n            print(result)  # Marvin, Ford, Unknown\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    self.logger.debug(\"Preparing to fetch all rows.\")\n    result = await run_sync_in_worker_thread(cursor.fetchall)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Repeatedly fetch two rows from the database where address is Highway 42. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            {\"name\": \"Me\", \"address\": \"Highway 42\"},\n        ],\n    )\n    result = conn.fetch_many(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n        size=2\n    )\n    print(result)  # Marvin, Ford\n    result = conn.fetch_many(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n        size=2\n    )\n    print(result)  # Unknown, Me\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Repeatedly fetch two rows from the database where address is Highway 42.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Me\", \"address\": \"Highway 42\"},\n                ],\n            )\n            result = conn.fetch_many(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n                size=2\n            )\n            print(result)  # Marvin, Ford\n            result = conn.fetch_many(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n                size=2\n            )\n            print(result)  # Unknown, Me\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    size = size or self.fetch_size\n    self.logger.debug(f\"Preparing to fetch {size} rows.\")\n    result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Tuple[Any]</code> <p>A tuple containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Fetch one row from the database where address is Space. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    result = conn.fetch_one(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Space\"}\n    )\n    print(result)\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; Tuple[Any]:\n    \"\"\"\n    Fetch a single result from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A tuple containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Fetch one row from the database where address is Space.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            result = conn.fetch_one(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Space\"}\n            )\n            print(result)\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type=cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    self.logger.debug(\"Preparing to fetch a row.\")\n    result = await run_sync_in_worker_thread(cursor.fetchone)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.get_connection","title":"<code>get_connection</code>","text":"<p>Returns an authenticated connection that can be used to query from Snowflake databases.</p> <p>Parameters:</p> Name Type Description Default <code>**connect_kwargs</code> <code>Any</code> <p>Additional arguments to pass to <code>snowflake.connector.connect</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>SnowflakeConnection</code> <p>The authenticated SnowflakeConnection.</p> <p>Examples:</p> <pre><code>from prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\nsnowflake_credentials = SnowflakeCredentials(\n    account=\"account\",\n    user=\"user\",\n    password=\"password\",\n)\nsnowflake_connector = SnowflakeConnector(\n    database=\"database\",\n    warehouse=\"warehouse\",\n    schema=\"schema\",\n    credentials=snowflake_credentials\n)\nwith snowflake_connector.get_connection() as connection:\n    ...\n</code></pre> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def get_connection(self, **connect_kwargs: Any) -&gt; SnowflakeConnection:\n    \"\"\"\n    Returns an authenticated connection that can be\n    used to query from Snowflake databases.\n\n    Args:\n        **connect_kwargs: Additional arguments to pass to\n            `snowflake.connector.connect`.\n\n    Returns:\n        The authenticated SnowflakeConnection.\n\n    Examples:\n        ```python\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        snowflake_credentials = SnowflakeCredentials(\n            account=\"account\",\n            user=\"user\",\n            password=\"password\",\n        )\n        snowflake_connector = SnowflakeConnector(\n            database=\"database\",\n            warehouse=\"warehouse\",\n            schema=\"schema\",\n            credentials=snowflake_credentials\n        )\n        with snowflake_connector.get_connection() as connection:\n            ...\n        ```\n    \"\"\"\n    if self._connection is not None:\n        return self._connection\n\n    connect_params = {\n        \"database\": self.database,\n        \"warehouse\": self.warehouse,\n        \"schema\": self.schema_,\n    }\n    connection = self.credentials.get_client(**connect_kwargs, **connect_params)\n    self._connection = connection\n    self.logger.info(\"Started a new connection to Snowflake.\")\n    return connection\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.reset_cursors","title":"<code>reset_cursors</code>","text":"<p>Tries to close all opened cursors.</p> <p>Examples:</p> <p>Reset the cursors to refresh cursor position. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n    conn.reset_cursors()\n    print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def reset_cursors(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened cursors.\n\n    Examples:\n        Reset the cursors to refresh cursor position.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n            conn.reset_cursors()\n            print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n        ```\n    \"\"\"  # noqa\n    if not self._unique_cursors:\n        self.logger.info(\"There were no cursors to reset.\")\n        return\n\n    input_hashes = tuple(self._unique_cursors.keys())\n    for input_hash in input_hashes:\n        cursor = self._unique_cursors.pop(input_hash)\n        try:\n            cursor.close()\n        except Exception as exc:\n            self.logger.warning(\n                f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n            )\n    self.logger.info(\"Successfully reset the cursors.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_multiquery","title":"<code>snowflake_multiquery</code>  <code>async</code>","text":"<p>Executes multiple queries against a Snowflake database in a shared session. Allows execution in a transaction.</p> <p>Parameters:</p> Name Type Description Default <code>queries</code> <code>List[str]</code> <p>The list of queries to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <code>as_transaction</code> <code>bool</code> <p>If True, queries are executed in a transaction.</p> <code>False</code> <code>return_transaction_control_results</code> <code>bool</code> <p>Determines if the results of queries controlling the transaction (BEGIN/COMMIT) should be returned.</p> <code>False</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>1</code> <p>Returns:</p> Type Description <code>List[List[Tuple[Any]]]</code> <p>List of the outputs of <code>response.fetchall()</code> for each query.</p> <p>Examples:</p> <p>Query Snowflake table with the ID value parameterized. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_multiquery\n\n\n@flow\ndef snowflake_multiquery_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_multiquery(\n        [\"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\", \"SELECT 1,2\"],\n        snowflake_connector,\n        params={\"id_param\": 1},\n        as_transaction=True\n    )\n    return result\n\nsnowflake_multiquery_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_multiquery(\n    queries: List[str],\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    as_transaction: bool = False,\n    return_transaction_control_results: bool = False,\n    poll_frequency_seconds: int = 1,\n) -&gt; List[List[Tuple[Any]]]:\n    \"\"\"\n    Executes multiple queries against a Snowflake database in a shared session.\n    Allows execution in a transaction.\n\n    Args:\n        queries: The list of queries to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n        as_transaction: If True, queries are executed in a transaction.\n        return_transaction_control_results: Determines if the results of queries\n            controlling the transaction (BEGIN/COMMIT) should be returned.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        List of the outputs of `response.fetchall()` for each query.\n\n    Examples:\n        Query Snowflake table with the ID value parameterized.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_multiquery\n\n\n        @flow\n        def snowflake_multiquery_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_multiquery(\n                [\"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\", \"SELECT 1,2\"],\n                snowflake_connector,\n                params={\"id_param\": 1},\n                as_transaction=True\n            )\n            return result\n\n        snowflake_multiquery_flow()\n        ```\n    \"\"\"\n    with snowflake_connector.get_connection() as connection:\n        if as_transaction:\n            queries.insert(0, BEGIN_TRANSACTION_STATEMENT)\n            queries.append(END_TRANSACTION_STATEMENT)\n\n        with connection.cursor(cursor_type) as cursor:\n            results = []\n            for query in queries:\n                response = cursor.execute_async(query, params=params)\n                query_id = response[\"queryId\"]\n                while connection.is_still_running(\n                    connection.get_query_status_throw_if_error(query_id)\n                ):\n                    await asyncio.sleep(poll_frequency_seconds)\n                cursor.get_results_from_sfqid(query_id)\n                result = cursor.fetchall()\n                results.append(result)\n\n    # cut off results from BEGIN/COMMIT queries\n    if as_transaction and not return_transaction_control_results:\n        return results[1:-1]\n    else:\n        return results\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_query","title":"<code>snowflake_query</code>  <code>async</code>","text":"<p>Executes a query against a Snowflake database.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>1</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The output of <code>response.fetchall()</code>.</p> <p>Examples:</p> <p>Query Snowflake table with the ID value parameterized. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n@flow\ndef snowflake_query_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_query(\n        \"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\",\n        snowflake_connector,\n        params={\"id_param\": 1}\n    )\n    return result\n\nsnowflake_query_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_query(\n    query: str,\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    poll_frequency_seconds: int = 1,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a query against a Snowflake database.\n\n    Args:\n        query: The query to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        The output of `response.fetchall()`.\n\n    Examples:\n        Query Snowflake table with the ID value parameterized.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n        @flow\n        def snowflake_query_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_query(\n                \"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\",\n                snowflake_connector,\n                params={\"id_param\": 1}\n            )\n            return result\n\n        snowflake_query_flow()\n        ```\n    \"\"\"\n    # context manager automatically rolls back failed transactions and closes\n    with snowflake_connector.get_connection() as connection:\n        with connection.cursor(cursor_type) as cursor:\n            response = cursor.execute_async(query, params=params)\n            query_id = response[\"queryId\"]\n            while connection.is_still_running(\n                connection.get_query_status_throw_if_error(query_id)\n            ):\n                await asyncio.sleep(poll_frequency_seconds)\n            cursor.get_results_from_sfqid(query_id)\n            result = cursor.fetchall()\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_query_sync","title":"<code>snowflake_query_sync</code>  <code>async</code>","text":"<p>Executes a query in sync mode against a Snowflake database.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The output of <code>response.fetchall()</code>.</p> <p>Examples:</p> <p>Execute a put statement. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n@flow\ndef snowflake_query_sync_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_query_sync(\n        \"put file://a_file.csv @mystage;\",\n        snowflake_connector,\n    )\n    return result\n\nsnowflake_query_sync_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_query_sync(\n    query: str,\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a query in sync mode against a Snowflake database.\n\n    Args:\n        query: The query to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n\n    Returns:\n        The output of `response.fetchall()`.\n\n    Examples:\n        Execute a put statement.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n        @flow\n        def snowflake_query_sync_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_query_sync(\n                \"put file://a_file.csv @mystage;\",\n                snowflake_connector,\n            )\n            return result\n\n        snowflake_query_sync_flow()\n        ```\n    \"\"\"\n    # context manager automatically rolls back failed transactions and closes\n    with snowflake_connector.get_connection() as connection:\n        with connection.cursor(cursor_type) as cursor:\n            cursor.execute(query, params=params)\n            result = cursor.fetchall()\n    return result\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/","title":"prefect-sqlalchemy","text":"<p>Visit the full docs here to see additional examples and the API reference.</p> <p>The prefect-sqlalchemy collection makes it easy to connect to a database in your Prefect flows. Check out the examples below to get started!</p>"},{"location":"integrations/prefect-sqlalchemy/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-sqlalchemy/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Prefect and SQLAlchemy are a data powerhouse duo. With Prefect, your workflows are orchestratable and observable, and with SQLAlchemy, your databases are a snap to handle! Get ready to experience the ultimate data \"flow-chemistry\"!</p> <p>To set up a table, use the <code>execute</code> and <code>execute_many</code> methods. Then, use the <code>fetch_many</code> method to retrieve data in a stream until there's no more data.</p> <p>By using the <code>SqlAlchemyConnector</code> as a context manager, you can make sure that the SQLAlchemy engine and any connected resources are closed properly after you're done with them.</p> <p>Be sure to install prefect-sqlalchemy and save your credentials to a Prefect block to run the examples below!</p> <p>Async support</p> <p><code>SqlAlchemyConnector</code> also supports async workflows! Just be sure to save, load, and use an async driver as in the example below.</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"DATABASE-PLACEHOLDER.db\"\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> SyncAsync <pre><code>from prefect import flow, task\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\n\n@task\ndef setup_table(block_name: str) -&gt; None:\n    with SqlAlchemyConnector.load(block_name) as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n\n@task\ndef fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with SqlAlchemyConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\ndef sqlalchemy_flow(block_name: str) -&gt; list:\n    setup_table(block_name)\n    all_rows = fetch_data(block_name)\n    return all_rows\n\n\nsqlalchemy_flow(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <pre><code>from prefect import flow, task\nfrom prefect_sqlalchemy import SqlAlchemyConnector\nimport asyncio\n\n@task\nasync def setup_table(block_name: str) -&gt; None:\n    async with await SqlAlchemyConnector.load(block_name) as connector:\n        await connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        await connector.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n        )\n        await connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n\n@task\nasync def fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    async with await SqlAlchemyConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = await connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\nasync def sqlalchemy_flow(block_name: str) -&gt; list:\n    await setup_table(block_name)\n    all_rows = await fetch_data(block_name)\n    return all_rows\n\n\nasyncio.run(sqlalchemy_flow(\"BLOCK-NAME-PLACEHOLDER\"))\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/#resources","title":"Resources","text":"<p>For more tips on how to use tasks and flows provided in a Prefect integration library, check out the Prefect docs on using integrations.</p>"},{"location":"integrations/prefect-sqlalchemy/#installation","title":"Installation","text":"<p>Install <code>prefect-sqlalchemy</code> with <code>pip</code>:</p> <pre><code>pip install prefect-sqlalchemy\n</code></pre> <p>Requires an installation of Python 3.8 or higher.</p> <p>We recommend using a Python virtual environment manager such as pipenv, conda, or virtualenv.</p> <p>The tasks in this library are designed to work with Prefect 2. For more information about how to use Prefect, please refer to the Prefect documentation.</p>"},{"location":"integrations/prefect-sqlalchemy/#saving-credentials-to-a-block","title":"Saving credentials to a block","text":"<p>To use the <code>load</code> method on Blocks, you must have a block document saved through code or saved through the UI.</p> <p>Below is a walkthrough on saving block documents through code; simply create a short script, replacing the placeholders.</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n        username=\"USERNAME-PLACEHOLDER\",\n        password=\"PASSWORD-PLACEHOLDER\",\n        host=\"localhost\",\n        port=5432,\n        database=\"DATABASE-PLACEHOLDER\",\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>Congrats! You can now easily load the saved block, which holds your credentials:</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nSqlAlchemyConnector.load(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>The required keywords depend upon the desired driver. For example, SQLite requires only the <code>driver</code> and <code>database</code> arguments:</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.SQLITE_PYSQLITE,\n        database=\"DATABASE-PLACEHOLDER.db\"\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>Registering blocks</p> <p>Register blocks in this module to view and edit them on Prefect Cloud:</p> <pre><code>prefect block register -m prefect_sqlalchemy\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/#feedback","title":"Feedback","text":"<p>If you encounter any bugs while using <code>prefect-sqlalchemy</code>, please open an issue in the prefect repository.</p> <p>If you have any questions or issues while using <code>prefect-sqlalchemy</code>, you can find help in the Prefect Community Slack .</p>"},{"location":"integrations/prefect-sqlalchemy/#contributing","title":"Contributing","text":"<p>If you'd like to help contribute to fix an issue or add a feature to <code>prefect-sqlalchemy</code>, please propose changes through a pull request from a fork of the repository.</p> <p>Here are the steps:</p> <ol> <li>Fork the repository</li> <li>Clone the forked repository</li> <li>Install the repository and its dependencies: <pre><code>pip install -e \".[dev]\"\n</code></pre></li> <li>Make desired changes</li> <li>Add tests</li> <li>Install <code>pre-commit</code> to perform quality checks prior to commit: <pre><code>pre-commit install\n</code></pre></li> <li><code>git commit</code>, <code>git push</code>, and create a pull request</li> </ol>"},{"location":"integrations/prefect-sqlalchemy/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials","title":"<code>prefect_sqlalchemy.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with SQLAlchemy</p>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.AsyncDriver","title":"<code>AsyncDriver</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Known dialects with their corresponding async drivers.</p> <p>Attributes:</p> Name Type Description <code>POSTGRESQL_ASYNCPG</code> <code>Enum</code> <p>postgresql+asyncpg</p> <code>SQLITE_AIOSQLITE</code> <code>Enum</code> <p>sqlite+aiosqlite</p> <code>MYSQL_ASYNCMY</code> <code>Enum</code> <p>mysql+asyncmy</p> <code>MYSQL_AIOMYSQL</code> <code>Enum</code> <p>mysql+aiomysql</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class AsyncDriver(Enum):\n    \"\"\"\n    Known dialects with their corresponding async drivers.\n\n    Attributes:\n        POSTGRESQL_ASYNCPG (Enum): [postgresql+asyncpg](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.asyncpg)\n\n        SQLITE_AIOSQLITE (Enum): [sqlite+aiosqlite](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.aiosqlite)\n\n        MYSQL_ASYNCMY (Enum): [mysql+asyncmy](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.asyncmy)\n        MYSQL_AIOMYSQL (Enum): [mysql+aiomysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.aiomysql)\n    \"\"\"  # noqa\n\n    POSTGRESQL_ASYNCPG = \"postgresql+asyncpg\"\n\n    SQLITE_AIOSQLITE = \"sqlite+aiosqlite\"\n\n    MYSQL_ASYNCMY = \"mysql+asyncmy\"\n    MYSQL_AIOMYSQL = \"mysql+aiomysql\"\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.ConnectionComponents","title":"<code>ConnectionComponents</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Parameters to use to create a SQLAlchemy engine URL.</p> <p>Attributes:</p> Name Type Description <code>driver</code> <code>Union[AsyncDriver, SyncDriver, str]</code> <p>The driver name to use.</p> <code>database</code> <code>str</code> <p>The name of the database to use.</p> <code>username</code> <code>Optional[str]</code> <p>The user name used to authenticate.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password used to authenticate.</p> <code>host</code> <code>Optional[str]</code> <p>The host address of the database.</p> <code>port</code> <code>Optional[str]</code> <p>The port to connect to the database.</p> <code>query</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class ConnectionComponents(BaseModel):\n    \"\"\"\n    Parameters to use to create a SQLAlchemy engine URL.\n\n    Attributes:\n        driver: The driver name to use.\n        database: The name of the database to use.\n        username: The user name used to authenticate.\n        password: The password used to authenticate.\n        host: The host address of the database.\n        port: The port to connect to the database.\n        query: A dictionary of string keys to string values to be passed to the dialect\n            and/or the DBAPI upon connect.\n    \"\"\"\n\n    driver: Union[AsyncDriver, SyncDriver, str] = Field(\n        default=..., description=\"The driver name to use.\"\n    )\n    database: str = Field(default=..., description=\"The name of the database to use.\")\n    username: Optional[str] = Field(\n        default=None, description=\"The user name used to authenticate.\"\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    host: Optional[str] = Field(\n        default=None, description=\"The host address of the database.\"\n    )\n    port: Optional[str] = Field(\n        default=None, description=\"The port to connect to the database.\"\n    )\n    query: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"A dictionary of string keys to string values to be passed to the dialect \"\n            \"and/or the DBAPI upon connect. To specify non-string parameters to a \"\n            \"Python DBAPI directly, use connect_args.\"\n        ),\n    )\n\n    def create_url(self) -&gt; URL:\n        \"\"\"\n        Create a fully formed connection URL.\n\n        Returns:\n            The SQLAlchemy engine URL.\n        \"\"\"\n        driver = self.driver\n        drivername = driver.value if isinstance(driver, Enum) else driver\n        password = self.password.get_secret_value() if self.password else None\n        url_params = dict(\n            drivername=drivername,\n            username=self.username,\n            password=password,\n            database=self.database,\n            host=self.host,\n            port=self.port,\n            query=self.query,\n        )\n        return URL.create(\n            **{\n                url_key: url_param\n                for url_key, url_param in url_params.items()\n                if url_param is not None\n            }\n        )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.ConnectionComponents.create_url","title":"<code>create_url</code>","text":"<p>Create a fully formed connection URL.</p> <p>Returns:</p> Type Description <code>URL</code> <p>The SQLAlchemy engine URL.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def create_url(self) -&gt; URL:\n    \"\"\"\n    Create a fully formed connection URL.\n\n    Returns:\n        The SQLAlchemy engine URL.\n    \"\"\"\n    driver = self.driver\n    drivername = driver.value if isinstance(driver, Enum) else driver\n    password = self.password.get_secret_value() if self.password else None\n    url_params = dict(\n        drivername=drivername,\n        username=self.username,\n        password=password,\n        database=self.database,\n        host=self.host,\n        port=self.port,\n        query=self.query,\n    )\n    return URL.create(\n        **{\n            url_key: url_param\n            for url_key, url_param in url_params.items()\n            if url_param is not None\n        }\n    )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials","title":"<code>DatabaseCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage authentication with a database.</p> <p>Attributes:</p> Name Type Description <code>driver</code> <code>Optional[Union[AsyncDriver, SyncDriver, str]]</code> <p>The driver name, e.g. \"postgresql+asyncpg\"</p> <code>database</code> <code>Optional[str]</code> <p>The name of the database to use.</p> <code>username</code> <code>Optional[str]</code> <p>The user name used to authenticate.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password used to authenticate.</p> <code>host</code> <code>Optional[str]</code> <p>The host address of the database.</p> <code>port</code> <code>Optional[str]</code> <p>The port to connect to the database.</p> <code>query</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect. To specify non-string parameters to a Python DBAPI directly, use connect_args.</p> <code>url</code> <code>Optional[AnyUrl]</code> <p>Manually create and provide a URL to create the engine, this is useful for external dialects, e.g. Snowflake, because some of the params, such as \"warehouse\", is not directly supported in the vanilla <code>sqlalchemy.engine.URL.create</code> method; do not provide this alongside with other URL params as it will raise a <code>ValueError</code>.</p> <code>connect_args</code> <code>Optional[Dict[str, Any]]</code> <p>The options which will be passed directly to the DBAPI's connect() method as additional keyword arguments.</p> Example <p>Load stored database credentials: <pre><code>from prefect_sqlalchemy import DatabaseCredentials\ndatabase_block = DatabaseCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class DatabaseCredentials(Block):\n    \"\"\"\n    Block used to manage authentication with a database.\n\n    Attributes:\n        driver: The driver name, e.g. \"postgresql+asyncpg\"\n        database: The name of the database to use.\n        username: The user name used to authenticate.\n        password: The password used to authenticate.\n        host: The host address of the database.\n        port: The port to connect to the database.\n        query: A dictionary of string keys to string values to be passed to\n            the dialect and/or the DBAPI upon connect. To specify non-string\n            parameters to a Python DBAPI directly, use connect_args.\n        url: Manually create and provide a URL to create the engine,\n            this is useful for external dialects, e.g. Snowflake, because some\n            of the params, such as \"warehouse\", is not directly supported in\n            the vanilla `sqlalchemy.engine.URL.create` method; do not provide\n            this alongside with other URL params as it will raise a `ValueError`.\n        connect_args: The options which will be passed directly to the\n            DBAPI's connect() method as additional keyword arguments.\n\n    Example:\n        Load stored database credentials:\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials\n        database_block = DatabaseCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Database Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/fb3f4debabcda1c5a3aeea4f5b3f94c28845e23e-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials\"  # noqa\n\n    driver: Optional[Union[AsyncDriver, SyncDriver, str]] = Field(\n        default=None, description=\"The driver name to use.\"\n    )\n    username: Optional[str] = Field(\n        default=None, description=\"The user name used to authenticate.\"\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    database: Optional[str] = Field(\n        default=None, description=\"The name of the database to use.\"\n    )\n    host: Optional[str] = Field(\n        default=None, description=\"The host address of the database.\"\n    )\n    port: Optional[str] = Field(\n        default=None, description=\"The port to connect to the database.\"\n    )\n    query: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"A dictionary of string keys to string values to be passed to the dialect \"\n            \"and/or the DBAPI upon connect. To specify non-string parameters to a \"\n            \"Python DBAPI directly, use connect_args.\"\n        ),\n    )\n    url: Optional[AnyUrl] = Field(\n        default=None,\n        description=(\n            \"Manually create and provide a URL to create the engine, this is useful \"\n            \"for external dialects, e.g. Snowflake, because some of the params, \"\n            \"such as 'warehouse', is not directly supported in the vanilla \"\n            \"`sqlalchemy.engine.URL.create` method; do not provide this \"\n            \"alongside with other URL params as it will raise a `ValueError`.\"\n        ),\n    )\n    connect_args: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=(\n            \"The options which will be passed directly to the DBAPI's connect() \"\n            \"method as additional keyword arguments.\"\n        ),\n    )\n\n    def block_initialization(self):\n        \"\"\"\n        Initializes the engine.\n        \"\"\"\n        warnings.warn(\n            \"DatabaseCredentials is now deprecated and will be removed March 2023; \"\n            \"please use SqlAlchemyConnector instead.\",\n            DeprecationWarning,\n        )\n        if isinstance(self.driver, AsyncDriver):\n            drivername = self.driver.value\n            self._driver_is_async = True\n        elif isinstance(self.driver, SyncDriver):\n            drivername = self.driver.value\n            self._driver_is_async = False\n        else:\n            drivername = self.driver\n            self._driver_is_async = drivername in AsyncDriver._value2member_map_\n\n        url_params = dict(\n            drivername=drivername,\n            username=self.username,\n            password=self.password.get_secret_value() if self.password else None,\n            database=self.database,\n            host=self.host,\n            port=self.port,\n            query=self.query,\n        )\n        if not self.url:\n            required_url_keys = (\"drivername\", \"database\")\n            if not all(url_params[key] for key in required_url_keys):\n                required_url_keys = (\"driver\", \"database\")\n                raise ValueError(\n                    f\"If the `url` is not provided, \"\n                    f\"all of these URL params are required: \"\n                    f\"{required_url_keys}\"\n                )\n            self.rendered_url = URL.create(\n                **{\n                    url_key: url_param\n                    for url_key, url_param in url_params.items()\n                    if url_param is not None\n                }\n            )  # from params\n        else:\n            if any(val for val in url_params.values()):\n                raise ValueError(\n                    f\"The `url` should not be provided \"\n                    f\"alongside any of these URL params: \"\n                    f\"{url_params.keys()}\"\n                )\n            self.rendered_url = make_url(str(self.url))\n\n    def get_engine(self) -&gt; Union[\"Connection\", \"AsyncConnection\"]:\n        \"\"\"\n        Returns an authenticated engine that can be\n        used to query from databases.\n\n        Returns:\n            The authenticated SQLAlchemy Connection / AsyncConnection.\n\n        Examples:\n            Create an asynchronous engine to PostgreSQL using URL params.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                sqlalchemy_credentials = DatabaseCredentials(\n                    driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                    username=\"prefect\",\n                    password=\"prefect_password\",\n                    database=\"postgres\"\n                )\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n\n            Create a synchronous engine to Snowflake using the `url` kwarg.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                url = (\n                    \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                    \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                    \"?warehouse=&lt;warehouse_name&gt;\"\n                )\n                sqlalchemy_credentials = DatabaseCredentials(url=url)\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n        \"\"\"\n        engine_kwargs = dict(\n            url=self.rendered_url,\n            connect_args=self.connect_args or {},\n            poolclass=NullPool,\n        )\n        if self._driver_is_async:\n            engine = create_async_engine(**engine_kwargs)\n        else:\n            engine = create_engine(**engine_kwargs)\n        return engine\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'URL' type\n        arbitrary_types_allowed = True\n        json_encoders = {URL: lambda u: u.render_as_string()}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'URL' type\n        d = super().dict(*args, **kwargs)\n        d[\"rendered_url\"] = SecretStr(\n            self.rendered_url.render_as_string(hide_password=False)\n        )\n        return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'URL' type\n    arbitrary_types_allowed = True\n    json_encoders = {URL: lambda u: u.render_as_string()}\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.block_initialization","title":"<code>block_initialization</code>","text":"<p>Initializes the engine.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def block_initialization(self):\n    \"\"\"\n    Initializes the engine.\n    \"\"\"\n    warnings.warn(\n        \"DatabaseCredentials is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector instead.\",\n        DeprecationWarning,\n    )\n    if isinstance(self.driver, AsyncDriver):\n        drivername = self.driver.value\n        self._driver_is_async = True\n    elif isinstance(self.driver, SyncDriver):\n        drivername = self.driver.value\n        self._driver_is_async = False\n    else:\n        drivername = self.driver\n        self._driver_is_async = drivername in AsyncDriver._value2member_map_\n\n    url_params = dict(\n        drivername=drivername,\n        username=self.username,\n        password=self.password.get_secret_value() if self.password else None,\n        database=self.database,\n        host=self.host,\n        port=self.port,\n        query=self.query,\n    )\n    if not self.url:\n        required_url_keys = (\"drivername\", \"database\")\n        if not all(url_params[key] for key in required_url_keys):\n            required_url_keys = (\"driver\", \"database\")\n            raise ValueError(\n                f\"If the `url` is not provided, \"\n                f\"all of these URL params are required: \"\n                f\"{required_url_keys}\"\n            )\n        self.rendered_url = URL.create(\n            **{\n                url_key: url_param\n                for url_key, url_param in url_params.items()\n                if url_param is not None\n            }\n        )  # from params\n    else:\n        if any(val for val in url_params.values()):\n            raise ValueError(\n                f\"The `url` should not be provided \"\n                f\"alongside any of these URL params: \"\n                f\"{url_params.keys()}\"\n            )\n        self.rendered_url = make_url(str(self.url))\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'URL' type\n    d = super().dict(*args, **kwargs)\n    d[\"rendered_url\"] = SecretStr(\n        self.rendered_url.render_as_string(hide_password=False)\n    )\n    return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.get_engine","title":"<code>get_engine</code>","text":"<p>Returns an authenticated engine that can be used to query from databases.</p> <p>Returns:</p> Type Description <code>Union[Connection, AsyncConnection]</code> <p>The authenticated SQLAlchemy Connection / AsyncConnection.</p> <p>Examples:</p> <p>Create an asynchronous engine to PostgreSQL using URL params. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n        username=\"prefect\",\n        password=\"prefect_password\",\n        database=\"postgres\"\n    )\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> <p>Create a synchronous engine to Snowflake using the <code>url</code> kwarg. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    url = (\n        \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n        \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n        \"?warehouse=&lt;warehouse_name&gt;\"\n    )\n    sqlalchemy_credentials = DatabaseCredentials(url=url)\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def get_engine(self) -&gt; Union[\"Connection\", \"AsyncConnection\"]:\n    \"\"\"\n    Returns an authenticated engine that can be\n    used to query from databases.\n\n    Returns:\n        The authenticated SQLAlchemy Connection / AsyncConnection.\n\n    Examples:\n        Create an asynchronous engine to PostgreSQL using URL params.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                username=\"prefect\",\n                password=\"prefect_password\",\n                database=\"postgres\"\n            )\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n\n        Create a synchronous engine to Snowflake using the `url` kwarg.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            url = (\n                \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                \"?warehouse=&lt;warehouse_name&gt;\"\n            )\n            sqlalchemy_credentials = DatabaseCredentials(url=url)\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n    \"\"\"\n    engine_kwargs = dict(\n        url=self.rendered_url,\n        connect_args=self.connect_args or {},\n        poolclass=NullPool,\n    )\n    if self._driver_is_async:\n        engine = create_async_engine(**engine_kwargs)\n    else:\n        engine = create_engine(**engine_kwargs)\n    return engine\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.SyncDriver","title":"<code>SyncDriver</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Known dialects with their corresponding sync drivers.</p> <p>Attributes:</p> Name Type Description <code>POSTGRESQL_PSYCOPG2</code> <code>Enum</code> <p>postgresql+psycopg2</p> <code>POSTGRESQL_PG8000</code> <code>Enum</code> <p>postgresql+pg8000</p> <code>POSTGRESQL_PSYCOPG2CFFI</code> <code>Enum</code> <p>postgresql+psycopg2cffi</p> <code>POSTGRESQL_PYPOSTGRESQL</code> <code>Enum</code> <p>postgresql+pypostgresql</p> <code>POSTGRESQL_PYGRESQL</code> <code>Enum</code> <p>postgresql+pygresql</p> <code>MYSQL_MYSQLDB</code> <code>Enum</code> <p>mysql+mysqldb</p> <code>MYSQL_PYMYSQL</code> <code>Enum</code> <p>mysql+pymysql</p> <code>MYSQL_MYSQLCONNECTOR</code> <code>Enum</code> <p>mysql+mysqlconnector</p> <code>MYSQL_CYMYSQL</code> <code>Enum</code> <p>mysql+cymysql</p> <code>MYSQL_OURSQL</code> <code>Enum</code> <p>mysql+oursql</p> <code>MYSQL_PYODBC</code> <code>Enum</code> <p>mysql+pyodbc</p> <code>SQLITE_PYSQLITE</code> <code>Enum</code> <p>sqlite+pysqlite</p> <code>SQLITE_PYSQLCIPHER</code> <code>Enum</code> <p>sqlite+pysqlcipher</p> <code>ORACLE_CX_ORACLE</code> <code>Enum</code> <p>oracle+cx_oracle</p> <code>MSSQL_PYODBC</code> <code>Enum</code> <p>mssql+pyodbc</p> <code>MSSQL_MXODBC</code> <code>Enum</code> <p>mssql+mxodbc</p> <code>MSSQL_PYMSSQL</code> <code>Enum</code> <p>mssql+pymssql</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class SyncDriver(Enum):\n    \"\"\"\n    Known dialects with their corresponding sync drivers.\n\n    Attributes:\n        POSTGRESQL_PSYCOPG2 (Enum): [postgresql+psycopg2](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg2)\n        POSTGRESQL_PG8000 (Enum): [postgresql+pg8000](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pg8000)\n        POSTGRESQL_PSYCOPG2CFFI (Enum): [postgresql+psycopg2cffi](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg2cffi)\n        POSTGRESQL_PYPOSTGRESQL (Enum): [postgresql+pypostgresql](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pypostgresql)\n        POSTGRESQL_PYGRESQL (Enum): [postgresql+pygresql](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pygresql)\n\n        MYSQL_MYSQLDB (Enum): [mysql+mysqldb](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.mysqldb)\n        MYSQL_PYMYSQL (Enum): [mysql+pymysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.pymysql)\n        MYSQL_MYSQLCONNECTOR (Enum): [mysql+mysqlconnector](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.mysqlconnector)\n        MYSQL_CYMYSQL (Enum): [mysql+cymysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.cymysql)\n        MYSQL_OURSQL (Enum): [mysql+oursql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.oursql)\n        MYSQL_PYODBC (Enum): [mysql+pyodbc](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.pyodbc)\n\n        SQLITE_PYSQLITE (Enum): [sqlite+pysqlite](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.pysqlite)\n        SQLITE_PYSQLCIPHER (Enum): [sqlite+pysqlcipher](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.pysqlcipher)\n\n        ORACLE_CX_ORACLE (Enum): [oracle+cx_oracle](https://docs.sqlalchemy.org/en/14/dialects/oracle.html#module-sqlalchemy.dialects.oracle.cx_oracle)\n\n        MSSQL_PYODBC (Enum): [mssql+pyodbc](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.pyodbc)\n        MSSQL_MXODBC (Enum): [mssql+mxodbc](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.mxodbc)\n        MSSQL_PYMSSQL (Enum): [mssql+pymssql](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.pymssql)\n    \"\"\"  # noqa\n\n    POSTGRESQL_PSYCOPG2 = \"postgresql+psycopg2\"\n    POSTGRESQL_PG8000 = \"postgresql+pg8000\"\n    POSTGRESQL_PSYCOPG2CFFI = \"postgresql+psycopg2cffi\"\n    POSTGRESQL_PYPOSTGRESQL = \"postgresql+pypostgresql\"\n    POSTGRESQL_PYGRESQL = \"postgresql+pygresql\"\n\n    MYSQL_MYSQLDB = \"mysql+mysqldb\"\n    MYSQL_PYMYSQL = \"mysql+pymysql\"\n    MYSQL_MYSQLCONNECTOR = \"mysql+mysqlconnector\"\n    MYSQL_CYMYSQL = \"mysql+cymysql\"\n    MYSQL_OURSQL = \"mysql+oursql\"\n    MYSQL_PYODBC = \"mysql+pyodbc\"\n\n    SQLITE_PYSQLITE = \"sqlite+pysqlite\"\n    SQLITE_PYSQLCIPHER = \"sqlite+pysqlcipher\"\n\n    ORACLE_CX_ORACLE = \"oracle+cx_oracle\"\n\n    MSSQL_PYODBC = \"mssql+pyodbc\"\n    MSSQL_MXODBC = \"mssql+mxodbc\"\n    MSSQL_PYMSSQL = \"mssql+pymssql\"\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/","title":"Database","text":""},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database","title":"<code>prefect_sqlalchemy.database</code>","text":"<p>Tasks for querying a database with SQLAlchemy</p>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector","title":"<code>SqlAlchemyConnector</code>","text":"<p>               Bases: <code>CredentialsBlock</code>, <code>DatabaseBlock</code></p> <p>Block used to manage authentication with a database.</p> <p>Upon instantiating, an engine is created and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the engine and its connections when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor could be lost.</p> <p>Attributes:</p> Name Type Description <code>connection_info</code> <code>Union[ConnectionComponents, AnyUrl]</code> <p>SQLAlchemy URL to create the engine; either create from components or create from a string.</p> <code>connect_args</code> <code>Optional[Dict[str, Any]]</code> <p>The options which will be passed directly to the DBAPI's connect() method as additional keyword arguments.</p> <code>fetch_size</code> <code>int</code> <p>The number of rows to fetch at a time.</p> Example <p>Load stored database credentials and use in context manager: <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\ndatabase_block = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith database_block:\n    ...\n</code></pre></p> <p>Create table named customers and insert values; then fetch the first 10 rows. <pre><code>from prefect_sqlalchemy import (\n    SqlAlchemyConnector, SyncDriver, ConnectionComponents\n)\n\nwith SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.SQLITE_PYSQLITE,\n        database=\"prefect.db\"\n    )\n) as database:\n    database.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n    )\n    for i in range(1, 42):\n        database.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": f\"Highway {i}\"},\n        )\n    results = database.fetch_many(\n        \"SELECT * FROM customers WHERE name = :name;\",\n        parameters={\"name\": \"Marvin\"},\n        size=10\n    )\nprint(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>class SqlAlchemyConnector(CredentialsBlock, DatabaseBlock):\n    \"\"\"\n    Block used to manage authentication with a database.\n\n    Upon instantiating, an engine is created and maintained for the life of\n    the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the engine and its connections when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor could be lost.\n\n    Attributes:\n        connection_info: SQLAlchemy URL to create the engine;\n            either create from components or create from a string.\n        connect_args: The options which will be passed directly to the\n            DBAPI's connect() method as additional keyword arguments.\n        fetch_size: The number of rows to fetch at a time.\n\n    Example:\n        Load stored database credentials and use in context manager:\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        database_block = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with database_block:\n            ...\n        ```\n\n        Create table named customers and insert values; then fetch the first 10 rows.\n        ```python\n        from prefect_sqlalchemy import (\n            SqlAlchemyConnector, SyncDriver, ConnectionComponents\n        )\n\n        with SqlAlchemyConnector(\n            connection_info=ConnectionComponents(\n                driver=SyncDriver.SQLITE_PYSQLITE,\n                database=\"prefect.db\"\n            )\n        ) as database:\n            database.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n            )\n            for i in range(1, 42):\n                database.execute(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    parameters={\"name\": \"Marvin\", \"address\": f\"Highway {i}\"},\n                )\n            results = database.fetch_many(\n                \"SELECT * FROM customers WHERE name = :name;\",\n                parameters={\"name\": \"Marvin\"},\n                size=10\n            )\n        print(results)\n        ```\n    \"\"\"\n\n    _block_type_name = \"SQLAlchemy Connector\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/3c7dff04f70aaf4528e184a3b028f9e40b98d68c-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector\"  # noqa\n\n    connection_info: Union[ConnectionComponents, AnyUrl] = Field(\n        default=...,\n        description=(\n            \"SQLAlchemy URL to create the engine; either create from components \"\n            \"or create from a string.\"\n        ),\n    )\n    connect_args: Optional[Dict[str, Any]] = Field(\n        default=None,\n        title=\"Additional Connection Arguments\",\n        description=(\n            \"The options which will be passed directly to the DBAPI's connect() \"\n            \"method as additional keyword arguments.\"\n        ),\n    )\n    fetch_size: int = Field(\n        default=1, description=\"The number of rows to fetch at a time.\"\n    )\n\n    _engine: Optional[Union[AsyncEngine, Engine]] = None\n    _exit_stack: Union[ExitStack, AsyncExitStack] = None\n    _unique_results: Dict[str, CursorResult] = None\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'URL' type\n        arbitrary_types_allowed = True\n        json_encoders = {URL: lambda u: u.render_as_string()}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'URL' type\n        d = super().dict(*args, **kwargs)\n        d[\"_rendered_url\"] = SecretStr(\n            self._rendered_url.render_as_string(hide_password=False)\n        )\n        return d\n\n    def block_initialization(self):\n        \"\"\"\n        Initializes the engine.\n        \"\"\"\n        super().block_initialization()\n\n        if isinstance(self.connection_info, ConnectionComponents):\n            self._rendered_url = self.connection_info.create_url()\n        else:\n            # make rendered url from string\n            self._rendered_url = make_url(str(self.connection_info))\n        drivername = self._rendered_url.drivername\n\n        try:\n            AsyncDriver(drivername)\n            self._driver_is_async = True\n        except ValueError:\n            self._driver_is_async = False\n\n        if self._unique_results is None:\n            self._unique_results = {}\n\n        if self._exit_stack is None:\n            self._start_exit_stack()\n\n    def _start_exit_stack(self):\n        \"\"\"\n        Starts an AsyncExitStack or ExitStack depending on whether driver is async.\n        \"\"\"\n        self._exit_stack = AsyncExitStack() if self._driver_is_async else ExitStack()\n\n    def get_engine(\n        self, **create_engine_kwargs: Dict[str, Any]\n    ) -&gt; Union[Engine, AsyncEngine]:\n        \"\"\"\n        Returns an authenticated engine that can be\n        used to query from databases.\n\n        If an existing engine exists, return that one.\n\n        Returns:\n            The authenticated SQLAlchemy Engine / AsyncEngine.\n\n        Examples:\n            Create an asynchronous engine to PostgreSQL using URL params.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import (\n                SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n            )\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                sqlalchemy_credentials = SqlAlchemyConnector(\n                connection_info=ConnectionComponents(\n                        driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                        username=\"prefect\",\n                        password=\"prefect_password\",\n                        database=\"postgres\"\n                    )\n                )\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n\n            Create a synchronous engine to Snowflake using the `url` kwarg.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                url = (\n                    \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                    \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                    \"?warehouse=&lt;warehouse_name&gt;\"\n                )\n                sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n        \"\"\"\n        if self._engine is not None:\n            self.logger.debug(\"Reusing existing engine.\")\n            return self._engine\n\n        engine_kwargs = dict(\n            url=self._rendered_url,\n            connect_args=self.connect_args or {},\n            **create_engine_kwargs,\n        )\n        if self._driver_is_async:\n            # no need to await here\n            engine = create_async_engine(**engine_kwargs)\n        else:\n            engine = create_engine(**engine_kwargs)\n        self.logger.info(\"Created a new engine.\")\n\n        if self._engine is None:\n            self._engine = engine\n\n        return engine\n\n    def get_connection(\n        self, begin: bool = True, **connect_kwargs: Dict[str, Any]\n    ) -&gt; Union[Connection, AsyncConnection]:\n        \"\"\"\n        Returns a connection that can be used to query from databases.\n\n        Args:\n            begin: Whether to begin a transaction on the connection; if True, if\n                any operations fail, the entire transaction will be rolled back.\n            **connect_kwargs: Additional keyword arguments to pass to either\n                `engine.begin` or engine.connect`.\n\n        Returns:\n            The SQLAlchemy Connection / AsyncConnection.\n\n        Examples:\n            Create an synchronous connection as a context-managed transaction.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            with sqlalchemy_connector.get_connection(begin=False) as connection:\n                connection.execute(\"SELECT * FROM table LIMIT 1;\")\n            ```\n\n            Create an asynchronous connection as a context-managed transacation.\n            ```python\n            import asyncio\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            async with sqlalchemy_connector.get_connection(begin=False) as connection:\n                asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n            ```\n        \"\"\"  # noqa: E501\n        engine = self.get_engine()\n        if begin:\n            connection = engine.begin(**connect_kwargs)\n        else:\n            connection = engine.connect(**connect_kwargs)\n        self.logger.info(\"Created a new connection.\")\n        return connection\n\n    def get_client(\n        self,\n        client_type: Literal[\"engine\", \"connection\"],\n        **get_client_kwargs: Dict[str, Any],\n    ) -&gt; Union[Engine, AsyncEngine, Connection, AsyncConnection]:\n        \"\"\"\n        Returns either an engine or connection that can be used to query from databases.\n\n        Args:\n            client_type: Select from either 'engine' or 'connection'.\n            **get_client_kwargs: Additional keyword arguments to pass to\n                either `get_engine` or `get_connection`.\n\n        Returns:\n            The authenticated SQLAlchemy engine or connection.\n\n        Examples:\n            Create an engine.\n            ```python\n            from prefect_sqlalchemy import SqlalchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            engine = sqlalchemy_connector.get_client(client_type=\"engine\")\n            ```\n\n            Create a context managed connection.\n            ```python\n            from prefect_sqlalchemy import SqlalchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            with sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n                ...\n            ```\n        \"\"\"  # noqa: E501\n        if client_type == \"engine\":\n            client = self.get_engine(**get_client_kwargs)\n        elif client_type == \"connection\":\n            client = self.get_connection(**get_client_kwargs)\n        else:\n            raise ValueError(\n                f\"{client_type!r} is not supported; choose from engine or connection.\"\n            )\n        return client\n\n    async def _async_sync_execute(\n        self,\n        connection: Union[Connection, AsyncConnection],\n        *execute_args: Tuple[Any],\n        **execute_kwargs: Dict[str, Any],\n    ) -&gt; CursorResult:\n        \"\"\"\n        Execute the statement asynchronously or synchronously.\n        \"\"\"\n        # can't use run_sync_in_worker_thread:\n        # ProgrammingError: (sqlite3.ProgrammingError) SQLite objects created in a\n        # thread can only be used in that same thread.\n        result_set = connection.execute(*execute_args, **execute_kwargs)\n\n        if self._driver_is_async:\n            result_set = await result_set\n            await connection.commit()  # very important\n        elif SQLALCHEMY_VERSION.startswith(\"2.\"):\n            connection.commit()\n        return result_set\n\n    @asynccontextmanager\n    async def _manage_connection(self, **get_connection_kwargs: Dict[str, Any]):\n        if self._driver_is_async:\n            async with self.get_connection(**get_connection_kwargs) as connection:\n                yield connection\n        else:\n            with self.get_connection(**get_connection_kwargs) as connection:\n                yield connection\n\n    async def _get_result_set(\n        self, *execute_args: Tuple[Any], **execute_kwargs: Dict[str, Any]\n    ) -&gt; CursorResult:\n        \"\"\"\n        Returns a new or existing result set based on whether the inputs\n        are unique.\n\n        Args:\n            *execute_args: Args to pass to execute.\n            **execute_kwargs: Keyword args to pass to execute.\n\n        Returns:\n            The result set from the operation.\n        \"\"\"  # noqa: E501\n        input_hash = hash_objects(*execute_args, **execute_kwargs)\n        assert input_hash is not None, (\n            \"We were not able to hash your inputs, \"\n            \"which resulted in an unexpected data return; \"\n            \"please open an issue with a reproducible example.\"\n        )\n\n        if input_hash not in self._unique_results.keys():\n            if self._driver_is_async:\n                connection = await self._exit_stack.enter_async_context(\n                    self.get_connection()\n                )\n            else:\n                connection = self._exit_stack.enter_context(self.get_connection())\n            result_set = await self._async_sync_execute(\n                connection, *execute_args, **execute_kwargs\n            )\n            # implicitly store the connection by storing the result set\n            # which points to its parent connection\n            self._unique_results[input_hash] = result_set\n        else:\n            result_set = self._unique_results[input_hash]\n        return result_set\n\n    def _reset_cursor_results(self) -&gt; None:\n        \"\"\"\n        Closes all the existing cursor results.\n        \"\"\"\n        input_hashes = tuple(self._unique_results.keys())\n        for input_hash in input_hashes:\n            try:\n                cursor_result = self._unique_results.pop(input_hash)\n                cursor_result.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close connection for input hash {input_hash!r}: {exc}\"\n                )\n\n    @sync_compatible\n    async def reset_connections(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened connections and their results.\n\n        Examples:\n            Resets connections so `fetch_*` methods return new results.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                results = database.fetch_one(\"SELECT * FROM customers\")\n                database.reset_connections()\n                results = database.fetch_one(\"SELECT * FROM customers\")\n            ```\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} has no synchronous connections. \"\n                f\"Please use the `reset_async_connections` method instead.\"\n            )\n\n        if self._exit_stack is None:\n            self.logger.info(\"There were no connections to reset.\")\n            return\n\n        self._reset_cursor_results()\n        self._exit_stack.close()\n        self.logger.info(\"Reset opened connections and their results.\")\n\n    async def reset_async_connections(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened connections and their results.\n\n        Examples:\n            Resets connections so `fetch_*` methods return new results.\n            ```python\n            import asyncio\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            async def example_run():\n                async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                    results = await database.fetch_one(\"SELECT * FROM customers\")\n                    await database.reset_async_connections()\n                    results = await database.fetch_one(\"SELECT * FROM customers\")\n\n            asyncio.run(example_run())\n            ```\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} has no asynchronous connections. \"\n                f\"Please use the `reset_connections` method instead.\"\n            )\n\n        if self._exit_stack is None:\n            self.logger.info(\"There were no connections to reset.\")\n            return\n\n        self._reset_cursor_results()\n        await self._exit_stack.aclose()\n        self.logger.info(\"Reset opened connections and their results.\")\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; Tuple[Any]:\n        \"\"\"\n        Fetch a single result from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch a row repeatedly.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = True\n                while results:\n                    results = database.fetch_one(\"SELECT * FROM customers\")\n                    print(results)\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        self.logger.debug(\"Preparing to fetch one row.\")\n        row = result_set.fetchone()\n        return row\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch two rows repeatedly.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n                print(results)\n                results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n                print(results)\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        size = size or self.fetch_size\n        self.logger.debug(f\"Preparing to fetch {size} rows.\")\n        rows = result_set.fetchmany(size=size)\n        return rows\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch all results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch all where name is 'Me'.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        self.logger.debug(\"Preparing to fetch all rows.\")\n        rows = result_set.fetchall()\n        return rows\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Examples:\n            Create a table and insert one row into it.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                )\n            ```\n        \"\"\"  # noqa\n        async with self._manage_connection(begin=False) as connection:\n            await self._async_sync_execute(\n                connection,\n                text(operation),\n                parameters,\n                execution_options=execution_options,\n            )\n        self.logger.info(f\"Executed the operation, {operation!r}\")\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Examples:\n            Create a table and insert two rows into it.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n            ```\n        \"\"\"  # noqa\n        async with self._manage_connection(begin=False) as connection:\n            await self._async_sync_execute(\n                connection,\n                text(operation),\n                seq_of_parameters,\n                execution_options=execution_options,\n            )\n        self.logger.info(\n            f\"Executed {len(seq_of_parameters)} operations based off {operation!r}.\"\n        )\n\n    async def __aenter__(self):\n        \"\"\"\n        Start an asynchronous database engine upon entry.\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} cannot be run asynchronously. \"\n                f\"Please use the `with` syntax.\"\n            )\n        return self\n\n    async def __aexit__(self, *args):\n        \"\"\"\n        Dispose the asynchronous database engine upon exit.\n        \"\"\"\n        await self.aclose()\n\n    async def aclose(self):\n        \"\"\"\n        Closes async connections and its cursors.\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} is not asynchronous. \"\n                f\"Please use the `close` method instead.\"\n            )\n        try:\n            await self.reset_async_connections()\n        finally:\n            if self._engine is not None:\n                await self._engine.dispose()\n                self._engine = None\n                self.logger.info(\"Disposed the engine.\")\n\n    def __enter__(self):\n        \"\"\"\n        Start an synchronous database engine upon entry.\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} cannot be run synchronously. \"\n                f\"Please use the `async with` syntax.\"\n            )\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Dispose the synchronous database engine upon exit.\n        \"\"\"\n        self.close()\n\n    def close(self):\n        \"\"\"\n        Closes sync connections and its cursors.\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} is not synchronous. \"\n                f\"Please use the `aclose` method instead.\"\n            )\n\n        try:\n            self.reset_connections()\n        finally:\n            if self._engine is not None:\n                self._engine.dispose()\n                self._engine = None\n                self.logger.info(\"Disposed the engine.\")\n\n    def __getstate__(self):\n        \"\"\"Allows the block to be pickleable.\"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_engine\", \"_exit_stack\", \"_unique_results\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"Upon loading back, restart the engine and results.\"\"\"\n        self.__dict__.update(data)\n\n        if self._unique_results is None:\n            self._unique_results = {}\n\n        if self._exit_stack is None:\n            self._start_exit_stack()\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'URL' type\n    arbitrary_types_allowed = True\n    json_encoders = {URL: lambda u: u.render_as_string()}\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.aclose","title":"<code>aclose</code>  <code>async</code>","text":"<p>Closes async connections and its cursors.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>async def aclose(self):\n    \"\"\"\n    Closes async connections and its cursors.\n    \"\"\"\n    if not self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} is not asynchronous. \"\n            f\"Please use the `close` method instead.\"\n        )\n    try:\n        await self.reset_async_connections()\n    finally:\n        if self._engine is not None:\n            await self._engine.dispose()\n            self._engine = None\n            self.logger.info(\"Disposed the engine.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.block_initialization","title":"<code>block_initialization</code>","text":"<p>Initializes the engine.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def block_initialization(self):\n    \"\"\"\n    Initializes the engine.\n    \"\"\"\n    super().block_initialization()\n\n    if isinstance(self.connection_info, ConnectionComponents):\n        self._rendered_url = self.connection_info.create_url()\n    else:\n        # make rendered url from string\n        self._rendered_url = make_url(str(self.connection_info))\n    drivername = self._rendered_url.drivername\n\n    try:\n        AsyncDriver(drivername)\n        self._driver_is_async = True\n    except ValueError:\n        self._driver_is_async = False\n\n    if self._unique_results is None:\n        self._unique_results = {}\n\n    if self._exit_stack is None:\n        self._start_exit_stack()\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.close","title":"<code>close</code>","text":"<p>Closes sync connections and its cursors.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes sync connections and its cursors.\n    \"\"\"\n    if self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} is not synchronous. \"\n            f\"Please use the `aclose` method instead.\"\n        )\n\n    try:\n        self.reset_connections()\n    finally:\n        if self._engine is not None:\n            self._engine.dispose()\n            self._engine = None\n            self.logger.info(\"Disposed the engine.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'URL' type\n    d = super().dict(*args, **kwargs)\n    d[\"_rendered_url\"] = SecretStr(\n        self._rendered_url.render_as_string(hide_password=False)\n    )\n    return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create a table and insert one row into it. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n    )\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Examples:\n        Create a table and insert one row into it.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            )\n        ```\n    \"\"\"  # noqa\n    async with self._manage_connection(begin=False) as connection:\n        await self._async_sync_execute(\n            connection,\n            text(operation),\n            parameters,\n            execution_options=execution_options,\n        )\n    self.logger.info(f\"Executed the operation, {operation!r}\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create a table and insert two rows into it. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Examples:\n        Create a table and insert two rows into it.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n        ```\n    \"\"\"  # noqa\n    async with self._manage_connection(begin=False) as connection:\n        await self._async_sync_execute(\n            connection,\n            text(operation),\n            seq_of_parameters,\n            execution_options=execution_options,\n        )\n    self.logger.info(\n        f\"Executed {len(seq_of_parameters)} operations based off {operation!r}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch all where name is 'Me'. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch all results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch all where name is 'Me'.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    self.logger.debug(\"Preparing to fetch all rows.\")\n    rows = result_set.fetchall()\n    return rows\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch two rows repeatedly. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n    print(results)\n    results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n    print(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch two rows repeatedly.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n            print(results)\n            results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n            print(results)\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    size = size or self.fetch_size\n    self.logger.debug(f\"Preparing to fetch {size} rows.\")\n    rows = result_set.fetchmany(size=size)\n    return rows\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Tuple[Any]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch a row repeatedly. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = True\n    while results:\n        results = database.fetch_one(\"SELECT * FROM customers\")\n        print(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; Tuple[Any]:\n    \"\"\"\n    Fetch a single result from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch a row repeatedly.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = True\n            while results:\n                results = database.fetch_one(\"SELECT * FROM customers\")\n                print(results)\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    self.logger.debug(\"Preparing to fetch one row.\")\n    row = result_set.fetchone()\n    return row\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_client","title":"<code>get_client</code>","text":"<p>Returns either an engine or connection that can be used to query from databases.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['engine', 'connection']</code> <p>Select from either 'engine' or 'connection'.</p> required <code>**get_client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to either <code>get_engine</code> or <code>get_connection</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Engine, AsyncEngine, Connection, AsyncConnection]</code> <p>The authenticated SQLAlchemy engine or connection.</p> <p>Examples:</p> <p>Create an engine. <pre><code>from prefect_sqlalchemy import SqlalchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nengine = sqlalchemy_connector.get_client(client_type=\"engine\")\n</code></pre></p> <p>Create a context managed connection. <pre><code>from prefect_sqlalchemy import SqlalchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n    ...\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_client(\n    self,\n    client_type: Literal[\"engine\", \"connection\"],\n    **get_client_kwargs: Dict[str, Any],\n) -&gt; Union[Engine, AsyncEngine, Connection, AsyncConnection]:\n    \"\"\"\n    Returns either an engine or connection that can be used to query from databases.\n\n    Args:\n        client_type: Select from either 'engine' or 'connection'.\n        **get_client_kwargs: Additional keyword arguments to pass to\n            either `get_engine` or `get_connection`.\n\n    Returns:\n        The authenticated SQLAlchemy engine or connection.\n\n    Examples:\n        Create an engine.\n        ```python\n        from prefect_sqlalchemy import SqlalchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        engine = sqlalchemy_connector.get_client(client_type=\"engine\")\n        ```\n\n        Create a context managed connection.\n        ```python\n        from prefect_sqlalchemy import SqlalchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n            ...\n        ```\n    \"\"\"  # noqa: E501\n    if client_type == \"engine\":\n        client = self.get_engine(**get_client_kwargs)\n    elif client_type == \"connection\":\n        client = self.get_connection(**get_client_kwargs)\n    else:\n        raise ValueError(\n            f\"{client_type!r} is not supported; choose from engine or connection.\"\n        )\n    return client\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_connection","title":"<code>get_connection</code>","text":"<p>Returns a connection that can be used to query from databases.</p> <p>Parameters:</p> Name Type Description Default <code>begin</code> <code>bool</code> <p>Whether to begin a transaction on the connection; if True, if any operations fail, the entire transaction will be rolled back.</p> <code>True</code> <code>**connect_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to either <code>engine.begin</code> or engine.connect`.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Connection, AsyncConnection]</code> <p>The SQLAlchemy Connection / AsyncConnection.</p> <p>Examples:</p> <p>Create an synchronous connection as a context-managed transaction. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith sqlalchemy_connector.get_connection(begin=False) as connection:\n    connection.execute(\"SELECT * FROM table LIMIT 1;\")\n</code></pre></p> <p>Create an asynchronous connection as a context-managed transacation. <pre><code>import asyncio\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nasync with sqlalchemy_connector.get_connection(begin=False) as connection:\n    asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_connection(\n    self, begin: bool = True, **connect_kwargs: Dict[str, Any]\n) -&gt; Union[Connection, AsyncConnection]:\n    \"\"\"\n    Returns a connection that can be used to query from databases.\n\n    Args:\n        begin: Whether to begin a transaction on the connection; if True, if\n            any operations fail, the entire transaction will be rolled back.\n        **connect_kwargs: Additional keyword arguments to pass to either\n            `engine.begin` or engine.connect`.\n\n    Returns:\n        The SQLAlchemy Connection / AsyncConnection.\n\n    Examples:\n        Create an synchronous connection as a context-managed transaction.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with sqlalchemy_connector.get_connection(begin=False) as connection:\n            connection.execute(\"SELECT * FROM table LIMIT 1;\")\n        ```\n\n        Create an asynchronous connection as a context-managed transacation.\n        ```python\n        import asyncio\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        async with sqlalchemy_connector.get_connection(begin=False) as connection:\n            asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n        ```\n    \"\"\"  # noqa: E501\n    engine = self.get_engine()\n    if begin:\n        connection = engine.begin(**connect_kwargs)\n    else:\n        connection = engine.connect(**connect_kwargs)\n    self.logger.info(\"Created a new connection.\")\n    return connection\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_engine","title":"<code>get_engine</code>","text":"<p>Returns an authenticated engine that can be used to query from databases.</p> <p>If an existing engine exists, return that one.</p> <p>Returns:</p> Type Description <code>Union[Engine, AsyncEngine]</code> <p>The authenticated SQLAlchemy Engine / AsyncEngine.</p> <p>Examples:</p> <p>Create an asynchronous engine to PostgreSQL using URL params. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import (\n    SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n)\n\n@flow\ndef sqlalchemy_credentials_flow():\n    sqlalchemy_credentials = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n            driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n            username=\"prefect\",\n            password=\"prefect_password\",\n            database=\"postgres\"\n        )\n    )\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> <p>Create a synchronous engine to Snowflake using the <code>url</code> kwarg. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    url = (\n        \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n        \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n        \"?warehouse=&lt;warehouse_name&gt;\"\n    )\n    sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_engine(\n    self, **create_engine_kwargs: Dict[str, Any]\n) -&gt; Union[Engine, AsyncEngine]:\n    \"\"\"\n    Returns an authenticated engine that can be\n    used to query from databases.\n\n    If an existing engine exists, return that one.\n\n    Returns:\n        The authenticated SQLAlchemy Engine / AsyncEngine.\n\n    Examples:\n        Create an asynchronous engine to PostgreSQL using URL params.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import (\n            SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n        )\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            sqlalchemy_credentials = SqlAlchemyConnector(\n            connection_info=ConnectionComponents(\n                    driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                    username=\"prefect\",\n                    password=\"prefect_password\",\n                    database=\"postgres\"\n                )\n            )\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n\n        Create a synchronous engine to Snowflake using the `url` kwarg.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            url = (\n                \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                \"?warehouse=&lt;warehouse_name&gt;\"\n            )\n            sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n    \"\"\"\n    if self._engine is not None:\n        self.logger.debug(\"Reusing existing engine.\")\n        return self._engine\n\n    engine_kwargs = dict(\n        url=self._rendered_url,\n        connect_args=self.connect_args or {},\n        **create_engine_kwargs,\n    )\n    if self._driver_is_async:\n        # no need to await here\n        engine = create_async_engine(**engine_kwargs)\n    else:\n        engine = create_engine(**engine_kwargs)\n    self.logger.info(\"Created a new engine.\")\n\n    if self._engine is None:\n        self._engine = engine\n\n    return engine\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.reset_async_connections","title":"<code>reset_async_connections</code>  <code>async</code>","text":"<p>Tries to close all opened connections and their results.</p> <p>Examples:</p> <p>Resets connections so <code>fetch_*</code> methods return new results. <pre><code>import asyncio\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\nasync def example_run():\n    async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n        results = await database.fetch_one(\"SELECT * FROM customers\")\n        await database.reset_async_connections()\n        results = await database.fetch_one(\"SELECT * FROM customers\")\n\nasyncio.run(example_run())\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>async def reset_async_connections(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened connections and their results.\n\n    Examples:\n        Resets connections so `fetch_*` methods return new results.\n        ```python\n        import asyncio\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        async def example_run():\n            async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                results = await database.fetch_one(\"SELECT * FROM customers\")\n                await database.reset_async_connections()\n                results = await database.fetch_one(\"SELECT * FROM customers\")\n\n        asyncio.run(example_run())\n        ```\n    \"\"\"\n    if not self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} has no asynchronous connections. \"\n            f\"Please use the `reset_connections` method instead.\"\n        )\n\n    if self._exit_stack is None:\n        self.logger.info(\"There were no connections to reset.\")\n        return\n\n    self._reset_cursor_results()\n    await self._exit_stack.aclose()\n    self.logger.info(\"Reset opened connections and their results.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.reset_connections","title":"<code>reset_connections</code>  <code>async</code>","text":"<p>Tries to close all opened connections and their results.</p> <p>Examples:</p> <p>Resets connections so <code>fetch_*</code> methods return new results. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    results = database.fetch_one(\"SELECT * FROM customers\")\n    database.reset_connections()\n    results = database.fetch_one(\"SELECT * FROM customers\")\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def reset_connections(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened connections and their results.\n\n    Examples:\n        Resets connections so `fetch_*` methods return new results.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            results = database.fetch_one(\"SELECT * FROM customers\")\n            database.reset_connections()\n            results = database.fetch_one(\"SELECT * FROM customers\")\n        ```\n    \"\"\"\n    if self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} has no synchronous connections. \"\n            f\"Please use the `reset_async_connections` method instead.\"\n        )\n\n    if self._exit_stack is None:\n        self.logger.info(\"There were no connections to reset.\")\n        return\n\n    self._reset_cursor_results()\n    self._exit_stack.close()\n    self.logger.info(\"Reset opened connections and their results.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.sqlalchemy_execute","title":"<code>sqlalchemy_execute</code>  <code>async</code>","text":"<p>Executes a SQL DDL or DML statement; useful for creating tables and inserting rows since this task does not return any objects.</p> <p>Parameters:</p> Name Type Description Default <code>statement</code> <code>str</code> <p>The statement to execute against the database.</p> required <code>sqlalchemy_credentials</code> <code>DatabaseCredentials</code> <p>The credentials to use to authenticate.</p> required <code>params</code> <code>Optional[Union[Tuple[Any], Dict[str, Any]]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <p>Examples:</p> <p>Create table named customers and insert values. <pre><code>from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\nfrom prefect_sqlalchemy.database import sqlalchemy_execute\nfrom prefect import flow\n\n@flow\ndef sqlalchemy_execute_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"prefect.db\",\n    )\n    sqlalchemy_execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n        sqlalchemy_credentials,\n    )\n    sqlalchemy_execute(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        sqlalchemy_credentials,\n        params={\"name\": \"Marvin\", \"address\": \"Highway 42\"}\n    )\n\nsqlalchemy_execute_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@task\nasync def sqlalchemy_execute(\n    statement: str,\n    sqlalchemy_credentials: \"DatabaseCredentials\",\n    params: Optional[Union[Tuple[Any], Dict[str, Any]]] = None,\n):\n    \"\"\"\n    Executes a SQL DDL or DML statement; useful for creating tables and inserting rows\n    since this task does not return any objects.\n\n    Args:\n        statement: The statement to execute against the database.\n        sqlalchemy_credentials: The credentials to use to authenticate.\n        params: The params to replace the placeholders in the query.\n\n    Examples:\n        Create table named customers and insert values.\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n        from prefect_sqlalchemy.database import sqlalchemy_execute\n        from prefect import flow\n\n        @flow\n        def sqlalchemy_execute_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.SQLITE_AIOSQLITE,\n                database=\"prefect.db\",\n            )\n            sqlalchemy_execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n                sqlalchemy_credentials,\n            )\n            sqlalchemy_execute(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                sqlalchemy_credentials,\n                params={\"name\": \"Marvin\", \"address\": \"Highway 42\"}\n            )\n\n        sqlalchemy_execute_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"sqlalchemy_query is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector execute_* methods instead.\",\n        DeprecationWarning,\n    )\n    # do not return anything or else results in the error:\n    # This result object does not return rows. It has been closed automatically\n    engine = sqlalchemy_credentials.get_engine()\n    async_supported = sqlalchemy_credentials._driver_is_async\n    async with _connect(engine, async_supported) as connection:\n        await _execute(connection, statement, params, async_supported)\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.sqlalchemy_query","title":"<code>sqlalchemy_query</code>  <code>async</code>","text":"<p>Executes a SQL query; useful for querying data from existing tables.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>sqlalchemy_credentials</code> <code>DatabaseCredentials</code> <p>The credentials to use to authenticate.</p> required <code>params</code> <code>Optional[Union[Tuple[Any], Dict[str, Any]]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>The number of rows to fetch. Note, this parameter is executed on the client side, i.e. passed to <code>fetchmany</code>. To limit on the server side, add the <code>LIMIT</code> clause, or the dialect's equivalent clause, like <code>TOP</code>, to the query.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The fetched results.</p> <p>Examples:</p> <p>Query postgres table with the ID value parameterized. <pre><code>from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\nfrom prefect_sqlalchemy.database import sqlalchemy_query\nfrom prefect import flow\n\n@flow\ndef sqlalchemy_query_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"prefect.db\",\n    )\n    result = sqlalchemy_query(\n        \"SELECT * FROM customers WHERE name = :name;\",\n        sqlalchemy_credentials,\n        params={\"name\": \"Marvin\"},\n    )\n    return result\n\nsqlalchemy_query_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@task\nasync def sqlalchemy_query(\n    query: str,\n    sqlalchemy_credentials: \"DatabaseCredentials\",\n    params: Optional[Union[Tuple[Any], Dict[str, Any]]] = None,\n    limit: Optional[int] = None,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a SQL query; useful for querying data from existing tables.\n\n    Args:\n        query: The query to execute against the database.\n        sqlalchemy_credentials: The credentials to use to authenticate.\n        params: The params to replace the placeholders in the query.\n        limit: The number of rows to fetch. Note, this parameter is\n            executed on the client side, i.e. passed to `fetchmany`.\n            To limit on the server side, add the `LIMIT` clause, or\n            the dialect's equivalent clause, like `TOP`, to the query.\n\n    Returns:\n        The fetched results.\n\n    Examples:\n        Query postgres table with the ID value parameterized.\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n        from prefect_sqlalchemy.database import sqlalchemy_query\n        from prefect import flow\n\n        @flow\n        def sqlalchemy_query_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.SQLITE_AIOSQLITE,\n                database=\"prefect.db\",\n            )\n            result = sqlalchemy_query(\n                \"SELECT * FROM customers WHERE name = :name;\",\n                sqlalchemy_credentials,\n                params={\"name\": \"Marvin\"},\n            )\n            return result\n\n        sqlalchemy_query_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"sqlalchemy_query is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector fetch_* methods instead.\",\n        DeprecationWarning,\n    )\n    engine = sqlalchemy_credentials.get_engine()\n    async_supported = sqlalchemy_credentials._driver_is_async\n    async with _connect(engine, async_supported) as connection:\n        result = await _execute(connection, query, params, async_supported)\n        # some databases, like sqlite, require a connection still open to fetch!\n        rows = result.fetchall() if limit is None else result.fetchmany(limit)\n    return rows\n</code></pre>"},{"location":"recipes/recipes/","title":"Prefect Recipes","text":"<p>Prefect recipes are common, extensible examples for setting up Prefect in your execution environment with ready-made ingredients such as Dockerfiles, Terraform files, and GitHub Actions.</p> <p>Recipes are useful when you are looking for tutorials on how to deploy a worker, use event-driven flows, set up unit testing, and more.</p> <p>The following are Prefect recipes specific to Prefect 2. You can find a full repository of recipes at https://github.com/PrefectHQ/prefect-recipes and additional recipes at Prefect Discourse.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#recipe-catalog","title":"Recipe catalog","text":"Agent on Azure with Kubernetes <p>                 Configure Prefect on Azure with Kubernetes, running a Prefect agent to execute deployment flow runs.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on ECS Fargate with AWS CLI <p>                 Run a Prefect 2 agent on ECS Fargate using the AWS CLI.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on ECS Fargate with Terraform <p>                 Run a Prefect 2 agent on ECS Fargate using Terraform.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on an Azure VM <p>                 Set up an Azure VM and run a Prefect agent.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Deploy a dlt pipeline on Prefect <p>                 dlt is an open-source Python library that enables the declarative loading of data sources into well-structured tables or datasets by automatically inferring and evolving schemas.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Flow Deployment with GitHub Actions <p>                 Deploy a Prefect flow with storage and infrastructure blocks, update and push Docker image to container registry.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Flow Deployment with GitHub Storage and Docker Infrastructure <p>                 Create a deployment with GitHub as a storage and Docker Container as an infrastructure             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Prefect server on an AKS Cluster <p>                 Deploy a Prefect server to an Azure Kubernetes Service (AKS) Cluster with Azure Blob Storage.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Serverless Prefect with AWS Chalice <p>                 Execute Prefect flows in an AWS Lambda function managed by Chalice.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Serverless Workflows with ECSTask Blocks <p>                 Deploy a Prefect agent to AWS ECS Fargate using GitHub Actions and ECSTask infrastructure blocks.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#contributing-recipes","title":"Contributing recipes","text":"<p>We're always looking for new recipe contributions! See the Prefect Recipes repository for details on how you can add your Prefect recipe, share best practices with fellow Prefect users, and earn some swag.</p> <p>Prefect recipes provide a vital cookbook where users can find helpful code examples and, when appropriate, common steps for specific Prefect use cases.</p> <p>We love recipes from anyone who has example code that another Prefect user can benefit from (e.g. a Prefect flow that loads data into Snowflake).</p> <p>Have a blog post, Discourse article, or tutorial you\u2019d like to share as a recipe? All submissions are welcome. Clone the prefect-recipes repo, create a branch, add a link to your recipe to the README, and submit a PR. Have more questions? Read on.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-is-a-recipe","title":"What is a recipe?","text":"<p>A Prefect recipe is like a cookbook recipe: it tells you what you need \u2014 the ingredients \u2014 and some basic steps, but assumes you can put the pieces together. Think of the Hello Fresh meal experience, but for dataflows.</p> <p>A tutorial, on the other hand, is Julia Child holding your hand through the entire cooking process: explaining each ingredient and procedure, demonstrating best practices, pointing out potential problems, and generally making sure you can\u2019t stray from the happy path to a delicious meal.</p> <p>We love Julia, and we love tutorials. But we don\u2019t expect that a Prefect recipe should handhold users through every step and possible contingency of a solution. A recipe can start from an expectation of more expertise and problem-solving ability on the part of the reader.</p> <p>To see an example of a high quality recipe, check out Serverless with AWS Chalice. This recipe includes all of the elements we like to see.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#steps-to-add-your-recipe","title":"Steps to add your recipe","text":"<p>Here\u2019s our guide to creating a recipe:</p> <pre><code># Clone the repository\ngit clone git@github.com:PrefectHQ/prefect-recipes.git\ncd prefect-recipes\n\n# Create and checkout a new branch\n\ngit checkout -b new_recipe_branch_name\n</code></pre> <ol> <li>Add your recipe. Your code may simply be a copy/paste of a single Python file or an entire folder. Unsure of where to add your file or folder? Just add under the <code>flows-advanced/</code> folder. A Prefect Recipes maintainer will help you find the best place for your recipe. Just want to direct others to a project you made, whether it be a repo or a blogpost? Simply link to it in the Prefect Recipes README!</li> <li>(Optional) Write a README.</li> <li>Include a dependencies file, if applicable.</li> <li>Push your code and make a PR to the repository.</li> </ol> <p>That\u2019s it! </p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-makes-a-good-recipe","title":"What makes a good recipe?","text":"<p>Every recipe is useful, as other Prefect users can adapt the recipe to their needs. Particularly good ones help a Prefect user bake a great dataflow solution! Take a look at the prefect-recipes repo to see some examples.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-are-the-common-ingredients-of-a-good-recipe","title":"What are the common ingredients of a good recipe?","text":"<ul> <li>Easy to understand: Can a user easily follow your recipe? Would a README or code comments help? A simple explanation providing context on how to use the example code is useful, but not required. A good README can set a recipe apart, so we have some additional suggestions for README files below.</li> <li>Code and more: Sometimes a use case is best represented in Python code or shell scripts. Sometimes a configuration file is the most important artifact \u2014 think of a Dockerfile or Terraform file for configuring infrastructure.</li> <li>All-inclusive: Share as much code as you can. Even boilerplate code like Dockerfiles or Terraform or Helm files are useful. Just don\u2019t share company secrets or IP.</li> <li>Specific: Don't worry about generalizing your code, aside from removing anything internal/secret! Other users will extrapolate their own unique solutions from your example.</li> </ul>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-are-some-tips-for-a-good-recipe-readme","title":"What are some tips for a good recipe README?","text":"<p>A thoughtful README can take a recipe from good to great. Here are some best practices that we\u2019ve found make for a great recipe README:</p> <ul> <li>Provide a brief explanation of what your recipe demonstrates. This helps users determine quickly whether the recipe is relevant to their needs or answers their questions.</li> <li>List which files are included and what each is meant to do. Each explanation can contain only a few words.</li> <li>Describe any dependencies and prerequisites (in addition to any dependencies you include in a requirements file). This includes both libraries or modules and any services your recipes depends on.</li> <li>If steps are involved or there\u2019s an order to do things, a simple list of steps is helpful.</li> <li>Bonus: troubleshooting steps you encountered to get here or tips where other users might get tripped up.</li> </ul>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#next-steps","title":"Next steps","text":"<p>We hope you\u2019ll feel comfortable sharing your Prefect solutions as recipes in the prefect-recipes repo. Collaboration and knowledge sharing are defining attributes of our Prefect Community! </p> <p>Have questions about sharing or using recipes? Reach out on our active Prefect Slack Community!</p> <p>Happy engineering!</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"tutorial/","title":"Tutorial Overview","text":"<p>Prefect orchestrates workflows \u2014 it simplifies the creation, scheduling, and monitoring of complex data pipelines. You define workflows as Python code and Prefect handles the rest.</p> <p>Prefect also provides error handling, retry mechanisms, and a user-friendly dashboard for monitoring. It's the easiest way to transform any Python function into a unit of work that can be observed and orchestrated.</p> <p>This tutorial provides a guided walk-through of Prefect's core concepts and instructions on how to use them.</p> <p>You will:</p> <ol> <li>Create a flow</li> <li>Add tasks to it</li> <li>Deploy and run the flow locally</li> <li>Create a work pool and run the flow on remote infrastructure</li> </ol> <p>These four topics will get most users to their first production deployment.</p> <p>Advanced users that need more governance and control of their workflow infrastructure can go one step further by:</p> <p>5.Using a worker-based deployment</p> <p>If you're looking for examples of more advanced operations (such as deploying on Kubernetes), check out Prefect's guides.</p> <p>Compared to the Quickstart, this tutorial is a more in-depth guide to Prefect's functionality. You will also see how to customize the Docker image where your flow runs and learn how to run flows on your own infrastructure.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/#prerequisites","title":"Prerequisites","text":"<p>Before you start, make sure you have Python installed in a virtual environment. Then install Prefect:</p> <pre><code>pip install -U prefect\n</code></pre> <p>See the install guide for more detailed instructions.</p> <p>To get the most out of Prefect, you need to connect to a forever-free Prefect Cloud account.</p> <ol> <li>Create a new account or sign in at https://app.prefect.cloud/.</li> <li>Use the <code>prefect cloud login</code> CLI command to authenticate to Prefect Cloud from your environment.</li> </ol> <pre><code>prefect cloud login\n</code></pre> <p>Choose Log in with a web browser and click the Authorize button in the browser window that opens.</p> <p>If you have any issues with browser-based authentication, see the Prefect Cloud docs to learn how to authenticate with a manually created API key.</p> <p>As an alternative to using Prefect Cloud, you can self-host a Prefect server instance. If you choose this option, run <code>prefect server start</code> to start a local Prefect server instance.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/#first-steps-flows","title":"First steps: Flows","text":"<p>Let's begin by learning how to create your first Prefect flow - click here to get started.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/deployments/","title":"Deploying Flows","text":"<p>Reminder to connect to Prefect Cloud or a self-hosted Prefect server instance</p> <p>Some features in this tutorial, such as scheduling, require you to be connected to a Prefect server. If using a self-hosted setup, run <code>prefect server start</code> to run both the webserver and UI. If using Prefect Cloud, make sure you have successfully authenticated your local environment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#why-deployments","title":"Why deployments?","text":"<p>Some of the most common reasons to use an orchestration tool such as Prefect are for scheduling and event-based triggering. Up to this point, we\u2019ve demonstrated running Prefect flows as scripts, but this means you have been the one triggering and managing flow runs. You can certainly continue to trigger your workflows in this way and use Prefect as a monitoring layer for other schedulers or systems, but you will miss out on many of the other benefits and features that Prefect offers.</p> <p>Deploying a flow exposes an API and UI so that you can:</p> <ul> <li>trigger new runs, cancel active runs, pause scheduled runs, customize parameters, and more</li> <li>remotely configure schedules and automation rules for your deployments</li> <li>dynamically provision infrastructure using workers</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#what-is-a-deployment","title":"What is a deployment?","text":"<p>Deploying a flow is the act of specifying where and how it will run. This information is encapsulated and sent to Prefect as a deployment that contains the crucial metadata needed for remote orchestration. Deployments elevate workflows from functions that you call manually to API-managed entities.</p> <p>Attributes of a deployment include (but are not limited to):</p> <ul> <li>Flow entrypoint: path to your flow function</li> <li>Schedule or Trigger: optional schedule or triggering rules for this deployment</li> <li>Tags: optional text labels for organizing your deployments</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#create-a-deployment","title":"Create a deployment","text":"<p>Using our <code>get_repo_info</code> flow from the previous sections, we can easily create a deployment for it by calling a single method on the flow object: <code>flow.serve</code>.</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.serve(name=\"my-first-deployment\")\n</code></pre> <p>Running this script will do two things:</p> <ul> <li>create a deployment called \"my-first-deployment\" for your flow in the Prefect API</li> <li>stay running to listen for flow runs for this deployment; when a run is found, it will be asynchronously executed within a subprocess</li> </ul> <p>Deployments must be defined in static files</p> <p>Flows can be defined and run interactively, that is, within REPLs or Notebooks. Deployments, on the other hand, require that your flow definition be in a known file (which can be located on a remote filesystem in certain setups, as we'll see in the next section of the tutorial).  </p> <p>Because this deployment has no schedule or triggering automation, you will need to use the UI or API to create runs for it. Let's use the CLI (in a separate terminal window) to create a run for this deployment:</p> <pre><code>prefect deployment run 'get-repo-info/my-first-deployment'\n</code></pre> <p>If you are watching either your terminal or your UI, you should see the newly created run execute successfully! Let's take this example further by adding a schedule and additional metadata.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#additional-options","title":"Additional options","text":"<p>The <code>serve</code> method on flows exposes many options for the deployment. Let's use a few of these options now:</p> <ul> <li><code>cron</code>: a keyword that allows us to set a cron string schedule for the deployment; see schedules for more advanced scheduling options</li> <li><code>tags</code>: a keyword that allows us to tag this deployment and its runs for bookkeeping and filtering purposes</li> <li><code>description</code>: a keyword that allows us to document what this deployment does; by default the description is set from the docstring of the flow function, but we did not document our flow function</li> <li><code>version</code>: a keyword that allows us to track changes to our deployment; by default a hash of the file containing the flow is used; popular options include semver tags or git commit hashes</li> </ul> <p>Let's add these options to our deployment:</p> <pre><code>if __name__ == \"__main__\":\n    get_repo_info.serve(\n        name=\"my-first-deployment\",\n        cron=\"* * * * *\",\n        tags=[\"testing\", \"tutorial\"],\n        description=\"Given a GitHub repository, logs repository statistics for that repo.\",\n        version=\"tutorial/deployments\",\n    )\n</code></pre> <p>When you rerun this script, you will find an updated deployment in the UI that is actively scheduling work! Stop the script in the CLI using <code>CTRL+C</code> and your schedule will be automatically paused.</p> <p><code>.serve</code> is a long-running process</p> <p>For remotely triggered or scheduled runs to be executed, your script with <code>flow.serve</code> must be actively running.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#running-multiple-deployments-at-once","title":"Running multiple deployments at once","text":"<p>This method is useful for creating deployments for single flows, but what if we have two or more flows?  This situation only requires a few additional method calls and imports to get up and running:</p> multi_flow_deployment.py<pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n    serve(slow_deploy, fast_deploy)\n</code></pre> <p>A few observations:</p> <ul> <li>the <code>flow.to_deployment</code> interface exposes the exact same options as <code>flow.serve</code>; this method produces a deployment object</li> <li>the deployments are only registered with the API once <code>serve(...)</code> is called</li> <li>when serving multiple deployments, the only requirement is that they share a Python environment; they can be executed and scheduled independently of each other</li> </ul> <p>Spend some time experimenting with this setup. A few potential next steps for exploration include:</p> <ul> <li>pausing and unpausing the schedule for the \"sleeper\" deployment</li> <li>using the UI to submit ad-hoc runs for the \"sleeper\" deployment with different values for <code>sleep</code></li> <li>cancelling an active run for the \"sleeper\" deployment from the UI (good luck cancelling the \"fast\" one \ud83d\ude09)</li> </ul> <p>Hybrid execution option</p> <p>Another implication of Prefect's deployment interface is that you can choose to use our hybrid execution model. Whether you use Prefect Cloud or host a Prefect server instance yourself, you can run work flows in the environments best suited to their execution. This model allows you efficient use of your infrastructure resources while maintaining the privacy of your code and data. There is no ingress required. For more information read more about our hybrid model.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#next-steps","title":"Next steps","text":"<p>Congratulations! You now have your first working deployment.</p> <p>Deploying flows through the <code>serve</code> method is a fast way to start scheduling flows with Prefect. However, if your team has more complex infrastructure requirements or you'd like to have Prefect manage flow execution, you can deploy flows to a work pool.</p> <p>Learn about work pools and how Prefect Cloud can handle infrastructure configuration for you in the next step of the tutorial.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/flows/","title":"Flows","text":"<p>Prerequisites</p> <p>This tutorial assumes you have already installed Prefect and connected to Prefect Cloud or a self-hosted server instance. See the prerequisites section of the tutorial for more details.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#what-is-a-flow","title":"What is a flow?","text":"<p>Flows are like functions. They can take inputs, perform work, and return an output. In fact, you can turn any function into a Prefect flow by adding the <code>@flow</code> decorator. When a function becomes a flow, its behavior changes, giving it the following advantages:</p> <ul> <li>All runs of the flow have persistent state. Transitions between states are recorded, allowing for flow execution to be observed and acted upon.</li> <li>Input arguments can be type validated as workflow parameters.</li> <li>Retries can be performed on failure.</li> <li>Timeouts can be enforced to prevent unintentional, long-running workflows.</li> <li>Metadata about flow runs, such as run time and final state, is automatically tracked.</li> <li>They can easily be elevated to a deployment, which exposes a remote API for interacting with it</li> </ul>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#run-your-first-flow","title":"Run your first flow","text":"<p>The simplest way to get started with Prefect is to annotate a Python function with the\u00a0<code>@flow</code>\u00a0decorator. The script below fetches statistics about the main Prefect repository. Note that httpx is an HTTP client library and a dependency of Prefect. Let's turn this function into a Prefect flow and run the script:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow\ndef get_repo_info():\n    url = \"https://api.github.com/repos/PrefectHQ/prefect\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(\"PrefectHQ/prefect repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Running this file will result in some interesting output:</p> <pre><code>12:47:42.792 | INFO | prefect.engine - Created flow run 'ludicrous-warthog' for flow 'get-repo-info'\nPrefectHQ/prefect repository statistics \ud83e\udd13:\nStars \ud83c\udf20 : 12146\nForks \ud83c\udf74 : 1245\n12:47:45.008 | INFO | Flow run 'ludicrous-warthog' - Finished in state Completed()\n</code></pre> <p>Flows can contain arbitrary Python</p> <p>As we can see above, flow definitions can contain arbitrary Python logic.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#parameters","title":"Parameters","text":"<p>As with any Python function, you can pass arguments to a flow. The positional and keyword arguments defined on your flow function are called parameters. Prefect will automatically perform type conversion using any provided type hints. Let's make the repository a string parameter with a default value:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info(repo_name=\"PrefectHQ/marvin\")\n</code></pre> <p>We can call our flow with varying values for the <code>repo_name</code> parameter (including \"bad\" values):</p> <pre><code>python repo_info.py\n</code></pre> <p>Try passing <code>repo_name=\"missing-org/missing-repo\"</code>.</p> <p>You should see</p> <pre><code>HTTPStatusError: Client error '404 Not Found' for url '&lt;https://api.github.com/repos/missing-org/missing-repo&gt;'\n</code></pre> <p>Now navigate to your Prefect dashboard and compare the displays for these two runs.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#logging","title":"Logging","text":"<p>Prefect enables you to log a variety of useful information about your flow and task runs, capturing information about your workflows for purposes such as monitoring, troubleshooting, and auditing. If we navigate to our dashboard and explore the runs we created above, we will notice that the repository statistics are not captured in the flow run logs. Let's fix that by adding some logging to our flow:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow, get_run_logger\n\n\n@flow\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    logger = get_run_logger()\n    logger.info(\"%s repository statistics \ud83e\udd13:\", repo_name)\n    logger.info(f\"Stars \ud83c\udf20 : %d\", repo[\"stargazers_count\"])\n    logger.info(f\"Forks \ud83c\udf74 : %d\", repo[\"forks_count\"])\n</code></pre> <p>Now the output looks more consistent and, more importantly, our statistics are stored in the Prefect backend and displayed in the UI for this flow run:</p> <pre><code>12:47:42.792 | INFO    | prefect.engine - Created flow run 'ludicrous-warthog' for flow 'get-repo-info'\n12:47:43.016 | INFO    | Flow run 'ludicrous-warthog' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n12:47:43.016 | INFO    | Flow run 'ludicrous-warthog' - Stars \ud83c\udf20 : 12146\n12:47:43.042 | INFO    | Flow run 'ludicrous-warthog' - Forks \ud83c\udf74 : 1245\n12:47:45.008 | INFO    | Flow run 'ludicrous-warthog' - Finished in state Completed()\n</code></pre> <p><code>log_prints=True</code></p> <p>We could have achieved the exact same outcome by using Prefect's convenient <code>log_prints</code> keyword argument in the <code>flow</code> decorator:</p> <pre><code>@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    ...\n</code></pre> <p>Logging vs Artifacts</p> <p>The example above is for educational purposes. In general, it is better to use Prefect artifacts for storing metrics and output. Logs are best for tracking progress and debugging errors.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#retries","title":"Retries","text":"<p>So far our script works, but in the future unexpected errors may occur. For example the GitHub API may be temporarily unavailable or rate limited. Retries help make our flow more resilient. Let's add retry functionality to our example above:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#next-tasks","title":"Next: Tasks","text":"<p>As you have seen, adding a flow decorator converts our Python function to a resilient and observable workflow. In the next section, you'll supercharge this flow by using tasks to break down the workflow's complexity and make it more performant and observable - click here to continue.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/tasks/","title":"Tasks","text":"","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#what-is-a-task","title":"What is a task?","text":"<p>A task is any Python function decorated with a <code>@task</code> decorator. You can think of a flow as a recipe for connecting a known sequence of tasks together. Tasks, and the dependencies between them, are displayed in the flow run graph, enabling you to break down a complex flow into something you can observe, understand and control at a more granular level. When a function becomes a task, it can be executed concurrently and its return value can be cached.</p> <p>Flows and tasks share some common features:</p> <ul> <li>Both are defined easily using their respective decorator, which accepts settings for that flow / task (see all task settings / flow settings).</li> <li>Each can be given a <code>name</code>, <code>description</code> and <code>tags</code> for organization and bookkeeping.</li> <li>Both provide functionality for retries, timeouts, and other hooks to handle failure and completion events.</li> </ul> <p>Network calls (such as our <code>GET</code> requests to the GitHub API) are particularly useful as tasks because they take advantage of task features such as retries, caching, and concurrency.</p> <p>Tasks may be called from other tasks</p> <p>As of <code>prefect 2.18.x</code>, tasks can be called from within other tasks. This removes the need to use subflows for simple task composition.</p> <p>When to use tasks</p> <p>Not all functions in a flow need be tasks. Use them only when their features are useful.</p> <p>Let's take our flow from before and move the request into a task:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow, task\nfrom typing import Optional\n\n\n@task\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    repo_stats = get_url(url)\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo_stats['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo_stats['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Running the flow in your terminal will result in something like this:</p> <pre><code>09:55:55.412 | INFO    | prefect.engine - Created flow run 'great-ammonite' for flow 'get-repo-info'\n09:55:55.499 | INFO    | Flow run 'great-ammonite' - Created task run 'get_url-0' for task 'get_url'\n09:55:55.500 | INFO    | Flow run 'great-ammonite' - Executing 'get_url-0' immediately...\n09:55:55.825 | INFO    | Task run 'get_url-0' - Finished in state Completed()\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - Stars \ud83c\udf20 : 12157\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - Forks \ud83c\udf74 : 1251\n09:55:55.849 | INFO    | Flow run 'great-ammonite' - Finished in state Completed('All states completed.')\n</code></pre> <p>And you should now see this task run tracked in the UI as well.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#caching","title":"Caching","text":"<p>Tasks support the ability to cache their return value. Caching allows you to efficiently reuse results of tasks that may be expensive to reproduce with every flow run, or reuse cached results if the inputs to a task have not changed.</p> <p>To enable caching, specify a <code>cache_key_fn</code> \u2014 a function that returns a cache key \u2014 on your task. You may optionally provide a <code>cache_expiration</code> timedelta indicating when the cache expires. You can define a task that is cached based on its inputs by using the Prefect <code>task_input_hash</code>. Let's add caching to our <code>get_url</code> task:</p> <pre><code>import httpx\nfrom datetime import timedelta\nfrom prefect import flow, task, get_run_logger\nfrom prefect.tasks import task_input_hash\nfrom typing import Optional\n\n\n@task(cache_key_fn=task_input_hash, \n      cache_expiration=timedelta(hours=1),\n      )\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n</code></pre> <p>You can test this caching behavior by using a personal repository as your workflow parameter - give it a star, or remove a star and see how the output of this task changes (or doesn't) by running your flow multiple times.</p> <p>Task results and caching</p> <p>Task results are cached in memory during a flow run and persisted to your home directory by default. Prefect Cloud only stores the cache key, not the data itself.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#concurrency","title":"Concurrency","text":"<p>Tasks enable concurrency, allowing you to execute multiple tasks asynchronously. This concurrency can greatly enhance the efficiency and performance of your workflows. Let's expand our script to calculate the average open issues per user. This will require making more requests:</p> repo_info.py<pre><code>import httpx\nfrom datetime import timedelta\nfrom prefect import flow, task\nfrom prefect.tasks import task_input_hash\nfrom typing import Optional\n\n\n@task(cache_key_fn=task_input_hash, cache_expiration=timedelta(hours=1))\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n\n\ndef get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p]\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    repo_stats = get_url(f\"https://api.github.com/repos/{repo_name}\")\n    issues = get_open_issues(repo_name, repo_stats[\"open_issues_count\"])\n    issues_per_user = len(issues) / len(set([i[\"user\"][\"id\"] for i in issues]))\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo_stats['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo_stats['forks_count']}\")\n    print(f\"Average open issues per user \ud83d\udc8c : {issues_per_user:.2f}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Now we're fetching the data we need, but the requests are happening sequentially. Tasks expose a <code>submit</code> method that changes the execution from sequential to concurrent. In our specific example, we also need to use the <code>result</code> method because we are unpacking a list of return values:</p> <pre><code>def get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url.submit(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p.result()]\n</code></pre> <p>The logs show that each task is running concurrently:</p> <pre><code>12:45:28.241 | INFO    | prefect.engine - Created flow run 'intrepid-coua' for flow 'get-repo-info'\n12:45:28.311 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-0' for task 'get_url'\n12:45:28.312 | INFO    | Flow run 'intrepid-coua' - Executing 'get_url-0' immediately...\n12:45:28.543 | INFO    | Task run 'get_url-0' - Finished in state Completed()\n12:45:28.583 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-1' for task 'get_url'\n12:45:28.584 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-1' for execution.\n12:45:28.594 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-2' for task 'get_url'\n12:45:28.594 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-2' for execution.\n12:45:28.609 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-4' for task 'get_url'\n12:45:28.610 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-4' for execution.\n12:45:28.624 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-5' for task 'get_url'\n12:45:28.625 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-5' for execution.\n12:45:28.640 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-6' for task 'get_url'\n12:45:28.641 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-6' for execution.\n12:45:28.708 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-3' for task 'get_url'\n12:45:28.708 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-3' for execution.\n12:45:29.096 | INFO    | Task run 'get_url-6' - Finished in state Completed()\n12:45:29.565 | INFO    | Task run 'get_url-2' - Finished in state Completed()\n12:45:29.721 | INFO    | Task run 'get_url-5' - Finished in state Completed()\n12:45:29.749 | INFO    | Task run 'get_url-4' - Finished in state Completed()\n12:45:29.801 | INFO    | Task run 'get_url-3' - Finished in state Completed()\n12:45:29.817 | INFO    | Task run 'get_url-1' - Finished in state Completed()\n12:45:29.820 | INFO    | Flow run 'intrepid-coua' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n12:45:29.820 | INFO    | Flow run 'intrepid-coua' - Stars \ud83c\udf20 : 12159\n12:45:29.821 | INFO    | Flow run 'intrepid-coua' - Forks \ud83c\udf74 : 1251\nAverage open issues per user \ud83d\udc8c : 2.27\n12:45:29.838 | INFO    | Flow run 'intrepid-coua' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#subflows","title":"Subflows","text":"<p>Not only can you call tasks within a flow, but you can also call other flows! Child flows are called\u00a0subflows\u00a0and allow you to efficiently manage, track, and version common multi-task logic.</p> <p>Subflows are a great way to organize your workflows and offer more visibility within the UI.</p> <p>Let's add a <code>flow</code> decorator to our <code>get_open_issues</code> function:</p> <pre><code>@flow\ndef get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url.submit(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p.result()]\n</code></pre> <p>Whenever we run the parent flow, a new run will be generated for related functions within that as well. Not only is this run tracked as a subflow run of the main flow, but you can also inspect it independently in the UI!</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#next-deployments","title":"Next: Deployments","text":"<p>We now have a flow with tasks, subflows, retries, logging, caching, and concurrent execution. In the next section, we'll see how we can deploy this flow in order to run it on a schedule and/or external infrastructure - click here to learn how to create your first deployment.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/work-pools/","title":"Work Pools","text":"","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#why-work-pools","title":"Why work pools?","text":"<p>Work pools are a bridge between the Prefect orchestration layer and infrastructure for flow runs that can be dynamically provisioned. To transition from persistent infrastructure to dynamic infrastructure, use <code>flow.deploy</code> instead of <code>flow.serve</code>.</p> <p>Choosing Between <code>flow.deploy()</code> and <code>flow.serve()</code></p> <p>Earlier in the tutorial you used <code>serve</code> to deploy your flows. For many use cases, <code>serve</code> is sufficient to meet scheduling and orchestration needs. Work pools are optional. If infrastructure needs escalate, work pools can become a handy tool. The best part? You're not locked into one method. You can seamlessly combine approaches as needed.</p> <p>Deployment definition methods differ slightly for work pools</p> <p>When you use work-pool-based execution, you define deployments differently. Deployments for workers are configured with <code>deploy</code>, which requires additional configuration. A deployment created with <code>serve</code> cannot be used with a work pool.</p> <p>The primary reason to use work pools is for dynamic infrastructure provisioning and configuration. For example, you might have a workflow that has expensive infrastructure requirements and is run infrequently. In this case, you don't want an idle process running within that infrastructure.</p> <p>Other advantages to using work pools include:</p> <ul> <li>You can configure default infrastructure configurations on your work pools that all jobs inherit and can override.</li> <li>Platform teams can use work pools to expose opinionated (and enforced!) interfaces to the infrastructure that they oversee.</li> <li>Work pools can be used to prioritize (or limit) flow runs through the use of work queues.</li> </ul> <p>Prefect provides several types of work pools. Prefect Cloud provides a Prefect Managed work pool option that is the simplest way to run workflows remotely. A cloud-provider account, such as AWS, is not required with a Prefect Managed work pool.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#set-up-a-work-pool","title":"Set up a work pool","text":"<p>Prefect Cloud</p> <p>This tutorial uses Prefect Cloud to deploy flows to work pools. Managed execution and push work pools are available in Prefect Cloud only. If you are not using Prefect Cloud, please learn about work pools below and then proceed to the next tutorial that uses worker-based work pools.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-a-prefect-managed-work-pool","title":"Create a Prefect Managed work pool","text":"<p>In your terminal, run the following command to set up a work pool named <code>my-managed-pool</code> of type <code>prefect:managed</code>.</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed \n</code></pre> <p>Let\u2019s confirm that the work pool was successfully created by running the following command.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>You should see your new <code>my-managed-pool</code> in the output list.</p> <p>Finally, let\u2019s double check that you can see this work pool in the UI.</p> <p>Navigate to the Work Pools tab and verify that you see <code>my-managed-pool</code> listed.</p> <p>Feel free to select Edit from the three-dot menu on right of the work pool card to view the details of your work pool.</p> <p>Work pools contain configuration that is used to provision infrastructure for flow runs. For example, you can specify additional Python packages or environment variables that should be set for all deployments that use this work pool. Note that individual deployments can override the work pool configuration.</p> <p>Now that you\u2019ve set up your work pool, we can deploy a flow to this work pool. Let's deploy your tutorial flow to <code>my-managed-pool</code>.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-the-deployment","title":"Create the deployment","text":"<p>From our previous steps, we now have:</p> <ol> <li>A flow</li> <li>A work pool</li> </ol> <p>Let's update our <code>repo_info.py</code> file to create a deployment in Prefect Cloud.</p> <p>The updates that we need to make to <code>repo_info.py</code> are:</p> <ol> <li>Change <code>flow.serve</code> to <code>flow.deploy</code>.</li> <li>Tell <code>flow.deploy</code> which work pool to deploy to.</li> </ol> <p>Here's what the updated <code>repo_info.py</code> looks like:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.from_source(\n        source=\"https://github.com/prefecthq/demos.git\", \n        entrypoint=\"repo_info.py:get_repo_info\"\n    ).deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-managed-pool\", \n    )\n</code></pre> <p>In the <code>from_source</code> method, we specify the source of our flow code.</p> <p>In the <code>deploy</code> method, we specify the name of our deployment and the name of the work pool that we created earlier.</p> <p>You can store your flow code in any of several types of remote storage. In this example, we use a GitHub repository, but you could use a Docker image, as you'll see in an upcoming section of the tutorial. Alternatively, you could store your flow code in cloud provider storage such as AWS S3, or within a different git-based cloud provider such as GitLab or Bitbucket.</p> <p>Note</p> <p>In the example above, we store our code in a GitHub repository. If you make changes to the flow code, you will need to push those changes to your own GitHub account and update the <code>source</code> argument of <code>from_source</code> to point to your repository.</p> <p>Now that you've updated your script, you can run it to register your deployment on Prefect Cloud:</p> <pre><code>python repo_info.py\n</code></pre> <p>You should see a message in the CLI that your deployment was created with instructions for how to run it.</p> <pre><code>Successfully created/updated all deployments!\n\n                       Deployments                       \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                              \u2503 Status  \u2503 Details \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 get-repo-info/my-first-deployment | applied \u2502         \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nTo schedule a run for this deployment, use the following command:\n\n        $ prefect deployment run 'get-repo-info/my-first-deployment'\n\n\nYou can also run your flow via the Prefect UI: https://app.prefect.cloud/account/\nabc/workspace/123/deployments/deployment/xyz\n</code></pre> <p>Navigate to your Prefect Cloud UI and view your new deployment. Click the Run button to trigger a run of your deployment.</p> <p>Because this deployment was configured with a Prefect Managed work pool, Prefect Cloud will run your flow on your behalf.</p> <p>View the logs in the UI.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#schedule-a-deployment-run","title":"Schedule a deployment run","text":"<p>Now everything is set up for us to submit a flow-run to the work pool. Go ahead and run the deployment from the CLI or the UI.</p> <pre><code>prefect deployment run 'get_repo_info/my-deployment'\n</code></pre> <p>Prefect Managed work pools are a great way to get started with Prefect. See the Managed Execution guide for more details.</p> <p>Many users will find that they need more control over the infrastructure that their flows run on. Prefect Cloud's push work pools are a popular option in those cases.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#push-work-pools-with-automatic-infrastructure-provisioning","title":"Push work pools with automatic infrastructure provisioning","text":"<p>Serverless push work pools scale infinitely and provide more configuration options than Prefect Managed work pools.</p> <p>Prefect provides push work pools for AWS ECS on Fargate, Azure Container Instances, Google Cloud Run, and Modal. To use a push work pool, you will need an account with sufficient permissions on the cloud provider that you want to use. We'll use GCP for this example.</p> <p>Setting up the cloud provider pieces for infrastructure can be tricky and time consuming. Fortunately, Prefect can automatically provision infrastructure for you and wire it all together to work with your push work pool.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-a-push-work-pool-with-automatic-infrastructure-provisioning","title":"Create a push work pool with automatic infrastructure provisioning","text":"<p>In your terminal, run the following command to set up a push work pool.</p> <p>Install the gcloud CLI and authenticate with your GCP project.</p> <p>If you already have the gcloud CLI installed, be sure to update to the latest version with <code>gcloud components update</code>.</p> <p>You will need the following permissions in your GCP project:</p> <ul> <li>resourcemanager.projects.list</li> <li>serviceusage.services.enable</li> <li>iam.serviceAccounts.create</li> <li>iam.serviceAccountKeys.create</li> <li>resourcemanager.projects.setIamPolicy</li> <li>artifactregistry.repositories.create</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Run the following command to set up a work pool named <code>my-cloud-run-pool</code> of type <code>cloud-run:push</code>.</p> <pre><code>prefect work-pool create --type cloud-run:push --provision-infra my-cloud-run-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag allows you to select a GCP project to use for your work pool and automatically configure it to be ready to execute flows via Cloud Run. In your GCP project, this command will activate the Cloud Run API, create a service account, and create a key for the service account, if they don't already exist. In your Prefect workspace, this command will create a <code>GCPCredentials</code> block for storing the service account key.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-cloud-run-pool will require:                           \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in GCP project central-kit-405415 in region us-central1                                      \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Activate the Cloud Run API for your project                                                    \u2502\n\u2502         - Activate the Artifact Registry API for your project                                            \u2502\n\u2502         - Create an Artifact Registry repository named prefect-images                                    \u2502\n\u2502         - Create a service account for managing Cloud Run jobs: prefect-cloud-run                        \u2502\n\u2502             - Service account will be granted the following roles:                                       \u2502\n\u2502                 - Service Account User                                                                   \u2502\n\u2502                 - Cloud Run Developer                                                                    \u2502\n\u2502         - Create a key for service account prefect-cloud-run                                             \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in Prefect workspace                                                                         \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Create GCP credentials block my--pool-push-pool-credentials to store the service account key   \u2502\n\u2502                                                                                                          \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nActivating Cloud Run API\nActivating Artifact Registry API\nCreating Artifact Registry repository\nConfiguring authentication to Artifact Registry\nSetting default Docker build namespace\nCreating service account\nAssigning roles to service account\nCreating service account key\nCreating GCP credentials block\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-cloud-run-pool'!\n</code></pre> <p>After infrastructure provisioning completes, you will be logged into your new Artifact Registry repository and the default Docker build namespace will be set to the URL of the repository.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the repository.</p> <p>To take advantage of this functionality, you can write your deploy script like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow running on Cloud Run!\")\n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"above-ground\",\n        cron=\"0 1 * * *\",\n        image=DeploymentImage(\n            name=\"my-image:latest\",\n            platform=\"linux/amd64\",\n        )\n    )\n</code></pre> <p>Run the script to create the deployment on the Prefect Cloud server.</p> <p>Running this script will build a Docker image with the tag <code>&lt;region&gt;-docker.pkg.dev/&lt;project&gt;/&lt;repository-name&gt;/my-image:latest</code> and push it to your repository.</p> <p>Tip</p> <p>Make sure you have Docker running locally before running this script.</p> <p>Note that you only need to include an object of the <code>DeploymentImage</code> class with the argument <code>platform=\"linux/amd64</code> if you're building your image on a machine with an ARM-based processor. Otherwise, you could just pass <code>image=\"my-image:latest\"</code> to <code>deploy</code>.</p> <p>Also note that the <code>cron</code> argument will schedule the deployment to run at 1am every day. See the schedules docs for more information on scheduling options.</p> <p>See the Push Work Pool guide for more details and example commands for each cloud provider.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#next-step","title":"Next step","text":"<p>Congratulations! You've learned how to deploy flows to work pools. If these work pool options meet all of your needs, we encourage you to go deeper with the concepts docs or explore our how-to guides to see examples of particular Prefect use cases.</p> <p>However, if you need more control over your infrastructure, want to run your workflows in Kubernetes, or are running a self-hosted Prefect server instance, we encourage you to see the next section of the tutorial. There you'll learn how to use work pools that rely on a worker and see how to customize Docker images for container-based infrastructure.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/workers/","title":"Workers","text":"","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#prerequisites","title":"Prerequisites","text":"<p>Docker installed and running on your machine.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#why-workers","title":"Why workers","text":"<p>In the previous section of the tutorial, you learned how work pools are a bridge between the Prefect orchestration layer and infrastructure for flow runs that can be dynamically provisioned. You saw how you can transition from persistent infrastructure to dynamic infrastructure by using <code>flow.deploy</code> instead of <code>flow.serve</code>.</p> <p>Work pools that rely on client-side workers take this a step further by enabling you to run work flows in your own Docker containers, Kubernetes clusters, and serverless environments such as AWS ECS, Azure Container Instances, and GCP Cloud Run.</p> <p>The architecture of a worker-based work pool deployment can be summarized with the following diagram:</p> <pre><code>graph TD\n    subgraph your_infra[\"Your Execution Environment\"]\n        worker[\"Worker\"]\n    subgraph flow_run_infra[Flow Run Infra]\n     flow_run_a((\"Flow Run A\"))\n    end\n    subgraph flow_run_infra_2[Flow Run Infra]\n     flow_run_b((\"Flow Run B\"))\n    end      \n    end\n\n    subgraph api[\"Prefect API\"]\n    Deployment --&gt; |assigned to| work_pool\n        work_pool([\"Work Pool\"])\n    end\n\n    worker --&gt; |polls| work_pool\n    worker --&gt; |creates| flow_run_infra\n    worker --&gt; |creates| flow_run_infra_2</code></pre> <p><sup>Notice above that the worker is in charge of provisioning the flow run infrastructure. In context of this tutorial, that flow run infrastructure is an ephemeral Docker container to host each flow run. Different worker types create different types of flow run infrastructure.</sup></p> <p>Now that we\u2019ve reviewed the concepts of a work pool and worker, let\u2019s create them so that you can deploy your tutorial flow, and execute it later using the Prefect API.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#set-up-a-work-pool-and-worker","title":"Set up a work pool and worker","text":"<p>For this tutorial you will create a Docker type work pool via the CLI.</p> <p>Using the Docker work pool type means that all work sent to this work pool will run within a dedicated Docker container using a Docker client available to the worker.</p> <p>Other work pool types</p> <p>There are work pool types for serverless computing environments such as AWS ECS, Azure Container Instances, Google Cloud Run, and Vertex AI. Kubernetes is also a popular work pool type.</p> <p>These options are expanded upon in various How-to Guides.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#create-a-work-pool","title":"Create a work pool","text":"<p>In your terminal, run the following command to set up a Docker type work pool.</p> <pre><code>prefect work-pool create --type docker my-docker-pool\n</code></pre> <p>Let\u2019s confirm that the work pool was successfully created by running the following command in the same terminal.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>You should see your new <code>my-docker-pool</code> listed in the output.</p> <p>Finally, let\u2019s double check that you can see this work pool in your Prefect UI.</p> <p>Navigate to the Work Pools tab and verify that you see <code>my-docker-pool</code> listed.</p> <p>When you click into <code>my-docker-pool</code> you should see a red status icon signifying that this work pool is not ready.</p> <p>To make the work pool ready, you need to start a worker.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#start-a-worker","title":"Start a worker","text":"<p>Workers are a lightweight polling process that kick off scheduled flow runs on a specific type of infrastructure (such as Docker). To start a worker on your local machine, open a new terminal and confirm that your virtual environment has <code>prefect</code> installed.</p> <p>Run the following command in this new terminal to start the worker:</p> <pre><code>prefect worker start --pool my-docker-pool\n</code></pre> <p>You should see the worker start. It's now polling the Prefect API to check for any scheduled flow runs it should pick up and then submit for execution. You\u2019ll see your new worker listed in the UI under the Workers tab of the Work Pools page with a recent last polled date.</p> <p>You should also be able to see a <code>Ready</code> status indicator on your work pool - progress!</p> <p>You will need to keep this terminal session active for the worker to continue to pick up jobs. Since you are running this worker locally, the worker will terminate if you close the terminal. Therefore, in a production setting this worker should run as a daemonized or managed process.</p> <p>Now that you\u2019ve set up your work pool and worker, we have what we need to kick off and execute flow runs of flows deployed to this work pool. Let's deploy your tutorial flow to <code>my-docker-pool</code>.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#create-the-deployment","title":"Create the deployment","text":"<p>From our previous steps, we now have:</p> <ol> <li>A flow</li> <li>A work pool</li> <li>A worker</li> </ol> <p>Now it\u2019s time to put it all together. We're going to update our <code>repo_info.py</code> file to build a Docker image and update our deployment so our worker can execute it.</p> <p>The updates that you need to make to <code>repo_info.py</code> are:</p> <ol> <li>Change <code>flow.serve</code> to <code>flow.deploy</code>.</li> <li>Tell <code>flow.deploy</code> which work pool to deploy to.</li> <li>Tell <code>flow.deploy</code> the name to use for the Docker image that will be built.</li> </ol> <p>Here's what the updated <code>repo_info.py</code> looks like:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my-first-deployment-image:tutorial\",\n        push=False\n    )\n</code></pre> <p>Why the <code>push=False</code>?</p> <p>For this tutorial, your Docker worker is running on your machine, so we don't need to push the image built by <code>flow.deploy</code> to a registry. When your worker is running on a remote machine, you will need to push the image to a registry that the worker can access.</p> <p>Remove the <code>push=False</code> argument, include your registry name, and ensure you've authenticated with the Docker CLI to push the image to a registry.</p> <p>Now that you've updated your script, you can run it to deploy your flow to the work pool:</p> <pre><code>python repo_info.py\n</code></pre> <p>Prefect will build a custom Docker image containing your workflow code that the worker can use to dynamically spawn Docker containers whenever this workflow needs to run.</p> <p>What Dockerfile?</p> <p>In this example, Prefect generates a Dockerfile for you that will build an image based off of one of Prefect's published images. The generated Dockerfile will copy the current directory into the Docker image and install any dependencies listed in a <code>requirements.txt</code> file.</p> <p>If you want to use a custom Dockerfile, you can specify the path to the Dockerfile using the <code>DeploymentImage</code> class:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=DeploymentImage(\n            name=\"my-first-deployment-image\",\n            tag=\"tutorial\",\n            dockerfile=\"Dockerfile\"\n        ),\n        push=False\n    )\n</code></pre>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#modify-the-deployment","title":"Modify the deployment","text":"<p>If you need to make updates to your deployment, you can do so by modifying your script and rerunning it. You'll need to make one update to specify a value for <code>job_variables</code> to ensure your Docker worker can successfully execute scheduled runs for this flow. See the example below.</p> <p>The <code>job_variables</code> section allows you to fine-tune the infrastructure settings for a specific deployment. These values override default values in the specified work pool's base job template.</p> <p>When testing images locally without pushing them to a registry (to avoid potential errors like docker.errors.NotFound), it's recommended to include an <code>image_pull_policy</code> job_variable set to <code>Never</code>. However, for production workflows, always consider pushing images to a remote registry for more reliability and accessibility.</p> <p>Here's how you can quickly set the <code>image_pull_policy</code> to be <code>Never</code> for this tutorial deployment without affecting the default value set on your work pool:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"image_pull_policy\": \"Never\"},\n        image=\"my-first-deployment-image:tutorial\",\n        push=False\n    )\n</code></pre> <p>To register this update to your deployment's parameters with Prefect's API, run:</p> <pre><code>python repo_info.py\n</code></pre> <p>Now everything is set for us to submit a flow-run to the work pool:</p> <pre><code>prefect deployment run 'get_repo_info/my-deployment'\n</code></pre> <p>Common Pitfall</p> <ul> <li>Store and run your deploy scripts at the root of your repo, otherwise the built Docker file may be missing files that it needs to execute!</li> </ul> <p>Did you know?</p> <p>A Prefect flow can have more than one deployment.  This pattern can be useful if you want your flow to run in different execution environments.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#next-steps","title":"Next steps","text":"<ul> <li>Go deeper with deployments and learn about configuring deployments in YAML with <code>prefect.yaml</code>.</li> <li>Concepts contain deep dives into Prefect components.</li> <li>Guides provide step-by-step recipes for common Prefect operations including:</li> <li>Deploying flows on Kubernetes</li> <li>Deploying flows in Docker</li> <li>Deploying flows on serverless infrastructure</li> <li>Daemonizing workers</li> </ul> <p>Happy building!</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to Prefect","text":"<p>Prefect is a workflow orchestration framework for building resilient data pipelines in Python.</p> <p>It's the easiest way to transform any Python function into a unit of work that can be observed and orchestrated. Just bring your Python code, sprinkle in a few decorators, and go!</p> <p>With Prefect you gain:</p> <ul> <li>  scheduling  </li> <li>  retries  </li> <li>  logging  </li> <li>  convenient async functionality </li> <li>  caching </li> <li>  notifications </li> <li>  observability </li> <li>  event-based orchestration </li> </ul> <p></p>","tags":["getting started","quick start","overview"],"boost":2},{"location":"#new-to-prefect","title":"New to Prefect?","text":"<p>Get up and running quickly with the quickstart guide.</p> <p>Want more hands on practice to productionize your workflows? Follow our tutorial.</p> <p>For deeper dives into common use cases, explore our guides.</p> <p>Take your understanding even further with Prefect's concepts and API reference.</p> <p>Join Prefect's vibrant community of over 26,000 engineers to learn with others and share your knowledge!</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["getting started","quick start","overview"],"boost":2},{"location":"faq/","title":"Frequently Asked Questions","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#prefect","title":"Prefect","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#how-is-prefect-licensed","title":"How is Prefect licensed?","text":"<p>Prefect is licensed under the Apache 2.0 License, an OSI approved open-source license. If you have any questions about licensing, please contact us.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#is-the-prefect-v2-cloud-url-different-than-the-prefect-v1-cloud-url","title":"Is the Prefect v2 Cloud URL different than the Prefect v1 Cloud URL?","text":"<p>Yes. Prefect Cloud for v2 is at app.prefect.cloud/ while Prefect Cloud for v1 is at cloud.prefect.io.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#the-prefect-orchestration-engine","title":"The Prefect Orchestration Engine","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#why-was-the-prefect-orchestration-engine-created","title":"Why was the Prefect orchestration engine created?","text":"<p>The Prefect orchestration engine has three major objectives:</p> <ul> <li>Embracing dynamic, DAG-free workflows</li> <li>An extraordinary developer experience</li> <li>Transparent and observable orchestration rules</li> </ul> <p>As Prefect has matured, so has the modern data stack. The on-demand, dynamic, highly scalable workflows that used to exist principally in the domain of data science and analytics are now prevalent throughout all of data engineering. Few companies have workflows that don\u2019t deal with streaming data, uncertain timing, runtime logic, complex dependencies, versioning, or custom scheduling.</p> <p>This means that the current generation of workflow managers are built around the wrong abstraction: the directed acyclic graph (DAG). DAGs are an increasingly arcane, constrained way of representing the dynamic, heterogeneous range of modern data and computation patterns.</p> <p>Furthermore, as workflows have become more complex, it has become even more important to focus on the developer experience of building, testing, and monitoring them. Faced with an explosion of available tools, it is more important than ever for development teams to seek orchestration tools that will be compatible with any code, tools, or services they may require in the future.</p> <p>And finally, this additional complexity means that providing clear and consistent insight into the behavior of the orchestration engine and any decisions it makes is critically important.</p> <p>The Prefect orchestration engine represents a unified solution to these three problems.</p> <p>The Prefect orchestration engine is capable of governing any code through a well-defined series of state transitions designed to maximize the user's understanding of what happened during execution. It's popular to describe \"workflows as code\" or \"orchestration as code,\" but the Prefect engine represents \"code as workflows\": rather than ask users to change how they work to meet the requirements of the orchestrator, we've defined an orchestrator that adapts to how our users work.</p> <p>To achieve this, we've leveraged the familiar tools of native Python: first class functions, type annotations, and <code>async</code> support. Users are free to implement as much \u2014 or as little \u2014 of the Prefect engine as is useful for their objectives.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#if-im-using-prefect-cloud-2-do-i-still-need-to-run-a-prefect-server-locally","title":"If I\u2019m using Prefect Cloud 2, do I still need to run a Prefect server locally?","text":"<p>No, Prefect Cloud hosts an instance of the Prefect API for you. In fact, each workspace in Prefect Cloud corresponds directly to a single instance of the Prefect orchestration engine. See the Prefect Cloud Overview for more information.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#features","title":"Features","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#does-prefect-support-mapping","title":"Does Prefect support mapping?","text":"<p>Yes! For more information, see the <code>Task.map</code> API reference</p> <pre><code>@flow\ndef my_flow():\n\n    # map over a constant\n    for i in range(10):\n        my_mapped_task(i)\n\n    # map over a task's output\n    l = list_task()\n    for i in l.wait().result():\n        my_mapped_task_2(i)\n</code></pre> <p>Note that when tasks are called on constant values, they cannot detect their upstream edges automatically. In this example, <code>my_mapped_task_2</code> does not know that it is downstream from <code>list_task()</code>. Prefect will have convenience functions for detecting these associations, and Prefect's <code>.map()</code> operator will automatically track them.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-enforce-ordering-between-tasks-that-dont-share-data","title":"Can I enforce ordering between tasks that don't share data?","text":"<p>Yes! For more information, see the <code>Tasks</code> section.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#does-prefect-support-proxies","title":"Does Prefect support proxies?","text":"<p>Yes!</p> <p>Prefect supports communicating via proxies through the use of environment variables. You can read more about this in the Installation documentation and the article Using Prefect Cloud with proxies.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-run-prefect-flows-on-linux","title":"Can I run Prefect flows on Linux?","text":"<p>Yes! </p> <p>See the Installation documentation and Linux installation notes for details on getting started with Prefect on Linux.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-run-prefect-flows-on-windows","title":"Can I run Prefect flows on Windows?","text":"<p>Yes!</p> <p>See the Installation documentation and Windows installation notes for details on getting started with Prefect on Windows.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#what-external-requirements-does-prefect-have","title":"What external requirements does Prefect have?","text":"<p>Prefect does not have any additional requirements besides those installed by <code>pip install --pre prefect</code>. The entire system, including the UI and services, can be run in a single process via <code>prefect server start</code> and does not require Docker.</p> <p>Prefect Cloud users do not need to worry about the Prefect database. Prefect Cloud uses PostgreSQL on GCP behind the scenes. To use PostgreSQL with a self-hosted Prefect server, users must provide the connection string for a running database via the <code>PREFECT_API_DATABASE_CONNECTION_URL</code> environment variable.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#what-databases-does-prefect-support","title":"What databases does Prefect support?","text":"<p>A self-hosted Prefect server can work with SQLite and PostgreSQL. New Prefect installs default to a SQLite database hosted at <code>~/.prefect/prefect.db</code> on Mac or Linux machines. SQLite and PostgreSQL are not installed by Prefect.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#how-do-i-choose-between-sqlite-and-postgres","title":"How do I choose between SQLite and Postgres?","text":"<p>SQLite generally works well for getting started and exploring Prefect. We have tested it with up to hundreds of thousands of task runs. Many users may be able to stay on SQLite for some time. However, for production uses, Prefect Cloud or self-hosted PostgreSQL is highly recommended. Under write-heavy workloads, SQLite performance can begin to suffer. Users running many flows with high degrees of parallelism or concurrency should use PostgreSQL.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#relationship-with-other-prefect-products","title":"Relationship with other Prefect products","text":"","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-a-flow-written-with-prefect-1-be-orchestrated-with-prefect-2-and-vice-versa","title":"Can a flow written with Prefect 1 be orchestrated with Prefect 2 and vice versa?","text":"<p>No. Flows written with the Prefect 1 client must be rewritten with the Prefect 2 client. For most flows, this should take just a few minutes. </p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"faq/#can-i-use-prefect-1-and-prefect-2-at-the-same-time-on-my-local-machine","title":"Can I use Prefect 1 and Prefect 2 at the same time on my local machine?","text":"<p>Yes. Just use different virtual environments.</p>","tags":["FAQ","frequently asked questions","questions","license","databases"]},{"location":"api-ref/","title":"API Reference","text":"<p>Prefect auto-generates reference documentation for the following components:</p> <ul> <li>Prefect Python SDK: used to build, test, and execute workflows.</li> <li>Prefect REST API: used by both workflow clients as well as the Prefect UI for orchestration and data retrieval</li> <li>Prefect Cloud REST API documentation is available at https://app.prefect.cloud/api/docs.</li> <li>The REST API documentation for a locally hosted open-source Prefect server is available in the Prefect REST API Reference.</li> <li>Prefect Server SDK: used primarily by the server to work with workflow metadata and enforce orchestration logic. This is only used directly by Prefect developers and contributors.</li> </ul> <p>Self-hosted docs</p> <p>When self-hosting, you can access REST API documentation at the <code>/docs</code> endpoint of your <code>PREFECT_API_URL</code> - for example, if you ran <code>prefect server start</code> with no additional configuration you can find this reference at http://localhost:4200/docs.</p>","tags":["API","Prefect API","Prefect SDK","Prefect Cloud","REST API","development","orchestration"]},{"location":"api-ref/rest-api-reference/","title":"Prefect server REST API reference","text":"","tags":["REST API","Prefect server"]},{"location":"api-ref/prefect/agent/","title":"prefect.agent","text":"","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent","title":"<code>prefect.agent</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. Agents have been replaced by workers, which offer enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent","title":"<code>PrefectAgent</code>","text":"Source code in <code>prefect/agent.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use a worker instead. Refer to the upgrade guide for more information: https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass PrefectAgent:\n    def __init__(\n        self,\n        work_queues: List[str] = None,\n        work_queue_prefix: Union[str, List[str]] = None,\n        work_pool_name: str = None,\n        prefetch_seconds: int = None,\n        default_infrastructure: Infrastructure = None,\n        default_infrastructure_document_id: UUID = None,\n        limit: Optional[int] = None,\n    ) -&gt; None:\n        if default_infrastructure and default_infrastructure_document_id:\n            raise ValueError(\n                \"Provide only one of 'default_infrastructure' and\"\n                \" 'default_infrastructure_document_id'.\"\n            )\n\n        self.work_queues: Set[str] = set(work_queues) if work_queues else set()\n        self.work_pool_name = work_pool_name\n        self.prefetch_seconds = prefetch_seconds\n        self.submitting_flow_run_ids = set()\n        self.cancelling_flow_run_ids = set()\n        self.scheduled_task_scopes = set()\n        self.started = False\n        self.logger = get_logger(\"agent\")\n        self.task_group: Optional[anyio.abc.TaskGroup] = None\n        self.limit: Optional[int] = limit\n        self.limiter: Optional[anyio.CapacityLimiter] = None\n        self.client: Optional[PrefectClient] = None\n\n        if isinstance(work_queue_prefix, str):\n            work_queue_prefix = [work_queue_prefix]\n        self.work_queue_prefix = work_queue_prefix\n\n        self._work_queue_cache_expiration: pendulum.DateTime = None\n        self._work_queue_cache: List[WorkQueue] = []\n\n        if default_infrastructure:\n            self.default_infrastructure_document_id = (\n                default_infrastructure._block_document_id\n            )\n            self.default_infrastructure = default_infrastructure\n        elif default_infrastructure_document_id:\n            self.default_infrastructure_document_id = default_infrastructure_document_id\n            self.default_infrastructure = None\n        else:\n            self.default_infrastructure = Process()\n            self.default_infrastructure_document_id = None\n\n    async def update_matched_agent_work_queues(self):\n        if self.work_queue_prefix:\n            if self.work_pool_name:\n                matched_queues = await self.client.read_work_queues(\n                    work_pool_name=self.work_pool_name,\n                    work_queue_filter=WorkQueueFilter(\n                        name=WorkQueueFilterName(startswith_=self.work_queue_prefix)\n                    ),\n                )\n            else:\n                matched_queues = await self.client.match_work_queues(\n                    self.work_queue_prefix, work_pool_name=DEFAULT_AGENT_WORK_POOL_NAME\n                )\n\n            matched_queues = set(q.name for q in matched_queues)\n            if matched_queues != self.work_queues:\n                new_queues = matched_queues - self.work_queues\n                removed_queues = self.work_queues - matched_queues\n                if new_queues:\n                    self.logger.info(\n                        f\"Matched new work queues: {', '.join(new_queues)}\"\n                    )\n                if removed_queues:\n                    self.logger.info(\n                        f\"Work queues no longer matched: {', '.join(removed_queues)}\"\n                    )\n            self.work_queues = matched_queues\n\n    async def get_work_queues(self) -&gt; AsyncIterator[WorkQueue]:\n        \"\"\"\n        Loads the work queue objects corresponding to the agent's target work\n        queues. If any of them don't exist, they are created.\n        \"\"\"\n\n        # if the queue cache has not expired, yield queues from the cache\n        now = pendulum.now(\"UTC\")\n        if (self._work_queue_cache_expiration or now) &gt; now:\n            for queue in self._work_queue_cache:\n                yield queue\n            return\n\n        # otherwise clear the cache, set the expiration for 30 seconds, and\n        # reload the work queues\n        self._work_queue_cache.clear()\n        self._work_queue_cache_expiration = now.add(seconds=30)\n\n        await self.update_matched_agent_work_queues()\n\n        for name in self.work_queues:\n            try:\n                work_queue = await self.client.read_work_queue_by_name(\n                    work_pool_name=self.work_pool_name, name=name\n                )\n            except (ObjectNotFound, Exception):\n                work_queue = None\n\n            # if the work queue wasn't found and the agent is NOT polling\n            # for queues using a regex, try to create it\n            if work_queue is None and not self.work_queue_prefix:\n                try:\n                    work_queue = await self.client.create_work_queue(\n                        work_pool_name=self.work_pool_name, name=name\n                    )\n                except Exception:\n                    # if creating it raises an exception, it was probably just\n                    # created by some other agent; rather than entering a re-read\n                    # loop with new error handling, we log the exception and\n                    # continue.\n                    self.logger.exception(f\"Failed to create work queue {name!r}.\")\n                    continue\n                else:\n                    log_str = f\"Created work queue {name!r}\"\n                    if self.work_pool_name:\n                        log_str = (\n                            f\"Created work queue {name!r} in work pool\"\n                            f\" {self.work_pool_name!r}.\"\n                        )\n                    else:\n                        log_str = f\"Created work queue '{name}'.\"\n                    self.logger.info(log_str)\n\n            if work_queue is None:\n                self.logger.error(\n                    f\"Work queue '{name!r}' with prefix {self.work_queue_prefix} wasn't\"\n                    \" found\"\n                )\n            else:\n                self._work_queue_cache.append(work_queue)\n                yield work_queue\n\n    async def get_and_submit_flow_runs(self) -&gt; List[FlowRun]:\n        \"\"\"\n        The principle method on agents. Queries for scheduled flow runs and submits\n        them for execution in parallel.\n        \"\"\"\n        if not self.started:\n            raise RuntimeError(\n                \"Agent is not started. Use `async with PrefectAgent()...`\"\n            )\n\n        self.logger.debug(\"Checking for scheduled flow runs...\")\n\n        before = pendulum.now(\"utc\").add(\n            seconds=self.prefetch_seconds or PREFECT_AGENT_PREFETCH_SECONDS.value()\n        )\n\n        submittable_runs: List[FlowRun] = []\n\n        if self.work_pool_name:\n            responses = await self.client.get_scheduled_flow_runs_for_work_pool(\n                work_pool_name=self.work_pool_name,\n                work_queue_names=[wq.name async for wq in self.get_work_queues()],\n                scheduled_before=before,\n            )\n            submittable_runs.extend([response.flow_run for response in responses])\n\n        else:\n            # load runs from each work queue\n            async for work_queue in self.get_work_queues():\n                # print a nice message if the work queue is paused\n                if work_queue.is_paused:\n                    self.logger.info(\n                        f\"Work queue {work_queue.name!r} ({work_queue.id}) is paused.\"\n                    )\n\n                else:\n                    try:\n                        queue_runs = await self.client.get_runs_in_work_queue(\n                            id=work_queue.id, limit=10, scheduled_before=before\n                        )\n                        submittable_runs.extend(queue_runs)\n                    except ObjectNotFound:\n                        self.logger.error(\n                            f\"Work queue {work_queue.name!r} ({work_queue.id}) not\"\n                            \" found.\"\n                        )\n                    except Exception as exc:\n                        self.logger.exception(exc)\n\n            submittable_runs.sort(key=lambda run: run.next_scheduled_start_time)\n\n        for flow_run in submittable_runs:\n            # don't resubmit a run\n            if flow_run.id in self.submitting_flow_run_ids:\n                continue\n\n            try:\n                if self.limiter:\n                    self.limiter.acquire_on_behalf_of_nowait(flow_run.id)\n            except anyio.WouldBlock:\n                self.logger.info(\n                    f\"Flow run limit reached; {self.limiter.borrowed_tokens} flow runs\"\n                    \" in progress.\"\n                )\n                break\n            else:\n                self.logger.info(f\"Submitting flow run '{flow_run.id}'\")\n                self.submitting_flow_run_ids.add(flow_run.id)\n                self.task_group.start_soon(\n                    self.submit_run,\n                    flow_run,\n                )\n\n        return list(\n            filter(lambda run: run.id in self.submitting_flow_run_ids, submittable_runs)\n        )\n\n    async def check_for_cancelled_flow_runs(self):\n        if not self.started:\n            raise RuntimeError(\n                \"Agent is not started. Use `async with PrefectAgent()...`\"\n            )\n\n        self.logger.debug(\"Checking for cancelled flow runs...\")\n\n        work_queue_filter = (\n            WorkQueueFilter(name=WorkQueueFilterName(any_=list(self.work_queues)))\n            if self.work_queues\n            else None\n        )\n\n        work_pool_filter = (\n            WorkPoolFilter(name=WorkPoolFilterName(any_=[self.work_pool_name]))\n            if self.work_pool_name\n            else WorkPoolFilter(name=WorkPoolFilterName(any_=[\"default-agent-pool\"]))\n        )\n        named_cancelling_flow_runs = await self.client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self.cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=work_pool_filter,\n            work_queue_filter=work_queue_filter,\n        )\n\n        typed_cancelling_flow_runs = await self.client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self.cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=work_pool_filter,\n            work_queue_filter=work_queue_filter,\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self.logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self.cancelling_flow_run_ids.add(flow_run.id)\n            self.task_group.start_soon(self.cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def cancel_run(self, flow_run: FlowRun) -&gt; None:\n        \"\"\"\n        Cancel a flow run by killing its infrastructure\n        \"\"\"\n        if not flow_run.infrastructure_pid:\n            self.logger.error(\n                f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n                \" attached. Cancellation cannot be guaranteed.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure tracking information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            infrastructure = await self.get_infrastructure(flow_run)\n            if infrastructure.is_using_a_runner:\n                self.logger.info(\n                    f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                    \" using enhanced cancellation. A dedicated runner will handle\"\n                    \" cancellation.\"\n                )\n                return\n        except Exception:\n            self.logger.exception(\n                f\"Failed to get infrastructure for flow run '{flow_run.id}'. \"\n                \"Flow run cannot be cancelled.\"\n            )\n            # Note: We leave this flow run in the cancelling set because it cannot be\n            #       cancelled and this will prevent additional attempts.\n            return\n\n        if not hasattr(infrastructure, \"kill\"):\n            self.logger.error(\n                f\"Flow run '{flow_run.id}' infrastructure {infrastructure.type!r} \"\n                \"does not support killing created infrastructure. \"\n                \"Cancellation cannot be guaranteed.\"\n            )\n            return\n\n        self.logger.info(\n            f\"Killing {infrastructure.type} {flow_run.infrastructure_pid} for flow run \"\n            f\"'{flow_run.id}'...\"\n        )\n        try:\n            await infrastructure.kill(flow_run.infrastructure_pid)\n        except InfrastructureNotFound as exc:\n            self.logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except InfrastructureNotAvailable as exc:\n            self.logger.warning(f\"{exc} Flow run cannot be cancelled by this agent.\")\n        except Exception:\n            self.logger.exception(\n                \"Encountered exception while killing infrastructure for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self.cancelling_flow_run_ids.remove(flow_run.id)\n            return\n        else:\n            await self._mark_flow_run_as_cancelled(flow_run)\n            self.logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: FlowRun, state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self.client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self.cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def get_infrastructure(self, flow_run: FlowRun) -&gt; Infrastructure:\n        deployment = await self.client.read_deployment(flow_run.deployment_id)\n\n        flow = await self.client.read_flow(deployment.flow_id)\n\n        # overrides only apply when configuring known infra blocks\n        if not deployment.infrastructure_document_id:\n            if self.default_infrastructure:\n                infra_block = self.default_infrastructure\n            else:\n                infra_document = await self.client.read_block_document(\n                    self.default_infrastructure_document_id\n                )\n                infra_block = Block._from_block_document(infra_document)\n\n            # Add flow run metadata to the infrastructure\n            prepared_infrastructure = infra_block.prepare_for_flow_run(\n                flow_run, deployment=deployment, flow=flow\n            )\n            return prepared_infrastructure\n\n        ## get infra\n        infra_document = await self.client.read_block_document(\n            deployment.infrastructure_document_id\n        )\n\n        # this piece of logic applies any overrides that may have been set on the\n        # deployment; overrides are defined as dot.delimited paths on possibly nested\n        # attributes of the infrastructure block\n        doc_dict = infra_document.dict()\n        infra_dict = doc_dict.get(\"data\", {})\n        for override, value in (deployment.job_variables or {}).items():\n            nested_fields = override.split(\".\")\n            data = infra_dict\n            for field in nested_fields[:-1]:\n                data = data[field]\n\n            # once we reach the end, set the value\n            data[nested_fields[-1]] = value\n\n        # reconstruct the infra block\n        doc_dict[\"data\"] = infra_dict\n        infra_document = BlockDocument(**doc_dict)\n        infrastructure_block = Block._from_block_document(infra_document)\n\n        # TODO: Here the agent may update the infrastructure with agent-level settings\n\n        # Add flow run metadata to the infrastructure\n        prepared_infrastructure = infrastructure_block.prepare_for_flow_run(\n            flow_run, deployment=deployment, flow=flow\n        )\n\n        return prepared_infrastructure\n\n    async def submit_run(self, flow_run: FlowRun) -&gt; None:\n        \"\"\"\n        Submit a flow run to the infrastructure\n        \"\"\"\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            try:\n                infrastructure = await self.get_infrastructure(flow_run)\n            except Exception as exc:\n                self.logger.exception(\n                    f\"Failed to get infrastructure for flow run '{flow_run.id}'.\"\n                )\n                await self._propose_failed_state(flow_run, exc)\n                if self.limiter:\n                    self.limiter.release_on_behalf_of(flow_run.id)\n            else:\n                # Wait for submission to be completed. Note that the submission function\n                # may continue to run in the background after this exits.\n                readiness_result = await self.task_group.start(\n                    self._submit_run_and_capture_errors, flow_run, infrastructure\n                )\n\n                if readiness_result and not isinstance(readiness_result, Exception):\n                    try:\n                        await self.client.update_flow_run(\n                            flow_run_id=flow_run.id,\n                            infrastructure_pid=str(readiness_result),\n                        )\n                    except Exception:\n                        self.logger.exception(\n                            \"An error occurred while setting the `infrastructure_pid`\"\n                            f\" on flow run {flow_run.id!r}. The flow run will not be\"\n                            \" cancellable.\"\n                        )\n\n                self.logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n\n        self.submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self,\n        flow_run: FlowRun,\n        infrastructure: Infrastructure,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; Union[InfrastructureResult, Exception]:\n        # Note: There is not a clear way to determine if task_status.started() has been\n        #       called without peeking at the internal `_future`. Ideally we could just\n        #       check if the flow run id has been removed from `submitting_flow_run_ids`\n        #       but it is not so simple to guarantee that this coroutine yields back\n        #       to `submit_run` to execute that line when exceptions are raised during\n        #       submission.\n        try:\n            result = await infrastructure.run(task_status=task_status)\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                self.logger.exception(\n                    f\"Failed to submit flow run '{flow_run.id}' to infrastructure.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run could not be submitted to infrastructure\"\n                )\n            else:\n                self.logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n\n        if not task_status._future.done():\n            self.logger.error(\n                f\"Infrastructure returned without reporting flow run '{flow_run.id}' \"\n                \"as started or raising an error. This behavior is not expected and \"\n                \"generally indicates improper implementation of infrastructure. The \"\n                \"flow run will not be marked as failed, but an issue may have occurred.\"\n            )\n            # Mark the task as started to prevent agent crash\n            task_status.started()\n\n        if result.status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                (\n                    \"Flow run infrastructure exited with non-zero status code\"\n                    f\" {result.status_code}.\"\n                ),\n            )\n\n        return result\n\n    async def _propose_pending_state(self, flow_run: FlowRun) -&gt; bool:\n        state = flow_run.state\n        try:\n            state = await propose_state(self.client, Pending(), flow_run_id=flow_run.id)\n        except Abort as exc:\n            self.logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            self.logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n            return False\n\n        if not state.is_pending():\n            self.logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: FlowRun, exc: Exception) -&gt; None:\n        try:\n            await propose_state(\n                self.client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            self.logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: FlowRun, message: str) -&gt; None:\n        try:\n            state = await propose_state(\n                self.client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            self.logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                self.logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the agent exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.started:\n                with anyio.CancelScope() as scope:\n                    self.scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self.scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self.task_group.start(wrapper)\n\n    # Context management ---------------------------------------------------------------\n\n    async def start(self):\n        self.started = True\n        self.task_group = anyio.create_task_group()\n        self.limiter = (\n            anyio.CapacityLimiter(self.limit) if self.limit is not None else None\n        )\n        self.client = get_client()\n        await self.client.__aenter__()\n        await self.task_group.__aenter__()\n\n    async def shutdown(self, *exc_info):\n        self.started = False\n        # We must cancel scheduled task scopes before closing the task group\n        for scope in self.scheduled_task_scopes:\n            scope.cancel()\n        await self.task_group.__aexit__(*exc_info)\n        await self.client.__aexit__(*exc_info)\n        self.task_group = None\n        self.client = None\n        self.submitting_flow_run_ids.clear()\n        self.cancelling_flow_run_ids.clear()\n        self.scheduled_task_scopes.clear()\n        self._work_queue_cache_expiration = None\n        self._work_queue_cache = []\n\n    async def __aenter__(self):\n        await self.start()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        await self.shutdown(*exc_info)\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.cancel_run","title":"<code>cancel_run</code>  <code>async</code>","text":"<p>Cancel a flow run by killing its infrastructure</p> Source code in <code>prefect/agent.py</code> <pre><code>async def cancel_run(self, flow_run: FlowRun) -&gt; None:\n    \"\"\"\n    Cancel a flow run by killing its infrastructure\n    \"\"\"\n    if not flow_run.infrastructure_pid:\n        self.logger.error(\n            f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n            \" attached. Cancellation cannot be guaranteed.\"\n        )\n        await self._mark_flow_run_as_cancelled(\n            flow_run,\n            state_updates={\n                \"message\": (\n                    \"This flow run is missing infrastructure tracking information\"\n                    \" and cancellation cannot be guaranteed.\"\n                )\n            },\n        )\n        return\n\n    try:\n        infrastructure = await self.get_infrastructure(flow_run)\n        if infrastructure.is_using_a_runner:\n            self.logger.info(\n                f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                \" using enhanced cancellation. A dedicated runner will handle\"\n                \" cancellation.\"\n            )\n            return\n    except Exception:\n        self.logger.exception(\n            f\"Failed to get infrastructure for flow run '{flow_run.id}'. \"\n            \"Flow run cannot be cancelled.\"\n        )\n        # Note: We leave this flow run in the cancelling set because it cannot be\n        #       cancelled and this will prevent additional attempts.\n        return\n\n    if not hasattr(infrastructure, \"kill\"):\n        self.logger.error(\n            f\"Flow run '{flow_run.id}' infrastructure {infrastructure.type!r} \"\n            \"does not support killing created infrastructure. \"\n            \"Cancellation cannot be guaranteed.\"\n        )\n        return\n\n    self.logger.info(\n        f\"Killing {infrastructure.type} {flow_run.infrastructure_pid} for flow run \"\n        f\"'{flow_run.id}'...\"\n    )\n    try:\n        await infrastructure.kill(flow_run.infrastructure_pid)\n    except InfrastructureNotFound as exc:\n        self.logger.warning(f\"{exc} Marking flow run as cancelled.\")\n        await self._mark_flow_run_as_cancelled(flow_run)\n    except InfrastructureNotAvailable as exc:\n        self.logger.warning(f\"{exc} Flow run cannot be cancelled by this agent.\")\n    except Exception:\n        self.logger.exception(\n            \"Encountered exception while killing infrastructure for flow run \"\n            f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n        )\n        # We will try again on generic exceptions\n        self.cancelling_flow_run_ids.remove(flow_run.id)\n        return\n    else:\n        await self._mark_flow_run_as_cancelled(flow_run)\n        self.logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.get_and_submit_flow_runs","title":"<code>get_and_submit_flow_runs</code>  <code>async</code>","text":"<p>The principle method on agents. Queries for scheduled flow runs and submits them for execution in parallel.</p> Source code in <code>prefect/agent.py</code> <pre><code>async def get_and_submit_flow_runs(self) -&gt; List[FlowRun]:\n    \"\"\"\n    The principle method on agents. Queries for scheduled flow runs and submits\n    them for execution in parallel.\n    \"\"\"\n    if not self.started:\n        raise RuntimeError(\n            \"Agent is not started. Use `async with PrefectAgent()...`\"\n        )\n\n    self.logger.debug(\"Checking for scheduled flow runs...\")\n\n    before = pendulum.now(\"utc\").add(\n        seconds=self.prefetch_seconds or PREFECT_AGENT_PREFETCH_SECONDS.value()\n    )\n\n    submittable_runs: List[FlowRun] = []\n\n    if self.work_pool_name:\n        responses = await self.client.get_scheduled_flow_runs_for_work_pool(\n            work_pool_name=self.work_pool_name,\n            work_queue_names=[wq.name async for wq in self.get_work_queues()],\n            scheduled_before=before,\n        )\n        submittable_runs.extend([response.flow_run for response in responses])\n\n    else:\n        # load runs from each work queue\n        async for work_queue in self.get_work_queues():\n            # print a nice message if the work queue is paused\n            if work_queue.is_paused:\n                self.logger.info(\n                    f\"Work queue {work_queue.name!r} ({work_queue.id}) is paused.\"\n                )\n\n            else:\n                try:\n                    queue_runs = await self.client.get_runs_in_work_queue(\n                        id=work_queue.id, limit=10, scheduled_before=before\n                    )\n                    submittable_runs.extend(queue_runs)\n                except ObjectNotFound:\n                    self.logger.error(\n                        f\"Work queue {work_queue.name!r} ({work_queue.id}) not\"\n                        \" found.\"\n                    )\n                except Exception as exc:\n                    self.logger.exception(exc)\n\n        submittable_runs.sort(key=lambda run: run.next_scheduled_start_time)\n\n    for flow_run in submittable_runs:\n        # don't resubmit a run\n        if flow_run.id in self.submitting_flow_run_ids:\n            continue\n\n        try:\n            if self.limiter:\n                self.limiter.acquire_on_behalf_of_nowait(flow_run.id)\n        except anyio.WouldBlock:\n            self.logger.info(\n                f\"Flow run limit reached; {self.limiter.borrowed_tokens} flow runs\"\n                \" in progress.\"\n            )\n            break\n        else:\n            self.logger.info(f\"Submitting flow run '{flow_run.id}'\")\n            self.submitting_flow_run_ids.add(flow_run.id)\n            self.task_group.start_soon(\n                self.submit_run,\n                flow_run,\n            )\n\n    return list(\n        filter(lambda run: run.id in self.submitting_flow_run_ids, submittable_runs)\n    )\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.get_work_queues","title":"<code>get_work_queues</code>  <code>async</code>","text":"<p>Loads the work queue objects corresponding to the agent's target work queues. If any of them don't exist, they are created.</p> Source code in <code>prefect/agent.py</code> <pre><code>async def get_work_queues(self) -&gt; AsyncIterator[WorkQueue]:\n    \"\"\"\n    Loads the work queue objects corresponding to the agent's target work\n    queues. If any of them don't exist, they are created.\n    \"\"\"\n\n    # if the queue cache has not expired, yield queues from the cache\n    now = pendulum.now(\"UTC\")\n    if (self._work_queue_cache_expiration or now) &gt; now:\n        for queue in self._work_queue_cache:\n            yield queue\n        return\n\n    # otherwise clear the cache, set the expiration for 30 seconds, and\n    # reload the work queues\n    self._work_queue_cache.clear()\n    self._work_queue_cache_expiration = now.add(seconds=30)\n\n    await self.update_matched_agent_work_queues()\n\n    for name in self.work_queues:\n        try:\n            work_queue = await self.client.read_work_queue_by_name(\n                work_pool_name=self.work_pool_name, name=name\n            )\n        except (ObjectNotFound, Exception):\n            work_queue = None\n\n        # if the work queue wasn't found and the agent is NOT polling\n        # for queues using a regex, try to create it\n        if work_queue is None and not self.work_queue_prefix:\n            try:\n                work_queue = await self.client.create_work_queue(\n                    work_pool_name=self.work_pool_name, name=name\n                )\n            except Exception:\n                # if creating it raises an exception, it was probably just\n                # created by some other agent; rather than entering a re-read\n                # loop with new error handling, we log the exception and\n                # continue.\n                self.logger.exception(f\"Failed to create work queue {name!r}.\")\n                continue\n            else:\n                log_str = f\"Created work queue {name!r}\"\n                if self.work_pool_name:\n                    log_str = (\n                        f\"Created work queue {name!r} in work pool\"\n                        f\" {self.work_pool_name!r}.\"\n                    )\n                else:\n                    log_str = f\"Created work queue '{name}'.\"\n                self.logger.info(log_str)\n\n        if work_queue is None:\n            self.logger.error(\n                f\"Work queue '{name!r}' with prefix {self.work_queue_prefix} wasn't\"\n                \" found\"\n            )\n        else:\n            self._work_queue_cache.append(work_queue)\n            yield work_queue\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/agent/#prefect.agent.PrefectAgent.submit_run","title":"<code>submit_run</code>  <code>async</code>","text":"<p>Submit a flow run to the infrastructure</p> Source code in <code>prefect/agent.py</code> <pre><code>async def submit_run(self, flow_run: FlowRun) -&gt; None:\n    \"\"\"\n    Submit a flow run to the infrastructure\n    \"\"\"\n    ready_to_submit = await self._propose_pending_state(flow_run)\n\n    if ready_to_submit:\n        try:\n            infrastructure = await self.get_infrastructure(flow_run)\n        except Exception as exc:\n            self.logger.exception(\n                f\"Failed to get infrastructure for flow run '{flow_run.id}'.\"\n            )\n            await self._propose_failed_state(flow_run, exc)\n            if self.limiter:\n                self.limiter.release_on_behalf_of(flow_run.id)\n        else:\n            # Wait for submission to be completed. Note that the submission function\n            # may continue to run in the background after this exits.\n            readiness_result = await self.task_group.start(\n                self._submit_run_and_capture_errors, flow_run, infrastructure\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                try:\n                    await self.client.update_flow_run(\n                        flow_run_id=flow_run.id,\n                        infrastructure_pid=str(readiness_result),\n                    )\n                except Exception:\n                    self.logger.exception(\n                        \"An error occurred while setting the `infrastructure_pid`\"\n                        f\" on flow run {flow_run.id!r}. The flow run will not be\"\n                        \" cancellable.\"\n                    )\n\n            self.logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n    else:\n        # If the run is not ready to submit, release the concurrency slot\n        if self.limiter:\n            self.limiter.release_on_behalf_of(flow_run.id)\n\n    self.submitting_flow_run_ids.remove(flow_run.id)\n</code></pre>","tags":["Python API","agents"]},{"location":"api-ref/prefect/artifacts/","title":"prefect.artifacts","text":"","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts","title":"<code>prefect.artifacts</code>","text":"<p>Interface for creating and reading artifacts.</p>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact","title":"<code>Artifact</code>","text":"<p>               Bases: <code>ArtifactCreate</code></p> <p>An artifact is a piece of data that is created by a flow or task run. https://docs.prefect.io/latest/concepts/artifacts/</p> <p>Parameters:</p> Name Type Description Default <code>type</code> <p>A string identifying the type of artifact.</p> required <code>key</code> <p>A user-provided string identifier. The key must only contain lowercase letters, numbers, and dashes.</p> required <code>description</code> <p>A user-specified description of the artifact.</p> required <code>data</code> <p>A JSON payload that allows for a result to be retrieved.</p> required Source code in <code>prefect/artifacts.py</code> <pre><code>class Artifact(ArtifactRequest):\n    \"\"\"\n    An artifact is a piece of data that is created by a flow or task run.\n    https://docs.prefect.io/latest/concepts/artifacts/\n\n    Arguments:\n        type: A string identifying the type of artifact.\n        key: A user-provided string identifier.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n        data: A JSON payload that allows for a result to be retrieved.\n    \"\"\"\n\n    @sync_compatible\n    async def create(\n        self: Self,\n        client: Optional[PrefectClient] = None,\n    ) -&gt; ArtifactResponse:\n        \"\"\"\n        A method to create an artifact.\n\n        Arguments:\n            client: The PrefectClient\n\n        Returns:\n            - The created artifact.\n        \"\"\"\n        client, _ = get_or_create_client(client)\n        task_run_id, flow_run_id = get_task_and_flow_run_ids()\n        return await client.create_artifact(\n            artifact=ArtifactRequest(\n                type=self.type,\n                key=self.key,\n                description=self.description,\n                task_run_id=self.task_run_id or task_run_id,\n                flow_run_id=self.flow_run_id or flow_run_id,\n                data=await self.format(),\n            )\n        )\n\n    @classmethod\n    @sync_compatible\n    async def get(\n        cls, key: Optional[str] = None, client: Optional[PrefectClient] = None\n    ) -&gt; Optional[ArtifactResponse]:\n        \"\"\"\n        A method to get an artifact.\n\n        Arguments:\n            key (str, optional): The key of the artifact to get.\n            client (PrefectClient, optional): The PrefectClient\n\n        Returns:\n            (ArtifactResponse, optional): The artifact (if found).\n        \"\"\"\n        client, _ = get_or_create_client(client)\n        return next(\n            iter(\n                await client.read_artifacts(\n                    limit=1,\n                    sort=ArtifactSort.UPDATED_DESC,\n                    artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n                )\n            ),\n            None,\n        )\n\n    @classmethod\n    @sync_compatible\n    async def get_or_create(\n        cls,\n        key: Optional[str] = None,\n        description: Optional[str] = None,\n        data: Optional[Union[Dict[str, Any], Any]] = None,\n        client: Optional[PrefectClient] = None,\n        **kwargs: Any,\n    ) -&gt; Tuple[ArtifactResponse, bool]:\n        \"\"\"\n        A method to get or create an artifact.\n\n        Arguments:\n            key (str, optional): The key of the artifact to get or create.\n            description (str, optional): The description of the artifact to create.\n            data (Union[Dict[str, Any], Any], optional): The data of the artifact to create.\n            client (PrefectClient, optional): The PrefectClient\n\n        Returns:\n            (ArtifactResponse): The artifact, either retrieved or created.\n        \"\"\"\n        artifact = await cls.get(key, client)\n        if artifact:\n            return artifact, False\n        else:\n            return (\n                await cls(key=key, description=description, data=data, **kwargs).create(\n                    client\n                ),\n                True,\n            )\n\n    async def format(self) -&gt; Optional[Union[Dict[str, Any], Any]]:\n        return json.dumps(self.data)\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.create","title":"<code>create</code>  <code>async</code>","text":"<p>A method to create an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>Optional[PrefectClient]</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>Artifact</code> <ul> <li>The created artifact.</li> </ul> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create(\n    self: Self,\n    client: Optional[PrefectClient] = None,\n) -&gt; ArtifactResponse:\n    \"\"\"\n    A method to create an artifact.\n\n    Arguments:\n        client: The PrefectClient\n\n    Returns:\n        - The created artifact.\n    \"\"\"\n    client, _ = get_or_create_client(client)\n    task_run_id, flow_run_id = get_task_and_flow_run_ids()\n    return await client.create_artifact(\n        artifact=ArtifactRequest(\n            type=self.type,\n            key=self.key,\n            description=self.description,\n            task_run_id=self.task_run_id or task_run_id,\n            flow_run_id=self.flow_run_id or flow_run_id,\n            data=await self.format(),\n        )\n    )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.get","title":"<code>get</code>  <code>async</code> <code>classmethod</code>","text":"<p>A method to get an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The key of the artifact to get.</p> <code>None</code> <code>client</code> <code>PrefectClient</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>(Artifact, optional)</code> <p>The artifact (if found).</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get(\n    cls, key: Optional[str] = None, client: Optional[PrefectClient] = None\n) -&gt; Optional[ArtifactResponse]:\n    \"\"\"\n    A method to get an artifact.\n\n    Arguments:\n        key (str, optional): The key of the artifact to get.\n        client (PrefectClient, optional): The PrefectClient\n\n    Returns:\n        (ArtifactResponse, optional): The artifact (if found).\n    \"\"\"\n    client, _ = get_or_create_client(client)\n    return next(\n        iter(\n            await client.read_artifacts(\n                limit=1,\n                sort=ArtifactSort.UPDATED_DESC,\n                artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n            )\n        ),\n        None,\n    )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.Artifact.get_or_create","title":"<code>get_or_create</code>  <code>async</code> <code>classmethod</code>","text":"<p>A method to get or create an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>The key of the artifact to get or create.</p> <code>None</code> <code>description</code> <code>str</code> <p>The description of the artifact to create.</p> <code>None</code> <code>data</code> <code>Union[Dict[str, Any], Any]</code> <p>The data of the artifact to create.</p> <code>None</code> <code>client</code> <code>PrefectClient</code> <p>The PrefectClient</p> <code>None</code> <p>Returns:</p> Type Description <code>Artifact</code> <p>The artifact, either retrieved or created.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get_or_create(\n    cls,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n    data: Optional[Union[Dict[str, Any], Any]] = None,\n    client: Optional[PrefectClient] = None,\n    **kwargs: Any,\n) -&gt; Tuple[ArtifactResponse, bool]:\n    \"\"\"\n    A method to get or create an artifact.\n\n    Arguments:\n        key (str, optional): The key of the artifact to get or create.\n        description (str, optional): The description of the artifact to create.\n        data (Union[Dict[str, Any], Any], optional): The data of the artifact to create.\n        client (PrefectClient, optional): The PrefectClient\n\n    Returns:\n        (ArtifactResponse): The artifact, either retrieved or created.\n    \"\"\"\n    artifact = await cls.get(key, client)\n    if artifact:\n        return artifact, False\n    else:\n        return (\n            await cls(key=key, description=description, data=data, **kwargs).create(\n                client\n            ),\n            True,\n        )\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.TableArtifact","title":"<code>TableArtifact</code>","text":"<p>               Bases: <code>Artifact</code></p> Source code in <code>prefect/artifacts.py</code> <pre><code>class TableArtifact(Artifact):\n    table: Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]]\n    type: Optional[str] = \"table\"\n\n    @classmethod\n    def _sanitize(\n        cls, item: Union[Dict[str, Any], List[Any], float]\n    ) -&gt; Union[Dict[str, Any], List[Any], int, float, None]:\n        \"\"\"\n        Sanitize NaN values in a given item.\n        The item can be a dict, list or float.\n        \"\"\"\n        if isinstance(item, list):\n            return [cls._sanitize(sub_item) for sub_item in item]\n        elif isinstance(item, dict):\n            return {k: cls._sanitize(v) for k, v in item.items()}\n        elif isinstance(item, float) and math.isnan(item):\n            return None\n        else:\n            return item\n\n    async def format(self) -&gt; str:\n        return json.dumps(self._sanitize(self.table))\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_link_artifact","title":"<code>create_link_artifact</code>  <code>async</code>","text":"<p>Create a link artifact.</p> <p>Parameters:</p> Name Type Description Default <code>link</code> <code>str</code> <p>The link to create.</p> required <code>link_text</code> <code>Optional[str]</code> <p>The link text.</p> <code>None</code> <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_link_artifact(\n    link: str,\n    link_text: Optional[str] = None,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n    client: Optional[PrefectClient] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a link artifact.\n\n    Arguments:\n        link: The link to create.\n        link_text: The link text.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n    artifact = await LinkArtifact(\n        key=key,\n        description=description,\n        link=link,\n        link_text=link_text,\n    ).create(client)\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_markdown_artifact","title":"<code>create_markdown_artifact</code>  <code>async</code>","text":"<p>Create a markdown artifact.</p> <p>Parameters:</p> Name Type Description Default <code>markdown</code> <code>str</code> <p>The markdown to create.</p> required <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_markdown_artifact(\n    markdown: str,\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a markdown artifact.\n\n    Arguments:\n        markdown: The markdown to create.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n    artifact = await MarkdownArtifact(\n        key=key,\n        description=description,\n        markdown=markdown,\n    ).create()\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/artifacts/#prefect.artifacts.create_table_artifact","title":"<code>create_table_artifact</code>  <code>async</code>","text":"<p>Create a table artifact.</p> <p>Parameters:</p> Name Type Description Default <code>table</code> <code>Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]]</code> <p>The table to create.</p> required <code>key</code> <code>Optional[str]</code> <p>A user-provided string identifier. Required for the artifact to show in the Artifacts page in the UI. The key must only contain lowercase letters, numbers, and dashes.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A user-specified description of the artifact.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The table artifact ID.</p> Source code in <code>prefect/artifacts.py</code> <pre><code>@sync_compatible\nasync def create_table_artifact(\n    table: Union[Dict[str, List[Any]], List[Dict[str, Any]], List[List[Any]]],\n    key: Optional[str] = None,\n    description: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a table artifact.\n\n    Arguments:\n        table: The table to create.\n        key: A user-provided string identifier.\n          Required for the artifact to show in the Artifacts page in the UI.\n          The key must only contain lowercase letters, numbers, and dashes.\n        description: A user-specified description of the artifact.\n\n    Returns:\n        The table artifact ID.\n    \"\"\"\n\n    artifact = await TableArtifact(\n        key=key,\n        description=description,\n        table=table,\n    ).create()\n\n    return artifact.id\n</code></pre>","tags":["Python API","artifacts"]},{"location":"api-ref/prefect/automations/","title":"prefect.automations","text":"","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations","title":"<code>prefect.automations</code>","text":"","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation","title":"<code>Automation</code>","text":"<p>               Bases: <code>AutomationCore</code></p> Source code in <code>prefect/automations.py</code> <pre><code>class Automation(AutomationCore):\n    id: Optional[UUID] = Field(default=None, description=\"The ID of this automation\")\n\n    @sync_compatible\n    async def create(self: Self) -&gt; Self:\n        \"\"\"\n        Create a new automation.\n\n        auto_to_create = Automation(\n            name=\"woodchonk\",\n            trigger=EventTrigger(\n                expect={\"animal.walked\"},\n                match={\n                    \"genus\": \"Marmota\",\n                    \"species\": \"monax\",\n                },\n                posture=\"Reactive\",\n                threshold=3,\n                within=timedelta(seconds=10),\n            ),\n            actions=[CancelFlowRun()]\n        )\n        created_automation = auto_to_create.create()\n        \"\"\"\n        client, _ = get_or_create_client()\n        automation = AutomationCore(**self.dict(exclude={\"id\"}))\n        self.id = await client.create_automation(automation=automation)\n        return self\n\n    @sync_compatible\n    async def update(self: Self):\n        \"\"\"\n        Updates an existing automation.\n        auto = Automation.read(id=123)\n        auto.name = \"new name\"\n        auto.update()\n        \"\"\"\n\n        client, _ = get_or_create_client()\n        automation = AutomationCore(**self.dict(exclude={\"id\", \"owner_resource\"}))\n        await client.update_automation(automation_id=self.id, automation=automation)\n\n    @classmethod\n    @sync_compatible\n    async def read(\n        cls: Self, id: Optional[UUID] = None, name: Optional[str] = None\n    ) -&gt; Self:\n        \"\"\"\n        Read an automation by ID or name.\n        automation = Automation.read(name=\"woodchonk\")\n\n        or\n\n        automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))\n        \"\"\"\n        if id and name:\n            raise ValueError(\"Only one of id or name can be provided\")\n        if not id and not name:\n            raise ValueError(\"One of id or name must be provided\")\n        client, _ = get_or_create_client()\n        if id:\n            try:\n                automation = await client.read_automation(automation_id=id)\n            except PrefectHTTPStatusError as exc:\n                if exc.response.status_code == 404:\n                    raise ValueError(f\"Automation with ID {id!r} not found\")\n            return Automation(**automation.dict())\n        else:\n            automation = await client.read_automations_by_name(name=name)\n            if len(automation) &gt; 0:\n                return Automation(**automation[0].dict()) if automation else None\n            else:\n                raise ValueError(f\"Automation with name {name!r} not found\")\n\n    @sync_compatible\n    async def delete(self: Self) -&gt; bool:\n        \"\"\"\n        auto = Automation.read(id = 123)\n        auto.delete()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.delete_automation(self.id)\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n\n    @sync_compatible\n    async def disable(self: Self) -&gt; bool:\n        \"\"\"\n        Disable an automation.\n        auto = Automation.read(id = 123)\n        auto.disable()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.pause_automation(self.id)\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n\n    @sync_compatible\n    async def enable(self: Self) -&gt; bool:\n        \"\"\"\n        Enable an automation.\n        auto = Automation.read(id = 123)\n        auto.enable()\n        \"\"\"\n        try:\n            client, _ = get_or_create_client()\n            await client.resume_automation(\"asd\")\n            return True\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                return False\n            raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new automation.</p> <p>auto_to_create = Automation(     name=\"woodchonk\",     trigger=EventTrigger(         expect={\"animal.walked\"},         match={             \"genus\": \"Marmota\",             \"species\": \"monax\",         },         posture=\"Reactive\",         threshold=3,         within=timedelta(seconds=10),     ),     actions=[CancelFlowRun()] ) created_automation = auto_to_create.create()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def create(self: Self) -&gt; Self:\n    \"\"\"\n    Create a new automation.\n\n    auto_to_create = Automation(\n        name=\"woodchonk\",\n        trigger=EventTrigger(\n            expect={\"animal.walked\"},\n            match={\n                \"genus\": \"Marmota\",\n                \"species\": \"monax\",\n            },\n            posture=\"Reactive\",\n            threshold=3,\n            within=timedelta(seconds=10),\n        ),\n        actions=[CancelFlowRun()]\n    )\n    created_automation = auto_to_create.create()\n    \"\"\"\n    client, _ = get_or_create_client()\n    automation = AutomationCore(**self.dict(exclude={\"id\"}))\n    self.id = await client.create_automation(automation=automation)\n    return self\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>auto = Automation.read(id = 123) auto.delete()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def delete(self: Self) -&gt; bool:\n    \"\"\"\n    auto = Automation.read(id = 123)\n    auto.delete()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.delete_automation(self.id)\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.disable","title":"<code>disable</code>  <code>async</code>","text":"<p>Disable an automation. auto = Automation.read(id = 123) auto.disable()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def disable(self: Self) -&gt; bool:\n    \"\"\"\n    Disable an automation.\n    auto = Automation.read(id = 123)\n    auto.disable()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.pause_automation(self.id)\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.enable","title":"<code>enable</code>  <code>async</code>","text":"<p>Enable an automation. auto = Automation.read(id = 123) auto.enable()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def enable(self: Self) -&gt; bool:\n    \"\"\"\n    Enable an automation.\n    auto = Automation.read(id = 123)\n    auto.enable()\n    \"\"\"\n    try:\n        client, _ = get_or_create_client()\n        await client.resume_automation(\"asd\")\n        return True\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return False\n        raise\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.read","title":"<code>read</code>  <code>async</code> <code>classmethod</code>","text":"<p>Read an automation by ID or name. automation = Automation.read(name=\"woodchonk\")</p> <p>or</p> <p>automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))</p> Source code in <code>prefect/automations.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def read(\n    cls: Self, id: Optional[UUID] = None, name: Optional[str] = None\n) -&gt; Self:\n    \"\"\"\n    Read an automation by ID or name.\n    automation = Automation.read(name=\"woodchonk\")\n\n    or\n\n    automation = Automation.read(id=UUID(\"b3514963-02b1-47a5-93d1-6eeb131041cb\"))\n    \"\"\"\n    if id and name:\n        raise ValueError(\"Only one of id or name can be provided\")\n    if not id and not name:\n        raise ValueError(\"One of id or name must be provided\")\n    client, _ = get_or_create_client()\n    if id:\n        try:\n            automation = await client.read_automation(automation_id=id)\n        except PrefectHTTPStatusError as exc:\n            if exc.response.status_code == 404:\n                raise ValueError(f\"Automation with ID {id!r} not found\")\n        return Automation(**automation.dict())\n    else:\n        automation = await client.read_automations_by_name(name=name)\n        if len(automation) &gt; 0:\n            return Automation(**automation[0].dict()) if automation else None\n        else:\n            raise ValueError(f\"Automation with name {name!r} not found\")\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Automation.update","title":"<code>update</code>  <code>async</code>","text":"<p>Updates an existing automation. auto = Automation.read(id=123) auto.name = \"new name\" auto.update()</p> Source code in <code>prefect/automations.py</code> <pre><code>@sync_compatible\nasync def update(self: Self):\n    \"\"\"\n    Updates an existing automation.\n    auto = Automation.read(id=123)\n    auto.name = \"new name\"\n    auto.update()\n    \"\"\"\n\n    client, _ = get_or_create_client()\n    automation = AutomationCore(**self.dict(exclude={\"id\", \"owner_resource\"}))\n    await client.update_automation(automation_id=self.id, automation=automation)\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.AutomationCore","title":"<code>AutomationCore</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines an action a user wants to take when a certain number of events do or don't happen to the matching resources</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class AutomationCore(PrefectBaseModel, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"Defines an action a user wants to take when a certain number of events\n    do or don't happen to the matching resources\"\"\"\n\n    name: str = Field(..., description=\"The name of this automation\")\n    description: str = Field(\"\", description=\"A longer description of this automation\")\n\n    enabled: bool = Field(True, description=\"Whether this automation will be evaluated\")\n\n    trigger: TriggerTypes = Field(\n        ...,\n        description=(\n            \"The criteria for which events this Automation covers and how it will \"\n            \"respond to the presence or absence of those events\"\n        ),\n    )\n\n    actions: List[ActionTypes] = Field(\n        ...,\n        description=\"The actions to perform when this Automation triggers\",\n    )\n\n    actions_on_trigger: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a triggered state\",\n    )\n\n    actions_on_resolve: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a resolving state\",\n    )\n\n    owner_resource: Optional[str] = Field(\n        default=None, description=\"The owning resource of this automation\"\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompositeTrigger","title":"<code>CompositeTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Requires some number of triggers to have fired within the given time period.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompositeTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Requires some number of triggers to have fired within the given time period.\n    \"\"\"\n\n    type: Literal[\"compound\", \"sequence\"]\n    triggers: List[\"TriggerTypes\"]\n    within: Optional[timedelta]\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompoundTrigger","title":"<code>CompoundTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompoundTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    type: Literal[\"compound\"] = \"compound\"\n    require: Union[int, Literal[\"any\", \"all\"]]\n\n    @root_validator\n    def validate_require(cls, values: Dict[str, Any]) -&gt; Dict[str, Any]:\n        require = values.get(\"require\")\n\n        if isinstance(require, int):\n            if require &lt; 1:\n                raise ValueError(\"required must be at least 1\")\n            if require &gt; len(values[\"triggers\"]):\n                raise ValueError(\n                    \"required must be less than or equal to the number of triggers\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"{str(self.require).capitalize()} of:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.CompoundTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"{str(self.require).capitalize()} of:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.EventTrigger","title":"<code>EventTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class EventTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    type: Literal[\"event\"] = \"event\"\n\n    after: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) which must first been seen to fire this trigger.  If \"\n            \"empty, then fire this trigger immediately.  Events may include \"\n            \"trailing wildcards, like `prefect.flow-run.*`\"\n        ),\n    )\n    expect: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) this trigger is expecting to see.  If empty, this \"\n            \"trigger will match any event.  Events may include trailing wildcards, \"\n            \"like `prefect.flow-run.*`\"\n        ),\n    )\n\n    for_each: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"Evaluate the trigger separately for each distinct value of these labels \"\n            \"on the resource.  By default, labels refer to the primary resource of the \"\n            \"triggering event.  You may also refer to labels from related \"\n            \"resources by specifying `related:&lt;role&gt;:&lt;label&gt;`.  This will use the \"\n            \"value of that label for the first related resource in that role.  For \"\n            'example, `\"for_each\": [\"related:flow:prefect.resource.id\"]` would '\n            \"evaluate the trigger for each flow.\"\n        ),\n    )\n    posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]\n        Posture.Reactive,\n        description=(\n            \"The posture of this trigger, either Reactive or Proactive.  Reactive \"\n            \"triggers respond to the _presence_ of the expected events, while \"\n            \"Proactive triggers respond to the _absence_ of those expected events.\"\n        ),\n    )\n    threshold: int = Field(\n        1,\n        description=(\n            \"The number of events required for this trigger to fire (for \"\n            \"Reactive triggers), or the number of events expected (for Proactive \"\n            \"triggers)\"\n        ),\n    )\n    within: timedelta = Field(\n        timedelta(0),\n        minimum=0.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The time period over which the events must occur.  For Reactive triggers, \"\n            \"this may be as low as 0 seconds, but must be at least 10 seconds for \"\n            \"Proactive triggers\"\n        ),\n    )\n\n    @validator(\"within\")\n    def enforce_minimum_within(\n        cls, value: timedelta, values, config, field: ModelField\n    ):\n        return validate_trigger_within(value, field)\n\n    @root_validator(skip_on_failure=True)\n    def enforce_minimum_within_for_proactive_triggers(cls, values: Dict[str, Any]):\n        posture: Optional[Posture] = values.get(\"posture\")\n        within: Optional[timedelta] = values.get(\"within\")\n\n        if posture == Posture.Proactive:\n            if not within or within == timedelta(0):\n                values[\"within\"] = timedelta(seconds=10.0)\n            elif within &lt; timedelta(seconds=10.0):\n                raise ValueError(\n                    \"The minimum within for Proactive triggers is 10 seconds\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        if self.posture == Posture.Reactive:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n        else:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                        f\"within {self.within}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.EventTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    if self.posture == Posture.Reactive:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n    else:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                    f\"within {self.within}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTrigger","title":"<code>MetricTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    type: Literal[\"metric\"] = \"metric\"\n\n    posture: Literal[Posture.Metric] = Field(  # type: ignore[valid-type]\n        Posture.Metric,\n        description=\"Periodically evaluate the configured metric query.\",\n    )\n\n    metric: MetricTriggerQuery = Field(\n        ...,\n        description=\"The metric query to evaluate for this trigger. \",\n    )\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        m = self.metric\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    m = self.metric\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.MetricTriggerQuery","title":"<code>MetricTriggerQuery</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines a subset of the Trigger subclass, which is specific to Metric automations, that specify the query configurations and breaching conditions for the Automation</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTriggerQuery(PrefectBaseModel):\n    \"\"\"Defines a subset of the Trigger subclass, which is specific\n    to Metric automations, that specify the query configurations\n    and breaching conditions for the Automation\"\"\"\n\n    name: PrefectMetric = Field(\n        ...,\n        description=\"The name of the metric to query.\",\n    )\n    threshold: float = Field(\n        ...,\n        description=(\n            \"The threshold value against which we'll compare \" \"the query result.\"\n        ),\n    )\n    operator: MetricTriggerOperator = Field(\n        ...,\n        description=(\n            \"The comparative operator (LT / LTE / GT / GTE) used to compare \"\n            \"the query result against the threshold value.\"\n        ),\n    )\n    range: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The lookback duration (seconds) for a metric query. This duration is \"\n            \"used to determine the time range over which the query will be executed. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n    firing_for: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The duration (seconds) for which the metric query must breach \"\n            \"or resolve continuously before the state is updated and the \"\n            \"automation is triggered. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.ResourceSpecification","title":"<code>ResourceSpecification</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation.  A resource must match at least one value of all of the provided labels</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ResourceSpecification(PrefectBaseModel):\n    \"\"\"A specification that may match zero, one, or many resources, used to target or\n    select a set of resources in a query or automation.  A resource must match at least\n    one value of all of the provided labels\"\"\"\n\n    __root__: Dict[str, Union[str, List[str]]]\n\n    def matches_every_resource(self) -&gt; bool:\n        return len(self) == 0\n\n    def matches_every_resource_of_kind(self, prefix: str) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        if len(self.__root__) == 1:\n            if resource_id := self.__root__.get(\"prefect.resource.id\"):\n                values = [resource_id] if isinstance(resource_id, str) else resource_id\n                return any(value == f\"{prefix}.*\" for value in values)\n\n        return False\n\n    def includes(self, candidates: Iterable[Resource]) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        for candidate in candidates:\n            if self.matches(candidate):\n                return True\n\n        return False\n\n    def matches(self, resource: Resource) -&gt; bool:\n        for label, expected in self.items():\n            value = resource.get(label)\n            if not any(matches(candidate, value) for candidate in expected):\n                return False\n        return True\n\n    def items(self) -&gt; Iterable[Tuple[str, List[str]]]:\n        return [\n            (label, [value] if isinstance(value, str) else value)\n            for label, value in self.__root__.items()\n        ]\n\n    def __contains__(self, key: str) -&gt; bool:\n        return self.__root__.__contains__(key)\n\n    def __getitem__(self, key: str) -&gt; List[str]:\n        value = self.__root__[key]\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def pop(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.pop(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def get(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.get(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def __len__(self) -&gt; int:\n        return len(self.__root__)\n\n    def deepcopy(self) -&gt; \"ResourceSpecification\":\n        return ResourceSpecification.parse_obj(copy.deepcopy(self.__root__))\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.ResourceTrigger","title":"<code>ResourceTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Base class for triggers that may filter by the labels of resources.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class ResourceTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Base class for triggers that may filter by the labels of resources.\n    \"\"\"\n\n    type: str\n\n    match: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for resources which this trigger will match.\",\n    )\n    match_related: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for related resources which this trigger will match.\",\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.SequenceTrigger","title":"<code>SequenceTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class SequenceTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    type: Literal[\"sequence\"] = \"sequence\"\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    \"In this order:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.SequenceTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                \"In this order:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Trigger","title":"<code>Trigger</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>Base class describing a set of criteria that must be satisfied in order to trigger an automation.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class Trigger(PrefectBaseModel, abc.ABC, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"\n    Base class describing a set of criteria that must be satisfied in order to trigger\n    an automation.\n    \"\"\"\n\n    type: str\n\n    @abc.abstractmethod\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n\n    # The following allows the regular Trigger class to be used when serving or\n    # deploying flows, analogous to how the Deployment*Trigger classes work\n\n    _deployment_id: Optional[UUID] = PrivateAttr(default=None)\n\n    def set_deployment_id(self, deployment_id: UUID):\n        self._deployment_id = deployment_id\n\n    def owner_resource(self) -&gt; Optional[str]:\n        return f\"prefect.deployment.{self._deployment_id}\"\n\n    def actions(self) -&gt; List[ActionTypes]:\n        assert self._deployment_id\n        return [\n            RunDeployment(\n                source=\"selected\",\n                deployment_id=self._deployment_id,\n                parameters=getattr(self, \"parameters\", None),\n                job_variables=getattr(self, \"job_variables\", None),\n            )\n        ]\n\n    def as_automation(self) -&gt; \"AutomationCore\":\n        assert self._deployment_id\n\n        trigger: TriggerTypes = cast(TriggerTypes, self)\n\n        # This is one of the Deployment*Trigger classes, so translate it over to a\n        # plain Trigger\n        if hasattr(self, \"trigger_type\"):\n            trigger = self.trigger_type(**self.dict())\n\n        return AutomationCore(\n            name=(\n                getattr(self, \"name\", None)\n                or f\"Automation for deployment {self._deployment_id}\"\n            ),\n            description=\"\",\n            enabled=getattr(self, \"enabled\", True),\n            trigger=trigger,\n            actions=self.actions(),\n            owner_resource=self.owner_resource(),\n        )\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/automations/#prefect.automations.Trigger.describe_for_cli","title":"<code>describe_for_cli</code>  <code>abstractmethod</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>@abc.abstractmethod\ndef describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n</code></pre>","tags":["Python API","automations"]},{"location":"api-ref/prefect/context/","title":"prefect.context","text":"","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context","title":"<code>prefect.context</code>","text":"<p>Async and thread safe models for passing runtime context data.</p> <p>These contexts should never be directly mutated by the user.</p> <p>For more user-accessible information about the current run, see <code>prefect.runtime</code>.</p>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.ContextModel","title":"<code>ContextModel</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A base model for context data that forbids mutation and extra data while providing a context manager</p> Source code in <code>prefect/context.py</code> <pre><code>class ContextModel(BaseModel):\n    \"\"\"\n    A base model for context data that forbids mutation and extra data while providing\n    a context manager\n    \"\"\"\n\n    # The context variable for storing data must be defined by the child class\n    __var__: ContextVar\n    _token: Token = PrivateAttr(None)\n\n    class Config:\n        # allow_mutation = False\n        arbitrary_types_allowed = True\n        extra = \"forbid\"\n\n    def __enter__(self):\n        if self._token is not None:\n            raise RuntimeError(\n                \"Context already entered. Context enter calls cannot be nested.\"\n            )\n        self._token = self.__var__.set(self)\n        return self\n\n    def __exit__(self, *_):\n        if not self._token:\n            raise RuntimeError(\n                \"Asymmetric use of context. Context exit called without an enter.\"\n            )\n        self.__var__.reset(self._token)\n        self._token = None\n\n    @classmethod\n    def get(cls: Type[T]) -&gt; Optional[T]:\n        return cls.__var__.get(None)\n\n    def copy(self, **kwargs):\n        \"\"\"\n        Duplicate the context model, optionally choosing which fields to include, exclude, or change.\n\n        Attributes:\n            include: Fields to include in new model.\n            exclude: Fields to exclude from new model, as with values this takes precedence over include.\n            update: Values to change/add in the new model. Note: the data is not validated before creating\n                the new model - you should trust this data.\n            deep: Set to `True` to make a deep copy of the model.\n\n        Returns:\n            A new model instance.\n        \"\"\"\n        # Remove the token on copy to avoid re-entrance errors\n        new = super().copy(**kwargs)\n        new._token = None\n        return new\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.ContextModel.copy","title":"<code>copy</code>","text":"<p>Duplicate the context model, optionally choosing which fields to include, exclude, or change.</p> <p>Attributes:</p> Name Type Description <code>include</code> <p>Fields to include in new model.</p> <code>exclude</code> <p>Fields to exclude from new model, as with values this takes precedence over include.</p> <code>update</code> <p>Values to change/add in the new model. Note: the data is not validated before creating the new model - you should trust this data.</p> <code>deep</code> <p>Set to <code>True</code> to make a deep copy of the model.</p> <p>Returns:</p> Type Description <p>A new model instance.</p> Source code in <code>prefect/context.py</code> <pre><code>def copy(self, **kwargs):\n    \"\"\"\n    Duplicate the context model, optionally choosing which fields to include, exclude, or change.\n\n    Attributes:\n        include: Fields to include in new model.\n        exclude: Fields to exclude from new model, as with values this takes precedence over include.\n        update: Values to change/add in the new model. Note: the data is not validated before creating\n            the new model - you should trust this data.\n        deep: Set to `True` to make a deep copy of the model.\n\n    Returns:\n        A new model instance.\n    \"\"\"\n    # Remove the token on copy to avoid re-entrance errors\n    new = super().copy(**kwargs)\n    new._token = None\n    return new\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.EngineContext","title":"<code>EngineContext</code>","text":"<p>               Bases: <code>RunContext</code></p> <p>The context for a flow run. Data in this context is only available from within a flow run function.</p> <p>Attributes:</p> Name Type Description <code>flow</code> <code>Optional[Flow]</code> <p>The flow instance associated with the run</p> <code>flow_run</code> <code>Optional[FlowRun]</code> <p>The API metadata for the flow run</p> <code>task_runner</code> <code>BaseTaskRunner</code> <p>The task runner instance being used for the flow run</p> <code>task_run_futures</code> <code>List[PrefectFuture]</code> <p>A list of futures for task runs submitted within this flow run</p> <code>task_run_states</code> <code>List[State]</code> <p>A list of states for task runs created within this flow run</p> <code>task_run_results</code> <code>Dict[int, State]</code> <p>A mapping of result ids to task run states for this flow run</p> <code>flow_run_states</code> <code>List[State]</code> <p>A list of states for flow runs created within this flow run</p> <code>sync_portal</code> <code>Optional[BlockingPortal]</code> <p>A blocking portal for sync task/flow runs in an async flow</p> <code>timeout_scope</code> <code>Optional[CancelScope]</code> <p>The cancellation scope for flow level timeouts</p> Source code in <code>prefect/context.py</code> <pre><code>class EngineContext(RunContext):\n    \"\"\"\n    The context for a flow run. Data in this context is only available from within a\n    flow run function.\n\n    Attributes:\n        flow: The flow instance associated with the run\n        flow_run: The API metadata for the flow run\n        task_runner: The task runner instance being used for the flow run\n        task_run_futures: A list of futures for task runs submitted within this flow run\n        task_run_states: A list of states for task runs created within this flow run\n        task_run_results: A mapping of result ids to task run states for this flow run\n        flow_run_states: A list of states for flow runs created within this flow run\n        sync_portal: A blocking portal for sync task/flow runs in an async flow\n        timeout_scope: The cancellation scope for flow level timeouts\n    \"\"\"\n\n    flow: Optional[\"Flow\"] = None\n    flow_run: Optional[FlowRun] = None\n    autonomous_task_run: Optional[TaskRun] = None\n    task_runner: BaseTaskRunner\n    log_prints: bool = False\n    parameters: Optional[Dict[str, Any]] = None\n\n    # Result handling\n    result_factory: ResultFactory\n\n    # Counter for task calls allowing unique\n    task_run_dynamic_keys: Dict[str, int] = Field(default_factory=dict)\n\n    # Counter for flow pauses\n    observed_flow_pauses: Dict[str, int] = Field(default_factory=dict)\n\n    # Tracking for objects created by this flow run\n    task_run_futures: List[PrefectFuture] = Field(default_factory=list)\n    task_run_states: List[State] = Field(default_factory=list)\n    task_run_results: Dict[int, State] = Field(default_factory=dict)\n    flow_run_states: List[State] = Field(default_factory=list)\n\n    # The synchronous portal is only created for async flows for creating engine calls\n    # from synchronous task and subflow calls\n    sync_portal: Optional[anyio.abc.BlockingPortal] = None\n    timeout_scope: Optional[anyio.abc.CancelScope] = None\n\n    # Task group that can be used for background tasks during the flow run\n    background_tasks: anyio.abc.TaskGroup\n\n    # Events worker to emit events to Prefect Cloud\n    events: Optional[EventsWorker] = None\n\n    __var__ = ContextVar(\"flow_run\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.PrefectObjectRegistry","title":"<code>PrefectObjectRegistry</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>A context that acts as a registry for all Prefect objects that are registered during load and execution.</p> <p>Attributes:</p> Name Type Description <code>start_time</code> <code>DateTimeTZ</code> <p>The time the object registry was created.</p> <code>block_code_execution</code> <code>bool</code> <p>If set, flow calls will be ignored.</p> <code>capture_failures</code> <code>bool</code> <p>If set, failures during init will be silenced and tracked.</p> Source code in <code>prefect/context.py</code> <pre><code>class PrefectObjectRegistry(ContextModel):\n    \"\"\"\n    A context that acts as a registry for all Prefect objects that are\n    registered during load and execution.\n\n    Attributes:\n        start_time: The time the object registry was created.\n        block_code_execution: If set, flow calls will be ignored.\n        capture_failures: If set, failures during __init__ will be silenced and tracked.\n    \"\"\"\n\n    start_time: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n\n    _instance_registry: Dict[Type[T], List[T]] = PrivateAttr(\n        default_factory=lambda: defaultdict(list)\n    )\n\n    # Failures will be a tuple of (exception, instance, args, kwargs)\n    _instance_init_failures: Dict[\n        Type[T], List[Tuple[Exception, T, Tuple, Dict]]\n    ] = PrivateAttr(default_factory=lambda: defaultdict(list))\n\n    block_code_execution: bool = False\n    capture_failures: bool = False\n\n    __var__ = ContextVar(\"object_registry\")\n\n    def get_instances(self, type_: Type[T]) -&gt; List[T]:\n        instances = []\n        for registered_type, type_instances in self._instance_registry.items():\n            if type_ in registered_type.mro():\n                instances.extend(type_instances)\n        return instances\n\n    def get_instance_failures(\n        self, type_: Type[T]\n    ) -&gt; List[Tuple[Exception, T, Tuple, Dict]]:\n        failures = []\n        for type__ in type_.mro():\n            failures.extend(self._instance_init_failures[type__])\n        return failures\n\n    def register_instance(self, object):\n        # TODO: Consider using a 'Set' to avoid duplicate entries\n        self._instance_registry[type(object)].append(object)\n\n    def register_init_failure(\n        self, exc: Exception, object: Any, init_args: Tuple, init_kwargs: Dict\n    ):\n        self._instance_init_failures[type(object)].append(\n            (exc, object, init_args, init_kwargs)\n        )\n\n    @classmethod\n    def register_instances(cls, type_: Type[T]) -&gt; Type[T]:\n        \"\"\"\n        Decorator for a class that adds registration to the `PrefectObjectRegistry`\n        on initialization of instances.\n        \"\"\"\n        original_init = type_.__init__\n\n        def __register_init__(__self__: T, *args: Any, **kwargs: Any) -&gt; None:\n            registry = cls.get()\n            try:\n                original_init(__self__, *args, **kwargs)\n            except Exception as exc:\n                if not registry or not registry.capture_failures:\n                    raise\n                else:\n                    registry.register_init_failure(exc, __self__, args, kwargs)\n            else:\n                if registry:\n                    registry.register_instance(__self__)\n\n        update_wrapper(__register_init__, original_init)\n\n        type_.__init__ = __register_init__\n        return type_\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.PrefectObjectRegistry.register_instances","title":"<code>register_instances</code>  <code>classmethod</code>","text":"<p>Decorator for a class that adds registration to the <code>PrefectObjectRegistry</code> on initialization of instances.</p> Source code in <code>prefect/context.py</code> <pre><code>@classmethod\ndef register_instances(cls, type_: Type[T]) -&gt; Type[T]:\n    \"\"\"\n    Decorator for a class that adds registration to the `PrefectObjectRegistry`\n    on initialization of instances.\n    \"\"\"\n    original_init = type_.__init__\n\n    def __register_init__(__self__: T, *args: Any, **kwargs: Any) -&gt; None:\n        registry = cls.get()\n        try:\n            original_init(__self__, *args, **kwargs)\n        except Exception as exc:\n            if not registry or not registry.capture_failures:\n                raise\n            else:\n                registry.register_init_failure(exc, __self__, args, kwargs)\n        else:\n            if registry:\n                registry.register_instance(__self__)\n\n    update_wrapper(__register_init__, original_init)\n\n    type_.__init__ = __register_init__\n    return type_\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.RunContext","title":"<code>RunContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The base context for a flow or task run. Data in this context will always be available when <code>get_run_context</code> is called.</p> <p>Attributes:</p> Name Type Description <code>start_time</code> <code>DateTimeTZ</code> <p>The time the run context was entered</p> <code>client</code> <code>Union[PrefectClient, SyncPrefectClient]</code> <p>The Prefect client instance being used for API communication</p> Source code in <code>prefect/context.py</code> <pre><code>class RunContext(ContextModel):\n    \"\"\"\n    The base context for a flow or task run. Data in this context will always be\n    available when `get_run_context` is called.\n\n    Attributes:\n        start_time: The time the run context was entered\n        client: The Prefect client instance being used for API communication\n    \"\"\"\n\n    start_time: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    input_keyset: Optional[Dict[str, Dict[str, str]]] = None\n    client: Union[PrefectClient, SyncPrefectClient]\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.SettingsContext","title":"<code>SettingsContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The context for a Prefect settings.</p> <p>This allows for safe concurrent access and modification of settings.</p> <p>Attributes:</p> Name Type Description <code>profile</code> <code>Profile</code> <p>The profile that is in use.</p> <code>settings</code> <code>Settings</code> <p>The complete settings model.</p> Source code in <code>prefect/context.py</code> <pre><code>class SettingsContext(ContextModel):\n    \"\"\"\n    The context for a Prefect settings.\n\n    This allows for safe concurrent access and modification of settings.\n\n    Attributes:\n        profile: The profile that is in use.\n        settings: The complete settings model.\n    \"\"\"\n\n    profile: Profile\n    settings: Settings\n\n    __var__ = ContextVar(\"settings\")\n\n    def __hash__(self) -&gt; int:\n        return hash(self.settings)\n\n    def __enter__(self):\n        \"\"\"\n        Upon entrance, we ensure the home directory for the profile exists.\n        \"\"\"\n        return_value = super().__enter__()\n\n        try:\n            prefect_home = Path(self.settings.value_of(PREFECT_HOME))\n            prefect_home.mkdir(mode=0o0700, exist_ok=True)\n        except OSError:\n            warnings.warn(\n                (\n                    \"Failed to create the Prefect home directory at \"\n                    f\"{self.settings.value_of(PREFECT_HOME)}\"\n                ),\n                stacklevel=2,\n            )\n\n        return return_value\n\n    @classmethod\n    def get(cls) -&gt; \"SettingsContext\":\n        # Return the global context instead of `None` if no context exists\n        return super().get() or GLOBAL_SETTINGS_CONTEXT\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.TagsContext","title":"<code>TagsContext</code>","text":"<p>               Bases: <code>ContextModel</code></p> <p>The context for <code>prefect.tags</code> management.</p> <p>Attributes:</p> Name Type Description <code>current_tags</code> <code>Set[str]</code> <p>A set of current tags in the context</p> Source code in <code>prefect/context.py</code> <pre><code>class TagsContext(ContextModel):\n    \"\"\"\n    The context for `prefect.tags` management.\n\n    Attributes:\n        current_tags: A set of current tags in the context\n    \"\"\"\n\n    current_tags: Set[str] = Field(default_factory=set)\n\n    @classmethod\n    def get(cls) -&gt; \"TagsContext\":\n        # Return an empty `TagsContext` instead of `None` if no context exists\n        return cls.__var__.get(TagsContext())\n\n    __var__ = ContextVar(\"tags\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.TaskRunContext","title":"<code>TaskRunContext</code>","text":"<p>               Bases: <code>RunContext</code></p> <p>The context for a task run. Data in this context is only available from within a task run function.</p> <p>Attributes:</p> Name Type Description <code>task</code> <code>Task</code> <p>The task instance associated with the task run</p> <code>task_run</code> <code>TaskRun</code> <p>The API metadata for this task run</p> Source code in <code>prefect/context.py</code> <pre><code>class TaskRunContext(RunContext):\n    \"\"\"\n    The context for a task run. Data in this context is only available from within a\n    task run function.\n\n    Attributes:\n        task: The task instance associated with the task run\n        task_run: The API metadata for this task run\n    \"\"\"\n\n    task: \"Task\"\n    task_run: TaskRun\n    log_prints: bool = False\n    parameters: Dict[str, Any]\n\n    # Result handling\n    result_factory: ResultFactory\n\n    __var__ = ContextVar(\"task_run\")\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.get_run_context","title":"<code>get_run_context</code>","text":"<p>Get the current run context from within a task or flow function.</p> <p>Returns:</p> Type Description <code>Union[FlowRunContext, TaskRunContext]</code> <p>A <code>FlowRunContext</code> or <code>TaskRunContext</code> depending on the function type.</p> <p>Raises     RuntimeError: If called outside of a flow or task run.</p> Source code in <code>prefect/context.py</code> <pre><code>def get_run_context() -&gt; Union[FlowRunContext, TaskRunContext]:\n    \"\"\"\n    Get the current run context from within a task or flow function.\n\n    Returns:\n        A `FlowRunContext` or `TaskRunContext` depending on the function type.\n\n    Raises\n        RuntimeError: If called outside of a flow or task run.\n    \"\"\"\n    task_run_ctx = TaskRunContext.get()\n    if task_run_ctx:\n        return task_run_ctx\n\n    flow_run_ctx = FlowRunContext.get()\n    if flow_run_ctx:\n        return flow_run_ctx\n\n    raise MissingContextError(\n        \"No run context available. You are not in a flow or task run context.\"\n    )\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.get_settings_context","title":"<code>get_settings_context</code>","text":"<p>Get the current settings context which contains profile information and the settings that are being used.</p> <p>Generally, the settings that are being used are a combination of values from the profile and environment. See <code>prefect.context.use_profile</code> for more details.</p> Source code in <code>prefect/context.py</code> <pre><code>def get_settings_context() -&gt; SettingsContext:\n    \"\"\"\n    Get the current settings context which contains profile information and the\n    settings that are being used.\n\n    Generally, the settings that are being used are a combination of values from the\n    profile and environment. See `prefect.context.use_profile` for more details.\n    \"\"\"\n    settings_ctx = SettingsContext.get()\n\n    if not settings_ctx:\n        raise MissingContextError(\"No settings context found.\")\n\n    return settings_ctx\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.registry_from_script","title":"<code>registry_from_script</code>","text":"<p>Return a fresh registry with instances populated from execution of a script.</p> Source code in <code>prefect/context.py</code> <pre><code>def registry_from_script(\n    path: str,\n    block_code_execution: bool = True,\n    capture_failures: bool = True,\n) -&gt; PrefectObjectRegistry:\n    \"\"\"\n    Return a fresh registry with instances populated from execution of a script.\n    \"\"\"\n    with PrefectObjectRegistry(\n        block_code_execution=block_code_execution,\n        capture_failures=capture_failures,\n    ) as registry:\n        load_script_as_module(path)\n\n    return registry\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.root_settings_context","title":"<code>root_settings_context</code>","text":"<p>Return the settings context that will exist as the root context for the module.</p> <p>The profile to use is determined with the following precedence - Command line via 'prefect --profile ' - Environment variable via 'PREFECT_PROFILE' - Profiles file via the 'active' key Source code in <code>prefect/context.py</code> <pre><code>def root_settings_context():\n    \"\"\"\n    Return the settings context that will exist as the root context for the module.\n\n    The profile to use is determined with the following precedence\n    - Command line via 'prefect --profile &lt;name&gt;'\n    - Environment variable via 'PREFECT_PROFILE'\n    - Profiles file via the 'active' key\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    active_name = profiles.active_name\n    profile_source = \"in the profiles file\"\n\n    if \"PREFECT_PROFILE\" in os.environ:\n        active_name = os.environ[\"PREFECT_PROFILE\"]\n        profile_source = \"by environment variable\"\n\n    if (\n        sys.argv[0].endswith(\"/prefect\")\n        and len(sys.argv) &gt;= 3\n        and sys.argv[1] == \"--profile\"\n    ):\n        active_name = sys.argv[2]\n        profile_source = \"by command line argument\"\n\n    if active_name not in profiles.names:\n        print(\n            (\n                f\"WARNING: Active profile {active_name!r} set {profile_source} not \"\n                \"found. The default profile will be used instead. \"\n            ),\n            file=sys.stderr,\n        )\n        active_name = \"default\"\n\n    with use_profile(\n        profiles[active_name],\n        # Override environment variables if the profile was set by the CLI\n        override_environment_variables=profile_source == \"by command line argument\",\n    ) as settings_context:\n        return settings_context\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.tags","title":"<code>tags</code>","text":"<p>Context manager to add tags to flow and task run calls.</p> <p>Tags are always combined with any existing tags.</p> <p>Yields:</p> Type Description <code>Set[str]</code> <p>The current set of tags</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect import tags, task, flow\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Run a task with tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"a\", \"b\"):\n&gt;&gt;&gt;         my_task()  # has tags: a, b\n</code></pre> <p>Run a flow with tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt; with tags(\"a\", \"b\"):\n&gt;&gt;&gt;     my_flow()  # has tags: a, b\n</code></pre> <p>Run a task with nested tag contexts</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"a\", \"b\"):\n&gt;&gt;&gt;         with tags(\"c\", \"d\"):\n&gt;&gt;&gt;             my_task()  # has tags: a, b, c, d\n&gt;&gt;&gt;         my_task()  # has tags: a, b\n</code></pre> <p>Inspect the current tags</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     with tags(\"c\", \"d\"):\n&gt;&gt;&gt;         with tags(\"e\", \"f\") as current_tags:\n&gt;&gt;&gt;              print(current_tags)\n&gt;&gt;&gt; with tags(\"a\", \"b\"):\n&gt;&gt;&gt;     my_flow()\n{\"a\", \"b\", \"c\", \"d\", \"e\", \"f\"}\n</code></pre> Source code in <code>prefect/context.py</code> <pre><code>@contextmanager\ndef tags(*new_tags: str) -&gt; Generator[Set[str], None, None]:\n    \"\"\"\n    Context manager to add tags to flow and task run calls.\n\n    Tags are always combined with any existing tags.\n\n    Yields:\n        The current set of tags\n\n    Examples:\n        &gt;&gt;&gt; from prefect import tags, task, flow\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Run a task with tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;         my_task()  # has tags: a, b\n\n        Run a flow with tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt; with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;     my_flow()  # has tags: a, b\n\n        Run a task with nested tag contexts\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;         with tags(\"c\", \"d\"):\n        &gt;&gt;&gt;             my_task()  # has tags: a, b, c, d\n        &gt;&gt;&gt;         my_task()  # has tags: a, b\n\n        Inspect the current tags\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     with tags(\"c\", \"d\"):\n        &gt;&gt;&gt;         with tags(\"e\", \"f\") as current_tags:\n        &gt;&gt;&gt;              print(current_tags)\n        &gt;&gt;&gt; with tags(\"a\", \"b\"):\n        &gt;&gt;&gt;     my_flow()\n        {\"a\", \"b\", \"c\", \"d\", \"e\", \"f\"}\n    \"\"\"\n    current_tags = TagsContext.get().current_tags\n    new_tags = current_tags.union(new_tags)\n    with TagsContext(current_tags=new_tags):\n        yield new_tags\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/context/#prefect.context.use_profile","title":"<code>use_profile</code>","text":"<p>Switch to a profile for the duration of this context.</p> <p>Profile contexts are confined to an async context in a single thread.</p> <p>Parameters:</p> Name Type Description Default <code>profile</code> <code>Union[Profile, str]</code> <p>The name of the profile to load or an instance of a Profile.</p> required <code>override_environment_variable</code> <p>If set, variables in the profile will take precedence over current environment variables. By default, environment variables will override profile settings.</p> required <code>include_current_context</code> <code>bool</code> <p>If set, the new settings will be constructed with the current settings context as a base. If not set, the use_base settings will be loaded from the environment and defaults.</p> <code>True</code> <p>Yields:</p> Type Description <p>The created <code>SettingsContext</code> object</p> Source code in <code>prefect/context.py</code> <pre><code>@contextmanager\ndef use_profile(\n    profile: Union[Profile, str],\n    override_environment_variables: bool = False,\n    include_current_context: bool = True,\n):\n    \"\"\"\n    Switch to a profile for the duration of this context.\n\n    Profile contexts are confined to an async context in a single thread.\n\n    Args:\n        profile: The name of the profile to load or an instance of a Profile.\n        override_environment_variable: If set, variables in the profile will take\n            precedence over current environment variables. By default, environment\n            variables will override profile settings.\n        include_current_context: If set, the new settings will be constructed\n            with the current settings context as a base. If not set, the use_base settings\n            will be loaded from the environment and defaults.\n\n    Yields:\n        The created `SettingsContext` object\n    \"\"\"\n    if isinstance(profile, str):\n        profiles = prefect.settings.load_profiles()\n        profile = profiles[profile]\n\n    if not isinstance(profile, Profile):\n        raise TypeError(\n            f\"Unexpected type {type(profile).__name__!r} for `profile`. \"\n            \"Expected 'str' or 'Profile'.\"\n        )\n\n    # Create a copy of the profiles settings as we will mutate it\n    profile_settings = profile.settings.copy()\n\n    existing_context = SettingsContext.get()\n    if existing_context and include_current_context:\n        settings = existing_context.settings\n    else:\n        settings = prefect.settings.get_settings_from_env()\n\n    if not override_environment_variables:\n        for key in os.environ:\n            if key in prefect.settings.SETTING_VARIABLES:\n                profile_settings.pop(prefect.settings.SETTING_VARIABLES[key], None)\n\n    new_settings = settings.copy_with_update(updates=profile_settings)\n\n    with SettingsContext(profile=profile, settings=new_settings) as ctx:\n        yield ctx\n</code></pre>","tags":["Python API","flow run context","task run context","context"]},{"location":"api-ref/prefect/engine/","title":"prefect.engine","text":"","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine","title":"<code>prefect.engine</code>","text":"<p>Client-side execution and orchestration of flows and tasks.</p>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--engine-process-overview","title":"Engine process overview","text":"","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--flows","title":"Flows","text":"<ul> <li> <p>The flow is called by the user or an existing flow run is executed in a new process.</p> <p>See <code>Flow.__call__</code> and <code>prefect.engine.__main__</code> (<code>python -m prefect.engine</code>)</p> </li> <li> <p>A synchronous function acts as an entrypoint to the engine.     The engine executes on a dedicated \"global loop\" thread. For asynchronous flow calls,     we return a coroutine from the entrypoint so the user can enter the engine without     blocking their event loop.</p> <p>See <code>enter_flow_run_engine_from_flow_call</code>, <code>enter_flow_run_engine_from_subprocess</code></p> </li> <li> <p>The thread that calls the entrypoint waits until orchestration of the flow run completes.     This thread is referred to as the \"user\" thread and is usually the \"main\" thread.     The thread is not blocked while waiting \u2014 it allows the engine to send work back to it.     This allows us to send calls back to the user thread from the global loop thread.</p> <p>See <code>wait_for_call_in_loop_thread</code> and <code>call_soon_in_waiting_thread</code></p> </li> <li> <p>The asynchronous engine branches depending on if the flow run exists already and if     there is a parent flow run in the current context.</p> <p>See <code>create_then_begin_flow_run</code>, <code>create_and_begin_subflow_run</code>, and <code>retrieve_flow_then_begin_flow_run</code></p> </li> <li> <p>The asynchronous engine prepares for execution of the flow run.     This includes starting the task runner, preparing context, etc.</p> <p>See <code>begin_flow_run</code></p> </li> <li> <p>The flow run is orchestrated through states, calling the user's function as necessary.     Generally the user's function is sent for execution on the user thread.     If the flow function cannot be safely executed on the user thread, e.g. it is     a synchronous child in an asynchronous parent it will be scheduled on a worker     thread instead.</p> <p>See <code>orchestrate_flow_run</code>, <code>call_soon_in_waiting_thread</code>, <code>call_soon_in_new_thread</code></p> </li> </ul>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine--tasks","title":"Tasks","text":"<ul> <li> <p>The task is called or submitted by the user.     We require that this is always within a flow.</p> <p>See <code>Task.__call__</code> and <code>Task.submit</code></p> </li> <li> <p>A synchronous function acts as an entrypoint to the engine.     Unlike flow calls, this will not block until completion if <code>submit</code> was used.</p> <p>See <code>enter_task_run_engine</code></p> </li> <li> <p>A future is created for the task call.     Creation of the task run and submission to the task runner is scheduled as a     background task so submission of many tasks can occur concurrently.</p> <p>See <code>create_task_run_future</code> and <code>create_task_run_then_submit</code></p> </li> <li> <p>The engine branches depending on if a future, state, or result is requested.     If a future is requested, it is returned immediately to the user thread.     Otherwise, the engine will wait for the task run to complete and return the final     state or result.</p> <p>See <code>get_task_call_return_value</code></p> </li> <li> <p>An engine function is submitted to the task runner.     The task runner will schedule this function for execution on a worker.     When executed, it will prepare for orchestration and wait for completion of the run.</p> <p>See <code>create_task_run_then_submit</code> and <code>begin_task_run</code></p> </li> <li> <p>The task run is orchestrated through states, calling the user's function as necessary.     The user's function is always executed in a worker thread for isolation.</p> <p>See <code>orchestrate_task_run</code>, <code>call_soon_in_new_thread</code></p> <p>_Ideally, for local and sequential task runners we would send the task run to the user thread as we do for flows. See #9855.</p> </li> </ul>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_flow_run","title":"<code>begin_flow_run</code>  <code>async</code>","text":"<p>Begins execution of a flow run; blocks until completion of the flow run</p> <ul> <li>Starts a task runner</li> <li>Determines the result storage block to use</li> <li>Orchestrates the flow run (runs the user-function and generates tasks)</li> <li>Waits for tasks to complete / shutsdown the task runner</li> <li>Sets a terminal state for the flow run</li> </ul> <p>Note that the <code>flow_run</code> contains a <code>parameters</code> attribute which is the serialized parameters sent to the backend while the <code>parameters</code> argument here should be the deserialized and validated dictionary of python objects.</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_flow_run(\n    flow: Flow,\n    flow_run: FlowRun,\n    parameters: Dict[str, Any],\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Begins execution of a flow run; blocks until completion of the flow run\n\n    - Starts a task runner\n    - Determines the result storage block to use\n    - Orchestrates the flow run (runs the user-function and generates tasks)\n    - Waits for tasks to complete / shutsdown the task runner\n    - Sets a terminal state for the flow run\n\n    Note that the `flow_run` contains a `parameters` attribute which is the serialized\n    parameters sent to the backend while the `parameters` argument here should be the\n    deserialized and validated dictionary of python objects.\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    logger = flow_run_logger(flow_run, flow)\n\n    log_prints = should_log_prints(flow)\n    flow_run_context = FlowRunContext.construct(log_prints=log_prints)\n\n    async with AsyncExitStack() as stack:\n        await stack.enter_async_context(\n            report_flow_run_crashes(flow_run=flow_run, client=client, flow=flow)\n        )\n\n        # Create a task group for background tasks\n        flow_run_context.background_tasks = await stack.enter_async_context(\n            anyio.create_task_group()\n        )\n\n        # If the flow is async, we need to provide a portal so sync tasks can run\n        flow_run_context.sync_portal = (\n            stack.enter_context(start_blocking_portal()) if flow.isasync else None\n        )\n\n        task_runner = flow.task_runner.duplicate()\n        if task_runner is NotImplemented:\n            # Backwards compatibility; will not support concurrent flow runs\n            task_runner = flow.task_runner\n            logger.warning(\n                f\"Task runner {type(task_runner).__name__!r} does not implement the\"\n                \" `duplicate` method and will fail if used for concurrent execution of\"\n                \" the same flow.\"\n            )\n\n        logger.debug(\n            f\"Starting {type(flow.task_runner).__name__!r}; submitted tasks \"\n            f\"will be run {CONCURRENCY_MESSAGES[flow.task_runner.concurrency_type]}...\"\n        )\n\n        flow_run_context.task_runner = await stack.enter_async_context(\n            task_runner.start()\n        )\n\n        flow_run_context.result_factory = await ResultFactory.from_flow(\n            flow, client=client\n        )\n\n        if log_prints:\n            stack.enter_context(patch_print())\n\n        terminal_or_paused_state = await orchestrate_flow_run(\n            flow,\n            flow_run=flow_run,\n            parameters=parameters,\n            wait_for=None,\n            client=client,\n            partial_flow_run_context=flow_run_context,\n            # Orchestration needs to be interruptible if it has a timeout\n            interruptible=flow.timeout_seconds is not None,\n            user_thread=user_thread,\n        )\n\n    if terminal_or_paused_state.is_paused():\n        timeout = terminal_or_paused_state.state_details.pause_timeout\n        msg = \"Currently paused and suspending execution.\"\n        if timeout:\n            msg += f\" Resume before {timeout.to_rfc3339_string()} to finish execution.\"\n        logger.log(level=logging.INFO, msg=msg)\n        await APILogHandler.aflush()\n\n        return terminal_or_paused_state\n    else:\n        terminal_state = terminal_or_paused_state\n\n    # If debugging, use the more complete `repr` than the usual `str` description\n    display_state = repr(terminal_state) if PREFECT_DEBUG_MODE else str(terminal_state)\n\n    logger.log(\n        level=logging.INFO if terminal_state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n\n    # When a \"root\" flow run finishes, flush logs so we do not have to rely on handling\n    # during interpreter shutdown\n    await APILogHandler.aflush()\n\n    return terminal_state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_task_map","title":"<code>begin_task_map</code>  <code>async</code>","text":"<p>Async entrypoint for task mapping</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_task_map(\n    task: Task,\n    flow_run_context: Optional[FlowRunContext],\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    task_runner: Optional[BaseTaskRunner],\n    autonomous: bool = False,\n) -&gt; List[Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun]]:\n    \"\"\"Async entrypoint for task mapping\"\"\"\n    # We need to resolve some futures to map over their data, collect the upstream\n    # links beforehand to retain relationship tracking.\n    task_inputs = {\n        k: await collect_task_run_inputs(v, max_depth=0) for k, v in parameters.items()\n    }\n\n    # Resolve the top-level parameters in order to get mappable data of a known length.\n    # Nested parameters will be resolved in each mapped child where their relationships\n    # will also be tracked.\n    parameters = await resolve_inputs(parameters, max_depth=1)\n\n    # Ensure that any parameters in kwargs are expanded before this check\n    parameters = explode_variadic_parameter(task.fn, parameters)\n\n    iterable_parameters = {}\n    static_parameters = {}\n    annotated_parameters = {}\n    for key, val in parameters.items():\n        if isinstance(val, (allow_failure, quote)):\n            # Unwrap annotated parameters to determine if they are iterable\n            annotated_parameters[key] = val\n            val = val.unwrap()\n\n        if isinstance(val, unmapped):\n            static_parameters[key] = val.value\n        elif isiterable(val):\n            iterable_parameters[key] = list(val)\n        else:\n            static_parameters[key] = val\n\n    if not len(iterable_parameters):\n        raise MappingMissingIterable(\n            \"No iterable parameters were received. Parameters for map must \"\n            f\"include at least one iterable. Parameters: {parameters}\"\n        )\n\n    iterable_parameter_lengths = {\n        key: len(val) for key, val in iterable_parameters.items()\n    }\n    lengths = set(iterable_parameter_lengths.values())\n    if len(lengths) &gt; 1:\n        raise MappingLengthMismatch(\n            \"Received iterable parameters with different lengths. Parameters for map\"\n            f\" must all be the same length. Got lengths: {iterable_parameter_lengths}\"\n        )\n\n    map_length = list(lengths)[0]\n\n    task_runs = []\n    for i in range(map_length):\n        call_parameters = {key: value[i] for key, value in iterable_parameters.items()}\n        call_parameters.update({key: value for key, value in static_parameters.items()})\n\n        # Add default values for parameters; these are skipped earlier since they should\n        # not be mapped over\n        for key, value in get_parameter_defaults(task.fn).items():\n            call_parameters.setdefault(key, value)\n\n        # Re-apply annotations to each key again\n        for key, annotation in annotated_parameters.items():\n            call_parameters[key] = annotation.rewrap(call_parameters[key])\n\n        # Collapse any previously exploded kwargs\n        call_parameters = collapse_variadic_parameters(task.fn, call_parameters)\n\n        if autonomous:\n            task_runs.append(\n                await create_autonomous_task_run(\n                    task=task,\n                    parameters=call_parameters,\n                )\n            )\n        else:\n            task_runs.append(\n                partial(\n                    get_task_call_return_value,\n                    task=task,\n                    flow_run_context=flow_run_context,\n                    parameters=call_parameters,\n                    wait_for=wait_for,\n                    return_type=return_type,\n                    task_runner=task_runner,\n                    extra_task_inputs=task_inputs,\n                )\n            )\n\n    if autonomous:\n        return task_runs\n\n    # Maintain the order of the task runs when using the sequential task runner\n    runner = task_runner if task_runner else flow_run_context.task_runner\n    if runner.concurrency_type == TaskConcurrencyType.SEQUENTIAL:\n        return [await task_run() for task_run in task_runs]\n\n    return await gather(*task_runs)\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.begin_task_run","title":"<code>begin_task_run</code>  <code>async</code>","text":"<p>Entrypoint for task run execution.</p> <p>This function is intended for submission to the task runner.</p> <p>This method may be called from a worker so we ensure the settings context has been entered. For example, with a runner that is executing tasks in the same event loop, we will likely not enter the context again because the current context already matches:</p> <p>main thread: --&gt; Flow called with settings A --&gt; <code>begin_task_run</code> executes same event loop --&gt; Profile A matches and is not entered again</p> <p>However, with execution on a remote environment, we are going to need to ensure the settings for the task run are respected by entering the context:</p> <p>main thread: --&gt; Flow called with settings A --&gt; <code>begin_task_run</code> is scheduled on a remote worker, settings A is serialized remote worker: --&gt; Remote worker imports Prefect (may not occur) --&gt; Global settings is loaded with default settings --&gt; <code>begin_task_run</code> executes on a different event loop than the flow --&gt; Current settings is not set or does not match, settings A is entered</p> Source code in <code>prefect/engine.py</code> <pre><code>async def begin_task_run(\n    task: Task,\n    task_run: TaskRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    result_factory: ResultFactory,\n    log_prints: bool,\n    settings: prefect.context.SettingsContext,\n):\n    \"\"\"\n    Entrypoint for task run execution.\n\n    This function is intended for submission to the task runner.\n\n    This method may be called from a worker so we ensure the settings context has been\n    entered. For example, with a runner that is executing tasks in the same event loop,\n    we will likely not enter the context again because the current context already\n    matches:\n\n    main thread:\n    --&gt; Flow called with settings A\n    --&gt; `begin_task_run` executes same event loop\n    --&gt; Profile A matches and is not entered again\n\n    However, with execution on a remote environment, we are going to need to ensure the\n    settings for the task run are respected by entering the context:\n\n    main thread:\n    --&gt; Flow called with settings A\n    --&gt; `begin_task_run` is scheduled on a remote worker, settings A is serialized\n    remote worker:\n    --&gt; Remote worker imports Prefect (may not occur)\n    --&gt; Global settings is loaded with default settings\n    --&gt; `begin_task_run` executes on a different event loop than the flow\n    --&gt; Current settings is not set or does not match, settings A is entered\n    \"\"\"\n    maybe_flow_run_context = prefect.context.FlowRunContext.get()\n\n    async with AsyncExitStack() as stack:\n        # The settings context may be null on a remote worker so we use the safe `.get`\n        # method and compare it to the settings required for this task run\n        if prefect.context.SettingsContext.get() != settings:\n            stack.enter_context(settings)\n            setup_logging()\n\n        if maybe_flow_run_context:\n            # Accessible if on a worker that is running in the same thread as the flow\n            client = maybe_flow_run_context.client\n            # Only run the task in an interruptible thread if it in the same thread as\n            # the flow _and_ the flow run has a timeout attached. If the task is on a\n            # worker, the flow run timeout will not be raised in the worker process.\n            interruptible = maybe_flow_run_context.timeout_scope is not None\n        else:\n            # Otherwise, retrieve a new clien`t\n            client = await stack.enter_async_context(get_client())\n            interruptible = False\n            await stack.enter_async_context(anyio.create_task_group())\n\n        await stack.enter_async_context(report_task_run_crashes(task_run, client))\n\n        # TODO: Use the background tasks group to manage logging for this task\n\n        if log_prints:\n            stack.enter_context(patch_print())\n\n        await check_api_reachable(\n            client, f\"Cannot orchestrate task run '{task_run.id}'\"\n        )\n        try:\n            state = await orchestrate_task_run(\n                task=task,\n                task_run=task_run,\n                parameters=parameters,\n                wait_for=wait_for,\n                result_factory=result_factory,\n                log_prints=log_prints,\n                interruptible=interruptible,\n                client=client,\n            )\n\n            if not maybe_flow_run_context:\n                # When a a task run finishes on a remote worker flush logs to prevent\n                # loss if the process exits\n                await APILogHandler.aflush()\n\n        except Abort as abort:\n            # Task run probably already completed, fetch its state\n            task_run = await client.read_task_run(task_run.id)\n\n            if task_run.state.is_final():\n                task_run_logger(task_run).info(\n                    f\"Task run '{task_run.id}' already finished.\"\n                )\n            else:\n                # TODO: This is a concerning case; we should determine when this occurs\n                #       1. This can occur when the flow run is not in a running state\n                task_run_logger(task_run).warning(\n                    f\"Task run '{task_run.id}' received abort during orchestration: \"\n                    f\"{abort} Task run is in {task_run.state.type.value} state.\"\n                )\n            state = task_run.state\n\n        except Pause:\n            # A pause signal here should mean the flow run suspended, so we\n            # should do the same. We'll look up the flow run's pause state to\n            # try and reuse it, so we capture any data like timeouts.\n            flow_run = await client.read_flow_run(task_run.flow_run_id)\n            if flow_run.state and flow_run.state.is_paused():\n                state = flow_run.state\n            else:\n                state = Suspended()\n\n            task_run_logger(task_run).info(\n                \"Task run encountered a pause signal during orchestration.\"\n            )\n\n        return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_and_begin_subflow_run","title":"<code>create_and_begin_subflow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flows calls within a flow run</p> <p>Subflows differ from parent flows in that they - Resolve futures in passed parameters into values - Create a dummy task for representation in the parent flow - Retrieve default result storage from the parent flow rather than the server</p> <p>Returns:</p> Type Description <code>Any</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def create_and_begin_subflow_run(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; Any:\n    \"\"\"\n    Async entrypoint for flows calls within a flow run\n\n    Subflows differ from parent flows in that they\n    - Resolve futures in passed parameters into values\n    - Create a dummy task for representation in the parent flow\n    - Retrieve default result storage from the parent flow rather than the server\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    parent_flow_run_context = FlowRunContext.get()\n    parent_logger = get_run_logger(parent_flow_run_context)\n    log_prints = should_log_prints(flow)\n    terminal_state = None\n\n    parent_logger.debug(f\"Resolving inputs to {flow.name!r}\")\n    task_inputs = {k: await collect_task_run_inputs(v) for k, v in parameters.items()}\n\n    if wait_for:\n        task_inputs[\"wait_for\"] = await collect_task_run_inputs(wait_for)\n\n    rerunning = (\n        parent_flow_run_context.flow_run.run_count &gt; 1\n        if getattr(parent_flow_run_context, \"flow_run\", None)\n        else False\n    )\n\n    # Generate a task in the parent flow run to represent the result of the subflow run\n    dummy_task = Task(name=flow.name, fn=flow.fn, version=flow.version)\n    parent_task_run = await client.create_task_run(\n        task=dummy_task,\n        flow_run_id=(\n            parent_flow_run_context.flow_run.id\n            if getattr(parent_flow_run_context, \"flow_run\", None)\n            else None\n        ),\n        dynamic_key=_dynamic_key_for_task_run(parent_flow_run_context, dummy_task),\n        task_inputs=task_inputs,\n        state=Pending(),\n    )\n\n    # Resolve any task futures in the input\n    parameters = await resolve_inputs(parameters)\n\n    if parent_task_run.state.is_final() and not (\n        rerunning and not parent_task_run.state.is_completed()\n    ):\n        # Retrieve the most recent flow run from the database\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                parent_task_run_id={\"any_\": [parent_task_run.id]}\n            ),\n            sort=FlowRunSort.EXPECTED_START_TIME_ASC,\n        )\n        flow_run = flow_runs[-1]\n\n        # Set up variables required downstream\n        terminal_state = flow_run.state\n        logger = flow_run_logger(flow_run, flow)\n\n    else:\n        flow_run = await client.create_flow_run(\n            flow,\n            parameters=flow.serialize_parameters(parameters),\n            parent_task_run_id=parent_task_run.id,\n            state=parent_task_run.state if not rerunning else Pending(),\n            tags=TagsContext.get().current_tags,\n        )\n\n        parent_logger.info(\n            f\"Created subflow run {flow_run.name!r} for flow {flow.name!r}\"\n        )\n\n        logger = flow_run_logger(flow_run, flow)\n        ui_url = PREFECT_UI_URL.value()\n        if ui_url:\n            logger.info(\n                f\"View at {ui_url}/flow-runs/flow-run/{flow_run.id}\",\n                extra={\"send_to_api\": False},\n            )\n\n        result_factory = await ResultFactory.from_flow(\n            flow, client=parent_flow_run_context.client\n        )\n\n        if flow.should_validate_parameters:\n            try:\n                parameters = flow.validate_parameters(parameters)\n            except Exception:\n                message = \"Validation of flow parameters failed with error:\"\n                logger.exception(message)\n                terminal_state = await propose_state(\n                    client,\n                    state=await exception_to_failed_state(\n                        message=message, result_factory=result_factory\n                    ),\n                    flow_run_id=flow_run.id,\n                )\n\n        if terminal_state is None or not terminal_state.is_final():\n            async with AsyncExitStack() as stack:\n                await stack.enter_async_context(\n                    report_flow_run_crashes(flow_run=flow_run, client=client, flow=flow)\n                )\n\n                task_runner = flow.task_runner.duplicate()\n                if task_runner is NotImplemented:\n                    # Backwards compatibility; will not support concurrent flow runs\n                    task_runner = flow.task_runner\n                    logger.warning(\n                        f\"Task runner {type(task_runner).__name__!r} does not implement\"\n                        \" the `duplicate` method and will fail if used for concurrent\"\n                        \" execution of the same flow.\"\n                    )\n\n                await stack.enter_async_context(task_runner.start())\n\n                if log_prints:\n                    stack.enter_context(patch_print())\n\n                terminal_state = await orchestrate_flow_run(\n                    flow,\n                    flow_run=flow_run,\n                    parameters=parameters,\n                    wait_for=wait_for,\n                    # If the parent flow run has a timeout, then this one needs to be\n                    # interruptible as well\n                    interruptible=parent_flow_run_context.timeout_scope is not None,\n                    client=client,\n                    partial_flow_run_context=FlowRunContext.construct(\n                        sync_portal=parent_flow_run_context.sync_portal,\n                        task_runner=task_runner,\n                        background_tasks=parent_flow_run_context.background_tasks,\n                        result_factory=result_factory,\n                        log_prints=log_prints,\n                    ),\n                    user_thread=user_thread,\n                )\n\n    # Display the full state (including the result) if debugging\n    display_state = repr(terminal_state) if PREFECT_DEBUG_MODE else str(terminal_state)\n    logger.log(\n        level=logging.INFO if terminal_state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n\n    # Track the subflow state so the parent flow can use it to determine its final state\n    parent_flow_run_context.flow_run_states.append(terminal_state)\n\n    if return_type == \"state\":\n        return terminal_state\n    elif return_type == \"result\":\n        return await terminal_state.result(fetch=True)\n    else:\n        raise ValueError(f\"Invalid return type for flow engine {return_type!r}.\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_autonomous_task_run","title":"<code>create_autonomous_task_run</code>  <code>async</code>","text":"<p>Create a task run in the API for an autonomous task submission and store the provided parameters using the existing result storage mechanism.</p> Source code in <code>prefect/engine.py</code> <pre><code>async def create_autonomous_task_run(task: Task, parameters: Dict[str, Any]) -&gt; TaskRun:\n    \"\"\"Create a task run in the API for an autonomous task submission and store\n    the provided parameters using the existing result storage mechanism.\n    \"\"\"\n    async with get_client() as client:\n        state = Scheduled()\n        if parameters:\n            parameters_id = uuid4()\n            state.state_details.task_parameters_id = parameters_id\n\n            # TODO: Improve use of result storage for parameter storage / reference\n            task.persist_result = True\n\n            factory = await ResultFactory.from_autonomous_task(task, client=client)\n            await factory.store_parameters(parameters_id, parameters)\n\n        task_run = await client.create_task_run(\n            task=task,\n            flow_run_id=None,\n            dynamic_key=f\"{task.task_key}-{str(uuid4())[:NUM_CHARS_DYNAMIC_KEY]}\",\n            state=state,\n        )\n\n        engine_logger.debug(f\"Submitted run of task {task.name!r} for execution\")\n\n    return task_run\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.create_then_begin_flow_run","title":"<code>create_then_begin_flow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flow calls</p> <p>Creates the flow run in the backend, then enters the main flow run engine.</p> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def create_then_begin_flow_run(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; Any:\n    \"\"\"\n    Async entrypoint for flow calls\n\n    Creates the flow run in the backend, then enters the main flow run engine.\n    \"\"\"\n    # TODO: Returns a `State` depending on `return_type` and we can add an overload to\n    #       the function signature to clarify this eventually.\n\n    await check_api_reachable(client, \"Cannot create flow run\")\n\n    flow_run = None\n    state = Pending()\n    if flow.should_validate_parameters:\n        try:\n            parameters = flow.validate_parameters(parameters)\n        except Exception:\n            state = await exception_to_failed_state(\n                message=\"Validation of flow parameters failed with error:\"\n            )\n            flow_run = await _make_flow_run(flow, parameters, state, client)\n            await _run_flow_hooks(flow, flow_run, state)\n\n    flow_run = flow_run or await _make_flow_run(flow, parameters, state, client)\n\n    engine_logger.info(f\"Created flow run {flow_run.name!r} for flow {flow.name!r}\")\n\n    logger = flow_run_logger(flow_run, flow)\n\n    ui_url = PREFECT_UI_URL.value()\n    if ui_url:\n        logger.info(\n            f\"View at {ui_url}/flow-runs/flow-run/{flow_run.id}\",\n            extra={\"send_to_api\": False},\n        )\n\n    if state.is_failed():\n        logger.error(state.message)\n        engine_logger.info(\n            f\"Flow run {flow_run.name!r} received invalid parameters and is marked as\"\n            \" failed.\"\n        )\n    else:\n        state = await begin_flow_run(\n            flow=flow,\n            flow_run=flow_run,\n            parameters=parameters,\n            client=client,\n            user_thread=user_thread,\n        )\n\n    if return_type == \"state\":\n        return state\n    elif return_type == \"result\":\n        return await state.result(fetch=True)\n    else:\n        raise ValueError(f\"Invalid return type for flow engine {return_type!r}.\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_flow_run_engine_from_flow_call","title":"<code>enter_flow_run_engine_from_flow_call</code>","text":"<p>Sync entrypoint for flow calls.</p> <p>This function does the heavy lifting of ensuring we can get into an async context for flow run execution with minimal overhead.</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_flow_run_engine_from_flow_call(\n    flow: Flow,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n) -&gt; Union[State, Awaitable[State]]:\n    \"\"\"\n    Sync entrypoint for flow calls.\n\n    This function does the heavy lifting of ensuring we can get into an async context\n    for flow run execution with minimal overhead.\n    \"\"\"\n    setup_logging()\n\n    registry = PrefectObjectRegistry.get()\n    if registry and registry.block_code_execution:\n        engine_logger.warning(\n            f\"Script loading is in progress, flow {flow.name!r} will not be executed.\"\n            \" Consider updating the script to only call the flow if executed\"\n            f' directly:\\n\\n\\tif __name__ == \"__main__\":\\n\\t\\t{flow.fn.__name__}()'\n        )\n        return None\n\n    parent_flow_run_context = FlowRunContext.get()\n    is_subflow_run = parent_flow_run_context is not None\n\n    if wait_for is not None and not is_subflow_run:\n        raise ValueError(\"Only flows run as subflows can wait for dependencies.\")\n\n    begin_run = create_call(\n        create_and_begin_subflow_run if is_subflow_run else create_then_begin_flow_run,\n        flow=flow,\n        parameters=parameters,\n        wait_for=wait_for,\n        return_type=return_type,\n        client=parent_flow_run_context.client if is_subflow_run else None,\n        user_thread=threading.current_thread(),\n    )\n\n    # On completion of root flows, wait for the global thread to ensure that\n    # any work there is complete\n    done_callbacks = (\n        [create_call(wait_for_global_loop_exit)] if not is_subflow_run else None\n    )\n\n    # WARNING: You must define any context managers here to pass to our concurrency\n    # api instead of entering them in here in the engine entrypoint. Otherwise, async\n    # flows will not use the context as this function _exits_ to return an awaitable to\n    # the user. Generally, you should enter contexts _within_ the async `begin_run`\n    # instead but if you need to enter a context from the main thread you'll need to do\n    # it here.\n    contexts = [capture_sigterm(), collapse_excgroups()]\n\n    if flow.isasync and (\n        not is_subflow_run or (is_subflow_run and parent_flow_run_context.flow.isasync)\n    ):\n        # return a coro for the user to await if the flow is async\n        # unless it is an async subflow called in a sync flow\n        retval = from_async.wait_for_call_in_loop_thread(\n            begin_run,\n            done_callbacks=done_callbacks,\n            contexts=contexts,\n        )\n\n    else:\n        retval = from_sync.wait_for_call_in_loop_thread(\n            begin_run,\n            done_callbacks=done_callbacks,\n            contexts=contexts,\n        )\n\n    return retval\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_flow_run_engine_from_subprocess","title":"<code>enter_flow_run_engine_from_subprocess</code>","text":"<p>Sync entrypoint for flow runs that have been submitted for execution by an agent</p> <p>Differs from <code>enter_flow_run_engine_from_flow_call</code> in that we have a flow run id but not a flow object. The flow must be retrieved before execution can begin. Additionally, this assumes that the caller is always in a context without an event loop as this should be called from a fresh process.</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_flow_run_engine_from_subprocess(flow_run_id: UUID) -&gt; State:\n    \"\"\"\n    Sync entrypoint for flow runs that have been submitted for execution by an agent\n\n    Differs from `enter_flow_run_engine_from_flow_call` in that we have a flow run id\n    but not a flow object. The flow must be retrieved before execution can begin.\n    Additionally, this assumes that the caller is always in a context without an event\n    loop as this should be called from a fresh process.\n    \"\"\"\n\n    # Ensure collections are imported and have the opportunity to register types before\n    # loading the user code from the deployment\n    prefect.plugins.load_prefect_collections()\n\n    setup_logging()\n\n    state = from_sync.wait_for_call_in_loop_thread(\n        create_call(\n            retrieve_flow_then_begin_flow_run,\n            flow_run_id,\n            user_thread=threading.current_thread(),\n        ),\n        contexts=[capture_sigterm(), collapse_excgroups()],\n    )\n\n    APILogHandler.flush()\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.enter_task_run_engine","title":"<code>enter_task_run_engine</code>","text":"<p>Sync entrypoint for task calls</p> Source code in <code>prefect/engine.py</code> <pre><code>def enter_task_run_engine(\n    task: Task,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    return_type: EngineReturnType,\n    task_runner: Optional[BaseTaskRunner],\n    mapped: bool,\n    entering_from_task_run: Optional[bool] = False,\n) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun]:\n    \"\"\"Sync entrypoint for task calls\"\"\"\n\n    flow_run_context = FlowRunContext.get()\n\n    if not flow_run_context:\n        if return_type == \"future\" or mapped:\n            raise RuntimeError(\n                \" If you meant to submit a background task, you need to set\"\n                \" `prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=true`\"\n                \" and use `your_task.submit()` instead of `your_task()`.\"\n            )\n        from prefect.task_engine import submit_autonomous_task_run_to_engine\n\n        return submit_autonomous_task_run_to_engine(\n            task=task,\n            task_run=None,\n            parameters=parameters,\n            task_runner=task_runner,\n            wait_for=wait_for,\n            return_type=return_type,\n            client=get_client(),\n        )\n\n    if flow_run_context.timeout_scope and flow_run_context.timeout_scope.cancel_called:\n        raise TimeoutError(\"Flow run timed out\")\n\n    call_arguments = {\n        \"task\": task,\n        \"flow_run_context\": flow_run_context,\n        \"parameters\": parameters,\n        \"wait_for\": wait_for,\n        \"return_type\": return_type,\n        \"task_runner\": task_runner,\n    }\n\n    if not mapped:\n        call_arguments[\"entering_from_task_run\"] = entering_from_task_run\n\n    begin_run = create_call(\n        begin_task_map if mapped else get_task_call_return_value, **call_arguments\n    )\n\n    if task.isasync and (\n        flow_run_context.flow is None or flow_run_context.flow.isasync\n    ):\n        # return a coro for the user to await if an async task in an async flow\n        return from_async.wait_for_call_in_loop_thread(begin_run)\n    else:\n        return from_sync.wait_for_call_in_loop_thread(begin_run)\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.orchestrate_flow_run","title":"<code>orchestrate_flow_run</code>  <code>async</code>","text":"<p>Executes a flow run.</p> Note on flow timeouts <p>Since async flows are run directly in the main event loop, timeout behavior will match that described by anyio. If the flow is awaiting something, it will immediately return; otherwise, the next time it awaits it will exit. Sync flows are being task runner in a worker thread, which cannot be interrupted. The worker thread will exit at the next task call. The worker thread also has access to the status of the cancellation scope at <code>FlowRunContext.timeout_scope.cancel_called</code> which allows it to raise a <code>TimeoutError</code> to respect the timeout.</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def orchestrate_flow_run(\n    flow: Flow,\n    flow_run: FlowRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    interruptible: bool,\n    client: PrefectClient,\n    partial_flow_run_context: FlowRunContext,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Executes a flow run.\n\n    Note on flow timeouts:\n        Since async flows are run directly in the main event loop, timeout behavior will\n        match that described by anyio. If the flow is awaiting something, it will\n        immediately return; otherwise, the next time it awaits it will exit. Sync flows\n        are being task runner in a worker thread, which cannot be interrupted. The worker\n        thread will exit at the next task call. The worker thread also has access to the\n        status of the cancellation scope at `FlowRunContext.timeout_scope.cancel_called`\n        which allows it to raise a `TimeoutError` to respect the timeout.\n\n    Returns:\n        The final state of the run\n    \"\"\"\n\n    logger = flow_run_logger(flow_run, flow)\n\n    flow_run_context = None\n    parent_flow_run_context = FlowRunContext.get()\n\n    try:\n        # Resolve futures in any non-data dependencies to ensure they are ready\n        if wait_for is not None:\n            await resolve_inputs({\"wait_for\": wait_for}, return_data=False)\n    except UpstreamTaskError as upstream_exc:\n        return await propose_state(\n            client,\n            Pending(name=\"NotReady\", message=str(upstream_exc)),\n            flow_run_id=flow_run.id,\n            # if orchestrating a run already in a pending state, force orchestration to\n            # update the state name\n            force=flow_run.state.is_pending(),\n        )\n\n    state = await propose_state(client, Running(), flow_run_id=flow_run.id)\n\n    # flag to ensure we only update the flow run name once\n    run_name_set = False\n\n    await _run_flow_hooks(flow=flow, flow_run=flow_run, state=state)\n\n    while state.is_running():\n        waited_for_task_runs = False\n\n        # Update the flow run to the latest data\n        flow_run = await client.read_flow_run(flow_run.id)\n        try:\n            with FlowRunContext(\n                **{\n                    **partial_flow_run_context.dict(),\n                    **{\n                        \"flow_run\": flow_run,\n                        \"flow\": flow,\n                        \"client\": client,\n                        \"parameters\": parameters,\n                    },\n                }\n            ) as flow_run_context:\n                # update flow run name\n                if not run_name_set and flow.flow_run_name:\n                    flow_run_name = _resolve_custom_flow_run_name(\n                        flow=flow, parameters=parameters\n                    )\n\n                    await client.update_flow_run(\n                        flow_run_id=flow_run.id, name=flow_run_name\n                    )\n                    logger.extra[\"flow_run_name\"] = flow_run_name\n                    logger.debug(\n                        f\"Renamed flow run {flow_run.name!r} to {flow_run_name!r}\"\n                    )\n                    flow_run.name = flow_run_name\n                    run_name_set = True\n\n                args, kwargs = parameters_to_args_kwargs(flow.fn, parameters)\n                logger.debug(\n                    f\"Executing flow {flow.name!r} for flow run {flow_run.name!r}...\"\n                )\n\n                if PREFECT_DEBUG_MODE:\n                    logger.debug(f\"Executing {call_repr(flow.fn, *args, **kwargs)}\")\n                else:\n                    logger.debug(\n                        \"Beginning execution...\", extra={\"state_message\": True}\n                    )\n\n                flow_call = create_call(flow.fn, *args, **kwargs)\n\n                # This check for a parent call is needed for cases where the engine\n                # was entered directly during testing\n                parent_call = get_current_call()\n\n                if parent_call and (\n                    not parent_flow_run_context\n                    or (\n                        getattr(parent_flow_run_context, \"flow\", None)\n                        and parent_flow_run_context.flow.isasync == flow.isasync\n                    )\n                ):\n                    from_async.call_soon_in_waiting_thread(\n                        flow_call,\n                        thread=user_thread,\n                        timeout=flow.timeout_seconds,\n                    )\n                else:\n                    from_async.call_soon_in_new_thread(\n                        flow_call, timeout=flow.timeout_seconds\n                    )\n\n                result = await flow_call.aresult()\n\n                waited_for_task_runs = await wait_for_task_runs_and_report_crashes(\n                    flow_run_context.task_run_futures, client=client\n                )\n        except PausedRun as exc:\n            # could get raised either via utility or by returning Paused from a task run\n            # if a task run pauses, we set its state as the flow's state\n            # to preserve reschedule and timeout behavior\n            paused_flow_run = await client.read_flow_run(flow_run.id)\n            if paused_flow_run.state.is_running():\n                state = await propose_state(\n                    client,\n                    state=exc.state,\n                    flow_run_id=flow_run.id,\n                )\n\n                return state\n            paused_flow_run_state = paused_flow_run.state\n            return paused_flow_run_state\n        except CancelledError as exc:\n            if not flow_call.timedout():\n                # If the flow call was not cancelled by us; this is a crash\n                raise\n            # Construct a new exception as `TimeoutError`\n            original = exc\n            exc = TimeoutError()\n            exc.__cause__ = original\n            logger.exception(\"Encountered exception during execution:\")\n            terminal_state = await exception_to_failed_state(\n                exc,\n                message=f\"Flow run exceeded timeout of {flow.timeout_seconds} seconds\",\n                result_factory=flow_run_context.result_factory,\n                name=\"TimedOut\",\n            )\n        except Exception:\n            # Generic exception in user code\n            logger.exception(\"Encountered exception during execution:\")\n            terminal_state = await exception_to_failed_state(\n                message=\"Flow run encountered an exception.\",\n                result_factory=flow_run_context.result_factory,\n            )\n        else:\n            if result is None:\n                # All tasks and subflows are reference tasks if there is no return value\n                # If there are no tasks, use `None` instead of an empty iterable\n                result = (\n                    flow_run_context.task_run_futures\n                    + flow_run_context.task_run_states\n                    + flow_run_context.flow_run_states\n                ) or None\n\n            terminal_state = await return_value_to_state(\n                await resolve_futures_to_states(result),\n                result_factory=flow_run_context.result_factory,\n            )\n\n        if not waited_for_task_runs:\n            # An exception occurred that prevented us from waiting for task runs to\n            # complete. Ensure that we wait for them before proposing a final state\n            # for the flow run.\n            await wait_for_task_runs_and_report_crashes(\n                flow_run_context.task_run_futures, client=client\n            )\n\n        # Before setting the flow run state, store state.data using\n        # block storage and send the resulting data document to the Prefect API instead.\n        # This prevents the pickled return value of flow runs\n        # from being sent to the Prefect API and stored in the Prefect database.\n        # state.data is left as is, otherwise we would have to load\n        # the data from block storage again after storing.\n        state = await propose_state(\n            client,\n            state=terminal_state,\n            flow_run_id=flow_run.id,\n        )\n\n        await _run_flow_hooks(flow=flow, flow_run=flow_run, state=state)\n\n        if state.type != terminal_state.type and PREFECT_DEBUG_MODE:\n            logger.debug(\n                (\n                    f\"Received new state {state} when proposing final state\"\n                    f\" {terminal_state}\"\n                ),\n                extra={\"send_to_api\": False},\n            )\n\n        if not state.is_final() and not state.is_paused():\n            logger.info(\n                (\n                    f\"Received non-final state {state.name!r} when proposing final\"\n                    f\" state {terminal_state.name!r} and will attempt to run again...\"\n                ),\n            )\n            # Attempt to enter a running state again\n            state = await propose_state(client, Running(), flow_run_id=flow_run.id)\n\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.orchestrate_task_run","title":"<code>orchestrate_task_run</code>  <code>async</code>","text":"<p>Execute a task run</p> <p>This function should be submitted to a task runner. We must construct the context here instead of receiving it already populated since we may be in a new environment.</p> <p>Proposes a RUNNING state, then - if accepted, the task user function will be run - if rejected, the received state will be returned</p> <p>When the user function is run, the result will be used to determine a final state - if an exception is encountered, it is trapped and stored in a FAILED state - otherwise, <code>return_value_to_state</code> is used to determine the state</p> <p>If the final state is COMPLETED, we generate a cache key as specified by the task</p> <p>The final state is then proposed - if accepted, this is the final state and will be returned - if rejected and a new final state is provided, it will be returned - if rejected and a non-final state is provided, we will attempt to enter a RUNNING     state again</p> <p>Returns:</p> Type Description <code>State</code> <p>The final state of the run</p> Source code in <code>prefect/engine.py</code> <pre><code>async def orchestrate_task_run(\n    task: Task,\n    task_run: TaskRun,\n    parameters: Dict[str, Any],\n    wait_for: Optional[Iterable[PrefectFuture]],\n    result_factory: ResultFactory,\n    log_prints: bool,\n    interruptible: bool,\n    client: PrefectClient,\n) -&gt; State:\n    \"\"\"\n    Execute a task run\n\n    This function should be submitted to a task runner. We must construct the context\n    here instead of receiving it already populated since we may be in a new environment.\n\n    Proposes a RUNNING state, then\n    - if accepted, the task user function will be run\n    - if rejected, the received state will be returned\n\n    When the user function is run, the result will be used to determine a final state\n    - if an exception is encountered, it is trapped and stored in a FAILED state\n    - otherwise, `return_value_to_state` is used to determine the state\n\n    If the final state is COMPLETED, we generate a cache key as specified by the task\n\n    The final state is then proposed\n    - if accepted, this is the final state and will be returned\n    - if rejected and a new final state is provided, it will be returned\n    - if rejected and a non-final state is provided, we will attempt to enter a RUNNING\n        state again\n\n    Returns:\n        The final state of the run\n    \"\"\"\n    flow_run_context = prefect.context.FlowRunContext.get()\n    if flow_run_context:\n        flow_run = flow_run_context.flow_run\n    else:\n        flow_run = await client.read_flow_run(task_run.flow_run_id)\n    logger = task_run_logger(task_run, task=task, flow_run=flow_run)\n\n    partial_task_run_context = TaskRunContext.construct(\n        task_run=task_run,\n        task=task,\n        client=client,\n        result_factory=result_factory,\n        log_prints=log_prints,\n    )\n    task_introspection_start_time = time.perf_counter()\n    try:\n        # Resolve futures in parameters into data\n        resolved_parameters = await resolve_inputs(parameters)\n        # Resolve futures in any non-data dependencies to ensure they are ready\n        await resolve_inputs({\"wait_for\": wait_for}, return_data=False)\n    except UpstreamTaskError as upstream_exc:\n        return await propose_state(\n            client,\n            Pending(name=\"NotReady\", message=str(upstream_exc)),\n            task_run_id=task_run.id,\n            # if orchestrating a run already in a pending state, force orchestration to\n            # update the state name\n            force=task_run.state.is_pending(),\n        )\n    task_introspection_end_time = time.perf_counter()\n\n    introspection_time = round(\n        task_introspection_end_time - task_introspection_start_time, 3\n    )\n    threshold = PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD.value()\n    if threshold and introspection_time &gt; threshold:\n        logger.warning(\n            f\"Task parameter introspection took {introspection_time} seconds \"\n            f\", exceeding `PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD` of {threshold}. \"\n            \"Try wrapping large task parameters with \"\n            \"`prefect.utilities.annotations.quote` for increased performance, \"\n            \"e.g. `my_task(quote(param))`. To disable this message set \"\n            \"`PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD=0`.\"\n        )\n\n    # Generate the cache key to attach to proposed states\n    # The cache key uses a TaskRunContext that does not include a `timeout_context``\n\n    task_run_context = TaskRunContext(\n        **partial_task_run_context.dict(), parameters=resolved_parameters\n    )\n\n    cache_key = (\n        task.cache_key_fn(\n            task_run_context,\n            resolved_parameters,\n        )\n        if task.cache_key_fn\n        else None\n    )\n\n    # Ignore the cached results for a cache key, default = false\n    # Setting on task level overrules the Prefect setting (env var)\n    refresh_cache = (\n        task.refresh_cache\n        if task.refresh_cache is not None\n        else PREFECT_TASKS_REFRESH_CACHE.value()\n    )\n\n    # Emit an event to capture that the task run was in the `PENDING` state.\n    last_event = emit_task_run_state_change_event(\n        task_run=task_run, initial_state=None, validated_state=task_run.state\n    )\n    last_state = (\n        Pending()\n        if flow_run_context and flow_run_context.autonomous_task_run\n        else task_run.state\n    )\n\n    # Completed states with persisted results should have result data. If it's missing,\n    # this could be a manual state transition, so we should use the Unknown result type\n    # to represent that we know we don't know the result.\n    if (\n        last_state\n        and last_state.is_completed()\n        and result_factory.persist_result\n        and not last_state.data\n    ):\n        state = await propose_state(\n            client,\n            state=Completed(data=await UnknownResult.create()),\n            task_run_id=task_run.id,\n            force=True,\n        )\n\n    # Transition from `PENDING` -&gt; `RUNNING`\n    try:\n        state = await propose_state(\n            client,\n            Running(\n                state_details=StateDetails(\n                    cache_key=cache_key, refresh_cache=refresh_cache\n                )\n            ),\n            task_run_id=task_run.id,\n        )\n    except Pause as exc:\n        # We shouldn't get a pause signal without a state, but if this happens,\n        # just use a Paused state to assume an in-process pause.\n        state = exc.state if exc.state else Paused()\n\n        # If a flow submits tasks and then pauses, we may reach this point due\n        # to concurrency timing because the tasks will try to transition after\n        # the flow run has paused. Orchestration will send back a Paused state\n        # for the task runs.\n        if state.state_details.pause_reschedule:\n            # If we're being asked to pause and reschedule, we should exit the\n            # task and expect to be resumed later.\n            raise\n\n    if state.is_paused():\n        BACKOFF_MAX = 10  # Seconds\n        backoff_count = 0\n\n        async def tick():\n            nonlocal backoff_count\n            if backoff_count &lt; BACKOFF_MAX:\n                backoff_count += 1\n            interval = 1 + backoff_count + random.random() * backoff_count\n            await anyio.sleep(interval)\n\n        # Enter a loop to wait for the task run to be resumed, i.e.\n        # become Pending, and then propose a Running state again.\n        while True:\n            await tick()\n\n            # Propose a Running state again. We do this instead of reading the\n            # task run because if the flow run times out, this lets\n            # orchestration fail the task run.\n            try:\n                state = await propose_state(\n                    client,\n                    Running(\n                        state_details=StateDetails(\n                            cache_key=cache_key, refresh_cache=refresh_cache\n                        )\n                    ),\n                    task_run_id=task_run.id,\n                )\n            except Pause as exc:\n                if not exc.state:\n                    continue\n\n                if exc.state.state_details.pause_reschedule:\n                    # If the pause state includes pause_reschedule, we should exit the\n                    # task and expect to be resumed later. We've already checked for this\n                    # above, but we check again here in case the state changed; e.g. the\n                    # flow run suspended.\n                    raise\n                else:\n                    # Propose a Running state again.\n                    continue\n            else:\n                break\n\n    # Emit an event to capture the result of proposing a `RUNNING` state.\n    last_event = emit_task_run_state_change_event(\n        task_run=task_run,\n        initial_state=last_state,\n        validated_state=state,\n        follows=last_event,\n    )\n    last_state = state\n\n    # flag to ensure we only update the task run name once\n    run_name_set = False\n\n    # Only run the task if we enter a `RUNNING` state\n    while state.is_running():\n        # Retrieve the latest metadata for the task run context\n        task_run = await client.read_task_run(task_run.id)\n\n        with task_run_context.copy(\n            update={\"task_run\": task_run, \"start_time\": pendulum.now(\"UTC\")}\n        ):\n            try:\n                args, kwargs = parameters_to_args_kwargs(task.fn, resolved_parameters)\n                # update task run name\n                if not run_name_set and task.task_run_name:\n                    task_run_name = _resolve_custom_task_run_name(\n                        task=task, parameters=resolved_parameters\n                    )\n                    await client.set_task_run_name(\n                        task_run_id=task_run.id, name=task_run_name\n                    )\n                    logger.extra[\"task_run_name\"] = task_run_name\n                    logger.debug(\n                        f\"Renamed task run {task_run.name!r} to {task_run_name!r}\"\n                    )\n                    task_run.name = task_run_name\n                    run_name_set = True\n\n                if PREFECT_DEBUG_MODE.value():\n                    logger.debug(f\"Executing {call_repr(task.fn, *args, **kwargs)}\")\n                else:\n                    logger.debug(\n                        \"Beginning execution...\", extra={\"state_message\": True}\n                    )\n\n                call = from_async.call_soon_in_new_thread(\n                    create_call(task.fn, *args, **kwargs), timeout=task.timeout_seconds\n                )\n                result = await call.aresult()\n\n            except (CancelledError, asyncio.CancelledError) as exc:\n                if not call.timedout():\n                    # If the task call was not cancelled by us; this is a crash\n                    raise\n                # Construct a new exception as `TimeoutError`\n                original = exc\n                exc = TimeoutError()\n                exc.__cause__ = original\n                logger.exception(\"Encountered exception during execution:\")\n                terminal_state = await exception_to_failed_state(\n                    exc,\n                    message=(\n                        f\"Task run exceeded timeout of {task.timeout_seconds} seconds\"\n                    ),\n                    result_factory=task_run_context.result_factory,\n                    name=\"TimedOut\",\n                )\n            except Exception as exc:\n                logger.exception(\"Encountered exception during execution:\")\n                terminal_state = await exception_to_failed_state(\n                    exc,\n                    message=\"Task run encountered an exception\",\n                    result_factory=task_run_context.result_factory,\n                )\n            else:\n                terminal_state = await return_value_to_state(\n                    result,\n                    result_factory=task_run_context.result_factory,\n                )\n\n                # for COMPLETED tasks, add the cache key and expiration\n                if terminal_state.is_completed():\n                    terminal_state.state_details.cache_expiration = (\n                        (pendulum.now(\"utc\") + task.cache_expiration)\n                        if task.cache_expiration\n                        else None\n                    )\n                    terminal_state.state_details.cache_key = cache_key\n\n            if terminal_state.is_failed():\n                # Defer to user to decide whether failure is retriable\n                terminal_state.state_details.retriable = (\n                    await _check_task_failure_retriable(task, task_run, terminal_state)\n                )\n            state = await propose_state(client, terminal_state, task_run_id=task_run.id)\n            last_event = emit_task_run_state_change_event(\n                task_run=task_run,\n                initial_state=last_state,\n                validated_state=state,\n                follows=last_event,\n            )\n            last_state = state\n\n            await _run_task_hooks(\n                task=task,\n                task_run=task_run,\n                state=state,\n            )\n\n            if state.type != terminal_state.type and PREFECT_DEBUG_MODE:\n                logger.debug(\n                    (\n                        f\"Received new state {state} when proposing final state\"\n                        f\" {terminal_state}\"\n                    ),\n                    extra={\"send_to_api\": False},\n                )\n\n            if not state.is_final() and not state.is_paused():\n                logger.info(\n                    (\n                        f\"Received non-final state {state.name!r} when proposing final\"\n                        f\" state {terminal_state.name!r} and will attempt to run\"\n                        \" again...\"\n                    ),\n                )\n                # Attempt to enter a running state again\n                state = await propose_state(client, Running(), task_run_id=task_run.id)\n                last_event = emit_task_run_state_change_event(\n                    task_run=task_run,\n                    initial_state=last_state,\n                    validated_state=state,\n                    follows=last_event,\n                )\n                last_state = state\n\n    # If debugging, use the more complete `repr` than the usual `str` description\n    display_state = repr(state) if PREFECT_DEBUG_MODE else str(state)\n\n    logger.log(\n        level=logging.INFO if state.is_completed() else logging.ERROR,\n        msg=f\"Finished in state {display_state}\",\n    )\n    return state\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.pause_flow_run","title":"<code>pause_flow_run</code>  <code>async</code>","text":"<p>Pauses the current flow run by blocking execution until resumed.</p> <p>When called within a flow run, execution will block and no downstream tasks will run until the flow is resumed. Task runs that have already started will continue running. A timeout parameter can be passed that will fail the flow run if it has not been resumed within the specified time.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>a flow run id. If supplied, this function will attempt to pause the specified flow run outside of the flow run process. When paused, the flow run will continue execution until the NEXT task is orchestrated, at which point the flow will exit. Any tasks that have already started will run until completion. When resumed, the flow run will be rescheduled to finish execution. In order pause a flow run in this way, the flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <code>None</code> <code>timeout</code> <code>int</code> <p>the number of seconds to wait for the flow to be resumed before failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds any configured flow-level timeout, the flow might fail even after resuming.</p> <code>3600</code> <code>poll_interval</code> <code>int</code> <p>The number of seconds between checking whether the flow has been resumed. Defaults to 10 seconds.</p> <code>10</code> <code>reschedule</code> <code>bool</code> <p>Flag that will reschedule the flow run if resumed. Instead of blocking execution, the flow will gracefully exit (with no result returned) instead. To use this flag, a flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <code>False</code> <code>key</code> <code>str</code> <p>An optional key to prevent calling pauses more than once. This defaults to the number of pauses observed by the flow so far, and prevents pauses that use the \"reschedule\" option from running the same pause twice. A custom key can be supplied for custom pausing behavior.</p> <code>None</code> <code>wait_for_input</code> <code>Optional[Type[T]]</code> <p>a subclass of <code>RunInput</code> or any type supported by Pydantic. If provided when the flow pauses, the flow will wait for the input to be provided before resuming. If the flow is resumed without providing the input, the flow will fail. If the flow is resumed with the input, the flow will resume and the input will be loaded and returned from this function.</p> <code>None</code> <pre><code>@task\ndef task_one():\n    for i in range(3):\n        sleep(1)\n\n@flow\ndef my_flow():\n    terminal_state = task_one.submit(return_state=True)\n    if terminal_state.type == StateType.COMPLETED:\n        print(\"Task one succeeded! Pausing flow run..\")\n        pause_flow_run(timeout=2)\n    else:\n        print(\"Task one failed. Skipping pause flow run..\")\n</code></pre> Source code in <code>prefect/engine.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"flow_run_id\", start_date=\"Dec 2023\", help=\"Use `suspend_flow_run` instead.\"\n)\n@deprecated_parameter(\n    \"reschedule\",\n    start_date=\"Dec 2023\",\n    when=lambda p: p is True,\n    help=\"Use `suspend_flow_run` instead.\",\n)\n@experimental_parameter(\n    \"wait_for_input\", group=\"flow_run_input\", when=lambda y: y is not None\n)\nasync def pause_flow_run(\n    wait_for_input: Optional[Type[T]] = None,\n    flow_run_id: UUID = None,\n    timeout: int = 3600,\n    poll_interval: int = 10,\n    reschedule: bool = False,\n    key: str = None,\n) -&gt; Optional[T]:\n    \"\"\"\n    Pauses the current flow run by blocking execution until resumed.\n\n    When called within a flow run, execution will block and no downstream tasks will\n    run until the flow is resumed. Task runs that have already started will continue\n    running. A timeout parameter can be passed that will fail the flow run if it has not\n    been resumed within the specified time.\n\n    Args:\n        flow_run_id: a flow run id. If supplied, this function will attempt to pause\n            the specified flow run outside of the flow run process. When paused, the\n            flow run will continue execution until the NEXT task is orchestrated, at\n            which point the flow will exit. Any tasks that have already started will\n            run until completion. When resumed, the flow run will be rescheduled to\n            finish execution. In order pause a flow run in this way, the flow needs to\n            have an associated deployment and results need to be configured with the\n            `persist_results` option.\n        timeout: the number of seconds to wait for the flow to be resumed before\n            failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds\n            any configured flow-level timeout, the flow might fail even after resuming.\n        poll_interval: The number of seconds between checking whether the flow has been\n            resumed. Defaults to 10 seconds.\n        reschedule: Flag that will reschedule the flow run if resumed. Instead of\n            blocking execution, the flow will gracefully exit (with no result returned)\n            instead. To use this flag, a flow needs to have an associated deployment and\n            results need to be configured with the `persist_results` option.\n        key: An optional key to prevent calling pauses more than once. This defaults to\n            the number of pauses observed by the flow so far, and prevents pauses that\n            use the \"reschedule\" option from running the same pause twice. A custom key\n            can be supplied for custom pausing behavior.\n        wait_for_input: a subclass of `RunInput` or any type supported by\n            Pydantic. If provided when the flow pauses, the flow will wait for the\n            input to be provided before resuming. If the flow is resumed without\n            providing the input, the flow will fail. If the flow is resumed with the\n            input, the flow will resume and the input will be loaded and returned\n            from this function.\n\n    Example:\n    ```python\n    @task\n    def task_one():\n        for i in range(3):\n            sleep(1)\n\n    @flow\n    def my_flow():\n        terminal_state = task_one.submit(return_state=True)\n        if terminal_state.type == StateType.COMPLETED:\n            print(\"Task one succeeded! Pausing flow run..\")\n            pause_flow_run(timeout=2)\n        else:\n            print(\"Task one failed. Skipping pause flow run..\")\n    ```\n\n    \"\"\"\n    if flow_run_id:\n        if wait_for_input is not None:\n            raise RuntimeError(\"Cannot wait for input when pausing out of process.\")\n\n        return await _out_of_process_pause(\n            flow_run_id=flow_run_id,\n            timeout=timeout,\n            reschedule=reschedule,\n            key=key,\n        )\n    else:\n        return await _in_process_pause(\n            timeout=timeout,\n            poll_interval=poll_interval,\n            reschedule=reschedule,\n            key=key,\n            wait_for_input=wait_for_input,\n        )\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.report_flow_run_crashes","title":"<code>report_flow_run_crashes</code>  <code>async</code>","text":"<p>Detect flow run crashes during this context and update the run to a proper final state.</p> <p>This context must reraise the exception to properly exit the run.</p> Source code in <code>prefect/engine.py</code> <pre><code>@asynccontextmanager\nasync def report_flow_run_crashes(flow_run: FlowRun, client: PrefectClient, flow: Flow):\n    \"\"\"\n    Detect flow run crashes during this context and update the run to a proper final\n    state.\n\n    This context _must_ reraise the exception to properly exit the run.\n    \"\"\"\n    try:\n        with collapse_excgroups():\n            yield\n    except (Abort, Pause):\n        # Do not capture internal signals as crashes\n        raise\n    except BaseException as exc:\n        state = await exception_to_crashed_state(exc)\n        logger = flow_run_logger(flow_run)\n        with anyio.CancelScope(shield=True):\n            logger.error(f\"Crash detected! {state.message}\")\n            logger.debug(\"Crash details:\", exc_info=exc)\n            flow_run_state = await propose_state(client, state, flow_run_id=flow_run.id)\n            engine_logger.debug(\n                f\"Reported crashed flow run {flow_run.name!r} successfully!\"\n            )\n\n            # Only `on_crashed` and `on_cancellation` flow run state change hooks can be called here.\n            # We call the hooks after the state change proposal to `CRASHED` is validated\n            # or rejected (if it is in a `CANCELLING` state).\n            await _run_flow_hooks(\n                flow=flow,\n                flow_run=flow_run,\n                state=flow_run_state,\n            )\n\n        # Reraise the exception\n        raise\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.report_task_run_crashes","title":"<code>report_task_run_crashes</code>  <code>async</code>","text":"<p>Detect task run crashes during this context and update the run to a proper final state.</p> <p>This context must reraise the exception to properly exit the run.</p> Source code in <code>prefect/engine.py</code> <pre><code>@asynccontextmanager\nasync def report_task_run_crashes(task_run: TaskRun, client: PrefectClient):\n    \"\"\"\n    Detect task run crashes during this context and update the run to a proper final\n    state.\n\n    This context _must_ reraise the exception to properly exit the run.\n    \"\"\"\n    try:\n        with collapse_excgroups():\n            yield\n    except (Abort, Pause):\n        # Do not capture internal signals as crashes\n        raise\n    except BaseException as exc:\n        state = await exception_to_crashed_state(exc)\n        logger = task_run_logger(task_run)\n        with anyio.CancelScope(shield=True):\n            logger.error(f\"Crash detected! {state.message}\")\n            logger.debug(\"Crash details:\", exc_info=exc)\n            await client.set_task_run_state(\n                state=state,\n                task_run_id=task_run.id,\n                force=True,\n            )\n            engine_logger.debug(\n                f\"Reported crashed task run {task_run.name!r} successfully!\"\n            )\n\n        # Reraise the exception\n        raise\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resumes a paused flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <p>the flow_run_id to resume</p> required <code>run_input</code> <code>Optional[Dict]</code> <p>a dictionary of inputs to provide to the flow run.</p> <code>None</code> Source code in <code>prefect/engine.py</code> <pre><code>@deprecated_callable(\n    start_date=\"Jun 2024\",\n    help=\"Will be moved in Prefect 3 to prefect.flow_runs:resume_flow_run\",\n)\n@sync_compatible\nasync def resume_flow_run(flow_run_id, run_input: Optional[Dict] = None):\n    \"\"\"\n    Resumes a paused flow.\n\n    Args:\n        flow_run_id: the flow_run_id to resume\n        run_input: a dictionary of inputs to provide to the flow run.\n    \"\"\"\n    client = get_client()\n    async with client:\n        flow_run = await client.read_flow_run(flow_run_id)\n\n        if not flow_run.state.is_paused():\n            raise NotPausedError(\"Cannot resume a run that isn't paused!\")\n\n        response = await client.resume_flow_run(flow_run_id, run_input=run_input)\n\n    if response.status == SetStateStatus.REJECT:\n        if response.state.type == StateType.FAILED:\n            raise FlowPauseTimeout(\"Flow run can no longer be resumed.\")\n        else:\n            raise RuntimeError(f\"Cannot resume this run: {response.details.reason}\")\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.retrieve_flow_then_begin_flow_run","title":"<code>retrieve_flow_then_begin_flow_run</code>  <code>async</code>","text":"<p>Async entrypoint for flow runs that have been submitted for execution by an agent</p> <ul> <li>Retrieves the deployment information</li> <li>Loads the flow object using deployment information</li> <li>Updates the flow run version</li> </ul> Source code in <code>prefect/engine.py</code> <pre><code>@inject_client\nasync def retrieve_flow_then_begin_flow_run(\n    flow_run_id: UUID,\n    client: PrefectClient,\n    user_thread: threading.Thread,\n) -&gt; State:\n    \"\"\"\n    Async entrypoint for flow runs that have been submitted for execution by an agent\n\n    - Retrieves the deployment information\n    - Loads the flow object using deployment information\n    - Updates the flow run version\n    \"\"\"\n    flow_run = await client.read_flow_run(flow_run_id)\n\n    entrypoint = os.environ.get(\"PREFECT__FLOW_ENTRYPOINT\")\n\n    try:\n        flow = (\n            # We do not want to use a placeholder flow at runtime\n            load_flow_from_entrypoint(entrypoint, use_placeholder_flow=False)\n            if entrypoint\n            else await load_flow_from_flow_run(\n                flow_run, client=client, use_placeholder_flow=False\n            )\n        )\n    except Exception:\n        message = (\n            \"Flow could not be retrieved from\"\n            f\" {'entrypoint' if entrypoint else 'deployment'}.\"\n        )\n        flow_run_logger(flow_run).exception(message)\n        state = await exception_to_failed_state(message=message)\n        await client.set_flow_run_state(\n            state=state, flow_run_id=flow_run_id, force=True\n        )\n        return state\n\n    # Update the flow run policy defaults to match settings on the flow\n    # Note: Mutating the flow run object prevents us from performing another read\n    #       operation if these properties are used by the client downstream\n    if flow_run.empirical_policy.retry_delay is None:\n        flow_run.empirical_policy.retry_delay = flow.retry_delay_seconds\n\n    if flow_run.empirical_policy.retries is None:\n        flow_run.empirical_policy.retries = flow.retries\n\n    await client.update_flow_run(\n        flow_run_id=flow_run_id,\n        flow_version=flow.version,\n        empirical_policy=flow_run.empirical_policy,\n    )\n\n    if flow.should_validate_parameters:\n        failed_state = None\n        try:\n            parameters = flow.validate_parameters(flow_run.parameters)\n        except Exception:\n            message = \"Validation of flow parameters failed with error: \"\n            flow_run_logger(flow_run).exception(message)\n            failed_state = await exception_to_failed_state(message=message)\n\n        if failed_state is not None:\n            await propose_state(\n                client,\n                state=failed_state,\n                flow_run_id=flow_run_id,\n            )\n            return failed_state\n    else:\n        parameters = flow_run.parameters\n\n    # Ensure default values are populated\n    parameters = {**get_parameter_defaults(flow.fn), **parameters}\n\n    return await begin_flow_run(\n        flow=flow,\n        flow_run=flow_run,\n        parameters=parameters,\n        client=client,\n        user_thread=user_thread,\n    )\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/engine/#prefect.engine.suspend_flow_run","title":"<code>suspend_flow_run</code>  <code>async</code>","text":"<p>Suspends a flow run by stopping code execution until resumed.</p> <p>When suspended, the flow run will continue execution until the NEXT task is orchestrated, at which point the flow will exit. Any tasks that have already started will run until completion. When resumed, the flow run will be rescheduled to finish execution. In order suspend a flow run in this way, the flow needs to have an associated deployment and results need to be configured with the <code>persist_results</code> option.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>Optional[UUID]</code> <p>a flow run id. If supplied, this function will attempt to suspend the specified flow run. If not supplied will attempt to suspend the current flow run.</p> <code>None</code> <code>timeout</code> <code>Optional[int]</code> <p>the number of seconds to wait for the flow to be resumed before failing. Defaults to 1 hour (3600 seconds). If the pause timeout exceeds any configured flow-level timeout, the flow might fail even after resuming.</p> <code>3600</code> <code>key</code> <code>Optional[str]</code> <p>An optional key to prevent calling suspend more than once. This defaults to a random string and prevents suspends from running the same suspend twice. A custom key can be supplied for custom suspending behavior.</p> <code>None</code> <code>wait_for_input</code> <code>Optional[Type[T]]</code> <p>a subclass of <code>RunInput</code> or any type supported by Pydantic. If provided when the flow suspends, the flow will remain suspended until receiving the input before resuming. If the flow is resumed without providing the input, the flow will fail. If the flow is resumed with the input, the flow will resume and the input will be loaded and returned from this function.</p> <code>None</code> Source code in <code>prefect/engine.py</code> <pre><code>@sync_compatible\n@inject_client\n@experimental_parameter(\n    \"wait_for_input\", group=\"flow_run_input\", when=lambda y: y is not None\n)\nasync def suspend_flow_run(\n    wait_for_input: Optional[Type[T]] = None,\n    flow_run_id: Optional[UUID] = None,\n    timeout: Optional[int] = 3600,\n    key: Optional[str] = None,\n    client: PrefectClient = None,\n) -&gt; Optional[T]:\n    \"\"\"\n    Suspends a flow run by stopping code execution until resumed.\n\n    When suspended, the flow run will continue execution until the NEXT task is\n    orchestrated, at which point the flow will exit. Any tasks that have\n    already started will run until completion. When resumed, the flow run will\n    be rescheduled to finish execution. In order suspend a flow run in this\n    way, the flow needs to have an associated deployment and results need to be\n    configured with the `persist_results` option.\n\n    Args:\n        flow_run_id: a flow run id. If supplied, this function will attempt to\n            suspend the specified flow run. If not supplied will attempt to\n            suspend the current flow run.\n        timeout: the number of seconds to wait for the flow to be resumed before\n            failing. Defaults to 1 hour (3600 seconds). If the pause timeout\n            exceeds any configured flow-level timeout, the flow might fail even\n            after resuming.\n        key: An optional key to prevent calling suspend more than once. This\n            defaults to a random string and prevents suspends from running the\n            same suspend twice. A custom key can be supplied for custom\n            suspending behavior.\n        wait_for_input: a subclass of `RunInput` or any type supported by\n            Pydantic. If provided when the flow suspends, the flow will remain\n            suspended until receiving the input before resuming. If the flow is\n            resumed without providing the input, the flow will fail. If the flow is\n            resumed with the input, the flow will resume and the input will be\n            loaded and returned from this function.\n    \"\"\"\n    context = FlowRunContext.get()\n\n    if flow_run_id is None:\n        if TaskRunContext.get():\n            raise RuntimeError(\"Cannot suspend task runs.\")\n\n        if context is None or context.flow_run is None:\n            raise RuntimeError(\n                \"Flow runs can only be suspended from within a flow run.\"\n            )\n\n        logger = get_run_logger(context=context)\n        logger.info(\n            \"Suspending flow run, execution will be rescheduled when this flow run is\"\n            \" resumed.\"\n        )\n        flow_run_id = context.flow_run.id\n        suspending_current_flow_run = True\n        pause_counter = _observed_flow_pauses(context)\n        pause_key = key or str(pause_counter)\n    else:\n        # Since we're suspending another flow run we need to generate a pause\n        # key that won't conflict with whatever suspends/pauses that flow may\n        # have. Since this method won't be called during that flow run it's\n        # okay that this is non-deterministic.\n        suspending_current_flow_run = False\n        pause_key = key or str(uuid4())\n\n    proposed_state = Suspended(timeout_seconds=timeout, pause_key=pause_key)\n\n    if wait_for_input:\n        wait_for_input = run_input_subclass_from_type(wait_for_input)\n        run_input_keyset = keyset_from_paused_state(proposed_state)\n        proposed_state.state_details.run_input_keyset = run_input_keyset\n\n    try:\n        state = await propose_state(\n            client=client,\n            state=proposed_state,\n            flow_run_id=flow_run_id,\n        )\n    except Abort as exc:\n        # Aborted requests mean the suspension is not allowed\n        raise RuntimeError(f\"Flow run cannot be suspended: {exc}\")\n\n    if state.is_running():\n        # The orchestrator rejected the suspended state which means that this\n        # suspend has happened before and the flow run has been resumed.\n        if wait_for_input:\n            # The flow run wanted input, so we need to load it and return it\n            # to the user.\n            return await wait_for_input.load(run_input_keyset)\n        return\n\n    if not state.is_paused():\n        # If we receive anything but a PAUSED state, we are unable to continue\n        raise RuntimeError(\n            f\"Flow run cannot be suspended. Received unexpected state from API: {state}\"\n        )\n\n    if wait_for_input:\n        await wait_for_input.save(run_input_keyset)\n\n    if suspending_current_flow_run:\n        # Exit this process so the run can be resubmitted later\n        raise Pause()\n</code></pre>","tags":["Python API","flow runs","orchestration","engine","context"]},{"location":"api-ref/prefect/events/","title":"prefect.events","text":"","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events","title":"<code>prefect.events</code>","text":"","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.TriggerTypes","title":"<code>TriggerTypes: TypeAlias = Union[EventTrigger, MetricTrigger, CompoundTrigger, SequenceTrigger]</code>  <code>module-attribute</code>","text":"<p>The union of all concrete trigger types that a user may actually create</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Action","title":"<code>Action</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>An Action that may be performed when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class Action(PrefectBaseModel, abc.ABC):\n    \"\"\"An Action that may be performed when an Automation is triggered\"\"\"\n\n    type: str\n\n    def describe_for_cli(self) -&gt; str:\n        \"\"\"A human-readable description of the action\"\"\"\n        return self.type.replace(\"-\", \" \").capitalize()\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Action.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>A human-readable description of the action</p> Source code in <code>prefect/events/actions.py</code> <pre><code>def describe_for_cli(self) -&gt; str:\n    \"\"\"A human-readable description of the action\"\"\"\n    return self.type.replace(\"-\", \" \").capitalize()\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.AutomationCore","title":"<code>AutomationCore</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines an action a user wants to take when a certain number of events do or don't happen to the matching resources</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class AutomationCore(PrefectBaseModel, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"Defines an action a user wants to take when a certain number of events\n    do or don't happen to the matching resources\"\"\"\n\n    name: str = Field(..., description=\"The name of this automation\")\n    description: str = Field(\"\", description=\"A longer description of this automation\")\n\n    enabled: bool = Field(True, description=\"Whether this automation will be evaluated\")\n\n    trigger: TriggerTypes = Field(\n        ...,\n        description=(\n            \"The criteria for which events this Automation covers and how it will \"\n            \"respond to the presence or absence of those events\"\n        ),\n    )\n\n    actions: List[ActionTypes] = Field(\n        ...,\n        description=\"The actions to perform when this Automation triggers\",\n    )\n\n    actions_on_trigger: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a triggered state\",\n    )\n\n    actions_on_resolve: List[ActionTypes] = Field(\n        default_factory=list,\n        description=\"The actions to perform when an Automation goes into a resolving state\",\n    )\n\n    owner_resource: Optional[str] = Field(\n        default=None, description=\"The owning resource of this automation\"\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CallWebhook","title":"<code>CallWebhook</code>","text":"<p>               Bases: <code>Action</code></p> <p>Call a webhook when an Automation is triggered.</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class CallWebhook(Action):\n    \"\"\"Call a webhook when an Automation is triggered.\"\"\"\n\n    type: Literal[\"call-webhook\"] = \"call-webhook\"\n    block_document_id: UUID = Field(\n        description=\"The identifier of the webhook block to use\"\n    )\n    payload: str = Field(\n        default=\"\",\n        description=\"An optional templatable payload to send when calling the webhook.\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CancelFlowRun","title":"<code>CancelFlowRun</code>","text":"<p>               Bases: <code>Action</code></p> <p>Cancels a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class CancelFlowRun(Action):\n    \"\"\"Cancels a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"cancel-flow-run\"] = \"cancel-flow-run\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ChangeFlowRunState","title":"<code>ChangeFlowRunState</code>","text":"<p>               Bases: <code>Action</code></p> <p>Changes the state of a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ChangeFlowRunState(Action):\n    \"\"\"Changes the state of a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"change-flow-run-state\"] = \"change-flow-run-state\"\n\n    name: Optional[str] = Field(\n        None,\n        description=\"The name of the state to change the flow run to\",\n    )\n    state: StateType = Field(\n        ...,\n        description=\"The type of the state to change the flow run to\",\n    )\n    message: Optional[str] = Field(\n        None,\n        description=\"An optional message to associate with the state change\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompositeTrigger","title":"<code>CompositeTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Requires some number of triggers to have fired within the given time period.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompositeTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Requires some number of triggers to have fired within the given time period.\n    \"\"\"\n\n    type: Literal[\"compound\", \"sequence\"]\n    triggers: List[\"TriggerTypes\"]\n    within: Optional[timedelta]\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompoundTrigger","title":"<code>CompoundTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class CompoundTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    type: Literal[\"compound\"] = \"compound\"\n    require: Union[int, Literal[\"any\", \"all\"]]\n\n    @root_validator\n    def validate_require(cls, values: Dict[str, Any]) -&gt; Dict[str, Any]:\n        require = values.get(\"require\")\n\n        if isinstance(require, int):\n            if require &lt; 1:\n                raise ValueError(\"required must be at least 1\")\n            if require &gt; len(values[\"triggers\"]):\n                raise ValueError(\n                    \"required must be less than or equal to the number of triggers\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"{str(self.require).capitalize()} of:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.CompoundTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"{str(self.require).capitalize()} of:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeclareIncident","title":"<code>DeclareIncident</code>","text":"<p>               Bases: <code>Action</code></p> <p>Declares an incident for the triggering event.  Only available on Prefect Cloud</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class DeclareIncident(Action):\n    \"\"\"Declares an incident for the triggering event.  Only available on Prefect Cloud\"\"\"\n\n    type: Literal[\"declare-incident\"] = \"declare-incident\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentCompoundTrigger","title":"<code>DeploymentCompoundTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>CompoundTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentCompoundTrigger(BaseDeploymentTrigger, CompoundTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have\n    fired within the given time period\"\"\"\n\n    trigger_type = CompoundTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentEventTrigger","title":"<code>DeploymentEventTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>EventTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentEventTrigger(BaseDeploymentTrigger, EventTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    trigger_type = EventTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentMetricTrigger","title":"<code>DeploymentMetricTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>MetricTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentMetricTrigger(BaseDeploymentTrigger, MetricTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    trigger_type = MetricTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DeploymentSequenceTrigger","title":"<code>DeploymentSequenceTrigger</code>","text":"<p>               Bases: <code>BaseDeploymentTrigger</code>, <code>SequenceTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/deployment_triggers.py</code> <pre><code>class DeploymentSequenceTrigger(BaseDeploymentTrigger, SequenceTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    trigger_type = SequenceTrigger\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.DoNothing","title":"<code>DoNothing</code>","text":"<p>               Bases: <code>Action</code></p> <p>Do nothing when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class DoNothing(Action):\n    \"\"\"Do nothing when an Automation is triggered\"\"\"\n\n    type: Literal[\"do-nothing\"] = \"do-nothing\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event","title":"<code>Event</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>The client-side view of an event that has happened to a Resource</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class Event(PrefectBaseModel):\n    \"\"\"The client-side view of an event that has happened to a Resource\"\"\"\n\n    occurred: DateTimeTZ = Field(\n        default_factory=lambda: pendulum.now(\"UTC\"),\n        description=\"When the event happened from the sender's perspective\",\n    )\n    event: str = Field(\n        description=\"The name of the event that happened\",\n    )\n    resource: Resource = Field(\n        description=\"The primary Resource this event concerns\",\n    )\n    related: List[RelatedResource] = Field(\n        default_factory=list,\n        description=\"A list of additional Resources involved in this event\",\n    )\n    payload: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"An open-ended set of data describing what happened\",\n    )\n    id: UUID = Field(\n        default_factory=uuid4,\n        description=\"The client-provided identifier of this event\",\n    )\n    follows: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The ID of an event that is known to have occurred prior to this one. \"\n            \"If set, this may be used to establish a more precise ordering of causally-\"\n            \"related events when they occur close enough together in time that the \"\n            \"system may receive them out-of-order.\"\n        ),\n    )\n\n    @property\n    def involved_resources(self) -&gt; Sequence[Resource]:\n        return [self.resource] + list(self.related)\n\n    @property\n    def resource_in_role(self) -&gt; Mapping[str, RelatedResource]:\n        \"\"\"Returns a mapping of roles to the first related resource in that role\"\"\"\n        return {related.role: related for related in reversed(self.related)}\n\n    @property\n    def resources_in_role(self) -&gt; Mapping[str, Sequence[RelatedResource]]:\n        \"\"\"Returns a mapping of roles to related resources in that role\"\"\"\n        resources: Dict[str, List[RelatedResource]] = defaultdict(list)\n        for related in self.related:\n            resources[related.role].append(related)\n        return resources\n\n    @validator(\"related\")\n    def enforce_maximum_related_resources(cls, value: List[RelatedResource]):\n        if len(value) &gt; PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value():\n            raise ValueError(\n                \"The maximum number of related resources \"\n                f\"is {PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value()}\"\n            )\n\n        return value\n\n    def find_resource_label(self, label: str) -&gt; Optional[str]:\n        \"\"\"Finds the value of the given label in this event's resource or one of its\n        related resources.  If the label starts with `related:&lt;role&gt;:`, search for the\n        first matching label in a related resource with that role.\"\"\"\n        directive, _, related_label = label.rpartition(\":\")\n        directive, _, role = directive.partition(\":\")\n        if directive == \"related\":\n            for related in self.related:\n                if related.role == role:\n                    return related.get(related_label)\n        return self.resource.get(label)\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.resource_in_role","title":"<code>resource_in_role: Mapping[str, RelatedResource]</code>  <code>property</code>","text":"<p>Returns a mapping of roles to the first related resource in that role</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.resources_in_role","title":"<code>resources_in_role: Mapping[str, Sequence[RelatedResource]]</code>  <code>property</code>","text":"<p>Returns a mapping of roles to related resources in that role</p>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Event.find_resource_label","title":"<code>find_resource_label</code>","text":"<p>Finds the value of the given label in this event's resource or one of its related resources.  If the label starts with <code>related:&lt;role&gt;:</code>, search for the first matching label in a related resource with that role.</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>def find_resource_label(self, label: str) -&gt; Optional[str]:\n    \"\"\"Finds the value of the given label in this event's resource or one of its\n    related resources.  If the label starts with `related:&lt;role&gt;:`, search for the\n    first matching label in a related resource with that role.\"\"\"\n    directive, _, related_label = label.rpartition(\":\")\n    directive, _, role = directive.partition(\":\")\n    if directive == \"related\":\n        for related in self.related:\n            if related.role == role:\n                return related.get(related_label)\n    return self.resource.get(label)\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.EventTrigger","title":"<code>EventTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the presence or absence of events within a given period of time.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class EventTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the presence or absence of events within a given\n    period of time.\n    \"\"\"\n\n    type: Literal[\"event\"] = \"event\"\n\n    after: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) which must first been seen to fire this trigger.  If \"\n            \"empty, then fire this trigger immediately.  Events may include \"\n            \"trailing wildcards, like `prefect.flow-run.*`\"\n        ),\n    )\n    expect: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"The event(s) this trigger is expecting to see.  If empty, this \"\n            \"trigger will match any event.  Events may include trailing wildcards, \"\n            \"like `prefect.flow-run.*`\"\n        ),\n    )\n\n    for_each: Set[str] = Field(\n        default_factory=set,\n        description=(\n            \"Evaluate the trigger separately for each distinct value of these labels \"\n            \"on the resource.  By default, labels refer to the primary resource of the \"\n            \"triggering event.  You may also refer to labels from related \"\n            \"resources by specifying `related:&lt;role&gt;:&lt;label&gt;`.  This will use the \"\n            \"value of that label for the first related resource in that role.  For \"\n            'example, `\"for_each\": [\"related:flow:prefect.resource.id\"]` would '\n            \"evaluate the trigger for each flow.\"\n        ),\n    )\n    posture: Literal[Posture.Reactive, Posture.Proactive] = Field(  # type: ignore[valid-type]\n        Posture.Reactive,\n        description=(\n            \"The posture of this trigger, either Reactive or Proactive.  Reactive \"\n            \"triggers respond to the _presence_ of the expected events, while \"\n            \"Proactive triggers respond to the _absence_ of those expected events.\"\n        ),\n    )\n    threshold: int = Field(\n        1,\n        description=(\n            \"The number of events required for this trigger to fire (for \"\n            \"Reactive triggers), or the number of events expected (for Proactive \"\n            \"triggers)\"\n        ),\n    )\n    within: timedelta = Field(\n        timedelta(0),\n        minimum=0.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The time period over which the events must occur.  For Reactive triggers, \"\n            \"this may be as low as 0 seconds, but must be at least 10 seconds for \"\n            \"Proactive triggers\"\n        ),\n    )\n\n    @validator(\"within\")\n    def enforce_minimum_within(\n        cls, value: timedelta, values, config, field: ModelField\n    ):\n        return validate_trigger_within(value, field)\n\n    @root_validator(skip_on_failure=True)\n    def enforce_minimum_within_for_proactive_triggers(cls, values: Dict[str, Any]):\n        posture: Optional[Posture] = values.get(\"posture\")\n        within: Optional[timedelta] = values.get(\"within\")\n\n        if posture == Posture.Proactive:\n            if not within or within == timedelta(0):\n                values[\"within\"] = timedelta(seconds=10.0)\n            elif within &lt; timedelta(seconds=10.0):\n                raise ValueError(\n                    \"The minimum within for Proactive triggers is 10 seconds\"\n                )\n\n        return values\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        if self.posture == Posture.Reactive:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n        else:\n            return textwrap.indent(\n                \"\\n\".join(\n                    [\n                        f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                        f\"within {self.within}\",\n                    ],\n                ),\n                prefix=\"  \" * indent,\n            )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.EventTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    if self.posture == Posture.Reactive:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Reactive: expecting {self.threshold} of {self.expect}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n    else:\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Proactive: expecting {self.threshold} {self.expect} event \"\n                    f\"within {self.within}\",\n                ],\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTrigger","title":"<code>MetricTrigger</code>","text":"<p>               Bases: <code>ResourceTrigger</code></p> <p>A trigger that fires based on the results of a metric query.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTrigger(ResourceTrigger):\n    \"\"\"\n    A trigger that fires based on the results of a metric query.\n    \"\"\"\n\n    type: Literal[\"metric\"] = \"metric\"\n\n    posture: Literal[Posture.Metric] = Field(  # type: ignore[valid-type]\n        Posture.Metric,\n        description=\"Periodically evaluate the configured metric query.\",\n    )\n\n    metric: MetricTriggerQuery = Field(\n        ...,\n        description=\"The metric query to evaluate for this trigger. \",\n    )\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        m = self.metric\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    m = self.metric\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                f\"Metric: {m.name.value} {m.operator.value} {m.threshold} for {m.range}\",\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.MetricTriggerQuery","title":"<code>MetricTriggerQuery</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines a subset of the Trigger subclass, which is specific to Metric automations, that specify the query configurations and breaching conditions for the Automation</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class MetricTriggerQuery(PrefectBaseModel):\n    \"\"\"Defines a subset of the Trigger subclass, which is specific\n    to Metric automations, that specify the query configurations\n    and breaching conditions for the Automation\"\"\"\n\n    name: PrefectMetric = Field(\n        ...,\n        description=\"The name of the metric to query.\",\n    )\n    threshold: float = Field(\n        ...,\n        description=(\n            \"The threshold value against which we'll compare \" \"the query result.\"\n        ),\n    )\n    operator: MetricTriggerOperator = Field(\n        ...,\n        description=(\n            \"The comparative operator (LT / LTE / GT / GTE) used to compare \"\n            \"the query result against the threshold value.\"\n        ),\n    )\n    range: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The lookback duration (seconds) for a metric query. This duration is \"\n            \"used to determine the time range over which the query will be executed. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n    firing_for: timedelta = Field(\n        timedelta(seconds=300),  # defaults to 5 minutes\n        minimum=300.0,\n        exclusiveMinimum=False,\n        description=(\n            \"The duration (seconds) for which the metric query must breach \"\n            \"or resolve continuously before the state is updated and the \"\n            \"automation is triggered. \"\n            \"The minimum value is 300 seconds (5 minutes).\"\n        ),\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseAutomation","title":"<code>PauseAutomation</code>","text":"<p>               Bases: <code>AutomationAction</code></p> <p>Pauses a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseAutomation(AutomationAction):\n    \"\"\"Pauses a Work Queue\"\"\"\n\n    type: Literal[\"pause-automation\"] = \"pause-automation\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseDeployment","title":"<code>PauseDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Pauses the given Deployment</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseDeployment(DeploymentAction):\n    \"\"\"Pauses the given Deployment\"\"\"\n\n    type: Literal[\"pause-deployment\"] = \"pause-deployment\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseWorkPool","title":"<code>PauseWorkPool</code>","text":"<p>               Bases: <code>WorkPoolAction</code></p> <p>Pauses a Work Pool</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseWorkPool(WorkPoolAction):\n    \"\"\"Pauses a Work Pool\"\"\"\n\n    type: Literal[\"pause-work-pool\"] = \"pause-work-pool\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.PauseWorkQueue","title":"<code>PauseWorkQueue</code>","text":"<p>               Bases: <code>WorkQueueAction</code></p> <p>Pauses a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class PauseWorkQueue(WorkQueueAction):\n    \"\"\"Pauses a Work Queue\"\"\"\n\n    type: Literal[\"pause-work-queue\"] = \"pause-work-queue\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ReceivedEvent","title":"<code>ReceivedEvent</code>","text":"<p>               Bases: <code>Event</code></p> <p>The server-side view of an event that has happened to a Resource after it has been received by the server</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ReceivedEvent(Event):\n    \"\"\"The server-side view of an event that has happened to a Resource after it has\n    been received by the server\"\"\"\n\n    class Config:\n        orm_mode = True\n\n    received: DateTimeTZ = Field(\n        ...,\n        description=\"When the event was received by Prefect Cloud\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.RelatedResource","title":"<code>RelatedResource</code>","text":"<p>               Bases: <code>Resource</code></p> <p>A Resource with a specific role in an Event</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class RelatedResource(Resource):\n    \"\"\"A Resource with a specific role in an Event\"\"\"\n\n    @root_validator(pre=True)\n    def requires_resource_role(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        labels = cast(Dict[str, str], labels)\n\n        if \"prefect.resource.role\" not in labels:\n            raise ValueError(\n                \"Related Resources must include the prefect.resource.role label\"\n            )\n        if not labels[\"prefect.resource.role\"]:\n            raise ValueError(\"The prefect.resource.role label must be non-empty\")\n\n        return values\n\n    @property\n    def role(self) -&gt; str:\n        return self[\"prefect.resource.role\"]\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Resource","title":"<code>Resource</code>","text":"<p>               Bases: <code>Labelled</code></p> <p>An observable business object of interest to the user</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class Resource(Labelled):\n    \"\"\"An observable business object of interest to the user\"\"\"\n\n    @root_validator(pre=True)\n    def enforce_maximum_labels(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        if len(labels) &gt; PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value():\n            raise ValueError(\n                \"The maximum number of labels per resource \"\n                f\"is {PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value()}\"\n            )\n\n        return values\n\n    @root_validator(pre=True)\n    def requires_resource_id(cls, values: Dict[str, Any]):\n        labels = values.get(\"__root__\")\n        if not isinstance(labels, dict):\n            return values\n\n        labels = cast(Dict[str, str], labels)\n\n        if \"prefect.resource.id\" not in labels:\n            raise ValueError(\"Resources must include the prefect.resource.id label\")\n        if not labels[\"prefect.resource.id\"]:\n            raise ValueError(\"The prefect.resource.id label must be non-empty\")\n\n        return values\n\n    @property\n    def id(self) -&gt; str:\n        return self[\"prefect.resource.id\"]\n\n    @property\n    def name(self) -&gt; Optional[str]:\n        return self.get(\"prefect.resource.name\")\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResourceSpecification","title":"<code>ResourceSpecification</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A specification that may match zero, one, or many resources, used to target or select a set of resources in a query or automation.  A resource must match at least one value of all of the provided labels</p> Source code in <code>prefect/events/schemas/events.py</code> <pre><code>class ResourceSpecification(PrefectBaseModel):\n    \"\"\"A specification that may match zero, one, or many resources, used to target or\n    select a set of resources in a query or automation.  A resource must match at least\n    one value of all of the provided labels\"\"\"\n\n    __root__: Dict[str, Union[str, List[str]]]\n\n    def matches_every_resource(self) -&gt; bool:\n        return len(self) == 0\n\n    def matches_every_resource_of_kind(self, prefix: str) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        if len(self.__root__) == 1:\n            if resource_id := self.__root__.get(\"prefect.resource.id\"):\n                values = [resource_id] if isinstance(resource_id, str) else resource_id\n                return any(value == f\"{prefix}.*\" for value in values)\n\n        return False\n\n    def includes(self, candidates: Iterable[Resource]) -&gt; bool:\n        if self.matches_every_resource():\n            return True\n\n        for candidate in candidates:\n            if self.matches(candidate):\n                return True\n\n        return False\n\n    def matches(self, resource: Resource) -&gt; bool:\n        for label, expected in self.items():\n            value = resource.get(label)\n            if not any(matches(candidate, value) for candidate in expected):\n                return False\n        return True\n\n    def items(self) -&gt; Iterable[Tuple[str, List[str]]]:\n        return [\n            (label, [value] if isinstance(value, str) else value)\n            for label, value in self.__root__.items()\n        ]\n\n    def __contains__(self, key: str) -&gt; bool:\n        return self.__root__.__contains__(key)\n\n    def __getitem__(self, key: str) -&gt; List[str]:\n        value = self.__root__[key]\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def pop(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.pop(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def get(\n        self, key: str, default: Optional[Union[str, List[str]]] = None\n    ) -&gt; Optional[List[str]]:\n        value = self.__root__.get(key, default)\n        if not value:\n            return []\n        if not isinstance(value, list):\n            value = [value]\n        return value\n\n    def __len__(self) -&gt; int:\n        return len(self.__root__)\n\n    def deepcopy(self) -&gt; \"ResourceSpecification\":\n        return ResourceSpecification.parse_obj(copy.deepcopy(self.__root__))\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResourceTrigger","title":"<code>ResourceTrigger</code>","text":"<p>               Bases: <code>Trigger</code>, <code>ABC</code></p> <p>Base class for triggers that may filter by the labels of resources.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class ResourceTrigger(Trigger, abc.ABC):\n    \"\"\"\n    Base class for triggers that may filter by the labels of resources.\n    \"\"\"\n\n    type: str\n\n    match: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for resources which this trigger will match.\",\n    )\n    match_related: ResourceSpecification = Field(\n        default_factory=lambda: ResourceSpecification.parse_obj({}),\n        description=\"Labels for related resources which this trigger will match.\",\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeAutomation","title":"<code>ResumeAutomation</code>","text":"<p>               Bases: <code>AutomationAction</code></p> <p>Resumes a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeAutomation(AutomationAction):\n    \"\"\"Resumes a Work Queue\"\"\"\n\n    type: Literal[\"resume-automation\"] = \"resume-automation\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeDeployment","title":"<code>ResumeDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Resumes the given Deployment</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeDeployment(DeploymentAction):\n    \"\"\"Resumes the given Deployment\"\"\"\n\n    type: Literal[\"resume-deployment\"] = \"resume-deployment\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeWorkPool","title":"<code>ResumeWorkPool</code>","text":"<p>               Bases: <code>WorkPoolAction</code></p> <p>Resumes a Work Pool</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeWorkPool(WorkPoolAction):\n    \"\"\"Resumes a Work Pool\"\"\"\n\n    type: Literal[\"resume-work-pool\"] = \"resume-work-pool\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.ResumeWorkQueue","title":"<code>ResumeWorkQueue</code>","text":"<p>               Bases: <code>WorkQueueAction</code></p> <p>Resumes a Work Queue</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class ResumeWorkQueue(WorkQueueAction):\n    \"\"\"Resumes a Work Queue\"\"\"\n\n    type: Literal[\"resume-work-queue\"] = \"resume-work-queue\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.RunDeployment","title":"<code>RunDeployment</code>","text":"<p>               Bases: <code>DeploymentAction</code></p> <p>Runs the given deployment with the given parameters</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class RunDeployment(DeploymentAction):\n    \"\"\"Runs the given deployment with the given parameters\"\"\"\n\n    type: Literal[\"run-deployment\"] = \"run-deployment\"\n\n    parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"The parameters to pass to the deployment, or None to use the \"\n            \"deployment's default parameters\"\n        ),\n    )\n    job_variables: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"The job variables to pass to the created flow run, or None \"\n            \"to use the deployment's default job variables\"\n        ),\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SendNotification","title":"<code>SendNotification</code>","text":"<p>               Bases: <code>Action</code></p> <p>Send a notification when an Automation is triggered</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class SendNotification(Action):\n    \"\"\"Send a notification when an Automation is triggered\"\"\"\n\n    type: Literal[\"send-notification\"] = \"send-notification\"\n    block_document_id: UUID = Field(\n        description=\"The identifier of the notification block to use\"\n    )\n    subject: str = Field(\"Prefect automated notification\")\n    body: str = Field(description=\"The text of the notification to send\")\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SequenceTrigger","title":"<code>SequenceTrigger</code>","text":"<p>               Bases: <code>CompositeTrigger</code></p> <p>A composite trigger that requires some number of triggers to have fired within the given time period in a specific order</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class SequenceTrigger(CompositeTrigger):\n    \"\"\"A composite trigger that requires some number of triggers to have fired\n    within the given time period in a specific order\"\"\"\n\n    type: Literal[\"sequence\"] = \"sequence\"\n\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n        return textwrap.indent(\n            \"\\n\".join(\n                [\n                    \"In this order:\",\n                    \"\\n\".join(\n                        [\n                            trigger.describe_for_cli(indent=indent + 1)\n                            for trigger in self.triggers\n                        ]\n                    ),\n                ]\n            ),\n            prefix=\"  \" * indent,\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SequenceTrigger.describe_for_cli","title":"<code>describe_for_cli</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>def describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n    return textwrap.indent(\n        \"\\n\".join(\n            [\n                \"In this order:\",\n                \"\\n\".join(\n                    [\n                        trigger.describe_for_cli(indent=indent + 1)\n                        for trigger in self.triggers\n                    ]\n                ),\n            ]\n        ),\n        prefix=\"  \" * indent,\n    )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.SuspendFlowRun","title":"<code>SuspendFlowRun</code>","text":"<p>               Bases: <code>Action</code></p> <p>Suspends a flow run associated with the trigger</p> Source code in <code>prefect/events/actions.py</code> <pre><code>class SuspendFlowRun(Action):\n    \"\"\"Suspends a flow run associated with the trigger\"\"\"\n\n    type: Literal[\"suspend-flow-run\"] = \"suspend-flow-run\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Trigger","title":"<code>Trigger</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>ABC</code></p> <p>Base class describing a set of criteria that must be satisfied in order to trigger an automation.</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>class Trigger(PrefectBaseModel, abc.ABC, extra=\"ignore\"):  # type: ignore[call-arg]\n    \"\"\"\n    Base class describing a set of criteria that must be satisfied in order to trigger\n    an automation.\n    \"\"\"\n\n    type: str\n\n    @abc.abstractmethod\n    def describe_for_cli(self, indent: int = 0) -&gt; str:\n        \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n\n    # The following allows the regular Trigger class to be used when serving or\n    # deploying flows, analogous to how the Deployment*Trigger classes work\n\n    _deployment_id: Optional[UUID] = PrivateAttr(default=None)\n\n    def set_deployment_id(self, deployment_id: UUID):\n        self._deployment_id = deployment_id\n\n    def owner_resource(self) -&gt; Optional[str]:\n        return f\"prefect.deployment.{self._deployment_id}\"\n\n    def actions(self) -&gt; List[ActionTypes]:\n        assert self._deployment_id\n        return [\n            RunDeployment(\n                source=\"selected\",\n                deployment_id=self._deployment_id,\n                parameters=getattr(self, \"parameters\", None),\n                job_variables=getattr(self, \"job_variables\", None),\n            )\n        ]\n\n    def as_automation(self) -&gt; \"AutomationCore\":\n        assert self._deployment_id\n\n        trigger: TriggerTypes = cast(TriggerTypes, self)\n\n        # This is one of the Deployment*Trigger classes, so translate it over to a\n        # plain Trigger\n        if hasattr(self, \"trigger_type\"):\n            trigger = self.trigger_type(**self.dict())\n\n        return AutomationCore(\n            name=(\n                getattr(self, \"name\", None)\n                or f\"Automation for deployment {self._deployment_id}\"\n            ),\n            description=\"\",\n            enabled=getattr(self, \"enabled\", True),\n            trigger=trigger,\n            actions=self.actions(),\n            owner_resource=self.owner_resource(),\n        )\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.Trigger.describe_for_cli","title":"<code>describe_for_cli</code>  <code>abstractmethod</code>","text":"<p>Return a human-readable description of this trigger for the CLI</p> Source code in <code>prefect/events/schemas/automations.py</code> <pre><code>@abc.abstractmethod\ndef describe_for_cli(self, indent: int = 0) -&gt; str:\n    \"\"\"Return a human-readable description of this trigger for the CLI\"\"\"\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/events/#prefect.events.emit_event","title":"<code>emit_event</code>","text":"<p>Send an event to Prefect Cloud.</p> <p>Parameters:</p> Name Type Description Default <code>event</code> <code>str</code> <p>The name of the event that happened.</p> required <code>resource</code> <code>Dict[str, str]</code> <p>The primary Resource this event concerns.</p> required <code>occurred</code> <code>Optional[DateTimeTZ]</code> <p>When the event happened from the sender's perspective.       Defaults to the current datetime.</p> <code>None</code> <code>related</code> <code>Optional[Union[List[Dict[str, str]], List[RelatedResource]]]</code> <p>A list of additional Resources involved in this event.</p> <code>None</code> <code>payload</code> <code>Optional[Dict[str, Any]]</code> <p>An open-ended set of data describing what happened.</p> <code>None</code> <code>id</code> <code>Optional[UUID]</code> <p>The sender-provided identifier for this event. Defaults to a random UUID.</p> <code>None</code> <code>follows</code> <code>Optional[Event]</code> <p>The event that preceded this one. If the preceding event happened more than 5 minutes prior to this event the follows relationship will not be set.</p> <code>None</code> <p>Returns:</p> Type Description <code>Optional[Event]</code> <p>The event that was emitted if worker is using a client that emit</p> <code>Optional[Event]</code> <p>events, otherwise None</p> Source code in <code>prefect/events/utilities.py</code> <pre><code>def emit_event(\n    event: str,\n    resource: Dict[str, str],\n    occurred: Optional[DateTimeTZ] = None,\n    related: Optional[Union[List[Dict[str, str]], List[RelatedResource]]] = None,\n    payload: Optional[Dict[str, Any]] = None,\n    id: Optional[UUID] = None,\n    follows: Optional[Event] = None,\n) -&gt; Optional[Event]:\n    \"\"\"\n    Send an event to Prefect Cloud.\n\n    Args:\n        event: The name of the event that happened.\n        resource: The primary Resource this event concerns.\n        occurred: When the event happened from the sender's perspective.\n                  Defaults to the current datetime.\n        related: A list of additional Resources involved in this event.\n        payload: An open-ended set of data describing what happened.\n        id: The sender-provided identifier for this event. Defaults to a random\n            UUID.\n        follows: The event that preceded this one. If the preceding event\n            happened more than 5 minutes prior to this event the follows\n            relationship will not be set.\n\n    Returns:\n        The event that was emitted if worker is using a client that emit\n        events, otherwise None\n    \"\"\"\n    if not should_emit_events():\n        return None\n\n    operational_clients = [\n        AssertingEventsClient,\n        PrefectCloudEventsClient,\n        PrefectEventsClient,\n        PrefectEphemeralEventsClient,\n    ]\n    worker_instance = EventsWorker.instance()\n\n    if worker_instance.client_type not in operational_clients:\n        return None\n\n    event_kwargs: Dict[str, Any] = {\n        \"event\": event,\n        \"resource\": resource,\n    }\n\n    if occurred is None:\n        occurred = pendulum.now(\"UTC\")\n    event_kwargs[\"occurred\"] = occurred\n\n    if related is not None:\n        event_kwargs[\"related\"] = related\n\n    if payload is not None:\n        event_kwargs[\"payload\"] = payload\n\n    if id is not None:\n        event_kwargs[\"id\"] = id\n\n    if follows is not None:\n        if -TIGHT_TIMING &lt; (occurred - follows.occurred) &lt; TIGHT_TIMING:\n            event_kwargs[\"follows\"] = follows.id\n\n    event_obj = Event(**event_kwargs)\n    worker_instance.send(event_obj)\n\n    return event_obj\n</code></pre>","tags":["Python API","events"]},{"location":"api-ref/prefect/exceptions/","title":"prefect.exceptions","text":"","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions","title":"<code>prefect.exceptions</code>","text":"<p>Prefect-specific exceptions.</p>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.Abort","title":"<code>Abort</code>","text":"<p>               Bases: <code>PrefectSignal</code></p> <p>Raised when the API sends an 'ABORT' instruction during state proposal.</p> <p>Indicates that the run should exit immediately.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class Abort(PrefectSignal):\n    \"\"\"\n    Raised when the API sends an 'ABORT' instruction during state proposal.\n\n    Indicates that the run should exit immediately.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.BlockMissingCapabilities","title":"<code>BlockMissingCapabilities</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a block does not have required capabilities for a given operation.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class BlockMissingCapabilities(PrefectException):\n    \"\"\"\n    Raised when a block does not have required capabilities for a given operation.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.CancelledRun","title":"<code>CancelledRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a cancelled run is retrieved and an exception is not attached.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class CancelledRun(PrefectException):\n    \"\"\"\n    Raised when the result from a cancelled run is retrieved and an exception\n    is not attached.\n\n    This occurs when a string is attached to the state instead of an exception\n    or if the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.CrashedRun","title":"<code>CrashedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a crashed run is retrieved.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class CrashedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a crashed run is retrieved.\n\n    This occurs when a string is attached to the state instead of an exception or if\n    the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ExternalSignal","title":"<code>ExternalSignal</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>Base type for external signal-like exceptions that should never be caught by users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ExternalSignal(BaseException):\n    \"\"\"\n    Base type for external signal-like exceptions that should never be caught by users.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FailedRun","title":"<code>FailedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a failed run is retrieved and an exception is not attached.</p> <p>This occurs when a string is attached to the state instead of an exception or if the state's data is null.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FailedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a failed run is retrieved and an exception is not\n    attached.\n\n    This occurs when a string is attached to the state instead of an exception or if\n    the state's data is null.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowPauseTimeout","title":"<code>FlowPauseTimeout</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a flow pause times out</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowPauseTimeout(PrefectException):\n    \"\"\"Raised when a flow pause times out\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowRunWaitTimeout","title":"<code>FlowRunWaitTimeout</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a flow run takes longer than a given timeout</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowRunWaitTimeout(PrefectException):\n    \"\"\"Raised when a flow run takes longer than a given timeout\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.FlowScriptError","title":"<code>FlowScriptError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a script errors during evaluation while attempting to load a flow.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class FlowScriptError(PrefectException):\n    \"\"\"\n    Raised when a script errors during evaluation while attempting to load a flow.\n    \"\"\"\n\n    def __init__(\n        self,\n        user_exc: Exception,\n        script_path: str,\n    ) -&gt; None:\n        message = f\"Flow script at {script_path!r} encountered an exception\"\n        super().__init__(message)\n\n        self.user_exc = user_exc\n\n    def rich_user_traceback(self, **kwargs):\n        trace = Traceback.extract(\n            type(self.user_exc),\n            self.user_exc,\n            self.user_exc.__traceback__.tb_next.tb_next.tb_next.tb_next,\n        )\n        return Traceback(trace, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureError","title":"<code>InfrastructureError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>A base class for exceptions related to infrastructure blocks</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureError(PrefectException):\n    \"\"\"\n    A base class for exceptions related to infrastructure blocks\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureNotAvailable","title":"<code>InfrastructureNotAvailable</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when infrastructure is not accessible from the current machine. For example, if a process was spawned on another machine it cannot be managed.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureNotAvailable(PrefectException):\n    \"\"\"\n    Raised when infrastructure is not accessible from the current machine. For example,\n    if a process was spawned on another machine it cannot be managed.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InfrastructureNotFound","title":"<code>InfrastructureNotFound</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when infrastructure is missing, likely because it has exited or been deleted.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InfrastructureNotFound(PrefectException):\n    \"\"\"\n    Raised when infrastructure is missing, likely because it has exited or been\n    deleted.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InvalidNameError","title":"<code>InvalidNameError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>ValueError</code></p> <p>Raised when a name contains characters that are not permitted.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InvalidNameError(PrefectException, ValueError):\n    \"\"\"\n    Raised when a name contains characters that are not permitted.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.InvalidRepositoryURLError","title":"<code>InvalidRepositoryURLError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when an incorrect URL is provided to a GitHub filesystem block.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class InvalidRepositoryURLError(PrefectException):\n    \"\"\"Raised when an incorrect URL is provided to a GitHub filesystem block.\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MappingLengthMismatch","title":"<code>MappingLengthMismatch</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to call Task.map with arguments of different lengths.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MappingLengthMismatch(PrefectException):\n    \"\"\"\n    Raised when attempting to call Task.map with arguments of different lengths.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MappingMissingIterable","title":"<code>MappingMissingIterable</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to call Task.map with all static arguments</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MappingMissingIterable(PrefectException):\n    \"\"\"\n    Raised when attempting to call Task.map with all static arguments\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingContextError","title":"<code>MissingContextError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>RuntimeError</code></p> <p>Raised when a method is called that requires a task or flow run context to be active but one cannot be found.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingContextError(PrefectException, RuntimeError):\n    \"\"\"\n    Raised when a method is called that requires a task or flow run context to be\n    active but one cannot be found.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingFlowError","title":"<code>MissingFlowError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a given flow name is not found in the expected script.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingFlowError(PrefectException):\n    \"\"\"\n    Raised when a given flow name is not found in the expected script.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingProfileError","title":"<code>MissingProfileError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>ValueError</code></p> <p>Raised when a profile name does not exist.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingProfileError(PrefectException, ValueError):\n    \"\"\"\n    Raised when a profile name does not exist.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.MissingResult","title":"<code>MissingResult</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a result is missing from a state; often when result persistence is disabled and the state is retrieved from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class MissingResult(PrefectException):\n    \"\"\"\n    Raised when a result is missing from a state; often when result persistence is\n    disabled and the state is retrieved from the API.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.NotPausedError","title":"<code>NotPausedError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when attempting to unpause a run that isn't paused.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class NotPausedError(PrefectException):\n    \"\"\"Raised when attempting to unpause a run that isn't paused.\"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ObjectAlreadyExists","title":"<code>ObjectAlreadyExists</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the client receives a 409 (conflict) from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ObjectAlreadyExists(PrefectException):\n    \"\"\"\n    Raised when the client receives a 409 (conflict) from the API.\n    \"\"\"\n\n    def __init__(self, http_exc: Exception, *args, **kwargs):\n        self.http_exc = http_exc\n        super().__init__(*args, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ObjectNotFound","title":"<code>ObjectNotFound</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the client receives a 404 (not found) from the API.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ObjectNotFound(PrefectException):\n    \"\"\"\n    Raised when the client receives a 404 (not found) from the API.\n    \"\"\"\n\n    def __init__(self, http_exc: Exception, *args, **kwargs):\n        self.http_exc = http_exc\n        super().__init__(*args, **kwargs)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ParameterBindError","title":"<code>ParameterBindError</code>","text":"<p>               Bases: <code>TypeError</code>, <code>PrefectException</code></p> <p>Raised when args and kwargs cannot be converted to parameters.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ParameterBindError(TypeError, PrefectException):\n    \"\"\"\n    Raised when args and kwargs cannot be converted to parameters.\n    \"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_bind_failure(\n        cls, fn: Callable, exc: TypeError, call_args: List, call_kwargs: Dict\n    ) -&gt; Self:\n        fn_signature = str(inspect.signature(fn)).strip(\"()\")\n\n        base = f\"Error binding parameters for function '{fn.__name__}': {exc}\"\n        signature = f\"Function '{fn.__name__}' has signature '{fn_signature}'\"\n        received = f\"received args: {call_args} and kwargs: {list(call_kwargs.keys())}\"\n        msg = f\"{base}.\\n{signature} but {received}.\"\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ParameterTypeError","title":"<code>ParameterTypeError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a parameter does not pass Pydantic type validation.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ParameterTypeError(PrefectException):\n    \"\"\"\n    Raised when a parameter does not pass Pydantic type validation.\n    \"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_validation_error(cls, exc: ValidationError) -&gt; Self:\n        bad_params = [\n            f'{\".\".join(str(item) for item in err[\"loc\"])}: {err[\"msg\"]}'\n            for err in exc.errors()\n        ]\n        msg = \"Flow run received invalid parameters:\\n - \" + \"\\n - \".join(bad_params)\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.Pause","title":"<code>Pause</code>","text":"<p>               Bases: <code>PrefectSignal</code></p> <p>Raised when a flow run is PAUSED and needs to exit for resubmission.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class Pause(PrefectSignal):\n    \"\"\"\n    Raised when a flow run is PAUSED and needs to exit for resubmission.\n    \"\"\"\n\n    def __init__(self, *args, state=None, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.state = state\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PausedRun","title":"<code>PausedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a paused run is retrieved.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PausedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a paused run is retrieved.\n    \"\"\"\n\n    def __init__(self, *args, state=None, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.state = state\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectException","title":"<code>PrefectException</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Base exception type for Prefect errors.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectException(Exception):\n    \"\"\"\n    Base exception type for Prefect errors.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectHTTPStatusError","title":"<code>PrefectHTTPStatusError</code>","text":"<p>               Bases: <code>HTTPStatusError</code></p> <p>Raised when client receives a <code>Response</code> that contains an HTTPStatusError.</p> <p>Used to include API error details in the error messages that the client provides users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectHTTPStatusError(HTTPStatusError):\n    \"\"\"\n    Raised when client receives a `Response` that contains an HTTPStatusError.\n\n    Used to include API error details in the error messages that the client provides users.\n    \"\"\"\n\n    @classmethod\n    def from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -&gt; Self:\n        \"\"\"\n        Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.\n        \"\"\"\n        try:\n            details = httpx_error.response.json()\n        except Exception:\n            details = None\n\n        error_message, *more_info = str(httpx_error).split(\"\\n\")\n\n        if details:\n            message_components = [error_message, f\"Response: {details}\", *more_info]\n        else:\n            message_components = [error_message, *more_info]\n\n        new_message = \"\\n\".join(message_components)\n\n        return cls(\n            new_message, request=httpx_error.request, response=httpx_error.response\n        )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectHTTPStatusError.from_httpx_error","title":"<code>from_httpx_error</code>  <code>classmethod</code>","text":"<p>Generate a <code>PrefectHTTPStatusError</code> from an <code>httpx.HTTPStatusError</code>.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>@classmethod\ndef from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -&gt; Self:\n    \"\"\"\n    Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.\n    \"\"\"\n    try:\n        details = httpx_error.response.json()\n    except Exception:\n        details = None\n\n    error_message, *more_info = str(httpx_error).split(\"\\n\")\n\n    if details:\n        message_components = [error_message, f\"Response: {details}\", *more_info]\n    else:\n        message_components = [error_message, *more_info]\n\n    new_message = \"\\n\".join(message_components)\n\n    return cls(\n        new_message, request=httpx_error.request, response=httpx_error.response\n    )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.PrefectSignal","title":"<code>PrefectSignal</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>Base type for signal-like exceptions that should never be caught by users.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class PrefectSignal(BaseException):\n    \"\"\"\n    Base type for signal-like exceptions that should never be caught by users.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ProtectedBlockError","title":"<code>ProtectedBlockError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when an operation is prevented due to block protection.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ProtectedBlockError(PrefectException):\n    \"\"\"\n    Raised when an operation is prevented due to block protection.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ReservedArgumentError","title":"<code>ReservedArgumentError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>TypeError</code></p> <p>Raised when a function used with Prefect has an argument with a name that is reserved for a Prefect feature</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ReservedArgumentError(PrefectException, TypeError):\n    \"\"\"\n    Raised when a function used with Prefect has an argument with a name that is\n    reserved for a Prefect feature\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.ScriptError","title":"<code>ScriptError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a script errors during evaluation while attempting to load data</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class ScriptError(PrefectException):\n    \"\"\"\n    Raised when a script errors during evaluation while attempting to load data\n    \"\"\"\n\n    def __init__(\n        self,\n        user_exc: Exception,\n        path: str,\n    ) -&gt; None:\n        message = f\"Script at {str(path)!r} encountered an exception: {user_exc!r}\"\n        super().__init__(message)\n        self.user_exc = user_exc\n\n        # Strip script run information from the traceback\n        self.user_exc.__traceback__ = _trim_traceback(\n            self.user_exc.__traceback__,\n            remove_modules=[prefect.utilities.importtools],\n        )\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.SignatureMismatchError","title":"<code>SignatureMismatchError</code>","text":"<p>               Bases: <code>PrefectException</code>, <code>TypeError</code></p> <p>Raised when parameters passed to a function do not match its signature.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class SignatureMismatchError(PrefectException, TypeError):\n    \"\"\"Raised when parameters passed to a function do not match its signature.\"\"\"\n\n    def __init__(self, msg: str):\n        super().__init__(msg)\n\n    @classmethod\n    def from_bad_params(cls, expected_params: List[str], provided_params: List[str]):\n        msg = (\n            f\"Function expects parameters {expected_params} but was provided with\"\n            f\" parameters {provided_params}\"\n        )\n        return cls(msg)\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.TerminationSignal","title":"<code>TerminationSignal</code>","text":"<p>               Bases: <code>ExternalSignal</code></p> <p>Raised when a flow run receives a termination signal.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class TerminationSignal(ExternalSignal):\n    \"\"\"\n    Raised when a flow run receives a termination signal.\n    \"\"\"\n\n    def __init__(self, signal: int):\n        self.signal = signal\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UnfinishedRun","title":"<code>UnfinishedRun</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the result from a run that is not finished is retrieved.</p> <p>For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UnfinishedRun(PrefectException):\n    \"\"\"\n    Raised when the result from a run that is not finished is retrieved.\n\n    For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UnspecifiedFlowError","title":"<code>UnspecifiedFlowError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when multiple flows are found in the expected script and no name is given.</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UnspecifiedFlowError(PrefectException):\n    \"\"\"\n    Raised when multiple flows are found in the expected script and no name is given.\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.UpstreamTaskError","title":"<code>UpstreamTaskError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when a task relies on the result of another task but that task is not 'COMPLETE'</p> Source code in <code>prefect/exceptions.py</code> <pre><code>class UpstreamTaskError(PrefectException):\n    \"\"\"\n    Raised when a task relies on the result of another task but that task is not\n    'COMPLETE'\n    \"\"\"\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/exceptions/#prefect.exceptions.exception_traceback","title":"<code>exception_traceback</code>","text":"<p>Convert an exception to a printable string with a traceback</p> Source code in <code>prefect/exceptions.py</code> <pre><code>def exception_traceback(exc: Exception) -&gt; str:\n    \"\"\"\n    Convert an exception to a printable string with a traceback\n    \"\"\"\n    tb = traceback.TracebackException.from_exception(exc)\n    return \"\".join(list(tb.format()))\n</code></pre>","tags":["Python API","exceptions","error handling","errors"]},{"location":"api-ref/prefect/filesystems/","title":"prefect.filesystems","text":"","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems","title":"<code>prefect.filesystems</code>","text":"","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure","title":"<code>Azure</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>AzureBlobStorageContainer</code> from the <code>prefect-azure</code> package, which offers enhanced functionality and better a better user experience.</p> <p>Store data as a file on Azure Datalake and Azure Blob Storage.</p> Example <p>Load stored Azure config: <pre><code>from prefect.filesystems import Azure\n\naz_block = Azure.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `AzureBlobStorageContainer` block from prefect-azure instead.\",\n)\nclass Azure(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `AzureBlobStorageContainer` from the `prefect-azure` package, which\n    offers enhanced functionality and better a better user experience.\n\n    Store data as a file on Azure Datalake and Azure Blob Storage.\n\n    Example:\n        Load stored Azure config:\n        ```python\n        from prefect.filesystems import Azure\n\n        az_block = Azure.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#azure\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"An Azure storage bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    azure_storage_connection_string: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage connection string\",\n        description=(\n            \"Equivalent to the AZURE_STORAGE_CONNECTION_STRING environment variable.\"\n        ),\n    )\n    azure_storage_account_name: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage account name\",\n        description=(\n            \"Equivalent to the AZURE_STORAGE_ACCOUNT_NAME environment variable.\"\n        ),\n    )\n    azure_storage_account_key: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage account key\",\n        description=\"Equivalent to the AZURE_STORAGE_ACCOUNT_KEY environment variable.\",\n    )\n    azure_storage_tenant_id: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage tenant ID\",\n        description=\"Equivalent to the AZURE_TENANT_ID environment variable.\",\n    )\n    azure_storage_client_id: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage client ID\",\n        description=\"Equivalent to the AZURE_CLIENT_ID environment variable.\",\n    )\n    azure_storage_client_secret: Optional[SecretStr] = Field(\n        None,\n        title=\"Azure storage client secret\",\n        description=\"Equivalent to the AZURE_CLIENT_SECRET environment variable.\",\n    )\n    azure_storage_anon: bool = Field(\n        default=True,\n        title=\"Azure storage anonymous connection\",\n        description=(\n            \"Set the 'anon' flag for ADLFS. This should be False for systems that\"\n            \" require ADLFS to use DefaultAzureCredentials.\"\n        ),\n    )\n    azure_storage_container: Optional[SecretStr] = Field(\n        default=None,\n        title=\"Azure storage container\",\n        description=(\n            \"Blob Container in Azure Storage Account. If set the 'bucket_path' will\"\n            \" be interpreted using the following URL format:\"\n            \"'az://&lt;container&gt;@&lt;storage_account&gt;.dfs.core.windows.net/&lt;bucket_path&gt;'.\"\n        ),\n    )\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        if self.azure_storage_container:\n            return (\n                f\"az://{self.azure_storage_container.get_secret_value()}\"\n                f\"@{self.azure_storage_account_name.get_secret_value()}\"\n                f\".dfs.core.windows.net/{self.bucket_path}\"\n            )\n        else:\n            return f\"az://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.azure_storage_connection_string:\n            settings[\n                \"connection_string\"\n            ] = self.azure_storage_connection_string.get_secret_value()\n        if self.azure_storage_account_name:\n            settings[\n                \"account_name\"\n            ] = self.azure_storage_account_name.get_secret_value()\n        if self.azure_storage_account_key:\n            settings[\"account_key\"] = self.azure_storage_account_key.get_secret_value()\n        if self.azure_storage_tenant_id:\n            settings[\"tenant_id\"] = self.azure_storage_tenant_id.get_secret_value()\n        if self.azure_storage_client_id:\n            settings[\"client_id\"] = self.azure_storage_client_id.get_secret_value()\n        if self.azure_storage_client_secret:\n            settings[\n                \"client_secret\"\n            ] = self.azure_storage_client_secret.get_secret_value()\n        settings[\"anon\"] = self.azure_storage_anon\n        self._remote_file_system = RemoteFileSystem(\n            basepath=self.basepath, settings=settings\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.Azure.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS","title":"<code>GCS</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>GcsBucket</code> from the <code>prefect-gcp</code> package, which offers enhanced functionality and better a better user experience. Store data as a file on Google Cloud Storage.</p> Example <p>Load stored GCS config: <pre><code>from prefect.filesystems import GCS\n\ngcs_block = GCS.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\", help=\"Use the `GcsBucket` block from prefect-gcp instead.\"\n)\nclass GCS(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `GcsBucket` from the `prefect-gcp` package, which offers enhanced functionality\n    and better a better user experience.\n    Store data as a file on Google Cloud Storage.\n\n    Example:\n        Load stored GCS config:\n        ```python\n        from prefect.filesystems import GCS\n\n        gcs_block = GCS.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/422d13bb838cf247eb2b2cf229ce6a2e717d601b-256x256.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#gcs\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"A GCS bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    service_account_info: Optional[SecretStr] = Field(\n        default=None,\n        description=\"The contents of a service account keyfile as a JSON string.\",\n    )\n    project: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The project the GCS bucket resides in. If not provided, the project will\"\n            \" be inferred from the credentials or environment.\"\n        ),\n    )\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"gcs://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.service_account_info:\n            try:\n                settings[\"token\"] = json.loads(\n                    self.service_account_info.get_secret_value()\n                )\n            except json.JSONDecodeError:\n                raise ValueError(\n                    \"Unable to load provided service_account_info. Please make sure\"\n                    \" that the provided value is a valid JSON string.\"\n                )\n        remote_file_system = RemoteFileSystem(\n            basepath=f\"gcs://{self.bucket_path}\", settings=settings\n        )\n        return remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GCS.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GitHub","title":"<code>GitHub</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <pre><code>DEPRECATION WARNING:\n\nThis class is deprecated as of March 2024 and will not be available after September 2024.\nIt has been replaced by `GitHubRepository` from the `prefect-github` package, which offers\nenhanced functionality and better a better user experience.\n</code></pre> <p>q     Interact with files stored on GitHub repositories.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `GitHubRepository` block from prefect-github instead.\",\n)\nclass GitHub(ReadableDeploymentStorage):\n    \"\"\"\n        DEPRECATION WARNING:\n\n        This class is deprecated as of March 2024 and will not be available after September 2024.\n        It has been replaced by `GitHubRepository` from the `prefect-github` package, which offers\n        enhanced functionality and better a better user experience.\n    q\n        Interact with files stored on GitHub repositories.\n    \"\"\"\n\n    _block_type_name = \"GitHub\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#github\"\n\n    repository: str = Field(\n        default=...,\n        description=(\n            \"The URL of a GitHub repository to read from, in either HTTPS or SSH\"\n            \" format.\"\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    access_token: Optional[SecretStr] = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=(\n            \"A GitHub Personal Access Token (PAT) with repo scope.\"\n            \" To use a fine-grained PAT, provide '{username}:{PAT}' as the value.\"\n        ),\n    )\n    include_git_objects: bool = Field(\n        default=True,\n        description=(\n            \"Whether to include git objects when copying the repo contents to a\"\n            \" directory.\"\n        ),\n    )\n\n    @validator(\"access_token\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict) -&gt; str:\n        return validate_github_access_token(v, values)\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos: https://&lt;oauth-key&gt;@github.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urllib.parse.urlparse(self.repository)\n        if url_components.scheme == \"https\" and self.access_token is not None:\n            updated_components = url_components._replace(\n                netloc=f\"{self.access_token.get_secret_value()}@{url_components.netloc}\"\n            )\n            full_url = urllib.parse.urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: str\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitHubRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitHub project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        cmd += [\"--depth\", \"1\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            ignore_func = None\n            if not self.include_git_objects:\n                ignore_func = ignore_patterns(\".git\")\n\n            copytree(\n                src=content_source,\n                dst=content_destination,\n                dirs_exist_ok=True,\n                ignore=ignore_func,\n            )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.GitHub.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitHub project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    cmd += [\"--depth\", \"1\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        ignore_func = None\n        if not self.include_git_objects:\n            ignore_func = ignore_patterns(\".git\")\n\n        copytree(\n            src=content_source,\n            dst=content_destination,\n            dirs_exist_ok=True,\n            ignore=ignore_func,\n        )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem","title":"<code>LocalFileSystem</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a local file system.</p> Example <p>Load stored local file system config: <pre><code>from prefect.filesystems import LocalFileSystem\n\nlocal_file_system_block = LocalFileSystem.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a local file system.\n\n    Example:\n        Load stored local file system config:\n        ```python\n        from prefect.filesystems import LocalFileSystem\n\n        local_file_system_block = LocalFileSystem.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Local File System\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/ad39089fa66d273b943394a68f003f7a19aa850e-48x48.png\"\n    _documentation_url = (\n        \"https://docs.prefect.io/concepts/filesystems/#local-filesystem\"\n    )\n\n    basepath: Optional[str] = Field(\n        default=None, description=\"Default local path for this block to write to.\"\n    )\n\n    @validator(\"basepath\", pre=True)\n    def cast_pathlib(cls, value):\n        return stringify_path(value)\n\n    def _resolve_path(self, path: str) -&gt; Path:\n        # Only resolve the base path at runtime, default to the current directory\n        basepath = (\n            Path(self.basepath).expanduser().resolve()\n            if self.basepath\n            else Path(\".\").resolve()\n        )\n\n        # Determine the path to access relative to the base path, ensuring that paths\n        # outside of the base path are off limits\n        if path is None:\n            return basepath\n\n        path: Path = Path(path).expanduser()\n\n        if not path.is_absolute():\n            path = basepath / path\n        else:\n            path = path.resolve()\n            if basepath not in path.parents and (basepath != path):\n                raise ValueError(\n                    f\"Provided path {path} is outside of the base path {basepath}.\"\n                )\n\n        return path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: str = None, local_path: str = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a directory from one place to another on the local filesystem.\n\n        Defaults to copying the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        if not from_path:\n            from_path = Path(self.basepath).expanduser().resolve()\n        else:\n            from_path = self._resolve_path(from_path)\n\n        if not local_path:\n            local_path = Path(\".\").resolve()\n        else:\n            local_path = Path(local_path).resolve()\n\n        if from_path == local_path:\n            # If the paths are the same there is no need to copy\n            # and we avoid shutil.copytree raising an error\n            return\n\n        # .prefectignore exists in the original location, not the current location which\n        # is most likely temporary\n        if (from_path / Path(\".prefectignore\")).exists():\n            ignore_func = await self._get_ignore_func(\n                local_path=from_path, ignore_file=from_path / Path(\".prefectignore\")\n            )\n        else:\n            ignore_func = None\n\n        copytree(from_path, local_path, dirs_exist_ok=True, ignore=ignore_func)\n\n    async def _get_ignore_func(self, local_path: str, ignore_file: str):\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(root=local_path, ignore_patterns=ignore_patterns)\n\n        def ignore_func(directory, files):\n            relative_path = Path(directory).relative_to(local_path)\n\n            files_to_ignore = [\n                f for f in files if str(relative_path / f) not in included_files\n            ]\n            return files_to_ignore\n\n        return ignore_func\n\n    @sync_compatible\n    async def put_directory(\n        self, local_path: str = None, to_path: str = None, ignore_file: str = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a directory from one place to another on the local filesystem.\n\n        Defaults to copying the entire contents of the current working directory to the block's basepath.\n        An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.\n        \"\"\"\n        destination_path = self._resolve_path(to_path)\n\n        if not local_path:\n            local_path = Path(\".\").absolute()\n\n        if ignore_file:\n            ignore_func = await self._get_ignore_func(\n                local_path=local_path, ignore_file=ignore_file\n            )\n        else:\n            ignore_func = None\n\n        if local_path == destination_path:\n            pass\n        else:\n            copytree(\n                src=local_path,\n                dst=destination_path,\n                ignore=ignore_func,\n                dirs_exist_ok=True,\n            )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        path: Path = self._resolve_path(path)\n\n        # Check if the path exists\n        if not path.exists():\n            raise ValueError(f\"Path {path} does not exist.\")\n\n        # Validate that its a file\n        if not path.is_file():\n            raise ValueError(f\"Path {path} is not a file.\")\n\n        async with await anyio.open_file(str(path), mode=\"rb\") as f:\n            content = await f.read()\n\n        return content\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        path: Path = self._resolve_path(path)\n\n        # Construct the path if it does not exist\n        path.parent.mkdir(exist_ok=True, parents=True)\n\n        # Check if the file already exists\n        if path.exists() and not path.is_file():\n            raise ValueError(f\"Path {path} already exists and is not a file.\")\n\n        async with await anyio.open_file(path, mode=\"wb\") as f:\n            await f.write(content)\n        # Leave path stringify to the OS\n        return str(path)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a directory from one place to another on the local filesystem.</p> <p>Defaults to copying the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: str = None, local_path: str = None\n) -&gt; None:\n    \"\"\"\n    Copies a directory from one place to another on the local filesystem.\n\n    Defaults to copying the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    if not from_path:\n        from_path = Path(self.basepath).expanduser().resolve()\n    else:\n        from_path = self._resolve_path(from_path)\n\n    if not local_path:\n        local_path = Path(\".\").resolve()\n    else:\n        local_path = Path(local_path).resolve()\n\n    if from_path == local_path:\n        # If the paths are the same there is no need to copy\n        # and we avoid shutil.copytree raising an error\n        return\n\n    # .prefectignore exists in the original location, not the current location which\n    # is most likely temporary\n    if (from_path / Path(\".prefectignore\")).exists():\n        ignore_func = await self._get_ignore_func(\n            local_path=from_path, ignore_file=from_path / Path(\".prefectignore\")\n        )\n    else:\n        ignore_func = None\n\n    copytree(from_path, local_path, dirs_exist_ok=True, ignore=ignore_func)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.LocalFileSystem.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Copies a directory from one place to another on the local filesystem.</p> <p>Defaults to copying the entire contents of the current working directory to the block's basepath. An <code>ignore_file</code> path may be provided that can include gitignore style expressions for filepaths to ignore.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self, local_path: str = None, to_path: str = None, ignore_file: str = None\n) -&gt; None:\n    \"\"\"\n    Copies a directory from one place to another on the local filesystem.\n\n    Defaults to copying the entire contents of the current working directory to the block's basepath.\n    An `ignore_file` path may be provided that can include gitignore style expressions for filepaths to ignore.\n    \"\"\"\n    destination_path = self._resolve_path(to_path)\n\n    if not local_path:\n        local_path = Path(\".\").absolute()\n\n    if ignore_file:\n        ignore_func = await self._get_ignore_func(\n            local_path=local_path, ignore_file=ignore_file\n        )\n    else:\n        ignore_func = None\n\n    if local_path == destination_path:\n        pass\n    else:\n        copytree(\n            src=local_path,\n            dst=destination_path,\n            ignore=ignore_func,\n            dirs_exist_ok=True,\n        )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem","title":"<code>RemoteFileSystem</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a remote file system.</p> <p>Supports any remote file system supported by <code>fsspec</code>. The file system is specified using a protocol. For example, \"s3://my-bucket/my-folder/\" will use S3.</p> Example <p>Load stored remote file system config: <pre><code>from prefect.filesystems import RemoteFileSystem\n\nremote_file_system_block = RemoteFileSystem.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a remote file system.\n\n    Supports any remote file system supported by `fsspec`. The file system is specified\n    using a protocol. For example, \"s3://my-bucket/my-folder/\" will use S3.\n\n    Example:\n        Load stored remote file system config:\n        ```python\n        from prefect.filesystems import RemoteFileSystem\n\n        remote_file_system_block = RemoteFileSystem.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Remote File System\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/e86b41bc0f9c99ba9489abeee83433b43d5c9365-48x48.png\"\n    _documentation_url = (\n        \"https://docs.prefect.io/concepts/filesystems/#remote-file-system\"\n    )\n\n    basepath: str = Field(\n        default=...,\n        description=\"Default path for this block to write to.\",\n        examples=[\"s3://my-bucket/my-folder/\"],\n    )\n    settings: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional settings to pass through to fsspec.\",\n    )\n\n    # Cache for the configured fsspec file system used for access\n    _filesystem: fsspec.AbstractFileSystem = None\n\n    @validator(\"basepath\")\n    def check_basepath(cls, value):\n        return validate_basepath(value)\n\n    def _resolve_path(self, path: str) -&gt; str:\n        base_scheme, base_netloc, base_urlpath, _, _ = urllib.parse.urlsplit(\n            self.basepath\n        )\n        scheme, netloc, urlpath, _, _ = urllib.parse.urlsplit(path)\n\n        # Confirm that absolute paths are valid\n        if scheme:\n            if scheme != base_scheme:\n                raise ValueError(\n                    f\"Path {path!r} with scheme {scheme!r} must use the same scheme as\"\n                    f\" the base path {base_scheme!r}.\"\n                )\n\n        if netloc:\n            if (netloc != base_netloc) or not urlpath.startswith(base_urlpath):\n                raise ValueError(\n                    f\"Path {path!r} is outside of the base path {self.basepath!r}.\"\n                )\n\n        return f\"{self.basepath.rstrip('/')}/{urlpath.lstrip('/')}\"\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        if from_path is None:\n            from_path = str(self.basepath)\n        else:\n            from_path = self._resolve_path(from_path)\n\n        if local_path is None:\n            local_path = Path(\".\").absolute()\n\n        # validate that from_path has a trailing slash for proper fsspec behavior across versions\n        if not from_path.endswith(\"/\"):\n            from_path += \"/\"\n\n        return self.filesystem.get(from_path, local_path, recursive=True)\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n        overwrite: bool = True,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        if to_path is None:\n            to_path = str(self.basepath)\n        else:\n            to_path = self._resolve_path(to_path)\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(\n                local_path, ignore_patterns, include_dirs=True\n            )\n\n        counter = 0\n        for f in Path(local_path).rglob(\"*\"):\n            relative_path = f.relative_to(local_path)\n            if included_files and str(relative_path) not in included_files:\n                continue\n\n            if to_path.endswith(\"/\"):\n                fpath = to_path + relative_path.as_posix()\n            else:\n                fpath = to_path + \"/\" + relative_path.as_posix()\n\n            if f.is_dir():\n                pass\n            else:\n                f = f.as_posix()\n                if overwrite:\n                    self.filesystem.put_file(f, fpath, overwrite=True)\n                else:\n                    self.filesystem.put_file(f, fpath)\n\n                counter += 1\n\n        return counter\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        path = self._resolve_path(path)\n\n        with self.filesystem.open(path, \"rb\") as file:\n            content = await run_sync_in_worker_thread(file.read)\n\n        return content\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        path = self._resolve_path(path)\n        dirpath = path[: path.rindex(\"/\")]\n\n        self.filesystem.makedirs(dirpath, exist_ok=True)\n\n        with self.filesystem.open(path, \"wb\") as file:\n            await run_sync_in_worker_thread(file.write, content)\n        return path\n\n    @property\n    def filesystem(self) -&gt; fsspec.AbstractFileSystem:\n        if not self._filesystem:\n            scheme, _, _, _, _ = urllib.parse.urlsplit(self.basepath)\n\n            try:\n                self._filesystem = fsspec.filesystem(scheme, **self.settings)\n            except ImportError as exc:\n                # The path is a remote file system that uses a lib that is not installed\n                raise RuntimeError(\n                    f\"File system created with scheme {scheme!r} from base path \"\n                    f\"{self.basepath!r} could not be created. \"\n                    \"You are likely missing a Python module required to use the given \"\n                    \"storage protocol.\"\n                ) from exc\n\n        return self._filesystem\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    if from_path is None:\n        from_path = str(self.basepath)\n    else:\n        from_path = self._resolve_path(from_path)\n\n    if local_path is None:\n        local_path = Path(\".\").absolute()\n\n    # validate that from_path has a trailing slash for proper fsspec behavior across versions\n    if not from_path.endswith(\"/\"):\n        from_path += \"/\"\n\n    return self.filesystem.get(from_path, local_path, recursive=True)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.RemoteFileSystem.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n    overwrite: bool = True,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    if to_path is None:\n        to_path = str(self.basepath)\n    else:\n        to_path = self._resolve_path(to_path)\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(\n            local_path, ignore_patterns, include_dirs=True\n        )\n\n    counter = 0\n    for f in Path(local_path).rglob(\"*\"):\n        relative_path = f.relative_to(local_path)\n        if included_files and str(relative_path) not in included_files:\n            continue\n\n        if to_path.endswith(\"/\"):\n            fpath = to_path + relative_path.as_posix()\n        else:\n            fpath = to_path + \"/\" + relative_path.as_posix()\n\n        if f.is_dir():\n            pass\n        else:\n            f = f.as_posix()\n            if overwrite:\n                self.filesystem.put_file(f, fpath, overwrite=True)\n            else:\n                self.filesystem.put_file(f, fpath)\n\n            counter += 1\n\n    return counter\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3","title":"<code>S3</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>S3Bucket</code> from the <code>prefect-aws</code> package, which offers enhanced functionality and better a better user experience.</p> <p>Store data as a file on AWS S3.</p> Example <p>Load stored S3 config: <pre><code>from prefect.filesystems import S3\n\ns3_block = S3.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/filesystems.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\", help=\"Use the `S3Bucket` block from prefect-aws instead.\"\n)\nclass S3(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `S3Bucket` from the `prefect-aws` package, which offers enhanced functionality\n    and better a better user experience.\n\n    Store data as a file on AWS S3.\n\n    Example:\n        Load stored S3 config:\n        ```python\n        from prefect.filesystems import S3\n\n        s3_block = S3.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"S3\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#s3\"\n\n    bucket_path: str = Field(\n        default=...,\n        description=\"An S3 bucket path.\",\n        examples=[\"my-bucket/a-directory-within\"],\n    )\n    aws_access_key_id: Optional[SecretStr] = Field(\n        default=None,\n        title=\"AWS Access Key ID\",\n        description=\"Equivalent to the AWS_ACCESS_KEY_ID environment variable.\",\n        examples=[\"AKIAIOSFODNN7EXAMPLE\"],\n    )\n    aws_secret_access_key: Optional[SecretStr] = Field(\n        default=None,\n        title=\"AWS Secret Access Key\",\n        description=\"Equivalent to the AWS_SECRET_ACCESS_KEY environment variable.\",\n        examples=[\"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\"],\n    )\n\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"s3://{self.bucket_path}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.aws_access_key_id:\n            settings[\"key\"] = self.aws_access_key_id.get_secret_value()\n        if self.aws_secret_access_key:\n            settings[\"secret\"] = self.aws_secret_access_key.get_secret_value()\n        self._remote_file_system = RemoteFileSystem(\n            basepath=f\"s3://{self.bucket_path}\", settings=settings\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path, to_path=to_path, ignore_file=ignore_file\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory.</p> <p>Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.S3.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory.</p> <p>Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path, to_path=to_path, ignore_file=ignore_file\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB","title":"<code>SMB</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Store data as a file on a SMB share.</p> Example <p>Load stored SMB config:</p> <pre><code>from prefect.filesystems import SMB\nsmb_block = SMB.load(\"BLOCK_NAME\")\n</code></pre> Source code in <code>prefect/filesystems.py</code> <pre><code>class SMB(WritableFileSystem, WritableDeploymentStorage):\n    \"\"\"\n    Store data as a file on a SMB share.\n\n    Example:\n        Load stored SMB config:\n\n        ```python\n        from prefect.filesystems import SMB\n        smb_block = SMB.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"SMB\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/3f624663f7beb97d011d011bffd51ecf6c499efc-195x195.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/filesystems/#smb\"\n\n    share_path: str = Field(\n        default=...,\n        description=\"SMB target (requires &lt;SHARE&gt;, followed by &lt;PATH&gt;).\",\n        examples=[\"/SHARE/dir/subdir\"],\n    )\n    smb_username: Optional[SecretStr] = Field(\n        default=None,\n        title=\"SMB Username\",\n        description=\"Username with access to the target SMB SHARE.\",\n    )\n    smb_password: Optional[SecretStr] = Field(\n        default=None, title=\"SMB Password\", description=\"Password for SMB access.\"\n    )\n    smb_host: str = Field(\n        default=..., tile=\"SMB server/hostname\", description=\"SMB server/hostname.\"\n    )\n    smb_port: Optional[int] = Field(\n        default=None, title=\"SMB port\", description=\"SMB port (default: 445).\"\n    )\n\n    _remote_file_system: RemoteFileSystem = None\n\n    @property\n    def basepath(self) -&gt; str:\n        return f\"smb://{self.smb_host.rstrip('/')}/{self.share_path.lstrip('/')}\"\n\n    @property\n    def filesystem(self) -&gt; RemoteFileSystem:\n        settings = {}\n        if self.smb_username:\n            settings[\"username\"] = self.smb_username.get_secret_value()\n        if self.smb_password:\n            settings[\"password\"] = self.smb_password.get_secret_value()\n        if self.smb_host:\n            settings[\"host\"] = self.smb_host\n        if self.smb_port:\n            settings[\"port\"] = self.smb_port\n        self._remote_file_system = RemoteFileSystem(\n            basepath=f\"smb://{self.smb_host.rstrip('/')}/{self.share_path.lstrip('/')}\",\n            settings=settings,\n        )\n        return self._remote_file_system\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; bytes:\n        \"\"\"\n        Downloads a directory from a given remote path to a local directory.\n        Defaults to downloading the entire contents of the block's basepath to the current working directory.\n        \"\"\"\n        return await self.filesystem.get_directory(\n            from_path=from_path, local_path=local_path\n        )\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to a remote directory.\n        Defaults to uploading the entire contents of the current working directory to the block's basepath.\n        \"\"\"\n        return await self.filesystem.put_directory(\n            local_path=local_path,\n            to_path=to_path,\n            ignore_file=ignore_file,\n            overwrite=False,\n        )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        return await self.filesystem.read_path(path)\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        return await self.filesystem.write_path(path=path, content=content)\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads a directory from a given remote path to a local directory. Defaults to downloading the entire contents of the block's basepath to the current working directory.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; bytes:\n    \"\"\"\n    Downloads a directory from a given remote path to a local directory.\n    Defaults to downloading the entire contents of the block's basepath to the current working directory.\n    \"\"\"\n    return await self.filesystem.get_directory(\n        from_path=from_path, local_path=local_path\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/filesystems/#prefect.filesystems.SMB.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to a remote directory. Defaults to uploading the entire contents of the current working directory to the block's basepath.</p> Source code in <code>prefect/filesystems.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to a remote directory.\n    Defaults to uploading the entire contents of the current working directory to the block's basepath.\n    \"\"\"\n    return await self.filesystem.put_directory(\n        local_path=local_path,\n        to_path=to_path,\n        ignore_file=ignore_file,\n        overwrite=False,\n    )\n</code></pre>","tags":["Python API","filesystems","LocalFileSystem","RemoteFileSystem"]},{"location":"api-ref/prefect/flow_runs/","title":"prefect.flow_runs","text":"","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flow_runs/#prefect.flow_runs","title":"<code>prefect.flow_runs</code>","text":"","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flow_runs/#prefect.flow_runs.wait_for_flow_run","title":"<code>wait_for_flow_run</code>  <code>async</code>","text":"<p>Waits for the prefect flow run to finish and returns the FlowRun</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run ID for the flow run to wait for.</p> required <code>timeout</code> <code>Optional[int]</code> <p>The wait timeout in seconds. Defaults to 10800 (3 hours).</p> <code>10800</code> <code>poll_interval</code> <code>int</code> <p>The poll interval in seconds. Defaults to 5.</p> <code>5</code> <p>Returns:</p> Name Type Description <code>FlowRun</code> <code>FlowRun</code> <p>The finished flow run.</p> <p>Raises:</p> Type Description <code>FlowWaitTimeout</code> <p>If flow run goes over the timeout.</p> <p>Examples:</p> <p>Create a flow run for a deployment and wait for it to finish:     <pre><code>import asyncio\n\nfrom prefect import get_client\nfrom prefect.flow_runs import wait_for_flow_run\n\nasync def main():\n    async with get_client() as client:\n        flow_run = await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n        flow_run = await wait_for_flow_run(flow_run_id=flow_run.id)\n        print(flow_run.state)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre></p> <p>Trigger multiple flow runs and wait for them to finish:     <pre><code>import asyncio\n\nfrom prefect import get_client\nfrom prefect.flow_runs import wait_for_flow_run\n\nasync def main(num_runs: int):\n    async with get_client() as client:\n        flow_runs = [\n            await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n            for _\n            in range(num_runs)\n        ]\n        coros = [wait_for_flow_run(flow_run_id=flow_run.id) for flow_run in flow_runs]\n        finished_flow_runs = await asyncio.gather(*coros)\n        print([flow_run.state for flow_run in finished_flow_runs])\n\nif __name__ == \"__main__\":\n    asyncio.run(main(num_runs=10))\n</code></pre></p> Source code in <code>prefect/flow_runs.py</code> <pre><code>@inject_client\nasync def wait_for_flow_run(\n    flow_run_id: UUID,\n    timeout: Optional[int] = 10800,\n    poll_interval: int = 5,\n    client: Optional[PrefectClient] = None,\n    log_states: bool = False,\n) -&gt; FlowRun:\n    \"\"\"\n    Waits for the prefect flow run to finish and returns the FlowRun\n\n    Args:\n        flow_run_id: The flow run ID for the flow run to wait for.\n        timeout: The wait timeout in seconds. Defaults to 10800 (3 hours).\n        poll_interval: The poll interval in seconds. Defaults to 5.\n\n    Returns:\n        FlowRun: The finished flow run.\n\n    Raises:\n        prefect.exceptions.FlowWaitTimeout: If flow run goes over the timeout.\n\n    Examples:\n        Create a flow run for a deployment and wait for it to finish:\n            ```python\n            import asyncio\n\n            from prefect import get_client\n            from prefect.flow_runs import wait_for_flow_run\n\n            async def main():\n                async with get_client() as client:\n                    flow_run = await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n                    flow_run = await wait_for_flow_run(flow_run_id=flow_run.id)\n                    print(flow_run.state)\n\n            if __name__ == \"__main__\":\n                asyncio.run(main())\n\n            ```\n\n        Trigger multiple flow runs and wait for them to finish:\n            ```python\n            import asyncio\n\n            from prefect import get_client\n            from prefect.flow_runs import wait_for_flow_run\n\n            async def main(num_runs: int):\n                async with get_client() as client:\n                    flow_runs = [\n                        await client.create_flow_run_from_deployment(deployment_id=\"my-deployment-id\")\n                        for _\n                        in range(num_runs)\n                    ]\n                    coros = [wait_for_flow_run(flow_run_id=flow_run.id) for flow_run in flow_runs]\n                    finished_flow_runs = await asyncio.gather(*coros)\n                    print([flow_run.state for flow_run in finished_flow_runs])\n\n            if __name__ == \"__main__\":\n                asyncio.run(main(num_runs=10))\n\n            ```\n    \"\"\"\n    assert client is not None, \"Client injection failed\"\n    logger = get_logger()\n    with anyio.move_on_after(timeout):\n        while True:\n            flow_run = await client.read_flow_run(flow_run_id)\n            flow_state = flow_run.state\n            if log_states:\n                logger.info(f\"Flow run is in state {flow_run.state.name!r}\")\n            if flow_state and flow_state.is_final():\n                return flow_run\n            await anyio.sleep(poll_interval)\n    raise FlowRunWaitTimeout(\n        f\"Flow run with ID {flow_run_id} exceeded watch timeout of {timeout} seconds\"\n    )\n</code></pre>","tags":["Python API","flow-runs"]},{"location":"api-ref/prefect/flows/","title":"prefect.flows","text":"","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows","title":"<code>prefect.flows</code>","text":"<p>Module containing the base workflow class and decorator - for most use cases, using the <code>@flow</code> decorator is preferred.</p>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>Generic[P, R]</code></p> <p>A Prefect workflow definition.</p> <p>Note</p> <p>We recommend using the <code>@flow</code> decorator for most use-cases.</p> <p>Wraps a function with an entrypoint to the Prefect engine. To preserve the input and output types, we use the generic type variables <code>P</code> and <code>R</code> for \"Parameters\" and \"Returns\" respectively.</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable[P, R]</code> <p>The function defining the workflow.</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional version string for the flow; if not provided, we will attempt to create a version string as a hash of the file containing the wrapped function; if the file cannot be located, the version will be null.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>task_runner</code> <code>Union[Type[BaseTaskRunner], BaseTaskRunner]</code> <p>An optional task runner to use for task execution within the flow; if not provided, a <code>ConcurrentTaskRunner</code> will be used.</p> <code>ConcurrentTaskRunner</code> <code>description</code> <code>str</code> <p>An optional string description for the flow; if not provided, the description will be pulled from the docstring for the decorated function.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>By default, parameters passed to flows are validated by Pydantic. This will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type; for example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p> <code>True</code> <code>retries</code> <code>Optional[int]</code> <p>An optional number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[int, float]]</code> <p>An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this flow should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this flow. This value will be used as the default for any tasks in this flow. If not provided, the local file system will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this flow for persistence. This value will be used as the default for any tasks in this flow. If not provided, the value of <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a completed state.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a cancelling state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a crashed state.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of callables to run when the flow enters a running state.</p> <code>None</code> Source code in <code>prefect/flows.py</code> <pre><code>@PrefectObjectRegistry.register_instances\nclass Flow(Generic[P, R]):\n    \"\"\"\n    A Prefect workflow definition.\n\n    !!! note\n        We recommend using the [`@flow` decorator][prefect.flows.flow] for most use-cases.\n\n    Wraps a function with an entrypoint to the Prefect engine. To preserve the input\n    and output types, we use the generic type variables `P` and `R` for \"Parameters\" and\n    \"Returns\" respectively.\n\n    Args:\n        fn: The function defining the workflow.\n        name: An optional name for the flow; if not provided, the name will be inferred\n            from the given function.\n        version: An optional version string for the flow; if not provided, we will\n            attempt to create a version string as a hash of the file containing the\n            wrapped function; if the file cannot be located, the version will be null.\n        flow_run_name: An optional name to distinguish runs of this flow; this name can\n            be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        task_runner: An optional task runner to use for task execution within the flow;\n            if not provided, a `ConcurrentTaskRunner` will be used.\n        description: An optional string description for the flow; if not provided, the\n            description will be pulled from the docstring for the decorated function.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the flow. If the flow exceeds this runtime, it will be marked as failed.\n            Flow execution may continue until the next task is called.\n        validate_parameters: By default, parameters passed to flows are validated by\n            Pydantic. This will check that input values conform to the annotated types\n            on the function. Where possible, values will be coerced into the correct\n            type; for example, if a parameter is defined as `x: int` and \"5\" is passed,\n            it will be resolved to `5`. If set to `False`, no validation will be\n            performed on flow parameters.\n        retries: An optional number of times to retry on flow run failure.\n        retry_delay_seconds: An optional number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        persist_result: An optional toggle indicating whether the result of this flow\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this flow.\n            This value will be used as the default for any tasks in this flow.\n            If not provided, the local file system will be used unless called as\n            a subflow, at which point the default will be loaded from the parent flow.\n        result_serializer: An optional serializer to use to serialize the result of this\n            flow for persistence. This value will be used as the default for any tasks\n            in this flow. If not provided, the value of `PREFECT_RESULTS_DEFAULT_SERIALIZER`\n            will be used unless called as a subflow, at which point the default will be\n            loaded from the parent flow.\n        on_failure: An optional list of callables to run when the flow enters a failed state.\n        on_completion: An optional list of callables to run when the flow enters a completed state.\n        on_cancellation: An optional list of callables to run when the flow enters a cancelling state.\n        on_crashed: An optional list of callables to run when the flow enters a crashed state.\n        on_running: An optional list of callables to run when the flow enters a running state.\n    \"\"\"\n\n    # NOTE: These parameters (types, defaults, and docstrings) should be duplicated\n    #       exactly in the @flow decorator\n    def __init__(\n        self,\n        fn: Callable[P, R],\n        name: Optional[str] = None,\n        version: Optional[str] = None,\n        flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[Union[int, float]] = None,\n        task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = ConcurrentTaskRunner,\n        description: str = None,\n        timeout_seconds: Union[int, float] = None,\n        validate_parameters: bool = True,\n        persist_result: Optional[bool] = None,\n        result_storage: Optional[ResultStorage] = None,\n        result_serializer: Optional[ResultSerializer] = None,\n        cache_result_in_memory: bool = True,\n        log_prints: Optional[bool] = None,\n        on_completion: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_cancellation: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    ):\n        if name is not None and not isinstance(name, str):\n            raise TypeError(\n                \"Expected string for flow parameter 'name'; got {} instead. {}\".format(\n                    type(name).__name__,\n                    (\n                        \"Perhaps you meant to call it? e.g.\"\n                        \" '@flow(name=get_flow_run_name())'\"\n                        if callable(name)\n                        else \"\"\n                    ),\n                )\n            )\n\n        # Validate if hook passed is list and contains callables\n        hook_categories = [\n            on_completion,\n            on_failure,\n            on_cancellation,\n            on_crashed,\n            on_running,\n        ]\n        hook_names = [\n            \"on_completion\",\n            \"on_failure\",\n            \"on_cancellation\",\n            \"on_crashed\",\n            \"on_running\",\n        ]\n        for hooks, hook_name in zip(hook_categories, hook_names):\n            if hooks is not None:\n                if not hooks:\n                    raise ValueError(f\"Empty list passed for '{hook_name}'\")\n                try:\n                    hooks = list(hooks)\n                except TypeError:\n                    raise TypeError(\n                        f\"Expected iterable for '{hook_name}'; got\"\n                        f\" {type(hooks).__name__} instead. Please provide a list of\"\n                        f\" hooks to '{hook_name}':\\n\\n\"\n                        f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                        \" my_flow():\\n\\tpass\"\n                    )\n\n                for hook in hooks:\n                    if not callable(hook):\n                        raise TypeError(\n                            f\"Expected callables in '{hook_name}'; got\"\n                            f\" {type(hook).__name__} instead. Please provide a list of\"\n                            f\" hooks to '{hook_name}':\\n\\n\"\n                            f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                            \" my_flow():\\n\\tpass\"\n                        )\n\n        if not callable(fn):\n            raise TypeError(\"'fn' must be callable\")\n\n        # Validate name if given\n        if name:\n            raise_on_name_with_banned_characters(name)\n\n        self.name = name or fn.__name__.replace(\"_\", \"-\")\n\n        if flow_run_name is not None:\n            if not isinstance(flow_run_name, str) and not callable(flow_run_name):\n                raise TypeError(\n                    \"Expected string or callable for 'flow_run_name'; got\"\n                    f\" {type(flow_run_name).__name__} instead.\"\n                )\n        self.flow_run_name = flow_run_name\n\n        task_runner = task_runner or ConcurrentTaskRunner()\n        self.task_runner = (\n            task_runner() if isinstance(task_runner, type) else task_runner\n        )\n\n        self.log_prints = log_prints\n\n        self.description = description or inspect.getdoc(fn)\n        update_wrapper(self, fn)\n        self.fn = fn\n        self.isasync = is_async_fn(self.fn)\n\n        raise_for_reserved_arguments(self.fn, [\"return_state\", \"wait_for\"])\n\n        # Version defaults to a hash of the function's file\n        flow_file = inspect.getsourcefile(self.fn)\n        if not version:\n            try:\n                version = file_hash(flow_file)\n            except (FileNotFoundError, TypeError, OSError):\n                pass  # `getsourcefile` can return null values and \"&lt;stdin&gt;\" for objects in repls\n        self.version = version\n\n        self.timeout_seconds = float(timeout_seconds) if timeout_seconds else None\n\n        # FlowRunPolicy settings\n        # TODO: We can instantiate a `FlowRunPolicy` and add Pydantic bound checks to\n        #       validate that the user passes positive numbers here\n        self.retries = (\n            retries if retries is not None else PREFECT_FLOW_DEFAULT_RETRIES.value()\n        )\n\n        self.retry_delay_seconds = (\n            retry_delay_seconds\n            if retry_delay_seconds is not None\n            else PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS.value()\n        )\n\n        self.parameters = parameter_schema(self.fn)\n        self.should_validate_parameters = validate_parameters\n\n        if self.should_validate_parameters:\n            # Try to create the validated function now so that incompatibility can be\n            # raised at declaration time rather than at runtime\n            # We cannot, however, store the validated function on the flow because it\n            # is not picklable in some environments\n            try:\n                ValidatedFunction(self.fn, config={\"arbitrary_types_allowed\": True})\n            except pydantic.ConfigError as exc:\n                raise ValueError(\n                    \"Flow function is not compatible with `validate_parameters`. \"\n                    \"Disable validation or change the argument names.\"\n                ) from exc\n\n        self.persist_result = persist_result\n        self.result_storage = result_storage\n        self.result_serializer = result_serializer\n        self.cache_result_in_memory = cache_result_in_memory\n        self.on_completion = on_completion\n        self.on_failure = on_failure\n        self.on_cancellation = on_cancellation\n        self.on_crashed = on_crashed\n        self.on_running = on_running\n\n        # Used for flows loaded from remote storage\n        self._storage: Optional[RunnerStorage] = None\n        self._entrypoint: Optional[str] = None\n\n        module = fn.__module__\n        if module in (\"__main__\", \"__prefect_loader__\"):\n            module_name = inspect.getfile(fn)\n            module = module_name if module_name != \"__main__\" else module\n\n        self._entrypoint = f\"{module}:{fn.__name__}\"\n\n    def with_options(\n        self,\n        *,\n        name: str = None,\n        version: str = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[Union[int, float]] = None,\n        description: str = None,\n        flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n        task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = None,\n        timeout_seconds: Union[int, float] = None,\n        validate_parameters: bool = None,\n        persist_result: Optional[bool] = NotSet,\n        result_storage: Optional[ResultStorage] = NotSet,\n        result_serializer: Optional[ResultSerializer] = NotSet,\n        cache_result_in_memory: bool = None,\n        log_prints: Optional[bool] = NotSet,\n        on_completion: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_cancellation: Optional[\n            List[Callable[[FlowSchema, FlowRun, State], None]]\n        ] = None,\n        on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n        on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Create a new flow from the current object, updating provided options.\n\n        Args:\n            name: A new name for the flow.\n            version: A new version for the flow.\n            description: A new description for the flow.\n            flow_run_name: An optional name to distinguish runs of this flow; this name\n                can be provided as a string template with the flow's parameters as variables,\n                or a function that returns a string.\n            task_runner: A new task runner for the flow.\n            timeout_seconds: A new number of seconds to fail the flow after if still\n                running.\n            validate_parameters: A new value indicating if flow calls should validate\n                given parameters.\n            retries: A new number of times to retry on flow run failure.\n            retry_delay_seconds: A new number of seconds to wait before retrying the\n                flow after failure. This is only applicable if `retries` is nonzero.\n            persist_result: A new option for enabling or disabling result persistence.\n            result_storage: A new storage type to use for results.\n            result_serializer: A new serializer to use for results.\n            cache_result_in_memory: A new value indicating if the flow's result should\n                be cached in memory.\n            on_failure: A new list of callables to run when the flow enters a failed state.\n            on_completion: A new list of callables to run when the flow enters a completed state.\n            on_cancellation: A new list of callables to run when the flow enters a cancelling state.\n            on_crashed: A new list of callables to run when the flow enters a crashed state.\n            on_running: A new list of callables to run when the flow enters a running state.\n\n        Returns:\n            A new `Flow` instance.\n\n        Examples:\n\n            Create a new flow from an existing flow and update the name:\n\n            &gt;&gt;&gt; @flow(name=\"My flow\")\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\n            Create a new flow from an existing flow, update the task runner, and call\n            it without an intermediate variable:\n\n            &gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow(x, y):\n            &gt;&gt;&gt;     return x + y\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n            &gt;&gt;&gt; assert state.result() == 4\n\n        \"\"\"\n        new_flow = Flow(\n            fn=self.fn,\n            name=name or self.name,\n            description=description or self.description,\n            flow_run_name=flow_run_name or self.flow_run_name,\n            version=version or self.version,\n            task_runner=task_runner or self.task_runner,\n            retries=retries if retries is not None else self.retries,\n            retry_delay_seconds=(\n                retry_delay_seconds\n                if retry_delay_seconds is not None\n                else self.retry_delay_seconds\n            ),\n            timeout_seconds=(\n                timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n            ),\n            validate_parameters=(\n                validate_parameters\n                if validate_parameters is not None\n                else self.should_validate_parameters\n            ),\n            persist_result=(\n                persist_result if persist_result is not NotSet else self.persist_result\n            ),\n            result_storage=(\n                result_storage if result_storage is not NotSet else self.result_storage\n            ),\n            result_serializer=(\n                result_serializer\n                if result_serializer is not NotSet\n                else self.result_serializer\n            ),\n            cache_result_in_memory=(\n                cache_result_in_memory\n                if cache_result_in_memory is not None\n                else self.cache_result_in_memory\n            ),\n            log_prints=log_prints if log_prints is not NotSet else self.log_prints,\n            on_completion=on_completion or self.on_completion,\n            on_failure=on_failure or self.on_failure,\n            on_cancellation=on_cancellation or self.on_cancellation,\n            on_crashed=on_crashed or self.on_crashed,\n            on_running=on_running or self.on_running,\n        )\n        new_flow._storage = self._storage\n        new_flow._entrypoint = self._entrypoint\n        return new_flow\n\n    def validate_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Validate parameters for compatibility with the flow by attempting to cast the inputs to the\n        associated types specified by the function's type annotations.\n\n        Returns:\n            A new dict of parameters that have been cast to the appropriate types\n\n        Raises:\n            ParameterTypeError: if the provided parameters are not valid\n        \"\"\"\n        args, kwargs = parameters_to_args_kwargs(self.fn, parameters)\n\n        if HAS_PYDANTIC_V2:\n            has_v1_models = any(isinstance(o, V1BaseModel) for o in args) or any(\n                isinstance(o, V1BaseModel) for o in kwargs.values()\n            )\n            has_v2_types = any(is_v2_type(o) for o in args) or any(\n                is_v2_type(o) for o in kwargs.values()\n            )\n\n            if has_v1_models and has_v2_types:\n                raise ParameterTypeError(\n                    \"Cannot mix Pydantic v1 and v2 types as arguments to a flow.\"\n                )\n\n            if has_v1_models:\n                validated_fn = V1ValidatedFunction(\n                    self.fn, config={\"arbitrary_types_allowed\": True}\n                )\n            else:\n                validated_fn = V2ValidatedFunction(\n                    self.fn, config={\"arbitrary_types_allowed\": True}\n                )\n\n        else:\n            validated_fn = ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n\n        try:\n            model = validated_fn.init_model_instance(*args, **kwargs)\n        except pydantic.ValidationError as exc:\n            # We capture the pydantic exception and raise our own because the pydantic\n            # exception is not picklable when using a cythonized pydantic installation\n            raise ParameterTypeError.from_validation_error(exc) from None\n        except V2ValidationError as exc:\n            # We capture the pydantic exception and raise our own because the pydantic\n            # exception is not picklable when using a cythonized pydantic installation\n            raise ParameterTypeError.from_validation_error(exc) from None\n\n        # Get the updated parameter dict with cast values from the model\n        cast_parameters = {\n            k: v\n            for k, v in model._iter()\n            if k in model.__fields_set__ or model.__fields__[k].default_factory\n        }\n        return cast_parameters\n\n    def serialize_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Convert parameters to a serializable form.\n\n        Uses FastAPI's `jsonable_encoder` to convert to JSON compatible objects without\n        converting everything directly to a string. This maintains basic types like\n        integers during API roundtrips.\n        \"\"\"\n        serialized_parameters = {}\n        for key, value in parameters.items():\n            try:\n                serialized_parameters[key] = jsonable_encoder(value)\n            except (TypeError, ValueError):\n                logger.debug(\n                    f\"Parameter {key!r} for flow {self.name!r} is of unserializable \"\n                    f\"type {type(value).__name__!r} and will not be stored \"\n                    \"in the backend.\"\n                )\n                serialized_parameters[key] = f\"&lt;{type(value).__name__}&gt;\"\n        return serialized_parameters\n\n    @sync_compatible\n    @deprecated_parameter(\n        \"schedule\",\n        start_date=\"Mar 2024\",\n        when=lambda p: p is not None,\n        help=\"Use `schedules` instead.\",\n    )\n    @deprecated_parameter(\n        \"is_schedule_active\",\n        start_date=\"Mar 2024\",\n        when=lambda p: p is not None,\n        help=\"Use `paused` instead.\",\n    )\n    async def to_deployment(\n        self,\n        name: str,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Creates a runner deployment object for this flow.\n\n        Args:\n            name: The name to give the created deployment.\n            interval: An interval on which to execute the new deployment. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this deployment.\n            rrule: An rrule schedule of when to execute runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options such as `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n\n        Examples:\n            Prepare two deployments and serve them:\n\n            ```python\n            from prefect import flow, serve\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            @flow\n            def my_other_flow(name):\n                print(f\"goodbye {name}\")\n\n            if __name__ == \"__main__\":\n                hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n                bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n                serve(hello_deploy, bye_deploy)\n            ```\n        \"\"\"\n        from prefect.deployments.runner import RunnerDeployment\n\n        if not name.endswith(\".py\"):\n            raise_on_name_with_banned_characters(name)\n        if self._storage and self._entrypoint:\n            return await RunnerDeployment.from_storage(\n                storage=self._storage,\n                entrypoint=self._entrypoint,\n                name=name,\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                paused=paused,\n                schedules=schedules,\n                schedule=schedule,\n                is_schedule_active=is_schedule_active,\n                tags=tags,\n                triggers=triggers,\n                parameters=parameters or {},\n                description=description,\n                version=version,\n                enforce_parameter_schema=enforce_parameter_schema,\n                work_pool_name=work_pool_name,\n                work_queue_name=work_queue_name,\n                job_variables=job_variables,\n            )\n        else:\n            return RunnerDeployment.from_flow(\n                self,\n                name=name,\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                paused=paused,\n                schedules=schedules,\n                schedule=schedule,\n                is_schedule_active=is_schedule_active,\n                tags=tags,\n                triggers=triggers,\n                parameters=parameters or {},\n                description=description,\n                version=version,\n                enforce_parameter_schema=enforce_parameter_schema,\n                work_pool_name=work_pool_name,\n                work_queue_name=work_queue_name,\n                job_variables=job_variables,\n                entrypoint_type=entrypoint_type,\n            )\n\n    @sync_compatible\n    async def serve(\n        self,\n        name: Optional[str] = None,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        parameters: Optional[dict] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        pause_on_shutdown: bool = True,\n        print_starting_message: bool = True,\n        limit: Optional[int] = None,\n        webserver: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ):\n        \"\"\"\n        Creates a deployment for this flow and starts a runner to monitor for scheduled work.\n\n        Args:\n            name: The name to give the created deployment. Defaults to the name of the flow.\n            interval: An interval on which to execute the deployment. Accepts a number or a\n                timedelta object to create a single schedule. If a number is given, it will be\n                interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n                multiple schedules.\n            cron: A cron schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of cron schedule strings to create multiple schedules.\n            rrule: An rrule schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of rrule schedule strings to create multiple schedules.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment. Used to\n                define additional scheduling options such as `timezone`.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            pause_on_shutdown: If True, provided schedule will be paused when the serve function is stopped.\n                If False, the schedules will continue running.\n            print_starting_message: Whether or not to print the starting message when flow is served.\n            limit: The maximum number of runs that can be executed concurrently.\n            webserver: Whether or not to start a monitoring webserver for this flow.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n\n        Examples:\n            Serve a flow:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.serve(\"example-deployment\")\n            ```\n\n            Serve a flow and run it every hour:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.serve(\"example-deployment\", interval=3600)\n            ```\n        \"\"\"\n        from prefect.runner import Runner\n\n        if not name:\n            name = self.name\n        else:\n            # Handling for my_flow.serve(__file__)\n            # Will set name to name of file where my_flow.serve() without the extension\n            # Non filepath strings will pass through unchanged\n            name = Path(name).stem\n\n        runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown, limit=limit)\n        deployment_id = await runner.add_flow(\n            self,\n            name=name,\n            triggers=triggers,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            entrypoint_type=entrypoint_type,\n        )\n        if print_starting_message:\n            help_message = (\n                f\"[green]Your flow {self.name!r} is being served and polling for\"\n                \" scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the\"\n                \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n                f\" '{self.name}/{name}'\\n[/]\"\n            )\n            if PREFECT_UI_URL:\n                help_message += (\n                    \"\\nYou can also run your flow via the Prefect UI:\"\n                    f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n                )\n\n            console = Console()\n            console.print(help_message, soft_wrap=True)\n        await runner.start(webserver=webserver)\n\n    @classmethod\n    @sync_compatible\n    async def from_source(\n        cls: Type[F],\n        source: Union[str, RunnerStorage, ReadableDeploymentStorage],\n        entrypoint: str,\n    ) -&gt; F:\n        \"\"\"\n        Loads a flow from a remote source.\n\n        Args:\n            source: Either a URL to a git repository or a storage object.\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n\n        Returns:\n            A new `Flow` instance.\n\n        Examples:\n            Load a flow from a public git repository:\n\n\n            ```python\n            from prefect import flow\n            from prefect.runner.storage import GitRepository\n            from prefect.blocks.system import Secret\n\n            my_flow = flow.from_source(\n                source=\"https://github.com/org/repo.git\",\n                entrypoint=\"flows.py:my_flow\",\n            )\n\n            my_flow()\n            ```\n\n            Load a flow from a private git repository using an access token stored in a `Secret` block:\n\n            ```python\n            from prefect import flow\n            from prefect.runner.storage import GitRepository\n            from prefect.blocks.system import Secret\n\n            my_flow = flow.from_source(\n                source=GitRepository(\n                    url=\"https://github.com/org/repo.git\",\n                    credentials={\"access_token\": Secret.load(\"github-access-token\")}\n                ),\n                entrypoint=\"flows.py:my_flow\",\n            )\n\n            my_flow()\n            ```\n        \"\"\"\n        if isinstance(source, str):\n            storage = create_storage_from_source(source)\n        elif isinstance(source, RunnerStorage):\n            storage = source\n        elif hasattr(source, \"get_directory\"):\n            storage = BlockStorageAdapter(source)\n        else:\n            raise TypeError(\n                f\"Unsupported source type {type(source).__name__!r}. Please provide a\"\n                \" URL to remote storage or a storage object.\"\n            )\n\n        with tempfile.TemporaryDirectory() as tmpdir:\n            if not isinstance(storage, LocalStorage):\n                storage.set_base_path(Path(tmpdir))\n                await storage.pull_code()\n\n            full_entrypoint = str(storage.destination / entrypoint)\n            flow: \"Flow\" = await from_async.wait_for_call_in_new_thread(\n                create_call(load_flow_from_entrypoint, full_entrypoint)\n            )\n            flow._storage = storage\n            flow._entrypoint = entrypoint\n\n        return flow\n\n    @sync_compatible\n    async def deploy(\n        self,\n        name: str,\n        work_pool_name: Optional[str] = None,\n        image: Optional[Union[str, DeploymentImage]] = None,\n        build: bool = True,\n        push: bool = True,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[dict] = None,\n        interval: Optional[Union[int, float, datetime.timedelta]] = None,\n        cron: Optional[str] = None,\n        rrule: Optional[str] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[List[MinimalDeploymentSchedule]] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        parameters: Optional[dict] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n        print_next_steps: bool = True,\n        ignore_warnings: bool = False,\n    ) -&gt; UUID:\n        \"\"\"\n        Deploys a flow to run on dynamic infrastructure via a work pool.\n\n        By default, calling this method will build a Docker image for the flow, push it to a registry,\n        and create a deployment via the Prefect API that will run the flow on the given schedule.\n\n        If you want to use an existing image, you can pass `build=False` to skip building and pushing\n        an image.\n\n        Args:\n            name: The name to give the created deployment.\n            work_pool_name: The name of the work pool to use for this deployment. Defaults to\n                the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n            image: The name of the Docker image to build, including the registry and\n                repository. Pass a DeploymentImage instance to customize the Dockerfile used\n                and build arguments.\n            build: Whether or not to build a new image for the flow. If False, the provided\n                image will be used as-is and pulled at runtime.\n            push: Whether or not to skip pushing the built image to a registry.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n            interval: An interval on which to execute the deployment. Accepts a number or a\n                timedelta object to create a single schedule. If a number is given, it will be\n                interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n                multiple schedules.\n            cron: A cron schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of cron schedule strings to create multiple schedules.\n            rrule: An rrule schedule string of when to execute runs of this deployment.\n                Also accepts an iterable of rrule schedule strings to create multiple schedules.\n            triggers: A list of triggers that will kick off runs of this deployment.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object defining when to execute runs of this deployment. Used to\n                define additional scheduling options like `timezone`.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            parameters: A dictionary of default parameter values to pass to runs of this deployment.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for the created deployment.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n            print_next_steps_message: Whether or not to print a message with next steps\n                after deploying the deployments.\n            ignore_warnings: Whether or not to ignore warnings about the work pool type.\n\n        Returns:\n            The ID of the created/updated deployment.\n\n        Examples:\n            Deploy a local flow to a work pool:\n\n            ```python\n            from prefect import flow\n\n            @flow\n            def my_flow(name):\n                print(f\"hello {name}\")\n\n            if __name__ == \"__main__\":\n                my_flow.deploy(\n                    \"example-deployment\",\n                    work_pool_name=\"my-work-pool\",\n                    image=\"my-repository/my-image:dev\",\n                )\n            ```\n\n            Deploy a remotely stored flow to a work pool:\n\n            ```python\n            from prefect import flow\n\n            if __name__ == \"__main__\":\n                flow.from_source(\n                    source=\"https://github.com/org/repo.git\",\n                    entrypoint=\"flows.py:my_flow\",\n                ).deploy(\n                    \"example-deployment\",\n                    work_pool_name=\"my-work-pool\",\n                    image=\"my-repository/my-image:dev\",\n                )\n            ```\n        \"\"\"\n        work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n        try:\n            async with get_client() as client:\n                work_pool = await client.read_work_pool(work_pool_name)\n        except ObjectNotFound as exc:\n            raise ValueError(\n                f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n                \" deploying this flow.\"\n            ) from exc\n\n        deployment = await self.to_deployment(\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedules=schedules,\n            paused=paused,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            triggers=triggers,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n            entrypoint_type=entrypoint_type,\n        )\n\n        deployment_ids = await deploy(\n            deployment,\n            work_pool_name=work_pool_name,\n            image=image,\n            build=build,\n            push=push,\n            print_next_steps_message=False,\n            ignore_warnings=ignore_warnings,\n        )\n\n        if print_next_steps:\n            console = Console()\n            if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n                console.print(\n                    \"\\nTo execute flow runs from this deployment, start a worker in a\"\n                    \" separate terminal that pulls work from the\"\n                    f\" {work_pool_name!r} work pool:\"\n                )\n                console.print(\n                    f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                    style=\"blue\",\n                )\n            console.print(\n                \"\\nTo schedule a run for this deployment, use the following command:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect deployment run '{self.name}/{name}'\\n\",\n                style=\"blue\",\n            )\n            if PREFECT_UI_URL:\n                message = (\n                    \"\\nYou can also run your flow via the Prefect UI:\"\n                    f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\\n\"\n                )\n                console.print(message, soft_wrap=True)\n\n        return deployment_ids[0]\n\n    @overload\n    def __call__(self: \"Flow[P, NoReturn]\", *args: P.args, **kwargs: P.kwargs) -&gt; None:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, Coroutine[Any, Any, T]]\", *args: P.args, **kwargs: P.kwargs\n    ) -&gt; Awaitable[T]:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; T:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Flow[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def __call__(\n        self,\n        *args: \"P.args\",\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: \"P.kwargs\",\n    ):\n        \"\"\"\n        Run the flow and return its result.\n\n\n        Flow parameter values must be serializable by Pydantic.\n\n        If writing an async flow, this call must be awaited.\n\n        This will create a new flow run in the API.\n\n        Args:\n            *args: Arguments to run the flow with.\n            return_state: Return a Prefect State containing the result of the\n                flow run.\n            wait_for: Upstream task futures to wait for before starting the flow if called as a subflow\n            **kwargs: Keyword arguments to run the flow with.\n\n        Returns:\n            If `return_state` is False, returns the result of the flow run.\n            If `return_state` is True, returns the result of the flow run\n                wrapped in a Prefect State which provides error handling.\n\n        Examples:\n\n            Define a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow(name):\n            &gt;&gt;&gt;     print(f\"hello {name}\")\n            &gt;&gt;&gt;     return f\"goodbye {name}\"\n\n            Run a flow\n\n            &gt;&gt;&gt; my_flow(\"marvin\")\n            hello marvin\n            \"goodbye marvin\"\n\n            Run a flow with additional tags\n\n            &gt;&gt;&gt; from prefect import tags\n            &gt;&gt;&gt; with tags(\"db\", \"blue\"):\n            &gt;&gt;&gt;     my_flow(\"foo\")\n        \"\"\"\n        from prefect.engine import enter_flow_run_engine_from_flow_call\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return_type = \"state\" if return_state else \"result\"\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            # this is a subflow, for now return a single task and do not go further\n            # we can add support for exploring subflows for tasks in the future.\n            return track_viz_task(self.isasync, self.name, parameters)\n\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE.value():\n            from prefect.new_flow_engine import run_flow, run_flow_sync\n\n            run_kwargs = dict(\n                flow=self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n            )\n            if self.isasync:\n                # this returns an awaitable coroutine\n                return run_flow(**run_kwargs)\n            else:\n                return run_flow_sync(**run_kwargs)\n\n        return enter_flow_run_engine_from_flow_call(\n            self,\n            parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n        )\n\n    @overload\n    def _run(self: \"Flow[P, NoReturn]\", *args: P.args, **kwargs: P.kwargs) -&gt; State[T]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def _run(\n        self: \"Flow[P, Coroutine[Any, Any, T]]\", *args: P.args, **kwargs: P.kwargs\n    ) -&gt; Awaitable[T]:\n        ...\n\n    @overload\n    def _run(self: \"Flow[P, T]\", *args: P.args, **kwargs: P.kwargs) -&gt; State[T]:\n        ...\n\n    def _run(\n        self,\n        *args: \"P.args\",\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: \"P.kwargs\",\n    ):\n        \"\"\"\n        Run the flow and return its final state.\n\n        Examples:\n\n            Run a flow and get the returned result\n\n            &gt;&gt;&gt; state = my_flow._run(\"marvin\")\n            &gt;&gt;&gt; state.result()\n           \"goodbye marvin\"\n        \"\"\"\n        from prefect.engine import enter_flow_run_engine_from_flow_call\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return enter_flow_run_engine_from_flow_call(\n            self,\n            parameters,\n            wait_for=wait_for,\n            return_type=\"state\",\n        )\n\n    @sync_compatible\n    async def visualize(self, *args, **kwargs):\n        \"\"\"\n        Generates a graphviz object representing the current flow. In IPython notebooks,\n        it's rendered inline, otherwise in a new window as a PNG.\n\n        Raises:\n            - ImportError: If `graphviz` isn't installed.\n            - GraphvizExecutableNotFoundError: If the `dot` executable isn't found.\n            - FlowVisualizationError: If the flow can't be visualized for any other reason.\n        \"\"\"\n        if not PREFECT_UNIT_TEST_MODE:\n            warnings.warn(\n                \"`flow.visualize()` will execute code inside of your flow that is not\"\n                \" decorated with `@task` or `@flow`.\"\n            )\n\n        try:\n            with TaskVizTracker() as tracker:\n                if self.isasync:\n                    await self.fn(*args, **kwargs)\n                else:\n                    self.fn(*args, **kwargs)\n\n                graph = build_task_dependencies(tracker)\n\n                visualize_task_dependencies(graph, self.name)\n\n        except GraphvizImportError:\n            raise\n        except GraphvizExecutableNotFoundError:\n            raise\n        except VisualizationUnsupportedError:\n            raise\n        except FlowVisualizationError:\n            raise\n        except Exception as e:\n            msg = (\n                \"It's possible you are trying to visualize a flow that contains \"\n                \"code that directly interacts with the result of a task\"\n                \" inside of the flow. \\nTry passing a `viz_return_value` \"\n                \"to the task decorator, e.g. `@task(viz_return_value=[1, 2, 3]).`\"\n            )\n\n            new_exception = type(e)(str(e) + \"\\n\" + msg)\n            # Copy traceback information from the original exception\n            new_exception.__traceback__ = e.__traceback__\n            raise new_exception\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploys a flow to run on dynamic infrastructure via a work pool.</p> <p>By default, calling this method will build a Docker image for the flow, push it to a registry, and create a deployment via the Prefect API that will run the flow on the given schedule.</p> <p>If you want to use an existing image, you can pass <code>build=False</code> to skip building and pushing an image.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name to give the created deployment.</p> required <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment. Defaults to the value of <code>PREFECT_DEFAULT_WORK_POOL_NAME</code>.</p> <code>None</code> <code>image</code> <code>Optional[Union[str, DeploymentImage]]</code> <p>The name of the Docker image to build, including the registry and repository. Pass a DeploymentImage instance to customize the Dockerfile used and build arguments.</p> <code>None</code> <code>build</code> <code>bool</code> <p>Whether or not to build a new image for the flow. If False, the provided image will be used as-is and pulled at runtime.</p> <code>True</code> <code>push</code> <code>bool</code> <p>Whether or not to skip pushing the built image to a registry.</p> <code>True</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[dict]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> <code>interval</code> <code>Optional[Union[int, float, timedelta]]</code> <p>An interval on which to execute the deployment. Accepts a number or a timedelta object to create a single schedule. If a number is given, it will be interpreted as seconds. Also accepts an iterable of numbers or timedelta to create multiple schedules.</p> <code>None</code> <code>cron</code> <code>Optional[str]</code> <p>A cron schedule string of when to execute runs of this deployment. Also accepts an iterable of cron schedule strings to create multiple schedules.</p> <code>None</code> <code>rrule</code> <code>Optional[str]</code> <p>An rrule schedule string of when to execute runs of this deployment. Also accepts an iterable of rrule schedule strings to create multiple schedules.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[MinimalDeploymentSchedule]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment. Used to define additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <code>print_next_steps_message</code> <p>Whether or not to print a message with next steps after deploying the deployments.</p> required <code>ignore_warnings</code> <code>bool</code> <p>Whether or not to ignore warnings about the work pool type.</p> <code>False</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The ID of the created/updated deployment.</p> <p>Examples:</p> <p>Deploy a local flow to a work pool:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        \"example-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my-repository/my-image:dev\",\n    )\n</code></pre> <p>Deploy a remotely stored flow to a work pool:</p> <pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/org/repo.git\",\n        entrypoint=\"flows.py:my_flow\",\n    ).deploy(\n        \"example-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my-repository/my-image:dev\",\n    )\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def deploy(\n    self,\n    name: str,\n    work_pool_name: Optional[str] = None,\n    image: Optional[Union[str, DeploymentImage]] = None,\n    build: bool = True,\n    push: bool = True,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[dict] = None,\n    interval: Optional[Union[int, float, datetime.timedelta]] = None,\n    cron: Optional[str] = None,\n    rrule: Optional[str] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[MinimalDeploymentSchedule]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    parameters: Optional[dict] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    print_next_steps: bool = True,\n    ignore_warnings: bool = False,\n) -&gt; UUID:\n    \"\"\"\n    Deploys a flow to run on dynamic infrastructure via a work pool.\n\n    By default, calling this method will build a Docker image for the flow, push it to a registry,\n    and create a deployment via the Prefect API that will run the flow on the given schedule.\n\n    If you want to use an existing image, you can pass `build=False` to skip building and pushing\n    an image.\n\n    Args:\n        name: The name to give the created deployment.\n        work_pool_name: The name of the work pool to use for this deployment. Defaults to\n            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n        image: The name of the Docker image to build, including the registry and\n            repository. Pass a DeploymentImage instance to customize the Dockerfile used\n            and build arguments.\n        build: Whether or not to build a new image for the flow. If False, the provided\n            image will be used as-is and pulled at runtime.\n        push: Whether or not to skip pushing the built image to a registry.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n        interval: An interval on which to execute the deployment. Accepts a number or a\n            timedelta object to create a single schedule. If a number is given, it will be\n            interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n            multiple schedules.\n        cron: A cron schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of cron schedule strings to create multiple schedules.\n        rrule: An rrule schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of rrule schedule strings to create multiple schedules.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment. Used to\n            define additional scheduling options like `timezone`.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n        print_next_steps_message: Whether or not to print a message with next steps\n            after deploying the deployments.\n        ignore_warnings: Whether or not to ignore warnings about the work pool type.\n\n    Returns:\n        The ID of the created/updated deployment.\n\n    Examples:\n        Deploy a local flow to a work pool:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.deploy(\n                \"example-deployment\",\n                work_pool_name=\"my-work-pool\",\n                image=\"my-repository/my-image:dev\",\n            )\n        ```\n\n        Deploy a remotely stored flow to a work pool:\n\n        ```python\n        from prefect import flow\n\n        if __name__ == \"__main__\":\n            flow.from_source(\n                source=\"https://github.com/org/repo.git\",\n                entrypoint=\"flows.py:my_flow\",\n            ).deploy(\n                \"example-deployment\",\n                work_pool_name=\"my-work-pool\",\n                image=\"my-repository/my-image:dev\",\n            )\n        ```\n    \"\"\"\n    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n    try:\n        async with get_client() as client:\n            work_pool = await client.read_work_pool(work_pool_name)\n    except ObjectNotFound as exc:\n        raise ValueError(\n            f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n            \" deploying this flow.\"\n        ) from exc\n\n    deployment = await self.to_deployment(\n        name=name,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedules=schedules,\n        paused=paused,\n        schedule=schedule,\n        is_schedule_active=is_schedule_active,\n        triggers=triggers,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n        entrypoint_type=entrypoint_type,\n    )\n\n    deployment_ids = await deploy(\n        deployment,\n        work_pool_name=work_pool_name,\n        image=image,\n        build=build,\n        push=push,\n        print_next_steps_message=False,\n        ignore_warnings=ignore_warnings,\n    )\n\n    if print_next_steps:\n        console = Console()\n        if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n            console.print(\n                \"\\nTo execute flow runs from this deployment, start a worker in a\"\n                \" separate terminal that pulls work from the\"\n                f\" {work_pool_name!r} work pool:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                style=\"blue\",\n            )\n        console.print(\n            \"\\nTo schedule a run for this deployment, use the following command:\"\n        )\n        console.print(\n            f\"\\n\\t$ prefect deployment run '{self.name}/{name}'\\n\",\n            style=\"blue\",\n        )\n        if PREFECT_UI_URL:\n            message = (\n                \"\\nYou can also run your flow via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_ids[0]}[/]\\n\"\n            )\n            console.print(message, soft_wrap=True)\n\n    return deployment_ids[0]\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.from_source","title":"<code>from_source</code>  <code>async</code> <code>classmethod</code>","text":"<p>Loads a flow from a remote source.</p> <p>Parameters:</p> Name Type Description Default <code>source</code> <code>Union[str, RunnerStorage, ReadableDeploymentStorage]</code> <p>Either a URL to a git repository or a storage object.</p> required <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <p>Returns:</p> Type Description <code>F</code> <p>A new <code>Flow</code> instance.</p> <p>Examples:</p> <p>Load a flow from a public git repository:</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=\"https://github.com/org/repo.git\",\n    entrypoint=\"flows.py:my_flow\",\n)\n\nmy_flow()\n</code></pre> <p>Load a flow from a private git repository using an access token stored in a <code>Secret</code> block:</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=GitRepository(\n        url=\"https://github.com/org/repo.git\",\n        credentials={\"access_token\": Secret.load(\"github-access-token\")}\n    ),\n    entrypoint=\"flows.py:my_flow\",\n)\n\nmy_flow()\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def from_source(\n    cls: Type[F],\n    source: Union[str, RunnerStorage, ReadableDeploymentStorage],\n    entrypoint: str,\n) -&gt; F:\n    \"\"\"\n    Loads a flow from a remote source.\n\n    Args:\n        source: Either a URL to a git repository or a storage object.\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n\n    Returns:\n        A new `Flow` instance.\n\n    Examples:\n        Load a flow from a public git repository:\n\n\n        ```python\n        from prefect import flow\n        from prefect.runner.storage import GitRepository\n        from prefect.blocks.system import Secret\n\n        my_flow = flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        )\n\n        my_flow()\n        ```\n\n        Load a flow from a private git repository using an access token stored in a `Secret` block:\n\n        ```python\n        from prefect import flow\n        from prefect.runner.storage import GitRepository\n        from prefect.blocks.system import Secret\n\n        my_flow = flow.from_source(\n            source=GitRepository(\n                url=\"https://github.com/org/repo.git\",\n                credentials={\"access_token\": Secret.load(\"github-access-token\")}\n            ),\n            entrypoint=\"flows.py:my_flow\",\n        )\n\n        my_flow()\n        ```\n    \"\"\"\n    if isinstance(source, str):\n        storage = create_storage_from_source(source)\n    elif isinstance(source, RunnerStorage):\n        storage = source\n    elif hasattr(source, \"get_directory\"):\n        storage = BlockStorageAdapter(source)\n    else:\n        raise TypeError(\n            f\"Unsupported source type {type(source).__name__!r}. Please provide a\"\n            \" URL to remote storage or a storage object.\"\n        )\n\n    with tempfile.TemporaryDirectory() as tmpdir:\n        if not isinstance(storage, LocalStorage):\n            storage.set_base_path(Path(tmpdir))\n            await storage.pull_code()\n\n        full_entrypoint = str(storage.destination / entrypoint)\n        flow: \"Flow\" = await from_async.wait_for_call_in_new_thread(\n            create_call(load_flow_from_entrypoint, full_entrypoint)\n        )\n        flow._storage = storage\n        flow._entrypoint = entrypoint\n\n    return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.serialize_parameters","title":"<code>serialize_parameters</code>","text":"<p>Convert parameters to a serializable form.</p> <p>Uses FastAPI's <code>jsonable_encoder</code> to convert to JSON compatible objects without converting everything directly to a string. This maintains basic types like integers during API roundtrips.</p> Source code in <code>prefect/flows.py</code> <pre><code>def serialize_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Convert parameters to a serializable form.\n\n    Uses FastAPI's `jsonable_encoder` to convert to JSON compatible objects without\n    converting everything directly to a string. This maintains basic types like\n    integers during API roundtrips.\n    \"\"\"\n    serialized_parameters = {}\n    for key, value in parameters.items():\n        try:\n            serialized_parameters[key] = jsonable_encoder(value)\n        except (TypeError, ValueError):\n            logger.debug(\n                f\"Parameter {key!r} for flow {self.name!r} is of unserializable \"\n                f\"type {type(value).__name__!r} and will not be stored \"\n                \"in the backend.\"\n            )\n            serialized_parameters[key] = f\"&lt;{type(value).__name__}&gt;\"\n    return serialized_parameters\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Creates a deployment for this flow and starts a runner to monitor for scheduled work.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>The name to give the created deployment. Defaults to the name of the flow.</p> <code>None</code> <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the deployment. Accepts a number or a timedelta object to create a single schedule. If a number is given, it will be interpreted as seconds. Also accepts an iterable of numbers or timedelta to create multiple schedules.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule string of when to execute runs of this deployment. Also accepts an iterable of cron schedule strings to create multiple schedules.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule string of when to execute runs of this deployment. Also accepts an iterable of rrule schedule strings to create multiple schedules.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[FlexibleScheduleList]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment. Used to define additional scheduling options such as <code>timezone</code>.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>pause_on_shutdown</code> <code>bool</code> <p>If True, provided schedule will be paused when the serve function is stopped. If False, the schedules will continue running.</p> <code>True</code> <code>print_starting_message</code> <code>bool</code> <p>Whether or not to print the starting message when flow is served.</p> <code>True</code> <code>limit</code> <code>Optional[int]</code> <p>The maximum number of runs that can be executed concurrently.</p> <code>None</code> <code>webserver</code> <code>bool</code> <p>Whether or not to start a monitoring webserver for this flow.</p> <code>False</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <p>Examples:</p> <p>Serve a flow:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\"example-deployment\")\n</code></pre> <p>Serve a flow and run it every hour:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\"example-deployment\", interval=3600)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def serve(\n    self,\n    name: Optional[str] = None,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    parameters: Optional[dict] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    pause_on_shutdown: bool = True,\n    print_starting_message: bool = True,\n    limit: Optional[int] = None,\n    webserver: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n):\n    \"\"\"\n    Creates a deployment for this flow and starts a runner to monitor for scheduled work.\n\n    Args:\n        name: The name to give the created deployment. Defaults to the name of the flow.\n        interval: An interval on which to execute the deployment. Accepts a number or a\n            timedelta object to create a single schedule. If a number is given, it will be\n            interpreted as seconds. Also accepts an iterable of numbers or timedelta to create\n            multiple schedules.\n        cron: A cron schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of cron schedule strings to create multiple schedules.\n        rrule: An rrule schedule string of when to execute runs of this deployment.\n            Also accepts an iterable of rrule schedule strings to create multiple schedules.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment. Used to\n            define additional scheduling options such as `timezone`.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        pause_on_shutdown: If True, provided schedule will be paused when the serve function is stopped.\n            If False, the schedules will continue running.\n        print_starting_message: Whether or not to print the starting message when flow is served.\n        limit: The maximum number of runs that can be executed concurrently.\n        webserver: Whether or not to start a monitoring webserver for this flow.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n\n    Examples:\n        Serve a flow:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.serve(\"example-deployment\")\n        ```\n\n        Serve a flow and run it every hour:\n\n        ```python\n        from prefect import flow\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        if __name__ == \"__main__\":\n            my_flow.serve(\"example-deployment\", interval=3600)\n        ```\n    \"\"\"\n    from prefect.runner import Runner\n\n    if not name:\n        name = self.name\n    else:\n        # Handling for my_flow.serve(__file__)\n        # Will set name to name of file where my_flow.serve() without the extension\n        # Non filepath strings will pass through unchanged\n        name = Path(name).stem\n\n    runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown, limit=limit)\n    deployment_id = await runner.add_flow(\n        self,\n        name=name,\n        triggers=triggers,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        paused=paused,\n        schedules=schedules,\n        schedule=schedule,\n        is_schedule_active=is_schedule_active,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        entrypoint_type=entrypoint_type,\n    )\n    if print_starting_message:\n        help_message = (\n            f\"[green]Your flow {self.name!r} is being served and polling for\"\n            \" scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            f\" '{self.name}/{name}'\\n[/]\"\n        )\n        if PREFECT_UI_URL:\n            help_message += (\n                \"\\nYou can also run your flow via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n            )\n\n        console = Console()\n        console.print(help_message, soft_wrap=True)\n    await runner.start(webserver=webserver)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.to_deployment","title":"<code>to_deployment</code>  <code>async</code>","text":"<p>Creates a runner deployment object for this flow.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name to give the created deployment.</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the new deployment. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this deployment.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this deployment.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[List[FlexibleScheduleList]]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options such as <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object defining when to execute runs of this deployment.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this deployment.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that will kick off runs of this deployment.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for the created deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for</p> <code>None</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> <p>Examples:</p> <p>Prepare two deployments and serve them:</p> <pre><code>from prefect import flow, serve\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef my_other_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\":\n    hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n    bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n    serve(hello_deploy, bye_deploy)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"schedule\",\n    start_date=\"Mar 2024\",\n    when=lambda p: p is not None,\n    help=\"Use `schedules` instead.\",\n)\n@deprecated_parameter(\n    \"is_schedule_active\",\n    start_date=\"Mar 2024\",\n    when=lambda p: p is not None,\n    help=\"Use `paused` instead.\",\n)\nasync def to_deployment(\n    self,\n    name: str,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[List[\"FlexibleScheduleList\"]] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Creates a runner deployment object for this flow.\n\n    Args:\n        name: The name to give the created deployment.\n        interval: An interval on which to execute the new deployment. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this deployment.\n        rrule: An rrule schedule of when to execute runs of this deployment.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options such as `timezone`.\n        schedule: A schedule object defining when to execute runs of this deployment.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        parameters: A dictionary of default parameter values to pass to runs of this deployment.\n        triggers: A list of triggers that will kick off runs of this deployment.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for the created deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n\n    Examples:\n        Prepare two deployments and serve them:\n\n        ```python\n        from prefect import flow, serve\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def my_other_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\":\n            hello_deploy = my_flow.to_deployment(\"hello\", tags=[\"dev\"])\n            bye_deploy = my_other_flow.to_deployment(\"goodbye\", tags=[\"dev\"])\n            serve(hello_deploy, bye_deploy)\n        ```\n    \"\"\"\n    from prefect.deployments.runner import RunnerDeployment\n\n    if not name.endswith(\".py\"):\n        raise_on_name_with_banned_characters(name)\n    if self._storage and self._entrypoint:\n        return await RunnerDeployment.from_storage(\n            storage=self._storage,\n            entrypoint=self._entrypoint,\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            tags=tags,\n            triggers=triggers,\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n    else:\n        return RunnerDeployment.from_flow(\n            self,\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            paused=paused,\n            schedules=schedules,\n            schedule=schedule,\n            is_schedule_active=is_schedule_active,\n            tags=tags,\n            triggers=triggers,\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n            entrypoint_type=entrypoint_type,\n        )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.validate_parameters","title":"<code>validate_parameters</code>","text":"<p>Validate parameters for compatibility with the flow by attempting to cast the inputs to the associated types specified by the function's type annotations.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A new dict of parameters that have been cast to the appropriate types</p> <p>Raises:</p> Type Description <code>ParameterTypeError</code> <p>if the provided parameters are not valid</p> Source code in <code>prefect/flows.py</code> <pre><code>def validate_parameters(self, parameters: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Validate parameters for compatibility with the flow by attempting to cast the inputs to the\n    associated types specified by the function's type annotations.\n\n    Returns:\n        A new dict of parameters that have been cast to the appropriate types\n\n    Raises:\n        ParameterTypeError: if the provided parameters are not valid\n    \"\"\"\n    args, kwargs = parameters_to_args_kwargs(self.fn, parameters)\n\n    if HAS_PYDANTIC_V2:\n        has_v1_models = any(isinstance(o, V1BaseModel) for o in args) or any(\n            isinstance(o, V1BaseModel) for o in kwargs.values()\n        )\n        has_v2_types = any(is_v2_type(o) for o in args) or any(\n            is_v2_type(o) for o in kwargs.values()\n        )\n\n        if has_v1_models and has_v2_types:\n            raise ParameterTypeError(\n                \"Cannot mix Pydantic v1 and v2 types as arguments to a flow.\"\n            )\n\n        if has_v1_models:\n            validated_fn = V1ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n        else:\n            validated_fn = V2ValidatedFunction(\n                self.fn, config={\"arbitrary_types_allowed\": True}\n            )\n\n    else:\n        validated_fn = ValidatedFunction(\n            self.fn, config={\"arbitrary_types_allowed\": True}\n        )\n\n    try:\n        model = validated_fn.init_model_instance(*args, **kwargs)\n    except pydantic.ValidationError as exc:\n        # We capture the pydantic exception and raise our own because the pydantic\n        # exception is not picklable when using a cythonized pydantic installation\n        raise ParameterTypeError.from_validation_error(exc) from None\n    except V2ValidationError as exc:\n        # We capture the pydantic exception and raise our own because the pydantic\n        # exception is not picklable when using a cythonized pydantic installation\n        raise ParameterTypeError.from_validation_error(exc) from None\n\n    # Get the updated parameter dict with cast values from the model\n    cast_parameters = {\n        k: v\n        for k, v in model._iter()\n        if k in model.__fields_set__ or model.__fields__[k].default_factory\n    }\n    return cast_parameters\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.visualize","title":"<code>visualize</code>  <code>async</code>","text":"<p>Generates a graphviz object representing the current flow. In IPython notebooks, it's rendered inline, otherwise in a new window as a PNG.</p> <p>Raises:</p> Type Description <code>-ImportError</code> <p>If <code>graphviz</code> isn't installed.</p> <code>-GraphvizExecutableNotFoundError</code> <p>If the <code>dot</code> executable isn't found.</p> <code>-FlowVisualizationError</code> <p>If the flow can't be visualized for any other reason.</p> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def visualize(self, *args, **kwargs):\n    \"\"\"\n    Generates a graphviz object representing the current flow. In IPython notebooks,\n    it's rendered inline, otherwise in a new window as a PNG.\n\n    Raises:\n        - ImportError: If `graphviz` isn't installed.\n        - GraphvizExecutableNotFoundError: If the `dot` executable isn't found.\n        - FlowVisualizationError: If the flow can't be visualized for any other reason.\n    \"\"\"\n    if not PREFECT_UNIT_TEST_MODE:\n        warnings.warn(\n            \"`flow.visualize()` will execute code inside of your flow that is not\"\n            \" decorated with `@task` or `@flow`.\"\n        )\n\n    try:\n        with TaskVizTracker() as tracker:\n            if self.isasync:\n                await self.fn(*args, **kwargs)\n            else:\n                self.fn(*args, **kwargs)\n\n            graph = build_task_dependencies(tracker)\n\n            visualize_task_dependencies(graph, self.name)\n\n    except GraphvizImportError:\n        raise\n    except GraphvizExecutableNotFoundError:\n        raise\n    except VisualizationUnsupportedError:\n        raise\n    except FlowVisualizationError:\n        raise\n    except Exception as e:\n        msg = (\n            \"It's possible you are trying to visualize a flow that contains \"\n            \"code that directly interacts with the result of a task\"\n            \" inside of the flow. \\nTry passing a `viz_return_value` \"\n            \"to the task decorator, e.g. `@task(viz_return_value=[1, 2, 3]).`\"\n        )\n\n        new_exception = type(e)(str(e) + \"\\n\" + msg)\n        # Copy traceback information from the original exception\n        new_exception.__traceback__ = e.__traceback__\n        raise new_exception\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.Flow.with_options","title":"<code>with_options</code>","text":"<p>Create a new flow from the current object, updating provided options.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A new name for the flow.</p> <code>None</code> <code>version</code> <code>str</code> <p>A new version for the flow.</p> <code>None</code> <code>description</code> <code>str</code> <p>A new description for the flow.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>task_runner</code> <code>Union[Type[BaseTaskRunner], BaseTaskRunner]</code> <p>A new task runner for the flow.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>A new number of seconds to fail the flow after if still running.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>A new value indicating if flow calls should validate given parameters.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>A new number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[int, float]]</code> <p>A new number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling result persistence.</p> <code>NotSet</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>A new storage type to use for results.</p> <code>NotSet</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>A new serializer to use for results.</p> <code>NotSet</code> <code>cache_result_in_memory</code> <code>bool</code> <p>A new value indicating if the flow's result should be cached in memory.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a completed state.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a cancelling state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a crashed state.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>A new list of callables to run when the flow enters a running state.</p> <code>None</code> <p>Returns:</p> Type Description <code>Self</code> <p>A new <code>Flow</code> instance.</p> <pre><code>Create a new flow from an existing flow and update the name:\n\n&gt;&gt;&gt; @flow(name=\"My flow\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\nCreate a new flow from an existing flow, update the task runner, and call\nit without an intermediate variable:\n\n&gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow(x, y):\n&gt;&gt;&gt;     return x + y\n&gt;&gt;&gt;\n&gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n&gt;&gt;&gt; assert state.result() == 4\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>def with_options(\n    self,\n    *,\n    name: str = None,\n    version: str = None,\n    retries: Optional[int] = None,\n    retry_delay_seconds: Optional[Union[int, float]] = None,\n    description: str = None,\n    flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n    task_runner: Union[Type[BaseTaskRunner], BaseTaskRunner] = None,\n    timeout_seconds: Union[int, float] = None,\n    validate_parameters: bool = None,\n    persist_result: Optional[bool] = NotSet,\n    result_storage: Optional[ResultStorage] = NotSet,\n    result_serializer: Optional[ResultSerializer] = NotSet,\n    cache_result_in_memory: bool = None,\n    log_prints: Optional[bool] = NotSet,\n    on_completion: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_failure: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_cancellation: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n) -&gt; Self:\n    \"\"\"\n    Create a new flow from the current object, updating provided options.\n\n    Args:\n        name: A new name for the flow.\n        version: A new version for the flow.\n        description: A new description for the flow.\n        flow_run_name: An optional name to distinguish runs of this flow; this name\n            can be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        task_runner: A new task runner for the flow.\n        timeout_seconds: A new number of seconds to fail the flow after if still\n            running.\n        validate_parameters: A new value indicating if flow calls should validate\n            given parameters.\n        retries: A new number of times to retry on flow run failure.\n        retry_delay_seconds: A new number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        persist_result: A new option for enabling or disabling result persistence.\n        result_storage: A new storage type to use for results.\n        result_serializer: A new serializer to use for results.\n        cache_result_in_memory: A new value indicating if the flow's result should\n            be cached in memory.\n        on_failure: A new list of callables to run when the flow enters a failed state.\n        on_completion: A new list of callables to run when the flow enters a completed state.\n        on_cancellation: A new list of callables to run when the flow enters a cancelling state.\n        on_crashed: A new list of callables to run when the flow enters a crashed state.\n        on_running: A new list of callables to run when the flow enters a running state.\n\n    Returns:\n        A new `Flow` instance.\n\n    Examples:\n\n        Create a new flow from an existing flow and update the name:\n\n        &gt;&gt;&gt; @flow(name=\"My flow\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_flow = my_flow.with_options(name=\"My new flow\")\n\n        Create a new flow from an existing flow, update the task runner, and call\n        it without an intermediate variable:\n\n        &gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow(x, y):\n        &gt;&gt;&gt;     return x + y\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; state = my_flow.with_options(task_runner=SequentialTaskRunner)(1, 3)\n        &gt;&gt;&gt; assert state.result() == 4\n\n    \"\"\"\n    new_flow = Flow(\n        fn=self.fn,\n        name=name or self.name,\n        description=description or self.description,\n        flow_run_name=flow_run_name or self.flow_run_name,\n        version=version or self.version,\n        task_runner=task_runner or self.task_runner,\n        retries=retries if retries is not None else self.retries,\n        retry_delay_seconds=(\n            retry_delay_seconds\n            if retry_delay_seconds is not None\n            else self.retry_delay_seconds\n        ),\n        timeout_seconds=(\n            timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n        ),\n        validate_parameters=(\n            validate_parameters\n            if validate_parameters is not None\n            else self.should_validate_parameters\n        ),\n        persist_result=(\n            persist_result if persist_result is not NotSet else self.persist_result\n        ),\n        result_storage=(\n            result_storage if result_storage is not NotSet else self.result_storage\n        ),\n        result_serializer=(\n            result_serializer\n            if result_serializer is not NotSet\n            else self.result_serializer\n        ),\n        cache_result_in_memory=(\n            cache_result_in_memory\n            if cache_result_in_memory is not None\n            else self.cache_result_in_memory\n        ),\n        log_prints=log_prints if log_prints is not NotSet else self.log_prints,\n        on_completion=on_completion or self.on_completion,\n        on_failure=on_failure or self.on_failure,\n        on_cancellation=on_cancellation or self.on_cancellation,\n        on_crashed=on_crashed or self.on_crashed,\n        on_running=on_running or self.on_running,\n    )\n    new_flow._storage = self._storage\n    new_flow._entrypoint = self._entrypoint\n    return new_flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.flow","title":"<code>flow</code>","text":"<p>Decorator to designate a function as a Prefect workflow.</p> <p>This decorator may be used for asynchronous or synchronous functions.</p> <p>Flow parameters must be serializable by Pydantic.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional version string for the flow; if not provided, we will attempt to create a version string as a hash of the file containing the wrapped function; if the file cannot be located, the version will be null.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>int</code> <p>An optional number of times to retry on flow run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero.</p> <code>None</code> <code>task_runner</code> <code>BaseTaskRunner</code> <p>An optional task runner to use for task execution within the flow; if not provided, a <code>ConcurrentTaskRunner</code> will be instantiated.</p> <code>ConcurrentTaskRunner</code> <code>description</code> <code>str</code> <p>An optional string description for the flow; if not provided, the description will be pulled from the docstring for the decorated function.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called.</p> <code>None</code> <code>validate_parameters</code> <code>bool</code> <p>By default, parameters passed to flows are validated by Pydantic. This will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type; for example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p> <code>True</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this flow should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this flow. This value will be used as the default for any tasks in this flow. If not provided, the local file system will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this flow for persistence. This value will be used as the default for any tasks in this flow. If not provided, the value of <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used unless called as a subflow, at which point the default will be loaded from the parent flow.</p> <code>None</code> <code>cache_result_in_memory</code> <code>bool</code> <p>An optional toggle indicating whether the cached result of a running the flow should be stored in memory. Defaults to <code>True</code>.</p> <code>True</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the flow will be redirected to the Prefect logger for the flow run. Defaults to <code>None</code>, which indicates that the value from the parent flow should be used. If this is a parent flow, the default is pulled from the <code>PREFECT_LOGGING_LOG_PRINTS</code> setting.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Flow, FlowRun, State], Union[Awaitable[None], None]]]]</code> <p>An optional list of functions to call when the flow run is completed. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Flow, FlowRun, State], Union[Awaitable[None], None]]]]</code> <p>An optional list of functions to call when the flow run fails. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_cancellation</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run is cancelled. These functions will be passed the flow, flow run, and final state.</p> <code>None</code> <code>on_crashed</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run crashes. Each function should accept three arguments: the flow, the flow run, and the final state of the flow run.</p> <code>None</code> <code>on_running</code> <code>Optional[List[Callable[[Flow, FlowRun, State], None]]]</code> <p>An optional list of functions to call when the flow run is started. Each function should accept three arguments: the flow, the flow run, and the current state</p> <code>None</code> <p>Returns:</p> Type Description <p>A callable <code>Flow</code> object which, when called, will run the flow and return its</p> <p>final state.</p> <p>Examples:</p> <p>Define a simple flow</p> <pre><code>&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define an async flow</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define a flow with a version and description</p> <pre><code>&gt;&gt;&gt; @flow(version=\"first-flow\", description=\"This flow is empty!\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a flow with a custom name</p> <pre><code>&gt;&gt;&gt; @flow(name=\"The Ultimate Flow\")\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a flow that submits its tasks to dask</p> <pre><code>&gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow(task_runner=DaskTaskRunner)\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     pass\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>def flow(\n    __fn=None,\n    *,\n    name: Optional[str] = None,\n    version: Optional[str] = None,\n    flow_run_name: Optional[Union[Callable[[], str], str]] = None,\n    retries: int = None,\n    retry_delay_seconds: Union[int, float] = None,\n    task_runner: BaseTaskRunner = ConcurrentTaskRunner,\n    description: str = None,\n    timeout_seconds: Union[int, float] = None,\n    validate_parameters: bool = True,\n    persist_result: Optional[bool] = None,\n    result_storage: Optional[ResultStorage] = None,\n    result_serializer: Optional[ResultSerializer] = None,\n    cache_result_in_memory: bool = True,\n    log_prints: Optional[bool] = None,\n    on_completion: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_failure: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_cancellation: Optional[\n        List[Callable[[FlowSchema, FlowRun, State], None]]\n    ] = None,\n    on_crashed: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n    on_running: Optional[List[Callable[[FlowSchema, FlowRun, State], None]]] = None,\n):\n    \"\"\"\n    Decorator to designate a function as a Prefect workflow.\n\n    This decorator may be used for asynchronous or synchronous functions.\n\n    Flow parameters must be serializable by Pydantic.\n\n    Args:\n        name: An optional name for the flow; if not provided, the name will be inferred\n            from the given function.\n        version: An optional version string for the flow; if not provided, we will\n            attempt to create a version string as a hash of the file containing the\n            wrapped function; if the file cannot be located, the version will be null.\n        flow_run_name: An optional name to distinguish runs of this flow; this name can\n            be provided as a string template with the flow's parameters as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on flow run failure.\n        retry_delay_seconds: An optional number of seconds to wait before retrying the\n            flow after failure. This is only applicable if `retries` is nonzero.\n        task_runner: An optional task runner to use for task execution within the flow; if\n            not provided, a `ConcurrentTaskRunner` will be instantiated.\n        description: An optional string description for the flow; if not provided, the\n            description will be pulled from the docstring for the decorated function.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the flow. If the flow exceeds this runtime, it will be marked as failed.\n            Flow execution may continue until the next task is called.\n        validate_parameters: By default, parameters passed to flows are validated by\n            Pydantic. This will check that input values conform to the annotated types\n            on the function. Where possible, values will be coerced into the correct\n            type; for example, if a parameter is defined as `x: int` and \"5\" is passed,\n            it will be resolved to `5`. If set to `False`, no validation will be\n            performed on flow parameters.\n        persist_result: An optional toggle indicating whether the result of this flow\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this flow.\n            This value will be used as the default for any tasks in this flow.\n            If not provided, the local file system will be used unless called as\n            a subflow, at which point the default will be loaded from the parent flow.\n        result_serializer: An optional serializer to use to serialize the result of this\n            flow for persistence. This value will be used as the default for any tasks\n            in this flow. If not provided, the value of `PREFECT_RESULTS_DEFAULT_SERIALIZER`\n            will be used unless called as a subflow, at which point the default will be\n            loaded from the parent flow.\n        cache_result_in_memory: An optional toggle indicating whether the cached result of\n            a running the flow should be stored in memory. Defaults to `True`.\n        log_prints: If set, `print` statements in the flow will be redirected to the\n            Prefect logger for the flow run. Defaults to `None`, which indicates that\n            the value from the parent flow should be used. If this is a parent flow,\n            the default is pulled from the `PREFECT_LOGGING_LOG_PRINTS` setting.\n        on_completion: An optional list of functions to call when the flow run is\n            completed. Each function should accept three arguments: the flow, the flow\n            run, and the final state of the flow run.\n        on_failure: An optional list of functions to call when the flow run fails. Each\n            function should accept three arguments: the flow, the flow run, and the\n            final state of the flow run.\n        on_cancellation: An optional list of functions to call when the flow run is\n            cancelled. These functions will be passed the flow, flow run, and final state.\n        on_crashed: An optional list of functions to call when the flow run crashes. Each\n            function should accept three arguments: the flow, the flow run, and the\n            final state of the flow run.\n        on_running: An optional list of functions to call when the flow run is started. Each\n            function should accept three arguments: the flow, the flow run, and the current state\n\n    Returns:\n        A callable `Flow` object which, when called, will run the flow and return its\n        final state.\n\n    Examples:\n        Define a simple flow\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define an async flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define a flow with a version and description\n\n        &gt;&gt;&gt; @flow(version=\"first-flow\", description=\"This flow is empty!\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n\n        Define a flow with a custom name\n\n        &gt;&gt;&gt; @flow(name=\"The Ultimate Flow\")\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n\n        Define a flow that submits its tasks to dask\n\n        &gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow(task_runner=DaskTaskRunner)\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     pass\n    \"\"\"\n    if __fn:\n        return cast(\n            Flow[P, R],\n            Flow(\n                fn=__fn,\n                name=name,\n                version=version,\n                flow_run_name=flow_run_name,\n                task_runner=task_runner,\n                description=description,\n                timeout_seconds=timeout_seconds,\n                validate_parameters=validate_parameters,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                log_prints=log_prints,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                on_cancellation=on_cancellation,\n                on_crashed=on_crashed,\n                on_running=on_running,\n            ),\n        )\n    else:\n        return cast(\n            Callable[[Callable[P, R]], Flow[P, R]],\n            partial(\n                flow,\n                name=name,\n                version=version,\n                flow_run_name=flow_run_name,\n                task_runner=task_runner,\n                description=description,\n                timeout_seconds=timeout_seconds,\n                validate_parameters=validate_parameters,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                log_prints=log_prints,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                on_cancellation=on_cancellation,\n                on_crashed=on_crashed,\n                on_running=on_running,\n            ),\n        )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.is_entrypoint_async","title":"<code>is_entrypoint_async</code>","text":"<p>Determine if the function specified in the entrypoint is asynchronous.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>A string in the format <code>&lt;path_to_script&gt;:&lt;func_name&gt;</code> or a module path to a function.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the function is asynchronous, False otherwise.</p> Source code in <code>prefect/flows.py</code> <pre><code>def is_entrypoint_async(entrypoint: str) -&gt; bool:\n    \"\"\"\n    Determine if the function specified in the entrypoint is asynchronous.\n\n    Args:\n        entrypoint: A string in the format `&lt;path_to_script&gt;:&lt;func_name&gt;` or\n          a module path to a function.\n\n    Returns:\n        True if the function is asynchronous, False otherwise.\n    \"\"\"\n    func_def, _ = _entrypoint_definition_and_source(entrypoint)\n    return isinstance(func_def, ast.AsyncFunctionDef)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_arguments_from_entrypoint","title":"<code>load_flow_arguments_from_entrypoint</code>","text":"<p>Extract flow arguments from an entrypoint string.</p> <p>Loads the source code of the entrypoint and extracts the flow arguments from the <code>flow</code> decorator.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_arguments_from_entrypoint(\n    entrypoint: str, arguments: Optional[Union[List[str], Set[str]]] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Extract flow arguments from an entrypoint string.\n\n    Loads the source code of the entrypoint and extracts the flow arguments\n    from the `flow` decorator.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n    \"\"\"\n\n    func_def, source_code = _entrypoint_definition_and_source(entrypoint)\n    path = None\n    if \":\" in entrypoint:\n        path = entrypoint.rsplit(\":\")[0]\n\n    if arguments is None:\n        # If no arguments are provided default to known arguments that are of\n        # built-in types.\n        arguments = {\n            \"name\",\n            \"version\",\n            \"retries\",\n            \"retry_delay_seconds\",\n            \"description\",\n            \"timeout_seconds\",\n            \"validate_parameters\",\n            \"persist_result\",\n            \"cache_result_in_memory\",\n            \"log_prints\",\n        }\n\n    result = {}\n\n    for decorator in func_def.decorator_list:\n        if (\n            isinstance(decorator, ast.Call)\n            and getattr(decorator.func, \"id\", \"\") == \"flow\"\n        ):\n            for keyword in decorator.keywords:\n                if keyword.arg not in arguments:\n                    continue\n\n                if isinstance(keyword.value, ast.Constant):\n                    # Use the string value of the argument\n                    result[keyword.arg] = str(keyword.value.value)\n                    continue\n\n                # if the arg value is not a raw str (i.e. a variable or expression),\n                # then attempt to evaluate it\n                namespace = safe_load_namespace(source_code, filepath=path)\n                literal_arg_value = ast.get_source_segment(source_code, keyword.value)\n                cleaned_value = (\n                    literal_arg_value.replace(\"\\n\", \"\") if literal_arg_value else \"\"\n                )\n\n                try:\n                    evaluated_value = eval(cleaned_value, namespace)  # type: ignore\n                    result[keyword.arg] = str(evaluated_value)\n                except Exception as e:\n                    logger.info(\n                        \"Failed to parse @flow argument: `%s=%s` due to the following error. Ignoring and falling back to default behavior.\",\n                        keyword.arg,\n                        literal_arg_value,\n                        exc_info=e,\n                    )\n                    # ignore the decorator arg and fallback to default behavior\n                    continue\n\n    if \"name\" in arguments and \"name\" not in result:\n        # If no matching decorator or keyword argument for `name' is found\n        # fallback to the function name.\n        result[\"name\"] = func_def.name.replace(\"_\", \"-\")\n\n    return result\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_entrypoint","title":"<code>load_flow_from_entrypoint</code>","text":"<p>Extract a flow object from a script at an entrypoint by running all of the code in the file.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required <code>use_placeholder_flow</code> <code>bool</code> <p>If True, a placeholder flow will be used if the entrypoint cannot be loaded for any reason (e.g. dependencies are missing). If False, an exception will be raised.</p> <code>True</code> <p>Returns:</p> Type Description <code>Flow</code> <p>The flow object from the script</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> <code>MissingFlowError</code> <p>If the flow function specified in the entrypoint does not exist</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_entrypoint(\n    entrypoint: str,\n    use_placeholder_flow: bool = True,\n) -&gt; Flow:\n    \"\"\"\n    Extract a flow object from a script at an entrypoint by running all of the code in the file.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;` or a module path\n            to a flow function\n        use_placeholder_flow: If True, a placeholder flow will be used if the entrypoint\n            cannot be loaded for any reason (e.g. dependencies are missing). If False, an\n            exception will be raised.\n\n    Returns:\n        The flow object from the script\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n        MissingFlowError: If the flow function specified in the entrypoint does not exist\n    \"\"\"\n    with PrefectObjectRegistry(\n        block_code_execution=True,\n        capture_failures=True,\n    ):\n        if \":\" in entrypoint:\n            # split by the last colon once to handle Windows paths with drive letters i.e C:\\path\\to\\file.py:do_stuff\n            path, func_name = entrypoint.rsplit(\":\", maxsplit=1)\n\n        else:\n            path, func_name = entrypoint.rsplit(\".\", maxsplit=1)\n        try:\n            flow = import_object(entrypoint)\n        except AttributeError as exc:\n            raise MissingFlowError(\n                f\"Flow function with name {func_name!r} not found in {path!r}. \"\n            ) from exc\n        except ScriptError:\n            # If the flow has dependencies that are not installed in the current\n            # environment, fallback to loading the flow via AST parsing.\n            if use_placeholder_flow:\n                flow = safe_load_flow_from_entrypoint(entrypoint)\n                if flow is None:\n                    raise\n            else:\n                raise\n\n        if not isinstance(flow, Flow):\n            raise MissingFlowError(\n                f\"Function with name {func_name!r} is not a flow. Make sure that it is \"\n                \"decorated with '@flow'.\"\n            )\n\n        return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_script","title":"<code>load_flow_from_script</code>","text":"<p>Extract a flow object from a script by running all of the code in the file.</p> <p>If the script has multiple flows in it, a flow name must be provided to specify the flow to return.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>A path to a Python script containing flows</p> required <code>flow_name</code> <code>str</code> <p>An optional flow name to look for in the script</p> <code>None</code> <p>Returns:</p> Type Description <code>Flow</code> <p>The flow object from the script</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> <code>MissingFlowError</code> <p>If no flows exist in the iterable</p> <code>MissingFlowError</code> <p>If a flow name is provided and that flow does not exist</p> <code>UnspecifiedFlowError</code> <p>If multiple flows exist but no flow name was provided</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_script(path: str, flow_name: str = None) -&gt; Flow:\n    \"\"\"\n    Extract a flow object from a script by running all of the code in the file.\n\n    If the script has multiple flows in it, a flow name must be provided to specify\n    the flow to return.\n\n    Args:\n        path: A path to a Python script containing flows\n        flow_name: An optional flow name to look for in the script\n\n    Returns:\n        The flow object from the script\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n        MissingFlowError: If no flows exist in the iterable\n        MissingFlowError: If a flow name is provided and that flow does not exist\n        UnspecifiedFlowError: If multiple flows exist but no flow name was provided\n    \"\"\"\n    return select_flow(\n        load_flows_from_script(path),\n        flow_name=flow_name,\n        from_message=f\"in script '{path}'\",\n    )\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flow_from_text","title":"<code>load_flow_from_text</code>","text":"<p>Load a flow from a text script.</p> <p>The script will be written to a temporary local file path so errors can refer to line numbers and contextual tracebacks can be provided.</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flow_from_text(script_contents: AnyStr, flow_name: str):\n    \"\"\"\n    Load a flow from a text script.\n\n    The script will be written to a temporary local file path so errors can refer\n    to line numbers and contextual tracebacks can be provided.\n    \"\"\"\n    with NamedTemporaryFile(\n        mode=\"wt\" if isinstance(script_contents, str) else \"wb\",\n        prefix=f\"flow-script-{flow_name}\",\n        suffix=\".py\",\n        delete=False,\n    ) as tmpfile:\n        tmpfile.write(script_contents)\n        tmpfile.flush()\n    try:\n        flow = load_flow_from_script(tmpfile.name, flow_name=flow_name)\n    finally:\n        # windows compat\n        tmpfile.close()\n        os.remove(tmpfile.name)\n    return flow\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_flows_from_script","title":"<code>load_flows_from_script</code>","text":"<p>Load all flow objects from the given python script. All of the code in the file will be executed.</p> <p>Returns:</p> Type Description <code>List[Flow]</code> <p>A list of flows</p> <p>Raises:</p> Type Description <code>FlowScriptError</code> <p>If an exception is encountered while running the script</p> Source code in <code>prefect/flows.py</code> <pre><code>def load_flows_from_script(path: str) -&gt; List[Flow]:\n    \"\"\"\n    Load all flow objects from the given python script. All of the code in the file\n    will be executed.\n\n    Returns:\n        A list of flows\n\n    Raises:\n        FlowScriptError: If an exception is encountered while running the script\n    \"\"\"\n    return registry_from_script(path).get_instances(Flow)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.load_placeholder_flow","title":"<code>load_placeholder_flow</code>","text":"<p>Load a placeholder flow that is initialized with the same arguments as the flow specified in the entrypoint. If called the flow will raise <code>raises</code>.</p> <p>This is useful when a flow can't be loaded due to missing dependencies or other issues but the base metadata defining the flow is still needed.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required <code>raises</code> <code>Exception</code> <p>an exception to raise when the flow is called</p> required Source code in <code>prefect/flows.py</code> <pre><code>def load_placeholder_flow(entrypoint: str, raises: Exception):\n    \"\"\"\n    Load a placeholder flow that is initialized with the same arguments as the\n    flow specified in the entrypoint. If called the flow will raise `raises`.\n\n    This is useful when a flow can't be loaded due to missing dependencies or\n    other issues but the base metadata defining the flow is still needed.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n        raises: an exception to raise when the flow is called\n    \"\"\"\n\n    def _base_placeholder():\n        raise raises\n\n    def sync_placeholder_flow(*args, **kwargs):\n        _base_placeholder()\n\n    async def async_placeholder_flow(*args, **kwargs):\n        _base_placeholder()\n\n    placeholder_flow = (\n        async_placeholder_flow\n        if is_entrypoint_async(entrypoint)\n        else sync_placeholder_flow\n    )\n\n    arguments = load_flow_arguments_from_entrypoint(entrypoint)\n    arguments[\"fn\"] = placeholder_flow\n\n    return Flow(**arguments)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.safe_load_flow_from_entrypoint","title":"<code>safe_load_flow_from_entrypoint</code>","text":"<p>Load a flow from an entrypoint and return None if an exception is raised.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>a string in the format <code>&lt;path_to_script&gt;:&lt;flow_func_name&gt;</code> or a module path to a flow function</p> required Source code in <code>prefect/flows.py</code> <pre><code>def safe_load_flow_from_entrypoint(entrypoint: str) -&gt; Optional[Flow]:\n    \"\"\"\n    Load a flow from an entrypoint and return None if an exception is raised.\n\n    Args:\n        entrypoint: a string in the format `&lt;path_to_script&gt;:&lt;flow_func_name&gt;`\n          or a module path to a flow function\n    \"\"\"\n    func_def, source_code = _entrypoint_definition_and_source(entrypoint)\n    path = None\n    if \":\" in entrypoint:\n        path = entrypoint.rsplit(\":\")[0]\n    namespace = safe_load_namespace(source_code, filepath=path)\n    if func_def.name in namespace:\n        return namespace[func_def.name]\n    else:\n        # If the function is not in the namespace, if may be due to missing dependencies\n        # for the function. We will attempt to compile each annotation and default value\n        # and remove them from the function definition to see if the function can be\n        # compiled without them.\n\n        return _sanitize_and_load_flow(func_def, namespace)\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.select_flow","title":"<code>select_flow</code>","text":"<p>Select the only flow in an iterable or a flow specified by name.</p> <p>Returns     A single flow object</p> <p>Raises:</p> Type Description <code>MissingFlowError</code> <p>If no flows exist in the iterable</p> <code>MissingFlowError</code> <p>If a flow name is provided and that flow does not exist</p> <code>UnspecifiedFlowError</code> <p>If multiple flows exist but no flow name was provided</p> Source code in <code>prefect/flows.py</code> <pre><code>def select_flow(\n    flows: Iterable[Flow], flow_name: str = None, from_message: str = None\n) -&gt; Flow:\n    \"\"\"\n    Select the only flow in an iterable or a flow specified by name.\n\n    Returns\n        A single flow object\n\n    Raises:\n        MissingFlowError: If no flows exist in the iterable\n        MissingFlowError: If a flow name is provided and that flow does not exist\n        UnspecifiedFlowError: If multiple flows exist but no flow name was provided\n    \"\"\"\n    # Convert to flows by name\n    flows = {f.name: f for f in flows}\n\n    # Add a leading space if given, otherwise use an empty string\n    from_message = (\" \" + from_message) if from_message else \"\"\n    if not flows:\n        raise MissingFlowError(f\"No flows found{from_message}.\")\n\n    elif flow_name and flow_name not in flows:\n        raise MissingFlowError(\n            f\"Flow {flow_name!r} not found{from_message}. \"\n            f\"Found the following flows: {listrepr(flows.keys())}. \"\n            \"Check to make sure that your flow function is decorated with `@flow`.\"\n        )\n\n    elif not flow_name and len(flows) &gt; 1:\n        raise UnspecifiedFlowError(\n            (\n                f\"Found {len(flows)} flows{from_message}:\"\n                f\" {listrepr(sorted(flows.keys()))}. Specify a flow name to select a\"\n                \" flow.\"\n            ),\n        )\n\n    if flow_name:\n        return flows[flow_name]\n    else:\n        return list(flows.values())[0]\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/flows/#prefect.flows.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Serve the provided list of deployments.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>RunnerDeployment</code> <p>A list of deployments to serve.</p> <code>()</code> <code>pause_on_shutdown</code> <code>bool</code> <p>A boolean for whether or not to automatically pause deployment schedules on shutdown.</p> <code>True</code> <code>print_starting_message</code> <code>bool</code> <p>Whether or not to print message to the console on startup.</p> <code>True</code> <code>limit</code> <code>Optional[int]</code> <p>The maximum number of runs that can be executed concurrently.</p> <code>None</code> <code>**kwargs</code> <p>Additional keyword arguments to pass to the runner.</p> <code>{}</code> <p>Examples:</p> <p>Prepare two deployments and serve them:</p> <pre><code>import datetime\n\nfrom prefect import flow, serve\n\n@flow\ndef my_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef my_other_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\":\n    # Run once a day\n    hello_deploy = my_flow.to_deployment(\n        \"hello\", tags=[\"dev\"], interval=datetime.timedelta(days=1)\n    )\n\n    # Run every Sunday at 4:00 AM\n    bye_deploy = my_other_flow.to_deployment(\n        \"goodbye\", tags=[\"dev\"], cron=\"0 4 * * sun\"\n    )\n\n    serve(hello_deploy, bye_deploy)\n</code></pre> Source code in <code>prefect/flows.py</code> <pre><code>@sync_compatible\nasync def serve(\n    *args: \"RunnerDeployment\",\n    pause_on_shutdown: bool = True,\n    print_starting_message: bool = True,\n    limit: Optional[int] = None,\n    **kwargs,\n):\n    \"\"\"\n    Serve the provided list of deployments.\n\n    Args:\n        *args: A list of deployments to serve.\n        pause_on_shutdown: A boolean for whether or not to automatically pause\n            deployment schedules on shutdown.\n        print_starting_message: Whether or not to print message to the console\n            on startup.\n        limit: The maximum number of runs that can be executed concurrently.\n        **kwargs: Additional keyword arguments to pass to the runner.\n\n    Examples:\n        Prepare two deployments and serve them:\n\n        ```python\n        import datetime\n\n        from prefect import flow, serve\n\n        @flow\n        def my_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def my_other_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\":\n            # Run once a day\n            hello_deploy = my_flow.to_deployment(\n                \"hello\", tags=[\"dev\"], interval=datetime.timedelta(days=1)\n            )\n\n            # Run every Sunday at 4:00 AM\n            bye_deploy = my_other_flow.to_deployment(\n                \"goodbye\", tags=[\"dev\"], cron=\"0 4 * * sun\"\n            )\n\n            serve(hello_deploy, bye_deploy)\n        ```\n    \"\"\"\n    from rich.console import Console, Group\n    from rich.table import Table\n\n    from prefect.runner import Runner\n\n    runner = Runner(pause_on_shutdown=pause_on_shutdown, limit=limit, **kwargs)\n    for deployment in args:\n        await runner.add_deployment(deployment)\n\n    if print_starting_message:\n        help_message_top = (\n            \"[green]Your deployments are being served and polling for\"\n            \" scheduled runs!\\n[/]\"\n        )\n\n        table = Table(title=\"Deployments\", show_header=False)\n\n        table.add_column(style=\"blue\", no_wrap=True)\n\n        for deployment in args:\n            table.add_row(f\"{deployment.flow_name}/{deployment.name}\")\n\n        help_message_bottom = (\n            \"\\nTo trigger any of these deployments, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            \" [DEPLOYMENT_NAME]\\n[/]\"\n        )\n        if PREFECT_UI_URL:\n            help_message_bottom += (\n                \"\\nYou can also trigger your deployments via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments[/]\\n\"\n            )\n\n        console = Console()\n        console.print(\n            Group(help_message_top, table, help_message_bottom), soft_wrap=True\n        )\n\n    await runner.start()\n</code></pre>","tags":["Python API","flows","parameters"]},{"location":"api-ref/prefect/futures/","title":"prefect.futures","text":"","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures","title":"<code>prefect.futures</code>","text":"<p>Futures represent the execution of a task and allow retrieval of the task run's state.</p> <p>This module contains the definition for futures as well as utilities for resolving futures in nested data structures.</p>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture","title":"<code>PrefectFuture</code>","text":"<p>               Bases: <code>Generic[R, A]</code></p> <p>Represents the result of a computation happening in a task runner.</p> <p>When tasks are called, they are submitted to a task runner which creates a future for access to the state and result of the task.</p> <p>Examples:</p> <p>Define a task that returns a string</p> <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task() -&gt; str:\n&gt;&gt;&gt;     return \"hello\"\n</code></pre> <p>Calls of this task in a flow will return a future</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()  # PrefectFuture[str, Sync] includes result type\n&gt;&gt;&gt;     future.task_run.id  # UUID for the task run\n</code></pre> <p>Wait for the task to complete</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     final_state = future.wait()\n</code></pre> <p>Wait N seconds for the task to complete</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     final_state = future.wait(0.1)\n&gt;&gt;&gt;     if final_state:\n&gt;&gt;&gt;         ... # Task done\n&gt;&gt;&gt;     else:\n&gt;&gt;&gt;         ... # Task not done yet\n</code></pre> <p>Wait for a task to complete and retrieve its result</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     result = future.result()\n&gt;&gt;&gt;     assert result == \"hello\"\n</code></pre> <p>Wait N seconds for a task to complete and retrieve its result</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     result = future.result(timeout=5)\n&gt;&gt;&gt;     assert result == \"hello\"\n</code></pre> <p>Retrieve the state of a task without waiting for completion</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task.submit()\n&gt;&gt;&gt;     state = future.get_state()\n</code></pre> Source code in <code>prefect/futures.py</code> <pre><code>class PrefectFuture(Generic[R, A]):\n    \"\"\"\n    Represents the result of a computation happening in a task runner.\n\n    When tasks are called, they are submitted to a task runner which creates a future\n    for access to the state and result of the task.\n\n    Examples:\n        Define a task that returns a string\n\n        &gt;&gt;&gt; from prefect import flow, task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task() -&gt; str:\n        &gt;&gt;&gt;     return \"hello\"\n\n        Calls of this task in a flow will return a future\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()  # PrefectFuture[str, Sync] includes result type\n        &gt;&gt;&gt;     future.task_run.id  # UUID for the task run\n\n        Wait for the task to complete\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     final_state = future.wait()\n\n        Wait N seconds for the task to complete\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     final_state = future.wait(0.1)\n        &gt;&gt;&gt;     if final_state:\n        &gt;&gt;&gt;         ... # Task done\n        &gt;&gt;&gt;     else:\n        &gt;&gt;&gt;         ... # Task not done yet\n\n        Wait for a task to complete and retrieve its result\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     result = future.result()\n        &gt;&gt;&gt;     assert result == \"hello\"\n\n        Wait N seconds for a task to complete and retrieve its result\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     result = future.result(timeout=5)\n        &gt;&gt;&gt;     assert result == \"hello\"\n\n        Retrieve the state of a task without waiting for completion\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task.submit()\n        &gt;&gt;&gt;     state = future.get_state()\n    \"\"\"\n\n    def __init__(\n        self,\n        name: str,\n        key: UUID,\n        task_runner: \"BaseTaskRunner\",\n        asynchronous: A = True,\n        _final_state: State[R] = None,  # Exposed for testing\n    ) -&gt; None:\n        self.key = key\n        self.name = name\n        self.asynchronous = asynchronous\n        self.task_run = None\n        self._final_state = _final_state\n        self._exception: Optional[Exception] = None\n        self._task_runner = task_runner\n        self._submitted = anyio.Event()\n\n        self._loop = asyncio.get_running_loop()\n\n    @overload\n    def wait(\n        self: \"PrefectFuture[R, Async]\", timeout: None = None\n    ) -&gt; Awaitable[State[R]]:\n        ...\n\n    @overload\n    def wait(self: \"PrefectFuture[R, Sync]\", timeout: None = None) -&gt; State[R]:\n        ...\n\n    @overload\n    def wait(\n        self: \"PrefectFuture[R, Async]\", timeout: float\n    ) -&gt; Awaitable[Optional[State[R]]]:\n        ...\n\n    @overload\n    def wait(self: \"PrefectFuture[R, Sync]\", timeout: float) -&gt; Optional[State[R]]:\n        ...\n\n    def wait(self, timeout=None):\n        \"\"\"\n        Wait for the run to finish and return the final state\n\n        If the timeout is reached before the run reaches a final state,\n        `None` is returned.\n        \"\"\"\n        wait = create_call(self._wait, timeout=timeout)\n        if self.asynchronous:\n            return from_async.call_soon_in_loop_thread(wait).aresult()\n        else:\n            # type checking cannot handle the overloaded timeout passing\n            return from_sync.call_soon_in_loop_thread(wait).result()  # type: ignore\n\n    @overload\n    async def _wait(self, timeout: None = None) -&gt; State[R]:\n        ...\n\n    @overload\n    async def _wait(self, timeout: float) -&gt; Optional[State[R]]:\n        ...\n\n    async def _wait(self, timeout=None):\n        \"\"\"\n        Async implementation for `wait`\n        \"\"\"\n        await self._wait_for_submission()\n\n        if self._final_state:\n            return self._final_state\n\n        self._final_state = await self._task_runner.wait(self.key, timeout)\n        return self._final_state\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Sync]\",\n        timeout: float = None,\n        raise_on_failure: bool = True,\n    ) -&gt; R:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Sync]\",\n        timeout: float = None,\n        raise_on_failure: bool = False,\n    ) -&gt; Union[R, Exception]:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Async]\",\n        timeout: float = None,\n        raise_on_failure: bool = True,\n    ) -&gt; Awaitable[R]:\n        ...\n\n    @overload\n    def result(\n        self: \"PrefectFuture[R, Async]\",\n        timeout: float = None,\n        raise_on_failure: bool = False,\n    ) -&gt; Awaitable[Union[R, Exception]]:\n        ...\n\n    def result(self, timeout: float = None, raise_on_failure: bool = True):\n        \"\"\"\n        Wait for the run to finish and return the final state.\n\n        If the timeout is reached before the run reaches a final state, a `TimeoutError`\n        will be raised.\n\n        If `raise_on_failure` is `True` and the task run failed, the task run's\n        exception will be raised.\n        \"\"\"\n        result = create_call(\n            self._result, timeout=timeout, raise_on_failure=raise_on_failure\n        )\n        if self.asynchronous:\n            return from_async.call_soon_in_loop_thread(result).aresult()\n        else:\n            return from_sync.call_soon_in_loop_thread(result).result()\n\n    async def _result(self, timeout: float = None, raise_on_failure: bool = True):\n        \"\"\"\n        Async implementation of `result`\n        \"\"\"\n        final_state = await self._wait(timeout=timeout)\n        if not final_state:\n            raise TimeoutError(\"Call timed out before task finished.\")\n        return await final_state.result(raise_on_failure=raise_on_failure, fetch=True)\n\n    @overload\n    def get_state(\n        self: \"PrefectFuture[R, Async]\", client: PrefectClient = None\n    ) -&gt; Awaitable[State[R]]:\n        ...\n\n    @overload\n    def get_state(\n        self: \"PrefectFuture[R, Sync]\", client: PrefectClient = None\n    ) -&gt; State[R]:\n        ...\n\n    def get_state(self, client: PrefectClient = None):\n        \"\"\"\n        Get the current state of the task run.\n        \"\"\"\n        if self.asynchronous:\n            return cast(Awaitable[State[R]], self._get_state(client=client))\n        else:\n            return cast(State[R], sync(self._get_state, client=client))\n\n    @inject_client\n    async def _get_state(self, client: PrefectClient = None) -&gt; State[R]:\n        assert client is not None  # always injected\n\n        # We must wait for the task run id to be populated\n        await self._wait_for_submission()\n\n        task_run = await client.read_task_run(self.task_run.id)\n\n        if not task_run:\n            raise RuntimeError(\"Future has no associated task run in the server.\")\n\n        # Update the task run reference\n        self.task_run = task_run\n        return task_run.state\n\n    async def _wait_for_submission(self):\n        await run_coroutine_in_loop_from_async(self._loop, self._submitted.wait())\n\n    def __hash__(self) -&gt; int:\n        return hash(self.key)\n\n    def __repr__(self) -&gt; str:\n        return f\"PrefectFuture({self.name!r})\"\n\n    def __bool__(self) -&gt; bool:\n        warnings.warn(\n            (\n                \"A 'PrefectFuture' from a task call was cast to a boolean; \"\n                \"did you mean to check the result of the task instead? \"\n                \"e.g. `if my_task().result(): ...`\"\n            ),\n            stacklevel=2,\n        )\n        return True\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.get_state","title":"<code>get_state</code>","text":"<p>Get the current state of the task run.</p> Source code in <code>prefect/futures.py</code> <pre><code>def get_state(self, client: PrefectClient = None):\n    \"\"\"\n    Get the current state of the task run.\n    \"\"\"\n    if self.asynchronous:\n        return cast(Awaitable[State[R]], self._get_state(client=client))\n    else:\n        return cast(State[R], sync(self._get_state, client=client))\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.result","title":"<code>result</code>","text":"<p>Wait for the run to finish and return the final state.</p> <p>If the timeout is reached before the run reaches a final state, a <code>TimeoutError</code> will be raised.</p> <p>If <code>raise_on_failure</code> is <code>True</code> and the task run failed, the task run's exception will be raised.</p> Source code in <code>prefect/futures.py</code> <pre><code>def result(self, timeout: float = None, raise_on_failure: bool = True):\n    \"\"\"\n    Wait for the run to finish and return the final state.\n\n    If the timeout is reached before the run reaches a final state, a `TimeoutError`\n    will be raised.\n\n    If `raise_on_failure` is `True` and the task run failed, the task run's\n    exception will be raised.\n    \"\"\"\n    result = create_call(\n        self._result, timeout=timeout, raise_on_failure=raise_on_failure\n    )\n    if self.asynchronous:\n        return from_async.call_soon_in_loop_thread(result).aresult()\n    else:\n        return from_sync.call_soon_in_loop_thread(result).result()\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.PrefectFuture.wait","title":"<code>wait</code>","text":"<p>Wait for the run to finish and return the final state</p> <p>If the timeout is reached before the run reaches a final state, <code>None</code> is returned.</p> Source code in <code>prefect/futures.py</code> <pre><code>def wait(self, timeout=None):\n    \"\"\"\n    Wait for the run to finish and return the final state\n\n    If the timeout is reached before the run reaches a final state,\n    `None` is returned.\n    \"\"\"\n    wait = create_call(self._wait, timeout=timeout)\n    if self.asynchronous:\n        return from_async.call_soon_in_loop_thread(wait).aresult()\n    else:\n        # type checking cannot handle the overloaded timeout passing\n        return from_sync.call_soon_in_loop_thread(wait).result()  # type: ignore\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.call_repr","title":"<code>call_repr</code>","text":"<p>Generate a repr for a function call as \"fn_name(arg_value, kwarg_name=kwarg_value)\"</p> Source code in <code>prefect/futures.py</code> <pre><code>def call_repr(__fn: Callable, *args: Any, **kwargs: Any) -&gt; str:\n    \"\"\"\n    Generate a repr for a function call as \"fn_name(arg_value, kwarg_name=kwarg_value)\"\n    \"\"\"\n\n    name = __fn.__name__\n\n    # TODO: If this computation is concerningly expensive, we can iterate checking the\n    #       length at each arg or avoid calling `repr` on args with large amounts of\n    #       data\n    call_args = \", \".join(\n        [repr(arg) for arg in args]\n        + [f\"{key}={repr(val)}\" for key, val in kwargs.items()]\n    )\n\n    # Enforce a maximum length\n    if len(call_args) &gt; 100:\n        call_args = call_args[:100] + \"...\"\n\n    return f\"{name}({call_args})\"\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.resolve_futures_to_data","title":"<code>resolve_futures_to_data</code>  <code>async</code>","text":"<p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a new collection with the same structure with futures resolved to their results. Resolving futures to their results may wait for execution to complete and require communication with the API.</p> <p>Unsupported object types will be returned without modification.</p> Source code in <code>prefect/futures.py</code> <pre><code>async def resolve_futures_to_data(\n    expr: Union[PrefectFuture[R, Any], Any],\n    raise_on_failure: bool = True,\n) -&gt; Union[R, Any]:\n    \"\"\"\n    Given a Python built-in collection, recursively find `PrefectFutures` and build a\n    new collection with the same structure with futures resolved to their results.\n    Resolving futures to their results may wait for execution to complete and require\n    communication with the API.\n\n    Unsupported object types will be returned without modification.\n    \"\"\"\n    futures: Set[PrefectFuture] = set()\n\n    maybe_expr = visit_collection(\n        expr,\n        visit_fn=partial(_collect_futures, futures),\n        return_data=False,\n        context={},\n    )\n    if maybe_expr is not None:\n        expr = maybe_expr\n\n    # Get results\n    results = await asyncio.gather(\n        *[\n            # We must wait for the future in the thread it was created in\n            from_async.call_soon_in_loop_thread(\n                create_call(future._result, raise_on_failure=raise_on_failure)\n            ).aresult()\n            for future in futures\n        ]\n    )\n\n    results_by_future = dict(zip(futures, results))\n\n    def replace_futures_with_results(expr, context):\n        # Expressions inside quotes should not be modified\n        if isinstance(context.get(\"annotation\"), quote):\n            raise StopVisiting()\n\n        if isinstance(expr, PrefectFuture):\n            return results_by_future[expr]\n        else:\n            return expr\n\n    return visit_collection(\n        expr,\n        visit_fn=replace_futures_with_results,\n        return_data=True,\n        context={},\n    )\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/futures/#prefect.futures.resolve_futures_to_states","title":"<code>resolve_futures_to_states</code>  <code>async</code>","text":"<p>Given a Python built-in collection, recursively find <code>PrefectFutures</code> and build a new collection with the same structure with futures resolved to their final states. Resolving futures to their final states may wait for execution to complete.</p> <p>Unsupported object types will be returned without modification.</p> Source code in <code>prefect/futures.py</code> <pre><code>async def resolve_futures_to_states(\n    expr: Union[PrefectFuture[R, Any], Any],\n) -&gt; Union[State[R], Any]:\n    \"\"\"\n    Given a Python built-in collection, recursively find `PrefectFutures` and build a\n    new collection with the same structure with futures resolved to their final states.\n    Resolving futures to their final states may wait for execution to complete.\n\n    Unsupported object types will be returned without modification.\n    \"\"\"\n    futures: Set[PrefectFuture] = set()\n\n    visit_collection(\n        expr,\n        visit_fn=partial(_collect_futures, futures),\n        return_data=False,\n        context={},\n    )\n\n    # Get final states for each future\n    states = await asyncio.gather(\n        *[\n            # We must wait for the future in the thread it was created in\n            from_async.call_soon_in_loop_thread(create_call(future._wait)).aresult()\n            for future in futures\n        ]\n    )\n\n    states_by_future = dict(zip(futures, states))\n\n    def replace_futures_with_states(expr, context):\n        # Expressions inside quotes should not be modified\n        if isinstance(context.get(\"annotation\"), quote):\n            raise StopVisiting()\n\n        if isinstance(expr, PrefectFuture):\n            return states_by_future[expr]\n        else:\n            return expr\n\n    return visit_collection(\n        expr,\n        visit_fn=replace_futures_with_states,\n        return_data=True,\n        context={},\n    )\n</code></pre>","tags":["Python API","tasks","futures","states"]},{"location":"api-ref/prefect/infrastructure/","title":"prefect.infrastructure","text":"","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure","title":"<code>prefect.infrastructure</code>","text":"","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer","title":"<code>DockerContainer</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Runs a command in a container.</p> <p>Requires a Docker Engine to be connectable. Docker settings will be retrieved from the environment.</p> <p>Click here to see a tutorial.</p> <p>Attributes:</p> Name Type Description <code>auto_remove</code> <code>bool</code> <p>If set, the container will be removed on completion. Otherwise, the container will remain after exit for inspection.</p> <code>command</code> <code>bool</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>env</code> <code>bool</code> <p>Environment variables to set for the container.</p> <code>image</code> <code>str</code> <p>An optional string specifying the tag of a Docker image to use. Defaults to the Prefect image.</p> <code>image_pull_policy</code> <code>Optional[ImagePullPolicy]</code> <p>Specifies if the image should be pulled. One of 'ALWAYS', 'NEVER', 'IF_NOT_PRESENT'.</p> <code>image_registry</code> <code>Optional[DockerRegistry]</code> <p>A <code>DockerRegistry</code> block containing credentials to use if <code>image</code> is stored in a private image registry.</p> <code>labels</code> <code>Optional[DockerRegistry]</code> <p>An optional dictionary of labels, mapping name to value.</p> <code>name</code> <code>Optional[DockerRegistry]</code> <p>An optional name for the container.</p> <code>network_mode</code> <code>Optional[str]</code> <p>Set the network mode for the created container. Defaults to 'host' if a local API url is detected, otherwise the Docker default of 'bridge' is used. If 'networks' is set, this cannot be set.</p> <code>networks</code> <code>List[str]</code> <p>An optional list of strings specifying Docker networks to connect the container to.</p> <code>stream_output</code> <code>bool</code> <p>If set, stream output from the container to local standard output.</p> <code>volumes</code> <code>List[str]</code> <p>An optional list of volume mount strings in the format of \"local_path:container_path\".</p> <code>memswap_limit</code> <code>Union[int, str]</code> <p>Total memory (memory + swap), -1 to disable swap. Should only be set if <code>mem_limit</code> is also set. If <code>mem_limit</code> is set, this defaults to allowing the container to use as much swap as memory. For example, if <code>mem_limit</code> is 300m and <code>memswap_limit</code> is not set, the container can use 600m in total of memory and swap.</p> <code>mem_limit</code> <code>Union[float, str]</code> <p>Memory limit of the created container. Accepts float values to enforce a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g. If a string is given without a unit, bytes are assumed.</p> <code>privileged</code> <code>bool</code> <p>Give extended privileges to this container.</p>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer--connecting-to-a-locally-hosted-prefect-api","title":"Connecting to a locally hosted Prefect API","text":"<p>If using a local API URL on Linux, we will update the network mode default to 'host' to enable connectivity. If using another OS or an alternative network mode is used, we will replace 'localhost' in the API URL with 'host.docker.internal'. Generally, this will enable connectivity, but the API URL can be provided as an environment variable to override inference in more complex use-cases.</p> <p>Note, if using 'host.docker.internal' in the API URL on Linux, the API must be bound to 0.0.0.0 or the Docker IP address to allow connectivity. On macOS, this is not necessary and the API is connectable while bound to localhost.</p> Source code in <code>prefect/infrastructure/container.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the Docker worker from prefect-docker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass DockerContainer(Infrastructure):\n    \"\"\"\n    Runs a command in a container.\n\n    Requires a Docker Engine to be connectable. Docker settings will be retrieved from\n    the environment.\n\n    Click [here](https://docs.prefect.io/guides/deployment/docker) to see a tutorial.\n\n    Attributes:\n        auto_remove: If set, the container will be removed on completion. Otherwise,\n            the container will remain after exit for inspection.\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        env: Environment variables to set for the container.\n        image: An optional string specifying the tag of a Docker image to use.\n            Defaults to the Prefect image.\n        image_pull_policy: Specifies if the image should be pulled. One of 'ALWAYS',\n            'NEVER', 'IF_NOT_PRESENT'.\n        image_registry: A `DockerRegistry` block containing credentials to use if `image` is stored in a private\n            image registry.\n        labels: An optional dictionary of labels, mapping name to value.\n        name: An optional name for the container.\n        network_mode: Set the network mode for the created container. Defaults to 'host'\n            if a local API url is detected, otherwise the Docker default of 'bridge' is\n            used. If 'networks' is set, this cannot be set.\n        networks: An optional list of strings specifying Docker networks to connect the\n            container to.\n        stream_output: If set, stream output from the container to local standard output.\n        volumes: An optional list of volume mount strings in the format of\n            \"local_path:container_path\".\n        memswap_limit: Total memory (memory + swap), -1 to disable swap. Should only be\n            set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\n            allowing the container to use as much swap as memory. For example, if\n            `mem_limit` is 300m and `memswap_limit` is not set, the container can use\n            600m in total of memory and swap.\n        mem_limit: Memory limit of the created container. Accepts float values to enforce\n            a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g.\n            If a string is given without a unit, bytes are assumed.\n        privileged: Give extended privileges to this container.\n\n    ## Connecting to a locally hosted Prefect API\n\n    If using a local API URL on Linux, we will update the network mode default to 'host'\n    to enable connectivity. If using another OS or an alternative network mode is used,\n    we will replace 'localhost' in the API URL with 'host.docker.internal'. Generally,\n    this will enable connectivity, but the API URL can be provided as an environment\n    variable to override inference in more complex use-cases.\n\n    Note, if using 'host.docker.internal' in the API URL on Linux, the API must be bound\n    to 0.0.0.0 or the Docker IP address to allow connectivity. On macOS, this is not\n    necessary and the API is connectable while bound to localhost.\n    \"\"\"\n\n    type: Literal[\"docker-container\"] = Field(\n        default=\"docker-container\", description=\"The type of infrastructure.\"\n    )\n    image: str = Field(\n        default_factory=get_prefect_image_name,\n        description=\"Tag of a Docker image to use. Defaults to the Prefect image.\",\n    )\n    image_pull_policy: Optional[ImagePullPolicy] = Field(\n        default=None, description=\"Specifies if the image should be pulled.\"\n    )\n    image_registry: Optional[DockerRegistry] = None\n    networks: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"A list of strings specifying Docker networks to connect the container to.\"\n        ),\n    )\n    network_mode: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The network mode for the created container (e.g. host, bridge). If\"\n            \" 'networks' is set, this cannot be set.\"\n        ),\n    )\n    auto_remove: bool = Field(\n        default=False,\n        description=\"If set, the container will be removed on completion.\",\n    )\n    volumes: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"A list of volume mount strings in the format of\"\n            ' \"local_path:container_path\".'\n        ),\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, the output will be streamed from the container to local standard\"\n            \" output.\"\n        ),\n    )\n    memswap_limit: Union[int, str] = Field(\n        default=None,\n        description=(\n            \"Total memory (memory + swap), -1 to disable swap. Should only be \"\n            \"set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\"\n            \"allowing the container to use as much swap as memory. For example, if \"\n            \"`mem_limit` is 300m and `memswap_limit` is not set, the container can use \"\n            \"600m in total of memory and swap.\"\n        ),\n    )\n    mem_limit: Union[float, str] = Field(\n        default=None,\n        description=(\n            \"Memory limit of the created container. Accepts float values to enforce \"\n            \"a limit in bytes or a string with a unit e.g. 100000b, 1000k, 128m, 1g. \"\n            \"If a string is given without a unit, bytes are assumed.\"\n        ),\n    )\n    privileged: bool = Field(\n        default=False,\n        description=\"Give extended privileges to this container.\",\n    )\n\n    _block_type_name = \"Docker Container\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainer\"\n\n    @validator(\"labels\")\n    def convert_labels_to_docker_format(cls, labels: Dict[str, str]):\n        labels = labels or {}\n        new_labels = {}\n        for name, value in labels.items():\n            if \"/\" in name:\n                namespace, key = name.split(\"/\", maxsplit=1)\n                new_namespace = \".\".join(reversed(namespace.split(\".\")))\n                new_labels[f\"{new_namespace}.{key}\"] = value\n            else:\n                new_labels[name] = value\n        return new_labels\n\n    @validator(\"volumes\")\n    def check_volume_format(cls, volumes):\n        for volume in volumes:\n            if \":\" not in volume:\n                raise ValueError(\n                    \"Invalid volume specification. \"\n                    f\"Expected format 'path:container_path', but got {volume!r}\"\n                )\n\n        return volumes\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; Optional[bool]:\n        if not self.command:\n            raise ValueError(\"Docker container cannot be run with empty command.\")\n\n        # The `docker` library uses requests instead of an async http library so it must\n        # be run in a thread to avoid blocking the event loop.\n        container = await run_sync_in_worker_thread(self._create_and_start_container)\n        container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n        # Mark as started and return the infrastructure id\n        if task_status:\n            task_status.started(container_pid)\n\n        # Monitor the container\n        container = await run_sync_in_worker_thread(\n            self._watch_container_safe, container\n        )\n\n        exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n        return DockerContainerResult(\n            status_code=exit_code if exit_code is not None else -1,\n            identifier=container_pid,\n        )\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        docker_client = self._get_client()\n        base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n\n        if docker_client.api.base_url != base_url:\n            raise InfrastructureNotAvailable(\n                \"\".join(\n                    [\n                        (\n                            f\"Unable to stop container {container_id!r}: the current\"\n                            \" Docker API \"\n                        ),\n                        (\n                            f\"URL {docker_client.api.base_url!r} does not match the\"\n                            \" expected \"\n                        ),\n                        f\"API base URL {base_url}.\",\n                    ]\n                )\n            )\n        try:\n            container = docker_client.containers.get(container_id=container_id)\n        except docker.errors.NotFound:\n            raise InfrastructureNotFound(\n                f\"Unable to stop container {container_id!r}: The container was not\"\n                \" found.\"\n            )\n\n        try:\n            container.stop(timeout=grace_seconds)\n        except Exception:\n            raise\n\n    def preview(self):\n        # TODO: build and document a more sophisticated preview\n        docker_client = self._get_client()\n        try:\n            return json.dumps(self._build_container_settings(docker_client))\n        finally:\n            docker_client.close()\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type()\n        )\n        if base_job_template is None:\n            return await super().generate_work_pool_base_job_template()\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key == \"image_registry\":\n                self.logger.warning(\n                    \"Image registry blocks are not supported by Docker\"\n                    \" work pools. Please authenticate to your registry using\"\n                    \" the `docker login` command on your worker instances.\"\n                )\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"image_pull_policy\":\n                new_value = None\n                if value == ImagePullPolicy.ALWAYS:\n                    new_value = \"Always\"\n                elif value == ImagePullPolicy.NEVER:\n                    new_value = \"Never\"\n                elif value == ImagePullPolicy.IF_NOT_PRESENT:\n                    new_value = \"IfNotPresent\"\n\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = new_value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Docker work pools. Skipping.\"\n                )\n\n        return base_job_template\n\n    def get_corresponding_worker_type(self):\n        return \"docker\"\n\n    def _get_infrastructure_pid(self, container_id: str) -&gt; str:\n        \"\"\"Generates a Docker infrastructure_pid string in the form of\n        `&lt;docker_host_base_url&gt;:&lt;container_id&gt;`.\n        \"\"\"\n        docker_client = self._get_client()\n        base_url = docker_client.api.base_url\n        docker_client.close()\n        return f\"{base_url}:{container_id}\"\n\n    def _parse_infrastructure_pid(self, infrastructure_pid: str) -&gt; Tuple[str, str]:\n        \"\"\"Splits a Docker infrastructure_pid into its component parts\"\"\"\n\n        # base_url can contain `:` so we only want the last item of the split\n        base_url, container_id = infrastructure_pid.rsplit(\":\", 1)\n        return base_url, str(container_id)\n\n    def _build_container_settings(\n        self,\n        docker_client: \"DockerClient\",\n    ) -&gt; Dict:\n        network_mode = self._get_network_mode()\n        return dict(\n            image=self.image,\n            network=self.networks[0] if self.networks else None,\n            network_mode=network_mode,\n            command=self.command,\n            environment=self._get_environment_variables(network_mode),\n            auto_remove=self.auto_remove,\n            labels={**CONTAINER_LABELS, **self.labels},\n            extra_hosts=self._get_extra_hosts(docker_client),\n            name=self._get_container_name(),\n            volumes=self.volumes,\n            mem_limit=self.mem_limit,\n            memswap_limit=self.memswap_limit,\n            privileged=self.privileged,\n        )\n\n    def _create_and_start_container(self) -&gt; \"Container\":\n        if self.image_registry:\n            # If an image registry block was supplied, load an authenticated Docker\n            # client from the block. Otherwise, use an unauthenticated client to\n            # pull images from public registries.\n            docker_client = self.image_registry.get_docker_client()\n        else:\n            docker_client = self._get_client()\n        container_settings = self._build_container_settings(docker_client)\n\n        if self._should_pull_image(docker_client):\n            self.logger.info(f\"Pulling image {self.image!r}...\")\n            self._pull_image(docker_client)\n\n        container = self._create_container(docker_client, **container_settings)\n\n        # Add additional networks after the container is created; only one network can\n        # be attached at creation time\n        if len(self.networks) &gt; 1:\n            for network_name in self.networks[1:]:\n                network = docker_client.networks.get(network_name)\n                network.connect(container)\n\n        # Start the container\n        container.start()\n\n        docker_client.close()\n\n        return container\n\n    def _get_image_and_tag(self) -&gt; Tuple[str, Optional[str]]:\n        return parse_image_tag(self.image)\n\n    def _determine_image_pull_policy(self) -&gt; ImagePullPolicy:\n        \"\"\"\n        Determine the appropriate image pull policy.\n\n        1. If they specified an image pull policy, use that.\n\n        2. If they did not specify an image pull policy and gave us\n           the \"latest\" tag, use ImagePullPolicy.always.\n\n        3. If they did not specify an image pull policy and did not\n           specify a tag, use ImagePullPolicy.always.\n\n        4. If they did not specify an image pull policy and gave us\n           a tag other than \"latest\", use ImagePullPolicy.if_not_present.\n\n        This logic matches the behavior of Kubernetes.\n        See:https://kubernetes.io/docs/concepts/containers/images/#imagepullpolicy-defaulting\n        \"\"\"\n        if not self.image_pull_policy:\n            _, tag = self._get_image_and_tag()\n            if tag == \"latest\" or not tag:\n                return ImagePullPolicy.ALWAYS\n            return ImagePullPolicy.IF_NOT_PRESENT\n        return self.image_pull_policy\n\n    def _get_network_mode(self) -&gt; Optional[str]:\n        # User's value takes precedence; this may collide with the incompatible options\n        # mentioned below.\n        if self.network_mode:\n            if sys.platform != \"linux\" and self.network_mode == \"host\":\n                warnings.warn(\n                    f\"{self.network_mode!r} network mode is not supported on platform \"\n                    f\"{sys.platform!r} and may not work as intended.\"\n                )\n            return self.network_mode\n\n        # Network mode is not compatible with networks or ports (we do not support ports\n        # yet though)\n        if self.networks:\n            return None\n\n        # Check for a local API connection\n        api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n        if api_url:\n            try:\n                _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n            except Exception as exc:\n                warnings.warn(\n                    f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                    f\"{exc}\\nThe network mode will not be inferred.\"\n                )\n                return None\n\n            host = netloc.split(\":\")[0]\n\n            # If using a locally hosted API, use a host network on linux\n            if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n                return \"host\"\n\n        # Default to unset\n        return None\n\n    def _should_pull_image(self, docker_client: \"DockerClient\") -&gt; bool:\n        \"\"\"\n        Decide whether we need to pull the Docker image.\n        \"\"\"\n        image_pull_policy = self._determine_image_pull_policy()\n\n        if image_pull_policy is ImagePullPolicy.ALWAYS:\n            return True\n        elif image_pull_policy is ImagePullPolicy.NEVER:\n            return False\n        elif image_pull_policy is ImagePullPolicy.IF_NOT_PRESENT:\n            try:\n                # NOTE: images.get() wants the tag included with the image\n                # name, while images.pull() wants them split.\n                docker_client.images.get(self.image)\n            except docker.errors.ImageNotFound:\n                self.logger.debug(f\"Could not find Docker image locally: {self.image}\")\n                return True\n        return False\n\n    def _pull_image(self, docker_client: \"DockerClient\"):\n        \"\"\"\n        Pull the image we're going to use to create the container.\n        \"\"\"\n        image, tag = self._get_image_and_tag()\n\n        return docker_client.images.pull(image, tag)\n\n    def _create_container(self, docker_client: \"DockerClient\", **kwargs) -&gt; \"Container\":\n        \"\"\"\n        Create a docker container with retries on name conflicts.\n\n        If the container already exists with the given name, an incremented index is\n        added.\n        \"\"\"\n        # Create the container with retries on name conflicts (with an incremented idx)\n        index = 0\n        container = None\n        name = original_name = kwargs.pop(\"name\")\n\n        while not container:\n            from docker.errors import APIError\n\n            try:\n                display_name = repr(name) if name else \"with auto-generated name\"\n                self.logger.info(f\"Creating Docker container {display_name}...\")\n                container = docker_client.containers.create(name=name, **kwargs)\n            except APIError as exc:\n                if \"Conflict\" in str(exc) and \"container name\" in str(exc):\n                    self.logger.info(\n                        f\"Docker container name {display_name} already exists; \"\n                        \"retrying...\"\n                    )\n                    index += 1\n                    name = f\"{original_name}-{index}\"\n                else:\n                    raise\n\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        return container\n\n    def _watch_container_safe(self, container: \"Container\") -&gt; \"Container\":\n        # Monitor the container capturing the latest snapshot while capturing\n        # not found errors\n        docker_client = self._get_client()\n\n        try:\n            for latest_container in self._watch_container(docker_client, container.id):\n                container = latest_container\n        except docker.errors.NotFound:\n            # The container was removed during watching\n            self.logger.warning(\n                f\"Docker container {container.name} was removed before we could wait \"\n                \"for its completion.\"\n            )\n        finally:\n            docker_client.close()\n\n        return container\n\n    def _watch_container(\n        self, docker_client: \"DockerClient\", container_id: str\n    ) -&gt; Generator[None, None, \"Container\"]:\n        container: \"Container\" = docker_client.containers.get(container_id)\n\n        status = container.status\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n        if self.stream_output:\n            try:\n                for log in container.logs(stream=True):\n                    log: bytes\n                    print(log.decode().rstrip())\n            except docker.errors.APIError as exc:\n                if \"marked for removal\" in str(exc):\n                    self.logger.warning(\n                        f\"Docker container {container.name} was marked for removal\"\n                        \" before logs could be retrieved. Output will not be\"\n                        \" streamed. \"\n                    )\n                else:\n                    self.logger.exception(\n                        \"An unexpected Docker API error occurred while streaming\"\n                        f\" output from container {container.name}.\"\n                    )\n\n            container.reload()\n            if container.status != status:\n                self.logger.info(\n                    f\"Docker container {container.name!r} has status\"\n                    f\" {container.status!r}\"\n                )\n            yield container\n\n        container.wait()\n        self.logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n    def _get_client(self):\n        try:\n            with warnings.catch_warnings():\n                # Silence warnings due to use of deprecated methods within dockerpy\n                # See https://github.com/docker/docker-py/pull/2931\n                warnings.filterwarnings(\n                    \"ignore\",\n                    message=\"distutils Version classes are deprecated.*\",\n                    category=DeprecationWarning,\n                )\n\n                docker_client = docker.from_env()\n\n        except docker.errors.DockerException as exc:\n            raise RuntimeError(\"Could not connect to Docker.\") from exc\n\n        return docker_client\n\n    def _get_container_name(self) -&gt; Optional[str]:\n        \"\"\"\n        Generates a container name to match the configured name, ensuring it is Docker\n        compatible.\n        \"\"\"\n        # Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+` in the end\n        if not self.name:\n            return None\n\n        return (\n            slugify(\n                self.name,\n                lowercase=False,\n                # Docker does not limit length but URL limits apply eventually so\n                # limit the length for safety\n                max_length=250,\n                # Docker allows these characters for container names\n                regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n            ).lstrip(\n                # Docker does not allow leading underscore, dash, or period\n                \"_-.\"\n            )\n            # Docker does not allow 0 character names so cast to null if the name is\n            # empty after slufification\n            or None\n        )\n\n    def _get_extra_hosts(self, docker_client) -&gt; Dict[str, str]:\n        \"\"\"\n        A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n        with the API on Linux machines. Docker Desktop on macOS will automatically\n        already have this mapping.\n        \"\"\"\n        if sys.platform == \"linux\" and (\n            # Do not warn if the user has specified a host manually that does not use\n            # a local address\n            \"PREFECT_API_URL\" not in self.env\n            or re.search(\n                \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n                self.env[\"PREFECT_API_URL\"],\n            )\n        ):\n            user_version = packaging.version.parse(\n                format_outlier_version_name(docker_client.version()[\"Version\"])\n            )\n            required_version = packaging.version.parse(\"20.10.0\")\n\n            if user_version &lt; required_version:\n                warnings.warn(\n                    \"`host.docker.internal` could not be automatically resolved to\"\n                    \" your local ip address. This feature is not supported on Docker\"\n                    f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                    \" encounter issues.\"\n                )\n                return {}\n            else:\n                # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n                # Only supported by Docker v20.10.0+ which is our minimum recommend version\n                return {\"host.docker.internal\": \"host-gateway\"}\n\n    def _get_environment_variables(self, network_mode):\n        # If the API URL has been set by the base environment rather than the by the\n        # user, update the value to ensure connectivity when using a bridge network by\n        # updating local connections to use the docker internal host unless the\n        # network mode is \"host\" where localhost is available already.\n        env = {**self._base_environment(), **self.env}\n\n        if (\n            \"PREFECT_API_URL\" in env\n            and \"PREFECT_API_URL\" not in self.env\n            and network_mode != \"host\"\n        ):\n            env[\"PREFECT_API_URL\"] = (\n                env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", \"host.docker.internal\")\n                .replace(\"127.0.0.1\", \"host.docker.internal\")\n            )\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.DockerContainerResult","title":"<code>DockerContainerResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about a completed Docker container</p> Source code in <code>prefect/infrastructure/container.py</code> <pre><code>class DockerContainerResult(InfrastructureResult):\n    \"\"\"Contains information about a completed Docker container\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure","title":"<code>Infrastructure</code>","text":"<p>               Bases: <code>Block</code>, <code>ABC</code></p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the `BaseWorker` class to create custom infrastructure integrations instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Infrastructure(Block, abc.ABC):\n    _block_schema_capabilities = [\"run-infrastructure\"]\n\n    type: str\n\n    env: Dict[str, Optional[str]] = pydantic.Field(\n        default_factory=dict,\n        title=\"Environment\",\n        description=\"Environment variables to set in the configured infrastructure.\",\n    )\n    labels: Dict[str, str] = pydantic.Field(\n        default_factory=dict,\n        description=\"Labels applied to the infrastructure for metadata purposes.\",\n    )\n    name: Optional[str] = pydantic.Field(\n        default=None,\n        description=\"Name applied to the infrastructure for identification.\",\n    )\n    command: Optional[List[str]] = pydantic.Field(\n        default=None,\n        description=\"The command to run in the infrastructure.\",\n    )\n\n    async def generate_work_pool_base_job_template(self):\n        if self._block_document_id is None:\n            raise BlockNotSavedError(\n                \"Cannot publish as work pool, block has not been saved. Please call\"\n                \" `.save()` on your block before publishing.\"\n            )\n\n        block_schema = self.__class__.schema()\n        return {\n            \"job_configuration\": {\"block\": \"{{ block }}\"},\n            \"variables\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"block\": {\n                        \"title\": \"Block\",\n                        \"description\": (\n                            \"The infrastructure block to use for job creation.\"\n                        ),\n                        \"allOf\": [{\"$ref\": f\"#/definitions/{self.__class__.__name__}\"}],\n                        \"default\": {\n                            \"$ref\": {\"block_document_id\": str(self._block_document_id)}\n                        },\n                    }\n                },\n                \"required\": [\"block\"],\n                \"definitions\": {self.__class__.__name__: block_schema},\n            },\n        }\n\n    def get_corresponding_worker_type(self):\n        return \"block\"\n\n    @sync_compatible\n    async def publish_as_work_pool(self, work_pool_name: Optional[str] = None):\n        \"\"\"\n        Creates a work pool configured to use the given block as the job creator.\n\n        Used to migrate from a agents setup to a worker setup.\n\n        Args:\n            work_pool_name: The name to give to the created work pool. If not provided, the name of the current\n                block will be used.\n        \"\"\"\n\n        base_job_template = await self.generate_work_pool_base_job_template()\n        work_pool_name = work_pool_name or self._block_document_name\n\n        if work_pool_name is None:\n            raise ValueError(\n                \"`work_pool_name` must be provided if the block has not been saved.\"\n            )\n\n        console = Console()\n\n        try:\n            async with prefect.get_client() as client:\n                work_pool = await client.create_work_pool(\n                    work_pool=WorkPoolCreate(\n                        name=work_pool_name,\n                        type=self.get_corresponding_worker_type(),\n                        base_job_template=base_job_template,\n                    )\n                )\n        except ObjectAlreadyExists:\n            console.print(\n                (\n                    f\"Work pool with name {work_pool_name!r} already exists, please use\"\n                    \" a different name.\"\n                ),\n                style=\"red\",\n            )\n            return\n\n        console.print(\n            f\"Work pool {work_pool.name} created!\",\n            style=\"green\",\n        )\n        if PREFECT_UI_URL:\n            console.print(\n                \"You see your new work pool in the UI at\"\n                f\" {PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n            )\n\n        deploy_script = (\n            \"my_flow.deploy(work_pool_name='{work_pool.name}', image='my_image:tag')\"\n        )\n        if not hasattr(self, \"image\"):\n            deploy_script = (\n                \"my_flow.from_source(source='https://github.com/org/repo.git',\"\n                f\" entrypoint='flow.py:my_flow').deploy(work_pool_name='{work_pool.name}')\"\n            )\n        console.print(\n            \"\\nYou can deploy a flow to this work pool by calling\"\n            f\" [blue].deploy[/]:\\n\\n\\t{deploy_script}\\n\"\n        )\n        console.print(\n            \"\\nTo start a worker to execute flow runs in this work pool run:\\n\"\n        )\n        console.print(f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\")\n\n    @abc.abstractmethod\n    async def run(\n        self,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; InfrastructureResult:\n        \"\"\"\n        Run the infrastructure.\n\n        If provided a `task_status`, the status will be reported as started when the\n        infrastructure is successfully created. The status return value will be an\n        identifier for the infrastructure.\n\n        The call will then monitor the created infrastructure, returning a result at\n        the end containing a status code indicating if the infrastructure exited cleanly\n        or encountered an error.\n        \"\"\"\n        # Note: implementations should include `sync_compatible`\n\n    @abc.abstractmethod\n    def preview(self) -&gt; str:\n        \"\"\"\n        View a preview of the infrastructure that would be run.\n        \"\"\"\n\n    @property\n    def logger(self):\n        return get_logger(f\"prefect.infrastructure.{self.type}\")\n\n    @property\n    def is_using_a_runner(self):\n        return self.command is not None and \"prefect flow-run execute\" in shlex.join(\n            self.command\n        )\n\n    @classmethod\n    def _base_environment(cls) -&gt; Dict[str, str]:\n        \"\"\"\n        Environment variables that should be passed to all created infrastructure.\n\n        These values should be overridable with the `env` field.\n        \"\"\"\n        return get_current_settings().to_environment_variables(exclude_unset=True)\n\n    def prepare_for_flow_run(\n        self: Self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"Deployment\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Return an infrastructure block that is prepared to execute a flow run.\n        \"\"\"\n        if deployment is not None:\n            deployment_labels = self._base_deployment_labels(deployment)\n        else:\n            deployment_labels = {}\n\n        if flow is not None:\n            flow_labels = self._base_flow_labels(flow)\n        else:\n            flow_labels = {}\n\n        return self.copy(\n            update={\n                \"env\": {**self._base_flow_run_environment(flow_run), **self.env},\n                \"labels\": {\n                    **self._base_flow_run_labels(flow_run),\n                    **deployment_labels,\n                    **flow_labels,\n                    **self.labels,\n                },\n                \"name\": self.name or flow_run.name,\n                \"command\": self.command or self._base_flow_run_command(),\n            }\n        )\n\n    @staticmethod\n    def _base_flow_run_command() -&gt; List[str]:\n        \"\"\"\n        Generate a command for a flow run job.\n        \"\"\"\n        if experiment_enabled(\"enhanced_cancellation\"):\n            if (\n                PREFECT_EXPERIMENTAL_WARN\n                and PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION\n            ):\n                warnings.warn(\n                    EXPERIMENTAL_WARNING.format(\n                        feature=\"Enhanced flow run cancellation\",\n                        group=\"enhanced_cancellation\",\n                        help=\"\",\n                    ),\n                    ExperimentalFeature,\n                    stacklevel=3,\n                )\n            return [\"prefect\", \"flow-run\", \"execute\"]\n\n        return [\"python\", \"-m\", \"prefect.engine\"]\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": prefect.__version__,\n        }\n\n    @staticmethod\n    def _base_flow_run_environment(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of environment variables for a flow run job.\n        \"\"\"\n        environment = {}\n        environment[\"PREFECT__FLOW_RUN_ID\"] = str(flow_run.id)\n        return environment\n\n    @staticmethod\n    def _base_deployment_labels(deployment: \"Deployment\") -&gt; Dict[str, str]:\n        labels = {\n            \"prefect.io/deployment-name\": deployment.name,\n        }\n        if deployment.updated is not None:\n            labels[\"prefect.io/deployment-updated\"] = deployment.updated.in_timezone(\n                \"utc\"\n            ).to_iso8601_string()\n        return labels\n\n    @staticmethod\n    def _base_flow_labels(flow: \"Flow\") -&gt; Dict[str, str]:\n        return {\n            \"prefect.io/flow-name\": flow.name,\n        }\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Return an infrastructure block that is prepared to execute a flow run.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>def prepare_for_flow_run(\n    self: Self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"Deployment\"] = None,\n    flow: Optional[\"Flow\"] = None,\n) -&gt; Self:\n    \"\"\"\n    Return an infrastructure block that is prepared to execute a flow run.\n    \"\"\"\n    if deployment is not None:\n        deployment_labels = self._base_deployment_labels(deployment)\n    else:\n        deployment_labels = {}\n\n    if flow is not None:\n        flow_labels = self._base_flow_labels(flow)\n    else:\n        flow_labels = {}\n\n    return self.copy(\n        update={\n            \"env\": {**self._base_flow_run_environment(flow_run), **self.env},\n            \"labels\": {\n                **self._base_flow_run_labels(flow_run),\n                **deployment_labels,\n                **flow_labels,\n                **self.labels,\n            },\n            \"name\": self.name or flow_run.name,\n            \"command\": self.command or self._base_flow_run_command(),\n        }\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.preview","title":"<code>preview</code>  <code>abstractmethod</code>","text":"<p>View a preview of the infrastructure that would be run.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@abc.abstractmethod\ndef preview(self) -&gt; str:\n    \"\"\"\n    View a preview of the infrastructure that would be run.\n    \"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.publish_as_work_pool","title":"<code>publish_as_work_pool</code>  <code>async</code>","text":"<p>Creates a work pool configured to use the given block as the job creator.</p> <p>Used to migrate from a agents setup to a worker setup.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>The name to give to the created work pool. If not provided, the name of the current block will be used.</p> <code>None</code> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@sync_compatible\nasync def publish_as_work_pool(self, work_pool_name: Optional[str] = None):\n    \"\"\"\n    Creates a work pool configured to use the given block as the job creator.\n\n    Used to migrate from a agents setup to a worker setup.\n\n    Args:\n        work_pool_name: The name to give to the created work pool. If not provided, the name of the current\n            block will be used.\n    \"\"\"\n\n    base_job_template = await self.generate_work_pool_base_job_template()\n    work_pool_name = work_pool_name or self._block_document_name\n\n    if work_pool_name is None:\n        raise ValueError(\n            \"`work_pool_name` must be provided if the block has not been saved.\"\n        )\n\n    console = Console()\n\n    try:\n        async with prefect.get_client() as client:\n            work_pool = await client.create_work_pool(\n                work_pool=WorkPoolCreate(\n                    name=work_pool_name,\n                    type=self.get_corresponding_worker_type(),\n                    base_job_template=base_job_template,\n                )\n            )\n    except ObjectAlreadyExists:\n        console.print(\n            (\n                f\"Work pool with name {work_pool_name!r} already exists, please use\"\n                \" a different name.\"\n            ),\n            style=\"red\",\n        )\n        return\n\n    console.print(\n        f\"Work pool {work_pool.name} created!\",\n        style=\"green\",\n    )\n    if PREFECT_UI_URL:\n        console.print(\n            \"You see your new work pool in the UI at\"\n            f\" {PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n        )\n\n    deploy_script = (\n        \"my_flow.deploy(work_pool_name='{work_pool.name}', image='my_image:tag')\"\n    )\n    if not hasattr(self, \"image\"):\n        deploy_script = (\n            \"my_flow.from_source(source='https://github.com/org/repo.git',\"\n            f\" entrypoint='flow.py:my_flow').deploy(work_pool_name='{work_pool.name}')\"\n        )\n    console.print(\n        \"\\nYou can deploy a flow to this work pool by calling\"\n        f\" [blue].deploy[/]:\\n\\n\\t{deploy_script}\\n\"\n    )\n    console.print(\n        \"\\nTo start a worker to execute flow runs in this work pool run:\\n\"\n    )\n    console.print(f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\")\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Infrastructure.run","title":"<code>run</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Run the infrastructure.</p> <p>If provided a <code>task_status</code>, the status will be reported as started when the infrastructure is successfully created. The status return value will be an identifier for the infrastructure.</p> <p>The call will then monitor the created infrastructure, returning a result at the end containing a status code indicating if the infrastructure exited cleanly or encountered an error.</p> Source code in <code>prefect/infrastructure/base.py</code> <pre><code>@abc.abstractmethod\nasync def run(\n    self,\n    task_status: anyio.abc.TaskStatus = None,\n) -&gt; InfrastructureResult:\n    \"\"\"\n    Run the infrastructure.\n\n    If provided a `task_status`, the status will be reported as started when the\n    infrastructure is successfully created. The status return value will be an\n    identifier for the infrastructure.\n\n    The call will then monitor the created infrastructure, returning a result at\n    the end containing a status code indicating if the infrastructure exited cleanly\n    or encountered an error.\n    \"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect.blocks.kubernetes import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the KubernetesClusterConfig block from prefect-kubernetes instead.\",\n)\nclass KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect.blocks.kubernetes import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig\"\n\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    def parse_yaml_config(cls, value):\n        return validate_yaml(value)\n\n    @classmethod\n    def from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n        kube_config = kubernetes.config.kube_config\n\n        path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        existing_contexts, current_context = kube_config.list_kube_config_contexts(\n            config_file=str(path)\n        )\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n\n        return cls(config=config_dict, context_name=context_name)\n\n    def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return kubernetes.config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        kubernetes.config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    kubernetes.config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@classmethod\ndef from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n    kube_config = kubernetes.config.kube_config\n\n    path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    existing_contexts, current_context = kube_config.list_kube_config_contexts(\n        config_file=str(path)\n    )\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return kubernetes.config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob","title":"<code>KubernetesJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Runs a command as a Kubernetes Job.</p> <p>For a guided tutorial, see How to use Kubernetes with Prefect. For more information, including examples for customizing the resulting manifest, see <code>KubernetesJob</code> infrastructure concepts.</p> <p>Attributes:</p> Name Type Description <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>An optional Kubernetes cluster config to use for this job.</p> <code>command</code> <code>Optional[KubernetesClusterConfig]</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>customizations</code> <code>JsonPatch</code> <p>A list of JSON 6902 patches to apply to the base Job manifest.</p> <code>env</code> <code>JsonPatch</code> <p>Environment variables to set for the container.</p> <code>finished_job_ttl</code> <code>Optional[int]</code> <p>The number of seconds to retain jobs after completion. If set, finished jobs will be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be manually removed.</p> <code>image</code> <code>Optional[str]</code> <p>An optional string specifying the image reference of a container image to use for the job, for example, docker.io/prefecthq/prefect:2-latest. The behavior is as described in https://kubernetes.io/docs/concepts/containers/images/#image-names. Defaults to the Prefect image.</p> <code>image_pull_policy</code> <code>Optional[KubernetesImagePullPolicy]</code> <p>The Kubernetes image pull policy to use for job containers.</p> <code>job</code> <code>KubernetesManifest</code> <p>The base manifest for the Kubernetes Job.</p> <code>job_watch_timeout_seconds</code> <code>Optional[int]</code> <p>Number of seconds to wait for the job to complete before marking it as crashed. Defaults to <code>None</code>, which means no timeout will be enforced.</p> <code>labels</code> <code>Optional[int]</code> <p>An optional dictionary of labels to add to the job.</p> <code>name</code> <code>Optional[int]</code> <p>An optional name for the job.</p> <code>namespace</code> <code>Optional[str]</code> <p>An optional string signifying the Kubernetes namespace to use.</p> <code>pod_watch_timeout_seconds</code> <code>int</code> <p>Number of seconds to watch for pod creation before timing out (default 60).</p> <code>service_account_name</code> <code>Optional[str]</code> <p>An optional string specifying which Kubernetes service account to use.</p> <code>stream_output</code> <code>bool</code> <p>If set, stream output from the job to local standard output.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the Kubernetes worker from prefect-kubernetes instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass KubernetesJob(Infrastructure):\n    \"\"\"\n    Runs a command as a Kubernetes Job.\n\n    For a guided tutorial, see [How to use Kubernetes with Prefect](https://medium.com/the-prefect-blog/how-to-use-kubernetes-with-prefect-419b2e8b8cb2/).\n    For more information, including examples for customizing the resulting manifest, see [`KubernetesJob` infrastructure concepts](https://docs.prefect.io/concepts/infrastructure/#kubernetesjob).\n\n    Attributes:\n        cluster_config: An optional Kubernetes cluster config to use for this job.\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        customizations: A list of JSON 6902 patches to apply to the base Job manifest.\n        env: Environment variables to set for the container.\n        finished_job_ttl: The number of seconds to retain jobs after completion. If set, finished jobs will\n            be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be\n            manually removed.\n        image: An optional string specifying the image reference of a container image\n            to use for the job, for example, docker.io/prefecthq/prefect:2-latest. The\n            behavior is as described in https://kubernetes.io/docs/concepts/containers/images/#image-names.\n            Defaults to the Prefect image.\n        image_pull_policy: The Kubernetes image pull policy to use for job containers.\n        job: The base manifest for the Kubernetes Job.\n        job_watch_timeout_seconds: Number of seconds to wait for the job to complete\n            before marking it as crashed. Defaults to `None`, which means no timeout will be enforced.\n        labels: An optional dictionary of labels to add to the job.\n        name: An optional name for the job.\n        namespace: An optional string signifying the Kubernetes namespace to use.\n        pod_watch_timeout_seconds: Number of seconds to watch for pod creation before timing out (default 60).\n        service_account_name: An optional string specifying which Kubernetes service account to use.\n        stream_output: If set, stream output from the job to local standard output.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob\"\n\n    type: Literal[\"kubernetes-job\"] = Field(\n        default=\"kubernetes-job\", description=\"The type of infrastructure.\"\n    )\n    # shortcuts for the most common user-serviceable settings\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image reference of a container image to use for the job, for example,\"\n            \" `docker.io/prefecthq/prefect:2-latest`.The behavior is as described in\"\n            \" the Kubernetes documentation and uses the latest version of Prefect by\"\n            \" default, unless an image is already present in a provided job manifest.\"\n        ),\n    )\n    namespace: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The Kubernetes namespace to use for this job. Defaults to 'default' \"\n            \"unless a namespace is already present in a provided job manifest.\"\n        ),\n    )\n    service_account_name: Optional[str] = Field(\n        default=None, description=\"The Kubernetes service account to use for this job.\"\n    )\n    image_pull_policy: Optional[KubernetesImagePullPolicy] = Field(\n        default=None,\n        description=\"The Kubernetes image pull policy to use for job containers.\",\n    )\n\n    # connection to a cluster\n    cluster_config: Optional[KubernetesClusterConfig] = Field(\n        default=None, description=\"The Kubernetes cluster config to use for this job.\"\n    )\n\n    # settings allowing full customization of the Job\n    job: KubernetesManifest = Field(\n        default_factory=lambda: KubernetesJob.base_job_manifest(),\n        description=\"The base manifest for the Kubernetes Job.\",\n        title=\"Base Job Manifest\",\n    )\n    customizations: JsonPatch = Field(\n        default_factory=lambda: JsonPatch([]),\n        description=\"A list of JSON 6902 patches to apply to the base Job manifest.\",\n    )\n\n    # controls the behavior of execution\n    job_watch_timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"Number of seconds to wait for the job to complete before marking it as\"\n            \" crashed. Defaults to `None`, which means no timeout will be enforced.\"\n        ),\n    )\n    pod_watch_timeout_seconds: int = Field(\n        default=60,\n        description=\"Number of seconds to watch for pod creation before timing out.\",\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the job to local standard output.\"\n        ),\n    )\n    finished_job_ttl: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to retain jobs after completion. If set, finished\"\n            \" jobs will be cleaned up by Kubernetes after the given delay. If None\"\n            \" (default), jobs will need to be manually removed.\"\n        ),\n    )\n\n    # internal-use only right now\n    _api_dns_name: Optional[str] = None  # Replaces 'localhost' in API URL\n\n    _block_type_name = \"Kubernetes Job\"\n\n    @validator(\"job\")\n    def ensure_job_includes_all_required_components(cls, value: KubernetesManifest):\n        return validate_k8s_job_required_components(cls, value)\n\n    @validator(\"job\")\n    def ensure_job_has_compatible_values(cls, value: KubernetesManifest):\n        return validate_k8s_job_compatible_values(cls, value)\n\n    @validator(\"customizations\", pre=True)\n    def cast_customizations_to_a_json_patch(\n        cls, value: Union[List[Dict], JsonPatch, str]\n    ) -&gt; JsonPatch:\n        return cast_k8s_job_customizations(cls, value)\n\n    @root_validator\n    def default_namespace(cls, values):\n        return set_default_namespace(values)\n\n    @root_validator\n    def default_image(cls, values):\n        return set_default_image(values)\n\n    # Support serialization of the 'JsonPatch' type\n    class Config:\n        arbitrary_types_allowed = True\n        json_encoders = {JsonPatch: lambda p: p.patch}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        d = super().dict(*args, **kwargs)\n        d[\"customizations\"] = self.customizations.patch\n        return d\n\n    @classmethod\n    def base_job_manifest(cls) -&gt; KubernetesManifest:\n        \"\"\"Produces the bare minimum allowed Job manifest\"\"\"\n        return {\n            \"apiVersion\": \"batch/v1\",\n            \"kind\": \"Job\",\n            \"metadata\": {\"labels\": {}},\n            \"spec\": {\n                \"template\": {\n                    \"spec\": {\n                        \"parallelism\": 1,\n                        \"completions\": 1,\n                        \"restartPolicy\": \"Never\",\n                        \"containers\": [\n                            {\n                                \"name\": \"prefect-job\",\n                                \"env\": [],\n                            }\n                        ],\n                    }\n                }\n            },\n        }\n\n    # Note that we're using the yaml package to load both YAML and JSON files below.\n    # This works because YAML is a strict superset of JSON:\n    #\n    #   &gt; The YAML 1.23 specification was published in 2009. Its primary focus was\n    #   &gt; making YAML a strict superset of JSON. It also removed many of the problematic\n    #   &gt; implicit typing recommendations.\n    #\n    #   https://yaml.org/spec/1.2.2/#12-yaml-history\n\n    @classmethod\n    def job_from_file(cls, filename: str) -&gt; KubernetesManifest:\n        \"\"\"Load a Kubernetes Job manifest from a YAML or JSON file.\"\"\"\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            return yaml.load(f, yaml.SafeLoader)\n\n    @classmethod\n    def customize_from_file(cls, filename: str) -&gt; JsonPatch:\n        \"\"\"Load an RFC 6902 JSON patch from a YAML or JSON file.\"\"\"\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            return JsonPatch(yaml.load(f, yaml.SafeLoader))\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; KubernetesJobResult:\n        if not self.command:\n            raise ValueError(\"Kubernetes job cannot be run with empty command.\")\n\n        self._configure_kubernetes_library_client()\n        manifest = self.build_job()\n        job = await run_sync_in_worker_thread(self._create_job, manifest)\n\n        pid = await run_sync_in_worker_thread(self._get_infrastructure_pid, job)\n        # Indicate that the job has started\n        if task_status is not None:\n            task_status.started(pid)\n\n        # Monitor the job until completion\n        status_code = await run_sync_in_worker_thread(\n            self._watch_job, job.metadata.name\n        )\n        return KubernetesJobResult(identifier=pid, status_code=status_code)\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        self._configure_kubernetes_library_client()\n        job_cluster_uid, job_namespace, job_name = self._parse_infrastructure_pid(\n            infrastructure_pid\n        )\n\n        if not job_namespace == self.namespace:\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill job {job_name!r}: The job is running in namespace \"\n                f\"{job_namespace!r} but this block is configured to use \"\n                f\"{self.namespace!r}.\"\n            )\n\n        current_cluster_uid = self._get_cluster_uid()\n        if job_cluster_uid != current_cluster_uid:\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill job {job_name!r}: The job is running on another \"\n                \"cluster.\"\n            )\n\n        with self.get_batch_client() as batch_client:\n            try:\n                batch_client.delete_namespaced_job(\n                    name=job_name,\n                    namespace=job_namespace,\n                    grace_period_seconds=grace_seconds,\n                    # Foreground propagation deletes dependent objects before deleting owner objects.\n                    # This ensures that the pods are cleaned up before the job is marked as deleted.\n                    # See: https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion\n                    propagation_policy=\"Foreground\",\n                )\n            except kubernetes.client.exceptions.ApiException as exc:\n                if exc.status == 404:\n                    raise InfrastructureNotFound(\n                        f\"Unable to kill job {job_name!r}: The job was not found.\"\n                    ) from exc\n                else:\n                    raise\n\n    def preview(self):\n        return yaml.dump(self.build_job())\n\n    def get_corresponding_worker_type(self):\n        return \"kubernetes\"\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type()\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to retrieve default base job template.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"job\",\n                \"customizations\",\n            ]:\n                continue\n            elif key == \"image_pull_policy\":\n                base_job_template[\"variables\"][\"properties\"][\"image_pull_policy\"][\n                    \"default\"\n                ] = value.value\n            elif key == \"cluster_config\":\n                base_job_template[\"variables\"][\"properties\"][\"cluster_config\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.cluster_config._block_document_id)\n                    }\n                }\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Kubernetes work pools.\"\n                    \" Skipping.\"\n                )\n\n        custom_job_manifest = self.dict(exclude_unset=True, exclude_defaults=True).get(\n            \"job\"\n        )\n        if custom_job_manifest:\n            job_manifest = self.build_job()\n        else:\n            job_manifest = copy.deepcopy(\n                base_job_template[\"job_configuration\"][\"job_manifest\"]\n            )\n            job_manifest = self.customizations.apply(job_manifest)\n        base_job_template[\"job_configuration\"][\"job_manifest\"] = job_manifest\n\n        return base_job_template\n\n    def build_job(self) -&gt; KubernetesManifest:\n        \"\"\"Builds the Kubernetes Job Manifest\"\"\"\n        job_manifest = copy.copy(self.job)\n        job_manifest = self._shortcut_customizations().apply(job_manifest)\n        job_manifest = self.customizations.apply(job_manifest)\n        return job_manifest\n\n    @contextmanager\n    def get_batch_client(self) -&gt; Generator[\"BatchV1Api\", None, None]:\n        with kubernetes.client.ApiClient() as client:\n            try:\n                yield kubernetes.client.BatchV1Api(api_client=client)\n            finally:\n                client.rest_client.pool_manager.clear()\n\n    @contextmanager\n    def get_client(self) -&gt; Generator[\"CoreV1Api\", None, None]:\n        with kubernetes.client.ApiClient() as client:\n            try:\n                yield kubernetes.client.CoreV1Api(api_client=client)\n            finally:\n                client.rest_client.pool_manager.clear()\n\n    def _get_infrastructure_pid(self, job: \"V1Job\") -&gt; str:\n        \"\"\"\n        Generates a Kubernetes infrastructure PID.\n\n        The PID is in the format: \"&lt;cluster uid&gt;:&lt;namespace&gt;:&lt;job name&gt;\".\n        \"\"\"\n        cluster_uid = self._get_cluster_uid()\n        pid = f\"{cluster_uid}:{self.namespace}:{job.metadata.name}\"\n        return pid\n\n    def _parse_infrastructure_pid(\n        self, infrastructure_pid: str\n    ) -&gt; Tuple[str, str, str]:\n        \"\"\"\n        Parse a Kubernetes infrastructure PID into its component parts.\n\n        Returns a cluster UID, namespace, and job name.\n        \"\"\"\n        cluster_uid, namespace, job_name = infrastructure_pid.split(\":\", 2)\n        return cluster_uid, namespace, job_name\n\n    def _get_cluster_uid(self) -&gt; str:\n        \"\"\"\n        Gets a unique id for the current cluster being used.\n\n        There is no real unique identifier for a cluster. However, the `kube-system`\n        namespace is immutable and has a persistence UID that we use instead.\n\n        PREFECT_KUBERNETES_CLUSTER_UID can be set in cases where the `kube-system`\n        namespace cannot be read e.g. when a cluster role cannot be created. If set,\n        this variable will be used and we will not attempt to read the `kube-system`\n        namespace.\n\n        See https://github.com/kubernetes/kubernetes/issues/44954\n        \"\"\"\n        # Default to an environment variable\n        env_cluster_uid = os.environ.get(\"PREFECT_KUBERNETES_CLUSTER_UID\")\n        if env_cluster_uid:\n            return env_cluster_uid\n\n        # Read the UID from the cluster namespace\n        with self.get_client() as client:\n            namespace = client.read_namespace(\"kube-system\")\n        cluster_uid = namespace.metadata.uid\n\n        return cluster_uid\n\n    def _configure_kubernetes_library_client(self) -&gt; None:\n        \"\"\"\n        Set the correct kubernetes client configuration.\n\n        WARNING: This action is not threadsafe and may override the configuration\n                  specified by another `KubernetesJob` instance.\n        \"\"\"\n        # TODO: Investigate returning a configured client so calls on other threads\n        #       will not invalidate the config needed here\n\n        # if a k8s cluster block is provided to the flow runner, use that\n        if self.cluster_config:\n            self.cluster_config.configure_client()\n        else:\n            # If no block specified, try to load Kubernetes configuration within a cluster. If that doesn't\n            # work, try to load the configuration from the local environment, allowing\n            # any further ConfigExceptions to bubble up.\n            try:\n                kubernetes.config.load_incluster_config()\n            except kubernetes.config.ConfigException:\n                kubernetes.config.load_kube_config()\n\n    def _shortcut_customizations(self) -&gt; JsonPatch:\n        \"\"\"Produces the JSON 6902 patch for the most commonly used customizations, like\n        image and namespace, which we offer as top-level parameters (with sensible\n        default values)\"\"\"\n        shortcuts = []\n\n        if self.namespace:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/namespace\",\n                    \"value\": self.namespace,\n                }\n            )\n\n        if self.image:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/image\",\n                    \"value\": self.image,\n                }\n            )\n\n        shortcuts += [\n            {\n                \"op\": \"add\",\n                \"path\": (\n                    f\"/metadata/labels/{self._slugify_label_key(key).replace('/', '~1', 1)}\"\n                ),\n                \"value\": self._slugify_label_value(value),\n            }\n            for key, value in self.labels.items()\n        ]\n\n        shortcuts += [\n            {\n                \"op\": \"add\",\n                \"path\": \"/spec/template/spec/containers/0/env/-\",\n                \"value\": {\"name\": key, \"value\": value},\n            }\n            for key, value in self._get_environment_variables().items()\n        ]\n\n        if self.image_pull_policy:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/imagePullPolicy\",\n                    \"value\": self.image_pull_policy.value,\n                }\n            )\n\n        if self.service_account_name:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/serviceAccountName\",\n                    \"value\": self.service_account_name,\n                }\n            )\n\n        if self.finished_job_ttl is not None:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/ttlSecondsAfterFinished\",\n                    \"value\": self.finished_job_ttl,\n                }\n            )\n\n        if self.command:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/spec/template/spec/containers/0/args\",\n                    \"value\": self.command,\n                }\n            )\n\n        if self.name:\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/generateName\",\n                    \"value\": self._slugify_name(self.name) + \"-\",\n                }\n            )\n        else:\n            # Generate name is required\n            shortcuts.append(\n                {\n                    \"op\": \"add\",\n                    \"path\": \"/metadata/generateName\",\n                    \"value\": (\n                        \"prefect-job-\"\n                        # We generate a name using a hash of the primary job settings\n                        + stable_hash(\n                            *self.command if self.command else \"\",\n                            *self.env.keys(),\n                            *[v for v in self.env.values() if v is not None],\n                        )\n                        + \"-\"\n                    ),\n                }\n            )\n\n        return JsonPatch(shortcuts)\n\n    def _get_job(self, job_id: str) -&gt; Optional[\"V1Job\"]:\n        with self.get_batch_client() as batch_client:\n            try:\n                job = batch_client.read_namespaced_job(job_id, self.namespace)\n            except kubernetes.client.exceptions.ApiException:\n                self.logger.error(f\"Job {job_id!r} was removed.\", exc_info=True)\n                return None\n            return job\n\n    def _get_job_pod(self, job_name: str) -&gt; \"V1Pod\":\n        \"\"\"Get the first running pod for a job.\"\"\"\n\n        # Wait until we find a running pod for the job\n        # if `pod_watch_timeout_seconds` is None, no timeout will be enforced\n        watch = kubernetes.watch.Watch()\n        self.logger.debug(f\"Job {job_name!r}: Starting watch for pod start...\")\n        last_phase = None\n        with self.get_client() as client:\n            for event in watch.stream(\n                func=client.list_namespaced_pod,\n                namespace=self.namespace,\n                label_selector=f\"job-name={job_name}\",\n                timeout_seconds=self.pod_watch_timeout_seconds,\n            ):\n                phase = event[\"object\"].status.phase\n                if phase != last_phase:\n                    self.logger.info(f\"Job {job_name!r}: Pod has status {phase!r}.\")\n\n                if phase != \"Pending\":\n                    watch.stop()\n                    return event[\"object\"]\n\n                last_phase = phase\n\n        self.logger.error(f\"Job {job_name!r}: Pod never started.\")\n\n    def _watch_job(self, job_name: str) -&gt; int:\n        \"\"\"\n        Watch a job.\n\n        Return the final status code of the first container.\n        \"\"\"\n        self.logger.debug(f\"Job {job_name!r}: Monitoring job...\")\n\n        job = self._get_job(job_name)\n        if not job:\n            return -1\n\n        pod = self._get_job_pod(job_name)\n        if not pod:\n            return -1\n\n        # Calculate the deadline before streaming output\n        deadline = (\n            (time.monotonic() + self.job_watch_timeout_seconds)\n            if self.job_watch_timeout_seconds is not None\n            else None\n        )\n\n        if self.stream_output:\n            with self.get_client() as client:\n                logs = client.read_namespaced_pod_log(\n                    pod.metadata.name,\n                    self.namespace,\n                    follow=True,\n                    _preload_content=False,\n                    container=\"prefect-job\",\n                )\n                try:\n                    for log in logs.stream():\n                        print(log.decode().rstrip())\n\n                        # Check if we have passed the deadline and should stop streaming\n                        # logs\n                        remaining_time = (\n                            deadline - time.monotonic() if deadline else None\n                        )\n                        if deadline and remaining_time &lt;= 0:\n                            break\n\n                except Exception:\n                    self.logger.warning(\n                        (\n                            \"Error occurred while streaming logs - \"\n                            \"Job will continue to run but logs will \"\n                            \"no longer be streamed to stdout.\"\n                        ),\n                        exc_info=True,\n                    )\n\n        with self.get_batch_client() as batch_client:\n            # Check if the job is completed before beginning a watch\n            job = batch_client.read_namespaced_job(\n                name=job_name, namespace=self.namespace\n            )\n            completed = job.status.completion_time is not None\n\n            while not completed:\n                remaining_time = (\n                    math.ceil(deadline - time.monotonic()) if deadline else None\n                )\n                if deadline and remaining_time &lt;= 0:\n                    self.logger.error(\n                        f\"Job {job_name!r}: Job did not complete within \"\n                        f\"timeout of {self.job_watch_timeout_seconds}s.\"\n                    )\n                    return -1\n\n                watch = kubernetes.watch.Watch()\n                # The kubernetes library will disable retries if the timeout kwarg is\n                # present regardless of the value so we do not pass it unless given\n                # https://github.com/kubernetes-client/python/blob/84f5fea2a3e4b161917aa597bf5e5a1d95e24f5a/kubernetes/base/watch/watch.py#LL160\n                timeout_seconds = (\n                    {\"timeout_seconds\": remaining_time} if deadline else {}\n                )\n\n                for event in watch.stream(\n                    func=batch_client.list_namespaced_job,\n                    field_selector=f\"metadata.name={job_name}\",\n                    namespace=self.namespace,\n                    **timeout_seconds,\n                ):\n                    if event[\"type\"] == \"DELETED\":\n                        self.logger.error(f\"Job {job_name!r}: Job has been deleted.\")\n                        completed = True\n                    elif event[\"object\"].status.completion_time:\n                        if not event[\"object\"].status.succeeded:\n                            # Job failed, exit while loop and return pod exit code\n                            self.logger.error(f\"Job {job_name!r}: Job failed.\")\n                        completed = True\n                    # Check if the job has reached its backoff limit\n                    # and stop watching if it has\n                    elif (\n                        event[\"object\"].spec.backoff_limit is not None\n                        and event[\"object\"].status.failed is not None\n                        and event[\"object\"].status.failed\n                        &gt; event[\"object\"].spec.backoff_limit\n                    ):\n                        self.logger.error(\n                            f\"Job {job_name!r}: Job reached backoff limit.\"\n                        )\n                        completed = True\n                    # If the job has no backoff limit, check if it has failed\n                    # and stop watching if it has\n                    elif (\n                        not event[\"object\"].spec.backoff_limit\n                        and event[\"object\"].status.failed\n                    ):\n                        completed = True\n\n                    if completed:\n                        watch.stop()\n                        break\n\n        with self.get_client() as core_client:\n            # Get all pods for the job\n            pods = core_client.list_namespaced_pod(\n                namespace=self.namespace, label_selector=f\"job-name={job_name}\"\n            )\n            # Get the status for only the most recently used pod\n            pods.items.sort(\n                key=lambda pod: pod.metadata.creation_timestamp, reverse=True\n            )\n            most_recent_pod = pods.items[0] if pods.items else None\n            first_container_status = (\n                most_recent_pod.status.container_statuses[0]\n                if most_recent_pod\n                else None\n            )\n            if not first_container_status:\n                self.logger.error(f\"Job {job_name!r}: No pods found for job.\")\n                return -1\n\n            # In some cases, such as spot instance evictions, the pod will be forcibly\n            # terminated and not report a status correctly.\n            elif (\n                first_container_status.state is None\n                or first_container_status.state.terminated is None\n                or first_container_status.state.terminated.exit_code is None\n            ):\n                self.logger.error(\n                    f\"Could not determine exit code for {job_name!r}.\"\n                    \"Exit code will be reported as -1.\"\n                    \"First container status info did not report an exit code.\"\n                    f\"First container info: {first_container_status}.\"\n                )\n                return -1\n\n        return first_container_status.state.terminated.exit_code\n\n    def _create_job(self, job_manifest: KubernetesManifest) -&gt; \"V1Job\":\n        \"\"\"\n        Given a Kubernetes Job Manifest, create the Job on the configured Kubernetes\n        cluster and return its name.\n        \"\"\"\n        with self.get_batch_client() as batch_client:\n            job = batch_client.create_namespaced_job(self.namespace, job_manifest)\n        return job\n\n    def _slugify_name(self, name: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a name.\n\n        Keeps only alphanumeric characters and dashes, and caps the length\n        of the slug at 45 chars.\n\n        The 45 character length allows room for the k8s utility\n        \"generateName\" to generate a unique name from the slug while\n        keeping the total length of a name below 63 characters, which is\n        the limit for e.g. label names that follow RFC 1123 (hostnames) and\n        RFC 1035 (domain names).\n\n        Args:\n            name: The name of the job\n\n        Returns:\n            the slugified job name\n        \"\"\"\n        slug = slugify(\n            name,\n            max_length=45,  # Leave enough space for generateName\n            regex_pattern=r\"[^a-zA-Z0-9-]+\",\n        )\n\n        # TODO: Handle the case that the name is an empty string after being\n        # slugified.\n\n        return slug\n\n    def _slugify_label_key(self, key: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a label key.\n\n        Keys are composed of an optional prefix and name, separated by a slash (/).\n\n        Keeps only alphanumeric characters, dashes, underscores, and periods.\n        Limits the length of the label prefix to 253 characters.\n        Limits the length of the label name to 63 characters.\n\n        See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set\n\n        Args:\n            key: The label key\n\n        Returns:\n            The slugified label key\n        \"\"\"\n        if \"/\" in key:\n            prefix, name = key.split(\"/\", maxsplit=1)\n        else:\n            prefix = None\n            name = key\n\n        name_slug = (\n            slugify(name, max_length=63, regex_pattern=r\"[^a-zA-Z0-9-_.]+\").strip(\n                \"_-.\"  # Must start or end with alphanumeric characters\n            )\n            or name\n        )\n        # Fallback to the original if we end up with an empty slug, this will allow\n        # Kubernetes to throw the validation error\n\n        if prefix:\n            prefix_slug = (\n                slugify(\n                    prefix,\n                    max_length=253,\n                    regex_pattern=r\"[^a-zA-Z0-9-\\.]+\",\n                ).strip(\"_-.\")  # Must start or end with alphanumeric characters\n                or prefix\n            )\n\n            return f\"{prefix_slug}/{name_slug}\"\n\n        return name_slug\n\n    def _slugify_label_value(self, value: str) -&gt; str:\n        \"\"\"\n        Slugify text for use as a label value.\n\n        Keeps only alphanumeric characters, dashes, underscores, and periods.\n        Limits the total length of label text to below 63 characters.\n\n        See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set\n\n        Args:\n            value: The text for the label\n\n        Returns:\n            The slugified value\n        \"\"\"\n        slug = (\n            slugify(value, max_length=63, regex_pattern=r\"[^a-zA-Z0-9-_\\.]+\").strip(\n                \"_-.\"  # Must start or end with alphanumeric characters\n            )\n            or value\n        )\n        # Fallback to the original if we end up with an empty slug, this will allow\n        # Kubernetes to throw the validation error\n\n        return slug\n\n    def _get_environment_variables(self):\n        # If the API URL has been set by the base environment rather than the by the\n        # user, update the value to ensure connectivity when using a bridge network by\n        # updating local connections to use the internal host\n        env = {**self._base_environment(), **self.env}\n\n        if (\n            \"PREFECT_API_URL\" in env\n            and \"PREFECT_API_URL\" not in self.env\n            and self._api_dns_name\n        ):\n            env[\"PREFECT_API_URL\"] = (\n                env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", self._api_dns_name)\n                .replace(\"127.0.0.1\", self._api_dns_name)\n            )\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.base_job_manifest","title":"<code>base_job_manifest</code>  <code>classmethod</code>","text":"<p>Produces the bare minimum allowed Job manifest</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef base_job_manifest(cls) -&gt; KubernetesManifest:\n    \"\"\"Produces the bare minimum allowed Job manifest\"\"\"\n    return {\n        \"apiVersion\": \"batch/v1\",\n        \"kind\": \"Job\",\n        \"metadata\": {\"labels\": {}},\n        \"spec\": {\n            \"template\": {\n                \"spec\": {\n                    \"parallelism\": 1,\n                    \"completions\": 1,\n                    \"restartPolicy\": \"Never\",\n                    \"containers\": [\n                        {\n                            \"name\": \"prefect-job\",\n                            \"env\": [],\n                        }\n                    ],\n                }\n            }\n        },\n    }\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.build_job","title":"<code>build_job</code>","text":"<p>Builds the Kubernetes Job Manifest</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>def build_job(self) -&gt; KubernetesManifest:\n    \"\"\"Builds the Kubernetes Job Manifest\"\"\"\n    job_manifest = copy.copy(self.job)\n    job_manifest = self._shortcut_customizations().apply(job_manifest)\n    job_manifest = self.customizations.apply(job_manifest)\n    return job_manifest\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.customize_from_file","title":"<code>customize_from_file</code>  <code>classmethod</code>","text":"<p>Load an RFC 6902 JSON patch from a YAML or JSON file.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef customize_from_file(cls, filename: str) -&gt; JsonPatch:\n    \"\"\"Load an RFC 6902 JSON patch from a YAML or JSON file.\"\"\"\n    with open(filename, \"r\", encoding=\"utf-8\") as f:\n        return JsonPatch(yaml.load(f, yaml.SafeLoader))\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJob.job_from_file","title":"<code>job_from_file</code>  <code>classmethod</code>","text":"<p>Load a Kubernetes Job manifest from a YAML or JSON file.</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>@classmethod\ndef job_from_file(cls, filename: str) -&gt; KubernetesManifest:\n    \"\"\"Load a Kubernetes Job manifest from a YAML or JSON file.\"\"\"\n    with open(filename, \"r\", encoding=\"utf-8\") as f:\n        return yaml.load(f, yaml.SafeLoader)\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.KubernetesJobResult","title":"<code>KubernetesJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about the final state of a completed Kubernetes Job</p> Source code in <code>prefect/infrastructure/kubernetes.py</code> <pre><code>class KubernetesJobResult(InfrastructureResult):\n    \"\"\"Contains information about the final state of a completed Kubernetes Job\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.Process","title":"<code>Process</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>Run a command in a new process.</p> <p>Current environment variables and Prefect settings will be included in the created process. Configured environment variables will override any current environment variables.</p> <p>Attributes:</p> Name Type Description <code>command</code> <p>A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this.</p> <code>env</code> <p>Environment variables to set for the new process.</p> <code>labels</code> <p>Labels for the process. Labels are for metadata purposes only and cannot be attached to the process itself.</p> <code>name</code> <p>A name for the process. For display purposes only.</p> <code>stream_output</code> <code>bool</code> <p>Whether to stream output to local stdout.</p> <code>working_dir</code> <code>Union[str, Path, None]</code> <p>Working directory where the process should be opened. If not set, a tmp directory will be used.</p> Source code in <code>prefect/infrastructure/process.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the process worker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Process(Infrastructure):\n    \"\"\"\n    Run a command in a new process.\n\n    Current environment variables and Prefect settings will be included in the created\n    process. Configured environment variables will override any current environment\n    variables.\n\n    Attributes:\n        command: A list of strings specifying the command to run in the container to\n            start the flow run. In most cases you should not override this.\n        env: Environment variables to set for the new process.\n        labels: Labels for the process. Labels are for metadata purposes only and\n            cannot be attached to the process itself.\n        name: A name for the process. For display purposes only.\n        stream_output: Whether to stream output to local stdout.\n        working_dir: Working directory where the process should be opened. If not set,\n            a tmp directory will be used.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/356e6766a91baf20e1d08bbe16e8b5aaef4d8643-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/concepts/infrastructure/#process\"\n\n    type: Literal[\"process\"] = Field(\n        default=\"process\", description=\"The type of infrastructure.\"\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the process to local standard output.\"\n        ),\n    )\n    working_dir: Union[str, Path, None] = Field(\n        default=None,\n        description=(\n            \"If set, the process will open within the specified path as the working\"\n            \" directory. Otherwise, a temporary directory will be created.\"\n        ),\n    )  # Underlying accepted types are str, bytes, PathLike[str], None\n\n    @sync_compatible\n    async def run(\n        self,\n        task_status: anyio.abc.TaskStatus = None,\n    ) -&gt; \"ProcessResult\":\n        if not self.command:\n            raise ValueError(\"Process cannot be run with empty command.\")\n\n        display_name = f\" {self.name!r}\" if self.name else \"\"\n\n        # Open a subprocess to execute the flow run\n        self.logger.info(f\"Opening process{display_name}...\")\n        working_dir_ctx = (\n            tempfile.TemporaryDirectory(suffix=\"prefect\")\n            if not self.working_dir\n            else contextlib.nullcontext(self.working_dir)\n        )\n        with working_dir_ctx as working_dir:\n            self.logger.debug(\n                f\"Process{display_name} running command: {' '.join(self.command)} in\"\n                f\" {working_dir}\"\n            )\n\n            # We must add creationflags to a dict so it is only passed as a function\n            # parameter on Windows, because the presence of creationflags causes\n            # errors on Unix even if set to None\n            kwargs: Dict[str, object] = {}\n            if sys.platform == \"win32\":\n                kwargs[\"creationflags\"] = subprocess.CREATE_NEW_PROCESS_GROUP\n\n            process = await run_process(\n                self.command,\n                stream_output=self.stream_output,\n                task_status=task_status,\n                task_status_handler=_infrastructure_pid_from_process,\n                env=self._get_environment_variables(),\n                cwd=working_dir,\n                **kwargs,\n            )\n\n        # Use the pid for display if no name was given\n        display_name = display_name or f\" {process.pid}\"\n\n        if process.returncode:\n            help_message = None\n            if process.returncode == -9:\n                help_message = (\n                    \"This indicates that the process exited due to a SIGKILL signal. \"\n                    \"Typically, this is either caused by manual cancellation or \"\n                    \"high memory usage causing the operating system to \"\n                    \"terminate the process.\"\n                )\n            if process.returncode == -15:\n                help_message = (\n                    \"This indicates that the process exited due to a SIGTERM signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n            elif process.returncode == 247:\n                help_message = (\n                    \"This indicates that the process was terminated due to high \"\n                    \"memory usage.\"\n                )\n            elif (\n                sys.platform == \"win32\" and process.returncode == STATUS_CONTROL_C_EXIT\n            ):\n                help_message = (\n                    \"Process was terminated due to a Ctrl+C or Ctrl+Break signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n\n            self.logger.error(\n                f\"Process{display_name} exited with status code: {process.returncode}\"\n                + (f\"; {help_message}\" if help_message else \"\")\n            )\n        else:\n            self.logger.info(f\"Process{display_name} exited cleanly.\")\n\n        return ProcessResult(\n            status_code=process.returncode, identifier=str(process.pid)\n        )\n\n    async def kill(self, infrastructure_pid: str, grace_seconds: int = 30):\n        hostname, pid = _parse_infrastructure_pid(infrastructure_pid)\n\n        if hostname != socket.gethostname():\n            raise InfrastructureNotAvailable(\n                f\"Unable to kill process {pid!r}: The process is running on a different\"\n                f\" host {hostname!r}.\"\n            )\n\n        # In a non-windows environment first send a SIGTERM, then, after\n        # `grace_seconds` seconds have passed subsequent send SIGKILL. In\n        # Windows we use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        if sys.platform == \"win32\":\n            try:\n                os.kill(pid, signal.CTRL_BREAK_EVENT)\n            except (ProcessLookupError, WindowsError):\n                raise InfrastructureNotFound(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n        else:\n            try:\n                os.kill(pid, signal.SIGTERM)\n            except ProcessLookupError:\n                raise InfrastructureNotFound(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n\n            # Throttle how often we check if the process is still alive to keep\n            # from making too many system calls in a short period of time.\n            check_interval = max(grace_seconds / 10, 1)\n\n            with anyio.move_on_after(grace_seconds):\n                while True:\n                    await anyio.sleep(check_interval)\n\n                    # Detect if the process is still alive. If not do an early\n                    # return as the process respected the SIGTERM from above.\n                    try:\n                        os.kill(pid, 0)\n                    except ProcessLookupError:\n                        return\n\n            try:\n                os.kill(pid, signal.SIGKILL)\n            except OSError:\n                # We shouldn't ever end up here, but it's possible that the\n                # process ended right after the check above.\n                return\n\n    def preview(self):\n        environment = self._get_environment_variables(include_os_environ=False)\n        return \" \\\\\\n\".join(\n            [f\"{key}={value}\" for key, value in environment.items()]\n            + [\" \".join(self.command)]\n        )\n\n    def _get_environment_variables(self, include_os_environ: bool = True):\n        os_environ = os.environ if include_os_environ else {}\n        # The base environment must override the current environment or\n        # the Prefect settings context may not be respected\n        env = {**os_environ, **self._base_environment(), **self.env}\n\n        # Drop null values allowing users to \"unset\" variables\n        return {key: value for key, value in env.items() if value is not None}\n\n    def _base_flow_run_command(self):\n        return [get_sys_executable(), \"-m\", \"prefect.engine\"]\n\n    def get_corresponding_worker_type(self):\n        return \"process\"\n\n    async def generate_work_pool_base_job_template(self):\n        from prefect.workers.utilities import (\n            get_default_base_job_template_for_infrastructure_type,\n        )\n\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Process worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Process work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/infrastructure/#prefect.infrastructure.ProcessResult","title":"<code>ProcessResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect/infrastructure/process.py</code> <pre><code>class ProcessResult(InfrastructureResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>","tags":["Python API","infrastructure","Docker","Kubernetes","subprocess","process"]},{"location":"api-ref/prefect/manifests/","title":"prefect.manifests","text":"","tags":["Python API","deployments"]},{"location":"api-ref/prefect/manifests/#prefect.manifests","title":"<code>prefect.manifests</code>","text":"<p>Manifests are portable descriptions of one or more workflows within a given directory structure.</p> <p>They are the foundational building blocks for defining Flow Deployments.</p>","tags":["Python API","deployments"]},{"location":"api-ref/prefect/manifests/#prefect.manifests.Manifest","title":"<code>Manifest</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A JSON representation of a flow.</p> Source code in <code>prefect/manifests.py</code> <pre><code>class Manifest(BaseModel):\n    \"\"\"A JSON representation of a flow.\"\"\"\n\n    flow_name: str = Field(default=..., description=\"The name of the flow.\")\n    import_path: str = Field(\n        default=..., description=\"The relative import path for the flow.\"\n    )\n    parameter_openapi_schema: ParameterSchema = Field(\n        default=..., description=\"The OpenAPI schema of the flow's parameters.\"\n    )\n</code></pre>","tags":["Python API","deployments"]},{"location":"api-ref/prefect/serializers/","title":"prefect.serializers","text":"","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers","title":"<code>prefect.serializers</code>","text":"<p>Serializer implementations for converting objects to bytes and bytes to objects.</p> <p>All serializers are based on the <code>Serializer</code> class and include a <code>type</code> string that allows them to be referenced without referencing the actual class. For example, you can get often specify the <code>JSONSerializer</code> with the string \"json\". Some serializers support additional settings for configuration of serialization. These are stored on the instance so the same settings can be used to load saved objects.</p> <p>All serializers must implement <code>dumps</code> and <code>loads</code> which convert objects to bytes and bytes to an object respectively.</p>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedJSONSerializer","title":"<code>CompressedJSONSerializer</code>","text":"<p>               Bases: <code>CompressedSerializer</code></p> <p>A compressed serializer preconfigured to use the json serializer.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedJSONSerializer(CompressedSerializer):\n    \"\"\"\n    A compressed serializer preconfigured to use the json serializer.\n    \"\"\"\n\n    type: Literal[\"compressed/json\"] = \"compressed/json\"\n\n    serializer: Serializer = Field(default_factory=JSONSerializer)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedPickleSerializer","title":"<code>CompressedPickleSerializer</code>","text":"<p>               Bases: <code>CompressedSerializer</code></p> <p>A compressed serializer preconfigured to use the pickle serializer.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedPickleSerializer(CompressedSerializer):\n    \"\"\"\n    A compressed serializer preconfigured to use the pickle serializer.\n    \"\"\"\n\n    type: Literal[\"compressed/pickle\"] = \"compressed/pickle\"\n\n    serializer: Serializer = Field(default_factory=PickleSerializer)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.CompressedSerializer","title":"<code>CompressedSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Wraps another serializer, compressing its output. Uses <code>lzma</code> by default. See <code>compressionlib</code> for using alternative libraries.</p> <p>Attributes:</p> Name Type Description <code>serializer</code> <code>Serializer</code> <p>The serializer to use before compression.</p> <code>compressionlib</code> <code>str</code> <p>The import path of a compression module to use. Must have methods <code>compress(bytes) -&gt; bytes</code> and <code>decompress(bytes) -&gt; bytes</code>.</p> <code>level</code> <code>str</code> <p>If not null, the level of compression to pass to <code>compress</code>.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class CompressedSerializer(Serializer):\n    \"\"\"\n    Wraps another serializer, compressing its output.\n    Uses `lzma` by default. See `compressionlib` for using alternative libraries.\n\n    Attributes:\n        serializer: The serializer to use before compression.\n        compressionlib: The import path of a compression module to use.\n            Must have methods `compress(bytes) -&gt; bytes` and `decompress(bytes) -&gt; bytes`.\n        level: If not null, the level of compression to pass to `compress`.\n    \"\"\"\n\n    type: Literal[\"compressed\"] = \"compressed\"\n\n    serializer: Serializer\n    compressionlib: str = \"lzma\"\n\n    @validator(\"serializer\", pre=True)\n    def validate_serializer(cls, value):\n        return cast_type_names_to_serializers(value)\n\n    @validator(\"compressionlib\")\n    def check_compressionlib(cls, value):\n        return validate_compressionlib(value)\n\n    def dumps(self, obj: Any) -&gt; bytes:\n        blob = self.serializer.dumps(obj)\n        compressor = from_qualified_name(self.compressionlib)\n        return base64.encodebytes(compressor.compress(blob))\n\n    def loads(self, blob: bytes) -&gt; Any:\n        compressor = from_qualified_name(self.compressionlib)\n        uncompressed = compressor.decompress(base64.decodebytes(blob))\n        return self.serializer.loads(uncompressed)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.JSONSerializer","title":"<code>JSONSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Serializes data to JSON.</p> <p>Input types must be compatible with the stdlib json library.</p> <p>Wraps the <code>json</code> library to serialize to UTF-8 bytes instead of string types.</p> Source code in <code>prefect/serializers.py</code> <pre><code>class JSONSerializer(Serializer):\n    \"\"\"\n    Serializes data to JSON.\n\n    Input types must be compatible with the stdlib json library.\n\n    Wraps the `json` library to serialize to UTF-8 bytes instead of string types.\n    \"\"\"\n\n    type: Literal[\"json\"] = \"json\"\n\n    jsonlib: str = \"json\"\n    object_encoder: Optional[str] = Field(\n        default=\"prefect.serializers.prefect_json_object_encoder\",\n        description=(\n            \"An optional callable to use when serializing objects that are not \"\n            \"supported by the JSON encoder. By default, this is set to a callable that \"\n            \"adds support for all types supported by \"\n        ),\n    )\n    object_decoder: Optional[str] = Field(\n        default=\"prefect.serializers.prefect_json_object_decoder\",\n        description=(\n            \"An optional callable to use when deserializing objects. This callable \"\n            \"is passed each dictionary encountered during JSON deserialization. \"\n            \"By default, this is set to a callable that deserializes content created \"\n            \"by our default `object_encoder`.\"\n        ),\n    )\n    dumps_kwargs: Dict[str, Any] = Field(default_factory=dict)\n    loads_kwargs: Dict[str, Any] = Field(default_factory=dict)\n\n    @validator(\"dumps_kwargs\")\n    def dumps_kwargs_cannot_contain_default(cls, value):\n        return validate_dump_kwargs(value)\n\n    @validator(\"loads_kwargs\")\n    def loads_kwargs_cannot_contain_object_hook(cls, value):\n        return validate_load_kwargs(value)\n\n    def dumps(self, data: Any) -&gt; bytes:\n        json = from_qualified_name(self.jsonlib)\n        kwargs = self.dumps_kwargs.copy()\n        if self.object_encoder:\n            kwargs[\"default\"] = from_qualified_name(self.object_encoder)\n        result = json.dumps(data, **kwargs)\n        if isinstance(result, str):\n            # The standard library returns str but others may return bytes directly\n            result = result.encode()\n        return result\n\n    def loads(self, blob: bytes) -&gt; Any:\n        json = from_qualified_name(self.jsonlib)\n        kwargs = self.loads_kwargs.copy()\n        if self.object_decoder:\n            kwargs[\"object_hook\"] = from_qualified_name(self.object_decoder)\n        return json.loads(blob.decode(), **kwargs)\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.PickleSerializer","title":"<code>PickleSerializer</code>","text":"<p>               Bases: <code>Serializer</code></p> <p>Serializes objects using the pickle protocol.</p> <ul> <li>Uses <code>cloudpickle</code> by default. See <code>picklelib</code> for using alternative libraries.</li> <li>Stores the version of the pickle library to check for compatibility during     deserialization.</li> <li>Wraps pickles in base64 for safe transmission.</li> </ul> Source code in <code>prefect/serializers.py</code> <pre><code>class PickleSerializer(Serializer):\n    \"\"\"\n    Serializes objects using the pickle protocol.\n\n    - Uses `cloudpickle` by default. See `picklelib` for using alternative libraries.\n    - Stores the version of the pickle library to check for compatibility during\n        deserialization.\n    - Wraps pickles in base64 for safe transmission.\n    \"\"\"\n\n    type: Literal[\"pickle\"] = \"pickle\"\n\n    picklelib: str = \"cloudpickle\"\n    picklelib_version: str = None\n\n    @validator(\"picklelib\")\n    def check_picklelib(cls, value):\n        return validate_picklelib(value)\n\n    @root_validator\n    def check_picklelib_version(cls, values):\n        return validate_picklelib_version(values)\n\n    def dumps(self, obj: Any) -&gt; bytes:\n        pickler = from_qualified_name(self.picklelib)\n        blob = pickler.dumps(obj)\n        return base64.encodebytes(blob)\n\n    def loads(self, blob: bytes) -&gt; Any:\n        pickler = from_qualified_name(self.picklelib)\n        return pickler.loads(base64.decodebytes(blob))\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer","title":"<code>Serializer</code>","text":"<p>               Bases: <code>BaseModel</code>, <code>Generic[D]</code>, <code>ABC</code></p> <p>A serializer that can encode objects of type 'D' into bytes.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@register_base_type\nclass Serializer(BaseModel, Generic[D], abc.ABC):\n    \"\"\"\n    A serializer that can encode objects of type 'D' into bytes.\n    \"\"\"\n\n    def __init__(self, **data: Any) -&gt; None:\n        type_string = get_dispatch_key(self) if type(self) != Serializer else \"__base__\"\n        data.setdefault(\"type\", type_string)\n        super().__init__(**data)\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        if \"type\" in kwargs:\n            try:\n                subcls = lookup_type(cls, dispatch_key=kwargs[\"type\"])\n            except KeyError as exc:\n                raise ValidationError(errors=[exc], model=cls)\n\n            return super().__new__(subcls)\n        else:\n            return super().__new__(cls)\n\n    type: str\n\n    @abc.abstractmethod\n    def dumps(self, obj: D) -&gt; bytes:\n        \"\"\"Encode the object into a blob of bytes.\"\"\"\n\n    @abc.abstractmethod\n    def loads(self, blob: bytes) -&gt; D:\n        \"\"\"Decode the blob of bytes into an object.\"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    @classmethod\n    def __dispatch_key__(cls):\n        return cls.__fields__.get(\"type\").get_default()\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer.dumps","title":"<code>dumps</code>  <code>abstractmethod</code>","text":"<p>Encode the object into a blob of bytes.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@abc.abstractmethod\ndef dumps(self, obj: D) -&gt; bytes:\n    \"\"\"Encode the object into a blob of bytes.\"\"\"\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.Serializer.loads","title":"<code>loads</code>  <code>abstractmethod</code>","text":"<p>Decode the blob of bytes into an object.</p> Source code in <code>prefect/serializers.py</code> <pre><code>@abc.abstractmethod\ndef loads(self, blob: bytes) -&gt; D:\n    \"\"\"Decode the blob of bytes into an object.\"\"\"\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.prefect_json_object_decoder","title":"<code>prefect_json_object_decoder</code>","text":"<p><code>JSONDecoder.object_hook</code> for decoding objects from JSON when previously encoded with <code>prefect_json_object_encoder</code></p> Source code in <code>prefect/serializers.py</code> <pre><code>def prefect_json_object_decoder(result: dict):\n    \"\"\"\n    `JSONDecoder.object_hook` for decoding objects from JSON when previously encoded\n    with `prefect_json_object_encoder`\n    \"\"\"\n    if \"__class__\" in result:\n        return parse_obj_as(from_qualified_name(result[\"__class__\"]), result[\"data\"])\n    elif \"__exc_type__\" in result:\n        return from_qualified_name(result[\"__exc_type__\"])(result[\"message\"])\n    else:\n        return result\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/serializers/#prefect.serializers.prefect_json_object_encoder","title":"<code>prefect_json_object_encoder</code>","text":"<p><code>JSONEncoder.default</code> for encoding objects into JSON with extended type support.</p> <p>Raises a <code>TypeError</code> to fallback on other encoders on failure.</p> Source code in <code>prefect/serializers.py</code> <pre><code>def prefect_json_object_encoder(obj: Any) -&gt; Any:\n    \"\"\"\n    `JSONEncoder.default` for encoding objects into JSON with extended type support.\n\n    Raises a `TypeError` to fallback on other encoders on failure.\n    \"\"\"\n    if isinstance(obj, BaseException):\n        return {\"__exc_type__\": to_qualified_name(obj.__class__), \"message\": str(obj)}\n    else:\n        return {\n            \"__class__\": to_qualified_name(obj.__class__),\n            \"data\": custom_pydantic_encoder({}, obj),\n        }\n</code></pre>","tags":["Python API","serializers","JSON","pickle"]},{"location":"api-ref/prefect/settings/","title":"prefect.settings","text":"","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings","title":"<code>prefect.settings</code>","text":"<p>Prefect settings management.</p> <p>Each setting is defined as a <code>Setting</code> type. The name of each setting is stylized in all caps, matching the environment variable that can be used to change the setting.</p> <p>All settings defined in this file are used to generate a dynamic Pydantic settings class called <code>Settings</code>. When instantiated, this class will load settings from environment variables and pull default values from the setting definitions.</p> <p>The current instance of <code>Settings</code> being used by the application is stored in a <code>SettingsContext</code> model which allows each instance of the <code>Settings</code> class to be accessed in an async-safe manner.</p> <p>Aside from environment variables, we allow settings to be changed during the runtime of the process using profiles. Profiles contain setting overrides that the user may persist without setting environment variables. Profiles are also used internally for managing settings during task run execution where differing settings may be used concurrently in the same process and during testing where we need to override settings to ensure their value is respected as intended.</p> <p>The <code>SettingsContext</code> is set when the <code>prefect</code> module is imported. This context is referred to as the \"root\" settings context for clarity. Generally, this is the only settings context that will be used. When this context is entered, we will instantiate a <code>Settings</code> object, loading settings from environment variables and defaults, then we will load the active profile and use it to override settings. See  <code>enter_root_settings_context</code> for details on determining the active profile.</p> <p>Another <code>SettingsContext</code> may be entered at any time to change the settings being used by the code within the context. Generally, users should not use this. Settings management should be left to Prefect application internals.</p> <p>Generally, settings should be accessed with <code>SETTING_VARIABLE.value()</code> which will pull the current <code>Settings</code> instance from the current <code>SettingsContext</code> and retrieve the value of the relevant setting.</p> <p>Accessing a setting's value will also call the <code>Setting.value_callback</code> which allows settings to be dynamically modified on retrieval. This allows us to make settings dependent on the value of other settings or perform other dynamic effects.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_HOME","title":"<code>PREFECT_HOME = Setting(Path, default=Path('~') / '.prefect', value_callback=expanduser_in_path)</code>  <code>module-attribute</code>","text":"<p>Prefect's home directory. Defaults to <code>~/.prefect</code>. This directory may be created automatically when required.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXTRA_ENTRYPOINTS","title":"<code>PREFECT_EXTRA_ENTRYPOINTS = Setting(str, default='')</code>  <code>module-attribute</code>","text":"<p>Modules for Prefect to import when Prefect is imported.</p> <p>Values should be separated by commas, e.g. <code>my_module,my_other_module</code>. Objects within modules may be specified by a ':' partition, e.g. <code>my_module:my_object</code>. If a callable object is provided, it will be called with no arguments on import.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEBUG_MODE","title":"<code>PREFECT_DEBUG_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, places the API in debug mode. This may modify behavior to facilitate debugging, including extra logs and other verbose assistance. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_COLORS","title":"<code>PREFECT_CLI_COLORS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, use colors in CLI output. If <code>False</code>, output will not include colors codes. Defaults to <code>True</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_PROMPT","title":"<code>PREFECT_CLI_PROMPT = Setting(Optional[bool], default=None)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, use interactive prompts in CLI commands. If <code>False</code>, no interactive prompts will be used. If <code>None</code>, the value will be dynamically determined based on the presence of an interactive-enabled terminal.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLI_WRAP_LINES","title":"<code>PREFECT_CLI_WRAP_LINES = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, wrap text by inserting new lines in long lines in CLI output. If <code>False</code>, output will not be wrapped. Defaults to <code>True</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TEST_MODE","title":"<code>PREFECT_TEST_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, places the API in test mode. This may modify behavior to facilitate testing. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UNIT_TEST_MODE","title":"<code>PREFECT_UNIT_TEST_MODE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>This variable only exists to facilitate unit testing. If <code>True</code>, code is executing in a unit test context. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UNIT_TEST_LOOP_DEBUG","title":"<code>PREFECT_UNIT_TEST_LOOP_DEBUG = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code> turns on debug mode for the unit testing event loop. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TEST_SETTING","title":"<code>PREFECT_TEST_SETTING = Setting(Any, default=None, value_callback=only_return_value_in_test_mode)</code>  <code>module-attribute</code>","text":"<p>This variable only exists to facilitate testing of settings. If accessed when <code>PREFECT_TEST_MODE</code> is not set, <code>None</code> is returned.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_TLS_INSECURE_SKIP_VERIFY","title":"<code>PREFECT_API_TLS_INSECURE_SKIP_VERIFY = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, disables SSL checking to allow insecure requests. This is recommended only during development, e.g. when using self-signed certificates.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SSL_CERT_FILE","title":"<code>PREFECT_API_SSL_CERT_FILE = Setting(str, default=os.environ.get('SSL_CERT_FILE'))</code>  <code>module-attribute</code>","text":"<p>This configuration settings option specifies the path to an SSL certificate file. When set, it allows the application to use the specified certificate for secure communication. If left unset, the setting will default to the value provided by the <code>SSL_CERT_FILE</code> environment variable.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_URL","title":"<code>PREFECT_API_URL = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>If provided, the URL of a hosted Prefect API. Defaults to <code>None</code>.</p> <p>When using Prefect Cloud, this will include an account and workspace.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SILENCE_API_URL_MISCONFIGURATION","title":"<code>PREFECT_SILENCE_API_URL_MISCONFIGURATION = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, disable the warning when a user accidentally misconfigure its <code>PREFECT_API_URL</code> Sometimes when a user manually set <code>PREFECT_API_URL</code> to a custom url,reverse-proxy for example, we would like to silence this warning so we will set it to <code>FALSE</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_KEY","title":"<code>PREFECT_API_KEY = Setting(str, default=None, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>API key used to authenticate with a the Prefect API. Defaults to <code>None</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_ENABLE_HTTP2","title":"<code>PREFECT_API_ENABLE_HTTP2 = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If true, enable support for HTTP/2 for communicating with an API.</p> <p>If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_MAX_RETRIES","title":"<code>PREFECT_CLIENT_MAX_RETRIES = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>The maximum number of retries to perform on failed HTTP requests.</p> <p>Defaults to 5. Set to 0 to disable retries.</p> <p>See <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> for details on which HTTP status codes are retried.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_RETRY_JITTER_FACTOR","title":"<code>PREFECT_CLIENT_RETRY_JITTER_FACTOR = Setting(float, default=0.2)</code>  <code>module-attribute</code>","text":"<p>A value greater than or equal to zero to control the amount of jitter added to retried client requests. Higher values introduce larger amounts of jitter.</p> <p>Set to 0 to disable jitter. See <code>clamped_poisson_interval</code> for details on the how jitter can affect retry lengths.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_RETRY_EXTRA_CODES","title":"<code>PREFECT_CLIENT_RETRY_EXTRA_CODES = Setting(str, default='', value_callback=status_codes_as_integers_in_range)</code>  <code>module-attribute</code>","text":"<p>A comma-separated list of extra HTTP status codes to retry on. Defaults to an empty string. 429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying may result in unexpected behavior.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLIENT_CSRF_SUPPORT_ENABLED","title":"<code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Determines if CSRF token handling is active in the Prefect client for API requests.</p> <p>When enabled (<code>True</code>), the client automatically manages CSRF tokens by retrieving, storing, and including them in applicable state-changing requests (POST, PUT, PATCH, DELETE) to the API.</p> <p>Disabling this setting (<code>False</code>) means the client will not handle CSRF tokens, which might be suitable for environments where CSRF protection is disabled.</p> <p>Defaults to <code>True</code>, ensuring CSRF protection is enabled by default.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_API_URL","title":"<code>PREFECT_CLOUD_API_URL = Setting(str, default='https://api.prefect.cloud/api', value_callback=check_for_deprecated_cloud_url)</code>  <code>module-attribute</code>","text":"<p>API URL for Prefect Cloud. Used for authentication.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_URL","title":"<code>PREFECT_CLOUD_URL = Setting(str, default=None, deprecated=True, deprecated_start_date='Dec 2022', deprecated_help='Use `PREFECT_CLOUD_API_URL` instead.')</code>  <code>module-attribute</code>","text":"","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_URL","title":"<code>PREFECT_UI_URL = Setting(Optional[str], default=None, value_callback=default_ui_url)</code>  <code>module-attribute</code>","text":"<p>The URL for the UI. By default, this is inferred from the PREFECT_API_URL.</p> <p>When using Prefect Cloud, this will include the account and workspace. When using an ephemeral server, this will be <code>None</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_CLOUD_UI_URL","title":"<code>PREFECT_CLOUD_UI_URL = Setting(str, default=None, value_callback=default_cloud_ui_url)</code>  <code>module-attribute</code>","text":"<p>The URL for the Cloud UI. By default, this is inferred from the PREFECT_CLOUD_API_URL.</p> PREFECT_UI_URL will be workspace specific and will be usable in the open source too. <p>In contrast, this value is only valid for Cloud and will not include the workspace.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_REQUEST_TIMEOUT","title":"<code>PREFECT_API_REQUEST_TIMEOUT = Setting(float, default=60.0)</code>  <code>module-attribute</code>","text":"<p>The default timeout for requests to the API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN","title":"<code>PREFECT_EXPERIMENTAL_WARN = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If enabled, warn on usage of experimental features.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_PROFILES_PATH","title":"<code>PREFECT_PROFILES_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'profiles.toml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a profiles configuration files.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RESULTS_DEFAULT_SERIALIZER","title":"<code>PREFECT_RESULTS_DEFAULT_SERIALIZER = Setting(str, default='pickle')</code>  <code>module-attribute</code>","text":"<p>The default serializer to use when not otherwise specified.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RESULTS_PERSIST_BY_DEFAULT","title":"<code>PREFECT_RESULTS_PERSIST_BY_DEFAULT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>The default setting for persisting results when not otherwise specified. If enabled, flow and task results will be persisted unless they opt out.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASKS_REFRESH_CACHE","title":"<code>PREFECT_TASKS_REFRESH_CACHE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, enables a refresh of cached results: re-executing the task will refresh the cached results. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_DEFAULT_RETRIES","title":"<code>PREFECT_TASK_DEFAULT_RETRIES = Setting(int, default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default number of retries for all tasks. This value does not overwrite individually set retries values on tasks</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_FLOW_DEFAULT_RETRIES","title":"<code>PREFECT_FLOW_DEFAULT_RETRIES = Setting(int, default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default number of retries for all flows. This value does not overwrite individually set retries values on a flow</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS","title":"<code>PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS = Setting(Union[int, float], default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the retry delay seconds for all flows. This value does not overwrite individually set retry delay seconds</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS","title":"<code>PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS = Setting(Union[float, int, List[float]], default=0)</code>  <code>module-attribute</code>","text":"<p>This value sets the default retry delay seconds for all tasks. This value does not overwrite individually set retry delay seconds</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS","title":"<code>PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS = Setting(int, default=30)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOCAL_STORAGE_PATH","title":"<code>PREFECT_LOCAL_STORAGE_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'storage', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a block storage directory to store things in.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MEMO_STORE_PATH","title":"<code>PREFECT_MEMO_STORE_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'memo_store.toml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to the memo store file.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION","title":"<code>PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Controls whether or not block auto-registration on start up should be memoized. Setting to False may result in slower server start up times.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_LEVEL","title":"<code>PREFECT_LOGGING_LEVEL = Setting(str, default='INFO', value_callback=debug_mode_log_level)</code>  <code>module-attribute</code>","text":"<p>The default logging level for Prefect loggers. Defaults to \"INFO\" during normal operation. Is forced to \"DEBUG\" during debug mode.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_INTERNAL_LEVEL","title":"<code>PREFECT_LOGGING_INTERNAL_LEVEL = Setting(str, default='ERROR', value_callback=debug_mode_log_level)</code>  <code>module-attribute</code>","text":"<p>The default logging level for Prefect's internal machinery loggers. Defaults to \"ERROR\" during normal operation. Is forced to \"DEBUG\" during debug mode.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_SERVER_LEVEL","title":"<code>PREFECT_LOGGING_SERVER_LEVEL = Setting(str, default='WARNING')</code>  <code>module-attribute</code>","text":"<p>The default logging level for the Prefect API server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_SETTINGS_PATH","title":"<code>PREFECT_LOGGING_SETTINGS_PATH = Setting(Path, default=Path('${PREFECT_HOME}') / 'logging.yml', value_callback=template_with_settings(PREFECT_HOME))</code>  <code>module-attribute</code>","text":"<p>The path to a custom YAML logging configuration file. If no file is found, the default <code>logging.yml</code> is used. Defaults to a logging.yml in the Prefect home directory.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_EXTRA_LOGGERS","title":"<code>PREFECT_LOGGING_EXTRA_LOGGERS = Setting(str, default='', value_callback=get_extra_loggers)</code>  <code>module-attribute</code>","text":"<p>Additional loggers to attach to Prefect logging at runtime. Values should be comma separated. The handlers attached to the 'prefect' logger will be added to these loggers. Additionally, if the level is not set, it will be set to the same level as the 'prefect' logger.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_LOG_PRINTS","title":"<code>PREFECT_LOGGING_LOG_PRINTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If set, <code>print</code> statements in flows and tasks will be redirected to the Prefect logger for the given run. This setting can be overridden by individual tasks and flows.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_ENABLED","title":"<code>PREFECT_LOGGING_TO_API_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Toggles sending logs to the API. If <code>False</code>, logs sent to the API log handler will not be sent to the API.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_BATCH_INTERVAL","title":"<code>PREFECT_LOGGING_TO_API_BATCH_INTERVAL = Setting(float, default=2.0)</code>  <code>module-attribute</code>","text":"<p>The number of seconds between batched writes of logs to the API.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_BATCH_SIZE","title":"<code>PREFECT_LOGGING_TO_API_BATCH_SIZE = Setting(int, default=4000000)</code>  <code>module-attribute</code>","text":"<p>The maximum size in bytes for a batch of logs.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_MAX_LOG_SIZE","title":"<code>PREFECT_LOGGING_TO_API_MAX_LOG_SIZE = Setting(int, default=1000000)</code>  <code>module-attribute</code>","text":"<p>The maximum size in bytes for a single log.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW","title":"<code>PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW = Setting(Literal['warn', 'error', 'ignore'], default='warn')</code>  <code>module-attribute</code>","text":"<p>Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.</p> <p>All logs sent to the API must be associated with a flow run. The API log handler can only be used outside of a flow by manually providing a flow run identifier. Logs that are not associated with a flow run will not be sent to the API. This setting can be used to determine if a warning or error is displayed when the identifier is missing.</p> <p>The following options are available:</p> <ul> <li>\"warn\": Log a warning message.</li> <li>\"error\": Raise an error.</li> <li>\"ignore\": Do not log a warning message or raise an error.</li> </ul>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SQLALCHEMY_POOL_SIZE","title":"<code>PREFECT_SQLALCHEMY_POOL_SIZE = Setting(int, default=None)</code>  <code>module-attribute</code>","text":"<p>Controls connection pool size when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy pool size will be used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SQLALCHEMY_MAX_OVERFLOW","title":"<code>PREFECT_SQLALCHEMY_MAX_OVERFLOW = Setting(int, default=None)</code>  <code>module-attribute</code>","text":"<p>Controls maximum overflow of the connection pool when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy maximum overflow value will be used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_COLORS","title":"<code>PREFECT_LOGGING_COLORS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether to style console logs with color.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_LOGGING_MARKUP","title":"<code>PREFECT_LOGGING_MARKUP = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether to interpret strings wrapped in square brackets as a style. This allows styles to be conveniently added to log messages, e.g. <code>[red]This is a red message.[/red]</code>. However, the downside is, if enabled, strings that contain square brackets may be inaccurately interpreted and lead to incomplete output, e.g. <code>DROP TABLE [dbo].[SomeTable];\"</code> outputs <code>DROP TABLE .[SomeTable];</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD","title":"<code>PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD = Setting(float, default=10.0)</code>  <code>module-attribute</code>","text":"<p>Threshold time in seconds for logging a warning if task parameter introspection exceeds this duration. Parameter introspection can be a significant performance hit when the parameter is a large collection object, e.g. a large dictionary or DataFrame, and each element needs to be inspected. See <code>prefect.utilities.annotations.quote</code> for more details. Defaults to <code>10.0</code>. Set to <code>0</code> to disable logging the warning.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_AGENT_QUERY_INTERVAL","title":"<code>PREFECT_AGENT_QUERY_INTERVAL = Setting(float, default=15)</code>  <code>module-attribute</code>","text":"<p>The agent loop interval, in seconds. Agents will check for new runs this often. Defaults to <code>15</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_AGENT_PREFETCH_SECONDS","title":"<code>PREFECT_AGENT_PREFETCH_SECONDS = Setting(int, default=15)</code>  <code>module-attribute</code>","text":"<p>Agents will look for scheduled runs this many seconds in the future and attempt to run them. This accounts for any additional infrastructure spin-up time or latency in preparing a flow run. Note flow runs will not start before their scheduled time, even if they are prefetched. Defaults to <code>15</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_ASYNC_FETCH_STATE_RESULT","title":"<code>PREFECT_ASYNC_FETCH_STATE_RESULT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Determines whether <code>State.result()</code> fetches results automatically or not. In Prefect 2.6.0, the <code>State.result()</code> method was updated to be async to facilitate automatic retrieval of results from storage which means when writing async code you must <code>await</code> the call. For backwards compatibility, the result is not retrieved by default for async users. You may opt into this per call by passing  <code>fetch=True</code> or toggle this setting to change the behavior globally. This setting does not affect users writing synchronous tasks and flows. This setting does not affect retrieval of results when using <code>Future.result()</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_BLOCKS_REGISTER_ON_START","title":"<code>PREFECT_API_BLOCKS_REGISTER_ON_START = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_PASSWORD","title":"<code>PREFECT_API_DATABASE_PASSWORD = Setting(str, default=None, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>Password to template into the <code>PREFECT_API_DATABASE_CONNECTION_URL</code>. This is useful if the password must be provided separately from the connection URL. To use this setting, you must include it in your connection URL.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_CONNECTION_URL","title":"<code>PREFECT_API_DATABASE_CONNECTION_URL = Setting(str, default=None, value_callback=default_database_connection_url, is_secret=True)</code>  <code>module-attribute</code>","text":"<p>A database connection URL in a SQLAlchemy-compatible format. Prefect currently supports SQLite and Postgres. Note that all Prefect database engines must use an async driver - for SQLite, use <code>sqlite+aiosqlite</code> and for Postgres use <code>postgresql+asyncpg</code>.</p> <p>SQLite in-memory databases can be used by providing the url <code>sqlite+aiosqlite:///file::memory:?cache=shared&amp;uri=true&amp;check_same_thread=false</code>, which will allow the database to be accessed by multiple threads. Note that in-memory databases can not be accessed from multiple processes and should only be used for simple tests.</p> <p>Defaults to a sqlite database stored in the Prefect home directory.</p> <p>If you need to provide password via a different environment variable, you use the <code>PREFECT_API_DATABASE_PASSWORD</code> setting. For example:</p> <pre><code>PREFECT_API_DATABASE_PASSWORD='mypassword'\nPREFECT_API_DATABASE_CONNECTION_URL='postgresql+asyncpg://postgres:${PREFECT_API_DATABASE_PASSWORD}@localhost/prefect'\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_ECHO","title":"<code>PREFECT_API_DATABASE_ECHO = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, SQLAlchemy will log all SQL issued to the database. Defaults to <code>False</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_MIGRATE_ON_START","title":"<code>PREFECT_API_DATABASE_MIGRATE_ON_START = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>If <code>True</code>, the database will be upgraded on application creation. If <code>False</code>, the database will need to be upgraded manually.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_TIMEOUT","title":"<code>PREFECT_API_DATABASE_TIMEOUT = Setting(Optional[float], default=10.0)</code>  <code>module-attribute</code>","text":"<p>A statement timeout, in seconds, applied to all database interactions made by the API. Defaults to 10 seconds.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DATABASE_CONNECTION_TIMEOUT","title":"<code>PREFECT_API_DATABASE_CONNECTION_TIMEOUT = Setting(Optional[float], default=5)</code>  <code>module-attribute</code>","text":"<p>A connection timeout, in seconds, applied to database connections. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS = Setting(float, default=60)</code>  <code>module-attribute</code>","text":"<p>The scheduler loop interval, in seconds. This determines how often the scheduler will attempt to schedule new flow runs, but has no impact on how quickly either flow runs or task runs are actually executed. Defaults to <code>60</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The number of deployments the scheduler will attempt to schedule in a single batch. If there are more deployments than the batch size, the scheduler immediately attempts to schedule the next batch; it does not sleep for <code>scheduler_loop_seconds</code> until it has visited every deployment once. Defaults to <code>100</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The scheduler will attempt to schedule up to this many auto-scheduled runs in the future. Note that runs may have fewer than this many scheduled runs, depending on the value of <code>scheduler_max_scheduled_time</code>.  Defaults to <code>100</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS = Setting(int, default=3)</code>  <code>module-attribute</code>","text":"<p>The scheduler will attempt to schedule at least this many auto-scheduled runs in the future. Note that runs may have more than this many scheduled runs, depending on the value of <code>scheduler_min_scheduled_time</code>.  Defaults to <code>3</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME = Setting(timedelta, default=timedelta(days=100))</code>  <code>module-attribute</code>","text":"<p>The scheduler will create new runs up to this far in the future. Note that this setting will take precedence over <code>scheduler_max_runs</code>: if a flow runs once a month and <code>scheduler_max_scheduled_time</code> is three months, then only three runs will be scheduled. Defaults to 100 days (<code>8640000</code> seconds).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME","title":"<code>PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME = Setting(timedelta, default=timedelta(hours=1))</code>  <code>module-attribute</code>","text":"<p>The scheduler will create new runs at least this far in the future. Note that this setting will take precedence over <code>scheduler_min_runs</code>: if a flow runs every hour and <code>scheduler_min_scheduled_time</code> is three hours, then three runs will be scheduled even if <code>scheduler_min_runs</code> is 1. Defaults to 1 hour (<code>3600</code> seconds).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The number of flow runs the scheduler will attempt to insert in one batch across all deployments. If the number of flow runs to schedule exceeds this amount, the runs will be inserted in batches of this size. Defaults to <code>500</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS = Setting(float, default=5)</code>  <code>module-attribute</code>","text":"<p>The late runs service will look for runs to mark as late this often. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS = Setting(timedelta, default=timedelta(seconds=15))</code>  <code>module-attribute</code>","text":"<p>The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to <code>5</code> seconds.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS = Setting(float, default=5)</code>  <code>module-attribute</code>","text":"<p>The pause expiration service will look for runs to mark as failed this often. Defaults to <code>5</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS = Setting(float, default=20)</code>  <code>module-attribute</code>","text":"<p>The cancellation cleanup service will look non-terminal tasks and subflows this often. Defaults to <code>20</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_ENABLED","title":"<code>PREFECT_API_SERVICES_FOREMAN_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the Foreman service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS = Setting(float, default=15)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to wait between each iteration of the Foreman loop which checks for offline workers and updates work pool status.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE","title":"<code>PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE = Setting(int, default=3)</code>  <code>module-attribute</code>","text":"<p>The number of heartbeats that must be missed before a worker is marked as offline.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS = Setting(int, default=30)</code>  <code>module-attribute</code>","text":"<p>The number of seconds to use for online/offline evaluation if a worker's heartbeat interval is not set.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS = Setting(int, default=60)</code>  <code>module-attribute</code>","text":"<p>The number of seconds before a deployment is marked as not ready if it has not been polled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS","title":"<code>PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS = Setting(int, default=60)</code>  <code>module-attribute</code>","text":"<p>The number of seconds before a work queue is marked as not ready if it has not been polled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_DEFAULT_LIMIT","title":"<code>PREFECT_API_DEFAULT_LIMIT = Setting(int, default=200)</code>  <code>module-attribute</code>","text":"<p>The default limit applied to queries that can return multiple objects, such as <code>POST /flow_runs/filter</code>.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_HOST","title":"<code>PREFECT_SERVER_API_HOST = Setting(str, default='127.0.0.1')</code>  <code>module-attribute</code>","text":"<p>The API's host address (defaults to <code>127.0.0.1</code>).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_PORT","title":"<code>PREFECT_SERVER_API_PORT = Setting(int, default=4200)</code>  <code>module-attribute</code>","text":"<p>The API's port address (defaults to <code>4200</code>).</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_API_KEEPALIVE_TIMEOUT","title":"<code>PREFECT_SERVER_API_KEEPALIVE_TIMEOUT = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>The API's keep alive timeout (defaults to <code>5</code>). Refer to https://www.uvicorn.org/settings/#timeouts for details.</p> <p>When the API is hosted behind a load balancer, you may want to set this to a value greater than the load balancer's idle timeout.</p> <p>Note this setting only applies when calling <code>prefect server start</code>; if hosting the API with another tool you will need to configure this there instead.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED","title":"<code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Controls the activation of CSRF protection for the Prefect server API.</p> <p>When enabled (<code>True</code>), the server enforces CSRF validation checks on incoming state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF token to be included in the request headers or body. This adds a layer of security by preventing unauthorized or malicious sites from making requests on behalf of authenticated users.</p> <p>It is recommended to enable this setting in production environments where the API is exposed to web clients to safeguard against CSRF attacks.</p> <p>Note: Enabling this setting requires corresponding support in the client for CSRF token management. See PREFECT_CLIENT_CSRF_SUPPORT_ENABLED for more.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_CSRF_TOKEN_EXPIRATION","title":"<code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION = Setting(timedelta, default=timedelta(hours=1))</code>  <code>module-attribute</code>","text":"<p>Specifies the duration for which a CSRF token remains valid after being issued by the server.</p> <p>The default expiration time is set to 1 hour, which offers a reasonable compromise. Adjust this setting based on your specific security requirements and usage patterns.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_ENABLED","title":"<code>PREFECT_UI_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to serve the Prefect UI.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_API_URL","title":"<code>PREFECT_UI_API_URL = Setting(str, default=None, value_callback=default_ui_api_url)</code>  <code>module-attribute</code>","text":"<p>The connection url for communication from the UI to the API. Defaults to <code>PREFECT_API_URL</code> if set. Otherwise, the default URL is generated from <code>PREFECT_SERVER_API_HOST</code> and <code>PREFECT_SERVER_API_PORT</code>. If providing a custom value, the aforementioned settings may be templated into the given string.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_SERVER_ANALYTICS_ENABLED","title":"<code>PREFECT_SERVER_ANALYTICS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version) on server startup to help us improve our product.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_SCHEDULER_ENABLED","title":"<code>PREFECT_API_SERVICES_SCHEDULER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the scheduling service in the server application. If disabled, you will need to run this service separately to schedule runs for deployments.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_ENABLED","title":"<code>PREFECT_API_SERVICES_LATE_RUNS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the late runs service in the server application. If disabled, you will need to run this service separately to have runs past their scheduled start time marked as late.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED","title":"<code>PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the flow run notifications service in the server application. If disabled, you will need to run this service separately to send flow run notifications.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED","title":"<code>PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the paused flow run expiration service in the server application. If disabled, paused flows that have timed out will remain in a Paused state until a resume attempt.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH","title":"<code>PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH = Setting(int, default=2000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of characters allowed for a task run cache key. This setting cannot be changed client-side, it must be set on the server.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED","title":"<code>PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the cancellation cleanup service in the server application. If disabled, task runs and subflow runs belonging to cancelled flows may remain in non-terminal states.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES","title":"<code>PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES = Setting(int, default=10000)</code>  <code>module-attribute</code>","text":"<p>The maximum size of a flow run graph on the v2 API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS","title":"<code>PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS = Setting(int, default=10000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of artifacts to show on a flow run graph on the v2 API</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS_ON_FLOW_RUN_GRAPH","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS_ON_FLOW_RUN_GRAPH = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable artifacts on the flow run graph.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_STATES_ON_FLOW_RUN_GRAPH = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run states on the flow run graph.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORK_POOLS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect work pools.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORK_POOLS","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORK_POOLS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect work pools are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKERS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORKERS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect workers.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKERS","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORKERS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect workers are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_VISUALIZE","title":"<code>PREFECT_EXPERIMENTAL_WARN_VISUALIZE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect visualize is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental enhanced flow run cancellation.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION","title":"<code>PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental enhanced flow run cancellation is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_DEPLOYMENT_STATUS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_DEPLOYMENT_STATUS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable deployment status in the UI</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS","title":"<code>PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when deployment status is used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT","title":"<code>PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run input.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT","title":"<code>PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable flow run input.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_EVENTS","title":"<code>PREFECT_EXPERIMENTAL_EVENTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether to enable Prefect's server-side event features. Note that Prefect Cloud clients will always emit events during flow and task runs regardless of this setting.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_PROCESS_LIMIT","title":"<code>PREFECT_RUNNER_PROCESS_LIMIT = Setting(int, default=5)</code>  <code>module-attribute</code>","text":"<p>Maximum number of processes a runner will execute in parallel.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_POLL_FREQUENCY","title":"<code>PREFECT_RUNNER_POLL_FREQUENCY = Setting(int, default=10)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a runner should wait between queries for scheduled work.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE","title":"<code>PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE = Setting(int, default=2)</code>  <code>module-attribute</code>","text":"<p>Number of missed polls before a runner is considered unhealthy by its webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_HOST","title":"<code>PREFECT_RUNNER_SERVER_HOST = Setting(str, default='localhost')</code>  <code>module-attribute</code>","text":"<p>The host address the runner's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_PORT","title":"<code>PREFECT_RUNNER_SERVER_PORT = Setting(int, default=8080)</code>  <code>module-attribute</code>","text":"<p>The port the runner's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_LOG_LEVEL","title":"<code>PREFECT_RUNNER_SERVER_LOG_LEVEL = Setting(str, default='error')</code>  <code>module-attribute</code>","text":"<p>The log level of the runner's webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_RUNNER_SERVER_ENABLE","title":"<code>PREFECT_RUNNER_SERVER_ENABLE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable the runner's webserver.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS","title":"<code>PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS = Setting(int, default=50)</code>  <code>module-attribute</code>","text":"<p>The maximum number of scheduled runs to create for a deployment.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_HEARTBEAT_SECONDS","title":"<code>PREFECT_WORKER_HEARTBEAT_SECONDS = Setting(float, default=30)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a worker should wait between sending a heartbeat.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_QUERY_SECONDS","title":"<code>PREFECT_WORKER_QUERY_SECONDS = Setting(float, default=10)</code>  <code>module-attribute</code>","text":"<p>Number of seconds a worker should wait between queries for scheduled flow runs.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_PREFETCH_SECONDS","title":"<code>PREFECT_WORKER_PREFETCH_SECONDS = Setting(float, default=10)</code>  <code>module-attribute</code>","text":"<p>The number of seconds into the future a worker should query for scheduled flow runs. Can be used to compensate for infrastructure start up time for a worker.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_WEBSERVER_HOST","title":"<code>PREFECT_WORKER_WEBSERVER_HOST = Setting(str, default='0.0.0.0')</code>  <code>module-attribute</code>","text":"<p>The host address the worker's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_WORKER_WEBSERVER_PORT","title":"<code>PREFECT_WORKER_WEBSERVER_PORT = Setting(int, default=8080)</code>  <code>module-attribute</code>","text":"<p>The port the worker's webserver should bind to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK","title":"<code>PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK = Setting(str, default='local-file-system/prefect-task-scheduling')</code>  <code>module-attribute</code>","text":"<p>The <code>block-type/block-document</code> slug of a block to use as the default storage for autonomous tasks.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS","title":"<code>PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to delete failed task submissions from the database.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE","title":"<code>PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE = Setting(int, default=1000)</code>  <code>module-attribute</code>","text":"<p>The maximum number of scheduled tasks to queue for submission.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE","title":"<code>PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE = Setting(int, default=100)</code>  <code>module-attribute</code>","text":"<p>The maximum number of retries to queue for submission.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT","title":"<code>PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT = Setting(timedelta, default=timedelta(seconds=30))</code>  <code>module-attribute</code>","text":"<p>How long before a PENDING task are made available to another task server.  In practice, a task server should move a task from PENDING to RUNNING very quickly, so runs stuck in PENDING for a while is a sign that the task server may have crashed.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental worker webserver endpoints.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental Prefect artifacts.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_ARTIFACTS","title":"<code>PREFECT_EXPERIMENTAL_WARN_ARTIFACTS = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when experimental Prefect artifacts are used.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORKSPACE_DASHBOARD","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORKSPACE_DASHBOARD = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable the experimental workspace dashboard.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_WARN_WORKSPACE_DASHBOARD","title":"<code>PREFECT_EXPERIMENTAL_WARN_WORKSPACE_DASHBOARD = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to warn when the experimental workspace dashboard is enabled.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental task scheduling.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_WORK_QUEUE_STATUS","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_WORK_QUEUE_STATUS = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental work queue status in-place of work queue health.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE","title":"<code>PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to enable experimental new engine.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT","title":"<code>PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT = Setting(bool, default=False)</code>  <code>module-attribute</code>","text":"<p>Whether or not to disable the sync_compatible decorator utility.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_RESULT_STORAGE_BLOCK","title":"<code>PREFECT_DEFAULT_RESULT_STORAGE_BLOCK = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The <code>block-type/block-document</code> slug of a block to use as the default result storage.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_WORK_POOL_NAME","title":"<code>PREFECT_DEFAULT_WORK_POOL_NAME = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The default work pool to deploy to.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE","title":"<code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The default Docker namespace to use when building images.</p> <p>Can be either an organization/username or a registry URL with an organization/username.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_SERVE_BASE","title":"<code>PREFECT_UI_SERVE_BASE = Setting(str, default='/')</code>  <code>module-attribute</code>","text":"<p>The base URL path to serve the Prefect UI from.</p> <p>Defaults to the root path.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_UI_STATIC_DIRECTORY","title":"<code>PREFECT_UI_STATIC_DIRECTORY = Setting(str, default=None)</code>  <code>module-attribute</code>","text":"<p>The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container)</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MESSAGING_BROKER","title":"<code>PREFECT_MESSAGING_BROKER = Setting(str, default='prefect.server.utilities.messaging.memory')</code>  <code>module-attribute</code>","text":"<p>Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_MESSAGING_CACHE","title":"<code>PREFECT_MESSAGING_CACHE = Setting(str, default='prefect.server.utilities.messaging.memory')</code>  <code>module-attribute</code>","text":"<p>Which cache implementation to use for the events system.  Should point to a module that exports a Cache class.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE","title":"<code>PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The maximum number of labels a resource may have.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES","title":"<code>PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES = Setting(int, default=500)</code>  <code>module-attribute</code>","text":"<p>The maximum number of related resources an Event may have.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_MAXIMUM_SIZE_BYTES","title":"<code>PREFECT_EVENTS_MAXIMUM_SIZE_BYTES = Setting(int, default=1500000)</code>  <code>module-attribute</code>","text":"<p>The maximum size of an Event when serialized to JSON</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED","title":"<code>PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the event debug logger service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_TRIGGERS_ENABLED","title":"<code>PREFECT_API_SERVICES_TRIGGERS_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the triggers service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER","title":"<code>PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER = Setting(timedelta, default=timedelta(seconds=60))</code>  <code>module-attribute</code>","text":"<p>The amount of time to retain expired automation buckets</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_PROACTIVE_GRANULARITY","title":"<code>PREFECT_EVENTS_PROACTIVE_GRANULARITY = Setting(timedelta, default=timedelta(seconds=5))</code>  <code>module-attribute</code>","text":"<p>How frequently proactive automations are evaluated</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to start the event persister service in the server application.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE = Setting(int, default=20, gt=0)</code>  <code>module-attribute</code>","text":"<p>The number of events the event persister will attempt to insert in one batch.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL","title":"<code>PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL = Setting(float, default=5, gt=0.0)</code>  <code>module-attribute</code>","text":"<p>The maximum number of seconds between flushes of the event persister.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_EVENTS_RETENTION_PERIOD","title":"<code>PREFECT_EVENTS_RETENTION_PERIOD = Setting(timedelta, default=timedelta(days=7))</code>  <code>module-attribute</code>","text":"<p>The amount of time to retain events in the database.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_EVENTS_STREAM_OUT_ENABLED","title":"<code>PREFECT_API_EVENTS_STREAM_OUT_ENABLED = Setting(bool, default=True)</code>  <code>module-attribute</code>","text":"<p>Whether or not to allow streaming events out of via websockets.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL","title":"<code>PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL = Setting(timedelta, default=timedelta(minutes=5))</code>  <code>module-attribute</code>","text":"<p>How long to cache related resource data for emitting server-side vents</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting","title":"<code>Setting</code>","text":"<p>               Bases: <code>Generic[T]</code></p> <p>Setting definition type.</p> Source code in <code>prefect/settings.py</code> <pre><code>class Setting(Generic[T]):\n    \"\"\"\n    Setting definition type.\n    \"\"\"\n\n    def __init__(\n        self,\n        type: Type[T],\n        *,\n        deprecated: bool = False,\n        deprecated_start_date: Optional[str] = None,\n        deprecated_end_date: Optional[str] = None,\n        deprecated_help: str = \"\",\n        deprecated_when_message: str = \"\",\n        deprecated_when: Optional[Callable[[Any], bool]] = None,\n        deprecated_renamed_to: Optional[\"Setting[T]\"] = None,\n        value_callback: Optional[Callable[[\"Settings\", T], T]] = None,\n        is_secret: bool = False,\n        **kwargs: Any,\n    ) -&gt; None:\n        self.field: fields.FieldInfo = Field(**kwargs)\n        self.type = type\n        self.value_callback = value_callback\n        self._name = None\n        self.is_secret = is_secret\n        self.deprecated = deprecated\n        self.deprecated_start_date = deprecated_start_date\n        self.deprecated_end_date = deprecated_end_date\n        self.deprecated_help = deprecated_help\n        self.deprecated_when = deprecated_when or (lambda _: True)\n        self.deprecated_when_message = deprecated_when_message\n        self.deprecated_renamed_to = deprecated_renamed_to\n        self.deprecated_renamed_from = None\n        self.__doc__ = self.field.description\n\n        # Validate the deprecation settings, will throw an error at setting definition\n        # time if the developer has not configured it correctly\n        if deprecated:\n            generate_deprecation_message(\n                name=\"...\",  # setting names not populated until after init\n                start_date=self.deprecated_start_date,\n                end_date=self.deprecated_end_date,\n                help=self.deprecated_help,\n                when=self.deprecated_when_message,\n            )\n\n        if deprecated_renamed_to is not None:\n            # Track the deprecation both ways\n            deprecated_renamed_to.deprecated_renamed_from = self\n\n    def value(self, bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Get the current value of a setting.\n\n        Example:\n        ```python\n        from prefect.settings import PREFECT_API_URL\n        PREFECT_API_URL.value()\n        ```\n        \"\"\"\n        return self.value_from(get_current_settings(), bypass_callback=bypass_callback)\n\n    def value_from(self, settings: \"Settings\", bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Get the value of a setting from a settings object\n\n        Example:\n        ```python\n        from prefect.settings import get_default_settings\n        PREFECT_API_URL.value_from(get_default_settings())\n        ```\n        \"\"\"\n        value = settings.value_of(self, bypass_callback=bypass_callback)\n\n        if not bypass_callback and self.deprecated and self.deprecated_when(value):\n            # Check if this setting is deprecated and someone is accessing the value\n            # via the old name\n            warnings.warn(self.deprecated_message, DeprecationWarning, stacklevel=3)\n\n            # If the the value is empty, return the new setting's value for compat\n            if value is None and self.deprecated_renamed_to is not None:\n                return self.deprecated_renamed_to.value_from(settings)\n\n        if not bypass_callback and self.deprecated_renamed_from is not None:\n            # Check if this setting is a rename of a deprecated setting and the\n            # deprecated setting is set and should be used for compatibility\n            deprecated_value = self.deprecated_renamed_from.value_from(\n                settings, bypass_callback=True\n            )\n            if deprecated_value is not None:\n                warnings.warn(\n                    (\n                        f\"{self.deprecated_renamed_from.deprecated_message} Because\"\n                        f\" {self.deprecated_renamed_from.name!r} is set it will be used\"\n                        f\" instead of {self.name!r} for backwards compatibility.\"\n                    ),\n                    DeprecationWarning,\n                    stacklevel=3,\n                )\n            return deprecated_value or value\n\n        return value\n\n    @property\n    def name(self):\n        if self._name:\n            return self._name\n\n        # Lookup the name on first access\n        for name, val in tuple(globals().items()):\n            if val == self:\n                self._name = name\n                return name\n\n        raise ValueError(\"Setting not found in `prefect.settings` module.\")\n\n    @name.setter\n    def name(self, value: str):\n        self._name = value\n\n    @property\n    def deprecated_message(self):\n        return generate_deprecation_message(\n            name=f\"Setting {self.name!r}\",\n            start_date=self.deprecated_start_date,\n            end_date=self.deprecated_end_date,\n            help=self.deprecated_help,\n            when=self.deprecated_when_message,\n        )\n\n    def __repr__(self) -&gt; str:\n        return f\"&lt;{self.name}: {self.type.__name__}&gt;\"\n\n    def __bool__(self) -&gt; bool:\n        \"\"\"\n        Returns a truthy check of the current value.\n        \"\"\"\n        return bool(self.value())\n\n    def __eq__(self, __o: object) -&gt; bool:\n        return __o.__eq__(self.value())\n\n    def __hash__(self) -&gt; int:\n        return hash((type(self), self.name))\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting.value","title":"<code>value</code>","text":"<p>Get the current value of a setting.</p> <p>Example: <pre><code>from prefect.settings import PREFECT_API_URL\nPREFECT_API_URL.value()\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>def value(self, bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Get the current value of a setting.\n\n    Example:\n    ```python\n    from prefect.settings import PREFECT_API_URL\n    PREFECT_API_URL.value()\n    ```\n    \"\"\"\n    return self.value_from(get_current_settings(), bypass_callback=bypass_callback)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Setting.value_from","title":"<code>value_from</code>","text":"<p>Get the value of a setting from a settings object</p> <p>Example: <pre><code>from prefect.settings import get_default_settings\nPREFECT_API_URL.value_from(get_default_settings())\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>def value_from(self, settings: \"Settings\", bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Get the value of a setting from a settings object\n\n    Example:\n    ```python\n    from prefect.settings import get_default_settings\n    PREFECT_API_URL.value_from(get_default_settings())\n    ```\n    \"\"\"\n    value = settings.value_of(self, bypass_callback=bypass_callback)\n\n    if not bypass_callback and self.deprecated and self.deprecated_when(value):\n        # Check if this setting is deprecated and someone is accessing the value\n        # via the old name\n        warnings.warn(self.deprecated_message, DeprecationWarning, stacklevel=3)\n\n        # If the the value is empty, return the new setting's value for compat\n        if value is None and self.deprecated_renamed_to is not None:\n            return self.deprecated_renamed_to.value_from(settings)\n\n    if not bypass_callback and self.deprecated_renamed_from is not None:\n        # Check if this setting is a rename of a deprecated setting and the\n        # deprecated setting is set and should be used for compatibility\n        deprecated_value = self.deprecated_renamed_from.value_from(\n            settings, bypass_callback=True\n        )\n        if deprecated_value is not None:\n            warnings.warn(\n                (\n                    f\"{self.deprecated_renamed_from.deprecated_message} Because\"\n                    f\" {self.deprecated_renamed_from.name!r} is set it will be used\"\n                    f\" instead of {self.name!r} for backwards compatibility.\"\n                ),\n                DeprecationWarning,\n                stacklevel=3,\n            )\n        return deprecated_value or value\n\n    return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings","title":"<code>Settings</code>","text":"<p>               Bases: <code>SettingsFieldsMixin</code></p> <p>Contains validated Prefect settings.</p> <p>Settings should be accessed using the relevant <code>Setting</code> object. For example: <pre><code>from prefect.settings import PREFECT_HOME\nPREFECT_HOME.value()\n</code></pre></p> <p>Accessing a setting attribute directly will ignore any <code>value_callback</code> mutations. This is not recommended: <pre><code>from prefect.settings import Settings\nSettings().PREFECT_PROFILES_PATH  # PosixPath('${PREFECT_HOME}/profiles.toml')\n</code></pre></p> Source code in <code>prefect/settings.py</code> <pre><code>@add_cloudpickle_reduction\nclass Settings(SettingsFieldsMixin):\n    \"\"\"\n    Contains validated Prefect settings.\n\n    Settings should be accessed using the relevant `Setting` object. For example:\n    ```python\n    from prefect.settings import PREFECT_HOME\n    PREFECT_HOME.value()\n    ```\n\n    Accessing a setting attribute directly will ignore any `value_callback` mutations.\n    This is not recommended:\n    ```python\n    from prefect.settings import Settings\n    Settings().PREFECT_PROFILES_PATH  # PosixPath('${PREFECT_HOME}/profiles.toml')\n    ```\n    \"\"\"\n\n    def value_of(self, setting: Setting[T], bypass_callback: bool = False) -&gt; T:\n        \"\"\"\n        Retrieve a setting's value.\n        \"\"\"\n        value = getattr(self, setting.name)\n        if setting.value_callback and not bypass_callback:\n            value = setting.value_callback(self, value)\n        return value\n\n    @validator(PREFECT_LOGGING_LEVEL.name, PREFECT_LOGGING_SERVER_LEVEL.name)\n    def check_valid_log_level(cls, value):\n        if isinstance(value, str):\n            value = value.upper()\n        logging._checkLevel(value)\n        return value\n\n    @root_validator\n    def post_root_validators(cls, values):\n        \"\"\"\n        Add root validation functions for settings here.\n        \"\"\"\n        # TODO: We could probably register these dynamically but this is the simpler\n        #       approach for now. We can explore more interesting validation features\n        #       in the future.\n        values = max_log_size_smaller_than_batch_size(values)\n        values = warn_on_database_password_value_without_usage(values)\n        if not values[\"PREFECT_SILENCE_API_URL_MISCONFIGURATION\"]:\n            values = warn_on_misconfigured_api_url(values)\n        return values\n\n    def copy_with_update(\n        self,\n        updates: Mapping[Setting, Any] = None,\n        set_defaults: Mapping[Setting, Any] = None,\n        restore_defaults: Iterable[Setting] = None,\n    ) -&gt; \"Settings\":\n        \"\"\"\n        Create a new `Settings` object with validation.\n\n        Arguments:\n            updates: A mapping of settings to new values. Existing values for the\n                given settings will be overridden.\n            set_defaults: A mapping of settings to new default values. Existing values for\n                the given settings will only be overridden if they were not set.\n            restore_defaults: An iterable of settings to restore to their default values.\n\n        Returns:\n            A new `Settings` object.\n        \"\"\"\n        updates = updates or {}\n        set_defaults = set_defaults or {}\n        restore_defaults = restore_defaults or set()\n        restore_defaults_names = {setting.name for setting in restore_defaults}\n\n        return self.__class__(\n            **{\n                **{setting.name: value for setting, value in set_defaults.items()},\n                **self.dict(exclude_unset=True, exclude=restore_defaults_names),\n                **{setting.name: value for setting, value in updates.items()},\n            }\n        )\n\n    def with_obfuscated_secrets(self):\n        \"\"\"\n        Returns a copy of this settings object with secret setting values obfuscated.\n        \"\"\"\n        settings = self.copy(\n            update={\n                setting.name: obfuscate(self.value_of(setting))\n                for setting in SETTING_VARIABLES.values()\n                if setting.is_secret\n                # Exclude deprecated settings with null values to avoid warnings\n                and not (setting.deprecated and self.value_of(setting) is None)\n            }\n        )\n        # Ensure that settings that have not been marked as \"set\" before are still so\n        # after we have updated their value above\n        settings.__fields_set__.intersection_update(self.__fields_set__)\n        return settings\n\n    def hash_key(self) -&gt; str:\n        \"\"\"\n        Return a hash key for the settings object.  This is needed since some\n        settings may be unhashable.  An example is lists.\n        \"\"\"\n        env_variables = self.to_environment_variables()\n        return str(hash(tuple((key, value) for key, value in env_variables.items())))\n\n    def to_environment_variables(\n        self, include: Iterable[Setting] = None, exclude_unset: bool = False\n    ) -&gt; Dict[str, str]:\n        \"\"\"\n        Convert the settings object to environment variables.\n\n        Note that setting values will not be run through their `value_callback` allowing\n        dynamic resolution to occur when loaded from the returned environment.\n\n        Args:\n            include_keys: An iterable of settings to include in the return value.\n                If not set, all settings are used.\n            exclude_unset: Only include settings that have been set (i.e. the value is\n                not from the default). If set, unset keys will be dropped even if they\n                are set in `include_keys`.\n\n        Returns:\n            A dictionary of settings with values cast to strings\n        \"\"\"\n        include = set(include or SETTING_VARIABLES.values())\n\n        if exclude_unset:\n            set_keys = {\n                # Collect all of the \"set\" keys and cast to `Setting` objects\n                SETTING_VARIABLES[key]\n                for key in self.dict(exclude_unset=True)\n            }\n            include.intersection_update(set_keys)\n\n        # Validate the types of items in `include` to prevent exclusion bugs\n        for key in include:\n            if not isinstance(key, Setting):\n                raise TypeError(\n                    \"Invalid type {type(key).__name__!r} for key in `include`.\"\n                )\n\n        env = {\n            # Use `getattr` instead of `value_of` to avoid value callback resolution\n            key: getattr(self, key)\n            for key, setting in SETTING_VARIABLES.items()\n            if setting in include\n        }\n\n        # Cast to strings and drop null values\n        return {key: str(value) for key, value in env.items() if value is not None}\n\n    class Config:\n        frozen = True\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.value_of","title":"<code>value_of</code>","text":"<p>Retrieve a setting's value.</p> Source code in <code>prefect/settings.py</code> <pre><code>def value_of(self, setting: Setting[T], bypass_callback: bool = False) -&gt; T:\n    \"\"\"\n    Retrieve a setting's value.\n    \"\"\"\n    value = getattr(self, setting.name)\n    if setting.value_callback and not bypass_callback:\n        value = setting.value_callback(self, value)\n    return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.post_root_validators","title":"<code>post_root_validators</code>","text":"<p>Add root validation functions for settings here.</p> Source code in <code>prefect/settings.py</code> <pre><code>@root_validator\ndef post_root_validators(cls, values):\n    \"\"\"\n    Add root validation functions for settings here.\n    \"\"\"\n    # TODO: We could probably register these dynamically but this is the simpler\n    #       approach for now. We can explore more interesting validation features\n    #       in the future.\n    values = max_log_size_smaller_than_batch_size(values)\n    values = warn_on_database_password_value_without_usage(values)\n    if not values[\"PREFECT_SILENCE_API_URL_MISCONFIGURATION\"]:\n        values = warn_on_misconfigured_api_url(values)\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.with_obfuscated_secrets","title":"<code>with_obfuscated_secrets</code>","text":"<p>Returns a copy of this settings object with secret setting values obfuscated.</p> Source code in <code>prefect/settings.py</code> <pre><code>def with_obfuscated_secrets(self):\n    \"\"\"\n    Returns a copy of this settings object with secret setting values obfuscated.\n    \"\"\"\n    settings = self.copy(\n        update={\n            setting.name: obfuscate(self.value_of(setting))\n            for setting in SETTING_VARIABLES.values()\n            if setting.is_secret\n            # Exclude deprecated settings with null values to avoid warnings\n            and not (setting.deprecated and self.value_of(setting) is None)\n        }\n    )\n    # Ensure that settings that have not been marked as \"set\" before are still so\n    # after we have updated their value above\n    settings.__fields_set__.intersection_update(self.__fields_set__)\n    return settings\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.hash_key","title":"<code>hash_key</code>","text":"<p>Return a hash key for the settings object.  This is needed since some settings may be unhashable.  An example is lists.</p> Source code in <code>prefect/settings.py</code> <pre><code>def hash_key(self) -&gt; str:\n    \"\"\"\n    Return a hash key for the settings object.  This is needed since some\n    settings may be unhashable.  An example is lists.\n    \"\"\"\n    env_variables = self.to_environment_variables()\n    return str(hash(tuple((key, value) for key, value in env_variables.items())))\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Settings.to_environment_variables","title":"<code>to_environment_variables</code>","text":"<p>Convert the settings object to environment variables.</p> <p>Note that setting values will not be run through their <code>value_callback</code> allowing dynamic resolution to occur when loaded from the returned environment.</p> <p>Parameters:</p> Name Type Description Default <code>include_keys</code> <p>An iterable of settings to include in the return value. If not set, all settings are used.</p> required <code>exclude_unset</code> <code>bool</code> <p>Only include settings that have been set (i.e. the value is not from the default). If set, unset keys will be dropped even if they are set in <code>include_keys</code>.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dictionary of settings with values cast to strings</p> Source code in <code>prefect/settings.py</code> <pre><code>def to_environment_variables(\n    self, include: Iterable[Setting] = None, exclude_unset: bool = False\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Convert the settings object to environment variables.\n\n    Note that setting values will not be run through their `value_callback` allowing\n    dynamic resolution to occur when loaded from the returned environment.\n\n    Args:\n        include_keys: An iterable of settings to include in the return value.\n            If not set, all settings are used.\n        exclude_unset: Only include settings that have been set (i.e. the value is\n            not from the default). If set, unset keys will be dropped even if they\n            are set in `include_keys`.\n\n    Returns:\n        A dictionary of settings with values cast to strings\n    \"\"\"\n    include = set(include or SETTING_VARIABLES.values())\n\n    if exclude_unset:\n        set_keys = {\n            # Collect all of the \"set\" keys and cast to `Setting` objects\n            SETTING_VARIABLES[key]\n            for key in self.dict(exclude_unset=True)\n        }\n        include.intersection_update(set_keys)\n\n    # Validate the types of items in `include` to prevent exclusion bugs\n    for key in include:\n        if not isinstance(key, Setting):\n            raise TypeError(\n                \"Invalid type {type(key).__name__!r} for key in `include`.\"\n            )\n\n    env = {\n        # Use `getattr` instead of `value_of` to avoid value callback resolution\n        key: getattr(self, key)\n        for key, setting in SETTING_VARIABLES.items()\n        if setting in include\n    }\n\n    # Cast to strings and drop null values\n    return {key: str(value) for key, value in env.items() if value is not None}\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile","title":"<code>Profile</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A user profile containing settings.</p> Source code in <code>prefect/settings.py</code> <pre><code>class Profile(BaseModel):\n    \"\"\"\n    A user profile containing settings.\n    \"\"\"\n\n    name: str\n    settings: Dict[Setting, Any] = Field(default_factory=dict)\n    source: Optional[Path]\n\n    @validator(\"settings\", pre=True)\n    def map_names_to_settings(cls, value):\n        return validate_settings(value)\n\n    def validate_settings(self) -&gt; None:\n        \"\"\"\n        Validate the settings contained in this profile.\n\n        Raises:\n            pydantic.ValidationError: When settings do not have valid values.\n        \"\"\"\n        # Create a new `Settings` instance with the settings from this profile relying\n        # on Pydantic validation to raise an error.\n        # We do not return the `Settings` object because this is not the recommended\n        # path for constructing settings with a profile. See `use_profile` instead.\n        Settings(**{setting.name: value for setting, value in self.settings.items()})\n\n    def convert_deprecated_renamed_settings(self) -&gt; List[Tuple[Setting, Setting]]:\n        \"\"\"\n        Update settings in place to replace deprecated settings with new settings when\n        renamed.\n\n        Returns a list of tuples with the old and new setting.\n        \"\"\"\n        changed = []\n        for setting in tuple(self.settings):\n            if (\n                setting.deprecated\n                and setting.deprecated_renamed_to\n                and setting.deprecated_renamed_to not in self.settings\n            ):\n                self.settings[setting.deprecated_renamed_to] = self.settings.pop(\n                    setting\n                )\n                changed.append((setting, setting.deprecated_renamed_to))\n        return changed\n\n    class Config:\n        arbitrary_types_allowed = True\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile.validate_settings","title":"<code>validate_settings</code>","text":"<p>Validate the settings contained in this profile.</p> <p>Raises:</p> Type Description <code>ValidationError</code> <p>When settings do not have valid values.</p> Source code in <code>prefect/settings.py</code> <pre><code>def validate_settings(self) -&gt; None:\n    \"\"\"\n    Validate the settings contained in this profile.\n\n    Raises:\n        pydantic.ValidationError: When settings do not have valid values.\n    \"\"\"\n    # Create a new `Settings` instance with the settings from this profile relying\n    # on Pydantic validation to raise an error.\n    # We do not return the `Settings` object because this is not the recommended\n    # path for constructing settings with a profile. See `use_profile` instead.\n    Settings(**{setting.name: value for setting, value in self.settings.items()})\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.Profile.convert_deprecated_renamed_settings","title":"<code>convert_deprecated_renamed_settings</code>","text":"<p>Update settings in place to replace deprecated settings with new settings when renamed.</p> <p>Returns a list of tuples with the old and new setting.</p> Source code in <code>prefect/settings.py</code> <pre><code>def convert_deprecated_renamed_settings(self) -&gt; List[Tuple[Setting, Setting]]:\n    \"\"\"\n    Update settings in place to replace deprecated settings with new settings when\n    renamed.\n\n    Returns a list of tuples with the old and new setting.\n    \"\"\"\n    changed = []\n    for setting in tuple(self.settings):\n        if (\n            setting.deprecated\n            and setting.deprecated_renamed_to\n            and setting.deprecated_renamed_to not in self.settings\n        ):\n            self.settings[setting.deprecated_renamed_to] = self.settings.pop(\n                setting\n            )\n            changed.append((setting, setting.deprecated_renamed_to))\n    return changed\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection","title":"<code>ProfilesCollection</code>","text":"<p>\" A utility class for working with a collection of profiles.</p> <p>Profiles in the collection must have unique names.</p> <p>The collection may store the name of the active profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>class ProfilesCollection:\n    \"\"\" \"\n    A utility class for working with a collection of profiles.\n\n    Profiles in the collection must have unique names.\n\n    The collection may store the name of the active profile.\n    \"\"\"\n\n    def __init__(\n        self, profiles: Iterable[Profile], active: Optional[str] = None\n    ) -&gt; None:\n        self.profiles_by_name = {profile.name: profile for profile in profiles}\n        self.active_name = active\n\n    @property\n    def names(self) -&gt; Set[str]:\n        \"\"\"\n        Return a set of profile names in this collection.\n        \"\"\"\n        return set(self.profiles_by_name.keys())\n\n    @property\n    def active_profile(self) -&gt; Optional[Profile]:\n        \"\"\"\n        Retrieve the active profile in this collection.\n        \"\"\"\n        if self.active_name is None:\n            return None\n        return self[self.active_name]\n\n    def set_active(self, name: Optional[str], check: bool = True):\n        \"\"\"\n        Set the active profile name in the collection.\n\n        A null value may be passed to indicate that this collection does not determine\n        the active profile.\n        \"\"\"\n        if check and name is not None and name not in self.names:\n            raise ValueError(f\"Unknown profile name {name!r}.\")\n        self.active_name = name\n\n    def update_profile(\n        self, name: str, settings: Mapping[Union[Dict, str], Any], source: Path = None\n    ) -&gt; Profile:\n        \"\"\"\n        Add a profile to the collection or update the existing on if the name is already\n        present in this collection.\n\n        If updating an existing profile, the settings will be merged. Settings can\n        be dropped from the existing profile by setting them to `None` in the new\n        profile.\n\n        Returns the new profile object.\n        \"\"\"\n        existing = self.profiles_by_name.get(name)\n\n        # Convert the input to a `Profile` to cast settings to the correct type\n        profile = Profile(name=name, settings=settings, source=source)\n\n        if existing:\n            new_settings = {**existing.settings, **profile.settings}\n\n            # Drop null keys to restore to default\n            for key, value in tuple(new_settings.items()):\n                if value is None:\n                    new_settings.pop(key)\n\n            new_profile = Profile(\n                name=profile.name,\n                settings=new_settings,\n                source=source or profile.source,\n            )\n        else:\n            new_profile = profile\n\n        self.profiles_by_name[new_profile.name] = new_profile\n\n        return new_profile\n\n    def add_profile(self, profile: Profile) -&gt; None:\n        \"\"\"\n        Add a profile to the collection.\n\n        If the profile name already exists, an exception will be raised.\n        \"\"\"\n        if profile.name in self.profiles_by_name:\n            raise ValueError(\n                f\"Profile name {profile.name!r} already exists in collection.\"\n            )\n\n        self.profiles_by_name[profile.name] = profile\n\n    def remove_profile(self, name: str) -&gt; None:\n        \"\"\"\n        Remove a profile from the collection.\n        \"\"\"\n        self.profiles_by_name.pop(name)\n\n    def without_profile_source(self, path: Optional[Path]) -&gt; \"ProfilesCollection\":\n        \"\"\"\n        Remove profiles that were loaded from a given path.\n\n        Returns a new collection.\n        \"\"\"\n        return ProfilesCollection(\n            [\n                profile\n                for profile in self.profiles_by_name.values()\n                if profile.source != path\n            ],\n            active=self.active_name,\n        )\n\n    def to_dict(self):\n        \"\"\"\n        Convert to a dictionary suitable for writing to disk.\n        \"\"\"\n        return {\n            \"active\": self.active_name,\n            \"profiles\": {\n                profile.name: {\n                    setting.name: value for setting, value in profile.settings.items()\n                }\n                for profile in self.profiles_by_name.values()\n            },\n        }\n\n    def __getitem__(self, name: str) -&gt; Profile:\n        return self.profiles_by_name[name]\n\n    def __iter__(self):\n        return self.profiles_by_name.__iter__()\n\n    def items(self):\n        return self.profiles_by_name.items()\n\n    def __eq__(self, __o: object) -&gt; bool:\n        if not isinstance(__o, ProfilesCollection):\n            return False\n\n        return (\n            self.profiles_by_name == __o.profiles_by_name\n            and self.active_name == __o.active_name\n        )\n\n    def __repr__(self) -&gt; str:\n        return (\n            f\"ProfilesCollection(profiles={list(self.profiles_by_name.values())!r},\"\n            f\" active={self.active_name!r})&gt;\"\n        )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.names","title":"<code>names: Set[str]</code>  <code>property</code>","text":"<p>Return a set of profile names in this collection.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.active_profile","title":"<code>active_profile: Optional[Profile]</code>  <code>property</code>","text":"<p>Retrieve the active profile in this collection.</p>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.set_active","title":"<code>set_active</code>","text":"<p>Set the active profile name in the collection.</p> <p>A null value may be passed to indicate that this collection does not determine the active profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>def set_active(self, name: Optional[str], check: bool = True):\n    \"\"\"\n    Set the active profile name in the collection.\n\n    A null value may be passed to indicate that this collection does not determine\n    the active profile.\n    \"\"\"\n    if check and name is not None and name not in self.names:\n        raise ValueError(f\"Unknown profile name {name!r}.\")\n    self.active_name = name\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.update_profile","title":"<code>update_profile</code>","text":"<p>Add a profile to the collection or update the existing on if the name is already present in this collection.</p> <p>If updating an existing profile, the settings will be merged. Settings can be dropped from the existing profile by setting them to <code>None</code> in the new profile.</p> <p>Returns the new profile object.</p> Source code in <code>prefect/settings.py</code> <pre><code>def update_profile(\n    self, name: str, settings: Mapping[Union[Dict, str], Any], source: Path = None\n) -&gt; Profile:\n    \"\"\"\n    Add a profile to the collection or update the existing on if the name is already\n    present in this collection.\n\n    If updating an existing profile, the settings will be merged. Settings can\n    be dropped from the existing profile by setting them to `None` in the new\n    profile.\n\n    Returns the new profile object.\n    \"\"\"\n    existing = self.profiles_by_name.get(name)\n\n    # Convert the input to a `Profile` to cast settings to the correct type\n    profile = Profile(name=name, settings=settings, source=source)\n\n    if existing:\n        new_settings = {**existing.settings, **profile.settings}\n\n        # Drop null keys to restore to default\n        for key, value in tuple(new_settings.items()):\n            if value is None:\n                new_settings.pop(key)\n\n        new_profile = Profile(\n            name=profile.name,\n            settings=new_settings,\n            source=source or profile.source,\n        )\n    else:\n        new_profile = profile\n\n    self.profiles_by_name[new_profile.name] = new_profile\n\n    return new_profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.add_profile","title":"<code>add_profile</code>","text":"<p>Add a profile to the collection.</p> <p>If the profile name already exists, an exception will be raised.</p> Source code in <code>prefect/settings.py</code> <pre><code>def add_profile(self, profile: Profile) -&gt; None:\n    \"\"\"\n    Add a profile to the collection.\n\n    If the profile name already exists, an exception will be raised.\n    \"\"\"\n    if profile.name in self.profiles_by_name:\n        raise ValueError(\n            f\"Profile name {profile.name!r} already exists in collection.\"\n        )\n\n    self.profiles_by_name[profile.name] = profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.remove_profile","title":"<code>remove_profile</code>","text":"<p>Remove a profile from the collection.</p> Source code in <code>prefect/settings.py</code> <pre><code>def remove_profile(self, name: str) -&gt; None:\n    \"\"\"\n    Remove a profile from the collection.\n    \"\"\"\n    self.profiles_by_name.pop(name)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.ProfilesCollection.without_profile_source","title":"<code>without_profile_source</code>","text":"<p>Remove profiles that were loaded from a given path.</p> <p>Returns a new collection.</p> Source code in <code>prefect/settings.py</code> <pre><code>def without_profile_source(self, path: Optional[Path]) -&gt; \"ProfilesCollection\":\n    \"\"\"\n    Remove profiles that were loaded from a given path.\n\n    Returns a new collection.\n    \"\"\"\n    return ProfilesCollection(\n        [\n            profile\n            for profile in self.profiles_by_name.values()\n            if profile.source != path\n        ],\n        active=self.active_name,\n    )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_extra_loggers","title":"<code>get_extra_loggers</code>","text":"<p><code>value_callback</code> for <code>PREFECT_LOGGING_EXTRA_LOGGERS</code>that parses the CSV string into a list and trims whitespace from logger names.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_extra_loggers(_: \"Settings\", value: str) -&gt; List[str]:\n    \"\"\"\n    `value_callback` for `PREFECT_LOGGING_EXTRA_LOGGERS`that parses the CSV string into a\n    list and trims whitespace from logger names.\n    \"\"\"\n    return [name.strip() for name in value.split(\",\")] if value else []\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.debug_mode_log_level","title":"<code>debug_mode_log_level</code>","text":"<p><code>value_callback</code> for <code>PREFECT_LOGGING_LEVEL</code> that overrides the log level to DEBUG when debug mode is enabled.</p> Source code in <code>prefect/settings.py</code> <pre><code>def debug_mode_log_level(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_LOGGING_LEVEL` that overrides the log level to DEBUG\n    when debug mode is enabled.\n    \"\"\"\n    if PREFECT_DEBUG_MODE.value_from(settings):\n        return \"DEBUG\"\n    else:\n        return value\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.only_return_value_in_test_mode","title":"<code>only_return_value_in_test_mode</code>","text":"<p><code>value_callback</code> for <code>PREFECT_TEST_SETTING</code> that only allows access during test mode</p> Source code in <code>prefect/settings.py</code> <pre><code>def only_return_value_in_test_mode(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_TEST_SETTING` that only allows access during test mode\n    \"\"\"\n    if PREFECT_TEST_MODE.value_from(settings):\n        return value\n    else:\n        return None\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.default_ui_api_url","title":"<code>default_ui_api_url</code>","text":"<p><code>value_callback</code> for <code>PREFECT_UI_API_URL</code> that sets the default value to relative path '/api', otherwise it constructs an API URL from the API settings.</p> Source code in <code>prefect/settings.py</code> <pre><code>def default_ui_api_url(settings, value):\n    \"\"\"\n    `value_callback` for `PREFECT_UI_API_URL` that sets the default value to\n    relative path '/api', otherwise it constructs an API URL from the API settings.\n    \"\"\"\n    if value is None:\n        # Set a default value\n        value = \"/api\"\n\n    return template_with_settings(\n        PREFECT_SERVER_API_HOST, PREFECT_SERVER_API_PORT, PREFECT_API_URL\n    )(settings, value)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.status_codes_as_integers_in_range","title":"<code>status_codes_as_integers_in_range</code>","text":"<p><code>value_callback</code> for <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code> that ensures status codes are integers in the range 100-599.</p> Source code in <code>prefect/settings.py</code> <pre><code>def status_codes_as_integers_in_range(_, value):\n    \"\"\"\n    `value_callback` for `PREFECT_CLIENT_RETRY_EXTRA_CODES` that ensures status codes\n    are integers in the range 100-599.\n    \"\"\"\n    if value == \"\":\n        return set()\n\n    values = {v.strip() for v in value.split(\",\")}\n\n    if any(not v.isdigit() or int(v) &lt; 100 or int(v) &gt; 599 for v in values):\n        raise ValueError(\n            \"PREFECT_CLIENT_RETRY_EXTRA_CODES must be a comma separated list of \"\n            \"integers between 100 and 599.\"\n        )\n\n    values = {int(v) for v in values}\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.template_with_settings","title":"<code>template_with_settings</code>","text":"<p>Returns a <code>value_callback</code> that will template the given settings into the runtime value for the setting.</p> Source code in <code>prefect/settings.py</code> <pre><code>def template_with_settings(*upstream_settings: Setting) -&gt; Callable[[\"Settings\", T], T]:\n    \"\"\"\n    Returns a `value_callback` that will template the given settings into the runtime\n    value for the setting.\n    \"\"\"\n\n    def templater(settings, value):\n        if value is None:\n            return value  # Do not attempt to template a null string\n\n        original_type = type(value)\n        template_values = {\n            setting.name: setting.value_from(settings) for setting in upstream_settings\n        }\n        template = string.Template(str(value))\n        # Note the use of `safe_substitute` to avoid raising an exception if a\n        # template value is missing. In this case, template values will be left\n        # as-is in the string. Using `safe_substitute` prevents us raising when\n        # the DB password contains a `$` character.\n        return original_type(template.safe_substitute(template_values))\n\n    return templater\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.max_log_size_smaller_than_batch_size","title":"<code>max_log_size_smaller_than_batch_size</code>","text":"<p>Validator for settings asserting the batch size and match log size are compatible</p> Source code in <code>prefect/settings.py</code> <pre><code>def max_log_size_smaller_than_batch_size(values):\n    \"\"\"\n    Validator for settings asserting the batch size and match log size are compatible\n    \"\"\"\n    if (\n        values[\"PREFECT_LOGGING_TO_API_BATCH_SIZE\"]\n        &lt; values[\"PREFECT_LOGGING_TO_API_MAX_LOG_SIZE\"]\n    ):\n        raise ValueError(\n            \"`PREFECT_LOGGING_TO_API_MAX_LOG_SIZE` cannot be larger than\"\n            \" `PREFECT_LOGGING_TO_API_BATCH_SIZE`\"\n        )\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.warn_on_database_password_value_without_usage","title":"<code>warn_on_database_password_value_without_usage</code>","text":"<p>Validator for settings warning if the database password is set but not used.</p> Source code in <code>prefect/settings.py</code> <pre><code>def warn_on_database_password_value_without_usage(values):\n    \"\"\"\n    Validator for settings warning if the database password is set but not used.\n    \"\"\"\n    value = values[\"PREFECT_API_DATABASE_PASSWORD\"]\n    if (\n        value\n        and not value.startswith(OBFUSCATED_PREFIX)\n        and (\n            \"PREFECT_API_DATABASE_PASSWORD\"\n            not in values[\"PREFECT_API_DATABASE_CONNECTION_URL\"]\n        )\n    ):\n        warnings.warn(\n            \"PREFECT_API_DATABASE_PASSWORD is set but not included in the \"\n            \"PREFECT_API_DATABASE_CONNECTION_URL. \"\n            \"The provided password will be ignored.\"\n        )\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.warn_on_misconfigured_api_url","title":"<code>warn_on_misconfigured_api_url</code>","text":"<p>Validator for settings warning if the API URL is misconfigured.</p> Source code in <code>prefect/settings.py</code> <pre><code>def warn_on_misconfigured_api_url(values):\n    \"\"\"\n    Validator for settings warning if the API URL is misconfigured.\n    \"\"\"\n    api_url = values[\"PREFECT_API_URL\"]\n    if api_url is not None:\n        misconfigured_mappings = {\n            \"app.prefect.cloud\": (\n                \"`PREFECT_API_URL` points to `app.prefect.cloud`. Did you\"\n                \" mean `api.prefect.cloud`?\"\n            ),\n            \"account/\": (\n                \"`PREFECT_API_URL` uses `/account/` but should use `/accounts/`.\"\n            ),\n            \"workspace/\": (\n                \"`PREFECT_API_URL` uses `/workspace/` but should use `/workspaces/`.\"\n            ),\n        }\n        warnings_list = []\n\n        for misconfig, warning in misconfigured_mappings.items():\n            if misconfig in api_url:\n                warnings_list.append(warning)\n\n        parsed_url = urlparse(api_url)\n        if parsed_url.path and not parsed_url.path.startswith(\"/api\"):\n            warnings_list.append(\n                \"`PREFECT_API_URL` should have `/api` after the base URL.\"\n            )\n\n        if warnings_list:\n            example = 'e.g. PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"'\n            warnings_list.append(example)\n\n            warnings.warn(\"\\n\".join(warnings_list), stacklevel=2)\n\n    return values\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.automation_settings_enabled","title":"<code>automation_settings_enabled</code>","text":"<p>Whether or not automations are enabled.</p> Source code in <code>prefect/settings.py</code> <pre><code>def automation_settings_enabled() -&gt; bool:\n    \"\"\"\n    Whether or not automations are enabled.\n    \"\"\"\n    return (\n        PREFECT_EXPERIMENTAL_EVENTS.value()\n        and PREFECT_API_SERVICES_TRIGGERS_ENABLED.value()\n    )\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_current_settings","title":"<code>get_current_settings</code>","text":"<p>Returns a settings object populated with values from the current settings context or, if no settings context is active, the environment.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_current_settings() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with values from the current settings context\n    or, if no settings context is active, the environment.\n    \"\"\"\n    from prefect.context import SettingsContext\n\n    settings_context = SettingsContext.get()\n    if settings_context is not None:\n        return settings_context.settings\n\n    return get_settings_from_env()\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_settings_from_env","title":"<code>get_settings_from_env</code>","text":"<p>Returns a settings object populated with default values and overrides from environment variables, ignoring any values in profiles.</p> <p>Calls with the same environment return a cached object instead of reconstructing to avoid validation overhead.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_settings_from_env() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with default values and overrides from\n    environment variables, ignoring any values in profiles.\n\n    Calls with the same environment return a cached object instead of reconstructing\n    to avoid validation overhead.\n    \"\"\"\n    # Since os.environ is a Dict[str, str] we can safely hash it by contents, but we\n    # must be careful to avoid hashing a generator instead of a tuple\n    cache_key = hash(tuple((key, value) for key, value in os.environ.items()))\n\n    if cache_key not in _FROM_ENV_CACHE:\n        _FROM_ENV_CACHE[cache_key] = Settings()\n\n    return _FROM_ENV_CACHE[cache_key]\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.get_default_settings","title":"<code>get_default_settings</code>","text":"<p>Returns a settings object populated with default values, ignoring any overrides from environment variables or profiles.</p> <p>This is cached since the defaults should not change during the lifetime of the module.</p> Source code in <code>prefect/settings.py</code> <pre><code>def get_default_settings() -&gt; Settings:\n    \"\"\"\n    Returns a settings object populated with default values, ignoring any overrides\n    from environment variables or profiles.\n\n    This is cached since the defaults should not change during the lifetime of the\n    module.\n    \"\"\"\n    global _DEFAULTS_CACHE\n\n    if not _DEFAULTS_CACHE:\n        old = os.environ\n        try:\n            os.environ = {}\n            settings = get_settings_from_env()\n        finally:\n            os.environ = old\n\n        _DEFAULTS_CACHE = settings\n\n    return _DEFAULTS_CACHE\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.temporary_settings","title":"<code>temporary_settings</code>","text":"<p>Temporarily override the current settings by entering a new profile.</p> <p>See <code>Settings.copy_with_update</code> for details on different argument behavior.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect.settings import PREFECT_API_URL\n&gt;&gt;&gt;\n&gt;&gt;&gt; with temporary_settings(updates={PREFECT_API_URL: \"foo\"}):\n&gt;&gt;&gt;    assert PREFECT_API_URL.value() == \"foo\"\n&gt;&gt;&gt;\n&gt;&gt;&gt;    with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"}):\n&gt;&gt;&gt;         assert PREFECT_API_URL.value() == \"foo\"\n&gt;&gt;&gt;\n&gt;&gt;&gt;    with temporary_settings(restore_defaults={PREFECT_API_URL}):\n&gt;&gt;&gt;         assert PREFECT_API_URL.value() is None\n&gt;&gt;&gt;\n&gt;&gt;&gt;         with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"})\n&gt;&gt;&gt;             assert PREFECT_API_URL.value() == \"bar\"\n&gt;&gt;&gt; assert PREFECT_API_URL.value() is None\n</code></pre> Source code in <code>prefect/settings.py</code> <pre><code>@contextmanager\ndef temporary_settings(\n    updates: Optional[Mapping[Setting[T], Any]] = None,\n    set_defaults: Optional[Mapping[Setting[T], Any]] = None,\n    restore_defaults: Optional[Iterable[Setting[T]]] = None,\n) -&gt; Generator[Settings, None, None]:\n    \"\"\"\n    Temporarily override the current settings by entering a new profile.\n\n    See `Settings.copy_with_update` for details on different argument behavior.\n\n    Examples:\n        &gt;&gt;&gt; from prefect.settings import PREFECT_API_URL\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; with temporary_settings(updates={PREFECT_API_URL: \"foo\"}):\n        &gt;&gt;&gt;    assert PREFECT_API_URL.value() == \"foo\"\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;    with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"}):\n        &gt;&gt;&gt;         assert PREFECT_API_URL.value() == \"foo\"\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;    with temporary_settings(restore_defaults={PREFECT_API_URL}):\n        &gt;&gt;&gt;         assert PREFECT_API_URL.value() is None\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;         with temporary_settings(set_defaults={PREFECT_API_URL: \"bar\"})\n        &gt;&gt;&gt;             assert PREFECT_API_URL.value() == \"bar\"\n        &gt;&gt;&gt; assert PREFECT_API_URL.value() is None\n    \"\"\"\n    import prefect.context\n\n    context = prefect.context.get_settings_context()\n\n    new_settings = context.settings.copy_with_update(\n        updates=updates, set_defaults=set_defaults, restore_defaults=restore_defaults\n    )\n\n    with prefect.context.SettingsContext(\n        profile=context.profile, settings=new_settings\n    ):\n        yield new_settings\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_profiles","title":"<code>load_profiles</code>","text":"<p>Load all profiles from the default and current profile paths.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_profiles() -&gt; ProfilesCollection:\n    \"\"\"\n    Load all profiles from the default and current profile paths.\n    \"\"\"\n    profiles = _read_profiles_from(DEFAULT_PROFILES_PATH)\n\n    user_profiles_path = PREFECT_PROFILES_PATH.value()\n    if user_profiles_path.exists():\n        user_profiles = _read_profiles_from(user_profiles_path)\n\n        # Merge all of the user profiles with the defaults\n        for name in user_profiles:\n            profiles.update_profile(\n                name,\n                settings=user_profiles[name].settings,\n                source=user_profiles[name].source,\n            )\n\n        if user_profiles.active_name:\n            profiles.set_active(user_profiles.active_name, check=False)\n\n    return profiles\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_current_profile","title":"<code>load_current_profile</code>","text":"<p>Load the current profile from the default and current profile paths.</p> <p>This will not include settings from the current settings context. Only settings that have been persisted to the profiles file will be saved.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_current_profile():\n    \"\"\"\n    Load the current profile from the default and current profile paths.\n\n    This will _not_ include settings from the current settings context. Only settings\n    that have been persisted to the profiles file will be saved.\n    \"\"\"\n    from prefect.context import SettingsContext\n\n    profiles = load_profiles()\n    context = SettingsContext.get()\n\n    if context:\n        profiles.set_active(context.profile.name)\n\n    return profiles.active_profile\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.save_profiles","title":"<code>save_profiles</code>","text":"<p>Writes all non-default profiles to the current profiles path.</p> Source code in <code>prefect/settings.py</code> <pre><code>def save_profiles(profiles: ProfilesCollection) -&gt; None:\n    \"\"\"\n    Writes all non-default profiles to the current profiles path.\n    \"\"\"\n    profiles_path = PREFECT_PROFILES_PATH.value()\n    profiles = profiles.without_profile_source(DEFAULT_PROFILES_PATH)\n    return _write_profiles_to(profiles_path, profiles)\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.load_profile","title":"<code>load_profile</code>","text":"<p>Load a single profile by name.</p> Source code in <code>prefect/settings.py</code> <pre><code>def load_profile(name: str) -&gt; Profile:\n    \"\"\"\n    Load a single profile by name.\n    \"\"\"\n    profiles = load_profiles()\n    try:\n        return profiles[name]\n    except KeyError:\n        raise ValueError(f\"Profile {name!r} not found.\")\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/settings/#prefect.settings.update_current_profile","title":"<code>update_current_profile</code>","text":"<p>Update the persisted data for the profile currently in-use.</p> <p>If the profile does not exist in the profiles file, it will be created.</p> <p>Given settings will be merged with the existing settings as described in <code>ProfilesCollection.update_profile</code>.</p> <p>Returns:</p> Type Description <code>Profile</code> <p>The new profile.</p> Source code in <code>prefect/settings.py</code> <pre><code>def update_current_profile(settings: Dict[Union[str, Setting], Any]) -&gt; Profile:\n    \"\"\"\n    Update the persisted data for the profile currently in-use.\n\n    If the profile does not exist in the profiles file, it will be created.\n\n    Given settings will be merged with the existing settings as described in\n    `ProfilesCollection.update_profile`.\n\n    Returns:\n        The new profile.\n    \"\"\"\n    import prefect.context\n\n    current_profile = prefect.context.get_settings_context().profile\n\n    if not current_profile:\n        raise MissingProfileError(\"No profile is currently in use.\")\n\n    profiles = load_profiles()\n\n    # Ensure the current profile's settings are present\n    profiles.update_profile(current_profile.name, current_profile.settings)\n    # Then merge the new settings in\n    new_profile = profiles.update_profile(current_profile.name, settings)\n\n    # Validate before saving\n    new_profile.validate_settings()\n\n    save_profiles(profiles)\n\n    return profiles[current_profile.name]\n</code></pre>","tags":["Python API","settings","configuration","environment variables"]},{"location":"api-ref/prefect/software/","title":"prefect.software","text":"","tags":["Python API","software"]},{"location":"api-ref/prefect/software/#prefect.software","title":"<code>prefect.software</code>","text":"","tags":["Python API","software"]},{"location":"api-ref/prefect/states/","title":"prefect.states","text":"","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states","title":"<code>prefect.states</code>","text":"","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.AwaitingRetry","title":"<code>AwaitingRetry</code>","text":"<p>Convenience function for creating <code>AwaitingRetry</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a AwaitingRetry state</p> Source code in <code>prefect/states.py</code> <pre><code>def AwaitingRetry(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `AwaitingRetry` states.\n\n    Returns:\n        State: a AwaitingRetry state\n    \"\"\"\n    return Scheduled(\n        cls=cls, scheduled_time=scheduled_time, name=\"AwaitingRetry\", **kwargs\n    )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Cancelled","title":"<code>Cancelled</code>","text":"<p>Convenience function for creating <code>Cancelled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Cancelled state</p> Source code in <code>prefect/states.py</code> <pre><code>def Cancelled(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Cancelled` states.\n\n    Returns:\n        State: a Cancelled state\n    \"\"\"\n    return cls(type=StateType.CANCELLED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Cancelling","title":"<code>Cancelling</code>","text":"<p>Convenience function for creating <code>Cancelling</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Cancelling state</p> Source code in <code>prefect/states.py</code> <pre><code>def Cancelling(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Cancelling` states.\n\n    Returns:\n        State: a Cancelling state\n    \"\"\"\n    return cls(type=StateType.CANCELLING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Completed","title":"<code>Completed</code>","text":"<p>Convenience function for creating <code>Completed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Completed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Completed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Completed` states.\n\n    Returns:\n        State: a Completed state\n    \"\"\"\n    return cls(type=StateType.COMPLETED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Crashed","title":"<code>Crashed</code>","text":"<p>Convenience function for creating <code>Crashed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Crashed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Crashed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Crashed` states.\n\n    Returns:\n        State: a Crashed state\n    \"\"\"\n    return cls(type=StateType.CRASHED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Failed","title":"<code>Failed</code>","text":"<p>Convenience function for creating <code>Failed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Failed state</p> Source code in <code>prefect/states.py</code> <pre><code>def Failed(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Failed` states.\n\n    Returns:\n        State: a Failed state\n    \"\"\"\n    return cls(type=StateType.FAILED, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Late","title":"<code>Late</code>","text":"<p>Convenience function for creating <code>Late</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Late state</p> Source code in <code>prefect/states.py</code> <pre><code>def Late(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Late` states.\n\n    Returns:\n        State: a Late state\n    \"\"\"\n    return Scheduled(cls=cls, scheduled_time=scheduled_time, name=\"Late\", **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Paused","title":"<code>Paused</code>","text":"<p>Convenience function for creating <code>Paused</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Paused state</p> Source code in <code>prefect/states.py</code> <pre><code>def Paused(\n    cls: Type[State[R]] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    reschedule: bool = False,\n    pause_key: Optional[str] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Paused` states.\n\n    Returns:\n        State: a Paused state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n\n    if state_details.pause_timeout:\n        raise ValueError(\"An extra pause timeout was provided in state_details\")\n\n    if pause_expiration_time is not None and timeout_seconds is not None:\n        raise ValueError(\n            \"Cannot supply both a pause_expiration_time and timeout_seconds\"\n        )\n\n    if pause_expiration_time is None and timeout_seconds is None:\n        pass\n    else:\n        state_details.pause_timeout = pause_expiration_time or (\n            pendulum.now(\"UTC\") + pendulum.Duration(seconds=timeout_seconds)\n        )\n\n    state_details.pause_reschedule = reschedule\n    state_details.pause_key = pause_key\n\n    return cls(type=StateType.PAUSED, state_details=state_details, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Pending","title":"<code>Pending</code>","text":"<p>Convenience function for creating <code>Pending</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Pending state</p> Source code in <code>prefect/states.py</code> <pre><code>def Pending(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Pending` states.\n\n    Returns:\n        State: a Pending state\n    \"\"\"\n    return cls(type=StateType.PENDING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Retrying","title":"<code>Retrying</code>","text":"<p>Convenience function for creating <code>Retrying</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Retrying state</p> Source code in <code>prefect/states.py</code> <pre><code>def Retrying(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Retrying` states.\n\n    Returns:\n        State: a Retrying state\n    \"\"\"\n    return cls(type=StateType.RUNNING, name=\"Retrying\", **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Running","title":"<code>Running</code>","text":"<p>Convenience function for creating <code>Running</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Running state</p> Source code in <code>prefect/states.py</code> <pre><code>def Running(cls: Type[State[R]] = State, **kwargs: Any) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Running` states.\n\n    Returns:\n        State: a Running state\n    \"\"\"\n    return cls(type=StateType.RUNNING, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Scheduled","title":"<code>Scheduled</code>","text":"<p>Convenience function for creating <code>Scheduled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State[R]</code> <p>a Scheduled state</p> Source code in <code>prefect/states.py</code> <pre><code>def Scheduled(\n    cls: Type[State[R]] = State,\n    scheduled_time: Optional[datetime.datetime] = None,\n    **kwargs: Any,\n) -&gt; State[R]:\n    \"\"\"Convenience function for creating `Scheduled` states.\n\n    Returns:\n        State: a Scheduled state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n    elif state_details.scheduled_time:\n        raise ValueError(\"An extra scheduled_time was provided in state_details\")\n    state_details.scheduled_time = scheduled_time\n\n    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.Suspended","title":"<code>Suspended</code>","text":"<p>Convenience function for creating <code>Suspended</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <p>a Suspended state</p> Source code in <code>prefect/states.py</code> <pre><code>def Suspended(\n    cls: Type[State[R]] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    pause_key: Optional[str] = None,\n    **kwargs: Any,\n):\n    \"\"\"Convenience function for creating `Suspended` states.\n\n    Returns:\n        State: a Suspended state\n    \"\"\"\n    return Paused(\n        cls=cls,\n        name=\"Suspended\",\n        reschedule=True,\n        timeout_seconds=timeout_seconds,\n        pause_expiration_time=pause_expiration_time,\n        pause_key=pause_key,\n        **kwargs,\n    )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.exception_to_crashed_state","title":"<code>exception_to_crashed_state</code>  <code>async</code>","text":"<p>Takes an exception that occurs outside of user code and converts it to a 'Crash' exception with a 'Crashed' state.</p> Source code in <code>prefect/states.py</code> <pre><code>async def exception_to_crashed_state(\n    exc: BaseException,\n    result_factory: Optional[ResultFactory] = None,\n) -&gt; State:\n    \"\"\"\n    Takes an exception that occurs _outside_ of user code and converts it to a\n    'Crash' exception with a 'Crashed' state.\n    \"\"\"\n    state_message = None\n\n    if isinstance(exc, anyio.get_cancelled_exc_class()):\n        state_message = \"Execution was cancelled by the runtime environment.\"\n\n    elif isinstance(exc, KeyboardInterrupt):\n        state_message = \"Execution was aborted by an interrupt signal.\"\n\n    elif isinstance(exc, TerminationSignal):\n        state_message = \"Execution was aborted by a termination signal.\"\n\n    elif isinstance(exc, SystemExit):\n        state_message = \"Execution was aborted by Python system exit call.\"\n\n    elif isinstance(exc, (httpx.TimeoutException, httpx.ConnectError)):\n        try:\n            request: httpx.Request = exc.request\n        except RuntimeError:\n            # The request property is not set\n            state_message = (\n                \"Request failed while attempting to contact the server:\"\n                f\" {format_exception(exc)}\"\n            )\n        else:\n            # TODO: We can check if this is actually our API url\n            state_message = f\"Request to {request.url} failed: {format_exception(exc)}.\"\n\n    else:\n        state_message = (\n            \"Execution was interrupted by an unexpected exception:\"\n            f\" {format_exception(exc)}\"\n        )\n\n    if result_factory:\n        data = await result_factory.create_result(exc)\n    else:\n        # Attach the exception for local usage, will not be available when retrieved\n        # from the API\n        data = exc\n\n    return Crashed(message=state_message, data=data)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.exception_to_failed_state","title":"<code>exception_to_failed_state</code>  <code>async</code>","text":"<p>Convenience function for creating <code>Failed</code> states from exceptions</p> Source code in <code>prefect/states.py</code> <pre><code>async def exception_to_failed_state(\n    exc: Optional[BaseException] = None,\n    result_factory: Optional[ResultFactory] = None,\n    **kwargs,\n) -&gt; State:\n    \"\"\"\n    Convenience function for creating `Failed` states from exceptions\n    \"\"\"\n    if not exc:\n        _, exc, _ = sys.exc_info()\n        if exc is None:\n            raise ValueError(\n                \"Exception was not passed and no active exception could be found.\"\n            )\n    else:\n        pass\n\n    if result_factory:\n        data = await result_factory.create_result(exc)\n    else:\n        # Attach the exception for local usage, will not be available when retrieved\n        # from the API\n        data = exc\n\n    existing_message = kwargs.pop(\"message\", \"\")\n    if existing_message and not existing_message.endswith(\" \"):\n        existing_message += \" \"\n\n    # TODO: Consider if we want to include traceback information, it is intentionally\n    #       excluded from messages for now\n    message = existing_message + format_exception(exc)\n\n    return Failed(data=data, message=message, **kwargs)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.get_state_exception","title":"<code>get_state_exception</code>  <code>async</code>","text":"<p>If not given a FAILED or CRASHED state, this raise a value error.</p> <p>If the state result is a state, its exception will be returned.</p> <p>If the state result is an iterable of states, the exception of the first failure will be returned.</p> <p>If the state result is a string, a wrapper exception will be returned with the string as the message.</p> <p>If the state result is null, a wrapper exception will be returned with the state message attached.</p> <p>If the state result is not of a known type, a <code>TypeError</code> will be returned.</p> <p>When a wrapper exception is returned, the type will be:     - <code>FailedRun</code> if the state type is FAILED.     - <code>CrashedRun</code> if the state type is CRASHED.     - <code>CancelledRun</code> if the state type is CANCELLED.</p> Source code in <code>prefect/states.py</code> <pre><code>@sync_compatible\nasync def get_state_exception(state: State) -&gt; BaseException:\n    \"\"\"\n    If not given a FAILED or CRASHED state, this raise a value error.\n\n    If the state result is a state, its exception will be returned.\n\n    If the state result is an iterable of states, the exception of the first failure\n    will be returned.\n\n    If the state result is a string, a wrapper exception will be returned with the\n    string as the message.\n\n    If the state result is null, a wrapper exception will be returned with the state\n    message attached.\n\n    If the state result is not of a known type, a `TypeError` will be returned.\n\n    When a wrapper exception is returned, the type will be:\n        - `FailedRun` if the state type is FAILED.\n        - `CrashedRun` if the state type is CRASHED.\n        - `CancelledRun` if the state type is CANCELLED.\n    \"\"\"\n\n    if state.is_failed():\n        wrapper = FailedRun\n        default_message = \"Run failed.\"\n    elif state.is_crashed():\n        wrapper = CrashedRun\n        default_message = \"Run crashed.\"\n    elif state.is_cancelled():\n        wrapper = CancelledRun\n        default_message = \"Run cancelled.\"\n    else:\n        raise ValueError(f\"Expected failed or crashed state got {state!r}.\")\n\n    if isinstance(state.data, BaseResult):\n        result = await state.data.get()\n    elif state.data is None:\n        result = None\n    else:\n        result = state.data\n\n    if result is None:\n        return wrapper(state.message or default_message)\n\n    if isinstance(result, Exception):\n        return result\n\n    elif isinstance(result, BaseException):\n        return result\n\n    elif isinstance(result, str):\n        return wrapper(result)\n\n    elif is_state(result):\n        # Return the exception from the inner state\n        return await get_state_exception(result)\n\n    elif is_state_iterable(result):\n        # Return the first failure\n        for state in result:\n            if state.is_failed() or state.is_crashed() or state.is_cancelled():\n                return await get_state_exception(state)\n\n        raise ValueError(\n            \"Failed state result was an iterable of states but none were failed.\"\n        )\n\n    else:\n        raise TypeError(\n            f\"Unexpected result for failed state: {result!r} \u2014\u2014 \"\n            f\"{type(result).__name__} cannot be resolved into an exception\"\n        )\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.get_state_result","title":"<code>get_state_result</code>","text":"<p>Get the result from a state.</p> <p>See <code>State.result()</code></p> Source code in <code>prefect/states.py</code> <pre><code>def get_state_result(\n    state: State[R], raise_on_failure: bool = True, fetch: Optional[bool] = None\n) -&gt; R:\n    \"\"\"\n    Get the result from a state.\n\n    See `State.result()`\n    \"\"\"\n\n    if fetch is None and (\n        PREFECT_ASYNC_FETCH_STATE_RESULT or not in_async_main_thread()\n    ):\n        # Fetch defaults to `True` for sync users or async users who have opted in\n        fetch = True\n\n    if not fetch:\n        if fetch is None and in_async_main_thread():\n            warnings.warn(\n                (\n                    \"State.result() was called from an async context but not awaited. \"\n                    \"This method will be updated to return a coroutine by default in \"\n                    \"the future. Pass `fetch=True` and `await` the call to get rid of \"\n                    \"this warning.\"\n                ),\n                DeprecationWarning,\n                stacklevel=2,\n            )\n        # Backwards compatibility\n        if isinstance(state.data, DataDocument):\n            return result_from_state_with_data_document(\n                state, raise_on_failure=raise_on_failure\n            )\n        else:\n            return state.data\n    else:\n        return _get_state_result(state, raise_on_failure=raise_on_failure)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.is_state","title":"<code>is_state</code>","text":"<p>Check if the given object is a state instance</p> Source code in <code>prefect/states.py</code> <pre><code>def is_state(obj: Any) -&gt; TypeGuard[State]:\n    \"\"\"\n    Check if the given object is a state instance\n    \"\"\"\n    # We may want to narrow this to client-side state types but for now this provides\n    # backwards compatibility\n    try:\n        from prefect.server.schemas.states import State as State_\n\n        classes_ = (State, State_)\n    except ImportError:\n        classes_ = State\n\n    # return isinstance(obj, (State, State_))\n    return isinstance(obj, classes_)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.is_state_iterable","title":"<code>is_state_iterable</code>","text":"<p>Check if a the given object is an iterable of states types</p> <p>Supported iterables are: - set - list - tuple</p> <p>Other iterables will return <code>False</code> even if they contain states.</p> Source code in <code>prefect/states.py</code> <pre><code>def is_state_iterable(obj: Any) -&gt; TypeGuard[Iterable[State]]:\n    \"\"\"\n    Check if a the given object is an iterable of states types\n\n    Supported iterables are:\n    - set\n    - list\n    - tuple\n\n    Other iterables will return `False` even if they contain states.\n    \"\"\"\n    # We do not check for arbitrary iterables because this is not intended to be used\n    # for things like dictionaries, dataframes, or pydantic models\n    if (\n        not isinstance(obj, BaseAnnotation)\n        and isinstance(obj, (list, set, tuple))\n        and obj\n    ):\n        return all([is_state(o) for o in obj])\n    else:\n        return False\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.raise_state_exception","title":"<code>raise_state_exception</code>  <code>async</code>","text":"<p>Given a FAILED or CRASHED state, raise the contained exception.</p> Source code in <code>prefect/states.py</code> <pre><code>@sync_compatible\nasync def raise_state_exception(state: State) -&gt; None:\n    \"\"\"\n    Given a FAILED or CRASHED state, raise the contained exception.\n    \"\"\"\n    if not (state.is_failed() or state.is_crashed() or state.is_cancelled()):\n        return None\n\n    raise await get_state_exception(state)\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/states/#prefect.states.return_value_to_state","title":"<code>return_value_to_state</code>  <code>async</code>","text":"<p>Given a return value from a user's function, create a <code>State</code> the run should be placed in.</p> <ul> <li>If data is returned, we create a 'COMPLETED' state with the data</li> <li>If a single, manually created state is returned, we use that state as given     (manual creation is determined by the lack of ids)</li> <li>If an upstream state or iterable of upstream states is returned, we apply the     aggregate rule</li> </ul> <p>The aggregate rule says that given multiple states we will determine the final state such that:</p> <ul> <li>If any states are not COMPLETED the final state is FAILED</li> <li>If all of the states are COMPLETED the final state is COMPLETED</li> <li>The states will be placed in the final state <code>data</code> attribute</li> </ul> <p>Callers should resolve all futures into states before passing return values to this function.</p> Source code in <code>prefect/states.py</code> <pre><code>async def return_value_to_state(retval: R, result_factory: ResultFactory) -&gt; State[R]:\n    \"\"\"\n    Given a return value from a user's function, create a `State` the run should\n    be placed in.\n\n    - If data is returned, we create a 'COMPLETED' state with the data\n    - If a single, manually created state is returned, we use that state as given\n        (manual creation is determined by the lack of ids)\n    - If an upstream state or iterable of upstream states is returned, we apply the\n        aggregate rule\n\n    The aggregate rule says that given multiple states we will determine the final state\n    such that:\n\n    - If any states are not COMPLETED the final state is FAILED\n    - If all of the states are COMPLETED the final state is COMPLETED\n    - The states will be placed in the final state `data` attribute\n\n    Callers should resolve all futures into states before passing return values to this\n    function.\n    \"\"\"\n\n    if (\n        is_state(retval)\n        # Check for manual creation\n        and not retval.state_details.flow_run_id\n        and not retval.state_details.task_run_id\n    ):\n        state = retval\n\n        # Do not modify states with data documents attached; backwards compatibility\n        if isinstance(state.data, DataDocument):\n            return state\n\n        # Unless the user has already constructed a result explicitly, use the factory\n        # to update the data to the correct type\n        if not isinstance(state.data, BaseResult):\n            state.data = await result_factory.create_result(state.data)\n\n        return state\n\n    # Determine a new state from the aggregate of contained states\n    if is_state(retval) or is_state_iterable(retval):\n        states = StateGroup(ensure_iterable(retval))\n\n        # Determine the new state type\n        if states.all_completed():\n            new_state_type = StateType.COMPLETED\n        elif states.any_cancelled():\n            new_state_type = StateType.CANCELLED\n        elif states.any_paused():\n            new_state_type = StateType.PAUSED\n        else:\n            new_state_type = StateType.FAILED\n\n        # Generate a nice message for the aggregate\n        if states.all_completed():\n            message = \"All states completed.\"\n        elif states.any_cancelled():\n            message = f\"{states.cancelled_count}/{states.total_count} states cancelled.\"\n        elif states.any_paused():\n            message = f\"{states.paused_count}/{states.total_count} states paused.\"\n        elif states.any_failed():\n            message = f\"{states.fail_count}/{states.total_count} states failed.\"\n        elif not states.all_final():\n            message = (\n                f\"{states.not_final_count}/{states.total_count} states are not final.\"\n            )\n        else:\n            message = \"Given states: \" + states.counts_message()\n\n        # TODO: We may actually want to set the data to a `StateGroup` object and just\n        #       allow it to be unpacked into a tuple and such so users can interact with\n        #       it\n        return State(\n            type=new_state_type,\n            message=message,\n            data=await result_factory.create_result(retval),\n        )\n\n    # Generators aren't portable, implicitly convert them to a list.\n    if isinstance(retval, GeneratorType):\n        data = list(retval)\n    else:\n        data = retval\n\n    # Otherwise, they just gave data and this is a completed retval\n    return Completed(data=await result_factory.create_result(data))\n</code></pre>","tags":["Python API","states"]},{"location":"api-ref/prefect/task-runners/","title":"prefect.task_runners","text":"","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners","title":"<code>prefect.task_runners</code>","text":"<p>Interface and implementations of various task runners.</p> <p>Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; from prefect.task_runners import SequentialTaskRunner\n&gt;&gt;&gt; from typing import List\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def say_hello(name):\n...     print(f\"hello {name}\")\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def say_goodbye(name):\n...     print(f\"goodbye {name}\")\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow(task_runner=SequentialTaskRunner())\n&gt;&gt;&gt; def greetings(names: List[str]):\n...     for name in names:\n...         say_hello(name)\n...         say_goodbye(name)\n&gt;&gt;&gt;\n&gt;&gt;&gt; greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\nhello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre> <p>Switching to a <code>DaskTaskRunner</code>: <pre><code>&gt;&gt;&gt; from prefect_dask.task_runners import DaskTaskRunner\n&gt;&gt;&gt; flow.task_runner = DaskTaskRunner()\n&gt;&gt;&gt; greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\nhello arthur\ngoodbye arthur\nhello trillian\nhello ford\ngoodbye marvin\nhello marvin\ngoodbye ford\ngoodbye trillian\n</code></pre></p> <p>For usage details, see the Task Runners documentation.</p>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner","title":"<code>BaseTaskRunner</code>","text":"Source code in <code>prefect/task_runners.py</code> <pre><code>class BaseTaskRunner(metaclass=abc.ABCMeta):\n    def __init__(self) -&gt; None:\n        self.logger = get_logger(f\"task_runner.{self.name}\")\n        self._started: bool = False\n\n    @property\n    @abc.abstractmethod\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        pass  # noqa\n\n    @property\n    def name(self):\n        return type(self).__name__.lower().replace(\"taskrunner\", \"\")\n\n    def duplicate(self):\n        \"\"\"\n        Return a new task runner instance with the same options.\n        \"\"\"\n        # The base class returns `NotImplemented` to indicate that this is not yet\n        # implemented by a given task runner.\n        return NotImplemented\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Returns true if the task runners use the same options.\n        \"\"\"\n        if type(other) == type(self) and (\n            # Compare public attributes for naive equality check\n            # Subclasses should implement this method with a check init option equality\n            {k: v for k, v in self.__dict__.items() if not k.startswith(\"_\")}\n            == {k: v for k, v in other.__dict__.items() if not k.startswith(\"_\")}\n        ):\n            return True\n        else:\n            return NotImplemented\n\n    @abc.abstractmethod\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        \"\"\"\n        Submit a call for execution and return a `PrefectFuture` that can be used to\n        get the call result.\n\n        Args:\n            task_run: The task run being submitted.\n            task_key: A unique key for this orchestration run of the task. Can be used\n                for caching.\n            call: The function to be executed\n            run_kwargs: A dict of keyword arguments to pass to `call`\n\n        Returns:\n            A future representing the result of `call` execution\n        \"\"\"\n        raise NotImplementedError()\n\n    @abc.abstractmethod\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        \"\"\"\n        Given a `PrefectFuture`, wait for its return state up to `timeout` seconds.\n        If it is not finished after the timeout expires, `None` should be returned.\n\n        Implementers should be careful to ensure that this function never returns or\n        raises an exception.\n        \"\"\"\n        raise NotImplementedError()\n\n    @asynccontextmanager\n    async def start(\n        self: T,\n    ) -&gt; AsyncIterator[T]:\n        \"\"\"\n        Start the task runner, preparing any resources necessary for task submission.\n\n        Children should implement `_start` to prepare and clean up resources.\n\n        Yields:\n            The prepared task runner\n        \"\"\"\n        if self._started:\n            raise RuntimeError(\"The task runner is already started!\")\n\n        async with AsyncExitStack() as exit_stack:\n            self.logger.debug(\"Starting task runner...\")\n            try:\n                await self._start(exit_stack)\n                self._started = True\n                yield self\n            finally:\n                self.logger.debug(\"Shutting down task runner...\")\n                self._started = False\n\n    async def _start(self, exit_stack: AsyncExitStack) -&gt; None:\n        \"\"\"\n        Create any resources required for this task runner to submit work.\n\n        Cleanup of resources should be submitted to the `exit_stack`.\n        \"\"\"\n        pass  # noqa\n\n    def __str__(self) -&gt; str:\n        return type(self).__name__\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Return a new task runner instance with the same options.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Return a new task runner instance with the same options.\n    \"\"\"\n    # The base class returns `NotImplemented` to indicate that this is not yet\n    # implemented by a given task runner.\n    return NotImplemented\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start the task runner, preparing any resources necessary for task submission.</p> <p>Children should implement <code>_start</code> to prepare and clean up resources.</p> <p>Yields:</p> Type Description <code>AsyncIterator[T]</code> <p>The prepared task runner</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@asynccontextmanager\nasync def start(\n    self: T,\n) -&gt; AsyncIterator[T]:\n    \"\"\"\n    Start the task runner, preparing any resources necessary for task submission.\n\n    Children should implement `_start` to prepare and clean up resources.\n\n    Yields:\n        The prepared task runner\n    \"\"\"\n    if self._started:\n        raise RuntimeError(\"The task runner is already started!\")\n\n    async with AsyncExitStack() as exit_stack:\n        self.logger.debug(\"Starting task runner...\")\n        try:\n            await self._start(exit_stack)\n            self._started = True\n            yield self\n        finally:\n            self.logger.debug(\"Shutting down task runner...\")\n            self._started = False\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.submit","title":"<code>submit</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Submit a call for execution and return a <code>PrefectFuture</code> that can be used to get the call result.</p> <p>Parameters:</p> Name Type Description Default <code>task_run</code> <p>The task run being submitted.</p> required <code>task_key</code> <p>A unique key for this orchestration run of the task. Can be used for caching.</p> required <code>call</code> <code>Callable[..., Awaitable[State[R]]]</code> <p>The function to be executed</p> required <code>run_kwargs</code> <p>A dict of keyword arguments to pass to <code>call</code></p> required <p>Returns:</p> Type Description <code>None</code> <p>A future representing the result of <code>call</code> execution</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@abc.abstractmethod\nasync def submit(\n    self,\n    key: UUID,\n    call: Callable[..., Awaitable[State[R]]],\n) -&gt; None:\n    \"\"\"\n    Submit a call for execution and return a `PrefectFuture` that can be used to\n    get the call result.\n\n    Args:\n        task_run: The task run being submitted.\n        task_key: A unique key for this orchestration run of the task. Can be used\n            for caching.\n        call: The function to be executed\n        run_kwargs: A dict of keyword arguments to pass to `call`\n\n    Returns:\n        A future representing the result of `call` execution\n    \"\"\"\n    raise NotImplementedError()\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.BaseTaskRunner.wait","title":"<code>wait</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Given a <code>PrefectFuture</code>, wait for its return state up to <code>timeout</code> seconds. If it is not finished after the timeout expires, <code>None</code> should be returned.</p> <p>Implementers should be careful to ensure that this function never returns or raises an exception.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>@abc.abstractmethod\nasync def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n    \"\"\"\n    Given a `PrefectFuture`, wait for its return state up to `timeout` seconds.\n    If it is not finished after the timeout expires, `None` should be returned.\n\n    Implementers should be careful to ensure that this function never returns or\n    raises an exception.\n    \"\"\"\n    raise NotImplementedError()\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.ConcurrentTaskRunner","title":"<code>ConcurrentTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A concurrent task runner that allows tasks to switch when blocking on IO. Synchronous tasks will be submitted to a thread pool maintained by <code>anyio</code>.</p> Example <pre><code>Using a thread for concurrency:\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; from prefect.task_runners import ConcurrentTaskRunner\n&gt;&gt;&gt; @flow(task_runner=ConcurrentTaskRunner)\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     ...\n</code></pre> Source code in <code>prefect/task_runners.py</code> <pre><code>class ConcurrentTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A concurrent task runner that allows tasks to switch when blocking on IO.\n    Synchronous tasks will be submitted to a thread pool maintained by `anyio`.\n\n    Example:\n        ```\n        Using a thread for concurrency:\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; from prefect.task_runners import ConcurrentTaskRunner\n        &gt;&gt;&gt; @flow(task_runner=ConcurrentTaskRunner)\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     ...\n        ```\n    \"\"\"\n\n    def __init__(self):\n        # TODO: Consider adding `max_workers` support using anyio capacity limiters\n\n        # Runtime attributes\n        self._task_group: anyio.abc.TaskGroup = None\n        self._result_events: Dict[UUID, Event] = {}\n        self._results: Dict[UUID, Any] = {}\n        self._keys: Set[UUID] = set()\n\n        super().__init__()\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.CONCURRENT\n\n    def duplicate(self):\n        return type(self)()\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[[], Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        if not self._task_group:\n            raise RuntimeError(\n                \"The concurrent task runner cannot be used to submit work after \"\n                \"serialization.\"\n            )\n\n        # Create an event to set on completion\n        self._result_events[key] = Event()\n\n        # Rely on the event loop for concurrency\n        self._task_group.start_soon(self._run_and_store_result, key, call)\n\n    async def wait(\n        self,\n        key: UUID,\n        timeout: float = None,\n    ) -&gt; Optional[State]:\n        if not self._task_group:\n            raise RuntimeError(\n                \"The concurrent task runner cannot be used to wait for work after \"\n                \"serialization.\"\n            )\n\n        return await self._get_run_result(key, timeout)\n\n    async def _run_and_store_result(\n        self, key: UUID, call: Callable[[], Awaitable[State[R]]]\n    ):\n        \"\"\"\n        Simple utility to store the orchestration result in memory on completion\n\n        Since this run is occurring on the main thread, we capture exceptions to prevent\n        task crashes from crashing the flow run.\n        \"\"\"\n        try:\n            result = await call()\n        except BaseException as exc:\n            result = await exception_to_crashed_state(exc)\n\n        self._results[key] = result\n        self._result_events[key].set()\n\n    async def _get_run_result(\n        self, key: UUID, timeout: float = None\n    ) -&gt; Optional[State]:\n        \"\"\"\n        Block until the run result has been populated.\n        \"\"\"\n        result = None  # retval on timeout\n\n        # Note we do not use `asyncio.wrap_future` and instead use an `Event` to avoid\n        # stdlib behavior where the wrapped future is cancelled if the parent future is\n        # cancelled (as it would be during a timeout here)\n        with anyio.move_on_after(timeout):\n            await self._result_events[key].wait()\n            result = self._results[key]\n\n        return result  # timeout reached\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the process pool\n        \"\"\"\n        self._task_group = await exit_stack.enter_async_context(\n            anyio.create_task_group()\n        )\n\n    def __getstate__(self):\n        \"\"\"\n        Allow the `ConcurrentTaskRunner` to be serialized by dropping the task group.\n        \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_task_group\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"\n        When deserialized, we will no longer have a reference to the task group.\n        \"\"\"\n        self.__dict__.update(data)\n        self._task_group = None\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/task-runners/#prefect.task_runners.SequentialTaskRunner","title":"<code>SequentialTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A simple task runner that executes calls as they are submitted.</p> <p>If writing synchronous tasks, this runner will always execute tasks sequentially. If writing async tasks, this runner will execute tasks sequentially unless grouped using <code>anyio.create_task_group</code> or <code>asyncio.gather</code>.</p> Source code in <code>prefect/task_runners.py</code> <pre><code>class SequentialTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A simple task runner that executes calls as they are submitted.\n\n    If writing synchronous tasks, this runner will always execute tasks sequentially.\n    If writing async tasks, this runner will execute tasks sequentially unless grouped\n    using `anyio.create_task_group` or `asyncio.gather`.\n    \"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__()\n        self._results: Dict[str, State] = {}\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.SEQUENTIAL\n\n    def duplicate(self):\n        return type(self)()\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        # Run the function immediately and store the result in memory\n        try:\n            result = await call()\n        except BaseException as exc:\n            result = await exception_to_crashed_state(exc)\n\n        self._results[key] = result\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        return self._results[key]\n</code></pre>","tags":["Python API","tasks","task runners","Dask","Ray"]},{"location":"api-ref/prefect/tasks/","title":"prefect.tasks","text":"","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks","title":"<code>prefect.tasks</code>","text":"<p>Module containing the base workflow task class and decorator - for most use cases, using the <code>@task</code> decorator is preferred.</p>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task","title":"<code>Task</code>","text":"<p>               Bases: <code>Generic[P, R]</code></p> <p>A Prefect task definition.</p> <p>Note</p> <p>We recommend using the <code>@task</code> decorator for most use-cases.</p> <p>Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function creates a new task run.</p> <p>To preserve the input and output types, we use the generic type variables P and R for \"Parameters\" and \"Returns\" respectively.</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable[P, R]</code> <p>The function defining the task.</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>An optional string description for the task.</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>An optional string specifying the version of this task definition</p> <code>None</code> <code>cache_key_fn</code> <code>Optional[Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]]</code> <p>An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.</p> <code>None</code> <code>cache_expiration</code> <code>Optional[timedelta]</code> <p>An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>An optional number of times to retry on task run failure.</p> <code>None</code> <code>retry_delay_seconds</code> <code>Optional[Union[float, int, List[float], Callable[[int], List[float]]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>None</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>An optional key to store the result in storage at when persisted. Defaults to a unique identifier.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float, None]</code> <p>An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the task will be redirected to the Prefect logger for the task run. Defaults to <code>None</code>, which indicates that the value from the flow should be used.</p> <code>False</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>If set, cached results for the cache key are not used. Defaults to <code>None</code>, which indicates that a cached result from a previous execution with matching cache key is used.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a completed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy (e.g. <code>retries=3</code>), and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Optional[Any]</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> Source code in <code>prefect/tasks.py</code> <pre><code>@PrefectObjectRegistry.register_instances\nclass Task(Generic[P, R]):\n    \"\"\"\n    A Prefect task definition.\n\n    !!! note\n        We recommend using [the `@task` decorator][prefect.tasks.task] for most use-cases.\n\n    Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function\n    creates a new task run.\n\n    To preserve the input and output types, we use the generic type variables P and R for \"Parameters\" and\n    \"Returns\" respectively.\n\n    Args:\n        fn: The function defining the task.\n        name: An optional name for the task; if not provided, the name will be inferred\n            from the given function.\n        description: An optional string description for the task.\n        tags: An optional set of tags to be associated with runs of this task. These\n            tags are combined with any tags defined by a `prefect.tags` context at\n            task runtime.\n        version: An optional string specifying the version of this task definition\n        cache_key_fn: An optional callable that, given the task run context and call\n            parameters, generates a string key; if the key matches a previous completed\n            state, that state result will be restored instead of running the task again.\n        cache_expiration: An optional amount of time indicating how long cached states\n            for this task should be restorable; if not provided, cached states will\n            never expire.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on task run failure.\n        retry_delay_seconds: Optionally configures how long to wait before retrying the\n            task after failure. This is only applicable if `retries` is nonzero. This\n            setting can either be a number of seconds, a list of retry delays, or a\n            callable that, given the total number of retries, generates a list of retry\n            delays. If a number of seconds, that delay will be applied to all retries.\n            If a list, each retry will wait for the corresponding delay before retrying.\n            When passing a callable or a list, the number of configured retry delays\n            cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a retry\n            can be jittered in order to avoid a \"thundering herd\".\n        persist_result: An optional toggle indicating whether the result of this task\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this task.\n            Defaults to the value set in the flow the task is called in.\n        result_storage_key: An optional key to store the result in storage at when persisted.\n            Defaults to a unique identifier.\n        result_serializer: An optional serializer to use to serialize the result of this\n            task for persistence. Defaults to the value set in the flow the task is\n            called in.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the task. If the task exceeds this runtime, it will be marked as failed.\n        log_prints: If set, `print` statements in the task will be redirected to the\n            Prefect logger for the task run. Defaults to `None`, which indicates\n            that the value from the flow should be used.\n        refresh_cache: If set, cached results for the cache key are not used.\n            Defaults to `None`, which indicates that a cached result from a previous\n            execution with matching cache key is used.\n        on_failure: An optional list of callables to run when the task enters a failed state.\n        on_completion: An optional list of callables to run when the task enters a completed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state. Should\n            return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task\n            should end as failed. Defaults to `None`, indicating the task should always continue\n            to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n    \"\"\"\n\n    # NOTE: These parameters (types, defaults, and docstrings) should be duplicated\n    #       exactly in the @task decorator\n    def __init__(\n        self,\n        fn: Callable[P, R],\n        name: Optional[str] = None,\n        description: Optional[str] = None,\n        tags: Optional[Iterable[str]] = None,\n        version: Optional[str] = None,\n        cache_key_fn: Optional[\n            Callable[[\"TaskRunContext\", Dict[str, Any]], Optional[str]]\n        ] = None,\n        cache_expiration: Optional[datetime.timedelta] = None,\n        task_run_name: Optional[Union[Callable[[], str], str]] = None,\n        retries: Optional[int] = None,\n        retry_delay_seconds: Optional[\n            Union[\n                float,\n                int,\n                List[float],\n                Callable[[int], List[float]],\n            ]\n        ] = None,\n        retry_jitter_factor: Optional[float] = None,\n        persist_result: Optional[bool] = None,\n        result_storage: Optional[ResultStorage] = None,\n        result_serializer: Optional[ResultSerializer] = None,\n        result_storage_key: Optional[str] = None,\n        cache_result_in_memory: bool = True,\n        timeout_seconds: Union[int, float, None] = None,\n        log_prints: Optional[bool] = False,\n        refresh_cache: Optional[bool] = None,\n        on_completion: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n        on_failure: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n        retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n        viz_return_value: Optional[Any] = None,\n    ):\n        # Validate if hook passed is list and contains callables\n        hook_categories = [on_completion, on_failure]\n        hook_names = [\"on_completion\", \"on_failure\"]\n        for hooks, hook_name in zip(hook_categories, hook_names):\n            if hooks is not None:\n                if not hooks:\n                    raise ValueError(f\"Empty list passed for '{hook_name}'\")\n                try:\n                    hooks = list(hooks)\n                except TypeError:\n                    raise TypeError(\n                        f\"Expected iterable for '{hook_name}'; got\"\n                        f\" {type(hooks).__name__} instead. Please provide a list of\"\n                        f\" hooks to '{hook_name}':\\n\\n\"\n                        f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                        \" my_flow():\\n\\tpass\"\n                    )\n\n                for hook in hooks:\n                    if not callable(hook):\n                        raise TypeError(\n                            f\"Expected callables in '{hook_name}'; got\"\n                            f\" {type(hook).__name__} instead. Please provide a list of\"\n                            f\" hooks to '{hook_name}':\\n\\n\"\n                            f\"@flow({hook_name}=[hook1, hook2])\\ndef\"\n                            \" my_flow():\\n\\tpass\"\n                        )\n\n        if not callable(fn):\n            raise TypeError(\"'fn' must be callable\")\n\n        self.description = description or inspect.getdoc(fn)\n        update_wrapper(self, fn)\n        self.fn = fn\n        self.isasync = inspect.iscoroutinefunction(self.fn)\n\n        if not name:\n            if not hasattr(self.fn, \"__name__\"):\n                self.name = type(self.fn).__name__\n            else:\n                self.name = self.fn.__name__\n        else:\n            self.name = name\n\n        if task_run_name is not None:\n            if not isinstance(task_run_name, str) and not callable(task_run_name):\n                raise TypeError(\n                    \"Expected string or callable for 'task_run_name'; got\"\n                    f\" {type(task_run_name).__name__} instead.\"\n                )\n        self.task_run_name = task_run_name\n\n        self.version = version\n        self.log_prints = log_prints\n\n        raise_for_reserved_arguments(self.fn, [\"return_state\", \"wait_for\"])\n\n        self.tags = set(tags if tags else [])\n\n        self.task_key = _generate_task_key(self.fn)\n\n        self.cache_key_fn = cache_key_fn\n        self.cache_expiration = cache_expiration\n        self.refresh_cache = refresh_cache\n\n        # TaskRunPolicy settings\n        # TODO: We can instantiate a `TaskRunPolicy` and add Pydantic bound checks to\n        #       validate that the user passes positive numbers here\n\n        self.retries = (\n            retries if retries is not None else PREFECT_TASK_DEFAULT_RETRIES.value()\n        )\n        if retry_delay_seconds is None:\n            retry_delay_seconds = PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS.value()\n\n        if callable(retry_delay_seconds):\n            self.retry_delay_seconds = retry_delay_seconds(retries)\n        else:\n            self.retry_delay_seconds = retry_delay_seconds\n\n        if isinstance(self.retry_delay_seconds, list) and (\n            len(self.retry_delay_seconds) &gt; 50\n        ):\n            raise ValueError(\"Can not configure more than 50 retry delays per task.\")\n\n        if retry_jitter_factor is not None and retry_jitter_factor &lt; 0:\n            raise ValueError(\"`retry_jitter_factor` must be &gt;= 0.\")\n\n        self.retry_jitter_factor = retry_jitter_factor\n        self.persist_result = persist_result\n        self.result_storage = result_storage\n        self.result_serializer = result_serializer\n        self.result_storage_key = result_storage_key\n        self.cache_result_in_memory = cache_result_in_memory\n        self.timeout_seconds = float(timeout_seconds) if timeout_seconds else None\n        self.on_completion = on_completion\n        self.on_failure = on_failure\n\n        # retry_condition_fn must be a callable or None. If it is neither, raise a TypeError\n        if retry_condition_fn is not None and not (callable(retry_condition_fn)):\n            raise TypeError(\n                \"Expected `retry_condition_fn` to be callable, got\"\n                f\" {type(retry_condition_fn).__name__} instead.\"\n            )\n\n        self.retry_condition_fn = retry_condition_fn\n        self.viz_return_value = viz_return_value\n\n    def with_options(\n        self,\n        *,\n        name: str = None,\n        description: str = None,\n        tags: Iterable[str] = None,\n        cache_key_fn: Callable[\n            [\"TaskRunContext\", Dict[str, Any]], Optional[str]\n        ] = None,\n        task_run_name: Optional[Union[Callable[[], str], str]] = None,\n        cache_expiration: datetime.timedelta = None,\n        retries: Optional[int] = NotSet,\n        retry_delay_seconds: Union[\n            float,\n            int,\n            List[float],\n            Callable[[int], List[float]],\n        ] = NotSet,\n        retry_jitter_factor: Optional[float] = NotSet,\n        persist_result: Optional[bool] = NotSet,\n        result_storage: Optional[ResultStorage] = NotSet,\n        result_serializer: Optional[ResultSerializer] = NotSet,\n        result_storage_key: Optional[str] = NotSet,\n        cache_result_in_memory: Optional[bool] = None,\n        timeout_seconds: Union[int, float] = None,\n        log_prints: Optional[bool] = NotSet,\n        refresh_cache: Optional[bool] = NotSet,\n        on_completion: Optional[\n            List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n        ] = None,\n        on_failure: Optional[\n            List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n        ] = None,\n        retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n        viz_return_value: Optional[Any] = None,\n    ):\n        \"\"\"\n        Create a new task from the current object, updating provided options.\n\n        Args:\n            name: A new name for the task.\n            description: A new description for the task.\n            tags: A new set of tags for the task. If given, existing tags are ignored,\n                not merged.\n            cache_key_fn: A new cache key function for the task.\n            cache_expiration: A new cache expiration time for the task.\n            task_run_name: An optional name to distinguish runs of this task; this name can be provided\n                as a string template with the task's keyword arguments as variables,\n                or a function that returns a string.\n            retries: A new number of times to retry on task run failure.\n            retry_delay_seconds: Optionally configures how long to wait before retrying\n                the task after failure. This is only applicable if `retries` is nonzero.\n                This setting can either be a number of seconds, a list of retry delays,\n                or a callable that, given the total number of retries, generates a list\n                of retry delays. If a number of seconds, that delay will be applied to\n                all retries. If a list, each retry will wait for the corresponding delay\n                before retrying. When passing a callable or a list, the number of\n                configured retry delays cannot exceed 50.\n            retry_jitter_factor: An optional factor that defines the factor to which a\n                retry can be jittered in order to avoid a \"thundering herd\".\n            persist_result: A new option for enabling or disabling result persistence.\n            result_storage: A new storage type to use for results.\n            result_serializer: A new serializer to use for results.\n            result_storage_key: A new key for the persisted result to be stored at.\n            timeout_seconds: A new maximum time for the task to complete in seconds.\n            log_prints: A new option for enabling or disabling redirection of `print` statements.\n            refresh_cache: A new option for enabling or disabling cache refresh.\n            on_completion: A new list of callables to run when the task enters a completed state.\n            on_failure: A new list of callables to run when the task enters a failed state.\n            retry_condition_fn: An optional callable run when a task run returns a Failed state.\n                Should return `True` if the task should continue to its retry policy, and `False`\n                if the task should end as failed. Defaults to `None`, indicating the task should\n                always continue to its retry policy.\n            viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n        Returns:\n            A new `Task` instance.\n\n        Examples:\n\n            Create a new task from an existing task and update the name\n\n            &gt;&gt;&gt; @task(name=\"My task\")\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\n            Create a new task from an existing task and update the retry settings\n\n            &gt;&gt;&gt; from random import randint\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     x = randint(0, 5)\n            &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n            &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n            &gt;&gt;&gt;     return x\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\n            Use a task with updated options within a flow\n\n            &gt;&gt;&gt; @task(name=\"My task\")\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; my_flow():\n            &gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n            &gt;&gt;&gt;     new_task()\n        \"\"\"\n        return Task(\n            fn=self.fn,\n            name=name or self.name,\n            description=description or self.description,\n            tags=tags or copy(self.tags),\n            cache_key_fn=cache_key_fn or self.cache_key_fn,\n            cache_expiration=cache_expiration or self.cache_expiration,\n            task_run_name=task_run_name,\n            retries=retries if retries is not NotSet else self.retries,\n            retry_delay_seconds=(\n                retry_delay_seconds\n                if retry_delay_seconds is not NotSet\n                else self.retry_delay_seconds\n            ),\n            retry_jitter_factor=(\n                retry_jitter_factor\n                if retry_jitter_factor is not NotSet\n                else self.retry_jitter_factor\n            ),\n            persist_result=(\n                persist_result if persist_result is not NotSet else self.persist_result\n            ),\n            result_storage=(\n                result_storage if result_storage is not NotSet else self.result_storage\n            ),\n            result_storage_key=(\n                result_storage_key\n                if result_storage_key is not NotSet\n                else self.result_storage_key\n            ),\n            result_serializer=(\n                result_serializer\n                if result_serializer is not NotSet\n                else self.result_serializer\n            ),\n            cache_result_in_memory=(\n                cache_result_in_memory\n                if cache_result_in_memory is not None\n                else self.cache_result_in_memory\n            ),\n            timeout_seconds=(\n                timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n            ),\n            log_prints=(log_prints if log_prints is not NotSet else self.log_prints),\n            refresh_cache=(\n                refresh_cache if refresh_cache is not NotSet else self.refresh_cache\n            ),\n            on_completion=on_completion or self.on_completion,\n            on_failure=on_failure or self.on_failure,\n            retry_condition_fn=retry_condition_fn or self.retry_condition_fn,\n            viz_return_value=viz_return_value or self.viz_return_value,\n        )\n\n    async def create_run(\n        self,\n        client: Optional[Union[PrefectClient, SyncPrefectClient]],\n        parameters: Dict[str, Any] = None,\n        flow_run_context: Optional[FlowRunContext] = None,\n        parent_task_run_context: Optional[TaskRunContext] = None,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        extra_task_inputs: Optional[Dict[str, Set[TaskRunInput]]] = None,\n    ) -&gt; TaskRun:\n        from prefect.utilities.engine import (\n            _dynamic_key_for_task_run,\n            _resolve_custom_task_run_name,\n            collect_task_run_inputs,\n        )\n\n        if flow_run_context is None:\n            flow_run_context = FlowRunContext.get()\n        if parent_task_run_context is None:\n            parent_task_run_context = TaskRunContext.get()\n        if parameters is None:\n            parameters = {}\n\n        try:\n            task_run_name = _resolve_custom_task_run_name(self, parameters)\n        except TypeError:\n            task_run_name = None\n\n        if flow_run_context:\n            dynamic_key = _dynamic_key_for_task_run(context=flow_run_context, task=self)\n        else:\n            dynamic_key = uuid4().hex\n\n        # collect task inputs\n        task_inputs = {\n            k: await collect_task_run_inputs(v) for k, v in parameters.items()\n        }\n\n        # check if this task has a parent task run based on running in another\n        # task run's existing context. A task run is only considered a parent if\n        # it is in the same flow run (because otherwise presumably the child is\n        # in a subflow, so the subflow serves as the parent) or if there is no\n        # flow run\n        if parent_task_run_context:\n            # there is no flow run\n            if not flow_run_context:\n                task_inputs[\"__parents__\"] = [\n                    TaskRunResult(id=parent_task_run_context.task_run.id)\n                ]\n            # there is a flow run and the task run is in the same flow run\n            elif (\n                flow_run_context\n                and parent_task_run_context.task_run.flow_run_id\n                == flow_run_context.flow_run.id\n            ):\n                task_inputs[\"__parents__\"] = [\n                    TaskRunResult(id=parent_task_run_context.task_run.id)\n                ]\n\n        if wait_for:\n            task_inputs[\"wait_for\"] = await collect_task_run_inputs(wait_for)\n\n        # Join extra task inputs\n        for k, extras in (extra_task_inputs or {}).items():\n            task_inputs[k] = task_inputs[k].union(extras)\n\n        # create the task run\n        task_run = client.create_task_run(\n            task=self,\n            name=task_run_name,\n            flow_run_id=(\n                getattr(flow_run_context.flow_run, \"id\", None)\n                if flow_run_context and flow_run_context.flow_run\n                else None\n            ),\n            dynamic_key=str(dynamic_key),\n            state=Pending(),\n            task_inputs=task_inputs,\n            extra_tags=TagsContext.get().current_tags,\n        )\n        # the new engine uses sync clients but old engines use async clients\n        if inspect.isawaitable(task_run):\n            task_run = await task_run\n\n        if flow_run_context and flow_run_context.flow_run:\n            get_run_logger(flow_run_context).debug(\n                f\"Created task run {task_run.name!r} for task {self.name!r}\"\n            )\n        else:\n            logger.debug(f\"Created task run {task_run.name!r} for task {self.name!r}\")\n\n        return task_run\n\n    @overload\n    def __call__(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; None:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def __call__(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; T:\n        ...\n\n    @overload\n    def __call__(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def __call__(\n        self,\n        *args: P.args,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: P.kwargs,\n    ):\n        \"\"\"\n        Run the task and return the result. If `return_state` is True returns\n        the result is wrapped in a Prefect State which provides error handling.\n        \"\"\"\n        from prefect.engine import enter_task_run_engine\n        from prefect.task_engine import submit_autonomous_task_run_to_engine\n        from prefect.task_runners import SequentialTaskRunner\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return_type = \"state\" if return_state else \"result\"\n\n        task_run_tracker = get_task_viz_tracker()\n        if task_run_tracker:\n            return track_viz_task(\n                self.isasync, self.name, parameters, self.viz_return_value\n            )\n\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE.value():\n            from prefect.new_task_engine import run_task\n\n            return run_task(\n                task=self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n            )\n\n        if (\n            PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n            and not FlowRunContext.get()\n        ):\n            from prefect import get_client\n\n            return submit_autonomous_task_run_to_engine(\n                task=self,\n                task_run=None,\n                task_runner=SequentialTaskRunner(),\n                parameters=parameters,\n                return_type=return_type,\n                client=get_client(),\n            )\n        entering_from_task_run = bool(TaskRunContext.get())\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            task_runner=SequentialTaskRunner(),\n            return_type=return_type,\n            mapped=False,\n            entering_from_task_run=entering_from_task_run,\n        )\n\n    @overload\n    def _run(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[None, Sync]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def _run(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[State[T]]:\n        ...\n\n    @overload\n    def _run(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    def _run(\n        self,\n        *args: P.args,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: P.kwargs,\n    ) -&gt; Union[State, Awaitable[State]]:\n        \"\"\"\n        Run the task and return the final state.\n        \"\"\"\n        from prefect.engine import enter_task_run_engine\n        from prefect.task_runners import SequentialTaskRunner\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=\"state\",\n            task_runner=SequentialTaskRunner(),\n            mapped=False,\n        )\n\n    @overload\n    def submit(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[None, Sync]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[PrefectFuture[T, Async]]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; PrefectFuture[T, Sync]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; State[T]:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; TaskRun:\n        ...\n\n    @overload\n    def submit(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[TaskRun]:\n        ...\n\n    def submit(\n        self,\n        *args: Any,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: Any,\n    ) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]:\n        \"\"\"\n        Submit a run of the task to the engine.\n\n        If writing an async task, this call must be awaited.\n\n        If called from within a flow function,\n\n        Will create a new task run in the backing API and submit the task to the flow's\n        task runner. This call only blocks execution while the task is being submitted,\n        once it is submitted, the flow function will continue executing. However, note\n        that the `SequentialTaskRunner` does not implement parallel execution for sync tasks\n        and they are fully resolved on submission.\n\n        Args:\n            *args: Arguments to run the task with\n            return_state: Return the result of the flow run wrapped in a\n                Prefect State.\n            wait_for: Upstream task futures to wait for before starting the task\n            **kwargs: Keyword arguments to run the task with\n\n        Returns:\n            If `return_state` is False a future allowing asynchronous access to\n                the state of the task\n            If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to\n                the state of the task\n\n        Examples:\n\n            Define a task\n\n            &gt;&gt;&gt; from prefect import task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return \"hello\"\n\n            Run a task in a flow\n\n            &gt;&gt;&gt; from prefect import flow\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.submit()\n\n            Wait for a task to finish\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.submit().wait()\n\n            Use the result from a task in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     print(my_task.submit().result())\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            hello\n\n            Run an async task in an async flow\n\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; async def my_async_task():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     await my_async_task.submit()\n\n            Run a sync task in an async flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     my_task.submit()\n\n            Enforce ordering between tasks that do not exchange data\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_1():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_2():\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     x = task_1.submit()\n            &gt;&gt;&gt;\n            &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n            &gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n\n        \"\"\"\n\n        from prefect.engine import create_autonomous_task_run, enter_task_run_engine\n\n        # Convert the call args/kwargs to a parameter dict\n        parameters = get_call_parameters(self.fn, args, kwargs)\n        return_type = \"state\" if return_state else \"future\"\n        flow_run_context = FlowRunContext.get()\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            raise VisualizationUnsupportedError(\n                \"`task.submit()` is not currently supported by `flow.visualize()`\"\n            )\n\n        if PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING and not flow_run_context:\n            create_autonomous_task_run_call = create_call(\n                create_autonomous_task_run, task=self, parameters=parameters\n            )\n            if self.isasync:\n                return from_async.wait_for_call_in_loop_thread(\n                    create_autonomous_task_run_call\n                )\n            else:\n                return from_sync.wait_for_call_in_loop_thread(\n                    create_autonomous_task_run_call\n                )\n        if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE and flow_run_context:\n            if self.isasync:\n                return self._submit_async(\n                    parameters=parameters,\n                    flow_run_context=flow_run_context,\n                    wait_for=wait_for,\n                    return_state=return_state,\n                )\n            else:\n                raise NotImplementedError(\n                    \"Submitting sync tasks with the new engine has not be implemented yet.\"\n                )\n\n        else:\n            return enter_task_run_engine(\n                self,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=return_type,\n                task_runner=None,  # Use the flow's task runner\n                mapped=False,\n            )\n\n    async def _submit_async(\n        self,\n        parameters: Dict[str, Any],\n        flow_run_context: FlowRunContext,\n        wait_for: Optional[Iterable[PrefectFuture]],\n        return_state: bool,\n    ):\n        from prefect.new_task_engine import run_task_async\n\n        task_runner = flow_run_context.task_runner\n\n        task_run = await self.create_run(\n            client=flow_run_context.client,\n            flow_run_context=flow_run_context,\n            parameters=parameters,\n            wait_for=wait_for,\n        )\n\n        future = PrefectFuture(\n            name=task_run.name,\n            key=uuid4(),\n            task_runner=task_runner,\n            asynchronous=(self.isasync and flow_run_context.flow.isasync),\n        )\n        future.task_run = task_run\n        flow_run_context.task_run_futures.append(future)\n        await task_runner.submit(\n            key=future.key,\n            call=partial(\n                run_task_async,\n                task=self,\n                task_run=task_run,\n                parameters=parameters,\n                wait_for=wait_for,\n                return_type=\"state\",\n            ),\n        )\n        # TODO: I don't like this. Can we move responsibility for creating the future\n        # and setting this anyio.Event to the task runner?\n        future._submitted.set()\n\n        if return_state:\n            return await future.wait()\n        else:\n            return future\n\n    @overload\n    def map(\n        self: \"Task[P, NoReturn]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; List[PrefectFuture[None, Sync]]:\n        # `NoReturn` matches if a type can't be inferred for the function which stops a\n        # sync function from matching the `Coroutine` overload\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, Coroutine[Any, Any, T]]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; Awaitable[List[PrefectFuture[T, Async]]]:\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        **kwargs: P.kwargs,\n    ) -&gt; List[PrefectFuture[T, Sync]]:\n        ...\n\n    @overload\n    def map(\n        self: \"Task[P, T]\",\n        *args: P.args,\n        return_state: Literal[True],\n        **kwargs: P.kwargs,\n    ) -&gt; List[State[T]]:\n        ...\n\n    def map(\n        self,\n        *args: Any,\n        return_state: bool = False,\n        wait_for: Optional[Iterable[PrefectFuture]] = None,\n        **kwargs: Any,\n    ) -&gt; Any:\n        \"\"\"\n        Submit a mapped run of the task to a worker.\n\n        Must be called within a flow function. If writing an async task, this\n        call must be awaited.\n\n        Must be called with at least one iterable and all iterables must be\n        the same length. Any arguments that are not iterable will be treated as\n        a static value and each task run will receive the same value.\n\n        Will create as many task runs as the length of the iterable(s) in the\n        backing API and submit the task runs to the flow's task runner. This\n        call blocks if given a future as input while the future is resolved. It\n        also blocks while the tasks are being submitted, once they are\n        submitted, the flow function will continue executing. However, note\n        that the `SequentialTaskRunner` does not implement parallel execution\n        for sync tasks and they are fully resolved on submission.\n\n        Args:\n            *args: Iterable and static arguments to run the tasks with\n            return_state: Return a list of Prefect States that wrap the results\n                of each task run.\n            wait_for: Upstream task futures to wait for before starting the\n                task\n            **kwargs: Keyword iterable arguments to run the task with\n\n        Returns:\n            A list of futures allowing asynchronous access to the state of the\n            tasks\n\n        Examples:\n\n            Define a task\n\n            &gt;&gt;&gt; from prefect import task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task(x):\n            &gt;&gt;&gt;     return x + 1\n\n            Create mapped tasks\n\n            &gt;&gt;&gt; from prefect import flow\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     my_task.map([1, 2, 3])\n\n            Wait for all mapped tasks to finish\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n            &gt;&gt;&gt;     for future in futures:\n            &gt;&gt;&gt;         future.wait()\n            &gt;&gt;&gt;     # Now all of the mapped tasks have finished\n            &gt;&gt;&gt;     my_task(10)\n\n            Use the result from mapped tasks in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n            &gt;&gt;&gt;     for future in futures:\n            &gt;&gt;&gt;         print(future.result())\n            &gt;&gt;&gt; my_flow()\n            2\n            3\n            4\n\n            Enforce ordering between tasks that do not exchange data\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_1(x):\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def task_2(y):\n            &gt;&gt;&gt;     pass\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     x = task_1.submit()\n            &gt;&gt;&gt;\n            &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n            &gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\n            Use a non-iterable input as a constant across mapped tasks\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def display(prefix, item):\n            &gt;&gt;&gt;    print(prefix, item)\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            Check it out: 1\n            Check it out: 2\n            Check it out: 3\n\n            Use `unmapped` to treat an iterable argument as a constant\n            &gt;&gt;&gt; from prefect import unmapped\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def add_n_to_items(items, n):\n            &gt;&gt;&gt;     return [item + n for item in items]\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n            &gt;&gt;&gt;\n            &gt;&gt;&gt; my_flow()\n            [[11, 21], [12, 22], [13, 23]]\n        \"\"\"\n\n        from prefect.engine import begin_task_map, enter_task_run_engine\n\n        # Convert the call args/kwargs to a parameter dict; do not apply defaults\n        # since they should not be mapped over\n        parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)\n        return_type = \"state\" if return_state else \"future\"\n\n        task_viz_tracker = get_task_viz_tracker()\n        if task_viz_tracker:\n            raise VisualizationUnsupportedError(\n                \"`task.map()` is not currently supported by `flow.visualize()`\"\n            )\n\n        if (\n            PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n            and not FlowRunContext.get()\n        ):\n            map_call = create_call(\n                begin_task_map,\n                task=self,\n                parameters=parameters,\n                flow_run_context=None,\n                wait_for=wait_for,\n                return_type=return_type,\n                task_runner=None,\n                autonomous=True,\n            )\n            if self.isasync:\n                return from_async.wait_for_call_in_loop_thread(map_call)\n            else:\n                return from_sync.wait_for_call_in_loop_thread(map_call)\n\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,\n            mapped=True,\n        )\n\n    def serve(self, task_runner: Optional[BaseTaskRunner] = None) -&gt; \"Task\":\n        \"\"\"Serve the task using the provided task runner. This method is used to\n        establish a websocket connection with the Prefect server and listen for\n        submitted task runs to execute.\n\n        Args:\n            task_runner: The task runner to use for serving the task. If not provided,\n                the default ConcurrentTaskRunner will be used.\n\n        Examples:\n            Serve a task using the default task runner\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task():\n            &gt;&gt;&gt;     return 1\n\n            &gt;&gt;&gt; my_task.serve()\n        \"\"\"\n\n        if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING:\n            raise ValueError(\n                \"Task's `serve` method is an experimental feature and must be enabled with \"\n                \"`prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=True`\"\n            )\n\n        from prefect.task_server import serve\n\n        serve(self, task_runner=task_runner)\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.map","title":"<code>map</code>","text":"<p>Submit a mapped run of the task to a worker.</p> <p>Must be called within a flow function. If writing an async task, this call must be awaited.</p> <p>Must be called with at least one iterable and all iterables must be the same length. Any arguments that are not iterable will be treated as a static value and each task run will receive the same value.</p> <p>Will create as many task runs as the length of the iterable(s) in the backing API and submit the task runs to the flow's task runner. This call blocks if given a future as input while the future is resolved. It also blocks while the tasks are being submitted, once they are submitted, the flow function will continue executing. However, note that the <code>SequentialTaskRunner</code> does not implement parallel execution for sync tasks and they are fully resolved on submission.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Iterable and static arguments to run the tasks with</p> <code>()</code> <code>return_state</code> <code>bool</code> <p>Return a list of Prefect States that wrap the results of each task run.</p> <code>False</code> <code>wait_for</code> <code>Optional[Iterable[PrefectFuture]]</code> <p>Upstream task futures to wait for before starting the task</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Keyword iterable arguments to run the task with</p> <code>{}</code> <p>Returns:</p> Type Description <code>Any</code> <p>A list of futures allowing asynchronous access to the state of the</p> <code>Any</code> <p>tasks</p> <pre><code>Define a task\n\n&gt;&gt;&gt; from prefect import task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task(x):\n&gt;&gt;&gt;     return x + 1\n\nCreate mapped tasks\n\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.map([1, 2, 3])\n\nWait for all mapped tasks to finish\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n&gt;&gt;&gt;     for future in futures:\n&gt;&gt;&gt;         future.wait()\n&gt;&gt;&gt;     # Now all of the mapped tasks have finished\n&gt;&gt;&gt;     my_task(10)\n\nUse the result from mapped tasks in a flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n&gt;&gt;&gt;     for future in futures:\n&gt;&gt;&gt;         print(future.result())\n&gt;&gt;&gt; my_flow()\n2\n3\n4\n\nEnforce ordering between tasks that do not exchange data\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_1(x):\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_2(y):\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     x = task_1.submit()\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n&gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\nUse a non-iterable input as a constant across mapped tasks\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def display(prefix, item):\n&gt;&gt;&gt;    print(prefix, item)\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\nCheck it out: 1\nCheck it out: 2\nCheck it out: 3\n\nUse `unmapped` to treat an iterable argument as a constant\n&gt;&gt;&gt; from prefect import unmapped\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def add_n_to_items(items, n):\n&gt;&gt;&gt;     return [item + n for item in items]\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\n[[11, 21], [12, 22], [13, 23]]\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def map(\n    self,\n    *args: Any,\n    return_state: bool = False,\n    wait_for: Optional[Iterable[PrefectFuture]] = None,\n    **kwargs: Any,\n) -&gt; Any:\n    \"\"\"\n    Submit a mapped run of the task to a worker.\n\n    Must be called within a flow function. If writing an async task, this\n    call must be awaited.\n\n    Must be called with at least one iterable and all iterables must be\n    the same length. Any arguments that are not iterable will be treated as\n    a static value and each task run will receive the same value.\n\n    Will create as many task runs as the length of the iterable(s) in the\n    backing API and submit the task runs to the flow's task runner. This\n    call blocks if given a future as input while the future is resolved. It\n    also blocks while the tasks are being submitted, once they are\n    submitted, the flow function will continue executing. However, note\n    that the `SequentialTaskRunner` does not implement parallel execution\n    for sync tasks and they are fully resolved on submission.\n\n    Args:\n        *args: Iterable and static arguments to run the tasks with\n        return_state: Return a list of Prefect States that wrap the results\n            of each task run.\n        wait_for: Upstream task futures to wait for before starting the\n            task\n        **kwargs: Keyword iterable arguments to run the task with\n\n    Returns:\n        A list of futures allowing asynchronous access to the state of the\n        tasks\n\n    Examples:\n\n        Define a task\n\n        &gt;&gt;&gt; from prefect import task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task(x):\n        &gt;&gt;&gt;     return x + 1\n\n        Create mapped tasks\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.map([1, 2, 3])\n\n        Wait for all mapped tasks to finish\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n        &gt;&gt;&gt;     for future in futures:\n        &gt;&gt;&gt;         future.wait()\n        &gt;&gt;&gt;     # Now all of the mapped tasks have finished\n        &gt;&gt;&gt;     my_task(10)\n\n        Use the result from mapped tasks in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     futures = my_task.map([1, 2, 3])\n        &gt;&gt;&gt;     for future in futures:\n        &gt;&gt;&gt;         print(future.result())\n        &gt;&gt;&gt; my_flow()\n        2\n        3\n        4\n\n        Enforce ordering between tasks that do not exchange data\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_1(x):\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_2(y):\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     x = task_1.submit()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n        &gt;&gt;&gt;     y = task_2.map([1, 2, 3], wait_for=[x])\n\n        Use a non-iterable input as a constant across mapped tasks\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def display(prefix, item):\n        &gt;&gt;&gt;    print(prefix, item)\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     display.map(\"Check it out: \", [1, 2, 3])\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        Check it out: 1\n        Check it out: 2\n        Check it out: 3\n\n        Use `unmapped` to treat an iterable argument as a constant\n        &gt;&gt;&gt; from prefect import unmapped\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def add_n_to_items(items, n):\n        &gt;&gt;&gt;     return [item + n for item in items]\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        [[11, 21], [12, 22], [13, 23]]\n    \"\"\"\n\n    from prefect.engine import begin_task_map, enter_task_run_engine\n\n    # Convert the call args/kwargs to a parameter dict; do not apply defaults\n    # since they should not be mapped over\n    parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)\n    return_type = \"state\" if return_state else \"future\"\n\n    task_viz_tracker = get_task_viz_tracker()\n    if task_viz_tracker:\n        raise VisualizationUnsupportedError(\n            \"`task.map()` is not currently supported by `flow.visualize()`\"\n        )\n\n    if (\n        PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value()\n        and not FlowRunContext.get()\n    ):\n        map_call = create_call(\n            begin_task_map,\n            task=self,\n            parameters=parameters,\n            flow_run_context=None,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,\n            autonomous=True,\n        )\n        if self.isasync:\n            return from_async.wait_for_call_in_loop_thread(map_call)\n        else:\n            return from_sync.wait_for_call_in_loop_thread(map_call)\n\n    return enter_task_run_engine(\n        self,\n        parameters=parameters,\n        wait_for=wait_for,\n        return_type=return_type,\n        task_runner=None,\n        mapped=True,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.serve","title":"<code>serve</code>","text":"<p>Serve the task using the provided task runner. This method is used to establish a websocket connection with the Prefect server and listen for submitted task runs to execute.</p> <p>Parameters:</p> Name Type Description Default <code>task_runner</code> <code>Optional[BaseTaskRunner]</code> <p>The task runner to use for serving the task. If not provided, the default ConcurrentTaskRunner will be used.</p> <code>None</code> <p>Examples:</p> <p>Serve a task using the default task runner</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n</code></pre> <pre><code>&gt;&gt;&gt; my_task.serve()\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def serve(self, task_runner: Optional[BaseTaskRunner] = None) -&gt; \"Task\":\n    \"\"\"Serve the task using the provided task runner. This method is used to\n    establish a websocket connection with the Prefect server and listen for\n    submitted task runs to execute.\n\n    Args:\n        task_runner: The task runner to use for serving the task. If not provided,\n            the default ConcurrentTaskRunner will be used.\n\n    Examples:\n        Serve a task using the default task runner\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n\n        &gt;&gt;&gt; my_task.serve()\n    \"\"\"\n\n    if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING:\n        raise ValueError(\n            \"Task's `serve` method is an experimental feature and must be enabled with \"\n            \"`prefect config set PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING=True`\"\n        )\n\n    from prefect.task_server import serve\n\n    serve(self, task_runner=task_runner)\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.submit","title":"<code>submit</code>","text":"<p>Submit a run of the task to the engine.</p> <p>If writing an async task, this call must be awaited.</p> <p>If called from within a flow function,</p> <p>Will create a new task run in the backing API and submit the task to the flow's task runner. This call only blocks execution while the task is being submitted, once it is submitted, the flow function will continue executing. However, note that the <code>SequentialTaskRunner</code> does not implement parallel execution for sync tasks and they are fully resolved on submission.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Arguments to run the task with</p> <code>()</code> <code>return_state</code> <code>bool</code> <p>Return the result of the flow run wrapped in a Prefect State.</p> <code>False</code> <code>wait_for</code> <code>Optional[Iterable[PrefectFuture]]</code> <p>Upstream task futures to wait for before starting the task</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Keyword arguments to run the task with</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]</code> <p>If <code>return_state</code> is False a future allowing asynchronous access to the state of the task</p> <code>Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]</code> <p>If <code>return_state</code> is True a future wrapped in a Prefect State allowing asynchronous access to the state of the task</p> <pre><code>Define a task\n\n&gt;&gt;&gt; from prefect import task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return \"hello\"\n\nRun a task in a flow\n\n&gt;&gt;&gt; from prefect import flow\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.submit()\n\nWait for a task to finish\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     my_task.submit().wait()\n\nUse the result from a task in a flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     print(my_task.submit().result())\n&gt;&gt;&gt;\n&gt;&gt;&gt; my_flow()\nhello\n\nRun an async task in an async flow\n\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; async def my_async_task():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     await my_async_task.submit()\n\nRun a sync task in an async flow\n\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     my_task.submit()\n\nEnforce ordering between tasks that do not exchange data\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_1():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def task_2():\n&gt;&gt;&gt;     pass\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     x = task_1.submit()\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n&gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def submit(\n    self,\n    *args: Any,\n    return_state: bool = False,\n    wait_for: Optional[Iterable[PrefectFuture]] = None,\n    **kwargs: Any,\n) -&gt; Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun, Awaitable[TaskRun]]:\n    \"\"\"\n    Submit a run of the task to the engine.\n\n    If writing an async task, this call must be awaited.\n\n    If called from within a flow function,\n\n    Will create a new task run in the backing API and submit the task to the flow's\n    task runner. This call only blocks execution while the task is being submitted,\n    once it is submitted, the flow function will continue executing. However, note\n    that the `SequentialTaskRunner` does not implement parallel execution for sync tasks\n    and they are fully resolved on submission.\n\n    Args:\n        *args: Arguments to run the task with\n        return_state: Return the result of the flow run wrapped in a\n            Prefect State.\n        wait_for: Upstream task futures to wait for before starting the task\n        **kwargs: Keyword arguments to run the task with\n\n    Returns:\n        If `return_state` is False a future allowing asynchronous access to\n            the state of the task\n        If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to\n            the state of the task\n\n    Examples:\n\n        Define a task\n\n        &gt;&gt;&gt; from prefect import task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return \"hello\"\n\n        Run a task in a flow\n\n        &gt;&gt;&gt; from prefect import flow\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.submit()\n\n        Wait for a task to finish\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     my_task.submit().wait()\n\n        Use the result from a task in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     print(my_task.submit().result())\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; my_flow()\n        hello\n\n        Run an async task in an async flow\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; async def my_async_task():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     await my_async_task.submit()\n\n        Run a sync task in an async flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     my_task.submit()\n\n        Enforce ordering between tasks that do not exchange data\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_1():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def task_2():\n        &gt;&gt;&gt;     pass\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     x = task_1.submit()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # task 2 will wait for task_1 to complete\n        &gt;&gt;&gt;     y = task_2.submit(wait_for=[x])\n\n    \"\"\"\n\n    from prefect.engine import create_autonomous_task_run, enter_task_run_engine\n\n    # Convert the call args/kwargs to a parameter dict\n    parameters = get_call_parameters(self.fn, args, kwargs)\n    return_type = \"state\" if return_state else \"future\"\n    flow_run_context = FlowRunContext.get()\n\n    task_viz_tracker = get_task_viz_tracker()\n    if task_viz_tracker:\n        raise VisualizationUnsupportedError(\n            \"`task.submit()` is not currently supported by `flow.visualize()`\"\n        )\n\n    if PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING and not flow_run_context:\n        create_autonomous_task_run_call = create_call(\n            create_autonomous_task_run, task=self, parameters=parameters\n        )\n        if self.isasync:\n            return from_async.wait_for_call_in_loop_thread(\n                create_autonomous_task_run_call\n            )\n        else:\n            return from_sync.wait_for_call_in_loop_thread(\n                create_autonomous_task_run_call\n            )\n    if PREFECT_EXPERIMENTAL_ENABLE_NEW_ENGINE and flow_run_context:\n        if self.isasync:\n            return self._submit_async(\n                parameters=parameters,\n                flow_run_context=flow_run_context,\n                wait_for=wait_for,\n                return_state=return_state,\n            )\n        else:\n            raise NotImplementedError(\n                \"Submitting sync tasks with the new engine has not be implemented yet.\"\n            )\n\n    else:\n        return enter_task_run_engine(\n            self,\n            parameters=parameters,\n            wait_for=wait_for,\n            return_type=return_type,\n            task_runner=None,  # Use the flow's task runner\n            mapped=False,\n        )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.Task.with_options","title":"<code>with_options</code>","text":"<p>Create a new task from the current object, updating provided options.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A new name for the task.</p> <code>None</code> <code>description</code> <code>str</code> <p>A new description for the task.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>A new set of tags for the task. If given, existing tags are ignored, not merged.</p> <code>None</code> <code>cache_key_fn</code> <code>Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]</code> <p>A new cache key function for the task.</p> <code>None</code> <code>cache_expiration</code> <code>timedelta</code> <p>A new cache expiration time for the task.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>Optional[int]</code> <p>A new number of times to retry on task run failure.</p> <code>NotSet</code> <code>retry_delay_seconds</code> <code>Union[float, int, List[float], Callable[[int], List[float]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>NotSet</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>NotSet</code> <code>persist_result</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling result persistence.</p> <code>NotSet</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>A new storage type to use for results.</p> <code>NotSet</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>A new serializer to use for results.</p> <code>NotSet</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>A new key for the persisted result to be stored at.</p> <code>NotSet</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>A new maximum time for the task to complete in seconds.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling redirection of <code>print</code> statements.</p> <code>NotSet</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>A new option for enabling or disabling cache refresh.</p> <code>NotSet</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], Union[Awaitable[None], None]]]]</code> <p>A new list of callables to run when the task enters a completed state.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], Union[Awaitable[None], None]]]]</code> <p>A new list of callables to run when the task enters a failed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy, and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Optional[Any]</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> <p>Returns:</p> Type Description <p>A new <code>Task</code> instance.</p> <pre><code>Create a new task from an existing task and update the name\n\n&gt;&gt;&gt; @task(name=\"My task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\nCreate a new task from an existing task and update the retry settings\n\n&gt;&gt;&gt; from random import randint\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     x = randint(0, 5)\n&gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n&gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n&gt;&gt;&gt;     return x\n&gt;&gt;&gt;\n&gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\nUse a task with updated options within a flow\n\n&gt;&gt;&gt; @task(name=\"My task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return 1\n&gt;&gt;&gt;\n&gt;&gt;&gt; @flow\n&gt;&gt;&gt; my_flow():\n&gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n&gt;&gt;&gt;     new_task()\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def with_options(\n    self,\n    *,\n    name: str = None,\n    description: str = None,\n    tags: Iterable[str] = None,\n    cache_key_fn: Callable[\n        [\"TaskRunContext\", Dict[str, Any]], Optional[str]\n    ] = None,\n    task_run_name: Optional[Union[Callable[[], str], str]] = None,\n    cache_expiration: datetime.timedelta = None,\n    retries: Optional[int] = NotSet,\n    retry_delay_seconds: Union[\n        float,\n        int,\n        List[float],\n        Callable[[int], List[float]],\n    ] = NotSet,\n    retry_jitter_factor: Optional[float] = NotSet,\n    persist_result: Optional[bool] = NotSet,\n    result_storage: Optional[ResultStorage] = NotSet,\n    result_serializer: Optional[ResultSerializer] = NotSet,\n    result_storage_key: Optional[str] = NotSet,\n    cache_result_in_memory: Optional[bool] = None,\n    timeout_seconds: Union[int, float] = None,\n    log_prints: Optional[bool] = NotSet,\n    refresh_cache: Optional[bool] = NotSet,\n    on_completion: Optional[\n        List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    on_failure: Optional[\n        List[Callable[[\"Task\", TaskRun, State], Union[Awaitable[None], None]]]\n    ] = None,\n    retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n    viz_return_value: Optional[Any] = None,\n):\n    \"\"\"\n    Create a new task from the current object, updating provided options.\n\n    Args:\n        name: A new name for the task.\n        description: A new description for the task.\n        tags: A new set of tags for the task. If given, existing tags are ignored,\n            not merged.\n        cache_key_fn: A new cache key function for the task.\n        cache_expiration: A new cache expiration time for the task.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: A new number of times to retry on task run failure.\n        retry_delay_seconds: Optionally configures how long to wait before retrying\n            the task after failure. This is only applicable if `retries` is nonzero.\n            This setting can either be a number of seconds, a list of retry delays,\n            or a callable that, given the total number of retries, generates a list\n            of retry delays. If a number of seconds, that delay will be applied to\n            all retries. If a list, each retry will wait for the corresponding delay\n            before retrying. When passing a callable or a list, the number of\n            configured retry delays cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a\n            retry can be jittered in order to avoid a \"thundering herd\".\n        persist_result: A new option for enabling or disabling result persistence.\n        result_storage: A new storage type to use for results.\n        result_serializer: A new serializer to use for results.\n        result_storage_key: A new key for the persisted result to be stored at.\n        timeout_seconds: A new maximum time for the task to complete in seconds.\n        log_prints: A new option for enabling or disabling redirection of `print` statements.\n        refresh_cache: A new option for enabling or disabling cache refresh.\n        on_completion: A new list of callables to run when the task enters a completed state.\n        on_failure: A new list of callables to run when the task enters a failed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state.\n            Should return `True` if the task should continue to its retry policy, and `False`\n            if the task should end as failed. Defaults to `None`, indicating the task should\n            always continue to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n    Returns:\n        A new `Task` instance.\n\n    Examples:\n\n        Create a new task from an existing task and update the name\n\n        &gt;&gt;&gt; @task(name=\"My task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_task = my_task.with_options(name=\"My new task\")\n\n        Create a new task from an existing task and update the retry settings\n\n        &gt;&gt;&gt; from random import randint\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(retries=1, retry_delay_seconds=5)\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     x = randint(0, 5)\n        &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n        &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n        &gt;&gt;&gt;     return x\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; new_task = my_task.with_options(retries=5, retry_delay_seconds=2)\n\n        Use a task with updated options within a flow\n\n        &gt;&gt;&gt; @task(name=\"My task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return 1\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; my_flow():\n        &gt;&gt;&gt;     new_task = my_task.with_options(name=\"My new task\")\n        &gt;&gt;&gt;     new_task()\n    \"\"\"\n    return Task(\n        fn=self.fn,\n        name=name or self.name,\n        description=description or self.description,\n        tags=tags or copy(self.tags),\n        cache_key_fn=cache_key_fn or self.cache_key_fn,\n        cache_expiration=cache_expiration or self.cache_expiration,\n        task_run_name=task_run_name,\n        retries=retries if retries is not NotSet else self.retries,\n        retry_delay_seconds=(\n            retry_delay_seconds\n            if retry_delay_seconds is not NotSet\n            else self.retry_delay_seconds\n        ),\n        retry_jitter_factor=(\n            retry_jitter_factor\n            if retry_jitter_factor is not NotSet\n            else self.retry_jitter_factor\n        ),\n        persist_result=(\n            persist_result if persist_result is not NotSet else self.persist_result\n        ),\n        result_storage=(\n            result_storage if result_storage is not NotSet else self.result_storage\n        ),\n        result_storage_key=(\n            result_storage_key\n            if result_storage_key is not NotSet\n            else self.result_storage_key\n        ),\n        result_serializer=(\n            result_serializer\n            if result_serializer is not NotSet\n            else self.result_serializer\n        ),\n        cache_result_in_memory=(\n            cache_result_in_memory\n            if cache_result_in_memory is not None\n            else self.cache_result_in_memory\n        ),\n        timeout_seconds=(\n            timeout_seconds if timeout_seconds is not None else self.timeout_seconds\n        ),\n        log_prints=(log_prints if log_prints is not NotSet else self.log_prints),\n        refresh_cache=(\n            refresh_cache if refresh_cache is not NotSet else self.refresh_cache\n        ),\n        on_completion=on_completion or self.on_completion,\n        on_failure=on_failure or self.on_failure,\n        retry_condition_fn=retry_condition_fn or self.retry_condition_fn,\n        viz_return_value=viz_return_value or self.viz_return_value,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.exponential_backoff","title":"<code>exponential_backoff</code>","text":"<p>A task retry backoff utility that configures exponential backoff for task retries. The exponential backoff design matches the urllib3 implementation.</p> <p>Parameters:</p> Name Type Description Default <code>backoff_factor</code> <code>float</code> <p>the base delay for the first retry, subsequent retries will increase the delay time by powers of 2.</p> required <p>Returns:</p> Type Description <code>Callable[[int], List[float]]</code> <p>a callable that can be passed to the task constructor</p> Source code in <code>prefect/tasks.py</code> <pre><code>def exponential_backoff(backoff_factor: float) -&gt; Callable[[int], List[float]]:\n    \"\"\"\n    A task retry backoff utility that configures exponential backoff for task retries.\n    The exponential backoff design matches the urllib3 implementation.\n\n    Arguments:\n        backoff_factor: the base delay for the first retry, subsequent retries will\n            increase the delay time by powers of 2.\n\n    Returns:\n        a callable that can be passed to the task constructor\n    \"\"\"\n\n    def retry_backoff_callable(retries: int) -&gt; List[float]:\n        # no more than 50 retry delays can be configured on a task\n        retries = min(retries, 50)\n\n        return [backoff_factor * max(0, 2**r) for r in range(retries)]\n\n    return retry_backoff_callable\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.task","title":"<code>task</code>","text":"<p>Decorator to designate a function as a task in a Prefect workflow.</p> <p>This decorator may be used for asynchronous or synchronous functions.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An optional name for the task; if not provided, the name will be inferred from the given function.</p> <code>None</code> <code>description</code> <code>str</code> <p>An optional string description for the task.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime.</p> <code>None</code> <code>version</code> <code>str</code> <p>An optional string specifying the version of this task definition</p> <code>None</code> <code>cache_key_fn</code> <code>Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]</code> <p>An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.</p> <code>None</code> <code>cache_expiration</code> <code>timedelta</code> <p>An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.</p> <code>None</code> <code>task_run_name</code> <code>Optional[Union[Callable[[], str], str]]</code> <p>An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.</p> <code>None</code> <code>retries</code> <code>int</code> <p>An optional number of times to retry on task run failure</p> <code>None</code> <code>retry_delay_seconds</code> <code>Union[float, int, List[float], Callable[[int], List[float]]]</code> <p>Optionally configures how long to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.</p> <code>None</code> <code>retry_jitter_factor</code> <code>Optional[float]</code> <p>An optional factor that defines the factor to which a retry can be jittered in order to avoid a \"thundering herd\".</p> <code>None</code> <code>persist_result</code> <code>Optional[bool]</code> <p>An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to <code>None</code>, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.</p> <code>None</code> <code>result_storage</code> <code>Optional[ResultStorage]</code> <p>An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>result_storage_key</code> <code>Optional[str]</code> <p>An optional key to store the result in storage at when persisted. Defaults to a unique identifier.</p> <code>None</code> <code>result_serializer</code> <code>Optional[ResultSerializer]</code> <p>An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.</p> <code>None</code> <code>timeout_seconds</code> <code>Union[int, float]</code> <p>An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.</p> <code>None</code> <code>log_prints</code> <code>Optional[bool]</code> <p>If set, <code>print</code> statements in the task will be redirected to the Prefect logger for the task run. Defaults to <code>None</code>, which indicates that the value from the flow should be used.</p> <code>None</code> <code>refresh_cache</code> <code>Optional[bool]</code> <p>If set, cached results for the cache key are not used. Defaults to <code>None</code>, which indicates that a cached result from a previous execution with matching cache key is used.</p> <code>None</code> <code>on_failure</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a failed state.</p> <code>None</code> <code>on_completion</code> <code>Optional[List[Callable[[Task, TaskRun, State], None]]]</code> <p>An optional list of callables to run when the task enters a completed state.</p> <code>None</code> <code>retry_condition_fn</code> <code>Optional[Callable[[Task, TaskRun, State], bool]]</code> <p>An optional callable run when a task run returns a Failed state. Should return <code>True</code> if the task should continue to its retry policy (e.g. <code>retries=3</code>), and <code>False</code> if the task should end as failed. Defaults to <code>None</code>, indicating the task should always continue to its retry policy.</p> <code>None</code> <code>viz_return_value</code> <code>Any</code> <p>An optional value to return when the task dependency tree is visualized.</p> <code>None</code> <p>Returns:</p> Type Description <p>A callable <code>Task</code> object which, when called, will submit the task for execution.</p> <p>Examples:</p> <p>Define a simple task</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define an async task</p> <pre><code>&gt;&gt;&gt; @task\n&gt;&gt;&gt; async def add(x, y):\n&gt;&gt;&gt;     return x + y\n</code></pre> <p>Define a task with tags and a description</p> <pre><code>&gt;&gt;&gt; @task(tags={\"a\", \"b\"}, description=\"This task is empty but its my first!\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a task with a custom name</p> <pre><code>&gt;&gt;&gt; @task(name=\"The Ultimate Task\")\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     pass\n</code></pre> <p>Define a task that retries 3 times with a 5 second delay between attempts</p> <pre><code>&gt;&gt;&gt; from random import randint\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(retries=3, retry_delay_seconds=5)\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     x = randint(0, 5)\n&gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n&gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n&gt;&gt;&gt;     return x\n</code></pre> <p>Define a task that is cached for a day based on its inputs</p> <pre><code>&gt;&gt;&gt; from prefect.tasks import task_input_hash\n&gt;&gt;&gt; from datetime import timedelta\n&gt;&gt;&gt;\n&gt;&gt;&gt; @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\n&gt;&gt;&gt; def my_task():\n&gt;&gt;&gt;     return \"hello\"\n</code></pre> Source code in <code>prefect/tasks.py</code> <pre><code>def task(\n    __fn=None,\n    *,\n    name: str = None,\n    description: str = None,\n    tags: Iterable[str] = None,\n    version: str = None,\n    cache_key_fn: Callable[[\"TaskRunContext\", Dict[str, Any]], Optional[str]] = None,\n    cache_expiration: datetime.timedelta = None,\n    task_run_name: Optional[Union[Callable[[], str], str]] = None,\n    retries: int = None,\n    retry_delay_seconds: Union[\n        float,\n        int,\n        List[float],\n        Callable[[int], List[float]],\n    ] = None,\n    retry_jitter_factor: Optional[float] = None,\n    persist_result: Optional[bool] = None,\n    result_storage: Optional[ResultStorage] = None,\n    result_storage_key: Optional[str] = None,\n    result_serializer: Optional[ResultSerializer] = None,\n    cache_result_in_memory: bool = True,\n    timeout_seconds: Union[int, float] = None,\n    log_prints: Optional[bool] = None,\n    refresh_cache: Optional[bool] = None,\n    on_completion: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n    on_failure: Optional[List[Callable[[\"Task\", TaskRun, State], None]]] = None,\n    retry_condition_fn: Optional[Callable[[\"Task\", TaskRun, State], bool]] = None,\n    viz_return_value: Any = None,\n):\n    \"\"\"\n    Decorator to designate a function as a task in a Prefect workflow.\n\n    This decorator may be used for asynchronous or synchronous functions.\n\n    Args:\n        name: An optional name for the task; if not provided, the name will be inferred\n            from the given function.\n        description: An optional string description for the task.\n        tags: An optional set of tags to be associated with runs of this task. These\n            tags are combined with any tags defined by a `prefect.tags` context at\n            task runtime.\n        version: An optional string specifying the version of this task definition\n        cache_key_fn: An optional callable that, given the task run context and call\n            parameters, generates a string key; if the key matches a previous completed\n            state, that state result will be restored instead of running the task again.\n        cache_expiration: An optional amount of time indicating how long cached states\n            for this task should be restorable; if not provided, cached states will\n            never expire.\n        task_run_name: An optional name to distinguish runs of this task; this name can be provided\n            as a string template with the task's keyword arguments as variables,\n            or a function that returns a string.\n        retries: An optional number of times to retry on task run failure\n        retry_delay_seconds: Optionally configures how long to wait before retrying the\n            task after failure. This is only applicable if `retries` is nonzero. This\n            setting can either be a number of seconds, a list of retry delays, or a\n            callable that, given the total number of retries, generates a list of retry\n            delays. If a number of seconds, that delay will be applied to all retries.\n            If a list, each retry will wait for the corresponding delay before retrying.\n            When passing a callable or a list, the number of configured retry delays\n            cannot exceed 50.\n        retry_jitter_factor: An optional factor that defines the factor to which a retry\n            can be jittered in order to avoid a \"thundering herd\".\n        persist_result: An optional toggle indicating whether the result of this task\n            should be persisted to result storage. Defaults to `None`, which indicates\n            that Prefect should choose whether the result should be persisted depending on\n            the features being used.\n        result_storage: An optional block to use to persist the result of this task.\n            Defaults to the value set in the flow the task is called in.\n        result_storage_key: An optional key to store the result in storage at when persisted.\n            Defaults to a unique identifier.\n        result_serializer: An optional serializer to use to serialize the result of this\n            task for persistence. Defaults to the value set in the flow the task is\n            called in.\n        timeout_seconds: An optional number of seconds indicating a maximum runtime for\n            the task. If the task exceeds this runtime, it will be marked as failed.\n        log_prints: If set, `print` statements in the task will be redirected to the\n            Prefect logger for the task run. Defaults to `None`, which indicates\n            that the value from the flow should be used.\n        refresh_cache: If set, cached results for the cache key are not used.\n            Defaults to `None`, which indicates that a cached result from a previous\n            execution with matching cache key is used.\n        on_failure: An optional list of callables to run when the task enters a failed state.\n        on_completion: An optional list of callables to run when the task enters a completed state.\n        retry_condition_fn: An optional callable run when a task run returns a Failed state. Should\n            return `True` if the task should continue to its retry policy (e.g. `retries=3`), and `False` if the task\n            should end as failed. Defaults to `None`, indicating the task should always continue\n            to its retry policy.\n        viz_return_value: An optional value to return when the task dependency tree is visualized.\n\n    Returns:\n        A callable `Task` object which, when called, will submit the task for execution.\n\n    Examples:\n        Define a simple task\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define an async task\n\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; async def add(x, y):\n        &gt;&gt;&gt;     return x + y\n\n        Define a task with tags and a description\n\n        &gt;&gt;&gt; @task(tags={\"a\", \"b\"}, description=\"This task is empty but its my first!\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Define a task with a custom name\n\n        &gt;&gt;&gt; @task(name=\"The Ultimate Task\")\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     pass\n\n        Define a task that retries 3 times with a 5 second delay between attempts\n\n        &gt;&gt;&gt; from random import randint\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(retries=3, retry_delay_seconds=5)\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     x = randint(0, 5)\n        &gt;&gt;&gt;     if x &gt;= 3:  # Make a task that fails sometimes\n        &gt;&gt;&gt;         raise ValueError(\"Retry me please!\")\n        &gt;&gt;&gt;     return x\n\n        Define a task that is cached for a day based on its inputs\n\n        &gt;&gt;&gt; from prefect.tasks import task_input_hash\n        &gt;&gt;&gt; from datetime import timedelta\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\n        &gt;&gt;&gt; def my_task():\n        &gt;&gt;&gt;     return \"hello\"\n    \"\"\"\n\n    if __fn:\n        return cast(\n            Task[P, R],\n            Task(\n                fn=__fn,\n                name=name,\n                description=description,\n                tags=tags,\n                version=version,\n                cache_key_fn=cache_key_fn,\n                cache_expiration=cache_expiration,\n                task_run_name=task_run_name,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                retry_jitter_factor=retry_jitter_factor,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_storage_key=result_storage_key,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                timeout_seconds=timeout_seconds,\n                log_prints=log_prints,\n                refresh_cache=refresh_cache,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                retry_condition_fn=retry_condition_fn,\n                viz_return_value=viz_return_value,\n            ),\n        )\n    else:\n        return cast(\n            Callable[[Callable[P, R]], Task[P, R]],\n            partial(\n                task,\n                name=name,\n                description=description,\n                tags=tags,\n                version=version,\n                cache_key_fn=cache_key_fn,\n                cache_expiration=cache_expiration,\n                task_run_name=task_run_name,\n                retries=retries,\n                retry_delay_seconds=retry_delay_seconds,\n                retry_jitter_factor=retry_jitter_factor,\n                persist_result=persist_result,\n                result_storage=result_storage,\n                result_storage_key=result_storage_key,\n                result_serializer=result_serializer,\n                cache_result_in_memory=cache_result_in_memory,\n                timeout_seconds=timeout_seconds,\n                log_prints=log_prints,\n                refresh_cache=refresh_cache,\n                on_completion=on_completion,\n                on_failure=on_failure,\n                retry_condition_fn=retry_condition_fn,\n                viz_return_value=viz_return_value,\n            ),\n        )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/tasks/#prefect.tasks.task_input_hash","title":"<code>task_input_hash</code>","text":"<p>A task cache key implementation which hashes all inputs to the task using a JSON or cloudpickle serializer. If any arguments are not JSON serializable, the pickle serializer is used as a fallback. If cloudpickle fails, this will return a null key indicating that a cache key could not be generated for the given inputs.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>TaskRunContext</code> <p>the active <code>TaskRunContext</code></p> required <code>arguments</code> <code>Dict[str, Any]</code> <p>a dictionary of arguments to be passed to the underlying task</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>a string hash if hashing succeeded, else <code>None</code></p> Source code in <code>prefect/tasks.py</code> <pre><code>def task_input_hash(\n    context: \"TaskRunContext\", arguments: Dict[str, Any]\n) -&gt; Optional[str]:\n    \"\"\"\n    A task cache key implementation which hashes all inputs to the task using a JSON or\n    cloudpickle serializer. If any arguments are not JSON serializable, the pickle\n    serializer is used as a fallback. If cloudpickle fails, this will return a null key\n    indicating that a cache key could not be generated for the given inputs.\n\n    Arguments:\n        context: the active `TaskRunContext`\n        arguments: a dictionary of arguments to be passed to the underlying task\n\n    Returns:\n        a string hash if hashing succeeded, else `None`\n    \"\"\"\n    return hash_objects(\n        # We use the task key to get the qualified name for the task and include the\n        # task functions `co_code` bytes to avoid caching when the underlying function\n        # changes\n        context.task.task_key,\n        context.task.fn.__code__.co_code.hex(),\n        arguments,\n    )\n</code></pre>","tags":["Python API","tasks","caching"]},{"location":"api-ref/prefect/testing/","title":"prefect.testing","text":"","tags":["Python API","testing"]},{"location":"api-ref/prefect/testing/#prefect.testing","title":"<code>prefect.testing</code>","text":"","tags":["Python API","testing"]},{"location":"api-ref/prefect/variables/","title":"prefect.variables","text":"","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables","title":"<code>prefect.variables</code>","text":"","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable","title":"<code>Variable</code>","text":"<p>               Bases: <code>VariableCreate</code></p> <p>Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud. https://docs.prefect.io/latest/concepts/variables/</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <p>A string identifying the variable.</p> required <code>value</code> <p>A string that is the value of the variable.</p> required <code>tags</code> <p>An optional list of strings to associate with the variable.</p> required Source code in <code>prefect/variables.py</code> <pre><code>class Variable(VariableRequest):\n    \"\"\"\n    Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.\n    https://docs.prefect.io/latest/concepts/variables/\n\n    Arguments:\n        name: A string identifying the variable.\n        value: A string that is the value of the variable.\n        tags: An optional list of strings to associate with the variable.\n    \"\"\"\n\n    @classmethod\n    @sync_compatible\n    async def set(\n        cls,\n        name: str,\n        value: str,\n        tags: Optional[List[str]] = None,\n        overwrite: bool = False,\n    ) -&gt; Optional[\"Variable\"]:\n        \"\"\"\n        Sets a new variable. If one exists with the same name, user must pass `overwrite=True`\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            def my_flow():\n                var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n        ```\n        or\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            async def my_flow():\n                var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n        ```\n        \"\"\"\n        client, _ = get_or_create_client()\n        variable = await client.read_variable_by_name(name)\n        var_dict = {\"name\": name, \"value\": value, \"tags\": tags or []}\n        if variable:\n            if not overwrite:\n                raise ValueError(\n                    \"You are attempting to save a variable with a name that is already in use. If you would like to overwrite the values that are saved, then call .set with `overwrite=True`.\"\n                )\n            var = VariableUpdateRequest(**var_dict)\n            await client.update_variable(variable=var)\n            variable = await client.read_variable_by_name(name)\n        else:\n            var = VariableRequest(**var_dict)\n            variable = await client.create_variable(variable=var)\n\n        return variable if variable else None\n\n    @classmethod\n    @sync_compatible\n    async def get(\n        cls, name: str, default: Optional[str] = None\n    ) -&gt; Optional[Union[\"Variable\", str]]:\n        \"\"\"\n        Get a variable by name. If doesn't exist return the default.\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            def my_flow():\n                var = Variable.get(\"my_var\")\n        ```\n        or\n        ```\n            from prefect.variables import Variable\n\n            @flow\n            async def my_flow():\n                var = await Variable.get(\"my_var\")\n        ```\n        \"\"\"\n        client, _ = get_or_create_client()\n        variable = await client.read_variable_by_name(name)\n\n        return (\n            Variable(name=variable.name, value=variable.value, tags=variable.tags)\n            if variable\n            else default\n        )\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable.get","title":"<code>get</code>  <code>async</code> <code>classmethod</code>","text":"<p>Get a variable by name. If doesn't exist return the default. <pre><code>    from prefect.variables import Variable\n\n    @flow\n    def my_flow():\n        var = Variable.get(\"my_var\")\n</code></pre> or <pre><code>    from prefect.variables import Variable\n\n    @flow\n    async def my_flow():\n        var = await Variable.get(\"my_var\")\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def get(\n    cls, name: str, default: Optional[str] = None\n) -&gt; Optional[Union[\"Variable\", str]]:\n    \"\"\"\n    Get a variable by name. If doesn't exist return the default.\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        def my_flow():\n            var = Variable.get(\"my_var\")\n    ```\n    or\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        async def my_flow():\n            var = await Variable.get(\"my_var\")\n    ```\n    \"\"\"\n    client, _ = get_or_create_client()\n    variable = await client.read_variable_by_name(name)\n\n    return (\n        Variable(name=variable.name, value=variable.value, tags=variable.tags)\n        if variable\n        else default\n    )\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.Variable.set","title":"<code>set</code>  <code>async</code> <code>classmethod</code>","text":"<p>Sets a new variable. If one exists with the same name, user must pass <code>overwrite=True</code> <pre><code>    from prefect.variables import Variable\n\n    @flow\n    def my_flow():\n        var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n</code></pre> or <pre><code>    from prefect.variables import Variable\n\n    @flow\n    async def my_flow():\n        var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def set(\n    cls,\n    name: str,\n    value: str,\n    tags: Optional[List[str]] = None,\n    overwrite: bool = False,\n) -&gt; Optional[\"Variable\"]:\n    \"\"\"\n    Sets a new variable. If one exists with the same name, user must pass `overwrite=True`\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        def my_flow():\n            var = Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n    ```\n    or\n    ```\n        from prefect.variables import Variable\n\n        @flow\n        async def my_flow():\n            var = await Variable.set(name=\"my_var\",value=\"test_value\", tags=[\"hi\", \"there\"], overwrite=True)\n    ```\n    \"\"\"\n    client, _ = get_or_create_client()\n    variable = await client.read_variable_by_name(name)\n    var_dict = {\"name\": name, \"value\": value, \"tags\": tags or []}\n    if variable:\n        if not overwrite:\n            raise ValueError(\n                \"You are attempting to save a variable with a name that is already in use. If you would like to overwrite the values that are saved, then call .set with `overwrite=True`.\"\n            )\n        var = VariableUpdateRequest(**var_dict)\n        await client.update_variable(variable=var)\n        variable = await client.read_variable_by_name(name)\n    else:\n        var = VariableRequest(**var_dict)\n        variable = await client.create_variable(variable=var)\n\n    return variable if variable else None\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/variables/#prefect.variables.get","title":"<code>get</code>  <code>async</code>","text":"<p>Get a variable by name. If doesn't exist return the default. <pre><code>    from prefect import variables\n\n    @flow\n    def my_flow():\n        var = variables.get(\"my_var\")\n</code></pre> or <pre><code>    from prefect import variables\n\n    @flow\n    async def my_flow():\n        var = await variables.get(\"my_var\")\n</code></pre></p> Source code in <code>prefect/variables.py</code> <pre><code>@deprecated_callable(start_date=\"Apr 2024\")\n@sync_compatible\nasync def get(name: str, default: Optional[str] = None) -&gt; Optional[str]:\n    \"\"\"\n    Get a variable by name. If doesn't exist return the default.\n    ```\n        from prefect import variables\n\n        @flow\n        def my_flow():\n            var = variables.get(\"my_var\")\n    ```\n    or\n    ```\n        from prefect import variables\n\n        @flow\n        async def my_flow():\n            var = await variables.get(\"my_var\")\n    ```\n    \"\"\"\n    variable = await Variable.get(name, default=default)\n    if isinstance(variable, Variable):\n        variable = variable.value\n    return variable\n</code></pre>","tags":["Python API","variables"]},{"location":"api-ref/prefect/blocks/core/","title":"core","text":"","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core","title":"<code>prefect.blocks.core</code>","text":"","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block","title":"<code>Block</code>","text":"<p>               Bases: <code>BaseModel</code>, <code>ABC</code></p> <p>A base class for implementing a block that wraps an external service.</p> <p>This class can be defined with an arbitrary set of fields and methods, and couples business logic with data contained in an block document. <code>_block_document_name</code>, <code>_block_document_id</code>, <code>_block_schema_id</code>, and <code>_block_type_id</code> are reserved by Prefect as Block metadata fields, but otherwise a Block can implement arbitrary logic. Blocks can be instantiated without populating these metadata fields, but can only be used interactively, not with the Prefect API.</p> <p>Instead of the init method, a block implementation allows the definition of a <code>block_initialization</code> method that is called after initialization.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@register_base_type\n@instrument_method_calls_on_class_instances\nclass Block(BaseModel, ABC):\n    \"\"\"\n    A base class for implementing a block that wraps an external service.\n\n    This class can be defined with an arbitrary set of fields and methods, and\n    couples business logic with data contained in an block document.\n    `_block_document_name`, `_block_document_id`, `_block_schema_id`, and\n    `_block_type_id` are reserved by Prefect as Block metadata fields, but\n    otherwise a Block can implement arbitrary logic. Blocks can be instantiated\n    without populating these metadata fields, but can only be used interactively,\n    not with the Prefect API.\n\n    Instead of the __init__ method, a block implementation allows the\n    definition of a `block_initialization` method that is called after\n    initialization.\n    \"\"\"\n\n    class Config:\n        extra = \"allow\"\n\n        json_encoders = {SecretDict: lambda v: v.dict()}\n\n        @staticmethod\n        def schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n            \"\"\"\n            Customizes Pydantic's schema generation feature to add blocks related information.\n            \"\"\"\n            schema[\"block_type_slug\"] = model.get_block_type_slug()\n            # Ensures args and code examples aren't included in the schema\n            description = model.get_description()\n            if description:\n                schema[\"description\"] = description\n            else:\n                # Prevent the description of the base class from being included in the schema\n                schema.pop(\"description\", None)\n\n            # create a list of secret field names\n            # secret fields include both top-level keys and dot-delimited nested secret keys\n            # A wildcard (*) means that all fields under a given key are secret.\n            # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n            # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n            # nested under the \"child\" key are all secret. There is no limit to nesting.\n            secrets = schema[\"secret_fields\"] = []\n            for field in model.__fields__.values():\n                _collect_secret_fields(field.name, field.type_, secrets)\n\n            # create block schema references\n            refs = schema[\"block_schema_references\"] = {}\n\n            def collect_block_schema_references(\n                field_name: str, annotation: type\n            ) -&gt; None:\n                \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n                if Block.is_block_class(annotation):\n                    if isinstance(refs.get(field_name), list):\n                        refs[field_name].append(\n                            annotation._to_block_schema_reference_dict()\n                        )\n                    elif isinstance(refs.get(field_name), dict):\n                        refs[field_name] = [\n                            refs[field_name],\n                            annotation._to_block_schema_reference_dict(),\n                        ]\n                    else:\n                        refs[field_name] = annotation._to_block_schema_reference_dict()\n                if get_origin(annotation) in (Union, list, tuple, dict):\n                    for type_ in get_args(annotation):\n                        collect_block_schema_references(field_name, type_)\n\n            for field in model.__fields__.values():\n                collect_block_schema_references(field.name, field.type_)\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.block_initialization()\n\n    def __str__(self) -&gt; str:\n        return self.__repr__()\n\n    def __repr_args__(self):\n        repr_args = super().__repr_args__()\n        data_keys = self.schema()[\"properties\"].keys()\n        return [\n            (key, value) for key, value in repr_args if key is None or key in data_keys\n        ]\n\n    def block_initialization(self) -&gt; None:\n        pass\n\n    # -- private class variables\n    # set by the class itself\n\n    # Attribute to customize the name of the block type created\n    # when the block is registered with the API. If not set, block\n    # type name will default to the class name.\n    _block_type_name: Optional[str] = None\n    _block_type_slug: Optional[str] = None\n\n    # Attributes used to set properties on a block type when registered\n    # with the API.\n    _logo_url: Optional[HttpUrl] = None\n    _documentation_url: Optional[HttpUrl] = None\n    _description: Optional[str] = None\n    _code_example: Optional[str] = None\n\n    # -- private instance variables\n    # these are set when blocks are loaded from the API\n    _block_type_id: Optional[UUID] = None\n    _block_schema_id: Optional[UUID] = None\n    _block_schema_capabilities: Optional[List[str]] = None\n    _block_schema_version: Optional[str] = None\n    _block_document_id: Optional[UUID] = None\n    _block_document_name: Optional[str] = None\n    _is_anonymous: Optional[bool] = None\n\n    # Exclude `save` as it uses the `sync_compatible` decorator and needs to be\n    # decorated directly.\n    _events_excluded_methods = [\"block_initialization\", \"save\", \"dict\"]\n\n    @classmethod\n    def __dispatch_key__(cls):\n        if cls.__name__ == \"Block\":\n            return None  # The base class is abstract\n        return block_schema_to_key(cls._to_block_schema())\n\n    @classmethod\n    def get_block_type_name(cls):\n        return cls._block_type_name or cls.__name__\n\n    @classmethod\n    def get_block_type_slug(cls):\n        return slugify(cls._block_type_slug or cls.get_block_type_name())\n\n    @classmethod\n    def get_block_capabilities(cls) -&gt; FrozenSet[str]:\n        \"\"\"\n        Returns the block capabilities for this Block. Recursively collects all block\n        capabilities of all parent classes into a single frozenset.\n        \"\"\"\n        return frozenset(\n            {\n                c\n                for base in (cls,) + cls.__mro__\n                for c in getattr(base, \"_block_schema_capabilities\", []) or []\n            }\n        )\n\n    @classmethod\n    def _get_current_package_version(cls):\n        current_module = inspect.getmodule(cls)\n        if current_module:\n            top_level_module = sys.modules[\n                current_module.__name__.split(\".\")[0] or \"__main__\"\n            ]\n            try:\n                version = Version(top_level_module.__version__)\n                # Strips off any local version information\n                return version.base_version\n            except (AttributeError, InvalidVersion):\n                # Module does not have a __version__ attribute or is not a parsable format\n                pass\n        return DEFAULT_BLOCK_SCHEMA_VERSION\n\n    @classmethod\n    def get_block_schema_version(cls) -&gt; str:\n        return cls._block_schema_version or cls._get_current_package_version()\n\n    @classmethod\n    def _to_block_schema_reference_dict(cls):\n        return dict(\n            block_type_slug=cls.get_block_type_slug(),\n            block_schema_checksum=cls._calculate_schema_checksum(),\n        )\n\n    @classmethod\n    def _calculate_schema_checksum(\n        cls, block_schema_fields: Optional[Dict[str, Any]] = None\n    ):\n        \"\"\"\n        Generates a unique hash for the underlying schema of block.\n\n        Args:\n            block_schema_fields: Dictionary detailing block schema fields to generate a\n                checksum for. The fields of the current class is used if this parameter\n                is not provided.\n\n        Returns:\n            str: The calculated checksum prefixed with the hashing algorithm used.\n        \"\"\"\n        block_schema_fields = (\n            cls.schema() if block_schema_fields is None else block_schema_fields\n        )\n        fields_for_checksum = remove_nested_keys([\"secret_fields\"], block_schema_fields)\n        if fields_for_checksum.get(\"definitions\"):\n            non_block_definitions = _get_non_block_reference_definitions(\n                fields_for_checksum, fields_for_checksum[\"definitions\"]\n            )\n            if non_block_definitions:\n                fields_for_checksum[\"definitions\"] = non_block_definitions\n            else:\n                # Pop off definitions entirely instead of empty dict for consistency\n                # with the OpenAPI specification\n                fields_for_checksum.pop(\"definitions\")\n        checksum = hash_objects(fields_for_checksum, hash_algo=hashlib.sha256)\n        if checksum is None:\n            raise ValueError(\"Unable to compute checksum for block schema\")\n        else:\n            return f\"sha256:{checksum}\"\n\n    def _to_block_document(\n        self,\n        name: Optional[str] = None,\n        block_schema_id: Optional[UUID] = None,\n        block_type_id: Optional[UUID] = None,\n        is_anonymous: Optional[bool] = None,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Creates the corresponding block document based on the data stored in a block.\n        The corresponding block document name, block type ID, and block schema ID must\n        either be passed into the method or configured on the block.\n\n        Args:\n            name: The name of the created block document. Not required if anonymous.\n            block_schema_id: UUID of the corresponding block schema.\n            block_type_id: UUID of the corresponding block type.\n            is_anonymous: if True, an anonymous block is created. Anonymous\n                blocks are not displayed in the UI and used primarily for system\n                operations and features that need to automatically generate blocks.\n\n        Returns:\n            BlockDocument: Corresponding block document\n                populated with the block's configured data.\n        \"\"\"\n        if is_anonymous is None:\n            is_anonymous = self._is_anonymous or False\n\n        # name must be present if not anonymous\n        if not is_anonymous and not name and not self._block_document_name:\n            raise ValueError(\"No name provided, either as an argument or on the block.\")\n\n        if not block_schema_id and not self._block_schema_id:\n            raise ValueError(\n                \"No block schema ID provided, either as an argument or on the block.\"\n            )\n        if not block_type_id and not self._block_type_id:\n            raise ValueError(\n                \"No block type ID provided, either as an argument or on the block.\"\n            )\n\n        # The keys passed to `include` must NOT be aliases, else some items will be missed\n        # i.e. must do `self.schema_` vs `self.schema` to get a `schema_ = Field(alias=\"schema\")`\n        # reported from https://github.com/PrefectHQ/prefect-dbt/issues/54\n        data_keys = self.schema(by_alias=False)[\"properties\"].keys()\n\n        # `block_document_data`` must return the aliased version for it to show in the UI\n        block_document_data = self.dict(by_alias=True, include=data_keys)\n\n        # Iterate through and find blocks that already have saved block documents to\n        # create references to those saved block documents.\n        for key in data_keys:\n            field_value = getattr(self, key)\n            if (\n                isinstance(field_value, Block)\n                and field_value._block_document_id is not None\n            ):\n                block_document_data[key] = {\n                    \"$ref\": {\"block_document_id\": field_value._block_document_id}\n                }\n\n        return BlockDocument(\n            id=self._block_document_id or uuid4(),\n            name=(name or self._block_document_name) if not is_anonymous else None,\n            block_schema_id=block_schema_id or self._block_schema_id,\n            block_type_id=block_type_id or self._block_type_id,\n            data=block_document_data,\n            block_schema=self._to_block_schema(\n                block_type_id=block_type_id or self._block_type_id,\n            ),\n            block_type=self._to_block_type(),\n            is_anonymous=is_anonymous,\n        )\n\n    @classmethod\n    def _to_block_schema(cls, block_type_id: Optional[UUID] = None) -&gt; BlockSchema:\n        \"\"\"\n        Creates the corresponding block schema of the block.\n        The corresponding block_type_id must either be passed into\n        the method or configured on the block.\n\n        Args:\n            block_type_id: UUID of the corresponding block type.\n\n        Returns:\n            BlockSchema: The corresponding block schema.\n        \"\"\"\n        fields = cls.schema()\n        return BlockSchema(\n            id=cls._block_schema_id if cls._block_schema_id is not None else uuid4(),\n            checksum=cls._calculate_schema_checksum(),\n            fields=fields,\n            block_type_id=block_type_id or cls._block_type_id,\n            block_type=cls._to_block_type(),\n            capabilities=list(cls.get_block_capabilities()),\n            version=cls.get_block_schema_version(),\n        )\n\n    @classmethod\n    def _parse_docstring(cls) -&gt; List[DocstringSection]:\n        \"\"\"\n        Parses the docstring into list of DocstringSection objects.\n        Helper method used primarily to suppress irrelevant logs, e.g.\n        `&lt;module&gt;:11: No type or annotation for parameter 'write_json'`\n        because griffe is unable to parse the types from pydantic.BaseModel.\n        \"\"\"\n        with disable_logger(\"griffe.docstrings.google\"):\n            with disable_logger(\"griffe.agents.nodes\"):\n                docstring = Docstring(cls.__doc__)\n                parsed = parse(docstring, Parser.google)\n        return parsed\n\n    @classmethod\n    def get_description(cls) -&gt; Optional[str]:\n        \"\"\"\n        Returns the description for the current block. Attempts to parse\n        description from class docstring if an override is not defined.\n        \"\"\"\n        description = cls._description\n        # If no description override has been provided, find the first text section\n        # and use that as the description\n        if description is None and cls.__doc__ is not None:\n            parsed = cls._parse_docstring()\n            parsed_description = next(\n                (\n                    section.as_dict().get(\"value\")\n                    for section in parsed\n                    if section.kind == DocstringSectionKind.text\n                ),\n                None,\n            )\n            if isinstance(parsed_description, str):\n                description = parsed_description.strip()\n        return description\n\n    @classmethod\n    def get_code_example(cls) -&gt; Optional[str]:\n        \"\"\"\n        Returns the code example for the given block. Attempts to parse\n        code example from the class docstring if an override is not provided.\n        \"\"\"\n        code_example = (\n            dedent(cls._code_example) if cls._code_example is not None else None\n        )\n        # If no code example override has been provided, attempt to find a examples\n        # section or an admonition with the annotation \"example\" and use that as the\n        # code example\n        if code_example is None and cls.__doc__ is not None:\n            parsed = cls._parse_docstring()\n            for section in parsed:\n                # Section kind will be \"examples\" if Examples section heading is used.\n                if section.kind == DocstringSectionKind.examples:\n                    # Examples sections are made up of smaller sections that need to be\n                    # joined with newlines. Smaller sections are represented as tuples\n                    # with shape (DocstringSectionKind, str)\n                    code_example = \"\\n\".join(\n                        (part[1] for part in section.as_dict().get(\"value\", []))\n                    )\n                    break\n                # Section kind will be \"admonition\" if Example section heading is used.\n                if section.kind == DocstringSectionKind.admonition:\n                    value = section.as_dict().get(\"value\", {})\n                    if value.get(\"annotation\") == \"example\":\n                        code_example = value.get(\"description\")\n                        break\n\n        if code_example is None:\n            # If no code example has been specified or extracted from the class\n            # docstring, generate a sensible default\n            code_example = cls._generate_code_example()\n\n        return code_example\n\n    @classmethod\n    def _generate_code_example(cls) -&gt; str:\n        \"\"\"Generates a default code example for the current class\"\"\"\n        qualified_name = to_qualified_name(cls)\n        module_str = \".\".join(qualified_name.split(\".\")[:-1])\n        class_name = cls.__name__\n        block_variable_name = f'{cls.get_block_type_slug().replace(\"-\", \"_\")}_block'\n\n        return dedent(\n            f\"\"\"\\\n        ```python\n        from {module_str} import {class_name}\n\n        {block_variable_name} = {class_name}.load(\"BLOCK_NAME\")\n        ```\"\"\"\n        )\n\n    @classmethod\n    def _to_block_type(cls) -&gt; BlockType:\n        \"\"\"\n        Creates the corresponding block type of the block.\n\n        Returns:\n            BlockType: The corresponding block type.\n        \"\"\"\n        return BlockType(\n            id=cls._block_type_id or uuid4(),\n            slug=cls.get_block_type_slug(),\n            name=cls.get_block_type_name(),\n            logo_url=cls._logo_url,\n            documentation_url=cls._documentation_url,\n            description=cls.get_description(),\n            code_example=cls.get_code_example(),\n        )\n\n    @classmethod\n    def _from_block_document(cls, block_document: BlockDocument):\n        \"\"\"\n        Instantiates a block from a given block document. The corresponding block class\n        will be looked up in the block registry based on the corresponding block schema\n        of the provided block document.\n\n        Args:\n            block_document: The block document used to instantiate a block.\n\n        Raises:\n            ValueError: If the provided block document doesn't have a corresponding block\n                schema.\n\n        Returns:\n            Block: Hydrated block with data from block document.\n        \"\"\"\n        if block_document.block_schema is None:\n            raise ValueError(\n                \"Unable to determine block schema for provided block document\"\n            )\n\n        block_cls = (\n            cls\n            if cls.__name__ != \"Block\"\n            # Look up the block class by dispatch\n            else cls.get_block_class_from_schema(block_document.block_schema)\n        )\n\n        block_cls = instrument_method_calls_on_class_instances(block_cls)\n\n        block = block_cls.parse_obj(block_document.data)\n        block._block_document_id = block_document.id\n        block.__class__._block_schema_id = block_document.block_schema_id\n        block.__class__._block_type_id = block_document.block_type_id\n        block._block_document_name = block_document.name\n        block._is_anonymous = block_document.is_anonymous\n        block._define_metadata_on_nested_blocks(\n            block_document.block_document_references\n        )\n\n        # Due to the way blocks are loaded we can't directly instrument the\n        # `load` method and have the data be about the block document. Instead\n        # this will emit a proxy event for the load method so that block\n        # document data can be included instead of the event being about an\n        # 'anonymous' block.\n\n        emit_instance_method_called_event(block, \"load\", successful=True)\n\n        return block\n\n    def _event_kind(self) -&gt; str:\n        return f\"prefect.block.{self.get_block_type_slug()}\"\n\n    def _event_method_called_resources(self) -&gt; Optional[ResourceTuple]:\n        if not (self._block_document_id and self._block_document_name):\n            return None\n\n        return (\n            {\n                \"prefect.resource.id\": (\n                    f\"prefect.block-document.{self._block_document_id}\"\n                ),\n                \"prefect.resource.name\": self._block_document_name,\n            },\n            [\n                {\n                    \"prefect.resource.id\": (\n                        f\"prefect.block-type.{self.get_block_type_slug()}\"\n                    ),\n                    \"prefect.resource.role\": \"block-type\",\n                }\n            ],\n        )\n\n    @classmethod\n    def get_block_class_from_schema(cls: Type[Self], schema: BlockSchema) -&gt; Type[Self]:\n        \"\"\"\n        Retrieve the block class implementation given a schema.\n        \"\"\"\n        return cls.get_block_class_from_key(block_schema_to_key(schema))\n\n    @classmethod\n    def get_block_class_from_key(cls: Type[Self], key: str) -&gt; Type[Self]:\n        \"\"\"\n        Retrieve the block class implementation given a key.\n        \"\"\"\n        # Ensure collections are imported and have the opportunity to register types\n        # before looking up the block class\n        prefect.plugins.load_prefect_collections()\n\n        return lookup_type(cls, key)\n\n    def _define_metadata_on_nested_blocks(\n        self, block_document_references: Dict[str, Dict[str, Any]]\n    ):\n        \"\"\"\n        Recursively populates metadata fields on nested blocks based on the\n        provided block document references.\n        \"\"\"\n        for item in block_document_references.items():\n            field_name, block_document_reference = item\n            nested_block = getattr(self, field_name)\n            if isinstance(nested_block, Block):\n                nested_block_document_info = block_document_reference.get(\n                    \"block_document\", {}\n                )\n                nested_block._define_metadata_on_nested_blocks(\n                    nested_block_document_info.get(\"block_document_references\", {})\n                )\n                nested_block_document_id = nested_block_document_info.get(\"id\")\n                nested_block._block_document_id = (\n                    UUID(nested_block_document_id) if nested_block_document_id else None\n                )\n                nested_block._block_document_name = nested_block_document_info.get(\n                    \"name\"\n                )\n                nested_block._is_anonymous = nested_block_document_info.get(\n                    \"is_anonymous\"\n                )\n\n    @classmethod\n    @inject_client\n    async def _get_block_document(\n        cls,\n        name: str,\n        client: \"PrefectClient\" = None,\n    ):\n        if cls.__name__ == \"Block\":\n            block_type_slug, block_document_name = name.split(\"/\", 1)\n        else:\n            block_type_slug = cls.get_block_type_slug()\n            block_document_name = name\n\n        try:\n            block_document = await client.read_block_document_by_name(\n                name=block_document_name, block_type_slug=block_type_slug\n            )\n        except prefect.exceptions.ObjectNotFound as e:\n            raise ValueError(\n                f\"Unable to find block document named {block_document_name} for block\"\n                f\" type {block_type_slug}\"\n            ) from e\n\n        return block_document, block_document_name\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def load(\n        cls,\n        name: str,\n        validate: bool = True,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Retrieves data from the block document with the given name for the block type\n        that corresponds with the current class and returns an instantiated version of\n        the current class with the data stored in the block document.\n\n        If a block document for a given block type is saved with a different schema\n        than the current class calling `load`, a warning will be raised.\n\n        If the current class schema is a subset of the block document schema, the block\n        can be loaded as normal using the default `validate = True`.\n\n        If the current class schema is a superset of the block document schema, `load`\n        must be called with `validate` set to False to prevent a validation error. In\n        this case, the block attributes will default to `None` and must be set manually\n        and saved to a new block document before the block can be used as expected.\n\n        Args:\n            name: The name or slug of the block document. A block document slug is a\n                string with the format &lt;block_type_slug&gt;/&lt;block_document_name&gt;\n            validate: If False, the block document will be loaded without Pydantic\n                validating the block schema. This is useful if the block schema has\n                changed client-side since the block document referred to by `name` was saved.\n            client: The client to use to load the block document. If not provided, the\n                default client will be injected.\n\n        Raises:\n            ValueError: If the requested block document is not found.\n\n        Returns:\n            An instance of the current class hydrated with the data stored in the\n            block document with the specified name.\n\n        Examples:\n            Load from a Block subclass with a block document name:\n            ```python\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            loaded_block = Custom.load(\"my-custom-message\")\n            ```\n\n            Load from Block with a block document slug:\n            ```python\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            loaded_block = Block.load(\"custom/my-custom-message\")\n            ```\n\n            Migrate a block document to a new schema:\n            ```python\n            # original class\n            class Custom(Block):\n                message: str\n\n            Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n            # Updated class with new required field\n            class Custom(Block):\n                message: str\n                number_of_ducks: int\n\n            loaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n            # Prints UserWarning about schema mismatch\n\n            loaded_block.number_of_ducks = 42\n\n            loaded_block.save(\"my-custom-message\", overwrite=True)\n            ```\n        \"\"\"\n        block_document, block_document_name = await cls._get_block_document(name)\n\n        try:\n            return cls._from_block_document(block_document)\n        except ValidationError as e:\n            if not validate:\n                missing_fields = tuple(err[\"loc\"][0] for err in e.errors())\n                missing_block_data = {field: None for field in missing_fields}\n                warnings.warn(\n                    f\"Could not fully load {block_document_name!r} of block type\"\n                    f\" {cls._block_type_slug!r} - this is likely because one or more\"\n                    \" required fields were added to the schema for\"\n                    f\" {cls.__name__!r} that did not exist on the class when this block\"\n                    \" was last saved. Please specify values for new field(s):\"\n                    f\" {listrepr(missing_fields)}, then run\"\n                    f' `{cls.__name__}.save(\"{block_document_name}\", overwrite=True)`,'\n                    \" and load this block again before attempting to use it.\"\n                )\n                return cls.construct(**block_document.data, **missing_block_data)\n            raise RuntimeError(\n                f\"Unable to load {block_document_name!r} of block type\"\n                f\" {cls._block_type_slug!r} due to failed validation. To load without\"\n                \" validation, try loading again with `validate=False`.\"\n            ) from e\n\n    @staticmethod\n    def is_block_class(block) -&gt; bool:\n        return _is_subclass(block, Block)\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def register_type_and_schema(cls, client: \"PrefectClient\" = None):\n        \"\"\"\n        Makes block available for configuration with current Prefect API.\n        Recursively registers all nested blocks. Registration is idempotent.\n\n        Args:\n            client: Optional client to use for registering type and schema with the\n                Prefect API. A new client will be created and used if one is not\n                provided.\n        \"\"\"\n        if cls.__name__ == \"Block\":\n            raise InvalidBlockRegistration(\n                \"`register_type_and_schema` should be called on a Block \"\n                \"subclass and not on the Block class directly.\"\n            )\n        if ABC in getattr(cls, \"__bases__\", []):\n            raise InvalidBlockRegistration(\n                \"`register_type_and_schema` should be called on a Block \"\n                \"subclass and not on a Block interface class directly.\"\n            )\n\n        async def register_blocks_in_annotation(annotation: type) -&gt; None:\n            \"\"\"Walk through the annotation and register any nested blocks.\"\"\"\n            if Block.is_block_class(annotation):\n                await annotation.register_type_and_schema(client=client)\n            elif get_origin(annotation) in (Union, tuple, list, dict):\n                for inner_annotation in get_args(annotation):\n                    await register_blocks_in_annotation(inner_annotation)\n\n        for field in cls.__fields__.values():\n            await register_blocks_in_annotation(field.annotation)\n\n        try:\n            block_type = await client.read_block_type_by_slug(\n                slug=cls.get_block_type_slug()\n            )\n            cls._block_type_id = block_type.id\n            local_block_type = cls._to_block_type()\n            if _should_update_block_type(\n                local_block_type=local_block_type, server_block_type=block_type\n            ):\n                await client.update_block_type(\n                    block_type_id=block_type.id, block_type=local_block_type\n                )\n        except prefect.exceptions.ObjectNotFound:\n            block_type = await client.create_block_type(block_type=cls._to_block_type())\n            cls._block_type_id = block_type.id\n\n        try:\n            block_schema = await client.read_block_schema_by_checksum(\n                checksum=cls._calculate_schema_checksum(),\n                version=cls.get_block_schema_version(),\n            )\n        except prefect.exceptions.ObjectNotFound:\n            block_schema = await client.create_block_schema(\n                block_schema=cls._to_block_schema(block_type_id=block_type.id)\n            )\n\n        cls._block_schema_id = block_schema.id\n\n    @inject_client\n    async def _save(\n        self,\n        name: Optional[str] = None,\n        is_anonymous: bool = False,\n        overwrite: bool = False,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Saves the values of a block as a block document with an option to save as an\n        anonymous block document.\n\n        Args:\n            name: User specified name to give saved block document which can later be used to load the\n                block document.\n            is_anonymous: Boolean value specifying whether the block document is anonymous. Anonymous\n                blocks are intended for system use and are not shown in the UI. Anonymous blocks do not\n                require a user-supplied name.\n            overwrite: Boolean value specifying if values should be overwritten if a block document with\n                the specified name already exists.\n\n        Raises:\n            ValueError: If a name is not given and `is_anonymous` is `False` or a name is given and\n                `is_anonymous` is `True`.\n        \"\"\"\n        if name is None and not is_anonymous:\n            if self._block_document_name is None:\n                raise ValueError(\n                    \"You're attempting to save a block document without a name.\"\n                    \" Please either call `save` with a `name` or pass\"\n                    \" `is_anonymous=True` to save an anonymous block.\"\n                )\n            else:\n                name = self._block_document_name\n\n        self._is_anonymous = is_anonymous\n\n        # Ensure block type and schema are registered before saving block document.\n        await self.register_type_and_schema(client=client)\n\n        try:\n            block_document = await client.create_block_document(\n                block_document=self._to_block_document(name=name)\n            )\n        except prefect.exceptions.ObjectAlreadyExists as err:\n            if overwrite:\n                block_document_id = self._block_document_id\n                if block_document_id is None:\n                    existing_block_document = await client.read_block_document_by_name(\n                        name=name, block_type_slug=self.get_block_type_slug()\n                    )\n                    block_document_id = existing_block_document.id\n                await client.update_block_document(\n                    block_document_id=block_document_id,\n                    block_document=self._to_block_document(name=name),\n                )\n                block_document = await client.read_block_document(\n                    block_document_id=block_document_id\n                )\n            else:\n                raise ValueError(\n                    \"You are attempting to save values with a name that is already in\"\n                    \" use for this block type. If you would like to overwrite the\"\n                    \" values that are saved, then save with `overwrite=True`.\"\n                ) from err\n\n        # Update metadata on block instance for later use.\n        self._block_document_name = block_document.name\n        self._block_document_id = block_document.id\n        return self._block_document_id\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def save(\n        self,\n        name: Optional[str] = None,\n        overwrite: bool = False,\n        client: \"PrefectClient\" = None,\n    ):\n        \"\"\"\n        Saves the values of a block as a block document.\n\n        Args:\n            name: User specified name to give saved block document which can later be used to load the\n                block document.\n            overwrite: Boolean value specifying if values should be overwritten if a block document with\n                the specified name already exists.\n\n        \"\"\"\n        document_id = await self._save(name=name, overwrite=overwrite, client=client)\n\n        return document_id\n\n    @classmethod\n    @sync_compatible\n    @inject_client\n    async def delete(\n        cls,\n        name: str,\n        client: \"PrefectClient\" = None,\n    ):\n        block_document, block_document_name = await cls._get_block_document(name)\n\n        await client.delete_block_document(block_document.id)\n\n    def _iter(self, *, include=None, exclude=None, **kwargs):\n        # Injects the `block_type_slug` into serialized payloads for dispatch\n        for key_value in super()._iter(include=include, exclude=exclude, **kwargs):\n            yield key_value\n\n        # Respect inclusion and exclusion still\n        if include and \"block_type_slug\" not in include:\n            return\n        if exclude and \"block_type_slug\" in exclude:\n            return\n\n        yield \"block_type_slug\", self.get_block_type_slug()\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        \"\"\"\n        Create an instance of the Block subclass type if a `block_type_slug` is\n        present in the data payload.\n        \"\"\"\n        block_type_slug = kwargs.pop(\"block_type_slug\", None)\n        if block_type_slug:\n            subcls = lookup_type(cls, dispatch_key=block_type_slug)\n            m = super().__new__(subcls)\n            # NOTE: This is a workaround for an obscure issue where copied models were\n            #       missing attributes. This pattern is from Pydantic's\n            #       `BaseModel._copy_and_set_values`.\n            #       The issue this fixes could not be reproduced in unit tests that\n            #       directly targeted dispatch handling and was only observed when\n            #       copying then saving infrastructure blocks on deployment models.\n            object.__setattr__(m, \"__dict__\", kwargs)\n            object.__setattr__(m, \"__fields_set__\", set(kwargs.keys()))\n            return m\n        else:\n            m = super().__new__(cls)\n            object.__setattr__(m, \"__dict__\", kwargs)\n            object.__setattr__(m, \"__fields_set__\", set(kwargs.keys()))\n            return m\n\n    def get_block_placeholder(self) -&gt; str:\n        \"\"\"\n        Returns the block placeholder for the current block which can be used for\n        templating.\n\n        Returns:\n            str: The block placeholder for the current block in the format\n                `prefect.blocks.{block_type_name}.{block_document_name}`\n\n        Raises:\n            BlockNotSavedError: Raised if the block has not been saved.\n\n        If a block has not been saved, the return value will be `None`.\n        \"\"\"\n        block_document_name = self._block_document_name\n        if not block_document_name:\n            raise BlockNotSavedError(\n                \"Could not generate block placeholder for unsaved block.\"\n            )\n\n        return f\"prefect.blocks.{self.get_block_type_slug()}.{block_document_name}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.Config","title":"<code>Config</code>","text":"Source code in <code>prefect/blocks/core.py</code> <pre><code>class Config:\n    extra = \"allow\"\n\n    json_encoders = {SecretDict: lambda v: v.dict()}\n\n    @staticmethod\n    def schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n        \"\"\"\n        Customizes Pydantic's schema generation feature to add blocks related information.\n        \"\"\"\n        schema[\"block_type_slug\"] = model.get_block_type_slug()\n        # Ensures args and code examples aren't included in the schema\n        description = model.get_description()\n        if description:\n            schema[\"description\"] = description\n        else:\n            # Prevent the description of the base class from being included in the schema\n            schema.pop(\"description\", None)\n\n        # create a list of secret field names\n        # secret fields include both top-level keys and dot-delimited nested secret keys\n        # A wildcard (*) means that all fields under a given key are secret.\n        # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n        # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n        # nested under the \"child\" key are all secret. There is no limit to nesting.\n        secrets = schema[\"secret_fields\"] = []\n        for field in model.__fields__.values():\n            _collect_secret_fields(field.name, field.type_, secrets)\n\n        # create block schema references\n        refs = schema[\"block_schema_references\"] = {}\n\n        def collect_block_schema_references(\n            field_name: str, annotation: type\n        ) -&gt; None:\n            \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n            if Block.is_block_class(annotation):\n                if isinstance(refs.get(field_name), list):\n                    refs[field_name].append(\n                        annotation._to_block_schema_reference_dict()\n                    )\n                elif isinstance(refs.get(field_name), dict):\n                    refs[field_name] = [\n                        refs[field_name],\n                        annotation._to_block_schema_reference_dict(),\n                    ]\n                else:\n                    refs[field_name] = annotation._to_block_schema_reference_dict()\n            if get_origin(annotation) in (Union, list, tuple, dict):\n                for type_ in get_args(annotation):\n                    collect_block_schema_references(field_name, type_)\n\n        for field in model.__fields__.values():\n            collect_block_schema_references(field.name, field.type_)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.Config.schema_extra","title":"<code>schema_extra</code>  <code>staticmethod</code>","text":"<p>Customizes Pydantic's schema generation feature to add blocks related information.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@staticmethod\ndef schema_extra(schema: Dict[str, Any], model: Type[\"Block\"]):\n    \"\"\"\n    Customizes Pydantic's schema generation feature to add blocks related information.\n    \"\"\"\n    schema[\"block_type_slug\"] = model.get_block_type_slug()\n    # Ensures args and code examples aren't included in the schema\n    description = model.get_description()\n    if description:\n        schema[\"description\"] = description\n    else:\n        # Prevent the description of the base class from being included in the schema\n        schema.pop(\"description\", None)\n\n    # create a list of secret field names\n    # secret fields include both top-level keys and dot-delimited nested secret keys\n    # A wildcard (*) means that all fields under a given key are secret.\n    # for example: [\"x\", \"y\", \"z.*\", \"child.a\"]\n    # means the top-level keys \"x\" and \"y\", all keys under \"z\", and the key \"a\" of a block\n    # nested under the \"child\" key are all secret. There is no limit to nesting.\n    secrets = schema[\"secret_fields\"] = []\n    for field in model.__fields__.values():\n        _collect_secret_fields(field.name, field.type_, secrets)\n\n    # create block schema references\n    refs = schema[\"block_schema_references\"] = {}\n\n    def collect_block_schema_references(\n        field_name: str, annotation: type\n    ) -&gt; None:\n        \"\"\"Walk through the annotation and collect block schemas for any nested blocks.\"\"\"\n        if Block.is_block_class(annotation):\n            if isinstance(refs.get(field_name), list):\n                refs[field_name].append(\n                    annotation._to_block_schema_reference_dict()\n                )\n            elif isinstance(refs.get(field_name), dict):\n                refs[field_name] = [\n                    refs[field_name],\n                    annotation._to_block_schema_reference_dict(),\n                ]\n            else:\n                refs[field_name] = annotation._to_block_schema_reference_dict()\n        if get_origin(annotation) in (Union, list, tuple, dict):\n            for type_ in get_args(annotation):\n                collect_block_schema_references(field_name, type_)\n\n    for field in model.__fields__.values():\n        collect_block_schema_references(field.name, field.type_)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_capabilities","title":"<code>get_block_capabilities</code>  <code>classmethod</code>","text":"<p>Returns the block capabilities for this Block. Recursively collects all block capabilities of all parent classes into a single frozenset.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_capabilities(cls) -&gt; FrozenSet[str]:\n    \"\"\"\n    Returns the block capabilities for this Block. Recursively collects all block\n    capabilities of all parent classes into a single frozenset.\n    \"\"\"\n    return frozenset(\n        {\n            c\n            for base in (cls,) + cls.__mro__\n            for c in getattr(base, \"_block_schema_capabilities\", []) or []\n        }\n    )\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_class_from_key","title":"<code>get_block_class_from_key</code>  <code>classmethod</code>","text":"<p>Retrieve the block class implementation given a key.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_class_from_key(cls: Type[Self], key: str) -&gt; Type[Self]:\n    \"\"\"\n    Retrieve the block class implementation given a key.\n    \"\"\"\n    # Ensure collections are imported and have the opportunity to register types\n    # before looking up the block class\n    prefect.plugins.load_prefect_collections()\n\n    return lookup_type(cls, key)\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_class_from_schema","title":"<code>get_block_class_from_schema</code>  <code>classmethod</code>","text":"<p>Retrieve the block class implementation given a schema.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_block_class_from_schema(cls: Type[Self], schema: BlockSchema) -&gt; Type[Self]:\n    \"\"\"\n    Retrieve the block class implementation given a schema.\n    \"\"\"\n    return cls.get_block_class_from_key(block_schema_to_key(schema))\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_block_placeholder","title":"<code>get_block_placeholder</code>","text":"<p>Returns the block placeholder for the current block which can be used for templating.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The block placeholder for the current block in the format <code>prefect.blocks.{block_type_name}.{block_document_name}</code></p> <p>Raises:</p> Type Description <code>BlockNotSavedError</code> <p>Raised if the block has not been saved.</p> <p>If a block has not been saved, the return value will be <code>None</code>.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>def get_block_placeholder(self) -&gt; str:\n    \"\"\"\n    Returns the block placeholder for the current block which can be used for\n    templating.\n\n    Returns:\n        str: The block placeholder for the current block in the format\n            `prefect.blocks.{block_type_name}.{block_document_name}`\n\n    Raises:\n        BlockNotSavedError: Raised if the block has not been saved.\n\n    If a block has not been saved, the return value will be `None`.\n    \"\"\"\n    block_document_name = self._block_document_name\n    if not block_document_name:\n        raise BlockNotSavedError(\n            \"Could not generate block placeholder for unsaved block.\"\n        )\n\n    return f\"prefect.blocks.{self.get_block_type_slug()}.{block_document_name}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_code_example","title":"<code>get_code_example</code>  <code>classmethod</code>","text":"<p>Returns the code example for the given block. Attempts to parse code example from the class docstring if an override is not provided.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_code_example(cls) -&gt; Optional[str]:\n    \"\"\"\n    Returns the code example for the given block. Attempts to parse\n    code example from the class docstring if an override is not provided.\n    \"\"\"\n    code_example = (\n        dedent(cls._code_example) if cls._code_example is not None else None\n    )\n    # If no code example override has been provided, attempt to find a examples\n    # section or an admonition with the annotation \"example\" and use that as the\n    # code example\n    if code_example is None and cls.__doc__ is not None:\n        parsed = cls._parse_docstring()\n        for section in parsed:\n            # Section kind will be \"examples\" if Examples section heading is used.\n            if section.kind == DocstringSectionKind.examples:\n                # Examples sections are made up of smaller sections that need to be\n                # joined with newlines. Smaller sections are represented as tuples\n                # with shape (DocstringSectionKind, str)\n                code_example = \"\\n\".join(\n                    (part[1] for part in section.as_dict().get(\"value\", []))\n                )\n                break\n            # Section kind will be \"admonition\" if Example section heading is used.\n            if section.kind == DocstringSectionKind.admonition:\n                value = section.as_dict().get(\"value\", {})\n                if value.get(\"annotation\") == \"example\":\n                    code_example = value.get(\"description\")\n                    break\n\n    if code_example is None:\n        # If no code example has been specified or extracted from the class\n        # docstring, generate a sensible default\n        code_example = cls._generate_code_example()\n\n    return code_example\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.get_description","title":"<code>get_description</code>  <code>classmethod</code>","text":"<p>Returns the description for the current block. Attempts to parse description from class docstring if an override is not defined.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\ndef get_description(cls) -&gt; Optional[str]:\n    \"\"\"\n    Returns the description for the current block. Attempts to parse\n    description from class docstring if an override is not defined.\n    \"\"\"\n    description = cls._description\n    # If no description override has been provided, find the first text section\n    # and use that as the description\n    if description is None and cls.__doc__ is not None:\n        parsed = cls._parse_docstring()\n        parsed_description = next(\n            (\n                section.as_dict().get(\"value\")\n                for section in parsed\n                if section.kind == DocstringSectionKind.text\n            ),\n            None,\n        )\n        if isinstance(parsed_description, str):\n            description = parsed_description.strip()\n    return description\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document.</p> <p>If a block document for a given block type is saved with a different schema than the current class calling <code>load</code>, a warning will be raised.</p> <p>If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default <code>validate = True</code>.</p> <p>If the current class schema is a superset of the block document schema, <code>load</code> must be called with <code>validate</code> set to False to prevent a validation error. In this case, the block attributes will default to <code>None</code> and must be set manually and saved to a new block document before the block can be used as expected.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name or slug of the block document. A block document slug is a string with the format / required <code>validate</code> <code>bool</code> <p>If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by <code>name</code> was saved.</p> <code>True</code> <code>client</code> <code>PrefectClient</code> <p>The client to use to load the block document. If not provided, the default client will be injected.</p> <code>None</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the requested block document is not found.</p> <p>Returns:</p> Type Description <p>An instance of the current class hydrated with the data stored in the</p> <p>block document with the specified name.</p> <p>Examples:</p> <p>Load from a Block subclass with a block document name: <pre><code>class Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\nloaded_block = Custom.load(\"my-custom-message\")\n</code></pre></p> <p>Load from Block with a block document slug: <pre><code>class Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\nloaded_block = Block.load(\"custom/my-custom-message\")\n</code></pre></p> <p>Migrate a block document to a new schema: <pre><code># original class\nclass Custom(Block):\n    message: str\n\nCustom(message=\"Hello!\").save(\"my-custom-message\")\n\n# Updated class with new required field\nclass Custom(Block):\n    message: str\n    number_of_ducks: int\n\nloaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n# Prints UserWarning about schema mismatch\n\nloaded_block.number_of_ducks = 42\n\nloaded_block.save(\"my-custom-message\", overwrite=True)\n</code></pre></p> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\n@sync_compatible\n@inject_client\nasync def load(\n    cls,\n    name: str,\n    validate: bool = True,\n    client: \"PrefectClient\" = None,\n):\n    \"\"\"\n    Retrieves data from the block document with the given name for the block type\n    that corresponds with the current class and returns an instantiated version of\n    the current class with the data stored in the block document.\n\n    If a block document for a given block type is saved with a different schema\n    than the current class calling `load`, a warning will be raised.\n\n    If the current class schema is a subset of the block document schema, the block\n    can be loaded as normal using the default `validate = True`.\n\n    If the current class schema is a superset of the block document schema, `load`\n    must be called with `validate` set to False to prevent a validation error. In\n    this case, the block attributes will default to `None` and must be set manually\n    and saved to a new block document before the block can be used as expected.\n\n    Args:\n        name: The name or slug of the block document. A block document slug is a\n            string with the format &lt;block_type_slug&gt;/&lt;block_document_name&gt;\n        validate: If False, the block document will be loaded without Pydantic\n            validating the block schema. This is useful if the block schema has\n            changed client-side since the block document referred to by `name` was saved.\n        client: The client to use to load the block document. If not provided, the\n            default client will be injected.\n\n    Raises:\n        ValueError: If the requested block document is not found.\n\n    Returns:\n        An instance of the current class hydrated with the data stored in the\n        block document with the specified name.\n\n    Examples:\n        Load from a Block subclass with a block document name:\n        ```python\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        loaded_block = Custom.load(\"my-custom-message\")\n        ```\n\n        Load from Block with a block document slug:\n        ```python\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        loaded_block = Block.load(\"custom/my-custom-message\")\n        ```\n\n        Migrate a block document to a new schema:\n        ```python\n        # original class\n        class Custom(Block):\n            message: str\n\n        Custom(message=\"Hello!\").save(\"my-custom-message\")\n\n        # Updated class with new required field\n        class Custom(Block):\n            message: str\n            number_of_ducks: int\n\n        loaded_block = Custom.load(\"my-custom-message\", validate=False)\n\n        # Prints UserWarning about schema mismatch\n\n        loaded_block.number_of_ducks = 42\n\n        loaded_block.save(\"my-custom-message\", overwrite=True)\n        ```\n    \"\"\"\n    block_document, block_document_name = await cls._get_block_document(name)\n\n    try:\n        return cls._from_block_document(block_document)\n    except ValidationError as e:\n        if not validate:\n            missing_fields = tuple(err[\"loc\"][0] for err in e.errors())\n            missing_block_data = {field: None for field in missing_fields}\n            warnings.warn(\n                f\"Could not fully load {block_document_name!r} of block type\"\n                f\" {cls._block_type_slug!r} - this is likely because one or more\"\n                \" required fields were added to the schema for\"\n                f\" {cls.__name__!r} that did not exist on the class when this block\"\n                \" was last saved. Please specify values for new field(s):\"\n                f\" {listrepr(missing_fields)}, then run\"\n                f' `{cls.__name__}.save(\"{block_document_name}\", overwrite=True)`,'\n                \" and load this block again before attempting to use it.\"\n            )\n            return cls.construct(**block_document.data, **missing_block_data)\n        raise RuntimeError(\n            f\"Unable to load {block_document_name!r} of block type\"\n            f\" {cls._block_type_slug!r} due to failed validation. To load without\"\n            \" validation, try loading again with `validate=False`.\"\n        ) from e\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.register_type_and_schema","title":"<code>register_type_and_schema</code>  <code>async</code> <code>classmethod</code>","text":"<p>Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>PrefectClient</code> <p>Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.</p> <code>None</code> Source code in <code>prefect/blocks/core.py</code> <pre><code>@classmethod\n@sync_compatible\n@inject_client\nasync def register_type_and_schema(cls, client: \"PrefectClient\" = None):\n    \"\"\"\n    Makes block available for configuration with current Prefect API.\n    Recursively registers all nested blocks. Registration is idempotent.\n\n    Args:\n        client: Optional client to use for registering type and schema with the\n            Prefect API. A new client will be created and used if one is not\n            provided.\n    \"\"\"\n    if cls.__name__ == \"Block\":\n        raise InvalidBlockRegistration(\n            \"`register_type_and_schema` should be called on a Block \"\n            \"subclass and not on the Block class directly.\"\n        )\n    if ABC in getattr(cls, \"__bases__\", []):\n        raise InvalidBlockRegistration(\n            \"`register_type_and_schema` should be called on a Block \"\n            \"subclass and not on a Block interface class directly.\"\n        )\n\n    async def register_blocks_in_annotation(annotation: type) -&gt; None:\n        \"\"\"Walk through the annotation and register any nested blocks.\"\"\"\n        if Block.is_block_class(annotation):\n            await annotation.register_type_and_schema(client=client)\n        elif get_origin(annotation) in (Union, tuple, list, dict):\n            for inner_annotation in get_args(annotation):\n                await register_blocks_in_annotation(inner_annotation)\n\n    for field in cls.__fields__.values():\n        await register_blocks_in_annotation(field.annotation)\n\n    try:\n        block_type = await client.read_block_type_by_slug(\n            slug=cls.get_block_type_slug()\n        )\n        cls._block_type_id = block_type.id\n        local_block_type = cls._to_block_type()\n        if _should_update_block_type(\n            local_block_type=local_block_type, server_block_type=block_type\n        ):\n            await client.update_block_type(\n                block_type_id=block_type.id, block_type=local_block_type\n            )\n    except prefect.exceptions.ObjectNotFound:\n        block_type = await client.create_block_type(block_type=cls._to_block_type())\n        cls._block_type_id = block_type.id\n\n    try:\n        block_schema = await client.read_block_schema_by_checksum(\n            checksum=cls._calculate_schema_checksum(),\n            version=cls.get_block_schema_version(),\n        )\n    except prefect.exceptions.ObjectNotFound:\n        block_schema = await client.create_block_schema(\n            block_schema=cls._to_block_schema(block_type_id=block_type.id)\n        )\n\n    cls._block_schema_id = block_schema.id\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.Block.save","title":"<code>save</code>  <code>async</code>","text":"<p>Saves the values of a block as a block document.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Optional[str]</code> <p>User specified name to give saved block document which can later be used to load the block document.</p> <code>None</code> <code>overwrite</code> <code>bool</code> <p>Boolean value specifying if values should be overwritten if a block document with the specified name already exists.</p> <code>False</code> Source code in <code>prefect/blocks/core.py</code> <pre><code>@sync_compatible\n@instrument_instance_method_call\nasync def save(\n    self,\n    name: Optional[str] = None,\n    overwrite: bool = False,\n    client: \"PrefectClient\" = None,\n):\n    \"\"\"\n    Saves the values of a block as a block document.\n\n    Args:\n        name: User specified name to give saved block document which can later be used to load the\n            block document.\n        overwrite: Boolean value specifying if values should be overwritten if a block document with\n            the specified name already exists.\n\n    \"\"\"\n    document_id = await self._save(name=name, overwrite=overwrite, client=client)\n\n    return document_id\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.BlockNotSavedError","title":"<code>BlockNotSavedError</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Raised when a given block is not saved and an operation that requires the block to be saved is attempted.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>class BlockNotSavedError(RuntimeError):\n    \"\"\"\n    Raised when a given block is not saved and an operation that requires\n    the block to be saved is attempted.\n    \"\"\"\n\n    pass\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.InvalidBlockRegistration","title":"<code>InvalidBlockRegistration</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised on attempted registration of the base Block class or a Block interface class</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>class InvalidBlockRegistration(Exception):\n    \"\"\"\n    Raised on attempted registration of the base Block\n    class or a Block interface class\n    \"\"\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/core/#prefect.blocks.core.block_schema_to_key","title":"<code>block_schema_to_key</code>","text":"<p>Defines the unique key used to lookup the Block class for a given schema.</p> Source code in <code>prefect/blocks/core.py</code> <pre><code>def block_schema_to_key(schema: BlockSchema) -&gt; str:\n    \"\"\"\n    Defines the unique key used to lookup the Block class for a given schema.\n    \"\"\"\n    return f\"{schema.block_type.slug}\"\n</code></pre>","tags":["Python API","blocks"]},{"location":"api-ref/prefect/blocks/fields/","title":"fields","text":"","tags":["Python API","fields"]},{"location":"api-ref/prefect/blocks/fields/#prefect.blocks.fields","title":"<code>prefect.blocks.fields</code>","text":"","tags":["Python API","fields"]},{"location":"api-ref/prefect/blocks/kubernetes/","title":"kubernetes","text":"","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes","title":"<code>prefect.blocks.kubernetes</code>","text":"","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect.blocks.kubernetes import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the KubernetesClusterConfig block from prefect-kubernetes instead.\",\n)\nclass KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect.blocks.kubernetes import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig\"\n\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    def parse_yaml_config(cls, value):\n        return validate_yaml(value)\n\n    @classmethod\n    def from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n        kube_config = kubernetes.config.kube_config\n\n        path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        existing_contexts, current_context = kube_config.list_kube_config_contexts(\n            config_file=str(path)\n        )\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n\n        return cls(config=config_dict, context_name=context_name)\n\n    def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return kubernetes.config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        kubernetes.config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    kubernetes.config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>@classmethod\ndef from_file(cls: Type[Self], path: Path = None, context_name: str = None) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n    kube_config = kubernetes.config.kube_config\n\n    path = Path(path or kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    existing_contexts, current_context = kube_config.list_kube_config_contexts(\n        config_file=str(path)\n    )\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/kubernetes/#prefect.blocks.kubernetes.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect/blocks/kubernetes.py</code> <pre><code>def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return kubernetes.config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>","tags":["Python API","blocks","Kubernetes"]},{"location":"api-ref/prefect/blocks/notifications/","title":"notifications","text":"","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications","title":"<code>prefect.blocks.notifications</code>","text":"","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.AbstractAppriseNotificationBlock","title":"<code>AbstractAppriseNotificationBlock</code>","text":"<p>               Bases: <code>NotificationBlock</code>, <code>ABC</code></p> <p>An abstract class for sending notifications using Apprise.</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class AbstractAppriseNotificationBlock(NotificationBlock, ABC):\n    \"\"\"\n    An abstract class for sending notifications using Apprise.\n    \"\"\"\n\n    notify_type: Literal[\n        \"prefect_default\", \"info\", \"success\", \"warning\", \"failure\"\n    ] = Field(\n        default=PREFECT_NOTIFY_TYPE_DEFAULT,\n        description=(\n            \"The type of notification being performed; the prefect_default \"\n            \"is a plain notification that does not attach an image.\"\n        ),\n    )\n\n    def __init__(self, *args, **kwargs):\n        import apprise\n\n        if PREFECT_NOTIFY_TYPE_DEFAULT not in apprise.NOTIFY_TYPES:\n            apprise.NOTIFY_TYPES += (PREFECT_NOTIFY_TYPE_DEFAULT,)\n\n        super().__init__(*args, **kwargs)\n\n    def _start_apprise_client(self, url: SecretStr):\n        from apprise import Apprise, AppriseAsset\n\n        # A custom `AppriseAsset` that ensures Prefect Notifications\n        # appear correctly across multiple messaging platforms\n        prefect_app_data = AppriseAsset(\n            app_id=\"Prefect Notifications\",\n            app_desc=\"Prefect Notifications\",\n            app_url=\"https://prefect.io\",\n        )\n\n        self._apprise_client = Apprise(asset=prefect_app_data)\n        self._apprise_client.add(url.get_secret_value())\n\n    def block_initialization(self) -&gt; None:\n        self._start_apprise_client(self.url)\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def notify(\n        self,\n        body: str,\n        subject: Optional[str] = None,\n    ):\n        with LogEavesdropper(\"apprise\", level=logging.DEBUG) as eavesdropper:\n            result = await self._apprise_client.async_notify(\n                body=body, title=subject, notify_type=self.notify_type\n            )\n        if not result and self._raise_on_failure:\n            raise NotificationError(log=eavesdropper.text())\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.AppriseNotificationBlock","title":"<code>AppriseNotificationBlock</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code>, <code>ABC</code></p> <p>A base class for sending notifications using Apprise, through webhook URLs.</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class AppriseNotificationBlock(AbstractAppriseNotificationBlock, ABC):\n    \"\"\"\n    A base class for sending notifications using Apprise, through webhook URLs.\n    \"\"\"\n\n    _documentation_url = \"https://docs.prefect.io/ui/notifications/\"\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Incoming webhook URL used to send notifications.\",\n        examples=[\"https://hooks.example.com/XXX\"],\n    )\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.CustomWebhookNotificationBlock","title":"<code>CustomWebhookNotificationBlock</code>","text":"<p>               Bases: <code>NotificationBlock</code></p> <p>Enables sending notifications via any custom webhook.</p> <p>All nested string param contains <code>{{key}}</code> will be substituted with value from context/secrets.</p> <p>Context values include: <code>subject</code>, <code>body</code> and <code>name</code>.</p> <p>Examples:</p> <p>Load a saved custom webhook and send a message: <pre><code>from prefect.blocks.notifications import CustomWebhookNotificationBlock\n\ncustom_webhook_block = CustomWebhookNotificationBlock.load(\"BLOCK_NAME\")\n\ncustom_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class CustomWebhookNotificationBlock(NotificationBlock):\n    \"\"\"\n    Enables sending notifications via any custom webhook.\n\n    All nested string param contains `{{key}}` will be substituted with value from context/secrets.\n\n    Context values include: `subject`, `body` and `name`.\n\n    Examples:\n        Load a saved custom webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import CustomWebhookNotificationBlock\n\n        custom_webhook_block = CustomWebhookNotificationBlock.load(\"BLOCK_NAME\")\n\n        custom_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Custom Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c7247cb359eb6cf276734d4b1fbf00fb8930e89e-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.CustomWebhookNotificationBlock\"\n\n    name: str = Field(title=\"Name\", description=\"Name of the webhook.\")\n\n    url: str = Field(\n        title=\"Webhook URL\",\n        description=\"The webhook URL.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n\n    method: Literal[\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"] = Field(\n        default=\"POST\", description=\"The webhook request method. Defaults to `POST`.\"\n    )\n\n    params: Optional[Dict[str, str]] = Field(\n        default=None, title=\"Query Params\", description=\"Custom query params.\"\n    )\n    json_data: Optional[dict] = Field(\n        default=None,\n        title=\"JSON Data\",\n        description=\"Send json data as payload.\",\n        examples=[\n            '{\"text\": \"{{subject}}\\\\n{{body}}\", \"title\": \"{{name}}\", \"token\":'\n            ' \"{{tokenFromSecrets}}\"}'\n        ],\n    )\n    form_data: Optional[Dict[str, str]] = Field(\n        default=None,\n        title=\"Form Data\",\n        description=(\n            \"Send form data as payload. Should not be used together with _JSON Data_.\"\n        ),\n        examples=[\n            '{\"text\": \"{{subject}}\\\\n{{body}}\", \"title\": \"{{name}}\", \"token\":'\n            ' \"{{tokenFromSecrets}}\"}'\n        ],\n    )\n\n    headers: Optional[Dict[str, str]] = Field(None, description=\"Custom headers.\")\n    cookies: Optional[Dict[str, str]] = Field(None, description=\"Custom cookies.\")\n\n    timeout: float = Field(\n        default=10, description=\"Request timeout in seconds. Defaults to 10.\"\n    )\n\n    secrets: SecretDict = Field(\n        default_factory=lambda: SecretDict(dict()),\n        title=\"Custom Secret Values\",\n        description=\"A dictionary of secret values to be substituted in other configs.\",\n        examples=['{\"tokenFromSecrets\":\"SomeSecretToken\"}'],\n    )\n\n    def _build_request_args(self, body: str, subject: Optional[str]):\n        \"\"\"Build kwargs for httpx.AsyncClient.request\"\"\"\n        # prepare values\n        values = self.secrets.get_secret_value()\n        # use 'null' when subject is None\n        values.update(\n            {\n                \"subject\": \"null\" if subject is None else subject,\n                \"body\": body,\n                \"name\": self.name,\n            }\n        )\n        # do substution\n        return apply_values(\n            {\n                \"method\": self.method,\n                \"url\": self.url,\n                \"params\": self.params,\n                \"data\": self.form_data,\n                \"json\": self.json_data,\n                \"headers\": self.headers,\n                \"cookies\": self.cookies,\n                \"timeout\": self.timeout,\n            },\n            values,\n        )\n\n    def block_initialization(self) -&gt; None:\n        # check form_data and json_data\n        if self.form_data is not None and self.json_data is not None:\n            raise ValueError(\"both `Form Data` and `JSON Data` provided\")\n        allowed_keys = {\"subject\", \"body\", \"name\"}.union(\n            self.secrets.get_secret_value().keys()\n        )\n        # test template to raise a error early\n        for name in [\"url\", \"params\", \"form_data\", \"json_data\", \"headers\", \"cookies\"]:\n            template = getattr(self, name)\n            if template is None:\n                continue\n            # check for placeholders not in predefined keys and secrets\n            placeholders = find_placeholders(template)\n            for placeholder in placeholders:\n                if placeholder.name not in allowed_keys:\n                    raise KeyError(f\"{name}/{placeholder}\")\n\n    @sync_compatible\n    @instrument_instance_method_call\n    async def notify(self, body: str, subject: Optional[str] = None):\n        import httpx\n\n        request_args = self._build_request_args(body, subject)\n        cookies = request_args.pop(\"cookies\", None)\n        # make request with httpx\n        client = httpx.AsyncClient(\n            headers={\"user-agent\": \"Prefect Notifications\"}, cookies=cookies\n        )\n        async with client:\n            resp = await client.request(**request_args)\n        resp.raise_for_status()\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.DiscordWebhook","title":"<code>DiscordWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Discord webhook. See Apprise notify_Discord docs # noqa</p> <p>Examples:</p> <p>Load a saved Discord webhook and send a message: <pre><code>from prefect.blocks.notifications import DiscordWebhook\n\ndiscord_webhook_block = DiscordWebhook.load(\"BLOCK_NAME\")\n\ndiscord_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class DiscordWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Discord webhook.\n    See [Apprise notify_Discord docs](https://github.com/caronc/apprise/wiki/Notify_Discord) # noqa\n\n    Examples:\n        Load a saved Discord webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import DiscordWebhook\n\n        discord_webhook_block = DiscordWebhook.load(\"BLOCK_NAME\")\n\n        discord_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Discord webhook.\"\n    _block_type_name = \"Discord Webhook\"\n    _block_type_slug = \"discord-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/9e94976c80ef925b66d24e5d14f0d47baa6b8f88-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.DiscordWebhook\"\n\n    webhook_id: SecretStr = Field(\n        default=...,\n        description=(\n            \"The first part of 2 tokens provided to you after creating a\"\n            \" incoming-webhook.\"\n        ),\n    )\n\n    webhook_token: SecretStr = Field(\n        default=...,\n        description=(\n            \"The second part of 2 tokens provided to you after creating a\"\n            \" incoming-webhook.\"\n        ),\n    )\n\n    botname: Optional[str] = Field(\n        title=\"Bot name\",\n        default=None,\n        description=(\n            \"Identify the name of the bot that should issue the message. If one isn't\"\n            \" specified then the default is to just use your account (associated with\"\n            \" the incoming-webhook).\"\n        ),\n    )\n\n    tts: bool = Field(\n        default=False,\n        description=\"Whether to enable Text-To-Speech.\",\n    )\n\n    include_image: bool = Field(\n        default=False,\n        description=(\n            \"Whether to include an image in-line with the message describing the\"\n            \" notification type.\"\n        ),\n    )\n\n    avatar: bool = Field(\n        default=False,\n        description=\"Whether to override the default discord avatar icon.\",\n    )\n\n    avatar_url: Optional[str] = Field(\n        title=\"Avatar URL\",\n        default=False,\n        description=(\n            \"Over-ride the default discord avatar icon URL. By default this is not set\"\n            \" and Apprise chooses the URL dynamically based on the type of message\"\n            \" (info, success, warning, or error).\"\n        ),\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.discord import NotifyDiscord\n\n        url = SecretStr(\n            NotifyDiscord(\n                webhook_id=self.webhook_id.get_secret_value(),\n                webhook_token=self.webhook_token.get_secret_value(),\n                botname=self.botname,\n                tts=self.tts,\n                include_image=self.include_image,\n                avatar=self.avatar,\n                avatar_url=self.avatar_url,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MattermostWebhook","title":"<code>MattermostWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Mattermost webhook. See Apprise notify_Mattermost docs # noqa</p> <p>Examples:</p> <p>Load a saved Mattermost webhook and send a message: <pre><code>from prefect.blocks.notifications import MattermostWebhook\n\nmattermost_webhook_block = MattermostWebhook.load(\"BLOCK_NAME\")\n\nmattermost_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class MattermostWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Mattermost webhook.\n    See [Apprise notify_Mattermost docs](https://github.com/caronc/apprise/wiki/Notify_Mattermost) # noqa\n\n\n    Examples:\n        Load a saved Mattermost webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import MattermostWebhook\n\n        mattermost_webhook_block = MattermostWebhook.load(\"BLOCK_NAME\")\n\n        mattermost_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Mattermost webhook.\"\n    _block_type_name = \"Mattermost Webhook\"\n    _block_type_slug = \"mattermost-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/1350a147130bf82cbc799a5f868d2c0116207736-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MattermostWebhook\"\n\n    hostname: str = Field(\n        default=...,\n        description=\"The hostname of your Mattermost server.\",\n        examples=[\"Mattermost.example.com\"],\n    )\n\n    token: SecretStr = Field(\n        default=...,\n        description=\"The token associated with your Mattermost webhook.\",\n    )\n\n    botname: Optional[str] = Field(\n        title=\"Bot name\",\n        default=None,\n        description=\"The name of the bot that will send the message.\",\n    )\n\n    channels: Optional[List[str]] = Field(\n        default=None,\n        description=\"The channel(s) you wish to notify.\",\n    )\n\n    include_image: bool = Field(\n        default=False,\n        description=\"Whether to include the Apprise status image in the message.\",\n    )\n\n    path: Optional[str] = Field(\n        default=None,\n        description=\"An optional sub-path specification to append to the hostname.\",\n    )\n\n    port: int = Field(\n        default=8065,\n        description=\"The port of your Mattermost server.\",\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.mattermost import NotifyMattermost\n\n        url = SecretStr(\n            NotifyMattermost(\n                token=self.token.get_secret_value(),\n                fullpath=self.path,\n                host=self.hostname,\n                botname=self.botname,\n                channels=self.channels,\n                include_image=self.include_image,\n                port=self.port,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook","title":"<code>MicrosoftTeamsWebhook</code>","text":"<p>               Bases: <code>AppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Microsoft Teams webhook.</p> <p>Examples:</p> <p>Load a saved Teams webhook and send a message: <pre><code>from prefect.blocks.notifications import MicrosoftTeamsWebhook\nteams_webhook_block = MicrosoftTeamsWebhook.load(\"BLOCK_NAME\")\nteams_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class MicrosoftTeamsWebhook(AppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Microsoft Teams webhook.\n\n    Examples:\n        Load a saved Teams webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import MicrosoftTeamsWebhook\n        teams_webhook_block = MicrosoftTeamsWebhook.load(\"BLOCK_NAME\")\n        teams_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Microsoft Teams Webhook\"\n    _block_type_slug = \"ms-teams-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/817efe008a57f0a24f3587414714b563e5e23658-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook\"\n\n    url: SecretStr = Field(\n        ...,\n        title=\"Webhook URL\",\n        description=\"The Microsoft Power Automate (Workflows) URL used to send notifications to Teams.\",\n        examples=[\n            \"https://prod-NO.LOCATION.logic.azure.com:443/workflows/WFID/triggers/manual/paths/invoke?sp=%2Ftriggers%2Fmanual%2Frun&amp;sv=1.0&amp;sig=SIGNATURE\"\n        ],\n    )\n\n    include_image: bool = Field(\n        default=True,\n        description=\"Include an image with the notification.\",\n    )\n\n    wrap: bool = Field(\n        default=True,\n        description=\"Wrap the notification text.\",\n    )\n\n    def block_initialization(self) -&gt; None:\n        \"\"\"see https://github.com/caronc/apprise/pull/1172\"\"\"\n        from apprise.plugins.workflows import NotifyWorkflows\n\n        if not (\n            parsed_url := NotifyWorkflows.parse_native_url(self.url.get_secret_value())\n        ):\n            raise ValueError(\"Invalid Microsoft Teams Workflow URL provided.\")\n\n        parsed_url.update(\n            {\n                \"include_image\": self.include_image,\n                \"wrap\": self.wrap,\n            }\n        )\n\n        self._start_apprise_client(SecretStr(NotifyWorkflows(**parsed_url).url()))\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.MicrosoftTeamsWebhook.block_initialization","title":"<code>block_initialization</code>","text":"<p>see https://github.com/caronc/apprise/pull/1172</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>def block_initialization(self) -&gt; None:\n    \"\"\"see https://github.com/caronc/apprise/pull/1172\"\"\"\n    from apprise.plugins.workflows import NotifyWorkflows\n\n    if not (\n        parsed_url := NotifyWorkflows.parse_native_url(self.url.get_secret_value())\n    ):\n        raise ValueError(\"Invalid Microsoft Teams Workflow URL provided.\")\n\n    parsed_url.update(\n        {\n            \"include_image\": self.include_image,\n            \"wrap\": self.wrap,\n        }\n    )\n\n    self._start_apprise_client(SecretStr(NotifyWorkflows(**parsed_url).url()))\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.OpsgenieWebhook","title":"<code>OpsgenieWebhook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Opsgenie webhook. See Apprise notify_opsgenie docs for more info on formatting the URL.</p> <p>Examples:</p> <p>Load a saved Opsgenie webhook and send a message: <pre><code>from prefect.blocks.notifications import OpsgenieWebhook\nopsgenie_webhook_block = OpsgenieWebhook.load(\"BLOCK_NAME\")\nopsgenie_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class OpsgenieWebhook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Opsgenie webhook.\n    See [Apprise notify_opsgenie docs](https://github.com/caronc/apprise/wiki/Notify_opsgenie)\n    for more info on formatting the URL.\n\n    Examples:\n        Load a saved Opsgenie webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import OpsgenieWebhook\n        opsgenie_webhook_block = OpsgenieWebhook.load(\"BLOCK_NAME\")\n        opsgenie_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided Opsgenie webhook.\"\n\n    _block_type_name = \"Opsgenie Webhook\"\n    _block_type_slug = \"opsgenie-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d8b5bc6244ae6cd83b62ec42f10d96e14d6e9113-280x280.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.OpsgenieWebhook\"\n\n    apikey: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"The API Key associated with your Opsgenie account.\",\n    )\n\n    target_user: Optional[List] = Field(\n        default=None, description=\"The user(s) you wish to notify.\"\n    )\n\n    target_team: Optional[List] = Field(\n        default=None, description=\"The team(s) you wish to notify.\"\n    )\n\n    target_schedule: Optional[List] = Field(\n        default=None, description=\"The schedule(s) you wish to notify.\"\n    )\n\n    target_escalation: Optional[List] = Field(\n        default=None, description=\"The escalation(s) you wish to notify.\"\n    )\n\n    region_name: Literal[\"us\", \"eu\"] = Field(\n        default=\"us\", description=\"The 2-character region code.\"\n    )\n\n    batch: bool = Field(\n        default=False,\n        description=\"Notify all targets in batches (instead of individually).\",\n    )\n\n    tags: Optional[List] = Field(\n        default=None,\n        description=(\n            \"A comma-separated list of tags you can associate with your Opsgenie\"\n            \" message.\"\n        ),\n        examples=['[\"tag1\", \"tag2\"]'],\n    )\n\n    priority: Optional[str] = Field(\n        default=3,\n        description=(\n            \"The priority to associate with the message. It is on a scale between 1\"\n            \" (LOW) and 5 (EMERGENCY).\"\n        ),\n    )\n\n    alias: Optional[str] = Field(\n        default=None, description=\"The alias to associate with the message.\"\n    )\n\n    entity: Optional[str] = Field(\n        default=None, description=\"The entity to associate with the message.\"\n    )\n\n    details: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=\"Additional details composed of key/values pairs.\",\n        examples=['{\"key1\": \"value1\", \"key2\": \"value2\"}'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.opsgenie import NotifyOpsgenie\n\n        targets = []\n        if self.target_user:\n            [targets.append(f\"@{x}\") for x in self.target_user]\n        if self.target_team:\n            [targets.append(f\"#{x}\") for x in self.target_team]\n        if self.target_schedule:\n            [targets.append(f\"*{x}\") for x in self.target_schedule]\n        if self.target_escalation:\n            [targets.append(f\"^{x}\") for x in self.target_escalation]\n        url = SecretStr(\n            NotifyOpsgenie(\n                apikey=self.apikey.get_secret_value(),\n                targets=targets,\n                region_name=self.region_name,\n                details=self.details,\n                priority=self.priority,\n                alias=self.alias,\n                entity=self.entity,\n                batch=self.batch,\n                tags=self.tags,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.PagerDutyWebHook","title":"<code>PagerDutyWebHook</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided PagerDuty webhook. See Apprise notify_pagerduty docs for more info on formatting the URL.</p> <p>Examples:</p> <p>Load a saved PagerDuty webhook and send a message: <pre><code>from prefect.blocks.notifications import PagerDutyWebHook\npagerduty_webhook_block = PagerDutyWebHook.load(\"BLOCK_NAME\")\npagerduty_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class PagerDutyWebHook(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided PagerDuty webhook.\n    See [Apprise notify_pagerduty docs](https://github.com/caronc/apprise/wiki/Notify_pagerduty)\n    for more info on formatting the URL.\n\n    Examples:\n        Load a saved PagerDuty webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import PagerDutyWebHook\n        pagerduty_webhook_block = PagerDutyWebHook.load(\"BLOCK_NAME\")\n        pagerduty_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via a provided PagerDuty webhook.\"\n\n    _block_type_name = \"Pager Duty Webhook\"\n    _block_type_slug = \"pager-duty-webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8dbf37d17089c1ce531708eac2e510801f7b3aee-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.PagerDutyWebHook\"\n\n    # The default cannot be prefect_default because NotifyPagerDuty's\n    # PAGERDUTY_SEVERITY_MAP only has these notify types defined as keys\n    notify_type: Literal[\"info\", \"success\", \"warning\", \"failure\"] = Field(\n        default=\"info\", description=\"The severity of the notification.\"\n    )\n\n    integration_key: SecretStr = Field(\n        default=...,\n        description=(\n            \"This can be found on the Events API V2 \"\n            \"integration's detail page, and is also referred to as a Routing Key. \"\n            \"This must be provided alongside `api_key`, but will error if provided \"\n            \"alongside `url`.\"\n        ),\n    )\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=(\n            \"This can be found under Integrations. \"\n            \"This must be provided alongside `integration_key`, but will error if \"\n            \"provided alongside `url`.\"\n        ),\n    )\n\n    source: Optional[str] = Field(\n        default=\"Prefect\", description=\"The source string as part of the payload.\"\n    )\n\n    component: str = Field(\n        default=\"Notification\",\n        description=\"The component string as part of the payload.\",\n    )\n\n    group: Optional[str] = Field(\n        default=None, description=\"The group string as part of the payload.\"\n    )\n\n    class_id: Optional[str] = Field(\n        default=None,\n        title=\"Class ID\",\n        description=\"The class string as part of the payload.\",\n    )\n\n    region_name: Literal[\"us\", \"eu\"] = Field(\n        default=\"us\", description=\"The region name.\"\n    )\n\n    clickable_url: Optional[AnyHttpUrl] = Field(\n        default=None,\n        title=\"Clickable URL\",\n        description=\"A clickable URL to associate with the notice.\",\n    )\n\n    include_image: bool = Field(\n        default=True,\n        description=\"Associate the notification status via a represented icon.\",\n    )\n\n    custom_details: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=\"Additional details to include as part of the payload.\",\n        examples=['{\"disk_space_left\": \"145GB\"}'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.pagerduty import NotifyPagerDuty\n\n        url = SecretStr(\n            NotifyPagerDuty(\n                apikey=self.api_key.get_secret_value(),\n                integrationkey=self.integration_key.get_secret_value(),\n                source=self.source,\n                component=self.component,\n                group=self.group,\n                class_id=self.class_id,\n                region_name=self.region_name,\n                click=self.clickable_url,\n                include_image=self.include_image,\n                details=self.custom_details,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SendgridEmail","title":"<code>SendgridEmail</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via any sendgrid account. See Apprise Notify_sendgrid docs</p> <p>Examples:</p> <p>Load a saved Sendgrid and send a email message: ```python from prefect.blocks.notifications import SendgridEmail</p> <p>sendgrid_block = SendgridEmail.load(\"BLOCK_NAME\")</p> <p>sendgrid_block.notify(\"Hello from Prefect!\")</p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class SendgridEmail(AbstractAppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via any sendgrid account.\n    See [Apprise Notify_sendgrid docs](https://github.com/caronc/apprise/wiki/Notify_Sendgrid)\n\n    Examples:\n        Load a saved Sendgrid and send a email message:\n        ```python\n        from prefect.blocks.notifications import SendgridEmail\n\n        sendgrid_block = SendgridEmail.load(\"BLOCK_NAME\")\n\n        sendgrid_block.notify(\"Hello from Prefect!\")\n    \"\"\"\n\n    _description = \"Enables sending notifications via Sendgrid email service.\"\n    _block_type_name = \"Sendgrid Email\"\n    _block_type_slug = \"sendgrid-email\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/82bc6ed16ca42a2252a5512c72233a253b8a58eb-250x250.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SendgridEmail\"\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"The API Key associated with your sendgrid account.\",\n    )\n\n    sender_email: str = Field(\n        title=\"Sender email id\",\n        description=\"The sender email id.\",\n        examples=[\"test-support@gmail.com\"],\n    )\n\n    to_emails: List[str] = Field(\n        default=...,\n        title=\"Recipient emails\",\n        description=\"Email ids of all recipients.\",\n        examples=['\"recipient1@gmail.com\"'],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.sendgrid import NotifySendGrid\n\n        url = SecretStr(\n            NotifySendGrid(\n                apikey=self.api_key.get_secret_value(),\n                from_email=self.sender_email,\n                targets=self.to_emails,\n            ).url()\n        )\n\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SlackWebhook","title":"<code>SlackWebhook</code>","text":"<p>               Bases: <code>AppriseNotificationBlock</code></p> <p>Enables sending notifications via a provided Slack webhook.</p> <p>Examples:</p> <p>Load a saved Slack webhook and send a message: <pre><code>from prefect.blocks.notifications import SlackWebhook\n\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nslack_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class SlackWebhook(AppriseNotificationBlock):\n    \"\"\"\n    Enables sending notifications via a provided Slack webhook.\n\n    Examples:\n        Load a saved Slack webhook and send a message:\n        ```python\n        from prefect.blocks.notifications import SlackWebhook\n\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        slack_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Slack Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c1965ecbf8704ee1ea20d77786de9a41ce1087d1-500x500.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.SlackWebhook\"\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Slack incoming webhook URL used to send notifications.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.TwilioSMS","title":"<code>TwilioSMS</code>","text":"<p>               Bases: <code>AbstractAppriseNotificationBlock</code></p> <p>Enables sending notifications via Twilio SMS. Find more on sending Twilio SMS messages in the docs.</p> <p>Examples:</p> <p>Load a saved <code>TwilioSMS</code> block and send a message: <pre><code>from prefect.blocks.notifications import TwilioSMS\ntwilio_webhook_block = TwilioSMS.load(\"BLOCK_NAME\")\ntwilio_webhook_block.notify(\"Hello from Prefect!\")\n</code></pre></p> Source code in <code>prefect/blocks/notifications.py</code> <pre><code>class TwilioSMS(AbstractAppriseNotificationBlock):\n    \"\"\"Enables sending notifications via Twilio SMS.\n    Find more on sending Twilio SMS messages in the [docs](https://www.twilio.com/docs/sms).\n\n    Examples:\n        Load a saved `TwilioSMS` block and send a message:\n        ```python\n        from prefect.blocks.notifications import TwilioSMS\n        twilio_webhook_block = TwilioSMS.load(\"BLOCK_NAME\")\n        twilio_webhook_block.notify(\"Hello from Prefect!\")\n        ```\n    \"\"\"\n\n    _description = \"Enables sending notifications via Twilio SMS.\"\n    _block_type_name = \"Twilio SMS\"\n    _block_type_slug = \"twilio-sms\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8bd8777999f82112c09b9c8d57083ac75a4a0d65-250x250.png\"  # noqa\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/notifications/#prefect.blocks.notifications.TwilioSMS\"\n\n    account_sid: str = Field(\n        default=...,\n        description=(\n            \"The Twilio Account SID - it can be found on the homepage \"\n            \"of the Twilio console.\"\n        ),\n    )\n\n    auth_token: SecretStr = Field(\n        default=...,\n        description=(\n            \"The Twilio Authentication Token - \"\n            \"it can be found on the homepage of the Twilio console.\"\n        ),\n    )\n\n    from_phone_number: str = Field(\n        default=...,\n        description=\"The valid Twilio phone number to send the message from.\",\n        examples=[\"18001234567\"],\n    )\n\n    to_phone_numbers: List[str] = Field(\n        default=...,\n        description=\"A list of valid Twilio phone number(s) to send the message to.\",\n        # not wrapped in brackets because of the way UI displays examples; in code should be [\"18004242424\"]\n        examples=[\"18004242424\"],\n    )\n\n    def block_initialization(self) -&gt; None:\n        from apprise.plugins.twilio import NotifyTwilio\n\n        url = SecretStr(\n            NotifyTwilio(\n                account_sid=self.account_sid,\n                auth_token=self.auth_token.get_secret_value(),\n                source=self.from_phone_number,\n                targets=self.to_phone_numbers,\n            ).url()\n        )\n        self._start_apprise_client(url)\n</code></pre>","tags":["Python API","blocks","notifications"]},{"location":"api-ref/prefect/blocks/system/","title":"system","text":"","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system","title":"<code>prefect.blocks.system</code>","text":"","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.DateTime","title":"<code>DateTime</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a datetime</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>DateTimeTZ</code> <p>An ISO 8601-compatible datetime value.</p> Example <p>Load a stored JSON value: <pre><code>from prefect.blocks.system import DateTime\n\ndata_time_block = DateTime.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class DateTime(Block):\n    \"\"\"\n    A block that represents a datetime\n\n    Attributes:\n        value: An ISO 8601-compatible datetime value.\n\n    Example:\n        Load a stored JSON value:\n        ```python\n        from prefect.blocks.system import DateTime\n\n        data_time_block = DateTime.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Date Time\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/8b3da9a6621e92108b8e6a75b82e15374e170ff7-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.DateTime\"\n\n    value: DateTimeTZ = Field(\n        default=...,\n        description=\"An ISO 8601-compatible datetime value.\",\n    )\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.JSON","title":"<code>JSON</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents JSON</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>Any</code> <p>A JSON-compatible value.</p> Example <p>Load a stored JSON value: <pre><code>from prefect.blocks.system import JSON\n\njson_block = JSON.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class JSON(Block):\n    \"\"\"\n    A block that represents JSON\n\n    Attributes:\n        value: A JSON-compatible value.\n\n    Example:\n        Load a stored JSON value:\n        ```python\n        from prefect.blocks.system import JSON\n\n        json_block = JSON.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/4fcef2294b6eeb423b1332d1ece5156bf296ff96-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.JSON\"\n\n    value: Any = Field(default=..., description=\"A JSON-compatible value.\")\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.Secret","title":"<code>Secret</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a secret value. The value stored in this block will be obfuscated when this block is logged or shown in the UI.</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>SecretStr</code> <p>A string value that should be kept secret.</p> Example <pre><code>from prefect.blocks.system import Secret\n\nsecret_block = Secret.load(\"BLOCK_NAME\")\n\n# Access the stored secret\nsecret_block.get()\n</code></pre> Source code in <code>prefect/blocks/system.py</code> <pre><code>class Secret(Block):\n    \"\"\"\n    A block that represents a secret value. The value stored in this block will be obfuscated when\n    this block is logged or shown in the UI.\n\n    Attributes:\n        value: A string value that should be kept secret.\n\n    Example:\n        ```python\n        from prefect.blocks.system import Secret\n\n        secret_block = Secret.load(\"BLOCK_NAME\")\n\n        # Access the stored secret\n        secret_block.get()\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c6f20e556dd16effda9df16551feecfb5822092b-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.Secret\"\n\n    value: SecretStr = Field(\n        default=..., description=\"A string value that should be kept secret.\"\n    )\n\n    def get(self):\n        return self.value.get_secret_value()\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/system/#prefect.blocks.system.String","title":"<code>String</code>","text":"<p>               Bases: <code>Block</code></p> <p>A block that represents a string</p> <p>Attributes:</p> Name Type Description <code>value</code> <code>str</code> <p>A string value.</p> Example <p>Load a stored string value: <pre><code>from prefect.blocks.system import String\n\nstring_block = String.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect/blocks/system.py</code> <pre><code>class String(Block):\n    \"\"\"\n    A block that represents a string\n\n    Attributes:\n        value: A string value.\n\n    Example:\n        Load a stored string value:\n        ```python\n        from prefect.blocks.system import String\n\n        string_block = String.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c262ea2c80a2c043564e8763f3370c3db5a6b3e6-48x48.png\"\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/system/#prefect.blocks.system.String\"\n\n    value: str = Field(default=..., description=\"A string value.\")\n</code></pre>","tags":["Python API","blocks","secret","config","json"]},{"location":"api-ref/prefect/blocks/webhook/","title":"webhook","text":"","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook","title":"<code>prefect.blocks.webhook</code>","text":"","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook","title":"<code>Webhook</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block that enables calling webhooks.</p> Source code in <code>prefect/blocks/webhook.py</code> <pre><code>class Webhook(Block):\n    \"\"\"\n    Block that enables calling webhooks.\n    \"\"\"\n\n    _block_type_name = \"Webhook\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c7247cb359eb6cf276734d4b1fbf00fb8930e89e-250x250.png\"  # type: ignore\n    _documentation_url = \"https://docs.prefect.io/api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook\"\n\n    method: Literal[\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"] = Field(\n        default=\"POST\", description=\"The webhook request method. Defaults to `POST`.\"\n    )\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"The webhook URL.\",\n        examples=[\"https://hooks.slack.com/XXX\"],\n    )\n\n    headers: SecretDict = Field(\n        default_factory=lambda: SecretDict(dict()),\n        title=\"Webhook Headers\",\n        description=\"A dictionary of headers to send with the webhook request.\",\n    )\n\n    def block_initialization(self):\n        self._client = AsyncClient(transport=_http_transport)\n\n    async def call(self, payload: Optional[dict] = None) -&gt; Response:\n        \"\"\"\n        Call the webhook.\n\n        Args:\n            payload: an optional payload to send when calling the webhook.\n        \"\"\"\n        async with self._client:\n            return await self._client.request(\n                method=self.method,\n                url=self.url.get_secret_value(),\n                headers=self.headers.get_secret_value(),\n                json=payload,\n            )\n</code></pre>","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/blocks/webhook/#prefect.blocks.webhook.Webhook.call","title":"<code>call</code>  <code>async</code>","text":"<p>Call the webhook.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Optional[dict]</code> <p>an optional payload to send when calling the webhook.</p> <code>None</code> Source code in <code>prefect/blocks/webhook.py</code> <pre><code>async def call(self, payload: Optional[dict] = None) -&gt; Response:\n    \"\"\"\n    Call the webhook.\n\n    Args:\n        payload: an optional payload to send when calling the webhook.\n    \"\"\"\n    async with self._client:\n        return await self._client.request(\n            method=self.method,\n            url=self.url.get_secret_value(),\n            headers=self.headers.get_secret_value(),\n            json=payload,\n        )\n</code></pre>","tags":["Python API","blocks","webhook"]},{"location":"api-ref/prefect/cli/agent/","title":"agent","text":"","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/agent/#prefect.cli.agent","title":"<code>prefect.cli.agent</code>","text":"<p>Command line interface for working with agent services</p>","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/agent/#prefect.cli.agent.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start an agent process to poll one or more work queues for flow runs.</p> Source code in <code>prefect/cli/agent.py</code> <pre><code>@agent_app.command()\nasync def start(\n    # deprecated main argument\n    work_queue: str = typer.Argument(\n        None,\n        show_default=False,\n        help=\"DEPRECATED: A work queue name or ID\",\n    ),\n    work_queues: List[str] = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the agent to pull from.\",\n    ),\n    work_queue_prefix: List[str] = typer.Option(\n        None,\n        \"-m\",\n        \"--match\",\n        help=(\n            \"Dynamically matches work queue names with the specified prefix for the\"\n            \" agent to pull from,for example `dev-` will match all work queues with a\"\n            \" name that starts with `dev-`\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"A work pool name for the agent to pull from.\",\n    ),\n    hide_welcome: bool = typer.Option(False, \"--hide-welcome\"),\n    api: str = SettingsOption(PREFECT_API_URL),\n    run_once: bool = typer.Option(\n        False, help=\"Run the agent loop once, instead of forever.\"\n    ),\n    prefetch_seconds: int = SettingsOption(PREFECT_AGENT_PREFETCH_SECONDS),\n    # deprecated tags\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"DEPRECATED: One or more optional tags that will be used to create a work\"\n            \" queue. This option will be removed on 2023-02-23.\"\n        ),\n    ),\n    limit: int = typer.Option(\n        None,\n        \"-l\",\n        \"--limit\",\n        help=\"Maximum number of flow runs to start simultaneously.\",\n    ),\n):\n    \"\"\"\n    Start an agent process to poll one or more work queues for flow runs.\n    \"\"\"\n    work_queues = work_queues or []\n\n    if work_queue is not None:\n        # try to treat the work_queue as a UUID\n        try:\n            async with get_client() as client:\n                q = await client.read_work_queue(UUID(work_queue))\n                work_queue = q.name\n        # otherwise treat it as a string name\n        except (TypeError, ValueError):\n            pass\n        work_queues.append(work_queue)\n        app.console.print(\n            (\n                \"Agents now support multiple work queues. Instead of passing a single\"\n                \" argument, provide work queue names with the `-q` or `--work-queue`\"\n                f\" flag: `prefect agent start -q {work_queue}`\\n\"\n            ),\n            style=\"blue\",\n        )\n    if work_pool_name:\n        is_queues_paused = await _check_work_queues_paused(\n            work_pool_name=work_pool_name,\n            work_queues=work_queues,\n        )\n        if is_queues_paused:\n            queue_scope = (\n                \"The 'default' work queue\"\n                if not work_queues\n                else \"Specified work queue(s)\"\n            )\n            app.console.print(\n                (\n                    f\"{queue_scope} in the work pool {work_pool_name!r} is currently\"\n                    \" paused. This agent will not execute any flow runs until the work\"\n                    \" queue(s) are unpaused.\"\n                ),\n                style=\"yellow\",\n            )\n\n    if not work_queues and not tags and not work_queue_prefix and not work_pool_name:\n        exit_with_error(\"No work queues provided!\", style=\"red\")\n    elif bool(work_queues) + bool(tags) + bool(work_queue_prefix) &gt; 1:\n        exit_with_error(\n            \"Only one of `work_queues`, `match`, or `tags` can be provided.\",\n            style=\"red\",\n        )\n    if work_pool_name and tags:\n        exit_with_error(\n            \"`tag` and `pool` options cannot be used together.\", style=\"red\"\n        )\n\n    if tags:\n        work_queue_name = f\"Agent queue {'-'.join(sorted(tags))}\"\n        app.console.print(\n            (\n                \"`tags` are deprecated. For backwards-compatibility with old versions\"\n                \" of Prefect, this agent will create a work queue named\"\n                f\" `{work_queue_name}` that uses legacy tag-based matching. This option\"\n                \" will be removed on 2023-02-23.\"\n            ),\n            style=\"red\",\n        )\n\n        async with get_client() as client:\n            try:\n                work_queue = await client.read_work_queue_by_name(work_queue_name)\n                if work_queue.filter is None:\n                    # ensure the work queue has legacy (deprecated) tag-based behavior\n                    await client.update_work_queue(filter=dict(tags=tags))\n            except ObjectNotFound:\n                # if the work queue doesn't already exist, we create it with tags\n                # to enable legacy (deprecated) tag-matching behavior\n                await client.create_work_queue(name=work_queue_name, tags=tags)\n\n        work_queues = [work_queue_name]\n\n    if not hide_welcome:\n        if api:\n            app.console.print(\n                f\"Starting v{prefect.__version__} agent connected to {api}...\"\n            )\n        else:\n            app.console.print(\n                f\"Starting v{prefect.__version__} agent with ephemeral API...\"\n            )\n\n    agent_process_id = os.getpid()\n    setup_signal_handlers_agent(\n        agent_process_id, \"the Prefect agent\", app.console.print\n    )\n\n    async with PrefectAgent(\n        work_queues=work_queues,\n        work_queue_prefix=work_queue_prefix,\n        work_pool_name=work_pool_name,\n        prefetch_seconds=prefetch_seconds,\n        limit=limit,\n    ) as agent:\n        if not hide_welcome:\n            app.console.print(ascii_name)\n            if work_pool_name:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"work pool '{work_pool_name}'...\"\n                )\n            elif work_queue_prefix:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"queue(s) that start with the prefix: {work_queue_prefix}...\"\n                )\n            else:\n                app.console.print(\n                    \"Agent started! Looking for work from \"\n                    f\"queue(s): {', '.join(work_queues)}...\"\n                )\n\n        try:\n            async with anyio.create_task_group() as tg:\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        agent.get_and_submit_flow_runs,\n                        PREFECT_AGENT_QUERY_INTERVAL.value(),\n                        printer=app.console.print,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                        backoff=4,  # Up to ~1 minute interval during backoff\n                    )\n                )\n\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        agent.check_for_cancelled_flow_runs,\n                        PREFECT_AGENT_QUERY_INTERVAL.value() * 2,\n                        printer=app.console.print,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n        except CancelledError:\n            logger.debug(\"Agent task group cancelled\")\n\n    app.console.print(\"Agent stopped!\")\n</code></pre>","tags":["Python API","agents","CLI"]},{"location":"api-ref/prefect/cli/artifact/","title":"artifact","text":"","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact","title":"<code>prefect.cli.artifact</code>","text":"","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete an artifact.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>Optional[str]</code> <p>the key of the artifact to delete</p> <code>Argument(None, help='The key of the artifact to delete.')</code> <p>Examples:</p> <p>$ prefect artifact delete \"my-artifact\"</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"delete\")\nasync def delete(\n    key: Optional[str] = typer.Argument(\n        None, help=\"The key of the artifact to delete.\"\n    ),\n    artifact_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"The ID of the artifact to delete.\"\n    ),\n):\n    \"\"\"\n    Delete an artifact.\n\n    Arguments:\n        key: the key of the artifact to delete\n\n    Examples:\n        $ prefect artifact delete \"my-artifact\"\n    \"\"\"\n    if key and artifact_id:\n        exit_with_error(\"Please provide either a key or an artifact_id but not both.\")\n\n    async with get_client() as client:\n        if artifact_id is not None:\n            try:\n                confirm_delete = typer.confirm(\n                    (\n                        \"Are you sure you want to delete artifact with id\"\n                        f\" {artifact_id!r}?\"\n                    ),\n                    default=False,\n                )\n                if not confirm_delete:\n                    exit_with_error(\"Deletion aborted.\")\n\n                await client.delete_artifact(artifact_id)\n                exit_with_success(f\"Deleted artifact with id {artifact_id!r}.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Artifact with id {artifact_id!r} not found!\")\n\n        elif key is not None:\n            artifacts = await client.read_artifacts(\n                artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n            )\n            if not artifacts:\n                exit_with_error(\n                    f\"Artifact with key {key!r} not found. You can also specify an\"\n                    \" artifact id with the --id flag.\"\n                )\n\n            confirm_delete = typer.confirm(\n                (\n                    f\"Are you sure you want to delete {len(artifacts)} artifact(s) with\"\n                    f\" key {key!r}?\"\n                ),\n                default=False,\n            )\n            if not confirm_delete:\n                exit_with_error(\"Deletion aborted.\")\n\n            for a in artifacts:\n                await client.delete_artifact(a.id)\n\n            exit_with_success(f\"Deleted {len(artifacts)} artifact(s) with key {key!r}.\")\n\n        else:\n            exit_with_error(\"Please provide a key or an artifact_id.\")\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<pre><code>View details about an artifact.\n\nArguments:\n    key: the key of the artifact to inspect\n\nExamples:\n    $ prefect artifact inspect \"my-artifact\"\n   [\n    {\n        'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',\n        'created': '2023-03-21T21:40:09.895910+00:00',\n        'updated': '2023-03-21T21:40:09.895910+00:00',\n        'key': 'my-artifact',\n        'type': 'markdown',\n        'description': None,\n        'data': 'my markdown',\n        'metadata_': None,\n        'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',\n        'task_run_id': None\n    },\n    {\n        'id': '57f235b5-2576-45a5-bd93-c829c2900966',\n        'created': '2023-03-27T23:16:15.536434+00:00',\n        'updated': '2023-03-27T23:16:15.536434+00:00',\n        'key': 'my-artifact',\n        'type': 'markdown',\n        'description': 'my-artifact-description',\n        'data': 'my markdown',\n        'metadata_': None,\n        'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',\n        'task_run_id': None\n    }\n</code></pre> <p>]</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"inspect\")\nasync def inspect(\n    key: str,\n    limit: int = typer.Option(\n        10,\n        \"--limit\",\n        help=\"The maximum number of artifacts to return.\",\n    ),\n):\n    \"\"\"\n        View details about an artifact.\n\n        Arguments:\n            key: the key of the artifact to inspect\n\n        Examples:\n            $ prefect artifact inspect \"my-artifact\"\n           [\n            {\n                'id': 'ba1d67be-0bd7-452e-8110-247fe5e6d8cc',\n                'created': '2023-03-21T21:40:09.895910+00:00',\n                'updated': '2023-03-21T21:40:09.895910+00:00',\n                'key': 'my-artifact',\n                'type': 'markdown',\n                'description': None,\n                'data': 'my markdown',\n                'metadata_': None,\n                'flow_run_id': '8dc54b6f-6e24-4586-a05c-e98c6490cb98',\n                'task_run_id': None\n            },\n            {\n                'id': '57f235b5-2576-45a5-bd93-c829c2900966',\n                'created': '2023-03-27T23:16:15.536434+00:00',\n                'updated': '2023-03-27T23:16:15.536434+00:00',\n                'key': 'my-artifact',\n                'type': 'markdown',\n                'description': 'my-artifact-description',\n                'data': 'my markdown',\n                'metadata_': None,\n                'flow_run_id': 'ffa91051-f249-48c1-ae0f-4754fcb7eb29',\n                'task_run_id': None\n            }\n    ]\n    \"\"\"\n\n    async with get_client() as client:\n        artifacts = await client.read_artifacts(\n            limit=limit,\n            sort=ArtifactSort.UPDATED_DESC,\n            artifact_filter=ArtifactFilter(key=ArtifactFilterKey(any_=[key])),\n        )\n        if not artifacts:\n            exit_with_error(f\"Artifact {key!r} not found.\")\n\n        artifacts = [a.dict(json_compatible=True) for a in artifacts]\n\n        app.console.print(Pretty(artifacts))\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/artifact/#prefect.cli.artifact.list_artifacts","title":"<code>list_artifacts</code>  <code>async</code>","text":"<p>List artifacts.</p> Source code in <code>prefect/cli/artifact.py</code> <pre><code>@artifact_app.command(\"ls\")\nasync def list_artifacts(\n    limit: int = typer.Option(\n        100,\n        \"--limit\",\n        help=\"The maximum number of artifacts to return.\",\n    ),\n    all: bool = typer.Option(\n        False,\n        \"--all\",\n        \"-a\",\n        help=\"Whether or not to only return the latest version of each artifact.\",\n    ),\n):\n    \"\"\"\n    List artifacts.\n    \"\"\"\n    table = Table(\n        title=\"Artifacts\",\n        caption=\"List Artifacts using `prefect artifact ls`\",\n        show_header=True,\n    )\n\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Key\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Type\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Updated\", style=\"blue\", no_wrap=True)\n\n    async with get_client() as client:\n        if all:\n            artifacts = await client.read_artifacts(\n                sort=ArtifactSort.KEY_ASC,\n                limit=limit,\n            )\n\n            for artifact in sorted(artifacts, key=lambda x: f\"{x.key}\"):\n                table.add_row(\n                    str(artifact.id),\n                    artifact.key,\n                    artifact.type,\n                    pendulum.instance(artifact.updated).diff_for_humans(),\n                )\n\n        else:\n            artifacts = await client.read_latest_artifacts(\n                sort=ArtifactCollectionSort.KEY_ASC,\n                limit=limit,\n            )\n\n            for artifact in sorted(artifacts, key=lambda x: f\"{x.key}\"):\n                table.add_row(\n                    str(artifact.latest_id),\n                    artifact.key,\n                    artifact.type,\n                    pendulum.instance(artifact.updated).diff_for_humans(),\n                )\n\n        app.console.print(table)\n</code></pre>","tags":["Python API","artifacts","CLI"]},{"location":"api-ref/prefect/cli/block/","title":"block","text":"","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block","title":"<code>prefect.cli.block</code>","text":"<p>Command line interface for working with blocks.</p>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_create","title":"<code>block_create</code>  <code>async</code>","text":"<p>Generate a link to the Prefect UI to create a block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"create\")\nasync def block_create(\n    block_type_slug: str = typer.Argument(\n        ...,\n        help=\"A block type slug. View available types with: prefect block type ls\",\n        show_default=False,\n    ),\n):\n    \"\"\"\n    Generate a link to the Prefect UI to create a block.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(block_type_slug)\n        except ObjectNotFound:\n            app.console.print(f\"[red]Block type {block_type_slug!r} not found![/red]\")\n            block_types = await client.read_block_types()\n            slugs = {block_type.slug for block_type in block_types}\n            app.console.print(f\"Available block types: {', '.join(slugs)}\")\n            raise typer.Exit(1)\n\n        if not PREFECT_UI_URL:\n            exit_with_error(\n                \"Prefect must be configured to use a hosted Prefect server or \"\n                \"Prefect Cloud to display the Prefect UI\"\n            )\n\n        block_link = f\"{PREFECT_UI_URL.value()}/blocks/catalog/{block_type.slug}/create\"\n        app.console.print(\n            f\"Create a {block_type_slug} block: {block_link}\",\n        )\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_delete","title":"<code>block_delete</code>  <code>async</code>","text":"<p>Delete a configured block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"delete\")\nasync def block_delete(\n    slug: Optional[str] = typer.Argument(\n        None, help=\"A block slug. Formatted as '&lt;BLOCK_TYPE_SLUG&gt;/&lt;BLOCK_NAME&gt;'\"\n    ),\n    block_id: Optional[str] = typer.Option(None, \"--id\", help=\"A block id.\"),\n):\n    \"\"\"\n    Delete a configured block.\n    \"\"\"\n    async with get_client() as client:\n        if slug is None and block_id is not None:\n            try:\n                await client.delete_block_document(block_id)\n                exit_with_success(f\"Deleted Block '{block_id}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {block_id!r} not found!\")\n        elif slug is not None:\n            if \"/\" not in slug:\n                exit_with_error(\n                    f\"{slug!r} is not valid. Slug must contain a '/', e.g. 'json/my-json-block'\"\n                )\n            block_type_slug, block_document_name = slug.split(\"/\")\n            try:\n                block_document = await client.read_block_document_by_name(\n                    block_document_name, block_type_slug, include_secrets=False\n                )\n                await client.delete_block_document(block_document.id)\n                exit_with_success(f\"Deleted Block '{slug}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Block {slug!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a block slug or id\")\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_inspect","title":"<code>block_inspect</code>  <code>async</code>","text":"<p>Displays details about a configured block.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"inspect\")\nasync def block_inspect(\n    slug: Optional[str] = typer.Argument(\n        None, help=\"A Block slug: &lt;BLOCK_TYPE_SLUG&gt;/&lt;BLOCK_NAME&gt;\"\n    ),\n    block_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"A Block id to search for if no slug is given\"\n    ),\n):\n    \"\"\"\n    Displays details about a configured block.\n    \"\"\"\n    async with get_client() as client:\n        if slug is None and block_id is not None:\n            try:\n                block_document = await client.read_block_document(\n                    block_id, include_secrets=False\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {block_id!r} not found!\")\n        elif slug is not None:\n            if \"/\" not in slug:\n                exit_with_error(\n                    f\"{slug!r} is not valid. Slug must contain a '/', e.g. 'json/my-json-block'\"\n                )\n            block_type_slug, block_document_name = slug.split(\"/\")\n            try:\n                block_document = await client.read_block_document_by_name(\n                    block_document_name, block_type_slug, include_secrets=False\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"Block {slug!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a block slug or id\")\n        app.console.print(display_block(block_document))\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.block_ls","title":"<code>block_ls</code>  <code>async</code>","text":"<p>View all configured blocks.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command(\"ls\")\nasync def block_ls():\n    \"\"\"\n    View all configured blocks.\n    \"\"\"\n    async with get_client() as client:\n        blocks = await client.read_block_documents()\n\n    table = Table(\n        title=\"Blocks\", caption=\"List Block Types using `prefect block type ls`\"\n    )\n    table.add_column(\"ID\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Type\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Slug\", style=\"blue\", no_wrap=True)\n\n    for block in sorted(blocks, key=lambda x: f\"{x.block_type.slug}/{x.name}\"):\n        table.add_row(\n            str(block.id),\n            block.block_type.name,\n            str(block.name),\n            f\"{block.block_type.slug}/{block.name}\",\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.blocktype_delete","title":"<code>blocktype_delete</code>  <code>async</code>","text":"<p>Delete an unprotected Block Type.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"delete\")\nasync def blocktype_delete(\n    slug: str = typer.Argument(..., help=\"A Block type slug\"),\n):\n    \"\"\"\n    Delete an unprotected Block Type.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(slug)\n            await client.delete_block_type(block_type.id)\n            exit_with_success(f\"Deleted Block Type '{slug}'.\")\n        except ObjectNotFound:\n            exit_with_error(f\"Block Type {slug!r} not found!\")\n        except ProtectedBlockError:\n            exit_with_error(f\"Block Type {slug!r} is a protected block!\")\n        except PrefectHTTPStatusError:\n            exit_with_error(f\"Cannot delete Block Type {slug!r}!\")\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.blocktype_inspect","title":"<code>blocktype_inspect</code>  <code>async</code>","text":"<p>Display details about a block type.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"inspect\")\nasync def blocktype_inspect(\n    slug: str = typer.Argument(..., help=\"A block type slug\"),\n):\n    \"\"\"\n    Display details about a block type.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            block_type = await client.read_block_type_by_slug(slug)\n        except ObjectNotFound:\n            exit_with_error(f\"Block type {slug!r} not found!\")\n\n        app.console.print(display_block_type(block_type))\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.list_types","title":"<code>list_types</code>  <code>async</code>","text":"<p>List all block types.</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocktypes_app.command(\"ls\")\nasync def list_types():\n    \"\"\"\n    List all block types.\n    \"\"\"\n    async with get_client() as client:\n        block_types = await client.read_block_types()\n\n    table = Table(\n        title=\"Block Types\",\n        show_lines=True,\n    )\n\n    table.add_column(\"Block Type Slug\", style=\"italic cyan\", no_wrap=True)\n    table.add_column(\"Description\", style=\"blue\", no_wrap=False, justify=\"left\")\n    table.add_column(\n        \"Generate creation link\", style=\"italic cyan\", no_wrap=False, justify=\"left\"\n    )\n\n    for blocktype in sorted(block_types, key=lambda x: x.name):\n        table.add_row(\n            str(blocktype.slug),\n            (\n                str(blocktype.description.splitlines()[0].partition(\".\")[0])\n                if blocktype.description is not None\n                else \"\"\n            ),\n            f\"prefect block create {blocktype.slug}\",\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/block/#prefect.cli.block.register","title":"<code>register</code>  <code>async</code>","text":"<p>Register blocks types within a module or file.</p> <p>This makes the blocks available for configuration via the UI. If a block type has already been registered, its registration will be updated to match the block's current definition.</p> <p>\b Examples:     \b     Register block types in a Python module:     $ prefect block register -m prefect_aws.credentials     \b     Register block types in a .py file:     $ prefect block register -f my_blocks.py</p> Source code in <code>prefect/cli/block.py</code> <pre><code>@blocks_app.command()\nasync def register(\n    module_name: Optional[str] = typer.Option(\n        None,\n        \"--module\",\n        \"-m\",\n        help=\"Python module containing block types to be registered\",\n    ),\n    file_path: Optional[Path] = typer.Option(\n        None,\n        \"--file\",\n        \"-f\",\n        help=\"Path to .py file containing block types to be registered\",\n    ),\n):\n    \"\"\"\n    Register blocks types within a module or file.\n\n    This makes the blocks available for configuration via the UI.\n    If a block type has already been registered, its registration will be updated to\n    match the block's current definition.\n\n    \\b\n    Examples:\n        \\b\n        Register block types in a Python module:\n        $ prefect block register -m prefect_aws.credentials\n        \\b\n        Register block types in a .py file:\n        $ prefect block register -f my_blocks.py\n    \"\"\"\n    # Handles if both options are specified or if neither are specified\n    if not (bool(file_path) ^ bool(module_name)):\n        exit_with_error(\n            \"Please specify either a module or a file containing blocks to be\"\n            \" registered, but not both.\"\n        )\n\n    if module_name:\n        try:\n            imported_module = import_module(name=module_name)\n        except ModuleNotFoundError:\n            exit_with_error(\n                f\"Unable to load {module_name}. Please make sure the module is \"\n                \"installed in your current environment.\"\n            )\n\n    if file_path:\n        if file_path.suffix != \".py\":\n            exit_with_error(\n                f\"{file_path} is not a .py file. Please specify a \"\n                \".py that contains blocks to be registered.\"\n            )\n        try:\n            imported_module = await run_sync_in_worker_thread(\n                load_script_as_module, str(file_path)\n            )\n        except ScriptError as exc:\n            app.console.print(exc)\n            app.console.print(exception_traceback(exc.user_exc))\n            exit_with_error(\n                f\"Unable to load file at {file_path}. Please make sure the file path \"\n                \"is correct and the file contains valid Python.\"\n            )\n\n    registered_blocks = await _register_blocks_in_module(imported_module)\n    number_of_registered_blocks = len(registered_blocks)\n    block_text = \"block\" if 0 &lt; number_of_registered_blocks &lt; 2 else \"blocks\"\n    app.console.print(\n        f\"[green]Successfully registered {number_of_registered_blocks} {block_text}\\n\"\n    )\n    app.console.print(_build_registered_blocks_table(registered_blocks))\n    msg = (\n        \"\\n To configure the newly registered blocks, \"\n        \"go to the Blocks page in the Prefect UI.\\n\"\n    )\n\n    ui_url = PREFECT_UI_URL.value()\n    if ui_url is not None:\n        block_catalog_url = f\"{ui_url}/blocks/catalog\"\n        msg = f\"{msg.rstrip().rstrip('.')}: {block_catalog_url}\\n\"\n\n    app.console.print(msg)\n</code></pre>","tags":["Python API","blocks","CLI"]},{"location":"api-ref/prefect/cli/cloud-webhook/","title":"Cloud webhook","text":"","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook","title":"<code>prefect.cli.cloud.webhook</code>","text":"<p>Command line interface for working with webhooks</p>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def create(\n    webhook_name: str,\n    description: str = typer.Option(\n        \"\", \"--description\", \"-d\", help=\"Description of the webhook\"\n    ),\n    template: str = typer.Option(\n        None, \"--template\", \"-t\", help=\"Jinja2 template expression\"\n    ),\n):\n    \"\"\"\n    Create a new Cloud webhook\n    \"\"\"\n    if not template:\n        exit_with_error(\n            \"Please provide a Jinja2 template expression in the --template flag \\nwhich\"\n            ' should define (at minimum) the following attributes: \\n{ \"event\":'\n            ' \"your.event.name\", \"resource\": { \"prefect.resource.id\":'\n            ' \"your.resource.id\" } }'\n            \" \\nhttps://docs.prefect.io/latest/cloud/webhooks/#webhook-templates\"\n        )\n\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\n            \"POST\",\n            \"/webhooks/\",\n            json={\n                \"name\": webhook_name,\n                \"description\": description,\n                \"template\": template,\n            },\n        )\n        app.console.print(f'Successfully created webhook {response[\"name\"]}')\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def delete(webhook_id: UUID):\n    \"\"\"\n    Delete an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    confirm_delete = typer.confirm(\n        \"Are you sure you want to delete it? This cannot be undone.\"\n    )\n\n    if not confirm_delete:\n        return\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        await client.request(\"DELETE\", f\"/webhooks/{webhook_id}\")\n        app.console.print(f\"Successfully deleted webhook {webhook_id}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.get","title":"<code>get</code>  <code>async</code>","text":"<p>Retrieve a webhook by ID.</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def get(webhook_id: UUID):\n    \"\"\"\n    Retrieve a webhook by ID.\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        webhook = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        display_table = _render_webhooks_into_table([webhook])\n        app.console.print(display_table)\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>Fetch and list all webhooks in your workspace</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def ls():\n    \"\"\"\n    Fetch and list all webhooks in your workspace\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        retrieved_webhooks = await client.request(\"POST\", \"/webhooks/filter\")\n        display_table = _render_webhooks_into_table(retrieved_webhooks)\n        app.console.print(display_table)\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.rotate","title":"<code>rotate</code>  <code>async</code>","text":"<p>Rotate url for an existing Cloud webhook, in case it has been compromised</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def rotate(webhook_id: UUID):\n    \"\"\"\n    Rotate url for an existing Cloud webhook, in case it has been compromised\n    \"\"\"\n    confirm_logged_in()\n\n    confirm_rotate = typer.confirm(\n        \"Are you sure you want to rotate? This will invalidate the old URL.\"\n    )\n\n    if not confirm_rotate:\n        return\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"POST\", f\"/webhooks/{webhook_id}/rotate\")\n        app.console.print(f'Successfully rotated webhook URL to {response[\"slug\"]}')\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.toggle","title":"<code>toggle</code>  <code>async</code>","text":"<p>Toggle the enabled status of an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def toggle(\n    webhook_id: UUID,\n):\n    \"\"\"\n    Toggle the enabled status of an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    status_lookup = {True: \"enabled\", False: \"disabled\"}\n\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        current_status = response[\"enabled\"]\n        new_status = not current_status\n\n        await client.request(\n            \"PATCH\", f\"/webhooks/{webhook_id}\", json={\"enabled\": new_status}\n        )\n        app.console.print(f\"Webhook is now {status_lookup[new_status]}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud-webhook/#prefect.cli.cloud.webhook.update","title":"<code>update</code>  <code>async</code>","text":"<p>Partially update an existing Cloud webhook</p> Source code in <code>prefect/cli/cloud/webhook.py</code> <pre><code>@webhook_app.command()\nasync def update(\n    webhook_id: UUID,\n    webhook_name: str = typer.Option(None, \"--name\", \"-n\", help=\"Webhook name\"),\n    description: str = typer.Option(\n        None, \"--description\", \"-d\", help=\"Description of the webhook\"\n    ),\n    template: str = typer.Option(\n        None, \"--template\", \"-t\", help=\"Jinja2 template expression\"\n    ),\n):\n    \"\"\"\n    Partially update an existing Cloud webhook\n    \"\"\"\n    confirm_logged_in()\n\n    # The /webhooks API lives inside the /accounts/{id}/workspaces/{id} routing tree\n    async with get_cloud_client(host=PREFECT_API_URL.value()) as client:\n        response = await client.request(\"GET\", f\"/webhooks/{webhook_id}\")\n        update_payload = {\n            \"name\": webhook_name or response[\"name\"],\n            \"description\": description or response[\"description\"],\n            \"template\": template or response[\"template\"],\n        }\n\n        await client.request(\"PUT\", f\"/webhooks/{webhook_id}\", json=update_payload)\n        app.console.print(f\"Successfully updated webhook {webhook_id}\")\n</code></pre>","tags":["Python API","CLI","events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"api-ref/prefect/cli/cloud/","title":"cloud","text":"","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud","title":"<code>prefect.cli.cloud</code>","text":"<p>Command line interface for interacting with Prefect Cloud</p>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login_api","title":"<code>login_api = FastAPI(lifespan=lifespan)</code>  <code>module-attribute</code>","text":"<p>This small API server is used for data transmission for browser-based log in.</p>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.check_key_is_valid_for_login","title":"<code>check_key_is_valid_for_login</code>  <code>async</code>","text":"<p>Attempt to use a key to see if it is valid</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>async def check_key_is_valid_for_login(key: str):\n    \"\"\"\n    Attempt to use a key to see if it is valid\n    \"\"\"\n    async with get_cloud_client(api_key=key) as client:\n        try:\n            await client.read_workspaces()\n            return True\n        except CloudUnauthorizedError:\n            return False\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login","title":"<code>login</code>  <code>async</code>","text":"<p>Log in to Prefect Cloud. Creates a new profile configured to use the specified PREFECT_API_KEY. Uses a previously configured profile if it exists.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def login(\n    key: Optional[str] = typer.Option(\n        None, \"--key\", \"-k\", help=\"API Key to authenticate with Prefect\"\n    ),\n    workspace_handle: Optional[str] = typer.Option(\n        None,\n        \"--workspace\",\n        \"-w\",\n        help=(\n            \"Full handle of workspace, in format '&lt;account_handle&gt;/&lt;workspace_handle&gt;'\"\n        ),\n    ),\n):\n    \"\"\"\n    Log in to Prefect Cloud.\n    Creates a new profile configured to use the specified PREFECT_API_KEY.\n    Uses a previously configured profile if it exists.\n    \"\"\"\n    if not is_interactive() and (not key or not workspace_handle):\n        exit_with_error(\n            \"When not using an interactive terminal, you must supply a `--key` and\"\n            \" `--workspace`.\"\n        )\n\n    profiles = load_profiles()\n    current_profile = get_settings_context().profile\n    env_var_api_key = PREFECT_API_KEY.value()\n    selected_workspace = None\n\n    if env_var_api_key and key and env_var_api_key != key:\n        exit_with_error(\n            \"Cannot log in with a key when a different PREFECT_API_KEY is present as an\"\n            \" environment variable that will override it.\"\n        )\n\n    if env_var_api_key and env_var_api_key == key:\n        is_valid_key = await check_key_is_valid_for_login(key)\n        is_correct_key_format = key.startswith(\"pnu_\") or key.startswith(\"pnb_\")\n        if not is_valid_key:\n            help_message = \"Please ensure your credentials are correct and unexpired.\"\n            if not is_correct_key_format:\n                help_message = \"Your key is not in our expected format.\"\n            exit_with_error(\n                f\"Unable to authenticate with Prefect Cloud. {help_message}\"\n            )\n\n    already_logged_in_profiles = []\n    for name, profile in profiles.items():\n        profile_key = profile.settings.get(PREFECT_API_KEY)\n        if (\n            # If a key is provided, only show profiles with the same key\n            (key and profile_key == key)\n            # Otherwise, show all profiles with a key set\n            or (not key and profile_key is not None)\n            # Check that the key is usable to avoid suggesting unauthenticated profiles\n            and await check_key_is_valid_for_login(profile_key)\n        ):\n            already_logged_in_profiles.append(name)\n\n    current_profile_is_logged_in = current_profile.name in already_logged_in_profiles\n\n    if current_profile_is_logged_in:\n        app.console.print(\"It looks like you're already authenticated on this profile.\")\n        if is_interactive():\n            should_reauth = typer.confirm(\n                \"? Would you like to reauthenticate?\", default=False\n            )\n        else:\n            should_reauth = True\n\n        if not should_reauth:\n            app.console.print(\"Using the existing authentication on this profile.\")\n            key = PREFECT_API_KEY.value()\n\n    elif already_logged_in_profiles:\n        app.console.print(\n            \"It looks like you're already authenticated with another profile.\"\n        )\n        if typer.confirm(\n            \"? Would you like to switch profiles?\",\n            default=True,\n        ):\n            profile_name = prompt_select_from_list(\n                app.console,\n                \"Which authenticated profile would you like to switch to?\",\n                already_logged_in_profiles,\n            )\n\n            profiles.set_active(profile_name)\n            save_profiles(profiles)\n            exit_with_success(f\"Switched to authenticated profile {profile_name!r}.\")\n\n    if not key:\n        choice = prompt_select_from_list(\n            app.console,\n            \"How would you like to authenticate?\",\n            [\n                (\"browser\", \"Log in with a web browser\"),\n                (\"key\", \"Paste an API key\"),\n            ],\n        )\n\n        if choice == \"key\":\n            key = typer.prompt(\"Paste your API key\", hide_input=True)\n        elif choice == \"browser\":\n            key = await login_with_browser()\n\n    async with get_cloud_client(api_key=key) as client:\n        try:\n            workspaces = await client.read_workspaces()\n            current_workspace = get_current_workspace(workspaces)\n            prompt_switch_workspace = False\n        except CloudUnauthorizedError:\n            if key.startswith(\"pcu\"):\n                help_message = (\n                    \"It looks like you're using API key from Cloud 1\"\n                    \" (https://cloud.prefect.io). Make sure that you generate API key\"\n                    \" using Cloud 2 (https://app.prefect.cloud)\"\n                )\n            elif not key.startswith(\"pnu_\") and not key.startswith(\"pnb_\"):\n                help_message = (\n                    \"Your key is not in our expected format: 'pnu_' or 'pnb_'.\"\n                )\n            else:\n                help_message = (\n                    \"Please ensure your credentials are correct and unexpired.\"\n                )\n            exit_with_error(\n                f\"Unable to authenticate with Prefect Cloud. {help_message}\"\n            )\n        except httpx.HTTPStatusError as exc:\n            exit_with_error(f\"Error connecting to Prefect Cloud: {exc!r}\")\n\n    if workspace_handle:\n        # Search for the given workspace\n        for workspace in workspaces:\n            if workspace.handle == workspace_handle:\n                selected_workspace = workspace\n                break\n        else:\n            if workspaces:\n                hint = (\n                    \" Available workspaces:\"\n                    f\" {listrepr((w.handle for w in workspaces), ', ')}\"\n                )\n            else:\n                hint = \"\"\n\n            exit_with_error(f\"Workspace {workspace_handle!r} not found.\" + hint)\n    else:\n        # Prompt a switch if the number of workspaces is greater than one\n        prompt_switch_workspace = len(workspaces) &gt; 1\n\n        # Confirm that we want to switch if the current profile is already logged in\n        if (\n            current_profile_is_logged_in and current_workspace is not None\n        ) and prompt_switch_workspace:\n            app.console.print(\n                f\"You are currently using workspace {current_workspace.handle!r}.\"\n            )\n            prompt_switch_workspace = typer.confirm(\n                \"? Would you like to switch workspaces?\", default=False\n            )\n    if prompt_switch_workspace:\n        go_back = True\n        while go_back:\n            selected_workspace, go_back = await _prompt_for_account_and_workspace(\n                workspaces\n            )\n        if selected_workspace is None:\n            exit_with_error(\"No workspace selected.\")\n\n    elif not selected_workspace and not workspace_handle:\n        if current_workspace:\n            selected_workspace = current_workspace\n        elif len(workspaces) &gt; 0:\n            selected_workspace = workspaces[0]\n        else:\n            exit_with_error(\n                \"No workspaces found! Create a workspace at\"\n                f\" {PREFECT_CLOUD_UI_URL.value()} and try again.\"\n            )\n\n    update_current_profile(\n        {\n            PREFECT_API_KEY: key,\n            PREFECT_API_URL: selected_workspace.api_url(),\n        }\n    )\n\n    exit_with_success(\n        f\"Authenticated with Prefect Cloud! Using workspace {selected_workspace.handle!r}.\"\n    )\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.login_with_browser","title":"<code>login_with_browser</code>  <code>async</code>","text":"<p>Perform login using the browser.</p> <p>On failure, this function will exit the process. On success, it will return an API key.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>async def login_with_browser() -&gt; str:\n    \"\"\"\n    Perform login using the browser.\n\n    On failure, this function will exit the process.\n    On success, it will return an API key.\n    \"\"\"\n\n    # Set up an event that the login API will toggle on startup\n    ready_event = login_api.extra[\"ready-event\"] = anyio.Event()\n\n    # Set up an event that the login API will set when a response comes from the UI\n    result_event = login_api.extra[\"result-event\"] = anyio.Event()\n\n    timeout_scope = None\n    async with anyio.create_task_group() as tg:\n        # Run a server in the background to get payload from the browser\n        server = await tg.start(serve_login_api, tg.cancel_scope)\n\n        # Wait for the login server to be ready\n        with anyio.fail_after(10):\n            await ready_event.wait()\n\n            # The server may not actually be serving as the lifespan is started first\n            while not server.started:\n                await anyio.sleep(0)\n\n        # Get the port the server is using\n        server_port = server.servers[0].sockets[0].getsockname()[1]\n        callback = urllib.parse.quote(f\"http://localhost:{server_port}\")\n        ui_login_url = (\n            PREFECT_CLOUD_UI_URL.value() + f\"/auth/client?callback={callback}\"\n        )\n\n        # Then open the authorization page in a new browser tab\n        app.console.print(\"Opening browser...\")\n        await run_sync_in_worker_thread(webbrowser.open_new_tab, ui_login_url)\n\n        # Wait for the response from the browser,\n        with anyio.move_on_after(120) as timeout_scope:\n            app.console.print(\"Waiting for response...\")\n            await result_event.wait()\n\n        # Shut down the background uvicorn server\n        tg.cancel_scope.cancel()\n\n    result = login_api.extra.get(\"result\")\n    if not result:\n        if timeout_scope and timeout_scope.cancel_called:\n            exit_with_error(\"Timed out while waiting for authorization.\")\n        else:\n            exit_with_error(\"Aborted.\")\n\n    if result.type == \"success\":\n        return result.content.api_key\n    elif result.type == \"failure\":\n        exit_with_error(f\"Failed to log in. {result.content.reason}\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.logout","title":"<code>logout</code>  <code>async</code>","text":"<p>Logout the current workspace. Reset PREFECT_API_KEY and PREFECT_API_URL to default.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def logout():\n    \"\"\"\n    Logout the current workspace.\n    Reset PREFECT_API_KEY and PREFECT_API_URL to default.\n    \"\"\"\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile is None:\n        exit_with_error(\"There is no current profile set.\")\n\n    if current_profile.settings.get(PREFECT_API_KEY) is None:\n        exit_with_error(\"Current profile is not logged into Prefect Cloud.\")\n\n    update_current_profile(\n        {\n            PREFECT_API_URL: None,\n            PREFECT_API_KEY: None,\n        },\n    )\n\n    exit_with_success(\"Logged out from Prefect Cloud.\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>List available workspaces.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@workspace_app.command()\nasync def ls():\n    \"\"\"List available workspaces.\"\"\"\n\n    confirm_logged_in()\n\n    async with get_cloud_client() as client:\n        try:\n            workspaces = await client.read_workspaces()\n        except CloudUnauthorizedError:\n            exit_with_error(\n                \"Unable to authenticate. Please ensure your credentials are correct.\"\n            )\n\n    current_workspace = get_current_workspace(workspaces)\n\n    table = Table(caption=\"* active workspace\")\n    table.add_column(\n        \"[#024dfd]Workspaces:\", justify=\"left\", style=\"#8ea0ae\", no_wrap=True\n    )\n\n    for workspace_handle in sorted(workspace.handle for workspace in workspaces):\n        if workspace_handle == current_workspace.handle:\n            table.add_row(f\"[green]* {workspace_handle}[/green]\")\n        else:\n            table.add_row(f\"  {workspace_handle}\")\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.open","title":"<code>open</code>  <code>async</code>","text":"<p>Open the Prefect Cloud UI in the browser.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@cloud_app.command()\nasync def open():\n    \"\"\"\n    Open the Prefect Cloud UI in the browser.\n    \"\"\"\n    confirm_logged_in()\n\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile is None:\n        exit_with_error(\n            \"There is no current profile set - set one with `prefect profile create\"\n            \" &lt;name&gt;` and `prefect profile use &lt;name&gt;`.\"\n        )\n\n    current_workspace = get_current_workspace(\n        await prefect.get_cloud_client().read_workspaces()\n    )\n    if current_workspace is None:\n        exit_with_error(\n            \"There is no current workspace set - set one with `prefect cloud workspace\"\n            \" set --workspace &lt;workspace&gt;`.\"\n        )\n\n    ui_url = current_workspace.ui_url()\n\n    await run_sync_in_worker_thread(webbrowser.open_new_tab, ui_url)\n\n    exit_with_success(f\"Opened {current_workspace.handle!r} in browser.\")\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.prompt_select_from_list","title":"<code>prompt_select_from_list</code>","text":"<p>Given a list of options, display the values to user in a table and prompt them to select one.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>Union[List[str], List[Tuple[Hashable, str]]]</code> <p>A list of options to present to the user. A list of tuples can be passed as key value pairs. If a value is chosen, the key will be returned.</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>the selected option</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>def prompt_select_from_list(\n    console, prompt: str, options: Union[List[str], List[Tuple[Hashable, str]]]\n) -&gt; str:\n    \"\"\"\n    Given a list of options, display the values to user in a table and prompt them\n    to select one.\n\n    Args:\n        options: A list of options to present to the user.\n            A list of tuples can be passed as key value pairs. If a value is chosen, the\n            key will be returned.\n\n    Returns:\n        str: the selected option\n    \"\"\"\n\n    current_idx = 0\n    selected_option = None\n\n    def build_table() -&gt; Table:\n        \"\"\"\n        Generate a table of options. The `current_idx` will be highlighted.\n        \"\"\"\n\n        table = Table(box=False, header_style=None, padding=(0, 0))\n        table.add_column(\n            f\"? [bold]{prompt}[/] [bright_blue][Use arrows to move; enter to select]\",\n            justify=\"left\",\n            no_wrap=True,\n        )\n\n        for i, option in enumerate(options):\n            if isinstance(option, tuple):\n                option = option[1]\n\n            if i == current_idx:\n                # Use blue for selected options\n                table.add_row(\"[bold][blue]&gt; \" + option)\n            else:\n                table.add_row(\"  \" + option)\n        return table\n\n    with Live(build_table(), auto_refresh=False, console=console) as live:\n        while selected_option is None:\n            key = readchar.readkey()\n\n            if key == readchar.key.UP:\n                current_idx = current_idx - 1\n                # wrap to bottom if at the top\n                if current_idx &lt; 0:\n                    current_idx = len(options) - 1\n            elif key == readchar.key.DOWN:\n                current_idx = current_idx + 1\n                # wrap to top if at the bottom\n                if current_idx &gt;= len(options):\n                    current_idx = 0\n            elif key == readchar.key.CTRL_C:\n                # gracefully exit with no message\n                exit_with_error(\"\")\n            elif key == readchar.key.ENTER or key == readchar.key.CR:\n                selected_option = options[current_idx]\n                if isinstance(selected_option, tuple):\n                    selected_option = selected_option[0]\n\n            live.update(build_table(), refresh=True)\n\n        return selected_option\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/cloud/#prefect.cli.cloud.set","title":"<code>set</code>  <code>async</code>","text":"<p>Set current workspace. Shows a workspace picker if no workspace is specified.</p> Source code in <code>prefect/cli/cloud/__init__.py</code> <pre><code>@workspace_app.command()\nasync def set(\n    workspace_handle: str = typer.Option(\n        None,\n        \"--workspace\",\n        \"-w\",\n        help=(\n            \"Full handle of workspace, in format '&lt;account_handle&gt;/&lt;workspace_handle&gt;'\"\n        ),\n    ),\n):\n    \"\"\"Set current workspace. Shows a workspace picker if no workspace is specified.\"\"\"\n    confirm_logged_in()\n    async with get_cloud_client() as client:\n        try:\n            workspaces = await client.read_workspaces()\n        except CloudUnauthorizedError:\n            exit_with_error(\n                \"Unable to authenticate. Please ensure your credentials are correct.\"\n            )\n\n        if workspace_handle:\n            # Search for the given workspace\n            for workspace in workspaces:\n                if workspace.handle == workspace_handle:\n                    break\n            else:\n                exit_with_error(f\"Workspace {workspace_handle!r} not found.\")\n        else:\n            if not workspaces:\n                exit_with_error(\"No workspaces found in the selected account.\")\n\n            go_back = True\n            while go_back:\n                workspace, go_back = await _prompt_for_account_and_workspace(workspaces)\n            if workspace is None:\n                exit_with_error(\"No workspace selected.\")\n\n        profile = update_current_profile({PREFECT_API_URL: workspace.api_url()})\n        exit_with_success(\n            f\"Successfully set workspace to {workspace.handle!r} in profile\"\n            f\" {profile.name!r}.\"\n        )\n</code></pre>","tags":["Python API","CLI","authentication","Cloud"]},{"location":"api-ref/prefect/cli/concurrency_limit/","title":"concurrency_limit","text":"","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit","title":"<code>prefect.cli.concurrency_limit</code>","text":"<p>Command line interface for working with concurrency limits.</p>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a concurrency limit against a tag.</p> <p>This limit controls how many task runs with that tag may simultaneously be in a Running state.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def create(tag: str, concurrency_limit: int):\n    \"\"\"\n    Create a concurrency limit against a tag.\n\n    This limit controls how many task runs with that tag may simultaneously be in a\n    Running state.\n    \"\"\"\n\n    async with get_client() as client:\n        await client.create_concurrency_limit(\n            tag=tag, concurrency_limit=concurrency_limit\n        )\n        await client.read_concurrency_limit_by_tag(tag)\n\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n            Created concurrency limit with properties:\n                tag - {tag!r}\n                concurrency_limit - {concurrency_limit}\n\n            Delete the concurrency limit:\n                prefect concurrency-limit delete {tag!r}\n\n            Inspect the concurrency limit:\n                prefect concurrency-limit inspect {tag!r}\n        \"\"\"\n        )\n    )\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete the concurrency limit set on the specified tag.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def delete(tag: str):\n    \"\"\"\n    Delete the concurrency limit set on the specified tag.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.delete_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    exit_with_success(f\"Deleted concurrency limit set on the tag: {tag}\")\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a concurrency limit. <code>active_slots</code> shows a list of TaskRun IDs which are currently using a concurrency slot.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def inspect(tag: str):\n    \"\"\"\n    View details about a concurrency limit. `active_slots` shows a list of TaskRun IDs\n    which are currently using a concurrency slot.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            result = await client.read_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    trid_table = Table()\n    trid_table.add_column(\"Active Task Run IDs\", style=\"cyan\", no_wrap=True)\n\n    cl_table = Table(title=f\"Concurrency Limit ID: [red]{str(result.id)}\")\n    cl_table.add_column(\"Tag\", style=\"green\", no_wrap=True)\n    cl_table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    cl_table.add_column(\"Created\", style=\"magenta\", no_wrap=True)\n    cl_table.add_column(\"Updated\", style=\"magenta\", no_wrap=True)\n\n    for trid in sorted(result.active_slots):\n        trid_table.add_row(str(trid))\n\n    cl_table.add_row(\n        str(result.tag),\n        str(result.concurrency_limit),\n        Pretty(pendulum.instance(result.created).diff_for_humans()),\n        Pretty(pendulum.instance(result.updated).diff_for_humans()),\n    )\n\n    group = Group(\n        cl_table,\n        trid_table,\n    )\n    app.console.print(Panel(group, expand=False))\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all concurrency limits.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def ls(limit: int = 15, offset: int = 0):\n    \"\"\"\n    View all concurrency limits.\n    \"\"\"\n    table = Table(\n        title=\"Concurrency Limits\",\n        caption=\"inspect a concurrency limit to show active task run IDs\",\n    )\n    table.add_column(\"Tag\", style=\"green\", no_wrap=True)\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Active Task Runs\", style=\"magenta\", no_wrap=True)\n\n    async with get_client() as client:\n        concurrency_limits = await client.read_concurrency_limits(\n            limit=limit, offset=offset\n        )\n\n    for cl in sorted(concurrency_limits, key=lambda c: c.updated, reverse=True):\n        table.add_row(\n            str(cl.tag),\n            str(cl.id),\n            str(cl.concurrency_limit),\n            str(len(cl.active_slots)),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/concurrency_limit/#prefect.cli.concurrency_limit.reset","title":"<code>reset</code>  <code>async</code>","text":"<p>Resets the concurrency limit slots set on the specified tag.</p> Source code in <code>prefect/cli/concurrency_limit.py</code> <pre><code>@concurrency_limit_app.command()\nasync def reset(tag: str):\n    \"\"\"\n    Resets the concurrency limit slots set on the specified tag.\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.reset_concurrency_limit_by_tag(tag=tag)\n        except ObjectNotFound:\n            exit_with_error(f\"No concurrency limit found for the tag: {tag}\")\n\n    exit_with_success(f\"Reset concurrency limit set on the tag: {tag}\")\n</code></pre>","tags":["Python API","CLI","concurrency"]},{"location":"api-ref/prefect/cli/config/","title":"config","text":"","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config","title":"<code>prefect.cli.config</code>","text":"<p>Command line interface for working with profiles</p>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.set_","title":"<code>set_</code>","text":"<p>Change the value for a setting by setting the value in the current profile.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command(\"set\")\ndef set_(settings: List[str]):\n    \"\"\"\n    Change the value for a setting by setting the value in the current profile.\n    \"\"\"\n    parsed_settings = {}\n    for item in settings:\n        try:\n            setting, value = item.split(\"=\", maxsplit=1)\n        except ValueError:\n            exit_with_error(\n                f\"Failed to parse argument {item!r}. Use the format 'VAR=VAL'.\"\n            )\n\n        if setting not in prefect.settings.SETTING_VARIABLES:\n            exit_with_error(f\"Unknown setting name {setting!r}.\")\n\n        # Guard against changing settings that tweak config locations\n        if setting in {\"PREFECT_HOME\", \"PREFECT_PROFILES_PATH\"}:\n            exit_with_error(\n                f\"Setting {setting!r} cannot be changed with this command. \"\n                \"Use an environment variable instead.\"\n            )\n\n        parsed_settings[setting] = value\n\n    try:\n        new_profile = prefect.settings.update_current_profile(parsed_settings)\n    except pydantic.ValidationError as exc:\n        for error in exc.errors():\n            setting = error[\"loc\"][0]\n            message = error[\"msg\"]\n            app.console.print(f\"Validation error for setting {setting!r}: {message}\")\n        exit_with_error(\"Invalid setting value.\")\n\n    for setting, value in parsed_settings.items():\n        app.console.print(f\"Set {setting!r} to {value!r}.\")\n        if setting in os.environ:\n            app.console.print(\n                f\"[yellow]{setting} is also set by an environment variable which will \"\n                f\"override your config value. Run `unset {setting}` to clear it.\"\n            )\n\n        if prefect.settings.SETTING_VARIABLES[setting].deprecated:\n            app.console.print(\n                f\"[yellow]{prefect.settings.SETTING_VARIABLES[setting].deprecated_message}.\"\n            )\n\n    exit_with_success(f\"Updated profile {new_profile.name!r}.\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.unset","title":"<code>unset</code>","text":"<p>Restore the default value for a setting.</p> <p>Removes the setting from the current profile.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef unset(settings: List[str]):\n    \"\"\"\n    Restore the default value for a setting.\n\n    Removes the setting from the current profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    profile = profiles[prefect.context.get_settings_context().profile.name]\n    parsed = set()\n\n    for setting in settings:\n        if setting not in prefect.settings.SETTING_VARIABLES:\n            exit_with_error(f\"Unknown setting name {setting!r}.\")\n        # Cast to settings objects\n        parsed.add(prefect.settings.SETTING_VARIABLES[setting])\n\n    for setting in parsed:\n        if setting not in profile.settings:\n            exit_with_error(f\"{setting.name!r} is not set in profile {profile.name!r}.\")\n\n    profiles.update_profile(\n        name=profile.name, settings={setting: None for setting in parsed}\n    )\n\n    for setting in settings:\n        app.console.print(f\"Unset {setting!r}.\")\n\n        if setting in os.environ:\n            app.console.print(\n                f\"[yellow]{setting!r} is also set by an environment variable. \"\n                f\"Use `unset {setting}` to clear it.\"\n            )\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"Updated profile {profile.name!r}.\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.validate","title":"<code>validate</code>","text":"<p>Read and validate the current profile.</p> <p>Deprecated settings will be automatically converted to new names unless both are set.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef validate():\n    \"\"\"\n    Read and validate the current profile.\n\n    Deprecated settings will be automatically converted to new names unless both are\n    set.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    profile = profiles[prefect.context.get_settings_context().profile.name]\n    changed = profile.convert_deprecated_renamed_settings()\n    for old, new in changed:\n        app.console.print(f\"Updated {old.name!r} to {new.name!r}.\")\n\n    for setting in profile.settings.keys():\n        if setting.deprecated:\n            app.console.print(f\"Found deprecated setting {setting.name!r}.\")\n\n    profile.validate_settings()\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(\"Configuration valid!\")\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/config/#prefect.cli.config.view","title":"<code>view</code>","text":"<p>Display the current settings.</p> Source code in <code>prefect/cli/config.py</code> <pre><code>@config_app.command()\ndef view(\n    show_defaults: Optional[bool] = typer.Option(\n        False, \"--show-defaults/--hide-defaults\", help=(show_defaults_help)\n    ),\n    show_sources: Optional[bool] = typer.Option(\n        True,\n        \"--show-sources/--hide-sources\",\n        help=(show_sources_help),\n    ),\n    show_secrets: Optional[bool] = typer.Option(\n        False,\n        \"--show-secrets/--hide-secrets\",\n        help=\"Toggle display of secrets setting values.\",\n    ),\n):\n    \"\"\"\n    Display the current settings.\n    \"\"\"\n    context = prefect.context.get_settings_context()\n\n    # Get settings at each level, converted to a flat dictionary for easy comparison\n    default_settings = prefect.settings.get_default_settings()\n    env_settings = prefect.settings.get_settings_from_env()\n    current_profile_settings = context.settings\n\n    # Obfuscate secrets\n    if not show_secrets:\n        default_settings = default_settings.with_obfuscated_secrets()\n        env_settings = env_settings.with_obfuscated_secrets()\n        current_profile_settings = current_profile_settings.with_obfuscated_secrets()\n\n    # Display the profile first\n    app.console.print(f\"PREFECT_PROFILE={context.profile.name!r}\")\n\n    settings_output = []\n\n    # The combination of environment variables and profile settings that are in use\n    profile_overrides = current_profile_settings.dict(exclude_unset=True)\n\n    # Used to see which settings in current_profile_settings came from env vars\n    env_overrides = env_settings.dict(exclude_unset=True)\n\n    for key, value in profile_overrides.items():\n        source = \"env\" if env_overrides.get(key) is not None else \"profile\"\n        source_blurb = f\" (from {source})\" if show_sources else \"\"\n        settings_output.append(f\"{key}='{value}'{source_blurb}\")\n\n    if show_defaults:\n        for key, value in default_settings.dict().items():\n            if key not in profile_overrides:\n                source_blurb = \" (from defaults)\" if show_sources else \"\"\n                settings_output.append(f\"{key}='{value}'{source_blurb}\")\n\n    app.console.print(\"\\n\".join(sorted(settings_output)))\n</code></pre>","tags":["Python API","CLI","config","settings"]},{"location":"api-ref/prefect/cli/deploy/","title":"deploy","text":"","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy","title":"<code>prefect.cli.deploy</code>","text":"<p>Module containing implementation for deploying flows.</p>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploy a flow from this project by creating a deployment.</p> <p>Should be run from a project root directory.</p> Source code in <code>prefect/cli/deploy.py</code> <pre><code>@app.command()\nasync def deploy(\n    entrypoint: str = typer.Argument(\n        None,\n        help=(\n            \"The path to a flow entrypoint within a project, in the form of\"\n            \" `./path/to/file.py:flow_func_name`\"\n        ),\n    ),\n    names: List[str] = typer.Option(\n        None,\n        \"--name\",\n        \"-n\",\n        help=(\n            \"The name to give the deployment. Can be a pattern. Examples:\"\n            \" 'my-deployment', 'my-flow/my-deployment', 'my-deployment-*',\"\n            \" '*-flow-name/deployment*'\"\n        ),\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the deployment. If not provided, the description\"\n            \" will be populated from the flow's description.\"\n        ),\n    ),\n    version: str = typer.Option(\n        None, \"--version\", help=\"A version to give the deployment.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"One or more optional tags to apply to the deployment. Note: tags are used\"\n            \" only for organizational purposes. For delegating work to agents, use the\"\n            \" --work-queue flag.\"\n        ),\n    ),\n    work_pool_name: str = SettingsOption(\n        PREFECT_DEFAULT_WORK_POOL_NAME,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool that will handle this deployment's runs.\",\n    ),\n    work_queue_name: str = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"The work queue that will handle this deployment's runs. \"\n            \"It will be created if it doesn't already exist. Defaults to `None`.\"\n        ),\n    ),\n    variables: List[str] = typer.Option(\n        None,\n        \"-v\",\n        \"--variable\",\n        help=(\"DEPRECATED: Please use --jv/--job-variable for similar functionality \"),\n    ),\n    job_variables: List[str] = typer.Option(\n        None,\n        \"-jv\",\n        \"--job-variable\",\n        help=(\n            \"One or more job variable overrides for the work pool provided in the\"\n            \" format of key=value string or a JSON object\"\n        ),\n    ),\n    cron: List[str] = typer.Option(\n        None,\n        \"--cron\",\n        help=\"A cron string that will be used to set a CronSchedule on the deployment.\",\n    ),\n    interval: List[int] = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) that will be used to set an\"\n            \" IntervalSchedule on the deployment.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The anchor date for all interval schedules\"\n    ),\n    rrule: List[str] = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set an RRuleSchedule on the deployment.\",\n    ),\n    timezone: str = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    trigger: List[str] = typer.Option(\n        None,\n        \"--trigger\",\n        help=(\n            \"Specifies a trigger for the deployment. The value can be a\"\n            \" json string or path to `.yaml`/`.json` file. This flag can be used\"\n            \" multiple times.\"\n        ),\n    ),\n    param: List[str] = typer.Option(\n        None,\n        \"--param\",\n        help=(\n            \"An optional parameter override, values are parsed as JSON strings e.g.\"\n            \" --param question=ultimate --param answer=42\"\n        ),\n    ),\n    params: str = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"An optional parameter override in a JSON string format e.g.\"\n            ' --params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\''\n        ),\n    ),\n    enforce_parameter_schema: bool = typer.Option(\n        False,\n        \"--enforce-parameter-schema\",\n        help=(\n            \"Whether to enforce the parameter schema on this deployment. If set to\"\n            \" True, any parameters passed to this deployment must match the signature\"\n            \" of the flow.\"\n        ),\n    ),\n    deploy_all: bool = typer.Option(\n        False,\n        \"--all\",\n        help=(\n            \"Deploy all flows in the project. If a flow name or entrypoint is also\"\n            \" provided, this flag will be ignored.\"\n        ),\n    ),\n    prefect_file: Path = typer.Option(\n        Path(\"prefect.yaml\"),\n        \"--prefect-file\",\n        help=\"Specify a custom path to a prefect.yaml file\",\n    ),\n):\n    \"\"\"\n    Deploy a flow from this project by creating a deployment.\n\n    Should be run from a project root directory.\n    \"\"\"\n\n    if variables is not None:\n        app.console.print(\n            generate_deprecation_message(\n                name=\"The `--variable` flag\",\n                start_date=\"Mar 2024\",\n                help=(\n                    \"Please use the `--job-variable foo=bar` argument instead: `prefect\"\n                    \" deploy --job-variable`.\"\n                ),\n            ),\n            style=\"yellow\",\n        )\n\n    if variables is None:\n        variables = list()\n    if job_variables is None:\n        job_variables = list()\n    job_variables.extend(variables)\n\n    options = {\n        \"entrypoint\": entrypoint,\n        \"description\": description,\n        \"version\": version,\n        \"tags\": tags,\n        \"work_pool_name\": work_pool_name,\n        \"work_queue_name\": work_queue_name,\n        \"variables\": job_variables,\n        \"cron\": cron,\n        \"interval\": interval,\n        \"anchor_date\": interval_anchor,\n        \"rrule\": rrule,\n        \"timezone\": timezone,\n        \"triggers\": trigger,\n        \"param\": param,\n        \"params\": params,\n        \"enforce_parameter_schema\": enforce_parameter_schema,\n    }\n    try:\n        deploy_configs, actions = _load_deploy_configs_and_actions(\n            prefect_file=prefect_file,\n        )\n        parsed_names = []\n        for name in names or []:\n            if \"*\" in name:\n                parsed_names.extend(_parse_name_from_pattern(deploy_configs, name))\n            else:\n                parsed_names.append(name)\n        deploy_configs = _pick_deploy_configs(\n            deploy_configs,\n            parsed_names,\n            deploy_all,\n        )\n\n        if len(deploy_configs) &gt; 1:\n            if any(options.values()):\n                app.console.print(\n                    (\n                        \"You have passed options to the deploy command, but you are\"\n                        \" creating or updating multiple deployments. These options\"\n                        \" will be ignored.\"\n                    ),\n                    style=\"yellow\",\n                )\n            await _run_multi_deploy(\n                deploy_configs=deploy_configs,\n                actions=actions,\n                deploy_all=deploy_all,\n                prefect_file=prefect_file,\n            )\n        else:\n            # Accommodate passing in -n flow-name/deployment-name as well as -n deployment-name\n            options[\"names\"] = [\n                name.split(\"/\", 1)[-1] if \"/\" in name else name for name in parsed_names\n            ]\n\n            await _run_single_deploy(\n                deploy_config=deploy_configs[0] if deploy_configs else {},\n                actions=actions,\n                options=options,\n                prefect_file=prefect_file,\n            )\n    except ValueError as exc:\n        exit_with_error(str(exc))\n</code></pre>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deploy/#prefect.cli.deploy.init","title":"<code>init</code>  <code>async</code>","text":"<p>Initialize a new deployment configuration recipe.</p> Source code in <code>prefect/cli/deploy.py</code> <pre><code>@app.command()\nasync def init(\n    name: str = None,\n    recipe: str = None,\n    fields: List[str] = typer.Option(\n        None,\n        \"-f\",\n        \"--field\",\n        help=(\n            \"One or more fields to pass to the recipe (e.g., image_name) in the format\"\n            \" of key=value.\"\n        ),\n    ),\n):\n    \"\"\"\n    Initialize a new deployment configuration recipe.\n    \"\"\"\n    inputs = {}\n    fields = fields or []\n    recipe_paths = prefect.__module_path__ / \"deployments\" / \"recipes\"\n\n    for field in fields:\n        key, value = field.split(\"=\")\n        inputs[key] = value\n\n    if not recipe and is_interactive():\n        recipe_paths = prefect.__module_path__ / \"deployments\" / \"recipes\"\n        recipes = []\n\n        for r in recipe_paths.iterdir():\n            if r.is_dir() and (r / \"prefect.yaml\").exists():\n                with open(r / \"prefect.yaml\") as f:\n                    recipe_data = yaml.safe_load(f)\n                    recipe_name = r.name\n                    recipe_description = recipe_data.get(\n                        \"description\", \"(no description available)\"\n                    )\n                    recipe_dict = {\n                        \"name\": recipe_name,\n                        \"description\": recipe_description,\n                    }\n                    recipes.append(recipe_dict)\n\n        selected_recipe = prompt_select_from_table(\n            app.console,\n            \"Would you like to initialize your deployment configuration with a recipe?\",\n            columns=[\n                {\"header\": \"Name\", \"key\": \"name\"},\n                {\"header\": \"Description\", \"key\": \"description\"},\n            ],\n            data=recipes,\n            opt_out_message=\"No, I'll use the default deployment configuration.\",\n            opt_out_response={},\n        )\n        if selected_recipe != {}:\n            recipe = selected_recipe[\"name\"]\n\n    if recipe and (recipe_paths / recipe / \"prefect.yaml\").exists():\n        with open(recipe_paths / recipe / \"prefect.yaml\") as f:\n            recipe_inputs = yaml.safe_load(f).get(\"required_inputs\") or {}\n\n        if recipe_inputs:\n            if set(recipe_inputs.keys()) &lt; set(inputs.keys()):\n                # message to user about extra fields\n                app.console.print(\n                    (\n                        f\"Warning: extra fields provided for {recipe!r} recipe:\"\n                        f\" '{', '.join(set(inputs.keys()) - set(recipe_inputs.keys()))}'\"\n                    ),\n                    style=\"red\",\n                )\n            elif set(recipe_inputs.keys()) &gt; set(inputs.keys()):\n                table = Table(\n                    title=f\"[red]Required inputs for {recipe!r} recipe[/red]\",\n                )\n                table.add_column(\"Field Name\", style=\"green\", no_wrap=True)\n                table.add_column(\n                    \"Description\", justify=\"left\", style=\"white\", no_wrap=False\n                )\n                for field, description in recipe_inputs.items():\n                    if field not in inputs:\n                        table.add_row(field, description)\n\n                app.console.print(table)\n\n                for key, description in recipe_inputs.items():\n                    if key not in inputs:\n                        inputs[key] = typer.prompt(key)\n\n            app.console.print(\"-\" * 15)\n\n    try:\n        files = [\n            f\"[green]{fname}[/green]\"\n            for fname in initialize_project(name=name, recipe=recipe, inputs=inputs)\n        ]\n    except ValueError as exc:\n        if \"Unknown recipe\" in str(exc):\n            exit_with_error(\n                f\"Unknown recipe {recipe!r} provided - run [yellow]`prefect init\"\n                \"`[/yellow] to see all available recipes.\"\n            )\n        else:\n            raise\n\n    files = \"\\n\".join(files)\n    empty_msg = (\n        f\"Created project in [green]{Path('.').resolve()}[/green]; no new files\"\n        \" created.\"\n    )\n    file_msg = (\n        f\"Created project in [green]{Path('.').resolve()}[/green] with the following\"\n        f\" new files:\\n{files}\"\n    )\n    app.console.print(file_msg if files else empty_msg)\n</code></pre>","tags":["Python API","deploy","deployment","CLI"]},{"location":"api-ref/prefect/cli/deployment/","title":"deployment","text":"","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment","title":"<code>prefect.cli.deployment</code>","text":"<p>Command line interface for working with deployments.</p>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Create or update a deployment from a YAML file.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command(\n    deprecated=True,\n    deprecated_start_date=\"Mar 2024\",\n    deprecated_name=\"deployment apply\",\n    deprecated_help=\"Use 'prefect deploy' to deploy flows via YAML instead.\",\n)\nasync def apply(\n    paths: List[str] = typer.Argument(\n        ...,\n        help=\"One or more paths to deployment YAML files.\",\n    ),\n    upload: bool = typer.Option(\n        False,\n        \"--upload\",\n        help=(\n            \"A flag that, when provided, uploads this deployment's files to remote\"\n            \" storage.\"\n        ),\n    ),\n    work_queue_concurrency: int = typer.Option(\n        None,\n        \"--limit\",\n        \"-l\",\n        help=(\n            \"Sets the concurrency limit on the work queue that handles this\"\n            \" deployment's runs\"\n        ),\n    ),\n):\n    \"\"\"\n    Create or update a deployment from a YAML file.\n    \"\"\"\n    deployment = None\n    async with get_client() as client:\n        for path in paths:\n            try:\n                deployment = await Deployment.load_from_yaml(path)\n                app.console.print(\n                    f\"Successfully loaded {deployment.name!r}\", style=\"green\"\n                )\n            except Exception as exc:\n                exit_with_error(\n                    f\"'{path!s}' did not conform to deployment spec: {exc!r}\"\n                )\n\n            assert deployment\n\n            await create_work_queue_and_set_concurrency_limit(\n                deployment.work_queue_name,\n                deployment.work_pool_name,\n                work_queue_concurrency,\n            )\n\n            if upload:\n                if (\n                    deployment.storage\n                    and \"put-directory\" in deployment.storage.get_block_capabilities()\n                ):\n                    file_count = await deployment.upload_to_storage()\n                    if file_count:\n                        app.console.print(\n                            (\n                                f\"Successfully uploaded {file_count} files to\"\n                                f\" {deployment.location}\"\n                            ),\n                            style=\"green\",\n                        )\n                else:\n                    app.console.print(\n                        (\n                            f\"Deployment storage {deployment.storage} does not have\"\n                            \" upload capabilities; no files uploaded.\"\n                        ),\n                        style=\"red\",\n                    )\n            await check_work_pool_exists(\n                work_pool_name=deployment.work_pool_name, client=client\n            )\n\n            if client.server_type != ServerType.CLOUD and deployment.triggers:\n                app.console.print(\n                    (\n                        \"Deployment triggers are only supported on \"\n                        f\"Prefect Cloud. Triggers defined in {path!r} will be \"\n                        \"ignored.\"\n                    ),\n                    style=\"red\",\n                )\n\n            deployment_id = await deployment.apply()\n            app.console.print(\n                (\n                    f\"Deployment '{deployment.flow_name}/{deployment.name}'\"\n                    f\" successfully created with id '{deployment_id}'.\"\n                ),\n                style=\"green\",\n            )\n\n            if PREFECT_UI_URL:\n                app.console.print(\n                    \"View Deployment in UI:\"\n                    f\" {PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}\"\n                )\n\n            if deployment.work_pool_name is not None:\n                await _print_deployment_work_pool_instructions(\n                    work_pool_name=deployment.work_pool_name, client=client\n                )\n            elif deployment.work_queue_name is not None:\n                app.console.print(\n                    \"\\nTo execute flow runs from this deployment, start an agent that\"\n                    f\" pulls work from the {deployment.work_queue_name!r} work queue:\"\n                )\n                app.console.print(\n                    f\"$ prefect agent start -q {deployment.work_queue_name!r}\",\n                    style=\"blue\",\n                )\n            else:\n                app.console.print(\n                    (\n                        \"\\nThis deployment does not specify a work queue name, which\"\n                        \" means agents will not be able to pick up its runs. To add a\"\n                        \" work queue, edit the deployment spec and re-run this command,\"\n                        \" or visit the deployment in the UI.\"\n                    ),\n                    style=\"red\",\n                )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.build","title":"<code>build</code>  <code>async</code>","text":"<p>Generate a deployment YAML from /path/to/file.py:flow_function</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command(\n    deprecated=True,\n    deprecated_start_date=\"Mar 2024\",\n    deprecated_name=\"deployment build\",\n    deprecated_help=\"Use 'prefect deploy' to deploy flows via YAML instead.\",\n)\nasync def build(\n    entrypoint: str = typer.Argument(\n        ...,\n        help=(\n            \"The path to a flow entrypoint, in the form of\"\n            \" `./path/to/file.py:flow_func_name`\"\n        ),\n    ),\n    name: str = typer.Option(\n        None, \"--name\", \"-n\", help=\"The name to give the deployment.\"\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the deployment. If not provided, the description\"\n            \" will be populated from the flow's description.\"\n        ),\n    ),\n    version: str = typer.Option(\n        None, \"--version\", \"-v\", help=\"A version to give the deployment.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"One or more optional tags to apply to the deployment. Note: tags are used\"\n            \" only for organizational purposes. For delegating work to agents, use the\"\n            \" --work-queue flag.\"\n        ),\n    ),\n    work_queue_name: str = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"The work queue that will handle this deployment's runs. \"\n            \"It will be created if it doesn't already exist. Defaults to `None`. \"\n            \"Note that if a work queue is not set, work will not be scheduled.\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool that will handle this deployment's runs.\",\n    ),\n    work_queue_concurrency: int = typer.Option(\n        None,\n        \"--limit\",\n        \"-l\",\n        help=(\n            \"Sets the concurrency limit on the work queue that handles this\"\n            \" deployment's runs\"\n        ),\n    ),\n    infra_type: str = typer.Option(\n        None,\n        \"--infra\",\n        \"-i\",\n        help=\"The infrastructure type to use, prepopulated with defaults. For example: \"\n        + listrepr(builtin_infrastructure_types, sep=\", \"),\n    ),\n    infra_block: str = typer.Option(\n        None,\n        \"--infra-block\",\n        \"-ib\",\n        help=\"The slug of the infrastructure block to use as a template.\",\n    ),\n    overrides: List[str] = typer.Option(\n        None,\n        \"--override\",\n        help=(\n            \"One or more optional infrastructure overrides provided as a dot delimited\"\n            \" path, e.g., `env.env_key=env_value`\"\n        ),\n    ),\n    storage_block: str = typer.Option(\n        None,\n        \"--storage-block\",\n        \"-sb\",\n        help=(\n            \"The slug of a remote storage block. Use the syntax:\"\n            \" 'block_type/block_name', where block_type is one of 'github', 's3',\"\n            \" 'gcs', 'azure', 'smb', or a registered block from a library that\"\n            \" implements the WritableDeploymentStorage interface such as\"\n            \" 'gitlab-repository', 'bitbucket-repository', 's3-bucket',\"\n            \" 'gcs-bucket'\"\n        ),\n    ),\n    skip_upload: bool = typer.Option(\n        False,\n        \"--skip-upload\",\n        help=(\n            \"A flag that, when provided, skips uploading this deployment's files to\"\n            \" remote storage.\"\n        ),\n    ),\n    cron: str = typer.Option(\n        None,\n        \"--cron\",\n        help=\"A cron string that will be used to set a CronSchedule on the deployment.\",\n    ),\n    interval: int = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) that will be used to set an\"\n            \" IntervalSchedule on the deployment.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The anchor date for an interval schedule\"\n    ),\n    rrule: str = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set an RRuleSchedule on the deployment.\",\n    ),\n    timezone: str = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    path: str = typer.Option(\n        None,\n        \"--path\",\n        help=(\n            \"An optional path to specify a subdirectory of remote storage to upload to,\"\n            \" or to point to a subdirectory of a locally stored flow.\"\n        ),\n    ),\n    output: str = typer.Option(\n        None,\n        \"--output\",\n        \"-o\",\n        help=\"An optional filename to write the deployment file to.\",\n    ),\n    _apply: bool = typer.Option(\n        False,\n        \"--apply\",\n        \"-a\",\n        help=(\n            \"An optional flag to automatically register the resulting deployment with\"\n            \" the API.\"\n        ),\n    ),\n    param: List[str] = typer.Option(\n        None,\n        \"--param\",\n        help=(\n            \"An optional parameter override, values are parsed as JSON strings e.g.\"\n            \" --param question=ultimate --param answer=42\"\n        ),\n    ),\n    params: str = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"An optional parameter override in a JSON string format e.g.\"\n            ' --params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\''\n        ),\n    ),\n    no_schedule: bool = typer.Option(\n        False,\n        \"--no-schedule\",\n        help=\"An optional flag to disable scheduling for this deployment.\",\n    ),\n):\n    \"\"\"\n    Generate a deployment YAML from /path/to/file.py:flow_function\n    \"\"\"\n    # validate inputs\n    if not name:\n        exit_with_error(\n            \"A name for this deployment must be provided with the '--name' flag.\"\n        )\n\n    if (\n        len([value for value in (cron, rrule, interval) if value is not None])\n        + (1 if no_schedule else 0)\n        &gt; 1\n    ):\n        exit_with_error(\"Only one schedule type can be provided.\")\n\n    if infra_block and infra_type:\n        exit_with_error(\n            \"Only one of `infra` or `infra_block` can be provided, please choose one.\"\n        )\n\n    output_file = None\n    if output:\n        output_file = Path(output)\n        if output_file.suffix and output_file.suffix != \".yaml\":\n            exit_with_error(\"Output file must be a '.yaml' file.\")\n        else:\n            output_file = output_file.with_suffix(\".yaml\")\n\n    # validate flow\n    try:\n        fpath, obj_name = entrypoint.rsplit(\":\", 1)\n    except ValueError as exc:\n        if str(exc) == \"not enough values to unpack (expected 2, got 1)\":\n            missing_flow_name_msg = (\n                \"Your flow entrypoint must include the name of the function that is\"\n                f\" the entrypoint to your flow.\\nTry {entrypoint}:&lt;flow_name&gt;\"\n            )\n            exit_with_error(missing_flow_name_msg)\n        else:\n            raise exc\n    try:\n        flow = await run_sync_in_worker_thread(load_flow_from_entrypoint, entrypoint)\n    except Exception as exc:\n        exit_with_error(exc)\n    app.console.print(f\"Found flow {flow.name!r}\", style=\"green\")\n    job_variables = {}\n    for override in overrides or []:\n        key, value = override.split(\"=\", 1)\n        job_variables[key] = value\n\n    if infra_block:\n        infrastructure = await Block.load(infra_block)\n    elif infra_type:\n        # Create an instance of the given type\n        infrastructure = Block.get_block_class_from_key(infra_type)()\n    else:\n        # will reset to a default of Process is no infra is present on the\n        # server-side definition of this deployment\n        infrastructure = None\n\n    if interval_anchor and not interval:\n        exit_with_error(\"An anchor date can only be provided with an interval schedule\")\n\n    schedule = None\n    if cron:\n        cron_kwargs = {\"cron\": cron, \"timezone\": timezone}\n        schedule = CronSchedule(\n            **{k: v for k, v in cron_kwargs.items() if v is not None}\n        )\n    elif interval:\n        interval_kwargs = {\n            \"interval\": timedelta(seconds=interval),\n            \"anchor_date\": interval_anchor,\n            \"timezone\": timezone,\n        }\n        schedule = IntervalSchedule(\n            **{k: v for k, v in interval_kwargs.items() if v is not None}\n        )\n    elif rrule:\n        try:\n            schedule = RRuleSchedule(**json.loads(rrule))\n            if timezone:\n                # override timezone if specified via CLI argument\n                schedule.timezone = timezone\n        except json.JSONDecodeError:\n            schedule = RRuleSchedule(rrule=rrule, timezone=timezone)\n\n    # parse storage_block\n    if storage_block:\n        block_type, block_name, *block_path = storage_block.split(\"/\")\n        if block_path and path:\n            exit_with_error(\n                \"Must provide a `path` explicitly or provide one on the storage block\"\n                \" specification, but not both.\"\n            )\n        elif not path:\n            path = \"/\".join(block_path)\n        storage_block = f\"{block_type}/{block_name}\"\n        storage = await Block.load(storage_block)\n    else:\n        storage = None\n\n    if create_default_ignore_file(path=\".\"):\n        app.console.print(\n            (\n                \"Default '.prefectignore' file written to\"\n                f\" {(Path('.') / '.prefectignore').absolute()}\"\n            ),\n            style=\"green\",\n        )\n\n    if param and (params is not None):\n        exit_with_error(\"Can only pass one of `param` or `params` options\")\n\n    parameters = dict()\n\n    if param:\n        for p in param or []:\n            k, unparsed_value = p.split(\"=\", 1)\n            try:\n                v = json.loads(unparsed_value)\n                app.console.print(\n                    f\"The parameter value {unparsed_value} is parsed as a JSON string\"\n                )\n            except json.JSONDecodeError:\n                v = unparsed_value\n            parameters[k] = v\n\n    if params is not None:\n        parameters = json.loads(params)\n\n    # set up deployment object\n    entrypoint = (\n        f\"{Path(fpath).absolute().relative_to(Path('.').absolute())}:{obj_name}\"\n    )\n\n    init_kwargs = dict(\n        path=path,\n        entrypoint=entrypoint,\n        version=version,\n        storage=storage,\n        job_variables=job_variables or {},\n    )\n\n    if parameters:\n        init_kwargs[\"parameters\"] = parameters\n\n    if description:\n        init_kwargs[\"description\"] = description\n\n    # if a schedule, tags, work_queue_name, or infrastructure are not provided via CLI,\n    # we let `build_from_flow` load them from the server\n    if schedule or no_schedule:\n        init_kwargs.update(schedule=schedule)\n    if tags:\n        init_kwargs.update(tags=tags)\n    if infrastructure:\n        init_kwargs.update(infrastructure=infrastructure)\n    if work_queue_name:\n        init_kwargs.update(work_queue_name=work_queue_name)\n    if work_pool_name:\n        init_kwargs.update(work_pool_name=work_pool_name)\n\n    deployment_loc = output_file or f\"{obj_name}-deployment.yaml\"\n    deployment = await Deployment.build_from_flow(\n        flow=flow,\n        name=name,\n        output=deployment_loc,\n        skip_upload=skip_upload,\n        apply=False,\n        **init_kwargs,\n    )\n    app.console.print(\n        f\"Deployment YAML created at '{Path(deployment_loc).absolute()!s}'.\",\n        style=\"green\",\n    )\n\n    await create_work_queue_and_set_concurrency_limit(\n        deployment.work_queue_name, deployment.work_pool_name, work_queue_concurrency\n    )\n\n    # we process these separately for informative output\n    if not skip_upload:\n        if (\n            deployment.storage\n            and \"put-directory\" in deployment.storage.get_block_capabilities()\n        ):\n            file_count = await deployment.upload_to_storage()\n            if file_count:\n                app.console.print(\n                    (\n                        f\"Successfully uploaded {file_count} files to\"\n                        f\" {deployment.location}\"\n                    ),\n                    style=\"green\",\n                )\n        else:\n            app.console.print(\n                (\n                    f\"Deployment storage {deployment.storage} does not have upload\"\n                    \" capabilities; no files uploaded.  Pass --skip-upload to suppress\"\n                    \" this warning.\"\n                ),\n                style=\"green\",\n            )\n\n    if _apply:\n        async with get_client() as client:\n            await check_work_pool_exists(\n                work_pool_name=deployment.work_pool_name, client=client\n            )\n            deployment_id = await deployment.apply()\n            app.console.print(\n                (\n                    f\"Deployment '{deployment.flow_name}/{deployment.name}'\"\n                    f\" successfully created with id '{deployment_id}'.\"\n                ),\n                style=\"green\",\n            )\n            if deployment.work_pool_name is not None:\n                await _print_deployment_work_pool_instructions(\n                    work_pool_name=deployment.work_pool_name, client=client\n                )\n\n            elif deployment.work_queue_name is not None:\n                app.console.print(\n                    \"\\nTo execute flow runs from this deployment, start an agent that\"\n                    f\" pulls work from the {deployment.work_queue_name!r} work queue:\"\n                )\n                app.console.print(\n                    f\"$ prefect agent start -q {deployment.work_queue_name!r}\",\n                    style=\"blue\",\n                )\n            else:\n                app.console.print(\n                    (\n                        \"\\nThis deployment does not specify a work queue name, which\"\n                        \" means agents will not be able to pick up its runs. To add a\"\n                        \" work queue, edit the deployment spec and re-run this command,\"\n                        \" or visit the deployment in the UI.\"\n                    ),\n                    style=\"red\",\n                )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.clear_schedules","title":"<code>clear_schedules</code>  <code>async</code>","text":"<p>Clear all schedules for a deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"clear\")\nasync def clear_schedules(\n    deployment_name: str,\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Clear all schedules for a deployment.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        await client.read_flow(deployment.flow_id)\n\n        # Get input from user: confirm removal of all schedules\n        if not assume_yes and not typer.confirm(\n            \"Are you sure you want to clear all schedules for this deployment?\",\n        ):\n            exit_with_error(\"Clearing schedules cancelled.\")\n\n        for schedule in deployment.schedules:\n            try:\n                await client.delete_deployment_schedule(deployment.id, schedule.id)\n            except ObjectNotFound:\n                pass\n\n        exit_with_success(f\"Cleared all schedules for deployment {deployment_name}\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.create_schedule","title":"<code>create_schedule</code>  <code>async</code>","text":"<p>Create a schedule for a given deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"create\")\nasync def create_schedule(\n    name: str,\n    interval: Optional[float] = typer.Option(\n        None,\n        \"--interval\",\n        help=\"An interval to schedule on, specified in seconds\",\n        min=0.0001,\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None,\n        \"--anchor-date\",\n        help=\"The anchor date for an interval schedule\",\n    ),\n    rrule_string: Optional[str] = typer.Option(\n        None, \"--rrule\", help=\"Deployment schedule rrule string\"\n    ),\n    cron_string: Optional[str] = typer.Option(\n        None, \"--cron\", help=\"Deployment schedule cron string\"\n    ),\n    cron_day_or: Optional[str] = typer.Option(\n        None,\n        \"--day_or\",\n        help=\"Control how croniter handles `day` and `day_of_week` entries\",\n    ),\n    timezone: Optional[str] = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Deployment schedule timezone string e.g. 'America/New_York'\",\n    ),\n    active: Optional[bool] = typer.Option(\n        True,\n        \"--active\",\n        help=\"Whether the schedule is active. Defaults to True.\",\n    ),\n    replace: Optional[bool] = typer.Option(\n        False,\n        \"--replace\",\n        help=\"Replace the deployment's current schedule(s) with this new schedule.\",\n    ),\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Create a schedule for a given deployment.\n    \"\"\"\n    assert_deployment_name_format(name)\n\n    if sum(option is not None for option in [interval, rrule_string, cron_string]) != 1:\n        exit_with_error(\n            \"Exactly one of `--interval`, `--rrule`, or `--cron` must be provided.\"\n        )\n\n    schedule = None\n\n    if interval_anchor and not interval:\n        exit_with_error(\"An anchor date can only be provided with an interval schedule\")\n\n    if interval is not None:\n        if interval_anchor:\n            try:\n                pendulum.parse(interval_anchor)\n            except ValueError:\n                return exit_with_error(\"The anchor date must be a valid date string.\")\n        interval_schedule = {\n            \"interval\": interval,\n            \"anchor_date\": interval_anchor,\n            \"timezone\": timezone,\n        }\n        schedule = IntervalSchedule(\n            **{k: v for k, v in interval_schedule.items() if v is not None}\n        )\n\n    if cron_string is not None:\n        cron_schedule = {\n            \"cron\": cron_string,\n            \"day_or\": cron_day_or,\n            \"timezone\": timezone,\n        }\n        schedule = CronSchedule(\n            **{k: v for k, v in cron_schedule.items() if v is not None}\n        )\n\n    if rrule_string is not None:\n        # a timezone in the `rrule_string` gets ignored by the RRuleSchedule constructor\n        if \"TZID\" in rrule_string and not timezone:\n            exit_with_error(\n                \"You can provide a timezone by providing a dict with a `timezone` key\"\n                \" to the --rrule option. E.g. {'rrule': 'FREQ=MINUTELY;INTERVAL=5',\"\n                \" 'timezone': 'America/New_York'}.\\nAlternatively, you can provide a\"\n                \" timezone by passing in a --timezone argument.\"\n            )\n        try:\n            schedule = RRuleSchedule(**json.loads(rrule_string))\n            if timezone:\n                # override timezone if specified via CLI argument\n                schedule.timezone = timezone\n        except json.JSONDecodeError:\n            schedule = RRuleSchedule(rrule=rrule_string, timezone=timezone)\n\n    if schedule is None:\n        return exit_with_success(\n            \"Could not create a valid schedule from the provided options.\"\n        )\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {name!r} not found!\")\n\n        num_schedules = len(deployment.schedules)\n        noun = \"schedule\" if num_schedules == 1 else \"schedules\"\n\n        if replace and num_schedules &gt; 0:\n            if not assume_yes and not typer.confirm(\n                f\"Are you sure you want to replace {num_schedules} {noun} for {name}?\"\n            ):\n                return exit_with_error(\"Schedule replacement cancelled.\")\n\n            for existing_schedule in deployment.schedules:\n                try:\n                    await client.delete_deployment_schedule(\n                        deployment.id, existing_schedule.id\n                    )\n                except ObjectNotFound:\n                    pass\n\n        await client.create_deployment_schedules(deployment.id, [(schedule, active)])\n\n        if replace and num_schedules &gt; 0:\n            exit_with_success(f\"Replaced existing deployment {noun} with new schedule!\")\n        else:\n            exit_with_success(\"Created deployment schedule!\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a deployment.</p> <p>\b Examples:     \b     $ prefect deployment delete test_flow/test_deployment     $ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def delete(\n    name: Optional[str] = typer.Argument(\n        None, help=\"A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\"\n    ),\n    deployment_id: Optional[str] = typer.Option(\n        None, \"--id\", help=\"A deployment id to search for if no name is given\"\n    ),\n):\n    \"\"\"\n    Delete a deployment.\n\n    \\b\n    Examples:\n        \\b\n        $ prefect deployment delete test_flow/test_deployment\n        $ prefect deployment delete --id dfd3e220-a130-4149-9af6-8d487e02fea6\n    \"\"\"\n    async with get_client() as client:\n        if name is None and deployment_id is not None:\n            try:\n                await client.delete_deployment(deployment_id)\n                exit_with_success(f\"Deleted deployment '{deployment_id}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {deployment_id!r} not found!\")\n        elif name is not None:\n            try:\n                deployment = await client.read_deployment_by_name(name)\n                await client.delete_deployment(deployment.id)\n                exit_with_success(f\"Deleted deployment '{name}'.\")\n            except ObjectNotFound:\n                exit_with_error(f\"Deployment {name!r} not found!\")\n        else:\n            exit_with_error(\"Must provide a deployment name or id\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.delete_schedule","title":"<code>delete_schedule</code>  <code>async</code>","text":"<p>Delete a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"delete\")\nasync def delete_schedule(\n    deployment_name: str,\n    schedule_id: UUID,\n    assume_yes: Optional[bool] = typer.Option(\n        False,\n        \"--accept-yes\",\n        \"-y\",\n        help=\"Accept the confirmation prompt without prompting\",\n    ),\n):\n    \"\"\"\n    Delete a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if not assume_yes and not typer.confirm(\n            f\"Are you sure you want to delete this schedule: {schedule.schedule}\",\n        ):\n            return exit_with_error(\"Deletion cancelled.\")\n\n        try:\n            await client.delete_deployment_schedule(deployment.id, schedule_id)\n        except ObjectNotFound:\n            exit_with_error(\"Deployment schedule not found!\")\n\n        exit_with_success(f\"Deleted deployment schedule {schedule_id}\")\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a deployment.</p> <p>\b Example:     \b     $ prefect deployment inspect \"hello-world/my-deployment\"     {         'id': '610df9c3-0fb4-4856-b330-67f588d20201',         'created': '2022-08-01T18:36:25.192102+00:00',         'updated': '2022-08-01T18:36:25.188166+00:00',         'name': 'my-deployment',         'description': None,         'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',         'schedules': None,         'parameters': {'name': 'Marvin'},         'tags': ['test'],         'parameter_openapi_schema': {             'title': 'Parameters',             'type': 'object',             'properties': {                 'name': {                     'title': 'name',                     'type': 'string'                 }             },             'required': ['name']         },         'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',         'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',         'infrastructure': {             'type': 'process',             'env': {},             'labels': {},             'name': None,             'command': ['python', '-m', 'prefect.engine'],             'stream_output': True         }     }</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def inspect(name: str):\n    \"\"\"\n    View details about a deployment.\n\n    \\b\n    Example:\n        \\b\n        $ prefect deployment inspect \"hello-world/my-deployment\"\n        {\n            'id': '610df9c3-0fb4-4856-b330-67f588d20201',\n            'created': '2022-08-01T18:36:25.192102+00:00',\n            'updated': '2022-08-01T18:36:25.188166+00:00',\n            'name': 'my-deployment',\n            'description': None,\n            'flow_id': 'b57b0aa2-ef3a-479e-be49-381fb0483b4e',\n            'schedules': None,\n            'parameters': {'name': 'Marvin'},\n            'tags': ['test'],\n            'parameter_openapi_schema': {\n                'title': 'Parameters',\n                'type': 'object',\n                'properties': {\n                    'name': {\n                        'title': 'name',\n                        'type': 'string'\n                    }\n                },\n                'required': ['name']\n            },\n            'storage_document_id': '63ef008f-1e5d-4e07-a0d4-4535731adb32',\n            'infrastructure_document_id': '6702c598-7094-42c8-9785-338d2ec3a028',\n            'infrastructure': {\n                'type': 'process',\n                'env': {},\n                'labels': {},\n                'name': None,\n                'command': ['python', '-m', 'prefect.engine'],\n                'stream_output': True\n            }\n        }\n\n    \"\"\"\n    assert_deployment_name_format(name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(name)\n        except ObjectNotFound:\n            exit_with_error(f\"Deployment {name!r} not found!\")\n\n        deployment_json = deployment.dict(json_compatible=True)\n\n        if deployment.infrastructure_document_id:\n            deployment_json[\"infrastructure\"] = Block._from_block_document(\n                await client.read_block_document(deployment.infrastructure_document_id)\n            ).dict(\n                exclude={\"_block_document_id\", \"_block_document_name\", \"_is_anonymous\"}\n            )\n\n        if client.server_type.supports_automations():\n            deployment_json[\"automations\"] = [\n                a.dict()\n                for a in await client.read_resource_related_automations(\n                    f\"prefect.deployment.{deployment.id}\"\n                )\n            ]\n\n    app.console.print(Pretty(deployment_json))\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.list_schedules","title":"<code>list_schedules</code>  <code>async</code>","text":"<p>View all schedules for a deployment.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"ls\")\nasync def list_schedules(deployment_name: str):\n    \"\"\"\n    View all schedules for a deployment.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n    def sort_by_created_key(schedule: DeploymentSchedule):  # type: ignore\n        assert schedule.created is not None, \"All schedules should have a created time.\"\n        return pendulum.now(\"utc\") - schedule.created\n\n    def schedule_details(schedule: DeploymentSchedule) -&gt; str:\n        if isinstance(schedule.schedule, IntervalSchedule):\n            return f\"interval: {schedule.schedule.interval}s\"\n        elif isinstance(schedule.schedule, CronSchedule):\n            return f\"cron: {schedule.schedule.cron}\"\n        elif isinstance(schedule.schedule, RRuleSchedule):\n            return f\"rrule: {schedule.schedule.rrule}\"\n        else:\n            return \"unknown\"\n\n    table = Table(\n        title=\"Deployment Schedules\",\n    )\n    table.add_column(\"ID\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Schedule\", style=\"cyan\", no_wrap=False)\n    table.add_column(\"Active\", style=\"purple\", no_wrap=True)\n\n    for schedule in sorted(deployment.schedules, key=sort_by_created_key):\n        table.add_row(\n            str(schedule.id),\n            schedule_details(schedule),\n            str(schedule.active),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all deployments or deployments for specific flows.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def ls(flow_name: Optional[List[str]] = None, by_created: bool = False):\n    \"\"\"\n    View all deployments or deployments for specific flows.\n    \"\"\"\n    async with get_client() as client:\n        deployments = await client.read_deployments(\n            flow_filter=FlowFilter(name={\"any_\": flow_name}) if flow_name else None\n        )\n        flows = {\n            flow.id: flow\n            for flow in await client.read_flows(\n                flow_filter=FlowFilter(id={\"any_\": [d.flow_id for d in deployments]})\n            )\n        }\n\n    def sort_by_name_keys(d):\n        return flows[d.flow_id].name, d.name\n\n    def sort_by_created_key(d):\n        return pendulum.now(\"utc\") - d.created\n\n    table = Table(\n        title=\"Deployments\",\n    )\n    table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(\"ID\", style=\"cyan\", no_wrap=True)\n\n    for deployment in sorted(\n        deployments, key=sort_by_created_key if by_created else sort_by_name_keys\n    ):\n        table.add_row(\n            f\"{flows[deployment.flow_id].name}/[bold]{deployment.name}[/]\",\n            str(deployment.id),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.pause_schedule","title":"<code>pause_schedule</code>  <code>async</code>","text":"<p>Pause a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"pause\")\nasync def pause_schedule(deployment_name: str, schedule_id: UUID):\n    \"\"\"\n    Pause a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if not schedule.active:\n            return exit_with_error(\n                f\"Deployment schedule {schedule_id} is already inactive\"\n            )\n\n        await client.update_deployment_schedule(\n            deployment.id, schedule_id, active=False\n        )\n        exit_with_success(\n            f\"Paused schedule {schedule.schedule} for deployment {deployment_name}\"\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.resume_schedule","title":"<code>resume_schedule</code>  <code>async</code>","text":"<p>Resume a deployment schedule.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@schedule_app.command(\"resume\")\nasync def resume_schedule(deployment_name: str, schedule_id: UUID):\n    \"\"\"\n    Resume a deployment schedule.\n    \"\"\"\n    assert_deployment_name_format(deployment_name)\n\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(deployment_name)\n        except ObjectNotFound:\n            return exit_with_error(f\"Deployment {deployment_name!r} not found!\")\n\n        try:\n            schedule = [s for s in deployment.schedules if s.id == schedule_id][0]\n        except IndexError:\n            return exit_with_error(\"Deployment schedule not found!\")\n\n        if schedule.active:\n            return exit_with_error(\n                f\"Deployment schedule {schedule_id} is already active\"\n            )\n\n        await client.update_deployment_schedule(deployment.id, schedule_id, active=True)\n        exit_with_success(\n            f\"Resumed schedule {schedule.schedule} for deployment {deployment_name}\"\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.run","title":"<code>run</code>  <code>async</code>","text":"<p>Create a flow run for the given flow and deployment.</p> <p>The flow run will be scheduled to run immediately unless <code>--start-in</code> or <code>--start-at</code> is specified. The flow run will not execute until a worker starts. To watch the flow run until it reaches a terminal state, use the <code>--watch</code> flag.</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>@deployment_app.command()\nasync def run(\n    name: Optional[str] = typer.Argument(\n        None, help=\"A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\"\n    ),\n    deployment_id: Optional[str] = typer.Option(\n        None,\n        \"--id\",\n        help=(\"A deployment id to search for if no name is given\"),\n    ),\n    job_variables: List[str] = typer.Option(\n        None,\n        \"-jv\",\n        \"--job-variable\",\n        help=(\n            \"A key, value pair (key=value) specifying a flow run job variable. The value will\"\n            \" be interpreted as JSON. May be passed multiple times to specify multiple\"\n            \" job variable values.\"\n        ),\n    ),\n    params: List[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--param\",\n        help=(\n            \"A key, value pair (key=value) specifying a flow parameter. The value will\"\n            \" be interpreted as JSON. May be passed multiple times to specify multiple\"\n            \" parameter values.\"\n        ),\n    ),\n    multiparams: Optional[str] = typer.Option(\n        None,\n        \"--params\",\n        help=(\n            \"A mapping of parameters to values. To use a stdin, pass '-'. Any \"\n            \"parameters passed with `--param` will take precedence over these values.\"\n        ),\n    ),\n    start_in: Optional[str] = typer.Option(\n        None,\n        \"--start-in\",\n        help=(\n            \"A human-readable string specifying a time interval to wait before starting\"\n            \" the flow run. E.g. 'in 5 minutes', 'in 1 hour', 'in 2 days'.\"\n        ),\n    ),\n    start_at: Optional[str] = typer.Option(\n        None,\n        \"--start-at\",\n        help=(\n            \"A human-readable string specifying a time to start the flow run. E.g.\"\n            \" 'at 5:30pm', 'at 2022-08-01 17:30', 'at 2022-08-01 17:30:00'.\"\n        ),\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"--tag\",\n        help=(\"Tag(s) to be applied to flow run.\"),\n    ),\n    watch: bool = typer.Option(\n        False,\n        \"--watch\",\n        help=(\"Whether to poll the flow run until a terminal state is reached.\"),\n    ),\n    watch_interval: Optional[int] = typer.Option(\n        None,\n        \"--watch-interval\",\n        help=(\"How often to poll the flow run for state changes (in seconds).\"),\n    ),\n    watch_timeout: Optional[int] = typer.Option(\n        None,\n        \"--watch-timeout\",\n        help=(\"Timeout for --watch.\"),\n    ),\n):\n    \"\"\"\n    Create a flow run for the given flow and deployment.\n\n    The flow run will be scheduled to run immediately unless `--start-in` or `--start-at` is specified.\n    The flow run will not execute until a worker starts.\n    To watch the flow run until it reaches a terminal state, use the `--watch` flag.\n    \"\"\"\n    import dateparser\n\n    now = pendulum.now(\"UTC\")\n\n    multi_params = {}\n    if multiparams:\n        if multiparams == \"-\":\n            multiparams = sys.stdin.read()\n            if not multiparams:\n                exit_with_error(\"No data passed to stdin\")\n\n        try:\n            multi_params = json.loads(multiparams)\n        except ValueError as exc:\n            exit_with_error(f\"Failed to parse JSON: {exc}\")\n        if watch_interval and not watch:\n            exit_with_error(\n                \"`--watch-interval` can only be used with `--watch`.\",\n            )\n    cli_params = _load_json_key_values(params or [], \"parameter\")\n    conflicting_keys = set(cli_params.keys()).intersection(multi_params.keys())\n    if conflicting_keys:\n        app.console.print(\n            \"The following parameters were specified by `--param` and `--params`, the \"\n            f\"`--param` value will be used: {conflicting_keys}\"\n        )\n    parameters = {**multi_params, **cli_params}\n\n    job_vars = _load_json_key_values(job_variables or [], \"job variable\")\n    if start_in and start_at:\n        exit_with_error(\n            \"Only one of `--start-in` or `--start-at` can be set, not both.\"\n        )\n\n    elif start_in is None and start_at is None:\n        scheduled_start_time = now\n        human_dt_diff = \" (now)\"\n    else:\n        if start_in:\n            start_time_raw = \"in \" + start_in\n        else:\n            start_time_raw = \"at \" + start_at\n        with warnings.catch_warnings():\n            # PyTZ throws a warning based on dateparser usage of the library\n            # See https://github.com/scrapinghub/dateparser/issues/1089\n            warnings.filterwarnings(\"ignore\", module=\"dateparser\")\n\n            try:\n                start_time_parsed = dateparser.parse(\n                    start_time_raw,\n                    settings={\n                        \"TO_TIMEZONE\": \"UTC\",\n                        \"RETURN_AS_TIMEZONE_AWARE\": False,\n                        \"PREFER_DATES_FROM\": \"future\",\n                        \"RELATIVE_BASE\": datetime.fromtimestamp(\n                            now.timestamp(), tz=timezone.utc\n                        ),\n                    },\n                )\n\n            except Exception as exc:\n                exit_with_error(f\"Failed to parse '{start_time_raw!r}': {exc!s}\")\n\n        if start_time_parsed is None:\n            exit_with_error(f\"Unable to parse scheduled start time {start_time_raw!r}.\")\n\n        scheduled_start_time = pendulum.instance(start_time_parsed)\n        human_dt_diff = (\n            \" (\" + pendulum.format_diff(scheduled_start_time.diff(now)) + \")\"\n        )\n\n    async with get_client() as client:\n        deployment = await get_deployment(client, name, deployment_id)\n        flow = await client.read_flow(deployment.flow_id)\n\n        deployment_parameters = deployment.parameter_openapi_schema[\"properties\"].keys()\n        unknown_keys = set(parameters.keys()).difference(deployment_parameters)\n        if unknown_keys:\n            available_parameters = (\n                (\n                    \"The following parameters are available on the deployment: \"\n                    + listrepr(deployment_parameters, sep=\", \")\n                )\n                if deployment_parameters\n                else \"This deployment does not accept parameters.\"\n            )\n\n            exit_with_error(\n                \"The following parameters were specified but not found on the \"\n                f\"deployment: {listrepr(unknown_keys, sep=', ')}\"\n                f\"\\n{available_parameters}\"\n            )\n\n        app.console.print(\n            f\"Creating flow run for deployment '{flow.name}/{deployment.name}'...\",\n        )\n\n        try:\n            flow_run = await client.create_flow_run_from_deployment(\n                deployment.id,\n                parameters=parameters,\n                state=Scheduled(scheduled_time=scheduled_start_time),\n                tags=tags,\n                job_variables=job_vars,\n            )\n        except PrefectHTTPStatusError as exc:\n            detail = exc.response.json().get(\"detail\")\n            if detail:\n                exit_with_error(\n                    exc.response.json()[\"detail\"],\n                )\n            else:\n                raise\n\n    if PREFECT_UI_URL:\n        run_url = f\"{PREFECT_UI_URL.value()}/flow-runs/flow-run/{flow_run.id}\"\n    else:\n        run_url = \"&lt;no dashboard available&gt;\"\n\n    datetime_local_tz = scheduled_start_time.in_tz(pendulum.tz.local_timezone())\n    scheduled_display = (\n        datetime_local_tz.to_datetime_string()\n        + \" \"\n        + datetime_local_tz.tzname()\n        + human_dt_diff\n    )\n\n    app.console.print(f\"Created flow run {flow_run.name!r}.\")\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n        \u2514\u2500\u2500 UUID: {flow_run.id}\n        \u2514\u2500\u2500 Parameters: {flow_run.parameters}\n        \u2514\u2500\u2500 Job Variables: {flow_run.job_variables}\n        \u2514\u2500\u2500 Scheduled start time: {scheduled_display}\n        \u2514\u2500\u2500 URL: {run_url}\n        \"\"\"\n        ).strip(),\n        soft_wrap=True,\n    )\n    if watch:\n        watch_interval = 5 if watch_interval is None else watch_interval\n        app.console.print(f\"Watching flow run {flow_run.name!r}...\")\n        finished_flow_run = await wait_for_flow_run(\n            flow_run.id,\n            timeout=watch_timeout,\n            poll_interval=watch_interval,\n            log_states=True,\n        )\n        finished_flow_run_state = finished_flow_run.state\n        if finished_flow_run_state.is_completed():\n            exit_with_success(\n                f\"Flow run finished successfully in {finished_flow_run_state.name!r}.\"\n            )\n        exit_with_error(\n            f\"Flow run finished in state {finished_flow_run_state.name!r}.\",\n            code=1,\n        )\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/deployment/#prefect.cli.deployment.str_presenter","title":"<code>str_presenter</code>","text":"<p>configures yaml for dumping multiline strings Ref: https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data</p> Source code in <code>prefect/cli/deployment.py</code> <pre><code>def str_presenter(dumper, data):\n    \"\"\"\n    configures yaml for dumping multiline strings\n    Ref: https://stackoverflow.com/questions/8640959/how-can-i-control-what-scalar-form-pyyaml-uses-for-my-data\n    \"\"\"\n    if len(data.splitlines()) &gt; 1:  # check for multiline string\n        return dumper.represent_scalar(\"tag:yaml.org,2002:str\", data, style=\"|\")\n    return dumper.represent_scalar(\"tag:yaml.org,2002:str\", data)\n</code></pre>","tags":["Python API","CLI","deployments"]},{"location":"api-ref/prefect/cli/dev/","title":"dev","text":"","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev","title":"<code>prefect.cli.dev</code>","text":"<p>Command line interface for working with Prefect Server</p>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.agent","title":"<code>agent</code>  <code>async</code>","text":"<p>Starts a hot-reloading development agent process.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def agent(\n    api_url: str = SettingsOption(PREFECT_API_URL),\n    work_queues: List[str] = typer.Option(\n        [\"default\"],\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Starts a hot-reloading development agent process.\n    \"\"\"\n    # Delayed import since this is only a 'dev' dependency\n    import watchfiles\n\n    app.console.print(\"Creating hot-reloading agent process...\")\n\n    try:\n        await watchfiles.arun_process(\n            prefect.__module_path__,\n            target=agent_process_entrypoint,\n            kwargs=dict(api=api_url, work_queues=work_queues),\n        )\n    except RuntimeError as err:\n        # a bug in watchfiles causes an 'Already borrowed' error from Rust when\n        # exiting: https://github.com/samuelcolvin/watchfiles/issues/200\n        if str(err).strip() != \"Already borrowed\":\n            raise\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.agent_process_entrypoint","title":"<code>agent_process_entrypoint</code>","text":"<p>An entrypoint for starting an agent in a subprocess. Adds a Rich console to the Typer app, processes Typer default parameters, then starts an agent. All kwargs are forwarded to  <code>prefect.cli.agent.start</code>.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>def agent_process_entrypoint(**kwargs):\n    \"\"\"\n    An entrypoint for starting an agent in a subprocess. Adds a Rich console\n    to the Typer app, processes Typer default parameters, then starts an agent.\n    All kwargs are forwarded to  `prefect.cli.agent.start`.\n    \"\"\"\n    import inspect\n\n    # import locally so only the `dev` command breaks if Typer internals change\n    from typer.models import ParameterInfo\n\n    # Typer does not process default parameters when calling a function\n    # directly, so we must set `start_agent`'s default parameters manually.\n    # get the signature of the `start_agent` function\n    start_agent_signature = inspect.signature(start_agent)\n\n    # for any arguments not present in kwargs, use the default value.\n    for name, param in start_agent_signature.parameters.items():\n        if name not in kwargs:\n            # All `param.default` values for start_agent are Typer params that store the\n            # actual default value in their `default` attribute and we must call\n            # `param.default.default` to get the actual default value. We should also\n            # ensure we extract the right default if non-Typer defaults are added\n            # to `start_agent` in the future.\n            if isinstance(param.default, ParameterInfo):\n                default = param.default.default\n            else:\n                default = param.default\n\n            # Some defaults are Prefect `SettingsOption.value` methods\n            # that must be called to get the actual value.\n            kwargs[name] = default() if callable(default) else default\n\n    try:\n        start_agent(**kwargs)  # type: ignore\n    except KeyboardInterrupt:\n        # expected when watchfiles kills the process\n        pass\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.api","title":"<code>api</code>  <code>async</code>","text":"<p>Starts a hot-reloading development API.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def api(\n    host: str = SettingsOption(PREFECT_SERVER_API_HOST),\n    port: int = SettingsOption(PREFECT_SERVER_API_PORT),\n    log_level: str = \"DEBUG\",\n    services: bool = True,\n):\n    \"\"\"\n    Starts a hot-reloading development API.\n    \"\"\"\n    import watchfiles\n\n    server_env = os.environ.copy()\n    server_env[\"PREFECT_API_SERVICES_RUN_IN_APP\"] = str(services)\n    server_env[\"PREFECT_API_SERVICES_UI\"] = \"False\"\n    server_env[\"PREFECT_UI_API_URL\"] = f\"http://{host}:{port}/api\"\n\n    command = [\n        sys.executable,\n        \"-m\",\n        \"uvicorn\",\n        \"--factory\",\n        \"prefect.server.api.server:create_app\",\n        \"--host\",\n        str(host),\n        \"--port\",\n        str(port),\n        \"--log-level\",\n        log_level.lower(),\n    ]\n\n    app.console.print(f\"Running: {' '.join(command)}\")\n    import signal\n\n    stop_event = anyio.Event()\n    start_command = partial(\n        run_process, command=command, env=server_env, stream_output=True\n    )\n\n    async with anyio.create_task_group() as tg:\n        try:\n            server_pid = await tg.start(start_command)\n            async for _ in watchfiles.awatch(\n                prefect.__module_path__,\n                stop_event=stop_event,  # type: ignore\n            ):\n                # when any watched files change, restart the server\n                app.console.print(\"Restarting Prefect Server...\")\n                os.kill(server_pid, signal.SIGTERM)  # type: ignore\n                # start a new server\n                server_pid = await tg.start(start_command)\n        except RuntimeError as err:\n            # a bug in watchfiles causes an 'Already borrowed' error from Rust when\n            # exiting: https://github.com/samuelcolvin/watchfiles/issues/200\n            if str(err).strip() != \"Already borrowed\":\n                raise\n        except KeyboardInterrupt:\n            # exit cleanly on ctrl-c by killing the server process if it's\n            # still running\n            try:\n                os.kill(server_pid, signal.SIGTERM)  # type: ignore\n            except ProcessLookupError:\n                # process already exited\n                pass\n\n            stop_event.set()\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.build_docs","title":"<code>build_docs</code>","text":"<p>Builds REST API reference documentation for static display.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef build_docs(\n    schema_path: str = None,\n):\n    \"\"\"\n    Builds REST API reference documentation for static display.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n\n    from prefect.server.api.server import create_app\n\n    schema = create_app(ephemeral=True).openapi()\n\n    if not schema_path:\n        schema_path = (\n            prefect.__development_base_path__ / \"docs\" / \"api-ref\" / \"schema.json\"\n        ).absolute()\n    # overwrite info for display purposes\n    schema[\"info\"] = {}\n    with open(schema_path, \"w\") as f:\n        json.dump(schema, f)\n    app.console.print(f\"OpenAPI schema written to {schema_path}\")\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.build_image","title":"<code>build_image</code>","text":"<p>Build a docker image for development.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef build_image(\n    arch: str = typer.Option(\n        None,\n        help=(\n            \"The architecture to build the container for. \"\n            \"Defaults to the architecture of the host Python. \"\n            f\"[default: {platform.machine()}]\"\n        ),\n    ),\n    python_version: str = typer.Option(\n        None,\n        help=(\n            \"The Python version to build the container for. \"\n            \"Defaults to the version of the host Python. \"\n            f\"[default: {python_version_minor()}]\"\n        ),\n    ),\n    flavor: str = typer.Option(\n        None,\n        help=(\n            \"An alternative flavor to build, for example 'conda'. \"\n            \"Defaults to the standard Python base image\"\n        ),\n    ),\n    dry_run: bool = False,\n):\n    \"\"\"\n    Build a docker image for development.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    # TODO: Once https://github.com/tiangolo/typer/issues/354 is addressed, the\n    #       default can be set in the function signature\n    arch = arch or platform.machine()\n    python_version = python_version or python_version_minor()\n\n    tag = get_prefect_image_name(python_version=python_version, flavor=flavor)\n\n    # Here we use a subprocess instead of the docker-py client to easily stream output\n    # as it comes\n    command = [\n        \"docker\",\n        \"build\",\n        str(prefect.__development_base_path__),\n        \"--tag\",\n        tag,\n        \"--platform\",\n        f\"linux/{arch}\",\n        \"--build-arg\",\n        \"PREFECT_EXTRAS=[dev]\",\n        \"--build-arg\",\n        f\"PYTHON_VERSION={python_version}\",\n    ]\n\n    if flavor:\n        command += [\"--build-arg\", f\"BASE_IMAGE=prefect-{flavor}\"]\n\n    if dry_run:\n        print(\" \".join(command))\n        return\n\n    try:\n        subprocess.check_call(command, shell=sys.platform == \"win32\")\n    except subprocess.CalledProcessError:\n        exit_with_error(\"Failed to build image!\")\n    else:\n        exit_with_success(f\"Built image {tag!r} for linux/{arch}\")\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.container","title":"<code>container</code>","text":"<p>Run a docker container with local code mounted and installed.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef container(bg: bool = False, name=\"prefect-dev\", api: bool = True, tag: str = None):\n    \"\"\"\n    Run a docker container with local code mounted and installed.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    import docker\n    from docker.models.containers import Container\n\n    client = docker.from_env()\n\n    containers = client.containers.list()\n    container_names = {container.name for container in containers}\n    if name in container_names:\n        exit_with_error(\n            f\"Container {name!r} already exists. Specify a different name or stop \"\n            \"the existing container.\"\n        )\n\n    blocking_cmd = \"prefect dev api\" if api else \"sleep infinity\"\n    tag = tag or get_prefect_image_name()\n\n    container: Container = client.containers.create(\n        image=tag,\n        command=[\n            \"/bin/bash\",\n            \"-c\",\n            (  # noqa\n                \"pip install -e /opt/prefect/repo\\\\[dev\\\\] &amp;&amp; touch /READY &amp;&amp;\"\n                f\" {blocking_cmd}\"\n            ),\n        ],\n        name=name,\n        auto_remove=True,\n        working_dir=\"/opt/prefect/repo\",\n        volumes=[f\"{prefect.__development_base_path__}:/opt/prefect/repo\"],\n        shm_size=\"4G\",\n    )\n\n    print(f\"Starting container for image {tag!r}...\")\n    container.start()\n\n    print(\"Waiting for installation to complete\", end=\"\", flush=True)\n    try:\n        ready = False\n        while not ready:\n            print(\".\", end=\"\", flush=True)\n            result = container.exec_run(\"test -f /READY\")\n            ready = result.exit_code == 0\n            if not ready:\n                time.sleep(3)\n    except BaseException:\n        print(\"\\nInterrupted. Stopping container...\")\n        container.stop()\n        raise\n\n    print(\n        textwrap.dedent(\n            f\"\"\"\n            Container {container.name!r} is ready! To connect to the container, run:\n\n                docker exec -it {container.name} /bin/bash\n            \"\"\"\n        )\n    )\n\n    if bg:\n        print(\n            textwrap.dedent(\n                f\"\"\"\n                The container will run forever. Stop the container with:\n\n                    docker stop {container.name}\n                \"\"\"\n            )\n        )\n        # Exit without stopping\n        return\n\n    try:\n        print(\"Send a keyboard interrupt to exit...\")\n        container.wait()\n    except KeyboardInterrupt:\n        pass  # Avoid showing \"Abort\"\n    finally:\n        print(\"\\nStopping container...\")\n        container.stop()\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.kubernetes_manifest","title":"<code>kubernetes_manifest</code>","text":"<p>Generates a Kubernetes manifest for development.</p> Example <p>$ prefect dev kubernetes-manifest | kubectl apply -f -</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\ndef kubernetes_manifest():\n    \"\"\"\n    Generates a Kubernetes manifest for development.\n\n    Example:\n        $ prefect dev kubernetes-manifest | kubectl apply -f -\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-dev.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"prefect_root_directory\": prefect.__development_base_path__,\n            \"image_name\": get_prefect_image_name(),\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.start","title":"<code>start</code>  <code>async</code>","text":"<p>Starts a hot-reloading development server with API, UI, and agent processes.</p> <p>Each service has an individual command if you wish to start them separately. Each service can be excluded here as well.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def start(\n    exclude_api: bool = typer.Option(False, \"--no-api\"),\n    exclude_ui: bool = typer.Option(False, \"--no-ui\"),\n    exclude_agent: bool = typer.Option(False, \"--no-agent\"),\n    work_queues: List[str] = typer.Option(\n        [\"default\"],\n        \"-q\",\n        \"--work-queue\",\n        help=\"One or more work queue names for the dev agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Starts a hot-reloading development server with API, UI, and agent processes.\n\n    Each service has an individual command if you wish to start them separately.\n    Each service can be excluded here as well.\n    \"\"\"\n    async with anyio.create_task_group() as tg:\n        if not exclude_api:\n            tg.start_soon(\n                partial(\n                    api,\n                    host=PREFECT_SERVER_API_HOST.value(),\n                    port=PREFECT_SERVER_API_PORT.value(),\n                )\n            )\n        if not exclude_ui:\n            tg.start_soon(ui)\n        if not exclude_agent:\n            # Hook the agent to the hosted API if running\n            if not exclude_api:\n                host = f\"http://{PREFECT_SERVER_API_HOST.value()}:{PREFECT_SERVER_API_PORT.value()}/api\"  # noqa\n            else:\n                host = PREFECT_API_URL.value()\n            tg.start_soon(agent, host, work_queues)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/dev/#prefect.cli.dev.ui","title":"<code>ui</code>  <code>async</code>","text":"<p>Starts a hot-reloading development UI.</p> Source code in <code>prefect/cli/dev.py</code> <pre><code>@dev_app.command()\nasync def ui():\n    \"\"\"\n    Starts a hot-reloading development UI.\n    \"\"\"\n    exit_with_error_if_not_editable_install()\n    with tmpchdir(prefect.__development_base_path__ / \"ui\"):\n        app.console.print(\"Installing npm packages...\")\n        await run_process([\"npm\", \"install\"], stream_output=True)\n\n        app.console.print(\"Starting UI development server...\")\n        await run_process(command=[\"npm\", \"run\", \"serve\"], stream_output=True)\n</code></pre>","tags":["Python API","CLI","development"]},{"location":"api-ref/prefect/cli/events/","title":"Events","text":"","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/events/#prefect.cli.events","title":"<code>prefect.cli.events</code>","text":"","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/events/#prefect.cli.events.stream","title":"<code>stream</code>  <code>async</code>","text":"<p>Subscribes to the event stream of a workspace, printing each event as it is received. By default, events are printed as JSON, but can be printed as text by passing <code>--format text</code>.</p> Source code in <code>prefect/cli/events.py</code> <pre><code>@events_app.command()\nasync def stream(\n    format: StreamFormat = typer.Option(\n        StreamFormat.json, \"--format\", help=\"Output format (json or text)\"\n    ),\n    output_file: str = typer.Option(\n        None, \"--output-file\", help=\"File to write events to\"\n    ),\n    account: bool = typer.Option(\n        False,\n        \"--account\",\n        help=\"Stream events for entire account, including audit logs\",\n    ),\n    run_once: bool = typer.Option(False, \"--run-once\", help=\"Stream only one event\"),\n):\n    \"\"\"Subscribes to the event stream of a workspace, printing each event\n    as it is received. By default, events are printed as JSON, but can be\n    printed as text by passing `--format text`.\n    \"\"\"\n\n    try:\n        if account:\n            events_subscriber = PrefectCloudAccountEventSubscriber()\n        else:\n            events_subscriber = get_events_subscriber()\n\n        app.console.print(\"Subscribing to event stream...\")\n        async with events_subscriber as subscriber:\n            async for event in subscriber:\n                await handle_event(event, format, output_file)\n                if run_once:\n                    typer.Exit(0)\n    except Exception as exc:\n        handle_error(exc)\n</code></pre>","tags":["Python API","CLI","Events"]},{"location":"api-ref/prefect/cli/flow/","title":"flow","text":"","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow","title":"<code>prefect.cli.flow</code>","text":"<p>Command line interface for working with flows.</p>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View flows.</p> Source code in <code>prefect/cli/flow.py</code> <pre><code>@flow_app.command()\nasync def ls(\n    limit: int = 15,\n):\n    \"\"\"\n    View flows.\n    \"\"\"\n    async with get_client() as client:\n        flows = await client.read_flows(\n            limit=limit,\n            sort=FlowSort.CREATED_DESC,\n        )\n\n    table = Table(title=\"Flows\")\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Created\", no_wrap=True)\n\n    for flow in flows:\n        table.add_row(\n            str(flow.id),\n            str(flow.name),\n            str(flow.created),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow/#prefect.cli.flow.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Serve a flow via an entrypoint.</p> Source code in <code>prefect/cli/flow.py</code> <pre><code>@flow_app.command()\nasync def serve(\n    entrypoint: str = typer.Argument(\n        ...,\n        help=(\n            \"The path to a file containing a flow and the name of the flow function in\"\n            \" the format `./path/to/file.py:flow_func_name`.\"\n        ),\n    ),\n    name: str = typer.Option(\n        ...,\n        \"--name\",\n        \"-n\",\n        help=\"The name to give the deployment created for the flow.\",\n    ),\n    description: Optional[str] = typer.Option(\n        None,\n        \"--description\",\n        \"-d\",\n        help=(\n            \"The description to give the created deployment. If not provided, the\"\n            \" description will be populated from the flow's description.\"\n        ),\n    ),\n    version: Optional[str] = typer.Option(\n        None, \"-v\", \"--version\", help=\"A version to give the created deployment.\"\n    ),\n    tags: Optional[List[str]] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=\"One or more optional tags to apply to the created deployment.\",\n    ),\n    cron: Optional[str] = typer.Option(\n        None,\n        \"--cron\",\n        help=(\n            \"A cron string that will be used to set a schedule for the created\"\n            \" deployment.\"\n        ),\n    ),\n    interval: Optional[int] = typer.Option(\n        None,\n        \"--interval\",\n        help=(\n            \"An integer specifying an interval (in seconds) between scheduled runs of\"\n            \" the flow.\"\n        ),\n    ),\n    interval_anchor: Optional[str] = typer.Option(\n        None, \"--anchor-date\", help=\"The start date for an interval schedule.\"\n    ),\n    rrule: Optional[str] = typer.Option(\n        None,\n        \"--rrule\",\n        help=\"An RRule that will be used to set a schedule for the created deployment.\",\n    ),\n    timezone: Optional[str] = typer.Option(\n        None,\n        \"--timezone\",\n        help=\"Timezone to used scheduling flow runs e.g. 'America/New_York'\",\n    ),\n    pause_on_shutdown: bool = typer.Option(\n        True,\n        help=(\n            \"If set, provided schedule will be paused when the serve command is\"\n            \" stopped. If not set, the schedules will continue running.\"\n        ),\n    ),\n):\n    \"\"\"\n    Serve a flow via an entrypoint.\n    \"\"\"\n    runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown)\n    try:\n        schedules = []\n        if interval or cron or rrule:\n            schedule = construct_schedule(\n                interval=interval,\n                cron=cron,\n                rrule=rrule,\n                timezone=timezone,\n                anchor_date=interval_anchor,\n            )\n            schedules = [MinimalDeploymentSchedule(schedule=schedule, active=True)]\n\n        runner_deployment = RunnerDeployment.from_entrypoint(\n            entrypoint=entrypoint,\n            name=name,\n            schedules=schedules,\n            description=description,\n            tags=tags or [],\n            version=version,\n        )\n    except (MissingFlowError, ValueError) as exc:\n        exit_with_error(str(exc))\n    deployment_id = await runner.add_deployment(runner_deployment)\n\n    help_message = (\n        f\"[green]Your flow {runner_deployment.flow_name!r} is being served and polling\"\n        \" for scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the following\"\n        \" command:\\n[blue]\\n\\t$ prefect deployment run\"\n        f\" '{runner_deployment.flow_name}/{name}'\\n[/]\"\n    )\n    if PREFECT_UI_URL:\n        help_message += (\n            \"\\nYou can also run your flow via the Prefect UI:\"\n            f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n        )\n\n    app.console.print(help_message, soft_wrap=True)\n    await runner.start()\n</code></pre>","tags":["Python API","flows","CLI"]},{"location":"api-ref/prefect/cli/flow_run/","title":"flow_run","text":"","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run","title":"<code>prefect.cli.flow_run</code>","text":"<p>Command line interface for working with flow runs</p>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.cancel","title":"<code>cancel</code>  <code>async</code>","text":"<p>Cancel a flow run by ID.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def cancel(id: UUID):\n    \"\"\"Cancel a flow run by ID.\"\"\"\n    async with get_client() as client:\n        cancelling_state = State(type=StateType.CANCELLING)\n        try:\n            result = await client.set_flow_run_state(\n                flow_run_id=id, state=cancelling_state\n            )\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run '{id}' not found!\")\n\n    if result.status == SetStateStatus.ABORT:\n        exit_with_error(\n            f\"Flow run '{id}' was unable to be cancelled. Reason:\"\n            f\" '{result.details.reason}'\"\n        )\n\n    exit_with_success(f\"Flow run '{id}' was successfully scheduled for cancellation.\")\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a flow run by ID.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def delete(id: UUID):\n    \"\"\"\n    Delete a flow run by ID.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.delete_flow_run(id)\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run '{id}' not found!\")\n\n    exit_with_success(f\"Successfully deleted flow run '{id}'.\")\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a flow run.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def inspect(id: UUID):\n    \"\"\"\n    View details about a flow run.\n    \"\"\"\n    async with get_client() as client:\n        try:\n            flow_run = await client.read_flow_run(id)\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code == status.HTTP_404_NOT_FOUND:\n                exit_with_error(f\"Flow run {id!r} not found!\")\n            else:\n                raise\n\n    app.console.print(Pretty(flow_run))\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.logs","title":"<code>logs</code>  <code>async</code>","text":"<p>View logs for a flow run.</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def logs(\n    id: UUID,\n    head: bool = typer.Option(\n        False,\n        \"--head\",\n        \"-h\",\n        help=(\n            f\"Show the first {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of\"\n            \" all logs.\"\n        ),\n    ),\n    num_logs: int = typer.Option(\n        None,\n        \"--num-logs\",\n        \"-n\",\n        help=(\n            \"Number of logs to show when using the --head or --tail flag. If None,\"\n            f\" defaults to {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS}.\"\n        ),\n        min=1,\n    ),\n    reverse: bool = typer.Option(\n        False,\n        \"--reverse\",\n        \"-r\",\n        help=\"Reverse the logs order to print the most recent logs first\",\n    ),\n    tail: bool = typer.Option(\n        False,\n        \"--tail\",\n        \"-t\",\n        help=(\n            f\"Show the last {LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS} logs instead of\"\n            \" all logs.\"\n        ),\n    ),\n):\n    \"\"\"\n    View logs for a flow run.\n    \"\"\"\n    # Pagination - API returns max 200 (LOGS_DEFAULT_PAGE_SIZE) logs at a time\n    offset = 0\n    more_logs = True\n    num_logs_returned = 0\n\n    # if head and tail flags are being used together\n    if head and tail:\n        exit_with_error(\"Please provide either a `head` or `tail` option but not both.\")\n\n    user_specified_num_logs = (\n        num_logs or LOGS_WITH_LIMIT_FLAG_DEFAULT_NUM_LOGS\n        if head or tail or num_logs\n        else None\n    )\n\n    # if using tail update offset according to LOGS_DEFAULT_PAGE_SIZE\n    if tail:\n        offset = max(0, user_specified_num_logs - LOGS_DEFAULT_PAGE_SIZE)\n\n    log_filter = LogFilter(flow_run_id={\"any_\": [id]})\n\n    async with get_client() as client:\n        # Get the flow run\n        try:\n            flow_run = await client.read_flow_run(id)\n        except ObjectNotFound:\n            exit_with_error(f\"Flow run {str(id)!r} not found!\")\n\n        while more_logs:\n            num_logs_to_return_from_page = (\n                LOGS_DEFAULT_PAGE_SIZE\n                if user_specified_num_logs is None\n                else min(\n                    LOGS_DEFAULT_PAGE_SIZE, user_specified_num_logs - num_logs_returned\n                )\n            )\n\n            # Get the next page of logs\n            page_logs = await client.read_logs(\n                log_filter=log_filter,\n                limit=num_logs_to_return_from_page,\n                offset=offset,\n                sort=(\n                    LogSort.TIMESTAMP_DESC if reverse or tail else LogSort.TIMESTAMP_ASC\n                ),\n            )\n\n            for log in reversed(page_logs) if tail and not reverse else page_logs:\n                app.console.print(\n                    # Print following the flow run format (declared in logging.yml)\n                    (\n                        f\"{pendulum.instance(log.timestamp).to_datetime_string()}.{log.timestamp.microsecond // 1000:03d} |\"\n                        f\" {logging.getLevelName(log.level):7s} | Flow run\"\n                        f\" {flow_run.name!r} - {log.message}\"\n                    ),\n                    soft_wrap=True,\n                )\n\n            # Update the number of logs retrieved\n            num_logs_returned += num_logs_to_return_from_page\n\n            if tail:\n                #  If the current offset is not 0, update the offset for the next page\n                if offset != 0:\n                    offset = (\n                        0\n                        # Reset the offset to 0 if there are less logs than the LOGS_DEFAULT_PAGE_SIZE to get the remaining log\n                        if offset &lt; LOGS_DEFAULT_PAGE_SIZE\n                        else offset - LOGS_DEFAULT_PAGE_SIZE\n                    )\n                else:\n                    more_logs = False\n            else:\n                if len(page_logs) == LOGS_DEFAULT_PAGE_SIZE:\n                    offset += LOGS_DEFAULT_PAGE_SIZE\n                else:\n                    # No more logs to show, exit\n                    more_logs = False\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/flow_run/#prefect.cli.flow_run.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View recent flow runs or flow runs for specific flows.</p> <p>Arguments:</p> <pre><code>flow_name: Name of the flow\n\nlimit: Maximum number of flow runs to list. Defaults to 15.\n\nstate: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.\n\nstate_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.\n</code></pre> <p>Examples:</p> <p>$ prefect flow-runs ls --state Running</p> <p>$ prefect flow-runs ls --state Running --state late</p> <p>$ prefect flow-runs ls --state-type RUNNING</p> <p>$ prefect flow-runs ls --state-type RUNNING --state-type FAILED</p> Source code in <code>prefect/cli/flow_run.py</code> <pre><code>@flow_run_app.command()\nasync def ls(\n    flow_name: List[str] = typer.Option(None, help=\"Name of the flow\"),\n    limit: int = typer.Option(15, help=\"Maximum number of flow runs to list\"),\n    state: List[str] = typer.Option(None, help=\"Name of the flow run's state\"),\n    state_type: List[str] = typer.Option(None, help=\"Type of the flow run's state\"),\n):\n    \"\"\"\n    View recent flow runs or flow runs for specific flows.\n\n    Arguments:\n\n        flow_name: Name of the flow\n\n        limit: Maximum number of flow runs to list. Defaults to 15.\n\n        state: Name of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'PAUSED', 'SUSPENDED', 'AWAITINGRETRY', 'RETRYING', and 'LATE'.\n\n        state_type: Type of the flow run's state. Can be provided multiple times. Options are 'SCHEDULED', 'PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CRASHED', 'CANCELLING', 'CANCELLED', 'CRASHED', and 'PAUSED'.\n\n    Examples:\n\n    $ prefect flow-runs ls --state Running\n\n    $ prefect flow-runs ls --state Running --state late\n\n    $ prefect flow-runs ls --state-type RUNNING\n\n    $ prefect flow-runs ls --state-type RUNNING --state-type FAILED\n    \"\"\"\n\n    # Handling `state` and `state_type` argument validity in the function instead of by specifying\n    # List[StateType] and List[StateName] in the type hints, allows users to provide\n    # case-insensitive arguments for `state` and `state_type`.\n\n    prefect_state_names = {\n        \"SCHEDULED\": \"Scheduled\",\n        \"PENDING\": \"Pending\",\n        \"RUNNING\": \"Running\",\n        \"COMPLETED\": \"Completed\",\n        \"FAILED\": \"Failed\",\n        \"CANCELLED\": \"Cancelled\",\n        \"CRASHED\": \"Crashed\",\n        \"PAUSED\": \"Paused\",\n        \"CANCELLING\": \"Cancelling\",\n        \"SUSPENDED\": \"Suspended\",\n        \"AWAITINGRETRY\": \"AwaitingRetry\",\n        \"RETRYING\": \"Retrying\",\n        \"LATE\": \"Late\",\n    }\n\n    state_filter = {}\n    formatted_states = []\n\n    if state:\n        for s in state:\n            uppercased_state = s.upper()\n            if uppercased_state in prefect_state_names:\n                capitalized_state = prefect_state_names[uppercased_state]\n                formatted_states.append(capitalized_state)\n            else:\n                # Do not change the case of the state name if it is not one of the official Prefect state names\n                formatted_states.append(s)\n                logger.warning(\n                    f\"State name {repr(s)} is not one of the official Prefect state names.\"\n                )\n\n        state_filter[\"name\"] = {\"any_\": formatted_states}\n\n    if state_type:\n        upper_cased_states = [s.upper() for s in state_type]\n        if not all(s in StateType.__members__ for s in upper_cased_states):\n            exit_with_error(\n                f\"Invalid state type. Options are {', '.join(StateType.__members__)}.\"\n            )\n\n        state_filter[\"type\"] = {\n            \"any_\": [StateType[s].value for s in upper_cased_states]\n        }\n\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_filter=FlowFilter(name={\"any_\": flow_name}) if flow_name else None,\n            flow_run_filter=FlowRunFilter(state=state_filter) if state_filter else None,\n            limit=limit,\n            sort=FlowRunSort.EXPECTED_START_TIME_DESC,\n        )\n        flows_by_id = {\n            flow.id: flow\n            for flow in await client.read_flows(\n                flow_filter=FlowFilter(id={\"any_\": [run.flow_id for run in flow_runs]})\n            )\n        }\n\n        if not flow_runs:\n            exit_with_success(\"No flow runs found.\")\n\n    table = Table(title=\"Flow Runs\")\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Flow\", style=\"blue\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"State\", no_wrap=True)\n    table.add_column(\"When\", style=\"bold\", no_wrap=True)\n\n    for flow_run in sorted(flow_runs, key=lambda d: d.created, reverse=True):\n        flow = flows_by_id[flow_run.flow_id]\n        timestamp = (\n            flow_run.state.state_details.scheduled_time\n            if flow_run.state.is_scheduled()\n            else flow_run.state.timestamp\n        )\n        table.add_row(\n            str(flow_run.id),\n            str(flow.name),\n            str(flow_run.name),\n            str(flow_run.state.type.value),\n            pendulum.instance(timestamp).diff_for_humans(),\n        )\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","flow runs"]},{"location":"api-ref/prefect/cli/kubernetes/","title":"kubernetes","text":"","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes","title":"<code>prefect.cli.kubernetes</code>","text":"<p>Command line interface for working with Prefect on Kubernetes</p>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_agent","title":"<code>manifest_agent</code>","text":"<p>Generates a manifest for deploying Agent on Kubernetes.</p> Example <p>$ prefect kubernetes manifest agent | kubectl apply -f -</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"agent\")\ndef manifest_agent(\n    api_url: str = SettingsOption(PREFECT_API_URL),\n    api_key: str = SettingsOption(PREFECT_API_KEY),\n    image_tag: str = typer.Option(\n        get_prefect_image_name(),\n        \"-i\",\n        \"--image-tag\",\n        help=\"The tag of a Docker image to use for the Agent.\",\n    ),\n    namespace: str = typer.Option(\n        \"default\",\n        \"-n\",\n        \"--namespace\",\n        help=\"A Kubernetes namespace to create agent in.\",\n    ),\n    work_queue: str = typer.Option(\n        \"kubernetes\",\n        \"-q\",\n        \"--work-queue\",\n        help=\"A work queue name for the agent to pull from.\",\n    ),\n):\n    \"\"\"\n    Generates a manifest for deploying Agent on Kubernetes.\n\n    Example:\n        $ prefect kubernetes manifest agent | kubectl apply -f -\n    \"\"\"\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-agent.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"api_url\": api_url,\n            \"api_key\": api_key,\n            \"image_name\": image_tag,\n            \"namespace\": namespace,\n            \"work_queue\": work_queue,\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_flow_run_job","title":"<code>manifest_flow_run_job</code>  <code>async</code>","text":"<p>Prints the default KubernetesJob Job manifest.</p> <p>Use this file to fully customize your <code>KubernetesJob</code> deployments.</p> <p>\b Example:     \b     $ prefect kubernetes manifest flow-run-job</p> <p>\b Output, a YAML file:     \b     apiVersion: batch/v1     kind: Job     ...</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"flow-run-job\")\nasync def manifest_flow_run_job():\n    \"\"\"\n    Prints the default KubernetesJob Job manifest.\n\n    Use this file to fully customize your `KubernetesJob` deployments.\n\n    \\b\n    Example:\n        \\b\n        $ prefect kubernetes manifest flow-run-job\n\n    \\b\n    Output, a YAML file:\n        \\b\n        apiVersion: batch/v1\n        kind: Job\n        ...\n    \"\"\"\n\n    KubernetesJob.base_job_manifest()\n\n    output = yaml.dump(KubernetesJob.base_job_manifest())\n\n    # add some commentary where appropriate\n    output = output.replace(\n        \"metadata:\\n  labels:\",\n        \"metadata:\\n  # labels are required, even if empty\\n  labels:\",\n    )\n    output = output.replace(\n        \"containers:\\n\",\n        \"containers:  # the first container is required\\n\",\n    )\n    output = output.replace(\n        \"env: []\\n\",\n        \"env: []  # env is required, even if empty\\n\",\n    )\n\n    print(output)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/kubernetes/#prefect.cli.kubernetes.manifest_server","title":"<code>manifest_server</code>","text":"<p>Generates a manifest for deploying Prefect on Kubernetes.</p> Example <p>$ prefect kubernetes manifest server | kubectl apply -f -</p> Source code in <code>prefect/cli/kubernetes.py</code> <pre><code>@manifest_app.command(\"server\")\ndef manifest_server(\n    image_tag: str = typer.Option(\n        get_prefect_image_name(),\n        \"-i\",\n        \"--image-tag\",\n        help=\"The tag of a Docker image to use for the server.\",\n    ),\n    namespace: str = typer.Option(\n        \"default\",\n        \"-n\",\n        \"--namespace\",\n        help=\"A Kubernetes namespace to create the server in.\",\n    ),\n    log_level: str = SettingsOption(PREFECT_LOGGING_SERVER_LEVEL),\n):\n    \"\"\"\n    Generates a manifest for deploying Prefect on Kubernetes.\n\n    Example:\n        $ prefect kubernetes manifest server | kubectl apply -f -\n    \"\"\"\n\n    template = Template(\n        (\n            prefect.__module_path__ / \"cli\" / \"templates\" / \"kubernetes-server.yaml\"\n        ).read_text()\n    )\n    manifest = template.substitute(\n        {\n            \"image_name\": image_tag,\n            \"namespace\": namespace,\n            \"log_level\": log_level,\n        }\n    )\n    print(manifest)\n</code></pre>","tags":["Python API","kubernetes","CLI"]},{"location":"api-ref/prefect/cli/profile/","title":"profile","text":"","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile","title":"<code>prefect.cli.profile</code>","text":"<p>Command line interface for working with profiles.</p>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.create","title":"<code>create</code>","text":"<p>Create a new profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef create(\n    name: str,\n    from_name: str = typer.Option(None, \"--from\", help=\"Copy an existing profile.\"),\n):\n    \"\"\"\n    Create a new profile.\n    \"\"\"\n\n    profiles = prefect.settings.load_profiles()\n    if name in profiles:\n        app.console.print(\n            textwrap.dedent(\n                f\"\"\"\n                [red]Profile {name!r} already exists.[/red]\n                To create a new profile, remove the existing profile first:\n\n                    prefect profile delete {name!r}\n                \"\"\"\n            ).strip()\n        )\n        raise typer.Exit(1)\n\n    if from_name:\n        if from_name not in profiles:\n            exit_with_error(f\"Profile {from_name!r} not found.\")\n\n        # Create a copy of the profile with a new name and add to the collection\n        profiles.add_profile(profiles[from_name].copy(update={\"name\": name}))\n    else:\n        profiles.add_profile(prefect.settings.Profile(name=name, settings={}))\n\n    prefect.settings.save_profiles(profiles)\n\n    app.console.print(\n        textwrap.dedent(\n            f\"\"\"\n            Created profile with properties:\n                name - {name!r}\n                from name - {from_name or None}\n\n            Use created profile for future, subsequent commands:\n                prefect profile use {name!r}\n\n            Use created profile temporarily for a single command:\n                prefect -p {name!r} config view\n            \"\"\"\n        )\n    )\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.delete","title":"<code>delete</code>","text":"<p>Delete the given profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef delete(name: str):\n    \"\"\"\n    Delete the given profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    current_profile = prefect.context.get_settings_context().profile\n    if current_profile.name == name:\n        exit_with_error(\n            f\"Profile {name!r} is the active profile. You must switch profiles before\"\n            \" it can be deleted.\"\n        )\n\n    profiles.remove_profile(name)\n\n    verb = \"Removed\"\n    if name == \"default\":\n        verb = \"Reset\"\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"{verb} profile {name!r}.\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.inspect","title":"<code>inspect</code>","text":"<p>Display settings from a given profile; defaults to active.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef inspect(\n    name: Optional[str] = typer.Argument(\n        None, help=\"Name of profile to inspect; defaults to active profile.\"\n    ),\n):\n    \"\"\"\n    Display settings from a given profile; defaults to active.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name is None:\n        current_profile = prefect.context.get_settings_context().profile\n        if not current_profile:\n            exit_with_error(\"No active profile set - please provide a name to inspect.\")\n        name = current_profile.name\n        print(f\"No name provided, defaulting to {name!r}\")\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    if not profiles[name].settings:\n        # TODO: Consider instructing on how to add settings.\n        print(f\"Profile {name!r} is empty.\")\n\n    for setting, value in profiles[name].settings.items():\n        app.console.print(f\"{setting.name}='{value}'\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.ls","title":"<code>ls</code>","text":"<p>List profile names.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef ls():\n    \"\"\"\n    List profile names.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    current_profile = prefect.context.get_settings_context().profile\n    current_name = current_profile.name if current_profile is not None else None\n\n    table = Table(caption=\"* active profile\")\n    table.add_column(\n        \"[#024dfd]Available Profiles:\", justify=\"right\", style=\"#8ea0ae\", no_wrap=True\n    )\n\n    for name in profiles:\n        if name == current_name:\n            table.add_row(f\"[green]  * {name}[/green]\")\n        else:\n            table.add_row(f\"  {name}\")\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.rename","title":"<code>rename</code>","text":"<p>Change the name of a profile.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\ndef rename(name: str, new_name: str):\n    \"\"\"\n    Change the name of a profile.\n    \"\"\"\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    if new_name in profiles:\n        exit_with_error(f\"Profile {new_name!r} already exists.\")\n\n    profiles.add_profile(profiles[name].copy(update={\"name\": new_name}))\n    profiles.remove_profile(name)\n\n    # If the active profile was renamed switch the active profile to the new name.\n    prefect.context.get_settings_context().profile\n    if profiles.active_name == name:\n        profiles.set_active(new_name)\n    if os.environ.get(\"PREFECT_PROFILE\") == name:\n        app.console.print(\n            f\"You have set your current profile to {name!r} with the \"\n            \"PREFECT_PROFILE environment variable. You must update this variable to \"\n            f\"{new_name!r} to continue using the profile.\"\n        )\n\n    prefect.settings.save_profiles(profiles)\n    exit_with_success(f\"Renamed profile {name!r} to {new_name!r}.\")\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/profile/#prefect.cli.profile.use","title":"<code>use</code>  <code>async</code>","text":"<p>Set the given profile to active.</p> Source code in <code>prefect/cli/profile.py</code> <pre><code>@profile_app.command()\nasync def use(name: str):\n    \"\"\"\n    Set the given profile to active.\n    \"\"\"\n    status_messages = {\n        ConnectionStatus.CLOUD_CONNECTED: (\n            exit_with_success,\n            f\"Connected to Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.CLOUD_ERROR: (\n            exit_with_error,\n            f\"Error connecting to Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.CLOUD_UNAUTHORIZED: (\n            exit_with_error,\n            f\"Error authenticating with Prefect Cloud using profile {name!r}\",\n        ),\n        ConnectionStatus.ORION_CONNECTED: (\n            exit_with_success,\n            f\"Connected to Prefect server using profile {name!r}\",\n        ),\n        ConnectionStatus.ORION_ERROR: (\n            exit_with_error,\n            f\"Error connecting to Prefect server using profile {name!r}\",\n        ),\n        ConnectionStatus.EPHEMERAL: (\n            exit_with_success,\n            (\n                f\"No Prefect server specified using profile {name!r} - the API will run\"\n                \" in ephemeral mode.\"\n            ),\n        ),\n        ConnectionStatus.INVALID_API: (\n            exit_with_error,\n            \"Error connecting to Prefect API URL\",\n        ),\n    }\n\n    profiles = prefect.settings.load_profiles()\n    if name not in profiles.names:\n        exit_with_error(f\"Profile {name!r} not found.\")\n\n    profiles.set_active(name)\n    prefect.settings.save_profiles(profiles)\n\n    with Progress(\n        SpinnerColumn(),\n        TextColumn(\"[progress.description]{task.description}\"),\n        transient=False,\n    ) as progress:\n        progress.add_task(\n            description=\"Checking API connectivity...\",\n            total=None,\n        )\n\n        with use_profile(name, include_current_context=False):\n            connection_status = await check_orion_connection()\n\n        exit_method, msg = status_messages[connection_status]\n\n    exit_method(msg)\n</code></pre>","tags":["Python API","CLI","settings","configuration","profiles"]},{"location":"api-ref/prefect/cli/root/","title":"root","text":"","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/root/#prefect.cli.root","title":"<code>prefect.cli.root</code>","text":"<p>Base <code>prefect</code> command-line application</p>","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/root/#prefect.cli.root.version","title":"<code>version</code>  <code>async</code>","text":"<p>Get the current Prefect version.</p> Source code in <code>prefect/cli/root.py</code> <pre><code>@app.command()\nasync def version():\n    \"\"\"Get the current Prefect version.\"\"\"\n    import sqlite3\n\n    from prefect.server.utilities.database import get_dialect\n    from prefect.settings import PREFECT_API_DATABASE_CONNECTION_URL\n\n    version_info = {\n        \"Version\": prefect.__version__,\n        \"API version\": SERVER_API_VERSION,\n        \"Python version\": platform.python_version(),\n        \"Git commit\": prefect.__version_info__[\"full-revisionid\"][:8],\n        \"Built\": pendulum.parse(\n            prefect.__version_info__[\"date\"]\n        ).to_day_datetime_string(),\n        \"OS/Arch\": f\"{sys.platform}/{platform.machine()}\",\n        \"Profile\": prefect.context.get_settings_context().profile.name,\n    }\n\n    server_type: str\n\n    try:\n        # We do not context manage the client because when using an ephemeral app we do not\n        # want to create the database or run migrations\n        client = prefect.get_client()\n        server_type = client.server_type.value\n    except Exception:\n        server_type = \"&lt;client error&gt;\"\n\n    version_info[\"Server type\"] = server_type.lower()\n\n    # TODO: Consider adding an API route to retrieve this information?\n    if server_type == ServerType.EPHEMERAL.value:\n        database = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value()).name\n        version_info[\"Server\"] = {\"Database\": database}\n        if database == \"sqlite\":\n            version_info[\"Server\"][\"SQLite version\"] = sqlite3.sqlite_version\n\n    def display(object: dict, nesting: int = 0):\n        # Recursive display of a dictionary with nesting\n        for key, value in object.items():\n            key += \":\"\n            if isinstance(value, dict):\n                app.console.print(key)\n                return display(value, nesting + 2)\n            prefix = \" \" * nesting\n            app.console.print(f\"{prefix}{key.ljust(20 - len(prefix))} {value}\")\n\n    display(version_info)\n</code></pre>","tags":["Python API","CLI"]},{"location":"api-ref/prefect/cli/server/","title":"server","text":"","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server","title":"<code>prefect.cli.server</code>","text":"<p>Command line interface for working with Prefect</p>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.downgrade","title":"<code>downgrade</code>  <code>async</code>","text":"<p>Downgrade the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def downgrade(\n    yes: bool = typer.Option(False, \"--yes\", \"-y\"),\n    revision: str = typer.Option(\n        \"-1\",\n        \"-r\",\n        help=(\n            \"The revision to pass to `alembic downgrade`. If not provided, \"\n            \"downgrades to the most recent revision. Use 'base' to run all \"\n            \"migrations.\"\n        ),\n    ),\n    dry_run: bool = typer.Option(\n        False,\n        help=(\n            \"Flag to show what migrations would be made without applying them. Will\"\n            \" emit sql statements to stdout.\"\n        ),\n    ),\n):\n    \"\"\"Downgrade the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_downgrade\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n\n    engine = await db.engine()\n\n    if not yes:\n        confirm = typer.confirm(\n            \"Are you sure you want to downgrade the Prefect \"\n            f\"database at {engine.url!r}?\"\n        )\n        if not confirm:\n            exit_with_error(\"Database downgrade aborted!\")\n\n    app.console.print(\"Running downgrade migrations ...\")\n    await run_sync_in_worker_thread(\n        alembic_downgrade, revision=revision, dry_run=dry_run\n    )\n    app.console.print(\"Migrations succeeded!\")\n    exit_with_success(f\"Prefect database at {engine.url!r} downgraded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.reset","title":"<code>reset</code>  <code>async</code>","text":"<p>Drop and recreate all Prefect database tables</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def reset(yes: bool = typer.Option(False, \"--yes\", \"-y\")):\n    \"\"\"Drop and recreate all Prefect database tables\"\"\"\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n    engine = await db.engine()\n    if not yes:\n        confirm = typer.confirm(\n            \"Are you sure you want to reset the Prefect database located \"\n            f'at \"{engine.url!r}\"? This will drop and recreate all tables.'\n        )\n        if not confirm:\n            exit_with_error(\"Database reset aborted\")\n    app.console.print(\"Downgrading database...\")\n    await db.drop_db()\n    app.console.print(\"Upgrading database...\")\n    await db.create_db()\n    exit_with_success(f'Prefect database \"{engine.url!r}\" reset!')\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.revision","title":"<code>revision</code>  <code>async</code>","text":"<p>Create a new migration for the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def revision(\n    message: str = typer.Option(\n        None,\n        \"--message\",\n        \"-m\",\n        help=\"A message to describe the migration.\",\n    ),\n    autogenerate: bool = False,\n):\n    \"\"\"Create a new migration for the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_revision\n\n    app.console.print(\"Running migration file creation ...\")\n    await run_sync_in_worker_thread(\n        alembic_revision,\n        message=message,\n        autogenerate=autogenerate,\n    )\n    exit_with_success(\"Creating new migration file succeeded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.stamp","title":"<code>stamp</code>  <code>async</code>","text":"<p>Stamp the revision table with the given revision; don't run any migrations</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def stamp(revision: str):\n    \"\"\"Stamp the revision table with the given revision; don't run any migrations\"\"\"\n    from prefect.server.database.alembic_commands import alembic_stamp\n\n    app.console.print(\"Stamping database with revision ...\")\n    await run_sync_in_worker_thread(alembic_stamp, revision=revision)\n    exit_with_success(\"Stamping database with revision succeeded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start a Prefect server instance</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@server_app.command()\nasync def start(\n    host: str = SettingsOption(PREFECT_SERVER_API_HOST),\n    port: int = SettingsOption(PREFECT_SERVER_API_PORT),\n    keep_alive_timeout: int = SettingsOption(PREFECT_SERVER_API_KEEPALIVE_TIMEOUT),\n    log_level: str = SettingsOption(PREFECT_LOGGING_SERVER_LEVEL),\n    scheduler: bool = SettingsOption(PREFECT_API_SERVICES_SCHEDULER_ENABLED),\n    analytics: bool = SettingsOption(\n        PREFECT_SERVER_ANALYTICS_ENABLED, \"--analytics-on/--analytics-off\"\n    ),\n    late_runs: bool = SettingsOption(PREFECT_API_SERVICES_LATE_RUNS_ENABLED),\n    ui: bool = SettingsOption(PREFECT_UI_ENABLED),\n    background: bool = typer.Option(\n        False, \"--background\", \"-b\", help=\"Run the server in the background\"\n    ),\n):\n    \"\"\"\n    Start a Prefect server instance\n    \"\"\"\n\n    server_env = os.environ.copy()\n    server_env[\"PREFECT_API_SERVICES_SCHEDULER_ENABLED\"] = str(scheduler)\n    server_env[\"PREFECT_SERVER_ANALYTICS_ENABLED\"] = str(analytics)\n    server_env[\"PREFECT_API_SERVICES_LATE_RUNS_ENABLED\"] = str(late_runs)\n    server_env[\"PREFECT_API_SERVICES_UI\"] = str(ui)\n    server_env[\"PREFECT_UI_ENABLED\"] = str(ui)\n    server_env[\"PREFECT_LOGGING_SERVER_LEVEL\"] = log_level\n\n    base_url = f\"http://{host}:{port}\"\n\n    pid_file = anyio.Path(PREFECT_HOME.value() / PID_FILE)\n    # check if port is already in use\n    try:\n        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n            s.bind((host, port))\n    except socket.error:\n        if await pid_file.exists():\n            exit_with_error(\n                f\"A background server process is already running on port {port}. \"\n                \"Run `prefect server stop` to stop it or specify a different port \"\n                \"with the `--port` flag.\"\n            )\n        exit_with_error(\n            f\"Port {port} is already in use. Please specify a different port with the \"\n            \"`--port` flag.\"\n        )\n\n    # check if server is already running in the background\n    if background:\n        try:\n            await pid_file.touch(mode=0o600, exist_ok=False)\n        except FileExistsError:\n            exit_with_error(\n                \"A server is already running in the background. To stop it,\"\n                \" run `prefect server stop`.\"\n            )\n\n    app.console.print(generate_welcome_blurb(base_url, ui_enabled=ui))\n    app.console.print(\"\\n\")\n\n    try:\n        command = [\n            sys.executable,\n            \"-m\",\n            \"uvicorn\",\n            \"--app-dir\",\n            str(prefect.__module_path__.parent),\n            \"--factory\",\n            \"prefect.server.api.server:create_app\",\n            \"--host\",\n            str(host),\n            \"--port\",\n            str(port),\n            \"--timeout-keep-alive\",\n            str(keep_alive_timeout),\n        ]\n        logger.debug(\"Opening server process with command: %s\", shlex.join(command))\n        process = await anyio.open_process(\n            command=command,\n            env=server_env,\n        )\n\n        process_id = process.pid\n        if background:\n            await pid_file.write_text(str(process_id))\n\n            app.console.print(\n                \"The Prefect server is running in the background. Run `prefect\"\n                \" server stop` to stop it.\"\n            )\n            return\n\n        async with process:\n            # Explicitly handle the interrupt signal here, as it will allow us to\n            # cleanly stop the uvicorn server. Failing to do that may cause a\n            # large amount of anyio error traces on the terminal, because the\n            # SIGINT is handled by Typer/Click in this process (the parent process)\n            # and will start shutting down subprocesses:\n            # https://github.com/PrefectHQ/server/issues/2475\n\n            setup_signal_handlers_server(\n                process_id, \"the Prefect server\", app.console.print\n            )\n\n            await consume_process_output(process, sys.stdout, sys.stderr)\n\n    except anyio.EndOfStream:\n        logging.error(\"Subprocess stream ended unexpectedly\")\n    except Exception as e:\n        logging.error(f\"An error occurred: {str(e)}\")\n\n    app.console.print(\"Server stopped!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Stop a Prefect server instance running in the background</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@server_app.command()\nasync def stop():\n    \"\"\"Stop a Prefect server instance running in the background\"\"\"\n    pid_file = anyio.Path(PREFECT_HOME.value() / PID_FILE)\n    if not await pid_file.exists():\n        exit_with_success(\"No server running in the background.\")\n    pid = int(await pid_file.read_text())\n    try:\n        os.kill(pid, 15)\n    except ProcessLookupError:\n        exit_with_success(\n            \"The server process is not running. Cleaning up stale PID file.\"\n        )\n    finally:\n        # The file probably exists, but use `missing_ok` to avoid an\n        # error if the file was deleted by another actor\n        await pid_file.unlink(missing_ok=True)\n    app.console.print(\"Server stopped!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/server/#prefect.cli.server.upgrade","title":"<code>upgrade</code>  <code>async</code>","text":"<p>Upgrade the Prefect database</p> Source code in <code>prefect/cli/server.py</code> <pre><code>@database_app.command()\nasync def upgrade(\n    yes: bool = typer.Option(False, \"--yes\", \"-y\"),\n    revision: str = typer.Option(\n        \"head\",\n        \"-r\",\n        help=(\n            \"The revision to pass to `alembic upgrade`. If not provided, runs all\"\n            \" migrations.\"\n        ),\n    ),\n    dry_run: bool = typer.Option(\n        False,\n        help=(\n            \"Flag to show what migrations would be made without applying them. Will\"\n            \" emit sql statements to stdout.\"\n        ),\n    ),\n):\n    \"\"\"Upgrade the Prefect database\"\"\"\n    from prefect.server.database.alembic_commands import alembic_upgrade\n    from prefect.server.database.dependencies import provide_database_interface\n\n    db = provide_database_interface()\n    engine = await db.engine()\n\n    if not yes:\n        confirm = typer.confirm(\n            f\"Are you sure you want to upgrade the Prefect database at {engine.url!r}?\"\n        )\n        if not confirm:\n            exit_with_error(\"Database upgrade aborted!\")\n\n    app.console.print(\"Running upgrade migrations ...\")\n    await run_sync_in_worker_thread(alembic_upgrade, revision=revision, dry_run=dry_run)\n    app.console.print(\"Migrations succeeded!\")\n    exit_with_success(f\"Prefect database at {engine.url!r} upgraded!\")\n</code></pre>","tags":["Python API","CLI","Kubernetes","database"]},{"location":"api-ref/prefect/cli/shell/","title":"shell","text":"","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell","title":"<code>prefect.cli.shell</code>","text":"<p>Provides a set of tools for executing shell commands as Prefect flows. Includes functionalities for running shell commands ad-hoc or serving them as Prefect flows, with options for logging output, scheduling, and deployment customization.</p>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.output_collect","title":"<code>output_collect</code>","text":"<p>Collects output from a subprocess pipe and stores it in a container list.</p> <p>Parameters:</p> Name Type Description Default <code>pipe</code> <p>The output pipe of the subprocess, either stdout or stderr.</p> required <code>container</code> <p>A list to store the collected output lines.</p> required Source code in <code>prefect/cli/shell.py</code> <pre><code>def output_collect(pipe, container):\n    \"\"\"\n    Collects output from a subprocess pipe and stores it in a container list.\n\n    Args:\n        pipe: The output pipe of the subprocess, either stdout or stderr.\n        container: A list to store the collected output lines.\n    \"\"\"\n    for line in iter(pipe.readline, \"\"):\n        container.append(line)\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.output_stream","title":"<code>output_stream</code>","text":"<p>Read from a pipe line by line and log using the provided logging function.</p> <p>Parameters:</p> Name Type Description Default <code>pipe</code> <code>IO</code> <p>A file-like object for reading process output.</p> required <code>logger_function</code> <code>function</code> <p>A logging function from the logger.</p> required Source code in <code>prefect/cli/shell.py</code> <pre><code>def output_stream(pipe, logger_function):\n    \"\"\"\n    Read from a pipe line by line and log using the provided logging function.\n\n    Args:\n        pipe (IO): A file-like object for reading process output.\n        logger_function (function): A logging function from the logger.\n    \"\"\"\n    with pipe:\n        for line in iter(pipe.readline, \"\"):\n            logger_function(line.strip())\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.run_shell_process","title":"<code>run_shell_process</code>","text":"<p>Asynchronously executes the specified shell command and logs its output.</p> <p>This function is designed to be used within Prefect flows to run shell commands as part of task execution. It handles both the execution of the command and the collection of its output for logging purposes.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command to execute.</p> required <code>log_output</code> <code>bool</code> <p>If True, the output of the command (both stdout and stderr) is logged to Prefect.                          Defaults to True</p> <code>True</code> <code>stream_stdout</code> <code>bool</code> <p>If True, the stdout of the command is streamed to Prefect logs. Defaults to False.</p> <code>False</code> <code>log_stderr</code> <code>bool</code> <p>If True, the stderr of the command is logged to Prefect logs. Defaults to False.</p> <code>False</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@flow\ndef run_shell_process(\n    command: str,\n    log_output: bool = True,\n    stream_stdout: bool = False,\n    log_stderr: bool = False,\n):\n    \"\"\"\n    Asynchronously executes the specified shell command and logs its output.\n\n    This function is designed to be used within Prefect flows to run shell commands as part of task execution.\n    It handles both the execution of the command and the collection of its output for logging purposes.\n\n    Args:\n        command (str): The shell command to execute.\n        log_output (bool, optional): If True, the output of the command (both stdout and stderr) is logged to Prefect.\n                                     Defaults to True\n        stream_stdout (bool, optional): If True, the stdout of the command is streamed to Prefect logs. Defaults to False.\n        log_stderr (bool, optional): If True, the stderr of the command is logged to Prefect logs. Defaults to False.\n\n\n    \"\"\"\n\n    logger = get_run_logger() if log_output else logging.getLogger(\"prefect\")\n\n    # Containers for log batching\n    stdout_container, stderr_container = [], []\n    with subprocess.Popen(\n        command,\n        stdout=subprocess.PIPE,\n        stderr=subprocess.PIPE,\n        shell=True,\n        text=True,\n        bufsize=1,\n        universal_newlines=True,\n    ) as proc:\n        # Create threads for collecting stdout and stderr\n        if stream_stdout:\n            stdout_logger = logger.info\n            output = output_stream\n        else:\n            stdout_logger = stdout_container\n            output = output_collect\n\n        stdout_thread = threading.Thread(\n            target=output, args=(proc.stdout, stdout_logger)\n        )\n\n        stderr_thread = threading.Thread(\n            target=output_collect, args=(proc.stderr, stderr_container)\n        )\n\n        stdout_thread.start()\n        stderr_thread.start()\n\n        stdout_thread.join()\n        stderr_thread.join()\n\n        proc.wait()\n        if stdout_container:\n            logger.info(\"\".join(stdout_container).strip())\n\n        if stderr_container and log_stderr:\n            logger.error(\"\".join(stderr_container).strip())\n            # Suppress traceback\n        if proc.returncode != 0:\n            logger.error(\"\".join(stderr_container).strip())\n            sys.tracebacklimit = 0\n            raise FailedRun(f\"Command failed with exit code {proc.returncode}\")\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.serve","title":"<code>serve</code>  <code>async</code>","text":"<p>Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.</p> <p>This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs, setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command the flow will execute.</p> required <code>name</code> <code>str</code> <p>The name assigned to the flow. This is required..</p> required <code>deployment_tags</code> <code>List[str]</code> <p>Optional tags for the deployment to facilitate filtering and organization.</p> <code>Option(None, '--tag', help='Tag for the deployment (can be provided multiple times)')</code> <code>log_output</code> <code>bool</code> <p>If True, streams the output of the shell command to the Prefect logs. Defaults to True.</p> <code>Option(True, help='Stream the output of the command', hidden=True)</code> <code>cron_schedule</code> <code>str</code> <p>A cron expression that defines when the flow will run. If not provided, the flow can be triggered manually.</p> <code>Option(None, help='Cron schedule for the flow')</code> <code>timezone</code> <code>str</code> <p>The timezone for the cron schedule. This is important if the schedule should align with local time.</p> <code>Option(None, help='Timezone for the schedule')</code> <code>concurrency_limit</code> <code>int</code> <p>The maximum number of instances of the flow that can run simultaneously.</p> <code>Option(None, min=1, help='The maximum number of flow runs that can execute at the same time')</code> <code>deployment_name</code> <code>str</code> <p>The name of the deployment. This helps distinguish deployments within the Prefect platform.</p> <code>Option('CLI Runner Deployment', help='Name of the deployment')</code> <code>run_once</code> <code>bool</code> <p>When True, the flow will only run once upon deployment initiation, rather than continuously.</p> <code>Option(False, help='Run the agent loop once, instead of forever.')</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@shell_app.command(\"serve\")\nasync def serve(\n    command: str,\n    flow_name: str = typer.Option(..., help=\"Name of the flow\"),\n    deployment_name: str = typer.Option(\n        \"CLI Runner Deployment\", help=\"Name of the deployment\"\n    ),\n    deployment_tags: List[str] = typer.Option(\n        None, \"--tag\", help=\"Tag for the deployment (can be provided multiple times)\"\n    ),\n    log_output: bool = typer.Option(\n        True, help=\"Stream the output of the command\", hidden=True\n    ),\n    stream_stdout: bool = typer.Option(True, help=\"Stream the output of the command\"),\n    cron_schedule: str = typer.Option(None, help=\"Cron schedule for the flow\"),\n    timezone: str = typer.Option(None, help=\"Timezone for the schedule\"),\n    concurrency_limit: int = typer.Option(\n        None,\n        min=1,\n        help=\"The maximum number of flow runs that can execute at the same time\",\n    ),\n    run_once: bool = typer.Option(\n        False, help=\"Run the agent loop once, instead of forever.\"\n    ),\n):\n    \"\"\"\n    Creates and serves a Prefect deployment that runs a specified shell command according to a cron schedule or ad hoc.\n\n    This function allows users to integrate shell command execution into Prefect workflows seamlessly. It provides options for\n    scheduled execution via cron expressions, flow and deployment naming for better management, and the application of tags for\n    easier categorization and filtering within the Prefect UI. Additionally, it supports streaming command output to Prefect logs,\n    setting concurrency limits to control flow execution, and optionally running the deployment once for ad-hoc tasks.\n\n    Args:\n        command (str): The shell command the flow will execute.\n        name (str): The name assigned to the flow. This is required..\n        deployment_tags (List[str], optional): Optional tags for the deployment to facilitate filtering and organization.\n        log_output (bool, optional): If True, streams the output of the shell command to the Prefect logs. Defaults to True.\n        cron_schedule (str, optional): A cron expression that defines when the flow will run. If not provided, the flow can be triggered manually.\n        timezone (str, optional): The timezone for the cron schedule. This is important if the schedule should align with local time.\n        concurrency_limit (int, optional): The maximum number of instances of the flow that can run simultaneously.\n        deployment_name (str, optional): The name of the deployment. This helps distinguish deployments within the Prefect platform.\n        run_once (bool, optional): When True, the flow will only run once upon deployment initiation, rather than continuously.\n    \"\"\"\n    schedule = (\n        CronSchedule(cron=cron_schedule, timezone=timezone) if cron_schedule else None\n    )\n    defined_flow = run_shell_process.with_options(name=flow_name)\n\n    runner_deployment = await defined_flow.to_deployment(\n        name=deployment_name,\n        parameters={\n            \"command\": command,\n            \"log_output\": log_output,\n            \"stream_stdout\": stream_stdout,\n        },\n        entrypoint_type=EntrypointType.MODULE_PATH,\n        schedule=schedule,\n        tags=(deployment_tags or []) + [\"shell\"],\n    )\n\n    runner = Runner(name=flow_name)\n    deployment_id = await runner.add_deployment(runner_deployment)\n    help_message = (\n        f\"[green]Your flow {runner_deployment.flow_name!r} is being served and polling\"\n        \" for scheduled runs!\\n[/]\\nTo trigger a run for this flow, use the following\"\n        \" command:\\n[blue]\\n\\t$ prefect deployment run\"\n        f\" '{runner_deployment.flow_name}/{deployment_name}'\\n[/]\"\n    )\n    if PREFECT_UI_URL:\n        help_message += (\n            \"\\nYou can also run your flow via the Prefect UI:\"\n            f\" [blue]{PREFECT_UI_URL.value()}/deployments/deployment/{deployment_id}[/]\\n\"\n        )\n\n    app.console.print(help_message, soft_wrap=True)\n    await runner.start(run_once=run_once)\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/shell/#prefect.cli.shell.watch","title":"<code>watch</code>  <code>async</code>","text":"<p>Executes a shell command and observes it as Prefect flow.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The shell command to be executed.</p> required <code>log_output</code> <code>bool</code> <p>If True, logs the command's output. Defaults to True.</p> <code>Option(True, help='Log the output of the command to Prefect logs.')</code> <code>flow_run_name</code> <code>str</code> <p>An optional name for the flow run.</p> <code>Option(None, help='Name of the flow run.')</code> <code>flow_name</code> <code>str</code> <p>An optional name for the flow. Useful for identification in the Prefect UI.</p> <code>Option('Shell Command', help='Name of the flow.')</code> <code>tag</code> <code>List[str]</code> <p>An optional list of tags for categorizing and filtering flows in the Prefect UI.</p> <code>None</code> Source code in <code>prefect/cli/shell.py</code> <pre><code>@shell_app.command(\"watch\")\nasync def watch(\n    command: str,\n    log_output: bool = typer.Option(\n        True, help=\"Log the output of the command to Prefect logs.\"\n    ),\n    flow_run_name: str = typer.Option(None, help=\"Name of the flow run.\"),\n    flow_name: str = typer.Option(\"Shell Command\", help=\"Name of the flow.\"),\n    stream_stdout: bool = typer.Option(True, help=\"Stream the output of the command.\"),\n    tag: Annotated[\n        Optional[List[str]], typer.Option(help=\"Optional tags for the flow run.\")\n    ] = None,\n):\n    \"\"\"\n    Executes a shell command and observes it as Prefect flow.\n\n    Args:\n        command (str): The shell command to be executed.\n        log_output (bool, optional): If True, logs the command's output. Defaults to True.\n        flow_run_name (str, optional): An optional name for the flow run.\n        flow_name (str, optional): An optional name for the flow. Useful for identification in the Prefect UI.\n        tag (List[str], optional): An optional list of tags for categorizing and filtering flows in the Prefect UI.\n    \"\"\"\n    tag = (tag or []) + [\"shell\"]\n\n    # Call the shell_run_command flow with provided arguments\n    defined_flow = run_shell_process.with_options(\n        name=flow_name, flow_run_name=flow_run_name\n    )\n    with tags(*tag):\n        defined_flow(\n            command=command, log_output=log_output, stream_stdout=stream_stdout\n        )\n</code></pre>","tags":["Python API","CLI","shell","command line","terminal"]},{"location":"api-ref/prefect/cli/variable/","title":"variable","text":"","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable","title":"<code>prefect.cli.variable</code>","text":"","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a variable.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the variable to delete</p> required Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"delete\")\nasync def delete(\n    name: str,\n):\n    \"\"\"\n    Delete a variable.\n\n    Arguments:\n        name: the name of the variable to delete\n    \"\"\"\n\n    async with get_client() as client:\n        try:\n            await client.delete_variable_by_name(\n                name=name,\n            )\n        except ObjectNotFound:\n            exit_with_error(f\"Variable {name!r} not found.\")\n\n        exit_with_success(f\"Deleted variable {name!r}.\")\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>View details about a variable.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the variable to inspect</p> required Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"inspect\")\nasync def inspect(\n    name: str,\n):\n    \"\"\"\n    View details about a variable.\n\n    Arguments:\n        name: the name of the variable to inspect\n    \"\"\"\n\n    async with get_client() as client:\n        variable = await client.read_variable_by_name(\n            name=name,\n        )\n        if not variable:\n            exit_with_error(f\"Variable {name!r} not found.\")\n\n        app.console.print(Pretty(variable))\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/variable/#prefect.cli.variable.list_variables","title":"<code>list_variables</code>  <code>async</code>","text":"<p>List variables.</p> Source code in <code>prefect/cli/variable.py</code> <pre><code>@variable_app.command(\"ls\")\nasync def list_variables(\n    limit: int = typer.Option(\n        100,\n        \"--limit\",\n        help=\"The maximum number of variables to return.\",\n    ),\n):\n    \"\"\"\n    List variables.\n    \"\"\"\n    async with get_client() as client:\n        variables = await client.read_variables(\n            limit=limit,\n        )\n\n        table = Table(\n            title=\"Variables\",\n            caption=\"List Variables using `prefect variable ls`\",\n            show_header=True,\n        )\n\n        table.add_column(\"Name\", style=\"blue\", no_wrap=True)\n        # values can be up 5000 characters so truncate early\n        table.add_column(\"Value\", style=\"blue\", no_wrap=True, max_width=50)\n        table.add_column(\"Created\", style=\"blue\", no_wrap=True)\n        table.add_column(\"Updated\", style=\"blue\", no_wrap=True)\n\n        for variable in sorted(variables, key=lambda x: f\"{x.name}\"):\n            table.add_row(\n                variable.name,\n                variable.value,\n                pendulum.instance(variable.created).diff_for_humans(),\n                pendulum.instance(variable.updated).diff_for_humans(),\n            )\n\n        app.console.print(table)\n</code></pre>","tags":["Python API","variables","CLI"]},{"location":"api-ref/prefect/cli/work_pool/","title":"work_pool","text":"","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool","title":"<code>prefect.cli.work_pool</code>","text":"<p>Command line interface for working with work queues.</p>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.clear_concurrency_limit","title":"<code>clear_concurrency_limit</code>  <code>async</code>","text":"<p>Clear the concurrency limit for a work pool.</p> <p>\b Examples:     $ prefect work-pool clear-concurrency-limit \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def clear_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n):\n    \"\"\"\n    Clear the concurrency limit for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool clear-concurrency-limit \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    concurrency_limit=None,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Cleared concurrency limit for work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a new work pool or update an existing one.</p> <p>\b Examples:     \b     Create a Kubernetes work pool in a paused state:         \b         $ prefect work-pool create \"my-pool\" --type kubernetes --paused     \b     Create a Docker work pool with a custom base job template:         \b         $ prefect work-pool create \"my-pool\" --type docker --base-job-template ./base-job-template.json     \b     Update an existing work pool:         \b         $ prefect work-pool create \"existing-pool\" --base-job-template ./base-job-template.json --overwrite</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def create(\n    name: str = typer.Argument(..., help=\"The name of the work pool.\"),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type.\"\n        ),\n    ),\n    paused: bool = typer.Option(\n        False,\n        \"--paused\",\n        help=\"Whether or not to create the work pool in a paused state.\",\n    ),\n    type: str = typer.Option(\n        None, \"-t\", \"--type\", help=\"The type of work pool to create.\"\n    ),\n    set_as_default: bool = typer.Option(\n        False,\n        \"--set-as-default\",\n        help=(\n            \"Whether or not to use the created work pool as the local default for\"\n            \" deployment.\"\n        ),\n    ),\n    provision_infrastructure: bool = typer.Option(\n        False,\n        \"--provision-infrastructure\",\n        \"--provision-infra\",\n        help=(\n            \"Whether or not to provision infrastructure for the work pool if supported\"\n            \" for the given work pool type.\"\n        ),\n    ),\n    overwrite: bool = typer.Option(\n        False,\n        \"--overwrite\",\n        help=(\"Whether or not to overwrite an existing work pool with the same name.\"),\n    ),\n):\n    \"\"\"\n    Create a new work pool or update an existing one.\n\n    \\b\n    Examples:\n        \\b\n        Create a Kubernetes work pool in a paused state:\n            \\b\n            $ prefect work-pool create \"my-pool\" --type kubernetes --paused\n        \\b\n        Create a Docker work pool with a custom base job template:\n            \\b\n            $ prefect work-pool create \"my-pool\" --type docker --base-job-template ./base-job-template.json\n        \\b\n        Update an existing work pool:\n            \\b\n            $ prefect work-pool create \"existing-pool\" --base-job-template ./base-job-template.json --overwrite\n\n    \"\"\"\n    if not name.lower().strip(\"'\\\" \"):\n        exit_with_error(\"Work pool name cannot be empty.\")\n    async with get_client() as client:\n        try:\n            existing_pool = await client.read_work_pool(work_pool_name=name)\n            if not overwrite:\n                exit_with_error(\n                    f\"Work pool named {name!r} already exists. Use --overwrite to update it.\"\n                )\n        except ObjectNotFound:\n            existing_pool = None\n\n        if type is None and existing_pool is None:\n            async with get_collections_metadata_client() as collections_client:\n                if not is_interactive():\n                    exit_with_error(\n                        \"When not using an interactive terminal, you must supply a\"\n                        \" `--type` value.\"\n                    )\n                worker_metadata = await collections_client.read_worker_metadata()\n\n                # Retrieve only push pools if provisioning infrastructure\n                data = [\n                    worker\n                    for collection in worker_metadata.values()\n                    for worker in collection.values()\n                    if provision_infrastructure\n                    and has_provisioner_for_type(worker[\"type\"])\n                    or not provision_infrastructure\n                ]\n                worker = prompt_select_from_table(\n                    app.console,\n                    \"What type of work pool infrastructure would you like to use?\",\n                    columns=[\n                        {\"header\": \"Infrastructure Type\", \"key\": \"display_name\"},\n                        {\"header\": \"Description\", \"key\": \"description\"},\n                    ],\n                    data=data,\n                    table_kwargs={\"show_lines\": True},\n                )\n                type = worker[\"type\"]\n        elif existing_pool:\n            type = existing_pool.type\n\n        available_work_pool_types = await get_available_work_pool_types()\n        if type not in available_work_pool_types:\n            exit_with_error(\n                f\"Unknown work pool type {type!r}. \"\n                \"Please choose from\"\n                f\" {', '.join(available_work_pool_types)}.\"\n            )\n\n        if base_job_template is None:\n            template_contents = (\n                await get_default_base_job_template_for_infrastructure_type(type)\n            )\n        else:\n            template_contents = json.load(base_job_template)\n\n        if provision_infrastructure:\n            try:\n                provisioner = get_infrastructure_provisioner_for_work_pool_type(type)\n                provisioner.console = app.console\n                template_contents = await provisioner.provision(\n                    work_pool_name=name, base_job_template=template_contents\n                )\n            except ValueError as exc:\n                print(exc)\n                app.console.print(\n                    (\n                        \"Automatic infrastructure provisioning is not supported for\"\n                        f\" {type!r} work pools.\"\n                    ),\n                    style=\"yellow\",\n                )\n            except RuntimeError as exc:\n                exit_with_error(f\"Failed to provision infrastructure: {exc}\")\n\n        try:\n            wp = WorkPoolCreate(\n                name=name,\n                type=type,\n                base_job_template=template_contents,\n                is_paused=paused,\n            )\n            work_pool = await client.create_work_pool(work_pool=wp, overwrite=overwrite)\n            action = \"Updated\" if overwrite and existing_pool else \"Created\"\n            app.console.print(\n                f\"{action} work pool {work_pool.name!r}!\\n\", style=\"green\"\n            )\n            if (\n                not work_pool.is_paused\n                and not work_pool.is_managed_pool\n                and not work_pool.is_push_pool\n            ):\n                app.console.print(\"To start a worker for this work pool, run:\\n\")\n                app.console.print(\n                    f\"\\t[blue]prefect worker start --pool {work_pool.name}[/]\\n\"\n                )\n            if set_as_default:\n                set_work_pool_as_default(work_pool.name)\n\n            url = (\n                f\"{PREFECT_UI_URL.value()}/work-pools/work-pool/{work_pool.name}\"\n                if PREFECT_UI_URL\n                else None\n            )\n            pool_url = url if url else \"&lt;no dashboard available&gt;\"\n\n            app.console.print(\n                textwrap.dedent(\n                    f\"\"\"\n                \u2514\u2500\u2500 UUID: {work_pool.id}\n                \u2514\u2500\u2500 Type: {work_pool.type}\n                \u2514\u2500\u2500 Description: {work_pool.description}\n                {\"\u2514\u2500\u2500 Status: \" + work_pool.status.display_name if work_pool.status else \"\"}\n                \u2514\u2500\u2500 URL: {pool_url}\n                \"\"\"\n                ).strip(),\n                soft_wrap=True,\n            )\n            exit_with_success(\"\")\n        except ObjectAlreadyExists:\n            exit_with_error(\n                f\"Work pool named {name!r} already exists. Please use --overwrite to update it.\"\n            )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a work pool.</p> <p>\b Examples:     $ prefect work-pool delete \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def delete(\n    name: str = typer.Argument(..., help=\"The name of the work pool to delete.\"),\n):\n    \"\"\"\n    Delete a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool delete \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.delete_work_pool(work_pool_name=name)\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Deleted work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.get_default_base_job_template","title":"<code>get_default_base_job_template</code>  <code>async</code>","text":"<p>Get the default base job template for a given work pool type.</p> <p>\b Examples:     $ prefect work-pool get-default-base-job-template --type kubernetes</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def get_default_base_job_template(\n    type: str = typer.Option(\n        None,\n        \"-t\",\n        \"--type\",\n        help=\"The type of work pool for which to get the default base job template.\",\n    ),\n    file: str = typer.Option(\n        None, \"-f\", \"--file\", help=\"If set, write the output to a file.\"\n    ),\n):\n    \"\"\"\n    Get the default base job template for a given work pool type.\n\n    \\b\n    Examples:\n        $ prefect work-pool get-default-base-job-template --type kubernetes\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        type\n    )\n    if base_job_template is None:\n        exit_with_error(\n            f\"Unknown work pool type {type!r}. \"\n            \"Please choose from\"\n            f\" {', '.join(await get_available_work_pool_types())}.\"\n        )\n\n    if file is None:\n        print(json.dumps(base_job_template, indent=2))\n    else:\n        with open(file, mode=\"w\") as f:\n            json.dump(base_job_template, fp=f, indent=2)\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.has_provisioner_for_type","title":"<code>has_provisioner_for_type</code>","text":"<p>Check if there is a provisioner for the given work pool type.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_type</code> <code>str</code> <p>The type of the work pool.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if a provisioner exists for the given type, False otherwise.</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>def has_provisioner_for_type(work_pool_type: str) -&gt; bool:\n    \"\"\"\n    Check if there is a provisioner for the given work pool type.\n\n    Args:\n        work_pool_type (str): The type of the work pool.\n\n    Returns:\n        bool: True if a provisioner exists for the given type, False otherwise.\n    \"\"\"\n    return work_pool_type in _provisioners\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>Inspect a work pool.</p> <p>\b Examples:     $ prefect work-pool inspect \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def inspect(\n    name: str = typer.Argument(..., help=\"The name of the work pool to inspect.\"),\n):\n    \"\"\"\n    Inspect a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool inspect \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            pool = await client.read_work_pool(work_pool_name=name)\n            app.console.print(Pretty(pool))\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool {name!r} not found!\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>List work pools.</p> <p>\b Examples:     $ prefect work-pool ls</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def ls(\n    verbose: bool = typer.Option(\n        False,\n        \"--verbose\",\n        \"-v\",\n        help=\"Show additional information about work pools.\",\n    ),\n):\n    \"\"\"\n    List work pools.\n\n    \\b\n    Examples:\n        $ prefect work-pool ls\n    \"\"\"\n    table = Table(\n        title=\"Work Pools\", caption=\"(**) denotes a paused pool\", caption_style=\"red\"\n    )\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Type\", style=\"magenta\", no_wrap=True)\n    table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n    if verbose:\n        table.add_column(\"Base Job Template\", style=\"magenta\", no_wrap=True)\n\n    async with get_client() as client:\n        pools = await client.read_work_pools()\n\n    def sort_by_created_key(q):\n        return pendulum.now(\"utc\") - q.created\n\n    for pool in sorted(pools, key=sort_by_created_key):\n        row = [\n            f\"{pool.name} [red](**)\" if pool.is_paused else pool.name,\n            str(pool.type),\n            str(pool.id),\n            (\n                f\"[red]{pool.concurrency_limit}\"\n                if pool.concurrency_limit is not None\n                else \"[blue]None\"\n            ),\n        ]\n        if verbose:\n            row.append(str(pool.base_job_template))\n        table.add_row(*row)\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.pause","title":"<code>pause</code>  <code>async</code>","text":"<p>Pause a work pool.</p> <p>\b Examples:     $ prefect work-pool pause \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def pause(\n    name: str = typer.Argument(..., help=\"The name of the work pool to pause.\"),\n):\n    \"\"\"\n    Pause a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool pause \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    is_paused=True,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Paused work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.preview","title":"<code>preview</code>  <code>async</code>","text":"<p>Preview the work pool's scheduled work for all queues.</p> <p>\b Examples:     $ prefect work-pool preview \"my-pool\" --hours 24</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def preview(\n    name: str = typer.Argument(None, help=\"The name or ID of the work pool to preview\"),\n    hours: int = typer.Option(\n        None,\n        \"-h\",\n        \"--hours\",\n        help=\"The number of hours to look ahead; defaults to 1 hour\",\n    ),\n):\n    \"\"\"\n    Preview the work pool's scheduled work for all queues.\n\n    \\b\n    Examples:\n        $ prefect work-pool preview \"my-pool\" --hours 24\n\n    \"\"\"\n    if hours is None:\n        hours = 1\n\n    async with get_client() as client:\n        try:\n            responses = await client.get_scheduled_flow_runs_for_work_pool(\n                work_pool_name=name,\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n    runs = [response.flow_run for response in responses]\n    table = Table(caption=\"(**) denotes a late run\", caption_style=\"red\")\n\n    table.add_column(\n        \"Scheduled Start Time\", justify=\"left\", style=\"yellow\", no_wrap=True\n    )\n    table.add_column(\"Run ID\", justify=\"left\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Deployment ID\", style=\"blue\", no_wrap=True)\n\n    pendulum.now(\"utc\").add(hours=hours or 1)\n\n    now = pendulum.now(\"utc\")\n\n    def sort_by_created_key(r):\n        return now - r.created\n\n    for run in sorted(runs, key=sort_by_created_key):\n        table.add_row(\n            (\n                f\"{run.expected_start_time} [red](**)\"\n                if run.expected_start_time &lt; now\n                else f\"{run.expected_start_time}\"\n            ),\n            str(run.id),\n            run.name,\n            str(run.deployment_id),\n        )\n\n    if runs:\n        app.console.print(table)\n    else:\n        app.console.print(\n            (\n                \"No runs found - try increasing how far into the future you preview\"\n                \" with the --hours flag\"\n            ),\n            style=\"yellow\",\n        )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.provision_infrastructure","title":"<code>provision_infrastructure</code>  <code>async</code>","text":"<p>Provision infrastructure for a work pool.</p> <p>\b Examples:     $ prefect work-pool provision-infrastructure \"my-pool\"</p> <pre><code>$ prefect work-pool provision-infra \"my-pool\"\n</code></pre> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command(aliases=[\"provision-infra\"])\nasync def provision_infrastructure(\n    name: str = typer.Argument(\n        ..., help=\"The name of the work pool to provision infrastructure for.\"\n    ),\n):\n    \"\"\"\n    Provision infrastructure for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool provision-infrastructure \"my-pool\"\n\n        $ prefect work-pool provision-infra \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            work_pool = await client.read_work_pool(work_pool_name=name)\n            if not work_pool.is_push_pool:\n                exit_with_error(\n                    f\"Work pool {name!r} is not a push pool type. \"\n                    \"Please try provisioning infrastructure for a push pool.\"\n                )\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool {name!r} does not exist.\")\n        except Exception as exc:\n            exit_with_error(f\"Failed to read work pool {name!r}: {exc}\")\n\n        try:\n            provisioner = get_infrastructure_provisioner_for_work_pool_type(\n                work_pool.type\n            )\n            provisioner.console = app.console\n            new_base_job_template = await provisioner.provision(\n                work_pool_name=name, base_job_template=work_pool.base_job_template\n            )\n\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    base_job_template=new_base_job_template,\n                ),\n            )\n\n        except ValueError as exc:\n            app.console.print(f\"Error: {exc}\")\n            app.console.print(\n                (\n                    \"Automatic infrastructure provisioning is not supported for\"\n                    f\" {work_pool.type!r} work pools.\"\n                ),\n                style=\"yellow\",\n            )\n        except RuntimeError as exc:\n            exit_with_error(\n                f\"Failed to provision infrastructure for '{name}' work pool: {exc}\"\n            )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.resume","title":"<code>resume</code>  <code>async</code>","text":"<p>Resume a work pool.</p> <p>\b Examples:     $ prefect work-pool resume \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def resume(\n    name: str = typer.Argument(..., help=\"The name of the work pool to resume.\"),\n):\n    \"\"\"\n    Resume a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool resume \"my-pool\"\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    is_paused=False,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(f\"Resumed work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.set_concurrency_limit","title":"<code>set_concurrency_limit</code>  <code>async</code>","text":"<p>Set the concurrency limit for a work pool.</p> <p>\b Examples:     $ prefect work-pool set-concurrency-limit \"my-pool\" 10</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def set_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n    concurrency_limit: int = typer.Argument(\n        ..., help=\"The new concurrency limit for the work pool.\"\n    ),\n):\n    \"\"\"\n    Set the concurrency limit for a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool set-concurrency-limit \"my-pool\" 10\n\n    \"\"\"\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=WorkPoolUpdate(\n                    concurrency_limit=concurrency_limit,\n                ),\n            )\n        except ObjectNotFound as exc:\n            exit_with_error(exc)\n\n        exit_with_success(\n            f\"Set concurrency limit for work pool {name!r} to {concurrency_limit}\"\n        )\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_pool/#prefect.cli.work_pool.update","title":"<code>update</code>  <code>async</code>","text":"<p>Update a work pool.</p> <p>\b Examples:     $ prefect work-pool update \"my-pool\"</p> Source code in <code>prefect/cli/work_pool.py</code> <pre><code>@work_pool_app.command()\nasync def update(\n    name: str = typer.Argument(..., help=\"The name of the work pool to update.\"),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type. If None, the base job template will not be modified.\"\n        ),\n    ),\n    concurrency_limit: int = typer.Option(\n        None,\n        \"--concurrency-limit\",\n        help=(\n            \"The concurrency limit for the work pool. If None, the concurrency limit\"\n            \" will not be modified.\"\n        ),\n    ),\n    description: str = typer.Option(\n        None,\n        \"--description\",\n        help=(\n            \"The description for the work pool. If None, the description will not be\"\n            \" modified.\"\n        ),\n    ),\n):\n    \"\"\"\n    Update a work pool.\n\n    \\b\n    Examples:\n        $ prefect work-pool update \"my-pool\"\n\n    \"\"\"\n    wp = WorkPoolUpdate()\n    if base_job_template:\n        wp.base_job_template = json.load(base_job_template)\n    if concurrency_limit:\n        wp.concurrency_limit = concurrency_limit\n    if description:\n        wp.description = description\n\n    async with get_client() as client:\n        try:\n            await client.update_work_pool(\n                work_pool_name=name,\n                work_pool=wp,\n            )\n        except ObjectNotFound:\n            exit_with_error(\"Work pool named {name!r} does not exist.\")\n\n        exit_with_success(f\"Updated work pool {name!r}\")\n</code></pre>","tags":["Python API","work pools","CLI"]},{"location":"api-ref/prefect/cli/work_queue/","title":"work_queue","text":"","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue","title":"<code>prefect.cli.work_queue</code>","text":"<p>Command line interface for working with work queues.</p>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.clear_concurrency_limit","title":"<code>clear_concurrency_limit</code>  <code>async</code>","text":"<p>Clear any concurrency limits from a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def clear_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to clear\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Clear any concurrency limits from a work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                concurrency_limit=None,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = (\n            f\"Concurrency limits removed on work queue {name!r} in work pool {pool!r}\"\n        )\n    else:\n        success_message = f\"Concurrency limits removed on work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.create","title":"<code>create</code>  <code>async</code>","text":"<p>Create a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def create(\n    name: str = typer.Argument(..., help=\"The unique name to assign this work queue\"),\n    limit: int = typer.Option(\n        None, \"-l\", \"--limit\", help=\"The concurrency limit to set on the queue.\"\n    ),\n    tags: List[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--tag\",\n        help=(\n            \"DEPRECATED: One or more optional tags. This option will be removed on\"\n            \" 2023-02-23.\"\n        ),\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool to create the work queue in.\",\n    ),\n    priority: Optional[int] = typer.Option(\n        None,\n        \"-q\",\n        \"--priority\",\n        help=\"The associated priority for the created work queue\",\n    ),\n):\n    \"\"\"\n    Create a work queue.\n    \"\"\"\n    if tags:\n        app.console.print(\n            (\n                \"Supplying `tags` for work queues is deprecated. This work \"\n                \"queue will use legacy tag-matching behavior. \"\n                \"This option will be removed on 2023-02-23.\"\n            ),\n            style=\"red\",\n        )\n\n    if pool and tags:\n        exit_with_error(\n            \"Work queues created with tags cannot specify work pools or set priorities.\"\n        )\n\n    async with get_client() as client:\n        try:\n            result = await client.create_work_queue(\n                name=name, tags=tags or None, work_pool_name=pool, priority=priority\n            )\n            if limit is not None:\n                await client.update_work_queue(\n                    id=result.id,\n                    concurrency_limit=limit,\n                )\n        except ObjectAlreadyExists:\n            exit_with_error(f\"Work queue with name: {name!r} already exists.\")\n        except ObjectNotFound:\n            exit_with_error(f\"Work pool with name: {pool!r} not found.\")\n\n    if tags:\n        tags_message = f\"tags - {', '.join(sorted(tags))}\\n\" or \"\"\n        output_msg = dedent(\n            f\"\"\"\n            Created work queue with properties:\n                name - {name!r}\n                id - {result.id}\n                concurrency limit - {limit}\n                {tags_message}\n            Start an agent to pick up flow runs from the work queue:\n                prefect agent start -q '{result.name}'\n\n            Inspect the work queue:\n                prefect work-queue inspect '{result.name}'\n            \"\"\"\n        )\n    else:\n        if not pool:\n            # specify the default work pool name after work queue creation to allow the server\n            # to handle a bunch of logic associated with agents without work pools\n            pool = DEFAULT_AGENT_WORK_POOL_NAME\n        output_msg = dedent(\n            f\"\"\"\n            Created work queue with properties:\n                name - {name!r}\n                work pool - {pool!r}\n                id - {result.id}\n                concurrency limit - {limit}\n            Start an agent to pick up flow runs from the work queue:\n                prefect agent start -q '{result.name} -p {pool}'\n\n            Inspect the work queue:\n                prefect work-queue inspect '{result.name}'\n            \"\"\"\n        )\n    exit_with_success(output_msg)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.delete","title":"<code>delete</code>  <code>async</code>","text":"<p>Delete a work queue by ID.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def delete(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to delete\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queue to delete.\",\n    ),\n):\n    \"\"\"\n    Delete a work queue by ID.\n    \"\"\"\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            await client.delete_work_queue_by_id(id=queue_id)\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n    if pool:\n        success_message = (\n            f\"Successfully deleted work queue {name!r} in work pool {pool!r}\"\n        )\n    else:\n        success_message = f\"Successfully deleted work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.inspect","title":"<code>inspect</code>  <code>async</code>","text":"<p>Inspect a work queue by ID.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def inspect(\n    name: str = typer.Argument(\n        None, help=\"The name or ID of the work queue to inspect\"\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Inspect a work queue by ID.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            result = await client.read_work_queue(id=queue_id)\n            app.console.print(Pretty(result))\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n        try:\n            status = await client.read_work_queue_status(id=queue_id)\n            app.console.print(Pretty(status))\n        except ObjectNotFound:\n            pass\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.ls","title":"<code>ls</code>  <code>async</code>","text":"<p>View all work queues.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def ls(\n    verbose: bool = typer.Option(\n        False, \"--verbose\", \"-v\", help=\"Display more information.\"\n    ),\n    work_queue_prefix: str = typer.Option(\n        None,\n        \"--match\",\n        \"-m\",\n        help=(\n            \"Will match work queues with names that start with the specified prefix\"\n            \" string\"\n        ),\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queues to list.\",\n    ),\n):\n    \"\"\"\n    View all work queues.\n    \"\"\"\n    if not pool and not experiment_enabled(\"work_pools\"):\n        table = Table(\n            title=\"Work Queues\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Filter (Deprecated)\", style=\"magenta\", no_wrap=True)\n\n        async with get_client() as client:\n            if work_queue_prefix is not None:\n                queues = await client.match_work_queues([work_queue_prefix])\n            else:\n                queues = await client.read_work_queues()\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    str(queue.id),\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose and queue.filter is not None:\n                    row.append(queue.filter.json())\n                table.add_row(*row)\n    elif not pool:\n        table = Table(\n            title=\"Work Queues\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"Pool\", style=\"magenta\", no_wrap=True)\n        table.add_column(\"ID\", justify=\"right\", style=\"cyan\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Filter (Deprecated)\", style=\"magenta\", no_wrap=True)\n\n        async with get_client() as client:\n            if work_queue_prefix is not None:\n                queues = await client.match_work_queues([work_queue_prefix])\n            else:\n                queues = await client.read_work_queues()\n\n            pool_ids = [q.work_pool_id for q in queues]\n            wp_filter = WorkPoolFilter(id=WorkPoolFilterId(any_=pool_ids))\n            pools = await client.read_work_pools(work_pool_filter=wp_filter)\n            pool_id_name_map = {p.id: p.name for p in pools}\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    pool_id_name_map[queue.work_pool_id],\n                    str(queue.id),\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose and queue.filter is not None:\n                    row.append(queue.filter.json())\n                table.add_row(*row)\n\n    else:\n        table = Table(\n            title=f\"Work Queues in Work Pool {pool!r}\",\n            caption=\"(**) denotes a paused queue\",\n            caption_style=\"red\",\n        )\n        table.add_column(\"Name\", style=\"green\", no_wrap=True)\n        table.add_column(\"Priority\", style=\"magenta\", no_wrap=True)\n        table.add_column(\"Concurrency Limit\", style=\"blue\", no_wrap=True)\n        if verbose:\n            table.add_column(\"Description\", style=\"cyan\", no_wrap=False)\n\n        async with get_client() as client:\n            try:\n                queues = await client.read_work_queues(work_pool_name=pool)\n            except ObjectNotFound:\n                exit_with_error(f\"No work pool found: {pool!r}\")\n\n            def sort_by_created_key(q):\n                return pendulum.now(\"utc\") - q.created\n\n            for queue in sorted(queues, key=sort_by_created_key):\n                row = [\n                    f\"{queue.name} [red](**)\" if queue.is_paused else queue.name,\n                    f\"{queue.priority}\",\n                    (\n                        f\"[red]{queue.concurrency_limit}\"\n                        if queue.concurrency_limit is not None\n                        else \"[blue]None\"\n                    ),\n                ]\n                if verbose:\n                    row.append(queue.description)\n                table.add_row(*row)\n\n    app.console.print(table)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.pause","title":"<code>pause</code>  <code>async</code>","text":"<p>Pause a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def pause(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to pause\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Pause a work queue.\n    \"\"\"\n\n    if not pool and not typer.confirm(\n        f\"You have not specified a work pool. Are you sure you want to pause {name} work queue in `{DEFAULT_AGENT_WORK_POOL_NAME}`?\"\n    ):\n        exit_with_error(\"Work queue pause aborted!\")\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                is_paused=True,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = f\"Work queue {name!r} in work pool {pool!r} paused\"\n    else:\n        success_message = f\"Work queue {name!r} paused\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.preview","title":"<code>preview</code>  <code>async</code>","text":"<p>Preview a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def preview(\n    name: str = typer.Argument(\n        None, help=\"The name or ID of the work queue to preview\"\n    ),\n    hours: int = typer.Option(\n        None,\n        \"-h\",\n        \"--hours\",\n        help=\"The number of hours to look ahead; defaults to 1 hour\",\n    ),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Preview a work queue.\n    \"\"\"\n    if pool:\n        title = f\"Preview of Work Queue {name!r} in Work Pool {pool!r}\"\n    else:\n        title = f\"Preview of Work Queue {name!r}\"\n\n    table = Table(title=title, caption=\"(**) denotes a late run\", caption_style=\"red\")\n    table.add_column(\n        \"Scheduled Start Time\", justify=\"left\", style=\"yellow\", no_wrap=True\n    )\n    table.add_column(\"Run ID\", justify=\"left\", style=\"cyan\", no_wrap=True)\n    table.add_column(\"Name\", style=\"green\", no_wrap=True)\n    table.add_column(\"Deployment ID\", style=\"blue\", no_wrap=True)\n\n    window = pendulum.now(\"utc\").add(hours=hours or 1)\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name, work_pool_name=pool\n    )\n    async with get_client() as client:\n        if pool:\n            try:\n                responses = await client.get_scheduled_flow_runs_for_work_pool(\n                    work_pool_name=pool,\n                    work_queue_names=[name],\n                )\n                runs = [response.flow_run for response in responses]\n            except ObjectNotFound:\n                exit_with_error(f\"No work queue found: {name!r} in work pool {pool!r}\")\n        else:\n            try:\n                runs = await client.get_runs_in_work_queue(\n                    queue_id,\n                    limit=10,\n                    scheduled_before=window,\n                )\n            except ObjectNotFound:\n                exit_with_error(f\"No work queue found: {name!r}\")\n    now = pendulum.now(\"utc\")\n\n    def sort_by_created_key(r):\n        return now - r.created\n\n    for run in sorted(runs, key=sort_by_created_key):\n        table.add_row(\n            (\n                f\"{run.expected_start_time} [red](**)\"\n                if run.expected_start_time &lt; now\n                else f\"{run.expected_start_time}\"\n            ),\n            str(run.id),\n            run.name,\n            str(run.deployment_id),\n        )\n\n    if runs:\n        app.console.print(table)\n    else:\n        app.console.print(\n            (\n                \"No runs found - try increasing how far into the future you preview\"\n                \" with the --hours flag\"\n            ),\n            style=\"yellow\",\n        )\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.read_wq_runs","title":"<code>read_wq_runs</code>  <code>async</code>","text":"<p>Get runs in a work queue. Note that this will trigger an artificial poll of the work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command(\"read-runs\")\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def read_wq_runs(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to poll\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool containing the work queue to poll.\",\n    ),\n):\n    \"\"\"\n    Get runs in a work queue. Note that this will trigger an artificial poll of\n    the work queue.\n    \"\"\"\n\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n    async with get_client() as client:\n        try:\n            runs = await client.get_runs_in_work_queue(id=queue_id)\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n    success_message = (\n        f\"Read {len(runs)} runs for work queue {name!r} in work pool {pool}: {runs}\"\n    )\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.resume","title":"<code>resume</code>  <code>async</code>","text":"<p>Resume a paused work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def resume(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue to resume\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Resume a paused work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                is_paused=False,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = f\"No work queue found: {name!r} in work pool {pool!r}\"\n            else:\n                error_message = f\"No work queue found: {name!r}\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = f\"Work queue {name!r} in work pool {pool!r} resumed\"\n    else:\n        success_message = f\"Work queue {name!r} resumed\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/work_queue/#prefect.cli.work_queue.set_concurrency_limit","title":"<code>set_concurrency_limit</code>  <code>async</code>","text":"<p>Set a concurrency limit on a work queue.</p> Source code in <code>prefect/cli/work_queue.py</code> <pre><code>@work_app.command()\n@experimental_parameter(\"pool\", group=\"work_pools\", when=lambda y: y is not None)\nasync def set_concurrency_limit(\n    name: str = typer.Argument(..., help=\"The name or ID of the work queue\"),\n    limit: int = typer.Argument(..., help=\"The concurrency limit to set on the queue.\"),\n    pool: Optional[str] = typer.Option(\n        None,\n        \"-p\",\n        \"--pool\",\n        help=\"The name of the work pool that the work queue belongs to.\",\n    ),\n):\n    \"\"\"\n    Set a concurrency limit on a work queue.\n    \"\"\"\n    queue_id = await _get_work_queue_id_from_name_or_id(\n        name_or_id=name,\n        work_pool_name=pool,\n    )\n\n    async with get_client() as client:\n        try:\n            await client.update_work_queue(\n                id=queue_id,\n                concurrency_limit=limit,\n            )\n        except ObjectNotFound:\n            if pool:\n                error_message = (\n                    f\"No work queue named {name!r} found in work pool {pool!r}.\"\n                )\n            else:\n                error_message = f\"No work queue named {name!r} found.\"\n            exit_with_error(error_message)\n\n    if pool:\n        success_message = (\n            f\"Concurrency limit of {limit} set on work queue {name!r} in work pool\"\n            f\" {pool!r}\"\n        )\n    else:\n        success_message = f\"Concurrency limit of {limit} set on work queue {name!r}\"\n    exit_with_success(success_message)\n</code></pre>","tags":["Python API","CLI","work-queue"]},{"location":"api-ref/prefect/cli/worker/","title":"worker","text":"","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/cli/worker/#prefect.cli.worker","title":"<code>prefect.cli.worker</code>","text":"","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/cli/worker/#prefect.cli.worker.start","title":"<code>start</code>  <code>async</code>","text":"<p>Start a worker process to poll a work pool for flow runs.</p> Source code in <code>prefect/cli/worker.py</code> <pre><code>@worker_app.command()\nasync def start(\n    worker_name: str = typer.Option(\n        None,\n        \"-n\",\n        \"--name\",\n        help=(\n            \"The name to give to the started worker. If not provided, a unique name\"\n            \" will be generated.\"\n        ),\n    ),\n    work_pool_name: str = typer.Option(\n        ...,\n        \"-p\",\n        \"--pool\",\n        help=\"The work pool the started worker should poll.\",\n        prompt=True,\n    ),\n    work_queues: List[str] = typer.Option(\n        None,\n        \"-q\",\n        \"--work-queue\",\n        help=(\n            \"One or more work queue names for the worker to pull from. If not provided,\"\n            \" the worker will pull from all work queues in the work pool.\"\n        ),\n    ),\n    worker_type: Optional[str] = typer.Option(\n        None,\n        \"-t\",\n        \"--type\",\n        help=(\n            \"The type of worker to start. If not provided, the worker type will be\"\n            \" inferred from the work pool.\"\n        ),\n    ),\n    prefetch_seconds: int = SettingsOption(\n        PREFECT_WORKER_PREFETCH_SECONDS,\n        help=\"Number of seconds to look into the future for scheduled flow runs.\",\n    ),\n    run_once: bool = typer.Option(\n        False, help=\"Only run worker polling once. By default, the worker runs forever.\"\n    ),\n    limit: int = typer.Option(\n        None,\n        \"-l\",\n        \"--limit\",\n        help=\"Maximum number of flow runs to start simultaneously.\",\n    ),\n    with_healthcheck: bool = typer.Option(\n        False, help=\"Start a healthcheck server for the worker.\"\n    ),\n    install_policy: InstallPolicy = typer.Option(\n        InstallPolicy.PROMPT.value,\n        \"--install-policy\",\n        help=\"Install policy to use workers from Prefect integration packages.\",\n        case_sensitive=False,\n    ),\n    base_job_template: typer.FileText = typer.Option(\n        None,\n        \"--base-job-template\",\n        help=(\n            \"The path to a JSON file containing the base job template to use. If\"\n            \" unspecified, Prefect will use the default base job template for the given\"\n            \" worker type. If the work pool already exists, this will be ignored.\"\n        ),\n    ),\n):\n    \"\"\"\n    Start a worker process to poll a work pool for flow runs.\n    \"\"\"\n\n    is_paused = await _check_work_pool_paused(work_pool_name)\n    if is_paused:\n        app.console.print(\n            (\n                f\"The work pool {work_pool_name!r} is currently paused. This worker\"\n                \" will not execute any flow runs until the work pool is unpaused.\"\n            ),\n            style=\"yellow\",\n        )\n\n    is_queues_paused = await _check_work_queues_paused(\n        work_pool_name,\n        work_queues,\n    )\n    if is_queues_paused:\n        queue_scope = (\n            \"All work queues\" if not work_queues else \"Specified work queue(s)\"\n        )\n        app.console.print(\n            (\n                f\"{queue_scope} in the work pool {work_pool_name!r} are currently\"\n                \" paused. This worker will not execute any flow runs until the work\"\n                \" queues are unpaused.\"\n            ),\n            style=\"yellow\",\n        )\n\n    worker_cls = await _get_worker_class(worker_type, work_pool_name, install_policy)\n\n    if worker_cls is None:\n        exit_with_error(\n            \"Unable to start worker. Please ensure you have the necessary dependencies\"\n            \" installed to run your desired worker type.\"\n        )\n\n    worker_process_id = os.getpid()\n    setup_signal_handlers_worker(\n        worker_process_id, f\"the {worker_type} worker\", app.console.print\n    )\n\n    template_contents = None\n    if base_job_template is not None:\n        template_contents = json.load(fp=base_job_template)\n\n    async with worker_cls(\n        name=worker_name,\n        work_pool_name=work_pool_name,\n        work_queues=work_queues,\n        limit=limit,\n        prefetch_seconds=prefetch_seconds,\n        heartbeat_interval_seconds=PREFECT_WORKER_HEARTBEAT_SECONDS.value(),\n        base_job_template=template_contents,\n    ) as worker:\n        app.console.print(f\"Worker {worker.name!r} started!\", style=\"green\")\n        try:\n            async with anyio.create_task_group() as tg:\n                # wait for an initial heartbeat to configure the worker\n                await worker.sync_with_backend()\n                # schedule the scheduled flow run polling loop\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.get_and_submit_flow_runs,\n                        interval=PREFECT_WORKER_QUERY_SECONDS.value(),\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,  # Up to ~1 minute interval during backoff\n                    )\n                )\n                # schedule the sync loop\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.sync_with_backend,\n                        interval=worker.heartbeat_interval_seconds,\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=worker.check_for_cancelled_flow_runs,\n                        interval=PREFECT_WORKER_QUERY_SECONDS.value() * 2,\n                        run_once=run_once,\n                        printer=app.console.print,\n                        jitter_range=0.3,\n                        backoff=4,\n                    )\n                )\n\n                started_event = await worker._emit_worker_started_event()\n\n                # if --with-healthcheck was passed, start the healthcheck server\n                if with_healthcheck:\n                    # we'll start the ASGI server in a separate thread so that\n                    # uvicorn does not block the main thread\n                    server_thread = threading.Thread(\n                        name=\"healthcheck-server-thread\",\n                        target=partial(\n                            start_healthcheck_server,\n                            worker=worker,\n                            query_interval_seconds=PREFECT_WORKER_QUERY_SECONDS.value(),\n                        ),\n                        daemon=True,\n                    )\n                    server_thread.start()\n        except CancelledError:\n            logger.debug(\"Worker task group cancelled\")\n\n    await worker._emit_worker_stopped_event(started_event)\n    app.console.print(f\"Worker {worker.name!r} stopped!\")\n</code></pre>","tags":["Python API","workers","CLI"]},{"location":"api-ref/prefect/client/base/","title":"base","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base","title":"<code>prefect.client.base</code>","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse","title":"<code>PrefectResponse</code>","text":"<p>               Bases: <code>Response</code></p> <p>A Prefect wrapper for the <code>httpx.Response</code> class.</p> <p>Provides more informative error messages.</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectResponse(httpx.Response):\n    \"\"\"\n    A Prefect wrapper for the `httpx.Response` class.\n\n    Provides more informative error messages.\n    \"\"\"\n\n    def raise_for_status(self) -&gt; None:\n        \"\"\"\n        Raise an exception if the response contains an HTTPStatusError.\n\n        The `PrefectHTTPStatusError` contains useful additional information that\n        is not contained in the `HTTPStatusError`.\n        \"\"\"\n        try:\n            return super().raise_for_status()\n        except HTTPStatusError as exc:\n            raise PrefectHTTPStatusError.from_httpx_error(exc) from exc.__cause__\n\n    @classmethod\n    def from_httpx_response(cls: Type[Self], response: httpx.Response) -&gt; Self:\n        \"\"\"\n        Create a `PrefectReponse` from an `httpx.Response`.\n\n        By changing the `__class__` attribute of the Response, we change the method\n        resolution order to look for methods defined in PrefectResponse, while leaving\n        everything else about the original Response instance intact.\n        \"\"\"\n        new_response = copy.copy(response)\n        new_response.__class__ = cls\n        return new_response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse.raise_for_status","title":"<code>raise_for_status</code>","text":"<p>Raise an exception if the response contains an HTTPStatusError.</p> <p>The <code>PrefectHTTPStatusError</code> contains useful additional information that is not contained in the <code>HTTPStatusError</code>.</p> Source code in <code>prefect/client/base.py</code> <pre><code>def raise_for_status(self) -&gt; None:\n    \"\"\"\n    Raise an exception if the response contains an HTTPStatusError.\n\n    The `PrefectHTTPStatusError` contains useful additional information that\n    is not contained in the `HTTPStatusError`.\n    \"\"\"\n    try:\n        return super().raise_for_status()\n    except HTTPStatusError as exc:\n        raise PrefectHTTPStatusError.from_httpx_error(exc) from exc.__cause__\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectResponse.from_httpx_response","title":"<code>from_httpx_response</code>  <code>classmethod</code>","text":"<p>Create a <code>PrefectReponse</code> from an <code>httpx.Response</code>.</p> <p>By changing the <code>__class__</code> attribute of the Response, we change the method resolution order to look for methods defined in PrefectResponse, while leaving everything else about the original Response instance intact.</p> Source code in <code>prefect/client/base.py</code> <pre><code>@classmethod\ndef from_httpx_response(cls: Type[Self], response: httpx.Response) -&gt; Self:\n    \"\"\"\n    Create a `PrefectReponse` from an `httpx.Response`.\n\n    By changing the `__class__` attribute of the Response, we change the method\n    resolution order to look for methods defined in PrefectResponse, while leaving\n    everything else about the original Response instance intact.\n    \"\"\"\n    new_response = copy.copy(response)\n    new_response.__class__ = cls\n    return new_response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxAsyncClient","title":"<code>PrefectHttpxAsyncClient</code>","text":"<p>               Bases: <code>AsyncClient</code></p> <p>A Prefect wrapper for the async httpx client with support for retry-after headers for the provided status codes (typically 429, 502 and 503).</p> <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p> <p>For more details on rate limit headers, see: Configuring Cloudflare Rate Limiting</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxAsyncClient(httpx.AsyncClient):\n    \"\"\"\n    A Prefect wrapper for the async httpx client with support for retry-after headers\n    for the provided status codes (typically 429, 502 and 503).\n\n    Additionally, this client will always call `raise_for_status` on responses.\n\n    For more details on rate limit headers, see:\n    [Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        enable_csrf_support: bool = False,\n        raise_on_all_errors: bool = True,\n        **kwargs,\n    ):\n        self.enable_csrf_support: bool = enable_csrf_support\n        self.csrf_token: Optional[str] = None\n        self.csrf_token_expiration: Optional[datetime] = None\n        self.csrf_client_id: uuid.UUID = uuid.uuid4()\n        self.raise_on_all_errors: bool = raise_on_all_errors\n\n        super().__init__(*args, **kwargs)\n\n        user_agent = (\n            f\"prefect/{prefect.__version__} (API {constants.SERVER_API_VERSION})\"\n        )\n        self.headers[\"User-Agent\"] = user_agent\n\n    async def _send_with_retry(\n        self,\n        request: Request,\n        send: Callable[[Request], Awaitable[Response]],\n        send_args: Tuple,\n        send_kwargs: Dict,\n        retry_codes: Set[int] = set(),\n        retry_exceptions: Tuple[Exception, ...] = tuple(),\n    ):\n        \"\"\"\n        Send a request and retry it if it fails.\n\n        Sends the provided request and retries it up to PREFECT_CLIENT_MAX_RETRIES times\n        if the request either raises an exception listed in `retry_exceptions` or\n        receives a response with a status code listed in `retry_codes`.\n\n        Retries will be delayed based on either the retry header (preferred) or\n        exponential backoff if a retry header is not provided.\n        \"\"\"\n        try_count = 0\n        response = None\n\n        is_change_request = request.method.lower() in {\"post\", \"put\", \"patch\", \"delete\"}\n\n        if self.enable_csrf_support and is_change_request:\n            await self._add_csrf_headers(request=request)\n\n        while try_count &lt;= PREFECT_CLIENT_MAX_RETRIES.value():\n            try_count += 1\n            retry_seconds = None\n            exc_info = None\n\n            try:\n                response = await send(request, *send_args, **send_kwargs)\n            except retry_exceptions:  # type: ignore\n                if try_count &gt; PREFECT_CLIENT_MAX_RETRIES.value():\n                    raise\n                # Otherwise, we will ignore this error but capture the info for logging\n                exc_info = sys.exc_info()\n            else:\n                # We got a response; check if it's a CSRF error, otherwise\n                # return immediately if it is not retryable\n                if (\n                    response.status_code == status.HTTP_403_FORBIDDEN\n                    and \"Invalid CSRF token\" in response.text\n                ):\n                    # We got a CSRF error, clear the token and try again\n                    self.csrf_token = None\n                    await self._add_csrf_headers(request)\n                elif response.status_code not in retry_codes:\n                    return response\n\n                if \"Retry-After\" in response.headers:\n                    retry_seconds = float(response.headers[\"Retry-After\"])\n\n            # Use an exponential back-off if not set in a header\n            if retry_seconds is None:\n                retry_seconds = 2**try_count\n\n            # Add jitter\n            jitter_factor = PREFECT_CLIENT_RETRY_JITTER_FACTOR.value()\n            if retry_seconds &gt; 0 and jitter_factor &gt; 0:\n                if response is not None and \"Retry-After\" in response.headers:\n                    # Always wait for _at least_ retry seconds if requested by the API\n                    retry_seconds = bounded_poisson_interval(\n                        retry_seconds, retry_seconds * (1 + jitter_factor)\n                    )\n                else:\n                    # Otherwise, use a symmetrical jitter\n                    retry_seconds = clamped_poisson_interval(\n                        retry_seconds, jitter_factor\n                    )\n\n            logger.debug(\n                (\n                    \"Encountered retryable exception during request. \"\n                    if exc_info\n                    else (\n                        \"Received response with retryable status code\"\n                        f\" {response.status_code}. \"\n                    )\n                )\n                + f\"Another attempt will be made in {retry_seconds}s. \"\n                \"This is attempt\"\n                f\" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.\",\n                exc_info=exc_info,\n            )\n            await anyio.sleep(retry_seconds)\n\n        assert (\n            response is not None\n        ), \"Retry handling ended without response or exception\"\n\n        # We ran out of retries, return the failed response\n        return response\n\n    async def send(self, request: Request, *args, **kwargs) -&gt; Response:\n        \"\"\"\n        Send a request with automatic retry behavior for the following status codes:\n\n        - 403 Forbidden, if the request failed due to CSRF protection\n        - 408 Request Timeout\n        - 429 CloudFlare-style rate limiting\n        - 502 Bad Gateway\n        - 503 Service unavailable\n        - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n        \"\"\"\n\n        super_send = super().send\n        response = await self._send_with_retry(\n            request=request,\n            send=super_send,\n            send_args=args,\n            send_kwargs=kwargs,\n            retry_codes={\n                status.HTTP_429_TOO_MANY_REQUESTS,\n                status.HTTP_503_SERVICE_UNAVAILABLE,\n                status.HTTP_502_BAD_GATEWAY,\n                status.HTTP_408_REQUEST_TIMEOUT,\n                *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n            },\n            retry_exceptions=(\n                httpx.ReadTimeout,\n                httpx.PoolTimeout,\n                httpx.ConnectTimeout,\n                # `ConnectionResetError` when reading socket raises as a `ReadError`\n                httpx.ReadError,\n                # Sockets can be closed during writes resulting in a `WriteError`\n                httpx.WriteError,\n                # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n                httpx.RemoteProtocolError,\n                # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n                httpx.LocalProtocolError,\n            ),\n        )\n\n        # Convert to a Prefect response to add nicer errors messages\n        response = PrefectResponse.from_httpx_response(response)\n\n        if self.raise_on_all_errors:\n            response.raise_for_status()\n\n        return response\n\n    async def _add_csrf_headers(self, request: Request):\n        now = datetime.now(timezone.utc)\n\n        if not self.enable_csrf_support:\n            return\n\n        if not self.csrf_token or (\n            self.csrf_token_expiration and now &gt; self.csrf_token_expiration\n        ):\n            token_request = self.build_request(\n                \"GET\", f\"/csrf-token?client={self.csrf_client_id}\"\n            )\n\n            try:\n                token_response = await self.send(token_request)\n            except PrefectHTTPStatusError as exc:\n                old_server = exc.response.status_code == status.HTTP_404_NOT_FOUND\n                unconfigured_server = (\n                    exc.response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY\n                    and \"CSRF protection is disabled.\" in exc.response.text\n                )\n\n                if old_server or unconfigured_server:\n                    # The token endpoint is either unavailable, suggesting an\n                    # older server, or CSRF protection is disabled. In either\n                    # case we should disable CSRF support.\n                    self.enable_csrf_support = False\n                    return\n\n                raise\n\n            token: CsrfToken = CsrfToken.parse_obj(token_response.json())\n            self.csrf_token = token.token\n            self.csrf_token_expiration = token.expiration\n\n        request.headers[\"Prefect-Csrf-Token\"] = self.csrf_token\n        request.headers[\"Prefect-Csrf-Client\"] = str(self.csrf_client_id)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxAsyncClient.send","title":"<code>send</code>  <code>async</code>","text":"<p>Send a request with automatic retry behavior for the following status codes:</p> <ul> <li>403 Forbidden, if the request failed due to CSRF protection</li> <li>408 Request Timeout</li> <li>429 CloudFlare-style rate limiting</li> <li>502 Bad Gateway</li> <li>503 Service unavailable</li> <li>Any additional status codes provided in <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code></li> </ul> Source code in <code>prefect/client/base.py</code> <pre><code>async def send(self, request: Request, *args, **kwargs) -&gt; Response:\n    \"\"\"\n    Send a request with automatic retry behavior for the following status codes:\n\n    - 403 Forbidden, if the request failed due to CSRF protection\n    - 408 Request Timeout\n    - 429 CloudFlare-style rate limiting\n    - 502 Bad Gateway\n    - 503 Service unavailable\n    - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n    \"\"\"\n\n    super_send = super().send\n    response = await self._send_with_retry(\n        request=request,\n        send=super_send,\n        send_args=args,\n        send_kwargs=kwargs,\n        retry_codes={\n            status.HTTP_429_TOO_MANY_REQUESTS,\n            status.HTTP_503_SERVICE_UNAVAILABLE,\n            status.HTTP_502_BAD_GATEWAY,\n            status.HTTP_408_REQUEST_TIMEOUT,\n            *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n        },\n        retry_exceptions=(\n            httpx.ReadTimeout,\n            httpx.PoolTimeout,\n            httpx.ConnectTimeout,\n            # `ConnectionResetError` when reading socket raises as a `ReadError`\n            httpx.ReadError,\n            # Sockets can be closed during writes resulting in a `WriteError`\n            httpx.WriteError,\n            # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n            httpx.RemoteProtocolError,\n            # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n            httpx.LocalProtocolError,\n        ),\n    )\n\n    # Convert to a Prefect response to add nicer errors messages\n    response = PrefectResponse.from_httpx_response(response)\n\n    if self.raise_on_all_errors:\n        response.raise_for_status()\n\n    return response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncClient","title":"<code>PrefectHttpxSyncClient</code>","text":"<p>               Bases: <code>Client</code></p> <p>A Prefect wrapper for the async httpx client with support for retry-after headers for the provided status codes (typically 429, 502 and 503).</p> <p>Additionally, this client will always call <code>raise_for_status</code> on responses.</p> <p>For more details on rate limit headers, see: Configuring Cloudflare Rate Limiting</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxSyncClient(httpx.Client):\n    \"\"\"\n    A Prefect wrapper for the async httpx client with support for retry-after headers\n    for the provided status codes (typically 429, 502 and 503).\n\n    Additionally, this client will always call `raise_for_status` on responses.\n\n    For more details on rate limit headers, see:\n    [Configuring Cloudflare Rate Limiting](https://support.cloudflare.com/hc/en-us/articles/115001635128-Configuring-Rate-Limiting-from-UI)\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        enable_csrf_support: bool = False,\n        raise_on_all_errors: bool = True,\n        **kwargs,\n    ):\n        self.enable_csrf_support: bool = enable_csrf_support\n        self.csrf_token: Optional[str] = None\n        self.csrf_token_expiration: Optional[datetime] = None\n        self.csrf_client_id: uuid.UUID = uuid.uuid4()\n        self.raise_on_all_errors: bool = raise_on_all_errors\n\n        super().__init__(*args, **kwargs)\n\n        user_agent = (\n            f\"prefect/{prefect.__version__} (API {constants.SERVER_API_VERSION})\"\n        )\n        self.headers[\"User-Agent\"] = user_agent\n\n    def _send_with_retry(\n        self,\n        request: Request,\n        send: Callable[[Request], Response],\n        send_args: Tuple,\n        send_kwargs: Dict,\n        retry_codes: Set[int] = set(),\n        retry_exceptions: Tuple[Exception, ...] = tuple(),\n    ):\n        \"\"\"\n        Send a request and retry it if it fails.\n\n        Sends the provided request and retries it up to PREFECT_CLIENT_MAX_RETRIES times\n        if the request either raises an exception listed in `retry_exceptions` or\n        receives a response with a status code listed in `retry_codes`.\n\n        Retries will be delayed based on either the retry header (preferred) or\n        exponential backoff if a retry header is not provided.\n        \"\"\"\n        try_count = 0\n        response = None\n\n        is_change_request = request.method.lower() in {\"post\", \"put\", \"patch\", \"delete\"}\n\n        if self.enable_csrf_support and is_change_request:\n            self._add_csrf_headers(request=request)\n\n        while try_count &lt;= PREFECT_CLIENT_MAX_RETRIES.value():\n            try_count += 1\n            retry_seconds = None\n            exc_info = None\n\n            try:\n                response = send(request, *send_args, **send_kwargs)\n            except retry_exceptions:  # type: ignore\n                if try_count &gt; PREFECT_CLIENT_MAX_RETRIES.value():\n                    raise\n                # Otherwise, we will ignore this error but capture the info for logging\n                exc_info = sys.exc_info()\n            else:\n                # We got a response; check if it's a CSRF error, otherwise\n                # return immediately if it is not retryable\n                if (\n                    response.status_code == status.HTTP_403_FORBIDDEN\n                    and \"Invalid CSRF token\" in response.text\n                ):\n                    # We got a CSRF error, clear the token and try again\n                    self.csrf_token = None\n                    self._add_csrf_headers(request)\n                elif response.status_code not in retry_codes:\n                    return response\n\n                if \"Retry-After\" in response.headers:\n                    retry_seconds = float(response.headers[\"Retry-After\"])\n\n            # Use an exponential back-off if not set in a header\n            if retry_seconds is None:\n                retry_seconds = 2**try_count\n\n            # Add jitter\n            jitter_factor = PREFECT_CLIENT_RETRY_JITTER_FACTOR.value()\n            if retry_seconds &gt; 0 and jitter_factor &gt; 0:\n                if response is not None and \"Retry-After\" in response.headers:\n                    # Always wait for _at least_ retry seconds if requested by the API\n                    retry_seconds = bounded_poisson_interval(\n                        retry_seconds, retry_seconds * (1 + jitter_factor)\n                    )\n                else:\n                    # Otherwise, use a symmetrical jitter\n                    retry_seconds = clamped_poisson_interval(\n                        retry_seconds, jitter_factor\n                    )\n\n            logger.debug(\n                (\n                    \"Encountered retryable exception during request. \"\n                    if exc_info\n                    else (\n                        \"Received response with retryable status code\"\n                        f\" {response.status_code}. \"\n                    )\n                )\n                + f\"Another attempt will be made in {retry_seconds}s. \"\n                \"This is attempt\"\n                f\" {try_count}/{PREFECT_CLIENT_MAX_RETRIES.value() + 1}.\",\n                exc_info=exc_info,\n            )\n            time.sleep(retry_seconds)\n\n        assert (\n            response is not None\n        ), \"Retry handling ended without response or exception\"\n\n        # We ran out of retries, return the failed response\n        return response\n\n    def send(self, request: Request, *args, **kwargs) -&gt; Response:\n        \"\"\"\n        Send a request with automatic retry behavior for the following status codes:\n\n        - 403 Forbidden, if the request failed due to CSRF protection\n        - 408 Request Timeout\n        - 429 CloudFlare-style rate limiting\n        - 502 Bad Gateway\n        - 503 Service unavailable\n        - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n        \"\"\"\n\n        super_send = super().send\n        response = self._send_with_retry(\n            request=request,\n            send=super_send,\n            send_args=args,\n            send_kwargs=kwargs,\n            retry_codes={\n                status.HTTP_429_TOO_MANY_REQUESTS,\n                status.HTTP_503_SERVICE_UNAVAILABLE,\n                status.HTTP_502_BAD_GATEWAY,\n                status.HTTP_408_REQUEST_TIMEOUT,\n                *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n            },\n            retry_exceptions=(\n                httpx.ReadTimeout,\n                httpx.PoolTimeout,\n                httpx.ConnectTimeout,\n                # `ConnectionResetError` when reading socket raises as a `ReadError`\n                httpx.ReadError,\n                # Sockets can be closed during writes resulting in a `WriteError`\n                httpx.WriteError,\n                # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n                httpx.RemoteProtocolError,\n                # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n                httpx.LocalProtocolError,\n            ),\n        )\n\n        # Convert to a Prefect response to add nicer errors messages\n        response = PrefectResponse.from_httpx_response(response)\n\n        if self.raise_on_all_errors:\n            response.raise_for_status()\n\n        return response\n\n    def _add_csrf_headers(self, request: Request):\n        now = datetime.now(timezone.utc)\n\n        if not self.enable_csrf_support:\n            return\n\n        if not self.csrf_token or (\n            self.csrf_token_expiration and now &gt; self.csrf_token_expiration\n        ):\n            token_request = self.build_request(\n                \"GET\", f\"/csrf-token?client={self.csrf_client_id}\"\n            )\n\n            try:\n                token_response = self.send(token_request)\n            except PrefectHTTPStatusError as exc:\n                old_server = exc.response.status_code == status.HTTP_404_NOT_FOUND\n                unconfigured_server = (\n                    exc.response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY\n                    and \"CSRF protection is disabled.\" in exc.response.text\n                )\n\n                if old_server or unconfigured_server:\n                    # The token endpoint is either unavailable, suggesting an\n                    # older server, or CSRF protection is disabled. In either\n                    # case we should disable CSRF support.\n                    self.enable_csrf_support = False\n                    return\n\n                raise\n\n            token: CsrfToken = CsrfToken.parse_obj(token_response.json())\n            self.csrf_token = token.token\n            self.csrf_token_expiration = token.expiration\n\n        request.headers[\"Prefect-Csrf-Token\"] = self.csrf_token\n        request.headers[\"Prefect-Csrf-Client\"] = str(self.csrf_client_id)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncClient.send","title":"<code>send</code>","text":"<p>Send a request with automatic retry behavior for the following status codes:</p> <ul> <li>403 Forbidden, if the request failed due to CSRF protection</li> <li>408 Request Timeout</li> <li>429 CloudFlare-style rate limiting</li> <li>502 Bad Gateway</li> <li>503 Service unavailable</li> <li>Any additional status codes provided in <code>PREFECT_CLIENT_RETRY_EXTRA_CODES</code></li> </ul> Source code in <code>prefect/client/base.py</code> <pre><code>def send(self, request: Request, *args, **kwargs) -&gt; Response:\n    \"\"\"\n    Send a request with automatic retry behavior for the following status codes:\n\n    - 403 Forbidden, if the request failed due to CSRF protection\n    - 408 Request Timeout\n    - 429 CloudFlare-style rate limiting\n    - 502 Bad Gateway\n    - 503 Service unavailable\n    - Any additional status codes provided in `PREFECT_CLIENT_RETRY_EXTRA_CODES`\n    \"\"\"\n\n    super_send = super().send\n    response = self._send_with_retry(\n        request=request,\n        send=super_send,\n        send_args=args,\n        send_kwargs=kwargs,\n        retry_codes={\n            status.HTTP_429_TOO_MANY_REQUESTS,\n            status.HTTP_503_SERVICE_UNAVAILABLE,\n            status.HTTP_502_BAD_GATEWAY,\n            status.HTTP_408_REQUEST_TIMEOUT,\n            *PREFECT_CLIENT_RETRY_EXTRA_CODES.value(),\n        },\n        retry_exceptions=(\n            httpx.ReadTimeout,\n            httpx.PoolTimeout,\n            httpx.ConnectTimeout,\n            # `ConnectionResetError` when reading socket raises as a `ReadError`\n            httpx.ReadError,\n            # Sockets can be closed during writes resulting in a `WriteError`\n            httpx.WriteError,\n            # Uvicorn bug, see https://github.com/PrefectHQ/prefect/issues/7512\n            httpx.RemoteProtocolError,\n            # HTTP2 bug, see https://github.com/PrefectHQ/prefect/issues/7442\n            httpx.LocalProtocolError,\n        ),\n    )\n\n    # Convert to a Prefect response to add nicer errors messages\n    response = PrefectResponse.from_httpx_response(response)\n\n    if self.raise_on_all_errors:\n        response.raise_for_status()\n\n    return response\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.PrefectHttpxSyncEphemeralClient","title":"<code>PrefectHttpxSyncEphemeralClient</code>","text":"<p>               Bases: <code>TestClient</code>, <code>PrefectHttpxSyncClient</code></p> <p>This client is a synchronous httpx client that can be used to talk directly to an ASGI app, such as an ephemeral Prefect API.</p> <p>It is a subclass of both Starlette's <code>TestClient</code> and Prefect's <code>PrefectHttpxSyncClient</code>, so it combines the synchronous testing capabilities of <code>TestClient</code> with the Prefect-specific behaviors of <code>PrefectHttpxSyncClient</code>.</p> Source code in <code>prefect/client/base.py</code> <pre><code>class PrefectHttpxSyncEphemeralClient(TestClient, PrefectHttpxSyncClient):\n    \"\"\"\n    This client is a synchronous httpx client that can be used to talk directly\n    to an ASGI app, such as an ephemeral Prefect API.\n\n    It is a subclass of both Starlette's `TestClient` and Prefect's\n    `PrefectHttpxSyncClient`, so it combines the synchronous testing\n    capabilities of `TestClient` with the Prefect-specific behaviors of\n    `PrefectHttpxSyncClient`.\n    \"\"\"\n\n    def __init__(\n        self,\n        *args,\n        # override TestClient default\n        raise_server_exceptions=False,\n        **kwargs,\n    ):\n        super().__init__(\n            *args,\n            raise_server_exceptions=raise_server_exceptions,\n            **kwargs,\n        )\n\n    pass\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/base/#prefect.client.base.app_lifespan_context","title":"<code>app_lifespan_context</code>  <code>async</code>","text":"<p>A context manager that calls startup/shutdown hooks for the given application.</p> <p>Lifespan contexts are cached per application to avoid calling the lifespan hooks more than once if the context is entered in nested code. A no-op context will be returned if the context for the given application is already being managed.</p> <p>This manager is robust to concurrent access within the event loop. For example, if you have concurrent contexts for the same application, it is guaranteed that startup hooks will be called before their context starts and shutdown hooks will only be called after their context exits.</p> <p>A reference count is used to support nested use of clients without running lifespan hooks excessively. The first client context entered will create and enter a lifespan context. Each subsequent client will increment a reference count but will not create a new lifespan context. When each client context exits, the reference count is decremented. When the last client context exits, the lifespan will be closed.</p> <p>In simple nested cases, the first client context will be the one to exit the lifespan. However, if client contexts are entered concurrently they may not exit in a consistent order. If the first client context was responsible for closing the lifespan, it would have to wait until all other client contexts to exit to avoid firing shutdown hooks while the application is in use. Waiting for the other clients to exit can introduce deadlocks, so, instead, the first client will exit without closing the lifespan context and reference counts will be used to ensure the lifespan is closed once all of the clients are done.</p> Source code in <code>prefect/client/base.py</code> <pre><code>@asynccontextmanager\nasync def app_lifespan_context(app: ASGIApp) -&gt; AsyncGenerator[None, None]:\n    \"\"\"\n    A context manager that calls startup/shutdown hooks for the given application.\n\n    Lifespan contexts are cached per application to avoid calling the lifespan hooks\n    more than once if the context is entered in nested code. A no-op context will be\n    returned if the context for the given application is already being managed.\n\n    This manager is robust to concurrent access within the event loop. For example,\n    if you have concurrent contexts for the same application, it is guaranteed that\n    startup hooks will be called before their context starts and shutdown hooks will\n    only be called after their context exits.\n\n    A reference count is used to support nested use of clients without running\n    lifespan hooks excessively. The first client context entered will create and enter\n    a lifespan context. Each subsequent client will increment a reference count but will\n    not create a new lifespan context. When each client context exits, the reference\n    count is decremented. When the last client context exits, the lifespan will be\n    closed.\n\n    In simple nested cases, the first client context will be the one to exit the\n    lifespan. However, if client contexts are entered concurrently they may not exit\n    in a consistent order. If the first client context was responsible for closing\n    the lifespan, it would have to wait until all other client contexts to exit to\n    avoid firing shutdown hooks while the application is in use. Waiting for the other\n    clients to exit can introduce deadlocks, so, instead, the first client will exit\n    without closing the lifespan context and reference counts will be used to ensure\n    the lifespan is closed once all of the clients are done.\n    \"\"\"\n    # TODO: A deadlock has been observed during multithreaded use of clients while this\n    #       lifespan context is being used. This has only been reproduced on Python 3.7\n    #       and while we hope to discourage using multiple event loops in threads, this\n    #       bug may emerge again.\n    #       See https://github.com/PrefectHQ/orion/pull/1696\n    thread_id = threading.get_ident()\n\n    # The id of the application is used instead of the hash so each application instance\n    # is managed independently even if they share the same settings. We include the\n    # thread id since applications are managed separately per thread.\n    key = (thread_id, id(app))\n\n    # On exception, this will be populated with exception details\n    exc_info = (None, None, None)\n\n    # Get a lock unique to this thread since anyio locks are not threadsafe\n    lock = APP_LIFESPANS_LOCKS[thread_id]\n\n    async with lock:\n        if key in APP_LIFESPANS:\n            # The lifespan is already being managed, just increment the reference count\n            APP_LIFESPANS_REF_COUNTS[key] += 1\n        else:\n            # Create a new lifespan manager\n            APP_LIFESPANS[key] = context = LifespanManager(\n                app, startup_timeout=30, shutdown_timeout=30\n            )\n            APP_LIFESPANS_REF_COUNTS[key] = 1\n\n            # Ensure we enter the context before releasing the lock so startup hooks\n            # are complete before another client can be used\n            await context.__aenter__()\n\n    try:\n        yield\n    except BaseException:\n        exc_info = sys.exc_info()\n        raise\n    finally:\n        # If we do not shield against anyio cancellation, the lock will return\n        # immediately and the code in its context will not run, leaving the lifespan\n        # open\n        with anyio.CancelScope(shield=True):\n            async with lock:\n                # After the consumer exits the context, decrement the reference count\n                APP_LIFESPANS_REF_COUNTS[key] -= 1\n\n                # If this the last context to exit, close the lifespan\n                if APP_LIFESPANS_REF_COUNTS[key] &lt;= 0:\n                    APP_LIFESPANS_REF_COUNTS.pop(key)\n                    context = APP_LIFESPANS.pop(key)\n                    await context.__aexit__(*exc_info)\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/","title":"cloud","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud","title":"<code>prefect.client.cloud</code>","text":"","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudUnauthorizedError","title":"<code>CloudUnauthorizedError</code>","text":"<p>               Bases: <code>PrefectException</code></p> <p>Raised when the CloudClient receives a 401 or 403 from the Cloud API.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>class CloudUnauthorizedError(PrefectException):\n    \"\"\"\n    Raised when the CloudClient receives a 401 or 403 from the Cloud API.\n    \"\"\"\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudClient","title":"<code>CloudClient</code>","text":"Source code in <code>prefect/client/cloud.py</code> <pre><code>class CloudClient:\n    def __init__(\n        self,\n        host: str,\n        api_key: str,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings or dict()\n        httpx_settings.setdefault(\"headers\", dict())\n        httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        httpx_settings.setdefault(\"base_url\", host)\n        if not PREFECT_UNIT_TEST_MODE.value():\n            httpx_settings.setdefault(\"follow_redirects\", True)\n        self._client = PrefectHttpxAsyncClient(\n            **httpx_settings, enable_csrf_support=False\n        )\n\n    async def api_healthcheck(self):\n        \"\"\"\n        Attempts to connect to the Cloud API and raises the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        with anyio.fail_after(10):\n            await self.read_workspaces()\n\n    async def read_workspaces(self) -&gt; List[Workspace]:\n        workspaces = pydantic.parse_obj_as(\n            List[Workspace], await self.get(\"/me/workspaces\")\n        )\n        return workspaces\n\n    async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n        configured_url = prefect.settings.PREFECT_API_URL.value()\n        account_id, workspace_id = re.findall(PARSE_API_URL_REGEX, configured_url)[0]\n        return await self.get(\n            f\"accounts/{account_id}/workspaces/{workspace_id}/collections/work_pool_types\"\n        )\n\n    async def __aenter__(self):\n        await self._client.__aenter__()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        return await self._client.__aexit__(*exc_info)\n\n    def __enter__(self):\n        raise RuntimeError(\n            \"The `CloudClient` must be entered with an async context. Use 'async \"\n            \"with CloudClient(...)' not 'with CloudClient(...)'\"\n        )\n\n    def __exit__(self, *_):\n        assert False, \"This should never be called but must be defined for __enter__\"\n\n    async def get(self, route, **kwargs):\n        return await self.request(\"GET\", route, **kwargs)\n\n    async def request(self, method, route, **kwargs):\n        try:\n            res = await self._client.request(method, route, **kwargs)\n            res.raise_for_status()\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code in (\n                status.HTTP_401_UNAUTHORIZED,\n                status.HTTP_403_FORBIDDEN,\n            ):\n                raise CloudUnauthorizedError\n            else:\n                raise exc\n\n        if res.status_code == status.HTTP_204_NO_CONTENT:\n            return\n\n        return res.json()\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.CloudClient.api_healthcheck","title":"<code>api_healthcheck</code>  <code>async</code>","text":"<p>Attempts to connect to the Cloud API and raises the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>async def api_healthcheck(self):\n    \"\"\"\n    Attempts to connect to the Cloud API and raises the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    with anyio.fail_after(10):\n        await self.read_workspaces()\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/cloud/#prefect.client.cloud.get_cloud_client","title":"<code>get_cloud_client</code>","text":"<p>Needs a docstring.</p> Source code in <code>prefect/client/cloud.py</code> <pre><code>def get_cloud_client(\n    host: Optional[str] = None,\n    api_key: Optional[str] = None,\n    httpx_settings: Optional[dict] = None,\n    infer_cloud_url: bool = False,\n) -&gt; \"CloudClient\":\n    \"\"\"\n    Needs a docstring.\n    \"\"\"\n    if httpx_settings is not None:\n        httpx_settings = httpx_settings.copy()\n\n    if infer_cloud_url is False:\n        host = host or PREFECT_CLOUD_API_URL.value()\n    else:\n        configured_url = prefect.settings.PREFECT_API_URL.value()\n        host = re.sub(PARSE_API_URL_REGEX, \"\", configured_url)\n\n    return CloudClient(\n        host=host,\n        api_key=api_key or PREFECT_API_KEY.value(),\n        httpx_settings=httpx_settings,\n    )\n</code></pre>","tags":["Python API"]},{"location":"api-ref/prefect/client/orchestration/","title":"orchestration","text":"<p>Asynchronous client implementation for communicating with the Prefect REST API.</p> <p>Explore the client by communicating with an in-memory webserver \u2014 no setup required:</p> <pre><code>$ # start python REPL with native await functionality\n$ python -m asyncio\n&gt;&gt;&gt; from prefect import get_client\n&gt;&gt;&gt; async with get_client() as client:\n...     response = await client.hello()\n...     print(response.json())\n\ud83d\udc4b\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration","title":"<code>prefect.client.orchestration</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient","title":"<code>PrefectClient</code>","text":"<p>An asynchronous client for interacting with the Prefect REST API.</p> <p>Parameters:</p> Name Type Description Default <code>api</code> <code>Union[str, ASGIApp]</code> <p>the REST API URL or FastAPI application to connect to</p> required <code>api_key</code> <code>str</code> <p>An optional API key for authentication.</p> <code>None</code> <code>api_version</code> <code>str</code> <p>The API version this client is compatible with.</p> <code>None</code> <code>httpx_settings</code> <code>Optional[Dict[str, Any]]</code> <p>An optional dictionary of settings to pass to the underlying <code>httpx.AsyncClient</code></p> <code>None</code> <pre><code>Say hello to a Prefect REST API\n\n&lt;div class=\"terminal\"&gt;\n```\n&gt;&gt;&gt; async with get_client() as client:\n&gt;&gt;&gt;     response = await client.hello()\n&gt;&gt;&gt;\n&gt;&gt;&gt; print(response.json())\n\ud83d\udc4b\n```\n&lt;/div&gt;\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>class PrefectClient:\n    \"\"\"\n    An asynchronous client for interacting with the [Prefect REST API](/api-ref/rest-api/).\n\n    Args:\n        api: the REST API URL or FastAPI application to connect to\n        api_key: An optional API key for authentication.\n        api_version: The API version this client is compatible with.\n        httpx_settings: An optional dictionary of settings to pass to the underlying\n            `httpx.AsyncClient`\n\n    Examples:\n\n        Say hello to a Prefect REST API\n\n        &lt;div class=\"terminal\"&gt;\n        ```\n        &gt;&gt;&gt; async with get_client() as client:\n        &gt;&gt;&gt;     response = await client.hello()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; print(response.json())\n        \ud83d\udc4b\n        ```\n        &lt;/div&gt;\n    \"\"\"\n\n    def __init__(\n        self,\n        api: Union[str, ASGIApp],\n        *,\n        api_key: str = None,\n        api_version: str = None,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings.copy() if httpx_settings else {}\n        httpx_settings.setdefault(\"headers\", {})\n\n        if PREFECT_API_TLS_INSECURE_SKIP_VERIFY:\n            httpx_settings.setdefault(\"verify\", False)\n        else:\n            cert_file = PREFECT_API_SSL_CERT_FILE.value()\n            if not cert_file:\n                cert_file = certifi.where()\n            httpx_settings.setdefault(\"verify\", cert_file)\n\n        if api_version is None:\n            api_version = SERVER_API_VERSION\n        httpx_settings[\"headers\"].setdefault(\"X-PREFECT-API-VERSION\", api_version)\n        if api_key:\n            httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        # Context management\n        self._exit_stack = AsyncExitStack()\n        self._ephemeral_app: Optional[ASGIApp] = None\n        self.manage_lifespan = True\n        self.server_type: ServerType\n\n        # Only set if this client started the lifespan of the application\n        self._ephemeral_lifespan: Optional[LifespanManager] = None\n\n        self._closed = False\n        self._started = False\n\n        # Connect to an external application\n        if isinstance(api, str):\n            if httpx_settings.get(\"app\"):\n                raise ValueError(\n                    \"Invalid httpx settings: `app` cannot be set when providing an \"\n                    \"api url. `app` is only for use with ephemeral instances. Provide \"\n                    \"it as the `api` parameter instead.\"\n                )\n            httpx_settings.setdefault(\"base_url\", api)\n\n            # See https://www.python-httpx.org/advanced/#pool-limit-configuration\n            httpx_settings.setdefault(\n                \"limits\",\n                httpx.Limits(\n                    # We see instability when allowing the client to open many connections at once.\n                    # Limiting concurrency results in more stable performance.\n                    max_connections=16,\n                    max_keepalive_connections=8,\n                    # The Prefect Cloud LB will keep connections alive for 30s.\n                    # Only allow the client to keep connections alive for 25s.\n                    keepalive_expiry=25,\n                ),\n            )\n\n            # See https://www.python-httpx.org/http2/\n            # Enabling HTTP/2 support on the client does not necessarily mean that your requests\n            # and responses will be transported over HTTP/2, since both the client and the server\n            # need to support HTTP/2. If you connect to a server that only supports HTTP/1.1 the\n            # client will use a standard HTTP/1.1 connection instead.\n            httpx_settings.setdefault(\"http2\", PREFECT_API_ENABLE_HTTP2.value())\n\n            self.server_type = (\n                ServerType.CLOUD\n                if api.startswith(PREFECT_CLOUD_API_URL.value())\n                else ServerType.SERVER\n            )\n\n        # Connect to an in-process application\n        elif isinstance(api, ASGIApp):\n            self._ephemeral_app = api\n            self.server_type = ServerType.EPHEMERAL\n\n            # When using an ephemeral server, server-side exceptions can be raised\n            # client-side breaking all of our response error code handling. To work\n            # around this, we create an ASGI transport with application exceptions\n            # disabled instead of using the application directly.\n            # refs:\n            # - https://github.com/PrefectHQ/prefect/pull/9637\n            # - https://github.com/encode/starlette/blob/d3a11205ed35f8e5a58a711db0ff59c86fa7bb31/starlette/middleware/errors.py#L184\n            # - https://github.com/tiangolo/fastapi/blob/8cc967a7605d3883bd04ceb5d25cc94ae079612f/fastapi/applications.py#L163-L164\n            httpx_settings.setdefault(\n                \"transport\",\n                httpx.ASGITransport(\n                    app=self._ephemeral_app, raise_app_exceptions=False\n                ),\n            )\n            httpx_settings.setdefault(\"base_url\", \"http://ephemeral-prefect/api\")\n\n        else:\n            raise TypeError(\n                f\"Unexpected type {type(api).__name__!r} for argument `api`. Expected\"\n                \" 'str' or 'ASGIApp/FastAPI'\"\n            )\n\n        # See https://www.python-httpx.org/advanced/#timeout-configuration\n        httpx_settings.setdefault(\n            \"timeout\",\n            httpx.Timeout(\n                connect=PREFECT_API_REQUEST_TIMEOUT.value(),\n                read=PREFECT_API_REQUEST_TIMEOUT.value(),\n                write=PREFECT_API_REQUEST_TIMEOUT.value(),\n                pool=PREFECT_API_REQUEST_TIMEOUT.value(),\n            ),\n        )\n\n        if not PREFECT_UNIT_TEST_MODE:\n            httpx_settings.setdefault(\"follow_redirects\", True)\n\n        enable_csrf_support = (\n            self.server_type != ServerType.CLOUD\n            and PREFECT_CLIENT_CSRF_SUPPORT_ENABLED.value()\n        )\n\n        self._client = PrefectHttpxAsyncClient(\n            **httpx_settings, enable_csrf_support=enable_csrf_support\n        )\n        self._loop = None\n\n        # See https://www.python-httpx.org/advanced/#custom-transports\n        #\n        # If we're using an HTTP/S client (not the ephemeral client), adjust the\n        # transport to add retries _after_ it is instantiated. If we alter the transport\n        # before instantiation, the transport will not be aware of proxies unless we\n        # reproduce all of the logic to make it so.\n        #\n        # Only alter the transport to set our default of 3 retries, don't modify any\n        # transport a user may have provided via httpx_settings.\n        #\n        # Making liberal use of getattr and isinstance checks here to avoid any\n        # surprises if the internals of httpx or httpcore change on us\n        if isinstance(api, str) and not httpx_settings.get(\"transport\"):\n            transport_for_url = getattr(self._client, \"_transport_for_url\", None)\n            if callable(transport_for_url):\n                server_transport = transport_for_url(httpx.URL(api))\n                if isinstance(server_transport, httpx.AsyncHTTPTransport):\n                    pool = getattr(server_transport, \"_pool\", None)\n                    if isinstance(pool, httpcore.AsyncConnectionPool):\n                        pool._retries = 3\n\n        self.logger = get_logger(\"client\")\n\n    @property\n    def api_url(self) -&gt; httpx.URL:\n        \"\"\"\n        Get the base URL for the API.\n        \"\"\"\n        return self._client.base_url\n\n    # API methods ----------------------------------------------------------------------\n\n    async def api_healthcheck(self) -&gt; Optional[Exception]:\n        \"\"\"\n        Attempts to connect to the API and returns the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        try:\n            await self._client.get(\"/health\")\n            return None\n        except Exception as exc:\n            return exc\n\n    async def hello(self) -&gt; httpx.Response:\n        \"\"\"\n        Send a GET request to /hello for testing purposes.\n        \"\"\"\n        return await self._client.get(\"/hello\")\n\n    async def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow: a [Flow][prefect.flows.Flow] object\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        return await self.create_flow_from_name(flow.name)\n\n    async def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow_name: the name of the new flow\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        flow_data = FlowCreate(name=flow_name)\n        response = await self._client.post(\n            \"/flows/\", json=flow_data.dict(json_compatible=True)\n        )\n\n        flow_id = response.json().get(\"id\")\n        if not flow_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        # Return the id of the created flow\n        return UUID(flow_id)\n\n    async def read_flow(self, flow_id: UUID) -&gt; Flow:\n        \"\"\"\n        Query the Prefect API for a flow by id.\n\n        Args:\n            flow_id: the flow ID of interest\n\n        Returns:\n            a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow\n        \"\"\"\n        response = await self._client.get(f\"/flows/{flow_id}\")\n        return Flow.parse_obj(response.json())\n\n    async def read_flows(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[Flow]:\n        \"\"\"\n        Query the Prefect API for flows. Only flows matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flows\n            limit: limit for the flow query\n            offset: offset for the flow query\n\n        Returns:\n            a list of Flow model representations of the flows\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/flows/filter\", json=body)\n        return pydantic.parse_obj_as(List[Flow], response.json())\n\n    async def read_flow_by_name(\n        self,\n        flow_name: str,\n    ) -&gt; Flow:\n        \"\"\"\n        Query the Prefect API for a flow by name.\n\n        Args:\n            flow_name: the name of a flow\n\n        Returns:\n            a fully hydrated Flow model\n        \"\"\"\n        response = await self._client.get(f\"/flows/name/{flow_name}\")\n        return Flow.parse_obj(response.json())\n\n    async def create_flow_run_from_deployment(\n        self,\n        deployment_id: UUID,\n        *,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        state: prefect.states.State = None,\n        name: str = None,\n        tags: Iterable[str] = None,\n        idempotency_key: str = None,\n        parent_task_run_id: UUID = None,\n        work_queue_name: str = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a deployment.\n\n        Args:\n            deployment_id: The deployment ID to create the flow run from\n            parameters: Parameter overrides for this flow run. Merged with the\n                deployment defaults\n            context: Optional run context data\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n            name: An optional name for the flow run. If not provided, the server will\n                generate a name.\n            tags: An optional iterable of tags to apply to the flow run; these tags\n                are merged with the deployment's tags.\n            idempotency_key: Optional idempotency key for creation of the flow run.\n                If the key matches the key of an existing flow run, the existing run will\n                be returned instead of creating a new one.\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            work_queue_name: An optional work queue name to add this run to. If not provided,\n                will default to the deployment's set work queue.  If one is provided that does not\n                exist, a new work queue will be created within the deployment's work pool.\n            job_variables: Optional variables that will be supplied to the flow run job.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n        state = state or prefect.states.Scheduled()\n        tags = tags or []\n\n        flow_run_create = DeploymentFlowRunCreate(\n            parameters=parameters,\n            context=context,\n            state=state.to_state_create(),\n            tags=tags,\n            name=name,\n            idempotency_key=idempotency_key,\n            parent_task_run_id=parent_task_run_id,\n            job_variables=job_variables,\n        )\n\n        # done separately to avoid including this field in payloads sent to older API versions\n        if work_queue_name:\n            flow_run_create.work_queue_name = work_queue_name\n\n        response = await self._client.post(\n            f\"/deployments/{deployment_id}/create_flow_run\",\n            json=flow_run_create.dict(json_compatible=True, exclude_unset=True),\n        )\n        return FlowRun.parse_obj(response.json())\n\n    async def create_flow_run(\n        self,\n        flow: \"FlowObject\",\n        name: Optional[str] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        tags: Optional[Iterable[str]] = None,\n        parent_task_run_id: Optional[UUID] = None,\n        state: Optional[\"prefect.states.State\"] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a flow.\n\n        Args:\n            flow: The flow model to create the flow run for\n            name: An optional name for the flow run\n            parameters: Parameter overrides for this flow run.\n            context: Optional run context data\n            tags: a list of tags to apply to this flow run\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        # Retrieve the flow id\n        flow_id = await self.create_flow(flow)\n\n        flow_run_create = FlowRunCreate(\n            flow_id=flow_id,\n            flow_version=flow.version,\n            name=name,\n            parameters=parameters,\n            context=context,\n            tags=list(tags or []),\n            parent_task_run_id=parent_task_run_id,\n            state=state.to_state_create(),\n            empirical_policy=FlowRunPolicy(\n                retries=flow.retries,\n                retry_delay=flow.retry_delay_seconds,\n            ),\n        )\n\n        flow_run_create_json = flow_run_create.dict(json_compatible=True)\n        response = await self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n        flow_run = FlowRun.parse_obj(response.json())\n\n        # Restore the parameters to the local objects to retain expectations about\n        # Python objects\n        flow_run.parameters = parameters\n\n        return flow_run\n\n    async def update_flow_run(\n        self,\n        flow_run_id: UUID,\n        flow_version: Optional[str] = None,\n        parameters: Optional[dict] = None,\n        name: Optional[str] = None,\n        tags: Optional[Iterable[str]] = None,\n        empirical_policy: Optional[FlowRunPolicy] = None,\n        infrastructure_pid: Optional[str] = None,\n        job_variables: Optional[dict] = None,\n    ) -&gt; httpx.Response:\n        \"\"\"\n        Update a flow run's details.\n\n        Args:\n            flow_run_id: The identifier for the flow run to update.\n            flow_version: A new version string for the flow run.\n            parameters: A dictionary of parameter values for the flow run. This will not\n                be merged with any existing parameters.\n            name: A new name for the flow run.\n            empirical_policy: A new flow run orchestration policy. This will not be\n                merged with any existing policy.\n            tags: An iterable of new tags for the flow run. These will not be merged with\n                any existing tags.\n            infrastructure_pid: The id of flow run as returned by an\n                infrastructure block.\n\n        Returns:\n            an `httpx.Response` object from the PATCH request\n        \"\"\"\n        params = {}\n        if flow_version is not None:\n            params[\"flow_version\"] = flow_version\n        if parameters is not None:\n            params[\"parameters\"] = parameters\n        if name is not None:\n            params[\"name\"] = name\n        if tags is not None:\n            params[\"tags\"] = tags\n        if empirical_policy is not None:\n            params[\"empirical_policy\"] = empirical_policy\n        if infrastructure_pid:\n            params[\"infrastructure_pid\"] = infrastructure_pid\n        if job_variables is not None:\n            params[\"job_variables\"] = job_variables\n\n        flow_run_data = FlowRunUpdate(**params)\n\n        return await self._client.patch(\n            f\"/flow_runs/{flow_run_id}\",\n            json=flow_run_data.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def delete_flow_run(\n        self,\n        flow_run_id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a flow run by UUID.\n\n        Args:\n            flow_run_id: The flow run UUID of interest.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_concurrency_limit(\n        self,\n        tag: str,\n        concurrency_limit: int,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a tag concurrency limit in the Prefect API. These limits govern concurrently\n        running tasks.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n            concurrency_limit: the maximum number of concurrent task runs for a given tag\n\n        Raises:\n            httpx.RequestError: if the concurrency limit was not created for any reason\n\n        Returns:\n            the ID of the concurrency limit in the backend\n        \"\"\"\n\n        concurrency_limit_create = ConcurrencyLimitCreate(\n            tag=tag,\n            concurrency_limit=concurrency_limit,\n        )\n        response = await self._client.post(\n            \"/concurrency_limits/\",\n            json=concurrency_limit_create.dict(json_compatible=True),\n        )\n\n        concurrency_limit_id = response.json().get(\"id\")\n\n        if not concurrency_limit_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(concurrency_limit_id)\n\n    async def read_concurrency_limit_by_tag(\n        self,\n        tag: str,\n    ):\n        \"\"\"\n        Read the concurrency limit set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: if the concurrency limit was not created for any reason\n\n        Returns:\n            the concurrency limit set on a specific tag\n        \"\"\"\n        try:\n            response = await self._client.get(\n                f\"/concurrency_limits/tag/{tag}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        concurrency_limit_id = response.json().get(\"id\")\n\n        if not concurrency_limit_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        concurrency_limit = ConcurrencyLimit.parse_obj(response.json())\n        return concurrency_limit\n\n    async def read_concurrency_limits(\n        self,\n        limit: int,\n        offset: int,\n    ):\n        \"\"\"\n        Lists concurrency limits set on task run tags.\n\n        Args:\n            limit: the maximum number of concurrency limits returned\n            offset: the concurrency limit query offset\n\n        Returns:\n            a list of concurrency limits\n        \"\"\"\n\n        body = {\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/concurrency_limits/filter\", json=body)\n        return pydantic.parse_obj_as(List[ConcurrencyLimit], response.json())\n\n    async def reset_concurrency_limit_by_tag(\n        self,\n        tag: str,\n        slot_override: Optional[List[Union[UUID, str]]] = None,\n    ):\n        \"\"\"\n        Resets the concurrency limit slots set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n            slot_override: a list of task run IDs that are currently using a\n                concurrency slot, please check that any task run IDs included in\n                `slot_override` are currently running, otherwise those concurrency\n                slots will never be released.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        \"\"\"\n        if slot_override is not None:\n            slot_override = [str(slot) for slot in slot_override]\n\n        try:\n            await self._client.post(\n                f\"/concurrency_limits/tag/{tag}/reset\",\n                json=dict(slot_override=slot_override),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_concurrency_limit_by_tag(\n        self,\n        tag: str,\n    ):\n        \"\"\"\n        Delete the concurrency limit set on a specific tag.\n\n        Args:\n            tag: a tag the concurrency limit is applied to\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/concurrency_limits/tag/{tag}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_work_queue(\n        self,\n        name: str,\n        tags: Optional[List[str]] = None,\n        description: Optional[str] = None,\n        is_paused: Optional[bool] = None,\n        concurrency_limit: Optional[int] = None,\n        priority: Optional[int] = None,\n        work_pool_name: Optional[str] = None,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Create a work queue.\n\n        Args:\n            name: a unique name for the work queue\n            tags: DEPRECATED: an optional list of tags to filter on; only work scheduled with these tags\n                will be included in the queue. This option will be removed on 2023-02-23.\n            description: An optional description for the work queue.\n            is_paused: Whether or not the work queue is paused.\n            concurrency_limit: An optional concurrency limit for the work queue.\n            priority: The queue's priority. Lower values are higher priority (1 is the highest).\n            work_pool_name: The name of the work pool to use for this queue.\n\n        Raises:\n            prefect.exceptions.ObjectAlreadyExists: If request returns 409\n            httpx.RequestError: If request fails\n\n        Returns:\n            The created work queue\n        \"\"\"\n        if tags:\n            warnings.warn(\n                (\n                    \"The use of tags for creating work queue filters is deprecated.\"\n                    \" This option will be removed on 2023-02-23.\"\n                ),\n                DeprecationWarning,\n            )\n            filter = QueueFilter(tags=tags)\n        else:\n            filter = None\n        create_model = WorkQueueCreate(name=name, filter=filter)\n        if description is not None:\n            create_model.description = description\n        if is_paused is not None:\n            create_model.is_paused = is_paused\n        if concurrency_limit is not None:\n            create_model.concurrency_limit = concurrency_limit\n        if priority is not None:\n            create_model.priority = priority\n\n        data = create_model.dict(json_compatible=True)\n        try:\n            if work_pool_name is not None:\n                response = await self._client.post(\n                    f\"/work_pools/{work_pool_name}/queues\", json=data\n                )\n            else:\n                response = await self._client.post(\"/work_queues/\", json=data)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            elif e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueue.parse_obj(response.json())\n\n    async def read_work_queue_by_name(\n        self,\n        name: str,\n        work_pool_name: Optional[str] = None,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Read a work queue by name.\n\n        Args:\n            name (str): a unique name for the work queue\n            work_pool_name (str, optional): the name of the work pool\n                the queue belongs to.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: if no work queue is found\n            httpx.HTTPStatusError: other status errors\n\n        Returns:\n            WorkQueue: a work queue API object\n        \"\"\"\n        try:\n            if work_pool_name is not None:\n                response = await self._client.get(\n                    f\"/work_pools/{work_pool_name}/queues/{name}\"\n                )\n            else:\n                response = await self._client.get(f\"/work_queues/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return WorkQueue.parse_obj(response.json())\n\n    async def update_work_queue(self, id: UUID, **kwargs):\n        \"\"\"\n        Update properties of a work queue.\n\n        Args:\n            id: the ID of the work queue to update\n            **kwargs: the fields to update\n\n        Raises:\n            ValueError: if no kwargs are provided\n            prefect.exceptions.ObjectNotFound: if request returns 404\n            httpx.RequestError: if the request fails\n\n        \"\"\"\n        if not kwargs:\n            raise ValueError(\"No fields provided to update.\")\n\n        data = WorkQueueUpdate(**kwargs).dict(json_compatible=True, exclude_unset=True)\n        try:\n            await self._client.patch(f\"/work_queues/{id}\", json=data)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def get_runs_in_work_queue(\n        self,\n        id: UUID,\n        limit: int = 10,\n        scheduled_before: datetime.datetime = None,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Read flow runs off a work queue.\n\n        Args:\n            id: the id of the work queue to read from\n            limit: a limit on the number of runs to return\n            scheduled_before: a timestamp; only runs scheduled before this time will be returned.\n                Defaults to now.\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            List[FlowRun]: a list of FlowRun objects read from the queue\n        \"\"\"\n        if scheduled_before is None:\n            scheduled_before = pendulum.now(\"UTC\")\n\n        try:\n            response = await self._client.post(\n                f\"/work_queues/{id}/get_runs\",\n                json={\n                    \"limit\": limit,\n                    \"scheduled_before\": scheduled_before.isoformat(),\n                },\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    async def read_work_queue(\n        self,\n        id: UUID,\n    ) -&gt; WorkQueue:\n        \"\"\"\n        Read a work queue.\n\n        Args:\n            id: the id of the work queue to load\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            WorkQueue: an instantiated WorkQueue object\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_queues/{id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueue.parse_obj(response.json())\n\n    async def read_work_queue_status(\n        self,\n        id: UUID,\n    ) -&gt; WorkQueueStatusDetail:\n        \"\"\"\n        Read a work queue status.\n\n        Args:\n            id: the id of the work queue to load\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            WorkQueueStatus: an instantiated WorkQueueStatus object\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_queues/{id}/status\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return WorkQueueStatusDetail.parse_obj(response.json())\n\n    async def match_work_queues(\n        self,\n        prefixes: List[str],\n        work_pool_name: Optional[str] = None,\n    ) -&gt; List[WorkQueue]:\n        \"\"\"\n        Query the Prefect API for work queues with names with a specific prefix.\n\n        Args:\n            prefixes: a list of strings used to match work queue name prefixes\n            work_pool_name: an optional work pool name to scope the query to\n\n        Returns:\n            a list of WorkQueue model representations\n                of the work queues\n        \"\"\"\n        page_length = 100\n        current_page = 0\n        work_queues = []\n\n        while True:\n            new_queues = await self.read_work_queues(\n                work_pool_name=work_pool_name,\n                offset=current_page * page_length,\n                limit=page_length,\n                work_queue_filter=WorkQueueFilter(\n                    name=WorkQueueFilterName(startswith_=prefixes)\n                ),\n            )\n            if not new_queues:\n                break\n            work_queues += new_queues\n            current_page += 1\n\n        return work_queues\n\n    async def delete_work_queue_by_id(\n        self,\n        id: UUID,\n    ):\n        \"\"\"\n        Delete a work queue by its ID.\n\n        Args:\n            id: the id of the work queue to delete\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/work_queues/{id}\",\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_block_type(self, block_type: BlockTypeCreate) -&gt; BlockType:\n        \"\"\"\n        Create a block type in the Prefect API.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_types/\",\n                json=block_type.dict(\n                    json_compatible=True, exclude_unset=True, exclude={\"id\"}\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockType.parse_obj(response.json())\n\n    async def create_block_schema(self, block_schema: BlockSchemaCreate) -&gt; BlockSchema:\n        \"\"\"\n        Create a block schema in the Prefect API.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_schemas/\",\n                json=block_schema.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_type\", \"checksum\"},\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockSchema.parse_obj(response.json())\n\n    async def create_block_document(\n        self,\n        block_document: Union[BlockDocument, BlockDocumentCreate],\n        include_secrets: bool = True,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Create a block document in the Prefect API. This data is used to configure a\n        corresponding Block.\n\n        Args:\n            include_secrets (bool): whether to include secret values\n                on the stored Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. Note Blocks may not work as expected if\n                this is set to `False`.\n        \"\"\"\n        if isinstance(block_document, BlockDocument):\n            block_document = BlockDocumentCreate.parse_obj(\n                block_document.dict(\n                    json_compatible=True,\n                    include_secrets=include_secrets,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_schema\", \"block_type\"},\n                ),\n            )\n\n        try:\n            response = await self._client.post(\n                \"/block_documents/\",\n                json=block_document.dict(\n                    json_compatible=True,\n                    include_secrets=include_secrets,\n                    exclude_unset=True,\n                    exclude={\"id\", \"block_schema\", \"block_type\"},\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def update_block_document(\n        self,\n        block_document_id: UUID,\n        block_document: BlockDocumentUpdate,\n    ):\n        \"\"\"\n        Update a block document in the Prefect API.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/block_documents/{block_document_id}\",\n                json=block_document.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    include={\"data\", \"merge_existing_data\", \"block_schema_id\"},\n                    include_secrets=True,\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_block_document(self, block_document_id: UUID):\n        \"\"\"\n        Delete a block document.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/block_documents/{block_document_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_block_type_by_slug(self, slug: str) -&gt; BlockType:\n        \"\"\"\n        Read a block type by its slug.\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/block_types/slug/{slug}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockType.parse_obj(response.json())\n\n    async def read_block_schema_by_checksum(\n        self, checksum: str, version: Optional[str] = None\n    ) -&gt; BlockSchema:\n        \"\"\"\n        Look up a block schema checksum\n        \"\"\"\n        try:\n            url = f\"/block_schemas/checksum/{checksum}\"\n            if version is not None:\n                url = f\"{url}?version={version}\"\n            response = await self._client.get(url)\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockSchema.parse_obj(response.json())\n\n    async def update_block_type(self, block_type_id: UUID, block_type: BlockTypeUpdate):\n        \"\"\"\n        Update a block document in the Prefect API.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/block_types/{block_type_id}\",\n                json=block_type.dict(\n                    json_compatible=True,\n                    exclude_unset=True,\n                    include=BlockTypeUpdate.updatable_fields(),\n                    include_secrets=True,\n                ),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_block_type(self, block_type_id: UUID):\n        \"\"\"\n        Delete a block type.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/block_types/{block_type_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            elif (\n                e.response.status_code == status.HTTP_403_FORBIDDEN\n                and e.response.json()[\"detail\"]\n                == \"protected block types cannot be deleted.\"\n            ):\n                raise prefect.exceptions.ProtectedBlockError(\n                    \"Protected block types cannot be deleted.\"\n                ) from e\n            else:\n                raise\n\n    async def read_block_types(self) -&gt; List[BlockType]:\n        \"\"\"\n        Read all block types\n        Raises:\n            httpx.RequestError: if the block types were not found\n\n        Returns:\n            List of BlockTypes.\n        \"\"\"\n        response = await self._client.post(\"/block_types/filter\", json={})\n        return pydantic.parse_obj_as(List[BlockType], response.json())\n\n    async def read_block_schemas(self) -&gt; List[BlockSchema]:\n        \"\"\"\n        Read all block schemas\n        Raises:\n            httpx.RequestError: if a valid block schema was not found\n\n        Returns:\n            A BlockSchema.\n        \"\"\"\n        response = await self._client.post(\"/block_schemas/filter\", json={})\n        return pydantic.parse_obj_as(List[BlockSchema], response.json())\n\n    async def get_most_recent_block_schema_for_block_type(\n        self,\n        block_type_id: UUID,\n    ) -&gt; Optional[BlockSchema]:\n        \"\"\"\n        Fetches the most recent block schema for a specified block type ID.\n\n        Args:\n            block_type_id: The ID of the block type.\n\n        Raises:\n            httpx.RequestError: If the request fails for any reason.\n\n        Returns:\n            The most recent block schema or None.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/block_schemas/filter\",\n                json={\n                    \"block_schemas\": {\"block_type_id\": {\"any_\": [str(block_type_id)]}},\n                    \"limit\": 1,\n                },\n            )\n        except httpx.HTTPStatusError:\n            raise\n        return BlockSchema.parse_obj(response.json()[0]) if response.json() else None\n\n    async def read_block_document(\n        self,\n        block_document_id: UUID,\n        include_secrets: bool = True,\n    ):\n        \"\"\"\n        Read the block document with the specified ID.\n\n        Args:\n            block_document_id: the block document id\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Raises:\n            httpx.RequestError: if the block document was not found for any reason\n\n        Returns:\n            A block document or None.\n        \"\"\"\n        assert (\n            block_document_id is not None\n        ), \"Unexpected ID on block document. Was it persisted?\"\n        try:\n            response = await self._client.get(\n                f\"/block_documents/{block_document_id}\",\n                params=dict(include_secrets=include_secrets),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def read_block_document_by_name(\n        self,\n        name: str,\n        block_type_slug: str,\n        include_secrets: bool = True,\n    ) -&gt; BlockDocument:\n        \"\"\"\n        Read the block document with the specified name that corresponds to a\n        specific block type name.\n\n        Args:\n            name: The block document name.\n            block_type_slug: The block type slug.\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Raises:\n            httpx.RequestError: if the block document was not found for any reason\n\n        Returns:\n            A block document or None.\n        \"\"\"\n        try:\n            response = await self._client.get(\n                f\"/block_types/slug/{block_type_slug}/block_documents/name/{name}\",\n                params=dict(include_secrets=include_secrets),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return BlockDocument.parse_obj(response.json())\n\n    async def read_block_documents(\n        self,\n        block_schema_type: Optional[str] = None,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n        include_secrets: bool = True,\n    ):\n        \"\"\"\n        Read block documents\n\n        Args:\n            block_schema_type: an optional block schema type\n            offset: an offset\n            limit: the number of blocks to return\n            include_secrets (bool): whether to include secret values\n                on the Block, corresponding to Pydantic's `SecretStr` and\n                `SecretBytes` fields. These fields are automatically obfuscated\n                by Pydantic, but users can additionally choose not to receive\n                their values from the API. Note that any business logic on the\n                Block may not work if this is `False`.\n\n        Returns:\n            A list of block documents\n        \"\"\"\n        response = await self._client.post(\n            \"/block_documents/filter\",\n            json=dict(\n                block_schema_type=block_schema_type,\n                offset=offset,\n                limit=limit,\n                include_secrets=include_secrets,\n            ),\n        )\n        return pydantic.parse_obj_as(List[BlockDocument], response.json())\n\n    async def read_block_documents_by_type(\n        self,\n        block_type_slug: str,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n        include_secrets: bool = True,\n    ) -&gt; List[BlockDocument]:\n        \"\"\"Retrieve block documents by block type slug.\n\n        Args:\n            block_type_slug: The block type slug.\n            offset: an offset\n            limit: the number of blocks to return\n            include_secrets: whether to include secret values\n\n        Returns:\n            A list of block documents\n        \"\"\"\n        response = await self._client.get(\n            f\"/block_types/slug/{block_type_slug}/block_documents\",\n            params=dict(\n                offset=offset,\n                limit=limit,\n                include_secrets=include_secrets,\n            ),\n        )\n\n        return pydantic.parse_obj_as(List[BlockDocument], response.json())\n\n    async def create_deployment(\n        self,\n        flow_id: UUID,\n        name: str,\n        version: str = None,\n        schedule: SCHEDULE_TYPES = None,\n        schedules: List[DeploymentScheduleCreate] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        description: str = None,\n        work_queue_name: str = None,\n        work_pool_name: str = None,\n        tags: List[str] = None,\n        storage_document_id: UUID = None,\n        manifest_path: str = None,\n        path: str = None,\n        entrypoint: str = None,\n        infrastructure_document_id: UUID = None,\n        infra_overrides: Optional[Dict[str, Any]] = None,  # for backwards compat\n        parameter_openapi_schema: Optional[Dict[str, Any]] = None,\n        is_schedule_active: Optional[bool] = None,\n        paused: Optional[bool] = None,\n        pull_steps: Optional[List[dict]] = None,\n        enforce_parameter_schema: Optional[bool] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a deployment.\n\n        Args:\n            flow_id: the flow ID to create a deployment for\n            name: the name of the deployment\n            version: an optional version string for the deployment\n            schedule: an optional schedule to apply to the deployment\n            tags: an optional list of tags to apply to the deployment\n            storage_document_id: an reference to the storage block document\n                used for the deployed flow\n            infrastructure_document_id: an reference to the infrastructure block document\n                to use for this deployment\n            job_variables: A dictionary of dot delimited infrastructure overrides that\n                will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n                `namespace='prefect'`. This argument was previously named `infra_overrides`.\n                Both arguments are supported for backwards compatibility.\n\n        Raises:\n            httpx.RequestError: if the deployment was not created for any reason\n\n        Returns:\n            the ID of the deployment in the backend\n        \"\"\"\n        jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n        deployment_create = DeploymentCreate(\n            flow_id=flow_id,\n            name=name,\n            version=version,\n            parameters=dict(parameters or {}),\n            tags=list(tags or []),\n            work_queue_name=work_queue_name,\n            description=description,\n            storage_document_id=storage_document_id,\n            path=path,\n            entrypoint=entrypoint,\n            manifest_path=manifest_path,  # for backwards compat\n            infrastructure_document_id=infrastructure_document_id,\n            job_variables=jv,\n            parameter_openapi_schema=parameter_openapi_schema,\n            is_schedule_active=is_schedule_active,\n            paused=paused,\n            schedule=schedule,\n            schedules=schedules or [],\n            pull_steps=pull_steps,\n            enforce_parameter_schema=enforce_parameter_schema,\n        )\n\n        if work_pool_name is not None:\n            deployment_create.work_pool_name = work_pool_name\n\n        # Exclude newer fields that are not set to avoid compatibility issues\n        exclude = {\n            field\n            for field in [\"work_pool_name\", \"work_queue_name\"]\n            if field not in deployment_create.__fields_set__\n        }\n\n        if deployment_create.is_schedule_active is None:\n            exclude.add(\"is_schedule_active\")\n\n        if deployment_create.paused is None:\n            exclude.add(\"paused\")\n\n        if deployment_create.pull_steps is None:\n            exclude.add(\"pull_steps\")\n\n        if deployment_create.enforce_parameter_schema is None:\n            exclude.add(\"enforce_parameter_schema\")\n\n        json = deployment_create.dict(json_compatible=True, exclude=exclude)\n        response = await self._client.post(\n            \"/deployments/\",\n            json=json,\n        )\n        deployment_id = response.json().get(\"id\")\n        if not deployment_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(deployment_id)\n\n    async def update_schedule(self, deployment_id: UUID, active: bool = True):\n        path = \"set_schedule_active\" if active else \"set_schedule_inactive\"\n        await self._client.post(\n            f\"/deployments/{deployment_id}/{path}\",\n        )\n\n    async def set_deployment_paused_state(self, deployment_id: UUID, paused: bool):\n        await self._client.patch(\n            f\"/deployments/{deployment_id}\", json={\"paused\": paused}\n        )\n\n    async def update_deployment(\n        self,\n        deployment: Deployment,\n        schedule: SCHEDULE_TYPES = None,\n        is_schedule_active: bool = None,\n    ):\n        deployment_update = DeploymentUpdate(\n            version=deployment.version,\n            schedule=schedule if schedule is not None else deployment.schedule,\n            is_schedule_active=(\n                is_schedule_active\n                if is_schedule_active is not None\n                else deployment.is_schedule_active\n            ),\n            description=deployment.description,\n            work_queue_name=deployment.work_queue_name,\n            tags=deployment.tags,\n            manifest_path=deployment.manifest_path,\n            path=deployment.path,\n            entrypoint=deployment.entrypoint,\n            parameters=deployment.parameters,\n            storage_document_id=deployment.storage_document_id,\n            infrastructure_document_id=deployment.infrastructure_document_id,\n            job_variables=deployment.job_variables,\n            enforce_parameter_schema=deployment.enforce_parameter_schema,\n        )\n\n        if getattr(deployment, \"work_pool_name\", None) is not None:\n            deployment_update.work_pool_name = deployment.work_pool_name\n\n        exclude = set()\n        if deployment.enforce_parameter_schema is None:\n            exclude.add(\"enforce_parameter_schema\")\n\n        await self._client.patch(\n            f\"/deployments/{deployment.id}\",\n            json=deployment_update.dict(json_compatible=True, exclude=exclude),\n        )\n\n    async def _create_deployment_from_schema(self, schema: DeploymentCreate) -&gt; UUID:\n        \"\"\"\n        Create a deployment from a prepared `DeploymentCreate` schema.\n        \"\"\"\n        # TODO: We are likely to remove this method once we have considered the\n        #       packaging interface for deployments further.\n        response = await self._client.post(\n            \"/deployments/\", json=schema.dict(json_compatible=True)\n        )\n        deployment_id = response.json().get(\"id\")\n        if not deployment_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(deployment_id)\n\n    async def read_deployment(\n        self,\n        deployment_id: UUID,\n    ) -&gt; DeploymentResponse:\n        \"\"\"\n        Query the Prefect API for a deployment by id.\n\n        Args:\n            deployment_id: the deployment ID of interest\n\n        Returns:\n            a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/{deployment_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return DeploymentResponse.parse_obj(response.json())\n\n    async def read_deployment_by_name(\n        self,\n        name: str,\n    ) -&gt; DeploymentResponse:\n        \"\"\"\n        Query the Prefect API for a deployment by name.\n\n        Args:\n            name: A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\n\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If request fails\n\n        Returns:\n            a Deployment model representation of the deployment\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return DeploymentResponse.parse_obj(response.json())\n\n    async def read_deployments(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        limit: int = None,\n        sort: DeploymentSort = None,\n        offset: int = 0,\n    ) -&gt; List[DeploymentResponse]:\n        \"\"\"\n        Query the Prefect API for deployments. Only deployments matching all\n        the provided criteria will be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            limit: a limit for the deployment query\n            offset: an offset for the deployment query\n\n        Returns:\n            a list of Deployment model representations\n                of the deployments\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n            \"sort\": sort,\n        }\n\n        response = await self._client.post(\"/deployments/filter\", json=body)\n        return pydantic.parse_obj_as(List[DeploymentResponse], response.json())\n\n    async def delete_deployment(\n        self,\n        deployment_id: UUID,\n    ):\n        \"\"\"\n        Delete deployment by id.\n\n        Args:\n            deployment_id: The deployment id of interest.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/deployments/{deployment_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_deployment_schedules(\n        self,\n        deployment_id: UUID,\n        schedules: List[Tuple[SCHEDULE_TYPES, bool]],\n    ) -&gt; List[DeploymentSchedule]:\n        \"\"\"\n        Create deployment schedules.\n\n        Args:\n            deployment_id: the deployment ID\n            schedules: a list of tuples containing the schedule to create\n                       and whether or not it should be active.\n\n        Raises:\n            httpx.RequestError: if the schedules were not created for any reason\n\n        Returns:\n            the list of schedules created in the backend\n        \"\"\"\n        deployment_schedule_create = [\n            DeploymentScheduleCreate(schedule=schedule[0], active=schedule[1])\n            for schedule in schedules\n        ]\n\n        json = [\n            deployment_schedule_create.dict(json_compatible=True)\n            for deployment_schedule_create in deployment_schedule_create\n        ]\n        response = await self._client.post(\n            f\"/deployments/{deployment_id}/schedules\", json=json\n        )\n        return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n\n    async def read_deployment_schedules(\n        self,\n        deployment_id: UUID,\n    ) -&gt; List[DeploymentSchedule]:\n        \"\"\"\n        Query the Prefect API for a deployment's schedules.\n\n        Args:\n            deployment_id: the deployment ID\n\n        Returns:\n            a list of DeploymentSchedule model representations of the deployment schedules\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/deployments/{deployment_id}/schedules\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n\n    async def update_deployment_schedule(\n        self,\n        deployment_id: UUID,\n        schedule_id: UUID,\n        active: Optional[bool] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n    ):\n        \"\"\"\n        Update a deployment schedule by ID.\n\n        Args:\n            deployment_id: the deployment ID\n            schedule_id: the deployment schedule ID of interest\n            active: whether or not the schedule should be active\n            schedule: the cron, rrule, or interval schedule this deployment schedule should use\n        \"\"\"\n        kwargs = {}\n        if active is not None:\n            kwargs[\"active\"] = active\n        if schedule is not None:\n            kwargs[\"schedule\"] = schedule\n\n        deployment_schedule_update = DeploymentScheduleUpdate(**kwargs)\n        json = deployment_schedule_update.dict(json_compatible=True, exclude_unset=True)\n\n        try:\n            await self._client.patch(\n                f\"/deployments/{deployment_id}/schedules/{schedule_id}\", json=json\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_deployment_schedule(\n        self,\n        deployment_id: UUID,\n        schedule_id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a deployment schedule.\n\n        Args:\n            deployment_id: the deployment ID\n            schedule_id: the ID of the deployment schedule to delete.\n\n        Raises:\n            httpx.RequestError: if the schedules were not deleted for any reason\n        \"\"\"\n        try:\n            await self._client.delete(\n                f\"/deployments/{deployment_id}/schedules/{schedule_id}\"\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n        \"\"\"\n        Query the Prefect API for a flow run by id.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n\n        Returns:\n            a Flow Run model representation of the flow run\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return FlowRun.parse_obj(response.json())\n\n    async def resume_flow_run(\n        self, flow_run_id: UUID, run_input: Optional[Dict] = None\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Resumes a paused flow run.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n            run_input: the input to resume the flow run with\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        try:\n            response = await self._client.post(\n                f\"/flow_runs/{flow_run_id}/resume\", json={\"run_input\": run_input}\n            )\n        except httpx.HTTPStatusError:\n            raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_flow_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Query the Prefect API for flow runs. Only flow runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flow runs\n            limit: limit for the flow run query\n            offset: offset for the flow run query\n\n        Returns:\n            a list of Flow Run model representations\n                of the flow runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = await self._client.post(\"/flow_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    async def set_flow_run_state(\n        self,\n        flow_run_id: UUID,\n        state: \"prefect.states.State\",\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a flow run.\n\n        Args:\n            flow_run_id: the id of the flow run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.flow_run_id = flow_run_id\n        state_create.state_details.transition_id = uuid4()\n        try:\n            response = await self._client.post(\n                f\"/flow_runs/{flow_run_id}/set_state\",\n                json=dict(state=state_create.dict(json_compatible=True), force=force),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_flow_run_states(\n        self, flow_run_id: UUID\n    ) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a flow run\n\n        Args:\n            flow_run_id: the id of the flow run\n\n        Returns:\n            a list of State model representations\n                of the flow run states\n        \"\"\"\n        response = await self._client.get(\n            \"/flow_run_states/\", params=dict(flow_run_id=str(flow_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n\n    async def set_task_run_name(self, task_run_id: UUID, name: str):\n        task_run_data = TaskRunUpdate(name=name)\n        return await self._client.patch(\n            f\"/task_runs/{task_run_id}\",\n            json=task_run_data.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def create_task_run(\n        self,\n        task: \"TaskObject[P, R]\",\n        flow_run_id: Optional[UUID],\n        dynamic_key: str,\n        name: Optional[str] = None,\n        extra_tags: Optional[Iterable[str]] = None,\n        state: Optional[prefect.states.State[R]] = None,\n        task_inputs: Optional[\n            Dict[\n                str,\n                List[\n                    Union[\n                        TaskRunResult,\n                        Parameter,\n                        Constant,\n                    ]\n                ],\n            ]\n        ] = None,\n    ) -&gt; TaskRun:\n        \"\"\"\n        Create a task run\n\n        Args:\n            task: The Task to run\n            flow_run_id: The flow run id with which to associate the task run\n            dynamic_key: A key unique to this particular run of a Task within the flow\n            name: An optional name for the task run\n            extra_tags: an optional list of extra tags to apply to the task run in\n                addition to `task.tags`\n            state: The initial state for the run. If not provided, defaults to\n                `Pending` for now. Should always be a `Scheduled` type.\n            task_inputs: the set of inputs passed to the task\n\n        Returns:\n            The created task run.\n        \"\"\"\n        tags = set(task.tags).union(extra_tags or [])\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        task_run_data = TaskRunCreate(\n            name=name,\n            flow_run_id=flow_run_id,\n            task_key=task.task_key,\n            dynamic_key=dynamic_key,\n            tags=list(tags),\n            task_version=task.version,\n            empirical_policy=TaskRunPolicy(\n                retries=task.retries,\n                retry_delay=task.retry_delay_seconds,\n                retry_jitter_factor=task.retry_jitter_factor,\n            ),\n            state=state.to_state_create(),\n            task_inputs=task_inputs or {},\n        )\n\n        response = await self._client.post(\n            \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n        )\n        return TaskRun.parse_obj(response.json())\n\n    async def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n        \"\"\"\n        Query the Prefect API for a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n\n        Returns:\n            a Task Run model representation of the task run\n        \"\"\"\n        response = await self._client.get(f\"/task_runs/{task_run_id}\")\n        return TaskRun.parse_obj(response.json())\n\n    async def read_task_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        sort: TaskRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[TaskRun]:\n        \"\"\"\n        Query the Prefect API for task runs. Only task runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            sort: sort criteria for the task runs\n            limit: a limit for the task run query\n            offset: an offset for the task run query\n\n        Returns:\n            a list of Task Run model representations\n                of the task runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/task_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[TaskRun], response.json())\n\n    async def delete_task_run(self, task_run_id: UUID) -&gt; None:\n        \"\"\"\n        Delete a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/task_runs/{task_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def set_task_run_state(\n        self,\n        task_run_id: UUID,\n        state: prefect.states.State,\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a task run.\n\n        Args:\n            task_run_id: the id of the task run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.task_run_id = task_run_id\n        response = await self._client.post(\n            f\"/task_runs/{task_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n        return OrchestrationResult.parse_obj(response.json())\n\n    async def read_task_run_states(\n        self, task_run_id: UUID\n    ) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a task run\n\n        Args:\n            task_run_id: the id of the task run\n\n        Returns:\n            a list of State model representations of the task run states\n        \"\"\"\n        response = await self._client.get(\n            \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n\n    async def create_logs(self, logs: Iterable[Union[LogCreate, dict]]) -&gt; None:\n        \"\"\"\n        Create logs for a flow or task run\n\n        Args:\n            logs: An iterable of `LogCreate` objects or already json-compatible dicts\n        \"\"\"\n        serialized_logs = [\n            log.dict(json_compatible=True) if isinstance(log, LogCreate) else log\n            for log in logs\n        ]\n        await self._client.post(\"/logs/\", json=serialized_logs)\n\n    async def create_flow_run_notification_policy(\n        self,\n        block_document_id: UUID,\n        is_active: bool = True,\n        tags: List[str] = None,\n        state_names: List[str] = None,\n        message_template: Optional[str] = None,\n    ) -&gt; UUID:\n        \"\"\"\n        Create a notification policy for flow runs\n\n        Args:\n            block_document_id: The block document UUID\n            is_active: Whether the notification policy is active\n            tags: List of flow tags\n            state_names: List of state names\n            message_template: Notification message template\n        \"\"\"\n        if tags is None:\n            tags = []\n        if state_names is None:\n            state_names = []\n\n        policy = FlowRunNotificationPolicyCreate(\n            block_document_id=block_document_id,\n            is_active=is_active,\n            tags=tags,\n            state_names=state_names,\n            message_template=message_template,\n        )\n        response = await self._client.post(\n            \"/flow_run_notification_policies/\",\n            json=policy.dict(json_compatible=True),\n        )\n\n        policy_id = response.json().get(\"id\")\n        if not policy_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        return UUID(policy_id)\n\n    async def delete_flow_run_notification_policy(\n        self,\n        id: UUID,\n    ) -&gt; None:\n        \"\"\"\n        Delete a flow run notification policy by id.\n\n        Args:\n            id: UUID of the flow run notification policy to delete.\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        try:\n            await self._client.delete(f\"/flow_run_notification_policies/{id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def update_flow_run_notification_policy(\n        self,\n        id: UUID,\n        block_document_id: Optional[UUID] = None,\n        is_active: Optional[bool] = None,\n        tags: Optional[List[str]] = None,\n        state_names: Optional[List[str]] = None,\n        message_template: Optional[str] = None,\n    ) -&gt; None:\n        \"\"\"\n        Update a notification policy for flow runs\n\n        Args:\n            id: UUID of the notification policy\n            block_document_id: The block document UUID\n            is_active: Whether the notification policy is active\n            tags: List of flow tags\n            state_names: List of state names\n            message_template: Notification message template\n        Raises:\n            prefect.exceptions.ObjectNotFound: If request returns 404\n            httpx.RequestError: If requests fails\n        \"\"\"\n        params = {}\n        if block_document_id is not None:\n            params[\"block_document_id\"] = block_document_id\n        if is_active is not None:\n            params[\"is_active\"] = is_active\n        if tags is not None:\n            params[\"tags\"] = tags\n        if state_names is not None:\n            params[\"state_names\"] = state_names\n        if message_template is not None:\n            params[\"message_template\"] = message_template\n\n        policy = FlowRunNotificationPolicyUpdate(**params)\n\n        try:\n            await self._client.patch(\n                f\"/flow_run_notification_policies/{id}\",\n                json=policy.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_flow_run_notification_policies(\n        self,\n        flow_run_notification_policy_filter: FlowRunNotificationPolicyFilter,\n        limit: Optional[int] = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRunNotificationPolicy]:\n        \"\"\"\n        Query the Prefect API for flow run notification policies. Only policies matching all criteria will\n        be returned.\n\n        Args:\n            flow_run_notification_policy_filter: filter criteria for notification policies\n            limit: a limit for the notification policies query\n            offset: an offset for the notification policies query\n\n        Returns:\n            a list of FlowRunNotificationPolicy model representations\n                of the notification policies\n        \"\"\"\n        body = {\n            \"flow_run_notification_policy_filter\": (\n                flow_run_notification_policy_filter.dict(json_compatible=True)\n                if flow_run_notification_policy_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\n            \"/flow_run_notification_policies/filter\", json=body\n        )\n        return pydantic.parse_obj_as(List[FlowRunNotificationPolicy], response.json())\n\n    async def read_logs(\n        self,\n        log_filter: LogFilter = None,\n        limit: int = None,\n        offset: int = None,\n        sort: LogSort = LogSort.TIMESTAMP_ASC,\n    ) -&gt; List[Log]:\n        \"\"\"\n        Read flow and task run logs.\n        \"\"\"\n        body = {\n            \"logs\": log_filter.dict(json_compatible=True) if log_filter else None,\n            \"limit\": limit,\n            \"offset\": offset,\n            \"sort\": sort,\n        }\n\n        response = await self._client.post(\"/logs/filter\", json=body)\n        return pydantic.parse_obj_as(List[Log], response.json())\n\n    async def resolve_datadoc(self, datadoc: DataDocument) -&gt; Any:\n        \"\"\"\n        Recursively decode possibly nested data documents.\n\n        \"server\" encoded documents will be retrieved from the server.\n\n        Args:\n            datadoc: The data document to resolve\n\n        Returns:\n            a decoded object, the innermost data\n        \"\"\"\n        if not isinstance(datadoc, DataDocument):\n            raise TypeError(\n                f\"`resolve_datadoc` received invalid type {type(datadoc).__name__}\"\n            )\n\n        async def resolve_inner(data):\n            if isinstance(data, bytes):\n                try:\n                    data = DataDocument.parse_raw(data)\n                except pydantic.ValidationError:\n                    return data\n\n            if isinstance(data, DataDocument):\n                return await resolve_inner(data.decode())\n\n            return data\n\n        return await resolve_inner(datadoc)\n\n    async def send_worker_heartbeat(\n        self,\n        work_pool_name: str,\n        worker_name: str,\n        heartbeat_interval_seconds: Optional[float] = None,\n    ):\n        \"\"\"\n        Sends a worker heartbeat for a given work pool.\n\n        Args:\n            work_pool_name: The name of the work pool to heartbeat against.\n            worker_name: The name of the worker sending the heartbeat.\n        \"\"\"\n        await self._client.post(\n            f\"/work_pools/{work_pool_name}/workers/heartbeat\",\n            json={\n                \"name\": worker_name,\n                \"heartbeat_interval_seconds\": heartbeat_interval_seconds,\n            },\n        )\n\n    async def read_workers_for_work_pool(\n        self,\n        work_pool_name: str,\n        worker_filter: Optional[WorkerFilter] = None,\n        offset: Optional[int] = None,\n        limit: Optional[int] = None,\n    ) -&gt; List[Worker]:\n        \"\"\"\n        Reads workers for a given work pool.\n\n        Args:\n            work_pool_name: The name of the work pool for which to get\n                member workers.\n            worker_filter: Criteria by which to filter workers.\n            limit: Limit for the worker query.\n            offset: Limit for the worker query.\n        \"\"\"\n        response = await self._client.post(\n            f\"/work_pools/{work_pool_name}/workers/filter\",\n            json={\n                \"worker_filter\": (\n                    worker_filter.dict(json_compatible=True, exclude_unset=True)\n                    if worker_filter\n                    else None\n                ),\n                \"offset\": offset,\n                \"limit\": limit,\n            },\n        )\n\n        return pydantic.parse_obj_as(List[Worker], response.json())\n\n    async def read_work_pool(self, work_pool_name: str) -&gt; WorkPool:\n        \"\"\"\n        Reads information for a given work pool\n\n        Args:\n            work_pool_name: The name of the work pool to for which to get\n                information.\n\n        Returns:\n            Information about the requested work pool.\n        \"\"\"\n        try:\n            response = await self._client.get(f\"/work_pools/{work_pool_name}\")\n            return pydantic.parse_obj_as(WorkPool, response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_work_pools(\n        self,\n        limit: Optional[int] = None,\n        offset: int = 0,\n        work_pool_filter: Optional[WorkPoolFilter] = None,\n    ) -&gt; List[WorkPool]:\n        \"\"\"\n        Reads work pools.\n\n        Args:\n            limit: Limit for the work pool query.\n            offset: Offset for the work pool query.\n            work_pool_filter: Criteria by which to filter work pools.\n\n        Returns:\n            A list of work pools.\n        \"\"\"\n\n        body = {\n            \"limit\": limit,\n            \"offset\": offset,\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n        }\n        response = await self._client.post(\"/work_pools/filter\", json=body)\n        return pydantic.parse_obj_as(List[WorkPool], response.json())\n\n    async def create_work_pool(\n        self,\n        work_pool: WorkPoolCreate,\n        overwrite: bool = False,\n    ) -&gt; WorkPool:\n        \"\"\"\n        Creates a work pool with the provided configuration.\n\n        Args:\n            work_pool: Desired configuration for the new work pool.\n            overwrite: Whether to overwrite an existing work pool with the same name.\n\n        Returns:\n            Information about the newly created work pool.\n        \"\"\"\n        try:\n            response = await self._client.post(\n                \"/work_pools/\",\n                json=work_pool.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_409_CONFLICT:\n                if overwrite:\n                    existing_work_pool = await self.read_work_pool(\n                        work_pool_name=work_pool.name\n                    )\n                    if existing_work_pool.type != work_pool.type:\n                        warnings.warn(\n                            \"Overwriting work pool type is not supported. Ignoring provided type.\",\n                            category=UserWarning,\n                        )\n                    await self.update_work_pool(\n                        work_pool_name=work_pool.name,\n                        work_pool=WorkPoolUpdate.parse_obj(\n                            work_pool.dict(exclude={\"name\", \"type\"})\n                        ),\n                    )\n                    response = await self._client.get(f\"/work_pools/{work_pool.name}\")\n                else:\n                    raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n            else:\n                raise\n\n        return pydantic.parse_obj_as(WorkPool, response.json())\n\n    async def update_work_pool(\n        self,\n        work_pool_name: str,\n        work_pool: WorkPoolUpdate,\n    ):\n        \"\"\"\n        Updates a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool to update.\n            work_pool: Fields to update in the work pool.\n        \"\"\"\n        try:\n            await self._client.patch(\n                f\"/work_pools/{work_pool_name}\",\n                json=work_pool.dict(json_compatible=True, exclude_unset=True),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_work_pool(\n        self,\n        work_pool_name: str,\n    ):\n        \"\"\"\n        Deletes a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool to delete.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/work_pools/{work_pool_name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_work_queues(\n        self,\n        work_pool_name: Optional[str] = None,\n        work_queue_filter: Optional[WorkQueueFilter] = None,\n        limit: Optional[int] = None,\n        offset: Optional[int] = None,\n    ) -&gt; List[WorkQueue]:\n        \"\"\"\n        Retrieves queues for a work pool.\n\n        Args:\n            work_pool_name: Name of the work pool for which to get queues.\n            work_queue_filter: Criteria by which to filter queues.\n            limit: Limit for the queue query.\n            offset: Limit for the queue query.\n\n        Returns:\n            List of queues for the specified work pool.\n        \"\"\"\n        json = {\n            \"work_queues\": (\n                work_queue_filter.dict(json_compatible=True, exclude_unset=True)\n                if work_queue_filter\n                else None\n            ),\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        if work_pool_name:\n            try:\n                response = await self._client.post(\n                    f\"/work_pools/{work_pool_name}/queues/filter\",\n                    json=json,\n                )\n            except httpx.HTTPStatusError as e:\n                if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                    raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n                else:\n                    raise\n        else:\n            response = await self._client.post(\"/work_queues/filter\", json=json)\n\n        return pydantic.parse_obj_as(List[WorkQueue], response.json())\n\n    async def get_scheduled_flow_runs_for_deployments(\n        self,\n        deployment_ids: List[UUID],\n        scheduled_before: Optional[datetime.datetime] = None,\n        limit: Optional[int] = None,\n    ):\n        body: Dict[str, Any] = dict(deployment_ids=[str(id) for id in deployment_ids])\n        if scheduled_before:\n            body[\"scheduled_before\"] = str(scheduled_before)\n        if limit:\n            body[\"limit\"] = limit\n\n        response = await self._client.post(\n            \"/deployments/get_scheduled_flow_runs\",\n            json=body,\n        )\n\n        return pydantic.parse_obj_as(List[FlowRunResponse], response.json())\n\n    async def get_scheduled_flow_runs_for_work_pool(\n        self,\n        work_pool_name: str,\n        work_queue_names: Optional[List[str]] = None,\n        scheduled_before: Optional[datetime.datetime] = None,\n    ) -&gt; List[WorkerFlowRunResponse]:\n        \"\"\"\n        Retrieves scheduled flow runs for the provided set of work pool queues.\n\n        Args:\n            work_pool_name: The name of the work pool that the work pool\n                queues are associated with.\n            work_queue_names: The names of the work pool queues from which\n                to get scheduled flow runs.\n            scheduled_before: Datetime used to filter returned flow runs. Flow runs\n                scheduled for after the given datetime string will not be returned.\n\n        Returns:\n            A list of worker flow run responses containing information about the\n            retrieved flow runs.\n        \"\"\"\n        body: Dict[str, Any] = {}\n        if work_queue_names is not None:\n            body[\"work_queue_names\"] = list(work_queue_names)\n        if scheduled_before:\n            body[\"scheduled_before\"] = str(scheduled_before)\n\n        response = await self._client.post(\n            f\"/work_pools/{work_pool_name}/get_scheduled_flow_runs\",\n            json=body,\n        )\n        return pydantic.parse_obj_as(List[WorkerFlowRunResponse], response.json())\n\n    async def create_artifact(\n        self,\n        artifact: ArtifactCreate,\n    ) -&gt; Artifact:\n        \"\"\"\n        Creates an artifact with the provided configuration.\n\n        Args:\n            artifact: Desired configuration for the new artifact.\n        Returns:\n            Information about the newly created artifact.\n        \"\"\"\n\n        response = await self._client.post(\n            \"/artifacts/\",\n            json=artifact.dict(json_compatible=True, exclude_unset=True),\n        )\n\n        return pydantic.parse_obj_as(Artifact, response.json())\n\n    async def read_artifacts(\n        self,\n        *,\n        artifact_filter: ArtifactFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        sort: ArtifactSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[Artifact]:\n        \"\"\"\n        Query the Prefect API for artifacts. Only artifacts matching all criteria will\n        be returned.\n        Args:\n            artifact_filter: filter criteria for artifacts\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            sort: sort criteria for the artifacts\n            limit: limit for the artifact query\n            offset: offset for the artifact query\n        Returns:\n            a list of Artifact model representations of the artifacts\n        \"\"\"\n        body = {\n            \"artifacts\": (\n                artifact_filter.dict(json_compatible=True) if artifact_filter else None\n            ),\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/artifacts/filter\", json=body)\n        return pydantic.parse_obj_as(List[Artifact], response.json())\n\n    async def read_latest_artifacts(\n        self,\n        *,\n        artifact_filter: ArtifactCollectionFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        sort: ArtifactCollectionSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[ArtifactCollection]:\n        \"\"\"\n        Query the Prefect API for artifacts. Only artifacts matching all criteria will\n        be returned.\n        Args:\n            artifact_filter: filter criteria for artifacts\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            sort: sort criteria for the artifacts\n            limit: limit for the artifact query\n            offset: offset for the artifact query\n        Returns:\n            a list of Artifact model representations of the artifacts\n        \"\"\"\n        body = {\n            \"artifacts\": (\n                artifact_filter.dict(json_compatible=True) if artifact_filter else None\n            ),\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = await self._client.post(\"/artifacts/latest/filter\", json=body)\n        return pydantic.parse_obj_as(List[ArtifactCollection], response.json())\n\n    async def delete_artifact(self, artifact_id: UUID) -&gt; None:\n        \"\"\"\n        Deletes an artifact with the provided id.\n\n        Args:\n            artifact_id: The id of the artifact to delete.\n        \"\"\"\n        try:\n            await self._client.delete(f\"/artifacts/{artifact_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def create_variable(self, variable: VariableCreate) -&gt; Variable:\n        \"\"\"\n        Creates an variable with the provided configuration.\n\n        Args:\n            variable: Desired configuration for the new variable.\n        Returns:\n            Information about the newly created variable.\n        \"\"\"\n        response = await self._client.post(\n            \"/variables/\",\n            json=variable.dict(json_compatible=True, exclude_unset=True),\n        )\n        return Variable(**response.json())\n\n    async def update_variable(self, variable: VariableUpdate) -&gt; None:\n        \"\"\"\n        Updates a variable with the provided configuration.\n\n        Args:\n            variable: Desired configuration for the updated variable.\n        Returns:\n            Information about the updated variable.\n        \"\"\"\n        await self._client.patch(\n            f\"/variables/name/{variable.name}\",\n            json=variable.dict(json_compatible=True, exclude_unset=True),\n        )\n\n    async def read_variable_by_name(self, name: str) -&gt; Optional[Variable]:\n        \"\"\"Reads a variable by name. Returns None if no variable is found.\"\"\"\n        try:\n            response = await self._client.get(f\"/variables/name/{name}\")\n            return Variable(**response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                return None\n            else:\n                raise\n\n    async def delete_variable_by_name(self, name: str):\n        \"\"\"Deletes a variable by name.\"\"\"\n        try:\n            await self._client.delete(f\"/variables/name/{name}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_variables(self, limit: int = None) -&gt; List[Variable]:\n        \"\"\"Reads all variables.\"\"\"\n        response = await self._client.post(\"/variables/filter\", json={\"limit\": limit})\n        return pydantic.parse_obj_as(List[Variable], response.json())\n\n    async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n        \"\"\"Reads worker metadata stored in Prefect collection registry.\"\"\"\n        response = await self._client.get(\"collections/views/aggregate-worker-metadata\")\n        response.raise_for_status()\n        return response.json()\n\n    async def increment_concurrency_slots(\n        self, names: List[str], slots: int, mode: str\n    ) -&gt; httpx.Response:\n        return await self._client.post(\n            \"/v2/concurrency_limits/increment\",\n            json={\"names\": names, \"slots\": slots, \"mode\": mode},\n        )\n\n    async def release_concurrency_slots(\n        self, names: List[str], slots: int, occupancy_seconds: float\n    ) -&gt; httpx.Response:\n        return await self._client.post(\n            \"/v2/concurrency_limits/decrement\",\n            json={\n                \"names\": names,\n                \"slots\": slots,\n                \"occupancy_seconds\": occupancy_seconds,\n            },\n        )\n\n    async def create_global_concurrency_limit(\n        self, concurrency_limit: GlobalConcurrencyLimitCreate\n    ) -&gt; UUID:\n        response = await self._client.post(\n            \"/v2/concurrency_limits/\",\n            json=concurrency_limit.dict(json_compatible=True, exclude_unset=True),\n        )\n        return UUID(response.json()[\"id\"])\n\n    async def update_global_concurrency_limit(\n        self, name: str, concurrency_limit: GlobalConcurrencyLimitUpdate\n    ) -&gt; httpx.Response:\n        try:\n            response = await self._client.patch(\n                f\"/v2/concurrency_limits/{name}\",\n                json=concurrency_limit.dict(json_compatible=True, exclude_unset=True),\n            )\n            return response\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def delete_global_concurrency_limit_by_name(\n        self, name: str\n    ) -&gt; httpx.Response:\n        try:\n            response = await self._client.delete(f\"/v2/concurrency_limits/{name}\")\n            return response\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_global_concurrency_limit_by_name(\n        self, name: str\n    ) -&gt; GlobalConcurrencyLimitResponse:\n        try:\n            response = await self._client.get(f\"/v2/concurrency_limits/{name}\")\n            return GlobalConcurrencyLimitResponse.parse_obj(response.json())\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n    async def read_global_concurrency_limits(\n        self, limit: int = 10, offset: int = 0\n    ) -&gt; List[GlobalConcurrencyLimitResponse]:\n        response = await self._client.post(\n            \"/v2/concurrency_limits/filter\",\n            json={\n                \"limit\": limit,\n                \"offset\": offset,\n            },\n        )\n        return pydantic.parse_obj_as(\n            List[GlobalConcurrencyLimitResponse], response.json()\n        )\n\n    async def create_flow_run_input(\n        self, flow_run_id: UUID, key: str, value: str, sender: Optional[str] = None\n    ):\n        \"\"\"\n        Creates a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n            value: The input value.\n            sender: The sender of the input.\n        \"\"\"\n\n        # Initialize the input to ensure that the key is valid.\n        FlowRunInput(flow_run_id=flow_run_id, key=key, value=value)\n\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/input\",\n            json={\"key\": key, \"value\": value, \"sender\": sender},\n        )\n        response.raise_for_status()\n\n    async def filter_flow_run_input(\n        self, flow_run_id: UUID, key_prefix: str, limit: int, exclude_keys: Set[str]\n    ) -&gt; List[FlowRunInput]:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/input/filter\",\n            json={\n                \"prefix\": key_prefix,\n                \"limit\": limit,\n                \"exclude_keys\": list(exclude_keys),\n            },\n        )\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[FlowRunInput], response.json())\n\n    async def read_flow_run_input(self, flow_run_id: UUID, key: str) -&gt; str:\n        \"\"\"\n        Reads a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n        \"\"\"\n        response = await self._client.get(f\"/flow_runs/{flow_run_id}/input/{key}\")\n        response.raise_for_status()\n        return response.content.decode()\n\n    async def delete_flow_run_input(self, flow_run_id: UUID, key: str):\n        \"\"\"\n        Deletes a flow run input.\n\n        Args:\n            flow_run_id: The flow run id.\n            key: The input key.\n        \"\"\"\n        response = await self._client.delete(f\"/flow_runs/{flow_run_id}/input/{key}\")\n        response.raise_for_status()\n\n    def _raise_for_unsupported_automations(self) -&gt; NoReturn:\n        if not PREFECT_EXPERIMENTAL_EVENTS:\n            raise RuntimeError(\n                \"The current server and client configuration does not support \"\n                \"events.  Enable experimental events support with the \"\n                \"PREFECT_EXPERIMENTAL_EVENTS setting.\"\n            )\n        else:\n            raise RuntimeError(\n                \"The current server and client configuration does not support \"\n                \"automations.  Enable experimental automations with the \"\n                \"PREFECT_API_SERVICES_TRIGGERS_ENABLED setting.\"\n            )\n\n    async def create_automation(self, automation: AutomationCore) -&gt; UUID:\n        \"\"\"Creates an automation in Prefect Cloud.\"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.post(\n            \"/automations/\",\n            json=automation.dict(json_compatible=True),\n        )\n\n        return UUID(response.json()[\"id\"])\n\n    async def update_automation(self, automation_id: UUID, automation: AutomationCore):\n        \"\"\"Updates an automation in Prefect Cloud.\"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n        response = await self._client.put(\n            f\"/automations/{automation_id}\",\n            json=automation.dict(json_compatible=True, exclude_unset=True),\n        )\n        response.raise_for_status\n\n    async def read_automations(self) -&gt; List[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.post(\"/automations/filter\")\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def find_automation(\n        self, id_or_name: Union[str, UUID], exit_if_not_found: bool = True\n    ) -&gt; Optional[Automation]:\n        if isinstance(id_or_name, str):\n            try:\n                id = UUID(id_or_name)\n            except ValueError:\n                id = None\n        elif isinstance(id_or_name, UUID):\n            id = id_or_name\n\n        if id:\n            try:\n                automation = await self.read_automation(id)\n                return automation\n            except prefect.exceptions.HTTPStatusError as e:\n                if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                    raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n\n        automations = await self.read_automations()\n\n        # Look for it by an exact name\n        for automation in automations:\n            if automation.name == id_or_name:\n                return automation\n\n        # Look for it by a case-insensitive name\n        for automation in automations:\n            if automation.name.lower() == id_or_name.lower():\n                return automation\n\n        return None\n\n    async def read_automation(self, automation_id: UUID) -&gt; Optional[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.get(f\"/automations/{automation_id}\")\n        if response.status_code == 404:\n            return None\n        response.raise_for_status()\n        return Automation.parse_obj(response.json())\n\n    async def read_automations_by_name(self, name: str) -&gt; List[Automation]:\n        \"\"\"\n        Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.\n\n        Args:\n            name: the name of the automation to query\n\n        Returns:\n            a list of Automation model representations of the automations\n        \"\"\"\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n        automation_filter = filters.AutomationFilter(name=dict(any_=[name]))\n\n        response = await self._client.post(\n            \"/automations/filter\",\n            json={\n                \"sort\": sorting.AutomationSort.UPDATED_DESC,\n                \"automations\": automation_filter.dict(json_compatible=True)\n                if automation_filter\n                else None,\n            },\n        )\n\n        response.raise_for_status()\n\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def pause_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.patch(\n            f\"/automations/{automation_id}\", json={\"enabled\": False}\n        )\n        response.raise_for_status()\n\n    async def resume_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.patch(\n            f\"/automations/{automation_id}\", json={\"enabled\": True}\n        )\n        response.raise_for_status()\n\n    async def delete_automation(self, automation_id: UUID):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.delete(f\"/automations/{automation_id}\")\n        if response.status_code == 404:\n            return\n\n        response.raise_for_status()\n\n    async def read_resource_related_automations(\n        self, resource_id: str\n    ) -&gt; List[Automation]:\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        response = await self._client.get(f\"/automations/related-to/{resource_id}\")\n        response.raise_for_status()\n        return pydantic.parse_obj_as(List[Automation], response.json())\n\n    async def delete_resource_owned_automations(self, resource_id: str):\n        if not self.server_type.supports_automations():\n            self._raise_for_unsupported_automations()\n\n        await self._client.delete(f\"/automations/owned-by/{resource_id}\")\n\n    async def __aenter__(self):\n        \"\"\"\n        Start the client.\n\n        If the client is already started, this will raise an exception.\n\n        If the client is already closed, this will raise an exception. Use a new client\n        instance instead.\n        \"\"\"\n        if self._closed:\n            # httpx.AsyncClient does not allow reuse so we will not either.\n            raise RuntimeError(\n                \"The client cannot be started again after closing. \"\n                \"Retrieve a new client with `get_client()` instead.\"\n            )\n\n        if self._started:\n            # httpx.AsyncClient does not allow reentrancy so we will not either.\n            raise RuntimeError(\"The client cannot be started more than once.\")\n\n        self._loop = asyncio.get_running_loop()\n        await self._exit_stack.__aenter__()\n\n        # Enter a lifespan context if using an ephemeral application.\n        # See https://github.com/encode/httpx/issues/350\n        if self._ephemeral_app and self.manage_lifespan:\n            self._ephemeral_lifespan = await self._exit_stack.enter_async_context(\n                app_lifespan_context(self._ephemeral_app)\n            )\n\n        if self._ephemeral_app:\n            self.logger.debug(\n                \"Using ephemeral application with database at \"\n                f\"{PREFECT_API_DATABASE_CONNECTION_URL.value()}\"\n            )\n        else:\n            self.logger.debug(f\"Connecting to API at {self.api_url}\")\n\n        # Enter the httpx client's context\n        await self._exit_stack.enter_async_context(self._client)\n\n        self._started = True\n\n        return self\n\n    async def __aexit__(self, *exc_info):\n        \"\"\"\n        Shutdown the client.\n        \"\"\"\n        self._closed = True\n        return await self._exit_stack.__aexit__(*exc_info)\n\n    def __enter__(self):\n        raise RuntimeError(\n            \"The `PrefectClient` must be entered with an async context. Use 'async \"\n            \"with PrefectClient(...)' not 'with PrefectClient(...)'\"\n        )\n\n    def __exit__(self, *_):\n        assert False, \"This should never be called but must be defined for __enter__\"\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.api_url","title":"<code>api_url: httpx.URL</code>  <code>property</code>","text":"<p>Get the base URL for the API.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.api_healthcheck","title":"<code>api_healthcheck</code>  <code>async</code>","text":"<p>Attempts to connect to the API and returns the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def api_healthcheck(self) -&gt; Optional[Exception]:\n    \"\"\"\n    Attempts to connect to the API and returns the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    try:\n        await self._client.get(\"/health\")\n        return None\n    except Exception as exc:\n        return exc\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.hello","title":"<code>hello</code>  <code>async</code>","text":"<p>Send a GET request to /hello for testing purposes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def hello(self) -&gt; httpx.Response:\n    \"\"\"\n    Send a GET request to /hello for testing purposes.\n    \"\"\"\n    return await self._client.get(\"/hello\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>a Flow object</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow: a [Flow][prefect.flows.Flow] object\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    return await self.create_flow_from_name(flow.name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_from_name","title":"<code>create_flow_from_name</code>  <code>async</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of the new flow</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow_name: the name of the new flow\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    flow_data = FlowCreate(name=flow_name)\n    response = await self._client.post(\n        \"/flows/\", json=flow_data.dict(json_compatible=True)\n    )\n\n    flow_id = response.json().get(\"id\")\n    if not flow_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    # Return the id of the created flow\n    return UUID(flow_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_id</code> <code>UUID</code> <p>the flow ID of interest</p> required <p>Returns:</p> Type Description <code>Flow</code> <p>a Flow model representation of the flow</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow(self, flow_id: UUID) -&gt; Flow:\n    \"\"\"\n    Query the Prefect API for a flow by id.\n\n    Args:\n        flow_id: the flow ID of interest\n\n    Returns:\n        a [Flow model][prefect.client.schemas.objects.Flow] representation of the flow\n    \"\"\"\n    response = await self._client.get(f\"/flows/{flow_id}\")\n    return Flow.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Query the Prefect API for flows. Only flows matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowSort</code> <p>sort criteria for the flows</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[Flow]</code> <p>a list of Flow model representations of the flows</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flows(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[Flow]:\n    \"\"\"\n    Query the Prefect API for flows. Only flows matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flows\n        limit: limit for the flow query\n        offset: offset for the flow query\n\n    Returns:\n        a list of Flow model representations of the flows\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/flows/filter\", json=body)\n    return pydantic.parse_obj_as(List[Flow], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow by name.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of a flow</p> required <p>Returns:</p> Type Description <code>Flow</code> <p>a fully hydrated Flow model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_by_name(\n    self,\n    flow_name: str,\n) -&gt; Flow:\n    \"\"\"\n    Query the Prefect API for a flow by name.\n\n    Args:\n        flow_name: the name of a flow\n\n    Returns:\n        a fully hydrated Flow model\n    \"\"\"\n    response = await self._client.get(f\"/flows/name/{flow_name}\")\n    return Flow.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_from_deployment","title":"<code>create_flow_run_from_deployment</code>  <code>async</code>","text":"<p>Create a flow run for a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>The deployment ID to create the flow run from</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run. Merged with the deployment defaults</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>state</code> <code>State</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>name</code> <code>str</code> <p>An optional name for the flow run. If not provided, the server will generate a name.</p> <code>None</code> <code>tags</code> <code>Iterable[str]</code> <p>An optional iterable of tags to apply to the flow run; these tags are merged with the deployment's tags.</p> <code>None</code> <code>idempotency_key</code> <code>str</code> <p>Optional idempotency key for creation of the flow run. If the key matches the key of an existing flow run, the existing run will be returned instead of creating a new one.</p> <code>None</code> <code>parent_task_run_id</code> <code>UUID</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>work_queue_name</code> <code>str</code> <p>An optional work queue name to add this run to. If not provided, will default to the deployment's set work queue.  If one is provided that does not exist, a new work queue will be created within the deployment's work pool.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Optional variables that will be supplied to the flow run job.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_from_deployment(\n    self,\n    deployment_id: UUID,\n    *,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    state: prefect.states.State = None,\n    name: str = None,\n    tags: Iterable[str] = None,\n    idempotency_key: str = None,\n    parent_task_run_id: UUID = None,\n    work_queue_name: str = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a deployment.\n\n    Args:\n        deployment_id: The deployment ID to create the flow run from\n        parameters: Parameter overrides for this flow run. Merged with the\n            deployment defaults\n        context: Optional run context data\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n        name: An optional name for the flow run. If not provided, the server will\n            generate a name.\n        tags: An optional iterable of tags to apply to the flow run; these tags\n            are merged with the deployment's tags.\n        idempotency_key: Optional idempotency key for creation of the flow run.\n            If the key matches the key of an existing flow run, the existing run will\n            be returned instead of creating a new one.\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        work_queue_name: An optional work queue name to add this run to. If not provided,\n            will default to the deployment's set work queue.  If one is provided that does not\n            exist, a new work queue will be created within the deployment's work pool.\n        job_variables: Optional variables that will be supplied to the flow run job.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n    state = state or prefect.states.Scheduled()\n    tags = tags or []\n\n    flow_run_create = DeploymentFlowRunCreate(\n        parameters=parameters,\n        context=context,\n        state=state.to_state_create(),\n        tags=tags,\n        name=name,\n        idempotency_key=idempotency_key,\n        parent_task_run_id=parent_task_run_id,\n        job_variables=job_variables,\n    )\n\n    # done separately to avoid including this field in payloads sent to older API versions\n    if work_queue_name:\n        flow_run_create.work_queue_name = work_queue_name\n\n    response = await self._client.post(\n        f\"/deployments/{deployment_id}/create_flow_run\",\n        json=flow_run_create.dict(json_compatible=True, exclude_unset=True),\n    )\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Create a flow run for a flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>The flow model to create the flow run for</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow run</p> <code>None</code> <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run.</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>a list of tags to apply to this flow run</p> <code>None</code> <code>parent_task_run_id</code> <code>Optional[UUID]</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>state</code> <code>Optional[State]</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run(\n    self,\n    flow: \"FlowObject\",\n    name: Optional[str] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    tags: Optional[Iterable[str]] = None,\n    parent_task_run_id: Optional[UUID] = None,\n    state: Optional[\"prefect.states.State\"] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a flow.\n\n    Args:\n        flow: The flow model to create the flow run for\n        name: An optional name for the flow run\n        parameters: Parameter overrides for this flow run.\n        context: Optional run context data\n        tags: a list of tags to apply to this flow run\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    # Retrieve the flow id\n    flow_id = await self.create_flow(flow)\n\n    flow_run_create = FlowRunCreate(\n        flow_id=flow_id,\n        flow_version=flow.version,\n        name=name,\n        parameters=parameters,\n        context=context,\n        tags=list(tags or []),\n        parent_task_run_id=parent_task_run_id,\n        state=state.to_state_create(),\n        empirical_policy=FlowRunPolicy(\n            retries=flow.retries,\n            retry_delay=flow.retry_delay_seconds,\n        ),\n    )\n\n    flow_run_create_json = flow_run_create.dict(json_compatible=True)\n    response = await self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n    flow_run = FlowRun.parse_obj(response.json())\n\n    # Restore the parameters to the local objects to retain expectations about\n    # Python objects\n    flow_run.parameters = parameters\n\n    return flow_run\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Update a flow run's details.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The identifier for the flow run to update.</p> required <code>flow_version</code> <code>Optional[str]</code> <p>A new version string for the flow run.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of parameter values for the flow run. This will not be merged with any existing parameters.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>A new name for the flow run.</p> <code>None</code> <code>empirical_policy</code> <code>Optional[FlowRunPolicy]</code> <p>A new flow run orchestration policy. This will not be merged with any existing policy.</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>An iterable of new tags for the flow run. These will not be merged with any existing tags.</p> <code>None</code> <code>infrastructure_pid</code> <code>Optional[str]</code> <p>The id of flow run as returned by an infrastructure block.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>an <code>httpx.Response</code> object from the PATCH request</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_flow_run(\n    self,\n    flow_run_id: UUID,\n    flow_version: Optional[str] = None,\n    parameters: Optional[dict] = None,\n    name: Optional[str] = None,\n    tags: Optional[Iterable[str]] = None,\n    empirical_policy: Optional[FlowRunPolicy] = None,\n    infrastructure_pid: Optional[str] = None,\n    job_variables: Optional[dict] = None,\n) -&gt; httpx.Response:\n    \"\"\"\n    Update a flow run's details.\n\n    Args:\n        flow_run_id: The identifier for the flow run to update.\n        flow_version: A new version string for the flow run.\n        parameters: A dictionary of parameter values for the flow run. This will not\n            be merged with any existing parameters.\n        name: A new name for the flow run.\n        empirical_policy: A new flow run orchestration policy. This will not be\n            merged with any existing policy.\n        tags: An iterable of new tags for the flow run. These will not be merged with\n            any existing tags.\n        infrastructure_pid: The id of flow run as returned by an\n            infrastructure block.\n\n    Returns:\n        an `httpx.Response` object from the PATCH request\n    \"\"\"\n    params = {}\n    if flow_version is not None:\n        params[\"flow_version\"] = flow_version\n    if parameters is not None:\n        params[\"parameters\"] = parameters\n    if name is not None:\n        params[\"name\"] = name\n    if tags is not None:\n        params[\"tags\"] = tags\n    if empirical_policy is not None:\n        params[\"empirical_policy\"] = empirical_policy\n    if infrastructure_pid:\n        params[\"infrastructure_pid\"] = infrastructure_pid\n    if job_variables is not None:\n        params[\"job_variables\"] = job_variables\n\n    flow_run_data = FlowRunUpdate(**params)\n\n    return await self._client.patch(\n        f\"/flow_runs/{flow_run_id}\",\n        json=flow_run_data.dict(json_compatible=True, exclude_unset=True),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by UUID.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run UUID of interest.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run(\n    self,\n    flow_run_id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a flow run by UUID.\n\n    Args:\n        flow_run_id: The flow run UUID of interest.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_concurrency_limit","title":"<code>create_concurrency_limit</code>  <code>async</code>","text":"<p>Create a tag concurrency limit in the Prefect API. These limits govern concurrently running tasks.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <code>concurrency_limit</code> <code>int</code> <p>the maximum number of concurrent task runs for a given tag</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the concurrency limit was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the concurrency limit in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_concurrency_limit(\n    self,\n    tag: str,\n    concurrency_limit: int,\n) -&gt; UUID:\n    \"\"\"\n    Create a tag concurrency limit in the Prefect API. These limits govern concurrently\n    running tasks.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n        concurrency_limit: the maximum number of concurrent task runs for a given tag\n\n    Raises:\n        httpx.RequestError: if the concurrency limit was not created for any reason\n\n    Returns:\n        the ID of the concurrency limit in the backend\n    \"\"\"\n\n    concurrency_limit_create = ConcurrencyLimitCreate(\n        tag=tag,\n        concurrency_limit=concurrency_limit,\n    )\n    response = await self._client.post(\n        \"/concurrency_limits/\",\n        json=concurrency_limit_create.dict(json_compatible=True),\n    )\n\n    concurrency_limit_id = response.json().get(\"id\")\n\n    if not concurrency_limit_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(concurrency_limit_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_concurrency_limit_by_tag","title":"<code>read_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Read the concurrency limit set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>if the concurrency limit was not created for any reason</p> <p>Returns:</p> Type Description <p>the concurrency limit set on a specific tag</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_concurrency_limit_by_tag(\n    self,\n    tag: str,\n):\n    \"\"\"\n    Read the concurrency limit set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: if the concurrency limit was not created for any reason\n\n    Returns:\n        the concurrency limit set on a specific tag\n    \"\"\"\n    try:\n        response = await self._client.get(\n            f\"/concurrency_limits/tag/{tag}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    concurrency_limit_id = response.json().get(\"id\")\n\n    if not concurrency_limit_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    concurrency_limit = ConcurrencyLimit.parse_obj(response.json())\n    return concurrency_limit\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_concurrency_limits","title":"<code>read_concurrency_limits</code>  <code>async</code>","text":"<p>Lists concurrency limits set on task run tags.</p> <p>Parameters:</p> Name Type Description Default <code>limit</code> <code>int</code> <p>the maximum number of concurrency limits returned</p> required <code>offset</code> <code>int</code> <p>the concurrency limit query offset</p> required <p>Returns:</p> Type Description <p>a list of concurrency limits</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_concurrency_limits(\n    self,\n    limit: int,\n    offset: int,\n):\n    \"\"\"\n    Lists concurrency limits set on task run tags.\n\n    Args:\n        limit: the maximum number of concurrency limits returned\n        offset: the concurrency limit query offset\n\n    Returns:\n        a list of concurrency limits\n    \"\"\"\n\n    body = {\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/concurrency_limits/filter\", json=body)\n    return pydantic.parse_obj_as(List[ConcurrencyLimit], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.reset_concurrency_limit_by_tag","title":"<code>reset_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Resets the concurrency limit slots set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <code>slot_override</code> <code>Optional[List[Union[UUID, str]]]</code> <p>a list of task run IDs that are currently using a concurrency slot, please check that any task run IDs included in <code>slot_override</code> are currently running, otherwise those concurrency slots will never be released.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def reset_concurrency_limit_by_tag(\n    self,\n    tag: str,\n    slot_override: Optional[List[Union[UUID, str]]] = None,\n):\n    \"\"\"\n    Resets the concurrency limit slots set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n        slot_override: a list of task run IDs that are currently using a\n            concurrency slot, please check that any task run IDs included in\n            `slot_override` are currently running, otherwise those concurrency\n            slots will never be released.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    \"\"\"\n    if slot_override is not None:\n        slot_override = [str(slot) for slot in slot_override]\n\n    try:\n        await self._client.post(\n            f\"/concurrency_limits/tag/{tag}/reset\",\n            json=dict(slot_override=slot_override),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_concurrency_limit_by_tag","title":"<code>delete_concurrency_limit_by_tag</code>  <code>async</code>","text":"<p>Delete the concurrency limit set on a specific tag.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>str</code> <p>a tag the concurrency limit is applied to</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_concurrency_limit_by_tag(\n    self,\n    tag: str,\n):\n    \"\"\"\n    Delete the concurrency limit set on a specific tag.\n\n    Args:\n        tag: a tag the concurrency limit is applied to\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/concurrency_limits/tag/{tag}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_work_queue","title":"<code>create_work_queue</code>  <code>async</code>","text":"<p>Create a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>a unique name for the work queue</p> required <code>tags</code> <code>Optional[List[str]]</code> <p>will be included in the queue. This option will be removed on 2023-02-23.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>An optional description for the work queue.</p> <code>None</code> <code>is_paused</code> <code>Optional[bool]</code> <p>Whether or not the work queue is paused.</p> <code>None</code> <code>concurrency_limit</code> <code>Optional[int]</code> <p>An optional concurrency limit for the work queue.</p> <code>None</code> <code>priority</code> <code>Optional[int]</code> <p>The queue's priority. Lower values are higher priority (1 is the highest).</p> <code>None</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this queue.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectAlreadyExists</code> <p>If request returns 409</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>WorkQueue</code> <p>The created work queue</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_work_queue(\n    self,\n    name: str,\n    tags: Optional[List[str]] = None,\n    description: Optional[str] = None,\n    is_paused: Optional[bool] = None,\n    concurrency_limit: Optional[int] = None,\n    priority: Optional[int] = None,\n    work_pool_name: Optional[str] = None,\n) -&gt; WorkQueue:\n    \"\"\"\n    Create a work queue.\n\n    Args:\n        name: a unique name for the work queue\n        tags: DEPRECATED: an optional list of tags to filter on; only work scheduled with these tags\n            will be included in the queue. This option will be removed on 2023-02-23.\n        description: An optional description for the work queue.\n        is_paused: Whether or not the work queue is paused.\n        concurrency_limit: An optional concurrency limit for the work queue.\n        priority: The queue's priority. Lower values are higher priority (1 is the highest).\n        work_pool_name: The name of the work pool to use for this queue.\n\n    Raises:\n        prefect.exceptions.ObjectAlreadyExists: If request returns 409\n        httpx.RequestError: If request fails\n\n    Returns:\n        The created work queue\n    \"\"\"\n    if tags:\n        warnings.warn(\n            (\n                \"The use of tags for creating work queue filters is deprecated.\"\n                \" This option will be removed on 2023-02-23.\"\n            ),\n            DeprecationWarning,\n        )\n        filter = QueueFilter(tags=tags)\n    else:\n        filter = None\n    create_model = WorkQueueCreate(name=name, filter=filter)\n    if description is not None:\n        create_model.description = description\n    if is_paused is not None:\n        create_model.is_paused = is_paused\n    if concurrency_limit is not None:\n        create_model.concurrency_limit = concurrency_limit\n    if priority is not None:\n        create_model.priority = priority\n\n    data = create_model.dict(json_compatible=True)\n    try:\n        if work_pool_name is not None:\n            response = await self._client.post(\n                f\"/work_pools/{work_pool_name}/queues\", json=data\n            )\n        else:\n            response = await self._client.post(\"/work_queues/\", json=data)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        elif e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue_by_name","title":"<code>read_work_queue_by_name</code>  <code>async</code>","text":"<p>Read a work queue by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>a unique name for the work queue</p> required <code>work_pool_name</code> <code>str</code> <p>the name of the work pool the queue belongs to.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>if no work queue is found</p> <code>HTTPStatusError</code> <p>other status errors</p> <p>Returns:</p> Name Type Description <code>WorkQueue</code> <code>WorkQueue</code> <p>a work queue API object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue_by_name(\n    self,\n    name: str,\n    work_pool_name: Optional[str] = None,\n) -&gt; WorkQueue:\n    \"\"\"\n    Read a work queue by name.\n\n    Args:\n        name (str): a unique name for the work queue\n        work_pool_name (str, optional): the name of the work pool\n            the queue belongs to.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: if no work queue is found\n        httpx.HTTPStatusError: other status errors\n\n    Returns:\n        WorkQueue: a work queue API object\n    \"\"\"\n    try:\n        if work_pool_name is not None:\n            response = await self._client.get(\n                f\"/work_pools/{work_pool_name}/queues/{name}\"\n            )\n        else:\n            response = await self._client.get(f\"/work_queues/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_work_queue","title":"<code>update_work_queue</code>  <code>async</code>","text":"<p>Update properties of a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the ID of the work queue to update</p> required <code>**kwargs</code> <p>the fields to update</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if no kwargs are provided</p> <code>ObjectNotFound</code> <p>if request returns 404</p> <code>RequestError</code> <p>if the request fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_work_queue(self, id: UUID, **kwargs):\n    \"\"\"\n    Update properties of a work queue.\n\n    Args:\n        id: the ID of the work queue to update\n        **kwargs: the fields to update\n\n    Raises:\n        ValueError: if no kwargs are provided\n        prefect.exceptions.ObjectNotFound: if request returns 404\n        httpx.RequestError: if the request fails\n\n    \"\"\"\n    if not kwargs:\n        raise ValueError(\"No fields provided to update.\")\n\n    data = WorkQueueUpdate(**kwargs).dict(json_compatible=True, exclude_unset=True)\n    try:\n        await self._client.patch(f\"/work_queues/{id}\", json=data)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_runs_in_work_queue","title":"<code>get_runs_in_work_queue</code>  <code>async</code>","text":"<p>Read flow runs off a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to read from</p> required <code>limit</code> <code>int</code> <p>a limit on the number of runs to return</p> <code>10</code> <code>scheduled_before</code> <code>datetime</code> <p>a timestamp; only runs scheduled before this time will be returned. Defaults to now.</p> <code>None</code> <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>List[FlowRun]: a list of FlowRun objects read from the queue</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_runs_in_work_queue(\n    self,\n    id: UUID,\n    limit: int = 10,\n    scheduled_before: datetime.datetime = None,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Read flow runs off a work queue.\n\n    Args:\n        id: the id of the work queue to read from\n        limit: a limit on the number of runs to return\n        scheduled_before: a timestamp; only runs scheduled before this time will be returned.\n            Defaults to now.\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        List[FlowRun]: a list of FlowRun objects read from the queue\n    \"\"\"\n    if scheduled_before is None:\n        scheduled_before = pendulum.now(\"UTC\")\n\n    try:\n        response = await self._client.post(\n            f\"/work_queues/{id}/get_runs\",\n            json={\n                \"limit\": limit,\n                \"scheduled_before\": scheduled_before.isoformat(),\n            },\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue","title":"<code>read_work_queue</code>  <code>async</code>","text":"<p>Read a work queue.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to load</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Name Type Description <code>WorkQueue</code> <code>WorkQueue</code> <p>an instantiated WorkQueue object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue(\n    self,\n    id: UUID,\n) -&gt; WorkQueue:\n    \"\"\"\n    Read a work queue.\n\n    Args:\n        id: the id of the work queue to load\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        WorkQueue: an instantiated WorkQueue object\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_queues/{id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueue.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queue_status","title":"<code>read_work_queue_status</code>  <code>async</code>","text":"<p>Read a work queue status.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to load</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Name Type Description <code>WorkQueueStatus</code> <code>WorkQueueStatusDetail</code> <p>an instantiated WorkQueueStatus object</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queue_status(\n    self,\n    id: UUID,\n) -&gt; WorkQueueStatusDetail:\n    \"\"\"\n    Read a work queue status.\n\n    Args:\n        id: the id of the work queue to load\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        WorkQueueStatus: an instantiated WorkQueueStatus object\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_queues/{id}/status\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return WorkQueueStatusDetail.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.match_work_queues","title":"<code>match_work_queues</code>  <code>async</code>","text":"<p>Query the Prefect API for work queues with names with a specific prefix.</p> <p>Parameters:</p> Name Type Description Default <code>prefixes</code> <code>List[str]</code> <p>a list of strings used to match work queue name prefixes</p> required <code>work_pool_name</code> <code>Optional[str]</code> <p>an optional work pool name to scope the query to</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>a list of WorkQueue model representations of the work queues</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def match_work_queues(\n    self,\n    prefixes: List[str],\n    work_pool_name: Optional[str] = None,\n) -&gt; List[WorkQueue]:\n    \"\"\"\n    Query the Prefect API for work queues with names with a specific prefix.\n\n    Args:\n        prefixes: a list of strings used to match work queue name prefixes\n        work_pool_name: an optional work pool name to scope the query to\n\n    Returns:\n        a list of WorkQueue model representations\n            of the work queues\n    \"\"\"\n    page_length = 100\n    current_page = 0\n    work_queues = []\n\n    while True:\n        new_queues = await self.read_work_queues(\n            work_pool_name=work_pool_name,\n            offset=current_page * page_length,\n            limit=page_length,\n            work_queue_filter=WorkQueueFilter(\n                name=WorkQueueFilterName(startswith_=prefixes)\n            ),\n        )\n        if not new_queues:\n            break\n        work_queues += new_queues\n        current_page += 1\n\n    return work_queues\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_work_queue_by_id","title":"<code>delete_work_queue_by_id</code>  <code>async</code>","text":"<p>Delete a work queue by its ID.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>the id of the work queue to delete</p> required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If requests fails</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_work_queue_by_id(\n    self,\n    id: UUID,\n):\n    \"\"\"\n    Delete a work queue by its ID.\n\n    Args:\n        id: the id of the work queue to delete\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/work_queues/{id}\",\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_type","title":"<code>create_block_type</code>  <code>async</code>","text":"<p>Create a block type in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_type(self, block_type: BlockTypeCreate) -&gt; BlockType:\n    \"\"\"\n    Create a block type in the Prefect API.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_types/\",\n            json=block_type.dict(\n                json_compatible=True, exclude_unset=True, exclude={\"id\"}\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockType.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_schema","title":"<code>create_block_schema</code>  <code>async</code>","text":"<p>Create a block schema in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_schema(self, block_schema: BlockSchemaCreate) -&gt; BlockSchema:\n    \"\"\"\n    Create a block schema in the Prefect API.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_schemas/\",\n            json=block_schema.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                exclude={\"id\", \"block_type\", \"checksum\"},\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockSchema.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_block_document","title":"<code>create_block_document</code>  <code>async</code>","text":"<p>Create a block document in the Prefect API. This data is used to configure a corresponding Block.</p> <p>Parameters:</p> Name Type Description Default <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the stored Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. Note Blocks may not work as expected if this is set to <code>False</code>.</p> <code>True</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_block_document(\n    self,\n    block_document: Union[BlockDocument, BlockDocumentCreate],\n    include_secrets: bool = True,\n) -&gt; BlockDocument:\n    \"\"\"\n    Create a block document in the Prefect API. This data is used to configure a\n    corresponding Block.\n\n    Args:\n        include_secrets (bool): whether to include secret values\n            on the stored Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. Note Blocks may not work as expected if\n            this is set to `False`.\n    \"\"\"\n    if isinstance(block_document, BlockDocument):\n        block_document = BlockDocumentCreate.parse_obj(\n            block_document.dict(\n                json_compatible=True,\n                include_secrets=include_secrets,\n                exclude_unset=True,\n                exclude={\"id\", \"block_schema\", \"block_type\"},\n            ),\n        )\n\n    try:\n        response = await self._client.post(\n            \"/block_documents/\",\n            json=block_document.dict(\n                json_compatible=True,\n                include_secrets=include_secrets,\n                exclude_unset=True,\n                exclude={\"id\", \"block_schema\", \"block_type\"},\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_block_document","title":"<code>update_block_document</code>  <code>async</code>","text":"<p>Update a block document in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_block_document(\n    self,\n    block_document_id: UUID,\n    block_document: BlockDocumentUpdate,\n):\n    \"\"\"\n    Update a block document in the Prefect API.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/block_documents/{block_document_id}\",\n            json=block_document.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                include={\"data\", \"merge_existing_data\", \"block_schema_id\"},\n                include_secrets=True,\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_block_document","title":"<code>delete_block_document</code>  <code>async</code>","text":"<p>Delete a block document.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_block_document(self, block_document_id: UUID):\n    \"\"\"\n    Delete a block document.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/block_documents/{block_document_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_type_by_slug","title":"<code>read_block_type_by_slug</code>  <code>async</code>","text":"<p>Read a block type by its slug.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_type_by_slug(self, slug: str) -&gt; BlockType:\n    \"\"\"\n    Read a block type by its slug.\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/block_types/slug/{slug}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockType.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_schema_by_checksum","title":"<code>read_block_schema_by_checksum</code>  <code>async</code>","text":"<p>Look up a block schema checksum</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_schema_by_checksum(\n    self, checksum: str, version: Optional[str] = None\n) -&gt; BlockSchema:\n    \"\"\"\n    Look up a block schema checksum\n    \"\"\"\n    try:\n        url = f\"/block_schemas/checksum/{checksum}\"\n        if version is not None:\n            url = f\"{url}?version={version}\"\n        response = await self._client.get(url)\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockSchema.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_block_type","title":"<code>update_block_type</code>  <code>async</code>","text":"<p>Update a block document in the Prefect API.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_block_type(self, block_type_id: UUID, block_type: BlockTypeUpdate):\n    \"\"\"\n    Update a block document in the Prefect API.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/block_types/{block_type_id}\",\n            json=block_type.dict(\n                json_compatible=True,\n                exclude_unset=True,\n                include=BlockTypeUpdate.updatable_fields(),\n                include_secrets=True,\n            ),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_block_type","title":"<code>delete_block_type</code>  <code>async</code>","text":"<p>Delete a block type.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_block_type(self, block_type_id: UUID):\n    \"\"\"\n    Delete a block type.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/block_types/{block_type_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        elif (\n            e.response.status_code == status.HTTP_403_FORBIDDEN\n            and e.response.json()[\"detail\"]\n            == \"protected block types cannot be deleted.\"\n        ):\n            raise prefect.exceptions.ProtectedBlockError(\n                \"Protected block types cannot be deleted.\"\n            ) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_types","title":"<code>read_block_types</code>  <code>async</code>","text":"<p>Read all block types Raises:     httpx.RequestError: if the block types were not found</p> <p>Returns:</p> Type Description <code>List[BlockType]</code> <p>List of BlockTypes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_types(self) -&gt; List[BlockType]:\n    \"\"\"\n    Read all block types\n    Raises:\n        httpx.RequestError: if the block types were not found\n\n    Returns:\n        List of BlockTypes.\n    \"\"\"\n    response = await self._client.post(\"/block_types/filter\", json={})\n    return pydantic.parse_obj_as(List[BlockType], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_schemas","title":"<code>read_block_schemas</code>  <code>async</code>","text":"<p>Read all block schemas Raises:     httpx.RequestError: if a valid block schema was not found</p> <p>Returns:</p> Type Description <code>List[BlockSchema]</code> <p>A BlockSchema.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_schemas(self) -&gt; List[BlockSchema]:\n    \"\"\"\n    Read all block schemas\n    Raises:\n        httpx.RequestError: if a valid block schema was not found\n\n    Returns:\n        A BlockSchema.\n    \"\"\"\n    response = await self._client.post(\"/block_schemas/filter\", json={})\n    return pydantic.parse_obj_as(List[BlockSchema], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_most_recent_block_schema_for_block_type","title":"<code>get_most_recent_block_schema_for_block_type</code>  <code>async</code>","text":"<p>Fetches the most recent block schema for a specified block type ID.</p> <p>Parameters:</p> Name Type Description Default <code>block_type_id</code> <code>UUID</code> <p>The ID of the block type.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>If the request fails for any reason.</p> <p>Returns:</p> Type Description <code>Optional[BlockSchema]</code> <p>The most recent block schema or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_most_recent_block_schema_for_block_type(\n    self,\n    block_type_id: UUID,\n) -&gt; Optional[BlockSchema]:\n    \"\"\"\n    Fetches the most recent block schema for a specified block type ID.\n\n    Args:\n        block_type_id: The ID of the block type.\n\n    Raises:\n        httpx.RequestError: If the request fails for any reason.\n\n    Returns:\n        The most recent block schema or None.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/block_schemas/filter\",\n            json={\n                \"block_schemas\": {\"block_type_id\": {\"any_\": [str(block_type_id)]}},\n                \"limit\": 1,\n            },\n        )\n    except httpx.HTTPStatusError:\n        raise\n    return BlockSchema.parse_obj(response.json()[0]) if response.json() else None\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_document","title":"<code>read_block_document</code>  <code>async</code>","text":"<p>Read the block document with the specified ID.</p> <p>Parameters:</p> Name Type Description Default <code>block_document_id</code> <code>UUID</code> <p>the block document id</p> required <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the block document was not found for any reason</p> <p>Returns:</p> Type Description <p>A block document or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_document(\n    self,\n    block_document_id: UUID,\n    include_secrets: bool = True,\n):\n    \"\"\"\n    Read the block document with the specified ID.\n\n    Args:\n        block_document_id: the block document id\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Raises:\n        httpx.RequestError: if the block document was not found for any reason\n\n    Returns:\n        A block document or None.\n    \"\"\"\n    assert (\n        block_document_id is not None\n    ), \"Unexpected ID on block document. Was it persisted?\"\n    try:\n        response = await self._client.get(\n            f\"/block_documents/{block_document_id}\",\n            params=dict(include_secrets=include_secrets),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_document_by_name","title":"<code>read_block_document_by_name</code>  <code>async</code>","text":"<p>Read the block document with the specified name that corresponds to a specific block type name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The block document name.</p> required <code>block_type_slug</code> <code>str</code> <p>The block type slug.</p> required <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the block document was not found for any reason</p> <p>Returns:</p> Type Description <code>BlockDocument</code> <p>A block document or None.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_document_by_name(\n    self,\n    name: str,\n    block_type_slug: str,\n    include_secrets: bool = True,\n) -&gt; BlockDocument:\n    \"\"\"\n    Read the block document with the specified name that corresponds to a\n    specific block type name.\n\n    Args:\n        name: The block document name.\n        block_type_slug: The block type slug.\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Raises:\n        httpx.RequestError: if the block document was not found for any reason\n\n    Returns:\n        A block document or None.\n    \"\"\"\n    try:\n        response = await self._client.get(\n            f\"/block_types/slug/{block_type_slug}/block_documents/name/{name}\",\n            params=dict(include_secrets=include_secrets),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return BlockDocument.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_documents","title":"<code>read_block_documents</code>  <code>async</code>","text":"<p>Read block documents</p> <p>Parameters:</p> Name Type Description Default <code>block_schema_type</code> <code>Optional[str]</code> <p>an optional block schema type</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>an offset</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>the number of blocks to return</p> <code>None</code> <code>include_secrets</code> <code>bool</code> <p>whether to include secret values on the Block, corresponding to Pydantic's <code>SecretStr</code> and <code>SecretBytes</code> fields. These fields are automatically obfuscated by Pydantic, but users can additionally choose not to receive their values from the API. Note that any business logic on the Block may not work if this is <code>False</code>.</p> <code>True</code> <p>Returns:</p> Type Description <p>A list of block documents</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_documents(\n    self,\n    block_schema_type: Optional[str] = None,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n    include_secrets: bool = True,\n):\n    \"\"\"\n    Read block documents\n\n    Args:\n        block_schema_type: an optional block schema type\n        offset: an offset\n        limit: the number of blocks to return\n        include_secrets (bool): whether to include secret values\n            on the Block, corresponding to Pydantic's `SecretStr` and\n            `SecretBytes` fields. These fields are automatically obfuscated\n            by Pydantic, but users can additionally choose not to receive\n            their values from the API. Note that any business logic on the\n            Block may not work if this is `False`.\n\n    Returns:\n        A list of block documents\n    \"\"\"\n    response = await self._client.post(\n        \"/block_documents/filter\",\n        json=dict(\n            block_schema_type=block_schema_type,\n            offset=offset,\n            limit=limit,\n            include_secrets=include_secrets,\n        ),\n    )\n    return pydantic.parse_obj_as(List[BlockDocument], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_block_documents_by_type","title":"<code>read_block_documents_by_type</code>  <code>async</code>","text":"<p>Retrieve block documents by block type slug.</p> <p>Parameters:</p> Name Type Description Default <code>block_type_slug</code> <code>str</code> <p>The block type slug.</p> required <code>offset</code> <code>Optional[int]</code> <p>an offset</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>the number of blocks to return</p> <code>None</code> <code>include_secrets</code> <code>bool</code> <p>whether to include secret values</p> <code>True</code> <p>Returns:</p> Type Description <code>List[BlockDocument]</code> <p>A list of block documents</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_block_documents_by_type(\n    self,\n    block_type_slug: str,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n    include_secrets: bool = True,\n) -&gt; List[BlockDocument]:\n    \"\"\"Retrieve block documents by block type slug.\n\n    Args:\n        block_type_slug: The block type slug.\n        offset: an offset\n        limit: the number of blocks to return\n        include_secrets: whether to include secret values\n\n    Returns:\n        A list of block documents\n    \"\"\"\n    response = await self._client.get(\n        f\"/block_types/slug/{block_type_slug}/block_documents\",\n        params=dict(\n            offset=offset,\n            limit=limit,\n            include_secrets=include_secrets,\n        ),\n    )\n\n    return pydantic.parse_obj_as(List[BlockDocument], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Create a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>flow_id</code> <code>UUID</code> <p>the flow ID to create a deployment for</p> required <code>name</code> <code>str</code> <p>the name of the deployment</p> required <code>version</code> <code>str</code> <p>an optional version string for the deployment</p> <code>None</code> <code>schedule</code> <code>SCHEDULE_TYPES</code> <p>an optional schedule to apply to the deployment</p> <code>None</code> <code>tags</code> <code>List[str]</code> <p>an optional list of tags to apply to the deployment</p> <code>None</code> <code>storage_document_id</code> <code>UUID</code> <p>an reference to the storage block document used for the deployed flow</p> <code>None</code> <code>infrastructure_document_id</code> <code>UUID</code> <p>an reference to the infrastructure block document to use for this deployment</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code>. This argument was previously named <code>infra_overrides</code>. Both arguments are supported for backwards compatibility.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the deployment was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the deployment in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_deployment(\n    self,\n    flow_id: UUID,\n    name: str,\n    version: str = None,\n    schedule: SCHEDULE_TYPES = None,\n    schedules: List[DeploymentScheduleCreate] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    description: str = None,\n    work_queue_name: str = None,\n    work_pool_name: str = None,\n    tags: List[str] = None,\n    storage_document_id: UUID = None,\n    manifest_path: str = None,\n    path: str = None,\n    entrypoint: str = None,\n    infrastructure_document_id: UUID = None,\n    infra_overrides: Optional[Dict[str, Any]] = None,  # for backwards compat\n    parameter_openapi_schema: Optional[Dict[str, Any]] = None,\n    is_schedule_active: Optional[bool] = None,\n    paused: Optional[bool] = None,\n    pull_steps: Optional[List[dict]] = None,\n    enforce_parameter_schema: Optional[bool] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a deployment.\n\n    Args:\n        flow_id: the flow ID to create a deployment for\n        name: the name of the deployment\n        version: an optional version string for the deployment\n        schedule: an optional schedule to apply to the deployment\n        tags: an optional list of tags to apply to the deployment\n        storage_document_id: an reference to the storage block document\n            used for the deployed flow\n        infrastructure_document_id: an reference to the infrastructure block document\n            to use for this deployment\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`. This argument was previously named `infra_overrides`.\n            Both arguments are supported for backwards compatibility.\n\n    Raises:\n        httpx.RequestError: if the deployment was not created for any reason\n\n    Returns:\n        the ID of the deployment in the backend\n    \"\"\"\n    jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n    deployment_create = DeploymentCreate(\n        flow_id=flow_id,\n        name=name,\n        version=version,\n        parameters=dict(parameters or {}),\n        tags=list(tags or []),\n        work_queue_name=work_queue_name,\n        description=description,\n        storage_document_id=storage_document_id,\n        path=path,\n        entrypoint=entrypoint,\n        manifest_path=manifest_path,  # for backwards compat\n        infrastructure_document_id=infrastructure_document_id,\n        job_variables=jv,\n        parameter_openapi_schema=parameter_openapi_schema,\n        is_schedule_active=is_schedule_active,\n        paused=paused,\n        schedule=schedule,\n        schedules=schedules or [],\n        pull_steps=pull_steps,\n        enforce_parameter_schema=enforce_parameter_schema,\n    )\n\n    if work_pool_name is not None:\n        deployment_create.work_pool_name = work_pool_name\n\n    # Exclude newer fields that are not set to avoid compatibility issues\n    exclude = {\n        field\n        for field in [\"work_pool_name\", \"work_queue_name\"]\n        if field not in deployment_create.__fields_set__\n    }\n\n    if deployment_create.is_schedule_active is None:\n        exclude.add(\"is_schedule_active\")\n\n    if deployment_create.paused is None:\n        exclude.add(\"paused\")\n\n    if deployment_create.pull_steps is None:\n        exclude.add(\"pull_steps\")\n\n    if deployment_create.enforce_parameter_schema is None:\n        exclude.add(\"enforce_parameter_schema\")\n\n    json = deployment_create.dict(json_compatible=True, exclude=exclude)\n    response = await self._client.post(\n        \"/deployments/\",\n        json=json,\n    )\n    deployment_id = response.json().get(\"id\")\n    if not deployment_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(deployment_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID of interest</p> required <p>Returns:</p> Type Description <code>DeploymentResponse</code> <p>a Deployment model representation of the deployment</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment(\n    self,\n    deployment_id: UUID,\n) -&gt; DeploymentResponse:\n    \"\"\"\n    Query the Prefect API for a deployment by id.\n\n    Args:\n        deployment_id: the deployment ID of interest\n\n    Returns:\n        a [Deployment model][prefect.client.schemas.objects.Deployment] representation of the deployment\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/{deployment_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return DeploymentResponse.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>A deployed flow's name: / required <p>Raises:</p> Type Description <code>ObjectNotFound</code> <p>If request returns 404</p> <code>RequestError</code> <p>If request fails</p> <p>Returns:</p> Type Description <code>DeploymentResponse</code> <p>a Deployment model representation of the deployment</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment_by_name(\n    self,\n    name: str,\n) -&gt; DeploymentResponse:\n    \"\"\"\n    Query the Prefect API for a deployment by name.\n\n    Args:\n        name: A deployed flow's name: &lt;FLOW_NAME&gt;/&lt;DEPLOYMENT_NAME&gt;\n\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If request fails\n\n    Returns:\n        a Deployment model representation of the deployment\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return DeploymentResponse.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Query the Prefect API for deployments. Only deployments matching all the provided criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the deployment query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the deployment query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[DeploymentResponse]</code> <p>a list of Deployment model representations of the deployments</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployments(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    limit: int = None,\n    sort: DeploymentSort = None,\n    offset: int = 0,\n) -&gt; List[DeploymentResponse]:\n    \"\"\"\n    Query the Prefect API for deployments. Only deployments matching all\n    the provided criteria will be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        limit: a limit for the deployment query\n        offset: an offset for the deployment query\n\n    Returns:\n        a list of Deployment model representations\n            of the deployments\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n        \"sort\": sort,\n    }\n\n    response = await self._client.post(\"/deployments/filter\", json=body)\n    return pydantic.parse_obj_as(List[DeploymentResponse], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>The deployment id of interest.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_deployment(\n    self,\n    deployment_id: UUID,\n):\n    \"\"\"\n    Delete deployment by id.\n\n    Args:\n        deployment_id: The deployment id of interest.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/deployments/{deployment_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_deployment_schedules","title":"<code>create_deployment_schedules</code>  <code>async</code>","text":"<p>Create deployment schedules.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedules</code> <code>List[Tuple[SCHEDULE_TYPES, bool]]</code> <p>a list of tuples containing the schedule to create        and whether or not it should be active.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the schedules were not created for any reason</p> <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>the list of schedules created in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_deployment_schedules(\n    self,\n    deployment_id: UUID,\n    schedules: List[Tuple[SCHEDULE_TYPES, bool]],\n) -&gt; List[DeploymentSchedule]:\n    \"\"\"\n    Create deployment schedules.\n\n    Args:\n        deployment_id: the deployment ID\n        schedules: a list of tuples containing the schedule to create\n                   and whether or not it should be active.\n\n    Raises:\n        httpx.RequestError: if the schedules were not created for any reason\n\n    Returns:\n        the list of schedules created in the backend\n    \"\"\"\n    deployment_schedule_create = [\n        DeploymentScheduleCreate(schedule=schedule[0], active=schedule[1])\n        for schedule in schedules\n    ]\n\n    json = [\n        deployment_schedule_create.dict(json_compatible=True)\n        for deployment_schedule_create in deployment_schedule_create\n    ]\n    response = await self._client.post(\n        f\"/deployments/{deployment_id}/schedules\", json=json\n    )\n    return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_deployment_schedules","title":"<code>read_deployment_schedules</code>  <code>async</code>","text":"<p>Query the Prefect API for a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>a list of DeploymentSchedule model representations of the deployment schedules</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_deployment_schedules(\n    self,\n    deployment_id: UUID,\n) -&gt; List[DeploymentSchedule]:\n    \"\"\"\n    Query the Prefect API for a deployment's schedules.\n\n    Args:\n        deployment_id: the deployment ID\n\n    Returns:\n        a list of DeploymentSchedule model representations of the deployment schedules\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/deployments/{deployment_id}/schedules\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return pydantic.parse_obj_as(List[DeploymentSchedule], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_deployment_schedule","title":"<code>update_deployment_schedule</code>  <code>async</code>","text":"<p>Update a deployment schedule by ID.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedule_id</code> <code>UUID</code> <p>the deployment schedule ID of interest</p> required <code>active</code> <code>Optional[bool]</code> <p>whether or not the schedule should be active</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>the cron, rrule, or interval schedule this deployment schedule should use</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_deployment_schedule(\n    self,\n    deployment_id: UUID,\n    schedule_id: UUID,\n    active: Optional[bool] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n):\n    \"\"\"\n    Update a deployment schedule by ID.\n\n    Args:\n        deployment_id: the deployment ID\n        schedule_id: the deployment schedule ID of interest\n        active: whether or not the schedule should be active\n        schedule: the cron, rrule, or interval schedule this deployment schedule should use\n    \"\"\"\n    kwargs = {}\n    if active is not None:\n        kwargs[\"active\"] = active\n    if schedule is not None:\n        kwargs[\"schedule\"] = schedule\n\n    deployment_schedule_update = DeploymentScheduleUpdate(**kwargs)\n    json = deployment_schedule_update.dict(json_compatible=True, exclude_unset=True)\n\n    try:\n        await self._client.patch(\n            f\"/deployments/{deployment_id}/schedules/{schedule_id}\", json=json\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_deployment_schedule","title":"<code>delete_deployment_schedule</code>  <code>async</code>","text":"<p>Delete a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>deployment_id</code> <code>UUID</code> <p>the deployment ID</p> required <code>schedule_id</code> <code>UUID</code> <p>the ID of the deployment schedule to delete.</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if the schedules were not deleted for any reason</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_deployment_schedule(\n    self,\n    deployment_id: UUID,\n    schedule_id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a deployment schedule.\n\n    Args:\n        deployment_id: the deployment ID\n        schedule_id: the ID of the deployment schedule to delete.\n\n    Raises:\n        httpx.RequestError: if the schedules were not deleted for any reason\n    \"\"\"\n    try:\n        await self._client.delete(\n            f\"/deployments/{deployment_id}/schedules/{schedule_id}\"\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Query the Prefect API for a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <p>Returns:</p> Type Description <code>FlowRun</code> <p>a Flow Run model representation of the flow run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n    \"\"\"\n    Query the Prefect API for a flow run by id.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n\n    Returns:\n        a Flow Run model representation of the flow run\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resumes a paused flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <code>run_input</code> <code>Optional[Dict]</code> <p>the input to resume the flow run with</p> <code>None</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def resume_flow_run(\n    self, flow_run_id: UUID, run_input: Optional[Dict] = None\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Resumes a paused flow run.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n        run_input: the input to resume the flow run with\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    try:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/resume\", json={\"run_input\": run_input}\n        )\n    except httpx.HTTPStatusError:\n        raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>sort criteria for the flow runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>a list of Flow Run model representations of the flow runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Query the Prefect API for flow runs. Only flow runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flow runs\n        limit: limit for the flow run query\n        offset: offset for the flow run query\n\n    Returns:\n        a list of Flow Run model representations\n            of the flow runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = await self._client.post(\"/flow_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Set the state of a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def set_flow_run_state(\n    self,\n    flow_run_id: UUID,\n    state: \"prefect.states.State\",\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a flow run.\n\n    Args:\n        flow_run_id: the id of the flow run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.flow_run_id = flow_run_id\n    state_create.state_details.transition_id = uuid4()\n    try:\n        response = await self._client.post(\n            f\"/flow_runs/{flow_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Query for the states of a flow run</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the flow run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_states(\n    self, flow_run_id: UUID\n) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a flow run\n\n    Args:\n        flow_run_id: the id of the flow run\n\n    Returns:\n        a list of State model representations\n            of the flow run states\n    \"\"\"\n    response = await self._client.get(\n        \"/flow_run_states/\", params=dict(flow_run_id=str(flow_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Create a task run</p> <p>Parameters:</p> Name Type Description Default <code>task</code> <code>Task[P, R]</code> <p>The Task to run</p> required <code>flow_run_id</code> <code>Optional[UUID]</code> <p>The flow run id with which to associate the task run</p> required <code>dynamic_key</code> <code>str</code> <p>A key unique to this particular run of a Task within the flow</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task run</p> <code>None</code> <code>extra_tags</code> <code>Optional[Iterable[str]]</code> <p>an optional list of extra tags to apply to the task run in addition to <code>task.tags</code></p> <code>None</code> <code>state</code> <code>Optional[State[R]]</code> <p>The initial state for the run. If not provided, defaults to <code>Pending</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>task_inputs</code> <code>Optional[Dict[str, List[Union[TaskRunResult, Parameter, Constant]]]]</code> <p>the set of inputs passed to the task</p> <code>None</code> <p>Returns:</p> Type Description <code>TaskRun</code> <p>The created task run.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_task_run(\n    self,\n    task: \"TaskObject[P, R]\",\n    flow_run_id: Optional[UUID],\n    dynamic_key: str,\n    name: Optional[str] = None,\n    extra_tags: Optional[Iterable[str]] = None,\n    state: Optional[prefect.states.State[R]] = None,\n    task_inputs: Optional[\n        Dict[\n            str,\n            List[\n                Union[\n                    TaskRunResult,\n                    Parameter,\n                    Constant,\n                ]\n            ],\n        ]\n    ] = None,\n) -&gt; TaskRun:\n    \"\"\"\n    Create a task run\n\n    Args:\n        task: The Task to run\n        flow_run_id: The flow run id with which to associate the task run\n        dynamic_key: A key unique to this particular run of a Task within the flow\n        name: An optional name for the task run\n        extra_tags: an optional list of extra tags to apply to the task run in\n            addition to `task.tags`\n        state: The initial state for the run. If not provided, defaults to\n            `Pending` for now. Should always be a `Scheduled` type.\n        task_inputs: the set of inputs passed to the task\n\n    Returns:\n        The created task run.\n    \"\"\"\n    tags = set(task.tags).union(extra_tags or [])\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    task_run_data = TaskRunCreate(\n        name=name,\n        flow_run_id=flow_run_id,\n        task_key=task.task_key,\n        dynamic_key=dynamic_key,\n        tags=list(tags),\n        task_version=task.version,\n        empirical_policy=TaskRunPolicy(\n            retries=task.retries,\n            retry_delay=task.retry_delay_seconds,\n            retry_jitter_factor=task.retry_jitter_factor,\n        ),\n        state=state.to_state_create(),\n        task_inputs=task_inputs or {},\n    )\n\n    response = await self._client.post(\n        \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n    )\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Query the Prefect API for a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required <p>Returns:</p> Type Description <code>TaskRun</code> <p>a Task Run model representation of the task run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n    \"\"\"\n    Query the Prefect API for a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n\n    Returns:\n        a Task Run model representation of the task run\n    \"\"\"\n    response = await self._client.get(f\"/task_runs/{task_run_id}\")\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Query the Prefect API for task runs. Only task runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>sort criteria for the task runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the task run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the task run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[TaskRun]</code> <p>a list of Task Run model representations of the task runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    sort: TaskRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[TaskRun]:\n    \"\"\"\n    Query the Prefect API for task runs. Only task runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        sort: sort criteria for the task runs\n        limit: a limit for the task run query\n        offset: an offset for the task run query\n\n    Returns:\n        a list of Task Run model representations\n            of the task runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/task_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[TaskRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_task_run(self, task_run_id: UUID) -&gt; None:\n    \"\"\"\n    Delete a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/task_runs/{task_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Set the state of a task run.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def set_task_run_state(\n    self,\n    task_run_id: UUID,\n    state: prefect.states.State,\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a task run.\n\n    Args:\n        task_run_id: the id of the task run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.task_run_id = task_run_id\n    response = await self._client.post(\n        f\"/task_runs/{task_run_id}/set_state\",\n        json=dict(state=state_create.dict(json_compatible=True), force=force),\n    )\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Query for the states of a task run</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the task run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_task_run_states(\n    self, task_run_id: UUID\n) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a task run\n\n    Args:\n        task_run_id: the id of the task run\n\n    Returns:\n        a list of State model representations of the task run states\n    \"\"\"\n    response = await self._client.get(\n        \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_logs","title":"<code>create_logs</code>  <code>async</code>","text":"<p>Create logs for a flow or task run</p> <p>Parameters:</p> Name Type Description Default <code>logs</code> <code>Iterable[Union[LogCreate, dict]]</code> <p>An iterable of <code>LogCreate</code> objects or already json-compatible dicts</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_logs(self, logs: Iterable[Union[LogCreate, dict]]) -&gt; None:\n    \"\"\"\n    Create logs for a flow or task run\n\n    Args:\n        logs: An iterable of `LogCreate` objects or already json-compatible dicts\n    \"\"\"\n    serialized_logs = [\n        log.dict(json_compatible=True) if isinstance(log, LogCreate) else log\n        for log in logs\n    ]\n    await self._client.post(\"/logs/\", json=serialized_logs)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_notification_policy","title":"<code>create_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Create a notification policy for flow runs</p> <p>Parameters:</p> Name Type Description Default <code>block_document_id</code> <code>UUID</code> <p>The block document UUID</p> required <code>is_active</code> <code>bool</code> <p>Whether the notification policy is active</p> <code>True</code> <code>tags</code> <code>List[str]</code> <p>List of flow tags</p> <code>None</code> <code>state_names</code> <code>List[str]</code> <p>List of state names</p> <code>None</code> <code>message_template</code> <code>Optional[str]</code> <p>Notification message template</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_notification_policy(\n    self,\n    block_document_id: UUID,\n    is_active: bool = True,\n    tags: List[str] = None,\n    state_names: List[str] = None,\n    message_template: Optional[str] = None,\n) -&gt; UUID:\n    \"\"\"\n    Create a notification policy for flow runs\n\n    Args:\n        block_document_id: The block document UUID\n        is_active: Whether the notification policy is active\n        tags: List of flow tags\n        state_names: List of state names\n        message_template: Notification message template\n    \"\"\"\n    if tags is None:\n        tags = []\n    if state_names is None:\n        state_names = []\n\n    policy = FlowRunNotificationPolicyCreate(\n        block_document_id=block_document_id,\n        is_active=is_active,\n        tags=tags,\n        state_names=state_names,\n        message_template=message_template,\n    )\n    response = await self._client.post(\n        \"/flow_run_notification_policies/\",\n        json=policy.dict(json_compatible=True),\n    )\n\n    policy_id = response.json().get(\"id\")\n    if not policy_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    return UUID(policy_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run_notification_policy","title":"<code>delete_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Delete a flow run notification policy by id.</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>UUID of the flow run notification policy to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run_notification_policy(\n    self,\n    id: UUID,\n) -&gt; None:\n    \"\"\"\n    Delete a flow run notification policy by id.\n\n    Args:\n        id: UUID of the flow run notification policy to delete.\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    try:\n        await self._client.delete(f\"/flow_run_notification_policies/{id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_flow_run_notification_policy","title":"<code>update_flow_run_notification_policy</code>  <code>async</code>","text":"<p>Update a notification policy for flow runs</p> <p>Parameters:</p> Name Type Description Default <code>id</code> <code>UUID</code> <p>UUID of the notification policy</p> required <code>block_document_id</code> <code>Optional[UUID]</code> <p>The block document UUID</p> <code>None</code> <code>is_active</code> <code>Optional[bool]</code> <p>Whether the notification policy is active</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>List of flow tags</p> <code>None</code> <code>state_names</code> <code>Optional[List[str]]</code> <p>List of state names</p> <code>None</code> <code>message_template</code> <code>Optional[str]</code> <p>Notification message template</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_flow_run_notification_policy(\n    self,\n    id: UUID,\n    block_document_id: Optional[UUID] = None,\n    is_active: Optional[bool] = None,\n    tags: Optional[List[str]] = None,\n    state_names: Optional[List[str]] = None,\n    message_template: Optional[str] = None,\n) -&gt; None:\n    \"\"\"\n    Update a notification policy for flow runs\n\n    Args:\n        id: UUID of the notification policy\n        block_document_id: The block document UUID\n        is_active: Whether the notification policy is active\n        tags: List of flow tags\n        state_names: List of state names\n        message_template: Notification message template\n    Raises:\n        prefect.exceptions.ObjectNotFound: If request returns 404\n        httpx.RequestError: If requests fails\n    \"\"\"\n    params = {}\n    if block_document_id is not None:\n        params[\"block_document_id\"] = block_document_id\n    if is_active is not None:\n        params[\"is_active\"] = is_active\n    if tags is not None:\n        params[\"tags\"] = tags\n    if state_names is not None:\n        params[\"state_names\"] = state_names\n    if message_template is not None:\n        params[\"message_template\"] = message_template\n\n    policy = FlowRunNotificationPolicyUpdate(**params)\n\n    try:\n        await self._client.patch(\n            f\"/flow_run_notification_policies/{id}\",\n            json=policy.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_notification_policies","title":"<code>read_flow_run_notification_policies</code>  <code>async</code>","text":"<p>Query the Prefect API for flow run notification policies. Only policies matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_notification_policy_filter</code> <code>FlowRunNotificationPolicyFilter</code> <p>filter criteria for notification policies</p> required <code>limit</code> <code>Optional[int]</code> <p>a limit for the notification policies query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the notification policies query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRunNotificationPolicy]</code> <p>a list of FlowRunNotificationPolicy model representations of the notification policies</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_notification_policies(\n    self,\n    flow_run_notification_policy_filter: FlowRunNotificationPolicyFilter,\n    limit: Optional[int] = None,\n    offset: int = 0,\n) -&gt; List[FlowRunNotificationPolicy]:\n    \"\"\"\n    Query the Prefect API for flow run notification policies. Only policies matching all criteria will\n    be returned.\n\n    Args:\n        flow_run_notification_policy_filter: filter criteria for notification policies\n        limit: a limit for the notification policies query\n        offset: an offset for the notification policies query\n\n    Returns:\n        a list of FlowRunNotificationPolicy model representations\n            of the notification policies\n    \"\"\"\n    body = {\n        \"flow_run_notification_policy_filter\": (\n            flow_run_notification_policy_filter.dict(json_compatible=True)\n            if flow_run_notification_policy_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\n        \"/flow_run_notification_policies/filter\", json=body\n    )\n    return pydantic.parse_obj_as(List[FlowRunNotificationPolicy], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_logs","title":"<code>read_logs</code>  <code>async</code>","text":"<p>Read flow and task run logs.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_logs(\n    self,\n    log_filter: LogFilter = None,\n    limit: int = None,\n    offset: int = None,\n    sort: LogSort = LogSort.TIMESTAMP_ASC,\n) -&gt; List[Log]:\n    \"\"\"\n    Read flow and task run logs.\n    \"\"\"\n    body = {\n        \"logs\": log_filter.dict(json_compatible=True) if log_filter else None,\n        \"limit\": limit,\n        \"offset\": offset,\n        \"sort\": sort,\n    }\n\n    response = await self._client.post(\"/logs/filter\", json=body)\n    return pydantic.parse_obj_as(List[Log], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.resolve_datadoc","title":"<code>resolve_datadoc</code>  <code>async</code>","text":"<p>Recursively decode possibly nested data documents.</p> <p>\"server\" encoded documents will be retrieved from the server.</p> <p>Parameters:</p> Name Type Description Default <code>datadoc</code> <code>DataDocument</code> <p>The data document to resolve</p> required <p>Returns:</p> Type Description <code>Any</code> <p>a decoded object, the innermost data</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def resolve_datadoc(self, datadoc: DataDocument) -&gt; Any:\n    \"\"\"\n    Recursively decode possibly nested data documents.\n\n    \"server\" encoded documents will be retrieved from the server.\n\n    Args:\n        datadoc: The data document to resolve\n\n    Returns:\n        a decoded object, the innermost data\n    \"\"\"\n    if not isinstance(datadoc, DataDocument):\n        raise TypeError(\n            f\"`resolve_datadoc` received invalid type {type(datadoc).__name__}\"\n        )\n\n    async def resolve_inner(data):\n        if isinstance(data, bytes):\n            try:\n                data = DataDocument.parse_raw(data)\n            except pydantic.ValidationError:\n                return data\n\n        if isinstance(data, DataDocument):\n            return await resolve_inner(data.decode())\n\n        return data\n\n    return await resolve_inner(datadoc)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.send_worker_heartbeat","title":"<code>send_worker_heartbeat</code>  <code>async</code>","text":"<p>Sends a worker heartbeat for a given work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool to heartbeat against.</p> required <code>worker_name</code> <code>str</code> <p>The name of the worker sending the heartbeat.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def send_worker_heartbeat(\n    self,\n    work_pool_name: str,\n    worker_name: str,\n    heartbeat_interval_seconds: Optional[float] = None,\n):\n    \"\"\"\n    Sends a worker heartbeat for a given work pool.\n\n    Args:\n        work_pool_name: The name of the work pool to heartbeat against.\n        worker_name: The name of the worker sending the heartbeat.\n    \"\"\"\n    await self._client.post(\n        f\"/work_pools/{work_pool_name}/workers/heartbeat\",\n        json={\n            \"name\": worker_name,\n            \"heartbeat_interval_seconds\": heartbeat_interval_seconds,\n        },\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_workers_for_work_pool","title":"<code>read_workers_for_work_pool</code>  <code>async</code>","text":"<p>Reads workers for a given work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool for which to get member workers.</p> required <code>worker_filter</code> <code>Optional[WorkerFilter]</code> <p>Criteria by which to filter workers.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>Limit for the worker query.</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>Limit for the worker query.</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_workers_for_work_pool(\n    self,\n    work_pool_name: str,\n    worker_filter: Optional[WorkerFilter] = None,\n    offset: Optional[int] = None,\n    limit: Optional[int] = None,\n) -&gt; List[Worker]:\n    \"\"\"\n    Reads workers for a given work pool.\n\n    Args:\n        work_pool_name: The name of the work pool for which to get\n            member workers.\n        worker_filter: Criteria by which to filter workers.\n        limit: Limit for the worker query.\n        offset: Limit for the worker query.\n    \"\"\"\n    response = await self._client.post(\n        f\"/work_pools/{work_pool_name}/workers/filter\",\n        json={\n            \"worker_filter\": (\n                worker_filter.dict(json_compatible=True, exclude_unset=True)\n                if worker_filter\n                else None\n            ),\n            \"offset\": offset,\n            \"limit\": limit,\n        },\n    )\n\n    return pydantic.parse_obj_as(List[Worker], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_pool","title":"<code>read_work_pool</code>  <code>async</code>","text":"<p>Reads information for a given work pool</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool to for which to get information.</p> required <p>Returns:</p> Type Description <code>WorkPool</code> <p>Information about the requested work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_pool(self, work_pool_name: str) -&gt; WorkPool:\n    \"\"\"\n    Reads information for a given work pool\n\n    Args:\n        work_pool_name: The name of the work pool to for which to get\n            information.\n\n    Returns:\n        Information about the requested work pool.\n    \"\"\"\n    try:\n        response = await self._client.get(f\"/work_pools/{work_pool_name}\")\n        return pydantic.parse_obj_as(WorkPool, response.json())\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_pools","title":"<code>read_work_pools</code>  <code>async</code>","text":"<p>Reads work pools.</p> <p>Parameters:</p> Name Type Description Default <code>limit</code> <code>Optional[int]</code> <p>Limit for the work pool query.</p> <code>None</code> <code>offset</code> <code>int</code> <p>Offset for the work pool query.</p> <code>0</code> <code>work_pool_filter</code> <code>Optional[WorkPoolFilter]</code> <p>Criteria by which to filter work pools.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkPool]</code> <p>A list of work pools.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_pools(\n    self,\n    limit: Optional[int] = None,\n    offset: int = 0,\n    work_pool_filter: Optional[WorkPoolFilter] = None,\n) -&gt; List[WorkPool]:\n    \"\"\"\n    Reads work pools.\n\n    Args:\n        limit: Limit for the work pool query.\n        offset: Offset for the work pool query.\n        work_pool_filter: Criteria by which to filter work pools.\n\n    Returns:\n        A list of work pools.\n    \"\"\"\n\n    body = {\n        \"limit\": limit,\n        \"offset\": offset,\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n    }\n    response = await self._client.post(\"/work_pools/filter\", json=body)\n    return pydantic.parse_obj_as(List[WorkPool], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_work_pool","title":"<code>create_work_pool</code>  <code>async</code>","text":"<p>Creates a work pool with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool</code> <code>WorkPoolCreate</code> <p>Desired configuration for the new work pool.</p> required <code>overwrite</code> <code>bool</code> <p>Whether to overwrite an existing work pool with the same name.</p> <code>False</code> <p>Returns:</p> Type Description <code>WorkPool</code> <p>Information about the newly created work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_work_pool(\n    self,\n    work_pool: WorkPoolCreate,\n    overwrite: bool = False,\n) -&gt; WorkPool:\n    \"\"\"\n    Creates a work pool with the provided configuration.\n\n    Args:\n        work_pool: Desired configuration for the new work pool.\n        overwrite: Whether to overwrite an existing work pool with the same name.\n\n    Returns:\n        Information about the newly created work pool.\n    \"\"\"\n    try:\n        response = await self._client.post(\n            \"/work_pools/\",\n            json=work_pool.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_409_CONFLICT:\n            if overwrite:\n                existing_work_pool = await self.read_work_pool(\n                    work_pool_name=work_pool.name\n                )\n                if existing_work_pool.type != work_pool.type:\n                    warnings.warn(\n                        \"Overwriting work pool type is not supported. Ignoring provided type.\",\n                        category=UserWarning,\n                    )\n                await self.update_work_pool(\n                    work_pool_name=work_pool.name,\n                    work_pool=WorkPoolUpdate.parse_obj(\n                        work_pool.dict(exclude={\"name\", \"type\"})\n                    ),\n                )\n                response = await self._client.get(f\"/work_pools/{work_pool.name}\")\n            else:\n                raise prefect.exceptions.ObjectAlreadyExists(http_exc=e) from e\n        else:\n            raise\n\n    return pydantic.parse_obj_as(WorkPool, response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_work_pool","title":"<code>update_work_pool</code>  <code>async</code>","text":"<p>Updates a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>Name of the work pool to update.</p> required <code>work_pool</code> <code>WorkPoolUpdate</code> <p>Fields to update in the work pool.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_work_pool(\n    self,\n    work_pool_name: str,\n    work_pool: WorkPoolUpdate,\n):\n    \"\"\"\n    Updates a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool to update.\n        work_pool: Fields to update in the work pool.\n    \"\"\"\n    try:\n        await self._client.patch(\n            f\"/work_pools/{work_pool_name}\",\n            json=work_pool.dict(json_compatible=True, exclude_unset=True),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_work_pool","title":"<code>delete_work_pool</code>  <code>async</code>","text":"<p>Deletes a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>Name of the work pool to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_work_pool(\n    self,\n    work_pool_name: str,\n):\n    \"\"\"\n    Deletes a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool to delete.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/work_pools/{work_pool_name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_work_queues","title":"<code>read_work_queues</code>  <code>async</code>","text":"<p>Retrieves queues for a work pool.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>Name of the work pool for which to get queues.</p> <code>None</code> <code>work_queue_filter</code> <code>Optional[WorkQueueFilter]</code> <p>Criteria by which to filter queues.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>Limit for the queue query.</p> <code>None</code> <code>offset</code> <code>Optional[int]</code> <p>Limit for the queue query.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>List of queues for the specified work pool.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_work_queues(\n    self,\n    work_pool_name: Optional[str] = None,\n    work_queue_filter: Optional[WorkQueueFilter] = None,\n    limit: Optional[int] = None,\n    offset: Optional[int] = None,\n) -&gt; List[WorkQueue]:\n    \"\"\"\n    Retrieves queues for a work pool.\n\n    Args:\n        work_pool_name: Name of the work pool for which to get queues.\n        work_queue_filter: Criteria by which to filter queues.\n        limit: Limit for the queue query.\n        offset: Limit for the queue query.\n\n    Returns:\n        List of queues for the specified work pool.\n    \"\"\"\n    json = {\n        \"work_queues\": (\n            work_queue_filter.dict(json_compatible=True, exclude_unset=True)\n            if work_queue_filter\n            else None\n        ),\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    if work_pool_name:\n        try:\n            response = await self._client.post(\n                f\"/work_pools/{work_pool_name}/queues/filter\",\n                json=json,\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n    else:\n        response = await self._client.post(\"/work_queues/filter\", json=json)\n\n    return pydantic.parse_obj_as(List[WorkQueue], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.get_scheduled_flow_runs_for_work_pool","title":"<code>get_scheduled_flow_runs_for_work_pool</code>  <code>async</code>","text":"<p>Retrieves scheduled flow runs for the provided set of work pool queues.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>str</code> <p>The name of the work pool that the work pool queues are associated with.</p> required <code>work_queue_names</code> <code>Optional[List[str]]</code> <p>The names of the work pool queues from which to get scheduled flow runs.</p> <code>None</code> <code>scheduled_before</code> <code>Optional[datetime]</code> <p>Datetime used to filter returned flow runs. Flow runs scheduled for after the given datetime string will not be returned.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[WorkerFlowRunResponse]</code> <p>A list of worker flow run responses containing information about the</p> <code>List[WorkerFlowRunResponse]</code> <p>retrieved flow runs.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def get_scheduled_flow_runs_for_work_pool(\n    self,\n    work_pool_name: str,\n    work_queue_names: Optional[List[str]] = None,\n    scheduled_before: Optional[datetime.datetime] = None,\n) -&gt; List[WorkerFlowRunResponse]:\n    \"\"\"\n    Retrieves scheduled flow runs for the provided set of work pool queues.\n\n    Args:\n        work_pool_name: The name of the work pool that the work pool\n            queues are associated with.\n        work_queue_names: The names of the work pool queues from which\n            to get scheduled flow runs.\n        scheduled_before: Datetime used to filter returned flow runs. Flow runs\n            scheduled for after the given datetime string will not be returned.\n\n    Returns:\n        A list of worker flow run responses containing information about the\n        retrieved flow runs.\n    \"\"\"\n    body: Dict[str, Any] = {}\n    if work_queue_names is not None:\n        body[\"work_queue_names\"] = list(work_queue_names)\n    if scheduled_before:\n        body[\"scheduled_before\"] = str(scheduled_before)\n\n    response = await self._client.post(\n        f\"/work_pools/{work_pool_name}/get_scheduled_flow_runs\",\n        json=body,\n    )\n    return pydantic.parse_obj_as(List[WorkerFlowRunResponse], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_artifact","title":"<code>create_artifact</code>  <code>async</code>","text":"<p>Creates an artifact with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>artifact</code> <code>ArtifactCreate</code> <p>Desired configuration for the new artifact.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_artifact(\n    self,\n    artifact: ArtifactCreate,\n) -&gt; Artifact:\n    \"\"\"\n    Creates an artifact with the provided configuration.\n\n    Args:\n        artifact: Desired configuration for the new artifact.\n    Returns:\n        Information about the newly created artifact.\n    \"\"\"\n\n    response = await self._client.post(\n        \"/artifacts/\",\n        json=artifact.dict(json_compatible=True, exclude_unset=True),\n    )\n\n    return pydantic.parse_obj_as(Artifact, response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_artifacts","title":"<code>read_artifacts</code>  <code>async</code>","text":"<p>Query the Prefect API for artifacts. Only artifacts matching all criteria will be returned. Args:     artifact_filter: filter criteria for artifacts     flow_run_filter: filter criteria for flow runs     task_run_filter: filter criteria for task runs     sort: sort criteria for the artifacts     limit: limit for the artifact query     offset: offset for the artifact query Returns:     a list of Artifact model representations of the artifacts</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_artifacts(\n    self,\n    *,\n    artifact_filter: ArtifactFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    sort: ArtifactSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[Artifact]:\n    \"\"\"\n    Query the Prefect API for artifacts. Only artifacts matching all criteria will\n    be returned.\n    Args:\n        artifact_filter: filter criteria for artifacts\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        sort: sort criteria for the artifacts\n        limit: limit for the artifact query\n        offset: offset for the artifact query\n    Returns:\n        a list of Artifact model representations of the artifacts\n    \"\"\"\n    body = {\n        \"artifacts\": (\n            artifact_filter.dict(json_compatible=True) if artifact_filter else None\n        ),\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/artifacts/filter\", json=body)\n    return pydantic.parse_obj_as(List[Artifact], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_latest_artifacts","title":"<code>read_latest_artifacts</code>  <code>async</code>","text":"<p>Query the Prefect API for artifacts. Only artifacts matching all criteria will be returned. Args:     artifact_filter: filter criteria for artifacts     flow_run_filter: filter criteria for flow runs     task_run_filter: filter criteria for task runs     sort: sort criteria for the artifacts     limit: limit for the artifact query     offset: offset for the artifact query Returns:     a list of Artifact model representations of the artifacts</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_latest_artifacts(\n    self,\n    *,\n    artifact_filter: ArtifactCollectionFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    sort: ArtifactCollectionSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[ArtifactCollection]:\n    \"\"\"\n    Query the Prefect API for artifacts. Only artifacts matching all criteria will\n    be returned.\n    Args:\n        artifact_filter: filter criteria for artifacts\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        sort: sort criteria for the artifacts\n        limit: limit for the artifact query\n        offset: offset for the artifact query\n    Returns:\n        a list of Artifact model representations of the artifacts\n    \"\"\"\n    body = {\n        \"artifacts\": (\n            artifact_filter.dict(json_compatible=True) if artifact_filter else None\n        ),\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True) if flow_run_filter else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = await self._client.post(\"/artifacts/latest/filter\", json=body)\n    return pydantic.parse_obj_as(List[ArtifactCollection], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_artifact","title":"<code>delete_artifact</code>  <code>async</code>","text":"<p>Deletes an artifact with the provided id.</p> <p>Parameters:</p> Name Type Description Default <code>artifact_id</code> <code>UUID</code> <p>The id of the artifact to delete.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_artifact(self, artifact_id: UUID) -&gt; None:\n    \"\"\"\n    Deletes an artifact with the provided id.\n\n    Args:\n        artifact_id: The id of the artifact to delete.\n    \"\"\"\n    try:\n        await self._client.delete(f\"/artifacts/{artifact_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_variable","title":"<code>create_variable</code>  <code>async</code>","text":"<p>Creates an variable with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>variable</code> <code>VariableCreate</code> <p>Desired configuration for the new variable.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_variable(self, variable: VariableCreate) -&gt; Variable:\n    \"\"\"\n    Creates an variable with the provided configuration.\n\n    Args:\n        variable: Desired configuration for the new variable.\n    Returns:\n        Information about the newly created variable.\n    \"\"\"\n    response = await self._client.post(\n        \"/variables/\",\n        json=variable.dict(json_compatible=True, exclude_unset=True),\n    )\n    return Variable(**response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_variable","title":"<code>update_variable</code>  <code>async</code>","text":"<p>Updates a variable with the provided configuration.</p> <p>Parameters:</p> Name Type Description Default <code>variable</code> <code>VariableUpdate</code> <p>Desired configuration for the updated variable.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_variable(self, variable: VariableUpdate) -&gt; None:\n    \"\"\"\n    Updates a variable with the provided configuration.\n\n    Args:\n        variable: Desired configuration for the updated variable.\n    Returns:\n        Information about the updated variable.\n    \"\"\"\n    await self._client.patch(\n        f\"/variables/name/{variable.name}\",\n        json=variable.dict(json_compatible=True, exclude_unset=True),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_variable_by_name","title":"<code>read_variable_by_name</code>  <code>async</code>","text":"<p>Reads a variable by name. Returns None if no variable is found.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_variable_by_name(self, name: str) -&gt; Optional[Variable]:\n    \"\"\"Reads a variable by name. Returns None if no variable is found.\"\"\"\n    try:\n        response = await self._client.get(f\"/variables/name/{name}\")\n        return Variable(**response.json())\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            return None\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_variable_by_name","title":"<code>delete_variable_by_name</code>  <code>async</code>","text":"<p>Deletes a variable by name.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_variable_by_name(self, name: str):\n    \"\"\"Deletes a variable by name.\"\"\"\n    try:\n        await self._client.delete(f\"/variables/name/{name}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_variables","title":"<code>read_variables</code>  <code>async</code>","text":"<p>Reads all variables.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_variables(self, limit: int = None) -&gt; List[Variable]:\n    \"\"\"Reads all variables.\"\"\"\n    response = await self._client.post(\"/variables/filter\", json={\"limit\": limit})\n    return pydantic.parse_obj_as(List[Variable], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_worker_metadata","title":"<code>read_worker_metadata</code>  <code>async</code>","text":"<p>Reads worker metadata stored in Prefect collection registry.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_worker_metadata(self) -&gt; Dict[str, Any]:\n    \"\"\"Reads worker metadata stored in Prefect collection registry.\"\"\"\n    response = await self._client.get(\"collections/views/aggregate-worker-metadata\")\n    response.raise_for_status()\n    return response.json()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Creates a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required <code>value</code> <code>str</code> <p>The input value.</p> required <code>sender</code> <code>Optional[str]</code> <p>The sender of the input.</p> <code>None</code> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_flow_run_input(\n    self, flow_run_id: UUID, key: str, value: str, sender: Optional[str] = None\n):\n    \"\"\"\n    Creates a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n        value: The input value.\n        sender: The sender of the input.\n    \"\"\"\n\n    # Initialize the input to ensure that the key is valid.\n    FlowRunInput(flow_run_id=flow_run_id, key=key, value=value)\n\n    response = await self._client.post(\n        f\"/flow_runs/{flow_run_id}/input\",\n        json={\"key\": key, \"value\": value, \"sender\": sender},\n    )\n    response.raise_for_status()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Reads a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_flow_run_input(self, flow_run_id: UUID, key: str) -&gt; str:\n    \"\"\"\n    Reads a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n    \"\"\"\n    response = await self._client.get(f\"/flow_runs/{flow_run_id}/input/{key}\")\n    response.raise_for_status()\n    return response.content.decode()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Deletes a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>The flow run id.</p> required <code>key</code> <code>str</code> <p>The input key.</p> required Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def delete_flow_run_input(self, flow_run_id: UUID, key: str):\n    \"\"\"\n    Deletes a flow run input.\n\n    Args:\n        flow_run_id: The flow run id.\n        key: The input key.\n    \"\"\"\n    response = await self._client.delete(f\"/flow_runs/{flow_run_id}/input/{key}\")\n    response.raise_for_status()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.create_automation","title":"<code>create_automation</code>  <code>async</code>","text":"<p>Creates an automation in Prefect Cloud.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def create_automation(self, automation: AutomationCore) -&gt; UUID:\n    \"\"\"Creates an automation in Prefect Cloud.\"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n\n    response = await self._client.post(\n        \"/automations/\",\n        json=automation.dict(json_compatible=True),\n    )\n\n    return UUID(response.json()[\"id\"])\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.update_automation","title":"<code>update_automation</code>  <code>async</code>","text":"<p>Updates an automation in Prefect Cloud.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def update_automation(self, automation_id: UUID, automation: AutomationCore):\n    \"\"\"Updates an automation in Prefect Cloud.\"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n    response = await self._client.put(\n        f\"/automations/{automation_id}\",\n        json=automation.dict(json_compatible=True, exclude_unset=True),\n    )\n    response.raise_for_status\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.PrefectClient.read_automations_by_name","title":"<code>read_automations_by_name</code>  <code>async</code>","text":"<p>Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the automation to query</p> required <p>Returns:</p> Type Description <code>List[Automation]</code> <p>a list of Automation model representations of the automations</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>async def read_automations_by_name(self, name: str) -&gt; List[Automation]:\n    \"\"\"\n    Query the Prefect API for an automation by name. Only automations matching the provided name will be returned.\n\n    Args:\n        name: the name of the automation to query\n\n    Returns:\n        a list of Automation model representations of the automations\n    \"\"\"\n    if not self.server_type.supports_automations():\n        self._raise_for_unsupported_automations()\n    automation_filter = filters.AutomationFilter(name=dict(any_=[name]))\n\n    response = await self._client.post(\n        \"/automations/filter\",\n        json={\n            \"sort\": sorting.AutomationSort.UPDATED_DESC,\n            \"automations\": automation_filter.dict(json_compatible=True)\n            if automation_filter\n            else None,\n        },\n    )\n\n    response.raise_for_status()\n\n    return pydantic.parse_obj_as(List[Automation], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient","title":"<code>SyncPrefectClient</code>","text":"<p>A synchronous client for interacting with the Prefect REST API.</p> <p>Parameters:</p> Name Type Description Default <code>api</code> <code>Union[str, ASGIApp]</code> <p>the REST API URL or FastAPI application to connect to</p> required <code>api_key</code> <code>str</code> <p>An optional API key for authentication.</p> <code>None</code> <code>api_version</code> <code>str</code> <p>The API version this client is compatible with.</p> <code>None</code> <code>httpx_settings</code> <code>Optional[Dict[str, Any]]</code> <p>An optional dictionary of settings to pass to the underlying <code>httpx.Client</code></p> <code>None</code> <pre><code>Say hello to a Prefect REST API\n\n&lt;div class=\"terminal\"&gt;\n```\n&gt;&gt;&gt; with get_client(sync_client=True) as client:\n&gt;&gt;&gt;     response = client.hello()\n&gt;&gt;&gt;\n&gt;&gt;&gt; print(response.json())\n\ud83d\udc4b\n```\n&lt;/div&gt;\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>class SyncPrefectClient:\n    \"\"\"\n    A synchronous client for interacting with the [Prefect REST API](/api-ref/rest-api/).\n\n    Args:\n        api: the REST API URL or FastAPI application to connect to\n        api_key: An optional API key for authentication.\n        api_version: The API version this client is compatible with.\n        httpx_settings: An optional dictionary of settings to pass to the underlying\n            `httpx.Client`\n\n    Examples:\n\n        Say hello to a Prefect REST API\n\n        &lt;div class=\"terminal\"&gt;\n        ```\n        &gt;&gt;&gt; with get_client(sync_client=True) as client:\n        &gt;&gt;&gt;     response = client.hello()\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; print(response.json())\n        \ud83d\udc4b\n        ```\n        &lt;/div&gt;\n    \"\"\"\n\n    def __init__(\n        self,\n        api: Union[str, ASGIApp],\n        *,\n        api_key: str = None,\n        api_version: str = None,\n        httpx_settings: Optional[Dict[str, Any]] = None,\n    ) -&gt; None:\n        httpx_settings = httpx_settings.copy() if httpx_settings else {}\n        httpx_settings.setdefault(\"headers\", {})\n\n        if PREFECT_API_TLS_INSECURE_SKIP_VERIFY:\n            httpx_settings.setdefault(\"verify\", False)\n        else:\n            cert_file = PREFECT_API_SSL_CERT_FILE.value()\n            if not cert_file:\n                cert_file = certifi.where()\n            httpx_settings.setdefault(\"verify\", cert_file)\n\n        if api_version is None:\n            api_version = SERVER_API_VERSION\n        httpx_settings[\"headers\"].setdefault(\"X-PREFECT-API-VERSION\", api_version)\n        if api_key:\n            httpx_settings[\"headers\"].setdefault(\"Authorization\", f\"Bearer {api_key}\")\n\n        # Context management\n        self._ephemeral_app: Optional[ASGIApp] = None\n        self.manage_lifespan = True\n        self.server_type: ServerType\n\n        self._closed = False\n        self._started = False\n\n        # Connect to an external application\n        if isinstance(api, str):\n            if httpx_settings.get(\"app\"):\n                raise ValueError(\n                    \"Invalid httpx settings: `app` cannot be set when providing an \"\n                    \"api url. `app` is only for use with ephemeral instances. Provide \"\n                    \"it as the `api` parameter instead.\"\n                )\n            httpx_settings.setdefault(\"base_url\", api)\n\n            # See https://www.python-httpx.org/advanced/#pool-limit-configuration\n            httpx_settings.setdefault(\n                \"limits\",\n                httpx.Limits(\n                    # We see instability when allowing the client to open many connections at once.\n                    # Limiting concurrency results in more stable performance.\n                    max_connections=16,\n                    max_keepalive_connections=8,\n                    # The Prefect Cloud LB will keep connections alive for 30s.\n                    # Only allow the client to keep connections alive for 25s.\n                    keepalive_expiry=25,\n                ),\n            )\n\n            # See https://www.python-httpx.org/http2/\n            # Enabling HTTP/2 support on the client does not necessarily mean that your requests\n            # and responses will be transported over HTTP/2, since both the client and the server\n            # need to support HTTP/2. If you connect to a server that only supports HTTP/1.1 the\n            # client will use a standard HTTP/1.1 connection instead.\n            httpx_settings.setdefault(\"http2\", PREFECT_API_ENABLE_HTTP2.value())\n\n            self.server_type = (\n                ServerType.CLOUD\n                if api.startswith(PREFECT_CLOUD_API_URL.value())\n                else ServerType.SERVER\n            )\n\n        # Connect to an in-process application\n        elif isinstance(api, ASGIApp):\n            self._ephemeral_app = api\n            self.server_type = ServerType.EPHEMERAL\n\n        else:\n            raise TypeError(\n                f\"Unexpected type {type(api).__name__!r} for argument `api`. Expected\"\n                \" 'str' or 'ASGIApp/FastAPI'\"\n            )\n\n        # See https://www.python-httpx.org/advanced/#timeout-configuration\n        httpx_settings.setdefault(\n            \"timeout\",\n            httpx.Timeout(\n                connect=PREFECT_API_REQUEST_TIMEOUT.value(),\n                read=PREFECT_API_REQUEST_TIMEOUT.value(),\n                write=PREFECT_API_REQUEST_TIMEOUT.value(),\n                pool=PREFECT_API_REQUEST_TIMEOUT.value(),\n            ),\n        )\n\n        if not PREFECT_UNIT_TEST_MODE:\n            httpx_settings.setdefault(\"follow_redirects\", True)\n\n        enable_csrf_support = (\n            self.server_type != ServerType.CLOUD\n            and PREFECT_CLIENT_CSRF_SUPPORT_ENABLED.value()\n        )\n\n        if self.server_type == ServerType.EPHEMERAL:\n            self._client = PrefectHttpxSyncEphemeralClient(\n                api, base_url=\"http://ephemeral-prefect/api\"\n            )\n        else:\n            self._client = PrefectHttpxSyncClient(\n                **httpx_settings, enable_csrf_support=enable_csrf_support\n            )\n\n        # See https://www.python-httpx.org/advanced/#custom-transports\n        #\n        # If we're using an HTTP/S client (not the ephemeral client), adjust the\n        # transport to add retries _after_ it is instantiated. If we alter the transport\n        # before instantiation, the transport will not be aware of proxies unless we\n        # reproduce all of the logic to make it so.\n        #\n        # Only alter the transport to set our default of 3 retries, don't modify any\n        # transport a user may have provided via httpx_settings.\n        #\n        # Making liberal use of getattr and isinstance checks here to avoid any\n        # surprises if the internals of httpx or httpcore change on us\n        if isinstance(api, str) and not httpx_settings.get(\"transport\"):\n            transport_for_url = getattr(self._client, \"_transport_for_url\", None)\n            if callable(transport_for_url):\n                server_transport = transport_for_url(httpx.URL(api))\n                if isinstance(server_transport, httpx.HTTPTransport):\n                    pool = getattr(server_transport, \"_pool\", None)\n                    if isinstance(pool, httpcore.ConnectionPool):\n                        pool._retries = 3\n\n        self.logger = get_logger(\"client\")\n\n    @property\n    def api_url(self) -&gt; httpx.URL:\n        \"\"\"\n        Get the base URL for the API.\n        \"\"\"\n        return self._client.base_url\n\n    # Context management ----------------------------------------------------------------\n\n    def __enter__(self) -&gt; \"SyncPrefectClient\":\n        \"\"\"\n        Start the client.\n\n        If the client is already started, this will raise an exception.\n\n        If the client is already closed, this will raise an exception. Use a new client\n        instance instead.\n        \"\"\"\n        if self._closed:\n            # httpx.Client does not allow reuse so we will not either.\n            raise RuntimeError(\n                \"The client cannot be started again after closing. \"\n                \"Retrieve a new client with `get_client()` instead.\"\n            )\n\n        if self._started:\n            # httpx.Client does not allow reentrancy so we will not either.\n            raise RuntimeError(\"The client cannot be started more than once.\")\n        self._client.__enter__()\n        self._started = True\n\n        return self\n\n    def __exit__(self, *exc_info) -&gt; None:\n        \"\"\"\n        Shutdown the client.\n        \"\"\"\n        self._closed = True\n        self._client.__exit__(*exc_info)\n\n    # API methods ----------------------------------------------------------------------\n\n    def api_healthcheck(self) -&gt; Optional[Exception]:\n        \"\"\"\n        Attempts to connect to the API and returns the encountered exception if not\n        successful.\n\n        If successful, returns `None`.\n        \"\"\"\n        try:\n            self._client.get(\"/health\")\n            return None\n        except Exception as exc:\n            return exc\n\n    def hello(self) -&gt; httpx.Response:\n        \"\"\"\n        Send a GET request to /hello for testing purposes.\n        \"\"\"\n        return self._client.get(\"/hello\")\n\n    def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow: a [Flow][prefect.flows.Flow] object\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        return self.create_flow_from_name(flow.name)\n\n    def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n        \"\"\"\n        Create a flow in the Prefect API.\n\n        Args:\n            flow_name: the name of the new flow\n\n        Raises:\n            httpx.RequestError: if a flow was not created for any reason\n\n        Returns:\n            the ID of the flow in the backend\n        \"\"\"\n        flow_data = FlowCreate(name=flow_name)\n        response = self._client.post(\n            \"/flows/\", json=flow_data.dict(json_compatible=True)\n        )\n\n        flow_id = response.json().get(\"id\")\n        if not flow_id:\n            raise httpx.RequestError(f\"Malformed response: {response}\")\n\n        # Return the id of the created flow\n        return UUID(flow_id)\n\n    def create_flow_run(\n        self,\n        flow: \"FlowObject\",\n        name: Optional[str] = None,\n        parameters: Optional[Dict[str, Any]] = None,\n        context: Optional[Dict[str, Any]] = None,\n        tags: Optional[Iterable[str]] = None,\n        parent_task_run_id: Optional[UUID] = None,\n        state: Optional[\"prefect.states.State\"] = None,\n    ) -&gt; FlowRun:\n        \"\"\"\n        Create a flow run for a flow.\n\n        Args:\n            flow: The flow model to create the flow run for\n            name: An optional name for the flow run\n            parameters: Parameter overrides for this flow run.\n            context: Optional run context data\n            tags: a list of tags to apply to this flow run\n            parent_task_run_id: if a subflow run is being created, the placeholder task\n                run identifier in the parent flow\n            state: The initial state for the run. If not provided, defaults to\n                `Scheduled` for now. Should always be a `Scheduled` type.\n\n        Raises:\n            httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n        Returns:\n            The flow run model\n        \"\"\"\n        parameters = parameters or {}\n        context = context or {}\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        # Retrieve the flow id\n        flow_id = self.create_flow(flow)\n\n        flow_run_create = FlowRunCreate(\n            flow_id=flow_id,\n            flow_version=flow.version,\n            name=name,\n            parameters=parameters,\n            context=context,\n            tags=list(tags or []),\n            parent_task_run_id=parent_task_run_id,\n            state=state.to_state_create(),\n            empirical_policy=FlowRunPolicy(\n                retries=flow.retries,\n                retry_delay=flow.retry_delay_seconds,\n            ),\n        )\n\n        flow_run_create_json = flow_run_create.dict(json_compatible=True)\n        response = self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n        flow_run = FlowRun.parse_obj(response.json())\n\n        # Restore the parameters to the local objects to retain expectations about\n        # Python objects\n        flow_run.parameters = parameters\n\n        return flow_run\n\n    def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n        \"\"\"\n        Query the Prefect API for a flow run by id.\n\n        Args:\n            flow_run_id: the flow run ID of interest\n\n        Returns:\n            a Flow Run model representation of the flow run\n        \"\"\"\n        try:\n            response = self._client.get(f\"/flow_runs/{flow_run_id}\")\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == 404:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n        return FlowRun.parse_obj(response.json())\n\n    def read_flow_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        work_pool_filter: WorkPoolFilter = None,\n        work_queue_filter: WorkQueueFilter = None,\n        sort: FlowRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[FlowRun]:\n        \"\"\"\n        Query the Prefect API for flow runs. Only flow runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            work_pool_filter: filter criteria for work pools\n            work_queue_filter: filter criteria for work pool queues\n            sort: sort criteria for the flow runs\n            limit: limit for the flow run query\n            offset: offset for the flow run query\n\n        Returns:\n            a list of Flow Run model representations\n                of the flow runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"work_pools\": (\n                work_pool_filter.dict(json_compatible=True)\n                if work_pool_filter\n                else None\n            ),\n            \"work_pool_queues\": (\n                work_queue_filter.dict(json_compatible=True)\n                if work_queue_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n\n        response = self._client.post(\"/flow_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[FlowRun], response.json())\n\n    def set_flow_run_state(\n        self,\n        flow_run_id: UUID,\n        state: \"prefect.states.State\",\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a flow run.\n\n        Args:\n            flow_run_id: the id of the flow run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.flow_run_id = flow_run_id\n        state_create.state_details.transition_id = uuid4()\n        try:\n            response = self._client.post(\n                f\"/flow_runs/{flow_run_id}/set_state\",\n                json=dict(state=state_create.dict(json_compatible=True), force=force),\n            )\n        except httpx.HTTPStatusError as e:\n            if e.response.status_code == status.HTTP_404_NOT_FOUND:\n                raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n            else:\n                raise\n\n        return OrchestrationResult.parse_obj(response.json())\n\n    def create_task_run(\n        self,\n        task: \"TaskObject[P, R]\",\n        flow_run_id: Optional[UUID],\n        dynamic_key: str,\n        name: Optional[str] = None,\n        extra_tags: Optional[Iterable[str]] = None,\n        state: Optional[prefect.states.State[R]] = None,\n        task_inputs: Optional[\n            Dict[\n                str,\n                List[\n                    Union[\n                        TaskRunResult,\n                        Parameter,\n                        Constant,\n                    ]\n                ],\n            ]\n        ] = None,\n    ) -&gt; TaskRun:\n        \"\"\"\n        Create a task run\n\n        Args:\n            task: The Task to run\n            flow_run_id: The flow run id with which to associate the task run\n            dynamic_key: A key unique to this particular run of a Task within the flow\n            name: An optional name for the task run\n            extra_tags: an optional list of extra tags to apply to the task run in\n                addition to `task.tags`\n            state: The initial state for the run. If not provided, defaults to\n                `Pending` for now. Should always be a `Scheduled` type.\n            task_inputs: the set of inputs passed to the task\n\n        Returns:\n            The created task run.\n        \"\"\"\n        tags = set(task.tags).union(extra_tags or [])\n\n        if state is None:\n            state = prefect.states.Pending()\n\n        task_run_data = TaskRunCreate(\n            name=name,\n            flow_run_id=flow_run_id,\n            task_key=task.task_key,\n            dynamic_key=dynamic_key,\n            tags=list(tags),\n            task_version=task.version,\n            empirical_policy=TaskRunPolicy(\n                retries=task.retries,\n                retry_delay=task.retry_delay_seconds,\n                retry_jitter_factor=task.retry_jitter_factor,\n            ),\n            state=state.to_state_create(),\n            task_inputs=task_inputs or {},\n        )\n\n        response = self._client.post(\n            \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n        )\n        return TaskRun.parse_obj(response.json())\n\n    def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n        \"\"\"\n        Query the Prefect API for a task run by id.\n\n        Args:\n            task_run_id: the task run ID of interest\n\n        Returns:\n            a Task Run model representation of the task run\n        \"\"\"\n        response = self._client.get(f\"/task_runs/{task_run_id}\")\n        return TaskRun.parse_obj(response.json())\n\n    def read_task_runs(\n        self,\n        *,\n        flow_filter: FlowFilter = None,\n        flow_run_filter: FlowRunFilter = None,\n        task_run_filter: TaskRunFilter = None,\n        deployment_filter: DeploymentFilter = None,\n        sort: TaskRunSort = None,\n        limit: int = None,\n        offset: int = 0,\n    ) -&gt; List[TaskRun]:\n        \"\"\"\n        Query the Prefect API for task runs. Only task runs matching all criteria will\n        be returned.\n\n        Args:\n            flow_filter: filter criteria for flows\n            flow_run_filter: filter criteria for flow runs\n            task_run_filter: filter criteria for task runs\n            deployment_filter: filter criteria for deployments\n            sort: sort criteria for the task runs\n            limit: a limit for the task run query\n            offset: an offset for the task run query\n\n        Returns:\n            a list of Task Run model representations\n                of the task runs\n        \"\"\"\n        body = {\n            \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n            \"flow_runs\": (\n                flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n                if flow_run_filter\n                else None\n            ),\n            \"task_runs\": (\n                task_run_filter.dict(json_compatible=True) if task_run_filter else None\n            ),\n            \"deployments\": (\n                deployment_filter.dict(json_compatible=True)\n                if deployment_filter\n                else None\n            ),\n            \"sort\": sort,\n            \"limit\": limit,\n            \"offset\": offset,\n        }\n        response = self._client.post(\"/task_runs/filter\", json=body)\n        return pydantic.parse_obj_as(List[TaskRun], response.json())\n\n    def set_task_run_state(\n        self,\n        task_run_id: UUID,\n        state: prefect.states.State,\n        force: bool = False,\n    ) -&gt; OrchestrationResult:\n        \"\"\"\n        Set the state of a task run.\n\n        Args:\n            task_run_id: the id of the task run\n            state: the state to set\n            force: if True, disregard orchestration logic when setting the state,\n                forcing the Prefect API to accept the state\n\n        Returns:\n            an OrchestrationResult model representation of state orchestration output\n        \"\"\"\n        state_create = state.to_state_create()\n        state_create.state_details.task_run_id = task_run_id\n        response = self._client.post(\n            f\"/task_runs/{task_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n        return OrchestrationResult.parse_obj(response.json())\n\n    def read_task_run_states(self, task_run_id: UUID) -&gt; List[prefect.states.State]:\n        \"\"\"\n        Query for the states of a task run\n\n        Args:\n            task_run_id: the id of the task run\n\n        Returns:\n            a list of State model representations of the task run states\n        \"\"\"\n        response = self._client.get(\n            \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n        )\n        return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.api_url","title":"<code>api_url: httpx.URL</code>  <code>property</code>","text":"<p>Get the base URL for the API.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.api_healthcheck","title":"<code>api_healthcheck</code>","text":"<p>Attempts to connect to the API and returns the encountered exception if not successful.</p> <p>If successful, returns <code>None</code>.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def api_healthcheck(self) -&gt; Optional[Exception]:\n    \"\"\"\n    Attempts to connect to the API and returns the encountered exception if not\n    successful.\n\n    If successful, returns `None`.\n    \"\"\"\n    try:\n        self._client.get(\"/health\")\n        return None\n    except Exception as exc:\n        return exc\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.hello","title":"<code>hello</code>","text":"<p>Send a GET request to /hello for testing purposes.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def hello(self) -&gt; httpx.Response:\n    \"\"\"\n    Send a GET request to /hello for testing purposes.\n    \"\"\"\n    return self._client.get(\"/hello\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow","title":"<code>create_flow</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>a Flow object</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow(self, flow: \"FlowObject\") -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow: a [Flow][prefect.flows.Flow] object\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    return self.create_flow_from_name(flow.name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow_from_name","title":"<code>create_flow_from_name</code>","text":"<p>Create a flow in the Prefect API.</p> <p>Parameters:</p> Name Type Description Default <code>flow_name</code> <code>str</code> <p>the name of the new flow</p> required <p>Raises:</p> Type Description <code>RequestError</code> <p>if a flow was not created for any reason</p> <p>Returns:</p> Type Description <code>UUID</code> <p>the ID of the flow in the backend</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow_from_name(self, flow_name: str) -&gt; UUID:\n    \"\"\"\n    Create a flow in the Prefect API.\n\n    Args:\n        flow_name: the name of the new flow\n\n    Raises:\n        httpx.RequestError: if a flow was not created for any reason\n\n    Returns:\n        the ID of the flow in the backend\n    \"\"\"\n    flow_data = FlowCreate(name=flow_name)\n    response = self._client.post(\n        \"/flows/\", json=flow_data.dict(json_compatible=True)\n    )\n\n    flow_id = response.json().get(\"id\")\n    if not flow_id:\n        raise httpx.RequestError(f\"Malformed response: {response}\")\n\n    # Return the id of the created flow\n    return UUID(flow_id)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_flow_run","title":"<code>create_flow_run</code>","text":"<p>Create a flow run for a flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>The flow model to create the flow run for</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the flow run</p> <code>None</code> <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>Parameter overrides for this flow run.</p> <code>None</code> <code>context</code> <code>Optional[Dict[str, Any]]</code> <p>Optional run context data</p> <code>None</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>a list of tags to apply to this flow run</p> <code>None</code> <code>parent_task_run_id</code> <code>Optional[UUID]</code> <p>if a subflow run is being created, the placeholder task run identifier in the parent flow</p> <code>None</code> <code>state</code> <code>Optional[State]</code> <p>The initial state for the run. If not provided, defaults to <code>Scheduled</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <p>Raises:</p> Type Description <code>RequestError</code> <p>if the Prefect API does not successfully create a run for any reason</p> <p>Returns:</p> Type Description <code>FlowRun</code> <p>The flow run model</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_flow_run(\n    self,\n    flow: \"FlowObject\",\n    name: Optional[str] = None,\n    parameters: Optional[Dict[str, Any]] = None,\n    context: Optional[Dict[str, Any]] = None,\n    tags: Optional[Iterable[str]] = None,\n    parent_task_run_id: Optional[UUID] = None,\n    state: Optional[\"prefect.states.State\"] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a flow.\n\n    Args:\n        flow: The flow model to create the flow run for\n        name: An optional name for the flow run\n        parameters: Parameter overrides for this flow run.\n        context: Optional run context data\n        tags: a list of tags to apply to this flow run\n        parent_task_run_id: if a subflow run is being created, the placeholder task\n            run identifier in the parent flow\n        state: The initial state for the run. If not provided, defaults to\n            `Scheduled` for now. Should always be a `Scheduled` type.\n\n    Raises:\n        httpx.RequestError: if the Prefect API does not successfully create a run for any reason\n\n    Returns:\n        The flow run model\n    \"\"\"\n    parameters = parameters or {}\n    context = context or {}\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    # Retrieve the flow id\n    flow_id = self.create_flow(flow)\n\n    flow_run_create = FlowRunCreate(\n        flow_id=flow_id,\n        flow_version=flow.version,\n        name=name,\n        parameters=parameters,\n        context=context,\n        tags=list(tags or []),\n        parent_task_run_id=parent_task_run_id,\n        state=state.to_state_create(),\n        empirical_policy=FlowRunPolicy(\n            retries=flow.retries,\n            retry_delay=flow.retry_delay_seconds,\n        ),\n    )\n\n    flow_run_create_json = flow_run_create.dict(json_compatible=True)\n    response = self._client.post(\"/flow_runs/\", json=flow_run_create_json)\n    flow_run = FlowRun.parse_obj(response.json())\n\n    # Restore the parameters to the local objects to retain expectations about\n    # Python objects\n    flow_run.parameters = parameters\n\n    return flow_run\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_flow_run","title":"<code>read_flow_run</code>","text":"<p>Query the Prefect API for a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the flow run ID of interest</p> required <p>Returns:</p> Type Description <code>FlowRun</code> <p>a Flow Run model representation of the flow run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_flow_run(self, flow_run_id: UUID) -&gt; FlowRun:\n    \"\"\"\n    Query the Prefect API for a flow run by id.\n\n    Args:\n        flow_run_id: the flow run ID of interest\n\n    Returns:\n        a Flow Run model representation of the flow run\n    \"\"\"\n    try:\n        response = self._client.get(f\"/flow_runs/{flow_run_id}\")\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == 404:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n    return FlowRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_flow_runs","title":"<code>read_flow_runs</code>","text":"<p>Query the Prefect API for flow runs. Only flow runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>filter criteria for work pools</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>filter criteria for work pool queues</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>sort criteria for the flow runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>limit for the flow run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>offset for the flow run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[FlowRun]</code> <p>a list of Flow Run model representations of the flow runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_flow_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    work_pool_filter: WorkPoolFilter = None,\n    work_queue_filter: WorkQueueFilter = None,\n    sort: FlowRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[FlowRun]:\n    \"\"\"\n    Query the Prefect API for flow runs. Only flow runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        work_pool_filter: filter criteria for work pools\n        work_queue_filter: filter criteria for work pool queues\n        sort: sort criteria for the flow runs\n        limit: limit for the flow run query\n        offset: offset for the flow run query\n\n    Returns:\n        a list of Flow Run model representations\n            of the flow runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"work_pools\": (\n            work_pool_filter.dict(json_compatible=True)\n            if work_pool_filter\n            else None\n        ),\n        \"work_pool_queues\": (\n            work_queue_filter.dict(json_compatible=True)\n            if work_queue_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n\n    response = self._client.post(\"/flow_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[FlowRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.set_flow_run_state","title":"<code>set_flow_run_state</code>","text":"<p>Set the state of a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run_id</code> <code>UUID</code> <p>the id of the flow run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def set_flow_run_state(\n    self,\n    flow_run_id: UUID,\n    state: \"prefect.states.State\",\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a flow run.\n\n    Args:\n        flow_run_id: the id of the flow run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.flow_run_id = flow_run_id\n    state_create.state_details.transition_id = uuid4()\n    try:\n        response = self._client.post(\n            f\"/flow_runs/{flow_run_id}/set_state\",\n            json=dict(state=state_create.dict(json_compatible=True), force=force),\n        )\n    except httpx.HTTPStatusError as e:\n        if e.response.status_code == status.HTTP_404_NOT_FOUND:\n            raise prefect.exceptions.ObjectNotFound(http_exc=e) from e\n        else:\n            raise\n\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.create_task_run","title":"<code>create_task_run</code>","text":"<p>Create a task run</p> <p>Parameters:</p> Name Type Description Default <code>task</code> <code>Task[P, R]</code> <p>The Task to run</p> required <code>flow_run_id</code> <code>Optional[UUID]</code> <p>The flow run id with which to associate the task run</p> required <code>dynamic_key</code> <code>str</code> <p>A key unique to this particular run of a Task within the flow</p> required <code>name</code> <code>Optional[str]</code> <p>An optional name for the task run</p> <code>None</code> <code>extra_tags</code> <code>Optional[Iterable[str]]</code> <p>an optional list of extra tags to apply to the task run in addition to <code>task.tags</code></p> <code>None</code> <code>state</code> <code>Optional[State[R]]</code> <p>The initial state for the run. If not provided, defaults to <code>Pending</code> for now. Should always be a <code>Scheduled</code> type.</p> <code>None</code> <code>task_inputs</code> <code>Optional[Dict[str, List[Union[TaskRunResult, Parameter, Constant]]]]</code> <p>the set of inputs passed to the task</p> <code>None</code> <p>Returns:</p> Type Description <code>TaskRun</code> <p>The created task run.</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def create_task_run(\n    self,\n    task: \"TaskObject[P, R]\",\n    flow_run_id: Optional[UUID],\n    dynamic_key: str,\n    name: Optional[str] = None,\n    extra_tags: Optional[Iterable[str]] = None,\n    state: Optional[prefect.states.State[R]] = None,\n    task_inputs: Optional[\n        Dict[\n            str,\n            List[\n                Union[\n                    TaskRunResult,\n                    Parameter,\n                    Constant,\n                ]\n            ],\n        ]\n    ] = None,\n) -&gt; TaskRun:\n    \"\"\"\n    Create a task run\n\n    Args:\n        task: The Task to run\n        flow_run_id: The flow run id with which to associate the task run\n        dynamic_key: A key unique to this particular run of a Task within the flow\n        name: An optional name for the task run\n        extra_tags: an optional list of extra tags to apply to the task run in\n            addition to `task.tags`\n        state: The initial state for the run. If not provided, defaults to\n            `Pending` for now. Should always be a `Scheduled` type.\n        task_inputs: the set of inputs passed to the task\n\n    Returns:\n        The created task run.\n    \"\"\"\n    tags = set(task.tags).union(extra_tags or [])\n\n    if state is None:\n        state = prefect.states.Pending()\n\n    task_run_data = TaskRunCreate(\n        name=name,\n        flow_run_id=flow_run_id,\n        task_key=task.task_key,\n        dynamic_key=dynamic_key,\n        tags=list(tags),\n        task_version=task.version,\n        empirical_policy=TaskRunPolicy(\n            retries=task.retries,\n            retry_delay=task.retry_delay_seconds,\n            retry_jitter_factor=task.retry_jitter_factor,\n        ),\n        state=state.to_state_create(),\n        task_inputs=task_inputs or {},\n    )\n\n    response = self._client.post(\n        \"/task_runs/\", json=task_run_data.dict(json_compatible=True)\n    )\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_run","title":"<code>read_task_run</code>","text":"<p>Query the Prefect API for a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the task run ID of interest</p> required <p>Returns:</p> Type Description <code>TaskRun</code> <p>a Task Run model representation of the task run</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_run(self, task_run_id: UUID) -&gt; TaskRun:\n    \"\"\"\n    Query the Prefect API for a task run by id.\n\n    Args:\n        task_run_id: the task run ID of interest\n\n    Returns:\n        a Task Run model representation of the task run\n    \"\"\"\n    response = self._client.get(f\"/task_runs/{task_run_id}\")\n    return TaskRun.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_runs","title":"<code>read_task_runs</code>","text":"<p>Query the Prefect API for task runs. Only task runs matching all criteria will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>flow_filter</code> <code>FlowFilter</code> <p>filter criteria for flows</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>filter criteria for flow runs</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>filter criteria for task runs</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>filter criteria for deployments</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>sort criteria for the task runs</p> <code>None</code> <code>limit</code> <code>int</code> <p>a limit for the task run query</p> <code>None</code> <code>offset</code> <code>int</code> <p>an offset for the task run query</p> <code>0</code> <p>Returns:</p> Type Description <code>List[TaskRun]</code> <p>a list of Task Run model representations of the task runs</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_runs(\n    self,\n    *,\n    flow_filter: FlowFilter = None,\n    flow_run_filter: FlowRunFilter = None,\n    task_run_filter: TaskRunFilter = None,\n    deployment_filter: DeploymentFilter = None,\n    sort: TaskRunSort = None,\n    limit: int = None,\n    offset: int = 0,\n) -&gt; List[TaskRun]:\n    \"\"\"\n    Query the Prefect API for task runs. Only task runs matching all criteria will\n    be returned.\n\n    Args:\n        flow_filter: filter criteria for flows\n        flow_run_filter: filter criteria for flow runs\n        task_run_filter: filter criteria for task runs\n        deployment_filter: filter criteria for deployments\n        sort: sort criteria for the task runs\n        limit: a limit for the task run query\n        offset: an offset for the task run query\n\n    Returns:\n        a list of Task Run model representations\n            of the task runs\n    \"\"\"\n    body = {\n        \"flows\": flow_filter.dict(json_compatible=True) if flow_filter else None,\n        \"flow_runs\": (\n            flow_run_filter.dict(json_compatible=True, exclude_unset=True)\n            if flow_run_filter\n            else None\n        ),\n        \"task_runs\": (\n            task_run_filter.dict(json_compatible=True) if task_run_filter else None\n        ),\n        \"deployments\": (\n            deployment_filter.dict(json_compatible=True)\n            if deployment_filter\n            else None\n        ),\n        \"sort\": sort,\n        \"limit\": limit,\n        \"offset\": offset,\n    }\n    response = self._client.post(\"/task_runs/filter\", json=body)\n    return pydantic.parse_obj_as(List[TaskRun], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.set_task_run_state","title":"<code>set_task_run_state</code>","text":"<p>Set the state of a task run.</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <code>state</code> <code>State</code> <p>the state to set</p> required <code>force</code> <code>bool</code> <p>if True, disregard orchestration logic when setting the state, forcing the Prefect API to accept the state</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>an OrchestrationResult model representation of state orchestration output</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def set_task_run_state(\n    self,\n    task_run_id: UUID,\n    state: prefect.states.State,\n    force: bool = False,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Set the state of a task run.\n\n    Args:\n        task_run_id: the id of the task run\n        state: the state to set\n        force: if True, disregard orchestration logic when setting the state,\n            forcing the Prefect API to accept the state\n\n    Returns:\n        an OrchestrationResult model representation of state orchestration output\n    \"\"\"\n    state_create = state.to_state_create()\n    state_create.state_details.task_run_id = task_run_id\n    response = self._client.post(\n        f\"/task_runs/{task_run_id}/set_state\",\n        json=dict(state=state_create.dict(json_compatible=True), force=force),\n    )\n    return OrchestrationResult.parse_obj(response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.SyncPrefectClient.read_task_run_states","title":"<code>read_task_run_states</code>","text":"<p>Query for the states of a task run</p> <p>Parameters:</p> Name Type Description Default <code>task_run_id</code> <code>UUID</code> <p>the id of the task run</p> required <p>Returns:</p> Type Description <code>List[State]</code> <p>a list of State model representations of the task run states</p> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def read_task_run_states(self, task_run_id: UUID) -&gt; List[prefect.states.State]:\n    \"\"\"\n    Query for the states of a task run\n\n    Args:\n        task_run_id: the id of the task run\n\n    Returns:\n        a list of State model representations of the task run states\n    \"\"\"\n    response = self._client.get(\n        \"/task_run_states/\", params=dict(task_run_id=str(task_run_id))\n    )\n    return pydantic.parse_obj_as(List[prefect.states.State], response.json())\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/orchestration/#prefect.client.orchestration.get_client","title":"<code>get_client</code>","text":"<p>Retrieve a HTTP client for communicating with the Prefect REST API.</p> <p>The client must be context managed; for example:</p> <pre><code>async with get_client() as client:\n    await client.hello()\n</code></pre> <p>To return a synchronous client, pass sync_client=True:</p> <pre><code>with get_client(sync_client=True) as client:\n    client.hello()\n</code></pre> Source code in <code>prefect/client/orchestration.py</code> <pre><code>def get_client(\n    httpx_settings: Optional[Dict[str, Any]] = None, sync_client: bool = False\n) -&gt; Union[\"PrefectClient\", \"SyncPrefectClient\"]:\n    \"\"\"\n    Retrieve a HTTP client for communicating with the Prefect REST API.\n\n    The client must be context managed; for example:\n\n    ```python\n    async with get_client() as client:\n        await client.hello()\n    ```\n\n    To return a synchronous client, pass sync_client=True:\n\n    ```python\n    with get_client(sync_client=True) as client:\n        client.hello()\n    ```\n    \"\"\"\n    ctx = prefect.context.get_settings_context()\n    api = PREFECT_API_URL.value()\n\n    if not api:\n        # create an ephemeral API if none was provided\n        from prefect.server.api.server import create_app\n\n        api = create_app(ctx.settings, ephemeral=True)\n\n    if sync_client:\n        return SyncPrefectClient(\n            api,\n            api_key=PREFECT_API_KEY.value(),\n            httpx_settings=httpx_settings,\n        )\n    else:\n        return PrefectClient(\n            api,\n            api_key=PREFECT_API_KEY.value(),\n            httpx_settings=httpx_settings,\n        )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_1","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions","title":"<code>prefect.client.schemas.actions</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.StateCreate","title":"<code>StateCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a new state.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class StateCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a new state.\"\"\"\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    state_details: StateDetails = Field(default_factory=StateDetails)\n    data: Union[\"BaseResult[R]\", \"DataDocument[R]\", Any] = Field(\n        default=None,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowCreate","title":"<code>FlowCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowUpdate","title":"<code>FlowUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow.\"\"\"\n\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentCreate","title":"<code>DeploymentCreate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentCreate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    name: str = Field(..., description=\"The name of the deployment.\")\n    flow_id: UUID = Field(..., description=\"The ID of the flow to deploy.\")\n    is_schedule_active: Optional[bool] = Field(None)\n    paused: Optional[bool] = Field(None)\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(None)\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(default_factory=list)\n    pull_steps: Optional[List[dict]] = Field(None)\n\n    manifest_path: Optional[str] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    schedule: Optional[SCHEDULE_TYPES] = Field(None)\n    description: Optional[str] = Field(None)\n    path: Optional[str] = Field(None)\n    version: Optional[str] = Field(None)\n    entrypoint: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"Check that the combination of base_job_template defaults\n        and job_variables conforms to the specified schema.\n        \"\"\"\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            # jsonschema considers required fields, even if that field has a default,\n            # to still be required. To get around this we remove the fields from\n            # required if there is a default present.\n            required = variables_schema.get(\"required\")\n            properties = variables_schema.get(\"properties\")\n            if required is not None and properties is not None:\n                for k, v in properties.items():\n                    if \"default\" in v and k in required:\n                        required.remove(k)\n\n            jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentCreate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"Check that the combination of base_job_template defaults\n    and job_variables conforms to the specified schema.\n    \"\"\"\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        # jsonschema considers required fields, even if that field has a default,\n        # to still be required. To get around this we remove the fields from\n        # required if there is a default present.\n        required = variables_schema.get(\"required\")\n        properties = variables_schema.get(\"properties\")\n        if required is not None and properties is not None:\n            for k, v in properties.items():\n                if \"default\" in v and k in required:\n                    required.remove(k)\n\n        jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentUpdate","title":"<code>DeploymentUpdate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentUpdate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    @validator(\"schedule\")\n    def validate_none_schedule(cls, v):\n        return return_none_schedule(v)\n\n    version: Optional[str] = Field(None)\n    schedule: Optional[SCHEDULE_TYPES] = Field(None)\n    description: Optional[str] = Field(None)\n    is_schedule_active: bool = Field(None)\n    parameters: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(default_factory=list)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    path: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    entrypoint: Optional[str] = Field(None)\n    manifest_path: Optional[str] = Field(None)\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"Check that the combination of base_job_template defaults\n        and job_variables conforms to the specified schema.\n        \"\"\"\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            # jsonschema considers required fields, even if that field has a default,\n            # to still be required. To get around this we remove the fields from\n            # required if there is a default present.\n            required = variables_schema.get(\"required\")\n            properties = variables_schema.get(\"properties\")\n            if required is not None and properties is not None:\n                for k, v in properties.items():\n                    if \"default\" in v and k in required:\n                        required.remove(k)\n\n        if variables_schema is not None:\n            jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentUpdate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"Check that the combination of base_job_template defaults\n    and job_variables conforms to the specified schema.\n    \"\"\"\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        # jsonschema considers required fields, even if that field has a default,\n        # to still be required. To get around this we remove the fields from\n        # required if there is a default present.\n        required = variables_schema.get(\"required\")\n        properties = variables_schema.get(\"properties\")\n        if required is not None and properties is not None:\n            for k, v in properties.items():\n                if \"default\" in v and k in required:\n                    required.remove(k)\n\n    if variables_schema is not None:\n        jsonschema.validate(self.job_variables, variables_schema)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunUpdate","title":"<code>FlowRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run.\"\"\"\n\n    name: Optional[str] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Optional[Dict[str, Any]] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    infrastructure_pid: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.TaskRunCreate","title":"<code>TaskRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a task run</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class TaskRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a task run\"\"\"\n\n    # TaskRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the task run to create\"\n    )\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the task run\",\n    )\n    flow_run_id: Optional[UUID] = Field(None)\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(None)\n    cache_expiration: Optional[objects.DateTimeTZ] = Field(None)\n    task_version: Optional[str] = Field(None)\n    empirical_policy: objects.TaskRunPolicy = Field(\n        default_factory=objects.TaskRunPolicy,\n    )\n    tags: List[str] = Field(default_factory=list)\n    task_inputs: Dict[\n        str,\n        List[\n            Union[\n                objects.TaskRunResult,\n                objects.Parameter,\n                objects.Constant,\n            ]\n        ],\n    ] = Field(default_factory=dict)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.TaskRunUpdate","title":"<code>TaskRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a task run</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class TaskRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a task run\"\"\"\n\n    name: Optional[str] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunCreate","title":"<code>FlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: Optional[str] = Field(default=None, description=\"The name of the flow run.\")\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    deployment_id: Optional[UUID] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The parameters for the flow run.\"\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The context for the flow run.\"\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    idempotency_key: Optional[str] = Field(None)\n\n    class Config(ActionBaseModel.Config):\n        json_dumps = orjson_dumps_extra_compatible\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.DeploymentFlowRunCreate","title":"<code>DeploymentFlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run from a deployment.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class DeploymentFlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run from a deployment.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: Optional[str] = Field(default=None, description=\"The name of the flow run.\")\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The parameters for the flow run.\"\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The context for the flow run.\"\n    )\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    idempotency_key: Optional[str] = Field(None)\n    parent_task_run_id: Optional[UUID] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    job_variables: Optional[dict] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.SavedSearchCreate","title":"<code>SavedSearchCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a saved search.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class SavedSearchCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a saved search.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[objects.SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ConcurrencyLimitCreate","title":"<code>ConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockTypeCreate","title":"<code>BlockTypeCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block type.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockTypeCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block type.\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[objects.HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[objects.HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n\n    # validators\n    _validate_slug_format = validator(\"slug\", allow_reuse=True)(\n        validate_block_type_slug\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockTypeUpdate","title":"<code>BlockTypeUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block type.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockTypeUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block type.\"\"\"\n\n    logo_url: Optional[objects.HttpUrl] = Field(None)\n    documentation_url: Optional[objects.HttpUrl] = Field(None)\n    description: Optional[str] = Field(None)\n    code_example: Optional[str] = Field(None)\n\n    @classmethod\n    def updatable_fields(cls) -&gt; set:\n        return get_class_fields_only(cls)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockSchemaCreate","title":"<code>BlockSchemaCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block schema.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockSchemaCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block schema.\"\"\"\n\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(None)\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=objects.DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentCreate","title":"<code>BlockDocumentCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block document.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None, description=\"The name of the block document\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(\n        default=..., description=\"The block schema ID for the block document\"\n    )\n    block_type_id: UUID = Field(\n        default=..., description=\"The block type ID for the block document\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    _validate_name_format = validator(\"name\", allow_reuse=True)(\n        validate_block_document_name\n    )\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentUpdate","title":"<code>BlockDocumentUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block document.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block document.\"\"\"\n\n    block_schema_id: Optional[UUID] = Field(\n        default=None, description=\"A block schema ID\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    merge_existing_data: bool = Field(\n        default=True,\n        description=\"Whether to merge the existing data with the new data or replace it\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.BlockDocumentReferenceCreate","title":"<code>BlockDocumentReferenceCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used to create block document reference.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class BlockDocumentReferenceCreate(ActionBaseModel):\n    \"\"\"Data used to create block document reference.\"\"\"\n\n    id: UUID = Field(default_factory=uuid4)\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.LogCreate","title":"<code>LogCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a log.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class LogCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a log.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkPoolCreate","title":"<code>WorkPoolCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work pool.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkPoolCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work pool.\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(None)\n    type: str = Field(\n        description=\"The work pool type.\", default=\"prefect-agent\"\n    )  # TODO: change default\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"The base job template for the work pool.\",\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Whether the work pool is paused.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkPoolUpdate","title":"<code>WorkPoolUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work pool.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkPoolUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work pool.\"\"\"\n\n    description: Optional[str] = Field(None)\n    is_paused: Optional[bool] = Field(None)\n    base_job_template: Optional[Dict[str, Any]] = Field(None)\n    concurrency_limit: Optional[int] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkQueueCreate","title":"<code>WorkQueueCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work queue.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkQueueCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work queue.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False,\n        description=\"Whether the work queue is paused.\",\n    )\n    concurrency_limit: Optional[int] = Field(\n        default=None,\n        description=\"A concurrency limit for the work queue.\",\n    )\n    priority: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n\n    # DEPRECATED\n\n    filter: Optional[objects.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.WorkQueueUpdate","title":"<code>WorkQueueUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work queue.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class WorkQueueUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work queue.\"\"\"\n\n    name: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[int] = Field(None)\n    priority: Optional[int] = Field(None)\n    last_polled: Optional[DateTimeTZ] = Field(None)\n\n    # DEPRECATED\n\n    filter: Optional[objects.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunNotificationPolicyCreate","title":"<code>FlowRunNotificationPolicyCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run notification policy.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run notification policy.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(objects.FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.FlowRunNotificationPolicyUpdate","title":"<code>FlowRunNotificationPolicyUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run notification policy.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run notification policy.\"\"\"\n\n    is_active: Optional[bool] = Field(None)\n    state_names: Optional[List[str]] = Field(None)\n    tags: Optional[List[str]] = Field(None)\n    block_document_id: Optional[UUID] = Field(None)\n    message_template: Optional[str] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ArtifactCreate","title":"<code>ArtifactCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create an artifact.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ArtifactCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create an artifact.\"\"\"\n\n    key: Optional[str] = Field(None)\n    type: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n\n    _validate_artifact_format = validator(\"key\", allow_reuse=True)(\n        validate_artifact_key\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.ArtifactUpdate","title":"<code>ArtifactUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update an artifact.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class ArtifactUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update an artifact.\"\"\"\n\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    description: Optional[str] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.VariableCreate","title":"<code>VariableCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a Variable.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class VariableCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a Variable.\"\"\"\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the variable\",\n        examples=[\"my_variable\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: str = Field(\n        default=...,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=objects.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(default=None)\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.VariableUpdate","title":"<code>VariableUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a Variable.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class VariableUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a Variable.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the variable\",\n        examples=[\"my_variable\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: Optional[str] = Field(\n        default=None,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=objects.MAX_VARIABLE_NAME_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(default=None)\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.GlobalConcurrencyLimitCreate","title":"<code>GlobalConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a global concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class GlobalConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a global concurrency limit.\"\"\"\n\n    name: str = Field(description=\"The name of the global concurrency limit.\")\n    limit: NonNegativeInteger = Field(\n        description=(\n            \"The maximum number of slots that can be occupied on this concurrency\"\n            \" limit.\"\n        )\n    )\n    active: Optional[bool] = Field(\n        default=True,\n        description=\"Whether or not the concurrency limit is in an active state.\",\n    )\n    active_slots: Optional[NonNegativeInteger] = Field(\n        default=0,\n        description=\"Number of tasks currently using a concurrency slot.\",\n    )\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(\n        default=0.0,\n        description=(\n            \"Controls the rate at which slots are released when the concurrency limit\"\n            \" is used as a rate limit.\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.actions.GlobalConcurrencyLimitUpdate","title":"<code>GlobalConcurrencyLimitUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a global concurrency limit.</p> Source code in <code>prefect/client/schemas/actions.py</code> <pre><code>class GlobalConcurrencyLimitUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a global concurrency limit.\"\"\"\n\n    name: Optional[str] = Field(None)\n    limit: Optional[NonNegativeInteger] = Field(None)\n    active: Optional[bool] = Field(None)\n    active_slots: Optional[NonNegativeInteger] = Field(None)\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(None)\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_2","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters","title":"<code>prefect.client.schemas.filters</code>","text":"<p>Schemas that define Prefect REST API filtering operations.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.Operator","title":"<code>Operator</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Operators for combining filter criteria.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class Operator(AutoEnum):\n    \"\"\"Operators for combining filter criteria.\"\"\"\n\n    and_ = AutoEnum.auto()\n    or_ = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.OperatorMixin","title":"<code>OperatorMixin</code>","text":"<p>Base model for Prefect filters that combines criteria with a user-provided operator</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class OperatorMixin:\n    \"\"\"Base model for Prefect filters that combines criteria with a user-provided operator\"\"\"\n\n    operator: Operator = Field(\n        default=Operator.and_,\n        description=\"Operator for combining filter criteria. Defaults to 'and_'.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterId","title":"<code>FlowFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Flow.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Flow.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterName","title":"<code>FlowFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Flow.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Flow.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow names to include\",\n        examples=[[\"my-flow-1\", \"my-flow-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilterTags","title":"<code>FlowFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Flow.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Flow.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flows will be returned only if their tags are a superset\"\n            \" of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flows without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowFilter","title":"<code>FlowFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for flows. Only flows matching all criteria will be returned.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for flows. Only flows matching all criteria will be returned.\"\"\"\n\n    id: Optional[FlowFilterId] = Field(\n        default=None, description=\"Filter criteria for `Flow.id`\"\n    )\n    name: Optional[FlowFilterName] = Field(\n        default=None, description=\"Filter criteria for `Flow.name`\"\n    )\n    tags: Optional[FlowFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Flow.tags`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterId","title":"<code>FlowRunFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by FlowRun.id.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterId(PrefectBaseModel):\n    \"\"\"Filter by FlowRun.id.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n    not_any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterName","title":"<code>FlowRunFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterName(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow run names to include\",\n        examples=[[\"my-flow-run-1\", \"my-flow-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterTags","title":"<code>FlowRunFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flow runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flow runs without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterDeploymentId","title":"<code>FlowRunFilterDeploymentId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.deployment_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterDeploymentId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.deployment_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run deployment ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without deployment ids\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterWorkQueueName","title":"<code>FlowRunFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.work_queue_name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterWorkQueueName(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without work queue names\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterStateType","title":"<code>FlowRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterStateType(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.state_type`.\"\"\"\n\n    any_: Optional[List[StateType]] = Field(\n        default=None, description=\"A list of flow run state types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterFlowVersion","title":"<code>FlowRunFilterFlowVersion</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.flow_version</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterFlowVersion(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.flow_version`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run flow_versions to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterStartTime","title":"<code>FlowRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return flow runs without a start time\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterExpectedStartTime","title":"<code>FlowRunFilterExpectedStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.expected_start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterExpectedStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.expected_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or after this time\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterNextScheduledStartTime","title":"<code>FlowRunFilterNextScheduledStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterNextScheduledStartTime(PrefectBaseModel):\n    \"\"\"Filter by `FlowRun.next_scheduled_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time or before this\"\n            \" time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time at or after this\"\n            \" time\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterParentFlowRunId","title":"<code>FlowRunFilterParentFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for subflows of the given flow runs</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterParentFlowRunId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for subflows of the given flow runs\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parents to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterParentTaskRunId","title":"<code>FlowRunFilterParentTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterParentTaskRunId(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `FlowRun.parent_task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parent_task_run_ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without parent_task_run_id\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilterIdempotencyKey","title":"<code>FlowRunFilterIdempotencyKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by FlowRun.idempotency_key.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilterIdempotencyKey(PrefectBaseModel):\n    \"\"\"Filter by FlowRun.idempotency_key.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunFilter","title":"<code>FlowRunFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter flow runs. Only flow runs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter flow runs. Only flow runs matching all criteria will be returned\"\"\"\n\n    id: Optional[FlowRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.id`\"\n    )\n    name: Optional[FlowRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.name`\"\n    )\n    tags: Optional[FlowRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.tags`\"\n    )\n    deployment_id: Optional[FlowRunFilterDeploymentId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.deployment_id`\"\n    )\n    work_queue_name: Optional[FlowRunFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.work_queue_name\"\n    )\n    state: Optional[FlowRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state`\"\n    )\n    flow_version: Optional[FlowRunFilterFlowVersion] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.flow_version`\"\n    )\n    start_time: Optional[FlowRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.start_time`\"\n    )\n    expected_start_time: Optional[FlowRunFilterExpectedStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.expected_start_time`\"\n    )\n    next_scheduled_start_time: Optional[FlowRunFilterNextScheduledStartTime] = Field(\n        default=None,\n        description=\"Filter criteria for `FlowRun.next_scheduled_start_time`\",\n    )\n    parent_flow_run_id: Optional[FlowRunFilterParentFlowRunId] = Field(\n        default=None, description=\"Filter criteria for subflows of the given flow runs\"\n    )\n    parent_task_run_id: Optional[FlowRunFilterParentTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.parent_task_run_id`\"\n    )\n    idempotency_key: Optional[FlowRunFilterIdempotencyKey] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.idempotency_key`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterFlowRunId","title":"<code>TaskRunFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n\n    is_null_: bool = Field(\n        default=False,\n        description=\"If true, only include task runs without a flow run id\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterId","title":"<code>TaskRunFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterId(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterName","title":"<code>TaskRunFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterName(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of task run names to include\",\n        examples=[[\"my-task-run-1\", \"my-task-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterTags","title":"<code>TaskRunFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>TaskRun.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `TaskRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Task runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include task runs without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterStateType","title":"<code>TaskRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.state_type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterStateType(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.state_type`.\"\"\"\n\n    any_: Optional[List[StateType]] = Field(\n        default=None, description=\"A list of task run state types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterSubFlowRuns","title":"<code>TaskRunFilterSubFlowRuns</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.subflow_run</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterSubFlowRuns(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.subflow_run`.\"\"\"\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If true, only include task runs that are subflow run parents; if false,\"\n            \" exclude parent task runs\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilterStartTime","title":"<code>TaskRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>TaskRun.start_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilterStartTime(PrefectBaseModel):\n    \"\"\"Filter by `TaskRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return task runs without a start time\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.TaskRunFilter","title":"<code>TaskRunFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter task runs. Only task runs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class TaskRunFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter task runs. Only task runs matching all criteria will be returned\"\"\"\n\n    id: Optional[TaskRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.id`\"\n    )\n    name: Optional[TaskRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.name`\"\n    )\n    tags: Optional[TaskRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.tags`\"\n    )\n    state: Optional[TaskRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.state`\"\n    )\n    start_time: Optional[TaskRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.start_time`\"\n    )\n    subflow_runs: Optional[TaskRunFilterSubFlowRuns] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.subflow_run`\"\n    )\n    flow_run_id: Optional[TaskRunFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.flow_run_id`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterId","title":"<code>DeploymentFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of deployment ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterName","title":"<code>DeploymentFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of deployment names to include\",\n        examples=[[\"my-deployment-1\", \"my-deployment-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterWorkQueueName","title":"<code>DeploymentFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.work_queue_name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterWorkQueueName(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterIsScheduleActive","title":"<code>DeploymentFilterIsScheduleActive</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Deployment.is_schedule_active</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterIsScheduleActive(PrefectBaseModel):\n    \"\"\"Filter by `Deployment.is_schedule_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilterTags","title":"<code>DeploymentFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Deployment.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Deployment.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Deployments will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include deployments without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.DeploymentFilter","title":"<code>DeploymentFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class DeploymentFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    id: Optional[DeploymentFilterId] = Field(\n        default=None, description=\"Filter criteria for `Deployment.id`\"\n    )\n    name: Optional[DeploymentFilterName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.name`\"\n    )\n    is_schedule_active: Optional[DeploymentFilterIsScheduleActive] = Field(\n        default=None, description=\"Filter criteria for `Deployment.is_schedule_active`\"\n    )\n    tags: Optional[DeploymentFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Deployment.tags`\"\n    )\n    work_queue_name: Optional[DeploymentFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.work_queue_name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterName","title":"<code>LogFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Log.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of log names to include\",\n        examples=[[\"prefect.logger.flow_runs\", \"prefect.logger.task_runs\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterLevel","title":"<code>LogFilterLevel</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.level</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterLevel(PrefectBaseModel):\n    \"\"\"Filter by `Log.level`.\"\"\"\n\n    ge_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level greater than or equal to this level\",\n        examples=[20],\n    )\n\n    le_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level less than or equal to this level\",\n        examples=[50],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterTimestamp","title":"<code>LogFilterTimestamp</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.timestamp</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterTimestamp(PrefectBaseModel):\n    \"\"\"Filter by `Log.timestamp`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or after this time\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterFlowRunId","title":"<code>LogFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `Log.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilterTaskRunId","title":"<code>LogFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Log.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `Log.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.LogFilter","title":"<code>LogFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter logs. Only logs matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class LogFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter logs. Only logs matching all criteria will be returned\"\"\"\n\n    level: Optional[LogFilterLevel] = Field(\n        default=None, description=\"Filter criteria for `Log.level`\"\n    )\n    timestamp: Optional[LogFilterTimestamp] = Field(\n        default=None, description=\"Filter criteria for `Log.timestamp`\"\n    )\n    flow_run_id: Optional[LogFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.flow_run_id`\"\n    )\n    task_run_id: Optional[LogFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.task_run_id`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FilterSet","title":"<code>FilterSet</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A collection of filters for common objects</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FilterSet(PrefectBaseModel):\n    \"\"\"A collection of filters for common objects\"\"\"\n\n    flows: FlowFilter = Field(\n        default_factory=FlowFilter, description=\"Filters that apply to flows\"\n    )\n    flow_runs: FlowRunFilter = Field(\n        default_factory=FlowRunFilter, description=\"Filters that apply to flow runs\"\n    )\n    task_runs: TaskRunFilter = Field(\n        default_factory=TaskRunFilter, description=\"Filters that apply to task runs\"\n    )\n    deployments: DeploymentFilter = Field(\n        default_factory=DeploymentFilter,\n        description=\"Filters that apply to deployments\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilterName","title":"<code>BlockTypeFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockType.name</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilterName(PrefectBaseModel):\n    \"\"\"Filter by `BlockType.name`\"\"\"\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilterSlug","title":"<code>BlockTypeFilterSlug</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockType.slug</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilterSlug(PrefectBaseModel):\n    \"\"\"Filter by `BlockType.slug`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of slugs to match\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockTypeFilter","title":"<code>BlockTypeFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter BlockTypes</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockTypeFilter(PrefectBaseModel):\n    \"\"\"Filter BlockTypes\"\"\"\n\n    name: Optional[BlockTypeFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockType.name`\"\n    )\n\n    slug: Optional[BlockTypeFilterSlug] = Field(\n        default=None, description=\"Filter criteria for `BlockType.slug`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterBlockTypeId","title":"<code>BlockSchemaFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.block_type_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterBlockTypeId(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterId","title":"<code>BlockSchemaFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by BlockSchema.id</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterId(PrefectBaseModel):\n    \"\"\"Filter by BlockSchema.id\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterCapabilities","title":"<code>BlockSchemaFilterCapabilities</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterCapabilities(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"write-storage\", \"read-storage\"]],\n        description=(\n            \"A list of block capabilities. Block entities will be returned only if an\"\n            \" associated block schema has a superset of the defined capabilities.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilterVersion","title":"<code>BlockSchemaFilterVersion</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilterVersion(PrefectBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"2.0.0\", \"2.1.0\"]],\n        description=\"A list of block schema versions.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockSchemaFilter","title":"<code>BlockSchemaFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter BlockSchemas</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockSchemaFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter BlockSchemas\"\"\"\n\n    block_type_id: Optional[BlockSchemaFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.block_type_id`\"\n    )\n    block_capabilities: Optional[BlockSchemaFilterCapabilities] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.capabilities`\"\n    )\n    id: Optional[BlockSchemaFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.id`\"\n    )\n    version: Optional[BlockSchemaFilterVersion] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.version`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterIsAnonymous","title":"<code>BlockDocumentFilterIsAnonymous</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.is_anonymous</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterIsAnonymous(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.is_anonymous`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter block documents for only those that are or are not anonymous.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterBlockTypeId","title":"<code>BlockDocumentFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.block_type_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterBlockTypeId(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterId","title":"<code>BlockDocumentFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterId(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilterName","title":"<code>BlockDocumentFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>BlockDocument.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilterName(PrefectBaseModel):\n    \"\"\"Filter by `BlockDocument.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of block names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match block names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-block%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.BlockDocumentFilter","title":"<code>BlockDocumentFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class BlockDocumentFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned\"\"\"\n\n    id: Optional[BlockDocumentFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.id`\"\n    )\n    is_anonymous: Optional[BlockDocumentFilterIsAnonymous] = Field(\n        # default is to exclude anonymous blocks\n        BlockDocumentFilterIsAnonymous(eq_=False),\n        description=(\n            \"Filter criteria for `BlockDocument.is_anonymous`. \"\n            \"Defaults to excluding anonymous blocks.\"\n        ),\n    )\n    block_type_id: Optional[BlockDocumentFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.block_type_id`\"\n    )\n    name: Optional[BlockDocumentFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunNotificationPolicyFilterIsActive","title":"<code>FlowRunNotificationPolicyFilterIsActive</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilterIsActive(PrefectBaseModel):\n    \"\"\"Filter by `FlowRunNotificationPolicy.is_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter notification policies for only those that are or are not active.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.FlowRunNotificationPolicyFilter","title":"<code>FlowRunNotificationPolicyFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter FlowRunNotificationPolicies.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilter(PrefectBaseModel):\n    \"\"\"Filter FlowRunNotificationPolicies.\"\"\"\n\n    is_active: Optional[FlowRunNotificationPolicyFilterIsActive] = Field(\n        default=FlowRunNotificationPolicyFilterIsActive(eq_=False),\n        description=\"Filter criteria for `FlowRunNotificationPolicy.is_active`. \",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilterId","title":"<code>WorkQueueFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkQueue.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilterId(PrefectBaseModel):\n    \"\"\"Filter by `WorkQueue.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"A list of work queue ids to include\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilterName","title":"<code>WorkQueueFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkQueue.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilterName(PrefectBaseModel):\n    \"\"\"Filter by `WorkQueue.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"wq-1\", \"wq-2\"]],\n    )\n\n    startswith_: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"A list of case-insensitive starts-with matches. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', and 'Marvin-robot', but not 'sad-marvin'.\"\n        ),\n        examples=[[\"marvin\", \"Marvin-robot\"]],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkQueueFilter","title":"<code>WorkQueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter work queues. Only work queues matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkQueueFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter work queues. Only work queues matching all criteria will be\n    returned\"\"\"\n\n    id: Optional[WorkQueueFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.id`\"\n    )\n\n    name: Optional[WorkQueueFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.name`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterId","title":"<code>WorkPoolFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterId(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterName","title":"<code>WorkPoolFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterName(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool names to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkPoolFilterType","title":"<code>WorkPoolFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>WorkPool.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkPoolFilterType(PrefectBaseModel):\n    \"\"\"Filter by `WorkPool.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool types to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkerFilterWorkPoolId","title":"<code>WorkerFilterWorkPoolId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Worker.worker_config_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkerFilterWorkPoolId(PrefectBaseModel):\n    \"\"\"Filter by `Worker.worker_config_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.WorkerFilterLastHeartbeatTime","title":"<code>WorkerFilterLastHeartbeatTime</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class WorkerFilterLastHeartbeatTime(PrefectBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or before this time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or after this time\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterId","title":"<code>ArtifactFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterKey","title":"<code>ArtifactFilterKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.key</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterKey(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterFlowRunId","title":"<code>ArtifactFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterTaskRunId","title":"<code>ArtifactFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilterType","title":"<code>ArtifactFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Artifact.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilterType(PrefectBaseModel):\n    \"\"\"Filter by `Artifact.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactFilter","title":"<code>ArtifactFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter artifacts. Only artifacts matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter artifacts. Only artifacts matching all criteria will be returned\"\"\"\n\n    id: Optional[ArtifactFilterId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterLatestId","title":"<code>ArtifactCollectionFilterLatestId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.latest_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterLatestId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.latest_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterKey","title":"<code>ArtifactCollectionFilterKey</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.key</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterKey(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key. Should return all rows in \"\n            \"the ArtifactCollection table if specified.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterFlowRunId","title":"<code>ArtifactCollectionFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterFlowRunId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterTaskRunId","title":"<code>ArtifactCollectionFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterTaskRunId(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilterType","title":"<code>ArtifactCollectionFilterType</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>ArtifactCollection.type</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterType(PrefectBaseModel):\n    \"\"\"Filter by `ArtifactCollection.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.ArtifactCollectionFilter","title":"<code>ArtifactCollectionFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter artifact collections. Only artifact collections matching all criteria will be returned\"\"\"\n\n    latest_id: Optional[ArtifactCollectionFilterLatestId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactCollectionFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactCollectionFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactCollectionFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactCollectionFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterId","title":"<code>VariableFilterId</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.id</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterId(PrefectBaseModel):\n    \"\"\"Filter by `Variable.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of variable ids to include\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterName","title":"<code>VariableFilterName</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.name</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterName(PrefectBaseModel):\n    \"\"\"Filter by `Variable.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my_variable_%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterValue","title":"<code>VariableFilterValue</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter by <code>Variable.value</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterValue(PrefectBaseModel):\n    \"\"\"Filter by `Variable.value`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables value to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable value against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-value-%\"],\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilterTags","title":"<code>VariableFilterTags</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter by <code>Variable.tags</code>.</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilterTags(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter by `Variable.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Variables will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include Variables without tags\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.filters.VariableFilter","title":"<code>VariableFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code>, <code>OperatorMixin</code></p> <p>Filter variables. Only variables matching all criteria will be returned</p> Source code in <code>prefect/client/schemas/filters.py</code> <pre><code>class VariableFilter(PrefectBaseModel, OperatorMixin):\n    \"\"\"Filter variables. Only variables matching all criteria will be returned\"\"\"\n\n    id: Optional[VariableFilterId] = Field(\n        default=None, description=\"Filter criteria for `Variable.id`\"\n    )\n    name: Optional[VariableFilterName] = Field(\n        default=None, description=\"Filter criteria for `Variable.name`\"\n    )\n    value: Optional[VariableFilterValue] = Field(\n        default=None, description=\"Filter criteria for `Variable.value`\"\n    )\n    tags: Optional[VariableFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Variable.tags`\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_3","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects","title":"<code>prefect.client.schemas.objects</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.StateType","title":"<code>StateType</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of state types.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class StateType(AutoEnum):\n    \"\"\"Enumeration of state types.\"\"\"\n\n    SCHEDULED = AutoEnum.auto()\n    PENDING = AutoEnum.auto()\n    RUNNING = AutoEnum.auto()\n    COMPLETED = AutoEnum.auto()\n    FAILED = AutoEnum.auto()\n    CANCELLED = AutoEnum.auto()\n    CRASHED = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n    CANCELLING = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkPoolStatus","title":"<code>WorkPoolStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of work pool statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkPoolStatus(AutoEnum):\n    \"\"\"Enumeration of work pool statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n\n    @property\n    def display_name(self):\n        return self.name.replace(\"_\", \" \").capitalize()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkerStatus","title":"<code>WorkerStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of worker statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkerStatus(AutoEnum):\n    \"\"\"Enumeration of worker statuses.\"\"\"\n\n    ONLINE = AutoEnum.auto()\n    OFFLINE = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.DeploymentStatus","title":"<code>DeploymentStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of deployment statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class DeploymentStatus(AutoEnum):\n    \"\"\"Enumeration of deployment statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueStatus","title":"<code>WorkQueueStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of work queue statuses.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueueStatus(AutoEnum):\n    \"\"\"Enumeration of work queue statuses.\"\"\"\n\n    READY = AutoEnum.auto()\n    NOT_READY = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State","title":"<code>State</code>","text":"<p>               Bases: <code>ObjectBaseModel</code>, <code>Generic[R]</code></p> <p>The state of a run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class State(ObjectBaseModel, Generic[R]):\n    \"\"\"\n    The state of a run.\n    \"\"\"\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    timestamp: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    state_details: StateDetails = Field(default_factory=StateDetails)\n    data: Union[\"BaseResult[R]\", \"DataDocument[R]\", Any] = Field(\n        default=None,\n    )\n\n    @overload\n    def result(self: \"State[R]\", raise_on_failure: bool = True) -&gt; R:\n        ...\n\n    @overload\n    def result(self: \"State[R]\", raise_on_failure: bool = False) -&gt; Union[R, Exception]:\n        ...\n\n    def result(\n        self, raise_on_failure: bool = True, fetch: Optional[bool] = None\n    ) -&gt; Union[R, Exception]:\n        \"\"\"\n        Retrieve the result attached to this state.\n\n        Args:\n            raise_on_failure: a boolean specifying whether to raise an exception\n                if the state is of type `FAILED` and the underlying data is an exception\n            fetch: a boolean specifying whether to resolve references to persisted\n                results into data. For synchronous users, this defaults to `True`.\n                For asynchronous users, this defaults to `False` for backwards\n                compatibility.\n\n        Raises:\n            TypeError: If the state is failed but the result is not an exception.\n\n        Returns:\n            The result of the run\n\n        Examples:\n            &gt;&gt;&gt; from prefect import flow, task\n            &gt;&gt;&gt; @task\n            &gt;&gt;&gt; def my_task(x):\n            &gt;&gt;&gt;     return x\n\n            Get the result from a task future in a flow\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     future = my_task(\"hello\")\n            &gt;&gt;&gt;     state = future.wait()\n            &gt;&gt;&gt;     result = state.result()\n            &gt;&gt;&gt;     print(result)\n            &gt;&gt;&gt; my_flow()\n            hello\n\n            Get the result from a flow state\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     return \"hello\"\n            &gt;&gt;&gt; my_flow(return_state=True).result()\n            hello\n\n            Get the result from a failed state\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n            &gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n            &gt;&gt;&gt; state.result()  # Raises `ValueError`\n\n            Get the result from a failed state without erroring\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; def my_flow():\n            &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n            &gt;&gt;&gt; state = my_flow(return_state=True)\n            &gt;&gt;&gt; result = state.result(raise_on_failure=False)\n            &gt;&gt;&gt; print(result)\n            ValueError(\"oh no!\")\n\n\n            Get the result from a flow state in an async context\n\n            &gt;&gt;&gt; @flow\n            &gt;&gt;&gt; async def my_flow():\n            &gt;&gt;&gt;     return \"hello\"\n            &gt;&gt;&gt; state = await my_flow(return_state=True)\n            &gt;&gt;&gt; await state.result()\n            hello\n        \"\"\"\n        from prefect.states import get_state_result\n\n        return get_state_result(self, raise_on_failure=raise_on_failure, fetch=fetch)\n\n    def to_state_create(self):\n        \"\"\"\n        Convert this state to a `StateCreate` type which can be used to set the state of\n        a run in the API.\n\n        This method will drop this state's `data` if it is not a result type. Only\n        results should be sent to the API. Other data is only available locally.\n        \"\"\"\n        from prefect.client.schemas.actions import StateCreate\n        from prefect.results import BaseResult\n\n        return StateCreate(\n            type=self.type,\n            name=self.name,\n            message=self.message,\n            data=self.data if isinstance(self.data, BaseResult) else None,\n            state_details=self.state_details,\n        )\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        \"\"\"\n        TODO: This should throw an error instead of setting a default but is out of\n              scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled\n              into work refactoring state initialization\n        \"\"\"\n        if values.get(\"type\") == StateType.SCHEDULED:\n            state_details = values.setdefault(\n                \"state_details\", cls.__fields__[\"state_details\"].get_default()\n            )\n            if not state_details.scheduled_time:\n                state_details.scheduled_time = pendulum.now(\"utc\")\n        return values\n\n    def is_scheduled(self) -&gt; bool:\n        return self.type == StateType.SCHEDULED\n\n    def is_pending(self) -&gt; bool:\n        return self.type == StateType.PENDING\n\n    def is_running(self) -&gt; bool:\n        return self.type == StateType.RUNNING\n\n    def is_completed(self) -&gt; bool:\n        return self.type == StateType.COMPLETED\n\n    def is_failed(self) -&gt; bool:\n        return self.type == StateType.FAILED\n\n    def is_crashed(self) -&gt; bool:\n        return self.type == StateType.CRASHED\n\n    def is_cancelled(self) -&gt; bool:\n        return self.type == StateType.CANCELLED\n\n    def is_cancelling(self) -&gt; bool:\n        return self.type == StateType.CANCELLING\n\n    def is_final(self) -&gt; bool:\n        return self.type in {\n            StateType.CANCELLED,\n            StateType.FAILED,\n            StateType.COMPLETED,\n            StateType.CRASHED,\n        }\n\n    def is_paused(self) -&gt; bool:\n        return self.type == StateType.PAUSED\n\n    def copy(\n        self,\n        *,\n        update: Optional[Dict[str, Any]] = None,\n        reset_fields: bool = False,\n        **kwargs,\n    ):\n        \"\"\"\n        Copying API models should return an object that could be inserted into the\n        database again. The 'timestamp' is reset using the default factory.\n        \"\"\"\n        update = update or {}\n        update.setdefault(\"timestamp\", self.__fields__[\"timestamp\"].get_default())\n        return super().copy(reset_fields=reset_fields, update=update, **kwargs)\n\n    def __repr__(self) -&gt; str:\n        \"\"\"\n        Generates a complete state representation appropriate for introspection\n        and debugging, including the result:\n\n        `MyCompletedState(message=\"my message\", type=COMPLETED, result=...)`\n        \"\"\"\n        from prefect.deprecated.data_documents import DataDocument\n\n        if isinstance(self.data, DataDocument):\n            result = self.data.decode()\n        else:\n            result = self.data\n\n        display = dict(\n            message=repr(self.message),\n            type=str(self.type.value),\n            result=repr(result),\n        )\n\n        return f\"{self.name}({', '.join(f'{k}={v}' for k, v in display.items())})\"\n\n    def __str__(self) -&gt; str:\n        \"\"\"\n        Generates a simple state representation appropriate for logging:\n\n        `MyCompletedState(\"my message\", type=COMPLETED)`\n        \"\"\"\n\n        display = []\n\n        if self.message:\n            display.append(repr(self.message))\n\n        if self.type.value.lower() != self.name.lower():\n            display.append(f\"type={self.type.value}\")\n\n        return f\"{self.name}({', '.join(display)})\"\n\n    def __hash__(self) -&gt; int:\n        return hash(\n            (\n                getattr(self.state_details, \"flow_run_id\", None),\n                getattr(self.state_details, \"task_run_id\", None),\n                self.timestamp,\n                self.type,\n            )\n        )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.result","title":"<code>result</code>","text":"<p>Retrieve the result attached to this state.</p> <p>Parameters:</p> Name Type Description Default <code>raise_on_failure</code> <code>bool</code> <p>a boolean specifying whether to raise an exception if the state is of type <code>FAILED</code> and the underlying data is an exception</p> <code>True</code> <code>fetch</code> <code>Optional[bool]</code> <p>a boolean specifying whether to resolve references to persisted results into data. For synchronous users, this defaults to <code>True</code>. For asynchronous users, this defaults to <code>False</code> for backwards compatibility.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If the state is failed but the result is not an exception.</p> <p>Returns:</p> Type Description <code>Union[R, Exception]</code> <p>The result of the run</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from prefect import flow, task\n&gt;&gt;&gt; @task\n&gt;&gt;&gt; def my_task(x):\n&gt;&gt;&gt;     return x\n</code></pre> <p>Get the result from a task future in a flow</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     future = my_task(\"hello\")\n&gt;&gt;&gt;     state = future.wait()\n&gt;&gt;&gt;     result = state.result()\n&gt;&gt;&gt;     print(result)\n&gt;&gt;&gt; my_flow()\nhello\n</code></pre> <p>Get the result from a flow state</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     return \"hello\"\n&gt;&gt;&gt; my_flow(return_state=True).result()\nhello\n</code></pre> <p>Get the result from a failed state</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     raise ValueError(\"oh no!\")\n&gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n&gt;&gt;&gt; state.result()  # Raises `ValueError`\n</code></pre> <p>Get the result from a failed state without erroring</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; def my_flow():\n&gt;&gt;&gt;     raise ValueError(\"oh no!\")\n&gt;&gt;&gt; state = my_flow(return_state=True)\n&gt;&gt;&gt; result = state.result(raise_on_failure=False)\n&gt;&gt;&gt; print(result)\nValueError(\"oh no!\")\n</code></pre> <p>Get the result from a flow state in an async context</p> <pre><code>&gt;&gt;&gt; @flow\n&gt;&gt;&gt; async def my_flow():\n&gt;&gt;&gt;     return \"hello\"\n&gt;&gt;&gt; state = await my_flow(return_state=True)\n&gt;&gt;&gt; await state.result()\nhello\n</code></pre> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def result(\n    self, raise_on_failure: bool = True, fetch: Optional[bool] = None\n) -&gt; Union[R, Exception]:\n    \"\"\"\n    Retrieve the result attached to this state.\n\n    Args:\n        raise_on_failure: a boolean specifying whether to raise an exception\n            if the state is of type `FAILED` and the underlying data is an exception\n        fetch: a boolean specifying whether to resolve references to persisted\n            results into data. For synchronous users, this defaults to `True`.\n            For asynchronous users, this defaults to `False` for backwards\n            compatibility.\n\n    Raises:\n        TypeError: If the state is failed but the result is not an exception.\n\n    Returns:\n        The result of the run\n\n    Examples:\n        &gt;&gt;&gt; from prefect import flow, task\n        &gt;&gt;&gt; @task\n        &gt;&gt;&gt; def my_task(x):\n        &gt;&gt;&gt;     return x\n\n        Get the result from a task future in a flow\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     future = my_task(\"hello\")\n        &gt;&gt;&gt;     state = future.wait()\n        &gt;&gt;&gt;     result = state.result()\n        &gt;&gt;&gt;     print(result)\n        &gt;&gt;&gt; my_flow()\n        hello\n\n        Get the result from a flow state\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     return \"hello\"\n        &gt;&gt;&gt; my_flow(return_state=True).result()\n        hello\n\n        Get the result from a failed state\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n        &gt;&gt;&gt; state = my_flow(return_state=True)  # Error is wrapped in FAILED state\n        &gt;&gt;&gt; state.result()  # Raises `ValueError`\n\n        Get the result from a failed state without erroring\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; def my_flow():\n        &gt;&gt;&gt;     raise ValueError(\"oh no!\")\n        &gt;&gt;&gt; state = my_flow(return_state=True)\n        &gt;&gt;&gt; result = state.result(raise_on_failure=False)\n        &gt;&gt;&gt; print(result)\n        ValueError(\"oh no!\")\n\n\n        Get the result from a flow state in an async context\n\n        &gt;&gt;&gt; @flow\n        &gt;&gt;&gt; async def my_flow():\n        &gt;&gt;&gt;     return \"hello\"\n        &gt;&gt;&gt; state = await my_flow(return_state=True)\n        &gt;&gt;&gt; await state.result()\n        hello\n    \"\"\"\n    from prefect.states import get_state_result\n\n    return get_state_result(self, raise_on_failure=raise_on_failure, fetch=fetch)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.to_state_create","title":"<code>to_state_create</code>","text":"<p>Convert this state to a <code>StateCreate</code> type which can be used to set the state of a run in the API.</p> <p>This method will drop this state's <code>data</code> if it is not a result type. Only results should be sent to the API. Other data is only available locally.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def to_state_create(self):\n    \"\"\"\n    Convert this state to a `StateCreate` type which can be used to set the state of\n    a run in the API.\n\n    This method will drop this state's `data` if it is not a result type. Only\n    results should be sent to the API. Other data is only available locally.\n    \"\"\"\n    from prefect.client.schemas.actions import StateCreate\n    from prefect.results import BaseResult\n\n    return StateCreate(\n        type=self.type,\n        name=self.name,\n        message=self.message,\n        data=self.data if isinstance(self.data, BaseResult) else None,\n        state_details=self.state_details,\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.State.default_scheduled_start_time","title":"<code>default_scheduled_start_time</code>","text":"This should throw an error instead of setting a default but is out of <p>scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled into work refactoring state initialization</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>@root_validator\ndef default_scheduled_start_time(cls, values):\n    \"\"\"\n    TODO: This should throw an error instead of setting a default but is out of\n          scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled\n          into work refactoring state initialization\n    \"\"\"\n    if values.get(\"type\") == StateType.SCHEDULED:\n        state_details = values.setdefault(\n            \"state_details\", cls.__fields__[\"state_details\"].get_default()\n        )\n        if not state_details.scheduled_time:\n            state_details.scheduled_time = pendulum.now(\"utc\")\n    return values\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunPolicy","title":"<code>FlowRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a flow run should be orchestrated.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a flow run should be orchestrated.\"\"\"\n\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Optional[int] = Field(\n        default=None, description=\"The delay time between retries, in seconds.\"\n    )\n    pause_keys: Optional[set] = Field(\n        default_factory=set, description=\"Tracks pauses this run has observed.\"\n    )\n    resuming: Optional[bool] = Field(\n        default=False, description=\"Indicates if this run is resuming from a pause.\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRun","title":"<code>FlowRun</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRun(ObjectBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[State] = Field(\n        default=None,\n        description=\"The state of the flow run.\",\n        examples=[State(type=StateType.COMPLETED)],\n    )\n    job_variables: Optional[dict] = Field(\n        default=None, description=\"Job variables for the flow run.\"\n    )\n\n    # These are server-side optimizations and should not be present on client models\n    # TODO: Deprecate these fields\n\n    state_type: Optional[StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n\n    @validator(\"name\", pre=True)\n    def set_default_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunPolicy","title":"<code>TaskRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a task run should retry.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a task run should retry.\"\"\"\n\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Union[None, int, List[int]] = Field(\n        default=None,\n        description=\"A delay time or list of delay times between retries, in seconds.\",\n    )\n    retry_jitter_factor: Optional[float] = Field(\n        default=None, description=\"Determines the amount a retry should jitter\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n\n    @validator(\"retry_delay\")\n    def validate_configured_retry_delays(cls, v):\n        return list_length_50_or_less(v)\n\n    @validator(\"retry_jitter_factor\")\n    def validate_jitter_factor(cls, v):\n        return validate_not_negative(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunInput","title":"<code>TaskRunInput</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Base class for classes that represent inputs to task runs, which could include, constants, parameters, or other task runs.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunInput(PrefectBaseModel):\n    \"\"\"\n    Base class for classes that represent inputs to task runs, which\n    could include, constants, parameters, or other task runs.\n    \"\"\"\n\n    # freeze TaskRunInputs to allow them to be placed in sets\n    class Config:\n        frozen = True\n\n    input_type: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.TaskRunResult","title":"<code>TaskRunResult</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents a task run result input to another task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class TaskRunResult(TaskRunInput):\n    \"\"\"Represents a task run result input to another task run.\"\"\"\n\n    input_type: Literal[\"task_run\"] = \"task_run\"\n    id: UUID\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Parameter","title":"<code>Parameter</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents a parameter input to a task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Parameter(TaskRunInput):\n    \"\"\"Represents a parameter input to a task run.\"\"\"\n\n    input_type: Literal[\"parameter\"] = \"parameter\"\n    name: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Constant","title":"<code>Constant</code>","text":"<p>               Bases: <code>TaskRunInput</code></p> <p>Represents constant input value to a task run.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Constant(TaskRunInput):\n    \"\"\"Represents constant input value to a task run.\"\"\"\n\n    input_type: Literal[\"constant\"] = \"constant\"\n    type: str\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace","title":"<code>Workspace</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A Prefect Cloud workspace.</p> <p>Expected payload for each workspace returned by the <code>me/workspaces</code> route.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Workspace(PrefectBaseModel):\n    \"\"\"\n    A Prefect Cloud workspace.\n\n    Expected payload for each workspace returned by the `me/workspaces` route.\n    \"\"\"\n\n    account_id: UUID = Field(..., description=\"The account id of the workspace.\")\n    account_name: str = Field(..., description=\"The account name.\")\n    account_handle: str = Field(..., description=\"The account's unique handle.\")\n    workspace_id: UUID = Field(..., description=\"The workspace id.\")\n    workspace_name: str = Field(..., description=\"The workspace name.\")\n    workspace_description: str = Field(..., description=\"Description of the workspace.\")\n    workspace_handle: str = Field(..., description=\"The workspace's unique handle.\")\n\n    class Config:\n        extra = \"ignore\"\n\n    @property\n    def handle(self) -&gt; str:\n        \"\"\"\n        The full handle of the workspace as `account_handle` / `workspace_handle`\n        \"\"\"\n        return self.account_handle + \"/\" + self.workspace_handle\n\n    def api_url(self) -&gt; str:\n        \"\"\"\n        Generate the API URL for accessing this workspace\n        \"\"\"\n        return (\n            f\"{PREFECT_CLOUD_API_URL.value()}\"\n            f\"/accounts/{self.account_id}\"\n            f\"/workspaces/{self.workspace_id}\"\n        )\n\n    def ui_url(self) -&gt; str:\n        \"\"\"\n        Generate the UI URL for accessing this workspace\n        \"\"\"\n        return (\n            f\"{PREFECT_CLOUD_UI_URL.value()}\"\n            f\"/account/{self.account_id}\"\n            f\"/workspace/{self.workspace_id}\"\n        )\n\n    def __hash__(self):\n        return hash(self.handle)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.handle","title":"<code>handle: str</code>  <code>property</code>","text":"<p>The full handle of the workspace as <code>account_handle</code> / <code>workspace_handle</code></p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.api_url","title":"<code>api_url</code>","text":"<p>Generate the API URL for accessing this workspace</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def api_url(self) -&gt; str:\n    \"\"\"\n    Generate the API URL for accessing this workspace\n    \"\"\"\n    return (\n        f\"{PREFECT_CLOUD_API_URL.value()}\"\n        f\"/accounts/{self.account_id}\"\n        f\"/workspaces/{self.workspace_id}\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Workspace.ui_url","title":"<code>ui_url</code>","text":"<p>Generate the UI URL for accessing this workspace</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def ui_url(self) -&gt; str:\n    \"\"\"\n    Generate the UI URL for accessing this workspace\n    \"\"\"\n    return (\n        f\"{PREFECT_CLOUD_UI_URL.value()}\"\n        f\"/account/{self.account_id}\"\n        f\"/workspace/{self.workspace_id}\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockType","title":"<code>BlockType</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block type</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockType(ObjectBaseModel):\n    \"\"\"An ORM representation of a block type\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n    is_protected: bool = Field(\n        default=False, description=\"Protected block types cannot be modified via API.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockDocument","title":"<code>BlockDocument</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block document.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockDocument(ObjectBaseModel):\n    \"\"\"An ORM representation of a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n    block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The associated block schema\"\n    )\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n    block_type_name: Optional[str] = Field(None, description=\"A block type name\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    block_document_references: Dict[str, Dict[str, Any]] = Field(\n        default_factory=dict, description=\"Record of the block document's references\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        # the BlockDocumentCreate subclass allows name=None\n        # and will inherit this validator\n        return raise_on_name_with_banned_characters(v)\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of flow data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Flow(ObjectBaseModel):\n    \"\"\"An ORM representation of flow data.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ObjectBaseModel</code></p> <p>An ORM representation of deployment data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Deployment(DeprecatedInfraOverridesField, ObjectBaseModel):\n    \"\"\"An ORM representation of deployment data.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the deployment.\")\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description for the deployment.\"\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The flow id associated with the deployment.\"\n    )\n    schedule: Optional[SCHEDULE_TYPES] = Field(\n        default=None, description=\"A schedule for the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether or not the deployment schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentSchedule] = Field(\n        default_factory=list, description=\"A list of schedules for the deployment.\"\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    pull_steps: Optional[List[dict]] = Field(\n        default=None,\n        description=\"Pull steps for cloning and running this deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the deployment\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The work queue for the deployment. If no work queue is set, work will not\"\n            \" be scheduled.\"\n        ),\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The last time the deployment was polled for status updates.\",\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    storage_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining storage used for this flow.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use for flow runs.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this deployment.\",\n    )\n    updated_by: Optional[UpdatedBy] = Field(\n        default=None,\n        description=\"Optional information about the updater of this deployment.\",\n    )\n    work_queue_id: UUID = Field(\n        default=None,\n        description=(\n            \"The id of the work pool queue to which this deployment is assigned.\"\n        ),\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.ConcurrencyLimit","title":"<code>ConcurrencyLimit</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a concurrency limit.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class ConcurrencyLimit(ObjectBaseModel):\n    \"\"\"An ORM representation of a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: List[UUID] = Field(\n        default_factory=list,\n        description=\"A list of active run ids using a concurrency slot\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockSchema","title":"<code>BlockSchema</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block schema.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockSchema(ObjectBaseModel):\n    \"\"\"An ORM representation of a block schema.\"\"\"\n\n    checksum: str = Field(default=..., description=\"The block schema's unique checksum\")\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockSchemaReference","title":"<code>BlockSchemaReference</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block schema reference.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockSchemaReference(ObjectBaseModel):\n    \"\"\"An ORM representation of a block schema reference.\"\"\"\n\n    parent_block_schema_id: UUID = Field(\n        default=..., description=\"ID of block schema the reference is nested within\"\n    )\n    parent_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The block schema the reference is nested within\"\n    )\n    reference_block_schema_id: UUID = Field(\n        default=..., description=\"ID of the nested block schema\"\n    )\n    reference_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The nested block schema\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.BlockDocumentReference","title":"<code>BlockDocumentReference</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a block document reference.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class BlockDocumentReference(ObjectBaseModel):\n    \"\"\"An ORM representation of a block document reference.\"\"\"\n\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    parent_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    reference_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.SavedSearchFilter","title":"<code>SavedSearchFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A filter for a saved search model. Intended for use by the Prefect UI.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class SavedSearchFilter(PrefectBaseModel):\n    \"\"\"A filter for a saved search model. Intended for use by the Prefect UI.\"\"\"\n\n    object: str = Field(default=..., description=\"The object over which to filter.\")\n    property: str = Field(\n        default=..., description=\"The property of the object on which to filter.\"\n    )\n    type: str = Field(default=..., description=\"The type of the property.\")\n    operation: str = Field(\n        default=...,\n        description=\"The operator to apply to the object. For example, `equals`.\",\n    )\n    value: Any = Field(\n        default=..., description=\"A JSON-compatible value for the filter.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.SavedSearch","title":"<code>SavedSearch</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of saved search data. Represents a set of filter criteria.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class SavedSearch(ObjectBaseModel):\n    \"\"\"An ORM representation of saved search data. Represents a set of filter criteria.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Log","title":"<code>Log</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of log data.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Log(ObjectBaseModel):\n    \"\"\"An ORM representation of log data.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run ID associated with the log.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run ID associated with the log.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.QueueFilter","title":"<code>QueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter criteria definition for a work queue.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class QueueFilter(PrefectBaseModel):\n    \"\"\"Filter criteria definition for a work queue.\"\"\"\n\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"Only include flow runs with these tags in the work queue.\",\n    )\n    deployment_ids: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"Only include flow runs from these deployments in the work queue.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueue","title":"<code>WorkQueue</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a work queue</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueue(ObjectBaseModel):\n    \"\"\"An ORM representation of a work queue\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"An optional concurrency limit for the work queue.\"\n    )\n    priority: PositiveInteger = Field(\n        default=1,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n    work_pool_name: Optional[str] = Field(default=None)\n    # Will be required after a future migration\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    filter: Optional[QueueFilter] = Field(\n        default=None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time an agent polled this queue for work.\"\n    )\n    status: Optional[WorkQueueStatus] = Field(\n        default=None, description=\"The queue status.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueHealthPolicy","title":"<code>WorkQueueHealthPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkQueueHealthPolicy(PrefectBaseModel):\n    maximum_late_runs: Optional[int] = Field(\n        default=0,\n        description=(\n            \"The maximum number of late runs in the work queue before it is deemed\"\n            \" unhealthy. Defaults to `0`.\"\n        ),\n    )\n    maximum_seconds_since_last_polled: Optional[int] = Field(\n        default=60,\n        description=(\n            \"The maximum number of time in seconds elapsed since work queue has been\"\n            \" polled before it is deemed unhealthy. Defaults to `60`.\"\n        ),\n    )\n\n    def evaluate_health_status(\n        self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n    ) -&gt; bool:\n        \"\"\"\n        Given empirical information about the state of the work queue, evaluate its health status.\n\n        Args:\n            late_runs: the count of late runs for the work queue.\n            last_polled: the last time the work queue was polled, if available.\n\n        Returns:\n            bool: whether or not the work queue is healthy.\n        \"\"\"\n        healthy = True\n        if (\n            self.maximum_late_runs is not None\n            and late_runs_count &gt; self.maximum_late_runs\n        ):\n            healthy = False\n\n        if self.maximum_seconds_since_last_polled is not None:\n            if (\n                last_polled is None\n                or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n                &gt; self.maximum_seconds_since_last_polled\n            ):\n                healthy = False\n\n        return healthy\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkQueueHealthPolicy.evaluate_health_status","title":"<code>evaluate_health_status</code>","text":"<p>Given empirical information about the state of the work queue, evaluate its health status.</p> <p>Parameters:</p> Name Type Description Default <code>late_runs</code> <p>the count of late runs for the work queue.</p> required <code>last_polled</code> <code>Optional[DateTimeTZ]</code> <p>the last time the work queue was polled, if available.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the work queue is healthy.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>def evaluate_health_status(\n    self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n) -&gt; bool:\n    \"\"\"\n    Given empirical information about the state of the work queue, evaluate its health status.\n\n    Args:\n        late_runs: the count of late runs for the work queue.\n        last_polled: the last time the work queue was polled, if available.\n\n    Returns:\n        bool: whether or not the work queue is healthy.\n    \"\"\"\n    healthy = True\n    if (\n        self.maximum_late_runs is not None\n        and late_runs_count &gt; self.maximum_late_runs\n    ):\n        healthy = False\n\n    if self.maximum_seconds_since_last_polled is not None:\n        if (\n            last_polled is None\n            or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n            &gt; self.maximum_seconds_since_last_polled\n        ):\n            healthy = False\n\n    return healthy\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunNotificationPolicy","title":"<code>FlowRunNotificationPolicy</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a flow run notification.</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunNotificationPolicy(ObjectBaseModel):\n    \"\"\"An ORM representation of a flow run notification.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Agent","title":"<code>Agent</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of an agent</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Agent(ObjectBaseModel):\n    \"\"\"An ORM representation of an agent\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the agent. If a name is not provided, it will be\"\n            \" auto-generated.\"\n        ),\n    )\n    work_queue_id: UUID = Field(\n        default=..., description=\"The work queue with which the agent is associated.\"\n    )\n    last_activity_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time this agent polled for work.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.WorkPool","title":"<code>WorkPool</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a work pool</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class WorkPool(ObjectBaseModel):\n    \"\"\"An ORM representation of a work pool\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description of the work pool.\"\n    )\n    type: str = Field(description=\"The work pool type.\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n    status: Optional[WorkPoolStatus] = Field(\n        default=None, description=\"The current status of the work pool.\"\n    )\n\n    # this required field has a default of None so that the custom validator\n    # below will be called and produce a more helpful error message\n    default_queue_id: UUID = Field(\n        None, description=\"The id of the pool's default queue.\"\n    )\n\n    @property\n    def is_push_pool(self) -&gt; bool:\n        return self.type.endswith(\":push\")\n\n    @property\n    def is_managed_pool(self) -&gt; bool:\n        return self.type.endswith(\":managed\")\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n\n    @validator(\"default_queue_id\", always=True)\n    def helpful_error_for_missing_default_queue_id(cls, v):\n        return validate_default_queue_id_not_none(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.Worker","title":"<code>Worker</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a worker</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class Worker(ObjectBaseModel):\n    \"\"\"An ORM representation of a worker\"\"\"\n\n    name: str = Field(description=\"The name of the worker.\")\n    work_pool_id: UUID = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    last_heartbeat_time: datetime.datetime = Field(\n        None, description=\"The last time the worker process sent a heartbeat.\"\n    )\n    heartbeat_interval_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to expect between heartbeats sent by the worker.\"\n        ),\n    )\n    status: WorkerStatus = Field(\n        WorkerStatus.OFFLINE,\n        description=\"Current status of the worker.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunInput","title":"<code>FlowRunInput</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class FlowRunInput(ObjectBaseModel):\n    flow_run_id: UUID = Field(description=\"The flow run ID associated with the input.\")\n    key: str = Field(description=\"The key of the input.\")\n    value: str = Field(description=\"The value of the input.\")\n    sender: Optional[str] = Field(description=\"The sender of the input.\")\n\n    @property\n    def decoded_value(self) -&gt; Any:\n        \"\"\"\n        Decode the value of the input.\n\n        Returns:\n            Any: the decoded value\n        \"\"\"\n        return orjson.loads(self.value)\n\n    @validator(\"key\", check_fields=False)\n    def validate_name_characters(cls, v):\n        raise_on_name_alphanumeric_dashes_only(v)\n        return v\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.FlowRunInput.decoded_value","title":"<code>decoded_value: Any</code>  <code>property</code>","text":"<p>Decode the value of the input.</p> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>the decoded value</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.objects.GlobalConcurrencyLimit","title":"<code>GlobalConcurrencyLimit</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>An ORM representation of a global concurrency limit</p> Source code in <code>prefect/client/schemas/objects.py</code> <pre><code>class GlobalConcurrencyLimit(ObjectBaseModel):\n    \"\"\"An ORM representation of a global concurrency limit\"\"\"\n\n    name: str = Field(description=\"The name of the global concurrency limit.\")\n    limit: int = Field(\n        description=(\n            \"The maximum number of slots that can be occupied on this concurrency\"\n            \" limit.\"\n        )\n    )\n    active: Optional[bool] = Field(\n        default=True,\n        description=\"Whether or not the concurrency limit is in an active state.\",\n    )\n    active_slots: Optional[int] = Field(\n        default=0,\n        description=\"Number of tasks currently using a concurrency slot.\",\n    )\n    slot_decay_per_second: Optional[float] = Field(\n        default=0.0,\n        description=(\n            \"Controls the rate at which slots are released when the concurrency limit\"\n            \" is used as a rate limit.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_4","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses","title":"<code>prefect.client.schemas.responses</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.SetStateStatus","title":"<code>SetStateStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumerates return statuses for setting run states.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class SetStateStatus(AutoEnum):\n    \"\"\"Enumerates return statuses for setting run states.\"\"\"\n\n    ACCEPT = AutoEnum.auto()\n    REJECT = AutoEnum.auto()\n    ABORT = AutoEnum.auto()\n    WAIT = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateAcceptDetails","title":"<code>StateAcceptDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ACCEPT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateAcceptDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ACCEPT state transition.\"\"\"\n\n    type: Literal[\"accept_details\"] = Field(\n        default=\"accept_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateRejectDetails","title":"<code>StateRejectDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a REJECT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateRejectDetails(PrefectBaseModel):\n    \"\"\"Details associated with a REJECT state transition.\"\"\"\n\n    type: Literal[\"reject_details\"] = Field(\n        default=\"reject_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was rejected.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateAbortDetails","title":"<code>StateAbortDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ABORT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateAbortDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ABORT state transition.\"\"\"\n\n    type: Literal[\"abort_details\"] = Field(\n        default=\"abort_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was aborted.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.StateWaitDetails","title":"<code>StateWaitDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a WAIT state transition.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class StateWaitDetails(PrefectBaseModel):\n    \"\"\"Details associated with a WAIT state transition.\"\"\"\n\n    type: Literal[\"wait_details\"] = Field(\n        default=\"wait_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    delay_seconds: int = Field(\n        default=...,\n        description=(\n            \"The length of time in seconds the client should wait before transitioning\"\n            \" states.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition should wait.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.HistoryResponseState","title":"<code>HistoryResponseState</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a single state's history over an interval.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class HistoryResponseState(PrefectBaseModel):\n    \"\"\"Represents a single state's history over an interval.\"\"\"\n\n    state_type: objects.StateType = Field(default=..., description=\"The state type.\")\n    state_name: str = Field(default=..., description=\"The state name.\")\n    count_runs: int = Field(\n        default=...,\n        description=\"The number of runs in the specified state during the interval.\",\n    )\n    sum_estimated_run_time: datetime.timedelta = Field(\n        default=...,\n        description=\"The total estimated run time of all runs during the interval.\",\n    )\n    sum_estimated_lateness: datetime.timedelta = Field(\n        default=...,\n        description=(\n            \"The sum of differences between actual and expected start time during the\"\n            \" interval.\"\n        ),\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.HistoryResponse","title":"<code>HistoryResponse</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a history of aggregation states over an interval</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class HistoryResponse(PrefectBaseModel):\n    \"\"\"Represents a history of aggregation states over an interval\"\"\"\n\n    interval_start: DateTimeTZ = Field(\n        default=..., description=\"The start date of the interval.\"\n    )\n    interval_end: DateTimeTZ = Field(\n        default=..., description=\"The end date of the interval.\"\n    )\n    states: List[HistoryResponseState] = Field(\n        default=..., description=\"A list of state histories during the interval.\"\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.OrchestrationResult","title":"<code>OrchestrationResult</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for the output of state orchestration.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class OrchestrationResult(PrefectBaseModel):\n    \"\"\"\n    A container for the output of state orchestration.\n    \"\"\"\n\n    state: Optional[objects.State]\n    status: SetStateStatus\n    details: StateResponseDetails\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.FlowRunResponse","title":"<code>FlowRunResponse</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class FlowRunResponse(ObjectBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: objects.FlowRunPolicy = Field(\n        default_factory=objects.FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    work_pool_id: Optional[UUID] = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[objects.State] = Field(\n        default=None,\n        description=\"The state of the flow run.\",\n        examples=[objects.State(type=objects.StateType.COMPLETED)],\n    )\n    job_variables: Optional[dict] = Field(\n        default=None, description=\"Job variables for the flow run.\"\n    )\n\n    # These are server-side optimizations and should not be present on client models\n    # TODO: Deprecate these fields\n\n    state_type: Optional[objects.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, objects.FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.responses.GlobalConcurrencyLimitResponse","title":"<code>GlobalConcurrencyLimitResponse</code>","text":"<p>               Bases: <code>ObjectBaseModel</code></p> <p>A response object for global concurrency limits.</p> Source code in <code>prefect/client/schemas/responses.py</code> <pre><code>class GlobalConcurrencyLimitResponse(ObjectBaseModel):\n    \"\"\"\n    A response object for global concurrency limits.\n    \"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the global concurrency limit is active.\"\n    )\n    name: str = Field(\n        default=..., description=\"The name of the global concurrency limit.\"\n    )\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=..., description=\"The number of active slots.\")\n    slot_decay_per_second: float = Field(\n        default=2.0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_5","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules","title":"<code>prefect.client.schemas.schedules</code>","text":"<p>Schedule schemas</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.IntervalSchedule","title":"<code>IntervalSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no <code>anchor_date</code> is supplied, the current UTC time is used.  If a timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a <code>timezone</code> can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date.</p> <p>NOTE: If the <code>IntervalSchedule</code> <code>anchor_date</code> or <code>timezone</code> is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>timedelta</code> <p>an interval to schedule on</p> required <code>anchor_date</code> <code>DateTimeTZ</code> <p>an anchor date to schedule increments against; if not provided, the current timestamp will be used</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class IntervalSchedule(PrefectBaseModel):\n    \"\"\"\n    A schedule formed by adding `interval` increments to an `anchor_date`. If no\n    `anchor_date` is supplied, the current UTC time is used.  If a\n    timezone-naive datetime is provided for `anchor_date`, it is assumed to be\n    in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,\n    anchor dates are always stored as UTC offsets, so a `timezone` can be\n    provided to determine localization behaviors like DST boundary handling. If\n    none is provided it will be inferred from the anchor date.\n\n    NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a\n    DST-observing timezone, then the schedule will adjust itself appropriately.\n    Intervals greater than 24 hours will follow DST conventions, while intervals\n    of less than 24 hours will follow UTC intervals. For example, an hourly\n    schedule will fire every UTC hour, even across DST boundaries. When clocks\n    are set back, this will result in two runs that *appear* to both be\n    scheduled for 1am local time, even though they are an hour apart in UTC\n    time. For longer intervals, like a daily schedule, the interval schedule\n    will adjust for DST boundaries so that the clock-hour remains constant. This\n    means that a daily schedule that always fires at 9am will observe DST and\n    continue to fire at 9am in the local time zone.\n\n    Args:\n        interval (datetime.timedelta): an interval to schedule on\n        anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against;\n            if not provided, the current timestamp will be used\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n        exclude_none = True\n\n    interval: PositiveDuration\n    anchor_date: Optional[DateTimeTZ] = None\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"anchor_date\", always=True)\n    def validate_anchor_date(cls, v):\n        return default_anchor_date(v)\n\n    @validator(\"timezone\", always=True)\n    def validate_default_timezone(cls, v, values):\n        return default_timezone(v, values=values)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Cron schedule</p> <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST.</p> <p>Parameters:</p> Name Type Description Default <code>cron</code> <code>str</code> <p>a valid cron string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string in IANA tzdata format (for example, America/New_York).</p> required <code>day_or</code> <code>bool</code> <p>Control how croniter handles <code>day</code> and <code>day_of_week</code> entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class CronSchedule(PrefectBaseModel):\n    \"\"\"\n    Cron schedule\n\n    NOTE: If the timezone is a DST-observing one, then the schedule will adjust\n    itself appropriately. Cron's rules for DST are based on schedule times, not\n    intervals. This means that an hourly cron schedule will fire on every new\n    schedule hour, not every elapsed hour; for example, when clocks are set back\n    this will result in a two-hour pause as the schedule will fire *the first\n    time* 1am is reached and *the first time* 2am is reached, 120 minutes later.\n    Longer schedules, such as one that fires at 9am every morning, will\n    automatically adjust for DST.\n\n    Args:\n        cron (str): a valid cron string\n        timezone (str): a valid timezone string in IANA tzdata format (for example,\n            America/New_York).\n        day_or (bool, optional): Control how croniter handles `day` and `day_of_week`\n            entries. Defaults to True, matching cron which connects those values using\n            OR. If the switch is set to False, the values are connected using AND. This\n            behaves like fcron and enables you to e.g. define a job that executes each\n            2nd friday of a month by setting the days of month and the weekday.\n\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    cron: str = Field(default=..., examples=[\"0 0 * * *\"])\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n    day_or: bool = Field(\n        default=True,\n        description=(\n            \"Control croniter behavior for handling day and day_of_week entries.\"\n        ),\n    )\n\n    @validator(\"timezone\")\n    def valid_timezone(cls, v):\n        return default_timezone(v)\n\n    @validator(\"cron\")\n    def valid_cron_string(cls, v):\n        return validate_cron_string(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.RRuleSchedule","title":"<code>RRuleSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>RRule schedule, based on the iCalendar standard (RFC 5545) as implemented in <code>dateutils.rrule</code>.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more.</p> <p>Note that as a calendar-oriented standard, <code>RRuleSchedules</code> are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p> <p>Parameters:</p> Name Type Description Default <code>rrule</code> <code>str</code> <p>a valid RRule string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>class RRuleSchedule(PrefectBaseModel):\n    \"\"\"\n    RRule schedule, based on the iCalendar standard\n    ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as\n    implemented in `dateutils.rrule`.\n\n    RRules are appropriate for any kind of calendar-date manipulation, including\n    irregular intervals, repetition, exclusions, week day or day-of-month\n    adjustments, and more.\n\n    Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to\n    to the initial timezone provided. A 9am daily schedule with a daylight saving\n    time-aware start date will maintain a local 9am time through DST boundaries;\n    a 9am daily schedule with a UTC start date will maintain a 9am UTC time.\n\n    Args:\n        rrule (str): a valid RRule string\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    rrule: str\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"rrule\")\n    def validate_rrule_str(cls, v):\n        return validate_rrule_string(v)\n\n    @classmethod\n    def from_rrule(cls, rrule: dateutil.rrule.rrule):\n        if isinstance(rrule, dateutil.rrule.rrule):\n            if rrule._dtstart.tzinfo is not None:\n                timezone = rrule._dtstart.tzinfo.name\n            else:\n                timezone = \"UTC\"\n            return RRuleSchedule(rrule=str(rrule), timezone=timezone)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            dtstarts = [rr._dtstart for rr in rrule._rrule if rr._dtstart is not None]\n            unique_dstarts = set(pendulum.instance(d).in_tz(\"UTC\") for d in dtstarts)\n            unique_timezones = set(d.tzinfo for d in dtstarts if d.tzinfo is not None)\n\n            if len(unique_timezones) &gt; 1:\n                raise ValueError(\n                    f\"rruleset has too many dtstart timezones: {unique_timezones}\"\n                )\n\n            if len(unique_dstarts) &gt; 1:\n                raise ValueError(f\"rruleset has too many dtstarts: {unique_dstarts}\")\n\n            if unique_dstarts and unique_timezones:\n                timezone = dtstarts[0].tzinfo.name\n            else:\n                timezone = \"UTC\"\n\n            rruleset_string = \"\"\n            if rrule._rrule:\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._rrule)\n            if rrule._exrule:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._exrule).replace(\n                    \"RRULE\", \"EXRULE\"\n                )\n            if rrule._rdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"RDATE:\" + \",\".join(\n                    rd.strftime(\"%Y%m%dT%H%M%SZ\") for rd in rrule._rdate\n                )\n            if rrule._exdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"EXDATE:\" + \",\".join(\n                    exd.strftime(\"%Y%m%dT%H%M%SZ\") for exd in rrule._exdate\n                )\n            return RRuleSchedule(rrule=rruleset_string, timezone=timezone)\n        else:\n            raise ValueError(f\"Invalid RRule object: {rrule}\")\n\n    def to_rrule(self) -&gt; dateutil.rrule.rrule:\n        \"\"\"\n        Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n        here\n        \"\"\"\n        rrule = dateutil.rrule.rrulestr(\n            self.rrule,\n            dtstart=DEFAULT_ANCHOR_DATE,\n            cache=True,\n        )\n        timezone = dateutil.tz.gettz(self.timezone)\n        if isinstance(rrule, dateutil.rrule.rrule):\n            kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n            if rrule._until:\n                kwargs.update(\n                    until=rrule._until.replace(tzinfo=timezone),\n                )\n            return rrule.replace(**kwargs)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            # update rrules\n            localized_rrules = []\n            for rr in rrule._rrule:\n                kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n                if rr._until:\n                    kwargs.update(\n                        until=rr._until.replace(tzinfo=timezone),\n                    )\n                localized_rrules.append(rr.replace(**kwargs))\n            rrule._rrule = localized_rrules\n\n            # update exrules\n            localized_exrules = []\n            for exr in rrule._exrule:\n                kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n                if exr._until:\n                    kwargs.update(\n                        until=exr._until.replace(tzinfo=timezone),\n                    )\n                localized_exrules.append(exr.replace(**kwargs))\n            rrule._exrule = localized_exrules\n\n            # update rdates\n            localized_rdates = []\n            for rd in rrule._rdate:\n                localized_rdates.append(rd.replace(tzinfo=timezone))\n            rrule._rdate = localized_rdates\n\n            # update exdates\n            localized_exdates = []\n            for exd in rrule._exdate:\n                localized_exdates.append(exd.replace(tzinfo=timezone))\n            rrule._exdate = localized_exdates\n\n            return rrule\n\n    @validator(\"timezone\", always=True)\n    def valid_timezone(cls, v):\n        return validate_rrule_timezone(v)\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.RRuleSchedule.to_rrule","title":"<code>to_rrule</code>","text":"<p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates here</p> Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>def to_rrule(self) -&gt; dateutil.rrule.rrule:\n    \"\"\"\n    Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n    here\n    \"\"\"\n    rrule = dateutil.rrule.rrulestr(\n        self.rrule,\n        dtstart=DEFAULT_ANCHOR_DATE,\n        cache=True,\n    )\n    timezone = dateutil.tz.gettz(self.timezone)\n    if isinstance(rrule, dateutil.rrule.rrule):\n        kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n        if rrule._until:\n            kwargs.update(\n                until=rrule._until.replace(tzinfo=timezone),\n            )\n        return rrule.replace(**kwargs)\n    elif isinstance(rrule, dateutil.rrule.rruleset):\n        # update rrules\n        localized_rrules = []\n        for rr in rrule._rrule:\n            kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n            if rr._until:\n                kwargs.update(\n                    until=rr._until.replace(tzinfo=timezone),\n                )\n            localized_rrules.append(rr.replace(**kwargs))\n        rrule._rrule = localized_rrules\n\n        # update exrules\n        localized_exrules = []\n        for exr in rrule._exrule:\n            kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n            if exr._until:\n                kwargs.update(\n                    until=exr._until.replace(tzinfo=timezone),\n                )\n            localized_exrules.append(exr.replace(**kwargs))\n        rrule._exrule = localized_exrules\n\n        # update rdates\n        localized_rdates = []\n        for rd in rrule._rdate:\n            localized_rdates.append(rd.replace(tzinfo=timezone))\n        rrule._rdate = localized_rdates\n\n        # update exdates\n        localized_exdates = []\n        for exd in rrule._exdate:\n            localized_exdates.append(exd.replace(tzinfo=timezone))\n        rrule._exdate = localized_exdates\n\n        return rrule\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.schedules.construct_schedule","title":"<code>construct_schedule</code>","text":"<p>Construct a schedule from the provided arguments.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>Optional[Union[int, float, timedelta]]</code> <p>An interval on which to schedule runs. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>anchor_date</code> <code>Optional[Union[datetime, str]]</code> <p>The start date for an interval schedule.</p> <code>None</code> <code>cron</code> <code>Optional[str]</code> <p>A cron schedule for runs.</p> <code>None</code> <code>rrule</code> <code>Optional[str]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>timezone</code> <code>Optional[str]</code> <p>A timezone to use for the schedule. Defaults to UTC.</p> <code>None</code> Source code in <code>prefect/client/schemas/schedules.py</code> <pre><code>def construct_schedule(\n    interval: Optional[Union[int, float, datetime.timedelta]] = None,\n    anchor_date: Optional[Union[datetime.datetime, str]] = None,\n    cron: Optional[str] = None,\n    rrule: Optional[str] = None,\n    timezone: Optional[str] = None,\n) -&gt; SCHEDULE_TYPES:\n    \"\"\"\n    Construct a schedule from the provided arguments.\n\n    Args:\n        interval: An interval on which to schedule runs. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        anchor_date: The start date for an interval schedule.\n        cron: A cron schedule for runs.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        timezone: A timezone to use for the schedule. Defaults to UTC.\n    \"\"\"\n    num_schedules = sum(1 for entry in (interval, cron, rrule) if entry is not None)\n    if num_schedules &gt; 1:\n        raise ValueError(\"Only one of interval, cron, or rrule can be provided.\")\n\n    if anchor_date and not interval:\n        raise ValueError(\n            \"An anchor date can only be provided with an interval schedule\"\n        )\n\n    if timezone and not (interval or cron or rrule):\n        raise ValueError(\n            \"A timezone can only be provided with interval, cron, or rrule\"\n        )\n\n    schedule = None\n    if interval:\n        if isinstance(interval, (int, float)):\n            interval = datetime.timedelta(seconds=interval)\n        schedule = IntervalSchedule(\n            interval=interval, anchor_date=anchor_date, timezone=timezone\n        )\n    elif cron:\n        schedule = CronSchedule(cron=cron, timezone=timezone)\n    elif rrule:\n        schedule = RRuleSchedule(rrule=rrule, timezone=timezone)\n\n    if schedule is None:\n        raise ValueError(\"Either interval, cron, or rrule must be provided\")\n\n    return schedule\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#_6","title":"schemas","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting","title":"<code>prefect.client.schemas.sorting</code>","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.FlowRunSort","title":"<code>FlowRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow run sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class FlowRunSort(AutoEnum):\n    \"\"\"Defines flow run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    START_TIME_ASC = AutoEnum.auto()\n    START_TIME_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.TaskRunSort","title":"<code>TaskRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines task run sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class TaskRunSort(AutoEnum):\n    \"\"\"Defines task run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.AutomationSort","title":"<code>AutomationSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines automation sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class AutomationSort(AutoEnum):\n    \"\"\"Defines automation sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.LogSort","title":"<code>LogSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines log sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class LogSort(AutoEnum):\n    \"\"\"Defines log sorting options.\"\"\"\n\n    TIMESTAMP_ASC = AutoEnum.auto()\n    TIMESTAMP_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.FlowSort","title":"<code>FlowSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class FlowSort(AutoEnum):\n    \"\"\"Defines flow sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.DeploymentSort","title":"<code>DeploymentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines deployment sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class DeploymentSort(AutoEnum):\n    \"\"\"Defines deployment sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.ArtifactSort","title":"<code>ArtifactSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class ArtifactSort(AutoEnum):\n    \"\"\"Defines artifact sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.ArtifactCollectionSort","title":"<code>ArtifactCollectionSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact collection sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class ArtifactCollectionSort(AutoEnum):\n    \"\"\"Defines artifact collection sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.VariableSort","title":"<code>VariableSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines variables sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class VariableSort(AutoEnum):\n    \"\"\"Defines variables sorting options.\"\"\"\n\n    CREATED_DESC = \"CREATED_DESC\"\n    UPDATED_DESC = \"UPDATED_DESC\"\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/schemas/#prefect.client.schemas.sorting.BlockDocumentSort","title":"<code>BlockDocumentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines block document sorting options.</p> Source code in <code>prefect/client/schemas/sorting.py</code> <pre><code>class BlockDocumentSort(AutoEnum):\n    \"\"\"Defines block document sorting options.\"\"\"\n\n    NAME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    BLOCK_TYPE_AND_NAME_ASC = AutoEnum.auto()\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/","title":"utilities","text":"","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities","title":"<code>prefect.client.utilities</code>","text":"<p>Utilities for working with clients.</p>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities.get_or_create_client","title":"<code>get_or_create_client</code>","text":"<p>Returns provided client, infers a client from context if available, or creates a new client.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>client (PrefectClient</code> <p>an optional client to use</p> required <p>Returns:</p> Type Description <code>Tuple[PrefectClient, bool]</code> <ul> <li>tuple: a tuple of the client and a boolean indicating if the client was inferred from context</li> </ul> Source code in <code>prefect/client/utilities.py</code> <pre><code>def get_or_create_client(\n    client: Optional[\"PrefectClient\"] = None,\n) -&gt; Tuple[\"PrefectClient\", bool]:\n    \"\"\"\n    Returns provided client, infers a client from context if available, or creates a new client.\n\n    Args:\n        - client (PrefectClient, optional): an optional client to use\n\n    Returns:\n        - tuple: a tuple of the client and a boolean indicating if the client was inferred from context\n    \"\"\"\n    if client is not None:\n        return client, True\n    from prefect._internal.concurrency.event_loop import get_running_loop\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    flow_run_context = FlowRunContext.get()\n    task_run_context = TaskRunContext.get()\n\n    if (\n        flow_run_context\n        and getattr(flow_run_context.client, \"_loop\", None) == get_running_loop()\n    ):\n        return flow_run_context.client, True\n    elif (\n        task_run_context\n        and getattr(task_run_context.client, \"_loop\", None) == get_running_loop()\n    ):\n        return task_run_context.client, True\n    else:\n        from prefect.client.orchestration import get_client as get_httpx_client\n\n        return get_httpx_client(), False\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/client/utilities/#prefect.client.utilities.inject_client","title":"<code>inject_client</code>","text":"<p>Simple helper to provide a context managed client to a asynchronous function.</p> <p>The decorated function must take a <code>client</code> kwarg and if a client is passed when called it will be used instead of creating a new one, but it will not be context managed as it is assumed that the caller is managing the context.</p> Source code in <code>prefect/client/utilities.py</code> <pre><code>def inject_client(\n    fn: Callable[P, Coroutine[Any, Any, Any]],\n) -&gt; Callable[P, Coroutine[Any, Any, Any]]:\n    \"\"\"\n    Simple helper to provide a context managed client to a asynchronous function.\n\n    The decorated function _must_ take a `client` kwarg and if a client is passed when\n    called it will be used instead of creating a new one, but it will not be context\n    managed as it is assumed that the caller is managing the context.\n    \"\"\"\n\n    @wraps(fn)\n    async def with_injected_client(*args: P.args, **kwargs: P.kwargs) -&gt; Any:\n        client = cast(Optional[\"PrefectClient\"], kwargs.pop(\"client\", None))\n        client, inferred = get_or_create_client(client)\n        if not inferred:\n            context = client\n        else:\n            from prefect.utilities.asyncutils import asyncnullcontext\n\n            context = asyncnullcontext()\n        async with context as new_client:\n            kwargs.setdefault(\"client\", new_client or client)\n            return await fn(*args, **kwargs)\n\n    return with_injected_client\n</code></pre>","tags":["Python API","REST API"]},{"location":"api-ref/prefect/concurrency/asyncio/","title":"asyncio","text":"","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio","title":"<code>prefect.concurrency.asyncio</code>","text":"","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.AcquireConcurrencySlotTimeoutError","title":"<code>AcquireConcurrencySlotTimeoutError</code>","text":"<p>               Bases: <code>TimeoutError</code></p> <p>Raised when acquiring a concurrency slot times out.</p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>class AcquireConcurrencySlotTimeoutError(TimeoutError):\n    \"\"\"Raised when acquiring a concurrency slot times out.\"\"\"\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.ConcurrencySlotAcquisitionError","title":"<code>ConcurrencySlotAcquisitionError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when an unhandlable occurs while acquiring concurrency slots.</p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>class ConcurrencySlotAcquisitionError(Exception):\n    \"\"\"Raised when an unhandlable occurs while acquiring concurrency slots.\"\"\"\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.concurrency","title":"<code>concurrency</code>  <code>async</code>","text":"<p>A context manager that acquires and releases concurrency slots from the given concurrency limits.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> <code>timeout_seconds</code> <code>Optional[float]</code> <p>The number of seconds to wait for the slots to be acquired before raising a <code>TimeoutError</code>. A timeout of <code>None</code> will wait indefinitely.</p> <code>None</code> <p>Raises:</p> Type Description <code>TimeoutError</code> <p>If the slots are not acquired within the given timeout.</p> <p>A simple example of using the async <code>concurrency</code> context manager: <pre><code>from prefect.concurrency.asyncio import concurrency\n\nasync def resource_heavy():\n    async with concurrency(\"test\", occupy=1):\n        print(\"Resource heavy task\")\n\nasync def main():\n    await resource_heavy()\n</code></pre></p> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>@asynccontextmanager\nasync def concurrency(\n    names: Union[str, List[str]],\n    occupy: int = 1,\n    timeout_seconds: Optional[float] = None,\n):\n    \"\"\"A context manager that acquires and releases concurrency slots from the\n    given concurrency limits.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n        timeout_seconds: The number of seconds to wait for the slots to be acquired before\n            raising a `TimeoutError`. A timeout of `None` will wait indefinitely.\n\n    Raises:\n        TimeoutError: If the slots are not acquired within the given timeout.\n\n    Example:\n    A simple example of using the async `concurrency` context manager:\n    ```python\n    from prefect.concurrency.asyncio import concurrency\n\n    async def resource_heavy():\n        async with concurrency(\"test\", occupy=1):\n            print(\"Resource heavy task\")\n\n    async def main():\n        await resource_heavy()\n    ```\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = await _acquire_concurrency_slots(\n        names, occupy, timeout_seconds=timeout_seconds\n    )\n    acquisition_time = pendulum.now(\"UTC\")\n    emitted_events = _emit_concurrency_acquisition_events(limits, occupy)\n\n    try:\n        yield\n    finally:\n        occupancy_period = cast(Interval, (pendulum.now(\"UTC\") - acquisition_time))\n        await _release_concurrency_slots(\n            names, occupy, occupancy_period.total_seconds()\n        )\n        _emit_concurrency_release_events(limits, occupy, emitted_events)\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/asyncio/#prefect.concurrency.asyncio.rate_limit","title":"<code>rate_limit</code>  <code>async</code>","text":"<p>Block execution until an <code>occupy</code> number of slots of the concurrency limits given in <code>names</code> are acquired. Requires that all given concurrency limits have a slot decay.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> Source code in <code>prefect/concurrency/asyncio.py</code> <pre><code>async def rate_limit(names: Union[str, List[str]], occupy: int = 1):\n    \"\"\"Block execution until an `occupy` number of slots of the concurrency\n    limits given in `names` are acquired. Requires that all given concurrency\n    limits have a slot decay.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = await _acquire_concurrency_slots(names, occupy, mode=\"rate_limit\")\n    _emit_concurrency_acquisition_events(limits, occupy)\n</code></pre>","tags":["Python API","concurrency","asyncio"]},{"location":"api-ref/prefect/concurrency/events/","title":"events","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/events/#prefect.concurrency.events","title":"<code>prefect.concurrency.events</code>","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/services/","title":"services","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/services/#prefect.concurrency.services","title":"<code>prefect.concurrency.services</code>","text":"","tags":["Python API","concurrency"]},{"location":"api-ref/prefect/concurrency/sync/","title":"sync","text":"","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync","title":"<code>prefect.concurrency.sync</code>","text":"","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync.concurrency","title":"<code>concurrency</code>","text":"<p>A context manager that acquires and releases concurrency slots from the given concurrency limits.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> <code>timeout_seconds</code> <code>Optional[float]</code> <p>The number of seconds to wait for the slots to be acquired before raising a <code>TimeoutError</code>. A timeout of <code>None</code> will wait indefinitely.</p> <code>None</code> <p>Raises:</p> Type Description <code>TimeoutError</code> <p>If the slots are not acquired within the given timeout.</p> <p>A simple example of using the sync <code>concurrency</code> context manager: <pre><code>from prefect.concurrency.sync import concurrency\n\ndef resource_heavy():\n    with concurrency(\"test\", occupy=1):\n        print(\"Resource heavy task\")\n\ndef main():\n    resource_heavy()\n</code></pre></p> Source code in <code>prefect/concurrency/sync.py</code> <pre><code>@contextmanager\ndef concurrency(\n    names: Union[str, List[str]],\n    occupy: int = 1,\n    timeout_seconds: Optional[float] = None,\n):\n    \"\"\"A context manager that acquires and releases concurrency slots from the\n    given concurrency limits.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n        timeout_seconds: The number of seconds to wait for the slots to be acquired before\n            raising a `TimeoutError`. A timeout of `None` will wait indefinitely.\n\n    Raises:\n        TimeoutError: If the slots are not acquired within the given timeout.\n\n    Example:\n    A simple example of using the sync `concurrency` context manager:\n    ```python\n    from prefect.concurrency.sync import concurrency\n\n    def resource_heavy():\n        with concurrency(\"test\", occupy=1):\n            print(\"Resource heavy task\")\n\n    def main():\n        resource_heavy()\n    ```\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n\n    limits: List[MinimalConcurrencyLimitResponse] = _call_async_function_from_sync(\n        _acquire_concurrency_slots, names, occupy, timeout_seconds=timeout_seconds\n    )\n    acquisition_time = pendulum.now(\"UTC\")\n    emitted_events = _emit_concurrency_acquisition_events(limits, occupy)\n\n    try:\n        yield\n    finally:\n        occupancy_period = cast(Interval, pendulum.now(\"UTC\") - acquisition_time)\n        _call_async_function_from_sync(\n            _release_concurrency_slots,\n            names,\n            occupy,\n            occupancy_period.total_seconds(),\n        )\n        _emit_concurrency_release_events(limits, occupy, emitted_events)\n</code></pre>","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/concurrency/sync/#prefect.concurrency.sync.rate_limit","title":"<code>rate_limit</code>","text":"<p>Block execution until an <code>occupy</code> number of slots of the concurrency limits given in <code>names</code> are acquired. Requires that all given concurrency limits have a slot decay.</p> <p>Parameters:</p> Name Type Description Default <code>names</code> <code>Union[str, List[str]]</code> <p>The names of the concurrency limits to acquire slots from.</p> required <code>occupy</code> <code>int</code> <p>The number of slots to acquire and hold from each limit.</p> <code>1</code> Source code in <code>prefect/concurrency/sync.py</code> <pre><code>def rate_limit(names: Union[str, List[str]], occupy: int = 1):\n    \"\"\"Block execution until an `occupy` number of slots of the concurrency\n    limits given in `names` are acquired. Requires that all given concurrency\n    limits have a slot decay.\n\n    Args:\n        names: The names of the concurrency limits to acquire slots from.\n        occupy: The number of slots to acquire and hold from each limit.\n    \"\"\"\n    names = names if isinstance(names, list) else [names]\n    limits = _call_async_function_from_sync(\n        _acquire_concurrency_slots, names, occupy, mode=\"rate_limit\"\n    )\n    _emit_concurrency_acquisition_events(limits, occupy)\n</code></pre>","tags":["Python API","concurrency","sync"]},{"location":"api-ref/prefect/deployments/base/","title":"base","text":"","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base","title":"<code>prefect.deployments.base</code>","text":"<p>Core primitives for managing Prefect deployments via <code>prefect deploy</code>, providing a minimally opinionated build system for managing flows and deployments.</p> <p>To get started, follow along with the deloyments tutorial.</p>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.configure_project_by_recipe","title":"<code>configure_project_by_recipe</code>","text":"<p>Given a recipe name, returns a dictionary representing base configuration options.</p> <p>Parameters:</p> Name Type Description Default <code>recipe</code> <code>str</code> <p>the name of the recipe to use</p> required <code>formatting_kwargs</code> <code>dict</code> <p>additional keyword arguments to format the recipe</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if provided recipe name does not exist.</p> Source code in <code>prefect/deployments/base.py</code> <pre><code>def configure_project_by_recipe(recipe: str, **formatting_kwargs) -&gt; dict:\n    \"\"\"\n    Given a recipe name, returns a dictionary representing base configuration options.\n\n    Args:\n        recipe (str): the name of the recipe to use\n        formatting_kwargs (dict, optional): additional keyword arguments to format the recipe\n\n    Raises:\n        ValueError: if provided recipe name does not exist.\n    \"\"\"\n    # load the recipe\n    recipe_path = Path(__file__).parent / \"recipes\" / recipe / \"prefect.yaml\"\n\n    if not recipe_path.exists():\n        raise ValueError(f\"Unknown recipe {recipe!r} provided.\")\n\n    with recipe_path.open(mode=\"r\") as f:\n        config = yaml.safe_load(f)\n\n    config = apply_values(\n        template=config, values=formatting_kwargs, remove_notset=False\n    )\n\n    return config\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.create_default_prefect_yaml","title":"<code>create_default_prefect_yaml</code>","text":"<p>Creates default <code>prefect.yaml</code> file in the provided path if one does not already exist; returns boolean specifying whether a file was created.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the project; if not provided, the current directory name will be used</p> <code>None</code> <code>contents</code> <code>dict</code> <p>a dictionary of contents to write to the file; if not provided, defaults will be used</p> <code>None</code> Source code in <code>prefect/deployments/base.py</code> <pre><code>def create_default_prefect_yaml(\n    path: str, name: str = None, contents: Optional[Dict[str, Any]] = None\n) -&gt; bool:\n    \"\"\"\n    Creates default `prefect.yaml` file in the provided path if one does not already exist;\n    returns boolean specifying whether a file was created.\n\n    Args:\n        name (str, optional): the name of the project; if not provided, the current directory name\n            will be used\n        contents (dict, optional): a dictionary of contents to write to the file; if not provided,\n            defaults will be used\n    \"\"\"\n    path = Path(path)\n    prefect_file = path / \"prefect.yaml\"\n    if prefect_file.exists():\n        return False\n    default_file = Path(__file__).parent / \"templates\" / \"prefect.yaml\"\n\n    with default_file.open(mode=\"r\") as df:\n        default_contents = yaml.safe_load(df)\n\n    import prefect\n\n    contents[\"prefect-version\"] = prefect.__version__\n    contents[\"name\"] = name\n\n    with prefect_file.open(mode=\"w\") as f:\n        # write header\n        f.write(\n            \"# Welcome to your prefect.yaml file! You can use this file for storing and\"\n            \" managing\\n# configuration for deploying your flows. We recommend\"\n            \" committing this file to source\\n# control along with your flow code.\\n\\n\"\n        )\n\n        f.write(\"# Generic metadata about this project\\n\")\n        yaml.dump({\"name\": contents[\"name\"]}, f, sort_keys=False)\n        yaml.dump({\"prefect-version\": contents[\"prefect-version\"]}, f, sort_keys=False)\n        f.write(\"\\n\")\n\n        # build\n        f.write(\"# build section allows you to manage and build docker images\\n\")\n        yaml.dump(\n            {\"build\": contents.get(\"build\", default_contents.get(\"build\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # push\n        f.write(\n            \"# push section allows you to manage if and how this project is uploaded to\"\n            \" remote locations\\n\"\n        )\n        yaml.dump(\n            {\"push\": contents.get(\"push\", default_contents.get(\"push\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # pull\n        f.write(\n            \"# pull section allows you to provide instructions for cloning this project\"\n            \" in remote locations\\n\"\n        )\n        yaml.dump(\n            {\"pull\": contents.get(\"pull\", default_contents.get(\"pull\"))},\n            f,\n            sort_keys=False,\n        )\n        f.write(\"\\n\")\n\n        # deployments\n        f.write(\n            \"# the deployments section allows you to provide configuration for\"\n            \" deploying flows\\n\"\n        )\n        yaml.dump(\n            {\n                \"deployments\": contents.get(\n                    \"deployments\", default_contents.get(\"deployments\")\n                )\n            },\n            f,\n            sort_keys=False,\n        )\n    return True\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/base/#prefect.deployments.base.initialize_project","title":"<code>initialize_project</code>","text":"<p>Initializes a basic project structure with base files.  If no name is provided, the name of the current directory is used.  If no recipe is provided, one is inferred.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>the name of the project; if not provided, the current directory name</p> <code>None</code> <code>recipe</code> <code>str</code> <p>the name of the recipe to use; if not provided, one is inferred</p> <code>None</code> <code>inputs</code> <code>dict</code> <p>a dictionary of inputs to use when formatting the recipe</p> <code>None</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>List[str]: a list of files / directories that were created</p> Source code in <code>prefect/deployments/base.py</code> <pre><code>def initialize_project(\n    name: str = None, recipe: str = None, inputs: Optional[Dict[str, Any]] = None\n) -&gt; List[str]:\n    \"\"\"\n    Initializes a basic project structure with base files.  If no name is provided, the name\n    of the current directory is used.  If no recipe is provided, one is inferred.\n\n    Args:\n        name (str, optional): the name of the project; if not provided, the current directory name\n        recipe (str, optional): the name of the recipe to use; if not provided, one is inferred\n        inputs (dict, optional): a dictionary of inputs to use when formatting the recipe\n\n    Returns:\n        List[str]: a list of files / directories that were created\n    \"\"\"\n    # determine if in git repo or use directory name as a default\n    is_git_based = False\n    formatting_kwargs = {\"directory\": str(Path(\".\").absolute().resolve())}\n    dir_name = os.path.basename(os.getcwd())\n\n    remote_url = _get_git_remote_origin_url()\n    if remote_url:\n        formatting_kwargs[\"repository\"] = remote_url\n        is_git_based = True\n        branch = _get_git_branch()\n        formatting_kwargs[\"branch\"] = branch or \"main\"\n\n    formatting_kwargs[\"name\"] = dir_name\n\n    has_dockerfile = Path(\"Dockerfile\").exists()\n\n    if has_dockerfile:\n        formatting_kwargs[\"dockerfile\"] = \"Dockerfile\"\n    elif recipe is not None and \"docker\" in recipe:\n        formatting_kwargs[\"dockerfile\"] = \"auto\"\n\n    # hand craft a pull step\n    if is_git_based and recipe is None:\n        if has_dockerfile:\n            recipe = \"docker-git\"\n        else:\n            recipe = \"git\"\n    elif recipe is None and has_dockerfile:\n        recipe = \"docker\"\n    elif recipe is None:\n        recipe = \"local\"\n\n    formatting_kwargs.update(inputs or {})\n    configuration = configure_project_by_recipe(recipe=recipe, **formatting_kwargs)\n\n    project_name = name or dir_name\n\n    files = []\n    if create_default_ignore_file(\".\"):\n        files.append(\".prefectignore\")\n    if create_default_prefect_yaml(\".\", name=project_name, contents=configuration):\n        files.append(\"prefect.yaml\")\n\n    return files\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/deployments/","title":"deployments","text":"","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments","title":"<code>prefect.deployments.deployments</code>","text":"<p>Objects for specifying deployments and utilities for loading flows from deployments.</p>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>BaseModel</code></p> <p>DEPRECATION WARNING:</p> <p>This class is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by <code>flow.deploy</code>, which offers enhanced functionality and better a better user experience. For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>A Prefect Deployment definition, used for specifying and building deployments.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <p>A name for the deployment (required).</p> required <code>version</code> <p>An optional version for the deployment; defaults to the flow's version</p> required <code>description</code> <p>An optional description of the deployment; defaults to the flow's description</p> required <code>tags</code> <p>An optional list of tags to associate with this deployment; note that tags are used only for organizational purposes. For delegating work to agents, see <code>work_queue_name</code>.</p> required <code>schedule</code> <p>A schedule to run this deployment on, once registered (deprecated)</p> required <code>is_schedule_active</code> <p>Whether or not the schedule is active (deprecated)</p> required <code>schedules</code> <p>A list of schedules to run this deployment on</p> required <code>work_queue_name</code> <p>The work queue that will handle this deployment's runs</p> required <code>work_pool_name</code> <p>The work pool for the deployment</p> required <code>flow_name</code> <p>The name of the flow this deployment encapsulates</p> required <code>parameters</code> <p>A dictionary of parameter values to pass to runs created from this deployment</p> required <code>infrastructure</code> <p>An optional infrastructure block used to configure infrastructure for runs; if not provided, will default to running this deployment in Agent subprocesses</p> required <code>job_variables</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code></p> required <code>storage</code> <p>An optional remote storage block used to store and retrieve this workflow; if not provided, will default to referencing this flow by its local path</p> required <code>path</code> <p>The path to the working directory for the workflow, relative to remote storage or, if stored on a local filesystem, an absolute path</p> required <code>entrypoint</code> <p>The path to the entrypoint for the workflow, always relative to the <code>path</code></p> required <code>parameter_openapi_schema</code> <p>The parameter schema of the flow, including defaults.</p> required <code>enforce_parameter_schema</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> required <pre><code>Create a new deployment using configuration defaults for an imported flow:\n\n&gt;&gt;&gt; from my_project.flows import my_flow\n&gt;&gt;&gt; from prefect.deployments import Deployment\n&gt;&gt;&gt;\n&gt;&gt;&gt; deployment = Deployment.build_from_flow(\n...     flow=my_flow,\n...     name=\"example\",\n...     version=\"1\",\n...     tags=[\"demo\"],\n&gt;&gt;&gt; )\n&gt;&gt;&gt; deployment.apply()\n\nCreate a new deployment with custom storage and an infrastructure override:\n\n&gt;&gt;&gt; from my_project.flows import my_flow\n&gt;&gt;&gt; from prefect.deployments import Deployment\n&gt;&gt;&gt; from prefect.filesystems import S3\n\n&gt;&gt;&gt; storage = S3.load(\"dev-bucket\") # load a pre-defined block\n&gt;&gt;&gt; deployment = Deployment.build_from_flow(\n...     flow=my_flow,\n...     name=\"s3-example\",\n...     version=\"2\",\n...     tags=[\"aws\"],\n...     storage=storage,\n...     job_variables=dict(\"env.PREFECT_LOGGING_LEVEL\"=\"DEBUG\"),\n&gt;&gt;&gt; )\n&gt;&gt;&gt; deployment.apply()\n</code></pre> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use `flow.deploy` to deploy your flows instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass Deployment(DeprecatedInfraOverridesField, BaseModel):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This class is deprecated as of March 2024 and will not be available after September 2024.\n    It has been replaced by `flow.deploy`, which offers enhanced functionality and better a better user experience.\n    For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\n\n    A Prefect Deployment definition, used for specifying and building deployments.\n\n    Args:\n        name: A name for the deployment (required).\n        version: An optional version for the deployment; defaults to the flow's version\n        description: An optional description of the deployment; defaults to the flow's\n            description\n        tags: An optional list of tags to associate with this deployment; note that tags\n            are used only for organizational purposes. For delegating work to agents,\n            see `work_queue_name`.\n        schedule: A schedule to run this deployment on, once registered (deprecated)\n        is_schedule_active: Whether or not the schedule is active (deprecated)\n        schedules: A list of schedules to run this deployment on\n        work_queue_name: The work queue that will handle this deployment's runs\n        work_pool_name: The work pool for the deployment\n        flow_name: The name of the flow this deployment encapsulates\n        parameters: A dictionary of parameter values to pass to runs created from this\n            deployment\n        infrastructure: An optional infrastructure block used to configure\n            infrastructure for runs; if not provided, will default to running this\n            deployment in Agent subprocesses\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`\n        storage: An optional remote storage block used to store and retrieve this\n            workflow; if not provided, will default to referencing this flow by its\n            local path\n        path: The path to the working directory for the workflow, relative to remote\n            storage or, if stored on a local filesystem, an absolute path\n        entrypoint: The path to the entrypoint for the workflow, always relative to the\n            `path`\n        parameter_openapi_schema: The parameter schema of the flow, including defaults.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n\n    Examples:\n\n        Create a new deployment using configuration defaults for an imported flow:\n\n        &gt;&gt;&gt; from my_project.flows import my_flow\n        &gt;&gt;&gt; from prefect.deployments import Deployment\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; deployment = Deployment.build_from_flow(\n        ...     flow=my_flow,\n        ...     name=\"example\",\n        ...     version=\"1\",\n        ...     tags=[\"demo\"],\n        &gt;&gt;&gt; )\n        &gt;&gt;&gt; deployment.apply()\n\n        Create a new deployment with custom storage and an infrastructure override:\n\n        &gt;&gt;&gt; from my_project.flows import my_flow\n        &gt;&gt;&gt; from prefect.deployments import Deployment\n        &gt;&gt;&gt; from prefect.filesystems import S3\n\n        &gt;&gt;&gt; storage = S3.load(\"dev-bucket\") # load a pre-defined block\n        &gt;&gt;&gt; deployment = Deployment.build_from_flow(\n        ...     flow=my_flow,\n        ...     name=\"s3-example\",\n        ...     version=\"2\",\n        ...     tags=[\"aws\"],\n        ...     storage=storage,\n        ...     job_variables=dict(\"env.PREFECT_LOGGING_LEVEL\"=\"DEBUG\"),\n        &gt;&gt;&gt; )\n        &gt;&gt;&gt; deployment.apply()\n\n    \"\"\"\n\n    class Config:\n        json_encoders = {SecretDict: lambda v: v.dict()}\n        validate_assignment = True\n        extra = \"forbid\"\n\n    @property\n    def _editable_fields(self) -&gt; List[str]:\n        editable_fields = [\n            \"name\",\n            \"description\",\n            \"version\",\n            \"work_queue_name\",\n            \"work_pool_name\",\n            \"tags\",\n            \"parameters\",\n            \"schedule\",\n            \"schedules\",\n            \"is_schedule_active\",\n            # The `infra_overrides` field has been renamed to `job_variables`.\n            # We will continue writing it in the YAML file as `infra_overrides`\n            # instead of `job_variables` for better backwards compat, but we'll\n            # accept either `job_variables` or `infra_overrides` when we read\n            # the file.\n            \"infra_overrides\",\n        ]\n\n        # if infrastructure is baked as a pre-saved block, then\n        # editing its fields will not update anything\n        if self.infrastructure._block_document_id:\n            return editable_fields\n        else:\n            return editable_fields + [\"infrastructure\"]\n\n    @property\n    def location(self) -&gt; str:\n        \"\"\"\n        The 'location' that this deployment points to is given by `path` alone\n        in the case of no remote storage, and otherwise by `storage.basepath / path`.\n\n        The underlying flow entrypoint is interpreted relative to this location.\n        \"\"\"\n        location = \"\"\n        if self.storage:\n            location = (\n                self.storage.basepath + \"/\"\n                if not self.storage.basepath.endswith(\"/\")\n                else \"\"\n            )\n        if self.path:\n            location += self.path\n        return location\n\n    @sync_compatible\n    async def to_yaml(self, path: Path) -&gt; None:\n        yaml_dict = self._yaml_dict()\n        schema = self.schema()\n\n        with open(path, \"w\") as f:\n            # write header\n            f.write(\n                \"###\\n### A complete description of a Prefect Deployment for flow\"\n                f\" {self.flow_name!r}\\n###\\n\"\n            )\n\n            # write editable fields\n            for field in self._editable_fields:\n                # write any comments\n                if schema[\"properties\"][field].get(\"yaml_comment\"):\n                    f.write(f\"# {schema['properties'][field]['yaml_comment']}\\n\")\n                # write the field\n                yaml.dump({field: yaml_dict[field]}, f, sort_keys=False)\n\n            # write non-editable fields, excluding `job_variables` because we'll\n            # continue writing it as `infra_overrides` for better backwards compat\n            # with the existing file format.\n            f.write(\"\\n###\\n### DO NOT EDIT BELOW THIS LINE\\n###\\n\")\n            yaml.dump(\n                {\n                    k: v\n                    for k, v in yaml_dict.items()\n                    if k not in self._editable_fields and k != \"job_variables\"\n                },\n                f,\n                sort_keys=False,\n            )\n\n    def _yaml_dict(self) -&gt; dict:\n        \"\"\"\n        Returns a YAML-compatible representation of this deployment as a dictionary.\n        \"\"\"\n        # avoids issues with UUIDs showing up in YAML\n        all_fields = json.loads(\n            self.json(\n                exclude={\n                    \"storage\": {\"_filesystem\", \"filesystem\", \"_remote_file_system\"}\n                }\n            )\n        )\n        if all_fields[\"storage\"]:\n            all_fields[\"storage\"][\n                \"_block_type_slug\"\n            ] = self.storage.get_block_type_slug()\n        if all_fields[\"infrastructure\"]:\n            all_fields[\"infrastructure\"][\n                \"_block_type_slug\"\n            ] = self.infrastructure.get_block_type_slug()\n        return all_fields\n\n    @classmethod\n    def _validate_schedule(cls, value):\n        \"\"\"We do not support COUNT-based (# of occurrences) RRule schedules for deployments.\"\"\"\n        if value:\n            rrule_value = getattr(value, \"rrule\", None)\n            if rrule_value and \"COUNT\" in rrule_value.upper():\n                raise ValueError(\n                    \"RRule schedules with `COUNT` are not supported. Please use `UNTIL`\"\n                    \" or the `/deployments/{id}/schedule` endpoint to schedule a fixed\"\n                    \" number of flow runs.\"\n                )\n\n    # top level metadata\n    name: str = Field(..., description=\"The name of the deployment.\")\n    description: Optional[str] = Field(\n        default=None, description=\"An optional description of the deployment.\"\n    )\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"One of more tags to apply to this deployment.\",\n    )\n    schedule: Optional[SCHEDULE_TYPES] = Field(default=None)\n    schedules: List[MinimalDeploymentSchedule] = Field(\n        default_factory=list,\n        description=\"The schedules to run this deployment on.\",\n    )\n    is_schedule_active: Optional[bool] = Field(\n        default=None, description=\"Whether or not the schedule is active.\"\n    )\n    flow_name: Optional[str] = Field(default=None, description=\"The name of the flow.\")\n    work_queue_name: Optional[str] = Field(\n        \"default\",\n        description=\"The work queue for the deployment.\",\n        yaml_comment=\"The work queue that will handle this deployment's runs\",\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None, description=\"The work pool for the deployment\"\n    )\n    # flow data\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    infrastructure: Infrastructure = Field(default_factory=Process)\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to the base infrastructure block at runtime.\",\n    )\n    storage: Optional[Block] = Field(\n        None,\n        help=\"The remote storage to use for this workflow.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    parameter_openapi_schema: ParameterSchema = Field(\n        default_factory=ParameterSchema,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    timestamp: datetime = Field(default_factory=partial(pendulum.now, \"UTC\"))\n    triggers: List[Union[DeploymentTriggerTypes, TriggerTypes]] = Field(\n        default_factory=list,\n        description=\"The triggers that should cause this deployment to run.\",\n    )\n    # defaults to None to allow for backwards compatibility\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the Prefect API should enforce the parameter schema for\"\n            \" this deployment.\"\n        ),\n    )\n\n    @validator(\"infrastructure\", pre=True)\n    def validate_infrastructure_capabilities(cls, value):\n        return infrastructure_must_have_capabilities(value)\n\n    @validator(\"storage\", pre=True)\n    def validate_storage(cls, value):\n        return storage_must_have_capabilities(value)\n\n    @validator(\"parameter_openapi_schema\", pre=True)\n    def validate_parameter_openapi_schema(cls, value):\n        return handle_openapi_schema(value)\n\n    @validator(\"triggers\")\n    def validate_triggers(cls, field_value, values):\n        return validate_automation_names(field_value, values)\n\n    @root_validator(pre=True)\n    def validate_schedule(cls, values):\n        return validate_deprecated_schedule_fields(values, logger)\n\n    @root_validator(pre=True)\n    def validate_backwards_compatibility_for_schedule(cls, values):\n        return reconcile_schedules(cls, values)\n\n    @classmethod\n    @sync_compatible\n    async def load_from_yaml(cls, path: str):\n        data = yaml.safe_load(await anyio.Path(path).read_bytes())\n        # load blocks from server to ensure secret values are properly hydrated\n        if data.get(\"storage\"):\n            block_doc_name = data[\"storage\"].get(\"_block_document_name\")\n            # if no doc name, this block is not stored on the server\n            if block_doc_name:\n                block_slug = data[\"storage\"][\"_block_type_slug\"]\n                block = await Block.load(f\"{block_slug}/{block_doc_name}\")\n                data[\"storage\"] = block\n\n        if data.get(\"infrastructure\"):\n            block_doc_name = data[\"infrastructure\"].get(\"_block_document_name\")\n            # if no doc name, this block is not stored on the server\n            if block_doc_name:\n                block_slug = data[\"infrastructure\"][\"_block_type_slug\"]\n                block = await Block.load(f\"{block_slug}/{block_doc_name}\")\n                data[\"infrastructure\"] = block\n\n            return cls(**data)\n\n    @sync_compatible\n    async def load(self) -&gt; bool:\n        \"\"\"\n        Queries the API for a deployment with this name for this flow, and if found,\n        prepopulates any settings that were not set at initialization.\n\n        Returns a boolean specifying whether a load was successful or not.\n\n        Raises:\n            - ValueError: if both name and flow name are not set\n        \"\"\"\n        if not self.name or not self.flow_name:\n            raise ValueError(\"Both a deployment name and flow name must be provided.\")\n        async with get_client() as client:\n            try:\n                deployment = await client.read_deployment_by_name(\n                    f\"{self.flow_name}/{self.name}\"\n                )\n                if deployment.storage_document_id:\n                    Block._from_block_document(\n                        await client.read_block_document(deployment.storage_document_id)\n                    )\n\n                excluded_fields = self.__fields_set__.union(\n                    {\n                        \"infrastructure\",\n                        \"storage\",\n                        \"timestamp\",\n                        \"triggers\",\n                        \"enforce_parameter_schema\",\n                        \"schedules\",\n                        \"schedule\",\n                        \"is_schedule_active\",\n                    }\n                )\n                for field in set(self.__fields__.keys()) - excluded_fields:\n                    new_value = getattr(deployment, field)\n                    setattr(self, field, new_value)\n\n                if \"schedules\" not in self.__fields_set__:\n                    self.schedules = [\n                        MinimalDeploymentSchedule(\n                            **schedule.dict(include={\"schedule\", \"active\"})\n                        )\n                        for schedule in deployment.schedules\n                    ]\n\n                # The API server generates the \"schedule\" field from the\n                # current list of schedules, so if the user has locally set\n                # \"schedules\" to anything, we should avoid sending \"schedule\"\n                # and let the API server generate a new value if necessary.\n                if \"schedules\" in self.__fields_set__:\n                    self.schedule = None\n                    self.is_schedule_active = None\n                else:\n                    # The user isn't using \"schedules,\" so we should\n                    # populate \"schedule\" and \"is_schedule_active\" from the\n                    # API's version of the deployment, unless the user gave\n                    # us these fields in __init__().\n                    if \"schedule\" not in self.__fields_set__:\n                        self.schedule = deployment.schedule\n                    if \"is_schedule_active\" not in self.__fields_set__:\n                        self.is_schedule_active = deployment.is_schedule_active\n\n                if \"infrastructure\" not in self.__fields_set__:\n                    if deployment.infrastructure_document_id:\n                        self.infrastructure = Block._from_block_document(\n                            await client.read_block_document(\n                                deployment.infrastructure_document_id\n                            )\n                        )\n                if \"storage\" not in self.__fields_set__:\n                    if deployment.storage_document_id:\n                        self.storage = Block._from_block_document(\n                            await client.read_block_document(\n                                deployment.storage_document_id\n                            )\n                        )\n            except ObjectNotFound:\n                return False\n        return True\n\n    @sync_compatible\n    async def update(self, ignore_none: bool = False, **kwargs):\n        \"\"\"\n        Performs an in-place update with the provided settings.\n\n        Args:\n            ignore_none: if True, all `None` values are ignored when performing the\n                update\n        \"\"\"\n        unknown_keys = set(kwargs.keys()) - set(self.dict().keys())\n        if unknown_keys:\n            raise ValueError(\n                f\"Received unexpected attributes: {', '.join(unknown_keys)}\"\n            )\n        for key, value in kwargs.items():\n            if ignore_none and value is None:\n                continue\n            setattr(self, key, value)\n\n    @sync_compatible\n    async def upload_to_storage(\n        self, storage_block: str = None, ignore_file: str = \".prefectignore\"\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Uploads the workflow this deployment represents using a provided storage block;\n        if no block is provided, defaults to configuring self for local storage.\n\n        Args:\n            storage_block: a string reference a remote storage block slug `$type/$name`;\n                if provided, used to upload the workflow's project\n            ignore_file: an optional path to a `.prefectignore` file that specifies\n                filename patterns to ignore when uploading to remote storage; if not\n                provided, looks for `.prefectignore` in the current working directory\n        \"\"\"\n        file_count = None\n        if storage_block:\n            storage = await Block.load(storage_block)\n\n            if \"put-directory\" not in storage.get_block_capabilities():\n                raise BlockMissingCapabilities(\n                    f\"Storage block {storage!r} missing 'put-directory' capability.\"\n                )\n\n            self.storage = storage\n\n            # upload current directory to storage location\n            file_count = await self.storage.put_directory(\n                ignore_file=ignore_file, to_path=self.path\n            )\n        elif self.storage:\n            if \"put-directory\" not in self.storage.get_block_capabilities():\n                raise BlockMissingCapabilities(\n                    f\"Storage block {self.storage!r} missing 'put-directory'\"\n                    \" capability.\"\n                )\n\n            file_count = await self.storage.put_directory(\n                ignore_file=ignore_file, to_path=self.path\n            )\n\n        # persists storage now in case it contains secret values\n        if self.storage and not self.storage._block_document_id:\n            await self.storage._save(is_anonymous=True)\n\n        return file_count\n\n    @sync_compatible\n    async def apply(\n        self, upload: bool = False, work_queue_concurrency: int = None\n    ) -&gt; UUID:\n        \"\"\"\n        Registers this deployment with the API and returns the deployment's ID.\n\n        Args:\n            upload: if True, deployment files are automatically uploaded to remote\n                storage\n            work_queue_concurrency: If provided, sets the concurrency limit on the\n                deployment's work queue\n        \"\"\"\n        if not self.name or not self.flow_name:\n            raise ValueError(\"Both a deployment name and flow name must be set.\")\n        async with get_client() as client:\n            # prep IDs\n            flow_id = await client.create_flow_from_name(self.flow_name)\n\n            infrastructure_document_id = self.infrastructure._block_document_id\n            if not infrastructure_document_id:\n                # if not building off a block, will create an anonymous block\n                self.infrastructure = self.infrastructure.copy()\n                infrastructure_document_id = await self.infrastructure._save(\n                    is_anonymous=True,\n                )\n\n            if upload:\n                await self.upload_to_storage()\n\n            if self.work_queue_name and work_queue_concurrency is not None:\n                try:\n                    res = await client.create_work_queue(\n                        name=self.work_queue_name, work_pool_name=self.work_pool_name\n                    )\n                except ObjectAlreadyExists:\n                    res = await client.read_work_queue_by_name(\n                        name=self.work_queue_name, work_pool_name=self.work_pool_name\n                    )\n                await client.update_work_queue(\n                    res.id, concurrency_limit=work_queue_concurrency\n                )\n\n            if self.schedule:\n                logger.info(\n                    \"Interpreting the deprecated `schedule` field as an entry in \"\n                    \"`schedules`.\"\n                )\n                schedules = [\n                    DeploymentScheduleCreate(\n                        schedule=self.schedule, active=self.is_schedule_active\n                    )\n                ]\n            elif self.schedules:\n                schedules = [\n                    DeploymentScheduleCreate(**schedule.dict())\n                    for schedule in self.schedules\n                ]\n            else:\n                schedules = None\n\n            # we assume storage was already saved\n            storage_document_id = getattr(self.storage, \"_block_document_id\", None)\n            deployment_id = await client.create_deployment(\n                flow_id=flow_id,\n                name=self.name,\n                work_queue_name=self.work_queue_name,\n                work_pool_name=self.work_pool_name,\n                version=self.version,\n                schedules=schedules,\n                is_schedule_active=self.is_schedule_active,\n                parameters=self.parameters,\n                description=self.description,\n                tags=self.tags,\n                manifest_path=self.manifest_path,  # allows for backwards YAML compat\n                path=self.path,\n                entrypoint=self.entrypoint,\n                job_variables=self.job_variables,\n                storage_document_id=storage_document_id,\n                infrastructure_document_id=infrastructure_document_id,\n                parameter_openapi_schema=self.parameter_openapi_schema.dict(),\n                enforce_parameter_schema=self.enforce_parameter_schema,\n            )\n\n            if client.server_type.supports_automations():\n                try:\n                    # The triggers defined in the deployment spec are, essentially,\n                    # anonymous and attempting truly sync them with cloud is not\n                    # feasible. Instead, we remove all automations that are owned\n                    # by the deployment, meaning that they were created via this\n                    # mechanism below, and then recreate them.\n                    await client.delete_resource_owned_automations(\n                        f\"prefect.deployment.{deployment_id}\"\n                    )\n                except PrefectHTTPStatusError as e:\n                    if e.response.status_code == 404:\n                        # This Prefect server does not support automations, so we can safely\n                        # ignore this 404 and move on.\n                        return deployment_id\n                    raise e\n\n                for trigger in self.triggers:\n                    trigger.set_deployment_id(deployment_id)\n                    await client.create_automation(trigger.as_automation())\n\n            return deployment_id\n\n    @classmethod\n    @sync_compatible\n    async def build_from_flow(\n        cls,\n        flow: Flow,\n        name: str,\n        output: str = None,\n        skip_upload: bool = False,\n        ignore_file: str = \".prefectignore\",\n        apply: bool = False,\n        load_existing: bool = True,\n        schedules: Optional[FlexibleScheduleList] = None,\n        **kwargs,\n    ) -&gt; \"Deployment\":\n        \"\"\"\n        Configure a deployment for a given flow.\n\n        Args:\n            flow: A flow function to deploy\n            name: A name for the deployment\n            output (optional): if provided, the full deployment specification will be\n                written as a YAML file in the location specified by `output`\n            skip_upload: if True, deployment files are not automatically uploaded to\n                remote storage\n            ignore_file: an optional path to a `.prefectignore` file that specifies\n                filename patterns to ignore when uploading to remote storage; if not\n                provided, looks for `.prefectignore` in the current working directory\n            apply: if True, the deployment is automatically registered with the API\n            load_existing: if True, load any settings that may already be configured for\n                the named deployment server-side (e.g., schedules, default parameter\n                values, etc.)\n            schedules: An optional list of schedules. Each item in the list can be:\n                  - An instance of `MinimalDeploymentSchedule`.\n                  - A dictionary with a `schedule` key, and optionally, an\n                    `active` key. The `schedule` key should correspond to a\n                    schedule type, and `active` is a boolean indicating whether\n                    the schedule is active or not.\n                  - An instance of one of the predefined schedule types:\n                    `IntervalSchedule`, `CronSchedule`, or `RRuleSchedule`.\n            **kwargs: other keyword arguments to pass to the constructor for the\n                `Deployment` class\n        \"\"\"\n        if not name:\n            raise ValueError(\"A deployment name must be provided.\")\n\n        # note that `deployment.load` only updates settings that were *not*\n        # provided at initialization\n\n        deployment_args = {\n            \"name\": name,\n            \"flow_name\": flow.name,\n            **kwargs,\n        }\n\n        if schedules is not None:\n            deployment_args[\"schedules\"] = schedules\n\n        deployment = cls(**deployment_args)\n        deployment.flow_name = flow.name\n        if not deployment.entrypoint:\n            ## first see if an entrypoint can be determined\n            flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n            mod_name = getattr(flow, \"__module__\", None)\n            if not flow_file:\n                if not mod_name:\n                    # todo, check if the file location was manually set already\n                    raise ValueError(\"Could not determine flow's file location.\")\n                module = importlib.import_module(mod_name)\n                flow_file = getattr(module, \"__file__\", None)\n                if not flow_file:\n                    raise ValueError(\"Could not determine flow's file location.\")\n\n            # set entrypoint\n            entry_path = Path(flow_file).absolute().relative_to(Path(\".\").absolute())\n            deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n        if load_existing:\n            await deployment.load()\n\n        # set a few attributes for this flow object\n        deployment.parameter_openapi_schema = parameter_schema(flow)\n\n        # ensure the ignore file exists\n        if not Path(ignore_file).exists():\n            Path(ignore_file).touch()\n\n        if not deployment.version:\n            deployment.version = flow.version\n        if not deployment.description:\n            deployment.description = flow.description\n\n        # proxy for whether infra is docker-based\n        is_docker_based = hasattr(deployment.infrastructure, \"image\")\n\n        if not deployment.storage and not is_docker_based and not deployment.path:\n            deployment.path = str(Path(\".\").absolute())\n        elif not deployment.storage and is_docker_based:\n            # only update if a path is not already set\n            if not deployment.path:\n                deployment.path = \"/opt/prefect/flows\"\n\n        if not skip_upload:\n            if (\n                deployment.storage\n                and \"put-directory\" in deployment.storage.get_block_capabilities()\n            ):\n                await deployment.upload_to_storage(ignore_file=ignore_file)\n\n        if output:\n            await deployment.to_yaml(output)\n\n        if apply:\n            await deployment.apply()\n\n        return deployment\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.location","title":"<code>location: str</code>  <code>property</code>","text":"<p>The 'location' that this deployment points to is given by <code>path</code> alone in the case of no remote storage, and otherwise by <code>storage.basepath / path</code>.</p> <p>The underlying flow entrypoint is interpreted relative to this location.</p>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Registers this deployment with the API and returns the deployment's ID.</p> <p>Parameters:</p> Name Type Description Default <code>upload</code> <code>bool</code> <p>if True, deployment files are automatically uploaded to remote storage</p> <code>False</code> <code>work_queue_concurrency</code> <code>int</code> <p>If provided, sets the concurrency limit on the deployment's work queue</p> <code>None</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def apply(\n    self, upload: bool = False, work_queue_concurrency: int = None\n) -&gt; UUID:\n    \"\"\"\n    Registers this deployment with the API and returns the deployment's ID.\n\n    Args:\n        upload: if True, deployment files are automatically uploaded to remote\n            storage\n        work_queue_concurrency: If provided, sets the concurrency limit on the\n            deployment's work queue\n    \"\"\"\n    if not self.name or not self.flow_name:\n        raise ValueError(\"Both a deployment name and flow name must be set.\")\n    async with get_client() as client:\n        # prep IDs\n        flow_id = await client.create_flow_from_name(self.flow_name)\n\n        infrastructure_document_id = self.infrastructure._block_document_id\n        if not infrastructure_document_id:\n            # if not building off a block, will create an anonymous block\n            self.infrastructure = self.infrastructure.copy()\n            infrastructure_document_id = await self.infrastructure._save(\n                is_anonymous=True,\n            )\n\n        if upload:\n            await self.upload_to_storage()\n\n        if self.work_queue_name and work_queue_concurrency is not None:\n            try:\n                res = await client.create_work_queue(\n                    name=self.work_queue_name, work_pool_name=self.work_pool_name\n                )\n            except ObjectAlreadyExists:\n                res = await client.read_work_queue_by_name(\n                    name=self.work_queue_name, work_pool_name=self.work_pool_name\n                )\n            await client.update_work_queue(\n                res.id, concurrency_limit=work_queue_concurrency\n            )\n\n        if self.schedule:\n            logger.info(\n                \"Interpreting the deprecated `schedule` field as an entry in \"\n                \"`schedules`.\"\n            )\n            schedules = [\n                DeploymentScheduleCreate(\n                    schedule=self.schedule, active=self.is_schedule_active\n                )\n            ]\n        elif self.schedules:\n            schedules = [\n                DeploymentScheduleCreate(**schedule.dict())\n                for schedule in self.schedules\n            ]\n        else:\n            schedules = None\n\n        # we assume storage was already saved\n        storage_document_id = getattr(self.storage, \"_block_document_id\", None)\n        deployment_id = await client.create_deployment(\n            flow_id=flow_id,\n            name=self.name,\n            work_queue_name=self.work_queue_name,\n            work_pool_name=self.work_pool_name,\n            version=self.version,\n            schedules=schedules,\n            is_schedule_active=self.is_schedule_active,\n            parameters=self.parameters,\n            description=self.description,\n            tags=self.tags,\n            manifest_path=self.manifest_path,  # allows for backwards YAML compat\n            path=self.path,\n            entrypoint=self.entrypoint,\n            job_variables=self.job_variables,\n            storage_document_id=storage_document_id,\n            infrastructure_document_id=infrastructure_document_id,\n            parameter_openapi_schema=self.parameter_openapi_schema.dict(),\n            enforce_parameter_schema=self.enforce_parameter_schema,\n        )\n\n        if client.server_type.supports_automations():\n            try:\n                # The triggers defined in the deployment spec are, essentially,\n                # anonymous and attempting truly sync them with cloud is not\n                # feasible. Instead, we remove all automations that are owned\n                # by the deployment, meaning that they were created via this\n                # mechanism below, and then recreate them.\n                await client.delete_resource_owned_automations(\n                    f\"prefect.deployment.{deployment_id}\"\n                )\n            except PrefectHTTPStatusError as e:\n                if e.response.status_code == 404:\n                    # This Prefect server does not support automations, so we can safely\n                    # ignore this 404 and move on.\n                    return deployment_id\n                raise e\n\n            for trigger in self.triggers:\n                trigger.set_deployment_id(deployment_id)\n                await client.create_automation(trigger.as_automation())\n\n        return deployment_id\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.build_from_flow","title":"<code>build_from_flow</code>  <code>async</code> <code>classmethod</code>","text":"<p>Configure a deployment for a given flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow function to deploy</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>output</code> <code>optional</code> <p>if provided, the full deployment specification will be written as a YAML file in the location specified by <code>output</code></p> <code>None</code> <code>skip_upload</code> <code>bool</code> <p>if True, deployment files are not automatically uploaded to remote storage</p> <code>False</code> <code>ignore_file</code> <code>str</code> <p>an optional path to a <code>.prefectignore</code> file that specifies filename patterns to ignore when uploading to remote storage; if not provided, looks for <code>.prefectignore</code> in the current working directory</p> <code>'.prefectignore'</code> <code>apply</code> <code>bool</code> <p>if True, the deployment is automatically registered with the API</p> <code>False</code> <code>load_existing</code> <code>bool</code> <p>if True, load any settings that may already be configured for the named deployment server-side (e.g., schedules, default parameter values, etc.)</p> <code>True</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>An optional list of schedules. Each item in the list can be:   - An instance of <code>MinimalDeploymentSchedule</code>.   - A dictionary with a <code>schedule</code> key, and optionally, an     <code>active</code> key. The <code>schedule</code> key should correspond to a     schedule type, and <code>active</code> is a boolean indicating whether     the schedule is active or not.   - An instance of one of the predefined schedule types:     <code>IntervalSchedule</code>, <code>CronSchedule</code>, or <code>RRuleSchedule</code>.</p> <code>None</code> <code>**kwargs</code> <p>other keyword arguments to pass to the constructor for the <code>Deployment</code> class</p> <code>{}</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def build_from_flow(\n    cls,\n    flow: Flow,\n    name: str,\n    output: str = None,\n    skip_upload: bool = False,\n    ignore_file: str = \".prefectignore\",\n    apply: bool = False,\n    load_existing: bool = True,\n    schedules: Optional[FlexibleScheduleList] = None,\n    **kwargs,\n) -&gt; \"Deployment\":\n    \"\"\"\n    Configure a deployment for a given flow.\n\n    Args:\n        flow: A flow function to deploy\n        name: A name for the deployment\n        output (optional): if provided, the full deployment specification will be\n            written as a YAML file in the location specified by `output`\n        skip_upload: if True, deployment files are not automatically uploaded to\n            remote storage\n        ignore_file: an optional path to a `.prefectignore` file that specifies\n            filename patterns to ignore when uploading to remote storage; if not\n            provided, looks for `.prefectignore` in the current working directory\n        apply: if True, the deployment is automatically registered with the API\n        load_existing: if True, load any settings that may already be configured for\n            the named deployment server-side (e.g., schedules, default parameter\n            values, etc.)\n        schedules: An optional list of schedules. Each item in the list can be:\n              - An instance of `MinimalDeploymentSchedule`.\n              - A dictionary with a `schedule` key, and optionally, an\n                `active` key. The `schedule` key should correspond to a\n                schedule type, and `active` is a boolean indicating whether\n                the schedule is active or not.\n              - An instance of one of the predefined schedule types:\n                `IntervalSchedule`, `CronSchedule`, or `RRuleSchedule`.\n        **kwargs: other keyword arguments to pass to the constructor for the\n            `Deployment` class\n    \"\"\"\n    if not name:\n        raise ValueError(\"A deployment name must be provided.\")\n\n    # note that `deployment.load` only updates settings that were *not*\n    # provided at initialization\n\n    deployment_args = {\n        \"name\": name,\n        \"flow_name\": flow.name,\n        **kwargs,\n    }\n\n    if schedules is not None:\n        deployment_args[\"schedules\"] = schedules\n\n    deployment = cls(**deployment_args)\n    deployment.flow_name = flow.name\n    if not deployment.entrypoint:\n        ## first see if an entrypoint can be determined\n        flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n        mod_name = getattr(flow, \"__module__\", None)\n        if not flow_file:\n            if not mod_name:\n                # todo, check if the file location was manually set already\n                raise ValueError(\"Could not determine flow's file location.\")\n            module = importlib.import_module(mod_name)\n            flow_file = getattr(module, \"__file__\", None)\n            if not flow_file:\n                raise ValueError(\"Could not determine flow's file location.\")\n\n        # set entrypoint\n        entry_path = Path(flow_file).absolute().relative_to(Path(\".\").absolute())\n        deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n    if load_existing:\n        await deployment.load()\n\n    # set a few attributes for this flow object\n    deployment.parameter_openapi_schema = parameter_schema(flow)\n\n    # ensure the ignore file exists\n    if not Path(ignore_file).exists():\n        Path(ignore_file).touch()\n\n    if not deployment.version:\n        deployment.version = flow.version\n    if not deployment.description:\n        deployment.description = flow.description\n\n    # proxy for whether infra is docker-based\n    is_docker_based = hasattr(deployment.infrastructure, \"image\")\n\n    if not deployment.storage and not is_docker_based and not deployment.path:\n        deployment.path = str(Path(\".\").absolute())\n    elif not deployment.storage and is_docker_based:\n        # only update if a path is not already set\n        if not deployment.path:\n            deployment.path = \"/opt/prefect/flows\"\n\n    if not skip_upload:\n        if (\n            deployment.storage\n            and \"put-directory\" in deployment.storage.get_block_capabilities()\n        ):\n            await deployment.upload_to_storage(ignore_file=ignore_file)\n\n    if output:\n        await deployment.to_yaml(output)\n\n    if apply:\n        await deployment.apply()\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.load","title":"<code>load</code>  <code>async</code>","text":"<p>Queries the API for a deployment with this name for this flow, and if found, prepopulates any settings that were not set at initialization.</p> <p>Returns a boolean specifying whether a load was successful or not.</p> <p>Raises:</p> Type Description <code>-ValueError</code> <p>if both name and flow name are not set</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def load(self) -&gt; bool:\n    \"\"\"\n    Queries the API for a deployment with this name for this flow, and if found,\n    prepopulates any settings that were not set at initialization.\n\n    Returns a boolean specifying whether a load was successful or not.\n\n    Raises:\n        - ValueError: if both name and flow name are not set\n    \"\"\"\n    if not self.name or not self.flow_name:\n        raise ValueError(\"Both a deployment name and flow name must be provided.\")\n    async with get_client() as client:\n        try:\n            deployment = await client.read_deployment_by_name(\n                f\"{self.flow_name}/{self.name}\"\n            )\n            if deployment.storage_document_id:\n                Block._from_block_document(\n                    await client.read_block_document(deployment.storage_document_id)\n                )\n\n            excluded_fields = self.__fields_set__.union(\n                {\n                    \"infrastructure\",\n                    \"storage\",\n                    \"timestamp\",\n                    \"triggers\",\n                    \"enforce_parameter_schema\",\n                    \"schedules\",\n                    \"schedule\",\n                    \"is_schedule_active\",\n                }\n            )\n            for field in set(self.__fields__.keys()) - excluded_fields:\n                new_value = getattr(deployment, field)\n                setattr(self, field, new_value)\n\n            if \"schedules\" not in self.__fields_set__:\n                self.schedules = [\n                    MinimalDeploymentSchedule(\n                        **schedule.dict(include={\"schedule\", \"active\"})\n                    )\n                    for schedule in deployment.schedules\n                ]\n\n            # The API server generates the \"schedule\" field from the\n            # current list of schedules, so if the user has locally set\n            # \"schedules\" to anything, we should avoid sending \"schedule\"\n            # and let the API server generate a new value if necessary.\n            if \"schedules\" in self.__fields_set__:\n                self.schedule = None\n                self.is_schedule_active = None\n            else:\n                # The user isn't using \"schedules,\" so we should\n                # populate \"schedule\" and \"is_schedule_active\" from the\n                # API's version of the deployment, unless the user gave\n                # us these fields in __init__().\n                if \"schedule\" not in self.__fields_set__:\n                    self.schedule = deployment.schedule\n                if \"is_schedule_active\" not in self.__fields_set__:\n                    self.is_schedule_active = deployment.is_schedule_active\n\n            if \"infrastructure\" not in self.__fields_set__:\n                if deployment.infrastructure_document_id:\n                    self.infrastructure = Block._from_block_document(\n                        await client.read_block_document(\n                            deployment.infrastructure_document_id\n                        )\n                    )\n            if \"storage\" not in self.__fields_set__:\n                if deployment.storage_document_id:\n                    self.storage = Block._from_block_document(\n                        await client.read_block_document(\n                            deployment.storage_document_id\n                        )\n                    )\n        except ObjectNotFound:\n            return False\n    return True\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.update","title":"<code>update</code>  <code>async</code>","text":"<p>Performs an in-place update with the provided settings.</p> <p>Parameters:</p> Name Type Description Default <code>ignore_none</code> <code>bool</code> <p>if True, all <code>None</code> values are ignored when performing the update</p> <code>False</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def update(self, ignore_none: bool = False, **kwargs):\n    \"\"\"\n    Performs an in-place update with the provided settings.\n\n    Args:\n        ignore_none: if True, all `None` values are ignored when performing the\n            update\n    \"\"\"\n    unknown_keys = set(kwargs.keys()) - set(self.dict().keys())\n    if unknown_keys:\n        raise ValueError(\n            f\"Received unexpected attributes: {', '.join(unknown_keys)}\"\n        )\n    for key, value in kwargs.items():\n        if ignore_none and value is None:\n            continue\n        setattr(self, key, value)\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.Deployment.upload_to_storage","title":"<code>upload_to_storage</code>  <code>async</code>","text":"<p>Uploads the workflow this deployment represents using a provided storage block; if no block is provided, defaults to configuring self for local storage.</p> <p>Parameters:</p> Name Type Description Default <code>storage_block</code> <code>str</code> <p>a string reference a remote storage block slug <code>$type/$name</code>; if provided, used to upload the workflow's project</p> <code>None</code> <code>ignore_file</code> <code>str</code> <p>an optional path to a <code>.prefectignore</code> file that specifies filename patterns to ignore when uploading to remote storage; if not provided, looks for <code>.prefectignore</code> in the current working directory</p> <code>'.prefectignore'</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\nasync def upload_to_storage(\n    self, storage_block: str = None, ignore_file: str = \".prefectignore\"\n) -&gt; Optional[int]:\n    \"\"\"\n    Uploads the workflow this deployment represents using a provided storage block;\n    if no block is provided, defaults to configuring self for local storage.\n\n    Args:\n        storage_block: a string reference a remote storage block slug `$type/$name`;\n            if provided, used to upload the workflow's project\n        ignore_file: an optional path to a `.prefectignore` file that specifies\n            filename patterns to ignore when uploading to remote storage; if not\n            provided, looks for `.prefectignore` in the current working directory\n    \"\"\"\n    file_count = None\n    if storage_block:\n        storage = await Block.load(storage_block)\n\n        if \"put-directory\" not in storage.get_block_capabilities():\n            raise BlockMissingCapabilities(\n                f\"Storage block {storage!r} missing 'put-directory' capability.\"\n            )\n\n        self.storage = storage\n\n        # upload current directory to storage location\n        file_count = await self.storage.put_directory(\n            ignore_file=ignore_file, to_path=self.path\n        )\n    elif self.storage:\n        if \"put-directory\" not in self.storage.get_block_capabilities():\n            raise BlockMissingCapabilities(\n                f\"Storage block {self.storage!r} missing 'put-directory'\"\n                \" capability.\"\n            )\n\n        file_count = await self.storage.put_directory(\n            ignore_file=ignore_file, to_path=self.path\n        )\n\n    # persists storage now in case it contains secret values\n    if self.storage and not self.storage._block_document_id:\n        await self.storage._save(is_anonymous=True)\n\n    return file_count\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.load_deployments_from_yaml","title":"<code>load_deployments_from_yaml</code>","text":"<p>Load deployments from a yaml file.</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_callable(start_date=\"Mar 2024\")\ndef load_deployments_from_yaml(\n    path: str,\n) -&gt; PrefectObjectRegistry:\n    \"\"\"\n    Load deployments from a yaml file.\n    \"\"\"\n    with open(path, \"r\") as f:\n        contents = f.read()\n\n    # Parse into a yaml tree to retrieve separate documents\n    nodes = yaml.compose_all(contents)\n\n    with PrefectObjectRegistry(capture_failures=True) as registry:\n        for node in nodes:\n            with tmpchdir(path):\n                deployment_dict = yaml.safe_load(yaml.serialize(node))\n                # The return value is not necessary, just instantiating the Deployment\n                # is enough to get it recorded on the registry\n                parse_obj_as(Deployment, deployment_dict)\n\n    return registry\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.load_flow_from_flow_run","title":"<code>load_flow_from_flow_run</code>  <code>async</code>","text":"<p>Load a flow from the location/script provided in a deployment's storage document.</p> <p>If <code>ignore_storage=True</code> is provided, no pull from remote storage occurs.  This flag is largely for testing, and assumes the flow is already available locally.</p> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@deprecated_callable(\n    start_date=\"Jun 2024\",\n    help=\"Will be moved in Prefect 3 to prefect.flows:load_flow_from_flow_run\",\n)\n@inject_client\nasync def load_flow_from_flow_run(\n    flow_run: FlowRun,\n    client: PrefectClient,\n    ignore_storage: bool = False,\n    storage_base_path: Optional[str] = None,\n    use_placeholder_flow: bool = True,\n) -&gt; Flow:\n    \"\"\"\n    Load a flow from the location/script provided in a deployment's storage document.\n\n    If `ignore_storage=True` is provided, no pull from remote storage occurs.  This flag\n    is largely for testing, and assumes the flow is already available locally.\n    \"\"\"\n    deployment = await client.read_deployment(flow_run.deployment_id)\n\n    if deployment.entrypoint is None:\n        raise ValueError(\n            f\"Deployment {deployment.id} does not have an entrypoint and can not be run.\"\n        )\n\n    run_logger = flow_run_logger(flow_run)\n\n    runner_storage_base_path = storage_base_path or os.environ.get(\n        \"PREFECT__STORAGE_BASE_PATH\"\n    )\n\n    # If there's no colon, assume it's a module path\n    if \":\" not in deployment.entrypoint:\n        run_logger.debug(\n            f\"Importing flow code from module path {deployment.entrypoint}\"\n        )\n        flow = await run_sync_in_worker_thread(\n            load_flow_from_entrypoint, deployment.entrypoint, use_placeholder_flow\n        )\n        return flow\n\n    if not ignore_storage and not deployment.pull_steps:\n        sys.path.insert(0, \".\")\n        if deployment.storage_document_id:\n            storage_document = await client.read_block_document(\n                deployment.storage_document_id\n            )\n            storage_block = Block._from_block_document(storage_document)\n        else:\n            basepath = deployment.path or Path(deployment.manifest_path).parent\n            if runner_storage_base_path:\n                basepath = str(basepath).replace(\n                    \"$STORAGE_BASE_PATH\", runner_storage_base_path\n                )\n            storage_block = LocalFileSystem(basepath=basepath)\n\n        from_path = (\n            str(deployment.path).replace(\"$STORAGE_BASE_PATH\", runner_storage_base_path)\n            if runner_storage_base_path and deployment.path\n            else deployment.path\n        )\n        run_logger.info(f\"Downloading flow code from storage at {from_path!r}\")\n        await storage_block.get_directory(from_path=from_path, local_path=\".\")\n\n    if deployment.pull_steps:\n        run_logger.debug(f\"Running {len(deployment.pull_steps)} deployment pull steps\")\n        output = await run_steps(deployment.pull_steps)\n        if output.get(\"directory\"):\n            run_logger.debug(f\"Changing working directory to {output['directory']!r}\")\n            os.chdir(output[\"directory\"])\n\n    import_path = relative_path_to_current_platform(deployment.entrypoint)\n    # for backwards compat\n    if deployment.manifest_path:\n        with open(deployment.manifest_path, \"r\") as f:\n            import_path = json.load(f)[\"import_path\"]\n            import_path = (\n                Path(deployment.manifest_path).parent / import_path\n            ).absolute()\n    run_logger.debug(f\"Importing flow code from '{import_path}'\")\n\n    flow = await run_sync_in_worker_thread(\n        load_flow_from_entrypoint, str(import_path), use_placeholder_flow\n    )\n\n    return flow\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/deployments/#prefect.deployments.deployments.run_deployment","title":"<code>run_deployment</code>  <code>async</code>","text":"<p>Create a flow run for a deployment and return it after completion or a timeout.</p> <p>By default, this function blocks until the flow run finishes executing. Specify a timeout (in seconds) to wait for the flow run to execute before returning flow run metadata. To return immediately, without waiting for the flow run to execute, set <code>timeout=0</code>.</p> <p>Note that if you specify a timeout, this function will return the flow run metadata whether or not the flow run finished executing.</p> <p>If called within a flow or task, the flow run this function creates will be linked to the current flow run as a subflow. Disable this behavior by passing <code>as_subflow=False</code>.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>Union[str, UUID]</code> <p>The deployment id or deployment name in the form: <code>\"flow name/deployment name\"</code></p> required <code>parameters</code> <code>Optional[dict]</code> <p>Parameter overrides for this flow run. Merged with the deployment defaults.</p> <code>None</code> <code>scheduled_time</code> <code>Optional[datetime]</code> <p>The time to schedule the flow run for, defaults to scheduling the flow run to start now.</p> <code>None</code> <code>flow_run_name</code> <code>Optional[str]</code> <p>A name for the created flow run</p> <code>None</code> <code>timeout</code> <code>Optional[float]</code> <p>The amount of time to wait (in seconds) for the flow run to complete before returning. Setting <code>timeout</code> to 0 will return the flow run metadata immediately. Setting <code>timeout</code> to None will allow this function to poll indefinitely. Defaults to None.</p> <code>None</code> <code>poll_interval</code> <code>Optional[float]</code> <p>The number of seconds between polls</p> <code>5</code> <code>tags</code> <code>Optional[Iterable[str]]</code> <p>A list of tags to associate with this flow run; tags can be used in automations and for organizational purposes.</p> <code>None</code> <code>idempotency_key</code> <code>Optional[str]</code> <p>A unique value to recognize retries of the same run, and prevent creating multiple flow runs.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of a work queue to use for this run. Defaults to the default work queue for the deployment.</p> <code>None</code> <code>as_subflow</code> <code>Optional[bool]</code> <p>Whether to link the flow run as a subflow of the current flow or task run.</p> <code>True</code> <code>job_variables</code> <code>Optional[dict]</code> <p>A dictionary of dot delimited infrastructure overrides that will be applied at runtime; for example <code>env.CONFIG_KEY=config_value</code> or <code>namespace='prefect'</code></p> <code>None</code> Source code in <code>prefect/deployments/deployments.py</code> <pre><code>@sync_compatible\n@deprecated_parameter(\n    \"infra_overrides\",\n    start_date=\"Apr 2024\",\n    help=\"Use `job_variables` instead.\",\n)\n@inject_client\nasync def run_deployment(\n    name: Union[str, UUID],\n    client: Optional[PrefectClient] = None,\n    parameters: Optional[dict] = None,\n    scheduled_time: Optional[datetime] = None,\n    flow_run_name: Optional[str] = None,\n    timeout: Optional[float] = None,\n    poll_interval: Optional[float] = 5,\n    tags: Optional[Iterable[str]] = None,\n    idempotency_key: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    as_subflow: Optional[bool] = True,\n    infra_overrides: Optional[dict] = None,\n    job_variables: Optional[dict] = None,\n) -&gt; FlowRun:\n    \"\"\"\n    Create a flow run for a deployment and return it after completion or a timeout.\n\n    By default, this function blocks until the flow run finishes executing.\n    Specify a timeout (in seconds) to wait for the flow run to execute before\n    returning flow run metadata. To return immediately, without waiting for the\n    flow run to execute, set `timeout=0`.\n\n    Note that if you specify a timeout, this function will return the flow run\n    metadata whether or not the flow run finished executing.\n\n    If called within a flow or task, the flow run this function creates will\n    be linked to the current flow run as a subflow. Disable this behavior by\n    passing `as_subflow=False`.\n\n    Args:\n        name: The deployment id or deployment name in the form:\n            `\"flow name/deployment name\"`\n        parameters: Parameter overrides for this flow run. Merged with the deployment\n            defaults.\n        scheduled_time: The time to schedule the flow run for, defaults to scheduling\n            the flow run to start now.\n        flow_run_name: A name for the created flow run\n        timeout: The amount of time to wait (in seconds) for the flow run to\n            complete before returning. Setting `timeout` to 0 will return the flow\n            run metadata immediately. Setting `timeout` to None will allow this\n            function to poll indefinitely. Defaults to None.\n        poll_interval: The number of seconds between polls\n        tags: A list of tags to associate with this flow run; tags can be used in\n            automations and for organizational purposes.\n        idempotency_key: A unique value to recognize retries of the same run, and\n            prevent creating multiple flow runs.\n        work_queue_name: The name of a work queue to use for this run. Defaults to\n            the default work queue for the deployment.\n        as_subflow: Whether to link the flow run as a subflow of the current\n            flow or task run.\n        job_variables: A dictionary of dot delimited infrastructure overrides that\n            will be applied at runtime; for example `env.CONFIG_KEY=config_value` or\n            `namespace='prefect'`\n    \"\"\"\n    if timeout is not None and timeout &lt; 0:\n        raise ValueError(\"`timeout` cannot be negative\")\n\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n\n    jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)\n\n    parameters = parameters or {}\n\n    deployment_id = None\n\n    if isinstance(name, UUID):\n        deployment_id = name\n    else:\n        try:\n            deployment_id = UUID(name)\n        except ValueError:\n            pass\n\n    if deployment_id:\n        deployment = await client.read_deployment(deployment_id=deployment_id)\n    else:\n        deployment = await client.read_deployment_by_name(name)\n\n    flow_run_ctx = FlowRunContext.get()\n    task_run_ctx = TaskRunContext.get()\n    if as_subflow and (flow_run_ctx or task_run_ctx):\n        # This was called from a flow. Link the flow run as a subflow.\n        from prefect.engine import (\n            Pending,\n            _dynamic_key_for_task_run,\n            collect_task_run_inputs,\n        )\n\n        task_inputs = {\n            k: await collect_task_run_inputs(v) for k, v in parameters.items()\n        }\n\n        if deployment_id:\n            flow = await client.read_flow(deployment.flow_id)\n            deployment_name = f\"{flow.name}/{deployment.name}\"\n        else:\n            deployment_name = name\n\n        # Generate a task in the parent flow run to represent the result of the subflow\n        dummy_task = Task(\n            name=deployment_name,\n            fn=lambda: None,\n            version=deployment.version,\n        )\n        # Override the default task key to include the deployment name\n        dummy_task.task_key = f\"{__name__}.run_deployment.{slugify(deployment_name)}\"\n        flow_run_id = (\n            flow_run_ctx.flow_run.id\n            if flow_run_ctx\n            else task_run_ctx.task_run.flow_run_id\n        )\n        dynamic_key = (\n            _dynamic_key_for_task_run(flow_run_ctx, dummy_task)\n            if flow_run_ctx\n            else task_run_ctx.task_run.dynamic_key\n        )\n        parent_task_run = await client.create_task_run(\n            task=dummy_task,\n            flow_run_id=flow_run_id,\n            dynamic_key=dynamic_key,\n            task_inputs=task_inputs,\n            state=Pending(),\n        )\n        parent_task_run_id = parent_task_run.id\n    else:\n        parent_task_run_id = None\n\n    flow_run = await client.create_flow_run_from_deployment(\n        deployment.id,\n        parameters=parameters,\n        state=Scheduled(scheduled_time=scheduled_time),\n        name=flow_run_name,\n        tags=tags,\n        idempotency_key=idempotency_key,\n        parent_task_run_id=parent_task_run_id,\n        work_queue_name=work_queue_name,\n        job_variables=jv,\n    )\n\n    flow_run_id = flow_run.id\n\n    if timeout == 0:\n        return flow_run\n\n    with anyio.move_on_after(timeout):\n        while True:\n            flow_run = await client.read_flow_run(flow_run_id)\n            flow_state = flow_run.state\n            if flow_state and flow_state.is_final():\n                return flow_run\n            await anyio.sleep(poll_interval)\n\n    return flow_run\n</code></pre>","tags":["Python API","flow runs","deployments"]},{"location":"api-ref/prefect/deployments/runner/","title":"runner","text":"","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner","title":"<code>prefect.deployments.runner</code>","text":"<p>Objects for creating and configuring deployments for flows using <code>serve</code> functionality.</p> Example <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    # to_deployment creates RunnerDeployment instances\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n\n    serve(slow_deploy, fast_deploy)\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.DeploymentApplyError","title":"<code>DeploymentApplyError</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Raised when an error occurs while applying a deployment.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class DeploymentApplyError(RuntimeError):\n    \"\"\"\n    Raised when an error occurs while applying a deployment.\n    \"\"\"\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.DeploymentImage","title":"<code>DeploymentImage</code>","text":"<p>Configuration used to build and push a Docker image for a deployment.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name of the Docker image to build, including the registry and repository.</p> <code>tag</code> <p>The tag to apply to the built image.</p> <code>dockerfile</code> <p>The path to the Dockerfile to use for building the image. If not provided, a default Dockerfile will be generated.</p> <code>**build_kwargs</code> <p>Additional keyword arguments to pass to the Docker build request. See the <code>docker-py</code> documentation for more information.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class DeploymentImage:\n    \"\"\"\n    Configuration used to build and push a Docker image for a deployment.\n\n    Attributes:\n        name: The name of the Docker image to build, including the registry and\n            repository.\n        tag: The tag to apply to the built image.\n        dockerfile: The path to the Dockerfile to use for building the image. If\n            not provided, a default Dockerfile will be generated.\n        **build_kwargs: Additional keyword arguments to pass to the Docker build request.\n            See the [`docker-py` documentation](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build)\n            for more information.\n\n    \"\"\"\n\n    def __init__(self, name, tag=None, dockerfile=\"auto\", **build_kwargs):\n        image_name, image_tag = parse_image_tag(name)\n        if tag and image_tag:\n            raise ValueError(\n                f\"Only one tag can be provided - both {image_tag!r} and {tag!r} were\"\n                \" provided as tags.\"\n            )\n        namespace, repository = split_repository_path(image_name)\n        # if the provided image name does not include a namespace (registry URL or user/org name),\n        # use the default namespace\n        if not namespace:\n            namespace = PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE.value()\n        # join the namespace and repository to create the full image name\n        # ignore namespace if it is None\n        self.name = \"/\".join(filter(None, [namespace, repository]))\n        self.tag = tag or image_tag or slugify(pendulum.now(\"utc\").isoformat())\n        self.dockerfile = dockerfile\n        self.build_kwargs = build_kwargs\n\n    @property\n    def reference(self):\n        return f\"{self.name}:{self.tag}\"\n\n    def build(self):\n        full_image_name = self.reference\n        build_kwargs = self.build_kwargs.copy()\n        build_kwargs[\"context\"] = Path.cwd()\n        build_kwargs[\"tag\"] = full_image_name\n        build_kwargs[\"pull\"] = build_kwargs.get(\"pull\", True)\n\n        if self.dockerfile == \"auto\":\n            with generate_default_dockerfile():\n                build_image(**build_kwargs)\n        else:\n            build_kwargs[\"dockerfile\"] = self.dockerfile\n            build_image(**build_kwargs)\n\n    def push(self):\n        with docker_client() as client:\n            events = client.api.push(\n                repository=self.name, tag=self.tag, stream=True, decode=True\n            )\n            for event in events:\n                if \"error\" in event:\n                    raise PushError(event[\"error\"])\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.EntrypointType","title":"<code>EntrypointType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing a entrypoint type.</p> <p>File path entrypoints are in the format: <code>path/to/file.py:function_name</code>. Module path entrypoints are in the format: <code>path.to.module.function_name</code>.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class EntrypointType(enum.Enum):\n    \"\"\"\n    Enum representing a entrypoint type.\n\n    File path entrypoints are in the format: `path/to/file.py:function_name`.\n    Module path entrypoints are in the format: `path.to.module.function_name`.\n    \"\"\"\n\n    FILE_PATH = \"file_path\"\n    MODULE_PATH = \"module_path\"\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment","title":"<code>RunnerDeployment</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A Prefect RunnerDeployment definition, used for specifying and building deployments.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>A name for the deployment (required).</p> <code>version</code> <code>Optional[str]</code> <p>An optional version for the deployment; defaults to the flow's version</p> <code>description</code> <code>Optional[str]</code> <p>An optional description of the deployment; defaults to the flow's description</p> <code>tags</code> <code>List[str]</code> <p>An optional list of tags to associate with this deployment; note that tags are used only for organizational purposes. For delegating work to agents, see <code>work_queue_name</code>.</p> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule to run this deployment on, once registered</p> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not the schedule is active</p> <code>parameters</code> <code>Dict[str, Any]</code> <p>A dictionary of parameter values to pass to runs created from this deployment</p> <code>path</code> <code>Dict[str, Any]</code> <p>The path to the working directory for the workflow, relative to remote storage or, if stored on a local filesystem, an absolute path</p> <code>entrypoint</code> <code>Optional[str]</code> <p>The path to the entrypoint for the workflow, always relative to the <code>path</code></p> <code>parameter_openapi_schema</code> <code>Optional[str]</code> <p>The parameter schema of the flow, including defaults.</p> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>job_variables</code> <code>Dict[str, Any]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>class RunnerDeployment(BaseModel):\n    \"\"\"\n    A Prefect RunnerDeployment definition, used for specifying and building deployments.\n\n    Attributes:\n        name: A name for the deployment (required).\n        version: An optional version for the deployment; defaults to the flow's version\n        description: An optional description of the deployment; defaults to the flow's\n            description\n        tags: An optional list of tags to associate with this deployment; note that tags\n            are used only for organizational purposes. For delegating work to agents,\n            see `work_queue_name`.\n        schedule: A schedule to run this deployment on, once registered\n        is_schedule_active: Whether or not the schedule is active\n        parameters: A dictionary of parameter values to pass to runs created from this\n            deployment\n        path: The path to the working directory for the workflow, relative to remote\n            storage or, if stored on a local filesystem, an absolute path\n        entrypoint: The path to the entrypoint for the workflow, always relative to the\n            `path`\n        parameter_openapi_schema: The parameter schema of the flow, including defaults.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n\n    class Config:\n        arbitrary_types_allowed = True\n\n    name: str = Field(..., description=\"The name of the deployment.\")\n    flow_name: Optional[str] = Field(\n        None, description=\"The name of the underlying flow; typically inferred.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"An optional description of the deployment.\"\n    )\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"One of more tags to apply to this deployment.\",\n    )\n    schedules: Optional[List[MinimalDeploymentSchedule]] = Field(\n        default=None,\n        description=\"The schedules that should cause this deployment to run.\",\n    )\n    schedule: Optional[SCHEDULE_TYPES] = None\n    paused: Optional[bool] = Field(\n        default=None, description=\"Whether or not the deployment is paused.\"\n    )\n    is_schedule_active: Optional[bool] = Field(\n        default=None, description=\"DEPRECATED: Whether or not the schedule is active.\"\n    )\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    triggers: List[Union[DeploymentTriggerTypes, TriggerTypes]] = Field(\n        default_factory=list,\n        description=\"The triggers that should cause this deployment to run.\",\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the Prefect API should enforce the parameter schema for\"\n            \" this deployment.\"\n        ),\n    )\n    storage: Optional[RunnerStorage] = Field(\n        default=None,\n        description=(\n            \"The storage object used to retrieve flow code for this deployment.\"\n        ),\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The name of the work pool to use for this deployment. Only used when\"\n            \" the deployment is registered with a built runner.\"\n        ),\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The name of the work queue to use for this deployment. Only used when\"\n            \" the deployment is registered with a built runner.\"\n        ),\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=(\n            \"Job variables used to override the default values of a work pool\"\n            \" base job template. Only used when the deployment is registered with\"\n            \" a built runner.\"\n        ),\n    )\n    _entrypoint_type: EntrypointType = PrivateAttr(\n        default=EntrypointType.FILE_PATH,\n    )\n    _path: Optional[str] = PrivateAttr(\n        default=None,\n    )\n    _parameter_openapi_schema: ParameterSchema = PrivateAttr(\n        default_factory=ParameterSchema,\n    )\n\n    @property\n    def entrypoint_type(self) -&gt; EntrypointType:\n        return self._entrypoint_type\n\n    @validator(\"triggers\", allow_reuse=True)\n    def validate_automation_names(cls, field_value, values):\n        \"\"\"Ensure that each trigger has a name for its automation if none is provided.\"\"\"\n        return validate_automation_names(field_value, values)\n\n    @root_validator(pre=True)\n    def reconcile_paused(cls, values):\n        return reconcile_paused_deployment(values)\n\n    @root_validator(pre=True)\n    def reconcile_schedules(cls, values):\n        return reconcile_schedules_runner(values)\n\n    @sync_compatible\n    async def apply(\n        self, work_pool_name: Optional[str] = None, image: Optional[str] = None\n    ) -&gt; UUID:\n        \"\"\"\n        Registers this deployment with the API and returns the deployment's ID.\n\n        Args:\n            work_pool_name: The name of the work pool to use for this\n                deployment.\n            image: The registry, name, and tag of the Docker image to\n                use for this deployment. Only used when the deployment is\n                deployed to a work pool.\n\n        Returns:\n            The ID of the created deployment.\n        \"\"\"\n\n        work_pool_name = work_pool_name or self.work_pool_name\n\n        if image and not work_pool_name:\n            raise ValueError(\n                \"An image can only be provided when registering a deployment with a\"\n                \" work pool.\"\n            )\n\n        if self.work_queue_name and not work_pool_name:\n            raise ValueError(\n                \"A work queue can only be provided when registering a deployment with\"\n                \" a work pool.\"\n            )\n\n        if self.job_variables and not work_pool_name:\n            raise ValueError(\n                \"Job variables can only be provided when registering a deployment\"\n                \" with a work pool.\"\n            )\n\n        async with get_client() as client:\n            flow_id = await client.create_flow_from_name(self.flow_name)\n\n            create_payload = dict(\n                flow_id=flow_id,\n                name=self.name,\n                work_queue_name=self.work_queue_name,\n                work_pool_name=work_pool_name,\n                version=self.version,\n                paused=self.paused,\n                schedules=self.schedules,\n                parameters=self.parameters,\n                description=self.description,\n                tags=self.tags,\n                path=self._path,\n                entrypoint=self.entrypoint,\n                storage_document_id=None,\n                infrastructure_document_id=None,\n                parameter_openapi_schema=self._parameter_openapi_schema.dict(),\n                enforce_parameter_schema=self.enforce_parameter_schema,\n            )\n\n            if work_pool_name:\n                create_payload[\"job_variables\"] = self.job_variables\n                if image:\n                    create_payload[\"job_variables\"][\"image\"] = image\n                create_payload[\"path\"] = None if self.storage else self._path\n                create_payload[\"pull_steps\"] = (\n                    [self.storage.to_pull_step()] if self.storage else []\n                )\n\n            try:\n                deployment_id = await client.create_deployment(**create_payload)\n            except Exception as exc:\n                if isinstance(exc, PrefectHTTPStatusError):\n                    detail = exc.response.json().get(\"detail\")\n                    if detail:\n                        raise DeploymentApplyError(detail) from exc\n                raise DeploymentApplyError(\n                    f\"Error while applying deployment: {str(exc)}\"\n                ) from exc\n\n            if client.server_type.supports_automations():\n                try:\n                    # The triggers defined in the deployment spec are, essentially,\n                    # anonymous and attempting truly sync them with cloud is not\n                    # feasible. Instead, we remove all automations that are owned\n                    # by the deployment, meaning that they were created via this\n                    # mechanism below, and then recreate them.\n                    await client.delete_resource_owned_automations(\n                        f\"prefect.deployment.{deployment_id}\"\n                    )\n                except PrefectHTTPStatusError as e:\n                    if e.response.status_code == 404:\n                        # This Prefect server does not support automations, so we can safely\n                        # ignore this 404 and move on.\n                        return deployment_id\n                    raise e\n\n                for trigger in self.triggers:\n                    trigger.set_deployment_id(deployment_id)\n                    await client.create_automation(trigger.as_automation())\n\n            return deployment_id\n\n    @staticmethod\n    def _construct_deployment_schedules(\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        anchor_date: Optional[Union[datetime, str]] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        timezone: Optional[str] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n    ) -&gt; Union[List[MinimalDeploymentSchedule], FlexibleScheduleList]:\n        \"\"\"\n        Construct a schedule or schedules from the provided arguments.\n\n        This method serves as a unified interface for creating deployment\n        schedules. If `schedules` is provided, it is directly returned. If\n        `schedule` is provided, it is encapsulated in a list and returned. If\n        `interval`, `cron`, or `rrule` are provided, they are used to construct\n        schedule objects.\n\n        Args:\n            interval: An interval on which to schedule runs, either as a single\n              value or as a list of values. Accepts numbers (interpreted as\n              seconds) or `timedelta` objects. Each value defines a separate\n              scheduling interval.\n            anchor_date: The anchor date from which interval schedules should\n              start. This applies to all intervals if a list is provided.\n            cron: A cron expression or a list of cron expressions defining cron\n              schedules. Each expression defines a separate cron schedule.\n            rrule: An rrule string or a list of rrule strings for scheduling.\n              Each string defines a separate recurrence rule.\n            timezone: The timezone to apply to the cron or rrule schedules.\n              This is a single value applied uniformly to all schedules.\n            schedule: A singular schedule object, used for advanced scheduling\n              options like specifying a timezone. This is returned as a list\n              containing this single schedule.\n            schedules: A pre-defined list of schedule objects. If provided,\n              this list is returned as-is, bypassing other schedule construction\n              logic.\n        \"\"\"\n\n        num_schedules = sum(\n            1\n            for entry in (interval, cron, rrule, schedule, schedules)\n            if entry is not None\n        )\n        if num_schedules &gt; 1:\n            raise ValueError(\n                \"Only one of interval, cron, rrule, schedule, or schedules can be provided.\"\n            )\n        elif num_schedules == 0:\n            return []\n\n        if schedules is not None:\n            return schedules\n        elif interval or cron or rrule:\n            # `interval`, `cron`, and `rrule` can be lists of values. This\n            # block figures out which one is not None and uses that to\n            # construct the list of schedules via `construct_schedule`.\n            parameters = [(\"interval\", interval), (\"cron\", cron), (\"rrule\", rrule)]\n            schedule_type, value = [\n                param for param in parameters if param[1] is not None\n            ][0]\n\n            if not isiterable(value):\n                value = [value]\n\n            return [\n                create_minimal_deployment_schedule(\n                    construct_schedule(\n                        **{\n                            schedule_type: v,\n                            \"timezone\": timezone,\n                            \"anchor_date\": anchor_date,\n                        }\n                    )\n                )\n                for v in value\n            ]\n        else:\n            return [create_minimal_deployment_schedule(schedule)]\n\n    def _set_defaults_from_flow(self, flow: \"Flow\"):\n        self._parameter_openapi_schema = parameter_schema(flow)\n\n        if not self.version:\n            self.version = flow.version\n        if not self.description:\n            self.description = flow.description\n\n    @classmethod\n    def from_flow(\n        cls,\n        flow: \"Flow\",\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Configure a deployment for a given flow.\n\n        Args:\n            flow: A flow function to deploy\n            name: A name for the deployment\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        job_variables = job_variables or {}\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            is_schedule_active=is_schedule_active,\n            paused=paused,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n\n        if not deployment.entrypoint:\n            no_file_location_error = (\n                \"Flows defined interactively cannot be deployed. Check out the\"\n                \" quickstart guide for help getting started:\"\n                \" https://docs.prefect.io/latest/getting-started/quickstart\"\n            )\n            ## first see if an entrypoint can be determined\n            flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n            mod_name = getattr(flow, \"__module__\", None)\n            if entrypoint_type == EntrypointType.MODULE_PATH:\n                if mod_name:\n                    deployment.entrypoint = f\"{mod_name}.{flow.__name__}\"\n                else:\n                    raise ValueError(\n                        \"Unable to determine module path for provided flow.\"\n                    )\n            else:\n                if not flow_file:\n                    if not mod_name:\n                        raise ValueError(no_file_location_error)\n                    try:\n                        module = importlib.import_module(mod_name)\n                        flow_file = getattr(module, \"__file__\", None)\n                    except ModuleNotFoundError as exc:\n                        if \"__prefect_loader__\" in str(exc):\n                            raise ValueError(\n                                \"Cannot create a RunnerDeployment from a flow that has been\"\n                                \" loaded from an entrypoint. To deploy a flow via\"\n                                \" entrypoint, use RunnerDeployment.from_entrypoint instead.\"\n                            )\n                        raise ValueError(no_file_location_error)\n                    if not flow_file:\n                        raise ValueError(no_file_location_error)\n\n                # set entrypoint\n                entry_path = (\n                    Path(flow_file).absolute().relative_to(Path.cwd().absolute())\n                )\n                deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n        if entrypoint_type == EntrypointType.FILE_PATH and not deployment._path:\n            deployment._path = \".\"\n\n        deployment._entrypoint_type = entrypoint_type\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n\n    @classmethod\n    def from_entrypoint(\n        cls,\n        entrypoint: str,\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ) -&gt; \"RunnerDeployment\":\n        \"\"\"\n        Configure a deployment for a given flow located at a given entrypoint.\n\n        Args:\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n            name: A name for the deployment\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            paused: Whether or not to set this deployment as paused.\n            schedules: A list of schedule objects defining when to execute runs of this deployment.\n                Used to define multiple schedules or additional scheduling options like `timezone`.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        from prefect.flows import load_flow_from_entrypoint\n\n        job_variables = job_variables or {}\n        flow = load_flow_from_entrypoint(entrypoint)\n\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            entrypoint=entrypoint,\n            enforce_parameter_schema=enforce_parameter_schema,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n        deployment._path = str(Path.cwd())\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n\n    @classmethod\n    @sync_compatible\n    async def from_storage(\n        cls,\n        storage: RunnerStorage,\n        entrypoint: str,\n        name: str,\n        interval: Optional[\n            Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        work_pool_name: Optional[str] = None,\n        work_queue_name: Optional[str] = None,\n        job_variables: Optional[Dict[str, Any]] = None,\n    ):\n        \"\"\"\n        Create a RunnerDeployment from a flow located at a given entrypoint and stored in a\n        local storage location.\n\n        Args:\n            entrypoint:  The path to a file containing a flow and the name of the flow function in\n                the format `./path/to/file.py:flow_func_name`.\n            name: A name for the deployment\n            storage: A storage object to use for retrieving flow code. If not provided, a\n                URL must be provided.\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            enforce_parameter_schema: Whether or not the Prefect API should enforce the\n                parameter schema for this deployment.\n            work_pool_name: The name of the work pool to use for this deployment.\n            work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n                If not provided the default work queue for the work pool will be used.\n            job_variables: Settings used to override the values specified default base job template\n                of the chosen work pool. Refer to the base job template of the chosen work pool for\n                available settings.\n        \"\"\"\n        from prefect.flows import load_flow_from_entrypoint\n\n        constructed_schedules = cls._construct_deployment_schedules(\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedule=schedule,\n            schedules=schedules,\n        )\n\n        job_variables = job_variables or {}\n\n        with tempfile.TemporaryDirectory() as tmpdir:\n            storage.set_base_path(Path(tmpdir))\n            await storage.pull_code()\n\n            full_entrypoint = str(storage.destination / entrypoint)\n            flow = await from_async.wait_for_call_in_new_thread(\n                create_call(load_flow_from_entrypoint, full_entrypoint)\n            )\n\n        deployment = cls(\n            name=Path(name).stem,\n            flow_name=flow.name,\n            schedule=schedule,\n            schedules=constructed_schedules,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            tags=tags or [],\n            triggers=triggers or [],\n            parameters=parameters or {},\n            description=description,\n            version=version,\n            entrypoint=entrypoint,\n            enforce_parameter_schema=enforce_parameter_schema,\n            storage=storage,\n            work_pool_name=work_pool_name,\n            work_queue_name=work_queue_name,\n            job_variables=job_variables,\n        )\n        deployment._path = str(storage.destination).replace(\n            tmpdir, \"$STORAGE_BASE_PATH\"\n        )\n\n        cls._set_defaults_from_flow(deployment, flow)\n\n        return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.apply","title":"<code>apply</code>  <code>async</code>","text":"<p>Registers this deployment with the API and returns the deployment's ID.</p> <p>Parameters:</p> Name Type Description Default <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>image</code> <code>Optional[str]</code> <p>The registry, name, and tag of the Docker image to use for this deployment. Only used when the deployment is deployed to a work pool.</p> <code>None</code> <p>Returns:</p> Type Description <code>UUID</code> <p>The ID of the created deployment.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@sync_compatible\nasync def apply(\n    self, work_pool_name: Optional[str] = None, image: Optional[str] = None\n) -&gt; UUID:\n    \"\"\"\n    Registers this deployment with the API and returns the deployment's ID.\n\n    Args:\n        work_pool_name: The name of the work pool to use for this\n            deployment.\n        image: The registry, name, and tag of the Docker image to\n            use for this deployment. Only used when the deployment is\n            deployed to a work pool.\n\n    Returns:\n        The ID of the created deployment.\n    \"\"\"\n\n    work_pool_name = work_pool_name or self.work_pool_name\n\n    if image and not work_pool_name:\n        raise ValueError(\n            \"An image can only be provided when registering a deployment with a\"\n            \" work pool.\"\n        )\n\n    if self.work_queue_name and not work_pool_name:\n        raise ValueError(\n            \"A work queue can only be provided when registering a deployment with\"\n            \" a work pool.\"\n        )\n\n    if self.job_variables and not work_pool_name:\n        raise ValueError(\n            \"Job variables can only be provided when registering a deployment\"\n            \" with a work pool.\"\n        )\n\n    async with get_client() as client:\n        flow_id = await client.create_flow_from_name(self.flow_name)\n\n        create_payload = dict(\n            flow_id=flow_id,\n            name=self.name,\n            work_queue_name=self.work_queue_name,\n            work_pool_name=work_pool_name,\n            version=self.version,\n            paused=self.paused,\n            schedules=self.schedules,\n            parameters=self.parameters,\n            description=self.description,\n            tags=self.tags,\n            path=self._path,\n            entrypoint=self.entrypoint,\n            storage_document_id=None,\n            infrastructure_document_id=None,\n            parameter_openapi_schema=self._parameter_openapi_schema.dict(),\n            enforce_parameter_schema=self.enforce_parameter_schema,\n        )\n\n        if work_pool_name:\n            create_payload[\"job_variables\"] = self.job_variables\n            if image:\n                create_payload[\"job_variables\"][\"image\"] = image\n            create_payload[\"path\"] = None if self.storage else self._path\n            create_payload[\"pull_steps\"] = (\n                [self.storage.to_pull_step()] if self.storage else []\n            )\n\n        try:\n            deployment_id = await client.create_deployment(**create_payload)\n        except Exception as exc:\n            if isinstance(exc, PrefectHTTPStatusError):\n                detail = exc.response.json().get(\"detail\")\n                if detail:\n                    raise DeploymentApplyError(detail) from exc\n            raise DeploymentApplyError(\n                f\"Error while applying deployment: {str(exc)}\"\n            ) from exc\n\n        if client.server_type.supports_automations():\n            try:\n                # The triggers defined in the deployment spec are, essentially,\n                # anonymous and attempting truly sync them with cloud is not\n                # feasible. Instead, we remove all automations that are owned\n                # by the deployment, meaning that they were created via this\n                # mechanism below, and then recreate them.\n                await client.delete_resource_owned_automations(\n                    f\"prefect.deployment.{deployment_id}\"\n                )\n            except PrefectHTTPStatusError as e:\n                if e.response.status_code == 404:\n                    # This Prefect server does not support automations, so we can safely\n                    # ignore this 404 and move on.\n                    return deployment_id\n                raise e\n\n            for trigger in self.triggers:\n                trigger.set_deployment_id(deployment_id)\n                await client.create_automation(trigger.as_automation())\n\n        return deployment_id\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_entrypoint","title":"<code>from_entrypoint</code>  <code>classmethod</code>","text":"<p>Configure a deployment for a given flow located at a given entrypoint.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\ndef from_entrypoint(\n    cls,\n    entrypoint: str,\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Configure a deployment for a given flow located at a given entrypoint.\n\n    Args:\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n        name: A name for the deployment\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    from prefect.flows import load_flow_from_entrypoint\n\n    job_variables = job_variables or {}\n    flow = load_flow_from_entrypoint(entrypoint)\n\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        entrypoint=entrypoint,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n    deployment._path = str(Path.cwd())\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_flow","title":"<code>from_flow</code>  <code>classmethod</code>","text":"<p>Configure a deployment for a given flow.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow function to deploy</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>paused</code> <code>Optional[bool]</code> <p>Whether or not to set this deployment as paused.</p> <code>None</code> <code>schedules</code> <code>Optional[FlexibleScheduleList]</code> <p>A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like <code>timezone</code>.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\ndef from_flow(\n    cls,\n    flow: \"Flow\",\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; \"RunnerDeployment\":\n    \"\"\"\n    Configure a deployment for a given flow.\n\n    Args:\n        flow: A flow function to deploy\n        name: A name for the deployment\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        paused: Whether or not to set this deployment as paused.\n        schedules: A list of schedule objects defining when to execute runs of this deployment.\n            Used to define multiple schedules or additional scheduling options like `timezone`.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    job_variables = job_variables or {}\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        is_schedule_active=is_schedule_active,\n        paused=paused,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n\n    if not deployment.entrypoint:\n        no_file_location_error = (\n            \"Flows defined interactively cannot be deployed. Check out the\"\n            \" quickstart guide for help getting started:\"\n            \" https://docs.prefect.io/latest/getting-started/quickstart\"\n        )\n        ## first see if an entrypoint can be determined\n        flow_file = getattr(flow, \"__globals__\", {}).get(\"__file__\")\n        mod_name = getattr(flow, \"__module__\", None)\n        if entrypoint_type == EntrypointType.MODULE_PATH:\n            if mod_name:\n                deployment.entrypoint = f\"{mod_name}.{flow.__name__}\"\n            else:\n                raise ValueError(\n                    \"Unable to determine module path for provided flow.\"\n                )\n        else:\n            if not flow_file:\n                if not mod_name:\n                    raise ValueError(no_file_location_error)\n                try:\n                    module = importlib.import_module(mod_name)\n                    flow_file = getattr(module, \"__file__\", None)\n                except ModuleNotFoundError as exc:\n                    if \"__prefect_loader__\" in str(exc):\n                        raise ValueError(\n                            \"Cannot create a RunnerDeployment from a flow that has been\"\n                            \" loaded from an entrypoint. To deploy a flow via\"\n                            \" entrypoint, use RunnerDeployment.from_entrypoint instead.\"\n                        )\n                    raise ValueError(no_file_location_error)\n                if not flow_file:\n                    raise ValueError(no_file_location_error)\n\n            # set entrypoint\n            entry_path = (\n                Path(flow_file).absolute().relative_to(Path.cwd().absolute())\n            )\n            deployment.entrypoint = f\"{entry_path}:{flow.fn.__name__}\"\n\n    if entrypoint_type == EntrypointType.FILE_PATH and not deployment._path:\n        deployment._path = \".\"\n\n    deployment._entrypoint_type = entrypoint_type\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.from_storage","title":"<code>from_storage</code>  <code>async</code> <code>classmethod</code>","text":"<p>Create a RunnerDeployment from a flow located at a given entrypoint and stored in a local storage location.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>The path to a file containing a flow and the name of the flow function in the format <code>./path/to/file.py:flow_func_name</code>.</p> required <code>name</code> <code>str</code> <p>A name for the deployment</p> required <code>storage</code> <code>RunnerStorage</code> <p>A storage object to use for retrieving flow code. If not provided, a URL must be provided.</p> required <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>enforce_parameter_schema</code> <code>bool</code> <p>Whether or not the Prefect API should enforce the parameter schema for this deployment.</p> <code>False</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for this deployment.</p> <code>None</code> <code>work_queue_name</code> <code>Optional[str]</code> <p>The name of the work queue to use for this deployment's scheduled runs. If not provided the default work queue for the work pool will be used.</p> <code>None</code> <code>job_variables</code> <code>Optional[Dict[str, Any]]</code> <p>Settings used to override the values specified default base job template of the chosen work pool. Refer to the base job template of the chosen work pool for available settings.</p> <code>None</code> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def from_storage(\n    cls,\n    storage: RunnerStorage,\n    entrypoint: str,\n    name: str,\n    interval: Optional[\n        Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    work_pool_name: Optional[str] = None,\n    work_queue_name: Optional[str] = None,\n    job_variables: Optional[Dict[str, Any]] = None,\n):\n    \"\"\"\n    Create a RunnerDeployment from a flow located at a given entrypoint and stored in a\n    local storage location.\n\n    Args:\n        entrypoint:  The path to a file containing a flow and the name of the flow function in\n            the format `./path/to/file.py:flow_func_name`.\n        name: A name for the deployment\n        storage: A storage object to use for retrieving flow code. If not provided, a\n            URL must be provided.\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        enforce_parameter_schema: Whether or not the Prefect API should enforce the\n            parameter schema for this deployment.\n        work_pool_name: The name of the work pool to use for this deployment.\n        work_queue_name: The name of the work queue to use for this deployment's scheduled runs.\n            If not provided the default work queue for the work pool will be used.\n        job_variables: Settings used to override the values specified default base job template\n            of the chosen work pool. Refer to the base job template of the chosen work pool for\n            available settings.\n    \"\"\"\n    from prefect.flows import load_flow_from_entrypoint\n\n    constructed_schedules = cls._construct_deployment_schedules(\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedule=schedule,\n        schedules=schedules,\n    )\n\n    job_variables = job_variables or {}\n\n    with tempfile.TemporaryDirectory() as tmpdir:\n        storage.set_base_path(Path(tmpdir))\n        await storage.pull_code()\n\n        full_entrypoint = str(storage.destination / entrypoint)\n        flow = await from_async.wait_for_call_in_new_thread(\n            create_call(load_flow_from_entrypoint, full_entrypoint)\n        )\n\n    deployment = cls(\n        name=Path(name).stem,\n        flow_name=flow.name,\n        schedule=schedule,\n        schedules=constructed_schedules,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        tags=tags or [],\n        triggers=triggers or [],\n        parameters=parameters or {},\n        description=description,\n        version=version,\n        entrypoint=entrypoint,\n        enforce_parameter_schema=enforce_parameter_schema,\n        storage=storage,\n        work_pool_name=work_pool_name,\n        work_queue_name=work_queue_name,\n        job_variables=job_variables,\n    )\n    deployment._path = str(storage.destination).replace(\n        tmpdir, \"$STORAGE_BASE_PATH\"\n    )\n\n    cls._set_defaults_from_flow(deployment, flow)\n\n    return deployment\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.RunnerDeployment.validate_automation_names","title":"<code>validate_automation_names</code>","text":"<p>Ensure that each trigger has a name for its automation if none is provided.</p> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@validator(\"triggers\", allow_reuse=True)\ndef validate_automation_names(cls, field_value, values):\n    \"\"\"Ensure that each trigger has a name for its automation if none is provided.\"\"\"\n    return validate_automation_names(field_value, values)\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/runner/#prefect.deployments.runner.deploy","title":"<code>deploy</code>  <code>async</code>","text":"<p>Deploy the provided list of deployments to dynamic infrastructure via a work pool.</p> <p>By default, calling this function will build a Docker image for the deployments, push it to a registry, and create each deployment via the Prefect API that will run the corresponding flow on the given schedule.</p> <p>If you want to use an existing image, you can pass <code>build=False</code> to skip building and pushing an image.</p> <p>Parameters:</p> Name Type Description Default <code>*deployments</code> <code>RunnerDeployment</code> <p>A list of deployments to deploy.</p> <code>()</code> <code>work_pool_name</code> <code>Optional[str]</code> <p>The name of the work pool to use for these deployments. Defaults to the value of <code>PREFECT_DEFAULT_WORK_POOL_NAME</code>.</p> <code>None</code> <code>image</code> <code>Optional[Union[str, DeploymentImage]]</code> <p>The name of the Docker image to build, including the registry and repository. Pass a DeploymentImage instance to customize the Dockerfile used and build arguments.</p> <code>None</code> <code>build</code> <code>bool</code> <p>Whether or not to build a new image for the flow. If False, the provided image will be used as-is and pulled at runtime.</p> <code>True</code> <code>push</code> <code>bool</code> <p>Whether or not to skip pushing the built image to a registry.</p> <code>True</code> <code>print_next_steps_message</code> <code>bool</code> <p>Whether or not to print a message with next steps after deploying the deployments.</p> <code>True</code> <p>Returns:</p> Type Description <code>List[UUID]</code> <p>A list of deployment IDs for the created/updated deployments.</p> <p>Examples:</p> <p>Deploy a group of flows to a work pool:</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef local_flow():\n    print(\"I'm a locally defined flow!\")\n\nif __name__ == \"__main__\":\n    deploy(\n        local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n        flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        ).to_deployment(\n            name=\"example-deploy-remote-flow\",\n        ),\n        work_pool_name=\"my-work-pool\",\n        image=\"my-registry/my-image:dev\",\n    )\n</code></pre> Source code in <code>prefect/deployments/runner.py</code> <pre><code>@sync_compatible\nasync def deploy(\n    *deployments: RunnerDeployment,\n    work_pool_name: Optional[str] = None,\n    image: Optional[Union[str, DeploymentImage]] = None,\n    build: bool = True,\n    push: bool = True,\n    print_next_steps_message: bool = True,\n    ignore_warnings: bool = False,\n) -&gt; List[UUID]:\n    \"\"\"\n    Deploy the provided list of deployments to dynamic infrastructure via a\n    work pool.\n\n    By default, calling this function will build a Docker image for the deployments, push it to a\n    registry, and create each deployment via the Prefect API that will run the corresponding\n    flow on the given schedule.\n\n    If you want to use an existing image, you can pass `build=False` to skip building and pushing\n    an image.\n\n    Args:\n        *deployments: A list of deployments to deploy.\n        work_pool_name: The name of the work pool to use for these deployments. Defaults to\n            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.\n        image: The name of the Docker image to build, including the registry and\n            repository. Pass a DeploymentImage instance to customize the Dockerfile used\n            and build arguments.\n        build: Whether or not to build a new image for the flow. If False, the provided\n            image will be used as-is and pulled at runtime.\n        push: Whether or not to skip pushing the built image to a registry.\n        print_next_steps_message: Whether or not to print a message with next steps\n            after deploying the deployments.\n\n    Returns:\n        A list of deployment IDs for the created/updated deployments.\n\n    Examples:\n        Deploy a group of flows to a work pool:\n\n        ```python\n        from prefect import deploy, flow\n\n        @flow(log_prints=True)\n        def local_flow():\n            print(\"I'm a locally defined flow!\")\n\n        if __name__ == \"__main__\":\n            deploy(\n                local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n                flow.from_source(\n                    source=\"https://github.com/org/repo.git\",\n                    entrypoint=\"flows.py:my_flow\",\n                ).to_deployment(\n                    name=\"example-deploy-remote-flow\",\n                ),\n                work_pool_name=\"my-work-pool\",\n                image=\"my-registry/my-image:dev\",\n            )\n        ```\n    \"\"\"\n    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()\n\n    if not image and not all(\n        d.storage or d.entrypoint_type == EntrypointType.MODULE_PATH\n        for d in deployments\n    ):\n        raise ValueError(\n            \"Either an image or remote storage location must be provided when deploying\"\n            \" a deployment.\"\n        )\n\n    if not work_pool_name:\n        raise ValueError(\n            \"A work pool name must be provided when deploying a deployment. Either\"\n            \" provide a work pool name when calling `deploy` or set\"\n            \" `PREFECT_DEFAULT_WORK_POOL_NAME` in your profile.\"\n        )\n\n    if image and isinstance(image, str):\n        image_name, image_tag = parse_image_tag(image)\n        image = DeploymentImage(name=image_name, tag=image_tag)\n\n    try:\n        async with get_client() as client:\n            work_pool = await client.read_work_pool(work_pool_name)\n    except ObjectNotFound as exc:\n        raise ValueError(\n            f\"Could not find work pool {work_pool_name!r}. Please create it before\"\n            \" deploying this flow.\"\n        ) from exc\n\n    is_docker_based_work_pool = get_from_dict(\n        work_pool.base_job_template, \"variables.properties.image\", False\n    )\n    is_block_based_work_pool = get_from_dict(\n        work_pool.base_job_template, \"variables.properties.block\", False\n    )\n    # carve out an exception for block based work pools that only have a block in their base job template\n    console = Console()\n    if not is_docker_based_work_pool and not is_block_based_work_pool:\n        if image:\n            raise ValueError(\n                f\"Work pool {work_pool_name!r} does not support custom Docker images.\"\n                \" Please use a work pool with an `image` variable in its base job template\"\n                \" or specify a remote storage location for the flow with `.from_source`.\"\n                \" If you are attempting to deploy a flow to a local process work pool,\"\n                \" consider using `flow.serve` instead. See the documentation for more\"\n                \" information: https://docs.prefect.io/latest/concepts/flows/#serving-a-flow\"\n            )\n        elif work_pool.type == \"process\" and not ignore_warnings:\n            console.print(\n                \"Looks like you're deploying to a process work pool. If you're creating a\"\n                \" deployment for local development, calling `.serve` on your flow is a great\"\n                \" way to get started. See the documentation for more information:\"\n                \" https://docs.prefect.io/latest/concepts/flows/#serving-a-flow. \"\n                \" Set `ignore_warnings=True` to suppress this message.\",\n                style=\"yellow\",\n            )\n\n    is_managed_pool = work_pool.is_managed_pool\n    if is_managed_pool:\n        build = False\n        push = False\n\n    if image and build:\n        with Progress(\n            SpinnerColumn(),\n            TextColumn(f\"Building image {image.reference}...\"),\n            transient=True,\n            console=console,\n        ) as progress:\n            docker_build_task = progress.add_task(\"docker_build\", total=1)\n            image.build()\n\n            progress.update(docker_build_task, completed=1)\n            console.print(\n                f\"Successfully built image {image.reference!r}\", style=\"green\"\n            )\n\n    if image and build and push:\n        with Progress(\n            SpinnerColumn(),\n            TextColumn(\"Pushing image...\"),\n            transient=True,\n            console=console,\n        ) as progress:\n            docker_push_task = progress.add_task(\"docker_push\", total=1)\n\n            image.push()\n\n            progress.update(docker_push_task, completed=1)\n\n        console.print(f\"Successfully pushed image {image.reference!r}\", style=\"green\")\n\n    deployment_exceptions = []\n    deployment_ids = []\n    image_ref = image.reference if image else None\n    for deployment in track(\n        deployments,\n        description=\"Creating/updating deployments...\",\n        console=console,\n        transient=True,\n    ):\n        try:\n            deployment_ids.append(\n                await deployment.apply(image=image_ref, work_pool_name=work_pool_name)\n            )\n        except Exception as exc:\n            if len(deployments) == 1:\n                raise\n            deployment_exceptions.append({\"deployment\": deployment, \"exc\": exc})\n\n    if deployment_exceptions:\n        console.print(\n            \"Encountered errors while creating/updating deployments:\\n\",\n            style=\"orange_red1\",\n        )\n    else:\n        console.print(\"Successfully created/updated all deployments!\\n\", style=\"green\")\n\n    complete_failure = len(deployment_exceptions) == len(deployments)\n\n    table = Table(\n        title=\"Deployments\",\n        show_lines=True,\n    )\n\n    table.add_column(header=\"Name\", style=\"blue\", no_wrap=True)\n    table.add_column(header=\"Status\", style=\"blue\", no_wrap=True)\n    table.add_column(header=\"Details\", style=\"blue\")\n\n    for deployment in deployments:\n        errored_deployment = next(\n            (d for d in deployment_exceptions if d[\"deployment\"] == deployment),\n            None,\n        )\n        if errored_deployment:\n            table.add_row(\n                f\"{deployment.flow_name}/{deployment.name}\",\n                \"failed\",\n                str(errored_deployment[\"exc\"]),\n                style=\"red\",\n            )\n        else:\n            table.add_row(f\"{deployment.flow_name}/{deployment.name}\", \"applied\")\n    console.print(table)\n\n    if print_next_steps_message and not complete_failure:\n        if not work_pool.is_push_pool and not work_pool.is_managed_pool:\n            console.print(\n                \"\\nTo execute flow runs from these deployments, start a worker in a\"\n                \" separate terminal that pulls work from the\"\n                f\" {work_pool_name!r} work pool:\"\n            )\n            console.print(\n                f\"\\n\\t$ prefect worker start --pool {work_pool_name!r}\",\n                style=\"blue\",\n            )\n        console.print(\n            \"\\nTo trigger any of these deployments, use the\"\n            \" following command:\\n[blue]\\n\\t$ prefect deployment run\"\n            \" [DEPLOYMENT_NAME]\\n[/]\"\n        )\n\n        if PREFECT_UI_URL:\n            console.print(\n                \"\\nYou can also trigger your deployments via the Prefect UI:\"\n                f\" [blue]{PREFECT_UI_URL.value()}/deployments[/]\\n\"\n            )\n\n    return deployment_ids\n</code></pre>","tags":["Python API","flow runs","deployments","runners"]},{"location":"api-ref/prefect/deployments/steps/core/","title":"steps.core","text":"","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core","title":"<code>prefect.deployments.steps.core</code>","text":"<p>Core primitives for running Prefect deployment steps.</p> <p>Deployment steps are YAML representations of Python functions along with their inputs.</p> <p>Whenever a step is run, the following actions are taken:</p> <ul> <li>The step's inputs and block / variable references are resolved (see the <code>prefect deploy</code> documentation for more details)</li> <li>The step's function is imported; if it cannot be found, the <code>requires</code> keyword is used to install the necessary packages</li> <li>The step's function is called with the resolved inputs</li> <li>The step's output is returned and used to resolve inputs for subsequent steps</li> </ul>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core.StepExecutionError","title":"<code>StepExecutionError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a step fails to execute.</p> Source code in <code>prefect/deployments/steps/core.py</code> <pre><code>class StepExecutionError(Exception):\n    \"\"\"\n    Raised when a step fails to execute.\n    \"\"\"\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/core/#prefect.deployments.steps.core.run_step","title":"<code>run_step</code>  <code>async</code>","text":"<p>Runs a step, returns the step's output.</p> <p>Steps are assumed to be in the format <code>{\"importable.func.name\": {\"kwarg1\": \"value1\", ...}}</code>.</p> <p>The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the inputs before passing to the step function:</p> <p>This keyword is used to specify packages that should be installed before running the step.</p> Source code in <code>prefect/deployments/steps/core.py</code> <pre><code>async def run_step(step: Dict, upstream_outputs: Optional[Dict] = None) -&gt; Dict:\n    \"\"\"\n    Runs a step, returns the step's output.\n\n    Steps are assumed to be in the format `{\"importable.func.name\": {\"kwarg1\": \"value1\", ...}}`.\n\n    The 'id and 'requires' keywords are reserved for specific purposes and will be removed from the\n    inputs before passing to the step function:\n\n    This keyword is used to specify packages that should be installed before running the step.\n    \"\"\"\n    fqn, inputs = _get_step_fully_qualified_name_and_inputs(step)\n    upstream_outputs = upstream_outputs or {}\n\n    if len(step.keys()) &gt; 1:\n        raise ValueError(\n            f\"Step has unexpected additional keys: {', '.join(list(step.keys())[1:])}\"\n        )\n\n    keywords = {\n        keyword: inputs.pop(keyword)\n        for keyword in RESERVED_KEYWORDS\n        if keyword in inputs\n    }\n\n    inputs = apply_values(inputs, upstream_outputs)\n    inputs = await resolve_block_document_references(inputs)\n    inputs = await resolve_variables(inputs)\n    inputs = apply_values(inputs, os.environ)\n    step_func = _get_function_for_step(fqn, requires=keywords.get(\"requires\"))\n    result = await from_async.call_soon_in_new_thread(\n        Call.new(step_func, **inputs)\n    ).aresult()\n    return result\n</code></pre>","tags":["Python API","projects","deployments","steps"]},{"location":"api-ref/prefect/deployments/steps/pull/","title":"steps.pull","text":"","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull","title":"<code>prefect.deployments.steps.pull</code>","text":"<p>Core set of steps for specifying a Prefect project pull step.</p>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.git_clone","title":"<code>git_clone</code>  <code>async</code>","text":"<p>Clones a git repository into the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>repository</code> <code>str</code> <p>the URL of the repository to clone</p> required <code>branch</code> <code>Optional[str]</code> <p>the branch to clone; if not provided, the default branch will be used</p> <code>None</code> <code>include_submodules</code> <code>bool</code> <p>whether to include git submodules when cloning the repository</p> <code>False</code> <code>access_token</code> <code>Optional[str]</code> <p>an access token to use for cloning the repository; if not provided the repository will be cloned using the default git credentials</p> <code>None</code> <code>credentials</code> <code>Optional[Block]</code> <p>a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the credentials to use for cloning the repository.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the new directory that was created</p> <p>Raises:</p> Type Description <code>CalledProcessError</code> <p>if the git clone command fails for any reason</p> <p>Examples:</p> <p>Clone a public repository: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/PrefectHQ/prefect.git\n</code></pre></p> <p>Clone a branch of a public repository: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/PrefectHQ/prefect.git\n        branch: my-branch\n</code></pre></p> <p>Clone a private repository using a GitHubCredentials block: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n</code></pre></p> <p>Clone a private repository using an access token: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        access_token: \"{{ prefect.blocks.secret.github-access-token }}\" # Requires creation of a Secret block\n</code></pre> Note that you will need to create a Secret block to store the value of your git credentials. You can also store a username/password combo or token prefix (e.g. <code>x-token-auth</code>) in your secret block. Refer to your git providers documentation for the correct authentication schema.</p> <p>Clone a repository with submodules: <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        include_submodules: true\n</code></pre></p> <p>Clone a repository with an SSH key (note that the SSH key must be added to the worker before executing flows): <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: git@github.com:org/repo.git\n</code></pre></p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>@sync_compatible\nasync def git_clone(\n    repository: str,\n    branch: Optional[str] = None,\n    include_submodules: bool = False,\n    access_token: Optional[str] = None,\n    credentials: Optional[Block] = None,\n) -&gt; dict:\n    \"\"\"\n    Clones a git repository into the current working directory.\n\n    Args:\n        repository: the URL of the repository to clone\n        branch: the branch to clone; if not provided, the default branch will be used\n        include_submodules (bool): whether to include git submodules when cloning the repository\n        access_token: an access token to use for cloning the repository; if not provided\n            the repository will be cloned using the default git credentials\n        credentials: a GitHubCredentials, GitLabCredentials, or BitBucketCredentials block can be used to specify the\n            credentials to use for cloning the repository.\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the new directory that was created\n\n    Raises:\n        subprocess.CalledProcessError: if the git clone command fails for any reason\n\n    Examples:\n        Clone a public repository:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/PrefectHQ/prefect.git\n        ```\n\n        Clone a branch of a public repository:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/PrefectHQ/prefect.git\n                branch: my-branch\n        ```\n\n        Clone a private repository using a GitHubCredentials block:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n        ```\n\n        Clone a private repository using an access token:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                access_token: \"{{ prefect.blocks.secret.github-access-token }}\" # Requires creation of a Secret block\n        ```\n        Note that you will need to [create a Secret block](/concepts/blocks/#using-existing-block-types) to store the\n        value of your git credentials. You can also store a username/password combo or token prefix (e.g. `x-token-auth`)\n        in your secret block. Refer to your git providers documentation for the correct authentication schema.\n\n        Clone a repository with submodules:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: https://github.com/org/repo.git\n                include_submodules: true\n        ```\n\n        Clone a repository with an SSH key (note that the SSH key must be added to the worker\n        before executing flows):\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                repository: git@github.com:org/repo.git\n        ```\n    \"\"\"\n    if access_token and credentials:\n        raise ValueError(\n            \"Please provide either an access token or credentials but not both.\"\n        )\n\n    credentials = {\"access_token\": access_token} if access_token else credentials\n\n    storage = GitRepository(\n        url=repository,\n        credentials=credentials,\n        branch=branch,\n        include_submodules=include_submodules,\n    )\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(f\"Cloned repository {repository!r} into {directory!r}\")\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.git_clone_project","title":"<code>git_clone_project</code>  <code>async</code>","text":"<p>Deprecated. Use <code>git_clone</code> instead.</p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use 'git clone' instead.\")\n@sync_compatible\nasync def git_clone_project(\n    repository: str,\n    branch: Optional[str] = None,\n    include_submodules: bool = False,\n    access_token: Optional[str] = None,\n) -&gt; dict:\n    \"\"\"Deprecated. Use `git_clone` instead.\"\"\"\n    return await git_clone(\n        repository=repository,\n        branch=branch,\n        include_submodules=include_submodules,\n        access_token=access_token,\n    )\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.pull_from_remote_storage","title":"<code>pull_from_remote_storage</code>  <code>async</code>","text":"<p>Pulls code from a remote storage location into the current working directory.</p> <p>Works with protocols supported by <code>fsspec</code>.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>the URL of the remote storage location. Should be a valid <code>fsspec</code> URL. Some protocols may require an additional <code>fsspec</code> dependency to be installed. Refer to the <code>fsspec</code> docs for more details.</p> required <code>**settings</code> <code>Any</code> <p>any additional settings to pass the <code>fsspec</code> filesystem class.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the new directory that was created</p> <p>Examples:</p> <p>Pull code from a remote storage location: <pre><code>pull:\n    - prefect.deployments.steps.pull_from_remote_storage:\n        url: s3://my-bucket/my-folder\n</code></pre></p> <p>Pull code from a remote storage location with additional settings: <pre><code>pull:\n    - prefect.deployments.steps.pull_from_remote_storage:\n        url: s3://my-bucket/my-folder\n        key: {{ prefect.blocks.secret.my-aws-access-key }}}\n        secret: {{ prefect.blocks.secret.my-aws-secret-key }}}\n</code></pre></p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>async def pull_from_remote_storage(url: str, **settings: Any):\n    \"\"\"\n    Pulls code from a remote storage location into the current working directory.\n\n    Works with protocols supported by `fsspec`.\n\n    Args:\n        url (str): the URL of the remote storage location. Should be a valid `fsspec` URL.\n            Some protocols may require an additional `fsspec` dependency to be installed.\n            Refer to the [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)\n            for more details.\n        **settings (Any): any additional settings to pass the `fsspec` filesystem class.\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the new directory that was created\n\n    Examples:\n        Pull code from a remote storage location:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.pull_from_remote_storage:\n                url: s3://my-bucket/my-folder\n        ```\n\n        Pull code from a remote storage location with additional settings:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.pull_from_remote_storage:\n                url: s3://my-bucket/my-folder\n                key: {{ prefect.blocks.secret.my-aws-access-key }}}\n                secret: {{ prefect.blocks.secret.my-aws-secret-key }}}\n        ```\n    \"\"\"\n    storage = RemoteStorage(url, **settings)\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(f\"Pulled code from {url!r} into {directory!r}\")\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.pull_with_block","title":"<code>pull_with_block</code>  <code>async</code>","text":"<p>Pulls code using a block.</p> <p>Parameters:</p> Name Type Description Default <code>block_document_name</code> <code>str</code> <p>The name of the block document to use</p> required <code>block_type_slug</code> <code>str</code> <p>The slug of the type of block to use</p> required Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>async def pull_with_block(block_document_name: str, block_type_slug: str):\n    \"\"\"\n    Pulls code using a block.\n\n    Args:\n        block_document_name: The name of the block document to use\n        block_type_slug: The slug of the type of block to use\n    \"\"\"\n    full_slug = f\"{block_type_slug}/{block_document_name}\"\n    try:\n        block = await Block.load(full_slug)\n    except Exception:\n        deployment_logger.exception(\"Unable to load block '%s'\", full_slug)\n        raise\n\n    try:\n        storage = BlockStorageAdapter(block)\n    except Exception:\n        deployment_logger.exception(\n            \"Unable to create storage adapter for block '%s'\", full_slug\n        )\n        raise\n\n    await storage.pull_code()\n\n    directory = str(storage.destination.relative_to(Path.cwd()))\n    deployment_logger.info(\n        \"Pulled code using block '%s' into '%s'\", full_slug, directory\n    )\n    return {\"directory\": directory}\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/pull/#prefect.deployments.steps.pull.set_working_directory","title":"<code>set_working_directory</code>","text":"<p>Sets the working directory; works with both absolute and relative paths.</p> <p>Parameters:</p> Name Type Description Default <code>directory</code> <code>str</code> <p>the directory to set as the working directory</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict</code> <p>a dictionary containing a <code>directory</code> key of the directory that was set</p> Source code in <code>prefect/deployments/steps/pull.py</code> <pre><code>def set_working_directory(directory: str) -&gt; dict:\n    \"\"\"\n    Sets the working directory; works with both absolute and relative paths.\n\n    Args:\n        directory (str): the directory to set as the working directory\n\n    Returns:\n        dict: a dictionary containing a `directory` key of the\n            directory that was set\n    \"\"\"\n    os.chdir(directory)\n    return dict(directory=directory)\n</code></pre>","tags":["Python API","projects","deployments","steps","pull step"]},{"location":"api-ref/prefect/deployments/steps/utility/","title":"steps.utility","text":"","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility","title":"<code>prefect.deployments.steps.utility</code>","text":"<p>Utility project steps that are useful for managing a project's deployment lifecycle.</p> <p>Steps within this module can be used within a <code>build</code>, <code>push</code>, or <code>pull</code> deployment action.</p> Example <p>Use the <code>run_shell_script</code> setp to retrieve the short Git commit hash of the current      repository and use it as a Docker image tag: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre></p>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.RunShellScriptResult","title":"<code>RunShellScriptResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>run_shell_script</code> step.</p> <p>Attributes:</p> Name Type Description <code>stdout</code> <code>str</code> <p>The captured standard output of the script.</p> <code>stderr</code> <code>str</code> <p>The captured standard error of the script.</p> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>class RunShellScriptResult(TypedDict):\n    \"\"\"\n    The result of a `run_shell_script` step.\n\n    Attributes:\n        stdout: The captured standard output of the script.\n        stderr: The captured standard error of the script.\n    \"\"\"\n\n    stdout: str\n    stderr: str\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.pip_install_requirements","title":"<code>pip_install_requirements</code>  <code>async</code>","text":"<p>Installs dependencies from a requirements.txt file.</p> <p>Parameters:</p> Name Type Description Default <code>requirements_file</code> <code>str</code> <p>The requirements.txt to use for installation.</p> <code>'requirements.txt'</code> <code>directory</code> <code>Optional[str]</code> <p>The directory the requirements.txt file is in. Defaults to the current working directory.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream the output from pip install should be streamed to the console</p> <code>True</code> <p>Returns:</p> Type Description <p>A dictionary with the keys <code>stdout</code> and <code>stderr</code> containing the output the <code>pip install</code> command</p> <p>Raises:</p> Type Description <code>CalledProcessError</code> <p>if the pip install command fails for any reason</p> Example <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        id: clone-step\n        repository: https://github.com/org/repo.git\n    - prefect.deployments.steps.pip_install_requirements:\n        directory: {{ clone-step.directory }}\n        requirements_file: requirements.txt\n        stream_output: False\n</code></pre> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>async def pip_install_requirements(\n    directory: Optional[str] = None,\n    requirements_file: str = \"requirements.txt\",\n    stream_output: bool = True,\n):\n    \"\"\"\n    Installs dependencies from a requirements.txt file.\n\n    Args:\n        requirements_file: The requirements.txt to use for installation.\n        directory: The directory the requirements.txt file is in. Defaults to\n            the current working directory.\n        stream_output: Whether to stream the output from pip install should be\n            streamed to the console\n\n    Returns:\n        A dictionary with the keys `stdout` and `stderr` containing the output\n            the `pip install` command\n\n    Raises:\n        subprocess.CalledProcessError: if the pip install command fails for any reason\n\n    Example:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.git_clone:\n                id: clone-step\n                repository: https://github.com/org/repo.git\n            - prefect.deployments.steps.pip_install_requirements:\n                directory: {{ clone-step.directory }}\n                requirements_file: requirements.txt\n                stream_output: False\n        ```\n    \"\"\"\n    stdout_sink = io.StringIO()\n    stderr_sink = io.StringIO()\n\n    async with open_process(\n        [get_sys_executable(), \"-m\", \"pip\", \"install\", \"-r\", requirements_file],\n        stdout=subprocess.PIPE,\n        stderr=subprocess.PIPE,\n        cwd=directory,\n    ) as process:\n        await _stream_capture_process_output(\n            process,\n            stdout_sink=stdout_sink,\n            stderr_sink=stderr_sink,\n            stream_output=stream_output,\n        )\n        await process.wait()\n\n        if process.returncode != 0:\n            raise RuntimeError(\n                f\"pip_install_requirements failed with error code {process.returncode}:\"\n                f\" {stderr_sink.getvalue()}\"\n            )\n\n    return {\n        \"stdout\": stdout_sink.getvalue().strip(),\n        \"stderr\": stderr_sink.getvalue().strip(),\n    }\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/deployments/steps/utility/#prefect.deployments.steps.utility.run_shell_script","title":"<code>run_shell_script</code>  <code>async</code>","text":"<p>Runs one or more shell commands in a subprocess. Returns the standard output and standard error of the script.</p> <p>Parameters:</p> Name Type Description Default <code>script</code> <code>str</code> <p>The script to run</p> required <code>directory</code> <code>Optional[str]</code> <p>The directory to run the script in. Defaults to the current working directory.</p> <code>None</code> <code>env</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of environment variables to set for the script</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream the output of the script to stdout/stderr</p> <code>True</code> <code>expand_env_vars</code> <code>bool</code> <p>Whether to expand environment variables in the script before running it</p> <code>False</code> <p>Returns:</p> Type Description <code>RunShellScriptResult</code> <p>A dictionary with the keys <code>stdout</code> and <code>stderr</code> containing the output of the script</p> <p>Examples:</p> <p>Retrieve the short Git commit hash of the current repository to use as     a Docker image tag: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre></p> <p>Run a multi-line shell script: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: |\n            echo \"Hello\"\n            echo \"World\"\n</code></pre></p> <p>Run a shell script with environment variables: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: echo \"Hello $NAME\"\n        env:\n            NAME: World\n</code></pre></p> <p>Run a shell script with environment variables expanded     from the current environment: <pre><code>pull:\n    - prefect.deployments.steps.run_shell_script:\n        script: |\n            echo \"User: $USER\"\n            echo \"Home Directory: $HOME\"\n        stream_output: true\n        expand_env_vars: true\n</code></pre></p> <p>Run a shell script in a specific directory: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: echo \"Hello\"\n        directory: /path/to/directory\n</code></pre></p> <p>Run a script stored in a file: <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        script: \"bash path/to/script.sh\"\n</code></pre></p> Source code in <code>prefect/deployments/steps/utility.py</code> <pre><code>async def run_shell_script(\n    script: str,\n    directory: Optional[str] = None,\n    env: Optional[Dict[str, str]] = None,\n    stream_output: bool = True,\n    expand_env_vars: bool = False,\n) -&gt; RunShellScriptResult:\n    \"\"\"\n    Runs one or more shell commands in a subprocess. Returns the standard\n    output and standard error of the script.\n\n    Args:\n        script: The script to run\n        directory: The directory to run the script in. Defaults to the current\n            working directory.\n        env: A dictionary of environment variables to set for the script\n        stream_output: Whether to stream the output of the script to\n            stdout/stderr\n        expand_env_vars: Whether to expand environment variables in the script\n            before running it\n\n    Returns:\n        A dictionary with the keys `stdout` and `stderr` containing the output\n            of the script\n\n    Examples:\n        Retrieve the short Git commit hash of the current repository to use as\n            a Docker image tag:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                id: get-commit-hash\n                script: git rev-parse --short HEAD\n                stream_output: false\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: my-image\n                image_tag: \"{{ get-commit-hash.stdout }}\"\n                dockerfile: auto\n        ```\n\n        Run a multi-line shell script:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: |\n                    echo \"Hello\"\n                    echo \"World\"\n        ```\n\n        Run a shell script with environment variables:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: echo \"Hello $NAME\"\n                env:\n                    NAME: World\n        ```\n\n        Run a shell script with environment variables expanded\n            from the current environment:\n        ```yaml\n        pull:\n            - prefect.deployments.steps.run_shell_script:\n                script: |\n                    echo \"User: $USER\"\n                    echo \"Home Directory: $HOME\"\n                stream_output: true\n                expand_env_vars: true\n        ```\n\n        Run a shell script in a specific directory:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: echo \"Hello\"\n                directory: /path/to/directory\n        ```\n\n        Run a script stored in a file:\n        ```yaml\n        build:\n            - prefect.deployments.steps.run_shell_script:\n                script: \"bash path/to/script.sh\"\n        ```\n    \"\"\"\n    current_env = os.environ.copy()\n    current_env.update(env or {})\n\n    commands = script.splitlines()\n    stdout_sink = io.StringIO()\n    stderr_sink = io.StringIO()\n\n    for command in commands:\n        if expand_env_vars:\n            # Expand environment variables in command and provided environment\n            command = string.Template(command).safe_substitute(current_env)\n        split_command = shlex.split(command, posix=sys.platform != \"win32\")\n        if not split_command:\n            continue\n        async with open_process(\n            split_command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.PIPE,\n            cwd=directory,\n            env=current_env,\n        ) as process:\n            await _stream_capture_process_output(\n                process,\n                stdout_sink=stdout_sink,\n                stderr_sink=stderr_sink,\n                stream_output=stream_output,\n            )\n\n            await process.wait()\n\n            if process.returncode != 0:\n                raise RuntimeError(\n                    f\"`run_shell_script` failed with error code {process.returncode}:\"\n                    f\" {stderr_sink.getvalue()}\"\n                )\n\n    return {\n        \"stdout\": stdout_sink.getvalue().strip(),\n        \"stderr\": stderr_sink.getvalue().strip(),\n    }\n</code></pre>","tags":["Python API","projects","deployments","steps","shell","pip install","requirements.txt"]},{"location":"api-ref/prefect/input/actions/","title":"actions","text":"","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions","title":"<code>prefect.input.actions</code>","text":"","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Create a new flow run input. The given <code>value</code> will be serialized to JSON and stored as a flow run input value.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>key (str</code> <p>the flow run input key</p> required <code>-</code> <code>value (Any</code> <p>the flow run input value</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the, optional, flow run ID. If not given will default to pulling the flow run ID from the current context.</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def create_flow_run_input(\n    client: \"PrefectClient\",\n    key: str,\n    value: Any,\n    flow_run_id: Optional[UUID] = None,\n    sender: Optional[str] = None,\n):\n    \"\"\"\n    Create a new flow run input. The given `value` will be serialized to JSON\n    and stored as a flow run input value.\n\n    Args:\n        - key (str): the flow run input key\n        - value (Any): the flow run input value\n        - flow_run_id (UUID): the, optional, flow run ID. If not given will\n          default to pulling the flow run ID from the current context.\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    await client.create_flow_run_input(\n        flow_run_id=flow_run_id,\n        key=key,\n        sender=sender,\n        value=orjson.dumps(value).decode(),\n    )\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Delete a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID</p> required <code>-</code> <code>key (str</code> <p>the flow run input key</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def delete_flow_run_input(\n    client: \"PrefectClient\", key: str, flow_run_id: Optional[UUID] = None\n):\n    \"\"\"Delete a flow run input.\n\n    Args:\n        - flow_run_id (UUID): the flow run ID\n        - key (str): the flow run input key\n    \"\"\"\n\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    await client.delete_flow_run_input(flow_run_id=flow_run_id, key=key)\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/actions/#prefect.input.actions.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Read a flow run input.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>key (str</code> <p>the flow run input key</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID</p> required Source code in <code>prefect/input/actions.py</code> <pre><code>@sync_compatible\n@client_injector\nasync def read_flow_run_input(\n    client: \"PrefectClient\", key: str, flow_run_id: Optional[UUID] = None\n) -&gt; Any:\n    \"\"\"Read a flow run input.\n\n    Args:\n        - key (str): the flow run input key\n        - flow_run_id (UUID): the flow run ID\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n\n    try:\n        value = await client.read_flow_run_input(flow_run_id=flow_run_id, key=key)\n    except PrefectHTTPStatusError as exc:\n        if exc.response.status_code == 404:\n            return None\n        raise\n    else:\n        return orjson.loads(value)\n</code></pre>","tags":["flow run","pause","suspend","input"]},{"location":"api-ref/prefect/input/run_input/","title":"run_input","text":"","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input","title":"<code>prefect.input.run_input</code>","text":"<p>This module contains functions that allow sending type-checked <code>RunInput</code> data to flows at runtime. Flows can send back responses, establishing two-way channels with senders. These functions are particularly useful for systems that require ongoing data transfer or need to react to input quickly. real-time interaction and efficient data handling. It's designed to facilitate dynamic communication within distributed or microservices-oriented systems, making it ideal for scenarios requiring continuous data synchronization and processing. It's particularly useful for systems that require ongoing data input and output.</p> <p>The following is an example of two flows. One sends a random number to the other and waits for a response. The other receives the number, squares it, and sends the result back. The sender flow then prints the result.</p> <p>Sender flow:</p> <pre><code>import random\nfrom uuid import UUID\nfrom prefect import flow, get_run_logger\nfrom prefect.input import RunInput\n\nclass NumberData(RunInput):\n    number: int\n\n\n@flow\nasync def sender_flow(receiver_flow_run_id: UUID):\n    logger = get_run_logger()\n\n    the_number = random.randint(1, 100)\n\n    await NumberData(number=the_number).send_to(receiver_flow_run_id)\n\n    receiver = NumberData.receive(flow_run_id=receiver_flow_run_id)\n    squared = await receiver.next()\n\n    logger.info(f\"{the_number} squared is {squared.number}\")\n</code></pre> <p>Receiver flow: <pre><code>import random\nfrom uuid import UUID\nfrom prefect import flow, get_run_logger\nfrom prefect.input import RunInput\n\nclass NumberData(RunInput):\n    number: int\n\n\n@flow\nasync def receiver_flow():\n    async for data in NumberData.receive():\n        squared = data.number ** 2\n        data.respond(NumberData(number=squared))\n</code></pre></p>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput","title":"<code>AutomaticRunInput</code>","text":"<p>               Bases: <code>RunInput</code>, <code>Generic[T]</code></p> Source code in <code>prefect/input/run_input.py</code> <pre><code>class AutomaticRunInput(RunInput, Generic[T]):\n    value: T\n\n    @classmethod\n    @sync_compatible\n    async def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -&gt; T:\n        \"\"\"\n        Load the run input response from the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to load the input for\n            - flow_run_id (UUID, optional): the flow run ID to load the input for\n        \"\"\"\n        instance = await super().load(keyset, flow_run_id=flow_run_id)\n        return instance.value\n\n    @classmethod\n    def subclass_from_type(cls, _type: Type[T]) -&gt; Type[\"AutomaticRunInput[T]\"]:\n        \"\"\"\n        Create a new `AutomaticRunInput` subclass from the given type.\n\n        This method uses the type's name as a key prefix to identify related\n        flow run inputs. This helps in ensuring that values saved under a type\n        (like List[int]) are retrievable under the generic type name (like \"list\").\n        \"\"\"\n        fields: Dict[str, Any] = {\"value\": (_type, ...)}\n\n        # Explanation for using getattr for type name extraction:\n        # - \"__name__\": This is the usual attribute for getting the name of\n        #   most types.\n        # - \"_name\": Used as a fallback, some type annotations in Python 3.9\n        #   and earlier might only have this attribute instead of __name__.\n        # - If neither is available, defaults to an empty string to prevent\n        #   errors, but typically we should find at least one valid name\n        #   attribute. This will match all automatic inputs sent to the flow\n        #   run, rather than a specific type.\n        #\n        # This approach ensures compatibility across Python versions and\n        # handles various edge cases in type annotations.\n\n        type_prefix: str = getattr(\n            _type, \"__name__\", getattr(_type, \"_name\", \"\")\n        ).lower()\n\n        class_name = f\"{type_prefix}AutomaticRunInput\"\n\n        # Creating a new Pydantic model class dynamically with the name based\n        # on the type prefix.\n        new_cls: Type[\"AutomaticRunInput\"] = pydantic.create_model(\n            class_name, **fields, __base__=AutomaticRunInput\n        )\n        return new_cls\n\n    @classmethod\n    def receive(cls, *args, **kwargs):\n        if kwargs.get(\"key_prefix\") is None:\n            kwargs[\"key_prefix\"] = f\"{cls.__name__.lower()}-auto\"\n\n        return GetAutomaticInputHandler(run_input_cls=cls, *args, **kwargs)\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Load the run input response from the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to load the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None) -&gt; T:\n    \"\"\"\n    Load the run input response from the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to load the input for\n        - flow_run_id (UUID, optional): the flow run ID to load the input for\n    \"\"\"\n    instance = await super().load(keyset, flow_run_id=flow_run_id)\n    return instance.value\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.AutomaticRunInput.subclass_from_type","title":"<code>subclass_from_type</code>  <code>classmethod</code>","text":"<p>Create a new <code>AutomaticRunInput</code> subclass from the given type.</p> <p>This method uses the type's name as a key prefix to identify related flow run inputs. This helps in ensuring that values saved under a type (like List[int]) are retrievable under the generic type name (like \"list\").</p> Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef subclass_from_type(cls, _type: Type[T]) -&gt; Type[\"AutomaticRunInput[T]\"]:\n    \"\"\"\n    Create a new `AutomaticRunInput` subclass from the given type.\n\n    This method uses the type's name as a key prefix to identify related\n    flow run inputs. This helps in ensuring that values saved under a type\n    (like List[int]) are retrievable under the generic type name (like \"list\").\n    \"\"\"\n    fields: Dict[str, Any] = {\"value\": (_type, ...)}\n\n    # Explanation for using getattr for type name extraction:\n    # - \"__name__\": This is the usual attribute for getting the name of\n    #   most types.\n    # - \"_name\": Used as a fallback, some type annotations in Python 3.9\n    #   and earlier might only have this attribute instead of __name__.\n    # - If neither is available, defaults to an empty string to prevent\n    #   errors, but typically we should find at least one valid name\n    #   attribute. This will match all automatic inputs sent to the flow\n    #   run, rather than a specific type.\n    #\n    # This approach ensures compatibility across Python versions and\n    # handles various edge cases in type annotations.\n\n    type_prefix: str = getattr(\n        _type, \"__name__\", getattr(_type, \"_name\", \"\")\n    ).lower()\n\n    class_name = f\"{type_prefix}AutomaticRunInput\"\n\n    # Creating a new Pydantic model class dynamically with the name based\n    # on the type prefix.\n    new_cls: Type[\"AutomaticRunInput\"] = pydantic.create_model(\n        class_name, **fields, __base__=AutomaticRunInput\n    )\n    return new_cls\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput","title":"<code>RunInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/input/run_input.py</code> <pre><code>class RunInput(pydantic.BaseModel):\n    class Config:\n        extra = \"forbid\"\n\n    _description: Optional[str] = pydantic.PrivateAttr(default=None)\n    _metadata: RunInputMetadata = pydantic.PrivateAttr()\n\n    @property\n    def metadata(self) -&gt; RunInputMetadata:\n        return self._metadata\n\n    @classmethod\n    def keyset_from_type(cls) -&gt; Keyset:\n        return keyset_from_base_key(cls.__name__.lower())\n\n    @classmethod\n    @sync_compatible\n    async def save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n        \"\"\"\n        Save the run input response to the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to save the input for\n            - flow_run_id (UUID, optional): the flow run ID to save the input for\n        \"\"\"\n\n        if HAS_PYDANTIC_V2:\n            schema = create_v2_schema(cls.__name__, model_base=cls)\n        else:\n            schema = cls.schema(by_alias=True)\n\n        await create_flow_run_input(\n            key=keyset[\"schema\"], value=schema, flow_run_id=flow_run_id\n        )\n\n        description = cls._description if isinstance(cls._description, str) else None\n        if description:\n            await create_flow_run_input(\n                key=keyset[\"description\"],\n                value=description,\n                flow_run_id=flow_run_id,\n            )\n\n    @classmethod\n    @sync_compatible\n    async def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n        \"\"\"\n        Load the run input response from the given key.\n\n        Args:\n            - keyset (Keyset): the keyset to load the input for\n            - flow_run_id (UUID, optional): the flow run ID to load the input for\n        \"\"\"\n        flow_run_id = ensure_flow_run_id(flow_run_id)\n        value = await read_flow_run_input(keyset[\"response\"], flow_run_id=flow_run_id)\n        if value:\n            instance = cls(**value)\n        else:\n            instance = cls()\n        instance._metadata = RunInputMetadata(\n            key=keyset[\"response\"], sender=None, receiver=flow_run_id\n        )\n        return instance\n\n    @classmethod\n    def load_from_flow_run_input(cls, flow_run_input: \"FlowRunInput\"):\n        \"\"\"\n        Load the run input from a FlowRunInput object.\n\n        Args:\n            - flow_run_input (FlowRunInput): the flow run input to load the input for\n        \"\"\"\n        instance = cls(**flow_run_input.decoded_value)\n        instance._metadata = RunInputMetadata(\n            key=flow_run_input.key,\n            sender=flow_run_input.sender,\n            receiver=flow_run_input.flow_run_id,\n        )\n        return instance\n\n    @classmethod\n    def with_initial_data(\n        cls: Type[R], description: Optional[str] = None, **kwargs: Any\n    ) -&gt; Type[R]:\n        \"\"\"\n        Create a new `RunInput` subclass with the given initial data as field\n        defaults.\n\n        Args:\n            - description (str, optional): a description to show when resuming\n                a flow run that requires input\n            - kwargs (Any): the initial data to populate the subclass\n        \"\"\"\n        fields: Dict[str, Any] = {}\n        for key, value in kwargs.items():\n            fields[key] = (type(value), value)\n        model = pydantic.create_model(cls.__name__, **fields, __base__=cls)\n\n        if description is not None:\n            model._description = description\n\n        return model\n\n    @sync_compatible\n    async def respond(\n        self,\n        run_input: \"RunInput\",\n        sender: Optional[str] = None,\n        key_prefix: Optional[str] = None,\n    ):\n        flow_run_id = None\n        if self.metadata.sender and self.metadata.sender.startswith(\"prefect.flow-run\"):\n            _, _, id = self.metadata.sender.rpartition(\".\")\n            flow_run_id = UUID(id)\n\n        if not flow_run_id:\n            raise RuntimeError(\n                \"Cannot respond to an input that was not sent by a flow run.\"\n            )\n\n        await _send_input(\n            flow_run_id=flow_run_id,\n            run_input=run_input,\n            sender=sender,\n            key_prefix=key_prefix,\n        )\n\n    @sync_compatible\n    async def send_to(\n        self,\n        flow_run_id: UUID,\n        sender: Optional[str] = None,\n        key_prefix: Optional[str] = None,\n    ):\n        await _send_input(\n            flow_run_id=flow_run_id,\n            run_input=self,\n            sender=sender,\n            key_prefix=key_prefix,\n        )\n\n    @classmethod\n    def receive(\n        cls,\n        timeout: Optional[float] = 3600,\n        poll_interval: float = 10,\n        raise_timeout_error: bool = False,\n        exclude_keys: Optional[Set[str]] = None,\n        key_prefix: Optional[str] = None,\n        flow_run_id: Optional[UUID] = None,\n    ):\n        if key_prefix is None:\n            key_prefix = f\"{cls.__name__.lower()}-auto\"\n\n        return GetInputHandler(\n            run_input_cls=cls,\n            key_prefix=key_prefix,\n            timeout=timeout,\n            poll_interval=poll_interval,\n            raise_timeout_error=raise_timeout_error,\n            exclude_keys=exclude_keys,\n            flow_run_id=flow_run_id,\n        )\n\n    @classmethod\n    def subclass_from_base_model_type(\n        cls, model_cls: Type[pydantic.BaseModel]\n    ) -&gt; Type[\"RunInput\"]:\n        \"\"\"\n        Create a new `RunInput` subclass from the given `pydantic.BaseModel`\n        subclass.\n\n        Args:\n            - model_cls (pydantic.BaseModel subclass): the class from which\n                to create the new `RunInput` subclass\n        \"\"\"\n        return type(f\"{model_cls.__name__}RunInput\", (RunInput, model_cls), {})  # type: ignore\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.load","title":"<code>load</code>  <code>async</code> <code>classmethod</code>","text":"<p>Load the run input response from the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to load the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n    \"\"\"\n    Load the run input response from the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to load the input for\n        - flow_run_id (UUID, optional): the flow run ID to load the input for\n    \"\"\"\n    flow_run_id = ensure_flow_run_id(flow_run_id)\n    value = await read_flow_run_input(keyset[\"response\"], flow_run_id=flow_run_id)\n    if value:\n        instance = cls(**value)\n    else:\n        instance = cls()\n    instance._metadata = RunInputMetadata(\n        key=keyset[\"response\"], sender=None, receiver=flow_run_id\n    )\n    return instance\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.load_from_flow_run_input","title":"<code>load_from_flow_run_input</code>  <code>classmethod</code>","text":"<p>Load the run input from a FlowRunInput object.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>flow_run_input (FlowRunInput</code> <p>the flow run input to load the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef load_from_flow_run_input(cls, flow_run_input: \"FlowRunInput\"):\n    \"\"\"\n    Load the run input from a FlowRunInput object.\n\n    Args:\n        - flow_run_input (FlowRunInput): the flow run input to load the input for\n    \"\"\"\n    instance = cls(**flow_run_input.decoded_value)\n    instance._metadata = RunInputMetadata(\n        key=flow_run_input.key,\n        sender=flow_run_input.sender,\n        receiver=flow_run_input.flow_run_id,\n    )\n    return instance\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.save","title":"<code>save</code>  <code>async</code> <code>classmethod</code>","text":"<p>Save the run input response to the given key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>keyset (Keyset</code> <p>the keyset to save the input for</p> required <code>-</code> <code>flow_run_id (UUID</code> <p>the flow run ID to save the input for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\n@sync_compatible\nasync def save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):\n    \"\"\"\n    Save the run input response to the given key.\n\n    Args:\n        - keyset (Keyset): the keyset to save the input for\n        - flow_run_id (UUID, optional): the flow run ID to save the input for\n    \"\"\"\n\n    if HAS_PYDANTIC_V2:\n        schema = create_v2_schema(cls.__name__, model_base=cls)\n    else:\n        schema = cls.schema(by_alias=True)\n\n    await create_flow_run_input(\n        key=keyset[\"schema\"], value=schema, flow_run_id=flow_run_id\n    )\n\n    description = cls._description if isinstance(cls._description, str) else None\n    if description:\n        await create_flow_run_input(\n            key=keyset[\"description\"],\n            value=description,\n            flow_run_id=flow_run_id,\n        )\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.subclass_from_base_model_type","title":"<code>subclass_from_base_model_type</code>  <code>classmethod</code>","text":"<p>Create a new <code>RunInput</code> subclass from the given <code>pydantic.BaseModel</code> subclass.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>model_cls (pydantic.BaseModel subclass</code> <p>the class from which to create the new <code>RunInput</code> subclass</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef subclass_from_base_model_type(\n    cls, model_cls: Type[pydantic.BaseModel]\n) -&gt; Type[\"RunInput\"]:\n    \"\"\"\n    Create a new `RunInput` subclass from the given `pydantic.BaseModel`\n    subclass.\n\n    Args:\n        - model_cls (pydantic.BaseModel subclass): the class from which\n            to create the new `RunInput` subclass\n    \"\"\"\n    return type(f\"{model_cls.__name__}RunInput\", (RunInput, model_cls), {})  # type: ignore\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.RunInput.with_initial_data","title":"<code>with_initial_data</code>  <code>classmethod</code>","text":"<p>Create a new <code>RunInput</code> subclass with the given initial data as field defaults.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>description (str</code> <p>a description to show when resuming a flow run that requires input</p> required <code>-</code> <code>kwargs (Any</code> <p>the initial data to populate the subclass</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>@classmethod\ndef with_initial_data(\n    cls: Type[R], description: Optional[str] = None, **kwargs: Any\n) -&gt; Type[R]:\n    \"\"\"\n    Create a new `RunInput` subclass with the given initial data as field\n    defaults.\n\n    Args:\n        - description (str, optional): a description to show when resuming\n            a flow run that requires input\n        - kwargs (Any): the initial data to populate the subclass\n    \"\"\"\n    fields: Dict[str, Any] = {}\n    for key, value in kwargs.items():\n        fields[key] = (type(value), value)\n    model = pydantic.create_model(cls.__name__, **fields, __base__=cls)\n\n    if description is not None:\n        model._description = description\n\n    return model\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.keyset_from_base_key","title":"<code>keyset_from_base_key</code>","text":"<p>Get the keyset for the given base key.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>base_key (str</code> <p>the base key to get the keyset for</p> required <p>Returns:</p> Type Description <code>Keyset</code> <ul> <li>Dict[str, str]: the keyset</li> </ul> Source code in <code>prefect/input/run_input.py</code> <pre><code>def keyset_from_base_key(base_key: str) -&gt; Keyset:\n    \"\"\"\n    Get the keyset for the given base key.\n\n    Args:\n        - base_key (str): the base key to get the keyset for\n\n    Returns:\n        - Dict[str, str]: the keyset\n    \"\"\"\n    return {\n        \"description\": f\"{base_key}-description\",\n        \"response\": f\"{base_key}-response\",\n        \"schema\": f\"{base_key}-schema\",\n    }\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.keyset_from_paused_state","title":"<code>keyset_from_paused_state</code>","text":"<p>Get the keyset for the given Paused state.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>state (State</code> <p>the state to get the keyset for</p> required Source code in <code>prefect/input/run_input.py</code> <pre><code>def keyset_from_paused_state(state: \"State\") -&gt; Keyset:\n    \"\"\"\n    Get the keyset for the given Paused state.\n\n    Args:\n        - state (State): the state to get the keyset for\n    \"\"\"\n\n    if not state.is_paused():\n        raise RuntimeError(f\"{state.type.value!r} is unsupported.\")\n\n    state_name = state.name or \"\"\n    base_key = f\"{state_name.lower()}-{str(state.state_details.pause_key)}\"\n    return keyset_from_base_key(base_key)\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/input/run_input/#prefect.input.run_input.run_input_subclass_from_type","title":"<code>run_input_subclass_from_type</code>","text":"<p>Create a new <code>RunInput</code> subclass from the given type.</p> Source code in <code>prefect/input/run_input.py</code> <pre><code>def run_input_subclass_from_type(\n    _type: Union[Type[R], Type[T], pydantic.BaseModel],\n) -&gt; Union[Type[AutomaticRunInput[T]], Type[R]]:\n    \"\"\"\n    Create a new `RunInput` subclass from the given type.\n    \"\"\"\n    if isclass(_type):\n        if issubclass(_type, RunInput):\n            return cast(Type[R], _type)\n        elif issubclass(_type, pydantic.BaseModel):\n            return cast(Type[R], RunInput.subclass_from_base_model_type(_type))\n\n    # Could be something like a typing._GenericAlias or any other type that\n    # isn't a `RunInput` subclass or `pydantic.BaseModel` subclass. Try passing\n    # it to AutomaticRunInput to see if we can create a model from it.\n    return cast(\n        Type[AutomaticRunInput[T]],\n        AutomaticRunInput.subclass_from_type(cast(Type[T], _type)),\n    )\n</code></pre>","tags":["flow run","pause","suspend","input","run input"]},{"location":"api-ref/prefect/logging/configuration/","title":"configuration","text":"<p>\"\"\"</p>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration","title":"<code>prefect.logging.configuration</code>","text":"","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration.load_logging_config","title":"<code>load_logging_config</code>","text":"<p>Loads logging configuration from a path allowing override from the environment</p> Source code in <code>prefect/logging/configuration.py</code> <pre><code>def load_logging_config(path: Path) -&gt; dict:\n    \"\"\"\n    Loads logging configuration from a path allowing override from the environment\n    \"\"\"\n    template = string.Template(path.read_text())\n    with warnings.catch_warnings():\n        warnings.filterwarnings(\"ignore\", category=DeprecationWarning)\n        config = yaml.safe_load(\n            # Substitute settings into the template in format $SETTING / ${SETTING}\n            template.substitute(\n                {\n                    setting.name: str(setting.value())\n                    for setting in SETTING_VARIABLES.values()\n                    if setting.value() is not None\n                }\n            )\n        )\n\n    # Load overrides from the environment\n    flat_config = dict_to_flatdict(config)\n\n    for key_tup, val in flat_config.items():\n        env_val = os.environ.get(\n            # Generate a valid environment variable with nesting indicated with '_'\n            to_envvar(\"PREFECT_LOGGING_\" + \"_\".join(key_tup)).upper()\n        )\n        if env_val:\n            val = env_val\n\n        # reassign the updated value\n        flat_config[key_tup] = val\n\n    return flatdict_to_dict(flat_config)\n</code></pre>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/configuration/#prefect.logging.configuration.setup_logging","title":"<code>setup_logging</code>","text":"<p>Sets up logging.</p> <p>Returns the config used.</p> Source code in <code>prefect/logging/configuration.py</code> <pre><code>def setup_logging(incremental: Optional[bool] = None) -&gt; dict:\n    \"\"\"\n    Sets up logging.\n\n    Returns the config used.\n    \"\"\"\n    global PROCESS_LOGGING_CONFIG\n\n    # If the user has specified a logging path and it exists we will ignore the\n    # default entirely rather than dealing with complex merging\n    config = load_logging_config(\n        (\n            PREFECT_LOGGING_SETTINGS_PATH.value()\n            if PREFECT_LOGGING_SETTINGS_PATH.value().exists()\n            else DEFAULT_LOGGING_SETTINGS_PATH\n        )\n    )\n\n    incremental = (\n        incremental if incremental is not None else bool(PROCESS_LOGGING_CONFIG)\n    )\n\n    # Perform an incremental update if setup has already been run\n    config.setdefault(\"incremental\", incremental)\n\n    try:\n        logging.config.dictConfig(config)\n    except ValueError:\n        if incremental:\n            setup_logging(incremental=False)\n\n    # Copy configuration of the 'prefect.extra' logger to the extra loggers\n    extra_config = logging.getLogger(\"prefect.extra\")\n\n    for logger_name in PREFECT_LOGGING_EXTRA_LOGGERS.value():\n        logger = logging.getLogger(logger_name)\n        for handler in extra_config.handlers:\n            if not config[\"incremental\"]:\n                logger.addHandler(handler)\n            if logger.level == logging.NOTSET:\n                logger.setLevel(extra_config.level)\n            logger.propagate = extra_config.propagate\n\n    PROCESS_LOGGING_CONFIG = config\n\n    return config\n</code></pre>","tags":["Python API","logging"]},{"location":"api-ref/prefect/logging/formatters/","title":"formatters","text":"<p>\"\"\"</p>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters","title":"<code>prefect.logging.formatters</code>","text":"","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters.JsonFormatter","title":"<code>JsonFormatter</code>","text":"<p>               Bases: <code>Formatter</code></p> <p>Formats log records as a JSON string.</p> <p>The format may be specified as \"pretty\" to format the JSON with indents and newlines.</p> Source code in <code>prefect/logging/formatters.py</code> <pre><code>class JsonFormatter(logging.Formatter):\n    \"\"\"\n    Formats log records as a JSON string.\n\n    The format may be specified as \"pretty\" to format the JSON with indents and\n    newlines.\n    \"\"\"\n\n    def __init__(self, fmt, dmft, style) -&gt; None:  # noqa\n        super().__init__()\n\n        if fmt not in [\"pretty\", \"default\"]:\n            raise ValueError(\"Format must be either 'pretty' or 'default'.\")\n\n        self.serializer = JSONSerializer(\n            jsonlib=\"orjson\",\n            object_encoder=\"pydantic.json.pydantic_encoder\",\n            dumps_kwargs={\"option\": orjson.OPT_INDENT_2} if fmt == \"pretty\" else {},\n        )\n\n    def format(self, record: logging.LogRecord) -&gt; str:\n        record_dict = record.__dict__.copy()\n\n        # GCP severity detection compatibility\n        record_dict.setdefault(\"severity\", record.levelname)\n\n        # replace any exception tuples returned by `sys.exc_info()`\n        # with a JSON-serializable `dict`.\n        if record.exc_info:\n            record_dict[\"exc_info\"] = format_exception_info(record.exc_info)\n\n        log_json_bytes = self.serializer.dumps(record_dict)\n\n        # JSONSerializer returns bytes; decode to string to conform to\n        # the `logging.Formatter.format` interface\n        return log_json_bytes.decode()\n</code></pre>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/formatters/#prefect.logging.formatters.PrefectFormatter","title":"<code>PrefectFormatter</code>","text":"<p>               Bases: <code>Formatter</code></p> Source code in <code>prefect/logging/formatters.py</code> <pre><code>class PrefectFormatter(logging.Formatter):\n    def __init__(\n        self,\n        format=None,\n        datefmt=None,\n        style=\"%\",\n        validate=True,\n        *,\n        defaults=None,\n        task_run_fmt: str = None,\n        flow_run_fmt: str = None,\n    ) -&gt; None:\n        \"\"\"\n        Implementation of the standard Python formatter with support for multiple\n        message formats.\n\n        \"\"\"\n        # See https://github.com/python/cpython/blob/c8c6113398ee9a7867fe9b08bc539cceb61e2aaa/Lib/logging/__init__.py#L546\n        # for implementation details\n\n        init_kwargs = {}\n        style_kwargs = {}\n\n        # defaults added in 3.10\n        if sys.version_info &gt;= (3, 10):\n            init_kwargs[\"defaults\"] = defaults\n            style_kwargs[\"defaults\"] = defaults\n\n        # validate added in 3.8\n        init_kwargs[\"validate\"] = validate\n\n        super().__init__(format, datefmt, style, **init_kwargs)\n\n        self.flow_run_fmt = flow_run_fmt\n        self.task_run_fmt = task_run_fmt\n\n        # Retrieve the style class from the base class to avoid importing private\n        # `_STYLES` mapping\n        style_class = type(self._style)\n\n        self._flow_run_style = (\n            style_class(flow_run_fmt, **style_kwargs) if flow_run_fmt else self._style\n        )\n        self._task_run_style = (\n            style_class(task_run_fmt, **style_kwargs) if task_run_fmt else self._style\n        )\n        if validate:\n            self._flow_run_style.validate()\n            self._task_run_style.validate()\n\n    def formatMessage(self, record: logging.LogRecord):\n        if record.name == \"prefect.flow_runs\":\n            style = self._flow_run_style\n        elif record.name == \"prefect.task_runs\":\n            style = self._task_run_style\n        else:\n            style = self._style\n\n        return style.format(record)\n</code></pre>","tags":["Python API","logging","formatters"]},{"location":"api-ref/prefect/logging/handlers/","title":"handlers","text":"<p>\"\"\"</p>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers","title":"<code>prefect.logging.handlers</code>","text":"","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler","title":"<code>APILogHandler</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A logging handler that sends logs to the Prefect API.</p> <p>Sends log records to the <code>APILogWorker</code> which manages sending batches of logs in the background.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>class APILogHandler(logging.Handler):\n    \"\"\"\n    A logging handler that sends logs to the Prefect API.\n\n    Sends log records to the `APILogWorker` which manages sending batches of logs in\n    the background.\n    \"\"\"\n\n    @classmethod\n    def flush(cls):\n        \"\"\"\n        Tell the `APILogWorker` to send any currently enqueued logs and block until\n        completion.\n\n        Use `aflush` from async contexts instead.\n        \"\"\"\n        loop = get_running_loop()\n        if loop:\n            if in_global_loop():  # Guard against internal misuse\n                raise RuntimeError(\n                    \"Cannot call `APILogWorker.flush` from the global event loop; it\"\n                    \" would block the event loop and cause a deadlock. Use\"\n                    \" `APILogWorker.aflush` instead.\"\n                )\n\n            # Not ideal, but this method is called by the stdlib and cannot return a\n            # coroutine so we just schedule the drain in a new thread and continue\n            from_sync.call_soon_in_new_thread(create_call(APILogWorker.drain_all))\n            return None\n        else:\n            # We set a timeout of 5s because we don't want to block forever if the worker\n            # is stuck. This can occur when the handler is being shutdown and the\n            # `logging._lock` is held but the worker is attempting to emit logs resulting\n            # in a deadlock.\n            return APILogWorker.drain_all(timeout=5)\n\n    @classmethod\n    def aflush(cls):\n        \"\"\"\n        Tell the `APILogWorker` to send any currently enqueued logs and block until\n        completion.\n\n        If called in a synchronous context, will only block up to 5s before returning.\n        \"\"\"\n\n        if not get_running_loop():\n            raise RuntimeError(\n                \"`aflush` cannot be used from a synchronous context; use `flush`\"\n                \" instead.\"\n            )\n\n        return APILogWorker.drain_all()\n\n    def emit(self, record: logging.LogRecord):\n        \"\"\"\n        Send a log to the `APILogWorker`\n        \"\"\"\n        try:\n            profile = prefect.context.get_settings_context()\n\n            if not PREFECT_LOGGING_TO_API_ENABLED.value_from(profile.settings):\n                return  # Respect the global settings toggle\n            if not getattr(record, \"send_to_api\", True):\n                return  # Do not send records that have opted out\n            if not getattr(record, \"send_to_orion\", True):\n                return  # Backwards compatibility\n\n            log = self.prepare(record)\n            APILogWorker.instance().send(log)\n\n        except Exception:\n            self.handleError(record)\n\n    def handleError(self, record: logging.LogRecord) -&gt; None:\n        _, exc, _ = sys.exc_info()\n\n        if isinstance(exc, MissingContextError):\n            log_handling_when_missing_flow = (\n                PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW.value()\n            )\n            if log_handling_when_missing_flow == \"warn\":\n                # Warn when a logger is used outside of a run context, the stack level here\n                # gets us to the user logging call\n                warnings.warn(str(exc), stacklevel=8)\n                return\n            elif log_handling_when_missing_flow == \"ignore\":\n                return\n            else:\n                raise exc\n\n        # Display a longer traceback for other errors\n        return super().handleError(record)\n\n    def prepare(self, record: logging.LogRecord) -&gt; Dict[str, Any]:\n        \"\"\"\n        Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.\n\n        This infers the linked flow or task run from the log record or the current\n        run context.\n\n        If a flow run id cannot be found, the log will be dropped.\n\n        Logs exceeding the maximum size will be dropped.\n        \"\"\"\n        flow_run_id = getattr(record, \"flow_run_id\", None)\n        task_run_id = getattr(record, \"task_run_id\", None)\n\n        if not flow_run_id:\n            try:\n                context = prefect.context.get_run_context()\n            except MissingContextError:\n                raise MissingContextError(\n                    f\"Logger {record.name!r} attempted to send logs to the API without\"\n                    \" a flow run id. The API log handler can only send logs within\"\n                    \" flow run contexts unless the flow run id is manually provided.\"\n                ) from None\n\n            if hasattr(context, \"flow_run\"):\n                flow_run_id = context.flow_run.id\n            elif hasattr(context, \"task_run\"):\n                flow_run_id = context.task_run.flow_run_id\n                task_run_id = task_run_id or context.task_run.id\n            else:\n                raise ValueError(\n                    \"Encountered malformed run context. Does not contain flow or task \"\n                    \"run information.\"\n                )\n\n        # Parsing to a `LogCreate` object here gives us nice parsing error messages\n        # from the standard lib `handleError` method if something goes wrong and\n        # prevents malformed logs from entering the queue\n        try:\n            is_uuid_like = isinstance(flow_run_id, uuid.UUID) or (\n                isinstance(flow_run_id, str) and uuid.UUID(flow_run_id)\n            )\n        except ValueError:\n            is_uuid_like = False\n\n        log = LogCreate(\n            flow_run_id=flow_run_id if is_uuid_like else None,\n            task_run_id=task_run_id,\n            name=record.name,\n            level=record.levelno,\n            timestamp=pendulum.from_timestamp(\n                getattr(record, \"created\", None) or time.time()\n            ),\n            message=self.format(record),\n        ).dict(json_compatible=True)\n\n        log_size = log[\"__payload_size__\"] = self._get_payload_size(log)\n        if log_size &gt; PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value():\n            raise ValueError(\n                f\"Log of size {log_size} is greater than the max size of \"\n                f\"{PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value()}\"\n            )\n\n        return log\n\n    def _get_payload_size(self, log: Dict[str, Any]) -&gt; int:\n        return len(json.dumps(log).encode())\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.aflush","title":"<code>aflush</code>  <code>classmethod</code>","text":"<p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until completion.</p> <p>If called in a synchronous context, will only block up to 5s before returning.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>@classmethod\ndef aflush(cls):\n    \"\"\"\n    Tell the `APILogWorker` to send any currently enqueued logs and block until\n    completion.\n\n    If called in a synchronous context, will only block up to 5s before returning.\n    \"\"\"\n\n    if not get_running_loop():\n        raise RuntimeError(\n            \"`aflush` cannot be used from a synchronous context; use `flush`\"\n            \" instead.\"\n        )\n\n    return APILogWorker.drain_all()\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.emit","title":"<code>emit</code>","text":"<p>Send a log to the <code>APILogWorker</code></p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>def emit(self, record: logging.LogRecord):\n    \"\"\"\n    Send a log to the `APILogWorker`\n    \"\"\"\n    try:\n        profile = prefect.context.get_settings_context()\n\n        if not PREFECT_LOGGING_TO_API_ENABLED.value_from(profile.settings):\n            return  # Respect the global settings toggle\n        if not getattr(record, \"send_to_api\", True):\n            return  # Do not send records that have opted out\n        if not getattr(record, \"send_to_orion\", True):\n            return  # Backwards compatibility\n\n        log = self.prepare(record)\n        APILogWorker.instance().send(log)\n\n    except Exception:\n        self.handleError(record)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.flush","title":"<code>flush</code>  <code>classmethod</code>","text":"<p>Tell the <code>APILogWorker</code> to send any currently enqueued logs and block until completion.</p> <p>Use <code>aflush</code> from async contexts instead.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>@classmethod\ndef flush(cls):\n    \"\"\"\n    Tell the `APILogWorker` to send any currently enqueued logs and block until\n    completion.\n\n    Use `aflush` from async contexts instead.\n    \"\"\"\n    loop = get_running_loop()\n    if loop:\n        if in_global_loop():  # Guard against internal misuse\n            raise RuntimeError(\n                \"Cannot call `APILogWorker.flush` from the global event loop; it\"\n                \" would block the event loop and cause a deadlock. Use\"\n                \" `APILogWorker.aflush` instead.\"\n            )\n\n        # Not ideal, but this method is called by the stdlib and cannot return a\n        # coroutine so we just schedule the drain in a new thread and continue\n        from_sync.call_soon_in_new_thread(create_call(APILogWorker.drain_all))\n        return None\n    else:\n        # We set a timeout of 5s because we don't want to block forever if the worker\n        # is stuck. This can occur when the handler is being shutdown and the\n        # `logging._lock` is held but the worker is attempting to emit logs resulting\n        # in a deadlock.\n        return APILogWorker.drain_all(timeout=5)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.APILogHandler.prepare","title":"<code>prepare</code>","text":"<p>Convert a <code>logging.LogRecord</code> to the API <code>LogCreate</code> schema and serialize.</p> <p>This infers the linked flow or task run from the log record or the current run context.</p> <p>If a flow run id cannot be found, the log will be dropped.</p> <p>Logs exceeding the maximum size will be dropped.</p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>def prepare(self, record: logging.LogRecord) -&gt; Dict[str, Any]:\n    \"\"\"\n    Convert a `logging.LogRecord` to the API `LogCreate` schema and serialize.\n\n    This infers the linked flow or task run from the log record or the current\n    run context.\n\n    If a flow run id cannot be found, the log will be dropped.\n\n    Logs exceeding the maximum size will be dropped.\n    \"\"\"\n    flow_run_id = getattr(record, \"flow_run_id\", None)\n    task_run_id = getattr(record, \"task_run_id\", None)\n\n    if not flow_run_id:\n        try:\n            context = prefect.context.get_run_context()\n        except MissingContextError:\n            raise MissingContextError(\n                f\"Logger {record.name!r} attempted to send logs to the API without\"\n                \" a flow run id. The API log handler can only send logs within\"\n                \" flow run contexts unless the flow run id is manually provided.\"\n            ) from None\n\n        if hasattr(context, \"flow_run\"):\n            flow_run_id = context.flow_run.id\n        elif hasattr(context, \"task_run\"):\n            flow_run_id = context.task_run.flow_run_id\n            task_run_id = task_run_id or context.task_run.id\n        else:\n            raise ValueError(\n                \"Encountered malformed run context. Does not contain flow or task \"\n                \"run information.\"\n            )\n\n    # Parsing to a `LogCreate` object here gives us nice parsing error messages\n    # from the standard lib `handleError` method if something goes wrong and\n    # prevents malformed logs from entering the queue\n    try:\n        is_uuid_like = isinstance(flow_run_id, uuid.UUID) or (\n            isinstance(flow_run_id, str) and uuid.UUID(flow_run_id)\n        )\n    except ValueError:\n        is_uuid_like = False\n\n    log = LogCreate(\n        flow_run_id=flow_run_id if is_uuid_like else None,\n        task_run_id=task_run_id,\n        name=record.name,\n        level=record.levelno,\n        timestamp=pendulum.from_timestamp(\n            getattr(record, \"created\", None) or time.time()\n        ),\n        message=self.format(record),\n    ).dict(json_compatible=True)\n\n    log_size = log[\"__payload_size__\"] = self._get_payload_size(log)\n    if log_size &gt; PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value():\n        raise ValueError(\n            f\"Log of size {log_size} is greater than the max size of \"\n            f\"{PREFECT_LOGGING_TO_API_MAX_LOG_SIZE.value()}\"\n        )\n\n    return log\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/handlers/#prefect.logging.handlers.PrefectConsoleHandler","title":"<code>PrefectConsoleHandler</code>","text":"<p>               Bases: <code>StreamHandler</code></p> Source code in <code>prefect/logging/handlers.py</code> <pre><code>class PrefectConsoleHandler(logging.StreamHandler):\n    def __init__(\n        self,\n        stream=None,\n        highlighter: Highlighter = PrefectConsoleHighlighter,\n        styles: Dict[str, str] = None,\n        level: Union[int, str] = logging.NOTSET,\n    ):\n        \"\"\"\n        The default console handler for Prefect, which highlights log levels,\n        web and file URLs, flow and task (run) names, and state types in the\n        local console (terminal).\n\n        Highlighting can be toggled on/off with the PREFECT_LOGGING_COLORS setting.\n        For finer control, use logging.yml to add or remove styles, and/or\n        adjust colors.\n        \"\"\"\n        super().__init__(stream=stream)\n\n        styled_console = PREFECT_LOGGING_COLORS.value()\n        markup_console = PREFECT_LOGGING_MARKUP.value()\n        if styled_console:\n            highlighter = highlighter()\n            theme = Theme(styles, inherit=False)\n        else:\n            highlighter = NullHighlighter()\n            theme = Theme(inherit=False)\n\n        self.level = level\n        self.console = Console(\n            highlighter=highlighter,\n            theme=theme,\n            file=self.stream,\n            markup=markup_console,\n        )\n\n    def emit(self, record: logging.LogRecord):\n        try:\n            message = self.format(record)\n            self.console.print(message, soft_wrap=True)\n        except RecursionError:\n            # This was copied over from logging.StreamHandler().emit()\n            # https://bugs.python.org/issue36272\n            raise\n        except Exception:\n            self.handleError(record)\n</code></pre>","tags":["Python API","logging","handlers"]},{"location":"api-ref/prefect/logging/highlighters/","title":"highlighters","text":"<p>\"\"\"</p>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers","title":"<code>prefect.logging.loggers</code>","text":"","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper","title":"<code>LogEavesdropper</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A context manager that collects logs for the duration of the context</p> <pre><code>Example:\n\n    ```python\n    import logging\n    from prefect.logging import LogEavesdropper\n\n    with LogEavesdropper(\"my_logger\") as eavesdropper:\n        logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n        logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n    print(eavesdropper.text())\n\n    # Outputs: \"Hello, world!\n</code></pre> <p>Another one!\"</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class LogEavesdropper(logging.Handler):\n    \"\"\"A context manager that collects logs for the duration of the context\n\n    Example:\n\n        ```python\n        import logging\n        from prefect.logging import LogEavesdropper\n\n        with LogEavesdropper(\"my_logger\") as eavesdropper:\n            logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n            logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n        print(eavesdropper.text())\n\n        # Outputs: \"Hello, world!\\nAnother one!\"\n    \"\"\"\n\n    _target_logger: logging.Logger\n    _lines: List[str]\n\n    def __init__(self, eavesdrop_on: str, level: int = logging.NOTSET):\n        \"\"\"\n        Args:\n            eavesdrop_on (str): the name of the logger to eavesdrop on\n            level (int): the minimum log level to eavesdrop on; if omitted, all levels\n                are captured\n        \"\"\"\n\n        super().__init__(level=level)\n        self.eavesdrop_on = eavesdrop_on\n        self._target_logger = None\n\n        # It's important that we use a very minimalistic formatter for use cases where\n        # we may present these logs back to the user.  We shouldn't leak filenames,\n        # versions, or other environmental information.\n        self.formatter = logging.Formatter(\"[%(levelname)s]: %(message)s\")\n\n    def __enter__(self) -&gt; Self:\n        self._target_logger = logging.getLogger(self.eavesdrop_on)\n        self._original_level = self._target_logger.level\n        self._target_logger.level = self.level\n        self._target_logger.addHandler(self)\n        self._lines = []\n        return self\n\n    def __exit__(self, *_):\n        if self._target_logger:\n            self._target_logger.removeHandler(self)\n            self._target_logger.level = self._original_level\n\n    def emit(self, record: LogRecord) -&gt; None:\n        \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n        self._lines.append(self.format(record))\n\n    def text(self) -&gt; str:\n        \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n        return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper.emit","title":"<code>emit</code>","text":"<p>The logging.Handler implementation, not intended to be called directly.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def emit(self, record: LogRecord) -&gt; None:\n    \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n    self._lines.append(self.format(record))\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.LogEavesdropper.text","title":"<code>text</code>","text":"<p>Return the collected logs as a single newline-delimited string</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def text(self) -&gt; str:\n    \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n    return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.PrefectLogAdapter","title":"<code>PrefectLogAdapter</code>","text":"<p>               Bases: <code>LoggerAdapter</code></p> <p>Adapter that ensures extra kwargs are passed through correctly; without this the <code>extra</code> fields set on the adapter would overshadow any provided on a log-by-log basis.</p> <p>See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is not a bug in the LoggingAdapter and subclassing is the intended workaround.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class PrefectLogAdapter(logging.LoggerAdapter):\n    \"\"\"\n    Adapter that ensures extra kwargs are passed through correctly; without this\n    the `extra` fields set on the adapter would overshadow any provided on a\n    log-by-log basis.\n\n    See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is\n    not a bug in the LoggingAdapter and subclassing is the intended workaround.\n    \"\"\"\n\n    def process(self, msg, kwargs):\n        kwargs[\"extra\"] = {**(self.extra or {}), **(kwargs.get(\"extra\") or {})}\n\n        from prefect._internal.compatibility.deprecated import (\n            PrefectDeprecationWarning,\n            generate_deprecation_message,\n        )\n\n        if \"send_to_orion\" in kwargs[\"extra\"]:\n            warnings.warn(\n                generate_deprecation_message(\n                    'The \"send_to_orion\" option',\n                    start_date=\"May 2023\",\n                    help='Use \"send_to_api\" instead.',\n                ),\n                PrefectDeprecationWarning,\n                stacklevel=4,\n            )\n\n        return (msg, kwargs)\n\n    def getChild(\n        self, suffix: str, extra: Optional[Dict[str, str]] = None\n    ) -&gt; \"PrefectLogAdapter\":\n        if extra is None:\n            extra = {}\n\n        return PrefectLogAdapter(\n            self.logger.getChild(suffix),\n            extra={\n                **self.extra,\n                **extra,\n            },\n        )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.disable_logger","title":"<code>disable_logger</code>","text":"<p>Get a logger by name and disables it within the context manager. Upon exiting the context manager, the logger is returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_logger(name: str):\n    \"\"\"\n    Get a logger by name and disables it within the context manager.\n    Upon exiting the context manager, the logger is returned to its\n    original state.\n    \"\"\"\n    logger = logging.getLogger(name=name)\n\n    # determine if it's already disabled\n    base_state = logger.disabled\n    try:\n        # disable the logger\n        logger.disabled = True\n        yield\n    finally:\n        # return to base state\n        logger.disabled = base_state\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.disable_run_logger","title":"<code>disable_run_logger</code>","text":"<p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them within the context manager. Upon exiting the context manager, both loggers are returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_run_logger():\n    \"\"\"\n    Gets both `prefect.flow_run` and `prefect.task_run` and disables them\n    within the context manager. Upon exiting the context manager, both loggers\n    are returned to its original state.\n    \"\"\"\n    with disable_logger(\"prefect.flow_run\"), disable_logger(\"prefect.task_run\"):\n        yield\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.flow_run_logger","title":"<code>flow_run_logger</code>","text":"<p>Create a flow run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def flow_run_logger(\n    flow_run: Union[\"FlowRun\", \"ClientFlowRun\"],\n    flow: Optional[\"Flow\"] = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a flow run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the flow run context is available, see `get_run_logger` instead.\n    \"\"\"\n    return PrefectLogAdapter(\n        get_logger(\"prefect.flow_runs\"),\n        extra={\n            **{\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_run_id\": str(flow_run.id) if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.get_logger","title":"<code>get_logger</code>  <code>cached</code>","text":"<p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the <code>prefect</code> package.</p> <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs. By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@lru_cache()\ndef get_logger(name: str = None) -&gt; logging.Logger:\n    \"\"\"\n    Get a `prefect` logger. These loggers are intended for internal use within the\n    `prefect` package.\n\n    See `get_run_logger` for retrieving loggers for use within task or flow runs.\n    By default, only run-related loggers are connected to the `APILogHandler`.\n    \"\"\"\n    parent_logger = logging.getLogger(\"prefect\")\n\n    if name:\n        # Append the name if given but allow explicit full names e.g. \"prefect.test\"\n        # should not become \"prefect.prefect.test\"\n        if not name.startswith(parent_logger.name + \".\"):\n            logger = parent_logger.getChild(name)\n        else:\n            logger = logging.getLogger(name)\n    else:\n        logger = parent_logger\n\n    # Prevent the current API key from being logged in plain text\n    obfuscate_api_key_filter = ObfuscateApiKeyFilter()\n    logger.addFilter(obfuscate_api_key_filter)\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.get_run_logger","title":"<code>get_run_logger</code>","text":"<p>Get a Prefect logger for the current task run or flow run.</p> <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>. Contextual data about the run will be attached to the log records.</p> <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to the API.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>RunContext</code> <p>A specific context may be provided as an override. By default, the context is inferred from global state and this should not be needed.</p> <code>None</code> <code>**kwargs</code> <code>str</code> <p>Additional keyword arguments will be attached to the log records in addition to the run metadata</p> <code>{}</code> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no context can be found</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def get_run_logger(\n    context: \"RunContext\" = None, **kwargs: str\n) -&gt; Union[logging.Logger, logging.LoggerAdapter]:\n    \"\"\"\n    Get a Prefect logger for the current task run or flow run.\n\n    The logger will be named either `prefect.task_runs` or `prefect.flow_runs`.\n    Contextual data about the run will be attached to the log records.\n\n    These loggers are connected to the `APILogHandler` by default to send log records to\n    the API.\n\n    Arguments:\n        context: A specific context may be provided as an override. By default, the\n            context is inferred from global state and this should not be needed.\n        **kwargs: Additional keyword arguments will be attached to the log records in\n            addition to the run metadata\n\n    Raises:\n        RuntimeError: If no context can be found\n    \"\"\"\n    # Check for existing contexts\n    task_run_context = prefect.context.TaskRunContext.get()\n    flow_run_context = prefect.context.FlowRunContext.get()\n\n    # Apply the context override\n    if context:\n        if isinstance(context, prefect.context.FlowRunContext):\n            flow_run_context = context\n        elif isinstance(context, prefect.context.TaskRunContext):\n            task_run_context = context\n        else:\n            raise TypeError(\n                f\"Received unexpected type {type(context).__name__!r} for context. \"\n                \"Expected one of 'None', 'FlowRunContext', or 'TaskRunContext'.\"\n            )\n\n    # Determine if this is a task or flow run logger\n    if task_run_context:\n        logger = task_run_logger(\n            task_run=task_run_context.task_run,\n            task=task_run_context.task,\n            flow_run=flow_run_context.flow_run if flow_run_context else None,\n            flow=flow_run_context.flow if flow_run_context else None,\n            **kwargs,\n        )\n    elif flow_run_context:\n        logger = flow_run_logger(\n            flow_run=flow_run_context.flow_run, flow=flow_run_context.flow, **kwargs\n        )\n    elif (\n        get_logger(\"prefect.flow_run\").disabled\n        and get_logger(\"prefect.task_run\").disabled\n    ):\n        logger = logging.getLogger(\"null\")\n    else:\n        raise MissingContextError(\"There is no active flow or task run context.\")\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.patch_print","title":"<code>patch_print</code>","text":"<p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef patch_print():\n    \"\"\"\n    Patches the Python builtin `print` method to use `print_as_log`\n    \"\"\"\n    import builtins\n\n    original = builtins.print\n\n    try:\n        builtins.print = print_as_log\n        yield\n    finally:\n        builtins.print = original\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.print_as_log","title":"<code>print_as_log</code>","text":"<p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p> <p>If no run is active, <code>print</code> will behave as if it were not patched.</p> <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will not be forwarded to the Prefect logger either.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def print_as_log(*args, **kwargs):\n    \"\"\"\n    A patch for `print` to send printed messages to the Prefect run logger.\n\n    If no run is active, `print` will behave as if it were not patched.\n\n    If `print` sends data to a file other than `sys.stdout` or `sys.stderr`, it will\n    not be forwarded to the Prefect logger either.\n    \"\"\"\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    context = TaskRunContext.get() or FlowRunContext.get()\n    if (\n        not context\n        or not context.log_prints\n        or kwargs.get(\"file\") not in {None, sys.stdout, sys.stderr}\n    ):\n        return print(*args, **kwargs)\n\n    logger = get_run_logger()\n\n    # Print to an in-memory buffer; so we do not need to implement `print`\n    buffer = io.StringIO()\n    kwargs[\"file\"] = buffer\n    print(*args, **kwargs)\n\n    # Remove trailing whitespace to prevent duplicates\n    logger.info(buffer.getvalue().rstrip())\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/highlighters/#prefect.logging.loggers.task_run_logger","title":"<code>task_run_logger</code>","text":"<p>Create a task run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the task run context is available, see <code>get_run_logger</code> instead.</p> <p>If only the flow run context is available, it will be used for default values of <code>flow_run</code> and <code>flow</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def task_run_logger(\n    task_run: \"TaskRun\",\n    task: \"Task\" = None,\n    flow_run: \"FlowRun\" = None,\n    flow: \"Flow\" = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a task run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the task run context is available, see `get_run_logger` instead.\n\n    If only the flow run context is available, it will be used for default values\n    of `flow_run` and `flow`.\n    \"\"\"\n    if not flow_run or not flow:\n        flow_run_context = prefect.context.FlowRunContext.get()\n        if flow_run_context:\n            flow_run = flow_run or flow_run_context.flow_run\n            flow = flow or flow_run_context.flow\n\n    return PrefectLogAdapter(\n        get_logger(\"prefect.task_runs\"),\n        extra={\n            **{\n                \"task_run_id\": str(task_run.id),\n                \"flow_run_id\": str(task_run.flow_run_id),\n                \"task_run_name\": task_run.name,\n                \"task_name\": task.name if task else \"&lt;unknown&gt;\",\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/","title":"loggers","text":"<p>\"\"\"</p>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers","title":"<code>prefect.logging.loggers</code>","text":"","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper","title":"<code>LogEavesdropper</code>","text":"<p>               Bases: <code>Handler</code></p> <p>A context manager that collects logs for the duration of the context</p> <pre><code>Example:\n\n    ```python\n    import logging\n    from prefect.logging import LogEavesdropper\n\n    with LogEavesdropper(\"my_logger\") as eavesdropper:\n        logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n        logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n    print(eavesdropper.text())\n\n    # Outputs: \"Hello, world!\n</code></pre> <p>Another one!\"</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class LogEavesdropper(logging.Handler):\n    \"\"\"A context manager that collects logs for the duration of the context\n\n    Example:\n\n        ```python\n        import logging\n        from prefect.logging import LogEavesdropper\n\n        with LogEavesdropper(\"my_logger\") as eavesdropper:\n            logging.getLogger(\"my_logger\").info(\"Hello, world!\")\n            logging.getLogger(\"my_logger.child_module\").info(\"Another one!\")\n\n        print(eavesdropper.text())\n\n        # Outputs: \"Hello, world!\\nAnother one!\"\n    \"\"\"\n\n    _target_logger: logging.Logger\n    _lines: List[str]\n\n    def __init__(self, eavesdrop_on: str, level: int = logging.NOTSET):\n        \"\"\"\n        Args:\n            eavesdrop_on (str): the name of the logger to eavesdrop on\n            level (int): the minimum log level to eavesdrop on; if omitted, all levels\n                are captured\n        \"\"\"\n\n        super().__init__(level=level)\n        self.eavesdrop_on = eavesdrop_on\n        self._target_logger = None\n\n        # It's important that we use a very minimalistic formatter for use cases where\n        # we may present these logs back to the user.  We shouldn't leak filenames,\n        # versions, or other environmental information.\n        self.formatter = logging.Formatter(\"[%(levelname)s]: %(message)s\")\n\n    def __enter__(self) -&gt; Self:\n        self._target_logger = logging.getLogger(self.eavesdrop_on)\n        self._original_level = self._target_logger.level\n        self._target_logger.level = self.level\n        self._target_logger.addHandler(self)\n        self._lines = []\n        return self\n\n    def __exit__(self, *_):\n        if self._target_logger:\n            self._target_logger.removeHandler(self)\n            self._target_logger.level = self._original_level\n\n    def emit(self, record: LogRecord) -&gt; None:\n        \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n        self._lines.append(self.format(record))\n\n    def text(self) -&gt; str:\n        \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n        return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper.emit","title":"<code>emit</code>","text":"<p>The logging.Handler implementation, not intended to be called directly.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def emit(self, record: LogRecord) -&gt; None:\n    \"\"\"The logging.Handler implementation, not intended to be called directly.\"\"\"\n    self._lines.append(self.format(record))\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.LogEavesdropper.text","title":"<code>text</code>","text":"<p>Return the collected logs as a single newline-delimited string</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def text(self) -&gt; str:\n    \"\"\"Return the collected logs as a single newline-delimited string\"\"\"\n    return \"\\n\".join(self._lines)\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.PrefectLogAdapter","title":"<code>PrefectLogAdapter</code>","text":"<p>               Bases: <code>LoggerAdapter</code></p> <p>Adapter that ensures extra kwargs are passed through correctly; without this the <code>extra</code> fields set on the adapter would overshadow any provided on a log-by-log basis.</p> <p>See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is not a bug in the LoggingAdapter and subclassing is the intended workaround.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>class PrefectLogAdapter(logging.LoggerAdapter):\n    \"\"\"\n    Adapter that ensures extra kwargs are passed through correctly; without this\n    the `extra` fields set on the adapter would overshadow any provided on a\n    log-by-log basis.\n\n    See https://bugs.python.org/issue32732 \u2014 the Python team has declared that this is\n    not a bug in the LoggingAdapter and subclassing is the intended workaround.\n    \"\"\"\n\n    def process(self, msg, kwargs):\n        kwargs[\"extra\"] = {**(self.extra or {}), **(kwargs.get(\"extra\") or {})}\n\n        from prefect._internal.compatibility.deprecated import (\n            PrefectDeprecationWarning,\n            generate_deprecation_message,\n        )\n\n        if \"send_to_orion\" in kwargs[\"extra\"]:\n            warnings.warn(\n                generate_deprecation_message(\n                    'The \"send_to_orion\" option',\n                    start_date=\"May 2023\",\n                    help='Use \"send_to_api\" instead.',\n                ),\n                PrefectDeprecationWarning,\n                stacklevel=4,\n            )\n\n        return (msg, kwargs)\n\n    def getChild(\n        self, suffix: str, extra: Optional[Dict[str, str]] = None\n    ) -&gt; \"PrefectLogAdapter\":\n        if extra is None:\n            extra = {}\n\n        return PrefectLogAdapter(\n            self.logger.getChild(suffix),\n            extra={\n                **self.extra,\n                **extra,\n            },\n        )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.disable_logger","title":"<code>disable_logger</code>","text":"<p>Get a logger by name and disables it within the context manager. Upon exiting the context manager, the logger is returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_logger(name: str):\n    \"\"\"\n    Get a logger by name and disables it within the context manager.\n    Upon exiting the context manager, the logger is returned to its\n    original state.\n    \"\"\"\n    logger = logging.getLogger(name=name)\n\n    # determine if it's already disabled\n    base_state = logger.disabled\n    try:\n        # disable the logger\n        logger.disabled = True\n        yield\n    finally:\n        # return to base state\n        logger.disabled = base_state\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.disable_run_logger","title":"<code>disable_run_logger</code>","text":"<p>Gets both <code>prefect.flow_run</code> and <code>prefect.task_run</code> and disables them within the context manager. Upon exiting the context manager, both loggers are returned to its original state.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef disable_run_logger():\n    \"\"\"\n    Gets both `prefect.flow_run` and `prefect.task_run` and disables them\n    within the context manager. Upon exiting the context manager, both loggers\n    are returned to its original state.\n    \"\"\"\n    with disable_logger(\"prefect.flow_run\"), disable_logger(\"prefect.task_run\"):\n        yield\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.flow_run_logger","title":"<code>flow_run_logger</code>","text":"<p>Create a flow run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the flow run context is available, see <code>get_run_logger</code> instead.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def flow_run_logger(\n    flow_run: Union[\"FlowRun\", \"ClientFlowRun\"],\n    flow: Optional[\"Flow\"] = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a flow run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the flow run context is available, see `get_run_logger` instead.\n    \"\"\"\n    return PrefectLogAdapter(\n        get_logger(\"prefect.flow_runs\"),\n        extra={\n            **{\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_run_id\": str(flow_run.id) if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.get_logger","title":"<code>get_logger</code>  <code>cached</code>","text":"<p>Get a <code>prefect</code> logger. These loggers are intended for internal use within the <code>prefect</code> package.</p> <p>See <code>get_run_logger</code> for retrieving loggers for use within task or flow runs. By default, only run-related loggers are connected to the <code>APILogHandler</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@lru_cache()\ndef get_logger(name: str = None) -&gt; logging.Logger:\n    \"\"\"\n    Get a `prefect` logger. These loggers are intended for internal use within the\n    `prefect` package.\n\n    See `get_run_logger` for retrieving loggers for use within task or flow runs.\n    By default, only run-related loggers are connected to the `APILogHandler`.\n    \"\"\"\n    parent_logger = logging.getLogger(\"prefect\")\n\n    if name:\n        # Append the name if given but allow explicit full names e.g. \"prefect.test\"\n        # should not become \"prefect.prefect.test\"\n        if not name.startswith(parent_logger.name + \".\"):\n            logger = parent_logger.getChild(name)\n        else:\n            logger = logging.getLogger(name)\n    else:\n        logger = parent_logger\n\n    # Prevent the current API key from being logged in plain text\n    obfuscate_api_key_filter = ObfuscateApiKeyFilter()\n    logger.addFilter(obfuscate_api_key_filter)\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.get_run_logger","title":"<code>get_run_logger</code>","text":"<p>Get a Prefect logger for the current task run or flow run.</p> <p>The logger will be named either <code>prefect.task_runs</code> or <code>prefect.flow_runs</code>. Contextual data about the run will be attached to the log records.</p> <p>These loggers are connected to the <code>APILogHandler</code> by default to send log records to the API.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>RunContext</code> <p>A specific context may be provided as an override. By default, the context is inferred from global state and this should not be needed.</p> <code>None</code> <code>**kwargs</code> <code>str</code> <p>Additional keyword arguments will be attached to the log records in addition to the run metadata</p> <code>{}</code> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If no context can be found</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def get_run_logger(\n    context: \"RunContext\" = None, **kwargs: str\n) -&gt; Union[logging.Logger, logging.LoggerAdapter]:\n    \"\"\"\n    Get a Prefect logger for the current task run or flow run.\n\n    The logger will be named either `prefect.task_runs` or `prefect.flow_runs`.\n    Contextual data about the run will be attached to the log records.\n\n    These loggers are connected to the `APILogHandler` by default to send log records to\n    the API.\n\n    Arguments:\n        context: A specific context may be provided as an override. By default, the\n            context is inferred from global state and this should not be needed.\n        **kwargs: Additional keyword arguments will be attached to the log records in\n            addition to the run metadata\n\n    Raises:\n        RuntimeError: If no context can be found\n    \"\"\"\n    # Check for existing contexts\n    task_run_context = prefect.context.TaskRunContext.get()\n    flow_run_context = prefect.context.FlowRunContext.get()\n\n    # Apply the context override\n    if context:\n        if isinstance(context, prefect.context.FlowRunContext):\n            flow_run_context = context\n        elif isinstance(context, prefect.context.TaskRunContext):\n            task_run_context = context\n        else:\n            raise TypeError(\n                f\"Received unexpected type {type(context).__name__!r} for context. \"\n                \"Expected one of 'None', 'FlowRunContext', or 'TaskRunContext'.\"\n            )\n\n    # Determine if this is a task or flow run logger\n    if task_run_context:\n        logger = task_run_logger(\n            task_run=task_run_context.task_run,\n            task=task_run_context.task,\n            flow_run=flow_run_context.flow_run if flow_run_context else None,\n            flow=flow_run_context.flow if flow_run_context else None,\n            **kwargs,\n        )\n    elif flow_run_context:\n        logger = flow_run_logger(\n            flow_run=flow_run_context.flow_run, flow=flow_run_context.flow, **kwargs\n        )\n    elif (\n        get_logger(\"prefect.flow_run\").disabled\n        and get_logger(\"prefect.task_run\").disabled\n    ):\n        logger = logging.getLogger(\"null\")\n    else:\n        raise MissingContextError(\"There is no active flow or task run context.\")\n\n    return logger\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.patch_print","title":"<code>patch_print</code>","text":"<p>Patches the Python builtin <code>print</code> method to use <code>print_as_log</code></p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>@contextmanager\ndef patch_print():\n    \"\"\"\n    Patches the Python builtin `print` method to use `print_as_log`\n    \"\"\"\n    import builtins\n\n    original = builtins.print\n\n    try:\n        builtins.print = print_as_log\n        yield\n    finally:\n        builtins.print = original\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.print_as_log","title":"<code>print_as_log</code>","text":"<p>A patch for <code>print</code> to send printed messages to the Prefect run logger.</p> <p>If no run is active, <code>print</code> will behave as if it were not patched.</p> <p>If <code>print</code> sends data to a file other than <code>sys.stdout</code> or <code>sys.stderr</code>, it will not be forwarded to the Prefect logger either.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def print_as_log(*args, **kwargs):\n    \"\"\"\n    A patch for `print` to send printed messages to the Prefect run logger.\n\n    If no run is active, `print` will behave as if it were not patched.\n\n    If `print` sends data to a file other than `sys.stdout` or `sys.stderr`, it will\n    not be forwarded to the Prefect logger either.\n    \"\"\"\n    from prefect.context import FlowRunContext, TaskRunContext\n\n    context = TaskRunContext.get() or FlowRunContext.get()\n    if (\n        not context\n        or not context.log_prints\n        or kwargs.get(\"file\") not in {None, sys.stdout, sys.stderr}\n    ):\n        return print(*args, **kwargs)\n\n    logger = get_run_logger()\n\n    # Print to an in-memory buffer; so we do not need to implement `print`\n    buffer = io.StringIO()\n    kwargs[\"file\"] = buffer\n    print(*args, **kwargs)\n\n    # Remove trailing whitespace to prevent duplicates\n    logger.info(buffer.getvalue().rstrip())\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/logging/loggers/#prefect.logging.loggers.task_run_logger","title":"<code>task_run_logger</code>","text":"<p>Create a task run logger with the run's metadata attached.</p> <p>Additional keyword arguments can be provided to attach custom data to the log records.</p> <p>If the task run context is available, see <code>get_run_logger</code> instead.</p> <p>If only the flow run context is available, it will be used for default values of <code>flow_run</code> and <code>flow</code>.</p> Source code in <code>prefect/logging/loggers.py</code> <pre><code>def task_run_logger(\n    task_run: \"TaskRun\",\n    task: \"Task\" = None,\n    flow_run: \"FlowRun\" = None,\n    flow: \"Flow\" = None,\n    **kwargs: str,\n):\n    \"\"\"\n    Create a task run logger with the run's metadata attached.\n\n    Additional keyword arguments can be provided to attach custom data to the log\n    records.\n\n    If the task run context is available, see `get_run_logger` instead.\n\n    If only the flow run context is available, it will be used for default values\n    of `flow_run` and `flow`.\n    \"\"\"\n    if not flow_run or not flow:\n        flow_run_context = prefect.context.FlowRunContext.get()\n        if flow_run_context:\n            flow_run = flow_run or flow_run_context.flow_run\n            flow = flow or flow_run_context.flow\n\n    return PrefectLogAdapter(\n        get_logger(\"prefect.task_runs\"),\n        extra={\n            **{\n                \"task_run_id\": str(task_run.id),\n                \"flow_run_id\": str(task_run.flow_run_id),\n                \"task_run_name\": task_run.name,\n                \"task_name\": task.name if task else \"&lt;unknown&gt;\",\n                \"flow_run_name\": flow_run.name if flow_run else \"&lt;unknown&gt;\",\n                \"flow_name\": flow.name if flow else \"&lt;unknown&gt;\",\n            },\n            **kwargs,\n        },\n    )\n</code></pre>","tags":["Python API","logging","loggers"]},{"location":"api-ref/prefect/runner/runner/","title":"runner","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner","title":"<code>prefect.runner.runner</code>","text":"<p>Runners are responsible for managing the execution of deployments created and managed by either <code>flow.serve</code> or the <code>serve</code> utility.</p> Example <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n\n    # serve generates a Runner instance\n    serve(slow_deploy, fast_deploy)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner","title":"<code>Runner</code>","text":"Source code in <code>prefect/runner/runner.py</code> <pre><code>class Runner:\n    def __init__(\n        self,\n        name: Optional[str] = None,\n        query_seconds: Optional[float] = None,\n        prefetch_seconds: float = 10,\n        limit: Optional[int] = None,\n        pause_on_shutdown: bool = True,\n        webserver: bool = False,\n    ):\n        \"\"\"\n        Responsible for managing the execution of remotely initiated flow runs.\n\n        Args:\n            name: The name of the runner. If not provided, a random one\n                will be generated. If provided, it cannot contain '/' or '%'.\n            query_seconds: The number of seconds to wait between querying for\n                scheduled flow runs; defaults to `PREFECT_RUNNER_POLL_FREQUENCY`\n            prefetch_seconds: The number of seconds to prefetch flow runs for.\n            limit: The maximum number of flow runs this runner should be running at\n            pause_on_shutdown: A boolean for whether or not to automatically pause\n                deployment schedules on shutdown; defaults to `True`\n            webserver: a boolean flag for whether to start a webserver for this runner\n\n        Examples:\n            Set up a Runner to manage the execute of scheduled flow runs for two flows:\n                ```python\n                from prefect import flow, Runner\n\n                @flow\n                def hello_flow(name):\n                    print(f\"hello {name}\")\n\n                @flow\n                def goodbye_flow(name):\n                    print(f\"goodbye {name}\")\n\n                if __name__ == \"__main__\"\n                    runner = Runner(name=\"my-runner\")\n\n                    # Will be runnable via the API\n                    runner.add_flow(hello_flow)\n\n                    # Run on a cron schedule\n                    runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n                    runner.start()\n                ```\n        \"\"\"\n        if name and (\"/\" in name or \"%\" in name):\n            raise ValueError(\"Runner name cannot contain '/' or '%'\")\n        self.name = Path(name).stem if name is not None else f\"runner-{uuid4()}\"\n        self._logger = get_logger(\"runner\")\n\n        self.started = False\n        self.stopping = False\n        self.pause_on_shutdown = pause_on_shutdown\n        self.limit = limit or PREFECT_RUNNER_PROCESS_LIMIT.value()\n        self.webserver = webserver\n\n        self.query_seconds = query_seconds or PREFECT_RUNNER_POLL_FREQUENCY.value()\n        self._prefetch_seconds = prefetch_seconds\n\n        self._runs_task_group: anyio.abc.TaskGroup = anyio.create_task_group()\n        self._loops_task_group: anyio.abc.TaskGroup = anyio.create_task_group()\n\n        self._limiter: Optional[anyio.CapacityLimiter] = anyio.CapacityLimiter(\n            self.limit\n        )\n        self._client = get_client()\n        self._submitting_flow_run_ids = set()\n        self._cancelling_flow_run_ids = set()\n        self._scheduled_task_scopes = set()\n        self._deployment_ids: Set[UUID] = set()\n        self._flow_run_process_map = dict()\n\n        self._tmp_dir: Path = (\n            Path(tempfile.gettempdir()) / \"runner_storage\" / str(uuid4())\n        )\n        self._storage_objs: List[RunnerStorage] = []\n        self._deployment_storage_map: Dict[UUID, RunnerStorage] = {}\n        self._loop = asyncio.get_event_loop()\n\n    @sync_compatible\n    async def add_deployment(\n        self,\n        deployment: RunnerDeployment,\n    ) -&gt; UUID:\n        \"\"\"\n        Registers the deployment with the Prefect API and will monitor for work once\n        the runner is started.\n\n        Args:\n            deployment: A deployment for the runner to register.\n        \"\"\"\n        deployment_id = await deployment.apply()\n        storage = deployment.storage\n        if storage is not None:\n            storage = await self._add_storage(storage)\n            self._deployment_storage_map[deployment_id] = storage\n        self._deployment_ids.add(deployment_id)\n\n        return deployment_id\n\n    @sync_compatible\n    async def add_flow(\n        self,\n        flow: Flow,\n        name: str = None,\n        interval: Optional[\n            Union[\n                Iterable[Union[int, float, datetime.timedelta]],\n                int,\n                float,\n                datetime.timedelta,\n            ]\n        ] = None,\n        cron: Optional[Union[Iterable[str], str]] = None,\n        rrule: Optional[Union[Iterable[str], str]] = None,\n        paused: Optional[bool] = None,\n        schedules: Optional[FlexibleScheduleList] = None,\n        schedule: Optional[SCHEDULE_TYPES] = None,\n        is_schedule_active: Optional[bool] = None,\n        parameters: Optional[dict] = None,\n        triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n        description: Optional[str] = None,\n        tags: Optional[List[str]] = None,\n        version: Optional[str] = None,\n        enforce_parameter_schema: bool = False,\n        entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n    ) -&gt; UUID:\n        \"\"\"\n        Provides a flow to the runner to be run based on the provided configuration.\n\n        Will create a deployment for the provided flow and register the deployment\n        with the runner.\n\n        Args:\n            flow: A flow for the runner to run.\n            name: The name to give the created deployment. Will default to the name\n                of the runner.\n            interval: An interval on which to execute the current flow. Accepts either a number\n                or a timedelta object. If a number is given, it will be interpreted as seconds.\n            cron: A cron schedule of when to execute runs of this flow.\n            rrule: An rrule schedule of when to execute runs of this flow.\n            schedule: A schedule object of when to execute runs of this flow. Used for\n                advanced scheduling options like timezone.\n            is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n                not provided when creating a deployment, the schedule will be set as active. If not\n                provided when updating a deployment, the schedule's activation will not be changed.\n            triggers: A list of triggers that should kick of a run of this flow.\n            parameters: A dictionary of default parameter values to pass to runs of this flow.\n            description: A description for the created deployment. Defaults to the flow's\n                description if not provided.\n            tags: A list of tags to associate with the created deployment for organizational\n                purposes.\n            version: A version for the created deployment. Defaults to the flow's version.\n            entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n                entrypoint, ensure that the module will be importable in the execution environment.\n        \"\"\"\n        api = PREFECT_API_URL.value()\n        if any([interval, cron, rrule]) and not api:\n            self._logger.warning(\n                \"Cannot schedule flows on an ephemeral server; run `prefect server\"\n                \" start` to start the scheduler.\"\n            )\n        name = self.name if name is None else name\n\n        deployment = await flow.to_deployment(\n            name=name,\n            interval=interval,\n            cron=cron,\n            rrule=rrule,\n            schedules=schedules,\n            schedule=schedule,\n            paused=paused,\n            is_schedule_active=is_schedule_active,\n            triggers=triggers,\n            parameters=parameters,\n            description=description,\n            tags=tags,\n            version=version,\n            enforce_parameter_schema=enforce_parameter_schema,\n            entrypoint_type=entrypoint_type,\n        )\n        return await self.add_deployment(deployment)\n\n    @sync_compatible\n    async def _add_storage(self, storage: RunnerStorage) -&gt; RunnerStorage:\n        \"\"\"\n        Adds a storage object to the runner. The storage object will be used to pull\n        code to the runner's working directory before the runner starts.\n\n        Args:\n            storage: The storage object to add to the runner.\n        Returns:\n            The updated storage object that was added to the runner.\n        \"\"\"\n        if storage not in self._storage_objs:\n            storage_copy = deepcopy(storage)\n            storage_copy.set_base_path(self._tmp_dir)\n\n            self._logger.debug(\n                f\"Adding storage {storage_copy!r} to runner at\"\n                f\" {str(storage_copy.destination)!r}\"\n            )\n            self._storage_objs.append(storage_copy)\n\n            return storage_copy\n        else:\n            return next(s for s in self._storage_objs if s == storage)\n\n    def handle_sigterm(self, signum, frame):\n        \"\"\"\n        Gracefully shuts down the runner when a SIGTERM is received.\n        \"\"\"\n        self._logger.info(\"SIGTERM received, initiating graceful shutdown...\")\n        from_sync.call_in_loop_thread(create_call(self.stop))\n\n        sys.exit(0)\n\n    @sync_compatible\n    async def start(\n        self, run_once: bool = False, webserver: Optional[bool] = None\n    ) -&gt; None:\n        \"\"\"\n        Starts a runner.\n\n        The runner will begin monitoring for and executing any scheduled work for all added flows.\n\n        Args:\n            run_once: If True, the runner will through one query loop and then exit.\n            webserver: a boolean for whether to start a webserver for this runner. If provided,\n                overrides the default on the runner\n\n        Examples:\n            Initialize a Runner, add two flows, and serve them by starting the Runner:\n\n            ```python\n            from prefect import flow, Runner\n\n            @flow\n            def hello_flow(name):\n                print(f\"hello {name}\")\n\n            @flow\n            def goodbye_flow(name):\n                print(f\"goodbye {name}\")\n\n            if __name__ == \"__main__\"\n                runner = Runner(name=\"my-runner\")\n\n                # Will be runnable via the API\n                runner.add_flow(hello_flow)\n\n                # Run on a cron schedule\n                runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n                runner.start()\n            ```\n        \"\"\"\n        _register_signal(signal.SIGTERM, self.handle_sigterm)\n\n        webserver = webserver if webserver is not None else self.webserver\n\n        if webserver or PREFECT_RUNNER_SERVER_ENABLE.value():\n            # we'll start the ASGI server in a separate thread so that\n            # uvicorn does not block the main thread\n            server_thread = threading.Thread(\n                name=\"runner-server-thread\",\n                target=partial(\n                    start_webserver,\n                    runner=self,\n                ),\n                daemon=True,\n            )\n            server_thread.start()\n\n        async with self as runner:\n            async with self._loops_task_group as tg:\n                for storage in self._storage_objs:\n                    if storage.pull_interval:\n                        tg.start_soon(\n                            partial(\n                                critical_service_loop,\n                                workload=storage.pull_code,\n                                interval=storage.pull_interval,\n                                run_once=run_once,\n                                jitter_range=0.3,\n                            )\n                        )\n                    else:\n                        tg.start_soon(storage.pull_code)\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=runner._get_and_submit_flow_runs,\n                        interval=self.query_seconds,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                    )\n                )\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=runner._check_for_cancelled_flow_runs,\n                        interval=self.query_seconds * 2,\n                        run_once=run_once,\n                        jitter_range=0.3,\n                    )\n                )\n\n    def execute_in_background(self, func, *args, **kwargs):\n        \"\"\"\n        Executes a function in the background.\n        \"\"\"\n\n        return asyncio.run_coroutine_threadsafe(func(*args, **kwargs), self._loop)\n\n    async def cancel_all(self):\n        runs_to_cancel = []\n\n        # done to avoid dictionary size changing during iteration\n        for info in self._flow_run_process_map.values():\n            runs_to_cancel.append(info[\"flow_run\"])\n        if runs_to_cancel:\n            for run in runs_to_cancel:\n                try:\n                    await self._cancel_run(run, state_msg=\"Runner is shutting down.\")\n                except Exception:\n                    self._logger.exception(\n                        f\"Exception encountered while cancelling {run.id}\",\n                        exc_info=True,\n                    )\n\n    @sync_compatible\n    async def stop(self):\n        \"\"\"Stops the runner's polling cycle.\"\"\"\n        if not self.started:\n            raise RuntimeError(\n                \"Runner has not yet started. Please start the runner by calling\"\n                \" .start()\"\n            )\n\n        self.started = False\n        self.stopping = True\n        await self.cancel_all()\n        try:\n            self._loops_task_group.cancel_scope.cancel()\n        except Exception:\n            self._logger.exception(\n                \"Exception encountered while shutting down\", exc_info=True\n            )\n\n    async def execute_flow_run(\n        self, flow_run_id: UUID, entrypoint: Optional[str] = None\n    ):\n        \"\"\"\n        Executes a single flow run with the given ID.\n\n        Execution will wait to monitor for cancellation requests. Exits once\n        the flow run process has exited.\n        \"\"\"\n        self.pause_on_shutdown = False\n        context = self if not self.started else asyncnullcontext()\n\n        async with context:\n            if not self._acquire_limit_slot(flow_run_id):\n                return\n\n            async with anyio.create_task_group() as tg:\n                with anyio.CancelScope():\n                    self._submitting_flow_run_ids.add(flow_run_id)\n                    flow_run = await self._client.read_flow_run(flow_run_id)\n\n                    pid = await self._runs_task_group.start(\n                        partial(\n                            self._submit_run_and_capture_errors,\n                            flow_run=flow_run,\n                            entrypoint=entrypoint,\n                        ),\n                    )\n\n                    self._flow_run_process_map[flow_run.id] = dict(\n                        pid=pid, flow_run=flow_run\n                    )\n\n                    # We want this loop to stop when the flow run process exits\n                    # so we'll check if the flow run process is still alive on\n                    # each iteration and cancel the task group if it is not.\n                    workload = partial(\n                        self._check_for_cancelled_flow_runs,\n                        should_stop=lambda: not self._flow_run_process_map,\n                        on_stop=tg.cancel_scope.cancel,\n                    )\n\n                    tg.start_soon(\n                        partial(\n                            critical_service_loop,\n                            workload=workload,\n                            interval=self.query_seconds,\n                            jitter_range=0.3,\n                        )\n                    )\n\n    def _get_flow_run_logger(self, flow_run: \"FlowRun\") -&gt; PrefectLogAdapter:\n        return flow_run_logger(flow_run=flow_run).getChild(\n            \"runner\",\n            extra={\n                \"runner_name\": self.name,\n            },\n        )\n\n    async def _run_process(\n        self,\n        flow_run: \"FlowRun\",\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n        entrypoint: Optional[str] = None,\n    ):\n        \"\"\"\n        Runs the given flow run in a subprocess.\n\n        Args:\n            flow_run: Flow run to execute via process. The ID of this flow run\n                is stored in the PREFECT__FLOW_RUN_ID environment variable to\n                allow the engine to retrieve the corresponding flow's code and\n                begin execution.\n            task_status: anyio task status used to send a message to the caller\n                than the flow run process has started.\n        \"\"\"\n        command = [get_sys_executable(), \"-m\", \"prefect.engine\"]\n\n        flow_run_logger = self._get_flow_run_logger(flow_run)\n\n        # We must add creationflags to a dict so it is only passed as a function\n        # parameter on Windows, because the presence of creationflags causes\n        # errors on Unix even if set to None\n        kwargs: Dict[str, object] = {}\n        if sys.platform == \"win32\":\n            kwargs[\"creationflags\"] = subprocess.CREATE_NEW_PROCESS_GROUP\n\n        flow_run_logger.info(\"Opening process...\")\n\n        env = get_current_settings().to_environment_variables(exclude_unset=True)\n        env.update(\n            {\n                **{\n                    \"PREFECT__FLOW_RUN_ID\": str(flow_run.id),\n                    \"PREFECT__STORAGE_BASE_PATH\": str(self._tmp_dir),\n                    \"PREFECT__ENABLE_CANCELLATION_AND_CRASHED_HOOKS\": \"false\",\n                },\n                **({\"PREFECT__FLOW_ENTRYPOINT\": entrypoint} if entrypoint else {}),\n            }\n        )\n        env.update(**os.environ)  # is this really necessary??\n\n        storage = self._deployment_storage_map.get(flow_run.deployment_id)\n        if storage and storage.pull_interval:\n            # perform an adhoc pull of code before running the flow if an\n            # adhoc pull hasn't been performed in the last pull_interval\n            # TODO: Explore integrating this behavior with global concurrency.\n            last_adhoc_pull = getattr(storage, \"last_adhoc_pull\", None)\n            if (\n                last_adhoc_pull is None\n                or last_adhoc_pull\n                &lt; datetime.datetime.now()\n                - datetime.timedelta(seconds=storage.pull_interval)\n            ):\n                self._logger.debug(\n                    \"Performing adhoc pull of code for flow run %s with storage %r\",\n                    flow_run.id,\n                    storage,\n                )\n                await storage.pull_code()\n                setattr(storage, \"last_adhoc_pull\", datetime.datetime.now())\n\n        process = await run_process(\n            command=command,\n            stream_output=True,\n            task_status=task_status,\n            env=env,\n            **kwargs,\n            cwd=storage.destination if storage else None,\n        )\n\n        # Use the pid for display if no name was given\n\n        if process.returncode:\n            help_message = None\n            level = logging.ERROR\n            if process.returncode == -9:\n                level = logging.INFO\n                help_message = (\n                    \"This indicates that the process exited due to a SIGKILL signal. \"\n                    \"Typically, this is either caused by manual cancellation or \"\n                    \"high memory usage causing the operating system to \"\n                    \"terminate the process.\"\n                )\n            if process.returncode == -15:\n                level = logging.INFO\n                help_message = (\n                    \"This indicates that the process exited due to a SIGTERM signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n            elif process.returncode == 247:\n                help_message = (\n                    \"This indicates that the process was terminated due to high \"\n                    \"memory usage.\"\n                )\n            elif (\n                sys.platform == \"win32\" and process.returncode == STATUS_CONTROL_C_EXIT\n            ):\n                level = logging.INFO\n                help_message = (\n                    \"Process was terminated due to a Ctrl+C or Ctrl+Break signal. \"\n                    \"Typically, this is caused by manual cancellation.\"\n                )\n\n            flow_run_logger.log(\n                level,\n                f\"Process for flow run {flow_run.name!r} exited with status code:\"\n                f\" {process.returncode}\"\n                + (f\"; {help_message}\" if help_message else \"\"),\n            )\n        else:\n            flow_run_logger.info(\n                f\"Process for flow run {flow_run.name!r} exited cleanly.\"\n            )\n\n        return process.returncode\n\n    async def _kill_process(\n        self,\n        pid: int,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Kills a given flow run process.\n\n        Args:\n            pid: ID of the process to kill\n            grace_seconds: Number of seconds to wait for the process to end.\n        \"\"\"\n        # In a non-windows environment first send a SIGTERM, then, after\n        # `grace_seconds` seconds have passed subsequent send SIGKILL. In\n        # Windows we use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        if sys.platform == \"win32\":\n            try:\n                os.kill(pid, signal.CTRL_BREAK_EVENT)\n            except (ProcessLookupError, WindowsError):\n                raise RuntimeError(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n        else:\n            try:\n                os.kill(pid, signal.SIGTERM)\n            except ProcessLookupError:\n                raise RuntimeError(\n                    f\"Unable to kill process {pid!r}: The process was not found.\"\n                )\n\n            # Throttle how often we check if the process is still alive to keep\n            # from making too many system calls in a short period of time.\n            check_interval = max(grace_seconds / 10, 1)\n\n            with anyio.move_on_after(grace_seconds):\n                while True:\n                    await anyio.sleep(check_interval)\n\n                    # Detect if the process is still alive. If not do an early\n                    # return as the process respected the SIGTERM from above.\n                    try:\n                        os.kill(pid, 0)\n                    except ProcessLookupError:\n                        return\n\n            try:\n                os.kill(pid, signal.SIGKILL)\n            except OSError:\n                # We shouldn't ever end up here, but it's possible that the\n                # process ended right after the check above.\n                return\n\n    async def _pause_schedules(self):\n        \"\"\"\n        Pauses all deployment schedules.\n        \"\"\"\n        self._logger.info(\"Pausing all deployments...\")\n        for deployment_id in self._deployment_ids:\n            self._logger.debug(f\"Pausing deployment '{deployment_id}'\")\n            await self._client.set_deployment_paused_state(deployment_id, True)\n        self._logger.info(\"All deployments have been paused!\")\n\n    async def _get_and_submit_flow_runs(self):\n        if self.stopping:\n            return\n        runs_response = await self._get_scheduled_flow_runs()\n        self.last_polled = pendulum.now(\"UTC\")\n        return await self._submit_scheduled_flow_runs(flow_run_response=runs_response)\n\n    async def _check_for_cancelled_flow_runs(\n        self, should_stop: Callable = lambda: False, on_stop: Callable = lambda: None\n    ):\n        \"\"\"\n        Checks for flow runs with CANCELLING a cancelling state and attempts to\n        cancel them.\n\n        Args:\n            should_stop: A callable that returns a boolean indicating whether or not\n                the runner should stop checking for cancelled flow runs.\n            on_stop: A callable that is called when the runner should stop checking\n                for cancelled flow runs.\n        \"\"\"\n        if self.stopping:\n            return\n        if not self.started:\n            raise RuntimeError(\n                \"Runner is not set up. Please make sure you are running this runner \"\n                \"as an async context manager.\"\n            )\n\n        if should_stop():\n            self._logger.debug(\n                \"Runner has no active flow runs or deployments. Sending message to loop\"\n                \" service that no further cancellation checks are needed.\"\n            )\n            on_stop()\n\n        self._logger.debug(\"Checking for cancelled flow runs...\")\n\n        named_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(\n                    any_=list(\n                        self._flow_run_process_map.keys()\n                        - self._cancelling_flow_run_ids\n                    )\n                ),\n            ),\n        )\n\n        typed_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(\n                    any_=list(\n                        self._flow_run_process_map.keys()\n                        - self._cancelling_flow_run_ids\n                    )\n                ),\n            ),\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self._logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self._cancelling_flow_run_ids.add(flow_run.id)\n            self._runs_task_group.start_soon(self._cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def _cancel_run(self, flow_run: \"FlowRun\", state_msg: Optional[str] = None):\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        pid = self._flow_run_process_map.get(flow_run.id, {}).get(\"pid\")\n        if not pid:\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"Could not find process ID for flow run\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            await self._kill_process(pid)\n        except RuntimeError as exc:\n            self._logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except Exception:\n            run_logger.exception(\n                \"Encountered exception while killing process for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self._cancelling_flow_run_ids.remove(flow_run.id)\n        else:\n            await self._run_on_cancellation_hooks(flow_run, flow_run.state)\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": state_msg or \"Flow run was cancelled successfully.\"\n                },\n            )\n            run_logger.info(f\"Cancelled flow run '{flow_run.name}'!\")\n\n    async def _get_scheduled_flow_runs(\n        self,\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Retrieve scheduled flow runs for this runner.\n        \"\"\"\n        scheduled_before = pendulum.now(\"utc\").add(seconds=int(self._prefetch_seconds))\n        self._logger.debug(\n            f\"Querying for flow runs scheduled before {scheduled_before}\"\n        )\n\n        scheduled_flow_runs = (\n            await self._client.get_scheduled_flow_runs_for_deployments(\n                deployment_ids=list(self._deployment_ids),\n                scheduled_before=scheduled_before,\n            )\n        )\n        self._logger.debug(f\"Discovered {len(scheduled_flow_runs)} scheduled_flow_runs\")\n        return scheduled_flow_runs\n\n    def has_slots_available(self) -&gt; bool:\n        \"\"\"\n        Determine if the flow run limit has been reached.\n\n        Returns:\n            - bool: True if the limit has not been reached, False otherwise.\n        \"\"\"\n        return self._limiter.available_tokens &gt; 0\n\n    def _acquire_limit_slot(self, flow_run_id: str) -&gt; bool:\n        \"\"\"\n        Enforces flow run limit set on runner.\n\n        Returns:\n            - bool: True if a slot was acquired, False otherwise.\n        \"\"\"\n        try:\n            if self._limiter:\n                self._limiter.acquire_on_behalf_of_nowait(flow_run_id)\n                self._logger.debug(\"Limit slot acquired for flow run '%s'\", flow_run_id)\n            return True\n        except RuntimeError as exc:\n            if (\n                \"this borrower is already holding one of this CapacityLimiter's tokens\"\n                in str(exc)\n            ):\n                self._logger.warning(\n                    f\"Duplicate submission of flow run '{flow_run_id}' detected. Runner\"\n                    \" will not re-submit flow run.\"\n                )\n                return False\n            else:\n                raise\n        except anyio.WouldBlock:\n            self._logger.info(\n                f\"Flow run limit reached; {self._limiter.borrowed_tokens} flow runs\"\n                \" in progress. You can control this limit by passing a `limit` value\"\n                \" to `serve` or adjusting the PREFECT_RUNNER_PROCESS_LIMIT setting.\"\n            )\n            return False\n\n    def _release_limit_slot(self, flow_run_id: str) -&gt; None:\n        \"\"\"\n        Frees up a slot taken by the given flow run id.\n        \"\"\"\n        if self._limiter:\n            self._limiter.release_on_behalf_of(flow_run_id)\n            self._logger.debug(\"Limit slot released for flow run '%s'\", flow_run_id)\n\n    async def _submit_scheduled_flow_runs(\n        self,\n        flow_run_response: List[\"FlowRun\"],\n        entrypoints: Optional[List[str]] = None,\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Takes a list of FlowRuns and submits the referenced flow runs\n        for execution by the runner.\n        \"\"\"\n        submittable_flow_runs = flow_run_response\n        submittable_flow_runs.sort(key=lambda run: run.next_scheduled_start_time)\n        for i, flow_run in enumerate(submittable_flow_runs):\n            if flow_run.id in self._submitting_flow_run_ids:\n                continue\n\n            if self._acquire_limit_slot(flow_run.id):\n                run_logger = self._get_flow_run_logger(flow_run)\n                run_logger.info(\n                    f\"Runner '{self.name}' submitting flow run '{flow_run.id}'\"\n                )\n                self._submitting_flow_run_ids.add(flow_run.id)\n                self._runs_task_group.start_soon(\n                    partial(\n                        self._submit_run,\n                        flow_run=flow_run,\n                        entrypoint=(\n                            entrypoints[i] if entrypoints else None\n                        ),  # TODO: avoid relying on index\n                    )\n                )\n            else:\n                break\n\n        return list(\n            filter(\n                lambda run: run.id in self._submitting_flow_run_ids,\n                submittable_flow_runs,\n            )\n        )\n\n    async def _submit_run(self, flow_run: \"FlowRun\", entrypoint: Optional[str] = None):\n        \"\"\"\n        Submits a given flow run for execution by the runner.\n        \"\"\"\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            readiness_result = await self._runs_task_group.start(\n                partial(\n                    self._submit_run_and_capture_errors,\n                    flow_run=flow_run,\n                    entrypoint=entrypoint,\n                ),\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                self._flow_run_process_map[flow_run.id] = dict(\n                    pid=readiness_result, flow_run=flow_run\n                )\n\n            run_logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            self._release_limit_slot(flow_run.id)\n\n        self._submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self,\n        flow_run: \"FlowRun\",\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n        entrypoint: Optional[str] = None,\n    ) -&gt; Union[Optional[int], Exception]:\n        run_logger = self._get_flow_run_logger(flow_run)\n\n        try:\n            status_code = await self._run_process(\n                flow_run=flow_run,\n                task_status=task_status,\n                entrypoint=entrypoint,\n            )\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                run_logger.exception(\n                    f\"Failed to start process for flow run '{flow_run.id}'.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run process could not be started\"\n                )\n            else:\n                run_logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            self._release_limit_slot(flow_run.id)\n            self._flow_run_process_map.pop(flow_run.id, None)\n\n        if status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                f\"Flow run process exited with non-zero status code {status_code}.\",\n            )\n\n        api_flow_run = await self._client.read_flow_run(flow_run_id=flow_run.id)\n        terminal_state = api_flow_run.state\n        if terminal_state.is_crashed():\n            await self._run_on_crashed_hooks(flow_run=flow_run, state=terminal_state)\n\n        return status_code\n\n    async def _propose_pending_state(self, flow_run: \"FlowRun\") -&gt; bool:\n        run_logger = self._get_flow_run_logger(flow_run)\n        state = flow_run.state\n        try:\n            state = await propose_state(\n                self._client, Pending(), flow_run_id=flow_run.id\n            )\n        except Abort as exc:\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            run_logger.exception(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n            )\n            return False\n\n        if not state.is_pending():\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: \"FlowRun\", exc: Exception) -&gt; None:\n        run_logger = self._get_flow_run_logger(flow_run)\n        try:\n            await propose_state(\n                self._client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            run_logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: \"FlowRun\", message: str) -&gt; None:\n        run_logger = self._get_flow_run_logger(flow_run)\n        try:\n            state = await propose_state(\n                self._client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            run_logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                run_logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: \"FlowRun\", state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self._client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self._cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the runner exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.started:\n                with anyio.CancelScope() as scope:\n                    self._scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self._scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self._runs_task_group.start(wrapper)\n\n    async def _run_on_cancellation_hooks(\n        self,\n        flow_run: \"FlowRun\",\n        state: State,\n    ) -&gt; None:\n        \"\"\"\n        Run the hooks for a flow.\n        \"\"\"\n        if state.is_cancelling():\n            try:\n                flow = await load_flow_from_flow_run(\n                    flow_run, client=self._client, storage_base_path=str(self._tmp_dir)\n                )\n                hooks = flow.on_cancellation or []\n\n                await _run_hooks(hooks, flow_run, flow, state)\n            except ObjectNotFound:\n                run_logger = self._get_flow_run_logger(flow_run)\n                run_logger.warning(\n                    f\"Runner cannot retrieve flow to execute cancellation hooks for flow run {flow_run.id!r}.\"\n                )\n\n    async def _run_on_crashed_hooks(\n        self,\n        flow_run: \"FlowRun\",\n        state: State,\n    ) -&gt; None:\n        \"\"\"\n        Run the hooks for a flow.\n        \"\"\"\n        if state.is_crashed():\n            flow = await load_flow_from_flow_run(\n                flow_run, client=self._client, storage_base_path=str(self._tmp_dir)\n            )\n            hooks = flow.on_crashed or []\n\n            await _run_hooks(hooks, flow_run, flow, state)\n\n    async def __aenter__(self):\n        self._logger.debug(\"Starting runner...\")\n        self._client = get_client()\n        self._tmp_dir.mkdir(parents=True)\n        await self._client.__aenter__()\n        await self._runs_task_group.__aenter__()\n\n        self.started = True\n        return self\n\n    async def __aexit__(self, *exc_info):\n        self._logger.debug(\"Stopping runner...\")\n        if self.pause_on_shutdown:\n            await self._pause_schedules()\n        self.started = False\n        for scope in self._scheduled_task_scopes:\n            scope.cancel()\n        if self._runs_task_group:\n            await self._runs_task_group.__aexit__(*exc_info)\n        if self._client:\n            await self._client.__aexit__(*exc_info)\n        shutil.rmtree(str(self._tmp_dir))\n\n    def __repr__(self):\n        return f\"Runner(name={self.name!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.add_deployment","title":"<code>add_deployment</code>  <code>async</code>","text":"<p>Registers the deployment with the Prefect API and will monitor for work once the runner is started.</p> <p>Parameters:</p> Name Type Description Default <code>deployment</code> <code>RunnerDeployment</code> <p>A deployment for the runner to register.</p> required Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def add_deployment(\n    self,\n    deployment: RunnerDeployment,\n) -&gt; UUID:\n    \"\"\"\n    Registers the deployment with the Prefect API and will monitor for work once\n    the runner is started.\n\n    Args:\n        deployment: A deployment for the runner to register.\n    \"\"\"\n    deployment_id = await deployment.apply()\n    storage = deployment.storage\n    if storage is not None:\n        storage = await self._add_storage(storage)\n        self._deployment_storage_map[deployment_id] = storage\n    self._deployment_ids.add(deployment_id)\n\n    return deployment_id\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.add_flow","title":"<code>add_flow</code>  <code>async</code>","text":"<p>Provides a flow to the runner to be run based on the provided configuration.</p> <p>Will create a deployment for the provided flow and register the deployment with the runner.</p> <p>Parameters:</p> Name Type Description Default <code>flow</code> <code>Flow</code> <p>A flow for the runner to run.</p> required <code>name</code> <code>str</code> <p>The name to give the created deployment. Will default to the name of the runner.</p> <code>None</code> <code>interval</code> <code>Optional[Union[Iterable[Union[int, float, timedelta]], int, float, timedelta]]</code> <p>An interval on which to execute the current flow. Accepts either a number or a timedelta object. If a number is given, it will be interpreted as seconds.</p> <code>None</code> <code>cron</code> <code>Optional[Union[Iterable[str], str]]</code> <p>A cron schedule of when to execute runs of this flow.</p> <code>None</code> <code>rrule</code> <code>Optional[Union[Iterable[str], str]]</code> <p>An rrule schedule of when to execute runs of this flow.</p> <code>None</code> <code>schedule</code> <code>Optional[SCHEDULE_TYPES]</code> <p>A schedule object of when to execute runs of this flow. Used for advanced scheduling options like timezone.</p> <code>None</code> <code>is_schedule_active</code> <code>Optional[bool]</code> <p>Whether or not to set the schedule for this deployment as active. If not provided when creating a deployment, the schedule will be set as active. If not provided when updating a deployment, the schedule's activation will not be changed.</p> <code>None</code> <code>triggers</code> <code>Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]]</code> <p>A list of triggers that should kick of a run of this flow.</p> <code>None</code> <code>parameters</code> <code>Optional[dict]</code> <p>A dictionary of default parameter values to pass to runs of this flow.</p> <code>None</code> <code>description</code> <code>Optional[str]</code> <p>A description for the created deployment. Defaults to the flow's description if not provided.</p> <code>None</code> <code>tags</code> <code>Optional[List[str]]</code> <p>A list of tags to associate with the created deployment for organizational purposes.</p> <code>None</code> <code>version</code> <code>Optional[str]</code> <p>A version for the created deployment. Defaults to the flow's version.</p> <code>None</code> <code>entrypoint_type</code> <code>EntrypointType</code> <p>Type of entrypoint to use for the deployment. When using a module path entrypoint, ensure that the module will be importable in the execution environment.</p> <code>FILE_PATH</code> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def add_flow(\n    self,\n    flow: Flow,\n    name: str = None,\n    interval: Optional[\n        Union[\n            Iterable[Union[int, float, datetime.timedelta]],\n            int,\n            float,\n            datetime.timedelta,\n        ]\n    ] = None,\n    cron: Optional[Union[Iterable[str], str]] = None,\n    rrule: Optional[Union[Iterable[str], str]] = None,\n    paused: Optional[bool] = None,\n    schedules: Optional[FlexibleScheduleList] = None,\n    schedule: Optional[SCHEDULE_TYPES] = None,\n    is_schedule_active: Optional[bool] = None,\n    parameters: Optional[dict] = None,\n    triggers: Optional[List[Union[DeploymentTriggerTypes, TriggerTypes]]] = None,\n    description: Optional[str] = None,\n    tags: Optional[List[str]] = None,\n    version: Optional[str] = None,\n    enforce_parameter_schema: bool = False,\n    entrypoint_type: EntrypointType = EntrypointType.FILE_PATH,\n) -&gt; UUID:\n    \"\"\"\n    Provides a flow to the runner to be run based on the provided configuration.\n\n    Will create a deployment for the provided flow and register the deployment\n    with the runner.\n\n    Args:\n        flow: A flow for the runner to run.\n        name: The name to give the created deployment. Will default to the name\n            of the runner.\n        interval: An interval on which to execute the current flow. Accepts either a number\n            or a timedelta object. If a number is given, it will be interpreted as seconds.\n        cron: A cron schedule of when to execute runs of this flow.\n        rrule: An rrule schedule of when to execute runs of this flow.\n        schedule: A schedule object of when to execute runs of this flow. Used for\n            advanced scheduling options like timezone.\n        is_schedule_active: Whether or not to set the schedule for this deployment as active. If\n            not provided when creating a deployment, the schedule will be set as active. If not\n            provided when updating a deployment, the schedule's activation will not be changed.\n        triggers: A list of triggers that should kick of a run of this flow.\n        parameters: A dictionary of default parameter values to pass to runs of this flow.\n        description: A description for the created deployment. Defaults to the flow's\n            description if not provided.\n        tags: A list of tags to associate with the created deployment for organizational\n            purposes.\n        version: A version for the created deployment. Defaults to the flow's version.\n        entrypoint_type: Type of entrypoint to use for the deployment. When using a module path\n            entrypoint, ensure that the module will be importable in the execution environment.\n    \"\"\"\n    api = PREFECT_API_URL.value()\n    if any([interval, cron, rrule]) and not api:\n        self._logger.warning(\n            \"Cannot schedule flows on an ephemeral server; run `prefect server\"\n            \" start` to start the scheduler.\"\n        )\n    name = self.name if name is None else name\n\n    deployment = await flow.to_deployment(\n        name=name,\n        interval=interval,\n        cron=cron,\n        rrule=rrule,\n        schedules=schedules,\n        schedule=schedule,\n        paused=paused,\n        is_schedule_active=is_schedule_active,\n        triggers=triggers,\n        parameters=parameters,\n        description=description,\n        tags=tags,\n        version=version,\n        enforce_parameter_schema=enforce_parameter_schema,\n        entrypoint_type=entrypoint_type,\n    )\n    return await self.add_deployment(deployment)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.execute_flow_run","title":"<code>execute_flow_run</code>  <code>async</code>","text":"<p>Executes a single flow run with the given ID.</p> <p>Execution will wait to monitor for cancellation requests. Exits once the flow run process has exited.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>async def execute_flow_run(\n    self, flow_run_id: UUID, entrypoint: Optional[str] = None\n):\n    \"\"\"\n    Executes a single flow run with the given ID.\n\n    Execution will wait to monitor for cancellation requests. Exits once\n    the flow run process has exited.\n    \"\"\"\n    self.pause_on_shutdown = False\n    context = self if not self.started else asyncnullcontext()\n\n    async with context:\n        if not self._acquire_limit_slot(flow_run_id):\n            return\n\n        async with anyio.create_task_group() as tg:\n            with anyio.CancelScope():\n                self._submitting_flow_run_ids.add(flow_run_id)\n                flow_run = await self._client.read_flow_run(flow_run_id)\n\n                pid = await self._runs_task_group.start(\n                    partial(\n                        self._submit_run_and_capture_errors,\n                        flow_run=flow_run,\n                        entrypoint=entrypoint,\n                    ),\n                )\n\n                self._flow_run_process_map[flow_run.id] = dict(\n                    pid=pid, flow_run=flow_run\n                )\n\n                # We want this loop to stop when the flow run process exits\n                # so we'll check if the flow run process is still alive on\n                # each iteration and cancel the task group if it is not.\n                workload = partial(\n                    self._check_for_cancelled_flow_runs,\n                    should_stop=lambda: not self._flow_run_process_map,\n                    on_stop=tg.cancel_scope.cancel,\n                )\n\n                tg.start_soon(\n                    partial(\n                        critical_service_loop,\n                        workload=workload,\n                        interval=self.query_seconds,\n                        jitter_range=0.3,\n                    )\n                )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.execute_in_background","title":"<code>execute_in_background</code>","text":"<p>Executes a function in the background.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>def execute_in_background(self, func, *args, **kwargs):\n    \"\"\"\n    Executes a function in the background.\n    \"\"\"\n\n    return asyncio.run_coroutine_threadsafe(func(*args, **kwargs), self._loop)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.handle_sigterm","title":"<code>handle_sigterm</code>","text":"<p>Gracefully shuts down the runner when a SIGTERM is received.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>def handle_sigterm(self, signum, frame):\n    \"\"\"\n    Gracefully shuts down the runner when a SIGTERM is received.\n    \"\"\"\n    self._logger.info(\"SIGTERM received, initiating graceful shutdown...\")\n    from_sync.call_in_loop_thread(create_call(self.stop))\n\n    sys.exit(0)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.has_slots_available","title":"<code>has_slots_available</code>","text":"<p>Determine if the flow run limit has been reached.</p> <p>Returns:</p> Type Description <code>bool</code> <ul> <li>bool: True if the limit has not been reached, False otherwise.</li> </ul> Source code in <code>prefect/runner/runner.py</code> <pre><code>def has_slots_available(self) -&gt; bool:\n    \"\"\"\n    Determine if the flow run limit has been reached.\n\n    Returns:\n        - bool: True if the limit has not been reached, False otherwise.\n    \"\"\"\n    return self._limiter.available_tokens &gt; 0\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.start","title":"<code>start</code>  <code>async</code>","text":"<p>Starts a runner.</p> <p>The runner will begin monitoring for and executing any scheduled work for all added flows.</p> <p>Parameters:</p> Name Type Description Default <code>run_once</code> <code>bool</code> <p>If True, the runner will through one query loop and then exit.</p> <code>False</code> <code>webserver</code> <code>Optional[bool]</code> <p>a boolean for whether to start a webserver for this runner. If provided, overrides the default on the runner</p> <code>None</code> <p>Examples:</p> <p>Initialize a Runner, add two flows, and serve them by starting the Runner:</p> <pre><code>from prefect import flow, Runner\n\n@flow\ndef hello_flow(name):\n    print(f\"hello {name}\")\n\n@flow\ndef goodbye_flow(name):\n    print(f\"goodbye {name}\")\n\nif __name__ == \"__main__\"\n    runner = Runner(name=\"my-runner\")\n\n    # Will be runnable via the API\n    runner.add_flow(hello_flow)\n\n    # Run on a cron schedule\n    runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n    runner.start()\n</code></pre> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def start(\n    self, run_once: bool = False, webserver: Optional[bool] = None\n) -&gt; None:\n    \"\"\"\n    Starts a runner.\n\n    The runner will begin monitoring for and executing any scheduled work for all added flows.\n\n    Args:\n        run_once: If True, the runner will through one query loop and then exit.\n        webserver: a boolean for whether to start a webserver for this runner. If provided,\n            overrides the default on the runner\n\n    Examples:\n        Initialize a Runner, add two flows, and serve them by starting the Runner:\n\n        ```python\n        from prefect import flow, Runner\n\n        @flow\n        def hello_flow(name):\n            print(f\"hello {name}\")\n\n        @flow\n        def goodbye_flow(name):\n            print(f\"goodbye {name}\")\n\n        if __name__ == \"__main__\"\n            runner = Runner(name=\"my-runner\")\n\n            # Will be runnable via the API\n            runner.add_flow(hello_flow)\n\n            # Run on a cron schedule\n            runner.add_flow(goodbye_flow, schedule={\"cron\": \"0 * * * *\"})\n\n            runner.start()\n        ```\n    \"\"\"\n    _register_signal(signal.SIGTERM, self.handle_sigterm)\n\n    webserver = webserver if webserver is not None else self.webserver\n\n    if webserver or PREFECT_RUNNER_SERVER_ENABLE.value():\n        # we'll start the ASGI server in a separate thread so that\n        # uvicorn does not block the main thread\n        server_thread = threading.Thread(\n            name=\"runner-server-thread\",\n            target=partial(\n                start_webserver,\n                runner=self,\n            ),\n            daemon=True,\n        )\n        server_thread.start()\n\n    async with self as runner:\n        async with self._loops_task_group as tg:\n            for storage in self._storage_objs:\n                if storage.pull_interval:\n                    tg.start_soon(\n                        partial(\n                            critical_service_loop,\n                            workload=storage.pull_code,\n                            interval=storage.pull_interval,\n                            run_once=run_once,\n                            jitter_range=0.3,\n                        )\n                    )\n                else:\n                    tg.start_soon(storage.pull_code)\n            tg.start_soon(\n                partial(\n                    critical_service_loop,\n                    workload=runner._get_and_submit_flow_runs,\n                    interval=self.query_seconds,\n                    run_once=run_once,\n                    jitter_range=0.3,\n                )\n            )\n            tg.start_soon(\n                partial(\n                    critical_service_loop,\n                    workload=runner._check_for_cancelled_flow_runs,\n                    interval=self.query_seconds * 2,\n                    run_once=run_once,\n                    jitter_range=0.3,\n                )\n            )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/runner/#prefect.runner.runner.Runner.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Stops the runner's polling cycle.</p> Source code in <code>prefect/runner/runner.py</code> <pre><code>@sync_compatible\nasync def stop(self):\n    \"\"\"Stops the runner's polling cycle.\"\"\"\n    if not self.started:\n        raise RuntimeError(\n            \"Runner has not yet started. Please start the runner by calling\"\n            \" .start()\"\n        )\n\n    self.started = False\n    self.stopping = True\n    await self.cancel_all()\n    try:\n        self._loops_task_group.cancel_scope.cancel()\n    except Exception:\n        self._logger.exception(\n            \"Exception encountered while shutting down\", exc_info=True\n        )\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/server/","title":"server","text":"","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server","title":"<code>prefect.runner.server</code>","text":"","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.build_server","title":"<code>build_server</code>  <code>async</code>","text":"<p>Build a FastAPI server for a runner.</p> <p>Parameters:</p> Name Type Description Default <code>runner</code> <code>Runner</code> <p>the runner this server interacts with and monitors</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> required Source code in <code>prefect/runner/server.py</code> <pre><code>@sync_compatible\nasync def build_server(runner: \"Runner\") -&gt; FastAPI:\n    \"\"\"\n    Build a FastAPI server for a runner.\n\n    Args:\n        runner (Runner): the runner this server interacts with and monitors\n        log_level (str): the log level to use for the server\n    \"\"\"\n    webserver = FastAPI()\n    router = APIRouter()\n\n    router.add_api_route(\n        \"/health\", perform_health_check(runner=runner), methods=[\"GET\"]\n    )\n    router.add_api_route(\"/run_count\", run_count(runner=runner), methods=[\"GET\"])\n    router.add_api_route(\"/shutdown\", shutdown(runner=runner), methods=[\"POST\"])\n    webserver.include_router(router)\n\n    if PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS.value():\n        deployments_router, deployment_schemas = await get_deployment_router(runner)\n        webserver.include_router(deployments_router)\n\n        subflow_schemas = await get_subflow_schemas(runner)\n        webserver.add_api_route(\n            \"/flow/run\",\n            _build_generic_endpoint_for_flows(runner=runner, schemas=subflow_schemas),\n            methods=[\"POST\"],\n            name=\"Run flow in background\",\n            description=\"Trigger any flow run as a background task on the runner.\",\n            summary=\"Run flow\",\n        )\n\n        def customize_openapi():\n            if webserver.openapi_schema:\n                return webserver.openapi_schema\n\n            openapi_schema = inject_schemas_into_openapi(webserver, deployment_schemas)\n            webserver.openapi_schema = openapi_schema\n            return webserver.openapi_schema\n\n        webserver.openapi = customize_openapi\n\n    return webserver\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.get_subflow_schemas","title":"<code>get_subflow_schemas</code>  <code>async</code>","text":"<p>Load available subflow schemas by filtering for only those subflows in the deployment entrypoint's import space.</p> Source code in <code>prefect/runner/server.py</code> <pre><code>async def get_subflow_schemas(runner: \"Runner\") -&gt; Dict[str, Dict]:\n    \"\"\"\n    Load available subflow schemas by filtering for only those subflows in the\n    deployment entrypoint's import space.\n    \"\"\"\n    schemas = {}\n    async with get_client() as client:\n        for deployment_id in runner._deployment_ids:\n            deployment = await client.read_deployment(deployment_id)\n            if deployment.entrypoint is None:\n                continue\n\n            script = deployment.entrypoint.split(\":\")[0]\n            subflows = load_flows_from_script(script)\n            for flow in subflows:\n                schemas[flow.name] = flow.parameters.dict()\n\n    return schemas\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/server/#prefect.runner.server.start_webserver","title":"<code>start_webserver</code>","text":"<p>Run a FastAPI server for a runner.</p> <p>Parameters:</p> Name Type Description Default <code>runner</code> <code>Runner</code> <p>the runner this server interacts with and monitors</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> <code>None</code> Source code in <code>prefect/runner/server.py</code> <pre><code>def start_webserver(runner: \"Runner\", log_level: Optional[str] = None) -&gt; None:\n    \"\"\"\n    Run a FastAPI server for a runner.\n\n    Args:\n        runner (Runner): the runner this server interacts with and monitors\n        log_level (str): the log level to use for the server\n    \"\"\"\n    host = PREFECT_RUNNER_SERVER_HOST.value()\n    port = PREFECT_RUNNER_SERVER_PORT.value()\n    log_level = log_level or PREFECT_RUNNER_SERVER_LOG_LEVEL.value()\n    webserver = build_server(runner)\n    uvicorn.run(webserver, host=host, port=port, log_level=log_level)\n</code></pre>","tags":["Python API","server"]},{"location":"api-ref/prefect/runner/storage/","title":"storage","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage","title":"<code>prefect.runner.storage</code>","text":"","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.BlockStorageAdapter","title":"<code>BlockStorageAdapter</code>","text":"<p>A storage adapter for a storage block object to allow it to be used as a runner storage object.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>class BlockStorageAdapter:\n    \"\"\"\n    A storage adapter for a storage block object to allow it to be used as a\n    runner storage object.\n    \"\"\"\n\n    def __init__(\n        self,\n        block: Union[ReadableDeploymentStorage, WritableDeploymentStorage],\n        pull_interval: Optional[int] = 60,\n    ):\n        self._block = block\n        self._pull_interval = pull_interval\n        self._storage_base_path = Path.cwd()\n        if not isinstance(block, Block):\n            raise TypeError(\n                f\"Expected a block object. Received a {type(block).__name__!r} object.\"\n            )\n        if not hasattr(block, \"get_directory\"):\n            raise ValueError(\"Provided block must have a `get_directory` method.\")\n\n        self._name = (\n            f\"{block.get_block_type_slug()}-{block._block_document_name}\"\n            if block._block_document_name\n            else str(uuid4())\n        )\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._storage_base_path / self._name\n\n    async def pull_code(self):\n        if not self.destination.exists():\n            self.destination.mkdir(parents=True, exist_ok=True)\n        await self._block.get_directory(local_path=str(self.destination))\n\n    def to_pull_step(self) -&gt; dict:\n        # Give blocks the change to implement their own pull step\n        if hasattr(self._block, \"get_pull_step\"):\n            return self._block.get_pull_step()\n        else:\n            if not self._block._block_document_name:\n                raise BlockNotSavedError(\n                    \"Block must be saved with `.save()` before it can be converted to a\"\n                    \" pull step.\"\n                )\n            return {\n                \"prefect.deployments.steps.pull_with_block\": {\n                    \"block_type_slug\": self._block.get_block_type_slug(),\n                    \"block_document_name\": self._block._block_document_name,\n                }\n            }\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, BlockStorageAdapter):\n            return self._block == __value._block\n        return False\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.GitRepository","title":"<code>GitRepository</code>","text":"<p>Pulls the contents of a git repository to the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>The URL of the git repository to pull from</p> required <code>credentials</code> <code>Union[GitCredentials, Block, Dict[str, Any], None]</code> <p>A dictionary of credentials to use when pulling from the repository. If a username is provided, an access token must also be provided.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>The name of the repository. If not provided, the name will be inferred from the repository URL.</p> <code>None</code> <code>branch</code> <code>Optional[str]</code> <p>The branch to pull from. Defaults to \"main\".</p> <code>None</code> <code>pull_interval</code> <code>Optional[int]</code> <p>The interval in seconds at which to pull contents from remote storage to local storage. If None, remote storage will perform a one-time sync.</p> <code>60</code> <p>Examples:</p> <p>Pull the contents of a private git repository to the local filesystem:</p> <pre><code>from prefect.runner.storage import GitRepository\n\nstorage = GitRepository(\n    url=\"https://github.com/org/repo.git\",\n    credentials={\"username\": \"oauth2\", \"access_token\": \"my-access-token\"},\n)\n\nawait storage.pull_code()\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class GitRepository:\n    \"\"\"\n    Pulls the contents of a git repository to the local filesystem.\n\n    Parameters:\n        url: The URL of the git repository to pull from\n        credentials: A dictionary of credentials to use when pulling from the\n            repository. If a username is provided, an access token must also be\n            provided.\n        name: The name of the repository. If not provided, the name will be\n            inferred from the repository URL.\n        branch: The branch to pull from. Defaults to \"main\".\n        pull_interval: The interval in seconds at which to pull contents from\n            remote storage to local storage. If None, remote storage will perform\n            a one-time sync.\n\n    Examples:\n        Pull the contents of a private git repository to the local filesystem:\n\n        ```python\n        from prefect.runner.storage import GitRepository\n\n        storage = GitRepository(\n            url=\"https://github.com/org/repo.git\",\n            credentials={\"username\": \"oauth2\", \"access_token\": \"my-access-token\"},\n        )\n\n        await storage.pull_code()\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        url: str,\n        credentials: Union[GitCredentials, Block, Dict[str, Any], None] = None,\n        name: Optional[str] = None,\n        branch: Optional[str] = None,\n        include_submodules: bool = False,\n        pull_interval: Optional[int] = 60,\n    ):\n        if credentials is None:\n            credentials = {}\n\n        if (\n            isinstance(credentials, dict)\n            and credentials.get(\"username\")\n            and not (credentials.get(\"access_token\") or credentials.get(\"password\"))\n        ):\n            raise ValueError(\n                \"If a username is provided, an access token or password must also be\"\n                \" provided.\"\n            )\n        self._url = url\n        self._branch = branch\n        self._credentials = credentials\n        self._include_submodules = include_submodules\n        repo_name = urlparse(url).path.split(\"/\")[-1].replace(\".git\", \"\")\n        default_name = f\"{repo_name}-{branch}\" if branch else repo_name\n        self._name = name or default_name\n        self._logger = get_logger(f\"runner.storage.git-repository.{self._name}\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._storage_base_path / self._name\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    @property\n    def _repository_url_with_credentials(self) -&gt; str:\n        if not self._credentials:\n            return self._url\n\n        url_components = urlparse(self._url)\n\n        credentials = (\n            self._credentials.dict()\n            if isinstance(self._credentials, Block)\n            else deepcopy(self._credentials)\n        )\n\n        for k, v in credentials.items():\n            if isinstance(v, Secret):\n                credentials[k] = v.get()\n            elif isinstance(v, SecretStr):\n                credentials[k] = v.get_secret_value()\n\n        formatted_credentials = _format_token_from_credentials(\n            urlparse(self._url).netloc, credentials\n        )\n        if url_components.scheme == \"https\" and formatted_credentials is not None:\n            updated_components = url_components._replace(\n                netloc=f\"{formatted_credentials}@{url_components.netloc}\"\n            )\n            repository_url = urlunparse(updated_components)\n        else:\n            repository_url = self._url\n\n        return repository_url\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls the contents of the configured repository to the local filesystem.\n        \"\"\"\n        self._logger.debug(\n            \"Pulling contents from repository '%s' to '%s'...\",\n            self._name,\n            self.destination,\n        )\n\n        git_dir = self.destination / \".git\"\n\n        if git_dir.exists():\n            # Check if the existing repository matches the configured repository\n            result = await run_process(\n                [\"git\", \"config\", \"--get\", \"remote.origin.url\"],\n                cwd=str(self.destination),\n            )\n            existing_repo_url = None\n            if result.stdout is not None:\n                existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())\n\n            if existing_repo_url != self._url:\n                raise ValueError(\n                    f\"The existing repository at {str(self.destination)} \"\n                    f\"does not match the configured repository {self._url}\"\n                )\n\n            self._logger.debug(\"Pulling latest changes from origin/%s\", self._branch)\n            # Update the existing repository\n            cmd = [\"git\", \"pull\", \"origin\"]\n            if self._branch:\n                cmd += [self._branch]\n            if self._include_submodules:\n                cmd += [\"--recurse-submodules\"]\n            cmd += [\"--depth\", \"1\"]\n            try:\n                await run_process(cmd, cwd=self.destination)\n                self._logger.debug(\"Successfully pulled latest changes\")\n            except subprocess.CalledProcessError as exc:\n                self._logger.error(\n                    f\"Failed to pull latest changes with exit code {exc}\"\n                )\n                shutil.rmtree(self.destination)\n                await self._clone_repo()\n\n        else:\n            await self._clone_repo()\n\n    async def _clone_repo(self):\n        \"\"\"\n        Clones the repository into the local destination.\n        \"\"\"\n        self._logger.debug(\"Cloning repository %s\", self._url)\n\n        repository_url = self._repository_url_with_credentials\n\n        cmd = [\n            \"git\",\n            \"clone\",\n            repository_url,\n        ]\n        if self._branch:\n            cmd += [\"--branch\", self._branch]\n        if self._include_submodules:\n            cmd += [\"--recurse-submodules\"]\n\n        # Limit git history and set path to clone to\n        cmd += [\"--depth\", \"1\", str(self.destination)]\n\n        try:\n            await run_process(cmd)\n        except subprocess.CalledProcessError as exc:\n            # Hide the command used to avoid leaking the access token\n            exc_chain = None if self._credentials else exc\n            raise RuntimeError(\n                f\"Failed to clone repository {self._url!r} with exit code\"\n                f\" {exc.returncode}.\"\n            ) from exc_chain\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, GitRepository):\n            return (\n                self._url == __value._url\n                and self._branch == __value._branch\n                and self._name == __value._name\n            )\n        return False\n\n    def __repr__(self) -&gt; str:\n        return (\n            f\"GitRepository(name={self._name!r} repository={self._url!r},\"\n            f\" branch={self._branch!r})\"\n        )\n\n    def to_pull_step(self) -&gt; Dict:\n        pull_step = {\n            \"prefect.deployments.steps.git_clone\": {\n                \"repository\": self._url,\n                \"branch\": self._branch,\n            }\n        }\n        if self._include_submodules:\n            pull_step[\"prefect.deployments.steps.git_clone\"][\n                \"include_submodules\"\n            ] = self._include_submodules\n        if isinstance(self._credentials, Block):\n            pull_step[\"prefect.deployments.steps.git_clone\"][\n                \"credentials\"\n            ] = f\"{{{{ {self._credentials.get_block_placeholder()} }}}}\"\n        elif isinstance(self._credentials, dict):\n            if isinstance(self._credentials.get(\"access_token\"), Secret):\n                pull_step[\"prefect.deployments.steps.git_clone\"][\"credentials\"] = {\n                    **self._credentials,\n                    \"access_token\": (\n                        \"{{\"\n                        f\" {self._credentials['access_token'].get_block_placeholder()} }}}}\"\n                    ),\n                }\n            elif self._credentials.get(\"access_token\") is not None:\n                raise ValueError(\n                    \"Please save your access token as a Secret block before converting\"\n                    \" this storage object to a pull step.\"\n                )\n\n        return pull_step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.GitRepository.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls the contents of the configured repository to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls the contents of the configured repository to the local filesystem.\n    \"\"\"\n    self._logger.debug(\n        \"Pulling contents from repository '%s' to '%s'...\",\n        self._name,\n        self.destination,\n    )\n\n    git_dir = self.destination / \".git\"\n\n    if git_dir.exists():\n        # Check if the existing repository matches the configured repository\n        result = await run_process(\n            [\"git\", \"config\", \"--get\", \"remote.origin.url\"],\n            cwd=str(self.destination),\n        )\n        existing_repo_url = None\n        if result.stdout is not None:\n            existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())\n\n        if existing_repo_url != self._url:\n            raise ValueError(\n                f\"The existing repository at {str(self.destination)} \"\n                f\"does not match the configured repository {self._url}\"\n            )\n\n        self._logger.debug(\"Pulling latest changes from origin/%s\", self._branch)\n        # Update the existing repository\n        cmd = [\"git\", \"pull\", \"origin\"]\n        if self._branch:\n            cmd += [self._branch]\n        if self._include_submodules:\n            cmd += [\"--recurse-submodules\"]\n        cmd += [\"--depth\", \"1\"]\n        try:\n            await run_process(cmd, cwd=self.destination)\n            self._logger.debug(\"Successfully pulled latest changes\")\n        except subprocess.CalledProcessError as exc:\n            self._logger.error(\n                f\"Failed to pull latest changes with exit code {exc}\"\n            )\n            shutil.rmtree(self.destination)\n            await self._clone_repo()\n\n    else:\n        await self._clone_repo()\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.LocalStorage","title":"<code>LocalStorage</code>","text":"<p>Sets the working directory in the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>Path</code> <p>Local file path to set the working directory for the flow</p> required <p>Examples:</p> <p>Sets the working directory for the local path to the flow:</p> <pre><code>from prefect.runner.storage import Localstorage\n\nstorage = LocalStorage(\n    path=\"/path/to/local/flow_directory\",\n)\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class LocalStorage:\n    \"\"\"\n    Sets the working directory in the local filesystem.\n\n    Parameters:\n        Path: Local file path to set the working directory for the flow\n\n    Examples:\n        Sets the working directory for the local path to the flow:\n\n        ```python\n        from prefect.runner.storage import Localstorage\n\n        storage = LocalStorage(\n            path=\"/path/to/local/flow_directory\",\n        )\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        path: str,\n        pull_interval: Optional[int] = None,\n    ):\n        self._path = Path(path).resolve()\n        self._logger = get_logger(\"runner.storage.local-storage\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        return self._path\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        return self._pull_interval\n\n    async def pull_code(self):\n        # Local storage assumes the code already exists on the local filesystem\n        # and does not need to be pulled from a remote location\n        pass\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n        step = {\n            \"prefect.deployments.steps.set_working_directory\": {\n                \"directory\": str(self.destination)\n            }\n        }\n        return step\n\n    def __eq__(self, __value) -&gt; bool:\n        if isinstance(__value, LocalStorage):\n            return self._path == __value._path\n        return False\n\n    def __repr__(self) -&gt; str:\n        return f\"LocalStorage(path={self._path!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.LocalStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n    step = {\n        \"prefect.deployments.steps.set_working_directory\": {\n            \"directory\": str(self.destination)\n        }\n    }\n    return step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage","title":"<code>RemoteStorage</code>","text":"<p>Pulls the contents of a remote storage location to the local filesystem.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>str</code> <p>The URL of the remote storage location to pull from. Supports <code>fsspec</code> URLs. Some protocols may require an additional <code>fsspec</code> dependency to be installed. Refer to the <code>fsspec</code> docs for more details.</p> required <code>pull_interval</code> <code>Optional[int]</code> <p>The interval in seconds at which to pull contents from remote storage to local storage. If None, remote storage will perform a one-time sync.</p> <code>60</code> <code>**settings</code> <code>Any</code> <p>Any additional settings to pass the <code>fsspec</code> filesystem class.</p> <code>{}</code> <p>Examples:</p> <p>Pull the contents of a remote storage location to the local filesystem:</p> <pre><code>from prefect.runner.storage import RemoteStorage\n\nstorage = RemoteStorage(url=\"s3://my-bucket/my-folder\")\n\nawait storage.pull_code()\n</code></pre> <p>Pull the contents of a remote storage location to the local filesystem with additional settings:</p> <pre><code>from prefect.runner.storage import RemoteStorage\nfrom prefect.blocks.system import Secret\n\nstorage = RemoteStorage(\n    url=\"s3://my-bucket/my-folder\",\n    # Use Secret blocks to keep credentials out of your code\n    key=Secret.load(\"my-aws-access-key\"),\n    secret=Secret.load(\"my-aws-secret-key\"),\n)\n\nawait storage.pull_code()\n</code></pre> Source code in <code>prefect/runner/storage.py</code> <pre><code>class RemoteStorage:\n    \"\"\"\n    Pulls the contents of a remote storage location to the local filesystem.\n\n    Parameters:\n        url: The URL of the remote storage location to pull from. Supports\n            `fsspec` URLs. Some protocols may require an additional `fsspec`\n            dependency to be installed. Refer to the\n            [`fsspec` docs](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations)\n            for more details.\n        pull_interval: The interval in seconds at which to pull contents from\n            remote storage to local storage. If None, remote storage will perform\n            a one-time sync.\n        **settings: Any additional settings to pass the `fsspec` filesystem class.\n\n    Examples:\n        Pull the contents of a remote storage location to the local filesystem:\n\n        ```python\n        from prefect.runner.storage import RemoteStorage\n\n        storage = RemoteStorage(url=\"s3://my-bucket/my-folder\")\n\n        await storage.pull_code()\n        ```\n\n        Pull the contents of a remote storage location to the local filesystem\n        with additional settings:\n\n        ```python\n        from prefect.runner.storage import RemoteStorage\n        from prefect.blocks.system import Secret\n\n        storage = RemoteStorage(\n            url=\"s3://my-bucket/my-folder\",\n            # Use Secret blocks to keep credentials out of your code\n            key=Secret.load(\"my-aws-access-key\"),\n            secret=Secret.load(\"my-aws-secret-key\"),\n        )\n\n        await storage.pull_code()\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        url: str,\n        pull_interval: Optional[int] = 60,\n        **settings: Any,\n    ):\n        self._url = url\n        self._settings = settings\n        self._logger = get_logger(\"runner.storage.remote-storage\")\n        self._storage_base_path = Path.cwd()\n        self._pull_interval = pull_interval\n\n    @staticmethod\n    def _get_required_package_for_scheme(scheme: str) -&gt; Optional[str]:\n        # attempt to discover the package name for the given scheme\n        # from fsspec's registry\n        known_implementation = fsspec.registry.get(scheme)\n        if known_implementation:\n            return known_implementation.__module__.split(\".\")[0]\n        # if we don't know the implementation, try to guess it for some\n        # common schemes\n        elif scheme == \"s3\":\n            return \"s3fs\"\n        elif scheme == \"gs\" or scheme == \"gcs\":\n            return \"gcsfs\"\n        elif scheme == \"abfs\" or scheme == \"az\":\n            return \"adlfs\"\n        else:\n            return None\n\n    @property\n    def _filesystem(self) -&gt; fsspec.AbstractFileSystem:\n        scheme, _, _, _, _ = urlsplit(self._url)\n\n        def replace_blocks_with_values(obj: Any) -&gt; Any:\n            if isinstance(obj, Block):\n                if hasattr(obj, \"get\"):\n                    return obj.get()\n                if hasattr(obj, \"value\"):\n                    return obj.value\n                else:\n                    return obj.dict()\n            return obj\n\n        settings_with_block_values = visit_collection(\n            self._settings, replace_blocks_with_values, return_data=True\n        )\n\n        return fsspec.filesystem(scheme, **settings_with_block_values)\n\n    def set_base_path(self, path: Path):\n        self._storage_base_path = path\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        \"\"\"\n        The interval at which contents from remote storage should be pulled to\n        local storage. If None, remote storage will perform a one-time sync.\n        \"\"\"\n        return self._pull_interval\n\n    @property\n    def destination(self) -&gt; Path:\n        \"\"\"\n        The local file path to pull contents from remote storage to.\n        \"\"\"\n        return self._storage_base_path / self._remote_path\n\n    @property\n    def _remote_path(self) -&gt; Path:\n        \"\"\"\n        The remote file path to pull contents from remote storage to.\n        \"\"\"\n        _, netloc, urlpath, _, _ = urlsplit(self._url)\n        return Path(netloc) / Path(urlpath.lstrip(\"/\"))\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls contents from remote storage to the local filesystem.\n        \"\"\"\n        self._logger.debug(\n            \"Pulling contents from remote storage '%s' to '%s'...\",\n            self._url,\n            self.destination,\n        )\n\n        if not self.destination.exists():\n            self.destination.mkdir(parents=True, exist_ok=True)\n\n        remote_path = str(self._remote_path) + \"/\"\n\n        try:\n            await from_async.wait_for_call_in_new_thread(\n                create_call(\n                    self._filesystem.get,\n                    remote_path,\n                    str(self.destination),\n                    recursive=True,\n                )\n            )\n        except Exception as exc:\n            raise RuntimeError(\n                f\"Failed to pull contents from remote storage {self._url!r} to\"\n                f\" {self.destination!r}\"\n            ) from exc\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n\n        def replace_block_with_placeholder(obj: Any) -&gt; Any:\n            if isinstance(obj, Block):\n                return f\"{{{{ {obj.get_block_placeholder()} }}}}\"\n            return obj\n\n        settings_with_placeholders = visit_collection(\n            self._settings, replace_block_with_placeholder, return_data=True\n        )\n        required_package = self._get_required_package_for_scheme(\n            urlparse(self._url).scheme\n        )\n        step = {\n            \"prefect.deployments.steps.pull_from_remote_storage\": {\n                \"url\": self._url,\n                **settings_with_placeholders,\n            }\n        }\n        if required_package:\n            step[\"prefect.deployments.steps.pull_from_remote_storage\"][\n                \"requires\"\n            ] = required_package\n        return step\n\n    def __eq__(self, __value) -&gt; bool:\n        \"\"\"\n        Equality check for runner storage objects.\n        \"\"\"\n        if isinstance(__value, RemoteStorage):\n            return self._url == __value._url and self._settings == __value._settings\n        return False\n\n    def __repr__(self) -&gt; str:\n        return f\"RemoteStorage(url={self._url!r})\"\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.destination","title":"<code>destination: Path</code>  <code>property</code>","text":"<p>The local file path to pull contents from remote storage to.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.pull_interval","title":"<code>pull_interval: Optional[int]</code>  <code>property</code>","text":"<p>The interval at which contents from remote storage should be pulled to local storage. If None, remote storage will perform a one-time sync.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls contents from remote storage to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls contents from remote storage to the local filesystem.\n    \"\"\"\n    self._logger.debug(\n        \"Pulling contents from remote storage '%s' to '%s'...\",\n        self._url,\n        self.destination,\n    )\n\n    if not self.destination.exists():\n        self.destination.mkdir(parents=True, exist_ok=True)\n\n    remote_path = str(self._remote_path) + \"/\"\n\n    try:\n        await from_async.wait_for_call_in_new_thread(\n            create_call(\n                self._filesystem.get,\n                remote_path,\n                str(self.destination),\n                recursive=True,\n            )\n        )\n    except Exception as exc:\n        raise RuntimeError(\n            f\"Failed to pull contents from remote storage {self._url!r} to\"\n            f\" {self.destination!r}\"\n        ) from exc\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RemoteStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n\n    def replace_block_with_placeholder(obj: Any) -&gt; Any:\n        if isinstance(obj, Block):\n            return f\"{{{{ {obj.get_block_placeholder()} }}}}\"\n        return obj\n\n    settings_with_placeholders = visit_collection(\n        self._settings, replace_block_with_placeholder, return_data=True\n    )\n    required_package = self._get_required_package_for_scheme(\n        urlparse(self._url).scheme\n    )\n    step = {\n        \"prefect.deployments.steps.pull_from_remote_storage\": {\n            \"url\": self._url,\n            **settings_with_placeholders,\n        }\n    }\n    if required_package:\n        step[\"prefect.deployments.steps.pull_from_remote_storage\"][\n            \"requires\"\n        ] = required_package\n    return step\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage","title":"<code>RunnerStorage</code>","text":"<p>               Bases: <code>Protocol</code></p> <p>A storage interface for a runner to use to retrieve remotely stored flow code.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>@runtime_checkable\nclass RunnerStorage(Protocol):\n    \"\"\"\n    A storage interface for a runner to use to retrieve\n    remotely stored flow code.\n    \"\"\"\n\n    def set_base_path(self, path: Path):\n        \"\"\"\n        Sets the base path to use when pulling contents from remote storage to\n        local storage.\n        \"\"\"\n        ...\n\n    @property\n    def pull_interval(self) -&gt; Optional[int]:\n        \"\"\"\n        The interval at which contents from remote storage should be pulled to\n        local storage. If None, remote storage will perform a one-time sync.\n        \"\"\"\n        ...\n\n    @property\n    def destination(self) -&gt; Path:\n        \"\"\"\n        The local file path to pull contents from remote storage to.\n        \"\"\"\n        ...\n\n    async def pull_code(self):\n        \"\"\"\n        Pulls contents from remote storage to the local filesystem.\n        \"\"\"\n        ...\n\n    def to_pull_step(self) -&gt; dict:\n        \"\"\"\n        Returns a dictionary representation of the storage object that can be\n        used as a deployment pull step.\n        \"\"\"\n        ...\n\n    def __eq__(self, __value) -&gt; bool:\n        \"\"\"\n        Equality check for runner storage objects.\n        \"\"\"\n        ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.destination","title":"<code>destination: Path</code>  <code>property</code>","text":"<p>The local file path to pull contents from remote storage to.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.pull_interval","title":"<code>pull_interval: Optional[int]</code>  <code>property</code>","text":"<p>The interval at which contents from remote storage should be pulled to local storage. If None, remote storage will perform a one-time sync.</p>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.pull_code","title":"<code>pull_code</code>  <code>async</code>","text":"<p>Pulls contents from remote storage to the local filesystem.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>async def pull_code(self):\n    \"\"\"\n    Pulls contents from remote storage to the local filesystem.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.set_base_path","title":"<code>set_base_path</code>","text":"<p>Sets the base path to use when pulling contents from remote storage to local storage.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def set_base_path(self, path: Path):\n    \"\"\"\n    Sets the base path to use when pulling contents from remote storage to\n    local storage.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.RunnerStorage.to_pull_step","title":"<code>to_pull_step</code>","text":"<p>Returns a dictionary representation of the storage object that can be used as a deployment pull step.</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def to_pull_step(self) -&gt; dict:\n    \"\"\"\n    Returns a dictionary representation of the storage object that can be\n    used as a deployment pull step.\n    \"\"\"\n    ...\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/storage/#prefect.runner.storage.create_storage_from_source","title":"<code>create_storage_from_source</code>","text":"<p>Creates a storage object from a URL.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <p>The URL to create a storage object from. Supports git and <code>fsspec</code> URLs.</p> required <code>pull_interval</code> <code>Optional[int]</code> <p>The interval at which to pull contents from remote storage to local storage</p> <code>60</code> <p>Returns:</p> Name Type Description <code>RunnerStorage</code> <code>RunnerStorage</code> <p>A runner storage compatible object</p> Source code in <code>prefect/runner/storage.py</code> <pre><code>def create_storage_from_source(\n    source: str, pull_interval: Optional[int] = 60\n) -&gt; RunnerStorage:\n    \"\"\"\n    Creates a storage object from a URL.\n\n    Args:\n        url: The URL to create a storage object from. Supports git and `fsspec`\n            URLs.\n        pull_interval: The interval at which to pull contents from remote storage to\n            local storage\n\n    Returns:\n        RunnerStorage: A runner storage compatible object\n    \"\"\"\n    logger = get_logger(\"runner.storage\")\n    parsed_source = urlparse(source)\n    if parsed_source.scheme == \"git\" or parsed_source.path.endswith(\".git\"):\n        return GitRepository(url=source, pull_interval=pull_interval)\n    elif parsed_source.scheme in (\"file\", \"local\"):\n        source_path = source.split(\"://\", 1)[-1]\n        return LocalStorage(path=source_path, pull_interval=pull_interval)\n    elif parsed_source.scheme in fsspec.available_protocols():\n        return RemoteStorage(url=source, pull_interval=pull_interval)\n    else:\n        logger.debug(\"No valid fsspec protocol found for URL, assuming local storage.\")\n        return LocalStorage(path=source, pull_interval=pull_interval)\n</code></pre>","tags":["Python API","runner"]},{"location":"api-ref/prefect/runner/utils/","title":"utils","text":"","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils","title":"<code>prefect.runner.utils</code>","text":"","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.inject_schemas_into_openapi","title":"<code>inject_schemas_into_openapi</code>","text":"<p>Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.</p> <p>Parameters:</p> Name Type Description Default <code>webserver</code> <code>FastAPI</code> <p>The FastAPI instance representing the webserver.</p> required <code>schemas_to_inject</code> <code>Dict[str, Any]</code> <p>A dictionary of OpenAPI schemas to integrate.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The augmented OpenAPI schema dictionary.</p> Source code in <code>prefect/runner/utils.py</code> <pre><code>def inject_schemas_into_openapi(\n    webserver: FastAPI, schemas_to_inject: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Augments the webserver's OpenAPI schema with additional schemas from deployments / flows / tasks.\n\n    Args:\n        webserver: The FastAPI instance representing the webserver.\n        schemas_to_inject: A dictionary of OpenAPI schemas to integrate.\n\n    Returns:\n        The augmented OpenAPI schema dictionary.\n    \"\"\"\n    openapi_schema = get_openapi(\n        title=\"FastAPI Prefect Runner\", version=PREFECT_VERSION, routes=webserver.routes\n    )\n\n    augmented_schema = merge_definitions(schemas_to_inject, openapi_schema)\n    return update_refs_to_components(augmented_schema)\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.merge_definitions","title":"<code>merge_definitions</code>","text":"<p>Integrates definitions from injected schemas into the OpenAPI components.</p> <p>Parameters:</p> Name Type Description Default <code>injected_schemas</code> <code>Dict[str, Any]</code> <p>A dictionary of deployment-specific schemas.</p> required <code>openapi_schema</code> <code>Dict[str, Any]</code> <p>The base OpenAPI schema to update.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def merge_definitions(\n    injected_schemas: Dict[str, Any], openapi_schema: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Integrates definitions from injected schemas into the OpenAPI components.\n\n    Args:\n        injected_schemas: A dictionary of deployment-specific schemas.\n        openapi_schema: The base OpenAPI schema to update.\n    \"\"\"\n    openapi_schema_copy = deepcopy(openapi_schema)\n    components = openapi_schema_copy.setdefault(\"components\", {}).setdefault(\n        \"schemas\", {}\n    )\n    for definitions in injected_schemas.values():\n        if \"definitions\" in definitions:\n            for def_name, def_schema in definitions[\"definitions\"].items():\n                def_schema_copy = deepcopy(def_schema)\n                update_refs_in_schema(def_schema_copy, \"#/components/schemas/\")\n                components[def_name] = def_schema_copy\n    return openapi_schema_copy\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.update_refs_in_schema","title":"<code>update_refs_in_schema</code>","text":"<p>Recursively replaces <code>$ref</code> with a new reference base in a schema item.</p> <p>Parameters:</p> Name Type Description Default <code>schema_item</code> <code>Any</code> <p>A schema or part of a schema to update references in.</p> required <code>new_ref</code> <code>str</code> <p>The new base string to replace in <code>$ref</code> values.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def update_refs_in_schema(schema_item: Any, new_ref: str) -&gt; None:\n    \"\"\"\n    Recursively replaces `$ref` with a new reference base in a schema item.\n\n    Args:\n        schema_item: A schema or part of a schema to update references in.\n        new_ref: The new base string to replace in `$ref` values.\n    \"\"\"\n    if isinstance(schema_item, dict):\n        if \"$ref\" in schema_item:\n            schema_item[\"$ref\"] = schema_item[\"$ref\"].replace(\"#/definitions/\", new_ref)\n        for value in schema_item.values():\n            update_refs_in_schema(value, new_ref)\n    elif isinstance(schema_item, list):\n        for item in schema_item:\n            update_refs_in_schema(item, new_ref)\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runner/utils/#prefect.runner.utils.update_refs_to_components","title":"<code>update_refs_to_components</code>","text":"<p>Updates all <code>$ref</code> fields in the OpenAPI schema to reference the components section.</p> <p>Parameters:</p> Name Type Description Default <code>openapi_schema</code> <code>Dict[str, Any]</code> <p>The OpenAPI schema to modify <code>$ref</code> fields in.</p> required Source code in <code>prefect/runner/utils.py</code> <pre><code>def update_refs_to_components(openapi_schema: Dict[str, Any]) -&gt; Dict[str, Any]:\n    \"\"\"\n    Updates all `$ref` fields in the OpenAPI schema to reference the components section.\n\n    Args:\n        openapi_schema: The OpenAPI schema to modify `$ref` fields in.\n    \"\"\"\n    for path_item in openapi_schema.get(\"paths\", {}).values():\n        for operation in path_item.values():\n            schema = (\n                operation.get(\"requestBody\", {})\n                .get(\"content\", {})\n                .get(\"application/json\", {})\n                .get(\"schema\", {})\n            )\n            update_refs_in_schema(schema, \"#/components/schemas/\")\n\n    for definition in openapi_schema.get(\"definitions\", {}).values():\n        update_refs_in_schema(definition, \"#/components/schemas/\")\n\n    return openapi_schema\n</code></pre>","tags":["Python API","runner","utilities"]},{"location":"api-ref/prefect/runtime/deployment/","title":"deployment","text":"","tags":["Python API","deployment context","context"]},{"location":"api-ref/prefect/runtime/deployment/#prefect.runtime.deployment","title":"<code>prefect.runtime.deployment</code>","text":"<p>Access attributes of the current deployment run dynamically.</p> <p>Note that if a deployment is not currently being run, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__DEPLOYMENT</code>.</p> Example usage <pre><code>from prefect.runtime import deployment\n\ndef get_task_runner():\n    task_runner_config = deployment.parameters.get(\"runner_config\", \"default config here\")\n    return DummyTaskRunner(task_runner_specs=task_runner_config)\n</code></pre> Available attributes <ul> <li><code>id</code>: the deployment's unique ID</li> <li><code>name</code>: the deployment's name</li> <li><code>version</code>: the deployment's version</li> <li><code>flow_run_id</code>: the current flow run ID for this deployment</li> <li><code>parameters</code>: the parameters that were passed to this run; note that these do not necessarily     include default values set on the flow function, only the parameter values set on the deployment     object or those directly provided via API for this run</li> </ul>","tags":["Python API","deployment context","context"]},{"location":"api-ref/prefect/runtime/flow_run/","title":"flow_run","text":"","tags":["Python API","flow run context","context"]},{"location":"api-ref/prefect/runtime/flow_run/#prefect.runtime.flow_run","title":"<code>prefect.runtime.flow_run</code>","text":"<p>Access attributes of the current flow run dynamically.</p> <p>Note that if a flow run cannot be discovered, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__FLOW_RUN</code>.</p> Available attributes <ul> <li><code>id</code>: the flow run's unique ID</li> <li><code>tags</code>: the flow run's set of tags</li> <li><code>scheduled_start_time</code>: the flow run's expected scheduled start time; defaults to now if not present</li> <li><code>name</code>: the name of the flow run</li> <li><code>flow_name</code>: the name of the flow</li> <li><code>flow_version</code>: the version of the flow</li> <li><code>parameters</code>: the parameters that were passed to this run; note that these do not necessarily     include default values set on the flow function, only the parameter values explicitly passed for the run</li> <li><code>parent_flow_run_id</code>: the ID of the flow run that triggered this run, if any</li> <li><code>parent_deployment_id</code>: the ID of the deployment that triggered this run, if any</li> <li><code>run_count</code>: the number of times this flow run has been run</li> </ul>","tags":["Python API","flow run context","context"]},{"location":"api-ref/prefect/runtime/task_run/","title":"task_run","text":"","tags":["Python API","task run context","context","task run"]},{"location":"api-ref/prefect/runtime/task_run/#prefect.runtime.task_run","title":"<code>prefect.runtime.task_run</code>","text":"<p>Access attributes of the current task run dynamically.</p> <p>Note that if a task run cannot be discovered, all attributes will return empty values.</p> <p>You can mock the runtime attributes for testing purposes by setting environment variables prefixed with <code>PREFECT__RUNTIME__TASK_RUN</code>.</p> Available attributes <ul> <li><code>id</code>: the task run's unique ID</li> <li><code>name</code>: the name of the task run</li> <li><code>tags</code>: the task run's set of tags</li> <li><code>parameters</code>: the parameters the task was called with</li> <li><code>run_count</code>: the number of times this task run has been run</li> <li><code>task_name</code>: the name of the task</li> </ul>","tags":["Python API","task run context","context","task run"]},{"location":"api-ref/prefect/utilities/annotations/","title":"annotations","text":"","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations","title":"<code>prefect.utilities.annotations</code>","text":"","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.BaseAnnotation","title":"<code>BaseAnnotation</code>","text":"<p>               Bases: <code>namedtuple('BaseAnnotation', field_names='value')</code>, <code>ABC</code>, <code>Generic[T]</code></p> <p>Base class for Prefect annotation types.</p> <p>Inherits from <code>namedtuple</code> for unpacking support in another tools.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class BaseAnnotation(\n    namedtuple(\"BaseAnnotation\", field_names=\"value\"), ABC, Generic[T]\n):\n    \"\"\"\n    Base class for Prefect annotation types.\n\n    Inherits from `namedtuple` for unpacking support in another tools.\n    \"\"\"\n\n    def unwrap(self) -&gt; T:\n        return self.value\n\n    def rewrap(self, value: T) -&gt; \"BaseAnnotation[T]\":\n        return type(self)(value)\n\n    def __eq__(self, other: object) -&gt; bool:\n        if not type(self) == type(other):\n            return False\n        return self.unwrap() == other.unwrap()\n\n    def __repr__(self) -&gt; str:\n        return f\"{type(self).__name__}({self.value!r})\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.NotSet","title":"<code>NotSet</code>","text":"<p>Singleton to distinguish <code>None</code> from a value that is not provided by the user.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class NotSet:\n    \"\"\"\n    Singleton to distinguish `None` from a value that is not provided by the user.\n    \"\"\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.allow_failure","title":"<code>allow_failure</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Wrapper for states or futures.</p> <p>Indicates that the upstream run for this input can be failed.</p> <p>Generally, Prefect will not allow a downstream run to start if any of its inputs are failed. This annotation allows you to opt into receiving a failed input downstream.</p> <p>If the input is from a failed run, the attached exception will be passed to your function.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class allow_failure(BaseAnnotation[T]):\n    \"\"\"\n    Wrapper for states or futures.\n\n    Indicates that the upstream run for this input can be failed.\n\n    Generally, Prefect will not allow a downstream run to start if any of its inputs\n    are failed. This annotation allows you to opt into receiving a failed input\n    downstream.\n\n    If the input is from a failed run, the attached exception will be passed to your\n    function.\n    \"\"\"\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.quote","title":"<code>quote</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Simple wrapper to mark an expression as a different type so it will not be coerced by Prefect. For example, if you want to return a state from a flow without having the flow assume that state.</p> <p>quote will also instruct prefect to ignore introspection of the wrapped object when passed as flow or task parameter. Parameter introspection can be a significant performance hit when the object is a large collection, e.g. a large dictionary or DataFrame, and each element needs to be visited. This will disable task dependency tracking for the wrapped object, but likely will increase performance.</p> <pre><code>@task\ndef my_task(df):\n    ...\n\n@flow\ndef my_flow():\n    my_task(quote(df))\n</code></pre> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class quote(BaseAnnotation[T]):\n    \"\"\"\n    Simple wrapper to mark an expression as a different type so it will not be coerced\n    by Prefect. For example, if you want to return a state from a flow without having\n    the flow assume that state.\n\n    quote will also instruct prefect to ignore introspection of the wrapped object\n    when passed as flow or task parameter. Parameter introspection can be a\n    significant performance hit when the object is a large collection,\n    e.g. a large dictionary or DataFrame, and each element needs to be visited. This\n    will disable task dependency tracking for the wrapped object, but likely will\n    increase performance.\n\n    ```\n    @task\n    def my_task(df):\n        ...\n\n    @flow\n    def my_flow():\n        my_task(quote(df))\n    ```\n    \"\"\"\n\n    def unquote(self) -&gt; T:\n        return self.unwrap()\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/annotations/#prefect.utilities.annotations.unmapped","title":"<code>unmapped</code>","text":"<p>               Bases: <code>BaseAnnotation[T]</code></p> <p>Wrapper for iterables.</p> <p>Indicates that this input should be sent as-is to all runs created during a mapping operation instead of being split.</p> Source code in <code>prefect/utilities/annotations.py</code> <pre><code>class unmapped(BaseAnnotation[T]):\n    \"\"\"\n    Wrapper for iterables.\n\n    Indicates that this input should be sent as-is to all runs created during a mapping\n    operation instead of being split.\n    \"\"\"\n\n    def __getitem__(self, _) -&gt; T:\n        # Internally, this acts as an infinite array where all items are the same value\n        return self.unwrap()\n</code></pre>","tags":["Python API","annotations"]},{"location":"api-ref/prefect/utilities/asyncutils/","title":"asyncutils","text":"","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils","title":"<code>prefect.utilities.asyncutils</code>","text":"<p>Utilities for interoperability with async functions and workers from various contexts.</p>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherIncomplete","title":"<code>GatherIncomplete</code>","text":"<p>               Bases: <code>RuntimeError</code></p> <p>Used to indicate retrieving gather results before completion</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>class GatherIncomplete(RuntimeError):\n    \"\"\"Used to indicate retrieving gather results before completion\"\"\"\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherTaskGroup","title":"<code>GatherTaskGroup</code>","text":"<p>               Bases: <code>TaskGroup</code></p> <p>A task group that gathers results.</p> <p>AnyIO does not include support <code>gather</code>. This class extends the <code>TaskGroup</code> interface to allow simple gathering.</p> <p>See https://github.com/agronholm/anyio/issues/100</p> <p>This class should be instantiated with <code>create_gather_task_group</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>class GatherTaskGroup(anyio.abc.TaskGroup):\n    \"\"\"\n    A task group that gathers results.\n\n    AnyIO does not include support `gather`. This class extends the `TaskGroup`\n    interface to allow simple gathering.\n\n    See https://github.com/agronholm/anyio/issues/100\n\n    This class should be instantiated with `create_gather_task_group`.\n    \"\"\"\n\n    def __init__(self, task_group: anyio.abc.TaskGroup):\n        self._results: Dict[UUID, Any] = {}\n        # The concrete task group implementation to use\n        self._task_group: anyio.abc.TaskGroup = task_group\n\n    async def _run_and_store(self, key, fn, args):\n        self._results[key] = await fn(*args)\n\n    def start_soon(self, fn, *args) -&gt; UUID:\n        key = uuid4()\n        # Put a placeholder in-case the result is retrieved earlier\n        self._results[key] = GatherIncomplete\n        self._task_group.start_soon(self._run_and_store, key, fn, args)\n        return key\n\n    async def start(self, fn, *args):\n        \"\"\"\n        Since `start` returns the result of `task_status.started()` but here we must\n        return the key instead, we just won't support this method for now.\n        \"\"\"\n        raise RuntimeError(\"`GatherTaskGroup` does not support `start`.\")\n\n    def get_result(self, key: UUID) -&gt; Any:\n        result = self._results[key]\n        if result is GatherIncomplete:\n            raise GatherIncomplete(\n                \"Task is not complete. \"\n                \"Results should not be retrieved until the task group exits.\"\n            )\n        return result\n\n    async def __aenter__(self):\n        await self._task_group.__aenter__()\n        return self\n\n    async def __aexit__(self, *tb):\n        try:\n            retval = await self._task_group.__aexit__(*tb)\n            return retval\n        finally:\n            del self._task_group\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.GatherTaskGroup.start","title":"<code>start</code>  <code>async</code>","text":"<p>Since <code>start</code> returns the result of <code>task_status.started()</code> but here we must return the key instead, we just won't support this method for now.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def start(self, fn, *args):\n    \"\"\"\n    Since `start` returns the result of `task_status.started()` but here we must\n    return the key instead, we just won't support this method for now.\n    \"\"\"\n    raise RuntimeError(\"`GatherTaskGroup` does not support `start`.\")\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.add_event_loop_shutdown_callback","title":"<code>add_event_loop_shutdown_callback</code>  <code>async</code>","text":"<p>Adds a callback to the given callable on event loop closure. The callable must be a coroutine function. It will be awaited when the current event loop is shutting down.</p> <p>Requires use of <code>asyncio.run()</code> which waits for async generator shutdown by default or explicit call of <code>asyncio.shutdown_asyncgens()</code>. If the application is entered with <code>asyncio.run_until_complete()</code> and the user calls <code>asyncio.close()</code> without the generator shutdown call, this will not trigger callbacks.</p> <p>asyncio does not provided any other way to clean up a resource when the event loop is about to close.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def add_event_loop_shutdown_callback(coroutine_fn: Callable[[], Awaitable]):\n    \"\"\"\n    Adds a callback to the given callable on event loop closure. The callable must be\n    a coroutine function. It will be awaited when the current event loop is shutting\n    down.\n\n    Requires use of `asyncio.run()` which waits for async generator shutdown by\n    default or explicit call of `asyncio.shutdown_asyncgens()`. If the application\n    is entered with `asyncio.run_until_complete()` and the user calls\n    `asyncio.close()` without the generator shutdown call, this will not trigger\n    callbacks.\n\n    asyncio does not provided _any_ other way to clean up a resource when the event\n    loop is about to close.\n    \"\"\"\n\n    async def on_shutdown(key):\n        # It appears that EVENT_LOOP_GC_REFS is somehow being garbage collected early.\n        # We hold a reference to it so as to preserve it, at least for the lifetime of\n        # this coroutine. See the issue below for the initial report/discussion:\n        # https://github.com/PrefectHQ/prefect/issues/7709#issuecomment-1560021109\n        _ = EVENT_LOOP_GC_REFS\n        try:\n            yield\n        except GeneratorExit:\n            await coroutine_fn()\n            # Remove self from the garbage collection set\n            EVENT_LOOP_GC_REFS.pop(key)\n\n    # Create the iterator and store it in a global variable so it is not garbage\n    # collected. If the iterator is garbage collected before the event loop closes, the\n    # callback will not run. Since this function does not know the scope of the event\n    # loop that is calling it, a reference with global scope is necessary to ensure\n    # garbage collection does not occur until after event loop closure.\n    key = id(on_shutdown)\n    EVENT_LOOP_GC_REFS[key] = on_shutdown(key)\n\n    # Begin iterating so it will be cleaned up as an incomplete generator\n    try:\n        await EVENT_LOOP_GC_REFS[key].__anext__()\n    # There is a poorly understood edge case we've seen in CI where the key is\n    # removed from the dict before we begin generator iteration.\n    except KeyError:\n        logger.warning(\"The event loop shutdown callback was not properly registered. \")\n        pass\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.create_gather_task_group","title":"<code>create_gather_task_group</code>","text":"<p>Create a new task group that gathers results</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def create_gather_task_group() -&gt; GatherTaskGroup:\n    \"\"\"Create a new task group that gathers results\"\"\"\n    # This function matches the AnyIO API which uses callables since the concrete\n    # task group class depends on the async library being used and cannot be\n    # determined until runtime\n    return GatherTaskGroup(anyio.create_task_group())\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.gather","title":"<code>gather</code>  <code>async</code>","text":"<p>Run calls concurrently and gather their results.</p> <p>Unlike <code>asyncio.gather</code> this expects to receive callables not coroutines. This matches <code>anyio</code> semantics.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def gather(*calls: Callable[[], Coroutine[Any, Any, T]]) -&gt; List[T]:\n    \"\"\"\n    Run calls concurrently and gather their results.\n\n    Unlike `asyncio.gather` this expects to receive _callables_ not _coroutines_.\n    This matches `anyio` semantics.\n    \"\"\"\n    keys = []\n    async with create_gather_task_group() as tg:\n        for call in calls:\n            keys.append(tg.start_soon(call))\n    return [tg.get_result(key) for key in keys]\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.is_async_fn","title":"<code>is_async_fn</code>","text":"<p>Returns <code>True</code> if a function returns a coroutine.</p> <p>See https://github.com/microsoft/pyright/issues/2142 for an example use</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def is_async_fn(\n    func: Union[Callable[P, R], Callable[P, Awaitable[R]]],\n) -&gt; TypeGuard[Callable[P, Awaitable[R]]]:\n    \"\"\"\n    Returns `True` if a function returns a coroutine.\n\n    See https://github.com/microsoft/pyright/issues/2142 for an example use\n    \"\"\"\n    while hasattr(func, \"__wrapped__\"):\n        func = func.__wrapped__\n\n    return inspect.iscoroutinefunction(func)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.is_async_gen_fn","title":"<code>is_async_gen_fn</code>","text":"<p>Returns <code>True</code> if a function is an async generator.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def is_async_gen_fn(func):\n    \"\"\"\n    Returns `True` if a function is an async generator.\n    \"\"\"\n    while hasattr(func, \"__wrapped__\"):\n        func = func.__wrapped__\n\n    return inspect.isasyncgenfunction(func)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.raise_async_exception_in_thread","title":"<code>raise_async_exception_in_thread</code>","text":"<p>Raise an exception in a thread asynchronously.</p> <p>This will not interrupt long-running system calls like <code>sleep</code> or <code>wait</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def raise_async_exception_in_thread(thread: Thread, exc_type: Type[BaseException]):\n    \"\"\"\n    Raise an exception in a thread asynchronously.\n\n    This will not interrupt long-running system calls like `sleep` or `wait`.\n    \"\"\"\n    ret = ctypes.pythonapi.PyThreadState_SetAsyncExc(\n        ctypes.c_long(thread.ident), ctypes.py_object(exc_type)\n    )\n    if ret == 0:\n        raise ValueError(\"Thread not found.\")\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_async_from_worker_thread","title":"<code>run_async_from_worker_thread</code>","text":"<p>Runs an async function in the main thread's event loop, blocking the worker thread until completion</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def run_async_from_worker_thread(\n    __fn: Callable[..., Awaitable[T]], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs an async function in the main thread's event loop, blocking the worker\n    thread until completion\n    \"\"\"\n    call = partial(__fn, *args, **kwargs)\n    return anyio.from_thread.run(call)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync","title":"<code>run_sync</code>","text":"<p>Runs a coroutine from a synchronous context. A thread will be spawned to run the event loop if necessary, which allows coroutines to run in environments like Jupyter notebooks where the event loop runs on the main thread.</p> <p>Parameters:</p> Name Type Description Default <code>coroutine</code> <code>Coroutine[Any, Any, T]</code> <p>The coroutine to run.</p> required <p>Returns:</p> Type Description <code>T</code> <p>The return value of the coroutine.</p> Example <p>Basic usage: <pre><code>async def my_async_function(x: int) -&gt; int:\n    return x + 1\n\nrun_sync(my_async_function(1))\n</code></pre></p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def run_sync(coroutine: Coroutine[Any, Any, T]) -&gt; T:\n    \"\"\"\n    Runs a coroutine from a synchronous context. A thread will be spawned\n    to run the event loop if necessary, which allows coroutines to run in\n    environments like Jupyter notebooks where the event loop runs on the main\n    thread.\n\n    Args:\n        coroutine: The coroutine to run.\n\n    Returns:\n        The return value of the coroutine.\n\n    Example:\n        Basic usage:\n        ```python\n        async def my_async_function(x: int) -&gt; int:\n            return x + 1\n\n        run_sync(my_async_function(1))\n        ```\n    \"\"\"\n    # ensure context variables are properly copied to the async frame\n    context = copy_context()\n    try:\n        loop = asyncio.get_running_loop()\n    except RuntimeError:\n        loop = None\n\n    if loop and loop.is_running():\n        with ThreadPoolExecutor() as executor:\n            future = executor.submit(context.run, asyncio.run, coroutine)\n            return cast(T, future.result())\n    else:\n        return context.run(asyncio.run, coroutine)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync_in_interruptible_worker_thread","title":"<code>run_sync_in_interruptible_worker_thread</code>  <code>async</code>","text":"<p>Runs a sync function in a new interruptible worker thread so that the main thread's event loop is not blocked</p> <p>Unlike the anyio function, this performs best-effort cancellation of the thread using the C API. Cancellation will not interrupt system calls like <code>sleep</code>.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def run_sync_in_interruptible_worker_thread(\n    __fn: Callable[..., T], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs a sync function in a new interruptible worker thread so that the main\n    thread's event loop is not blocked\n\n    Unlike the anyio function, this performs best-effort cancellation of the\n    thread using the C API. Cancellation will not interrupt system calls like\n    `sleep`.\n    \"\"\"\n\n    class NotSet:\n        pass\n\n    thread: Thread = None\n    result = NotSet\n    event = asyncio.Event()\n    loop = asyncio.get_running_loop()\n\n    def capture_worker_thread_and_result():\n        # Captures the worker thread that AnyIO is using to execute the function so\n        # the main thread can perform actions on it\n        nonlocal thread, result\n        try:\n            thread = threading.current_thread()\n            result = __fn(*args, **kwargs)\n        except BaseException as exc:\n            result = exc\n            raise\n        finally:\n            loop.call_soon_threadsafe(event.set)\n\n    async def send_interrupt_to_thread():\n        # This task waits until the result is returned from the thread, if cancellation\n        # occurs during that time, we will raise the exception in the thread as well\n        try:\n            await event.wait()\n        except anyio.get_cancelled_exc_class():\n            # NOTE: We could send a SIGINT here which allow us to interrupt system\n            # calls but the interrupt bubbles from the child thread into the main thread\n            # and there is not a clear way to prevent it.\n            raise_async_exception_in_thread(thread, anyio.get_cancelled_exc_class())\n            raise\n\n    async with anyio.create_task_group() as tg:\n        tg.start_soon(send_interrupt_to_thread)\n        tg.start_soon(\n            partial(\n                anyio.to_thread.run_sync,\n                capture_worker_thread_and_result,\n                abandon_on_cancel=True,\n                limiter=get_thread_limiter(),\n            )\n        )\n\n    assert result is not NotSet\n    return result\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.run_sync_in_worker_thread","title":"<code>run_sync_in_worker_thread</code>  <code>async</code>","text":"<p>Runs a sync function in a new worker thread so that the main thread's event loop is not blocked</p> <p>Unlike the anyio function, this defaults to a cancellable thread and does not allow passing arguments to the anyio function so users can pass kwargs to their function.</p> <p>Note that cancellation of threads will not result in interrupted computation, the thread may continue running \u2014 the outcome will just be ignored.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>async def run_sync_in_worker_thread(\n    __fn: Callable[..., T], *args: Any, **kwargs: Any\n) -&gt; T:\n    \"\"\"\n    Runs a sync function in a new worker thread so that the main thread's event loop\n    is not blocked\n\n    Unlike the anyio function, this defaults to a cancellable thread and does not allow\n    passing arguments to the anyio function so users can pass kwargs to their function.\n\n    Note that cancellation of threads will not result in interrupted computation, the\n    thread may continue running \u2014 the outcome will just be ignored.\n    \"\"\"\n    call = partial(__fn, *args, **kwargs)\n    return await anyio.to_thread.run_sync(\n        call, abandon_on_cancel=True, limiter=get_thread_limiter()\n    )\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.sync","title":"<code>sync</code>","text":"<p>Call an async function from a synchronous context. Block until completion.</p> <p>If in an asynchronous context, we will run the code in a separate loop instead of failing but a warning will be displayed since this is not recommended.</p> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def sync(__async_fn: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs) -&gt; T:\n    \"\"\"\n    Call an async function from a synchronous context. Block until completion.\n\n    If in an asynchronous context, we will run the code in a separate loop instead of\n    failing but a warning will be displayed since this is not recommended.\n    \"\"\"\n    if in_async_main_thread():\n        warnings.warn(\n            \"`sync` called from an asynchronous context; \"\n            \"you should `await` the async function directly instead.\"\n        )\n        with start_blocking_portal() as portal:\n            return portal.call(partial(__async_fn, *args, **kwargs))\n    elif in_async_worker_thread():\n        # In a sync context but we can access the event loop thread; send the async\n        # call to the parent\n        return run_async_from_worker_thread(__async_fn, *args, **kwargs)\n    else:\n        # In a sync context and there is no event loop; just create an event loop\n        # to run the async code then tear it down\n        return run_async_in_new_loop(__async_fn, *args, **kwargs)\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/asyncutils/#prefect.utilities.asyncutils.sync_compatible","title":"<code>sync_compatible</code>","text":"<p>Converts an async function into a dual async and sync function.</p> <p>When the returned function is called, we will attempt to determine the best way to enter the async function.</p> <ul> <li>If in a thread with a running event loop, we will return the coroutine for the     caller to await. This is normal async behavior.</li> <li>If in a blocking worker thread with access to an event loop in another thread, we     will submit the async method to the event loop.</li> <li>If we cannot find an event loop, we will create a new one and run the async method     then tear down the loop.</li> </ul> Source code in <code>prefect/utilities/asyncutils.py</code> <pre><code>def sync_compatible(async_fn: T) -&gt; T:\n    \"\"\"\n    Converts an async function into a dual async and sync function.\n\n    When the returned function is called, we will attempt to determine the best way\n    to enter the async function.\n\n    - If in a thread with a running event loop, we will return the coroutine for the\n        caller to await. This is normal async behavior.\n    - If in a blocking worker thread with access to an event loop in another thread, we\n        will submit the async method to the event loop.\n    - If we cannot find an event loop, we will create a new one and run the async method\n        then tear down the loop.\n    \"\"\"\n\n    @wraps(async_fn)\n    def coroutine_wrapper(*args, _sync: Optional[bool] = None, **kwargs):\n        from prefect._internal.concurrency.api import create_call, from_sync\n        from prefect._internal.concurrency.calls import get_current_call, logger\n        from prefect._internal.concurrency.event_loop import get_running_loop\n        from prefect._internal.concurrency.threads import get_global_loop\n        from prefect.settings import PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT\n\n        if PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT or _sync is False:\n            return async_fn(*args, **kwargs)\n\n        global_thread_portal = get_global_loop()\n        current_thread = threading.current_thread()\n        current_call = get_current_call()\n        current_loop = get_running_loop()\n\n        if (\n            current_thread.ident == global_thread_portal.thread.ident\n            and _sync is not True\n        ):\n            logger.debug(f\"{async_fn} --&gt; return coroutine for internal await\")\n            # In the prefect async context; return the coro for us to await\n            return async_fn(*args, **kwargs)\n        elif (\n            in_async_main_thread()\n            and (not current_call or is_async_fn(current_call.fn))\n            and _sync is not True\n        ):\n            # In the main async context; return the coro for them to await\n            logger.debug(f\"{async_fn} --&gt; return coroutine for user await\")\n            return async_fn(*args, **kwargs)\n        elif in_async_worker_thread():\n            # In a sync context but we can access the event loop thread; send the async\n            # call to the parent\n            return run_async_from_worker_thread(async_fn, *args, **kwargs)\n        elif current_loop is not None:\n            logger.debug(f\"{async_fn} --&gt; run async in global loop portal\")\n            # An event loop is already present but we are in a sync context, run the\n            # call in Prefect's event loop thread\n            return from_sync.call_soon_in_loop_thread(\n                create_call(async_fn, *args, **kwargs)\n            ).result()\n        else:\n            logger.debug(f\"{async_fn} --&gt; run async in new loop\")\n            # Run in a new event loop, but use a `Call` for nested context detection\n            call = create_call(async_fn, *args, **kwargs)\n            return call()\n\n    # TODO: This is breaking type hints on the callable... mypy is behind the curve\n    #       on argument annotations. We can still fix this for editors though.\n    if is_async_fn(async_fn):\n        wrapper = coroutine_wrapper\n    elif is_async_gen_fn(async_fn):\n        raise ValueError(\"Async generators cannot yet be marked as `sync_compatible`\")\n    else:\n        raise TypeError(\"The decorated function must be async.\")\n\n    wrapper.aio = async_fn\n    return wrapper\n</code></pre>","tags":["Python API","async"]},{"location":"api-ref/prefect/utilities/callables/","title":"callables","text":"","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables","title":"<code>prefect.utilities.callables</code>","text":"<p>Utilities for working with Python callables.</p>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.ParameterSchema","title":"<code>ParameterSchema</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Simple data model corresponding to an OpenAPI <code>Schema</code>.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>class ParameterSchema(pydantic.BaseModel):\n    \"\"\"Simple data model corresponding to an OpenAPI `Schema`.\"\"\"\n\n    title: Literal[\"Parameters\"] = \"Parameters\"\n    type: Literal[\"object\"] = \"object\"\n    properties: Dict[str, Any] = pydantic.Field(default_factory=dict)\n    required: List[str] = None\n    definitions: Optional[Dict[str, Any]] = None\n\n    def dict(self, *args, **kwargs):\n        \"\"\"Exclude `None` fields by default to comply with\n        the OpenAPI spec.\n        \"\"\"\n        kwargs.setdefault(\"exclude_none\", True)\n        return super().dict(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.ParameterSchema.dict","title":"<code>dict</code>","text":"<p>Exclude <code>None</code> fields by default to comply with the OpenAPI spec.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def dict(self, *args, **kwargs):\n    \"\"\"Exclude `None` fields by default to comply with\n    the OpenAPI spec.\n    \"\"\"\n    kwargs.setdefault(\"exclude_none\", True)\n    return super().dict(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.call_with_parameters","title":"<code>call_with_parameters</code>","text":"<p>Call a function with parameters extracted with <code>get_call_parameters</code></p> <p>The function must have an identical signature to the original function or this will fail. If you need to send to a function with a different signature, extract the args/kwargs using <code>parameters_to_positional_and_keyword</code> directly</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def call_with_parameters(fn: Callable, parameters: Dict[str, Any]):\n    \"\"\"\n    Call a function with parameters extracted with `get_call_parameters`\n\n    The function _must_ have an identical signature to the original function or this\n    will fail. If you need to send to a function with a different signature, extract\n    the args/kwargs using `parameters_to_positional_and_keyword` directly\n    \"\"\"\n    args, kwargs = parameters_to_args_kwargs(fn, parameters)\n    return fn(*args, **kwargs)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.cloudpickle_wrapped_call","title":"<code>cloudpickle_wrapped_call</code>","text":"<p>Serializes a function call using cloudpickle then returns a callable which will execute that call and return a cloudpickle serialized return value</p> <p>This is particularly useful for sending calls to libraries that only use the Python built-in pickler (e.g. <code>anyio.to_process</code> and <code>multiprocessing</code>) but may require a wider range of pickling support.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def cloudpickle_wrapped_call(\n    __fn: Callable, *args: Any, **kwargs: Any\n) -&gt; Callable[[], bytes]:\n    \"\"\"\n    Serializes a function call using cloudpickle then returns a callable which will\n    execute that call and return a cloudpickle serialized return value\n\n    This is particularly useful for sending calls to libraries that only use the Python\n    built-in pickler (e.g. `anyio.to_process` and `multiprocessing`) but may require\n    a wider range of pickling support.\n    \"\"\"\n    payload = cloudpickle.dumps((__fn, args, kwargs))\n    return partial(_run_serialized_call, payload)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.collapse_variadic_parameters","title":"<code>collapse_variadic_parameters</code>","text":"<p>Given a parameter dictionary, move any parameters stored not present in the signature into the variadic keyword argument.</p> <p>Example:</p> <pre><code>```python\ndef foo(a, b, **kwargs):\n    pass\n\nparameters = {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\ncollapse_variadic_parameters(foo, parameters)\n# {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n```\n</code></pre> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def collapse_variadic_parameters(\n    fn: Callable, parameters: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Given a parameter dictionary, move any parameters stored not present in the\n    signature into the variadic keyword argument.\n\n    Example:\n\n        ```python\n        def foo(a, b, **kwargs):\n            pass\n\n        parameters = {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n        collapse_variadic_parameters(foo, parameters)\n        # {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n        ```\n    \"\"\"\n    signature_parameters = inspect.signature(fn).parameters\n    variadic_key = None\n    for key, parameter in signature_parameters.items():\n        if parameter.kind == parameter.VAR_KEYWORD:\n            variadic_key = key\n            break\n\n    missing_parameters = set(parameters.keys()) - set(signature_parameters.keys())\n\n    if not variadic_key and missing_parameters:\n        raise ValueError(\n            f\"Signature for {fn} does not include any variadic keyword argument \"\n            \"but parameters were given that are not present in the signature.\"\n        )\n\n    if variadic_key and not missing_parameters:\n        # variadic key is present but no missing parameters, return parameters unchanged\n        return parameters\n\n    new_parameters = parameters.copy()\n    if variadic_key:\n        new_parameters[variadic_key] = {}\n\n    for key in missing_parameters:\n        new_parameters[variadic_key][key] = new_parameters.pop(key)\n\n    return new_parameters\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.explode_variadic_parameter","title":"<code>explode_variadic_parameter</code>","text":"<p>Given a parameter dictionary, move any parameters stored in a variadic keyword argument parameter (i.e. **kwargs) into the top level.</p> <p>Example:</p> <pre><code>```python\ndef foo(a, b, **kwargs):\n    pass\n\nparameters = {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\nexplode_variadic_parameter(foo, parameters)\n# {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n```\n</code></pre> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def explode_variadic_parameter(\n    fn: Callable, parameters: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Given a parameter dictionary, move any parameters stored in a variadic keyword\n    argument parameter (i.e. **kwargs) into the top level.\n\n    Example:\n\n        ```python\n        def foo(a, b, **kwargs):\n            pass\n\n        parameters = {\"a\": 1, \"b\": 2, \"kwargs\": {\"c\": 3, \"d\": 4}}\n        explode_variadic_parameter(foo, parameters)\n        # {\"a\": 1, \"b\": 2, \"c\": 3, \"d\": 4}\n        ```\n    \"\"\"\n    variadic_key = None\n    for key, parameter in inspect.signature(fn).parameters.items():\n        if parameter.kind == parameter.VAR_KEYWORD:\n            variadic_key = key\n            break\n\n    if not variadic_key:\n        return parameters\n\n    new_parameters = parameters.copy()\n    for key, value in new_parameters.pop(variadic_key, {}).items():\n        new_parameters[key] = value\n\n    return new_parameters\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.generate_parameter_schema","title":"<code>generate_parameter_schema</code>","text":"<p>Generate a parameter schema from a function signature and docstrings.</p> <p>To get a signature from a function, use <code>inspect.signature(fn)</code> or <code>_generate_signature_from_source(source_code, func_name)</code>.</p> <p>Parameters:</p> Name Type Description Default <code>signature</code> <code>Signature</code> <p>The function signature.</p> required <code>docstrings</code> <code>Dict[str, str]</code> <p>A dictionary mapping parameter names to docstrings.</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>The parameter schema.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def generate_parameter_schema(\n    signature: inspect.Signature, docstrings: Dict[str, str]\n) -&gt; ParameterSchema:\n    \"\"\"\n    Generate a parameter schema from a function signature and docstrings.\n\n    To get a signature from a function, use `inspect.signature(fn)` or\n    `_generate_signature_from_source(source_code, func_name)`.\n\n    Args:\n        signature: The function signature.\n        docstrings: A dictionary mapping parameter names to docstrings.\n\n    Returns:\n        ParameterSchema: The parameter schema.\n    \"\"\"\n\n    model_fields = {}\n    aliases = {}\n\n    class ModelConfig:\n        arbitrary_types_allowed = True\n\n    if HAS_PYDANTIC_V2 and not has_v1_type_as_param(signature):\n        create_schema = create_v2_schema\n        process_params = process_v2_params\n    else:\n        create_schema = create_v1_schema\n        process_params = process_v1_params\n\n    for position, param in enumerate(signature.parameters.values()):\n        name, type_, field = process_params(\n            param, position=position, docstrings=docstrings, aliases=aliases\n        )\n        # Generate a Pydantic model at each step so we can check if this parameter\n        # type supports schema generation\n        try:\n            create_schema(\n                \"CheckParameter\", model_cfg=ModelConfig, **{name: (type_, field)}\n            )\n        except (ValueError, TypeError):\n            # This field's type is not valid for schema creation, update it to `Any`\n            type_ = Any\n        model_fields[name] = (type_, field)\n\n    # Generate the final model and schema\n    schema = create_schema(\"Parameters\", model_cfg=ModelConfig, **model_fields)\n    return ParameterSchema(**schema)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.get_call_parameters","title":"<code>get_call_parameters</code>","text":"<p>Bind a call to a function to get parameter/value mapping. Default values on the signature will be included if not overridden.</p> <p>Raises a ParameterBindError if the arguments/kwargs are not valid for the function</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def get_call_parameters(\n    fn: Callable,\n    call_args: Tuple[Any, ...],\n    call_kwargs: Dict[str, Any],\n    apply_defaults: bool = True,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Bind a call to a function to get parameter/value mapping. Default values on the\n    signature will be included if not overridden.\n\n    Raises a ParameterBindError if the arguments/kwargs are not valid for the function\n    \"\"\"\n    try:\n        bound_signature = inspect.signature(fn).bind(*call_args, **call_kwargs)\n    except TypeError as exc:\n        raise ParameterBindError.from_bind_failure(fn, exc, call_args, call_kwargs)\n\n    if apply_defaults:\n        bound_signature.apply_defaults()\n\n    # We cast from `OrderedDict` to `dict` because Dask will not convert futures in an\n    # ordered dictionary to values during execution; this is the default behavior in\n    # Python 3.9 anyway.\n    return dict(bound_signature.arguments)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.get_parameter_defaults","title":"<code>get_parameter_defaults</code>","text":"<p>Get default parameter values for a callable.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def get_parameter_defaults(\n    fn: Callable,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Get default parameter values for a callable.\n    \"\"\"\n    signature = inspect.signature(fn)\n\n    parameter_defaults = {}\n\n    for name, param in signature.parameters.items():\n        if param.default is not signature.empty:\n            parameter_defaults[name] = param.default\n\n    return parameter_defaults\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_docstrings","title":"<code>parameter_docstrings</code>","text":"<p>Given a docstring in Google docstring format, parse the parameter section and return a dictionary that maps parameter names to docstring.</p> <p>Parameters:</p> Name Type Description Default <code>docstring</code> <code>Optional[str]</code> <p>The function's docstring.</p> required <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>Mapping from parameter names to docstrings.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_docstrings(docstring: Optional[str]) -&gt; Dict[str, str]:\n    \"\"\"\n    Given a docstring in Google docstring format, parse the parameter section\n    and return a dictionary that maps parameter names to docstring.\n\n    Args:\n        docstring: The function's docstring.\n\n    Returns:\n        Mapping from parameter names to docstrings.\n    \"\"\"\n    param_docstrings = {}\n\n    if not docstring:\n        return param_docstrings\n\n    with disable_logger(\"griffe.docstrings.google\"), disable_logger(\n        \"griffe.agents.nodes\"\n    ):\n        parsed = parse(Docstring(docstring), Parser.google)\n        for section in parsed:\n            if section.kind != DocstringSectionKind.parameters:\n                continue\n            param_docstrings = {\n                parameter.name: parameter.description for parameter in section.value\n            }\n\n    return param_docstrings\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_schema","title":"<code>parameter_schema</code>","text":"<p>Given a function, generates an OpenAPI-compatible description of the function's arguments, including:     - name     - typing information     - whether it is required     - a default value     - additional constraints (like possible enum values)</p> <p>Parameters:</p> Name Type Description Default <code>fn</code> <code>Callable</code> <p>The function whose arguments will be serialized</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>the argument schema</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_schema(fn: Callable) -&gt; ParameterSchema:\n    \"\"\"Given a function, generates an OpenAPI-compatible description\n    of the function's arguments, including:\n        - name\n        - typing information\n        - whether it is required\n        - a default value\n        - additional constraints (like possible enum values)\n\n    Args:\n        fn (Callable): The function whose arguments will be serialized\n\n    Returns:\n        ParameterSchema: the argument schema\n    \"\"\"\n    try:\n        signature = inspect.signature(fn, eval_str=True)  # novm\n    except (NameError, TypeError):\n        # `eval_str` is not available in Python &lt; 3.10\n        signature = inspect.signature(fn)\n\n    docstrings = parameter_docstrings(inspect.getdoc(fn))\n\n    return generate_parameter_schema(signature, docstrings)\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameter_schema_from_entrypoint","title":"<code>parameter_schema_from_entrypoint</code>","text":"<p>Generate a parameter schema from an entrypoint string.</p> <p>Will load the source code of the function and extract the signature and docstring to generate the schema.</p> <p>Useful for generating a schema for a function when instantiating the function may not be possible due to missing imports or other issues.</p> <p>Parameters:</p> Name Type Description Default <code>entrypoint</code> <code>str</code> <p>A string representing the entrypoint to a function. The string should be in the format of <code>module.path.to.function:do_stuff</code>.</p> required <p>Returns:</p> Name Type Description <code>ParameterSchema</code> <code>ParameterSchema</code> <p>The parameter schema for the function.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameter_schema_from_entrypoint(entrypoint: str) -&gt; ParameterSchema:\n    \"\"\"\n    Generate a parameter schema from an entrypoint string.\n\n    Will load the source code of the function and extract the signature and docstring\n    to generate the schema.\n\n    Useful for generating a schema for a function when instantiating the function may\n    not be possible due to missing imports or other issues.\n\n    Args:\n        entrypoint: A string representing the entrypoint to a function. The string\n            should be in the format of `module.path.to.function:do_stuff`.\n\n    Returns:\n        ParameterSchema: The parameter schema for the function.\n    \"\"\"\n    filepath = None\n    if \":\" in entrypoint:\n        # split by the last colon once to handle Windows paths with drive letters i.e C:\\path\\to\\file.py:do_stuff\n        path, func_name = entrypoint.rsplit(\":\", maxsplit=1)\n        source_code = Path(path).read_text()\n        filepath = path\n    else:\n        path, func_name = entrypoint.rsplit(\".\", maxsplit=1)\n        spec = importlib.util.find_spec(path)\n        if not spec or not spec.origin:\n            raise ValueError(f\"Could not find module {path!r}\")\n        source_code = Path(spec.origin).read_text()\n    signature = _generate_signature_from_source(source_code, func_name, filepath)\n    docstring = _get_docstring_from_source(source_code, func_name)\n    return generate_parameter_schema(signature, parameter_docstrings(docstring))\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.parameters_to_args_kwargs","title":"<code>parameters_to_args_kwargs</code>","text":"<p>Convert a <code>parameters</code> dictionary to positional and keyword arguments</p> <p>The function must have an identical signature to the original function or this will return an empty tuple and dict.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def parameters_to_args_kwargs(\n    fn: Callable,\n    parameters: Dict[str, Any],\n) -&gt; Tuple[Tuple[Any, ...], Dict[str, Any]]:\n    \"\"\"\n    Convert a `parameters` dictionary to positional and keyword arguments\n\n    The function _must_ have an identical signature to the original function or this\n    will return an empty tuple and dict.\n    \"\"\"\n    function_params = dict(inspect.signature(fn).parameters).keys()\n    # Check for parameters that are not present in the function signature\n    unknown_params = parameters.keys() - function_params\n    if unknown_params:\n        raise SignatureMismatchError.from_bad_params(\n            list(function_params), list(parameters.keys())\n        )\n    bound_signature = inspect.signature(fn).bind_partial()\n    bound_signature.arguments = parameters\n\n    return bound_signature.args, bound_signature.kwargs\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/callables/#prefect.utilities.callables.raise_for_reserved_arguments","title":"<code>raise_for_reserved_arguments</code>","text":"<p>Raise a ReservedArgumentError if <code>fn</code> has any parameters that conflict with the names contained in <code>reserved_arguments</code>.</p> Source code in <code>prefect/utilities/callables.py</code> <pre><code>def raise_for_reserved_arguments(fn: Callable, reserved_arguments: Iterable[str]):\n    \"\"\"Raise a ReservedArgumentError if `fn` has any parameters that conflict\n    with the names contained in `reserved_arguments`.\"\"\"\n    function_paremeters = inspect.signature(fn).parameters\n\n    for argument in reserved_arguments:\n        if argument in function_paremeters:\n            raise ReservedArgumentError(\n                f\"{argument!r} is a reserved argument name and cannot be used.\"\n            )\n</code></pre>","tags":["Python API","callables"]},{"location":"api-ref/prefect/utilities/collections/","title":"collections","text":"","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections","title":"<code>prefect.utilities.collections</code>","text":"<p>Utilities for extensions of and operations on Python collections.</p>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.AutoEnum","title":"<code>AutoEnum</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>An enum class that automatically generates value from variable names.</p> <p>This guards against common errors where variable names are updated but values are not.</p> <p>In addition, because AutoEnums inherit from <code>str</code>, they are automatically JSON-serializable.</p> <p>See https://docs.python.org/3/library/enum.html#using-automatic-values</p> Example <pre><code>class MyEnum(AutoEnum):\n    RED = AutoEnum.auto() # equivalent to RED = 'RED'\n    BLUE = AutoEnum.auto() # equivalent to BLUE = 'BLUE'\n</code></pre> Source code in <code>prefect/utilities/collections.py</code> <pre><code>class AutoEnum(str, Enum):\n    \"\"\"\n    An enum class that automatically generates value from variable names.\n\n    This guards against common errors where variable names are updated but values are\n    not.\n\n    In addition, because AutoEnums inherit from `str`, they are automatically\n    JSON-serializable.\n\n    See https://docs.python.org/3/library/enum.html#using-automatic-values\n\n    Example:\n        ```python\n        class MyEnum(AutoEnum):\n            RED = AutoEnum.auto() # equivalent to RED = 'RED'\n            BLUE = AutoEnum.auto() # equivalent to BLUE = 'BLUE'\n        ```\n    \"\"\"\n\n    def _generate_next_value_(name, start, count, last_values):\n        return name\n\n    @staticmethod\n    def auto():\n        \"\"\"\n        Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n        \"\"\"\n        return auto()\n\n    def __repr__(self) -&gt; str:\n        return f\"{type(self).__name__}.{self.value}\"\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.AutoEnum.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.StopVisiting","title":"<code>StopVisiting</code>","text":"<p>               Bases: <code>BaseException</code></p> <p>A special exception used to stop recursive visits in <code>visit_collection</code>.</p> <p>When raised, the expression is returned without modification and recursive visits in that path will end.</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>class StopVisiting(BaseException):\n    \"\"\"\n    A special exception used to stop recursive visits in `visit_collection`.\n\n    When raised, the expression is returned without modification and recursive visits\n    in that path will end.\n    \"\"\"\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.batched_iterable","title":"<code>batched_iterable</code>","text":"<p>Yield batches of a certain size from an iterable</p> <p>Parameters:</p> Name Type Description Default <code>iterable</code> <code>Iterable</code> <p>An iterable</p> required <code>size</code> <code>int</code> <p>The batch size to return</p> required <p>Yields:</p> Name Type Description <code>tuple</code> <code>T</code> <p>A batch of the iterable</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def batched_iterable(iterable: Iterable[T], size: int) -&gt; Iterator[Tuple[T, ...]]:\n    \"\"\"\n    Yield batches of a certain size from an iterable\n\n    Args:\n        iterable (Iterable): An iterable\n        size (int): The batch size to return\n\n    Yields:\n        tuple: A batch of the iterable\n    \"\"\"\n    it = iter(iterable)\n    while True:\n        batch = tuple(itertools.islice(it, size))\n        if not batch:\n            break\n        yield batch\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.dict_to_flatdict","title":"<code>dict_to_flatdict</code>","text":"<p>Converts a (nested) dictionary to a flattened representation.</p> <p>Each key of the flat dict will be a CompoundKey tuple containing the \"chain of keys\" for the corresponding value.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>dict</code> <p>The dictionary to flatten</p> required <code>_parent</code> <code>Tuple</code> <p>The current parent for recursion</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[Tuple[KT, ...], Any]</code> <p>A flattened dict of the same type as dct</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def dict_to_flatdict(\n    dct: Dict[KT, Union[Any, Dict[KT, Any]]], _parent: Tuple[KT, ...] = None\n) -&gt; Dict[Tuple[KT, ...], Any]:\n    \"\"\"Converts a (nested) dictionary to a flattened representation.\n\n    Each key of the flat dict will be a CompoundKey tuple containing the \"chain of keys\"\n    for the corresponding value.\n\n    Args:\n        dct (dict): The dictionary to flatten\n        _parent (Tuple, optional): The current parent for recursion\n\n    Returns:\n        A flattened dict of the same type as dct\n    \"\"\"\n    typ = cast(Type[Dict[Tuple[KT, ...], Any]], type(dct))\n    items: List[Tuple[Tuple[KT, ...], Any]] = []\n    parent = _parent or tuple()\n\n    for k, v in dct.items():\n        k_parent = tuple(parent + (k,))\n        # if v is a non-empty dict, recurse\n        if isinstance(v, dict) and v:\n            items.extend(dict_to_flatdict(v, _parent=k_parent).items())\n        else:\n            items.append((k_parent, v))\n    return typ(items)\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.extract_instances","title":"<code>extract_instances</code>","text":"<p>Extract objects from a file and returns a dict of type -&gt; instances</p> <p>Parameters:</p> Name Type Description Default <code>objects</code> <code>Iterable</code> <p>An iterable of objects</p> required <code>types</code> <code>Union[Type[T], Tuple[Type[T], ...]]</code> <p>A type or tuple of types to extract, defaults to all objects</p> <code>object</code> <p>Returns:</p> Type Description <code>Union[List[T], Dict[Type[T], T]]</code> <p>If a single type is given: a list of instances of that type</p> <code>Union[List[T], Dict[Type[T], T]]</code> <p>If a tuple of types is given: a mapping of type to a list of instances</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def extract_instances(\n    objects: Iterable,\n    types: Union[Type[T], Tuple[Type[T], ...]] = object,\n) -&gt; Union[List[T], Dict[Type[T], T]]:\n    \"\"\"\n    Extract objects from a file and returns a dict of type -&gt; instances\n\n    Args:\n        objects: An iterable of objects\n        types: A type or tuple of types to extract, defaults to all objects\n\n    Returns:\n        If a single type is given: a list of instances of that type\n        If a tuple of types is given: a mapping of type to a list of instances\n    \"\"\"\n    types = ensure_iterable(types)\n\n    # Create a mapping of type -&gt; instance from the exec values\n    ret = defaultdict(list)\n\n    for o in objects:\n        # We iterate here so that the key is the passed type rather than type(o)\n        for type_ in types:\n            if isinstance(o, type_):\n                ret[type_].append(o)\n\n    if len(types) == 1:\n        return ret[types[0]]\n\n    return ret\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.flatdict_to_dict","title":"<code>flatdict_to_dict</code>","text":"<p>Converts a flattened dictionary back to a nested dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>dict</code> <p>The dictionary to be nested. Each key should be a tuple of keys as generated by <code>dict_to_flatdict</code></p> required <p>Returns     A nested dict of the same type as dct</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def flatdict_to_dict(\n    dct: Dict[Tuple[KT, ...], VT],\n) -&gt; Dict[KT, Union[VT, Dict[KT, VT]]]:\n    \"\"\"Converts a flattened dictionary back to a nested dictionary.\n\n    Args:\n        dct (dict): The dictionary to be nested. Each key should be a tuple of keys\n            as generated by `dict_to_flatdict`\n\n    Returns\n        A nested dict of the same type as dct\n    \"\"\"\n    typ = type(dct)\n    result = cast(Dict[KT, Union[VT, Dict[KT, VT]]], typ())\n    for key_tuple, value in dct.items():\n        current_dict = result\n        for prefix_key in key_tuple[:-1]:\n            # Build nested dictionaries up for the current key tuple\n            # Use `setdefault` in case the nested dict has already been created\n            current_dict = current_dict.setdefault(prefix_key, typ())  # type: ignore\n        # Set the value\n        current_dict[key_tuple[-1]] = value\n\n    return result\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.get_from_dict","title":"<code>get_from_dict</code>","text":"<p>Fetch a value from a nested dictionary or list using a sequence of keys.</p> <p>This function allows to fetch a value from a deeply nested structure of dictionaries and lists using either a dot-separated string or a list of keys. If a requested key does not exist, the function returns the provided default value.</p> <p>Parameters:</p> Name Type Description Default <code>dct</code> <code>Dict</code> <p>The nested dictionary or list from which to fetch the value.</p> required <code>keys</code> <code>Union[str, List[str]]</code> <p>The sequence of keys to use for access. Can be a dot-separated string or a list of keys. List indices can be included in the sequence as either integer keys or as string indices in square brackets.</p> required <code>default</code> <code>Any</code> <p>The default value to return if the requested key path does not exist. Defaults to None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Any</code> <p>The fetched value if the key exists, or the default value if it does not.</p> <p>get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]') 2 get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1]) 2 get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default') 'default'</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def get_from_dict(dct: Dict, keys: Union[str, List[str]], default: Any = None) -&gt; Any:\n    \"\"\"\n    Fetch a value from a nested dictionary or list using a sequence of keys.\n\n    This function allows to fetch a value from a deeply nested structure\n    of dictionaries and lists using either a dot-separated string or a list\n    of keys. If a requested key does not exist, the function returns the\n    provided default value.\n\n    Args:\n        dct: The nested dictionary or list from which to fetch the value.\n        keys: The sequence of keys to use for access. Can be a\n            dot-separated string or a list of keys. List indices can be included\n            in the sequence as either integer keys or as string indices in square\n            brackets.\n        default: The default value to return if the requested key path does not\n            exist. Defaults to None.\n\n    Returns:\n        The fetched value if the key exists, or the default value if it does not.\n\n    Examples:\n    &gt;&gt;&gt; get_from_dict({'a': {'b': {'c': [1, 2, 3, 4]}}}, 'a.b.c[1]')\n    2\n    &gt;&gt;&gt; get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, ['a', 'b', 1, 'c', 1])\n    2\n    &gt;&gt;&gt; get_from_dict({'a': {'b': [0, {'c': [1, 2]}]}}, 'a.b.1.c.2', 'default')\n    'default'\n    \"\"\"\n    if isinstance(keys, str):\n        keys = keys.replace(\"[\", \".\").replace(\"]\", \"\").split(\".\")\n    try:\n        for key in keys:\n            try:\n                # Try to cast to int to handle list indices\n                key = int(key)\n            except ValueError:\n                # If it's not an int, use the key as-is\n                # for dict lookup\n                pass\n            dct = dct[key]\n        return dct\n    except (TypeError, KeyError, IndexError):\n        return default\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.isiterable","title":"<code>isiterable</code>","text":"<p>Return a boolean indicating if an object is iterable.</p> <p>Excludes types that are iterable but typically used as singletons: - str - bytes - IO objects</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def isiterable(obj: Any) -&gt; bool:\n    \"\"\"\n    Return a boolean indicating if an object is iterable.\n\n    Excludes types that are iterable but typically used as singletons:\n    - str\n    - bytes\n    - IO objects\n    \"\"\"\n    try:\n        iter(obj)\n    except TypeError:\n        return False\n    else:\n        return not isinstance(obj, (str, bytes, io.IOBase))\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.remove_nested_keys","title":"<code>remove_nested_keys</code>","text":"<p>Recurses a dictionary returns a copy without all keys that match an entry in <code>key_to_remove</code>. Return <code>obj</code> unchanged if not a dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>keys_to_remove</code> <code>List[Hashable]</code> <p>A list of keys to remove from obj obj: The object to remove keys from.</p> required <p>Returns:</p> Type Description <p><code>obj</code> without keys matching an entry in <code>keys_to_remove</code> if <code>obj</code> is a dictionary. <code>obj</code> if <code>obj</code> is not a dictionary.</p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def remove_nested_keys(keys_to_remove: List[Hashable], obj):\n    \"\"\"\n    Recurses a dictionary returns a copy without all keys that match an entry in\n    `key_to_remove`. Return `obj` unchanged if not a dictionary.\n\n    Args:\n        keys_to_remove: A list of keys to remove from obj obj: The object to remove keys\n            from.\n\n    Returns:\n        `obj` without keys matching an entry in `keys_to_remove` if `obj` is a\n            dictionary. `obj` if `obj` is not a dictionary.\n    \"\"\"\n    if not isinstance(obj, dict):\n        return obj\n    return {\n        key: remove_nested_keys(keys_to_remove, value)\n        for key, value in obj.items()\n        if key not in keys_to_remove\n    }\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/collections/#prefect.utilities.collections.visit_collection","title":"<code>visit_collection</code>","text":"<p>This function visits every element of an arbitrary Python collection. If an element is a Python collection, it will be visited recursively. If an element is not a collection, <code>visit_fn</code> will be called with the element. The return value of <code>visit_fn</code> can be used to alter the element if <code>return_data</code> is set.</p> <p>Note that when using <code>return_data</code> a copy of each collection is created to avoid mutating the original object. This may have significant performance penalties and should only be used if you intend to transform the collection.</p> <p>Supported types: - List - Tuple - Set - Dict (note: keys are also visited recursively) - Dataclass - Pydantic model - Prefect annotations</p> <p>Parameters:</p> Name Type Description Default <code>expr</code> <code>Any</code> <p>a Python object or expression</p> required <code>visit_fn</code> <code>Callable[[Any], Awaitable[Any]]</code> <p>an async function that will be applied to every non-collection element of expr.</p> required <code>return_data</code> <code>bool</code> <p>if <code>True</code>, a copy of <code>expr</code> containing data modified by <code>visit_fn</code> will be returned. This is slower than <code>return_data=False</code> (the default).</p> <code>False</code> <code>max_depth</code> <code>int</code> <p>Controls the depth of recursive visitation. If set to zero, no recursion will occur. If set to a positive integer N, visitation will only descend to N layers deep. If set to any negative integer, no limit will be enforced and recursion will continue until terminal items are reached. By default, recursion is unlimited.</p> <code>-1</code> <code>context</code> <code>Optional[dict]</code> <p>An optional dictionary. If passed, the context will be sent to each call to the <code>visit_fn</code>. The context can be mutated by each visitor and will be available for later visits to expressions at the given depth. Values will not be available \"up\" a level from a given expression.</p> <p>The context will be automatically populated with an 'annotation' key when visiting collections within a <code>BaseAnnotation</code> type. This requires the caller to pass <code>context={}</code> and will not be activated by default.</p> <code>None</code> <code>remove_annotations</code> <code>bool</code> <p>If set, annotations will be replaced by their contents. By default, annotations are preserved but their contents are visited.</p> <code>False</code> Source code in <code>prefect/utilities/collections.py</code> <pre><code>def visit_collection(\n    expr,\n    visit_fn: Callable[[Any], Any],\n    return_data: bool = False,\n    max_depth: int = -1,\n    context: Optional[dict] = None,\n    remove_annotations: bool = False,\n):\n    \"\"\"\n    This function visits every element of an arbitrary Python collection. If an element\n    is a Python collection, it will be visited recursively. If an element is not a\n    collection, `visit_fn` will be called with the element. The return value of\n    `visit_fn` can be used to alter the element if `return_data` is set.\n\n    Note that when using `return_data` a copy of each collection is created to avoid\n    mutating the original object. This may have significant performance penalties and\n    should only be used if you intend to transform the collection.\n\n    Supported types:\n    - List\n    - Tuple\n    - Set\n    - Dict (note: keys are also visited recursively)\n    - Dataclass\n    - Pydantic model\n    - Prefect annotations\n\n    Args:\n        expr (Any): a Python object or expression\n        visit_fn (Callable[[Any], Awaitable[Any]]): an async function that\n            will be applied to every non-collection element of expr.\n        return_data (bool): if `True`, a copy of `expr` containing data modified\n            by `visit_fn` will be returned. This is slower than `return_data=False`\n            (the default).\n        max_depth: Controls the depth of recursive visitation. If set to zero, no\n            recursion will occur. If set to a positive integer N, visitation will only\n            descend to N layers deep. If set to any negative integer, no limit will be\n            enforced and recursion will continue until terminal items are reached. By\n            default, recursion is unlimited.\n        context: An optional dictionary. If passed, the context will be sent to each\n            call to the `visit_fn`. The context can be mutated by each visitor and will\n            be available for later visits to expressions at the given depth. Values\n            will not be available \"up\" a level from a given expression.\n\n            The context will be automatically populated with an 'annotation' key when\n            visiting collections within a `BaseAnnotation` type. This requires the\n            caller to pass `context={}` and will not be activated by default.\n        remove_annotations: If set, annotations will be replaced by their contents. By\n            default, annotations are preserved but their contents are visited.\n    \"\"\"\n\n    def visit_nested(expr):\n        # Utility for a recursive call, preserving options and updating the depth.\n        return visit_collection(\n            expr,\n            visit_fn=visit_fn,\n            return_data=return_data,\n            remove_annotations=remove_annotations,\n            max_depth=max_depth - 1,\n            # Copy the context on nested calls so it does not \"propagate up\"\n            context=context.copy() if context is not None else None,\n        )\n\n    def visit_expression(expr):\n        if context is not None:\n            return visit_fn(expr, context)\n        else:\n            return visit_fn(expr)\n\n    # Visit every expression\n    try:\n        result = visit_expression(expr)\n    except StopVisiting:\n        max_depth = 0\n        result = expr\n\n    if return_data:\n        # Only mutate the expression while returning data, otherwise it could be null\n        expr = result\n\n    # Then, visit every child of the expression recursively\n\n    # If we have reached the maximum depth, do not perform any recursion\n    if max_depth == 0:\n        return result if return_data else None\n\n    # Get the expression type; treat iterators like lists\n    typ = list if isinstance(expr, IteratorABC) and isiterable(expr) else type(expr)\n    typ = cast(type, typ)  # mypy treats this as 'object' otherwise and complains\n\n    # Then visit every item in the expression if it is a collection\n    if isinstance(expr, Mock):\n        # Do not attempt to recurse into mock objects\n        result = expr\n\n    elif isinstance(expr, BaseAnnotation):\n        if context is not None:\n            context[\"annotation\"] = expr\n        value = visit_nested(expr.unwrap())\n\n        if remove_annotations:\n            result = value if return_data else None\n        else:\n            result = expr.rewrap(value) if return_data else None\n\n    elif typ in (list, tuple, set):\n        items = [visit_nested(o) for o in expr]\n        result = typ(items) if return_data else None\n\n    elif typ in (dict, OrderedDict):\n        assert isinstance(expr, (dict, OrderedDict))  # typecheck assertion\n        items = [(visit_nested(k), visit_nested(v)) for k, v in expr.items()]\n        result = typ(items) if return_data else None\n\n    elif is_dataclass(expr) and not isinstance(expr, type):\n        values = [visit_nested(getattr(expr, f.name)) for f in fields(expr)]\n        items = {field.name: value for field, value in zip(fields(expr), values)}\n        result = typ(**items) if return_data else None\n\n    elif isinstance(expr, pydantic.BaseModel):\n        # NOTE: This implementation *does not* traverse private attributes\n        # Pydantic does not expose extras in `__fields__` so we use `__fields_set__`\n        # as well to get all of the relevant attributes\n        # Check for presence of attrs even if they're in the field set due to pydantic#4916\n        model_fields = {\n            f for f in expr.__fields_set__.union(expr.__fields__) if hasattr(expr, f)\n        }\n        items = [visit_nested(getattr(expr, key)) for key in model_fields]\n\n        if return_data:\n            # Collect fields with aliases so reconstruction can use the correct field name\n            aliases = {\n                key: value.alias\n                for key, value in expr.__fields__.items()\n                if value.has_alias\n            }\n\n            model_instance = typ(\n                **{\n                    aliases.get(key) or key: value\n                    for key, value in zip(model_fields, items)\n                }\n            )\n\n            # Private attributes are not included in `__fields_set__` but we do not want\n            # to drop them from the model so we restore them after constructing a new\n            # model\n            for attr in expr.__private_attributes__:\n                # Use `object.__setattr__` to avoid errors on immutable models\n                object.__setattr__(model_instance, attr, getattr(expr, attr))\n\n            # Preserve data about which fields were explicitly set on the original model\n            object.__setattr__(model_instance, \"__fields_set__\", expr.__fields_set__)\n            result = model_instance\n        else:\n            result = None\n\n    else:\n        result = result if return_data else None\n\n    return result\n</code></pre>","tags":["Python API","collections"]},{"location":"api-ref/prefect/utilities/compat/","title":"compat","text":"","tags":["Python API","utilities","compatibility"]},{"location":"api-ref/prefect/utilities/compat/#prefect.utilities.compat","title":"<code>prefect.utilities.compat</code>","text":"<p>Utilities for Python version compatibility</p>","tags":["Python API","utilities","compatibility"]},{"location":"api-ref/prefect/utilities/context/","title":"context","text":"","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/context/#prefect.utilities.context","title":"<code>prefect.utilities.context</code>","text":"","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/context/#prefect.utilities.context.get_task_and_flow_run_ids","title":"<code>get_task_and_flow_run_ids</code>","text":"<p>Get the task run and flow run ids from the context, if available.</p> <p>Returns:</p> Type Description <code>Tuple[Optional[UUID], Optional[UUID]]</code> <p>Tuple[Optional[UUID], Optional[UUID]]: a tuple of the task run id and flow run id</p> Source code in <code>prefect/utilities/context.py</code> <pre><code>def get_task_and_flow_run_ids() -&gt; Tuple[Optional[UUID], Optional[UUID]]:\n    \"\"\"\n    Get the task run and flow run ids from the context, if available.\n\n    Returns:\n        Tuple[Optional[UUID], Optional[UUID]]: a tuple of the task run id and flow run id\n    \"\"\"\n    return get_task_run_id(), get_flow_run_id()\n</code></pre>","tags":["Python API","utilities","context"]},{"location":"api-ref/prefect/utilities/dispatch/","title":"dispatch","text":"","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch","title":"<code>prefect.utilities.dispatch</code>","text":"<p>Provides methods for performing dynamic dispatch for actions on base type to one of its subtypes.</p> <p>Example:</p> <pre><code>@register_base_type\nclass Base:\n    @classmethod\n    def __dispatch_key__(cls):\n        return cls.__name__.lower()\n\n\nclass Foo(Base):\n    ...\n\nkey = get_dispatch_key(Foo)  # 'foo'\nlookup_type(Base, key) # Foo\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.get_dispatch_key","title":"<code>get_dispatch_key</code>","text":"<p>Retrieve the unique dispatch key for a class type or instance.</p> <p>This key is defined at the <code>__dispatch_key__</code> attribute. If it is a callable, it will be resolved.</p> <p>If <code>allow_missing</code> is <code>False</code>, an exception will be raised if the attribute is not defined or the key is null. If <code>True</code>, <code>None</code> will be returned in these cases.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def get_dispatch_key(\n    cls_or_instance: Any, allow_missing: bool = False\n) -&gt; Optional[str]:\n    \"\"\"\n    Retrieve the unique dispatch key for a class type or instance.\n\n    This key is defined at the `__dispatch_key__` attribute. If it is a callable, it\n    will be resolved.\n\n    If `allow_missing` is `False`, an exception will be raised if the attribute is not\n    defined or the key is null. If `True`, `None` will be returned in these cases.\n    \"\"\"\n    dispatch_key = getattr(cls_or_instance, \"__dispatch_key__\", None)\n\n    type_name = (\n        cls_or_instance.__name__\n        if isinstance(cls_or_instance, type)\n        else type(cls_or_instance).__name__\n    )\n\n    if dispatch_key is None:\n        if allow_missing:\n            return None\n        raise ValueError(\n            f\"Type {type_name!r} does not define a value for \"\n            \"'__dispatch_key__' which is required for registry lookup.\"\n        )\n\n    if callable(dispatch_key):\n        dispatch_key = dispatch_key()\n\n    if allow_missing and dispatch_key is None:\n        return None\n\n    if not isinstance(dispatch_key, str):\n        raise TypeError(\n            f\"Type {type_name!r} has a '__dispatch_key__' of type \"\n            f\"{type(dispatch_key).__name__} but a type of 'str' is required.\"\n        )\n\n    return dispatch_key\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.get_registry_for_type","title":"<code>get_registry_for_type</code>","text":"<p>Get the first matching registry for a class or any of its base classes.</p> <p>If not found, <code>None</code> is returned.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def get_registry_for_type(cls: T) -&gt; Optional[Dict[str, T]]:\n    \"\"\"\n    Get the first matching registry for a class or any of its base classes.\n\n    If not found, `None` is returned.\n    \"\"\"\n    return next(\n        filter(\n            lambda registry: registry is not None,\n            (_TYPE_REGISTRIES.get(cls) for cls in cls.mro()),\n        ),\n        None,\n    )\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.lookup_type","title":"<code>lookup_type</code>","text":"<p>Look up a dispatch key in the type registry for the given class.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def lookup_type(cls: T, dispatch_key: str) -&gt; T:\n    \"\"\"\n    Look up a dispatch key in the type registry for the given class.\n    \"\"\"\n    # Get the first matching registry for the class or one of its bases\n    registry = get_registry_for_type(cls)\n\n    # Look up this type in the registry\n    subcls = registry.get(dispatch_key)\n\n    if subcls is None:\n        raise KeyError(\n            f\"No class found for dispatch key {dispatch_key!r} in registry for type \"\n            f\"{cls.__name__!r}.\"\n        )\n\n    return subcls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.register_base_type","title":"<code>register_base_type</code>","text":"<p>Register a base type allowing child types to be registered for dispatch with <code>register_type</code>.</p> <p>The base class may or may not define a <code>__dispatch_key__</code> to allow lookups of the base type.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def register_base_type(cls: T) -&gt; T:\n    \"\"\"\n    Register a base type allowing child types to be registered for dispatch with\n    `register_type`.\n\n    The base class may or may not define a `__dispatch_key__` to allow lookups of the\n    base type.\n    \"\"\"\n    registry = _TYPE_REGISTRIES.setdefault(cls, {})\n    base_key = get_dispatch_key(cls, allow_missing=True)\n    if base_key is not None:\n        registry[base_key] = cls\n\n    # Add automatic subtype registration\n    cls.__init_subclass_original__ = getattr(cls, \"__init_subclass__\")\n    cls.__init_subclass__ = _register_subclass_of_base_type\n\n    return cls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dispatch/#prefect.utilities.dispatch.register_type","title":"<code>register_type</code>","text":"<p>Register a type for lookup with dispatch.</p> <p>The type or one of its parents must define a unique <code>__dispatch_key__</code>.</p> <p>One of the classes base types must be registered using <code>register_base_type</code>.</p> Source code in <code>prefect/utilities/dispatch.py</code> <pre><code>def register_type(cls: T) -&gt; T:\n    \"\"\"\n    Register a type for lookup with dispatch.\n\n    The type or one of its parents must define a unique `__dispatch_key__`.\n\n    One of the classes base types must be registered using `register_base_type`.\n    \"\"\"\n    # Lookup the registry for this type\n    registry = get_registry_for_type(cls)\n\n    # Check if a base type is registered\n    if registry is None:\n        # Include a description of registered base types\n        known = \", \".join(repr(base.__name__) for base in _TYPE_REGISTRIES)\n        known_message = (\n            f\" Did you mean to inherit from one of the following known types: {known}.\"\n            if known\n            else \"\"\n        )\n\n        # And a list of all base types for the type they tried to register\n        bases = \", \".join(\n            repr(base.__name__) for base in cls.mro() if base not in (object, cls)\n        )\n\n        raise ValueError(\n            f\"No registry found for type {cls.__name__!r} with bases {bases}.\"\n            + known_message\n        )\n\n    key = get_dispatch_key(cls)\n    existing_value = registry.get(key)\n    if existing_value is not None and id(existing_value) != id(cls):\n        # Get line numbers for debugging\n        file = inspect.getsourcefile(cls)\n        line_number = inspect.getsourcelines(cls)[1]\n        existing_file = inspect.getsourcefile(existing_value)\n        existing_line_number = inspect.getsourcelines(existing_value)[1]\n        warnings.warn(\n            f\"Type {cls.__name__!r} at {file}:{line_number} has key {key!r} that \"\n            f\"matches existing registered type {existing_value.__name__!r} from \"\n            f\"{existing_file}:{existing_line_number}. The existing type will be \"\n            \"overridden.\"\n        )\n\n    # Add to the registry\n    registry[key] = cls\n\n    return cls\n</code></pre>","tags":["Python API","dispatch"]},{"location":"api-ref/prefect/utilities/dockerutils/","title":"dockerutils","text":"","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils","title":"<code>prefect.utilities.dockerutils</code>","text":"","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.BuildError","title":"<code>BuildError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a Docker build fails</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class BuildError(Exception):\n    \"\"\"Raised when a Docker build fails\"\"\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder","title":"<code>ImageBuilder</code>","text":"<p>An interface for preparing Docker build contexts and building images</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class ImageBuilder:\n    \"\"\"An interface for preparing Docker build contexts and building images\"\"\"\n\n    base_directory: Path\n    context: Optional[Path]\n    platform: Optional[str]\n    dockerfile_lines: List[str]\n\n    def __init__(\n        self,\n        base_image: str,\n        base_directory: Path = None,\n        platform: str = None,\n        context: Path = None,\n    ):\n        \"\"\"Create an ImageBuilder\n\n        Args:\n            base_image: the base image to use\n            base_directory: the starting point on your host for relative file locations,\n                defaulting to the current directory\n            context: use this path as the build context (if not provided, will create a\n                temporary directory for the context)\n\n        Returns:\n            The image ID\n        \"\"\"\n        self.base_directory = base_directory or context or Path().absolute()\n        self.temporary_directory = None\n        self.context = context\n        self.platform = platform\n        self.dockerfile_lines = []\n\n        if self.context:\n            dockerfile_path: Path = self.context / \"Dockerfile\"\n            if dockerfile_path.exists():\n                raise ValueError(f\"There is already a Dockerfile at {context}\")\n\n        self.add_line(f\"FROM {base_image}\")\n\n    def __enter__(self) -&gt; Self:\n        if self.context and not self.temporary_directory:\n            return self\n\n        self.temporary_directory = TemporaryDirectory()\n        self.context = Path(self.temporary_directory.__enter__())\n        return self\n\n    def __exit__(\n        self, exc: Type[BaseException], value: BaseException, traceback: TracebackType\n    ) -&gt; None:\n        if not self.temporary_directory:\n            return\n\n        self.temporary_directory.__exit__(exc, value, traceback)\n        self.temporary_directory = None\n        self.context = None\n\n    def add_line(self, line: str) -&gt; None:\n        \"\"\"Add a line to this image's Dockerfile\"\"\"\n        self.add_lines([line])\n\n    def add_lines(self, lines: Iterable[str]) -&gt; None:\n        \"\"\"Add lines to this image's Dockerfile\"\"\"\n        self.dockerfile_lines.extend(lines)\n\n    def copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]):\n        \"\"\"Copy a file to this image\"\"\"\n        if not self.context:\n            raise Exception(\"No context available\")\n\n        if not isinstance(destination, PurePosixPath):\n            destination = PurePosixPath(destination)\n\n        if not isinstance(source, Path):\n            source = Path(source)\n\n        if source.is_absolute():\n            source = source.resolve().relative_to(self.base_directory)\n\n        if self.temporary_directory:\n            os.makedirs(self.context / source.parent, exist_ok=True)\n\n            if source.is_dir():\n                shutil.copytree(self.base_directory / source, self.context / source)\n            else:\n                shutil.copy2(self.base_directory / source, self.context / source)\n\n        self.add_line(f\"COPY {source} {destination}\")\n\n    def write_text(self, text: str, destination: Union[str, PurePosixPath]):\n        if not self.context:\n            raise Exception(\"No context available\")\n\n        if not isinstance(destination, PurePosixPath):\n            destination = PurePosixPath(destination)\n\n        source_hash = hashlib.sha256(text.encode()).hexdigest()\n        (self.context / f\".{source_hash}\").write_text(text)\n        self.add_line(f\"COPY .{source_hash} {destination}\")\n\n    def build(\n        self, pull: bool = False, stream_progress_to: Optional[TextIO] = None\n    ) -&gt; str:\n        \"\"\"Build the Docker image from the current state of the ImageBuilder\n\n        Args:\n            pull: True to pull the base image during the build\n            stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO)\n                that will collect the build output as it is reported by Docker\n\n        Returns:\n            The image ID\n        \"\"\"\n        dockerfile_path: Path = self.context / \"Dockerfile\"\n\n        with dockerfile_path.open(\"w\") as dockerfile:\n            dockerfile.writelines(line + \"\\n\" for line in self.dockerfile_lines)\n\n        try:\n            return build_image(\n                self.context,\n                platform=self.platform,\n                pull=pull,\n                stream_progress_to=stream_progress_to,\n            )\n        finally:\n            os.unlink(dockerfile_path)\n\n    def assert_has_line(self, line: str) -&gt; None:\n        \"\"\"Asserts that the given line is in the Dockerfile\"\"\"\n        all_lines = \"\\n\".join(\n            [f\"  {i+1:&gt;3}: {line}\" for i, line in enumerate(self.dockerfile_lines)]\n        )\n        message = (\n            f\"Expected {line!r} not found in Dockerfile.  Dockerfile:\\n{all_lines}\"\n        )\n        assert line in self.dockerfile_lines, message\n\n    def assert_line_absent(self, line: str) -&gt; None:\n        \"\"\"Asserts that the given line is absent from the Dockerfile\"\"\"\n        if line not in self.dockerfile_lines:\n            return\n\n        i = self.dockerfile_lines.index(line)\n\n        surrounding_lines = \"\\n\".join(\n            [\n                f\"  {i+1:&gt;3}: {line}\"\n                for i, line in enumerate(self.dockerfile_lines[i - 2 : i + 2])\n            ]\n        )\n        message = (\n            f\"Unexpected {line!r} found in Dockerfile at line {i+1}.  \"\n            f\"Surrounding lines:\\n{surrounding_lines}\"\n        )\n\n        assert line not in self.dockerfile_lines, message\n\n    def assert_line_before(self, first: str, second: str) -&gt; None:\n        \"\"\"Asserts that the first line appears before the second line\"\"\"\n        self.assert_has_line(first)\n        self.assert_has_line(second)\n\n        first_index = self.dockerfile_lines.index(first)\n        second_index = self.dockerfile_lines.index(second)\n\n        surrounding_lines = \"\\n\".join(\n            [\n                f\"  {i+1:&gt;3}: {line}\"\n                for i, line in enumerate(\n                    self.dockerfile_lines[second_index - 2 : first_index + 2]\n                )\n            ]\n        )\n\n        message = (\n            f\"Expected {first!r} to appear before {second!r} in the Dockerfile, but \"\n            f\"{first!r} was at line {first_index+1} and {second!r} as at line \"\n            f\"{second_index+1}.  Surrounding lines:\\n{surrounding_lines}\"\n        )\n\n        assert first_index &lt; second_index, message\n\n    def assert_line_after(self, second: str, first: str) -&gt; None:\n        \"\"\"Asserts that the second line appears after the first line\"\"\"\n        self.assert_line_before(first, second)\n\n    def assert_has_file(self, source: Path, container_path: PurePosixPath) -&gt; None:\n        \"\"\"Asserts that the given file or directory will be copied into the container\n        at the given path\"\"\"\n        if source.is_absolute():\n            source = source.relative_to(self.base_directory)\n\n        self.assert_has_line(f\"COPY {source} {container_path}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.add_line","title":"<code>add_line</code>","text":"<p>Add a line to this image's Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def add_line(self, line: str) -&gt; None:\n    \"\"\"Add a line to this image's Dockerfile\"\"\"\n    self.add_lines([line])\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.add_lines","title":"<code>add_lines</code>","text":"<p>Add lines to this image's Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def add_lines(self, lines: Iterable[str]) -&gt; None:\n    \"\"\"Add lines to this image's Dockerfile\"\"\"\n    self.dockerfile_lines.extend(lines)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_has_file","title":"<code>assert_has_file</code>","text":"<p>Asserts that the given file or directory will be copied into the container at the given path</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_has_file(self, source: Path, container_path: PurePosixPath) -&gt; None:\n    \"\"\"Asserts that the given file or directory will be copied into the container\n    at the given path\"\"\"\n    if source.is_absolute():\n        source = source.relative_to(self.base_directory)\n\n    self.assert_has_line(f\"COPY {source} {container_path}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_has_line","title":"<code>assert_has_line</code>","text":"<p>Asserts that the given line is in the Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_has_line(self, line: str) -&gt; None:\n    \"\"\"Asserts that the given line is in the Dockerfile\"\"\"\n    all_lines = \"\\n\".join(\n        [f\"  {i+1:&gt;3}: {line}\" for i, line in enumerate(self.dockerfile_lines)]\n    )\n    message = (\n        f\"Expected {line!r} not found in Dockerfile.  Dockerfile:\\n{all_lines}\"\n    )\n    assert line in self.dockerfile_lines, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_absent","title":"<code>assert_line_absent</code>","text":"<p>Asserts that the given line is absent from the Dockerfile</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_absent(self, line: str) -&gt; None:\n    \"\"\"Asserts that the given line is absent from the Dockerfile\"\"\"\n    if line not in self.dockerfile_lines:\n        return\n\n    i = self.dockerfile_lines.index(line)\n\n    surrounding_lines = \"\\n\".join(\n        [\n            f\"  {i+1:&gt;3}: {line}\"\n            for i, line in enumerate(self.dockerfile_lines[i - 2 : i + 2])\n        ]\n    )\n    message = (\n        f\"Unexpected {line!r} found in Dockerfile at line {i+1}.  \"\n        f\"Surrounding lines:\\n{surrounding_lines}\"\n    )\n\n    assert line not in self.dockerfile_lines, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_after","title":"<code>assert_line_after</code>","text":"<p>Asserts that the second line appears after the first line</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_after(self, second: str, first: str) -&gt; None:\n    \"\"\"Asserts that the second line appears after the first line\"\"\"\n    self.assert_line_before(first, second)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.assert_line_before","title":"<code>assert_line_before</code>","text":"<p>Asserts that the first line appears before the second line</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def assert_line_before(self, first: str, second: str) -&gt; None:\n    \"\"\"Asserts that the first line appears before the second line\"\"\"\n    self.assert_has_line(first)\n    self.assert_has_line(second)\n\n    first_index = self.dockerfile_lines.index(first)\n    second_index = self.dockerfile_lines.index(second)\n\n    surrounding_lines = \"\\n\".join(\n        [\n            f\"  {i+1:&gt;3}: {line}\"\n            for i, line in enumerate(\n                self.dockerfile_lines[second_index - 2 : first_index + 2]\n            )\n        ]\n    )\n\n    message = (\n        f\"Expected {first!r} to appear before {second!r} in the Dockerfile, but \"\n        f\"{first!r} was at line {first_index+1} and {second!r} as at line \"\n        f\"{second_index+1}.  Surrounding lines:\\n{surrounding_lines}\"\n    )\n\n    assert first_index &lt; second_index, message\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.build","title":"<code>build</code>","text":"<p>Build the Docker image from the current state of the ImageBuilder</p> <p>Parameters:</p> Name Type Description Default <code>pull</code> <code>bool</code> <p>True to pull the base image during the build</p> <code>False</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The image ID</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def build(\n    self, pull: bool = False, stream_progress_to: Optional[TextIO] = None\n) -&gt; str:\n    \"\"\"Build the Docker image from the current state of the ImageBuilder\n\n    Args:\n        pull: True to pull the base image during the build\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO)\n            that will collect the build output as it is reported by Docker\n\n    Returns:\n        The image ID\n    \"\"\"\n    dockerfile_path: Path = self.context / \"Dockerfile\"\n\n    with dockerfile_path.open(\"w\") as dockerfile:\n        dockerfile.writelines(line + \"\\n\" for line in self.dockerfile_lines)\n\n    try:\n        return build_image(\n            self.context,\n            platform=self.platform,\n            pull=pull,\n            stream_progress_to=stream_progress_to,\n        )\n    finally:\n        os.unlink(dockerfile_path)\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.ImageBuilder.copy","title":"<code>copy</code>","text":"<p>Copy a file to this image</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def copy(self, source: Union[str, Path], destination: Union[str, PurePosixPath]):\n    \"\"\"Copy a file to this image\"\"\"\n    if not self.context:\n        raise Exception(\"No context available\")\n\n    if not isinstance(destination, PurePosixPath):\n        destination = PurePosixPath(destination)\n\n    if not isinstance(source, Path):\n        source = Path(source)\n\n    if source.is_absolute():\n        source = source.resolve().relative_to(self.base_directory)\n\n    if self.temporary_directory:\n        os.makedirs(self.context / source.parent, exist_ok=True)\n\n        if source.is_dir():\n            shutil.copytree(self.base_directory / source, self.context / source)\n        else:\n            shutil.copy2(self.base_directory / source, self.context / source)\n\n    self.add_line(f\"COPY {source} {destination}\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.PushError","title":"<code>PushError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a Docker image push fails</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>class PushError(Exception):\n    \"\"\"Raised when a Docker image push fails\"\"\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.build_image","title":"<code>build_image</code>","text":"<p>Builds a Docker image, returning the image ID</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>Path</code> <p>the root directory for the Docker build context</p> required <code>dockerfile</code> <code>str</code> <p>the path to the Dockerfile, relative to the context</p> <code>'Dockerfile'</code> <code>tag</code> <code>Optional[str]</code> <p>the tag to give this image</p> <code>None</code> <code>pull</code> <code>bool</code> <p>True to pull the base image during the build</p> <code>False</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The image ID</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@silence_docker_warnings()\ndef build_image(\n    context: Path,\n    dockerfile: str = \"Dockerfile\",\n    tag: Optional[str] = None,\n    pull: bool = False,\n    platform: str = None,\n    stream_progress_to: Optional[TextIO] = None,\n    **kwargs,\n) -&gt; str:\n    \"\"\"Builds a Docker image, returning the image ID\n\n    Args:\n        context: the root directory for the Docker build context\n        dockerfile: the path to the Dockerfile, relative to the context\n        tag: the tag to give this image\n        pull: True to pull the base image during the build\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that\n            will collect the build output as it is reported by Docker\n\n    Returns:\n        The image ID\n    \"\"\"\n\n    if not context:\n        raise ValueError(\"context required to build an image\")\n\n    if not Path(context).exists():\n        raise ValueError(f\"Context path {context} does not exist\")\n\n    kwargs = {key: kwargs[key] for key in kwargs if key not in [\"decode\", \"labels\"]}\n\n    image_id = None\n    with docker_client() as client:\n        events = client.api.build(\n            path=str(context),\n            tag=tag,\n            dockerfile=dockerfile,\n            pull=pull,\n            decode=True,\n            labels=IMAGE_LABELS,\n            platform=platform,\n            **kwargs,\n        )\n\n        try:\n            for event in events:\n                if \"stream\" in event:\n                    if not stream_progress_to:\n                        continue\n                    stream_progress_to.write(event[\"stream\"])\n                    stream_progress_to.flush()\n                elif \"aux\" in event:\n                    image_id = event[\"aux\"][\"ID\"]\n                elif \"error\" in event:\n                    raise BuildError(event[\"error\"])\n                elif \"message\" in event:\n                    raise BuildError(event[\"message\"])\n        except docker.errors.APIError as e:\n            raise BuildError(e.explanation) from e\n\n    assert image_id, \"The Docker daemon did not return an image ID\"\n    return image_id\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.docker_client","title":"<code>docker_client</code>","text":"<p>Get the environmentally-configured Docker client</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@contextmanager\ndef docker_client() -&gt; Generator[\"DockerClient\", None, None]:\n    \"\"\"Get the environmentally-configured Docker client\"\"\"\n    client = None\n    try:\n        with silence_docker_warnings():\n            client = docker.DockerClient.from_env()\n\n            yield client\n    except docker.errors.DockerException as exc:\n        raise RuntimeError(\n            \"This error is often thrown because Docker is not running. Please ensure Docker is running.\"\n        ) from exc\n    finally:\n        client is not None and client.close()\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.format_outlier_version_name","title":"<code>format_outlier_version_name</code>","text":"<p>Formats outlier docker version names to pass <code>packaging.version.parse</code> validation - Current cases are simple, but creates stub for more complicated formatting if eventually needed. - Example outlier versions that throw a parsing exception:   - \"20.10.0-ce\" (variant of community edition label)   - \"20.10.0-ee\" (variant of enterprise edition label)</p> <p>Parameters:</p> Name Type Description Default <code>version</code> <code>str</code> <p>raw docker version value</p> required <p>Returns:</p> Name Type Description <code>str</code> <p>value that can pass <code>packaging.version.parse</code> validation</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def format_outlier_version_name(version: str):\n    \"\"\"\n    Formats outlier docker version names to pass `packaging.version.parse` validation\n    - Current cases are simple, but creates stub for more complicated formatting if eventually needed.\n    - Example outlier versions that throw a parsing exception:\n      - \"20.10.0-ce\" (variant of community edition label)\n      - \"20.10.0-ee\" (variant of enterprise edition label)\n\n    Args:\n        version (str): raw docker version value\n\n    Returns:\n        str: value that can pass `packaging.version.parse` validation\n    \"\"\"\n    return version.replace(\"-ce\", \"\").replace(\"-ee\", \"\")\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.generate_default_dockerfile","title":"<code>generate_default_dockerfile</code>","text":"<p>Generates a default Dockerfile used for deploying flows. The Dockerfile is written to a temporary file and yielded. The temporary file is removed after the context manager exits.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>context</code> <p>The context to use for the Dockerfile. Defaults to the current working directory.</p> required Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@contextmanager\ndef generate_default_dockerfile(context: Optional[Path] = None):\n    \"\"\"\n    Generates a default Dockerfile used for deploying flows. The Dockerfile is written\n    to a temporary file and yielded. The temporary file is removed after the context\n    manager exits.\n\n    Args:\n        - context: The context to use for the Dockerfile. Defaults to\n            the current working directory.\n    \"\"\"\n    if not context:\n        context = Path.cwd()\n    lines = []\n    base_image = get_prefect_image_name()\n    lines.append(f\"FROM {base_image}\")\n    dir_name = context.name\n\n    if (context / \"requirements.txt\").exists():\n        lines.append(f\"COPY requirements.txt /opt/prefect/{dir_name}/requirements.txt\")\n        lines.append(\n            f\"RUN python -m pip install -r /opt/prefect/{dir_name}/requirements.txt\"\n        )\n\n    lines.append(f\"COPY . /opt/prefect/{dir_name}/\")\n    lines.append(f\"WORKDIR /opt/prefect/{dir_name}/\")\n\n    temp_dockerfile = context / \"Dockerfile\"\n    if Path(temp_dockerfile).exists():\n        raise RuntimeError(\n            \"Failed to generate Dockerfile. Dockerfile already exists in the\"\n            \" current directory.\"\n        )\n\n    with Path(temp_dockerfile).open(\"w\") as f:\n        f.writelines(line + \"\\n\" for line in lines)\n\n    try:\n        yield temp_dockerfile\n    finally:\n        temp_dockerfile.unlink()\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.get_prefect_image_name","title":"<code>get_prefect_image_name</code>","text":"<p>Get the Prefect image name matching the current Prefect and Python versions.</p> <p>Parameters:</p> Name Type Description Default <code>prefect_version</code> <code>str</code> <p>An optional override for the Prefect version.</p> <code>None</code> <code>python_version</code> <code>str</code> <p>An optional override for the Python version; must be at the minor level e.g. '3.9'.</p> <code>None</code> <code>flavor</code> <code>str</code> <p>An optional alternative image flavor to build, like 'conda'</p> <code>None</code> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def get_prefect_image_name(\n    prefect_version: str = None, python_version: str = None, flavor: str = None\n) -&gt; str:\n    \"\"\"\n    Get the Prefect image name matching the current Prefect and Python versions.\n\n    Args:\n        prefect_version: An optional override for the Prefect version.\n        python_version: An optional override for the Python version; must be at the\n            minor level e.g. '3.9'.\n        flavor: An optional alternative image flavor to build, like 'conda'\n    \"\"\"\n    parsed_version = (prefect_version or prefect.__version__).split(\"+\")\n    is_prod_build = len(parsed_version) == 1\n    prefect_version = (\n        parsed_version[0]\n        if is_prod_build\n        else \"sha-\" + prefect.__version_info__[\"full-revisionid\"][:7]\n    )\n\n    python_version = python_version or python_version_minor()\n\n    tag = slugify(\n        f\"{prefect_version}-python{python_version}\" + (f\"-{flavor}\" if flavor else \"\"),\n        lowercase=False,\n        max_length=128,\n        # Docker allows these characters for tag names\n        regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n    )\n\n    image = \"prefect\" if is_prod_build else \"prefect-dev\"\n    return f\"prefecthq/{image}:{tag}\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.parse_image_tag","title":"<code>parse_image_tag</code>","text":"<p>Parse Docker Image String</p> <ul> <li>If a tag exists, this function parses and returns the image registry and tag,   separately as a tuple.</li> <li>Example 1: 'prefecthq/prefect:latest' -&gt; ('prefecthq/prefect', 'latest')</li> <li>Example 2: 'hostname.io:5050/folder/subfolder:latest' -&gt; ('hostname.io:5050/folder/subfolder', 'latest')</li> <li>Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0</li> <li>Image building tools typically enforce this standard</li> </ul> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of Docker Image</p> required Return Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def parse_image_tag(name: str) -&gt; Tuple[str, Optional[str]]:\n    \"\"\"\n    Parse Docker Image String\n\n    - If a tag exists, this function parses and returns the image registry and tag,\n      separately as a tuple.\n      - Example 1: 'prefecthq/prefect:latest' -&gt; ('prefecthq/prefect', 'latest')\n      - Example 2: 'hostname.io:5050/folder/subfolder:latest' -&gt; ('hostname.io:5050/folder/subfolder', 'latest')\n    - Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0\n      - Image building tools typically enforce this standard\n\n    Args:\n        name (str): Name of Docker Image\n\n    Return:\n        tuple: image registry, image tag\n    \"\"\"\n    tag = None\n    name_parts = name.split(\"/\")\n    # First handles the simplest image names (DockerHub-based, index-free, potentionally with a tag)\n    # - Example: simplename:latest\n    if len(name_parts) == 1:\n        if \":\" in name_parts[0]:\n            image_name, tag = name_parts[0].split(\":\")\n        else:\n            image_name = name_parts[0]\n    else:\n        # 1. Separates index (hostname.io or prefecthq) from path:tag (folder/subfolder:latest or prefect:latest)\n        # 2. Separates path and tag (if tag exists)\n        # 3. Reunites index and path (without tag) as image name\n        index_name = name_parts[0]\n        image_path = \"/\".join(name_parts[1:])\n        if \":\" in image_path:\n            image_path, tag = image_path.split(\":\")\n        image_name = f\"{index_name}/{image_path}\"\n    return image_name, tag\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.push_image","title":"<code>push_image</code>","text":"<p>Pushes a local image to a Docker registry, returning the registry-qualified tag for that image</p> <p>This assumes that the environment's Docker daemon is already authenticated to the given registry, and currently makes no attempt to authenticate.</p> <p>Parameters:</p> Name Type Description Default <code>image_id</code> <code>str</code> <p>a Docker image ID</p> required <code>registry_url</code> <code>str</code> <p>the URL of a Docker registry</p> required <code>name</code> <code>str</code> <p>the name of this image</p> required <code>tag</code> <code>str</code> <p>the tag to give this image (defaults to a short representation of the image's ID)</p> <code>None</code> <code>stream_progress_to</code> <code>Optional[TextIO]</code> <p>an optional stream (like sys.stdout, or an io.TextIO) that will collect the build output as it is reported by Docker</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>A registry-qualified tag, like my-registry.example.com/my-image:abcdefg</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>@silence_docker_warnings()\ndef push_image(\n    image_id: str,\n    registry_url: str,\n    name: str,\n    tag: Optional[str] = None,\n    stream_progress_to: Optional[TextIO] = None,\n) -&gt; str:\n    \"\"\"Pushes a local image to a Docker registry, returning the registry-qualified tag\n    for that image\n\n    This assumes that the environment's Docker daemon is already authenticated to the\n    given registry, and currently makes no attempt to authenticate.\n\n    Args:\n        image_id (str): a Docker image ID\n        registry_url (str): the URL of a Docker registry\n        name (str): the name of this image\n        tag (str): the tag to give this image (defaults to a short representation of\n            the image's ID)\n        stream_progress_to: an optional stream (like sys.stdout, or an io.TextIO) that\n            will collect the build output as it is reported by Docker\n\n    Returns:\n        A registry-qualified tag, like my-registry.example.com/my-image:abcdefg\n    \"\"\"\n\n    if not tag:\n        tag = slugify(pendulum.now(\"utc\").isoformat())\n\n    _, registry, _, _, _ = urlsplit(registry_url)\n    repository = f\"{registry}/{name}\"\n\n    with docker_client() as client:\n        image: \"docker.Image\" = client.images.get(image_id)\n        image.tag(repository, tag=tag)\n        events = client.api.push(repository, tag=tag, stream=True, decode=True)\n        try:\n            for event in events:\n                if \"status\" in event:\n                    if not stream_progress_to:\n                        continue\n                    stream_progress_to.write(event[\"status\"])\n                    if \"progress\" in event:\n                        stream_progress_to.write(\" \" + event[\"progress\"])\n                    stream_progress_to.write(\"\\n\")\n                    stream_progress_to.flush()\n                elif \"error\" in event:\n                    raise PushError(event[\"error\"])\n        finally:\n            client.api.remove_image(f\"{repository}:{tag}\", noprune=True)\n\n    return f\"{repository}:{tag}\"\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.split_repository_path","title":"<code>split_repository_path</code>","text":"<p>Splits a Docker repository path into its namespace and repository components.</p> <p>Parameters:</p> Name Type Description Default <code>repository_path</code> <code>str</code> <p>The Docker repository path to split.</p> required <p>Returns:</p> Type Description <code>Tuple[Optional[str], str]</code> <p>Tuple[Optional[str], str]: A tuple containing the namespace and repository components. - namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present. - repository (Optionals[str]): The repository name.</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def split_repository_path(repository_path: str) -&gt; Tuple[Optional[str], str]:\n    \"\"\"\n    Splits a Docker repository path into its namespace and repository components.\n\n    Args:\n        repository_path: The Docker repository path to split.\n\n    Returns:\n        Tuple[Optional[str], str]: A tuple containing the namespace and repository components.\n            - namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present.\n            - repository (Optionals[str]): The repository name.\n    \"\"\"\n    parts = repository_path.split(\"/\", 2)\n\n    # Check if the path includes a registry and organization or just organization/repository\n    if len(parts) == 3 or (len(parts) == 2 and (\".\" in parts[0] or \":\" in parts[0])):\n        # Namespace includes registry and organization\n        namespace = \"/\".join(parts[:-1])\n        repository = parts[-1]\n    elif len(parts) == 2:\n        # Only organization/repository provided, so namespace is just the first part\n        namespace = parts[0]\n        repository = parts[1]\n    else:\n        # No namespace provided\n        namespace = None\n        repository = parts[0]\n\n    return namespace, repository\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/dockerutils/#prefect.utilities.dockerutils.to_run_command","title":"<code>to_run_command</code>","text":"<p>Convert a process-style list of command arguments to a single Dockerfile RUN instruction.</p> Source code in <code>prefect/utilities/dockerutils.py</code> <pre><code>def to_run_command(command: List[str]) -&gt; str:\n    \"\"\"\n    Convert a process-style list of command arguments to a single Dockerfile RUN\n    instruction.\n    \"\"\"\n    if not command:\n        return \"\"\n\n    run_command = f\"RUN {command[0]}\"\n    if len(command) &gt; 1:\n        run_command += \" \" + \" \".join([repr(arg) for arg in command[1:]])\n\n    # TODO: Consider performing text-wrapping to improve readability of the generated\n    #       Dockerfile\n    # return textwrap.wrap(\n    #     run_command,\n    #     subsequent_indent=\" \" * 4,\n    #     break_on_hyphens=False,\n    #     break_long_words=False\n    # )\n\n    return run_command\n</code></pre>","tags":["Python API","Docker"]},{"location":"api-ref/prefect/utilities/filesystem/","title":"filesystem","text":"","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem","title":"<code>prefect.utilities.filesystem</code>","text":"<p>Utilities for working with file systems</p>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.create_default_ignore_file","title":"<code>create_default_ignore_file</code>","text":"<p>Creates default ignore file in the provided path if one does not already exist; returns boolean specifying whether a file was created.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def create_default_ignore_file(path: str) -&gt; bool:\n    \"\"\"\n    Creates default ignore file in the provided path if one does not already exist; returns boolean specifying\n    whether a file was created.\n    \"\"\"\n    path = pathlib.Path(path)\n    ignore_file = path / \".prefectignore\"\n    if ignore_file.exists():\n        return False\n    default_file = pathlib.Path(prefect.__module_path__) / \".prefectignore\"\n    with ignore_file.open(mode=\"w\") as f:\n        f.write(default_file.read_text())\n    return True\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.filename","title":"<code>filename</code>","text":"<p>Extract the file name from a path with remote file system support</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def filename(path: str) -&gt; str:\n    \"\"\"Extract the file name from a path with remote file system support\"\"\"\n    try:\n        of: OpenFile = fsspec.open(path)\n        sep = of.fs.sep\n    except (ImportError, AttributeError):\n        sep = \"\\\\\" if \"\\\\\" in path else \"/\"\n    return path.split(sep)[-1]\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.filter_files","title":"<code>filter_files</code>","text":"<p>This function accepts a root directory path and a list of file patterns to ignore, and returns a list of files that excludes those that should be ignored.</p> <p>The specification matches that of .gitignore files.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def filter_files(\n    root: str = \".\", ignore_patterns: list = None, include_dirs: bool = True\n) -&gt; set:\n    \"\"\"\n    This function accepts a root directory path and a list of file patterns to ignore, and returns\n    a list of files that excludes those that should be ignored.\n\n    The specification matches that of [.gitignore files](https://git-scm.com/docs/gitignore).\n    \"\"\"\n    if ignore_patterns is None:\n        ignore_patterns = []\n    spec = pathspec.PathSpec.from_lines(\"gitwildmatch\", ignore_patterns)\n    ignored_files = {p.path for p in spec.match_tree_entries(root)}\n    if include_dirs:\n        all_files = {p.path for p in pathspec.util.iter_tree_entries(root)}\n    else:\n        all_files = set(pathspec.util.iter_tree_files(root))\n    included_files = all_files - ignored_files\n    return included_files\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.get_open_file_limit","title":"<code>get_open_file_limit</code>","text":"<p>Get the maximum number of open files allowed for the current process</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def get_open_file_limit() -&gt; int:\n    \"\"\"Get the maximum number of open files allowed for the current process\"\"\"\n\n    try:\n        if os.name == \"nt\":\n            import ctypes\n\n            return ctypes.cdll.ucrtbase._getmaxstdio()\n        else:\n            import resource\n\n            soft_limit, _ = resource.getrlimit(resource.RLIMIT_NOFILE)\n            return soft_limit\n    except Exception:\n        # Catch all exceptions, as ctypes can raise several errors\n        # depending on what went wrong. Return a safe default if we\n        # can't get the limit from the OS.\n        return 200\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.is_local_path","title":"<code>is_local_path</code>","text":"<p>Check if the given path points to a local or remote file system</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def is_local_path(path: Union[str, pathlib.Path, OpenFile]):\n    \"\"\"Check if the given path points to a local or remote file system\"\"\"\n    if isinstance(path, str):\n        try:\n            of = fsspec.open(path)\n        except ImportError:\n            # The path is a remote file system that uses a lib that is not installed\n            return False\n    elif isinstance(path, pathlib.Path):\n        return True\n    elif isinstance(path, OpenFile):\n        of = path\n    else:\n        raise TypeError(f\"Invalid path of type {type(path).__name__!r}\")\n\n    return type(of.fs) == LocalFileSystem\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.relative_path_to_current_platform","title":"<code>relative_path_to_current_platform</code>","text":"<p>Converts a relative path generated on any platform to a relative path for the current platform.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def relative_path_to_current_platform(path_str: str) -&gt; Path:\n    \"\"\"\n    Converts a relative path generated on any platform to a relative path for the\n    current platform.\n    \"\"\"\n\n    return Path(PureWindowsPath(path_str).as_posix())\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.tmpchdir","title":"<code>tmpchdir</code>","text":"<p>Change current-working directories for the duration of the context</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>@contextmanager\ndef tmpchdir(path: str):\n    \"\"\"\n    Change current-working directories for the duration of the context\n    \"\"\"\n    path = os.path.abspath(path)\n    if os.path.isfile(path) or (not os.path.exists(path) and not path.endswith(\"/\")):\n        path = os.path.dirname(path)\n\n    owd = os.getcwd()\n\n    with chdir_lock:\n        try:\n            os.chdir(path)\n            yield path\n        finally:\n            os.chdir(owd)\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/filesystem/#prefect.utilities.filesystem.to_display_path","title":"<code>to_display_path</code>","text":"<p>Convert a path to a displayable path. The absolute path or relative path to the current (or given) directory will be returned, whichever is shorter.</p> Source code in <code>prefect/utilities/filesystem.py</code> <pre><code>def to_display_path(\n    path: Union[pathlib.Path, str], relative_to: Union[pathlib.Path, str] = None\n) -&gt; str:\n    \"\"\"\n    Convert a path to a displayable path. The absolute path or relative path to the\n    current (or given) directory will be returned, whichever is shorter.\n    \"\"\"\n    path, relative_to = (\n        pathlib.Path(path).resolve(),\n        pathlib.Path(relative_to or \".\").resolve(),\n    )\n    relative_path = str(path.relative_to(relative_to))\n    absolute_path = str(path)\n    return relative_path if len(relative_path) &lt; len(absolute_path) else absolute_path\n</code></pre>","tags":["Python API","files","filesystems"]},{"location":"api-ref/prefect/utilities/hashing/","title":"hashing","text":"","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing","title":"<code>prefect.utilities.hashing</code>","text":"","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.file_hash","title":"<code>file_hash</code>","text":"<p>Given a path to a file, produces a stable hash of the file contents.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>the path to a file</p> required <code>hash_algo</code> <p>Hash algorithm from hashlib to use.</p> <code>_md5</code> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>a hash of the file contents</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def file_hash(path: str, hash_algo=_md5) -&gt; str:\n    \"\"\"Given a path to a file, produces a stable hash of the file contents.\n\n    Args:\n        path (str): the path to a file\n        hash_algo: Hash algorithm from hashlib to use.\n\n    Returns:\n        str: a hash of the file contents\n    \"\"\"\n    contents = Path(path).read_bytes()\n    return stable_hash(contents, hash_algo=hash_algo)\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.hash_objects","title":"<code>hash_objects</code>","text":"<p>Attempt to hash objects by dumping to JSON or serializing with cloudpickle. On failure of both, <code>None</code> will be returned</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def hash_objects(*args, hash_algo=_md5, **kwargs) -&gt; Optional[str]:\n    \"\"\"\n    Attempt to hash objects by dumping to JSON or serializing with cloudpickle.\n    On failure of both, `None` will be returned\n    \"\"\"\n    try:\n        serializer = JSONSerializer(dumps_kwargs={\"sort_keys\": True})\n        return stable_hash(serializer.dumps((args, kwargs)), hash_algo=hash_algo)\n    except Exception:\n        pass\n\n    try:\n        return stable_hash(cloudpickle.dumps((args, kwargs)), hash_algo=hash_algo)\n    except Exception:\n        pass\n\n    return None\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/hashing/#prefect.utilities.hashing.stable_hash","title":"<code>stable_hash</code>","text":"<p>Given some arguments, produces a stable 64-bit hash of their contents.</p> <p>Supports bytes and strings. Strings will be UTF-8 encoded.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Union[str, bytes]</code> <p>Items to include in the hash.</p> <code>()</code> <code>hash_algo</code> <p>Hash algorithm from hashlib to use.</p> <code>_md5</code> <p>Returns:</p> Type Description <code>str</code> <p>A hex hash.</p> Source code in <code>prefect/utilities/hashing.py</code> <pre><code>def stable_hash(*args: Union[str, bytes], hash_algo=_md5) -&gt; str:\n    \"\"\"Given some arguments, produces a stable 64-bit hash of their contents.\n\n    Supports bytes and strings. Strings will be UTF-8 encoded.\n\n    Args:\n        *args: Items to include in the hash.\n        hash_algo: Hash algorithm from hashlib to use.\n\n    Returns:\n        A hex hash.\n    \"\"\"\n    h = hash_algo()\n    for a in args:\n        if isinstance(a, str):\n            a = a.encode()\n        h.update(a)\n    return h.hexdigest()\n</code></pre>","tags":["Python API","hashes","hashing"]},{"location":"api-ref/prefect/utilities/importtools/","title":"importtools","text":"","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools","title":"<code>prefect.utilities.importtools</code>","text":"","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleDefinition","title":"<code>AliasedModuleDefinition</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>A definition for the <code>AliasedModuleFinder</code>.</p> <p>Parameters:</p> Name Type Description Default <code>alias</code> <p>The import name to create</p> required <code>real</code> <p>The import name of the module to reference for the alias</p> required <code>callback</code> <p>A function to call when the alias module is loaded</p> required Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class AliasedModuleDefinition(NamedTuple):\n    \"\"\"\n    A definition for the `AliasedModuleFinder`.\n\n    Args:\n        alias: The import name to create\n        real: The import name of the module to reference for the alias\n        callback: A function to call when the alias module is loaded\n    \"\"\"\n\n    alias: str\n    real: str\n    callback: Optional[Callable[[str], None]]\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleFinder","title":"<code>AliasedModuleFinder</code>","text":"<p>               Bases: <code>MetaPathFinder</code></p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class AliasedModuleFinder(MetaPathFinder):\n    def __init__(self, aliases: Iterable[AliasedModuleDefinition]):\n        \"\"\"\n        See `AliasedModuleDefinition` for alias specification.\n\n        Aliases apply to all modules nested within an alias.\n        \"\"\"\n        self.aliases = aliases\n\n    def find_spec(\n        self,\n        fullname: str,\n        path=None,\n        target=None,\n    ) -&gt; Optional[ModuleSpec]:\n        \"\"\"\n        The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\"\n        for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and\n        create a new spec for \"phi.bar\" that points to \"foo.bar\".\n        \"\"\"\n        for alias, real, callback in self.aliases:\n            if fullname.startswith(alias):\n                # Retrieve the spec of the real module\n                real_spec = importlib.util.find_spec(fullname.replace(alias, real, 1))\n                # Create a new spec for the alias\n                return ModuleSpec(\n                    fullname,\n                    AliasedModuleLoader(fullname, callback, real_spec),\n                    origin=real_spec.origin,\n                    is_package=real_spec.submodule_search_locations is not None,\n                )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.AliasedModuleFinder.find_spec","title":"<code>find_spec</code>","text":"<p>The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\" for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and create a new spec for \"phi.bar\" that points to \"foo.bar\".</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def find_spec(\n    self,\n    fullname: str,\n    path=None,\n    target=None,\n) -&gt; Optional[ModuleSpec]:\n    \"\"\"\n    The fullname is the imported path, e.g. \"foo.bar\". If there is an alias \"phi\"\n    for \"foo\" then on import of \"phi.bar\" we will find the spec for \"foo.bar\" and\n    create a new spec for \"phi.bar\" that points to \"foo.bar\".\n    \"\"\"\n    for alias, real, callback in self.aliases:\n        if fullname.startswith(alias):\n            # Retrieve the spec of the real module\n            real_spec = importlib.util.find_spec(fullname.replace(alias, real, 1))\n            # Create a new spec for the alias\n            return ModuleSpec(\n                fullname,\n                AliasedModuleLoader(fullname, callback, real_spec),\n                origin=real_spec.origin,\n                is_package=real_spec.submodule_search_locations is not None,\n            )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.DelayedImportErrorModule","title":"<code>DelayedImportErrorModule</code>","text":"<p>               Bases: <code>ModuleType</code></p> <p>A fake module returned by <code>lazy_import</code> when the module cannot be found. When any of the module's attributes are accessed, we will throw a <code>ModuleNotFoundError</code>.</p> <p>Adapted from lazy_loader</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>class DelayedImportErrorModule(ModuleType):\n    \"\"\"\n    A fake module returned by `lazy_import` when the module cannot be found. When any\n    of the module's attributes are accessed, we will throw a `ModuleNotFoundError`.\n\n    Adapted from [lazy_loader][1]\n\n    [1]: https://github.com/scientific-python/lazy_loader\n    \"\"\"\n\n    def __init__(self, frame_data, help_message, *args, **kwargs):\n        self.__frame_data = frame_data\n        self.__help_message = (\n            help_message or \"Import errors for this module are only reported when used.\"\n        )\n        super().__init__(*args, **kwargs)\n\n    def __getattr__(self, attr):\n        if attr in (\"__class__\", \"__file__\", \"__frame_data\", \"__help_message\"):\n            super().__getattr__(attr)\n        else:\n            fd = self.__frame_data\n            raise ModuleNotFoundError(\n                f\"No module named '{fd['spec']}'\\n\\nThis module was originally imported\"\n                f\" at:\\n  File \\\"{fd['filename']}\\\", line {fd['lineno']}, in\"\n                f\" {fd['function']}\\n\\n    {''.join(fd['code_context']).strip()}\\n\"\n                + self.__help_message\n            )\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.from_qualified_name","title":"<code>from_qualified_name</code>","text":"<p>Import an object given a fully-qualified name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The fully-qualified name of the object to import.</p> required <p>Returns:</p> Type Description <code>Any</code> <p>the imported object</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; obj = from_qualified_name(\"random.randint\")\n&gt;&gt;&gt; import random\n&gt;&gt;&gt; obj == random.randint\nTrue\n</code></pre> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def from_qualified_name(name: str) -&gt; Any:\n    \"\"\"\n    Import an object given a fully-qualified name.\n\n    Args:\n        name: The fully-qualified name of the object to import.\n\n    Returns:\n        the imported object\n\n    Examples:\n        &gt;&gt;&gt; obj = from_qualified_name(\"random.randint\")\n        &gt;&gt;&gt; import random\n        &gt;&gt;&gt; obj == random.randint\n        True\n    \"\"\"\n    # Try importing it first so we support \"module\" or \"module.sub_module\"\n    try:\n        module = importlib.import_module(name)\n        return module\n    except ImportError:\n        # If no subitem was included raise the import error\n        if \".\" not in name:\n            raise\n\n    # Otherwise, we'll try to load it as an attribute of a module\n    mod_name, attr_name = name.rsplit(\".\", 1)\n    module = importlib.import_module(mod_name)\n    return getattr(module, attr_name)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.import_object","title":"<code>import_object</code>","text":"<p>Load an object from an import path.</p> <p>Import paths can be formatted as one of: - module.object - module:object - /path/to/script.py:object</p> <p>This function is not thread safe as it modifies the 'sys' module during execution.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def import_object(import_path: str):\n    \"\"\"\n    Load an object from an import path.\n\n    Import paths can be formatted as one of:\n    - module.object\n    - module:object\n    - /path/to/script.py:object\n\n    This function is not thread safe as it modifies the 'sys' module during execution.\n    \"\"\"\n    if \".py:\" in import_path:\n        script_path, object_name = import_path.rsplit(\":\", 1)\n        module = load_script_as_module(script_path)\n    else:\n        if \":\" in import_path:\n            module_name, object_name = import_path.rsplit(\":\", 1)\n        elif \".\" in import_path:\n            module_name, object_name = import_path.rsplit(\".\", 1)\n        else:\n            raise ValueError(\n                f\"Invalid format for object import. Received {import_path!r}.\"\n            )\n\n        module = load_module(module_name)\n\n    return getattr(module, object_name)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.lazy_import","title":"<code>lazy_import</code>","text":"<p>Create a lazily-imported module to use in place of the module of the given name. Use this to retain module-level imports for libraries that we don't want to actually import until they are needed.</p> <p>Adapted from the Python documentation and lazy_loader</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def lazy_import(\n    name: str, error_on_import: bool = False, help_message: str = \"\"\n) -&gt; ModuleType:\n    \"\"\"\n    Create a lazily-imported module to use in place of the module of the given name.\n    Use this to retain module-level imports for libraries that we don't want to\n    actually import until they are needed.\n\n    Adapted from the [Python documentation][1] and [lazy_loader][2]\n\n    [1]: https://docs.python.org/3/library/importlib.html#implementing-lazy-imports\n    [2]: https://github.com/scientific-python/lazy_loader\n    \"\"\"\n\n    try:\n        return sys.modules[name]\n    except KeyError:\n        pass\n\n    spec = importlib.util.find_spec(name)\n    if spec is None:\n        if error_on_import:\n            raise ModuleNotFoundError(f\"No module named '{name}'.\\n{help_message}\")\n        else:\n            try:\n                parent = inspect.stack()[1]\n                frame_data = {\n                    \"spec\": name,\n                    \"filename\": parent.filename,\n                    \"lineno\": parent.lineno,\n                    \"function\": parent.function,\n                    \"code_context\": parent.code_context,\n                }\n                return DelayedImportErrorModule(\n                    frame_data, help_message, \"DelayedImportErrorModule\"\n                )\n            finally:\n                del parent\n\n    module = importlib.util.module_from_spec(spec)\n    sys.modules[name] = module\n\n    loader = importlib.util.LazyLoader(spec.loader)\n    loader.exec_module(module)\n\n    return module\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.load_module","title":"<code>load_module</code>","text":"<p>Import a module with support for relative imports within the module.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def load_module(module_name: str) -&gt; ModuleType:\n    \"\"\"\n    Import a module with support for relative imports within the module.\n    \"\"\"\n    # Ensure relative imports within the imported module work if the user is in the\n    # correct working directory\n    working_directory = os.getcwd()\n    sys.path.insert(0, working_directory)\n\n    try:\n        return importlib.import_module(module_name)\n    finally:\n        sys.path.remove(working_directory)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.load_script_as_module","title":"<code>load_script_as_module</code>","text":"<p>Execute a script at the given path.</p> <p>Sets the module name to <code>__prefect_loader__</code>.</p> <p>If an exception occurs during execution of the script, a <code>prefect.exceptions.ScriptError</code> is created to wrap the exception and raised.</p> <p>During the duration of this function call, <code>sys</code> is modified to support loading. These changes are reverted after completion, but this function is not thread safe and use of it in threaded contexts may result in undesirable behavior.</p> <p>See https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def load_script_as_module(path: str) -&gt; ModuleType:\n    \"\"\"\n    Execute a script at the given path.\n\n    Sets the module name to `__prefect_loader__`.\n\n    If an exception occurs during execution of the script, a\n    `prefect.exceptions.ScriptError` is created to wrap the exception and raised.\n\n    During the duration of this function call, `sys` is modified to support loading.\n    These changes are reverted after completion, but this function is not thread safe\n    and use of it in threaded contexts may result in undesirable behavior.\n\n    See https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly\n    \"\"\"\n    # We will add the parent directory to search locations to support relative imports\n    # during execution of the script\n    if not path.endswith(\".py\"):\n        raise ValueError(f\"The provided path does not point to a python file: {path!r}\")\n\n    parent_path = str(Path(path).resolve().parent)\n    working_directory = os.getcwd()\n\n    spec = importlib.util.spec_from_file_location(\n        \"__prefect_loader__\",\n        path,\n        # Support explicit relative imports i.e. `from .foo import bar`\n        submodule_search_locations=[parent_path, working_directory],\n    )\n    module = importlib.util.module_from_spec(spec)\n    sys.modules[\"__prefect_loader__\"] = module\n\n    # Support implicit relative imports i.e. `from foo import bar`\n    sys.path.insert(0, working_directory)\n    sys.path.insert(0, parent_path)\n    try:\n        spec.loader.exec_module(module)\n    except Exception as exc:\n        raise ScriptError(user_exc=exc, path=path) from exc\n    finally:\n        sys.modules.pop(\"__prefect_loader__\")\n        sys.path.remove(parent_path)\n        sys.path.remove(working_directory)\n\n    return module\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.objects_from_script","title":"<code>objects_from_script</code>","text":"<p>Run a python script and return all the global variables</p> <p>Supports remote paths by copying to a local temporary file.</p> <p>WARNING: The Python documentation does not recommend using runpy for this pattern.</p> <p>Furthermore, any functions and classes defined by the executed code are not guaranteed to work correctly after a runpy function has returned. If that limitation is not acceptable for a given use case, importlib is likely to be a more suitable choice than this module.</p> <p>The function <code>load_script_as_module</code> uses importlib instead and should be used instead for loading objects from scripts.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path to the script to run</p> required <code>text</code> <code>Union[str, bytes]</code> <p>Optionally, the text of the script. Skips loading the contents if given.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dictionary mapping variable name to value</p> <p>Raises:</p> Type Description <code>ScriptError</code> <p>if the script raises an exception during execution</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def objects_from_script(path: str, text: Union[str, bytes] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Run a python script and return all the global variables\n\n    Supports remote paths by copying to a local temporary file.\n\n    WARNING: The Python documentation does not recommend using runpy for this pattern.\n\n    &gt; Furthermore, any functions and classes defined by the executed code are not\n    &gt; guaranteed to work correctly after a runpy function has returned. If that\n    &gt; limitation is not acceptable for a given use case, importlib is likely to be a\n    &gt; more suitable choice than this module.\n\n    The function `load_script_as_module` uses importlib instead and should be used\n    instead for loading objects from scripts.\n\n    Args:\n        path: The path to the script to run\n        text: Optionally, the text of the script. Skips loading the contents if given.\n\n    Returns:\n        A dictionary mapping variable name to value\n\n    Raises:\n        ScriptError: if the script raises an exception during execution\n    \"\"\"\n\n    def run_script(run_path: str):\n        # Cast to an absolute path before changing directories to ensure relative paths\n        # are not broken\n        abs_run_path = os.path.abspath(run_path)\n        with tmpchdir(run_path):\n            try:\n                return runpy.run_path(abs_run_path)\n            except Exception as exc:\n                raise ScriptError(user_exc=exc, path=path) from exc\n\n    if text:\n        with NamedTemporaryFile(\n            mode=\"wt\" if isinstance(text, str) else \"wb\",\n            prefix=f\"run-{filename(path)}\",\n            suffix=\".py\",\n        ) as tmpfile:\n            tmpfile.write(text)\n            tmpfile.flush()\n            return run_script(tmpfile.name)\n\n    else:\n        if not is_local_path(path):\n            # Remote paths need to be local to run\n            with fsspec.open(path) as f:\n                contents = f.read()\n            return objects_from_script(path, contents)\n        else:\n            return run_script(path)\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.safe_load_namespace","title":"<code>safe_load_namespace</code>","text":"<p>Safely load a namespace from source code, optionally handling relative imports.</p> <p>If a <code>filepath</code> is provided, <code>sys.path</code> is modified to support relative imports. Changes to <code>sys.path</code> are reverted after completion, but this function is not thread safe and use of it in threaded contexts may result in undesirable behavior.</p> <p>Parameters:</p> Name Type Description Default <code>source_code</code> <code>str</code> <p>The source code to load</p> required <code>filepath</code> <code>Optional[str]</code> <p>Optional file path of the source code. If provided, enables relative imports.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The namespace loaded from the source code.</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def safe_load_namespace(\n    source_code: str, filepath: Optional[str] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Safely load a namespace from source code, optionally handling relative imports.\n\n    If a `filepath` is provided, `sys.path` is modified to support relative imports.\n    Changes to `sys.path` are reverted after completion, but this function is not thread safe\n    and use of it in threaded contexts may result in undesirable behavior.\n\n    Args:\n        source_code: The source code to load\n        filepath: Optional file path of the source code. If provided, enables relative imports.\n\n    Returns:\n        The namespace loaded from the source code.\n    \"\"\"\n    parsed_code = ast.parse(source_code)\n\n    namespace: Dict[str, Any] = {\"__name__\": \"prefect_safe_namespace_loader\"}\n\n    # Remove the body of the if __name__ == \"__main__\": block\n    new_body = [node for node in parsed_code.body if not _is_main_block(node)]\n    parsed_code.body = new_body\n\n    temp_module = None\n    original_sys_path = None\n\n    if filepath:\n        # Setup for relative imports\n        file_dir = os.path.dirname(os.path.abspath(filepath))\n        package_name = os.path.basename(file_dir)\n        parent_dir = os.path.dirname(file_dir)\n\n        # Save original sys.path and modify it\n        original_sys_path = sys.path.copy()\n        sys.path.insert(0, parent_dir)\n\n        # Create a temporary module for import context\n        temp_module = ModuleType(package_name)\n        temp_module.__file__ = filepath\n        temp_module.__package__ = package_name\n\n        # Create a spec for the module\n        temp_module.__spec__ = ModuleSpec(package_name, None)\n        temp_module.__spec__.loader = None\n        temp_module.__spec__.submodule_search_locations = [file_dir]\n\n    try:\n        for node in parsed_code.body:\n            if isinstance(node, ast.Import):\n                for alias in node.names:\n                    module_name = alias.name\n                    as_name = alias.asname or module_name\n                    try:\n                        namespace[as_name] = importlib.import_module(module_name)\n                        logger.debug(\"Successfully imported %s\", module_name)\n                    except ImportError as e:\n                        logger.debug(f\"Failed to import {module_name}: {e}\")\n            elif isinstance(node, ast.ImportFrom):\n                module_name = node.module or \"\"\n                if filepath:\n                    try:\n                        if node.level &gt; 0:\n                            # For relative imports, use the parent package to inform the import\n                            package_parts = temp_module.__package__.split(\".\")\n                            if len(package_parts) &lt; node.level:\n                                raise ImportError(\n                                    \"Attempted relative import beyond top-level package\"\n                                )\n                            parent_package = \".\".join(\n                                package_parts[: (1 - node.level)]\n                                if node.level &gt; 1\n                                else package_parts\n                            )\n                            module = importlib.import_module(\n                                f\".{module_name}\" if module_name else \"\",\n                                package=parent_package,\n                            )\n                        else:\n                            # Absolute imports are handled as normal\n                            module = importlib.import_module(module_name)\n\n                        for alias in node.names:\n                            name = alias.name\n                            asname = alias.asname or name\n                            if name == \"*\":\n                                # Handle 'from module import *'\n                                module_dict = {\n                                    k: v\n                                    for k, v in module.__dict__.items()\n                                    if not k.startswith(\"_\")\n                                }\n                                namespace.update(module_dict)\n                            else:\n                                try:\n                                    attribute = getattr(module, name)\n                                    namespace[asname] = attribute\n                                except AttributeError as e:\n                                    logger.debug(\n                                        \"Failed to retrieve %s from %s: %s\",\n                                        name,\n                                        module_name,\n                                        e,\n                                    )\n                    except ImportError as e:\n                        logger.debug(\"Failed to import from %s: %s\", module_name, e)\n                else:\n                    # Handle as absolute import when no filepath is provided\n                    try:\n                        module = importlib.import_module(module_name)\n                        for alias in node.names:\n                            name = alias.name\n                            asname = alias.asname or name\n                            if name == \"*\":\n                                # Handle 'from module import *'\n                                module_dict = {\n                                    k: v\n                                    for k, v in module.__dict__.items()\n                                    if not k.startswith(\"_\")\n                                }\n                                namespace.update(module_dict)\n                            else:\n                                try:\n                                    attribute = getattr(module, name)\n                                    namespace[asname] = attribute\n                                except AttributeError as e:\n                                    logger.debug(\n                                        \"Failed to retrieve %s from %s: %s\",\n                                        name,\n                                        module_name,\n                                        e,\n                                    )\n                    except ImportError as e:\n                        logger.debug(\"Failed to import from %s: %s\", module_name, e)\n        # Handle local definitions\n        for node in parsed_code.body:\n            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.Assign)):\n                try:\n                    code = compile(\n                        ast.Module(body=[node], type_ignores=[]),\n                        filename=\"&lt;ast&gt;\",\n                        mode=\"exec\",\n                    )\n                    exec(code, namespace)\n                except Exception as e:\n                    logger.debug(\"Failed to compile: %s\", e)\n\n    finally:\n        # Restore original sys.path if it was modified\n        if original_sys_path:\n            sys.path[:] = original_sys_path\n\n    return namespace\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/importtools/#prefect.utilities.importtools.to_qualified_name","title":"<code>to_qualified_name</code>","text":"<p>Given an object, returns its fully-qualified name: a string that represents its Python import path.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Any</code> <p>an importable Python object</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>the qualified name</p> Source code in <code>prefect/utilities/importtools.py</code> <pre><code>def to_qualified_name(obj: Any) -&gt; str:\n    \"\"\"\n    Given an object, returns its fully-qualified name: a string that represents its\n    Python import path.\n\n    Args:\n        obj (Any): an importable Python object\n\n    Returns:\n        str: the qualified name\n    \"\"\"\n    if sys.version_info &lt; (3, 10):\n        # These attributes are only available in Python 3.10+\n        if isinstance(obj, (classmethod, staticmethod)):\n            obj = obj.__func__\n    return obj.__module__ + \".\" + obj.__qualname__\n</code></pre>","tags":["Python API","imports"]},{"location":"api-ref/prefect/utilities/math/","title":"math","text":"","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math","title":"<code>prefect.utilities.math</code>","text":"","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.bounded_poisson_interval","title":"<code>bounded_poisson_interval</code>","text":"<p>Bounds Poisson \"inter-arrival times\" to a range.</p> <p>Unlike <code>clamped_poisson_interval</code> this does not take a target average interval. Instead, the interval is predetermined and the average is calculated as their midpoint. This allows Poisson intervals to be used in cases where a lower bound must be enforced.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def bounded_poisson_interval(lower_bound, upper_bound):\n    \"\"\"\n    Bounds Poisson \"inter-arrival times\" to a range.\n\n    Unlike `clamped_poisson_interval` this does not take a target average interval.\n    Instead, the interval is predetermined and the average is calculated as their\n    midpoint. This allows Poisson intervals to be used in cases where a lower bound\n    must be enforced.\n    \"\"\"\n    average = (float(lower_bound) + float(upper_bound)) / 2.0\n    upper_rv = exponential_cdf(upper_bound, average)\n    lower_rv = exponential_cdf(lower_bound, average)\n    return poisson_interval(average, lower_rv, upper_rv)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.clamped_poisson_interval","title":"<code>clamped_poisson_interval</code>","text":"<p>Bounds Poisson \"inter-arrival times\" to a range defined by the clamping factor.</p> <p>The upper bound for this random variate is: average_interval * (1 + clamping_factor). A lower bound is picked so that the average interval remains approximately fixed.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def clamped_poisson_interval(average_interval, clamping_factor=0.3):\n    \"\"\"\n    Bounds Poisson \"inter-arrival times\" to a range defined by the clamping factor.\n\n    The upper bound for this random variate is: average_interval * (1 + clamping_factor).\n    A lower bound is picked so that the average interval remains approximately fixed.\n    \"\"\"\n    if clamping_factor &lt;= 0:\n        raise ValueError(\"`clamping_factor` must be &gt;= 0.\")\n\n    upper_clamp_multiple = 1 + clamping_factor\n    upper_bound = average_interval * upper_clamp_multiple\n    lower_bound = max(0, average_interval * lower_clamp_multiple(upper_clamp_multiple))\n\n    upper_rv = exponential_cdf(upper_bound, average_interval)\n    lower_rv = exponential_cdf(lower_bound, average_interval)\n    return poisson_interval(average_interval, lower_rv, upper_rv)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.lower_clamp_multiple","title":"<code>lower_clamp_multiple</code>","text":"<p>Computes a lower clamp multiple that can be used to bound a random variate drawn from an exponential distribution.</p> <p>Given an upper clamp multiple <code>k</code> (and corresponding upper bound k * average_interval), this function computes a lower clamp multiple <code>c</code> (corresponding to a lower bound c * average_interval) where the probability mass between the lower bound and the median is equal to the probability mass between the median and the upper bound.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def lower_clamp_multiple(k):\n    \"\"\"\n    Computes a lower clamp multiple that can be used to bound a random variate drawn\n    from an exponential distribution.\n\n    Given an upper clamp multiple `k` (and corresponding upper bound k * average_interval),\n    this function computes a lower clamp multiple `c` (corresponding to a lower bound\n    c * average_interval) where the probability mass between the lower bound and the\n    median is equal to the probability mass between the median and the upper bound.\n    \"\"\"\n    if k &gt;= 50:\n        # return 0 for large values of `k` to prevent numerical overflow\n        return 0.0\n\n    return math.log(max(2**k / (2**k - 1), 1e-10), 2)\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/math/#prefect.utilities.math.poisson_interval","title":"<code>poisson_interval</code>","text":"<p>Generates an \"inter-arrival time\" for a Poisson process.</p> <p>Draws a random variable from an exponential distribution using the inverse-CDF method. Can optionally be passed a lower and upper bound between (0, 1] to clamp the potential output values.</p> Source code in <code>prefect/utilities/math.py</code> <pre><code>def poisson_interval(average_interval, lower=0, upper=1):\n    \"\"\"\n    Generates an \"inter-arrival time\" for a Poisson process.\n\n    Draws a random variable from an exponential distribution using the inverse-CDF\n    method. Can optionally be passed a lower and upper bound between (0, 1] to clamp\n    the potential output values.\n    \"\"\"\n\n    # note that we ensure the argument to the logarithm is stabilized to prevent\n    # calling log(0), which results in a DomainError\n    return -math.log(max(1 - random.uniform(lower, upper), 1e-10)) * average_interval\n</code></pre>","tags":["Python API","math"]},{"location":"api-ref/prefect/utilities/names/","title":"names","text":"","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names","title":"<code>prefect.utilities.names</code>","text":"","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.generate_slug","title":"<code>generate_slug</code>","text":"<p>Generates a random slug.</p> <p>Parameters:</p> Name Type Description Default <code>-</code> <code>n_words (int</code> <p>the number of words in the slug</p> required Source code in <code>prefect/utilities/names.py</code> <pre><code>def generate_slug(n_words: int) -&gt; str:\n    \"\"\"\n    Generates a random slug.\n\n    Args:\n        - n_words (int): the number of words in the slug\n    \"\"\"\n    words = coolname.generate(n_words)\n\n    # regenerate words if they include ignored words\n    while IGNORE_LIST.intersection(words):\n        words = coolname.generate(n_words)\n\n    return \"-\".join(words)\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.obfuscate","title":"<code>obfuscate</code>","text":"<p>Obfuscates any data type's string representation. See <code>obfuscate_string</code>.</p> Source code in <code>prefect/utilities/names.py</code> <pre><code>def obfuscate(s: Any, show_tail=False) -&gt; str:\n    \"\"\"\n    Obfuscates any data type's string representation. See `obfuscate_string`.\n    \"\"\"\n    if s is None:\n        return OBFUSCATED_PREFIX + \"*\" * 4\n\n    return obfuscate_string(str(s), show_tail=show_tail)\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/names/#prefect.utilities.names.obfuscate_string","title":"<code>obfuscate_string</code>","text":"<p>Obfuscates a string by returning a new string of 8 characters. If the input string is longer than 10 characters and show_tail is True, then up to 4 of its final characters will become final characters of the obfuscated string; all other characters are \"*\".</p> <p>\"abc\"      -&gt; \"*\" \"abcdefgh\" -&gt; \"*\" \"abcdefghijk\" -&gt; \"*k\" \"abcdefghijklmnopqrs\" -&gt; \"****pqrs\"</p> Source code in <code>prefect/utilities/names.py</code> <pre><code>def obfuscate_string(s: str, show_tail=False) -&gt; str:\n    \"\"\"\n    Obfuscates a string by returning a new string of 8 characters. If the input\n    string is longer than 10 characters and show_tail is True, then up to 4 of\n    its final characters will become final characters of the obfuscated string;\n    all other characters are \"*\".\n\n    \"abc\"      -&gt; \"********\"\n    \"abcdefgh\" -&gt; \"********\"\n    \"abcdefghijk\" -&gt; \"*******k\"\n    \"abcdefghijklmnopqrs\" -&gt; \"****pqrs\"\n    \"\"\"\n    result = OBFUSCATED_PREFIX + \"*\" * 4\n    # take up to 4 characters, but only after the 10th character\n    suffix = s[10:][-4:]\n    if suffix and show_tail:\n        result = f\"{result[:-len(suffix)]}{suffix}\"\n    return result\n</code></pre>","tags":["Python API","names"]},{"location":"api-ref/prefect/utilities/processutils/","title":"processutils","text":""},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils","title":"<code>prefect.utilities.processutils</code>","text":""},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.forward_signal_handler","title":"<code>forward_signal_handler</code>","text":"<p>Forward subsequent signum events (e.g. interrupts) to respective signums.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def forward_signal_handler(\n    pid: int, signum: int, *signums: int, process_name: str, print_fn: Callable\n):\n    \"\"\"Forward subsequent signum events (e.g. interrupts) to respective signums.\"\"\"\n    current_signal, future_signals = signums[0], signums[1:]\n\n    # avoid RecursionError when setting up a direct signal forward to the same signal for the main pid\n    avoid_infinite_recursion = signum == current_signal and pid == os.getpid()\n    if avoid_infinite_recursion:\n        # store the vanilla handler so it can be temporarily restored below\n        original_handler = signal.getsignal(current_signal)\n\n    def handler(*args):\n        print_fn(\n            f\"Received {getattr(signum, 'name', signum)}. \"\n            f\"Sending {getattr(current_signal, 'name', current_signal)} to\"\n            f\" {process_name} (PID {pid})...\"\n        )\n        if avoid_infinite_recursion:\n            signal.signal(current_signal, original_handler)\n        os.kill(pid, current_signal)\n        if future_signals:\n            forward_signal_handler(\n                pid,\n                signum,\n                *future_signals,\n                process_name=process_name,\n                print_fn=print_fn,\n            )\n\n    # register current and future signal handlers\n    _register_signal(signum, handler)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.open_process","title":"<code>open_process</code>  <code>async</code>","text":"<p>Like <code>anyio.open_process</code> but with: - Support for Windows command joining - Termination of the process on exception during yield - Forced cleanup of process resources during cancellation</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>@asynccontextmanager\nasync def open_process(command: List[str], **kwargs):\n    \"\"\"\n    Like `anyio.open_process` but with:\n    - Support for Windows command joining\n    - Termination of the process on exception during yield\n    - Forced cleanup of process resources during cancellation\n    \"\"\"\n    # Passing a string to open_process is equivalent to shell=True which is\n    # generally necessary for Unix-like commands on Windows but otherwise should\n    # be avoided\n    if not isinstance(command, list):\n        raise TypeError(\n            \"The command passed to open process must be a list. You passed the command\"\n            f\"'{command}', which is type '{type(command)}'.\"\n        )\n\n    if sys.platform == \"win32\":\n        command = \" \".join(command)\n        process = await _open_anyio_process(command, **kwargs)\n    else:\n        process = await anyio.open_process(command, **kwargs)\n\n    # if there's a creationflags kwarg and it contains CREATE_NEW_PROCESS_GROUP,\n    # use SetConsoleCtrlHandler to handle CTRL-C\n    win32_process_group = False\n    if (\n        sys.platform == \"win32\"\n        and \"creationflags\" in kwargs\n        and kwargs[\"creationflags\"] &amp; subprocess.CREATE_NEW_PROCESS_GROUP\n    ):\n        win32_process_group = True\n        _windows_process_group_pids.add(process.pid)\n        # Add a handler for CTRL-C. Re-adding the handler is safe as Windows\n        # will not add a duplicate handler if _win32_ctrl_handler is\n        # already registered.\n        windll.kernel32.SetConsoleCtrlHandler(_win32_ctrl_handler, 1)\n\n    try:\n        async with process:\n            yield process\n    finally:\n        try:\n            process.terminate()\n            if win32_process_group:\n                _windows_process_group_pids.remove(process.pid)\n\n        except OSError:\n            # Occurs if the process is already terminated\n            pass\n\n        # Ensure the process resource is closed. If not shielded from cancellation,\n        # this resource can be left open and the subprocess output can appear after\n        # the parent process has exited.\n        with anyio.CancelScope(shield=True):\n            await process.aclose()\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.run_process","title":"<code>run_process</code>  <code>async</code>","text":"<p>Like <code>anyio.run_process</code> but with:</p> <ul> <li>Use of our <code>open_process</code> utility to ensure resources are cleaned up</li> <li>Simple <code>stream_output</code> support to connect the subprocess to the parent stdout/err</li> <li>Support for submission with <code>TaskGroup.start</code> marking as 'started' after the     process has been created. When used, the PID is returned to the task status.</li> </ul> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>async def run_process(\n    command: List[str],\n    stream_output: Union[bool, Tuple[Optional[TextSink], Optional[TextSink]]] = False,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n    task_status_handler: Optional[Callable[[anyio.abc.Process], Any]] = None,\n    **kwargs,\n):\n    \"\"\"\n    Like `anyio.run_process` but with:\n\n    - Use of our `open_process` utility to ensure resources are cleaned up\n    - Simple `stream_output` support to connect the subprocess to the parent stdout/err\n    - Support for submission with `TaskGroup.start` marking as 'started' after the\n        process has been created. When used, the PID is returned to the task status.\n\n    \"\"\"\n    if stream_output is True:\n        stream_output = (sys.stdout, sys.stderr)\n\n    async with open_process(\n        command,\n        stdout=subprocess.PIPE if stream_output else subprocess.DEVNULL,\n        stderr=subprocess.PIPE if stream_output else subprocess.DEVNULL,\n        **kwargs,\n    ) as process:\n        if task_status is not None:\n            if not task_status_handler:\n\n                def task_status_handler(process):\n                    return process.pid\n\n            task_status.started(task_status_handler(process))\n\n        if stream_output:\n            await consume_process_output(\n                process, stdout_sink=stream_output[0], stderr_sink=stream_output[1]\n            )\n\n        await process.wait()\n\n    return process\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_agent","title":"<code>setup_signal_handlers_agent</code>","text":"<p>Handle interrupts of the agent gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_agent(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of the agent gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when agent receives SIGINT, it stops dequeueing new FlowRuns, and runs until the subprocesses finish\n    # the signal is not forwarded to subprocesses, so they can continue to run and hopefully still complete\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # forward first SIGINT directly, send SIGKILL on subsequent interrupt\n        setup_handler(signal.SIGINT, signal.SIGINT, signal.SIGKILL)\n        # first SIGTERM: send SIGINT, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGINT, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_server","title":"<code>setup_signal_handlers_server</code>","text":"<p>Handle interrupts of the server gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_server(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of the server gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when server receives a signal, it needs to be propagated to the uvicorn subprocess\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # first interrupt: SIGTERM, second interrupt: SIGKILL\n        setup_handler(signal.SIGINT, signal.SIGTERM, signal.SIGKILL)\n        # forward first SIGTERM directly, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGTERM, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/processutils/#prefect.utilities.processutils.setup_signal_handlers_worker","title":"<code>setup_signal_handlers_worker</code>","text":"<p>Handle interrupts of workers gracefully.</p> Source code in <code>prefect/utilities/processutils.py</code> <pre><code>def setup_signal_handlers_worker(pid: int, process_name: str, print_fn: Callable):\n    \"\"\"Handle interrupts of workers gracefully.\"\"\"\n    setup_handler = partial(\n        forward_signal_handler, pid, process_name=process_name, print_fn=print_fn\n    )\n    # when agent receives SIGINT, it stops dequeueing new FlowRuns, and runs until the subprocesses finish\n    # the signal is not forwarded to subprocesses, so they can continue to run and hopefully still complete\n    if sys.platform == \"win32\":\n        # on Windows, use CTRL_BREAK_EVENT as SIGTERM is useless:\n        # https://bugs.python.org/issue26350\n        setup_handler(signal.SIGINT, signal.CTRL_BREAK_EVENT)\n    else:\n        # forward first SIGINT directly, send SIGKILL on subsequent interrupt\n        setup_handler(signal.SIGINT, signal.SIGINT, signal.SIGKILL)\n        # first SIGTERM: send SIGINT, send SIGKILL on subsequent SIGTERM\n        setup_handler(signal.SIGTERM, signal.SIGINT, signal.SIGKILL)\n</code></pre>"},{"location":"api-ref/prefect/utilities/pydantic/","title":"pydantic","text":"","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic","title":"<code>prefect.utilities.pydantic</code>","text":"","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.PartialModel","title":"<code>PartialModel</code>","text":"<p>               Bases: <code>Generic[M]</code></p> <p>A utility for creating a Pydantic model in several steps.</p> <p>Fields may be set at initialization, via attribute assignment, or at finalization when the concrete model is returned.</p> <p>Pydantic validation does not occur until finalization.</p> <p>Each field can only be set once and a <code>ValueError</code> will be raised on assignment if a field already has a value.</p> Example <p>class MyModel(pydantic_v1.BaseModel):     x: int     y: str     z: float</p> <p>partial_model = PartialModel(MyModel, x=1) partial_model.y = \"two\" model = partial_model.finalize(z=3.0)</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>class PartialModel(Generic[M]):\n    \"\"\"\n    A utility for creating a Pydantic model in several steps.\n\n    Fields may be set at initialization, via attribute assignment, or at finalization\n    when the concrete model is returned.\n\n    Pydantic validation does not occur until finalization.\n\n    Each field can only be set once and a `ValueError` will be raised on assignment if\n    a field already has a value.\n\n    Example:\n        &gt;&gt;&gt; class MyModel(pydantic_v1.BaseModel):\n        &gt;&gt;&gt;     x: int\n        &gt;&gt;&gt;     y: str\n        &gt;&gt;&gt;     z: float\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; partial_model = PartialModel(MyModel, x=1)\n        &gt;&gt;&gt; partial_model.y = \"two\"\n        &gt;&gt;&gt; model = partial_model.finalize(z=3.0)\n    \"\"\"\n\n    def __init__(self, __model_cls: Type[M], **kwargs: Any) -&gt; None:\n        self.fields = kwargs\n        # Set fields first to avoid issues if `fields` is also set on the `model_cls`\n        # in our custom `setattr` implementation.\n        self.model_cls = __model_cls\n\n        for name in kwargs.keys():\n            self.raise_if_not_in_model(name)\n\n    def finalize(self, **kwargs: Any) -&gt; M:\n        for name in kwargs.keys():\n            self.raise_if_already_set(name)\n            self.raise_if_not_in_model(name)\n        return self.model_cls(**self.fields, **kwargs)\n\n    def raise_if_already_set(self, name):\n        if name in self.fields:\n            raise ValueError(f\"Field {name!r} has already been set.\")\n\n    def raise_if_not_in_model(self, name):\n        if name not in self.model_cls.__fields__:\n            raise ValueError(f\"Field {name!r} is not present in the model.\")\n\n    def __setattr__(self, __name: str, __value: Any) -&gt; None:\n        if __name in {\"fields\", \"model_cls\"}:\n            return super().__setattr__(__name, __value)\n\n        self.raise_if_already_set(__name)\n        self.raise_if_not_in_model(__name)\n        self.fields[__name] = __value\n\n    def __repr__(self) -&gt; str:\n        dsp_fields = \", \".join(\n            f\"{key}={repr(value)}\" for key, value in self.fields.items()\n        )\n        return f\"PartialModel(cls={self.model_cls.__name__}, {dsp_fields})\"\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.add_cloudpickle_reduction","title":"<code>add_cloudpickle_reduction</code>","text":"<p>Adds a <code>__reducer__</code> to the given class that ensures it is cloudpickle compatible.</p> <p>Workaround for issues with cloudpickle when using cythonized pydantic which throws exceptions when attempting to pickle the class which has \"compiled\" validator methods dynamically attached to it.</p> <p>We cannot define this utility in the model class itself because the class is the type that contains unserializable methods.</p> <p>Any model using some features of Pydantic (e.g. <code>Path</code> validation) with a Cython compiled Pydantic installation may encounter pickling issues.</p> <p>See related issue at https://github.com/cloudpipe/cloudpickle/issues/408</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def add_cloudpickle_reduction(__model_cls: Type[M] = None, **kwargs: Any):\n    \"\"\"\n    Adds a `__reducer__` to the given class that ensures it is cloudpickle compatible.\n\n    Workaround for issues with cloudpickle when using cythonized pydantic which\n    throws exceptions when attempting to pickle the class which has \"compiled\"\n    validator methods dynamically attached to it.\n\n    We cannot define this utility in the model class itself because the class is the\n    type that contains unserializable methods.\n\n    Any model using some features of Pydantic (e.g. `Path` validation) with a Cython\n    compiled Pydantic installation may encounter pickling issues.\n\n    See related issue at https://github.com/cloudpipe/cloudpickle/issues/408\n    \"\"\"\n    if __model_cls:\n        __model_cls.__reduce__ = _reduce_model\n        __model_cls.__reduce_kwargs__ = kwargs\n        return __model_cls\n    else:\n        return cast(\n            Callable[[Type[M]], Type[M]],\n            partial(\n                add_cloudpickle_reduction,\n                **kwargs,\n            ),\n        )\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.add_type_dispatch","title":"<code>add_type_dispatch</code>","text":"<p>Extend a Pydantic model to add a 'type' field that is used as a discriminator field to dynamically determine the subtype that when deserializing models.</p> <p>This allows automatic resolution to subtypes of the decorated model.</p> <p>If a type field already exists, it should be a string literal field that has a constant value for each subclass. The default value of this field will be used as the dispatch key.</p> <p>If a type field does not exist, one will be added. In this case, the value of the field will be set to the value of the <code>__dispatch_key__</code>. The base class should define a <code>__dispatch_key__</code> class method that is used to determine the unique key for each subclass. Alternatively, each subclass can define the <code>__dispatch_key__</code> as a string literal.</p> <p>The base class must not define a 'type' field. If it is not desirable to add a field to the model and the dispatch key can be tracked separately, the lower level utilities in <code>prefect.utilities.dispatch</code> should be used directly.</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def add_type_dispatch(model_cls: Type[M]) -&gt; Type[M]:\n    \"\"\"\n    Extend a Pydantic model to add a 'type' field that is used as a discriminator field\n    to dynamically determine the subtype that when deserializing models.\n\n    This allows automatic resolution to subtypes of the decorated model.\n\n    If a type field already exists, it should be a string literal field that has a\n    constant value for each subclass. The default value of this field will be used as\n    the dispatch key.\n\n    If a type field does not exist, one will be added. In this case, the value of the\n    field will be set to the value of the `__dispatch_key__`. The base class should\n    define a `__dispatch_key__` class method that is used to determine the unique key\n    for each subclass. Alternatively, each subclass can define the `__dispatch_key__`\n    as a string literal.\n\n    The base class must not define a 'type' field. If it is not desirable to add a field\n    to the model and the dispatch key can be tracked separately, the lower level\n    utilities in `prefect.utilities.dispatch` should be used directly.\n    \"\"\"\n    defines_dispatch_key = hasattr(\n        model_cls, \"__dispatch_key__\"\n    ) or \"__dispatch_key__\" in getattr(model_cls, \"__annotations__\", {})\n\n    defines_type_field = \"type\" in model_cls.__fields__\n\n    if not defines_dispatch_key and not defines_type_field:\n        raise ValueError(\n            f\"Model class {model_cls.__name__!r} does not define a `__dispatch_key__` \"\n            \"or a type field. One of these is required for dispatch.\"\n        )\n\n    elif defines_dispatch_key and not defines_type_field:\n        # Add a type field to store the value of the dispatch key\n        model_cls.__fields__[\"type\"] = pydantic_v1.fields.ModelField(\n            name=\"type\",\n            type_=str,\n            required=True,\n            class_validators=None,\n            model_config=model_cls.__config__,\n        )\n\n    elif not defines_dispatch_key and defines_type_field:\n        field_type_annotation = model_cls.__fields__[\"type\"].type_\n        if field_type_annotation != str:\n            raise TypeError(\n                f\"Model class {model_cls.__name__!r} defines a 'type' field with \"\n                f\"type {field_type_annotation.__name__!r} but it must be 'str'.\"\n            )\n\n        # Set the dispatch key to retrieve the value from the type field\n        @classmethod\n        def dispatch_key_from_type_field(cls):\n            return cls.__fields__[\"type\"].default\n\n        model_cls.__dispatch_key__ = dispatch_key_from_type_field\n\n    else:\n        raise ValueError(\n            f\"Model class {model_cls.__name__!r} defines a `__dispatch_key__` \"\n            \"and a type field. Only one of these may be defined for dispatch.\"\n        )\n\n    cls_init = model_cls.__init__\n    cls_new = model_cls.__new__\n\n    def __init__(__pydantic_self__, **data: Any) -&gt; None:\n        type_string = (\n            get_dispatch_key(__pydantic_self__)\n            if type(__pydantic_self__) != model_cls\n            else \"__base__\"\n        )\n        data.setdefault(\"type\", type_string)\n        cls_init(__pydantic_self__, **data)\n\n    def __new__(cls: Type[Self], **kwargs) -&gt; Self:\n        if \"type\" in kwargs:\n            try:\n                subcls = lookup_type(cls, dispatch_key=kwargs[\"type\"])\n            except KeyError as exc:\n                raise pydantic_v1.ValidationError(errors=[exc], model=cls)\n            return cls_new(subcls)\n        else:\n            return cls_new(cls)\n\n    model_cls.__init__ = __init__\n    model_cls.__new__ = __new__\n\n    register_base_type(model_cls)\n\n    return model_cls\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/pydantic/#prefect.utilities.pydantic.get_class_fields_only","title":"<code>get_class_fields_only</code>","text":"<p>Gets all the field names defined on the model class but not any parent classes. Any fields that are on the parent but redefined on the subclass are included.</p> Source code in <code>prefect/utilities/pydantic.py</code> <pre><code>def get_class_fields_only(model: Type[pydantic_v1.BaseModel]) -&gt; set:\n    \"\"\"\n    Gets all the field names defined on the model class but not any parent classes.\n    Any fields that are on the parent but redefined on the subclass are included.\n    \"\"\"\n    subclass_class_fields = set(model.__annotations__.keys())\n    parent_class_fields = set()\n\n    for base in model.__class__.__bases__:\n        if issubclass(base, pydantic_v1.BaseModel):\n            parent_class_fields.update(base.__annotations__.keys())\n\n    return (subclass_class_fields - parent_class_fields) | (\n        subclass_class_fields &amp; parent_class_fields\n    )\n</code></pre>","tags":["Python API","pydantic"]},{"location":"api-ref/prefect/utilities/render_swagger/","title":"render_swagger","text":"","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/render_swagger/#prefect.utilities.render_swagger","title":"<code>prefect.utilities.render_swagger</code>","text":"","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/render_swagger/#prefect.utilities.render_swagger.swagger_lib","title":"<code>swagger_lib</code>","text":"<p>Provides the actual swagger library used</p> Source code in <code>prefect/utilities/render_swagger.py</code> <pre><code>def swagger_lib(config) -&gt; dict:\n    \"\"\"\n    Provides the actual swagger library used\n    \"\"\"\n    lib_swagger = {\n        \"css\": \"https://unpkg.com/swagger-ui-dist@3/swagger-ui.css\",\n        \"js\": \"https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js\",\n    }\n\n    extra_javascript = config.get(\"extra_javascript\", [])\n    extra_css = config.get(\"extra_css\", [])\n    for lib in extra_javascript:\n        if os.path.basename(urllib.parse.urlparse(lib).path) == \"swagger-ui-bundle.js\":\n            lib_swagger[\"js\"] = lib\n            break\n\n    for css in extra_css:\n        if os.path.basename(urllib.parse.urlparse(css).path) == \"swagger-ui.css\":\n            lib_swagger[\"css\"] = css\n            break\n    return lib_swagger\n</code></pre>","tags":["Python API","Swagger"]},{"location":"api-ref/prefect/utilities/services/","title":"services","text":"","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/services/#prefect.utilities.services","title":"<code>prefect.utilities.services</code>","text":"","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/services/#prefect.utilities.services.critical_service_loop","title":"<code>critical_service_loop</code>  <code>async</code>","text":"<p>Runs the given <code>workload</code> function on the specified <code>interval</code>, while being forgiving of intermittent issues like temporary HTTP errors.  If more than a certain number of <code>consecutive</code> errors occur, print a summary of up to <code>memory</code> recent exceptions to <code>printer</code>, then begin backoff.</p> <p>The loop will exit after reaching the consecutive error limit <code>backoff</code> times. On each backoff, the interval will be doubled. On a successful loop, the backoff will be reset.</p> <p>Parameters:</p> Name Type Description Default <code>workload</code> <code>Callable[..., Coroutine]</code> <p>the function to call</p> required <code>interval</code> <code>float</code> <p>how frequently to call it</p> required <code>memory</code> <code>int</code> <p>how many recent errors to remember</p> <code>10</code> <code>consecutive</code> <code>int</code> <p>how many consecutive errors must we see before we begin backoff</p> <code>3</code> <code>backoff</code> <code>int</code> <p>how many times we should allow consecutive errors before exiting</p> <code>1</code> <code>printer</code> <code>Callable[..., None]</code> <p>a <code>print</code>-like function where errors will be reported</p> <code>print</code> <code>run_once</code> <code>bool</code> <p>if set, the loop will only run once then return</p> <code>False</code> <code>jitter_range</code> <code>float</code> <p>if set, the interval will be a random variable (rv) drawn from a clamped Poisson distribution where lambda = interval and the rv is bound between <code>interval * (1 - range) &lt; rv &lt; interval * (1 + range)</code></p> <code>None</code> Source code in <code>prefect/utilities/services.py</code> <pre><code>async def critical_service_loop(\n    workload: Callable[..., Coroutine],\n    interval: float,\n    memory: int = 10,\n    consecutive: int = 3,\n    backoff: int = 1,\n    printer: Callable[..., None] = print,\n    run_once: bool = False,\n    jitter_range: float = None,\n):\n    \"\"\"\n    Runs the given `workload` function on the specified `interval`, while being\n    forgiving of intermittent issues like temporary HTTP errors.  If more than a certain\n    number of `consecutive` errors occur, print a summary of up to `memory` recent\n    exceptions to `printer`, then begin backoff.\n\n    The loop will exit after reaching the consecutive error limit `backoff` times.\n    On each backoff, the interval will be doubled. On a successful loop, the backoff\n    will be reset.\n\n    Args:\n        workload: the function to call\n        interval: how frequently to call it\n        memory: how many recent errors to remember\n        consecutive: how many consecutive errors must we see before we begin backoff\n        backoff: how many times we should allow consecutive errors before exiting\n        printer: a `print`-like function where errors will be reported\n        run_once: if set, the loop will only run once then return\n        jitter_range: if set, the interval will be a random variable (rv) drawn from\n            a clamped Poisson distribution where lambda = interval and the rv is bound\n            between `interval * (1 - range) &lt; rv &lt; interval * (1 + range)`\n    \"\"\"\n\n    track_record: Deque[bool] = deque([True] * consecutive, maxlen=consecutive)\n    failures: Deque[Tuple[Exception, TracebackType]] = deque(maxlen=memory)\n    backoff_count = 0\n\n    while True:\n        try:\n            workload_display_name = (\n                workload.__name__ if hasattr(workload, \"__name__\") else workload\n            )\n            logger.debug(f\"Starting run of {workload_display_name!r}\")\n            await workload()\n\n            # Reset the backoff count on success; we may want to consider resetting\n            # this only if the track record is _all_ successful to avoid ending backoff\n            # prematurely\n            if backoff_count &gt; 0:\n                printer(\"Resetting backoff due to successful run.\")\n                backoff_count = 0\n\n            track_record.append(True)\n        except CancelledError as exc:\n            # Exit immediately because the task was cancelled, possibly due\n            # to a signal or timeout.\n            logger.debug(f\"Run of {workload!r} cancelled\", exc_info=exc)\n            return\n        except httpx.TransportError as exc:\n            # httpx.TransportError is the base class for any kind of communications\n            # error, like timeouts, connection failures, etc.  This does _not_ cover\n            # routine HTTP error codes (even 5xx errors like 502/503) so this\n            # handler should not be attempting to cover cases where the Prefect server\n            # or Prefect Cloud is having an outage (which will be covered by the\n            # exception clause below)\n            track_record.append(False)\n            failures.append((exc, sys.exc_info()[-1]))\n            logger.debug(\n                f\"Run of {workload!r} failed with TransportError\", exc_info=exc\n            )\n        except httpx.HTTPStatusError as exc:\n            if exc.response.status_code &gt;= 500:\n                # 5XX codes indicate a potential outage of the Prefect API which is\n                # likely to be temporary and transient.  Don't quit over these unless\n                # it is prolonged.\n                track_record.append(False)\n                failures.append((exc, sys.exc_info()[-1]))\n                logger.debug(\n                    f\"Run of {workload!r} failed with HTTPStatusError\", exc_info=exc\n                )\n            else:\n                raise\n\n        # Decide whether to exit now based on recent history.\n        #\n        # Given some typical background error rate of, say, 1%, we may still observe\n        # quite a few errors in our recent samples, but this is not necessarily a cause\n        # for concern.\n        #\n        # Imagine two distributions that could reflect our situation at any time: the\n        # everything-is-fine distribution of errors, and the everything-is-on-fire\n        # distribution of errors. We are trying to determine which of those two worlds\n        # we are currently experiencing.  We compare the likelihood that we'd draw N\n        # consecutive errors from each.  In the everything-is-fine distribution, that\n        # would be a very low-probability occurrence, but in the everything-is-on-fire\n        # distribution, that is a high-probability occurrence.\n        #\n        # Remarkably, we only need to look back for a small number of consecutive\n        # errors to have reasonable confidence that this is indeed an anomaly.\n        # @anticorrelator and @chrisguidry estimated that we should only need to look\n        # back for 3 consecutive errors.\n        if not any(track_record):\n            # We've failed enough times to be sure something is wrong, the writing is\n            # on the wall.  Let's explain what we've seen and exit.\n            printer(\n                f\"\\nFailed the last {consecutive} attempts. \"\n                \"Please check your environment and configuration.\"\n            )\n\n            printer(\"Examples of recent errors:\\n\")\n\n            failures_by_type = distinct(\n                reversed(failures),\n                key=lambda pair: type(pair[0]),  # Group by the type of exception\n            )\n            for exception, traceback in failures_by_type:\n                printer(\"\".join(format_exception(None, exception, traceback)))\n                printer()\n\n            backoff_count += 1\n\n            if backoff_count &gt;= backoff:\n                raise RuntimeError(\"Service exceeded error threshold.\")\n\n            # Reset the track record\n            track_record.extend([True] * consecutive)\n            failures.clear()\n            printer(\n                \"Backing off due to consecutive errors, using increased interval of \"\n                f\" {interval * 2 ** backoff_count}s.\"\n            )\n\n        if run_once:\n            return\n\n        if jitter_range is not None:\n            sleep = clamped_poisson_interval(interval, clamping_factor=jitter_range)\n        else:\n            sleep = interval * 2**backoff_count\n\n        await anyio.sleep(sleep)\n</code></pre>","tags":["Python API","services"]},{"location":"api-ref/prefect/utilities/slugify/","title":"slugify","text":"","tags":["Python API","slugify"]},{"location":"api-ref/prefect/utilities/slugify/#prefect.utilities.slugify","title":"<code>prefect.utilities.slugify</code>","text":"","tags":["Python API","slugify"]},{"location":"api-ref/prefect/utilities/templating/","title":"templating","text":"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating","title":"<code>prefect.utilities.templating</code>","text":"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.apply_values","title":"<code>apply_values</code>","text":"<p>Replaces placeholders in a template with values from a supplied dictionary.</p> <p>Will recursively replace placeholders in dictionaries and lists.</p> <p>If a value has no placeholders, it will be returned unchanged.</p> <p>If a template contains only a single placeholder, the placeholder will be fully replaced with the value.</p> <p>If a template contains text before or after a placeholder or there are multiple placeholders, the placeholders will be replaced with the corresponding variable values.</p> <p>If a template contains a placeholder that is not in <code>values</code>, NotSet will be returned to signify that no placeholder replacement occurred. If <code>template</code> is a dictionary that contains a key with a value of NotSet, the key will be removed in the return value unless <code>remove_notset</code> is set to False.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>template to discover and replace values in</p> required <code>values</code> <code>Dict[str, Any]</code> <p>The values to apply to placeholders in the template</p> required <code>remove_notset</code> <code>bool</code> <p>If True, remove keys with an unset value</p> <code>True</code> <p>Returns:</p> Type Description <code>Union[T, Type[NotSet]]</code> <p>The template with the values applied</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def apply_values(\n    template: T, values: Dict[str, Any], remove_notset: bool = True\n) -&gt; Union[T, Type[NotSet]]:\n    \"\"\"\n    Replaces placeholders in a template with values from a supplied dictionary.\n\n    Will recursively replace placeholders in dictionaries and lists.\n\n    If a value has no placeholders, it will be returned unchanged.\n\n    If a template contains only a single placeholder, the placeholder will be\n    fully replaced with the value.\n\n    If a template contains text before or after a placeholder or there are\n    multiple placeholders, the placeholders will be replaced with the\n    corresponding variable values.\n\n    If a template contains a placeholder that is not in `values`, NotSet will\n    be returned to signify that no placeholder replacement occurred. If\n    `template` is a dictionary that contains a key with a value of NotSet,\n    the key will be removed in the return value unless `remove_notset` is set to False.\n\n    Args:\n        template: template to discover and replace values in\n        values: The values to apply to placeholders in the template\n        remove_notset: If True, remove keys with an unset value\n\n    Returns:\n        The template with the values applied\n    \"\"\"\n    if isinstance(template, (int, float, bool, type(NotSet), type(None))):\n        return template\n    if isinstance(template, str):\n        placeholders = find_placeholders(template)\n        if not placeholders:\n            # If there are no values, we can just use the template\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.STANDARD\n        ):\n            # If there is only one variable with no surrounding text,\n            # we can replace it. If there is no variable value, we\n            # return NotSet to indicate that the value should not be included.\n            return get_from_dict(values, list(placeholders)[0].name, NotSet)\n        else:\n            for full_match, name, placeholder_type in placeholders:\n                if placeholder_type is PlaceholderType.STANDARD:\n                    value = get_from_dict(values, name, NotSet)\n                elif placeholder_type is PlaceholderType.ENV_VAR:\n                    name = name.lstrip(ENV_VAR_PLACEHOLDER_PREFIX)\n                    value = os.environ.get(name, NotSet)\n                else:\n                    continue\n\n                if value is NotSet and not remove_notset:\n                    continue\n                elif value is NotSet:\n                    template = template.replace(full_match, \"\")\n                else:\n                    template = template.replace(full_match, str(value))\n\n            return template\n    elif isinstance(template, dict):\n        updated_template = {}\n        for key, value in template.items():\n            updated_value = apply_values(value, values, remove_notset=remove_notset)\n            if updated_value is not NotSet:\n                updated_template[key] = updated_value\n            elif not remove_notset:\n                updated_template[key] = value\n\n        return updated_template\n    elif isinstance(template, list):\n        updated_list = []\n        for value in template:\n            updated_value = apply_values(value, values, remove_notset=remove_notset)\n            if updated_value is not NotSet:\n                updated_list.append(updated_value)\n        return updated_list\n    else:\n        raise ValueError(f\"Unexpected template type {type(template).__name__!r}\")\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.determine_placeholder_type","title":"<code>determine_placeholder_type</code>","text":"<p>Determines the type of a placeholder based on its name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the placeholder</p> required <p>Returns:</p> Type Description <code>PlaceholderType</code> <p>The type of the placeholder</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def determine_placeholder_type(name: str) -&gt; PlaceholderType:\n    \"\"\"\n    Determines the type of a placeholder based on its name.\n\n    Args:\n        name: The name of the placeholder\n\n    Returns:\n        The type of the placeholder\n    \"\"\"\n    if name.startswith(BLOCK_DOCUMENT_PLACEHOLDER_PREFIX):\n        return PlaceholderType.BLOCK_DOCUMENT\n    elif name.startswith(VARIABLE_PLACEHOLDER_PREFIX):\n        return PlaceholderType.VARIABLE\n    elif name.startswith(ENV_VAR_PLACEHOLDER_PREFIX):\n        return PlaceholderType.ENV_VAR\n    else:\n        return PlaceholderType.STANDARD\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.find_placeholders","title":"<code>find_placeholders</code>","text":"<p>Finds all placeholders in a template.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>template to discover placeholders in</p> required <p>Returns:</p> Type Description <code>Set[Placeholder]</code> <p>A set of all placeholders in the template</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>def find_placeholders(template: T) -&gt; Set[Placeholder]:\n    \"\"\"\n    Finds all placeholders in a template.\n\n    Args:\n        template: template to discover placeholders in\n\n    Returns:\n        A set of all placeholders in the template\n    \"\"\"\n    if isinstance(template, (int, float, bool)):\n        return set()\n    if isinstance(template, str):\n        result = PLACEHOLDER_CAPTURE_REGEX.findall(template)\n        return {\n            Placeholder(full_match, name, determine_placeholder_type(name))\n            for full_match, name in result\n        }\n    elif isinstance(template, dict):\n        return set().union(\n            *[find_placeholders(value) for key, value in template.items()]\n        )\n    elif isinstance(template, list):\n        return set().union(*[find_placeholders(item) for item in template])\n    else:\n        raise ValueError(f\"Unexpected type: {type(template)}\")\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references","title":"<code>resolve_block_document_references</code>  <code>async</code>","text":"<p>Resolve block document references in a template by replacing each reference with the data of the block document.</p> <p>Recursively searches for block document references in dictionaries and lists.</p> <p>Identifies block document references by the as dictionary with the following structure: <pre><code>{\n    \"$ref\": {\n        \"block_document_id\": &lt;block_document_id&gt;\n    }\n}\n</code></pre> where <code>&lt;block_document_id&gt;</code> is the ID of the block document to resolve.</p> <p>Once the block document is retrieved from the API, the data of the block document is used to replace the reference.</p>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references--accessing-values","title":"Accessing Values:","text":"<p>To access different values in a block document, use dot notation combined with the block document's prefix, slug, and block name.</p> <p>For a block document with the structure: <pre><code>{\n    \"value\": {\n        \"key\": {\n            \"nested-key\": \"nested-value\"\n        },\n        \"list\": [\n            {\"list-key\": \"list-value\"},\n            1,\n            2\n        ]\n    }\n}\n</code></pre> examples of value resolution are as follows:</p> <ol> <li> <p>Accessing a nested dictionary:    Format: prefect.blocks...value.key    Example: Returns {\"nested-key\": \"nested-value\"} <li> <p>Accessing a specific nested value:    Format: prefect.blocks...value.key.nested-key    Example: Returns \"nested-value\" <li> <p>Accessing a list element's key-value:    Format: prefect.blocks...value.list[0].list-key    Example: Returns \"list-value\"","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_block_document_references--default-resolution-for-system-blocks","title":"Default Resolution for System Blocks:","text":"<p>For system blocks, which only contain a <code>value</code> attribute, this attribute is resolved by default.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>The template to resolve block documents in</p> required <p>Returns:</p> Type Description <code>Union[T, Dict[str, Any]]</code> <p>The template with block documents resolved</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>@inject_client\nasync def resolve_block_document_references(\n    template: T, client: \"PrefectClient\" = None\n) -&gt; Union[T, Dict[str, Any]]:\n    \"\"\"\n    Resolve block document references in a template by replacing each reference with\n    the data of the block document.\n\n    Recursively searches for block document references in dictionaries and lists.\n\n    Identifies block document references by the as dictionary with the following\n    structure:\n    ```\n    {\n        \"$ref\": {\n            \"block_document_id\": &lt;block_document_id&gt;\n        }\n    }\n    ```\n    where `&lt;block_document_id&gt;` is the ID of the block document to resolve.\n\n    Once the block document is retrieved from the API, the data of the block document\n    is used to replace the reference.\n\n    Accessing Values:\n    -----------------\n    To access different values in a block document, use dot notation combined with the block document's prefix, slug, and block name.\n\n    For a block document with the structure:\n    ```json\n    {\n        \"value\": {\n            \"key\": {\n                \"nested-key\": \"nested-value\"\n            },\n            \"list\": [\n                {\"list-key\": \"list-value\"},\n                1,\n                2\n            ]\n        }\n    }\n    ```\n    examples of value resolution are as follows:\n\n    1. Accessing a nested dictionary:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.key\n       Example: Returns {\"nested-key\": \"nested-value\"}\n\n    2. Accessing a specific nested value:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.key.nested-key\n       Example: Returns \"nested-value\"\n\n    3. Accessing a list element's key-value:\n       Format: prefect.blocks.&lt;block_type_slug&gt;.&lt;block_document_name&gt;.value.list[0].list-key\n       Example: Returns \"list-value\"\n\n    Default Resolution for System Blocks:\n    -------------------------------------\n    For system blocks, which only contain a `value` attribute, this attribute is resolved by default.\n\n    Args:\n        template: The template to resolve block documents in\n\n    Returns:\n        The template with block documents resolved\n    \"\"\"\n    if isinstance(template, dict):\n        block_document_id = template.get(\"$ref\", {}).get(\"block_document_id\")\n        if block_document_id:\n            block_document = await client.read_block_document(block_document_id)\n            return block_document.data\n        updated_template = {}\n        for key, value in template.items():\n            updated_value = await resolve_block_document_references(\n                value, client=client\n            )\n            updated_template[key] = updated_value\n        return updated_template\n    elif isinstance(template, list):\n        return [\n            await resolve_block_document_references(item, client=client)\n            for item in template\n        ]\n    elif isinstance(template, str):\n        placeholders = find_placeholders(template)\n        has_block_document_placeholder = any(\n            placeholder.type is PlaceholderType.BLOCK_DOCUMENT\n            for placeholder in placeholders\n        )\n        if len(placeholders) == 0 or not has_block_document_placeholder:\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.BLOCK_DOCUMENT\n        ):\n            # value_keypath will be a list containing a dot path if additional\n            # attributes are accessed and an empty list otherwise.\n            block_type_slug, block_document_name, *value_keypath = (\n                list(placeholders)[0]\n                .name.replace(BLOCK_DOCUMENT_PLACEHOLDER_PREFIX, \"\")\n                .split(\".\", 2)\n            )\n            block_document = await client.read_block_document_by_name(\n                name=block_document_name, block_type_slug=block_type_slug\n            )\n            value = block_document.data\n\n            # resolving system blocks to their data for backwards compatibility\n            if len(value) == 1 and \"value\" in value:\n                # only resolve the value if the keypath is not already pointing to \"value\"\n                if len(value_keypath) == 0 or value_keypath[0][:5] != \"value\":\n                    value = value[\"value\"]\n\n            # resolving keypath/block attributes\n            if len(value_keypath) &gt; 0:\n                value_keypath: str = value_keypath[0]\n                value = get_from_dict(value, value_keypath, default=NotSet)\n                if value is NotSet:\n                    raise ValueError(\n                        f\"Invalid template: {template!r}. Could not resolve the\"\n                        \" keypath in the block document data.\"\n                    )\n\n            return value\n        else:\n            raise ValueError(\n                f\"Invalid template: {template!r}. Only a single block placeholder is\"\n                \" allowed in a string and no surrounding text is allowed.\"\n            )\n\n    return template\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/templating/#prefect.utilities.templating.resolve_variables","title":"<code>resolve_variables</code>  <code>async</code>","text":"<p>Resolve variables in a template by replacing each variable placeholder with the value of the variable.</p> <p>Recursively searches for variable placeholders in dictionaries and lists.</p> <p>Strips variable placeholders if the variable is not found.</p> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>T</code> <p>The template to resolve variables in</p> required <p>Returns:</p> Type Description <p>The template with variables resolved</p> Source code in <code>prefect/utilities/templating.py</code> <pre><code>@inject_client\nasync def resolve_variables(template: T, client: \"PrefectClient\" = None):\n    \"\"\"\n    Resolve variables in a template by replacing each variable placeholder with the\n    value of the variable.\n\n    Recursively searches for variable placeholders in dictionaries and lists.\n\n    Strips variable placeholders if the variable is not found.\n\n    Args:\n        template: The template to resolve variables in\n\n    Returns:\n        The template with variables resolved\n    \"\"\"\n    if isinstance(template, str):\n        placeholders = find_placeholders(template)\n        has_variable_placeholder = any(\n            placeholder.type is PlaceholderType.VARIABLE for placeholder in placeholders\n        )\n        if not placeholders or not has_variable_placeholder:\n            # If there are no values, we can just use the template\n            return template\n        elif (\n            len(placeholders) == 1\n            and list(placeholders)[0].full_match == template\n            and list(placeholders)[0].type is PlaceholderType.VARIABLE\n        ):\n            variable_name = list(placeholders)[0].name.replace(\n                VARIABLE_PLACEHOLDER_PREFIX, \"\"\n            )\n            variable = await client.read_variable_by_name(name=variable_name)\n            if variable is None:\n                return \"\"\n            else:\n                return variable.value\n        else:\n            for full_match, name, placeholder_type in placeholders:\n                if placeholder_type is PlaceholderType.VARIABLE:\n                    variable_name = name.replace(VARIABLE_PLACEHOLDER_PREFIX, \"\")\n                    variable = await client.read_variable_by_name(name=variable_name)\n                    if variable is None:\n                        template = template.replace(full_match, \"\")\n                    else:\n                        template = template.replace(full_match, variable.value)\n            return template\n    elif isinstance(template, dict):\n        return {\n            key: await resolve_variables(value, client=client)\n            for key, value in template.items()\n        }\n    elif isinstance(template, list):\n        return [await resolve_variables(item, client=client) for item in template]\n    else:\n        return template\n</code></pre>","tags":["Python API","templating"]},{"location":"api-ref/prefect/utilities/text/","title":"text","text":"","tags":["Python API","text"]},{"location":"api-ref/prefect/utilities/text/#prefect.utilities.text","title":"<code>prefect.utilities.text</code>","text":"","tags":["Python API","text"]},{"location":"api-ref/prefect/utilities/visualization/","title":"visualization","text":"","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization","title":"<code>prefect.utilities.visualization</code>","text":"<p>Utilities for working with Flow.visualize()</p>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.TaskVizTracker","title":"<code>TaskVizTracker</code>","text":"Source code in <code>prefect/utilities/visualization.py</code> <pre><code>class TaskVizTracker:\n    def __init__(self):\n        self.tasks = []\n        self.dynamic_task_counter = {}\n        self.object_id_to_task = {}\n\n    def add_task(self, task: VizTask):\n        if task.name not in self.dynamic_task_counter:\n            self.dynamic_task_counter[task.name] = 0\n        else:\n            self.dynamic_task_counter[task.name] += 1\n\n        task.name = f\"{task.name}-{self.dynamic_task_counter[task.name]}\"\n        self.tasks.append(task)\n\n    def __enter__(self):\n        TaskVizTrackerState.current = self\n        return self\n\n    def __exit__(self, exc_type, exc_val, exc_tb):\n        TaskVizTrackerState.current = None\n\n    def link_viz_return_value_to_viz_task(\n        self, viz_return_value: Any, viz_task: VizTask\n    ) -&gt; None:\n        \"\"\"\n        We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256\n        because they are singletons.\n        \"\"\"\n        from prefect.utilities.engine import UNTRACKABLE_TYPES\n\n        if (type(viz_return_value) in UNTRACKABLE_TYPES) or (\n            isinstance(viz_return_value, int) and (-5 &lt;= viz_return_value &lt;= 256)\n        ):\n            return\n        self.object_id_to_task[id(viz_return_value)] = viz_task\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.TaskVizTracker.link_viz_return_value_to_viz_task","title":"<code>link_viz_return_value_to_viz_task</code>","text":"<p>We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256 because they are singletons.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def link_viz_return_value_to_viz_task(\n    self, viz_return_value: Any, viz_task: VizTask\n) -&gt; None:\n    \"\"\"\n    We cannot track booleans, Ellipsis, None, NotImplemented, or the integers from -5 to 256\n    because they are singletons.\n    \"\"\"\n    from prefect.utilities.engine import UNTRACKABLE_TYPES\n\n    if (type(viz_return_value) in UNTRACKABLE_TYPES) or (\n        isinstance(viz_return_value, int) and (-5 &lt;= viz_return_value &lt;= 256)\n    ):\n        return\n    self.object_id_to_task[id(viz_return_value)] = viz_task\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.build_task_dependencies","title":"<code>build_task_dependencies</code>","text":"<p>Constructs a Graphviz directed graph object that represents the dependencies between tasks in the given TaskVizTracker.</p> <ul> <li>task_run_tracker (TaskVizTracker): An object containing tasks and their   dependencies.</li> </ul> <ul> <li>graphviz.Digraph: A directed graph object depicting the relationships and   dependencies between tasks.</li> </ul> <p>Raises: - GraphvizImportError: If there's an ImportError related to graphviz. - FlowVisualizationError: If there's any other error during the visualization   process or if return values of tasks are directly accessed without   specifying a <code>viz_return_value</code>.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def build_task_dependencies(task_run_tracker: TaskVizTracker):\n    \"\"\"\n    Constructs a Graphviz directed graph object that represents the dependencies\n    between tasks in the given TaskVizTracker.\n\n    Parameters:\n    - task_run_tracker (TaskVizTracker): An object containing tasks and their\n      dependencies.\n\n    Returns:\n    - graphviz.Digraph: A directed graph object depicting the relationships and\n      dependencies between tasks.\n\n    Raises:\n    - GraphvizImportError: If there's an ImportError related to graphviz.\n    - FlowVisualizationError: If there's any other error during the visualization\n      process or if return values of tasks are directly accessed without\n      specifying a `viz_return_value`.\n    \"\"\"\n    try:\n        g = graphviz.Digraph()\n        for task in task_run_tracker.tasks:\n            g.node(task.name)\n            for upstream in task.upstream_tasks:\n                g.edge(upstream.name, task.name)\n        return g\n    except ImportError as exc:\n        raise GraphvizImportError from exc\n    except Exception:\n        raise FlowVisualizationError(\n            \"Something went wrong building the flow's visualization.\"\n            \" If you're interacting with the return value of a task\"\n            \" directly inside of your flow, you must set a set a `viz_return_value`\"\n            \", for example `@task(viz_return_value=[1, 2, 3])`.\"\n        )\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.track_viz_task","title":"<code>track_viz_task</code>","text":"<p>Return a result if sync otherwise return a coroutine that returns the result</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def track_viz_task(\n    is_async: bool,\n    task_name: str,\n    parameters: dict,\n    viz_return_value: Optional[Any] = None,\n):\n    \"\"\"Return a result if sync otherwise return a coroutine that returns the result\"\"\"\n    if is_async:\n        return from_async.wait_for_call_in_loop_thread(\n            partial(_track_viz_task, task_name, parameters, viz_return_value)\n        )\n    else:\n        return _track_viz_task(task_name, parameters, viz_return_value)\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/utilities/visualization/#prefect.utilities.visualization.visualize_task_dependencies","title":"<code>visualize_task_dependencies</code>","text":"<p>Renders and displays a Graphviz directed graph representing task dependencies.</p> <p>The graph is rendered in PNG format and saved with the name specified by flow_run_name. After rendering, the visualization is opened and displayed.</p> <p>Parameters: - graph (graphviz.Digraph): The directed graph object to visualize. - flow_run_name (str): The name to use when saving the rendered graph image.</p> <p>Raises: - GraphvizExecutableNotFoundError: If Graphviz isn't found on the system. - FlowVisualizationError: If there's any other error during the visualization   process or if return values of tasks are directly accessed without   specifying a <code>viz_return_value</code>.</p> Source code in <code>prefect/utilities/visualization.py</code> <pre><code>def visualize_task_dependencies(graph: graphviz.Digraph, flow_run_name: str):\n    \"\"\"\n    Renders and displays a Graphviz directed graph representing task dependencies.\n\n    The graph is rendered in PNG format and saved with the name specified by\n    flow_run_name. After rendering, the visualization is opened and displayed.\n\n    Parameters:\n    - graph (graphviz.Digraph): The directed graph object to visualize.\n    - flow_run_name (str): The name to use when saving the rendered graph image.\n\n    Raises:\n    - GraphvizExecutableNotFoundError: If Graphviz isn't found on the system.\n    - FlowVisualizationError: If there's any other error during the visualization\n      process or if return values of tasks are directly accessed without\n      specifying a `viz_return_value`.\n    \"\"\"\n    try:\n        graph.render(filename=flow_run_name, view=True, format=\"png\", cleanup=True)\n    except graphviz.backend.ExecutableNotFound as exc:\n        msg = (\n            \"It appears you do not have Graphviz installed, or it is not on your \"\n            \"PATH. Please install Graphviz from http://www.graphviz.org/download/. \"\n            \"Note: Just installing the `graphviz` python package is not \"\n            \"sufficient.\"\n        )\n        raise GraphvizExecutableNotFoundError(msg) from exc\n    except Exception:\n        raise FlowVisualizationError(\n            \"Something went wrong building the flow's visualization.\"\n            \" If you're interacting with the return value of a task\"\n            \" directly inside of your flow, you must set a set a `viz_return_value`\"\n            \", for example `@task(viz_return_value=[1, 2, 3])`.\"\n        )\n</code></pre>","tags":["Python API","visualization"]},{"location":"api-ref/prefect/workers/base/","title":"base","text":"","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base","title":"<code>prefect.workers.base</code>","text":"","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration","title":"<code>BaseJobConfiguration</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>class BaseJobConfiguration(BaseModel):\n    command: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The command to use when starting a flow run. \"\n            \"In most cases, this should be left blank and the command \"\n            \"will be automatically generated by the worker.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to set when starting a flow run.\",\n    )\n    labels: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"Labels applied to infrastructure created by the worker using \"\n            \"this job configuration.\"\n        ),\n    )\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"Name given to infrastructure created by the worker using this \"\n            \"job configuration.\"\n        ),\n    )\n\n    _related_objects: Dict[str, Any] = PrivateAttr(default_factory=dict)\n\n    @property\n    def is_using_a_runner(self):\n        return self.command is not None and \"prefect flow-run execute\" in self.command\n\n    @validator(\"command\")\n    def _coerce_command(cls, v):\n        return return_v_or_none(v)\n\n    @staticmethod\n    def _get_base_config_defaults(variables: dict) -&gt; dict:\n        \"\"\"Get default values from base config for all variables that have them.\"\"\"\n        defaults = dict()\n        for variable_name, attrs in variables.items():\n            if \"default\" in attrs:\n                defaults[variable_name] = attrs[\"default\"]\n\n        return defaults\n\n    @classmethod\n    @inject_client\n    async def from_template_and_values(\n        cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n    ):\n        \"\"\"Creates a valid worker configuration object from the provided base\n        configuration and overrides.\n\n        Important: this method expects that the base_job_template was already\n        validated server-side.\n        \"\"\"\n        job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n        variables_schema = base_job_template[\"variables\"]\n        variables = cls._get_base_config_defaults(\n            variables_schema.get(\"properties\", {})\n        )\n        variables.update(values)\n\n        populated_configuration = apply_values(template=job_config, values=variables)\n        populated_configuration = await resolve_block_document_references(\n            template=populated_configuration, client=client\n        )\n        populated_configuration = await resolve_variables(\n            template=populated_configuration, client=client\n        )\n        return cls(**populated_configuration)\n\n    @classmethod\n    def json_template(cls) -&gt; dict:\n        \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n        Defaults to using the job configuration parameter name as the template variable name.\n\n        e.g.\n        {\n            key1: '{{ key1 }}',     # default variable template\n            key2: '{{ template2 }}', # `template2` specifically provide as template\n        }\n        \"\"\"\n        configuration = {}\n        properties = cls.schema()[\"properties\"]\n        for k, v in properties.items():\n            if v.get(\"template\"):\n                template = v[\"template\"]\n            else:\n                template = \"{{ \" + k + \" }}\"\n            configuration[k] = template\n\n        return configuration\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepare the job configuration for a flow run.\n\n        This method is called by the worker before starting a flow run. It\n        should be used to set any configuration values that are dependent on\n        the flow run.\n\n        Args:\n            flow_run: The flow run to be executed.\n            deployment: The deployment that the flow run is associated with.\n            flow: The flow that the flow run is associated with.\n        \"\"\"\n\n        self._related_objects = {\n            \"deployment\": deployment,\n            \"flow\": flow,\n            \"flow-run\": flow_run,\n        }\n        if deployment is not None:\n            deployment_labels = self._base_deployment_labels(deployment)\n        else:\n            deployment_labels = {}\n\n        if flow is not None:\n            flow_labels = self._base_flow_labels(flow)\n        else:\n            flow_labels = {}\n\n        env = {\n            **self._base_environment(),\n            **self._base_flow_run_environment(flow_run),\n            **self.env,\n        }\n        self.env = {key: value for key, value in env.items() if value is not None}\n        self.labels = {\n            **self._base_flow_run_labels(flow_run),\n            **deployment_labels,\n            **flow_labels,\n            **self.labels,\n        }\n        self.name = self.name or flow_run.name\n        self.command = self.command or self._base_flow_run_command()\n\n    @staticmethod\n    def _base_flow_run_command() -&gt; str:\n        \"\"\"\n        Generate a command for a flow run job.\n        \"\"\"\n        if experiment_enabled(\"enhanced_cancellation\"):\n            if (\n                PREFECT_EXPERIMENTAL_WARN\n                and PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION\n            ):\n                warnings.warn(\n                    EXPERIMENTAL_WARNING.format(\n                        feature=\"Enhanced flow run cancellation\",\n                        group=\"enhanced_cancellation\",\n                        help=\"\",\n                    ),\n                    ExperimentalFeature,\n                    stacklevel=3,\n                )\n            return \"prefect flow-run execute\"\n        return \"python -m prefect.engine\"\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": prefect.__version__,\n        }\n\n    @classmethod\n    def _base_environment(cls) -&gt; Dict[str, str]:\n        \"\"\"\n        Environment variables that should be passed to all created infrastructure.\n\n        These values should be overridable with the `env` field.\n        \"\"\"\n        return get_current_settings().to_environment_variables(exclude_unset=True)\n\n    @staticmethod\n    def _base_flow_run_environment(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of environment variables for a flow run job.\n        \"\"\"\n        return {\"PREFECT__FLOW_RUN_ID\": str(flow_run.id)}\n\n    @staticmethod\n    def _base_deployment_labels(deployment: \"DeploymentResponse\") -&gt; Dict[str, str]:\n        labels = {\n            \"prefect.io/deployment-id\": str(deployment.id),\n            \"prefect.io/deployment-name\": deployment.name,\n        }\n        if deployment.updated is not None:\n            labels[\"prefect.io/deployment-updated\"] = deployment.updated.in_timezone(\n                \"utc\"\n            ).to_iso8601_string()\n        return labels\n\n    @staticmethod\n    def _base_flow_labels(flow: \"Flow\") -&gt; Dict[str, str]:\n        return {\n            \"prefect.io/flow-id\": str(flow.id),\n            \"prefect.io/flow-name\": flow.name,\n        }\n\n    def _related_resources(self) -&gt; List[RelatedResource]:\n        tags = set()\n        related = []\n\n        for kind, obj in self._related_objects.items():\n            if obj is None:\n                continue\n            if hasattr(obj, \"tags\"):\n                tags.update(obj.tags)\n            related.append(object_as_related_resource(kind=kind, role=kind, object=obj))\n\n        return related + tags_as_related_resources(tags)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.from_template_and_values","title":"<code>from_template_and_values</code>  <code>async</code> <code>classmethod</code>","text":"<p>Creates a valid worker configuration object from the provided base configuration and overrides.</p> <p>Important: this method expects that the base_job_template was already validated server-side.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@classmethod\n@inject_client\nasync def from_template_and_values(\n    cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n):\n    \"\"\"Creates a valid worker configuration object from the provided base\n    configuration and overrides.\n\n    Important: this method expects that the base_job_template was already\n    validated server-side.\n    \"\"\"\n    job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n    variables_schema = base_job_template[\"variables\"]\n    variables = cls._get_base_config_defaults(\n        variables_schema.get(\"properties\", {})\n    )\n    variables.update(values)\n\n    populated_configuration = apply_values(template=job_config, values=variables)\n    populated_configuration = await resolve_block_document_references(\n        template=populated_configuration, client=client\n    )\n    populated_configuration = await resolve_variables(\n        template=populated_configuration, client=client\n    )\n    return cls(**populated_configuration)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.json_template","title":"<code>json_template</code>  <code>classmethod</code>","text":"<p>Returns a dict with job configuration as keys and the corresponding templates as values</p> <p>Defaults to using the job configuration parameter name as the template variable name.</p> <p>e.g. {     key1: '{{ key1 }}',     # default variable template     key2: '{{ template2 }}', # <code>template2</code> specifically provide as template }</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@classmethod\ndef json_template(cls) -&gt; dict:\n    \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n    Defaults to using the job configuration parameter name as the template variable name.\n\n    e.g.\n    {\n        key1: '{{ key1 }}',     # default variable template\n        key2: '{{ template2 }}', # `template2` specifically provide as template\n    }\n    \"\"\"\n    configuration = {}\n    properties = cls.schema()[\"properties\"]\n    for k, v in properties.items():\n        if v.get(\"template\"):\n            template = v[\"template\"]\n        else:\n            template = \"{{ \" + k + \" }}\"\n        configuration[k] = template\n\n    return configuration\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepare the job configuration for a flow run.</p> <p>This method is called by the worker before starting a flow run. It should be used to set any configuration values that are dependent on the flow run.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to be executed.</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment that the flow run is associated with.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow that the flow run is associated with.</p> <code>None</code> Source code in <code>prefect/workers/base.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepare the job configuration for a flow run.\n\n    This method is called by the worker before starting a flow run. It\n    should be used to set any configuration values that are dependent on\n    the flow run.\n\n    Args:\n        flow_run: The flow run to be executed.\n        deployment: The deployment that the flow run is associated with.\n        flow: The flow that the flow run is associated with.\n    \"\"\"\n\n    self._related_objects = {\n        \"deployment\": deployment,\n        \"flow\": flow,\n        \"flow-run\": flow_run,\n    }\n    if deployment is not None:\n        deployment_labels = self._base_deployment_labels(deployment)\n    else:\n        deployment_labels = {}\n\n    if flow is not None:\n        flow_labels = self._base_flow_labels(flow)\n    else:\n        flow_labels = {}\n\n    env = {\n        **self._base_environment(),\n        **self._base_flow_run_environment(flow_run),\n        **self.env,\n    }\n    self.env = {key: value for key, value in env.items() if value is not None}\n    self.labels = {\n        **self._base_flow_run_labels(flow_run),\n        **deployment_labels,\n        **flow_labels,\n        **self.labels,\n    }\n    self.name = self.name or flow_run.name\n    self.command = self.command or self._base_flow_run_command()\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker","title":"<code>BaseWorker</code>","text":"<p>               Bases: <code>ABC</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>@register_base_type\nclass BaseWorker(abc.ABC):\n    type: str\n    job_configuration: Type[BaseJobConfiguration] = BaseJobConfiguration\n    job_configuration_variables: Optional[Type[BaseVariables]] = None\n\n    _documentation_url = \"\"\n    _logo_url = \"\"\n    _description = \"\"\n\n    def __init__(\n        self,\n        work_pool_name: str,\n        work_queues: Optional[List[str]] = None,\n        name: Optional[str] = None,\n        prefetch_seconds: Optional[float] = None,\n        create_pool_if_not_found: bool = True,\n        limit: Optional[int] = None,\n        heartbeat_interval_seconds: Optional[int] = None,\n        *,\n        base_job_template: Optional[Dict[str, Any]] = None,\n    ):\n        \"\"\"\n        Base class for all Prefect workers.\n\n        Args:\n            name: The name of the worker. If not provided, a random one\n                will be generated. If provided, it cannot contain '/' or '%'.\n                The name is used to identify the worker in the UI; if two\n                processes have the same name, they will be treated as the same\n                worker.\n            work_pool_name: The name of the work pool to poll.\n            work_queues: A list of work queues to poll. If not provided, all\n                work queue in the work pool will be polled.\n            prefetch_seconds: The number of seconds to prefetch flow runs for.\n            create_pool_if_not_found: Whether to create the work pool\n                if it is not found. Defaults to `True`, but can be set to `False` to\n                ensure that work pools are not created accidentally.\n            limit: The maximum number of flow runs this worker should be running at\n                a given time.\n            base_job_template: If creating the work pool, provide the base job\n                template to use. Logs a warning if the pool already exists.\n        \"\"\"\n        if name and (\"/\" in name or \"%\" in name):\n            raise ValueError(\"Worker name cannot contain '/' or '%'\")\n        self.name = name or f\"{self.__class__.__name__} {uuid4()}\"\n        self._logger = get_logger(f\"worker.{self.__class__.type}.{self.name.lower()}\")\n\n        self.is_setup = False\n        self._create_pool_if_not_found = create_pool_if_not_found\n        self._base_job_template = base_job_template\n        self._work_pool_name = work_pool_name\n        self._work_queues: Set[str] = set(work_queues) if work_queues else set()\n\n        self._prefetch_seconds: float = (\n            prefetch_seconds or PREFECT_WORKER_PREFETCH_SECONDS.value()\n        )\n        self.heartbeat_interval_seconds = (\n            heartbeat_interval_seconds or PREFECT_WORKER_HEARTBEAT_SECONDS.value()\n        )\n\n        self._work_pool: Optional[WorkPool] = None\n        self._runs_task_group: Optional[anyio.abc.TaskGroup] = None\n        self._client: Optional[PrefectClient] = None\n        self._last_polled_time: pendulum.DateTime = pendulum.now(\"utc\")\n        self._limit = limit\n        self._limiter: Optional[anyio.CapacityLimiter] = None\n        self._submitting_flow_run_ids = set()\n        self._cancelling_flow_run_ids = set()\n        self._scheduled_task_scopes = set()\n\n    @classmethod\n    def get_documentation_url(cls) -&gt; str:\n        return cls._documentation_url\n\n    @classmethod\n    def get_logo_url(cls) -&gt; str:\n        return cls._logo_url\n\n    @classmethod\n    def get_description(cls) -&gt; str:\n        return cls._description\n\n    @classmethod\n    def get_default_base_job_template(cls) -&gt; Dict:\n        if cls.job_configuration_variables is None:\n            schema = cls.job_configuration.schema()\n            # remove \"template\" key from all dicts in schema['properties'] because it is not a\n            # relevant field\n            for key, value in schema[\"properties\"].items():\n                if isinstance(value, dict):\n                    schema[\"properties\"][key].pop(\"template\", None)\n            variables_schema = schema\n        else:\n            variables_schema = cls.job_configuration_variables.schema()\n        variables_schema.pop(\"title\", None)\n        return {\n            \"job_configuration\": cls.job_configuration.json_template(),\n            \"variables\": variables_schema,\n        }\n\n    @staticmethod\n    def get_worker_class_from_type(type: str) -&gt; Optional[Type[\"BaseWorker\"]]:\n        \"\"\"\n        Returns the worker class for a given worker type. If the worker type\n        is not recognized, returns None.\n        \"\"\"\n        load_prefect_collections()\n        worker_registry = get_registry_for_type(BaseWorker)\n        if worker_registry is not None:\n            return worker_registry.get(type)\n\n    @staticmethod\n    def get_all_available_worker_types() -&gt; List[str]:\n        \"\"\"\n        Returns all worker types available in the local registry.\n        \"\"\"\n        load_prefect_collections()\n        worker_registry = get_registry_for_type(BaseWorker)\n        if worker_registry is not None:\n            return list(worker_registry.keys())\n        return []\n\n    def get_name_slug(self):\n        return slugify(self.name)\n\n    def get_flow_run_logger(self, flow_run: \"FlowRun\") -&gt; PrefectLogAdapter:\n        return flow_run_logger(flow_run=flow_run).getChild(\n            \"worker\",\n            extra={\n                \"worker_name\": self.name,\n                \"work_pool_name\": (\n                    self._work_pool_name if self._work_pool else \"&lt;unknown&gt;\"\n                ),\n                \"work_pool_id\": str(getattr(self._work_pool, \"id\", \"unknown\")),\n            },\n        )\n\n    @abc.abstractmethod\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: BaseJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        \"\"\"\n        Runs a given flow run on the current worker.\n        \"\"\"\n        raise NotImplementedError(\n            \"Workers must implement a method for running submitted flow runs\"\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: BaseJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Method for killing infrastructure created by a worker. Should be implemented by\n        individual workers if they support killing infrastructure.\n        \"\"\"\n        raise NotImplementedError(\n            \"This worker does not support killing infrastructure.\"\n        )\n\n    @classmethod\n    def __dispatch_key__(cls):\n        if cls.__name__ == \"BaseWorker\":\n            return None  # The base class is abstract\n        return cls.type\n\n    async def setup(self):\n        \"\"\"Prepares the worker to run.\"\"\"\n        self._logger.debug(\"Setting up worker...\")\n        self._runs_task_group = anyio.create_task_group()\n        self._limiter = (\n            anyio.CapacityLimiter(self._limit) if self._limit is not None else None\n        )\n        self._client = get_client()\n        await self._client.__aenter__()\n        await self._runs_task_group.__aenter__()\n\n        self.is_setup = True\n\n    async def teardown(self, *exc_info):\n        \"\"\"Cleans up resources after the worker is stopped.\"\"\"\n        self._logger.debug(\"Tearing down worker...\")\n        self.is_setup = False\n        for scope in self._scheduled_task_scopes:\n            scope.cancel()\n        if self._runs_task_group:\n            await self._runs_task_group.__aexit__(*exc_info)\n        if self._client:\n            await self._client.__aexit__(*exc_info)\n        self._runs_task_group = None\n        self._client = None\n\n    def is_worker_still_polling(self, query_interval_seconds: int) -&gt; bool:\n        \"\"\"\n        This method is invoked by a webserver healthcheck handler\n        and returns a boolean indicating if the worker has recorded a\n        scheduled flow run poll within a variable amount of time.\n\n        The `query_interval_seconds` is the same value that is used by\n        the loop services - we will evaluate if the _last_polled_time\n        was within that interval x 30 (so 10s -&gt; 5m)\n\n        The instance property `self._last_polled_time`\n        is currently set/updated in `get_and_submit_flow_runs()`\n        \"\"\"\n        threshold_seconds = query_interval_seconds * 30\n\n        seconds_since_last_poll = (\n            pendulum.now(\"utc\") - self._last_polled_time\n        ).in_seconds()\n\n        is_still_polling = seconds_since_last_poll &lt;= threshold_seconds\n\n        if not is_still_polling:\n            self._logger.error(\n                f\"Worker has not polled in the last {seconds_since_last_poll} seconds \"\n                \"and should be restarted\"\n            )\n\n        return is_still_polling\n\n    async def get_and_submit_flow_runs(self):\n        runs_response = await self._get_scheduled_flow_runs()\n\n        self._last_polled_time = pendulum.now(\"utc\")\n\n        return await self._submit_scheduled_flow_runs(flow_run_response=runs_response)\n\n    async def check_for_cancelled_flow_runs(self):\n        if not self.is_setup:\n            raise RuntimeError(\n                \"Worker is not set up. Please make sure you are running this worker \"\n                \"as an async context manager.\"\n            )\n\n        self._logger.debug(\"Checking for cancelled flow runs...\")\n\n        work_queue_filter = (\n            WorkQueueFilter(name=WorkQueueFilterName(any_=list(self._work_queues)))\n            if self._work_queues\n            else None\n        )\n\n        named_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),\n                    name=FlowRunFilterStateName(any_=[\"Cancelling\"]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self._cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=WorkPoolFilter(\n                name=WorkPoolFilterName(any_=[self._work_pool_name])\n            ),\n            work_queue_filter=work_queue_filter,\n        )\n\n        typed_cancelling_flow_runs = await self._client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),\n                ),\n                # Avoid duplicate cancellation calls\n                id=FlowRunFilterId(not_any_=list(self._cancelling_flow_run_ids)),\n            ),\n            work_pool_filter=WorkPoolFilter(\n                name=WorkPoolFilterName(any_=[self._work_pool_name])\n            ),\n            work_queue_filter=work_queue_filter,\n        )\n\n        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs\n\n        if cancelling_flow_runs:\n            self._logger.info(\n                f\"Found {len(cancelling_flow_runs)} flow runs awaiting cancellation.\"\n            )\n\n        for flow_run in cancelling_flow_runs:\n            self._cancelling_flow_run_ids.add(flow_run.id)\n            self._runs_task_group.start_soon(self.cancel_run, flow_run)\n\n        return cancelling_flow_runs\n\n    async def cancel_run(self, flow_run: \"FlowRun\"):\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            configuration = await self._get_configuration(flow_run)\n        except ObjectNotFound:\n            self._logger.warning(\n                f\"Flow run {flow_run.id!r} cannot be cancelled by this worker:\"\n                f\" associated deployment {flow_run.deployment_id!r} does not exist.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure configuration information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n        else:\n            if configuration.is_using_a_runner:\n                self._logger.info(\n                    f\"Skipping cancellation because flow run {str(flow_run.id)!r} is\"\n                    \" using enhanced cancellation. A dedicated runner will handle\"\n                    \" cancellation.\"\n                )\n                return\n\n        if not flow_run.infrastructure_pid:\n            run_logger.error(\n                f\"Flow run '{flow_run.id}' does not have an infrastructure pid\"\n                \" attached. Cancellation cannot be guaranteed.\"\n            )\n            await self._mark_flow_run_as_cancelled(\n                flow_run,\n                state_updates={\n                    \"message\": (\n                        \"This flow run is missing infrastructure tracking information\"\n                        \" and cancellation cannot be guaranteed.\"\n                    )\n                },\n            )\n            return\n\n        try:\n            await self.kill_infrastructure(\n                infrastructure_pid=flow_run.infrastructure_pid,\n                configuration=configuration,\n            )\n        except NotImplementedError:\n            self._logger.error(\n                f\"Worker type {self.type!r} does not support killing created \"\n                \"infrastructure. Cancellation cannot be guaranteed.\"\n            )\n        except InfrastructureNotFound as exc:\n            self._logger.warning(f\"{exc} Marking flow run as cancelled.\")\n            await self._mark_flow_run_as_cancelled(flow_run)\n        except InfrastructureNotAvailable as exc:\n            self._logger.warning(f\"{exc} Flow run cannot be cancelled by this worker.\")\n        except Exception:\n            run_logger.exception(\n                \"Encountered exception while killing infrastructure for flow run \"\n                f\"'{flow_run.id}'. Flow run may not be cancelled.\"\n            )\n            # We will try again on generic exceptions\n            self._cancelling_flow_run_ids.remove(flow_run.id)\n            return\n        else:\n            self._emit_flow_run_cancelled_event(\n                flow_run=flow_run, configuration=configuration\n            )\n            await self._mark_flow_run_as_cancelled(flow_run)\n            run_logger.info(f\"Cancelled flow run '{flow_run.id}'!\")\n\n    async def _update_local_work_pool_info(self):\n        try:\n            work_pool = await self._client.read_work_pool(\n                work_pool_name=self._work_pool_name\n            )\n        except ObjectNotFound:\n            if self._create_pool_if_not_found:\n                wp = WorkPoolCreate(\n                    name=self._work_pool_name,\n                    type=self.type,\n                )\n                if self._base_job_template is not None:\n                    wp.base_job_template = self._base_job_template\n\n                work_pool = await self._client.create_work_pool(work_pool=wp)\n                self._logger.info(f\"Work pool {self._work_pool_name!r} created.\")\n            else:\n                self._logger.warning(f\"Work pool {self._work_pool_name!r} not found!\")\n                if self._base_job_template is not None:\n                    self._logger.warning(\n                        \"Ignoring supplied base job template because the work pool\"\n                        \" already exists\"\n                    )\n                return\n\n        # if the remote config type changes (or if it's being loaded for the\n        # first time), check if it matches the local type and warn if not\n        if getattr(self._work_pool, \"type\", 0) != work_pool.type:\n            if work_pool.type != self.__class__.type:\n                self._logger.warning(\n                    \"Worker type mismatch! This worker process expects type \"\n                    f\"{self.type!r} but received {work_pool.type!r}\"\n                    \" from the server. Unexpected behavior may occur.\"\n                )\n\n        # once the work pool is loaded, verify that it has a `base_job_template` and\n        # set it if not\n        if not work_pool.base_job_template:\n            job_template = self.__class__.get_default_base_job_template()\n            await self._set_work_pool_template(work_pool, job_template)\n            work_pool.base_job_template = job_template\n\n        self._work_pool = work_pool\n\n    async def _send_worker_heartbeat(self):\n        if self._work_pool:\n            await self._client.send_worker_heartbeat(\n                work_pool_name=self._work_pool_name,\n                worker_name=self.name,\n                heartbeat_interval_seconds=self.heartbeat_interval_seconds,\n            )\n\n    async def sync_with_backend(self):\n        \"\"\"\n        Updates the worker's local information about it's current work pool and\n        queues. Sends a worker heartbeat to the API.\n        \"\"\"\n        await self._update_local_work_pool_info()\n\n        await self._send_worker_heartbeat()\n\n        self._logger.debug(\"Worker synchronized with the Prefect API server.\")\n\n    async def _get_scheduled_flow_runs(\n        self,\n    ) -&gt; List[\"WorkerFlowRunResponse\"]:\n        \"\"\"\n        Retrieve scheduled flow runs from the work pool's queues.\n        \"\"\"\n        scheduled_before = pendulum.now(\"utc\").add(seconds=int(self._prefetch_seconds))\n        self._logger.debug(\n            f\"Querying for flow runs scheduled before {scheduled_before}\"\n        )\n        try:\n            scheduled_flow_runs = (\n                await self._client.get_scheduled_flow_runs_for_work_pool(\n                    work_pool_name=self._work_pool_name,\n                    scheduled_before=scheduled_before,\n                    work_queue_names=list(self._work_queues),\n                )\n            )\n            self._logger.debug(\n                f\"Discovered {len(scheduled_flow_runs)} scheduled_flow_runs\"\n            )\n            return scheduled_flow_runs\n        except ObjectNotFound:\n            # the pool doesn't exist; it will be created on the next\n            # heartbeat (or an appropriate warning will be logged)\n            return []\n\n    async def _submit_scheduled_flow_runs(\n        self, flow_run_response: List[\"WorkerFlowRunResponse\"]\n    ) -&gt; List[\"FlowRun\"]:\n        \"\"\"\n        Takes a list of WorkerFlowRunResponses and submits the referenced flow runs\n        for execution by the worker.\n        \"\"\"\n        submittable_flow_runs = [entry.flow_run for entry in flow_run_response]\n        submittable_flow_runs.sort(key=lambda run: run.next_scheduled_start_time)\n        for flow_run in submittable_flow_runs:\n            if flow_run.id in self._submitting_flow_run_ids:\n                continue\n\n            try:\n                if self._limiter:\n                    self._limiter.acquire_on_behalf_of_nowait(flow_run.id)\n            except anyio.WouldBlock:\n                self._logger.info(\n                    f\"Flow run limit reached; {self._limiter.borrowed_tokens} flow runs\"\n                    \" in progress.\"\n                )\n                break\n            else:\n                run_logger = self.get_flow_run_logger(flow_run)\n                run_logger.info(\n                    f\"Worker '{self.name}' submitting flow run '{flow_run.id}'\"\n                )\n                self._submitting_flow_run_ids.add(flow_run.id)\n                self._runs_task_group.start_soon(\n                    self._submit_run,\n                    flow_run,\n                )\n\n        return list(\n            filter(\n                lambda run: run.id in self._submitting_flow_run_ids,\n                submittable_flow_runs,\n            )\n        )\n\n    async def _check_flow_run(self, flow_run: \"FlowRun\") -&gt; None:\n        \"\"\"\n        Performs a check on a submitted flow run to warn the user if the flow run\n        was created from a deployment with a storage block.\n        \"\"\"\n        if flow_run.deployment_id:\n            assert (\n                self._client and self._client._started\n            ), \"Client must be started to check flow run deployment.\"\n            deployment = await self._client.read_deployment(flow_run.deployment_id)\n            if deployment.storage_document_id:\n                raise ValueError(\n                    f\"Flow run {flow_run.id!r} was created from deployment\"\n                    f\" {deployment.name!r} which is configured with a storage block.\"\n                    \" Please use an agent to execute this flow run.\"\n                )\n\n            #\n\n    async def _submit_run(self, flow_run: \"FlowRun\") -&gt; None:\n        \"\"\"\n        Submits a given flow run for execution by the worker.\n        \"\"\"\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            await self._check_flow_run(flow_run)\n        except (ValueError, ObjectNotFound):\n            self._logger.exception(\n                (\n                    \"Flow run %s did not pass checks and will not be submitted for\"\n                    \" execution\"\n                ),\n                flow_run.id,\n            )\n            self._submitting_flow_run_ids.remove(flow_run.id)\n            return\n\n        ready_to_submit = await self._propose_pending_state(flow_run)\n\n        if ready_to_submit:\n            readiness_result = await self._runs_task_group.start(\n                self._submit_run_and_capture_errors, flow_run\n            )\n\n            if readiness_result and not isinstance(readiness_result, Exception):\n                try:\n                    await self._client.update_flow_run(\n                        flow_run_id=flow_run.id,\n                        infrastructure_pid=str(readiness_result),\n                    )\n                except Exception:\n                    run_logger.exception(\n                        \"An error occurred while setting the `infrastructure_pid` on \"\n                        f\"flow run {flow_run.id!r}. The flow run will \"\n                        \"not be cancellable.\"\n                    )\n\n            run_logger.info(f\"Completed submission of flow run '{flow_run.id}'\")\n\n        else:\n            # If the run is not ready to submit, release the concurrency slot\n            if self._limiter:\n                self._limiter.release_on_behalf_of(flow_run.id)\n\n        self._submitting_flow_run_ids.remove(flow_run.id)\n\n    async def _submit_run_and_capture_errors(\n        self, flow_run: \"FlowRun\", task_status: Optional[anyio.abc.TaskStatus] = None\n    ) -&gt; Union[BaseWorkerResult, Exception]:\n        run_logger = self.get_flow_run_logger(flow_run)\n\n        try:\n            configuration = await self._get_configuration(flow_run)\n            submitted_event = self._emit_flow_run_submitted_event(configuration)\n            result = await self.run(\n                flow_run=flow_run,\n                task_status=task_status,\n                configuration=configuration,\n            )\n        except Exception as exc:\n            if not task_status._future.done():\n                # This flow run was being submitted and did not start successfully\n                run_logger.exception(\n                    f\"Failed to submit flow run '{flow_run.id}' to infrastructure.\"\n                )\n                # Mark the task as started to prevent agent crash\n                task_status.started(exc)\n                await self._propose_crashed_state(\n                    flow_run, \"Flow run could not be submitted to infrastructure\"\n                )\n            else:\n                run_logger.exception(\n                    f\"An error occurred while monitoring flow run '{flow_run.id}'. \"\n                    \"The flow run will not be marked as failed, but an issue may have \"\n                    \"occurred.\"\n                )\n            return exc\n        finally:\n            if self._limiter:\n                self._limiter.release_on_behalf_of(flow_run.id)\n\n        if not task_status._future.done():\n            run_logger.error(\n                f\"Infrastructure returned without reporting flow run '{flow_run.id}' \"\n                \"as started or raising an error. This behavior is not expected and \"\n                \"generally indicates improper implementation of infrastructure. The \"\n                \"flow run will not be marked as failed, but an issue may have occurred.\"\n            )\n            # Mark the task as started to prevent agent crash\n            task_status.started()\n\n        if result.status_code != 0:\n            await self._propose_crashed_state(\n                flow_run,\n                (\n                    \"Flow run infrastructure exited with non-zero status code\"\n                    f\" {result.status_code}.\"\n                ),\n            )\n\n        self._emit_flow_run_executed_event(result, configuration, submitted_event)\n\n        return result\n\n    def get_status(self):\n        \"\"\"\n        Retrieves the status of the current worker including its name, current worker\n        pool, the work pool queues it is polling, and its local settings.\n        \"\"\"\n        return {\n            \"name\": self.name,\n            \"work_pool\": (\n                self._work_pool.dict(json_compatible=True)\n                if self._work_pool is not None\n                else None\n            ),\n            \"settings\": {\n                \"prefetch_seconds\": self._prefetch_seconds,\n            },\n        }\n\n    async def _get_configuration(\n        self,\n        flow_run: \"FlowRun\",\n    ) -&gt; BaseJobConfiguration:\n        deployment = await self._client.read_deployment(flow_run.deployment_id)\n        flow = await self._client.read_flow(flow_run.flow_id)\n\n        deployment_vars = deployment.job_variables or {}\n        flow_run_vars = flow_run.job_variables or {}\n        job_variables = {**deployment_vars}\n\n        # merge environment variables carefully, otherwise full override\n        if isinstance(job_variables.get(\"env\"), dict):\n            job_variables[\"env\"].update(flow_run_vars.pop(\"env\", {}))\n        job_variables.update(flow_run_vars)\n\n        configuration = await self.job_configuration.from_template_and_values(\n            base_job_template=self._work_pool.base_job_template,\n            values=job_variables,\n            client=self._client,\n        )\n        configuration.prepare_for_flow_run(\n            flow_run=flow_run, deployment=deployment, flow=flow\n        )\n        return configuration\n\n    async def _propose_pending_state(self, flow_run: \"FlowRun\") -&gt; bool:\n        run_logger = self.get_flow_run_logger(flow_run)\n        state = flow_run.state\n        try:\n            state = await propose_state(\n                self._client, Pending(), flow_run_id=flow_run.id\n            )\n        except Abort as exc:\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}'. \"\n                    f\"Server sent an abort signal: {exc}\"\n                ),\n            )\n            return False\n        except Exception:\n            run_logger.exception(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n            )\n            return False\n\n        if not state.is_pending():\n            run_logger.info(\n                (\n                    f\"Aborted submission of flow run '{flow_run.id}': \"\n                    f\"Server returned a non-pending state {state.type.value!r}\"\n                ),\n            )\n            return False\n\n        return True\n\n    async def _propose_failed_state(self, flow_run: \"FlowRun\", exc: Exception) -&gt; None:\n        run_logger = self.get_flow_run_logger(flow_run)\n        try:\n            await propose_state(\n                self._client,\n                await exception_to_failed_state(message=\"Submission failed.\", exc=exc),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # We've already failed, no need to note the abort but we don't want it to\n            # raise in the agent process\n            pass\n        except Exception:\n            run_logger.error(\n                f\"Failed to update state of flow run '{flow_run.id}'\",\n                exc_info=True,\n            )\n\n    async def _propose_crashed_state(self, flow_run: \"FlowRun\", message: str) -&gt; None:\n        run_logger = self.get_flow_run_logger(flow_run)\n        try:\n            state = await propose_state(\n                self._client,\n                Crashed(message=message),\n                flow_run_id=flow_run.id,\n            )\n        except Abort:\n            # Flow run already marked as failed\n            pass\n        except Exception:\n            run_logger.exception(f\"Failed to update state of flow run '{flow_run.id}'\")\n        else:\n            if state.is_crashed():\n                run_logger.info(\n                    f\"Reported flow run '{flow_run.id}' as crashed: {message}\"\n                )\n\n    async def _mark_flow_run_as_cancelled(\n        self, flow_run: \"FlowRun\", state_updates: Optional[dict] = None\n    ) -&gt; None:\n        state_updates = state_updates or {}\n        state_updates.setdefault(\"name\", \"Cancelled\")\n        state_updates.setdefault(\"type\", StateType.CANCELLED)\n        state = flow_run.state.copy(update=state_updates)\n\n        await self._client.set_flow_run_state(flow_run.id, state, force=True)\n\n        # Do not remove the flow run from the cancelling set immediately because\n        # the API caches responses for the `read_flow_runs` and we do not want to\n        # duplicate cancellations.\n        await self._schedule_task(\n            60 * 10, self._cancelling_flow_run_ids.remove, flow_run.id\n        )\n\n    async def _set_work_pool_template(self, work_pool, job_template):\n        \"\"\"Updates the `base_job_template` for the worker's work pool server side.\"\"\"\n        await self._client.update_work_pool(\n            work_pool_name=work_pool.name,\n            work_pool=WorkPoolUpdate(\n                base_job_template=job_template,\n            ),\n        )\n\n    async def _schedule_task(self, __in_seconds: int, fn, *args, **kwargs):\n        \"\"\"\n        Schedule a background task to start after some time.\n\n        These tasks will be run immediately when the worker exits instead of waiting.\n\n        The function may be async or sync. Async functions will be awaited.\n        \"\"\"\n\n        async def wrapper(task_status):\n            # If we are shutting down, do not sleep; otherwise sleep until the scheduled\n            # time or shutdown\n            if self.is_setup:\n                with anyio.CancelScope() as scope:\n                    self._scheduled_task_scopes.add(scope)\n                    task_status.started()\n                    await anyio.sleep(__in_seconds)\n\n                self._scheduled_task_scopes.remove(scope)\n            else:\n                task_status.started()\n\n            result = fn(*args, **kwargs)\n            if inspect.iscoroutine(result):\n                await result\n\n        await self._runs_task_group.start(wrapper)\n\n    async def __aenter__(self):\n        self._logger.debug(\"Entering worker context...\")\n        await self.setup()\n        return self\n\n    async def __aexit__(self, *exc_info):\n        self._logger.debug(\"Exiting worker context...\")\n        await self.teardown(*exc_info)\n\n    def __repr__(self):\n        return f\"Worker(pool={self._work_pool_name!r}, name={self.name!r})\"\n\n    def _event_resource(self):\n        return {\n            \"prefect.resource.id\": f\"prefect.worker.{self.type}.{self.get_name_slug()}\",\n            \"prefect.resource.name\": self.name,\n            \"prefect.version\": prefect.__version__,\n            \"prefect.worker-type\": self.type,\n        }\n\n    def _event_related_resources(\n        self,\n        configuration: Optional[BaseJobConfiguration] = None,\n        include_self: bool = False,\n    ) -&gt; List[RelatedResource]:\n        related = []\n        if configuration:\n            related += configuration._related_resources()\n\n        if self._work_pool:\n            related.append(\n                object_as_related_resource(\n                    kind=\"work-pool\", role=\"work-pool\", object=self._work_pool\n                )\n            )\n\n        if include_self:\n            worker_resource = self._event_resource()\n            worker_resource[\"prefect.resource.role\"] = \"worker\"\n            related.append(RelatedResource.parse_obj(worker_resource))\n\n        return related\n\n    def _emit_flow_run_submitted_event(\n        self, configuration: BaseJobConfiguration\n    ) -&gt; Event:\n        return emit_event(\n            event=\"prefect.worker.submitted-flow-run\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(configuration=configuration),\n        )\n\n    def _emit_flow_run_executed_event(\n        self,\n        result: BaseWorkerResult,\n        configuration: BaseJobConfiguration,\n        submitted_event: Event,\n    ):\n        related = self._event_related_resources(configuration=configuration)\n\n        for resource in related:\n            if resource.role == \"flow-run\":\n                resource[\"prefect.infrastructure.identifier\"] = str(result.identifier)\n                resource[\"prefect.infrastructure.status-code\"] = str(result.status_code)\n\n        emit_event(\n            event=\"prefect.worker.executed-flow-run\",\n            resource=self._event_resource(),\n            related=related,\n            follows=submitted_event,\n        )\n\n    async def _emit_worker_started_event(self) -&gt; Event:\n        return emit_event(\n            \"prefect.worker.started\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(),\n        )\n\n    async def _emit_worker_stopped_event(self, started_event: Event):\n        emit_event(\n            \"prefect.worker.stopped\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(),\n            follows=started_event,\n        )\n\n    def _emit_flow_run_cancelled_event(\n        self, flow_run: \"FlowRun\", configuration: BaseJobConfiguration\n    ):\n        related = self._event_related_resources(configuration=configuration)\n\n        for resource in related:\n            if resource.role == \"flow-run\":\n                resource[\"prefect.infrastructure.identifier\"] = str(\n                    flow_run.infrastructure_pid\n                )\n\n        emit_event(\n            event=\"prefect.worker.cancelled-flow-run\",\n            resource=self._event_resource(),\n            related=related,\n        )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_all_available_worker_types","title":"<code>get_all_available_worker_types</code>  <code>staticmethod</code>","text":"<p>Returns all worker types available in the local registry.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@staticmethod\ndef get_all_available_worker_types() -&gt; List[str]:\n    \"\"\"\n    Returns all worker types available in the local registry.\n    \"\"\"\n    load_prefect_collections()\n    worker_registry = get_registry_for_type(BaseWorker)\n    if worker_registry is not None:\n        return list(worker_registry.keys())\n    return []\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_status","title":"<code>get_status</code>","text":"<p>Retrieves the status of the current worker including its name, current worker pool, the work pool queues it is polling, and its local settings.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>def get_status(self):\n    \"\"\"\n    Retrieves the status of the current worker including its name, current worker\n    pool, the work pool queues it is polling, and its local settings.\n    \"\"\"\n    return {\n        \"name\": self.name,\n        \"work_pool\": (\n            self._work_pool.dict(json_compatible=True)\n            if self._work_pool is not None\n            else None\n        ),\n        \"settings\": {\n            \"prefetch_seconds\": self._prefetch_seconds,\n        },\n    }\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.get_worker_class_from_type","title":"<code>get_worker_class_from_type</code>  <code>staticmethod</code>","text":"<p>Returns the worker class for a given worker type. If the worker type is not recognized, returns None.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@staticmethod\ndef get_worker_class_from_type(type: str) -&gt; Optional[Type[\"BaseWorker\"]]:\n    \"\"\"\n    Returns the worker class for a given worker type. If the worker type\n    is not recognized, returns None.\n    \"\"\"\n    load_prefect_collections()\n    worker_registry = get_registry_for_type(BaseWorker)\n    if worker_registry is not None:\n        return worker_registry.get(type)\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.is_worker_still_polling","title":"<code>is_worker_still_polling</code>","text":"<p>This method is invoked by a webserver healthcheck handler and returns a boolean indicating if the worker has recorded a scheduled flow run poll within a variable amount of time.</p> <p>The <code>query_interval_seconds</code> is the same value that is used by the loop services - we will evaluate if the _last_polled_time was within that interval x 30 (so 10s -&gt; 5m)</p> <p>The instance property <code>self._last_polled_time</code> is currently set/updated in <code>get_and_submit_flow_runs()</code></p> Source code in <code>prefect/workers/base.py</code> <pre><code>def is_worker_still_polling(self, query_interval_seconds: int) -&gt; bool:\n    \"\"\"\n    This method is invoked by a webserver healthcheck handler\n    and returns a boolean indicating if the worker has recorded a\n    scheduled flow run poll within a variable amount of time.\n\n    The `query_interval_seconds` is the same value that is used by\n    the loop services - we will evaluate if the _last_polled_time\n    was within that interval x 30 (so 10s -&gt; 5m)\n\n    The instance property `self._last_polled_time`\n    is currently set/updated in `get_and_submit_flow_runs()`\n    \"\"\"\n    threshold_seconds = query_interval_seconds * 30\n\n    seconds_since_last_poll = (\n        pendulum.now(\"utc\") - self._last_polled_time\n    ).in_seconds()\n\n    is_still_polling = seconds_since_last_poll &lt;= threshold_seconds\n\n    if not is_still_polling:\n        self._logger.error(\n            f\"Worker has not polled in the last {seconds_since_last_poll} seconds \"\n            \"and should be restarted\"\n        )\n\n    return is_still_polling\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Method for killing infrastructure created by a worker. Should be implemented by individual workers if they support killing infrastructure.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: BaseJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Method for killing infrastructure created by a worker. Should be implemented by\n    individual workers if they support killing infrastructure.\n    \"\"\"\n    raise NotImplementedError(\n        \"This worker does not support killing infrastructure.\"\n    )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.run","title":"<code>run</code>  <code>abstractmethod</code> <code>async</code>","text":"<p>Runs a given flow run on the current worker.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>@abc.abstractmethod\nasync def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: BaseJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; BaseWorkerResult:\n    \"\"\"\n    Runs a given flow run on the current worker.\n    \"\"\"\n    raise NotImplementedError(\n        \"Workers must implement a method for running submitted flow runs\"\n    )\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.setup","title":"<code>setup</code>  <code>async</code>","text":"<p>Prepares the worker to run.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def setup(self):\n    \"\"\"Prepares the worker to run.\"\"\"\n    self._logger.debug(\"Setting up worker...\")\n    self._runs_task_group = anyio.create_task_group()\n    self._limiter = (\n        anyio.CapacityLimiter(self._limit) if self._limit is not None else None\n    )\n    self._client = get_client()\n    await self._client.__aenter__()\n    await self._runs_task_group.__aenter__()\n\n    self.is_setup = True\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.sync_with_backend","title":"<code>sync_with_backend</code>  <code>async</code>","text":"<p>Updates the worker's local information about it's current work pool and queues. Sends a worker heartbeat to the API.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def sync_with_backend(self):\n    \"\"\"\n    Updates the worker's local information about it's current work pool and\n    queues. Sends a worker heartbeat to the API.\n    \"\"\"\n    await self._update_local_work_pool_info()\n\n    await self._send_worker_heartbeat()\n\n    self._logger.debug(\"Worker synchronized with the Prefect API server.\")\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/base/#prefect.workers.base.BaseWorker.teardown","title":"<code>teardown</code>  <code>async</code>","text":"<p>Cleans up resources after the worker is stopped.</p> Source code in <code>prefect/workers/base.py</code> <pre><code>async def teardown(self, *exc_info):\n    \"\"\"Cleans up resources after the worker is stopped.\"\"\"\n    self._logger.debug(\"Tearing down worker...\")\n    self.is_setup = False\n    for scope in self._scheduled_task_scopes:\n        scope.cancel()\n    if self._runs_task_group:\n        await self._runs_task_group.__aexit__(*exc_info)\n    if self._client:\n        await self._client.__aexit__(*exc_info)\n    self._runs_task_group = None\n    self._client = None\n</code></pre>","tags":["Python API","workers"]},{"location":"api-ref/prefect/workers/block/","title":"block","text":"","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block","title":"<code>prefect.workers.block</code>","text":"","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration","title":"<code>BlockWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseModel</code></p> Source code in <code>prefect/workers/block.py</code> <pre><code>@deprecated_class(\n    start_date=\"Jun 2024\",\n    help=\"Refer to the upgrade guide for more information: https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/\",\n)\nclass BlockWorkerJobConfiguration(BaseModel):\n    block: Block = Field(\n        default=..., description=\"The infrastructure block to use for job creation.\"\n    )\n\n    @validator(\"block\")\n    def _validate_infrastructure_block(cls, v):\n        return validate_block_is_infrastructure(v)\n\n    _related_objects: Dict[str, Any] = PrivateAttr(default_factory=dict)\n\n    @property\n    def is_using_a_runner(self):\n        return (\n            self.block.command is not None\n            and \"prefect flow-run execute\" in shlex.join(self.block.command)\n        )\n\n    @staticmethod\n    def _get_base_config_defaults(variables: dict) -&gt; dict:\n        \"\"\"Get default values from base config for all variables that have them.\"\"\"\n        defaults = dict()\n        for variable_name, attrs in variables.items():\n            if \"default\" in attrs:\n                defaults[variable_name] = attrs[\"default\"]\n\n        return defaults\n\n    @classmethod\n    @inject_client\n    async def from_template_and_values(\n        cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n    ):\n        \"\"\"Creates a valid worker configuration object from the provided base\n        configuration and overrides.\n\n        Important: this method expects that the base_job_template was already\n        validated server-side.\n        \"\"\"\n        job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n        variables_schema = base_job_template[\"variables\"]\n        variables = cls._get_base_config_defaults(\n            variables_schema.get(\"properties\", {})\n        )\n        variables.update(values)\n\n        populated_configuration = apply_values(template=job_config, values=variables)\n\n        block_document_id = get_from_dict(\n            populated_configuration, \"block.$ref.block_document_id\"\n        )\n        if not block_document_id:\n            raise ValueError(\n                \"Base job template is invalid for this worker type because it does not\"\n                \" contain a block_document_id after variable resolution.\"\n            )\n\n        block_document = await client.read_block_document(\n            block_document_id=block_document_id\n        )\n        infrastructure_block = Block._from_block_document(block_document)\n\n        populated_configuration[\"block\"] = infrastructure_block\n\n        return cls(**populated_configuration)\n\n    @classmethod\n    def json_template(cls) -&gt; dict:\n        \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n        Defaults to using the job configuration parameter name as the template variable name.\n\n        e.g.\n        {\n            key1: '{{ key1 }}',     # default variable template\n            key2: '{{ template2 }}', # `template2` specifically provide as template\n        }\n        \"\"\"\n        configuration = {}\n        properties = cls.schema()[\"properties\"]\n        for k, v in properties.items():\n            if v.get(\"template\"):\n                template = v[\"template\"]\n            else:\n                template = \"{{ \" + k + \" }}\"\n            configuration[k] = template\n\n        return configuration\n\n    def _related_resources(self) -&gt; List[RelatedResource]:\n        tags = set()\n        related = []\n\n        for kind, obj in self._related_objects.items():\n            if obj is None:\n                continue\n            if hasattr(obj, \"tags\"):\n                tags.update(obj.tags)\n            related.append(object_as_related_resource(kind=kind, role=kind, object=obj))\n\n        return related + tags_as_related_resources(tags)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        self.block = self.block.prepare_for_flow_run(\n            flow_run=flow_run, deployment=deployment, flow=flow\n        )\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration.from_template_and_values","title":"<code>from_template_and_values</code>  <code>async</code> <code>classmethod</code>","text":"<p>Creates a valid worker configuration object from the provided base configuration and overrides.</p> <p>Important: this method expects that the base_job_template was already validated server-side.</p> Source code in <code>prefect/workers/block.py</code> <pre><code>@classmethod\n@inject_client\nasync def from_template_and_values(\n    cls, base_job_template: dict, values: dict, client: \"PrefectClient\" = None\n):\n    \"\"\"Creates a valid worker configuration object from the provided base\n    configuration and overrides.\n\n    Important: this method expects that the base_job_template was already\n    validated server-side.\n    \"\"\"\n    job_config: Dict[str, Any] = base_job_template[\"job_configuration\"]\n    variables_schema = base_job_template[\"variables\"]\n    variables = cls._get_base_config_defaults(\n        variables_schema.get(\"properties\", {})\n    )\n    variables.update(values)\n\n    populated_configuration = apply_values(template=job_config, values=variables)\n\n    block_document_id = get_from_dict(\n        populated_configuration, \"block.$ref.block_document_id\"\n    )\n    if not block_document_id:\n        raise ValueError(\n            \"Base job template is invalid for this worker type because it does not\"\n            \" contain a block_document_id after variable resolution.\"\n        )\n\n    block_document = await client.read_block_document(\n        block_document_id=block_document_id\n    )\n    infrastructure_block = Block._from_block_document(block_document)\n\n    populated_configuration[\"block\"] = infrastructure_block\n\n    return cls(**populated_configuration)\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerJobConfiguration.json_template","title":"<code>json_template</code>  <code>classmethod</code>","text":"<p>Returns a dict with job configuration as keys and the corresponding templates as values</p> <p>Defaults to using the job configuration parameter name as the template variable name.</p> <p>e.g. {     key1: '{{ key1 }}',     # default variable template     key2: '{{ template2 }}', # <code>template2</code> specifically provide as template }</p> Source code in <code>prefect/workers/block.py</code> <pre><code>@classmethod\ndef json_template(cls) -&gt; dict:\n    \"\"\"Returns a dict with job configuration as keys and the corresponding templates as values\n\n    Defaults to using the job configuration parameter name as the template variable name.\n\n    e.g.\n    {\n        key1: '{{ key1 }}',     # default variable template\n        key2: '{{ template2 }}', # `template2` specifically provide as template\n    }\n    \"\"\"\n    configuration = {}\n    properties = cls.schema()[\"properties\"]\n    for k, v in properties.items():\n        if v.get(\"template\"):\n            template = v[\"template\"]\n        else:\n            template = \"{{ \" + k + \" }}\"\n        configuration[k] = template\n\n    return configuration\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/block/#prefect.workers.block.BlockWorkerResult","title":"<code>BlockWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Result of a block worker job</p> Source code in <code>prefect/workers/block.py</code> <pre><code>class BlockWorkerResult(BaseWorkerResult):\n    \"\"\"Result of a block worker job\"\"\"\n</code></pre>","tags":["Python API","workers","block"]},{"location":"api-ref/prefect/workers/process/","title":"process","text":"","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process","title":"<code>prefect.workers.process</code>","text":"<p>Module containing the Process worker used for executing flow runs as subprocesses.</p> <p>To start a Process worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type process\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process.ProcessJobConfiguration","title":"<code>ProcessJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> Source code in <code>prefect/workers/process.py</code> <pre><code>class ProcessJobConfiguration(BaseJobConfiguration):\n    stream_output: bool = Field(default=True)\n    working_dir: Optional[Path] = Field(default=None)\n\n    @validator(\"working_dir\")\n    def validate_command(cls, v):\n        return validate_command(v)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self.env = {**os.environ, **self.env}\n        self.command = (\n            f\"{get_sys_executable()} -m prefect.engine\"\n            if self.command == self._base_flow_run_command()\n            else self.command\n        )\n\n    def _base_flow_run_command(self) -&gt; str:\n        \"\"\"\n        Override the base flow run command because enhanced cancellation doesn't\n        work with the process worker.\n        \"\"\"\n        return \"python -m prefect.engine\"\n</code></pre>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/process/#prefect.workers.process.ProcessWorkerResult","title":"<code>ProcessWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect/workers/process.py</code> <pre><code>class ProcessWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>","tags":["Python API","workers","process"]},{"location":"api-ref/prefect/workers/server/","title":"server","text":"","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/server/#prefect.workers.server","title":"<code>prefect.workers.server</code>","text":"","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/server/#prefect.workers.server.start_healthcheck_server","title":"<code>start_healthcheck_server</code>","text":"<p>Run a healthcheck FastAPI server for a worker.</p> <p>Parameters:</p> Name Type Description Default <code>worker</code> <code>BaseWorker | ProcessWorker</code> <p>the worker whose health we will check</p> required <code>log_level</code> <code>str</code> <p>the log level to use for the server</p> <code>'error'</code> Source code in <code>prefect/workers/server.py</code> <pre><code>def start_healthcheck_server(\n    worker: Union[BaseWorker, ProcessWorker],\n    query_interval_seconds: int,\n    log_level: str = \"error\",\n) -&gt; None:\n    \"\"\"\n    Run a healthcheck FastAPI server for a worker.\n\n    Args:\n        worker (BaseWorker | ProcessWorker): the worker whose health we will check\n        log_level (str): the log level to use for the server\n    \"\"\"\n    webserver = FastAPI()\n    router = APIRouter()\n\n    def perform_health_check():\n        did_recently_poll = worker.is_worker_still_polling(\n            query_interval_seconds=query_interval_seconds\n        )\n\n        if not did_recently_poll:\n            return JSONResponse(\n                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n                content={\"message\": \"Worker may be unresponsive at this time\"},\n            )\n        return JSONResponse(status_code=status.HTTP_200_OK, content={\"message\": \"OK\"})\n\n    router.add_api_route(\"/health\", perform_health_check, methods=[\"GET\"])\n\n    webserver.include_router(router)\n\n    uvicorn.run(\n        webserver,\n        host=PREFECT_WORKER_WEBSERVER_HOST.value(),\n        port=PREFECT_WORKER_WEBSERVER_PORT.value(),\n        log_level=log_level,\n    )\n</code></pre>","tags":["Python API","workers","server"]},{"location":"api-ref/prefect/workers/utilities/","title":"utilities","text":"","tags":["Python API","workers","utilities"]},{"location":"api-ref/prefect/workers/utilities/#prefect.workers.utilities","title":"<code>prefect.workers.utilities</code>","text":"","tags":["Python API","workers","utilities"]},{"location":"api-ref/python/","title":"Python SDK","text":"<p>The Prefect Python SDK is used to build, test, and execute workflows against the Prefect API.</p> <p>Explore the modules in the navigation bar to the left to learn more.</p>","tags":["API","Python SDK"]},{"location":"api-ref/rest-api/","title":"REST API","text":"<p>The Prefect REST API is used for communicating data from clients to a Prefect server so that orchestration can be performed. This API is consumed by clients such as the Prefect Python SDK or the server dashboard.</p> <p>Prefect Cloud and a locally hosted Prefect server each provide a REST API.</p> <ul> <li>Prefect Cloud:<ul> <li>Interactive Prefect Cloud REST API documentation</li> <li>Finding your Prefect Cloud details</li> </ul> </li> <li>A Locally hosted open-source Prefect server:<ul> <li>Interactive REST API documentation for a locally hosted open-source Prefect server is available at <code>http://localhost:4200/docs</code> or the <code>/docs</code> endpoint of the PREFECT_API_URL you have configured to access the server. You must have the server running with <code>prefect server start</code> to access the interactive documentation.</li> <li>Prefect REST API documentation</li> </ul> </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#interacting-with-the-rest-api","title":"Interacting with the REST API","text":"<p>You have many options to interact with the Prefect REST API:</p> <ul> <li>Create an instance of <code>PrefectClient</code> </li> <li>Use your favorite Python HTTP library such as Requests or HTTPX</li> <li>Use an HTTP library in your language of choice</li> <li>Use curl from the command line </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#prefectclient-with-a-prefect-server","title":"PrefectClient with a Prefect server","text":"<p>This example uses <code>PrefectClient</code> with a locally hosted Prefect server:</p> <pre><code>import asyncio\nfrom prefect.client import get_client\n\nasync def get_flows():\n    client = get_client()\n    r = await client.read_flows(limit=5)\n    return r\n\nr = asyncio.run(get_flows())\n\nfor flow in r:\n    print(flow.name, flow.id)\n\nif __name__ == \"__main__\":\n    asyncio.run(get_flows())\n</code></pre> <p>Output:</p> <pre><code>cat-facts 58ed68b1-0201-4f37-adef-0ea24bd2a022\ndog-facts e7c0403d-44e7-45cf-a6c8-79117b7f3766\nsloth-facts 771c0574-f5bf-4f59-a69d-3be3e061a62d\ncapybara-facts fbadaf8b-584f-48b9-b092-07d351edd424\nlemur-facts 53f710e7-3b0f-4b2f-ab6b-44934111818c\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#requests-with-prefect","title":"Requests with Prefect","text":"<p>This example uses the Requests library with Prefect Cloud to return the five newest artifacts.</p> <pre><code>import requests\n\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/abc-my-cloud-account-id-is-here/workspaces/123-my-workspace-id-is-here\"\nPREFECT_API_KEY=\"123abc_my_api_key_goes_here\"\ndata = {\n    \"sort\": \"CREATED_DESC\",\n    \"limit\": 5,\n    \"artifacts\": {\n        \"key\": {\n            \"exists_\": True\n        }\n    }\n}\n\nheaders = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\nendpoint = f\"{PREFECT_API_URL}/artifacts/filter\"\n\nresponse = requests.post(endpoint, headers=headers, json=data)\nassert response.status_code == 200\nfor artifact in response.json():\n    print(artifact)\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#curl-with-prefect-cloud","title":"curl with Prefect Cloud","text":"<p>This example uses curl with Prefect Cloud to create a flow run:</p> <pre><code>ACCOUNT_ID=\"abc-my-cloud-account-id-goes-here\"\nWORKSPACE_ID=\"123-my-workspace-id-goes-here\"\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/$ACCOUNT_ID/workspaces/$WORKSPACE_ID\"\nPREFECT_API_KEY=\"123abc_my_api_key_goes_here\"\nDEPLOYMENT_ID=\"my_deployment_id\"\n\ncurl --location --request POST \"$PREFECT_API_URL/deployments/$DEPLOYMENT_ID/create_flow_run\" \\\n  --header \"Content-Type: application/json\" \\\n  --header \"Authorization: Bearer $PREFECT_API_KEY\" \\\n  --header \"X-PREFECT-API-VERSION: 0.8.4\" \\\n  --data-raw \"{}\"\n</code></pre> <p>Note that in this example <code>--data-raw \"{}\"</code> is required and is where you can specify other aspects of the flow run such as the state. Windows users substitute <code>^</code> for <code>\\</code> for line multi-line commands.</p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#finding-your-prefect-cloud-details","title":"Finding your Prefect Cloud details","text":"<p>When working with the Prefect Cloud REST API you will need your Account ID and often the Workspace ID for the workspace you want to interact with. You can find both IDs for a Prefect profile in the CLI with <code>prefect profile inspect my_profile</code>. This command will also display your Prefect API key, as shown below:</p> <pre><code>PREFECT_API_URL='https://api.prefect.cloud/api/accounts/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here'\nPREFECT_API_KEY='123abc_my_api_key_is_here'\n</code></pre> <p>Alternatively, view your Account ID and Workspace ID in your browser URL. For example: <code>https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here</code>. </p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#rest-guidelines","title":"REST Guidelines","text":"<p>The REST APIs adhere to the following guidelines:</p> <ul> <li>Collection names are pluralized (for example, <code>/flows</code> or <code>/runs</code>).</li> <li>We indicate variable placeholders with colons: <code>GET /flows/:id</code>.</li> <li>We use snake case for route names: <code>GET /task_runs</code>.</li> <li>We avoid nested resources unless there is no possibility of accessing the child resource outside the parent context. For example, we query <code>/task_runs</code> with a flow run filter instead of accessing <code>/flow_runs/:id/task_runs</code>.</li> <li>The API is hosted with an <code>/api/:version</code> prefix that (optionally) allows versioning in the future. By convention, we treat that as part of the base URL and do not include that in API examples.</li> <li>Filtering, sorting, and pagination parameters are provided in the request body of <code>POST</code> requests where applicable.<ul> <li>Pagination parameters are <code>limit</code> and <code>offset</code>.</li> <li>Sorting is specified with a single <code>sort</code> parameter.</li> <li>See more information on filtering below.</li> </ul> </li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#http-verbs","title":"HTTP verbs","text":"<ul> <li><code>GET</code>, <code>PUT</code> and <code>DELETE</code> requests are always idempotent. <code>POST</code> and <code>PATCH</code> are not guaranteed to be idempotent.</li> <li><code>GET</code> requests cannot receive information from the request body.</li> <li><code>POST</code> requests can receive information from the request body.</li> <li><code>POST /collection</code> creates a new member of the collection.</li> <li><code>GET /collection</code> lists all members of the collection.</li> <li><code>GET /collection/:id</code> gets a specific member of the collection by ID.</li> <li><code>DELETE /collection/:id</code> deletes a specific member of the collection.</li> <li><code>PUT /collection/:id</code> creates or replaces a specific member of the collection.</li> <li><code>PATCH /collection/:id</code> partially updates a specific member of the collection.</li> <li><code>POST /collection/action</code> is how we implement non-CRUD actions. For example, to set a flow run's state, we use <code>POST /flow_runs/:id/set_state</code>.</li> <li><code>POST /collection/action</code> may also be used for read-only queries. This is to allow us to send complex arguments as body arguments (which often cannot be done via <code>GET</code>). Examples include <code>POST /flow_runs/filter</code>, <code>POST /flow_runs/count</code>, and <code>POST /flow_runs/history</code>.</li> </ul>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#filtering","title":"Filtering","text":"<p>Objects can be filtered by providing filter criteria in the body of a <code>POST</code> request. When multiple criteria are specified, logical AND will be applied to the criteria.</p> <p>Filter criteria are structured as follows:</p> <pre><code>{\n    \"objects\": {\n        \"object_field\": {\n            \"field_operator_\": &lt;field_value&gt;\n        }\n    }\n}\n</code></pre> <p>In this example, <code>objects</code> is the name of the collection to filter over (for example, <code>flows</code>). The collection can be either the object being queried for (<code>flows</code> for <code>POST /flows/filter</code>) or a related object (<code>flow_runs</code> for <code>POST /flows/filter</code>).</p> <p><code>object_field</code> is the name of the field over which to filter (<code>name</code> for <code>flows</code>). Note that some objects may have nested object fields, such as <code>{flow_run: {state: {type: {any_: []}}}}</code>.</p> <p><code>field_operator_</code> is the operator to apply to a field when filtering. Common examples include:</p> <ul> <li><code>any_</code>: return objects where this field matches any of the following values.</li> <li><code>is_null_</code>: return objects where this field is or is not null.</li> <li><code>eq_</code>: return objects where this field is equal to the following value.</li> <li><code>all_</code>: return objects where this field matches all of the following values.</li> <li><code>before_</code>: return objects where this datetime field is less than or equal to the following value.</li> <li><code>after_</code>: return objects where this datetime field is greater than or equal to the following value.</li> </ul> <p>For example, to query for flows with the tag <code>\"database\"</code> and failed flow runs, <code>POST /flows/filter</code> with the following request body:</p> <pre><code>{\n    \"flows\": {\n        \"tags\": {\n            \"all_\": [\"database\"]\n        }\n    },\n    \"flow_runs\": {\n        \"state\": {\n            \"type\": {\n              \"any_\": [\"FAILED\"]\n            }\n        }\n    }\n}\n</code></pre>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/rest-api/#openapi","title":"OpenAPI","text":"<p>The Prefect REST API can be fully described with an OpenAPI 3.0 compliant document. OpenAPI is a standard specification for describing REST APIs.</p> <p>To generate the Prefect server's complete OpenAPI document, run the following commands in an interactive Python session:</p> <pre><code>from prefect.server.api.server import create_app\n\napp = create_app()\nopenapi_doc = app.openapi()\n</code></pre> <p>This document allows you to generate your own API client, explore the API using an API inspection tool, or write tests to ensure API compliance.</p>","tags":["REST API","Prefect Cloud","Prefect server","curl","PrefectClient","Requests","API reference"]},{"location":"api-ref/server/","title":"Server API","text":"<p>The Prefect server API is used by the server to work with workflow metadata and enforce orchestration logic. This API is primarily used by Prefect developers.</p> <p>Select links in the left navigation menu to explore.</p>","tags":["API","Server API"]},{"location":"api-ref/server/api/admin/","title":"server.api.admin","text":"","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin","title":"<code>prefect.server.api.admin</code>","text":"<p>Routes for admin-level interactions with the Prefect REST API.</p>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.clear_database","title":"<code>clear_database</code>  <code>async</code>","text":"<p>Clear all database tables without dropping them.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/clear\", status_code=status.HTTP_204_NO_CONTENT)\nasync def clear_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Clear all database tables without dropping them.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n    async with db.session_context(begin_transaction=True) as session:\n        # work pool has a circular dependency on pool queue; delete it first\n        await session.execute(db.WorkPool.__table__.delete())\n        for table in reversed(db.Base.metadata.sorted_tables):\n            await session.execute(table.delete())\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.create_database","title":"<code>create_database</code>  <code>async</code>","text":"<p>Create all database objects.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/create\", status_code=status.HTTP_204_NO_CONTENT)\nasync def create_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Create all database objects.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n\n    await db.create_db()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.drop_database","title":"<code>drop_database</code>  <code>async</code>","text":"<p>Drop all database objects.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.post(\"/database/drop\", status_code=status.HTTP_204_NO_CONTENT)\nasync def drop_database(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    confirm: bool = Body(\n        False,\n        embed=True,\n        description=\"Pass confirm=True to confirm you want to modify the database.\",\n    ),\n    response: Response = None,\n):\n    \"\"\"Drop all database objects.\"\"\"\n    if not confirm:\n        response.status_code = status.HTTP_400_BAD_REQUEST\n        return\n\n    await db.drop_db()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.read_settings","title":"<code>read_settings</code>  <code>async</code>","text":"<p>Get the current Prefect REST API settings.</p> <p>Secret setting values will be obfuscated.</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.get(\"/settings\")\nasync def read_settings() -&gt; prefect.settings.Settings:\n    \"\"\"\n    Get the current Prefect REST API settings.\n\n    Secret setting values will be obfuscated.\n    \"\"\"\n    return prefect.settings.get_current_settings().with_obfuscated_secrets()\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/admin/#prefect.server.api.admin.read_version","title":"<code>read_version</code>  <code>async</code>","text":"<p>Returns the Prefect version number</p> Source code in <code>prefect/server/api/admin.py</code> <pre><code>@router.get(\"/version\")\nasync def read_version() -&gt; str:\n    \"\"\"Returns the Prefect version number\"\"\"\n    return prefect.__version__\n</code></pre>","tags":["Prefect API","administration"]},{"location":"api-ref/server/api/csrf_token/","title":"server.api.csrf_token","text":"","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/csrf_token/#prefect.server.api.csrf_token","title":"<code>prefect.server.api.csrf_token</code>","text":"","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/csrf_token/#prefect.server.api.csrf_token.create_csrf_token","title":"<code>create_csrf_token</code>  <code>async</code>","text":"<p>Create or update a CSRF token for a client</p> Source code in <code>prefect/server/api/csrf_token.py</code> <pre><code>@router.get(\"\")\nasync def create_csrf_token(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    client: str = Query(..., description=\"The client to create a CSRF token for\"),\n) -&gt; schemas.core.CsrfToken:\n    \"\"\"Create or update a CSRF token for a client\"\"\"\n    if PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value() is False:\n        raise HTTPException(\n            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"CSRF protection is disabled.\",\n        )\n\n    async with db.session_context(begin_transaction=True) as session:\n        token = await models.csrf_token.create_or_update_csrf_token(\n            session=session, client=client\n        )\n        await models.csrf_token.delete_expired_tokens(session=session)\n\n    return token\n</code></pre>","tags":["Prefect API","csrf","security"]},{"location":"api-ref/server/api/dependencies/","title":"server.api.dependencies","text":"","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies","title":"<code>prefect.server.api.dependencies</code>","text":"<p>Utilities for injecting FastAPI dependencies.</p>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.EnforceMinimumAPIVersion","title":"<code>EnforceMinimumAPIVersion</code>","text":"<p>FastAPI Dependency used to check compatibility between the version of the api and a given request.</p> <p>Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it to the api's version. Rejects requests that are lower than the minimum version.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>class EnforceMinimumAPIVersion:\n    \"\"\"\n    FastAPI Dependency used to check compatibility between the version of the api\n    and a given request.\n\n    Looks for the header 'X-PREFECT-API-VERSION' in the request and compares it\n    to the api's version. Rejects requests that are lower than the minimum version.\n    \"\"\"\n\n    def __init__(self, minimum_api_version: str, logger: logging.Logger):\n        self.minimum_api_version = minimum_api_version\n        versions = [int(v) for v in minimum_api_version.split(\".\")]\n        self.api_major = versions[0]\n        self.api_minor = versions[1]\n        self.api_patch = versions[2]\n        self.logger = logger\n\n    async def __call__(\n        self,\n        x_prefect_api_version: str = Header(None),\n    ):\n        request_version = x_prefect_api_version\n\n        # if no version header, assume latest and continue\n        if not request_version:\n            return\n\n        # parse version\n        try:\n            major, minor, patch = [int(v) for v in request_version.split(\".\")]\n        except ValueError:\n            await self._notify_of_invalid_value(request_version)\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=(\n                    \"Invalid X-PREFECT-API-VERSION header format.\"\n                    f\"Expected header in format 'x.y.z' but received {request_version}\"\n                ),\n            )\n\n        if (major, minor, patch) &lt; (self.api_major, self.api_minor, self.api_patch):\n            await self._notify_of_outdated_version(request_version)\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=(\n                    f\"The request specified API version {request_version} but this \"\n                    f\"server requires version {self.minimum_api_version} or higher.\"\n                ),\n            )\n\n    async def _notify_of_invalid_value(self, request_version: str):\n        self.logger.error(\n            f\"Invalid X-PREFECT-API-VERSION header format: '{request_version}'\"\n        )\n\n    async def _notify_of_outdated_version(self, request_version: str):\n        self.logger.error(\n            f\"X-PREFECT-API-VERSION header specifies version '{request_version}' \"\n            f\"but minimum allowed version is '{self.minimum_api_version}'\"\n        )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.LimitBody","title":"<code>LimitBody</code>","text":"<p>A <code>fastapi.Depends</code> factory for pulling a <code>limit: int</code> parameter from the request body while determining the default from the current settings.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def LimitBody() -&gt; Depends:\n    \"\"\"\n    A `fastapi.Depends` factory for pulling a `limit: int` parameter from the\n    request body while determining the default from the current settings.\n    \"\"\"\n\n    def get_limit(\n        limit: int = Body(\n            None,\n            description=\"Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.\",\n        ),\n    ):\n        default_limit = PREFECT_API_DEFAULT_LIMIT.value()\n        limit = limit if limit is not None else default_limit\n        if not limit &gt;= 0:\n            raise HTTPException(\n                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                detail=\"Invalid limit: must be greater than or equal to 0.\",\n            )\n        if limit &gt; default_limit:\n            raise HTTPException(\n                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                detail=f\"Invalid limit: must be less than or equal to {default_limit}.\",\n            )\n        return limit\n\n    return Depends(get_limit)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.get_created_by","title":"<code>get_created_by</code>","text":"<p>A dependency that returns the provenance information to use when creating objects during this API call.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def get_created_by(\n    prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False),\n    prefect_automation_name: Optional[str] = Header(None, include_in_schema=False),\n) -&gt; Optional[schemas.core.CreatedBy]:\n    \"\"\"A dependency that returns the provenance information to use when creating objects\n    during this API call.\"\"\"\n    if prefect_automation_id and prefect_automation_name:\n        try:\n            display_value = b64decode(prefect_automation_name.encode()).decode()\n        except Exception:\n            display_value = None\n\n        if display_value:\n            return schemas.core.CreatedBy(\n                id=prefect_automation_id,\n                type=\"AUTOMATION\",\n                display_value=display_value,\n            )\n\n    return None\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.get_updated_by","title":"<code>get_updated_by</code>","text":"<p>A dependency that returns the provenance information to use when updating objects during this API call.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def get_updated_by(\n    prefect_automation_id: Optional[UUID] = Header(None, include_in_schema=False),\n    prefect_automation_name: Optional[str] = Header(None, include_in_schema=False),\n) -&gt; Optional[schemas.core.UpdatedBy]:\n    \"\"\"A dependency that returns the provenance information to use when updating objects\n    during this API call.\"\"\"\n    if prefect_automation_id and prefect_automation_name:\n        return schemas.core.UpdatedBy(\n            id=prefect_automation_id,\n            type=\"AUTOMATION\",\n            display_value=prefect_automation_name,\n        )\n\n    return None\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/dependencies/#prefect.server.api.dependencies.is_ephemeral_request","title":"<code>is_ephemeral_request</code>","text":"<p>A dependency that returns whether the request is to an ephemeral server.</p> Source code in <code>prefect/server/api/dependencies.py</code> <pre><code>def is_ephemeral_request(request: Request):\n    \"\"\"\n    A dependency that returns whether the request is to an ephemeral server.\n    \"\"\"\n    return \"ephemeral-prefect\" in str(request.base_url)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/deployments/","title":"server.api.deployments","text":"","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments","title":"<code>prefect.server.api.deployments</code>","text":"<p>Routes for interacting with Deployment objects.</p>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.count_deployments","title":"<code>count_deployments</code>  <code>async</code>","text":"<p>Count deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/count\")\nasync def count_deployments(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Count deployments.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.deployments.count_deployments(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Gracefully creates a new deployment from the provided schema. If a deployment with the same name and flow_id already exists, the deployment is updated.</p> <p>If the deployment has an active schedule, flow runs will be scheduled. When upserting, any scheduled runs from the existing deployment will be deleted.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/\")\nasync def create_deployment(\n    deployment: schemas.actions.DeploymentCreate,\n    response: Response,\n    worker_lookups: WorkerLookups = Depends(WorkerLookups),\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    updated_by: Optional[schemas.core.UpdatedBy] = Depends(dependencies.get_updated_by),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Gracefully creates a new deployment from the provided schema. If a deployment with\n    the same name and flow_id already exists, the deployment is updated.\n\n    If the deployment has an active schedule, flow runs will be scheduled.\n    When upserting, any scheduled runs from the existing deployment will be deleted.\n    \"\"\"\n\n    data = deployment.dict(exclude_unset=True)\n    data[\"created_by\"] = created_by.dict() if created_by else None\n    data[\"updated_by\"] = updated_by.dict() if created_by else None\n\n    async with db.session_context(begin_transaction=True) as session:\n        if (\n            deployment.work_pool_name\n            and deployment.work_pool_name != DEFAULT_AGENT_WORK_POOL_NAME\n        ):\n            # Make sure that deployment is valid before beginning creation process\n            work_pool = await models.workers.read_work_pool_by_name(\n                session=session, work_pool_name=deployment.work_pool_name\n            )\n            if work_pool is None:\n                raise HTTPException(\n                    status_code=status.HTTP_404_NOT_FOUND,\n                    detail=f'Work pool \"{deployment.work_pool_name}\" not found.',\n                )\n\n            await validate_job_variables_for_deployment(\n                session,\n                work_pool,\n                deployment,\n            )\n\n        # hydrate the input model into a full model\n        deployment_dict = deployment.dict(exclude={\"work_pool_name\"})\n        if deployment.work_pool_name and deployment.work_queue_name:\n            # If a specific pool name/queue name combination was provided, get the\n            # ID for that work pool queue.\n            deployment_dict[\n                \"work_queue_id\"\n            ] = await worker_lookups._get_work_queue_id_from_name(\n                session=session,\n                work_pool_name=deployment.work_pool_name,\n                work_queue_name=deployment.work_queue_name,\n                create_queue_if_not_found=True,\n            )\n        elif deployment.work_pool_name:\n            # If just a pool name was provided, get the ID for its default\n            # work pool queue.\n            deployment_dict[\n                \"work_queue_id\"\n            ] = await worker_lookups._get_default_work_queue_id_from_work_pool_name(\n                session=session,\n                work_pool_name=deployment.work_pool_name,\n            )\n        elif deployment.work_queue_name:\n            # If just a queue name was provided, ensure that the queue exists and\n            # get its ID.\n            work_queue = await models.work_queues.ensure_work_queue_exists(\n                session=session, name=deployment.work_queue_name\n            )\n            deployment_dict[\"work_queue_id\"] = work_queue.id\n\n        deployment = schemas.core.Deployment(**deployment_dict)\n        # check to see if relevant blocks exist, allowing us throw a useful error message\n        # for debugging\n        if deployment.infrastructure_document_id is not None:\n            infrastructure_block = (\n                await models.block_documents.read_block_document_by_id(\n                    session=session,\n                    block_document_id=deployment.infrastructure_document_id,\n                )\n            )\n            if not infrastructure_block:\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error creating deployment. Could not find infrastructure\"\n                        f\" block with id: {deployment.infrastructure_document_id}. This\"\n                        \" usually occurs when applying a deployment specification that\"\n                        \" was built against a different Prefect database / workspace.\"\n                    ),\n                )\n\n        if deployment.storage_document_id is not None:\n            storage_block = await models.block_documents.read_block_document_by_id(\n                session=session,\n                block_document_id=deployment.storage_document_id,\n            )\n            if not storage_block:\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error creating deployment. Could not find storage block with\"\n                        f\" id: {deployment.storage_document_id}. This usually occurs\"\n                        \" when applying a deployment specification that was built\"\n                        \" against a different Prefect database / workspace.\"\n                    ),\n                )\n\n        # Ensure that `paused` and `is_schedule_active` are consistent.\n        if \"paused\" in data:\n            deployment.is_schedule_active = not data[\"paused\"]\n        elif \"is_schedule_active\" in data:\n            deployment.paused = not data[\"is_schedule_active\"]\n\n        now = pendulum.now(\"UTC\")\n        model = await models.deployments.create_deployment(\n            session=session, deployment=deployment\n        )\n\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n\n        return schemas.responses.DeploymentResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.create_flow_run_from_deployment","title":"<code>create_flow_run_from_deployment</code>  <code>async</code>","text":"<p>Create a flow run from a deployment.</p> <p>Any parameters not provided will be inferred from the deployment's parameters. If tags are not provided, the deployment's tags will be used.</p> <p>If no state is provided, the flow run will be created in a SCHEDULED state.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id}/create_flow_run\")\nasync def create_flow_run_from_deployment(\n    flow_run: schemas.actions.DeploymentFlowRunCreate,\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    worker_lookups: WorkerLookups = Depends(WorkerLookups),\n    response: Response = None,\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Create a flow run from a deployment.\n\n    Any parameters not provided will be inferred from the deployment's parameters.\n    If tags are not provided, the deployment's tags will be used.\n\n    If no state is provided, the flow run will be created in a SCHEDULED state.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        # get relevant info from the deployment\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n\n        try:\n            dehydrated_params = deployment.parameters\n            dehydrated_params.update(flow_run.parameters or {})\n            ctx = await HydrationContext.build(\n                session=session,\n                raise_on_error=True,\n                render_jinja=True,\n                render_workspace_variables=True,\n            )\n            parameters = hydrate(dehydrated_params, ctx)\n        except HydrationError as exc:\n            raise HTTPException(\n                status.HTTP_400_BAD_REQUEST,\n                detail=f\"Error hydrating flow run parameters: {exc}\",\n            )\n\n        # default\n        enforce_parameter_schema = deployment.enforce_parameter_schema\n\n        # run override\n        if flow_run.enforce_parameter_schema is not None:\n            enforce_parameter_schema = flow_run.enforce_parameter_schema\n\n        if enforce_parameter_schema:\n            if not isinstance(deployment.parameter_openapi_schema, dict):\n                raise HTTPException(\n                    status.HTTP_409_CONFLICT,\n                    detail=(\n                        \"Error updating deployment: Cannot update parameters because\"\n                        \" parameter schema enforcement is enabled and the deployment\"\n                        \" does not have a valid parameter schema.\"\n                    ),\n                )\n            try:\n                validate(\n                    parameters, deployment.parameter_openapi_schema, raise_on_error=True\n                )\n            except ValidationError as exc:\n                raise HTTPException(\n                    status.HTTP_409_CONFLICT,\n                    detail=f\"Error creating flow run: {exc}\",\n                )\n            except CircularSchemaRefError:\n                raise HTTPException(\n                    status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n                    detail=\"Invalid schema: Unable to validate schema with circular references.\",\n                )\n\n        await validate_job_variables_for_deployment_flow_run(\n            session, deployment, flow_run\n        )\n\n        work_queue_name = deployment.work_queue_name\n        work_queue_id = deployment.work_queue_id\n\n        if flow_run.work_queue_name:\n            # can't mutate the ORM model or else it will commit the changes back\n            work_queue_id = await worker_lookups._get_work_queue_id_from_name(\n                session=session,\n                work_pool_name=deployment.work_queue.work_pool.name,\n                work_queue_name=flow_run.work_queue_name,\n                create_queue_if_not_found=True,\n            )\n            work_queue_name = flow_run.work_queue_name\n\n        # hydrate the input model into a full flow run / state model\n        flow_run = schemas.core.FlowRun(\n            **flow_run.dict(\n                exclude={\n                    \"parameters\",\n                    \"tags\",\n                    \"infrastructure_document_id\",\n                    \"work_queue_name\",\n                    \"enforce_parameter_schema\",\n                }\n            ),\n            flow_id=deployment.flow_id,\n            deployment_id=deployment.id,\n            deployment_version=deployment.version,\n            parameters=parameters,\n            tags=set(deployment.tags).union(flow_run.tags),\n            infrastructure_document_id=(\n                flow_run.infrastructure_document_id\n                or deployment.infrastructure_document_id\n            ),\n            work_queue_name=work_queue_name,\n            work_queue_id=work_queue_id,\n            created_by=created_by,\n        )\n\n        if not flow_run.state:\n            flow_run.state = schemas.states.Scheduled()\n\n        now = pendulum.now(\"UTC\")\n        model = await models.flow_runs.create_flow_run(\n            session=session, flow_run=flow_run\n        )\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n        return schemas.responses.FlowRunResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete a deployment by id.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a deployment by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.deployments.delete_deployment(\n            session=session, deployment_id=deployment_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.get_scheduled_flow_runs_for_deployments","title":"<code>get_scheduled_flow_runs_for_deployments</code>  <code>async</code>","text":"<p>Get scheduled runs for a set of deployments. Used by a runner to poll for work.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/get_scheduled_flow_runs\")\nasync def get_scheduled_flow_runs_for_deployments(\n    background_tasks: BackgroundTasks,\n    deployment_ids: List[UUID] = Body(\n        default=..., description=\"The deployment IDs to get scheduled runs for\"\n    ),\n    scheduled_before: DateTimeTZ = Body(\n        None, description=\"The maximum time to look for scheduled flow runs\"\n    ),\n    limit: int = dependencies.LimitBody(),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.FlowRunResponse]:\n    \"\"\"\n    Get scheduled runs for a set of deployments. Used by a runner to poll for work.\n    \"\"\"\n    async with db.session_context() as session:\n        orm_flow_runs = await models.flow_runs.read_flow_runs(\n            session=session,\n            limit=limit,\n            deployment_filter=schemas.filters.DeploymentFilter(\n                id=schemas.filters.DeploymentFilterId(any_=deployment_ids),\n            ),\n            flow_run_filter=schemas.filters.FlowRunFilter(\n                next_scheduled_start_time=schemas.filters.FlowRunFilterNextScheduledStartTime(\n                    before_=scheduled_before\n                ),\n                state=schemas.filters.FlowRunFilterState(\n                    type=schemas.filters.FlowRunFilterStateType(\n                        any_=[schemas.states.StateType.SCHEDULED]\n                    )\n                ),\n            ),\n            sort=schemas.sorting.FlowRunSort.NEXT_SCHEDULED_START_TIME_ASC,\n        )\n\n        flow_run_responses = [\n            schemas.responses.FlowRunResponse.from_orm(orm_flow_run=orm_flow_run)\n            for orm_flow_run in orm_flow_runs\n        ]\n\n    background_tasks.add_task(\n        mark_deployments_ready,\n        deployment_ids=deployment_ids,\n    )\n\n    return flow_run_responses\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.pause_deployment","title":"<code>pause_deployment</code>  <code>async</code>","text":"<p>Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled state will be deleted.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id:uuid}/set_schedule_inactive\")  # Legacy route\n@router.post(\"/{id:uuid}/pause_deployment\")\nasync def pause_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled\n    state will be deleted.\n    \"\"\"\n    async with db.session_context(begin_transaction=False) as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        deployment.is_schedule_active = False\n        deployment.paused = True\n\n        # Ensure that we're updating the replicated schedule's `active` field,\n        # if there is only a single schedule. This is support for legacy\n        # clients.\n\n        number_of_schedules = len(deployment.schedules)\n\n        if number_of_schedules == 1:\n            deployment.schedules[0].active = False\n        elif number_of_schedules &gt; 1:\n            raise _multiple_schedules_error(deployment_id)\n\n        # commit here to make the inactive schedule \"visible\" to the scheduler service\n        await session.commit()\n\n        # delete any auto scheduled runs\n        await models.deployments._delete_scheduled_runs(\n            session=session,\n            deployment_id=deployment_id,\n            auto_scheduled_only=True,\n        )\n\n        await session.commit()\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Get a deployment by id.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Get a deployment by id.\n    \"\"\"\n    async with db.session_context() as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        return schemas.responses.DeploymentResponse.from_orm(deployment)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Get a deployment using the name of the flow and the deployment.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/name/{flow_name}/{deployment_name}\")\nasync def read_deployment_by_name(\n    flow_name: str = Path(..., description=\"The name of the flow\"),\n    deployment_name: str = Path(..., description=\"The name of the deployment\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.DeploymentResponse:\n    \"\"\"\n    Get a deployment using the name of the flow and the deployment.\n    \"\"\"\n    async with db.session_context() as session:\n        deployment = await models.deployments.read_deployment_by_name(\n            session=session, name=deployment_name, flow_name=flow_name\n        )\n        if not deployment:\n            raise HTTPException(\n                status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        return schemas.responses.DeploymentResponse.from_orm(deployment)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Query for deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_deployments(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    sort: schemas.sorting.DeploymentSort = Body(\n        schemas.sorting.DeploymentSort.NAME_ASC\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.DeploymentResponse]:\n    \"\"\"\n    Query for deployments.\n    \"\"\"\n    async with db.session_context() as session:\n        response = await models.deployments.read_deployments(\n            session=session,\n            offset=offset,\n            sort=sort,\n            limit=limit,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n        return [\n            schemas.responses.DeploymentResponse.from_orm(orm_deployment=deployment)\n            for deployment in response\n        ]\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.resume_deployment","title":"<code>resume_deployment</code>  <code>async</code>","text":"<p>Set a deployment schedule to active. Runs will be scheduled immediately.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id:uuid}/set_schedule_active\")  # Legacy route\n@router.post(\"/{id:uuid}/resume_deployment\")\nasync def resume_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Set a deployment schedule to active. Runs will be scheduled immediately.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        deployment = await models.deployments.read_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        if not deployment:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n            )\n        deployment.is_schedule_active = True\n        deployment.paused = False\n\n        # Ensure that we're updating the replicated schedule's `active` field,\n        # if there is only a single schedule. This is support for legacy\n        # clients.\n\n        number_of_schedules = len(deployment.schedules)\n\n        if number_of_schedules == 1:\n            deployment.schedules[0].active = True\n        elif number_of_schedules &gt; 1:\n            raise _multiple_schedules_error(deployment_id)\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.schedule_deployment","title":"<code>schedule_deployment</code>  <code>async</code>","text":"<p>Schedule runs for a deployment. For backfills, provide start/end times in the past.</p> <p>This function will generate the minimum number of runs that satisfy the min and max times, and the min and max counts. Specifically, the following order will be respected.</p> <pre><code>- Runs will be generated starting on or after the `start_time`\n- No more than `max_runs` runs will be generated\n- No runs will be generated after `end_time` is reached\n- At least `min_runs` runs will be generated\n- Runs will be generated until at least `start_time + min_time` is reached\n</code></pre> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.post(\"/{id}/schedule\")\nasync def schedule_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    start_time: DateTimeTZ = Body(None, description=\"The earliest date to schedule\"),\n    end_time: DateTimeTZ = Body(None, description=\"The latest date to schedule\"),\n    min_time: datetime.timedelta = Body(\n        None,\n        description=(\n            \"Runs will be scheduled until at least this long after the `start_time`\"\n        ),\n    ),\n    min_runs: int = Body(None, description=\"The minimum number of runs to schedule\"),\n    max_runs: int = Body(None, description=\"The maximum number of runs to schedule\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; None:\n    \"\"\"\n    Schedule runs for a deployment. For backfills, provide start/end times in the past.\n\n    This function will generate the minimum number of runs that satisfy the min\n    and max times, and the min and max counts. Specifically, the following order\n    will be respected.\n\n        - Runs will be generated starting on or after the `start_time`\n        - No more than `max_runs` runs will be generated\n        - No runs will be generated after `end_time` is reached\n        - At least `min_runs` runs will be generated\n        - Runs will be generated until at least `start_time + min_time` is reached\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        await models.deployments.schedule_runs(\n            session=session,\n            deployment_id=deployment_id,\n            start_time=start_time,\n            min_time=min_time,\n            end_time=end_time,\n            min_runs=min_runs,\n            max_runs=max_runs,\n        )\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/deployments/#prefect.server.api.deployments.work_queue_check_for_deployment","title":"<code>work_queue_check_for_deployment</code>  <code>async</code>","text":"<p>Get list of work-queues that are able to pick up the specified deployment.</p> <p>This endpoint is intended to be used by the UI to provide users warnings about deployments that are unable to be executed because there are no work queues that will pick up their runs, based on existing filter criteria. It may be deprecated in the future because there is not a strict relationship between work queues and deployments.</p> Source code in <code>prefect/server/api/deployments.py</code> <pre><code>@router.get(\"/{id}/work_queue_check\", deprecated=True)\nasync def work_queue_check_for_deployment(\n    deployment_id: UUID = Path(..., description=\"The deployment id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.WorkQueue]:\n    \"\"\"\n    Get list of work-queues that are able to pick up the specified deployment.\n\n    This endpoint is intended to be used by the UI to provide users warnings\n    about deployments that are unable to be executed because there are no work\n    queues that will pick up their runs, based on existing filter criteria. It\n    may be deprecated in the future because there is not a strict relationship\n    between work queues and deployments.\n    \"\"\"\n    try:\n        async with db.session_context() as session:\n            work_queues = await models.deployments.check_work_queues_for_deployment(\n                session=session, deployment_id=deployment_id\n            )\n    except ObjectNotFoundError:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Deployment not found\"\n        )\n    return work_queues\n</code></pre>","tags":["Prefect API","deployments"]},{"location":"api-ref/server/api/flow_run_states/","title":"server.api.flow_run_states","text":"","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states","title":"<code>prefect.server.api.flow_run_states</code>","text":"<p>Routes for interacting with flow run state objects.</p>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states.read_flow_run_state","title":"<code>read_flow_run_state</code>  <code>async</code>","text":"<p>Get a flow run state by id.</p> Source code in <code>prefect/server/api/flow_run_states.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow_run_state(\n    flow_run_state_id: UUID = Path(\n        ..., description=\"The flow run state id\", alias=\"id\"\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.states.State:\n    \"\"\"\n    Get a flow run state by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow_run_state = await models.flow_run_states.read_flow_run_state(\n            session=session, flow_run_state_id=flow_run_state_id\n        )\n    if not flow_run_state:\n        raise HTTPException(\n            status.HTTP_404_NOT_FOUND, detail=\"Flow run state not found\"\n        )\n    return flow_run_state\n</code></pre>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_run_states/#prefect.server.api.flow_run_states.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Get states associated with a flow run.</p> Source code in <code>prefect/server/api/flow_run_states.py</code> <pre><code>@router.get(\"/\")\nasync def read_flow_run_states(\n    flow_run_id: UUID,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.states.State]:\n    \"\"\"\n    Get states associated with a flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_run_states.read_flow_run_states(\n            session=session, flow_run_id=flow_run_id\n        )\n</code></pre>","tags":["Prefect API","flow runs","states"]},{"location":"api-ref/server/api/flow_runs/","title":"server.api.flow_runs","text":"","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs","title":"<code>prefect.server.api.flow_runs</code>","text":"<p>Routes for interacting with flow run objects.</p>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.average_flow_run_lateness","title":"<code>average_flow_run_lateness</code>  <code>async</code>","text":"<p>Query for average flow-run lateness in seconds.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/lateness\")\nasync def average_flow_run_lateness(\n    flows: Optional[schemas.filters.FlowFilter] = None,\n    flow_runs: Optional[schemas.filters.FlowRunFilter] = None,\n    task_runs: Optional[schemas.filters.TaskRunFilter] = None,\n    deployments: Optional[schemas.filters.DeploymentFilter] = None,\n    work_pools: Optional[schemas.filters.WorkPoolFilter] = None,\n    work_pool_queues: Optional[schemas.filters.WorkQueueFilter] = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; Optional[float]:\n    \"\"\"\n    Query for average flow-run lateness in seconds.\n    \"\"\"\n    async with db.session_context() as session:\n        if db.dialect.name == \"sqlite\":\n            # Since we want an _average_ of the lateness we're unable to use\n            # the existing FlowRun.expected_start_time_delta property as it\n            # returns a timedelta and SQLite is unable to properly deal with it\n            # and always returns 1970.0 as the average. This copies the same\n            # logic but ensures that it returns the number of seconds instead\n            # so it's compatible with SQLite.\n            base_query = sa.case(\n                (\n                    db.FlowRun.start_time &gt; db.FlowRun.expected_start_time,\n                    sa.func.strftime(\"%s\", db.FlowRun.start_time)\n                    - sa.func.strftime(\"%s\", db.FlowRun.expected_start_time),\n                ),\n                (\n                    db.FlowRun.start_time.is_(None)\n                    &amp; db.FlowRun.state_type.notin_(schemas.states.TERMINAL_STATES)\n                    &amp; (db.FlowRun.expected_start_time &lt; sa.func.datetime(\"now\")),\n                    sa.func.strftime(\"%s\", sa.func.datetime(\"now\"))\n                    - sa.func.strftime(\"%s\", db.FlowRun.expected_start_time),\n                ),\n                else_=0,\n            )\n        else:\n            base_query = db.FlowRun.estimated_start_time_delta\n\n        query = await models.flow_runs._apply_flow_run_filters(\n            sa.select(sa.func.avg(base_query)),\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n        result = await session.execute(query)\n\n        avg_lateness = result.scalar()\n\n        if avg_lateness is None:\n            return None\n        elif isinstance(avg_lateness, datetime.timedelta):\n            return avg_lateness.total_seconds()\n        else:\n            return avg_lateness\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.count_flow_runs","title":"<code>count_flow_runs</code>  <code>async</code>","text":"<p>Query for flow runs.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/count\")\nasync def count_flow_runs(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Query for flow runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_runs.count_flow_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Create a flow run. If a flow run with the same flow_id and idempotency key already exists, the existing flow run will be returned.</p> <p>If no state is provided, the flow run will be created in a PENDING state.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/\")\nasync def create_flow_run(\n    flow_run: schemas.actions.FlowRunCreate,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    created_by: Optional[schemas.core.CreatedBy] = Depends(dependencies.get_created_by),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Create a flow run. If a flow run with the same flow_id and\n    idempotency key already exists, the existing flow run will be returned.\n\n    If no state is provided, the flow run will be created in a PENDING state.\n    \"\"\"\n    # hydrate the input model into a full flow run / state model\n    flow_run = schemas.core.FlowRun(**flow_run.dict(), created_by=created_by)\n\n    # pass the request version to the orchestration engine to support compatibility code\n    orchestration_parameters.update({\"api-version\": api_version})\n\n    if not flow_run.state:\n        flow_run.state = schemas.states.Pending()\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.flow_runs.create_flow_run(\n            session=session,\n            flow_run=flow_run,\n            orchestration_parameters=orchestration_parameters,\n        )\n        if model.created &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n\n        return schemas.responses.FlowRunResponse.from_orm(model)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.create_flow_run_input","title":"<code>create_flow_run_input</code>  <code>async</code>","text":"<p>Create a key/value input for a flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/input\", status_code=status.HTTP_201_CREATED)\nasync def create_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Body(..., description=\"The input key\"),\n    value: bytes = Body(..., description=\"The value of the input\"),\n    sender: Optional[str] = Body(None, description=\"The sender of the input\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Create a key/value input for a flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        try:\n            await models.flow_run_input.create_flow_run_input(\n                session=session,\n                flow_run_input=schemas.core.FlowRunInput(\n                    flow_run_id=flow_run_id,\n                    key=key,\n                    sender=sender,\n                    value=value.decode(),\n                ),\n            )\n            await session.commit()\n\n        except IntegrityError as exc:\n            if \"unique constraint\" in str(exc).lower():\n                raise HTTPException(\n                    status_code=status.HTTP_409_CONFLICT,\n                    detail=\"A flow run input with this key already exists.\",\n                )\n            else:\n                raise HTTPException(\n                    status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n                )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by id.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow run by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flow_runs.delete_flow_run(\n            session=session, flow_run_id=flow_run_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.delete_flow_run_input","title":"<code>delete_flow_run_input</code>  <code>async</code>","text":"<p>Delete a flow run input</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.delete(\"/{id}/input/{key}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Path(..., description=\"The input key\", alias=\"key\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow run input\n    \"\"\"\n\n    async with db.session_context() as session:\n        deleted = await models.flow_run_input.delete_flow_run_input(\n            session=session, flow_run_id=flow_run_id, key=key\n        )\n        await session.commit()\n\n        if not deleted:\n            raise HTTPException(\n                status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run input not found\"\n            )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.filter_flow_run_input","title":"<code>filter_flow_run_input</code>  <code>async</code>","text":"<p>Filter flow run inputs by key prefix</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/input/filter\")\nasync def filter_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    prefix: str = Body(..., description=\"The input key prefix\", embed=True),\n    limit: int = Body(\n        1, description=\"The maximum number of results to return\", embed=True\n    ),\n    exclude_keys: List[str] = Body(\n        [], description=\"Exclude inputs with these keys\", embed=True\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.FlowRunInput]:\n    \"\"\"\n    Filter flow run inputs by key prefix\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_run_input.filter_flow_run_input(\n            session=session,\n            flow_run_id=flow_run_id,\n            prefix=prefix,\n            limit=limit,\n            exclude_keys=exclude_keys,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.flow_run_history","title":"<code>flow_run_history</code>  <code>async</code>","text":"<p>Query for flow run history data across a given range and interval.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/history\")\nasync def flow_run_history(\n    history_start: DateTimeTZ = Body(..., description=\"The history's start time.\"),\n    history_end: DateTimeTZ = Body(..., description=\"The history's end time.\"),\n    history_interval: datetime.timedelta = Body(\n        ...,\n        description=(\n            \"The size of each history interval, in seconds. Must be at least 1 second.\"\n        ),\n        alias=\"history_interval_seconds\",\n    ),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Query for flow run history data across a given range and interval.\n    \"\"\"\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise HTTPException(\n            status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"History interval must not be less than 1 second.\",\n        )\n\n    async with db.session_context() as session:\n        return await run_history(\n            session=session,\n            run_type=\"flow_run\",\n            history_start=history_start,\n            history_end=history_end,\n            history_interval=history_interval,\n            flows=flows,\n            flow_runs=flow_runs,\n            task_runs=task_runs,\n            deployments=deployments,\n            work_pools=work_pools,\n            work_queues=work_queues,\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Get a flow run by id.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.responses.FlowRunResponse:\n    \"\"\"\n    Get a flow run by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow_run = await models.flow_runs.read_flow_run(\n            session=session, flow_run_id=flow_run_id\n        )\n        if not flow_run:\n            raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\")\n        return schemas.responses.FlowRunResponse.from_orm(flow_run)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_graph_v1","title":"<code>read_flow_run_graph_v1</code>  <code>async</code>","text":"<p>Get a task run dependency map for a given flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}/graph\")\nasync def read_flow_run_graph_v1(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[DependencyResult]:\n    \"\"\"\n    Get a task run dependency map for a given flow run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flow_runs.read_task_run_dependencies(\n            session=session, flow_run_id=flow_run_id\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_graph_v2","title":"<code>read_flow_run_graph_v2</code>  <code>async</code>","text":"<p>Get a graph of the tasks and subflow runs for the given flow run</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id:uuid}/graph-v2\")\nasync def read_flow_run_graph_v2(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    since: datetime.datetime = Query(\n        datetime.datetime.min,\n        description=\"Only include runs that start or end after this time.\",\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; Graph:\n    \"\"\"\n    Get a graph of the tasks and subflow runs for the given flow run\n    \"\"\"\n    async with db.session_context() as session:\n        try:\n            return await read_flow_run_graph(\n                session=session,\n                flow_run_id=flow_run_id,\n                since=since,\n            )\n        except FlowRunGraphTooLarge as e:\n            raise HTTPException(\n                status_code=status.HTTP_400_BAD_REQUEST,\n                detail=str(e),\n            )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_run_input","title":"<code>read_flow_run_input</code>  <code>async</code>","text":"<p>Create a value from a flow run input</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.get(\"/{id}/input/{key}\")\nasync def read_flow_run_input(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    key: str = Path(..., description=\"The input key\", alias=\"key\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; PlainTextResponse:\n    \"\"\"\n    Create a value from a flow run input\n    \"\"\"\n\n    async with db.session_context() as session:\n        flow_run_input = await models.flow_run_input.read_flow_run_input(\n            session=session, flow_run_id=flow_run_id, key=key\n        )\n\n    if flow_run_input:\n        return PlainTextResponse(flow_run_input.value)\n    else:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run input not found\"\n        )\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Query for flow runs.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/filter\", response_class=ORJSONResponse)\nasync def read_flow_runs(\n    sort: schemas.sorting.FlowRunSort = Body(schemas.sorting.FlowRunSort.ID_DESC),\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_pool_queues: schemas.filters.WorkQueueFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.FlowRunResponse]:\n    \"\"\"\n    Query for flow runs.\n    \"\"\"\n    async with db.session_context() as session:\n        db_flow_runs = await models.flow_runs.read_flow_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_pool_queues,\n            offset=offset,\n            limit=limit,\n            sort=sort,\n        )\n\n        # Instead of relying on fastapi.encoders.jsonable_encoder to convert the\n        # response to JSON, we do so more efficiently ourselves.\n        # In particular, the FastAPI encoder is very slow for large, nested objects.\n        # See: https://github.com/tiangolo/fastapi/issues/1224\n        encoded = [\n            schemas.responses.FlowRunResponse.from_orm(fr).dict(json_compatible=True)\n            for fr in db_flow_runs\n        ]\n        return ORJSONResponse(content=encoded)\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.resume_flow_run","title":"<code>resume_flow_run</code>  <code>async</code>","text":"<p>Resume a paused flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/resume\")\nasync def resume_flow_run(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    run_input: Optional[Dict] = Body(default=None, embed=True),\n    response: Response = None,\n    flow_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_flow_policy\n    ),\n    task_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_task_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Resume a paused flow run.\n    \"\"\"\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        flow_run = await models.flow_runs.read_flow_run(session, flow_run_id)\n        state = flow_run.state\n\n        if state is None or state.type != schemas.states.StateType.PAUSED:\n            result = OrchestrationResult(\n                state=None,\n                status=schemas.responses.SetStateStatus.ABORT,\n                details=schemas.responses.StateAbortDetails(\n                    reason=\"Cannot resume a flow run that is not paused.\"\n                ),\n            )\n            return result\n\n        orchestration_parameters.update({\"api-version\": api_version})\n\n        keyset = state.state_details.run_input_keyset\n\n        if keyset:\n            run_input = run_input or {}\n\n            try:\n                hydration_context = await schema_tools.HydrationContext.build(\n                    session=session,\n                    raise_on_error=True,\n                    render_jinja=True,\n                    render_workspace_variables=True,\n                )\n                run_input = schema_tools.hydrate(run_input, hydration_context) or {}\n            except schema_tools.HydrationError as exc:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=f\"Error hydrating run input: {exc}\",\n                    ),\n                )\n\n            schema_json = await models.flow_run_input.read_flow_run_input(\n                session=session, flow_run_id=flow_run.id, key=keyset[\"schema\"]\n            )\n\n            if schema_json is None:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Run input schema not found.\"\n                    ),\n                )\n\n            try:\n                schema = orjson.loads(schema_json.value)\n            except orjson.JSONDecodeError:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Run input schema is not valid JSON.\"\n                    ),\n                )\n\n            try:\n                schema_tools.validate(run_input, schema, raise_on_error=True)\n            except schema_tools.ValidationError as exc:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=f\"Reason: {exc}\"\n                    ),\n                )\n            except schema_tools.CircularSchemaRefError:\n                return OrchestrationResult(\n                    state=state,\n                    status=schemas.responses.SetStateStatus.REJECT,\n                    details=schemas.responses.StateAbortDetails(\n                        reason=\"Invalid schema: Unable to validate schema with circular references.\",\n                    ),\n                )\n\n        if state.state_details.pause_reschedule:\n            orchestration_result = await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run_id,\n                state=schemas.states.Scheduled(\n                    name=\"Resuming\", scheduled_time=pendulum.now(\"UTC\")\n                ),\n                flow_policy=flow_policy,\n                orchestration_parameters=orchestration_parameters,\n            )\n        else:\n            orchestration_result = await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run_id,\n                state=schemas.states.Running(),\n                flow_policy=flow_policy,\n                orchestration_parameters=orchestration_parameters,\n            )\n\n        if (\n            keyset\n            and run_input\n            and orchestration_result.status == schemas.responses.SetStateStatus.ACCEPT\n        ):\n            # The state change is accepted, go ahead and store the validated\n            # run input.\n            await models.flow_run_input.create_flow_run_input(\n                session=session,\n                flow_run_input=schemas.core.FlowRunInput(\n                    flow_run_id=flow_run_id,\n                    key=keyset[\"response\"],\n                    value=orjson.dumps(run_input).decode(\"utf-8\"),\n                ),\n            )\n\n        # set the 201 if a new state was created\n        if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n            response.status_code = status.HTTP_201_CREATED\n        else:\n            response.status_code = status.HTTP_200_OK\n\n        return orchestration_result\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Set a flow run state, invoking any orchestration rules.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.post(\"/{id}/set_state\")\nasync def set_flow_run_state(\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    state: schemas.actions.StateCreate = Body(..., description=\"The intended state.\"),\n    force: bool = Body(\n        False,\n        description=(\n            \"If false, orchestration rules will be applied that may alter or prevent\"\n            \" the state transition. If True, orchestration rules are not applied.\"\n        ),\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    flow_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_flow_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_flow_orchestration_parameters\n    ),\n    api_version=Depends(dependencies.provide_request_api_version),\n) -&gt; OrchestrationResult:\n    \"\"\"Set a flow run state, invoking any orchestration rules.\"\"\"\n\n    # pass the request version to the orchestration engine to support compatibility code\n    orchestration_parameters.update({\"api-version\": api_version})\n\n    now = pendulum.now(\"UTC\")\n\n    # create the state\n    async with db.session_context(\n        begin_transaction=True, with_for_update=True\n    ) as session:\n        orchestration_result = await models.flow_runs.set_flow_run_state(\n            session=session,\n            flow_run_id=flow_run_id,\n            # convert to a full State object\n            state=schemas.states.State.parse_obj(state),\n            force=force,\n            flow_policy=flow_policy,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    # set the 201 if a new state was created\n    if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    else:\n        response.status_code = status.HTTP_200_OK\n\n    return orchestration_result\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flow_runs/#prefect.server.api.flow_runs.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Updates a flow run.</p> Source code in <code>prefect/server/api/flow_runs.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_flow_run(\n    flow_run: schemas.actions.FlowRunUpdate,\n    flow_run_id: UUID = Path(..., description=\"The flow run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a flow run.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        if flow_run.job_variables is not None:\n            this_run = await models.flow_runs.read_flow_run(\n                session, flow_run_id=flow_run_id\n            )\n            if this_run is None:\n                raise HTTPException(\n                    status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\"\n                )\n            if not this_run.state:\n                raise HTTPException(\n                    status.HTTP_400_BAD_REQUEST,\n                    detail=\"Flow run state is required to update job variables but none exists\",\n                )\n            if this_run.state.type != schemas.states.StateType.SCHEDULED:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=f\"Job variables for a flow run in state {this_run.state.type.name} cannot be updated\",\n                )\n            if this_run.deployment_id is None:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=\"A deployment for the flow run could not be found\",\n                )\n\n            deployment = await models.deployments.read_deployment(\n                session=session, deployment_id=this_run.deployment_id\n            )\n            if deployment is None:\n                raise HTTPException(\n                    status_code=status.HTTP_400_BAD_REQUEST,\n                    detail=\"A deployment for the flow run could not be found\",\n                )\n\n            await validate_job_variables_for_deployment_flow_run(\n                session, deployment, flow_run\n            )\n\n        result = await models.flow_runs.update_flow_run(\n            session=session, flow_run=flow_run, flow_run_id=flow_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Flow run not found\")\n</code></pre>","tags":["Prefect API","flow runs"]},{"location":"api-ref/server/api/flows/","title":"server.api.flows","text":"","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows","title":"<code>prefect.server.api.flows</code>","text":"<p>Routes for interacting with flow objects.</p>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.count_flows","title":"<code>count_flows</code>  <code>async</code>","text":"<p>Count flows.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/count\")\nasync def count_flows(\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; int:\n    \"\"\"\n    Count flows.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flows.count_flows(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Gracefully creates a new flow from the provided schema. If a flow with the same name already exists, the existing flow is returned.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/\")\nasync def create_flow(\n    flow: schemas.actions.FlowCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"Gracefully creates a new flow from the provided schema. If a flow with the\n    same name already exists, the existing flow is returned.\n    \"\"\"\n    # hydrate the input model into a full flow model\n    flow = schemas.core.Flow(**flow.dict())\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.flows.create_flow(session=session, flow=flow)\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    return model\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.delete_flow","title":"<code>delete_flow</code>  <code>async</code>","text":"<p>Delete a flow by id.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_flow(\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a flow by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flows.delete_flow(session=session, flow_id=flow_id)\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Get a flow by id.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_flow(\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"\n    Get a flow by id.\n    \"\"\"\n    async with db.session_context() as session:\n        flow = await models.flows.read_flow(session=session, flow_id=flow_id)\n    if not flow:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n    return flow\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Get a flow by name.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.get(\"/name/{name}\")\nasync def read_flow_by_name(\n    name: str = Path(..., description=\"The name of the flow\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.Flow:\n    \"\"\"\n    Get a flow by name.\n    \"\"\"\n    async with db.session_context() as session:\n        flow = await models.flows.read_flow_by_name(session=session, name=name)\n    if not flow:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n    return flow\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Query for flows.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_flows(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    sort: schemas.sorting.FlowSort = Body(schemas.sorting.FlowSort.NAME_ASC),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.Flow]:\n    \"\"\"\n    Query for flows.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.flows.read_flows(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            sort=sort,\n            offset=offset,\n            limit=limit,\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/flows/#prefect.server.api.flows.update_flow","title":"<code>update_flow</code>  <code>async</code>","text":"<p>Updates a flow.</p> Source code in <code>prefect/server/api/flows.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_flow(\n    flow: schemas.actions.FlowUpdate,\n    flow_id: UUID = Path(..., description=\"The flow id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a flow.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.flows.update_flow(\n            session=session, flow=flow, flow_id=flow_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow not found\"\n        )\n</code></pre>","tags":["Prefect API","flows"]},{"location":"api-ref/server/api/middleware/","title":"server.api.middleware","text":"","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware","title":"<code>prefect.server.api.middleware</code>","text":"","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware.CsrfMiddleware","title":"<code>CsrfMiddleware</code>","text":"<p>               Bases: <code>BaseHTTPMiddleware</code></p> <p>Middleware for CSRF protection. This middleware will check for a CSRF token in the headers of any POST, PUT, PATCH, or DELETE request. If the token is not present or does not match the token stored in the database for the client, the request will be rejected with a 403 status code.</p> Source code in <code>prefect/server/api/middleware.py</code> <pre><code>class CsrfMiddleware(BaseHTTPMiddleware):\n    \"\"\"\n    Middleware for CSRF protection. This middleware will check for a CSRF token\n    in the headers of any POST, PUT, PATCH, or DELETE request. If the token is\n    not present or does not match the token stored in the database for the\n    client, the request will be rejected with a 403 status code.\n    \"\"\"\n\n    async def dispatch(\n        self, request: Request, call_next: NextMiddlewareFunction\n    ) -&gt; Response:\n        \"\"\"\n        Dispatch method for the middleware. This method will check for the\n        presence of a CSRF token in the headers of the request and compare it\n        to the token stored in the database for the client. If the token is not\n        present or does not match, the request will be rejected with a 403\n        status code.\n        \"\"\"\n\n        request_needs_csrf_protection = request.method in {\n            \"POST\",\n            \"PUT\",\n            \"PATCH\",\n            \"DELETE\",\n        }\n\n        if (\n            settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value()\n            and request_needs_csrf_protection\n        ):\n            incoming_token = request.headers.get(\"Prefect-Csrf-Token\")\n            incoming_client = request.headers.get(\"Prefect-Csrf-Client\")\n\n            if incoming_token is None:\n                return JSONResponse(\n                    {\"detail\": \"Missing CSRF token.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                )\n\n            if incoming_client is None:\n                return JSONResponse(\n                    {\"detail\": \"Missing client identifier.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                )\n\n            db = provide_database_interface()\n            async with db.session_context() as session:\n                token = await models.csrf_token.read_token_for_client(\n                    session=session, client=incoming_client\n                )\n\n                if token is None or token.token != incoming_token:\n                    return JSONResponse(\n                        {\"detail\": \"Invalid CSRF token or client identifier.\"},\n                        status_code=status.HTTP_403_FORBIDDEN,\n                        headers={\"Access-Control-Allow-Origin\": \"*\"},\n                    )\n\n        return await call_next(request)\n</code></pre>","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/middleware/#prefect.server.api.middleware.CsrfMiddleware.dispatch","title":"<code>dispatch</code>  <code>async</code>","text":"<p>Dispatch method for the middleware. This method will check for the presence of a CSRF token in the headers of the request and compare it to the token stored in the database for the client. If the token is not present or does not match, the request will be rejected with a 403 status code.</p> Source code in <code>prefect/server/api/middleware.py</code> <pre><code>async def dispatch(\n    self, request: Request, call_next: NextMiddlewareFunction\n) -&gt; Response:\n    \"\"\"\n    Dispatch method for the middleware. This method will check for the\n    presence of a CSRF token in the headers of the request and compare it\n    to the token stored in the database for the client. If the token is not\n    present or does not match, the request will be rejected with a 403\n    status code.\n    \"\"\"\n\n    request_needs_csrf_protection = request.method in {\n        \"POST\",\n        \"PUT\",\n        \"PATCH\",\n        \"DELETE\",\n    }\n\n    if (\n        settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value()\n        and request_needs_csrf_protection\n    ):\n        incoming_token = request.headers.get(\"Prefect-Csrf-Token\")\n        incoming_client = request.headers.get(\"Prefect-Csrf-Client\")\n\n        if incoming_token is None:\n            return JSONResponse(\n                {\"detail\": \"Missing CSRF token.\"},\n                status_code=status.HTTP_403_FORBIDDEN,\n            )\n\n        if incoming_client is None:\n            return JSONResponse(\n                {\"detail\": \"Missing client identifier.\"},\n                status_code=status.HTTP_403_FORBIDDEN,\n            )\n\n        db = provide_database_interface()\n        async with db.session_context() as session:\n            token = await models.csrf_token.read_token_for_client(\n                session=session, client=incoming_client\n            )\n\n            if token is None or token.token != incoming_token:\n                return JSONResponse(\n                    {\"detail\": \"Invalid CSRF token or client identifier.\"},\n                    status_code=status.HTTP_403_FORBIDDEN,\n                    headers={\"Access-Control-Allow-Origin\": \"*\"},\n                )\n\n    return await call_next(request)\n</code></pre>","tags":["Prefect API","middleware"]},{"location":"api-ref/server/api/run_history/","title":"server.api.run_history","text":"","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/run_history/#prefect.server.api.run_history","title":"<code>prefect.server.api.run_history</code>","text":"<p>Utilities for querying flow and task run history.</p>","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/run_history/#prefect.server.api.run_history.run_history","title":"<code>run_history</code>  <code>async</code>","text":"<p>Produce a history of runs aggregated by interval and state</p> Source code in <code>prefect/server/api/run_history.py</code> <pre><code>@db_injector\nasync def run_history(\n    db: PrefectDBInterface,\n    session: sa.orm.Session,\n    run_type: Literal[\"flow_run\", \"task_run\"],\n    history_start: DateTimeTZ,\n    history_end: DateTimeTZ,\n    history_interval: datetime.timedelta,\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    work_pools: schemas.filters.WorkPoolFilter = None,\n    work_queues: schemas.filters.WorkQueueFilter = None,\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Produce a history of runs aggregated by interval and state\n    \"\"\"\n\n    # SQLite has issues with very small intervals\n    # (by 0.001 seconds it stops incrementing the interval)\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise ValueError(\"History interval must not be less than 1 second.\")\n\n    # prepare run-specific models\n    if run_type == \"flow_run\":\n        run_model = db.FlowRun\n        run_filter_function = models.flow_runs._apply_flow_run_filters\n    elif run_type == \"task_run\":\n        run_model = db.TaskRun\n        run_filter_function = models.task_runs._apply_task_run_filters\n    else:\n        raise ValueError(\n            f\"Unknown run type {run_type!r}. Expected 'flow_run' or 'task_run'.\"\n        )\n\n    # create a CTE for timestamp intervals\n    intervals = db.make_timestamp_intervals(\n        history_start,\n        history_end,\n        history_interval,\n    ).cte(\"intervals\")\n\n    # apply filters to the flow runs (and related states)\n    runs = (\n        await run_filter_function(\n            sa.select(\n                run_model.id,\n                run_model.expected_start_time,\n                run_model.estimated_run_time,\n                run_model.estimated_start_time_delta,\n                run_model.state_type,\n                run_model.state_name,\n            ).select_from(run_model),\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            work_pool_filter=work_pools,\n            work_queue_filter=work_queues,\n        )\n    ).alias(\"runs\")\n    # outer join intervals to the filtered runs to create a dataset composed of\n    # every interval and the aggregate of all its runs. The runs aggregate is represented\n    # by a descriptive JSON object\n    counts = (\n        sa.select(\n            intervals.c.interval_start,\n            intervals.c.interval_end,\n            # build a JSON object, ignoring the case where the count of runs is 0\n            sa.case(\n                (sa.func.count(runs.c.id) == 0, None),\n                else_=db.build_json_object(\n                    \"state_type\",\n                    runs.c.state_type,\n                    \"state_name\",\n                    runs.c.state_name,\n                    \"count_runs\",\n                    sa.func.count(runs.c.id),\n                    # estimated run times only includes positive run times (to avoid any unexpected corner cases)\n                    \"sum_estimated_run_time\",\n                    sa.func.sum(\n                        db.greatest(0, sa.extract(\"epoch\", runs.c.estimated_run_time))\n                    ),\n                    # estimated lateness is the sum of any positive start time deltas\n                    \"sum_estimated_lateness\",\n                    sa.func.sum(\n                        db.greatest(\n                            0, sa.extract(\"epoch\", runs.c.estimated_start_time_delta)\n                        )\n                    ),\n                ),\n            ).label(\"state_agg\"),\n        )\n        .select_from(intervals)\n        .join(\n            runs,\n            sa.and_(\n                runs.c.expected_start_time &gt;= intervals.c.interval_start,\n                runs.c.expected_start_time &lt; intervals.c.interval_end,\n            ),\n            isouter=True,\n        )\n        .group_by(\n            intervals.c.interval_start,\n            intervals.c.interval_end,\n            runs.c.state_type,\n            runs.c.state_name,\n        )\n    ).alias(\"counts\")\n\n    # aggregate all state-aggregate objects into a single array for each interval,\n    # ensuring that intervals with no runs have an empty array\n    query = (\n        sa.select(\n            counts.c.interval_start,\n            counts.c.interval_end,\n            sa.func.coalesce(\n                db.json_arr_agg(db.cast_to_json(counts.c.state_agg)).filter(\n                    counts.c.state_agg.is_not(None)\n                ),\n                sa.text(\"'[]'\"),\n            ).label(\"states\"),\n        )\n        .group_by(counts.c.interval_start, counts.c.interval_end)\n        .order_by(counts.c.interval_start)\n        # return no more than 500 bars\n        .limit(500)\n    )\n\n    # issue the query\n    result = await session.execute(query)\n    records = result.mappings()\n\n    # load and parse the record if the database returns JSON as strings\n    if db.uses_json_strings:\n        records = [dict(r) for r in records]\n        for r in records:\n            r[\"states\"] = json.loads(r[\"states\"])\n\n    return pydantic.parse_obj_as(List[schemas.responses.HistoryResponse], list(records))\n</code></pre>","tags":["Prefect API","flow runs","task runs","observability"]},{"location":"api-ref/server/api/saved_searches/","title":"server.api.saved_searches","text":"","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches","title":"<code>prefect.server.api.saved_searches</code>","text":"<p>Routes for interacting with saved search objects.</p>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.create_saved_search","title":"<code>create_saved_search</code>  <code>async</code>","text":"<p>Gracefully creates a new saved search from the provided schema.</p> <p>If a saved search with the same name already exists, the saved search's fields are replaced.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.put(\"/\")\nasync def create_saved_search(\n    saved_search: schemas.actions.SavedSearchCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.SavedSearch:\n    \"\"\"Gracefully creates a new saved search from the provided schema.\n\n    If a saved search with the same name already exists, the saved search's fields are\n    replaced.\n    \"\"\"\n\n    # hydrate the input model into a full model\n    saved_search = schemas.core.SavedSearch(**saved_search.dict())\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.saved_searches.create_saved_search(\n            session=session, saved_search=saved_search\n        )\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n\n    return model\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.delete_saved_search","title":"<code>delete_saved_search</code>  <code>async</code>","text":"<p>Delete a saved search by id.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_saved_search(\n    saved_search_id: UUID = Path(..., description=\"The saved search id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a saved search by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.saved_searches.delete_saved_search(\n            session=session, saved_search_id=saved_search_id\n        )\n    if not result:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Saved search not found\"\n        )\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.read_saved_search","title":"<code>read_saved_search</code>  <code>async</code>","text":"<p>Get a saved search by id.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_saved_search(\n    saved_search_id: UUID = Path(..., description=\"The saved search id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.SavedSearch:\n    \"\"\"\n    Get a saved search by id.\n    \"\"\"\n    async with db.session_context() as session:\n        saved_search = await models.saved_searches.read_saved_search(\n            session=session, saved_search_id=saved_search_id\n        )\n    if not saved_search:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Saved search not found\"\n        )\n    return saved_search\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/saved_searches/#prefect.server.api.saved_searches.read_saved_searches","title":"<code>read_saved_searches</code>  <code>async</code>","text":"<p>Query for saved searches.</p> Source code in <code>prefect/server/api/saved_searches.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_saved_searches(\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.SavedSearch]:\n    \"\"\"\n    Query for saved searches.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.saved_searches.read_saved_searches(\n            session=session,\n            offset=offset,\n            limit=limit,\n        )\n</code></pre>","tags":["Prefect API","search","saved search"]},{"location":"api-ref/server/api/server/","title":"server.api.server","text":"","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server","title":"<code>prefect.server.api.server</code>","text":"<p>Defines the Prefect REST API FastAPI app.</p>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.RequestLimitMiddleware","title":"<code>RequestLimitMiddleware</code>","text":"<p>A middleware that limits the number of concurrent requests handled by the API.</p> <p>This is a blunt tool for limiting SQLite concurrent writes which will cause failures at high volume. Ideally, we would only apply the limit to routes that perform writes.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>class RequestLimitMiddleware:\n    \"\"\"\n    A middleware that limits the number of concurrent requests handled by the API.\n\n    This is a blunt tool for limiting SQLite concurrent writes which will cause failures\n    at high volume. Ideally, we would only apply the limit to routes that perform\n    writes.\n    \"\"\"\n\n    def __init__(self, app, limit: float):\n        self.app = app\n        self._limiter = anyio.CapacityLimiter(limit)\n\n    async def __call__(self, scope, receive, send) -&gt; None:\n        async with self._limiter:\n            await self.app(scope, receive, send)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.SPAStaticFiles","title":"<code>SPAStaticFiles</code>","text":"<p>               Bases: <code>StaticFiles</code></p> <p>Implementation of <code>StaticFiles</code> for serving single page applications.</p> <p>Adds <code>get_response</code> handling to ensure that when a resource isn't found the application still returns the index.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>class SPAStaticFiles(StaticFiles):\n    \"\"\"\n    Implementation of `StaticFiles` for serving single page applications.\n\n    Adds `get_response` handling to ensure that when a resource isn't found the\n    application still returns the index.\n    \"\"\"\n\n    async def get_response(self, path: str, scope):\n        try:\n            return await super().get_response(path, scope)\n        except HTTPException:\n            return await super().get_response(\"./index.html\", scope)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.create_api_app","title":"<code>create_api_app</code>","text":"<p>Create a FastAPI app that includes the Prefect REST API</p> <p>Parameters:</p> Name Type Description Default <code>router_prefix</code> <code>Optional[str]</code> <p>a prefix to apply to all included routers</p> <code>''</code> <code>dependencies</code> <code>Optional[List[Depends]]</code> <p>a list of global dependencies to add to each Prefect REST API router</p> <code>None</code> <code>health_check_path</code> <code>str</code> <p>the health check route path</p> <code>'/health'</code> <code>fast_api_app_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>kwargs to pass to the FastAPI constructor</p> <code>None</code> <code>router_overrides</code> <code>Mapping[str, Optional[APIRouter]]</code> <p>a mapping of route prefixes (i.e. \"/admin\") to new routers allowing the caller to override the default routers. If <code>None</code> is provided as a value, the default router will be dropped from the application.</p> <code>None</code> <p>Returns:</p> Type Description <code>FastAPI</code> <p>a FastAPI app that serves the Prefect REST API</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>def create_api_app(\n    router_prefix: Optional[str] = \"\",\n    dependencies: Optional[List[Depends]] = None,\n    health_check_path: str = \"/health\",\n    version_check_path: str = \"/version\",\n    fast_api_app_kwargs: Optional[Dict[str, Any]] = None,\n    router_overrides: Mapping[str, Optional[APIRouter]] = None,\n) -&gt; FastAPI:\n    \"\"\"\n    Create a FastAPI app that includes the Prefect REST API\n\n    Args:\n        router_prefix: a prefix to apply to all included routers\n        dependencies: a list of global dependencies to add to each Prefect REST API router\n        health_check_path: the health check route path\n        fast_api_app_kwargs: kwargs to pass to the FastAPI constructor\n        router_overrides: a mapping of route prefixes (i.e. \"/admin\") to new routers\n            allowing the caller to override the default routers. If `None` is provided\n            as a value, the default router will be dropped from the application.\n\n    Returns:\n        a FastAPI app that serves the Prefect REST API\n    \"\"\"\n    fast_api_app_kwargs = fast_api_app_kwargs or {}\n    api_app = FastAPI(title=API_TITLE, **fast_api_app_kwargs)\n    api_app.add_middleware(GZipMiddleware)\n\n    @api_app.get(health_check_path, tags=[\"Root\"])\n    async def health_check():\n        return True\n\n    @api_app.get(version_check_path, tags=[\"Root\"])\n    async def orion_info():\n        return SERVER_API_VERSION\n\n    # always include version checking\n    if dependencies is None:\n        dependencies = [Depends(enforce_minimum_version)]\n    else:\n        dependencies.append(Depends(enforce_minimum_version))\n\n    routers = {router.prefix: router for router in API_ROUTERS}\n\n    if router_overrides:\n        for prefix, router in router_overrides.items():\n            # We may want to allow this behavior in the future to inject new routes, but\n            # for now this will be treated an as an exception\n            if prefix not in routers:\n                raise KeyError(\n                    \"Router override provided for prefix that does not exist:\"\n                    f\" {prefix!r}\"\n                )\n\n            # Drop the existing router\n            existing_router = routers.pop(prefix)\n\n            # Replace it with a new router if provided\n            if router is not None:\n                if prefix != router.prefix:\n                    # We may want to allow this behavior in the future, but it will\n                    # break expectations without additional routing and is banned for\n                    # now\n                    raise ValueError(\n                        f\"Router override for {prefix!r} defines a different prefix \"\n                        f\"{router.prefix!r}.\"\n                    )\n\n                existing_paths = method_paths_from_routes(existing_router.routes)\n                new_paths = method_paths_from_routes(router.routes)\n                if not existing_paths.issubset(new_paths):\n                    raise ValueError(\n                        f\"Router override for {prefix!r} is missing paths defined by \"\n                        f\"the original router: {existing_paths.difference(new_paths)}\"\n                    )\n\n                routers[prefix] = router\n\n    for router in routers.values():\n        api_app.include_router(router, prefix=router_prefix, dependencies=dependencies)\n\n    return api_app\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.create_app","title":"<code>create_app</code>","text":"<p>Create an FastAPI app that includes the Prefect REST API and UI</p> <p>Parameters:</p> Name Type Description Default <code>settings</code> <code>Settings</code> <p>The settings to use to create the app. If not set, settings are pulled from the context.</p> <code>None</code> <code>ignore_cache</code> <code>bool</code> <p>If set, a new application will be created even if the settings match. Otherwise, an application is returned from the cache.</p> <code>False</code> <code>ephemeral</code> <code>bool</code> <p>If set, the application will be treated as ephemeral. The UI and services will be disabled.</p> <code>False</code> Source code in <code>prefect/server/api/server.py</code> <pre><code>def create_app(\n    settings: prefect.settings.Settings = None,\n    ephemeral: bool = False,\n    ignore_cache: bool = False,\n) -&gt; FastAPI:\n    \"\"\"\n    Create an FastAPI app that includes the Prefect REST API and UI\n\n    Args:\n        settings: The settings to use to create the app. If not set, settings are pulled\n            from the context.\n        ignore_cache: If set, a new application will be created even if the settings\n            match. Otherwise, an application is returned from the cache.\n        ephemeral: If set, the application will be treated as ephemeral. The UI\n            and services will be disabled.\n    \"\"\"\n    settings = settings or prefect.settings.get_current_settings()\n    cache_key = (settings.hash_key(), ephemeral)\n\n    if cache_key in APP_CACHE and not ignore_cache:\n        return APP_CACHE[cache_key]\n\n    # TODO: Move these startup functions out of this closure into the top-level or\n    #       another dedicated location\n    async def run_migrations():\n        \"\"\"Ensure the database is created and up to date with the current migrations\"\"\"\n        if prefect.settings.PREFECT_API_DATABASE_MIGRATE_ON_START:\n            from prefect.server.database.dependencies import provide_database_interface\n\n            db = provide_database_interface()\n            await db.create_db()\n\n    @_memoize_block_auto_registration\n    async def add_block_types():\n        \"\"\"Add all registered blocks to the database\"\"\"\n        if not prefect.settings.PREFECT_API_BLOCKS_REGISTER_ON_START:\n            return\n\n        from prefect.server.database.dependencies import provide_database_interface\n        from prefect.server.models.block_registration import run_block_auto_registration\n\n        db = provide_database_interface()\n        session = await db.session()\n\n        async with session:\n            await run_block_auto_registration(session=session)\n\n    async def start_services():\n        \"\"\"Start additional services when the Prefect REST API starts up.\"\"\"\n\n        if ephemeral:\n            app.state.services = None\n            return\n\n        service_instances = []\n\n        if prefect.settings.PREFECT_API_SERVICES_SCHEDULER_ENABLED.value():\n            service_instances.append(services.scheduler.Scheduler(handle_signals=False))\n            service_instances.append(\n                services.scheduler.RecentDeploymentsScheduler(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_LATE_RUNS_ENABLED.value():\n            service_instances.append(\n                services.late_runs.MarkLateRuns(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED.value():\n            service_instances.append(\n                services.pause_expirations.FailExpiredPauses(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED.value():\n            service_instances.append(\n                services.cancellation_cleanup.CancellationCleanup(handle_signals=False)\n            )\n\n        if prefect.settings.PREFECT_SERVER_ANALYTICS_ENABLED.value():\n            service_instances.append(services.telemetry.Telemetry(handle_signals=False))\n\n        if prefect.settings.PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED.value():\n            service_instances.append(\n                services.flow_run_notifications.FlowRunNotifications(\n                    handle_signals=False\n                )\n            )\n\n        if prefect.settings.PREFECT_API_SERVICES_FOREMAN_ENABLED.value():\n            service_instances.append(services.foreman.Foreman(handle_signals=False))\n\n        if prefect.settings.PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value():\n            service_instances.append(\n                services.task_scheduling.TaskSchedulingTimeouts(handle_signals=False)\n            )\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS.value()\n            and prefect.settings.PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED.value()\n        ):\n            service_instances.append(EventLogger())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS.value()\n            and prefect.settings.PREFECT_API_SERVICES_TRIGGERS_ENABLED.value()\n        ):\n            service_instances.append(ReactiveTriggers())\n            service_instances.append(ProactiveTriggers(handle_signals=False))\n            service_instances.append(Actions())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS\n            and prefect.settings.PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED\n        ):\n            service_instances.append(EventPersister())\n\n        if (\n            prefect.settings.PREFECT_EXPERIMENTAL_EVENTS\n            and prefect.settings.PREFECT_API_EVENTS_STREAM_OUT_ENABLED\n        ):\n            service_instances.append(stream.Distributor())\n\n        loop = asyncio.get_running_loop()\n\n        app.state.services = {\n            service: loop.create_task(service.start()) for service in service_instances\n        }\n\n        for service, task in app.state.services.items():\n            logger.info(f\"{service.name} service scheduled to start in-app\")\n            task.add_done_callback(partial(on_service_exit, service))\n\n    async def stop_services():\n        \"\"\"Ensure services are stopped before the Prefect REST API shuts down.\"\"\"\n        if hasattr(app.state, \"services\") and app.state.services:\n            await asyncio.gather(*[service.stop() for service in app.state.services])\n            try:\n                await asyncio.gather(\n                    *[task.stop() for task in app.state.services.values()]\n                )\n            except Exception:\n                # `on_service_exit` should handle logging exceptions on exit\n                pass\n\n    @asynccontextmanager\n    async def lifespan(app):\n        try:\n            await run_migrations()\n            await add_block_types()\n            await start_services()\n            yield\n        finally:\n            await stop_services()\n\n    def on_service_exit(service, task):\n        \"\"\"\n        Added as a callback for completion of services to log exit\n        \"\"\"\n        try:\n            # Retrieving the result will raise the exception\n            task.result()\n        except Exception:\n            logger.error(f\"{service.name} service failed!\", exc_info=True)\n        else:\n            logger.info(f\"{service.name} service stopped!\")\n\n    app = FastAPI(\n        title=TITLE,\n        version=API_VERSION,\n        lifespan=lifespan,\n    )\n    api_app = create_api_app(\n        fast_api_app_kwargs={\n            \"exception_handlers\": {\n                # NOTE: FastAPI special cases the generic `Exception` handler and\n                #       registers it as a separate middleware from the others\n                Exception: custom_internal_exception_handler,\n                RequestValidationError: validation_exception_handler,\n                sa.exc.IntegrityError: integrity_exception_handler,\n                ObjectNotFoundError: prefect_object_not_found_exception_handler,\n            }\n        },\n    )\n    ui_app = create_ui_app(ephemeral)\n\n    # middleware\n    app.add_middleware(\n        CORSMiddleware,\n        allow_origins=[\"*\"],\n        allow_methods=[\"*\"],\n        allow_headers=[\"*\"],\n    )\n\n    # Limit the number of concurrent requests when using a SQLite database to reduce\n    # chance of errors where the database cannot be opened due to a high number of\n    # concurrent writes\n    if (\n        get_dialect(prefect.settings.PREFECT_API_DATABASE_CONNECTION_URL.value()).name\n        == \"sqlite\"\n    ):\n        app.add_middleware(RequestLimitMiddleware, limit=100)\n\n    if prefect.settings.PREFECT_SERVER_CSRF_PROTECTION_ENABLED.value():\n        app.add_middleware(api.middleware.CsrfMiddleware)\n\n    api_app.mount(\n        \"/static\",\n        StaticFiles(\n            directory=os.path.join(\n                os.path.dirname(os.path.realpath(__file__)), \"static\"\n            )\n        ),\n        name=\"static\",\n    )\n    app.api_app = api_app\n    app.mount(\"/api\", app=api_app, name=\"api\")\n    app.mount(\"/\", app=ui_app, name=\"ui\")\n\n    def openapi():\n        \"\"\"\n        Convenience method for extracting the user facing OpenAPI schema from the API app.\n\n        This method is attached to the global public app for easy access.\n        \"\"\"\n        partial_schema = get_openapi(\n            title=API_TITLE,\n            version=API_VERSION,\n            routes=api_app.routes,\n        )\n        new_schema = partial_schema.copy()\n        new_schema[\"paths\"] = {}\n        for path, value in partial_schema[\"paths\"].items():\n            new_schema[\"paths\"][f\"/api{path}\"] = value\n\n        new_schema[\"info\"][\"x-logo\"] = {\"url\": \"static/prefect-logo-mark-gradient.png\"}\n        return new_schema\n\n    app.openapi = openapi\n\n    APP_CACHE[cache_key] = app\n    return app\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.custom_internal_exception_handler","title":"<code>custom_internal_exception_handler</code>  <code>async</code>","text":"<p>Log a detailed exception for internal server errors before returning.</p> <p>Send 503 for errors clients can retry on.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def custom_internal_exception_handler(request: Request, exc: Exception):\n    \"\"\"\n    Log a detailed exception for internal server errors before returning.\n\n    Send 503 for errors clients can retry on.\n    \"\"\"\n    logger.error(\"Encountered exception in request:\", exc_info=True)\n\n    if is_client_retryable_exception(exc):\n        return JSONResponse(\n            content={\"exception_message\": \"Service Unavailable\"},\n            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,\n        )\n\n    return JSONResponse(\n        content={\"exception_message\": \"Internal Server Error\"},\n        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.integrity_exception_handler","title":"<code>integrity_exception_handler</code>  <code>async</code>","text":"<p>Capture database integrity errors.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def integrity_exception_handler(request: Request, exc: Exception):\n    \"\"\"Capture database integrity errors.\"\"\"\n    logger.error(\"Encountered exception in request:\", exc_info=True)\n    return JSONResponse(\n        content={\n            \"detail\": (\n                \"Data integrity conflict. This usually means a \"\n                \"unique or foreign key constraint was violated. \"\n                \"See server logs for details.\"\n            )\n        },\n        status_code=status.HTTP_409_CONFLICT,\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.prefect_object_not_found_exception_handler","title":"<code>prefect_object_not_found_exception_handler</code>  <code>async</code>","text":"<p>Return 404 status code on object not found exceptions.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def prefect_object_not_found_exception_handler(\n    request: Request, exc: ObjectNotFoundError\n):\n    \"\"\"Return 404 status code on object not found exceptions.\"\"\"\n    return JSONResponse(\n        content={\"exception_message\": str(exc)}, status_code=status.HTTP_404_NOT_FOUND\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.replace_placeholder_string_in_files","title":"<code>replace_placeholder_string_in_files</code>","text":"<p>Recursively loops through all files in the given directory and replaces a placeholder string.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>def replace_placeholder_string_in_files(\n    directory, placeholder, replacement, allowed_extensions=None\n):\n    \"\"\"\n    Recursively loops through all files in the given directory and replaces\n    a placeholder string.\n    \"\"\"\n    if allowed_extensions is None:\n        allowed_extensions = [\".txt\", \".html\", \".css\", \".js\", \".json\", \".txt\"]\n\n    for root, dirs, files in os.walk(directory):\n        for file in files:\n            if any(file.endswith(ext) for ext in allowed_extensions):\n                file_path = os.path.join(root, file)\n\n                with open(file_path, \"r\", encoding=\"utf-8\") as file:\n                    file_data = file.read()\n\n                file_data = file_data.replace(placeholder, replacement)\n\n                with open(file_path, \"w\", encoding=\"utf-8\") as file:\n                    file.write(file_data)\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/server/#prefect.server.api.server.validation_exception_handler","title":"<code>validation_exception_handler</code>  <code>async</code>","text":"<p>Provide a detailed message for request validation errors.</p> Source code in <code>prefect/server/api/server.py</code> <pre><code>async def validation_exception_handler(request: Request, exc: RequestValidationError):\n    \"\"\"Provide a detailed message for request validation errors.\"\"\"\n    return JSONResponse(\n        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n        content=jsonable_encoder(\n            {\n                \"exception_message\": \"Invalid request received.\",\n                \"exception_detail\": exc.errors(),\n                \"request_body\": exc.body,\n            }\n        ),\n    )\n</code></pre>","tags":["Prefect API","FastAPI"]},{"location":"api-ref/server/api/task_run_states/","title":"server.api.task_run_states","text":"","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states","title":"<code>prefect.server.api.task_run_states</code>","text":"<p>Routes for interacting with task run state objects.</p>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states.read_task_run_state","title":"<code>read_task_run_state</code>  <code>async</code>","text":"<p>Get a task run state by id.</p> Source code in <code>prefect/server/api/task_run_states.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_task_run_state(\n    task_run_state_id: UUID = Path(\n        ..., description=\"The task run state id\", alias=\"id\"\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.states.State:\n    \"\"\"\n    Get a task run state by id.\n    \"\"\"\n    async with db.session_context() as session:\n        task_run_state = await models.task_run_states.read_task_run_state(\n            session=session, task_run_state_id=task_run_state_id\n        )\n    if not task_run_state:\n        raise HTTPException(\n            status_code=status.HTTP_404_NOT_FOUND, detail=\"Flow run state not found\"\n        )\n    return task_run_state\n</code></pre>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_run_states/#prefect.server.api.task_run_states.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Get states associated with a task run.</p> Source code in <code>prefect/server/api/task_run_states.py</code> <pre><code>@router.get(\"/\")\nasync def read_task_run_states(\n    task_run_id: UUID,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.states.State]:\n    \"\"\"\n    Get states associated with a task run.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_run_states.read_task_run_states(\n            session=session, task_run_id=task_run_id\n        )\n</code></pre>","tags":["Prefect API","task runs","states"]},{"location":"api-ref/server/api/task_runs/","title":"server.api.task_runs","text":"","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs","title":"<code>prefect.server.api.task_runs</code>","text":"<p>Routes for interacting with task run objects.</p>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.count_task_runs","title":"<code>count_task_runs</code>  <code>async</code>","text":"<p>Count task runs.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/count\")\nasync def count_task_runs(\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count task runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_runs.count_task_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Create a task run. If a task run with the same flow_run_id, task_key, and dynamic_key already exists, the existing task run will be returned.</p> <p>If no state is provided, the task run will be created in a PENDING state.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/\")\nasync def create_task_run(\n    task_run: schemas.actions.TaskRunCreate,\n    response: Response,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_task_orchestration_parameters\n    ),\n) -&gt; schemas.core.TaskRun:\n    \"\"\"\n    Create a task run. If a task run with the same flow_run_id,\n    task_key, and dynamic_key already exists, the existing task\n    run will be returned.\n\n    If no state is provided, the task run will be created in a PENDING state.\n    \"\"\"\n\n    # hydrate the input model into a full task run / state model\n    task_run_dict = task_run.dict()\n    if not task_run_dict.get(\"id\"):\n        task_run_dict.pop(\"id\", None)\n    task_run = schemas.core.TaskRun(**task_run_dict)\n\n    if not task_run.state:\n        task_run.state = schemas.states.Pending()\n\n    now = pendulum.now(\"UTC\")\n\n    async with db.session_context(begin_transaction=True) as session:\n        model = await models.task_runs.create_task_run(\n            session=session,\n            task_run=task_run,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    if model.created &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n\n    new_task_run: schemas.core.TaskRun = schemas.core.TaskRun.from_orm(model)\n\n    return new_task_run\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.delete(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def delete_task_run(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Delete a task run by id.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.task_runs.delete_task_run(\n            session=session, task_run_id=task_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task not found\")\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Get a task run by id.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.get(\"/{id}\")\nasync def read_task_run(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; schemas.core.TaskRun:\n    \"\"\"\n    Get a task run by id.\n    \"\"\"\n    async with db.session_context() as session:\n        task_run = await models.task_runs.read_task_run(\n            session=session, task_run_id=task_run_id\n        )\n    if not task_run:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task not found\")\n    return task_run\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Query for task runs.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/filter\")\nasync def read_task_runs(\n    sort: schemas.sorting.TaskRunSort = Body(schemas.sorting.TaskRunSort.ID_DESC),\n    limit: int = dependencies.LimitBody(),\n    offset: int = Body(0, ge=0),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.core.TaskRun]:\n    \"\"\"\n    Query for task runs.\n    \"\"\"\n    async with db.session_context() as session:\n        return await models.task_runs.read_task_runs(\n            session=session,\n            flow_filter=flows,\n            flow_run_filter=flow_runs,\n            task_run_filter=task_runs,\n            deployment_filter=deployments,\n            offset=offset,\n            limit=limit,\n            sort=sort,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Set a task run state, invoking any orchestration rules.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/{id}/set_state\")\nasync def set_task_run_state(\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    state: schemas.actions.StateCreate = Body(..., description=\"The intended state.\"),\n    force: bool = Body(\n        False,\n        description=(\n            \"If false, orchestration rules will be applied that may alter or prevent\"\n            \" the state transition. If True, orchestration rules are not applied.\"\n        ),\n    ),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n    response: Response = None,\n    task_policy: BaseOrchestrationPolicy = Depends(\n        orchestration_dependencies.provide_task_policy\n    ),\n    orchestration_parameters: Dict[str, Any] = Depends(\n        orchestration_dependencies.provide_task_orchestration_parameters\n    ),\n) -&gt; OrchestrationResult:\n    \"\"\"Set a task run state, invoking any orchestration rules.\"\"\"\n\n    now = pendulum.now(\"UTC\")\n\n    # create the state\n    async with db.session_context(\n        begin_transaction=True, with_for_update=True\n    ) as session:\n        orchestration_result = await models.task_runs.set_task_run_state(\n            session=session,\n            task_run_id=task_run_id,\n            state=schemas.states.State.parse_obj(\n                state\n            ),  # convert to a full State object\n            force=force,\n            task_policy=task_policy,\n            orchestration_parameters=orchestration_parameters,\n        )\n\n    # set the 201 if a new state was created\n    if orchestration_result.state and orchestration_result.state.timestamp &gt;= now:\n        response.status_code = status.HTTP_201_CREATED\n    else:\n        response.status_code = status.HTTP_200_OK\n\n    return orchestration_result\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.task_run_history","title":"<code>task_run_history</code>  <code>async</code>","text":"<p>Query for task run history data across a given range and interval.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.post(\"/history\")\nasync def task_run_history(\n    history_start: DateTimeTZ = Body(..., description=\"The history's start time.\"),\n    history_end: DateTimeTZ = Body(..., description=\"The history's end time.\"),\n    history_interval: datetime.timedelta = Body(\n        ...,\n        description=(\n            \"The size of each history interval, in seconds. Must be at least 1 second.\"\n        ),\n        alias=\"history_interval_seconds\",\n    ),\n    flows: schemas.filters.FlowFilter = None,\n    flow_runs: schemas.filters.FlowRunFilter = None,\n    task_runs: schemas.filters.TaskRunFilter = None,\n    deployments: schemas.filters.DeploymentFilter = None,\n    db: PrefectDBInterface = Depends(provide_database_interface),\n) -&gt; List[schemas.responses.HistoryResponse]:\n    \"\"\"\n    Query for task run history data across a given range and interval.\n    \"\"\"\n    if history_interval &lt; datetime.timedelta(seconds=1):\n        raise HTTPException(\n            status.HTTP_422_UNPROCESSABLE_ENTITY,\n            detail=\"History interval must not be less than 1 second.\",\n        )\n\n    async with db.session_context() as session:\n        return await run_history(\n            session=session,\n            run_type=\"task_run\",\n            history_start=history_start,\n            history_end=history_end,\n            history_interval=history_interval,\n            flows=flows,\n            flow_runs=flow_runs,\n            task_runs=task_runs,\n            deployments=deployments,\n        )\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/api/task_runs/#prefect.server.api.task_runs.update_task_run","title":"<code>update_task_run</code>  <code>async</code>","text":"<p>Updates a task run.</p> Source code in <code>prefect/server/api/task_runs.py</code> <pre><code>@router.patch(\"/{id}\", status_code=status.HTTP_204_NO_CONTENT)\nasync def update_task_run(\n    task_run: schemas.actions.TaskRunUpdate,\n    task_run_id: UUID = Path(..., description=\"The task run id\", alias=\"id\"),\n    db: PrefectDBInterface = Depends(provide_database_interface),\n):\n    \"\"\"\n    Updates a task run.\n    \"\"\"\n    async with db.session_context(begin_transaction=True) as session:\n        result = await models.task_runs.update_task_run(\n            session=session, task_run=task_run, task_run_id=task_run_id\n        )\n    if not result:\n        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=\"Task run not found\")\n</code></pre>","tags":["Prefect API","task runs"]},{"location":"api-ref/server/models/csrf_token/","title":"server.models.csrf_token","text":""},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token","title":"<code>prefect.server.models.csrf_token</code>","text":""},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.create_or_update_csrf_token","title":"<code>create_or_update_csrf_token</code>  <code>async</code>","text":"<p>Create or update a CSRF token for a client. If the client already has a token, it will be updated.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <code>client</code> <code>str</code> <p>The client identifier</p> required <p>Returns:</p> Type Description <code>CsrfToken</code> <p>core.CsrfToken: The CSRF token</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def create_or_update_csrf_token(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    client: str,\n) -&gt; core.CsrfToken:\n    \"\"\"Create or update a CSRF token for a client. If the client already has a\n    token, it will be updated.\n\n    Args:\n        session (AsyncSession): The database session\n        client (str): The client identifier\n\n    Returns:\n        core.CsrfToken: The CSRF token\n    \"\"\"\n\n    expiration = (\n        datetime.now(timezone.utc)\n        + settings.PREFECT_SERVER_CSRF_TOKEN_EXPIRATION.value()\n    )\n    token = secrets.token_hex(32)\n\n    await session.execute(\n        db.insert(db.CsrfToken)\n        .values(\n            client=client,\n            token=token,\n            expiration=expiration,\n        )\n        .on_conflict_do_update(\n            index_elements=[db.CsrfToken.client],\n            set_={\"token\": token, \"expiration\": expiration},\n        ),\n    )\n\n    # Return the created / updated token object\n    return await read_token_for_client(session=session, client=client)\n</code></pre>"},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.delete_expired_tokens","title":"<code>delete_expired_tokens</code>  <code>async</code>","text":"<p>Delete expired CSRF tokens.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of tokens deleted</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def delete_expired_tokens(db: PrefectDBInterface, session: AsyncSession) -&gt; int:\n    \"\"\"Delete expired CSRF tokens.\n\n    Args:\n        session (AsyncSession): The database session\n\n    Returns:\n        int: The number of tokens deleted\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.CsrfToken).where(\n            db.CsrfToken.expiration &lt; datetime.now(timezone.utc)\n        )\n    )\n    return result.rowcount\n</code></pre>"},{"location":"api-ref/server/models/csrf_token/#prefect.server.models.csrf_token.read_token_for_client","title":"<code>read_token_for_client</code>  <code>async</code>","text":"<p>Read a CSRF token for a client.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>The database session</p> required <code>client</code> <code>str</code> <p>The client identifier</p> required <p>Returns:</p> Type Description <code>Optional[CsrfToken]</code> <p>Optional[core.CsrfToken]: The CSRF token, if it exists and is not expired.</p> Source code in <code>prefect/server/models/csrf_token.py</code> <pre><code>@db_injector\nasync def read_token_for_client(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    client: str,\n) -&gt; Optional[core.CsrfToken]:\n    \"\"\"Read a CSRF token for a client.\n\n    Args:\n        session (AsyncSession): The database session\n        client (str): The client identifier\n\n    Returns:\n        Optional[core.CsrfToken]: The CSRF token, if it exists and is not\n            expired.\n    \"\"\"\n    token = (\n        await session.execute(\n            sa.select(db.CsrfToken).where(\n                sa.and_(\n                    db.CsrfToken.expiration &gt; datetime.now(timezone.utc),\n                    db.CsrfToken.client == client,\n                )\n            )\n        )\n    ).scalar_one_or_none()\n\n    if token is None:\n        return None\n\n    return core.CsrfToken.from_orm(token)\n</code></pre>"},{"location":"api-ref/server/models/deployments/","title":"server.models.deployments","text":""},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments","title":"<code>prefect.server.models.deployments</code>","text":"<p>Functions for interacting with deployment ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.check_work_queues_for_deployment","title":"<code>check_work_queues_for_deployment</code>  <code>async</code>","text":"<p>Get work queues that can pick up the specified deployment.</p> <p>Work queues will pick up a deployment when all of the following are met.</p> <ul> <li>The deployment has ALL tags that the work queue has (i.e. the work queue's tags must be a subset of the deployment's tags).</li> <li>The work queue's specified deployment IDs match the deployment's ID, or the work queue does NOT have specified deployment IDs.</li> <li>The work queue's specified flow runners match the deployment's flow runner or the work queue does NOT have a specified flow runner.</li> </ul> <p>Notes on the query:</p> <ul> <li>Our database currently allows either \"null\" and empty lists as null values in filters, so we need to catch both cases with \"or\".</li> <li><code>json_contains(A, B)</code> should be interpreted as \"True if A contains B\".</li> </ul> <p>Returns:</p> Type Description <code>List[WorkQueue]</code> <p>List[db.WorkQueue]: WorkQueues</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def check_work_queues_for_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; List[schemas.core.WorkQueue]:\n    \"\"\"\n    Get work queues that can pick up the specified deployment.\n\n    Work queues will pick up a deployment when all of the following are met.\n\n    - The deployment has ALL tags that the work queue has (i.e. the work\n    queue's tags must be a subset of the deployment's tags).\n    - The work queue's specified deployment IDs match the deployment's ID,\n    or the work queue does NOT have specified deployment IDs.\n    - The work queue's specified flow runners match the deployment's flow\n    runner or the work queue does NOT have a specified flow runner.\n\n    Notes on the query:\n\n    - Our database currently allows either \"null\" and empty lists as\n    null values in filters, so we need to catch both cases with \"or\".\n    - `json_contains(A, B)` should be interpreted as \"True if A\n    contains B\".\n\n    Returns:\n        List[db.WorkQueue]: WorkQueues\n    \"\"\"\n    deployment = await session.get(db.Deployment, deployment_id)\n    if not deployment:\n        raise ObjectNotFoundError(f\"Deployment with id {deployment_id} not found\")\n\n    query = (\n        select(db.WorkQueue)\n        # work queue tags are a subset of deployment tags\n        .filter(\n            or_(\n                json_contains(deployment.tags, db.WorkQueue.filter[\"tags\"]),\n                json_contains([], db.WorkQueue.filter[\"tags\"]),\n                json_contains(None, db.WorkQueue.filter[\"tags\"]),\n            )\n        )\n        # deployment_ids is null or contains the deployment's ID\n        .filter(\n            or_(\n                json_contains(\n                    db.WorkQueue.filter[\"deployment_ids\"],\n                    str(deployment.id),\n                ),\n                json_contains(None, db.WorkQueue.filter[\"deployment_ids\"]),\n                json_contains([], db.WorkQueue.filter[\"deployment_ids\"]),\n            )\n        )\n    )\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.count_deployments","title":"<code>count_deployments</code>  <code>async</code>","text":"<p>Count deployments.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count deployments whose flows match these criteria</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count deployments whose flow runs match these criteria</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count deployments whose task runs match these criteria</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count deployment that match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>only count deployments that match these work pool filters</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>only count deployments that match these work pool queue filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>the number of deployments matching filters</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def count_deployments(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count deployments.\n\n    Args:\n        session: A database session\n        flow_filter: only count deployments whose flows match these criteria\n        flow_run_filter: only count deployments whose flow runs match these criteria\n        task_run_filter: only count deployments whose task runs match these criteria\n        deployment_filter: only count deployment that match these filters\n        work_pool_filter: only count deployments that match these work pool filters\n        work_queue_filter: only count deployments that match these work pool queue filters\n\n    Returns:\n        int: the number of deployments matching filters\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.Deployment)\n\n    query = await _apply_deployment_filters(\n        query=query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.create_deployment","title":"<code>create_deployment</code>  <code>async</code>","text":"<p>Upserts a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment</code> <code>Deployment</code> <p>a deployment model</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the newly-created or updated deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def create_deployment(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment: schemas.core.Deployment,\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Upserts a deployment.\n\n    Args:\n        session: a database session\n        deployment: a deployment model\n\n    Returns:\n        db.Deployment: the newly-created or updated deployment\n\n    \"\"\"\n\n    # set `updated` manually\n    # known limitation of `on_conflict_do_update`, will not use `Column.onupdate`\n    # https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#the-set-clause\n    deployment.updated = pendulum.now(\"UTC\")\n\n    schedules = deployment.schedules\n    insert_values = deployment.dict(\n        shallow=True, exclude_unset=True, exclude={\"schedules\"}\n    )\n\n    # The job_variables field in client and server schemas is named\n    # infra_overrides in the database.\n    job_variables = insert_values.pop(\"job_variables\", None)\n    if job_variables:\n        insert_values[\"infra_overrides\"] = job_variables\n\n    conflict_update_fields = deployment.dict(\n        shallow=True,\n        exclude_unset=True,\n        exclude={\"id\", \"created\", \"created_by\", \"schedules\", \"job_variables\"},\n    )\n    if job_variables:\n        conflict_update_fields[\"infra_overrides\"] = job_variables\n\n    insert_stmt = (\n        db.insert(db.Deployment)\n        .values(**insert_values)\n        .on_conflict_do_update(\n            index_elements=db.deployment_unique_upsert_columns,\n            set_={**conflict_update_fields},\n        )\n    )\n\n    await session.execute(insert_stmt)\n\n    # Get the id of the deployment we just created or updated\n    result = await session.execute(\n        sa.select(db.Deployment.id).where(\n            sa.and_(\n                db.Deployment.flow_id == deployment.flow_id,\n                db.Deployment.name == deployment.name,\n            )\n        )\n    )\n    deployment_id = result.scalar_one_or_none()\n\n    if not deployment_id:\n        return None\n\n    # Because this was possibly an upsert, we need to delete any existing\n    # schedules and any runs from the old deployment.\n\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=True\n    )\n\n    await delete_schedules_for_deployment(session=session, deployment_id=deployment_id)\n\n    if schedules:\n        await create_deployment_schedules(\n            session=session,\n            deployment_id=deployment_id,\n            schedules=[\n                schemas.actions.DeploymentScheduleCreate(\n                    schedule=schedule.schedule,\n                    active=schedule.active,  # type: ignore[call-arg]\n                )\n                for schedule in schedules\n            ],\n        )\n\n    query = (\n        sa.select(db.Deployment)\n        .where(\n            sa.and_(\n                db.Deployment.flow_id == deployment.flow_id,\n                db.Deployment.name == deployment.name,\n            )\n        )\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.create_deployment_schedules","title":"<code>create_deployment_schedules</code>  <code>async</code>","text":"<p>Creates a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <code>schedules</code> <code>List[DeploymentScheduleCreate]</code> <p>a list of deployment schedule create actions</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def create_deployment_schedules(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    schedules: List[schemas.actions.DeploymentScheduleCreate],\n) -&gt; List[schemas.core.DeploymentSchedule]:\n    \"\"\"\n    Creates a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n        schedules: a list of deployment schedule create actions\n    \"\"\"\n\n    schedules_with_deployment_id = []\n    for schedule in schedules:\n        data = schedule.dict()\n        data[\"deployment_id\"] = deployment_id\n        schedules_with_deployment_id.append(data)\n\n    models = [\n        db.DeploymentSchedule(**schedule) for schedule in schedules_with_deployment_id\n    ]\n    session.add_all(models)\n    await session.flush()\n\n    return [schemas.core.DeploymentSchedule.from_orm(m) for m in models]\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_deployment","title":"<code>delete_deployment</code>  <code>async</code>","text":"<p>Delete a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the deployment was deleted</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a deployment by id.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        bool: whether or not the deployment was deleted\n    \"\"\"\n\n    # delete scheduled runs, both auto- and user- created.\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=False\n    )\n\n    result = await session.execute(\n        delete(db.Deployment).where(db.Deployment.id == deployment_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_deployment_schedule","title":"<code>delete_deployment_schedule</code>  <code>async</code>","text":"<p>Deletes a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_schedule_id</code> <code>UUID</code> <p>a deployment schedule id</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_deployment_schedule(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_id: UUID,\n) -&gt; bool:\n    \"\"\"\n    Deletes a deployment schedule.\n\n    Args:\n        session: A database session\n        deployment_schedule_id: a deployment schedule id\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.DeploymentSchedule).where(\n            sa.and_(\n                db.DeploymentSchedule.id == deployment_schedule_id,\n                db.DeploymentSchedule.deployment_id == deployment_id,\n            )\n        )\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.delete_schedules_for_deployment","title":"<code>delete_schedules_for_deployment</code>  <code>async</code>","text":"<p>Deletes a deployment schedule.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def delete_schedules_for_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Deletes a deployment schedule.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n    \"\"\"\n\n    result = await session.execute(\n        sa.delete(db.DeploymentSchedule).where(\n            db.DeploymentSchedule.deployment_id == deployment_id\n        )\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment","title":"<code>read_deployment</code>  <code>async</code>","text":"<p>Reads a deployment by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment(\n    db: PrefectDBInterface, session: AsyncSession, deployment_id: UUID\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Reads a deployment by id.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        db.Deployment: the deployment\n    \"\"\"\n\n    return await session.get(db.Deployment, deployment_id)\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment_by_name","title":"<code>read_deployment_by_name</code>  <code>async</code>","text":"<p>Reads a deployment by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a deployment name</p> required <code>flow_name</code> <code>str</code> <p>the name of the flow the deployment belongs to</p> required <p>Returns:</p> Type Description <code>Optional[ORMDeployment]</code> <p>db.Deployment: the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment_by_name(\n    db: PrefectDBInterface, session: AsyncSession, name: str, flow_name: str\n) -&gt; Optional[\"ORMDeployment\"]:\n    \"\"\"Reads a deployment by name.\n\n    Args:\n        session: A database session\n        name: a deployment name\n        flow_name: the name of the flow the deployment belongs to\n\n    Returns:\n        db.Deployment: the deployment\n    \"\"\"\n\n    result = await session.execute(\n        select(db.Deployment)\n        .join(db.Flow, db.Deployment.flow_id == db.Flow.id)\n        .where(\n            sa.and_(\n                db.Flow.name == flow_name,\n                db.Deployment.name == name,\n            )\n        )\n        .limit(1)\n    )\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployment_schedules","title":"<code>read_deployment_schedules</code>  <code>async</code>","text":"<p>Reads a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_id</code> <code>UUID</code> <p>a deployment id</p> required <p>Returns:</p> Type Description <code>List[DeploymentSchedule]</code> <p>list[schemas.core.DeploymentSchedule]: the deployment's schedules</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployment_schedules(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_filter: Optional[\n        schemas.filters.DeploymentScheduleFilter\n    ] = None,\n) -&gt; List[schemas.core.DeploymentSchedule]:\n    \"\"\"\n    Reads a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_id: a deployment id\n\n    Returns:\n        list[schemas.core.DeploymentSchedule]: the deployment's schedules\n    \"\"\"\n\n    query = (\n        sa.select(db.DeploymentSchedule)\n        .where(db.DeploymentSchedule.deployment_id == deployment_id)\n        .order_by(db.DeploymentSchedule.updated.desc())\n    )\n\n    if deployment_schedule_filter:\n        query = query.where(deployment_schedule_filter.as_sql_filter(db))\n\n    result = await session.execute(query)\n\n    return [schemas.core.DeploymentSchedule.from_orm(s) for s in result.scalars().all()]\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.read_deployments","title":"<code>read_deployments</code>  <code>async</code>","text":"<p>Read deployments.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>flow_filter</code> <code>FlowFilter</code> <p>only select deployments whose flows match these criteria</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select deployments whose flow runs match these criteria</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select deployments whose task runs match these criteria</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select deployment that match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>WorkPoolFilter</code> <p>only select deployments whose work pools match these criteria</p> <code>None</code> <code>work_queue_filter</code> <code>WorkQueueFilter</code> <p>only select deployments whose work pool queues match these criteria</p> <code>None</code> <code>sort</code> <code>DeploymentSort</code> <p>the sort criteria for selected deployments. Defaults to <code>name</code> ASC.</p> <code>NAME_ASC</code> <p>Returns:</p> Type Description <code>Sequence[ORMDeployment]</code> <p>List[db.Deployment]: deployments</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def read_deployments(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    offset: int = None,\n    limit: int = None,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n    sort: schemas.sorting.DeploymentSort = schemas.sorting.DeploymentSort.NAME_ASC,\n) -&gt; Sequence[\"ORMDeployment\"]:\n    \"\"\"\n    Read deployments.\n\n    Args:\n        session: A database session\n        offset: Query offset\n        limit: Query limit\n        flow_filter: only select deployments whose flows match these criteria\n        flow_run_filter: only select deployments whose flow runs match these criteria\n        task_run_filter: only select deployments whose task runs match these criteria\n        deployment_filter: only select deployment that match these filters\n        work_pool_filter: only select deployments whose work pools match these criteria\n        work_queue_filter: only select deployments whose work pool queues match these criteria\n        sort: the sort criteria for selected deployments. Defaults to `name` ASC.\n\n    Returns:\n        List[db.Deployment]: deployments\n    \"\"\"\n\n    query = select(db.Deployment).order_by(sort.as_sql_sort(db=db))\n\n    query = await _apply_deployment_filters(\n        query=query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.schedule_runs","title":"<code>schedule_runs</code>  <code>async</code>","text":"<p>Schedule flow runs for a deployment</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment_id</code> <code>UUID</code> <p>the id of the deployment to schedule</p> required <code>start_time</code> <code>datetime</code> <p>the time from which to start scheduling runs</p> <code>None</code> <code>end_time</code> <code>datetime</code> <p>runs will be scheduled until at most this time</p> <code>None</code> <code>min_time</code> <code>timedelta</code> <p>runs will be scheduled until at least this far in the future</p> <code>None</code> <code>min_runs</code> <code>int</code> <p>a minimum amount of runs to schedule</p> <code>None</code> <code>max_runs</code> <code>int</code> <p>a maximum amount of runs to schedule</p> <code>None</code> <p>This function will generate the minimum number of runs that satisfy the min and max times, and the min and max counts. Specifically, the following order will be respected.</p> <pre><code>- Runs will be generated starting on or after the `start_time`\n- No more than `max_runs` runs will be generated\n- No runs will be generated after `end_time` is reached\n- At least `min_runs` runs will be generated\n- Runs will be generated until at least `start_time` + `min_time` is reached\n</code></pre> <p>Returns:</p> Type Description <code>List[UUID]</code> <p>a list of flow run ids scheduled for the deployment</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>async def schedule_runs(\n    session: AsyncSession,\n    deployment_id: UUID,\n    start_time: datetime.datetime = None,\n    end_time: datetime.datetime = None,\n    min_time: datetime.timedelta = None,\n    min_runs: int = None,\n    max_runs: int = None,\n    auto_scheduled: bool = True,\n) -&gt; List[UUID]:\n    \"\"\"\n    Schedule flow runs for a deployment\n\n    Args:\n        session: a database session\n        deployment_id: the id of the deployment to schedule\n        start_time: the time from which to start scheduling runs\n        end_time: runs will be scheduled until at most this time\n        min_time: runs will be scheduled until at least this far in the future\n        min_runs: a minimum amount of runs to schedule\n        max_runs: a maximum amount of runs to schedule\n\n    This function will generate the minimum number of runs that satisfy the min\n    and max times, and the min and max counts. Specifically, the following order\n    will be respected.\n\n        - Runs will be generated starting on or after the `start_time`\n        - No more than `max_runs` runs will be generated\n        - No runs will be generated after `end_time` is reached\n        - At least `min_runs` runs will be generated\n        - Runs will be generated until at least `start_time` + `min_time` is reached\n\n    Returns:\n        a list of flow run ids scheduled for the deployment\n    \"\"\"\n    if min_runs is None:\n        min_runs = PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS.value()\n    if max_runs is None:\n        max_runs = PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS.value()\n    if start_time is None:\n        start_time = pendulum.now(\"UTC\")\n    if end_time is None:\n        end_time = start_time + (\n            PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME.value()\n        )\n    if min_time is None:\n        min_time = PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME.value()\n\n    start_time = pendulum.instance(start_time)\n    end_time = pendulum.instance(end_time)\n\n    runs = await _generate_scheduled_flow_runs(\n        session=session,\n        deployment_id=deployment_id,\n        start_time=start_time,\n        end_time=end_time,\n        min_time=min_time,\n        min_runs=min_runs,\n        max_runs=max_runs,\n        auto_scheduled=auto_scheduled,\n    )\n    return await _insert_scheduled_flow_runs(session=session, runs=runs)\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.update_deployment","title":"<code>update_deployment</code>  <code>async</code>","text":"<p>Updates a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>deployment_id</code> <code>UUID</code> <p>the ID of the deployment to modify</p> required <code>deployment</code> <code>DeploymentUpdate</code> <p>changes to a deployment model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether the deployment was updated</p> Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def update_deployment(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment: schemas.actions.DeploymentUpdate,\n) -&gt; bool:\n    \"\"\"Updates a deployment.\n\n    Args:\n        session: a database session\n        deployment_id: the ID of the deployment to modify\n        deployment: changes to a deployment model\n\n    Returns:\n        bool: whether the deployment was updated\n\n    \"\"\"\n\n    from prefect.server.api.workers import WorkerLookups\n\n    schedules = deployment.schedules\n\n    # exclude_unset=True allows us to only update values provided by\n    # the user, ignoring any defaults on the model\n    update_data = deployment.dict(\n        shallow=True,\n        exclude_unset=True,\n        exclude={\"work_pool_name\"},\n    )\n\n    # The job_variables field in client and server schemas is named\n    # infra_overrides in the database.\n    job_variables = update_data.pop(\"job_variables\", None)\n    if job_variables:\n        update_data[\"infra_overrides\"] = job_variables\n\n    should_update_schedules = update_data.pop(\"schedules\", None) is not None\n\n    if deployment.work_pool_name and deployment.work_queue_name:\n        # If a specific pool name/queue name combination was provided, get the\n        # ID for that work pool queue.\n        update_data[\n            \"work_queue_id\"\n        ] = await WorkerLookups()._get_work_queue_id_from_name(\n            session=session,\n            work_pool_name=deployment.work_pool_name,\n            work_queue_name=deployment.work_queue_name,\n            create_queue_if_not_found=True,\n        )\n    elif deployment.work_pool_name:\n        # If just a pool name was provided, get the ID for its default\n        # work pool queue.\n        update_data[\n            \"work_queue_id\"\n        ] = await WorkerLookups()._get_default_work_queue_id_from_work_pool_name(\n            session=session,\n            work_pool_name=deployment.work_pool_name,\n        )\n    elif deployment.work_queue_name:\n        # If just a queue name was provided, ensure the queue exists and\n        # get its ID.\n        work_queue = await models.work_queues.ensure_work_queue_exists(\n            session=session, name=update_data[\"work_queue_name\"]\n        )\n        update_data[\"work_queue_id\"] = work_queue.id\n\n    if \"is_schedule_active\" in update_data:\n        update_data[\"paused\"] = not update_data[\"is_schedule_active\"]\n\n    update_stmt = (\n        sa.update(db.Deployment)\n        .where(db.Deployment.id == deployment_id)\n        .values(**update_data)\n    )\n    result = await session.execute(update_stmt)\n\n    # delete any auto scheduled runs that would have reflected the old deployment config\n    await _delete_scheduled_runs(\n        session=session, deployment_id=deployment_id, auto_scheduled_only=True\n    )\n\n    if should_update_schedules:\n        # If schedules were provided, remove the existing schedules and\n        # replace them with the new ones.\n        await delete_schedules_for_deployment(\n            session=session, deployment_id=deployment_id\n        )\n        await create_deployment_schedules(\n            session=session,\n            deployment_id=deployment_id,\n            schedules=[\n                schemas.actions.DeploymentScheduleCreate(\n                    schedule=schedule.schedule,\n                    active=schedule.active,  # type: ignore[call-arg]\n                )\n                for schedule in schedules\n            ],\n        )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/deployments/#prefect.server.models.deployments.update_deployment_schedule","title":"<code>update_deployment_schedule</code>  <code>async</code>","text":"<p>Updates a deployment's schedules.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>deployment_schedule_id</code> <code>UUID</code> <p>a deployment schedule id</p> required <code>schedule</code> <code>DeploymentScheduleUpdate</code> <p>a deployment schedule update action</p> required Source code in <code>prefect/server/models/deployments.py</code> <pre><code>@db_injector\nasync def update_deployment_schedule(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    deployment_id: UUID,\n    deployment_schedule_id: UUID,\n    schedule: schemas.actions.DeploymentScheduleUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a deployment's schedules.\n\n    Args:\n        session: A database session\n        deployment_schedule_id: a deployment schedule id\n        schedule: a deployment schedule update action\n    \"\"\"\n\n    result = await session.execute(\n        sa.update(db.DeploymentSchedule)\n        .where(\n            sa.and_(\n                db.DeploymentSchedule.id == deployment_schedule_id,\n                db.DeploymentSchedule.deployment_id == deployment_id,\n            )\n        )\n        .values(**schedule.dict(exclude_none=True))\n    )\n\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/","title":"server.models.flow_run_states","text":""},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states","title":"<code>prefect.server.models.flow_run_states</code>","text":"<p>Functions for interacting with flow run state ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.delete_flow_run_state","title":"<code>delete_flow_run_state</code>  <code>async</code>","text":"<p>Delete a flow run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_state_id</code> <code>UUID</code> <p>a flow run state id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow run state was deleted</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def delete_flow_run_state(\n    session: sa.orm.Session, flow_run_state_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a flow run state by id.\n\n    Args:\n        session: A database session\n        flow_run_state_id: a flow run state id\n\n    Returns:\n        bool: whether or not the flow run state was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.FlowRunState).where(db.FlowRunState.id == flow_run_state_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.read_flow_run_state","title":"<code>read_flow_run_state</code>  <code>async</code>","text":"<p>Reads a flow run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_state_id</code> <code>UUID</code> <p>a flow run state id</p> required <p>Returns:</p> Type Description <p>db.FlowRunState: the flow state</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def read_flow_run_state(\n    session: sa.orm.Session, flow_run_state_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a flow run state by id.\n\n    Args:\n        session: A database session\n        flow_run_state_id: a flow run state id\n\n    Returns:\n        db.FlowRunState: the flow state\n    \"\"\"\n\n    return await session.get(db.FlowRunState, flow_run_state_id)\n</code></pre>"},{"location":"api-ref/server/models/flow_run_states/#prefect.server.models.flow_run_states.read_flow_run_states","title":"<code>read_flow_run_states</code>  <code>async</code>","text":"<p>Reads flow runs states for a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id</p> required <p>Returns:</p> Type Description <p>List[db.FlowRunState]: the flow run states</p> Source code in <code>prefect/server/models/flow_run_states.py</code> <pre><code>@inject_db\nasync def read_flow_run_states(\n    session: sa.orm.Session, flow_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads flow runs states for a flow run.\n\n    Args:\n        session: A database session\n        flow_run_id: the flow run id\n\n    Returns:\n        List[db.FlowRunState]: the flow run states\n    \"\"\"\n\n    query = (\n        select(db.FlowRunState)\n        .filter_by(flow_run_id=flow_run_id)\n        .order_by(db.FlowRunState.timestamp)\n    )\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/","title":"server.models.flow_runs","text":""},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs","title":"<code>prefect.server.models.flow_runs</code>","text":"<p>Functions for interacting with flow run ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.count_flow_runs","title":"<code>count_flow_runs</code>  <code>async</code>","text":"<p>Count flow runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count flow runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count flow runs that match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count flow runs whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count flow runs whose deployments match these filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>count of flow runs</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def count_flow_runs(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count flow runs.\n\n    Args:\n        session: a database session\n        flow_filter: only count flow runs whose flows match these filters\n        flow_run_filter: only count flow runs that match these filters\n        task_run_filter: only count flow runs whose task runs match these filters\n        deployment_filter: only count flow runs whose deployments match these filters\n\n    Returns:\n        int: count of flow runs\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.FlowRun)\n\n    query = await _apply_flow_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.create_flow_run","title":"<code>create_flow_run</code>  <code>async</code>","text":"<p>Creates a new flow run.</p> <p>If the provided flow run has a state attached, it will also be created.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run</code> <code>FlowRun</code> <p>a flow run model</p> required <p>Returns:</p> Type Description <code>ORMFlowRun</code> <p>db.FlowRun: the newly-created flow run</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def create_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run: schemas.core.FlowRun,\n    orchestration_parameters: Optional[dict] = None,\n) -&gt; \"ORMFlowRun\":\n    \"\"\"Creates a new flow run.\n\n    If the provided flow run has a state attached, it will also be created.\n\n    Args:\n        session: a database session\n        flow_run: a flow run model\n\n    Returns:\n        db.FlowRun: the newly-created flow run\n    \"\"\"\n    now = pendulum.now(\"UTC\")\n\n    flow_run_dict = dict(\n        **flow_run.dict(\n            shallow=True,\n            exclude={\n                \"created\",\n                \"state\",\n                \"estimated_run_time\",\n                \"estimated_start_time_delta\",\n            },\n            exclude_unset=True,\n        ),\n        created=now,\n    )\n\n    # if no idempotency key was provided, create the run directly\n    if not flow_run.idempotency_key:\n        model = db.FlowRun(**flow_run_dict)\n        session.add(model)\n        await session.flush()\n\n    # otherwise let the database take care of enforcing idempotency\n    else:\n        insert_stmt = (\n            db.insert(db.FlowRun)\n            .values(**flow_run_dict)\n            .on_conflict_do_nothing(\n                index_elements=db.flow_run_unique_upsert_columns,\n            )\n        )\n        await session.execute(insert_stmt)\n\n        # read the run to see if idempotency was applied or not\n        query = (\n            sa.select(db.FlowRun)\n            .where(\n                sa.and_(\n                    db.FlowRun.flow_id == flow_run.flow_id,\n                    db.FlowRun.idempotency_key == flow_run.idempotency_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n            .options(\n                selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n            )\n        )\n        result = await session.execute(query)\n        model = result.scalar()\n\n    # if the flow run was created in this function call then we need to set the\n    # state. If it was created idempotently, the created time won't match.\n    if model.created == now and flow_run.state:\n        await models.flow_runs.set_flow_run_state(\n            session=session,\n            flow_run_id=model.id,\n            state=flow_run.state,\n            force=True,\n            orchestration_parameters=orchestration_parameters,\n        )\n    return model\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.delete_flow_run","title":"<code>delete_flow_run</code>  <code>async</code>","text":"<p>Delete a flow run by flow_run_id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>a flow run id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow run was deleted</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def delete_flow_run(\n    db: PrefectDBInterface, session: AsyncSession, flow_run_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a flow run by flow_run_id.\n\n    Args:\n        session: A database session\n        flow_run_id: a flow run id\n\n    Returns:\n        bool: whether or not the flow run was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.FlowRun).where(db.FlowRun.id == flow_run_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_run","title":"<code>read_flow_run</code>  <code>async</code>","text":"<p>Reads a flow run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>a flow run id</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlowRun]</code> <p>db.FlowRun: the flow run</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    for_update: bool = False,\n) -&gt; Optional[\"ORMFlowRun\"]:\n    \"\"\"\n    Reads a flow run by id.\n\n    Args:\n        session: A database session\n        flow_run_id: a flow run id\n\n    Returns:\n        db.FlowRun: the flow run\n    \"\"\"\n    select = (\n        sa.select(db.FlowRun)\n        .where(db.FlowRun.id == flow_run_id)\n        .options(\n            selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n        )\n    )\n\n    if for_update:\n        select = select.with_for_update()\n\n    result = await session.execute(select)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_run_graph","title":"<code>read_flow_run_graph</code>  <code>async</code>","text":"<p>Given a flow run, return the graph of it's task and subflow runs. If a <code>since</code> datetime is provided, only return items that may have changed since that time.</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_run_graph(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    since: datetime.datetime = datetime.datetime.min,\n) -&gt; Graph:\n    \"\"\"Given a flow run, return the graph of it's task and subflow runs. If a `since`\n    datetime is provided, only return items that may have changed since that time.\"\"\"\n    return await db.queries.flow_run_graph_v2(\n        db=db,\n        session=session,\n        flow_run_id=flow_run_id,\n        since=since,\n        max_nodes=PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES.value(),\n        max_artifacts=PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS.value(),\n    )\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_flow_runs","title":"<code>read_flow_runs</code>  <code>async</code>","text":"<p>Read flow runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>columns</code> <code>List</code> <p>a list of the flow run ORM columns to load, for performance</p> <code>None</code> <code>flow_filter</code> <code>FlowFilter</code> <p>only select flow runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select flow runs whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select flow runs whose deployments match these filters</p> <code>None</code> <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>sort</code> <code>FlowRunSort</code> <p>Query sort</p> <code>ID_DESC</code> <p>Returns:</p> Type Description <code>Sequence[ORMFlowRun]</code> <p>List[db.FlowRun]: flow runs</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def read_flow_runs(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    columns: List = None,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    work_pool_filter: schemas.filters.WorkPoolFilter = None,\n    work_queue_filter: schemas.filters.WorkQueueFilter = None,\n    offset: int = None,\n    limit: int = None,\n    sort: schemas.sorting.FlowRunSort = schemas.sorting.FlowRunSort.ID_DESC,\n) -&gt; Sequence[\"ORMFlowRun\"]:\n    \"\"\"\n    Read flow runs.\n\n    Args:\n        session: a database session\n        columns: a list of the flow run ORM columns to load, for performance\n        flow_filter: only select flow runs whose flows match these filters\n        flow_run_filter: only select flow runs match these filters\n        task_run_filter: only select flow runs whose task runs match these filters\n        deployment_filter: only select flow runs whose deployments match these filters\n        offset: Query offset\n        limit: Query limit\n        sort: Query sort\n\n    Returns:\n        List[db.FlowRun]: flow runs\n    \"\"\"\n    query = (\n        select(db.FlowRun)\n        .order_by(sort.as_sql_sort(db))\n        .options(\n            selectinload(db.FlowRun.work_queue).selectinload(db.WorkQueue.work_pool)\n        )\n    )\n\n    if columns:\n        query = query.options(load_only(*columns))\n\n    query = await _apply_flow_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n        work_queue_filter=work_queue_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.read_task_run_dependencies","title":"<code>read_task_run_dependencies</code>  <code>async</code>","text":"<p>Get a task run dependency map for a given flow run.</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>async def read_task_run_dependencies(\n    session: AsyncSession,\n    flow_run_id: UUID,\n) -&gt; List[DependencyResult]:\n    \"\"\"\n    Get a task run dependency map for a given flow run.\n    \"\"\"\n    flow_run = await models.flow_runs.read_flow_run(\n        session=session, flow_run_id=flow_run_id\n    )\n    if not flow_run:\n        raise ObjectNotFoundError(f\"Flow run with id {flow_run_id} not found\")\n\n    task_runs = await models.task_runs.read_task_runs(\n        session=session,\n        flow_run_filter=schemas.filters.FlowRunFilter(\n            id=schemas.filters.FlowRunFilterId(any_=[flow_run_id])\n        ),\n    )\n\n    dependency_graph = []\n\n    for task_run in task_runs:\n        inputs = list(set(chain(*task_run.task_inputs.values())))\n        untrackable_result_status = (\n            False\n            if task_run.state is None\n            else task_run.state.state_details.untrackable_result\n        )\n        dependency_graph.append(\n            {\n                \"id\": task_run.id,\n                \"upstream_dependencies\": inputs,\n                \"state\": task_run.state,\n                \"expected_start_time\": task_run.expected_start_time,\n                \"name\": task_run.name,\n                \"start_time\": task_run.start_time,\n                \"end_time\": task_run.end_time,\n                \"total_run_time\": task_run.total_run_time,\n                \"estimated_run_time\": task_run.estimated_run_time,\n                \"untrackable_result\": untrackable_result_status,\n            }\n        )\n\n    return dependency_graph\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.set_flow_run_state","title":"<code>set_flow_run_state</code>  <code>async</code>","text":"<p>Creates a new orchestrated flow run state.</p> <p>Setting a new state on a run is the one of the principal actions that is governed by Prefect's orchestration logic. Setting a new run state will not guarantee creation, but instead trigger orchestration rules to govern the proposed <code>state</code> input. If the state is considered valid, it will be written to the database. Otherwise, a it's possible a different state, or no state, will be created. A <code>force</code> flag is supplied to bypass a subset of orchestration logic.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id</p> required <code>state</code> <code>State</code> <p>a flow run state model</p> required <code>force</code> <code>bool</code> <p>if False, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>OrchestrationResult object</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>async def set_flow_run_state(\n    session: AsyncSession,\n    flow_run_id: UUID,\n    state: schemas.states.State,\n    force: bool = False,\n    flow_policy: BaseOrchestrationPolicy = None,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Creates a new orchestrated flow run state.\n\n    Setting a new state on a run is the one of the principal actions that is governed by\n    Prefect's orchestration logic. Setting a new run state will not guarantee creation,\n    but instead trigger orchestration rules to govern the proposed `state` input. If\n    the state is considered valid, it will be written to the database. Otherwise, a\n    it's possible a different state, or no state, will be created. A `force` flag is\n    supplied to bypass a subset of orchestration logic.\n\n    Args:\n        session: a database session\n        flow_run_id: the flow run id\n        state: a flow run state model\n        force: if False, orchestration rules will be applied that may alter or prevent\n            the state transition. If True, orchestration rules are not applied.\n\n    Returns:\n        OrchestrationResult object\n    \"\"\"\n\n    # load the flow run\n    run = await models.flow_runs.read_flow_run(\n        session=session,\n        flow_run_id=flow_run_id,\n        # Lock the row to prevent orchestration race conditions\n        for_update=True,\n    )\n\n    if not run:\n        raise ObjectNotFoundError(f\"Flow run with id {flow_run_id} not found\")\n\n    initial_state = run.state.as_state() if run.state else None\n    initial_state_type = initial_state.type if initial_state else None\n    proposed_state_type = state.type if state else None\n    intended_transition = (initial_state_type, proposed_state_type)\n\n    if force or flow_policy is None:\n        flow_policy = MinimalFlowPolicy\n\n    orchestration_rules = flow_policy.compile_transition_rules(*intended_transition)\n    global_rules = GlobalFlowPolicy.compile_transition_rules(*intended_transition)\n\n    context = FlowOrchestrationContext(\n        session=session,\n        run=run,\n        initial_state=initial_state,\n        proposed_state=state,\n    )\n\n    if orchestration_parameters is not None:\n        context.parameters = orchestration_parameters\n\n    # apply orchestration rules and create the new flow run state\n    async with contextlib.AsyncExitStack() as stack:\n        for rule in orchestration_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        for rule in global_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        await context.validate_proposed_state()\n\n    if context.orchestration_error is not None:\n        raise context.orchestration_error\n\n    result = OrchestrationResult(\n        state=context.validated_state,\n        status=context.response_status,\n        details=context.response_details,\n    )\n\n    # if a new state is being set (either ACCEPTED from user or REJECTED\n    # and set by the server), check for any notification policies\n    if result.status in (SetStateStatus.ACCEPT, SetStateStatus.REJECT):\n        await models.flow_run_notification_policies.queue_flow_run_notifications(\n            session=session, flow_run=run\n        )\n\n    return result\n</code></pre>"},{"location":"api-ref/server/models/flow_runs/#prefect.server.models.flow_runs.update_flow_run","title":"<code>update_flow_run</code>  <code>async</code>","text":"<p>Updates a flow run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_run_id</code> <code>UUID</code> <p>the flow run id to update</p> required <code>flow_run</code> <code>FlowRunUpdate</code> <p>a flow run model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/flow_runs.py</code> <pre><code>@db_injector\nasync def update_flow_run(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_run_id: UUID,\n    flow_run: schemas.actions.FlowRunUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a flow run.\n\n    Args:\n        session: a database session\n        flow_run_id: the flow run id to update\n        flow_run: a flow run model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.FlowRun)\n        .where(db.FlowRun.id == flow_run_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**flow_run.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flows/","title":"server.models.flows","text":""},{"location":"api-ref/server/models/flows/#prefect.server.models.flows","title":"<code>prefect.server.models.flows</code>","text":"<p>Functions for interacting with flow ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.count_flows","title":"<code>count_flows</code>  <code>async</code>","text":"<p>Count flows.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>Union[FlowFilter, None]</code> <p>only count flows that match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Union[FlowRunFilter, None]</code> <p>only count flows whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Union[TaskRunFilter, None]</code> <p>only count flows whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Union[DeploymentFilter, None]</code> <p>only count flows whose deployments match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>Union[WorkPoolFilter, None]</code> <p>only count flows whose work pools match these filters</p> <code>None</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>count of flows</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def count_flows(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: Union[schemas.filters.FlowFilter, None] = None,\n    flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None,\n    task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None,\n    deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None,\n    work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None,\n) -&gt; int:\n    \"\"\"\n    Count flows.\n\n    Args:\n        session: A database session\n        flow_filter: only count flows that match these filters\n        flow_run_filter: only count flows whose flow runs match these filters\n        task_run_filter: only count flows whose task runs match these filters\n        deployment_filter: only count flows whose deployments match these filters\n        work_pool_filter: only count flows whose work pools match these filters\n\n    Returns:\n        int: count of flows\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.Flow)\n\n    query = await _apply_flow_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n    )\n\n    result = await session.execute(query)\n    return result.scalar_one()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.create_flow","title":"<code>create_flow</code>  <code>async</code>","text":"<p>Creates a new flow.</p> <p>If a flow with the same name already exists, the existing flow is returned.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow</code> <code>Flow</code> <p>a flow model</p> required <p>Returns:</p> Type Description <code>ORMFlow</code> <p>db.Flow: the newly-created or existing flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def create_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow: schemas.core.Flow\n) -&gt; \"ORMFlow\":\n    \"\"\"\n    Creates a new flow.\n\n    If a flow with the same name already exists, the existing flow is returned.\n\n    Args:\n        session: a database session\n        flow: a flow model\n\n    Returns:\n        db.Flow: the newly-created or existing flow\n    \"\"\"\n\n    insert_stmt = (\n        db.insert(db.Flow)\n        .values(**flow.dict(shallow=True, exclude_unset=True))\n        .on_conflict_do_nothing(\n            index_elements=db.flow_unique_upsert_columns,\n        )\n    )\n    await session.execute(insert_stmt)\n\n    query = (\n        sa.select(db.Flow)\n        .where(\n            db.Flow.name == flow.name,\n        )\n        .limit(1)\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    model = result.scalar_one()\n    return model\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.delete_flow","title":"<code>delete_flow</code>  <code>async</code>","text":"<p>Delete a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_id</code> <code>UUID</code> <p>a flow id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the flow was deleted</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def delete_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow_id: UUID\n) -&gt; bool:\n    \"\"\"\n    Delete a flow by id.\n\n    Args:\n        session: A database session\n        flow_id: a flow id\n\n    Returns:\n        bool: whether or not the flow was deleted\n    \"\"\"\n\n    result = await session.execute(delete(db.Flow).where(db.Flow.id == flow_id))\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flow","title":"<code>read_flow</code>  <code>async</code>","text":"<p>Reads a flow by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_id</code> <code>UUID</code> <p>a flow id</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlow]</code> <p>db.Flow: the flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flow(\n    db: PrefectDBInterface, session: AsyncSession, flow_id: UUID\n) -&gt; Optional[\"ORMFlow\"]:\n    \"\"\"\n    Reads a flow by id.\n\n    Args:\n        session: A database session\n        flow_id: a flow id\n\n    Returns:\n        db.Flow: the flow\n    \"\"\"\n    return await session.get(db.Flow, flow_id)\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flow_by_name","title":"<code>read_flow_by_name</code>  <code>async</code>","text":"<p>Reads a flow by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a flow name</p> required <p>Returns:</p> Type Description <code>Optional[ORMFlow]</code> <p>db.Flow: the flow</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flow_by_name(\n    db: PrefectDBInterface, session: AsyncSession, name: str\n) -&gt; Optional[\"ORMFlow\"]:\n    \"\"\"\n    Reads a flow by name.\n\n    Args:\n        session: A database session\n        name: a flow name\n\n    Returns:\n        db.Flow: the flow\n    \"\"\"\n\n    result = await session.execute(select(db.Flow).filter_by(name=name))\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.read_flows","title":"<code>read_flows</code>  <code>async</code>","text":"<p>Read multiple flows.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>A database session</p> required <code>flow_filter</code> <code>Union[FlowFilter, None]</code> <p>only select flows that match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Union[FlowRunFilter, None]</code> <p>only select flows whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Union[TaskRunFilter, None]</code> <p>only select flows whose task runs match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Union[DeploymentFilter, None]</code> <p>only select flows whose deployments match these filters</p> <code>None</code> <code>work_pool_filter</code> <code>Union[WorkPoolFilter, None]</code> <p>only select flows whose work pools match these filters</p> <code>None</code> <code>offset</code> <code>Union[int, None]</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>Union[int, None]</code> <p>Query limit</p> <code>None</code> <p>Returns:</p> Type Description <code>Sequence[ORMFlow]</code> <p>List[db.Flow]: flows</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def read_flows(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_filter: Union[schemas.filters.FlowFilter, None] = None,\n    flow_run_filter: Union[schemas.filters.FlowRunFilter, None] = None,\n    task_run_filter: Union[schemas.filters.TaskRunFilter, None] = None,\n    deployment_filter: Union[schemas.filters.DeploymentFilter, None] = None,\n    work_pool_filter: Union[schemas.filters.WorkPoolFilter, None] = None,\n    sort: schemas.sorting.FlowSort = schemas.sorting.FlowSort.NAME_ASC,\n    offset: Union[int, None] = None,\n    limit: Union[int, None] = None,\n) -&gt; Sequence[\"ORMFlow\"]:\n    \"\"\"\n    Read multiple flows.\n\n    Args:\n        session: A database session\n        flow_filter: only select flows that match these filters\n        flow_run_filter: only select flows whose flow runs match these filters\n        task_run_filter: only select flows whose task runs match these filters\n        deployment_filter: only select flows whose deployments match these filters\n        work_pool_filter: only select flows whose work pools match these filters\n        offset: Query offset\n        limit: Query limit\n\n    Returns:\n        List[db.Flow]: flows\n    \"\"\"\n\n    query = select(db.Flow).order_by(sort.as_sql_sort(db=db))\n\n    query = await _apply_flow_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        work_pool_filter=work_pool_filter,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/flows/#prefect.server.models.flows.update_flow","title":"<code>update_flow</code>  <code>async</code>","text":"<p>Updates a flow.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_id</code> <code>UUID</code> <p>the flow id to update</p> required <code>flow</code> <code>FlowUpdate</code> <p>a flow update model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/flows.py</code> <pre><code>@db_injector\nasync def update_flow(\n    db: PrefectDBInterface,\n    session: AsyncSession,\n    flow_id: UUID,\n    flow: schemas.actions.FlowUpdate,\n) -&gt; bool:\n    \"\"\"\n    Updates a flow.\n\n    Args:\n        session: a database session\n        flow_id: the flow id to update\n        flow: a flow update model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.Flow)\n        .where(db.Flow.id == flow_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**flow.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/","title":"server.models.saved_searches","text":""},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches","title":"<code>prefect.server.models.saved_searches</code>","text":"<p>Functions for interacting with saved search ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.create_saved_search","title":"<code>create_saved_search</code>  <code>async</code>","text":"<p>Upserts a SavedSearch.</p> <p>If a SavedSearch with the same name exists, all properties will be updated.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>saved_search</code> <code>SavedSearch</code> <p>a SavedSearch model</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the newly-created or updated SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def create_saved_search(\n    session: sa.orm.Session,\n    saved_search: schemas.core.SavedSearch,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Upserts a SavedSearch.\n\n    If a SavedSearch with the same name exists, all properties will be updated.\n\n    Args:\n        session (sa.orm.Session): a database session\n        saved_search (schemas.core.SavedSearch): a SavedSearch model\n\n    Returns:\n        db.SavedSearch: the newly-created or updated SavedSearch\n\n    \"\"\"\n\n    insert_stmt = (\n        db.insert(db.SavedSearch)\n        .values(**saved_search.dict(shallow=True, exclude_unset=True))\n        .on_conflict_do_update(\n            index_elements=db.saved_search_unique_upsert_columns,\n            set_=saved_search.dict(shallow=True, include={\"filters\"}),\n        )\n    )\n\n    await session.execute(insert_stmt)\n\n    query = (\n        sa.select(db.SavedSearch)\n        .where(\n            db.SavedSearch.name == saved_search.name,\n        )\n        .execution_options(populate_existing=True)\n    )\n    result = await session.execute(query)\n    model = result.scalar()\n\n    return model\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.delete_saved_search","title":"<code>delete_saved_search</code>  <code>async</code>","text":"<p>Delete a SavedSearch by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>saved_search_id</code> <code>str</code> <p>a SavedSearch id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the SavedSearch was deleted</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def delete_saved_search(\n    session: sa.orm.Session, saved_search_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a SavedSearch by id.\n\n    Args:\n        session (sa.orm.Session): A database session\n        saved_search_id (str): a SavedSearch id\n\n    Returns:\n        bool: whether or not the SavedSearch was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.SavedSearch).where(db.SavedSearch.id == saved_search_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_search","title":"<code>read_saved_search</code>  <code>async</code>","text":"<p>Reads a SavedSearch by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>saved_search_id</code> <code>str</code> <p>a SavedSearch id</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_search(\n    session: sa.orm.Session, saved_search_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a SavedSearch by id.\n\n    Args:\n        session (sa.orm.Session): A database session\n        saved_search_id (str): a SavedSearch id\n\n    Returns:\n        db.SavedSearch: the SavedSearch\n    \"\"\"\n\n    return await session.get(db.SavedSearch, saved_search_id)\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_search_by_name","title":"<code>read_saved_search_by_name</code>  <code>async</code>","text":"<p>Reads a SavedSearch by name.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>name</code> <code>str</code> <p>a SavedSearch name</p> required <p>Returns:</p> Type Description <p>db.SavedSearch: the SavedSearch</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_search_by_name(\n    session: sa.orm.Session, name: str, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a SavedSearch by name.\n\n    Args:\n        session (sa.orm.Session): A database session\n        name (str): a SavedSearch name\n\n    Returns:\n        db.SavedSearch: the SavedSearch\n    \"\"\"\n    result = await session.execute(\n        select(db.SavedSearch).where(db.SavedSearch.name == name).limit(1)\n    )\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/saved_searches/#prefect.server.models.saved_searches.read_saved_searches","title":"<code>read_saved_searches</code>  <code>async</code>","text":"<p>Read SavedSearches.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit(int)</code> <p>Query limit</p> required <p>Returns:</p> Type Description <p>List[db.SavedSearch]: SavedSearches</p> Source code in <code>prefect/server/models/saved_searches.py</code> <pre><code>@inject_db\nasync def read_saved_searches(\n    db: PrefectDBInterface,\n    session: sa.orm.Session,\n    offset: int = None,\n    limit: int = None,\n):\n    \"\"\"\n    Read SavedSearches.\n\n    Args:\n        session (sa.orm.Session): A database session\n        offset (int): Query offset\n        limit(int): Query limit\n\n    Returns:\n        List[db.SavedSearch]: SavedSearches\n    \"\"\"\n\n    query = select(db.SavedSearch).order_by(db.SavedSearch.name)\n\n    if offset is not None:\n        query = query.offset(offset)\n    if limit is not None:\n        query = query.limit(limit)\n\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/","title":"server.models.task_run_states","text":""},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states","title":"<code>prefect.server.models.task_run_states</code>","text":"<p>Functions for interacting with task run state ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.delete_task_run_state","title":"<code>delete_task_run_state</code>  <code>async</code>","text":"<p>Delete a task run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_state_id</code> <code>UUID</code> <p>a task run state id</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the task run state was deleted</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def delete_task_run_state(\n    session: sa.orm.Session, task_run_state_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a task run state by id.\n\n    Args:\n        session: A database session\n        task_run_state_id: a task run state id\n\n    Returns:\n        bool: whether or not the task run state was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.TaskRunState).where(db.TaskRunState.id == task_run_state_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.read_task_run_state","title":"<code>read_task_run_state</code>  <code>async</code>","text":"<p>Reads a task run state by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_state_id</code> <code>UUID</code> <p>a task run state id</p> required <p>Returns:</p> Type Description <p>db.TaskRunState: the task state</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def read_task_run_state(\n    session: sa.orm.Session, task_run_state_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads a task run state by id.\n\n    Args:\n        session: A database session\n        task_run_state_id: a task run state id\n\n    Returns:\n        db.TaskRunState: the task state\n    \"\"\"\n\n    return await session.get(db.TaskRunState, task_run_state_id)\n</code></pre>"},{"location":"api-ref/server/models/task_run_states/#prefect.server.models.task_run_states.read_task_run_states","title":"<code>read_task_run_states</code>  <code>async</code>","text":"<p>Reads task runs states for a task run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>A database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <p>Returns:</p> Type Description <p>List[db.TaskRunState]: the task run states</p> Source code in <code>prefect/server/models/task_run_states.py</code> <pre><code>@inject_db\nasync def read_task_run_states(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Reads task runs states for a task run.\n\n    Args:\n        session: A database session\n        task_run_id: the task run id\n\n    Returns:\n        List[db.TaskRunState]: the task run states\n    \"\"\"\n\n    query = (\n        select(db.TaskRunState)\n        .filter_by(task_run_id=task_run_id)\n        .order_by(db.TaskRunState.timestamp)\n    )\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/","title":"server.models.task_runs","text":""},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs","title":"<code>prefect.server.models.task_runs</code>","text":"<p>Functions for interacting with task run ORM objects. Intended for internal use by the Prefect REST API.</p>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.count_task_runs","title":"<code>count_task_runs</code>  <code>async</code>","text":"<p>Count task runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only count task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only count task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only count task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only count task runs whose deployments match these filters</p> <code>None</code> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def count_task_runs(\n    session: sa.orm.Session,\n    db: PrefectDBInterface,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n) -&gt; int:\n    \"\"\"\n    Count task runs.\n\n    Args:\n        session: a database session\n        flow_filter: only count task runs whose flows match these filters\n        flow_run_filter: only count task runs whose flow runs match these filters\n        task_run_filter: only count task runs that match these filters\n        deployment_filter: only count task runs whose deployments match these filters\n    Returns:\n        int: count of task runs\n    \"\"\"\n\n    query = select(sa.func.count(sa.text(\"*\"))).select_from(db.TaskRun)\n\n    query = await _apply_task_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        db=db,\n    )\n\n    result = await session.execute(query)\n    return result.scalar()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.count_task_runs_by_state","title":"<code>count_task_runs_by_state</code>  <code>async</code>","text":"<p>Count task runs by state.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>flow_filter</code> <code>Optional[FlowFilter]</code> <p>only count task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>Optional[FlowRunFilter]</code> <p>only count task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>Optional[TaskRunFilter]</code> <p>only count task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>Optional[DeploymentFilter]</code> <p>only count task runs whose deployments match these filters</p> <code>None</code> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>async def count_task_runs_by_state(\n    session: AsyncSession,\n    db: PrefectDBInterface,\n    flow_filter: Optional[schemas.filters.FlowFilter] = None,\n    flow_run_filter: Optional[schemas.filters.FlowRunFilter] = None,\n    task_run_filter: Optional[schemas.filters.TaskRunFilter] = None,\n    deployment_filter: Optional[schemas.filters.DeploymentFilter] = None,\n) -&gt; schemas.states.CountByState:\n    \"\"\"\n    Count task runs by state.\n\n    Args:\n        session: a database session\n        flow_filter: only count task runs whose flows match these filters\n        flow_run_filter: only count task runs whose flow runs match these filters\n        task_run_filter: only count task runs that match these filters\n        deployment_filter: only count task runs whose deployments match these filters\n    Returns:\n        schemas.states.CountByState: count of task runs by state\n    \"\"\"\n\n    base_query = (\n        select(\n            db.TaskRun.state_type,\n            sa.func.count(sa.text(\"*\")).label(\"count\"),\n        )\n        .select_from(db.TaskRun)\n        .group_by(db.TaskRun.state_type)\n    )\n\n    query = await _apply_task_run_filters(\n        base_query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n    )\n\n    result = await session.execute(query)\n\n    counts = schemas.states.CountByState()\n\n    for row in result:\n        setattr(counts, row.state_type, row.count)\n\n    return counts\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.create_task_run","title":"<code>create_task_run</code>  <code>async</code>","text":"<p>Creates a new task run.</p> <p>If a task run with the same flow_run_id, task_key, and dynamic_key already exists, the existing task run will be returned. If the provided task run has a state attached, it will also be created.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run</code> <code>TaskRun</code> <p>a task run model</p> required <p>Returns:</p> Type Description <p>db.TaskRun: the newly-created or existing task run</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def create_task_run(\n    session: sa.orm.Session,\n    task_run: schemas.core.TaskRun,\n    db: PrefectDBInterface,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n):\n    \"\"\"\n    Creates a new task run.\n\n    If a task run with the same flow_run_id, task_key, and dynamic_key already exists,\n    the existing task run will be returned. If the provided task run has a state\n    attached, it will also be created.\n\n    Args:\n        session: a database session\n        task_run: a task run model\n\n    Returns:\n        db.TaskRun: the newly-created or existing task run\n    \"\"\"\n\n    now = pendulum.now(\"UTC\")\n\n    # if a dynamic key exists, we need to guard against conflicts\n    if task_run.flow_run_id:\n        insert_stmt = (\n            db.insert(db.TaskRun)\n            .values(\n                created=now,\n                **task_run.dict(\n                    shallow=True, exclude={\"state\", \"created\"}, exclude_unset=True\n                ),\n            )\n            .on_conflict_do_nothing(\n                index_elements=db.task_run_unique_upsert_columns,\n            )\n        )\n        await session.execute(insert_stmt)\n\n        query = (\n            sa.select(db.TaskRun)\n            .where(\n                sa.and_(\n                    db.TaskRun.flow_run_id == task_run.flow_run_id,\n                    db.TaskRun.task_key == task_run.task_key,\n                    db.TaskRun.dynamic_key == task_run.dynamic_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n        )\n        result = await session.execute(query)\n        model = result.scalar()\n    else:\n        # Upsert on (task_key, dynamic_key) application logic.\n        query = (\n            sa.select(db.TaskRun)\n            .where(\n                sa.and_(\n                    db.TaskRun.flow_run_id.is_(None),\n                    db.TaskRun.task_key == task_run.task_key,\n                    db.TaskRun.dynamic_key == task_run.dynamic_key,\n                )\n            )\n            .limit(1)\n            .execution_options(populate_existing=True)\n        )\n\n        result = await session.execute(query)\n        model = result.scalar()\n\n        if model is None:\n            model = db.TaskRun(\n                created=now,\n                **task_run.dict(\n                    shallow=True, exclude={\"state\", \"created\"}, exclude_unset=True\n                ),\n                state=None,\n            )\n            session.add(model)\n            await session.flush()\n\n    if model.created == now and task_run.state:\n        await models.task_runs.set_task_run_state(\n            session=session,\n            task_run_id=model.id,\n            state=task_run.state,\n            force=True,\n            orchestration_parameters=orchestration_parameters,\n        )\n    return model\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.delete_task_run","title":"<code>delete_task_run</code>  <code>async</code>","text":"<p>Delete a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id to delete</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the task run was deleted</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def delete_task_run(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n) -&gt; bool:\n    \"\"\"\n    Delete a task run by id.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id to delete\n\n    Returns:\n        bool: whether or not the task run was deleted\n    \"\"\"\n\n    result = await session.execute(\n        delete(db.TaskRun).where(db.TaskRun.id == task_run_id)\n    )\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.read_task_run","title":"<code>read_task_run</code>  <code>async</code>","text":"<p>Read a task run by id.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <p>Returns:</p> Type Description <p>db.TaskRun: the task run</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def read_task_run(\n    session: sa.orm.Session, task_run_id: UUID, db: PrefectDBInterface\n):\n    \"\"\"\n    Read a task run by id.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id\n\n    Returns:\n        db.TaskRun: the task run\n    \"\"\"\n\n    model = await session.get(db.TaskRun, task_run_id)\n    return model\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.read_task_runs","title":"<code>read_task_runs</code>  <code>async</code>","text":"<p>Read task runs.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>flow_filter</code> <code>FlowFilter</code> <p>only select task runs whose flows match these filters</p> <code>None</code> <code>flow_run_filter</code> <code>FlowRunFilter</code> <p>only select task runs whose flow runs match these filters</p> <code>None</code> <code>task_run_filter</code> <code>TaskRunFilter</code> <p>only select task runs that match these filters</p> <code>None</code> <code>deployment_filter</code> <code>DeploymentFilter</code> <p>only select task runs whose deployments match these filters</p> <code>None</code> <code>offset</code> <code>int</code> <p>Query offset</p> <code>None</code> <code>limit</code> <code>int</code> <p>Query limit</p> <code>None</code> <code>sort</code> <code>TaskRunSort</code> <p>Query sort</p> <code>ID_DESC</code> <p>Returns:</p> Type Description <p>List[db.TaskRun]: the task runs</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def read_task_runs(\n    session: sa.orm.Session,\n    db: PrefectDBInterface,\n    flow_filter: schemas.filters.FlowFilter = None,\n    flow_run_filter: schemas.filters.FlowRunFilter = None,\n    task_run_filter: schemas.filters.TaskRunFilter = None,\n    deployment_filter: schemas.filters.DeploymentFilter = None,\n    offset: int = None,\n    limit: int = None,\n    sort: schemas.sorting.TaskRunSort = schemas.sorting.TaskRunSort.ID_DESC,\n):\n    \"\"\"\n    Read task runs.\n\n    Args:\n        session: a database session\n        flow_filter: only select task runs whose flows match these filters\n        flow_run_filter: only select task runs whose flow runs match these filters\n        task_run_filter: only select task runs that match these filters\n        deployment_filter: only select task runs whose deployments match these filters\n        offset: Query offset\n        limit: Query limit\n        sort: Query sort\n\n    Returns:\n        List[db.TaskRun]: the task runs\n    \"\"\"\n\n    query = select(db.TaskRun).order_by(sort.as_sql_sort(db))\n\n    query = await _apply_task_run_filters(\n        query,\n        flow_filter=flow_filter,\n        flow_run_filter=flow_run_filter,\n        task_run_filter=task_run_filter,\n        deployment_filter=deployment_filter,\n        db=db,\n    )\n\n    if offset is not None:\n        query = query.offset(offset)\n\n    if limit is not None:\n        query = query.limit(limit)\n\n    logger.debug(f\"In read_task_runs, query generated is:\\n{query}\")\n    result = await session.execute(query)\n    return result.scalars().unique().all()\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.set_task_run_state","title":"<code>set_task_run_state</code>  <code>async</code>","text":"<p>Creates a new orchestrated task run state.</p> <p>Setting a new state on a run is the one of the principal actions that is governed by Prefect's orchestration logic. Setting a new run state will not guarantee creation, but instead trigger orchestration rules to govern the proposed <code>state</code> input. If the state is considered valid, it will be written to the database. Otherwise, a it's possible a different state, or no state, will be created. A <code>force</code> flag is supplied to bypass a subset of orchestration logic.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>Session</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id</p> required <code>state</code> <code>State</code> <p>a task run state model</p> required <code>force</code> <code>bool</code> <p>if False, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied.</p> <code>False</code> <p>Returns:</p> Type Description <code>OrchestrationResult</code> <p>OrchestrationResult object</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>async def set_task_run_state(\n    session: sa.orm.Session,\n    task_run_id: UUID,\n    state: schemas.states.State,\n    force: bool = False,\n    task_policy: BaseOrchestrationPolicy = None,\n    orchestration_parameters: Optional[Dict[str, Any]] = None,\n) -&gt; OrchestrationResult:\n    \"\"\"\n    Creates a new orchestrated task run state.\n\n    Setting a new state on a run is the one of the principal actions that is governed by\n    Prefect's orchestration logic. Setting a new run state will not guarantee creation,\n    but instead trigger orchestration rules to govern the proposed `state` input. If\n    the state is considered valid, it will be written to the database. Otherwise, a\n    it's possible a different state, or no state, will be created. A `force` flag is\n    supplied to bypass a subset of orchestration logic.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id\n        state: a task run state model\n        force: if False, orchestration rules will be applied that may alter or prevent\n            the state transition. If True, orchestration rules are not applied.\n\n    Returns:\n        OrchestrationResult object\n    \"\"\"\n\n    # load the task run\n    run = await models.task_runs.read_task_run(session=session, task_run_id=task_run_id)\n\n    if not run:\n        raise ObjectNotFoundError(f\"Task run with id {task_run_id} not found\")\n\n    initial_state = run.state.as_state() if run.state else None\n    initial_state_type = initial_state.type if initial_state else None\n    proposed_state_type = state.type if state else None\n    intended_transition = (initial_state_type, proposed_state_type)\n\n    if run.flow_run_id is None:\n        task_policy = AutonomousTaskPolicy  # CoreTaskPolicy + prevent `Running` -&gt; `Running` transition\n    elif force or task_policy is None:\n        task_policy = MinimalTaskPolicy\n\n    orchestration_rules = task_policy.compile_transition_rules(*intended_transition)\n    global_rules = GlobalTaskPolicy.compile_transition_rules(*intended_transition)\n\n    context = TaskOrchestrationContext(\n        session=session,\n        run=run,\n        initial_state=initial_state,\n        proposed_state=state,\n    )\n\n    if orchestration_parameters is not None:\n        context.parameters = orchestration_parameters\n\n    # apply orchestration rules and create the new task run state\n    async with contextlib.AsyncExitStack() as stack:\n        for rule in orchestration_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        for rule in global_rules:\n            context = await stack.enter_async_context(\n                rule(context, *intended_transition)\n            )\n\n        await context.validate_proposed_state()\n\n    if context.orchestration_error is not None:\n        raise context.orchestration_error\n\n    result = OrchestrationResult(\n        state=context.validated_state,\n        status=context.response_status,\n        details=context.response_details,\n    )\n\n    return result\n</code></pre>"},{"location":"api-ref/server/models/task_runs/#prefect.server.models.task_runs.update_task_run","title":"<code>update_task_run</code>  <code>async</code>","text":"<p>Updates a task run.</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <code>AsyncSession</code> <p>a database session</p> required <code>task_run_id</code> <code>UUID</code> <p>the task run id to update</p> required <code>task_run</code> <code>TaskRunUpdate</code> <p>a task run model</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not matching rows were found to update</p> Source code in <code>prefect/server/models/task_runs.py</code> <pre><code>@inject_db\nasync def update_task_run(\n    session: AsyncSession,\n    task_run_id: UUID,\n    task_run: schemas.actions.TaskRunUpdate,\n    db: PrefectDBInterface,\n) -&gt; bool:\n    \"\"\"\n    Updates a task run.\n\n    Args:\n        session: a database session\n        task_run_id: the task run id to update\n        task_run: a task run model\n\n    Returns:\n        bool: whether or not matching rows were found to update\n    \"\"\"\n    update_stmt = (\n        sa.update(db.TaskRun)\n        .where(db.TaskRun.id == task_run_id)\n        # exclude_unset=True allows us to only update values provided by\n        # the user, ignoring any defaults on the model\n        .values(**task_run.dict(shallow=True, exclude_unset=True))\n    )\n    result = await session.execute(update_stmt)\n    return result.rowcount &gt; 0\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/","title":"server.orchestration.core_policy","text":""},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy","title":"<code>prefect.server.orchestration.core_policy</code>","text":"<p>Orchestration logic that fires on state transitions.</p> <p><code>CoreFlowPolicy</code> and <code>CoreTaskPolicy</code> contain all default orchestration rules that Prefect enforces on a state transition.</p>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CoreFlowPolicy","title":"<code>CoreFlowPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against flow-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CoreFlowPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against flow-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            PreventDuplicateTransitions,\n            HandleFlowTerminalStateTransitions,\n            EnforceCancellingToCancelledTransition,\n            BypassCancellingFlowRunsWithNoInfra,\n            PreventPendingTransitions,\n            EnsureOnlyScheduledFlowsMarkedLate,\n            HandlePausingFlows,\n            HandleResumingPausedFlows,\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedFlows,\n        ] + ([InstrumentFlowRunStateTransitions] if PREFECT_EXPERIMENTAL_EVENTS else [])\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CoreTaskPolicy","title":"<code>CoreTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against task-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CoreTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against task-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            CacheRetrieval,\n            HandleTaskTerminalStateTransitions,\n            PreventRunningTasksFromStoppedFlows,\n            SecureTaskConcurrencySlots,  # retrieve cached states even if slots are full\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedTasks,\n            RenameReruns,\n            UpdateFlowRunTrackerOnTasks,\n            CacheInsertion,\n            ReleaseTaskConcurrencySlots,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.AutonomousTaskPolicy","title":"<code>AutonomousTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Orchestration rules that run against task-run-state transitions in priority order.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class AutonomousTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Orchestration rules that run against task-run-state transitions in priority order.\n    \"\"\"\n\n    def priority():\n        return [\n            PreventPendingTransitions,\n            CacheRetrieval,\n            HandleTaskTerminalStateTransitions,\n            SecureTaskConcurrencySlots,  # retrieve cached states even if slots are full\n            CopyScheduledTime,\n            WaitForScheduledTime,\n            RetryFailedTasks,\n            RenameReruns,\n            UpdateFlowRunTrackerOnTasks,\n            CacheInsertion,\n            ReleaseTaskConcurrencySlots,\n            EnqueueScheduledTasks,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.SecureTaskConcurrencySlots","title":"<code>SecureTaskConcurrencySlots</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Checks relevant concurrency slots are available before entering a Running state.</p> <p>This rule checks if concurrency limits have been set on the tags associated with a TaskRun. If so, a concurrency slot will be secured against each concurrency limit before being allowed to transition into a running state. If a concurrency limit has been reached, the client will be instructed to delay the transition for the duration specified by the \"PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS\" setting before trying again. If the concurrency limit set on a tag is 0, the transition will be aborted to prevent deadlocks.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class SecureTaskConcurrencySlots(BaseOrchestrationRule):\n    \"\"\"\n    Checks relevant concurrency slots are available before entering a Running state.\n\n    This rule checks if concurrency limits have been set on the tags associated with a\n    TaskRun. If so, a concurrency slot will be secured against each concurrency limit\n    before being allowed to transition into a running state. If a concurrency limit has\n    been reached, the client will be instructed to delay the transition for the duration\n    specified by the \"PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS\" setting\n    before trying again. If the concurrency limit set on a tag is 0, the transition will\n    be aborted to prevent deadlocks.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        self._applied_limits = []\n        filtered_limits = (\n            await concurrency_limits.filter_concurrency_limits_for_orchestration(\n                context.session, tags=context.run.tags\n            )\n        )\n        run_limits = {limit.tag: limit for limit in filtered_limits}\n        for tag, cl in run_limits.items():\n            limit = cl.concurrency_limit\n            if limit == 0:\n                # limits of 0 will deadlock, and the transition needs to abort\n                for stale_tag in self._applied_limits:\n                    stale_limit = run_limits.get(stale_tag, None)\n                    active_slots = set(stale_limit.active_slots)\n                    active_slots.discard(str(context.run.id))\n                    stale_limit.active_slots = list(active_slots)\n\n                await self.abort_transition(\n                    reason=(\n                        f'The concurrency limit on tag \"{tag}\" is 0 and will deadlock'\n                        \" if the task tries to run again.\"\n                    ),\n                )\n            elif len(cl.active_slots) &gt;= limit:\n                # if the limit has already been reached, delay the transition\n                for stale_tag in self._applied_limits:\n                    stale_limit = run_limits.get(stale_tag, None)\n                    active_slots = set(stale_limit.active_slots)\n                    active_slots.discard(str(context.run.id))\n                    stale_limit.active_slots = list(active_slots)\n\n                await self.delay_transition(\n                    PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS.value(),\n                    f\"Concurrency limit for the {tag} tag has been reached\",\n                )\n            else:\n                # log the TaskRun ID to active_slots\n                self._applied_limits.append(tag)\n                active_slots = set(cl.active_slots)\n                active_slots.add(str(context.run.id))\n                cl.active_slots = list(active_slots)\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        for tag in self._applied_limits:\n            cl = await concurrency_limits.read_concurrency_limit_by_tag(\n                context.session, tag\n            )\n            active_slots = set(cl.active_slots)\n            active_slots.discard(str(context.run.id))\n            cl.active_slots = list(active_slots)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.ReleaseTaskConcurrencySlots","title":"<code>ReleaseTaskConcurrencySlots</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Releases any concurrency slots held by a run upon exiting a Running or Cancelling state.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class ReleaseTaskConcurrencySlots(BaseUniversalTransform):\n    \"\"\"\n    Releases any concurrency slots held by a run upon exiting a Running or\n    Cancelling state.\n    \"\"\"\n\n    async def after_transition(\n        self,\n        context: OrchestrationContext,\n    ):\n        if self.nullified_transition():\n            return\n\n        if context.validated_state and context.validated_state.type not in [\n            states.StateType.RUNNING,\n            states.StateType.CANCELLING,\n        ]:\n            filtered_limits = (\n                await concurrency_limits.filter_concurrency_limits_for_orchestration(\n                    context.session, tags=context.run.tags\n                )\n            )\n            run_limits = {limit.tag: limit for limit in filtered_limits}\n            for tag, cl in run_limits.items():\n                active_slots = set(cl.active_slots)\n                active_slots.discard(str(context.run.id))\n                cl.active_slots = list(active_slots)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.AddUnknownResult","title":"<code>AddUnknownResult</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Assign an \"unknown\" result to runs that are forced to complete from a failed or crashed state, if the previous state used a persisted result.</p> <p>When we retry a flow run, we retry any task runs that were in a failed or crashed state, but we also retry completed task runs that didn't use a persisted result. This means that without a sentinel value for unknown results, a task run forced into Completed state will always get rerun if the flow run retries because the task run lacks a persisted result. The \"unknown\" sentinel ensures that when we see a completed task run with an unknown result, we know that it was forced to complete and we shouldn't rerun it.</p> <p>Flow runs forced into a Completed state have a similar problem: without a sentinel value, attempting to refer to the flow run's result will raise an exception because the flow run has no result. The sentinel ensures that we can distinguish between a flow run that has no result and a flow run that has an unknown result.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class AddUnknownResult(BaseOrchestrationRule):\n    \"\"\"\n    Assign an \"unknown\" result to runs that are forced to complete from a\n    failed or crashed state, if the previous state used a persisted result.\n\n    When we retry a flow run, we retry any task runs that were in a failed or\n    crashed state, but we also retry completed task runs that didn't use a\n    persisted result. This means that without a sentinel value for unknown\n    results, a task run forced into Completed state will always get rerun if the\n    flow run retries because the task run lacks a persisted result. The\n    \"unknown\" sentinel ensures that when we see a completed task run with an\n    unknown result, we know that it was forced to complete and we shouldn't\n    rerun it.\n\n    Flow runs forced into a Completed state have a similar problem: without a\n    sentinel value, attempting to refer to the flow run's result will raise an\n    exception because the flow run has no result. The sentinel ensures that we\n    can distinguish between a flow run that has no result and a flow run that\n    has an unknown result.\n    \"\"\"\n\n    FROM_STATES = [StateType.FAILED, StateType.CRASHED]\n    TO_STATES = [StateType.COMPLETED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state\n            and initial_state.data\n            and initial_state.data.get(\"type\") == \"reference\"\n        ):\n            unknown_result = await UnknownResult.create()\n            self.context.proposed_state.data = unknown_result.dict()\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CacheInsertion","title":"<code>CacheInsertion</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Caches completed states with cache keys after they are validated.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CacheInsertion(BaseOrchestrationRule):\n    \"\"\"\n    Caches completed states with cache keys after they are validated.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.COMPLETED]\n\n    @inject_db\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n        db: PrefectDBInterface,\n    ) -&gt; None:\n        if not validated_state or not context.session:\n            return\n\n        cache_key = validated_state.state_details.cache_key\n        if cache_key:\n            new_cache_item = db.TaskRunStateCache(\n                cache_key=cache_key,\n                cache_expiration=validated_state.state_details.cache_expiration,\n                task_run_state_id=validated_state.id,\n            )\n            context.session.add(new_cache_item)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CacheRetrieval","title":"<code>CacheRetrieval</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects running states if a completed state has been cached.</p> <p>This rule rejects transitions into a running state with a cache key if the key has already been associated with a completed state in the cache table. The client will be instructed to transition into the cached completed state instead.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CacheRetrieval(BaseOrchestrationRule):\n    \"\"\"\n    Rejects running states if a completed state has been cached.\n\n    This rule rejects transitions into a running state with a cache key if the key\n    has already been associated with a completed state in the cache table. The client\n    will be instructed to transition into the cached completed state instead.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    @inject_db\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n        db: PrefectDBInterface,\n    ) -&gt; None:\n        cache_key = proposed_state.state_details.cache_key\n        if cache_key and not proposed_state.state_details.refresh_cache:\n            # Check for cached states matching the cache key\n            cached_state_id = (\n                select(db.TaskRunStateCache.task_run_state_id)\n                .where(\n                    sa.and_(\n                        db.TaskRunStateCache.cache_key == cache_key,\n                        sa.or_(\n                            db.TaskRunStateCache.cache_expiration.is_(None),\n                            db.TaskRunStateCache.cache_expiration &gt; pendulum.now(\"utc\"),\n                        ),\n                    ),\n                )\n                .order_by(db.TaskRunStateCache.created.desc())\n                .limit(1)\n            ).scalar_subquery()\n            query = select(db.TaskRunState).where(db.TaskRunState.id == cached_state_id)\n            cached_state = (await context.session.execute(query)).scalar()\n            if cached_state:\n                new_state = cached_state.as_state().copy(reset_fields=True)\n                new_state.name = \"Cached\"\n                await self.reject_transition(\n                    state=new_state, reason=\"Retrieved state from cache\"\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RetryFailedFlows","title":"<code>RetryFailedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p> <p>This rule rejects transitions into a failed state if <code>retries</code> has been set and the run count has not reached the specified limit. The client will be instructed to transition into a scheduled state to retry flow execution.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RetryFailedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Rejects failed states and schedules a retry if the retry limit has not been reached.\n\n    This rule rejects transitions into a failed state if `retries` has been\n    set and the run count has not reached the specified limit. The client will be\n    instructed to transition into a scheduled state to retry flow execution.\n    \"\"\"\n\n    FROM_STATES = [StateType.RUNNING]\n    TO_STATES = [StateType.FAILED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        run_settings = context.run_settings\n        run_count = context.run.run_count\n\n        if run_settings.retries is None or run_count &gt; run_settings.retries:\n            return  # Retry count exceeded, allow transition to failed\n\n        scheduled_start_time = pendulum.now(\"UTC\").add(\n            seconds=run_settings.retry_delay or 0\n        )\n\n        # support old-style flow run retries for older clients\n        # older flow retries require us to loop over failed tasks to update their state\n        # this is not required after API version 0.8.3\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version and api_version &lt; Version(\"0.8.3\"):\n            failed_task_runs = await models.task_runs.read_task_runs(\n                context.session,\n                flow_run_filter=filters.FlowRunFilter(id={\"any_\": [context.run.id]}),\n                task_run_filter=filters.TaskRunFilter(\n                    state={\"type\": {\"any_\": [\"FAILED\"]}}\n                ),\n            )\n            for run in failed_task_runs:\n                await models.task_runs.set_task_run_state(\n                    context.session,\n                    run.id,\n                    state=states.AwaitingRetry(scheduled_time=scheduled_start_time),\n                    force=True,\n                )\n                # Reset the run count so that the task run retries still work correctly\n                run.run_count = 0\n\n        # Reset pause metadata on retry\n        # Pauses as a concept only exist after API version 0.8.4\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n            updated_policy = context.run.empirical_policy.dict()\n            updated_policy[\"resuming\"] = False\n            updated_policy[\"pause_keys\"] = set()\n            context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n\n        # Generate a new state for the flow\n        retry_state = states.AwaitingRetry(\n            scheduled_time=scheduled_start_time,\n            message=proposed_state.message,\n            data=proposed_state.data,\n        )\n        await self.reject_transition(state=retry_state, reason=\"Retrying\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RetryFailedTasks","title":"<code>RetryFailedTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects failed states and schedules a retry if the retry limit has not been reached.</p> <p>This rule rejects transitions into a failed state if <code>retries</code> has been set, the run count has not reached the specified limit, and the client asserts it is a retriable task run. The client will be instructed to transition into a scheduled state to retry task execution.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RetryFailedTasks(BaseOrchestrationRule):\n    \"\"\"\n    Rejects failed states and schedules a retry if the retry limit has not been reached.\n\n    This rule rejects transitions into a failed state if `retries` has been\n    set, the run count has not reached the specified limit, and the client\n    asserts it is a retriable task run. The client will be instructed to\n    transition into a scheduled state to retry task execution.\n    \"\"\"\n\n    FROM_STATES = [StateType.RUNNING]\n    TO_STATES = [StateType.FAILED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        run_settings = context.run_settings\n        run_count = context.run.run_count\n        delay = run_settings.retry_delay\n\n        if isinstance(delay, list):\n            base_delay = delay[min(run_count - 1, len(delay) - 1)]\n        else:\n            base_delay = run_settings.retry_delay or 0\n\n        # guard against negative relative jitter inputs\n        if run_settings.retry_jitter_factor:\n            delay = clamped_poisson_interval(\n                base_delay, clamping_factor=run_settings.retry_jitter_factor\n            )\n        else:\n            delay = base_delay\n\n        # set by user to conditionally retry a task using @task(retry_condition_fn=...)\n        if getattr(proposed_state.state_details, \"retriable\", True) is False:\n            return\n\n        if run_settings.retries is not None and run_count &lt;= run_settings.retries:\n            retry_state = states.AwaitingRetry(\n                scheduled_time=pendulum.now(\"UTC\").add(seconds=delay),\n                message=proposed_state.message,\n                data=proposed_state.data,\n            )\n            await self.reject_transition(state=retry_state, reason=\"Retrying\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.EnqueueScheduledTasks","title":"<code>EnqueueScheduledTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Enqueues autonomous task runs when they are scheduled</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class EnqueueScheduledTasks(BaseOrchestrationRule):\n    \"\"\"\n    Enqueues autonomous task runs when they are scheduled\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.SCHEDULED]\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if not PREFECT_EXPERIMENTAL_ENABLE_TASK_SCHEDULING.value():\n            # Only if task scheduling is enabled\n            return\n\n        if not validated_state:\n            # Only if the transition was valid\n            return\n\n        if context.run.flow_run_id:\n            # Only for autonomous tasks\n            return\n\n        task_run: TaskRun = TaskRun.from_orm(context.run)\n        queue = TaskQueue.for_key(task_run.task_key)\n\n        if validated_state.name == \"AwaitingRetry\":\n            await queue.retry(task_run)\n        else:\n            await queue.enqueue(task_run)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.RenameReruns","title":"<code>RenameReruns</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Name the states if they have run more than once.</p> <p>In the special case where the initial state is an \"AwaitingRetry\" scheduled state, the proposed state will be renamed to \"Retrying\" instead.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class RenameReruns(BaseOrchestrationRule):\n    \"\"\"\n    Name the states if they have run more than once.\n\n    In the special case where the initial state is an \"AwaitingRetry\" scheduled state,\n    the proposed state will be renamed to \"Retrying\" instead.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        run_count = context.run.run_count\n        if run_count &gt; 0:\n            if initial_state.name == \"AwaitingRetry\":\n                await self.rename_state(\"Retrying\")\n            else:\n                await self.rename_state(\"Rerunning\")\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.CopyScheduledTime","title":"<code>CopyScheduledTime</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Ensures scheduled time is copied from scheduled states to pending states.</p> <p>If a new scheduled time has been proposed on the pending state, the scheduled time on the scheduled state will be ignored.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class CopyScheduledTime(BaseOrchestrationRule):\n    \"\"\"\n    Ensures scheduled time is copied from scheduled states to pending states.\n\n    If a new scheduled time has been proposed on the pending state, the scheduled time\n    on the scheduled state will be ignored.\n    \"\"\"\n\n    FROM_STATES = [StateType.SCHEDULED]\n    TO_STATES = [StateType.PENDING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if not proposed_state.state_details.scheduled_time:\n            proposed_state.state_details.scheduled_time = (\n                initial_state.state_details.scheduled_time\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.WaitForScheduledTime","title":"<code>WaitForScheduledTime</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents transitions to running states from happening to early.</p> <p>This rule enforces that all scheduled states will only start with the machine clock used by the Prefect REST API instance. This rule will identify transitions from scheduled states that are too early and nullify them. Instead, no state will be written to the database and the client will be sent an instruction to wait for <code>delay_seconds</code> before attempting the transition again.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class WaitForScheduledTime(BaseOrchestrationRule):\n    \"\"\"\n    Prevents transitions to running states from happening to early.\n\n    This rule enforces that all scheduled states will only start with the machine clock\n    used by the Prefect REST API instance. This rule will identify transitions from scheduled\n    states that are too early and nullify them. Instead, no state will be written to the\n    database and the client will be sent an instruction to wait for `delay_seconds`\n    before attempting the transition again.\n    \"\"\"\n\n    FROM_STATES = [StateType.SCHEDULED, StateType.PENDING]\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        scheduled_time = initial_state.state_details.scheduled_time\n        if not scheduled_time:\n            return\n\n        # At this moment, we round delay to the nearest second as the API schema\n        # specifies an integer return value.\n        delay = scheduled_time - pendulum.now(\"UTC\")\n        delay_seconds = delay.in_seconds()\n        delay_seconds += round(delay.microseconds / 1e6)\n        if delay_seconds &gt; 0:\n            await self.delay_transition(\n                delay_seconds, reason=\"Scheduled time is in the future\"\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandlePausingFlows","title":"<code>HandlePausingFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Governs runs attempting to enter a Paused/Suspended state</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandlePausingFlows(BaseOrchestrationRule):\n    \"\"\"\n    Governs runs attempting to enter a Paused/Suspended state\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.PAUSED]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        verb = \"suspend\" if proposed_state.name == \"Suspended\" else \"pause\"\n\n        if initial_state is None:\n            await self.abort_transition(f\"Cannot {verb} flows with no state.\")\n            return\n\n        if not initial_state.is_running():\n            await self.reject_transition(\n                state=None,\n                reason=f\"Cannot {verb} flows that are not currently running.\",\n            )\n            return\n\n        self.key = proposed_state.state_details.pause_key\n        if self.key is None:\n            # if no pause key is provided, default to a UUID\n            self.key = str(uuid4())\n\n        if self.key in context.run.empirical_policy.pause_keys:\n            await self.reject_transition(\n                state=None, reason=f\"This {verb} has already fired.\"\n            )\n            return\n\n        if proposed_state.state_details.pause_reschedule:\n            if context.run.parent_task_run_id:\n                await self.abort_transition(\n                    reason=f\"Cannot {verb} subflows.\",\n                )\n                return\n\n            if context.run.deployment_id is None:\n                await self.abort_transition(\n                    reason=f\"Cannot {verb} flows without a deployment.\",\n                )\n                return\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        updated_policy = context.run.empirical_policy.dict()\n        updated_policy[\"pause_keys\"].add(self.key)\n        context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleResumingPausedFlows","title":"<code>HandleResumingPausedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Governs runs attempting to leave a Paused state</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleResumingPausedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Governs runs attempting to leave a Paused state\n    \"\"\"\n\n    FROM_STATES = [StateType.PAUSED]\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if not (\n            proposed_state.is_running()\n            or proposed_state.is_scheduled()\n            or proposed_state.is_final()\n        ):\n            await self.reject_transition(\n                state=None,\n                reason=(\n                    f\"This run cannot transition to the {proposed_state.type} state\"\n                    f\" from the {initial_state.type} state.\"\n                ),\n            )\n            return\n\n        verb = \"suspend\" if proposed_state.name == \"Suspended\" else \"pause\"\n\n        if initial_state.state_details.pause_reschedule:\n            if not context.run.deployment_id:\n                await self.reject_transition(\n                    state=None,\n                    reason=(\n                        f\"Cannot reschedule a {proposed_state.name.lower()} flow run\"\n                        \" without a deployment.\"\n                    ),\n                )\n                return\n        pause_timeout = initial_state.state_details.pause_timeout\n        if pause_timeout and pause_timeout &lt; pendulum.now(\"UTC\"):\n            pause_timeout_failure = states.Failed(\n                message=(\n                    f\"The flow was {proposed_state.name.lower()} and never resumed.\"\n                ),\n            )\n            await self.reject_transition(\n                state=pause_timeout_failure,\n                reason=f\"The flow run {verb} has timed out and can no longer resume.\",\n            )\n            return\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        updated_policy = context.run.empirical_policy.dict()\n        updated_policy[\"resuming\"] = True\n        context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.UpdateFlowRunTrackerOnTasks","title":"<code>UpdateFlowRunTrackerOnTasks</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Tracks the flow run attempt a task run state is associated with.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class UpdateFlowRunTrackerOnTasks(BaseOrchestrationRule):\n    \"\"\"\n    Tracks the flow run attempt a task run state is associated with.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        if context.run.flow_run_id is not None:\n            self.flow_run = await context.flow_run()\n            if self.flow_run:\n                context.run.flow_run_run_count = self.flow_run.run_count\n            else:\n                raise ObjectNotFoundError(\n                    (\n                        \"Unable to read flow run associated with task run:\"\n                        f\" {context.run.id}, this flow run might have been deleted\"\n                    ),\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleTaskTerminalStateTransitions","title":"<code>HandleTaskTerminalStateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>We do not allow tasks to leave terminal states if: - The task is completed and has a persisted result - The task is going to CANCELLING / PAUSED / CRASHED</p> <p>We reset the run count when a task leaves a terminal state for a non-terminal state which resets task run retries; this is particularly relevant for flow run retries.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleTaskTerminalStateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    We do not allow tasks to leave terminal states if:\n    - The task is completed and has a persisted result\n    - The task is going to CANCELLING / PAUSED / CRASHED\n\n    We reset the run count when a task leaves a terminal state for a non-terminal state\n    which resets task run retries; this is particularly relevant for flow run retries.\n    \"\"\"\n\n    FROM_STATES = TERMINAL_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        self.original_run_count = context.run.run_count\n\n        # Do not allow runs to be marked as crashed, paused, or cancelling if already terminal\n        if proposed_state.type in {\n            StateType.CANCELLING,\n            StateType.PAUSED,\n            StateType.CRASHED,\n        }:\n            await self.abort_transition(f\"Run is already {initial_state.type.value}.\")\n            return\n\n        # Only allow departure from a happily completed state if the result is not persisted\n        if (\n            initial_state.is_completed()\n            and initial_state.data\n            and initial_state.data.get(\"type\") != \"unpersisted\"\n        ):\n            await self.reject_transition(None, \"This run is already completed.\")\n            return\n\n        if not proposed_state.is_final():\n            # Reset run count to reset retries\n            context.run.run_count = 0\n\n        # Change the name of the state to retrying if its a flow run retry\n        if proposed_state.is_running() and context.run.flow_run_id is not None:\n            self.flow_run = await context.flow_run()\n            flow_retrying = context.run.flow_run_run_count &lt; self.flow_run.run_count\n            if flow_retrying:\n                await self.rename_state(\"Retrying\")\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ):\n        # reset run count\n        context.run.run_count = self.original_run_count\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.HandleFlowTerminalStateTransitions","title":"<code>HandleFlowTerminalStateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>We do not allow flows to leave terminal states if: - The flow is completed and has a persisted result - The flow is going to CANCELLING / PAUSED / CRASHED - The flow is going to scheduled and has no deployment</p> <p>We reset the pause metadata when a flow leaves a terminal state for a non-terminal state. This resets pause behavior during manual flow run retries.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class HandleFlowTerminalStateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    We do not allow flows to leave terminal states if:\n    - The flow is completed and has a persisted result\n    - The flow is going to CANCELLING / PAUSED / CRASHED\n    - The flow is going to scheduled and has no deployment\n\n    We reset the pause metadata when a flow leaves a terminal state for a non-terminal\n    state. This resets pause behavior during manual flow run retries.\n    \"\"\"\n\n    FROM_STATES = TERMINAL_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        self.original_flow_policy = context.run.empirical_policy.dict()\n\n        # Do not allow runs to be marked as crashed, paused, or cancelling if already terminal\n        if proposed_state.type in {\n            StateType.CANCELLING,\n            StateType.PAUSED,\n            StateType.CRASHED,\n        }:\n            await self.abort_transition(\n                f\"Run is already in terminal state {initial_state.type.value}.\"\n            )\n            return\n\n        # Only allow departure from a happily completed state if the result is not\n        # persisted and the a rerun is being proposed\n        if (\n            initial_state.is_completed()\n            and not proposed_state.is_final()\n            and initial_state.data\n            and initial_state.data.get(\"type\") != \"unpersisted\"\n        ):\n            await self.reject_transition(None, \"Run is already COMPLETED.\")\n            return\n\n        # Do not allows runs to be rescheduled without a deployment\n        if proposed_state.is_scheduled() and not context.run.deployment_id:\n            await self.abort_transition(\n                \"Cannot reschedule a run without an associated deployment.\"\n            )\n            return\n\n        if not proposed_state.is_final():\n            # Reset pause metadata when leaving a terminal state\n            api_version = context.parameters.get(\"api-version\", None)\n            if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n                updated_policy = context.run.empirical_policy.dict()\n                updated_policy[\"resuming\"] = False\n                updated_policy[\"pause_keys\"] = set()\n                context.run.empirical_policy = core.FlowRunPolicy(**updated_policy)\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ):\n        context.run.empirical_policy = core.FlowRunPolicy(**self.original_flow_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventPendingTransitions","title":"<code>PreventPendingTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents transitions to PENDING.</p> <p>This rule is only used for flow runs.</p> <p>This is intended to prevent race conditions during duplicate submissions of runs. Before a run is submitted to its execution environment, it should be placed in a PENDING state. If two workers attempt to submit the same run, one of them should encounter a PENDING -&gt; PENDING transition and abort orchestration of the run.</p> <p>Similarly, if the execution environment starts quickly the run may be in a RUNNING state when the second worker attempts the PENDING transition. We deny these state changes as well to prevent duplicate submission. If a run has transitioned to a RUNNING state a worker should not attempt to submit it again unless it has moved into a terminal state.</p> <p>CANCELLING and CANCELLED runs should not be allowed to transition to PENDING. For re-runs of deployed runs, they should transition to SCHEDULED first. For re-runs of ad-hoc runs, they should transition directly to RUNNING.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventPendingTransitions(BaseOrchestrationRule):\n    \"\"\"\n    Prevents transitions to PENDING.\n\n    This rule is only used for flow runs.\n\n    This is intended to prevent race conditions during duplicate submissions of runs.\n    Before a run is submitted to its execution environment, it should be placed in a\n    PENDING state. If two workers attempt to submit the same run, one of them should\n    encounter a PENDING -&gt; PENDING transition and abort orchestration of the run.\n\n    Similarly, if the execution environment starts quickly the run may be in a RUNNING\n    state when the second worker attempts the PENDING transition. We deny these state\n    changes as well to prevent duplicate submission. If a run has transitioned to a\n    RUNNING state a worker should not attempt to submit it again unless it has moved\n    into a terminal state.\n\n    CANCELLING and CANCELLED runs should not be allowed to transition to PENDING.\n    For re-runs of deployed runs, they should transition to SCHEDULED first.\n    For re-runs of ad-hoc runs, they should transition directly to RUNNING.\n    \"\"\"\n\n    FROM_STATES = [\n        StateType.PENDING,\n        StateType.CANCELLING,\n        StateType.RUNNING,\n        StateType.CANCELLED,\n    ]\n    TO_STATES = [StateType.PENDING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        await self.abort_transition(\n            reason=(\n                f\"This run is in a {initial_state.type.name} state and cannot\"\n                \" transition to a PENDING state.\"\n            )\n        )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventRunningTasksFromStoppedFlows","title":"<code>PreventRunningTasksFromStoppedFlows</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevents running tasks from stopped flows.</p> <p>A running state implies execution, but also the converse. This rule ensures that a flow's tasks cannot be run unless the flow is also running.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventRunningTasksFromStoppedFlows(BaseOrchestrationRule):\n    \"\"\"\n    Prevents running tasks from stopped flows.\n\n    A running state implies execution, but also the converse. This rule ensures that a\n    flow's tasks cannot be run unless the flow is also running.\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = [StateType.RUNNING]\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        flow_run = await context.flow_run()\n        if flow_run is not None:\n            if flow_run.state is None:\n                await self.abort_transition(\n                    reason=\"The enclosing flow must be running to begin task execution.\"\n                )\n            elif flow_run.state.type == StateType.PAUSED:\n                # Use the flow run's Paused state details to preserve data like\n                # timeouts.\n                paused_state = states.Paused(\n                    name=\"NotReady\",\n                    pause_expiration_time=flow_run.state.state_details.pause_timeout,\n                    reschedule=flow_run.state.state_details.pause_reschedule,\n                )\n                await self.reject_transition(\n                    state=paused_state,\n                    reason=(\n                        \"The flow is paused, new tasks can execute after resuming flow\"\n                        f\" run: {flow_run.id}.\"\n                    ),\n                )\n            elif not flow_run.state.type == StateType.RUNNING:\n                # task runners should abort task run execution\n                await self.abort_transition(\n                    reason=(\n                        \"The enclosing flow must be running to begin task execution.\"\n                    ),\n                )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.EnforceCancellingToCancelledTransition","title":"<code>EnforceCancellingToCancelledTransition</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects transitions from Cancelling to any terminal state except for Cancelled.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class EnforceCancellingToCancelledTransition(BaseOrchestrationRule):\n    \"\"\"\n    Rejects transitions from Cancelling to any terminal state except for Cancelled.\n    \"\"\"\n\n    FROM_STATES = {StateType.CANCELLED, StateType.CANCELLING}\n    TO_STATES = ALL_ORCHESTRATION_STATES - {StateType.CANCELLED}\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: TaskOrchestrationContext,\n    ) -&gt; None:\n        await self.reject_transition(\n            state=None,\n            reason=(\n                \"Cannot transition flows that are cancelling to a state other \"\n                \"than Cancelled.\"\n            ),\n        )\n        return\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.BypassCancellingFlowRunsWithNoInfra","title":"<code>BypassCancellingFlowRunsWithNoInfra</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled, if the flow run has no associated infrastructure process ID. Also Rejects transitions from Paused to Cancelling if the Paused state's details indicates the flow run has been suspended, exiting the flow and tearing down infra.</p> <p>The <code>Cancelling</code> state is used to clean up infrastructure. If there is not infrastructure to clean up, we can transition directly to <code>Cancelled</code>. Runs that are <code>Resuming</code> are in a <code>Scheduled</code> state that were previously <code>Suspended</code> and do not yet have infrastructure.</p> <p>Runs that are <code>AwaitingRetry</code> are a <code>Scheduled</code> state that may have associated infrastructure.</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class BypassCancellingFlowRunsWithNoInfra(BaseOrchestrationRule):\n    \"\"\"Rejects transitions from Scheduled to Cancelling, and instead sets the state to Cancelled,\n    if the flow run has no associated infrastructure process ID. Also Rejects transitions from\n    Paused to Cancelling if the Paused state's details indicates the flow run has been suspended,\n    exiting the flow and tearing down infra.\n\n    The `Cancelling` state is used to clean up infrastructure. If there is not infrastructure\n    to clean up, we can transition directly to `Cancelled`. Runs that are `Resuming` are in a\n    `Scheduled` state that were previously `Suspended` and do not yet have infrastructure.\n\n    Runs that are `AwaitingRetry` are a `Scheduled` state that may have associated infrastructure.\n    \"\"\"\n\n    FROM_STATES = {StateType.SCHEDULED, StateType.PAUSED}\n    TO_STATES = {StateType.CANCELLING}\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: FlowOrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state.type == states.StateType.SCHEDULED\n            and not context.run.infrastructure_pid\n            or initial_state.name == \"Resuming\"\n        ):\n            await self.reject_transition(\n                state=states.Cancelled(),\n                reason=\"Scheduled flow run has no infrastructure to terminate.\",\n            )\n        elif (\n            initial_state.type == states.StateType.PAUSED\n            and initial_state.state_details.pause_reschedule\n        ):\n            await self.reject_transition(\n                state=states.Cancelled(),\n                reason=\"Suspended flow run has no infrastructure to terminate.\",\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/core_policy/#prefect.server.orchestration.core_policy.PreventDuplicateTransitions","title":"<code>PreventDuplicateTransitions</code>","text":"<p>               Bases: <code>BaseOrchestrationRule</code></p> <p>Prevent duplicate transitions from being made right after one another.</p> <p>This rule allows for clients to set an optional transition_id on a state. If the run's next transition has the same transition_id, the transition will be rejected and the existing state will be returned.</p> <p>This allows for clients to make state transition requests without worrying about the following case: - A client making a state transition request - The server accepts transition and commits the transition - The client is unable to receive the response and retries the request</p> Source code in <code>prefect/server/orchestration/core_policy.py</code> <pre><code>class PreventDuplicateTransitions(BaseOrchestrationRule):\n    \"\"\"\n    Prevent duplicate transitions from being made right after one another.\n\n    This rule allows for clients to set an optional transition_id on a state. If the\n    run's next transition has the same transition_id, the transition will be\n    rejected and the existing state will be returned.\n\n    This allows for clients to make state transition requests without worrying about\n    the following case:\n    - A client making a state transition request\n    - The server accepts transition and commits the transition\n    - The client is unable to receive the response and retries the request\n    \"\"\"\n\n    FROM_STATES = ALL_ORCHESTRATION_STATES\n    TO_STATES = ALL_ORCHESTRATION_STATES\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if (\n            initial_state is None\n            or proposed_state is None\n            or initial_state.state_details is None\n            or proposed_state.state_details is None\n        ):\n            return\n\n        initial_transition_id = getattr(\n            initial_state.state_details, \"transition_id\", None\n        )\n        proposed_transition_id = getattr(\n            proposed_state.state_details, \"transition_id\", None\n        )\n        if (\n            initial_transition_id is not None\n            and proposed_transition_id is not None\n            and initial_transition_id == proposed_transition_id\n        ):\n            await self.reject_transition(\n                # state=None will return the initial (current) state\n                state=None,\n                reason=\"This run has already made this state transition.\",\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/","title":"server.orchestration.global_policy","text":""},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy","title":"<code>prefect.server.orchestration.global_policy</code>","text":"<p>Bookkeeping logic that fires on every state transition.</p> <p>For clarity, <code>GlobalFlowpolicy</code> and <code>GlobalTaskPolicy</code> contain all transition logic implemented using <code>BaseUniversalTransform</code>. None of these operations modify state, and regardless of what orchestration Prefect REST API might enforce on a transition, the global policies contain Prefect's necessary bookkeeping. Because these transforms record information about the validated state committed to the state database, they should be the most deeply nested contexts in orchestration loop.</p>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.GlobalFlowPolicy","title":"<code>GlobalFlowPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Global transforms that run against flow-run-state transitions in priority order.</p> <p>These transforms are intended to run immediately before and after a state transition is validated.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class GlobalFlowPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Global transforms that run against flow-run-state transitions in priority order.\n\n    These transforms are intended to run immediately before and after a state transition\n    is validated.\n    \"\"\"\n\n    def priority():\n        return COMMON_GLOBAL_TRANSFORMS() + [\n            UpdateSubflowParentTask,\n            UpdateSubflowStateDetails,\n            IncrementFlowRunCount,\n            RemoveResumingIndicator,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.GlobalTaskPolicy","title":"<code>GlobalTaskPolicy</code>","text":"<p>               Bases: <code>BaseOrchestrationPolicy</code></p> <p>Global transforms that run against task-run-state transitions in priority order.</p> <p>These transforms are intended to run immediately before and after a state transition is validated.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class GlobalTaskPolicy(BaseOrchestrationPolicy):\n    \"\"\"\n    Global transforms that run against task-run-state transitions in priority order.\n\n    These transforms are intended to run immediately before and after a state transition\n    is validated.\n    \"\"\"\n\n    def priority():\n        return COMMON_GLOBAL_TRANSFORMS() + [\n            IncrementTaskRunCount,\n        ]\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateType","title":"<code>SetRunStateType</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Updates the state type of a run on a state transition.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateType(BaseUniversalTransform):\n    \"\"\"\n    Updates the state type of a run on a state transition.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's type\n        context.run.state_type = context.proposed_state.type\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateName","title":"<code>SetRunStateName</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Updates the state name of a run on a state transition.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateName(BaseUniversalTransform):\n    \"\"\"\n    Updates the state name of a run on a state transition.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's name\n        context.run.state_name = context.proposed_state.name\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetStartTime","title":"<code>SetStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run enters a running state for the first time.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetStartTime(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run enters a running state for the first time.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state and no start time is set...\n        if context.proposed_state.is_running() and context.run.start_time is None:\n            # set the start time\n            context.run.start_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetRunStateTimestamp","title":"<code>SetRunStateTimestamp</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run changes states.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetRunStateTimestamp(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run changes states.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # record the new state's timestamp\n        context.run.state_timestamp = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetEndTime","title":"<code>SetEndTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the time a run enters a terminal state.</p> <p>With normal client usage, a run will not transition out of a terminal state. However, it's possible to force these transitions manually via the API. While leaving a terminal state, the end time will be unset.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetEndTime(BaseUniversalTransform):\n    \"\"\"\n    Records the time a run enters a terminal state.\n\n    With normal client usage, a run will not transition out of a terminal state.\n    However, it's possible to force these transitions manually via the API. While\n    leaving a terminal state, the end time will be unset.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if exiting a final state for a non-final state...\n        if (\n            context.initial_state\n            and context.initial_state.is_final()\n            and not context.proposed_state.is_final()\n        ):\n            # clear the end time\n            context.run.end_time = None\n\n        # if entering a final state...\n        if context.proposed_state.is_final():\n            # if the run has a start time and no end time, give it one\n            if context.run.start_time and not context.run.end_time:\n                context.run.end_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementRunTime","title":"<code>IncrementRunTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the amount of time a run spends in the running state.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementRunTime(BaseUniversalTransform):\n    \"\"\"\n    Records the amount of time a run spends in the running state.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if exiting a running state...\n        if context.initial_state and context.initial_state.is_running():\n            # increment the run time by the time spent in the previous state\n            context.run.total_run_time += (\n                context.proposed_state.timestamp - context.initial_state.timestamp\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementFlowRunCount","title":"<code>IncrementFlowRunCount</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the number of times a run enters a running state. For use with retries.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementFlowRunCount(BaseUniversalTransform):\n    \"\"\"\n    Records the number of times a run enters a running state. For use with retries.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state...\n        if context.proposed_state.is_running():\n            # do not increment the run count if resuming a paused flow\n            api_version = context.parameters.get(\"api-version\", None)\n            if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n                if context.run.empirical_policy.resuming:\n                    return\n\n            # increment the run count\n            context.run.run_count += 1\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.RemoveResumingIndicator","title":"<code>RemoveResumingIndicator</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Removes the indicator on a flow run that marks it as resuming.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class RemoveResumingIndicator(BaseUniversalTransform):\n    \"\"\"\n    Removes the indicator on a flow run that marks it as resuming.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        proposed_state = context.proposed_state\n\n        api_version = context.parameters.get(\"api-version\", None)\n        if api_version is None or api_version &gt;= Version(\"0.8.4\"):\n            if proposed_state.is_running() or proposed_state.is_final():\n                if context.run.empirical_policy.resuming:\n                    updated_policy = context.run.empirical_policy.dict()\n                    updated_policy[\"resuming\"] = False\n                    context.run.empirical_policy = FlowRunPolicy(**updated_policy)\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.IncrementTaskRunCount","title":"<code>IncrementTaskRunCount</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the number of times a run enters a running state. For use with retries.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class IncrementTaskRunCount(BaseUniversalTransform):\n    \"\"\"\n    Records the number of times a run enters a running state. For use with retries.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # if entering a running state...\n        if context.proposed_state.is_running():\n            # increment the run count\n            context.run.run_count += 1\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetExpectedStartTime","title":"<code>SetExpectedStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Estimates the time a state is expected to start running if not set.</p> <p>For scheduled states, this estimate is simply the scheduled time. For other states, this is set to the time the proposed state was created by Prefect.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetExpectedStartTime(BaseUniversalTransform):\n    \"\"\"\n    Estimates the time a state is expected to start running if not set.\n\n    For scheduled states, this estimate is simply the scheduled time. For other states,\n    this is set to the time the proposed state was created by Prefect.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # set expected start time if this is the first state\n        if not context.run.expected_start_time:\n            if context.proposed_state.is_scheduled():\n                context.run.expected_start_time = (\n                    context.proposed_state.state_details.scheduled_time\n                )\n            else:\n                context.run.expected_start_time = context.proposed_state.timestamp\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.SetNextScheduledStartTime","title":"<code>SetNextScheduledStartTime</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Records the scheduled time on a run.</p> <p>When a run enters a scheduled state, <code>run.next_scheduled_start_time</code> is set to the state's scheduled time. When leaving a scheduled state, <code>run.next_scheduled_start_time</code> is unset.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class SetNextScheduledStartTime(BaseUniversalTransform):\n    \"\"\"\n    Records the scheduled time on a run.\n\n    When a run enters a scheduled state, `run.next_scheduled_start_time` is set to\n    the state's scheduled time. When leaving a scheduled state,\n    `run.next_scheduled_start_time` is unset.\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # remove the next scheduled start time if exiting a scheduled state\n        if context.initial_state and context.initial_state.is_scheduled():\n            context.run.next_scheduled_start_time = None\n\n        # set next scheduled start time if entering a scheduled state\n        if context.proposed_state.is_scheduled():\n            context.run.next_scheduled_start_time = (\n                context.proposed_state.state_details.scheduled_time\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateSubflowParentTask","title":"<code>UpdateSubflowParentTask</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Whenever a subflow changes state, it must update its parent task run's state.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateSubflowParentTask(BaseUniversalTransform):\n    \"\"\"\n    Whenever a subflow changes state, it must update its parent task run's state.\n    \"\"\"\n\n    async def after_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # only applies to flow runs with a parent task run id\n        if context.run.parent_task_run_id is not None:\n            # avoid mutation of the flow run state\n            subflow_parent_task_state = context.validated_state.copy(\n                reset_fields=True,\n                include={\n                    \"type\",\n                    \"timestamp\",\n                    \"name\",\n                    \"message\",\n                    \"state_details\",\n                    \"data\",\n                },\n            )\n\n            # set the task's \"child flow run id\" to be the subflow run id\n            subflow_parent_task_state.state_details.child_flow_run_id = context.run.id\n\n            await models.task_runs.set_task_run_state(\n                session=context.session,\n                task_run_id=context.run.parent_task_run_id,\n                state=subflow_parent_task_state,\n                force=True,\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateSubflowStateDetails","title":"<code>UpdateSubflowStateDetails</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Update a child subflow state's references to a corresponding tracking task run id in the parent flow run</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateSubflowStateDetails(BaseUniversalTransform):\n    \"\"\"\n    Update a child subflow state's references to a corresponding tracking task run id\n    in the parent flow run\n    \"\"\"\n\n    async def before_transition(self, context: OrchestrationContext) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        # only applies to flow runs with a parent task run id\n        if context.run.parent_task_run_id is not None:\n            context.proposed_state.state_details.task_run_id = (\n                context.run.parent_task_run_id\n            )\n</code></pre>"},{"location":"api-ref/server/orchestration/global_policy/#prefect.server.orchestration.global_policy.UpdateStateDetails","title":"<code>UpdateStateDetails</code>","text":"<p>               Bases: <code>BaseUniversalTransform</code></p> <p>Update a state's references to a corresponding flow- or task- run.</p> Source code in <code>prefect/server/orchestration/global_policy.py</code> <pre><code>class UpdateStateDetails(BaseUniversalTransform):\n    \"\"\"\n    Update a state's references to a corresponding flow- or task- run.\n    \"\"\"\n\n    async def before_transition(\n        self,\n        context: OrchestrationContext,\n    ) -&gt; None:\n        if self.nullified_transition():\n            return\n\n        if isinstance(context, FlowOrchestrationContext):\n            flow_run = await context.flow_run()\n            context.proposed_state.state_details.flow_run_id = flow_run.id\n\n        elif isinstance(context, TaskOrchestrationContext):\n            task_run = await context.task_run()\n            context.proposed_state.state_details.flow_run_id = task_run.flow_run_id\n            context.proposed_state.state_details.task_run_id = task_run.id\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/","title":"server.orchestration.policies","text":""},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies","title":"<code>prefect.server.orchestration.policies</code>","text":"<p>Policies are collections of orchestration rules and transforms.</p> <p>Prefect implements (most) orchestration with logic that governs a Prefect flow or task changing state. Policies organize of orchestration logic both to provide an ordering mechanism as well as provide observability into the orchestration process.</p> <p>While Prefect's orchestration rules can gracefully run independently of one another, ordering can still have an impact on the observed behavior of the system. For example, it makes no sense to secure a concurrency slot for a run if a cached state exists. Furthermore, policies, provide a mechanism to configure and observe exactly what logic will fire against a transition.</p>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy","title":"<code>BaseOrchestrationPolicy</code>","text":"<p>               Bases: <code>ABC</code></p> <p>An abstract base class used to organize orchestration rules in priority order.</p> <p>Different collections of orchestration rules might be used to govern various kinds of transitions. For example, flow-run states and task-run states might require different orchestration logic.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>class BaseOrchestrationPolicy(ABC):\n    \"\"\"\n    An abstract base class used to organize orchestration rules in priority order.\n\n    Different collections of orchestration rules might be used to govern various kinds\n    of transitions. For example, flow-run states and task-run states might require\n    different orchestration logic.\n    \"\"\"\n\n    @staticmethod\n    @abstractmethod\n    def priority():\n        \"\"\"\n        A list of orchestration rules in priority order.\n        \"\"\"\n\n        return []\n\n    @classmethod\n    def compile_transition_rules(cls, from_state=None, to_state=None):\n        \"\"\"\n        Returns rules in policy that are valid for the specified state transition.\n        \"\"\"\n\n        transition_rules = []\n        for rule in cls.priority():\n            if from_state in rule.FROM_STATES and to_state in rule.TO_STATES:\n                transition_rules.append(rule)\n        return transition_rules\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy.priority","title":"<code>priority</code>  <code>abstractmethod</code> <code>staticmethod</code>","text":"<p>A list of orchestration rules in priority order.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>@staticmethod\n@abstractmethod\ndef priority():\n    \"\"\"\n    A list of orchestration rules in priority order.\n    \"\"\"\n\n    return []\n</code></pre>"},{"location":"api-ref/server/orchestration/policies/#prefect.server.orchestration.policies.BaseOrchestrationPolicy.compile_transition_rules","title":"<code>compile_transition_rules</code>  <code>classmethod</code>","text":"<p>Returns rules in policy that are valid for the specified state transition.</p> Source code in <code>prefect/server/orchestration/policies.py</code> <pre><code>@classmethod\ndef compile_transition_rules(cls, from_state=None, to_state=None):\n    \"\"\"\n    Returns rules in policy that are valid for the specified state transition.\n    \"\"\"\n\n    transition_rules = []\n    for rule in cls.priority():\n        if from_state in rule.FROM_STATES and to_state in rule.TO_STATES:\n            transition_rules.append(rule)\n    return transition_rules\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/","title":"server.orchestration.rules","text":""},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules","title":"<code>prefect.server.orchestration.rules</code>","text":"<p>Prefect's flow and task-run orchestration machinery.</p> <p>This module contains all the core concepts necessary to implement Prefect's state orchestration engine. These states correspond to intuitive descriptions of all the points that a Prefect flow or task can observe executing user code and intervene, if necessary. A detailed description of states can be found in our concept documentation.</p> <p>Prefect's orchestration engine operates under the assumption that no governed user code will execute without first requesting Prefect REST API validate a change in state and record metadata about the run. With all attempts to run user code being checked against a Prefect instance, the Prefect REST API database becomes the unambiguous source of truth for managing the execution of complex interacting workflows. Orchestration rules can be implemented as discrete units of logic that operate against each state transition and can be fully observable, extensible, and customizable -- all without needing to store or parse a single line of user code.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext","title":"<code>OrchestrationContext</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for a state transition, governed by orchestration rules.</p> Note <p>An <code>OrchestrationContext</code> should not be instantiated directly, instead use the flow- or task- specific subclasses, <code>FlowOrchestrationContext</code> and <code>TaskOrchestrationContext</code>.</p> <p>When a flow- or task- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>OrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <code>Optional[Union[Session, AsyncSession]]</code> <p>a SQLAlchemy database session</p> <code>initial_state</code> <code>Optional[State]</code> <p>the initial state of a run</p> <code>proposed_state</code> <code>Optional[State]</code> <p>the proposed state a run is transitioning into</p> <code>validated_state</code> <code>Optional[State]</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>List[str]</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>List[str]</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>SetStateStatus</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>StateResponseDetails</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class OrchestrationContext(PrefectBaseModel):\n    \"\"\"\n    A container for a state transition, governed by orchestration rules.\n\n    Note:\n        An `OrchestrationContext` should not be instantiated directly, instead\n        use the flow- or task- specific subclasses, `FlowOrchestrationContext` and\n        `TaskOrchestrationContext`.\n\n    When a flow- or task- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `OrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    class Config:\n        arbitrary_types_allowed = True\n\n    session: Optional[Union[sa.orm.Session, AsyncSession]] = ...\n    initial_state: Optional[states.State] = ...\n    proposed_state: Optional[states.State] = ...\n    validated_state: Optional[states.State]\n    rule_signature: List[str] = Field(default_factory=list)\n    finalization_signature: List[str] = Field(default_factory=list)\n    response_status: SetStateStatus = Field(default=SetStateStatus.ACCEPT)\n    response_details: StateResponseDetails = Field(default_factory=StateAcceptDetails)\n    orchestration_error: Optional[Exception] = Field(default=None)\n    parameters: Dict[Any, Any] = Field(default_factory=dict)\n\n    @property\n    def initial_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.initial_state` if it exists.\"\"\"\n\n        return self.initial_state.type if self.initial_state else None\n\n    @property\n    def proposed_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.proposed_state` if it exists.\"\"\"\n\n        return self.proposed_state.type if self.proposed_state else None\n\n    @property\n    def validated_state_type(self) -&gt; Optional[states.StateType]:\n        \"\"\"The state type of `self.validated_state` if it exists.\"\"\"\n        return self.validated_state.type if self.validated_state else None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Returns:\n            A mutation-safe copy of the `OrchestrationContext`\n        \"\"\"\n\n        safe_copy = self.copy()\n\n        safe_copy.initial_state = (\n            self.initial_state.copy() if self.initial_state else None\n        )\n        safe_copy.proposed_state = (\n            self.proposed_state.copy() if self.proposed_state else None\n        )\n        safe_copy.validated_state = (\n            self.validated_state.copy() if self.validated_state else None\n        )\n        safe_copy.parameters = self.parameters.copy()\n        return safe_copy\n\n    def entry_context(self):\n        \"\"\"\n        A convenience method that generates input parameters for orchestration rules.\n\n        An `OrchestrationContext` defines a state transition that is managed by\n        orchestration rules which can fire hooks before a transition has been committed\n        to the database. These hooks have a consistent interface which can be generated\n        with this method.\n        \"\"\"\n\n        safe_context = self.safe_copy()\n        return safe_context.initial_state, safe_context.proposed_state, safe_context\n\n    def exit_context(self):\n        \"\"\"\n        A convenience method that generates input parameters for orchestration rules.\n\n        An `OrchestrationContext` defines a state transition that is managed by\n        orchestration rules which can fire hooks after a transition has been committed\n        to the database. These hooks have a consistent interface which can be generated\n        with this method.\n        \"\"\"\n\n        safe_context = self.safe_copy()\n        return safe_context.initial_state, safe_context.validated_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.initial_state_type","title":"<code>initial_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.initial_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.proposed_state_type","title":"<code>proposed_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.proposed_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.validated_state_type","title":"<code>validated_state_type: Optional[states.StateType]</code>  <code>property</code>","text":"<p>The state type of <code>self.validated_state</code> if it exists.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of the <code>OrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Returns:\n        A mutation-safe copy of the `OrchestrationContext`\n    \"\"\"\n\n    safe_copy = self.copy()\n\n    safe_copy.initial_state = (\n        self.initial_state.copy() if self.initial_state else None\n    )\n    safe_copy.proposed_state = (\n        self.proposed_state.copy() if self.proposed_state else None\n    )\n    safe_copy.validated_state = (\n        self.validated_state.copy() if self.validated_state else None\n    )\n    safe_copy.parameters = self.parameters.copy()\n    return safe_copy\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.entry_context","title":"<code>entry_context</code>","text":"<p>A convenience method that generates input parameters for orchestration rules.</p> <p>An <code>OrchestrationContext</code> defines a state transition that is managed by orchestration rules which can fire hooks before a transition has been committed to the database. These hooks have a consistent interface which can be generated with this method.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def entry_context(self):\n    \"\"\"\n    A convenience method that generates input parameters for orchestration rules.\n\n    An `OrchestrationContext` defines a state transition that is managed by\n    orchestration rules which can fire hooks before a transition has been committed\n    to the database. These hooks have a consistent interface which can be generated\n    with this method.\n    \"\"\"\n\n    safe_context = self.safe_copy()\n    return safe_context.initial_state, safe_context.proposed_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.OrchestrationContext.exit_context","title":"<code>exit_context</code>","text":"<p>A convenience method that generates input parameters for orchestration rules.</p> <p>An <code>OrchestrationContext</code> defines a state transition that is managed by orchestration rules which can fire hooks after a transition has been committed to the database. These hooks have a consistent interface which can be generated with this method.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def exit_context(self):\n    \"\"\"\n    A convenience method that generates input parameters for orchestration rules.\n\n    An `OrchestrationContext` defines a state transition that is managed by\n    orchestration rules which can fire hooks after a transition has been committed\n    to the database. These hooks have a consistent interface which can be generated\n    with this method.\n    \"\"\"\n\n    safe_context = self.safe_copy()\n    return safe_context.initial_state, safe_context.validated_state, safe_context\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext","title":"<code>FlowOrchestrationContext</code>","text":"<p>               Bases: <code>OrchestrationContext</code></p> <p>A container for a flow run state transition, governed by orchestration rules.</p> <p>When a flow- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>FlowOrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <p>a SQLAlchemy database session</p> <code>run</code> <code>Any</code> <p>the flow run attempting to change state</p> <code>initial_state</code> <code>Any</code> <p>the initial state of the run</p> <code>proposed_state</code> <code>Any</code> <p>the proposed state the run is transitioning into</p> <code>validated_state</code> <code>Any</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>Any</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>Any</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>Any</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>Any</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>run</code> <p>the flow run attempting to change state</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class FlowOrchestrationContext(OrchestrationContext):\n    \"\"\"\n    A container for a flow run state transition, governed by orchestration rules.\n\n    When a flow- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `FlowOrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        run: the flow run attempting to change state\n        initial_state: the initial state of the run\n        proposed_state: the proposed state the run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        run: the flow run attempting to change state\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    # run: db.FlowRun = ...\n    run: Any = ...\n\n    @inject_db\n    async def validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        \"\"\"\n        Validates a proposed state by committing it to the database.\n\n        After the `FlowOrchestrationContext` is governed by orchestration rules, the\n        proposed state can be validated: the proposed state is added to the current\n        SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n        state. The state on the run is set to the validated state as well.\n\n        If the proposed state is `None` when this method is called, no state will be\n        written and `self.validated_state` will be set to the run's current state.\n\n        Returns:\n            None\n        \"\"\"\n        # (circular import)\n        from prefect.server.api.server import is_client_retryable_exception\n\n        try:\n            await self._validate_proposed_state()\n            return\n        except Exception as exc:\n            logger.exception(\"Encountered error during state validation\")\n            self.proposed_state = None\n\n            if is_client_retryable_exception(exc):\n                # Do not capture retryable database exceptions, this exception will be\n                # raised as a 503 in the API layer\n                raise\n\n            reason = f\"Error validating state: {exc!r}\"\n            self.response_status = SetStateStatus.ABORT\n            self.response_details = StateAbortDetails(reason=reason)\n\n    @inject_db\n    async def _validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        if self.proposed_state is None:\n            validated_orm_state = self.run.state\n            # We cannot access `self.run.state.data` directly for unknown reasons\n            state_data = (\n                (\n                    await artifacts.read_artifact(\n                        self.session, self.run.state.result_artifact_id\n                    )\n                ).data\n                if self.run.state.result_artifact_id\n                else None\n            )\n        else:\n            state_payload = self.proposed_state.dict(shallow=True)\n            state_data = state_payload.pop(\"data\", None)\n\n            if state_data is not None and not (\n                isinstance(state_data, dict) and state_data.get(\"type\") == \"unpersisted\"\n            ):\n                state_result_artifact = core.Artifact.from_result(state_data)\n                state_result_artifact.flow_run_id = self.run.id\n                await artifacts.create_artifact(self.session, state_result_artifact)\n                state_payload[\"result_artifact_id\"] = state_result_artifact.id\n\n            validated_orm_state = db.FlowRunState(\n                flow_run_id=self.run.id,\n                **state_payload,\n            )\n\n        self.session.add(validated_orm_state)\n        self.run.set_state(validated_orm_state)\n\n        await self.session.flush()\n        if validated_orm_state:\n            self.validated_state = states.State.from_orm_without_result(\n                validated_orm_state, with_data=state_data\n            )\n        else:\n            self.validated_state = None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Note:\n            `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n        Returns:\n            A mutation-safe copy of `FlowOrchestrationContext`\n        \"\"\"\n\n        return super().safe_copy()\n\n    @property\n    def run_settings(self) -&gt; Dict:\n        \"\"\"Run-level settings used to orchestrate the state transition.\"\"\"\n\n        return self.run.empirical_policy\n\n    async def task_run(self):\n        return None\n\n    async def flow_run(self):\n        return self.run\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.run_settings","title":"<code>run_settings: Dict</code>  <code>property</code>","text":"<p>Run-level settings used to orchestrate the state transition.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.validate_proposed_state","title":"<code>validate_proposed_state</code>  <code>async</code>","text":"<p>Validates a proposed state by committing it to the database.</p> <p>After the <code>FlowOrchestrationContext</code> is governed by orchestration rules, the proposed state can be validated: the proposed state is added to the current SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed state. The state on the run is set to the validated state as well.</p> <p>If the proposed state is <code>None</code> when this method is called, no state will be written and <code>self.validated_state</code> will be set to the run's current state.</p> <p>Returns:</p> Type Description <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>@inject_db\nasync def validate_proposed_state(\n    self,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Validates a proposed state by committing it to the database.\n\n    After the `FlowOrchestrationContext` is governed by orchestration rules, the\n    proposed state can be validated: the proposed state is added to the current\n    SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n    state. The state on the run is set to the validated state as well.\n\n    If the proposed state is `None` when this method is called, no state will be\n    written and `self.validated_state` will be set to the run's current state.\n\n    Returns:\n        None\n    \"\"\"\n    # (circular import)\n    from prefect.server.api.server import is_client_retryable_exception\n\n    try:\n        await self._validate_proposed_state()\n        return\n    except Exception as exc:\n        logger.exception(\"Encountered error during state validation\")\n        self.proposed_state = None\n\n        if is_client_retryable_exception(exc):\n            # Do not capture retryable database exceptions, this exception will be\n            # raised as a 503 in the API layer\n            raise\n\n        reason = f\"Error validating state: {exc!r}\"\n        self.response_status = SetStateStatus.ABORT\n        self.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.FlowOrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> Note <p><code>self.run</code> is an ORM model, and even when copied is unsafe to mutate</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of <code>FlowOrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Note:\n        `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n    Returns:\n        A mutation-safe copy of `FlowOrchestrationContext`\n    \"\"\"\n\n    return super().safe_copy()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext","title":"<code>TaskOrchestrationContext</code>","text":"<p>               Bases: <code>OrchestrationContext</code></p> <p>A container for a task run state transition, governed by orchestration rules.</p> <p>When a task- run attempts to change state, Prefect REST API has an opportunity to decide whether this transition can proceed. All the relevant information associated with the state transition is stored in an <code>OrchestrationContext</code>, which is subsequently governed by nested orchestration rules implemented using the <code>BaseOrchestrationRule</code> ABC.</p> <p><code>TaskOrchestrationContext</code> introduces the concept of a state being <code>None</code> in the context of an intended state transition. An initial state can be <code>None</code> if a run is is attempting to set a state for the first time. The proposed state might be <code>None</code> if a rule governing the transition determines that no state change should occur at all and nothing is written to the database.</p> <p>Attributes:</p> Name Type Description <code>session</code> <p>a SQLAlchemy database session</p> <code>run</code> <code>Any</code> <p>the task run attempting to change state</p> <code>initial_state</code> <code>Any</code> <p>the initial state of the run</p> <code>proposed_state</code> <code>Any</code> <p>the proposed state the run is transitioning into</p> <code>validated_state</code> <code>Any</code> <p>a proposed state that has committed to the database</p> <code>rule_signature</code> <code>Any</code> <p>a record of rules that have fired on entry into a managed context, currently only used for debugging purposes</p> <code>finalization_signature</code> <code>Any</code> <p>a record of rules that have fired on exit from a managed context, currently only used for debugging purposes</p> <code>response_status</code> <code>Any</code> <p>a SetStateStatus object used to build the API response</p> <code>response_details</code> <code>Any</code> <p>a StateResponseDetails object use to build the API response</p> <p>Parameters:</p> Name Type Description Default <code>session</code> <p>a SQLAlchemy database session</p> required <code>run</code> <p>the task run attempting to change state</p> required <code>initial_state</code> <p>the initial state of a run</p> required <code>proposed_state</code> <p>the proposed state a run is transitioning into</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class TaskOrchestrationContext(OrchestrationContext):\n    \"\"\"\n    A container for a task run state transition, governed by orchestration rules.\n\n    When a task- run attempts to change state, Prefect REST API has an opportunity\n    to decide whether this transition can proceed. All the relevant information\n    associated with the state transition is stored in an `OrchestrationContext`,\n    which is subsequently governed by nested orchestration rules implemented using\n    the `BaseOrchestrationRule` ABC.\n\n    `TaskOrchestrationContext` introduces the concept of a state being `None` in the\n    context of an intended state transition. An initial state can be `None` if a run\n    is is attempting to set a state for the first time. The proposed state might be\n    `None` if a rule governing the transition determines that no state change\n    should occur at all and nothing is written to the database.\n\n    Attributes:\n        session: a SQLAlchemy database session\n        run: the task run attempting to change state\n        initial_state: the initial state of the run\n        proposed_state: the proposed state the run is transitioning into\n        validated_state: a proposed state that has committed to the database\n        rule_signature: a record of rules that have fired on entry into a\n            managed context, currently only used for debugging purposes\n        finalization_signature: a record of rules that have fired on exit from a\n            managed context, currently only used for debugging purposes\n        response_status: a SetStateStatus object used to build the API response\n        response_details:a StateResponseDetails object use to build the API response\n\n    Args:\n        session: a SQLAlchemy database session\n        run: the task run attempting to change state\n        initial_state: the initial state of a run\n        proposed_state: the proposed state a run is transitioning into\n    \"\"\"\n\n    # run: db.TaskRun = ...\n    run: Any = ...\n\n    @inject_db\n    async def validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        \"\"\"\n        Validates a proposed state by committing it to the database.\n\n        After the `TaskOrchestrationContext` is governed by orchestration rules, the\n        proposed state can be validated: the proposed state is added to the current\n        SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n        state. The state on the run is set to the validated state as well.\n\n        If the proposed state is `None` when this method is called, no state will be\n        written and `self.validated_state` will be set to the run's current state.\n\n        Returns:\n            None\n        \"\"\"\n        # (circular import)\n        from prefect.server.api.server import is_client_retryable_exception\n\n        try:\n            await self._validate_proposed_state()\n            return\n        except Exception as exc:\n            logger.exception(\"Encountered error during state validation\")\n            self.proposed_state = None\n\n            if is_client_retryable_exception(exc):\n                # Do not capture retryable database exceptions, this exception will be\n                # raised as a 503 in the API layer\n                raise\n\n            reason = f\"Error validating state: {exc!r}\"\n            self.response_status = SetStateStatus.ABORT\n            self.response_details = StateAbortDetails(reason=reason)\n\n    @inject_db\n    async def _validate_proposed_state(\n        self,\n        db: PrefectDBInterface,\n    ):\n        if self.proposed_state is None:\n            validated_orm_state = self.run.state\n            # We cannot access `self.run.state.data` directly for unknown reasons\n            state_data = (\n                (\n                    await artifacts.read_artifact(\n                        self.session, self.run.state.result_artifact_id\n                    )\n                ).data\n                if self.run.state.result_artifact_id\n                else None\n            )\n        else:\n            state_payload = self.proposed_state.dict(shallow=True)\n            state_data = state_payload.pop(\"data\", None)\n\n            if state_data is not None and not (\n                isinstance(state_data, dict) and state_data.get(\"type\") == \"unpersisted\"\n            ):\n                state_result_artifact = core.Artifact.from_result(state_data)\n                state_result_artifact.task_run_id = self.run.id\n\n                if self.run.flow_run_id is not None:\n                    flow_run = await self.flow_run()\n                    state_result_artifact.flow_run_id = flow_run.id\n\n                await artifacts.create_artifact(self.session, state_result_artifact)\n                state_payload[\"result_artifact_id\"] = state_result_artifact.id\n\n            validated_orm_state = db.TaskRunState(\n                task_run_id=self.run.id,\n                **state_payload,\n            )\n\n        self.session.add(validated_orm_state)\n        self.run.set_state(validated_orm_state)\n\n        await self.session.flush()\n        if validated_orm_state:\n            self.validated_state = states.State.from_orm_without_result(\n                validated_orm_state, with_data=state_data\n            )\n        else:\n            self.validated_state = None\n\n    def safe_copy(self):\n        \"\"\"\n        Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n        Orchestration rules govern state transitions using information stored in\n        an `OrchestrationContext`. However, mutating objects stored on the context\n        directly can have unintended side-effects. To guard against this,\n        `self.safe_copy` can be used to pass information to orchestration rules\n        without risking mutation.\n\n        Note:\n            `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n        Returns:\n            A mutation-safe copy of `TaskOrchestrationContext`\n        \"\"\"\n\n        return super().safe_copy()\n\n    @property\n    def run_settings(self) -&gt; Dict:\n        \"\"\"Run-level settings used to orchestrate the state transition.\"\"\"\n\n        return self.run.empirical_policy\n\n    async def task_run(self):\n        return self.run\n\n    async def flow_run(self):\n        return await flow_runs.read_flow_run(\n            session=self.session,\n            flow_run_id=self.run.flow_run_id,\n        )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.run_settings","title":"<code>run_settings: Dict</code>  <code>property</code>","text":"<p>Run-level settings used to orchestrate the state transition.</p>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.validate_proposed_state","title":"<code>validate_proposed_state</code>  <code>async</code>","text":"<p>Validates a proposed state by committing it to the database.</p> <p>After the <code>TaskOrchestrationContext</code> is governed by orchestration rules, the proposed state can be validated: the proposed state is added to the current SQLAlchemy session and is flushed. <code>self.validated_state</code> set to the flushed state. The state on the run is set to the validated state as well.</p> <p>If the proposed state is <code>None</code> when this method is called, no state will be written and <code>self.validated_state</code> will be set to the run's current state.</p> <p>Returns:</p> Type Description <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>@inject_db\nasync def validate_proposed_state(\n    self,\n    db: PrefectDBInterface,\n):\n    \"\"\"\n    Validates a proposed state by committing it to the database.\n\n    After the `TaskOrchestrationContext` is governed by orchestration rules, the\n    proposed state can be validated: the proposed state is added to the current\n    SQLAlchemy session and is flushed. `self.validated_state` set to the flushed\n    state. The state on the run is set to the validated state as well.\n\n    If the proposed state is `None` when this method is called, no state will be\n    written and `self.validated_state` will be set to the run's current state.\n\n    Returns:\n        None\n    \"\"\"\n    # (circular import)\n    from prefect.server.api.server import is_client_retryable_exception\n\n    try:\n        await self._validate_proposed_state()\n        return\n    except Exception as exc:\n        logger.exception(\"Encountered error during state validation\")\n        self.proposed_state = None\n\n        if is_client_retryable_exception(exc):\n            # Do not capture retryable database exceptions, this exception will be\n            # raised as a 503 in the API layer\n            raise\n\n        reason = f\"Error validating state: {exc!r}\"\n        self.response_status = SetStateStatus.ABORT\n        self.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.TaskOrchestrationContext.safe_copy","title":"<code>safe_copy</code>","text":"<p>Creates a mostly-mutation-safe copy for use in orchestration rules.</p> <p>Orchestration rules govern state transitions using information stored in an <code>OrchestrationContext</code>. However, mutating objects stored on the context directly can have unintended side-effects. To guard against this, <code>self.safe_copy</code> can be used to pass information to orchestration rules without risking mutation.</p> Note <p><code>self.run</code> is an ORM model, and even when copied is unsafe to mutate</p> <p>Returns:</p> Type Description <p>A mutation-safe copy of <code>TaskOrchestrationContext</code></p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def safe_copy(self):\n    \"\"\"\n    Creates a mostly-mutation-safe copy for use in orchestration rules.\n\n    Orchestration rules govern state transitions using information stored in\n    an `OrchestrationContext`. However, mutating objects stored on the context\n    directly can have unintended side-effects. To guard against this,\n    `self.safe_copy` can be used to pass information to orchestration rules\n    without risking mutation.\n\n    Note:\n        `self.run` is an ORM model, and even when copied is unsafe to mutate\n\n    Returns:\n        A mutation-safe copy of `TaskOrchestrationContext`\n    \"\"\"\n\n    return super().safe_copy()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule","title":"<code>BaseOrchestrationRule</code>","text":"<p>               Bases: <code>AbstractAsyncContextManager</code></p> <p>An abstract base class used to implement a discrete piece of orchestration logic.</p> <p>An <code>OrchestrationRule</code> is a stateful context manager that directly governs a state transition. Complex orchestration is achieved by nesting multiple rules. Each rule runs against an <code>OrchestrationContext</code> that contains the transition details; this context is then passed to subsequent rules. The context can be modified by hooks that fire before and after a new state is validated and committed to the database. These hooks will fire as long as the state transition is considered \"valid\" and govern a transition by either modifying the proposed state before it is validated or by producing a side-effect.</p> <p>A state transition occurs whenever a flow- or task- run changes state, prompting Prefect REST API to decide whether or not this transition can proceed. The current state of the run is referred to as the \"initial state\", and the state a run is attempting to transition into is the \"proposed state\". Together, the initial state transitioning into the proposed state is the intended transition that is governed by these orchestration rules. After using rules to enter a runtime context, the <code>OrchestrationContext</code> will contain a proposed state that has been governed by each rule, and at that point can validate the proposed state and commit it to the database. The validated state will be set on the context as <code>context.validated_state</code>, and rules will call the <code>self.after_transition</code> hook upon exiting the managed context.</p> <p>Examples:</p> <pre><code>Create a rule:\n\n&gt;&gt;&gt; class BasicRule(BaseOrchestrationRule):\n&gt;&gt;&gt;     # allowed initial state types\n&gt;&gt;&gt;     FROM_STATES = [StateType.RUNNING]\n&gt;&gt;&gt;     # allowed proposed state types\n&gt;&gt;&gt;     TO_STATES = [StateType.COMPLETED, StateType.FAILED]\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def before_transition(initial_state, proposed_state, ctx):\n&gt;&gt;&gt;         # side effects and proposed state mutation can happen here\n&gt;&gt;&gt;         ...\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def after_transition(initial_state, validated_state, ctx):\n&gt;&gt;&gt;         # operations on states that have been validated can happen here\n&gt;&gt;&gt;         ...\n&gt;&gt;&gt;\n&gt;&gt;&gt;     async def cleanup(intitial_state, validated_state, ctx):\n&gt;&gt;&gt;         # reverts side effects generated by `before_transition` if necessary\n&gt;&gt;&gt;         ...\n\nUse a rule:\n\n&gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n&gt;&gt;&gt; async with BasicRule(context, *intended_transition):\n&gt;&gt;&gt;     # context.proposed_state has been governed by BasicRule\n&gt;&gt;&gt;     ...\n\nUse multiple rules:\n\n&gt;&gt;&gt; rules = [BasicRule, BasicRule]\n&gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n&gt;&gt;&gt; async with contextlib.AsyncExitStack() as stack:\n&gt;&gt;&gt;     for rule in rules:\n&gt;&gt;&gt;         stack.enter_async_context(rule(context, *intended_transition))\n&gt;&gt;&gt;\n&gt;&gt;&gt;     # context.proposed_state has been governed by all rules\n&gt;&gt;&gt;     ...\n</code></pre> <p>Attributes:</p> Name Type Description <code>FROM_STATES</code> <code>Iterable</code> <p>list of valid initial state types this rule governs</p> <code>TO_STATES</code> <code>Iterable</code> <p>list of valid proposed state types this rule governs</p> <code>context</code> <p>the orchestration context</p> <code>from_state_type</code> <p>the state type a run is currently in</p> <code>to_state_type</code> <p>the intended proposed state type prior to any orchestration</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>OrchestrationContext</code> <p>A <code>FlowOrchestrationContext</code> or <code>TaskOrchestrationContext</code> that is passed between rules</p> required <code>from_state_type</code> <code>Optional[StateType]</code> <p>The state type of the initial state of a run, if this state type is not contained in <code>FROM_STATES</code>, no hooks will fire</p> required <code>to_state_type</code> <code>Optional[StateType]</code> <p>The state type of the proposed state before orchestration, if this state type is not contained in <code>TO_STATES</code>, no hooks will fire</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class BaseOrchestrationRule(contextlib.AbstractAsyncContextManager):\n    \"\"\"\n    An abstract base class used to implement a discrete piece of orchestration logic.\n\n    An `OrchestrationRule` is a stateful context manager that directly governs a state\n    transition. Complex orchestration is achieved by nesting multiple rules.\n    Each rule runs against an `OrchestrationContext` that contains the transition\n    details; this context is then passed to subsequent rules. The context can be\n    modified by hooks that fire before and after a new state is validated and committed\n    to the database. These hooks will fire as long as the state transition is\n    considered \"valid\" and govern a transition by either modifying the proposed state\n    before it is validated or by producing a side-effect.\n\n    A state transition occurs whenever a flow- or task- run changes state, prompting\n    Prefect REST API to decide whether or not this transition can proceed. The current state of\n    the run is referred to as the \"initial state\", and the state a run is\n    attempting to transition into is the \"proposed state\". Together, the initial state\n    transitioning into the proposed state is the intended transition that is governed\n    by these orchestration rules. After using rules to enter a runtime context, the\n    `OrchestrationContext` will contain a proposed state that has been governed by\n    each rule, and at that point can validate the proposed state and commit it to\n    the database. The validated state will be set on the context as\n    `context.validated_state`, and rules will call the `self.after_transition` hook\n    upon exiting the managed context.\n\n    Examples:\n\n        Create a rule:\n\n        &gt;&gt;&gt; class BasicRule(BaseOrchestrationRule):\n        &gt;&gt;&gt;     # allowed initial state types\n        &gt;&gt;&gt;     FROM_STATES = [StateType.RUNNING]\n        &gt;&gt;&gt;     # allowed proposed state types\n        &gt;&gt;&gt;     TO_STATES = [StateType.COMPLETED, StateType.FAILED]\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def before_transition(initial_state, proposed_state, ctx):\n        &gt;&gt;&gt;         # side effects and proposed state mutation can happen here\n        &gt;&gt;&gt;         ...\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def after_transition(initial_state, validated_state, ctx):\n        &gt;&gt;&gt;         # operations on states that have been validated can happen here\n        &gt;&gt;&gt;         ...\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     async def cleanup(intitial_state, validated_state, ctx):\n        &gt;&gt;&gt;         # reverts side effects generated by `before_transition` if necessary\n        &gt;&gt;&gt;         ...\n\n        Use a rule:\n\n        &gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n        &gt;&gt;&gt; async with BasicRule(context, *intended_transition):\n        &gt;&gt;&gt;     # context.proposed_state has been governed by BasicRule\n        &gt;&gt;&gt;     ...\n\n        Use multiple rules:\n\n        &gt;&gt;&gt; rules = [BasicRule, BasicRule]\n        &gt;&gt;&gt; intended_transition = (StateType.RUNNING, StateType.COMPLETED)\n        &gt;&gt;&gt; async with contextlib.AsyncExitStack() as stack:\n        &gt;&gt;&gt;     for rule in rules:\n        &gt;&gt;&gt;         stack.enter_async_context(rule(context, *intended_transition))\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;     # context.proposed_state has been governed by all rules\n        &gt;&gt;&gt;     ...\n\n    Attributes:\n        FROM_STATES: list of valid initial state types this rule governs\n        TO_STATES: list of valid proposed state types this rule governs\n        context: the orchestration context\n        from_state_type: the state type a run is currently in\n        to_state_type: the intended proposed state type prior to any orchestration\n\n    Args:\n        context: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is\n            passed between rules\n        from_state_type: The state type of the initial state of a run, if this\n            state type is not contained in `FROM_STATES`, no hooks will fire\n        to_state_type: The state type of the proposed state before orchestration, if\n            this state type is not contained in `TO_STATES`, no hooks will fire\n    \"\"\"\n\n    FROM_STATES: Iterable = []\n    TO_STATES: Iterable = []\n\n    def __init__(\n        self,\n        context: OrchestrationContext,\n        from_state_type: Optional[states.StateType],\n        to_state_type: Optional[states.StateType],\n    ):\n        self.context = context\n        self.from_state_type = from_state_type\n        self.to_state_type = to_state_type\n        self._invalid_on_entry = None\n\n    async def __aenter__(self) -&gt; OrchestrationContext:\n        \"\"\"\n        Enter an async runtime context governed by this rule.\n\n        The `with` statement will bind a governed `OrchestrationContext` to the target\n        specified by the `as` clause. If the transition proposed by the\n        `OrchestrationContext` is considered invalid on entry, entering this context\n        will do nothing. Otherwise, `self.before_transition` will fire.\n        \"\"\"\n\n        if await self.invalid():\n            pass\n        else:\n            try:\n                entry_context = self.context.entry_context()\n                await self.before_transition(*entry_context)\n                self.context.rule_signature.append(str(self.__class__))\n            except Exception as before_transition_error:\n                reason = (\n                    f\"Aborting orchestration due to error in {self.__class__!r}:\"\n                    f\" !{before_transition_error!r}\"\n                )\n                logger.exception(\n                    f\"Error running before-transition hook in rule {self.__class__!r}:\"\n                    f\" !{before_transition_error!r}\"\n                )\n\n                self.context.proposed_state = None\n                self.context.response_status = SetStateStatus.ABORT\n                self.context.response_details = StateAbortDetails(reason=reason)\n                self.context.orchestration_error = before_transition_error\n\n        return self.context\n\n    async def __aexit__(\n        self,\n        exc_type: Optional[Type[BaseException]],\n        exc_val: Optional[BaseException],\n        exc_tb: Optional[TracebackType],\n    ) -&gt; None:\n        \"\"\"\n        Exit the async runtime context governed by this rule.\n\n        One of three outcomes can happen upon exiting this rule's context depending on\n        the state of the rule. If the rule was found to be invalid on entry, nothing\n        happens. If the rule was valid on entry and continues to be valid on exit,\n        `self.after_transition` will fire. If the rule was valid on entry but invalid\n        on exit, the rule will \"fizzle\" and `self.cleanup` will fire in order to revert\n        any side-effects produced by `self.before_transition`.\n        \"\"\"\n\n        exit_context = self.context.exit_context()\n        if await self.invalid():\n            pass\n        elif await self.fizzled():\n            await self.cleanup(*exit_context)\n        else:\n            await self.after_transition(*exit_context)\n            self.context.finalization_signature.append(str(self.__class__))\n\n    async def before_transition(\n        self,\n        initial_state: Optional[states.State],\n        proposed_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire before a state is committed to the database.\n\n        This hook may produce side-effects or mutate the proposed state of a\n        transition using one of four methods: `self.reject_transition`,\n        `self.delay_transition`, `self.abort_transition`, and `self.rename_state`.\n\n        Note:\n            As currently implemented, the `before_transition` hook is not\n            perfectly isolated from mutating the transition. It is a standard instance\n            method that has access to `self`, and therefore `self.context`. This should\n            never be modified directly. Furthermore, `context.run` is an ORM model, and\n            mutating the run can also cause unintended writes to the database.\n\n        Args:\n            initial_state: The initial state of a transition\n            proposed_state: The proposed state of a transition\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def after_transition(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        Args:\n            initial_state: The initial state of a transition\n            validated_state: The governed state that has been committed to the database\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def cleanup(\n        self,\n        initial_state: Optional[states.State],\n        validated_state: Optional[states.State],\n        context: OrchestrationContext,\n    ) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        The intended use of this method is to revert side-effects produced by\n        `self.before_transition` when the transition is found to be invalid on exit.\n        This allows multiple rules to be gracefully run in sequence, without logic that\n        keeps track of all other rules that might govern a transition.\n\n        Args:\n            initial_state: The initial state of a transition\n            validated_state: The governed state that has been committed to the database\n            context: A safe copy of the `OrchestrationContext`, with the exception of\n                `context.run`, mutating this context will have no effect on the broader\n                orchestration environment.\n\n        Returns:\n            None\n        \"\"\"\n\n    async def invalid(self) -&gt; bool:\n        \"\"\"\n        Determines if a rule is invalid.\n\n        Invalid rules do nothing and no hooks fire upon entering or exiting a governed\n        context. Rules are invalid if the transition states types are not contained in\n        `self.FROM_STATES` and `self.TO_STATES`, or if the context is proposing\n        a transition that differs from the transition the rule was instantiated with.\n\n        Returns:\n            True if the rules in invalid, False otherwise.\n        \"\"\"\n        # invalid and fizzled states are mutually exclusive,\n        # `_invalid_on_entry` holds this statefulness\n        if self.from_state_type not in self.FROM_STATES:\n            self._invalid_on_entry = True\n        if self.to_state_type not in self.TO_STATES:\n            self._invalid_on_entry = True\n\n        if self._invalid_on_entry is None:\n            self._invalid_on_entry = await self.invalid_transition()\n        return self._invalid_on_entry\n\n    async def fizzled(self) -&gt; bool:\n        \"\"\"\n        Determines if a rule is fizzled and side-effects need to be reverted.\n\n        Rules are fizzled if the transitions were valid on entry (thus firing\n        `self.before_transition`) but are invalid upon exiting the governed context,\n        most likely caused by another rule mutating the transition.\n\n        Returns:\n            True if the rule is fizzled, False otherwise.\n        \"\"\"\n\n        if self._invalid_on_entry:\n            return False\n        return await self.invalid_transition()\n\n    async def invalid_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition proposed by the `OrchestrationContext` is invalid.\n\n        If the `OrchestrationContext` is attempting to manage a transition with this\n        rule that differs from the transition the rule was instantiated with, the\n        transition is considered to be invalid. Depending on the context, a rule with an\n        invalid transition is either \"invalid\" or \"fizzled\".\n\n        Returns:\n            True if the transition is invalid, False otherwise.\n        \"\"\"\n\n        initial_state_type = self.context.initial_state_type\n        proposed_state_type = self.context.proposed_state_type\n        return (self.from_state_type != initial_state_type) or (\n            self.to_state_type != proposed_state_type\n        )\n\n    async def reject_transition(self, state: Optional[states.State], reason: str):\n        \"\"\"\n        Rejects a proposed transition before the transition is validated.\n\n        This method will reject a proposed transition, mutating the proposed state to\n        the provided `state`. A reason for rejecting the transition is also passed on\n        to the `OrchestrationContext`. Rules that reject the transition will not fizzle,\n        despite the proposed state type changing.\n\n        Args:\n            state: The new proposed state. If `None`, the current run state will be\n                returned in the result instead.\n            reason: The reason for rejecting the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # the current state will be used if a new one is not provided\n        if state is None:\n            if self.from_state_type is None:\n                raise OrchestrationError(\n                    \"The current run has no state; this transition cannot be \"\n                    \"rejected without providing a new state.\"\n                )\n            self.to_state_type = None\n            self.context.proposed_state = None\n        else:\n            # a rule that mutates state should not fizzle itself\n            self.to_state_type = state.type\n            self.context.proposed_state = state\n\n        self.context.response_status = SetStateStatus.REJECT\n        self.context.response_details = StateRejectDetails(reason=reason)\n\n    async def delay_transition(\n        self,\n        delay_seconds: int,\n        reason: str,\n    ):\n        \"\"\"\n        Delays a proposed transition before the transition is validated.\n\n        This method will delay a proposed transition, setting the proposed state to\n        `None`, signaling to the `OrchestrationContext` that no state should be\n        written to the database. The number of seconds a transition should be delayed is\n        passed to the `OrchestrationContext`. A reason for delaying the transition is\n        also provided. Rules that delay the transition will not fizzle, despite the\n        proposed state type changing.\n\n        Args:\n            delay_seconds: The number of seconds the transition should be delayed\n            reason: The reason for delaying the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = None\n        self.context.proposed_state = None\n        self.context.response_status = SetStateStatus.WAIT\n        self.context.response_details = StateWaitDetails(\n            delay_seconds=delay_seconds, reason=reason\n        )\n\n    async def abort_transition(self, reason: str):\n        \"\"\"\n        Aborts a proposed transition before the transition is validated.\n\n        This method will abort a proposed transition, expecting no further action to\n        occur for this run. The proposed state is set to `None`, signaling to the\n        `OrchestrationContext` that no state should be written to the database. A\n        reason for aborting the transition is also provided. Rules that abort the\n        transition will not fizzle, despite the proposed state type changing.\n\n        Args:\n            reason: The reason for aborting the transition\n        \"\"\"\n\n        # don't run if the transition is already validated\n        if self.context.validated_state:\n            raise RuntimeError(\"The transition is already validated\")\n\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = None\n        self.context.proposed_state = None\n        self.context.response_status = SetStateStatus.ABORT\n        self.context.response_details = StateAbortDetails(reason=reason)\n\n    async def rename_state(self, state_name):\n        \"\"\"\n        Sets the \"name\" attribute on a proposed state.\n\n        The name of a state is an annotation intended to provide rich, human-readable\n        context for how a run is progressing. This method only updates the name and not\n        the canonical state TYPE, and will not fizzle or invalidate any other rules\n        that might govern this state transition.\n        \"\"\"\n        if self.context.proposed_state is not None:\n            self.context.proposed_state.name = state_name\n\n    async def update_context_parameters(self, key, value):\n        \"\"\"\n        Updates the \"parameters\" dictionary attribute with the specified key-value pair.\n\n        This mechanism streamlines the process of passing messages and information\n        between orchestration rules if necessary and is simpler and more ephemeral than\n        message-passing via the database or some other side-effect. This mechanism can\n        be used to break up large rules for ease of testing or comprehension, but note\n        that any rules coupled this way (or any other way) are no longer independent and\n        the order in which they appear in the orchestration policy priority will matter.\n        \"\"\"\n\n        self.context.parameters.update({key: value})\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.before_transition","title":"<code>before_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire before a state is committed to the database.</p> <p>This hook may produce side-effects or mutate the proposed state of a transition using one of four methods: <code>self.reject_transition</code>, <code>self.delay_transition</code>, <code>self.abort_transition</code>, and <code>self.rename_state</code>.</p> Note <p>As currently implemented, the <code>before_transition</code> hook is not perfectly isolated from mutating the transition. It is a standard instance method that has access to <code>self</code>, and therefore <code>self.context</code>. This should never be modified directly. Furthermore, <code>context.run</code> is an ORM model, and mutating the run can also cause unintended writes to the database.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>proposed_state</code> <code>Optional[State]</code> <p>The proposed state of a transition</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def before_transition(\n    self,\n    initial_state: Optional[states.State],\n    proposed_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire before a state is committed to the database.\n\n    This hook may produce side-effects or mutate the proposed state of a\n    transition using one of four methods: `self.reject_transition`,\n    `self.delay_transition`, `self.abort_transition`, and `self.rename_state`.\n\n    Note:\n        As currently implemented, the `before_transition` hook is not\n        perfectly isolated from mutating the transition. It is a standard instance\n        method that has access to `self`, and therefore `self.context`. This should\n        never be modified directly. Furthermore, `context.run` is an ORM model, and\n        mutating the run can also cause unintended writes to the database.\n\n    Args:\n        initial_state: The initial state of a transition\n        proposed_state: The proposed state of a transition\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.after_transition","title":"<code>after_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>validated_state</code> <code>Optional[State]</code> <p>The governed state that has been committed to the database</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def after_transition(\n    self,\n    initial_state: Optional[states.State],\n    validated_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    Args:\n        initial_state: The initial state of a transition\n        validated_state: The governed state that has been committed to the database\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.cleanup","title":"<code>cleanup</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>The intended use of this method is to revert side-effects produced by <code>self.before_transition</code> when the transition is found to be invalid on exit. This allows multiple rules to be gracefully run in sequence, without logic that keeps track of all other rules that might govern a transition.</p> <p>Parameters:</p> Name Type Description Default <code>initial_state</code> <code>Optional[State]</code> <p>The initial state of a transition</p> required <code>validated_state</code> <code>Optional[State]</code> <p>The governed state that has been committed to the database</p> required <code>context</code> <code>OrchestrationContext</code> <p>A safe copy of the <code>OrchestrationContext</code>, with the exception of <code>context.run</code>, mutating this context will have no effect on the broader orchestration environment.</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def cleanup(\n    self,\n    initial_state: Optional[states.State],\n    validated_state: Optional[states.State],\n    context: OrchestrationContext,\n) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    The intended use of this method is to revert side-effects produced by\n    `self.before_transition` when the transition is found to be invalid on exit.\n    This allows multiple rules to be gracefully run in sequence, without logic that\n    keeps track of all other rules that might govern a transition.\n\n    Args:\n        initial_state: The initial state of a transition\n        validated_state: The governed state that has been committed to the database\n        context: A safe copy of the `OrchestrationContext`, with the exception of\n            `context.run`, mutating this context will have no effect on the broader\n            orchestration environment.\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.invalid","title":"<code>invalid</code>  <code>async</code>","text":"<p>Determines if a rule is invalid.</p> <p>Invalid rules do nothing and no hooks fire upon entering or exiting a governed context. Rules are invalid if the transition states types are not contained in <code>self.FROM_STATES</code> and <code>self.TO_STATES</code>, or if the context is proposing a transition that differs from the transition the rule was instantiated with.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the rules in invalid, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def invalid(self) -&gt; bool:\n    \"\"\"\n    Determines if a rule is invalid.\n\n    Invalid rules do nothing and no hooks fire upon entering or exiting a governed\n    context. Rules are invalid if the transition states types are not contained in\n    `self.FROM_STATES` and `self.TO_STATES`, or if the context is proposing\n    a transition that differs from the transition the rule was instantiated with.\n\n    Returns:\n        True if the rules in invalid, False otherwise.\n    \"\"\"\n    # invalid and fizzled states are mutually exclusive,\n    # `_invalid_on_entry` holds this statefulness\n    if self.from_state_type not in self.FROM_STATES:\n        self._invalid_on_entry = True\n    if self.to_state_type not in self.TO_STATES:\n        self._invalid_on_entry = True\n\n    if self._invalid_on_entry is None:\n        self._invalid_on_entry = await self.invalid_transition()\n    return self._invalid_on_entry\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.fizzled","title":"<code>fizzled</code>  <code>async</code>","text":"<p>Determines if a rule is fizzled and side-effects need to be reverted.</p> <p>Rules are fizzled if the transitions were valid on entry (thus firing <code>self.before_transition</code>) but are invalid upon exiting the governed context, most likely caused by another rule mutating the transition.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the rule is fizzled, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def fizzled(self) -&gt; bool:\n    \"\"\"\n    Determines if a rule is fizzled and side-effects need to be reverted.\n\n    Rules are fizzled if the transitions were valid on entry (thus firing\n    `self.before_transition`) but are invalid upon exiting the governed context,\n    most likely caused by another rule mutating the transition.\n\n    Returns:\n        True if the rule is fizzled, False otherwise.\n    \"\"\"\n\n    if self._invalid_on_entry:\n        return False\n    return await self.invalid_transition()\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.invalid_transition","title":"<code>invalid_transition</code>  <code>async</code>","text":"<p>Determines if the transition proposed by the <code>OrchestrationContext</code> is invalid.</p> <p>If the <code>OrchestrationContext</code> is attempting to manage a transition with this rule that differs from the transition the rule was instantiated with, the transition is considered to be invalid. Depending on the context, a rule with an invalid transition is either \"invalid\" or \"fizzled\".</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is invalid, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def invalid_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition proposed by the `OrchestrationContext` is invalid.\n\n    If the `OrchestrationContext` is attempting to manage a transition with this\n    rule that differs from the transition the rule was instantiated with, the\n    transition is considered to be invalid. Depending on the context, a rule with an\n    invalid transition is either \"invalid\" or \"fizzled\".\n\n    Returns:\n        True if the transition is invalid, False otherwise.\n    \"\"\"\n\n    initial_state_type = self.context.initial_state_type\n    proposed_state_type = self.context.proposed_state_type\n    return (self.from_state_type != initial_state_type) or (\n        self.to_state_type != proposed_state_type\n    )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.reject_transition","title":"<code>reject_transition</code>  <code>async</code>","text":"<p>Rejects a proposed transition before the transition is validated.</p> <p>This method will reject a proposed transition, mutating the proposed state to the provided <code>state</code>. A reason for rejecting the transition is also passed on to the <code>OrchestrationContext</code>. Rules that reject the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>Optional[State]</code> <p>The new proposed state. If <code>None</code>, the current run state will be returned in the result instead.</p> required <code>reason</code> <code>str</code> <p>The reason for rejecting the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def reject_transition(self, state: Optional[states.State], reason: str):\n    \"\"\"\n    Rejects a proposed transition before the transition is validated.\n\n    This method will reject a proposed transition, mutating the proposed state to\n    the provided `state`. A reason for rejecting the transition is also passed on\n    to the `OrchestrationContext`. Rules that reject the transition will not fizzle,\n    despite the proposed state type changing.\n\n    Args:\n        state: The new proposed state. If `None`, the current run state will be\n            returned in the result instead.\n        reason: The reason for rejecting the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # the current state will be used if a new one is not provided\n    if state is None:\n        if self.from_state_type is None:\n            raise OrchestrationError(\n                \"The current run has no state; this transition cannot be \"\n                \"rejected without providing a new state.\"\n            )\n        self.to_state_type = None\n        self.context.proposed_state = None\n    else:\n        # a rule that mutates state should not fizzle itself\n        self.to_state_type = state.type\n        self.context.proposed_state = state\n\n    self.context.response_status = SetStateStatus.REJECT\n    self.context.response_details = StateRejectDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.delay_transition","title":"<code>delay_transition</code>  <code>async</code>","text":"<p>Delays a proposed transition before the transition is validated.</p> <p>This method will delay a proposed transition, setting the proposed state to <code>None</code>, signaling to the <code>OrchestrationContext</code> that no state should be written to the database. The number of seconds a transition should be delayed is passed to the <code>OrchestrationContext</code>. A reason for delaying the transition is also provided. Rules that delay the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>delay_seconds</code> <code>int</code> <p>The number of seconds the transition should be delayed</p> required <code>reason</code> <code>str</code> <p>The reason for delaying the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def delay_transition(\n    self,\n    delay_seconds: int,\n    reason: str,\n):\n    \"\"\"\n    Delays a proposed transition before the transition is validated.\n\n    This method will delay a proposed transition, setting the proposed state to\n    `None`, signaling to the `OrchestrationContext` that no state should be\n    written to the database. The number of seconds a transition should be delayed is\n    passed to the `OrchestrationContext`. A reason for delaying the transition is\n    also provided. Rules that delay the transition will not fizzle, despite the\n    proposed state type changing.\n\n    Args:\n        delay_seconds: The number of seconds the transition should be delayed\n        reason: The reason for delaying the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # a rule that mutates state should not fizzle itself\n    self.to_state_type = None\n    self.context.proposed_state = None\n    self.context.response_status = SetStateStatus.WAIT\n    self.context.response_details = StateWaitDetails(\n        delay_seconds=delay_seconds, reason=reason\n    )\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.abort_transition","title":"<code>abort_transition</code>  <code>async</code>","text":"<p>Aborts a proposed transition before the transition is validated.</p> <p>This method will abort a proposed transition, expecting no further action to occur for this run. The proposed state is set to <code>None</code>, signaling to the <code>OrchestrationContext</code> that no state should be written to the database. A reason for aborting the transition is also provided. Rules that abort the transition will not fizzle, despite the proposed state type changing.</p> <p>Parameters:</p> Name Type Description Default <code>reason</code> <code>str</code> <p>The reason for aborting the transition</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def abort_transition(self, reason: str):\n    \"\"\"\n    Aborts a proposed transition before the transition is validated.\n\n    This method will abort a proposed transition, expecting no further action to\n    occur for this run. The proposed state is set to `None`, signaling to the\n    `OrchestrationContext` that no state should be written to the database. A\n    reason for aborting the transition is also provided. Rules that abort the\n    transition will not fizzle, despite the proposed state type changing.\n\n    Args:\n        reason: The reason for aborting the transition\n    \"\"\"\n\n    # don't run if the transition is already validated\n    if self.context.validated_state:\n        raise RuntimeError(\"The transition is already validated\")\n\n    # a rule that mutates state should not fizzle itself\n    self.to_state_type = None\n    self.context.proposed_state = None\n    self.context.response_status = SetStateStatus.ABORT\n    self.context.response_details = StateAbortDetails(reason=reason)\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.rename_state","title":"<code>rename_state</code>  <code>async</code>","text":"<p>Sets the \"name\" attribute on a proposed state.</p> <p>The name of a state is an annotation intended to provide rich, human-readable context for how a run is progressing. This method only updates the name and not the canonical state TYPE, and will not fizzle or invalidate any other rules that might govern this state transition.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def rename_state(self, state_name):\n    \"\"\"\n    Sets the \"name\" attribute on a proposed state.\n\n    The name of a state is an annotation intended to provide rich, human-readable\n    context for how a run is progressing. This method only updates the name and not\n    the canonical state TYPE, and will not fizzle or invalidate any other rules\n    that might govern this state transition.\n    \"\"\"\n    if self.context.proposed_state is not None:\n        self.context.proposed_state.name = state_name\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseOrchestrationRule.update_context_parameters","title":"<code>update_context_parameters</code>  <code>async</code>","text":"<p>Updates the \"parameters\" dictionary attribute with the specified key-value pair.</p> <p>This mechanism streamlines the process of passing messages and information between orchestration rules if necessary and is simpler and more ephemeral than message-passing via the database or some other side-effect. This mechanism can be used to break up large rules for ease of testing or comprehension, but note that any rules coupled this way (or any other way) are no longer independent and the order in which they appear in the orchestration policy priority will matter.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def update_context_parameters(self, key, value):\n    \"\"\"\n    Updates the \"parameters\" dictionary attribute with the specified key-value pair.\n\n    This mechanism streamlines the process of passing messages and information\n    between orchestration rules if necessary and is simpler and more ephemeral than\n    message-passing via the database or some other side-effect. This mechanism can\n    be used to break up large rules for ease of testing or comprehension, but note\n    that any rules coupled this way (or any other way) are no longer independent and\n    the order in which they appear in the orchestration policy priority will matter.\n    \"\"\"\n\n    self.context.parameters.update({key: value})\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform","title":"<code>BaseUniversalTransform</code>","text":"<p>               Bases: <code>AbstractAsyncContextManager</code></p> <p>An abstract base class used to implement privileged bookkeeping logic.</p> Warning <p>In almost all cases, use the <code>BaseOrchestrationRule</code> base class instead.</p> <p>Beyond the orchestration rules implemented with the <code>BaseOrchestrationRule</code> ABC, Universal transforms are not stateful, and fire their before- and after- transition hooks on every state transition unless the proposed state is <code>None</code>, indicating that no state should be written to the database. Because there are no guardrails in place to prevent directly mutating state or other parts of the orchestration context, universal transforms should only be used with care.</p> <p>Attributes:</p> Name Type Description <code>FROM_STATES</code> <code>Iterable</code> <p>for compatibility with <code>BaseOrchestrationPolicy</code></p> <code>TO_STATES</code> <code>Iterable</code> <p>for compatibility with <code>BaseOrchestrationPolicy</code></p> <code>context</code> <p>the orchestration context</p> <code>from_state_type</code> <p>the state type a run is currently in</p> <code>to_state_type</code> <p>the intended proposed state type prior to any orchestration</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <code>OrchestrationContext</code> <p>A <code>FlowOrchestrationContext</code> or <code>TaskOrchestrationContext</code> that is passed between transforms</p> required Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>class BaseUniversalTransform(contextlib.AbstractAsyncContextManager):\n    \"\"\"\n    An abstract base class used to implement privileged bookkeeping logic.\n\n    Warning:\n        In almost all cases, use the `BaseOrchestrationRule` base class instead.\n\n    Beyond the orchestration rules implemented with the `BaseOrchestrationRule` ABC,\n    Universal transforms are not stateful, and fire their before- and after- transition\n    hooks on every state transition unless the proposed state is `None`, indicating that\n    no state should be written to the database. Because there are no guardrails in place\n    to prevent directly mutating state or other parts of the orchestration context,\n    universal transforms should only be used with care.\n\n    Attributes:\n        FROM_STATES: for compatibility with `BaseOrchestrationPolicy`\n        TO_STATES: for compatibility with `BaseOrchestrationPolicy`\n        context: the orchestration context\n        from_state_type: the state type a run is currently in\n        to_state_type: the intended proposed state type prior to any orchestration\n\n    Args:\n        context: A `FlowOrchestrationContext` or `TaskOrchestrationContext` that is\n            passed between transforms\n    \"\"\"\n\n    # `BaseUniversalTransform` will always fire on non-null transitions\n    FROM_STATES: Iterable = ALL_ORCHESTRATION_STATES\n    TO_STATES: Iterable = ALL_ORCHESTRATION_STATES\n\n    def __init__(\n        self,\n        context: OrchestrationContext,\n        from_state_type: Optional[states.StateType],\n        to_state_type: Optional[states.StateType],\n    ):\n        self.context = context\n        self.from_state_type = from_state_type\n        self.to_state_type = to_state_type\n\n    async def __aenter__(self):\n        \"\"\"\n        Enter an async runtime context governed by this transform.\n\n        The `with` statement will bind a governed `OrchestrationContext` to the target\n        specified by the `as` clause. If the transition proposed by the\n        `OrchestrationContext` has been nullified on entry and `context.proposed_state`\n        is `None`, entering this context will do nothing. Otherwise\n        `self.before_transition` will fire.\n        \"\"\"\n\n        await self.before_transition(self.context)\n        self.context.rule_signature.append(str(self.__class__))\n        return self.context\n\n    async def __aexit__(\n        self,\n        exc_type: Optional[Type[BaseException]],\n        exc_val: Optional[BaseException],\n        exc_tb: Optional[TracebackType],\n    ) -&gt; None:\n        \"\"\"\n        Exit the async runtime context governed by this transform.\n\n        If the transition has been nullified or errorred upon exiting this transforms's context,\n        nothing happens. Otherwise, `self.after_transition` will fire on every non-null\n        proposed state.\n        \"\"\"\n\n        if not self.exception_in_transition():\n            await self.after_transition(self.context)\n            self.context.finalization_signature.append(str(self.__class__))\n\n    async def before_transition(self, context) -&gt; None:\n        \"\"\"\n        Implements a hook that fires before a state is committed to the database.\n\n        Args:\n            context: the `OrchestrationContext` that contains transition details\n\n        Returns:\n            None\n        \"\"\"\n\n    async def after_transition(self, context) -&gt; None:\n        \"\"\"\n        Implements a hook that can fire after a state is committed to the database.\n\n        Args:\n            context: the `OrchestrationContext` that contains transition details\n\n        Returns:\n            None\n        \"\"\"\n\n    def nullified_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition has been nullified.\n\n        Transitions are nullified if the proposed state is `None`, indicating that\n        nothing should be written to the database.\n\n        Returns:\n            True if the transition is nullified, False otherwise.\n        \"\"\"\n\n        return self.context.proposed_state is None\n\n    def exception_in_transition(self) -&gt; bool:\n        \"\"\"\n        Determines if the transition has encountered an exception.\n\n        Returns:\n            True if the transition is encountered an exception, False otherwise.\n        \"\"\"\n\n        return self.context.orchestration_error is not None\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.before_transition","title":"<code>before_transition</code>  <code>async</code>","text":"<p>Implements a hook that fires before a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <p>the <code>OrchestrationContext</code> that contains transition details</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def before_transition(self, context) -&gt; None:\n    \"\"\"\n    Implements a hook that fires before a state is committed to the database.\n\n    Args:\n        context: the `OrchestrationContext` that contains transition details\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.after_transition","title":"<code>after_transition</code>  <code>async</code>","text":"<p>Implements a hook that can fire after a state is committed to the database.</p> <p>Parameters:</p> Name Type Description Default <code>context</code> <p>the <code>OrchestrationContext</code> that contains transition details</p> required <p>Returns:</p> Type Description <code>None</code> <p>None</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>async def after_transition(self, context) -&gt; None:\n    \"\"\"\n    Implements a hook that can fire after a state is committed to the database.\n\n    Args:\n        context: the `OrchestrationContext` that contains transition details\n\n    Returns:\n        None\n    \"\"\"\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.nullified_transition","title":"<code>nullified_transition</code>","text":"<p>Determines if the transition has been nullified.</p> <p>Transitions are nullified if the proposed state is <code>None</code>, indicating that nothing should be written to the database.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is nullified, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def nullified_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition has been nullified.\n\n    Transitions are nullified if the proposed state is `None`, indicating that\n    nothing should be written to the database.\n\n    Returns:\n        True if the transition is nullified, False otherwise.\n    \"\"\"\n\n    return self.context.proposed_state is None\n</code></pre>"},{"location":"api-ref/server/orchestration/rules/#prefect.server.orchestration.rules.BaseUniversalTransform.exception_in_transition","title":"<code>exception_in_transition</code>","text":"<p>Determines if the transition has encountered an exception.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if the transition is encountered an exception, False otherwise.</p> Source code in <code>prefect/server/orchestration/rules.py</code> <pre><code>def exception_in_transition(self) -&gt; bool:\n    \"\"\"\n    Determines if the transition has encountered an exception.\n\n    Returns:\n        True if the transition is encountered an exception, False otherwise.\n    \"\"\"\n\n    return self.context.orchestration_error is not None\n</code></pre>"},{"location":"api-ref/server/schemas/actions/","title":"server.schemas.actions","text":""},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions","title":"<code>prefect.server.schemas.actions</code>","text":"<p>Reduced schemas for accepting API actions.</p>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactCreate","title":"<code>ArtifactCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create an artifact.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ArtifactCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create an artifact.\"\"\"\n\n    key: Optional[str] = Field(\n        default=None, description=\"An optional unique reference key for this artifact.\"\n    )\n    type: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier that describes the shape of the data field. e.g. 'result',\"\n            \" 'table', 'markdown'\"\n        ),\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A markdown-enabled description of the artifact.\"\n    )\n    data: Optional[Union[Dict[str, Any], Any]] = Field(\n        default=None,\n        description=(\n            \"Data associated with the artifact, e.g. a result.; structure depends on\"\n            \" the artifact type.\"\n        ),\n    )\n    metadata_: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"User-defined artifact metadata. Content must be string key and value\"\n            \" pairs.\"\n        ),\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run associated with the artifact.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run associated with the artifact.\"\n    )\n\n    @classmethod\n    def from_result(cls, data: Any):\n        artifact_info = dict()\n        if isinstance(data, dict):\n            artifact_key = data.pop(\"artifact_key\", None)\n            if artifact_key:\n                artifact_info[\"key\"] = artifact_key\n\n            artifact_type = data.pop(\"artifact_type\", None)\n            if artifact_type:\n                artifact_info[\"type\"] = artifact_type\n\n            description = data.pop(\"artifact_description\", None)\n            if description:\n                artifact_info[\"description\"] = description\n\n        return cls(data=data, **artifact_info)\n\n    _validate_metadata_length = validator(\"metadata_\")(validate_max_metadata_length)\n\n    _validate_artifact_format = validator(\"key\", allow_reuse=True)(\n        validate_artifact_key\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactUpdate","title":"<code>ArtifactUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update an artifact.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ArtifactUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update an artifact.\"\"\"\n\n    data: Optional[Union[Dict[str, Any], Any]] = Field(None)\n    description: Optional[str] = Field(None)\n    metadata_: Optional[Dict[str, str]] = Field(None)\n\n    _validate_metadata_length = validator(\"metadata_\", allow_reuse=True)(\n        validate_max_metadata_length\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ArtifactUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentCreate","title":"<code>BlockDocumentCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block document.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    _validate_name_format = validator(\"name\", allow_reuse=True)(\n        validate_block_document_name\n    )\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentReferenceCreate","title":"<code>BlockDocumentReferenceCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used to create block document reference.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentReferenceCreate(ActionBaseModel):\n    \"\"\"Data used to create block document reference.\"\"\"\n\n    id: UUID = Field(\n        default_factory=uuid4, description=\"The block document reference ID\"\n    )\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of the parent block document\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentReferenceCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentUpdate","title":"<code>BlockDocumentUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block document.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockDocumentUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block document.\"\"\"\n\n    block_schema_id: Optional[UUID] = Field(\n        default=None, description=\"A block schema ID\"\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    merge_existing_data: bool = True\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockDocumentUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockSchemaCreate","title":"<code>BlockSchemaCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block schema.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockSchemaCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block schema.\"\"\"\n\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=schemas.core.DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockSchemaCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeCreate","title":"<code>BlockTypeCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a block type.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockTypeCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a block type.\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n\n    # validators\n    _validate_slug_format = validator(\"slug\", allow_reuse=True)(\n        validate_block_type_slug\n    )\n\n    _validate_name_characters = validator(\"name\", check_fields=False)(\n        raise_on_name_with_banned_characters\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeUpdate","title":"<code>BlockTypeUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a block type.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class BlockTypeUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a block type.\"\"\"\n\n    logo_url: Optional[schemas.core.HttpUrl] = Field(None)\n    documentation_url: Optional[schemas.core.HttpUrl] = Field(None)\n    description: Optional[str] = Field(None)\n    code_example: Optional[str] = Field(None)\n\n    @classmethod\n    def updatable_fields(cls) -&gt; set:\n        return get_class_fields_only(cls)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.BlockTypeUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitCreate","title":"<code>ConcurrencyLimitCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Create","title":"<code>ConcurrencyLimitV2Create</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitV2Create(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a v2 concurrency limit.\"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the concurrency limit is active.\"\n    )\n    name: str = Field(default=..., description=\"The name of the concurrency limit.\")\n    limit: NonNegativeInteger = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: NonNegativeInteger = Field(\n        default=0, description=\"The number of active slots.\"\n    )\n    denied_slots: NonNegativeInteger = Field(\n        default=0, description=\"The number of denied slots.\"\n    )\n    slot_decay_per_second: NonNegativeFloat = Field(\n        default=0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Create.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Update","title":"<code>ConcurrencyLimitV2Update</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class ConcurrencyLimitV2Update(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a v2 concurrency limit.\"\"\"\n\n    active: Optional[bool] = Field(None)\n    name: Optional[str] = Field(None)\n    limit: Optional[NonNegativeInteger] = Field(None)\n    active_slots: Optional[NonNegativeInteger] = Field(None)\n    denied_slots: Optional[NonNegativeInteger] = Field(None)\n    slot_decay_per_second: Optional[NonNegativeFloat] = Field(None)\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.ConcurrencyLimitV2Update.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate","title":"<code>DeploymentCreate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentCreate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a deployment.\"\"\"\n\n    @root_validator\n    def populate_schedules(cls, values):\n        return set_deployment_schedules(values)\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the deployment.\",\n        examples=[\"my-deployment\"],\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The ID of the flow associated with the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether the schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of deployment tags.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    pull_steps: Optional[List[dict]] = Field(None)\n\n    manifest_path: Optional[str] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    schedule: Optional[schemas.schedules.SCHEDULE_TYPES] = Field(\n        None, description=\"The schedule for the deployment.\"\n    )\n    description: Optional[str] = Field(None)\n    path: Optional[str] = Field(None)\n    version: Optional[str] = Field(None)\n    entrypoint: Optional[str] = Field(None)\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides for the flow's infrastructure configuration.\",\n    )\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"\n        Check that the combination of base_job_template defaults and job_variables\n        conforms to the specified schema.\n\n        NOTE: This method does not hydrate block references in default values within the\n        base job template to validate them. Failing to do this can cause user-facing\n        errors. Instead of this method, use `validate_job_variables_for_deployment`\n        function from `prefect_cloud.orion.api.validation`.\n        \"\"\"\n        # This import is here to avoid a circular import\n        from prefect.utilities.schema_tools import validate\n\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            validate(\n                self.job_variables,\n                variables_schema,\n                raise_on_error=True,\n                preprocess=True,\n                ignore_required=True,\n            )\n\n    @validator(\"parameters\")\n    def _validate_parameters_conform_to_schema(cls, value, values):\n        return validate_parameters_conform_to_schema(value, values)\n\n    @validator(\"parameter_openapi_schema\")\n    def _validate_parameter_openapi_schema(cls, value, values):\n        return validate_parameter_openapi_schema(value, values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the specified schema.</p> <p>NOTE: This method does not hydrate block references in default values within the base job template to validate them. Failing to do this can cause user-facing errors. Instead of this method, use <code>validate_job_variables_for_deployment</code> function from <code>prefect_cloud.orion.api.validation</code>.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"\n    Check that the combination of base_job_template defaults and job_variables\n    conforms to the specified schema.\n\n    NOTE: This method does not hydrate block references in default values within the\n    base job template to validate them. Failing to do this can cause user-facing\n    errors. Instead of this method, use `validate_job_variables_for_deployment`\n    function from `prefect_cloud.orion.api.validation`.\n    \"\"\"\n    # This import is here to avoid a circular import\n    from prefect.utilities.schema_tools import validate\n\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        validate(\n            self.job_variables,\n            variables_schema,\n            raise_on_error=True,\n            preprocess=True,\n            ignore_required=True,\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentCreate.schema","title":"<code>schema</code>  <code>classmethod</code>","text":"<p>Don't use the mixin docstring as the description if this class is missing a docstring.</p> Source code in <code>prefect/_internal/compatibility/deprecated.py</code> <pre><code>@classmethod\ndef schema(\n    cls, by_alias: bool = True, ref_template: str = default_ref_template\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Don't use the mixin docstring as the description if this class is missing a\n    docstring.\n    \"\"\"\n    schema = super().schema(by_alias=by_alias, ref_template=ref_template)\n\n    if not cls.__doc__:\n        schema.pop(\"description\", None)\n\n    return schema\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentFlowRunCreate","title":"<code>DeploymentFlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run from a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentFlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run from a deployment.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=\"Whether or not to enforce the parameter schema on this run.\",\n    )\n    context: Dict[str, Any] = Field(default_factory=dict)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy,\n        description=\"The empirical policy for the flow run.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the flow run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    idempotency_key: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional idempotency key. If a flow run with the same idempotency key\"\n            \" has already been created, the existing flow run will be returned.\"\n        ),\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    work_queue_name: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentFlowRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate","title":"<code>DeploymentUpdate</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a deployment.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class DeploymentUpdate(DeprecatedInfraOverridesField, ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a deployment.\"\"\"\n\n    @root_validator(pre=True)\n    def remove_old_fields(cls, values):\n        return remove_old_deployment_fields(values)\n\n    version: Optional[str] = Field(None)\n    schedule: Optional[schemas.schedules.SCHEDULE_TYPES] = Field(\n        None, description=\"The schedule for the deployment.\"\n    )\n    description: Optional[str] = Field(None)\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether the schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentScheduleCreate] = Field(\n        default_factory=list,\n        description=\"A list of schedules for the deployment.\",\n    )\n    parameters: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of deployment tags.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(None)\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the deployment's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    path: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Overrides for the flow's infrastructure configuration.\",\n    )\n    entrypoint: Optional[str] = Field(None)\n    manifest_path: Optional[str] = Field(None)\n    storage_document_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    enforce_parameter_schema: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    class Config:\n        allow_population_by_field_name = True\n\n    def check_valid_configuration(self, base_job_template: dict):\n        \"\"\"\n        Check that the combination of base_job_template defaults and job_variables\n        conforms to the schema specified in the base_job_template.\n\n        NOTE: This method does not hydrate block references in default values within the\n        base job template to validate them. Failing to do this can cause user-facing\n        errors. Instead of this method, use `validate_job_variables_for_deployment`\n        function from `prefect_cloud.orion.api.validation`.\n        \"\"\"\n        # This import is here to avoid a circular import\n        from prefect.utilities.schema_tools import validate\n\n        variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n        if variables_schema is not None:\n            errors = validate(\n                self.job_variables,\n                variables_schema,\n                raise_on_error=False,\n                preprocess=True,\n                ignore_required=True,\n            )\n            if errors:\n                for error in errors:\n                    raise error\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.check_valid_configuration","title":"<code>check_valid_configuration</code>","text":"<p>Check that the combination of base_job_template defaults and job_variables conforms to the schema specified in the base_job_template.</p> <p>NOTE: This method does not hydrate block references in default values within the base job template to validate them. Failing to do this can cause user-facing errors. Instead of this method, use <code>validate_job_variables_for_deployment</code> function from <code>prefect_cloud.orion.api.validation</code>.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>def check_valid_configuration(self, base_job_template: dict):\n    \"\"\"\n    Check that the combination of base_job_template defaults and job_variables\n    conforms to the schema specified in the base_job_template.\n\n    NOTE: This method does not hydrate block references in default values within the\n    base job template to validate them. Failing to do this can cause user-facing\n    errors. Instead of this method, use `validate_job_variables_for_deployment`\n    function from `prefect_cloud.orion.api.validation`.\n    \"\"\"\n    # This import is here to avoid a circular import\n    from prefect.utilities.schema_tools import validate\n\n    variables_schema = deepcopy(base_job_template.get(\"variables\"))\n\n    if variables_schema is not None:\n        errors = validate(\n            self.job_variables,\n            variables_schema,\n            raise_on_error=False,\n            preprocess=True,\n            ignore_required=True,\n        )\n        if errors:\n            for error in errors:\n                raise error\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.DeploymentUpdate.schema","title":"<code>schema</code>  <code>classmethod</code>","text":"<p>Don't use the mixin docstring as the description if this class is missing a docstring.</p> Source code in <code>prefect/_internal/compatibility/deprecated.py</code> <pre><code>@classmethod\ndef schema(\n    cls, by_alias: bool = True, ref_template: str = default_ref_template\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Don't use the mixin docstring as the description if this class is missing a\n    docstring.\n    \"\"\"\n    schema = super().schema(by_alias=by_alias, ref_template=ref_template)\n\n    if not cls.__doc__:\n        schema.pop(\"description\", None)\n\n    return schema\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowCreate","title":"<code>FlowCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunCreate","title":"<code>FlowRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run.\"\"\"\n\n    # FlowRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the flow run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    flow_version: Optional[str] = Field(\n        default=None, description=\"The version of the flow being run.\"\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"The context of the flow run.\",\n    )\n    parent_task_run_id: Optional[UUID] = Field(None)\n    infrastructure_document_id: Optional[UUID] = Field(None)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy,\n        description=\"The empirical policy for the flow run.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the flow run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    idempotency_key: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional idempotency key. If a flow run with the same idempotency key\"\n            \" has already been created, the existing flow run will be returned.\"\n        ),\n    )\n\n    # DEPRECATED\n\n    deployment_id: Optional[UUID] = Field(\n        None,\n        description=(\n            \"DEPRECATED: The id of the deployment associated with this flow run, if\"\n            \" available.\"\n        ),\n        deprecated=True,\n    )\n\n    class Config(ActionBaseModel.Config):\n        json_dumps = orjson_dumps_extra_compatible\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyCreate","title":"<code>FlowRunNotificationPolicyCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a flow run notification policy.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a flow run notification policy.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(schemas.core.FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate","title":"<code>FlowRunNotificationPolicyUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run notification policy.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunNotificationPolicyUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run notification policy.\"\"\"\n\n    is_active: Optional[bool] = Field(None)\n    state_names: Optional[List[str]] = Field(None)\n    tags: Optional[List[str]] = Field(None)\n    block_document_id: Optional[UUID] = Field(None)\n    message_template: Optional[str] = Field(None)\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunNotificationPolicyUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunUpdate","title":"<code>FlowRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow run.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow run.\"\"\"\n\n    name: Optional[str] = Field(None)\n    flow_version: Optional[str] = Field(None)\n    parameters: Dict[str, Any] = Field(default_factory=dict)\n    empirical_policy: schemas.core.FlowRunPolicy = Field(\n        default_factory=schemas.core.FlowRunPolicy\n    )\n    tags: List[str] = Field(default_factory=list)\n    infrastructure_pid: Optional[str] = Field(None)\n    job_variables: Optional[Dict[str, Any]] = Field(None)\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowRunUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowUpdate","title":"<code>FlowUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a flow.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class FlowUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a flow.\"\"\"\n\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.FlowUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.LogCreate","title":"<code>LogCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a log.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class LogCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a log.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(None)\n    task_run_id: Optional[UUID] = Field(None)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.LogCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.SavedSearchCreate","title":"<code>SavedSearchCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a saved search.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class SavedSearchCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a saved search.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[schemas.core.SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.SavedSearchCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.StateCreate","title":"<code>StateCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a new state.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class StateCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a new state.\"\"\"\n\n    type: schemas.states.StateType = Field(\n        default=..., description=\"The type of the state to create\"\n    )\n    name: Optional[str] = Field(\n        default=None, description=\"The name of the state to create\"\n    )\n    message: Optional[str] = Field(\n        default=None, description=\"The message of the state to create\"\n    )\n    data: Optional[Any] = Field(\n        default=None, description=\"The data of the state to create\"\n    )\n    state_details: schemas.states.StateDetails = Field(\n        default_factory=schemas.states.StateDetails,\n        description=\"The details of the state to create\",\n    )\n\n    timestamp: Optional[DateTimeTZ] = Field(\n        default=None,\n        repr=False,\n        ignored=True,\n    )\n    id: Optional[UUID] = Field(default=None, repr=False, ignored=True)\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        return set_default_scheduled_time(cls, values)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.StateCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunCreate","title":"<code>TaskRunCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a task run</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class TaskRunCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a task run\"\"\"\n\n    id: Optional[UUID] = Field(\n        default=None,\n        description=\"The ID to use for the task run. If not provided, a random UUID will be generated.\",\n    )\n\n    # TaskRunCreate states must be provided as StateCreate objects\n    state: Optional[StateCreate] = Field(\n        default=None, description=\"The state of the task run to create\"\n    )\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run id of the task run.\"\n    )\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional cache key. If a COMPLETED state associated with this cache key\"\n            \" is found, the cached COMPLETED state will be used instead of executing\"\n            \" the task run.\"\n        ),\n    )\n    cache_expiration: Optional[DateTimeTZ] = Field(\n        default=None, description=\"Specifies when the cached state should expire.\"\n    )\n    task_version: Optional[str] = Field(\n        default=None, description=\"The version of the task being run.\"\n    )\n    empirical_policy: schemas.core.TaskRunPolicy = Field(\n        default_factory=schemas.core.TaskRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the task run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    task_inputs: Dict[\n        str,\n        List[\n            Union[\n                schemas.core.TaskRunResult,\n                schemas.core.Parameter,\n                schemas.core.Constant,\n            ]\n        ],\n    ] = Field(\n        default_factory=dict,\n        description=\"The inputs to the task run.\",\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    @validator(\"cache_key\")\n    def validate_cache_key(cls, cache_key):\n        return validate_cache_key_length(cache_key)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunUpdate","title":"<code>TaskRunUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a task run</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class TaskRunUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a task run\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.TaskRunUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableCreate","title":"<code>VariableCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a Variable.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class VariableCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a Variable.\"\"\"\n\n    name: str = Field(\n        default=...,\n        description=\"The name of the variable\",\n        examples=[\"my-variable\"],\n        max_length=schemas.core.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: str = Field(\n        default=...,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=schemas.core.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of variable tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableUpdate","title":"<code>VariableUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a Variable.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class VariableUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a Variable.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the variable\",\n        examples=[\"my-variable\"],\n        max_length=schemas.core.MAX_VARIABLE_NAME_LENGTH,\n    )\n    value: Optional[str] = Field(\n        default=None,\n        description=\"The value of the variable\",\n        examples=[\"my-value\"],\n        max_length=schemas.core.MAX_VARIABLE_VALUE_LENGTH,\n    )\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of variable tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    # validators\n    _validate_name_format = validator(\"name\", allow_reuse=True)(validate_variable_name)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.VariableUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolCreate","title":"<code>WorkPoolCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work pool.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkPoolCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work pool.\"\"\"\n\n    name: str = Field(..., description=\"The name of the work pool.\")\n    description: Optional[str] = Field(None, description=\"The work pool description.\")\n    type: str = Field(description=\"The work pool type.\", default=\"prefect-agent\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n\n    _validate_base_job_template = validator(\"base_job_template\", allow_reuse=True)(\n        validate_base_job_template\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolUpdate","title":"<code>WorkPoolUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work pool.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkPoolUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work pool.\"\"\"\n\n    description: Optional[str] = Field(None)\n    is_paused: Optional[bool] = Field(None)\n    base_job_template: Optional[Dict[str, Any]] = Field(None)\n    concurrency_limit: Optional[NonNegativeInteger] = Field(None)\n\n    _validate_base_job_template = validator(\"base_job_template\", allow_reuse=True)(\n        validate_base_job_template\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkPoolUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueCreate","title":"<code>WorkQueueCreate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to create a work queue.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkQueueCreate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to create a work queue.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        None, description=\"The work queue's concurrency limit.\"\n    )\n    priority: Optional[PositiveInteger] = Field(\n        None,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n\n    # DEPRECATED\n\n    filter: Optional[schemas.core.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueCreate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueUpdate","title":"<code>WorkQueueUpdate</code>","text":"<p>               Bases: <code>ActionBaseModel</code></p> <p>Data used by the Prefect REST API to update a work queue.</p> Source code in <code>prefect/server/schemas/actions.py</code> <pre><code>class WorkQueueUpdate(ActionBaseModel):\n    \"\"\"Data used by the Prefect REST API to update a work queue.\"\"\"\n\n    name: Optional[str] = Field(None)\n    description: Optional[str] = Field(None)\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(None)\n    priority: Optional[PositiveInteger] = Field(None)\n    last_polled: Optional[DateTimeTZ] = Field(None)\n\n    # DEPRECATED\n\n    filter: Optional[schemas.core.QueueFilter] = Field(\n        None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/actions/#prefect.server.schemas.actions.WorkQueueUpdate.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/core/","title":"server.schemas.core","text":""},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core","title":"<code>prefect.server.schemas.core</code>","text":"<p>Full schemas of Prefect REST API objects.</p>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Agent","title":"<code>Agent</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of an agent</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Agent(ORMBaseModel):\n    \"\"\"An ORM representation of an agent\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the agent. If a name is not provided, it will be\"\n            \" auto-generated.\"\n        ),\n    )\n    work_queue_id: UUID = Field(\n        default=..., description=\"The work queue with which the agent is associated.\"\n    )\n    last_activity_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time this agent polled for work.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockDocument","title":"<code>BlockDocument</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block document.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockDocument(ORMBaseModel):\n    \"\"\"An ORM representation of a block document.\"\"\"\n\n    name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The block document's name. Not required for anonymous block documents.\"\n        ),\n    )\n    data: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block document's data\"\n    )\n    block_schema_id: UUID = Field(default=..., description=\"A block schema ID\")\n    block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The associated block schema\"\n    )\n    block_type_id: UUID = Field(default=..., description=\"A block type ID\")\n    block_type_name: Optional[str] = Field(\n        default=None, description=\"The associated block type's name\"\n    )\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    block_document_references: Dict[str, Dict[str, Any]] = Field(\n        default_factory=dict, description=\"Record of the block document's references\"\n    )\n    is_anonymous: bool = Field(\n        default=False,\n        description=(\n            \"Whether the block is anonymous (anonymous blocks are usually created by\"\n            \" Prefect automatically)\"\n        ),\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        # the BlockDocumentCreate subclass allows name=None\n        # and will inherit this validator\n        return raise_on_name_with_banned_characters(v)\n\n    @root_validator\n    def validate_name_is_present_if_not_anonymous(cls, values):\n        return validate_name_present_on_nonanonymous_blocks(values)\n\n    @classmethod\n    async def from_orm_model(\n        cls,\n        session,\n        orm_block_document: \"prefect.server.database.orm_models.ORMBlockDocument\",\n        include_secrets: bool = False,\n    ):\n        data = await orm_block_document.decrypt_data(session=session)\n        # if secrets are not included, obfuscate them based on the schema's\n        # `secret_fields`. Note this walks any nested blocks as well. If the\n        # nested blocks were recovered from named blocks, they will already\n        # be obfuscated, but if nested fields were hardcoded into the parent\n        # blocks data, this is the only opportunity to obfuscate them.\n        if not include_secrets:\n            flat_data = dict_to_flatdict(data)\n            # iterate over the (possibly nested) secret fields\n            # and obfuscate their data\n            for secret_field in orm_block_document.block_schema.fields.get(\n                \"secret_fields\", []\n            ):\n                secret_key = tuple(secret_field.split(\".\"))\n                if flat_data.get(secret_key) is not None:\n                    flat_data[secret_key] = obfuscate_string(flat_data[secret_key])\n                # If a wildcard (*) is in the current secret key path, we take the portion\n                # of the path before the wildcard and compare it to the same level of each\n                # key. A match means that the field is nested under the secret key and should\n                # be obfuscated.\n                elif \"*\" in secret_key:\n                    wildcard_index = secret_key.index(\"*\")\n                    for data_key in flat_data.keys():\n                        if secret_key[0:wildcard_index] == data_key[0:wildcard_index]:\n                            flat_data[data_key] = obfuscate(flat_data[data_key])\n            data = flatdict_to_dict(flat_data)\n\n        return cls(\n            id=orm_block_document.id,\n            created=orm_block_document.created,\n            updated=orm_block_document.updated,\n            name=orm_block_document.name,\n            data=data,\n            block_schema_id=orm_block_document.block_schema_id,\n            block_schema=orm_block_document.block_schema,\n            block_type_id=orm_block_document.block_type_id,\n            block_type_name=orm_block_document.block_type_name,\n            block_type=orm_block_document.block_type,\n            is_anonymous=orm_block_document.is_anonymous,\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockDocumentReference","title":"<code>BlockDocumentReference</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block document reference.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockDocumentReference(ORMBaseModel):\n    \"\"\"An ORM representation of a block document reference.\"\"\"\n\n    parent_block_document_id: UUID = Field(\n        default=..., description=\"ID of block document the reference is nested within\"\n    )\n    parent_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The block document the reference is nested within\"\n    )\n    reference_block_document_id: UUID = Field(\n        default=..., description=\"ID of the nested block document\"\n    )\n    reference_block_document: Optional[BlockDocument] = Field(\n        default=None, description=\"The nested block document\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n\n    @root_validator\n    def validate_parent_and_ref_are_different(cls, values):\n        return validate_parent_and_ref_diff(values)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockSchema","title":"<code>BlockSchema</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block schema.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockSchema(ORMBaseModel):\n    \"\"\"An ORM representation of a block schema.\"\"\"\n\n    checksum: str = Field(default=..., description=\"The block schema's unique checksum\")\n    fields: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The block schema's field schema\"\n    )\n    block_type_id: Optional[UUID] = Field(default=..., description=\"A block type ID\")\n    block_type: Optional[BlockType] = Field(\n        default=None, description=\"The associated block type\"\n    )\n    capabilities: List[str] = Field(\n        default_factory=list,\n        description=\"A list of Block capabilities\",\n    )\n    version: str = Field(\n        default=DEFAULT_BLOCK_SCHEMA_VERSION,\n        description=\"Human readable identifier for the block schema\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockSchemaReference","title":"<code>BlockSchemaReference</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block schema reference.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockSchemaReference(ORMBaseModel):\n    \"\"\"An ORM representation of a block schema reference.\"\"\"\n\n    parent_block_schema_id: UUID = Field(\n        default=..., description=\"ID of block schema the reference is nested within\"\n    )\n    parent_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The block schema the reference is nested within\"\n    )\n    reference_block_schema_id: UUID = Field(\n        default=..., description=\"ID of the nested block schema\"\n    )\n    reference_block_schema: Optional[BlockSchema] = Field(\n        default=None, description=\"The nested block schema\"\n    )\n    name: str = Field(\n        default=..., description=\"The name that the reference is nested under\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.BlockType","title":"<code>BlockType</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a block type</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class BlockType(ORMBaseModel):\n    \"\"\"An ORM representation of a block type\"\"\"\n\n    name: str = Field(default=..., description=\"A block type's name\")\n    slug: str = Field(default=..., description=\"A block type's slug\")\n    logo_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's logo\"\n    )\n    documentation_url: Optional[HttpUrl] = Field(\n        default=None, description=\"Web URL for the block type's documentation\"\n    )\n    description: Optional[str] = Field(\n        default=None,\n        description=\"A short blurb about the corresponding block's intended use\",\n    )\n    code_example: Optional[str] = Field(\n        default=None,\n        description=\"A code snippet demonstrating use of the corresponding block\",\n    )\n    is_protected: bool = Field(\n        default=False, description=\"Protected block types cannot be modified via API.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.ConcurrencyLimit","title":"<code>ConcurrencyLimit</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a concurrency limit.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class ConcurrencyLimit(ORMBaseModel):\n    \"\"\"An ORM representation of a concurrency limit.\"\"\"\n\n    tag: str = Field(\n        default=..., description=\"A tag the concurrency limit is applied to.\"\n    )\n    concurrency_limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: List[UUID] = Field(\n        default_factory=list,\n        description=\"A list of active run ids using a concurrency slot\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.ConcurrencyLimitV2","title":"<code>ConcurrencyLimitV2</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a v2 concurrency limit.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class ConcurrencyLimitV2(ORMBaseModel):\n    \"\"\"An ORM representation of a v2 concurrency limit.\"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the concurrency limit is active.\"\n    )\n    name: str = Field(default=..., description=\"The name of the concurrency limit.\")\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=0, description=\"The number of active slots.\")\n    denied_slots: int = Field(default=0, description=\"The number of denied slots.\")\n    slot_decay_per_second: float = Field(\n        default=0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n    avg_slot_occupancy_seconds: float = Field(\n        default=2.0, description=\"The average amount of time a slot is occupied.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Configuration","title":"<code>Configuration</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of account info.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Configuration(ORMBaseModel):\n    \"\"\"An ORM representation of account info.\"\"\"\n\n    key: str = Field(default=..., description=\"Account info key\")\n    value: Dict[str, Any] = Field(default=..., description=\"Account info\")\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Deployment","title":"<code>Deployment</code>","text":"<p>               Bases: <code>DeprecatedInfraOverridesField</code>, <code>ORMBaseModel</code></p> <p>An ORM representation of deployment data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Deployment(DeprecatedInfraOverridesField, ORMBaseModel):\n    \"\"\"An ORM representation of deployment data.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the deployment.\")\n    version: Optional[str] = Field(\n        default=None, description=\"An optional version for the deployment.\"\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description for the deployment.\"\n    )\n    flow_id: UUID = Field(\n        default=..., description=\"The flow id associated with the deployment.\"\n    )\n    schedule: Optional[schedules.SCHEDULE_TYPES] = Field(\n        default=None, description=\"A schedule for the deployment.\"\n    )\n    is_schedule_active: bool = Field(\n        default=True, description=\"Whether or not the deployment schedule is active.\"\n    )\n    paused: bool = Field(\n        default=False, description=\"Whether or not the deployment is paused.\"\n    )\n    schedules: List[DeploymentSchedule] = Field(\n        default_factory=list, description=\"A list of schedules for the deployment.\"\n    )\n    job_variables: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Overrides to apply to flow run infrastructure at runtime.\",\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Parameters for flow runs scheduled by the deployment.\",\n    )\n    pull_steps: Optional[List[dict]] = Field(\n        default=None,\n        description=\"Pull steps for cloning and running this deployment.\",\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the deployment\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The work queue for the deployment. If no work queue is set, work will not\"\n            \" be scheduled.\"\n        ),\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The last time the deployment was polled for status updates.\",\n    )\n    parameter_openapi_schema: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"The parameter schema of the flow, including defaults.\",\n    )\n    path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the working directory for the workflow, relative to remote\"\n            \" storage or an absolute path.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the entrypoint for the workflow, relative to the `path`.\"\n        ),\n    )\n    manifest_path: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The path to the flow's manifest file, relative to the chosen storage.\"\n        ),\n    )\n    storage_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining storage used for this flow.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use for flow runs.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this deployment.\",\n    )\n    updated_by: Optional[UpdatedBy] = Field(\n        default=None,\n        description=\"Optional information about the updater of this deployment.\",\n    )\n    work_queue_id: UUID = Field(\n        default=None,\n        description=(\n            \"The id of the work pool queue to which this deployment is assigned.\"\n        ),\n    )\n    enforce_parameter_schema: bool = Field(\n        default=False,\n        description=(\n            \"Whether or not the deployment should enforce the parameter schema.\"\n        ),\n    )\n\n    class Config:\n        allow_population_by_field_name = True\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Flow","title":"<code>Flow</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of flow data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Flow(ORMBaseModel):\n    \"\"\"An ORM representation of flow data.\"\"\"\n\n    name: str = Field(\n        default=..., description=\"The name of the flow\", examples=[\"my-flow\"]\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of flow tags\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRun","title":"<code>FlowRun</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of flow run data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRun(ORMBaseModel):\n    \"\"\"An ORM representation of flow run data.\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_value\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n\n    state_type: Optional[states.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n\n    # relationships\n    # flow: Flow = None\n    # task_runs: List[\"TaskRun\"] = Field(default_factory=list)\n    state: Optional[states.State] = Field(\n        default=None, description=\"The current state of the flow run.\"\n    )\n    # parent_task_run: \"TaskRun\" = None\n\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Variables used as overrides in the base job template\",\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRun):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRunNotificationPolicy","title":"<code>FlowRunNotificationPolicy</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a flow run notification.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRunNotificationPolicy(ORMBaseModel):\n    \"\"\"An ORM representation of a flow run notification.\"\"\"\n\n    is_active: bool = Field(\n        default=True, description=\"Whether the policy is currently active\"\n    )\n    state_names: List[str] = Field(\n        default=..., description=\"The flow run states that trigger notifications\"\n    )\n    tags: List[str] = Field(\n        default=...,\n        description=\"The flow run tags that trigger notifications (set [] to disable)\",\n    )\n    block_document_id: UUID = Field(\n        default=..., description=\"The block document ID used for sending notifications\"\n    )\n    message_template: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A templatable notification message. Use {braces} to add variables.\"\n            \" Valid variables include:\"\n            f\" {listrepr(sorted(FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}\"\n        ),\n        examples=[\n            \"Flow run {flow_run_name} with id {flow_run_id} entered state\"\n            \" {flow_run_state_name}.\"\n        ],\n    )\n\n    @validator(\"message_template\")\n    def validate_message_template_variables(cls, v):\n        return validate_message_template_variables(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.FlowRunPolicy","title":"<code>FlowRunPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Defines of how a flow run should retry.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class FlowRunPolicy(PrefectBaseModel):\n    \"\"\"Defines of how a flow run should retry.\"\"\"\n\n    # TODO: Determine how to separate between infrastructure and within-process level\n    #       retries\n    max_retries: int = Field(\n        default=0,\n        description=(\n            \"The maximum number of retries. Field is not used. Please use `retries`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retry_delay_seconds: float = Field(\n        default=0,\n        description=(\n            \"The delay between retries. Field is not used. Please use `retry_delay`\"\n            \" instead.\"\n        ),\n        deprecated=True,\n    )\n    retries: Optional[int] = Field(default=None, description=\"The number of retries.\")\n    retry_delay: Optional[int] = Field(\n        default=None, description=\"The delay time between retries, in seconds.\"\n    )\n    pause_keys: Optional[set] = Field(\n        default_factory=set, description=\"Tracks pauses this run has observed.\"\n    )\n    resuming: Optional[bool] = Field(\n        default=False, description=\"Indicates if this run is resuming from a pause.\"\n    )\n\n    @root_validator\n    def populate_deprecated_fields(cls, values):\n        return set_run_policy_deprecated_fields(values)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Log","title":"<code>Log</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of log data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Log(ORMBaseModel):\n    \"\"\"An ORM representation of log data.\"\"\"\n\n    name: str = Field(default=..., description=\"The logger name.\")\n    level: int = Field(default=..., description=\"The log level.\")\n    message: str = Field(default=..., description=\"The log message.\")\n    timestamp: DateTimeTZ = Field(default=..., description=\"The log timestamp.\")\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run ID associated with the log.\"\n    )\n    task_run_id: Optional[UUID] = Field(\n        default=None, description=\"The task run ID associated with the log.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.QueueFilter","title":"<code>QueueFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Filter criteria definition for a work queue.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class QueueFilter(PrefectBaseModel):\n    \"\"\"Filter criteria definition for a work queue.\"\"\"\n\n    tags: Optional[List[str]] = Field(\n        default=None,\n        description=\"Only include flow runs with these tags in the work queue.\",\n    )\n    deployment_ids: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"Only include flow runs from these deployments in the work queue.\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.SavedSearch","title":"<code>SavedSearch</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of saved search data. Represents a set of filter criteria.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class SavedSearch(ORMBaseModel):\n    \"\"\"An ORM representation of saved search data. Represents a set of filter criteria.\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the saved search.\")\n    filters: List[SavedSearchFilter] = Field(\n        default_factory=list, description=\"The filter set for the saved search.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.SavedSearchFilter","title":"<code>SavedSearchFilter</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A filter for a saved search model. Intended for use by the Prefect UI.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class SavedSearchFilter(PrefectBaseModel):\n    \"\"\"A filter for a saved search model. Intended for use by the Prefect UI.\"\"\"\n\n    object: str = Field(default=..., description=\"The object over which to filter.\")\n    property: str = Field(\n        default=..., description=\"The property of the object on which to filter.\"\n    )\n    type: str = Field(default=..., description=\"The type of the property.\")\n    operation: str = Field(\n        default=...,\n        description=\"The operator to apply to the object. For example, `equals`.\",\n    )\n    value: Any = Field(\n        default=..., description=\"A JSON-compatible value for the filter.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.TaskRun","title":"<code>TaskRun</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of task run data.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class TaskRun(ORMBaseModel):\n    \"\"\"An ORM representation of task run data.\"\"\"\n\n    name: str = Field(\n        default_factory=lambda: generate_slug(2), examples=[\"my-task-run\"]\n    )\n    flow_run_id: Optional[UUID] = Field(\n        default=None, description=\"The flow run id of the task run.\"\n    )\n    task_key: str = Field(\n        default=..., description=\"A unique identifier for the task being run.\"\n    )\n    dynamic_key: str = Field(\n        default=...,\n        description=(\n            \"A dynamic key used to differentiate between multiple runs of the same task\"\n            \" within the same flow run.\"\n        ),\n    )\n    cache_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional cache key. If a COMPLETED state associated with this cache key\"\n            \" is found, the cached COMPLETED state will be used instead of executing\"\n            \" the task run.\"\n        ),\n    )\n    cache_expiration: Optional[DateTimeTZ] = Field(\n        default=None, description=\"Specifies when the cached state should expire.\"\n    )\n    task_version: Optional[str] = Field(\n        default=None, description=\"The version of the task being run.\"\n    )\n    empirical_policy: TaskRunPolicy = Field(\n        default_factory=TaskRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags for the task run.\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the current task run state.\"\n    )\n    task_inputs: Dict[str, List[Union[TaskRunResult, Parameter, Constant]]] = Field(\n        default_factory=dict,\n        description=(\n            \"Tracks the source of inputs to a task run. Used for internal bookkeeping.\"\n        ),\n    )\n    state_type: Optional[states.StateType] = Field(\n        default=None, description=\"The type of the current task run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current task run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the task run has been executed.\"\n    )\n    flow_run_run_count: int = Field(\n        default=0,\n        description=(\n            \"If the parent flow has retried, this indicates the flow retry this run is\"\n            \" associated with.\"\n        ),\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The task run's expected start time.\",\n    )\n\n    # the next scheduled start time will be populated\n    # whenever the run is in a scheduled state\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the task run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the task run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n\n    # relationships\n    # flow_run: FlowRun = None\n    # subflow_runs: List[FlowRun] = Field(default_factory=list)\n    state: Optional[states.State] = Field(\n        default=None, description=\"The current task run state.\"\n    )\n\n    @validator(\"name\", pre=True)\n    def set_name(cls, name):\n        return get_or_create_run_name(name)\n\n    @validator(\"cache_key\")\n    def validate_cache_key(cls, cache_key):\n        return validate_cache_key_length(cache_key)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkPool","title":"<code>WorkPool</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a work pool</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkPool(ORMBaseModel):\n    \"\"\"An ORM representation of a work pool\"\"\"\n\n    name: str = Field(\n        description=\"The name of the work pool.\",\n    )\n    description: Optional[str] = Field(\n        default=None, description=\"A description of the work pool.\"\n    )\n    type: str = Field(description=\"The work pool type.\")\n    base_job_template: Dict[str, Any] = Field(\n        default_factory=dict, description=\"The work pool's base job template.\"\n    )\n    is_paused: bool = Field(\n        default=False,\n        description=\"Pausing the work pool stops the delivery of all work.\",\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"A concurrency limit for the work pool.\"\n    )\n    status: Optional[WorkPoolStatus] = Field(\n        default=None, description=\"The current status of the work pool.\"\n    )\n\n    # this required field has a default of None so that the custom validator\n    # below will be called and produce a more helpful error message\n    default_queue_id: UUID = Field(\n        None, description=\"The id of the pool's default queue.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n\n    @validator(\"default_queue_id\", always=True)\n    def helpful_error_for_missing_default_queue_id(cls, v):\n        return validate_default_queue_id_not_none(v)\n\n    @classmethod\n    def from_orm(cls, work_pool: \"ORMWorkPool\") -&gt; Self:\n        parsed: WorkPool = super().from_orm(work_pool)\n        if work_pool.type == \"prefect-agent\":\n            parsed.status = None\n        return parsed\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueue","title":"<code>WorkQueue</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a work queue</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkQueue(ORMBaseModel):\n    \"\"\"An ORM representation of a work queue\"\"\"\n\n    name: str = Field(default=..., description=\"The name of the work queue.\")\n    description: Optional[str] = Field(\n        default=\"\", description=\"An optional description for the work queue.\"\n    )\n    is_paused: bool = Field(\n        default=False, description=\"Whether or not the work queue is paused.\"\n    )\n    concurrency_limit: Optional[NonNegativeInteger] = Field(\n        default=None, description=\"An optional concurrency limit for the work queue.\"\n    )\n    priority: PositiveInteger = Field(\n        default=1,\n        description=(\n            \"The queue's priority. Lower values are higher priority (1 is the highest).\"\n        ),\n    )\n    # Will be required after a future migration\n    work_pool_id: Optional[UUID] = Field(\n        default=None, description=\"The work pool with which the queue is associated.\"\n    )\n    filter: Optional[QueueFilter] = Field(\n        default=None,\n        description=\"DEPRECATED: Filter criteria for the work queue.\",\n        deprecated=True,\n    )\n    last_polled: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The last time an agent polled this queue for work.\"\n    )\n\n    @validator(\"name\", check_fields=False)\n    def validate_name_characters(cls, v):\n        return raise_on_name_with_banned_characters(v)\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueueHealthPolicy","title":"<code>WorkQueueHealthPolicy</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class WorkQueueHealthPolicy(PrefectBaseModel):\n    maximum_late_runs: Optional[int] = Field(\n        default=0,\n        description=(\n            \"The maximum number of late runs in the work queue before it is deemed\"\n            \" unhealthy. Defaults to `0`.\"\n        ),\n    )\n    maximum_seconds_since_last_polled: Optional[int] = Field(\n        default=60,\n        description=(\n            \"The maximum number of time in seconds elapsed since work queue has been\"\n            \" polled before it is deemed unhealthy. Defaults to `60`.\"\n        ),\n    )\n\n    def evaluate_health_status(\n        self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n    ) -&gt; bool:\n        \"\"\"\n        Given empirical information about the state of the work queue, evaluate its health status.\n\n        Args:\n            late_runs: the count of late runs for the work queue.\n            last_polled: the last time the work queue was polled, if available.\n\n        Returns:\n            bool: whether or not the work queue is healthy.\n        \"\"\"\n        healthy = True\n        if (\n            self.maximum_late_runs is not None\n            and late_runs_count &gt; self.maximum_late_runs\n        ):\n            healthy = False\n\n        if self.maximum_seconds_since_last_polled is not None:\n            if (\n                last_polled is None\n                or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n                &gt; self.maximum_seconds_since_last_polled\n            ):\n                healthy = False\n\n        return healthy\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.WorkQueueHealthPolicy.evaluate_health_status","title":"<code>evaluate_health_status</code>","text":"<p>Given empirical information about the state of the work queue, evaluate its health status.</p> <p>Parameters:</p> Name Type Description Default <code>late_runs</code> <p>the count of late runs for the work queue.</p> required <code>last_polled</code> <code>Optional[DateTimeTZ]</code> <p>the last time the work queue was polled, if available.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>whether or not the work queue is healthy.</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>def evaluate_health_status(\n    self, late_runs_count: int, last_polled: Optional[DateTimeTZ] = None\n) -&gt; bool:\n    \"\"\"\n    Given empirical information about the state of the work queue, evaluate its health status.\n\n    Args:\n        late_runs: the count of late runs for the work queue.\n        last_polled: the last time the work queue was polled, if available.\n\n    Returns:\n        bool: whether or not the work queue is healthy.\n    \"\"\"\n    healthy = True\n    if (\n        self.maximum_late_runs is not None\n        and late_runs_count &gt; self.maximum_late_runs\n    ):\n        healthy = False\n\n    if self.maximum_seconds_since_last_polled is not None:\n        if (\n            last_polled is None\n            or pendulum.now(\"UTC\").diff(last_polled).in_seconds()\n            &gt; self.maximum_seconds_since_last_polled\n        ):\n            healthy = False\n\n    return healthy\n</code></pre>"},{"location":"api-ref/server/schemas/core/#prefect.server.schemas.core.Worker","title":"<code>Worker</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>An ORM representation of a worker</p> Source code in <code>prefect/server/schemas/core.py</code> <pre><code>class Worker(ORMBaseModel):\n    \"\"\"An ORM representation of a worker\"\"\"\n\n    name: str = Field(description=\"The name of the worker.\")\n    work_pool_id: UUID = Field(\n        description=\"The work pool with which the queue is associated.\"\n    )\n    last_heartbeat_time: datetime.datetime = Field(\n        None, description=\"The last time the worker process sent a heartbeat.\"\n    )\n    heartbeat_interval_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"The number of seconds to expect between heartbeats sent by the worker.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/filters/","title":"server.schemas.filters","text":""},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters","title":"<code>prefect.server.schemas.filters</code>","text":"<p>Schemas that define Prefect REST API filtering operations.</p> <p>Each filter schema includes logic for transforming itself into a SQL <code>where</code> clause.</p>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilter","title":"<code>ArtifactCollectionFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter artifact collections. Only artifact collections matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter artifact collections. Only artifact collections matching all criteria will be returned\"\"\"\n\n    latest_id: Optional[ArtifactCollectionFilterLatestId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactCollectionFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactCollectionFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactCollectionFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactCollectionFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.latest_id is not None:\n            filters.append(self.latest_id.as_sql_filter(db))\n        if self.key is not None:\n            filters.append(self.key.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId","title":"<code>ArtifactCollectionFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterKey","title":"<code>ArtifactCollectionFilterKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.key</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterKey(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key. Should return all rows in \"\n            \"the ArtifactCollection table if specified.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.key.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.ArtifactCollection.key.ilike(f\"%{self.like_}%\"))\n        if self.exists_ is not None:\n            filters.append(\n                db.ArtifactCollection.key.isnot(None)\n                if self.exists_\n                else db.ArtifactCollection.key.is_(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterLatestId","title":"<code>ArtifactCollectionFilterLatestId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.latest_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterLatestId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.latest_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.latest_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterLatestId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId","title":"<code>ArtifactCollectionFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterType","title":"<code>ArtifactCollectionFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>ArtifactCollection.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactCollectionFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `ArtifactCollection.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.ArtifactCollection.type.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.ArtifactCollection.type.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactCollectionFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilter","title":"<code>ArtifactFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter artifacts. Only artifacts matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter artifacts. Only artifacts matching all criteria will be returned\"\"\"\n\n    id: Optional[ArtifactFilterId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.id`\"\n    )\n    key: Optional[ArtifactFilterKey] = Field(\n        default=None, description=\"Filter criteria for `Artifact.key`\"\n    )\n    flow_run_id: Optional[ArtifactFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.flow_run_id`\"\n    )\n    task_run_id: Optional[ArtifactFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Artifact.task_run_id`\"\n    )\n    type: Optional[ArtifactFilterType] = Field(\n        default=None, description=\"Filter criteria for `Artifact.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.key is not None:\n            filters.append(self.key.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterFlowRunId","title":"<code>ArtifactFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterId","title":"<code>ArtifactFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of artifact ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterKey","title":"<code>ArtifactFilterKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.key</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterKey(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.key`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact keys to include\"\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match artifact keys against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-artifact-%\"],\n    )\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `true`, only include artifacts with a non-null key. If `false`, \"\n            \"only include artifacts with a null key.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.key.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Artifact.key.ilike(f\"%{self.like_}%\"))\n        if self.exists_ is not None:\n            filters.append(\n                db.Artifact.key.isnot(None)\n                if self.exists_\n                else db.Artifact.key.is_(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterTaskRunId","title":"<code>ArtifactFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterType","title":"<code>ArtifactFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Artifact.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class ArtifactFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `Artifact.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of artifact types to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Artifact.type.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.Artifact.type.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.ArtifactFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilter","title":"<code>BlockDocumentFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter BlockDocuments. Only BlockDocuments matching all criteria will be returned\"\"\"\n\n    id: Optional[BlockDocumentFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.id`\"\n    )\n    is_anonymous: Optional[BlockDocumentFilterIsAnonymous] = Field(\n        # default is to exclude anonymous blocks\n        BlockDocumentFilterIsAnonymous(eq_=False),\n        description=(\n            \"Filter criteria for `BlockDocument.is_anonymous`. \"\n            \"Defaults to excluding anonymous blocks.\"\n        ),\n    )\n    block_type_id: Optional[BlockDocumentFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.block_type_id`\"\n    )\n    name: Optional[BlockDocumentFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockDocument.name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.is_anonymous is not None:\n            filters.append(self.is_anonymous.as_sql_filter(db))\n        if self.block_type_id is not None:\n            filters.append(self.block_type_id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId","title":"<code>BlockDocumentFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.block_type_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterBlockTypeId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.block_type_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterBlockTypeId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterId","title":"<code>BlockDocumentFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous","title":"<code>BlockDocumentFilterIsAnonymous</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.is_anonymous</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterIsAnonymous(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.is_anonymous`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter block documents for only those that are or are not anonymous.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.BlockDocument.is_anonymous.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterIsAnonymous.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterName","title":"<code>BlockDocumentFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockDocument.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockDocumentFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockDocument.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of block names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match block names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-block%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockDocument.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.BlockDocument.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockDocumentFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilter","title":"<code>BlockSchemaFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter BlockSchemas</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter BlockSchemas\"\"\"\n\n    block_type_id: Optional[BlockSchemaFilterBlockTypeId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.block_type_id`\"\n    )\n    block_capabilities: Optional[BlockSchemaFilterCapabilities] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.capabilities`\"\n    )\n    id: Optional[BlockSchemaFilterId] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.id`\"\n    )\n    version: Optional[BlockSchemaFilterVersion] = Field(\n        default=None, description=\"Filter criteria for `BlockSchema.version`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.block_type_id is not None:\n            filters.append(self.block_type_id.as_sql_filter(db))\n        if self.block_capabilities is not None:\n            filters.append(self.block_capabilities.as_sql_filter(db))\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.version is not None:\n            filters.append(self.version.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId","title":"<code>BlockSchemaFilterBlockTypeId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.block_type_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterBlockTypeId(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.block_type_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of block type ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.block_type_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterBlockTypeId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterCapabilities","title":"<code>BlockSchemaFilterCapabilities</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterCapabilities(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"write-storage\", \"read-storage\"]],\n        description=(\n            \"A list of block capabilities. Block entities will be returned only if an\"\n            \" associated block schema has a superset of the defined capabilities.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.BlockSchema.capabilities, self.all_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterCapabilities.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterId","title":"<code>BlockSchemaFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by BlockSchema.id</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by BlockSchema.id\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterVersion","title":"<code>BlockSchemaFilterVersion</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockSchema.capabilities</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockSchemaFilterVersion(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockSchema.capabilities`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"2.0.0\", \"2.1.0\"]],\n        description=\"A list of block schema versions.\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        pass\n\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockSchema.version.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockSchemaFilterVersion.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilter","title":"<code>BlockTypeFilter</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter BlockTypes</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilter(PrefectFilterBaseModel):\n    \"\"\"Filter BlockTypes\"\"\"\n\n    name: Optional[BlockTypeFilterName] = Field(\n        default=None, description=\"Filter criteria for `BlockType.name`\"\n    )\n\n    slug: Optional[BlockTypeFilterSlug] = Field(\n        default=None, description=\"Filter criteria for `BlockType.slug`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.slug is not None:\n            filters.append(self.slug.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterName","title":"<code>BlockTypeFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockType.name</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockType.name`\"\"\"\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.like_ is not None:\n            filters.append(db.BlockType.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterSlug","title":"<code>BlockTypeFilterSlug</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>BlockType.slug</code></p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class BlockTypeFilterSlug(PrefectFilterBaseModel):\n    \"\"\"Filter by `BlockType.slug`\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of slugs to match\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.BlockType.slug.in_(self.any_))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.BlockTypeFilterSlug.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilter","title":"<code>DeploymentFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    id: Optional[DeploymentFilterId] = Field(\n        default=None, description=\"Filter criteria for `Deployment.id`\"\n    )\n    name: Optional[DeploymentFilterName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.name`\"\n    )\n    paused: Optional[DeploymentFilterPaused] = Field(\n        default=None, description=\"Filter criteria for `Deployment.paused`\"\n    )\n    is_schedule_active: Optional[DeploymentFilterIsScheduleActive] = Field(\n        default=None, description=\"Filter criteria for `Deployment.is_schedule_active`\"\n    )\n    tags: Optional[DeploymentFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Deployment.tags`\"\n    )\n    work_queue_name: Optional[DeploymentFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `Deployment.work_queue_name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.paused is not None:\n            filters.append(self.paused.as_sql_filter(db))\n        if self.is_schedule_active is not None:\n            filters.append(self.is_schedule_active.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.work_queue_name is not None:\n            filters.append(self.work_queue_name.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterId","title":"<code>DeploymentFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of deployment ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterIsScheduleActive","title":"<code>DeploymentFilterIsScheduleActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Legacy filter to filter by <code>Deployment.is_schedule_active</code> which is always the opposite of <code>Deployment.paused</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterIsScheduleActive(PrefectFilterBaseModel):\n    \"\"\"Legacy filter to filter by `Deployment.is_schedule_active` which\n    is always the opposite of `Deployment.paused`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.Deployment.paused.is_not(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterIsScheduleActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterName","title":"<code>DeploymentFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of deployment names to include\",\n        examples=[[\"my-deployment-1\", \"my-deployment-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Deployment.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterPaused","title":"<code>DeploymentFilterPaused</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.paused</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterPaused(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.paused`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment is/is not paused\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.Deployment.paused.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterPaused.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterTags","title":"<code>DeploymentFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Deployment.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Deployment.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Deployments will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include deployments without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Deployment.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.Deployment.tags == [] if self.is_null_ else db.Deployment.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterWorkQueueName","title":"<code>DeploymentFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Deployment.work_queue_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentFilterWorkQueueName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Deployment.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Deployment.work_queue_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentFilterWorkQueueName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilter","title":"<code>DeploymentScheduleFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for deployments. Only deployments matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentScheduleFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for deployments. Only deployments matching all criteria will be returned.\"\"\"\n\n    active: Optional[DeploymentScheduleFilterActive] = Field(\n        default=None, description=\"Filter criteria for `DeploymentSchedule.active`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.active is not None:\n            filters.append(self.active.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilterActive","title":"<code>DeploymentScheduleFilterActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>DeploymentSchedule.active</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class DeploymentScheduleFilterActive(PrefectFilterBaseModel):\n    \"\"\"Filter by `DeploymentSchedule.active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=\"Only returns where deployment schedule is/is not active\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.DeploymentSchedule.active.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.DeploymentScheduleFilterActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FilterSet","title":"<code>FilterSet</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A collection of filters for common objects</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FilterSet(PrefectBaseModel):\n    \"\"\"A collection of filters for common objects\"\"\"\n\n    flows: FlowFilter = Field(\n        default_factory=FlowFilter, description=\"Filters that apply to flows\"\n    )\n    flow_runs: FlowRunFilter = Field(\n        default_factory=FlowRunFilter, description=\"Filters that apply to flow runs\"\n    )\n    task_runs: TaskRunFilter = Field(\n        default_factory=TaskRunFilter, description=\"Filters that apply to task runs\"\n    )\n    deployments: DeploymentFilter = Field(\n        default_factory=DeploymentFilter,\n        description=\"Filters that apply to deployments\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FilterSet.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilter","title":"<code>FlowFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for flows. Only flows matching all criteria will be returned.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for flows. Only flows matching all criteria will be returned.\"\"\"\n\n    id: Optional[FlowFilterId] = Field(\n        default=None, description=\"Filter criteria for `Flow.id`\"\n    )\n    deployment: Optional[FlowFilterDeployment] = Field(\n        default=None, description=\"Filter criteria for Flow deployments\"\n    )\n    name: Optional[FlowFilterName] = Field(\n        default=None, description=\"Filter criteria for `Flow.name`\"\n    )\n    tags: Optional[FlowFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Flow.tags`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.deployment is not None:\n            filters.append(self.deployment.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterDeployment","title":"<code>FlowFilterDeployment</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by flows by deployment</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterDeployment(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by flows by deployment\"\"\"\n\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flows without deployments\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.is_null_ is not None:\n            deployments_subquery = (\n                sa.select(db.Deployment.flow_id).distinct().subquery()\n            )\n\n            if self.is_null_:\n                filters.append(\n                    db.Flow.id.not_in(sa.select(deployments_subquery.c.flow_id))\n                )\n            else:\n                filters.append(\n                    db.Flow.id.in_(sa.select(deployments_subquery.c.flow_id))\n                )\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterDeployment.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterId","title":"<code>FlowFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Flow.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Flow.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Flow.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterName","title":"<code>FlowFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Flow.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Flow.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow names to include\",\n        examples=[[\"my-flow-1\", \"my-flow-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Flow.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Flow.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterTags","title":"<code>FlowFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Flow.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Flow.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flows will be returned only if their tags are a superset\"\n            \" of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flows without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Flow.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(db.Flow.tags == [] if self.is_null_ else db.Flow.tags != [])\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilter","title":"<code>FlowRunFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter flow runs. Only flow runs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter flow runs. Only flow runs matching all criteria will be returned\"\"\"\n\n    id: Optional[FlowRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.id`\"\n    )\n    name: Optional[FlowRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.name`\"\n    )\n    tags: Optional[FlowRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.tags`\"\n    )\n    deployment_id: Optional[FlowRunFilterDeploymentId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.deployment_id`\"\n    )\n    work_queue_name: Optional[FlowRunFilterWorkQueueName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.work_queue_name\"\n    )\n    state: Optional[FlowRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state`\"\n    )\n    flow_version: Optional[FlowRunFilterFlowVersion] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.flow_version`\"\n    )\n    start_time: Optional[FlowRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.start_time`\"\n    )\n    expected_start_time: Optional[FlowRunFilterExpectedStartTime] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.expected_start_time`\"\n    )\n    next_scheduled_start_time: Optional[FlowRunFilterNextScheduledStartTime] = Field(\n        default=None,\n        description=\"Filter criteria for `FlowRun.next_scheduled_start_time`\",\n    )\n    parent_flow_run_id: Optional[FlowRunFilterParentFlowRunId] = Field(\n        default=None, description=\"Filter criteria for subflows of the given flow runs\"\n    )\n    parent_task_run_id: Optional[FlowRunFilterParentTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.parent_task_run_id`\"\n    )\n    idempotency_key: Optional[FlowRunFilterIdempotencyKey] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.idempotency_key`\"\n    )\n\n    def only_filters_on_id(self):\n        return (\n            self.id is not None\n            and (self.id.any_ and not self.id.not_any_)\n            and self.name is None\n            and self.tags is None\n            and self.deployment_id is None\n            and self.work_queue_name is None\n            and self.state is None\n            and self.flow_version is None\n            and self.start_time is None\n            and self.expected_start_time is None\n            and self.next_scheduled_start_time is None\n            and self.parent_flow_run_id is None\n            and self.parent_task_run_id is None\n            and self.idempotency_key is None\n        )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.deployment_id is not None:\n            filters.append(self.deployment_id.as_sql_filter(db))\n        if self.work_queue_name is not None:\n            filters.append(self.work_queue_name.as_sql_filter(db))\n        if self.flow_version is not None:\n            filters.append(self.flow_version.as_sql_filter(db))\n        if self.state is not None:\n            filters.append(self.state.as_sql_filter(db))\n        if self.start_time is not None:\n            filters.append(self.start_time.as_sql_filter(db))\n        if self.expected_start_time is not None:\n            filters.append(self.expected_start_time.as_sql_filter(db))\n        if self.next_scheduled_start_time is not None:\n            filters.append(self.next_scheduled_start_time.as_sql_filter(db))\n        if self.parent_flow_run_id is not None:\n            filters.append(self.parent_flow_run_id.as_sql_filter(db))\n        if self.parent_task_run_id is not None:\n            filters.append(self.parent_task_run_id.as_sql_filter(db))\n        if self.idempotency_key is not None:\n            filters.append(self.idempotency_key.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterDeploymentId","title":"<code>FlowRunFilterDeploymentId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.deployment_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterDeploymentId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.deployment_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run deployment ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without deployment ids\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.deployment_id.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.deployment_id.is_(None)\n                if self.is_null_\n                else db.FlowRun.deployment_id.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterDeploymentId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterExpectedStartTime","title":"<code>FlowRunFilterExpectedStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.expected_start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterExpectedStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.expected_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs scheduled to start at or after this time\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.expected_start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.expected_start_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterExpectedStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterFlowVersion","title":"<code>FlowRunFilterFlowVersion</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.flow_version</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterFlowVersion(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.flow_version`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run flow_versions to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.flow_version.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterFlowVersion.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterId","title":"<code>FlowRunFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to include\"\n    )\n    not_any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run ids to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.id.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.FlowRun.id.not_in(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterIdempotencyKey","title":"<code>FlowRunFilterIdempotencyKey</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by FlowRun.idempotency_key.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterIdempotencyKey(PrefectFilterBaseModel):\n    \"\"\"Filter by FlowRun.idempotency_key.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to include\"\n    )\n    not_any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run idempotency keys to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.idempotency_key.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.FlowRun.idempotency_key.not_in(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterIdempotencyKey.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterName","title":"<code>FlowRunFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of flow run names to include\",\n        examples=[[\"my-flow-run-1\", \"my-flow-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.FlowRun.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime","title":"<code>FlowRunFilterNextScheduledStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.next_scheduled_start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterNextScheduledStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.next_scheduled_start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time or before this\"\n            \" time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include flow runs with a next_scheduled_start_time at or after this\"\n            \" time\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.next_scheduled_start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.next_scheduled_start_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterNextScheduledStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentFlowRunId","title":"<code>FlowRunFilterParentFlowRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter for subflows of a given flow run</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterParentFlowRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter for subflows of a given flow run\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of parent flow run ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(\n                db.FlowRun.id.in_(\n                    sa.select(db.FlowRun.id)\n                    .join(\n                        db.TaskRun,\n                        sa.and_(\n                            db.TaskRun.id == db.FlowRun.parent_task_run_id,\n                        ),\n                    )\n                    .where(db.TaskRun.flow_run_id.in_(self.any_))\n                )\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentTaskRunId","title":"<code>FlowRunFilterParentTaskRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.parent_task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterParentTaskRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.parent_task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run parent_task_run_ids to include\"\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without parent_task_run_id\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.parent_task_run_id.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.parent_task_run_id.is_(None)\n                if self.is_null_\n                else db.FlowRun.parent_task_run_id.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterParentTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStartTime","title":"<code>FlowRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include flow runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return flow runs without a start time\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.FlowRun.start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.FlowRun.start_time &gt;= self.after_)\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.start_time.is_(None)\n                if self.is_null_\n                else db.FlowRun.start_time.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterState","title":"<code>FlowRunFilterState</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code> and <code>FlowRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterState(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_type` and `FlowRun.state_name`.\"\"\"\n\n    type: Optional[FlowRunFilterStateType] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state_type`\"\n    )\n    name: Optional[FlowRunFilterStateName] = Field(\n        default=None, description=\"Filter criteria for `FlowRun.state_name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.type is not None:\n            filters.extend(self.type._get_filter_list(db))\n        if self.name is not None:\n            filters.extend(self.name._get_filter_list(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterState.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateName","title":"<code>FlowRunFilterStateName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStateName(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of flow run state names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.state_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateType","title":"<code>FlowRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRun.state_type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterStateType(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRun.state_type`.\"\"\"\n\n    any_: Optional[List[schemas.states.StateType]] = Field(\n        default=None, description=\"A list of flow run state types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.state_type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterStateType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterTags","title":"<code>FlowRunFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Flow runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include flow runs without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.FlowRun.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.tags == [] if self.is_null_ else db.FlowRun.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterWorkQueueName","title":"<code>FlowRunFilterWorkQueueName</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>FlowRun.work_queue_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunFilterWorkQueueName(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `FlowRun.work_queue_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"work_queue_1\", \"work_queue_2\"]],\n    )\n    is_null_: Optional[bool] = Field(\n        default=None,\n        description=\"If true, only include flow runs without work queue names\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.FlowRun.work_queue_name.in_(self.any_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.FlowRun.work_queue_name.is_(None)\n                if self.is_null_\n                else db.FlowRun.work_queue_name.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunFilterWorkQueueName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilter","title":"<code>FlowRunNotificationPolicyFilter</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter FlowRunNotificationPolicies.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilter(PrefectFilterBaseModel):\n    \"\"\"Filter FlowRunNotificationPolicies.\"\"\"\n\n    is_active: Optional[FlowRunNotificationPolicyFilterIsActive] = Field(\n        default=FlowRunNotificationPolicyFilterIsActive(eq_=False),\n        description=\"Filter criteria for `FlowRunNotificationPolicy.is_active`. \",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.is_active is not None:\n            filters.append(self.is_active.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive","title":"<code>FlowRunNotificationPolicyFilterIsActive</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>FlowRunNotificationPolicy.is_active</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class FlowRunNotificationPolicyFilterIsActive(PrefectFilterBaseModel):\n    \"\"\"Filter by `FlowRunNotificationPolicy.is_active`.\"\"\"\n\n    eq_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Filter notification policies for only those that are or are not active.\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.eq_ is not None:\n            filters.append(db.FlowRunNotificationPolicy.is_active.is_(self.eq_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.FlowRunNotificationPolicyFilterIsActive.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilter","title":"<code>LogFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter logs. Only logs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter logs. Only logs matching all criteria will be returned\"\"\"\n\n    level: Optional[LogFilterLevel] = Field(\n        default=None, description=\"Filter criteria for `Log.level`\"\n    )\n    timestamp: Optional[LogFilterTimestamp] = Field(\n        default=None, description=\"Filter criteria for `Log.timestamp`\"\n    )\n    flow_run_id: Optional[LogFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.flow_run_id`\"\n    )\n    task_run_id: Optional[LogFilterTaskRunId] = Field(\n        default=None, description=\"Filter criteria for `Log.task_run_id`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.level is not None:\n            filters.append(self.level.as_sql_filter(db))\n        if self.timestamp is not None:\n            filters.append(self.timestamp.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n        if self.task_run_id is not None:\n            filters.append(self.task_run_id.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterFlowRunId","title":"<code>LogFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterFlowRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of flow run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterLevel","title":"<code>LogFilterLevel</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.level</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterLevel(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.level`.\"\"\"\n\n    ge_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level greater than or equal to this level\",\n        examples=[20],\n    )\n\n    le_: Optional[int] = Field(\n        default=None,\n        description=\"Include logs with a level less than or equal to this level\",\n        examples=[50],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.ge_ is not None:\n            filters.append(db.Log.level &gt;= self.ge_)\n        if self.le_ is not None:\n            filters.append(db.Log.level &lt;= self.le_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterLevel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterName","title":"<code>LogFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of log names to include\",\n        examples=[[\"prefect.logger.flow_runs\", \"prefect.logger.task_runs\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTaskRunId","title":"<code>LogFilterTaskRunId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.task_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterTaskRunId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.task_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run IDs to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Log.task_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTaskRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTimestamp","title":"<code>LogFilterTimestamp</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Log.timestamp</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class LogFilterTimestamp(PrefectFilterBaseModel):\n    \"\"\"Filter by `Log.timestamp`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include logs with a timestamp at or after this time\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.Log.timestamp &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.Log.timestamp &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.LogFilterTimestamp.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.Operator","title":"<code>Operator</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Operators for combining filter criteria.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class Operator(AutoEnum):\n    \"\"\"Operators for combining filter criteria.\"\"\"\n\n    and_ = AutoEnum.auto()\n    or_ = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.Operator.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectFilterBaseModel","title":"<code>PrefectFilterBaseModel</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Base model for Prefect filters</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class PrefectFilterBaseModel(PrefectBaseModel):\n    \"\"\"Base model for Prefect filters\"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    def as_sql_filter(self, db: \"PrefectDBInterface\") -&gt; \"BooleanClauseList\":\n        \"\"\"Generate SQL filter from provided filter parameters. If no filters parameters are available, return a TRUE filter.\"\"\"\n        filters = self._get_filter_list(db)\n        if not filters:\n            return True\n        return sa.and_(*filters)\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        \"\"\"Return a list of boolean filter statements based on filter parameters\"\"\"\n        raise NotImplementedError(\"_get_filter_list must be implemented\")\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectFilterBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel","title":"<code>PrefectOperatorFilterBaseModel</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Base model for Prefect filters that combines criteria with a user-provided operator</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class PrefectOperatorFilterBaseModel(PrefectFilterBaseModel):\n    \"\"\"Base model for Prefect filters that combines criteria with a user-provided operator\"\"\"\n\n    operator: Operator = Field(\n        default=Operator.and_,\n        description=\"Operator for combining filter criteria. Defaults to 'and_'.\",\n    )\n\n    def as_sql_filter(self, db: \"PrefectDBInterface\") -&gt; \"BooleanClauseList\":\n        filters = self._get_filter_list(db)\n        if not filters:\n            return True\n        return sa.and_(*filters) if self.operator == Operator.and_ else sa.or_(*filters)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.PrefectOperatorFilterBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilter","title":"<code>TaskRunFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter task runs. Only task runs matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter task runs. Only task runs matching all criteria will be returned\"\"\"\n\n    id: Optional[TaskRunFilterId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.id`\"\n    )\n    name: Optional[TaskRunFilterName] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.name`\"\n    )\n    tags: Optional[TaskRunFilterTags] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.tags`\"\n    )\n    state: Optional[TaskRunFilterState] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.state`\"\n    )\n    start_time: Optional[TaskRunFilterStartTime] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.start_time`\"\n    )\n    subflow_runs: Optional[TaskRunFilterSubFlowRuns] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.subflow_run`\"\n    )\n    flow_run_id: Optional[TaskRunFilterFlowRunId] = Field(\n        default=None, description=\"Filter criteria for `TaskRun.flow_run_id`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        if self.state is not None:\n            filters.append(self.state.as_sql_filter(db))\n        if self.start_time is not None:\n            filters.append(self.start_time.as_sql_filter(db))\n        if self.subflow_runs is not None:\n            filters.append(self.subflow_runs.as_sql_filter(db))\n        if self.flow_run_id is not None:\n            filters.append(self.flow_run_id.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterFlowRunId","title":"<code>TaskRunFilterFlowRunId</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.flow_run_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterFlowRunId(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.flow_run_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run flow run ids to include\"\n    )\n\n    is_null_: bool = Field(\n        default=False, description=\"Filter for task runs with None as their flow run id\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.is_null_ is True:\n            filters.append(db.TaskRun.flow_run_id.is_(None))\n        else:\n            if self.any_ is not None:\n                filters.append(db.TaskRun.flow_run_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterFlowRunId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterId","title":"<code>TaskRunFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of task run ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterName","title":"<code>TaskRunFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of task run names to include\",\n        examples=[[\"my-task-run-1\", \"my-task-run-2\"]],\n    )\n\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A case-insensitive partial match. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', 'sad-Marvin', and 'marvin-robot'.\"\n        ),\n        examples=[\"marvin\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.TaskRun.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStartTime","title":"<code>TaskRunFilterStartTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.start_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStartTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.start_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or before this time\",\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"Only include task runs starting at or after this time\",\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only return task runs without a start time\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.TaskRun.start_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.TaskRun.start_time &gt;= self.after_)\n        if self.is_null_ is not None:\n            filters.append(\n                db.TaskRun.start_time.is_(None)\n                if self.is_null_\n                else db.TaskRun.start_time.is_not(None)\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStartTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterState","title":"<code>TaskRunFilterState</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.type</code> and <code>TaskRun.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterState(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.type` and `TaskRun.name`.\"\"\"\n\n    type: Optional[TaskRunFilterStateType]\n    name: Optional[TaskRunFilterStateName]\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.type is not None:\n            filters.extend(self.type._get_filter_list(db))\n        if self.name is not None:\n            filters.extend(self.name._get_filter_list(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterState.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateName","title":"<code>TaskRunFilterStateName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.state_name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStateName(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.state_name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of task run state names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.state_name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateType","title":"<code>TaskRunFilterStateType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.state_type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterStateType(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.state_type`.\"\"\"\n\n    any_: Optional[List[schemas.states.StateType]] = Field(\n        default=None, description=\"A list of task run state types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.TaskRun.state_type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterStateType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterSubFlowRuns","title":"<code>TaskRunFilterSubFlowRuns</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>TaskRun.subflow_run</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterSubFlowRuns(PrefectFilterBaseModel):\n    \"\"\"Filter by `TaskRun.subflow_run`.\"\"\"\n\n    exists_: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If true, only include task runs that are subflow run parents; if false,\"\n            \" exclude parent task runs\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.exists_ is True:\n            filters.append(db.TaskRun.subflow_run.has())\n        elif self.exists_ is False:\n            filters.append(sa.not_(db.TaskRun.subflow_run.has()))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterSubFlowRuns.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterTags","title":"<code>TaskRunFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>TaskRun.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class TaskRunFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `TaskRun.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Task runs will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include task runs without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.TaskRun.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.TaskRun.tags == [] if self.is_null_ else db.TaskRun.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.TaskRunFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilter","title":"<code>VariableFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter variables. Only variables matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter variables. Only variables matching all criteria will be returned\"\"\"\n\n    id: Optional[VariableFilterId] = Field(\n        default=None, description=\"Filter criteria for `Variable.id`\"\n    )\n    name: Optional[VariableFilterName] = Field(\n        default=None, description=\"Filter criteria for `Variable.name`\"\n    )\n    value: Optional[VariableFilterValue] = Field(\n        default=None, description=\"Filter criteria for `Variable.value`\"\n    )\n    tags: Optional[VariableFilterTags] = Field(\n        default=None, description=\"Filter criteria for `Variable.tags`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.value is not None:\n            filters.append(self.value.as_sql_filter(db))\n        if self.tags is not None:\n            filters.append(self.tags.as_sql_filter(db))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterId","title":"<code>VariableFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of variable ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterName","title":"<code>VariableFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables names to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable names against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my_variable_%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.name.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Variable.name.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterTags","title":"<code>VariableFilterTags</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Variable.tags</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterTags(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Variable.tags`.\"\"\"\n\n    all_: Optional[List[str]] = Field(\n        default=None,\n        examples=[[\"tag-1\", \"tag-2\"]],\n        description=(\n            \"A list of tags. Variables will be returned only if their tags are a\"\n            \" superset of the list\"\n        ),\n    )\n    is_null_: Optional[bool] = Field(\n        default=None, description=\"If true, only include Variables without tags\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        from prefect.server.utilities.database import json_has_all_keys\n\n        filters = []\n        if self.all_ is not None:\n            filters.append(json_has_all_keys(db.Variable.tags, self.all_))\n        if self.is_null_ is not None:\n            filters.append(\n                db.Variable.tags == [] if self.is_null_ else db.Variable.tags != []\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterTags.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterValue","title":"<code>VariableFilterValue</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Variable.value</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class VariableFilterValue(PrefectFilterBaseModel):\n    \"\"\"Filter by `Variable.value`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of variables value to include\"\n    )\n    like_: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A string to match variable value against. This can include \"\n            \"SQL wildcard characters like `%` and `_`.\"\n        ),\n        examples=[\"my-value-%\"],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Variable.value.in_(self.any_))\n        if self.like_ is not None:\n            filters.append(db.Variable.value.ilike(f\"%{self.like_}%\"))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.VariableFilterValue.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilter","title":"<code>WorkPoolFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter work pools. Only work pools matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter work pools. Only work pools matching all criteria will be returned\"\"\"\n\n    id: Optional[WorkPoolFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.id`\"\n    )\n    name: Optional[WorkPoolFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.name`\"\n    )\n    type: Optional[WorkPoolFilterType] = Field(\n        default=None, description=\"Filter criteria for `WorkPool.type`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n        if self.type is not None:\n            filters.append(self.type.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterId","title":"<code>WorkPoolFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterName","title":"<code>WorkPoolFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool names to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.name.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterType","title":"<code>WorkPoolFilterType</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkPool.type</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkPoolFilterType(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkPool.type`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None, description=\"A list of work pool types to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkPool.type.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkPoolFilterType.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilter","title":"<code>WorkQueueFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter work queues. Only work queues matching all criteria will be returned</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter work queues. Only work queues matching all criteria will be\n    returned\"\"\"\n\n    id: Optional[WorkQueueFilterId] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.id`\"\n    )\n\n    name: Optional[WorkQueueFilterName] = Field(\n        default=None, description=\"Filter criteria for `WorkQueue.name`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.id is not None:\n            filters.append(self.id.as_sql_filter(db))\n        if self.name is not None:\n            filters.append(self.name.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterId","title":"<code>WorkQueueFilterId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkQueue.id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilterId(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkQueue.id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None,\n        description=\"A list of work queue ids to include\",\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkQueue.id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterName","title":"<code>WorkQueueFilterName</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>WorkQueue.name</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkQueueFilterName(PrefectFilterBaseModel):\n    \"\"\"Filter by `WorkQueue.name`.\"\"\"\n\n    any_: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of work queue names to include\",\n        examples=[[\"wq-1\", \"wq-2\"]],\n    )\n\n    startswith_: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"A list of case-insensitive starts-with matches. For example, \"\n            \" passing 'marvin' will match \"\n            \"'marvin', and 'Marvin-robot', but not 'sad-marvin'.\"\n        ),\n        examples=[[\"marvin\", \"Marvin-robot\"]],\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.WorkQueue.name.in_(self.any_))\n        if self.startswith_ is not None:\n            filters.append(\n                sa.or_(\n                    *[db.WorkQueue.name.ilike(f\"{item}%\") for item in self.startswith_]\n                )\n            )\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkQueueFilterName.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilter","title":"<code>WorkerFilter</code>","text":"<p>               Bases: <code>PrefectOperatorFilterBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilter(PrefectOperatorFilterBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    # worker_config_id: Optional[WorkerFilterWorkPoolId] = Field(\n    #     default=None, description=\"Filter criteria for `Worker.worker_config_id`\"\n    # )\n\n    last_heartbeat_time: Optional[WorkerFilterLastHeartbeatTime] = Field(\n        default=None,\n        description=\"Filter criteria for `Worker.last_heartbeat_time`\",\n    )\n\n    status: Optional[WorkerFilterStatus] = Field(\n        default=None, description=\"Filter criteria for `Worker.status`\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n\n        if self.last_heartbeat_time is not None:\n            filters.append(self.last_heartbeat_time.as_sql_filter(db))\n\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilter.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime","title":"<code>WorkerFilterLastHeartbeatTime</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.last_heartbeat_time</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterLastHeartbeatTime(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.last_heartbeat_time`.\"\"\"\n\n    before_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or before this time\"\n        ),\n    )\n    after_: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=(\n            \"Only include processes whose last heartbeat was at or after this time\"\n        ),\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.before_ is not None:\n            filters.append(db.Worker.last_heartbeat_time &lt;= self.before_)\n        if self.after_ is not None:\n            filters.append(db.Worker.last_heartbeat_time &gt;= self.after_)\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterLastHeartbeatTime.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterStatus","title":"<code>WorkerFilterStatus</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.status</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterStatus(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.status`.\"\"\"\n\n    any_: Optional[List[schemas.statuses.WorkerStatus]] = Field(\n        default=None, description=\"A list of worker statuses to include\"\n    )\n    not_any_: Optional[List[schemas.statuses.WorkerStatus]] = Field(\n        default=None, description=\"A list of worker statuses to exclude\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Worker.status.in_(self.any_))\n        if self.not_any_ is not None:\n            filters.append(db.Worker.status.notin_(self.not_any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterStatus.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterWorkPoolId","title":"<code>WorkerFilterWorkPoolId</code>","text":"<p>               Bases: <code>PrefectFilterBaseModel</code></p> <p>Filter by <code>Worker.worker_config_id</code>.</p> Source code in <code>prefect/server/schemas/filters.py</code> <pre><code>class WorkerFilterWorkPoolId(PrefectFilterBaseModel):\n    \"\"\"Filter by `Worker.worker_config_id`.\"\"\"\n\n    any_: Optional[List[UUID]] = Field(\n        default=None, description=\"A list of work pool ids to include\"\n    )\n\n    def _get_filter_list(self, db: \"PrefectDBInterface\") -&gt; List:\n        filters = []\n        if self.any_ is not None:\n            filters.append(db.Worker.worker_config_id.in_(self.any_))\n        return filters\n</code></pre>"},{"location":"api-ref/server/schemas/filters/#prefect.server.schemas.filters.WorkerFilterWorkPoolId.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/responses/","title":"server.schemas.responses","text":""},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses","title":"<code>prefect.server.schemas.responses</code>","text":"<p>Schemas for special responses from the Prefect REST API.</p>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.FlowRunResponse","title":"<code>FlowRunResponse</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class FlowRunResponse(ORMBaseModel):\n    name: str = Field(\n        default_factory=lambda: generate_slug(2),\n        description=(\n            \"The name of the flow run. Defaults to a random slug if not specified.\"\n        ),\n        examples=[\"my-flow-run\"],\n    )\n    flow_id: UUID = Field(default=..., description=\"The id of the flow being run.\")\n    state_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the flow run's current state.\"\n    )\n    deployment_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"The id of the deployment associated with this flow run, if available.\"\n        ),\n    )\n    deployment_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the deployment associated with this flow run.\",\n        examples=[\"1.0\"],\n    )\n    work_queue_id: Optional[UUID] = Field(\n        default=None, description=\"The id of the run's work pool queue.\"\n    )\n    work_queue_name: Optional[str] = Field(\n        default=None, description=\"The work queue that handled this flow run.\"\n    )\n    flow_version: Optional[str] = Field(\n        default=None,\n        description=\"The version of the flow executed in this flow run.\",\n        examples=[\"1.0\"],\n    )\n    parameters: Dict[str, Any] = Field(\n        default_factory=dict, description=\"Parameters for the flow run.\"\n    )\n    idempotency_key: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An optional idempotency key for the flow run. Used to ensure the same flow\"\n            \" run is not created multiple times.\"\n        ),\n    )\n    context: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional context for the flow run.\",\n        examples=[{\"my_var\": \"my_val\"}],\n    )\n    empirical_policy: FlowRunPolicy = Field(\n        default_factory=FlowRunPolicy,\n    )\n    tags: List[str] = Field(\n        default_factory=list,\n        description=\"A list of tags on the flow run\",\n        examples=[[\"tag-1\", \"tag-2\"]],\n    )\n    parent_task_run_id: Optional[UUID] = Field(\n        default=None,\n        description=(\n            \"If the flow run is a subflow, the id of the 'dummy' task in the parent\"\n            \" flow used to track subflow state.\"\n        ),\n    )\n    state_type: Optional[schemas.states.StateType] = Field(\n        default=None, description=\"The type of the current flow run state.\"\n    )\n    state_name: Optional[str] = Field(\n        default=None, description=\"The name of the current flow run state.\"\n    )\n    run_count: int = Field(\n        default=0, description=\"The number of times the flow run was executed.\"\n    )\n    expected_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The flow run's expected start time.\",\n    )\n    next_scheduled_start_time: Optional[DateTimeTZ] = Field(\n        default=None,\n        description=\"The next time the flow run is scheduled to start.\",\n    )\n    start_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual start time.\"\n    )\n    end_time: Optional[DateTimeTZ] = Field(\n        default=None, description=\"The actual end time.\"\n    )\n    total_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=(\n            \"Total run time. If the flow run was executed multiple times, the time of\"\n            \" each run will be summed.\"\n        ),\n    )\n    estimated_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"A real-time estimate of the total run time.\",\n    )\n    estimated_start_time_delta: datetime.timedelta = Field(\n        default=datetime.timedelta(0),\n        description=\"The difference between actual and expected start time.\",\n    )\n    auto_scheduled: bool = Field(\n        default=False,\n        description=\"Whether or not the flow run was automatically scheduled.\",\n    )\n    infrastructure_document_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The block document defining infrastructure to use this flow run.\",\n    )\n    infrastructure_pid: Optional[str] = Field(\n        default=None,\n        description=\"The id of the flow run as returned by an infrastructure block.\",\n    )\n    created_by: Optional[CreatedBy] = Field(\n        default=None,\n        description=\"Optional information about the creator of this flow run.\",\n    )\n    work_pool_id: Optional[UUID] = Field(\n        default=None,\n        description=\"The id of the flow run's work pool.\",\n    )\n    work_pool_name: Optional[str] = Field(\n        default=None,\n        description=\"The name of the flow run's work pool.\",\n        examples=[\"my-work-pool\"],\n    )\n    state: Optional[schemas.states.State] = Field(\n        default=None, description=\"The current state of the flow run.\"\n    )\n    job_variables: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=\"Variables used as overrides in the base job template\",\n    )\n\n    @classmethod\n    def from_orm(cls, orm_flow_run: \"ORMFlowRun\"):\n        response = super().from_orm(orm_flow_run)\n        if orm_flow_run.work_queue:\n            response.work_queue_id = orm_flow_run.work_queue.id\n            response.work_queue_name = orm_flow_run.work_queue.name\n            if orm_flow_run.work_queue.work_pool:\n                response.work_pool_id = orm_flow_run.work_queue.work_pool.id\n                response.work_pool_name = orm_flow_run.work_queue.work_pool.name\n\n        return response\n\n    def __eq__(self, other: Any) -&gt; bool:\n        \"\"\"\n        Check for \"equality\" to another flow run schema\n\n        Estimates times are rolling and will always change with repeated queries for\n        a flow run so we ignore them during equality checks.\n        \"\"\"\n        if isinstance(other, FlowRunResponse):\n            exclude_fields = {\"estimated_run_time\", \"estimated_start_time_delta\"}\n            return self.dict(exclude=exclude_fields) == other.dict(\n                exclude=exclude_fields\n            )\n        return super().__eq__(other)\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.GlobalConcurrencyLimitResponse","title":"<code>GlobalConcurrencyLimitResponse</code>","text":"<p>               Bases: <code>ORMBaseModel</code></p> <p>A response object for global concurrency limits.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class GlobalConcurrencyLimitResponse(ORMBaseModel):\n    \"\"\"\n    A response object for global concurrency limits.\n    \"\"\"\n\n    active: bool = Field(\n        default=True, description=\"Whether the global concurrency limit is active.\"\n    )\n    name: str = Field(\n        default=..., description=\"The name of the global concurrency limit.\"\n    )\n    limit: int = Field(default=..., description=\"The concurrency limit.\")\n    active_slots: int = Field(default=..., description=\"The number of active slots.\")\n    slot_decay_per_second: float = Field(\n        default=2.0,\n        description=\"The decay rate for active slots when used as a rate limit.\",\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.HistoryResponse","title":"<code>HistoryResponse</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a history of aggregation states over an interval</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class HistoryResponse(PrefectBaseModel):\n    \"\"\"Represents a history of aggregation states over an interval\"\"\"\n\n    interval_start: DateTimeTZ = Field(\n        default=..., description=\"The start date of the interval.\"\n    )\n    interval_end: DateTimeTZ = Field(\n        default=..., description=\"The end date of the interval.\"\n    )\n    states: List[HistoryResponseState] = Field(\n        default=..., description=\"A list of state histories during the interval.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.HistoryResponseState","title":"<code>HistoryResponseState</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Represents a single state's history over an interval.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class HistoryResponseState(PrefectBaseModel):\n    \"\"\"Represents a single state's history over an interval.\"\"\"\n\n    state_type: schemas.states.StateType = Field(\n        default=..., description=\"The state type.\"\n    )\n    state_name: str = Field(default=..., description=\"The state name.\")\n    count_runs: int = Field(\n        default=...,\n        description=\"The number of runs in the specified state during the interval.\",\n    )\n    sum_estimated_run_time: datetime.timedelta = Field(\n        default=...,\n        description=\"The total estimated run time of all runs during the interval.\",\n    )\n    sum_estimated_lateness: datetime.timedelta = Field(\n        default=...,\n        description=(\n            \"The sum of differences between actual and expected start time during the\"\n            \" interval.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.OrchestrationResult","title":"<code>OrchestrationResult</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A container for the output of state orchestration.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class OrchestrationResult(PrefectBaseModel):\n    \"\"\"\n    A container for the output of state orchestration.\n    \"\"\"\n\n    state: Optional[schemas.states.State]\n    status: SetStateStatus\n    details: StateResponseDetails\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.SetStateStatus","title":"<code>SetStateStatus</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumerates return statuses for setting run states.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class SetStateStatus(AutoEnum):\n    \"\"\"Enumerates return statuses for setting run states.\"\"\"\n\n    ACCEPT = AutoEnum.auto()\n    REJECT = AutoEnum.auto()\n    ABORT = AutoEnum.auto()\n    WAIT = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateAbortDetails","title":"<code>StateAbortDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ABORT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateAbortDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ABORT state transition.\"\"\"\n\n    type: Literal[\"abort_details\"] = Field(\n        default=\"abort_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was aborted.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateAcceptDetails","title":"<code>StateAcceptDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with an ACCEPT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateAcceptDetails(PrefectBaseModel):\n    \"\"\"Details associated with an ACCEPT state transition.\"\"\"\n\n    type: Literal[\"accept_details\"] = Field(\n        default=\"accept_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateRejectDetails","title":"<code>StateRejectDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a REJECT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateRejectDetails(PrefectBaseModel):\n    \"\"\"Details associated with a REJECT state transition.\"\"\"\n\n    type: Literal[\"reject_details\"] = Field(\n        default=\"reject_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition was rejected.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.StateWaitDetails","title":"<code>StateWaitDetails</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Details associated with a WAIT state transition.</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class StateWaitDetails(PrefectBaseModel):\n    \"\"\"Details associated with a WAIT state transition.\"\"\"\n\n    type: Literal[\"wait_details\"] = Field(\n        default=\"wait_details\",\n        description=(\n            \"The type of state transition detail. Used to ensure pydantic does not\"\n            \" coerce into a different type.\"\n        ),\n    )\n    delay_seconds: int = Field(\n        default=...,\n        description=(\n            \"The length of time in seconds the client should wait before transitioning\"\n            \" states.\"\n        ),\n    )\n    reason: Optional[str] = Field(\n        default=None, description=\"The reason why the state transition should wait.\"\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/responses/#prefect.server.schemas.responses.WorkQueueWithStatus","title":"<code>WorkQueueWithStatus</code>","text":"<p>               Bases: <code>WorkQueueResponse</code>, <code>WorkQueueStatusDetail</code></p> <p>Combines a work queue and its status details into a single object</p> Source code in <code>prefect/server/schemas/responses.py</code> <pre><code>class WorkQueueWithStatus(WorkQueueResponse, WorkQueueStatusDetail):\n    \"\"\"Combines a work queue and its status details into a single object\"\"\"\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/","title":"server.schemas.schedules","text":""},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules","title":"<code>prefect.server.schemas.schedules</code>","text":"<p>Schedule schemas</p>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>Cron schedule</p> <p>NOTE: If the timezone is a DST-observing one, then the schedule will adjust itself appropriately. Cron's rules for DST are based on schedule times, not intervals. This means that an hourly cron schedule will fire on every new schedule hour, not every elapsed hour; for example, when clocks are set back this will result in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. Longer schedules, such as one that fires at 9am every morning, will automatically adjust for DST.</p> <p>Parameters:</p> Name Type Description Default <code>cron</code> <code>str</code> <p>a valid cron string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string in IANA tzdata format (for example, America/New_York).</p> required <code>day_or</code> <code>bool</code> <p>Control how croniter handles <code>day</code> and <code>day_of_week</code> entries. Defaults to True, matching cron which connects those values using OR. If the switch is set to False, the values are connected using AND. This behaves like fcron and enables you to e.g. define a job that executes each 2nd friday of a month by setting the days of month and the weekday.</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class CronSchedule(PrefectBaseModel):\n    \"\"\"\n    Cron schedule\n\n    NOTE: If the timezone is a DST-observing one, then the schedule will adjust\n    itself appropriately. Cron's rules for DST are based on schedule times, not\n    intervals. This means that an hourly cron schedule will fire on every new\n    schedule hour, not every elapsed hour; for example, when clocks are set back\n    this will result in a two-hour pause as the schedule will fire *the first\n    time* 1am is reached and *the first time* 2am is reached, 120 minutes later.\n    Longer schedules, such as one that fires at 9am every morning, will\n    automatically adjust for DST.\n\n    Args:\n        cron (str): a valid cron string\n        timezone (str): a valid timezone string in IANA tzdata format (for example,\n            America/New_York).\n        day_or (bool, optional): Control how croniter handles `day` and `day_of_week`\n            entries. Defaults to True, matching cron which connects those values using\n            OR. If the switch is set to False, the values are connected using AND. This\n            behaves like fcron and enables you to e.g. define a job that executes each\n            2nd friday of a month by setting the days of month and the weekday.\n\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    cron: str = Field(default=..., examples=[\"0 0 * * *\"])\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n    day_or: bool = Field(\n        default=True,\n        description=(\n            \"Control croniter behavior for handling day and day_of_week entries.\"\n        ),\n    )\n\n    @validator(\"timezone\")\n    def validate_timezone(cls, v, *, values, **kwargs):\n        return default_timezone(v, values)\n\n    @validator(\"cron\")\n    def valid_cron_string(cls, v):\n        return validate_cron_string(v)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to the current date. If a timezone-naive\n                datetime is provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): No returned date will exceed this date.\n                If a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up to\n            # MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        elif self.timezone:\n            start = start.in_tz(self.timezone)\n\n        # subtract one second from the start date, so that croniter returns it\n        # as an event (if it meets the cron criteria)\n        start = start.subtract(seconds=1)\n\n        # Respect microseconds by rounding up\n        if start.microsecond &gt; 0:\n            start += datetime.timedelta(seconds=1)\n\n        # croniter's DST logic interferes with all other datetime libraries except pytz\n        start_localized = pytz.timezone(start.tz.name).localize(\n            datetime.datetime(\n                year=start.year,\n                month=start.month,\n                day=start.day,\n                hour=start.hour,\n                minute=start.minute,\n                second=start.second,\n                microsecond=start.microsecond,\n            )\n        )\n        start_naive_tz = start.naive()\n\n        cron = croniter(self.cron, start_naive_tz, day_or=self.day_or)  # type: ignore\n        dates = set()\n        counter = 0\n\n        while True:\n            # croniter does not handle DST properly when the start time is\n            # in and around when the actual shift occurs. To work around this,\n            # we use the naive start time to get the next cron date delta, then\n            # add that time to the original scheduling anchor.\n            next_time = cron.get_next(datetime.datetime)\n            delta = next_time - start_naive_tz\n            next_date = pendulum.instance(start_localized + delta)\n\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.CronSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.IntervalSchedule","title":"<code>IntervalSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>A schedule formed by adding <code>interval</code> increments to an <code>anchor_date</code>. If no <code>anchor_date</code> is supplied, the current UTC time is used.  If a timezone-naive datetime is provided for <code>anchor_date</code>, it is assumed to be in the schedule's timezone (or UTC). Even if supplied with an IANA timezone, anchor dates are always stored as UTC offsets, so a <code>timezone</code> can be provided to determine localization behaviors like DST boundary handling. If none is provided it will be inferred from the anchor date.</p> <p>NOTE: If the <code>IntervalSchedule</code> <code>anchor_date</code> or <code>timezone</code> is provided in a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals. For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant. This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>timedelta</code> <p>an interval to schedule on.</p> required <code>anchor_date</code> <code>DateTimeTZ</code> <p>an anchor date to schedule increments against; if not provided, the current timestamp will be used.</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string.</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class IntervalSchedule(PrefectBaseModel):\n    \"\"\"\n    A schedule formed by adding `interval` increments to an `anchor_date`. If no\n    `anchor_date` is supplied, the current UTC time is used.  If a\n    timezone-naive datetime is provided for `anchor_date`, it is assumed to be\n    in the schedule's timezone (or UTC). Even if supplied with an IANA timezone,\n    anchor dates are always stored as UTC offsets, so a `timezone` can be\n    provided to determine localization behaviors like DST boundary handling. If\n    none is provided it will be inferred from the anchor date.\n\n    NOTE: If the `IntervalSchedule` `anchor_date` or `timezone` is provided in a\n    DST-observing timezone, then the schedule will adjust itself appropriately.\n    Intervals greater than 24 hours will follow DST conventions, while intervals\n    of less than 24 hours will follow UTC intervals. For example, an hourly\n    schedule will fire every UTC hour, even across DST boundaries. When clocks\n    are set back, this will result in two runs that *appear* to both be\n    scheduled for 1am local time, even though they are an hour apart in UTC\n    time. For longer intervals, like a daily schedule, the interval schedule\n    will adjust for DST boundaries so that the clock-hour remains constant. This\n    means that a daily schedule that always fires at 9am will observe DST and\n    continue to fire at 9am in the local time zone.\n\n    Args:\n        interval (datetime.timedelta): an interval to schedule on.\n        anchor_date (DateTimeTZ, optional): an anchor date to schedule increments against;\n            if not provided, the current timestamp will be used.\n        timezone (str, optional): a valid timezone string.\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n        exclude_none = True\n\n    interval: PositiveDuration\n    anchor_date: DateTimeTZ = None\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"anchor_date\", always=True)\n    def validate_anchor_date(cls, v):\n        return default_anchor_date(v)\n\n    @validator(\"timezone\", always=True)\n    def validate_timezone(cls, v, *, values, **kwargs):\n        return default_timezone(v, values)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up to\n            # MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        anchor_tz = self.anchor_date.in_tz(self.timezone)\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        # compute the offset between the anchor date and the start date to jump to the\n        # next date\n        offset = (start - anchor_tz).total_seconds() / self.interval.total_seconds()\n        next_date = anchor_tz.add(seconds=self.interval.total_seconds() * int(offset))\n\n        # break the interval into `days` and `seconds` because pendulum\n        # will handle DST boundaries properly if days are provided, but not\n        # if we add `total seconds`. Therefore, `next_date + self.interval`\n        # fails while `next_date.add(days=days, seconds=seconds)` works.\n        interval_days = self.interval.days\n        interval_seconds = self.interval.total_seconds() - (\n            interval_days * 24 * 60 * 60\n        )\n\n        # daylight saving time boundaries can create a situation where the next date is\n        # before the start date, so we advance it if necessary\n        while next_date &lt; start:\n            next_date = next_date.add(days=interval_days, seconds=interval_seconds)\n\n        counter = 0\n        dates = set()\n\n        while True:\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n\n            next_date = next_date.add(days=interval_days, seconds=interval_seconds)\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.IntervalSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule","title":"<code>RRuleSchedule</code>","text":"<p>               Bases: <code>PrefectBaseModel</code></p> <p>RRule schedule, based on the iCalendar standard (RFC 5545) as implemented in <code>dateutils.rrule</code>.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including irregular intervals, repetition, exclusions, week day or day-of-month adjustments, and more.</p> <p>Note that as a calendar-oriented standard, <code>RRuleSchedules</code> are sensitive to to the initial timezone provided. A 9am daily schedule with a daylight saving time-aware start date will maintain a local 9am time through DST boundaries; a 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p> <p>Parameters:</p> Name Type Description Default <code>rrule</code> <code>str</code> <p>a valid RRule string</p> required <code>timezone</code> <code>str</code> <p>a valid timezone string</p> required Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>class RRuleSchedule(PrefectBaseModel):\n    \"\"\"\n    RRule schedule, based on the iCalendar standard\n    ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) as\n    implemented in `dateutils.rrule`.\n\n    RRules are appropriate for any kind of calendar-date manipulation, including\n    irregular intervals, repetition, exclusions, week day or day-of-month\n    adjustments, and more.\n\n    Note that as a calendar-oriented standard, `RRuleSchedules` are sensitive to\n    to the initial timezone provided. A 9am daily schedule with a daylight saving\n    time-aware start date will maintain a local 9am time through DST boundaries;\n    a 9am daily schedule with a UTC start date will maintain a 9am UTC time.\n\n    Args:\n        rrule (str): a valid RRule string\n        timezone (str, optional): a valid timezone string\n    \"\"\"\n\n    class Config:\n        extra = \"forbid\"\n\n    rrule: str\n    timezone: Optional[str] = Field(default=None, examples=[\"America/New_York\"])\n\n    @validator(\"rrule\")\n    def validate_rrule_str(cls, v):\n        return validate_rrule_string(v)\n\n    @classmethod\n    def from_rrule(cls, rrule: dateutil.rrule.rrule):\n        if isinstance(rrule, dateutil.rrule.rrule):\n            if rrule._dtstart.tzinfo is not None:\n                timezone = rrule._dtstart.tzinfo.name\n            else:\n                timezone = \"UTC\"\n            return RRuleSchedule(rrule=str(rrule), timezone=timezone)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            dtstarts = [rr._dtstart for rr in rrule._rrule if rr._dtstart is not None]\n            unique_dstarts = set(pendulum.instance(d).in_tz(\"UTC\") for d in dtstarts)\n            unique_timezones = set(d.tzinfo for d in dtstarts if d.tzinfo is not None)\n\n            if len(unique_timezones) &gt; 1:\n                raise ValueError(\n                    f\"rruleset has too many dtstart timezones: {unique_timezones}\"\n                )\n\n            if len(unique_dstarts) &gt; 1:\n                raise ValueError(f\"rruleset has too many dtstarts: {unique_dstarts}\")\n\n            if unique_dstarts and unique_timezones:\n                timezone = dtstarts[0].tzinfo.name\n            else:\n                timezone = \"UTC\"\n\n            rruleset_string = \"\"\n            if rrule._rrule:\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._rrule)\n            if rrule._exrule:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"\\n\".join(str(r) for r in rrule._exrule).replace(\n                    \"RRULE\", \"EXRULE\"\n                )\n            if rrule._rdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"RDATE:\" + \",\".join(\n                    rd.strftime(\"%Y%m%dT%H%M%SZ\") for rd in rrule._rdate\n                )\n            if rrule._exdate:\n                rruleset_string += \"\\n\" if rruleset_string else \"\"\n                rruleset_string += \"EXDATE:\" + \",\".join(\n                    exd.strftime(\"%Y%m%dT%H%M%SZ\") for exd in rrule._exdate\n                )\n            return RRuleSchedule(rrule=rruleset_string, timezone=timezone)\n        else:\n            raise ValueError(f\"Invalid RRule object: {rrule}\")\n\n    def to_rrule(self) -&gt; dateutil.rrule.rrule:\n        \"\"\"\n        Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n        here\n        \"\"\"\n        rrule = dateutil.rrule.rrulestr(\n            self.rrule,\n            dtstart=DEFAULT_ANCHOR_DATE,\n            cache=True,\n        )\n        timezone = dateutil.tz.gettz(self.timezone)\n        if isinstance(rrule, dateutil.rrule.rrule):\n            kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n            if rrule._until:\n                kwargs.update(\n                    until=rrule._until.replace(tzinfo=timezone),\n                )\n            return rrule.replace(**kwargs)\n        elif isinstance(rrule, dateutil.rrule.rruleset):\n            # update rrules\n            localized_rrules = []\n            for rr in rrule._rrule:\n                kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n                if rr._until:\n                    kwargs.update(\n                        until=rr._until.replace(tzinfo=timezone),\n                    )\n                localized_rrules.append(rr.replace(**kwargs))\n            rrule._rrule = localized_rrules\n\n            # update exrules\n            localized_exrules = []\n            for exr in rrule._exrule:\n                kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n                if exr._until:\n                    kwargs.update(\n                        until=exr._until.replace(tzinfo=timezone),\n                    )\n                localized_exrules.append(exr.replace(**kwargs))\n            rrule._exrule = localized_exrules\n\n            # update rdates\n            localized_rdates = []\n            for rd in rrule._rdate:\n                localized_rdates.append(rd.replace(tzinfo=timezone))\n            rrule._rdate = localized_rdates\n\n            # update exdates\n            localized_exdates = []\n            for exd in rrule._exdate:\n                localized_exdates.append(exd.replace(tzinfo=timezone))\n            rrule._exdate = localized_exdates\n\n            return rrule\n\n    @validator(\"timezone\", always=True)\n    def valid_timezone(cls, v):\n        return validate_rrule_timezone(v)\n\n    async def get_dates(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; List[pendulum.DateTime]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to None.  If a timezone-naive datetime is\n                provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): The maximum scheduled date to return. If\n                a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: A list of dates\n        \"\"\"\n        return sorted(self._get_dates_generator(n=n, start=start, end=end))\n\n    def _get_dates_generator(\n        self,\n        n: int = None,\n        start: datetime.datetime = None,\n        end: datetime.datetime = None,\n    ) -&gt; Generator[pendulum.DateTime, None, None]:\n        \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n        following the start date.\n\n        Args:\n            n (int): The number of dates to generate\n            start (datetime.datetime, optional): The first returned date will be on or\n                after this date. Defaults to the current date. If a timezone-naive\n                datetime is provided, it is assumed to be in the schedule's timezone.\n            end (datetime.datetime, optional): No returned date will exceed this date.\n                If a timezone-naive datetime is provided, it is assumed to be in the\n                schedule's timezone.\n\n        Returns:\n            List[pendulum.DateTime]: a list of dates\n        \"\"\"\n        if start is None:\n            start = pendulum.now(\"UTC\")\n\n        start, end = _prepare_scheduling_start_and_end(start, end, self.timezone)\n\n        if n is None:\n            # if an end was supplied, we do our best to supply all matching dates (up\n            # to MAX_ITERATIONS)\n            if end is not None:\n                n = MAX_ITERATIONS\n            else:\n                n = 1\n\n        dates = set()\n        counter = 0\n\n        # pass count = None to account for discrepancies with duplicates around DST\n        # boundaries\n        for next_date in self.to_rrule().xafter(start, count=None, inc=True):\n            next_date = pendulum.instance(next_date).in_tz(self.timezone)\n\n            # if the end date was exceeded, exit\n            if end and next_date &gt; end:\n                break\n\n            # ensure no duplicates; weird things can happen with DST\n            if next_date not in dates:\n                dates.add(next_date)\n                yield next_date\n\n            # if enough dates have been collected or enough attempts were made, exit\n            if len(dates) &gt;= n or counter &gt; MAX_ITERATIONS:\n                break\n\n            counter += 1\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule.get_dates","title":"<code>get_dates</code>  <code>async</code>","text":"<p>Retrieves dates from the schedule. Up to 1,000 candidate dates are checked following the start date.</p> <p>Parameters:</p> Name Type Description Default <code>n</code> <code>int</code> <p>The number of dates to generate</p> <code>None</code> <code>start</code> <code>datetime</code> <p>The first returned date will be on or after this date. Defaults to None.  If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <code>end</code> <code>datetime</code> <p>The maximum scheduled date to return. If a timezone-naive datetime is provided, it is assumed to be in the schedule's timezone.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[DateTime]</code> <p>List[pendulum.DateTime]: A list of dates</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>async def get_dates(\n    self,\n    n: int = None,\n    start: datetime.datetime = None,\n    end: datetime.datetime = None,\n) -&gt; List[pendulum.DateTime]:\n    \"\"\"Retrieves dates from the schedule. Up to 1,000 candidate dates are checked\n    following the start date.\n\n    Args:\n        n (int): The number of dates to generate\n        start (datetime.datetime, optional): The first returned date will be on or\n            after this date. Defaults to None.  If a timezone-naive datetime is\n            provided, it is assumed to be in the schedule's timezone.\n        end (datetime.datetime, optional): The maximum scheduled date to return. If\n            a timezone-naive datetime is provided, it is assumed to be in the\n            schedule's timezone.\n\n    Returns:\n        List[pendulum.DateTime]: A list of dates\n    \"\"\"\n    return sorted(self._get_dates_generator(n=n, start=start, end=end))\n</code></pre>"},{"location":"api-ref/server/schemas/schedules/#prefect.server.schemas.schedules.RRuleSchedule.to_rrule","title":"<code>to_rrule</code>","text":"<p>Since rrule doesn't properly serialize/deserialize timezones, we localize dates here</p> Source code in <code>prefect/server/schemas/schedules.py</code> <pre><code>def to_rrule(self) -&gt; dateutil.rrule.rrule:\n    \"\"\"\n    Since rrule doesn't properly serialize/deserialize timezones, we localize dates\n    here\n    \"\"\"\n    rrule = dateutil.rrule.rrulestr(\n        self.rrule,\n        dtstart=DEFAULT_ANCHOR_DATE,\n        cache=True,\n    )\n    timezone = dateutil.tz.gettz(self.timezone)\n    if isinstance(rrule, dateutil.rrule.rrule):\n        kwargs = dict(dtstart=rrule._dtstart.replace(tzinfo=timezone))\n        if rrule._until:\n            kwargs.update(\n                until=rrule._until.replace(tzinfo=timezone),\n            )\n        return rrule.replace(**kwargs)\n    elif isinstance(rrule, dateutil.rrule.rruleset):\n        # update rrules\n        localized_rrules = []\n        for rr in rrule._rrule:\n            kwargs = dict(dtstart=rr._dtstart.replace(tzinfo=timezone))\n            if rr._until:\n                kwargs.update(\n                    until=rr._until.replace(tzinfo=timezone),\n                )\n            localized_rrules.append(rr.replace(**kwargs))\n        rrule._rrule = localized_rrules\n\n        # update exrules\n        localized_exrules = []\n        for exr in rrule._exrule:\n            kwargs = dict(dtstart=exr._dtstart.replace(tzinfo=timezone))\n            if exr._until:\n                kwargs.update(\n                    until=exr._until.replace(tzinfo=timezone),\n                )\n            localized_exrules.append(exr.replace(**kwargs))\n        rrule._exrule = localized_exrules\n\n        # update rdates\n        localized_rdates = []\n        for rd in rrule._rdate:\n            localized_rdates.append(rd.replace(tzinfo=timezone))\n        rrule._rdate = localized_rdates\n\n        # update exdates\n        localized_exdates = []\n        for exd in rrule._exdate:\n            localized_exdates.append(exd.replace(tzinfo=timezone))\n        rrule._exdate = localized_exdates\n\n        return rrule\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/","title":"server.schemas.sorting","text":""},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting","title":"<code>prefect.server.schemas.sorting</code>","text":"<p>Schemas for sorting Prefect REST API objects.</p>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactCollectionSort","title":"<code>ArtifactCollectionSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact collection sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class ArtifactCollectionSort(AutoEnum):\n    \"\"\"Defines artifact collection sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort artifact collections\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.ArtifactCollection.created.desc(),\n            \"UPDATED_DESC\": db.ArtifactCollection.updated.desc(),\n            \"ID_DESC\": db.ArtifactCollection.id.desc(),\n            \"KEY_DESC\": db.ArtifactCollection.key.desc(),\n            \"KEY_ASC\": db.ArtifactCollection.key.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactCollectionSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort artifact collections</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort artifact collections\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.ArtifactCollection.created.desc(),\n        \"UPDATED_DESC\": db.ArtifactCollection.updated.desc(),\n        \"ID_DESC\": db.ArtifactCollection.id.desc(),\n        \"KEY_DESC\": db.ArtifactCollection.key.desc(),\n        \"KEY_ASC\": db.ArtifactCollection.key.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactSort","title":"<code>ArtifactSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines artifact sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class ArtifactSort(AutoEnum):\n    \"\"\"Defines artifact sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    ID_DESC = AutoEnum.auto()\n    KEY_DESC = AutoEnum.auto()\n    KEY_ASC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort artifacts\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Artifact.created.desc(),\n            \"UPDATED_DESC\": db.Artifact.updated.desc(),\n            \"ID_DESC\": db.Artifact.id.desc(),\n            \"KEY_DESC\": db.Artifact.key.desc(),\n            \"KEY_ASC\": db.Artifact.key.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.ArtifactSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort artifacts</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort artifacts\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Artifact.created.desc(),\n        \"UPDATED_DESC\": db.Artifact.updated.desc(),\n        \"ID_DESC\": db.Artifact.id.desc(),\n        \"KEY_DESC\": db.Artifact.key.desc(),\n        \"KEY_ASC\": db.Artifact.key.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.BlockDocumentSort","title":"<code>BlockDocumentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines block document sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class BlockDocumentSort(AutoEnum):\n    \"\"\"Defines block document sorting options.\"\"\"\n\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n    BLOCK_TYPE_AND_NAME_ASC = \"BLOCK_TYPE_AND_NAME_ASC\"\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort block documents\"\"\"\n        sort_mapping = {\n            \"NAME_DESC\": db.BlockDocument.name.desc(),\n            \"NAME_ASC\": db.BlockDocument.name.asc(),\n            \"BLOCK_TYPE_AND_NAME_ASC\": sa.text(\"block_type_name asc, name asc\"),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.BlockDocumentSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort block documents</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort block documents\"\"\"\n    sort_mapping = {\n        \"NAME_DESC\": db.BlockDocument.name.desc(),\n        \"NAME_ASC\": db.BlockDocument.name.asc(),\n        \"BLOCK_TYPE_AND_NAME_ASC\": sa.text(\"block_type_name asc, name asc\"),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.DeploymentSort","title":"<code>DeploymentSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines deployment sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class DeploymentSort(AutoEnum):\n    \"\"\"Defines deployment sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort deployments\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Deployment.created.desc(),\n            \"UPDATED_DESC\": db.Deployment.updated.desc(),\n            \"NAME_ASC\": db.Deployment.name.asc(),\n            \"NAME_DESC\": db.Deployment.name.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.DeploymentSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort deployments</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort deployments\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Deployment.created.desc(),\n        \"UPDATED_DESC\": db.Deployment.updated.desc(),\n        \"NAME_ASC\": db.Deployment.name.asc(),\n        \"NAME_DESC\": db.Deployment.name.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowRunSort","title":"<code>FlowRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow run sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class FlowRunSort(AutoEnum):\n    \"\"\"Defines flow run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    START_TIME_ASC = AutoEnum.auto()\n    START_TIME_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        from sqlalchemy.sql.functions import coalesce\n\n        \"\"\"Return an expression used to sort flow runs\"\"\"\n        sort_mapping = {\n            \"ID_DESC\": db.FlowRun.id.desc(),\n            \"START_TIME_ASC\": coalesce(\n                db.FlowRun.start_time, db.FlowRun.expected_start_time\n            ).asc(),\n            \"START_TIME_DESC\": coalesce(\n                db.FlowRun.start_time, db.FlowRun.expected_start_time\n            ).desc(),\n            \"EXPECTED_START_TIME_ASC\": db.FlowRun.expected_start_time.asc(),\n            \"EXPECTED_START_TIME_DESC\": db.FlowRun.expected_start_time.desc(),\n            \"NAME_ASC\": db.FlowRun.name.asc(),\n            \"NAME_DESC\": db.FlowRun.name.desc(),\n            \"NEXT_SCHEDULED_START_TIME_ASC\": db.FlowRun.next_scheduled_start_time.asc(),\n            \"END_TIME_DESC\": db.FlowRun.end_time.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowSort","title":"<code>FlowSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines flow sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class FlowSort(AutoEnum):\n    \"\"\"Defines flow sorting options.\"\"\"\n\n    CREATED_DESC = AutoEnum.auto()\n    UPDATED_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort flows\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Flow.created.desc(),\n            \"UPDATED_DESC\": db.Flow.updated.desc(),\n            \"NAME_ASC\": db.Flow.name.asc(),\n            \"NAME_DESC\": db.Flow.name.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.FlowSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort flows</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort flows\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Flow.created.desc(),\n        \"UPDATED_DESC\": db.Flow.updated.desc(),\n        \"NAME_ASC\": db.Flow.name.asc(),\n        \"NAME_DESC\": db.Flow.name.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.LogSort","title":"<code>LogSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines log sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class LogSort(AutoEnum):\n    \"\"\"Defines log sorting options.\"\"\"\n\n    TIMESTAMP_ASC = AutoEnum.auto()\n    TIMESTAMP_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort task runs\"\"\"\n        sort_mapping = {\n            \"TIMESTAMP_ASC\": db.Log.timestamp.asc(),\n            \"TIMESTAMP_DESC\": db.Log.timestamp.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.LogSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort task runs</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort task runs\"\"\"\n    sort_mapping = {\n        \"TIMESTAMP_ASC\": db.Log.timestamp.asc(),\n        \"TIMESTAMP_DESC\": db.Log.timestamp.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.TaskRunSort","title":"<code>TaskRunSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines task run sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class TaskRunSort(AutoEnum):\n    \"\"\"Defines task run sorting options.\"\"\"\n\n    ID_DESC = AutoEnum.auto()\n    EXPECTED_START_TIME_ASC = AutoEnum.auto()\n    EXPECTED_START_TIME_DESC = AutoEnum.auto()\n    NAME_ASC = AutoEnum.auto()\n    NAME_DESC = AutoEnum.auto()\n    NEXT_SCHEDULED_START_TIME_ASC = AutoEnum.auto()\n    END_TIME_DESC = AutoEnum.auto()\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort task runs\"\"\"\n        sort_mapping = {\n            \"ID_DESC\": db.TaskRun.id.desc(),\n            \"EXPECTED_START_TIME_ASC\": db.TaskRun.expected_start_time.asc(),\n            \"EXPECTED_START_TIME_DESC\": db.TaskRun.expected_start_time.desc(),\n            \"NAME_ASC\": db.TaskRun.name.asc(),\n            \"NAME_DESC\": db.TaskRun.name.desc(),\n            \"NEXT_SCHEDULED_START_TIME_ASC\": db.TaskRun.next_scheduled_start_time.asc(),\n            \"END_TIME_DESC\": db.TaskRun.end_time.desc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.TaskRunSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort task runs</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort task runs\"\"\"\n    sort_mapping = {\n        \"ID_DESC\": db.TaskRun.id.desc(),\n        \"EXPECTED_START_TIME_ASC\": db.TaskRun.expected_start_time.asc(),\n        \"EXPECTED_START_TIME_DESC\": db.TaskRun.expected_start_time.desc(),\n        \"NAME_ASC\": db.TaskRun.name.asc(),\n        \"NAME_DESC\": db.TaskRun.name.desc(),\n        \"NEXT_SCHEDULED_START_TIME_ASC\": db.TaskRun.next_scheduled_start_time.asc(),\n        \"END_TIME_DESC\": db.TaskRun.end_time.desc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.VariableSort","title":"<code>VariableSort</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Defines variables sorting options.</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>class VariableSort(AutoEnum):\n    \"\"\"Defines variables sorting options.\"\"\"\n\n    CREATED_DESC = \"CREATED_DESC\"\n    UPDATED_DESC = \"UPDATED_DESC\"\n    NAME_DESC = \"NAME_DESC\"\n    NAME_ASC = \"NAME_ASC\"\n\n    def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n        \"\"\"Return an expression used to sort variables\"\"\"\n        sort_mapping = {\n            \"CREATED_DESC\": db.Variable.created.desc(),\n            \"UPDATED_DESC\": db.Variable.updated.desc(),\n            \"NAME_DESC\": db.Variable.name.desc(),\n            \"NAME_ASC\": db.Variable.name.asc(),\n        }\n        return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/sorting/#prefect.server.schemas.sorting.VariableSort.as_sql_sort","title":"<code>as_sql_sort</code>","text":"<p>Return an expression used to sort variables</p> Source code in <code>prefect/server/schemas/sorting.py</code> <pre><code>def as_sql_sort(self, db: \"PrefectDBInterface\") -&gt; \"ColumnElement\":\n    \"\"\"Return an expression used to sort variables\"\"\"\n    sort_mapping = {\n        \"CREATED_DESC\": db.Variable.created.desc(),\n        \"UPDATED_DESC\": db.Variable.updated.desc(),\n        \"NAME_DESC\": db.Variable.name.desc(),\n        \"NAME_ASC\": db.Variable.name.asc(),\n    }\n    return sort_mapping[self.value]\n</code></pre>"},{"location":"api-ref/server/schemas/states/","title":"server.schemas.states","text":""},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states","title":"<code>prefect.server.schemas.states</code>","text":"<p>State schemas.</p>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State","title":"<code>State</code>","text":"<p>               Bases: <code>StateBaseModel</code></p> <p>Represents the state of a run.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class State(StateBaseModel):\n    \"\"\"Represents the state of a run.\"\"\"\n\n    class Config:\n        orm_mode = True\n\n    type: StateType\n    name: Optional[str] = Field(default=None)\n    timestamp: DateTimeTZ = Field(default_factory=lambda: pendulum.now(\"UTC\"))\n    message: Optional[str] = Field(default=None, examples=[\"Run started\"])\n    data: Optional[Any] = Field(\n        default=None,\n        description=(\n            \"Data associated with the state, e.g. a result. \"\n            \"Content must be storable as JSON.\"\n        ),\n    )\n    state_details: StateDetails = Field(default_factory=StateDetails)\n\n    @classmethod\n    def from_orm_without_result(\n        cls,\n        orm_state: Union[\n            \"prefect.server.database.orm_models.ORMFlowRunState\",\n            \"prefect.server.database.orm_models.ORMTaskRunState\",\n        ],\n        with_data: Optional[Any] = None,\n    ):\n        \"\"\"\n        During orchestration, ORM states can be instantiated prior to inserting results\n        into the artifact table and the `data` field will not be eagerly loaded. In\n        these cases, sqlalchemy will attempt to lazily load the the relationship, which\n        will fail when called within a synchronous pydantic method.\n\n        This method will construct a `State` object from an ORM model without a loaded\n        artifact and attach data passed using the `with_data` argument to the `data`\n        field.\n        \"\"\"\n\n        field_keys = cls.schema()[\"properties\"].keys()\n        state_data = {\n            field: getattr(orm_state, field, None)\n            for field in field_keys\n            if field != \"data\"\n        }\n        state_data[\"data\"] = with_data\n        return cls(**state_data)\n\n    @validator(\"name\", always=True)\n    def default_name_from_type(cls, v, *, values, **kwargs):\n        return get_or_create_state_name(v, values)\n\n    @root_validator\n    def default_scheduled_start_time(cls, values):\n        return set_default_scheduled_time(cls, values)\n\n    def is_scheduled(self) -&gt; bool:\n        return self.type == StateType.SCHEDULED\n\n    def is_pending(self) -&gt; bool:\n        return self.type == StateType.PENDING\n\n    def is_running(self) -&gt; bool:\n        return self.type == StateType.RUNNING\n\n    def is_completed(self) -&gt; bool:\n        return self.type == StateType.COMPLETED\n\n    def is_failed(self) -&gt; bool:\n        return self.type == StateType.FAILED\n\n    def is_crashed(self) -&gt; bool:\n        return self.type == StateType.CRASHED\n\n    def is_cancelled(self) -&gt; bool:\n        return self.type == StateType.CANCELLED\n\n    def is_cancelling(self) -&gt; bool:\n        return self.type == StateType.CANCELLING\n\n    def is_final(self) -&gt; bool:\n        return self.type in TERMINAL_STATES\n\n    def is_paused(self) -&gt; bool:\n        return self.type == StateType.PAUSED\n\n    def copy(\n        self,\n        *,\n        update: Optional[Dict[str, Any]] = None,\n        reset_fields: bool = False,\n        **kwargs,\n    ):\n        \"\"\"\n        Copying API models should return an object that could be inserted into the\n        database again. The 'timestamp' is reset using the default factory.\n        \"\"\"\n        update = update or {}\n        update.setdefault(\"timestamp\", self.__fields__[\"timestamp\"].get_default())\n        return super().copy(reset_fields=reset_fields, update=update, **kwargs)\n\n    def result(self, raise_on_failure: bool = True, fetch: Optional[bool] = None):\n        # Backwards compatible `result` handling on the server-side schema\n        from prefect.states import State\n\n        warnings.warn(\n            (\n                \"`result` is no longer supported by\"\n                \" `prefect.server.schemas.states.State` and will be removed in a future\"\n                \" release. When result retrieval is needed, use `prefect.states.State`.\"\n            ),\n            DeprecationWarning,\n            stacklevel=2,\n        )\n\n        state = State.parse_obj(self)\n        return state.result(raise_on_failure=raise_on_failure, fetch=fetch)\n\n    def to_state_create(self):\n        # Backwards compatibility for `to_state_create`\n        from prefect.client.schemas import State\n\n        warnings.warn(\n            (\n                \"Use of `prefect.server.schemas.states.State` from the client is\"\n                \" deprecated and support will be removed in a future release. Use\"\n                \" `prefect.states.State` instead.\"\n            ),\n            DeprecationWarning,\n            stacklevel=2,\n        )\n\n        state = State.parse_obj(self)\n        return state.to_state_create()\n\n    def __repr__(self) -&gt; str:\n        \"\"\"\n        Generates a complete state representation appropriate for introspection\n        and debugging, including the result:\n\n        `MyCompletedState(message=\"my message\", type=COMPLETED, result=...)`\n        \"\"\"\n        from prefect.deprecated.data_documents import DataDocument\n\n        if isinstance(self.data, DataDocument):\n            result = self.data.decode()\n        else:\n            result = self.data\n\n        display = dict(\n            message=repr(self.message),\n            type=str(self.type.value),\n            result=repr(result),\n        )\n\n        return f\"{self.name}({', '.join(f'{k}={v}' for k, v in display.items())})\"\n\n    def __str__(self) -&gt; str:\n        \"\"\"\n        Generates a simple state representation appropriate for logging:\n\n        `MyCompletedState(\"my message\", type=COMPLETED)`\n        \"\"\"\n\n        display = []\n\n        if self.message:\n            display.append(repr(self.message))\n\n        if self.type.value.lower() != self.name.lower():\n            display.append(f\"type={self.type.value}\")\n\n        return f\"{self.name}({', '.join(display)})\"\n\n    def __hash__(self) -&gt; int:\n        return hash(\n            (\n                getattr(self.state_details, \"flow_run_id\", None),\n                getattr(self.state_details, \"task_run_id\", None),\n                self.timestamp,\n                self.type,\n            )\n        )\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State.from_orm_without_result","title":"<code>from_orm_without_result</code>  <code>classmethod</code>","text":"<p>During orchestration, ORM states can be instantiated prior to inserting results into the artifact table and the <code>data</code> field will not be eagerly loaded. In these cases, sqlalchemy will attempt to lazily load the the relationship, which will fail when called within a synchronous pydantic method.</p> <p>This method will construct a <code>State</code> object from an ORM model without a loaded artifact and attach data passed using the <code>with_data</code> argument to the <code>data</code> field.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>@classmethod\ndef from_orm_without_result(\n    cls,\n    orm_state: Union[\n        \"prefect.server.database.orm_models.ORMFlowRunState\",\n        \"prefect.server.database.orm_models.ORMTaskRunState\",\n    ],\n    with_data: Optional[Any] = None,\n):\n    \"\"\"\n    During orchestration, ORM states can be instantiated prior to inserting results\n    into the artifact table and the `data` field will not be eagerly loaded. In\n    these cases, sqlalchemy will attempt to lazily load the the relationship, which\n    will fail when called within a synchronous pydantic method.\n\n    This method will construct a `State` object from an ORM model without a loaded\n    artifact and attach data passed using the `with_data` argument to the `data`\n    field.\n    \"\"\"\n\n    field_keys = cls.schema()[\"properties\"].keys()\n    state_data = {\n        field: getattr(orm_state, field, None)\n        for field in field_keys\n        if field != \"data\"\n    }\n    state_data[\"data\"] = with_data\n    return cls(**state_data)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.State.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateBaseModel","title":"<code>StateBaseModel</code>","text":"<p>               Bases: <code>IDBaseModel</code></p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class StateBaseModel(IDBaseModel):\n    def orm_dict(\n        self, *args, shallow: bool = False, json_compatible: bool = False, **kwargs\n    ) -&gt; dict:\n        \"\"\"\n        This method is used as a convenience method for constructing fixtues by first\n        building a `State` schema object and converting it into an ORM-compatible\n        format. Because the `data` field is not writable on ORM states, this method\n        omits the `data` field entirely for the purposes of constructing an ORM model.\n        If state data is required, an artifact must be created separately.\n        \"\"\"\n\n        schema_dict = self.dict(\n            *args, shallow=shallow, json_compatible=json_compatible, **kwargs\n        )\n        # remove the data field in order to construct a state ORM model\n        schema_dict.pop(\"data\", None)\n        return schema_dict\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateBaseModel.json","title":"<code>json</code>","text":"<p>Returns a representation of the model as JSON.</p> <p>If <code>include_secrets=True</code>, then <code>SecretStr</code> and <code>SecretBytes</code> objects are fully revealed. Otherwise they are obfuscated.</p> Source code in <code>prefect/server/utilities/schemas/bases.py</code> <pre><code>def json(self, *args, include_secrets: bool = False, **kwargs) -&gt; str:\n    \"\"\"\n    Returns a representation of the model as JSON.\n\n    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are\n    fully revealed. Otherwise they are obfuscated.\n\n    \"\"\"\n    if include_secrets:\n        if \"encoder\" in kwargs:\n            raise ValueError(\n                \"Alternative encoder provided; can not set encoder for\"\n                \" SecretFields.\"\n            )\n        kwargs[\"encoder\"] = partial(\n            custom_pydantic_encoder,\n            {SecretField: lambda v: v.get_secret_value() if v else None},\n        )\n    return super().json(*args, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateType","title":"<code>StateType</code>","text":"<p>               Bases: <code>AutoEnum</code></p> <p>Enumeration of state types.</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>class StateType(AutoEnum):\n    \"\"\"Enumeration of state types.\"\"\"\n\n    SCHEDULED = AutoEnum.auto()\n    PENDING = AutoEnum.auto()\n    RUNNING = AutoEnum.auto()\n    COMPLETED = AutoEnum.auto()\n    FAILED = AutoEnum.auto()\n    CANCELLED = AutoEnum.auto()\n    CRASHED = AutoEnum.auto()\n    PAUSED = AutoEnum.auto()\n    CANCELLING = AutoEnum.auto()\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.StateType.auto","title":"<code>auto</code>  <code>staticmethod</code>","text":"<p>Exposes <code>enum.auto()</code> to avoid requiring a second import to use <code>AutoEnum</code></p> Source code in <code>prefect/utilities/collections.py</code> <pre><code>@staticmethod\ndef auto():\n    \"\"\"\n    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`\n    \"\"\"\n    return auto()\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.AwaitingRetry","title":"<code>AwaitingRetry</code>","text":"<p>Convenience function for creating <code>AwaitingRetry</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a AwaitingRetry state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def AwaitingRetry(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `AwaitingRetry` states.\n\n    Returns:\n        State: a AwaitingRetry state\n    \"\"\"\n    return Scheduled(\n        cls=cls, scheduled_time=scheduled_time, name=\"AwaitingRetry\", **kwargs\n    )\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Cancelled","title":"<code>Cancelled</code>","text":"<p>Convenience function for creating <code>Cancelled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Cancelled state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Cancelled(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Cancelled` states.\n\n    Returns:\n        State: a Cancelled state\n    \"\"\"\n    return cls(type=StateType.CANCELLED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Cancelling","title":"<code>Cancelling</code>","text":"<p>Convenience function for creating <code>Cancelling</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Cancelling state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Cancelling(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Cancelling` states.\n\n    Returns:\n        State: a Cancelling state\n    \"\"\"\n    return cls(type=StateType.CANCELLING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Completed","title":"<code>Completed</code>","text":"<p>Convenience function for creating <code>Completed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Completed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Completed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Completed` states.\n\n    Returns:\n        State: a Completed state\n    \"\"\"\n    return cls(type=StateType.COMPLETED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Crashed","title":"<code>Crashed</code>","text":"<p>Convenience function for creating <code>Crashed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Crashed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Crashed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Crashed` states.\n\n    Returns:\n        State: a Crashed state\n    \"\"\"\n    return cls(type=StateType.CRASHED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Failed","title":"<code>Failed</code>","text":"<p>Convenience function for creating <code>Failed</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Failed state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Failed(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Failed` states.\n\n    Returns:\n        State: a Failed state\n    \"\"\"\n    return cls(type=StateType.FAILED, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Late","title":"<code>Late</code>","text":"<p>Convenience function for creating <code>Late</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Late state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Late(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `Late` states.\n\n    Returns:\n        State: a Late state\n    \"\"\"\n    return Scheduled(cls=cls, scheduled_time=scheduled_time, name=\"Late\", **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Paused","title":"<code>Paused</code>","text":"<p>Convenience function for creating <code>Paused</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Paused state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Paused(\n    cls: Type[State] = State,\n    timeout_seconds: int = None,\n    pause_expiration_time: datetime.datetime = None,\n    reschedule: bool = False,\n    pause_key: str = None,\n    **kwargs,\n) -&gt; State:\n    \"\"\"Convenience function for creating `Paused` states.\n\n    Returns:\n        State: a Paused state\n    \"\"\"\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n\n    if state_details.pause_timeout:\n        raise ValueError(\"An extra pause timeout was provided in state_details\")\n\n    if pause_expiration_time is not None and timeout_seconds is not None:\n        raise ValueError(\n            \"Cannot supply both a pause_expiration_time and timeout_seconds\"\n        )\n\n    if pause_expiration_time is None and timeout_seconds is None:\n        pass\n    else:\n        state_details.pause_timeout = pause_expiration_time or (\n            pendulum.now(\"UTC\") + pendulum.Duration(seconds=timeout_seconds)\n        )\n\n    state_details.pause_reschedule = reschedule\n    state_details.pause_key = pause_key\n\n    return cls(type=StateType.PAUSED, state_details=state_details, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Pending","title":"<code>Pending</code>","text":"<p>Convenience function for creating <code>Pending</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Pending state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Pending(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Pending` states.\n\n    Returns:\n        State: a Pending state\n    \"\"\"\n    return cls(type=StateType.PENDING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Retrying","title":"<code>Retrying</code>","text":"<p>Convenience function for creating <code>Retrying</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Retrying state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Retrying(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Retrying` states.\n\n    Returns:\n        State: a Retrying state\n    \"\"\"\n    return cls(type=StateType.RUNNING, name=\"Retrying\", **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Running","title":"<code>Running</code>","text":"<p>Convenience function for creating <code>Running</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Running state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Running(cls: Type[State] = State, **kwargs) -&gt; State:\n    \"\"\"Convenience function for creating `Running` states.\n\n    Returns:\n        State: a Running state\n    \"\"\"\n    return cls(type=StateType.RUNNING, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Scheduled","title":"<code>Scheduled</code>","text":"<p>Convenience function for creating <code>Scheduled</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>a Scheduled state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Scheduled(\n    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs\n) -&gt; State:\n    \"\"\"Convenience function for creating `Scheduled` states.\n\n    Returns:\n        State: a Scheduled state\n    \"\"\"\n    # NOTE: `scheduled_time` must come first for backwards compatibility\n\n    state_details = StateDetails.parse_obj(kwargs.pop(\"state_details\", {}))\n    if scheduled_time is None:\n        scheduled_time = pendulum.now(\"UTC\")\n    elif state_details.scheduled_time:\n        raise ValueError(\"An extra scheduled_time was provided in state_details\")\n    state_details.scheduled_time = scheduled_time\n\n    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)\n</code></pre>"},{"location":"api-ref/server/schemas/states/#prefect.server.schemas.states.Suspended","title":"<code>Suspended</code>","text":"<p>Convenience function for creating <code>Suspended</code> states.</p> <p>Returns:</p> Name Type Description <code>State</code> <p>a Suspended state</p> Source code in <code>prefect/server/schemas/states.py</code> <pre><code>def Suspended(\n    cls: Type[State] = State,\n    timeout_seconds: Optional[int] = None,\n    pause_expiration_time: Optional[datetime.datetime] = None,\n    pause_key: Optional[str] = None,\n    **kwargs,\n):\n    \"\"\"Convenience function for creating `Suspended` states.\n\n    Returns:\n        State: a Suspended state\n    \"\"\"\n    return Paused(\n        cls=cls,\n        name=\"Suspended\",\n        reschedule=True,\n        timeout_seconds=timeout_seconds,\n        pause_expiration_time=pause_expiration_time,\n        pause_key=pause_key,\n        **kwargs,\n    )\n</code></pre>"},{"location":"api-ref/server/services/late_runs/","title":"server.services.late_runs","text":""},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs","title":"<code>prefect.server.services.late_runs</code>","text":"<p>The MarkLateRuns service. Responsible for putting flow runs in a Late state if they are not started on time. The threshold for a late run can be configured by changing <code>PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS</code>.</p>"},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs.MarkLateRuns","title":"<code>MarkLateRuns</code>","text":"<p>               Bases: <code>LoopService</code></p> <p>A simple loop service responsible for identifying flow runs that are \"late\".</p> <p>A flow run is defined as \"late\" if has not scheduled within a certain amount of time after its scheduled start time. The exact amount is configurable in Prefect REST API Settings.</p> Source code in <code>prefect/server/services/late_runs.py</code> <pre><code>class MarkLateRuns(LoopService):\n    \"\"\"\n    A simple loop service responsible for identifying flow runs that are \"late\".\n\n    A flow run is defined as \"late\" if has not scheduled within a certain amount\n    of time after its scheduled start time. The exact amount is configurable in\n    Prefect REST API Settings.\n    \"\"\"\n\n    def __init__(self, loop_seconds: float = None, **kwargs):\n        super().__init__(\n            loop_seconds=loop_seconds\n            or PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS.value(),\n            **kwargs,\n        )\n\n        # mark runs late if they are this far past their expected start time\n        self.mark_late_after: datetime.timedelta = (\n            PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS.value()\n        )\n\n        # query for this many runs to mark as late at once\n        self.batch_size = 400\n\n    @inject_db\n    async def run_once(self, db: PrefectDBInterface):\n        \"\"\"\n        Mark flow runs as late by:\n\n        - Querying for flow runs in a scheduled state that are Scheduled to start in the past\n        - For any runs past the \"late\" threshold, setting the flow run state to a new `Late` state\n        \"\"\"\n        scheduled_to_start_before = pendulum.now(\"UTC\").subtract(\n            seconds=self.mark_late_after.total_seconds()\n        )\n\n        while True:\n            async with db.session_context(begin_transaction=True) as session:\n                query = self._get_select_late_flow_runs_query(\n                    scheduled_to_start_before=scheduled_to_start_before, db=db\n                )\n\n                result = await session.execute(query)\n                runs = result.all()\n\n                # mark each run as late\n                for run in runs:\n                    await self._mark_flow_run_as_late(session=session, flow_run=run)\n\n                # if no runs were found, exit the loop\n                if len(runs) &lt; self.batch_size:\n                    break\n\n        self.logger.info(\"Finished monitoring for late runs.\")\n\n    @inject_db\n    def _get_select_late_flow_runs_query(\n        self, scheduled_to_start_before: datetime.datetime, db: PrefectDBInterface\n    ):\n        \"\"\"\n        Returns a sqlalchemy query for late flow runs.\n\n        Args:\n            scheduled_to_start_before: the maximum next scheduled start time of\n                scheduled flow runs to consider in the returned query\n        \"\"\"\n        query = (\n            sa.select(\n                db.FlowRun.id,\n                db.FlowRun.next_scheduled_start_time,\n            )\n            .where(\n                # The next scheduled start time is in the past, including the mark late\n                # after buffer\n                (db.FlowRun.next_scheduled_start_time &lt;= scheduled_to_start_before),\n                db.FlowRun.state_type == states.StateType.SCHEDULED,\n                db.FlowRun.state_name == \"Scheduled\",\n            )\n            .limit(self.batch_size)\n        )\n        return query\n\n    async def _mark_flow_run_as_late(\n        self, session: AsyncSession, flow_run: PrefectDBInterface.FlowRun\n    ) -&gt; None:\n        \"\"\"\n        Mark a flow run as late.\n\n        Pass-through method for overrides.\n        \"\"\"\n        try:\n            await models.flow_runs.set_flow_run_state(\n                session=session,\n                flow_run_id=flow_run.id,\n                state=states.Late(scheduled_time=flow_run.next_scheduled_start_time),\n                flow_policy=MarkLateRunsPolicy,  # type: ignore\n            )\n        except ObjectNotFoundError:\n            return  # flow run was deleted, ignore it\n</code></pre>"},{"location":"api-ref/server/services/late_runs/#prefect.server.services.late_runs.MarkLateRuns.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Mark flow runs as late by:</p> <ul> <li>Querying for flow runs in a scheduled state that are Scheduled to start in the past</li> <li>For any runs past the \"late\" threshold, setting the flow run state to a new <code>Late</code> state</li> </ul> Source code in <code>prefect/server/services/late_runs.py</code> <pre><code>@inject_db\nasync def run_once(self, db: PrefectDBInterface):\n    \"\"\"\n    Mark flow runs as late by:\n\n    - Querying for flow runs in a scheduled state that are Scheduled to start in the past\n    - For any runs past the \"late\" threshold, setting the flow run state to a new `Late` state\n    \"\"\"\n    scheduled_to_start_before = pendulum.now(\"UTC\").subtract(\n        seconds=self.mark_late_after.total_seconds()\n    )\n\n    while True:\n        async with db.session_context(begin_transaction=True) as session:\n            query = self._get_select_late_flow_runs_query(\n                scheduled_to_start_before=scheduled_to_start_before, db=db\n            )\n\n            result = await session.execute(query)\n            runs = result.all()\n\n            # mark each run as late\n            for run in runs:\n                await self._mark_flow_run_as_late(session=session, flow_run=run)\n\n            # if no runs were found, exit the loop\n            if len(runs) &lt; self.batch_size:\n                break\n\n    self.logger.info(\"Finished monitoring for late runs.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/","title":"server.services.loop_service","text":""},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service","title":"<code>prefect.server.services.loop_service</code>","text":"<p>The base class for all Prefect REST API loop services.</p>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService","title":"<code>LoopService</code>","text":"<p>Loop services are relatively lightweight maintenance routines that need to run periodically.</p> <p>This class makes it straightforward to design and integrate them. Users only need to define the <code>run_once</code> coroutine to describe the behavior of the service on each loop.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>class LoopService:\n    \"\"\"\n    Loop services are relatively lightweight maintenance routines that need to run periodically.\n\n    This class makes it straightforward to design and integrate them. Users only need to\n    define the `run_once` coroutine to describe the behavior of the service on each loop.\n    \"\"\"\n\n    loop_seconds = 60\n\n    def __init__(self, loop_seconds: float = None, handle_signals: bool = True):\n        \"\"\"\n        Args:\n            loop_seconds (float): if provided, overrides the loop interval\n                otherwise specified as a class variable\n            handle_signals (bool): if True (default), SIGINT and SIGTERM are\n                gracefully intercepted and shut down the running service.\n        \"\"\"\n        if loop_seconds:\n            self.loop_seconds = loop_seconds  # seconds between runs\n        self._should_stop = False  # flag for whether the service should stop running\n        self._is_running = False  # flag for whether the service is running\n        self.name = type(self).__name__\n        self.logger = get_logger(f\"server.services.{self.name.lower()}\")\n\n        if handle_signals:\n            _register_signal(signal.SIGINT, self._stop)\n            _register_signal(signal.SIGTERM, self._stop)\n\n    @inject_db\n    async def _on_start(self, db: PrefectDBInterface) -&gt; None:\n        \"\"\"\n        Called prior to running the service\n        \"\"\"\n        # reset the _should_stop flag\n        self._should_stop = False\n        # set the _is_running flag\n        self._is_running = True\n\n    async def _on_stop(self) -&gt; None:\n        \"\"\"\n        Called after running the service\n        \"\"\"\n        # reset the _is_running flag\n        self._is_running = False\n\n    async def start(self, loops=None) -&gt; None:\n        \"\"\"\n        Run the service `loops` time. Pass loops=None to run forever.\n\n        Args:\n            loops (int, optional): the number of loops to run before exiting.\n        \"\"\"\n\n        await self._on_start()\n\n        i = 0\n        while not self._should_stop:\n            start_time = pendulum.now(\"UTC\")\n\n            try:\n                self.logger.debug(f\"About to run {self.name}...\")\n                await self.run_once()\n\n            except NotImplementedError as exc:\n                raise exc from None\n\n            # if an error is raised, log and continue\n            except Exception as exc:\n                self.logger.error(f\"Unexpected error in: {repr(exc)}\", exc_info=True)\n\n            end_time = pendulum.now(\"UTC\")\n\n            # if service took longer than its loop interval, log a warning\n            # that the interval might be too short\n            if (end_time - start_time).total_seconds() &gt; self.loop_seconds:\n                self.logger.warning(\n                    f\"{self.name} took {(end_time-start_time).total_seconds()} seconds\"\n                    \" to run, which is longer than its loop interval of\"\n                    f\" {self.loop_seconds} seconds.\"\n                )\n\n            # check if early stopping was requested\n            i += 1\n            if loops is not None and i == loops:\n                self.logger.debug(f\"{self.name} exiting after {loops} loop(s).\")\n                await self.stop(block=False)\n\n            # next run is every \"loop seconds\" after each previous run *started*.\n            # note that if the loop took unexpectedly long, the \"next_run\" time\n            # might be in the past, which will result in an instant start\n            next_run = max(\n                start_time.add(seconds=self.loop_seconds), pendulum.now(\"UTC\")\n            )\n            self.logger.debug(f\"Finished running {self.name}. Next run at {next_run}\")\n\n            # check the `_should_stop` flag every 1 seconds until the next run time is reached\n            while pendulum.now(\"UTC\") &lt; next_run and not self._should_stop:\n                await asyncio.sleep(\n                    min(1, (next_run - pendulum.now(\"UTC\")).total_seconds())\n                )\n\n        await self._on_stop()\n\n    async def stop(self, block=True) -&gt; None:\n        \"\"\"\n        Gracefully stops a running LoopService and optionally blocks until the\n        service stops.\n\n        Args:\n            block (bool): if True, blocks until the service is\n                finished running. Otherwise it requests a stop and returns but\n                the service may still be running a final loop.\n\n        \"\"\"\n        self._stop()\n\n        if block:\n            # if block=True, sleep until the service stops running,\n            # but no more than `loop_seconds` to avoid a deadlock\n            with anyio.move_on_after(self.loop_seconds):\n                while self._is_running:\n                    await asyncio.sleep(0.1)\n\n            # if the service is still running after `loop_seconds`, something's wrong\n            if self._is_running:\n                self.logger.warning(\n                    f\"`stop(block=True)` was called on {self.name} but more than one\"\n                    f\" loop interval ({self.loop_seconds} seconds) has passed. This\"\n                    \" usually means something is wrong. If `stop()` was called from\"\n                    \" inside the loop service, use `stop(block=False)` instead.\"\n                )\n\n    def _stop(self, *_) -&gt; None:\n        \"\"\"\n        Private, synchronous method for setting the `_should_stop` flag. Takes arbitrary\n        arguments so it can be used as a signal handler.\n        \"\"\"\n        self._should_stop = True\n\n    async def run_once(self) -&gt; None:\n        \"\"\"\n        Represents one loop of the service.\n\n        Users should override this method.\n\n        To actually run the service once, call `LoopService().start(loops=1)`\n        instead of `LoopService().run_once()`, because this method will not invoke setup\n        and teardown methods properly.\n        \"\"\"\n        raise NotImplementedError(\"LoopService subclasses must implement this method.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Represents one loop of the service.</p> <p>Users should override this method.</p> <p>To actually run the service once, call <code>LoopService().start(loops=1)</code> instead of <code>LoopService().run_once()</code>, because this method will not invoke setup and teardown methods properly.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def run_once(self) -&gt; None:\n    \"\"\"\n    Represents one loop of the service.\n\n    Users should override this method.\n\n    To actually run the service once, call `LoopService().start(loops=1)`\n    instead of `LoopService().run_once()`, because this method will not invoke setup\n    and teardown methods properly.\n    \"\"\"\n    raise NotImplementedError(\"LoopService subclasses must implement this method.\")\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.start","title":"<code>start</code>  <code>async</code>","text":"<p>Run the service <code>loops</code> time. Pass loops=None to run forever.</p> <p>Parameters:</p> Name Type Description Default <code>loops</code> <code>int</code> <p>the number of loops to run before exiting.</p> <code>None</code> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def start(self, loops=None) -&gt; None:\n    \"\"\"\n    Run the service `loops` time. Pass loops=None to run forever.\n\n    Args:\n        loops (int, optional): the number of loops to run before exiting.\n    \"\"\"\n\n    await self._on_start()\n\n    i = 0\n    while not self._should_stop:\n        start_time = pendulum.now(\"UTC\")\n\n        try:\n            self.logger.debug(f\"About to run {self.name}...\")\n            await self.run_once()\n\n        except NotImplementedError as exc:\n            raise exc from None\n\n        # if an error is raised, log and continue\n        except Exception as exc:\n            self.logger.error(f\"Unexpected error in: {repr(exc)}\", exc_info=True)\n\n        end_time = pendulum.now(\"UTC\")\n\n        # if service took longer than its loop interval, log a warning\n        # that the interval might be too short\n        if (end_time - start_time).total_seconds() &gt; self.loop_seconds:\n            self.logger.warning(\n                f\"{self.name} took {(end_time-start_time).total_seconds()} seconds\"\n                \" to run, which is longer than its loop interval of\"\n                f\" {self.loop_seconds} seconds.\"\n            )\n\n        # check if early stopping was requested\n        i += 1\n        if loops is not None and i == loops:\n            self.logger.debug(f\"{self.name} exiting after {loops} loop(s).\")\n            await self.stop(block=False)\n\n        # next run is every \"loop seconds\" after each previous run *started*.\n        # note that if the loop took unexpectedly long, the \"next_run\" time\n        # might be in the past, which will result in an instant start\n        next_run = max(\n            start_time.add(seconds=self.loop_seconds), pendulum.now(\"UTC\")\n        )\n        self.logger.debug(f\"Finished running {self.name}. Next run at {next_run}\")\n\n        # check the `_should_stop` flag every 1 seconds until the next run time is reached\n        while pendulum.now(\"UTC\") &lt; next_run and not self._should_stop:\n            await asyncio.sleep(\n                min(1, (next_run - pendulum.now(\"UTC\")).total_seconds())\n            )\n\n    await self._on_stop()\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.LoopService.stop","title":"<code>stop</code>  <code>async</code>","text":"<p>Gracefully stops a running LoopService and optionally blocks until the service stops.</p> <p>Parameters:</p> Name Type Description Default <code>block</code> <code>bool</code> <p>if True, blocks until the service is finished running. Otherwise it requests a stop and returns but the service may still be running a final loop.</p> <code>True</code> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def stop(self, block=True) -&gt; None:\n    \"\"\"\n    Gracefully stops a running LoopService and optionally blocks until the\n    service stops.\n\n    Args:\n        block (bool): if True, blocks until the service is\n            finished running. Otherwise it requests a stop and returns but\n            the service may still be running a final loop.\n\n    \"\"\"\n    self._stop()\n\n    if block:\n        # if block=True, sleep until the service stops running,\n        # but no more than `loop_seconds` to avoid a deadlock\n        with anyio.move_on_after(self.loop_seconds):\n            while self._is_running:\n                await asyncio.sleep(0.1)\n\n        # if the service is still running after `loop_seconds`, something's wrong\n        if self._is_running:\n            self.logger.warning(\n                f\"`stop(block=True)` was called on {self.name} but more than one\"\n                f\" loop interval ({self.loop_seconds} seconds) has passed. This\"\n                \" usually means something is wrong. If `stop()` was called from\"\n                \" inside the loop service, use `stop(block=False)` instead.\"\n            )\n</code></pre>"},{"location":"api-ref/server/services/loop_service/#prefect.server.services.loop_service.run_multiple_services","title":"<code>run_multiple_services</code>  <code>async</code>","text":"<p>Only one signal handler can be active at a time, so this function takes a list of loop services and runs all of them with a global signal handler.</p> Source code in <code>prefect/server/services/loop_service.py</code> <pre><code>async def run_multiple_services(loop_services: List[LoopService]):\n    \"\"\"\n    Only one signal handler can be active at a time, so this function takes a list\n    of loop services and runs all of them with a global signal handler.\n    \"\"\"\n\n    def stop_all_services(self, *_):\n        for service in loop_services:\n            service._stop()\n\n    signal.signal(signal.SIGINT, stop_all_services)\n    signal.signal(signal.SIGTERM, stop_all_services)\n    await asyncio.gather(*[service.start() for service in loop_services])\n</code></pre>"},{"location":"api-ref/server/services/scheduler/","title":"server.services.scheduler","text":""},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler","title":"<code>prefect.server.services.scheduler</code>","text":"<p>The Scheduler service.</p>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.RecentDeploymentsScheduler","title":"<code>RecentDeploymentsScheduler</code>","text":"<p>               Bases: <code>Scheduler</code></p> <p>A scheduler that only schedules deployments that were updated very recently. This scheduler can run on a tight loop and ensure that runs from newly-created or updated deployments are rapidly scheduled without having to wait for the \"main\" scheduler to complete its loop.</p> <p>Note that scheduling is idempotent, so its ok for this scheduler to attempt to schedule the same deployments as the main scheduler. It's purpose is to accelerate scheduling for any deployments that users are interacting with.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class RecentDeploymentsScheduler(Scheduler):\n    \"\"\"\n    A scheduler that only schedules deployments that were updated very recently.\n    This scheduler can run on a tight loop and ensure that runs from\n    newly-created or updated deployments are rapidly scheduled without having to\n    wait for the \"main\" scheduler to complete its loop.\n\n    Note that scheduling is idempotent, so its ok for this scheduler to attempt\n    to schedule the same deployments as the main scheduler. It's purpose is to\n    accelerate scheduling for any deployments that users are interacting with.\n    \"\"\"\n\n    # this scheduler runs on a tight loop\n    loop_seconds = 5\n\n    @inject_db\n    def _get_select_deployments_to_schedule_query(self, db: PrefectDBInterface):\n        \"\"\"\n        Returns a sqlalchemy query for selecting deployments to schedule\n        \"\"\"\n        query = (\n            sa.select(db.Deployment.id)\n            .where(\n                sa.and_(\n                    db.Deployment.paused.is_not(True),\n                    # use a slightly larger window than the loop interval to pick up\n                    # any deployments that were created *while* the scheduler was\n                    # last running (assuming the scheduler takes less than one\n                    # second to run). Scheduling is idempotent so picking up schedules\n                    # multiple times is not a concern.\n                    db.Deployment.updated\n                    &gt;= pendulum.now(\"UTC\").subtract(seconds=self.loop_seconds + 1),\n                    (\n                        # Only include deployments that have at least one\n                        # active schedule.\n                        sa.select(db.DeploymentSchedule.deployment_id)\n                        .where(\n                            sa.and_(\n                                db.DeploymentSchedule.deployment_id == db.Deployment.id,\n                                db.DeploymentSchedule.active.is_(True),\n                            )\n                        )\n                        .exists()\n                    ),\n                )\n            )\n            .order_by(db.Deployment.id)\n            .limit(self.deployment_batch_size)\n        )\n        return query\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.Scheduler","title":"<code>Scheduler</code>","text":"<p>               Bases: <code>LoopService</code></p> <p>A loop service that schedules flow runs from deployments.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class Scheduler(LoopService):\n    \"\"\"\n    A loop service that schedules flow runs from deployments.\n    \"\"\"\n\n    # the main scheduler takes its loop interval from\n    # PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS\n    loop_seconds = None\n\n    def __init__(self, loop_seconds: float = None, **kwargs):\n        super().__init__(\n            loop_seconds=(\n                loop_seconds\n                or self.loop_seconds\n                or PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS.value()\n            ),\n            **kwargs,\n        )\n        self.deployment_batch_size: int = (\n            PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE.value()\n        )\n        self.max_runs: int = PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS.value()\n        self.min_runs: int = PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS.value()\n        self.max_scheduled_time: datetime.timedelta = (\n            PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME.value()\n        )\n        self.min_scheduled_time: datetime.timedelta = (\n            PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME.value()\n        )\n        self.insert_batch_size = (\n            PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE.value()\n        )\n\n    @inject_db\n    async def run_once(self, db: PrefectDBInterface):\n        \"\"\"\n        Schedule flow runs by:\n\n        - Querying for deployments with active schedules\n        - Generating the next set of flow runs based on each deployments schedule\n        - Inserting all scheduled flow runs into the database\n\n        All inserted flow runs are committed to the database at the termination of the\n        loop.\n        \"\"\"\n        total_inserted_runs = 0\n\n        last_id = None\n        while True:\n            async with db.session_context(begin_transaction=False) as session:\n                query = self._get_select_deployments_to_schedule_query()\n\n                # use cursor based pagination\n                if last_id:\n                    query = query.where(db.Deployment.id &gt; last_id)\n\n                result = await session.execute(query)\n                deployment_ids = result.scalars().unique().all()\n\n                # collect runs across all deployments\n                try:\n                    runs_to_insert = await self._collect_flow_runs(\n                        session=session, deployment_ids=deployment_ids\n                    )\n                except TryAgain:\n                    continue\n\n            # bulk insert the runs based on batch size setting\n            for batch in batched_iterable(runs_to_insert, self.insert_batch_size):\n                async with db.session_context(begin_transaction=True) as session:\n                    inserted_runs = await self._insert_scheduled_flow_runs(\n                        session=session, runs=batch\n                    )\n                    total_inserted_runs += len(inserted_runs)\n\n            # if this is the last page of deployments, exit the loop\n            if len(deployment_ids) &lt; self.deployment_batch_size:\n                break\n            else:\n                # record the last deployment ID\n                last_id = deployment_ids[-1]\n\n        self.logger.info(f\"Scheduled {total_inserted_runs} runs.\")\n\n    @inject_db\n    def _get_select_deployments_to_schedule_query(self, db: PrefectDBInterface):\n        \"\"\"\n        Returns a sqlalchemy query for selecting deployments to schedule.\n\n        The query gets the IDs of any deployments with:\n\n            - an active schedule\n            - EITHER:\n                - fewer than `min_runs` auto-scheduled runs\n                - OR the max scheduled time is less than `max_scheduled_time` in the future\n        \"\"\"\n        now = pendulum.now(\"UTC\")\n        query = (\n            sa.select(db.Deployment.id)\n            .select_from(db.Deployment)\n            # TODO: on Postgres, this could be replaced with a lateral join that\n            # sorts by `next_scheduled_start_time desc` and limits by\n            # `self.min_runs` for a ~ 50% speedup. At the time of writing,\n            # performance of this universal query appears to be fast enough that\n            # this optimization is not worth maintaining db-specific queries\n            .join(\n                db.FlowRun,\n                # join on matching deployments, only picking up future scheduled runs\n                sa.and_(\n                    db.Deployment.id == db.FlowRun.deployment_id,\n                    db.FlowRun.state_type == StateType.SCHEDULED,\n                    db.FlowRun.next_scheduled_start_time &gt;= now,\n                    db.FlowRun.auto_scheduled.is_(True),\n                ),\n                isouter=True,\n            )\n            .where(\n                sa.and_(\n                    db.Deployment.paused.is_not(True),\n                    (\n                        # Only include deployments that have at least one\n                        # active schedule.\n                        sa.select(db.DeploymentSchedule.deployment_id)\n                        .where(\n                            sa.and_(\n                                db.DeploymentSchedule.deployment_id == db.Deployment.id,\n                                db.DeploymentSchedule.active.is_(True),\n                            )\n                        )\n                        .exists()\n                    ),\n                )\n            )\n            .group_by(db.Deployment.id)\n            # having EITHER fewer than three runs OR runs not scheduled far enough out\n            .having(\n                sa.or_(\n                    sa.func.count(db.FlowRun.next_scheduled_start_time) &lt; self.min_runs,\n                    sa.func.max(db.FlowRun.next_scheduled_start_time)\n                    &lt; now + self.min_scheduled_time,\n                )\n            )\n            .order_by(db.Deployment.id)\n            .limit(self.deployment_batch_size)\n        )\n        return query\n\n    async def _collect_flow_runs(\n        self,\n        session: sa.orm.Session,\n        deployment_ids: List[UUID],\n    ) -&gt; List[Dict]:\n        runs_to_insert = []\n        for deployment_id in deployment_ids:\n            now = pendulum.now(\"UTC\")\n            # guard against erroneously configured schedules\n            try:\n                runs_to_insert.extend(\n                    await self._generate_scheduled_flow_runs(\n                        session=session,\n                        deployment_id=deployment_id,\n                        start_time=now,\n                        end_time=now + self.max_scheduled_time,\n                        min_time=self.min_scheduled_time,\n                        min_runs=self.min_runs,\n                        max_runs=self.max_runs,\n                    )\n                )\n            except Exception:\n                self.logger.exception(\n                    f\"Error scheduling deployment {deployment_id!r}.\",\n                )\n            finally:\n                connection = await session.connection()\n                if connection.invalidated:\n                    # If the error we handled above was the kind of database error that\n                    # causes underlying transaction to rollback and the connection to\n                    # become invalidated, rollback this session.  Errors that may cause\n                    # this are connection drops, database restarts, and things of the\n                    # sort.\n                    #\n                    # This rollback _does not rollback a transaction_, since that has\n                    # actually already happened due to the error above.  It brings the\n                    # Python session in sync with underlying connection so that when we\n                    # exec the outer with block, the context manager will not attempt to\n                    # commit the session.\n                    #\n                    # Then, raise TryAgain to break out of these nested loops, back to\n                    # the outer loop, where we'll begin a new transaction with\n                    # session.begin() in the next loop iteration.\n                    await session.rollback()\n                    raise TryAgain()\n        return runs_to_insert\n\n    @inject_db\n    async def _generate_scheduled_flow_runs(\n        self,\n        session: sa.orm.Session,\n        deployment_id: UUID,\n        start_time: datetime.datetime,\n        end_time: datetime.datetime,\n        min_time: datetime.timedelta,\n        min_runs: int,\n        max_runs: int,\n        db: PrefectDBInterface,\n    ) -&gt; List[Dict]:\n        \"\"\"\n        Given a `deployment_id` and schedule params, generates a list of flow run\n        objects and associated scheduled states that represent scheduled flow runs.\n\n        Pass-through method for overrides.\n\n\n        Args:\n            session: a database session\n            deployment_id: the id of the deployment to schedule\n            start_time: the time from which to start scheduling runs\n            end_time: runs will be scheduled until at most this time\n            min_time: runs will be scheduled until at least this far in the future\n            min_runs: a minimum amount of runs to schedule\n            max_runs: a maximum amount of runs to schedule\n\n        This function will generate the minimum number of runs that satisfy the min\n        and max times, and the min and max counts. Specifically, the following order\n        will be respected:\n\n            - Runs will be generated starting on or after the `start_time`\n            - No more than `max_runs` runs will be generated\n            - No runs will be generated after `end_time` is reached\n            - At least `min_runs` runs will be generated\n            - Runs will be generated until at least `start_time + min_time` is reached\n\n        \"\"\"\n        return await models.deployments._generate_scheduled_flow_runs(\n            session=session,\n            deployment_id=deployment_id,\n            start_time=start_time,\n            end_time=end_time,\n            min_time=min_time,\n            min_runs=min_runs,\n            max_runs=max_runs,\n        )\n\n    @inject_db\n    async def _insert_scheduled_flow_runs(\n        self,\n        session: sa.orm.Session,\n        runs: List[Dict],\n        db: PrefectDBInterface,\n    ) -&gt; List[UUID]:\n        \"\"\"\n        Given a list of flow runs to schedule, as generated by\n        `_generate_scheduled_flow_runs`, inserts them into the database. Note this is a\n        separate method to facilitate batch operations on many scheduled runs.\n\n        Pass-through method for overrides.\n        \"\"\"\n        return await models.deployments._insert_scheduled_flow_runs(\n            session=session, runs=runs\n        )\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.Scheduler.run_once","title":"<code>run_once</code>  <code>async</code>","text":"<p>Schedule flow runs by:</p> <ul> <li>Querying for deployments with active schedules</li> <li>Generating the next set of flow runs based on each deployments schedule</li> <li>Inserting all scheduled flow runs into the database</li> </ul> <p>All inserted flow runs are committed to the database at the termination of the loop.</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>@inject_db\nasync def run_once(self, db: PrefectDBInterface):\n    \"\"\"\n    Schedule flow runs by:\n\n    - Querying for deployments with active schedules\n    - Generating the next set of flow runs based on each deployments schedule\n    - Inserting all scheduled flow runs into the database\n\n    All inserted flow runs are committed to the database at the termination of the\n    loop.\n    \"\"\"\n    total_inserted_runs = 0\n\n    last_id = None\n    while True:\n        async with db.session_context(begin_transaction=False) as session:\n            query = self._get_select_deployments_to_schedule_query()\n\n            # use cursor based pagination\n            if last_id:\n                query = query.where(db.Deployment.id &gt; last_id)\n\n            result = await session.execute(query)\n            deployment_ids = result.scalars().unique().all()\n\n            # collect runs across all deployments\n            try:\n                runs_to_insert = await self._collect_flow_runs(\n                    session=session, deployment_ids=deployment_ids\n                )\n            except TryAgain:\n                continue\n\n        # bulk insert the runs based on batch size setting\n        for batch in batched_iterable(runs_to_insert, self.insert_batch_size):\n            async with db.session_context(begin_transaction=True) as session:\n                inserted_runs = await self._insert_scheduled_flow_runs(\n                    session=session, runs=batch\n                )\n                total_inserted_runs += len(inserted_runs)\n\n        # if this is the last page of deployments, exit the loop\n        if len(deployment_ids) &lt; self.deployment_batch_size:\n            break\n        else:\n            # record the last deployment ID\n            last_id = deployment_ids[-1]\n\n    self.logger.info(f\"Scheduled {total_inserted_runs} runs.\")\n</code></pre>"},{"location":"api-ref/server/services/scheduler/#prefect.server.services.scheduler.TryAgain","title":"<code>TryAgain</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Internal control-flow exception used to retry the Scheduler's main loop</p> Source code in <code>prefect/server/services/scheduler.py</code> <pre><code>class TryAgain(Exception):\n    \"\"\"Internal control-flow exception used to retry the Scheduler's main loop\"\"\"\n</code></pre>"},{"location":"api-ref/server/utilities/database/","title":"server.utilities.database","text":""},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database","title":"<code>prefect.server.utilities.database</code>","text":"<p>Utilities for interacting with Prefect REST API database and ORM layer.</p> <p>Prefect supports both SQLite and Postgres. Many of these utilities allow the Prefect REST API to seamlessly switch between the two.</p>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.GenerateUUID","title":"<code>GenerateUUID</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent UUID default generator. Note the actual functionality for this class is specified in the <code>compiles</code>-decorated functions below</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class GenerateUUID(FunctionElement):\n    \"\"\"\n    Platform-independent UUID default generator.\n    Note the actual functionality for this class is specified in the\n    `compiles`-decorated functions below\n    \"\"\"\n\n    name = \"uuid_default\"\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.JSON","title":"<code>JSON</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>JSON type that returns SQLAlchemy's dialect-specific JSON types, where possible. Uses generic JSON otherwise.</p> <p>The \"base\" type is postgresql.JSONB to expose useful methods prior to SQL compilation</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class JSON(TypeDecorator):\n    \"\"\"\n    JSON type that returns SQLAlchemy's dialect-specific JSON types, where\n    possible. Uses generic JSON otherwise.\n\n    The \"base\" type is postgresql.JSONB to expose useful methods prior\n    to SQL compilation\n    \"\"\"\n\n    impl = postgresql.JSONB\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.JSONB(none_as_null=True))\n        elif dialect.name == \"sqlite\":\n            return dialect.type_descriptor(sqlite.JSON(none_as_null=True))\n        else:\n            return dialect.type_descriptor(sa.JSON(none_as_null=True))\n\n    def process_bind_param(self, value, dialect):\n        \"\"\"Prepares the given value to be used as a JSON field in a parameter binding\"\"\"\n        if not value:\n            return value\n\n        # PostgreSQL does not support the floating point extrema values `NaN`,\n        # `-Infinity`, or `Infinity`\n        # https://www.postgresql.org/docs/current/datatype-json.html#JSON-TYPE-MAPPING-TABLE\n        #\n        # SQLite supports storing and retrieving full JSON values that include\n        # `NaN`, `-Infinity`, or `Infinity`, but any query that requires SQLite to parse\n        # the value (like `json_extract`) will fail.\n        #\n        # Replace any `NaN`, `-Infinity`, or `Infinity` values with `None` in the\n        # returned value.  See more about `parse_constant` at\n        # https://docs.python.org/3/library/json.html#json.load.\n        return json.loads(json.dumps(value), parse_constant=lambda c: None)\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.Pydantic","title":"<code>Pydantic</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>A pydantic type that converts inserted parameters to json and converts read values to the pydantic type.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class Pydantic(TypeDecorator):\n    \"\"\"\n    A pydantic type that converts inserted parameters to\n    json and converts read values to the pydantic type.\n    \"\"\"\n\n    impl = JSON\n    cache_ok = True\n\n    def __init__(self, pydantic_type, sa_column_type=None):\n        super().__init__()\n        self._pydantic_type = pydantic_type\n        if sa_column_type is not None:\n            self.impl = sa_column_type\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        # parse the value to ensure it complies with the schema\n        # (this will raise validation errors if not)\n        value = pydantic.parse_obj_as(self._pydantic_type, value)\n        # sqlalchemy requires the bind parameter's value to be a python-native\n        # collection of JSON-compatible objects. we achieve that by dumping the\n        # value to a json string using the pydantic JSON encoder and re-parsing\n        # it into a python-native form.\n        return json.loads(json.dumps(value, default=pydantic.json.pydantic_encoder))\n\n    def process_result_value(self, value, dialect):\n        if value is not None:\n            # load the json object into a fully hydrated typed object\n            return pydantic.parse_obj_as(self._pydantic_type, value)\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.Timestamp","title":"<code>Timestamp</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>TypeDecorator that ensures that timestamps have a timezone.</p> <p>For SQLite, all timestamps are converted to UTC (since they are stored as naive timestamps without timezones) and recovered as UTC.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class Timestamp(TypeDecorator):\n    \"\"\"TypeDecorator that ensures that timestamps have a timezone.\n\n    For SQLite, all timestamps are converted to UTC (since they are stored\n    as naive timestamps without timezones) and recovered as UTC.\n    \"\"\"\n\n    impl = sa.TIMESTAMP(timezone=True)\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.TIMESTAMP(timezone=True))\n        elif dialect.name == \"sqlite\":\n            return dialect.type_descriptor(\n                sqlite.DATETIME(\n                    # SQLite is very particular about datetimes, and performs all comparisons\n                    # as alphanumeric comparisons without regard for actual timestamp\n                    # semantics or timezones. Therefore, it's important to have uniform\n                    # and sortable datetime representations. The default is an ISO8601-compatible\n                    # string with NO time zone and a space (\" \") delimiter between the date\n                    # and the time. The below settings can be used to add a \"T\" delimiter but\n                    # will require all other sqlite datetimes to be set similarly, including\n                    # the custom default value for datetime columns and any handwritten SQL\n                    # formed with `strftime()`.\n                    #\n                    # store with \"T\" separator for time\n                    # storage_format=(\n                    #     \"%(year)04d-%(month)02d-%(day)02d\"\n                    #     \"T%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d\"\n                    # ),\n                    # handle ISO 8601 with \"T\" or \" \" as the time separator\n                    # regexp=r\"(\\d+)-(\\d+)-(\\d+)[T ](\\d+):(\\d+):(\\d+).(\\d+)\",\n                )\n            )\n        else:\n            return dialect.type_descriptor(sa.TIMESTAMP(timezone=True))\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        else:\n            if value.tzinfo is None:\n                raise ValueError(\"Timestamps must have a timezone.\")\n            elif dialect.name == \"sqlite\":\n                return pendulum.instance(value).in_timezone(\"UTC\")\n            else:\n                return value\n\n    def process_result_value(self, value, dialect):\n        # retrieve timestamps in their native timezone (or UTC)\n        if value is not None:\n            return pendulum.instance(value).in_timezone(\"utc\")\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.UUID","title":"<code>UUID</code>","text":"<p>               Bases: <code>TypeDecorator</code></p> <p>Platform-independent UUID type.</p> <p>Uses PostgreSQL's UUID type, otherwise uses CHAR(36), storing as stringified hex values with hyphens.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class UUID(TypeDecorator):\n    \"\"\"\n    Platform-independent UUID type.\n\n    Uses PostgreSQL's UUID type, otherwise uses\n    CHAR(36), storing as stringified hex values with\n    hyphens.\n    \"\"\"\n\n    impl = TypeEngine\n    cache_ok = True\n\n    def load_dialect_impl(self, dialect):\n        if dialect.name == \"postgresql\":\n            return dialect.type_descriptor(postgresql.UUID())\n        else:\n            return dialect.type_descriptor(CHAR(36))\n\n    def process_bind_param(self, value, dialect):\n        if value is None:\n            return None\n        elif dialect.name == \"postgresql\":\n            return str(value)\n        elif isinstance(value, uuid.UUID):\n            return str(value)\n        else:\n            return str(uuid.UUID(value))\n\n    def process_result_value(self, value, dialect):\n        if value is None:\n            return value\n        else:\n            if not isinstance(value, uuid.UUID):\n                value = uuid.UUID(value)\n            return value\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.date_add","title":"<code>date_add</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent way to add a date and an interval.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class date_add(FunctionElement):\n    \"\"\"\n    Platform-independent way to add a date and an interval.\n    \"\"\"\n\n    type = Timestamp()\n    name = \"date_add\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, dt, interval):\n        self.dt = dt\n        self.interval = interval\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.date_diff","title":"<code>date_diff</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent difference of dates. Computes d1 - d2.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class date_diff(FunctionElement):\n    \"\"\"\n    Platform-independent difference of dates. Computes d1 - d2.\n    \"\"\"\n\n    type = sa.Interval()\n    name = \"date_diff\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, d1, d2):\n        self.d1 = d1\n        self.d2 = d2\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.interval_add","title":"<code>interval_add</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent way to add two intervals.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class interval_add(FunctionElement):\n    \"\"\"\n    Platform-independent way to add two intervals.\n    \"\"\"\n\n    type = sa.Interval()\n    name = \"interval_add\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, i1, i2):\n        self.i1 = i1\n        self.i2 = i2\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_contains","title":"<code>json_contains</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_contains operator, tests if the <code>left</code> expression contains the <code>right</code> expression.</p> <p>On postgres this is equivalent to the @&gt; containment operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_contains(FunctionElement):\n    \"\"\"\n    Platform independent json_contains operator, tests if the\n    `left` expression contains the `right` expression.\n\n    On postgres this is equivalent to the @&gt; containment operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_contains\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, left, right):\n        self.left = left\n        self.right = right\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_extract","title":"<code>json_extract</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_extract operator, extracts a value from a JSON field via key.</p> <p>On postgres this is equivalent to the -&gt;&gt; operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_extract(FunctionElement):\n    \"\"\"\n    Platform independent json_extract operator, extracts a value from a JSON\n    field via key.\n\n    On postgres this is equivalent to the -&gt;&gt; operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = sa.Text()\n    name = \"json_extract\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, column: sa.Column, path: str, wrap_quotes: bool = False):\n        self.column = column\n        self.path = path\n        self.wrap_quotes = wrap_quotes\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_has_all_keys","title":"<code>json_has_all_keys</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_has_all_keys operator.</p> <p>On postgres this is equivalent to the ?&amp; existence operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_has_all_keys(FunctionElement):\n    \"\"\"Platform independent json_has_all_keys operator.\n\n    On postgres this is equivalent to the ?&amp; existence operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_has_all_keys\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, json_expr, values: List):\n        self.json_expr = json_expr\n        if isinstance(values, list) and not all(isinstance(v, str) for v in values):\n            raise ValueError(\n                \"json_has_all_key values must be strings if provided as a literal list\"\n            )\n        self.values = values\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.json_has_any_key","title":"<code>json_has_any_key</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform independent json_has_any_key operator.</p> <p>On postgres this is equivalent to the ?| existence operator. https://www.postgresql.org/docs/current/functions-json.html</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class json_has_any_key(FunctionElement):\n    \"\"\"\n    Platform independent json_has_any_key operator.\n\n    On postgres this is equivalent to the ?| existence operator.\n    https://www.postgresql.org/docs/current/functions-json.html\n    \"\"\"\n\n    type = BOOLEAN\n    name = \"json_has_any_key\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = False\n\n    def __init__(self, json_expr, values: List):\n        self.json_expr = json_expr\n        if not all(isinstance(v, str) for v in values):\n            raise ValueError(\"json_has_any_key values must be strings\")\n        self.values = values\n        super().__init__()\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.now","title":"<code>now</code>","text":"<p>               Bases: <code>FunctionElement</code></p> <p>Platform-independent \"now\" generator.</p> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>class now(FunctionElement):\n    \"\"\"\n    Platform-independent \"now\" generator.\n    \"\"\"\n\n    type = Timestamp()\n    name = \"now\"\n    # see https://docs.sqlalchemy.org/en/14/core/compiler.html#enabling-caching-support-for-custom-constructs\n    inherit_cache = True\n</code></pre>"},{"location":"api-ref/server/utilities/database/#prefect.server.utilities.database.get_dialect","title":"<code>get_dialect</code>","text":"<p>Get the dialect of a session, engine, or connection url.</p> <p>Primary use case is figuring out whether the Prefect REST API is communicating with SQLite or Postgres.</p> Example <pre><code>import prefect.settings\nfrom prefect.server.utilities.database import get_dialect\n\ndialect = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value())\nif dialect.name == \"sqlite\":\n    print(\"Using SQLite!\")\nelse:\n    print(\"Using Postgres!\")\n</code></pre> Source code in <code>prefect/server/utilities/database.py</code> <pre><code>def get_dialect(\n    obj: Union[str, sa.orm.Session, sa.engine.Engine],\n) -&gt; sa.engine.Dialect:\n    \"\"\"\n    Get the dialect of a session, engine, or connection url.\n\n    Primary use case is figuring out whether the Prefect REST API is communicating with\n    SQLite or Postgres.\n\n    Example:\n        ```python\n        import prefect.settings\n        from prefect.server.utilities.database import get_dialect\n\n        dialect = get_dialect(PREFECT_API_DATABASE_CONNECTION_URL.value())\n        if dialect.name == \"sqlite\":\n            print(\"Using SQLite!\")\n        else:\n            print(\"Using Postgres!\")\n        ```\n    \"\"\"\n    if isinstance(obj, sa.orm.Session):\n        url = obj.bind.url\n    elif isinstance(obj, sa.engine.Engine):\n        url = obj.url\n    else:\n        url = sa.engine.url.make_url(obj)\n\n    return url.get_dialect()\n</code></pre>"},{"location":"api-ref/server/utilities/schemas/","title":"server.utilities.schemas","text":""},{"location":"api-ref/server/utilities/schemas/#prefect.server.utilities.schemas","title":"<code>prefect.server.utilities.schemas</code>","text":""},{"location":"api-ref/server/utilities/server/","title":"server.utilities.server","text":""},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server","title":"<code>prefect.server.utilities.server</code>","text":"<p>Utilities for the Prefect REST API server.</p>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectAPIRoute","title":"<code>PrefectAPIRoute</code>","text":"<p>               Bases: <code>APIRoute</code></p> <p>A FastAPIRoute class which attaches an async stack to requests that exits before a response is returned.</p> <p>Requests already have <code>request.scope['fastapi_astack']</code> which is an async stack for the full scope of the request. This stack is used for managing contexts of FastAPI dependencies. If we want to close a dependency before the request is complete (i.e. before returning a response to the user), we need a stack with a different scope. This extension adds this stack at <code>request.state.response_scoped_stack</code>.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>class PrefectAPIRoute(APIRoute):\n    \"\"\"\n    A FastAPIRoute class which attaches an async stack to requests that exits before\n    a response is returned.\n\n    Requests already have `request.scope['fastapi_astack']` which is an async stack for\n    the full scope of the request. This stack is used for managing contexts of FastAPI\n    dependencies. If we want to close a dependency before the request is complete\n    (i.e. before returning a response to the user), we need a stack with a different\n    scope. This extension adds this stack at `request.state.response_scoped_stack`.\n    \"\"\"\n\n    def get_route_handler(self) -&gt; Callable[[Request], Coroutine[Any, Any, Response]]:\n        default_handler = super().get_route_handler()\n\n        async def handle_response_scoped_depends(request: Request) -&gt; Response:\n            # Create a new stack scoped to exit before the response is returned\n            async with AsyncExitStack() as stack:\n                request.state.response_scoped_stack = stack\n                response = await default_handler(request)\n\n            return response\n\n        return handle_response_scoped_depends\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectRouter","title":"<code>PrefectRouter</code>","text":"<p>               Bases: <code>APIRouter</code></p> <p>A base class for Prefect REST API routers.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>class PrefectRouter(APIRouter):\n    \"\"\"\n    A base class for Prefect REST API routers.\n    \"\"\"\n\n    def __init__(self, **kwargs: Any) -&gt; None:\n        kwargs.setdefault(\"route_class\", PrefectAPIRoute)\n        super().__init__(**kwargs)\n\n    def add_api_route(\n        self, path: str, endpoint: Callable[..., Any], **kwargs: Any\n    ) -&gt; None:\n        \"\"\"\n        Add an API route.\n\n        For routes that return content and have not specified a `response_model`,\n        use return type annotation to infer the response model.\n\n        For routes that return No-Content status codes, explicitly set\n        a `response_class` to ensure nothing is returned in the response body.\n        \"\"\"\n        if kwargs.get(\"status_code\") == status.HTTP_204_NO_CONTENT:\n            # any routes that return No-Content status codes must\n            # explicitly set a response_class that will handle status codes\n            # and not return anything in the body\n            kwargs[\"response_class\"] = Response\n        if kwargs.get(\"response_model\") is None:\n            kwargs[\"response_model\"] = get_type_hints(endpoint).get(\"return\")\n        return super().add_api_route(path, endpoint, **kwargs)\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.PrefectRouter.add_api_route","title":"<code>add_api_route</code>","text":"<p>Add an API route.</p> <p>For routes that return content and have not specified a <code>response_model</code>, use return type annotation to infer the response model.</p> <p>For routes that return No-Content status codes, explicitly set a <code>response_class</code> to ensure nothing is returned in the response body.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def add_api_route(\n    self, path: str, endpoint: Callable[..., Any], **kwargs: Any\n) -&gt; None:\n    \"\"\"\n    Add an API route.\n\n    For routes that return content and have not specified a `response_model`,\n    use return type annotation to infer the response model.\n\n    For routes that return No-Content status codes, explicitly set\n    a `response_class` to ensure nothing is returned in the response body.\n    \"\"\"\n    if kwargs.get(\"status_code\") == status.HTTP_204_NO_CONTENT:\n        # any routes that return No-Content status codes must\n        # explicitly set a response_class that will handle status codes\n        # and not return anything in the body\n        kwargs[\"response_class\"] = Response\n    if kwargs.get(\"response_model\") is None:\n        kwargs[\"response_model\"] = get_type_hints(endpoint).get(\"return\")\n    return super().add_api_route(path, endpoint, **kwargs)\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.method_paths_from_routes","title":"<code>method_paths_from_routes</code>","text":"<p>Generate a set of strings describing the given routes in the format:  <p>For example, \"GET /logs/\"</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def method_paths_from_routes(routes: Sequence[BaseRoute]) -&gt; Set[str]:\n    \"\"\"\n    Generate a set of strings describing the given routes in the format: &lt;method&gt; &lt;path&gt;\n\n    For example, \"GET /logs/\"\n    \"\"\"\n    method_paths = set()\n    for route in routes:\n        if isinstance(route, (APIRoute, StarletteRoute)):\n            for method in route.methods:\n                method_paths.add(f\"{method} {route.path}\")\n\n    return method_paths\n</code></pre>"},{"location":"api-ref/server/utilities/server/#prefect.server.utilities.server.response_scoped_dependency","title":"<code>response_scoped_dependency</code>","text":"<p>Ensure that this dependency closes before the response is returned to the client. By default, FastAPI closes dependencies after sending the response.</p> <p>Uses an async stack that is exited before the response is returned. This is particularly useful for database sessions which must be committed before the client can do more work.</p> Do not use a response-scoped dependency within a FastAPI background task. <p>Background tasks run after FastAPI sends the response, so a response-scoped dependency will already be closed. Use a normal FastAPI dependency instead.</p> <p>Parameters:</p> Name Type Description Default <code>dependency</code> <code>Callable</code> <p>An async callable. FastAPI dependencies may still be used.</p> required <p>Returns:</p> Type Description <p>A wrapped <code>dependency</code> which will push the <code>dependency</code> context manager onto</p> <p>a stack when called.</p> Source code in <code>prefect/server/utilities/server.py</code> <pre><code>def response_scoped_dependency(dependency: Callable):\n    \"\"\"\n    Ensure that this dependency closes before the response is returned to the client. By\n    default, FastAPI closes dependencies after sending the response.\n\n    Uses an async stack that is exited before the response is returned. This is\n    particularly useful for database sessions which must be committed before the client\n    can do more work.\n\n    NOTE: Do not use a response-scoped dependency within a FastAPI background task.\n          Background tasks run after FastAPI sends the response, so a response-scoped\n          dependency will already be closed. Use a normal FastAPI dependency instead.\n\n    Args:\n        dependency: An async callable. FastAPI dependencies may still be used.\n\n    Returns:\n        A wrapped `dependency` which will push the `dependency` context manager onto\n        a stack when called.\n    \"\"\"\n    signature = inspect.signature(dependency)\n\n    async def wrapper(*args, request: Request, **kwargs):\n        # Replicate FastAPI behavior of auto-creating a context manager\n        if inspect.isasyncgenfunction(dependency):\n            context_manager = asynccontextmanager(dependency)\n        else:\n            context_manager = dependency\n\n        # Ensure request is provided if requested\n        if \"request\" in signature.parameters:\n            kwargs[\"request\"] = request\n\n        # Enter the route handler provided stack that is closed before responding,\n        # return the value yielded by the wrapped dependency\n        return await request.state.response_scoped_stack.enter_async_context(\n            context_manager(*args, **kwargs)\n        )\n\n    # Ensure that the signature includes `request: Request` to ensure that FastAPI will\n    # inject the request as a dependency; maintain the old signature so those depends\n    # work\n    request_parameter = inspect.signature(wrapper).parameters[\"request\"]\n    functools.update_wrapper(wrapper, dependency)\n\n    if \"request\" not in signature.parameters:\n        new_parameters = signature.parameters.copy()\n        new_parameters[\"request\"] = request_parameter\n        wrapper.__signature__ = signature.replace(\n            parameters=tuple(new_parameters.values())\n        )\n\n    return wrapper\n</code></pre>"},{"location":"cloud/","title":"Welcome to Prefect Cloud","text":"<p>Prefect Cloud is a hosted workflow application framework that provides all the capabilities of Prefect server plus additional features, such as:</p> <ul> <li>automations, events, and webhooks so you can create event-driven workflows</li> <li>workspaces, RBAC, SSO, audit logs and related user management tools for collaboration</li> <li>push work pools for running flows on serverless infrastructure without a worker</li> <li>error summaries powered by Marvin AI to help you resolve errors faster</li> </ul> <p>Getting Started with Prefect Cloud</p> <p>Ready to jump right in and start running with Prefect Cloud? See the Quickstart and follow the instructions on the Cloud tabs to write and deploy your first Prefect Cloud-monitored flow run.</p> <p></p> <p>Prefect Cloud includes all the features in the open-source Prefect server plus the following:</p> <p>Prefect Cloud features</p> <ul> <li>User accounts \u2014 personal accounts for working in Prefect Cloud.</li> <li>Workspaces \u2014 isolated environments to organize your flows, deployments, and flow runs.</li> <li>Automations \u2014 configure triggers, actions, and notifications in response to real-time monitoring events.</li> <li>Email notifications \u2014 send email alerts from Prefect's server based on automation triggers.</li> <li>Service accounts \u2014 configure API access for running workers or executing flow runs on remote infrastructure.</li> <li>Custom role-based access controls (RBAC) \u2014 assign users granular permissions to perform certain activities within an account or a workspace.</li> <li>Single Sign-on (SSO) \u2014 authentication using your identity provider.</li> <li>Audit Log \u2014 a record of user activities to monitor security and compliance.</li> <li>Collaboration \u2014 invite other people to your account.</li> <li>Error summaries  \u2014 (enabled by Marvin AI) distill the error logs of <code>Failed</code> and <code>Crashed</code> flow runs into actionable information.</li> <li>Push work pools \u2014 run flows on your serverless infrastructure without running a worker.</li> </ul>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#user-accounts","title":"User accounts","text":"<p>When you sign up for Prefect Cloud, an account and a user profile are automatically provisioned for you.</p> <p>Your profile is the place where you'll manage settings related to yourself as a user, including:</p> <ul> <li>Profile, including profile handle and image</li> <li>API keys</li> <li>Preferences, including timezone and color mode</li> </ul> <p>As an account Admin, you will also have access to account settings from the Account Settings page, such as:</p> <ul> <li>Members</li> <li>Workspaces</li> <li>Roles</li> </ul> <p>As an account Admin you can create a workspace and invite other individuals to your workspace.</p> <p>Upgrading from a Prefect Cloud Free tier plan to a Pro or Custom tier plan enables additional functionality for adding workspaces, managing teams, and running higher volume workloads.</p> <p>Workspace Admins for Pro tier plans have the ability to set role-based access controls (RBAC), view Audit Logs, and configure service accounts.</p> <p>Custom plans have object-level access control lists, custom roles, teams, and [single sign-on (SSO)](#single-sign-on-(sso) with Directory Sync/SCIM provisioning.</p> <p>Prefect Cloud plans for teams of every size</p> <p>See the Prefect Cloud plans for details on Pro and Custom account tiers.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#workspaces","title":"Workspaces","text":"<p>A workspace is an isolated environment within Prefect Cloud for your flows, deployments, and block configuration. See the Workspaces documentation for more information about configuring and using workspaces.</p> <p>Each workspace keeps track of its own:</p> <ul> <li>Flow runs and task runs executed in an environment that is syncing with the workspace</li> <li>Flows associated with flow runs and deployments observed by the Prefect Cloud API</li> <li>Deployments</li> <li>Work pools</li> <li>Blocks and storage</li> <li>Events</li> <li>Automations</li> <li>Incidents</li> </ul> <p></p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#events","title":"Events","text":"<p>Prefect Cloud allows you to see your events. Events provide information about the state of your workflows, and can be used as automation triggers.</p> <p></p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#automations","title":"Automations","text":"<p>Prefect Cloud automations provide additional notification capabilities beyond those in a self-hosted open-source Prefect server. Automations also enable you to create event-driven workflows, toggle resources such as schedules and work pools, and declare incidents.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#incidents","title":"Incidents","text":"<p>Prefect Cloud's incidents help teams identify, rectify, and document issues in mission-critical workflows. Incidents are formal declarations of disruptions to a workspace. With automations), activity in that workspace can be paused when an incident is created and resumed when it is resolved.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#error-summaries","title":"Error summaries","text":"<p>Prefect Cloud error summaries, enabled by Marvin AI, distill the error logs of <code>Failed</code> and <code>Crashed</code> flow runs into actionable information. To enable this feature and others powered by Marvin AI, visit the Settings page for your account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#service-accounts","title":"Service accounts","text":"<p>Service accounts enable you to create Prefect Cloud API keys that are not associated with a user account. Service accounts are typically used to configure API access for running workers or executing flow runs on remote infrastructure. See the service accounts documentation for more information about creating and managing service accounts.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#roles-and-custom-permissions","title":"Roles and custom permissions","text":"<p>Role-based access controls (RBAC) enable you to assign users a role with permissions to perform certain activities within an account or a workspace. See the role-based access controls (RBAC) documentation for more information about managing user roles in a Prefect Cloud account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#single-sign-on-sso","title":"Single Sign-on (SSO)","text":"<p>Prefect Cloud's Pro and Custom plans offer single sign-on (SSO) authentication integration with your team\u2019s identity provider. SSO integration can bet set up with identity providers that support OIDC and SAML. Directory Sync and SCIM provisioning is also available with Custom plans.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#audit-log","title":"Audit log","text":"<p>Prefect Cloud's Pro and Custom plans offer Audit Logs for compliance and security. Audit logs provide a chronological record of activities performed by users in an account.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#prefect-cloud-rest-api","title":"Prefect Cloud REST API","text":"<p>The Prefect REST API is used for communicating data from Prefect clients to Prefect Cloud or a local Prefect server for orchestration and monitoring. This API is mainly consumed by Prefect clients like the Prefect Python Client or the Prefect UI.</p> <p>Prefect Cloud REST API interactive documentation</p> <p>Prefect Cloud REST API documentation is available at https://app.prefect.cloud/api/docs.</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/#start-using-prefect-cloud","title":"Start using Prefect Cloud","text":"<p>To create an account or sign in with an existing Prefect Cloud account, go to https://app.prefect.cloud/.</p> <p>Then follow the steps in the UI to deploy your first Prefect Cloud-monitored flow run. For more details, see the Prefect Quickstart and follow the instructions on the Cloud tabs.</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["UI","dashboard","orchestration","Prefect Cloud","accounts","teams","workspaces","PaaS"],"boost":2},{"location":"cloud/connecting/","title":"Connecting &amp; Troubleshooting Prefect Cloud","text":"<p>To create flow runs in a local or remote execution environment and use either Prefect Cloud or a Prefect server as the backend API server, you need to  </p> <ul> <li>Configure the execution environment with the location of the API.</li> <li>Authenticate with the API, either by logging in or providing a valid API key (Prefect Cloud only).</li> </ul>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#log-into-prefect-cloud-from-a-terminal","title":"Log into Prefect Cloud from a terminal","text":"<p>Configure a local execution environment to use Prefect Cloud as the API server for flow runs. In other words, \"log in\" to Prefect Cloud from a local environment where you want to run a flow.</p> <ol> <li>Open a new terminal session.</li> <li>Install Prefect in the environment in which you want to execute flow runs.</li> </ol> <pre><code>$ pip install -U prefect\n</code></pre> <ol> <li>Use the <code>prefect cloud login</code> Prefect CLI command to log into Prefect Cloud from your environment.</li> </ol> <pre><code>$ prefect cloud login\n</code></pre> <p>The <code>prefect cloud login</code> command, used on its own, provides an interactive login experience. Using this command, you can log in with either an API key or through a browser.</p> <pre><code>$ prefect cloud login\n? How would you like to authenticate? [Use arrows to move; enter to select]\n&gt; Log in with a web browser\n    Paste an API key\nPaste your authentication key:\n? Which workspace would you like to use? [Use arrows to move; enter to select]\n&gt; prefect/terry-prefect-workspace\n    g-gadflow/g-workspace\nAuthenticated with Prefect Cloud! Using workspace 'prefect/terry-prefect-workspace'.\n</code></pre> <p>You can also log in by providing a Prefect Cloud API key that you create.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#change-workspaces","title":"Change workspaces","text":"<p>If you need to change which workspace you're syncing with, use the <code>prefect cloud workspace set</code> Prefect CLI command while logged in, passing the account handle and workspace name.</p> <pre><code>$ prefect cloud workspace set --workspace \"prefect/my-workspace\"\n</code></pre> <p>If no workspace is provided, you will be prompted to select one.</p> <p>Workspace Settings also shows you the <code>prefect cloud workspace set</code> Prefect CLI command you can use to sync a local execution environment with a given workspace.</p> <p>You may also use the <code>prefect cloud login</code> command with the <code>--workspace</code> or <code>-w</code> option to set the current workspace.</p> <pre><code>$ prefect cloud login --workspace \"prefect/my-workspace\"\n</code></pre>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#manually-configure-prefect-api-settings","title":"Manually configure Prefect API settings","text":"<p>You can also manually configure the <code>PREFECT_API_URL</code> setting to specify the Prefect Cloud API.</p> <p>For Prefect Cloud, you can configure the <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> settings to authenticate with Prefect Cloud by using an account ID, workspace ID, and API key.</p> <pre><code>$ prefect config set PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n$ prefect config set PREFECT_API_KEY=\"[API-KEY]\"\n</code></pre> <p>When you're in a Prefect Cloud workspace, you can copy the <code>PREFECT_API_URL</code> value directly from the page URL.</p> <p>In this example, we configured <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> in the default profile. You can use <code>prefect profile</code> CLI commands to create settings profiles for different configurations. For example, you could have a \"cloud\" profile configured to use the Prefect Cloud API URL and API key, and another \"local\" profile for local development using a local Prefect API server started with <code>prefect server start</code>. See Settings for details.</p> <p>Environment variables</p> <p>You can also set <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as you would any other environment variable. See Overriding defaults with environment variables for more information.</p> <p>See the Flow orchestration with Prefect tutorial for examples.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#install-requirements-in-execution-environments","title":"Install requirements in execution environments","text":"<p>In local and remote execution environments \u2014 such as VMs and containers \u2014 you must make sure any flow requirements or dependencies have been installed before creating a flow run.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#troubleshooting-prefect-cloud","title":"Troubleshooting Prefect Cloud","text":"<p>This section provides tips that may be helpful if you run into problems using Prefect Cloud.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-and-proxies","title":"Prefect Cloud and proxies","text":"<p>Proxies intermediate network requests between a server and a client.</p> <p>To communicate with Prefect Cloud, the Prefect client library makes HTTPS requests. These requests are made using the <code>httpx</code> Python library. <code>httpx</code> respects accepted proxy environment variables, so the Prefect client is able to communicate through proxies.</p> <p>To enable communication via proxies, simply set the <code>HTTPS_PROXY</code> and <code>SSL_CERT_FILE</code> environment variables as appropriate in your execution environment and things should \u201cjust work.\u201d</p> <p>See the Using Prefect Cloud with proxies topic in Prefect Discourse for examples of proxy configuration.</p> <p>URLs that should be whitelisted for outbound-communication in a secure environment include the UI, the API, Authentication, and the current OCSP server:  </p> <ul> <li>app.prefect.cloud</li> <li>api.prefect.cloud</li> <li>auth.workos.com</li> <li>api.github.com</li> <li>github.com</li> <li>ocsp.pki.goog/s/gts1d4/OxYEb8XcYmo</li> </ul>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-access-via-api","title":"Prefect Cloud access via API","text":"<p>If the Prefect Cloud API key, environment variable settings, or account login for your execution environment are not configured correctly, you may experience errors or unexpected flow run results when using Prefect CLI commands, running flows, or observing flow run results in Prefect Cloud.</p> <p>Use the <code>prefect config view</code> CLI command to make sure your execution environment is correctly configured to access Prefect Cloud.</p> <pre><code>$ prefect config view\nPREFECT_PROFILE='cloud'\nPREFECT_API_KEY='pnu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' (from profile)\nPREFECT_API_URL='https://api.prefect.cloud/api/accounts/...' (from profile)\n</code></pre> <p>Make sure <code>PREFECT_API_URL</code> is configured to use <code>https://api.prefect.cloud/api/...</code>.</p> <p>Make sure <code>PREFECT_API_KEY</code> is configured to use a valid API key.</p> <p>You can use the <code>prefect cloud workspace ls</code> CLI command to view or set the active workspace.</p> <pre><code>$ prefect cloud workspace ls\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503   Available Workspaces: \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502   g-gadflow/g-workspace \u2502\n\u2502    * prefect/workinonit \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n    * active workspace\n</code></pre> <p>You can also check that the account and workspace IDs specified in the URL for <code>PREFECT_API_URL</code> match those shown in the URL bar for your Prefect Cloud workspace.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/connecting/#prefect-cloud-login-errors","title":"Prefect Cloud login errors","text":"<p>If you're having difficulty logging in to Prefect Cloud, the following troubleshooting steps may resolve the issue, or will provide more information when sharing your case to the support channel.</p> <ul> <li>Are you logging into Prefect Cloud 2? Prefect Cloud 1 and Prefect Cloud 2 use separate accounts. Make sure to use the right Prefect Cloud 2 URL: https://app.prefect.cloud/</li> <li>Do you already have a Prefect Cloud account? If you\u2019re having difficulty accepting an invitation, try creating an account first using the email associated with the invitation, then accept the invitation.</li> <li>Are you using a single sign-on (SSO) provider, social authentication (Google, Microsoft, or GitHub) or just using an emailed link?</li> </ul> <p>Other tips to help with login difficulties:</p> <ul> <li>Hard refresh your browser with Cmd+Shift+R.</li> <li>Try in a different browser. We actively test against the following browsers:</li> <li>Chrome</li> <li>Edge</li> <li>Firefox</li> <li>Safari</li> <li>Clear recent browser history/cookies</li> </ul> <p>None of this worked?</p> <p>Email us at help@prefect.io and provide answers to the questions above in your email to make it faster to troubleshoot and unblock you. Make sure you add the email address with which you were trying to log in, your Prefect Cloud account name, and, if applicable, the organization to which it belongs.</p>","tags":["Prefect Cloud","API keys","configuration","workers","troubleshooting","connecting"],"boost":2},{"location":"cloud/events/","title":"Events","text":"<p>An event is a notification of a change. Together, events form a feed of activity recording what's happening across your stack.</p> <p>Events power several features in Prefect Cloud, including flow run logs, audit logs, and automations.</p> <p>Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.</p> <p>Events enable observability into your data stack via the event feed, and the configuration of Prefect's reactivity via automations.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-specification","title":"Event specification","text":"<p>Events adhere to a structured specification.</p> <p></p> Name Type Required? Description occurred String yes When the event happened event String yes The name of the event that happened resource Object yes The primary Resource this event concerns related Array no A list of additional Resources involved in this event payload Object no An open-ended set of data describing what happened id String yes The client-provided identifier of this event follows String no The ID of an event that is known to have occurred prior to this one.","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-grammar","title":"Event grammar","text":"<p>Generally, events have a consistent and informative grammar - an event describes a resource and an action that the resource took or that was taken on that resource. For example, events emitted by Prefect objects take the form of:</p> <pre><code>prefect.block.write-method.called\nprefect-cloud.automation.action.executed\nprefect-cloud.user.logged-in\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#event-sources","title":"Event sources","text":"<p>Events are automatically emitted by all Prefect objects, including flows, tasks, deployments, work queues, and logs. Prefect-emitted events will contain the <code>prefect</code> or <code>prefect-cloud</code> resource prefix. Events can also be sent to the Prefect events API via authenticated http request.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#emit-custom-events-from-python-code","title":"Emit custom events from Python code","text":"<p>The Prefect Python SDK provides an <code>emit_event</code> function that emits an Prefect event when called. The function can be called inside or outside of a task or flow. Running the following code will emit an event to Prefect Cloud, which will validate and ingest the event data.</p> <pre><code>from prefect.events import emit_event\n\ndef some_function(name: str=\"kiki\") -&gt; None:\n    print(f\"hi {name}!\")\n    emit_event(event=f\"{name}.sent.event!\", resource={\"prefect.resource.id\": f\"coder.{name}\"})\n\nsome_function()\n</code></pre> <p>Note that the <code>emit_event</code> arguments shown above are required: <code>event</code> represents the name of the event and <code>resource={\"prefect.resource.id\": \"my_string\"}</code> is the resource id.  To get data into an event for use in an automation action, you can specify a dictionary of values for the <code>payload</code> parameter. </p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#emit-events-via-webhooks","title":"Emit events via webhooks","text":"<p>Prefect Cloud offers programmable webhooks to receive HTTP requests from other systems and translate them into events within your workspace.  Webhooks can emit pre-defined static events, dynamic events that use portions of the incoming HTTP request, or events derived from CloudEvents.</p> <p>Events emitted from any source will appear in the event feed, where you can visualize activity in context and configure automations to react to the presence or absence of it in the future. </p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#resources","title":"Resources","text":"<p>Every event has a primary resource, which describes the object that emitted an event. Resources are used as quasi-stable identifiers for sources of events, and are constructed as dot-delimited strings, for example:</p> <pre><code>prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0\nacme.user.kiki.elt_script_1\nprefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6\n</code></pre> <p>Resources can optionally have additional arbitrary labels which can be used in event aggregation queries, such as:</p> <pre><code>\"resource\": {\n    \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3\",\n    \"prefect-cloud.action.type\": \"call-webhook\"\n    }\n</code></pre> <p>Events can optionally contain related resources, used to associate the event with other resources, such as in the case that the primary resource acted on or with another resource:</p> <pre><code>\"resource\": {\n    \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0\",\n    \"prefect-cloud.action.type\": \"call-webhook\"\n  },\n\"related\": [\n  {\n      \"prefect.resource.id\": \"prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3\",\n      \"prefect.resource.role\": \"automation\",\n      \"prefect-cloud.name\": \"webhook_body_demo\",\n      \"prefect-cloud.posture\": \"Reactive\"\n  }\n]\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#events-in-the-cloud-ui","title":"Events in the Cloud UI","text":"<p>Prefect Cloud provides an interactive dashboard to analyze and take action on events that occurred in your workspace on the event feed page.</p> <p></p> <p>The event feed is the primary place to view, search, and filter events to understand activity across your stack. Each entry displays data on the resource, related resource, and event that took place.</p> <p>You can view more information about an event by clicking into it, where you can view the full details of an event's resource, related resources, and its payload.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/events/#reacting-to-events","title":"Reacting to events","text":"<p>From an event page, you can configure an automation to trigger on the observation of matching events or a lack of matching events by clicking the automate button in the overflow menu:</p> <p></p> <p>The default trigger configuration will fire every time it sees an event with a matching resource identifier. Advanced configuration is possible via custom triggers.</p>","tags":["UI","dashboard","Prefect Cloud","Observability","Events"],"boost":2},{"location":"cloud/incidents/","title":"Incidents","text":"","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#overview","title":"Overview","text":"<p>Incidents are a Prefect Cloud feature to help your team manage workflow disruptions. Incidents help you identify, resolve, and document issues with mission-critical workflows. This system enhances operational efficiency by automating the incident management process and providing a centralized platform for collaboration and compliance.</p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#what-are-incidents","title":"What are incidents?","text":"<p>Incidents are formal declarations of disruptions to a workspace. With automations, activity in a workspace can be paused when an incident is created and resumed when it is resolved.</p> <p>Incidents vary in nature and severity, ranging from minor glitches to critical system failures. Prefect Cloud enables users to effectively and automatically track and manage these incidents, ensuring minimal impact on operational continuity.</p> <p></p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#why-use-incident-management","title":"Why use incident management?","text":"<ol> <li> <p>Automated detection and reporting: Incidents can be automatically identified based on specific triggers or manually reported by team members, facilitating prompt response.</p> </li> <li> <p>Collaborative problem-solving: The platform fosters collaboration, allowing team members to share insights, discuss resolutions, and track contributions.</p> </li> <li> <p>Comprehensive impact assessment: Users gain insights into the incident's influence on workflows, helping in prioritizing response efforts.</p> </li> <li> <p>Compliance with incident management processes: Detailed documentation and reporting features support compliance with incident management systems.</p> </li> <li> <p>Enhanced operational transparency: The system provides a transparent view of both ongoing and resolved incidents, promoting accountability and continuous improvement.</p> </li> </ol> <p></p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#how-to-use-incident-management-in-prefect-cloud","title":"How to use incident management in Prefect Cloud","text":"","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#creating-an-incident","title":"Creating an incident","text":"<p>There are several ways to create an incident:</p> <ol> <li> <p>From the Incidents page:</p> <ul> <li>Click on the + button.</li> <li>Fill in required fields and attach any Prefect resources related to your incident.</li> </ul> </li> <li> <p>From a flow run, work pool, or block:</p> <ul> <li>Initiate an incident directly from a failed flow run, automatically linking it as a resource, by clicking on the menu button and selecting \"Declare an incident\".</li> </ul> </li> <li> <p>Via an automation:</p> <ul> <li>Set up incident creation as an automated response to selected triggers.</li> </ul> </li> </ol>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#incident-automations","title":"Incident automations","text":"<p>Automations can be used for triggering an incident and for selecting actions to take when an incident is triggered. For example, a work pool status change could trigger the declaration of an incident, or a critical level incident could trigger a notification action.</p> <p>To automatically take action when an incident is declared, set up a custom trigger that listens for declaration events.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect-cloud.incident.*\"\n  },\n  \"expect\": [\n    \"prefect-cloud.incident.declared\"\n  ],\n  \"posture\": \"Reactive\",\n  \"threshold\": 1,\n  \"within\": 0\n}\n</code></pre> <p>Building custom triggers</p> <p>To get started with incident automations, you only need to specify two fields in your trigger:</p> <ul> <li> <p>match: The resource emitting your event of interest. You can match on specific resource IDs, use wildcards to match on all resources of a given type, and even match on other resource attributes, like <code>prefect.resource.name</code>.</p> </li> <li> <p>expect: The event type to listen for. For example, you could listen for any (or all) of the following event types:</p> <ul> <li><code>prefect-cloud.incident.declared</code></li> <li><code>prefect-cloud.incident.resolved</code></li> <li><code>prefect-cloud.incident.updated.severity</code></li> </ul> </li> </ul> <p>See Event Triggers for more information on custom triggers, and check out your Event Feed to see the event types emitted by your incidents and other resources (i.e. events that you can react to).</p> <p>When an incident is declared, any actions you configure such as pausing work pools or sending notifications, will execute immediately.</p>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#managing-an-incident","title":"Managing an incident","text":"<ul> <li>Monitor active incidents: View real-time status, severity, and impact.</li> <li>Adjust incident details: Update status, severity, and other relevant information.</li> <li>Collaborate: Add comments and insights; these will display with user identifiers and timestamps.</li> <li>Impact assessment: Evaluate how the incident affects ongoing and future workflows.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#resolving-and-documenting-incidents","title":"Resolving and documenting incidents","text":"<ul> <li>Resolution: Update the incident status to reflect resolution steps taken.</li> <li>Documentation: Ensure all actions, comments, and changes are logged for future reference.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/incidents/#incident-reporting","title":"Incident reporting","text":"<ul> <li>Generate a detailed timeline of the incident: actions taken, updates to severity and resolution - suitable for compliance and retrospective analysis.</li> </ul>","tags":["incidents"],"boost":2},{"location":"cloud/rate-limits/","title":"API Rate Limits &amp; Retention Periods","text":"<p>API rate limits restrict the number of requests that a single client can make in a given time period. They ensure Prefect Cloud's stability, so that when you make an API call, you always get a response.</p> <p>Prefect Cloud rate limits are subject to change</p> <p>The following rate limits are in effect currently, but are subject to change. Contact Prefect support at help@prefect.io if you have questions about current rate limits.</p> <p>Prefect Cloud enforces the following rate limits:</p> <ul> <li>Flow and task creation rate limits</li> <li>Log service rate limits</li> </ul>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#flow-flow-run-and-task-run-rate-limits","title":"Flow, flow run, and task run rate limits","text":"<p>Prefect Cloud limits the <code>flow_runs</code>, <code>task_runs</code>, and <code>flows</code> endpoints and their subroutes at the following levels:</p> <ul> <li>400 per minute for personal accounts</li> <li>2,000 per minute for Pro accounts</li> </ul> <p>The Prefect Cloud API will return a <code>429</code> response with an appropriate <code>Retry-After</code> header if these limits are triggered.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#log-service-rate-limits","title":"Log service rate limits","text":"<p>Prefect Cloud limits the number of logs accepted:</p> <ul> <li>700 logs per minute for personal accounts</li> <li>10,000 logs per minute for Pro accounts</li> </ul> <p>The Prefect Cloud API will return a <code>429</code> response if these limits are triggered.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/rate-limits/#flow-run-retention","title":"Flow run retention","text":"<p>Prefect Cloud feature</p> <p>The Flow Run Retention Policy setting is only applicable in Prefect Cloud.</p> <p>Flow runs in Prefect Cloud are retained according to the Flow Run Retention Policy set by your account tier. The policy setting applies to all workspaces owned by the account.</p> <p>The flow run retention policy represents the number of days each flow run is available in the Prefect Cloud UI, and via the Prefect CLI and API after it ends. Once a flow run reaches a terminal state (detailed in the chart here), it will be retained until the end of the flow run retention period.</p> <p>Flow Run Retention Policy keys on terminal state</p> <p>Note that, because Flow Run Retention Policy keys on terminal state, if two flows start at the same time, but reach a terminal state at different times, they will be removed at different times according to when they each reached their respective terminal states.</p> <p>This retention policy applies to all details about a flow run, including its task runs. Subflow runs follow the retention policy independently from their parent flow runs, and are removed based on the time each subflow run reaches a terminal state.</p> <p>If you or your organization have needs that require a tailored retention period, contact the Prefect Sales team.</p>","tags":["API","Prefect Cloud","rate limits"],"boost":2},{"location":"cloud/workspaces/","title":"Workspaces","text":"<p>A workspace is a discrete environment within Prefect Cloud for your workflows and blocks. Workspaces are available to Prefect Cloud accounts only.</p> <p>Workspaces can be used to organize and compartmentalize your workflows. For example, you can use separate workspaces to isolate dev, staging, and prod environments, or to provide separation between different teams.</p> <p>When you first log into Prefect Cloud, you will be prompted to create your own initial workspace. After creating your workspace, you'll be able to view flow runs, flows, deployments, and other workspace-specific features in the Prefect Cloud UI.</p> <p></p> <p>Select a workspace name in the navigation menu to see all workspaces you can access.</p> <p></p> <p>Your list of available workspaces may include:</p> <ul> <li>Your own account's workspace.</li> <li>Workspaces in an account to which you've been invited and have been given access as an Admin or Member.</li> </ul> <p>Workspace-specific features</p> <p>Each workspace keeps track of its own:</p> <ul> <li>Flow runs and task runs executed in an environment that is syncing with the workspace</li> <li>Flows associated with flow runs or deployments observed by the Prefect Cloud API</li> <li>Deployments</li> <li>Work pools</li> <li>Blocks and Storage</li> <li>Automations</li> </ul> <p>Your user permissions within workspaces may vary. Account admins can assign roles and permissions at the workspace level.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#create-a-workspace","title":"Create a workspace","text":"<p>On the Account Workspaces dropdown or the Workspaces page select the + icon to create a new workspace.</p> <p>You'll be prompted to configure:</p> <ul> <li>The Workspace Owner from the dropdown account menu options.</li> <li>The Workspace Name must be unique within the account.</li> <li>An optional description for the workspace.</li> </ul> <p></p> <p>Select Create to create the new workspace. The number of available workspaces varies by Prefect Cloud plan. See Pricing if you need additional workspaces or users.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-settings","title":"Workspace settings","text":"<p>Within a workspace, select Settings -&gt; General to view or edit workspace details.  </p> <p></p> <p>On this page you can edit workspace details or delete the workspace.</p> <p>Deleting a workspace</p> <p>Deleting a workspace deletes all deployments, flow run history, work pools, and notifications configured in workspace.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-access","title":"Workspace access","text":"<p>Within a Prefect Cloud Pro or Custom tier account, Workspace Owners can invite other people to be members and provision service accounts to a workspace. In addition to giving the user access to the workspace, a Workspace Owner assigns a workspace role to the user. The role specifies the scope of permissions for the user within the workspace.</p> <p>As a Workspace Owner, select Workspaces -&gt; Sharing to manage members and service accounts for the workspace.</p> <p>If you've previously invited individuals to your account or provisioned service accounts, you'll see them listed here.</p> <p></p> <p>To invite someone to an account, select the Members + icon. You can select from a list of existing account members.</p> <p>Select a Role for the user. This will be the initial role for the user within the workspace. A workspace Owner can change this role at any time.</p> <p>Select Send to initiate the invitation.</p> <p>To add a service account to a workspace, select the Service Accounts + icon. You can select from a list of configured service accounts. Select a Workspace Role for the service account. This will be the initial role for the service account within the workspace. A workspace Owner can change this role at any time. Select Share to finalize adding the service account.</p> <p>To remove a workspace member or service account, select Remove from the menu on the right side of the user or service account information on this page.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#workspace-transfer","title":"Workspace transfer","text":"<p>Workspace transfer enables you to move an existing workspace from one account to another.</p> <p>Workspace transfer retains existing workspace configuration and flow run history, including blocks, deployments, notifications, work pools, and logs.</p> <p>Workspace transfer permissions</p> <p>Workspace transfer must be initiated or approved by a user with admin privileges for the workspace to be transferred.</p> <p>To initiate a workspace transfer between personal accounts, contact support@prefect.io.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/workspaces/#transfer-a-workspace","title":"Transfer a workspace","text":"<p>To transfer a workspace, select Settings  -&gt; General within the workspace. Then, from the three dot menu in the upper right of the page, select Transfer.</p> <p></p> <p>The Transfer Workspace page shows the workspace to be transferred on the left. Select the target account for the workspace on the right.</p> <p>Workspace transfer impact on accounts</p> <p>Workspace transfer may impact resource usage and costs for source and target accounts.</p> <p>When you transfer a workspace, users, API keys, and service accounts may lose access to the workspace.  Audit log will no longer track activity on the workspace.  Flow runs ending outside of the destination account\u2019s flow run retention period will be removed.  You may also need to update Prefect CLI profiles and execution environment settings to access the workspace's new location.</p> <p>You may also incur new charges in the target account to accommodate the transferred workspace.</p> <p>The Transfer Workspace page outlines the impacts of transferring the selected workspace to the selected target.  Please review these notes carefully before selecting Transfer to transfer the workspace.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/","title":"User accounts","text":"<p>Sign up for a Prefect Cloud account at app.prefect.cloud.</p> <p>An individual user can be invited to become a member of other accounts.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#user-settings","title":"User settings","text":"<p>Users can access their personal settings in the profile menu, including:</p> <ul> <li>Profile: View and editing basic information, such as name.</li> <li>API keys: Create and view API keys for connecting to Prefect Cloud from the CLI or other environments.</li> <li>Preferences: Manage settings, such as color mode and default time zone.</li> <li>Feature previews: Enable or disable feature previews.</li> </ul>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#account-roles","title":"Account roles","text":"<p>Users who are part of an account can hold the role of Admin or Member. Admins can invite other users to join the account and manage the account's workspaces and teams.</p> <p>Admins on Pro and Custom tier Prefect Cloud accounts can grant members of the account roles in a workspace, such as Runner or Viewer. Custom roles are available on Custom tier accounts.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#api-keys","title":"API keys","text":"<p>API keys enable you to authenticate an environment to work with Prefect Cloud.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#service-accounts","title":"Service accounts","text":"<p>Service accounts enable you to create a Prefect Cloud API key that is not associated with a user account.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#single-sign-on-sso","title":"Single sign-on (SSO)","text":"<p>Custom tier plans offer single sign-on (SSO) integration with your team\u2019s identity provider, including options for directory sync and SCIM provisioning.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#audit-log","title":"Audit log","text":"<p>Audit logs provide a chronological record of activities performed by Prefect Cloud users who are members of an account.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#object-level-access-control-lists-acls","title":"Object-level access control lists (ACLs)","text":"<p>Prefect Cloud's Custom plan offers object-level access control lists to restrict access to specific users and service accounts within a workspace.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/#teams","title":"Teams","text":"<p>Users of Custom tier Prefect Cloud accounts can be added to Teams to simplify access control governance.</p>","tags":["Prefect Cloud","Users"],"boost":2},{"location":"cloud/users/api-keys/","title":"Manage Prefect Cloud API Keys","text":"<p>API keys enable you to authenticate a local environment to work with Prefect Cloud.</p> <p>If you run <code>prefect cloud login</code> from your CLI, you'll have the choice to authenticate through your browser or by pasting an API key.</p> <p>If you choose to authenticate through your browser, you'll be directed to an authorization page. After you grant approval to connect, you'll be redirected to the CLI and the API key will be saved to your local Prefect profile.</p> <p>If you choose to authenticate by pasting an API key, you'll need to create an API key in the Prefect Cloud UI first.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#create-an-api-key","title":"Create an API key","text":"<p>To create an API key, select the account icon at the bottom-left corner of the UI.</p> <p>Select API Keys. The page displays a list of previously generated keys and lets you create new API keys or delete keys.</p> <p></p> <p>Select the + button to create a new API key. Provide a name for the key and an expiration date.</p> <p></p> <p>Warning</p> <p>Note that an API key cannot be revealed again in the UI after it is generated, so copy the key to a secure location.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#log-into-prefect-cloud-with-an-api-key","title":"Log into Prefect Cloud with an API Key","text":"<pre><code>prefect cloud login -k '&lt;my-api-key&gt;'\n</code></pre>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/api-keys/#service-account-api-keys","title":"Service account API keys","text":"<p>Service accounts are a feature of Prefect Cloud Pro and Custom tier plans that enable you to create a Prefect Cloud API key that is not associated with a user account.</p> <p>Service accounts are typically used to configure API access for running workers or executing flow runs on remote infrastructure. Events and logs for flow runs in those environments are then associated with the service account rather than a user, and API access may be managed or revoked by configuring or removing the service account without disrupting user access.</p> <p>See the service accounts documentation for more information about creating and managing service accounts in Prefect Cloud.</p>","tags":["Prefect Cloud","API keys","configuration"],"boost":2},{"location":"cloud/users/audit-log/","title":"Audit Log","text":"<p>Prefect Cloud's Pro and Custom plans offer enhanced compliance and transparency tools with Audit Log. Audit logs provide a chronological record of activities performed by members in your account, allowing you to monitor detailed Prefect Cloud actions for security and compliance purposes.</p> <p>Audit logs enable you to identify who took what action, when, and using what resources within your Prefect Cloud account. In conjunction with appropriate tools and procedures, audit logs can assist in detecting potential security violations and investigating application errors.  </p> <p>Audit logs can be used to identify changes in:</p> <ul> <li>Access to workspaces</li> <li>User login activity</li> <li>User API key creation and removal</li> <li>Workspace creation and removal</li> <li>Account member invitations and removal</li> <li>Service account creation, API key rotation, and removal</li> <li>Billing payment method for self-serve pricing tiers</li> </ul> <p>See the Prefect Cloud plan information to learn more about options for supporting audit logs.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/audit-log/#viewing-audit-logs","title":"Viewing audit logs","text":"<p>From your Pro or Custom account settings page, select the Audit Log page to view audit logs.</p> <p></p> <p>Pro and Custom account tier admins can view audit logs for:</p> <ul> <li>Account-level events in Prefect Cloud, such as:</li> <li>Member invites</li> <li>Changing a member\u2019s role</li> <li>Member login and logout of Prefect Cloud</li> <li>Creating or deleting a service account</li> <li>Workspace-level events in Prefect Cloud, such as:</li> <li>Adding a member to a workspace</li> <li>Changing a member\u2019s workspace role</li> <li>Creating or deleting a workspace</li> </ul> <p>Admins can filter audit logs on multiple dimensions to restrict the results they see by workspace, user, or event type. Available audit log events are displayed in the Events drop-down menu.</p> <p>Audit logs may also be filtered by date range. Audit log retention period varies by Prefect Cloud plan.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/object-access-control-lists/","title":"Object Access Control Lists","text":"<p>Prefect Cloud's Custom plan offers object-level access control lists to restrict access to specific users and service accounts within a workspace. ACLs are supported for blocks and deployments.</p> <p>Organization Admins and Workspace Owners can configure access control lists by navigating to an object and clicking manage access. When an ACL is added, all users and service accounts with access to an object via their workspace role will lose access if not explicitly added to the ACL.</p> <p></p> <p>ACLs and visibility</p> <p>Objects not governed by access control lists such as flow runs, flows, and artifacts will be visible to a user within a workspace even if an associated block or deployment has been restricted for that user.</p> <p>See the Prefect Cloud plans to learn more about options for supporting object-level access control.</p>","tags":["UI","Permissions","Access","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"cloud/users/roles/","title":"User and Service Account Roles","text":"<p>Prefect Cloud's Pro and Custom tiers allow you to set team member access to the appropriate level within specific workspaces.</p> <p>Role-based access controls (RBAC) enable you to assign users granular permissions to perform certain activities.</p> <p>To give users access to functionality beyond the scope of Prefect\u2019s built-in workspace roles, Custom account Admins can create custom roles for users.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#built-in-roles","title":"Built-in roles","text":"<p>Roles give users abilities at either the account level or at the individual workspace level.</p> <ul> <li>An account-level role defines a user's default permissions within an account.</li> <li>A workspace-level role defines a user's permissions within a specific workspace.</li> </ul> <p>The following sections outline the abilities of the built-in, Prefect-defined ac and workspace roles.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#account-level-roles","title":"Account-level roles","text":"<p>The following built-in roles have permissions across an account in Prefect Cloud.</p> Role Abilities Owner \u2022 Set/change all account profile settings allowed to be set/changed by a Prefect user.  \u2022 Add and remove account members, and their account roles.  \u2022 Create and delete service accounts in the account.  \u2022 Create workspaces in the account.  \u2022 Implicit workspace owner access on all workspaces in the account.  \u2022 Bypass SSO. Admin \u2022 Set/change all account profile settings allowed to be set/changed by a Prefect user.  \u2022 Add and remove account members, and their account roles.  \u2022 Create and delete service accounts in the account.  \u2022 Create workspaces in the account.  \u2022 Implicit workspace owner access on all workspaces in the account.  \u2022 Cannot bypass SSO. Member \u2022 View account profile settings.  \u2022 View workspaces I have access to in the account.  \u2022 View account members and their roles.  \u2022 View service accounts in the account.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-level-roles","title":"Workspace-level roles","text":"<p>The following built-in roles have permissions within a given workspace in Prefect Cloud.</p> Role Abilities Viewer \u2022 View flow runs within a workspace.  \u2022 View deployments within a workspace.  \u2022 View all work pools within a workspace.  \u2022 View all blocks within a workspace.  \u2022 View all automations within a workspace.  \u2022 View workspace handle and description. Runner All Viewer abilities, plus:  \u2022 Run deployments within a workspace. Developer All Runner abilities, plus:  \u2022 Run flows within a workspace.  \u2022 Delete flow runs within a workspace.  \u2022 Create, edit, and delete deployments within a workspace.  \u2022 Create, edit, and delete work pools within a workspace.  \u2022 Create, edit, and delete all blocks and their secrets within a workspace.  \u2022 Create, edit, and delete automations within a workspace.  \u2022 View all workspace settings. Owner All Developer abilities, plus:  \u2022 Add and remove account members, and set their role within a workspace.  \u2022 Set the workspace\u2019s default workspace role for all users in the account.  \u2022 Set, view, edit workspace settings. Worker The minimum scopes required for a worker to poll for and submit work.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#custom-workspace-roles","title":"Custom workspace roles","text":"<p>The built-in roles will serve the needs of most users, but your team may need to configure custom roles, giving users access to specific permissions within a workspace.</p> <p>Custom roles can inherit permissions from a built-in role. This enables tweaks to the role to meet your team\u2019s needs, while ensuring users can still benefit from Prefect\u2019s default workspace role permission curation as new functionality becomes available.</p> <p>Custom workspace roles can also be created independent of Prefect\u2019s built-in roles. This option gives workspace admins full control of user access to workspace functionality. However, for non-inherited custom roles, the workspace admin takes on the responsibility for monitoring and setting permissions for new functionality as it is released.</p> <p>See Role permissions for details of permissions you may set for custom roles.</p> <p>After you create a new role, it become available in the account Members page and the Workspace Sharing page for you to apply to users.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#inherited-roles","title":"Inherited roles","text":"<p>A custom role may be configured as an Inherited Role. Using an inherited role allows you to create a custom role using a set of initial permissions associated with a built-in Prefect role. Additional permissions can be added to the custom role. Permissions included in the inherited role cannot be removed.</p> <p>Custom roles created using an inherited role will follow Prefect's default workspace role permission curation as new functionality becomes available.</p> <p>To configure an inherited role when configuring a custom role, select the Inherit permission from a default role check box, then select the role from which the new role should inherit permissions.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-role-permissions","title":"Workspace role permissions","text":"<p>The following permissions are available for custom roles.</p>","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#automations","title":"Automations","text":"Permission Description View automations User can see configured automations within a workspace. Create, edit, and delete automations User can create, edit, and delete automations within a workspace. Includes permissions of View automations.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#blocks","title":"Blocks","text":"Permission Description View blocks User can see configured blocks within a workspace. View secret block data User can see configured blocks and their secrets within a workspace. Includes permissions of\u00a0View blocks. Create, edit, and delete blocks User can create, edit, and delete blocks within a workspace. Includes permissions of View blocks and View secret block data.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#deployments","title":"Deployments","text":"Permission Description View deployments User can see configured deployments within a workspace. Run deployments User can run deployments within a workspace. This does not give a user permission to execute the flow associated with the deployment. This only gives a user (via their key) the ability to run a deployment \u2014 another user/key must actually execute that flow, such as a service account with an appropriate role. Includes permissions of View deployments. Create and edit deployments User can create and edit deployments within a workspace. Includes permissions of View deployments and Run deployments. Delete deployments User can delete deployments within a workspace. Includes permissions of View deployments, Run deployments, and Create and edit deployments.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#flows","title":"Flows","text":"Permission Description View flows and flow runs User can see flows and flow runs within a workspace. Create, update, and delete saved search filters User can create, update, and delete saved flow run search filters configured within a workspace. Includes permissions of View flows and flow runs. Create, update, and run flows User can create, update, and run flows within a workspace. Includes permissions of View flows and flow runs. Delete flows User can delete flows within a workspace. Includes permissions of View flows and flow runs and Create, update, and run flows.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#notifications","title":"Notifications","text":"Permission Description View notification policies User can see notification policies configured within a workspace. Create and edit notification policies User can create and edit notification policies configured within a workspace. Includes permissions of View notification policies. Delete notification policies User can delete notification policies configured within a workspace. Includes permissions of View notification policies and Create and edit notification policies.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#task-run-concurrency","title":"Task run concurrency","text":"Permission Description View concurrency limits User can see configured task run concurrency limits within a workspace. Create, edit, and delete concurrency limits User can create, edit, and delete task run concurrency limits within a workspace. Includes permissions of View concurrency limits.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#work-pools","title":"Work pools","text":"Permission Description View work pools User can see work pools configured within a workspace. Create, edit, and pause work pools User can create, edit, and pause work pools configured within a workspace. Includes permissions of View work pools. Delete work pools User can delete work pools configured within a workspace. Includes permissions of View work pools and Create, edit, and pause work pools.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/roles/#workspace-management","title":"Workspace management","text":"Permission Description View information about workspace service accounts User can see service accounts configured within a workspace. View information about workspace users User can see user accounts for users invited to the workspace. View workspace settings User can see settings configured within a workspace. Edit workspace settings User can edit settings for a workspace. Includes permissions of View workspace settings. Delete the workspace User can delete a workspace. Includes permissions of View workspace settings and Edit workspace settings.","tags":["UI","dashboard","Prefect Cloud","accounts","teams","workspaces","organizations","custom roles","RBAC"],"boost":2},{"location":"cloud/users/service-accounts/","title":"Service Accounts","text":"<p>Service accounts enable you to create a Prefect Cloud API key that is not associated with a user account. Service accounts are typically used to configure API access for running workers or executing deployment flow runs on remote infrastructure.</p> <p>Service accounts are non-user accounts that have the following features:</p> <ul> <li>Prefect Cloud API keys</li> <li>Roles and permissions</li> </ul> <p>Using service account credentials, you can configure an execution environment to interact with your Prefect Cloud workspaces without a user having to manually log in from that environment. Service accounts may be created, added to workspaces, have their roles changed, or deleted without affecting other user accounts.</p> <p>Select Service Accounts to view, create, or edit service accounts.</p> <p></p> <p>Service accounts are created at the account level, but individual workspaces may be shared with the service account. See workspace sharing for more information.</p> <p>Service account credentials</p> <p>When you create a service account, Prefect Cloud creates a new API key for the account and provides the API configuration command for the execution environment. Save these to a safe location for future use. If the access credentials are lost or compromised, you should regenerate the credentials from the service account page.</p> <p>Service account roles</p> <p>Service accounts are created at the account level, and can then be added to workspaces within the account. You may apply any valid workspace-level role to a service account.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/service-accounts/#create-a-service-account","title":"Create a service account","text":"<p>Within your account, on the Service Accounts page, select the + icon to create a new service account. You'll be prompted to configure:</p> <ul> <li>The service account name. This name must be unique within your account.</li> <li>An expiration date, or the Never Expire option.</li> </ul> <p>Service account roles</p> <p>A service account may only be a Member of an account. You may apply any valid workspace-level role to a service account when it is added to a workspace.</p> <p>Select Create to create the new service account.</p> <p>Warning</p> <p>Note that an API key cannot be revealed again in the UI after it is generated, so copy the key to a secure location.</p> <p>You can change the API key and expiration for a service account by rotating the API key. Select Rotate API Key from the menu on the left side of the service account's information on this page. Optionally, you can set a period of time for your old service account key to remain active.</p> <p>To delete a service account, select Remove from the menu on the left side of the service account's information.</p>","tags":["UI","Prefect Cloud","workspaces","deployments"],"boost":2},{"location":"cloud/users/sso/","title":"Single Sign-on (SSO)","text":"<p>Prefect Cloud's Custom plans offer single sign-on (SSO) integration with your team\u2019s identity provider. SSO integration can be set up with any identity provider that supports:</p> <ul> <li>OIDC</li> <li>SAML 2.0</li> </ul> <p>When using SSO, Prefect Cloud won't store passwords for any accounts managed by your identity provider. Members of your Prefect Cloud account will instead log in and authenticate using your identity provider.</p> <p>Once your SSO integration has been set up, non-admins will be required to authenticate through the SSO provider when accessing account resources.</p> <p>See the Prefect Cloud plans to learn more about options for supporting more users and workspaces, service accounts, and SSO.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#configuring-sso","title":"Configuring SSO","text":"<p>Within your account, select the SSO page to enable SSO for users.</p> <p>If you haven't enabled SSO for a domain yet, enter the email domains for which you want to configure SSO in Prefect Cloud and save it.</p> <p>Under Enabled Domains, select the domains from the Domains list, then select Generate Link. This step creates a link you can use to configure SSO with your identity provider.</p> <p></p> <p>Using the provided link navigate to the Identity Provider Configuration dashboard and select your identity provider to continue configuration. If your provider isn't listed, you can continue with the <code>SAML</code> or <code>Open ID Connect</code> choices instead.</p> <p></p> <p>Once you complete SSO configuration your users will be required to authenticate via your identity provider when accessing account resources, giving you full control over application access.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#directory-sync","title":"Directory sync","text":"<p>Directory sync automatically provisions and de-provisions users for your account.</p> <p>Provisioned users are given basic \u201cMember\u201d roles and will have access to any resources that role entails.</p> <p>When a user is unassigned from the Prefect Cloud application in your identity provider, they will automatically lose access to Prefect Cloud resources, allowing your IT team to control access to Prefect Cloud without ever signing into the Prefect UI.</p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/sso/#scim-provisioning","title":"SCIM Provisioning","text":"<p>Custom accounts have access to SCIM for user provisioning. The SSO tab provides access to enable SCIM provisioning.</p> <p></p>","tags":["UI","dashboard","Prefect Cloud","enterprise","teams","workspaces","organizations","single sign-on","SSO","authentication"],"boost":2},{"location":"cloud/users/teams/","title":"Teams","text":"<p>Prefect Cloud's Custom plan offers team management to simplify access control governance.</p> <p>Account Admins can configure teams and team membership from the account settings menu by clicking Teams. Teams are composed of users and service accounts. Teams can be added to workspaces or object access control lists just like users and service accounts.</p> <p></p> <p>If SCIM is enabled on your account, the set of teams and the users within them is governed by your IDP. Prefect Cloud service accounts, which are not governed by your IDP, can be still be added to your existing set of teams.</p> <p>See the Prefect Cloud plans to learn more about options for supporting teams.</p>","tags":["UI","Permissions","Access","Prefect Cloud","enterprise","teams","workspaces","organizations","audit logs","compliance"],"boost":2},{"location":"community/","title":"Community","text":"<p>There are many ways to get involved with the Prefect community</p> <ul> <li>Join over 26,000 engineers in the Prefect Slack community</li> <li>Get help in Prefect Discourse - the community-driven knowledge base</li> <li>Give Prefect a \u2b50\ufe0f on GitHub</li> <li>Contribute to Prefect's open source libraries</li> <li>Become a Prefect Ambassador by joining Club 42</li> </ul>","tags":["community","Slack","Discourse"],"boost":2},{"location":"concepts/","title":"Explore Prefect concepts","text":"Concept Description Flows A Prefect workflow, defined as a Python function. Tasks Discrete units of work in a Prefect workflow. Deployments A server-side concept that encapsulates flow metadata, allowing it to be scheduled and triggered via API. Work Pools &amp; Workers Use Prefect to dynamically provision and configure infrastructure in your execution environment. Schedules Tell the Prefect API how to create new flow runs for you automatically on a specified cadence. Results The data returned by a flow or a task. Artifacts Formatted outputs rendered in the Prefect UI, such as markdown, tables, or links. States Rich objects that capture the status of a particular task run or flow run. Blocks Prefect primitives that enable the storage of configuration and provide a UI interface. Task Runners Configure how tasks are run - concurrently, in parallel, or in a distributed environment. Automations Configure actions that Prefect executes automatically based on trigger conditions. Block and Agent-Based Deployments Description Block-based Deployments Create deployments that rely on blocks. Infrastructure Blocks that specify infrastructure for flow runs created by a deployment. Storage Lets you configure how flow code for deployments is persisted and retrieved. Agents Like untyped workers. <p>Many features specific to Prefect Cloud are in their own navigation subheading.</p>","tags":["concepts","features","overview"],"boost":2},{"location":"concepts/agents/","title":"Agents","text":"<p>Workers are recommended</p> <p>Agents are part of the block-based deployment model. Work Pools and Workers simplify the specification of a flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-overview","title":"Agent overview","text":"<p>Agent processes are lightweight polling services that get scheduled work from a work pool and deploy the corresponding flow runs.</p> <p>Agents poll for work every 15 seconds by default. This interval is configurable in your profile settings with the <code>PREFECT_AGENT_QUERY_INTERVAL</code> setting.</p> <p>It is possible for multiple agent processes to be started for a single work pool. Each agent process sends a unique ID to the server to help disambiguate themselves and let users know how many agents are active.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-options","title":"Agent options","text":"<p>Agents are configured to pull work from one or more work pool queues. If the agent references a work queue that doesn't exist, it will be created automatically.</p> <p>Configuration parameters you can specify when starting an agent include:</p> Option Description <code>--api</code> The API URL for the Prefect server. Default is the value of <code>PREFECT_API_URL</code>. <code>--hide-welcome</code> Do not display the startup ASCII art for the agent process. <code>--limit</code> Maximum number of flow runs to start simultaneously. [default: None] <code>--match</code>, <code>-m</code> Dynamically matches work queue names with the specified prefix for the agent to pull from,for example <code>dev-</code> will match all work queues with a name that starts with <code>dev-</code>. [default: None] <code>--pool</code>, <code>-p</code> A work pool name for the agent to pull from. [default: None] <code>--prefetch-seconds</code> The amount of time before a flow run's scheduled start time to begin submission. Default is the value of <code>PREFECT_AGENT_PREFETCH_SECONDS</code>. <code>--run-once</code> Only run agent polling once. By default, the agent runs forever. [default: no-run-once] <code>--work-queue</code>, <code>-q</code> One or more work queue names for the agent to pull from. [default: None] <p>You must start an agent within an environment that can access or create the infrastructure needed to execute flow runs. Your agent will deploy flow runs to the infrastructure specified by the deployment.</p> <p>Prefect must be installed in execution environments</p> <p>Prefect must be installed in any environment in which you intend to run the agent or execute a flow run.</p> <p><code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> settings for agents</p> <p><code>PREFECT_API_URL</code> must be set for the environment in which your agent is running or specified when starting the agent with the <code>--api</code> flag. You must also have a user or service account with the <code>Worker</code> role, which can be configured by setting the <code>PREFECT_API_KEY</code>.</p> <p>If you want an agent to communicate with Prefect Cloud or a Prefect server from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#starting-an-agent","title":"Starting an agent","text":"<p>Use the <code>prefect agent start</code> CLI command to start an agent. You must pass at least one work pool name or match string that the agent will poll for work. If the work pool does not exist, it will be created.</p> <pre><code>prefect agent start -p [work pool name]\n</code></pre> <p>For example:</p> <pre><code>Starting agent with ephemeral API...\n\u00a0 ___ ___ ___ ___ ___ ___ _____ \u00a0 \u00a0 _ \u00a0 ___ ___ _\u00a0 _ _____\n\u00a0| _ \\ _ \\ __| __| __/ __|_ \u00a0 _| \u00a0 /_\\ / __| __| \\| |_ \u00a0 _|\n\u00a0|\u00a0 _/ \u00a0 / _|| _|| _| (__\u00a0 | |\u00a0 \u00a0 / _ \\ (_ | _|| .` | | |\n\u00a0|_| |_|_\\___|_| |___\\___| |_| \u00a0 /_/ \\_\\___|___|_|\\_| |_|\n\nAgent started! Looking for work from work pool 'my-pool'...\n</code></pre> <p>By default, the agent polls the API specified by the <code>PREFECT_API_URL</code> environment variable. To configure the agent to poll from a different server location, use the <code>--api</code> flag, specifying the URL of the server.</p> <p>In addition, agents can match multiple queues in a work pool by providing a <code>--match</code> string instead of specifying all of the queues. The agent will poll every queue with a name that starts with the given string. New queues matching this prefix will be found by the agent without needing to restart it.</p> <p>For example:</p> <pre><code>prefect agent start --match \"foo-\"\n</code></pre> <p>This example will poll every work queue that starts with \"foo-\".</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#configuring-prefetch","title":"Configuring prefetch","text":"<p>By default, the agent begins submission of flow runs a short time (10 seconds) before they are scheduled to run. This allows time for the infrastructure to be created, so the flow run can start on time. In some cases, infrastructure will take longer than this to actually start the flow run. In these cases, the prefetch can be increased using the <code>--prefetch-seconds</code> option or the <code>PREFECT_AGENT_PREFETCH_SECONDS</code> setting.</p> <p>Submission can begin an arbitrary amount of time before the flow run is scheduled to start. If this value is larger than the amount of time it takes for the infrastructure to start, the flow run will wait until its scheduled start time. This allows flow runs to start exactly on time.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#troubleshooting","title":"Troubleshooting","text":"","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/agents/#agent-crash-or-keyboard-interrupt","title":"Agent crash or keyboard interrupt","text":"<p>If the agent process is ended abruptly, you can sometimes have left over flows that were destined for the agent whose process was ended. In the UI, these will show up as pending. You will need to delete these flows in order for the restarted agent to begin processing the work queue again. Take note of the flows you deleted, you might need to set them to run manually.</p>","tags":["agents","deployments"],"boost":0.5},{"location":"concepts/artifacts/","title":"Artifacts","text":"<p>Artifacts are persisted outputs such as tables, Markdown, or links. They are stored on Prefect Cloud or a Prefect server instance and rendered in the Prefect UI. Artifacts make it easy to track and monitor the objects that your flows produce and update over time.</p> <p></p> <p>Published artifacts may be associated with a particular task run or flow run. Artifacts can also be created outside of any flow run context.</p> <p>Whether you're publishing links, Markdown, or tables, artifacts provide a powerful and flexible way to showcase data within your workflows.</p> <p>With artifacts, you can easily manage and share information with your team, providing valuable insights and context.</p> <p>Common use cases for artifacts include:</p> <ul> <li>Debugging: By publishing data that you care about in the UI, you can easily see when and where your results were written. If an artifact doesn't look the way you expect, you can find out which flow run last updated it, and you can click through a link in the artifact to a storage location (such as an S3 bucket).</li> <li>Data quality checks: Artifacts can be used to publish data quality checks from in-progress tasks. This can help ensure that data quality is maintained throughout the pipeline. During long-running tasks such as ML model training, you might use artifacts to publish performance graphs. This can help you visualize how well your models are performing and make adjustments as needed. You can also track the versions of these artifacts over time, making it easier to identify changes in your data.</li> <li>Documentation: Artifacts can be used to publish documentation and sample data to help you keep track of your work and share information with your colleagues. For instance, artifacts allow you to add a description to let your colleagues know why this piece of data is important.</li> </ul>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-artifacts","title":"Creating artifacts","text":"<p>Creating artifacts allows you to publish data from task and flow runs or outside of a flow run context. Currently, you can render three artifact types: links, Markdown, and tables.</p> <p>Artifacts render individually</p> <p>Please note that every artifact created within a task will be displayed as an individual artifact in the Prefect UI. This means that each call to <code>create_link_artifact()</code> or <code>create_markdown_artifact()</code> generates a distinct artifact.</p> <p>Unlike the <code>print()</code> command, where you can concatenate multiple calls to include additional items in a report, within a task, these commands must be used multiple times if necessary. </p> <p>To create artifacts like reports or summaries using <code>create_markdown_artifact()</code>, compile your message string separately and then pass it to <code>create_markdown_artifact()</code> to create the complete artifact.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-link-artifacts","title":"Creating link artifacts","text":"<p>To create a link artifact, use the <code>create_link_artifact()</code> function. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_link_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the Artifacts tab of the associated flow run or task run.</p> <pre><code>from prefect import flow, task\nfrom prefect.artifacts import create_link_artifact\n\n@task\ndef my_first_task():\n        create_link_artifact(\n            key=\"irregular-data\",\n            link=\"https://nyc3.digitaloceanspaces.com/my-bucket-name/highly_variable_data.csv\",\n            description=\"## Highly variable data\",\n        )\n\n@task\ndef my_second_task():\n        create_link_artifact(\n            key=\"irregular-data\",\n            link=\"https://nyc3.digitaloceanspaces.com/my-bucket-name/low_pred_data.csv\",\n            description=\"# Low prediction accuracy\",\n        )\n\n@flow\ndef my_flow():\n    my_first_task()\n    my_second_task()\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Tip</p> <p>You can specify multiple artifacts with the same key to more easily track something very specific that you care about, such as irregularities in your data pipeline.</p> <p>After running the above flows, you can find your new artifacts in the Artifacts page of the UI. Click into the \"irregular-data\" artifact and see all versions of it, along with custom descriptions and links to the relevant data.</p> <p></p> <p>Here, you'll also be able to view information about your artifact such as its associated flow run or task run id, previous and future versions of the artifact (multiple artifacts can have the same key in order to show lineage), the data you've stored (in this case a Markdown-rendered link), an optional Markdown description, and when the artifact was created or updated.</p> <p>To make the links more readable for you and your collaborators, you can pass in a <code>link_text</code> argument for your link artifacts:</p> <pre><code>from prefect import flow\nfrom prefect.artifacts import create_link_artifact\n\n@flow\ndef my_flow():\n    create_link_artifact(\n        key=\"my-important-link\",\n        link=\"https://www.prefect.io/\",\n        link_text=\"Prefect\",\n    )\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>In the above example, the <code>create_link_artifact</code> method is used within a flow to create a link artifact with a key of <code>my-important-link</code>. The <code>link</code> parameter is used to specify the external resource to be linked to, and <code>link_text</code> is used to specify the text to be displayed for the link. An optional <code>description</code> could also be added for context.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#creating-markdown-artifacts","title":"Creating Markdown artifacts","text":"<p>To create a Markdown artifact, you can use the <code>create_markdown_artifact()</code> function. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_markdown_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the Artifacts tab of the associated flow run or task run.</p> <p>Don't indent Markdown</p> <p>Markdown in mult-line strings must be unindented to be interpreted correctly.</p> <pre><code>from prefect import flow, task\nfrom prefect.artifacts import create_markdown_artifact\n\n@task\ndef markdown_task():\n    na_revenue = 500000\n    markdown_report = f\"\"\"# Sales Report\n\n## Summary\n\nIn the past quarter, our company saw a significant increase in sales, with a total revenue of $1,000,000. \nThis represents a 20% increase over the same period last year.\n\n## Sales by Region\n\n| Region        | Revenue |\n|:--------------|-------:|\n| North America | ${na_revenue:,} |\n| Europe        | $250,000 |\n| Asia          | $150,000 |\n| South America | $75,000 |\n| Africa        | $25,000 |\n\n## Top Products\n\n1. Product A - $300,000 in revenue\n2. Product B - $200,000 in revenue\n3. Product C - $150,000 in revenue\n\n## Conclusion\n\nOverall, these results are very encouraging and demonstrate the success of our sales team in increasing revenue \nacross all regions. However, we still have room for improvement and should focus on further increasing sales in \nthe coming quarter.\n\"\"\"\n    create_markdown_artifact(\n        key=\"gtm-report\",\n        markdown=markdown_report,\n        description=\"Quarterly Sales Report\",\n    )\n\n@flow()\ndef my_flow():\n    markdown_task()\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>After running the above flow, you should see your \"gtm-report\" artifact in the Artifacts page of the UI.</p> <p></p> <p>As with all artifacts, you'll be able to view the associated flow run or task run id, previous and future versions of the artifact, your rendered Markdown data, and your optional Markdown description.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#create-table-artifacts","title":"Create table artifacts","text":"<p>You can create a table artifact by calling <code>create_table_artifact()</code>. To create multiple versions of the same artifact and/or view them on the Artifacts page of the Prefect UI, provide a <code>key</code> argument to the <code>create_table_artifact()</code> function to track an artifact's history over time. Without a <code>key</code>, the artifact will only be visible in the artifacts tab of the associated flow run or task run.</p> <p>Note</p> <p>The <code>create_table_artifact()</code> function accepts a <code>table</code> argument, which can be provided as either a list of lists, a list of dictionaries, or a dictionary of lists.</p> <pre><code>from prefect.artifacts import create_table_artifact\n\ndef my_fn():\n    highest_churn_possibility = [\n       {'customer_id':'12345', 'name': 'John Smith', 'churn_probability': 0.85 }, \n       {'customer_id':'56789', 'name': 'Jane Jones', 'churn_probability': 0.65 } \n    ]\n\n    create_table_artifact(\n        key=\"personalized-reachout\",\n        table=highest_churn_possibility,\n        description= \"# Marvin, please reach out to these customers today!\"\n    )\n\nif __name__ == \"__main__\":\n    my_fn()\n</code></pre> <p> As you can see, you don't need to create an artifact in a flow run context. You can create one anywhere in a Python script and see it in the Prefect UI.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#managing-artifacts","title":"Managing artifacts","text":"","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#reading-artifacts","title":"Reading artifacts","text":"<p>In the Prefect UI, you can view all of the latest versions of your artifacts and click into a specific artifact to see its lineage over time. Additionally, you can inspect all versions of an artifact with a given key from the CLI by running:</p> <pre><code>prefect artifact inspect &lt;my_key&gt;\n</code></pre> <p>or view all artifacts by running:</p> <pre><code>prefect artifact ls\n</code></pre> <p>You can also use the Prefect REST API to programmatically filter your results.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#fetching-artifacts","title":"Fetching artifacts","text":"<p>In Python code, you can retrieve an existing artifact with the <code>Artifact.get</code> class method:</p> <pre><code>from prefect.artifacts import Artifact\n\nmy_retrieved_artifact = Artifact.get(\"my_artifact_key\")\n</code></pre>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#deleting-artifacts","title":"Deleting artifacts","text":"<p>You can delete an artifact directly using the CLI to delete specific artifacts with a given key or id:</p> <pre><code>prefect artifact delete &lt;my_key&gt;\n</code></pre> <pre><code>prefect artifact delete --id &lt;my_id&gt;\n</code></pre> <p>Alternatively, you can delete artifacts using the Prefect REST API.</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/artifacts/#artifacts-api","title":"Artifacts API","text":"<p>Prefect provides the Prefect REST API to allow you to create, read, and delete artifacts programmatically. With the Artifacts API, you can automate the creation and management of artifacts as part of your workflow.</p> <p>For example, to read the five most recently created Markdown, table, and link artifacts, you can run the following:</p> <pre><code>import requests\n\nPREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/abc/workspaces/xyz\"\nPREFECT_API_KEY=\"pnu_ghijk\"\ndata = {\n    \"sort\": \"CREATED_DESC\",\n    \"limit\": 5,\n    \"artifacts\": {\n        \"key\": {\n            \"exists_\": True\n        }\n    }\n}\n\nheaders = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\nendpoint = f\"{PREFECT_API_URL}/artifacts/filter\"\n\nresponse = requests.post(endpoint, headers=headers, json=data)\nassert response.status_code == 200\nfor artifact in response.json():\n    print(artifact)\n</code></pre> <p>If you don't specify a key or that a key must exist, you will also return results (which are a type of key-less artifact).</p> <p>See the rest of the Prefect REST API documentation on artifacts for more information!</p>","tags":["artifacts","UI","Markdown"],"boost":2},{"location":"concepts/automations/","title":"Automations","text":"<p>Automations in Prefect Cloud enable you to configure actions that Prefect executes automatically based on trigger conditions.</p> <p>Potential triggers include the occurrence of events from changes in a flow run's state - or the absence of such events. You can even define your own custom trigger to fire based on an event created from a webhook or a custom event defined in Python code.</p> <p>Potential actions include kicking off flow runs, pausing schedules, and sending custom notifications.</p> <p>Automations are only available in Prefect Cloud</p> <p>Notifications in an open-source Prefect server provide a subset of the notification message-sending features available in Automations.</p> <p>Automations provide a flexible and powerful framework for automatically taking action in response to events.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#automations-overview","title":"Automations overview","text":"<p>The Automations page provides an overview of all configured automations for your workspace.</p> <p></p> <p>Selecting the toggle next to an automation pauses execution of the automation.</p> <p>The button next to the toggle provides commands to copy the automation ID, edit the automation, or delete the automation.</p> <p>Select the name of an automation to view Details about it and relevant Events.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#create-an-automation","title":"Create an automation","text":"<p>On the Automations page, select the + icon to create a new automation. You'll be prompted to configure:</p> <ul> <li>A trigger condition that causes the automation to execute.</li> <li>One or more actions carried out by the automation.</li> <li>Details about the automation, such as a name and description.</li> </ul>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#triggers","title":"Triggers","text":"<p>Triggers specify the conditions under which your action should be performed. The Prefect UI includes templates for many common conditions, such as:</p> <ul> <li>Flow run state change</li> <li>Note - Flow Run Tags currently are only evaluated with <code>OR</code> criteria</li> <li>Work pool status</li> <li>Work queue status</li> <li>Deployment status</li> <li>Metric thresholds, such as average duration, lateness, or completion percentage</li> <li>Incident declarations (available on Pro and Custom plans)</li> <li>Custom event triggers</li> </ul> <p>Automations API</p> <p>The automations API enables further programmatic customization of trigger and action policies based on arbitrary events.</p> <p>Importantly, triggers can be configured not only in reaction to events, but also proactively: to fire in the absence of an expected event.</p> <p></p> <p>For example, in the case of flow run state change triggers, you might expect production flows to finish in no longer than thirty minutes. But transient infrastructure or network issues could cause your flow to get \u201cstuck\u201d in a running state. A trigger could kick off an action if the flow stays in a running state for more than 30 minutes. This action could be taken on the flow itself, such as canceling or restarting it. Or the action could take the form of a notification so someone can take manual remediation steps. Or you could set both actions to to take place when the trigger occurs.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#actions","title":"Actions","text":"<p>Actions specify what your automation does when its trigger criteria are met. Current action types include:</p> <ul> <li>Cancel a flow run</li> <li>Pause or resume a schedule</li> <li>Run a deployment</li> <li>Pause or resume a deployment schedule</li> <li>Pause or resume a work pool</li> <li>Pause or resume a work queue</li> <li>Pause or resume an automation</li> <li>Send a notification</li> <li>Call a webhook</li> <li>Suspend a flow run</li> <li>Declare an incident (available on Pro and Custom plans)</li> <li>Change the state of a flow run</li> </ul> <p></p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#creating-automations-in-python-code","title":"Creating automations In Python code","text":"<p>You can create and access any automation with the Python SDK's <code>Automation</code> class and its methods.</p> <pre><code>from prefect.automations import Automation\nfrom prefect.events.schemas.automations import EventTrigger\nfrom prefect.server.events.actions import CancelFlowRun\n\n# creating an automation\nautomation = Automation(\n    name=\"woodchonk\",\n    trigger=EventTrigger(\n        expect={\"animal.walked\"},\n        match={\n            \"genus\": \"Marmota\",\n            \"species\": \"monax\",\n        },\n        posture=\"Reactive\",\n        threshold=3,\n    ),\n    actions=[CancelFlowRun()]\n).create()\nprint(automation)\n# name='woodchonk' description='' enabled=True trigger=EventTrigger(type='event', match=ResourceSpecification(__root__={'genus': 'Marmota', 'species': 'monax'}), match_related=ResourceSpecification(__root__={}), after=set(), expect={'animal.walked'}, for_each=set(), posture=Posture.Reactive, threshold=3, within=datetime.timedelta(seconds=10)) actions=[CancelFlowRun(type='cancel-flow-run')] actions_on_trigger=[] actions_on_resolve=[] owner_resource=None id=UUID('d641c552-775c-4dc6-a31e-541cb11137a6')\n\n# reading the automation\n\nautomation = Automation.read(id =\"d641c552-775c-4dc6-a31e-541cb11137a6\")\n# or\nautomation = Automation.read(\"woodchonk\")\n\nprint(automation)\n# name='woodchonk' description='' enabled=True trigger=EventTrigger(type='event', match=ResourceSpecification(__root__={'genus': 'Marmota', 'species': 'monax'}), match_related=ResourceSpecification(__root__={}), after=set(), expect={'animal.walked'}, for_each=set(), posture=Posture.Reactive, threshold=3, within=datetime.timedelta(seconds=10)) actions=[CancelFlowRun(type='cancel-flow-run')] actions_on_trigger=[] actions_on_resolve=[] owner_resource=None id=UUID('d641c552-775c-4dc6-a31e-541cb11137a6')\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#selected-and-inferred-action-targets","title":"Selected and inferred action targets","text":"<p>Some actions require you to either select the target of the action, or specify that the target of the action should be inferred.</p> <p>Selected targets are simple, and useful for when you know exactly what object your action should act on \u2014 for example, the case of a cleanup flow you want to run or a specific notification you\u2019d like to send.</p> <p>Inferred targets are deduced from the trigger itself.</p> <p>For example, if a trigger fires on a flow run that is stuck in a running state, and the action is to cancel an inferred flow run, the flow run to cancel is inferred as the stuck run that caused the trigger to fire.</p> <p>Similarly, if a trigger fires on a work queue event and the corresponding action is to pause an inferred work queue, the inferred work queue is the one that emitted the event.</p> <p>Prefect tries to infer the relevant event whenever possible, but sometimes one does not exist.</p> <p>Specify a name and, optionally, a description for the automation.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#custom-triggers","title":"Custom triggers","text":"<p>When you need a trigger that doesn't quite fit the templates in UI trigger builder, you can define a custom trigger in JSON.  With custom triggers, you have access to the full capabilities of Prefect's automation system - allowing you to react to many kinds of events and metrics in your workspace.</p> <p>Each automation has a single trigger that, when fired, will cause all of its associated actions to run.  That single trigger may be a reactive or proactive event trigger, a trigger monitoring the value of a metric, or a composite trigger that combines several underlying triggers.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#event-triggers","title":"Event triggers","text":"<p>Event triggers are the most common types of trigger, and they are intended to react to the presence or absence of an event happening in your workspace.  Event triggers are indicated with <code>{\"type\": \"event\"}</code>.</p> <p></p> <p>The schema that defines an event trigger is as follows:</p> Name Type Supports trailing wildcards Description match object Labels for resources which this Automation will match. match_related object Labels for related resources which this Automation will match. posture string enum N/A The posture of this Automation, either Reactive or Proactive. Reactive automations respond to the presence of the expected events, while Proactive automations respond to the absence of those expected events. after array of strings Event(s), one of which must have first been seen to start this automation. expect array of strings The event(s) this automation is expecting to see. If empty, this automation will evaluate any matched event. for_each array of strings Evaluate the Automation separately for each distinct value of these labels on the resource. By default, labels refer to the primary resource of the triggering event. You may also refer to labels from related resources by specifying <code>related:&lt;role&gt;:&lt;label&gt;</code>. This will use the value of that label for the first related resource in that role. threshold integer N/A The number of events required for this Automation to trigger (for Reactive automations), or the number of events expected (for Proactive automations) within number N/A The time period over which the events must occur. For Reactive triggers, this may be as low as 0 seconds, but must be at least 10 seconds for Proactive triggers","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#resource-matching","title":"Resource matching","text":"<p>Both the <code>event</code> and <code>metric</code> triggers support matching events for specific resources in your workspace, including most Prefect objects (like flows, deployment, blocks, work pools, tags, etc) as well as resources you have defined in any events you emit yourself.  The <code>match</code> and <code>match_related</code> fields control which events a trigger considers for evaluation by filtering on the contents of their <code>resource</code> and <code>related</code> fields, respectively. Each label added to a <code>match</code> filter is <code>AND</code>ed with the other labels, and can accept a single value or a list of multiple values that are <code>OR</code>ed together.</p> <p>Consider the <code>resource</code> and <code>related</code> fields on the following <code>prefect.flow-run.Completed</code> event, truncated for the sake of example. Its primary resource is a flow run, and since that flow run was started via a deployment, it is related to both its flow and its deployment:</p> <pre><code>\"resource\": {\n  \"prefect.resource.id\": \"prefect.flow-run.925eacce-7fe5-4753-8f02-77f1511543db\",\n  \"prefect.resource.name\": \"cute-kittiwake\"\n}\n\"related\": [\n  {\n    \"prefect.resource.id\": \"prefect.flow.cb6126db-d528-402f-b439-96637187a8ca\",\n    \"prefect.resource.role\": \"flow\",\n    \"prefect.resource.name\": \"hello\"\n  },\n  {\n    \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\",\n    \"prefect.resource.role\": \"deployment\",\n    \"prefect.resource.name\": \"example\"\n  }\n]\n</code></pre> <p>There are a number of valid ways to select the above event for evaluation, and the approach depends on the purpose of the automation.</p> <p>The following configuration will filter for any events whose primary resource is a flow run, and that flow run has a name starting with <code>cute-</code> or <code>radical-</code>.</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": \"prefect.flow-run.*\",\n  \"prefect.resource.name\": [\"cute-*\", \"radical-*\"]\n},\n\"match_related\": {},\n...\n</code></pre> <p>This configuration, on the other hand, will filter for any events for which this specific deployment is a related resource.</p> <pre><code>\"match\": {},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n},\n...\n</code></pre> <p>Both of the above approaches will select the example <code>prefect.flow-run.Completed</code> event, but will permit additional, possibly undesired events through the filter as well. <code>match</code> and <code>match_related</code> can be combined for more restrictive filtering:</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": \"prefect.flow-run.*\",\n  \"prefect.resource.name\": [\"cute-*\", \"radical-*\"]\n},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n},\n...\n</code></pre> <p>Now this trigger will filter only for events whose primary resource is a flow run started by a specific deployment, and that flow run has a name starting with <code>cute-</code> or <code>radical-</code>.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#expected-events","title":"Expected events","text":"<p>Once an event has passed through the <code>match</code> filters, it must be decided if this event should be counted toward the trigger's <code>threshold</code>. Whether that is the case is determined by the event names present in <code>expect</code>.</p> <p>This configuration informs the trigger to evaluate only <code>prefect.flow-run.Completed</code> events that have passed the <code>match</code> filters.</p> <pre><code>\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n...\n</code></pre> <p><code>threshold</code> decides the quantity of <code>expect</code>ed events needed to satisfy the trigger. Increasing the <code>threshold</code> above 1 will also require use of <code>within</code> to define a range of time in which multiple events are seen. The following configuration will expect two occurrences of <code>prefect.flow-run.Completed</code> within 60 seconds.</p> <pre><code>\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n\"threshold\": 2,\n\"within\": 60,\n...\n</code></pre> <p><code>after</code> can be used to handle scenarios that require more complex event reactivity.</p> <p>Take, for example, this flow which emits an event indicating the table it operates on is missing or empty:</p> <pre><code>from prefect import flow\nfrom prefect.events import emit_event\nfrom db import Table\n\n\n@flow\ndef transform(table_name: str):\n    table = Table(table_name)\n\n    if not table.exists():\n        emit_event(\n            event=\"table-missing\",\n            resource={\"prefect.resource.id\": \"etl-events.transform\"}\n        )\n    elif table.is_empty():\n        emit_event(\n            event=\"table-empty\",\n            resource={\"prefect.resource.id\": \"etl-events.transform\"}\n        )\n    else:\n        # transform data\n</code></pre> <p>The following configuration uses <code>after</code> to prevent this automation from firing unless either a <code>table-missing</code> or a <code>table-empty</code> event has occurred before a flow run of this deployment completes.</p> <p>Tip</p> <p>Note how <code>match</code> and <code>match_related</code> are used to ensure the trigger only evaluates events that are relevant to its purpose.</p> <pre><code>\"match\": {\n  \"prefect.resource.id\": [\n    \"prefect.flow-run.*\",\n    \"etl-events.transform\"\n  ]\n},\n\"match_related\": {\n  \"prefect.resource.id\": \"prefect.deployment.37ca4a08-e2d9-4628-a310-cc15a323378e\"\n}\n\"after\": [\n  \"table-missing\",\n  \"table-empty\"\n]\n\"expect\": [\n  \"prefect.flow-run.Completed\"\n],\n...\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#evaluation-strategy","title":"Evaluation strategy","text":"<p>All of the previous examples were designed around a reactive <code>posture</code> - that is, count up events toward the <code>threshold</code> until it is met, then execute actions. To respond to the absence of events, use a proactive <code>posture</code>. A proactive trigger will fire when its <code>threshold</code> has not been met by the end of the window of time defined by <code>within</code>. Proactive triggers must have a <code>within</code> value of at least 10 seconds.</p> <p>The following trigger will fire if a <code>prefect.flow-run.Completed</code> event is not seen within 60 seconds after a <code>prefect.flow-run.Running</code> event is seen.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {},\n  \"after\": [\n    \"prefect.flow-run.Running\"\n  ],\n  \"expect\": [\n    \"prefect.flow-run.Completed\"\n  ],\n  \"for_each\": [],\n  \"posture\": \"Proactive\",\n  \"threshold\": 1,\n  \"within\": 60\n}\n</code></pre> <p>However, without <code>for_each</code>, a <code>prefect.flow-run.Completed</code> event from a different flow run than the one that started this trigger with its <code>prefect.flow-run.Running</code> event could satisfy the condition. Adding a <code>for_each</code> of <code>prefect.resource.id</code> will cause this trigger to be evaluated separately for each flow run id associated with these events.</p> <pre><code>{\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {},\n  \"after\": [\n    \"prefect.flow-run.Running\"\n  ],\n  \"expect\": [\n    \"prefect.flow-run.Completed\"\n  ],\n  \"for_each\": [\n    \"prefect.resource.id\"\n  ],\n  \"posture\": \"Proactive\",\n  \"threshold\": 1,\n  \"within\": 60\n}\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#metric-triggers","title":"Metric triggers","text":"<p>Metric triggers (<code>{\"type\": \"metric\"}</code>) fire when the value of a metric in your workspace crosses a threshold you've defined.  For example, you can trigger an automation when the success rate of flows in your workspace drops below 95% over the course of an hour.</p> <p>Prefect's metrics are all derived by examining your workspace's events, and if applicable, use the <code>occurred</code> times of those events as the basis for their calculations.</p> <p>Prefect defines three metrics today:</p> <ul> <li>Successes (<code>{\"name\": \"successes\"}</code>), defined as the number of flow runs that went <code>Pending</code> and then the latest state we saw was not a failure (<code>Failed</code> or <code>Crashed</code>).  This metric accounts for retries if the ultimate state was successful.</li> <li>Duration (<code>{\"name\": \"duration\"}</code>), defined as the length of time that a flow remains in a <code>Running</code> state before transitioning to a terminal state such as <code>Completed</code>, <code>Failed</code>, or <code>Crashed</code>.  Because this time is derived in terms of flow run state change events, it may be greater than the runtime of your function.</li> <li>Lateness (<code>{\"name\": \"lateness\"}</code>), defined as the length of time that a <code>Scheduled</code> flow remains in a <code>Late</code> state before transitioning to a <code>Running</code> and/or <code>Crashed</code> state.  Only flow runs that the system marks <code>Late</code> are included.</li> </ul> <p>The schema of a metric trigger is as follows:</p> Name Type Supports trailing wildcards Description match object Labels for resources which this Automation will match. match_related object Labels for related resources which this Automation will match. metric <code>MetricTriggerQuery</code> N/A The definition of the metric query to run <p>And the <code>MetricTriggerQuery</code> query is defined as:</p> Name Type Description name string The name of the Prefect metric to evaluate (see above). threshold number The threshold to which the current metric value is compared operator string (<code>\"&lt;\"</code>, <code>\"&lt;=\"</code>, <code>\"&gt;\"</code>, <code>\"&gt;=\"</code>) The comparison operator to use to decide if the threshold value is met range duration in seconds How far back to evaluate the metric firing_for duration in seconds How long the value must exceed the threshold before this trigger fires <p>For example, to fire when flow runs tagged <code>production</code> in your workspace are failing at a rate of 10% or worse for the last hour (in other words, your success rate is below 90%), create this trigger:</p> <pre><code>{\n  \"type\": \"metric\",\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {\n    \"prefect.resource.id\": \"prefect.tag.production\",\n    \"prefect.resource.role\": \"tag\"\n  },\n  \"metric\": {\n    \"name\": \"successes\",\n    \"threshold\": 0.9,\n    \"operator\": \"&lt;\",\n    \"range\": 3600,\n    \"firing_for\": 0\n  }\n}\n</code></pre> <p>To detect when the average lateness of your Kubernetes workloads (running on a work pool named <code>kubernetes</code>) in the last day exceeds 5 minutes late, and that number hasn't gotten better for the last 10 minutes, use a trigger like this:</p> <pre><code>{\n  \"type\": \"metric\",\n  \"match\": {\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  },\n  \"match_related\": {\n    \"prefect.resource.id\": \"prefect.work-pool.kubernetes\",\n    \"prefect.resource.role\": \"work-pool\"\n  },\n  \"metric\": {\n    \"name\": \"lateness\",\n    \"threshold\": 300,\n    \"operator\": \"&gt;\",\n    \"range\": 86400,\n    \"firing_for\": 600\n  }\n}\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#composite-triggers","title":"Composite triggers","text":"<p>To create a trigger from multiple kinds of events and metrics, use a <code>compound</code> or <code>sequence</code> trigger.  These higher-order triggers are composed from a set of underlying <code>event</code> and <code>metric</code> triggers.</p> <p>For example, if you want to run a deployment only after three different flows in your workspace have written their results to a remote filesystem, combine them with a 'compound' trigger:</p> <pre><code>{\n  \"type\": \"compound\",\n  \"require\": \"all\",\n  \"within\": 3600,\n  \"triggers\": [\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-customer-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-revenue-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-expenses-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    }\n  ]\n}\n</code></pre> <p>This trigger will fire once it sees at least one of each of the underlying event triggers fire within the time frame specified. Then the trigger will reset its state and fire the next time these three events all happen.  The order the events occur doesn't matter, just that all of the events occur within one hour.</p> <p>If you want a flow run to complete prior to starting to watch for those three events,  you can combine the entire previous trigger as the second part of a sequence of two triggers:</p> <pre><code>{\n  // the outer trigger is now a \"sequence\" trigger\n  \"type\": \"sequence\",\n  \"within\": 7200,\n  \"triggers\": [\n    // with the first child trigger expecting a Completed event\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.flow-run.Completed\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-export-initiator\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    // and the second child trigger being the compound trigger from the prior example\n    {\n      \"type\": \"compound\",\n      \"require\": \"all\",\n      \"within\": 3600,\n      \"triggers\": [\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-customer-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        },\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-revenue-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        },\n        {\n          \"type\": \"event\",\n          \"posture\": \"Reactive\",\n          \"expect\": [\"prefect.block.remote-file-system.write_path.called\"],\n          \"match_related\": {\n            \"prefect.resource.name\": \"daily-expenses-export\",\n            \"prefect.resource.role\": \"flow\"\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre> <p>In this case, the trigger will only fire if it sees the <code>daily-export-initiator</code> flow complete, and then the three files written by the other flows.</p> <p>The <code>within</code> parameter for compound and sequence triggers constrains how close in time (in seconds) the child triggers must fire to satisfy the composite trigger.  For example, if the <code>daily-export-initiator</code> flow runs, but the other three flows don't write their result files until three hours later, this trigger won't fire.  Placing these time constraints on the triggers can prevent a misfire if you know that the events will generally happen within a specific timeframe, and you don't want a stray older event to be included in the evaluation of the trigger.  If this isn't a concern for you, you may omit the <code>within</code> period, in which case there is no limit to how far apart in time the child triggers occur.</p> <p>Any type of trigger may be composed into higher-order composite triggers, including proactive event triggers and metric triggers.  In the following example, the compound trigger will fire if any of the following events occur: a flow run stuck in <code>Pending</code>, a work pool becoming unready, or the average amount of <code>Late</code> work in your workspace going over 10 minutes:</p> <pre><code>{\n  \"type\": \"compound\",\n  \"require\": \"any\",\n  \"triggers\": [\n    {\n      \"type\": \"event\",\n      \"posture\": \"Proactive\",\n      \"after\": [\"prefect.flow-run.Pending\"],\n      \"expect\": [\"prefect.flow-run.Running\", \"prefect.flow-run.Crashed\"],\n      \"for_each\": [\"prefect.resource.id\"],\n      \"match_related\": {\n        \"prefect.resource.name\": \"daily-customer-export\",\n        \"prefect.resource.role\": \"flow\"\n      }\n    },\n    {\n      \"type\": \"event\",\n      \"posture\": \"Reactive\",\n      \"expect\": [\"prefect.work-pool.not-ready\"],\n      \"match\": {\n        \"prefect.resource.name\": \"kubernetes-workers\",\n      }\n    },\n    {\n      \"type\": \"metric\",\n      \"metric\": {\n        \"name\": \"lateness\",\n        \"operator\": \"&gt;\",\n        \"threshold\": 600,\n        \"range\": 3600,\n        \"firing_for\": 300\n      }\n    }\n  ]\n}\n</code></pre> <p>For compound triggers, the <code>require</code> parameter may be <code>\"any\"</code>, <code>\"all\"</code>, or a number between 1 and the number of child triggers.  In the example above, if you feel that you are receiving too many spurious notifications for issues that resolve on their own, you can specify <code>{\"require\": 2}</code> to express that any two of the triggers must fire in order for the compound trigger to fire.  Sequence triggers, on the other hand, always require all of their child triggers to fire before they fire.</p> <p>Compound triggers are defined as:</p> Name Type Description require number, <code>\"any\"</code>, or <code>\"all\"</code> How many of the child triggers must fire for this trigger to fire within time, in seconds How close in time the child triggers must fire for this trigger to fire triggers array of other triggers <p>Sequence triggers are defined as:</p> Name Type Description within time, in seconds How close in time the child triggers must fire for this trigger to fire triggers array of other triggers","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#create-an-automation-via-deployment-triggers","title":"Create an automation via deployment triggers","text":"<p>To enable the simple configuration of event-driven deployments, Prefect provides deployment triggers - a shorthand for creating automations that are linked to specific deployments to run them based on the presence or absence of events.</p> <p>Trigger definitions for deployments are supported in <code>prefect.yaml</code>, <code>.serve</code>, and <code>.deploy</code>. At deployment time, specified trigger definitions will create linked automations that are triggered by events matching your chosen grammar. Each trigger definition may include a jinja template to render the triggering <code>event</code> as the <code>parameters</code> of your  deployment's flow run.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#defining-triggers-in-prefectyaml","title":"Defining triggers in <code>prefect.yaml</code>","text":"<p>A list of triggers can be included directly on any deployment in a <code>prefect.yaml</code> file:</p> <pre><code>deployments:\n  - name: my-deployment\n    entrypoint: path/to/flow.py:decorated_fn\n    work_pool:\n      name: my-work-pool\n    triggers:\n      - type: event\n        enabled: true\n        match:\n          prefect.resource.id: my.external.resource\n        expect:\n          - external.resource.pinged\n        parameters:\n          param_1: \"{{ event }}\"\n</code></pre> <p>This deployment will create a flow run when an <code>external.resource.pinged</code> event and an <code>external.resource.replied</code> event have been seen from <code>my.external.resource</code>:</p> <pre><code>deployments:\n  - name: my-deployment\n    entrypoint: path/to/flow.py:decorated_fn\n    work_pool:\n      name: my-work-pool\n    triggers:\n      - type: compound\n        require: all\n        parameters:\n          param_1: \"{{ event }}\"\n        triggers:\n          - type: event\n            match:\n              prefect.resource.id: my.external.resource\n            expect:\n              - external.resource.pinged\n          - type: event\n            match:\n              prefect.resource.id: my.external.resource\n            expect:\n              - external.resource.replied\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#defining-triggers-in-serve-and-deploy","title":"Defining triggers in <code>.serve</code> and <code>.deploy</code>","text":"<p>For creating deployments with triggers in Python, the trigger types <code>DeploymentEventTrigger</code>, <code>DeploymentMetricTrigger</code>, <code>DeploymentCompoundTrigger</code>, and <code>DeploymentSequenceTrigger</code> can be imported from <code>prefect.events</code>:</p> <pre><code>from prefect import flow\nfrom prefect.events import DeploymentEventTrigger\n\n\n@flow(log_prints=True)\ndef decorated_fn(param_1: str):\n    print(param_1)\n\n\nif __name__==\"__main__\":\n    decorated_fn.serve(\n        name=\"my-deployment\",\n        triggers=[\n            DeploymentEventTrigger(\n                enabled=True,\n                match={\"prefect.resource.id\": \"my.external.resource\"},\n                expect=[\"external.resource.pinged\"],\n                parameters={\n                    \"param_1\": \"{{ event }}\",\n                },\n            )\n        ],\n    )\n</code></pre> <p>As with prior examples, composite triggers must be supplied with a list of underlying triggers:</p> <pre><code>from prefect import flow\nfrom prefect.events import DeploymentCompoundTrigger\n\n\n@flow(log_prints=True)\ndef decorated_fn(param_1: str):\n    print(param_1)\n\n\nif __name__==\"__main__\":\n    decorated_fn.deploy(\n        name=\"my-deployment\",\n        image=\"my-image-registry/my-image:my-tag\"\n        triggers=[\n            DeploymentCompoundTrigger(\n                enabled=True,\n                name=\"my-compound-trigger\",\n                require=\"all\",\n                triggers=[\n                    {\n                      \"type\": \"event\",\n                      \"match\": {\"prefect.resource.id\": \"my.external.resource\"},\n                      \"expect\": [\"external.resource.pinged\"],\n                    },\n                    {\n                      \"type\": \"event\",\n                      \"match\": {\"prefect.resource.id\": \"my.external.resource\"},\n                      \"expect\": [\"external.resource.replied\"],\n                    },\n                ],\n                parameters={\n                    \"param_1\": \"{{ event }}\",\n                },\n            )\n        ],\n        work_pool_name=\"my-work-pool\",\n    )\n</code></pre>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#pass-triggers-to-prefect-deploy","title":"Pass triggers to <code>prefect deploy</code>","text":"<p>You can pass one or more <code>--trigger</code> arguments to <code>prefect deploy</code>, which can be either a JSON string or a path to a <code>.yaml</code> or <code>.json</code> file.</p> <pre><code># Pass a trigger as a JSON string\nprefect deploy -n test-deployment \\\n  --trigger '{\n    \"enabled\": true,\n    \"match\": {\n      \"prefect.resource.id\": \"prefect.flow-run.*\"\n    },\n    \"expect\": [\"prefect.flow-run.Completed\"]\n  }'\n\n# Pass a trigger using a JSON/YAML file\nprefect deploy -n test-deployment --trigger triggers.yaml\nprefect deploy -n test-deployment --trigger my_stuff/triggers.json\n</code></pre> <p>For example, a <code>triggers.yaml</code> file could have many triggers defined:</p> <pre><code>triggers:\n  - enabled: true\n    match:\n      prefect.resource.id: my.external.resource\n    expect:\n      - external.resource.pinged\n    parameters:\n      param_1: \"{{ event }}\"\n  - enabled: true\n    match:\n      prefect.resource.id: my.other.external.resource\n    expect:\n      - some.other.event\n    parameters:\n      param_1: \"{{ event }}\"\n</code></pre> <p>Both of the above triggers would be attached to <code>test-deployment</code> after running <code>prefect deploy</code>.</p> <p>Triggers passed to <code>prefect deploy</code> will override any triggers defined in <code>prefect.yaml</code></p> <p>While you can define triggers in <code>prefect.yaml</code> for a given deployment, triggers passed to <code>prefect deploy</code> will take precedence over those defined in <code>prefect.yaml</code>.</p> <p>Note that deployment triggers contribute to the total number of automations in your workspace.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#automation-notifications","title":"Automation notifications","text":"<p>Notifications enable you to set up automation actions that send a message.</p> <p>Automation notifications support sending notifications via any predefined block that is capable of and configured to send a message. That includes, for example:</p> <ul> <li>Slack message to a channel</li> <li>Microsoft Teams message to a channel</li> <li>Email to a configured email address</li> </ul> <p></p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/automations/#templating-with-jinja","title":"Templating with Jinja","text":"<p>Automation actions can access templated variables through Jinja syntax. Templated variables enable you to dynamically include details from an automation trigger, such as a flow or pool name.</p> <p>Jinja templated variable syntax wraps the variable name in double curly brackets, like this: <code>{{ variable }}</code>.</p> <p>You can access properties of the underlying flow run objects including:</p> <ul> <li>flow_run</li> <li>flow</li> <li>deployment</li> <li>work_queue</li> <li>work_pool</li> </ul> <p>In addition to its native properties, each object includes an <code>id</code> along with <code>created</code> and <code>updated</code> timestamps.</p> <p>The <code>flow_run|ui_url</code> token returns the URL for viewing the flow run in Prefect Cloud.</p> <p>Here\u2019s an example for something that would be relevant to a flow run state-based notification:</p> <pre><code>Flow run {{ flow_run.name }} entered state {{ flow_run.state.name }}.\n\n    Timestamp: {{ flow_run.state.timestamp }}\n    Flow ID: {{ flow_run.flow_id }}\n    Flow Run ID: {{ flow_run.id }}\n    State message: {{ flow_run.state.message }}\n</code></pre> <p>The resulting Slack webhook notification would look something like this:</p> <p></p> <p>You could include <code>flow</code> and <code>deployment</code> properties.</p> <pre><code>Flow run {{ flow_run.name }} for flow {{ flow.name }}\nentered state {{ flow_run.state.name }}\nwith message {{ flow_run.state.message }}\n\nFlow tags: {{ flow_run.tags }}\nDeployment name: {{ deployment.name }}\nDeployment version: {{ deployment.version }}\nDeployment parameters: {{ deployment.parameters }}\n</code></pre> <p>An automation that reports on work pool status might include notifications using <code>work_pool</code> properties.</p> <pre><code>Work pool status alert!\n\nName: {{ work_pool.name }}\nLast polled: {{ work_pool.last_polled }}\n</code></pre> <p>In addition to those shortcuts for flows, deployments, and work pools, you have access to the automation and the event that triggered the automation. See the Automations API for additional details.</p> <pre><code>Automation: {{ automation.name }}\nDescription: {{ automation.description }}\n\nEvent: {{ event.id }}\nResource:\n{% for label, value in event.resource %}\n{{ label }}: {{ value }}\n{% endfor %}\nRelated Resources:\n{% for related in event.related %}\n    Role: {{ related.role }}\n    {% for label, value in related %}\n    {{ label }}: {{ value }}\n    {% endfor %}\n{% endfor %}\n</code></pre> <p>Note that this example also illustrates the ability to use Jinja features such as iterator and for loop control structures when templating notifications.</p>","tags":["UI","states","flow runs","events","triggers","Prefect Cloud","automations"],"boost":2},{"location":"concepts/blocks/","title":"Blocks","text":"<p>Prefect blocks store configuration and provide an interface for interacting with external systems.</p> <p>Blocks expose methods that provide functionality specific to the systems they interface with. For example, blocks can be used to download data from or upload data to an S3 bucket, query data from or write data to a database, or send a message to a Slack channel.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#overview","title":"Overview","text":"<p>Block types are Python classes with a handy UI webform for configuration. Blocks are instantiation of these classes with specific values.</p> <p>Configure blocks through Python code or via a form in the UI. Access blocks for use in Python code.</p> <p>Block values are stored in Prefect Cloud or your self-hosted Prefect server instance. Blocks can be shared with other users in your Prefect Cloud workspace.</p> <p>To see block types available for configuration, use <code>prefect block type ls</code> from the CLI or navigate to the Blocks page in the UI and click +.</p> <p></p> <p>Blocks and parameters</p> <p>Blocks are useful for configuration that needs to be shared across flow runs and between flows.</p> <p>For configuration that will change between flow runs, we recommend using parameters.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#prefect-built-in-blocks","title":"Prefect built-in blocks","text":"<p>Commonly used block types come built-in with Prefect.  These block types can be created via the UI and used without installing any additional packages.</p> Block Slug Description Azure <code>azure</code> Stores data as a file on Azure Data Lake and Azure Blob Storage. Custom Webhook <code>custom-webhook</code> Calls custom webhooks. Discord Webhook <code>discord-webhook</code> Calls Discord webhooks. Date Time <code>date-time</code> Stores a datetime value. Docker Container <code>docker-container</code> Runs a command in a container. Docker Registry <code>docker-registry</code> Connects to a Docker registry.  Requires a Docker Engine to be connectable. GCS <code>gcs</code> Store data as a file on Google Cloud Storage. GitHub <code>github</code> Interacts with files stored on public GitHub repositories. JSON <code>json</code> Stores JSON data. Kubernetes Cluster Config <code>kubernetes-cluster-config</code> Stores configuration for interaction with Kubernetes clusters. Kubernetes Job <code>kubernetes-job</code> Runs a command as a Kubernetes Job. Local File System <code>local-file-system</code> Stores data as a file on a local file system. Mattermost Webhook <code>mattermost-webhook</code> Sends notifications via a provided Mattermost webhook. Microsoft Teams Webhook <code>ms-teams-webhook</code> Sends notifications via a provided Microsoft Teams webhook. Opsgenie Webhook <code>opsgenie-webhook</code> Sends notifications via a provided Opsgenie webhook. Pager Duty Webhook <code>pager-duty-webhook</code> Sends notifications via a provided PagerDuty webhook. Process <code>process</code> Run a command in a new process. Remote File System <code>remote-file-system</code> Stores data as a file on any remote file system that supports <code>fsspec</code>. S3 <code>s3</code> Stores data as a file on AWS S3. Secret <code>secret</code> Stores a secret value. The value will be obfuscated when this block is logged or shown in the UI. Sendgrid Email <code>sendgrid-email</code> Sends notifications via Sendgrid email. Slack Webhook <code>slack-webhook</code> Sends notifications via a provided Slack webhook. SMB <code>smb</code> Stores data as a file on a SMB share. String <code>string</code> Stores a string value. Twilio SMS <code>twilio-sms</code> Sends notifications via Twilio SMS. <p>Warning</p> <p>The <code>S3</code>, <code>Azure</code>, <code>GCS</code>, and <code>GitHub</code> blocks are deprecated in favor of the the corresponding <code>S3Bucket</code>, <code>AzureBlobStorageCredentials</code>, <code>GCSBucket</code>, and <code>GitHubRepository</code> blocks found in the Prefect integration libraries.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#blocks-in-prefect-integration-libraries","title":"Blocks in Prefect integration libraries","text":"<p>Some block types that appear in the UI can be created immediately, and then the corresponding integration library must be installed for use. For example, an AWS Secret block can be created, but not used until the <code>prefect-aws</code> library is installed.</p> <p>Block types can be created by anyone and optionally shared with the community. You'll find block types available for consumption in many of the published Prefect integrations libraries. If a block type is not available in the UI, you can register it via the CLI.</p> Integration Block Slug prefect-aws ECS Task <code>ecs-task</code> prefect-aws MinIO Credentials <code>minio-credentials</code> prefect-aws S3 Bucket <code>s3-bucket</code> prefect-azure Azure Blob Storage Credentials <code>azure-blob-storage-credentials</code> prefect-azure Azure Container Instance Credentials <code>azure-container-instance-credentials</code> prefect-azure Azure Container Instance Job <code>azure-container-instance-job</code> prefect-azure Azure Cosmos DB Credentials <code>azure-cosmos-db-credentials</code> prefect-azure AzureML Credentials <code>azureml-credentials</code> prefect-bitbucket BitBucket Credentials <code>bitbucket-credentials</code> prefect-bitbucket BitBucket Repository <code>bitbucket-repository</code> prefect-databricks Databricks Credentials <code>databricks-credentials</code> prefect-dbt dbt CLI BigQuery Target Configs <code>dbt-cli-bigquery-target-configs</code> prefect-dbt dbt CLI Profile <code>dbt-cli-profile</code> prefect-dbt dbt Cloud Credentials <code>dbt-cloud-credentials</code> prefect-dbt dbt CLI Global Configs <code>dbt-cli-global-configs</code> prefect-dbt dbt CLI Postgres Target Configs <code>dbt-cli-postgres-target-configs</code> prefect-dbt dbt CLI Snowflake Target Configs <code>dbt-cli-snowflake-target-configs</code> prefect-dbt dbt CLI Target Configs <code>dbt-cli-target-configs</code> prefect-docker Docker Host <code>docker-host</code> prefect-docker Docker Registry Credentials <code>docker-registry-credentials</code> prefect-email Email Server Credentials <code>email-server-credentials</code> prefect-gcp BigQuery Warehouse <code>bigquery-warehouse</code> prefect-gcp GCP Cloud Run Job <code>cloud-run-job</code> prefect-gcp GCP Credentials <code>gcp-credentials</code> prefect-gcp GcpSecret <code>gcpsecret</code> prefect-gcp GCS Bucket <code>gcs-bucket</code> prefect-gcp Vertex AI Custom Training Job <code>vertex-ai-custom-training-job</code> prefect-github GitHub Credentials <code>github-credentials</code> prefect-github GitHub Repository <code>github-repository</code> prefect-gitlab GitLab Credentials <code>gitlab-credentials</code> prefect-gitlab GitLab Repository <code>gitlab-repository</code> prefect-kubernetes Kubernetes Credentials <code>kubernetes-credentials</code> prefect-shell Shell Operation <code>shell-operation</code> prefect-slack Slack Credentials <code>slack-credentials</code> prefect-slack Slack Incoming Webhook <code>slack-incoming-webhook</code> prefect-snowflake Snowflake Connector <code>snowflake-connector</code> prefect-snowflake Snowflake Credentials <code>snowflake-credentials</code> prefect-sqlalchemy Database Credentials <code>database-credentials</code> prefect-sqlalchemy SQLAlchemy Connector <code>sqlalchemy-connector</code>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#use-existing-block-types","title":"Use existing block types","text":"<p>Blocks are classes that subclass the <code>Block</code> base class. They can be instantiated and used like normal classes.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#instantiate-blocks","title":"Instantiate blocks","text":"<p>To instantiate a block that stores a JSON value, use the <code>JSON</code> block:</p> <pre><code>from prefect.blocks.system import JSON\n\njson_block = JSON(value={\"the_answer\": 42})\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#save-blocks","title":"Save blocks","text":"<p>To retrieve this saved value use the <code>.save()</code> method:</p> <pre><code>json_block.save(name=\"life-the-universe-everything\")\n</code></pre> <p>To update saved block value stored for a given block, overwrite the existing block by passing <code>overwrite=True</code>:</p> <pre><code>json_block.save(overwrite=True)\n</code></pre> <p>Create a new JSON block by setting the <code>name</code> parameter to a new value:</p> <pre><code>json_block.save(name=\"actually-life-the-universe-everything\")\n</code></pre> <p>Note that blocks can also be created and updated via the Prefect UI.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#load-blocks","title":"Load blocks","text":"<p>The block name can be used to load the block:</p> <pre><code>from prefect import flow\nfrom prefect.blocks.system import JSON\n\n@flow\ndef what_is_the_answer():\n    json_block = JSON.load(\"life-the-universe-everything\")\n    print(json_block.value[\"the_answer\"])\n\nif __name__ == \"__main__\":\n    what_is_the_answer() # 42\n</code></pre> <p>Alternatively, load a block with the unique slug that is a combination of the block type slug and the block name.</p> <p>To load our JSON block from above, run the following:</p> <pre><code>from prefect.blocks.core import Block\n\njson_block = Block.load(\"json/life-the-universe-everything\")\nprint(json_block.value[\"the-answer\"]) #42\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#delete-blocks","title":"Delete blocks","text":"<p>Delete a block with the <code>.delete()</code> method:</p> <pre><code>from prefect.blocks.core import Block\n\nBlock.delete(\"json/life-the-universe-everything\")\n</code></pre> <p>Alternatively, use the CLI to delete specific blocks with a given slug or id:</p> <pre><code>prefect block delete json/life-the-universe-everything\n</code></pre> <pre><code>prefect block delete --id &lt;my-id&gt;\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#creating-new-block-types","title":"Creating new block types","text":"<p>To create a custom block type, define a class that subclasses <code>Block</code>. The <code>Block</code> base class builds on Pydantic's <code>BaseModel</code>, so custom blocks can be declared in the same manner as a Pydantic model.</p> <p>Here's a block that represents a cube and holds information about the length of each edge in inches:</p> <pre><code>from prefect.blocks.core import Block\n\nclass Cube(Block):\n    edge_length_inches: float\n</code></pre> <p>You can include methods on a block to provide functionality. Here's the same cube block with methods to calculate the volume and surface area of the cube:</p> <pre><code>from prefect.blocks.core import Block\n\nclass Cube(Block):\n    edge_length_inches: float\n\n    def get_volume(self):\n        return self.edge_length_inches**3\n\n    def get_surface_area(self):\n        return 6 * self.edge_length_inches**2\n</code></pre> <p>Use the new <code>Cube</code> block type in a flow:</p> <pre><code>from prefect import flow\n\nrubiks_cube = Cube(edge_length_inches=2.25)\nrubiks_cube.save(\"rubiks-cube\")\n\n@flow\ndef calculate_cube_surface_area(cube_name):\n    cube = Cube.load(cube_name)\n    print(cube.get_surface_area())\n\nif __name__ == \"__main__\":\n    calculate_cube_surface_area(\"rubiks-cube\") # 30.375\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#secret-fields","title":"Secret fields","text":"<p>All block values are encrypted before being stored. If you have values that you would not like visible in the UI or in logs, use the <code>SecretStr</code> field type provided by Pydantic to automatically obfuscate those values. This functionality can be useful for fields that are used to store credentials such as passwords and API tokens.</p> <p>Here's an example of an <code>AWSCredentials</code> block that uses <code>SecretStr</code>:</p> <pre><code>from typing import Optional\n\nfrom prefect.blocks.core import Block\nfrom pydantic import SecretStr  # if pydantic version &gt;= 2.0, use: from pydantic.v1 import SecretStr\n\nclass AWSCredentials(Block):\n    aws_access_key_id: Optional[str] = None\n    aws_secret_access_key: Optional[SecretStr] = None\n    aws_session_token: Optional[str] = None\n    profile_name: Optional[str] = None\n    region_name: Optional[str] = None\n</code></pre> <p>Because <code>aws_secret_access_key</code> has the <code>SecretStr</code> type hint assigned to it, the value of that field will not be exposed if the object is logged:</p> <pre><code>aws_credentials_block = AWSCredentials(\n    aws_access_key_id=\"AKIAJKLJKLJKLJKLJKLJK\",\n    aws_secret_access_key=\"secret_access_key\"\n)\n\nprint(aws_credentials_block)\n# aws_access_key_id='AKIAJKLJKLJKLJKLJKLJK' aws_secret_access_key=SecretStr('**********') aws_session_token=None profile_name=None region_name=None\n</code></pre> <p>Prefect's <code>SecretDict</code> field type allows you to add a dictionary field to your block that will have values at all levels automatically obfuscated in the UI or in logs. This functionality is useful for blocks where typing or structure of secret fields is not known until configuration time.</p> <p>Here's an example of a block that uses <code>SecretDict</code>:</p> <pre><code>from typing import Dict\n\nfrom prefect.blocks.core import Block\nfrom prefect.blocks.fields import SecretDict\n\n\nclass SystemConfiguration(Block):\n    system_secrets: SecretDict\n    system_variables: Dict\n\n\nsystem_configuration_block = SystemConfiguration(\n    system_secrets={\n        \"password\": \"p@ssw0rd\",\n        \"api_token\": \"token_123456789\",\n        \"private_key\": \"&lt;private key here&gt;\",\n    },\n    system_variables={\n        \"self_destruct_countdown_seconds\": 60,\n        \"self_destruct_countdown_stop_time\": 7,\n    },\n)\n</code></pre> <p><code>system_secrets</code> will be obfuscated when <code>system_configuration_block</code> is displayed, but <code>system_variables</code> will be shown in plain-text:</p> <pre><code>print(system_configuration_block)\n# SystemConfiguration(\n#   system_secrets=SecretDict('{'password': '**********', 'api_token': '**********', 'private_key': '**********'}'), \n#   system_variables={'self_destruct_countdown_seconds': 60, 'self_destruct_countdown_stop_time': 7}\n# )\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#block-type-metadata","title":"Block type metadata","text":"<p>The way that a block is displayed can be controlled by metadata fields that can be set on a block type's subclass.</p> <p>Available metadata fields include:</p> Property Description _block_type_name Display name of the block in the UI. Defaults to the class name. _block_type_slug Unique slug used to reference the block type in the API. Defaults to a lowercase, dash-delimited version of the block type name. _logo_url URL pointing to an image that should be displayed for the block type in the UI. Default to <code>None</code>. _description Short description of block type. Defaults to docstring, if provided. _code_example Short code snippet shown in UI for how to load/use block type. Default to first example provided in the docstring of the class, if provided.","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#nested-blocks","title":"Nested blocks","text":"<p>Blocks are composable - a block can be used within other blocks. You can create a block type that uses functionality from another block type by declaring it as an attribute.</p> <p>Nestable blocks are loosely coupled, as configuration can be changed for each block independently. This allows configuration to be shared across multiple use cases.</p> <p>To illustrate, here's a an expanded <code>AWSCredentials</code> block that includes the ability to get an authenticated session via the <code>boto3</code> library:</p> <pre><code>from typing import Optional\n\nimport boto3\nfrom prefect.blocks.core import Block\nfrom pydantic import SecretStr\n\nclass AWSCredentials(Block):\n    aws_access_key_id: Optional[str] = None\n    aws_secret_access_key: Optional[SecretStr] = None\n    aws_session_token: Optional[str] = None\n    profile_name: Optional[str] = None\n    region_name: Optional[str] = None\n\n    def get_boto3_session(self):\n        return boto3.Session(\n            aws_access_key_id = self.aws_access_key_id\n            aws_secret_access_key = self.aws_secret_access_key\n            aws_session_token = self.aws_session_token\n            profile_name = self.profile_name\n            region_name = self.region\n        )\n</code></pre> <p>The <code>AWSCredentials</code> block can be used within an S3Bucket block to provide authentication when interacting with an S3 bucket:</p> <pre><code>import io\n\nclass S3Bucket(Block):\n    bucket_name: str\n    credentials: AWSCredentials\n\n    def read(self, key: str) -&gt; bytes:\n        s3_client = self.credentials.get_boto3_session().client(\"s3\")\n\n        stream = io.BytesIO()\n        s3_client.download_fileobj(Bucket=self.bucket_name, key=key, Fileobj=stream)\n\n        stream.seek(0)\n        output = stream.read()\n\n        return output\n\n    def write(self, key: str, data: bytes) -&gt; None:\n        s3_client = self.credentials.get_boto3_session().client(\"s3\")\n        stream = io.BytesIO(data)\n        s3_client.upload_fileobj(stream, Bucket=self.bucket_name, Key=key)\n</code></pre> <p>You can use this <code>S3Bucket</code> block with previously saved <code>AWSCredentials</code> block values in order to interact with the configured S3 bucket:</p> <pre><code>my_s3_bucket = S3Bucket(\n    bucket_name=\"my_s3_bucket\",\n    credentials=AWSCredentials.load(\"my_aws_credentials\")\n)\n\nmy_s3_bucket.save(\"my_s3_bucket\")\n</code></pre> <p>Saving block values like this links the values of the two blocks so that any changes to the values stored for the <code>AWSCredentials</code> block with the name <code>my_aws_credentials</code> will be seen the next time that block values for the <code>S3Bucket</code> block named <code>my_s3_bucket</code> is loaded.</p> <p>Values for nested blocks can also be hard coded by not first saving child blocks:</p> <pre><code>my_s3_bucket = S3Bucket(\n    bucket_name=\"my_s3_bucket\",\n    credentials=AWSCredentials(\n        aws_access_key_id=\"AKIAJKLJKLJKLJKLJKLJK\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n)\n\nmy_s3_bucket.save(\"my_s3_bucket\")\n</code></pre> <p>In the above example, the values for <code>AWSCredentials</code> are saved with <code>my_s3_bucket</code> and will not be usable with any other blocks.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#update-custom-block-types","title":"Update custom <code>Block</code> types","text":"<p>Let's add a <code>bucket_folder</code> field to your custom <code>S3Bucket</code> block that represents the default path to read and write objects from (this field exists on our implementation).</p> <p>Add the new field to the class definition:</p> <pre><code>class S3Bucket(Block):\n    bucket_name: str\n    credentials: AWSCredentials\n    bucket_folder: str = None\n    ...\n</code></pre> <p>Then register the updated block type with either Prefect Cloud or your self-hosted Prefect server instance.</p> <p>If you have any existing blocks of this type that were created before the update and you'd prefer to not re-create them, migrate them to the new version of your block type by adding the missing values:</p> <pre><code># Bypass Pydantic validation to allow your local Block class to load the old block version\nmy_s3_bucket_block = S3Bucket.load(\"my-s3-bucket\", validate=False)\n\n# Set the new field to an appropriate value\nmy_s3_bucket_block.bucket_path = \"my-default-bucket-path\"\n\n# Overwrite the old block values and update the expected fields on the block\nmy_s3_bucket_block.save(\"my-s3-bucket\", overwrite=True)\n</code></pre>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/blocks/#register-blocks","title":"Register blocks","text":"<p>Prefect comes with many blocks pre-registered and ready to use. If you do not have a block available for use, you can register it.</p> <p>Blocks can be registered from a Python module available in the current environment with a CLI command like this:</p> <pre><code>prefect block register --module prefect_aws.credentials\n</code></pre> <p>This command is useful for registering all blocks found within a module in a Prefect Integration library.</p> <p>Alternatively, if a custom block has been created in a <code>.py</code> file, the block can also be registered with the CLI command:</p> <pre><code>prefect block register --file my_block.py\n</code></pre> <p>The registered block will then be available for configuration.</p>","tags":["blocks","storage","secrets","configuration"],"boost":2},{"location":"concepts/deployments-block-based/","title":"Block Based Deployments","text":"<p>Workers are recommended</p> <p>This page is about the block-based deployment model. The Work Pools and Workers based deployment model simplifies the specification of a flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p> <p>We encourage you to check out the new deployment experience with guided command line prompts and convenient CI/CD with <code>prefect.yaml</code> files.</p> <p>With remote storage blocks, you can package not only your flow code script but also any supporting files, including your custom modules, SQL scripts and any configuration files needed in your project.</p> <p>To define how your flow execution environment should be configured, you may either reference pre-configured infrastructure blocks or let Prefect create those automatically for you as anonymous blocks (this happens when you specify the infrastructure type using <code>--infra</code> flag during the build process).</p> <p>Work queue affinity improved starting from Prefect 2.0.5</p> <p>Until Prefect 2.0.4, tags were used to associate flow runs with work queues. Starting in Prefect 2.0.5, tag-based work queues are deprecated. Instead, work queue names are used to explicitly direct flow runs from deployments into queues.</p> <p>Note that backward compatibility is maintained and work queues that use tag-based matching can still be created and will continue to work. However, those work queues are now considered legacy and we encourage you to use the new behavior by specifying work queues explicitly on agents and deployments.</p> <p>See Agents &amp; Work Pools for details.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployments-and-flows","title":"Deployments and flows","text":"<p>Each deployment is associated with a single flow, but any given flow can be referenced by multiple deployments.</p> <p>Deployments are uniquely identified by the combination of: <code>flow_name/deployment_name</code>.</p> <pre><code>graph LR\n    F(\"my_flow\"):::yellow -.-&gt; A(\"Deployment 'daily'\"):::tan --&gt; W(\"my_flow/daily\"):::fgreen\n    F -.-&gt; B(\"Deployment 'weekly'\"):::gold  --&gt; X(\"my_flow/weekly\"):::green\n    F -.-&gt; C(\"Deployment 'ad-hoc'\"):::dgold --&gt; Y(\"my_flow/ad-hoc\"):::dgreen\n    F -.-&gt; D(\"Deployment 'trigger-based'\"):::dgold --&gt; Z(\"my_flow/trigger-based\"):::dgreen\n\n    classDef gold fill:goldenrod,stroke:goldenrod,stroke-width:4px,color:white\n    classDef yellow fill:gold,stroke:gold,stroke-width:4px\n    classDef dgold fill:darkgoldenrod,stroke:darkgoldenrod,stroke-width:4px,color:white\n    classDef tan fill:tan,stroke:tan,stroke-width:4px,color:white\n    classDef fgreen fill:forestgreen,stroke:forestgreen,stroke-width:4px,color:white\n    classDef green fill:green,stroke:green,stroke-width:4px,color:white\n    classDef dgreen fill:darkgreen,stroke:darkgreen,stroke-width:4px,color:white</code></pre> <p>This enables you to run a single flow with different parameters, based on multiple schedules and triggers, and in different environments. This also enables you to run different versions of the same flow for testing and production purposes.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-definition","title":"Deployment definition","text":"<p>A deployment definition captures the settings for creating a deployment object on the Prefect API. You can create the deployment definition by:</p> <ul> <li>Run the <code>prefect deployment build</code> CLI command with deployment options to create a <code>deployment.yaml</code> deployment definition file, then run <code>prefect deployment apply</code> to create a deployment on the API using the settings in <code>deployment.yaml</code>.</li> <li>Define a <code>Deployment</code> Python object, specifying the deployment options as properties of the object, then building and applying the object using methods of <code>Deployment</code>.</li> </ul> <p>The minimum required information to create a deployment includes:</p> <ul> <li>The path and filename of the file containing the flow script.</li> <li>The name of the entrypoint flow function \u2014 this is the flow function that starts the flow and calls and additional tasks or subflows.</li> <li>The name of the deployment.</li> </ul> <p>You may provide additional settings for the deployment. Any settings you do not explicitly specify are inferred from defaults.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment-on-the-cli","title":"Create a deployment on the CLI","text":"<p>To create a deployment on the CLI, there are two steps:</p> <ol> <li>Build the deployment definition file <code>deployment.yaml</code>. This step includes uploading your flow to its configured remote storage location, if one is specified.</li> <li>Create the deployment on the API.</li> </ol>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#build-the-deployment","title":"Build the deployment","text":"<p>To build the deployment definition file <code>deployment.yaml</code>, run the <code>prefect deployment build</code> Prefect CLI command from the folder containing your flow script and any dependencies of the script.</p> <pre><code>$ prefect deployment build [OPTIONS] PATH\n</code></pre> <p>Path to the flow is specified in the format <code>path-to-script:flow-function-name</code> \u2014 The path and filename of the flow script file, a colon, then the name of the entrypoint flow function.</p> <p>For example:</p> <pre><code>$ prefect deployment build -n marvin -p default-agent-pool -q test flows/marvin.py:say_hi\n</code></pre> <p>When you run this command, Prefect:</p> <ul> <li>Creates a <code>marvin_flow-deployment.yaml</code> file for your deployment based on your flow code and options.</li> <li>Uploads your flow files to the configured storage location (local by default).</li> <li>Submit your deployment to the work queue <code>test</code>. The work queue <code>test</code> will be created if it doesn't exist.</li> </ul> <p>Uploading files may require storage filesystem libraries</p> <p>Note that the appropriate filesystem library supporting the storage location must be installed prior to building a deployment with a storage block. For example, the AWS S3 Storage block requires the <code>s3fs</code> library.</p> <p>Ignore files or directories from a deployment</p> <p>By default, Prefect uploads all files in the current folder to the configured storage location (local by default) when you build a deployment.</p> <p>If you want to omit certain files or directories from your deployments, add a <code>.prefectignore</code> file to the root directory. <code>.prefectignore</code> enables users to omit certain files or directories from their deployments.</p> <p>Similar to other <code>.ignore</code> files, the syntax supports pattern matching, so an entry of <code>*.pyc</code> will ensure all <code>.pyc</code> files are ignored by the deployment call when uploading to remote storage.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-build-options","title":"Deployment build options","text":"<p>You may specify additional options to further customize your deployment.</p> <p> Options Description PATH Path, filename, and flow name of the flow definition. (Required) <code>--apply</code>, <code>-a</code> When provided, automatically registers the resulting deployment with the API. <code>--cron TEXT</code> A cron string that will be used to set a <code>CronSchedule</code> on the deployment. For example, <code>--cron \"*/1 * * * *\"</code> to create flow runs from that deployment every minute. <code>--help</code> Display help for available commands and options. <code>--infra-block TEXT</code>, <code>-ib</code> The infrastructure block to use, in <code>block-type/block-name</code> format. <code>--infra</code>, <code>-i</code> The infrastructure type to use. (Default is <code>Process</code>) <code>--interval INTEGER</code> An integer specifying an interval (in seconds) that will be used to set an <code>IntervalSchedule</code> on the deployment. For example, <code>--interval 60</code> to create flow runs from that deployment every minute. <code>--name TEXT</code>, <code>-n</code> The name of the deployment. <code>--output TEXT</code>, <code>-o</code> Optional location for the YAML manifest generated as a result of the <code>build</code> step. You can version-control that file, but it's not required since the CLI can generate everything you need to define a deployment. <code>--override TEXT</code> One or more optional infrastructure overrides provided as a dot delimited path. For example, specify an environment variable: <code>env.env_key=env_value</code>. For Kubernetes, specify customizations: <code>customizations='[{\"op\": \"add\",\"path\": \"/spec/template/spec/containers/0/resources/limits\", \"value\": {\"memory\": \"8Gi\",\"cpu\": \"4000m\"}}]'</code> (note the string format). <code>--param</code> An optional parameter override, values are parsed as JSON strings. For example, <code>--param question=ultimate --param answer=42</code>. <code>--params</code> An optional parameter override in a JSON string format. For example, <code>--params=\\'{\"question\": \"ultimate\", \"answer\": 42}\\'</code>. <code>--path</code> An optional path to specify a subdirectory of remote storage to upload to, or to point to a subdirectory of a locally stored flow. <code>--pool TEXT</code>, <code>-p</code> The work pool that will handle this deployment's runs. \u2502 <code>--rrule TEXT</code> An <code>RRule</code> that will be used to set an <code>RRuleSchedule</code> on the deployment. For example, <code>--rrule 'FREQ=HOURLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9,10,11,12,13,14,15,16,17'</code> to create flow runs from that deployment every hour but only during business hours. <code>--skip-upload</code> When provided, skips uploading this deployment's files to remote storage. <code>--storage-block TEXT</code>, <code>-sb</code> The storage block to use, in <code>block-type/block-name</code> or <code>block-type/block-name/path</code> format. Note that the appropriate library supporting the storage filesystem must be installed. <code>--tag TEXT</code>, <code>-t</code> One or more optional tags to apply to the deployment. <code>--version TEXT</code>, <code>-v</code> An optional version for the deployment. This could be a git commit hash if you use this command from a CI/CD pipeline. <code>--work-queue TEXT</code>, <code>-q</code> The work queue that will handle this deployment's runs. It will be created if it doesn't already exist. Defaults to <code>None</code>. Note that if a work queue is not set, work will not be scheduled.","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#block-identifiers","title":"Block identifiers","text":"<p>When specifying a storage block with the <code>-sb</code> or <code>--storage-block</code> flag, you may specify the block by passing its slug. The storage block slug is formatted as <code>block-type/block-name</code>. </p> <p>For example, <code>s3/example-block</code> is the slug for an S3 block named <code>example-block</code>.</p> <p>In addition, when passing the storage block slug, you may pass just the block slug or the block slug and a path.</p> <ul> <li><code>block-type/block-name</code> indicates just the block, including any path included in the block configuration.</li> <li><code>block-type/block-name/path</code> indicates a storage path in addition to any path included in the block configuration.</li> </ul> <p>When specifying an infrastructure block with the <code>-ib</code> or <code>--infra-block</code> flag, you specify the block by passing its slug. The infrastructure block slug is formatted as <code>block-type/block-name</code>. </p> Block name Block class name Block type for a slug Azure <code>Azure</code> <code>azure</code> Docker Container <code>DockerContainer</code> <code>docker-container</code> GitHub <code>GitHub</code> <code>github</code> GCS <code>GCS</code> <code>gcs</code> Kubernetes Job <code>KubernetesJob</code> <code>kubernetes-job</code> Process <code>Process</code> <code>process</code> Remote File System <code>RemoteFileSystem</code> <code>remote-file-system</code> S3 <code>S3</code> <code>s3</code> SMB <code>SMB</code> <code>smb</code> GitLab Repository <code>GitLabRepository</code> <code>gitlab-repository</code> <p>Note that the appropriate library supporting the storage filesystem must be installed prior to building a deployment with a storage block. For example, the AWS S3 Storage block requires the <code>s3fs</code> library. See Storage for more information.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deploymentyaml","title":"deployment.yaml","text":"<p>A deployment's YAML file configures additional settings needed to create a deployment on the server.</p> <p>A single flow may have multiple deployments created for it, with different schedules, tags, and so on. A single flow definition may have multiple deployment YAML files referencing it, each specifying different settings. The only requirement is that each deployment must have a unique name.</p> <p>The default <code>{flow-name}-deployment.yaml</code> filename may be edited as needed with the <code>--output</code> flag to <code>prefect deployment build</code>.</p> <pre><code>###\n### A complete description of a Prefect Deployment for flow 'Cat Facts'\n###\nname: catfact\ndescription: null\nversion: c0fc95308d8137c50d2da51af138aa23\n# The work queue that will handle this deployment's runs\nwork_queue_name: test\nwork_pool_name: null\ntags: []\nparameters: {}\nschedule: null\ninfra_overrides: {}\ninfrastructure:\n  type: process\n  env: {}\n  labels: {}\n  name: null\n  command:\n  - python\n  - -m\n  - prefect.engine\n  stream_output: true\n###\n### DO NOT EDIT BELOW THIS LINE\n###\nflow_name: Cat Facts\nmanifest_path: null\nstorage: null\npath: /Users/terry/test/testflows/catfact\nentrypoint: catfact.py:catfacts_flow\nparameter_openapi_schema:\n  title: Parameters\n  type: object\n  properties:\n    url:\n      title: url\n  required:\n  - url\n  definitions: null\n</code></pre> <p>Editing deployment.yaml</p> <p>Note the big DO NOT EDIT comment in your deployment's YAML: In practice, anything above this block can be freely edited before running <code>prefect deployment apply</code> to create the deployment on the API.</p> <p>We recommend editing most of these fields from the CLI or Prefect UI for convenience.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#parameters-in-deployments","title":"Parameters in deployments","text":"<p>You may provide default parameter values in the <code>deployment.yaml</code> configuration, and these parameter values will be used for flow runs based on the deployment. </p> <p>To configure default parameter values, add them to the <code>parameters: {}</code> line of <code>deployment.yaml</code> as JSON key-value pairs. The parameter list configured in <code>deployment.yaml</code> must match the parameters expected by the entrypoint flow function.</p> <pre><code>parameters: {\"name\": \"Marvin\", \"num\": 42, \"url\": \"https://catfact.ninja/fact\"}\n</code></pre> <p>Passing **kwargs as flow parameters</p> <p>You may pass <code>**kwargs</code> as a deployment parameter as a <code>\"kwargs\":{}</code> JSON object containing the key-value pairs of any passed keyword arguments.</p> <pre><code>parameters: {\"name\": \"Marvin\", \"kwargs\":{\"cattype\":\"tabby\",\"num\": 42}\n</code></pre> <p>You can edit default parameters for deployments in the Prefect UI, and you can override default parameter values when creating ad-hoc flow runs via the Prefect UI.</p> <p>To edit parameters in the Prefect UI, go the the details page for a deployment, then select Edit from the commands menu. If you change parameter values, the new values are used for all future flow runs based on the deployment.</p> <p>To create an ad-hoc flow run with different parameter values, go the the details page for a deployment, select Run, then select Custom. You will be able to provide custom values for any editable deployment fields. Under Parameters, select Custom. Provide the new values, then select Save. Select Run to begin the flow run with custom values.</p> <p>If you want the Prefect API to verify the parameter values passed to a flow run against the schema defined by <code>parameter_openapi_schema</code>, set <code>enforce_parameter_schema</code> to <code>true</code>.</p> <p></p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment","title":"Create a deployment","text":"<p>When you've configured <code>deployment.yaml</code> for a deployment, you can create the deployment on the API by running the <code>prefect deployment apply</code> Prefect CLI command.</p> <pre><code>$ prefect deployment apply catfacts_flow-deployment.yaml\n</code></pre> <p>For example:</p> <pre><code>$ prefect deployment apply ./catfacts_flow-deployment.yaml\nSuccessfully loaded 'catfact'\nDeployment '76a9f1ac-4d8c-4a92-8869-615bec502685' successfully created.\n</code></pre> <p><code>prefect deployment apply</code> accepts an optional <code>--upload</code> flag that, when provided, uploads this deployment's files to remote storage.</p> <p>Once the deployment has been created, you'll see it in the Prefect UI and can inspect it using the CLI.</p> <pre><code>$ prefect deployment ls\n                               Deployments\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                           \u2503 ID                                   \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Cat Facts/catfact              \u2502 76a9f1ac-4d8c-4a92-8869-615bec502685 \u2502\n\u2502 leonardo_dicapriflow/hello_leo \u2502 fb4681d7-aa5a-4617-bf6f-f67e6f964984 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> <p></p> <p>When you run a deployed flow with Prefect, the following happens:</p> <ul> <li>The user runs the deployment, which creates a flow run. (The API creates flow runs automatically for deployments with schedules.)</li> <li>An agent picks up the flow run from a work queue and uses an infrastructure block to create infrastructure for the run.</li> <li>The flow run executes within the infrastructure.</li> </ul> <p>Agents and work pools enable the Prefect orchestration engine and API to run deployments in your local execution environments. To execute deployed flow runs you need to configure at least one agent.</p> <p>Scheduled flow runs</p> <p>Scheduled flow runs will not be created unless the scheduler is running with either Prefect Cloud or a local Prefect server started with <code>prefect server start</code>.</p> <p>Scheduled flow runs will not run unless an appropriate agent and work pool are configured.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-deployment-from-a-python-object","title":"Create a deployment from a Python object","text":"<p>You can also create deployments from Python scripts by using the <code>prefect.deployments.Deployment</code> class.</p> <p>Create a new deployment using configuration defaults for an imported flow:</p> <pre><code>from my_project.flows import my_flow\nfrom prefect.deployments import Deployment\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"example-deployment\", \n    version=1, \n    work_queue_name=\"demo\",\n    work_pool_name=\"default-agent-pool\",\n)\ndeployment.apply()\n</code></pre> <p>Create a new deployment with a pre-defined storage block and an infrastructure override:</p> <pre><code>from my_project.flows import my_flow\nfrom prefect.deployments import Deployment\nfrom prefect.filesystems import S3\n\nstorage = S3.load(\"dev-bucket\") # load a pre-defined block\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"s3-example\",\n    version=2,\n    work_queue_name=\"aws\",\n    work_pool_name=\"default-agent-pool\",\n    storage=storage,\n    infra_overrides={\n        \"env\": {\n            \"ENV_VAR\": \"value\"\n        }\n    },\n)\n\ndeployment.apply()\n</code></pre> <p>If you have settings that you want to share from an existing deployment you can load those settings:</p> <pre><code>deployment = Deployment(\n    name=\"a-name-you-used\", \n    flow_name=\"name-of-flow\"\n)\ndeployment.load() # loads server-side settings\n</code></pre> <p>Once the existing deployment settings are loaded, you may update them as needed by changing deployment properties.</p> <p>View all of the parameters for the <code>Deployment</code> object in the Python API documentation.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#deployment-api-representation","title":"Deployment API representation","text":"<p>When you create a deployment, it is constructed from deployment definition data you provide and additional properties set by client-side utilities.</p> <p>Deployment properties include:</p> Property Description <code>id</code> An auto-generated UUID ID value identifying the deployment. <code>created</code> A <code>datetime</code> timestamp indicating when the deployment was created. <code>updated</code> A <code>datetime</code> timestamp indicating when the deployment was last changed. <code>name</code> The name of the deployment. <code>version</code> The version of the deployment <code>description</code> A description of the deployment. <code>flow_id</code> The id of the flow associated with the deployment. <code>schedule</code> An optional schedule for the deployment. <code>is_schedule_active</code> Boolean indicating whether the deployment schedule is active. Default is True. <code>infra_overrides</code> One or more optional infrastructure overrides <code>parameters</code> An optional dictionary of parameters for flow runs scheduled by the deployment. <code>tags</code> An optional list of tags for the deployment. <code>work_queue_name</code> The optional work queue that will handle the deployment's run <code>parameter_openapi_schema</code> JSON schema for flow parameters. <code>enforce_parameter_schema</code> Whether the API should validate the parameters passed to a flow run against the schema defined by <code>parameter_openapi_schema</code> <code>path</code> The path to the deployment.yaml file <code>entrypoint</code> The path to a flow entry point <code>storage_document_id</code> Storage block configured for the deployment. <code>infrastructure_document_id</code> Infrastructure block configured for the deployment. <p>You can inspect a deployment using the CLI with the <code>prefect deployment inspect</code> command, referencing the deployment with <code>&lt;flow_name&gt;/&lt;deployment_name&gt;</code>.</p> <pre><code>$ prefect deployment inspect 'Cat Facts/catfact'\n{\n    'id': '76a9f1ac-4d8c-4a92-8869-615bec502685',\n    'created': '2022-07-26T03:48:14.723328+00:00',\n    'updated': '2022-07-26T03:50:02.043238+00:00',\n    'name': 'catfact',\n    'version': '899b136ebc356d58562f48d8ddce7c19',\n    'description': None,\n    'flow_id': '2c7b36d1-0bdb-462e-bb97-f6eb9fef6fd5',\n    'schedule': None,\n    'is_schedule_active': True,\n    'infra_overrides': {},\n    'parameters': {},\n    'tags': [],\n    'work_queue_name': 'test',\n    'parameter_openapi_schema': {\n        'title': 'Parameters',\n        'type': 'object',\n        'properties': {'url': {'title': 'url'}},\n        'required': ['url']\n    },\n    'path': '/Users/terry/test/testflows/catfact',\n    'entrypoint': 'catfact.py:catfacts_flow',\n    'manifest_path': None,\n    'storage_document_id': None,\n    'infrastructure_document_id': 'f958db1c-b143-4709-846c-321125247e07',\n    'infrastructure': {\n        'type': 'process',\n        'env': {},\n        'labels': {},\n        'name': None,\n        'command': ['python', '-m', 'prefect.engine'],\n        'stream_output': True\n    }\n}\n</code></pre>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-from-a-deployment","title":"Create a flow run from a deployment","text":"","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-a-schedule","title":"Create a flow run with a schedule","text":"<p>If you specify a schedule for a deployment, the deployment will execute its flow automatically on that schedule as long as a Prefect server and agent are running. Prefect Cloud creates schedules flow runs automatically, and they will run on schedule if an agent is configured to pick up flow runs for the deployment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-an-event-trigger","title":"Create a flow run with an event trigger","text":"<p>deployment triggers are only available in Prefect Cloud</p> <p>Deployments can optionally take a trigger specification, which will configure an automation to run the deployment based on the presence or absence of events, and optionally pass event data into the deployment run as parameters via jinja templating.</p> <pre><code>triggers:\n  - enabled: true\n    match:\n      prefect.resource.id: prefect.flow-run.*\n    expect:\n      - prefect.flow-run.Completed\n    match_related:\n      prefect.resource.name: prefect.flow.etl-flow\n      prefect.resource.role: flow\n    parameters:\n      param_1: \"{{ event }}\"\n</code></pre> <p>When applied, this deployment will start a flow run upon the completion of the upstream flow specified in the <code>match_related</code> key, with the flow run passed in as a parameter. Triggers can be configured to respond to the presence or absence of arbitrary internal or external events. The trigger system and API are detailed in Automations.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-with-prefect-ui","title":"Create a flow run with Prefect UI","text":"<p>In the Prefect UI, you can click the Run button next to any deployment to execute an ad hoc flow run for that deployment.</p> <p>The <code>prefect deployment</code> CLI command provides commands for managing and running deployments locally.</p> Command Description <code>apply</code> Create or update a deployment from a YAML file. <code>build</code> Generate a deployment YAML from /path/to/file.py:flow_function. <code>delete</code> Delete a deployment. <code>inspect</code> View details about a deployment. <code>ls</code> View all deployments or deployments for specific flows. <code>pause-schedule</code> Pause schedule of a given deployment. <code>resume-schedule</code> Resume schedule of a given deployment. <code>run</code> Create a flow run for the given flow and deployment. <code>schedule</code> Commands for interacting with your deployment's schedules. <code>set-schedule</code> Set schedule for a given deployment. <p>Deprecated Schedule Commands</p> <p>The pause-schedule, resume-schedule, and set-schedule commands are deprecated due to the introduction of multi-schedule support for deployments. Use the new <code>prefect deployment schedule</code> command for enhanced flexibility and control over your deployment schedules.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#create-a-flow-run-in-a-python-script","title":"Create a flow run in a Python script","text":"<p>You can create a flow run from a deployment in a Python script with the <code>run_deployment</code> function.</p> <pre><code>from prefect.deployments import run_deployment\n\n\ndef main():\n    response = run_deployment(name=\"flow-name/deployment-name\")\n    print(response)\n\n\nif __name__ == \"__main__\":\n   main()\n</code></pre> <p><code>PREFECT_API_URL</code> setting for agents</p> <p>You'll need to configure agents and work pools that can create flow runs for deployments in remote environments. <code>PREFECT_API_URL</code> must be set for the environment in which your agent is running.</p> <p>If you want the agent to communicate with Prefect Cloud from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments-block-based/#examples","title":"Examples","text":"<ul> <li>How to deploy Prefect flows to AWS</li> <li>How to deploy Prefect flows to GCP</li> <li>How to deploy Prefect flows to Azure</li> <li>How to deploy Prefect flows using files stored locally</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker"]},{"location":"concepts/deployments/","title":"Deployments","text":"<p>Deployments are server-side representations of flows.  They store the crucial metadata needed for remote orchestration including when, where, and how a workflow should run. Deployments elevate workflows from functions that you must call manually to API-managed entities that can be triggered remotely.</p> <p>Here we will focus largely on the metadata that defines a deployment and how it is used.  Different ways of creating a deployment populate these fields differently.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#overview","title":"Overview","text":"<p>Every Prefect deployment references one and only one \"entrypoint\" flow (though that flow may itself call any number of subflows).  Different deployments may reference the same underlying flow, a useful pattern when developing or promoting workflow changes through staged environments.</p> <p>The complete schema that defines a deployment is as follows:</p> <pre><code>class Deployment:\n    \"\"\"\n    Structure of the schema defining a deployment\n    \"\"\"\n\n    # required defining data\n    name: str \n    flow_id: UUID\n    entrypoint: str\n    path: str = None\n\n    # workflow scheduling and parametrization\n    parameters: Optional[Dict[str, Any]] = None\n    parameter_openapi_schema: Optional[Dict[str, Any]] = None\n    schedules: list[Schedule] = None\n    paused: bool = False\n    trigger: Trigger = None\n\n    # metadata for bookkeeping\n    version: str = None\n    description: str = None\n    tags: list = None\n\n    # worker-specific fields\n    work_pool_name: str = None\n    work_queue_name: str = None\n    infra_overrides: Optional[Dict[str, Any]] = None\n    pull_steps: Optional[Dict[str, Any]] = None\n</code></pre> <p>All methods for creating Prefect deployments are interfaces for populating this schema. Let's look at each section in turn.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#required-data","title":"Required data","text":"<p>Deployments universally require both a <code>name</code> and a reference to an underlying <code>Flow</code>. In almost all instances of deployment creation, users do not need to concern themselves with the <code>flow_id</code> as most interfaces will only need the flow's name. Note that the deployment name is not required to be unique across all deployments but is required to be unique for a given flow ID. As a consequence, you will often see references to the deployment's unique identifying name <code>{FLOW_NAME}/{DEPLOYMENT_NAME}</code>. For example, triggering a run of a deployment from the Prefect CLI can be done via:</p> <pre><code>prefect deployment run my-first-flow/my-first-deployment\n</code></pre> <p>The other two fields are less obvious:</p> <ul> <li><code>path</code>: the path can generally be interpreted as the runtime working directory for the flow.  For example, if a deployment references a workflow defined within a Docker image, the <code>path</code> will be the absolute path to the parent directory where that workflow will run anytime the deployment is triggered.  This interpretation is more subtle in the case of flows defined in remote filesystems.</li> <li><code>entrypoint</code>: the entrypoint of a deployment is a relative reference to a function decorated as a flow that exists on some filesystem.  It is always specified relative to the <code>path</code>. Entrypoints use Python's standard path-to-object syntax (e.g., <code>path/to/file.py:function_name</code> or simply <code>path:object</code>).</li> </ul> <p>The entrypoint must reference the same flow as the flow ID.</p> <p>Note that Prefect requires that deployments reference flows defined within Python files. Flows defined within interactive REPLs or notebooks cannot currently be deployed as such.  They are still valid flows that will be monitored by the API and observable in the UI whenever they are run, but Prefect cannot trigger them.</p> <p>Deployments do not contain code definitions</p> <p>Deployment metadata references code that exists in potentially diverse locations within your environment. This separation of concerns means that your flow code stays within your storage and execution infrastructure and never lives on the Prefect server or database.</p> <p>This is the heart of the Prefect hybrid model: there's a boundary between your proprietary assets, such as your flow code, and the Prefect backend (including Prefect Cloud). </p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#scheduling-and-parametrization","title":"Scheduling and parametrization","text":"<p>One of the primary motivations for creating deployments of flows is to remotely schedule and trigger them. Just as flows can be called as functions with different input values, so can deployments be triggered or scheduled with different values through the use of parameters.</p> <p>The six fields here capture the necessary metadata to perform such actions:</p> <ul> <li><code>schedules</code>: a list of schedule objects. Most of the convenient interfaces for creating deployments allow users to avoid creating this object themselves. For example, when updating a deployment schedule in the UI basic information such as a cron string or interval is all that's required.</li> <li><code>trigger</code> (Cloud-only): triggers allow you to define event-based rules for running a deployment. For more information see Automations.</li> <li><code>parameter_openapi_schema</code>: an OpenAPI compatible schema that defines the types and defaults for the flow's parameters. This is used by both the UI and the backend to expose options for creating manual runs as well as type validation.</li> <li><code>parameters</code>: default values of flow parameters that this deployment will pass on each run. These can be overwritten through a trigger or when manually creating a custom run.</li> <li><code>enforce_parameter_schema</code>: a boolean flag that determines whether the API should validate the parameters passed to a flow run against the schema defined by <code>parameter_openapi_schema</code>.</li> </ul> <p>Scheduling is asynchronous and decoupled</p> <p>Because deployments are nothing more than metadata, runs can be created at anytime. Note that pausing a schedule, updating your deployment, and other actions reset your auto-scheduled runs.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#running-a-deployed-flow-from-within-python-flow-code","title":"Running a deployed flow from within Python flow code","text":"<p>Prefect provides a <code>run_deployment</code> function that can be used to schedule the run of an existing deployment when your Python code executes.</p> <pre><code>from prefect.deployments import run_deployment\n\ndef main():\n    run_deployment(name=\"my_flow_name/my_deployment_name\")\n</code></pre> <p>Run a deployment without blocking</p> <p>By default, <code>run_deployment</code> blocks until the scheduled flow run finishes executing. Pass <code>timeout=0</code> to return immediately and not block.</p> <p>If you call <code>run_deployment</code> from within a flow or task, the scheduled flow run will be linked to the calling flow run (or the calling task's flow run) as a subflow run by default.</p> <p>Subflow runs have different behavior than regular flow runs. For example, a  subflow run can't be suspended independently of its parent flow. If you'd rather not link the scheduled flow run to the calling flow or task run, you can disable this behavior by passing <code>as_subflow=False</code>:</p> <pre><code>from prefect import flow\nfrom prefect.deployments import run_deployment\n\n\n@flow\ndef my_flow():\n    # The scheduled flow run will not be linked to this flow as a subflow.\n    run_deployment(name=\"my_other_flow/my_deployment_name\", as_subflow=False)\n</code></pre> <p>The return value of <code>run_deployment</code> is a FlowRun object containing metadata about the scheduled run. You can use this object to retrieve information about the run after calling <code>run_deployment</code>:</p> <pre><code>from prefect import get_client\nfrom prefect.deployments import run_deployment\n\ndef main():\n    flow_run = run_deployment(name=\"my_flow_name/my_deployment_name\")\n    flow_run_id = flow_run.id\n\n    # If you save the flow run's ID, you can use it later to retrieve\n    # flow run metadata again, e.g. to check if it's completed.\n    async with get_client() as client:\n        flow_run = client.read_flow_run(flow_run_id)\n        print(f\"Current state of the flow run: {flow_run.state}\")\n</code></pre> <p>Using the Prefect client</p> <p>For more information on using the Prefect client to interact with Prefect's REST API, see our guide.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#versioning-and-bookkeeping","title":"Versioning and bookkeeping","text":"<p>Versions, descriptions and tags are omnipresent fields throughout Prefect that can be easy to overlook. However, putting some extra thought into how you use these fields can pay dividends down the road.</p> <ul> <li><code>version</code>: versions are always set by the client and can be any arbitrary string.  We recommend tightly coupling this field on your deployments to your software development lifecycle.  For example if you leverage <code>git</code> to manage code changes, use either a tag or commit hash in this field. If you don't set a value for the version, Prefect will compute a hash</li> <li><code>description</code>: the description field of a deployment is a place to provide rich reference material for downstream stakeholders such as intended use and parameter documentation. Markdown formatting will be rendered in the Prefect UI, allowing for section headers, links, tables, and other formatting. If not provided explicitly, Prefect will use the docstring of your flow function as a default value.</li> <li><code>tags</code>: tags are a mechanism for grouping related work together across a diverse set of objects. Tags set on a deployment will be inherited by that deployment's flow runs. These tags can then be used to filter what runs are displayed on the primary UI dashboard, allowing you to customize different views into your work. In addition, in Prefect Cloud you can easily find objects through searching by tag.</li> </ul> <p>All of these bits of metadata can be leveraged to great effect by injecting them into the processes that Prefect is orchestrating. For example you can use both run ID and versions to organize files that you produce from your workflows, or by associating your flow run's tags with the metadata of a job it orchestrates. This metadata is available during execution through Prefect runtime.</p> <p>Everything has a version</p> <p>Deployments aren't the only entity in Prefect with a version attached; both flows and tasks also have versions that can be set through their respective decorators. These versions will be sent to the API anytime the flow or task is run and thereby allow you to audit your changes across all levels.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#workers-and-work-pools","title":"Workers and Work Pools","text":"<p>Workers and work pools are an advanced deployment pattern that allow you to dynamically provision infrastructure for each flow run. In addition, the work pool job template interface allows users to create and govern opinionated interfaces to their workflow infrastructure. To do this, a deployment using workers needs to evaluate the following fields:</p> <ul> <li><code>work_pool_name</code>: the name of the work pool this deployment will be associated with. Work pool types mirror infrastructure types and therefore the decision here affects the options available for the other fields.</li> <li><code>work_queue_name</code>: if you are using work queues to either manage priority or concurrency, you can associate a deployment with a specific queue within a work pool using this field.</li> <li><code>infra_overrides</code>: often called <code>job_variables</code> within various interfaces, this field allows deployment authors to customize whatever infrastructure options have been exposed on this work pool. This field is often used for things such as Docker image names, Kubernetes annotations and limits, and environment variables.</li> <li><code>pull_steps</code>: a JSON description of steps that should be performed to retrieve flow code or configuration and prepare the runtime environment for workflow execution.</li> </ul> <p>Pull steps allow users to highly decouple their workflow architecture. For example, a common use of pull steps is to dynamically pull code from remote filesystems such as GitHub with each run of their deployment.</p> <p>For more information see the guide to deploying with a worker.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#two-approaches-to-deployments","title":"Two approaches to deployments","text":"<p>There are two primary ways to deploy flows with Prefect, differentiated by how much control Prefect has over the infrastructure in which the flows run.</p> <p>In one setup, deploying Prefect flows is analogous to deploying a webserver - users author their workflows and then start a long-running process (often within a Docker container) that is responsible for managing all of the runs for the associated deployment(s).</p> <p>In the other setup, you do a little extra up-front work to set up a work pool and a base job template that defines how individual flow runs will be submitted to infrastructure.</p> <p>Prefect provides several types of work pools corresponding to different types of infrastructure. Prefect Cloud provides a Prefect Managed work pool option that is the simplest way to run workflows remotely. A cloud-provider account, such as AWS, is not required with a Prefect Managed work pool.</p> <p>Some work pool types require a client-side worker to submit job definitions to the appropriate infrastructure with each run.</p> <p>Each of these setups can support production workloads.  The choice ultimately boils down to your use case and preferences.  Read further to decide which setup is best for your situation.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#serving-flows-on-long-lived-infrastructure","title":"Serving flows on long-lived infrastructure","text":"<p>When you have several flows running regularly, the <code>serve</code> method of the <code>Flow</code> object or the <code>serve</code> utility is a great option for managing multiple flows simultaneously.</p> <p>Once you have authored your flow and decided on its deployment settings as described above, all that's left is to run this long-running process in a location of your choosing. The process will stay in communication with the Prefect API, monitoring for work and submitting each run within an individual subprocess. Note that because runs are submitted to subprocesses, any external infrastructure configuration will need to be setup beforehand and kept associated with this process.</p> <p>This approach has many benefits:</p> <ul> <li>Users are in complete control of their infrastructure, and anywhere the \"serve\" Python process can run is a suitable deployment environment.</li> <li>It is simple to reason about.</li> <li>Creating deployments requires a minimal set of decisions.</li> <li>Iteration speed is fast.</li> </ul> <p>However, there are a few reasons you might consider running flows on dynamically provisioned infrastructure with work pools instead:</p> <ul> <li>Flows that have expensive infrastructure needs may be more costly in this setup due to the long-running process.</li> <li>Flows with heterogeneous infrastructure needs across runs will be more difficult to configure and schedule.</li> <li>Large volumes of deployments can be harder to track.</li> <li>If your internal team structure requires that deployment authors be members of a different team than the team managing infrastructure, the work pool interface may be preferred.</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/deployments/#dynamically-provisioning-infrastructure-with-work-pools","title":"Dynamically provisioning infrastructure with work pools","text":"<p>Work pools allow Prefect to exercise greater control of the infrastructure on which flows run. Options for serverless work pools allow you to scale to zero when workflows aren't running. Prefect even provides you with the ability to provision cloud infrastructure via a single CLI command, if you use a Prefect Cloud push work pool option.</p> <p>With work pools:</p> <ul> <li>You can configure and monitor infrastructure configuration within the Prefect UI.</li> <li>Infrastructure is ephemeral and dynamically provisioned.</li> <li>Prefect is more infrastructure-aware and therefore collects more event data from your infrastructure by default.</li> <li>Highly decoupled setups are possible.</li> </ul> <p>You don't have to commit to one approach</p> <p>You are not required to use only one of these approaches for your deployments. You can mix and match approaches based on the needs of each flow. Further, you can change the deployment approach for a particular flow as its needs evolve. For example, you might use workers for your expensive machine learning pipelines, but use the serve mechanics for smaller, more frequent file-processing pipelines.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","infrastructure","storage","work pool","worker","run_deployment"],"boost":2},{"location":"concepts/filesystems/","title":"Filesystems","text":"<p>A filesystem block is an object that allows you to read and write data from paths. Prefect provides multiple built-in file system types that cover a wide range of use cases. </p> <ul> <li><code>LocalFileSystem</code></li> <li><code>RemoteFileSystem</code></li> <li><code>Azure</code></li> <li><code>GitHub</code></li> <li><code>GitLab</code></li> <li><code>GCS</code></li> <li><code>S3</code></li> <li><code>SMB</code></li> </ul> <p>Additional file system types are available in Prefect Collections.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#local-filesystem","title":"Local filesystem","text":"<p>The <code>LocalFileSystem</code> block enables interaction with the files in your current development environment. </p> <p><code>LocalFileSystem</code> properties include:</p> Property Description basepath String path to the location of files on the local filesystem. Access to files outside of the base path will not be allowed. <pre><code>from prefect.filesystems import LocalFileSystem\n\nfs = LocalFileSystem(basepath=\"/foo/bar\")\n</code></pre> <p>Limited access to local file system</p> <p>Be aware that <code>LocalFileSystem</code> access is limited to the exact path provided. This file system may not be ideal for some use cases. The execution environment for your workflows may not have the same file system as the environment you are writing and deploying your code on. </p> <p>Use of this file system can limit the availability of results after a flow run has completed or prevent the code for a flow from being retrieved successfully at the start of a run.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#remote-file-system","title":"Remote file system","text":"<p>The <code>RemoteFileSystem</code> block enables interaction with arbitrary remote file systems. Under the hood, <code>RemoteFileSystem</code> uses <code>fsspec</code> and supports any file system that <code>fsspec</code> supports. </p> <p><code>RemoteFileSystem</code> properties include:</p> Property Description basepath String path to the location of files on the remote filesystem. Access to files outside of the base path will not be allowed. settings Dictionary containing extra parameters required to access the remote file system. <p>The file system is specified using a protocol:</p> <ul> <li><code>s3://my-bucket/my-folder/</code> will use S3</li> <li><code>gcs://my-bucket/my-folder/</code> will use GCS</li> <li><code>az://my-bucket/my-folder/</code> will use Azure</li> </ul> <p>For example, to use it with Amazon S3:</p> <pre><code>from prefect.filesystems import RemoteFileSystem\n\nblock = RemoteFileSystem(basepath=\"s3://my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>You may need to install additional libraries to use some remote storage types.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#remotefilesystem-examples","title":"RemoteFileSystem examples","text":"<p>How can we use <code>RemoteFileSystem</code> to store our flow code? The following is a use case where we use MinIO as a storage backend:</p> <pre><code>from prefect.filesystems import RemoteFileSystem\n\nminio_block = RemoteFileSystem(\n    basepath=\"s3://my-bucket\",\n    settings={\n        \"key\": \"MINIO_ROOT_USER\",\n        \"secret\": \"MINIO_ROOT_PASSWORD\",\n        \"client_kwargs\": {\"endpoint_url\": \"http://localhost:9000\"},\n    },\n)\nminio_block.save(\"minio\")\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#azure","title":"Azure","text":"<p>The <code>Azure</code> file system block enables interaction with Azure Datalake and Azure Blob Storage. Under the hood, the <code>Azure</code> block uses <code>adlfs</code>.</p> <p><code>Azure</code> properties include:</p> Property Description bucket_path String path to the location of files on the remote filesystem. Access to files outside of the bucket path will not be allowed. azure_storage_connection_string Azure storage connection string. azure_storage_account_name Azure storage account name. azure_storage_account_key Azure storage account key. azure_storage_tenant_id Azure storage tenant ID. azure_storage_client_id Azure storage client ID. azure_storage_client_secret Azure storage client secret. azure_storage_anon Anonymous authentication, disable to use <code>DefaultAzureCredential</code>. <p>To create a block:</p> <pre><code>from prefect.filesystems import Azure\n\nblock = Azure(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb az/dev\n</code></pre> <p>You need to install <code>adlfs</code> to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#github","title":"GitHub","text":"<p>The <code>GitHub</code> filesystem block enables interaction with GitHub repositories. This block is read-only and works with both public and private repositories.</p> <p><code>GitHub</code> properties include:</p> Property Description reference An optional reference to pin to, such as a branch name or tag. repository The URL of a GitHub repository to read from, in either HTTPS or SSH format. access_token A GitHub Personal Access Token (PAT) with <code>repo</code> scope. <p>To create a block:</p> <pre><code>from prefect.filesystems import GitHub\n\nblock = GitHub(\n    repository=\"https://github.com/my-repo/\",\n    access_token=&lt;my_access_token&gt; # only required for private repos\n)\nblock.get_directory(\"folder-in-repo\") # specify a subfolder of repo\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb github/dev -a\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#gitlabrepository","title":"GitLabRepository","text":"<p>The <code>GitLabRepository</code> block is read-only and works with private GitLab repositories.</p> <p><code>GitLabRepository</code> properties include:</p> Property Description reference An optional reference to pin to, such as a branch name or tag. repository The URL of a GitLab repository to read from, in either HTTPS or SSH format. credentials A <code>GitLabCredentials</code> block with Personal Access Token (PAT) with <code>read_repository</code> scope. <p>To create a block:</p> <pre><code>from prefect_gitlab.credentials import GitLabCredentials\nfrom prefect_gitlab.repositories import GitLabRepository\n\ngitlab_creds = GitLabCredentials(token=\"YOUR_GITLAB_ACCESS_TOKEN\")\ngitlab_repo = GitLabRepository(\n    repository=\"https://gitlab.com/yourorg/yourrepo.git\",\n    reference=\"main\",\n    credentials=gitlab_creds,\n)\ngitlab_repo.save(\"dev\")\n</code></pre> <p>To use it in a deployment (and apply):</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb gitlab-repository/dev -a\n</code></pre> <p>Note that to use this block, you need to install the <code>prefect-gitlab</code> collection.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#gcs","title":"GCS","text":"<p>The <code>GCS</code> file system block enables interaction with Google Cloud Storage. Under the hood, <code>GCS</code> uses <code>gcsfs</code>.</p> <p><code>GCS</code> properties include:</p> Property Description bucket_path A GCS bucket path service_account_info The contents of a service account keyfile as a JSON string. project The project the GCS bucket resides in. If not provided, the project will be inferred from the credentials or environment. <p>To create a block:</p> <pre><code>from prefect.filesystems import GCS\n\nblock = GCS(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb gcs/dev\n</code></pre> <p>You need to install <code>gcsfs</code>to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#s3","title":"S3","text":"<p>The <code>S3</code> file system block enables interaction with Amazon S3. Under the hood, <code>S3</code> uses <code>s3fs</code>.</p> <p><code>S3</code> properties include:</p> Property Description bucket_path An S3 bucket path aws_access_key_id AWS Access Key ID aws_secret_access_key AWS Secret Access Key <p>To create a block:</p> <pre><code>from prefect.filesystems import S3\n\nblock = S3(bucket_path=\"my-bucket/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb s3/dev\n</code></pre> <p>You need to install <code>s3fs</code>to use this block.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#smb","title":"SMB","text":"<p>The <code>SMB</code> file system block enables interaction with SMB shared network storage. Under the hood, <code>SMB</code> uses <code>smbprotocol</code>. Used to connect to Windows-based SMB shares from Linux-based Prefect flows. The SMB file system block is able to copy files, but cannot create directories.</p> <p><code>SMB</code> properties include:</p> Property Description basepath String path to the location of files on the remote filesystem. Access to files outside of the base path will not be allowed. smb_host Hostname or IP address where SMB network share is located. smb_port Port for SMB network share (defaults to 445). smb_username SMB username with read/write permissions. smb_password SMB password. <p>To create a block:</p> <pre><code>from prefect.filesystems import SMB\n\nblock = SMB(basepath=\"my-share/folder/\")\nblock.save(\"dev\")\n</code></pre> <p>To use it in a deployment:</p> <pre><code>prefect deployment build path/to/flow.py:flow_name --name deployment_name --tag dev -sb smb/dev\n</code></pre> <p>You need to install <code>smbprotocol</code> to use it.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#handling-credentials-for-cloud-object-storage-services","title":"Handling credentials for cloud object storage services","text":"<p>If you leverage <code>S3</code>, <code>GCS</code>, or <code>Azure</code> storage blocks, and you don't explicitly configure credentials on the respective storage block, those credentials will be inferred from the environment. Make sure to set those either explicitly on the block or as environment variables, configuration files, or IAM roles within both the build and runtime environment for your deployments.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#filesystem-package-dependencies","title":"Filesystem package dependencies","text":"<p>A Prefect installation and doesn't include filesystem-specific package dependencies such as <code>s3fs</code>, <code>gcsfs</code> or <code>adlfs</code>. This includes Prefect base Docker images.</p> <p>You must ensure that filesystem-specific libraries are installed in an execution environment where they will be used by flow runs.</p> <p>In Dockerized deployments using the Prefect base image, you can leverage the <code>EXTRA_PIP_PACKAGES</code> environment variable. Those dependencies will be installed at runtime within your Docker container or Kubernetes Job before the flow starts running. </p> <p>In Dockerized deployments using a custom image, you must include the filesystem-specific package dependency in your image.</p> <p>Here is an example from a deployment YAML file showing how to specify the installation of <code>s3fs</code> from into your image:</p> <pre><code>infrastructure:\n  type: docker-container\n  env:\n    EXTRA_PIP_PACKAGES: s3fs  # could be gcsfs, adlfs, etc.\n</code></pre> <p>You may specify multiple dependencies by providing a comma-delimted list.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#saving-and-loading-file-systems","title":"Saving and loading file systems","text":"<p>Configuration for a file system can be saved to the Prefect API. For example:</p> <pre><code>fs = RemoteFileSystem(basepath=\"s3://my-bucket/folder/\")\nfs.write_path(\"foo\", b\"hello\")\nfs.save(\"dev-s3\")\n</code></pre> <p>This file system can be retrieved for later use with <code>load</code>.</p> <pre><code>fs = RemoteFileSystem.load(\"dev-s3\")\nfs.read_path(\"foo\")  # b'hello'\n</code></pre>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/filesystems/#readable-and-writable-file-systems","title":"Readable and writable file systems","text":"<p>Prefect provides two abstract file system types, <code>ReadableFileSystem</code> and <code>WriteableFileSystem</code>. </p> <ul> <li>All readable file systems must implement <code>read_path</code>, which takes a file path to read content from and returns bytes. </li> <li>All writeable file systems must implement <code>write_path</code> which takes a file path and content and writes the content to the file as bytes. </li> </ul> <p>A file system may implement both of these types.</p>","tags":["filesystems","storage","deployments","LocalFileSystem","RemoteFileSystem"],"boost":0.5},{"location":"concepts/flows/","title":"Flows","text":"<p>Flows are the most central Prefect object. A flow is a container for workflow logic as-code and allows users to configure how their workflows behave. Flows are defined as Python functions, and any Python function is eligible to be a flow.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flows-overview","title":"Flows overview","text":"<p>Flows can be thought of as special types of functions. They can take inputs, perform work, and return an output. In fact, you can turn any function into a Prefect flow by adding the <code>@flow</code> decorator. When a function becomes a flow, its behavior changes, giving it the following advantages:</p> <ul> <li>Every invocation of this function is tracked and all state transitions are reported to the API, allowing observation of flow execution.</li> <li>Input arguments are automatically type checked and coerced to the appropriate types.</li> <li>Retries can be performed on failure.</li> <li>Timeouts can be enforced to prevent unintentional, long-running workflows.</li> </ul> <p>Flows also take advantage of automatic Prefect logging to capture details about flow runs such as run time and final state.</p> <p>Flows can include calls to tasks as well as to other flows, which Prefect calls \"subflows\" in this context. Flows may be defined within modules and imported for use as subflows in your flow definitions.</p> <p>Deployments elevate individual workflows from functions that you call manually to API-managed entities.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flow-runs","title":"Flow runs","text":"<p>A flow run represents a single execution of the flow.</p> <p>You can create a flow run by calling the flow manually. For example, by running a Python script or importing the flow into an interactive session and calling it.</p> <p>You can also create a flow run by:</p> <ul> <li>Using external schedulers such as <code>cron</code> to invoke a flow function</li> <li>Creating a deployment on Prefect Cloud or a locally run Prefect server.</li> <li>Creating a flow run for the deployment via a schedule, the Prefect UI, or the Prefect API.</li> </ul> <p>However you run the flow, the Prefect API monitors the flow run, capturing flow run state for observability.</p> <p>When you run a flow that contains tasks or additional flows, Prefect will track the relationship of each child run to the parent flow run.</p> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#writing-flows","title":"Writing flows","text":"<p>The <code>@flow</code> decorator is used to designate a flow:</p> <pre><code>from prefect import flow\n\n@flow\ndef my_flow():\n    return\n</code></pre> <p>There are no rigid rules for what code you include within a flow definition - all valid Python is acceptable.</p> <p>Flows are uniquely identified by name. You can provide a <code>name</code> parameter value for the flow. If you don't provide a name, Prefect uses the flow function name.</p> <pre><code>@flow(name=\"My Flow\")\ndef my_flow():\n    return\n</code></pre> <p>Flows can call tasks to allow Prefect to orchestrate and track more granular units of work:</p> <pre><code>from prefect import flow, task\n\n@task\ndef print_hello(name):\n    print(f\"Hello {name}!\")\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    print_hello(name)\n</code></pre> <p>Flows and tasks</p> <p>There's nothing stopping you from putting all of your code in a single flow function \u2014 Prefect will happily run it!</p> <p>However, organizing your workflow code into smaller flow and task units lets you take advantage of Prefect features like retries, more granular visibility into runtime state, the ability to determine final state regardless of individual task state, and more.</p> <p>In addition, if you put all of your workflow logic in a single flow function and any line of code fails, the entire flow will fail and must be retried from the beginning.  This can be avoided by breaking up the code into multiple tasks.</p> <p>You may call any number of other tasks, subflows, and even regular Python functions within your flow.  You can pass parameters to your flow function that will be used elsewhere in the workflow, and Prefect will report on the progress and final state of any invocation.</p> <p>Prefect encourages \"small tasks\" \u2014 each one should represent a single logical step of your workflow.  This allows Prefect to better contain task failures.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#flow-settings","title":"Flow settings","text":"<p>Flows allow a great deal of configuration by passing arguments to the decorator. Flows accept the following optional settings.</p> Argument Description <code>description</code> An optional string description for the flow. If not provided, the description will be pulled from the docstring for the decorated function. <code>name</code> An optional name for the flow. If not provided, the name will be inferred from the function. <code>retries</code> An optional number of times to retry on flow run failure. <code>retry_delay_seconds</code> An optional number of seconds to wait before retrying the flow after failure. This is only applicable if <code>retries</code> is nonzero. <code>flow_run_name</code> An optional name to distinguish runs of this flow; this name can be provided as a string template with the flow's parameters as variables; this name can also be provided as a function that returns a string. <code>task_runner</code> An optional task runner to use for task execution within the flow when you <code>.submit()</code> tasks. If not provided and you <code>.submit()</code> tasks, the <code>ConcurrentTaskRunner</code> will be used. <code>timeout_seconds</code> An optional number of seconds indicating a maximum runtime for the flow. If the flow exceeds this runtime, it will be marked as failed. Flow execution may continue until the next task is called. <code>validate_parameters</code> Boolean indicating whether parameters passed to flows are validated by Pydantic. Default is <code>True</code>. <code>version</code> An optional version string for the flow. If not provided, we will attempt to create a version string as a hash of the file containing the wrapped function. If the file cannot be located, the version will be null. <p>For example, you can provide a <code>name</code> value for the flow. Here we've also used the optional <code>description</code> argument and specified a non-default task runner.</p> <pre><code>from prefect import flow\nfrom prefect.task_runners import SequentialTaskRunner\n\n@flow(name=\"My Flow\",\n      description=\"My flow using SequentialTaskRunner\",\n      task_runner=SequentialTaskRunner())\ndef my_flow():\n    return\n</code></pre> <p>You can also provide the description as the docstring on the flow function.</p> <pre><code>@flow(name=\"My Flow\",\n      task_runner=SequentialTaskRunner())\ndef my_flow():\n    \"\"\"My flow using SequentialTaskRunner\"\"\"\n    return\n</code></pre> <p>You can distinguish runs of this flow by providing a <code>flow_run_name</code>. This setting accepts a string that can optionally contain templated references to the parameters of your flow. The name will be formatted using Python's standard string formatting syntax as can be seen here:</p> <pre><code>import datetime\nfrom prefect import flow\n\n@flow(flow_run_name=\"{name}-on-{date:%A}\")\ndef my_flow(name: str, date: datetime.datetime):\n    pass\n\n# creates a flow run called 'marvin-on-Thursday'\nmy_flow(name=\"marvin\", date=datetime.datetime.now(datetime.timezone.utc))\n</code></pre> <p>Additionally this setting also accepts a function that returns a string for the flow run name:</p> <pre><code>import datetime\nfrom prefect import flow\n\ndef generate_flow_run_name():\n    date = datetime.datetime.now(datetime.timezone.utc)\n\n    return f\"{date:%A}-is-a-nice-day\"\n\n@flow(flow_run_name=generate_flow_run_name)\ndef my_flow(name: str):\n    pass\n\n# creates a flow run called 'Thursday-is-a-nice-day'\nif __name__ == \"__main__\":\n    my_flow(name=\"marvin\")\n</code></pre> <p>If you need access to information about the flow, use the <code>prefect.runtime</code> module. For example:</p> <pre><code>from prefect import flow\nfrom prefect.runtime import flow_run\n\ndef generate_flow_run_name():\n    flow_name = flow_run.flow_name\n\n    parameters = flow_run.parameters\n    name = parameters[\"name\"]\n    limit = parameters[\"limit\"]\n\n    return f\"{flow_name}-with-{name}-and-{limit}\"\n\n@flow(flow_run_name=generate_flow_run_name)\ndef my_flow(name: str, limit: int = 100):\n    pass\n\n# creates a flow run called 'my-flow-with-marvin-and-100'\nif __name__ == \"__main__\":\n    my_flow(name=\"marvin\")\n</code></pre> <p>Note that <code>validate_parameters</code> will check that input values conform to the annotated types on the function. Where possible, values will be coerced into the correct type. For example, if a parameter is defined as <code>x: int</code> and \"5\" is passed, it will be resolved to <code>5</code>. If set to <code>False</code>, no validation will be performed on flow parameters.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#separating-logic-into-tasks","title":"Separating logic into tasks","text":"<p>The simplest workflow is just a <code>@flow</code> function that does all the work of the workflow.</p> <pre><code>from prefect import flow\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    print(f\"Hello {name}!\")\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>When you run this flow, you'll see output like the following:</p> <pre><code>$ python hello.py\n15:11:23.594 | INFO    | prefect.engine - Created flow run 'benevolent-donkey' for flow 'hello-world'\n15:11:23.594 | INFO    | Flow run 'benevolent-donkey' - Using task runner 'ConcurrentTaskRunner'\nHello Marvin!\n15:11:24.447 | INFO    | Flow run 'benevolent-donkey' - Finished in state Completed()\n</code></pre> <p>A better practice is to create <code>@task</code> functions that do the specific work of your flow, and use your <code>@flow</code> function as the conductor that orchestrates the flow of your application:</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>When you run this flow, you'll see the following output, which illustrates how the work is encapsulated in a task run.</p> <pre><code>$ python hello.py\n15:15:58.673 | INFO    | prefect.engine - Created flow run 'loose-wolverine' for flow 'Hello Flow'\n15:15:58.674 | INFO    | Flow run 'loose-wolverine' - Using task runner 'ConcurrentTaskRunner'\n15:15:58.973 | INFO    | Flow run 'loose-wolverine' - Created task run 'Print Hello-84f0fe0e-0' for task 'Print Hello'\nHello Marvin!\n15:15:59.037 | INFO    | Task run 'Print Hello-84f0fe0e-0' - Finished in state Completed()\n15:15:59.568 | INFO    | Flow run 'loose-wolverine' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#visualizing-flow-structure","title":"Visualizing flow structure","text":"<p>You can get a quick sense of the structure of your flow using the <code>.visualize()</code> method on your flow. Calling this method will attempt to produce a schematic diagram of your flow and tasks without actually running your flow code.</p> <p>Functions and code not inside of flows or tasks will still be run when calling <code>.visualize()</code>. This may have unintended consequences. Place your code into tasks to avoid unintended execution.</p> <p>To use the <code>visualize()</code> method, Graphviz must be installed and on your PATH. Please install Graphviz from http://www.graphviz.org/download/. And note: just installing the <code>graphviz</code> python package is not sufficient.</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@task(name=\"Print Hello Again\")\ndef print_hello_again(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    message2 = print_hello_again(message)\n\nif __name__ == \"__main__\":\n    hello_world.visualize()\n</code></pre> <p></p> <p>Prefect cannot automatically produce a schematic for dynamic workflows, such as those with loops or if/else control flow. In this case, you can provide tasks with mock return values for use in the <code>visualize()</code> call.</p> <pre><code>from prefect import flow, task\n@task(viz_return_value=[4])\ndef get_list():\n    return [1, 2, 3]\n\n@task\ndef append_one(n):\n    return n.append(6)\n\n@flow\ndef viz_return_value_tracked():\n    l = get_list()\n    for num in range(3):\n        l.append(5)\n        append_one(l)\n\nif __name__ == \"__main__\":\n    viz_return_value_tracked.visualize()\n</code></pre> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#composing-flows","title":"Composing flows","text":"<p>A subflow run is created when a flow function is called inside the execution of another flow. The primary flow is the \"parent\" flow. The flow created within the parent is the \"child\" flow or \"subflow.\"</p> <p>Subflow runs behave like normal flow runs. There is a full representation of the flow run in the backend as if it had been called separately. When a subflow starts, it will create a new task runner for tasks within the subflow. When the subflow completes, the task runner is shut down.</p> <p>Subflows will block execution of the parent flow until completion. However, asynchronous subflows can be run concurrently by using AnyIO task groups or asyncio.gather.</p> <p>Subflows differ from normal flows in that they will resolve any passed task futures into data. This allows data to be passed from the parent flow to the child easily.</p> <p>The relationship between a child and parent flow is tracked by creating a special task run in the parent flow. This task run will mirror the state of the child flow run.</p> <p>A task that represents a subflow will be annotated as such in its <code>state_details</code> via the presence of a <code>child_flow_run_id</code> field. A subflow can be identified via the presence of a <code>parent_task_run_id</code> on <code>state_details</code>.</p> <p>You can define multiple flows within the same file. Whether running locally or via a deployment, you must indicate which flow is the entrypoint for a flow run.</p> <p>Cancelling subflow runs</p> <p>Inline subflow runs, specifically those created without <code>run_deployment</code>, cannot be cancelled without cancelling their parent flow run. If you may need to cancel a subflow run independent of its parent flow run, we recommend deploying it separately and starting it using the run_deployment function.</p> <pre><code>from prefect import flow, task\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Subflow\")\ndef my_subflow(msg):\n    print(f\"Subflow says: {msg}\")\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    my_subflow(message)\n\nif __name__ == \"__main__\":\n    hello_world(\"Marvin\")\n</code></pre> <p>You can also define flows or tasks in separate modules and import them for usage. For example, here's a simple subflow module:</p> <pre><code>from prefect import flow, task\n\n@flow(name=\"Subflow\")\ndef my_subflow(msg):\n    print(f\"Subflow says: {msg}\")\n</code></pre> <p>Here's a parent flow that imports and uses <code>my_subflow()</code> as a subflow:</p> <pre><code>from prefect import flow, task\nfrom subflow import my_subflow\n\n@task(name=\"Print Hello\")\ndef print_hello(name):\n    msg = f\"Hello {name}!\"\n    print(msg)\n    return msg\n\n@flow(name=\"Hello Flow\")\ndef hello_world(name=\"world\"):\n    message = print_hello(name)\n    my_subflow(message)\n\nhello_world(\"Marvin\")\n</code></pre> <p>Running the <code>hello_world()</code> flow (in this example from the file <code>hello.py</code>) creates a flow run like this:</p> <pre><code>$ python hello.py\n15:19:21.651 | INFO    | prefect.engine - Created flow run 'daft-cougar' for flow 'Hello Flow'\n15:19:21.651 | INFO    | Flow run 'daft-cougar' - Using task runner 'ConcurrentTaskRunner'\n15:19:21.945 | INFO    | Flow run 'daft-cougar' - Created task run 'Print Hello-84f0fe0e-0' for task 'Print Hello'\nHello Marvin!\n15:19:22.055 | INFO    | Task run 'Print Hello-84f0fe0e-0' - Finished in state Completed()\n15:19:22.107 | INFO    | Flow run 'daft-cougar' - Created subflow run 'ninja-duck' for flow 'Subflow'\nSubflow says: Hello Marvin!\n15:19:22.794 | INFO    | Flow run 'ninja-duck' - Finished in state Completed()\n15:19:23.215 | INFO    | Flow run 'daft-cougar' - Finished in state Completed('All states completed.')\n</code></pre> <p>Subflows or tasks?</p> <p>In Prefect you can call tasks or subflows to do work within your workflow, including passing results from other tasks to your subflow. So a common question is:</p> <p>\"When should I use a subflow instead of a task?\"</p> <p>We recommend writing tasks that do a discrete, specific piece of work in your workflow: calling an API, performing a database operation, analyzing or transforming a data point.  Prefect tasks are well suited to parallel or distributed execution using distributed computation frameworks such as Dask or Ray.  For troubleshooting, the more granular you create your tasks, the easier it is to find and fix issues should a task fail.</p> <p>Subflows enable you to group related tasks within your workflow.  Here are some scenarios where you might choose to use a subflow rather than calling tasks individually:</p> <ul> <li>Observability: Subflows, like any other flow run, have first-class observability within the Prefect UI and Prefect Cloud. You'll see subflow status in the Flow Runs dashboard rather than having to dig down into the tasks within a specific flow run. See Final state determination for some examples of leveraging task state within flows.</li> <li>Conditional flows: If you have a group of tasks that run only under certain conditions, you can group them within a subflow and conditionally run the subflow rather than each task individually.</li> <li>Parameters: Flows have first-class support for parameterization, making it easy to run the same group of tasks in different use cases by simply passing different parameters to the subflow in which they run.</li> <li>Task runners: Subflows enable you to specify the task runner used for tasks within the flow. For example, if you want to optimize parallel execution of certain tasks with Dask, you can group them in a subflow that uses the Dask task runner. You can use a different task runner for each subflow.</li> </ul>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#parameters","title":"Parameters","text":"<p>Flows can be called with both positional and keyword arguments. These arguments are resolved at runtime into a dictionary of parameters mapping name to value. These parameters are stored by the Prefect orchestration engine on the flow run object.</p> <p>Prefect API requires keyword arguments</p> <p>When creating flow runs from the Prefect API, parameter names must be specified when overriding defaults \u2014 they cannot be positional.</p> <p>Type hints provide an easy way to enforce typing on your flow parameters via pydantic. This means any pydantic model used as a type hint within a flow will be coerced automatically into the relevant object type:</p> <pre><code>from prefect import flow\nfrom pydantic import BaseModel\n\nclass Model(BaseModel):\n    a: int\n    b: float\n    c: str\n\n@flow\ndef model_validator(model: Model):\n    print(model)\n</code></pre> <p>Note that parameter values can be provided to a flow via API using a deployment. Flow run parameters sent to the API on flow calls are coerced to a serializable form. Type hints on your flow functions provide you a way of automatically coercing JSON provided values to their appropriate Python representation.</p> <p>For example, to automatically convert something to a datetime:</p> <pre><code>from prefect import flow\nfrom datetime import datetime\n\n@flow\ndef what_day_is_it(date: datetime = None):\n    if date is None:\n        date = datetime.now(timezone.utc)\n    print(f\"It was {date.strftime('%A')} on {date.isoformat()}\")\n\nif __name__ == \"__main__\":\n    what_day_is_it(\"2021-01-01T02:00:19.180906\")\n</code></pre> <p>When you run this flow, you'll see the following output:</p> <pre><code>It was Friday on 2021-01-01T02:00:19.180906\n</code></pre> <p>Parameters are validated before a flow is run. If a flow call receives invalid parameters, a flow run is created in a <code>Failed</code> state. If a flow run for a deployment receives invalid parameters, it will move from a <code>Pending</code> state to a <code>Failed</code> without entering a <code>Running</code> state.</p> <p>Flow run parameters cannot exceed <code>512kb</code> in size</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#final-state-determination","title":"Final state determination","text":"<p>Prerequisite</p> <p>Read the documentation about states before proceeding with this section.</p> <p>The final state of the flow is determined by its return value. The following rules apply:</p> <ul> <li>If an exception is raised directly in the flow function, the flow run is marked as failed.</li> <li>If the flow does not return a value (or returns <code>None</code>), its state is determined by the states of all of the tasks and subflows within it.</li> <li>If any task run or subflow run failed, then the final flow run state is marked as <code>FAILED</code>.</li> <li>If any task run was cancelled, then the final flow run state is marked as <code>CANCELLED</code>.</li> <li>If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.</li> <li>If the flow run returns any other object, then it is marked as completed.</li> </ul> <p>The following examples illustrate each of these cases:</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#raise-an-exception","title":"Raise an exception","text":"<p>If an exception is raised within the flow function, the flow is immediately marked as failed.</p> <pre><code>from prefect import flow\n\n@flow\ndef always_fails_flow():\n    raise ValueError(\"This flow immediately fails\")\n\nif __name__ == \"__main__\":\n    always_fails_flow()\n</code></pre> <p>Running this flow produces the following result:</p> <pre><code>22:22:36.864 | INFO    | prefect.engine - Created flow run 'acrid-tuatara' for flow 'always-fails-flow'\n22:22:36.864 | INFO    | Flow run 'acrid-tuatara' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n22:22:37.060 | ERROR   | Flow run 'acrid-tuatara' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: This flow immediately fails\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-none","title":"Return <code>none</code>","text":"<p>A flow with no return statement is determined by the state of all of its task runs.</p> <pre><code>from prefect import flow, task\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_fails_flow():\n    always_fails_task.submit().result(raise_on_failure=False)\n    always_succeeds_task()\n\nif __name__ == \"__main__\":\n    always_fails_flow()\n</code></pre> <p>Running this flow produces the following result:</p> <pre><code>18:32:05.345 | INFO    | prefect.engine - Created flow run 'auburn-lionfish' for flow 'always-fails-flow'\n18:32:05.346 | INFO    | Flow run 'auburn-lionfish' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:32:05.582 | INFO    | Flow run 'auburn-lionfish' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:32:05.582 | INFO    | Flow run 'auburn-lionfish' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:32:05.610 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n18:32:05.638 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:32:05.658 | INFO    | Flow run 'auburn-lionfish' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:32:05.659 | INFO    | Flow run 'auburn-lionfish' - Executing 'always_succeeds_task-9c27db32-0' immediately...\nI'm fail safe!\n18:32:05.703 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:32:05.730 | ERROR   | Flow run 'auburn-lionfish' - Finished in state Failed('1/2 states failed.')\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-a-future","title":"Return a future","text":"<p>If a flow returns one or more futures, the final state is determined based on the underlying states.</p> <pre><code>from prefect import flow, task\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_succeeds_flow():\n    x = always_fails_task.submit().result(raise_on_failure=False)\n    y = always_succeeds_task.submit(wait_for=[x])\n    return y\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result \u2014 it succeeds because it returns the future of the task that succeeds:</p> <pre><code>18:35:24.965 | INFO    | prefect.engine - Created flow run 'whispering-guan' for flow 'always-succeeds-flow'\n18:35:24.965 | INFO    | Flow run 'whispering-guan' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:35:25.204 | INFO    | Flow run 'whispering-guan' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:35:25.205 | INFO    | Flow run 'whispering-guan' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:35:25.232 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\n18:35:25.265 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:35:25.289 | INFO    | Flow run 'whispering-guan' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:35:25.289 | INFO    | Flow run 'whispering-guan' - Submitted task run 'always_succeeds_task-9c27db32-0' for execution.\nI'm fail safe!\n18:35:25.335 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:35:25.362 | INFO    | Flow run 'whispering-guan' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-multiple-states-or-futures","title":"Return multiple states or futures","text":"<p>If a flow returns a mix of futures and states, the final state is determined by resolving all futures to states, then determining if any of the states are not <code>COMPLETED</code>.</p> <pre><code>from prefect import task, flow\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I am bad task\")\n\n@task\ndef always_succeeds_task():\n    return \"foo\"\n\n@flow\ndef always_succeeds_flow():\n    return \"bar\"\n\n@flow\ndef always_fails_flow():\n    x = always_fails_task()\n    y = always_succeeds_task()\n    z = always_succeeds_flow()\n    return x, y, z\n</code></pre> <p>Running this flow produces the following result. It fails because one of the three returned futures failed. Note that the final state is <code>Failed</code>, but the states of each of the returned futures is included in the flow state:</p> <pre><code>20:57:51.547 | INFO    | prefect.engine - Created flow run 'impartial-gorilla' for flow 'always-fails-flow'\n20:57:51.548 | INFO    | Flow run 'impartial-gorilla' - Using task runner 'ConcurrentTaskRunner'\n20:57:51.645 | INFO    | Flow run 'impartial-gorilla' - Created task run 'always_fails_task-58ea43a6-0' for task 'always_fails_task'\n20:57:51.686 | INFO    | Flow run 'impartial-gorilla' - Created task run 'always_succeeds_task-c9014725-0' for task 'always_succeeds_task'\n20:57:51.727 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: I am bad task\n20:57:51.787 | INFO    | Task run 'always_succeeds_task-c9014725-0' - Finished in state Completed()\n20:57:51.808 | INFO    | Flow run 'impartial-gorilla' - Created subflow run 'unbiased-firefly' for flow 'always-succeeds-flow'\n20:57:51.884 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Finished in state Failed('Task run encountered an exception.')\n20:57:52.438 | INFO    | Flow run 'unbiased-firefly' - Finished in state Completed()\n20:57:52.811 | ERROR   | Flow run 'impartial-gorilla' - Finished in state Failed('1/3 states failed.')\nFailed(message='1/3 states failed.', type=FAILED, result=(Failed(message='Task run encountered an exception.', type=FAILED, result=ValueError('I am bad task'), task_run_id=5fd4c697-7c4c-440d-8ebc-dd9c5bbf2245), Completed(message=None, type=COMPLETED, result='foo', task_run_id=df9b6256-f8ac-457c-ba69-0638ac9b9367), Completed(message=None, type=COMPLETED, result='bar', task_run_id=cfdbf4f1-dccd-4816-8d0f-128750017d0c)), flow_run_id=6d2ec094-001a-4cb0-a24e-d2051db6318d)\n</code></pre> <p>Returning multiple states</p> <p>When returning multiple states, they must be contained in a <code>set</code>, <code>list</code>, or <code>tuple</code>. If other collection types are used, the result of the contained states will not be checked.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-a-manual-state","title":"Return a manual state","text":"<p>If a flow returns a manually created state, the final state is determined based on the return value.</p> <pre><code>from prefect import task, flow\nfrom prefect.states import Completed, Failed\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@task\ndef always_succeeds_task():\n    print(\"I'm fail safe!\")\n    return \"success\"\n\n@flow\ndef always_succeeds_flow():\n    x = always_fails_task.submit()\n    y = always_succeeds_task.submit()\n    if y.result() == \"success\":\n        return Completed(message=\"I am happy with this result\")\n    else:\n        return Failed(message=\"How did this happen!?\")\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result.</p> <pre><code>18:37:42.844 | INFO    | prefect.engine - Created flow run 'lavender-elk' for flow 'always-succeeds-flow'\n18:37:42.845 | INFO    | Flow run 'lavender-elk' - Starting 'ConcurrentTaskRunner'; submitted tasks will be run concurrently...\n18:37:43.125 | INFO    | Flow run 'lavender-elk' - Created task run 'always_fails_task-96e4be14-0' for task 'always_fails_task'\n18:37:43.126 | INFO    | Flow run 'lavender-elk' - Submitted task run 'always_fails_task-96e4be14-0' for execution.\n18:37:43.162 | INFO    | Flow run 'lavender-elk' - Created task run 'always_succeeds_task-9c27db32-0' for task 'always_succeeds_task'\n18:37:43.163 | INFO    | Flow run 'lavender-elk' - Submitted task run 'always_succeeds_task-9c27db32-0' for execution.\n18:37:43.175 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Encountered exception during execution:\nTraceback (most recent call last):\n  ...\nValueError: I fail successfully\nI'm fail safe!\n18:37:43.217 | ERROR   | Task run 'always_fails_task-96e4be14-0' - Finished in state Failed('Task run encountered an exception.')\n18:37:43.236 | INFO    | Task run 'always_succeeds_task-9c27db32-0' - Finished in state Completed()\n18:37:43.264 | INFO    | Flow run 'lavender-elk' - Finished in state Completed('I am happy with this result')\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#return-an-object","title":"Return an object","text":"<p>If the flow run returns any other object, then it is marked as completed.</p> <pre><code>from prefect import task, flow\n\n@task\ndef always_fails_task():\n    raise ValueError(\"I fail successfully\")\n\n@flow\ndef always_succeeds_flow():\n    always_fails_task().submit()\n    return \"foo\"\n\nif __name__ == \"__main__\":\n    always_succeeds_flow()\n</code></pre> <p>Running this flow produces the following result.</p> <pre><code>21:02:45.715 | INFO    | prefect.engine - Created flow run 'sparkling-pony' for flow 'always-succeeds-flow'\n21:02:45.715 | INFO    | Flow run 'sparkling-pony' - Using task runner 'ConcurrentTaskRunner'\n21:02:45.816 | INFO    | Flow run 'sparkling-pony' - Created task run 'always_fails_task-58ea43a6-0' for task 'always_fails_task'\n21:02:45.853 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Encountered exception during execution:\nTraceback (most recent call last):...\nValueError: I am bad task\n21:02:45.879 | ERROR   | Task run 'always_fails_task-58ea43a6-0' - Finished in state Failed('Task run encountered an exception.')\n21:02:46.593 | INFO    | Flow run 'sparkling-pony' - Finished in state Completed()\nCompleted(message=None, type=COMPLETED, result='foo', flow_run_id=7240e6f5-f0a8-4e00-9440-a7b33fb51153)\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#serving-a-flow","title":"Serving a flow","text":"<p>The simplest way to create a deployment for your flow is by calling its <code>serve</code> method. This method creates a deployment for the flow and starts a long-running process that monitors for work from the Prefect server. When work is found, it is executed within its own isolated subprocess.</p> hello_world.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef hello_world(name: str = \"world\", goodbye: bool = False):\n    print(f\"Hello {name} from Prefect! \ud83e\udd17\")\n\n    if goodbye:\n        print(f\"Goodbye {name}!\")\n\n\nif __name__ == \"__main__\":\n    # creates a deployment and stays running to monitor for work instructions generated on the server\n\n    hello_world.serve(name=\"my-first-deployment\",\n                      tags=[\"onboarding\"],\n                      parameters={\"goodbye\": True},\n                      interval=60)\n</code></pre> <p>This interface provides all of the configuration needed for a deployment with no strong infrastructure requirements:</p> <ul> <li>schedules</li> <li>event triggers</li> <li>metadata such as tags and description</li> <li>default parameter values</li> </ul> <p>Schedules are auto-paused on shutdown</p> <p>By default, stopping the process running <code>flow.serve</code> will pause the schedule for the deployment (if it has one). When running this in environments where restarts are expected use the <code>pause_on_shutdown=False</code> flag to prevent this behavior:</p> <pre><code>if __name__ == \"__main__\":\n    hello_world.serve(name=\"my-first-deployment\",\n                      tags=[\"onboarding\"],\n                      parameters={\"goodbye\": True},\n                      pause_on_shutdown=False,\n                      interval=60)\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#serving-multiple-flows-at-once","title":"Serving multiple flows at once","text":"<p>You can take this further and serve multiple flows with the same process using the <code>serve</code> utility along with the <code>to_deployment</code> method of flows:</p> <pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n    serve(slow_deploy, fast_deploy)\n</code></pre> <p>The behavior and interfaces are identical to the single flow case.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#retrieve-a-flow-from-remote-storage","title":"Retrieve a flow from remote storage","text":"<p>Flows can be retrieved from remote storage using the <code>flow.from_source</code> method.</p> <p><code>flow.from_source</code> accepts a git repository URL  and an entrypoint pointing to the flow to load from the repository:</p> load_from_url.py<pre><code>from prefect import flow\n\nmy_flow = flow.from_source(\n    source=\"https://github.com/PrefectHQ/prefect.git\",\n    entrypoint=\"flows/hello_world.py:hello\"\n)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <pre><code>16:40:33.818 | INFO    | prefect.engine - Created flow run 'muscular-perch' for flow 'hello'\n16:40:34.048 | INFO    | Flow run 'muscular-perch' - Hello world!\n16:40:34.706 | INFO    | Flow run 'muscular-perch' - Finished in state Completed()\n</code></pre> <p>A flow entrypoint is the path to the file the flow is located in and the name of the flow function separated by a colon.</p> <p>If you need additional configuration, such as specifying a private repository, you can provide a <code>GitRepository</code> instead of URL:</p> load_from_storage.py<pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nmy_flow = flow.from_source(\n    source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        branch=\"dev\",\n        credentials={\n            \"access_token\": Secret.load(\"github-access-token\").get()\n        }\n    ),\n    entrypoint=\"flows.py:my_flow\"\n)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>You can serve loaded flows</p> <p>Flows loaded from remote storage can be served using the same <code>serve</code> method as local flows:</p> serve_loaded_flow.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/org/repo.git\",\n        entrypoint=\"flows.py:my_flow\"\n    ).serve(name=\"my-deployment\")\n</code></pre> <p>When you serve a flow loaded from remote storage, the serving process will periodically poll your remote storage for updates to the flow's code.  This pattern allows you to update your flow code without restarting the serving process.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#pausing-or-suspending-a-flow-run","title":"Pausing or suspending a flow run","text":"<p>Prefect provides you with the ability to halt a flow run with two functions that are similar, but slightly different. When a flow run is paused, code execution is stopped and the process continues to run. When a flow run is suspended, code execution is stopped and so is the process.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#pausing-a-flow-run","title":"Pausing a flow run","text":"<p>Prefect enables pausing an in-progress flow run for manual approval. Prefect exposes this functionality via the <code>pause_flow_run</code> and <code>resume_flow_run</code> functions.</p> <p>Timeouts</p> <p>Paused flow runs time out after one hour by default. After the timeout, the flow run will fail with a message saying it paused and never resumed. You can specify a different timeout period in seconds using the <code>timeout</code> parameter.</p> <p>Most simply, <code>pause_flow_run</code> can be called inside a flow:</p> <pre><code>from prefect import task, flow, pause_flow_run, resume_flow_run\n\n@task\nasync def marvin_setup():\n    return \"a raft of ducks walk into a bar...\"\n\n\n@task\nasync def marvin_punchline():\n    return \"it's a wonder none of them ducked!\"\n\n\n@flow\nasync def inspiring_joke():\n    await marvin_setup()\n    await pause_flow_run(timeout=600)  # pauses for 10 minutes\n    await marvin_punchline()\n</code></pre> <p>You can also implement conditional pauses:</p> <pre><code>from prefect import task, flow, pause_flow_run\n\n@task\ndef task_one():\n    for i in range(3):\n        sleep(1)\n        print(i)\n\n@flow(log_prints=True)\ndef my_flow():\n    terminal_state = task_one.submit(return_state=True)\n    if terminal_state.type == StateType.COMPLETED:\n        print(\"Task one succeeded! Pausing flow run..\")\n        pause_flow_run(timeout=2) \n    else:\n        print(\"Task one failed. Skipping pause flow run..\")\n</code></pre> <p>Calling this flow will block code execution after the first task and wait for resumption to deliver the punchline.</p> <pre><code>await inspiring_joke()\n&gt; \"a raft of ducks walk into a bar...\"\n</code></pre> <p>Paused flow runs can be resumed by clicking the Resume button in the Prefect UI or calling the <code>resume_flow_run</code> utility via client code.</p> <pre><code>resume_flow_run(FLOW_RUN_ID)\n</code></pre> <p>The paused flow run will then finish!</p> <pre><code>&gt; \"it's a wonder none of them ducked!\"\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#suspending-a-flow-run","title":"Suspending a flow run","text":"<p>Similar to pausing a flow run, Prefect enables suspending an in-progress flow run.</p> <p>The difference between pausing and suspending a flow run</p> <p>There is an important difference between pausing and suspending a flow run. When you pause a flow run, the flow code is still running but is blocked until someone resumes the flow. This is not the case with suspending a flow run! When you suspend a flow run, the flow exits completely and the infrastructure running it (e.g., a Kubernetes Job) tears down.</p> <p>This means that you can suspend flow runs to save costs instead of paying for long-running infrastructure.  However, when the flow run resumes, the flow code will execute again from the beginning of the flow, so you should use tasks and task caching to avoid recomputing expensive operations.</p> <p>Prefect exposes this functionality via the <code>suspend_flow_run</code> and <code>resume_flow_run</code> functions, as well as the Prefect UI.</p> <p>When called inside of a flow <code>suspend_flow_run</code> will immediately suspend execution of the flow run. The flow run will be marked as <code>Suspended</code> and will not be resumed until <code>resume_flow_run</code> is called.</p> <p>Timeouts</p> <p>Suspended flow runs time out after one hour by default. After the timeout, the flow run will fail with a message saying it suspended and never resumed. You can specify a different timeout period in seconds using the <code>timeout</code> parameter or pass <code>timeout=None</code> for no timeout.</p> <p>Here is an example of a flow that does not block flow execution while paused. This flow will exit after one task, and will be rescheduled upon resuming. The stored result of the first task is retrieved instead of being rerun.</p> <pre><code>from prefect import flow, pause_flow_run, task\n\n@task(persist_result=True)\ndef foo():\n    return 42\n\n@flow(persist_result=True)\ndef noblock_pausing():\n    x = foo.submit()\n    pause_flow_run(timeout=30, reschedule=True)\n    y = foo.submit()\n    z = foo(wait_for=[x])\n    alpha = foo(wait_for=[y])\n    omega = foo(wait_for=[x, y])\n</code></pre> <p>Flow runs can be suspended out-of-process by calling <code>suspend_flow_run(flow_run_id=&lt;ID&gt;)</code> or selecting the Suspend button in the Prefect UI or Prefect Cloud.</p> <p>Suspended flow runs can be resumed by clicking the Resume button in the Prefect UI or calling the <code>resume_flow_run</code> utility via client code.</p> <pre><code>resume_flow_run(FLOW_RUN_ID)\n</code></pre> <p>Subflows can't be suspended independently of their parent run</p> <p>You can't suspend a subflow run independently of its parent flow run.</p> <p>If you use a flow to schedule a flow run with <code>run_deployment</code>, the scheduled flow run will be linked to the calling flow as a subflow run by default. This means you won't be able to suspend the scheduled flow run independently of the calling flow. Call <code>run_deployment</code> with <code>as_subflow=False</code> to disable this linking if you need to be able to suspend the scheduled flow run independently of the calling flow.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#waiting-for-input-when-pausing-or-suspending-a-flow-run","title":"Waiting for input when pausing or suspending a flow run","text":"<p>Experimental</p> <p>The <code>wait_for_input</code> parameter used in the <code>pause_flow_run</code> or <code>suspend_flow_run</code> functions is an experimental feature. The interface or behavior of this feature may change without warning in future releases.</p> <p>If you encounter any issues, please let us know in Slack or with a Github issue.</p> <p>When pausing or suspending a flow run you may want to wait for input from a user. Prefect provides a way to do this by leveraging the <code>pause_flow_run</code> and <code>suspend_flow_run</code> functions. These functions accept a <code>wait_for_input</code> argument, the value of which should be a subclass of <code>prefect.input.RunInput</code>, a pydantic model. When resuming the flow run, users are required to provide data for this model. Upon successful validation, the flow run resumes, and the return value of the <code>pause_flow_run</code> or <code>suspend_flow_run</code> is an instance of the model containing the provided data.</p> <p>Here is an example of a flow that pauses and waits for input from a user:</p> <pre><code>from prefect import flow, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass UserNameInput(RunInput):\n    name: str\n\n\n@flow(log_prints=True)\nasync def greet_user():\n    user_input = await pause_flow_run(\n        wait_for_input=UserNameInput\n    )\n\n    print(f\"Hello, {user_input.name}!\")\n</code></pre> <p>Running this flow will create a flow run. The flow run will advance until code execution reaches <code>pause_flow_run</code>, at which point it will move into a <code>Paused</code> state. Execution will block and wait for resumption.</p> <p>When resuming the flow run, users will be prompted to provide a value for the <code>name</code> field of the <code>UserNameInput</code> model. Upon successful validation, the flow run will resume, and the return value of the <code>pause_flow_run</code> will be an instance of the <code>UserNameInput</code> model containing the provided data.</p> <p>For more in-depth information on receiving input from users when pausing and suspending flow runs, see the Creating interactive workflows guide.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#canceling-a-flow-run","title":"Canceling a flow run","text":"<p>You may cancel a scheduled or in-progress flow run from the CLI, UI, REST API, or Python client.</p> <p>When cancellation is requested, the flow run is moved to a \"Cancelling\" state. If the deployment is a work pool-based deployemnt with a worker, then the worker monitors the state of flow runs and detects that cancellation has been requested. The worker then sends a signal to the flow run infrastructure, requesting termination of the run. If the run does not terminate after a grace period (default of 30 seconds), the infrastructure will be killed, ensuring the flow run exits.</p> <p>A deployment is required</p> <p>Flow run cancellation requires the flow run to be associated with a deployment. A monitoring process must be running to enforce the cancellation. Inline subflow runs, i.e. those created without <code>run_deployment</code>, cannot be cancelled without cancelling the parent flow run. If you may need to cancel a subflow run independent of its parent flow run, we recommend deploying it separately and starting it using the run_deployment function.</p> <p>Cancellation is robust to restarts of Prefect workers. To enable this, we attach metadata about the created infrastructure to the flow run. Internally, this is referred to as the <code>infrastructure_pid</code> or infrastructure identifier. Generally, this is composed of two parts:</p> <ol> <li>Scope: identifying where the infrastructure is running.</li> <li>ID: a unique identifier for the infrastructure within the scope.</li> </ol> <p>The scope is used to ensure that Prefect does not kill the wrong infrastructure. For example, workers running on multiple machines may have overlapping process IDs but should not have a matching scope.</p> <p>The identifiers for infrastructure types:</p> <ul> <li>Processes: The machine hostname and the PID.</li> <li>Docker Containers: The Docker API URL and container ID.</li> <li>Kubernetes Jobs: The Kubernetes cluster name and the job name.</li> </ul> <p>While the cancellation process is robust, there are a few issues than can occur:</p> <ul> <li>If the infrastructure block for the flow run has been removed or altered, cancellation may not work.</li> <li>If the infrastructure block for the flow run does not have support for cancellation, cancellation will not work.</li> <li>If the identifier scope does not match when attempting to cancel a flow run the worker will be unable to cancel the flow run. Another worker may attempt cancellation.</li> <li>If the infrastructure associated with the run cannot be found or has already been killed, the worker will mark the flow run as cancelled.</li> <li>If the <code>infrastructre_pid</code> is missing from the flow run will be marked as cancelled but cancellation cannot be enforced.</li> <li>If the worker runs into an unexpected error during cancellation the flow run may or may not be cancelled depending on where the error occurred. The worker will try again to cancel the flow run. Another worker may attempt cancellation.</li> </ul> <p>Enhanced cancellation</p> <p>We are working on improving cases where cancellation can fail. You can try the improved cancellation experience by enabling the <code>PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION</code> setting on your worker or agents:</p> <p> <pre><code>prefect config set PREFECT_EXPERIMENTAL_ENABLE_ENHANCED_CANCELLATION=True\n</code></pre> </p> <p>If you encounter any issues, please let us know in Slack or with a Github issue.</p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#cancel-via-the-cli","title":"Cancel via the CLI","text":"<p>From the command line in your execution environment, you can cancel a flow run by using the <code>prefect flow-run cancel</code> CLI command, passing the ID of the flow run.</p> <pre><code>prefect flow-run cancel 'a55a4804-9e3c-4042-8b59-b3b6b7618736'\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#cancel-via-the-ui","title":"Cancel via the UI","text":"<p>From the UI you can cancel a flow run by navigating to the flow run's detail page and clicking the <code>Cancel</code> button in the upper right corner.</p> <p></p>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/flows/#timeouts","title":"Timeouts","text":"<p>Flow timeouts are used to prevent unintentional long-running flows. When the duration of execution for a flow exceeds the duration specified in the timeout, a timeout exception will be raised and the flow will be marked as failed. In the UI, the flow will be visibly designated as <code>TimedOut</code>.</p> <p>Timeout durations are specified using the <code>timeout_seconds</code> keyword argument.</p> <pre><code>from prefect import flow\nimport time\n\n@flow(timeout_seconds=1, log_prints=True)\ndef show_timeouts():\n    print(\"I will execute\")\n    time.sleep(5)\n    print(\"I will not execute\")\n</code></pre>","tags":["flows","subflows","workflows","scripts","parameters","states","final state"],"boost":2},{"location":"concepts/infrastructure/","title":"Infrastructure","text":"<p>Workers are recommended</p> <p>Infrastructure blocks are part of the agent based deployment model. Work Pools and Workers simplify the specification of each flow's infrastructure and runtime environment. If you have existing agents, you can upgrade from agents to workers to significantly enhance the experience of deploying flows.</p> <p>Users may specify an infrastructure block when creating a deployment. This block will be used to specify infrastructure for flow runs created by the deployment at runtime.</p> <p>Infrastructure can only be used with a deployment. When you run a flow directly by calling the flow yourself, you are responsible for the environment in which the flow executes.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#infrastructure-overview","title":"Infrastructure overview","text":"<p>Prefect uses infrastructure to create the environment for a user's flow to execute.</p> <p>Infrastructure is attached to a deployment and is propagated to flow runs created for that deployment. Infrastructure is deserialized by the agent and it has two jobs:</p> <ul> <li>Create execution environment infrastructure for the flow run.</li> <li>Run a Python command to start the <code>prefect.engine</code> in the infrastructure, which retrieves the flow from storage and executes the flow.</li> </ul> <p>The engine acquires and calls the flow. Infrastructure doesn't know anything about how the flow is stored, it's just passing a flow run ID to the engine.</p> <p>Infrastructure is specific to the environments in which flows will run. Prefect currently provides the following infrastructure types:</p> <ul> <li><code>Process</code> runs flows in a local subprocess.</li> <li><code>DockerContainer</code> runs flows in a Docker container.</li> <li><code>KubernetesJob</code> runs flows in a Kubernetes Job.</li> <li><code>ECSTask</code> runs flows in an Amazon ECS Task.</li> <li><code>Cloud Run</code> runs flows in a Google Cloud Run Job.</li> <li><code>Container Instance</code> runs flows in an Azure Container Instance.</li> </ul> <p>What about tasks?</p> <p>Flows and tasks can both use configuration objects to manage the environment in which code runs.</p> <p>Flows use infrastructure.</p> <p>Tasks use task runners. For more on how task runners work, see Task Runners.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#using-infrastructure","title":"Using infrastructure","text":"<p>You may create customized infrastructure blocks through the Prefect UI or Prefect Cloud Blocks page or create them in code and save them to the API using the blocks <code>.save()</code> method.</p> <p>Once created, there are two distinct ways to use infrastructure in a deployment:</p> <ul> <li>Starting with Prefect defaults \u2014 this is what happens when you pass  the <code>-i</code> or <code>--infra</code> flag and provide a type when building deployment files.</li> <li>Pre-configure infrastructure settings as blocks and base your deployment infrastructure on those settings \u2014 by passing <code>-ib</code> or <code>--infra-block</code> and a block slug when building deployment files.</li> </ul> <p>For example, when creating your deployment files, the supported Prefect infrastrucure types are:</p> <ul> <li><code>process</code></li> <li><code>docker-container</code></li> <li><code>kubernetes-job</code></li> <li><code>ecs-task</code></li> <li><code>cloud-run-job</code></li> <li><code>container-instance-job</code></li> </ul> <pre><code>$ prefect deployment build ./my_flow.py:my_flow -n my-flow-deployment -t test -i docker-container -sb s3/my-bucket --override env.EXTRA_PIP_PACKAGES=s3fs\nFound flow 'my-flow'\nSuccessfully uploaded 2 files to s3://bucket-full-of-sunshine\nDeployment YAML created at '/Users/terry/test/flows/infra/deployment.yaml'.\n</code></pre> <p>In this example we specify the <code>DockerContainer</code> infrastructure in addition to a preconfigured AWS S3 bucket storage block.</p> <p>The default deployment YAML filename may be edited as needed to add an infrastructure type or infrastructure settings.</p> <pre><code>###\n### A complete description of a Prefect Deployment for flow 'my-flow'\n###\nname: my-flow-deployment\ndescription: null\nversion: e29de5d01b06d61b4e321d40f34a480c\n# The work queue that will handle this deployment's runs\nwork_queue_name: default\nwork_pool_name: default-agent-pool\ntags:\n- test\nparameters: {}\nschedules: []\npaused: true\ninfra_overrides:\n  env.EXTRA_PIP_PACKAGES: s3fs\ninfrastructure:\n  type: docker-container\n  env: {}\n  labels: {}\n  name: null\n  command:\n  - python\n  - -m\n  - prefect.engine\n  image: prefecthq/prefect:2-latest\n  image_pull_policy: null\n  networks: []\n  network_mode: null\n  auto_remove: false\n  volumes: []\n  stream_output: true\n  memswap_limit: null\n  mem_limit: null\n  privileged: false\n  block_type_slug: docker-container\n  _block_type_slug: docker-container\n\n###\n### DO NOT EDIT BELOW THIS LINE\n###\nflow_name: my-flow\nmanifest_path: my_flow-manifest.json\nstorage:\n  bucket_path: bucket-full-of-sunshine\n  aws_access_key_id: '**********'\n  aws_secret_access_key: '**********'\n  _is_anonymous: true\n  _block_document_name: anonymous-xxxxxxxx-f1ff-4265-b55c-6353a6d65333\n  _block_document_id: xxxxxxxx-06c2-4c3c-a505-4a8db0147011\n  block_type_slug: s3\n  _block_type_slug: s3\npath: ''\nentrypoint: my_flow.py:my-flow\nparameter_openapi_schema:\n  title: Parameters\n  type: object\n  properties: {}\n  required: null\n  definitions: null\ntimestamp: '2023-02-08T23:00:14.974642+00:00'\n</code></pre> <p>Editing deployment YAML</p> <p>Note the big DO NOT EDIT comment in the deployment YAML: In practice, anything above this block can be freely edited before running <code>prefect deployment apply</code> to create the deployment on the API.</p> <p>Once the deployment exists, any flow runs that this deployment starts will use <code>DockerContainer</code> infrastructure.</p> <p>You can also create custom infrastructure blocks \u2014 either in the Prefect UI for in code via the API \u2014 and use the settings in the block to configure your infastructure. For example, here we specify settings for Kubernetes infrastructure in a block named <code>k8sdev</code>.</p> <pre><code>from prefect.infrastructure import KubernetesJob, KubernetesImagePullPolicy\n\nk8s_job = KubernetesJob(\n    namespace=\"dev\",\n    image=\"prefecthq/prefect:2.0.0-python3.9\",\n    image_pull_policy=KubernetesImagePullPolicy.IF_NOT_PRESENT,\n)\nk8s_job.save(\"k8sdev\")\n</code></pre> <p>Now we can apply the infrastrucure type and settings in the block by specifying the block slug <code>kubernetes-job/k8sdev</code> as the infrastructure type when building a deployment:</p> <pre><code>prefect deployment build flows/k8s_example.py:k8s_flow --name k8sdev --tag k8s -sb s3/dev -ib kubernetes-job/k8sdev\n</code></pre> <p>See Deployments for more information about deployment build options.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#configuring-infrastructure","title":"Configuring infrastructure","text":"<p>Every infrastrcture type has type-specific options.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#process","title":"Process","text":"<p><code>Process</code> infrastructure runs a command in a new process.</p> <p>Current environment variables and Prefect settings will be included in the created process. Configured environment variables will override any current environment variables.</p> <p><code>Process</code> supports the following settings:</p> Attributes Description command A list of strings specifying the command to start the flow run. In most cases you should not override this. env Environment variables to set for the new process. labels Labels for the process. Labels are for metadata purposes only and cannot be attached to the process itself. name A name for the process. For display purposes only.","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#dockercontainer","title":"DockerContainer","text":"<p><code>DockerContainer</code> infrastructure  executes flow runs in a container.</p> <p>Requirements for <code>DockerContainer</code>:</p> <ul> <li>Docker Engine must be available.</li> <li>You must configure remote Storage. Local storage is not supported for Docker.</li> <li>The API must be available from within the flow run container. To facilitate connections to locally hosted APIs, <code>localhost</code> and <code>127.0.0.1</code> will be replaced with <code>host.docker.internal</code>.</li> <li>The ephemeral Prefect API won't work with Docker and Kubernetes. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> </ul> <p><code>DockerContainer</code> supports the following settings:</p> Attributes Description auto_remove Bool indicating whether the container will be removed on completion. If False, the container will remain after exit for inspection. command A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this. env Environment variables to set for the container. image An optional string specifying the name of a Docker image to use. Defaults to the Prefect image. If the image is stored anywhere other than a public Docker Hub registry, use a corresponding registry block, e.g. <code>DockerRegistry</code> or ensure otherwise that your execution layer is authenticated to pull the image from the image registry. image_pull_policy Specifies if the image should be pulled. One of 'ALWAYS', 'NEVER', 'IF_NOT_PRESENT'. image_registry A <code>DockerRegistry</code> block containing credentials to use if <code>image</code> is stored in a private image registry. labels An optional dictionary of labels, mapping name to value. name An optional name for the container. networks An optional list of strings specifying Docker networks to connect the container to. network_mode Set the network mode for the created container. Defaults to 'host' if a local API url is detected, otherwise the Docker default of 'bridge' is used. If 'networks' is set, this cannot be set. stream_output Bool indicating whether to stream output from the subprocess to local standard output. volumes An optional list of volume mount strings in the format of \"local_path:container_path\". <p>Prefect automatically sets a Docker image matching the Python and Prefect version you're using at deployment time. You can see all available images at Docker Hub.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#kubernetesjob","title":"KubernetesJob","text":"<p><code>KubernetesJob</code> infrastructure executes flow runs in a Kubernetes Job.</p> <p>Requirements for <code>KubernetesJob</code>:</p> <ul> <li><code>kubectl</code> must be available.</li> <li>You must configure remote Storage. Local storage is not supported for Kubernetes.</li> <li>The ephemeral Prefect API won't work with Docker and Kubernetes. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> </ul> <p>The Prefect CLI command <code>prefect kubernetes manifest server</code> automatically generates a Kubernetes manifest with default settings for Prefect deployments. By default, it simply prints out the YAML configuration for a manifest. You can pipe this output to a file of your choice and edit as necessary.</p> <p><code>KubernetesJob</code> supports the following settings:</p> Attributes Description cluster_config An optional Kubernetes cluster config to use for this job. command A list of strings specifying the command to run in the container to start the flow run. In most cases you should not override this. customizations A list of JSON 6902 patches to apply to the base Job manifest. Alternatively, a valid JSON string is allowed (handy for deployments CLI). env Environment variables to set for the container. finished_job_ttl The number of seconds to retain jobs after completion. If set, finished jobs will be cleaned up by Kubernetes after the given delay. If None (default), jobs will need to be manually removed. image String specifying the tag of a Docker image to use for the Job. image_pull_policy The Kubernetes image pull policy to use for job containers. job The base manifest for the Kubernetes Job. job_watch_timeout_seconds Number of seconds to watch for job creation before timing out (defaults to None). labels Dictionary of labels to add to the Job. name An optional name for the job. namespace String signifying the Kubernetes namespace to use. pod_watch_timeout_seconds Number of seconds to watch for pod creation before timing out (default 60). service_account_name An optional string specifying which Kubernetes service account to use. stream_output Bool indicating whether to stream output from the subprocess to local standard output.","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#kubernetesjob-overrides-and-customizations","title":"KubernetesJob overrides and customizations","text":"<p>When creating deployments using <code>KubernetesJob</code> infrastructure, the <code>infra_overrides</code> parameter expects a dictionary. For a <code>KubernetesJob</code>, the <code>customizations</code> parameter expects a list.</p> <p>Containers expect a list of objects, even if there is only one. For any patches applying to the container, the path value should be a list, for example:   <code>/spec/templates/spec/containers/0/resources</code></p> <p>A <code>Kubernetes-Job</code> infrastructure block defined in Python:</p> <pre><code>customizations = [\n {\n     \"op\": \"add\",\n     \"path\": \"/spec/template/spec/containers/0/resources\",\n     \"value\": {\n         \"requests\": {\n             \"cpu\": \"2000m\",\n             \"memory\": \"4gi\"\n         },\n         \"limits\": {\n             \"cpu\": \"4000m\",\n             \"memory\": \"8Gi\",\n             \"nvidia.com/gpu\": \"1\"\n      }\n  },\n }\n]\n\nk8s_job = KubernetesJob(\n        namespace=namespace,\n        image=image_name,\n        image_pull_policy=KubernetesImagePullPolicy.ALWAYS,\n        finished_job_ttl=300,\n        job_watch_timeout_seconds=600,\n        pod_watch_timeout_seconds=600,\n        service_account_name=\"prefect-server\",\n        customizations=customizations,\n    )\nk8s_job.save(\"devk8s\")\n</code></pre> <p>A <code>Deployment</code> with infra-overrides defined in Python:</p> <pre><code>infra_overrides={ \n    \"customizations\": [\n            {\n                \"op\": \"add\",\n                \"path\": \"/spec/template/spec/containers/0/resources\",\n                \"value\": {\n                    \"requests\": {\n                        \"cpu\": \"2000m\",\n                        \"memory\": \"4gi\"\n                    },\n                    \"limits\": {\n                        \"cpu\": \"4000m\",\n                        \"memory\": \"8Gi\",\n                        \"nvidia.com/gpu\": \"1\"\n                }\n            },\n        }\n    ]\n}\n\n# Load an already created K8s Block\nk8sjob = k8s_job.load(\"devk8s\")\n\ndeployment = Deployment.build_from_flow(\n    flow=my_flow,\n    name=\"s3-example\",\n    version=2,\n    work_queue_name=\"aws\",\n    infrastructure=k8sjob,\n    storage=storage,\n    infra_overrides=infra_overrides,\n)\n\ndeployment.apply()\n</code></pre>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#ecstask","title":"ECSTask","text":"<p><code>ECSTask</code> infrastructure runs your flow in an ECS Task.</p> <p>Requirements for <code>ECSTask</code>:</p> <ul> <li>The ephemeral Prefect API won't work with ECS directly. You must have a Prefect server or Prefect Cloud API endpoint set in your agent's configuration.</li> <li>The <code>prefect-aws</code> collection must be installed within the agent environment: <code>pip install prefect-aws</code></li> <li>The <code>ECSTask</code> and <code>AwsCredentials</code> blocks must be registered within the agent environment: <code>prefect block register -m prefect_aws.ecs</code></li> <li>You must configure remote Storage. Local storage is not supported for ECS tasks. The most commonly used type of storage with <code>ECSTask</code> is S3. If you leverage that type of block, make sure that <code>s3fs</code> is installed within your agent and flow run environment. The easiest way to satisfy all the installation-related points mentioned above is to include the following commands in your Dockerfile:  </li> </ul> <pre><code>FROM prefecthq/prefect:2-python3.9  # example base image \nRUN pip install s3fs prefect-aws\n</code></pre> <p>Make sure to allocate enough CPU and memory to your agent, and consider adding retries</p> <p>When you start a Prefect agent on AWS ECS Fargate, allocate as much CPU and memory as needed for your workloads. Your agent needs enough resources to appropriately provision infrastructure for your flow runs and to monitor their execution. Otherwise, your flow runs may get stuck in a <code>Pending</code> state. Alternatively, set a work-queue concurrency limit to ensure that the agent will not try to process all runs at the same time.</p> <p>Some API calls to provision infrastructure may fail due to unexpected issues on the client side (for example, transient errors such as <code>ConnectionError</code>, <code>HTTPClientError</code>, or <code>RequestTimeout</code>), or due to server-side rate limiting from the AWS service. To mitigate those issues, we recommend adding environment variables such as <code>AWS_MAX_ATTEMPTS</code> (can be set to an integer value such as 10) and <code>AWS_RETRY_MODE</code> (can be set to a string value including <code>standard</code> or <code>adaptive</code> modes). Those environment variables must be added within the agent environment, e.g. on your ECS service running the agent, rather than on the <code>ECSTask</code> infrastructure block. </p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/infrastructure/#docker-images","title":"Docker images","text":"<p>Learn about options for Prefect-maintained Docker images in the Docker guide.</p>","tags":["orchestration","infrastructure","flow run infrastructure","deployments","Kubernetes","Docker","ECS","Cloud Run","Container Instances"],"boost":0.5},{"location":"concepts/results/","title":"Results","text":"<p>Results represent the data returned by a flow or a task.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#retrieving-results","title":"Retrieving results","text":"<p>When calling flows or tasks, the result is returned directly:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    task_result = my_task()\n    return task_result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>When working with flow and task states, the result can be retrieved with the <code>State.result()</code> method:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n    return state.result() + 1\n\nstate = my_flow(return_state=True)\nassert state.result() == 2\n</code></pre> <p>When submitting tasks to a runner, the result can be retrieved with the <code>Future.result()</code> method:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 1\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    return future.result() + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#handling-failures","title":"Handling failures","text":"<p>Sometimes your flows or tasks will encounter an exception. Prefect captures all exceptions in order to report states to the orchestrator, but we do not hide them from you (unless you ask us to) as your program needs to know if an unexpected error has occurred.</p> <p>When calling flows or tasks, the exceptions are raised as in normal Python:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    try:\n        my_task()\n    except ValueError:\n        print(\"Oh no! The task failed.\")\n\n    return True\n\nmy_flow()\n</code></pre> <p>If you would prefer to check for a failed task without using <code>try/except</code>, you may ask Prefect to return the state:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    if state.is_failed():\n        print(\"Oh no! The task failed. Falling back to '1'.\")\n        result = 1\n    else:\n        result = state.result()\n\n    return result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>If you retrieve the result from a failed state, the exception will be raised. For this reason, it's often best to check if the state is failed first.</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    try:\n        result = state.result()\n    except ValueError:\n        print(\"Oh no! The state raised the error!\")\n\n    return True\n\nmy_flow()\n</code></pre> <p>When retrieving the result from a state, you can ask Prefect not to raise exceptions:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    state = my_task(return_state=True)\n\n    maybe_result = state.result(raise_on_failure=False)\n    if isinstance(maybe_result, ValueError):\n        print(\"Oh no! The task failed. Falling back to '1'.\")\n        result = 1\n    else:\n        result = maybe_result\n\n    return result + 1\n\nresult = my_flow()\nassert result == 2\n</code></pre> <p>When submitting tasks to a runner, <code>Future.result()</code> works the same as <code>State.result()</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    raise ValueError()\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n\n    try:\n        future.result()\n    except ValueError:\n        print(\"Ah! Futures will raise the failure as well.\")\n\n    # You can ask it not to raise the exception too\n    maybe_result = future.result(raise_on_failure=False)\n    print(f\"Got {type(maybe_result)}\")\n\n    return True\n\nmy_flow()\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#working-with-async-results","title":"Working with async results","text":"<p>When calling flows or tasks, the result is returned directly:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    task_result = await my_task()\n    return task_result + 1\n\nresult = asyncio.run(my_flow())\nassert result == 2\n</code></pre> <p>When working with flow and task states, the result can be retrieved with the <code>State.result()</code> method:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    state = await my_task(return_state=True)\n    result = await state.result(fetch=True)\n    return result + 1\n\nasync def main():\n    state = await my_flow(return_state=True)\n    assert await state.result(fetch=True) == 2\n\nasyncio.run(main())\n</code></pre> <p>Resolving results</p> <p>Prefect 2.6.0 added automatic retrieval of persisted results. Prior to this version, <code>State.result()</code> did not require an <code>await</code>. For backwards compatibility, when used from an asynchronous context, <code>State.result()</code> returns a raw result type.</p> <p>You may opt-in to the new behavior by passing <code>fetch=True</code> as shown in the example above. If you would like this behavior to be used automatically, you may enable the <code>PREFECT_ASYNC_FETCH_STATE_RESULT</code> setting. If you do not opt-in to this behavior, you will see a warning.</p> <p>You may also opt-out by setting <code>fetch=False</code>. This will silence the warning, but you will need to retrieve your result manually from the result type.</p> <p>When submitting tasks to a runner, the result can be retrieved with the <code>Future.result()</code> method:</p> <pre><code>import asyncio\nfrom prefect import flow, task\n\n@task\nasync def my_task():\n    return 1\n\n@flow\nasync def my_flow():\n    future = await my_task.submit()\n    result = await future.result()\n    return result + 1\n\nresult = asyncio.run(my_flow())\nassert result == 2\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisting-results","title":"Persisting results","text":"<p>The Prefect API does not store your results except in special cases. Instead, the result is persisted to a storage location in your infrastructure and Prefect stores a reference to the result.</p> <p>The following Prefect features require results to be persisted:</p> <ul> <li>Task cache keys</li> <li>Flow run retries</li> </ul> <p>If results are not persisted, these features may not be usable.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#configuring-persistence-of-results","title":"Configuring persistence of results","text":"<p>Persistence of results requires a serializer and a storage location. Prefect sets defaults for these, and you should not need to adjust them until you want to customize behavior. You can configure results on the <code>flow</code> and <code>task</code> decorators with the following options:</p> <ul> <li><code>persist_result</code>: Whether the result should be persisted to storage.</li> <li><code>result_storage</code>: Where to store the result when persisted.</li> <li><code>result_serializer</code>: How to convert the result to a storable form.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#toggling-persistence","title":"Toggling persistence","text":"<p>Persistence of the result of a task or flow can be configured with the <code>persist_result</code> option. The <code>persist_result</code> option defaults to a null value, which will automatically enable persistence if it is needed for a Prefect feature used by the flow or task. Otherwise, persistence is disabled by default.</p> <p>For example, the following flow has retries enabled. Flow retries require that all task results are persisted, so the task's result will be persisted:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return \"hello world!\"\n\n@flow(retries=2)\ndef my_flow():\n    # This task does not have persistence toggled off and it is needed for the flow feature,\n    # so Prefect will persist its result at runtime\n    my_task()\n</code></pre> <p>Flow retries do not require the flow's result to be persisted, so it will not be.</p> <p>In this next example, one task has caching enabled. Task caching requires that the given task's result is persisted:</p> <pre><code>from prefect import flow, task\nfrom datetime import timedelta\n\n@task(cache_key_fn=lambda: \"always\", cache_expiration=timedelta(seconds=20))\ndef my_task():\n    # This task uses caching so its result will be persisted by default\n    return \"hello world!\"\n\n\n@task\ndef my_other_task():\n    ...\n\n@flow\ndef my_flow():\n    # This task uses a feature that requires result persistence\n    my_task()\n\n    # This task does not use a feature that requires result persistence and the\n    # flow does not use any features that require task result persistence so its\n    # result will not be persisted by default\n    my_other_task()\n</code></pre> <p>Persistence of results can be manually toggled on or off:</p> <pre><code>from prefect import flow, task\n\n@flow(persist_result=True)\ndef my_flow():\n    # This flow will persist its result even if not necessary for a feature.\n    ...\n\n@task(persist_result=False)\ndef my_task():\n    # This task will never persist its result.\n    # If persistence needed for a feature, an error will be raised.\n    ...\n</code></pre> <p>Toggling persistence manually will always override any behavior that Prefect would infer.</p> <p>You may also change Prefect's default persistence behavior with the <code>PREFECT_RESULTS_PERSIST_BY_DEFAULT</code> setting. To persist results by default, even if they are not needed for a feature change the value to a truthy value:</p> <pre><code>prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true\n</code></pre> <p>Task and flows with <code>persist_result=False</code> will not persist their results even if <code>PREFECT_RESULTS_PERSIST_BY_DEFAULT</code> is <code>true</code>.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-location","title":"Result storage location","text":"<p>The result storage location can be configured with the <code>result_storage</code> option. The <code>result_storage</code> option defaults to a null value, which infers storage from the context. Generally, this means that tasks will use the result storage configured on the flow unless otherwise specified. If there is no context to load the storage from and results must be persisted, results will be stored in the path specified by the <code>PREFECT_LOCAL_STORAGE_PATH</code> setting (defaults to <code>~/.prefect/storage</code>).</p> <pre><code>from prefect import flow, task\nfrom prefect.filesystems import LocalFileSystem, S3\n\n@flow(persist_result=True)\ndef my_flow():\n    my_task()  # This task will use the flow's result storage\n\n@task(persist_result=True)\ndef my_task():\n    ...\n\nmy_flow()  # The flow has no result storage configured and no parent, the local file system will be used.\n\n\n# Reconfigure the flow to use a different storage type\nnew_flow = my_flow.with_options(result_storage=S3(bucket_path=\"my-bucket\"))\n\nnew_flow()  # The flow and task within it will use S3 for result storage.\n</code></pre> <p>You can configure this to use a specific storage using one of the following:</p> <ul> <li>A storage instance, e.g. <code>LocalFileSystem(basepath=\".my-results\")</code></li> <li>A storage slug, e.g. <code>'s3/dev-s3-block'</code></li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-key","title":"Result storage key","text":"<p>The path of the result file in the result storage can be configured with the <code>result_storage_key</code>. The <code>result_storage_key</code> option defaults to a null value, which generates a unique identifier for each result.</p> <pre><code>from prefect import flow, task\nfrom prefect.filesystems import LocalFileSystem, S3\n\n@flow(result_storage=S3(bucket_path=\"my-bucket\"))\ndef my_flow():\n    my_task()\n\n@task(persist_result=True, result_storage_key=\"my_task.json\")\ndef my_task():\n    ...\n\nmy_flow()  # The task's result will be persisted to 's3://my-bucket/my_task.json'\n</code></pre> <p>Result storage keys are formatted with access to all of the modules in <code>prefect.runtime</code> and the run's <code>parameters</code>. In the following example, we will run a flow with three runs of the same task. Each task run will write its result to a unique file based on the <code>name</code> parameter.</p> <pre><code>from prefect import flow, task\n\n@flow()\ndef my_flow():\n    hello_world()\n    hello_world(name=\"foo\")\n    hello_world(name=\"bar\")\n\n@task(persist_result=True, result_storage_key=\"hello-{parameters[name]}.json\")\ndef hello_world(name: str = \"world\"):\n    return f\"hello {name}\"\n\nmy_flow()\n</code></pre> <p>After running the flow, we can see three persisted result files in our storage directory:</p> <pre><code>$ ls ~/.prefect/storage | grep \"hello-\"\nhello-bar.json\nhello-foo.json\nhello-world.json\n</code></pre> <p>In the next example, we include metadata about the flow run from the <code>prefect.runtime.flow_run</code> module:</p> <pre><code>from prefect import flow, task\n\n@flow\ndef my_flow():\n    hello_world()\n\n@task(persist_result=True, result_storage_key=\"{flow_run.flow_name}_{flow_run.name}_hello.json\")\ndef hello_world(name: str = \"world\"):\n    return f\"hello {name}\"\n\nmy_flow()\n</code></pre> <p>After running this flow, we can see a result file templated with the name of the flow and the flow run:</p> <pre><code>\u276f ls ~/.prefect/storage | grep \"my-flow\"    \nmy-flow_industrious-trout_hello.json\n</code></pre> <p>If a result exists at a given storage key in the storage location, it will be overwritten.</p> <p>Result storage keys can only be configured on tasks at this time.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-serializer","title":"Result serializer","text":"<p>The result serializer can be configured with the <code>result_serializer</code> option. The <code>result_serializer</code> option defaults to a null value, which infers the serializer from the context. Generally, this means that tasks will use the result serializer configured on the flow unless otherwise specified. If there is no context to load the serializer from, the serializer defined by <code>PREFECT_RESULTS_DEFAULT_SERIALIZER</code> will be used. This setting defaults to Prefect's pickle serializer.</p> <p>You may configure the result serializer using:</p> <ul> <li>A type name, e.g. <code>\"json\"</code> or <code>\"pickle\"</code> \u2014 this corresponds to an instance with default values</li> <li>An instance, e.g. <code>JSONSerializer(jsonlib=\"orjson\")</code></li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#compressing-results","title":"Compressing results","text":"<p>Prefect provides a <code>CompressedSerializer</code> which can be used to wrap other serializers to provide compression over the bytes they generate. The compressed serializer uses <code>lzma</code> compression by default. We test other compression schemes provided in the Python standard library such as <code>bz2</code> and <code>zlib</code>, but you should be able to use any compression library that provides <code>compress</code> and <code>decompress</code> methods.</p> <p>You may configure compression of results using:</p> <ul> <li>A type name, prefixed with <code>compressed/</code> e.g. <code>\"compressed/json\"</code> or <code>\"compressed/pickle\"</code></li> <li>An instance e.g. <code>CompressedSerializer(serializer=\"pickle\", compressionlib=\"lzma\")</code></li> </ul> <p>Note that the <code>\"compressed/&lt;serializer-type&gt;\"</code> shortcut will only work for serializers provided by Prefect. If you are using custom serializers, you must pass a full instance.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#storage-of-results-in-prefect","title":"Storage of results in Prefect","text":"<p>The Prefect API does not store your results in most cases for the following reasons:</p> <ul> <li>Results can be large and slow to send to and from the API.</li> <li>Results often contain private information or data.</li> <li>Results would need to be stored in the database or complex logic implemented to hydrate from another source.</li> </ul> <p>There are a few cases where Prefect will store your results directly in the database. This is an optimization to reduce the overhead of reading and writing to result storage.</p> <p>The following data types will be stored by the API without persistence to storage:</p> <ul> <li>booleans (<code>True</code>, <code>False</code>)</li> <li>nulls (<code>None</code>)</li> </ul> <p>If <code>persist_result</code> is set to <code>False</code>, these values will never be stored.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#tracking-results","title":"Tracking results","text":"<p>The Prefect API tracks metadata about your results. The value of your result is only stored in specific cases. Result metadata can be seen in the UI on the \"Results\" page for flows.</p> <p>Prefect tracks the following result metadata:</p> <ul> <li>Data type</li> <li>Storage location (if persisted)</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#caching-of-results-in-memory","title":"Caching of results in memory","text":"<p>When running your workflows, Prefect will keep the results of all tasks and flows in memory so they can be passed downstream. In some cases, it is desirable to override this behavior. For example, if you are returning a large amount of data from a task it can be costly to keep it memory for the entire duration of the flow run.</p> <p>Flows and tasks both include an option to drop the result from memory with <code>cache_result_in_memory</code>:</p> <pre><code>@flow(cache_result_in_memory=False)\ndef foo():\n    return \"pretend this is large data\"\n\n@task(cache_result_in_memory=False)\ndef bar():\n    return \"pretend this is biiiig data\"\n</code></pre> <p>When <code>cache_result_in_memory</code> is disabled, the result of your flow or task will be persisted by default. The result will then be pulled from storage when needed.</p> <pre><code>@flow\ndef foo():\n    result = bar()\n    state = bar(return_state=True)\n\n    # The result will be retrieved from storage here\n    state.result()\n\n    future = bar.submit()\n    # The result will be retrieved from storage here\n    future.result()\n\n@task(cache_result_in_memory=False)\ndef bar():\n    # This result will persisted\n    return \"pretend this is biiiig data\"\n</code></pre> <p>If both <code>cache_result_in_memory</code> and persistence are disabled, your results will not be available downstream.</p> <pre><code>@task(persist_result=False, cache_result_in_memory=False)\ndef bar():\n    return \"pretend this is biiiig data\"\n\n@flow\ndef foo():\n    # Raises an error\n    result = bar()\n\n    # This is oaky\n    state = bar(return_state=True)\n\n    # Raises an error\n    state.result()\n\n    # This is okay\n    future = bar.submit()\n\n    # Raises an error\n    future.result()\n</code></pre>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-storage-types","title":"Result storage types","text":"<p>Result storage is responsible for reading and writing serialized data to an external location. At this time, any file system block can be used for result storage.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-serializer-types","title":"Result serializer types","text":"<p>A result serializer is responsible for converting your Python object to and from bytes. This is necessary to store the object outside of Python and retrieve it later.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#pickle-serializer","title":"Pickle serializer","text":"<p>Pickle is a standard Python protocol for encoding arbitrary Python objects. We supply a custom pickle serializer at <code>prefect.serializers.PickleSerializer</code>. Prefect's pickle serializer uses the cloudpickle project by default to support more object types. Alternative pickle libraries can be specified:</p> <pre><code>from prefect.serializers import PickleSerializer\n\nPickleSerializer(picklelib=\"custompickle\")\n</code></pre> <p>Benefits of the pickle serializer:</p> <ul> <li>Many object types are supported.</li> <li>Objects can define custom pickle support.</li> </ul> <p>Drawbacks of the pickle serializer:</p> <ul> <li>When nested attributes of an object cannot be pickled, it is hard to determine the cause.</li> <li>When deserializing objects, your Python and pickle library versions must match the one used at serialization time.</li> <li>Serialized objects cannot be easily shared across different programming languages.</li> <li>Serialized objects are not human readable.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#json-serializer","title":"JSON serializer","text":"<p>We supply a custom JSON serializer at <code>prefect.serializers.JSONSerializer</code>. Prefect's JSON serializer uses custom hooks by default to support more object types. Specifically, we add support for all types supported by Pydantic.</p> <p>By default, we use the standard Python <code>json</code> library. Alternative JSON libraries can be specified:</p> <pre><code>from prefect.serializers import JSONSerializer\n\nJSONSerializer(jsonlib=\"orjson\")\n</code></pre> <p>Benefits of the JSON serializer:</p> <ul> <li>Serialized objects are human readable.</li> <li>Serialized objects can often be shared across different programming languages.</li> <li>Deserialization of serialized objects is generally version agnostic.</li> </ul> <p>Drawbacks of the JSON serializer:</p> <ul> <li>Supported types are limited.</li> <li>Implementing support for additional types must be done at the serializer level.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#result-types","title":"Result types","text":"<p>Prefect uses internal result types to capture information about the result attached to a state. The following types are used:</p> <ul> <li><code>UnpersistedResult</code>: Stores result metadata but the value is only available when created.</li> <li><code>LiteralResult</code>: Stores simple values inline.</li> <li><code>PersistedResult</code>: Stores a reference to a result persisted to storage.</li> </ul> <p>All result types include a <code>get()</code> method that can be called to return the value of the result. This is done behind the scenes when the <code>result()</code> method is used on states or futures.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#unpersisted-results","title":"Unpersisted results","text":"<p>Unpersisted results are used to represent results that have not been and will not be persisted beyond the current flow run. The value associated with the result is stored in memory, but will not be available later. Result metadata is attached to this object for storage in the API and representation in the UI.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#literal-results","title":"Literal results","text":"<p>Literal results are used to represent results stored in the Prefect database. The values contained by these results must always be JSON serializable.</p> <p>Example:</p> <pre><code>result = LiteralResult(value=None)\nresult.json()\n# {\"type\": \"result\", \"value\": \"null\"}\n</code></pre> <p>Literal results reduce the overhead required to persist simple results.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisted-results","title":"Persisted results","text":"<p>The persisted result type contains all of the information needed to retrieve the result from storage. This includes:</p> <ul> <li>Storage: A reference to the result storage that can be used to read the serialized result.</li> <li>Key: Indicates where this specific result is in storage.</li> </ul> <p>Persisted result types also contain metadata for inspection without retrieving the result:</p> <ul> <li>Serializer type: The name of the result serializer type.</li> </ul> <p>The <code>get()</code> method on result references retrieves the data from storage, deserializes it, and returns the original object. The <code>get()</code> operation will cache the resolved object to reduce the overhead of subsequent calls.</p>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/results/#persisted-result-blob","title":"Persisted result blob","text":"<p>When results are persisted to storage, they are always written as a JSON document. The schema for this is described by the <code>PersistedResultBlob</code> type. The document contains:</p> <ul> <li>The serialized data of the result.</li> <li>A full description of result serializer that can be used to deserialize the result data.</li> <li>The Prefect version used to create the result.</li> </ul>","tags":["flows","subflows","tasks","states","results"],"boost":2},{"location":"concepts/schedules/","title":"Schedules","text":"<p>Scheduling is one of the primary reasons for using an orchestrator such as Prefect. Prefect allows you to use schedules to automatically create new flow runs for deployments.</p> <p>Prefect Cloud can also schedule flow runs through event-driven automations.</p> <p>Schedules tell the Prefect API how to create new flow runs for you automatically on a specified cadence.</p> <p>You can add a schedule to any deployment. The Prefect <code>Scheduler</code> service periodically reviews every deployment and creates new flow runs according to the schedule configured for the deployment.</p> <p>Support for multiple schedules</p> <p>We are currently rolling out support for multiple schedules per deployment. You can now assign multiple schedules to deployments in the Prefect UI, the CLI via <code>prefect deployment schedule</code> commands, the <code>Deployment</code> class, and in block-based deployment YAML files.</p> <p>Support for multiple schedules in <code>flow.serve</code>, <code>flow.deploy</code>, <code>serve</code>, and worker-based deployments with <code>prefect deploy</code> will arrive soon.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#schedule-types","title":"Schedule types","text":"<p>Prefect supports several types of schedules that cover a wide range of use cases and offer a large degree of customization:</p> <ul> <li><code>Cron</code> is most appropriate for users who are already familiar with <code>cron</code> from previous use.</li> <li><code>Interval</code> is best suited for deployments that need to run at some consistent cadence that isn't related to absolute time.</li> <li><code>RRule</code> is best suited for deployments that rely on calendar logic for simple recurring schedules, irregular intervals, exclusions, or day-of-month adjustments.</li> </ul> <p>Schedules can be inactive</p> <p>When you create or edit a schedule, you can set the <code>active</code> property to <code>False</code> in Python (or <code>false</code> in a YAML file) to deactivate the schedule. This is useful if you want to keep the schedule configuration but temporarily stop the schedule from creating new flow runs.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#cron","title":"Cron","text":"<p>A schedule may be specified with a <code>cron</code> pattern. Users may also provide a timezone to enforce DST behaviors.</p> <p><code>Cron</code> uses <code>croniter</code> to specify datetime iteration with a <code>cron</code>-like format.</p> <p><code>Cron</code> properties include:</p> Property Description cron A valid <code>cron</code> string. (Required) day_or Boolean indicating how <code>croniter</code> handles <code>day</code> and <code>day_of_week</code> entries. Default is <code>True</code>. timezone String name of a time zone. (See the IANA Time Zone Database for valid time zones.)","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#how-the-day_or-property-works","title":"How the <code>day_or</code> property works","text":"<p>The <code>day_or</code> property defaults to <code>True</code>, matching the behavior of <code>cron</code>. In this mode, if you specify a <code>day</code> (of the month) entry and a <code>day_of_week</code> entry, the schedule will run a flow on both the specified day of the month and on the specified day of the week. The \"or\" in <code>day_or</code> refers to the fact that the two entries are treated like an <code>OR</code> statement, so the schedule should include both, as in the SQL statement <code>SELECT * FROM employees WHERE first_name = 'Xi\u0101ng' OR last_name = 'Brookins';</code>.</p> <p>For example, with <code>day_or</code> set to <code>True</code>, the cron schedule <code>* * 3 1 2</code> runs a flow every minute on the 3rd day of the month (whatever that is) and on Tuesday (the second day of the week) in January (the first month of the year).</p> <p>With <code>day_or</code> set to <code>False</code>, the <code>day</code> (of the month) and <code>day_of_week</code> entries are joined with the more restrictive <code>AND</code> operation, as in the SQL statement <code>SELECT * from employees WHERE first_name = 'Andrew' AND last_name = 'Brookins';</code>. For example, the same schedule, when <code>day_or</code> is <code>False</code>, runs a flow on every minute on the 3rd Tuesday in January. This behavior matches <code>fcron</code> instead of <code>cron</code>.</p> <p>Supported <code>croniter</code> features</p> <p>While Prefect supports most features of <code>croniter</code> for creating <code>cron</code>-like schedules, we do not currently support \"R\" random or \"H\" hashed keyword expressions or the schedule jittering possible with those expressions.</p> <p>Daylight saving time considerations</p> <p>If the <code>timezone</code> is a DST-observing one, then the schedule will adjust itself appropriately.</p> <p>The <code>cron</code> rules for DST are based on schedule times, not intervals. This means that an hourly <code>cron</code> schedule fires on every new schedule hour, not every elapsed hour.  For example, when clocks are set back, this results in a two-hour pause as the schedule will fire the first time 1am is reached and the first time 2am is reached, 120 minutes later. </p> <p>Longer schedules, such as one that fires at 9am every morning, will adjust for DST automatically.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#interval","title":"Interval","text":"<p>An <code>Interval</code> schedule creates new flow runs on a regular interval measured in seconds. Intervals are computed using an optional <code>anchor_date</code>. For example, here's how you can create a schedule for every 10 minutes in a block-based deployment YAML file:</p> <pre><code>schedule:\n  interval: 600\n  timezone: America/Chicago \n</code></pre> <p><code>Interval</code> properties include:</p> Property Description interval <code>datetime.timedelta</code> indicating the time between flow runs. (Required) anchor_date <code>datetime.datetime</code> indicating the starting or \"anchor\" date to begin the schedule. If no <code>anchor_date</code> is supplied, the current UTC time is used. timezone String name of a time zone, used to enforce localization behaviors like DST boundaries. (See the IANA Time Zone Database for valid time zones.) <p>Note that the <code>anchor_date</code> does not indicate a \"start time\" for the schedule, but rather a fixed point in time from which to compute intervals. If the anchor date is in the future, then schedule dates are computed by subtracting the <code>interval</code> from it. Note that in this example, we import the Pendulum Python package for easy datetime manipulation. Pendulum isn\u2019t required, but it\u2019s a useful tool for specifying dates.</p> <p>Daylight saving time considerations</p> <p>If the schedule's <code>anchor_date</code> or <code>timezone</code> are provided with a DST-observing timezone, then the schedule will adjust itself appropriately. Intervals greater than 24 hours will follow DST conventions, while intervals of less than 24 hours will follow UTC intervals.</p> <p>For example, an hourly schedule will fire every UTC hour, even across DST boundaries. When clocks are set back, this will result in two runs that appear to both be scheduled for 1am local time, even though they are an hour apart in UTC time. </p> <p>For longer intervals, like a daily schedule, the interval schedule will adjust for DST boundaries so that the clock-hour remains constant.  This means that a daily schedule that always fires at 9am will observe DST and continue to fire at 9am in the local time zone.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#rrule","title":"RRule","text":"<p>An <code>RRule</code> scheduling supports iCal recurrence rules (RRules), which provide convenient syntax for creating repetitive schedules. Schedules can repeat on a frequency from yearly down to every minute.</p> <p><code>RRule</code> uses the dateutil rrule module to specify iCal recurrence rules.</p> <p>RRules are appropriate for any kind of calendar-date manipulation, including simple repetition, irregular intervals, exclusions, week day or day-of-month adjustments, and more. RRules can represent complex logic like:</p> <ul> <li>The last weekday of each month</li> <li>The fourth Thursday of November</li> <li>Every other day of the week</li> </ul> <p><code>RRule</code> properties include:</p> Property Description rrule String representation of an RRule schedule. See the <code>rrulestr</code> examples for syntax. timezone String name of a time zone. See the IANA Time Zone Database for valid time zones. <p>You may find it useful to use an RRule string generator such as the iCalendar.org RRule Tool to help create valid RRules.</p> <p>For example, the following RRule schedule in a block-based deployment YAML file creates flow runs on Monday, Wednesday, and Friday until July 30, 2024.</p> <pre><code>schedule:\n  rrule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20240730T040000Z'\n</code></pre> <p>RRule restrictions</p> <p>Note the max supported character length of an <code>rrulestr</code> is 6500 characters</p> <p>Note that <code>COUNT</code> is not supported. Please use <code>UNTIL</code> or the <code>/deployments/{id}/runs</code> endpoint to schedule a fixed number of flow runs.</p> <p>Daylight saving time considerations</p> <p>Note that as a calendar-oriented standard, <code>RRules</code> are sensitive to the initial timezone provided. A 9am daily schedule with a DST-aware start date will maintain a local 9am time through DST boundaries. A 9am daily schedule with a UTC start date will maintain a 9am UTC time.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules","title":"Creating schedules","text":"<p>There are several ways to create a schedule for a deployment:</p> <ul> <li>Through the Prefect UI</li> <li>Via the <code>cron</code>, <code>interval</code>, or <code>rrule</code> parameters if building your deployment via the <code>serve</code> method of the <code>Flow</code> object or the <code>serve</code> utility for managing multiple flows simultaneously</li> <li>If using worker-based deployments</li> <li>When you define a deployment with <code>flow.serve</code> or <code>flow.deploy</code></li> <li>Through the interactive <code>prefect deploy</code> command</li> <li>With the <code>deployments</code> -&gt; <code>schedules</code> section of the <code>prefect.yaml</code> file</li> <li>If using block-based deployments - Deprecated </li> <li><code>Through the schedules</code> section of the deployment YAML file</li> <li>By passing <code>schedules</code> into the <code>Deployment</code> class or <code>Deployment.build_from_flow</code></li> </ul>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-in-the-ui","title":"Creating schedules in the UI","text":"<p>You can add schedules in the Schedules section on a Deployment page in the UI.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#locating-the-schedules-section","title":"Locating the Schedules section","text":"<p>The Schedules section appears in the sidebar on the right side of the page on wider displays. On narrower displays, it appears on the Details tab of the page.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#adding-a-schedule","title":"Adding a schedule","text":"<p>Under Schedules, select the + Schedule button. A modal dialog will open. Choose Interval or Cron to create a schedule.</p> <p></p> <p>What about RRule?</p> <p>The UI does not support creating RRule schedules. However, the UI will display RRule schedules that you've created via the command line.</p> <p>The new schedule will appear on the Deployment page where you created it. In addition, the schedule will be viewable in human-friendly text in the list of deployments on the Deployments page.</p> <p>After you create a schedule, new scheduled flow runs will be visible in the Upcoming tab of the Deployment page where you created it.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#editing-schedules","title":"Editing schedules","text":"<p>You can edit a schedule by selecting Edit from the three-dot menu next to a schedule on a Deployment page.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-with-a-python-deployment-creation-file","title":"Creating schedules with a Python deployment creation file","text":"<p>When you create a deployment in a Python file with <code>flow.serve()</code>, <code>serve</code>, <code>flow.deploy()</code>, or <code>deploy</code> you can specify the schedule. Just add the keyword argument <code>cron</code>, <code>interval</code>, or <code>rrule</code>.</p> <pre><code>interval: An interval on which to execute the deployment. Accepts a number or a \n    timedelta object to create a single schedule. If a number is given, it will be \n    interpreted as seconds. Also accepts an iterable of numbers or timedelta to create \n    multiple schedules.\ncron: A cron schedule string of when to execute runs of this deployment. \n    Also accepts an iterable of cron schedule strings to create multiple schedules.\nrrule: An rrule schedule string of when to execute runs of this deployment.\n    Also accepts an iterable of rrule schedule strings to create multiple schedules.\nschedules: A list of schedule objects defining when to execute runs of this deployment.\n    Used to define multiple schedules or additional scheduling options such as `timezone`.\nschedule: A schedule object defining when to execute runs of this deployment. Used to\n    define additional scheduling options like `timezone`.\n</code></pre> <p>Here's an example of creating a cron schedule with <code>serve</code> for a deployment flow that will run every minute of every day:</p> <pre><code>my_flow.serve(name=\"flowing\", cron=\"* * * * *\")\n</code></pre> <p>If using work pool-based deployments, the <code>deploy</code> method has the same schedule-based parameters.</p> <p>Here's an example of creating an interval schedule with <code>serve</code> for a deployment flow that will run every 10 minutes with an anchor date and a timezone:</p> <pre><code>from datetime import timedelta, datetime\nfrom prefect.client.schemas.schedules import IntervalSchedule\n\nmy_flow.serve(name=\"flowing\", schedule=IntervalSchedule(interval=timedelta(minutes=10), anchor_date=datetime(2023, 1, 1, 0, 0), timezone=\"America/Chicago\"))\n</code></pre> <p>Block and agent-based deployments with Python files are not a recommended way to create deployments. However, if you are using that deployment creation method you can create a schedule by passing a <code>schedule</code> argument to the <code>Deployment.build_from_flow</code> method.</p> <p>Here's how you create the equivalent schedule in a Python deployment file.</p> <pre><code>from prefect.client.schemas.schedules import CronSchedule\n\ncron_demo = Deployment.build_from_flow(\n    pipeline,\n    \"etl\",\n    schedule=(CronSchedule(cron=\"0 0 * * *\", timezone=\"America/Chicago\"))\n)\n</code></pre>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-with-the-interactive-prefect-deploy-command","title":"Creating schedules with the interactive <code>prefect deploy</code> command","text":"<p>If you are using worker-based deployments, you can create a schedule through the interactive <code>prefect deploy</code> command. You will be prompted to choose which type of schedule to create.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#creating-schedules-in-the-prefectyaml-files-deployments-schedule-section","title":"Creating schedules in the <code>prefect.yaml</code> file's <code>deployments</code> -&gt; <code>schedule</code> section","text":"<p>If you save the <code>prefect.yaml</code> file from the <code>prefect deploy</code> command, you will see it has a <code>schedules</code> section for your deployment. Alternatively, you can create a <code>prefect.yaml</code> file from a recipe or from scratch and add a <code>schedules</code> section to it.</p> <pre><code>deployments:\n  ...\n  schedules:\n    - cron: \"0 0 * * *\"\n      timezone: \"America/Chicago\"\n      active: false\n    - cron: \"0 12 * * *\"\n      timezone: \"America/New_York\"\n      active: true\n    - cron: \"0 18 * * *\"\n      timezone: \"Europe/London\"\n      active: true\n</code></pre>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/schedules/#the-scheduler-service","title":"The <code>Scheduler</code> service","text":"<p>The <code>Scheduler</code> service is started automatically when <code>prefect server start</code> is run and it is a built-in service of Prefect Cloud.</p> <p>By default, the <code>Scheduler</code> service visits deployments on a 60-second loop, though recently-modified deployments will be visited more frequently. The <code>Scheduler</code> evaluates each deployment's schedules and creates new runs appropriately. For typical deployments, it will create the next three runs, though more runs will be scheduled if the next 3 would all start in the next hour.</p> <p>More specifically, the <code>Scheduler</code> tries to create the smallest number of runs that satisfy the following constraints, in order:</p> <ul> <li>No more than 100 runs will be scheduled.</li> <li>Runs will not be scheduled more than 100 days in the future.</li> <li>At least 3 runs will be scheduled.</li> <li>Runs will be scheduled until at least one hour in the future.</li> </ul> <p>These behaviors can all be adjusted through the relevant settings that can be viewed with the terminal command <code>prefect config view --show-defaults</code>:</p> <pre><code>PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE='100'\nPREFECT_API_SERVICES_SCHEDULER_ENABLED='True'\nPREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE='500'\nPREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS='60.0'\nPREFECT_API_SERVICES_SCHEDULER_MIN_RUNS='3'\nPREFECT_API_SERVICES_SCHEDULER_MAX_RUNS='100'\nPREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME='1:00:00'\nPREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME='100 days, 0:00:00'\n</code></pre> <p>See the Settings docs for more information on altering your settings.</p> <p>These settings mean that if a deployment has an hourly schedule, the default settings will create runs for the next 4 days (or 100 hours). If it has a weekly schedule, the default settings will maintain the next 14 runs (up to 100 days in the future).</p> <p>The <code>Scheduler</code> does not affect execution</p> <p>The Prefect <code>Scheduler</code> service only creates new flow runs and places them in <code>Scheduled</code> states. It is not involved in flow or task execution.</p> <p>If you change a schedule, previously scheduled flow runs that have not started are removed, and new scheduled flow runs are created to reflect the new schedule.</p> <p>To remove all scheduled runs for a flow deployment, you can remove the schedule via the UI.</p>","tags":["flows","flow runs","deployments","schedules","scheduling","cron","RRule","iCal"],"boost":2},{"location":"concepts/states/","title":"States","text":"","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#overview","title":"Overview","text":"<p>States are rich objects that contain information about the status of a particular task run or flow run. While you don't need to know the details of the states to use Prefect, you can give your workflows superpowers by taking advantage of it.</p> <p>At any moment, you can learn anything you need to know about a task or flow by examining its current state or the history of its states. For example, a state could tell you that a task:</p> <ul> <li> <p>is scheduled to make a third run attempt in an hour</p> </li> <li> <p>succeeded and what data it produced</p> </li> <li> <p>was scheduled to run, but later cancelled</p> </li> <li> <p>used the cached result of a previous run instead of re-running</p> </li> <li> <p>failed because it timed out</p> </li> </ul> <p>By manipulating a relatively small number of task states, Prefect flows can harness the complexity that emerges in workflows.</p> <p>Only runs have states</p> <p>Though we often refer to the \"state\" of a flow or a task, what we really mean is the state of a flow run or a task run. Flows and tasks are templates that describe what a system does; only when we run the system does it also take on a state. So while we might refer to a task as \"running\" or being \"successful\", we really mean that a specific instance of the task is in that state.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#state-types","title":"State Types","text":"<p>States have names and types. State types are canonical, with specific orchestration rules that apply to transitions into and out of each state type. A state's name, is often, but not always, synonymous with its type. For example, a task run that is running for the first time has a state with the name Running and the type <code>RUNNING</code>. However, if the task retries, that same task run will have the name Retrying and the type <code>RUNNING</code>. Each time the task run transitions into the <code>RUNNING</code> state, the same orchestration rules are applied.</p> <p>There are terminal state types from which there are no orchestrated transitions to any other state type.</p> <ul> <li><code>COMPLETED</code></li> <li><code>CANCELLED</code></li> <li><code>FAILED</code></li> <li><code>CRASHED</code></li> </ul> <p>The full complement of states and state types includes:</p> Name Type Terminal? Description Scheduled SCHEDULED No The run will begin at a particular time in the future. Late SCHEDULED No The run's scheduled start time has passed, but it has not transitioned to PENDING (15 seconds by default). AwaitingRetry SCHEDULED No The run did not complete successfully because of a code issue and had remaining retry attempts. Pending PENDING No The run has been submitted to run, but is waiting on necessary preconditions to be satisfied. Running RUNNING No The run code is currently executing. Retrying RUNNING No The run code is currently executing after previously not complete successfully. Paused PAUSED No The run code has stopped executing until it receives manual approval to proceed. Cancelling CANCELLING No The infrastructure on which the code was running is being cleaned up. Cancelled CANCELLED Yes The run did not complete because a user determined that it should not. Completed COMPLETED Yes The run completed successfully. Failed FAILED Yes The run did not complete because of a code issue and had no remaining retry attempts. Crashed CRASHED Yes The run did not complete because of an infrastructure issue.","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#returned-values","title":"Returned values","text":"<p>When calling a task or a flow, there are three types of returned values:</p> <ul> <li>Data: A Python object (such as <code>int</code>, <code>str</code>, <code>dict</code>, <code>list</code>, and so on).</li> <li><code>State</code>: A Prefect object indicating the state of a flow or task run.</li> <li><code>PrefectFuture</code>: A Prefect object that contains both data and State.</li> </ul> <p>Returning data\u200a is the default behavior any time you call <code>your_task()</code>.</p> <p>Returning Prefect <code>State</code> occurs anytime you call your task or flow with the argument <code>return_state=True</code>.</p> <p>Returning <code>PrefectFuture</code> is achieved by calling <code>your_task.submit()</code>.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-data","title":"Return Data","text":"<p>By default, running a task will return data:</p> <pre><code>from prefect import flow, task \n\n@task \ndef add_one(x):\n    return x + 1\n\n@flow \ndef my_flow():\n    result = add_one(1) # return int\n</code></pre> <p>The same rule applies for a subflow:</p> <pre><code>@flow \ndef subflow():\n    return 42 \n\n@flow \ndef my_flow():\n    result = subflow() # return data\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-prefect-state","title":"Return Prefect State","text":"<p>To return a <code>State</code> instead, add <code>return_state=True</code> as a parameter of your task call.</p> <pre><code>@flow \ndef my_flow():\n    state = add_one(1, return_state=True) # return State\n</code></pre> <p>To get data from a <code>State</code>, call <code>.result()</code>.</p> <pre><code>@flow \ndef my_flow():\n    state = add_one(1, return_state=True) # return State\n    result = state.result() # return int\n</code></pre> <p>The same rule applies for a subflow:</p> <pre><code>@flow \ndef subflow():\n    return 42 \n\n@flow \ndef my_flow():\n    state = subflow(return_state=True) # return State\n    result = state.result() # return int\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#return-a-prefectfuture","title":"Return a PrefectFuture","text":"<p>To get a <code>PrefectFuture</code>, add <code>.submit()</code> to your task call.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n</code></pre> <p>To get data from a <code>PrefectFuture</code>, call <code>.result()</code>.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n    result = future.result() # return data\n</code></pre> <p>To get a <code>State</code> from a <code>PrefectFuture</code>, call <code>.wait()</code>.</p> <pre><code>@flow \ndef my_flow():\n    future = add_one.submit(1) # return PrefectFuture\n    state = future.wait() # return State\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#final-state-determination","title":"Final state determination","text":"<p>The final state of a flow is determined by its return value.  The following rules apply:</p> <ul> <li>If an exception is raised directly in the flow function, the flow run is marked as <code>FAILED</code>.</li> <li>If the flow does not return a value (or returns <code>None</code>), its state is determined by the states of all of the tasks and subflows within it.</li> <li>If any task run or subflow run failed and none were cancelled, then the final flow run state is marked as <code>FAILED</code>.</li> <li>If any task run or subflow run was cancelled, then the final flow run state is marked as <code>CANCELLED</code>.</li> <li>If a flow returns a manually created state, it is used as the state of the final flow run. This allows for manual determination of final state.</li> <li>If the flow run returns any other object, then it is marked as successfully completed.</li> </ul> <p>See the Final state determination section of the Flows documentation for further details and examples.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#state-change-hooks","title":"State Change Hooks","text":"<p>State change hooks execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow.</p>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#a-simple-example","title":"A simple example","text":"<pre><code>from prefect import flow\n\ndef my_success_hook(flow, flow_run, state):\n    print(\"Flow run succeeded!\")\n\n@flow(on_completion=[my_success_hook])\ndef my_flow():\n    return 42\n\nmy_flow()\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-and-use-hooks","title":"Create and use hooks","text":"","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#available-state-change-hooks","title":"Available state change hooks","text":"Type Flow Task Description <code>on_completion</code> \u2713 \u2713 Executes when a flow or task run enters a <code>Completed</code> state. <code>on_failure</code> \u2713 \u2713 Executes when a flow or task run enters a <code>Failed</code> state. <code>on_cancellation</code> \u2713 - Executes when a flow run enters a <code>Cancelling</code> state. <code>on_crashed</code> \u2713 - Executes when a flow run enters a <code>Crashed</code> state. <code>on_running</code> \u2713 - Executes when a flow run enters a <code>Running</code> state.","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-flow-run-state-change-hooks","title":"Create flow run state change hooks","text":"<pre><code>def my_flow_hook(flow: Flow, flow_run: FlowRun, state: State):\n    \"\"\"This is the required signature for a flow run state\n    change hook. This hook can only be passed into flows.\n    \"\"\"\n\n# pass hook as a list of callables\n@flow(on_completion=[my_flow_hook])\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#create-task-run-state-change-hooks","title":"Create task run state change hooks","text":"<pre><code>def my_task_hook(task: Task, task_run: TaskRun, state: State):\n    \"\"\"This is the required signature for a task run state change\n    hook. This hook can only be passed into tasks.\n    \"\"\"\n\n# pass hook as a list of callables\n@task(on_failure=[my_task_hook])\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#use-multiple-state-change-hooks","title":"Use multiple state change hooks","text":"<p>State change hooks are versatile, allowing you to specify multiple state change hooks for the same state transition, or to use the same state change hook for different transitions:</p> <pre><code>def my_success_hook(task, task_run, state):\n    print(\"Task run succeeded!\")\n\ndef my_failure_hook(task, task_run, state):\n    print(\"Task run failed!\")\n\ndef my_succeed_or_fail_hook(task, task_run, state):\n    print(\"If the task run succeeds or fails, this hook runs.\")\n\n@task(\n    on_completion=[my_success_hook, my_succeed_or_fail_hook],\n    on_failure=[my_failure_hook, my_succeed_or_fail_hook]\n)\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#pass-kwargs-to-your-hooks","title":"Pass <code>kwargs</code> to your hooks","text":"<p>The Prefect engine will call your hooks for you upon the state change, passing in the flow, flow run, and state objects.</p> <p>However, you can define your hook to have additional default arguments:</p> <pre><code>from prefect import flow\n\ndata = {}\n\ndef my_hook(flow, flow_run, state, my_arg=\"custom_value\"):\n    data.update(my_arg=my_arg, state=state)\n\n@flow(on_completion=[my_hook])\ndef lazy_flow():\n    pass\n\nstate = lazy_flow(return_state=True)\n\nassert data == {\"my_arg\": \"custom_value\", \"state\": state}\n</code></pre> <p>... or define your hook to accept arbitrary keyword arguments:</p> <pre><code>from functools import partial\nfrom prefect import flow, task\n\ndata = {}\n\ndef my_hook(task, task_run, state, **kwargs):\n    data.update(state=state, **kwargs)\n\n@task\ndef bad_task():\n    raise ValueError(\"meh\")\n\n@flow\ndef ok_with_failure_flow(x: str = \"foo\", y: int = 42):\n    bad_task_with_a_hook = bad_task.with_options(\n        on_failure=[partial(my_hook, **dict(x=x, y=y))]\n    )\n    # return a tuple of \"bar\" and the task run state\n    # to avoid raising the task's exception\n    return \"bar\", bad_task_with_a_hook(return_state=True)\n\n_, task_run_state = ok_with_failure_flow()\n\nassert data == {\"x\": \"foo\", \"y\": 42, \"state\": task_run_state}\n</code></pre>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/states/#more-examples-of-state-change-hooks","title":"More examples of state change hooks","text":"<ul> <li>Send a notification when a flow run fails</li> <li>Delete a Cloud Run job when a flow crashes</li> </ul>","tags":["orchestration","flow runs","task runs","states","status","state change hooks","triggers"],"boost":2},{"location":"concepts/storage/","title":"Storage","text":"<p>Storage blocks are not recommended</p> <p>Storage blocks are part of the legacy block-based deployment model. Instead, using <code>serve</code> or <code>runner</code>-based Python creation methods or workers and work pools with <code>prefect deploy</code> via the CLI are the recommended options for creating a deployment.  Flow code storage can be specified in the Python file with <code>serve</code> or <code>runner</code>-based Python creation methods; alternatively, with the work pools and workers style of flow deployment, you can specify flow code storage during the interactive <code>prefect deploy</code> CLI experience and in its resulting <code>prefect.yaml</code> file. </p> <p>Storage lets you configure how flow code for deployments is persisted and retrieved by Prefect workers (or legacy agents). Anytime you build a block-based deployment, a storage block is used to upload the entire directory containing your workflow code (along with supporting files) to its configured location.  This helps ensure portability of your relative imports, configuration files, and more.  Note that your environment dependencies (for example, external Python packages) still need to be managed separately.</p> <p>If no storage is explicitly configured, Prefect will use <code>LocalFileSystem</code> storage by default. Local storage works fine for many local flow run scenarios, especially when testing and getting started. However, due to the inherent lack of portability, many use cases are better served by using remote storage such as S3 or Google Cloud Storage.</p> <p>Prefect supports creating multiple storage configurations and switching between storage as needed.</p> <p>Storage uses blocks</p> <p>Blocks are the Prefect technology underlying storage, and enables you to do so much more.</p> <p>In addition to creating storage blocks via the Prefect CLI, you can now create storage blocks and other kinds of block configuration objects via the Prefect UI and Prefect Cloud.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#configuring-storage-for-a-deployment","title":"Configuring storage for a deployment","text":"<p>When building a deployment for a workflow, you have two options for configuring workflow storage:</p> <ul> <li>Use the default local storage</li> <li>Preconfigure a storage block to use</li> </ul>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#using-the-default","title":"Using the default","text":"<p>Anytime you call <code>prefect deployment build</code> without providing the <code>--storage-block</code> flag, a default <code>LocalFileSystem</code> block will be used.  Note that this block will always use your present working directory as its basepath (which is usually desirable).  You can see the block's settings by inspecting the <code>deployment.yaml</code> file that Prefect creates after calling <code>prefect deployment build</code>.</p> <p>While you generally can't run a deployment stored on a local file system on other machines, any agent running on the same machine will be able to successfully run your deployment.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#supported-storage-blocks","title":"Supported storage blocks","text":"<p>Current options for deployment storage blocks include:</p> Storage Description Required Library Local File System Store code in a run's local file system. Remote File System Store code in a any filesystem supported by <code>fsspec</code>. AWS S3 Storage Store code in an AWS S3 bucket. <code>s3fs</code> Azure Storage Store code in Azure Datalake and Azure Blob Storage. <code>adlfs</code> GitHub Storage Store code in a GitHub repository. Google Cloud Storage Store code in a Google Cloud Platform (GCP) Cloud Storage bucket. <code>gcsfs</code> SMB Store code in SMB shared network storage. <code>smbprotocol</code> GitLab Repository Store code in a GitLab repository. <code>prefect-gitlab</code> Bitbucket Repository Store code in a Bitbucket repository. <code>prefect-bitbucket</code> <p>Accessing files may require storage filesystem libraries</p> <p>Note that the appropriate filesystem library supporting the storage location must be installed prior to building a deployment with a storage block or accessing the storage location from flow scripts.</p> <p>For example, the AWS S3 Storage block requires the <code>s3fs</code> library.</p> <p>See Filesystem package dependencies for more information about configuring filesystem libraries in your execution environment.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/storage/#configuring-a-block","title":"Configuring a block","text":"<p>You can create these blocks either via the UI or via Python.</p> <p>You can create, edit, and manage storage blocks in the Prefect UI and Prefect Cloud. On a Prefect server, blocks are created in the server's database. On Prefect Cloud, blocks are created on a workspace.</p> <p>To create a new block, select the + button. Prefect displays a library of block types you can configure to create blocks to be used by your flows.</p> <p></p> <p>Select Add + to configure a new storage block based on a specific block type. Prefect displays a Create page that enables specifying storage settings.</p> <p></p> <p>You can also create blocks using the Prefect Python API:</p> <pre><code>from prefect.filesystems import S3\n\nblock = S3(bucket_path=\"my-bucket/a-sub-directory\", \n           aws_access_key_id=\"foo\", \n           aws_secret_access_key=\"bar\"\n)\nblock.save(\"example-block\")\n</code></pre> <p>This block configuration is now available to be used by anyone with appropriate access to your Prefect API.  We can use this block to build a deployment by passing its slug to the <code>prefect deployment build</code> command. The storage block slug is formatted as <code>block-type/block-name</code>. In this case, <code>s3/example-block</code> for an AWS S3 Bucket block named <code>example-block</code>. See block identifiers for details.</p> <pre><code>prefect deployment build ./flows/my_flow.py:my_flow --name \"Example Deployment\" --storage-block s3/example-block\n</code></pre> <p>This command will upload the contents of your flow's directory to the designated storage location, then the full deployment specification will be persisted to a newly created <code>deployment.yaml</code> file.  For more information, see Deployments.</p>","tags":["storage","databases","database configuration","configuration","settings","AWS S3","Azure Blob Storage","Google Cloud Storage","SMB"],"boost":0.5},{"location":"concepts/task-runners/","title":"Task runners","text":"<p>Task runners enable you to engage specific executors for Prefect tasks, such as for concurrent, parallel, or distributed execution of tasks.</p> <p>Task runners are not required for task execution. If you call a task function directly, the task executes as a regular Python function, without a task runner, and produces whatever result is returned by the function.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#task-runner-overview","title":"Task runner overview","text":"<p>Calling a task function from within a flow, using the default task settings, executes the function sequentially. Execution of the task function blocks execution of the flow until the task completes. This means, by default, calling multiple tasks in a flow causes them to run in order. </p> <p>However, that's not the only way to run tasks!</p> <p>You can use the <code>.submit()</code> method on a task function to submit the task to a task runner. Using a task runner enables you to control whether tasks run sequentially, concurrently, or if you want to take advantage of a parallel or distributed execution library such as Dask or Ray.</p> <p>Using the <code>.submit()</code> method to submit a task also causes the task run to return a <code>PrefectFuture</code>, a Prefect object that contains both any data returned by the task function and a <code>State</code>, a Prefect object indicating the state of the task run.</p> <p>Prefect currently provides the following built-in task runners: </p> <ul> <li><code>SequentialTaskRunner</code> can run tasks sequentially. </li> <li><code>ConcurrentTaskRunner</code> can run tasks concurrently, allowing tasks to switch when blocking on IO. Tasks will be submitted to a thread pool maintained by <code>anyio</code>.</li> </ul> <p>In addition, the following Prefect-developed task runners for parallel or distributed task execution may be installed as Prefect Integrations. </p> <ul> <li><code>DaskTaskRunner</code> can run tasks requiring parallel execution using <code>dask.distributed</code>. </li> <li><code>RayTaskRunner</code> can run tasks requiring parallel execution using Ray.</li> </ul> <p>Concurrency versus parallelism</p> <p>The words \"concurrency\" and \"parallelism\" may sound the same, but they mean different things in computing.</p> <p>Concurrency refers to a system that can do more than one thing simultaneously, but not at the exact same time. It may be more accurate to think of concurrent execution as non-blocking: within the restrictions of resources available in the execution environment and data dependencies between tasks, execution of one task does not block execution of other tasks in a flow.</p> <p>Parallelism refers to a system that can do more than one thing at the exact same time. Again, within the restrictions of resources available, parallel execution can run tasks at the same time, such as for operations mapped across a dataset.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-a-task-runner","title":"Using a task runner","text":"<p>You do not need to specify a task runner for a flow unless your tasks require a specific type of execution. </p> <p>To configure your flow to use a specific task runner, import a task runner and assign it as an argument for the flow when the flow is defined.</p> <p>Remember to call <code>.submit()</code> when using a task runner</p> <p>Make sure you use <code>.submit()</code> to run your task with a task runner. Calling the task directly, without <code>.submit()</code>, from within a flow will run the task sequentially instead of using a specified task runner.</p> <p>For example, you can use <code>ConcurrentTaskRunner</code> to allow tasks to switch when they would block.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import ConcurrentTaskRunner\nimport time\n\n@task\ndef stop_at_floor(floor):\n    print(f\"elevator moving to floor {floor}\")\n    time.sleep(floor)\n    print(f\"elevator stops on floor {floor}\")\n\n@flow(task_runner=ConcurrentTaskRunner())\ndef elevator():\n    for floor in range(10, 0, -1):\n        stop_at_floor.submit(floor)\n</code></pre> <p>If you specify an uninitialized task runner class, a task runner instance of that type is created with the default settings. You can also pass additional configuration parameters for task runners that accept parameters, such as <code>DaskTaskRunner</code> and <code>RayTaskRunner</code>.</p> <p>Default task runner</p> <p>If you don't specify a task runner for a flow and you call a task with <code>.submit()</code> within the flow, Prefect uses the default <code>ConcurrentTaskRunner</code>.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-sequentially","title":"Running tasks sequentially","text":"<p>Sometimes, it's useful to force tasks to run sequentially to make it easier to reason about the behavior of your program. Switching to the <code>SequentialTaskRunner</code> will force submitted tasks to run sequentially rather than concurrently.</p> <p>Synchronous and asynchronous tasks</p> <p>The <code>SequentialTaskRunner</code> works with both synchronous and asynchronous task functions. Asynchronous tasks are Python functions defined using <code>async def</code> rather than <code>def</code>.</p> <p>The following example demonstrates using the <code>SequentialTaskRunner</code> to ensure that tasks run sequentially. In the example, the flow <code>glass_tower</code> runs the task <code>stop_at_floor</code> for floors one through 38, in that order.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\nimport random\n\n@task\ndef stop_at_floor(floor):\n    situation = random.choice([\"on fire\",\"clear\"])\n    print(f\"elevator stops on {floor} which is {situation}\")\n\n@flow(task_runner=SequentialTaskRunner(),\n      name=\"towering-infernflow\",\n      )\ndef glass_tower():\n    for floor in range(1, 39):\n        stop_at_floor.submit(floor)\n\nglass_tower()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-multiple-task-runners","title":"Using multiple task runners","text":"<p>Each flow can only have a single task runner, but sometimes you may want a subset of your tasks to run using a specific task runner. In this case, you can create subflows for tasks that need to use a different task runner.</p> <p>For example, you can have a flow (in the example below called <code>sequential_flow</code>) that runs its tasks locally using the <code>SequentialTaskRunner</code>. If you have some tasks that can run more efficiently in parallel on a Dask cluster, you could create a subflow (such as <code>dask_subflow</code>) to run those tasks using the <code>DaskTaskRunner</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef hello_local():\n    print(\"Hello!\")\n\n@task\ndef hello_dask():\n    print(\"Hello from Dask!\")\n\n@flow(task_runner=SequentialTaskRunner())\ndef sequential_flow():\n    hello_local.submit()\n    dask_subflow()\n    hello_local.submit()\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_subflow():\n    hello_dask.submit()\n\nif __name__ == \"__main__\":\n    sequential_flow()\n</code></pre> <p>Guarding main</p> <p>Note that you should guard the <code>main</code> function by using <code>if __name__ == \"__main__\"</code> to avoid issues with parallel processing. </p> <p>This script outputs the following logs demonstrating the use of the Dask task runner:</p> <pre><code>120:14:29.785 | INFO    | prefect.engine - Created flow run 'ivory-caiman' for flow 'sequential-flow'\n20:14:29.785 | INFO    | Flow run 'ivory-caiman' - Starting 'SequentialTaskRunner'; submitted tasks will be run sequentially...\n20:14:29.880 | INFO    | Flow run 'ivory-caiman' - Created task run 'hello_local-7633879f-0' for task 'hello_local'\n20:14:29.881 | INFO    | Flow run 'ivory-caiman' - Executing 'hello_local-7633879f-0' immediately...\nHello!\n20:14:29.904 | INFO    | Task run 'hello_local-7633879f-0' - Finished in state Completed()\n20:14:29.952 | INFO    | Flow run 'ivory-caiman' - Created subflow run 'nimble-sparrow' for flow 'dask-subflow'\n20:14:29.953 | INFO    | prefect.task_runner.dask - Creating a new Dask cluster with `distributed.deploy.local.LocalCluster`\n20:14:31.862 | INFO    | prefect.task_runner.dask - The Dask dashboard is available at http://127.0.0.1:8787/status\n20:14:31.901 | INFO    | Flow run 'nimble-sparrow' - Created task run 'hello_dask-2b96d711-0' for task 'hello_dask'\n20:14:32.370 | INFO    | Flow run 'nimble-sparrow' - Submitted task run 'hello_dask-2b96d711-0' for execution.\nHello from Dask!\n20:14:33.358 | INFO    | Flow run 'nimble-sparrow' - Finished in state Completed('All states completed.')\n20:14:33.368 | INFO    | Flow run 'ivory-caiman' - Created task run 'hello_local-7633879f-1' for task 'hello_local'\n20:14:33.368 | INFO    | Flow run 'ivory-caiman' - Executing 'hello_local-7633879f-1' immediately...\nHello!\n20:14:33.386 | INFO    | Task run 'hello_local-7633879f-1' - Finished in state Completed()\n20:14:33.399 | INFO    | Flow run 'ivory-caiman' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-results-from-submitted-tasks","title":"Using results from submitted tasks","text":"<p>When you use <code>.submit()</code> to submit a task to a task runner, the task runner creates a <code>PrefectFuture</code> for access to the state and result of the task.</p> <p>A <code>PrefectFuture</code> is an object that provides access to a computation happening in a task runner \u2014 even if that computation is happening on a remote system.</p> <p>In the following example, we save the return value of calling <code>.submit()</code> on the task <code>say_hello</code> to the variable <code>future</code>, and then we print the type of the variable:</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@flow\ndef hello_world():\n    future = say_hello.submit(\"Marvin\")\n    print(f\"variable 'future' is type {type(future)}\")\n\nhello_world()\n</code></pre> <p>When you run this code, you'll see that the variable <code>future</code> is a <code>PrefectFuture</code>:</p> <pre><code>variable 'future' is type &lt;class 'prefect.futures.PrefectFuture'&gt;\n</code></pre> <p>When you pass a future into a task, Prefect waits for the \"upstream\" task \u2014 the one that the future references \u2014 to reach a final state before starting the downstream task.</p> <p>This means that the downstream task won't receive the <code>PrefectFuture</code> you passed as an argument. Instead, the downstream task will receive the value that the upstream task returned.</p> <p>Take a look at how this works in the following example</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef print_result(result):\n    print(type(result))\n    print(result)\n\n@flow(name=\"hello-flow\")\ndef hello_world():\n    future = say_hello.submit(\"Marvin\")\n    print_result.submit(future)\n\nhello_world()\n</code></pre> <pre><code>&lt;class 'str'&gt;\nHello Marvin!\n</code></pre> <p>Futures have a few useful methods. For example, you can get the return value of the task run with  <code>.result()</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return 42\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    result = future.result()\n    print(result)\n\nmy_flow()\n</code></pre> <p>The <code>.result()</code> method will wait for the task to complete before returning the result to the caller. If the task run fails, <code>.result()</code> will raise the task run's exception. You may disable this behavior with the <code>raise_on_failure</code> option:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    return \"I'm a task!\"\n\n\n@flow\ndef my_flow():\n    future = my_task.submit()\n    result = future.result(raise_on_failure=False)\n    if future.get_state().is_failed():\n        # `result` is an exception! handle accordingly\n        ...\n    else:\n        # `result` is the expected return value of our task\n        ...\n</code></pre> <p>You can retrieve the current state of the task run associated with the <code>PrefectFuture</code> using <code>.get_state()</code>:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    state = future.get_state()\n</code></pre> <p>You can also wait for a task to complete by using the <code>.wait()</code> method:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    final_state = future.wait()\n</code></pre> <p>You can include a timeout in the <code>wait</code> call to perform logic if the task has not finished in a given amount of time:</p> <pre><code>@flow\ndef my_flow():\n    future = my_task.submit()\n    final_state = future.wait(1)  # Wait one second max\n    if final_state:\n        # Take action if the task is done\n        result = final_state.result()\n    else:\n        ... # Task action if the task is still running\n</code></pre> <p>You may also use the <code>wait_for=[]</code> parameter when calling a task, specifying upstream task dependencies. This enables you to control task execution order for tasks that do not share data dependencies.</p> <pre><code>@task\ndef task_a():\n    pass\n\n@task\ndef task_b():\n    pass\n\n@task\ndef task_c():\n    pass\n\n@task\ndef task_d():\n    pass\n\n@flow\ndef my_flow():\n    a = task_a.submit()\n    b = task_b.submit()\n    # Wait for task_a and task_b to complete\n    c = task_c.submit(wait_for=[a, b])\n    # task_d will wait for task_c to complete\n    # Note: If waiting for one task it must still be in a list.\n    d = task_d(wait_for=[c])\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#when-to-use-result-in-flows","title":"When to use <code>.result()</code> in flows","text":"<p>The simplest pattern for writing a flow is either only using tasks or only using pure Python functions. When you need to mix the two, use <code>.result()</code>.</p> <p>Using only tasks:</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    hello = say_hello.submit(\"Marvin\")\n    nice_to_meet_you = say_nice_to_meet_you.submit(hello)\n\nhello_world()\n</code></pre> <p>Using only Python functions:</p> <pre><code>from prefect import flow, task\n\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    # because this is just a Python function, calls will not be tracked\n    hello = say_hello(\"Marvin\") \n    nice_to_meet_you = say_nice_to_meet_you(hello)\n\nhello_world()\n</code></pre> <p>Mixing tasks and Python functions:</p> <pre><code>from prefect import flow, task\n\ndef say_hello_extra_nicely_to_marvin(hello): # not a task or flow!\n    if hello == \"Hello Marvin!\":\n        return \"HI MARVIN!\"\n    return hello\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef say_nice_to_meet_you(hello_greeting):\n    return f\"{hello_greeting} Nice to meet you :)\"\n\n@flow\ndef hello_world():\n    # run a task and get the result\n    hello = say_hello.submit(\"Marvin\").result()\n\n    # not calling a task or flow\n    special_greeting = say_hello_extra_nicely_to_marvin(hello)\n\n    # pass our modified greeting back into a task\n    nice_to_meet_you = say_nice_to_meet_you.submit(special_greeting)\n\n    print(nice_to_meet_you.result())\n\nhello_world()\n</code></pre> <p>Note that <code>.result()</code> also limits Prefect's ability to track task dependencies. In the \"mixed\" example above, Prefect will not be aware that <code>say_hello</code> is upstream of <code>nice_to_meet_you</code>.</p> <p>Calling <code>.result()</code> is blocking</p> <p>When calling <code>.result()</code>, be mindful your flow function will have to wait until the task run is completed before continuing.</p> <pre><code>from prefect import flow, task\n\n@task\ndef say_hello(name):\n    return f\"Hello {name}!\"\n\n@task\ndef do_important_stuff():\n    print(\"Doing lots of important stuff!\")\n\n@flow\ndef hello_world():\n    # blocks until `say_hello` has finished\n    result = say_hello.submit(\"Marvin\").result() \n    do_important_stuff.submit()\n\nhello_world()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-on-dask","title":"Running tasks on Dask","text":"<p>The <code>DaskTaskRunner</code> is a parallel task runner that submits tasks to the <code>dask.distributed</code> scheduler. By default, a temporary Dask cluster is created for the duration of the flow run. If you already have a Dask cluster running, either local or cloud hosted, you can provide the connection URL via the <code>address</code> kwarg.</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed: <code>pip install prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>DaskTaskRunner</code> configured to access an existing Dask cluster at <code>http://my-dask-cluster</code>.</p> <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner(address=\"http://my-dask-cluster\"))\ndef my_flow():\n    ...\n</code></pre> <p><code>DaskTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Dask scheduler. cluster_class The cluster class to use when creating a temporary Dask cluster. It can be either the full class name (for example, <code>\"distributed.LocalCluster\"</code>), or the class itself. cluster_kwargs Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary Dask cluster. adapt_kwargs Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary Dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided. client_kwargs Additional kwargs to use when creating a <code>dask.distributed.Client</code>. <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or you will encounter  warnings and errors.</p> <p>If you don't provide the <code>address</code> of a Dask scheduler, Prefect creates a temporary local cluster automatically. The number of workers used is based on the number of cores on your machine. The default provides a mix of processes and threads that should work well for most workloads. If you want to specify this explicitly, you can pass values for <code>n_workers</code> or <code>threads_per_worker</code> to <code>cluster_kwargs</code>.</p> <pre><code># Use 4 worker processes, each with 2 threads\nDaskTaskRunner(\n    cluster_kwargs={\"n_workers\": 4, \"threads_per_worker\": 2}\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#using-a-temporary-cluster","title":"Using a temporary cluster","text":"<p>The <code>DaskTaskRunner</code> is capable of creating a temporary cluster using any of Dask's cluster-manager options. This can be useful when you want each flow run to have its own Dask cluster, allowing for per-flow adaptive scaling.</p> <p>To configure, you need to provide a <code>cluster_class</code>. This can be:</p> <ul> <li>A string specifying the import path to the cluster class (for example, <code>\"dask_cloudprovider.aws.FargateCluster\"</code>)</li> <li>The cluster class itself</li> <li>A function for creating a custom cluster. </li> </ul> <p>You can also configure <code>cluster_kwargs</code>, which takes a dictionary of keyword arguments to pass to <code>cluster_class</code> when starting the flow run.</p> <p>For example, to configure a flow to use a temporary <code>dask_cloudprovider.aws.FargateCluster</code> with 4 workers running with an image named <code>my-prefect-image</code>:</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    cluster_kwargs={\"n_workers\": 4, \"image\": \"my-prefect-image\"},\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#connecting-to-an-existing-cluster","title":"Connecting to an existing cluster","text":"<p>Multiple Prefect flow runs can all use the same existing Dask cluster. You might manage a single long-running Dask cluster (maybe using the Dask  Helm Chart) and configure flows to connect to it during execution. This has a few downsides when compared to using a temporary cluster (as described above):</p> <ul> <li>All workers in the cluster must have dependencies installed for all flows you   intend to run.</li> <li>Multiple flow runs may compete for resources. Dask tries to do a good job   sharing resources between tasks, but you may still run into issues.</li> </ul> <p>That said, you may prefer managing a single long-running cluster. </p> <p>To configure a <code>DaskTaskRunner</code> to connect to an existing cluster, pass in the address of the scheduler to the <code>address</code> argument:</p> <pre><code># Connect to an existing cluster running at a specified address\nDaskTaskRunner(address=\"tcp://...\")\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#adaptive-scaling","title":"Adaptive scaling","text":"<p>One nice feature of using a <code>DaskTaskRunner</code> is the ability to scale adaptively to the workload. Instead of specifying <code>n_workers</code> as a fixed number, this lets you specify a minimum and maximum number of workers to use, and the dask cluster will scale up and down as needed.</p> <p>To do this, you can pass <code>adapt_kwargs</code> to <code>DaskTaskRunner</code>. This takes the following fields:</p> <ul> <li><code>maximum</code> (<code>int</code> or <code>None</code>, optional): the maximum number of workers to scale   to. Set to <code>None</code> for no maximum.</li> <li><code>minimum</code> (<code>int</code> or <code>None</code>, optional): the minimum number of workers to scale   to. Set to <code>None</code> for no minimum.</li> </ul> <p>For example, here we configure a flow to run on a <code>FargateCluster</code> scaling up to at most 10 workers.</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    adapt_kwargs={\"maximum\": 10}\n)\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#dask-annotations","title":"Dask annotations","text":"<p>Dask annotations can be used to further control the behavior of tasks.</p> <p>For example, we can set the priority of tasks in the Dask scheduler:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n\n@flow(task_runner=DaskTaskRunner())\ndef my_flow():\n    with dask.annotate(priority=-10):\n        future = show.submit(1)  # low priority task\n\n    with dask.annotate(priority=10):\n        future = show.submit(2)  # high priority task\n</code></pre> <p>Another common use case is resource annotations:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n# Create a `LocalCluster` with some resource annotations\n# Annotations are abstract in dask and not inferred from your system.\n# Here, we claim that our system has 1 GPU and 1 process available per worker\n@flow(\n    task_runner=DaskTaskRunner(\n        cluster_kwargs={\"n_workers\": 1, \"resources\": {\"GPU\": 1, \"process\": 1}}\n    )\n)\n\ndef my_flow():\n    with dask.annotate(resources={'GPU': 1}):\n        future = show(0)  # this task requires 1 GPU resource on a worker\n\n    with dask.annotate(resources={'process': 1}):\n        # These tasks each require 1 process on a worker; because we've \n        # specified that our cluster has 1 process per worker and 1 worker,\n        # these tasks will run sequentially\n        future = show(1)\n        future = show(2)\n        future = show(3)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/task-runners/#running-tasks-on-ray","title":"Running tasks on Ray","text":"<p>The <code>RayTaskRunner</code> \u2014 installed separately as a Prefect Collection \u2014 is a parallel task runner that submits tasks to Ray. By default, a temporary Ray instance is created for the duration of the flow run. If you already have a Ray instance running, you can provide the connection URL via an <code>address</code> argument.</p> <p>Remote storage and Ray tasks</p> <p>We recommend configuring remote storage for task execution with the <code>RayTaskRunner</code>. This ensures tasks executing in Ray have access to task result storage, particularly when accessing a Ray instance outside of your execution environment.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-ray</code> collection is installed: <code>pip install prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>RayTaskRunner</code> configured to access an existing Ray instance at <code>ray://192.0.2.255:8786</code>.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner(address=\"ray://192.0.2.255:8786\"))\ndef my_flow():\n    ... \n</code></pre> <p><code>RayTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Ray instance, starting with the ray:// URI. init_kwargs Additional kwargs to use when calling <code>ray.init</code>. <p>Note that Ray Client uses the ray:// URI to indicate the address of a Ray instance. If you don't provide the <code>address</code> of a Ray instance, Prefect creates a temporary instance automatically.</p> <p>Ray environment limitations</p> <p>While we're excited about adding support for parallel task execution via Ray to Prefect, there are some inherent limitations with Ray you should be aware of:</p> <p>Ray's support for Python 3.11 is experimental.</p> <p>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</p> <p>See the Ray installation documentation for further compatibility information.</p>","tags":["tasks","task runners","executors","PrefectFuture","submit","concurrent execution","sequential execution","parallel execution","Dask","Ray"],"boost":2},{"location":"concepts/tasks/","title":"Tasks","text":"<p>A task is a function that represents a discrete unit of work in a Prefect workflow. Tasks are not required \u2014 you may define Prefect workflows that consist only of flows, using regular Python statements and functions. Tasks enable you to encapsulate elements of your workflow logic in observable units that can be reused across flows and subflows.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#tasks-overview","title":"Tasks overview","text":"<p>Tasks are functions: they can take inputs, perform work, and return an output. A Prefect task can do almost anything a Python function can do.  </p> <p>Tasks are special because they receive metadata about upstream dependencies and the state of those dependencies before they run, even if they don't receive any explicit data inputs from them. This gives you the opportunity to, for example, have a task wait on the completion of another task before executing.</p> <p>Tasks also take advantage of automatic Prefect logging to capture details about task runs such as runtime, tags, and final state.</p> <p>You can define your tasks within the same file as your flow definition, or you can define tasks within modules and import them for use in your flow definitions. Tasks may be called from within a flow, from within a subflow, or (as of <code>prefect 2.18.x</code>) from within another task.</p> <p>Calling a task from a flow</p> <p>Use the <code>@task</code> decorator to designate a function as a task. Calling the task creates a new task run:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@flow\ndef my_flow():\n    my_task()\n</code></pre> <p>Calling a task from another task</p> <p>As of <code>prefect 2.18.x</code>, you can call a task from within another task:</p> <pre><code>from prefect import task\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@task(log_prints=True)\ndef my_parent_task():\n    my_task()\n</code></pre> <p>Tasks are uniquely identified by a task key, which is a hash composed of the task name, the fully-qualified name of the function, and any tags. If the task does not have a name specified, the name is derived from the task function.</p> <p>How big should a task be?</p> <p>Prefect encourages \"small tasks\" \u2014 each one should represent a single logical step of your workflow. This allows Prefect to better contain task failures.</p> <p>To be clear, there's nothing stopping you from putting all of your code in a single task \u2014 Prefect will happily run it! However, if any line of code fails, the entire task will fail and must be retried from the beginning. This can be avoided by splitting the code into multiple dependent tasks.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-arguments","title":"Task arguments","text":"<p>Tasks allow for customization through optional arguments:</p> Argument Description <code>name</code> An optional name for the task. If not provided, the name will be inferred from the function name. <code>description</code> An optional string description for the task. If not provided, the description will be pulled from the docstring for the decorated function. <code>tags</code> An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a <code>prefect.tags</code> context at task runtime. <code>cache_key_fn</code> An optional callable that, given the task run context and call parameters, generates a string key. If the key matches a previous completed state, that state result will be restored instead of running the task again. <code>cache_expiration</code> An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire. <code>retries</code> An optional number of times to retry on task run failure. <code>retry_delay_seconds</code> An optional number of seconds to wait before retrying the task after failure. This is only applicable if <code>retries</code> is nonzero. <code>log_prints</code> An optional boolean indicating whether to log print statements. <code>persist_result</code> An optional boolean indicating whether to persist the result of the task run to storage. <p>See all possible parameters in the Python SDK API docs.</p> <p>For example, you can provide a <code>name</code> value for the task. Here we've used the optional <code>description</code> argument as well.</p> <pre><code>@task(name=\"hello-task\", \n      description=\"This task says hello.\")\ndef my_task():\n    print(\"Hello, I'm a task\")\n</code></pre> <p>You can distinguish runs of this task by providing a <code>task_run_name</code>; this setting accepts a string that can optionally contain templated references to the keyword arguments of your task. The name will be formatted using Python's standard string formatting syntax as can be seen here:</p> <pre><code>import datetime\nfrom prefect import flow, task\n\n@task(name=\"My Example Task\", \n      description=\"An example task for a tutorial.\",\n      task_run_name=\"hello-{name}-on-{date:%A}\")\ndef my_task(name, date):\n    pass\n\n@flow\ndef my_flow():\n    # creates a run with a name like \"hello-marvin-on-Thursday\"\n    my_task(name=\"marvin\", date=datetime.datetime.now(datetime.timezone.utc))\n</code></pre> <p>Additionally this setting also accepts a function that returns a string to be used for the task run name:</p> <pre><code>import datetime\nfrom prefect import flow, task\n\ndef generate_task_name():\n    date = datetime.datetime.now(datetime.timezone.utc)\n    return f\"{date:%A}-is-a-lovely-day\"\n\n@task(name=\"My Example Task\",\n      description=\"An example task for a tutorial.\",\n      task_run_name=generate_task_name)\ndef my_task(name):\n    pass\n\n@flow\ndef my_flow():\n    # creates a run with a name like \"Thursday-is-a-lovely-day\"\n    my_task(name=\"marvin\")\n</code></pre> <p>If you need access to information about the task, use the <code>prefect.runtime</code> module. For example:</p> <pre><code>from prefect import flow\nfrom prefect.runtime import flow_run, task_run\n\ndef generate_task_name():\n    flow_name = flow_run.flow_name\n    task_name = task_run.task_name\n\n    parameters = task_run.parameters\n    name = parameters[\"name\"]\n    limit = parameters[\"limit\"]\n\n    return f\"{flow_name}-{task_name}-with-{name}-and-{limit}\"\n\n@task(name=\"my-example-task\",\n      description=\"An example task for a tutorial.\",\n      task_run_name=generate_task_name)\ndef my_task(name: str, limit: int = 100):\n    pass\n\n@flow\ndef my_flow(name: str):\n    # creates a run with a name like \"my-flow-my-example-task-with-marvin-and-100\"\n    my_task(name=\"marvin\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#tags","title":"Tags","text":"<p>Tags are optional string labels that enable you to identify and group tasks other than by name or flow. Tags are useful for:</p> <ul> <li>Filtering task runs by tag in the UI and via the Prefect REST API.</li> <li>Setting concurrency limits on task runs by tag.</li> </ul> <p>Tags may be specified as a keyword argument on the task decorator.</p> <pre><code>@task(name=\"hello-task\", tags=[\"test\"])\ndef my_task():\n    print(\"Hello, I'm a task\")\n</code></pre> <p>You can also provide tags as an argument with a <code>tags</code> context manager, specifying tags when the task is called rather than in its definition.</p> <pre><code>from prefect import flow, task\nfrom prefect import tags\n\n@task\ndef my_task():\n    print(\"Hello, I'm a task\")\n\n@flow\ndef my_flow():\n    with tags(\"test\"):\n        my_task()\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#retries","title":"Retries","text":"<p>Prefect can automatically retry tasks on failure. In Prefect, a task fails if its Python function raises an exception.</p> <p>To enable retries, pass <code>retries</code> and <code>retry_delay_seconds</code> parameters to your task. If the task fails, Prefect will retry it up to <code>retries</code> times, waiting <code>retry_delay_seconds</code> seconds between each attempt. If the task fails on the final retry, Prefect marks the task as crashed if the task raised an exception or failed if it returned a string.</p> <p>Retries don't create new task runs</p> <p>A new task run is not created when a task is retried. A new state is added to the state history of the original task run.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#a-real-world-example-making-an-api-request","title":"A real-world example: making an API request","text":"<p>Consider the real-world problem of making an API request. In this example, we'll use the <code>httpx</code> library to make an HTTP request.</p> <pre><code>import httpx\n\nfrom prefect import flow, task\n\n\n@task(retries=2, retry_delay_seconds=5)\ndef get_data_task(\n    url: str = \"https://api.brittle-service.com/endpoint\"\n) -&gt; dict:\n    response = httpx.get(url)\n\n    # If the response status code is anything but a 2xx, httpx will raise\n    # an exception. This task doesn't handle the exception, so Prefect will\n    # catch the exception and will consider the task run failed.\n    response.raise_for_status()\n\n    return response.json()\n\n\n@flow\ndef get_data_flow():\n    get_data_task()\n</code></pre> <p>In this task, if the HTTP request to the brittle API receives any status code other than a 2xx (200, 201, etc.), Prefect will retry the task a maximum of two times, waiting five seconds in between retries.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#custom-retry-behavior","title":"Custom retry behavior","text":"<p>The <code>retry_delay_seconds</code> option accepts a list of delays for more custom retry behavior. The following task will wait for successively increasing intervals of 1, 10, and 100 seconds, respectively, before the next attempt starts:</p> <pre><code>from prefect import task\n\n@task(retries=3, retry_delay_seconds=[1, 10, 100])\ndef some_task_with_manual_backoff_retries():\n   ...\n</code></pre> <p>The <code>retry_condition_fn</code> option accepts a callable that returns a boolean. If the callable returns <code>True</code>, the task will be retried. If the callable returns <code>False</code>, the task will not be retried. The callable accepts three arguments \u2014 the task, the task run, and the state of the task run. The following task will retry on HTTP status codes other than 401 or 404:</p> <pre><code>import httpx\nfrom prefect import flow, task\n\ndef retry_handler(task, task_run, state) -&gt; bool:\n    \"\"\"This is a custom retry handler to handle when we want to retry a task\"\"\"\n    try:\n        # Attempt to get the result of the task\n        state.result()\n    except httpx.HTTPStatusError as exc:\n        # Retry on any HTTP status code that is not 401 or 404\n        do_not_retry_on_these_codes = [401, 404]\n        return exc.response.status_code not in do_not_retry_on_these_codes\n    except httpx.ConnectError:\n        # Do not retry\n        return False\n    except:\n        # For any other exception, retry\n        return True\n\n@task(retries=1, retry_condition_fn=retry_handler)\ndef my_api_call_task(url):\n    response = httpx.get(url)\n    response.raise_for_status()\n    return response.json()\n\n@flow\ndef get_data_flow(url):\n    my_api_call_task(url=url)\n\nif __name__ == \"__main__\":\n    get_data_flow(url=\"https://httpbin.org/status/503\")\n</code></pre> <p>Additionally, you can pass a callable that accepts the number of retries as an argument and returns a list. Prefect includes an <code>exponential_backoff</code> utility that will automatically generate a list of retry delays that correspond to an exponential backoff retry strategy. The following flow will wait for 10, 20, then 40 seconds before each retry.</p> <pre><code>from prefect import task\nfrom prefect.tasks import exponential_backoff\n\n@task(retries=3, retry_delay_seconds=exponential_backoff(backoff_factor=10))\ndef some_task_with_exponential_backoff_retries():\n   ...\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#advanced-topic-adding-jitter","title":"Advanced topic: adding \"jitter\"","text":"<p>While using exponential backoff, you may also want to add jitter to the delay times. Jitter is a random amount of time added to retry periods that helps prevent \"thundering herd\" scenarios, which is when many tasks all retry at the exact same time, potentially overwhelming systems.</p> <p>The <code>retry_jitter_factor</code> option can be used to add variance to the base delay. For example, a retry delay of 10 seconds with a <code>retry_jitter_factor</code> of 0.5 will be allowed to delay up to 15 seconds. Large values of <code>retry_jitter_factor</code> provide more protection against \"thundering herds,\" while keeping the average retry delay time constant. For example, the following task adds jitter to its exponential backoff so the retry delays will vary up to a maximum delay time of 20, 40, and 80 seconds respectively.</p> <pre><code>from prefect import task\nfrom prefect.tasks import exponential_backoff\n\n@task(\n    retries=3,\n    retry_delay_seconds=exponential_backoff(backoff_factor=10),\n    retry_jitter_factor=1,\n)\ndef some_task_with_exponential_backoff_retries():\n   ...\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#configuring-retry-behavior-globally-with-settings","title":"Configuring retry behavior globally with settings","text":"<p>You can also set retries and retry delays by using the following global settings. These settings will not override the <code>retries</code> or <code>retry_delay_seconds</code> that are set in the flow or task decorator.</p> <pre><code>prefect config set PREFECT_FLOW_DEFAULT_RETRIES=2\nprefect config set PREFECT_TASK_DEFAULT_RETRIES=2\nprefect config set PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS = [1, 10, 100]\nprefect config set PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS = [1, 10, 100]\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#caching","title":"Caching","text":"<p>Caching refers to the ability of a task run to reflect a finished state without actually running the code that defines the task. This allows you to efficiently reuse results of tasks that may be expensive to run with every flow run, or reuse cached results if the inputs to a task have not changed.</p> <p>To determine whether a task run should retrieve a cached state, we use \"cache keys\". A cache key is a string value that indicates if one run should be considered identical to another. When a task run with a cache key finishes, we attach that cache key to the state. When each task run starts, Prefect checks for states with a matching cache key. If a state with an identical key is found, Prefect will use the cached state instead of running the task again.</p> <p>To enable caching, specify a <code>cache_key_fn</code> \u2014 a function that returns a cache key \u2014 on your task. You may optionally provide a <code>cache_expiration</code> timedelta indicating when the cache expires. If you do not specify a <code>cache_expiration</code>, the cache key does not expire.</p> <p>You can define a task that is cached based on its inputs by using the Prefect <code>task_input_hash</code>. This is a task cache key implementation that hashes all inputs to the task using a JSON or cloudpickle serializer. If the task inputs do not change, the cached results are used rather than running the task until the cache expires.</p> <p>Note that, if any arguments are not JSON serializable, the pickle serializer is used as a fallback. If cloudpickle fails, <code>task_input_hash</code> returns a null key indicating that a cache key could not be generated for the given inputs.</p> <p>In this example, until the <code>cache_expiration</code> time ends, as long as the input to <code>hello_task()</code> remains the same when it is called, the cached return value is returned. In this situation the task is not rerun. However, if the input argument value changes, <code>hello_task()</code> runs using the new input.</p> <pre><code>from datetime import timedelta\nfrom prefect import flow, task\nfrom prefect.tasks import task_input_hash\n\n@task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))\ndef hello_task(name_input):\n    # Doing some work\n    print(\"Saying hello\")\n    return \"hello \" + name_input\n\n@flow(log_prints=True)\ndef hello_flow(name_input):\n    hello_task(name_input)\n</code></pre> <p>Alternatively, you can provide your own function or other callable that returns a string cache key. A generic <code>cache_key_fn</code> is a function that accepts two positional arguments:</p> <ul> <li>The first argument corresponds to the <code>TaskRunContext</code>, which stores task run metadata in the attributes <code>task_run_id</code>, <code>flow_run_id</code>, and <code>task</code>.</li> <li>The second argument corresponds to a dictionary of input values to the task. For example, if your task is defined with signature <code>fn(x, y, z)</code> then the dictionary will have keys <code>\"x\"</code>, <code>\"y\"</code>, and <code>\"z\"</code> with corresponding values that can be used to compute your cache key.</li> </ul> <p>Note that the <code>cache_key_fn</code> is not defined as a <code>@task</code>.</p> <p>Task cache keys</p> <p>By default, a task cache key is limited to 2000 characters, specified by the <code>PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH</code> setting.</p> <pre><code>from prefect import task, flow\n\ndef static_cache_key(context, parameters):\n    # return a constant\n    return \"static cache key\"\n\n@task(cache_key_fn=static_cache_key)\ndef cached_task():\n    print('running an expensive operation')\n    return 42\n\n@flow\ndef test_caching():\n    cached_task()\n    cached_task()\n    cached_task()\n</code></pre> <p>In this case, there's no expiration for the cache key, and no logic to change the cache key, so <code>cached_task()</code> only runs once.</p> <pre><code>&gt;&gt;&gt; test_caching()\nrunning an expensive operation\n&gt;&gt;&gt; test_caching()\n&gt;&gt;&gt; test_caching()\n</code></pre> <p>When each task run requested to enter a <code>Running</code> state, it provided its cache key computed from the <code>cache_key_fn</code>.  The Prefect backend identified that there was a COMPLETED state associated with this key and instructed the run to immediately enter the same COMPLETED state, including the same return values.  </p> <p>A real-world example might include the flow run ID from the context in the cache key so only repeated calls in the same flow run are cached.</p> <pre><code>def cache_within_flow_run(context, parameters):\n    return f\"{context.task_run.flow_run_id}-{task_input_hash(context, parameters)}\"\n\n@task(cache_key_fn=cache_within_flow_run)\ndef cached_task():\n    print('running an expensive operation')\n    return 42\n</code></pre> <p>Task results, retries, and caching</p> <p>Task results are cached in memory during a flow run and persisted to the location specified by the <code>PREFECT_LOCAL_STORAGE_PATH</code> setting. As a result, task caching between flow runs is currently limited to flow runs with access to that local storage path.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#refreshing-the-cache","title":"Refreshing the cache","text":"<p>Sometimes, you want a task to update the data associated with its cache key instead of using the cache. This is a cache \"refresh\".</p> <p>The <code>refresh_cache</code> option can be used to enable this behavior for a specific task:</p> <pre><code>import random\n\n\ndef static_cache_key(context, parameters):\n    # return a constant\n    return \"static cache key\"\n\n\n@task(cache_key_fn=static_cache_key, refresh_cache=True)\ndef caching_task():\n    return random.random()\n</code></pre> <p>When this task runs, it will always update the cache key instead of using the cached value. This is particularly useful when you have a flow that is responsible for updating the cache.</p> <p>If you want to refresh the cache for all tasks, you can use the <code>PREFECT_TASKS_REFRESH_CACHE</code> setting. Setting <code>PREFECT_TASKS_REFRESH_CACHE=true</code> will change the default behavior of all tasks to refresh. This is particularly useful if you want to rerun a flow without cached results.</p> <p>If you have tasks that should not refresh when this setting is enabled, you may explicitly set <code>refresh_cache</code> to <code>False</code>. These tasks will never refresh the cache \u2014 if a cache key exists it will be read, not updated. Note that, if a cache key does not exist yet, these tasks can still write to the cache.</p> <pre><code>@task(cache_key_fn=static_cache_key, refresh_cache=False)\ndef caching_task():\n    return random.random()\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#timeouts","title":"Timeouts","text":"<p>Task timeouts are used to prevent unintentional long-running tasks. When the duration of execution for a task exceeds the duration specified in the timeout, a timeout exception will be raised and the task will be marked as failed. In the UI, the task will be visibly designated as <code>TimedOut</code>. From the perspective of the flow, the timed-out task will be treated like any other failed task.</p> <p>Timeout durations are specified using the <code>timeout_seconds</code> keyword argument.</p> <pre><code>from prefect import task\nimport time\n\n@task(timeout_seconds=1, log_prints=True)\ndef show_timeouts():\n    print(\"I will execute\")\n    time.sleep(5)\n    print(\"I will not execute\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-results","title":"Task results","text":"<p>Depending on how you call tasks, they can return different types of results and optionally engage the use of a task runner.</p> <p>Any task can return:</p> <ul> <li>Data\u200a, such as <code>int</code>, <code>str</code>, <code>dict</code>, <code>list</code>, and so on \u2014 \u200athis is the default behavior any time you call <code>your_task()</code>.</li> <li><code>PrefectFuture</code> \u2014 \u200athis is achieved by calling <code>your_task.submit()</code>. A <code>PrefectFuture</code> contains both data and State</li> <li>Prefect <code>State</code> \u200a\u2014 anytime you call your task or flow with the argument <code>return_state=True</code>, it will directly return a state you can use to build custom behavior based on a state change you care about, such as task or flow failing or retrying.</li> </ul> <p>To run your task with a task runner, you must call the task with <code>.submit()</code>.</p> <p>See state returned values for examples.</p> <p>Task runners are optional</p> <p>If you just need the result from a task, you can simply call the task from your flow. For most workflows, the default behavior of calling a task directly and receiving a result is all you'll need.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#wait-for","title":"Wait for","text":"<p>To create a dependency between two tasks that do not exchange data, but one needs to wait for the other to finish, use the special <code>wait_for</code> keyword argument:</p> <pre><code>@task\ndef task_1():\n    pass\n\n@task\ndef task_2():\n    pass\n\n@flow\ndef my_flow():\n    x = task_1()\n\n    # task 2 will wait for task_1 to complete\n    y = task_2(wait_for=[x])\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#map","title":"Map","text":"<p>Prefect provides a <code>.map()</code> implementation that automatically creates a task run for each element of its input data. Mapped tasks represent the computations of many individual children tasks.</p> <p>The simplest Prefect map takes a tasks and applies it to each element of its inputs.</p> <pre><code>from prefect import flow, task\n\n@task\ndef print_nums(nums):\n    for n in nums:\n        print(n)\n\n@task\ndef square_num(num):\n    return num**2\n\n@flow\ndef map_flow(nums):\n    print_nums(nums)\n    squared_nums = square_num.map(nums) \n    print_nums(squared_nums)\n\nmap_flow([1,2,3,5,8,13])\n</code></pre> <p>Prefect also supports <code>unmapped</code> arguments, allowing you to pass static values that don't get mapped over.</p> <pre><code>from prefect import flow, task\n\n@task\ndef add_together(x, y):\n    return x + y\n\n@flow\ndef sum_it(numbers, static_value):\n    futures = add_together.map(numbers, static_value)\n    return futures\n\nsum_it([1, 2, 3], 5)\n</code></pre> <p>If your static argument is an iterable, you'll need to wrap it with <code>unmapped</code> to tell Prefect that it should be treated as a static value.</p> <pre><code>from prefect import flow, task, unmapped\n\n@task\ndef sum_plus(x, static_iterable):\n    return x + sum(static_iterable)\n\n@flow\ndef sum_it(numbers, static_iterable):\n    futures = sum_plus.map(numbers, static_iterable)\n    return futures\n\nsum_it([4, 5, 6], unmapped([1, 2, 3]))\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#async-tasks","title":"Async tasks","text":"<p>Prefect also supports asynchronous task and flow definitions by default. All of the standard rules of async apply:</p> <pre><code>import asyncio\n\nfrom prefect import task, flow\n\n@task\nasync def print_values(values):\n    for value in values:\n        await asyncio.sleep(1) # yield\n        print(value, end=\" \")\n\n@flow\nasync def async_flow():\n    await print_values([1, 2])  # runs immediately\n    coros = [print_values(\"abcd\"), print_values(\"6789\")]\n\n    # asynchronously gather the tasks\n    await asyncio.gather(*coros)\n\nasyncio.run(async_flow())\n</code></pre> <p>Note, if you are not using <code>asyncio.gather</code>, calling <code>.submit()</code> is required for asynchronous execution on the <code>ConcurrentTaskRunner</code>.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#task-run-concurrency-limits","title":"Task run concurrency limits","text":"<p>There are situations in which you want to actively prevent too many tasks from running simultaneously. For example, if many tasks across multiple flows are designed to interact with a database that only allows 10 connections, you want to make sure that no more than 10 tasks that connect to this database are running at any given time.</p> <p>Prefect has built-in functionality for achieving this: task concurrency limits.</p> <p>Task concurrency limits use task tags. You can specify an optional concurrency limit as the maximum number of concurrent task runs in a <code>Running</code> state for tasks with a given tag. The specified concurrency limit applies to any task to which the tag is applied.</p> <p>If a task has multiple tags, it will run only if all tags have available concurrency.</p> <p>Tags without explicit limits are considered to have unlimited concurrency.</p> <p>0 concurrency limit aborts task runs</p> <p>Currently, if the concurrency limit is set to 0 for a tag, any attempt to run a task with that tag will be aborted instead of delayed.</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#execution-behavior","title":"Execution behavior","text":"<p>Task tag limits are checked whenever a task run attempts to enter a <code>Running</code> state.</p> <p>If there are no concurrency slots available for any one of your task's tags, the transition to a <code>Running</code> state will be delayed and the client is instructed to try entering a <code>Running</code> state again in 30 seconds (or the value specified by the <code>PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS</code> setting).</p>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#configuring-concurrency-limits","title":"Configuring concurrency limits","text":"<p>Flow run concurrency limits are set at a work pool and/or work queue level</p> <p>While task run concurrency limits are configured via tags (as shown below), flow run concurrency limits are configured via work pools and/or work queues.</p> <p>You can set concurrency limits on as few or as many tags as you wish. You can set limits through:</p> <ul> <li>Prefect CLI</li> <li>Prefect API by using <code>PrefectClient</code> Python client</li> <li>Prefect server UI or Prefect Cloud</li> </ul>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#cli","title":"CLI","text":"<p>You can create, list, and remove concurrency limits by using Prefect CLI <code>concurrency-limit</code> commands.</p> <pre><code>prefect concurrency-limit [command] [arguments]\n</code></pre> Command Description create Create a concurrency limit by specifying a tag and limit. delete Delete the concurrency limit set on the specified tag. inspect View details about a concurrency limit set on the specified tag. ls View all defined concurrency limits. <p>For example, to set a concurrency limit of 10 on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit create small_instance 10\n</code></pre> <p>To delete the concurrency limit on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit delete small_instance\n</code></pre> <p>To view details about the concurrency limit on the 'small_instance' tag:</p> <pre><code>prefect concurrency-limit inspect small_instance\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/tasks/#python-client","title":"Python client","text":"<p>To update your tag concurrency limits programmatically, use <code>PrefectClient.orchestration.create_concurrency_limit</code>.</p> <p><code>create_concurrency_limit</code> takes two arguments:</p> <ul> <li><code>tag</code> specifies the task tag on which you're setting a limit.</li> <li><code>concurrency_limit</code> specifies the maximum number of concurrent task runs for that tag.</li> </ul> <p>For example, to set a concurrency limit of 10 on the 'small_instance' tag:</p> <pre><code>from prefect import get_client\n\nasync with get_client() as client:\n    # set a concurrency limit of 10 on the 'small_instance' tag\n    limit_id = await client.create_concurrency_limit(\n        tag=\"small_instance\", \n        concurrency_limit=10\n        )\n</code></pre> <p>To remove all concurrency limits on a tag, use <code>PrefectClient.delete_concurrency_limit_by_tag</code>, passing the tag:</p> <pre><code>async with get_client() as client:\n    # remove a concurrency limit on the 'small_instance' tag\n    await client.delete_concurrency_limit_by_tag(tag=\"small_instance\")\n</code></pre> <p>If you wish to query for the currently set limit on a tag, use <code>PrefectClient.read_concurrency_limit_by_tag</code>, passing the tag:</p> <p>To see all of your limits across all of your tags, use <code>PrefectClient.read_concurrency_limits</code>.</p> <pre><code>async with get_client() as client:\n    # query the concurrency limit on the 'small_instance' tag\n    limit = await client.read_concurrency_limit_by_tag(tag=\"small_instance\")\n</code></pre>","tags":["tasks","task runs","functions","retries","caching","cache keys","cache key functions","tags","results","async","asynchronous execution","map","concurrency","concurrency limits","task concurrency"],"boost":2},{"location":"concepts/work-pools/","title":"Work Pools &amp;  Workers","text":"<p>Work pools and workers bridge the Prefect orchestration environment with your execution environment. When a deployment creates a flow run, it is submitted to a specific work pool for scheduling. A worker running in the execution environment can poll its respective work pool for new runs to execute, or the work pool can submit flow runs to serverless infrastructure directly, depending on your configuration.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-overview","title":"Work pool overview","text":"<p>Work pools organize work for execution. Work pools have types corresponding to the infrastructure that will execute the flow code, as well as the delivery method of work to that environment. Pull work pools require workers (or less ideally, agents) to poll the work pool for flow runs to execute. Push work pools can submit runs directly to your serverless infrastructure providers such as Google Cloud Run, Azure Container Instances, and AWS ECS without the need for an agent or worker. Managed work pools are administered by Prefect and handle the submission and execution of code on your behalf.</p> <p>Work pools are like pub/sub topics</p> <p>It's helpful to think of work pools as a way to coordinate (potentially many) deployments with (potentially many) workers through a known channel: the pool itself. This is similar to how \"topics\" are used to connect producers and consumers in a pub/sub or message-based system. By switching a deployment's work pool, users can quickly change the worker that will execute their runs, making it easy to promote runs through environments or even debug locally.</p> <p>In addition, users can control aspects of work pool behavior, such as how many runs the pool allows to be run concurrently or pausing delivery entirely. These options can be modified at any time, and any workers requesting work for a specific pool will only see matching flow runs.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-configuration","title":"Work pool configuration","text":"<p>You can configure work pools by using any of the following:</p> <ul> <li>Prefect UI</li> <li>Prefect CLI commands</li> <li>Prefect REST API</li> <li>Terraform provider for Prefect Cloud</li> </ul> <p>To manage work pools in the UI, click the Work Pools icon. This displays a list of currently configured work pools.</p> <p></p> <p>You can pause a work pool from this page by using the toggle.</p> <p>Select the + button to create a new work pool. You'll be able to specify the details for work served by this work pool.</p> <p>To create a work pool via the Prefect CLI, use the <code>prefect work-pool create</code> command:</p> <pre><code>prefect work-pool create [OPTIONS] NAME\n</code></pre> <p><code>NAME</code> is a required, unique name for the work pool.</p> <p>Optional configuration parameters you can specify to filter work on the pool include:</p> Option Description <code>--paused</code> If provided, the work pool will be created in a paused state. <code>--type</code> The type of infrastructure that can execute runs from this work pool. <code>--set-as-default</code> Whether to use the created work pool as the local default for deployment. <code>--base-job-template</code> The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. <p>For example, to create a work pool called <code>test-pool</code>, you would run this command:</p> <pre><code>prefect work-pool create test-pool\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-types","title":"Work pool types","text":"<p>If you don't use the <code>--type</code> flag to specify an infrastructure type, you are prompted to select from the following options:</p> Prefect CloudPrefect server instance Infrastructure Type Description Prefect Agent Execute flow runs on heterogeneous infrastructure using infrastructure blocks. Process Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started. AWS Elastic Container Service Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account. Azure Container Instances Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Docker Execute flow runs within Docker containers. Works well for managing flow execution environments via Docker images. Requires  access to a running Docker daemon. Google Cloud Run Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Google Cloud Run V2 Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account. Google Vertex AI Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account. Kubernetes Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster. Google Cloud Run - Push Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. AWS Elastic Container Service - Push Execute flow runs within containers on AWS ECS. Works with existing ECS clusters and serverless execution via AWS Fargate. Requires an AWS account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. Azure Container Instances - Push Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Flow runs are pushed directly to your environment, without the need for a Prefect worker. Modal - Push Execute flow runs on Modal. Requires a Modal account. Flow runs are pushed directly to your Modal workspace, without the need for a Prefect worker. Prefect Managed Execute flow runs within containers on Prefect managed infrastructure. Infrastructure Type Description Prefect Agent Execute flow runs on heterogeneous infrastructure using infrastructure blocks. Process Execute flow runs as subprocesses on a worker. Works well for local execution when first getting started. AWS Elastic Container Service Execute flow runs within containers on AWS ECS. Works with EC2 and Fargate clusters. Requires an AWS account. Azure Container Instances Execute flow runs within containers on Azure's Container Instances service. Requires an Azure account. Docker Execute flow runs within Docker containers. Works well for managing flow execution environments via Docker images. Requires access to a running Docker daemon. Google Cloud Run Execute flow runs within containers on Google Cloud Run. Requires a Google Cloud Platform account. Google Cloud Run V2 Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account. Google Vertex AI Execute flow runs within containers on Google Vertex AI. Requires a Google Cloud Platform account. Kubernetes Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a Kubernetes cluster. <p>On success, the command returns the details of the newly created work pool.</p> <pre><code>Created work pool with properties:\n    name - 'test-pool'\n    id - a51adf8c-58bb-4949-abe6-1b87af46eabd\n    concurrency limit - None\n\nStart a worker to pick up flows from the work pool:\n    prefect worker start -p 'test-pool'\n\nInspect the work pool:\n    prefect work-pool inspect 'test-pool'\n</code></pre> <p>Set a work pool as the default for new deployments by adding the <code>--set-as-default</code> flag.</p> <p>Which would result in output similar to the following:</p> <pre><code>Set 'test-pool' as default work pool for profile 'default'\n\nTo change your default work pool, run:\n\n        prefect config set PREFECT_DEFAULT_WORK_POOL_NAME=&lt;work-pool-name&gt;\n</code></pre> <p>To update a work pool via the Prefect CLI, use the <code>prefect work-pool update</code> command:</p> <pre><code>prefect work-pool update [OPTIONS] NAME\n</code></pre> <p><code>NAME</code> is the name of the work pool to update.</p> <p>Optional configuration parameters you can specify to update the work pool include:</p> Option Description <code>--base-job-template</code> The path to a JSON file containing the base job template to use. If unspecified, Prefect will use the default base job template for the given worker type. <code>--description</code> A description of the work pool. <code>--concurrency-limit</code> The maximum number of flow runs to run simultaneously in the work pool. <p>Managing work pools in CI/CD</p> <p>You can version control your base job template by committing it as a JSON file to your repository and control updates to your work pools' base job templates by using the <code>prefect work-pool update</code> command in your CI/CD pipeline. For example, you could use the following command to update a work pool's base job template to the contents of a file named <code>base-job-template.json</code>:</p> <pre><code>prefect work-pool update --base-job-template base-job-template.json my-work-pool\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#base-job-template","title":"Base job template","text":"<p>Each work pool has a base job template that allows the customization of the behavior of the worker executing flow runs from the work pool.</p> <p>The base job template acts as a contract defining the configuration passed to the worker for each flow run and the options available to deployment creators to customize worker behavior per deployment.</p> <p>A base job template comprises a <code>job_configuration</code> section and a <code>variables</code> section.</p> <p>The <code>variables</code> section defines the fields available to be customized per deployment. The <code>variables</code> section follows the OpenAPI specification, which allows work pool creators to place limits on provided values (type, minimum, maximum, etc.).</p> <p>The job configuration section defines how values provided for fields in the variables section should be translated into the configuration given to a worker when executing a flow run.</p> <p>The values in the <code>job_configuration</code> can use placeholders to reference values provided in the <code>variables</code> section. Placeholders are declared using double curly braces, e.g., <code>{{ variable_name }}</code>. <code>job_configuration</code> values can also be hard-coded if the value should not be customizable.</p> <p>Each worker type is configured with a default base job template, making it easy to start with a work pool. The default base template defines values that will be passed to every flow run, but can be overridden on a per-deployment or per-flow run basis.</p> <p>For example, if we create a <code>process</code> work pool named 'above-ground' via the CLI:</p> <pre><code>prefect work-pool create --type process above-ground\n</code></pre> <p>We see these configuration options available in the Prefect UI: </p> <p>For a <code>process</code> work pool with the default base job template, we can set environment variables for spawned processes, set the working directory to execute flows, and control whether the flow run output is streamed to workers' standard output. You can also see an example of JSON formatted base job template with the 'Advanced' tab.</p> <p>You can examine the default base job template for a given worker type by running:</p> <pre><code>prefect work-pool get-default-base-job-template --type process\n</code></pre> <pre><code>{\n  \"job_configuration\": {\n    \"command\": \"{{ command }}\",\n    \"env\": \"{{ env }}\",\n    \"labels\": \"{{ labels }}\",\n    \"name\": \"{{ name }}\",\n    \"stream_output\": \"{{ stream_output }}\",\n    \"working_dir\": \"{{ working_dir }}\"\n  },\n  \"variables\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"name\": {\n        \"title\": \"Name\",\n        \"description\": \"Name given to infrastructure created by a worker.\",\n        \"type\": \"string\"\n      },\n      \"env\": {\n        \"title\": \"Environment Variables\",\n        \"description\": \"Environment variables to set when starting a flow run.\",\n        \"type\": \"object\",\n        \"additionalProperties\": {\n          \"type\": \"string\"\n        }\n      },\n      \"labels\": {\n        \"title\": \"Labels\",\n        \"description\": \"Labels applied to infrastructure created by a worker.\",\n        \"type\": \"object\",\n        \"additionalProperties\": {\n          \"type\": \"string\"\n        }\n      },\n      \"command\": {\n        \"title\": \"Command\",\n        \"description\": \"The command to use when starting a flow run. In most cases, this should be left blank and the command will be automatically generated by the worker.\",\n        \"type\": \"string\"\n      },\n      \"stream_output\": {\n        \"title\": \"Stream Output\",\n        \"description\": \"If enabled, workers will stream output from flow run processes to local standard output.\",\n        \"default\": true,\n        \"type\": \"boolean\"\n      },\n      \"working_dir\": {\n        \"title\": \"Working Directory\",\n        \"description\": \"If provided, workers will open flow run processes within the specified path as the working directory. Otherwise, a temporary directory will be created.\",\n        \"type\": \"string\",\n        \"format\": \"path\"\n      }\n    }\n  }\n}\n</code></pre> <p>You can override each of these attributes on a per-deployment or per-flow run basis. When creating a deployment, you can specify these overrides in the <code>deployments.work_pool.job_variables</code> section of a <code>prefect.yaml</code> file or in the <code>job_variables</code> argument of a Python <code>flow.deploy</code> method.</p> <p>For example, to turn off streaming output for a specific deployment, we could add the following to our <code>prefect.yaml</code>:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: above-ground  \n    job_variables:\n        stream_output: false\n</code></pre> <p>See more about overriding job variables in the Overriding Job Variables Guide.</p> <p>Advanced Customization of the Base Job Template</p> <p>For advanced use cases, you can create work pools with fully customizable job templates. This customization is available when creating or editing a work pool on the 'Advanced' tab within the UI or when updating a work pool via the Prefect CLI.</p> <p>Advanced customization is useful anytime the underlying infrastructure supports a high degree of customization. In these scenarios a work pool job template allows you to expose a minimal and easy-to-digest set of options to deployment authors.  Additionally, these options are the only customizable aspects for deployment infrastructure, which can be useful for restricting functionality in secure environments. For example, the <code>kubernetes</code> worker type allows users to specify a custom job template that can be used to configure the manifest that workers use to create jobs for flow execution.</p> <p>For more information and advanced configuration examples, see the Kubernetes Worker documentation.</p> <p>For more information on overriding a work pool's job variables see this guide.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#viewing-work-pools","title":"Viewing work pools","text":"<p>At any time, users can see and edit configured work pools in the Prefect UI.</p> <p></p> <p>To view work pools with the Prefect CLI, you can:</p> <ul> <li>List (<code>ls</code>) all available pools</li> <li>Inspect (<code>inspect</code>) the details of a single pool</li> <li>Preview (<code>preview</code>) scheduled work for a single pool</li> </ul> <p><code>prefect work-pool ls</code> lists all configured work pools for the server.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>For example:</p> <pre><code>                               Work pools\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name       \u2503    Type        \u2503                                   ID \u2503 Concurrency Limit \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 barbeque   \u2502 docker         \u2502 72c0a101-b3e2-4448-b5f8-a8c5184abd17 \u2502 None              \u2502\n\u2502 k8s-pool   \u2502 kubernetes     \u2502 7b6e3523-d35b-4882-84a7-7a107325bb3f \u2502 None              \u2502\n\u2502 test-pool  \u2502 prefect-agent  \u2502 a51adf8c-58bb-4949-abe6-1b87af46eabd \u2502 None              |\n| my-pool    \u2502 process        \u2502 cd6ff9e8-bfd8-43be-9be3-69375f7a11cd \u2502 None              \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                       (**) denotes a paused pool\n</code></pre> <p><code>prefect work-pool inspect</code> provides all configuration metadata for a specific work pool by ID.</p> <pre><code>prefect work-pool inspect 'test-pool'\n</code></pre> <p>Outputs information similar to the following:</p> <pre><code>Workpool(\n    id='a51adf8c-58bb-4949-abe6-1b87af46eabd',\n    created='2 minutes ago',\n    updated='2 minutes ago',\n    name='test-pool',\n    filter=None,\n)\n</code></pre> <p><code>prefect work-pool preview</code> displays scheduled flow runs for a specific work pool by ID for the upcoming hour. The optional <code>--hours</code> flag lets you specify the number of hours to look ahead.</p> <pre><code>prefect work-pool preview 'test-pool' --hours 12\n</code></pre> <pre><code>\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Scheduled Star\u2026 \u2503 Run ID                     \u2503 Name         \u2503 Deployment ID               \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 2022-02-26 06:\u2026 \u2502 741483d4-dc90-4913-b88d-0\u2026 \u2502 messy-petrel \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 05:\u2026 \u2502 14e23a19-a51b-4833-9322-5\u2026 \u2502 unselfish-g\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 04:\u2026 \u2502 deb44d4d-5fa2-4f70-a370-e\u2026 \u2502 solid-ostri\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 03:\u2026 \u2502 07374b5c-121f-4c8d-9105-b\u2026 \u2502 sophisticat\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 02:\u2026 \u2502 545bc975-b694-4ece-9def-8\u2026 \u2502 gorgeous-mo\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 01:\u2026 \u2502 704f2d67-9dfa-4fb8-9784-4\u2026 \u2502 sassy-hedge\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-26 00:\u2026 \u2502 691312f0-d142-4218-b617-a\u2026 \u2502 sincere-moo\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 23:\u2026 \u2502 7cb3ff96-606b-4d8c-8a33-4\u2026 \u2502 curious-cat\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 22:\u2026 \u2502 3ea559fe-cb34-43b0-8090-1\u2026 \u2502 primitive-f\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2502 2022-02-25 21:\u2026 \u2502 96212e80-426d-4bf4-9c49-e\u2026 \u2502 phenomenal-\u2026 \u2502 156edead-fe6a-4783-a618-21\u2026 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                   (**) denotes a late run\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-pool-status","title":"Work pool status","text":"<p>Work pools have three statuses: <code>READY</code>, <code>NOT_READY</code>, and <code>PAUSED</code>. A work pool is considered ready if it has at least one online worker sending heartbeats to the work pool. If a work pool has no online workers, it is considered not ready to execute work. A work pool can be placed in a paused status manually by a user or via an automation. When a paused work pool is unpaused, it will be reassigned the appropriate status based on whether any workers are sending heartbeats.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#pausing-and-deleting-work-pools","title":"Pausing and deleting work pools","text":"<p>A work pool can be paused at any time to stop the delivery of work to workers. Workers will not receive any work when polling a paused pool.</p> <p>To pause a work pool through the Prefect CLI, use the <code>prefect work-pool pause</code> command:</p> <pre><code>prefect work-pool pause 'test-pool'\n</code></pre> <p>To resume a work pool through the Prefect CLI, use the <code>prefect work-pool resume</code> command with the work pool name.</p> <p>To delete a work pool through the Prefect CLI, use the <code>prefect work-pool delete</code> command with the work pool name.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#managing-concurrency","title":"Managing concurrency","text":"<p>Each work pool can optionally restrict concurrent runs of matching flows.</p> <p>For example, a work pool with a concurrency limit of 5 will only release new work if fewer than 5 matching runs are currently in a <code>Running</code> or <code>Pending</code> state. If 3 runs are <code>Running</code> or <code>Pending</code>, polling the pool for work will only result in 2 new runs, even if there are many more available, to ensure that the concurrency limit is not exceeded.</p> <p>When using the <code>prefect work-pool</code> Prefect CLI command to configure a work pool, the following subcommands set concurrency limits:</p> <ul> <li><code>set-concurrency-limit</code>  sets a concurrency limit on a work pool.</li> <li><code>clear-concurrency-limit</code> clears any concurrency limits from a work pool.</li> </ul>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#work-queues","title":"Work queues","text":"<p>Advanced topic</p> <p>Prefect will automatically create a default work queue if needed.</p> <p>Work queues offer advanced control over how runs are executed. Each work pool has a \"default\" queue that all work will be sent to by default. Additional queues can be added to a work pool to enable greater control over work delivery through fine grained priority and concurrency. Each work queue has a priority indicated by a unique positive integer. Lower numbers take greater priority in the allocation of work. Accordingly, new queues can be added without changing the rank of the higher-priority queues (e.g. no matter how many queues you add, the queue with priority <code>1</code> will always be the highest priority).</p> <p>Work queues can also have their own concurrency limits. Note that each queue is also subject to the global work pool concurrency limit, which cannot be exceeded.</p> <p>Together work queue priority and concurrency enable precise control over work. For example, a pool may have three queues: A \"low\" queue with priority <code>10</code> and no concurrency limit, a \"high\" queue with priority <code>5</code> and a concurrency limit of <code>3</code>, and a \"critical\" queue with priority <code>1</code> and a concurrency limit of <code>1</code>. This arrangement would enable a pattern in which there are two levels of priority, \"high\" and \"low\" for regularly scheduled flow runs, with the remaining \"critical\" queue for unplanned, urgent work, such as a backfill.</p> <p>Priority is evaluated to determine the order in which flow runs are submitted for execution. If all flow runs are capable of being executed with no limitation due to concurrency or otherwise, priority is still used to determine order of submission, but there is no impact to execution. If not all flow runs can be executed, usually as a result of concurrency limits, priority is used to determine which queues receive precedence to submit runs for execution.</p> <p>Priority for flow run submission proceeds from the highest priority to the lowest priority. In the preceding example, all work from the \"critical\" queue (priority 1) will be submitted, before any work is submitted from \"high\" (priority 5). Once all work has been submitted from priority queue \"critical\", work from the \"high\" queue will begin submission.</p> <p>If new flow runs are received on the \"critical\" queue while flow runs are still in scheduled on the \"high\" and \"low\" queues, flow run submission goes back to ensuring all scheduled work is first satisfied from the highest priority queue, until it is empty, in waterfall fashion.</p> <p>Work queue status</p> <p>A work queue has a <code>READY</code> status when it has been polled by a worker in the last 60 seconds. Pausing a work queue will give it a <code>PAUSED</code> status and mean that it will accept no new work until it is unpaused. A user can control the work queue's paused status in the UI. Unpausing a work queue will give the work queue a <code>NOT_READY</code> status unless a worker has polled it in the last 60 seconds.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#local-debugging","title":"Local debugging","text":"<p>As long as your deployment's infrastructure block supports it, you can use work pools to temporarily send runs to a worker running on your local machine for debugging by running <code>prefect worker start -p my-local-machine</code> and updating the deployment's work pool to <code>my-local-machine</code>.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-overview","title":"Worker overview","text":"<p>Workers are lightweight polling services that retrieve scheduled runs from a work pool and execute them.</p> <p>Workers are similar to agents, but offer greater control over infrastructure configuration and the ability to route work to specific types of execution environments.</p> <p>Workers each have a type corresponding to the execution environment to which they will submit flow runs. Workers are only able to poll work pools that match their type. As a result, when deployments are assigned to a work pool, you know in which execution environment scheduled flow runs for that deployment will run.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-types","title":"Worker types","text":"<p>Below is a list of available worker types. Note that most worker types will require installation of an additional package.</p> Worker Type Description Required Package <code>process</code> Executes flow runs in subprocesses <code>kubernetes</code> Executes flow runs as Kubernetes jobs <code>prefect-kubernetes</code> <code>docker</code> Executes flow runs within Docker containers <code>prefect-docker</code> <code>ecs</code> Executes flow runs as ECS tasks <code>prefect-aws</code> <code>cloud-run</code> Executes flow runs as Google Cloud Run jobs <code>prefect-gcp</code> <code>vertex-ai</code> Executes flow runs as Google Cloud Vertex AI jobs <code>prefect-gcp</code> <code>azure-container-instance</code> Execute flow runs in ACI containers <code>prefect-azure</code> <p>If you don\u2019t see a worker type that meets your needs, consider developing a new worker type!</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-options","title":"Worker options","text":"<p>Workers poll for work from one or more queues within a work pool. If the worker references a work queue that doesn't exist, it will be created automatically. The worker CLI is able to infer the worker type from the work pool. Alternatively, you can also specify the worker type explicitly. If you supply the worker type to the worker CLI, a work pool will be created automatically if it doesn't exist (using default job settings).</p> <p>Configuration parameters you can specify when starting a worker include:</p> Option Description <code>--name</code>, <code>-n</code> The name to give to the started worker. If not provided, a unique name will be generated. <code>--pool</code>, <code>-p</code> The work pool the started worker should poll. <code>--work-queue</code>, <code>-q</code> One or more work queue names for the worker to pull from. If not provided, the worker will pull from all work queues in the work pool. <code>--type</code>, <code>-t</code> The type of worker to start. If not provided, the worker type will be inferred from the work pool. <code>--prefetch-seconds</code> The amount of time before a flow run's scheduled start time to begin submission. Default is the value of <code>PREFECT_WORKER_PREFETCH_SECONDS</code>. <code>--run-once</code> Only run worker polling once. By default, the worker runs forever. <code>--limit</code>, <code>-l</code> The maximum number of flow runs to start simultaneously. <code>--with-healthcheck</code> Start a healthcheck server for the worker. <code>--install-policy</code> Install policy to use workers from Prefect integration packages. <p>You must start a worker within an environment that can access or create the infrastructure needed to execute flow runs. The worker will deploy flow runs to the infrastructure corresponding to the worker type. For example, if you start a worker with type <code>kubernetes</code>, the worker will deploy flow runs to a Kubernetes cluster.</p> <p>Prefect must be installed in execution environments</p> <p>Prefect must be installed in any environment (virtual environment, Docker container, etc.) where you intend to run the worker or execute a flow run.</p> <p><code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code>settings for workers</p> <p><code>PREFECT_API_URL</code> must be set for the environment in which your worker is running. You must also have a user or service account with the <code>Worker</code> role, which can be configured by setting the <code>PREFECT_API_KEY</code>.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#worker-status","title":"Worker status","text":"<p>Workers have two statuses: <code>ONLINE</code> and <code>OFFLINE</code>. A worker is online if it sends regular heartbeat messages to the Prefect API. If a worker has missed three heartbeats, it is considered offline. By default, a worker is considered offline a maximum of 90 seconds after it stopped sending heartbeats, but the threshold can be configured via the <code>PREFECT_WORKER_HEARTBEAT_SECONDS</code> setting.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#starting-a-worker","title":"Starting a worker","text":"<p>Use the <code>prefect worker start</code> CLI command to start a worker. You must pass at least the work pool name. If the work pool does not exist, it will be created if the <code>--type</code> flag is used.</p> <pre><code>prefect worker start -p [work pool name]\n</code></pre> <p>For example:</p> <pre><code>prefect worker start -p \"my-pool\"\n</code></pre> <p>Results in output like this:</p> <pre><code>Discovered worker type 'process' for work pool 'my-pool'.\nWorker 'ProcessWorker 65716280-96f8-420b-9300-7e94417f2673' started!\n</code></pre> <p>In this case, Prefect automatically discovered the worker type from the work pool. To create a work pool and start a worker in one command, use the <code>--type</code> flag:</p> <pre><code>prefect worker start -p \"my-pool\" --type \"process\"\n</code></pre> <pre><code>Worker 'ProcessWorker d24f3768-62a9-4141-9480-a056b9539a25' started!\n06:57:53.289 | INFO    | prefect.worker.process.processworker d24f3768-62a9-4141-9480-a056b9539a25 - Worker pool 'my-pool' created.\n</code></pre> <p>In addition, workers can limit the number of flow runs they will start simultaneously with the <code>--limit</code> flag. For example, to limit a worker to five concurrent flow runs:</p> <pre><code>prefect worker start --pool \"my-pool\" --limit 5\n</code></pre>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#configuring-prefetch","title":"Configuring prefetch","text":"<p>By default, the worker begins submitting flow runs a short time (10 seconds) before they are scheduled to run. This behavior allows time for the infrastructure to be created so that the flow run can start on time.</p> <p>In some cases, infrastructure will take longer than 10 seconds to start the flow run. The prefetch can be increased using the <code>--prefetch-seconds</code> option or the <code>PREFECT_WORKER_PREFETCH_SECONDS</code> setting.</p> <p>If this value is more than the amount of time it takes for the infrastructure to start, the flow run will wait until its scheduled start time.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#polling-for-work","title":"Polling for work","text":"<p>Workers poll for work every 15 seconds by default. This interval is configurable in your profile settings with the <code>PREFECT_WORKER_QUERY_SECONDS</code> setting.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#install-policy","title":"Install policy","text":"<p>The Prefect CLI can install the required package for Prefect-maintained worker types automatically. You can configure this behavior with the <code>--install-policy</code> option. The following are valid install policies</p> Install Policy Description <code>always</code> Always install the required package. Will update the required package to the most recent version if already installed. <code>if-not-present</code> Install the required package if it is not already installed. <code>never</code> Never install the required package. <code>prompt</code> Prompt the user to choose whether to install the required package. This is the default install policy. If <code>prefect worker start</code> is run non-interactively, the <code>prompt</code> install policy will behave the same as <code>never</code>.","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"concepts/work-pools/#additional-resources","title":"Additional resources","text":"<p>See how to daemonize a Prefect worker in this guide.</p> <p>For more information on overriding a work pool's job variables see this guide.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","schedules","concurrency limits","priority","work queues"],"boost":2},{"location":"contributing/overview/","title":"Contributing","text":"<p>Thanks for considering contributing to Prefect!</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#setting-up-a-development-environment","title":"Setting up a development environment","text":"<p>First, download the source code and install an editable version of the Python package:</p> <pre><code># Clone the repository\ngit clone https://github.com/PrefectHQ/prefect.git\ncd prefect\n\n# We recommend using a virtual environment\n\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install the package with development dependencies\n\npip install -e \".[dev]\"\n\n# Setup pre-commit hooks for required formatting\n\npre-commit install\n</code></pre> <p>If you don't want to install the pre-commit hooks, you can manually install the formatting dependencies with:</p> <pre><code>pip install $(./scripts/precommit-versions.py)\n</code></pre> <p>You'll need to run <code>black</code> and  <code>ruff</code> before a contribution can be accepted.</p> <p>After installation, you can run the test suite with <code>pytest</code>:</p> <pre><code># Run all the tests\npytest tests\n\n# Run a subset of tests\n\npytest tests/test_flows.py\n</code></pre> <p>Building the Prefect UI</p> <p>If you intend to run a local Prefect server during development, you must first build the UI. See UI development for instructions.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#prefect-code-of-conduct","title":"Prefect Code of Conduct","text":"","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or   advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic   address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a   professional setting</li> </ul>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#scope","title":"Scope","text":"<p>This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Chris White at chris@prefect.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#developer-tooling","title":"Developer tooling","text":"<p>The Prefect CLI provides several helpful commands to aid development.</p> <p>Start all services with hot-reloading on code changes (requires UI dependencies to be installed):</p> <pre><code>prefect dev start\n</code></pre> <p>Start a Prefect API that reloads on code changes:</p> <pre><code>prefect dev api\n</code></pre> <p>Start a Prefect worker that reloads on code changes:</p> <pre><code>prefect dev agent\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#ui-development","title":"UI development","text":"<p>Developing the Prefect UI requires that npm is installed.</p> <p>Start a development UI that reloads on code changes:</p> <pre><code>prefect dev ui\n</code></pre> <p>Build the static UI (the UI served by <code>prefect server start</code>):</p> <pre><code>prefect dev build-ui\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#docs-development","title":"Docs Development","text":"<p>Prefect uses mkdocs for the docs website and the mkdocs-material theme. While we use <code>mkdocs-material-insiders</code> for production, builds can still happen without the extra plugins. Deploy previews are available on pull requests, so you'll be able to browse the final look of your changes before merging.</p> <p>To build the docs:</p> <pre><code>mkdocs build\n</code></pre> <p>To serve the docs locally at http://127.0.0.1:8000/:</p> <pre><code>mkdocs serve\n</code></pre> <p>For additional mkdocs help and options:</p> <pre><code>mkdocs --help\n</code></pre> <p>We use the mkdocs-material theme. To add additional JavaScript or CSS to the docs, please see the theme documentation here.</p> <p>Internal developers can install the production theme by running:</p> <pre><code>pip install -e git+https://github.com/PrefectHQ/mkdocs-material-insiders.git#egg=mkdocs-material\nmkdocs build # or mkdocs build --config-file mkdocs.insiders.yml if needed\n</code></pre>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#kubernetes-development","title":"Kubernetes development","text":"<p>Generate a manifest to deploy a development API to a local kubernetes cluster:</p> <pre><code>prefect dev kubernetes-manifest\n</code></pre> <p>To access the Prefect UI running in a Kubernetes cluster, use the <code>kubectl port-forward</code> command to forward a port on your local machine to an open port within the cluster. For example:</p> <pre><code>kubectl port-forward deployment/prefect-dev 4200:4200\n</code></pre> <p>This forwards port 4200 on the default internal loop IP for localhost to the Prefect server deployment.</p> <p>To tell the local <code>prefect</code> command how to communicate with the Prefect API running in Kubernetes, set the <code>PREFECT_API_URL</code> environment variable:</p> <pre><code>export PREFECT_API_URL=http://localhost:4200/api\n</code></pre> <p>Since you previously configured port forwarding for the localhost port to the Kubernetes environment, you\u2019ll be able to interact with the Prefect API running in Kubernetes when using local Prefect CLI commands.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/overview/#adding-database-migrations","title":"Adding database migrations","text":"<p>To make changes to a table, first update the SQLAlchemy model in <code>src/prefect/server/database/orm_models.py</code>. For example, if you wanted to add a new column to the <code>flow_run</code> table, you would add a new column to the <code>FlowRun</code> model:</p> <pre><code># src/prefect/server/database/orm_models.py\n\n@declarative_mixin\nclass ORMFlowRun(ORMRun):\n    \"\"\"SQLAlchemy model of a flow run.\"\"\"\n    ...\n    new_column = Column(String, nullable=True) # &lt;-- add this line\n</code></pre> <p>Next, you will need to generate new migration files. You must generate a new migration file for each database type. Migrations will be generated for whatever database type <code>PREFECT_API_DATABASE_CONNECTION_URL</code> is set to. See here for how to set the database connection URL for each database type.</p> <p>To generate a new migration file, run the following command:</p> <pre><code>prefect server database revision --autogenerate -m \"&lt;migration name&gt;\"\n</code></pre> <p>Try to make your migration name brief but descriptive. For example:</p> <ul> <li><code>add_flow_run_new_column</code></li> <li><code>add_flow_run_new_column_idx</code></li> <li><code>rename_flow_run_old_column_to_new_column</code></li> </ul> <p>The <code>--autogenerate</code> flag will automatically generate a migration file based on the changes to the models.</p> <p>Always inspect the output of <code>--autogenerate</code></p> <p><code>--autogenerate</code> will generate a migration file based on the changes to the models. However, it is not perfect. Be sure to check the file to make sure it only includes the changes you want to make. Additionally, you may need to remove extra statements that were included and not related to your change.</p> <p>The new migration can be found in the <code>src/prefect/server/database/migrations/versions/</code> directory. Each database type has its own subdirectory. For example, the SQLite migrations are stored in <code>src/prefect/server/database/migrations/versions/sqlite/</code>.</p> <p>After you have inspected the migration file, you can apply the migration to your database by running the following command:</p> <pre><code>prefect server database upgrade -y\n</code></pre> <p>Once you have successfully created and applied migrations for all database types, make sure to update <code>MIGRATION-NOTES.md</code> to document your additions.</p>","tags":["open source","contributing","development","standards","migrations"],"boost":2},{"location":"contributing/style/","title":"Code style and practices","text":"<p>Generally, we follow the Google Python Style Guide. This document covers sections where we differ or where additional clarification is necessary.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports","title":"Imports","text":"<p>A brief collection of rules and guidelines for how imports should be handled in this repository.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports-in-__init__-files","title":"Imports in <code>__init__</code> files","text":"<p>Leave <code>__init__</code> files empty unless exposing an interface. If you must expose objects to present a simpler API, please follow these rules.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#exposing-objects-from-submodules","title":"Exposing objects from submodules","text":"<p>If importing objects from submodules, the <code>__init__</code> file should use a relative import. This is required for type checkers to understand the exposed interface.</p> <pre><code># Correct\nfrom .flows import flow\n</code></pre> <pre><code># Wrong\nfrom prefect.flows import flow\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#exposing-submodules","title":"Exposing submodules","text":"<p>Generally, submodules should not be imported in the <code>__init__</code> file. Submodules should only be exposed when the module is designed to be imported and used as a namespaced object.</p> <p>For example, we do this for our schema and model modules because it is important to know if you are working with an API schema or database model, both of which may have similar names.</p> <pre><code>import prefect.server.schemas as schemas\n\n# The full module is accessible now\nschemas.core.FlowRun\n</code></pre> <p>If exposing a submodule, use a relative import as you would when exposing an object.</p> <pre><code># Correct\nfrom . import flows\n</code></pre> <pre><code># Wrong\nimport prefect.flows\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-to-run-side-effects","title":"Importing to run side-effects","text":"<p>Another use case for importing submodules is perform global side-effects that occur when they are imported.</p> <p>Often, global side-effects on import are a dangerous pattern. Avoid them if feasible.</p> <p>We have a couple acceptable use-cases for this currently:</p> <ul> <li>To register dispatchable types, e.g. <code>prefect.serializers</code>.</li> <li>To extend a CLI application e.g. <code>prefect.cli</code>.</li> </ul>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#imports-in-modules","title":"Imports in modules","text":"","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-other-modules","title":"Importing other modules","text":"<p>The <code>from</code> syntax should be reserved for importing objects from modules. Modules should not be imported using the <code>from</code> syntax.</p> <pre><code># Correct\nimport prefect.server.schemas  # use with the full name\nimport prefect.server.schemas as schemas  # use the shorter name\n</code></pre> <pre><code># Wrong\nfrom prefect.server import schemas\n</code></pre> <p>Unless in an <code>__init__.py</code> file, relative imports should not be used.</p> <pre><code># Correct\nfrom prefect.utilities.foo import bar\n</code></pre> <pre><code># Wrong\nfrom .utilities.foo import bar\n</code></pre> <p>Imports dependent on file location should never be used without explicit indication it is relative. This avoids confusion about the source of a module.</p> <pre><code># Correct\nfrom . import test\n</code></pre> <pre><code># Wrong\nimport test\n</code></pre>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#resolving-circular-dependencies","title":"Resolving circular dependencies","text":"<p>Sometimes, we must defer an import and perform it within a function to avoid a circular dependency.</p> <pre><code>## This function in `settings.py` requires a method from the global `context` but the context\n## uses settings\ndef from_context():\n    from prefect.context import get_profile_context\n\n    ...\n</code></pre> <p>Attempt to avoid circular dependencies. This often reveals overentanglement in the design.</p> <p>When performing deferred imports, they should all be placed at the top of the function.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#with-type-annotations","title":"With type annotations","text":"<p>If you are just using the imported object for a type signature, you should use the <code>TYPE_CHECKING</code> flag.</p> <pre><code># Correct\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from prefect.server.schemas.states import State\n\ndef foo(state: \"State\"):\n    pass\n</code></pre> <p>Note that usage of the type within the module will need quotes e.g. <code>\"State\"</code> since it is not available at runtime.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#importing-optional-requirements","title":"Importing optional requirements","text":"<p>We do not have a best practice for this yet. See the <code>kubernetes</code>, <code>docker</code>, and <code>distributed</code> implementations for now.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#delaying-expensive-imports","title":"Delaying expensive imports","text":"<p>Sometimes, imports are slow. We'd like to keep the <code>prefect</code> module import times fast. In these cases, we can lazily import the slow module by deferring import to the relevant function body. For modules that are consumed by many functions, the pattern used for optional requirements may be used instead.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#command-line-interface-cli-output-messages","title":"Command line interface (CLI) output messages","text":"<p>Upon executing a command that creates an object, the output message should offer: - A short description of what the command just did. - A bullet point list, rehashing user inputs, if possible. - Next steps, like the next command to run, if applicable. - Other relevant, pre-formatted commands that can be copied and pasted, if applicable. - A new line before the first line and after the last line.</p> <p>Output Example: <pre><code>$ prefect work-queue create testing\n\nCreated work queue with properties:\n    name - 'abcde'\n    uuid - 940f9828-c820-4148-9526-ea8107082bda\n    tags - None\n    deployment_ids - None\n\nStart an agent to pick up flows from the created work queue:\n    prefect agent start -q 'abcde'\n\nInspect the created work queue:\n    prefect work-queue inspect 'abcde'\n</code></pre></p> <p>Additionally:</p> <ul> <li>Wrap generated arguments in apostrophes (') to ensure validity by using suffixing formats with <code>!r</code>.</li> <li>Indent example commands, instead of wrapping in backticks (`).</li> <li>Use placeholders if the example cannot be pre-formatted completely.</li> <li>Capitalize placeholder labels and wrap them in less than (&lt;) and greater than (&gt;) signs.</li> <li>Utilize <code>textwrap.dedent</code> to remove extraneous spacing for strings that are written with triple quotes (\"\"\").</li> </ul> <p>Placeholder Example: <pre><code>Create a work queue with tags:\n    prefect work-queue create '&lt;WORK QUEUE NAME&gt;' -t '&lt;OPTIONAL TAG 1&gt;' -t '&lt;OPTIONAL TAG 2&gt;'\n</code></pre></p> <p>Dedent Example: <pre><code>from textwrap import dedent\n...\noutput_msg = dedent(\n    f\"\"\"\n    Created work queue with properties:\n        name - {name!r}\n        uuid - {result}\n        tags - {tags or None}\n        deployment_ids - {deployment_ids or None}\n\n    Start an agent to pick up flows from the created work queue:\n        prefect agent start -q {name!r}\n\n    Inspect the created work queue:\n        prefect work-queue inspect {name!r}\n    \"\"\"\n)\n</code></pre></p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/style/#api-versioning","title":"API Versioning","text":"<p>The Prefect client can be run separately from the Prefect orchestration server and communicate entirely via an API. Among other things, the Prefect client includes anything that runs task or flow code, (e.g. agents, and the Python client) or any consumer of Prefect metadata, (e.g. the Prefect UI, and CLI). The Prefect server stores this metadata and serves it via the REST API.</p> <p>Sometimes, we make breaking changes to the API (for good reasons). In order to check that a Prefect client is compatible with the API it's making requests to, every API call the client makes includes a three-component <code>API_VERSION</code> header with major, minor, and patch versions.</p> <p>For example, a request with the <code>X-PREFECT-API-VERSION=3.2.1</code> header has a major version of <code>3</code>, minor version <code>2</code>, and patch version <code>1</code>.</p> <p>This version header can be changed by modifying the <code>API_VERSION</code> constant in <code>prefect.server.api.server</code>.</p> <p>When making a breaking change to the API, we should consider if the change might be backwards compatible for clients, meaning that the previous version of the client would still be able to make calls against the updated version of the server code. This might happen if the changes are purely additive: such as adding a non-critical API route. In these cases, we should make sure to bump the patch version.</p> <p>In almost all other cases, we should bump the minor version, which denotes a non-backwards-compatible API change. We have reserved the major version chanes to denote also-backwards compatible change that might be significant in some way, such as a major release milestone.</p>","tags":["standards","code style","coding practices","contributing"],"boost":2},{"location":"contributing/versioning/","title":"Versioning","text":"","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#understanding-version-numbers","title":"Understanding version numbers","text":"<p>Versions are composed of three parts: MAJOR.MINOR.PATCH. For example, the version 2.5.0 has a major version of 2, a minor version of 5, and patch version of 0.</p> <p>Occasionally, we will add a suffix to the version such as <code>rc</code>, <code>a</code>, or <code>b</code>. These indicate pre-release versions that users can opt-into installing to test functionality before it is ready for release.</p> <p>Each release will increase one of the version numbers. If we increase a number other than the patch version, the versions to the right of it will be reset to zero.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#prefects-versioning-scheme","title":"Prefect's versioning scheme","text":"<p>Prefect will increase the major version when significant and widespread changes are made to the core product. It is very unlikely that the major version will change without extensive warning.</p> <p>Prefect will increase the minor version when:</p> <ul> <li>Introducing a new concept that changes how Prefect can be used</li> <li>Changing an existing concept in a way that fundamentally alters how it is used</li> <li>Removing a deprecated feature</li> </ul> <p>Prefect will increase the patch version when:</p> <ul> <li>Making enhancements to existing features</li> <li>Fixing behavior in existing features</li> <li>Adding new functionality to existing concepts</li> <li>Updating dependencies</li> </ul>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#breaking-changes-and-deprecation","title":"Breaking changes and deprecation","text":"<p>A breaking change means that your code will need to change to use a new version of Prefect. We strive to avoid breaking changes in all releases.</p> <p>At times, Prefect will deprecate a feature. This means that a feature has been marked for removal in the future. When you use it, you may see warnings that it will be removed. A feature is deprecated when it will no longer be maintained. Frequently, a deprecated feature will have a new and improved alternative. Deprecated features will be retained for at least 3 minor version increases or 6 months, whichever is longer. We may retain deprecated features longer than this time period.</p> <p>Prefect will sometimes include changes to behavior to fix a bug. These changes are not categorized as breaking changes.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#client-compatibility-with-prefect","title":"Client compatibility with Prefect","text":"<p>When running a Prefect server, you are in charge of ensuring the version is compatible with those of the clients that are using the server. Prefect aims to maintain backwards compatibility with old clients for each server release. In contrast, sometimes new clients cannot be used with an old server. The new client may expect the server to support functionality that it does not yet include. For this reason, we recommend that all clients are the same version as the server or older.</p> <p>For example, a client on 2.1.0 can be used with a server on 2.5.0. A client on 2.5.0 cannot be used with a server on 2.1.0.</p>","tags":["versioning","semver"],"boost":2},{"location":"contributing/versioning/#client-compatibility-with-cloud","title":"Client compatibility with Cloud","text":"<p>Prefect Cloud targets compatibility with all versions of Prefect clients. If you encounter a compatibility issue, please file a bug report.</p>","tags":["versioning","semver"],"boost":2},{"location":"getting-started/installation/","title":"Installation","text":"<p>Prefect requires Python 3.8 or newer.</p> <p> </p> <p>We recommend installing Prefect using a Python virtual environment manager such as <code>pipenv</code>, <code>conda</code>, or <code>virtualenv</code>/<code>venv</code>.</p> <p>You can use Prefect Cloud as your API server or host your own Prefect server instance backed by PostgreSQL. For development, you can use SQLite 2.24 or newer as your database.</p> <p>Prefect Cloud is a managed solution that provides strong scaling, performance, and security. Learn more about Prefect Cloud solutions for enterprises here.</p> <p>Windows and Linux requirements</p> <p>See Windows installation notes and Linux installation notes for details on additional installation requirements and considerations.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#install-prefect","title":"Install Prefect","text":"<p>The following sections describe how to install Prefect in your environment.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#installing-the-latest-version","title":"Installing the latest version","text":"<p>Prefect is published as a Python package. To install the latest release or upgrade an existing Prefect install, and upgrade existing Python dependencies, run the following command in your terminal:</p> <pre><code>pip install -U prefect\n</code></pre> <p>To install a specific Prefect version, specify the version number like this:</p> <pre><code>pip install -U \"prefect==2.17.1\"\n</code></pre> <p>See available release versions in the Prefect Release Notes.</p> <p>See our Contributing guide for instructions on installing Prefect for development and see the section below to install directly from the <code>main</code> branch.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#checking-your-installation","title":"Checking your installation","text":"<p>To confirm that Prefect was installed correctly, run the command <code>prefect version</code> in your terminal.</p> <pre><code>prefect version\n</code></pre> <p>You should see output similar to the following:</p> <pre><code>Version:             2.17.1\nAPI version:         0.8.4\nPython version:      3.12.2\nGit commit:          d6bdb075\nBuilt:               Thu, Apr 11, 2024 6:58 PM\nOS/Arch:             darwin/arm64\nProfile:              local\nServer type:         ephemeral\nServer:\n  Database:          sqlite\n  SQLite version:    3.45.2\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#windows-installation-notes","title":"Windows installation notes","text":"<p>You can install and run Prefect via Windows PowerShell, the Windows Command Prompt, or <code>conda</code>. After installation, you may need to manually add the Python local packages <code>Scripts</code> folder to your <code>Path</code> environment variable.</p> <p>The <code>Scripts</code> folder path looks something like this (the username and Python version may be different on your system):</p> <pre><code>C:\\Users\\MyUserNameHere\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python311\\Scripts\n</code></pre> <p>Watch the <code>pip install</code> output messages for the <code>Scripts</code> folder path on your system.</p> <p>If you're using Windows Subsystem for Linux (WSL), see Linux installation notes.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#linux-installation-notes","title":"Linux installation notes","text":"<p>Linux is a popular operating system for running Prefect. If you are hosting your own Prefect server instance with a SQLite database, note that certain Linux versions of SQLite can be problematic. Compatible versions include Ubuntu 22.04 LTS and Ubuntu 20.04 LTS.</p> <p>Alternatively, you can install SQLite on Red Hat Custom Linux (RHEL) or use the <code>conda</code> virtual environment manager and configure a compatible SQLite version.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#using-a-self-signed-ssl-certificate","title":"Using a self-signed SSL certificate","text":"<p>If you're using a self-signed SSL certificate, you need to configure your environment to trust the certificate. You can add the certificate to your system bundle and pointing your tools to use that bundle by configuring the <code>SSL_CERT_FILE</code> environment variable.</p> <p>If the certificate is not part of your system bundle, you can set the <code>PREFECT_API_TLS_INSECURE_SKIP_VERIFY</code> to <code>True</code> to disable certificate verification altogether.</p> <p>Note: Disabling certificate validation is insecure and only suggested as an option for testing!</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#proxies","title":"Proxies","text":"<p>Prefect supports communicating via proxies through environment variables. Whether you are using Prefect Cloud or hosting your own Prefect server instance, set <code>HTTPS_PROXY</code> and <code>SSL_CERT_FILE</code> in your environment, and the underlying network libraries will route Prefect\u2019s requests appropriately.</p> <p>Alternatively, the Prefect library will connect to the API via any proxies you have listed in the <code>HTTP_PROXY</code> or <code>ALL_PROXY</code> environment variables. You may also use the <code>NO_PROXY</code> environment variable to specify which hosts should not be sent through the proxy.</p> <p>For more information about these environment variables, see the cURL documentation.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#prefect-client-library","title":"<code>prefect-client</code> library","text":"<p>The <code>prefect-client</code> library is a minimal installation of Prefect designed for interacting with Prefect Cloud or a remote self-hosted server instance.</p> <p><code>prefect-client</code> enables a subset of Prefect's functionality with a smaller installation size, making it ideal for use in lightweight, resource-constrained, or ephemeral environments. It omits all CLI and server components found in the <code>prefect</code> library.</p> <p>Install the latest version with:</p> <pre><code>pip install -U prefect-client\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#sqlite","title":"SQLite","text":"<p>By default, a local Prefect server instance uses SQLite as the backing database. SQLite is not packaged with the Prefect installation. Most systems will already have SQLite installed, because it is typically bundled with Python.</p> <p>Note</p> <p>Note that in production we recommend using Prefect Cloud as your API server or hosting your own Prefect server instance backed by PostgreSQL.</p> <p>Info</p> <p>If you install the <code>prefect-client</code> library that provides a limited set of the full Prefect library's functionality, you do not need SQLite installed.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#install-sqlite-on-rhel","title":"Install SQLite on RHEL","text":"<p>To install an appropriate version of SQLite on Red Hat Custom Linux (RHEL), follow the instructions below:</p> Expand for instructions  Note that some RHEL instances have no C compiler, so you may need to check for and install `gcc` first:   <pre><code>yum install gcc\n</code></pre>   Download and extract the tarball for SQLite.   <pre><code>wget https://www.sqlite.org/2022/sqlite-autoconf-3390200.tar.gz\ntar -xzf sqlite-autoconf-3390200.tar.gz\n</code></pre>   Move to the extracted SQLite directory, then build and install SQLite.   <pre><code>cd sqlite-autoconf-3390200/\n./configure\nmake\nmake install\n</code></pre>   Add `LD_LIBRARY_PATH` to your profile.   <pre><code>echo 'export LD_LIBRARY_PATH=\"/usr/local/lib\"' &gt;&gt; /etc/profile\n</code></pre>   Restart your shell to register these changes.  Now you can install Prefect using `pip`.   <pre><code>pip3 install prefect\n</code></pre>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#installing-unreleased-code","title":"Installing unreleased code","text":"<p>To use the most up-to-date, unreleased Prefect code, you can install directly off the <code>main</code> GitHub branch:</p> <pre><code>pip install -U git+https://github.com/PrefectHQ/prefect\n</code></pre> <p>The <code>main</code> branch may not be stable</p> <p>Please be aware that this method installs unreleased code and may not be stable.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/installation/#next-steps","title":"Next steps","text":"<p>Now that you have Prefect installed and your environment configured, check out the Tutorial to get more familiar with Prefect.</p>","tags":["installation","pip install","development","Linux","Windows","SQLite","upgrading"],"boost":2},{"location":"getting-started/quickstart/","title":"Quickstart","text":"<p>Prefect is an orchestration and observability platform that empowers developers to build and scale code quickly, turning their Python scripts into resilient, recurring workflows.</p> <p>In this quickstart, you'll see how you can schedule your code on remote infrastructure and observe the state of your workflows. With Prefect, you can go from a Python script to a production-ready workflow that runs remotely in a few minutes.</p> <p>Let's get started!</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#setup","title":"Setup","text":"<p>Here's a basic script that fetches statistics about the main Prefect GitHub repository.</p> <pre><code>import httpx\n\ndef get_repo_info():\n    url = \"https://api.github.com/repos/PrefectHQ/prefect\"\n    response = httpx.get(url)\n    repo = response.json()\n    print(\"PrefectHQ/prefect repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Let's make this script schedulable, observable, resilient, and capable of running anywhere.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-1-install-prefect","title":"Step 1: Install Prefect","text":"<pre><code>pip install -U prefect\n</code></pre> <p>See the install guide for more detailed installation instructions, if needed.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-2-connect-to-prefects-api","title":"Step 2: Connect to Prefect's API","text":"<p>Much of Prefect's functionality is backed by an API. The easiest way to get started is to use the API hosted by Prefect:</p> <ol> <li>Create a forever-free Prefect Cloud account or sign in at https://app.prefect.cloud/</li> <li>Use the <code>prefect cloud login</code> CLI command to log in to Prefect Cloud from your development environment</li> </ol> <pre><code>prefect cloud login\n</code></pre> <p>Choose Log in with a web browser and click the Authorize button in the browser window that opens. Your CLI is now authenticated with your Prefect Cloud account through a locally-stored API key that expires in 30 days.</p> <p>If you have any issues with browser-based authentication, see the Prefect Cloud docs to learn how to authenticate with a manually created API key.</p> <p>Self-hosted Prefect server instance</p> <p>If you would like to host a Prefect server instance on your own infrastructure, see the tutorial and select the \"Self-hosted\" tab. Note that you will need to both host your own server and run your flows on your own infrastructure.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-3-turn-your-function-into-a-prefect-flow","title":"Step 3: Turn your function into a Prefect flow","text":"<p>The fastest way to get started with Prefect is to add a <code>@flow</code> decorator to your Python function. Flows are the core observable, deployable units in Prefect and are the primary entrypoint to orchestrated work.</p> my_gh_workflow.py<pre><code>import httpx   # an HTTP client library and dependency of Prefect\nfrom prefect import flow, task\n\n\n@task(retries=2)\ndef get_repo_info(repo_owner: str, repo_name: str):\n    \"\"\"Get info about a repo - will retry twice after failing\"\"\"\n    url = f\"https://api.github.com/repos/{repo_owner}/{repo_name}\"\n    api_response = httpx.get(url)\n    api_response.raise_for_status()\n    repo_info = api_response.json()\n    return repo_info\n\n\n@task\ndef get_contributors(repo_info: dict):\n    \"\"\"Get contributors for a repo\"\"\"\n    contributors_url = repo_info[\"contributors_url\"]\n    response = httpx.get(contributors_url)\n    response.raise_for_status()\n    contributors = response.json()\n    return contributors\n\n\n@flow(log_prints=True)\ndef repo_info(repo_owner: str = \"PrefectHQ\", repo_name: str = \"prefect\"):\n    \"\"\"\n    Given a GitHub repository, logs the number of stargazers\n    and contributors for that repo.\n    \"\"\"\n    repo_info = get_repo_info(repo_owner, repo_name)\n    print(f\"Stars \ud83c\udf20 : {repo_info['stargazers_count']}\")\n\n    contributors = get_contributors(repo_info)\n    print(f\"Number of contributors \ud83d\udc77: {len(contributors)}\")\n\n\nif __name__ == \"__main__\":\n    repo_info()\n</code></pre> <p>Note that we added a <code>log_prints=True</code> argument to the <code>@flow</code> decorator so that <code>print</code> statements within the flow-decorated function will be logged. Also note that our flow calls two tasks, which are defined by the <code>@task</code> decorator. Tasks are the smallest unit of observed and orchestrated work in Prefect.</p> <pre><code>python my_gh_workflow.py\n</code></pre> <p>Now when we run this script, Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.</p> <pre><code>14:28:31.099 | INFO    | prefect.engine - Created flow run 'energetic-panther' for flow 'repo-info'\n14:28:31.100 | INFO    | Flow run 'energetic-panther' - View at https://app.prefect.cloud/account/123/workspace/abc/flow-runs/flow-run/xyz\n14:28:32.178 | INFO    | Flow run 'energetic-panther' - Created task run 'get_repo_info-0' for task 'get_repo_info'\n14:28:32.179 | INFO    | Flow run 'energetic-panther' - Executing 'get_repo_info-0' immediately...\n14:28:32.584 | INFO    | Task run 'get_repo_info-0' - Finished in state Completed()\n14:28:32.599 | INFO    | Flow run 'energetic-panther' - Stars \ud83c\udf20 : 13609\n14:28:32.682 | INFO    | Flow run 'energetic-panther' - Created task run 'get_contributors-0' for task 'get_contributors'\n14:28:32.682 | INFO    | Flow run 'energetic-panther' - Executing 'get_contributors-0' immediately...\n14:28:33.118 | INFO    | Task run 'get_contributors-0' - Finished in state Completed()\n14:28:33.134 | INFO    | Flow run 'energetic-panther' - Number of contributors \ud83d\udc77: 30\n14:28:33.255 | INFO    | Flow run 'energetic-panther' - Finished in state Completed('All states completed.')\n</code></pre> <p>You should see similar output in your terminal, with your own randomly generated flow run name and your own Prefect Cloud account URL.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-4-choose-a-remote-infrastructure-location","title":"Step 4: Choose a remote infrastructure location","text":"<p>Let's get this workflow running on infrastructure other than your local machine! We can tell Prefect where we want to run our workflow by creating a work pool.</p> <p>We can have Prefect Cloud run our flow code for us with a Prefect Managed work pool.</p> <p>Let's create a Prefect Managed work pool so that Prefect can run our flows for us. We can create a work pool in the UI or from the CLI. Let's use the CLI:</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed\n</code></pre> <p>You should see a message in the CLI that your work pool was created. Feel free to check out your new work pool on the Work Pools page in the UI.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#step-5-make-your-code-schedulable","title":"Step 5: Make your code schedulable","text":"<p>We have a flow function and we have a work pool where we can run our flow remotely. Let's package both of these things, along with the location for where to find our flow code, into a deployment so that we can schedule our workflow to run remotely.</p> <p>Deployments elevate flows to remotely configurable entities that have their own API.</p> <p>Let's make a script to build a deployment with the name my-first-deployment and set it to run on a schedule.</p> create_deployment.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/prefecthq/demos.git\",\n        entrypoint=\"my_gh_workflow.py:repo_info\",\n    ).deploy(\n        name=\"my-first-deployment\",\n        work_pool_name=\"my-managed-pool\",\n        cron=\"0 1 * * *\",\n    )\n</code></pre> <p>Run the script to create the deployment on the Prefect Cloud server. Note that the <code>cron</code> argument will schedule the deployment to run at 1am every day.</p> <pre><code>python create_deployment.py\n</code></pre> <p>You should see a message that your deployment was created, similar to the one below.</p> <pre><code>Successfully created/updated all deployments!\n______________________________________________________\n|                    Deployments                     |  \n______________________________________________________\n|    Name                       |  Status  | Details |\n______________________________________________________\n| repo-info/my-first-deployment | applied  |         |\n______________________________________________________\n\nTo schedule a run for this deployment, use the following command:\n\n       $ prefect deployment run 'repo-info/my-first-deployment'\n\nYou can also run your flow via the Prefect UI: &lt;https://app.prefect.cloud/account/abc/workspace/123/deployments/deployment/xyz&gt;\n</code></pre> <p>Head to the Deployments page of the UI to check it out.</p> <p>Code storage options</p> <p>You can store your flow code in nearly any location. You just need to tell Prefect where to find it. In this example, we use a GitHub repository, but you could bake your code into a Docker image or store it in cloud provider storage. Read more in this guide.</p> <p>Push your code to GitHub</p> <p>In the example above, we use an existing GitHub repository. If you make changes to the flow code, you will need to push those changes to your own GitHub account and update the <code>source</code> argument to point to your repository.</p> <p>You can trigger a manual run of this deployment by either clicking the Run button in the top right of the deployment page in the UI, or by running the following CLI command in your terminal:</p> <pre><code>prefect deployment run 'repo-info/my-first-deployment'\n</code></pre> <p>The deployment is configured to run on a Prefect Managed work pool, so Prefect will automatically spin up the infrastructure to run this flow. It may take a minute to set up the Docker image in which the flow will run.</p> <p>After a minute or so, you should see the flow run graph and logs on the Flow Run page in the UI.</p> <p></p> <p>Remove the schedule</p> <p>Click the Remove button in the top right of the Deployment page so that the workflow is no longer scheduled to run once per day.</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"getting-started/quickstart/#next-steps","title":"Next steps","text":"<p>You've seen how to move from a Python script to a scheduled, observable, remotely orchestrated workflow with Prefect.</p> <p>To learn how to run flows on your own infrastructure, customize the Docker image where your flow runs, and gain more orchestration and observation benefits check out the tutorial.</p> <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a meeting</p> <p>Happy building!</p>","tags":["getting started","quickstart","overview"],"boost":2},{"location":"guides/","title":"How-to Guides","text":"<p>This section of the documentation contains how-to guides for common workflows and use cases.</p>","tags":["guides","how to"],"boost":2},{"location":"guides/#development","title":"Development","text":"Title Description Hosting Host your own Prefect server instance. Profiles &amp; Settings Configure Prefect and save your settings. Testing Easily test your workflows. Global Concurrency Limits Limit flow runs. Runtime Context Enable a flow to access metadata about itself and its context when it runs. Variables Store and retrieve configuration data. Prefect Client Use <code>PrefectClient</code> to interact with the API server. Interactive Workflows Create human-in-the-loop workflows by pausing flow runs for input. Automations Configure actions that Prefect executes automatically based on trigger conditions. Webhooks Receive, observe, and react to events from other systems. Terraform Provider Use the Terraform Provider for Prefect Cloud for infrastructure as code. CI/CD Use CI/CD with Prefect. Specifying Upstream Dependencies Run tasks in a desired order. Third-party Secrets Use credentials stored in a secrets manager in your workflows. Prefect Recipes Common, extensible examples for setting up Prefect.","tags":["guides","how to"],"boost":2},{"location":"guides/#execution","title":"Execution","text":"Title Description Docker Deploy flows with Docker containers. State Change Hooks Execute code in response to state changes. Dask and Ray Scale your flows with parallel computing frameworks. Read and Write Data Read and write data to and from cloud provider storage. Big Data Handle large data with Prefect. Logging Configure Prefect's logger and aggregate logs from other tools. Troubleshooting Identify and resolve common issues with Prefect. Managed Execution Let prefect run your code. Shell Commands Shell commands as Prefect flows","tags":["guides","how to"],"boost":2},{"location":"guides/#work-pools","title":"Work Pools","text":"Title Description Deploying Flows to Work Pools and Workers Learn how to run you code with dynamic infrastructure. Upgrade from Agents to Workers Why and how to upgrade from agents to workers. Flow Code Storage Where to store your code for deployments. Kubernetes Deploy flows on Kubernetes. Serverless Push Work Pools Run flows on serverless infrastructure without a worker. Serverless Work Pools with Workers Run flows on serverless infrastructure with a worker. Daemonize Processes Set up a systemd service to run a Prefect worker or .serve process. Custom Workers Develop your own worker type. Overriding Work Pool Job Variables Override job variables for a work pool for a given deployment. <p>Need help?</p> <p>Get your questions answered by a Prefect Product Advocate! Book a Meeting</p>","tags":["guides","how to"],"boost":2},{"location":"guides/automations/","title":"Using Automations for Dynamic Responses","text":"<p>From the Automations concept page, we saw what an automation can do and how to configure one within the UI. </p> <p>In this guide, we will showcase the following common use cases:</p> <ul> <li>Create a simple notification automation in just a few UI clicks</li> <li>Build upon an event based automation</li> <li>Combine into a multi-layered responsive deployment pattern</li> </ul> <p>Available only on Prefect Cloud</p> <pre><code>Automations are a Prefect Cloud feature.\n</code></pre>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#prerequisites","title":"Prerequisites","text":"<p>Please have the following before exploring the guide:</p> <ul> <li>Python installed</li> <li>Prefect installed (follow the installation guide)</li> <li>Authenticated to a Prefect Cloud workspace</li> <li>A work pool set up to handle the deployments</li> </ul>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#creating-the-example-script","title":"Creating the example script","text":"<p>Automations allow you to take actions in response to triggering events recorded by Prefect. </p> <p>For example, let's try to grab data from an API and send a notification based on the end state. </p> <p>We can start by pulling hypothetical user data from an endpoint and then performing data cleaning and transformations. </p> <p>Let's create a simple extract method, that pulls the data from a random user data generator endpoint. </p> <pre><code>from prefect import flow, task, get_run_logger\nimport requests\nimport json\n\n@task\ndef fetch(url: str):\n    logger = get_run_logger()\n    response = requests.get(url)\n    raw_data = response.json()\n    logger.info(f\"Raw response: {raw_data}\")\n    return raw_data\n\n@task\ndef clean(raw_data: dict):\n    print(raw_data.get('results')[0])\n    results = raw_data.get('results')[0]\n    logger = get_run_logger()\n    logger.info(f\"Cleaned results: {results}\")\n    return results['name']\n\n@flow\ndef build_names(num: int = 10):\n    df = []\n    url = \"https://randomuser.me/api/\"\n    logger = get_run_logger()\n    copy = num\n    while num != 0:\n        raw_data = fetch(url)\n        df.append(clean(raw_data))\n        num -= 1\n    logger.info(f\"Built {copy} names: {df}\")\n    return df\n\nif __name__ == \"__main__\":\n    list_of_names = build_names()\n</code></pre> <p>The data cleaning workflow has visibility into each step, and we are sending a list of names to our next step of our pipeline.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#create-notification-block-within-the-ui","title":"Create notification block within the UI","text":"<p>Now let's try to send a notification based off a completed state outcome. We can configure a notification to be sent so that we know when to look into our workflow logic. </p> <ol> <li> <p>Prior to creating the automation, let's confirm the notification location. We have to create a notification block to help define where the notification will be sent.  </p> </li> <li> <p>Let's navigate to the blocks page on the UI, and click into creating an email notification block.  </p> </li> <li> <p>Now that we created a notification block, we can go to the automations page to create our first automation. </p> </li> <li> <p>Next we try to find the trigger type, in this case let's use a flow completion.  </p> </li> <li> <p>Finally, let's create the actions that will be done once the triggered is hit. In this case, let's create a notification to be sent out to showcase the completion.  </p> </li> <li> <p>Now the automation is ready to be triggered from a flow run completion. Let's run the file locally and see that the notification is sent to our inbox after the completion. It may take a few minutes for the notification to arrive. </p> </li> </ol> <p>No deployment created</p> <p>Keep in mind, we did not need to create a deployment to trigger our automation, where a state outcome of a local flow run helped trigger this notification block. We are not required to create a deployment to trigger a notification.</p> <p>Now that you've seen how to create an email notification from a flow run completion, let's see how we can kick off a deployment run in response to an event.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#event-based-deployment-automation","title":"Event-based deployment automation","text":"<p>We can create an automation that can kick off a deployment instead of a notification. Let's explore how we can programmatically create this automation. We will take advantage of Prefect's REST API to help create this automation.  </p> <p>See the REST API documentation as a reference for interacting with the Prefect Cloud automation endpoints.</p> <p>Let's create a deployment where we can kick off some work based on how long a flow is running. For example, if the <code>build_names</code> flow is taking too long to execute, we can kick off a deployment of the with the same <code>build_names</code> flow, but replace the <code>count</code> value with a lower number - to speed up completion. You can create a deployment with a <code>prefect.yaml</code> file or a Python file that uses <code>flow.deploy</code>.</p> prefect.yaml.deploy <p>Create a <code>prefect.yaml</code> file like this one for our flow <code>build_names</code>:</p> <pre><code>  # Welcome to your prefect.yaml file! You can use this file for storing and managing\n  # configuration for deploying your flows. We recommend committing this file to source\n  # control along with your flow code.\n\n  # Generic metadata about this project\n  name: automations-guide\n  prefect-version: 2.13.1\n\n  # build section allows you to manage and build docker images\n  build: null\n\n  # push section allows you to manage if and how this project is uploaded to remote locations\n  push: null\n\n  # pull section allows you to provide instructions for cloning this project in remote locations\n  pull:\n  - prefect.deployments.steps.set_working_directory:\n      directory: /Users/src/prefect/Playground/automations-guide\n\n  # the deployments section allows you to provide configuration for deploying flows\n  deployments:\n  - name: deploy-build-names\n    version: null\n    tags: []\n    description: null\n    entrypoint: test-automations.py:build_names\n    parameters: {}\n    work_pool:\n      name: tutorial-process-pool\n      work_queue_name: null\n      job_variables: {}\n    schedule: null\n</code></pre> <p>To follow a more Python based approach to create a deployment, you can use <code>flow.deploy</code> as in the example below.</p> <pre><code># .deploy only needs a name, valid work pool \n# and a reference to where the flow code exists\n\nif __name__ == \"__main__\":\nbuild_names.deploy(\n    name=\"deploy-build-names\",\n    work_pool_name=\"tutorial-process-pool\"\n    image=\"my_registry/my_image:my_image_tag\",\n)\n</code></pre> <p>Now let's grab our <code>deployment_id</code> from this deployment, and embed it in our automation. There are many ways to obtain the <code>deployment_id</code>, but the CLI is a quick way to see all of your deployment ids. </p> <p>Find deployment_id from the CLI</p> <p>The quickest way to see the ID's associated with your deployment would be running <code>prefect deployment ls</code>   in an authenticated command prompt, and you will be able to see the id's associated with all of your deployments</p> <p><pre><code>prefect deployment ls\n                                          Deployments                                           \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                                                  \u2503 ID                                   \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Extract islands/island-schedule                       \u2502 d9d7289c-7a41-436d-8313-80a044e61532 \u2502\n\u2502 build-names/deploy-build-names                        \u2502 8b10a65e-89ef-4c19-9065-eec5c50242f4 \u2502\n\u2502 ride-duration-prediction-backfill/backfill-deployment \u2502 76dc6581-1773-45c5-a291-7f864d064c57 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> We can create an automation via a POST call, where we can programmatically create the automation. Ensure you have your <code>api_key</code>, <code>account_id</code>, and <code>workspace_id</code>. </p> <pre><code>def create_event_driven_automation():\n    api_url = f\"https://api.prefect.cloud/api/accounts/{account_id}/workspaces/{workspace_id}/automations/\"\n    data = {\n    \"name\": \"Event Driven Redeploy\",\n    \"description\": \"Programmatically created an automation to redeploy a flow based on an event\",\n    \"enabled\": \"true\",\n    \"trigger\": {\n    \"after\": [\n        \"string\"\n    ],\n    \"expect\": [\n        \"prefect.flow-run.Running\"\n    ],\n    \"for_each\": [\n        \"prefect.resource.id\"\n    ],\n    \"posture\": \"Proactive\",\n    \"threshold\": 30,\n    \"within\": 0\n    },\n    \"actions\": [\n    {\n        \"type\": \"run-deployment\",\n        \"source\": \"selected\",\n        \"deployment_id\": \"YOUR-DEPLOYMENT-ID\", \n        \"parameters\": \"10\"\n    }\n    ],\n    \"owner_resource\": \"string\"\n        }\n\n    headers = {\"Authorization\": f\"Bearer {PREFECT_API_KEY}\"}\n    response = requests.post(api_url, headers=headers, json=data)\n\n    print(response.json())\n    return response.json()\n</code></pre> <p>After running this function, you will see within the UI the changes that came from the post request. Keep in mind, the context will be \"custom\" on UI. </p> <p>Let's run the underlying flow and see the deployment get kicked off after 30 seconds elapsed. This will result in a new flow run of <code>build_names</code>, and we are able to see this new deployment get initiated with the custom parameters we outlined above. </p> <p>In a few quick changes, we are able to programmatically create an automation that deploys workflows with custom parameters. </p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#using-an-underlying-yaml-file","title":"Using an underlying .yaml file","text":"<p>We can extend this idea one step further by utilizing our own .yaml version of the automation, and registering that file with our UI. This simplifies the requirements of the automation by declaring it in its own .yaml file, and then registering that .yaml with the API. </p> <p>Let's first start with creating the .yaml file that will house the automation requirements. Here is how it would look like:</p> <pre><code>name: Cancel long running flows\ndescription: Cancel any flow run after an hour of execution\ntrigger:\n  match:\n    \"prefect.resource.id\": \"prefect.flow-run.*\"\n  match_related: {}\n  after:\n    - \"prefect.flow-run.Failed\"\n  expect:\n    - \"prefect.flow-run.*\"\n  for_each:\n    - \"prefect.resource.id\"\n  posture: \"Proactive\"\n  threshold: 1\n  within: 30\nactions:\n  - type: \"cancel-flow-run\"\n</code></pre> <p>We can then have a helper function that applies this YAML file with the REST API function.  <pre><code>import yaml\n\nfrom utils import post, put\n\ndef create_or_update_automation(path: str = \"automation.yaml\"):\n    \"\"\"Create or update an automation from a local YAML file\"\"\"\n    # Load the definition\n    with open(path, \"r\") as fh:\n        payload = yaml.safe_load(fh)\n\n    # Find existing automations by name\n    automations = post(\"/automations/filter\")\n    existing_automation = [a[\"id\"] for a in automations if a[\"name\"] == payload[\"name\"]]\n    automation_exists = len(existing_automation) &gt; 0\n\n    # Create or update the automation\n    if automation_exists:\n        print(f\"Automation '{payload['name']}' already exists and will be updated\")\n        put(f\"/automations/{existing_automation[0]}\", payload=payload)\n    else:\n        print(f\"Creating automation '{payload['name']}'\")\n        post(\"/automations/\", payload=payload)\n\nif __name__ == \"__main__\":\n    create_or_update_automation()\n</code></pre></p> <p>You can find a complete repo with these APIs examples in this GitHub repository. </p> <p>In this example, we managed to create the automation by registering the .yaml file with a helper function. This offers another experience when trying to create an automation.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#custom-webhook-kicking-off-an-automation","title":"Custom webhook kicking off an automation","text":"<p>We can use webhooks to expose the events API which allows us to extend the functionality of deployments and ways to respond to changes in our workflow through a few easy steps. </p> <p>By exposing a webhook endpoint, we can kick off workflows that can trigger deployments - all from a simple event created from an HTTP request. </p> <p>Lets create a webhook within the UI.  Here is the webhook we can use to create these dynamic events. <pre><code>{\n    \"event\": \"model-update\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.{{ body.model_id}}\",\n        \"prefect.resource.name\": \"{{ body.friendly_name }}\",\n        \"run_count\": \"{{body.run_count}}\"\n    }\n}\n</code></pre> From a simple input, we can easily create an exposed webhook endpoint. </p> <p></p> <p>Each webhook will correspond to a custom event created, where you can react to it downstream with a separate deployment or automation. </p> <p>For example, we can create a curl request that sends the endpoint information such as a run count for our deployment.  <pre><code>curl -X POST https://api.prefect.cloud/hooks/34iV2SFke3mVa6y5Y-YUoA -d \"model_id=adhoc\" -d \"run_count=10\" -d \"friendly_name=test-user-input\"\n</code></pre> From here, we can make a webhook that is connected to pulling in parameters on the curl command, and then it kicks off a deployment that uses these pulled parameters. </p> <p>Let us go into the event feed, and we can automate straight from this event.  </p> <p>This allows us to create automations that respond to these webhook events. From a few clicks in the UI, we are able to associate an external process with the Prefect events API, that can enable us to trigger downstream deployments.  </p> <p>In the next section, we will explore event triggers that automate the kickoff of a deployment run.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#using-triggers","title":"Using triggers","text":"<p>Let's take this idea one step further, by creating a deployment that will be triggered when a flow run takes longer than expected.  We can take advantage of Prefect's Marvin library that will use an LLM to classify our data.  Marvin is great at embedding data science and data analysis applications within your pre-existing data engineering workflows. In this case, we can use Marvin'd AI functions to help make our dataset more information rich. </p> <p>Install Marvin with <code>pip install marvin</code> and set you OpenAI API key as shown here</p> <p>We can add a trigger to run a deployment in response to a specific event. </p> <p>Let's create an example with Marvin's AI functions. We will take in a pandas DataFrame and use the AI function to analyze it. </p> <p>Here is an example of pulling in that data and classifying using Marvin AI. We can help create dummy data based on classifications we have already created.</p> <pre><code>from marvin import ai_classifier\nfrom enum import Enum\nimport pandas as pd\n\n@ai_fn\ndef generate_synthetic_user_data(build_of_names: list[dict]) -&gt; list:\n    \"\"\"\n    Generate additional data for userID (numerical values with 6 digits), location, and timestamp as separate columns and append the data onto 'build_of_names'. Make userID the first column\n    \"\"\"\n\n@flow\ndef create_fake_user_dataset(df):\n  artifact_df = generate_synthetic_user_data(df)\n  print(artifact_df)\n\n  create_table_artifact(\n      key=\"fake-user-data\",\n      table=artifact_df,\n      description= \"Dataset that is comprised of a mix of autogenerated data based on user data\"\n  )\n\nif __name__ == \"__main__\":\n    create_fake_artifact()  \n</code></pre> <p>Let's kick off a deployment with a trigger defined in a <code>prefect.yaml</code> file. Let's specify what we want to trigger when the event stays in a running state for longer than 30 seconds.  <pre><code># Welcome to your prefect.yaml file! You can use this file for storing and managing\n# configuration for deploying your flows. We recommend committing this file to source\n# control along with your flow code.\n\n# Generic metadata about this project\nname: automations-guide\nprefect-version: 2.13.1\n\n# build section allows you to manage and build docker images\nbuild: null\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush: null\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /Users/src/prefect/Playground/marvin-extension\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: create-fake-user-dataset\n  triggers:\n    - enabled: true\n      match:\n        prefect.resource.id: \"prefect.flow-run.*\"\n      after: \"prefect.flow-run.Running\",\n      expect: [],\n      for_each: [\"prefect.resource.id\"],\n      parameters:\n        param_1: 10\n      posture: \"Proactive\"\n  version: null\n  tags: []\n  description: null\n  entrypoint: marvin-extension.py:create_fake_user_dataset\n  parameters: {}\n  work_pool:\n    name: tutorial-process-pool\n    work_queue_name: null\n    job_variables: {}\n  schedule: null\n</code></pre></p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/automations/#next-steps","title":"Next steps","text":"<p>You've seen how to create automations via the UI, REST API, and a triggers defined in a <code>prefect.yaml</code> deployment definition.</p> <p>To learn more about events that can act as automation triggers, see the events docs.  To learn more about event webhooks in particular, see the webhooks guide.</p>","tags":["automations","event-driven","trigger"],"boost":2},{"location":"guides/big-data/","title":"Big Data with Prefect","text":"<p>In this guide you'll learn tips for working with large amounts of data in Prefect.</p> <p>Big data doesn't have a widely accepted, precise definition. In this guide, we'll discuss methods to reduce the processing time or memory utilization of Prefect workflows, without editing your Python code.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#optimizing-your-python-code-with-prefect-for-big-data","title":"Optimizing your Python code with Prefect for big data","text":"<p>Depending upon your needs, you may want to optimize your Python code for speed, memory, compute, or disk space.</p> <p>Prefect provides several options that we'll explore in this guide:</p> <ol> <li>Remove task introspection with <code>quote</code> to save time running your code.</li> <li>Write task results to cloud storage such as S3 using a block to save memory.</li> <li>Save data to disk within a flow rather than using results.</li> <li>Cache task results to save time and compute.</li> <li>Compress results written to disk to save space.</li> <li>Use a task runner for parallelizable operations to save time.</li> </ol>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#remove-task-introspection","title":"Remove task introspection","text":"<p>When a task is called from a flow, each argument is introspected by Prefect, by default. To speed up your flow runs, you can disable this behavior for a task by wrapping the argument using <code>quote</code>.</p> <p>To demonstrate, let's use a basic example that extracts and transforms some New York taxi data.</p> et_quote.py<pre><code>from prefect import task, flow\nfrom prefect.utilities.annotations import quote\nimport pandas as pd\n\n\n@task\ndef extract(url: str):\n    \"\"\"Extract data\"\"\"\n    df_raw = pd.read_parquet(url)\n    print(df_raw.info())\n    return df_raw\n\n\n@task\ndef transform(df: pd.DataFrame):\n    \"\"\"Basic transformation\"\"\"\n    df[\"tip_fraction\"] = df[\"tip_amount\"] / df[\"total_amount\"]\n    print(df.info())\n    return df\n\n\n@flow(log_prints=True)\ndef et(url: str):\n    \"\"\"ET pipeline\"\"\"\n    df_raw = extract(url)\n    df = transform(quote(df_raw))\n\n\nif __name__ == \"__main__\":\n    url = \"https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2023-09.parquet\"\n    et(url)\n</code></pre> <p>Introspection can take significant time when the object being passed is a large collection, such as dictionary or DataFrame, where each element needs to be visited. Note that using <code>quote</code> reduces execution time at the expense of disabling task dependency tracking for the wrapped object.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#write-task-results-to-cloud-storage","title":"Write task results to cloud storage","text":"<p>By default, the results of task runs are stored in memory in your execution environment. This behavior makes flow runs fast for small data, but can be problematic for large data. You can save memory by writing results to disk. In production, you'll generally want to write results to a cloud provider storage such as AWS S3. Prefect lets you to use a storage block from a Prefect cloud integration library such as prefect-aws to save your configuration information. Learn more about blocks here.</p> <p>Install the relevant library, register the block with the server, and create your storage block. Then you can reference the block in your flow like this:</p> <pre><code>...\nfrom prefect_aws.s3 import S3Bucket\n\nmy_s3_block = S3Bucket.load(\"MY_BLOCK_NAME\")\n\n...\n@task(result_storage=my_s3_block)\n</code></pre> <p>Now the result of the task will be written to S3, rather than stored in memory.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#save-data-to-disk-within-a-flow","title":"Save data to disk within a flow","text":"<p>To save memory and time with big data, you don't need to pass results between tasks at all. Instead, you can write and read data to disk directly in your flow code. Prefect has integration libraries for each of the major cloud providers. Each library contains blocks with methods that make it convenient to read and write data to and from cloud object storage. The moving data guide has step-by-step examples for each cloud provider.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#cache-task-results","title":"Cache task results","text":"<p>Caching allows you to avoid re-running tasks when doing so is unnecessary. Caching can save you time and compute. Note that caching requires task result persistence. Caching is discussed in detail in the tasks concept page.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#compress-results-written-to-disk","title":"Compress results written to disk","text":"<p>If you're using Prefect's task result persistence, you can save disk space by compressing the results. You just need to specify the result type with <code>compressed/</code> prefixed like this:</p> <pre><code>@task(result_serializer=\"compressed/json\")\n</code></pre> <p>Read about compressing results with Prefect for more details. The tradeoff of using compression is that it takes time to compress and decompress the data.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/big-data/#use-a-task-runner-for-parallelizable-operations","title":"Use a task runner for parallelizable operations","text":"<p>Prefect's task runners allow you to use the Dask and Ray Python libraries to run tasks in parallel and distributed across multiple machines. This can save you time and compute when operating on large data structures. See the guide to working with Dask and Ray Task Runners for details.</p>","tags":["big data","flow configuration","parallel execution","distributed execution","caching"],"boost":2},{"location":"guides/ci-cd/","title":"CI/CD With Prefect","text":"<p>Many organizations deploy Prefect workflows via their CI/CD process. Each organization has their own unique CI/CD setup, but a common pattern is to use CI/CD to manage Prefect deployments. Combining Prefect's deployment features with CI/CD tools enables efficient management of flow code updates, scheduling changes, and container builds. This guide uses GitHub Actions to implement a CI/CD process, but these concepts are generally applicable across many CI/CD tools.</p> <p>Note that Prefect's primary ways for creating deployments, a <code>.deploy</code> flow method or a <code>prefect.yaml</code> configuration file, are both designed with building and pushing images to a Docker registry in mind.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#getting-started-with-github-actions-and-prefect","title":"Getting started with GitHub Actions and Prefect","text":"<p>In this example, you'll write a GitHub Actions workflow that will run each time you push to your repository's <code>main</code> branch. This workflow will build and push a Docker image containing your flow code to Docker Hub, then deploy the flow to Prefect Cloud.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#repository-secrets","title":"Repository secrets","text":"<p>Your CI/CD process must be able to authenticate with Prefect in order to deploy flows.</p> <p>Deploying flows securely and non-interactively in your CI/CD process can be accomplished by saving your <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as secrets in your repository's settings so they can be accessed in your CI/CD runner's environment without exposing them in any scripts or configuration files.</p> <p>In this scenario, deploying flows involves building and pushing Docker images, so add <code>DOCKER_USERNAME</code> and <code>DOCKER_PASSWORD</code> as secrets to your repository as well.</p> <p>You can create secrets for GitHub Actions in your repository under Settings -&gt; Secrets and variables -&gt; Actions -&gt; New repository secret:</p> <p></p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#writing-a-github-workflow","title":"Writing a GitHub workflow","text":"<p>To deploy your flow via GitHub Actions, you'll need a workflow YAML file. GitHub will look for workflow YAML files in the <code>.github/workflows/</code> directory in the root of your repository. In their simplest form, GitHub workflow files are made up of triggers and jobs.</p> <p>The <code>on:</code> trigger is set to run the workflow each time a push occurs on the <code>main</code> branch of the repository.</p> <p>The <code>deploy</code> job is comprised of four <code>steps</code>:</p> <ul> <li><code>Checkout</code> clones your repository into the GitHub Actions runner so you can reference files or run scripts from your repository in later steps.</li> <li><code>Log in to Docker Hub</code> authenticates to DockerHub so your image can be pushed to the Docker registry in your DockerHub account. docker/login-action is an existing GitHub action maintained by Docker. <code>with:</code> passes values into the Action, similar to passing parameters to a function.</li> <li><code>Setup Python</code> installs your selected version of Python.</li> <li><code>Prefect Deploy</code> installs the dependencies used in your flow, then deploys your flow. <code>env:</code> makes the <code>PREFECT_API_KEY</code> and <code>PREFECT_API_URL</code> secrets from your repository available as environment variables during this step's execution.</li> </ul> <p>For reference, the examples below can be found on their respective branches of this repository.</p> .deployprefect.yaml <pre><code>.\n\u251c\u2500\u2500 .github/\n\u2502   \u2514\u2500\u2500 workflows/\n\u2502       \u2514\u2500\u2500 deploy-prefect-flow.yaml\n\u251c\u2500\u2500 flow.py\n\u2514\u2500\u2500 requirements.txt\n</code></pre> <p><code>flow.py</code></p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef hello():\n  print(\"Hello!\")\n\nif __name__ == \"__main__\":\n    hello.deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"my-work-pool\",\n        image=\"my_registry/my_image:my_image_tag\",\n    )\n</code></pre> <p><code>.github/workflows/deploy-prefect-flow.yaml</code></p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n\n      - name: Prefect Deploy\n        env:\n          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}\n          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}\n        run: |\n          pip install -r requirements.txt\n          python flow.py\n</code></pre> <pre><code>.\n\u251c\u2500\u2500 .github/\n\u2502   \u2514\u2500\u2500 workflows/\n\u2502       \u2514\u2500\u2500 deploy-prefect-flow.yaml\n\u251c\u2500\u2500 flow.py\n\u251c\u2500\u2500 prefect.yaml\n\u2514\u2500\u2500 requirements.txt\n</code></pre> <p><code>flow.py</code></p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef hello():\n  print(\"Hello!\")\n</code></pre> <p><code>prefect.yaml</code></p> <pre><code>name: cicd-example\nprefect-version: 2.14.11\n\nbuild:\n  - prefect_docker.deployments.steps.build_docker_image:\n      id: build_image\n      requires: prefect-docker&gt;=0.3.1\n      image_name: my_registry/my_image\n      tag: my_image_tag\n      dockerfile: auto\n\npush:\n  - prefect_docker.deployments.steps.push_docker_image:\n      requires: prefect-docker&gt;=0.3.1\n      image_name: \"{{ build_image.image_name }}\"\n      tag: \"{{ build_image.tag }}\"\n\npull: null\n\ndeployments:\n  - name: my-deployment\n    entrypoint: flow.py:hello\n    work_pool:\n      name: my-work-pool\n      work_queue_name: default\n      job_variables:\n        image: \"{{ build-image.image }}\"\n</code></pre> <p><code>.github/workflows/deploy-prefect-flow.yaml</code></p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n\n      - name: Prefect Deploy\n        env:\n          PREFECT_API_KEY: ${{ secrets.PREFECT_API_KEY }}\n          PREFECT_API_URL: ${{ secrets.PREFECT_API_URL }}\n        run: |\n          pip install -r requirements.txt\n          prefect deploy -n my-deployment\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#running-a-github-workflow","title":"Running a GitHub workflow","text":"<p>After pushing commits to your repository, GitHub will automatically trigger a run of your workflow. The status of running and completed workflows can be monitored from the Actions tab of your repository.</p> <p></p> <p>You can view the logs from each workflow step as they run. The <code>Prefect Deploy</code> step will include output about your image build and push, and the creation/update of your deployment.</p> <pre><code>Successfully built image '***/cicd-example:latest'\n\nSuccessfully pushed image '***/cicd-example:latest'\n\nSuccessfully created/updated all deployments!\n\n                Deployments\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                \u2503 Status  \u2503 Details \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 hello/my-deployment \u2502 applied \u2502         \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#advanced-example","title":"Advanced example","text":"<p>In more complex scenarios, CI/CD processes often need to accommodate several additional considerations to enable a smooth development workflow:</p> <ul> <li>Making code available in different environments as it advances through stages of development</li> <li>Handling independent deployment of distinct groupings of work, as in a monorepo</li> <li>Efficiently using build time to avoid repeated work</li> </ul> <p>This example repository demonstrates how each of these considerations can be addressed using a combination of Prefect's and GitHub's capabilities.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#deploying-to-multiple-workspaces","title":"Deploying to multiple workspaces","text":"<p>Which deployment processes should run are automatically selected when changes are pushed depending on two conditions:</p> <pre><code>on:\n  push:\n    branches:\n      - stg\n      - main\n    paths:\n      - \"project_1/**\"\n</code></pre> <ol> <li><code>branches:</code> - which branch has changed. This will ultimately select which Prefect workspace a deployment is created or updated in. In this example, changes on the <code>stg</code> branch will deploy flows to a staging workspace, and changes on the <code>main</code> branch will deploy flows to a production workspace.</li> <li><code>paths:</code> - which project folders' files have changed. Since each project folder contains its own flows, dependencies, and <code>prefect.yaml</code>, it represents a complete set of logic and configuration that can be deployed independently. Each project in this repository gets its own GitHub Actions workflow YAML file.</li> </ol> <p>The <code>prefect.yaml</code> file in each project folder depends on environment variables that are dictated by the selected job in each CI/CD workflow, enabling external code storage for Prefect deployments that is clearly separated across projects and environments.</p> <pre><code>  .\n  \u251c\u2500\u2500 cicd-example-workspaces-prod  # production bucket\n  \u2502   \u251c\u2500\u2500 project_1\n  \u2502   \u2514\u2500\u2500 project_2\n  \u2514\u2500\u2500 cicd-example-workspaces-stg  # staging bucket\n      \u251c\u2500\u2500 project_1\n      \u2514\u2500\u2500 project_2  \n</code></pre> <p>Since the deployments in this example use S3 for code storage, it's important that push steps place flow files in separate locations depending upon their respective environment and project so no deployment overwrites another deployment's files.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#caching-build-dependencies","title":"Caching build dependencies","text":"<p>Since building Docker images and installing Python dependencies are essential parts of the deployment process, it's useful to rely on caching to skip repeated build steps.</p> <p>The <code>setup-python</code> action offers caching options so Python packages do not have to be downloaded on repeat workflow runs.</p> <pre><code>- name: Setup Python\n  uses: actions/setup-python@v5\n  with:\n    python-version: \"3.11\"\n    cache: \"pip\"\n</code></pre> <pre><code>Using cached prefect-2.16.1-py3-none-any.whl (2.9 MB)\nUsing cached prefect_aws-0.4.10-py3-none-any.whl (61 kB)\n</code></pre> <p>The <code>build-push-action</code> for building Docker images also offers caching options for GitHub Actions. If you are not using GitHub, other remote cache backends are available as well.</p> <pre><code>- name: Build and push\n  id: build-docker-image\n  env:\n      GITHUB_SHA: ${{ steps.get-commit-hash.outputs.COMMIT_HASH }}\n  uses: docker/build-push-action@v5\n  with:\n    context: ${{ env.PROJECT_NAME }}/\n    push: true\n    tags: ${{ secrets.DOCKER_USERNAME }}/${{ env.PROJECT_NAME }}:${{ env.GITHUB_SHA }}-stg\n    cache-from: type=gha\n    cache-to: type=gha,mode=max\n</code></pre> <pre><code>importing cache manifest from gha:***\nDONE 0.1s\n\n[internal] load build context\ntransferring context: 70B done\nDONE 0.0s\n\n[2/3] COPY requirements.txt requirements.txt\nCACHED\n\n[3/3] RUN pip install -r requirements.txt\nCACHED\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#prefect-github-actions","title":"Prefect GitHub Actions","text":"<p>Prefect provides its own GitHub Actions for authentication and deployment creation. These actions can simplify deploying with CI/CD when using <code>prefect.yaml</code>, especially in cases where a repository contains flows that are used in multiple deployments across multiple Prefect Cloud workspaces.</p> <p>Here's an example of integrating these actions into the workflow we created above:</p> <pre><code>name: Deploy Prefect flow\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Log in to Docker Hub\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKER_USERNAME }}\n          password: ${{ secrets.DOCKER_PASSWORD }}\n\n      - name: Setup Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: \"3.11\"\n\n      - name: Prefect Auth\n        uses: PrefectHQ/actions-prefect-auth@v1\n        with:\n          prefect-api-key: ${{ secrets.PREFECT_API_KEY }}\n          prefect-workspace: ${{ secrets.PREFECT_WORKSPACE }}\n\n      - name: Run Prefect Deploy\n        uses: PrefectHQ/actions-prefect-deploy@v3\n        with:\n          deployment-names: my-deployment\n          requirements-file-paths: requirements.txt\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#authenticating-to-other-docker-image-registries","title":"Authenticating to other Docker image registries","text":"<p>The <code>docker/login-action</code> GitHub Action supports pushing images to a wide variety of image registries.</p> <p>For example, if you are storing Docker images in AWS Elastic Container Registry, you can add your ECR registry URL to the <code>registry</code> key in the <code>with:</code> part of the action and use an <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code> as your <code>username</code> and <code>password</code>.</p> <pre><code>- name: Login to ECR\n  uses: docker/login-action@v3\n  with:\n    registry: &lt;aws-account-number&gt;.dkr.ecr.&lt;region&gt;.amazonaws.com\n    username: ${{ secrets.AWS_ACCESS_KEY_ID }}\n    password: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n</code></pre>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/ci-cd/#other-resources","title":"Other resources","text":"<p>Check out the Prefect Cloud Terraform provider if you're using Terraform to manage your infrastructure.</p>","tags":["CI/CD","continuous integration","continuous delivery"],"boost":2},{"location":"guides/cli-shell/","title":"Orchestrating Shell Commands with Prefect","text":"<p>Harness the power of the Prefect CLI to execute and schedule shell commands as Prefect flows. This guide shows how to use the <code>watch</code> and <code>serve</code> commands to showcase the CLI's versatility for automation tasks.</p> <p>Here's what you'll learn:</p> <ul> <li>Running a shell command as a Prefect flow on-demand with <code>watch</code>.</li> <li>Scheduling a shell command as a recurring Prefect flow using <code>serve</code>.</li> <li>The benefits of embedding these commands into your automation workflows.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#prerequisites","title":"Prerequisites","text":"<p>Before you begin, ensure you have:</p> <ul> <li>A basic understanding of Prefect flows. Start with the Getting Started guide if you're new.</li> <li>A recent version of Prefect installed in your command line environment. Follow the instructions in the docs if you have any issues.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#the-watch-command","title":"The <code>watch</code> command","text":"<p>The <code>watch</code> command wraps any shell command in a Prefect flow for instant execution, ideal for quick tasks or integrating shell scripts into your workflows.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#example-usage","title":"Example usage","text":"<p>Imagine you want to fetch the current weather in Chicago using the <code>curl</code> command. The following Prefect CLI command does just that:</p> <pre><code>prefect shell watch \"curl http://wttr.in/Chicago?format=3\"\n</code></pre> <p>This command makes a request to <code>wttr.in</code>, a console-oriented weather service, and prints the weather conditions for Chicago.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#benefits-of-watch","title":"Benefits of <code>watch</code>","text":"<ul> <li>Immediate feedback: Execute shell commands  within the Prefect framework for immediate results.</li> <li>Easy integration: Seamlessly blend external scripts or data fetching into your data workflows.</li> <li>Visibility and logging: Leverage Prefect's logging to track the execution and output of your shell tasks.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#deploying-with-serve","title":"Deploying with <code>serve</code>","text":"<p>When you need to run shell commands on a schedule, the <code>serve</code> command creates a Prefect [deployment](/concepts/deployments/ for regular execution. This is an extremely quick way to create a deployment that is served by Prefect.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#example-usage_1","title":"Example usage","text":"<p>To set up a daily weather report for Chicago at 9 AM, you can use the <code>serve</code> command as follows:</p> <pre><code>prefect shell serve \"curl http://wttr.in/Chicago?format=3\" --flow-name \"Daily Chicago Weather Report\" --cron-schedule \"0 9 * * *\" --deployment-name \"Chicago Weather\"\n</code></pre> <p>This command schedules a Prefect flow to fetch Chicago's weather conditions daily, providing consistent updates without manual intervention. Additionally, if you want to fetch the Chicago weather, you can manually create a run of your new deployment from the UI or the CLI.</p> <p>To shut down your server and pause your scheduled runs, hit <code>ctrl</code> + <code>c</code> in the CLI.</p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#benefits-of-serve","title":"Benefits of <code>serve</code>","text":"<ul> <li>Automated scheduling: Schedule shell commands to run automatically, ensuring critical updates are generated and available on time.</li> <li>Centralized workflow management: Manage and monitor your scheduled shell commands inside Prefect for a unified workflow overview.</li> <li>Configurable execution: Tailor execution frequency, concurrency limits, and other parameters to suit your project's needs and resources.</li> </ul>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/cli-shell/#next-steps","title":"Next steps","text":"<p>With the <code>watch</code> and <code>serve</code> commands at your disposal, you're ready to incorporate shell command automation into your Prefect workflows. You can start with straightforward tasks like observing cron jobs and expand to more complex automation scenarios to enhance your workflows' efficiency and capabilities.</p> <p>Check out the tutorial and explore other Prefect docs to learn how to gain more observability and orchestration capabilities in your workflows. </p>","tags":["CLI","Shell Commands","Prefect Flows","Automation","Scheduling"],"boost":2},{"location":"guides/creating-interactive-workflows/","title":"Creating Interactive Workflows","text":"<p>Flows can pause or suspend execution and automatically resume when they receive type-checked input in Prefect's UI. Flows can also send and receive type-checked input at any time while running, without pausing or suspending. This guide will show you how to use these features to build interactive workflows.</p> <p>A note on async Python syntax</p> <p>Most of the example code in this section uses async Python functions and <code>await</code>. However, as with other Prefect features, you can call these functions with or without <code>await</code>.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#pausing-or-suspending-a-flow-until-it-receives-input","title":"Pausing or suspending a flow until it receives input","text":"<p>You can pause or suspend a flow until it receives input from a user in Prefect's UI. This is useful when you need to ask for additional information or feedback before resuming a flow. Such workflows are often called human-in-the-loop (HITL) systems.</p> <p>What is human-in-the-loop interactivity used for?</p> <p>Approval workflows that pause to ask a human to confirm whether a workflow should continue are very common in the business world. Certain types of machine learning training and artificial intelligence workflows benefit from incorporating HITL design.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#waiting-for-input","title":"Waiting for input","text":"<p>To receive input while paused or suspended use the <code>wait_for_input</code> parameter in the <code>pause_flow_run</code> or <code>suspend_flow_run</code> functions. This parameter accepts one of the following:</p> <ul> <li>A built-in type like <code>int</code> or <code>str</code>, or a built-in collection like <code>List[int]</code></li> <li>A <code>pydantic.BaseModel</code> subclass</li> <li>A subclass of <code>prefect.input.RunInput</code></li> </ul> <p>When to use a <code>RunModel</code> or <code>BaseModel</code> instead of a built-in type</p> <p>There are a few reasons to use a <code>RunModel</code> or <code>BaseModel</code>. The first is that when you let Prefect automatically create one of these classes for your input type, the field that users will see in Prefect's UI when they click \"Resume\" on a flow run is named <code>value</code> and has no help text to suggest what the field is. If you create a <code>RunInput</code> or <code>BaseModel</code>, you can change details like the field name, help text, and default value, and users will see those reflected in the \"Resume\" form.</p> <p>The simplest way to pause or suspend and wait for input is to pass a built-in type:</p> <pre><code>from prefect import flow, pause_flow_run, get_run_logger\n\n@flow\ndef greet_user():\n    logger = get_run_logger()\n\n    user = pause_flow_run(wait_for_input=str)\n\n    logger.info(f\"Hello, {user}!\")\n</code></pre> <p>In this example, the flow run will pause until a user clicks the Resume button in the Prefect UI, enters a name, and submits the form.</p> <p>What types can you pass for <code>wait_for_input</code>?</p> <p>When you pass a built-in type such as <code>int</code> as an argument for the <code>wait_for_input</code> parameter to <code>pause_flow_run</code> or <code>suspend_flow_run</code>, Prefect automatically creates a Pydantic model containing one field annotated with the type you specified. This means you can use any type annotation that Pydantic accepts for model fields with these functions.</p> <p>Instead of a built-in type, you can pass in a <code>pydantic.BaseModel</code> class. This is useful if you already have a <code>BaseModel</code> you want to use:</p> <pre><code>from prefect import flow, pause_flow_run, get_run_logger\nfrom pydantic import BaseModel\n\n\nclass User(BaseModel):\n    name: str\n    age: int\n\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user = await pause_flow_run(wait_for_input=User)\n\n    logger.info(f\"Hello, {user.name}!\")\n</code></pre> <p><code>BaseModel</code> classes are upgraded to <code>RunInput</code> classes automatically</p> <p>When you pass a <code>pydantic.BaseModel</code> class as the <code>wait_for_input</code> argument to <code>pause_flow_run</code> or <code>suspend_flow_run</code>, Prefect automatically creates a <code>RunInput</code> class with the same behavior as your <code>BaseModel</code> and uses that instead.</p> <p><code>RunInput</code> classes contain extra logic that allows flows to send and receive them at runtime. You shouldn't notice any difference!</p> <p>Finally, for advanced use cases like overriding how Prefect stores flow run inputs, you can create a <code>RunInput</code> class:</p> <pre><code>from prefect import get_run_logger\nfrom prefect.input import RunInput\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n    # Imagine overridden methods here!\n    def override_something(self, *args, **kwargs):\n        super().override_something(*args, **kwargs)\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user = await pause_flow_run(wait_for_input=UserInput)\n\n    logger.info(f\"Hello, {user.name}!\")\n</code></pre>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#providing-initial-data","title":"Providing initial data","text":"<p>You can set default values for fields in your model by using the <code>with_initial_data</code> method. This is useful when you want to provide default values for the fields in your own <code>RunInput</code> class.</p> <p>Expanding on the example above, you could make the <code>name</code> field default to \"anonymous\":</p> <pre><code>from prefect import get_run_logger\nfrom prefect.input import RunInput\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n\n    user_input = await pause_flow_run(\n        wait_for_input=UserInput.with_initial_data(name=\"anonymous\")\n    )\n\n    if user_input.name == \"anonymous\":\n        logger.info(\"Hello, stranger!\")\n    else:\n        logger.info(f\"Hello, {user_input.name}!\")\n</code></pre> <p>When a user sees the form for this input, the name field will contain \"anonymous\" as the default.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#providing-a-description-with-runtime-data","title":"Providing a description with runtime data","text":"<p>You can provide a dynamic, markdown description that will appear in the Prefect UI when the flow run pauses. This feature enables context-specific prompts, enhancing clarity and user interaction. Building on the example above:</p> <pre><code>from datetime import datetime\nfrom prefect import flow, pause_flow_run, get_run_logger\nfrom prefect.input import RunInput\n\n\nclass UserInput(RunInput):\n    name: str\n    age: int\n\n\n@flow\nasync def greet_user():\n    logger = get_run_logger()\n    current_date = datetime.now().strftime(\"%B %d, %Y\")\n\n    description_md = f\"\"\"\n**Welcome to the User Greeting Flow!**\nToday's Date: {current_date}\n\nPlease enter your details below:\n- **Name**: What should we call you?\n- **Age**: Just a number, nothing more.\n\"\"\"\n\n    user_input = await pause_flow_run(\n        wait_for_input=UserInput.with_initial_data(\n            description=description_md, name=\"anonymous\"\n        )\n    )\n\n    if user_input.name == \"anonymous\":\n        logger.info(\"Hello, stranger!\")\n    else:\n        logger.info(f\"Hello, {user_input.name}!\")\n</code></pre> <p>When a user sees the form for this input, the given markdown will appear above the input fields.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#handling-custom-validation","title":"Handling custom validation","text":"<p>Prefect uses the fields and type hints on your <code>RunInput</code> or <code>BaseModel</code> class to validate the general structure of input your flow receives, but you might require more complex validation. If you do, you can use Pydantic validators.</p> <p>Custom validation runs after the flow resumes</p> <p>Prefect transforms the type annotations in your <code>RunInput</code> or <code>BaseModel</code> class to a JSON schema and uses that schema in the UI for client-side validation. However, custom validation requires running Python logic defined in your <code>RunInput</code> class. Because of this, validation happens after the flow resumes, so you'll want to handle it explicitly in your flow. Continue reading for an example best practice.</p> <p>The following is an example <code>RunInput</code> class that uses a custom field validator:</p> <pre><code>import pydantic\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n</code></pre> <p>In the example, we use Pydantic's <code>validator</code> decorator to define a custom validation method for the <code>color</code> field. We can use it in a flow like this:</p> <pre><code>import pydantic\nfrom prefect import flow, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n\n\n@flow\ndef get_shirt_order():\n    shirt_order = pause_flow_run(wait_for_input=ShirtOrder)\n</code></pre> <p>If a user chooses any size and color combination other than <code>small</code> and <code>green</code>, the flow run will resume successfully. However, if the user chooses size <code>small</code> and color <code>green</code>, the flow run will resume, and <code>pause_flow_run</code> will raise a <code>ValidationError</code> exception. This will cause the flow run to fail and log the error.</p> <p>However, what if you don't want the flow run to fail? One way to handle this case is to use a <code>while</code> loop and pause again if the <code>ValidationError</code> exception is raised:</p> <pre><code>from typing import Literal\n\nimport pydantic\nfrom prefect import flow, get_run_logger, pause_flow_run\nfrom prefect.input import RunInput\n\n\nclass ShirtOrder(RunInput):\n    size: Literal[\"small\", \"medium\", \"large\", \"xlarge\"]\n    color: Literal[\"red\", \"green\", \"black\"]\n\n    @pydantic.validator(\"color\")\n    def validate_age(cls, value, values, **kwargs):\n        if value == \"green\" and values[\"size\"] == \"small\":\n            raise ValueError(\n                \"Green is only in-stock for medium, large, and XL sizes.\"\n            )\n\n        return value\n\n\n@flow\ndef get_shirt_order():\n    logger = get_run_logger()\n    shirt_order = None\n\n    while shirt_order is None:\n        try:\n            shirt_order = pause_flow_run(wait_for_input=ShirtOrder)\n        except pydantic.ValidationError as exc:\n            logger.error(f\"Invalid size and color combination: {exc}\")\n\n    logger.info(\n        f\"Shirt order: {shirt_order.size}, {shirt_order.color}\"\n    )\n</code></pre> <p>This code will cause the flow run to continually pause until the user enters a valid age.</p> <p>As an additional step, you may want to use an automation or notification to alert the user to the error.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#sending-and-receiving-input-at-runtime","title":"Sending and receiving input at runtime","text":"<p>Use the <code>send_input</code> and <code>receive_input</code> functions to send input to a flow or receive input from a flow at runtime. You don't need to pause or suspend the flow to send or receive input.</p> <p>Why would you send or receive input without pausing or suspending?</p> <p>You might want to send or receive input without pausing or suspending in scenarios where the flow run is designed to handle real-time data. For instance, in a live monitoring system, you might need to update certain parameters based on the incoming data without interrupting the flow. Another use is having a long-running flow that continually responds to runtime input with low latency. For example, if you're building a chatbot, you could have a flow that starts a GPT Assistant and manages a conversation thread.</p> <p>The most important parameter to the <code>send_input</code> and <code>receive_input</code> functions is <code>run_type</code>, which should be one of the following:</p> <ul> <li>A built-in type such as <code>int</code> or <code>str</code></li> <li>A <code>pydantic.BaseModel</code> class</li> <li>A <code>prefect.input.RunInput</code> class</li> </ul> <p>When to use a <code>BaseModel</code> or <code>RunInput</code> instead of a built-in type</p> <p>Most built-in types and collections of built-in types should work with <code>send_input</code> and <code>receive_input</code>, but there is a caveat with nested collection types, such as lists of tuples, e.g. <code>List[Tuple[str, float]])</code>. In this case, validation may happen after your flow receives the data, so calling <code>receive_input</code> may raise a <code>ValidationError</code>. You can plan to catch this exception, but also, consider placing the field in an explicit <code>BaseModel</code> or <code>RunInput</code> so that your flow only receives exact type matches.</p> <p>Let's look at some examples! We'll check out <code>receive_input</code> first, followed by <code>send_input</code>, and then we'll see the two functions working together.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#receiving-input","title":"Receiving input","text":"<p>The following flow uses <code>receive_input</code> to continually receive names and print a personalized greeting for each name it receives:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(str, timeout=None):\n        # Prints \"Hello, andrew!\" if another flow sent \"andrew\"\n        print(f\"Hello, {name_input}!\")\n</code></pre> <p>When you pass a type such as <code>str</code> into <code>receive_input</code>, Prefect creates a <code>RunInput</code> class to manage your input automatically. When a flow sends input of this type, Prefect uses the <code>RunInput</code> class to validate the input. If the validation succeeds, your flow receives the input in the type you specified. In this example, if the flow received a valid string as input, the variable <code>name_input</code> would contain the string value.</p> <p>If, instead, you pass a <code>BaseModel</code>, Prefect upgrades your <code>BaseModel</code> to a <code>RunInput</code> class, and the variable your flow sees \u2014 in this case, <code>name_input</code> \u2014 is a <code>RunInput</code> instance that behaves like a <code>BaseModel</code>. Of course, if you pass in a <code>RunInput</code> class, no upgrade is needed, and you'll get a <code>RunInput</code> instance.</p> <p>If you prefer to keep things simple and pass types such as <code>str</code> into <code>receive_input</code>, you can do so. If you need access to the generated <code>RunInput</code> that contains the received value, pass <code>with_metadata=True</code> to <code>receive_input</code>:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(\n        str,\n        timeout=None,\n        with_metadata=True\n    ):\n        # Input will always be in the field \"value\" on this object.\n        print(f\"Hello, {name_input.value}!\")\n</code></pre> <p>Why would you need to use <code>with_metadata=True</code>?</p> <p>The primary uses of accessing the <code>RunInput</code> object for a receive input are to respond to the sender with the <code>RunInput.respond()</code> function or to access the unique key for an input. Later in this guide, we'll discuss how and why you might use these features.</p> <p>Notice that we are now printing <code>name_input.value</code>. When Prefect generates a <code>RunInput</code> for you from a built-in type, the <code>RunInput</code> class has a single field, <code>value</code>, that uses a type annotation matching the type you specified. So if you call <code>receive_input</code> like this: <code>receive_input(str, with_metadata=True)</code>, that's equivalent to manually creating the following <code>RunInput</code> class and <code>receive_input</code> call:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import RunInput\n\nclass GreeterInput(RunInput):\n    value: str\n\n@flow\nasync def greeter_flow():\n    async for name_input in receive_input(GreeterInput, timeout=None):\n        print(f\"Hello, {name_input.value}!\")\n</code></pre> <p>The type used in <code>receive_input</code> and <code>send_input</code> must match</p> <p>For a flow to receive input, the sender must use the same type that the receiver is receiving. This means that if the receiver is receiving <code>GreeterInput</code>, the sender must send <code>GreeterInput</code>. If the receiver is receiving <code>GreeterInput</code> and the sender sends <code>str</code> input that Prefect automatically upgrades to a <code>RunInput</code> class, the types won't match, so the receiving flow run won't receive the input. However, the input will be waiting if the flow ever calls <code>receive_input(str)</code>!</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#keeping-track-of-inputs-youve-already-seen","title":"Keeping track of inputs you've already seen","text":"<p>By default, each time you call <code>receive_input</code>, you get an iterator that iterates over all known inputs to a specific flow run, starting with the first received. The iterator will keep track of your current position as you iterate over it, or you can call <code>next()</code> to explicitly get the next input. If you're using the iterator in a loop, you should probably assign it to a variable:</p> <pre><code>from prefect import flow, get_client\nfrom prefect.deployments.deployments import run_deployment\nfrom prefect.input.run_input import receive_input, send_input\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    client = get_client()\n\n    # Assigning the `receive_input` iterator to a variable\n    # outside of the the `while True` loop allows us to continue\n    # iterating over inputs in subsequent passes through the\n    # while loop without losing our position.\n    receiver = receive_input(\n        str,\n        with_metadata=True,\n        timeout=None,\n        poll_interval=0.1\n    )\n\n    while True:\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n\n        # Saving the iterator outside of the while loop and\n        # calling next() on each iteration of the loop ensures\n        # that we're always getting the newest greeting. If we\n        # had instead called `receive_input` here, we would\n        # always get the _first_ greeting this flow received,\n        # print it, and then ask for a new name.\n        greeting = await receiver.next()\n        print(greeting)\n</code></pre> <p>So, an iterator helps to keep track of the inputs your flow has already received. But what if you want your flow to suspend and then resume later, picking up where it left off? In that case, you will need to save the keys of the inputs you've seen so that the flow can read them back out when it resumes. You might use a Block, such as a <code>JSONBlock</code>.</p> <p>The following flow receives input for 30 seconds then suspends itself, which exits the flow and tears down infrastructure:</p> <pre><code>from prefect import flow, get_run_logger, suspend_flow_run\nfrom prefect.blocks.system import JSON\nfrom prefect.context import get_run_context\nfrom prefect.input.run_input import receive_input\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    logger = get_run_logger()\n    run_context = get_run_context()\n    assert run_context.flow_run, \"Could not see my flow run ID\"\n\n    block_name = f\"{run_context.flow_run.id}-seen-ids\"\n\n    try:\n        seen_keys_block = await JSON.load(block_name)\n    except ValueError:\n        seen_keys_block = JSON(\n            value=[],\n        )\n\n    try:\n        async for name_input in receive_input(\n            str,\n            with_metadata=True,\n            poll_interval=0.1,\n            timeout=30,\n            exclude_keys=seen_keys_block.value\n        ):\n            if name_input.value == EXIT_SIGNAL:\n                print(\"Goodbye!\")\n                return\n            await name_input.respond(f\"Hello, {name_input.value}!\")\n\n            seen_keys_block.value.append(name_input.metadata.key)\n            await seen_keys_block.save(\n                name=block_name,\n                overwrite=True\n            )\n    except TimeoutError:\n        logger.info(\"Suspending greeter after 30 seconds of idle time\")\n        await suspend_flow_run(timeout=10000)\n</code></pre> <p>As this flow processes name input, it adds the key of the flow run input to the <code>seen_keys_block</code>. When the flow later suspends and then resumes, it reads the keys it has already seen out of the JSON Block and passes them as the <code>exlude_keys</code> parameter to <code>receive_input</code>.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#responding-to-the-inputs-sender","title":"Responding to the input's sender","text":"<p>When your flow receives input from another flow, Prefect knows the sending flow run ID, so the receiving flow can respond by calling the <code>respond</code> method on the <code>RunInput</code> instance the flow received. There are a couple of requirements:</p> <ol> <li>You will need to pass in a <code>BaseModel</code> or <code>RunInput</code>, or use <code>with_metadata=True</code></li> <li>The flow you are responding to must receive the same type of input you send in order to see it.</li> </ol> <p>The <code>respond</code> method is equivalent to calling <code>send_input(..., flow_run_id=sending_flow_run.id)</code>, but with <code>respond</code>, your flow doesn't need to know the sending flow run's ID.</p> <p>Now that we know about <code>respond</code>, let's make our <code>greeter_flow</code> respond to name inputs instead of printing them:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n@flow\nasync def greeter():\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        timeout=None\n    ):\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n</code></pre> <p>Cool! There's one problem left: this flow runs forever! We need a way to signal that it should exit. Let's keep things simple and teach it to look for a special string:</p> <pre><code>from prefect import flow\nfrom prefect.input.run_input import receive_input\n\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        poll_interval=0.1,\n        timeout=None\n    ):\n        if name_input.value == EXIT_SIGNAL:\n            print(\"Goodbye!\")\n            return\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n</code></pre> <p>With a <code>greeter</code> flow in place, we're ready to create the flow that sends <code>greeter</code> names!</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#sending-input","title":"Sending input","text":"<p>You can send input to a flow with the <code>send_input</code> function. This works similarly to <code>receive_input</code> and, like that function, accepts the same <code>run_input</code> argument, which can be a built-in type such as <code>str</code>, or else a <code>BaseModel</code> or <code>RunInput</code> subclass.</p> <p>When can you send input to a flow run?</p> <p>You can send input to a flow run as soon as you have the flow run's ID. The flow does not have to be receiving input for you to send input. If you send a flow input before it is receiving, it will see your input when it calls <code>receive_input</code> (as long as the types in the <code>send_input</code> and <code>receive_input</code> calls match!)</p> <p>Next, we'll create a <code>sender</code> flow that starts a <code>greeter</code> flow run and then enters a loop, continuously getting input from the terminal and sending it to the greeter flow:</p> <pre><code>@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    receiver = receive_input(str, timeout=None, poll_interval=0.1)\n    client = get_client()\n\n    while True:\n        flow_run = await client.read_flow_run(greeter_flow_run.id)\n\n        if not flow_run.state or not flow_run.state.is_running():\n            continue\n\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n        greeting = await receiver.next()\n        print(greeting)\n</code></pre> <p>There's more going on here than in <code>greeter</code>, so let's take a closer look at the pieces.</p> <p>First, we use <code>run_deployment</code> to start a <code>greeter</code> flow run. This means we must have a worker or <code>flow.serve()</code> running in separate process. That process will begin running <code>greeter</code> while <code>sender</code> continues to execute. Calling <code>run_deployment(..., timeout=0)</code> ensures that <code>sender</code> won't wait for the <code>greeter</code> flow run to complete, because it's running a loop and will only exit when we send <code>EXIT_SIGNAL</code>.</p> <p>Next, we capture the iterator returned by <code>receive_input</code> as <code>receiver</code>. This flow works by entering a loop, and on each iteration of the loop, the flow asks for terminal input, sends that to the <code>greeter</code> flow, and then runs <code>receiver.next()</code> to wait until it receives the response from <code>greeter</code>.</p> <p>Next, we let the terminal user who ran this flow exit by entering the string <code>q</code> or <code>quit</code>. When that happens, we send the <code>greeter</code> flow an exit signal so it will shut down too.</p> <p>Finally, we send the new name to <code>greeter</code>. We know that <code>greeter</code> is going to send back a greeting as a string, so we immediately wait for new string input. When we receive the greeting, we print it and continue the loop that gets terminal input.</p>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/creating-interactive-workflows/#seeing-a-complete-example","title":"Seeing a complete example","text":"<p>Finally, let's see a complete example of using <code>send_input</code> and <code>receive_input</code>. Here is what the <code>greeter</code> and <code>sender</code> flows look like together:</p> <pre><code>import asyncio\nimport sys\nfrom prefect import flow, get_client\nfrom prefect.blocks.system import JSON\nfrom prefect.context import get_run_context\nfrom prefect.deployments.deployments import run_deployment\nfrom prefect.input.run_input import receive_input, send_input\n\n\nEXIT_SIGNAL = \"__EXIT__\"\n\n\n@flow\nasync def greeter():\n    run_context = get_run_context()\n    assert run_context.flow_run, \"Could not see my flow run ID\"\n\n    block_name = f\"{run_context.flow_run.id}-seen-ids\"\n\n    try:\n        seen_keys_block = await JSON.load(block_name)\n    except ValueError:\n        seen_keys_block = JSON(\n            value=[],\n        )\n\n    async for name_input in receive_input(\n        str,\n        with_metadata=True,\n        poll_interval=0.1,\n        timeout=None\n    ):\n        if name_input.value == EXIT_SIGNAL:\n            print(\"Goodbye!\")\n            return\n        await name_input.respond(f\"Hello, {name_input.value}!\")\n\n        seen_keys_block.value.append(name_input.metadata.key)\n        await seen_keys_block.save(\n            name=block_name,\n            overwrite=True\n        )\n\n\n@flow\nasync def sender():\n    greeter_flow_run = await run_deployment(\n        \"greeter/send-receive\", timeout=0, as_subflow=False\n    )\n    receiver = receive_input(str, timeout=None, poll_interval=0.1)\n    client = get_client()\n\n    while True:\n        flow_run = await client.read_flow_run(greeter_flow_run.id)\n\n        if not flow_run.state or not flow_run.state.is_running():\n            continue\n\n        name = input(\"What is your name? \")\n        if not name:\n            continue\n\n        if name == \"q\" or name == \"quit\":\n            await send_input(\n                EXIT_SIGNAL,\n                flow_run_id=greeter_flow_run.id\n            )\n            print(\"Goodbye!\")\n            break\n\n        await send_input(name, flow_run_id=greeter_flow_run.id)\n        greeting = await receiver.next()\n        print(greeting)\n\n\nif __name__ == \"__main__\":\n    if sys.argv[1] == \"greeter\":\n        asyncio.run(greeter.serve(name=\"send-receive\"))\n    elif sys.argv[1] == \"sender\":\n        asyncio.run(sender())\n</code></pre> <p>To run the example, you'll need a Python environment with Prefect installed, pointed at either an open-source Prefect server instance or Prefect Cloud.</p> <p>With your environment set up, start a flow runner in one terminal with the following command:</p> <pre><code>python my_file_name greeter\n</code></pre> <p>For example, with Prefect Cloud, you should see output like this:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Your flow 'greeter' is being served and polling for scheduled runs!                              \u2502\n\u2502                                                                                                  \u2502\n\u2502 To trigger a run for this flow, use the following command:                                       \u2502\n\u2502                                                                                                  \u2502\n\u2502         $ prefect deployment run 'greeter/send-receive'                                          \u2502\n\u2502                                                                                                  \u2502\n\u2502 You can also run your flow via the Prefect UI:                                                   \u2502\n\u2502 https://app.prefect.cloud/account/...(a URL for your account)                                    \u2502\n\u2502                                                                                                  \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>Then start the greeter process in another terminal:</p> <pre><code>python my_file_name sender\n</code></pre> <p>You should see output like this:</p> <pre><code>11:38:41.800 | INFO    | prefect.engine - Created flow run 'gregarious-owl' for flow 'sender'\n11:38:41.802 | INFO    | Flow run 'gregarious-owl' - View at https://app.prefect.cloud/account/...\nWhat is your name?\n</code></pre> <p>Type a name and press the enter key to see a greeting, and you'll see sending and receiving in action:</p> <pre><code>What is your name? andrew\nHello, andrew!\n</code></pre>","tags":["flow run","pause","suspend","input","human-in-the-loop workflows","interactive workflows"],"boost":2},{"location":"guides/dask-ray-task-runners/","title":"Dask and Ray Task Runners","text":"<p>Task runners provide an execution environment for tasks. In a flow decorator, you can specify a task runner to run the tasks called in that flow.</p> <p>The default task runner is the <code>ConcurrentTaskRunner</code>.</p> <p>Use <code>.submit</code> to run your tasks asynchronously</p> <p>To run tasks asynchronously use the <code>.submit</code> method when you call them. If you call a task as you would normally in Python code it will run synchronously, even if you are calling the task within a flow that uses the <code>ConcurrentTaskRunner</code>, <code>DaskTaskRunner</code>, or <code>RayTaskRunner</code>.</p> <p>Many real-world data workflows benefit from true parallel, distributed task execution. For these use cases, the following Prefect-developed task runners for parallel task execution may be installed as Prefect Integrations.</p> <ul> <li><code>DaskTaskRunner</code> runs tasks requiring parallel execution using <code>dask.distributed</code>.</li> <li><code>RayTaskRunner</code> runs tasks requiring parallel execution using Ray.</li> </ul> <p>These task runners can spin up a local Dask cluster or Ray instance on the fly, or let you connect with a Dask or Ray environment you've set up separately. Then you can take advantage of massively parallel computing environments.</p> <p>Use Dask or Ray in your flows to choose the execution environment that fits your particular needs.</p> <p>To show you how they work, let's start small.</p> <p>Remote storage</p> <p>We recommend configuring remote file storage for task execution with <code>DaskTaskRunner</code> or <code>RayTaskRunner</code>. This ensures tasks executing in Dask or Ray have access to task result storage, particularly when accessing a Dask or Ray instance outside of your execution environment.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#configure-a-task-runner","title":"Configure a task runner","text":"<p>You may have seen this briefly in a previous tutorial, but let's look a bit more closely at how you can configure a specific task runner for a flow.</p> <p>Let's start with the <code>SequentialTaskRunner</code>. This task runner runs all tasks synchronously and may be useful when used as a debugging tool in conjunction with async code.</p> <p>Let's start with this simple flow. We import the <code>SequentialTaskRunner</code>, specify a <code>task_runner</code> on the flow, and call the tasks with <code>.submit()</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect.task_runners import SequentialTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=SequentialTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Save this code as <code>sequential_flow.py</code> and run it.</p> <pre><code>python sequential_flow.py\n</code></pre> <p>If you remove the log messages from the output and just look at the printed output from the task runs, you see they're executed sequentially:</p> <pre><code>hello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#run-tasks-in-parallel-with-dask","title":"Run tasks in parallel with Dask","text":"<p>This basic flow won't benefit from parallel execution, but let's proceed so you can see just how simple it is to use the <code>DaskTaskRunner</code> for more complex flows.</p> <p>Configure your flow to use the <code>DaskTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed by running <code>pip install -U prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> <li>Use the <code>.submit</code> method when calling task-decorated functions.</li> </ol> <p>Example code:</p> <pre><code>from prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=DaskTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Note that, because you're using <code>DaskTaskRunner</code> in a script, you must use <code>if __name__ == \"__main__\":</code> or you'll see warnings and errors.</p> <p>Run <code>dask_flow.py</code>. If you get a warning about accepting incoming network connections, that's okay - everything is local in this example.</p> <pre><code>python dask_flow.py\n</code></pre> <p><code>DaskTaskRunner</code> automatically creates a local Dask cluster, then starts executing all of the task runs in parallel. The results do not return in the same order as the sequential code above.</p> <p>Abbreviated output:</p> <pre><code>goodbye marvin\nhello arthur\ngoodbye ford\nhello trillian\n</code></pre> <p>Notice what happens if you do not use the <code>submit</code> method when calling tasks:</p> <pre><code>from prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n\n@flow(task_runner=DaskTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello(name)\n        say_goodbye(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Run the script:</p> <pre><code>python dask_flow.py\n</code></pre> <p>Once again, the tasks run sequentially. Here's the output with logs removed.</p> <pre><code>hello arthur\ngoodbye arthur\nhello trillian\ngoodbye trillian\nhello ford\ngoodbye ford\nhello marvin\ngoodbye marvin\n</code></pre> <p>The task runs are not submitted to the <code>DaskTaskRunner</code>; instead, they run sequentially.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#run-tasks-in-parallel-with-ray","title":"Run tasks in parallel with Ray","text":"<p>You can easily switch to Ray as another parallel task runner option. Use the <code>RayTaskRunner</code> instead of <code>DaskTaskRunner</code>.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Install <code>prefect-ray</code> into your environment with <code>pip install -U prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Specify the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>Ray environment limitations</p> <p>While we're excited about parallel task execution via Ray, there are a few limitations with Ray you should be aware of:</p> <ul> <li>Support for Python 3.11 is experimental.</li> <li>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</li> <li>Ray's Windows support is currently in beta.</li> </ul> <p>See the Ray installation documentation for further compatibility information.</p> <p>Save this code in <code>ray_flow.py</code>.</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n@flow(task_runner=RayTaskRunner())\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>Now run <code>ray_flow.py</code> <code>RayTaskRunner</code> automatically creates a local Ray instance, then immediately starts executing all of the tasks in parallel. If you have an existing Ray instance, you can provide the address as a parameter to run tasks in the instance. See Running tasks on Ray for details.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/dask-ray-task-runners/#using-multiple-task-runners","title":"Using multiple task runners","text":"<p>Many workflows include a variety of tasks, and not all of them benefit from parallel execution. You'll most likely want to use the Dask or Ray task runners and spin up their respective resources only for those tasks that need them.</p> <p>Because task runners are specified on flows, you can assign different task runners to tasks by using subflows to organize those tasks.</p> <p>This example uses the same tasks as the previous examples, but on the parent flow <code>greetings()</code> we use the default <code>ConcurrentTaskRunner</code>. Then we call a <code>ray_greetings()</code> subflow that uses the <code>RayTaskRunner</code> to execute the same tasks in a Ray instance.</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@task\ndef say_hello(name):\n    print(f\"hello {name}\")\n\n@task\ndef say_goodbye(name):\n    print(f\"goodbye {name}\")\n\n@flow(task_runner=RayTaskRunner())\ndef ray_greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n\n@flow()\ndef greetings(names):\n    for name in names:\n        say_hello.submit(name)\n        say_goodbye.submit(name)\n    ray_greetings(names)\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <p>If you save this as <code>ray_subflow.py</code> and run it, you'll see that the flow <code>greetings</code> runs as you'd expect for a concurrent flow, then flow <code>ray-greetings</code> spins up a Ray instance to run the tasks again.</p>","tags":["tasks","task runners","flow configuration","parallel execution","distributed execution","Dask","Ray"],"boost":2},{"location":"guides/docker/","title":"Running Flows with Docker","text":"<p>In the Deployments tutorial, we looked at serving a flow that enables scheduling or creating flow runs via the Prefect API.</p> <p>With our Python script in hand, we can build a Docker image for our script, allowing us to serve our flow in various remote environments. We'll use Kubernetes in this guide, but you can use any Docker-compatible infrastructure.</p> <p>In this guide we'll:</p> <ul> <li>Write a Dockerfile to build an image that stores our Prefect flow code.</li> <li>Build a Docker image for our flow.</li> <li>Deploy and run our Docker image on a Kubernetes cluster.</li> <li>Look at the Prefect-maintained Docker images and discuss options for use</li> </ul> <p>Note that in this guide we'll create a Dockerfile from scratch. Alternatively, Prefect makes it convenient to build a Docker image as part of deployment creation. You can even include environment variables and specify additional Python packages to install at runtime.</p> <p>If creating a deployment with a <code>prefect.yaml</code> file, the build step makes it easy to customize your Docker image and push it to the registry of your choice. See an example here.</p> <p>Deployment creation with a Python script that includes <code>flow.deploy</code> similarly allows you to customize your Docker image with keyword arguments as shown below.</p> <pre><code>...\n\nif __name__ == \"__main__\":\n    hello_world.deploy(\n        name=\"my-first-deployment\",\n        work_pool_name=\"above-ground\",\n        image='my_registry/hello_world:demo',\n        job_variables={\"env\": { \"EXTRA_PIP_PACKAGES\": \"boto3\" } }\n    )\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#prerequisites","title":"Prerequisites","text":"<p>To complete this guide, you'll need the following:</p> <ul> <li>A Python script that defines and serves a flow.</li> <li>We'll use the flow script and deployment from the Deployments tutorial.</li> <li>Access to a running Prefect API server.</li> <li>You can sign up for a forever free Prefect Cloud account or run a Prefect API server locally with <code>prefect server start</code>.</li> <li>Docker Desktop installed on your machine.</li> </ul>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#writing-a-dockerfile","title":"Writing a Dockerfile","text":"<p>First let's make a clean directory to work from, <code>prefect-docker-guide</code>.</p> <pre><code>mkdir prefect-docker-guide\ncd prefect-docker-guide\n</code></pre> <p>In this directory, we'll create a sub-directory named <code>flows</code> and put our flow script from the Deployments tutorial in it.</p> <pre><code>mkdir flows\ncd flows\ntouch prefect-docker-guide-flow.py\n</code></pre> <p>Here's the flow code for reference:</p> prefect-docker-guide-flow.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.serve(name=\"prefect-docker-guide\")\n</code></pre> <p>The next file we'll add to the <code>prefect-docker-guide</code> directory is a <code>requirements.txt</code>. We'll include all dependencies required for our <code>prefect-docker-guide-flow.py</code> script in the Docker image we'll build.</p> <pre><code># ensure you run this line from the top level of the `prefect-docker-guide` directory\ntouch requirements.txt\n</code></pre> <p>Here's what we'll put in our <code>requirements.txt</code> file:</p> requirements.txt<pre><code>prefect&gt;=2.12.0\nhttpx\n</code></pre> <p>Next, we'll create a <code>Dockerfile</code> that we'll use to create a Docker image that will also store the flow code.</p> <pre><code>touch Dockerfile\n</code></pre> <p>We'll add the following content to our <code>Dockerfile</code>:</p> Dockerfile<pre><code># We're using the latest version of Prefect with Python 3.10\nFROM prefecthq/prefect:2-python3.10\n\n# Add our requirements.txt file to the image and install dependencies\nCOPY requirements.txt .\nRUN pip install -r requirements.txt --trusted-host pypi.python.org --no-cache-dir\n\n# Add our flow code to the image\nCOPY flows /opt/prefect/flows\n\n# Run our flow script when the container starts\nCMD [\"python\", \"flows/prefect-docker-guide-flow.py\"]\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#building-a-docker-image","title":"Building a Docker image","text":"<p>Now that we have a Dockerfile we can build our image by running:</p> <pre><code>docker build -t prefect-docker-guide-image .\n</code></pre> <p>We can check that our build worked by running a container from our new image.</p> CloudSelf-hosted <p>Our container will need an API URL and and API key to communicate with Prefect Cloud. </p> <ul> <li> <p>You can get an API key from the API Keys section of the user settings in the Prefect UI. </p> </li> <li> <p>You can get your API URL by running <code>prefect config view</code> and copying the <code>PREFECT_API_URL</code> value.</p> </li> </ul> <p>We'll provide both these values to our container by passing them as environment variables with the <code>-e</code> flag.</p> <pre><code>docker run -e PREFECT_API_URL=YOUR_PREFECT_API_URL -e PREFECT_API_KEY=YOUR_API_KEY prefect-docker-guide-image\n</code></pre> <p>After running the above command, the container should start up and serve the flow within the container!</p> <p>Our container will need an API URL and network access to communicate with the Prefect API. </p> <p>For this guide, we'll assume the Prefect API is running on the same machine that we'll run our container on and the Prefect API was started with <code>prefect server start</code>. If you're running a different setup, check out the Hosting a Prefect server guide for information on how to connect to your Prefect API instance.</p> <p>To ensure that our flow container can communicate with the Prefect API, we'll set our <code>PREFECT_API_URL</code> to <code>http://host.docker.internal:4200/api</code>. If you're running Linux, you'll need to set your <code>PREFECT_API_URL</code> to <code>http://localhost:4200/api</code> and use the <code>--network=\"host\"</code> option instead.</p> <pre><code>docker run --network=\"host\" -e PREFECT_API_URL=http://host.docker.internal:4200/api prefect-docker-guide-image\n</code></pre> <p>After running the above command, the container should start up and serve the flow within the container!</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#deploying-to-a-remote-environment","title":"Deploying to a remote environment","text":"<p>Now that we have a Docker image with our flow code embedded, we can deploy it to a remote environment!</p> <p>For this guide, we'll simulate a remote environment by using Kubernetes locally with Docker Desktop. You can use the instructions provided by Docker to set up Kubernetes locally.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#creating-a-kubernetes-deployment-manifest","title":"Creating a Kubernetes deployment manifest","text":"<p>To ensure the process serving our flow is always running, we'll create a Kubernetes deployment. If our flow's container ever crashes, Kubernetes will automatically restart it, ensuring that we won't miss any scheduled runs.</p> <p>First, we'll create a <code>deployment-manifest.yaml</code> file in our <code>prefect-docker-guide</code> directory:</p> <pre><code>touch deployment-manifest.yaml\n</code></pre> <p>And we'll add the following content to our <code>deployment-manifest.yaml</code> file:</p> CloudSelf-hosted deployment-manifest.yaml<pre><code>apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: prefect-docker-guide\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      flow: get-repo-info\n  template:\n    metadata:\n      labels:\n        flow: get-repo-info\n    spec:\n      containers:\n      - name: flow-container\n        image: prefect-docker-guide-image:latest\n        env:\n        - name: PREFECT_API_URL\n          value: YOUR_PREFECT_API_URL\n        - name: PREFECT_API_KEY\n          value: YOUR_API_KEY\n        # Never pull the image because we're using a local image\n        imagePullPolicy: Never\n</code></pre> <p>Keep your API key secret</p> <p>In the above manifest we are passing in the Prefect API URL and API key as environment variables. This approach is simple, but it is not secure. If you are deploying your flow to a remote cluster, you should use a Kubernetes secret to store your API key.</p> deployment-manifest.yaml<pre><code>apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: prefect-docker-guide\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      flow: get-repo-info\n  template:\n    metadata:\n      labels:\n        flow: get-repo-info\n    spec:\n      containers:\n      - name: flow-container\n        image: prefect-docker-guide-image:latest\n        env:\n        - name: PREFECT_API_URL\n          value: &lt;http://host.docker.internal:4200/api&gt;\n        # Never pull the image because we're using a local image\n        imagePullPolicy: Never\n</code></pre> <p>Linux users</p> <p>If you're running Linux, you'll need to set your <code>PREFECT_API_URL</code> to use the IP address of your machine instead of <code>host.docker.internal</code>.</p> <p>This manifest defines how our image will run when deployed in our Kubernetes cluster. Note that we will be running a single replica of our flow container. If you want to run multiple replicas of your flow container to keep up with an active schedule, or because our flow is resource-intensive, you can increase the <code>replicas</code> value.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#deploying-our-flow-to-the-cluster","title":"Deploying our flow to the cluster","text":"<p>Now that we have a deployment manifest, we can deploy our flow to the cluster by running:</p> <pre><code>kubectl apply -f deployment-manifest.yaml\n</code></pre> <p>We can monitor the status of our Kubernetes deployment by running:</p> <pre><code>kubectl get deployments\n</code></pre> <p>Once the deployment has successfully started, we can check the logs of our flow container by running the following:</p> <pre><code>kubectl logs -l flow=get-repo-info\n</code></pre> <p>Now that we're serving our flow in our cluster, we can trigger a flow run by running:</p> <pre><code>prefect deployment run get-repo-info/prefect-docker-guide\n</code></pre> <p>If we navigate to the URL provided by the <code>prefect deployment run</code> command, we can follow the flow run via the logs in the Prefect UI!</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#prefect-maintained-docker-images","title":"Prefect-maintained Docker images","text":"<p>Every release of Prefect results in several new Docker images. These images are all named prefecthq/prefect and their tags identify their differences.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#image-tags","title":"Image tags","text":"<p>When a release is published, images are built for all of Prefect's supported Python versions. These images are tagged to identify the combination of Prefect and Python versions contained. Additionally, we have \"convenience\" tags which are updated with each release to facilitate automatic updates.</p> <p>For example, when release <code>2.11.5</code> is published:</p> <ol> <li>Images with the release packaged are built for each supported Python version (3.8, 3.9, 3.10, 3.11) with both standard Python and Conda.</li> <li>These images are tagged with the full description, e.g. <code>prefect:2.1.1-python3.10</code> and <code>prefect:2.1.1-python3.10-conda</code>.</li> <li>For users that want more specific pins, these images are also tagged with the SHA of the git commit of the release, e.g. <code>sha-88a7ff17a3435ec33c95c0323b8f05d7b9f3f6d2-python3.10</code></li> <li>For users that want to be on the latest <code>2.1.x</code> release, receiving patch updates, we update a tag without the patch version to this release, e.g. <code>prefect.2.1-python3.10</code>.</li> <li>For users that want to be on the latest <code>2.x.y</code> release, receiving minor version updates, we update a tag without the minor or patch version to this release, e.g. <code>prefect.2-python3.10</code></li> <li>Finally, for users who want the latest <code>2.x.y</code> release without specifying a Python version, we update <code>2-latest</code> to the image for our highest supported Python version, which in this case would be equivalent to <code>prefect:2.1.1-python3.10</code>.</li> </ol> <p>Choose image versions carefully</p> <p>It's a good practice to use Docker images with specific Prefect versions in production.</p> <p>Use care when employing images that automatically update to new versions (such as <code>prefecthq/prefect:2-python3.11</code> or <code>prefecthq/prefect:2-latest</code>).</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#standard-python","title":"Standard Python","text":"<p>Standard Python images are based on the official Python <code>slim</code> images, e.g. <code>python:3.10-slim</code>.</p> Tag Prefect Version Python Version 2-latest most recent v2 PyPi version 3.10 2-python3.11 most recent v2 PyPi version 3.11 2-python3.10 most recent v2 PyPi version 3.10 2-python3.9 most recent v2 PyPi version 3.9 2-python3.8 most recent v2 PyPi version 3.8 2.X-python3.11 2.X 3.11 2.X-python3.10 2.X 3.10 2.X-python3.9 2.X 3.9 2.X-python3.8 2.X 3.8 sha-&lt;hash&gt;-python3.11 &lt;hash&gt; 3.11 sha-&lt;hash&gt;-python3.10 &lt;hash&gt; 3.10 sha-&lt;hash&gt;-python3.9 &lt;hash&gt; 3.9 sha-&lt;hash&gt;-python3.8 &lt;hash&gt; 3.8","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#conda-flavored-python","title":"Conda-flavored Python","text":"<p>Conda flavored images are based on <code>continuumio/miniconda3</code>. Prefect is installed into a conda environment named <code>prefect</code>.</p> Tag Prefect Version Python Version 2-latest-conda most recent v2 PyPi version 3.10 2-python3.11-conda most recent v2 PyPi version 3.11 2-python3.10-conda most recent v2 PyPi version 3.10 2-python3.9-conda most recent v2 PyPi version 3.9 2-python3.8-conda most recent v2 PyPi version 3.8 2.X-python3.11-conda 2.X 3.11 2.X-python3.10-conda 2.X 3.10 2.X-python3.9-conda 2.X 3.9 2.X-python3.8-conda 2.X 3.8 sha-&lt;hash&gt;-python3.11-conda &lt;hash&gt; 3.11 sha-&lt;hash&gt;-python3.10-conda &lt;hash&gt; 3.10 sha-&lt;hash&gt;-python3.9-conda &lt;hash&gt; 3.9 sha-&lt;hash&gt;-python3.8-conda &lt;hash&gt; 3.8","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#building-your-own-image","title":"Building your own image","text":"<p>If your flow relies on dependencies not found in the default <code>prefecthq/prefect</code> images, you may want to build your own image. You can either base it off of one of the provided <code>prefecthq/prefect</code> images, or build your own image. See the Work pool deployment guide for discussion of how Prefect can help you build custom images with dependencies specified in a <code>requirements.txt</code> file.</p> <p>By default, Prefect work pools that use containers refer to the <code>2-latest</code> image. You can specify another image at work pool creation. The work pool image choice can be overridden in individual deployments.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#extending-the-prefecthqprefect-image-manually","title":"Extending the <code>prefecthq/prefect</code> image manually","text":"<p>Here we provide an example <code>Dockerfile</code> for building an image based on <code>prefecthq/prefect:2-latest</code>, but with <code>scikit-learn</code> installed.</p> <pre><code>FROM prefecthq/prefect:2-latest\n\nRUN pip install scikit-learn\n</code></pre>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#choosing-an-image-strategy","title":"Choosing an image strategy","text":"<p>The options described above have different complexity (and performance) characteristics. For choosing a strategy, we provide the following recommendations:</p> <ul> <li> <p>If your flow only makes use of tasks defined in the same file as the flow, or tasks that are part of <code>prefect</code> itself, then you can rely on the default provided <code>prefecthq/prefect</code> image.</p> </li> <li> <p>If your flow requires a few extra dependencies found on PyPI, you can use the default <code>prefecthq/prefect</code> image and set <code>prefect.deployments.steps.pip_install_requirements:</code> in the <code>pull</code>step to install these dependencies at runtime.</p> </li> <li> <p>If the installation process requires compiling code or other expensive operations, you may be better off building a custom image instead.</p> </li> <li> <p>If your flow (or flows) require extra dependencies or shared libraries, we recommend building a shared custom image with all the extra dependencies and shared task definitions you need. Your flows can then all rely on the same image, but have their source stored externally. This option can ease development, as the shared image only needs to be rebuilt when dependencies change, not when the flow source changes.</p> </li> </ul>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/docker/#next-steps","title":"Next steps","text":"<p>We only served a single flow in this guide, but you can extend this setup to serve multiple flows in a single Docker image by updating your Python script to using <code>flow.to_deployment</code> and <code>serve</code> to serve multiple flows or the same flow with different configuration.</p> <p>To learn more about deploying flows, check out the Deployments concept doc!</p> <p>For advanced infrastructure requirements, such as executing each flow run within its own dedicated Docker container, learn more in the Work pool deployment guide.</p>","tags":["Docker","containers","orchestration","infrastructure","deployments","images","Kubernetes"],"boost":2},{"location":"guides/global-concurrency-limits/","title":"Global Concurrency Limits and Rate Limits","text":"<p>Global concurrency limits allow you to manage execution efficiently, controlling how many tasks, flows, or other operations can run simultaneously. They are ideal when optimizing resource usage, preventing bottlenecks, and customizing task execution are priorities.</p> <p>Clarification on use of the term 'tasks'</p> <p>In the context of global concurrency and rate limits, \"tasks\" refers not specifically to Prefect tasks, but to concurrent units of work in general, such as those managed by an event loop or <code>TaskGroup</code> in asynchronous programming. These general \"tasks\" could include Prefect tasks when they are part of an asynchronous execution environment.</p> <p>Rate Limits ensure system stability by governing the frequency of requests or operations. They are suitable for preventing overuse, ensuring fairness, and handling errors gracefully.</p> <p>When selecting between Concurrency and Rate Limits, consider your primary goal. Choose Concurrency Limits for resource optimization and task management. Choose Rate Limits to maintain system stability and fair access to services.</p> <p>The core difference between a rate limit and a concurrency limit is the way in which slots are released. With a rate limit, slots are released at a controlled rate, controlled by <code>slot_decay_per_second</code> whereas with a concurrency limit, slots are released when the concurrency manager is exited.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#managing-global-concurrency-limits-and-rate-limits","title":"Managing Global concurrency limits and rate limits","text":"","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#active-vs-inactive-limits","title":"Active vs inactive limits","text":"<p>Global concurrency limits can be in either an <code>active</code> or <code>inactive</code> state.</p> <ul> <li>Active: In this state, slots can be occupied, and code execution will be blocked when slots are unable to be acquired.</li> <li>Inactive: In this state, slots will not be occupied, and code execution will not be blocked. Concurrency enforcement occurs only when you activate the limit.</li> </ul>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#slot-decay","title":"Slot decay","text":"<p>Global concurrency limits can be configured with slot decay. This is used when the concurrency limit is used as a rate limit, and it governs the pace at which slots are released or become available for reuse after being occupied. These slots effectively represent the concurrency capacity within a specific concurrency limit. The concept is best understood as the rate at which these slots \"decay\" or refresh.</p> <p>To configure slot decay, you can set the <code>slot_decay_per_second</code> parameter when defining or adjusting a concurrency limit.</p> <p>For practical use, consider the following:</p> <ul> <li> <p>Higher values: Setting <code>slot_decay_per_second</code> to a higher value, such as 5.0, results in slots becoming available relatively quickly. In this scenario, a slot that was occupied by a task will free up after just <code>0.2</code> (<code>1.0 / 5.0</code>) seconds.</p> </li> <li> <p>Lower values: Conversely, setting <code>slot_decay_per_second</code> to a lower value, like 0.1, causes slots to become available more slowly. In this scenario it would take <code>10</code> (<code>1.0 / 0.1</code>) seconds for a slot to become available again after occupancy</p> </li> </ul> <p>Slot decay provides fine-grained control over the availability of slots, enabling you to optimize the rate of your workflow based on your specific requirements.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#via-the-ui","title":"Via the UI","text":"<p>You can create, read, edit, and delete concurrency limits via the Prefect UI.</p> <p>When creating a concurrency limit, you can specify the following parameters:</p> <ul> <li>Name: The name of the concurrency limit. This name is also how you'll reference the concurrency limit in your code. Special characters, such as <code>/</code>, <code>%</code>, <code>&amp;</code>, <code>&gt;</code>, <code>&lt;</code>, are not allowed.</li> <li>Concurrency Limit: The maximum number of slots that can be occupied on this concurrency limit.</li> <li>Slot Decay Per Second: Controls the rate at which slots are released when the concurrency limit is used as a rate limit. This value must be configured when using the <code>rate_limit</code> function.</li> <li>Active Slots: The number of slots currently in use by clients. Prefect manages this field automatically, but you can set it to 0 to reset the limit if necessary.</li> <li>Active: Whether or not the concurrency limit is in an active state.</li> </ul>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#via-the-cli","title":"Via the CLI","text":"<p>You can create, read, edit, and delete global concurrency limits via the Prefect CLI.</p> <p>To create a new concurrency limit, use the <code>prefect gcl create</code> command. You must specify a <code>--limit</code> argument, and can optionally specify a <code>--slot-decay-per-second</code> and <code>--disable</code> argument.</p> <pre><code>prefect gcl create my-concurrency-limit --limit 5 --slot-decay-per-second 1.0\n</code></pre> <p>You can inspect the details of a concurrency limit using the <code>prefect gcl inspect</code> command:</p> <pre><code>prefect gcl inspect my-concurrency-limit\n</code></pre> <p>To update a concurrency limit, use the <code>prefect gcl update</code> command. You can update the <code>--limit</code>, <code>--slot-decay-per-second</code>, <code>--enable</code>, and <code>--disable</code> arguments:</p> <pre><code>prefect gcl update my-concurrency-limit --limit 10\n</code></pre> <pre><code>prefect gcl update my-concurrency-limit --disable\n</code></pre> <p>To delete a concurrency limit, use the <code>prefect gcl delete</code> command:</p> <pre><code>prefect gcl delete my-concurrency-limit\nAre you sure you want to delete global concurrency limit 'my-concurrency-limit'? [y/N]: y\nDeleted global concurrency limit with name 'my-concurrency-limit'.\n</code></pre> <p>See all available commands and options by running <code>prefect gcl --help</code>.</p>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-the-concurrency-context-manager","title":"Using the <code>concurrency</code> context manager","text":"<p>The <code>concurrency</code>context manager allows control over the maximum number of concurrent operations. You can select either the synchronous (<code>sync</code>) or asynchronous (<code>async</code>) version, depending on your use case. Here's how to use it:</p> <p>Concurrency limits are implicitly created</p> <p>When using the <code>concurrency</code> context manager, the concurrency limit you use will be created, in an inactive state, if it does not already exist.</p> <p>Sync</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import concurrency\n\n\n@task\ndef process_data(x, y):\n    with concurrency(\"database\", occupy=1):\n        return x + y\n\n\n@flow\ndef my_flow():\n    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:\n        process_data.submit(x, y)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Async</p> <pre><code>import asyncio\nfrom prefect import flow, task\nfrom prefect.concurrency.asyncio import concurrency\n\n\n@task\nasync def process_data(x, y):\n    async with concurrency(\"database\", occupy=1):\n        return x + y\n\n\n@flow\nasync def my_flow():\n    for x, y in [(1, 2), (2, 3), (3, 4), (4, 5)]:\n        await process_data.submit(x, y)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(my_flow())\n</code></pre> <ol> <li>The code imports the necessary modules and the concurrency context manager. Use the <code>prefect.concurrency.sync</code> module for sync usage and the <code>prefect.concurrency.asyncio</code> module for async usage.</li> <li>It defines a <code>process_data</code> task, taking <code>x</code> and <code>y</code> as input arguments. Inside this task, the concurrency context manager controls concurrency, using the <code>database</code> concurrency limit and occupying one slot. If another task attempts to run with the same limit and no slots are available, that task will be blocked until a slot becomes available.</li> <li>A flow named <code>my_flow</code> is defined. Within this flow, it iterates through a list of tuples, each containing pairs of x and y values. For each pair, the <code>process_data</code> task is submitted with the corresponding x and y values for processing.</li> </ol>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-rate_limit","title":"Using <code>rate_limit</code>","text":"<p>The Rate Limit feature provides control over the frequency of requests or operations, ensuring responsible usage and system stability. Depending on your requirements, you can utilize <code>rate_limit</code> to govern both synchronous (sync) and asynchronous (async) operations. Here's how to make the most of it:</p> <p>Slot decay</p> <p>When using the <code>rate_limit</code> function the concurrency limit you use must have a slot decay configured.</p> <p>Sync</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import rate_limit\n\n\n@task\ndef make_http_request():\n    rate_limit(\"rate-limited-api\")\n    print(\"Making an HTTP request...\")\n\n\n@flow\ndef my_flow():\n    for _ in range(10):\n        make_http_request.submit()\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre> <p>Async</p> <pre><code>import asyncio\n\nfrom prefect import flow, task\nfrom prefect.concurrency.asyncio import rate_limit\n\n\n@task\nasync def make_http_request():\n    await rate_limit(\"rate-limited-api\")\n    print(\"Making an HTTP request...\")\n\n\n@flow\nasync def my_flow():\n    for _ in range(10):\n        await make_http_request.submit()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(my_flow())\n</code></pre> <ol> <li>The code imports the necessary modules and the <code>rate_limit</code> function. Use the <code>prefect.concurrency.sync</code> module for sync usage and the <code>prefect.concurrency.asyncio</code> module for async usage.</li> <li>It defines a <code>make_http_request</code> task. Inside this task, the <code>rate_limit</code> function is used to ensure that the requests are made at a controlled pace.</li> <li>A flow named <code>my_flow</code> is defined. Within this flow the <code>make_http_request</code> task is submitted 10 times.</li> </ol>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#using-concurrency-and-rate_limit-outside-of-a-flow","title":"Using <code>concurrency</code> and <code>rate_limit</code> outside of a flow","text":"<p><code>concurreny</code> and <code>rate_limit</code> can be used outside of a flow to control concurrency and rate limits for any operation.</p> <pre><code>import asyncio\n\nfrom prefect.concurrency.asyncio import rate_limit\n\n\nasync def main():\n    for _ in range(10):\n        await rate_limit(\"rate-limited-api\")\n        print(\"Making an HTTP request...\")\n\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#use-cases","title":"Use cases","text":"","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#throttling-task-submission","title":"Throttling task submission","text":"<p>Throttling task submission to avoid overloading resources, to comply with external rate limits, or ensure a steady, controlled flow of work.</p> <p>In this scenario the <code>rate_limit</code> function is used to throttle the submission of tasks. The rate limit acts as a bottleneck, ensuring that tasks are submitted at a controlled rate, governed by the <code>slot_decay_per_second</code> setting on the associated concurrency limit.</p> <pre><code>from prefect import flow, task\nfrom prefect.concurrency.sync import rate_limit\n\n\n@task\ndef my_task(i):\n    return i\n\n\n@flow\ndef my_flow():\n    for _ in range(100):\n        rate_limit(\"slow-my-flow\", occupy=1)\n        my_task.submit(1)\n\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#managing-database-connections","title":"Managing database connections","text":"<p>Managing the maximum number of concurrent database connections to avoid exhausting database resources.</p> <p>In this scenario we've setup a concurrency limit named <code>database</code> and given it a maximum concurrency limit that matches the maximum number of database connections we want to allow. We then use the <code>concurrency</code> context manager to control the number of database connections allowed at any one time.</p> <pre><code>from prefect import flow, task, concurrency\nimport psycopg2\n\n@task\ndef database_query(query):\n    # Here we request a single slot on the 'database' concurrency limit. This\n    # will block in the case that all of the database connections are in use\n    # ensuring that we never exceed the maximum number of database connections.\n    with concurrency(\"database\", occupy=1):\n        connection = psycopg2.connect(\"&lt;connection_string&gt;\")\n        cursor = connection.cursor()\n        cursor.execute(query)\n        result = cursor.fetchall()\n        connection.close()\n        return result\n\n@flow\ndef my_flow():\n    queries = [\"SELECT * FROM table1\", \"SELECT * FROM table2\", \"SELECT * FROM table3\"]\n\n    for query in queries:\n        database_query.submit(query)\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/global-concurrency-limits/#parallel-data-processing","title":"Parallel data processing","text":"<p>Limiting the maximum number of parallel processing tasks.</p> <p>In this scenario we want to limit the number of <code>process_data</code> tasks to five at any one time. We do this by using the <code>concurrency</code> context manager to request five slots on the <code>data-processing</code> concurrency limit. This will block until five slots are free and then submit five more tasks, ensuring that we never exceed the maximum number of parallel processing tasks.</p> <pre><code>import asyncio\nfrom prefect.concurrency.sync import concurrency\n\n\nasync def process_data(data):\n    print(f\"Processing: {data}\")\n    await asyncio.sleep(1)\n    return f\"Processed: {data}\"\n\n\nasync def main():\n    data_items = list(range(100))\n    processed_data = []\n\n    while data_items:\n        with concurrency(\"data-processing\", occupy=5):\n            chunk = [data_items.pop() for _ in range(5)]\n            processed_data += await asyncio.gather(\n                *[process_data(item) for item in chunk]\n            )\n\n    print(processed_data)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n</code></pre>","tags":["concurrency","rate limits"],"boost":2},{"location":"guides/host/","title":"Host a Prefect server instance","text":"<p>Learn how to host your own Prefect server instance.</p> <p>Note</p> <p>If you would like to host a Prefect server instance on Kubernetes, check out the prefect-server Helm chart.</p> <p>After installing Prefect, you have:</p> <ul> <li>a Python SDK client that can communicate with Prefect Cloud</li> <li>an API server instance backed by a database and a UI</li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#steps","title":"Steps","text":"<ol> <li>Spin up a local Prefect server UI with the <code>prefect server start</code> CLI command in the terminal:</li> </ol> <pre><code>prefect server start\n</code></pre> <ol> <li>Open the URL for the Prefect server UI (http://127.0.0.1:4200 by default) in a browser.</li> </ol> <ol> <li>Shut down the Prefect server with  ctrl  +  c  in the terminal.","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#comparing-a-self-hosted-prefect-server-instance-and-prefect-cloud","title":"Comparing a self-hosted Prefect server instance and Prefect Cloud","text":"<p>A self-hosted Prefect server instance and Prefect Cloud share a common set of features. Prefect Cloud includes the following additional features:</p> <ul> <li>Workspaces \u2014 isolated environments to organize your flows, deployments, and flow runs.</li> <li>Automations \u2014 configure triggers, actions, and notifications in response to real-time monitoring events.</li> <li>Email notifications \u2014 send email alerts from Prefect's servers based on automation triggers.</li> <li>Service accounts \u2014 configure API access for running workers or executing flow runs on remote infrastructure.</li> <li>Custom role-based access controls (RBAC) \u2014 assign users granular permissions to perform activities within an account or workspace.</li> <li>Single Sign-on (SSO) \u2014 authentication using your identity provider.</li> <li>Audit Log \u2014 a record of user activities to monitor security and compliance.</li> </ul> <p>Read more about Prefect Cloud in the Cloud section.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-a-prefect-server-instance","title":"Configure a Prefect server instance","text":"<p>Go to your terminal session and run this command to set the API URL to point to a Prefect server instance:</p> <pre><code>prefect config set PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n</code></pre> <p><code>PREFECT_API_URL</code> required when running Prefect inside a container</p> <p>You must set the API server address to use Prefect within a container, such as a Docker container.</p> <p>You can save the API server address in a Prefect profile. Whenever that profile is active, the API endpoint is at that address.</p> <p>See Profiles &amp; Configuration for more information on profiles and configurable Prefect settings.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#the-prefect-database","title":"The Prefect database","text":"<p>The Prefect database persists data to track the state of your flow runs and related Prefect concepts, including:</p> <ul> <li>Flow run and task run state</li> <li>Run history</li> <li>Logs</li> <li>Deployments</li> <li>Flow and task run concurrency limits</li> <li>Storage blocks for flow and task results</li> <li>Variables</li> <li>Artifacts</li> <li>Work pool status</li> </ul> <p>Currently Prefect supports the following databases:</p> <ul> <li>SQLite (default in Prefect): Recommended for lightweight, single-server deployments. SQLite requires essentially no setup.</li> <li>PostgreSQL: Best for connecting to external databases, but requires additional setup (such as Docker). Prefect uses the <code>pg_trgm</code> extension, so it must be installed and enabled.</li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#using-the-database","title":"Using the database","text":"<p>A local SQLite database is the default database and is configured upon Prefect installation. The database is located at <code>~/.prefect/prefect.db</code> by default.</p> <p>To reset your database, run the CLI command:  </p> <pre><code>prefect server database reset -y\n</code></pre> <p>This command clears all data and reapplies the schema.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#database-settings","title":"Database settings","text":"<p>Prefect provides several settings for configuring the database. The default settings are:</p> <pre><code>PREFECT_API_DATABASE_CONNECTION_URL='sqlite+aiosqlite:///${PREFECT_HOME}/prefect.db'\nPREFECT_API_DATABASE_ECHO='False'\nPREFECT_API_DATABASE_MIGRATE_ON_START='True'\nPREFECT_API_DATABASE_PASSWORD='None'\n</code></pre> <p>Save a setting to your active Prefect profile with <code>prefect config set</code>.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-a-postgresql-database","title":"Configure a PostgreSQL database","text":"<p>Connect Prefect to a PostgreSQL database by setting the following environment variable:</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"postgresql+asyncpg://postgres:yourTopSecretPassword@localhost:5432/prefect\"\n</code></pre> <p>The above environment variable assumes:</p> <ul> <li>You have a username called <code>postgres</code></li> <li>Your password is set to <code>yourTopSecretPassword</code></li> <li>Your database runs on the same host as the Prefect server instance, <code>localhost</code></li> <li>You use the default PostgreSQL port <code>5432</code></li> <li>Your PostgreSQL instance has a database called <code>prefect</code></li> </ul>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#quickstart-configure-a-postgresql-database-with-docker","title":"Quickstart: configure a PostgreSQL database with Docker","text":"<p>Quickly start a PostgreSQL instance to use as your Prefect database with the following command (which will start a Docker container running PostgreSQL):</p> <pre><code>docker run -d --name prefect-postgres -v prefectdb:/var/lib/postgresql/data -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=yourTopSecretPassword -e POSTGRES_DB=prefect postgres:latest\n</code></pre> <p>The above command:</p> <ul> <li>Pulls the latest version of the official <code>postgres</code> Docker image, which is compatible with Prefect.</li> <li>Starts a container with the name <code>prefect-postgres</code>.</li> <li>Creates a database <code>prefect</code> with a user <code>postgres</code> and <code>yourTopSecretPassword</code> password.</li> <li>Mounts the PostgreSQL data to a Docker volume called <code>prefectdb</code> to provide persistence if you ever have to restart or rebuild that container.</li> </ul> <p>Run the command below to set your current Prefect Profile to the PostgreSQL database instance running in your Docker container.</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"postgresql+asyncpg://postgres:yourTopSecretPassword@localhost:5432/prefect\"\n</code></pre>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#confirm-your-postgresql-database-configuration","title":"Confirm your PostgreSQL database configuration","text":"<p>Inspect your Prefect profile to confirm that the environment variable has been properly set:</p> <pre><code>prefect config view --show-sources\n</code></pre> <pre><code>You should see output similar to the following:\n\nPREFECT_PROFILE='my_profile'\nPREFECT_API_DATABASE_CONNECTION_URL='********' (from profile)\nPREFECT_API_URL='http://127.0.0.1:4200/api' (from profile)\n</code></pre> <p>Start the Prefect server to use your PostgreSQL database instance:</p> <pre><code>prefect server start\n</code></pre>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#in-memory-database","title":"In-memory database","text":"<p>To use an in-memory SQLite database, set the following environment variable:</p> <pre><code>prefect config set PREFECT_API_DATABASE_CONNECTION_URL=\"sqlite+aiosqlite:///file::memory:?cache=shared&amp;uri=true&amp;check_same_thread=false\"\n</code></pre> <p>Use SQLite database for testing only</p> <p>SQLite is only supported by Prefect for testing purposes and is not compatible with multiprocessing.  </p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#migrations","title":"Migrations","text":"<p>Prefect uses Alembic to manage database migrations. Alembic is a database migration tool to use with the SQLAlchemy Database Toolkit for Python. Alembic provides a framework for generating and applying schema changes to a database.</p> <p>Apply migrations to your database with the following commands:</p> <p>To upgrade:</p> <pre><code>prefect server database upgrade -y\n</code></pre> <p>To downgrade:</p> <pre><code>prefect server database downgrade -y\n</code></pre> <p>Use the <code>-r</code> flag to specify a specific migration version to upgrade or downgrade to. For example, to downgrade to the previous migration version, run:</p> <pre><code>prefect server database downgrade -y -r -1\n</code></pre> <p>or to downgrade to a specific revision:</p> <pre><code>prefect server database downgrade -y -r d20618ce678e\n</code></pre> <p>To downgrade all migrations, use the <code>base</code> revision.</p> <p>See the contributing docs to create new database migrations.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#notifications","title":"Notifications","text":"<p>Prefect Cloud gives you access to a hosted platform with Workspace &amp; User controls, Events, and Automations. Prefect Cloud has an option for automation notifications. The more limited Notifications option is provided for the self-hosted Prefect server.</p> <p>Notifications enable you to set up alerts that are sent when a flow enters any state you specify. When your flow and task runs changes state, Prefect notes the state change and checks whether the new state matches any notification policies. If it does, a new notification is queued.</p> <p>Prefect supports sending notifications through:</p> <ul> <li>Custom webhook</li> <li>Discord webhook</li> <li>Mattermost webhook</li> <li>Microsoft Teams webhook</li> <li>Opsgenie webhook</li> <li>PagerDuty webhook</li> <li>Sendgrid email</li> <li>Slack webhook</li> <li>Twilio SMS</li> </ul> <p>Notifications in Prefect Cloud</p> <p>Prefect Cloud uses the robust Automations interface to enable notifications related to flow run state changes and work pool status.</p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/host/#configure-notifications","title":"Configure notifications","text":"<p>To configure a notification in a Prefect server, go to the Notifications page and select Create Notification or the + button.</p> <p></p> <p>You can choose:</p> <ul> <li>Which run states should trigger a notification</li> <li>Tags to filter which flow runs are covered by the notification</li> <li>Whether to send an email, a Slack message, Microsoft Teams message, or use another services</li> </ul> <p>For email notifications (supported on Prefect Cloud only), the configuration requires email addresses to which the message is sent.</p> <p>For Slack notifications, the configuration requires webhook credentials for your Slack and the channel to which the message is sent.</p> <p>For example, to get a Slack message if a flow with a <code>daily-etl</code> tag fails, the notification will read:</p> <p>If a run of any flow with daily-etl tag enters a failed state, send a notification to my-slack-webhook</p> <p>When the conditions of the notification are triggered, you\u2019ll receive a message:</p> <p>The fuzzy-leopard run of the daily-etl flow entered a failed state at 22-06-27 16:21:37 EST.</p> <p>On the Notifications page you can pause, edit, or delete any configured notification.</p> <p></p>","tags":["UI","dashboard","Prefect Server","Observability","Events","Serve","Database","SQLite"],"boost":2},{"location":"guides/logs/","title":"Logging","text":"<p>Prefect enables you to log a variety of useful information about your flow and task runs, capturing information about your workflows for purposes such as monitoring, troubleshooting, and auditing.</p> <p>Prefect captures logs for your flow and task runs by default, even if you have not started a Prefect server with <code>prefect server start</code>.</p> <p>You can view and filter logs in the Prefect UI or Prefect Cloud, or access log records via the API.</p> <p>Prefect enables fine-grained customization of log levels for flows and tasks, including configuration for default levels and log message formatting.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-overview","title":"Logging overview","text":"<p>Whenever you run a flow, Prefect automatically logs events for flow runs and task runs, along with any custom log handlers you have configured. No configuration is needed to enable Prefect logging.</p> <p>For example, say you created a simple flow in a file <code>flow.py</code>. If you create a local flow run with <code>python flow.py</code>, you'll see an example of the log messages created automatically by Prefect:</p> <pre><code>16:45:44.534 | INFO    | prefect.engine - Created flow run 'gray-dingo' for flow\n'hello-flow'\n16:45:44.534 | INFO    | Flow run 'gray-dingo' - Using task runner 'SequentialTaskRunner'\n16:45:44.598 | INFO    | Flow run 'gray-dingo' - Created task run 'hello-task-54135dc1-0'\nfor task 'hello-task'\nHello world!\n16:45:44.650 | INFO    | Task run 'hello-task-54135dc1-0' - Finished in state\nCompleted(None)\n16:45:44.672 | INFO    | Flow run 'gray-dingo' - Finished in state\nCompleted('All states completed.')\n</code></pre> <p>You can see logs for a flow run in the Prefect UI by navigating to the Flow Runs page and selecting a specific flow run to inspect.</p> <p></p> <p>These log messages reflect the logging configuration for log levels and message formatters. You may customize the log levels captured and the default message format through configuration, and you can capture custom logging events by explicitly emitting log messages during flow and task runs.</p> <p>Prefect supports the standard Python logging levels <code>CRITICAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, and <code>DEBUG</code>. By default, Prefect displays <code>INFO</code>-level and above events. You can configure the root logging level as well as specific logging levels for flow and task runs.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-configuration","title":"Logging configuration","text":"","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-settings","title":"Logging settings","text":"<p>Prefect provides several settings for configuring logging level and loggers.</p> <p>By default, Prefect displays <code>INFO</code>-level and above logging records. You may change this level to <code>DEBUG</code> and <code>DEBUG</code>-level logs created by Prefect will be shown as well. You may need to change the log level used by loggers from other libraries to see their log records.</p> <p>You can override any logging configuration by setting an environment variable or Prefect Profile setting using the syntax <code>PREFECT_LOGGING_[PATH]_[TO]_[KEY]</code>, with <code>[PATH]_[TO]_[KEY]</code> corresponding to the nested address of any setting.</p> <p>For example, to change the default logging levels for Prefect to <code>DEBUG</code>, you can set the environment variable <code>PREFECT_LOGGING_LEVEL=\"DEBUG\"</code>.</p> <p>You may also configure the \"root\" Python logger. The root logger receives logs from all loggers unless they explicitly opt out by disabling propagation. By default, the root logger is configured to output <code>WARNING</code> level logs to the console. As with other logging settings, you can override this from the environment or in the logging configuration file. For example, you can change the level with the variable <code>PREFECT_LOGGING_ROOT_LEVEL</code>.</p> <p>You may adjust the log level used by specific handlers. For example, you could set <code>PREFECT_LOGGING_HANDLERS_API_LEVEL=ERROR</code> to have only <code>ERROR</code> logs reported to the Prefect API. The console handlers will still default to level <code>INFO</code>.</p> <p>There is a <code>logging.yml</code> file packaged with Prefect that defines the default logging configuration.</p> <p>You can customize logging configuration by creating your own version of <code>logging.yml</code> with custom settings, by either creating the file at the default location (<code>/.prefect/logging.yml</code>) or by specifying the path to the file with <code>PREFECT_LOGGING_SETTINGS_PATH</code>. (If the file does not exist at the specified location, Prefect ignores the setting and uses the default configuration.)</p> <p>See the Python Logging configuration documentation for more information about the configuration options and syntax used by <code>logging.yml</code>.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#prefect-loggers","title":"Prefect loggers","text":"<p>To access the Prefect logger, import <code>from prefect import get_run_logger</code>. You can send messages to the logger in both flows and tasks.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-in-flows","title":"Logging in flows","text":"<p>To log from a flow, retrieve a logger instance with <code>get_run_logger()</code>, then call the standard Python logging methods.</p> <pre><code>from prefect import flow, get_run_logger\n\n@flow(name=\"log-example-flow\")\ndef logger_flow():\n    logger = get_run_logger()\n    logger.info(\"INFO level log message.\")\n</code></pre> <p>Prefect automatically uses the flow run logger based on the flow context. If you run the above code, Prefect captures the following as a log event.</p> <pre><code>15:35:17.304 | INFO    | Flow run 'mottled-marten' - INFO level log message.\n</code></pre> <p>The default flow run log formatter uses the flow run name for log messages.</p> <p>Note</p> <pre><code>Starting in 2.7.11, if you use a logger that sends logs to the API outside of a flow or task run, a warning will be displayed instead of an error. You can silence this warning by setting `PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW=ignore` or have the logger raise an error by setting the value to `error`.\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-in-tasks","title":"Logging in tasks","text":"<p>Logging in tasks works much as logging in flows: retrieve a logger instance with <code>get_run_logger()</code>, then call the standard Python logging methods.</p> <pre><code>from prefect import flow, task, get_run_logger\n\n@task(name=\"log-example-task\")\ndef logger_task():\n    logger = get_run_logger()\n    logger.info(\"INFO level log message from a task.\")\n\n@flow(name=\"log-example-flow\")\ndef logger_flow():\n    logger_task()\n</code></pre> <p>Prefect automatically uses the task run logger based on the task context. The default task run log formatter uses the task run name for log messages.</p> <pre><code>15:33:47.179 | INFO   | Task run 'logger_task-80a1ffd1-0' - INFO level log message from a task.\n</code></pre> <p>The underlying log model for task runs captures the task name, task run ID, and parent flow run ID, which are persisted to the database for reporting and may also be used in custom message formatting.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#logging-print-statements","title":"Logging print statements","text":"<p>Prefect provides the <code>log_prints</code> option to enable the logging of <code>print</code> statements at the task or flow level. When <code>log_prints=True</code> for a given task or flow, the Python builtin <code>print</code> will be patched to redirect to the Prefect logger for the scope of that task or flow.</p> <p>By default, tasks and subflows will inherit the <code>log_prints</code> setting from their parent flow, unless opted out with their own explicit <code>log_prints</code> setting.</p> <pre><code>from prefect import task, flow\n\n@task\ndef my_task():\n    print(\"we're logging print statements from a task\")\n\n@flow(log_prints=True)\ndef my_flow():\n    print(\"we're logging print statements from a flow\")\n    my_task()\n</code></pre> <p>Will output:</p> <pre><code>15:52:11.244 | INFO    | prefect.engine - Created flow run 'emerald-gharial' for flow 'my-flow'\n15:52:11.812 | INFO    | Flow run 'emerald-gharial' - we're logging print statements from a flow\n15:52:11.926 | INFO    | Flow run 'emerald-gharial' - Created task run 'my_task-20c6ece6-0' for task 'my_task'\n15:52:11.927 | INFO    | Flow run 'emerald-gharial' - Executing 'my_task-20c6ece6-0' immediately...\n15:52:12.217 | INFO    | Task run 'my_task-20c6ece6-0' - we're logging print statements from a task\n</code></pre> <pre><code>from prefect import task, flow\n\n@task\ndef my_task(log_prints=False):\n    print(\"not logging print statements in this task\")\n\n@flow(log_prints=True)\ndef my_flow():\n    print(\"we're logging print statements from a flow\")\n    my_task()\n</code></pre> <p>Using <code>log_prints=False</code> at the task level will output:</p> <pre><code>15:52:11.244 | INFO    | prefect.engine - Created flow run 'emerald-gharial' for flow 'my-flow'\n15:52:11.812 | INFO    | Flow run 'emerald-gharial' - we're logging print statements from a flow\n15:52:11.926 | INFO    | Flow run 'emerald-gharial' - Created task run 'my_task-20c6ece6-0' for task 'my_task'\n15:52:11.927 | INFO    | Flow run 'emerald-gharial' - Executing 'my_task-20c6ece6-0' immediately...\nnot logging print statements in this task\n</code></pre> <p>You can also configure this behavior globally for all Prefect flows, tasks, and subflows.</p> <pre><code>prefect config set PREFECT_LOGGING_LOG_PRINTS=True\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#formatters","title":"Formatters","text":"<p>Prefect log formatters specify the format of log messages. You can see details of message formatting for different loggers in <code>logging.yml</code>. For example, the default formatting for task run log records is:</p> <pre><code>\"%(asctime)s.%(msecs)03d | %(levelname)-7s | Task run %(task_run_name)r - %(message)s\"\n</code></pre> <p>The variables available to interpolate in log messages varies by logger. In addition to the run context, message string, and any keyword arguments, flow and task run loggers have access to additional variables.</p> <p>The flow run logger has the following:</p> <ul> <li><code>flow_run_name</code></li> <li><code>flow_run_id</code></li> <li><code>flow_name</code></li> </ul> <p>The task run logger has the following:</p> <ul> <li><code>task_run_id</code></li> <li><code>flow_run_id</code></li> <li><code>task_run_name</code></li> <li><code>task_name</code></li> <li><code>flow_run_name</code></li> <li><code>flow_name</code></li> </ul> <p>You can specify custom formatting by setting an environment variable or by modifying the formatter in a <code>logging.yml</code> file as described earlier. For example, to change the formatting for the flow runs formatter:</p> <pre><code>PREFECT_LOGGING_FORMATTERS_STANDARD_FLOW_RUN_FMT=\"%(asctime)s.%(msecs)03d | %(levelname)-7s | %(flow_run_id)s - %(message)s\"\n</code></pre> <p>The resulting messages, using the flow run ID instead of name, would look like this:</p> <pre><code>10:40:01.211 | INFO    | e43a5a80-417a-41c4-a39e-2ef7421ee1fc - Created task run\n'othertask-1c085beb-3' for task 'othertask'\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#styles","title":"Styles","text":"<p>By default, Prefect highlights specific keywords in the console logs with a variety of colors.</p> <p>Highlighting can be toggled on/off with the <code>PREFECT_LOGGING_COLORS</code> setting, e.g.</p> <pre><code>PREFECT_LOGGING_COLORS=False\n</code></pre> <p>You can change what gets highlighted and also adjust the colors by updating the styles in a <code>logging.yml</code> file. Below lists the specific keys built-in to the <code>PrefectConsoleHighlighter</code>.</p> <p>URLs:</p> <ul> <li><code>log.web_url</code></li> <li><code>log.local_url</code></li> </ul> <p>Log levels:</p> <ul> <li><code>log.info_level</code></li> <li><code>log.warning_level</code></li> <li><code>log.error_level</code></li> <li><code>log.critical_level</code></li> </ul> <p>State types:</p> <ul> <li><code>log.pending_state</code></li> <li><code>log.running_state</code></li> <li><code>log.scheduled_state</code></li> <li><code>log.completed_state</code></li> <li><code>log.cancelled_state</code></li> <li><code>log.failed_state</code></li> <li><code>log.crashed_state</code></li> </ul> <p>Flow (run) names:</p> <ul> <li><code>log.flow_run_name</code></li> <li><code>log.flow_name</code></li> </ul> <p>Task (run) names:</p> <ul> <li><code>log.task_run_name</code></li> <li><code>log.task_name</code></li> </ul> <p>You can also build your own handler with a custom highlighter. For example, to additionally highlight emails:</p> <ol> <li>Copy and paste the following into  <code>my_package_or_module.py</code> (rename as needed) in the same directory as the flow run script, or ideally part of a Python package so it's available in <code>site-packages</code> to be accessed anywhere within your environment.</li> </ol> <pre><code>import logging\nfrom typing import Dict, Union\n\nfrom rich.highlighter import Highlighter\n\nfrom prefect.logging.handlers import PrefectConsoleHandler\nfrom prefect.logging.highlighters import PrefectConsoleHighlighter\n\nclass CustomConsoleHighlighter(PrefectConsoleHighlighter):\n    base_style = \"log.\"\n    highlights = PrefectConsoleHighlighter.highlights + [\n        # ?P&lt;email&gt; is naming this expression as `email`\n        r\"(?P&lt;email&gt;[\\w-]+@([\\w-]+\\.)+[\\w-]+)\",\n    ]\n\nclass CustomConsoleHandler(PrefectConsoleHandler):\n    def __init__(\n        self,\n        highlighter: Highlighter = CustomConsoleHighlighter,\n        styles: Dict[str, str] = None,\n        level: Union[int, str] = logging.NOTSET,\n   ):\n        super().__init__(highlighter=highlighter, styles=styles, level=level)\n</code></pre> <ol> <li>Update <code>/.prefect/logging.yml</code> to use <code>my_package_or_module.CustomConsoleHandler</code> and additionally reference the base_style and named expression: <code>log.email</code>.</li> </ol> <pre><code>    console_flow_runs:\n        level: 0\n        class: my_package_or_module.CustomConsoleHandler\n        formatter: flow_runs\n        styles:\n            log.email: magenta\n            # other styles can be appended here, e.g.\n            # log.completed_state: green\n</code></pre> <ol> <li>Then on your next flow run, text that looks like an email will be highlighted--e.g. <code>my@email.com</code> is colored in magenta here.</li> </ol> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef log_email_flow():\n    logger = get_run_logger()\n    logger.info(\"my@email.com\")\n\nlog_email_flow()\n</code></pre>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#applying-markup-in-logs","title":"Applying markup in logs","text":"<p>To use Rich's markup in Prefect logs, first configure <code>PREFECT_LOGGING_MARKUP</code>.</p> <pre><code>PREFECT_LOGGING_MARKUP=True\n</code></pre> <p>Then, the following will highlight \"fancy\" in red.</p> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"This is [bold red]fancy[/]\")\n\nmy_flow()\n</code></pre> <p>Inaccurate logs could result</p> <p>Although this can be convenient, the downside is, if enabled, strings that contain square brackets may be inaccurately interpreted and lead to incomplete output, e.g. <code>DROP TABLE [dbo].[SomeTable];\"</code> outputs <code>DROP TABLE .[SomeTable];</code>.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#log-database-schema","title":"Log database schema","text":"<p>Logged events are also persisted to the Prefect database. A log record includes the following data:</p> Column Description id Primary key ID of the log record. created Timestamp specifying when the record was created. updated Timestamp specifying when the record was updated. name String specifying the name of the logger. level Integer representation of the logging level. flow_run_id ID of the flow run associated with the log record. If the log record is for a task run, this is the parent flow of the task. task_run_id ID of the task run associated with the log record. Null if logging a flow run event. message Log message. timestamp The client-side timestamp of this logged statement. <p>For more information, see Log schema in the API documentation.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/logs/#including-logs-from-other-libraries","title":"Including logs from other libraries","text":"<p>By default, Prefect won't capture log statements from libraries that your flows and tasks use. You can tell Prefect to include logs from these libraries with the <code>PREFECT_LOGGING_EXTRA_LOGGERS</code> setting.</p> <p>To use this setting, specify one or more Python library names to include, separated by commas. For example, if you want to make sure Prefect captures Dask and SciPy logging statements with your flow and task run logs:</p> <pre><code>PREFECT_LOGGING_EXTRA_LOGGERS=dask,scipy\n</code></pre> <p>You can set this setting as an environment variable or in a profile. See Settings for more details about how to use settings.</p>","tags":["UI","dashboard","Prefect Cloud","flows","tasks","logging","log formatters","configuration","debug"],"boost":2},{"location":"guides/managed-execution/","title":"Managed Execution","text":"<p>Prefect Cloud can run your flows on your behalf with Prefect Managed work pools. Flows run with this work pool do not require a worker or cloud provider account. Prefect handles the infrastructure and code execution for you.</p> <p>Managed execution is a great option for users who want to get started quickly, with no infrastructure setup.</p> <p>Managed Execution is in beta</p> <p>Managed Execution is currently in beta. Features are likely to change without warning.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#usage-guide","title":"Usage guide","text":"<p>Run a flow with managed infrastructure in three steps.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-1","title":"Step 1","text":"<p>Create a new work pool of type Prefect Managed in the UI or the CLI. Here's the command to create a new work pool using the CLI:</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed\n</code></pre>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-2","title":"Step 2","text":"<p>Create a deployment using the flow <code>deploy</code> method or <code>prefect.yaml</code>.</p> <p>Specify the name of your managed work pool, as shown in this example that uses the <code>deploy</code> method:</p> managed-execution.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n    source=\"https://github.com/prefecthq/demo.git\",\n    entrypoint=\"flow.py:my_flow\",\n    ).deploy(\n        name=\"test-managed-flow\",\n        work_pool_name=\"my-managed-pool\",\n    )\n</code></pre> <p>With your CLI authenticated to your Prefect Cloud workspace, run the script to create your deployment:</p> <pre><code>python managed-execution.py\n</code></pre> <p>Note that this deployment uses flow code stored in a GitHub repository.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#step-3","title":"Step 3","text":"<p>Run the deployment from the UI or from the CLI.</p> <p>That's it! You ran a flow on remote infrastructure without any infrastructure setup, starting a worker, or needing a cloud provider account.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#adding-dependencies","title":"Adding dependencies","text":"<p>Prefect can install Python packages in the container that runs your flow at runtime. You can specify these dependencies in the Pip Packages field in the UI, or by configuring <code>job_variables={\"pip_packages\": [\"pandas\", \"prefect-aws\"]}</code> in your deployment creation like this:</p> <pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n    source=\"https://github.com/prefecthq/demo.git\",\n    entrypoint=\"flow.py:my_flow\",\n    ).deploy(\n        name=\"test-managed-flow\",\n        work_pool_name=\"my-managed-pool\",\n        job_variables={\"pip_packages\": [\"pandas\", \"prefect-aws\"]}\n    )\n</code></pre> <p>Alternatively, you can create a <code>requirements.txt</code> file and reference it in your <code>prefect.yaml</code> <code>pull_step</code>.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#limitations","title":"Limitations","text":"<p>Managed execution requires Prefect 2.14.4 or newer.</p> <p>All limitations listed below may change without warning during the beta period. We will update this page as we make changes.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#concurrency-work-pools","title":"Concurrency &amp; work pools","text":"<p>Free tier accounts are limited to:</p> <ul> <li>Maximum of 1 concurrent flow run per workspace across all <code>prefect:managed</code> pools.</li> <li>Maximum of 1 managed execution work pool per workspace.</li> </ul> <p>Pro tier and above accounts are limited to:</p> <ul> <li>Maximum of 10 concurrent flow runs per workspace across all <code>prefect:managed</code> pools.</li> <li>Maximum of 5 managed execution work pools per workspace.</li> </ul>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#images","title":"Images","text":"<p>At this time, managed execution requires that you run the official Prefect Docker image: <code>prefecthq/prefect:2-latest</code>. However, as noted above, you can install Python package dependencies at runtime. If you need to use your own image, we recommend using another type of work pool.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#code-storage","title":"Code storage","text":"<p>Flow code must be stored in an accessible remote location. This means git-based cloud providers such as GitHub, Bitbucket, or GitLab are supported. Remote block-based storage is also supported, so S3, GCS, and Azure Blob are additional code storage options.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#resources","title":"Resources","text":"<p>Memory is limited to 2GB of RAM, which includes all operations such as dependency installation. Maximum job run time is 24 hours.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#usage-limits","title":"Usage limits","text":"<p>Free tier accounts are limited to ten compute hours per workspace per month. Pro tier and above accounts are limited to 250 hours per workspace per month. You can view your compute hours quota usage on the Work Pools page in the UI.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/managed-execution/#next-steps","title":"Next steps","text":"<p>Read more about creating deployments in the deployment guide.</p> <p>If you find that you need more control over your infrastructure, such as the ability to run custom Docker images, serverless push work pools might be a good option. Read more here.</p>","tags":["managed infrastructure","infrastructure"],"boost":2},{"location":"guides/migration-guide/","title":"Migrating from Prefect 1 to Prefect 2","text":"<p>This guide is designed to help you migrate your workflows from Prefect 1 to Prefect 2. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-stayed-the-same","title":"What stayed the same","text":"<p>Prefect 2 still:</p> <ul> <li>Has tasks and flows.</li> <li>Orchestrates your flow runs and provides observability into their execution states.</li> <li>Runs and inspects flow runs locally.</li> <li>Provides a coordination plane for your dataflows based on the same principles. </li> <li>Employs the same hybrid execution model, where Prefect doesn't store your flow code or data. </li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed","title":"What changed","text":"<p>Prefect 2 requires modifications to your existing tasks, flows, and deployment patterns. We've organized this section into the following categories:</p> <ul> <li>Simplified patterns \u2014 abstractions from Prefect 1 that are no longer necessary in the dynamic, DAG-free Prefect workflows that support running native Python code in your flows.</li> <li>Conceptual and syntax changes that often clarify names and simplify familiar abstractions such as retries and caching.</li> <li>New features enabled by the dynamic and flexible Prefect API.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#simplified-patterns","title":"Simplified patterns","text":"<p>Since Prefect 2 allows running native Python code within the flow function, some abstractions are no longer necessary:</p> <ul> <li><code>Parameter</code> tasks: in Prefect 2, inputs to your flow function are automatically treated as parameters of your flow. You can define the parameter values in your flow code when you create your <code>Deployment</code>, or when you schedule an ad-hoc flow run. One benefit of Prefect parametrization is built-in type validation with pydantic.</li> <li>Task-level <code>state_handlers</code>: in Prefect 2, you can build custom logic that reacts to task-run states within your flow function without the need for <code>state_handlers</code>. The page \"   How to take action on a state change of a task run\" provides a further explanation and code examples.</li> <li>Instead of using <code>signals</code>, Prefect 2 allows you to raise an arbitrary exception in your task or flow and return a custom state. For more details and examples, see How can I stop the task run based on a custom logic.</li> <li>Conditional tasks such as <code>case</code> are no longer required. Use Python native <code>if...else</code> statements to build a conditional logic. The Discourse tag \"conditional-logic\" provides more resources.</li> <li>Since you can use any context manager directly in your flow, a <code>resource_manager</code> is no longer necessary. As long as you point to your flow script in your <code>Deployment</code>, you can share database connections and any other resources between tasks in your flow. The Discourse page How to clean up resources used in a flow provides a full example.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#conceptual-and-syntax-changes","title":"Conceptual and syntax changes","text":"<p>The changes listed below require you to modify your workflow code. The following table shows how Prefect 1 concepts have been implemented in Prefect 2. The last column contains references to additional resources that provide more details and examples.</p> Concept Prefect 1 Prefect 2 Reference links Flow definition. <code>with Flow(\"flow_name\") as flow:</code> <code>@flow(name=\"flow_name\")</code> How can I define a flow? Flow executor that determines how to execute your task runs. Executor such as <code>LocalExecutor</code>. Task runner such as <code>ConcurrentTaskRunner</code>. What is the default TaskRunner (executor)? Configuration that determines how and where to execute your flow runs. Run configuration such as <code>flow.run_config = DockerRun()</code>. Create an infrastructure block such as a Docker Container and specify it as the infrastructure when creating a deployment. How can I run my flow in a Docker container? Assignment of schedules and default parameter values. Schedules are attached to the flow object and default parameter values are defined within the Parameter tasks. Schedules and default parameters are assigned to a flow\u2019s <code>Deployment</code>, rather than to a Flow object. How can I attach a schedule to a flow? Retries <code>@task(max_retries=2, retry_delay=timedelta(seconds=5))</code> <code>@task(retries=2, retry_delay_seconds=5)</code> How can I specify the retry behavior for a specific task? Logger syntax. Logger is retrieved from <code>prefect.context</code> and can only be used within tasks. In Prefect 2, you can log not only from tasks, but also within flows. To get the logger object, use: <code>prefect.get_run_logger()</code>. How can I add logs to my flow? The syntax and contents of Prefect context. Context is a thread-safe way of accessing variables related to the flow run and task run. The syntax to retrieve it: <code>prefect.context</code>. Context is still available, but its content is much richer, allowing you to retrieve even more information about your flow runs and task runs. The syntax to retrieve it: <code>prefect.context.get_run_context()</code>. How to access Prefect context values? Task library. Included in the main Prefect Core repository. Separated into individual repositories per system, cloud provider, or technology. How to migrate Prefect 1 tasks to Prefect 2 integrations.","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed-in-dataflow-orchestration","title":"What changed in dataflow orchestration?","text":"<p>Let\u2019s look at the differences in how Prefect 2 transitions your flow and task runs between various execution states.</p> <ul> <li>In Prefect 2, the final state of a flow run that finished without errors is <code>Completed</code>, while in Prefect 1, this flow run has a <code>Success</code> state. You can find more about that topic here.</li> <li>The decision about whether a flow run should be considered successful or not is no longer based on special reference tasks. Instead, your flow\u2019s return value determines the final state of a flow run. This link provides a more detailed explanation with code examples.</li> <li>In Prefect 1, concurrency limits were only available to Prefect Cloud users. Prefect 2 provides customizable concurrency limits with the open-source Prefect server and Prefect Cloud. In Prefect 2, flow run concurrency limits are set on work pools.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#what-changed-in-flow-deployment-patterns","title":"What changed in flow deployment patterns?","text":"<p>To deploy your Prefect 1 flows, you have to send flow metadata to the backend in a step called registration. Prefect 2 no longer requires flow pre-registration. Instead, you create a Deployment that specifies the entry point to your flow code and optionally specifies:</p> <ul> <li>Where to run your flow (your Infrastructure, such as a <code>DockerContainer</code>, <code>KubernetesJob</code>, or <code>ECSTask</code>).</li> <li>When to run your flow (an <code>Interval</code>, <code>Cron</code>, or <code>RRule</code> schedule).</li> <li>How to run your flow (execution details such as <code>parameters</code>, flow deployment <code>name</code>, and more).</li> <li>The work pool for your deployment. If no work pool is specified, a default work pool named <code>default</code> is used.</li> </ul> <p>The API is now implemented as a REST API rather than GraphQL. This page illustrates how you can interact with the API.</p> <p>In Prefect 1, the logical grouping of flows was based on projects. Prefect 2 provides a much more flexible way of organizing your flows, tasks, and deployments through customizable filters and\u00a0tags. This page provides more details on how to assign tags to various Prefect 2 objects.</p> <p>The role of agents has changed:</p> <ul> <li>In Prefect 2, there is only one generic agent type. The agent polls a work pool looking for flow runs.</li> <li>See this Discourse page for a more detailed discussion.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#new-features-introduced-in-prefect-2","title":"New features introduced in Prefect 2","text":"<p>The following new components and capabilities are enabled by Prefect 2.</p> <ul> <li>More flexibility thanks to the elimination of flow pre-registration.</li> <li>More flexibility for flow deployments, including easier promotion of a flow through development, staging, and production environments.</li> <li>Native <code>async</code> support.</li> <li>Out-of-the-box <code>pydantic</code> validation.</li> <li>Blocks allowing you to securely store UI-editable, type-checked configuration to external systems and an easy-to-use Key-Value Store. All those components are configurable in one place and provided as part of the open-source Prefect 2 product. In contrast, the concept of Secrets in Prefect 1 was much more narrow and only available in Prefect Cloud.  </li> <li>Notifications available in the open-source Prefect 2 version, as opposed to Cloud-only Automations in Prefect 1.  </li> <li>A first-class <code>subflows</code> concept: Prefect 1 only allowed the flow-of-flows orchestrator pattern. With Prefect 2 subflows, you gain a natural and intuitive way of organizing your flows into modular sub-components. For more details, see the following list of resources about subflows.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#orchestration-behind-the-api","title":"Orchestration behind the API","text":"<p>Apart from new features, Prefect 2 simplifies many usage patterns and provides a much more seamless onboarding experience.</p> <p>Every time you run a flow, whether it is tracked by the API server or ad-hoc through a Python script, it is on the same UI page for easier debugging and observability. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#code-as-workflows","title":"Code as workflows","text":"<p>With Prefect 2, your functions\u00a0are\u00a0your flows and tasks. Prefect 2 automatically detects your flows and tasks without the need to define a rigid DAG structure. While use of tasks is encouraged to provide you the maximum visibility into your workflows, they are no longer required. You can add a single <code>@flow</code> decorator to your main function to transform any Python script into a Prefect workflow.</p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#incremental-adoption","title":"Incremental adoption","text":"<p>The built-in SQLite database automatically tracks all your locally executed flow runs. As soon as you start a Prefect server and open the Prefect UI in your browser (or authenticate your CLI with your Prefect Cloud workspace), you can see all your locally executed flow runs in the UI. You don't even need to start an agent.</p> <p>Then, when you want to move toward scheduled, repeatable workflows, you can build a deployment and send it to the server by running a CLI command or a Python script. </p> <ul> <li>You can create a deployment to on remote infrastructure, where the run environment is defined by a reusable infrastructure block.</li> </ul>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#fewer-ambiguities","title":"Fewer ambiguities","text":"<p>Prefect 2 eliminates ambiguities in many ways. For example. there is no more confusion between Prefect Core and Prefect Server \u2014 Prefect 2 unifies those into a single open source product. This product is also much easier to deploy with no requirement for Docker or docker-compose.</p> <p>If you want to switch your backend to use Prefect Cloud for an easier production-level managed experience, Prefect profiles let you quickly connect to your workspace.</p> <p>In Prefect 1, there are several confusing ways you could implement <code>caching</code>. Prefect 2 resolves those ambiguities by providing a single <code>cache_key_fn</code> function paired with <code>cache_expiration</code>, allowing you to define arbitrary caching mechanisms \u2014 no more confusion about whether you need to use <code>cache_for</code>, <code>cache_validator</code>, or file-based caching using <code>targets</code>.</p> <p>For more details on how to configure caching, check out the following resources:</p> <ul> <li>Caching docs</li> <li>Time-based caching</li> <li>Input-based caching</li> </ul> <p>A similarly confusing concept in Prefect 1 was distinguishing between the functional and imperative APIs. This distinction caused ambiguities with respect to how to define state dependencies between tasks. Prefect 1 users were often unsure whether they should use the functional <code>upstream_tasks</code> keyword argument or the imperative methods such as <code>task.set_upstream()</code>, <code>task.set_downstream()</code>, or <code>flow.set_dependencies()</code>. In Prefect 2, there is only the functional API. </p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/migration-guide/#next-steps","title":"Next steps","text":"<p>We know migrations can be tough. We encourage you to take it step-by-step and experiment with the new features.</p> <p>To make the migration process easier for you:</p> <ul> <li>We provided a detailed FAQ section allowing you to find the right information you need to move your workflows to Prefect 2. If you still have some open questions, feel free to create a new topic describing your migration issue.</li> <li>We have dedicated resources in the Customer Success team to help you along your migration journey. Reach out to cs@prefect.io to discuss how we can help.  </li> <li>You can ask questions in our 20,000+ member Community Slack.</li> </ul> <p>Happy Engineering!</p>","tags":["migration","upgrading","best practices"],"boost":2},{"location":"guides/moving-data/","title":"Read and Write Data to and from Cloud Provider Storage","text":"<p>Writing data to cloud-based storage and reading data from that storage is a common task in data engineering. In this guide we'll learn how to use Prefect to move data to and from AWS, Azure, and GCP blob storage.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed</li> <li>Authenticated with Prefect Cloud (or self-hosted Prefect server instance)</li> <li>A cloud provider account (e.g. AWS)</li> </ul>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#install-relevant-prefect-integration-library","title":"Install relevant Prefect integration library","text":"<p>In the CLI, install the Prefect integration library for your cloud provider:</p> AWSAzureGCP <p>prefect-aws provides blocks for interacting with AWS services.</p> <p> <pre><code>pip install -U prefect-aws\n</code></pre> </p> <p>prefect-azure provides blocks for interacting with Azure services.</p> <p> <pre><code> pip install -U prefect-azure\n</code></pre> </p> <p>prefect-gcp provides blocks for interacting with GCP services.</p> <p> <pre><code> pip install -U prefect-gcp\n</code></pre> </p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#register-the-block-types","title":"Register the block types","text":"<p>Register the new block types with Prefect Cloud (or with your self-hosted Prefect server instance):</p> AWSAzureGCP <p> <pre><code>prefect block register -m prefect_aws  \n</code></pre> </p> <p> <pre><code>prefect block register -m prefect_azure \n</code></pre> </p> <p> <pre><code>prefect block register -m prefect_gcp\n</code></pre> </p> <p>We should see a message in the CLI that several block types were registered. If we check the UI, we should see the new block types listed.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-storage-bucket","title":"Create a storage bucket","text":"<p>Create a storage bucket in the cloud provider account. Ensure the bucket is publicly accessible or create a user or service account with the appropriate permissions to fetch and write data to the bucket.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-credentials-block","title":"Create a credentials block","text":"<p>If the bucket is private, there are several options to authenticate:</p> <ol> <li>At deployment runtime, ensure the runtime environment is authenticated.</li> <li>Create a block with configuration details and reference it when creating the storage block.</li> </ol> <p>If saving credential details in a block we can use a credentials block specific to the cloud provider or use a more generic secret block. We can create blocks via the UI or Python code. Below we'll use Python code to create a credentials block for our cloud provider.</p> <p>Credentials safety</p> <p>Reminder, don't store credential values in public locations such as public git platform repositories.  In the examples below we use environment variables to store credential values.</p> AWSAzureGCP <pre><code>import os\nfrom prefect_aws import AwsCredentials\n\nmy_aws_creds = AwsCredentials(\n    aws_access_key_id=\"123abc\",\n    aws_secret_access_key=os.environ.get(\"MY_AWS_SECRET_ACCESS_KEY\"),\n)\nmy_aws_creds.save(name=\"my-aws-creds-block\", overwrite=True)\n</code></pre> <pre><code>import os\nfrom prefect_azure import AzureBlobStorageCredentials\n\nmy_azure_creds = AzureBlobStorageCredentials(\n    connection_string=os.environ.get(\"MY_AZURE_CONNECTION_STRING\"),\n)\nmy_azure_creds.save(name=\"my-azure-creds-block\", overwrite=True)\n</code></pre> <p>We recommend specifying the service account key file contents as a string, rather than the path to the file, because that file might not be available in your production environments.</p> <pre><code>import os\nfrom prefect_gcp import GCPCredentials\n\nmy_gcp_creds = GCPCredentials(\n    service_account_info=os.environ.get(\"GCP_SERVICE_ACCOUNT_KEY_FILE_CONTENTS\"), \n)\nmy_gcp_creds.save(name=\"my-gcp-creds-block\", overwrite=True)\n</code></pre> <p>Run the code to create the block. We should see a message that the block was created.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#create-a-storage-block","title":"Create a storage block","text":"<p>Let's create a block for the chosen cloud provider using Python code or the UI. In this example we'll use Python code.</p> AWSAzureGCP <p>Note that the <code>S3Bucket</code> block is not the same as the <code>S3</code> block that ships with Prefect.  The <code>S3Bucket</code> block we use in this example is part of the <code>prefect-aws</code> library and provides additional functionality. </p> <p>We'll reference the credentials block created above.</p> <pre><code>from prefect_aws import S3Bucket\n\ns3bucket = S3Bucket.create(\n    bucket=\"my-bucket-name\",\n    credentials=\"my-aws-creds-block\"\n    )\ns3bucket.save(name=\"my-s3-bucket-block\", overwrite=True)\n</code></pre> <p>Note that the <code>AzureBlobStorageCredentials</code> block is not the same as the Azure block that ships with Prefect.  The <code>AzureBlobStorageCredentials</code> block we use in this example is part of the <code>prefect-azure</code> library and provides additional functionality. </p> <p>Azure blob storage doesn't require a separate block, the connection string used in the <code>AzureBlobStorageCredentials</code> block can encode the information needed. </p> <p>Note that the <code>GcsBucket</code> block is not the same as the <code>GCS</code> block that ships with Prefect.  The <code>GcsBucket</code> block is part of the <code>prefect-gcp</code> library and provides additional functionality.  We'll use it here.</p> <p>We'll reference the credentials block created above.</p> <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcsbucket = GcsBucket(\n    bucket=\"my-bucket-name\", \n    credentials=\"my-gcp-creds-block\"\n    )\ngcsbucket.save(name=\"my-gcs-bucket-block\", overwrite=True)\n</code></pre> <p>Run the code to create the block. We should see a message that the block was created.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#write-data","title":"Write data","text":"<p>Use your new block inside a flow to write data to your cloud provider.</p> AWSAzureGCP <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_aws.s3 import S3Bucket\n\n@flow()\ndef upload_to_s3():\n    \"\"\"Flow function to upload data\"\"\"\n    path = Path(\"my_path_to/my_file.parquet\")\n    aws_block = S3Bucket.load(\"my-s3-bucket-block\")\n    aws_block.upload_from_path(from_path=path, to_path=path)\n\nif __name__ == \"__main__\":\n    upload_to_s3()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_upload\n\n@flow\ndef upload_to_azure():\n    \"\"\"Flow function to upload data\"\"\"\n    blob_storage_credentials = AzureBlobStorageCredentials.load(\n        name=\"my-azure-creds-block\"\n    )\n\n    with open(\"my_path_to/my_file.parquet\", \"rb\") as f:\n        blob_storage_upload(\n            data=f.read(),\n            container=\"my_container\",\n            blob=\"my_path_to/my_file.parquet\",\n            blob_storage_credentials=blob_storage_credentials,\n        )\n\nif __name__ == \"__main__\":\n    upload_to_azure()\n</code></pre> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_gcp.cloud_storage import GcsBucket\n\n@flow()\ndef upload_to_gcs():\n    \"\"\"Flow function to upload data\"\"\"\n    path = Path(\"my_path_to/my_file.parquet\")\n    gcs_block = GcsBucket.load(\"my-gcs-bucket-block\")\n    gcs_block.upload_from_path(from_path=path, to_path=path)\n\nif __name__ == \"__main__\":\n    upload_to_gcs()\n</code></pre>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#read-data","title":"Read data","text":"<p>Use your block to read data from your cloud provider inside a flow.</p> AWSAzureGCP <pre><code>from prefect import flow\nfrom prefect_aws import S3Bucket\n\n@flow\ndef download_from_s3():\n    \"\"\"Flow function to download data\"\"\"\n    s3_block = S3Bucket.load(\"my-s3-bucket-block\")\n    s3_block.get_directory(\n        from_path=\"my_path_to/my_file.parquet\", \n        local_path=\"my_path_to/my_file.parquet\"\n    )\n\nif __name__ == \"__main__\":\n    download_from_s3()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef download_from_azure():\n    \"\"\"Flow function to download data\"\"\"\n    blob_storage_credentials = AzureBlobStorageCredentials.load(\n        name=\"my-azure-creds-block\"\n    )\n    blob_storage_download(\n        blob=\"my_path_to/my_file.parquet\",\n        container=\"my_container\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n\nif __name__ == \"__main__\":\n    download_from_azure()\n</code></pre> <pre><code>from prefect import flow\nfrom prefect_gcp.cloud_storage import GcsBucket\n\n@flow\ndef download_from_gcs():\n    gcs_block = GcsBucket.load(\"my-gcs-bucket-block\")\n    gcs_block.get_directory(\n        from_path=\"my_path_to/my_file.parquet\", \n        local_path=\"my_path_to/my_file.parquet\"\n    )\n\nif __name__ == \"__main__\":\n    download_from_gcs()\n</code></pre> <p>In this guide we've seen how to use Prefect to read data from and write data to cloud providers!</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/moving-data/#next-steps","title":"Next steps","text":"<p>Check out the <code>prefect-aws</code>, <code>prefect-azure</code>, and <code>prefect-gcp</code> docs to see additional methods for interacting with cloud storage providers. Each library also contains blocks for interacting with other cloud-provider services.</p>","tags":["data","storage","read data","write data","cloud providers","AWS","S3","Azure Storage","Azure Blob Storage","Azure","GCP","Google Cloud Storage","GCS","moving data"],"boost":2},{"location":"guides/prefect-deploy/","title":"Deploying Flows to Work Pools and Workers","text":"<p>In this guide, we will configure a deployment that uses a work pool for dynamically provisioned infrastructure.</p> <p>All Prefect flow runs are tracked by the API. The API does not require prior registration of flows. With Prefect, you can call a flow locally or on a remote environment and it will be tracked.</p> <p>A deployment turns your workflow into an application that can be interacted with and managed via the Prefect API. A deployment enables you to:</p> <ul> <li>Schedule flow runs.</li> <li>Specify event triggers for flow runs.</li> <li>Assign one or more tags to organize your deployments and flow runs. You can use those tags as filters in the Prefect UI.</li> <li>Assign custom parameter values for flow runs based on the deployment.</li> <li>Create ad-hoc flow runs from the API or Prefect UI.</li> <li>Upload flow files to a defined storage location for retrieval at run time.</li> </ul> <p>Deployments created with <code>.serve</code></p> <p>A deployment created with the Python <code>flow.serve</code> method or the <code>serve</code> function runs flows in a subprocess on the same machine where the deployment is created. It does not use a work pool or worker.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#work-pool-based-deployments","title":"Work pool-based deployments","text":"<p>A work pool-based deployment is useful when you want to dynamically scale the infrastructure where your flow code runs. Work pool-based deployments contain information about the infrastructure type and configuration for your workflow execution.</p> <p>Work pool-based deployment infrastructure options include the following:</p> <ul> <li>Process - runs flow in a subprocess. In most cases, you're better off using <code>.serve</code>.</li> <li>Docker - runs flows in an ephemeral Docker container.</li> <li>Kubernetes - runs flows as a Kubernetes Job.</li> <li>Serverless Cloud Provider options - runs flows in a Docker container in a serverless cloud provider environment, such as AWS ECS, Azure Container Instance, Google Cloud Run, or Vertex AI.</li> </ul> <p>The following diagram provides a high-level overview of the conceptual elements involved in defining a work-pool based deployment that is polled by a worker and executes a flow run based on that deployment.</p> <pre><code>%%{\n  init: {\n    'theme': 'base',\n    'themeVariables': {\n      'fontSize': '19px'\n    }\n  }\n}%%\n\nflowchart LR\n    F(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Flow Code&lt;/div&gt;\"):::yellow -.-&gt; A(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Deployment Definition&lt;/div&gt;\"):::gold\n    subgraph Server [\"&lt;div style='width: 150px; text-align: center; margin-top: 5px;'&gt;Prefect API&lt;/div&gt;\"]\n        D(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Deployment&lt;/div&gt;\"):::green\n    end\n    subgraph Remote Storage [\"&lt;div style='width: 160px; text-align: center; margin-top: 5px;'&gt;Remote Storage&lt;/div&gt;\"]\n        B(\"&lt;div style='margin: 5px 6px 5px 5px;'&gt;Flow&lt;/div&gt;\"):::yellow\n    end\n    subgraph Infrastructure [\"&lt;div style='width: 150px; text-align: center; margin-top: 5px;'&gt;Infrastructure&lt;/div&gt;\"]\n        G(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Flow Run&lt;/div&gt;\"):::blue\n    end\n\n    A --&gt; D\n    D --&gt; E(\"&lt;div style='margin: 5px 10px 5px 5px;'&gt;Worker&lt;/div&gt;\"):::red\n    B -.-&gt; E\n    A -.-&gt; B\n    E -.-&gt; G\n\n    classDef gold fill:goldenrod,stroke:goldenrod,stroke-width:4px,color:black\n    classDef yellow fill:gold,stroke:gold,stroke-width:4px,color:black\n    classDef gray fill:lightgray,stroke:lightgray,stroke-width:4px\n    classDef blue fill:blue,stroke:blue,stroke-width:4px,color:white\n    classDef green fill:green,stroke:green,stroke-width:4px,color:white\n    classDef red fill:red,stroke:red,stroke-width:4px,color:white\n    classDef dkgray fill:darkgray,stroke:darkgray,stroke-width:4px,color:white</code></pre> <p>The work pool types above require a worker to be running on your infrastructure to poll a work pool for scheduled flow runs.</p> <p>Additional work pool options available with Prefect Cloud</p> <p>Prefect Cloud offers other flavors of work pools that don't require a worker:</p> <ul> <li> <p>Push Work Pools - serverless cloud options that don't require a worker because Prefect Cloud submits them to your serverless cloud infrastructure on your behalf. Prefect can auto-provision your cloud infrastructure for you and set it up to use your work pool.</p> </li> <li> <p>Managed Execution Prefect Cloud submits and runs your deployment on serverless infrastructure. No cloud provider account required.</p> </li> </ul> <p>In this guide, we focus on deployments that require a worker.</p> <p>Work pool-based deployments that use a worker also allow you to assign a work queue name to prioritize work and allow you to limit concurrent runs at the work pool level.</p> <p>When creating a deployment that uses a work pool and worker, we must answer two basic questions:</p> <ul> <li>What instructions does a worker need to set up an execution environment for our flow? For example, a flow may have Python package requirements, unique Kubernetes settings, or Docker networking configuration.</li> <li>How should the flow code be accessed?</li> </ul> <p>The tutorial shows how you can create a deployment with a long-running process using <code>.serve</code> and how to move to a work-pool-based deployment setup with <code>.deploy</code>. See the discussion of when you might want to move to work-pool-based deployments there.</p> <p>Next, we'll explore how to use <code>.deploy</code> to create deployments with Python code. If you'd prefer to learn about using a YAML-based alternative for managing deployment configuration, skip to the later section on <code>prefect.yaml</code>.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#creating-work-pool-based-deployments-with-deploy","title":"Creating work pool-based deployments with <code>.deploy</code>","text":"","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#automatically-bake-your-code-into-a-docker-image","title":"Automatically bake your code into a Docker image","text":"<p>You can create a deployment from Python code by calling the <code>.deploy</code> method on a flow.</p> buy.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities\")\n\n\nif __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/my_image:my_image_tag\"\n    )\n</code></pre> <p>Make sure you have the work pool created in the Prefect Cloud workspace you are authenticated to or on your running self-hosted server instance. Then run the script to create a deployment (in future examples this step will be omitted for brevity):</p> <pre><code>python buy.py\n</code></pre> <p>You should see messages in your terminal that Docker is building your image. When the deployment build succeeds you will see helpful information in your terminal showing you how to start a worker for your deployment and how to run your deployment. Your deployment will be visible on the <code>Deployments</code> page in the UI.</p> <p>By default, <code>.deploy</code> will build a Docker image with your flow code baked into it and push the image to the Docker Hub registry specified in the <code>image</code> argument`.</p> <p>Authentication to Docker Hub</p> <p>You need your environment to be authenticated to your Docker registry to push an image to it.</p> <p>You can specify a registry other than Docker Hub by providing the full registry path in the <code>image</code> argument.</p> <p>Warning</p> <p>If building a Docker image, the environment in which you are creating the deployment needs to have Docker installed and running.</p> <p>To avoid pushing to a registry, set <code>push=False</code> in the <code>.deploy</code> method.</p> <pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/my_image:my_image_tag\",\n        push=False\n    )\n</code></pre> <p>To avoid building an image, set <code>build=False</code> in the <code>.deploy</code> method.</p> <pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_registry/no-build-image:1.0\",\n        build=False\n    )\n</code></pre> <p>The specified image will need to be available in your deployment's execution environment for your flow code to be accessible.</p> <p>Prefect generates a Dockerfile for you that will build an image based off of one of Prefect's published images. The generated Dockerfile will copy the current directory into the Docker image and install any dependencies listed in a <code>requirements.txt</code> file.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#automatically-build-a-custom-docker-image-with-a-local-dockerfile","title":"Automatically build a custom Docker image with a local Dockerfile","text":"<p>If you want to use a custom Dockerfile, you can specify the path to the Dockerfile with the <code>DeploymentImage</code> class:</p> custom_dockerfile.py<pre><code>from prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Selling securities\")\n\n\nif __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-custom-dockerfile-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=DeploymentImage(\n            name=\"my_image\",\n            tag=\"deploy-guide\",\n            dockerfile=\"Dockerfile\"\n    ),\n    push=False\n)\n</code></pre> <p>The <code>DeploymentImage</code> object allows for a great deal of image customization.</p> <p>For example, you can install a private Python package from GCP's artifact registry like this:</p> <p>Create a custom base Dockerfile.</p> <pre><code>FROM python:3.10\n\nARG AUTHED_ARTIFACT_REG_URL\nCOPY ./requirements.txt /requirements.txt\n\nRUN pip install --extra-index-url ${AUTHED_ARTIFACT_REG_URL} -r /requirements.txt\n</code></pre> <p>Create our deployment by leveraging the DeploymentImage class.</p> private-package.py<pre><code>from prefect import flow\nfrom prefect.deployments.runner import DeploymentImage\nfrom prefect.blocks.system import Secret\nfrom my_private_package import do_something_cool\n\n\n@flow(log_prints=True)\ndef my_flow():\n    do_something_cool()\n\n\nif __name__ == \"__main__\":\n    artifact_reg_url: Secret = Secret.load(\"artifact-reg-url\")\n\n    my_flow.deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"k8s-demo\",\n        image=DeploymentImage(\n            name=\"my-image\",\n            tag=\"test\",\n            dockerfile=\"Dockerfile\",\n            buildargs={\"AUTHED_ARTIFACT_REG_URL\": artifact_reg_url.get()},\n        ),\n    )\n</code></pre> <p>Note that we used a Prefect Secret block to load the URL configuration for the artifact registry above.</p> <p>See all the optional keyword arguments for the DeploymentImage class here.</p> <p>Default Docker namespace</p> <p>You can set the <code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE</code> setting to append a default Docker namespace to all images you build with <code>.deploy</code>. This is great if you use a private registry to store your images.</p> <p>To set a default Docker namespace for your current profile run:</p> <p> <pre><code>prefect config set PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE=&lt;docker-registry-url&gt;/&lt;organization-or-username&gt;\n</code></pre> </p> <p>Once set, you can omit the namespace from your image name when creating a deployment:</p> with_default_docker_namespace.py<pre><code>if __name__ == \"__main__\":\n    buy.deploy(\n        name=\"my-code-baked-into-an-image-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my_image:my_image_tag\"\n    )\n</code></pre> <p>The above code will build an image with the format <code>&lt;docker-registry-url&gt;/&lt;organization-or-username&gt;/my_image:my_image_tag</code> when <code>PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE</code> is set.</p> <p>While baking code into Docker images is a popular deployment option, many teams decide to store their workflow code in git-based storage, such as GitHub, Bitbucket, or Gitlab. Let's see how to do that next.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#store-your-code-in-git-based-cloud-storage","title":"Store your code in git-based cloud storage","text":"<p>If you don't specify an <code>image</code> argument for <code>.deploy</code>, then you need to specify where to pull the flow code from at runtime with the <code>from_source</code> method.</p> <p>Here's how we can pull our flow code from a GitHub repository.</p> git_storage.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        \"https://github.com/my_github_account/my_repo/my_file.git\",\n        entrypoint=\"flows/no-image.py:hello_world\",\n    ).deploy(\n        name=\"no-image-deployment\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>The <code>entrypoint</code> is the path to the file the flow is located in and the function name, separated by a colon.</p> <p>Alternatively, you could specify a git-based cloud storage URL for a Bitbucket or Gitlab repository.</p> <p>Note</p> <p>If you don't specify an image as part of your deployment creation, the image specified in the work pool will be used to run your flow.</p> <p>After creating a deployment you might change your flow code. Generally, you can just push your code to GitHub, without rebuilding your deployment. The exception is if something that the server needs to know about changes, such as the flow entrypoint parameters. Rerunning the Python script with <code>.deploy</code> will update your deployment on the server with the new flow code.</p> <p>If you need to provide additional configuration, such as specifying a private repository, you can provide a <code>GitRepository</code> object instead of a URL:</p> private_git_storage.py<pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect.blocks.system import Secret\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        branch=\"dev\",\n        credentials={\n            \"access_token\": Secret.load(\"github-access-token\")\n        }\n    ),\n    entrypoint=\"flows/no-image.py:hello_world\",\n    ).deploy(\n        name=\"private-git-storage-deployment\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Note the use of the Secret block to load the GitHub access token. Alternatively, you could provide a username and password to the <code>username</code> and <code>password</code> fields of the <code>credentials</code> argument.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#store-your-code-in-cloud-provider-storage","title":"Store your code in cloud provider storage","text":"<p>Another option for flow code storage is any fsspec-supported storage location, such as AWS S3, GCP GCS, or Azure Blob Storage.</p> <p>For example, you can pass the S3 bucket path to <code>source</code>.</p> s3_storage.py<pre><code>from prefect import flow\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=\"s3://my-bucket/my-folder\",\n        entrypoint=\"flows.py:my_flow\",\n    ).deploy(\n        name=\"deployment-from-aws-flow\",\n        work_pool_name=\"my_pool\",\n    )\n</code></pre> <p>In the example above your credentials will be auto-discovered from your deployment creation environment and credentials will need to be available in your runtime environment.</p> <p>If you need additional configuration for your cloud-based storage - for example, with a private S3 Bucket -  we recommend using a storage block. A storage block also ensures your credentials will be available in both your deployment creation environment and your execution environment.</p> <p>Here's an example that uses an <code>S3Bucket</code> block from the prefect-aws library.</p> s3_storage_auth.py<pre><code>from prefect import flow\nfrom prefect_aws.s3 import S3Bucket\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=S3Bucket.load(\"my-code-storage\"), entrypoint=\"my_file.py:my_flow\"\n    ).deploy(name=\"test-s3\", work_pool_name=\"my_pool\")\n</code></pre> <p>If you are familiar with the deployment creation mechanics with <code>.serve</code>, you will notice that <code>.deploy</code> is very similar. <code>.deploy</code> just requires a work pool name and has a number of parameters dealing with flow-code storage for Docker images.</p> <p>Unlike <code>.serve</code>, if you don't specify an image to use for your flow, you must to specify where to pull the flow code from at runtime with the <code>from_source</code> method, whereas <code>from_source</code> is optional with <code>.serve</code>.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#additional-configuration-with-deploy","title":"Additional configuration with <code>.deploy</code>","text":"<p>Our examples thus far have explored options for where to store flow code. Let's turn our attention to other deployment configuration options.</p> <p>To pass parameters to your flow, you can use the <code>parameters</code> argument in the <code>.deploy</code> method. Just pass in a dictionary of key-value pairs.</p> pass_params.py<pre><code>from prefect import flow\n\n@flow\ndef hello_world(name: str):\n    print(f\"Hello, {name}!\")\n\nif __name__ == \"__main__\":\n    hello_world.deploy(\n        name=\"pass-params-deployment\",\n        work_pool_name=\"my_pool\",\n        parameters=dict(name=\"Prefect\"),\n        image=\"my_registry/my_image:my_image_tag\",\n    )\n</code></pre> <p>The <code>job_variables</code> parameter allows you to fine-tune the infrastructure settings for a deployment. The values passed in override default values in the specified work pool's base job template.</p> <p>You can override environment variables, such as <code>image_pull_policy</code> and <code>image</code>, for a specific deployment with the <code>job_variables</code> argument.</p> job_var_image_pull.py<pre><code>if __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-deployment-never-pull\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"image_pull_policy\": \"Never\"},\n        image=\"my-image:my-tag\"\",\n        push=False\n    )\n</code></pre> <p>Similarly, you can override the environment variables specified in a work pool through the <code>job_variables</code> parameter:</p> job_var_env_vars.py<pre><code>if __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-deployment-never-pull\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"env\": {\"EXTRA_PIP_PACKAGES\": \"boto3\"} },\n        image=\"my-image:my-tag\"\",\n        push=False\n    )\n</code></pre> <p>The dictionary key \"EXTRA_PIP_PACKAGES\" denotes a special environment variable that Prefect will use to install additional Python packages at runtime. This approach is an alternative to building an image with a custom <code>requirements.txt</code> copied into it.</p> <p>For more information on overriding job variables see this guide.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#working-with-multiple-deployments-with-deploy","title":"Working with multiple deployments with <code>deploy</code>","text":"<p>You can create multiple deployments from one or more Python files that use <code>.deploy</code>. These deployments can be managed independently of one another, allowing you to deploy the same flow with different configurations in the same codebase.</p> <p>To create multiple work pool-based deployments at once you can use the <code>deploy</code> function, which is analogous to the <code>serve</code> function.</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities\")\n\n\nif __name__ == \"__main__\":\n    deploy(\n        buy.to_deployment(name=\"dev-deploy\", work_pool_name=\"my-dev-work-pool\"),\n        buy.to_deployment(name=\"prod-deploy\", work_pool_name=\"my-prod-work-pool\"),\n        image=\"my-registry/my-image:dev\",\n        push=False,\n    )\n</code></pre> <p>Note that in the example above we created two deployments from the same flow, but with different work pools. Alternatively, we could have created two deployments from different flows.</p> <pre><code>from prefect import deploy, flow\n\n@flow(log_prints=True)\ndef buy():\n    print(\"Buying securities.\")\n\n@flow(log_prints=True)\ndef sell():\n    print(\"Selling securities.\")\n\n\nif __name__ == \"__main__\":\n    deploy(\n        buy.to_deployment(name=\"buy-deploy\"),\n        sell.to_deployment(name=\"sell-deploy\"),\n        work_pool_name=\"my-dev-work-pool\"\n        image=\"my-registry/my-image:dev\",\n        push=False,\n    )\n</code></pre> <p>In the example above the code for both flows gets baked into the same image.</p> <p>We can specify that one or more flows should be pulled from a remote location at runtime by using the <code>from_source</code> method. Here's an example of deploying two flows, one defined locally and one defined in a remote repository:</p> <pre><code>from prefect import deploy, flow\n\n\n@flow(log_prints=True)\ndef local_flow():\n    print(\"I'm a flow!\")\n\nif __name__ == \"__main__\":\n    deploy(\n        local_flow.to_deployment(name=\"example-deploy-local-flow\"),\n        flow.from_source(\n            source=\"https://github.com/org/repo.git\",\n            entrypoint=\"flows.py:my_flow\",\n        ).to_deployment(\n            name=\"example-deploy-remote-flow\",\n        ),\n        work_pool_name=\"my-work-pool\",\n        image=\"my-registry/my-image:dev\",\n    )\n</code></pre> <p>You could pass any number of flows to the <code>deploy</code> function. This behavior is useful if using a monorepo approach to your workflows.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#creating-work-pool-based-deployments-with-prefectyaml","title":"Creating work pool-based deployments with prefect.yaml","text":"<p>The <code>prefect.yaml</code> file is a YAML file describing base settings for your deployments, procedural steps for preparing deployments, and instructions for preparing the execution environment for a deployment run.</p> <p>You can initialize your deployment configuration, which creates the <code>prefect.yaml</code> file, by running the CLI command <code>prefect init</code> in any directory or repository that stores your flow code.</p> <p>Deployment configuration recipes</p> <p>Prefect ships with many off-the-shelf \"recipes\" that allow you to get started with more structure within your <code>prefect.yaml</code> file; run <code>prefect init</code> to be prompted with available recipes in your installation. You can provide a recipe name in your initialization command with the <code>--recipe</code> flag, otherwise Prefect will attempt to guess an appropriate recipe based on the structure of your working directory (for example if you initialize within a <code>git</code> repository, Prefect will use the <code>git</code> recipe).</p> <p>The <code>prefect.yaml</code> file contains deployment configuration for deployments created from this file, default instructions for how to build and push any necessary code artifacts (such as Docker images), and default instructions for pulling a deployment in remote execution environments (e.g., cloning a GitHub repository).</p> <p>Any deployment configuration can be overridden via options available on the <code>prefect deploy</code> CLI command when creating a deployment.</p> <p><code>prefect.yaml</code> file flexibility</p> <p>In older versions of Prefect, this file had to be in the root of your repository or project directory and named <code>prefect.yaml</code>. Now this file can be located in a directory outside the project or a subdirectory inside the project. It can be named differently, provided the filename ends in <code>.yaml</code>. You can even have multiple <code>prefect.yaml</code> files with the same name in different directories. By default, <code>prefect deploy</code> will use a <code>prefect.yaml</code> file in the project's root directory. To use a custom deployment configuration file, supply the new  <code>--prefect-file</code> CLI argument when running the <code>deploy</code> command from the root of your project directory:</p> <p><code>prefect deploy --prefect-file path/to/my_file.yaml</code></p> <p>The base structure for <code>prefect.yaml</code> is as follows:</p> <pre><code># generic metadata\nprefect-version: null\nname: null\n\n# preparation steps\nbuild: null\npush: null\n\n# runtime steps\npull: null\n\n# deployment configurations\ndeployments:\n- # base metadata\n    name: null\n    version: null\n    tags: []\n    description: null\n    schedule: null\n\n    # flow-specific fields\n    entrypoint: null\n    parameters: {}\n\n    # infra-specific fields\n    work_pool:\n    name: null\n    work_queue_name: null\n    job_variables: {}\n</code></pre> <p>The metadata fields are always pre-populated for you. These fields are for bookkeeping purposes only.  The other sections are pre-populated based on recipe; if no recipe is provided, Prefect will attempt to guess an appropriate one based on local configuration.</p> <p>You can create deployments via the CLI command <code>prefect deploy</code> without ever needing to alter the <code>deployments</code> section of your <code>prefect.yaml</code> file \u2014 the <code>prefect deploy</code> command will help in deployment creation via interactive prompts. The <code>prefect.yaml</code> file facilitates version-controlling your deployment configuration and managing multiple deployments.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-actions","title":"Deployment actions","text":"<p>Deployment actions defined in your <code>prefect.yaml</code> file control the lifecycle of the creation and execution of your deployments. The three actions available are <code>build</code>, <code>push</code>, and <code>pull</code>. <code>pull</code> is the only required deployment action \u2014 it is used to define how Prefect will pull your deployment in remote execution environments.</p> <p>Each action is defined as a list of steps that are executing in sequence.</p> <p>Each step has the following format:</p> <pre><code>section:\n- prefect_package.path.to.importable.step:\n    id: \"step-id\" # optional\n    requires: \"pip-installable-package-spec\" # optional\n    kwarg1: value\n    kwarg2: more-values\n</code></pre> <p>Every step can optionally provide a <code>requires</code> field that Prefect will use to auto-install in the event that the step cannot be found in the current environment. Each step can also specify an <code>id</code> for the step which is used when referencing step outputs in later steps. The additional fields map directly onto Python keyword arguments to the step function. Within a given section, steps always run in the order that they are provided within the <code>prefect.yaml</code> file.</p> <p>Deployment Instruction Overrides</p> <p><code>build</code>, <code>push</code>, and <code>pull</code> sections can all be overridden on a per-deployment basis by defining <code>build</code>, <code>push</code>, and <code>pull</code> fields within a deployment definition in the <code>prefect.yaml</code> file.</p> <p>The <code>prefect deploy</code> command will use any <code>build</code>, <code>push</code>, or <code>pull</code> instructions provided in a deployment's definition in the <code>prefect.yaml</code> file.</p> <p>This capability is useful with multiple deployments that require different deployment instructions.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-build-action","title":"The build action","text":"<p>The build section of <code>prefect.yaml</code> is where any necessary side effects for running your deployments are built - the most common type of side effect produced here is a Docker image. If you initialize with the docker recipe, you will be prompted to provide required information, such as image name and tag:</p> <pre><code>prefect init --recipe docker\n&gt;&gt; image_name: &lt; insert image name here &gt;\n&gt;&gt; tag: &lt; insert image tag here &gt;\n</code></pre> <p>Use <code>--field</code> to avoid the interactive experience</p> <p>We recommend that you only initialize a recipe when you are first creating your deployment structure, and afterwards store your configuration files within version control. However, sometimes you may need to initialize programmatically and avoid the interactive prompts. To do so, provide all required fields for your recipe using the <code>--field</code> flag:</p> <p> <pre><code>prefect init --recipe docker \\\n    --field image_name=my-repo/my-image \\\n    --field tag=my-tag\n</code></pre> </p> <pre><code>build:\n- prefect_docker.deployments.steps.build_docker_image:\n    requires: prefect-docker&gt;=0.3.0\n    image_name: my-repo/my-image\n    tag: my-tag\n    dockerfile: auto\n    push: true\n</code></pre> <p>Once you've confirmed that these fields are set to their desired values, this step will automatically build a Docker image with the provided name and tag and push it to the repository referenced by the image name. As the <code>prefect-docker</code> package documentation notes, this step produces a few fields that can optionally be used in future steps or within <code>prefect.yaml</code> as template values. It is best practice to use <code>{{ image }}</code> within <code>prefect.yaml</code> (specifically the work pool's job variables section) so that you don't risk having your build step and deployment specification get out of sync with hardcoded values.  </p> <p>Note</p> <p>Note that in the build step example above, we relied on the <code>prefect-docker</code> package; in cases that deal with external services, additional packages are often required and will be auto-installed for you.</p> <p>Pass output to downstream steps</p> <p>Each deployment action can be composed of multiple steps. For example, if you wanted to build a Docker image tagged with the current commit hash, you could use the <code>run_shell_script</code> step and feed the output into the <code>build_docker_image</code> step:</p> <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: my-image\n        image_tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre> <p>Note that the <code>id</code> field is used in the <code>run_shell_script</code> step so that its output can be referenced in the next step.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-push-action","title":"The push action","text":"<p>The push section is most critical for situations in which code is not stored on persistent filesystems or in version control.  In this scenario, code is often pushed and pulled from a Cloud storage bucket of some kind (e.g., S3, GCS, Azure Blobs, etc.).  The push section allows users to specify and customize the logic for pushing this code repository to arbitrary remote locations.</p> <p>For example, a user wishing to store their code in an S3 bucket and rely on default worker settings for its runtime environment could use the <code>s3</code> recipe:</p> <pre><code>prefect init --recipe s3\n&gt;&gt; bucket: &lt; insert bucket name here &gt;\n</code></pre> <p>Inspecting our newly created <code>prefect.yaml</code> file we find that the <code>push</code> and <code>pull</code> sections have been templated out for us as follows:</p> <pre><code>push:\n- prefect_aws.deployments.steps.push_to_s3:\n    id: push-code\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: project-name\n    credentials: null\n\npull:\n- prefect_aws.deployments.steps.pull_from_s3:\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: \"{{ push-code.folder }}\"\n    credentials: null\n</code></pre> <p>The bucket has been populated with our provided value (which also could have been provided with the <code>--field</code> flag); note that the <code>folder</code> property of the <code>push</code> step is a template - the <code>pull_from_s3</code> step outputs both a <code>bucket</code> value as well as a <code>folder</code> value that can be used to template downstream steps.  Doing this helps you keep your steps consistent across edits.</p> <p>As discussed above, if you are using blocks, the credentials section can be templated with a block reference for secure and dynamic credentials access:</p> <pre><code>push:\n- prefect_aws.deployments.steps.push_to_s3:\n    requires: prefect-aws&gt;=0.3.0\n    bucket: my-bucket\n    folder: project-name\n    credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre> <p>Anytime you run <code>prefect deploy</code>, this <code>push</code> section will be executed upon successful completion of your <code>build</code> section. For more information on the mechanics of steps, see below.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#the-pull-action","title":"The pull action","text":"<p>The pull section is the most important section within the <code>prefect.yaml</code> file. It contains instructions for preparing your flows for a deployment run. These instructions will be executed each time a deployment created within this folder is run via a worker.</p> <p>There are three main types of steps that typically show up in a <code>pull</code> section:</p> <ul> <li><code>set_working_directory</code>: this step simply sets the working directory for the process prior to importing your flow</li> <li><code>git_clone</code>: this step clones the provided repository on the provided branch</li> <li><code>pull_from_{cloud}</code>: this step pulls the working directory from a Cloud storage location (e.g., S3)</li> </ul> <p>Use block and variable references</p> <p>All block and variable references within your pull step will remain unresolved until runtime and will be pulled each time your deployment is run. This allows you to avoid storing sensitive information insecurely; it also allows you to manage certain types of configuration from the API and UI without having to rebuild your deployment every time.</p> <p>Below is an example of how to use an existing <code>GitHubCredentials</code> block to clone a private GitHub repository:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-credentials }}\"\n</code></pre> <p>Alternatively, you can specify a <code>BitBucketCredentials</code> or <code>GitLabCredentials</code> block to clone from Bitbucket or GitLab. In lieu of a credentials block, you can also provide a GitHub, GitLab, or Bitbucket token directly to the 'access_token` field. You can use a Secret block to do this securely:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://bitbucket.org/org/repo.git\n        access_token: \"{{ prefect.blocks.secret.bitbucket-token }}\"\n</code></pre>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#utility-steps","title":"Utility steps","text":"<p>Utility steps can be used within a build, push, or pull action to assist in managing the deployment lifecycle:</p> <ul> <li><code>run_shell_script</code> allows for the execution of one or more shell commands in a subprocess, and returns the standard output and standard error of the script. This step is useful for scripts that require execution in a specific environment, or those which have specific input and output requirements.</li> </ul> <p>Here is an example of retrieving the short Git commit hash of the current repository to use as a Docker image tag:</p> <pre><code>build:\n    - prefect.deployments.steps.run_shell_script:\n        id: get-commit-hash\n        script: git rev-parse --short HEAD\n        stream_output: false\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker&gt;=0.3.0\n        image_name: my-image\n        tag: \"{{ get-commit-hash.stdout }}\"\n        dockerfile: auto\n</code></pre> <p>Provided environment variables are not expanded by default</p> <p>To expand environment variables in your shell script, set <code>expand_env_vars: true</code> in your <code>run_shell_script</code> step. For example:</p> <pre><code>- prefect.deployments.steps.run_shell_script:\n    id: get-user\n    script: echo $USER\n    stream_output: true\n    expand_env_vars: true\n</code></pre> <p>Without <code>expand_env_vars: true</code>, the above step would return a literal string <code>$USER</code> instead of the current user.</p> <ul> <li><code>pip_install_requirements</code> installs dependencies from a <code>requirements.txt</code> file within a specified directory.</li> </ul> <p>Below is an example of installing dependencies from a <code>requirements.txt</code> file after cloning:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        id: clone-step  # needed in order to be referenced in subsequent steps\n        repository: https://github.com/org/repo.git\n    - prefect.deployments.steps.pip_install_requirements:\n        directory: {{ clone-step.directory }}  # `clone-step` is a user-provided `id` field\n        requirements_file: requirements.txt\n</code></pre> <p>Below is an example that retrieves an access token from a 3rd party Key Vault and uses it in a private clone step:</p> <pre><code>pull:\n- prefect.deployments.steps.run_shell_script:\n    id: get-access-token\n    script: az keyvault secret show --name &lt;secret name&gt; --vault-name &lt;secret vault&gt; --query \"value\" --output tsv\n    stream_output: false\n- prefect.deployments.steps.git_clone:\n    repository: https://bitbucket.org/samples/deployments.git\n    branch: master\n    access_token: \"{{ get-access-token.stdout }}\"\n</code></pre> <p>You can also run custom steps by packaging them. In the example below, <code>retrieve_secrets</code> is a custom python module that has been packaged into the default working directory of a Docker image (which is /opt/prefect by default). <code>main</code> is the function entry point, which returns an access token (e.g. <code>return {\"access_token\": access_token}</code>) like the preceding example, but utilizing the Azure Python SDK for retrieval.</p> <pre><code>- retrieve_secrets.main:\n    id: get-access-token\n- prefect.deployments.steps.git_clone:\n    repository: https://bitbucket.org/samples/deployments.git\n    branch: master\n    access_token: '{{ get-access-token.access_token }}'\n</code></pre>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#templating-options","title":"Templating options","text":"<p>Values that you place within your <code>prefect.yaml</code> file can reference dynamic values in several different ways:</p> <ul> <li>step outputs: every step of both <code>build</code> and <code>push</code> produce named fields such as <code>image_name</code>; you can reference these fields within <code>prefect.yaml</code> and <code>prefect deploy</code> will populate them with each call.  References must be enclosed in double brackets and be of the form <code>\"{{ field_name }}\"</code></li> <li>blocks: Prefect blocks can also be referenced with the special syntax <code>{{ prefect.blocks.block_type.block_slug }}</code>. It is highly recommended that you use block references for any sensitive information (such as a GitHub access token or any credentials) to avoid hardcoding these values in plaintext</li> <li>variables: Prefect variables can also be referenced with the special syntax <code>{{ prefect.variables.variable_name }}</code>. Variables can be used to reference non-sensitive, reusable pieces of information such as a default image name or a default work pool name.</li> <li>environment variables: you can also reference environment variables with the special syntax <code>{{ $MY_ENV_VAR }}</code>. This is especially useful for referencing environment variables that are set at runtime.</li> </ul> <p>As an example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.3.0\n    image_name: my-repo/my-image\n    tag: my-tag\n    dockerfile: auto\n    push: true\n\ndeployments:\n- # base metadata\n    name: null\n    version: \"{{ build-image.tag }}\"\n    tags:\n        - \"{{ $my_deployment_tag }}\"\n        - \"{{ prefect.variables.some_common_tag }}\"\n    description: null\n    schedule: null\n\n    # flow-specific fields\n    entrypoint: null\n    parameters: {}\n\n    # infra-specific fields\n    work_pool:\n        name: \"my-k8s-work-pool\"\n        work_queue_name: null\n        job_variables:\n            image: \"{{ build-image.image }}\"\n            cluster_config: \"{{ prefect.blocks.kubernetes-cluster-config.my-favorite-config }}\"\n</code></pre> <p>So long as our <code>build</code> steps produce fields called <code>image_name</code> and <code>tag</code>, every time we deploy a new version of our deployment, the <code>{{ build-image.image }}</code> variable will be dynamically populated with the relevant values.</p> <p>Docker step</p> <p>The most commonly used build step is <code>prefect_docker.deployments.steps.build_docker_image</code> which produces both the <code>image_name</code> and <code>tag</code> fields.</p> <p>For an example, check out the deployments tutorial.</p> <p>A <code>prefect.yaml</code> file can have multiple deployment configurations that control the behavior of several deployments. These deployments can be managed independently of one another, allowing you to deploy the same flow with different configurations in the same codebase.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#working-with-multiple-deployments-with-prefectyaml","title":"Working with multiple deployments with prefect.yaml","text":"<p>Prefect supports multiple deployment declarations within the <code>prefect.yaml</code> file. This method of declaring multiple deployments allows the configuration for all deployments to be version controlled and deployed with a single command.</p> <p>New deployment declarations can be added to the <code>prefect.yaml</code> file by adding a new entry to the <code>deployments</code> list. Each deployment declaration must have a unique <code>name</code> field which is used to select deployment declarations when using the <code>prefect deploy</code> command.</p> <p>Warning</p> <p>When using a <code>prefect.yaml</code> file that is in another directory or differently named, remember that the value for the deployment <code>entrypoint</code> must be relative to the root directory of the project.  </p> <p>For example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build: ...\npush: ...\npull: ...\n\ndeployments:\n- name: deployment-1\n    entrypoint: flows/hello.py:my_flow\n    parameters:\n        number: 42,\n        message: Don't panic!\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: primary-queue\n\n- name: deployment-2\n    entrypoint: flows/goodbye.py:my_other_flow\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: secondary-queue\n\n- name: deployment-3\n    entrypoint: flows/hello.py:yet_another_flow\n    work_pool:\n        name: my-docker-work-pool\n        work_queue_name: tertiary-queue\n</code></pre> <p>This file has three deployment declarations, each referencing a different flow. Each deployment declaration has a unique <code>name</code> field and can be deployed individually by using the <code>--name</code> flag when deploying.</p> <p>For example, to deploy <code>deployment-1</code> you would run:</p> <pre><code>prefect deploy --name deployment-1\n</code></pre> <p>To deploy multiple deployments you can provide multiple <code>--name</code> flags:</p> <pre><code>prefect deploy --name deployment-1 --name deployment-2\n</code></pre> <p>To deploy multiple deployments with the same name, you can prefix the deployment name with its flow name:</p> <pre><code>prefect deploy --name my_flow/deployment-1 --name my_other_flow/deployment-1\n</code></pre> <p>To deploy all deployments you can use the <code>--all</code> flag:</p> <pre><code>prefect deploy --all\n</code></pre> <p>To deploy deployments that match a pattern you can run:</p> <pre><code>prefect deploy -n my-flow/* -n *dev/my-deployment -n dep*prod\n</code></pre> <p>The above command will deploy all deployments from the flow <code>my-flow</code>, all flows ending in <code>dev</code> with a deployment named <code>my-deployment</code>, and all deployments starting with <code>dep</code> and ending in <code>prod</code>.</p> <p>CLI Options When Deploying Multiple Deployments</p> <p>When deploying more than one deployment with a single <code>prefect deploy</code> command, any additional attributes provided via the CLI will be ignored.</p> <p>To provide overrides to a deployment via the CLI, you must deploy that deployment individually.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#reusing-configuration-across-deployments","title":"Reusing configuration across deployments","text":"<p>Because a <code>prefect.yaml</code> file is a standard YAML file, you can use YAML aliases to reuse configuration across deployments.</p> <p>This functionality is useful when multiple deployments need to share the work pool configuration, deployment actions, or other configurations.</p> <p>You can declare a YAML alias by using the <code>&amp;{alias_name}</code> syntax and insert that alias elsewhere in the file with the <code>*{alias_name}</code> syntax. When aliasing YAML maps, you can also override specific fields of the aliased map by using the <code>&lt;&lt;: *{alias_name}</code> syntax and adding additional fields below.</p> <p>We recommend adding a <code>definitions</code> section to your <code>prefect.yaml</code> file at the same level as the <code>deployments</code> section to store your aliases.</p> <p>For example, consider the following <code>prefect.yaml</code> file:</p> <pre><code>build: ...\npush: ...\npull: ...\n\ndefinitions:\n    work_pools:\n        my_docker_work_pool: &amp;my_docker_work_pool\n            name: my-docker-work-pool\n            work_queue_name: default\n            job_variables:\n                image: \"{{ build-image.image }}\"\n    schedules:\n        every_ten_minutes: &amp;every_10_minutes\n            interval: 600\n    actions:\n        docker_build: &amp;docker_build\n            - prefect_docker.deployments.steps.build_docker_image: &amp;docker_build_config\n                id: build-image\n                requires: prefect-docker&gt;=0.3.0\n                image_name: my-example-image\n                tag: dev\n                dockerfile: auto\n                push: true\n\ndeployments:\n- name: deployment-1\n    entrypoint: flows/hello.py:my_flow\n    schedule: *every_10_minutes\n    parameters:\n        number: 42,\n        message: Don't panic!\n    work_pool: *my_docker_work_pool\n    build: *docker_build # Uses the full docker_build action with no overrides\n\n- name: deployment-2\n    entrypoint: flows/goodbye.py:my_other_flow\n    work_pool: *my_docker_work_pool\n    build:\n        - prefect_docker.deployments.steps.build_docker_image:\n            &lt;&lt;: *docker_build_config # Uses the docker_build_config alias and overrides the dockerfile field\n            dockerfile: Dockerfile.custom\n\n- name: deployment-3\n    entrypoint: flows/hello.py:yet_another_flow\n    schedule: *every_10_minutes\n    work_pool:\n        name: my-process-work-pool\n        work_queue_name: primary-queue\n</code></pre> <p>In the above example, we are using YAML aliases to reuse work pool, schedule, and build configuration across multiple deployments:</p> <ul> <li><code>deployment-1</code> and <code>deployment-2</code> are using the same work pool configuration</li> <li><code>deployment-1</code> and <code>deployment-3</code> are using the same schedule</li> <li><code>deployment-1</code> and <code>deployment-2</code> are using the same build deployment action, but <code>deployment-2</code> is overriding the <code>dockerfile</code> field to use a custom Dockerfile</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-declaration-reference","title":"Deployment declaration reference","text":"","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-fields","title":"Deployment fields","text":"<p>Below are fields that can be added to each deployment declaration.</p> Property Description <code>name</code> The name to give to the created deployment. Used with the <code>prefect deploy</code> command to create or update specific deployments. <code>version</code> An optional version for the deployment. <code>tags</code> A list of strings to assign to the deployment as tags. <code>description</code> An optional description for the deployment. <code>schedule</code> An optional schedule to assign to the deployment. Fields for this section are documented in the Schedule Fields section. <code>triggers</code> An optional array of triggers to assign to the deployment <code>entrypoint</code> Required path to the <code>.py</code> file containing the flow you want to deploy (relative to the root directory of your development folder) combined with the name of the flow function. Should be in the format <code>path/to/file.py:flow_function_name</code>. <code>parameters</code> Optional default values to provide for the parameters of the deployed flow. Should be an object with key/value pairs. <code>enforce_parameter_schema</code> Boolean flag that determines whether the API should validate the parameters passed to a flow run against the parameter schema generated for the deployed flow. <code>work_pool</code> Information on where to schedule flow runs for the deployment. Fields for this section are documented in the Work Pool Fields section.","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#schedule-fields","title":"Schedule fields","text":"<p>Below are fields that can be added to a deployment declaration's <code>schedule</code> section.</p> Property Description <code>interval</code> Number of seconds indicating the time between flow runs. Cannot be used in conjunction with <code>cron</code> or <code>rrule</code>. <code>anchor_date</code> Datetime string indicating the starting or \"anchor\" date to begin the schedule. If no <code>anchor_date</code> is supplied, the current UTC time is used. Can only be used with <code>interval</code>. <code>timezone</code> String name of a time zone, used to enforce localization behaviors like DST boundaries. See the IANA Time Zone Database for valid time zones. <code>cron</code> A valid cron string. Cannot be used in conjunction with <code>interval</code> or <code>rrule</code>. <code>day_or</code> Boolean indicating how croniter handles day and day_of_week entries. Must be used with <code>cron</code>. Defaults to <code>True</code>. <code>rrule</code> String representation of an RRule schedule. See the <code>rrulestr</code> examples for syntax. Cannot be used in conjunction with <code>interval</code> or <code>cron</code>. <p>For more information about schedules, see the Schedules concept doc.</p>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#work-pool-fields","title":"Work pool fields","text":"<p>Below are fields that can be added to a deployment declaration's <code>work_pool</code> section.</p> Property Description <code>name</code> The name of the work pool to schedule flow runs in for the deployment. <code>work_queue_name</code> The name of the work queue within the specified work pool to schedule flow runs in for the deployment. If not provided, the default queue for the specified work pool will be used. <code>job_variables</code> Values used to override the default values in the specified work pool's base job template. Maps directly to a created deployments <code>infra_overrides</code> attribute.","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#deployment-mechanics","title":"Deployment mechanics","text":"<p>Anytime you run <code>prefect deploy</code> in a directory that contains a <code>prefect.yaml</code> file, the following actions are taken in order:</p> <ul> <li>The <code>prefect.yaml</code> file is loaded. First, the <code>build</code> section is loaded and all variable and block references are resolved. The steps are then run in the order provided.</li> <li>Next, the <code>push</code> section is loaded and all variable and block references are resolved; the steps within this section are then run in the order provided</li> <li>Next, the <code>pull</code> section is templated with any step outputs but is not run.  Note that block references are not hydrated for security purposes - block references are always resolved at runtime</li> <li>Next, all variable and block references are resolved with the deployment declaration.  All flags provided via the <code>prefect deploy</code> CLI are then overlaid on the values loaded from the file.</li> <li>The final step occurs when the fully realized deployment specification is registered with the Prefect API</li> </ul> <p>Deployment Instruction Overrides</p> <p>The <code>build</code>, <code>push</code>, and <code>pull</code> sections in deployment definitions take precedence over the corresponding sections above them in <code>prefect.yaml</code>.</p> <p>Each time a step is run, the following actions are taken in order:</p> <ul> <li>The step's inputs and block / variable references are resolved (see the templating documentation above for more details).</li> <li>The step's function is imported; if it cannot be found, the special <code>requires</code> keyword is used to install the necessary packages</li> <li>The step's function is called with the resolved inputs.</li> <li>The step's output is returned and used to resolve inputs for subsequent steps.</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/prefect-deploy/#next-steps","title":"Next steps","text":"<p>Now that you are familiar with creating deployments, you may want to explore infrastructure options for running your deployments:</p> <ul> <li>Managed work pools</li> <li>Push work pools</li> <li>Kubernetes work pools</li> <li>Serverless hybrid work pools</li> </ul>","tags":["orchestration","deploy","CLI","flow runs","deployments","schedules","triggers","prefect.yaml","infrastructure","storage","work pool","worker"],"boost":2},{"location":"guides/runtime-context/","title":"Get Information about the Runtime Context","text":"<p>Prefect tracks information about the current flow or task run with a run context. The run context can be thought of as a global variable that allows the Prefect engine to determine relationships between your runs, such as which flow your task was called from.</p> <p>The run context itself contains many internal objects used by Prefect to manage execution of your run and is only available in specific situations. For this reason, we expose a simple interface that only includes the items you care about and dynamically retrieves additional information when necessary. We call this the \"runtime context\" as it contains information that can be accessed only when a run is happening.</p> <p>Mock values via environment variable</p> <p>Oftentimes, you may want to mock certain values for testing purposes.  For example, by manually setting an ID or a scheduled start time to ensure your code is functioning properly.  Starting in version <code>2.10.3</code>, you can mock values in runtime via environment variable using the schema <code>PREFECT__RUNTIME__{SUBMODULE}__{KEY_NAME}=value</code>:  <pre><code>$ export PREFECT__RUNTIME__TASK_RUN__FAKE_KEY='foo'\n$ python -c 'from prefect.runtime import task_run; print(task_run.fake_key)' # \"foo\"\n</code></pre> </p> <p>If the environment variable mocks an existing runtime attribute, the value is cast to the same type. This works for runtime attributes of basic types (<code>bool</code>, <code>int</code>, <code>float</code> and <code>str</code>) and <code>pendulum.DateTime</code>. For complex types like <code>list</code> or <code>dict</code>, we suggest mocking them using monkeypatch or a similar tool.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/runtime-context/#accessing-runtime-information","title":"Accessing runtime information","text":"<p>The <code>prefect.runtime</code> module is the home for all runtime context access. Each major runtime concept has its own submodule:</p> <ul> <li><code>deployment</code>: Access information about the deployment for the current run</li> <li><code>flow_run</code>: Access information about the current flow run</li> <li><code>task_run</code>: Access information about the current task run</li> </ul> <p>For example:</p> my_runtime_info.py<pre><code>from prefect import flow, task\nfrom prefect import runtime\n\n@flow(log_prints=True)\ndef my_flow(x):\n    print(\"My name is\", runtime.flow_run.name)\n    print(\"I belong to deployment\", runtime.deployment.name)\n    my_task(2)\n\n@task\ndef my_task(y):\n    print(\"My name is\", runtime.task_run.name)\n    print(\"Flow run parameters:\", runtime.flow_run.parameters)\n\nmy_flow(1)\n</code></pre> <p>Running this file will produce output similar to the following:</p> <pre><code>10:08:02.948 | INFO    | prefect.engine - Created flow run 'solid-gibbon' for flow 'my-flow'\n10:08:03.555 | INFO    | Flow run 'solid-gibbon' - My name is solid-gibbon\n10:08:03.558 | INFO    | Flow run 'solid-gibbon' - I belong to deployment None\n10:08:03.703 | INFO    | Flow run 'solid-gibbon' - Created task run 'my_task-0' for task 'my_task'\n10:08:03.704 | INFO    | Flow run 'solid-gibbon' - Executing 'my_task-0' immediately...\n10:08:04.006 | INFO    | Task run 'my_task-0' - My name is my_task-0\n10:08:04.007 | INFO    | Task run 'my_task-0' - Flow run parameters: {'x': 1}\n10:08:04.105 | INFO    | Task run 'my_task-0' - Finished in state Completed()\n10:08:04.968 | INFO    | Flow run 'solid-gibbon' - Finished in state Completed('All states completed.')\n</code></pre> <p>Above, we demonstrated access to information about the current flow run, task run, and deployment. When run without a deployment (via <code>python my_runtime_info.py</code>), you should see <code>\"I belong to deployment None\"</code> logged. When information is not available, the runtime will always return an empty value. Because this flow was run outside of a deployment, there is no deployment data. If this flow was run as part of a deployment, we'd see the name of the deployment instead.</p> <p>See the runtime API reference for a full list of available attributes.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/runtime-context/#accessing-the-run-context-directly","title":"Accessing the run context directly","text":"<p>The current run context can be accessed with <code>prefect.context.get_run_context()</code>. This function will raise an exception if no run context is available, meaning you are not in a flow or task run. If a task run context is available, it will be returned even if a flow run context is available.</p> <p>Alternatively, you can access the flow run or task run context explicitly. This will, for example, allow you to access the flow run context from a task run.</p> <p>Note that we do not send the flow run context to distributed task workers because the context is costly to serialize and deserialize.</p> <pre><code>from prefect.context import FlowRunContext, TaskRunContext\n\nflow_run_ctx = FlowRunContext.get()\ntask_run_ctx = TaskRunContext.get()\n</code></pre> <p>Unlike <code>get_run_context</code>, these method calls will not raise an error if the context is not available. Instead, they will return <code>None</code>.</p>","tags":["flows","subflows","tasks","deployments"],"boost":2},{"location":"guides/secrets/","title":"Third-party Secrets: Connect to services without storing credentials in blocks","text":"<p>Credentials blocks and secret blocks are popular ways to store and retrieve sensitive information for connecting to third-party services.</p> <p>In Prefect Cloud, these block values are stored in encrypted format. Organizations whose security policies make such storage infeasible can still use Prefect to connect to third-party services securely.</p> <p>Any sensitive information that is not stored in a block can be read from the environment.</p> <p>For example, to find AWS credentials for authentication, any attributes not provided to an AWS Credentials block are sourced at runtime in the order shown in the Boto3 docs. Prefect-aws creates the session object using the values in the block and then, any missing values follow the sequence in the Boto3 docs.</p> <p>Prefect-gcp and prefect-azure follow similar patterns.</p> <p>In the example below, we interact with a Snowflake database using credentials stored in AWS Secrets Manager. This example can be generalized to other third party services that require credentials.</p>"},{"location":"guides/secrets/#prerequisites","title":"Prerequisites","text":"<ol> <li>Prefect installed.</li> <li>CLI authenticated to your Prefect Cloud account.</li> <li>Snowflake account.</li> <li>AWS account.</li> </ol>"},{"location":"guides/secrets/#steps","title":"Steps","text":"<ol> <li>Install <code>prefect-aws</code> and <code>prefect-snowflake</code> integration libraries.</li> <li>Store Snowflake password in AWS Secrets Manager.</li> <li>Create <code>AwsSecret</code> block to access the Snowflake password.</li> <li>Create <code>AwsCredentials</code> block for authentication.</li> <li>Ensure the compute environment has access to AWS credentials that are authorized to access the secret in AWS.</li> <li>Create and use <code>SnowflakeCredentials</code> and <code>SnowflakeConnector</code> blocks in Python code to interact with Snowflake.</li> </ol>"},{"location":"guides/secrets/#install-prefect-aws-and-prefect-snowflake-libraries","title":"Install <code>prefect-aws</code> and <code>prefect-snowflake</code> libraries","text":"<p>The following code will install and upgrade the necessary libraries and their dependencies.</p> <pre><code>pip install -U prefect-aws prefect-snowflake\n</code></pre>"},{"location":"guides/secrets/#store-snowflake-password-in-aws-secrets-manager","title":"Store Snowflake password in AWS Secrets Manager","text":"<p>Go to the AWS Secrets Manager console and create a new secret. Alternatively, create a secret using the AWS CLI or a script.</p> <ol> <li>In the UI, choose Store a new secret.</li> <li>Select Other type of secret.</li> <li>Input the key-value pair for your Snowflake password where the key is any string and the value is your Snowflake password.</li> <li>Copy the key for future reference and click Next.</li> <li>Enter a name for your secret, copy the name, and click Next.</li> <li>For this demo, we won't rotate the key, so click Next.</li> <li>Click Store.</li> </ol>"},{"location":"guides/secrets/#create-awssecret-block-to-access-your-snowflake-password","title":"Create <code>AwsSecret</code> block to access your Snowflake password","text":"<p>You can create blocks with Python code or via the Prefect UI. Block creation through the UI can help you visualize how the pieces fit together, so let's use it here.</p> <p>On the Blocks page, click on + to add a new block and select AWS Secret from the list of block types. Enter a name for your block and enter the secret name from AWS Secrets Manager.</p> <p>Note that if you're using a self-hosted Prefect server instance, you'll need to register the block types in the newly installed modules before creating blocks.</p> <pre><code>prefect block register -m prefect_aws &amp;&amp; prefect block register -m prefect_snowflake\n</code></pre>"},{"location":"guides/secrets/#create-awscredentials-block","title":"Create <code>AwsCredentials</code> block","text":"<p>Under the hood, Prefect is using the AWS <code>boto3</code> client to create a session.</p> <p>In the AwsCredentials section of the form, click Add + and create an AWS Credentials block by entering the necessary values.</p> <p>Values for Access Key ID and Secret Access Key will be read from the compute environment. My AWS Access Key ID and Secret Access Key values with permissions to read the AWS Secret are stored locally in my <code>~/.aws/credentials</code> file, so I'll leave those fields blank. You could enter those values at block creation, but then they would be saved to the database, and that's what we're trying to avoid. By leaving those attributes blank, Prefect knows to look to the compute environment. If the compute environment contains the necessary credentials, Prefect will use them to authenticate in the order shown in the Boto3 docs.</p> <p>The same order is followed to resolve the AWS region. Let's specify the region in our <code>AWSCredentials</code> block so that our connection works regardless of the contents of our local AWS config file or whether we run our code on AWS compute located in anther region than our secret.</p> <p>Click Create to save the blocks.</p>"},{"location":"guides/secrets/#ensure-the-compute-environment-has-access-to-aws-credentials","title":"Ensure the compute environment has access to AWS credentials","text":"<p>Ensure the compute environment contains AWS credentials with authorization to access AWS Secrets Manager. When we connect to Snowflake, Prefect will automatically use these credentials to authenticate and access the AWS secret that contains the Snowflake password.</p>"},{"location":"guides/secrets/#create-and-use-snowflakecredentials-and-snowflakeconnector-blocks-in-python-code","title":"Create and use <code>SnowflakeCredentials</code> and <code>SnowflakeConnector</code> blocks in Python code","text":"<p>Let's use Prefect's blocks for convenient access to Snowflake. We won't save the blocks, to ensure the credentials are not stored in Prefect Cloud.</p> <p>We'll create a flow that connects to Snowflake and calls two tasks. The first task creates a table and inserts some data. The second task reads the data out.</p> <pre><code>import json\nfrom prefect import flow, task\nfrom prefect_aws import AwsSecret\nfrom prefect_snowflake import SnowflakeConnector, SnowflakeCredentials\n\n\n@task\ndef setup_table(snow_connector: SnowflakeConnector) -&gt; None:\n    with snow_connector as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n\n@task\ndef fetch_data(snow_connector: SnowflakeConnector) -&gt; list:\n    all_rows = []\n    with snow_connector as connector:\n        while True:\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n\n@flow(log_prints=True)\ndef snowflake_flow():\n    aws_secret_block = AwsSecret.load(\"my-snowflake-pw\")\n\n    snow_connector = SnowflakeConnector(\n        schema=\"MY_SCHEMA\",\n        database=\"MY_DATABASE\",\n        warehouse=\"COMPUTE_WH\",\n        fetch_size=1,\n        credentials=SnowflakeCredentials(\n            role=\"MYROLE\",\n            user=\"MYUSERNAME\",\n            account=\"ab12345.us-east-2.aws\",\n            password=json.loads(aws_secret_block.read_secret()).get(\"my-snowflake-pw\"),\n        ),\n        poll_frequency_s=1,\n    )\n\n    setup_table(snow_connector)\n    all_rows = fetch_data(snow_connector)\n    print(all_rows)\n\n\nif __name__ == \"__main__\":\n    snowflake_flow()\n</code></pre> <p>Fill in the relevant details for your Snowflake account and run the script.</p> <p>Note that the flow reads the Snowflake password from the AWS Secret Manager and uses it in the <code>SnowflakeCredentials</code> block. The <code>SnowflakeConnector</code> block uses the nested <code>SnowflakeCredentials</code> block to connect to Snowflake. Again, neither of the Snowflake blocks are saved, so the credentials are not stored in Prefect Cloud.</p> <p>Check out the <code>prefect-snowflake</code> docs for more examples of working with Snowflake.</p>"},{"location":"guides/secrets/#next-steps","title":"Next steps","text":"<p>Now you can turn your flow into a deployment so that you and your team can run it remotely on a schedule, in response to an event, or manually.  </p> <p>Make sure to specify the <code>prefect-aws</code> and <code>prefect-snowflake</code> dependencies in your work pool or deployment so that they are available at runtime.</p> <p>Also ensure your compute has the AWS credentials for accessing the secret in AWS Secrets Manager.</p> <p>You've seen how to use Prefect blocks to store non-sensitive configuration and fetch sensitive configuration values from the environment. You can use this pattern to connect to other third-party services that require credentials, such as databases and APIs. You can use a similar pattern with any secret manager, or extend it to work with environment variables.</p>"},{"location":"guides/settings/","title":"Profiles &amp; Configuration","text":"<p>Prefect's local settings are documented and type-validated. </p> <p>By modifying the default settings, you can customize various aspects of the system.  You can override a setting with an environment variable or by updating the setting in a Prefect profile.</p> <p>Prefect profiles are persisted groups of settings on your local machine. A single profile is always active.</p> <p>Initially, a default profile named <code>default</code> is active and contains no settings overrides.</p> <p>All currently active settings can be viewed from the command line by running the following command:</p> <pre><code>prefect config view --show-defaults\n</code></pre> <p>When you switch to a different profile, all of the settings configured in the newly activated profile are applied. </p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#commonly-configured-settings","title":"Commonly configured settings","text":"<p>This section describes some commonly configured settings.  See Configuring settings for details on setting and unsetting configuration values.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_api_key","title":"PREFECT_API_KEY","text":"<p>The <code>PREFECT_API_KEY</code> value specifies the API key used to authenticate with Prefect Cloud.</p> <pre><code>PREFECT_API_KEY=\"[API-KEY]\"\n</code></pre> <p>Generally, you will set the <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> for your active profile by running <code>prefect cloud login</code>.  If you're curious, read more about managing API keys. </p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_api_url","title":"PREFECT_API_URL","text":"<p>The <code>PREFECT_API_URL</code> value specifies the API endpoint of your Prefect Cloud workspace or a self-hosted Prefect server instance.</p> <p>For example, if using Prefect Cloud:</p> <pre><code>PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n</code></pre> <p>You can view your Account ID and Workspace ID in your browser URL when at a Prefect Cloud workspace page.  For example: https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here.</p> <p>If using a local Prefect server instance, set your API URL like this:</p> <pre><code>PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n</code></pre> <p><code>PREFECT_API_URL</code> setting for workers</p> <p>If using a worker (agent and block-based deployments are legacy) that can create flow runs for deployments in remote environments,  <code>PREFECT_API_URL</code> must be set for the environment in which your worker is running.</p> <p>If you want the worker to communicate with Prefect Cloud or a Prefect server instance from a remote execution environment such as a VM or Docker container, you must configure <code>PREFECT_API_URL</code> in that environment.</p> <p>Running the Prefect UI behind a reverse proxy</p> <p>When using a reverse proxy (such as Nginx or Traefik) to proxy traffic to a locally-hosted Prefect UI instance, the Prefect server instance also needs to be configured to know how to connect to the API.  The <code>PREFECT_UI_API_URL</code> should be set to the external proxy URL (e.g. if your external URL is https://prefect-server.example.com/ then set <code>PREFECT_UI_API_URL=https://prefect-server.example.com/api</code> for the Prefect server process).  You can also accomplish this by setting <code>PREFECT_API_URL</code> to the API URL, as this setting is used as a fallback if <code>PREFECT_UI_API_URL</code> is not set.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_home","title":"PREFECT_HOME","text":"<p>The <code>PREFECT_HOME</code> value specifies the local Prefect directory for configuration files, profiles, and the location of the default Prefect SQLite database.</p> <pre><code>PREFECT_HOME='~/.prefect'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#prefect_local_storage_path","title":"PREFECT_LOCAL_STORAGE_PATH","text":"<p>The <code>PREFECT_LOCAL_STORAGE_PATH</code> value specifies the default location of local storage for flow runs.</p> <pre><code>PREFECT_LOCAL_STORAGE_PATH='${PREFECT_HOME}/storage'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#csrf-protection-settings","title":"CSRF Protection Settings","text":"<p>If using a local Prefect server instance, you can configure CSRF protection settings.</p> <p><code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED</code> - Activates CSRF protection on the server, requiring valid CSRF tokens for applicable requests. Recommended for production to prevent CSRF attacks. Defaults to False.</p> <pre><code>PREFECT_SERVER_CSRF_PROTECTION_ENABLED=True\n</code></pre> <p><code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION</code> - Sets the expiration duration for server-issued CSRF tokens, influencing how often tokens need to be refreshed. The default is 1 hour.</p> <pre><code>PREFECT_SERVER_CSRF_TOKEN_EXPIRATION='3600'  # 1 hour in seconds\n</code></pre> <p>By default clients expect that CSRF protection is enabled on the server. If you are running a server without CSRF protection, you can disable CSRF support in the client.</p> <p><code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED</code> - Enables or disables CSRF token handling in the Prefect client. When enabled, the client manages CSRF tokens for state-changing API requests. Defaults to True.</p> <pre><code>PREFECT_CLIENT_CSRF_SUPPORT_ENABLED=True\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#database-settings","title":"Database settings","text":"<p>If running a self-hosted Prefect server instance, there are several database configuration settings you can read about here.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#logging-settings","title":"Logging settings","text":"<p>Prefect provides several logging configuration settings that you can read about in the logging docs.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#configuring-settings","title":"Configuring settings","text":"<p>The <code>prefect config</code> CLI commands enable you to view, set, and unset settings.</p> Command Description set Change the value for a setting. unset Restore the default value for a setting. view Display the current settings.","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#viewing-settings-from-the-cli","title":"Viewing settings from the CLI","text":"<p>The <code>prefect config view</code> command will display settings that override default values.</p> <pre><code>$ prefect config view\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG'\n</code></pre> <p>You can show the sources of values with <code>--show-sources</code>:</p> <pre><code>$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG' (from env)\n</code></pre> <p>You can also include default values with <code>--show-defaults</code>:</p> <pre><code>$ prefect config view --show-defaults\nPREFECT_PROFILE='default'\nPREFECT_AGENT_PREFETCH_SECONDS='10' (from defaults)\nPREFECT_AGENT_QUERY_INTERVAL='5.0' (from defaults)\nPREFECT_API_KEY='None' (from defaults)\nPREFECT_API_REQUEST_TIMEOUT='60.0' (from defaults)\nPREFECT_API_URL='None' (from defaults)\n...\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#setting-and-clearing-values","title":"Setting and clearing values","text":"<p>The <code>prefect config set</code> command lets you change the value of a default setting.</p> <p>A commonly used example is setting the <code>PREFECT_API_URL</code>, which you may need to change when interacting with different Prefect server instances or Prefect Cloud.</p> <pre><code># use a local Prefect server\nprefect config set PREFECT_API_URL=\"http://127.0.0.1:4200/api\"\n\n# use Prefect Cloud\nprefect config set PREFECT_API_URL=\"https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]\"\n</code></pre> <p>If you want to configure a setting to use its default value, use the <code>prefect config unset</code> command.</p> <pre><code>prefect config unset PREFECT_API_URL\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#overriding-defaults-with-environment-variables","title":"Overriding defaults with environment variables","text":"<p>All settings have keys that match the environment variable that can be used to override them.</p> <p>For example, configuring the home directory:</p> <pre><code># environment variable\nexport PREFECT_HOME=\"/path/to/home\"\n</code></pre> <pre><code># python\nimport prefect.settings\nprefect.settings.PREFECT_HOME.value()  # PosixPath('/path/to/home')\n</code></pre> <p>Configuring the a server instance's port:</p> <pre><code># environment variable\nexport PREFECT_SERVER_API_PORT=4242\n</code></pre> <pre><code># python\nprefect.settings.PREFECT_SERVER_API_PORT.value()  # 4242\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#configuration-profiles","title":"Configuration profiles","text":"<p>Prefect allows you to persist settings instead of setting an environment variable each time you open a new shell. Settings are persisted to profiles, which allow you to move between groups of settings quickly.</p> <p>The <code>prefect profile</code> CLI commands enable you to create, review, and manage profiles.</p> Command Description create Create a new profile. delete Delete the given profile. inspect Display settings from a given profile; defaults to active. ls List profile names. rename Change the name of a profile. use Switch the active profile. <p>If you configured settings for a profile, <code>prefect profile inspect</code> displays those settings:</p> <pre><code>$ prefect profile inspect\nPREFECT_PROFILE = \"default\"\nPREFECT_API_KEY = \"pnu_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nPREFECT_API_URL = \"http://127.0.0.1:4200/api\"\n</code></pre> <p>You can pass the name of a profile to view its settings:</p> <pre><code>$ prefect profile create test\n$ prefect profile inspect test\nPREFECT_PROFILE=\"test\"\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#creating-and-removing-profiles","title":"Creating and removing profiles","text":"<p>Create a new profile with no settings:</p> <pre><code>$ prefect profile create test\nCreated profile 'test' at /Users/terry/.prefect/profiles.toml.\n</code></pre> <p>Create a new profile <code>foo</code> with settings cloned from an existing <code>default</code> profile:</p> <pre><code>$ prefect profile create foo --from default\nCreated profile 'cloud' matching 'default' at /Users/terry/.prefect/profiles.toml.\n</code></pre> <p>Rename a profile:</p> <pre><code>$ prefect profile rename temp test\nRenamed profile 'temp' to 'test'.\n</code></pre> <p>Remove a profile:</p> <pre><code>$ prefect profile delete test\nRemoved profile 'test'.\n</code></pre> <p>Removing the default profile resets it:</p> <pre><code>$ prefect profile delete default\nReset profile 'default'.\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#change-values-in-profiles","title":"Change values in profiles","text":"<p>Set a value in the current profile:</p> <pre><code>$ prefect config set VAR=X\nSet variable 'VAR' to 'X'\nUpdated profile 'default'\n</code></pre> <p>Set multiple values in the current profile:</p> <pre><code>$ prefect config set VAR2=Y VAR3=Z\nSet variable 'VAR2' to 'Y'\nSet variable 'VAR3' to 'Z'\nUpdated profile 'default'\n</code></pre> <p>You can set a value in another profile by passing the <code>--profile NAME</code> option to a CLI command:</p> <pre><code>$ prefect --profile \"foo\" config set VAR=Y\nSet variable 'VAR' to 'Y'\nUpdated profile 'foo'\n</code></pre> <p>Unset values in the current profile to restore the defaults:</p> <pre><code>$ prefect config unset VAR2 VAR3\nUnset variable 'VAR2'\nUnset variable 'VAR3'\nUpdated profile 'default'\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#inspecting-profiles","title":"Inspecting profiles","text":"<p>See a list of available profiles:</p> <pre><code>$ prefect profile ls\n* default\ncloud\ntest\nlocal\n</code></pre> <p>View all settings for a profile:</p> <pre><code>$ prefect profile inspect cloud\nPREFECT_API_URL='https://api.prefect.cloud/api/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx\nx/workspaces/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\nPREFECT_API_KEY='xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'          \n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#using-profiles","title":"Using profiles","text":"<p>The profile named <code>default</code> is used by default. There are several methods to switch to another profile.</p> <p>The recommended method is to use the <code>prefect profile use</code> command with the name of the profile:</p> <pre><code>$ prefect profile use foo\nProfile 'test' now active.\n</code></pre> <p>Alternatively, you can set the environment variable <code>PREFECT_PROFILE</code> to the name of the profile:</p> <pre><code>export PREFECT_PROFILE=foo\n</code></pre> <p>Or, specify the profile in the CLI command for one-time usage:</p> <pre><code>prefect --profile \"foo\" ...\n</code></pre> <p>Note that this option must come before the subcommand. For example, to list flow runs using the profile <code>foo</code>:</p> <pre><code>prefect --profile \"foo\" flow-run ls\n</code></pre> <p>You may use the <code>-p</code> flag as well:</p> <pre><code>prefect -p \"foo\" flow-run ls\n</code></pre> <p>You may also create an 'alias' to automatically use your profile:</p> <pre><code>$ alias prefect-foo=\"prefect --profile 'foo' \"\n# uses our profile!\n$ prefect-foo config view  \n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#conflicts-with-environment-variables","title":"Conflicts with environment variables","text":"<p>If setting the profile from the CLI with <code>--profile</code>, environment variables that conflict with settings in the profile will be ignored.</p> <p>In all other cases, environment variables will take precedence over the value in the profile.</p> <p>For example, a value set in a profile will be used by default:</p> <pre><code>$ prefect config set PREFECT_LOGGING_LEVEL=\"ERROR\"\n$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='ERROR' (from profile)\n</code></pre> <p>But, setting an environment variable will override the profile setting:</p> <pre><code>$ export PREFECT_LOGGING_LEVEL=\"DEBUG\"\n$ prefect config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='DEBUG' (from env)\n</code></pre> <p>Unless the profile is explicitly requested when using the CLI:</p> <pre><code>$ prefect --profile default config view --show-sources\nPREFECT_PROFILE=\"default\"\nPREFECT_LOGGING_LEVEL='ERROR' (from profile)\n</code></pre>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/settings/#profile-files","title":"Profile files","text":"<p>Profiles are persisted to the file location specified by <code>PREFECT_PROFILES_PATH</code>.  The default location is a <code>profiles.toml</code> file in the <code>PREFECT_HOME</code> directory:</p> <pre><code>$ prefect config view --show-defaults\n...\nPREFECT_PROFILES_PATH='${PREFECT_HOME}/profiles.toml'\n...\n</code></pre> <p>The TOML format is used to store profile data.</p>","tags":["configuration","settings","environment variables","profiles"],"boost":2},{"location":"guides/specifying-upstream-dependencies/","title":"Specifying Upstream Dependencies","text":"<p>Results from a task can be provided to other tasks (or subflows) as upstream dependencies. Prefect uses upstream dependencies in two ways:</p> <ol> <li>To populate dependency arrows in the flow run graph</li> <li>To determine execution order for concurrently submitted units of work that depend on each other</li> </ol> <p>Tasks vs. other functions</p> <p>Only results from tasks inform Prefect's ability to determine dependencies. Return values from functions without task decorators, including subflows, do not carry the same information about their origin as task results.</p> <p>When using non-sequential task runners such as the <code>ConcurrentTaskRunner</code> or <code>DaskTaskRunner</code>, the order of execution for submitted tasks is not guaranteed unless their dependencies are specified.</p> <p>For example, compare how tasks submitted to the <code>ConcurrentTaskRunner</code> behave with and without upstream dependencies by clicking on the tabs below.</p> Without dependenciesWith dependencies <pre><code>@flow(log_prints=True) # Default task runner is ConcurrentTaskRunner\ndef flow_of_tasks():\n    # no dependencies, execution is order not guaranteed\n    first.submit()\n    second.submit()\n    third.submit()\n\n@task\ndef first():\n    print(\"I'm first!\")\n\n@task\ndef second():\n    print(\"I'm second!\")\n\n@task\ndef third():\n    print(\"I'm third!\")\n</code></pre> <pre><code>Flow run 'pumpkin-puffin' - Created task run 'first-0' for task 'first'\nFlow run 'pumpkin-puffin' - Submitted task run 'first-0' for execution.\nFlow run 'pumpkin-puffin' - Created task run 'second-0' for task 'second'\nFlow run 'pumpkin-puffin' - Submitted task run 'second-0' for execution.\nFlow run 'pumpkin-puffin' - Created task run 'third-0' for task 'third'\nFlow run 'pumpkin-puffin' - Submitted task run 'third-0' for execution.\nTask run 'third-0' - I'm third!\nTask run 'first-0' - I'm first!\nTask run 'second-0' - I'm second!\nTask run 'second-0' - Finished in state Completed()\nTask run 'third-0' - Finished in state Completed()\nTask run 'first-0' - Finished in state Completed()\nFlow run 'pumpkin-puffin' - Finished in state Completed('All states completed.')\n</code></pre> <pre><code>@flow(log_prints=True) # Default task runner is ConcurrentTaskRunner\ndef flow_of_tasks():\n    # with dependencies, tasks execute in order\n    first_result = first.submit()\n    second_result = second.submit(first_result)\n    third.submit(second_result)\n\n@task\ndef first():\n    print(\"I'm first!\")\n\n@task\ndef second(input):\n    print(\"I'm second!\")\n\n@task\ndef third(input):\n    print(\"I'm third!\")\n</code></pre> <pre><code>Flow run 'statuesque-waxbill' - Created task run 'first-0' for task 'first'\nFlow run 'statuesque-waxbill' - Submitted task run 'first-0' for execution.\nFlow run 'statuesque-waxbill' - Created task run 'second-0' for task 'second'\nFlow run 'statuesque-waxbill' - Submitted task run 'second-0' for execution.\nFlow run 'statuesque-waxbill' - Created task run 'third-0' for task 'third'\nFlow run 'statuesque-waxbill' - Submitted task run 'third-0' for execution.\nTask run 'first-0' - I'm first!\nTask run 'first-0' - Finished in state Completed()\nTask run 'second-0' - I'm second!\nTask run 'second-0' - Finished in state Completed()\nTask run 'third-0' - I'm third!\nTask run 'third-0' - Finished in state Completed()\nFlow run 'statuesque-waxbill' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#determination-methods","title":"Determination methods","text":"<p>A task or subflow's upstream dependencies can be inferred automatically via its inputs, or stated explicitly via the <code>wait_for</code> parameter.</p>","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#automatic","title":"Automatic","text":"<p>When a result from a task is used as input for another task, Prefect automatically recognizes the task that result originated from as an upstream dependency.</p> <p>This applies to every way you can run tasks with Prefect, whether you're calling the task function directly, calling <code>.submit()</code>, or calling <code>.map()</code>. Subflows similarly recognize tasks results as upstream dependencies.</p> <pre><code>from prefect import flow, task\n\n\n@flow(log_prints=True)\ndef flow_of_tasks():\n    upstream_result = upstream.submit()\n    downstream_1_result = downstream_1.submit(upstream_result)\n    downstream_2_result = downstream_2.submit(upstream_result)\n    mapped_task_results = mapped_task.map([downstream_1_result, downstream_2_result])\n    final_task(mapped_task_results)\n\n@task\ndef upstream():\n    return \"Hello from upstream!\"\n\n@task\ndef downstream_1(input):\n    return input\n\n@task\ndef downstream_2(input):\n    return input\n\n@task\ndef mapped_task(input):\n    return input\n\n@task\ndef final_task(input):\n    print(input)\n</code></pre> Flow run graph displaying inferred dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#manual","title":"Manual","text":"<p>Tasks that do not share data can be informed of their upstream dependencies through the <code>wait_for</code> parameter. Just as with automatic dependencies, this applies to direct task function calls, <code>.submit()</code>, <code>.map()</code>, and subflows.</p> <p>Differences with <code>.map()</code></p> <p>Manually defined upstream dependencies apply to all tasks submitted by <code>.map()</code>, so each mapped task must wait for all upstream dependencies passed into <code>wait_for</code> to finish. This is distinct from automatic dependencies for mapped tasks, where each mapped task must only wait for the upstream tasks whose results it depends on.</p> <pre><code>from prefect import flow, task\n\n\n@flow(log_prints=True)\ndef flow_of_tasks():\n    upstream_result = upstream.submit()\n    downstream_1_result = downstream_1.submit(wait_for=[upstream_result])\n    downstream_2_result = downstream_2.submit(wait_for=[upstream_result])\n    mapped_task_results = mapped_task.map([1, 2], wait_for=[downstream_1_result, downstream_2_result])\n    final_task(wait_for=mapped_task_results)\n\n@task\ndef upstream():\n    pass\n\n@task\ndef downstream_1():\n    pass\n\n@task\ndef downstream_2():\n    pass\n\n@task\ndef mapped_task(input):\n    pass\n\n@task\ndef final_task():\n    pass\n</code></pre> Flow run graph displaying manual dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/specifying-upstream-dependencies/#deployments-as-dependencies","title":"Deployments as dependencies","text":"<p>For more complex workflows, parts of your logic may require additional resources, different infrastructure, or independent parallel execution. A typical approach for addressing these needs is to execute that logic as separate deployment runs from within a flow.</p> <p>Composing deployment runs into a flow so that they can be treated as upstream dependencies is as simple as calling <code>run_deployment</code> from within a task.</p> <p>Given a deployment <code>process-user</code> of flow <code>parallel-work</code>, a flow of deployments might look like this:</p> <pre><code>from prefect import flow, task\nfrom prefect.deployments import run_deployment\n\n\n@flow\ndef flow_of_deployments():\n    deployment_run_1 = run_deployment_task.submit(\n        flow_name=\"parallel-work\",\n        deployment_name=\"process-user\",\n        parameters={\"user_id\": 1},\n    )\n    deployment_run_2 = run_deployment_task.submit(\n        flow_name=\"parallel-work\",\n        deployment_name=\"process-user\",\n        parameters={\"user_id\": 2},\n    )\n    downstream_task(wait_for=[deployment_run_1, deployment_run_2])\n\n\n@task(task_run_name=\"Run deployment {flow_name}/{deployment_name}\")\ndef run_deployment_task(\n    flow_name: str,\n    deployment_name: str,\n    parameters: dict\n):\n    run_deployment(\n        name=f\"{flow_name}/{deployment_name}\",\n        parameters=parameters\n    )\n\n\n@task\ndef downstream_task():\n    print(\"I'm downstream!\")\n</code></pre> <p>By default, deployments started from <code>run_deployment</code> will also appear as subflows for tracking purposes. This behavior can be disabled by setting the <code>as_subflow</code> parameter for <code>run_deployment</code> to <code>False</code>.</p> Flow run graph displaying deployments as dependencies with the \"Dependency grid\" layout selected","tags":["tasks","dependencies","wait_for"],"boost":2},{"location":"guides/state-change-hooks/","title":"State Change Hooks","text":"<p>State change hooks execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow. This guide provides examples of real-world use cases.</p>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#example-use-cases","title":"Example use cases","text":"","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#send-a-notification-when-a-flow-run-fails","title":"Send a notification when a flow run fails","text":"<p>State change hooks enable you to customize messages sent when tasks transition between states, such as sending notifications containing sensitive information when tasks enter a <code>Failed</code> state. Let's run a client-side hook upon a flow run entering a <code>Failed</code> state.</p> <pre><code>from prefect import flow\nfrom prefect.blocks.core import Block\nfrom prefect.settings import PREFECT_API_URL\n\ndef notify_slack(flow, flow_run, state):\n    slack_webhook_block = Block.load(\n        \"slack-webhook/my-slack-webhook\"\n    )\n\n    slack_webhook_block.notify(\n        (\n            f\"Your job {flow_run.name} entered {state.name} \"\n            f\"with message:\\n\\n\"\n            f\"See &lt;https://{PREFECT_API_URL.value()}/flow-runs/\"\n            f\"flow-run/{flow_run.id}|the flow run in the UI&gt;\\n\\n\"\n            f\"Tags: {flow_run.tags}\\n\\n\"\n            f\"Scheduled start: {flow_run.expected_start_time}\"\n        )\n    )\n\n@flow(on_failure=[notify_slack], retries=1)\ndef failing_flow():\n    raise ValueError(\"oops!\")\n\nif __name__ == \"__main__\":\n    failing_flow()\n</code></pre> <p>Note that because we've configured retries in this example, the <code>on_failure</code> hook will not run until all <code>retries</code> have completed, when the flow run enters a <code>Failed</code> state.</p>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/state-change-hooks/#delete-a-cloud-run-job-when-a-flow-run-crashes","title":"Delete a Cloud Run job when a flow run crashes","text":"<p>State change hooks can aid in managing infrastructure cleanup in scenarios where tasks spin up individual infrastructure resources independently of Prefect. When a flow run crashes, tasks may exit abruptly, resulting in the potential omission of cleanup logic within the tasks. State change hooks can be used to ensure infrastructure is properly cleaned up even when a flow run enters a <code>Crashed</code> state!</p> <p>Let's create a hook that deletes a Cloud Run job if the flow run crashes.</p> <pre><code>import os\nfrom prefect import flow, task\nfrom prefect.blocks.system import String\nfrom prefect.client import get_client\nimport prefect.runtime\n\nasync def delete_cloud_run_job(flow, flow_run, state):\n    \"\"\"Flow run state change hook that deletes a Cloud Run Job if\n    the flow run crashes.\"\"\"\n\n    # retrieve Cloud Run job name\n    cloud_run_job_name = await String.load(\n        name=\"crashing-flow-cloud-run-job\"\n    )\n\n    # delete Cloud Run job\n    delete_job_command = f\"yes | gcloud beta run jobs delete \n    {cloud_run_job_name.value} --region us-central1\"\n    os.system(delete_job_command)\n\n    # clean up the Cloud Run job string block as well\n    async with get_client() as client:\n        block_document = await client.read_block_document_by_name(\n            \"crashing-flow-cloud-run-job\", block_type_slug=\"string\"\n        )\n        await client.delete_block_document(block_document.id)\n\n@task\ndef my_task_that_crashes():\n    raise SystemExit(\"Crashing on purpose!\")\n\n@flow(on_crashed=[delete_cloud_run_job])\ndef crashing_flow():\n    \"\"\"Save the flow run name (i.e. Cloud Run job name) as a \n    String block. It then executes a task that ends up crashing.\"\"\"\n    flow_run_name = prefect.runtime.flow_run.name\n    cloud_run_job_name = String(value=flow_run_name)\n    cloud_run_job_name.save(\n        name=\"crashing-flow-cloud-run-job\", overwrite=True\n    )\n\n    my_task_that_crashes()\n\nif __name__ == \"__main__\":\n    crashing_flow()\n</code></pre>","tags":["state change","hooks","triggers"],"boost":2},{"location":"guides/testing/","title":"Testing","text":"<p>Once you have some awesome flows, you probably want to test them!</p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/testing/#unit-testing-flows","title":"Unit testing flows","text":"<p>Prefect provides a simple context manager for unit tests that allows you to run flows and tasks against a temporary local SQLite database.</p> <pre><code>from prefect import flow\nfrom prefect.testing.utilities import prefect_test_harness\n\n@flow\ndef my_favorite_flow():\n    return 42\n\ndef test_my_favorite_flow():\n  with prefect_test_harness():\n      # run the flow against a temporary testing database\n      assert my_favorite_flow() == 42\n</code></pre> <p>For more extensive testing, you can leverage <code>prefect_test_harness</code> as a fixture in your unit testing framework. For example, when using <code>pytest</code>:</p> <pre><code>from prefect import flow\nimport pytest\nfrom prefect.testing.utilities import prefect_test_harness\n\n@pytest.fixture(autouse=True, scope=\"session\")\ndef prefect_test_fixture():\n    with prefect_test_harness():\n        yield\n\n@flow\ndef my_favorite_flow():\n    return 42\n\ndef test_my_favorite_flow():\n    assert my_favorite_flow() == 42\n</code></pre> <p>Note</p> <p>In this example, the fixture is scoped to run once for the entire test session. In most cases, you will not need a clean database for each test and just want to isolate your test runs to a test database. Creating a new test database per test creates significant overhead, so we recommend scoping the fixture to the session. If you need to isolate some tests fully, you can use the test harness again to create a fresh database.</p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/testing/#unit-testing-tasks","title":"Unit testing tasks","text":"<p>To test an individual task, you can access the original function using <code>.fn</code>:</p> <pre><code>from prefect import flow, task\n\n@task\ndef my_favorite_task():\n    return 42\n\n@flow\ndef my_favorite_flow():\n    val = my_favorite_task()\n    return val\n\ndef test_my_favorite_task():\n    assert my_favorite_task.fn() == 42\n</code></pre> <p>Disable logger</p> <p>If your task makes uses a logger, you can disable the logger in order to avoid the <code>RuntimeError</code> raised from a missing flow context. <pre><code>from prefect.logging import disable_run_logger\n\ndef test_my_favorite_task():\n    with disable_run_logger():\n        assert my_favorite_task.fn() == 42\n</code></pre></p>","tags":["testing","unit testing","development"],"boost":2},{"location":"guides/troubleshooting/","title":"Troubleshooting","text":"<p>Don't Panic! If you experience an error with Prefect, there are many paths to understanding and resolving it. The first troubleshooting step is confirming that you are running the latest version of Prefect. If you are not, be sure to upgrade to the latest version, since the issue may have already been fixed. Beyond that, there are several categories of errors:</p> <ul> <li>The issue may be in your flow code, in which case you should carefully read the logs.</li> <li>The issue could be with how you are authenticated, and whether or not you are connected to Cloud.</li> <li>The issue might have to do with how your code is executed.</li> </ul>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#upgrade","title":"Upgrade","text":"<p>Prefect is constantly evolving, adding new features and fixing bugs. Chances are that a patch has already been identified and released. Search existing issues for similar reports and check out the Release Notes. Upgrade to the newest version with the following command:</p> <pre><code>pip install --upgrade prefect\n</code></pre> <p>Different components may use different versions of Prefect:</p> <ul> <li>Cloud will generally always be the newest version. Cloud is continuously deployed by the Prefect team. When using a self-hosted server, you can control this version.</li> <li>Workers and agents typically don't change versions frequently, and are usually whatever the latest version was at the time of creation. Workers and agents provision infrastructure for flow runs, so upgrading them may help with infrastructure problems.</li> <li>Flows could use a different version than the worker or agent that created them, especially when running in different environments. Suppose your worker and flow both use the latest official Docker image, but your worker was created a month ago. Your worker will often be on an older version than your flow.</li> </ul> <p>Integration Versions</p> <p>Keep in mind that integrations are versioned and released independently of the core Prefect library. They should be upgraded simultaneously with the core library, using the same method.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#logs","title":"Logs","text":"<p>In many cases, there will be an informative stack trace in Prefect's logs. Read it carefully, locate the source of the error, and try to identify the cause.</p> <p>There are two types of logs:</p> <ul> <li>Flow and task logs are always scoped to a flow. They are sent to Prefect and are viewable in the UI.</li> <li>Worker and agent logs are not scoped to a flow and may have more information on what happened before the flow started. These logs are generally only available where the worker or agent is running.</li> </ul> <p>If your flow and task logs are empty, there may have been an infrastructure issue that prevented your flow from starting. Check your worker logs for more details.</p> <p>If there is no clear indication of what went wrong, try updating the logging level from the default <code>INFO</code> level to the <code>DEBUG</code> level. Settings such as the logging level are propagated from the worker environment to the flow run environment and can be set via environment variables or the <code>prefect config set</code> CLI:</p> <pre><code># Using the CLI\nprefect config set PREFECT_LOGGING_LEVEL=DEBUG\n\n# Using environment variables\nexport PREFECT_LOGGING_LEVEL=DEBUG\n</code></pre> <p>The <code>DEBUG</code> logging level produces a high volume of logs so consider setting it back to <code>INFO</code> once any issues are resolved.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#cloud","title":"Cloud","text":"<p>When using Prefect Cloud, there are the additional concerns of authentication and authorization. The Prefect API authenticates users and service accounts - collectively known as actors - with API keys. Missing, incorrect, or expired API keys will result in a 401 response with detail <code>Invalid authentication credentials</code>. Use the following command to check your authentication, replacing <code>$PREFECT_API_KEY</code> with your API key:</p> <pre><code>curl -s -H \"Authorization: Bearer $PREFECT_API_KEY\" \"https://api.prefect.cloud/api/me/\"\n</code></pre> <p>Users vs Service Accounts</p> <p>Service accounts - sometimes referred to as bots - represent non-human actors that interact with Prefect such as workers and CI/CD systems. Each human that interacts with Prefect should be represented as a user. User API keys start with <code>pnu_</code> and service account API keys start with <code>pnb_</code>.</p> <p>Supposing the response succeeds, let's check our authorization. Actors can be members of workspaces. An actor attempting an action in a workspace they are not a member of will result in a 404 response. Use the following command to check your actor's workspace memberships:</p> <pre><code>curl -s -H \"Authorization: Bearer $PREFECT_API_KEY\" \"https://api.prefect.cloud/api/me/workspaces\"\n</code></pre> <p>Formatting JSON</p> <p>Python comes with a helpful tool for formatting JSON. Append the following to the end of the command above to make the output more readable: <code>| python -m json.tool</code></p> <p>Make sure your actor is a member of the workspace you are working in. Within a workspace, an actor has a role which grants them certain permissions. Insufficient permissions will result in an error. For example, starting an agent or worker with the Viewer role, will result in errors.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#execution","title":"Execution","text":"<p>Prefect flows can be executed locally by the user, or remotely by a worker or agent. Local execution generally means that you - the user - run your flow directly with a command like <code>python flow.py</code>. Remote execution generally means that a worker runs your flow via a deployment, optionally on different infrastructure.</p> <p>With remote execution, the creation of your flow run happens separately from its execution. Flow runs are assigned to a work pool and a work queue. For flow runs to execute, a worker must be subscribed to the work pool and work queue, otherwise the flow runs will go from <code>Scheduled</code> to <code>Late</code>. Ensure that your work pool and work queue have a subscribed worker.</p> <p>Local and remote execution can also differ in their treatment of relative imports. If switching from local to remote execution results in local import errors, try replicating the behavior by executing the flow locally with the <code>-m</code> flag (i.e. <code>python -m flow</code> instead of <code>python flow.py</code>). Read more about <code>-m</code> here.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#api-tests-return-an-unexpected-307-redirected","title":"API tests return an unexpected 307 Redirected","text":"<p>Summary: Requests require a trailing <code>/</code> in the request URL.</p> <p>If you write a test that does not include a trailing <code>/</code> when making a request to a specific endpoint:</p> <pre><code>async def test_example(client):\n    response = await client.post(\"/my_route\")\n    assert response.status_code == 201\n</code></pre> <p>You'll see a failure like:</p> <pre><code>E       assert 307 == 201\nE        +  where 307 = &lt;Response [307 Temporary Redirect]&gt;.status_code\n</code></pre> <p>To resolve this, include the trailing <code>/</code>:</p> <pre><code>async def test_example(client):\n    response = await client.post(\"/my_route/\")\n    assert response.status_code == 201\n</code></pre> <p>Note: requests to nested URLs may exhibit the opposite behavior and require no trailing slash:</p> <pre><code>async def test_nested_example(client):\n    response = await client.post(\"/my_route/filter/\")\n    assert response.status_code == 307\n\n    response = await client.post(\"/my_route/filter\")\n    assert response.status_code == 200\n</code></pre> <p>Reference: \"HTTPX disabled redirect following by default\" in <code>0.22.0</code>.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/troubleshooting/#pytestpytestunraisableexceptionwarning-or-resourcewarning","title":"<code>pytest.PytestUnraisableExceptionWarning</code> or <code>ResourceWarning</code>","text":"<p>As you're working with one of the <code>FlowRunner</code> implementations, you may get an error like this one:</p> <pre><code>E               pytest.PytestUnraisableExceptionWarning: Exception ignored in: &lt;ssl.SSLSocket fd=-1, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0&gt;\nE\nE               Traceback (most recent call last):\nE                 File \".../pytest_asyncio/plugin.py\", line 306, in setup\nE                   res = await func(**_add_kwargs(func, kwargs, event_loop, request))\nE               ResourceWarning: unclosed &lt;ssl.SSLSocket fd=10, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 60605), raddr=('127.0.0.1', 6443)&gt;\n\n.../_pytest/unraisableexception.py:78: PytestUnraisableExceptionWarning\n</code></pre> <p>This error is saying that your test suite (or the <code>prefect</code> library code) opened a connection to something (like a Docker daemon or a Kubernetes cluster) and didn't close it.</p> <p>It may help to re-run the specific test with <code>PYTHONTRACEMALLOC=25 pytest ...</code> so that Python can display more of the stack trace where the connection was opened.</p>","tags":["troubleshooting","guides","how to"]},{"location":"guides/upgrade-guide-agents-to-workers/","title":"Upgrade from Agents to Workers","text":"<p>Upgrading from agents to workers significantly enhances the experience of deploying flows. It simplifies the specification of each flow's infrastructure and runtime environment.</p> <p>A worker is the fusion of an agent with an infrastructure block. Like agents, workers poll a work pool for flow runs that are scheduled to start. Like infrastructure blocks, workers are typed - they work with only one kind of infrastructure, and they specify the default configuration for jobs submitted to that infrastructure.</p> <p>Accordingly, workers are not a drop-in replacement for agents. Using workers requires deploying flows differently. In particular, deploying a flow with a worker does not involve specifying an infrastructure block. Instead, infrastructure configuration is specified on the work pool and passed to each worker that polls work from that pool.</p> <p>This guide provides an overview of the differences between agents and workers. It also describes how to upgrade from agents to workers in just a few quick steps.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#enhancements","title":"Enhancements","text":"","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#workers","title":"Workers","text":"<ul> <li>Improved visibility into the status of each worker, including when a worker was started and when it last polled.</li> <li>Better handling of race conditions for high availability use cases.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#work-pools","title":"Work pools","text":"<ul> <li>Work pools allow greater customization and governance of infrastructure parameters for deployments via their base job template.</li> <li>Prefect Cloud push work pools enable flow execution in your cloud provider environment without needing to host a worker.</li> <li>Prefect Cloud managed work pools allow you to run flows on Prefect's infrastructure, without needing to host a worker or configure cloud provider infrastructure.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#improved-deployment-interfaces","title":"Improved deployment interfaces","text":"<ul> <li>The Python deployment experience with <code>.deploy()</code> or the alternative deployment experience with <code>prefect.yaml</code> are more flexible and easier to use than block and agent-based deployments.</li> <li>Both options allow you to deploy multiple flows with a single command.</li> <li>Both options allow you to build Docker images for your flows to create portable execution environments.</li> <li>The YAML-based API supports templating to enable dryer deployment definitions.</li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#whats-different","title":"What's different","text":"<ol> <li> <p>Deployment CLI and Python SDK:</p> <p><code>prefect deployment build &lt;entrypoint&gt;</code>/<code>prefect deployment apply</code> --&gt; <code>prefect deploy</code></p> <p>Prefect will now automatically detect flows in your repo and provide a wizard \ud83e\uddd9 to guide you through setting required attributes for your deployments.</p> <p><code>Deployment.build_from_flow</code> --&gt; <code>flow.deploy</code></p> </li> <li> <p>Configuring remote flow code storage:</p> <p>storage blocks --&gt; pull action</p> <p>When using the YAML-based deployment API, you can configure a pull action in your <code>prefect.yaml</code> file to specify how to retrieve flow code for your deployments. You can use configuration from your existing storage blocks to define your pull action via templating.</p> <p>When using the Python deployment API, you can pass any storage block to the <code>flow.deploy</code> method to specify how to retrieve flow code for your deployment.</p> </li> <li> <p>Configuring flow run infrastructure:</p> <p>infrastructure blocks --&gt; typed work pool</p> <p>Default infrastructure config is now set on the typed work pool, and can be overwritten by individual deployments.</p> </li> <li> <p>Managing multiple deployments:</p> <p>Create and/or update many deployments at once through a <code>prefect.yaml</code> file or use the <code>deploy</code> function.</p> </li> </ol>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#whats-similar","title":"What's similar","text":"<ul> <li>Storage blocks can be set as the pull action in a <code>prefect.yaml</code> file.</li> <li>Infrastructure blocks have configuration fields similar to typed work pools.</li> <li> <p>Deployment-level infrastructure overrides operate in much the same way.</p> <p><code>infra_override</code> -&gt; <code>job_variable</code></p> </li> <li> <p>The process for starting an agent and starting a worker in your environment are virtually identical.</p> <p><code>prefect agent start --pool &lt;work pool name&gt;</code> --&gt; <code>prefect worker start --pool &lt;work pool name&gt;</code></p> <p>Worker Helm chart</p> <p>If you host your agents in a Kubernetes cluster, you can use the Prefect worker Helm chart to host workers in your cluster.</p> </li> </ul>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#upgrade-guide","title":"Upgrade guide","text":"<p>If you have existing deployments that use infrastructure blocks, you can quickly upgrade them to be compatible with workers by following these steps:</p> <ol> <li>Create a work pool</li> </ol> <p>This new work pool will replace your infrastructure block.</p> <p>You can use the <code>.publish_as_work_pool</code> method on any infrastructure block to create a work pool with the same configuration.</p> <p>For example, if you have a <code>KubernetesJob</code> infrastructure block named 'my-k8s-job', you can create a work pool with the same configuration with this script:</p> <pre><code>from prefect.infrastructure import KubernetesJob\n\nKubernetesJob.load(\"my-k8s-job\").publish_as_work_pool()\n</code></pre> <pre><code>Running this script will create a work pool named 'my-k8s-job' with the same configuration as your infrastructure block.\n</code></pre> <p>Serving flows</p> <p>If you are using a <code>Process</code> infrastructure block and a <code>LocalFilesystem</code> storage block (or aren't using an infrastructure and storage block at all), you can use <code>flow.serve</code> to create a deployment without needing to specify a work pool name or start a worker.</p> <p>This is a quick way to create a deployment for a flow and is a great way to manage your deployments if you don't need the dynamic infrastructure creation or configuration offered by workers.</p> <p>Check out our Docker guide for how to build a served flow into a Docker image and host it in your environment.</p> <ol> <li>Start a worker</li> </ol> <p>This worker will replace your agent and poll your new work pool for flow runs to execute.</p> <pre><code>prefect worker start -p &lt;work pool name&gt;\n</code></pre> <ol> <li>Deploy your flows to the new work pool</li> </ol> <p>To deploy your flows to the new work pool, you can use <code>flow.deploy</code> for a Pythonic deployment experience or <code>prefect deploy</code> for a YAML-based deployment experience.</p> <p>If you currently use <code>Deployment.build_from_flow</code>, we recommend using <code>flow.deploy</code>.</p> <p>If you currently use <code>prefect deployment build</code> and <code>prefect deployment apply</code>, we recommend using <code>prefect deploy</code>.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#flowdeploy","title":"<code>flow.deploy</code>","text":"<p>If you have a Python script that uses <code>Deployment.build_from_flow</code>, you can replace it with <code>flow.deploy</code>.</p> <p>Most arguments to <code>Deployment.build_from_flow</code> can be translated directly to <code>flow.deploy</code>, but here are some changes that you may need to make:</p> <ul> <li>Replace <code>infrastructure</code> with <code>work_pool_name</code>.</li> <li>If you've used the <code>.publish_as_work_pool</code> method on your infrastructure block, use the name of the created work pool.</li> <li>Replace <code>infra_overrides</code> with <code>job_variables</code>.</li> <li>Replace <code>storage</code> with a call to <code>flow.from_source</code>.</li> <li><code>flow.from_source</code> will load your flow from a remote storage location and make it deployable. Your existing storage block can be passed to the <code>source</code> argument of <code>flow.from_source</code>.</li> </ul> <p>Below are some examples of how to translate <code>Deployment.build_from_flow</code> to <code>flow.deploy</code>.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-without-any-blocks","title":"Deploying without any blocks","text":"<p>If you aren't using any blocks:</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Python script!\")\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>You can replace <code>Deployment.build_from_flow</code> with <code>flow.serve</code> :</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Python script!\")\n\nif __name__ == \"__main__\":\n    my_flow.serve(\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>This will start a process that will serve your flow and execute any flow runs that are scheduled to start.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-using-a-storage-block","title":"Deploying using a storage block","text":"<p>If you currently use a storage block to load your flow code but no infrastructure block:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a GitHub repo!\")\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        storage=GitHub.load(\"demo-repo\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>you can use <code>flow.from_source</code> to load your flow from the same location and <code>flow.serve</code> to create a deployment:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\"\n    ).serve(\n        name=\"my-deployment\",\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>This will allow you to execute scheduled flow runs without starting a worker. Additionally, the process serving your flow will regularly check for updates to your flow code and automatically update the flow if it detects any changes to the code.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-using-an-infrastructure-and-storage-block","title":"Deploying using an infrastructure and storage block","text":"<p>For the code below, we'll need to create a work pool from our infrastructure block and pass it to <code>flow.deploy</code> as the <code>work_pool_name</code> argument. We'll also need to pass our storage block to <code>flow.from_source</code> as the <code>source</code> argument.</p> <pre><code>from prefect import flow\nfrom prefect.deployments import Deployment\nfrom prefect.filesystems import GitHub\nfrom prefect.infrastructure.kubernetes import KubernetesJob\n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a GitHub repo!\")\n\n\nif __name__ == \"__main__\":\n    Deployment.build_from_flow(\n        my_flow,\n        name=\"my-deployment\",\n        storage=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\",\n        infrastructure=KubernetesJob.load(\"my-k8s-job\"),\n        infra_overrides=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>The equivalent deployment code using <code>flow.deploy</code> would look like this:</p> <pre><code>from prefect import flow\nfrom prefect.storage import GitHub\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitHub.load(\"demo-repo\"),\n        entrypoint=\"example.py:my_flow\"\n    ).deploy(\n        name=\"my-deployment\",\n        work_pool_name=\"my-k8s-job\",\n        job_variables=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>Note that when using <code>flow.from_source(...).deploy(...)</code>, the flow you're deploying does not need to be available locally before running your script.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#deploying-via-a-docker-image","title":"Deploying via a Docker image","text":"<p>If you currently bake your flow code into a Docker image before deploying, you can use the <code>image</code> argument of <code>flow.deploy</code> to build a Docker image as part of your deployment process:</p> <pre><code>from prefect import flow\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow from a Docker image!\")\n\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"my-deployment\",\n        image=\"my-repo/my-image:latest\",\n        work_pool_name=\"my-k8s-job\",\n        job_variables=dict(pull_policy=\"Never\"),\n        parameters=dict(name=\"Marvin\"),\n    )\n</code></pre> <p>You can skip a <code>flow.from_source</code> call when building an image with <code>flow.deploy</code>. Prefect will keep track of the flow's source code location in the image and load it from that location when the flow is executed.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/upgrade-guide-agents-to-workers/#using-prefect-deploy","title":"Using <code>prefect deploy</code>","text":"<p>Always run <code>prefect deploy</code> commands from the root level of your repo!</p> <p>With agents, you might have had multiple <code>deployment.yaml</code> files, but under worker deployment patterns, each repo will have a single <code>prefect.yaml</code> file located at the root of the repo that contains deployment configuration for all flows in that repo.</p> <p>To set up a new <code>prefect.yaml</code> file for your deployments, run the following command from the root level of your repo:</p> <pre><code>prefect deploy\n</code></pre> <p>This will start a wizard that will guide you through setting up your deployment.</p> <p>For step 4, select <code>y</code> on the last prompt to save the configuration for the deployment.</p> <p>Saving the configuration for your deployment will result in a <code>prefect.yaml</code> file populated with your first deployment. You can use this YAML file to edit and define multiple deployments for this repo.</p> <p>You can add more deployments to the <code>deployments</code> list in your <code>prefect.yaml</code> file and/or by continuing to use the deployment creation wizard.</p> <p>For more information on deployments, check out our in-depth guide for deploying flows to work pools.</p>","tags":["worker","agent","deployments","infrastructure","work pool"],"boost":2},{"location":"guides/using-the-client/","title":"Using the Prefect Orchestration Client","text":"","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#overview","title":"Overview","text":"<p>In the API reference for the <code>PrefectClient</code>, you can find many useful client methods that make it simpler to do things such as:</p> <ul> <li>reschedule late flow runs</li> <li>get the last <code>N</code> completed flow runs from my workspace</li> </ul> <p>The <code>PrefectClient</code> is an async context manager, so you can use it like this:</p> <pre><code>from prefect import get_client\n\nasync with get_client() as client:\n    response = await client.hello()\n    print(response.json()) # \ud83d\udc4b\n</code></pre>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#examples","title":"Examples","text":"","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#rescheduling-late-flow-runs","title":"Rescheduling late flow runs","text":"<p>Sometimes, you may need to bulk reschedule flow runs that are late - for example, if you've accidentally scheduled many flow runs of a deployment to an inactive work pool.</p> <p>To do this, we can delete late flow runs and create new ones in a <code>Scheduled</code> state with a delay.</p> <p>This example reschedules the last 3 late flow runs of a deployment named <code>healthcheck-storage-test</code> to run 6 hours later than their original expected start time. It also deletes any remaining late flow runs of that deployment.</p> <pre><code>import asyncio\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Optional\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import (\n    DeploymentFilter, FlowRunFilter\n)\nfrom prefect.client.schemas.objects import FlowRun\nfrom prefect.client.schemas.sorting import FlowRunSort\nfrom prefect.states import Scheduled\n\nasync def reschedule_late_flow_runs(\n    deployment_name: str,\n    delay: timedelta,\n    most_recent_n: int,\n    delete_remaining: bool = True,\n    states: Optional[list[str]] = None\n) -&gt; list[FlowRun]:\n    if not states:\n        states = [\"Late\"]\n\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=dict(name=dict(any_=states)),\n                expected_start_time=dict(\n                    before_=datetime.now(timezone.utc)\n                ),\n            ),\n            deployment_filter=DeploymentFilter(\n                name={'like_': deployment_name}\n            ),\n            sort=FlowRunSort.START_TIME_DESC,\n            limit=most_recent_n if not delete_remaining else None\n        )\n\n        if not flow_runs:\n            print(f\"No flow runs found in states: {states!r}\")\n            return []\n\n        rescheduled_flow_runs = []\n        for i, run in enumerate(flow_runs):\n            await client.delete_flow_run(flow_run_id=run.id)\n            if i &lt; most_recent_n:\n                new_run = await client.create_flow_run_from_deployment(\n                    deployment_id=run.deployment_id,\n                    state=Scheduled(\n                        scheduled_time=run.expected_start_time + delay\n                    ),\n                )\n                rescheduled_flow_runs.append(new_run)\n\n        return rescheduled_flow_runs\n\nif __name__ == \"__main__\":\n    rescheduled_flow_runs = asyncio.run(\n        reschedule_late_flow_runs(\n            deployment_name=\"healthcheck-storage-test\",\n            delay=timedelta(hours=6),\n            most_recent_n=3,\n        )\n    )\n\n    print(f\"Rescheduled {len(rescheduled_flow_runs)} flow runs\")\n\n    assert all(\n        run.state.is_scheduled() for run in rescheduled_flow_runs\n    )\n    assert all(\n        run.expected_start_time &gt; datetime.now(timezone.utc)\n        for run in rescheduled_flow_runs\n    )\n</code></pre>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#get-the-last-n-completed-flow-runs-from-my-workspace","title":"Get the last <code>N</code> completed flow runs from my workspace","text":"<p>To get the last <code>N</code> completed flow runs from our workspace, we can make use of <code>read_flow_runs</code> and <code>prefect.client.schemas</code>.</p> <p>This example gets the last three completed flow runs from our workspace:</p> <pre><code>import asyncio\nfrom typing import Optional\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import FlowRunFilter\nfrom prefect.client.schemas.objects import FlowRun\nfrom prefect.client.schemas.sorting import FlowRunSort\n\nasync def get_most_recent_flow_runs(\n    n: int = 3,\n    states: Optional[list[str]] = None\n) -&gt; list[FlowRun]:\n    if not states:\n        states = [\"COMPLETED\"]\n\n    async with get_client() as client:\n        return await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state={'type': {'any_': states}}\n            ),\n            sort=FlowRunSort.END_TIME_DESC,\n            limit=n,\n        )\n\nif __name__ == \"__main__\":\n    last_3_flow_runs: list[FlowRun] = asyncio.run(\n        get_most_recent_flow_runs()\n    )\n    print(last_3_flow_runs)\n\n    assert all(\n        run.state.is_completed() for run in last_3_flow_runs\n    )\n    assert (\n        end_times := [run.end_time for run in last_3_flow_runs]\n    ) == sorted(end_times, reverse=True)\n</code></pre> <p>Instead of the last three from the whole workspace, you could also use the <code>DeploymentFilter</code> like the previous example to get the last three completed flow runs of a specific deployment.</p>","tags":["client","API","filters","orchestration"]},{"location":"guides/using-the-client/#transition-all-running-flows-to-cancelled-via-the-client","title":"Transition all running flows to cancelled via the Client","text":"<p>It can be cumbersome to cancel many flow runs through the UI.  You can use <code>get_client</code>to set multiple runs to a <code>Cancelled</code> state. The code below will cancel all flow runs that are in <code>Pending</code>, <code>Running</code>, <code>Scheduled</code>, or <code>Late</code> states when the script is run. <pre><code>import anyio\n\nfrom prefect import get_client\nfrom prefect.client.schemas.filters import FlowRunFilter, FlowRunFilterState, FlowRunFilterStateName\nfrom prefect.client.schemas.objects import StateType\n\nasync def list_flow_runs_with_states(states: list[str]):\n    async with get_client() as client:\n        flow_runs = await client.read_flow_runs(\n            flow_run_filter=FlowRunFilter(\n                state=FlowRunFilterState(\n                    name=FlowRunFilterStateName(any_=states)\n                )\n            )\n        )\n    return flow_runs\n\n\nasync def cancel_flow_runs(flow_runs):\n    async with get_client() as client:\n        for idx, flow_run in enumerate(flow_runs):\n            print(f\"[{idx + 1}] Cancelling flow run '{flow_run.name}' with ID '{flow_run.id}'\")\n            state_updates = {}\n            state_updates.setdefault(\"name\", \"Cancelled\")\n            state_updates.setdefault(\"type\", StateType.CANCELLED)\n            state = flow_run.state.copy(update=state_updates)\n            await client.set_flow_run_state(flow_run.id, state, force=True)\n\n\nasync def bulk_cancel_flow_runs():\n    states = [\"Pending\", \"Running\", \"Scheduled\", \"Late\"]\n    flow_runs = await list_flow_runs_with_states(states)\n\n    while len(flow_runs) &gt; 0:\n        print(f\"Cancelling {len(flow_runs)} flow runs\\n\")\n        await cancel_flow_runs(flow_runs)\n        flow_runs = await list_flow_runs_with_states(states)\n    print(\"Done!\")\n\n\nif __name__ == \"__main__\":\n    anyio.run(bulk_cancel_flow_runs)\n</code></pre></p> <p>There are other ways to filter objects like flow runs</p> <p>See <code>the filters API reference</code> for more ways to filter flow runs and other objects in your Prefect ecosystem.</p>","tags":["client","API","filters","orchestration"]},{"location":"guides/variables/","title":"Variables","text":"<p>Variables enable you to store and reuse non-sensitive bits of data, such as configuration information. Variables are named, mutable string values, much like environment variables. Variables are scoped to a Prefect server instance or a single workspace in Prefect Cloud.</p> <p>Variables can be created or modified at any time, but are intended for values with infrequent writes and frequent reads. Variable values may be cached for quicker retrieval.</p> <p>While variable values are most commonly loaded during flow runtime, they can be loaded in other contexts, at any time, such that they can be used to pass configuration information to Prefect configuration files, such as deployment steps.</p> <p>Variables are not Encrypted</p> <p>Using variables to store sensitive information, such as credentials, is not recommended. Instead, use Secret blocks to store and access sensitive information.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#managing-variables","title":"Managing variables","text":"<p>You can create, read, edit and delete variables via the Prefect UI, API, and CLI. Names must adhere to traditional variable naming conventions:</p> <ul> <li>Have no more than 255 characters.</li> <li>Only contain lowercase alphanumeric characters ([a-z], [0-9]) or underscores (_). Spaces are not allowed.</li> <li>be unique.</li> </ul> <p>Values must:</p> <ul> <li>have less than or equal to 5000 characters.</li> </ul> <p>Optionally, you can add tags to the variable.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-prefect-ui","title":"Via the Prefect UI","text":"<p>You can see all the variables in your Prefect server instance or Prefect Cloud workspace on the Variables page of the Prefect UI. Both the name and value of all variables are visible to anyone with access to the server or workspace.</p> <p>To create a new variable, select the + button next to the header of the Variables page. Enter the name and value of the variable.</p> <p></p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-rest-api","title":"Via the REST API","text":"<p>Variables can be created and deleted via the REST API. You can also set and get variables via the API with either the variable name or ID. See the REST reference for more information.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#via-the-cli","title":"Via the CLI","text":"<p>You can list, inspect, and delete variables via the command line interface with the <code>prefect variable ls</code>, <code>prefect variable inspect &lt;name&gt;</code>, and <code>prefect variable delete &lt;name&gt;</code> commands, respectively.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#accessing-variables","title":"Accessing variables","text":"<p>In addition to the UI and API, variables can be referenced in code and in certain Prefect configuration files.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#in-python-code","title":"In Python code","text":"<p>You can access any variable via the Python SDK via the <code>Variable.get()</code> method. If you attempt to reference a variable that does not exist, the method will return <code>None</code>. You can create variables via the Python SDK with the <code>Variable.set()</code> method. Note that if a variable of the same name exists, you'll need to pass <code>overwrite=True</code>.</p> <pre><code>from prefect.variables import Variable\n\n# setting the variable\nvariable = Variable.set(name=\"the_answer\", value=\"42\")\n\n# getting from a synchronous context\nanswer = Variable.get('the_answer')\nprint(answer.value)\n# 42\n\n# getting from an asynchronous context\nanswer = await Variable.get('the_answer')\nprint(answer.value)\n# 42\n\n# getting without a default value\nanswer = Variable.get('not_the_answer')\nprint(answer.value)\n# None\n\n# getting with a default value\nanswer = Variable.get('not_the_answer', default='42')\nprint(answer.value)\n# 42\n\n# using `overwrite=True`\nanswer = Variable.get('the_answer')\nprint(answer.value)\n#42\nanswer = Variable.set(name=\"the_answer\", value=\"43\", overwrite=True)\nprint(answer.value)\n#43\n</code></pre>","tags":["variables","blocks"],"boost":2},{"location":"guides/variables/#in-prefectyaml-deployment-steps","title":"In <code>prefect.yaml</code> deployment steps","text":"<p>In <code>.yaml</code> files, variables are denoted by quotes and double curly brackets, like so: <code>\"{{ prefect.variables.my_variable }}\"</code>. You can use variables to templatize deployment steps by referencing them in the <code>prefect.yaml</code> file used to create deployments. For example, you could pass a variable in to specify a branch for a git repo in a deployment <code>pull</code> step:</p> <pre><code>pull:\n- prefect.deployments.steps.git_clone:\n    repository: https://github.com/PrefectHQ/hello-projects.git\n    branch: \"{{ prefect.variables.deployment_branch }}\"\n</code></pre> <p>The <code>deployment_branch</code> variable will be evaluated at runtime for the deployed flow, allowing changes to be made to variables used in a pull action without updating a deployment directly.</p>","tags":["variables","blocks"],"boost":2},{"location":"guides/webhooks/","title":"Webhooks","text":"<p>Use webhooks in your Prefect Cloud workspace to receive, observe, and react to events from other systems in your ecosystem.  Each webhook exposes a unique URL endpoint to receive events from other systems and transforms them into Prefect events for use in automations.</p> <p>Webhooks are defined by two essential components: a unique URL and a template that translates incoming web requests to a Prefect event.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#configuring-webhooks","title":"Configuring webhooks","text":"","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-the-prefect-cloud-api","title":"Via the Prefect Cloud API","text":"<p>Webhooks are managed via the Webhooks API endpoints.  This is a Prefect Cloud-only feature. You authenticate API calls using the standard authentication methods you use with Prefect Cloud.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-prefect-cloud","title":"Via Prefect Cloud","text":"<p>Webhooks can be created and managed from the Prefect Cloud UI.</p> <p></p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#via-the-prefect-cli","title":"Via the Prefect CLI","text":"<p>Webhooks can be managed and interacted with via the <code>prefect cloud webhook</code> command group.</p> <pre><code>prefect cloud webhook --help\n</code></pre> <p>You can create your first webhook by invoking <code>create</code>:</p> <pre><code>prefect cloud webhook create your-webhook-name \\\n    --description \"Receives webhooks from your system\" \\\n    --template '{ \"event\": \"your.event.name\", \"resource\": { \"prefect.resource.id\": \"your.resource.id\" } }'\n</code></pre> <p>Note the template string, which is discussed in greater detail below</p> <p>You can retrieve details for a specific webhook by ID using <code>get</code>, or optionally query all webhooks in your workspace via <code>ls</code>:</p> <pre><code># get webhook by ID\nprefect cloud webhook get &lt;webhook-id&gt;\n\n# list all configured webhooks in your workspace\n\nprefect cloud webhook ls\n</code></pre> <p>If you need to disable an existing webhook without deleting it, use <code>toggle</code>:</p> <pre><code>prefect cloud webhook toggle &lt;webhook-id&gt;\nWebhook is now disabled\n\nprefect cloud webhook toggle &lt;webhook-id&gt;\nWebhook is now enabled\n</code></pre> <p>If you are concerned that your webhook endpoint may have been compromised, use <code>rotate</code> to generate a new, random endpoint</p> <pre><code>prefect cloud webhook rotate &lt;webhook-url-slug&gt;\n</code></pre>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#webhook-endpoints","title":"Webhook endpoints","text":"<p>The webhook endpoints have randomly generated opaque URLs that do not divulge any information about your Prefect Cloud workspace.  They are rooted at <code>https://api.prefect.cloud/hooks/</code>. For example: <code>https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ</code>. Prefect Cloud assigns this URL when you create a webhook; it cannot be set via the API. You may rotate your webhook URL at any time without losing the associated configuration.</p> <p>All webhooks may accept requests via the most common HTTP methods:</p> <ul> <li><code>GET</code>, <code>HEAD</code>, and <code>DELETE</code> may be used for webhooks that define a static event   template, or a template that does not depend on the body of the HTTP request.  The   headers of the request will be available for templates.</li> <li><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> may be used when the webhook request will include a body.   See How HTTP request components are   handled for more details on how the body is   parsed.</li> </ul> <p>Prefect Cloud webhooks are deliberately quiet to the outside world, and will only return a <code>204 No Content</code> response when they are successful, and a <code>400 Bad Request</code> error when there is any error interpreting the request.  For more visibility when your webhooks fail, see the Troubleshooting section below.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#webhook-templates","title":"Webhook templates","text":"<p>The purpose of a webhook is to accept an HTTP request from another system and produce a Prefect event from it.  You may find that you often have little influence or control over the format of those requests, so Prefect's webhook system gives you full control over how you turn those notifications from other systems into meaningful events in your Prefect Cloud workspace.  The template you define for each webhook will determine how individual components of the incoming HTTP request become the event name and resource labels of the resulting Prefect event.</p> <p>As with the templates available in Prefect Cloud Automation for defining notifications and other parameters, you will write templates in Jinja2.  All of the built-in Jinja2 blocks and filters are available, as well as the filters from the <code>jinja2-humanize-extensions</code> package.</p> <p>Your goal when defining your event template is to produce a valid JSON object that defines (at minimum) the <code>event</code> name and the <code>resource[\"prefect.resource.id\"]</code>, which are required of all events.  The simplest template is one in which these are statically defined.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#static-webhook-events","title":"Static webhook events","text":"<p>Let's see a static webhook template example.  Say you want to configure a webhook that will notify Prefect when your <code>recommendations</code> machine learning model has been updated, so you can then send a Slack notification to your team and run a few subsequent deployments.  Those models are produced on a daily schedule by another team that is using <code>cron</code> for scheduling. They aren't able to use Prefect for their flows (yet!), but they are happy to add a <code>curl</code> to the end of their daily script to notify you. Because this webhook will only be used for a single event from a single resource, your template can be entirely static:</p> <pre><code>{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.recommendations\",\n        \"prefect.resource.name\": \"Recommendations [Products]\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>Make sure to produce valid JSON</p> <p>The output of your template, when rendered, should be a valid string that can be parsed, for example, with <code>json.loads</code>.</p> <p>A webhook with this template may be invoked via any of the HTTP methods, including a <code>GET</code> request with no body, so the team you are integrating with can include this line at the end of their daily script:</p> <pre><code>curl https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ\n</code></pre> <p>Each time the script hits the webhook, the webhook will produce a single Prefect event with that name and resource in your workspace.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#event-fields-that-prefect-cloud-populates-for-you","title":"Event fields that Prefect Cloud populates for you","text":"<p>You may notice that you only had to provide the <code>event</code> and <code>resource</code> definition, which is not a completely fleshed out event.  Prefect Cloud will set default values for any missing fields, such as <code>occurred</code> and <code>id</code>, so you don't need to set them in your template.  Additionally, Prefect Cloud will add the webhook itself as a related resource on all of the events it produces.</p> <p>If your template does not produce a <code>payload</code> field, the <code>payload</code> will default to a standard set of debugging information, including the HTTP method, headers, and body.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#dynamic-webhook-events","title":"Dynamic webhook events","text":"<p>Now let's say that after a few days you and the Data Science team are getting a lot of value from the automations you have set up with the static webhook.  You've agreed to upgrade this webhook to handle all of the various models that the team produces.  It's time to add some dynamic information to your webhook template.</p> <p>Your colleagues on the team have adjusted their daily <code>cron</code> scripts to <code>POST</code> a small body that includes the ID and name of the model that was updated:</p> <pre><code>curl \\\n    -d \"model=recommendations\" \\\n    -d \"friendly_name=Recommendations%20[Products]\" \\\n    -X POST https://api.prefect.cloud/hooks/AERylZ_uewzpDx-8fcweHQ\n</code></pre> <p>This script will send a <code>POST</code> request and the body will include a traditional URL-encoded form with two fields describing the model that was updated: <code>model</code> and <code>friendly_name</code>. Here's the webhook code that uses Jinja to receive these values in your template and produce different events for the different models:</p> <pre><code>{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.{{ body.model }}\",\n        \"prefect.resource.name\": \"{{ body.friendly_name }}\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>All subsequent <code>POST</code> requests will produce events with those variable resource IDs and names.  The other statically-defined parts, such as <code>event</code> or the <code>producing-team</code> label you included earlier will still be used.</p> <p>Use Jinja2's <code>default</code> filter to handle missing values</p> <p>Jinja2 has a helpful <code>default</code> filter that can compensate for missing values in the request.  In this example, you may want to use the model's ID in place of the friendly name when the friendly name is not provided: <code>{{ body.friendly_name|default(body.model) }}</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#how-http-request-components-are-handled","title":"How HTTP request components are handled","text":"<p>The Jinja2 template context includes the three parts of the incoming HTTP request:</p> <ul> <li><code>method</code> is the uppercased string of the HTTP method, like <code>GET</code> or <code>POST</code>.</li> <li><code>headers</code> is a case-insensitive dictionary of the HTTP headers included with the   request.  To prevent accidental disclosures, the <code>Authorization</code> header is removed.</li> <li><code>body</code> represents the body that was posted to the webhook, with a best-effort approach   to parse it into an object you can access.</li> </ul> <p>HTTP headers are available without any alteration as a <code>dict</code>-like object, but you may access them with header names in any case.  For example, these template expressions all return the value of the <code>Content-Length</code> header:</p> <pre><code>{{ headers['Content-Length'] }}\n\n{{ headers['content-length'] }}\n\n{{ headers['CoNtEnt-LeNgTh'] }}\n</code></pre> <p>The HTTP request body goes through some light preprocessing to make it more useful in templates.  If the <code>Content-Type</code> of the request is <code>application/json</code>, the body will be parsed as a JSON object and made available to the webhook templates.  If the <code>Content-Type</code> is <code>application/x-www-form-urlencoded</code> (as in our example above), the body is parsed into a flat <code>dict</code>-like object of key-value pairs.  Jinja2 supports both index and attribute access to the fields of these objects, so the following two expressions are equivalent:</p> <pre><code>{{ body['friendly_name'] }}\n\n{{ body.friendly_name }}\n</code></pre> <p>Only for Python identifiers</p> <p>Jinja2's syntax only allows attribute-like access if the key is a valid Python identifier, so <code>body.friendly-name</code> will not work.  Use <code>body['friendly-name']</code> in those cases.</p> <p>You may not have much control over the client invoking your webhook, but would still like for bodies that look like JSON to be parsed as such.  Prefect Cloud will attempt to parse any other content type (like <code>text/plain</code>) as if it were JSON first.  In any case where the body cannot be transformed into JSON, it will be made available to your templates as a Python <code>str</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#accepting-prefect-events-directly","title":"Accepting Prefect events directly","text":"<p>In cases where you have more control over the client, your webhook can accept Prefect events directly with a simple pass-through template:</p> <pre><code>{{ body|tojson }}\n</code></pre> <p>This template accepts the incoming body (assuming it was in JSON format) and just passes it through unmodified.  This allows a <code>POST</code> of a partial Prefect event as in this example:</p> <pre><code>POST /hooks/AERylZ_uewzpDx-8fcweHQ HTTP/1.1\nHost: api.prefect.cloud\nContent-Type: application/json\nContent-Length: 228\n\n{\n    \"event\": \"model.refreshed\",\n    \"resource\": {\n        \"prefect.resource.id\": \"product.models.recommendations\",\n        \"prefect.resource.name\": \"Recommendations [Products]\",\n        \"producing-team\": \"Data Science\"\n    }\n}\n</code></pre> <p>The resulting event will be filled out with the default values for <code>occurred</code>, <code>id</code>, and other fields as described above.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#accepting-cloudevents","title":"Accepting CloudEvents","text":"<p>The Cloud Native Computing Foundation has standardized CloudEvents for use by systems to exchange event information in a common format.  These events are supported by major cloud providers and a growing number of cloud-native systems.  Prefect Cloud can interpret a webhook containing a CloudEvent natively with the following template:</p> <pre><code>{{ body|from_cloud_event(headers) }}\n</code></pre> <p>The resulting event will use the CloudEvent's <code>subject</code> as the resource (or the <code>source</code> if no <code>subject</code> is available).  The CloudEvent's <code>data</code> attribute will become the Prefect event's <code>payload['data']</code>, and the other CloudEvent metadata will be at <code>payload['cloudevents']</code>.  If you would like to handle CloudEvents in a more specific way tailored to your use case, use a dynamic template to interpret the incoming <code>body</code>.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/webhooks/#troubleshooting","title":"Troubleshooting","text":"<p>The initial configuration of your webhook may require some trial and error as you get the sender and your receiving webhook speaking a compatible language.  While you are in this phase, you may find the Event Feed in the UI to be indispensable for seeing the events as they are happening.</p> <p>When Prefect Cloud encounters an error during receipt of a webhook, it will produce a <code>prefect-cloud.webhook.failed</code> event in your workspace.  This event will include critical information about the HTTP method, headers, and body it received, as well as what the template rendered.  Keep an eye out for these events when something goes wrong.</p>","tags":["events","automations","triggers","webhooks","Prefect Cloud"]},{"location":"guides/deployment/aci/","title":"Run an Agent with Azure Container Instances","text":"<p>Microsoft Azure Container Instances (ACI) provides a convenient and simple service for quickly spinning up a Docker container that can host a Prefect Agent and execute flow runs.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#prerequisites","title":"Prerequisites","text":"<p>To follow this quickstart, you'll need the following:</p> <ul> <li>A Prefect Cloud account</li> <li>A Prefect Cloud API key (Prefect Cloud Pro and Custom tier accounts can use a service account API key)</li> <li>A Microsoft Azure account</li> <li>Azure CLI installed and authenticated</li> </ul>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-a-resource-group","title":"Create a resource group","text":"<p>Like most Azure resources, ACI applications must live in a resource group. If you don\u2019t already have a resource group you\u2019d like to use, create a new one by running the <code>az group create</code> command. For example, this example creates a resource group called <code>prefect-agents</code> in the <code>eastus</code> region:</p> <pre><code>az group create --name prefect-agents --location eastus\n</code></pre> <p>Feel free to change the group name or location to match your use case. You can also run <code>az account list-locations -o table</code> to see all available resource group locations for your account.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-the-container-instance","title":"Create the container instance","text":"<p>Prefect provides pre-configured Docker images you can use to quickly stand up a container instance. These Docker images include Python and Prefect. For example, the image <code>prefecthq/prefect:2-python3.10</code> includes the latest release version of Prefect and Python 3.10.</p> <p>To create the container instance, use the <code>az container create</code> command. This example shows the syntax, but you'll need to provide the correct values for <code>[ACCOUNT-ID]</code>,<code>[WORKSPACE-ID]</code>, <code>[API-KEY]</code>, and any dependencies you need to <code>pip install</code> on the instance. These options are discussed below.</p> <pre><code>az container create \\\n--resource-group prefect-agents \\\n--name prefect-agent-example \\\n--image prefecthq/prefect:2-python3.10 \\\n--secure-environment-variables PREFECT_API_URL='https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]' PREFECT_API_KEY='[API-KEY]' \\\n--command-line \"/bin/bash -c 'pip install adlfs s3fs requests pandas; prefect agent start -p default-agent-pool -q test'\"\n</code></pre> <p>When the container instance is running, go to Prefect Cloud and select the Work Pools page. Select default-agent-pool, then select the Queues tab to see work queues configured on this work pool. When the container instance is running and the agent has started, the <code>test</code> work queue displays \"Healthy\" status. This work queue and agent are ready to execute deployments configured to run on the <code>test</code> queue.</p> <p></p> <p>Agents and queues</p> <p>The agent running in this container instance can now pick up and execute flow runs for any deployment configured to use the <code>test</code> queue on the <code>default-agent-pool</code> work pool.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#container-create-options","title":"Container create options","text":"<p>Let's break down the details of the <code>az container create</code> command used here.</p> <p>The <code>az container create command</code> creates a new ACI container.</p> <p><code>--resource-group prefect-agents</code> tells Azure which resource group the new container is created in. Here, the examples uses the <code>prefect-agents</code> resource group created earlier.</p> <p><code>--name prefect-agent-example</code> determines the container name you will see in the Azure Portal. You can set any name you\u2019d like here to suit your use case, but container instance names must be unique in your resource group.</p> <p><code>--image prefecthq/prefect:2-python3.10</code> tells ACI which Docker images to run. The script above pulls a public Prefect image from Docker Hub. You can also build custom images and push them to a public container registry so ACI can access them. Or you can push your image to a private Azure Container Registry and use it to create a container instance.</p> <p><code>--secure-environment-variables</code> sets environment variables that are only visible from inside the container. They do not show up when viewing the container\u2019s metadata. You'll populate these environment variables with a few pieces of information to configure the execution environment of the container instance so it can communicate with your Prefect Cloud workspace:</p> <ul> <li>A Prefect Cloud [<code>PREFECT_API_KEY</code>]/concepts/settings/#prefect_api_key) value specifying the API key used to authenticate with your Prefect Cloud workspace. (Pro and Custom tier accounts can use a service account API key.)</li> <li>The <code>PREFECT_API_URL</code> value specifying the API endpoint of your Prefect Cloud workspace.</li> </ul> <p><code>--command-line</code> lets you override the container\u2019s normal entry point and run a command instead. The script above uses this section to install the <code>adlfs</code> pip package so it can read flow code from Azure Blob Storage, along with <code>s3fs</code>, <code>pandas</code>, and <code>requests</code>. It then runs the Prefect agent, in this case using the default work pool and a <code>test</code> work queue. If you want to use a different work pool or queue, make sure to change these values appropriately.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#create-a-deployment","title":"Create a deployment","text":"<p>Following the example of the Flow deployments tutorial, let's create a deployment that can be executed by the agent on this container instance.</p> <p>In an environment where you have installed Prefect, create a new folder called <code>health_test</code>, and within it create a new file called <code>health_flow.py</code> containing the following code.</p> <pre><code>import prefect\nfrom prefect import task, flow\nfrom prefect import get_run_logger\n\n\n@task\ndef say_hi():\n    logger = get_run_logger()\n    logger.info(\"Hello from the Health Check Flow! \ud83d\udc4b\")\n\n\n@task\ndef log_platform_info():\n    import platform\n    import sys\n    from prefect.server.api.server import SERVER_API_VERSION\n\n    logger = get_run_logger()\n    logger.info(\"Host's network name = %s\", platform.node())\n    logger.info(\"Python version = %s\", platform.python_version())\n    logger.info(\"Platform information (instance type) = %s \", platform.platform())\n    logger.info(\"OS/Arch = %s/%s\", sys.platform, platform.machine())\n    logger.info(\"Prefect Version = %s \ud83d\ude80\", prefect.__version__)\n    logger.info(\"Prefect API Version = %s\", SERVER_API_VERSION)\n\n\n@flow(name=\"Health Check Flow\")\ndef health_check_flow():\n    hi = say_hi()\n    log_platform_info(wait_for=[hi])\n</code></pre> <p>Now create a deployment for this flow script, making sure that it's configured to use the <code>test</code> queue on the <code>default-agent-pool</code> work pool.</p> <pre><code>prefect deployment build --infra process --storage-block azure/flowsville/health_test --name health-test --pool default-agent-pool --work-queue test --apply health_flow.py:health_check_flow\n</code></pre> <p>Once created, any flow runs for this deployment will be picked up by the agent running on this container instance.</p> <p>Infrastructure and storage</p> <p>This Prefect deployment example was built using the <code>Process</code> infrastructure type and Azure Blob Storage.</p> <p>You might wonder why your deployment needs process infrastructure rather than <code>DockerContainer</code> infrastructure when you are deploying a Docker image to ACI.</p> <p>A Prefect deployment\u2019s infrastructure type describes how you want Prefect agents to run flows for the deployment. With <code>DockerContainer</code> infrastructure, the agent will try to use Docker to spin up a new container for each flow run. Since you\u2019ll be starting your own container on ACI, you don\u2019t need Prefect to do it for you. Specifying process infrastructure on the deployment tells Prefect you want to agent to run flows by starting a process in your ACI container.</p> <p>You can use any storage type as long as you've configured a block for it before creating the deployment.</p>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/aci/#cleaning-up","title":"Cleaning up","text":"<p>Note that ACI instances may incur usage charges while running, but must be running for the agent to pick up and execute flow runs.</p> <p>To stop a container, use the <code>az container stop</code> command:</p> <pre><code>az container stop --resource-group prefect-agents --name prefect-agent-example\n</code></pre> <p>To delete a container, use the <code>az container delete</code> command:</p> <pre><code>az container delete --resource-group prefect-agents --name prefect-agent-example\n</code></pre>","tags":["Docker","containers","agents","cloud"],"boost":2},{"location":"guides/deployment/daemonize/","title":"Daemonize Processes for Prefect Deployments","text":"<p>When running workflow applications, it can be helpful to create long-running processes that run at startup and are robust to failure. In this guide you'll learn how to set up a systemd service to create long-running Prefect processes that poll for scheduled flow runs.</p> <p>A systemd service is ideal for running a long-lived process on a Linux VM or physical Linux server. We will leverage systemd and see how to automatically start a Prefect worker or long-lived <code>serve</code> process when Linux starts. This approach provides resilience by automatically restarting the process if it crashes.</p> <p>In this guide we will:</p> <ul> <li>Create a Linux user</li> <li>Install and configure Prefect</li> <li>Set up a systemd service for the Prefect worker or <code>.serve</code> process</li> </ul>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#prerequisites","title":"Prerequisites","text":"<ul> <li>An environment with a linux operating system with systemd and Python 3.8 or later.</li> <li>A superuser account (you can run <code>sudo</code> commands).</li> <li>A Prefect Cloud account, or a local instance of a Prefect server running on your network.</li> <li>If daemonizing a worker, you'll need a Prefect deployment with a work pool your worker can connect to.</li> </ul> <p>If using an AWS t2-micro EC2 instance with an AWS Linux image, you can install Python and pip with <code>sudo yum install -y python3 python3-pip</code>.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-1-add-a-user","title":"Step 1: Add a user","text":"<p>Create a user account on your linux system for the Prefect process. While you can run a worker or serve process as root, it's good security practice to avoid doing so unless you are sure you need to.</p> <p>In a terminal, run:</p> <pre><code>sudo useradd -m prefect\nsudo passwd prefect\n</code></pre> <p>When prompted, enter a password for the <code>prefect</code> account.</p> <p>Next, log in to the <code>prefect</code> account by running:</p> <pre><code>sudo su prefect\n</code></pre>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-2-install-prefect","title":"Step 2: Install Prefect","text":"<p>Run:</p> <pre><code>pip3 install prefect\n</code></pre> <p>This guide assumes you are installing Prefect globally, not in a virtual environment. If running a systemd service in a virtual environment, you'll just need to change the ExecPath. For example, if using venv, change the ExecPath to target the <code>prefect</code> application in the <code>bin</code> subdirectory of your virtual environment.</p> <p>Next, set up your environment so that the Prefect client will know which server to connect to.</p> <p>If connecting to Prefect Cloud, follow the instructions to obtain an API key and then run the following:</p> <pre><code>prefect cloud login -k YOUR_API_KEY\n</code></pre> <p>When prompted, choose the Prefect workspace you'd like to log in to.</p> <p>If connecting to a self-hosted Prefect server instance instead of Prefect Cloud, run the following and substitute the IP address of your server:</p> <pre><code>prefect config set PREFECT_API_URL=http://your-prefect-server-IP:4200\n</code></pre> <p>Finally, run the <code>exit</code> command to sign out of the <code>prefect</code> Linux account. This command switches you back to your sudo-enabled account so you will can run the commands in the next section.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#step-3-set-up-a-systemd-service","title":"Step 3: Set up a systemd service","text":"<p>See the section below if you are setting up a Prefect worker. Skip to the next section if you are setting up a Prefect <code>.serve</code> process.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#setting-up-a-systemd-service-for-a-prefect-worker","title":"Setting up a systemd service for a Prefect worker","text":"<p>Move into the <code>/etc/systemd/system</code> folder and open a file for editing. We use the Vim text editor below.</p> <pre><code>cd /etc/systemd/system\nsudo vim my-prefect-service.service\n</code></pre> my-prefect-service.service<pre><code>[Unit]\nDescription=Prefect worker\n\n[Service]\nUser=prefect\nWorkingDirectory=/home\nExecStart=prefect worker start --pool YOUR_WORK_POOL_NAME\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Make sure you substitute your own work pool name.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#setting-up-a-systemd-service-for-serve","title":"Setting up a systemd service for <code>.serve</code>","text":"<p>Copy your flow entrypoint Python file and any other files needed for your flow to run into the <code>/home</code> directory (or the directory of your choice).</p> <p>Here's a basic example flow:</p> my_file.py<pre><code>from prefect import flow\n\n\n@flow(log_prints=True)\ndef say_hi():\n    print(\"Hello!\")\n\nif __name__==\"__main__\":\n    say_hi.serve(name=\"Greeting from daemonized .serve\")\n</code></pre> <p>If you want to make changes to your flow code without restarting your process, you can push your code to git-based cloud storage (GitHub, BitBucket, GitLab) and use <code>flow.from_source().serve()</code>, as in the example below.</p> my_remote_flow_code_file.py<pre><code>if __name__ == \"__main__\":\nflow.from_source(\n    source=\"https://github.com/org/repo.git\",\n    entrypoint=\"path/to/my_remote_flow_code_file.py:say_hi\",\n).serve(name=\"deployment-with-github-storage\")\n</code></pre> <p>Make sure you substitute your own flow code entrypoint path.</p> <p>Note that if you change the flow entrypoint parameters, you will need to restart the process.</p> <p>Move into the <code>/etc/systemd/system</code> folder and open a file for editing. We use the Vim text editor below.</p> <pre><code>cd /etc/systemd/system\nsudo vim my-prefect-service.service\n</code></pre> my-prefect-service.service<pre><code>[Unit]\nDescription=Prefect serve \n\n[Service]\nUser=prefect\nWorkingDirectory=/home\nExecStart=python3 my_file.py\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n</code></pre>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#save-enable-and-start-the-service","title":"Save, enable, and start the service","text":"<p>To save the file and exit Vim hit the escape key, type <code>:wq!</code>, then press the return key.</p> <p>Next, run <code>sudo systemctl daemon-reload</code> to make systemd aware of your new service.</p> <p>Then, run <code>sudo systemctl enable my-prefect-service</code> to enable the service. This command will ensure it runs when your system boots.</p> <p>Next, run <code>sudo systemctl start my-prefect-service</code> to start the service.</p> <p>Run your deployment from UI and check out the logs on the Flow Runs page.</p> <p>You can see if your daemonized Prefect worker or serve process is running and see the Prefect logs with <code>systemctl status my-prefect-service</code>.</p> <p>That's it! You now have a systemd service that starts when your system boots, and will restart if it ever crashes.</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/daemonize/#next-steps","title":"Next steps","text":"<p>If you want to set up a long-lived process on a Windows machine the pattern is similar. Instead of systemd, you can use NSSM.</p> <p>Check out other Prefect guides to see what else you can do with Prefect!</p>","tags":["systemd","daemonize","worker"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/","title":"Developing a New Worker Type","text":"<p>Advanced Topic</p> <p>This tutorial is for users who want to extend the Prefect framework and completing this successfully will require deep knowledge of Prefect concepts. For standard use cases, we recommend using one of the available workers instead.</p> <p>Prefect workers are responsible for setting up execution infrastructure and starting flow runs on that infrastructure.</p> <p>A list of available workers can be found here. What if you want to execute your flow runs on infrastructure that doesn't have an available worker type? This tutorial will walk you through creating a custom worker that can run your flows on your chosen infrastructure.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-configuration","title":"Worker configuration","text":"<p>When setting up an execution environment for a flow run, a worker receives configuration for the infrastructure it is designed to work with. Examples of configuration values include memory allocation, CPU allocation, credentials, image name, etc. The worker then uses this configuration to create the execution environment and start the flow run.</p> <p>How are the configuration values populated?</p> <p>The work pool that a worker polls for flow runs has a base job template associated with it. The template is the contract for how configuration values populate for each flow run.</p> <p>The keys in the <code>job_configuration</code> section of this base job template match the worker's configuration class attributes. The values in the <code>job_configuration</code> section of the base job template are used to populate the attributes of the worker's configuration class.</p> <p>The work pool creator gets to decide how they want to populate the values in the <code>job_configuration</code> section of the base job template. The values can be hard-coded, templated using placeholders, or a mix of these two approaches. Because you, as the worker developer, don't know how the work pool creator will populate the values, you should set sensible defaults for your configuration class attributes as a matter of best practice.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#implementing-a-basejobconfiguration-subclass","title":"Implementing a <code>BaseJobConfiguration</code> subclass","text":"<p>A worker developer defines their worker's configuration to function with a class extending <code>BaseJobConfiguration</code>.</p> <p><code>BaseJobConfiguration</code> has attributes that are common to all workers:</p> Attribute Description <code>name</code> The name to assign to the created execution environment. <code>env</code> Environment variables to set in the created execution environment. <code>labels</code> The labels assigned to the created execution environment for metadata purposes. <code>command</code> The command to use when starting a flow run. <p>Prefect sets values for each attribute before giving the configuration to the worker. If you want to customize the values of these attributes, use the <code>prepare_for_flow_run</code> method.</p> <p>Here's an example <code>prepare_for_flow_run</code> method that adds a label to the execution environment:</p> <pre><code>def prepare_for_flow_run(\n    self, flow_run, deployment = None, flow = None,\n):  \n    super().prepare_for_flow_run(flow_run, deployment, flow)  \n    self.labels.append(\"my-custom-label\")\n</code></pre> <p>A worker configuration class is a Pydantic model, so you can add additional attributes to your configuration class as Pydantic fields. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseJobConfiguration\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n</code></pre> <p>This configuration class will populate the <code>job_configuration</code> section of the resulting base job template.</p> <p>For this example, the base job template would look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory }}\"\n    cpu: \"{{ cpu }}\"\nvariables:\n    type: object\n    properties:\n        name:\n          title: Name\n          description: Name given to infrastructure created by a worker.\n          type: string\n        env:\n          title: Environment Variables\n          description: Environment variables to set when starting a flow run.\n          type: object\n          additionalProperties:\n            type: string\n        labels:\n          title: Labels\n          description: Labels applied to infrastructure created by a worker.\n          type: object\n          additionalProperties:\n            type: string\n        command:\n          title: Command\n          description: The command to use when starting a flow run. In most cases,\n            this should be left blank and the command will be automatically generated\n            by the worker.\n          type: string\n        memory:\n            title: Memory\n            description: Memory allocation for the execution environment.\n            type: integer\n            default: 1024\n        cpu:\n            title: CPU\n            description: CPU allocation for the execution environment.\n            type: integer\n            default: 500\n</code></pre> <p>This base job template defines what values can be provided by deployment creators on a per-deployment basis and how those provided values will be translated into the configuration values that the worker will use to create the execution environment.</p> <p>Notice that each attribute for the class was added in the <code>job_configuration</code> section with placeholders whose name matches the attribute name. The <code>variables</code> section was also populated with the OpenAPI schema for each attribute. If a configuration class is used without explicitly declaring any template variables, the template variables will be inferred from the configuration class attributes.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#customizing-configuration-attribute-templates","title":"Customizing Configuration Attribute Templates","text":"<p>You can customize the template for each attribute for situations where the configuration values should use more sophisticated templating. For example, if you want to add units for the <code>memory</code> attribute, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseJobConfiguration\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: str = Field(\n            default=\"1024Mi\",\n            description=\"Memory allocation for the execution environment.\"\n            template=\"{{ memory_request }}Mi\"\n        )\n    cpu: str = Field(\n            default=\"500m\", \n            description=\"CPU allocation for the execution environment.\"\n            template=\"{{ cpu_request }}m\"\n        )\n</code></pre> <p>Notice that we changed the type of each attribute to <code>str</code> to accommodate the units, and we added a new <code>template</code> attribute to each attribute. The <code>template</code> attribute is used to populate the <code>job_configuration</code> section of the resulting base job template.</p> <p>For this example, the <code>job_configuration</code> section of the resulting base job template would look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory_request }}Mi\"\n    cpu: \"{{ cpu_request }}m\"\n</code></pre> <p>Note that to use custom templates, you will need to declare the template variables used in the template because the names of those variables can no longer be inferred from the configuration class attributes. We will cover how to declare the default variable schema in the Worker Template Variables section.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#rules-for-template-variable-interpolation","title":"Rules for template variable interpolation","text":"<p>When defining a job configuration model, it's useful to understand how template variables are interpolated into the job configuration. The templating engine follows a few simple rules:</p> <ol> <li>If a template variable is the only value for a key in the <code>job_configuration</code> section, the key will be replaced with the value template variable.</li> <li>If a template variable is part of a string (i.e., there is text before or after the template variable), the value of the template variable will be interpolated into the string.</li> <li>If a template variable is the only value for a key in the <code>job_configuration</code> section and no value is provided for the template variable, the key will be removed from the <code>job_configuration</code> section.</li> </ol> <p>These rules allow worker developers and work pool maintainers to define template variables that can be complex types like dictionaries and lists. These rules also mean that worker developers should give reasonable default values to job configuration fields whenever possible because values are not guaranteed to be provided if template variables are unset.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#template-variable-usage-strategies","title":"Template variable usage strategies","text":"<p>Template variables define the interface that deployment creators interact with to configure the execution environments of their deployments. The complexity of this interface can be controlled via the template variables that are defined for a base job template. This control allows work pool maintainers to find a point along the spectrum of flexibility and simplicity appropriate for their organization.</p> <p>There are two patterns that are represented in current worker implementations:</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#pass-through","title":"Pass-through","text":"<p>In the pass-through pattern, template variables are passed through to the job configuration with little change. This pattern exposes complete control to deployment creators but also requires them to understand the details of the execution environment.</p> <p>This pattern is useful when the execution environment is simple, and the deployment creators are expected to have high technical knowledge.</p> <p>The Docker worker is an example of a worker that uses this pattern.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#infrastructure-as-code-templating","title":"Infrastructure as code templating","text":"<p>Depending on the infrastructure they interact with, workers can sometimes employ a declarative infrastructure syntax (i.e., infrastructure as code) to create execution environments (e.g., a Kubernetes manifest or an ECS task definition).</p> <p>In the IaC pattern, it's often useful to use template variables to template portions of the declarative syntax which then can be used to generate the declarative syntax into a final form.</p> <p>This approach allows work pool creators to provide a simpler interface to deployment creators while also controlling which portions of infrastructure are configurable by deployment creators.</p> <p>The Kubernetes worker is an example of a worker that uses this pattern.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#configuring-credentials","title":"Configuring credentials","text":"<p>When executing flow runs within cloud services, workers will often need credentials to authenticate with those services. For example, a worker that executes flow runs in AWS Fargate will need AWS credentials. As a worker developer, you can use blocks to accept credentials configuration from the user.</p> <p>For example, if you want to allow the user to configure AWS credentials, you can do so like this:</p> <pre><code>from prefect_aws import AwsCredentials\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    aws_credentials: AwsCredentials = Field(\n        default=None,\n        description=\"AWS credentials to use when creating AWS resources.\"\n    )\n</code></pre> <p>Users can create and assign a block to the <code>aws_credentials</code> attribute in the UI and the worker will use these credentials when interacting with AWS resources.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-template-variables","title":"Worker template variables","text":"<p>Providing template variables for a base job template defines the fields that deployment creators can override per deployment. The work pool creator ultimately defines the template variables for a base job template, but the worker developer is able to define default template variables for the worker to make it easier to use.</p> <p>Default template variables for a worker are defined by implementing the <code>BaseVariables</code> class. Like the <code>BaseJobConfiguration</code> class, the <code>BaseVariables</code> class has attributes that are common to all workers:</p> Attribute Description <code>name</code> The name to assign to the created execution environment. <code>env</code> Environment variables to set in the created execution environment. <code>labels</code> The labels assigned the created execution environment for metadata purposes. <code>command</code> The command to use when starting a flow run. <p>Additional attributes can be added to the <code>BaseVariables</code> class to define additional template variables. For example, if you want to allow memory and CPU requests for your worker, you can do so like this:</p> <pre><code>from pydantic import Field\nfrom prefect.workers.base import BaseVariables\n\nclass MyWorkerTemplateVariables(BaseVariables):\n    memory_request: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu_request: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n</code></pre> <p>When <code>MyWorkerTemplateVariables</code> is used in conjunction with <code>MyWorkerConfiguration</code> from the Customizing Configuration Attribute Templates section, the resulting base job template will look like this:</p> <pre><code>job_configuration:\n    name: \"{{ name }}\"\n    env: \"{{ env }}\"\n    labels: \"{{ labels }}\"\n    command: \"{{ command }}\"\n    memory: \"{{ memory_request }}Mi\"\n    cpu: \"{{ cpu_request }}m\"\nvariables:\n    type: object\n    properties:\n        name:\n          title: Name\n          description: Name given to infrastructure created by a worker.\n          type: string\n        env:\n          title: Environment Variables\n          description: Environment variables to set when starting a flow run.\n          type: object\n          additionalProperties:\n            type: string\n        labels:\n          title: Labels\n          description: Labels applied to infrastructure created by a worker.\n          type: object\n          additionalProperties:\n            type: string\n        command:\n          title: Command\n          description: The command to use when starting a flow run. In most cases,\n            this should be left blank and the command will be automatically generated\n            by the worker.\n          type: string\n        memory_request:\n            title: Memory Request\n            description: Memory allocation for the execution environment.\n            type: integer\n            default: 1024\n        cpu_request:\n            title: CPU Request\n            description: CPU allocation for the execution environment.\n            type: integer\n            default: 500\n</code></pre> <p>Note that template variable classes are never used directly. Instead, they are used to generate a schema that is used to populate the <code>variables</code> section of a base job template and validate the template variables provided by the user.</p> <p>We don't recommend using template variable classes within your worker implementation for validation purposes because the work pool creator ultimately defines the template variables. The configuration class should handle any necessary run-time validation.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-implementation","title":"Worker implementation","text":"<p>Workers set up execution environments using provided configuration. Workers also observe the execution environment as the flow run executes and report any crashes to the Prefect API.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#attributes","title":"Attributes","text":"<p>To implement a worker, you must implement the <code>BaseWorker</code> class and provide it with the following attributes:</p> Attribute Description Required <code>type</code> The type of the worker. Yes <code>job_configuration</code> The configuration class for the worker. Yes <code>job_configuration_variables</code> The template variables class for the worker. No <code>_documentation_url</code> Link to documentation for the worker. No <code>_logo_url</code> Link to a logo for the worker. No <code>_description</code> A description of the worker. No","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#methods","title":"Methods","text":"","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#run","title":"<code>run</code>","text":"<p>In addition to the attributes above, you must also implement a <code>run</code> method. The <code>run</code> method is called for each flow run the worker receives for execution from the work pool.</p> <p>The <code>run</code> method has the following signature:</p> <pre><code> async def run(\n        self, flow_run: FlowRun, configuration: BaseJobConfiguration, task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        ...\n</code></pre> <p>The <code>run</code> method is passed: the flow run to execute, the execution environment configuration for the flow run, and a task status object that allows the worker to track whether the flow run was submitted successfully.</p> <p>The <code>run</code> method must also return a <code>BaseWorkerResult</code> object. The <code>BaseWorkerResult</code> object returned contains information about the flow run execution. For the most part, you can implement the <code>BaseWorkerResult</code> with no modifications like so:</p> <pre><code>from prefect.workers.base import BaseWorkerResult\n\nclass MyWorkerResult(BaseWorkerResult):\n    \"\"\"Result returned by the MyWorker.\"\"\"\n</code></pre> <p>If you would like to return more information about a flow run, then additional attributes can be added to the <code>BaseWorkerResult</code> class.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#kill_infrastructure","title":"<code>kill_infrastructure</code>","text":"<p>Workers must implement a <code>kill_infrastructure</code> method to support flow run cancellation. The <code>kill_infrastructure</code> method is called when a flow run is canceled and is passed an identifier for the infrastructure to tear down and the execution environment configuration for the flow run.</p> <p>The <code>infrastructure_pid</code> passed to the <code>kill_infrastructure</code> method is the same identifier used to mark a flow run execution as started in the <code>run</code> method. The <code>infrastructure_pid</code> must be a string, but it can take on any format you choose.</p> <p>The <code>infrastructure_pid</code> should contain enough information to uniquely identify the infrastructure created for a flow run when used with the <code>job_configuration</code> passed to the <code>kill_infrastructure</code> method. Examples of useful information include: the cluster name, the hostname, the process ID, the container ID, etc.</p> <p>If a worker cannot tear down infrastructure created for a flow run, the <code>kill_infrastructure</code> command should raise an <code>InfrastructureNotFound</code> or <code>InfrastructureNotAvailable</code> exception.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#worker-implementation-example","title":"Worker implementation example","text":"<p>Below is an example of a worker implementation. This example is not intended to be a complete implementation but to illustrate the aforementioned concepts.</p> <pre><code>from prefect.workers.base import BaseWorker, BaseWorkerResult, BaseJobConfiguration, BaseVariables\n\nclass MyWorkerConfiguration(BaseJobConfiguration):\n    memory: str = Field(\n            default=\"1024Mi\",\n            description=\"Memory allocation for the execution environment.\"\n            template=\"{{ memory_request }}Mi\"\n        )\n    cpu: str = Field(\n            default=\"500m\", \n            description=\"CPU allocation for the execution environment.\"\n            template=\"{{ cpu_request }}m\"\n        )\n\nclass MyWorkerTemplateVariables(BaseVariables):\n    memory_request: int = Field(\n            default=1024,\n            description=\"Memory allocation for the execution environment.\"\n        )\n    cpu_request: int = Field(\n            default=500, \n            description=\"CPU allocation for the execution environment.\"\n        )\n\nclass MyWorkerResult(BaseWorkerResult):\n    \"\"\"Result returned by the MyWorker.\"\"\"\n\nclass MyWorker(BaseWorker):\n    type = \"my-worker\"\n    job_configuration = MyWorkerConfiguration\n    job_configuration_variables = MyWorkerTemplateVariables\n    _documentation_url = \"https://example.com/docs\"\n    _logo_url = \"https://example.com/logo\"\n    _description = \"My worker description.\"\n\n    async def run(\n        self, flow_run: FlowRun, configuration: BaseJobConfiguration, task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        # Create the execution environment and start execution\n        job = await self._create_and_start_job(configuration)\n\n        if task_status:\n            # Use a unique ID to mark the run as started. This ID is later used to tear down infrastructure\n            # if the flow run is cancelled.\n            task_status.started(job.id) \n\n        # Monitor the execution\n        job_status = await self._watch_job(job, configuration)\n\n        exit_code = job_status.exit_code if job_status else -1 # Get result of execution for reporting\n        return MyWorkerResult(\n            status_code=exit_code,\n            identifier=job.id,\n        )\n\n    async def kill_infrastructure(self, infrastructure_pid: str, configuration: BaseJobConfiguration) -&gt; None:\n        # Tear down the execution environment\n        await self._kill_job(infrastructure_pid, configuration)\n</code></pre> <p>Most of the execution logic is omitted from the example above, but it shows that the typical order of operations in the <code>run</code> method is:     1. Create the execution environment and start the flow run execution     2. Mark the flow run as started via the passed <code>task_status</code> object     3. Monitor the execution     4. Get the execution's final status from the infrastructure and return a <code>BaseWorkerResult</code> object</p> <p>To see other examples of worker implementations, see the <code>ProcessWorker</code> and <code>KubernetesWorker</code> implementations.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/developing-a-new-worker-type/#integrating-with-the-prefect-cli","title":"Integrating with the Prefect CLI","text":"<p>Workers can be started via the Prefect CLI by providing the <code>--type</code> option to the <code>prefect worker start</code> CLI command. To make your worker type available via the CLI, it must be available at import time.</p> <p>If your worker is in a package, you can add an entry point to your setup file in the following format:</p> <pre><code>entry_points={\n    \"prefect.collections\": [\n        \"my_package_name = my_worker_module\",\n    ]\n},\n</code></pre> <p>Prefect will discover this entry point and load your work module in the specified module. The entry point will allow the worker to be available via the CLI.</p>","tags":["work pools","workers","orchestration","flow runs","deployments","storage","infrastructure","tutorial","recipes"],"boost":2},{"location":"guides/deployment/kubernetes/","title":"Running Flows with Kubernetes","text":"<p>This guide will walk you through running your flows on Kubernetes. Though much of the guide is general to any Kubernetes cluster, there are differences between the managed Kubernetes offerings between cloud providers, especially when it comes to container registries and access management. We'll focus on Amazon Elastic Kubernetes Service (EKS).</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#prerequisites","title":"Prerequisites","text":"<p>Before we begin, there are a few pre-requisites:</p> <ol> <li>A Prefect Cloud account</li> <li>A cloud provider (AWS, GCP, or Azure) account</li> <li>Install Python and Prefect</li> <li>Install Helm</li> <li>Install the Kubernetes CLI (kubectl)</li> </ol> <p>Prefect is tested against Kubernetes 1.26.0 and newer minor versions.</p> <p>Administrator Access</p> <p>Though not strictly necessary, you may want to ensure you have admin access, both in Prefect Cloud and in your cloud provider. Admin access is only necessary during the initial setup and can be downgraded after.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-cluster","title":"Create a cluster","text":"<p>Let's start by creating a new cluster. If you already have one, skip ahead to the next section.</p> AWSGCPAzure <p>One easy way to get set up with a cluster in EKS is with <code>eksctl</code>.  Node pools can be backed by either EC2 instances or FARGATE.  Let's choose FARGATE so there's less to manage.  The following command takes around 15 minutes and must not be interrupted:</p> <pre><code># Replace the cluster name with your own value\neksctl create cluster --fargate --name &lt;CLUSTER-NAME&gt;\n\n# Authenticate to the cluster.\naws eks update-kubeconfig --name &lt;CLUSTER-NAME&gt;\n</code></pre> <p>You can get a GKE cluster up and running with a few commands using the <code>gcloud</code> CLI.  We'll build a bare-bones cluster that is accessible over the open internet - this should not be used in a production environment.  To deploy the cluster, your project must have a VPC network configured.</p> <p>First, authenticate to GCP by setting the following configuration options.</p> <pre><code># Authenticate to gcloud\ngcloud auth login\n\n# Specify the project &amp; zone to deploy the cluster to\n# Replace the project name with your GCP project name\ngcloud config set project &lt;GCP-PROJECT-NAME&gt;\ngcloud config set compute/zone &lt;AVAILABILITY-ZONE&gt;\n</code></pre> <p>Next, deploy the cluster - this command will take ~15 minutes to complete.  Once the cluster has been created, authenticate to the cluster.</p> <pre><code># Create cluster\n# Replace the cluster name with your own value\ngcloud container clusters create &lt;CLUSTER-NAME&gt; --num-nodes=1 \\\n--machine-type=n1-standard-2\n\n# Authenticate to the cluster\ngcloud container clusters &lt;CLUSTER-NAME&gt; --region &lt;AVAILABILITY-ZONE&gt;\n</code></pre> <p>GCP Gotchas</p> <ul> <li>You'll need to enable the default service account in the IAM console, or specify a different service account with the appropriate permissions to be used.</li> </ul> <pre><code>ERROR: (gcloud.container.clusters.create) ResponseError: code=400, message=Service account \"000000000000-compute@developer.gserviceaccount.com\" is disabled.\n</code></pre> <ul> <li>Organization policy blocks creation of external (public) IPs. You can override this policy (if you have the appropriate permissions) under the <code>Organizational Policy</code> page within IAM.</li> </ul> <pre><code>creation failed: Constraint constraints/compute.vmExternalIpAccess violated for project 000000000000. Add instance projects/&lt;GCP-PROJECT-NAME&gt;/zones/us-east1-b/instances/gke-gke-guide-1-default-pool-c369c84d-wcfl to the constraint to use external IP with it.\"\n</code></pre> <p>You can quickly create an AKS cluster using the Azure CLI, or use the Cloud Shell directly from the Azure portal shell.azure.com.</p> <p>First, authenticate to Azure if not already done.</p> <pre><code>  az login\n</code></pre> <p>Next, deploy the cluster - this command will take ~4 minutes to complete. Once the cluster has been created, authenticate to the cluster.</p> <pre><code>  # Create a Resource Group at the desired location, e.g. westus\n  az group create --name &lt;RESOURCE-GROUP-NAME&gt; --location &lt;LOCATION&gt;\n\n  # Create a kubernetes cluster with default kubernetes version, default SKU load balancer (Standard) and default vm set type (VirtualMachineScaleSets)\n  az aks create --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt;\n\n  # Configure kubectl to connect to your Kubernetes cluster\n  az aks get-credentials --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt;\n\n  # Verify the connection by listing the cluster nodes\n  kubectl get nodes\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-container-registry","title":"Create a container registry","text":"<p>Besides a cluster, the other critical resource we'll need is a container registry. A registry is not strictly required, but in most cases you'll want to use custom images and/or have more control over where images are stored. If you already have a registry, skip ahead to the next section.</p> AWSGCPAzure <p>Let's create a registry using the AWS CLI and authenticate the docker daemon to said registry:</p> <pre><code># Replace the image name with your own value\naws ecr create-repository --repository-name &lt;IMAGE-NAME&gt;\n\n# Login to ECR\n# Replace the region and account ID with your own values\naws ecr get-login-password --region &lt;REGION&gt; | docker login \\\n  --username AWS --password-stdin &lt;AWS_ACCOUNT_ID&gt;.dkr.ecr.&lt;REGION&gt;.amazonaws.com\n</code></pre> <p>Let's create a registry using the gcloud CLI and authenticate the docker daemon to said registry:</p> <pre><code># Create artifact registry repository to host your custom image\n# Replace the repository name with your own value; it can be the \n# same name as your image\ngcloud artifacts repositories create &lt;REPOSITORY-NAME&gt; \\\n--repository-format=docker --location=us\n\n# Authenticate to artifact registry\ngcloud auth configure-docker us-docker.pkg.dev\n</code></pre> <p>Let's create a registry using the Azure CLI and authenticate the docker daemon to said registry:</p> <pre><code># Name must be a lower-case alphanumeric\n# Tier SKU can easily be updated later, e.g. az acr update --name &lt;REPOSITORY-NAME&gt; --sku Standard\naz acr create --resource-group &lt;RESOURCE-GROUP-NAME&gt; \\\n  --name &lt;REPOSITORY-NAME&gt; \\\n  --sku Basic\n\n# Attach ACR to AKS cluster\n# You need Owner, Account Administrator, or Co-Administrator role on your Azure subscription as per Azure docs\naz aks update --resource-group &lt;RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt; --attach-acr &lt;REPOSITORY-NAME&gt;\n\n# You can verify AKS can now reach ACR\naz aks check-acr --resource-group RESOURCE-GROUP-NAME&gt; --name &lt;CLUSTER-NAME&gt; --acr &lt;REPOSITORY-NAME&gt;.azurecr.io\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-kubernetes-work-pool","title":"Create a Kubernetes work pool","text":"<p>Work pools allow you to manage deployment infrastructure. We'll configure the default values for our Kubernetes base job template. Note that these values can be overridden by individual deployments.</p> <p>Let's switch to the Prefect Cloud UI, where we'll create a new Kubernetes work pool (alternatively, you could use the Prefect CLI to create a work pool).</p> <ol> <li>Click on the Work Pools tab on the left sidebar</li> <li>Click the + button at the top of the page</li> <li>Select Kubernetes as the work pool type</li> <li>Click Next to configure the work pool settings</li> </ol> <p>Let's look at a few popular configuration options.</p> <p>Environment Variables</p> <p>Add environment variables to set when starting a flow run. So long as you are using a Prefect-maintained image and haven't overwritten the image's entrypoint, you can specify Python packages to install at runtime with <code>{\"EXTRA_PIP_PACKAGES\":\"my_package\"}</code>. For example <code>{\"EXTRA_PIP_PACKAGES\":\"pandas==1.2.3\"}</code> will install pandas version 1.2.3. Alternatively, you can specify package installation in a custom Dockerfile, which can allow you to take advantage of image caching. As we'll see below, Prefect can help us create a Dockerfile with our flow code and the packages specified in a <code>requirements.txt</code> file baked in.</p> <p>Namespace</p> <p>Set the Kubernetes namespace to create jobs within, such as <code>prefect</code>. By default, set to default.</p> <p>Image</p> <p>Specify the Docker container image for created jobs. If not set, the latest Prefect 2 image will be used (i.e. <code>prefecthq/prefect:2-latest</code>). Note that you can override this on each deployment through <code>job_variables</code>.</p> <p>Image Pull Policy</p> <p>Select from the dropdown options to specify when to pull the image. When using the <code>IfNotPresent</code> policy, make sure to use unique image tags, as otherwise old images could get cached on your nodes.</p> <p>Finished Job TTL</p> <p>Number of seconds before finished jobs are automatically cleaned up by Kubernetes' controller. You may want to set to 60 so that completed flow runs are cleaned up after a minute.</p> <p>Pod Watch Timeout Seconds</p> <p>Number of seconds for pod creation to complete before timing out. Consider setting to 300, especially if using a serverless type node pool, as these tend to have longer startup times.</p> <p>Kubernetes Cluster Config</p> <p>You can configure the Kubernetes cluster to use for job creation by specifying a <code>KubernetesClusterConfig</code> block. Generally you should leave the cluster config blank as the worker should be provisioned with appropriate access and permissions. Typically this setting is used when a worker is deployed to a cluster that is different from the cluster where flow runs are executed.</p> <p>Advanced Settings</p> <p>Want to modify the default base job template to add other fields or delete existing fields?</p> <p>Select the Advanced tab and edit the JSON representation of the base job template.</p> <p>For example, to set a CPU request, add the following section under variables:</p> <pre><code>\"cpu_request\": {\n  \"title\": \"CPU Request\",\n  \"description\": \"The CPU allocation to request for this pod.\",\n  \"default\": \"default\",\n  \"type\": \"string\"\n},\n</code></pre> <p>Next add the following to the first <code>containers</code> item under <code>job_configuration</code>:</p> <pre><code>...\n\"containers\": [\n  {\n    ...,\n    \"resources\": {\n      \"requests\": {\n        \"cpu\": \"{{ cpu_request }}\"\n      }\n    }\n  }\n],\n...\n</code></pre> <p>Running deployments with this work pool will now request the specified CPU.</p> <p>After configuring the work pool settings, move to the next screen.</p> <p>Give the work pool a name and save.</p> <p>Our new Kubernetes work pool should now appear in the list of work pools.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-prefect-cloud-api-key","title":"Create a Prefect Cloud API key","text":"<p>While in the Prefect Cloud UI, create a Prefect Cloud API key if you don't already have one. Click on your profile avatar picture, then click your name to go to your profile settings, click API Keys and hit the plus button to create a new API key here. Make sure to store it safely along with your other passwords, ideally via a password manager.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#deploy-a-worker-using-helm","title":"Deploy a worker using Helm","text":"<p>With our cluster and work pool created, it's time to deploy a worker, which will set up Kubernetes infrastructure to run our flows. The best way to deploy a worker is using the Prefect Helm Chart.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#add-the-prefect-helm-repository","title":"Add the Prefect Helm repository","text":"<p>Add the Prefect Helm repository to your Helm client:</p> <pre><code>helm repo add prefect https://prefecthq.github.io/prefect-helm\nhelm repo update\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-namespace","title":"Create a namespace","text":"<p>Create a new namespace in your Kubernetes cluster to deploy the Prefect worker:</p> <pre><code>kubectl create namespace prefect\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-kubernetes-secret-for-the-prefect-api-key","title":"Create a Kubernetes secret for the Prefect API key","text":"<pre><code>kubectl create secret generic prefect-api-key \\\n--namespace=prefect --from-literal=key=your-prefect-cloud-api-key\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#configure-helm-chart-values","title":"Configure Helm chart values","text":"<p>Create a <code>values.yaml</code> file to customize the Prefect worker configuration. Add the following contents to the file:</p> <pre><code>worker:\n  cloudApiConfig:\n    accountId: &lt;target account ID&gt;\n    workspaceId: &lt;target workspace ID&gt;\n  config:\n    workPool: &lt;target work pool name&gt;\n</code></pre> <p>These settings will ensure that the worker connects to the proper account, workspace, and work pool.</p> <p>View your Account ID and Workspace ID in your browser URL when logged into Prefect Cloud. For example: https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#create-a-helm-release","title":"Create a Helm release","text":"<p>Let's install the Prefect worker using the Helm chart with your custom <code>values.yaml</code> file:</p> <pre><code>helm install prefect-worker prefect/prefect-worker \\\n  --namespace=prefect \\\n  -f values.yaml\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#verify-deployment","title":"Verify deployment","text":"<p>Check the status of your Prefect worker deployment:</p> <pre><code>kubectl get pods -n prefect\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#define-a-flow","title":"Define a flow","text":"<p>Let's start simple with a flow that just logs a message. In a directory named <code>flows</code>, create a file named <code>hello.py</code> with the following contents:</p> <pre><code>from prefect import flow, get_run_logger, tags\n\n@flow\ndef hello(name: str = \"Marvin\"):\n    logger = get_run_logger()\n    logger.info(f\"Hello, {name}!\")\n\nif __name__ == \"__main__\":\n    with tags(\"local\"):\n        hello()\n</code></pre> <p>Run the flow locally with <code>python hello.py</code> to verify that it works. Note that we use the <code>tags</code> context manager to tag the flow run as <code>local</code>. This step is not required, but does add some helpful metadata.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#define-a-prefect-deployment","title":"Define a Prefect deployment","text":"<p>Prefect has two recommended options for creating a deployment with dynamic infrastructure. You can define a deployment in a Python script using the <code>flow.deploy</code> mechanics or in a <code>prefect.yaml</code> definition file. The <code>prefect.yaml</code> file currently allows for more customization in terms of push and pull steps. Kubernetes objects are defined in YAML, so we expect many teams using Kubernetes work pools to create their deployments with YAML as well. To learn about the Python deployment creation method with <code>flow.deploy</code> refer to the Workers &amp; Work Pools tutorial page.</p> <p>The <code>prefect.yaml</code> file is used by the <code>prefect deploy</code> command to deploy our flows. As a part of that process it will also build and push our image. Create a new file named <code>prefect.yaml</code> with the following contents:</p> <pre><code># Generic metadata about this project\nname: flows\nprefect-version: 2.13.8\n\n# build section allows you to manage and build docker images\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ $PREFECT_IMAGE_NAME }}\"\n    tag: latest\n    dockerfile: auto\n    platform: \"linux/amd64\"\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ build-image.image_name }}\"\n    tag: \"{{ build-image.tag }}\"\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /opt/prefect/flows\n\n# the definitions section allows you to define reusable components for your deployments\ndefinitions:\n  tags: &amp;common_tags\n    - \"eks\"\n  work_pool: &amp;common_work_pool\n    name: \"kubernetes\"\n    job_variables:\n      image: \"{{ build-image.image }}\"\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: \"default\"\n  tags: *common_tags\n  schedule: null\n  entrypoint: \"flows/hello.py:hello\"\n  work_pool: *common_work_pool\n\n- name: \"arthur\"\n  tags: *common_tags\n  schedule: null\n  entrypoint: \"flows/hello.py:hello\"\n  parameters:\n    name: \"Arthur\"\n  work_pool: *common_work_pool\n</code></pre> <p>We define two deployments of the <code>hello</code> flow: <code>default</code> and <code>arthur</code>. Note that by specifying <code>dockerfile: auto</code>, Prefect will automatically create a dockerfile that installs any <code>requirements.txt</code> and copies over the current directory. You can pass a custom Dockerfile instead with <code>dockerfile: Dockerfile</code> or <code>dockerfile: path/to/Dockerfile</code>. Also note that we are specifically building for the <code>linux/amd64</code> platform. This specification is often necessary when images are built on Macs with M series chips but run on cloud provider instances.</p> <p>Deployment specific build, push, and pull</p> <p>The build, push, and pull steps can be overridden for each deployment. This allows for more custom behavior, such as specifying a different image for each deployment.</p> <p>Let's make sure we define our requirements in a <code>requirements.txt</code> file:</p> <pre><code>prefect&gt;=2.13.8\nprefect-docker&gt;=0.4.0\nprefect-kubernetes&gt;=0.3.1\n</code></pre> <p>The directory should now look something like this:</p> <pre><code>.\n\u251c\u2500\u2500 prefect.yaml\n\u2514\u2500\u2500 flows\n    \u251c\u2500\u2500 requirements.txt\n    \u2514\u2500\u2500 hello.py\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#tag-images-with-a-git-sha","title":"Tag images with a Git SHA","text":"<p>If your code is stored in a GitHub repository, it's good practice to tag your images with the Git SHA of the code used to build it. This can be done in the <code>prefect.yaml</code> file with a few minor modifications, and isn't yet an option with the Python deployment creation method. Let's use the <code>run_shell_script</code> command to grab the SHA and pass it to the <code>tag</code> parameter of <code>build_docker_image</code>:</p> <pre><code>build:\n- prefect.deployments.steps.run_shell_script:\n    id: get-commit-hash\n    script: git rev-parse --short HEAD\n    stream_output: false\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build-image\n    requires: prefect-docker&gt;=0.4.0\n    image_name: \"{{ $PREFECT_IMAGE_NAME }}\"\n    tag: \"{{ get-commit-hash.stdout }}\"\n    dockerfile: auto\n    platform: \"linux/amd64\"\n</code></pre> <p>Let's also set the SHA as a tag for easy identification in the UI:</p> <pre><code>definitions:\n  tags: &amp;common_tags\n    - \"eks\"\n    - \"{{ get-commit-hash.stdout }}\"\n  work_pool: &amp;common_work_pool\n    name: \"kubernetes\"\n    job_variables:\n      image: \"{{ build-image.image }}\"\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#authenticate-to-prefect","title":"Authenticate to Prefect","text":"<p>Before we deploy the flows to Prefect, we will need to authenticate via the Prefect CLI. We will also need to ensure that all of our flow's dependencies are present at <code>deploy</code> time.</p> <p>This example uses a virtual environment to ensure consistency across environments.</p> <pre><code># Create a virtualenv &amp; activate it\nvirtualenv prefect-demo\nsource prefect-demo/bin/activate\n\n# Install dependencies of your flow\nprefect-demo/bin/pip install -r requirements.txt\n\n# Authenticate to Prefect &amp; select the appropriate \n# workspace to deploy your flows to\nprefect-demo/bin/prefect cloud login\n</code></pre>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#deploy-the-flows","title":"Deploy the flows","text":"<p>Now we're ready to deploy our flows which will build our images. The image name determines which registry it will end up in. We have configured our <code>prefect.yaml</code> file to get the image name from the <code>PREFECT_IMAGE_NAME</code> environment variable, so let's set that first:</p> AWSGCPAzure <pre><code>export PREFECT_IMAGE_NAME=&lt;AWS_ACCOUNT_ID&gt;.dkr.ecr.&lt;REGION&gt;.amazonaws.com/&lt;IMAGE-NAME&gt;\n</code></pre> <pre><code>export PREFECT_IMAGE_NAME=us-docker.pkg.dev/&lt;GCP-PROJECT-NAME&gt;/&lt;REPOSITORY-NAME&gt;/&lt;IMAGE-NAME&gt;\n</code></pre> <pre><code>export PREFECT_IMAGE_NAME=&lt;REPOSITORY-NAME&gt;.azurecr.io/&lt;IMAGE-NAME&gt;\n</code></pre> <p>To deploy your flows, ensure your Docker daemon is running first. Deploy all the flows with <code>prefect deploy --all</code> or deploy them individually by name: <code>prefect deploy -n hello/default</code> or <code>prefect deploy -n hello/arthur</code>.</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/kubernetes/#run-the-flows","title":"Run the flows","text":"<p>Once the deployments are successfully created, we can run them from the UI or the CLI:</p> <pre><code>prefect deployment run hello/default\nprefect deployment run hello/arthur\n</code></pre> <p>Congratulations! You just ran two deployments in Kubernetes. Head over to the UI to check their status!</p>","tags":["kubernetes","containers","orchestration","infrastructure","deployments"],"boost":2},{"location":"guides/deployment/overriding-job-variables/","title":"Deeper Dive: Overriding Work Pool Job Variables","text":"<p>As described in the Deploying Flows to Work Pools and Workers guide, there are two ways to deploy flows to work pools: using a <code>prefect.yaml</code> file or using the <code>.deploy()</code> method.</p> <p>In both cases, you can override job variables on a work pool for a given deployment.</p> <p>While exactly which job variables are available to be overridden depends on the type of work pool you're using at a given time, this guide will explore some common patterns for overriding job variables in both deployment methods.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#background","title":"Background","text":"<p>First of all, what are \"job variables\"?</p> <p>Job variables are infrastructure related values that are configurable on a work pool, which may be relevant to how your flow run executes on your infrastructure. Job variables can be overridden on a per-deployment or per-flow run basis, allowing you to dynamically change infrastructure from the work pools defaults depending on your needs.</p> <p>Let's use <code>env</code> - the only job variable that is configurable for all work pool types - as an example.</p> <p>When you create or edit a work pool, you can specify a set of environment variables that will be set in the runtime environment of the flow run.</p> <p>For example, you might want a certain deployment to have the following environment variables available: <pre><code>{\n  \"EXECUTION_ENV\": \"staging\",\n  \"MY_NOT_SO_SECRET_CONFIG\": \"plumbus\",\n}\n</code></pre></p> <p>Rather than hardcoding these values into your work pool in the UI and making them available to all deployments associated with that work pool, you can override these values on a per-deployment basis.</p> <p>Let's look at how to do that.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#how-to-override-job-variables-on-a-deployment","title":"How to override job variables on a deployment","text":"<p>Say we have the following repo structure: <pre><code>\u00bb tree\n.\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 demo_project\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 daily_flow.py\n</code></pre></p> <p>... and we have some <code>demo_flow.py</code> file like this:</p> <pre><code>import os\nfrom prefect import flow, task\n\n@task\ndef do_something_important(not_so_secret_value: str) -&gt; None:\n    print(f\"Doing something important with {not_so_secret_value}!\")\n\n@flow(log_prints=True)\ndef some_work():\n    environment = os.environ.get(\"EXECUTION_ENVIRONMENT\", \"local\")\n\n    print(f\"Coming to you live from {environment}!\")\n\n    not_so_secret_value = os.environ.get(\"MY_NOT_SO_SECRET_CONFIG\")\n\n    if not_so_secret_value is None:\n        raise ValueError(\"You forgot to set MY_NOT_SO_SECRET_CONFIG!\")\n\n    do_something_important(not_so_secret_value)\n</code></pre>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-a-prefectyaml-file","title":"Using a <code>prefect.yaml</code> file","text":"<p>In this case, let's also say we have the following deployment definition in a <code>prefect.yaml</code> file at the root of our repository: <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n  schedule: null\n</code></pre></p> <p>Note</p> <p>While not the focus of this guide, note that this deployment definition uses a default \"global\" <code>pull</code> step, because one is not explicitly defined on the deployment. For reference, here's what that would look like at the top of the <code>prefect.yaml</code> file: <pre><code>pull:\n- prefect.deployments.steps.git_clone: &amp;clone_repo\n    repository: https://github.com/some-user/prefect-monorepo\n    branch: main\n</code></pre></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#hard-coded-job-variables","title":"Hard-coded job variables","text":"<p>To provide the <code>EXECUTION_ENVIRONMENT</code> and <code>MY_NOT_SO_SECRET_CONFIG</code> environment variables to this deployment, we can add a <code>job_variables</code> section to our deployment definition in the <code>prefect.yaml</code> file:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n    job_variables:\n        env:\n            EXECUTION_ENVIRONMENT: staging\n            MY_NOT_SO_SECRET_CONFIG: plumbus\n  schedule: null\n</code></pre> <p>... and then run <code>prefect deploy -n demo-deployment</code> to deploy the flow with these job variables.</p> <p>We should then be able to see the job variables in the <code>Configuration</code> tab of the deployment in the UI:</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-existing-environment-variables","title":"Using existing environment variables","text":"<p>If you want to use environment variables that are already set in your local environment, you can template these in the <code>prefect.yaml</code> file using the <code>{{ $ENV_VAR_NAME }}</code> syntax:</p> <pre><code>deployments:\n- name: demo-deployment\n  entrypoint: demo_project/demo_flow.py:some_work\n  work_pool:\n    name: local\n    job_variables:\n        env:\n            EXECUTION_ENVIRONMENT: \"{{ $EXECUTION_ENVIRONMENT }}\"\n            MY_NOT_SO_SECRET_CONFIG: \"{{ $MY_NOT_SO_SECRET_CONFIG }}\"\n  schedule: null\n</code></pre> <p>Note</p> <p>This assumes that the machine where <code>prefect deploy</code> is run would have these environment variables set.</p> <p> <pre><code>export EXECUTION_ENVIRONMENT=staging\nexport MY_NOT_SO_SECRET_CONFIG=plumbus\n</code></pre> </p> <p>As before, run <code>prefect deploy -n demo-deployment</code> to deploy the flow with these job variables, and you should see them in the UI under the <code>Configuration</code> tab.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-deploy-method","title":"Using the <code>.deploy()</code> method","text":"<p>If you're using the <code>.deploy()</code> method to deploy your flow, the process is similar, but instead of having your <code>prefect.yaml</code> file define the job variables, you can pass them as a dictionary to the <code>job_variables</code> argument of the <code>.deploy()</code> method.</p> <p>We could add the following block to our <code>demo_project/daily_flow.py</code> file from the setup section: <pre><code>if __name__ == \"__main__\":\n    flow.from_source(\n        source=\"https://github.com/zzstoatzz/prefect-monorepo.git\",\n        entrypoint=\"src/demo_project/demo_flow.py:some_work\"\n    ).deploy(\n        name=\"demo-deployment\",\n        work_pool_name=\"local\", # can only .deploy() to a local work pool in prefect&gt;=2.15.1\n        job_variables={\n            \"env\": {\n                \"EXECUTION_ENVIRONMENT\": os.environ.get(\"EXECUTION_ENVIRONMENT\", \"local\"),\n                \"MY_NOT_SO_SECRET_CONFIG\": os.environ.get(\"MY_NOT_SO_SECRET_CONFIG\")\n            }\n        }\n    )\n</code></pre></p> <p>Note</p> <p>The above example works assuming a couple things: - the machine where this script is run would have these environment variables set.  <pre><code>export EXECUTION_ENVIRONMENT=staging\nexport MY_NOT_SO_SECRET_CONFIG=plumbus\n</code></pre> </p> <ul> <li><code>demo_project/daily_flow.py</code> already exists in the repository at the specified path</li> </ul> <p>Running this script with something like:</p> <pre><code>python demo_project/daily_flow.py\n</code></pre> <p>... will deploy the flow with the specified job variables, which should then be visible in the UI under the <code>Configuration</code> tab.</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#how-to-override-job-variables-on-a-flow-run","title":"How to override job variables on a flow run","text":"<p>When running flows, you can pass in job variables that override any values set on the work pool or deployment. Any interface that runs deployments can accept job variables.</p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-custom-run-form-in-the-ui","title":"Using the custom run form in the UI","text":"<p>Custom runs allow you to pass in a dictionary of variables into your flow run infrastructure. Using the same <code>env</code> example from above, we could do the following:</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-the-cli","title":"Using the CLI","text":"<p>Similarly, runs kicked off via CLI accept job variables with the <code>-jv</code> or <code>--job-variable</code> flag.</p> <pre><code>prefect deployment run \\\n  --id \"fb8e3073-c449-474b-b993-851fe5e80e53\" \\\n  --job-variable MY_NEW_ENV_VAR=42 \\\n  --job-variable HELLO=THERE\n</code></pre>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/overriding-job-variables/#using-job-variables-in-automations","title":"Using job variables in automations","text":"<p>Additionally, runs kicked off via automation actions can use job variables, including ones rendered from Jinja templates.</p> <p></p>","tags":["deployments","flow runs","work pools","job variables","environment variables"],"boost":2},{"location":"guides/deployment/push-work-pools/","title":"Push Work to Serverless Computing Infrastructure","text":"<p>Push work pools are a special type of work pool that allows Prefect Cloud to submit flow runs for execution to serverless computing infrastructure without running a worker. Push work pools currently support execution in AWS ECS tasks, Azure Container Instances, Google Cloud Run jobs, and Modal.</p> <p>In this guide you will:</p> <ul> <li>Create a push work pool that sends work to Amazon Elastic Container Service (AWS ECS), Azure Container Instances (ACI), Google Cloud Run, or Modal</li> <li>Deploy a flow to that work pool</li> <li>Execute a flow without having to run a worker or agent process to poll for flow runs</li> </ul> <p>You can automatically provision infrastructure and create your push work pool using the <code>prefect work-pool create</code> CLI command with the <code>--provision-infra</code> flag. This approach greatly simplifies the setup process.</p> <p>Let's explore automatic infrastructure provisioning for push work pools first, and then we'll cover how to manually set up your push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#automatic-infrastructure-provisioning","title":"Automatic infrastructure provisioning","text":"<p>With Perfect Cloud you can provision infrastructure for use with an AWS ECS, Google Cloud Run, ACI push work pool. Push work pools in Prefect Cloud simplify the setup and management of the infrastructure necessary to run your flows. However, setting up infrastructure on your cloud provider can still be a time-consuming process. Prefect can dramatically simplify this process by automatically provisioning the necessary infrastructure for you.</p> <p>We'll use the <code>prefect work-pool create</code> CLI command with the <code>--provision-infra</code> flag to automatically provision your serverless cloud resources and set up your Prefect workspace to use a new push pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#prerequisites","title":"Prerequisites","text":"<p>To use automatic infrastructure provisioning, you'll need to have the relevant cloud CLI library installed and to have authenticated with your cloud provider.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Install the AWS CLI, authenticate with your AWS account, and set a default region.</p> <p>If you already have the AWS CLI installed, be sure to update to the latest version. </p> <p>You will need the following permissions in your authenticated AWS account:</p> <p>IAM Permissions:</p> <ul> <li>iam:CreatePolicy</li> <li>iam:GetPolicy</li> <li>iam:ListPolicies</li> <li>iam:CreateUser</li> <li>iam:GetUser</li> <li>iam:AttachUserPolicy</li> <li>iam:CreateRole</li> <li>iam:GetRole</li> <li>iam:AttachRolePolicy</li> <li>iam:ListRoles</li> <li>iam:PassRole</li> </ul> <p>Amazon ECS Permissions:</p> <ul> <li>ecs:CreateCluster</li> <li>ecs:DescribeClusters</li> </ul> <p>Amazon EC2 Permissions:</p> <ul> <li>ec2:CreateVpc</li> <li>ec2:DescribeVpcs</li> <li>ec2:CreateInternetGateway</li> <li>ec2:AttachInternetGateway</li> <li>ec2:CreateRouteTable</li> <li>ec2:CreateRoute</li> <li>ec2:CreateSecurityGroup</li> <li>ec2:DescribeSubnets</li> <li>ec2:CreateSubnet</li> <li>ec2:DescribeAvailabilityZones</li> <li>ec2:AuthorizeSecurityGroupIngress</li> <li>ec2:AuthorizeSecurityGroupEgress</li> </ul> <p>Amazon ECR Permissions:</p> <ul> <li>ecr:CreateRepository</li> <li>ecr:DescribeRepositories</li> <li>ecr:GetAuthorizationToken</li> </ul> <p>If you want to use AWS managed policies, you can use the following:</p> <ul> <li>AmazonECS_FullAccess</li> <li>AmazonEC2FullAccess</li> <li>IAMFullAccess</li> <li>AmazonEC2ContainerRegistryFullAccess</li> </ul> <p>Note that the above policies will give you all the permissions needed, but are more permissive than necessary.</p> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install the Azure CLI and authenticate with your Azure account.</p> <p>If you already have the Azure CLI installed, be sure to update to the latest version with <code>az upgrade</code>.</p> <p>You will also need the following roles in your Azure subscription:</p> <ul> <li>Contributor</li> <li>User Access Administrator</li> <li>Application Administrator</li> <li>Managed Identity Operator</li> <li>Azure Container Registry Contributor</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install the gcloud CLI and authenticate with your GCP project.</p> <p>If you already have the gcloud CLI installed, be sure to update to the latest version with <code>gcloud components update</code>.</p> <p>You will also need the following permissions in your GCP project:</p> <ul> <li>resourcemanager.projects.list</li> <li>serviceusage.services.enable</li> <li>iam.serviceAccounts.create</li> <li>iam.serviceAccountKeys.create</li> <li>resourcemanager.projects.setIamPolicy</li> <li>artifactregistry.repositories.create</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Install <code>modal</code> by running:</p> <p> <pre><code>pip install modal\n</code></pre> </p> <p>Create a Modal API token by running:</p> <p> <pre><code>modal token new\n</code></pre> </p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#automatically-creating-a-new-push-work-pool-and-provisioning-infrastructure","title":"Automatically creating a new push work pool and provisioning infrastructure","text":"<p>Here's the command to create a new push work pool and configure the necessary infrastructure.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <pre><code>prefect work-pool create --type ecs:push --provision-infra my-ecs-pool\n</code></pre> <p>Using the <code>--provision-infra</code> flag will automatically set up your default AWS account to be ready to execute flows via ECS tasks.  In your AWS account, this command will create a new IAM user, IAM policy, ECS cluster that uses AWS Fargate, VPC, and ECR repository if they don't already exist. In your Prefect workspace, this command will create an <code>AWSCredentials</code> block for storing the generated credentials.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-ecs-pool will require:                                          \u2502\n\u2502                                                                                                                   \u2502\n\u2502          - Creating an IAM user for managing ECS tasks: prefect-ecs-user                                          \u2502\n\u2502          - Creating and attaching an IAM policy for managing ECS tasks: prefect-ecs-policy                        \u2502\n\u2502          - Storing generated AWS credentials in a block                                                           \u2502\n\u2502          - Creating an ECS cluster for running Prefect flows: prefect-ecs-cluster                                 \u2502\n\u2502          - Creating a VPC with CIDR 172.31.0.0/16 for running ECS tasks: prefect-ecs-vpc                          \u2502\n\u2502          - Creating an ECR repository for storing Prefect images: prefect-flows                                   \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nProvisioning IAM user\nCreating IAM policy\nGenerating AWS credentials\nCreating AWS credentials block\nProvisioning ECS cluster\nProvisioning VPC\nCreating internet gateway\nSetting up subnets\nSetting up security group\nProvisioning ECR repository\nAuthenticating with ECR\nSetting default Docker build namespace\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-ecs-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new ECR repository and the default Docker build namespace will be set to the URL of the registry.</p> <p>While the default namespace is set, you will not need to provide the registry URL when building images as part of your deployment process.</p> <p>To take advantage of this, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n@flow(log_prints=True)            \ndef my_flow(name: str = \"world\"):                          \n    print(f\"Hello {name}! I'm a flow running in a ECS task!\") \n\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"my-deployment\", \n        work_pool_name=\"my-work-pool\",\n        image=DeploymentImage(                                                 \n            name=\"my-repository:latest\",\n            platform=\"linux/amd64\",\n        )                                                                      \n    )       \n</code></pre> <p>This will build an image with the tag <code>&lt;ecr-registry-url&gt;/my-image:latest</code> and push it to the registry.</p> <p>Your image name will need to match the name of the repository created with your work pool. You can create new repositories in the ECR console.</p> <p><pre><code>prefect work-pool create --type azure-container-instance:push --provision-infra my-aci-pool\n</code></pre> </p> <p>Using the <code>--provision-infra</code> flag will automatically set up your default Azure account to be ready to execute flows via Azure Container Instances. In your Azure account, this command will create a resource group, app registration, service account with necessary permission, generate a secret for the app registration, and create an Azure Container Registry, if they don't already exist. In your Prefect workspace, this command will create an <code>AzureContainerInstanceCredentials</code> block for storing the client secret value from the generated secret.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-aci-work-pool will require:                     \u2502\n\u2502                                                                                           \u2502\n\u2502     Updates in subscription Azure subscription 1                                          \u2502\n\u2502                                                                                           \u2502\n\u2502         - Create a resource group in location eastus                                      \u2502\n\u2502         - Create an app registration in Azure AD prefect-aci-push-pool-app                \u2502\n\u2502         - Create/use a service principal for app registration                             \u2502\n\u2502         - Generate a secret for app registration                                          \u2502\n\u2502         - Create an Azure Container Registry with prefix prefect                          \u2502\n\u2502         - Create an identity prefect-acr-identity to allow access to the created registry \u2502\n\u2502         - Assign Contributor role to service account                                      \u2502\n\u2502         - Create an ACR registry for image hosting                                        \u2502\n\u2502         - Create an identity for Azure Container Instance to allow access to the registry \u2502\n\u2502                                                                                           \u2502\n\u2502     Updates in Prefect workspace                                                          \u2502\n\u2502                                                                                           \u2502\n\u2502         - Create Azure Container Instance credentials block aci-push-pool-credentials     \u2502\n\u2502                                                                                           \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]:     \nCreating resource group\nCreating app registration\nGenerating secret for app registration\nCreating ACI credentials block\nACI credentials block 'aci-push-pool-credentials' created in Prefect Cloud\nAssigning Contributor role to service account\nCreating Azure Container Registry\nCreating identity\nProvisioning infrastructure... \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned for 'my-aci-work-pool' work pool!\nCreated work pool 'my-aci-work-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new Azure Container Registry and the default Docker build namespace will be set to the URL of the registry.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the registry.</p> <p>To take advantage of this functionality, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)                                                         \ndef my_flow(name: str = \"world\"):                                              \n    print(f\"Hello {name}! I'm a flow running on an Azure Container Instance!\") \n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"my-work-pool\",                                                \n        image=DeploymentImage(                                                 \n            name=\"my-image:latest\",                                            \n            platform=\"linux/amd64\",                                            \n        )                                                                      \n    )       \n</code></pre> <p>This will build an image with the tag <code>&lt;acr-registry-url&gt;/my-image:latest</code> and push it to the registry.</p> <pre><code>prefect work-pool create --type cloud-run:push --provision-infra my-cloud-run-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag will allow you to select a GCP project to use for your work pool and automatically configure it to be ready to execute flows via Cloud Run. In your GCP project, this command will activate the Cloud Run API, create a service account, and create a key for the service account, if they don't already exist. In your Prefect workspace, this command will create a <code>GCPCredentials</code> block for storing the service account key.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-cloud-run-pool will require:                           \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in GCP project central-kit-405415 in region us-central1                                      \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Activate the Cloud Run API for your project                                                    \u2502\n\u2502         - Activate the Artifact Registry API for your project                                            \u2502\n\u2502         - Create an Artifact Registry repository named prefect-images                                    \u2502\n\u2502         - Create a service account for managing Cloud Run jobs: prefect-cloud-run                        \u2502\n\u2502             - Service account will be granted the following roles:                                       \u2502\n\u2502                 - Service Account User                                                                   \u2502\n\u2502                 - Cloud Run Developer                                                                    \u2502\n\u2502         - Create a key for service account prefect-cloud-run                                             \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in Prefect workspace                                                                         \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Create GCP credentials block my--pool-push-pool-credentials to store the service account key   \u2502\n\u2502                                                                                                          \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nActivating Cloud Run API\nActivating Artifact Registry API\nCreating Artifact Registry repository\nConfiguring authentication to Artifact Registry\nSetting default Docker build namespace\nCreating service account\nAssigning roles to service account\nCreating service account key\nCreating GCP credentials block\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-cloud-run-pool'!\n</code></pre> <p>Default Docker build namespace</p> <p>After infrastructure provisioning completes, you will be logged into your new Artifact Registry repository and the default Docker build namespace will be set to the URL of the repository.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the repository.</p> <p>To take advantage of this functionality, you can write your deploy scripts like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow running on Cloud Run!\")\n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"above-ground\",\n        image=DeploymentImage(\n            name=\"my-image:latest\",\n            platform=\"linux/amd64\",\n        )\n    )\n</code></pre> <p>This will build an image with the tag <code>&lt;region&gt;-docker.pkg.dev/&lt;project&gt;/&lt;repository-name&gt;/my-image:latest</code> and push it to the repository.</p> <pre><code>prefect work-pool create --type modal:push --provision-infra my-modal-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag will trigger the creation of a <code>ModalCredentials</code> block in your Prefect Cloud workspace. This block will store your Modal API token, which is used to authenticate with Modal's API. By default, the token for your current Modal profile will be used for the new <code>ModalCredentials</code> block. If Prefect is unable to discover a Modal API token for your current profile, you will be prompted to create a new one.</p> <p>That's it! You're ready to create and schedule deployments that use your new push work pool. Reminder that no worker is needed to run flows with a push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#using-existing-resources-with-automatic-infrastructure-provisioning","title":"Using existing resources with automatic infrastructure provisioning","text":"<p>If you already have the necessary infrastructure set up, Prefect will detect that upon work pool creation and the infrastructure provisioning for that resource will be skipped.</p> <p>For example, here's how <code>prefect work-pool create my-work-pool --provision-infra</code> looks when existing Azure resources are detected:</p> <pre><code>Proceed with infrastructure provisioning? [y/n]: y\nCreating resource group\nResource group 'prefect-aci-push-pool-rg' already exists in location 'eastus'.\nCreating app registration\nApp registration 'prefect-aci-push-pool-app' already exists.\nGenerating secret for app registration\nProvisioning infrastructure\nACI credentials block 'bb-push-pool-credentials' created\nAssigning Contributor role to service account...\nService principal with object ID '4be6fed7-...' already has the 'Contributor' role assigned in \n'/subscriptions/.../'\nCreating Azure Container Instance\nContainer instance 'prefect-aci-push-pool-container' already exists.\nCreating Azure Container Instance credentials block\nProvisioning infrastructure... \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-work-pool'!\n</code></pre>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#provisioning-infrastructure-for-an-existing-push-work-pool","title":"Provisioning infrastructure for an existing push work pool","text":"<p>If you already have a push work pool set up, but haven't configured the necessary infrastructure, you can use the <code>provision-infra</code> sub-command to provision the infrastructure for that work pool. For example, you can run the following command if you have a work pool named \"my-work-pool\".</p> <pre><code>prefect work-pool provision-infra my-work-pool\n</code></pre> <p>Prefect will create the necessary infrastructure for the <code>my-work-pool</code> work pool and provide you with a summary of the changes to be made:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-work-pool will require:                                      \u2502\n\u2502                                                                                                                \u2502\n\u2502     Updates in subscription Azure subscription 1                                                               \u2502\n\u2502                                                                                                                \u2502\n\u2502         - Create a resource group in location eastus                                                           \u2502\n\u2502         - Create an app registration in Azure AD prefect-aci-push-pool-app                                     \u2502\n\u2502         - Create/use a service principal for app registration                                                  \u2502\n\u2502         - Generate a secret for app registration                                                               \u2502\n\u2502         - Assign Contributor role to service account                                                           \u2502\n\u2502         - Create Azure Container Instance 'aci-push-pool-container' in resource group prefect-aci-push-pool-rg \u2502\n\u2502                                                                                                                \u2502\n\u2502     Updates in Prefect workspace                                                                               \u2502\n\u2502                                                                                                                \u2502\n\u2502         - Create Azure Container Instance credentials block aci-push-pool-credentials                          \u2502\n\u2502                                                                                                                \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\n</code></pre> <p>This command can speed up your infrastructure setup process.</p> <p>As with the examples above, you will need to have the related cloud CLI library installed and be authenticated with your cloud provider.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#manual-infrastructure-provisioning","title":"Manual infrastructure provisioning","text":"<p>If you prefer to set up your infrastructure manually, don't include the <code>--provision-infra</code> flag in the CLI command. In the examples below, we'll create a push work pool via the Prefect Cloud UI.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>To push work to ECS, AWS credentials are required.</p> <p>Create a user and attach the AmazonECS_FullAccess permissions.</p> <p>From that user's page create credentials and store them somewhere safe for use in the next section.</p> <p>To push work to Azure, an Azure subscription, resource group and tenant secret are required. </p> <p>Create Subscription and Resource Group</p> <ol> <li>In the Azure portal, create a subscription.</li> <li>Create a resource group within your subscription.</li> </ol> <p>Create App Registration</p> <ol> <li>In the Azure portal, create an app registration.</li> <li>In the app registration, create a client secret. Copy the value and store it somewhere safe.</li> </ol> <p>Add App Registration to Resource Group</p> <ol> <li>Navigate to the resource group you created earlier.</li> <li>Choose the \"Access control (IAM)\" blade in the left-hand side menu. Click \"+ Add\" button at the top, then \"Add role assignment\".</li> <li>Go to the \"Privileged administrator roles\" tab, click on \"Contributor\", then click \"Next\" at the bottom of the page.</li> <li>Click on \"+ Select members\". Type the name of the app registration (otherwise it may not autopopulate) and click to add it. Then hit \"Select\" and click \"Next\". The default permissions associated with a role like \"Contributor\" might not always be sufficient for all operations related to Azure Container Instances (ACI). The specific permissions required can depend on the operations you need to perform (like creating, running, and deleting ACI container groups) and your organization's security policies. In some cases, additional permissions or custom roles might be necessary.</li> <li>Click \"Review + assign\" to finish.</li> </ol> <p>A GCP service account and an API Key are required, to push work to Cloud Run.</p> <p>Create a service account by navigating to the service accounts page and clicking Create. Name and describe your service account, and click continue to configure permissions.</p> <p>The service account must have two roles at a minimum, Cloud Run Developer, and Service Account User.</p> <p></p> <p>Once the Service account is created, navigate to its Keys page to add an API key. Create a JSON type key, download it, and store it somewhere safe for use in the next section.</p> <p>A Modal API token is required to push work to Modal.</p> <p>Create a Modal API token by navigating to Settings in the Modal UI. In the API Tokens section of the Settings page, click New Token.</p> <p>Copy the token ID and token secret and store them somewhere safe for use in the next section.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#work-pool-configuration","title":"Work pool configuration","text":"<p>Our push work pool will store information about what type of infrastructure our flow will run on, what default values to provide to compute jobs, and other important execution environment parameters. Because our push work pool needs to integrate securely with your serverless infrastructure, we need to start by storing our credentials in Prefect Cloud, which we'll do by making a block.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#creating-a-credentials-block","title":"Creating a Credentials block","text":"AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Navigate to the blocks page, click create new block, and select AWS Credentials for the type.</p> <p>For use in a push work pool, region, access key, and access key secret must be set.</p> <p>Provide any other optional information and create your block.</p> <p>Navigate to the blocks page and click the \"+\" at the top to create a new block. Find the Azure Container Instance Credentials block and click \"Add +\".</p> <p>Locate the client ID and tenant ID on your app registration and use the client secret you saved earlier. Be sure to use the value of the secret, not the secret ID!</p> <p>Provide any other optional information and click \"Create\".</p> <p>Navigate to the blocks page, click create new block, and select GCP Credentials for the type.</p> <p>For use in a push work pool, this block must have the contents of the JSON key stored in the Service Account Info field, as such:</p> <p></p> <p>Provide any other optional information and create your block.</p> <p>Navigate to the blocks page, click create new block, and select Modal Credentials for the type.</p> <p>For use in a push work pool, this block must have the token ID and token secret stored in the Token ID and Token Secret fields, respectively.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#creating-a-push-work-pool","title":"Creating a push work pool","text":"<p>Now navigate to the work pools page. Click Create to start configuring your push work pool by selecting a push option in the infrastructure type step.</p> AWS ECSAzure Container InstancesGoogle Cloud RunModal <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the AWS Credentials field.  This will allow Prefect Cloud to securely interact with your ECS cluster.</p> <p>Fill in the subscription ID and resource group name from the resource group you created. Add the Azure Container Instance Credentials block you created in the step above. </p> <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the GCP Credentials field.  This will allow Prefect Cloud to securely interact with your GCP project.</p> <p>Each step has several optional fields that are detailed in the work pools documentation.  Select the block you created under the Modal Credentials field.  This will allow Prefect Cloud to securely interact with your Modal account.</p> <p>Create your pool and you are ready to deploy flows to your Push work pool.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#deployment","title":"Deployment","text":"<p>Deployment details are described in the deployments concept section. Your deployment needs to be configured to send flow runs to our push work pool. For example, if you create a deployment through the interactive command line experience, choose the work pool you just created. If you are deploying an existing <code>prefect.yaml</code> file, the deployment would contain:</p> <pre><code>  work_pool:\n    name: my-push-pool\n</code></pre> <p>Deploying your flow to the <code>my-push-pool</code> work pool will ensure that runs that are ready for execution will be submitted immediately, without the need for a worker to poll for them.</p> <p>Serverless infrastructure may require a certain image architecture</p> <p>Note that serverless infrastructure may assume a certain Docker image architecture; for example, Google Cloud Run will fail to run images built with <code>linux/arm64</code> architecture. If using Prefect to build your image, you can change the image architecture through the <code>platform</code> keyword (e.g., <code>platform=\"linux/amd64\"</code>).</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#putting-it-all-together","title":"Putting it all together","text":"<p>With your deployment created, navigate to its detail page and create a new flow run. You'll see the flow start running without ever having to poll the work pool, because Prefect Cloud securely connected to your serverless infrastructure, created a job, ran the job, and began reporting on its execution.</p> <p></p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/push-work-pools/#next-steps","title":"Next steps","text":"<p>Learn more about workers and work pools in the Prefect concept documentation.</p> <p>Learn about installing dependencies at runtime or baking them into your Docker image in the Deploying Flows to Work Pools and Workers guide.</p>","tags":["work pools","deployments","Cloud Run","AWS ECS","Azure Container Instances","ACI","elastic container service","GCP","Google Cloud Run","serverless","Amazon Web Services","Modal","push work pools"],"boost":2},{"location":"guides/deployment/serverless-workers/","title":"Run Deployments on Serverless Infrastructure with Prefect Workers","text":"<p>Prefect provides hybrid work pools for workers to run flows on the serverless platforms of major cloud providers. The following options are available:</p> <ul> <li>AWS Elastic Container Service (ECS)</li> <li>Azure Container Instances (ACI)</li> <li>Google Cloud Run</li> <li>Google Cloud Run V2</li> <li>Google Vertex AI</li> </ul> <p></p> <ul> <li>Create a work pool that sends work to your chosen serverless infrastructure</li> <li>Deploy a flow to that work pool</li> <li>Start a worker in your serverless cloud provider that will poll its matched work pool for scheduled runs</li> <li>Schedule a deployment run that a worker will pick up from the work pool and run on your serverless infrastructure</li> </ul> <p>Push work pools don't require a worker</p> <p>Options for push work pool versions of AWS ECS, Azure Container Instances, and Google Cloud Run that do not require a worker are available with Prefect Cloud. These push work pool options require connection configuration information to be stored on Prefect Cloud. Read more in the Serverless Push Work Pool Guide.</p> <p>This is a brief overview of the options to run workflows on serverless infrastructure. For in-depth guides, see the Prefect integration libraries:</p> <ul> <li>AWS ECS guide in the <code>prefect-aws</code> docs</li> <li>Azure Container Instances guide</li> <li>Google Cloud Run guide in the <code>prefect-gcp</code> docs.</li> <li>For Google Vertex AI, follow the Cloud Run guide, substituting Google Vertex AI where Google Cloud Run is mentioned.</li> </ul> <p>Choosing between Google Cloud Run and Google Vertex AI</p> <p>Google Vertex AI is well-suited for machine learning model training applications in which GPUs or TPUs and high resource levels are desired.</p>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/serverless-workers/#steps","title":"Steps","text":"<ol> <li>Make sure you have an user or service account on your chosen cloud provider with the necessary permissions to run serverless jobs</li> <li>Create the appropriate serverless work pool that uses a worker in the Prefect UI</li> <li>Create a deployment that references the work pool</li> <li>Start a worker in your chose serverless cloud provider infrastructure</li> <li>Run the deployment</li> </ol>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/serverless-workers/#next-steps","title":"Next steps","text":"<p>Options for push versions on AWS ECS, Azure Container Instances, and Google Cloud Run work pools that do not require a worker are available with Prefect Cloud. Read more in the Serverless Push Work Pool Guide.</p> <p>Learn more about workers and work pools in the Prefect concept documentation.</p> <p>Learn about installing dependencies at runtime or baking them into your Docker image in the Deploying Flows to Work Pools and Workers guide.</p>","tags":["work pools","deployments","Cloud Run","GCP","Vertex AI","AWS ECS","Azure Container Instances","ACI"],"boost":2},{"location":"guides/deployment/storage-guide/","title":"Where to Store Your Flow Code","text":"<p>When a deployment is run, the execution environment needs access to the flow code. Flow code is not stored in a Prefect server instance or in Prefect Cloud.</p> <p>You have several flow code storage options.</p> <p>This guide focusses on deployments created with the interactive CLI experience or a prefect.yaml file. If you'd like to create your deployments using Python code, see the discussion of flow code storage in the <code>.deploy</code> section of Deploying Flows to Work pools and Workers guide.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-1-git-based-storage","title":"Option 1: Git-based storage","text":"<p>Git-based version control platforms are popular locations for code storage.  They provide redundancy, version control, and easier collaboration.</p> <p>GitHub is the most popular cloud-based repository hosting provider.  GitLab and Bitbucket are other popular options.  Prefect supports each of these platforms.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#creating-a-deployment-with-git-based-storage","title":"Creating a deployment with git-based storage","text":"<p>Run <code>prefect deploy</code> from the root directory of the git repository and create a new deployment. You will see a series of prompts. Select that you want to create a new deployment, select the flow code entrypoint, and name your deployment.</p> <p>Prefect detects that you are in a git repository and asks if you want to store your flow code in a git repository. Select \"y\" and you will be prompted to confirm the URL of your git repository and the branch name, as in the example below:</p> <pre><code>? Your Prefect workers will need access to this flow's code in order to run it. \nWould you like your workers to pull your flow code from its remote repository when running this flow? [y/n] (y): \n? Is https://github.com/my_username/my_repo.git the correct URL to pull your flow code from? [y/n] (y): \n? Is main the correct branch to pull your flow code from? [y/n] (y): \n? Is this a private repository? [y/n]: y\n</code></pre> <p>In this example, the git repository is hosted on GitHub. If you are using Bitbucket or GitLab, the URL will match your provider. If the repository is public, enter \"n\" and you are on your way.</p> <p>If the repository is private, you can enter a token to access your private repository. This token will be saved in an encrypted Prefect Secret block.</p> <pre><code>? Please enter a token that can be used to access your private repository. This token will be saved as a Secret block via the Prefect API: \"123_abc_this_is_my_token\"\n</code></pre> <p>Verify that you have a new Secret block in your active workspace named in the format \"deployment-my-deployment-my-flow-name-repo-token\".</p> <p>Creating access tokens differs for each provider.</p> GitHubBitbucketGitLab <p>We recommend using HTTPS with fine-grained Personal Access Tokens so that you can limit access by repository.  See the GitHub docs for Personal Access Tokens (PATs).</p> <p>Under Your Profile-&gt;Developer Settings-&gt;Personal access tokens-&gt;Fine-grained token choose Generate New Token and fill in the required fields.  Under Repository access choose Only select repositories and grant the token permissions for Contents.</p> <p>We recommend using HTTPS with Repository, Project, or Workspace Access Tokens. </p> <p>You can create a Repository Access Token with Scopes-&gt;Repositories-&gt;Read.</p> <p>Bitbucket requires you prepend the token string with <code>x-token-auth:</code> So the full string looks like <code>x-token-auth:abc_123_this_is_my_token</code>. </p> <p>We recommend using HTTPS with Project Access Tokens.</p> <p>In your repository in the GitLab UI, select Settings-&gt;Repository-&gt;Project Access Tokens and check read_repository under Select scopes.</p> <p>If you want to configure a Secret block ahead of time, create the block via code or the Prefect UI and reference it in your <code>prefect.yaml</code> file.</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://gitlab.com/org/my-private-repo.git\n        access_token: \"{{ prefect.blocks.secret.my-block-name }}\"\n</code></pre> <p>Alternatively, you can create a Credentials block ahead of time and reference it in the <code>prefect.yaml</code> pull step.</p> GitHubBitbucketGitLab <ol> <li>Install the Prefect-Github library with <code>pip install -U prefect-github</code></li> <li>Register the blocks in that library to make them available on the server with <code>prefect block register -m prefect_github</code>.</li> <li>Create a GitHub Credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-block-name }}\"\n</code></pre> <ol> <li>Install the relevant library with <code>pip install -U prefect-bitbucket</code></li> <li>Register the blocks in that library with <code>prefect block register -m prefect_bitbucket</code> </li> <li>Create a Bitbucket credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://bitbucket.org/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.bitbucket-credentials.my-block-name }}\"\n</code></pre> <ol> <li>Install the relevant library with <code>pip install -U prefect-gitlab</code></li> <li>Register the blocks in that library with <code>prefect block register -m prefect_gitlab</code> </li> <li>Create a GitLab credentials block via code or the Prefect UI and reference it as shown:</li> </ol> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://gitlab.com/org/my-private-repo.git\n        credentials: \"{{ prefect.blocks.gitlab-credentials.my-block-name }}\"\n</code></pre> <p>Push your code</p> <p>When you make a change to your code, Prefect does not push your code to your git-based version control platform. You need to push your code manually or as part of your CI/CD pipeline. This design decision is an intentional one to avoid confusion about the git history and push process.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-2-docker-based-storage","title":"Option 2: Docker-based storage","text":"<p>Another popular way to store your flow code is to include it in a Docker image.  All work pool options except Process and Prefect Managed work pools allow you to bake your code into a Docker image.</p> <ol> <li>Run <code>prefect init</code> in the root of your repository and choose <code>docker</code> for the project name and answer the prompts to create a <code>prefect.yaml</code> file with a build step that will create a Docker image with the flow code built in. See the Workers and Work Pools page of the tutorial for more info.</li> <li>Run <code>prefect deploy</code> from the root of your repository to create a deployment.</li> <li>When a deployment runs the worker pulls the Docker image and spins up a container.</li> <li>The flow code baked into the image runs inside the container.</li> </ol> <p>CI/CD may not require push or pull steps</p> <p>You don't need push or pull steps in the <code>prefect.yaml</code> file if using CI/CD to build a Docker image outside of Prefect. Instead, the work pool can reference the image directly.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#option-3-cloud-provider-storage","title":"Option 3: Cloud-provider storage","text":"<p>You can store your code in an AWS S3 bucket, Azure Blob Storage container, or GCP GCS bucket and specify the destination directly in the <code>push</code> and <code>pull</code> steps of your <code>prefect.yaml</code> file.</p> <p>To create a templated <code>prefect.yaml</code> file run <code>prefect init</code> and select the recipe for the applicable cloud-provider storage. Below are the recipe options and the relevant portions of the <code>prefect.yaml</code> file.</p> AWS S3 bucketAzure Blob Storage containerGCP GCS bucket <p>Choose <code>s3Bucket</code> as the recipe and enter the bucket name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_aws.deployments.steps.push_to_s3:\n    id: push_code\n    requires: prefect-aws&gt;=0.3.4\n    bucket: my-bucket\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.aws-credentials.my-credentials-block }}\" # if private\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_aws.deployments.steps.pull_from_s3:\n    id: pull_code\n    requires: prefect-aws&gt;=0.3.4\n    bucket: '{{ push_code.bucket }}'\n    folder: '{{ push_code.folder }}'\n    credentials: \"{{ prefect.blocks.aws-credentials.my-credentials-block }}\" # if private \n</code></pre> <p>If the bucket requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-AWS library with <code>pip install -U prefect-aws</code></li> <li>Register the blocks in Prefect-AWS with <code>prefect block register -m prefect_aws</code> </li> <li>Create a user with a role with read and write permissions to access the bucket. If using the UI, create an access key pair with IAM-&gt;Users-&gt;Security credentials-&gt;Access keys-&gt;Create access key. Choose Use case-&gt;Other and then copy the Access key and Secret access key values.</li> <li>Create an AWS Credentials block via code or the Prefect UI. In addition to the block name, most users will fill in the AWS Access Key ID and AWS Access Key Secret fields.</li> <li>Reference the block as shown in the push and pull steps </li> </ol> <p>Choose <code>azure</code> as the recipe and enter the container name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_azure.deployments.steps.push_to_azure_blob_storage:\n    id: push_code\n    requires: prefect-azure&gt;=0.2.8\n    container: my-prefect-azure-container\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}\" # if private\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n    id: pull_code\n    requires: prefect-azure&gt;=0.2.8\n    container: '{{ push_code.container }}'\n    folder: '{{ push_code.folder }}'\n    credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.my-credentials-block }}\" # if private\n</code></pre> <p>If the blob requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-Azure library with <code>pip install -U prefect-azure</code></li> <li>Register the blocks in Prefect-Azure with <code>prefect block register -m prefect_azure</code> </li> <li>Create an access key for a role with sufficient (read and write) permissions to access the blob. A connection string that will contain all needed information can be created in the UI under Storage Account-&gt;Access keys.</li> <li>Create an Azure Blob Storage Credentials block via code or the Prefect UI. Enter a name for the block and paste the connection string into the Connection String field.</li> <li>Reference the block as shown in the push and pull steps above. </li> </ol> <p>Choose `gcs`` as the recipe and enter the bucket name when prompted.</p> <pre><code># push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_gcp.deployment.steps.push_to_gcs:\n    id: push_code\n    requires: prefect-gcp&gt;=0.4.3\n    bucket: my-bucket\n    folder: my-folder\n    credentials: \"{{ prefect.blocks.gcp-credentials.my-credentials-block }}\" # if private \n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect_gcp.deployment.steps.pull_from_gcs:\n    id: pull_code\n    requires: prefect-gcp&gt;=0.4.3\n    bucket: '{{ push_code.bucket }}'\n    folder: '{{ pull_code.folder }}'\n    credentials: \"{{ prefect.blocks.gcp-credentials.my-credentials-block }}\" # if private \n</code></pre> <p>If the bucket requires authentication to access it, you can do the following:</p> <ol> <li>Install the Prefect-GCP library with <code>pip install -U prefect-gcp</code></li> <li>Register the blocks in Prefect-GCP with <code>prefect block register -m prefect_gcp</code> </li> <li>Create a service account in GCP for a role with read and write permissions to access the bucket contents. If using the GCP  console, go to IAM &amp; Admin-&gt;Service accounts-&gt;Create service account. After choosing a role with the required permissions, see your service account and click on the three dot menu in the Actions column. Select Manage Keys-&gt;ADD KEY-&gt;Create new key-&gt;JSON. Download the JSON file.</li> <li>Create a GCP Credentials block via code or the Prefect UI. Enter a name for the block and paste the entire contents of the JSON key file into the Service Account Info field.</li> <li>Reference the block as shown in the push and pull steps above. </li> </ol> <p>Another option for authentication is for the worker to have access to the storage location at runtime via SSH keys.</p> <p>Alternatively, you can inject environment variables into your deployment like this example that uses an environment variable named <code>CUSTOM_FOLDER</code>:</p> <pre><code> push:\n    - prefect_gcp.deployment.steps.push_to_gcs:\n        id: push_code\n        requires: prefect-gcp&gt;=0.4.3\n        bucket: my-bucket\n        folder: '{{ $CUSTOM_FOLDER }}'\n</code></pre>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#include-or-exclude-files-from-storage","title":"Include or exclude files from storage","text":"<p>By default, Prefect uploads all files in the current folder to the configured storage location when you create a deployment.</p> <p>When using a git repository, Docker image, or cloud-provider storage location, you may want to exclude certain files or directories.</p> <ul> <li>If you are familiar with git you are likely familiar with the <code>.gitignore</code> file.</li> <li>If you are familiar with Docker you are likely familiar with the <code>.dockerignore</code> file.</li> <li>For cloud-provider storage the <code>.prefectignore</code> file serves the same purpose and follows a similar syntax as those files. So an entry of <code>*.pyc</code> will exclude all <code>.pyc</code> files from upload.</li> </ul>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#other-code-storage-creation-methods","title":"Other code storage creation methods","text":"<p>In earlier versions of Prefect storage blocks were the recommended way to store flow code. Storage blocks are deprecated.</p> <p>As shown above, repositories can be referenced directly through interactive prompts with <code>prefect deploy</code> or in a <code>prefect.yaml</code>. When authentication is needed, Secret or Credential blocks can be referenced, and in some cases, created automatically through interactive deployment creation prompts.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"guides/deployment/storage-guide/#conclusion","title":"Conclusion","text":"<p>You've seen options for storing your flow code. For easier version control, we recommend using Docker-based storage or git-based storage for your production deployments.</p>","tags":["guides","guide","flow code","storage","code storage","repository","github","git","gitlab","bitbucket","s3","azure","blob storage","bucket","AWS","GCP","GCS","Google Cloud Storage","Azure Blob Storage","Docker","storage"],"boost":2},{"location":"integrations/","title":"Integrations","text":"<p>You can install the following integrations of pre-built tasks, flows, blocks and more as PyPI packages:</p> <p>                         Alert                     </p> <p>                     Maintained by Khuyen Tran </p> <p>                         AWS                     </p> <p>                     Maintained by Prefect </p> <p>                         Azure                     </p> <p>                     Maintained by Prefect </p> <p>                         Bitbucket                     </p> <p>                     Maintained by Prefect </p> <p>                         Coiled                     </p> <p>                     Maintained by Coiled </p> <p>                         CubeJS                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Dask                     </p> <p>                     Maintained by Prefect </p> <p>                         Databricks                     </p> <p>                     Maintained by Prefect </p> <p>                         dbt                     </p> <p>                     Maintained by Prefect </p> <p>                         Docker                     </p> <p>                     Maintained by Prefect </p> <p>                         Earthdata                     </p> <p>                     Maintained by Giorgio Basile </p> <p>                         Email                     </p> <p>                     Maintained by Prefect </p> <p>                         Fivetran                     </p> <p>                     Maintained by Fivetran </p> <p>                         Fugue                     </p> <p>                     Maintained by The Fugue Development Team </p> <p>                         GCP                     </p> <p>                     Maintained by Prefect </p> <p>                         GitHub                     </p> <p>                     Maintained by Prefect </p> <p>                         GitLab                     </p> <p>                     Maintained by Prefect </p> <p>                         Google Sheets                     </p> <p>                     Maintained by Stefano Cascavilla </p> <p>                         HashiCorp Vault                     </p> <p>                     Maintained by Pavel Chekin </p> <p>                         Kubernetes                     </p> <p>                     Maintained by Prefect </p> <p>                         KV                     </p> <p>                     Maintained by Zanie Blue </p> <p>                         MetricFlow                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Planetary Computer                     </p> <p>                     Maintained by Giorgio Basile </p> <p>                         Ray                     </p> <p>                     Maintained by Prefect </p> <p>                         Shell                     </p> <p>                     Maintained by Prefect </p> <p>                         Sifflet                     </p> <p>                     Maintained by Sifflet and Alessandro Lollo </p> <p>                         Slack                     </p> <p>                     Maintained by Prefect </p> <p>                         Snowflake                     </p> <p>                     Maintained by Prefect </p> <p>                         Soda Cloud                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Soda Core                     </p> <p>                     Maintained by Soda and Alessandro Lollo </p> <p>                         Spark on Kubernetes                     </p> <p>                     Maintained by Manoj Babu Katragadda </p> <p>                         SQLAlchemy                     </p> <p>                     Maintained by Prefect </p> <p>                         Stitch                     </p> <p>                     Maintained by Alessandro Lollo </p> <p>                         Transform                     </p> <p>                     Maintained by Alessandro Lollo </p>","tags":["tasks","flows","blocks","collections","task library","integrations","Alert","AWS","Azure","Bitbucket","Coiled","CubeJS","Dask","Databricks","dbt","Docker","Earthdata","Email","Fivetran","Fugue","GCP","GitHub","GitLab","Google Sheets","HashiCorp Vault","Kubernetes","KV","MetricFlow","Planetary Computer","Ray","Shell","Sifflet","Slack","Snowflake","Soda Cloud","Soda Core","Spark on Kubernetes","SQLAlchemy","Stitch","Transform"],"boost":2},{"location":"integrations/contribute/","title":"Contribute","text":"<p>We welcome contributors! You can help contribute blocks and integrations by following these steps.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contributing-blocks","title":"Contributing Blocks","text":"<p>Building your own custom block is simple!</p> <ol> <li>Subclass from <code>Block</code>.</li> <li>Add a description alongside an <code>Attributes</code> and <code>Example</code> section in the docstring.</li> <li>Set a <code>_logo_url</code> to point to a relevant image.</li> <li>Create the <code>pydantic.Field</code>s of the block with a type annotation, <code>default</code> or <code>default_factory</code>, and a short description about the field.</li> <li>Define the methods of the block.</li> </ol> <p>For example, this is how the Secret block is implemented: <pre><code>from pydantic import Field, SecretStr\nfrom prefect.blocks.core import Block\n\nclass Secret(Block):\n    \"\"\"\n    A block that represents a secret value. The value stored in this block will be obfuscated when\n    this block is logged or shown in the UI.\n\n    Attributes:\n        value: A string value that should be kept secret.\n\n    Example:\n        ```python\n        from prefect.blocks.system import Secret\n        secret_block = Secret.load(\"BLOCK_NAME\")\n\n        # Access the stored secret\n        secret_block.get()\n        ```\n    \"\"\"\n\n    _logo_url = \"https://example.com/logo.png\"\n\n    value: SecretStr = Field(\n        default=..., description=\"A string value that should be kept secret.\"\n    )  # ... indicates it's a required field\n\n    def get(self):\n        return self.value.get_secret_value()\n</code></pre></p> <p>To view in Prefect Cloud or the Prefect server UI, register the block.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contributing-integrations","title":"Contributing Integrations","text":"<p>Anyone can create and share a Prefect Integration and we encourage anyone interested in creating an integration to do so!</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#generate-a-project","title":"Generate a project","text":"<p>To help you get started with your integration, we've created a template that gives the tools you need to create and publish your integration.</p> <p>Use the Prefect Integration template to get started creating an integration with a bootstrapped project!</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#list-a-project-in-the-integrations-catalog","title":"List a project in the Integrations Catalog","text":"<p>To list your integration in the Prefect Integrations Catalog, submit a PR to the Prefect repository adding a file to the <code>docs/integrations/catalog</code> directory with details about your integration. Please use <code>TEMPLATE.yaml</code> in that folder as a guide.</p>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/contribute/#contribute-fixes-or-enhancements-to-integrations","title":"Contribute fixes or enhancements to Integrations","text":"<p>If you'd like to help contribute to fix an issue or add a feature to any of our Integrations, please propose changes through a pull request from a fork of the repository.</p> <ol> <li>Fork the repository</li> <li>Clone the forked repository</li> <li>Install the repository and its dependencies: <pre><code>pip install -e \".[dev]\"\n</code></pre></li> <li>Make desired changes</li> <li>Add tests</li> <li>Insert an entry to the Integration's CHANGELOG.md</li> <li>Install <code>pre-commit</code> to perform quality checks prior to commit: <pre><code>pre-commit install\n</code></pre></li> <li><code>git commit</code>, <code>git push</code>, and create a pull request</li> </ol>","tags":["blocks","storage","secrets","configuration","infrastructure","integrations","integrations","contributing"],"boost":2},{"location":"integrations/usage/","title":"Using Integrations","text":"","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#installing-an-integration","title":"Installing an Integration","text":"<p>Install the Integration via <code>pip</code>.</p> <p>For example, to use <code>prefect-aws</code>:</p> <pre><code>pip install prefect-aws\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#registering-blocks-from-an-integration","title":"Registering Blocks from an Integration","text":"<p>Once the Prefect Integration is installed, register the blocks within the integration to view them in the Prefect Cloud UI:</p> <p>For example, to register the blocks available in <code>prefect-aws</code>:</p> <pre><code>prefect block register -m prefect_aws\n</code></pre> <p>Updating blocks from an integrations</p> <p>If you install an updated Prefect integration that adds fields to a block type, you will need to re-register that block type.</p> <p>Loading a block in code</p> <p>To use the <code>load</code> method on a Block, you must already have a block document saved either through code or through the Prefect UI.</p> <p>Learn more about Blocks here!</p>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#using-tasks-and-flows-from-an-integration","title":"Using Tasks and Flows from an Integration","text":"<p>Integrations also contain pre-built tasks and flows that can be imported and called within your code.</p> <p>As an example, to read a secret from AWS Secrets Manager with the <code>read_secret</code> task:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import read_secret\n\n@flow\ndef connect_to_database():\n    aws_credentials = AwsCredentials.load(\"MY_BLOCK_NAME\")\n    secret_value = read_secret(\n        secret_name=\"db_password\",\n        aws_credentials=aws_credentials\n    )\n\n    # Use secret_value to connect to a database\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#customizing-tasks-and-flows-from-an-integration","title":"Customizing Tasks and Flows from an Integration","text":"<p>To customize the settings of a task or flow pre-configured in a collection, use <code>with_options</code>:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\ncustom_run_dbt_cloud_job = trigger_dbt_cloud_job_run_and_wait_for_completion.with_options(\n    name=\"Run My DBT Cloud Job\",\n    retries=2,\n    retry_delay_seconds=10\n)\n\n@flow\ndef run_dbt_job_flow():\n    run_result = custom_run_dbt_cloud_job(\n        dbt_cloud_credentials=DbtCloudCredentials.load(\"my-dbt-cloud-credentials\"),\n        job_id=1\n    )\n\nrun_dbt_job_flow()\n</code></pre>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/usage/#recipes-and-tutorials","title":"Recipes and Tutorials","text":"<p>To learn more about how to use Integrations, check out Prefect recipes on GitHub. These recipes provide examples of how Integrations can be used in various scenarios.</p>","tags":["tasks","flows","blocks","integrations","task library","contributing"],"boost":2},{"location":"integrations/prefect-aws/","title":"prefect-aws","text":"<p>The prefect-aws library makes it easy to leverage the capabilities of AWS in your workflows. For example, you can retrieve secrets using AWS Secrets Manager, read and write objects with AWS S3, and deploy your flows on AWS ECS.</p>"},{"location":"integrations/prefect-aws/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-aws/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>An AWS account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-aws/#install-prefect-aws","title":"Install prefect-aws","text":"<pre><code>pip install -U prefect-aws\n</code></pre>"},{"location":"integrations/prefect-aws/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-aws module to make them available for use.</p> <pre><code>prefect block register -m prefect_aws\n</code></pre>"},{"location":"integrations/prefect-aws/#examples","title":"Examples","text":""},{"location":"integrations/prefect-aws/#run-flows-on-aws-ecs","title":"Run flows on AWS ECS","text":"<p>Run flows on AWS Elastic Container Service (ECS) to dynamically scale your infrastructure.</p> <p>See the ECS guide for a walkthrough of using ECS in a hybrid work pool.</p> <p>If you're using Prefect Cloud, ECS push work pools provide all the benefits of ECS with a quick setup and no worker needed.</p> <p>In the examples below, you create blocks with Python code. Alternatively, each block can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-aws/#save-credentials-to-an-aws-credentials-block","title":"Save credentials to an AWS Credentials block","text":"<p>Use of most AWS services requires an authenticated session. Prefect makes it simple to provide credentials via a AWS Credentials block.</p> <p>Steps:</p> <ol> <li>Refer to the AWS Configuration documentation to retrieve your access key ID and secret access key.</li> <li>Copy the access key ID and secret access key.</li> <li>Create an <code>AWSCredenitals</code> block in the Prefect UI or use a Python script like the one below.</li> </ol> <pre><code>from prefect_aws import AwsCredentials\n\n\nAwsCredentials(\n    aws_access_key_id=\"PLACEHOLDER\",\n    aws_secret_access_key=\"PLACEHOLDER\",\n    aws_session_token=None,  # replace this with token if necessary\n    region_name=\"us-east-2\"\n).save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Prefect is using the Boto3 library under the hood. To find credentials for authentication, any data not provided to the block are sourced at runtime in the order shown in the Boto3 docs. Prefect creates the session object using the values in the block and then, any missing values follow the sequence in the Boto3 docs.</p> <p>See an example of using the <code>AwsCredentials</code> block with AWS Secrets Manager with third-party services without storing credentials in the block itself in this guide.</p> <p>Here's how to load the saved credentials:</p> <pre><code>from prefect_aws import AwsCredentials\n\n\nAwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>The AWS Credentials block is often nested within other blocks, such as <code>S3Bucket</code> or <code>AwsSecret</code>, and provides authentication for those services.</p>"},{"location":"integrations/prefect-aws/#read-and-write-files-to-aws-s3","title":"Read and write files to AWS S3","text":"<p>Upload a file to an AWS S3 bucket and download the same file under a different file name. The following code assumes that the bucket already exists:</p> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials, S3Bucket\n\n\n@flow\ndef s3_flow():\n    # create a dummy file to upload\n    file_path = Path(\"test-example.txt\")\n    file_path.write_text(\"Hello, Prefect!\")\n\n    aws_credentials = AwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    s3_bucket = S3Bucket(\n        bucket_name=\"BUCKET-NAME-PLACEHOLDER\",\n        credentials=aws_credentials\n    )\n\n    s3_bucket_path = s3_bucket.upload_from_path(file_path)\n    downloaded_file_path = s3_bucket.download_object_to_path(\n        s3_bucket_path, \"downloaded-test-example.txt\"\n    )\n    return downloaded_file_path.read_text()\n\n\nif __name__ == \"__main__\":\n    s3_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/#access-secrets-with-aws-secrets-manager","title":"Access secrets with AWS Secrets Manager","text":"<p>Write a secret to AWS Secrets Manager, read the secret data, delete the secret, and return the secret data.</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials, AwsSecret\n\n\n@flow\ndef secrets_manager_flow():\n    aws_credentials = AwsCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    aws_secret = AwsSecret(secret_name=\"test-example\", aws_credentials=aws_credentials)\n    aws_secret.write_secret(secret_data=b\"Hello, Prefect!\")\n    secret_data = aws_secret.read_secret()\n    aws_secret.delete_secret()\n    return secret_data\n\n\nif __name__ == \"__main__\":\n    secrets_manager_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/#resources","title":"Resources","text":"<p>For assistance using AWS, consult the AWS documentation and, in particular, the Boto3 documentation.</p> <p>Refer to the prefect-aws API documentation linked in the sidebar to explore all the capabilities of the prefect-aws library.</p>"},{"location":"integrations/prefect-aws/batch/","title":"Batch","text":""},{"location":"integrations/prefect-aws/batch/#prefect_aws.batch","title":"<code>prefect_aws.batch</code>","text":"<p>Tasks for interacting with AWS Batch</p>"},{"location":"integrations/prefect-aws/batch/#prefect_aws.batch.batch_submit","title":"<code>batch_submit</code>  <code>async</code>","text":"<p>Submit a job to the AWS Batch job service.</p> <p>Parameters:</p> Name Type Description Default <code>job_name</code> <code>str</code> <p>The AWS batch job name.</p> required <code>job_queue</code> <code>str</code> <p>Name of the AWS batch job queue.</p> required <code>job_definition</code> <code>str</code> <p>The AWS batch job definition.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>**batch_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to the boto3 <code>submit_job</code> function. See the documentation for submit_job for more details.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The id corresponding to the job.</p> Example <p>Submits a job to batch.</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.batch import batch_submit\n\n\n@flow\ndef example_batch_submit_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    job_id = batch_submit(\n        \"job_name\",\n        \"job_queue\",\n        \"job_definition\",\n        aws_credentials\n    )\n    return job_id\n\nexample_batch_submit_flow()\n</code></pre> Source code in <code>prefect_aws/batch.py</code> <pre><code>@task\nasync def batch_submit(\n    job_name: str,\n    job_queue: str,\n    job_definition: str,\n    aws_credentials: AwsCredentials,\n    **batch_kwargs: Optional[Dict[str, Any]],\n) -&gt; str:\n    \"\"\"\n    Submit a job to the AWS Batch job service.\n\n    Args:\n        job_name: The AWS batch job name.\n        job_queue: Name of the AWS batch job queue.\n        job_definition: The AWS batch job definition.\n        aws_credentials: Credentials to use for authentication with AWS.\n        **batch_kwargs: Additional keyword arguments to pass to the boto3\n            `submit_job` function. See the documentation for\n            [submit_job](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/batch.html#Batch.Client.submit_job)\n            for more details.\n\n    Returns:\n        The id corresponding to the job.\n\n    Example:\n        Submits a job to batch.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.batch import batch_submit\n\n\n        @flow\n        def example_batch_submit_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            job_id = batch_submit(\n                \"job_name\",\n                \"job_queue\",\n                \"job_definition\",\n                aws_credentials\n            )\n            return job_id\n\n        example_batch_submit_flow()\n        ```\n\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Preparing to submit %s job to %s job queue\", job_name, job_queue)\n\n    batch_client = aws_credentials.get_boto3_session().client(\"batch\")\n\n    response = await run_sync_in_worker_thread(\n        batch_client.submit_job,\n        jobName=job_name,\n        jobQueue=job_queue,\n        jobDefinition=job_definition,\n        **batch_kwargs,\n    )\n    return response[\"jobId\"]\n</code></pre>"},{"location":"integrations/prefect-aws/client_waiter/","title":"Client Waiter","text":""},{"location":"integrations/prefect-aws/client_waiter/#prefect_aws.client_waiter","title":"<code>prefect_aws.client_waiter</code>","text":"<p>Task for waiting on a long-running AWS job</p>"},{"location":"integrations/prefect-aws/client_waiter/#prefect_aws.client_waiter.client_waiter","title":"<code>client_waiter</code>  <code>async</code>","text":"<p>Uses the underlying boto3 waiter functionality.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>str</code> <p>The AWS client on which to wait (e.g., 'client_wait', 'ec2', etc).</p> required <code>waiter_name</code> <code>str</code> <p>The name of the waiter to instantiate. You may also use a custom waiter name, if you supply an accompanying waiter definition dict.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>waiter_definition</code> <code>Optional[Dict[str, Any]]</code> <p>A valid custom waiter model, as a dict. Note that if you supply a custom definition, it is assumed that the provided 'waiter_name' is contained within the waiter definition dict.</p> <code>None</code> <code>**waiter_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Arguments to pass to the <code>waiter.wait(...)</code> method. Will depend upon the specific waiter being called.</p> <code>{}</code> Example <p>Run an ec2 waiter until instance_exists. <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.client_wait import client_waiter\n\n@flow\ndef example_client_wait_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n\n    waiter = client_waiter(\n        \"ec2\",\n        \"instance_exists\",\n        aws_credentials\n    )\n\n    return waiter\nexample_client_wait_flow()\n</code></pre></p> Source code in <code>prefect_aws/client_waiter.py</code> <pre><code>@task\nasync def client_waiter(\n    client: str,\n    waiter_name: str,\n    aws_credentials: AwsCredentials,\n    waiter_definition: Optional[Dict[str, Any]] = None,\n    **waiter_kwargs: Optional[Dict[str, Any]],\n):\n    \"\"\"\n    Uses the underlying boto3 waiter functionality.\n\n    Args:\n        client: The AWS client on which to wait (e.g., 'client_wait', 'ec2', etc).\n        waiter_name: The name of the waiter to instantiate.\n            You may also use a custom waiter name, if you supply\n            an accompanying waiter definition dict.\n        aws_credentials: Credentials to use for authentication with AWS.\n        waiter_definition: A valid custom waiter model, as a dict. Note that if\n            you supply a custom definition, it is assumed that the provided\n            'waiter_name' is contained within the waiter definition dict.\n        **waiter_kwargs: Arguments to pass to the `waiter.wait(...)` method. Will\n            depend upon the specific waiter being called.\n\n    Example:\n        Run an ec2 waiter until instance_exists.\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.client_wait import client_waiter\n\n        @flow\n        def example_client_wait_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n\n            waiter = client_waiter(\n                \"ec2\",\n                \"instance_exists\",\n                aws_credentials\n            )\n\n            return waiter\n        example_client_wait_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Waiting on %s job\", client)\n\n    boto_client = aws_credentials.get_boto3_session().client(client)\n\n    if waiter_definition is not None:\n        # Use user-provided waiter definition\n        waiter_model = WaiterModel(waiter_definition)\n        waiter = create_waiter_with_client(waiter_name, waiter_model, boto_client)\n    elif waiter_name in boto_client.waiter_names:\n        waiter = boto_client.get_waiter(waiter_name)\n    else:\n        raise ValueError(\n            f\"The waiter name, {waiter_name}, is not a valid boto waiter; \"\n            \"if using a custom waiter, you must provide a waiter definition\"\n        )\n\n    await run_sync_in_worker_thread(waiter.wait, **waiter_kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials","title":"<code>prefect_aws.credentials</code>","text":"<p>Module handling AWS credentials</p>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials","title":"<code>AwsCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with AWS. AWS authentication is handled via the <code>boto3</code> module. Refer to the boto3 docs for more info about the possible credential configurations.</p> Example <p>Load stored AWS credentials: <pre><code>from prefect_aws import AwsCredentials\n\naws_credentials_block = AwsCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class AwsCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with AWS. AWS authentication is\n    handled via the `boto3` module. Refer to the\n    [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)\n    for more info about the possible credential configurations.\n\n    Example:\n        Load stored AWS credentials:\n        ```python\n        from prefect_aws import AwsCredentials\n\n        aws_credentials_block = AwsCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"AWS Credentials\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials\"  # noqa\n\n    aws_access_key_id: Optional[str] = Field(\n        default=None,\n        description=\"A specific AWS access key ID.\",\n        title=\"AWS Access Key ID\",\n    )\n    aws_secret_access_key: Optional[SecretStr] = Field(\n        default=None,\n        description=\"A specific AWS secret access key.\",\n        title=\"AWS Access Key Secret\",\n    )\n    aws_session_token: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The session key for your AWS account. \"\n            \"This is only needed when you are using temporary credentials.\"\n        ),\n        title=\"AWS Session Token\",\n    )\n    profile_name: Optional[str] = Field(\n        default=None, description=\"The profile to use when creating your session.\"\n    )\n    region_name: Optional[str] = Field(\n        default=None,\n        description=\"The AWS Region where you want to create new connections.\",\n    )\n    aws_client_parameters: AwsClientParameters = Field(\n        default_factory=AwsClientParameters,\n        description=\"Extra parameters to initialize the Client.\",\n        title=\"AWS Client Parameters\",\n    )\n\n    class Config:\n        \"\"\"Config class for pydantic model.\"\"\"\n\n        arbitrary_types_allowed = True\n\n    def __hash__(self):\n        field_hashes = (\n            hash(self.aws_access_key_id),\n            hash(self.aws_secret_access_key),\n            hash(self.aws_session_token),\n            hash(self.profile_name),\n            hash(self.region_name),\n            hash(self.aws_client_parameters),\n        )\n        return hash(field_hashes)\n\n    def get_boto3_session(self) -&gt; boto3.Session:\n        \"\"\"\n        Returns an authenticated boto3 session that can be used to create clients\n        for AWS services\n\n        Example:\n            Create an S3 client from an authorized boto3 session:\n            ```python\n            aws_credentials = AwsCredentials(\n                aws_access_key_id = \"access_key_id\",\n                aws_secret_access_key = \"secret_access_key\"\n                )\n            s3_client = aws_credentials.get_boto3_session().client(\"s3\")\n            ```\n        \"\"\"\n\n        if self.aws_secret_access_key:\n            aws_secret_access_key = self.aws_secret_access_key.get_secret_value()\n        else:\n            aws_secret_access_key = None\n\n        return boto3.Session(\n            aws_access_key_id=self.aws_access_key_id,\n            aws_secret_access_key=aws_secret_access_key,\n            aws_session_token=self.aws_session_token,\n            profile_name=self.profile_name,\n            region_name=self.region_name,\n        )\n\n    def get_client(self, client_type: Union[str, ClientType]):\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The client's service name.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, ClientType):\n            client_type = client_type.value\n\n        return _get_client_cached(ctx=self, client_type=client_type)\n\n    def get_s3_client(self) -&gt; S3Client:\n        \"\"\"\n        Gets an authenticated S3 client.\n\n        Returns:\n            An authenticated S3 client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.S3)\n\n    def get_secrets_manager_client(self) -&gt; SecretsManagerClient:\n        \"\"\"\n        Gets an authenticated Secrets Manager client.\n\n        Returns:\n            An authenticated Secrets Manager client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.SECRETS_MANAGER)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.Config","title":"<code>Config</code>","text":"<p>Config class for pydantic model.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class Config:\n    \"\"\"Config class for pydantic model.\"\"\"\n\n    arbitrary_types_allowed = True\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_boto3_session","title":"<code>get_boto3_session</code>","text":"<p>Returns an authenticated boto3 session that can be used to create clients for AWS services</p> Example <p>Create an S3 client from an authorized boto3 session: <pre><code>aws_credentials = AwsCredentials(\n    aws_access_key_id = \"access_key_id\",\n    aws_secret_access_key = \"secret_access_key\"\n    )\ns3_client = aws_credentials.get_boto3_session().client(\"s3\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_boto3_session(self) -&gt; boto3.Session:\n    \"\"\"\n    Returns an authenticated boto3 session that can be used to create clients\n    for AWS services\n\n    Example:\n        Create an S3 client from an authorized boto3 session:\n        ```python\n        aws_credentials = AwsCredentials(\n            aws_access_key_id = \"access_key_id\",\n            aws_secret_access_key = \"secret_access_key\"\n            )\n        s3_client = aws_credentials.get_boto3_session().client(\"s3\")\n        ```\n    \"\"\"\n\n    if self.aws_secret_access_key:\n        aws_secret_access_key = self.aws_secret_access_key.get_secret_value()\n    else:\n        aws_secret_access_key = None\n\n    return boto3.Session(\n        aws_access_key_id=self.aws_access_key_id,\n        aws_secret_access_key=aws_secret_access_key,\n        aws_session_token=self.aws_session_token,\n        profile_name=self.profile_name,\n        region_name=self.region_name,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The client's service name.</p> required <p>Returns:</p> Type Description <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_client(self, client_type: Union[str, ClientType]):\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The client's service name.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, ClientType):\n        client_type = client_type.value\n\n    return _get_client_cached(ctx=self, client_type=client_type)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_s3_client","title":"<code>get_s3_client</code>","text":"<p>Gets an authenticated S3 client.</p> <p>Returns:</p> Type Description <code>S3Client</code> <p>An authenticated S3 client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_s3_client(self) -&gt; S3Client:\n    \"\"\"\n    Gets an authenticated S3 client.\n\n    Returns:\n        An authenticated S3 client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.AwsCredentials.get_secrets_manager_client","title":"<code>get_secrets_manager_client</code>","text":"<p>Gets an authenticated Secrets Manager client.</p> <p>Returns:</p> Type Description <code>SecretsManagerClient</code> <p>An authenticated Secrets Manager client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_secrets_manager_client(self) -&gt; SecretsManagerClient:\n    \"\"\"\n    Gets an authenticated Secrets Manager client.\n\n    Returns:\n        An authenticated Secrets Manager client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.SECRETS_MANAGER)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.ClientType","title":"<code>ClientType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>The supported boto3 clients.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class ClientType(Enum):\n    \"\"\"The supported boto3 clients.\"\"\"\n\n    S3 = \"s3\"\n    ECS = \"ecs\"\n    BATCH = \"batch\"\n    SECRETS_MANAGER = \"secretsmanager\"\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials","title":"<code>MinIOCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with MinIO. Refer to the MinIO docs for more info about the possible credential configurations.</p> <p>Attributes:</p> Name Type Description <code>minio_root_user</code> <code>str</code> <p>Admin or root user.</p> <code>minio_root_password</code> <code>SecretStr</code> <p>Admin or root password.</p> <code>region_name</code> <code>Optional[str]</code> <p>Location of server, e.g. \"us-east-1\".</p> Example <p>Load stored MinIO credentials: <pre><code>from prefect_aws import MinIOCredentials\n\nminio_credentials_block = MinIOCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class MinIOCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with MinIO. Refer to the\n    [MinIO docs](https://docs.min.io/docs/minio-server-configuration-guide.html)\n    for more info about the possible credential configurations.\n\n    Attributes:\n        minio_root_user: Admin or root user.\n        minio_root_password: Admin or root password.\n        region_name: Location of server, e.g. \"us-east-1\".\n\n    Example:\n        Load stored MinIO credentials:\n        ```python\n        from prefect_aws import MinIOCredentials\n\n        minio_credentials_block = MinIOCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/676cb17bcbdff601f97e0a02ff8bcb480e91ff40-250x250.png\"  # noqa\n    _block_type_name = \"MinIO Credentials\"\n    _description = (\n        \"Block used to manage authentication with MinIO. Refer to the MinIO \"\n        \"docs: https://docs.min.io/docs/minio-server-configuration-guide.html \"\n        \"for more info about the possible credential configurations.\"\n    )\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials\"  # noqa\n\n    minio_root_user: str = Field(default=..., description=\"Admin or root user.\")\n    minio_root_password: SecretStr = Field(\n        default=..., description=\"Admin or root password.\"\n    )\n    region_name: Optional[str] = Field(\n        default=None,\n        description=\"The AWS Region where you want to create new connections.\",\n    )\n    aws_client_parameters: AwsClientParameters = Field(\n        default_factory=AwsClientParameters,\n        description=\"Extra parameters to initialize the Client.\",\n    )\n\n    class Config:\n        \"\"\"Config class for pydantic model.\"\"\"\n\n        arbitrary_types_allowed = True\n\n    def __hash__(self):\n        return hash(\n            (\n                hash(self.minio_root_user),\n                hash(self.minio_root_password),\n                hash(self.region_name),\n                hash(frozenset(self.aws_client_parameters.dict().items())),\n            )\n        )\n\n    def get_boto3_session(self) -&gt; boto3.Session:\n        \"\"\"\n        Returns an authenticated boto3 session that can be used to create clients\n        and perform object operations on MinIO server.\n\n        Example:\n            Create an S3 client from an authorized boto3 session\n\n            ```python\n            minio_credentials = MinIOCredentials(\n                minio_root_user = \"minio_root_user\",\n                minio_root_password = \"minio_root_password\"\n            )\n            s3_client = minio_credentials.get_boto3_session().client(\n                service=\"s3\",\n                endpoint_url=\"http://localhost:9000\"\n            )\n            ```\n        \"\"\"\n\n        minio_root_password = (\n            self.minio_root_password.get_secret_value()\n            if self.minio_root_password\n            else None\n        )\n\n        return boto3.Session(\n            aws_access_key_id=self.minio_root_user,\n            aws_secret_access_key=minio_root_password,\n            region_name=self.region_name,\n        )\n\n    def get_client(self, client_type: Union[str, ClientType]):\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The client's service name.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, ClientType):\n            client_type = client_type.value\n\n        return _get_client_cached(ctx=self, client_type=client_type)\n\n    def get_s3_client(self) -&gt; S3Client:\n        \"\"\"\n        Gets an authenticated S3 client.\n\n        Returns:\n            An authenticated S3 client.\n        \"\"\"\n        return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.Config","title":"<code>Config</code>","text":"<p>Config class for pydantic model.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>class Config:\n    \"\"\"Config class for pydantic model.\"\"\"\n\n    arbitrary_types_allowed = True\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_boto3_session","title":"<code>get_boto3_session</code>","text":"<p>Returns an authenticated boto3 session that can be used to create clients and perform object operations on MinIO server.</p> Example <p>Create an S3 client from an authorized boto3 session</p> <pre><code>minio_credentials = MinIOCredentials(\n    minio_root_user = \"minio_root_user\",\n    minio_root_password = \"minio_root_password\"\n)\ns3_client = minio_credentials.get_boto3_session().client(\n    service=\"s3\",\n    endpoint_url=\"http://localhost:9000\"\n)\n</code></pre> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_boto3_session(self) -&gt; boto3.Session:\n    \"\"\"\n    Returns an authenticated boto3 session that can be used to create clients\n    and perform object operations on MinIO server.\n\n    Example:\n        Create an S3 client from an authorized boto3 session\n\n        ```python\n        minio_credentials = MinIOCredentials(\n            minio_root_user = \"minio_root_user\",\n            minio_root_password = \"minio_root_password\"\n        )\n        s3_client = minio_credentials.get_boto3_session().client(\n            service=\"s3\",\n            endpoint_url=\"http://localhost:9000\"\n        )\n        ```\n    \"\"\"\n\n    minio_root_password = (\n        self.minio_root_password.get_secret_value()\n        if self.minio_root_password\n        else None\n    )\n\n    return boto3.Session(\n        aws_access_key_id=self.minio_root_user,\n        aws_secret_access_key=minio_root_password,\n        region_name=self.region_name,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The client's service name.</p> required <p>Returns:</p> Type Description <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_client(self, client_type: Union[str, ClientType]):\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The client's service name.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, ClientType):\n        client_type = client_type.value\n\n    return _get_client_cached(ctx=self, client_type=client_type)\n</code></pre>"},{"location":"integrations/prefect-aws/credentials/#prefect_aws.credentials.MinIOCredentials.get_s3_client","title":"<code>get_s3_client</code>","text":"<p>Gets an authenticated S3 client.</p> <p>Returns:</p> Type Description <code>S3Client</code> <p>An authenticated S3 client.</p> Source code in <code>prefect_aws/credentials.py</code> <pre><code>def get_s3_client(self) -&gt; S3Client:\n    \"\"\"\n    Gets an authenticated S3 client.\n\n    Returns:\n        An authenticated S3 client.\n    \"\"\"\n    return self.get_client(client_type=ClientType.S3)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/","title":"ECS (deprecated)","text":""},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs","title":"<code>prefect_aws.ecs</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the ECS worker, which offers enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with the Amazon Elastic Container Service.</p> <p>Examples:</p> <pre><code>Run a task using ECS Fargate\n```python\nECSTask(command=[\"echo\", \"hello world\"]).run()\n```\n\nRun a task using ECS Fargate with a spot container instance\n```python\nECSTask(command=[\"echo\", \"hello world\"], launch_type=\"FARGATE_SPOT\").run()\n```\n\nRun a task using ECS with an EC2 container instance\n```python\nECSTask(command=[\"echo\", \"hello world\"], launch_type=\"EC2\").run()\n```\n\nRun a task on a specific VPC using ECS Fargate\n```python\nECSTask(command=[\"echo\", \"hello world\"], vpc_id=\"vpc-01abcdf123456789a\").run()\n```\n\nRun a task and stream the container's output to the local terminal. Note an\nexecution role must be provided with permissions: logs:CreateLogStream,\nlogs:CreateLogGroup, and logs:PutLogEvents.\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    stream_output=True,\n    execution_role_arn=\"...\"\n)\n```\n\nRun a task using an existing task definition as a base\n```python\nECSTask(command=[\"echo\", \"hello world\"], task_definition_arn=\"arn:aws:ecs:...\")\n```\n\nRun a task with a specific image\n```python\nECSTask(command=[\"echo\", \"hello world\"], image=\"alpine:latest\")\n```\n\nRun a task with custom memory and CPU requirements\n```python\nECSTask(command=[\"echo\", \"hello world\"], memory=4096, cpu=2048)\n```\n\nRun a task with custom environment variables\n```python\nECSTask(command=[\"echo\", \"hello $PLANET\"], env={\"PLANET\": \"earth\"})\n```\n\nRun a task in a specific ECS cluster\n```python\nECSTask(command=[\"echo\", \"hello world\"], cluster=\"my-cluster-name\")\n```\n\nRun a task with custom VPC subnets\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    task_customizations=[\n        {\n            \"op\": \"add\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/subnets\",\n            \"value\": [\"subnet-80b6fbcd\", \"subnet-42a6fdgd\"],\n        },\n    ]\n)\n```\n\nRun a task without a public IP assigned\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    vpc_id=\"vpc-01abcdf123456789a\",\n    task_customizations=[\n        {\n            \"op\": \"replace\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/assignPublicIp\",\n            \"value\": \"DISABLED\",\n        },\n    ]\n)\n```\n\nRun a task with custom VPC security groups\n```python\nECSTask(\n    command=[\"echo\", \"hello world\"],\n    vpc_id=\"vpc-01abcdf123456789a\",\n    task_customizations=[\n        {\n            \"op\": \"add\",\n            \"path\": \"/networkConfiguration/awsvpcConfiguration/securityGroups\",\n            \"value\": [\"sg-d72e9599956a084f5\"],\n        },\n    ],\n)\n```\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask","title":"<code>ECSTask</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Run a command as an ECS task.</p> <p>Attributes:</p> Name Type Description <code>type</code> <code>Literal['ecs-task']</code> <p>The slug for this task type with a default value of \"ecs-task\".</p> <code>aws_credentials</code> <code>AwsCredentials</code> <p>The AWS credentials to use to connect to ECS with a default factory of AwsCredentials.</p> <code>task_definition_arn</code> <code>Optional[str]</code> <p>An optional identifier for an existing task definition to use. If fields are set on the ECSTask that conflict with the task definition, a new copy will be registered with the required values. Cannot be used with task_definition. If not provided, Prefect will generate and register a minimal task definition.</p> <code>task_definition</code> <code>Optional[dict]</code> <p>An optional ECS task definition to use. Prefect may set defaults or override fields on this task definition to match other ECSTask fields. Cannot be used with task_definition_arn. If not provided, Prefect will generate and register a minimal task definition.</p> <code>family</code> <code>Optional[str]</code> <p>An optional family for the task definition. If not provided, it will be inferred from the task definition. If the task definition does not have a family, the name will be generated. When flow and deployment metadata is available, the generated name will include their names. Values for this field will be slugified to match AWS character requirements.</p> <code>image</code> <code>Optional[str]</code> <p>An optional image to use for the Prefect container in the task. If this value is not null, it will override the value in the task definition. This value defaults to a Prefect base image matching your local versions.</p> <code>auto_deregister_task_definition</code> <code>bool</code> <p>A boolean that controls if any task definitions that are created by this block will be deregistered or not. Existing task definitions linked by ARN will never be deregistered. Deregistering a task definition does not remove it from your AWS account, instead it will be marked as INACTIVE.</p> <code>cpu</code> <code>int</code> <p>The amount of CPU to provide to the ECS task. Valid amounts are specified in the AWS documentation. If not provided, a default value of ECS_DEFAULT_CPU will be used unless present on the task definition.</p> <code>memory</code> <code>int</code> <p>The amount of memory to provide to the ECS task. Valid amounts are specified in the AWS documentation. If not provided, a default value of ECS_DEFAULT_MEMORY will be used unless present on the task definition.</p> <code>execution_role_arn</code> <code>str</code> <p>An execution role to use for the task. This controls the permissions of the task when it is launching. If this value is not null, it will override the value in the task definition. An execution role must be provided to capture logs from the container.</p> <code>configure_cloudwatch_logs</code> <code>bool</code> <p>A boolean that controls if the Prefect container will be configured to send its output to the AWS CloudWatch logs service or not. This functionality requires an execution role with permissions to create log streams and groups.</p> <code>cloudwatch_logs_options</code> <code>Dict[str, str]</code> <p>A dictionary of options to pass to the CloudWatch logs configuration.</p> <code>stream_output</code> <code>bool</code> <p>A boolean indicating whether logs will be streamed from the Prefect container to the local console.</p> <code>launch_type</code> <code>Optional[Literal['FARGATE', 'EC2', 'EXTERNAL', 'FARGATE_SPOT']]</code> <p>An optional launch type for the ECS task run infrastructure.</p> <code>vpc_id</code> <code>Optional[str]</code> <p>An optional VPC ID to link the task run to. This is only applicable when using the 'awsvpc' network mode for your task.</p> <code>cluster</code> <code>Optional[str]</code> <p>An optional ECS cluster to run the task in. The ARN or name may be provided. If not provided, the default cluster will be used.</p> <code>env</code> <code>Dict[str, Optional[str]]</code> <p>A dictionary of environment variables to provide to the task run. These variables are set on the Prefect container at task runtime.</p> <code>task_role_arn</code> <code>str</code> <p>An optional role to attach to the task run. This controls the permissions of the task while it is running.</p> <code>task_customizations</code> <code>JsonPatch</code> <p>A list of JSON 6902 patches to apply to the task run request. If a string is given, it will parsed as a JSON expression.</p> <code>task_start_timeout_seconds</code> <code>int</code> <p>The amount of time to watch for the start of the ECS task before marking it as failed. The task must enter a RUNNING state to be considered started.</p> <code>task_watch_poll_interval</code> <code>float</code> <p>The amount of time to wait between AWS API calls while monitoring the state of an ECS task.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the ECS worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass ECSTask(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Run a command as an ECS task.\n\n    Attributes:\n        type: The slug for this task type with a default value of \"ecs-task\".\n        aws_credentials: The AWS credentials to use to connect to ECS with a\n            default factory of AwsCredentials.\n        task_definition_arn: An optional identifier for an existing task definition\n            to use. If fields are set on the ECSTask that conflict with the task\n            definition, a new copy will be registered with the required values.\n            Cannot be used with task_definition. If not provided, Prefect will\n            generate and register a minimal task definition.\n        task_definition: An optional ECS task definition to use. Prefect may set\n            defaults or override fields on this task definition to match other\n            ECSTask fields. Cannot be used with task_definition_arn.\n            If not provided, Prefect will generate and register\n            a minimal task definition.\n        family: An optional family for the task definition. If not provided,\n            it will be inferred from the task definition. If the task definition\n            does not have a family, the name will be generated. When flow and\n            deployment metadata is available, the generated name will include\n            their names. Values for this field will be slugified to match\n            AWS character requirements.\n        image: An optional image to use for the Prefect container in the task.\n            If this value is not null, it will override the value in the task\n            definition. This value defaults to a Prefect base image matching\n            your local versions.\n        auto_deregister_task_definition: A boolean that controls if any task\n            definitions that are created by this block will be deregistered\n            or not. Existing task definitions linked by ARN will never be\n            deregistered. Deregistering a task definition does not remove\n            it from your AWS account, instead it will be marked as INACTIVE.\n        cpu: The amount of CPU to provide to the ECS task. Valid amounts are\n            specified in the AWS documentation. If not provided, a default\n            value of ECS_DEFAULT_CPU will be used unless present on\n            the task definition.\n        memory: The amount of memory to provide to the ECS task.\n            Valid amounts are specified in the AWS documentation.\n            If not provided, a default value of ECS_DEFAULT_MEMORY\n            will be used unless present on the task definition.\n        execution_role_arn: An execution role to use for the task.\n            This controls the permissions of the task when it is launching.\n            If this value is not null, it will override the value in the task\n            definition. An execution role must be provided to capture logs\n            from the container.\n        configure_cloudwatch_logs: A boolean that controls if the Prefect\n            container will be configured to send its output to the\n            AWS CloudWatch logs service or not. This functionality requires\n            an execution role with permissions to create log streams and groups.\n        cloudwatch_logs_options: A dictionary of options to pass to\n            the CloudWatch logs configuration.\n        stream_output: A boolean indicating whether logs will be\n            streamed from the Prefect container to the local console.\n        launch_type: An optional launch type for the ECS task run infrastructure.\n        vpc_id: An optional VPC ID to link the task run to.\n            This is only applicable when using the 'awsvpc' network mode for your task.\n        cluster: An optional ECS cluster to run the task in.\n            The ARN or name may be provided. If not provided,\n            the default cluster will be used.\n        env: A dictionary of environment variables to provide to\n            the task run. These variables are set on the\n            Prefect container at task runtime.\n        task_role_arn: An optional role to attach to the task run.\n            This controls the permissions of the task while it is running.\n        task_customizations: A list of JSON 6902 patches to apply to the task\n            run request. If a string is given, it will parsed as a JSON expression.\n        task_start_timeout_seconds: The amount of time to watch for the\n            start of the ECS task before marking it as failed. The task must\n            enter a RUNNING state to be considered started.\n        task_watch_poll_interval: The amount of time to wait between AWS API\n            calls while monitoring the state of an ECS task.\n    \"\"\"\n\n    _block_type_slug = \"ecs-task\"\n    _block_type_name = \"ECS Task\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _description = \"Run a command as an ECS task.\"  # noqa\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-aws/ecs/#prefect_aws.ecs.ECSTask\"  # noqa\n    )\n\n    type: Literal[\"ecs-task\"] = Field(\n        \"ecs-task\", description=\"The slug for this task type.\"\n    )\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to ECS.\",\n    )\n\n    # Task definition settings\n    task_definition_arn: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier for an existing task definition to use. If fields are set \"\n            \"on the `ECSTask` that conflict with the task definition, a new copy \"\n            \"will be registered with the required values. \"\n            \"Cannot be used with `task_definition`. If not provided, Prefect will \"\n            \"generate and register a minimal task definition.\"\n        ),\n    )\n    task_definition: Optional[dict] = Field(\n        default=None,\n        description=(\n            \"An ECS task definition to use. Prefect may set defaults or override \"\n            \"fields on this task definition to match other `ECSTask` fields. \"\n            \"Cannot be used with `task_definition_arn`. If not provided, Prefect will \"\n            \"generate and register a minimal task definition.\"\n        ),\n    )\n    family: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A family for the task definition. If not provided, it will be inferred \"\n            \"from the task definition. If the task definition does not have a family, \"\n            \"the name will be generated. When flow and deployment metadata is \"\n            \"available, the generated name will include their names. Values for this \"\n            \"field will be slugified to match AWS character requirements.\"\n        ),\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. If this value is \"\n            \"not null, it will override the value in the task definition. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    auto_deregister_task_definition: bool = Field(\n        default=True,\n        description=(\n            \"If set, any task definitions that are created by this block will be \"\n            \"deregistered. Existing task definitions linked by ARN will never be \"\n            \"deregistered. Deregistering a task definition does not remove it from \"\n            \"your AWS account, instead it will be marked as INACTIVE.\"\n        ),\n    )\n\n    # Mixed task definition / run settings\n    cpu: int = Field(\n        title=\"CPU\",\n        default=None,\n        description=(\n            \"The amount of CPU to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_CPU} will be used unless present on the task definition.\"\n        ),\n    )\n    memory: int = Field(\n        default=None,\n        description=(\n            \"The amount of memory to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_MEMORY} will be used unless present on the task definition.\"\n        ),\n    )\n    execution_role_arn: str = Field(\n        title=\"Execution Role ARN\",\n        default=None,\n        description=(\n            \"An execution role to use for the task. This controls the permissions of \"\n            \"the task when it is launching. If this value is not null, it will \"\n            \"override the value in the task definition. An execution role must be \"\n            \"provided to capture logs from the container.\"\n        ),\n    )\n    configure_cloudwatch_logs: bool = Field(\n        default=None,\n        description=(\n            \"If `True`, the Prefect container will be configured to send its output \"\n            \"to the AWS CloudWatch logs service. This functionality requires an \"\n            \"execution role with logs:CreateLogStream, logs:CreateLogGroup, and \"\n            \"logs:PutLogEvents permissions. The default for this field is `False` \"\n            \"unless `stream_output` is set.\"\n        ),\n    )\n    cloudwatch_logs_options: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to \"\n            \"pass additional options to the CloudWatch logs configuration or override \"\n            \"the default options. See the AWS documentation for available options. \"\n            \"https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html#create_awslogs_logdriver_options.\"  # noqa\n        ),\n    )\n    stream_output: bool = Field(\n        default=None,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console. Unless you have configured AWS CloudWatch logs manually on your \"\n            \"task definition, this requires the same prerequisites outlined in \"\n            \"`configure_cloudwatch_logs`.\"\n        ),\n    )\n\n    # Task run settings\n    launch_type: Optional[\n        Literal[\"FARGATE\", \"EC2\", \"EXTERNAL\", \"FARGATE_SPOT\"]\n    ] = Field(\n        default=\"FARGATE\",\n        description=(\n            \"The type of ECS task run infrastructure that should be used. Note that\"\n            \" 'FARGATE_SPOT' is not a formal ECS launch type, but we will configure\"\n            \" the proper capacity provider strategy if set here.\"\n        ),\n    )\n    vpc_id: Optional[str] = Field(\n        title=\"VPC ID\",\n        default=None,\n        description=(\n            \"The AWS VPC to link the task run to. This is only applicable when using \"\n            \"the 'awsvpc' network mode for your task. FARGATE tasks require this \"\n            \"network  mode, but for EC2 tasks the default network mode is 'bridge'. \"\n            \"If using the 'awsvpc' network mode and this field is null, your default \"\n            \"VPC will be used. If no default VPC can be found, the task run will fail.\"\n        ),\n    )\n    cluster: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The ECS cluster to run the task in. The ARN or name may be provided. If \"\n            \"not provided, the default cluster will be used.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    task_role_arn: str = Field(\n        title=\"Task Role ARN\",\n        default=None,\n        description=(\n            \"A role to attach to the task run. This controls the permissions of the \"\n            \"task while it is running.\"\n        ),\n    )\n    task_customizations: JsonPatch = Field(\n        default_factory=lambda: JsonPatch([]),\n        description=(\n            \"A list of JSON 6902 patches to apply to the task run request. \"\n            \"If a string is given, it will parsed as a JSON expression.\"\n        ),\n    )\n\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=120,\n        description=(\n            \"The amount of time to watch for the start of the ECS task \"\n            \"before marking it as failed. The task must enter a RUNNING state to be \"\n            \"considered started.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an ECS task.\"\n        ),\n    )\n\n    @root_validator(pre=True)\n    def set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Streaming output generally requires CloudWatch logs to be configured.\n\n        To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n        defaults to matching the value of `stream_output`.\n        \"\"\"\n        configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n        if configure_cloudwatch_logs is None:\n            values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n        return values\n\n    @root_validator\n    def configure_cloudwatch_logs_requires_execution_role_arn(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if (\n            values.get(\"configure_cloudwatch_logs\")\n            and not values.get(\"execution_role_arn\")\n            # Do not raise if they've linked to another task definition or provided\n            # it without using our shortcuts\n            and not values.get(\"task_definition_arn\")\n            and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n        ):\n            raise ValueError(\n                \"An `execution_role_arn` must be provided to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs`.\"\n            )\n        return values\n\n    @root_validator\n    def cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if values.get(\"cloudwatch_logs_options\") and not values.get(\n            \"configure_cloudwatch_logs\"\n        ):\n            raise ValueError(\n                \"`configure_cloudwatch_log` must be enabled to use \"\n                \"`cloudwatch_logs_options`.\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def image_is_required(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Enforces that an image is available if image is `None`.\n        \"\"\"\n        has_image = bool(values.get(\"image\"))\n        has_task_definition_arn = bool(values.get(\"task_definition_arn\"))\n\n        # The image can only be null when the task_definition_arn is set\n        if has_image or has_task_definition_arn:\n            return values\n\n        prefect_container = (\n            get_prefect_container(\n                (values.get(\"task_definition\") or {}).get(\"containerDefinitions\", [])\n            )\n            or {}\n        )\n        image_in_task_definition = prefect_container.get(\"image\")\n\n        # If a task_definition is given with a prefect container image, use that value\n        if image_in_task_definition:\n            values[\"image\"] = image_in_task_definition\n        # Otherwise, it should default to the Prefect base image\n        else:\n            values[\"image\"] = get_prefect_image_name()\n        return values\n\n    @validator(\"task_customizations\", pre=True)\n    def cast_customizations_to_a_json_patch(\n        cls, value: Union[List[Dict], JsonPatch, str]\n    ) -&gt; JsonPatch:\n        \"\"\"\n        Casts lists to JsonPatch instances.\n        \"\"\"\n        if isinstance(value, str):\n            value = json.loads(value)\n        if isinstance(value, list):\n            return JsonPatch(value)\n        return value  # type: ignore\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'JsonPatch' type\n        arbitrary_types_allowed = True\n        json_encoders = {JsonPatch: lambda p: p.patch}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'JsonPatch' type\n        d = super().dict(*args, **kwargs)\n        d[\"task_customizations\"] = self.task_customizations.patch\n        return d\n\n    def prepare_for_flow_run(\n        self: Self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"Deployment\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ) -&gt; Self:\n        \"\"\"\n        Return an copy of the block that is prepared to execute a flow run.\n        \"\"\"\n        new_family = None\n\n        # Update the family if not specified elsewhere\n        if (\n            not self.family\n            and not self.task_definition_arn\n            and not (self.task_definition and self.task_definition.get(\"family\"))\n        ):\n            if flow and deployment:\n                new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}__{deployment.name}\"\n            elif flow and not deployment:\n                new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}\"\n            elif deployment and not flow:\n                # This is a weird case and should not be see in the wild\n                new_family = f\"{ECS_DEFAULT_FAMILY}__unknown-flow__{deployment.name}\"\n\n        new = super().prepare_for_flow_run(flow_run, deployment=deployment, flow=flow)\n\n        if new_family:\n            return new.copy(update={\"family\": new_family})\n        else:\n            # Avoid an extra copy if not needed\n            return new\n\n    @sync_compatible\n    async def run(self, task_status: Optional[TaskStatus] = None) -&gt; ECSTaskResult:\n        \"\"\"\n        Run the configured task on ECS.\n        \"\"\"\n        boto_session, ecs_client = await run_sync_in_worker_thread(\n            self._get_session_and_client\n        )\n\n        (\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition,\n        ) = await run_sync_in_worker_thread(\n            self._create_task_and_wait_for_start, boto_session, ecs_client\n        )\n\n        # Display a nice message indicating the command and image\n        command = self.command or get_prefect_container(\n            task_definition[\"containerDefinitions\"]\n        ).get(\"command\", [])\n        self.logger.info(\n            f\"{self._log_prefix}: Running command {' '.join(command)!r} \"\n            f\"in container {PREFECT_ECS_CONTAINER_NAME!r} ({self.image})...\"\n        )\n\n        # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n        # if set to preserve matching by name rather than arn\n        # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n        # single colons.\n        identifier = (self.cluster if self.cluster else cluster_arn) + \"::\" + task_arn\n\n        if task_status:\n            task_status.started(identifier)\n\n        status_code = await run_sync_in_worker_thread(\n            self._watch_task_and_get_exit_code,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition and self.auto_deregister_task_definition,\n            boto_session,\n            ecs_client,\n        )\n\n        return ECSTaskResult(\n            identifier=identifier,\n            # If the container does not start the exit code can be null but we must\n            # still report a status code. We use a -1 to indicate a special code.\n            status_code=status_code if status_code is not None else -1,\n        )\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a task running on ECS.\n\n        Args:\n            identifier: A cluster and task arn combination. This should match a value\n                yielded by `ECSTask.run`.\n        \"\"\"\n        if grace_seconds != 30:\n            self.logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n                \"support dynamic grace period configuration so 30s will be used. \"\n                \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n            )\n        cluster, task = parse_task_identifier(identifier)\n        await run_sync_in_worker_thread(self._stop_task, cluster, task)\n\n    @staticmethod\n    def get_corresponding_worker_type() -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return ECSWorker.type\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a cloud-run work pool with the same\n        configuration as this block.\n\n        Returns:\n            - dict: a base job template for a cloud-run work pool\n        \"\"\"\n        base_job_template = copy.deepcopy(ECSWorker.get_default_base_job_template())\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"task_customizations\",\n            ]:\n                continue\n            elif key == \"aws_credentials\":\n                if not self.aws_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"aws_credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.aws_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"task_definition\":\n                base_job_template[\"job_configuration\"][\"task_definition\"] = value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                    \" Skipping.\"\n                )\n\n        if self.task_customizations:\n            network_config_patches = JsonPatch(\n                [\n                    patch\n                    for patch in self.task_customizations\n                    if \"networkConfiguration\" in patch[\"path\"]\n                ]\n            )\n            minimal_network_config = assemble_document_for_patches(\n                network_config_patches\n            )\n            if minimal_network_config:\n                minimal_network_config_with_patches = network_config_patches.apply(\n                    minimal_network_config\n                )\n                base_job_template[\"variables\"][\"properties\"][\"network_configuration\"][\n                    \"default\"\n                ] = minimal_network_config_with_patches[\"networkConfiguration\"][\n                    \"awsvpcConfiguration\"\n                ]\n            try:\n                base_job_template[\"job_configuration\"][\n                    \"task_run_request\"\n                ] = self.task_customizations.apply(\n                    base_job_template[\"job_configuration\"][\"task_run_request\"]\n                )\n            except JsonPointerException:\n                self.logger.warning(\n                    \"Unable to apply task customizations to the base job template.\"\n                    \"You may need to update the template manually.\"\n                )\n\n        return base_job_template\n\n    def _stop_task(self, cluster: str, task: str) -&gt; None:\n        \"\"\"\n        Stop a running ECS task.\n        \"\"\"\n        if self.cluster is not None and cluster != self.cluster:\n            raise InfrastructureNotAvailable(\n                \"Cannot stop ECS task: this infrastructure block has access to \"\n                f\"cluster {self.cluster!r} but the task is running in cluster \"\n                f\"{cluster!r}.\"\n            )\n\n        _, ecs_client = self._get_session_and_client()\n        try:\n            ecs_client.stop_task(cluster=cluster, task=task)\n        except Exception as exc:\n            # Raise a special exception if the task does not exist\n            if \"ClusterNotFound\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} could not be found.\"\n                ) from exc\n            if \"not find task\" in str(exc) or \"referenced task was not found\" in str(\n                exc\n            ):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the task {task!r} could not be found in \"\n                    f\"cluster {cluster!r}.\"\n                ) from exc\n            if \"no registered tasks\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} has no tasks.\"\n                ) from exc\n\n            # Reraise unknown exceptions\n            raise\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"ECSTask {self.name!r}\"\n        else:\n            return \"ECSTask\"\n\n    def _get_session_and_client(self) -&gt; Tuple[boto3.Session, _ECSClient]:\n        \"\"\"\n        Retrieve a boto3 session and ECS client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        ecs_client = boto_session.client(\"ecs\")\n        return boto_session, ecs_client\n\n    def _create_task_and_wait_for_start(\n        self, boto_session: boto3.Session, ecs_client: _ECSClient\n    ) -&gt; Tuple[str, str, dict, bool]:\n        \"\"\"\n        Register the task definition, create the task run, and wait for it to start.\n\n        Returns a tuple of\n        - The task ARN\n        - The task's cluster ARN\n        - The task definition\n        - A bool indicating if the task definition is newly registered\n        \"\"\"\n        new_task_definition_registered = False\n        requested_task_definition = (\n            self._retrieve_task_definition(ecs_client, self.task_definition_arn)\n            if self.task_definition_arn\n            else self.task_definition\n        ) or {}\n        task_definition_arn = requested_task_definition.get(\"taskDefinitionArn\", None)\n\n        task_definition = self._prepare_task_definition(\n            requested_task_definition, region=ecs_client.meta.region_name\n        )\n\n        # We must register the task definition if the arn is null or changes were made\n        if task_definition != requested_task_definition or not task_definition_arn:\n            # Before registering, check if the latest task definition in the family\n            # can be used\n            latest_task_definition = self._retrieve_latest_task_definition(\n                ecs_client, task_definition[\"family\"]\n            )\n            if self._task_definitions_equal(latest_task_definition, task_definition):\n                self.logger.debug(\n                    f\"{self._log_prefix}: The latest task definition matches the \"\n                    \"required task definition; using that instead of registering a new \"\n                    \" one.\"\n                )\n                task_definition_arn = latest_task_definition[\"taskDefinitionArn\"]\n            else:\n                if task_definition_arn:\n                    self.logger.warning(\n                        f\"{self._log_prefix}: Settings require changes to the linked \"\n                        \"task definition. A new task definition will be registered. \"\n                        + (\n                            \"Enable DEBUG level logs to see the difference.\"\n                            if self.logger.level &gt; logging.DEBUG\n                            else \"\"\n                        )\n                    )\n                    self.logger.debug(\n                        f\"{self._log_prefix}: Diff for requested task definition\"\n                        + _pretty_diff(requested_task_definition, task_definition)\n                    )\n                else:\n                    self.logger.info(\n                        f\"{self._log_prefix}: Registering task definition...\"\n                    )\n                    self.logger.debug(\n                        \"Task definition payload\\n\" + yaml.dump(task_definition)\n                    )\n\n                task_definition_arn = self._register_task_definition(\n                    ecs_client, task_definition\n                )\n                new_task_definition_registered = True\n\n        if task_definition.get(\"networkMode\") == \"awsvpc\":\n            network_config = self._load_vpc_network_config(self.vpc_id, boto_session)\n        else:\n            network_config = None\n\n        task_run = self._prepare_task_run(\n            network_config=network_config,\n            task_definition_arn=task_definition_arn,\n        )\n        self.logger.info(f\"{self._log_prefix}: Creating task run...\")\n        self.logger.debug(\"Task run payload\\n\" + yaml.dump(task_run))\n\n        try:\n            task = self._run_task(ecs_client, task_run)\n            task_arn = task[\"taskArn\"]\n            cluster_arn = task[\"clusterArn\"]\n        except Exception as exc:\n            self._report_task_run_creation_failure(task_run, exc)\n\n        # Raises an exception if the task does not start\n        self.logger.info(f\"{self._log_prefix}: Waiting for task run to start...\")\n        self._wait_for_task_start(\n            task_arn, cluster_arn, ecs_client, timeout=self.task_start_timeout_seconds\n        )\n\n        return task_arn, cluster_arn, task_definition, new_task_definition_registered\n\n    def _watch_task_and_get_exit_code(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        deregister_task_definition: bool,\n        boto_session: boto3.Session,\n        ecs_client: _ECSClient,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Wait for the task run to complete and retrieve the exit code of the Prefect\n        container.\n        \"\"\"\n\n        # Wait for completion and stream logs\n        task = self._wait_for_task_finish(\n            task_arn, cluster_arn, task_definition, ecs_client, boto_session\n        )\n\n        if deregister_task_definition:\n            ecs_client.deregister_task_definition(\n                taskDefinition=task[\"taskDefinitionArn\"]\n            )\n\n        # Check the status code of the Prefect container\n        prefect_container = get_prefect_container(task[\"containers\"])\n        assert (\n            prefect_container is not None\n        ), f\"'prefect' container missing from task: {task}\"\n        status_code = prefect_container.get(\"exitCode\")\n        self._report_container_status_code(PREFECT_ECS_CONTAINER_NAME, status_code)\n\n        return status_code\n\n    def _task_definitions_equal(self, taskdef_1, taskdef_2) -&gt; bool:\n        \"\"\"\n        Compare two task definitions.\n\n        Since one may come from the AWS API and have populated defaults, we do our best\n        to homogenize the definitions without changing their meaning.\n        \"\"\"\n        if taskdef_1 == taskdef_2:\n            return True\n\n        if taskdef_1 is None or taskdef_2 is None:\n            return False\n\n        taskdef_1 = copy.deepcopy(taskdef_1)\n        taskdef_2 = copy.deepcopy(taskdef_2)\n\n        def _set_aws_defaults(taskdef):\n            \"\"\"Set defaults that AWS would set after registration\"\"\"\n            container_definitions = taskdef.get(\"containerDefinitions\", [])\n            essential = any(\n                container.get(\"essential\") for container in container_definitions\n            )\n            if not essential:\n                container_definitions[0].setdefault(\"essential\", True)\n\n            taskdef.setdefault(\"networkMode\", \"bridge\")\n\n        _set_aws_defaults(taskdef_1)\n        _set_aws_defaults(taskdef_2)\n\n        def _drop_empty_keys(dict_):\n            \"\"\"Recursively drop keys with 'empty' values\"\"\"\n            for key, value in tuple(dict_.items()):\n                if not value:\n                    dict_.pop(key)\n                if isinstance(value, dict):\n                    _drop_empty_keys(value)\n                if isinstance(value, list):\n                    for v in value:\n                        if isinstance(v, dict):\n                            _drop_empty_keys(v)\n\n        _drop_empty_keys(taskdef_1)\n        _drop_empty_keys(taskdef_2)\n\n        # Clear fields that change on registration for comparison\n        for field in POST_REGISTRATION_FIELDS:\n            taskdef_1.pop(field, None)\n            taskdef_2.pop(field, None)\n\n        return taskdef_1 == taskdef_2\n\n    def preview(self) -&gt; str:\n        \"\"\"\n        Generate a preview of the task definition and task run that will be sent to AWS.\n        \"\"\"\n        preview = \"\"\n\n        task_definition_arn = self.task_definition_arn or \"&lt;registered at runtime&gt;\"\n\n        if self.task_definition or not self.task_definition_arn:\n            task_definition = self._prepare_task_definition(\n                self.task_definition or {},\n                region=self.aws_credentials.region_name\n                or \"&lt;loaded from client at runtime&gt;\",\n            )\n            preview += \"---\\n# Task definition\\n\"\n            preview += yaml.dump(task_definition)\n            preview += \"\\n\"\n        else:\n            task_definition = None\n\n        if task_definition and task_definition.get(\"networkMode\") == \"awsvpc\":\n            vpc = \"the default VPC\" if not self.vpc_id else self.vpc_id\n            network_config = {\n                \"awsvpcConfiguration\": {\n                    \"subnets\": f\"&lt;loaded from {vpc} at runtime&gt;\",\n                    \"assignPublicIp\": \"ENABLED\",\n                }\n            }\n        else:\n            network_config = None\n\n        task_run = self._prepare_task_run(network_config, task_definition_arn)\n        preview += \"---\\n# Task run request\\n\"\n        preview += yaml.dump(task_run)\n\n        return preview\n\n    def _report_container_status_code(\n        self, name: str, status_code: Optional[int]\n    ) -&gt; None:\n        \"\"\"\n        Display a log for the given container status code.\n        \"\"\"\n        if status_code is None:\n            self.logger.error(\n                f\"{self._log_prefix}: Task exited without reporting an exit status \"\n                f\"for container {name!r}.\"\n            )\n        elif status_code == 0:\n            self.logger.info(\n                f\"{self._log_prefix}: Container {name!r} exited successfully.\"\n            )\n        else:\n            self.logger.warning(\n                f\"{self._log_prefix}: Container {name!r} exited with non-zero exit \"\n                f\"code {status_code}.\"\n            )\n\n    def _report_task_run_creation_failure(self, task_run: dict, exc: Exception) -&gt; None:\n        \"\"\"\n        Wrap common AWS task run creation failures with nicer user-facing messages.\n        \"\"\"\n        # AWS generates exception types at runtime so they must be captured a bit\n        # differently than normal.\n        if \"ClusterNotFoundException\" in str(exc):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} not found. \"\n                \"Confirm that the cluster is configured in your region.\"\n            ) from exc\n        elif \"No Container Instances\" in str(exc) and self.launch_type == \"EC2\":\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} does not appear to \"\n                \"have any container instances associated with it. Confirm that you \"\n                \"have EC2 container instances available.\"\n            ) from exc\n        elif (\n            \"failed to validate logger args\" in str(exc)\n            and \"AccessDeniedException\" in str(exc)\n            and self.configure_cloudwatch_logs\n        ):\n            raise RuntimeError(\n                \"Failed to run ECS task, the attached execution role does not appear \"\n                \"to have sufficient permissions. Ensure that the execution role \"\n                f\"{self.execution_role!r} has permissions logs:CreateLogStream, \"\n                \"logs:CreateLogGroup, and logs:PutLogEvents.\"\n            )\n        else:\n            raise\n\n    def _watch_task_run(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        current_status: str = \"UNKNOWN\",\n        until_status: str = None,\n        timeout: int = None,\n    ) -&gt; Generator[None, None, dict]:\n        \"\"\"\n        Watches an ECS task run by querying every `poll_interval` seconds. After each\n        query, the retrieved task is yielded. This function returns when the task run\n        reaches a STOPPED status or the provided `until_status`.\n\n        Emits a log each time the status changes.\n        \"\"\"\n        last_status = status = current_status\n        t0 = time.time()\n        while status != until_status:\n            tasks = ecs_client.describe_tasks(\n                tasks=[task_arn], cluster=cluster_arn, include=[\"TAGS\"]\n            )[\"tasks\"]\n\n            if tasks:\n                task = tasks[0]\n\n                status = task[\"lastStatus\"]\n                if status != last_status:\n                    self.logger.info(f\"{self._log_prefix}: Status is {status}.\")\n\n                yield task\n\n                # No point in continuing if the status is final\n                if status == \"STOPPED\":\n                    break\n\n                last_status = status\n\n            else:\n                # Intermittently, the task will not be described. We wat to respect the\n                # watch timeout though.\n                self.logger.debug(f\"{self._log_prefix}: Task not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching task for status \"\n                    f\"{until_status or 'STOPPED'}\"\n                )\n            time.sleep(self.task_watch_poll_interval)\n\n    def _wait_for_task_start(\n        self, task_arn: str, cluster_arn: str, ecs_client: _ECSClient, timeout: int\n    ) -&gt; dict:\n        \"\"\"\n        Waits for an ECS task run to reach a RUNNING status.\n\n        If a STOPPED status is reached instead, an exception is raised indicating the\n        reason that the task run did not start.\n        \"\"\"\n        for task in self._watch_task_run(\n            task_arn, cluster_arn, ecs_client, until_status=\"RUNNING\", timeout=timeout\n        ):\n            # TODO: It is possible that the task has passed _through_ a RUNNING\n            #       status during the polling interval. In this case, there is not an\n            #       exception to raise.\n            if task[\"lastStatus\"] == \"STOPPED\":\n                code = task.get(\"stopCode\")\n                reason = task.get(\"stoppedReason\")\n                # Generate a dynamic exception type from the AWS name\n                raise type(code, (RuntimeError,), {})(reason)\n\n        return task\n\n    def _wait_for_task_finish(\n        self,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        ecs_client: _ECSClient,\n        boto_session: boto3.Session,\n    ):\n        \"\"\"\n        Watch an ECS task until it reaches a STOPPED status.\n\n        If configured, logs from the Prefect container are streamed to stderr.\n\n        Returns a description of the task on completion.\n        \"\"\"\n        can_stream_output = False\n\n        if self.stream_output:\n            container_def = get_prefect_container(\n                task_definition[\"containerDefinitions\"]\n            )\n            if not container_def:\n                self.logger.warning(\n                    f\"{self._log_prefix}: Prefect container definition not found in \"\n                    \"task definition. Output cannot be streamed.\"\n                )\n            elif not container_def.get(\"logConfiguration\"):\n                self.logger.warning(\n                    f\"{self._log_prefix}: Logging configuration not found on task. \"\n                    \"Output cannot be streamed.\"\n                )\n            elif not container_def[\"logConfiguration\"].get(\"logDriver\") == \"awslogs\":\n                self.logger.warning(\n                    f\"{self._log_prefix}: Logging configuration uses unsupported \"\n                    \" driver {container_def['logConfiguration'].get('logDriver')!r}. \"\n                    \"Output cannot be streamed.\"\n                )\n            else:\n                # Prepare to stream the output\n                log_config = container_def[\"logConfiguration\"][\"options\"]\n                logs_client = boto_session.client(\"logs\")\n                can_stream_output = True\n                # Track the last log timestamp to prevent double display\n                last_log_timestamp: Optional[int] = None\n                # Determine the name of the stream as \"prefix/container/run-id\"\n                stream_name = \"/\".join(\n                    [\n                        log_config[\"awslogs-stream-prefix\"],\n                        PREFECT_ECS_CONTAINER_NAME,\n                        task_arn.rsplit(\"/\")[-1],\n                    ]\n                )\n                self.logger.info(\n                    f\"{self._log_prefix}: Streaming output from container \"\n                    f\"{PREFECT_ECS_CONTAINER_NAME!r}...\"\n                )\n\n        for task in self._watch_task_run(\n            task_arn, cluster_arn, ecs_client, current_status=\"RUNNING\"\n        ):\n            if self.stream_output and can_stream_output:\n                # On each poll for task run status, also retrieve available logs\n                last_log_timestamp = self._stream_available_logs(\n                    logs_client,\n                    log_group=log_config[\"awslogs-group\"],\n                    log_stream=stream_name,\n                    last_log_timestamp=last_log_timestamp,\n                )\n\n        return task\n\n    def _stream_available_logs(\n        self,\n        logs_client: Any,\n        log_group: str,\n        log_stream: str,\n        last_log_timestamp: Optional[int] = None,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Stream logs from the given log group and stream since the last log timestamp.\n\n        Will continue on paginated responses until all logs are returned.\n\n        Returns the last log timestamp which can be used to call this method in the\n        future.\n        \"\"\"\n        last_log_stream_token = \"NO-TOKEN\"\n        next_log_stream_token = None\n\n        # AWS will return the same token that we send once the end of the paginated\n        # response is reached\n        while last_log_stream_token != next_log_stream_token:\n            last_log_stream_token = next_log_stream_token\n\n            request = {\n                \"logGroupName\": log_group,\n                \"logStreamName\": log_stream,\n            }\n\n            if last_log_stream_token is not None:\n                request[\"nextToken\"] = last_log_stream_token\n\n            if last_log_timestamp is not None:\n                # Bump the timestamp by one ms to avoid retrieving the last log again\n                request[\"startTime\"] = last_log_timestamp + 1\n\n            try:\n                response = logs_client.get_log_events(**request)\n            except Exception:\n                self.logger.error(\n                    (\n                        f\"{self._log_prefix}: Failed to read log events with request \"\n                        f\"{request}\"\n                    ),\n                    exc_info=True,\n                )\n                return last_log_timestamp\n\n            log_events = response[\"events\"]\n            for log_event in log_events:\n                # TODO: This doesn't forward to the local logger, which can be\n                #       bad for customizing handling and understanding where the\n                #       log is coming from, but it avoid nesting logger information\n                #       when the content is output from a Prefect logger on the\n                #       running infrastructure\n                print(log_event[\"message\"], file=sys.stderr)\n\n                if (\n                    last_log_timestamp is None\n                    or log_event[\"timestamp\"] &gt; last_log_timestamp\n                ):\n                    last_log_timestamp = log_event[\"timestamp\"]\n\n            next_log_stream_token = response.get(\"nextForwardToken\")\n            if not log_events:\n                # Stop reading pages if there was no data\n                break\n\n        return last_log_timestamp\n\n    def _retrieve_latest_task_definition(\n        self, ecs_client: _ECSClient, task_definition_family: str\n    ) -&gt; Optional[dict]:\n        try:\n            latest_task_definition = self._retrieve_task_definition(\n                ecs_client, task_definition_family\n            )\n        except Exception:\n            # The family does not exist...\n            return None\n\n        return latest_task_definition\n\n    def _retrieve_task_definition(\n        self, ecs_client: _ECSClient, task_definition_arn: str\n    ):\n        \"\"\"\n        Retrieve an existing task definition from AWS.\n        \"\"\"\n        self.logger.info(\n            f\"{self._log_prefix}: Retrieving task definition {task_definition_arn!r}...\"\n        )\n        response = ecs_client.describe_task_definition(\n            taskDefinition=task_definition_arn\n        )\n        return response[\"taskDefinition\"]\n\n    def _register_task_definition(\n        self, ecs_client: _ECSClient, task_definition: dict\n    ) -&gt; str:\n        \"\"\"\n        Register a new task definition with AWS.\n        \"\"\"\n        # TODO: Consider including a global cache for this task definition since\n        #       registration of task definitions is frequently rate limited\n        task_definition_request = copy.deepcopy(task_definition)\n\n        # We need to remove some fields here if copying an existing task definition\n        for field in POST_REGISTRATION_FIELDS:\n            task_definition_request.pop(field, None)\n\n        response = ecs_client.register_task_definition(**task_definition_request)\n        return response[\"taskDefinition\"][\"taskDefinitionArn\"]\n\n    def _prepare_task_definition(self, task_definition: dict, region: str) -&gt; dict:\n        \"\"\"\n        Prepare a task definition by inferring any defaults and merging overrides.\n        \"\"\"\n        task_definition = copy.deepcopy(task_definition)\n\n        # Configure the Prefect runtime container\n        task_definition.setdefault(\"containerDefinitions\", [])\n        container = get_prefect_container(task_definition[\"containerDefinitions\"])\n        if container is None:\n            container = {\"name\": PREFECT_ECS_CONTAINER_NAME}\n            task_definition[\"containerDefinitions\"].append(container)\n\n        if self.image:\n            container[\"image\"] = self.image\n\n        # Remove any keys that have been explicitly \"unset\"\n        unset_keys = {key for key, value in self.env.items() if value is None}\n        for item in tuple(container.get(\"environment\", [])):\n            if item[\"name\"] in unset_keys:\n                container[\"environment\"].remove(item)\n\n        if self.configure_cloudwatch_logs:\n            container[\"logConfiguration\"] = {\n                \"logDriver\": \"awslogs\",\n                \"options\": {\n                    \"awslogs-create-group\": \"true\",\n                    \"awslogs-group\": \"prefect\",\n                    \"awslogs-region\": region,\n                    \"awslogs-stream-prefix\": self.name or \"prefect\",\n                    **self.cloudwatch_logs_options,\n                },\n            }\n\n        family = self.family or task_definition.get(\"family\") or ECS_DEFAULT_FAMILY\n        task_definition[\"family\"] = slugify(\n            family,\n            max_length=255,\n            regex_pattern=r\"[^a-zA-Z0-9-_]+\",\n        )\n\n        # CPU and memory are required in some cases, retrieve the value to use\n        cpu = self.cpu or task_definition.get(\"cpu\") or ECS_DEFAULT_CPU\n        memory = self.memory or task_definition.get(\"memory\") or ECS_DEFAULT_MEMORY\n\n        if self.launch_type == \"FARGATE\" or self.launch_type == \"FARGATE_SPOT\":\n            # Task level memory and cpu are required when using fargate\n            task_definition[\"cpu\"] = str(cpu)\n            task_definition[\"memory\"] = str(memory)\n\n            # The FARGATE compatibility is required if it will be used as as launch type\n            requires_compatibilities = task_definition.setdefault(\n                \"requiresCompatibilities\", []\n            )\n            if \"FARGATE\" not in requires_compatibilities:\n                task_definition[\"requiresCompatibilities\"].append(\"FARGATE\")\n\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            # However, we will not enforce that here if the user has set it\n            network_mode = task_definition.setdefault(\"networkMode\", \"awsvpc\")\n\n            if network_mode != \"awsvpc\":\n                warnings.warn(\n                    f\"Found network mode {network_mode!r} which is not compatible with \"\n                    f\"launch type {self.launch_type!r}. Use either the 'EC2' launch \"\n                    \"type or the 'awsvpc' network mode.\"\n                )\n\n        elif self.launch_type == \"EC2\":\n            # Container level memory and cpu are required when using ec2\n            container.setdefault(\"cpu\", int(cpu))\n            container.setdefault(\"memory\", int(memory))\n\n        if self.execution_role_arn and not self.task_definition_arn:\n            task_definition[\"executionRoleArn\"] = self.execution_role_arn\n\n        if self.configure_cloudwatch_logs and not task_definition.get(\n            \"executionRoleArn\"\n        ):\n            raise ValueError(\n                \"An execution role arn must be set on the task definition to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs` but no execution role \"\n                \"was found on the task definition.\"\n            )\n\n        return task_definition\n\n    def _prepare_task_run_overrides(self) -&gt; dict:\n        \"\"\"\n        Prepare the 'overrides' payload for a task run request.\n        \"\"\"\n        overrides = {\n            \"containerOverrides\": [\n                {\n                    \"name\": PREFECT_ECS_CONTAINER_NAME,\n                    \"environment\": [\n                        {\"name\": key, \"value\": value}\n                        for key, value in {\n                            **self._base_environment(),\n                            **self.env,\n                        }.items()\n                        if value is not None\n                    ],\n                }\n            ],\n        }\n\n        prefect_container_overrides = overrides[\"containerOverrides\"][0]\n\n        if self.command:\n            prefect_container_overrides[\"command\"] = self.command\n\n        if self.execution_role_arn:\n            overrides[\"executionRoleArn\"] = self.execution_role_arn\n\n        if self.task_role_arn:\n            overrides[\"taskRoleArn\"] = self.task_role_arn\n\n        if self.memory:\n            overrides[\"memory\"] = str(self.memory)\n            prefect_container_overrides.setdefault(\"memory\", self.memory)\n\n        if self.cpu:\n            overrides[\"cpu\"] = str(self.cpu)\n            prefect_container_overrides.setdefault(\"cpu\", self.cpu)\n\n        return overrides\n\n    def _load_vpc_network_config(\n        self, vpc_id: Optional[str], boto_session: boto3.Session\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = boto_session.client(\"ec2\")\n        vpc_message = \"the default VPC\" if not vpc_id else f\"VPC with ID {vpc_id}\"\n\n        if not vpc_id:\n            # Retrieve the default VPC\n            describe = {\"Filters\": [{\"Name\": \"isDefault\", \"Values\": [\"true\"]}]}\n        else:\n            describe = {\"VpcIds\": [vpc_id]}\n\n        vpcs = ec2_client.describe_vpcs(**describe)[\"Vpcs\"]\n        if not vpcs:\n            help_message = (\n                \"Pass an explicit `vpc_id` or configure a default VPC.\"\n                if not vpc_id\n                else \"Check that the VPC exists in the current region.\"\n            )\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                \"Network configuration cannot be inferred. \" + help_message\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                \"Network configuration cannot be inferred.\"\n            )\n\n        return {\n            \"awsvpcConfiguration\": {\n                \"subnets\": [s[\"SubnetId\"] for s in subnets],\n                \"assignPublicIp\": \"ENABLED\",\n                \"securityGroups\": [],\n            }\n        }\n\n    def _prepare_task_run(\n        self,\n        network_config: Optional[dict],\n        task_definition_arn: str,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task run request payload.\n        \"\"\"\n        task_run = {\n            \"overrides\": self._prepare_task_run_overrides(),\n            \"tags\": [\n                {\n                    \"key\": slugify(\n                        key,\n                        regex_pattern=_TAG_REGEX,\n                        allow_unicode=True,\n                        lowercase=False,\n                    ),\n                    \"value\": slugify(\n                        value,\n                        regex_pattern=_TAG_REGEX,\n                        allow_unicode=True,\n                        lowercase=False,\n                    ),\n                }\n                for key, value in self.labels.items()\n            ],\n            \"taskDefinition\": task_definition_arn,\n        }\n\n        if self.cluster:\n            task_run[\"cluster\"] = self.cluster\n\n        if self.launch_type:\n            if self.launch_type == \"FARGATE_SPOT\":\n                task_run[\"capacityProviderStrategy\"] = [\n                    {\"capacityProvider\": \"FARGATE_SPOT\", \"weight\": 1}\n                ]\n            else:\n                task_run[\"launchType\"] = self.launch_type\n\n        if network_config:\n            task_run[\"networkConfiguration\"] = network_config\n\n        task_run = self.task_customizations.apply(task_run)\n        return task_run\n\n    def _run_task(self, ecs_client: _ECSClient, task_run: dict):\n        \"\"\"\n        Run the task using the ECS client.\n\n        This is isolated as a separate method for testing purposes.\n        \"\"\"\n        return ecs_client.run_task(**task_run)[\"tasks\"][0]\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'JsonPatch' type\n    arbitrary_types_allowed = True\n    json_encoders = {JsonPatch: lambda p: p.patch}\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.cast_customizations_to_a_json_patch","title":"<code>cast_customizations_to_a_json_patch</code>","text":"<p>Casts lists to JsonPatch instances.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@validator(\"task_customizations\", pre=True)\ndef cast_customizations_to_a_json_patch(\n    cls, value: Union[List[Dict], JsonPatch, str]\n) -&gt; JsonPatch:\n    \"\"\"\n    Casts lists to JsonPatch instances.\n    \"\"\"\n    if isinstance(value, str):\n        value = json.loads(value)\n    if isinstance(value, list):\n        return JsonPatch(value)\n    return value  # type: ignore\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.cloudwatch_logs_options_requires_configure_cloudwatch_logs","title":"<code>cloudwatch_logs_options_requires_configure_cloudwatch_logs</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator\ndef cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if values.get(\"cloudwatch_logs_options\") and not values.get(\n        \"configure_cloudwatch_logs\"\n    ):\n        raise ValueError(\n            \"`configure_cloudwatch_log` must be enabled to use \"\n            \"`cloudwatch_logs_options`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.configure_cloudwatch_logs_requires_execution_role_arn","title":"<code>configure_cloudwatch_logs_requires_execution_role_arn</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator\ndef configure_cloudwatch_logs_requires_execution_role_arn(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if (\n        values.get(\"configure_cloudwatch_logs\")\n        and not values.get(\"execution_role_arn\")\n        # Do not raise if they've linked to another task definition or provided\n        # it without using our shortcuts\n        and not values.get(\"task_definition_arn\")\n        and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n    ):\n        raise ValueError(\n            \"An `execution_role_arn` must be provided to use \"\n            \"`configure_cloudwatch_logs` or `stream_logs`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'JsonPatch' type\n    d = super().dict(*args, **kwargs)\n    d[\"task_customizations\"] = self.task_customizations.patch\n    return d\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a cloud-run work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for a cloud-run work pool</li> </ul> Source code in <code>prefect_aws/ecs.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a cloud-run work pool with the same\n    configuration as this block.\n\n    Returns:\n        - dict: a base job template for a cloud-run work pool\n    \"\"\"\n    base_job_template = copy.deepcopy(ECSWorker.get_default_base_job_template())\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n            \"task_customizations\",\n        ]:\n            continue\n        elif key == \"aws_credentials\":\n            if not self.aws_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"aws_credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.aws_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"task_definition\":\n            base_job_template[\"job_configuration\"][\"task_definition\"] = value\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                \" Skipping.\"\n            )\n\n    if self.task_customizations:\n        network_config_patches = JsonPatch(\n            [\n                patch\n                for patch in self.task_customizations\n                if \"networkConfiguration\" in patch[\"path\"]\n            ]\n        )\n        minimal_network_config = assemble_document_for_patches(\n            network_config_patches\n        )\n        if minimal_network_config:\n            minimal_network_config_with_patches = network_config_patches.apply(\n                minimal_network_config\n            )\n            base_job_template[\"variables\"][\"properties\"][\"network_configuration\"][\n                \"default\"\n            ] = minimal_network_config_with_patches[\"networkConfiguration\"][\n                \"awsvpcConfiguration\"\n            ]\n        try:\n            base_job_template[\"job_configuration\"][\n                \"task_run_request\"\n            ] = self.task_customizations.apply(\n                base_job_template[\"job_configuration\"][\"task_run_request\"]\n            )\n        except JsonPointerException:\n            self.logger.warning(\n                \"Unable to apply task customizations to the base job template.\"\n                \"You may need to update the template manually.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>  <code>staticmethod</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@staticmethod\ndef get_corresponding_worker_type() -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return ECSWorker.type\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.image_is_required","title":"<code>image_is_required</code>","text":"<p>Enforces that an image is available if image is <code>None</code>.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator(pre=True)\ndef image_is_required(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Enforces that an image is available if image is `None`.\n    \"\"\"\n    has_image = bool(values.get(\"image\"))\n    has_task_definition_arn = bool(values.get(\"task_definition_arn\"))\n\n    # The image can only be null when the task_definition_arn is set\n    if has_image or has_task_definition_arn:\n        return values\n\n    prefect_container = (\n        get_prefect_container(\n            (values.get(\"task_definition\") or {}).get(\"containerDefinitions\", [])\n        )\n        or {}\n    )\n    image_in_task_definition = prefect_container.get(\"image\")\n\n    # If a task_definition is given with a prefect container image, use that value\n    if image_in_task_definition:\n        values[\"image\"] = image_in_task_definition\n    # Otherwise, it should default to the Prefect base image\n    else:\n        values[\"image\"] = get_prefect_image_name()\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a task running on ECS.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>A cluster and task arn combination. This should match a value yielded by <code>ECSTask.run</code>.</p> required Source code in <code>prefect_aws/ecs.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a task running on ECS.\n\n    Args:\n        identifier: A cluster and task arn combination. This should match a value\n            yielded by `ECSTask.run`.\n    \"\"\"\n    if grace_seconds != 30:\n        self.logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n            \"support dynamic grace period configuration so 30s will be used. \"\n            \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n        )\n    cluster, task = parse_task_identifier(identifier)\n    await run_sync_in_worker_thread(self._stop_task, cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Return an copy of the block that is prepared to execute a flow run.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def prepare_for_flow_run(\n    self: Self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"Deployment\"] = None,\n    flow: Optional[\"Flow\"] = None,\n) -&gt; Self:\n    \"\"\"\n    Return an copy of the block that is prepared to execute a flow run.\n    \"\"\"\n    new_family = None\n\n    # Update the family if not specified elsewhere\n    if (\n        not self.family\n        and not self.task_definition_arn\n        and not (self.task_definition and self.task_definition.get(\"family\"))\n    ):\n        if flow and deployment:\n            new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}__{deployment.name}\"\n        elif flow and not deployment:\n            new_family = f\"{ECS_DEFAULT_FAMILY}__{flow.name}\"\n        elif deployment and not flow:\n            # This is a weird case and should not be see in the wild\n            new_family = f\"{ECS_DEFAULT_FAMILY}__unknown-flow__{deployment.name}\"\n\n    new = super().prepare_for_flow_run(flow_run, deployment=deployment, flow=flow)\n\n    if new_family:\n        return new.copy(update={\"family\": new_family})\n    else:\n        # Avoid an extra copy if not needed\n        return new\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the task definition and task run that will be sent to AWS.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"\n    Generate a preview of the task definition and task run that will be sent to AWS.\n    \"\"\"\n    preview = \"\"\n\n    task_definition_arn = self.task_definition_arn or \"&lt;registered at runtime&gt;\"\n\n    if self.task_definition or not self.task_definition_arn:\n        task_definition = self._prepare_task_definition(\n            self.task_definition or {},\n            region=self.aws_credentials.region_name\n            or \"&lt;loaded from client at runtime&gt;\",\n        )\n        preview += \"---\\n# Task definition\\n\"\n        preview += yaml.dump(task_definition)\n        preview += \"\\n\"\n    else:\n        task_definition = None\n\n    if task_definition and task_definition.get(\"networkMode\") == \"awsvpc\":\n        vpc = \"the default VPC\" if not self.vpc_id else self.vpc_id\n        network_config = {\n            \"awsvpcConfiguration\": {\n                \"subnets\": f\"&lt;loaded from {vpc} at runtime&gt;\",\n                \"assignPublicIp\": \"ENABLED\",\n            }\n        }\n    else:\n        network_config = None\n\n    task_run = self._prepare_task_run(network_config, task_definition_arn)\n    preview += \"---\\n# Task run request\\n\"\n    preview += yaml.dump(task_run)\n\n    return preview\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured task on ECS.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@sync_compatible\nasync def run(self, task_status: Optional[TaskStatus] = None) -&gt; ECSTaskResult:\n    \"\"\"\n    Run the configured task on ECS.\n    \"\"\"\n    boto_session, ecs_client = await run_sync_in_worker_thread(\n        self._get_session_and_client\n    )\n\n    (\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition,\n    ) = await run_sync_in_worker_thread(\n        self._create_task_and_wait_for_start, boto_session, ecs_client\n    )\n\n    # Display a nice message indicating the command and image\n    command = self.command or get_prefect_container(\n        task_definition[\"containerDefinitions\"]\n    ).get(\"command\", [])\n    self.logger.info(\n        f\"{self._log_prefix}: Running command {' '.join(command)!r} \"\n        f\"in container {PREFECT_ECS_CONTAINER_NAME!r} ({self.image})...\"\n    )\n\n    # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n    # if set to preserve matching by name rather than arn\n    # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n    # single colons.\n    identifier = (self.cluster if self.cluster else cluster_arn) + \"::\" + task_arn\n\n    if task_status:\n        task_status.started(identifier)\n\n    status_code = await run_sync_in_worker_thread(\n        self._watch_task_and_get_exit_code,\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition and self.auto_deregister_task_definition,\n        boto_session,\n        ecs_client,\n    )\n\n    return ECSTaskResult(\n        identifier=identifier,\n        # If the container does not start the exit code can be null but we must\n        # still report a status code. We use a -1 to indicate a special code.\n        status_code=status_code if status_code is not None else -1,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTask.set_default_configure_cloudwatch_logs","title":"<code>set_default_configure_cloudwatch_logs</code>","text":"<p>Streaming output generally requires CloudWatch logs to be configured.</p> <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code> defaults to matching the value of <code>stream_output</code>.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>@root_validator(pre=True)\ndef set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Streaming output generally requires CloudWatch logs to be configured.\n\n    To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n    defaults to matching the value of `stream_output`.\n    \"\"\"\n    configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n    if configure_cloudwatch_logs is None:\n        values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.ECSTaskResult","title":"<code>ECSTaskResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>The result of a run of an ECS task</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>class ECSTaskResult(InfrastructureResult):\n    \"\"\"The result of a run of an ECS task\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.get_container","title":"<code>get_container</code>","text":"<p>Extract a container from a list of containers or container definitions. If not found, <code>None</code> is returned.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def get_container(containers: List[dict], name: str) -&gt; Optional[dict]:\n    \"\"\"\n    Extract a container from a list of containers or container definitions.\n    If not found, `None` is returned.\n    \"\"\"\n    for container in containers:\n        if container.get(\"name\") == name:\n            return container\n    return None\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.get_prefect_container","title":"<code>get_prefect_container</code>","text":"<p>Extract the Prefect container from a list of containers or container definitions. If not found, <code>None</code> is returned.</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def get_prefect_container(containers: List[dict]) -&gt; Optional[dict]:\n    \"\"\"\n    Extract the Prefect container from a list of containers or container definitions.\n    If not found, `None` is returned.\n    \"\"\"\n    return get_container(containers, PREFECT_ECS_CONTAINER_NAME)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs/#prefect_aws.ecs.parse_task_identifier","title":"<code>parse_task_identifier</code>","text":"<p>Splits identifier into its cluster and task components, e.g. input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").</p> Source code in <code>prefect_aws/ecs.py</code> <pre><code>def parse_task_identifier(identifier: str) -&gt; Tuple[str, str]:\n    \"\"\"\n    Splits identifier into its cluster and task components, e.g.\n    input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").\n    \"\"\"\n    cluster, task = identifier.split(\"::\", maxsplit=1)\n    return cluster, task\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/","title":"ECS Worker Guide","text":""},{"location":"integrations/prefect-aws/ecs_guide/#why-use-ecs-for-flow-run-execution","title":"Why use ECS for flow run execution?","text":"<p>ECS (Elastic Container Service) tasks are a good option for executing Prefect flow runs for several reasons:</p> <ol> <li>Scalability: ECS scales your infrastructure in response to demand, effectively managing Prefect flow runs. ECS automatically administers container distribution across multiple instances based on demand.</li> <li>Flexibility: ECS lets you choose between AWS Fargate and Amazon EC2 for container operation. Fargate abstracts the underlying infrastructure, while EC2 has faster job start times and offers additional control over instance management and configuration.</li> <li>AWS Integration: Easily connect with other AWS services, such as AWS IAM and CloudWatch.</li> <li>Containerization: ECS supports Docker containers and offers managed execution. Containerization encourages reproducible deployments.</li> </ol>"},{"location":"integrations/prefect-aws/ecs_guide/#ecs-flow-run-execution","title":"ECS flow run execution","text":"<p>Prefect enables remote flow execution via workers and work pools. To learn more about these concepts please see our deployment tutorial.</p> <p>For details on how workers and work pools are implemented for ECS, see the diagram below.</p> <pre><code>%%{\n  init: {\n    'theme': 'base',\n    'themeVariables': {\n      'primaryColor': '#2D6DF6',\n      'primaryTextColor': '#fff',\n      'lineColor': '#FE5A14',\n      'secondaryColor': '#E04BF0',\n      'tertiaryColor': '#fff'\n    }\n  }\n}%%\ngraph TB\n\n  subgraph ecs_cluster[ECS cluster]\n    subgraph ecs_service[ECS service]\n      td_worker[Worker task definition] --&gt; |defines| prefect_worker((Prefect worker))\n    end\n    prefect_worker --&gt;|kicks off| ecs_task\n    fr_task_definition[Flow run task definition]\n\n\n    subgraph ecs_task[\"ECS task execution\"]\n    style ecs_task text-align:center,display:flex\n\n\n    flow_run((Flow run))\n\n    end\n    fr_task_definition --&gt;|defines| ecs_task\n  end\n\n  subgraph prefect_cloud[Prefect Cloud]\n    subgraph prefect_workpool[ECS work pool]\n      workqueue[Work queue]\n    end\n  end\n\n  subgraph github[\"ECR\"]\n    flow_code{{\"Flow code\"}}\n  end\n  flow_code --&gt; |pulls| ecs_task\n  prefect_worker --&gt;|polls| workqueue\n  prefect_workpool --&gt;|configures| fr_task_definition</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#ecs-and-prefect","title":"ECS and Prefect","text":"<p>ECS tasks != Prefect tasks</p> <p>An ECS task is not the same thing as a Prefect task.</p> <p>ECS tasks are groupings of containers that run within an ECS Cluster. An ECS task's behavior is determined by its task definition. </p> <p>An ECS task definition is the blueprint for the ECS task. It describes which Docker containers to run and what you want to have happen inside these containers.</p> <p>ECS tasks are instances of a task definition. A Task Execution launches container(s) as defined in the task definition until they are stopped or exit on their own. This setup is ideal for ephemeral processes such as a Prefect flow run.</p> <p>The ECS task running the Prefect worker should be an ECS Service, given its long-running nature and need for auto-recovery in case of failure. An ECS service automatically replaces any task that fails, which is ideal for managing a long-running process such as a Prefect worker.</p> <p>When a Prefect flow is scheduled to run it goes into the work pool specified in the flow's deployment. Work pools are typed according to the infrastructure the flow will run on. Flow runs scheduled in an <code>ecs</code> typed work pool are executed as ECS tasks. Only Prefect ECS workers can poll an <code>ecs</code> typed work pool.</p> <p>When the ECS worker receives a scheduled flow run from the ECS work pool it is polling, it spins up the specified infrastructure on AWS ECS. The worker knows to build an ECS task definition for each flow run based on the configuration specified in the work pool.</p> <p>Once the flow run completes, the ECS containers of the cluster are spun down to a single container that continues to run the Prefect worker. This worker continues polling for work from the Prefect work pool.</p> <p>If you specify a task definition ARN (Amazon Resource Name) in the work pool, the worker will use that ARN when spinning up the ECS Task, rather than creating a task definition from the fields supplied in the work pool configuration.</p> <p>You can use either EC2 or Fargate as the capacity provider. Fargate simplifies initiation, but lengthens infrastructure setup time for each flow run. Using EC2 for the ECS cluster can reduce setup time. In this example, we will show how to use Fargate.</p> <p>Tip</p> <p>If you prefer infrastructure as code check out this Terraform module to provision an ECS cluster with a worker.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#prerequisites","title":"Prerequisites","text":"<ul> <li>An AWS account with permissions to create ECS services and IAM roles.</li> <li>The AWS CLI installed on your local machine. You can download it from the AWS website.</li> <li>An ECS Cluster to host both the worker and the flow runs it submits. This guide uses the default cluster. To create your own follow this guide.</li> <li>A VPC configured for your ECS tasks. This guide uses the default VPC.</li> <li>Prefect Cloud account or Prefect self-managed instance.</li> </ul>"},{"location":"integrations/prefect-aws/ecs_guide/#step-1-set-up-an-ecs-work-pool","title":"Step 1: Set up an ECS work pool","text":"<p>Before setting up the worker, create a work pool of type ECS for the worker to pull work from. If doing so from the CLI, be sure to authenticate with Prefect Cloud.</p> <p>Create a work pool from the CLI:</p> <pre><code>prefect work-pool create --type ecs my-ecs-pool\n</code></pre> <p>Or from the Prefect UI: </p> <p>!!!     Because this guide uses Fargate as the capacity provider and the default VPC and ECS cluster, no further configuration is needed.</p> <p>Next, set up a Prefect ECS worker that will discover and pull work from this work pool.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-2-start-a-prefect-worker-in-your-ecs-cluster","title":"Step 2: Start a Prefect worker in your ECS cluster","text":"<p>First start by creating the IAM role required in order for your worker and flows to run. The sample flow in this guide doesn't interact with many other AWS services, so you will only be creating one role, <code>taskExecutionRole</code>.  To create an IAM role for the ECS task using the AWS CLI, follow these steps:</p>"},{"location":"integrations/prefect-aws/ecs_guide/#1-create-a-trust-policy","title":"1. Create a trust policy","text":"<p>The trust policy will specify that the ECS service containing the Prefect worker will be able to assume the role required for calling other AWS services.</p> <p>Save this policy to a file, such as <code>ecs-trust-policy.json</code>:</p> <pre><code>{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Principal\": {\n                \"Service\": \"ecs-tasks.amazonaws.com\"\n            },\n            \"Action\": \"sts:AssumeRole\"\n        }\n    ]\n}\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#2-create-the-iam-roles","title":"2. Create the IAM roles","text":"<p>Use the <code>aws iam create-role</code> command to create the roles that you will be using. For this guide, the <code>ecsTaskExecutionRole</code> will be used by the worker to start ECS tasks, and will also be the role assigned to the ECS tasks running your Prefect flows.</p> <pre><code>    aws iam create-role \\\n    --role-name ecsTaskExecutionRole \\\n    --assume-role-policy-document file://ecs-trust-policy.json\n</code></pre> <p>Tip</p> <p>Depending on the requirements of your flows, it is advised to create a second role for your ECS tasks. This role will contain the permissions required by the ECS tasks in which your flows will run. For example, if your workflow loads data into an S3 bucket, you would need a role with additional permissions to access S3.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#3-attach-the-policy-to-the-role","title":"3. Attach the policy to the role","text":"<p>For this guide the ECS worker will require permissions to pull images from ECR and publish logs to CloudWatch. Amazon has a managed policy named <code>AmazonECSTaskExecutionRolePolicy</code> that grants the permissions necessary for starting ECS tasks. See here for other common execution role permissions. Attach this policy to your task execution role:</p> <pre><code>    aws iam attach-role-policy \\\n    --role-name ecsTaskExecutionRole \\\n    --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy\n</code></pre> <p>Remember to replace the <code>--role-name</code> and <code>--policy-arn</code> with the actual role name and policy Amazon Resource Name (ARN) you want to use.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-3-creating-an-ecs-worker-service","title":"Step 3: Creating an ECS worker service","text":""},{"location":"integrations/prefect-aws/ecs_guide/#1-launch-an-ecs-service-to-host-the-worker","title":"1. Launch an ECS Service to host the worker","text":"<p>Next, create an ECS task definition that specifies the Docker image for the Prefect worker, the resources it requires, and the command it should run. In this example, the command to start the worker is <code>prefect worker start --pool my-ecs-pool</code>.</p> <p>Create a JSON file with the following contents:</p> <pre><code>{\n    \"family\": \"prefect-worker-task\",\n    \"networkMode\": \"awsvpc\",\n    \"requiresCompatibilities\": [\n        \"FARGATE\"\n    ],\n    \"cpu\": \"512\",\n    \"memory\": \"1024\",\n    \"executionRoleArn\": \"&lt;ecs-task-role-arn&gt;\",\n    \"taskRoleArn\": \"&lt;ecs-task-role-arn&gt;\",\n    \"containerDefinitions\": [\n        {\n            \"name\": \"prefect-worker\",\n            \"image\": \"prefecthq/prefect:2-latest\",\n            \"cpu\": 512,\n            \"memory\": 1024,\n            \"essential\": true,\n            \"command\": [\n                \"/bin/sh\",\n                \"-c\",\n                \"pip install prefect-aws &amp;&amp; prefect worker start --pool my-ecs-pool --type ecs\"\n            ],\n            \"environment\": [\n                {\n                    \"name\": \"PREFECT_API_URL\",\n                    \"value\": \"prefect-api-url&gt;\"\n                },\n                {\n                    \"name\": \"PREFECT_API_KEY\",\n                    \"value\": \"&lt;prefect-api-key&gt;\"\n                }\n            ]\n        }\n    ]\n}\n</code></pre> <ul> <li> <p>Use <code>prefect config view</code> to view the <code>PREFECT_API_URL</code> for your current Prefect profile. Use this to replace <code>&lt;prefect-api-url&gt;</code>.</p> </li> <li> <p>For the <code>PREFECT_API_KEY</code>, if you are on a paid plan you can create a service account for the worker. If your are on a free plan, you can pass a user\u2019s API key.</p> </li> <li> <p>Replace both instances of <code>&lt;ecs-task-role-arn&gt;</code> with the ARN of the IAM role you created in Step 2. You can grab this by running: <pre><code>aws iam get-role --role-name taskExecutionRole --query 'Role.[RoleName, Arn]' --output text\n</code></pre></p> </li> <li> <p>Notice that the CPU and Memory allocations are relatively small. The worker's main responsibility is to submit work through API calls to AWS, not to execute your Prefect flow code.</p> </li> </ul> <p>Tip</p> <p>To avoid hardcoding your API key into the task definition JSON see how to add sensitive data using AWS secrets manager to the container definition.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#2-register-the-task-definition","title":"2. Register the task definition","text":"<p>Before creating a service, you first need to register a task definition. You can do that using the <code>register-task-definition</code> command in the AWS CLI. Here is an example:</p> <pre><code>aws ecs register-task-definition --cli-input-json file://task-definition.json\n</code></pre> <p>Replace <code>task-definition.json</code> with the name of your JSON file.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#3-create-an-ecs-service-to-host-your-worker","title":"3. Create an ECS service to host your worker","text":"<p>Finally, create a service that will manage your Prefect worker:</p> <p>Open a terminal window and run the following command to create an ECS Fargate service:</p> <pre><code>aws ecs create-service \\\n    --service-name prefect-worker-service \\\n    --cluster &lt;ecs-cluster&gt; \\\n    --task-definition &lt;task-definition-arn&gt; \\\n    --launch-type FARGATE \\\n    --desired-count 1 \\\n    --network-configuration \"awsvpcConfiguration={subnets=[&lt;subnet-ids&gt;],securityGroups=[&lt;security-group-ids&gt;],assignPublicIp='ENABLED'}\"\n</code></pre> <ul> <li>Replace <code>&lt;ecs-cluster&gt;</code> with the name of your ECS cluster.</li> <li>Replace <code>&lt;task-definition-arn&gt;</code> with the ARN of the task definition you just registered.</li> <li>Replace <code>&lt;subnet-ids&gt;</code> with a comma-separated list of your VPC subnet IDs. Ensure that these subnets are aligned with the vpc specified on the work pool in step 1. You can view subnet ids with the following command:     <code>aws ec2 describe-subnets --filter Name=&lt;vpc-id&gt;</code></li> <li>Replace <code>&lt;security-group-ids&gt;</code> with a comma-separated list of your VPC security group IDs.</li> </ul> <p>Sanity check</p> <p>The work pool page in the Prefect UI allows you to check the health of your workers - make sure your new worker is live! Note that it can take a few minutes for an ECS service to come online. If your worker does not come online and you are using the command from this guide, you may not be using the default VPC. For connectivity issues, check your VPC's configuration and refer to the ECS outbound networking guide.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#step-4-pick-up-a-flow-run-with-your-new-worker","title":"Step 4: Pick up a flow run with your new worker","text":"<p>This guide uses ECR to store a Docker image containing your flow code. To do this, we will write a flow, then deploy it using build and push steps that copy flow code into a Docker image and push that image to an ECR repository.</p>"},{"location":"integrations/prefect-aws/ecs_guide/#1-write-a-simple-test-flow","title":"1. Write a simple test flow","text":"<p><code>my_flow.py</code></p> <pre><code>from prefect import flow, get_run_logger\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"Hello from ECS!!\")\n\nif __name__ == \"__main__\":\n    my_flow()\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#2-create-an-ecr-repository","title":"2. Create an ECR repository","text":"<p>Use the following AWS CLI command to create an ECR repository. The name you choose for your repository will be reused in the next step when defining your Prefect deployment.</p> <pre><code>aws ecr create-repository \\\n--repository-name &lt;my-ecr-repo&gt; \\\n--region &lt;region&gt;\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#3-create-a-prefectyaml-file","title":"3. Create a <code>prefect.yaml</code> file","text":"<p>To have Prefect build your image when deploying your flow create a <code>prefect.yaml</code> file with the following specification:</p> <pre><code>name: ecs-worker-guide\n# this is pre-populated by running prefect init\nprefect-version: 2.14.20 \n\n# build section allows you to manage and build docker images\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build_image\n    requires: prefect-docker&gt;=0.3.1\n    image_name: &lt;my-ecr-repo&gt;\n    tag: latest\n    dockerfile: auto\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.3.1\n    image_name: '{{ build_image.image_name }}'\n    tag: '{{ build_image.tag }}'\n\n # the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: my_ecs_deployment\n    version:\n    tags: []\n    description:\n    entrypoint: flow.py:my_flow\n    parameters: {}\n    work_pool:\n        name: ecs-dev-pool\n        work_queue_name:\n        job_variables:\n        image: '{{ build_image.image }}'\n    schedules: []\npull:\n    - prefect.deployments.steps.set_working_directory:\n        directory: /opt/prefect/ecs-worker-guide\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#4-deploy-the-flow-to-the-prefect-cloud-or-your-self-managed-server-instance-specifying-the-ecs-work-pool-when-prompted","title":"4. Deploy the flow to the Prefect Cloud or your self-managed server instance, specifying the ECS work pool when prompted","text":"<pre><code>prefect deploy my_flow.py:my_ecs_deployment\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_guide/#5-find-the-deployment-in-the-ui-and-click-the-quick-run-button","title":"5. Find the deployment in the UI and click the Quick Run button!","text":""},{"location":"integrations/prefect-aws/ecs_guide/#optional-next-steps","title":"Optional next steps","text":"<ol> <li> <p>Now that you are confident your ECS worker is healthy, you can experiment with different work pool configurations.</p> <ul> <li>Do your flow runs require higher <code>CPU</code>?</li> <li>Would an EC2 <code>Launch Type</code> speed up your flow run execution?</li> </ul> <p>These infrastructure configuration values can be set on your ECS work pool or they can be overridden on the deployment level through job_variables if desired.</p> </li> </ol>"},{"location":"integrations/prefect-aws/ecs_worker/","title":"ECS Worker","text":""},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker","title":"<code>prefect_aws.workers.ecs_worker</code>","text":"<p>Prefect worker for executing flow runs as ECS tasks.</p> <p>Get started by creating a work pool:</p> <pre><code>$ prefect work-pool create --type ecs my-ecs-pool\n</code></pre> <p>Then, you can start a worker for the pool:</p> <pre><code>$ prefect worker start --pool my-ecs-pool\n</code></pre> <p>It's common to deploy the worker as an ECS task as well. However, you can run the worker locally to get started.</p> <p>The worker may work without any additional configuration, but it is dependent on your specific AWS setup and we'd recommend opening the work pool editor in the UI to see the available options.</p> <p>By default, the worker will register a task definition for each flow run and run a task in your default ECS cluster using AWS Fargate. Fargate requires tasks to configure subnets, which we will infer from your default VPC. If you do not have a default VPC, you must provide a VPC ID or manually setup the network configuration for your tasks.</p> <p>Note, the worker caches task definitions for each deployment to avoid excessive registration. The worker will check that the cached task definition is compatible with your configuration before using it.</p> <p>The launch type option can be used to run your tasks in different modes. For example, <code>FARGATE_SPOT</code> can be used to use spot instances for your Fargate tasks or <code>EC2</code> can be used to run your tasks on a cluster backed by EC2 instances.</p> <p>Generally, it is very useful to enable CloudWatch logging for your ECS tasks; this can help you debug task failures. To enable CloudWatch logging, you must provide an execution role ARN with permissions to create and write to log streams. See the <code>configure_cloudwatch_logs</code> field documentation for details.</p> <p>The worker can be configured to use an existing task definition by setting the task definition arn variable or by providing a \"taskDefinition\" in the task run request. When a task definition is provided, the worker will never create a new task definition which may result in variables that are templated into the task definition payload being ignored.</p>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.CapacityProvider","title":"<code>CapacityProvider</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>The capacity provider strategy to use when running the task.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class CapacityProvider(BaseModel):\n    \"\"\"\n    The capacity provider strategy to use when running the task.\n    \"\"\"\n\n    capacityProvider: str\n    weight: int\n    base: int\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSIdentifier","title":"<code>ECSIdentifier</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>The identifier for a running ECS task.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSIdentifier(NamedTuple):\n    \"\"\"\n    The identifier for a running ECS task.\n    \"\"\"\n\n    cluster: str\n    task_arn: str\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration","title":"<code>ECSJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Job configuration for an ECS worker.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Job configuration for an ECS worker.\n    \"\"\"\n\n    aws_credentials: Optional[AwsCredentials] = Field(default_factory=AwsCredentials)\n    task_definition: Optional[Dict[str, Any]] = Field(\n        template=_default_task_definition_template()\n    )\n    task_run_request: Dict[str, Any] = Field(\n        template=_default_task_run_request_template()\n    )\n    configure_cloudwatch_logs: Optional[bool] = Field(default=None)\n    cloudwatch_logs_options: Dict[str, str] = Field(default_factory=dict)\n    cloudwatch_logs_prefix: Optional[str] = Field(default=None)\n    network_configuration: Dict[str, Any] = Field(default_factory=dict)\n    stream_output: Optional[bool] = Field(default=None)\n    task_start_timeout_seconds: int = Field(default=300)\n    task_watch_poll_interval: float = Field(default=5.0)\n    auto_deregister_task_definition: bool = Field(default=False)\n    vpc_id: Optional[str] = Field(default=None)\n    container_name: Optional[str] = Field(default=None)\n    cluster: Optional[str] = Field(default=None)\n    match_latest_revision_in_family: bool = Field(default=False)\n\n    @root_validator\n    def task_run_request_requires_arn_if_no_task_definition_given(cls, values) -&gt; dict:\n        \"\"\"\n        If no task definition is provided, a task definition ARN must be present on the\n        task run request.\n        \"\"\"\n        if not values.get(\"task_run_request\", {}).get(\n            \"taskDefinition\"\n        ) and not values.get(\"task_definition\"):\n            raise ValueError(\n                \"A task definition must be provided if a task definition ARN is not \"\n                \"present on the task run request.\"\n            )\n        return values\n\n    @root_validator\n    def container_name_default_from_task_definition(cls, values) -&gt; dict:\n        \"\"\"\n        Infers the container name from the task definition if not provided.\n        \"\"\"\n        if values.get(\"container_name\") is None:\n            values[\"container_name\"] = _container_name_from_task_definition(\n                values.get(\"task_definition\")\n            )\n\n            # We may not have a name here still; for example if someone is using a task\n            # definition arn. In that case, we'll perform similar logic later to find\n            # the name to treat as the \"orchestration\" container.\n\n        return values\n\n    @root_validator(pre=True)\n    def set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Streaming output generally requires CloudWatch logs to be configured.\n\n        To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n        defaults to matching the value of `stream_output`.\n        \"\"\"\n        configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n        if configure_cloudwatch_logs is None:\n            values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n        return values\n\n    @root_validator\n    def configure_cloudwatch_logs_requires_execution_role_arn(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if (\n            values.get(\"configure_cloudwatch_logs\")\n            and not values.get(\"execution_role_arn\")\n            # TODO: Does not match\n            # Do not raise if they've linked to another task definition or provided\n            # it without using our shortcuts\n            and not values.get(\"task_run_request\", {}).get(\"taskDefinition\")\n            and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n        ):\n            raise ValueError(\n                \"An `execution_role_arn` must be provided to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs`.\"\n            )\n        return values\n\n    @root_validator\n    def cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n        cls, values: dict\n    ) -&gt; dict:\n        \"\"\"\n        Enforces that an execution role arn is provided (or could be provided by a\n        runtime task definition) when configuring logging.\n        \"\"\"\n        if values.get(\"cloudwatch_logs_options\") and not values.get(\n            \"configure_cloudwatch_logs\"\n        ):\n            raise ValueError(\n                \"`configure_cloudwatch_log` must be enabled to use \"\n                \"`cloudwatch_logs_options`.\"\n            )\n        return values\n\n    @root_validator\n    def network_configuration_requires_vpc_id(cls, values: dict) -&gt; dict:\n        \"\"\"\n        Enforces a `vpc_id` is provided when custom network configuration mode is\n        enabled for network settings.\n        \"\"\"\n        if values.get(\"network_configuration\") and not values.get(\"vpc_id\"):\n            raise ValueError(\n                \"You must provide a `vpc_id` to enable custom `network_configuration`.\"\n            )\n        return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.cloudwatch_logs_options_requires_configure_cloudwatch_logs","title":"<code>cloudwatch_logs_options_requires_configure_cloudwatch_logs</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef cloudwatch_logs_options_requires_configure_cloudwatch_logs(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if values.get(\"cloudwatch_logs_options\") and not values.get(\n        \"configure_cloudwatch_logs\"\n    ):\n        raise ValueError(\n            \"`configure_cloudwatch_log` must be enabled to use \"\n            \"`cloudwatch_logs_options`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.configure_cloudwatch_logs_requires_execution_role_arn","title":"<code>configure_cloudwatch_logs_requires_execution_role_arn</code>","text":"<p>Enforces that an execution role arn is provided (or could be provided by a runtime task definition) when configuring logging.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef configure_cloudwatch_logs_requires_execution_role_arn(\n    cls, values: dict\n) -&gt; dict:\n    \"\"\"\n    Enforces that an execution role arn is provided (or could be provided by a\n    runtime task definition) when configuring logging.\n    \"\"\"\n    if (\n        values.get(\"configure_cloudwatch_logs\")\n        and not values.get(\"execution_role_arn\")\n        # TODO: Does not match\n        # Do not raise if they've linked to another task definition or provided\n        # it without using our shortcuts\n        and not values.get(\"task_run_request\", {}).get(\"taskDefinition\")\n        and not (values.get(\"task_definition\") or {}).get(\"executionRoleArn\")\n    ):\n        raise ValueError(\n            \"An `execution_role_arn` must be provided to use \"\n            \"`configure_cloudwatch_logs` or `stream_logs`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.container_name_default_from_task_definition","title":"<code>container_name_default_from_task_definition</code>","text":"<p>Infers the container name from the task definition if not provided.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef container_name_default_from_task_definition(cls, values) -&gt; dict:\n    \"\"\"\n    Infers the container name from the task definition if not provided.\n    \"\"\"\n    if values.get(\"container_name\") is None:\n        values[\"container_name\"] = _container_name_from_task_definition(\n            values.get(\"task_definition\")\n        )\n\n        # We may not have a name here still; for example if someone is using a task\n        # definition arn. In that case, we'll perform similar logic later to find\n        # the name to treat as the \"orchestration\" container.\n\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.network_configuration_requires_vpc_id","title":"<code>network_configuration_requires_vpc_id</code>","text":"<p>Enforces a <code>vpc_id</code> is provided when custom network configuration mode is enabled for network settings.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef network_configuration_requires_vpc_id(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Enforces a `vpc_id` is provided when custom network configuration mode is\n    enabled for network settings.\n    \"\"\"\n    if values.get(\"network_configuration\") and not values.get(\"vpc_id\"):\n        raise ValueError(\n            \"You must provide a `vpc_id` to enable custom `network_configuration`.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.set_default_configure_cloudwatch_logs","title":"<code>set_default_configure_cloudwatch_logs</code>","text":"<p>Streaming output generally requires CloudWatch logs to be configured.</p> <p>To avoid entangled arguments in the simple case, <code>configure_cloudwatch_logs</code> defaults to matching the value of <code>stream_output</code>.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator(pre=True)\ndef set_default_configure_cloudwatch_logs(cls, values: dict) -&gt; dict:\n    \"\"\"\n    Streaming output generally requires CloudWatch logs to be configured.\n\n    To avoid entangled arguments in the simple case, `configure_cloudwatch_logs`\n    defaults to matching the value of `stream_output`.\n    \"\"\"\n    configure_cloudwatch_logs = values.get(\"configure_cloudwatch_logs\")\n    if configure_cloudwatch_logs is None:\n        values[\"configure_cloudwatch_logs\"] = values.get(\"stream_output\")\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSJobConfiguration.task_run_request_requires_arn_if_no_task_definition_given","title":"<code>task_run_request_requires_arn_if_no_task_definition_given</code>","text":"<p>If no task definition is provided, a task definition ARN must be present on the task run request.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>@root_validator\ndef task_run_request_requires_arn_if_no_task_definition_given(cls, values) -&gt; dict:\n    \"\"\"\n    If no task definition is provided, a task definition ARN must be present on the\n    task run request.\n    \"\"\"\n    if not values.get(\"task_run_request\", {}).get(\n        \"taskDefinition\"\n    ) and not values.get(\"task_definition\"):\n        raise ValueError(\n            \"A task definition must be provided if a task definition ARN is not \"\n            \"present on the task run request.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSVariables","title":"<code>ECSVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Variables for templating an ECS job.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSVariables(BaseVariables):\n    \"\"\"\n    Variables for templating an ECS job.\n    \"\"\"\n\n    task_definition_arn: Optional[str] = Field(\n        default=None,\n        description=(\n            \"An identifier for an existing task definition to use. If set, options that\"\n            \" require changes to the task definition will be ignored. All contents of \"\n            \"the task definition in the job configuration will be ignored.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=(\n            \"The AWS credentials to use to connect to ECS. If not provided, credentials\"\n            \" will be inferred from the local environment following AWS's boto client's\"\n            \" rules.\"\n        ),\n    )\n    cluster: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The ECS cluster to run the task in. An ARN or name may be provided. If \"\n            \"not provided, the default cluster will be used.\"\n        ),\n    )\n    family: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A family for the task definition. If not provided, it will be inferred \"\n            \"from the task definition. If the task definition does not have a family, \"\n            \"the name will be generated. When flow and deployment metadata is \"\n            \"available, the generated name will include their names. Values for this \"\n            \"field will be slugified to match AWS character requirements.\"\n        ),\n    )\n    launch_type: Optional[\n        Literal[\"FARGATE\", \"EC2\", \"EXTERNAL\", \"FARGATE_SPOT\"]\n    ] = Field(\n        default=ECS_DEFAULT_LAUNCH_TYPE,\n        description=(\n            \"The type of ECS task run infrastructure that should be used. Note that\"\n            \" 'FARGATE_SPOT' is not a formal ECS launch type, but we will configure\"\n            \" the proper capacity provider strategy if set here.\"\n        ),\n    )\n    capacity_provider_strategy: Optional[List[CapacityProvider]] = Field(\n        default_factory=list,\n        description=(\n            \"The capacity provider strategy to use when running the task. \"\n            \"If a capacity provider strategy is specified, the selected launch\"\n            \" type will be ignored.\"\n        ),\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. If this value is \"\n            \"not null, it will override the value in the task definition. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    cpu: int = Field(\n        title=\"CPU\",\n        default=None,\n        description=(\n            \"The amount of CPU to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_CPU} will be used unless present on the task definition.\"\n        ),\n    )\n    memory: int = Field(\n        default=None,\n        description=(\n            \"The amount of memory to provide to the ECS task. Valid amounts are \"\n            \"specified in the AWS documentation. If not provided, a default value of \"\n            f\"{ECS_DEFAULT_MEMORY} will be used unless present on the task definition.\"\n        ),\n    )\n    container_name: str = Field(\n        default=None,\n        description=(\n            \"The name of the container flow run orchestration will occur in. If not \"\n            f\"specified, a default value of {ECS_DEFAULT_CONTAINER_NAME} will be used \"\n            \"and if that is not found in the task definition the first container will \"\n            \"be used.\"\n        ),\n    )\n    task_role_arn: str = Field(\n        title=\"Task Role ARN\",\n        default=None,\n        description=(\n            \"A role to attach to the task run. This controls the permissions of the \"\n            \"task while it is running.\"\n        ),\n    )\n    execution_role_arn: str = Field(\n        title=\"Execution Role ARN\",\n        default=None,\n        description=(\n            \"An execution role to use for the task. This controls the permissions of \"\n            \"the task when it is launching. If this value is not null, it will \"\n            \"override the value in the task definition. An execution role must be \"\n            \"provided to capture logs from the container.\"\n        ),\n    )\n    vpc_id: Optional[str] = Field(\n        title=\"VPC ID\",\n        default=None,\n        description=(\n            \"The AWS VPC to link the task run to. This is only applicable when using \"\n            \"the 'awsvpc' network mode for your task. FARGATE tasks require this \"\n            \"network  mode, but for EC2 tasks the default network mode is 'bridge'. \"\n            \"If using the 'awsvpc' network mode and this field is null, your default \"\n            \"VPC will be used. If no default VPC can be found, the task run will fail.\"\n        ),\n    )\n    configure_cloudwatch_logs: bool = Field(\n        default=None,\n        description=(\n            \"If enabled, the Prefect container will be configured to send its output \"\n            \"to the AWS CloudWatch logs service. This functionality requires an \"\n            \"execution role with logs:CreateLogStream, logs:CreateLogGroup, and \"\n            \"logs:PutLogEvents permissions. The default for this field is `False` \"\n            \"unless `stream_output` is set.\"\n        ),\n    )\n    cloudwatch_logs_options: Dict[str, str] = Field(\n        default_factory=dict,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to\"\n            \" pass additional options to the CloudWatch logs configuration or override\"\n            \" the default options. See the [AWS\"\n            \" documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html#create_awslogs_logdriver_options)\"  # noqa\n            \" for available options. \"\n        ),\n    )\n    cloudwatch_logs_prefix: Optional[str] = Field(\n        default=None,\n        description=(\n            \"When `configure_cloudwatch_logs` is enabled, this setting may be used to\"\n            \" set a prefix for the log group. If not provided, the default prefix will\"\n            \" be `prefect-logs_&lt;work_pool_name&gt;_&lt;deployment_id&gt;`. If\"\n            \" `awslogs-stream-prefix` is present in `Cloudwatch logs options` this\"\n            \" setting will be ignored.\"\n        ),\n    )\n\n    network_configuration: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=(\n            \"When `network_configuration` is supplied it will override ECS Worker's\"\n            \"awsvpcConfiguration that defined in the ECS task executing your workload. \"\n            \"See the [AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-awsvpcconfiguration.html)\"  # noqa\n            \" for available options.\"\n        ),\n    )\n\n    stream_output: bool = Field(\n        default=None,\n        description=(\n            \"If enabled, logs will be streamed from the Prefect container to the local \"\n            \"console. Unless you have configured AWS CloudWatch logs manually on your \"\n            \"task definition, this requires the same prerequisites outlined in \"\n            \"`configure_cloudwatch_logs`.\"\n        ),\n    )\n    task_start_timeout_seconds: int = Field(\n        default=300,\n        description=(\n            \"The amount of time to watch for the start of the ECS task \"\n            \"before marking it as failed. The task must enter a RUNNING state to be \"\n            \"considered started.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an ECS task.\"\n        ),\n    )\n    auto_deregister_task_definition: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, any task definitions that are created by this block will be \"\n            \"deregistered. Existing task definitions linked by ARN will never be \"\n            \"deregistered. Deregistering a task definition does not remove it from \"\n            \"your AWS account, instead it will be marked as INACTIVE.\"\n        ),\n    )\n    match_latest_revision_in_family: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, the most recent active revision in the task definition \"\n            \"family will be compared against the desired ECS task configuration. \"\n            \"If they are equal, the existing task definition will be used instead \"\n            \"of registering a new one. If no family is specified the default family \"\n            f'\"{ECS_DEFAULT_FAMILY}\" will be used.'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker","title":"<code>ECSWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>A Prefect worker to run flow runs as ECS tasks.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSWorker(BaseWorker):\n    \"\"\"\n    A Prefect worker to run flow runs as ECS tasks.\n    \"\"\"\n\n    type = \"ecs\"\n    job_configuration = ECSJobConfiguration\n    job_configuration_variables = ECSVariables\n    _description = (\n        \"Execute flow runs within containers on AWS ECS. Works with EC2 \"\n        \"and Fargate clusters. Requires an AWS account.\"\n    )\n    _display_name = \"AWS Elastic Container Service\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/ecs_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: ECSJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; ECSWorkerResult:\n        \"\"\"\n        Runs a given flow run on the current worker.\n        \"\"\"\n        ecs_client = await run_sync_in_worker_thread(\n            self._get_client, configuration, \"ecs\"\n        )\n\n        logger = self.get_flow_run_logger(flow_run)\n\n        (\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition,\n        ) = await run_sync_in_worker_thread(\n            self._create_task_and_wait_for_start,\n            logger,\n            ecs_client,\n            configuration,\n            flow_run,\n        )\n\n        # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n        # if set to preserve matching by name rather than arn\n        # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n        # single colons.\n        identifier = (\n            (configuration.cluster if configuration.cluster else cluster_arn)\n            + \"::\"\n            + task_arn\n        )\n\n        if task_status:\n            task_status.started(identifier)\n\n        status_code = await run_sync_in_worker_thread(\n            self._watch_task_and_get_exit_code,\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            is_new_task_definition and configuration.auto_deregister_task_definition,\n            ecs_client,\n        )\n\n        return ECSWorkerResult(\n            identifier=identifier,\n            # If the container does not start the exit code can be null but we must\n            # still report a status code. We use a -1 to indicate a special code.\n            status_code=status_code if status_code is not None else -1,\n        )\n\n    def _get_client(\n        self, configuration: ECSJobConfiguration, client_type: Union[str, ClientType]\n    ) -&gt; _ECSClient:\n        \"\"\"\n        Get a boto3 client of client_type. Will use a cached client if one exists.\n        \"\"\"\n        return configuration.aws_credentials.get_client(client_type)\n\n    def _create_task_and_wait_for_start(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        configuration: ECSJobConfiguration,\n        flow_run: FlowRun,\n    ) -&gt; Tuple[str, str, dict, bool]:\n        \"\"\"\n        Register the task definition, create the task run, and wait for it to start.\n\n        Returns a tuple of\n        - The task ARN\n        - The task's cluster ARN\n        - The task definition\n        - A bool indicating if the task definition is newly registered\n        \"\"\"\n        task_definition_arn = configuration.task_run_request.get(\"taskDefinition\")\n        new_task_definition_registered = False\n\n        if not task_definition_arn:\n            task_definition = self._prepare_task_definition(\n                configuration, region=ecs_client.meta.region_name, flow_run=flow_run\n            )\n            (\n                task_definition_arn,\n                new_task_definition_registered,\n            ) = self._get_or_register_task_definition(\n                logger, ecs_client, configuration, flow_run, task_definition\n            )\n        else:\n            task_definition = self._retrieve_task_definition(\n                logger, ecs_client, task_definition_arn\n            )\n            if configuration.task_definition:\n                logger.warning(\n                    \"Ignoring task definition in configuration since task definition\"\n                    \" ARN is provided on the task run request.\"\n                )\n\n        self._validate_task_definition(task_definition, configuration)\n\n        _TASK_DEFINITION_CACHE[flow_run.deployment_id] = task_definition_arn\n\n        logger.info(f\"Using ECS task definition {task_definition_arn!r}...\")\n        logger.debug(\n            f\"Task definition {json.dumps(task_definition, indent=2, default=str)}\"\n        )\n\n        task_run_request = self._prepare_task_run_request(\n            configuration,\n            task_definition,\n            task_definition_arn,\n        )\n\n        logger.info(\"Creating ECS task run...\")\n        logger.debug(\n            \"Task run request\"\n            f\"{json.dumps(mask_api_key(task_run_request), indent=2, default=str)}\"\n        )\n\n        try:\n            task = self._create_task_run(ecs_client, task_run_request)\n            task_arn = task[\"taskArn\"]\n            cluster_arn = task[\"clusterArn\"]\n        except Exception as exc:\n            self._report_task_run_creation_failure(configuration, task_run_request, exc)\n            raise\n\n        logger.info(\"Waiting for ECS task run to start...\")\n        self._wait_for_task_start(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            timeout=configuration.task_start_timeout_seconds,\n        )\n\n        return task_arn, cluster_arn, task_definition, new_task_definition_registered\n\n    def _get_or_register_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        configuration: ECSJobConfiguration,\n        flow_run: FlowRun,\n        task_definition: dict,\n    ) -&gt; Tuple[str, bool]:\n        \"\"\"Get or register a task definition for the given flow run.\n\n        Returns a tuple of the task definition ARN and a bool indicating if the task\n        definition is newly registered.\n        \"\"\"\n\n        cached_task_definition_arn = _TASK_DEFINITION_CACHE.get(flow_run.deployment_id)\n        new_task_definition_registered = False\n\n        if cached_task_definition_arn:\n            try:\n                cached_task_definition = self._retrieve_task_definition(\n                    logger, ecs_client, cached_task_definition_arn\n                )\n                if not cached_task_definition[\n                    \"status\"\n                ] == \"ACTIVE\" or not self._task_definitions_equal(\n                    task_definition, cached_task_definition\n                ):\n                    cached_task_definition_arn = None\n            except Exception:\n                cached_task_definition_arn = None\n\n        if (\n            not cached_task_definition_arn\n            and configuration.match_latest_revision_in_family\n        ):\n            family_name = task_definition.get(\"family\", ECS_DEFAULT_FAMILY)\n            try:\n                task_definition_from_family = self._retrieve_task_definition(\n                    logger, ecs_client, family_name\n                )\n                if task_definition_from_family and self._task_definitions_equal(\n                    task_definition, task_definition_from_family\n                ):\n                    cached_task_definition_arn = task_definition_from_family[\n                        \"taskDefinitionArn\"\n                    ]\n            except Exception:\n                cached_task_definition_arn = None\n\n        if not cached_task_definition_arn:\n            task_definition_arn = self._register_task_definition(\n                logger, ecs_client, task_definition\n            )\n            new_task_definition_registered = True\n        else:\n            task_definition_arn = cached_task_definition_arn\n\n        return task_definition_arn, new_task_definition_registered\n\n    def _watch_task_and_get_exit_code(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        deregister_task_definition: bool,\n        ecs_client: _ECSClient,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Wait for the task run to complete and retrieve the exit code of the Prefect\n        container.\n        \"\"\"\n\n        # Wait for completion and stream logs\n        task = self._wait_for_task_finish(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            task_definition,\n            ecs_client,\n        )\n\n        if deregister_task_definition:\n            ecs_client.deregister_task_definition(\n                taskDefinition=task[\"taskDefinitionArn\"]\n            )\n\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        # Check the status code of the Prefect container\n        container = _get_container(task[\"containers\"], container_name)\n        assert (\n            container is not None\n        ), f\"'{container_name}' container missing from task: {task}\"\n        status_code = container.get(\"exitCode\")\n        self._report_container_status_code(logger, container_name, status_code)\n\n        return status_code\n\n    def _report_container_status_code(\n        self, logger: logging.Logger, name: str, status_code: Optional[int]\n    ) -&gt; None:\n        \"\"\"\n        Display a log for the given container status code.\n        \"\"\"\n        if status_code is None:\n            logger.error(\n                f\"Task exited without reporting an exit status for container {name!r}.\"\n            )\n        elif status_code == 0:\n            logger.info(f\"Container {name!r} exited successfully.\")\n        else:\n            logger.warning(\n                f\"Container {name!r} exited with non-zero exit code {status_code}.\"\n            )\n\n    def _report_task_run_creation_failure(\n        self, configuration: ECSJobConfiguration, task_run: dict, exc: Exception\n    ) -&gt; None:\n        \"\"\"\n        Wrap common AWS task run creation failures with nicer user-facing messages.\n        \"\"\"\n        # AWS generates exception types at runtime so they must be captured a bit\n        # differently than normal.\n        if \"ClusterNotFoundException\" in str(exc):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} not found. \"\n                \"Confirm that the cluster is configured in your region.\"\n            ) from exc\n        elif (\n            \"No Container Instances\" in str(exc) and task_run.get(\"launchType\") == \"EC2\"\n        ):\n            cluster = task_run.get(\"cluster\", \"default\")\n            raise RuntimeError(\n                f\"Failed to run ECS task, cluster {cluster!r} does not appear to \"\n                \"have any container instances associated with it. Confirm that you \"\n                \"have EC2 container instances available.\"\n            ) from exc\n        elif (\n            \"failed to validate logger args\" in str(exc)\n            and \"AccessDeniedException\" in str(exc)\n            and configuration.configure_cloudwatch_logs\n        ):\n            raise RuntimeError(\n                \"Failed to run ECS task, the attached execution role does not appear\"\n                \" to have sufficient permissions. Ensure that the execution role\"\n                f\" {configuration.execution_role!r} has permissions\"\n                \" logs:CreateLogStream, logs:CreateLogGroup, and logs:PutLogEvents.\"\n            )\n        else:\n            raise\n\n    def _validate_task_definition(\n        self, task_definition: dict, configuration: ECSJobConfiguration\n    ) -&gt; None:\n        \"\"\"\n        Ensure that the task definition is compatible with the configuration.\n\n        Raises `ValueError` on incompatibility. Returns `None` on success.\n        \"\"\"\n        launch_type = configuration.task_run_request.get(\n            \"launchType\", ECS_DEFAULT_LAUNCH_TYPE\n        )\n        if (\n            launch_type != \"EC2\"\n            and \"FARGATE\" not in task_definition[\"requiresCompatibilities\"]\n        ):\n            raise ValueError(\n                \"Task definition does not have 'FARGATE' in 'requiresCompatibilities'\"\n                f\" and cannot be used with launch type {launch_type!r}\"\n            )\n\n        if launch_type == \"FARGATE\" or launch_type == \"FARGATE_SPOT\":\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            network_mode = task_definition.get(\"networkMode\")\n            if network_mode != \"awsvpc\":\n                raise ValueError(\n                    f\"Found network mode {network_mode!r} which is not compatible with \"\n                    f\"launch type {launch_type!r}. Use either the 'EC2' launch \"\n                    \"type or the 'awsvpc' network mode.\"\n                )\n\n        if configuration.configure_cloudwatch_logs and not task_definition.get(\n            \"executionRoleArn\"\n        ):\n            raise ValueError(\n                \"An execution role arn must be set on the task definition to use \"\n                \"`configure_cloudwatch_logs` or `stream_logs` but no execution role \"\n                \"was found on the task definition.\"\n            )\n\n    def _register_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        task_definition: dict,\n    ) -&gt; str:\n        \"\"\"\n        Register a new task definition with AWS.\n\n        Returns the ARN.\n        \"\"\"\n        logger.info(\"Registering ECS task definition...\")\n        logger.debug(\n            \"Task definition request\"\n            f\"{json.dumps(task_definition, indent=2, default=str)}\"\n        )\n        response = ecs_client.register_task_definition(**task_definition)\n        return response[\"taskDefinition\"][\"taskDefinitionArn\"]\n\n    def _retrieve_task_definition(\n        self,\n        logger: logging.Logger,\n        ecs_client: _ECSClient,\n        task_definition: str,\n    ):\n        \"\"\"\n        Retrieve an existing task definition from AWS.\n        \"\"\"\n        if task_definition.startswith(\"arn:aws:ecs:\"):\n            logger.info(f\"Retrieving ECS task definition {task_definition!r}...\")\n        else:\n            logger.info(\n                \"Retrieving most recent active revision from \"\n                f\"ECS task family {task_definition!r}...\"\n            )\n        response = ecs_client.describe_task_definition(taskDefinition=task_definition)\n        return response[\"taskDefinition\"]\n\n    def _wait_for_task_start(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        timeout: int,\n    ) -&gt; dict:\n        \"\"\"\n        Waits for an ECS task run to reach a RUNNING status.\n\n        If a STOPPED status is reached instead, an exception is raised indicating the\n        reason that the task run did not start.\n        \"\"\"\n        for task in self._watch_task_run(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            until_status=\"RUNNING\",\n            timeout=timeout,\n        ):\n            # TODO: It is possible that the task has passed _through_ a RUNNING\n            #       status during the polling interval. In this case, there is not an\n            #       exception to raise.\n            if task[\"lastStatus\"] == \"STOPPED\":\n                code = task.get(\"stopCode\")\n                reason = task.get(\"stoppedReason\")\n                # Generate a dynamic exception type from the AWS name\n                raise type(code, (RuntimeError,), {})(reason)\n\n        return task\n\n    def _wait_for_task_finish(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        task_definition: dict,\n        ecs_client: _ECSClient,\n    ):\n        \"\"\"\n        Watch an ECS task until it reaches a STOPPED status.\n\n        If configured, logs from the Prefect container are streamed to stderr.\n\n        Returns a description of the task on completion.\n        \"\"\"\n        can_stream_output = False\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        if configuration.stream_output:\n            container_def = _get_container(\n                task_definition[\"containerDefinitions\"], container_name\n            )\n            if not container_def:\n                logger.warning(\n                    \"Prefect container definition not found in \"\n                    \"task definition. Output cannot be streamed.\"\n                )\n            elif not container_def.get(\"logConfiguration\"):\n                logger.warning(\n                    \"Logging configuration not found on task. \"\n                    \"Output cannot be streamed.\"\n                )\n            elif not container_def[\"logConfiguration\"].get(\"logDriver\") == \"awslogs\":\n                logger.warning(\n                    \"Logging configuration uses unsupported \"\n                    \" driver {container_def['logConfiguration'].get('logDriver')!r}. \"\n                    \"Output cannot be streamed.\"\n                )\n            else:\n                # Prepare to stream the output\n                log_config = container_def[\"logConfiguration\"][\"options\"]\n                logs_client = self._get_client(configuration, \"logs\")\n                can_stream_output = True\n                # Track the last log timestamp to prevent double display\n                last_log_timestamp: Optional[int] = None\n                # Determine the name of the stream as \"prefix/container/run-id\"\n                stream_name = \"/\".join(\n                    [\n                        log_config[\"awslogs-stream-prefix\"],\n                        container_name,\n                        task_arn.rsplit(\"/\")[-1],\n                    ]\n                )\n                self._logger.info(\n                    f\"Streaming output from container {container_name!r}...\"\n                )\n\n        for task in self._watch_task_run(\n            logger,\n            configuration,\n            task_arn,\n            cluster_arn,\n            ecs_client,\n            current_status=\"RUNNING\",\n        ):\n            if configuration.stream_output and can_stream_output:\n                # On each poll for task run status, also retrieve available logs\n                last_log_timestamp = self._stream_available_logs(\n                    logger,\n                    logs_client,\n                    log_group=log_config[\"awslogs-group\"],\n                    log_stream=stream_name,\n                    last_log_timestamp=last_log_timestamp,\n                )\n\n        return task\n\n    def _stream_available_logs(\n        self,\n        logger: logging.Logger,\n        logs_client: Any,\n        log_group: str,\n        log_stream: str,\n        last_log_timestamp: Optional[int] = None,\n    ) -&gt; Optional[int]:\n        \"\"\"\n        Stream logs from the given log group and stream since the last log timestamp.\n\n        Will continue on paginated responses until all logs are returned.\n\n        Returns the last log timestamp which can be used to call this method in the\n        future.\n        \"\"\"\n        last_log_stream_token = \"NO-TOKEN\"\n        next_log_stream_token = None\n\n        # AWS will return the same token that we send once the end of the paginated\n        # response is reached\n        while last_log_stream_token != next_log_stream_token:\n            last_log_stream_token = next_log_stream_token\n\n            request = {\n                \"logGroupName\": log_group,\n                \"logStreamName\": log_stream,\n            }\n\n            if last_log_stream_token is not None:\n                request[\"nextToken\"] = last_log_stream_token\n\n            if last_log_timestamp is not None:\n                # Bump the timestamp by one ms to avoid retrieving the last log again\n                request[\"startTime\"] = last_log_timestamp + 1\n\n            try:\n                response = logs_client.get_log_events(**request)\n            except Exception:\n                logger.error(\n                    f\"Failed to read log events with request {request}\",\n                    exc_info=True,\n                )\n                return last_log_timestamp\n\n            log_events = response[\"events\"]\n            for log_event in log_events:\n                # TODO: This doesn't forward to the local logger, which can be\n                #       bad for customizing handling and understanding where the\n                #       log is coming from, but it avoid nesting logger information\n                #       when the content is output from a Prefect logger on the\n                #       running infrastructure\n                print(log_event[\"message\"], file=sys.stderr)\n\n                if (\n                    last_log_timestamp is None\n                    or log_event[\"timestamp\"] &gt; last_log_timestamp\n                ):\n                    last_log_timestamp = log_event[\"timestamp\"]\n\n            next_log_stream_token = response.get(\"nextForwardToken\")\n            if not log_events:\n                # Stop reading pages if there was no data\n                break\n\n        return last_log_timestamp\n\n    def _watch_task_run(\n        self,\n        logger: logging.Logger,\n        configuration: ECSJobConfiguration,\n        task_arn: str,\n        cluster_arn: str,\n        ecs_client: _ECSClient,\n        current_status: str = \"UNKNOWN\",\n        until_status: str = None,\n        timeout: int = None,\n    ) -&gt; Generator[None, None, dict]:\n        \"\"\"\n        Watches an ECS task run by querying every `poll_interval` seconds. After each\n        query, the retrieved task is yielded. This function returns when the task run\n        reaches a STOPPED status or the provided `until_status`.\n\n        Emits a log each time the status changes.\n        \"\"\"\n        last_status = status = current_status\n        t0 = time.time()\n        while status != until_status:\n            tasks = ecs_client.describe_tasks(\n                tasks=[task_arn], cluster=cluster_arn, include=[\"TAGS\"]\n            )[\"tasks\"]\n\n            if tasks:\n                task = tasks[0]\n\n                status = task[\"lastStatus\"]\n                if status != last_status:\n                    logger.info(f\"ECS task status is {status}.\")\n\n                yield task\n\n                # No point in continuing if the status is final\n                if status == \"STOPPED\":\n                    break\n\n                last_status = status\n\n            else:\n                # Intermittently, the task will not be described. We wat to respect the\n                # watch timeout though.\n                logger.debug(\"Task not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching task for status \"\n                    f\"{until_status or 'STOPPED'}.\"\n                )\n            time.sleep(configuration.task_watch_poll_interval)\n\n    def _get_or_generate_family(self, task_definition: dict, flow_run: FlowRun) -&gt; str:\n        \"\"\"\n        Gets or generate a family for the task definition.\n        \"\"\"\n        family = task_definition.get(\"family\")\n        if not family:\n            assert self._work_pool_name and flow_run.deployment_id\n            family = (\n                f\"{ECS_DEFAULT_FAMILY}_{self._work_pool_name}_{flow_run.deployment_id}\"\n            )\n        slugify(\n            family,\n            max_length=255,\n            regex_pattern=r\"[^a-zA-Z0-9-_]+\",\n        )\n        return family\n\n    def _prepare_task_definition(\n        self,\n        configuration: ECSJobConfiguration,\n        region: str,\n        flow_run: FlowRun,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task definition by inferring any defaults and merging overrides.\n        \"\"\"\n        task_definition = copy.deepcopy(configuration.task_definition)\n\n        # Configure the Prefect runtime container\n        task_definition.setdefault(\"containerDefinitions\", [])\n\n        # Remove empty container definitions\n        task_definition[\"containerDefinitions\"] = [\n            d for d in task_definition[\"containerDefinitions\"] if d\n        ]\n\n        container_name = configuration.container_name\n        if not container_name:\n            container_name = (\n                _container_name_from_task_definition(task_definition)\n                or ECS_DEFAULT_CONTAINER_NAME\n            )\n\n        container = _get_container(\n            task_definition[\"containerDefinitions\"], container_name\n        )\n        if container is None:\n            if container_name != ECS_DEFAULT_CONTAINER_NAME:\n                raise ValueError(\n                    f\"Container {container_name!r} not found in task definition.\"\n                )\n\n            # Look for a container without a name\n            for container in task_definition[\"containerDefinitions\"]:\n                if \"name\" not in container:\n                    container[\"name\"] = container_name\n                    break\n            else:\n                container = {\"name\": container_name}\n                task_definition[\"containerDefinitions\"].append(container)\n\n        # Image is required so make sure it's present\n        container.setdefault(\"image\", get_prefect_image_name())\n\n        # Remove any keys that have been explicitly \"unset\"\n        unset_keys = {key for key, value in configuration.env.items() if value is None}\n        for item in tuple(container.get(\"environment\", [])):\n            if item[\"name\"] in unset_keys or item[\"value\"] is None:\n                container[\"environment\"].remove(item)\n\n        if configuration.configure_cloudwatch_logs:\n            prefix = f\"prefect-logs_{self._work_pool_name}_{flow_run.deployment_id}\"\n            container[\"logConfiguration\"] = {\n                \"logDriver\": \"awslogs\",\n                \"options\": {\n                    \"awslogs-create-group\": \"true\",\n                    \"awslogs-group\": \"prefect\",\n                    \"awslogs-region\": region,\n                    \"awslogs-stream-prefix\": (\n                        configuration.cloudwatch_logs_prefix or prefix\n                    ),\n                    **configuration.cloudwatch_logs_options,\n                },\n            }\n\n        task_definition[\"family\"] = self._get_or_generate_family(\n            task_definition, flow_run\n        )\n        # CPU and memory are required in some cases, retrieve the value to use\n        cpu = task_definition.get(\"cpu\") or ECS_DEFAULT_CPU\n        memory = task_definition.get(\"memory\") or ECS_DEFAULT_MEMORY\n\n        launch_type = configuration.task_run_request.get(\n            \"launchType\", ECS_DEFAULT_LAUNCH_TYPE\n        )\n\n        if launch_type == \"FARGATE\" or launch_type == \"FARGATE_SPOT\":\n            # Task level memory and cpu are required when using fargate\n            task_definition[\"cpu\"] = str(cpu)\n            task_definition[\"memory\"] = str(memory)\n\n            # The FARGATE compatibility is required if it will be used as as launch type\n            requires_compatibilities = task_definition.setdefault(\n                \"requiresCompatibilities\", []\n            )\n            if \"FARGATE\" not in requires_compatibilities:\n                task_definition[\"requiresCompatibilities\"].append(\"FARGATE\")\n\n            # Only the 'awsvpc' network mode is supported when using FARGATE\n            # However, we will not enforce that here if the user has set it\n            task_definition.setdefault(\"networkMode\", \"awsvpc\")\n\n        elif launch_type == \"EC2\":\n            # Container level memory and cpu are required when using ec2\n            container.setdefault(\"cpu\", cpu)\n            container.setdefault(\"memory\", memory)\n\n            # Ensure set values are cast to integers\n            container[\"cpu\"] = int(container[\"cpu\"])\n            container[\"memory\"] = int(container[\"memory\"])\n\n        # Ensure set values are cast to strings\n        if task_definition.get(\"cpu\"):\n            task_definition[\"cpu\"] = str(task_definition[\"cpu\"])\n        if task_definition.get(\"memory\"):\n            task_definition[\"memory\"] = str(task_definition[\"memory\"])\n\n        return task_definition\n\n    def _load_network_configuration(\n        self, vpc_id: Optional[str], configuration: ECSJobConfiguration\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = self._get_client(configuration, \"ec2\")\n        vpc_message = \"the default VPC\" if not vpc_id else f\"VPC with ID {vpc_id}\"\n\n        if not vpc_id:\n            # Retrieve the default VPC\n            describe = {\"Filters\": [{\"Name\": \"isDefault\", \"Values\": [\"true\"]}]}\n        else:\n            describe = {\"VpcIds\": [vpc_id]}\n\n        vpcs = ec2_client.describe_vpcs(**describe)[\"Vpcs\"]\n        if not vpcs:\n            help_message = (\n                \"Pass an explicit `vpc_id` or configure a default VPC.\"\n                if not vpc_id\n                else \"Check that the VPC exists in the current region.\"\n            )\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                \"Network configuration cannot be inferred. \" + help_message\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                \"Network configuration cannot be inferred.\"\n            )\n\n        return {\n            \"awsvpcConfiguration\": {\n                \"subnets\": [s[\"SubnetId\"] for s in subnets],\n                \"assignPublicIp\": \"ENABLED\",\n                \"securityGroups\": [],\n            }\n        }\n\n    def _custom_network_configuration(\n        self,\n        vpc_id: str,\n        network_configuration: dict,\n        configuration: ECSJobConfiguration,\n    ) -&gt; dict:\n        \"\"\"\n        Load settings from a specific VPC or the default VPC and generate a task\n        run request's network configuration.\n        \"\"\"\n        ec2_client = self._get_client(configuration, \"ec2\")\n        vpc_message = f\"VPC with ID {vpc_id}\"\n\n        vpcs = ec2_client.describe_vpcs(VpcIds=[vpc_id]).get(\"Vpcs\")\n\n        if not vpcs:\n            raise ValueError(\n                f\"Failed to find {vpc_message}. \"\n                + \"Network configuration cannot be inferred. \"\n                + \"Pass an explicit `vpc_id`.\"\n            )\n\n        vpc_id = vpcs[0][\"VpcId\"]\n        subnets = ec2_client.describe_subnets(\n            Filters=[{\"Name\": \"vpc-id\", \"Values\": [vpc_id]}]\n        )[\"Subnets\"]\n\n        if not subnets:\n            raise ValueError(\n                f\"Failed to find subnets for {vpc_message}. \"\n                + \"Network configuration cannot be inferred.\"\n            )\n\n        subnet_ids = [subnet[\"SubnetId\"] for subnet in subnets]\n\n        config_subnets = network_configuration.get(\"subnets\", [])\n        if not all(conf_sn in subnet_ids for conf_sn in config_subnets):\n            raise ValueError(\n                f\"Subnets {config_subnets} not found within {vpc_message}.\"\n                + \" Please check that VPC is associated with supplied subnets.\"\n            )\n\n        return {\"awsvpcConfiguration\": network_configuration}\n\n    def _prepare_task_run_request(\n        self,\n        configuration: ECSJobConfiguration,\n        task_definition: dict,\n        task_definition_arn: str,\n    ) -&gt; dict:\n        \"\"\"\n        Prepare a task run request payload.\n        \"\"\"\n        task_run_request = deepcopy(configuration.task_run_request)\n\n        task_run_request.setdefault(\"taskDefinition\", task_definition_arn)\n        assert task_run_request[\"taskDefinition\"] == task_definition_arn\n        capacityProviderStrategy = task_run_request.get(\"capacityProviderStrategy\")\n\n        if capacityProviderStrategy:\n            # Should not be provided at all if capacityProviderStrategy is set, see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html#ECS-RunTask-request-capacityProviderStrategy  # noqa\n            self._logger.warning(\n                \"Found capacityProviderStrategy. \"\n                \"Removing launchType from task run request.\"\n            )\n            task_run_request.pop(\"launchType\", None)\n\n        elif task_run_request.get(\"launchType\") == \"FARGATE_SPOT\":\n            # Should not be provided at all for FARGATE SPOT\n            task_run_request.pop(\"launchType\", None)\n\n            # A capacity provider strategy is required for FARGATE SPOT\n            task_run_request[\"capacityProviderStrategy\"] = [\n                {\"capacityProvider\": \"FARGATE_SPOT\", \"weight\": 1}\n            ]\n        overrides = task_run_request.get(\"overrides\", {})\n        container_overrides = overrides.get(\"containerOverrides\", [])\n\n        # Ensure the network configuration is present if using awsvpc for network mode\n        if (\n            task_definition.get(\"networkMode\") == \"awsvpc\"\n            and not task_run_request.get(\"networkConfiguration\")\n            and not configuration.network_configuration\n        ):\n            task_run_request[\"networkConfiguration\"] = self._load_network_configuration(\n                configuration.vpc_id, configuration\n            )\n\n        # Use networkConfiguration if supplied by user\n        if (\n            task_definition.get(\"networkMode\") == \"awsvpc\"\n            and configuration.network_configuration\n            and configuration.vpc_id\n        ):\n            task_run_request[\n                \"networkConfiguration\"\n            ] = self._custom_network_configuration(\n                configuration.vpc_id,\n                configuration.network_configuration,\n                configuration,\n            )\n\n        # Ensure the container name is set if not provided at template time\n\n        container_name = (\n            configuration.container_name\n            or _container_name_from_task_definition(task_definition)\n            or ECS_DEFAULT_CONTAINER_NAME\n        )\n\n        if container_overrides and not container_overrides[0].get(\"name\"):\n            container_overrides[0][\"name\"] = container_name\n\n        # Ensure configuration command is respected post-templating\n\n        orchestration_container = _get_container(container_overrides, container_name)\n\n        if orchestration_container:\n            # Override the command if given on the configuration\n            if configuration.command:\n                orchestration_container[\"command\"] = configuration.command\n\n        # Clean up templated variable formatting\n\n        for container in container_overrides:\n            if isinstance(container.get(\"command\"), str):\n                container[\"command\"] = shlex.split(container[\"command\"])\n            if isinstance(container.get(\"environment\"), dict):\n                container[\"environment\"] = [\n                    {\"name\": k, \"value\": v} for k, v in container[\"environment\"].items()\n                ]\n\n            # Remove null values \u2014 they're not allowed by AWS\n            container[\"environment\"] = [\n                item\n                for item in container.get(\"environment\", [])\n                if item[\"value\"] is not None\n            ]\n\n        if isinstance(task_run_request.get(\"tags\"), dict):\n            task_run_request[\"tags\"] = [\n                {\"key\": k, \"value\": v} for k, v in task_run_request[\"tags\"].items()\n            ]\n\n        if overrides.get(\"cpu\"):\n            overrides[\"cpu\"] = str(overrides[\"cpu\"])\n\n        if overrides.get(\"memory\"):\n            overrides[\"memory\"] = str(overrides[\"memory\"])\n\n        # Ensure configuration tags and env are respected post-templating\n\n        tags = [\n            item\n            for item in task_run_request.get(\"tags\", [])\n            if item[\"key\"] not in configuration.labels.keys()\n        ] + [\n            {\"key\": k, \"value\": v}\n            for k, v in configuration.labels.items()\n            if v is not None\n        ]\n\n        # Slugify tags keys and values\n        tags = [\n            {\n                \"key\": slugify(\n                    item[\"key\"],\n                    regex_pattern=_TAG_REGEX,\n                    allow_unicode=True,\n                    lowercase=False,\n                ),\n                \"value\": slugify(\n                    item[\"value\"],\n                    regex_pattern=_TAG_REGEX,\n                    allow_unicode=True,\n                    lowercase=False,\n                ),\n            }\n            for item in tags\n        ]\n\n        if tags:\n            task_run_request[\"tags\"] = tags\n\n        if orchestration_container:\n            environment = [\n                item\n                for item in orchestration_container.get(\"environment\", [])\n                if item[\"name\"] not in configuration.env.keys()\n            ] + [\n                {\"name\": k, \"value\": v}\n                for k, v in configuration.env.items()\n                if v is not None\n            ]\n            if environment:\n                orchestration_container[\"environment\"] = environment\n\n        # Remove empty container overrides\n\n        overrides[\"containerOverrides\"] = [v for v in container_overrides if v]\n\n        return task_run_request\n\n    @retry(\n        stop=stop_after_attempt(MAX_CREATE_TASK_RUN_ATTEMPTS),\n        wait=wait_fixed(CREATE_TASK_RUN_MIN_DELAY_SECONDS)\n        + wait_random(\n            CREATE_TASK_RUN_MIN_DELAY_JITTER_SECONDS,\n            CREATE_TASK_RUN_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    def _create_task_run(self, ecs_client: _ECSClient, task_run_request: dict) -&gt; str:\n        \"\"\"\n        Create a run of a task definition.\n\n        Returns the task run ARN.\n        \"\"\"\n        task = ecs_client.run_task(**task_run_request)\n        if task[\"failures\"]:\n            raise RuntimeError(\n                f\"Failed to run ECS task: {task['failures'][0]['reason']}\"\n            )\n        elif not task[\"tasks\"]:\n            raise RuntimeError(\n                \"Failed to run ECS task: no tasks or failures were returned.\"\n            )\n        return task[\"tasks\"][0]\n\n    def _task_definitions_equal(self, taskdef_1, taskdef_2) -&gt; bool:\n        \"\"\"\n        Compare two task definitions.\n\n        Since one may come from the AWS API and have populated defaults, we do our best\n        to homogenize the definitions without changing their meaning.\n        \"\"\"\n        if taskdef_1 == taskdef_2:\n            return True\n\n        if taskdef_1 is None or taskdef_2 is None:\n            return False\n\n        taskdef_1 = copy.deepcopy(taskdef_1)\n        taskdef_2 = copy.deepcopy(taskdef_2)\n\n        for taskdef in (taskdef_1, taskdef_2):\n            # Set defaults that AWS would set after registration\n            container_definitions = taskdef.get(\"containerDefinitions\", [])\n            essential = any(\n                container.get(\"essential\") for container in container_definitions\n            )\n            if not essential:\n                container_definitions[0].setdefault(\"essential\", True)\n\n            taskdef.setdefault(\"networkMode\", \"bridge\")\n\n        _drop_empty_keys_from_task_definition(taskdef_1)\n        _drop_empty_keys_from_task_definition(taskdef_2)\n\n        # Clear fields that change on registration for comparison\n        for field in ECS_POST_REGISTRATION_FIELDS:\n            taskdef_1.pop(field, None)\n            taskdef_2.pop(field, None)\n\n        return taskdef_1 == taskdef_2\n\n    async def kill_infrastructure(\n        self,\n        configuration: ECSJobConfiguration,\n        infrastructure_pid: str,\n        grace_seconds: int = 30,\n    ) -&gt; None:\n        \"\"\"\n        Kill a task running on ECS.\n\n        Args:\n            infrastructure_pid: A cluster and task arn combination. This should match a\n                value yielded by `ECSWorker.run`.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n                \"support dynamic grace period configuration so 30s will be used. \"\n                \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n            )\n        cluster, task = parse_identifier(infrastructure_pid)\n        await run_sync_in_worker_thread(self._stop_task, configuration, cluster, task)\n\n    def _stop_task(\n        self, configuration: ECSJobConfiguration, cluster: str, task: str\n    ) -&gt; None:\n        \"\"\"\n        Stop a running ECS task.\n        \"\"\"\n        if configuration.cluster is not None and cluster != configuration.cluster:\n            raise InfrastructureNotAvailable(\n                \"Cannot stop ECS task: this infrastructure block has access to \"\n                f\"cluster {configuration.cluster!r} but the task is running in cluster \"\n                f\"{cluster!r}.\"\n            )\n\n        ecs_client = self._get_client(configuration, \"ecs\")\n        try:\n            ecs_client.stop_task(cluster=cluster, task=task)\n        except Exception as exc:\n            # Raise a special exception if the task does not exist\n            if \"ClusterNotFound\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} could not be found.\"\n                ) from exc\n            if \"not find task\" in str(exc) or \"referenced task was not found\" in str(\n                exc\n            ):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the task {task!r} could not be found in \"\n                    f\"cluster {cluster!r}.\"\n                ) from exc\n            if \"no registered tasks\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop ECS task: the cluster {cluster!r} has no tasks.\"\n                ) from exc\n\n            # Reraise unknown exceptions\n            raise\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Kill a task running on ECS.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>A cluster and task arn combination. This should match a value yielded by <code>ECSWorker.run</code>.</p> required Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    configuration: ECSJobConfiguration,\n    infrastructure_pid: str,\n    grace_seconds: int = 30,\n) -&gt; None:\n    \"\"\"\n    Kill a task running on ECS.\n\n    Args:\n        infrastructure_pid: A cluster and task arn combination. This should match a\n            value yielded by `ECSWorker.run`.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but AWS does not \"\n            \"support dynamic grace period configuration so 30s will be used. \"\n            \"See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html for configuration of grace periods.\"  # noqa\n        )\n    cluster, task = parse_identifier(infrastructure_pid)\n    await run_sync_in_worker_thread(self._stop_task, configuration, cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs a given flow run on the current worker.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: ECSJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; ECSWorkerResult:\n    \"\"\"\n    Runs a given flow run on the current worker.\n    \"\"\"\n    ecs_client = await run_sync_in_worker_thread(\n        self._get_client, configuration, \"ecs\"\n    )\n\n    logger = self.get_flow_run_logger(flow_run)\n\n    (\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition,\n    ) = await run_sync_in_worker_thread(\n        self._create_task_and_wait_for_start,\n        logger,\n        ecs_client,\n        configuration,\n        flow_run,\n    )\n\n    # The task identifier is \"{cluster}::{task}\" where we use the configured cluster\n    # if set to preserve matching by name rather than arn\n    # Note \"::\" is used despite the Prefect standard being \":\" because ARNs contain\n    # single colons.\n    identifier = (\n        (configuration.cluster if configuration.cluster else cluster_arn)\n        + \"::\"\n        + task_arn\n    )\n\n    if task_status:\n        task_status.started(identifier)\n\n    status_code = await run_sync_in_worker_thread(\n        self._watch_task_and_get_exit_code,\n        logger,\n        configuration,\n        task_arn,\n        cluster_arn,\n        task_definition,\n        is_new_task_definition and configuration.auto_deregister_task_definition,\n        ecs_client,\n    )\n\n    return ECSWorkerResult(\n        identifier=identifier,\n        # If the container does not start the exit code can be null but we must\n        # still report a status code. We use a -1 to indicate a special code.\n        status_code=status_code if status_code is not None else -1,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.ECSWorkerResult","title":"<code>ECSWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>The result of an ECS job.</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>class ECSWorkerResult(BaseWorkerResult):\n    \"\"\"\n    The result of an ECS job.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/ecs_worker/#prefect_aws.workers.ecs_worker.parse_identifier","title":"<code>parse_identifier</code>","text":"<p>Splits identifier into its cluster and task components, e.g. input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").</p> Source code in <code>prefect_aws/workers/ecs_worker.py</code> <pre><code>def parse_identifier(identifier: str) -&gt; ECSIdentifier:\n    \"\"\"\n    Splits identifier into its cluster and task components, e.g.\n    input \"cluster_name::task_arn\" outputs (\"cluster_name\", \"task_arn\").\n    \"\"\"\n    cluster, task = identifier.split(\"::\", maxsplit=1)\n    return ECSIdentifier(cluster, task)\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/","title":"Glue Job","text":""},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job","title":"<code>prefect_aws.glue_job</code>","text":"<p>Integrations with the AWS Glue Job.</p>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobBlock","title":"<code>GlueJobBlock</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>Execute a job to the AWS Glue Job service.</p> <p>Attributes:</p> Name Type Description <code>job_name</code> <code>str</code> <p>The name of the job definition to use.</p> <code>arguments</code> <code>Optional[dict]</code> <p>The job arguments associated with this run. For this job run, they replace the default arguments set in the job definition itself. You can specify arguments here that your own job-execution script consumes, as well as arguments that Glue itself consumes. Job arguments may be logged. Do not pass plaintext secrets as arguments. Retrieve secrets from a Glue Connection, Secrets Manager or other secret management mechanism if you intend to keep them within the Job. doc</p> <code>job_watch_poll_interval</code> <code>float</code> <p>The amount of time to wait between AWS API calls while monitoring the state of a Glue Job. default is 60s because of jobs that use AWS Glue versions 2.0 and later have a 1-minute minimum. AWS Glue Pricing</p> Example <p>Start a job to AWS Glue Job. <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.glue_job import GlueJobBlock\n\n\n@flow\ndef example_run_glue_job():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"your_access_key_id\",\n        aws_secret_access_key=\"your_secret_access_key\"\n    )\n    glue_job_run = GlueJobBlock(\n        job_name=\"your_glue_job_name\",\n        arguments={\"--YOUR_EXTRA_ARGUMENT\": \"YOUR_EXTRA_ARGUMENT_VALUE\"},\n    ).trigger()\n\n    return glue_job_run.wait_for_completion()\n\n\nexample_run_glue_job()\n</code></pre></p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>class GlueJobBlock(JobBlock):\n    \"\"\"Execute a job to the AWS Glue Job service.\n\n    Attributes:\n        job_name: The name of the job definition to use.\n        arguments: The job arguments associated with this run.\n            For this job run, they replace the default arguments set in the job\n            definition itself.\n            You can specify arguments here that your own job-execution script consumes,\n            as well as arguments that Glue itself consumes.\n            Job arguments may be logged. Do not pass plaintext secrets as arguments.\n            Retrieve secrets from a Glue Connection, Secrets Manager or other secret\n            management mechanism if you intend to keep them within the Job.\n            [doc](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)\n        job_watch_poll_interval: The amount of time to wait between AWS API\n            calls while monitoring the state of a Glue Job.\n            default is 60s because of jobs that use AWS Glue versions 2.0 and later\n            have a 1-minute minimum.\n            [AWS Glue Pricing](https://aws.amazon.com/glue/pricing/?nc1=h_ls)\n\n    Example:\n        Start a job to AWS Glue Job.\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.glue_job import GlueJobBlock\n\n\n        @flow\n        def example_run_glue_job():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"your_access_key_id\",\n                aws_secret_access_key=\"your_secret_access_key\"\n            )\n            glue_job_run = GlueJobBlock(\n                job_name=\"your_glue_job_name\",\n                arguments={\"--YOUR_EXTRA_ARGUMENT\": \"YOUR_EXTRA_ARGUMENT_VALUE\"},\n            ).trigger()\n\n            return glue_job_run.wait_for_completion()\n\n\n        example_run_glue_job()\n        ```\n    \"\"\"\n\n    job_name: str = Field(\n        ...,\n        title=\"AWS Glue Job Name\",\n        description=\"The name of the job definition to use.\",\n    )\n\n    arguments: Optional[dict] = Field(\n        default=None,\n        title=\"AWS Glue Job Arguments\",\n        description=\"The job arguments associated with this run.\",\n    )\n    job_watch_poll_interval: float = Field(\n        default=60.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an Glue Job.\"\n        ),\n    )\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to Glue.\",\n    )\n\n    async def trigger(self) -&gt; GlueJobRun:\n        \"\"\"trigger for GlueJobRun\"\"\"\n        client = self._get_client()\n        job_run_id = self._start_job(client)\n        return GlueJobRun(\n            job_name=self.job_name,\n            job_id=job_run_id,\n            job_watch_poll_interval=self.job_watch_poll_interval,\n        )\n\n    def _start_job(self, client: _GlueJobClient) -&gt; str:\n        \"\"\"\n        Start the AWS Glue Job\n        [doc](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/glue/client/start_job_run.html)\n        \"\"\"\n        self.logger.info(\n            f\"starting job {self.job_name} with arguments {self.arguments}\"\n        )\n        try:\n            response = client.start_job_run(\n                JobName=self.job_name,\n                Arguments=self.arguments,\n            )\n            job_run_id = str(response[\"JobRunId\"])\n            self.logger.info(f\"job started with job run id: {job_run_id}\")\n            return job_run_id\n        except Exception as e:\n            self.logger.error(f\"failed to start job: {e}\")\n            raise RuntimeError\n\n    def _get_client(self) -&gt; _GlueJobClient:\n        \"\"\"\n        Retrieve a Glue Job Client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        return boto_session.client(\"glue\")\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobBlock.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>trigger for GlueJobRun</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>async def trigger(self) -&gt; GlueJobRun:\n    \"\"\"trigger for GlueJobRun\"\"\"\n    client = self._get_client()\n    job_run_id = self._start_job(client)\n    return GlueJobRun(\n        job_name=self.job_name,\n        job_id=job_run_id,\n        job_watch_poll_interval=self.job_watch_poll_interval,\n    )\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun","title":"<code>GlueJobRun</code>","text":"<p>               Bases: <code>JobRun</code>, <code>BaseModel</code></p> <p>Execute a Glue Job</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>class GlueJobRun(JobRun, BaseModel):\n    \"\"\"Execute a Glue Job\"\"\"\n\n    job_name: str = Field(\n        ...,\n        title=\"AWS Glue Job Name\",\n        description=\"The name of the job definition to use.\",\n    )\n\n    job_id: str = Field(\n        ...,\n        title=\"AWS Glue Job ID\",\n        description=\"The ID of the job run.\",\n    )\n\n    job_watch_poll_interval: float = Field(\n        default=60.0,\n        description=(\n            \"The amount of time to wait between AWS API calls while monitoring the \"\n            \"state of an Glue Job.\"\n        ),\n    )\n\n    _error_states = [\"FAILED\", \"STOPPED\", \"ERROR\", \"TIMEOUT\"]\n\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to use to connect to Glue.\",\n    )\n\n    client: _GlueJobClient = Field(default=None, description=\"\")\n\n    async def fetch_result(self) -&gt; str:\n        \"\"\"fetch glue job state\"\"\"\n        job = self._get_job_run()\n        return job[\"JobRun\"][\"JobRunState\"]\n\n    def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Wait for the job run to complete and get exit code\n        \"\"\"\n        self.logger.info(f\"watching job {self.job_name} with run id {self.job_id}\")\n        while True:\n            job = self._get_job_run()\n            job_state = job[\"JobRun\"][\"JobRunState\"]\n            if job_state in self._error_states:\n                # Generate a dynamic exception type from the AWS name\n                self.logger.error(f\"job failed: {job['JobRun']['ErrorMessage']}\")\n                raise RuntimeError(job[\"JobRun\"][\"ErrorMessage\"])\n            elif job_state == \"SUCCEEDED\":\n                self.logger.info(f\"job succeeded: {self.job_id}\")\n                break\n\n            time.sleep(self.job_watch_poll_interval)\n\n    def _get_job_run(self):\n        \"\"\"get glue job\"\"\"\n        return self.client.get_job_run(JobName=self.job_name, RunId=self.job_id)\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>fetch glue job state</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>async def fetch_result(self) -&gt; str:\n    \"\"\"fetch glue job state\"\"\"\n    job = self._get_job_run()\n    return job[\"JobRun\"][\"JobRunState\"]\n</code></pre>"},{"location":"integrations/prefect-aws/glue_job/#prefect_aws.glue_job.GlueJobRun.wait_for_completion","title":"<code>wait_for_completion</code>","text":"<p>Wait for the job run to complete and get exit code</p> Source code in <code>prefect_aws/glue_job.py</code> <pre><code>def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Wait for the job run to complete and get exit code\n    \"\"\"\n    self.logger.info(f\"watching job {self.job_name} with run id {self.job_id}\")\n    while True:\n        job = self._get_job_run()\n        job_state = job[\"JobRun\"][\"JobRunState\"]\n        if job_state in self._error_states:\n            # Generate a dynamic exception type from the AWS name\n            self.logger.error(f\"job failed: {job['JobRun']['ErrorMessage']}\")\n            raise RuntimeError(job[\"JobRun\"][\"ErrorMessage\"])\n        elif job_state == \"SUCCEEDED\":\n            self.logger.info(f\"job succeeded: {self.job_id}\")\n            break\n\n        time.sleep(self.job_watch_poll_interval)\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/","title":"Lambda","text":""},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function","title":"<code>prefect_aws.lambda_function</code>","text":"<p>Integrations with AWS Lambda.</p> <p>Examples:</p> <pre><code>Run a lambda function with a payload\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(payload={\"foo\": \"bar\"})\n```\n\nSpecify a version of a lambda function\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    qualifier=\"1\",\n    aws_credentials=aws_credentials,\n).invoke()\n```\n\nInvoke a lambda function asynchronously\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(invocation_type=\"Event\")\n```\n\nInvoke a lambda function and return the last 4 KB of logs\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(tail=True)\n```\n\nInvoke a lambda function with a client context\n\n```python\nLambdaFunction(\n    function_name=\"test-function\",\n    aws_credentials=aws_credentials,\n).invoke(client_context={\"bar\": \"foo\"})\n```\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction","title":"<code>LambdaFunction</code>","text":"<p>               Bases: <code>Block</code></p> <p>Invoke a Lambda function. This block is part of the prefect-aws collection. Install prefect-aws with <code>pip install prefect-aws</code> to use this block.</p> <p>Attributes:</p> Name Type Description <code>function_name</code> <code>str</code> <p>The name, ARN, or partial ARN of the Lambda function to run. This must be the name of a function that is already deployed to AWS Lambda.</p> <code>qualifier</code> <code>Optional[str]</code> <p>The version or alias of the Lambda function to use when invoked. If not specified, the latest (unqualified) version of the Lambda function will be used.</p> <code>aws_credentials</code> <code>AwsCredentials</code> <p>The AWS credentials to use to connect to AWS Lambda with a default factory of AwsCredentials.</p> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>class LambdaFunction(Block):\n    \"\"\"Invoke a Lambda function. This block is part of the prefect-aws\n    collection. Install prefect-aws with `pip install prefect-aws` to use this\n    block.\n\n    Attributes:\n        function_name: The name, ARN, or partial ARN of the Lambda function to\n            run. This must be the name of a function that is already deployed\n            to AWS Lambda.\n        qualifier: The version or alias of the Lambda function to use when\n            invoked. If not specified, the latest (unqualified) version of the\n            Lambda function will be used.\n        aws_credentials: The AWS credentials to use to connect to AWS Lambda\n            with a default factory of AwsCredentials.\n\n    \"\"\"\n\n    _block_type_name = \"Lambda Function\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/s3/#prefect_aws.lambda_function.LambdaFunction\"  # noqa\n\n    function_name: str = Field(\n        title=\"Function Name\",\n        description=(\n            \"The name, ARN, or partial ARN of the Lambda function to run. This\"\n            \" must be the name of a function that is already deployed to AWS\"\n            \" Lambda.\"\n        ),\n    )\n    qualifier: Optional[str] = Field(\n        default=None,\n        title=\"Qualifier\",\n        description=(\n            \"The version or alias of the Lambda function to use when invoked. \"\n            \"If not specified, the latest (unqualified) version of the Lambda \"\n            \"function will be used.\"\n        ),\n    )\n    aws_credentials: AwsCredentials = Field(\n        title=\"AWS Credentials\",\n        default_factory=AwsCredentials,\n        description=\"The AWS credentials to invoke the Lambda with.\",\n    )\n\n    class Config:\n        \"\"\"Lambda's pydantic configuration.\"\"\"\n\n        smart_union = True\n\n    def _get_lambda_client(self):\n        \"\"\"\n        Retrieve a boto3 session and Lambda client\n        \"\"\"\n        boto_session = self.aws_credentials.get_boto3_session()\n        lambda_client = boto_session.client(\"lambda\")\n        return lambda_client\n\n    @sync_compatible\n    async def invoke(\n        self,\n        payload: dict = None,\n        invocation_type: Literal[\n            \"RequestResponse\", \"Event\", \"DryRun\"\n        ] = \"RequestResponse\",\n        tail: bool = False,\n        client_context: Optional[dict] = None,\n    ) -&gt; dict:\n        \"\"\"\n        [Invoke](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html)\n        the Lambda function with the given payload.\n\n        Args:\n            payload: The payload to send to the Lambda function.\n            invocation_type: The invocation type of the Lambda function. This\n                can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses\n                \"RequestResponse\" by default.\n            tail: If True, the response will include the base64-encoded last 4\n                KB of log data produced by the Lambda function.\n            client_context: The client context to send to the Lambda function.\n                Limited to 3583 bytes.\n\n        Returns:\n            The response from the Lambda function.\n\n        Examples:\n\n            ```python\n            from prefect_aws.lambda_function import LambdaFunction\n            from prefect_aws.credentials import AwsCredentials\n\n            credentials = AwsCredentials()\n            lambda_function = LambdaFunction(\n                function_name=\"test_lambda_function\",\n                aws_credentials=credentials,\n            )\n            response = lambda_function.invoke(\n                payload={\"foo\": \"bar\"},\n                invocation_type=\"RequestResponse\",\n            )\n            response[\"Payload\"].read()\n            ```\n            ```txt\n            b'{\"foo\": \"bar\"}'\n            ```\n\n        \"\"\"\n        # Add invocation arguments\n        kwargs = dict(FunctionName=self.function_name)\n\n        if payload:\n            kwargs[\"Payload\"] = json.dumps(payload).encode()\n\n        # Let boto handle invalid invocation types\n        kwargs[\"InvocationType\"] = invocation_type\n\n        if self.qualifier is not None:\n            kwargs[\"Qualifier\"] = self.qualifier\n\n        if tail:\n            kwargs[\"LogType\"] = \"Tail\"\n\n        if client_context is not None:\n            # For some reason this is string, but payload is bytes\n            kwargs[\"ClientContext\"] = json.dumps(client_context)\n\n        # Get client and invoke\n        lambda_client = await run_sync_in_worker_thread(self._get_lambda_client)\n        return await run_sync_in_worker_thread(lambda_client.invoke, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction.Config","title":"<code>Config</code>","text":"<p>Lambda's pydantic configuration.</p> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>class Config:\n    \"\"\"Lambda's pydantic configuration.\"\"\"\n\n    smart_union = True\n</code></pre>"},{"location":"integrations/prefect-aws/lambda_function/#prefect_aws.lambda_function.LambdaFunction.invoke","title":"<code>invoke</code>  <code>async</code>","text":"<p>Invoke the Lambda function with the given payload.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>dict</code> <p>The payload to send to the Lambda function.</p> <code>None</code> <code>invocation_type</code> <code>Literal['RequestResponse', 'Event', 'DryRun']</code> <p>The invocation type of the Lambda function. This can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses \"RequestResponse\" by default.</p> <code>'RequestResponse'</code> <code>tail</code> <code>bool</code> <p>If True, the response will include the base64-encoded last 4 KB of log data produced by the Lambda function.</p> <code>False</code> <code>client_context</code> <code>Optional[dict]</code> <p>The client context to send to the Lambda function. Limited to 3583 bytes.</p> <code>None</code> <p>Returns:</p> Type Description <code>dict</code> <p>The response from the Lambda function.</p> <pre><code>```python\nfrom prefect_aws.lambda_function import LambdaFunction\nfrom prefect_aws.credentials import AwsCredentials\n\ncredentials = AwsCredentials()\nlambda_function = LambdaFunction(\n    function_name=\"test_lambda_function\",\n    aws_credentials=credentials,\n)\nresponse = lambda_function.invoke(\n    payload={\"foo\": \"bar\"},\n    invocation_type=\"RequestResponse\",\n)\nresponse[\"Payload\"].read()\n```\n```txt\nb'{\"foo\": \"bar\"}'\n```\n</code></pre> Source code in <code>prefect_aws/lambda_function.py</code> <pre><code>@sync_compatible\nasync def invoke(\n    self,\n    payload: dict = None,\n    invocation_type: Literal[\n        \"RequestResponse\", \"Event\", \"DryRun\"\n    ] = \"RequestResponse\",\n    tail: bool = False,\n    client_context: Optional[dict] = None,\n) -&gt; dict:\n    \"\"\"\n    [Invoke](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lambda/client/invoke.html)\n    the Lambda function with the given payload.\n\n    Args:\n        payload: The payload to send to the Lambda function.\n        invocation_type: The invocation type of the Lambda function. This\n            can be one of \"RequestResponse\", \"Event\", or \"DryRun\". Uses\n            \"RequestResponse\" by default.\n        tail: If True, the response will include the base64-encoded last 4\n            KB of log data produced by the Lambda function.\n        client_context: The client context to send to the Lambda function.\n            Limited to 3583 bytes.\n\n    Returns:\n        The response from the Lambda function.\n\n    Examples:\n\n        ```python\n        from prefect_aws.lambda_function import LambdaFunction\n        from prefect_aws.credentials import AwsCredentials\n\n        credentials = AwsCredentials()\n        lambda_function = LambdaFunction(\n            function_name=\"test_lambda_function\",\n            aws_credentials=credentials,\n        )\n        response = lambda_function.invoke(\n            payload={\"foo\": \"bar\"},\n            invocation_type=\"RequestResponse\",\n        )\n        response[\"Payload\"].read()\n        ```\n        ```txt\n        b'{\"foo\": \"bar\"}'\n        ```\n\n    \"\"\"\n    # Add invocation arguments\n    kwargs = dict(FunctionName=self.function_name)\n\n    if payload:\n        kwargs[\"Payload\"] = json.dumps(payload).encode()\n\n    # Let boto handle invalid invocation types\n    kwargs[\"InvocationType\"] = invocation_type\n\n    if self.qualifier is not None:\n        kwargs[\"Qualifier\"] = self.qualifier\n\n    if tail:\n        kwargs[\"LogType\"] = \"Tail\"\n\n    if client_context is not None:\n        # For some reason this is string, but payload is bytes\n        kwargs[\"ClientContext\"] = json.dumps(client_context)\n\n    # Get client and invoke\n    lambda_client = await run_sync_in_worker_thread(self._get_lambda_client)\n    return await run_sync_in_worker_thread(lambda_client.invoke, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/","title":"S3","text":""},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3","title":"<code>prefect_aws.s3</code>","text":"<p>Tasks for interacting with AWS S3</p>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket","title":"<code>S3Bucket</code>","text":"<p>               Bases: <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code>, <code>ObjectStorageBlock</code></p> <p>Block used to store data using AWS S3 or S3-compatible object storage like MinIO.</p> <p>Attributes:</p> Name Type Description <code>bucket_name</code> <code>str</code> <p>Name of your bucket.</p> <code>credentials</code> <code>Union[MinIOCredentials, AwsCredentials]</code> <p>A block containing your credentials to AWS or MinIO.</p> <code>bucket_folder</code> <code>str</code> <p>A default path to a folder within the S3 bucket to use for reading and writing objects.</p> Source code in <code>prefect_aws/s3.py</code> <pre><code>class S3Bucket(WritableFileSystem, WritableDeploymentStorage, ObjectStorageBlock):\n\n    \"\"\"\n    Block used to store data using AWS S3 or S3-compatible object storage like MinIO.\n\n    Attributes:\n        bucket_name: Name of your bucket.\n        credentials: A block containing your credentials to AWS or MinIO.\n        bucket_folder: A default path to a folder within the S3 bucket to use\n            for reading and writing objects.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"S3 Bucket\"\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-aws/s3/#prefect_aws.s3.S3Bucket\"  # noqa\n    )\n\n    bucket_name: str = Field(default=..., description=\"Name of your bucket.\")\n\n    credentials: Union[MinIOCredentials, AwsCredentials] = Field(\n        default_factory=AwsCredentials,\n        description=\"A block containing your credentials to AWS or MinIO.\",\n    )\n\n    bucket_folder: str = Field(\n        default=\"\",\n        description=(\n            \"A default path to a folder within the S3 bucket to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    @root_validator\n    def validate_credentials(cls, values):\n        creds = values[\"credentials\"]\n        if isinstance(creds, AwsCredentials) and isinstance(\n            creds.aws_client_parameters, dict\n        ):\n            # There's an issue with pydantic and nested blocks in a Union\n            # that is causing `aws_client_parameters` to be a dict in some\n            # cases instead of an `AwsClientParameters` object. Here we\n            # convert it to the correct type.\n            creds.aws_client_parameters = AwsClientParameters(\n                **creds.aws_client_parameters\n            )\n\n        return values\n\n    # Property to maintain compatibility with storage block based deployments\n    @property\n    def basepath(self) -&gt; str:\n        \"\"\"\n        The base path of the S3 bucket.\n\n        Returns:\n            str: The base path of the S3 bucket.\n        \"\"\"\n        return self.bucket_folder\n\n    @basepath.setter\n    def basepath(self, value: str) -&gt; None:\n        self.bucket_folder = value\n\n    def _resolve_path(self, path: str) -&gt; str:\n        \"\"\"\n        A helper function used in write_path to join `self.basepath` and `path`.\n\n        Args:\n\n            path: Name of the key, e.g. \"file1\". Each object in your\n                bucket has a unique key (or key name).\n\n        \"\"\"\n        # If bucket_folder provided, it means we won't write to the root dir of\n        # the bucket. So we need to add it on the front of the path.\n        #\n        # AWS object key naming guidelines require '/' for bucket folders.\n        # Get POSIX path to prevent `pathlib` from inferring '\\' on Windows OS\n        path = (\n            (Path(self.bucket_folder) / path).as_posix() if self.bucket_folder else path\n        )\n\n        return path\n\n    def _get_s3_client(self) -&gt; boto3.client:\n        \"\"\"\n        Authenticate MinIO credentials or AWS credentials and return an S3 client.\n        This is a helper function called by read_path() or write_path().\n        \"\"\"\n        return self.credentials.get_client(\"s3\")\n\n    def _get_bucket_resource(self) -&gt; boto3.resource:\n        \"\"\"\n        Retrieves boto3 resource object for the configured bucket\n        \"\"\"\n        params_override = self.credentials.aws_client_parameters.get_params_override()\n        bucket = (\n            self.credentials.get_boto3_session()\n            .resource(\"s3\", **params_override)\n            .Bucket(self.bucket_name)\n        )\n        return bucket\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Copies a folder from the configured S3 bucket to a local directory.\n\n        Defaults to copying the entire contents of the block's basepath to the current\n        working directory.\n\n        Args:\n            from_path: Path in S3 bucket to download from. Defaults to the block's\n                configured basepath.\n            local_path: Local path to download S3 contents to. Defaults to the current\n                working directory.\n        \"\"\"\n        bucket_folder = self.bucket_folder\n        if from_path is None:\n            from_path = str(bucket_folder) if bucket_folder else \"\"\n\n        if local_path is None:\n            local_path = str(Path(\".\").absolute())\n        else:\n            local_path = str(Path(local_path).expanduser())\n\n        bucket = self._get_bucket_resource()\n        for obj in bucket.objects.filter(Prefix=from_path):\n            if obj.key[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n            target = os.path.join(\n                local_path,\n                os.path.relpath(obj.key, from_path),\n            )\n            os.makedirs(os.path.dirname(target), exist_ok=True)\n            bucket.download_file(obj.key, target)\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to the configured S3 bucket in a\n        given folder.\n\n        Defaults to uploading the entire contents the current working directory to the\n        block's basepath.\n\n        Args:\n            local_path: Path to local directory to upload from.\n            to_path: Path in S3 bucket to upload to. Defaults to block's configured\n                basepath.\n            ignore_file: Path to file containing gitignore style expressions for\n                filepaths to ignore.\n\n        \"\"\"\n        to_path = \"\" if to_path is None else to_path\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(local_path, ignore_patterns)\n\n        uploaded_file_count = 0\n        for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(to_path) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as local_file:\n                    local_file_content = local_file.read()\n\n                await self.write_path(\n                    remote_file_path.as_posix(), content=local_file_content\n                )\n                uploaded_file_count += 1\n\n        return uploaded_file_count\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Read specified path from S3 and return contents. Provide the entire\n        path to the key in S3.\n\n        Args:\n            path: Entire path to (and including) the key.\n\n        Example:\n            Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\":\n            ```python\n            from prefect_aws import AwsCredentials\n            from prefect_aws.s3 import S3Bucket\n\n            aws_creds = AwsCredentials(\n                aws_access_key_id=AWS_ACCESS_KEY_ID,\n                aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n            )\n\n            s3_bucket_block = S3Bucket(\n                bucket_name=\"bucket\",\n                credentials=aws_creds,\n                bucket_folder=\"subfolder\"\n            )\n\n            key_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n            ```\n        \"\"\"\n        path = self._resolve_path(path)\n\n        return await run_sync_in_worker_thread(self._read_sync, path)\n\n    def _read_sync(self, key: str) -&gt; bytes:\n        \"\"\"\n        Called by read_path(). Creates an S3 client and retrieves the\n        contents from  a specified path.\n        \"\"\"\n\n        s3_client = self._get_s3_client()\n\n        with io.BytesIO() as stream:\n            s3_client.download_fileobj(Bucket=self.bucket_name, Key=key, Fileobj=stream)\n            stream.seek(0)\n            output = stream.read()\n            return output\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        \"\"\"\n        Writes to an S3 bucket.\n\n        Args:\n\n            path: The key name. Each object in your bucket has a unique\n                key (or key name).\n            content: What you are uploading to S3.\n\n        Example:\n\n            Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n            ```python\n            from prefect_aws import MinioCredentials\n            from prefect_aws.s3 import S3Bucket\n\n            minio_creds = MinIOCredentials(\n                minio_root_user = \"minioadmin\",\n                minio_root_password = \"minioadmin\",\n            )\n\n            s3_bucket_block = S3Bucket(\n                bucket_name=\"bucket\",\n                minio_credentials=minio_creds,\n                bucket_folder=\"dogs/smalldogs\",\n                endpoint_url=\"http://localhost:9000\",\n            )\n            s3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n            ```\n        \"\"\"\n\n        path = self._resolve_path(path)\n\n        await run_sync_in_worker_thread(self._write_sync, path, content)\n\n        return path\n\n    def _write_sync(self, key: str, data: bytes) -&gt; None:\n        \"\"\"\n        Called by write_path(). Creates an S3 client and uploads a file\n        object.\n        \"\"\"\n\n        s3_client = self._get_s3_client()\n\n        with io.BytesIO(data) as stream:\n            s3_client.upload_fileobj(Fileobj=stream, Bucket=self.bucket_name, Key=key)\n\n    # NEW BLOCK INTERFACE METHODS BELOW\n    @staticmethod\n    def _list_objects_sync(page_iterator: PageIterator) -&gt; List[Dict[str, Any]]:\n        \"\"\"\n        Synchronous method to collect S3 objects into a list\n\n        Args:\n            page_iterator: AWS Paginator for S3 objects\n\n        Returns:\n            List[Dict]: List of object information\n        \"\"\"\n        return [\n            content for page in page_iterator for content in page.get(\"Contents\", [])\n        ]\n\n    def _join_bucket_folder(self, bucket_path: str = \"\") -&gt; str:\n        \"\"\"\n        Joins the base bucket folder to the bucket path.\n        NOTE: If a method reuses another method in this class, be careful to not\n        call this  twice because it'll join the bucket folder twice.\n        See https://github.com/PrefectHQ/prefect-aws/issues/141 for a past issue.\n        \"\"\"\n        if not self.bucket_folder and not bucket_path:\n            # there's a difference between \".\" and \"\", at least in the tests\n            return \"\"\n\n        bucket_path = str(bucket_path)\n        if self.bucket_folder != \"\" and bucket_path.startswith(self.bucket_folder):\n            self.logger.info(\n                f\"Bucket path {bucket_path!r} is already prefixed with \"\n                f\"bucket folder {self.bucket_folder!r}; is this intentional?\"\n            )\n\n        return (Path(self.bucket_folder) / bucket_path).as_posix() + (\n            \"\" if not bucket_path.endswith(\"/\") else \"/\"\n        )\n\n    @sync_compatible\n    async def list_objects(\n        self,\n        folder: str = \"\",\n        delimiter: str = \"\",\n        page_size: Optional[int] = None,\n        max_items: Optional[int] = None,\n        jmespath_query: Optional[str] = None,\n    ) -&gt; List[Dict[str, Any]]:\n        \"\"\"\n        Args:\n            folder: Folder to list objects from.\n            delimiter: Character used to group keys of listed objects.\n            page_size: Number of objects to return in each request to the AWS API.\n            max_items: Maximum number of objects that to be returned by task.\n            jmespath_query: Query used to filter objects based on object attributes refer to\n                the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n                for more information on how to construct queries.\n\n        Returns:\n            List of objects and their metadata in the bucket.\n\n        Examples:\n            List objects under the `base_folder`.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.list_objects(\"base_folder\")\n            ```\n        \"\"\"  # noqa: E501\n        bucket_path = self._join_bucket_folder(folder)\n        client = self.credentials.get_s3_client()\n        paginator = client.get_paginator(\"list_objects_v2\")\n        page_iterator = paginator.paginate(\n            Bucket=self.bucket_name,\n            Prefix=bucket_path,\n            Delimiter=delimiter,\n            PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n        )\n        if jmespath_query:\n            page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n        self.logger.info(f\"Listing objects in bucket {bucket_path}.\")\n        objects = await run_sync_in_worker_thread(\n            self._list_objects_sync, page_iterator\n        )\n        return objects\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Optional[Union[str, Path]],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads an object from the S3 bucket to a path.\n\n        Args:\n            from_path: The path to the object to download; this gets prefixed\n                with the bucket_folder.\n            to_path: The path to download the object to. If not provided, the\n                object's name will be used.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_file`.\n\n        Returns:\n            The absolute path that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # making path absolute, but converting back to str here\n        # since !r looks nicer that way and filename arg expects str\n        to_path = str(Path(to_path).absolute())\n        bucket_path = self._join_bucket_folder(from_path)\n        client = self.credentials.get_s3_client()\n\n        self.logger.debug(\n            f\"Preparing to download object from bucket {self.bucket_name!r} \"\n            f\"path {bucket_path!r} to {to_path!r}.\"\n        )\n        await run_sync_in_worker_thread(\n            client.download_file,\n            Bucket=self.bucket_name,\n            Key=from_path,\n            Filename=to_path,\n            **download_kwargs,\n        )\n        self.logger.info(\n            f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n            f\"to {to_path!r}.\"\n        )\n        return Path(to_path)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; BinaryIO:\n        \"\"\"\n        Downloads an object from the object storage service to a file-like object,\n        which can be a BytesIO object or a BufferedWriter.\n\n        Args:\n            from_path: The path to the object to download from; this gets prefixed\n                with the bucket_folder.\n            to_file_object: The file-like object to download the object to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_fileobj`.\n\n        Returns:\n            The file-like object that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with BytesIO() as buf:\n                s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n            ```\n\n            Download my_folder/notes.txt object to a BufferedWriter.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"wb\") as f:\n                s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n            ```\n        \"\"\"\n        client = self.credentials.get_s3_client()\n        bucket_path = self._join_bucket_folder(from_path)\n\n        self.logger.debug(\n            f\"Preparing to download object from bucket {self.bucket_name!r} \"\n            f\"path {bucket_path!r} to file object.\"\n        )\n        await run_sync_in_worker_thread(\n            client.download_fileobj,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            Fileobj=to_file_object,\n            **download_kwargs,\n        )\n        self.logger.info(\n            f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n            \"to file object.\"\n        )\n        return to_file_object\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads objects *within* a folder (excluding the folder itself)\n        from the S3 bucket to a folder.\n\n        Args:\n            from_folder: The path to the folder to download from.\n            to_folder: The path to download the folder to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Client.download_file`.\n\n        Returns:\n            The absolute path that the folder was downloaded to.\n\n        Examples:\n            Download my_folder to a local folder named my_folder.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n            ```\n        \"\"\"\n        if to_folder is None:\n            to_folder = \"\"\n        to_folder = Path(to_folder).absolute()\n\n        client = self.credentials.get_s3_client()\n        objects = await self.list_objects(folder=from_folder)\n\n        # do not call self._join_bucket_folder for filter\n        # because it's built-in to that method already!\n        # however, we still need to do it because we're using relative_to\n        bucket_folder = self._join_bucket_folder(from_folder)\n\n        async_coros = []\n        for object in objects:\n            bucket_path = Path(object[\"Key\"]).relative_to(bucket_folder)\n            # this skips the actual directory itself, e.g.\n            # `my_folder/` will be skipped\n            # `my_folder/notes.txt` will be downloaded\n            if bucket_path.is_dir():\n                continue\n            to_path = to_folder / bucket_path\n            to_path.parent.mkdir(parents=True, exist_ok=True)\n            to_path = str(to_path)  # must be string\n            self.logger.info(\n                f\"Downloading object from bucket {self.bucket_name!r} path \"\n                f\"{bucket_path.as_posix()!r} to {to_path!r}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    client.download_file,\n                    Bucket=self.bucket_name,\n                    Key=object[\"Key\"],\n                    Filename=to_path,\n                    **download_kwargs,\n                )\n            )\n        await asyncio.gather(*async_coros)\n\n        return Path(to_folder)\n\n    @sync_compatible\n    async def stream_from(\n        self,\n        bucket: \"S3Bucket\",\n        from_path: str,\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"Streams an object from another bucket to this bucket. Requires the\n        object to be downloaded and uploaded in chunks. If `self`'s credentials\n        allow for writes to the other bucket, try using `S3Bucket.copy_object`.\n\n        Args:\n            bucket: The bucket to stream from.\n            from_path: The path of the object to stream.\n            to_path: The path to stream the object to. Defaults to the object's name.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            your_s3_bucket = S3Bucket.load(\"your-bucket\")\n            my_s3_bucket = S3Bucket.load(\"my-bucket\")\n\n            my_s3_bucket.stream_from(\n                your_s3_bucket,\n                \"notes.txt\",\n                to_path=\"landed/notes.txt\"\n            )\n            ```\n\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # Get the source object's StreamingBody\n        from_path: str = bucket._join_bucket_folder(from_path)\n        from_client = bucket.credentials.get_s3_client()\n        obj = await run_sync_in_worker_thread(\n            from_client.get_object, Bucket=bucket.bucket_name, Key=from_path\n        )\n        body: StreamingBody = obj[\"Body\"]\n\n        # Upload the StreamingBody to this bucket\n        bucket_path = str(self._join_bucket_folder(to_path))\n        to_client = self.credentials.get_s3_client()\n        await run_sync_in_worker_thread(\n            to_client.upload_fileobj,\n            Fileobj=body,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            f\"Streamed s3://{bucket.bucket_name}/{from_path} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_path(\n        self,\n        from_path: Union[str, Path],\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object from a path to the S3 bucket.\n\n        Args:\n            from_path: The path to the file to upload from.\n            to_path: The path to upload the file to.\n            **upload_kwargs: Additional keyword arguments to pass to `Client.upload`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload notes.txt to my_folder/notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n            ```\n        \"\"\"\n        from_path = str(Path(from_path).absolute())\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        bucket_path = str(self._join_bucket_folder(to_path))\n        client = self.credentials.get_s3_client()\n\n        await run_sync_in_worker_thread(\n            client.upload_file,\n            Filename=from_path,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            f\"Uploaded from {from_path!r} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object to the S3 bucket from a file-like object,\n        which can be a BytesIO object or a BufferedReader.\n\n        Args:\n            from_file_object: The file-like object to upload from.\n            to_path: The path to upload the object to.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload BytesIO object to my_folder/notes.txt.\n            ```python\n            from io import BytesIO\n\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n            ```\n\n            Upload BufferedReader object to my_folder/notes.txt.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                s3_bucket.upload_from_file_object(\n                    f, \"my_folder/notes.txt\"\n                )\n            ```\n        \"\"\"\n        bucket_path = str(self._join_bucket_folder(to_path))\n        client = self.credentials.get_s3_client()\n        await run_sync_in_worker_thread(\n            client.upload_fileobj,\n            Fileobj=from_file_object,\n            Bucket=self.bucket_name,\n            Key=bucket_path,\n            **upload_kwargs,\n        )\n        self.logger.info(\n            \"Uploaded from file object to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads files *within* a folder (excluding the folder itself)\n        to the object storage service folder.\n\n        Args:\n            from_folder: The path to the folder to upload from.\n            to_folder: The path to upload the folder to.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Client.upload_fileobj`.\n\n        Returns:\n            The path that the folder was uploaded to.\n\n        Examples:\n            Upload contents from my_folder to new_folder.\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n            ```\n        \"\"\"\n        from_folder = Path(from_folder)\n        bucket_folder = self._join_bucket_folder(to_folder or \"\")\n\n        num_uploaded = 0\n        client = self.credentials.get_s3_client()\n\n        async_coros = []\n        for from_path in from_folder.rglob(\"**/*\"):\n            # this skips the actual directory itself, e.g.\n            # `my_folder/` will be skipped\n            # `my_folder/notes.txt` will be uploaded\n            if from_path.is_dir():\n                continue\n            bucket_path = (\n                Path(bucket_folder) / from_path.relative_to(from_folder)\n            ).as_posix()\n            self.logger.info(\n                f\"Uploading from {str(from_path)!r} to the bucket \"\n                f\"{self.bucket_name!r} path {bucket_path!r}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    client.upload_file,\n                    Filename=str(from_path),\n                    Bucket=self.bucket_name,\n                    Key=bucket_path,\n                    **upload_kwargs,\n                )\n            )\n            num_uploaded += 1\n        await asyncio.gather(*async_coros)\n\n        if num_uploaded == 0:\n            self.logger.warning(f\"No files were uploaded from {str(from_folder)!r}.\")\n        else:\n            self.logger.info(\n                f\"Uploaded {num_uploaded} files from {str(from_folder)!r} to \"\n                f\"the bucket {self.bucket_name!r} path {bucket_path!r}\"\n            )\n\n        return to_folder\n\n    @sync_compatible\n    async def copy_object(\n        self,\n        from_path: Union[str, Path],\n        to_path: Union[str, Path],\n        to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n        **copy_kwargs,\n    ) -&gt; str:\n        \"\"\"Uses S3's internal\n        [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n        to copy objects within or between buckets. To copy objects between buckets,\n        `self`'s credentials must have permission to read the source object and write\n        to the target object. If the credentials do not have those permissions, try\n        using `S3Bucket.stream_from`.\n\n        Args:\n            from_path: The path of the object to copy.\n            to_path: The path to copy the object to.\n            to_bucket: The bucket to copy to. Defaults to the current bucket.\n            **copy_kwargs: Additional keyword arguments to pass to\n                `S3Client.copy_object`.\n\n        Returns:\n            The path that the object was copied to. Excludes the bucket name.\n\n        Examples:\n\n            Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n            ```\n\n            Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n            another bucket.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.copy_object(\n                \"my_folder/notes.txt\",\n                \"my_folder/notes_copy.txt\",\n                to_bucket=\"other-bucket\"\n            )\n            ```\n        \"\"\"\n        s3_client = self.credentials.get_s3_client()\n\n        source_bucket_name = self.bucket_name\n        source_path = self._resolve_path(Path(from_path).as_posix())\n\n        # Default to copying within the same bucket\n        to_bucket = to_bucket or self\n\n        target_bucket_name: str\n        target_path: str\n        if isinstance(to_bucket, S3Bucket):\n            target_bucket_name = to_bucket.bucket_name\n            target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n        elif isinstance(to_bucket, str):\n            target_bucket_name = to_bucket\n            target_path = Path(to_path).as_posix()\n        else:\n            raise TypeError(\n                f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n            )\n\n        self.logger.info(\n            \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n            source_bucket_name,\n            source_path,\n            target_bucket_name,\n            target_path,\n        )\n\n        s3_client.copy_object(\n            CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n            Bucket=target_bucket_name,\n            Key=target_path,\n            **copy_kwargs,\n        )\n\n        return target_path\n\n    @sync_compatible\n    async def move_object(\n        self,\n        from_path: Union[str, Path],\n        to_path: Union[str, Path],\n        to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n    ) -&gt; str:\n        \"\"\"Uses S3's internal CopyObject and DeleteObject to move objects within or\n        between buckets. To move objects between buckets, `self`'s credentials must\n        have permission to read and delete the source object and write to the target\n        object. If the credentials do not have those permissions, this method will\n        raise an error. If the credentials have permission to read the source object\n        but not delete it, the object will be copied but not deleted.\n\n        Args:\n            from_path: The path of the object to move.\n            to_path: The path to move the object to.\n            to_bucket: The bucket to move to. Defaults to the current bucket.\n\n        Returns:\n            The path that the object was moved to. Excludes the bucket name.\n\n        Examples:\n\n            Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n            ```\n\n            Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n            another bucket.\n\n            ```python\n            from prefect_aws.s3 import S3Bucket\n\n            s3_bucket = S3Bucket.load(\"my-bucket\")\n            s3_bucket.move_object(\n                \"my_folder/notes.txt\",\n                \"my_folder/notes_copy.txt\",\n                to_bucket=\"other-bucket\"\n            )\n            ```\n        \"\"\"\n        s3_client = self.credentials.get_s3_client()\n\n        source_bucket_name = self.bucket_name\n        source_path = self._resolve_path(Path(from_path).as_posix())\n\n        # Default to moving within the same bucket\n        to_bucket = to_bucket or self\n\n        target_bucket_name: str\n        target_path: str\n        if isinstance(to_bucket, S3Bucket):\n            target_bucket_name = to_bucket.bucket_name\n            target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n        elif isinstance(to_bucket, str):\n            target_bucket_name = to_bucket\n            target_path = Path(to_path).as_posix()\n        else:\n            raise TypeError(\n                f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n            )\n\n        self.logger.info(\n            \"Moving object from s3://%s/%s to s3://%s/%s\",\n            source_bucket_name,\n            source_path,\n            target_bucket_name,\n            target_path,\n        )\n\n        # If invalid, should error and prevent next operation\n        s3_client.copy(\n            CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n            Bucket=target_bucket_name,\n            Key=target_path,\n        )\n        s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n        return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.basepath","title":"<code>basepath: str</code>  <code>property</code> <code>writable</code>","text":"<p>The base path of the S3 bucket.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The base path of the S3 bucket.</p>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.copy_object","title":"<code>copy_object</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject to copy objects within or between buckets. To copy objects between buckets, <code>self</code>'s credentials must have permission to read the source object and write to the target object. If the credentials do not have those permissions, try using <code>S3Bucket.stream_from</code>.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path of the object to copy.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path to copy the object to.</p> required <code>to_bucket</code> <code>Optional[Union[S3Bucket, str]]</code> <p>The bucket to copy to. Defaults to the current bucket.</p> <code>None</code> <code>**copy_kwargs</code> <p>Additional keyword arguments to pass to <code>S3Client.copy_object</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was copied to. Excludes the bucket name.</p> <pre><code>Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n```\n\nCopy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\nanother bucket.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.copy_object(\n    \"my_folder/notes.txt\",\n    \"my_folder/notes_copy.txt\",\n    to_bucket=\"other-bucket\"\n)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def copy_object(\n    self,\n    from_path: Union[str, Path],\n    to_path: Union[str, Path],\n    to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n    **copy_kwargs,\n) -&gt; str:\n    \"\"\"Uses S3's internal\n    [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n    to copy objects within or between buckets. To copy objects between buckets,\n    `self`'s credentials must have permission to read the source object and write\n    to the target object. If the credentials do not have those permissions, try\n    using `S3Bucket.stream_from`.\n\n    Args:\n        from_path: The path of the object to copy.\n        to_path: The path to copy the object to.\n        to_bucket: The bucket to copy to. Defaults to the current bucket.\n        **copy_kwargs: Additional keyword arguments to pass to\n            `S3Client.copy_object`.\n\n    Returns:\n        The path that the object was copied to. Excludes the bucket name.\n\n    Examples:\n\n        Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.copy_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n        ```\n\n        Copy notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n        another bucket.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.copy_object(\n            \"my_folder/notes.txt\",\n            \"my_folder/notes_copy.txt\",\n            to_bucket=\"other-bucket\"\n        )\n        ```\n    \"\"\"\n    s3_client = self.credentials.get_s3_client()\n\n    source_bucket_name = self.bucket_name\n    source_path = self._resolve_path(Path(from_path).as_posix())\n\n    # Default to copying within the same bucket\n    to_bucket = to_bucket or self\n\n    target_bucket_name: str\n    target_path: str\n    if isinstance(to_bucket, S3Bucket):\n        target_bucket_name = to_bucket.bucket_name\n        target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n    elif isinstance(to_bucket, str):\n        target_bucket_name = to_bucket\n        target_path = Path(to_path).as_posix()\n    else:\n        raise TypeError(\n            f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n        )\n\n    self.logger.info(\n        \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    s3_client.copy_object(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n        **copy_kwargs,\n    )\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Downloads objects within a folder (excluding the folder itself) from the S3 bucket to a folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The path to the folder to download from.</p> required <code>to_folder</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the folder to.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the folder was downloaded to.</p> <p>Examples:</p> <p>Download my_folder to a local folder named my_folder. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads objects *within* a folder (excluding the folder itself)\n    from the S3 bucket to a folder.\n\n    Args:\n        from_folder: The path to the folder to download from.\n        to_folder: The path to download the folder to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_file`.\n\n    Returns:\n        The absolute path that the folder was downloaded to.\n\n    Examples:\n        Download my_folder to a local folder named my_folder.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n        ```\n    \"\"\"\n    if to_folder is None:\n        to_folder = \"\"\n    to_folder = Path(to_folder).absolute()\n\n    client = self.credentials.get_s3_client()\n    objects = await self.list_objects(folder=from_folder)\n\n    # do not call self._join_bucket_folder for filter\n    # because it's built-in to that method already!\n    # however, we still need to do it because we're using relative_to\n    bucket_folder = self._join_bucket_folder(from_folder)\n\n    async_coros = []\n    for object in objects:\n        bucket_path = Path(object[\"Key\"]).relative_to(bucket_folder)\n        # this skips the actual directory itself, e.g.\n        # `my_folder/` will be skipped\n        # `my_folder/notes.txt` will be downloaded\n        if bucket_path.is_dir():\n            continue\n        to_path = to_folder / bucket_path\n        to_path.parent.mkdir(parents=True, exist_ok=True)\n        to_path = str(to_path)  # must be string\n        self.logger.info(\n            f\"Downloading object from bucket {self.bucket_name!r} path \"\n            f\"{bucket_path.as_posix()!r} to {to_path!r}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                client.download_file,\n                Bucket=self.bucket_name,\n                Key=object[\"Key\"],\n                Filename=to_path,\n                **download_kwargs,\n            )\n        )\n    await asyncio.gather(*async_coros)\n\n    return Path(to_folder)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a file-like object, which can be a BytesIO object or a BufferedWriter.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the object to download from; this gets prefixed with the bucket_folder.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file-like object to download the object to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BinaryIO</code> <p>The file-like object that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\n\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith BytesIO() as buf:\n    s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n</code></pre></p> <p>Download my_folder/notes.txt object to a BufferedWriter. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"wb\") as f:\n    s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; BinaryIO:\n    \"\"\"\n    Downloads an object from the object storage service to a file-like object,\n    which can be a BytesIO object or a BufferedWriter.\n\n    Args:\n        from_path: The path to the object to download from; this gets prefixed\n            with the bucket_folder.\n        to_file_object: The file-like object to download the object to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_fileobj`.\n\n    Returns:\n        The file-like object that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with BytesIO() as buf:\n            s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n        ```\n\n        Download my_folder/notes.txt object to a BufferedWriter.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"wb\") as f:\n            s3_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n        ```\n    \"\"\"\n    client = self.credentials.get_s3_client()\n    bucket_path = self._join_bucket_folder(from_path)\n\n    self.logger.debug(\n        f\"Preparing to download object from bucket {self.bucket_name!r} \"\n        f\"path {bucket_path!r} to file object.\"\n    )\n    await run_sync_in_worker_thread(\n        client.download_fileobj,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        Fileobj=to_file_object,\n        **download_kwargs,\n    )\n    self.logger.info(\n        f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n        \"to file object.\"\n    )\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from the S3 bucket to a path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the object to download; this gets prefixed with the bucket_folder.</p> required <code>to_path</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the object to. If not provided, the object's name will be used.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.download_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Optional[Union[str, Path]],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads an object from the S3 bucket to a path.\n\n    Args:\n        from_path: The path to the object to download; this gets prefixed\n            with the bucket_folder.\n        to_path: The path to download the object to. If not provided, the\n            object's name will be used.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Client.download_file`.\n\n    Returns:\n        The absolute path that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # making path absolute, but converting back to str here\n    # since !r looks nicer that way and filename arg expects str\n    to_path = str(Path(to_path).absolute())\n    bucket_path = self._join_bucket_folder(from_path)\n    client = self.credentials.get_s3_client()\n\n    self.logger.debug(\n        f\"Preparing to download object from bucket {self.bucket_name!r} \"\n        f\"path {bucket_path!r} to {to_path!r}.\"\n    )\n    await run_sync_in_worker_thread(\n        client.download_file,\n        Bucket=self.bucket_name,\n        Key=from_path,\n        Filename=to_path,\n        **download_kwargs,\n    )\n    self.logger.info(\n        f\"Downloaded object from bucket {self.bucket_name!r} path {bucket_path!r} \"\n        f\"to {to_path!r}.\"\n    )\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a folder from the configured S3 bucket to a local directory.</p> <p>Defaults to copying the entire contents of the block's basepath to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>Path in S3 bucket to download from. Defaults to the block's configured basepath.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>Local path to download S3 contents to. Defaults to the current working directory.</p> <code>None</code> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Copies a folder from the configured S3 bucket to a local directory.\n\n    Defaults to copying the entire contents of the block's basepath to the current\n    working directory.\n\n    Args:\n        from_path: Path in S3 bucket to download from. Defaults to the block's\n            configured basepath.\n        local_path: Local path to download S3 contents to. Defaults to the current\n            working directory.\n    \"\"\"\n    bucket_folder = self.bucket_folder\n    if from_path is None:\n        from_path = str(bucket_folder) if bucket_folder else \"\"\n\n    if local_path is None:\n        local_path = str(Path(\".\").absolute())\n    else:\n        local_path = str(Path(local_path).expanduser())\n\n    bucket = self._get_bucket_resource()\n    for obj in bucket.objects.filter(Prefix=from_path):\n        if obj.key[-1] == \"/\":\n            # object is a folder and will be created if it contains any objects\n            continue\n        target = os.path.join(\n            local_path,\n            os.path.relpath(obj.key, from_path),\n        )\n        os.makedirs(os.path.dirname(target), exist_ok=True)\n        bucket.download_file(obj.key, target)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.list_objects","title":"<code>list_objects</code>  <code>async</code>","text":"<p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>Folder to list objects from.</p> <code>''</code> <code>delimiter</code> <code>str</code> <p>Character used to group keys of listed objects.</p> <code>''</code> <code>page_size</code> <code>Optional[int]</code> <p>Number of objects to return in each request to the AWS API.</p> <code>None</code> <code>max_items</code> <code>Optional[int]</code> <p>Maximum number of objects that to be returned by task.</p> <code>None</code> <code>jmespath_query</code> <code>Optional[str]</code> <p>Query used to filter objects based on object attributes refer to the boto3 docs for more information on how to construct queries.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Dict[str, Any]]</code> <p>List of objects and their metadata in the bucket.</p> <p>Examples:</p> <p>List objects under the <code>base_folder</code>. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.list_objects(\"base_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def list_objects(\n    self,\n    folder: str = \"\",\n    delimiter: str = \"\",\n    page_size: Optional[int] = None,\n    max_items: Optional[int] = None,\n    jmespath_query: Optional[str] = None,\n) -&gt; List[Dict[str, Any]]:\n    \"\"\"\n    Args:\n        folder: Folder to list objects from.\n        delimiter: Character used to group keys of listed objects.\n        page_size: Number of objects to return in each request to the AWS API.\n        max_items: Maximum number of objects that to be returned by task.\n        jmespath_query: Query used to filter objects based on object attributes refer to\n            the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n            for more information on how to construct queries.\n\n    Returns:\n        List of objects and their metadata in the bucket.\n\n    Examples:\n        List objects under the `base_folder`.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.list_objects(\"base_folder\")\n        ```\n    \"\"\"  # noqa: E501\n    bucket_path = self._join_bucket_folder(folder)\n    client = self.credentials.get_s3_client()\n    paginator = client.get_paginator(\"list_objects_v2\")\n    page_iterator = paginator.paginate(\n        Bucket=self.bucket_name,\n        Prefix=bucket_path,\n        Delimiter=delimiter,\n        PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n    )\n    if jmespath_query:\n        page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n    self.logger.info(f\"Listing objects in bucket {bucket_path}.\")\n    objects = await run_sync_in_worker_thread(\n        self._list_objects_sync, page_iterator\n    )\n    return objects\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.move_object","title":"<code>move_object</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject and DeleteObject to move objects within or between buckets. To move objects between buckets, <code>self</code>'s credentials must have permission to read and delete the source object and write to the target object. If the credentials do not have those permissions, this method will raise an error. If the credentials have permission to read the source object but not delete it, the object will be copied but not deleted.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path of the object to move.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path to move the object to.</p> required <code>to_bucket</code> <code>Optional[Union[S3Bucket, str]]</code> <p>The bucket to move to. Defaults to the current bucket.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was moved to. Excludes the bucket name.</p> <pre><code>Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n```\n\nMove notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\nanother bucket.\n\n```python\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.move_object(\n    \"my_folder/notes.txt\",\n    \"my_folder/notes_copy.txt\",\n    to_bucket=\"other-bucket\"\n)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def move_object(\n    self,\n    from_path: Union[str, Path],\n    to_path: Union[str, Path],\n    to_bucket: Optional[Union[\"S3Bucket\", str]] = None,\n) -&gt; str:\n    \"\"\"Uses S3's internal CopyObject and DeleteObject to move objects within or\n    between buckets. To move objects between buckets, `self`'s credentials must\n    have permission to read and delete the source object and write to the target\n    object. If the credentials do not have those permissions, this method will\n    raise an error. If the credentials have permission to read the source object\n    but not delete it, the object will be copied but not deleted.\n\n    Args:\n        from_path: The path of the object to move.\n        to_path: The path to move the object to.\n        to_bucket: The bucket to move to. Defaults to the current bucket.\n\n    Returns:\n        The path that the object was moved to. Excludes the bucket name.\n\n    Examples:\n\n        Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.move_object(\"my_folder/notes.txt\", \"my_folder/notes_copy.txt\")\n        ```\n\n        Move notes.txt from my_folder/notes.txt to my_folder/notes_copy.txt in\n        another bucket.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.move_object(\n            \"my_folder/notes.txt\",\n            \"my_folder/notes_copy.txt\",\n            to_bucket=\"other-bucket\"\n        )\n        ```\n    \"\"\"\n    s3_client = self.credentials.get_s3_client()\n\n    source_bucket_name = self.bucket_name\n    source_path = self._resolve_path(Path(from_path).as_posix())\n\n    # Default to moving within the same bucket\n    to_bucket = to_bucket or self\n\n    target_bucket_name: str\n    target_path: str\n    if isinstance(to_bucket, S3Bucket):\n        target_bucket_name = to_bucket.bucket_name\n        target_path = to_bucket._resolve_path(Path(to_path).as_posix())\n    elif isinstance(to_bucket, str):\n        target_bucket_name = to_bucket\n        target_path = Path(to_path).as_posix()\n    else:\n        raise TypeError(\n            f\"to_bucket must be a string or S3Bucket, not {type(to_bucket)}\"\n        )\n\n    self.logger.info(\n        \"Moving object from s3://%s/%s to s3://%s/%s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    # If invalid, should error and prevent next operation\n    s3_client.copy(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n    )\n    s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to the configured S3 bucket in a given folder.</p> <p>Defaults to uploading the entire contents the current working directory to the block's basepath.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>Optional[str]</code> <p>Path to local directory to upload from.</p> <code>None</code> <code>to_path</code> <code>Optional[str]</code> <p>Path in S3 bucket to upload to. Defaults to block's configured basepath.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>Path to file containing gitignore style expressions for filepaths to ignore.</p> <code>None</code> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to the configured S3 bucket in a\n    given folder.\n\n    Defaults to uploading the entire contents the current working directory to the\n    block's basepath.\n\n    Args:\n        local_path: Path to local directory to upload from.\n        to_path: Path in S3 bucket to upload to. Defaults to block's configured\n            basepath.\n        ignore_file: Path to file containing gitignore style expressions for\n            filepaths to ignore.\n\n    \"\"\"\n    to_path = \"\" if to_path is None else to_path\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(local_path, ignore_patterns)\n\n    uploaded_file_count = 0\n    for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(to_path) / local_file_path.relative_to(\n                local_path\n            )\n            with open(local_file_path, \"rb\") as local_file:\n                local_file_content = local_file.read()\n\n            await self.write_path(\n                remote_file_path.as_posix(), content=local_file_content\n            )\n            uploaded_file_count += 1\n\n    return uploaded_file_count\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Read specified path from S3 and return contents. Provide the entire path to the key in S3.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Entire path to (and including) the key.</p> required Example <p>Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\": <pre><code>from prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import S3Bucket\n\naws_creds = AwsCredentials(\n    aws_access_key_id=AWS_ACCESS_KEY_ID,\n    aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n)\n\ns3_bucket_block = S3Bucket(\n    bucket_name=\"bucket\",\n    credentials=aws_creds,\n    bucket_folder=\"subfolder\"\n)\n\nkey_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Read specified path from S3 and return contents. Provide the entire\n    path to the key in S3.\n\n    Args:\n        path: Entire path to (and including) the key.\n\n    Example:\n        Read \"subfolder/file1\" contents from an S3 bucket named \"bucket\":\n        ```python\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import S3Bucket\n\n        aws_creds = AwsCredentials(\n            aws_access_key_id=AWS_ACCESS_KEY_ID,\n            aws_secret_access_key=AWS_SECRET_ACCESS_KEY\n        )\n\n        s3_bucket_block = S3Bucket(\n            bucket_name=\"bucket\",\n            credentials=aws_creds,\n            bucket_folder=\"subfolder\"\n        )\n\n        key_contents = s3_bucket_block.read_path(path=\"subfolder/file1\")\n        ```\n    \"\"\"\n    path = self._resolve_path(path)\n\n    return await run_sync_in_worker_thread(self._read_sync, path)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.stream_from","title":"<code>stream_from</code>  <code>async</code>","text":"<p>Streams an object from another bucket to this bucket. Requires the object to be downloaded and uploaded in chunks. If <code>self</code>'s credentials allow for writes to the other bucket, try using <code>S3Bucket.copy_object</code>.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>S3Bucket</code> <p>The bucket to stream from.</p> required <code>from_path</code> <code>str</code> <p>The path of the object to stream.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to stream the object to. Defaults to the object's name.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.</p> <pre><code>from prefect_aws.s3 import S3Bucket\n\nyour_s3_bucket = S3Bucket.load(\"your-bucket\")\nmy_s3_bucket = S3Bucket.load(\"my-bucket\")\n\nmy_s3_bucket.stream_from(\n    your_s3_bucket,\n    \"notes.txt\",\n    to_path=\"landed/notes.txt\"\n)\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def stream_from(\n    self,\n    bucket: \"S3Bucket\",\n    from_path: str,\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"Streams an object from another bucket to this bucket. Requires the\n    object to be downloaded and uploaded in chunks. If `self`'s credentials\n    allow for writes to the other bucket, try using `S3Bucket.copy_object`.\n\n    Args:\n        bucket: The bucket to stream from.\n        from_path: The path of the object to stream.\n        to_path: The path to stream the object to. Defaults to the object's name.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Stream notes.txt from your-bucket/notes.txt to my-bucket/landed/notes.txt.\n\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        your_s3_bucket = S3Bucket.load(\"your-bucket\")\n        my_s3_bucket = S3Bucket.load(\"my-bucket\")\n\n        my_s3_bucket.stream_from(\n            your_s3_bucket,\n            \"notes.txt\",\n            to_path=\"landed/notes.txt\"\n        )\n        ```\n\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # Get the source object's StreamingBody\n    from_path: str = bucket._join_bucket_folder(from_path)\n    from_client = bucket.credentials.get_s3_client()\n    obj = await run_sync_in_worker_thread(\n        from_client.get_object, Bucket=bucket.bucket_name, Key=from_path\n    )\n    body: StreamingBody = obj[\"Body\"]\n\n    # Upload the StreamingBody to this bucket\n    bucket_path = str(self._join_bucket_folder(to_path))\n    to_client = self.credentials.get_s3_client()\n    await run_sync_in_worker_thread(\n        to_client.upload_fileobj,\n        Fileobj=body,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        f\"Streamed s3://{bucket.bucket_name}/{from_path} to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object to the S3 bucket from a file-like object, which can be a BytesIO object or a BufferedReader.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file-like object to upload from.</p> required <code>to_path</code> <code>str</code> <p>The path to upload the object to.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload BytesIO object to my_folder/notes.txt. <pre><code>from io import BytesIO\n\nfrom prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n</code></pre></p> <p>Upload BufferedReader object to my_folder/notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    s3_bucket.upload_from_file_object(\n        f, \"my_folder/notes.txt\"\n    )\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; str:\n    \"\"\"\n    Uploads an object to the S3 bucket from a file-like object,\n    which can be a BytesIO object or a BufferedReader.\n\n    Args:\n        from_file_object: The file-like object to upload from.\n        to_path: The path to upload the object to.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload BytesIO object to my_folder/notes.txt.\n        ```python\n        from io import BytesIO\n\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            s3_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n        ```\n\n        Upload BufferedReader object to my_folder/notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            s3_bucket.upload_from_file_object(\n                f, \"my_folder/notes.txt\"\n            )\n        ```\n    \"\"\"\n    bucket_path = str(self._join_bucket_folder(to_path))\n    client = self.credentials.get_s3_client()\n    await run_sync_in_worker_thread(\n        client.upload_fileobj,\n        Fileobj=from_file_object,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        \"Uploaded from file object to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files within a folder (excluding the folder itself) to the object storage service folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the folder to upload from.</p> required <code>to_folder</code> <code>Optional[str]</code> <p>The path to upload the folder to.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload_fileobj</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the folder was uploaded to.</p> <p>Examples:</p> <p>Upload contents from my_folder to new_folder. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads files *within* a folder (excluding the folder itself)\n    to the object storage service folder.\n\n    Args:\n        from_folder: The path to the folder to upload from.\n        to_folder: The path to upload the folder to.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Client.upload_fileobj`.\n\n    Returns:\n        The path that the folder was uploaded to.\n\n    Examples:\n        Upload contents from my_folder to new_folder.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.upload_from_folder(\"my_folder\", \"new_folder\")\n        ```\n    \"\"\"\n    from_folder = Path(from_folder)\n    bucket_folder = self._join_bucket_folder(to_folder or \"\")\n\n    num_uploaded = 0\n    client = self.credentials.get_s3_client()\n\n    async_coros = []\n    for from_path in from_folder.rglob(\"**/*\"):\n        # this skips the actual directory itself, e.g.\n        # `my_folder/` will be skipped\n        # `my_folder/notes.txt` will be uploaded\n        if from_path.is_dir():\n            continue\n        bucket_path = (\n            Path(bucket_folder) / from_path.relative_to(from_folder)\n        ).as_posix()\n        self.logger.info(\n            f\"Uploading from {str(from_path)!r} to the bucket \"\n            f\"{self.bucket_name!r} path {bucket_path!r}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                client.upload_file,\n                Filename=str(from_path),\n                Bucket=self.bucket_name,\n                Key=bucket_path,\n                **upload_kwargs,\n            )\n        )\n        num_uploaded += 1\n    await asyncio.gather(*async_coros)\n\n    if num_uploaded == 0:\n        self.logger.warning(f\"No files were uploaded from {str(from_folder)!r}.\")\n    else:\n        self.logger.info(\n            f\"Uploaded {num_uploaded} files from {str(from_folder)!r} to \"\n            f\"the bucket {self.bucket_name!r} path {bucket_path!r}\"\n        )\n\n    return to_folder\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a path to the S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path to the file to upload from.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to upload the file to.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Client.upload</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload notes.txt to my_folder/notes.txt. <pre><code>from prefect_aws.s3 import S3Bucket\n\ns3_bucket = S3Bucket.load(\"my-bucket\")\ns3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n</code></pre></p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self,\n    from_path: Union[str, Path],\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads an object from a path to the S3 bucket.\n\n    Args:\n        from_path: The path to the file to upload from.\n        to_path: The path to upload the file to.\n        **upload_kwargs: Additional keyword arguments to pass to `Client.upload`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload notes.txt to my_folder/notes.txt.\n        ```python\n        from prefect_aws.s3 import S3Bucket\n\n        s3_bucket = S3Bucket.load(\"my-bucket\")\n        s3_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n        ```\n    \"\"\"\n    from_path = str(Path(from_path).absolute())\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    bucket_path = str(self._join_bucket_folder(to_path))\n    client = self.credentials.get_s3_client()\n\n    await run_sync_in_worker_thread(\n        client.upload_file,\n        Filename=from_path,\n        Bucket=self.bucket_name,\n        Key=bucket_path,\n        **upload_kwargs,\n    )\n    self.logger.info(\n        f\"Uploaded from {from_path!r} to the bucket \"\n        f\"{self.bucket_name!r} path {bucket_path!r}.\"\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.S3Bucket.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes to an S3 bucket.</p> <p>Args:</p> <pre><code>path: The key name. Each object in your bucket has a unique\n    key (or key name).\ncontent: What you are uploading to S3.\n</code></pre> <p>Example:</p> <pre><code>Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n```python\nfrom prefect_aws import MinioCredentials\nfrom prefect_aws.s3 import S3Bucket\n\nminio_creds = MinIOCredentials(\n    minio_root_user = \"minioadmin\",\n    minio_root_password = \"minioadmin\",\n)\n\ns3_bucket_block = S3Bucket(\n    bucket_name=\"bucket\",\n    minio_credentials=minio_creds,\n    bucket_folder=\"dogs/smalldogs\",\n    endpoint_url=\"http://localhost:9000\",\n)\ns3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; str:\n    \"\"\"\n    Writes to an S3 bucket.\n\n    Args:\n\n        path: The key name. Each object in your bucket has a unique\n            key (or key name).\n        content: What you are uploading to S3.\n\n    Example:\n\n        Write data to the path `dogs/small_dogs/havanese` in an S3 Bucket:\n        ```python\n        from prefect_aws import MinioCredentials\n        from prefect_aws.s3 import S3Bucket\n\n        minio_creds = MinIOCredentials(\n            minio_root_user = \"minioadmin\",\n            minio_root_password = \"minioadmin\",\n        )\n\n        s3_bucket_block = S3Bucket(\n            bucket_name=\"bucket\",\n            minio_credentials=minio_creds,\n            bucket_folder=\"dogs/smalldogs\",\n            endpoint_url=\"http://localhost:9000\",\n        )\n        s3_havanese_path = s3_bucket_block.write_path(path=\"havanese\", content=data)\n        ```\n    \"\"\"\n\n    path = self._resolve_path(path)\n\n    await run_sync_in_worker_thread(self._write_sync, path, content)\n\n    return path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_copy","title":"<code>s3_copy</code>  <code>async</code>","text":"<p>Uses S3's internal CopyObject to copy objects within or between buckets. To copy objects between buckets, the credentials must have permission to read the source object and write to the target object. If the credentials do not have those permissions, try using <code>S3Bucket.stream_from</code>.</p> <p>Parameters:</p> Name Type Description Default <code>source_path</code> <code>str</code> <p>The path to the object to copy. Can be a string or <code>Path</code>.</p> required <code>target_path</code> <code>str</code> <p>The path to copy the object to. Can be a string or <code>Path</code>.</p> required <code>source_bucket_name</code> <code>str</code> <p>The bucket to copy the object from.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>target_bucket_name</code> <code>Optional[str]</code> <p>The bucket to copy the object to. If not provided, defaults to <code>source_bucket</code>.</p> <code>None</code> <code>**copy_kwargs</code> <p>Additional keyword arguments to pass to <code>S3Client.copy_object</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was copied to. Excludes the bucket name.</p> <pre><code>Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\ns3://my-bucket/my_folder/notes_copy.txt.\n\n```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_copy\n\naws_credentials = AwsCredentials.load(\"my-creds\")\n\n@flow\nasync def example_copy_flow():\n    await s3_copy(\n        source_path=\"my_folder/notes.txt\",\n        target_path=\"my_folder/notes_copy.txt\",\n        source_bucket_name=\"my-bucket\",\n        aws_credentials=aws_credentials,\n    )\n\nexample_copy_flow()\n```\n\nCopy notes.txt from s3://my-bucket/my_folder/notes.txt to\ns3://other-bucket/notes_copy.txt.\n\n```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_copy\n\naws_credentials = AwsCredentials.load(\"shared-creds\")\n\n@flow\nasync def example_copy_flow():\n    await s3_copy(\n        source_path=\"my_folder/notes.txt\",\n        target_path=\"notes_copy.txt\",\n        source_bucket_name=\"my-bucket\",\n        aws_credentials=aws_credentials,\n        target_bucket_name=\"other-bucket\",\n    )\n\nexample_copy_flow()\n```\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_copy(\n    source_path: str,\n    target_path: str,\n    source_bucket_name: str,\n    aws_credentials: AwsCredentials,\n    target_bucket_name: Optional[str] = None,\n    **copy_kwargs,\n) -&gt; str:\n    \"\"\"Uses S3's internal\n    [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)\n    to copy objects within or between buckets. To copy objects between buckets, the\n    credentials must have permission to read the source object and write to the target\n    object. If the credentials do not have those permissions, try using\n    `S3Bucket.stream_from`.\n\n    Args:\n        source_path: The path to the object to copy. Can be a string or `Path`.\n        target_path: The path to copy the object to. Can be a string or `Path`.\n        source_bucket_name: The bucket to copy the object from.\n        aws_credentials: Credentials to use for authentication with AWS.\n        target_bucket_name: The bucket to copy the object to. If not provided, defaults\n            to `source_bucket`.\n        **copy_kwargs: Additional keyword arguments to pass to `S3Client.copy_object`.\n\n    Returns:\n        The path that the object was copied to. Excludes the bucket name.\n\n    Examples:\n\n        Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\n        s3://my-bucket/my_folder/notes_copy.txt.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_copy\n\n        aws_credentials = AwsCredentials.load(\"my-creds\")\n\n        @flow\n        async def example_copy_flow():\n            await s3_copy(\n                source_path=\"my_folder/notes.txt\",\n                target_path=\"my_folder/notes_copy.txt\",\n                source_bucket_name=\"my-bucket\",\n                aws_credentials=aws_credentials,\n            )\n\n        example_copy_flow()\n        ```\n\n        Copy notes.txt from s3://my-bucket/my_folder/notes.txt to\n        s3://other-bucket/notes_copy.txt.\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_copy\n\n        aws_credentials = AwsCredentials.load(\"shared-creds\")\n\n        @flow\n        async def example_copy_flow():\n            await s3_copy(\n                source_path=\"my_folder/notes.txt\",\n                target_path=\"notes_copy.txt\",\n                source_bucket_name=\"my-bucket\",\n                aws_credentials=aws_credentials,\n                target_bucket_name=\"other-bucket\",\n            )\n\n        example_copy_flow()\n        ```\n\n    \"\"\"\n    logger = get_run_logger()\n\n    s3_client = aws_credentials.get_s3_client()\n\n    target_bucket_name = target_bucket_name or source_bucket_name\n\n    logger.info(\n        \"Copying object from bucket %s with key %s to bucket %s with key %s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    s3_client.copy_object(\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Bucket=target_bucket_name,\n        Key=target_path,\n        **copy_kwargs,\n    )\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_download","title":"<code>s3_download</code>  <code>async</code>","text":"<p>Downloads an object with a given key from a given S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of bucket to download object from. Required if a default value was not supplied when creating the task.</p> required <code>key</code> <code>str</code> <p>Key of object to download. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization.</p> <code>AwsClientParameters()</code> <p>Returns:</p> Type Description <code>bytes</code> <p>A <code>bytes</code> representation of the downloaded object.</p> Example <p>Download a file from an S3 bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_download\n\n\n@flow\nasync def example_s3_download_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    data = await s3_download(\n        bucket=\"bucket\",\n        key=\"key\",\n        aws_credentials=aws_credentials,\n    )\n\nexample_s3_download_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_download(\n    bucket: str,\n    key: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n) -&gt; bytes:\n    \"\"\"\n    Downloads an object with a given key from a given S3 bucket.\n\n    Args:\n        bucket: Name of bucket to download object from. Required if a default value was\n            not supplied when creating the task.\n        key: Key of object to download. Required if a default value was not supplied\n            when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization.\n\n\n    Returns:\n        A `bytes` representation of the downloaded object.\n\n    Example:\n        Download a file from an S3 bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_download\n\n\n        @flow\n        async def example_s3_download_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            data = await s3_download(\n                bucket=\"bucket\",\n                key=\"key\",\n                aws_credentials=aws_credentials,\n            )\n\n        example_s3_download_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading object from bucket %s with key %s\", bucket, key)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    stream = io.BytesIO()\n    await run_sync_in_worker_thread(\n        s3_client.download_fileobj, Bucket=bucket, Key=key, Fileobj=stream\n    )\n    stream.seek(0)\n    output = stream.read()\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_list_objects","title":"<code>s3_list_objects</code>  <code>async</code>","text":"<p>Lists details of objects in a given S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of bucket to list items from. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization..</p> <code>AwsClientParameters()</code> <code>prefix</code> <code>str</code> <p>Used to filter objects with keys starting with the specified prefix.</p> <code>''</code> <code>delimiter</code> <code>str</code> <p>Character used to group keys of listed objects.</p> <code>''</code> <code>page_size</code> <code>Optional[int]</code> <p>Number of objects to return in each request to the AWS API.</p> <code>None</code> <code>max_items</code> <code>Optional[int]</code> <p>Maximum number of objects that to be returned by task.</p> <code>None</code> <code>jmespath_query</code> <code>Optional[str]</code> <p>Query used to filter objects based on object attributes refer to the boto3 docs for more information on how to construct queries.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Dict[str, Any]]</code> <p>A list of dictionaries containing information about the objects retrieved. Refer to the boto3 docs for an example response.</p> Example <p>List all objects in a bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_list_objects\n\n\n@flow\nasync def example_s3_list_objects_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    objects = await s3_list_objects(\n        bucket=\"data_bucket\",\n        aws_credentials=aws_credentials\n    )\n\nexample_s3_list_objects_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_list_objects(\n    bucket: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n    prefix: str = \"\",\n    delimiter: str = \"\",\n    page_size: Optional[int] = None,\n    max_items: Optional[int] = None,\n    jmespath_query: Optional[str] = None,\n) -&gt; List[Dict[str, Any]]:\n    \"\"\"\n    Lists details of objects in a given S3 bucket.\n\n    Args:\n        bucket: Name of bucket to list items from. Required if a default value was not\n            supplied when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization..\n        prefix: Used to filter objects with keys starting with the specified prefix.\n        delimiter: Character used to group keys of listed objects.\n        page_size: Number of objects to return in each request to the AWS API.\n        max_items: Maximum number of objects that to be returned by task.\n        jmespath_query: Query used to filter objects based on object attributes refer to\n            the [boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html#filtering-results-with-jmespath)\n            for more information on how to construct queries.\n\n    Returns:\n        A list of dictionaries containing information about the objects retrieved. Refer\n            to the boto3 docs for an example response.\n\n    Example:\n        List all objects in a bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_list_objects\n\n\n        @flow\n        async def example_s3_list_objects_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            objects = await s3_list_objects(\n                bucket=\"data_bucket\",\n                aws_credentials=aws_credentials\n            )\n\n        example_s3_list_objects_flow()\n        ```\n    \"\"\"  # noqa E501\n    logger = get_run_logger()\n    logger.info(\"Listing objects in bucket %s with prefix %s\", bucket, prefix)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    paginator = s3_client.get_paginator(\"list_objects_v2\")\n    page_iterator = paginator.paginate(\n        Bucket=bucket,\n        Prefix=prefix,\n        Delimiter=delimiter,\n        PaginationConfig={\"PageSize\": page_size, \"MaxItems\": max_items},\n    )\n    if jmespath_query:\n        page_iterator = page_iterator.search(f\"{jmespath_query} | {{Contents: @}}\")\n\n    return await run_sync_in_worker_thread(_list_objects_sync, page_iterator)\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_move","title":"<code>s3_move</code>  <code>async</code>","text":"<p>Move an object from one S3 location to another. To move objects between buckets, the credentials must have permission to read and delete the source object and write to the target object. If the credentials do not have those permissions, this method will raise an error. If the credentials have permission to read the source object but not delete it, the object will be copied but not deleted.</p> <p>Parameters:</p> Name Type Description Default <code>source_path</code> <code>str</code> <p>The path of the object to move</p> required <code>target_path</code> <code>str</code> <p>The path to move the object to</p> required <code>source_bucket_name</code> <code>str</code> <p>The name of the bucket containing the source object</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>target_bucket_name</code> <code>Optional[str]</code> <p>The bucket to copy the object to. If not provided, defaults to <code>source_bucket</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was moved to. Excludes the bucket name.</p> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_move(\n    source_path: str,\n    target_path: str,\n    source_bucket_name: str,\n    aws_credentials: AwsCredentials,\n    target_bucket_name: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Move an object from one S3 location to another. To move objects between buckets,\n    the credentials must have permission to read and delete the source object and write\n    to the target object. If the credentials do not have those permissions, this method\n    will raise an error. If the credentials have permission to read the source object\n    but not delete it, the object will be copied but not deleted.\n\n    Args:\n        source_path: The path of the object to move\n        target_path: The path to move the object to\n        source_bucket_name: The name of the bucket containing the source object\n        aws_credentials: Credentials to use for authentication with AWS.\n        target_bucket_name: The bucket to copy the object to. If not provided, defaults\n            to `source_bucket`.\n\n    Returns:\n        The path that the object was moved to. Excludes the bucket name.\n    \"\"\"\n    logger = get_run_logger()\n\n    s3_client = aws_credentials.get_s3_client()\n\n    # If target bucket is not provided, assume it's the same as the source bucket\n    target_bucket_name = target_bucket_name or source_bucket_name\n\n    logger.info(\n        \"Moving object from s3://%s/%s s3://%s/%s\",\n        source_bucket_name,\n        source_path,\n        target_bucket_name,\n        target_path,\n    )\n\n    # Copy the object to the new location\n    s3_client.copy_object(\n        Bucket=target_bucket_name,\n        CopySource={\"Bucket\": source_bucket_name, \"Key\": source_path},\n        Key=target_path,\n    )\n\n    # Delete the original object\n    s3_client.delete_object(Bucket=source_bucket_name, Key=source_path)\n\n    return target_path\n</code></pre>"},{"location":"integrations/prefect-aws/s3/#prefect_aws.s3.s3_upload","title":"<code>s3_upload</code>  <code>async</code>","text":"<p>Uploads data to an S3 bucket.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>bytes</code> <p>Bytes representation of data to upload to S3.</p> required <code>bucket</code> <code>str</code> <p>Name of bucket to upload data to. Required if a default value was not supplied when creating the task.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>aws_client_parameters</code> <code>AwsClientParameters</code> <p>Custom parameter for the boto3 client initialization..</p> <code>AwsClientParameters()</code> <code>key</code> <code>Optional[str]</code> <p>Key of object to download. Defaults to a UUID string.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The key of the uploaded object</p> Example <p>Read and upload a file to an S3 bucket:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.s3 import s3_upload\n\n\n@flow\nasync def example_s3_upload_flow():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"acccess_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    with open(\"data.csv\", \"rb\") as file:\n        key = await s3_upload(\n            bucket=\"bucket\",\n            key=\"data.csv\",\n            data=file.read(),\n            aws_credentials=aws_credentials,\n        )\n\nexample_s3_upload_flow()\n</code></pre> Source code in <code>prefect_aws/s3.py</code> <pre><code>@task\nasync def s3_upload(\n    data: bytes,\n    bucket: str,\n    aws_credentials: AwsCredentials,\n    aws_client_parameters: AwsClientParameters = AwsClientParameters(),\n    key: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Uploads data to an S3 bucket.\n\n    Args:\n        data: Bytes representation of data to upload to S3.\n        bucket: Name of bucket to upload data to. Required if a default value was not\n            supplied when creating the task.\n        aws_credentials: Credentials to use for authentication with AWS.\n        aws_client_parameters: Custom parameter for the boto3 client initialization..\n        key: Key of object to download. Defaults to a UUID string.\n\n    Returns:\n        The key of the uploaded object\n\n    Example:\n        Read and upload a file to an S3 bucket:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.s3 import s3_upload\n\n\n        @flow\n        async def example_s3_upload_flow():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"acccess_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            with open(\"data.csv\", \"rb\") as file:\n                key = await s3_upload(\n                    bucket=\"bucket\",\n                    key=\"data.csv\",\n                    data=file.read(),\n                    aws_credentials=aws_credentials,\n                )\n\n        example_s3_upload_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    key = key or str(uuid.uuid4())\n\n    logger.info(\"Uploading object to bucket %s with key %s\", bucket, key)\n\n    s3_client = aws_credentials.get_boto3_session().client(\n        \"s3\", **aws_client_parameters.get_params_override()\n    )\n    stream = io.BytesIO(data)\n    await run_sync_in_worker_thread(\n        s3_client.upload_fileobj, stream, Bucket=bucket, Key=key\n    )\n\n    return key\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/","title":"Secrets Manager","text":""},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager","title":"<code>prefect_aws.secrets_manager</code>","text":"<p>Tasks for interacting with AWS Secrets Manager</p>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret","title":"<code>AwsSecret</code>","text":"<p>               Bases: <code>SecretBlock</code></p> <p>Manages a secret in AWS's Secrets Manager.</p> <p>Attributes:</p> Name Type Description <code>aws_credentials</code> <code>AwsCredentials</code> <p>The credentials to use for authentication with AWS.</p> <code>secret_name</code> <code>str</code> <p>The name of the secret.</p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>class AwsSecret(SecretBlock):\n    \"\"\"\n    Manages a secret in AWS's Secrets Manager.\n\n    Attributes:\n        aws_credentials: The credentials to use for authentication with AWS.\n        secret_name: The name of the secret.\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/d74b16fe84ce626345adf235a47008fea2869a60-225x225.png\"  # noqa\n    _block_type_name = \"AWS Secret\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret\"  # noqa\n\n    aws_credentials: AwsCredentials\n    secret_name: str = Field(default=..., description=\"The name of the secret.\")\n\n    @sync_compatible\n    async def read_secret(\n        self,\n        version_id: str = None,\n        version_stage: str = None,\n        **read_kwargs: Dict[str, Any],\n    ) -&gt; bytes:\n        \"\"\"\n        Reads the secret from the secret storage service.\n\n        Args:\n            version_id: The version of the secret to read. If not provided, the latest\n                version will be read.\n            version_stage: The version stage of the secret to read. If not provided,\n                the latest version will be read.\n            read_kwargs: Additional keyword arguments to pass to the\n                `get_secret_value` method of the boto3 client.\n\n        Returns:\n            The secret data.\n\n        Examples:\n            Reads a secret.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.read_secret()\n            ```\n        \"\"\"\n        client = self.aws_credentials.get_secrets_manager_client()\n        if version_id is not None:\n            read_kwargs[\"VersionId\"] = version_id\n        if version_stage is not None:\n            read_kwargs[\"VersionStage\"] = version_stage\n        response = await run_sync_in_worker_thread(\n            client.get_secret_value, SecretId=self.secret_name, **read_kwargs\n        )\n        if \"SecretBinary\" in response:\n            secret = response[\"SecretBinary\"]\n        elif \"SecretString\" in response:\n            secret = response[\"SecretString\"]\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret {arn!r} data was successfully read.\")\n        return secret\n\n    @sync_compatible\n    async def write_secret(\n        self, secret_data: bytes, **put_or_create_secret_kwargs: Dict[str, Any]\n    ) -&gt; str:\n        \"\"\"\n        Writes the secret to the secret storage service as a SecretBinary;\n        if it doesn't exist, it will be created.\n\n        Args:\n            secret_data: The secret data to write.\n            **put_or_create_secret_kwargs: Additional keyword arguments to pass to\n                put_secret_value or create_secret method of the boto3 client.\n\n        Returns:\n            The path that the secret was written to.\n\n        Examples:\n            Write some secret data.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.write_secret(b\"my_secret_data\")\n            ```\n        \"\"\"\n        client = self.aws_credentials.get_secrets_manager_client()\n        try:\n            response = await run_sync_in_worker_thread(\n                client.put_secret_value,\n                SecretId=self.secret_name,\n                SecretBinary=secret_data,\n                **put_or_create_secret_kwargs,\n            )\n        except client.exceptions.ResourceNotFoundException:\n            self.logger.info(\n                f\"The secret {self.secret_name!r} does not exist yet, creating it now.\"\n            )\n            response = await run_sync_in_worker_thread(\n                client.create_secret,\n                Name=self.secret_name,\n                SecretBinary=secret_data,\n                **put_or_create_secret_kwargs,\n            )\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret data was written successfully to {arn!r}.\")\n        return arn\n\n    @sync_compatible\n    async def delete_secret(\n        self,\n        recovery_window_in_days: int = 30,\n        force_delete_without_recovery: bool = False,\n        **delete_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Deletes the secret from the secret storage service.\n\n        Args:\n            recovery_window_in_days: The number of days to wait before permanently\n                deleting the secret. Must be between 7 and 30 days.\n            force_delete_without_recovery: If True, the secret will be deleted\n                immediately without a recovery window.\n            **delete_kwargs: Additional keyword arguments to pass to the\n                delete_secret method of the boto3 client.\n\n        Returns:\n            The path that the secret was deleted from.\n\n        Examples:\n            Deletes the secret with a recovery window of 15 days.\n            ```python\n            secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n            secrets_manager.delete_secret(recovery_window_in_days=15)\n            ```\n        \"\"\"\n        if force_delete_without_recovery and recovery_window_in_days:\n            raise ValueError(\n                \"Cannot specify recovery window and force delete without recovery.\"\n            )\n        elif not (7 &lt;= recovery_window_in_days &lt;= 30):\n            raise ValueError(\n                \"Recovery window must be between 7 and 30 days, got \"\n                f\"{recovery_window_in_days}.\"\n            )\n\n        client = self.aws_credentials.get_secrets_manager_client()\n        response = await run_sync_in_worker_thread(\n            client.delete_secret,\n            SecretId=self.secret_name,\n            RecoveryWindowInDays=recovery_window_in_days,\n            ForceDeleteWithoutRecovery=force_delete_without_recovery,\n            **delete_kwargs,\n        )\n        arn = response[\"ARN\"]\n        self.logger.info(f\"The secret {arn} was deleted successfully.\")\n        return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the secret from the secret storage service.</p> <p>Parameters:</p> Name Type Description Default <code>recovery_window_in_days</code> <code>int</code> <p>The number of days to wait before permanently deleting the secret. Must be between 7 and 30 days.</p> <code>30</code> <code>force_delete_without_recovery</code> <code>bool</code> <p>If True, the secret will be deleted immediately without a recovery window.</p> <code>False</code> <code>**delete_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the delete_secret method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was deleted from.</p> <p>Examples:</p> <p>Deletes the secret with a recovery window of 15 days. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.delete_secret(recovery_window_in_days=15)\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def delete_secret(\n    self,\n    recovery_window_in_days: int = 30,\n    force_delete_without_recovery: bool = False,\n    **delete_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Deletes the secret from the secret storage service.\n\n    Args:\n        recovery_window_in_days: The number of days to wait before permanently\n            deleting the secret. Must be between 7 and 30 days.\n        force_delete_without_recovery: If True, the secret will be deleted\n            immediately without a recovery window.\n        **delete_kwargs: Additional keyword arguments to pass to the\n            delete_secret method of the boto3 client.\n\n    Returns:\n        The path that the secret was deleted from.\n\n    Examples:\n        Deletes the secret with a recovery window of 15 days.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.delete_secret(recovery_window_in_days=15)\n        ```\n    \"\"\"\n    if force_delete_without_recovery and recovery_window_in_days:\n        raise ValueError(\n            \"Cannot specify recovery window and force delete without recovery.\"\n        )\n    elif not (7 &lt;= recovery_window_in_days &lt;= 30):\n        raise ValueError(\n            \"Recovery window must be between 7 and 30 days, got \"\n            f\"{recovery_window_in_days}.\"\n        )\n\n    client = self.aws_credentials.get_secrets_manager_client()\n    response = await run_sync_in_worker_thread(\n        client.delete_secret,\n        SecretId=self.secret_name,\n        RecoveryWindowInDays=recovery_window_in_days,\n        ForceDeleteWithoutRecovery=force_delete_without_recovery,\n        **delete_kwargs,\n    )\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret {arn} was deleted successfully.\")\n    return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the secret from the secret storage service.</p> <p>Parameters:</p> Name Type Description Default <code>version_id</code> <code>str</code> <p>The version of the secret to read. If not provided, the latest version will be read.</p> <code>None</code> <code>version_stage</code> <code>str</code> <p>The version stage of the secret to read. If not provided, the latest version will be read.</p> <code>None</code> <code>read_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>get_secret_value</code> method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>bytes</code> <p>The secret data.</p> <p>Examples:</p> <p>Reads a secret. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.read_secret()\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def read_secret(\n    self,\n    version_id: str = None,\n    version_stage: str = None,\n    **read_kwargs: Dict[str, Any],\n) -&gt; bytes:\n    \"\"\"\n    Reads the secret from the secret storage service.\n\n    Args:\n        version_id: The version of the secret to read. If not provided, the latest\n            version will be read.\n        version_stage: The version stage of the secret to read. If not provided,\n            the latest version will be read.\n        read_kwargs: Additional keyword arguments to pass to the\n            `get_secret_value` method of the boto3 client.\n\n    Returns:\n        The secret data.\n\n    Examples:\n        Reads a secret.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.read_secret()\n        ```\n    \"\"\"\n    client = self.aws_credentials.get_secrets_manager_client()\n    if version_id is not None:\n        read_kwargs[\"VersionId\"] = version_id\n    if version_stage is not None:\n        read_kwargs[\"VersionStage\"] = version_stage\n    response = await run_sync_in_worker_thread(\n        client.get_secret_value, SecretId=self.secret_name, **read_kwargs\n    )\n    if \"SecretBinary\" in response:\n        secret = response[\"SecretBinary\"]\n    elif \"SecretString\" in response:\n        secret = response[\"SecretString\"]\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret {arn!r} data was successfully read.\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.AwsSecret.write_secret","title":"<code>write_secret</code>  <code>async</code>","text":"<p>Writes the secret to the secret storage service as a SecretBinary; if it doesn't exist, it will be created.</p> <p>Parameters:</p> Name Type Description Default <code>secret_data</code> <code>bytes</code> <p>The secret data to write.</p> required <code>**put_or_create_secret_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to put_secret_value or create_secret method of the boto3 client.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was written to.</p> <p>Examples:</p> <p>Write some secret data. <pre><code>secrets_manager = SecretsManager.load(\"MY_BLOCK\")\nsecrets_manager.write_secret(b\"my_secret_data\")\n</code></pre></p> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@sync_compatible\nasync def write_secret(\n    self, secret_data: bytes, **put_or_create_secret_kwargs: Dict[str, Any]\n) -&gt; str:\n    \"\"\"\n    Writes the secret to the secret storage service as a SecretBinary;\n    if it doesn't exist, it will be created.\n\n    Args:\n        secret_data: The secret data to write.\n        **put_or_create_secret_kwargs: Additional keyword arguments to pass to\n            put_secret_value or create_secret method of the boto3 client.\n\n    Returns:\n        The path that the secret was written to.\n\n    Examples:\n        Write some secret data.\n        ```python\n        secrets_manager = SecretsManager.load(\"MY_BLOCK\")\n        secrets_manager.write_secret(b\"my_secret_data\")\n        ```\n    \"\"\"\n    client = self.aws_credentials.get_secrets_manager_client()\n    try:\n        response = await run_sync_in_worker_thread(\n            client.put_secret_value,\n            SecretId=self.secret_name,\n            SecretBinary=secret_data,\n            **put_or_create_secret_kwargs,\n        )\n    except client.exceptions.ResourceNotFoundException:\n        self.logger.info(\n            f\"The secret {self.secret_name!r} does not exist yet, creating it now.\"\n        )\n        response = await run_sync_in_worker_thread(\n            client.create_secret,\n            Name=self.secret_name,\n            SecretBinary=secret_data,\n            **put_or_create_secret_kwargs,\n        )\n    arn = response[\"ARN\"]\n    self.logger.info(f\"The secret data was written successfully to {arn!r}.\")\n    return arn\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.create_secret","title":"<code>create_secret</code>  <code>async</code>","text":"<p>Creates a secret in AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>The name of the secret to create.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>The value to store in the created secret.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>description</code> <code>Optional[str]</code> <p>A description for the created secret.</p> <code>None</code> <code>tags</code> <code>Optional[List[Dict[str, str]]]</code> <p>A list of tags to attach to the secret. Each tag should be specified as a dictionary in the following format: <pre><code>{\n    \"Key\": str,\n    \"Value\": str\n}\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and current version ID. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"VersionId\": str\n}\n</code></pre></p> <pre><code>```python\nfrom prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import create_secret\n\n@flow\ndef example_create_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    create_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        secret_value=\"42\",\n        aws_credentials=aws_credentials\n    )\n\nexample_create_secret()\n```\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def create_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    aws_credentials: AwsCredentials,\n    description: Optional[str] = None,\n    tags: Optional[List[Dict[str, str]]] = None,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Creates a secret in AWS Secrets Manager.\n\n    Args:\n        secret_name: The name of the secret to create.\n        secret_value: The value to store in the created secret.\n        aws_credentials: Credentials to use for authentication with AWS.\n        description: A description for the created secret.\n        tags: A list of tags to attach to the secret. Each tag should be specified as a\n            dictionary in the following format:\n            ```python\n            {\n                \"Key\": str,\n                \"Value\": str\n            }\n            ```\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and current version ID.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"VersionId\": str\n            }\n            ```\n    Example:\n        Create a secret:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import create_secret\n\n        @flow\n        def example_create_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            create_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                secret_value=\"42\",\n                aws_credentials=aws_credentials\n            )\n\n        example_create_secret()\n        ```\n\n\n    \"\"\"\n    create_secret_kwargs: Dict[str, Union[str, bytes, List[Dict[str, str]]]] = dict(\n        Name=secret_name\n    )\n    if description is not None:\n        create_secret_kwargs[\"Description\"] = description\n    if tags is not None:\n        create_secret_kwargs[\"Tags\"] = tags\n    if isinstance(secret_value, bytes):\n        create_secret_kwargs[\"SecretBinary\"] = secret_value\n    elif isinstance(secret_value, str):\n        create_secret_kwargs[\"SecretString\"] = secret_value\n    else:\n        raise ValueError(\"Please provide a bytes or str value for secret_value\")\n\n    logger = get_run_logger()\n    logger.info(\"Creating secret named %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.create_secret, **create_secret_kwargs\n        )\n        print(response.pop(\"ResponseMetadata\", None))\n        return response\n    except ClientError:\n        logger.exception(\"Unable to create secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes a secret from AWS Secrets Manager.</p> <p>Secrets can either be deleted immediately by setting <code>force_delete_without_recovery</code> equal to <code>True</code>. Otherwise, secrets will be marked for deletion and available for recovery for the number of days specified in <code>recovery_window_in_days</code></p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to be deleted.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>recovery_window_in_days</code> <code>int</code> <p>Number of days a secret should be recoverable for before permanent deletion. Minimum window is 7 days and maximum window is 30 days. If <code>force_delete_without_recovery</code> is set to <code>True</code>, this value will be ignored.</p> <code>30</code> <code>force_delete_without_recovery</code> <code>bool</code> <p>If <code>True</code>, the secret will be immediately deleted and will not be recoverable.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and deletion date of the secret. DeletionDate is the date and time of the delete request plus the number of days in <code>recovery_window_in_days</code>. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"DeletionDate\": datetime.datetime\n}\n</code></pre></p> <p>Examples:</p> <p>Delete a secret immediately:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import delete_secret\n\n@flow\ndef example_delete_secret_immediately():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    delete_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        aws_credentials=aws_credentials,\n        force_delete_without_recovery: True\n    )\n\nexample_delete_secret_immediately()\n</code></pre> <p>Delete a secret with a 90 day recovery window:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import delete_secret\n\n@flow\ndef example_delete_secret_with_recovery_window():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    delete_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        aws_credentials=aws_credentials,\n        recovery_window_in_days=90\n    )\n\nexample_delete_secret_with_recovery_window()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def delete_secret(\n    secret_name: str,\n    aws_credentials: AwsCredentials,\n    recovery_window_in_days: int = 30,\n    force_delete_without_recovery: bool = False,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Deletes a secret from AWS Secrets Manager.\n\n    Secrets can either be deleted immediately by setting `force_delete_without_recovery`\n    equal to `True`. Otherwise, secrets will be marked for deletion and available for\n    recovery for the number of days specified in `recovery_window_in_days`\n\n    Args:\n        secret_name: Name of the secret to be deleted.\n        aws_credentials: Credentials to use for authentication with AWS.\n        recovery_window_in_days: Number of days a secret should be recoverable for\n            before permanent deletion. Minimum window is 7 days and maximum window\n            is 30 days. If `force_delete_without_recovery` is set to `True`, this\n            value will be ignored.\n        force_delete_without_recovery: If `True`, the secret will be immediately\n            deleted and will not be recoverable.\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and deletion date of the secret. DeletionDate is the date and\n            time of the delete request plus the number of days in\n            `recovery_window_in_days`.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"DeletionDate\": datetime.datetime\n            }\n            ```\n\n    Examples:\n        Delete a secret immediately:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import delete_secret\n\n        @flow\n        def example_delete_secret_immediately():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            delete_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                aws_credentials=aws_credentials,\n                force_delete_without_recovery: True\n            )\n\n        example_delete_secret_immediately()\n        ```\n\n        Delete a secret with a 90 day recovery window:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import delete_secret\n\n        @flow\n        def example_delete_secret_with_recovery_window():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            delete_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                aws_credentials=aws_credentials,\n                recovery_window_in_days=90\n            )\n\n        example_delete_secret_with_recovery_window()\n        ```\n\n\n    \"\"\"\n    if not force_delete_without_recovery and not (7 &lt;= recovery_window_in_days &lt;= 30):\n        raise ValueError(\"Recovery window must be between 7 and 30 days.\")\n\n    delete_secret_kwargs: Dict[str, Union[str, int, bool]] = dict(SecretId=secret_name)\n    if force_delete_without_recovery:\n        delete_secret_kwargs[\n            \"ForceDeleteWithoutRecovery\"\n        ] = force_delete_without_recovery\n    else:\n        delete_secret_kwargs[\"RecoveryWindowInDays\"] = recovery_window_in_days\n\n    logger = get_run_logger()\n    logger.info(\"Deleting secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.delete_secret, **delete_secret_kwargs\n        )\n        response.pop(\"ResponseMetadata\", None)\n        return response\n    except ClientError:\n        logger.exception(\"Unable to delete secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the value of a given secret from AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of stored secret.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>version_id</code> <code>Optional[str]</code> <p>Specifies version of secret to read. Defaults to the most recent version if not given.</p> <code>None</code> <code>version_stage</code> <code>Optional[str]</code> <p>Specifies the version stage of the secret to read. Defaults to AWS_CURRENT if not given.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[str, bytes]</code> <p>The secret values as a <code>str</code> or <code>bytes</code> depending on the format in which the secret was stored.</p> Example <p>Read a secret value:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import read_secret\n\n@flow\ndef example_read_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    secret_value = read_secret(\n        secret_name=\"db_password\",\n        aws_credentials=aws_credentials\n    )\n\nexample_read_secret()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def read_secret(\n    secret_name: str,\n    aws_credentials: AwsCredentials,\n    version_id: Optional[str] = None,\n    version_stage: Optional[str] = None,\n) -&gt; Union[str, bytes]:\n    \"\"\"\n    Reads the value of a given secret from AWS Secrets Manager.\n\n    Args:\n        secret_name: Name of stored secret.\n        aws_credentials: Credentials to use for authentication with AWS.\n        version_id: Specifies version of secret to read. Defaults to the most recent\n            version if not given.\n        version_stage: Specifies the version stage of the secret to read. Defaults to\n            AWS_CURRENT if not given.\n\n    Returns:\n        The secret values as a `str` or `bytes` depending on the format in which the\n            secret was stored.\n\n    Example:\n        Read a secret value:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import read_secret\n\n        @flow\n        def example_read_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            secret_value = read_secret(\n                secret_name=\"db_password\",\n                aws_credentials=aws_credentials\n            )\n\n        example_read_secret()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Getting value for secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    get_secret_value_kwargs = dict(SecretId=secret_name)\n    if version_id is not None:\n        get_secret_value_kwargs[\"VersionId\"] = version_id\n    if version_stage is not None:\n        get_secret_value_kwargs[\"VersionStage\"] = version_stage\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.get_secret_value, **get_secret_value_kwargs\n        )\n    except ClientError:\n        logger.exception(\"Unable to get value for secret %s\", secret_name)\n        raise\n    else:\n        return response.get(\"SecretString\") or response.get(\"SecretBinary\")\n</code></pre>"},{"location":"integrations/prefect-aws/secrets_manager/#prefect_aws.secrets_manager.update_secret","title":"<code>update_secret</code>  <code>async</code>","text":"<p>Updates the value of a given secret in AWS Secrets Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of secret to update.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>Desired value of the secret. Can be either <code>str</code> or <code>bytes</code>.</p> required <code>aws_credentials</code> <code>AwsCredentials</code> <p>Credentials to use for authentication with AWS.</p> required <code>description</code> <code>Optional[str]</code> <p>Desired description of the secret.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>A dict containing the secret ARN (Amazon Resource Name), name, and current version ID. <pre><code>{\n    \"ARN\": str,\n    \"Name\": str,\n    \"VersionId\": str\n}\n</code></pre></p> Example <p>Update a secret value:</p> <pre><code>from prefect import flow\nfrom prefect_aws import AwsCredentials\nfrom prefect_aws.secrets_manager import update_secret\n\n@flow\ndef example_update_secret():\n    aws_credentials = AwsCredentials(\n        aws_access_key_id=\"access_key_id\",\n        aws_secret_access_key=\"secret_access_key\"\n    )\n    update_secret(\n        secret_name=\"life_the_universe_and_everything\",\n        secret_value=\"42\",\n        aws_credentials=aws_credentials\n    )\n\nexample_update_secret()\n</code></pre> Source code in <code>prefect_aws/secrets_manager.py</code> <pre><code>@task\nasync def update_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    aws_credentials: AwsCredentials,\n    description: Optional[str] = None,\n) -&gt; Dict[str, str]:\n    \"\"\"\n    Updates the value of a given secret in AWS Secrets Manager.\n\n    Args:\n        secret_name: Name of secret to update.\n        secret_value: Desired value of the secret. Can be either `str` or `bytes`.\n        aws_credentials: Credentials to use for authentication with AWS.\n        description: Desired description of the secret.\n\n    Returns:\n        A dict containing the secret ARN (Amazon Resource Name),\n            name, and current version ID.\n            ```python\n            {\n                \"ARN\": str,\n                \"Name\": str,\n                \"VersionId\": str\n            }\n            ```\n\n    Example:\n        Update a secret value:\n\n        ```python\n        from prefect import flow\n        from prefect_aws import AwsCredentials\n        from prefect_aws.secrets_manager import update_secret\n\n        @flow\n        def example_update_secret():\n            aws_credentials = AwsCredentials(\n                aws_access_key_id=\"access_key_id\",\n                aws_secret_access_key=\"secret_access_key\"\n            )\n            update_secret(\n                secret_name=\"life_the_universe_and_everything\",\n                secret_value=\"42\",\n                aws_credentials=aws_credentials\n            )\n\n        example_update_secret()\n        ```\n\n    \"\"\"\n    update_secret_kwargs: Dict[str, Union[str, bytes]] = dict(SecretId=secret_name)\n    if description is not None:\n        update_secret_kwargs[\"Description\"] = description\n    if isinstance(secret_value, bytes):\n        update_secret_kwargs[\"SecretBinary\"] = secret_value\n    elif isinstance(secret_value, str):\n        update_secret_kwargs[\"SecretString\"] = secret_value\n    else:\n        raise ValueError(\"Please provide a bytes or str value for secret_value\")\n\n    logger = get_run_logger()\n    logger.info(\"Updating value for secret %s\", secret_name)\n\n    client = aws_credentials.get_boto3_session().client(\"secretsmanager\")\n\n    try:\n        response = await run_sync_in_worker_thread(\n            client.update_secret, **update_secret_kwargs\n        )\n        response.pop(\"ResponseMetadata\", None)\n        return response\n    except ClientError:\n        logger.exception(\"Unable to update secret %s\", secret_name)\n        raise\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps","title":"<code>prefect_aws.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage and retrieval in S3 and S3 compatible services.</p>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PullFromS3Output","title":"<code>PullFromS3Output</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>pull_from_s3</code> step.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>class PullFromS3Output(TypedDict):\n    \"\"\"\n    The output of the `pull_from_s3` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n    directory: str\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PullProjectFromS3Output","title":"<code>PullProjectFromS3Output</code>","text":"<p>               Bases: <code>PullFromS3Output</code></p> <p>Deprecated. Use <code>PullFromS3Output</code> instead..</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PullFromS3Output` instead.\")\nclass PullProjectFromS3Output(PullFromS3Output):\n    \"\"\"Deprecated. Use `PullFromS3Output` instead..\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PushProjectToS3Output","title":"<code>PushProjectToS3Output</code>","text":"<p>               Bases: <code>PushToS3Output</code></p> <p>Deprecated. Use <code>PushToS3Output</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PushToS3Output` instead.\")\nclass PushProjectToS3Output(PushToS3Output):\n    \"\"\"Deprecated. Use `PushToS3Output` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.PushToS3Output","title":"<code>PushToS3Output</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>push_to_s3</code> step.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>class PushToS3Output(TypedDict):\n    \"\"\"\n    The output of the `push_to_s3` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.pull_from_s3","title":"<code>pull_from_s3</code>","text":"<p>Pulls the contents of an S3 bucket folder to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the S3 bucket where files are stored.</p> required <code>folder</code> <code>str</code> <p>The folder in the S3 bucket where files are stored.</p> required <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary of AWS credentials (aws_access_key_id, aws_secret_access_key, aws_session_token) or MinIO credentials (minio_root_user, minio_root_password).</p> <code>None</code> <code>client_parameters</code> <code>Optional[Dict]</code> <p>A dictionary of additional parameters to pass to the boto3 client.</p> <code>None</code> <p>Returns:</p> Type Description <code>PullFromS3Output</code> <p>A dictionary containing the bucket, folder, and local directory where files were downloaded.</p> <p>Examples:</p> <p>Pull files from S3 using the default credentials and client parameters: <pre><code>pull:\n    - prefect_aws.deployments.steps.pull_from_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Pull files from S3 using credentials stored in a block: <pre><code>pull:\n    - prefect_aws.deployments.steps.pull_from_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n        credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre></p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>def pull_from_s3(\n    bucket: str,\n    folder: str,\n    credentials: Optional[Dict] = None,\n    client_parameters: Optional[Dict] = None,\n) -&gt; PullFromS3Output:\n    \"\"\"\n    Pulls the contents of an S3 bucket folder to the current working directory.\n\n    Args:\n        bucket: The name of the S3 bucket where files are stored.\n        folder: The folder in the S3 bucket where files are stored.\n        credentials: A dictionary of AWS credentials (aws_access_key_id,\n            aws_secret_access_key, aws_session_token) or MinIO credentials\n            (minio_root_user, minio_root_password).\n        client_parameters: A dictionary of additional parameters to pass to the\n            boto3 client.\n\n    Returns:\n        A dictionary containing the bucket, folder, and local directory where\n            files were downloaded.\n\n    Examples:\n        Pull files from S3 using the default credentials and client parameters:\n        ```yaml\n        pull:\n            - prefect_aws.deployments.steps.pull_from_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Pull files from S3 using credentials stored in a block:\n        ```yaml\n        pull:\n            - prefect_aws.deployments.steps.pull_from_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n                credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n        ```\n    \"\"\"\n    s3 = get_s3_client(credentials=credentials, client_parameters=client_parameters)\n\n    local_path = Path.cwd()\n\n    paginator = s3.get_paginator(\"list_objects_v2\")\n    for result in paginator.paginate(Bucket=bucket, Prefix=folder):\n        for obj in result.get(\"Contents\", []):\n            remote_key = obj[\"Key\"]\n\n            if remote_key[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n\n            target = PurePosixPath(\n                local_path\n                / relative_path_to_current_platform(remote_key).relative_to(folder)\n            )\n            Path.mkdir(Path(target.parent), parents=True, exist_ok=True)\n            s3.download_file(bucket, remote_key, str(target))\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n        \"directory\": str(local_path),\n    }\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.pull_project_from_s3","title":"<code>pull_project_from_s3</code>","text":"<p>Deprecated. Use <code>pull_from_s3</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `pull_from_s3` instead.\")\ndef pull_project_from_s3(*args, **kwargs):\n    \"\"\"Deprecated. Use `pull_from_s3` instead.\"\"\"\n    pull_from_s3(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.push_project_to_s3","title":"<code>push_project_to_s3</code>","text":"<p>Deprecated. Use <code>push_to_s3</code> instead.</p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `push_to_s3` instead.\")\ndef push_project_to_s3(*args, **kwargs):\n    \"\"\"Deprecated. Use `push_to_s3` instead.\"\"\"\n    push_to_s3(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-aws/deployments/steps/#prefect_aws.deployments.steps.push_to_s3","title":"<code>push_to_s3</code>","text":"<p>Pushes the contents of the current working directory to an S3 bucket, excluding files and folders specified in the ignore_file.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the S3 bucket where files will be uploaded.</p> required <code>folder</code> <code>str</code> <p>The folder in the S3 bucket where files will be uploaded.</p> required <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary of AWS credentials (aws_access_key_id, aws_secret_access_key, aws_session_token) or MinIO credentials (minio_root_user, minio_root_password).</p> <code>None</code> <code>client_parameters</code> <code>Optional[Dict]</code> <p>A dictionary of additional parameters to pass to the boto3 client.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>The name of the file containing ignore patterns.</p> <code>'.prefectignore'</code> <p>Returns:</p> Type Description <code>PushToS3Output</code> <p>A dictionary containing the bucket and folder where files were uploaded.</p> <p>Examples:</p> <p>Push files to an S3 bucket: <pre><code>push:\n    - prefect_aws.deployments.steps.push_to_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Push files to an S3 bucket using credentials stored in a block: <pre><code>push:\n    - prefect_aws.deployments.steps.push_to_s3:\n        requires: prefect-aws\n        bucket: my-bucket\n        folder: my-project\n        credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n</code></pre></p> Source code in <code>prefect_aws/deployments/steps.py</code> <pre><code>def push_to_s3(\n    bucket: str,\n    folder: str,\n    credentials: Optional[Dict] = None,\n    client_parameters: Optional[Dict] = None,\n    ignore_file: Optional[str] = \".prefectignore\",\n) -&gt; PushToS3Output:\n    \"\"\"\n    Pushes the contents of the current working directory to an S3 bucket,\n    excluding files and folders specified in the ignore_file.\n\n    Args:\n        bucket: The name of the S3 bucket where files will be uploaded.\n        folder: The folder in the S3 bucket where files will be uploaded.\n        credentials: A dictionary of AWS credentials (aws_access_key_id,\n            aws_secret_access_key, aws_session_token) or MinIO credentials\n            (minio_root_user, minio_root_password).\n        client_parameters: A dictionary of additional parameters to pass to the boto3\n            client.\n        ignore_file: The name of the file containing ignore patterns.\n\n    Returns:\n        A dictionary containing the bucket and folder where files were uploaded.\n\n    Examples:\n        Push files to an S3 bucket:\n        ```yaml\n        push:\n            - prefect_aws.deployments.steps.push_to_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Push files to an S3 bucket using credentials stored in a block:\n        ```yaml\n        push:\n            - prefect_aws.deployments.steps.push_to_s3:\n                requires: prefect-aws\n                bucket: my-bucket\n                folder: my-project\n                credentials: \"{{ prefect.blocks.aws-credentials.dev-credentials }}\"\n        ```\n\n    \"\"\"\n    s3 = get_s3_client(credentials=credentials, client_parameters=client_parameters)\n\n    local_path = Path.cwd()\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    for local_file_path in local_path.expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(folder) / local_file_path.relative_to(local_path)\n            s3.upload_file(\n                str(local_file_path), bucket, str(remote_file_path.as_posix())\n            )\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-azure/","title":"prefect-azure","text":"<p><code>prefect-azure</code> makes it easy to leverage the capabilities of Azure in your workflows. For example, you can retrieve secrets, read and write Blob Storage objects, and deploy your flows on Azure Container Instances (ACI).</p>"},{"location":"integrations/prefect-azure/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-azure/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>An Azure account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-azure/#install-prefect-azure","title":"Install prefect-azure","text":"<pre><code>pip install -U prefect-azure\n</code></pre> <p>If necessary, see additional installation options for Blob Storage, Cosmos DB, and ML Datastore.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-azure[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-azure/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the module to make them available for use.</p> <pre><code>prefect block register -m prefect_azure\n</code></pre>"},{"location":"integrations/prefect-azure/#examples","title":"Examples","text":""},{"location":"integrations/prefect-azure/#download-a-blob","title":"Download a blob","text":"<pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef example_blob_storage_download_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    data = blob_storage_download(\n        blob=\"prefect.txt\",\n        container=\"prefect\",\n        azure_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_download_flow()\n</code></pre> <p>Use <code>with_options</code> to customize options on any existing task or flow:</p> <pre><code>custom_blob_storage_download_flow = example_blob_storage_download_flow.with_options(\n    name=\"My custom task name\",\n    retries=2,\n    retry_delay_seconds=10,\n)\n</code></pre>"},{"location":"integrations/prefect-azure/#run-flows-on-azure-container-instances","title":"Run flows on Azure Container Instances","text":"<p>Run flows on Azure Container Instances (ACI) to dynamically scale your infrastructure.</p> <p>See the Azure Container Instances Worker Guide for a walkthrough of using ACI in a hybrid work pool.</p> <p>If you're using Prefect Cloud, ACI push work pools provide all the benefits of ACI with a quick setup and no worker needed.</p>"},{"location":"integrations/prefect-azure/#resources","title":"Resources","text":"<p>For assistance using Azure, consult the Azure documentation.</p> <p>Refer to the prefect-azure API documentation linked in the sidebar to explore all the capabilities of the prefect-azure library.</p>"},{"location":"integrations/prefect-azure/#additional-installation-options","title":"Additional installation options","text":"<p>To use Blob Storage:</p> <pre><code>pip install -U \"prefect-azure[blob_storage]\"\n</code></pre> <p>To use Cosmos DB:</p> <pre><code>pip install -U \"prefect-azure[cosmos_db]\"\n</code></pre> <p>To use ML Datastore:</p> <pre><code>pip install -U \"prefect-azure[ml_datastore]\"\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/","title":"Azure Container Instances Worker Guide","text":""},{"location":"integrations/prefect-azure/aci_worker/#why-use-aci-for-flow-run-execution","title":"Why use ACI for flow run execution?","text":"<p>ACI (Azure Container Instances) is a fully managed compute platform that streamlines running your Prefect flows on scalable, on-demand infrastructure on Azure.</p>"},{"location":"integrations/prefect-azure/aci_worker/#prerequisites","title":"Prerequisites","text":"<p>Before starting this guide, make sure you have:</p> <ul> <li>An Azure account and user permissions for provisioning resource groups and container instances.</li> <li>The <code>azure</code> CLI installed on your local machine. You can follow Microsoft's installation guide.</li> <li>Docker installed on your local machine.</li> </ul>"},{"location":"integrations/prefect-azure/aci_worker/#step-1-create-a-resource-group","title":"Step 1. Create a resource group","text":"<p>Azure resource groups serve as containers for managing groupings of Azure resources.</p> <p>Replace <code>&lt;resource-group-name&gt;</code> with the name of your choosing, and <code>&lt;location&gt;</code> with a valid Azure location name, such as<code>eastus</code>.</p> <pre><code>export RG_NAME=&lt;resource-group-name&gt; &amp;&amp; \\\naz group create --name $RG_NAME --location &lt;location&gt;\n</code></pre> <p>Throughout the rest of the guide, we'll need to refer to the scope of the created resource group, which is a string describing where the resource group lives in the hierarchy of your Azure account. To save the scope of your resource group as an environment variable, run the following command:</p> <pre><code>RG_SCOPE=$(az group show --name $RG_NAME --query id --output tsv)\n</code></pre> <p>You can check that the scope is correct before moving on by running <code>echo $RG_SCOPE</code> in your terminal. It should be formatted as follows:</p> <pre><code>/subscriptions/&lt;subscription-id&gt;/resourceGroups/&lt;resource-group-name&gt;\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-2-prepare-aci-permissions","title":"Step 2. Prepare ACI permissions","text":"<p>In order for the worker to create, monitor, and delete the other container instances in which flows will run, we'll need to create a custom role and an identity, and then affiliate that role to the identity with a role assignment. When we start our worker, we'll assign that identity to the container instance it's running in.</p>"},{"location":"integrations/prefect-azure/aci_worker/#1-create-a-role","title":"1. Create a role","text":"<p>The custom <code>Container Instances Contributor</code> role has all the permissions your worker will need to run flows in other container instances. Create it by running the following command:</p> <pre><code>az role definition create --role-definition '{\n  \"Name\": \"Container Instances Contributor\",\n  \"IsCustom\": true,\n  \"Description\": \"Can create, delete, and monitor container instances.\",\n  \"Actions\": [\n    \"Microsoft.ManagedIdentity/userAssignedIdentities/assign/action\",\n    \"Microsoft.Resources/deployments/*\",\n    \"Microsoft.ContainerInstance/containerGroups/*\"\n  ],\n  \"NotActions\": [\n  ],\n  \"AssignableScopes\": [\n    '\"\\\"$RG_SCOPE\\\"\"'\n  ]\n}'\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#2-create-an-identity","title":"2. Create an identity","text":"<p>Create a user-managed identity with the following command, replacing <code>&lt;identity-name&gt;</code> with the name you'd like to use for the identity:</p> <pre><code>export IDENTITY_NAME=&lt;identity_name&gt; &amp;&amp; \\\naz identity create -g $RG_NAME -n $IDENTITY_NAME\n</code></pre> <p>We'll also need to save the principal ID and full object ID of the identity for the role assignment and container creation steps, respectively:</p> <pre><code>IDENTITY_PRINCIPAL_ID=$(az identity list --query \"[?name=='$IDENTITY_NAME'].principalId\" --output tsv) &amp;&amp; \\\nIDENTITY_ID=$(az identity list --query \"[?name=='$IDENTITY_NAME'].id\" --output tsv)\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#3-assign-roles-to-the-identity","title":"3. Assign roles to the identity","text":"<p>Now let's assign the <code>Container Instances Contributor</code> role we created earlier to the new identity:</p> <pre><code>az role assignment create \\\n    --assignee $IDENTITY_PRINCIPAL_ID \\\n    --role \"Container Instances Contributor\" \\\n    --scope $RG_SCOPE\n</code></pre> <p>Since we'll be using ACR to host a custom Docker image containing a Prefect flow later in the guide, let's also assign the built in <code>AcrPull</code> role to the identity:</p> <pre><code>az role assignment create \\\n    --assignee $IDENTITY_PRINCIPAL_ID \\\n    --role \"AcrPull\" \\\n    --scope $RG_SCOPE\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-3-create-the-worker-container-instance","title":"Step 3. Create the worker container instance","text":"<p>Before running this command, set your <code>PREFECT_API_URL</code> and <code>PREFECT_API_KEY</code> as environment variables:</p> <pre><code>export PREFECT_API_URL=&lt;PREFECT_API_URL_HERE&gt; PREFECT_API_KEY=&lt;PREFECT_API_KEY_HERE&gt;\n</code></pre> <p>Running the following command will create a container instance in your Azure resource group that will start a Prefect ACI worker. If there is not already a work pool in Prefect with the name you chose, a work pool will also be created.</p> <p>Replace <code>&lt;work-pool-name&gt;</code> with the name of the ACI work pool you want to create in Prefect. Here we're using the work pool name as the name of the container instance in Azure as well, but you may name it something else if you prefer.</p> <pre><code>az container create \\\n    --name &lt;work-pool-name&gt; \\\n    --resource-group $RG_NAME \\\n    --assign-identity $IDENTITY_ID \\\n    --image \"prefecthq/prefect:2-python3.11\" \\\n    --secure-environment-variables PREFECT_API_URL=$PREFECT_API_URL PREFECT_API_KEY=$PREFECT_API_KEY \\\n    --command-line \"/bin/bash -c 'pip install prefect-azure &amp;&amp; prefect worker start --pool &lt;work-pool-name&gt; --type azure-container-instance'\" \n</code></pre> <p>This container instance uses default networking and security settings. For advanced configuration, refer the <code>az container create</code> CLI reference.</p>"},{"location":"integrations/prefect-azure/aci_worker/#step-4-create-an-acr-registry","title":"Step 4. Create an ACR registry","text":"<p>In order to build and push images containing flow code to Azure, we'll need a container registry. Create one with the following command, replacing <code>&lt;registry-name&gt;</code> with the registry name of your choosing:</p> <pre><code>export REGISTRY_NAME=&lt;registry-name&gt; &amp;&amp; \\\naz acr create --resource-group $RG_NAME \\\n  --name &lt;registry-name&gt; --sku Basic\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#step-5-update-your-aci-work-pool-configuration","title":"Step 5. Update your ACI work pool configuration","text":"<p>Once your work pool is created, navigate to the Edit page of your ACI work pool. You will need to update the following fields:</p>"},{"location":"integrations/prefect-azure/aci_worker/#identities","title":"Identities","text":"<p>This will be your <code>IDENTITY_ID</code>. You can get it from your terminal by running <code>echo $IDENTITY_ID</code>. When adding it to your work pool, it should be formatted as a JSON array:</p> <pre><code>[\"/subscriptions/&lt;subscription-id&gt;/resourcegroups/&lt;resource-group-name&gt;/providers/Microsoft.ManagedIdentity/userAssignedIdentities/&lt;identity-name&gt;\"]\n</code></pre> <p></p>"},{"location":"integrations/prefect-azure/aci_worker/#acrmanagedidentity","title":"ACRManagedIdentity","text":"<p>ACRManagedIdentity is required for your flow code containers to be pulled from ACR. It consists of the following:</p> <ul> <li>Identity: the same <code>IDENTITY_ID</code> as above, as a string <pre><code>/subscriptions/&lt;subscription-id&gt;/resourcegroups/&lt;resource-group-name&gt;/providers/Microsoft.ManagedIdentity/userAssignedIdentities/&lt;identity-name&gt;\n</code></pre></li> <li>Registry URL: your <code>&lt;registry-name&gt;</code>, followed by <code>.azurecr.io</code> <pre><code>&lt;registry-name&gt;.azurecr.io\n</code></pre></li> </ul> <p></p>"},{"location":"integrations/prefect-azure/aci_worker/#subscription-id-and-resource-group-name","title":"Subscription ID and resource group name","text":"<p>Both the subscription ID and resource group name can be found in in the <code>RG_SCOPE</code> environment variable created earlier in the guide. View their values by running <code>echo $RG_SCOPE</code>:</p> <pre><code>/subscriptions/&lt;subscription-id&gt;/resourceGroups/&lt;resource-group-name&gt;\n</code></pre> <p></p> <p>Then click Save.</p>"},{"location":"integrations/prefect-azure/aci_worker/#step-6-pick-up-a-flow-run-with-your-new-worker","title":"Step 6. Pick up a flow run with your new worker","text":"<p>This guide uses ACR to store a Docker image containing your flow code. Write a flow, then deploy it using <code>flow.deploy()</code>, which will copy flow code into a Docker image and push that image to an ACR registry.</p>"},{"location":"integrations/prefect-azure/aci_worker/#1-log-in-to-acr","title":"1. Log in to ACR","text":"<p>Use the following commands to log in to ACR:</p> <pre><code>TOKEN=$(az acr login --name $REGISTRY_NAME --expose-token --output tsv --query accessToken)\n</code></pre> <pre><code>docker login $REGISTRY_NAME.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin &lt;&lt;&lt; $TOKEN\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#2-write-and-deploy-a-simple-test-flow","title":"2. Write and deploy a simple test flow","text":"<p>Create and run the following script to deploy your flow. Be sure to replace <code>&lt;registry-name&gt;</code> and <code>&lt;work-pool-name&gt;</code> with the appropriate values.</p> <p><code>my_flow.py</code></p> <pre><code>from prefect import flow, get_run_logger\nfrom prefect.deployments import DeploymentImage\n\n@flow\ndef my_flow():\n    logger = get_run_logger()\n    logger.info(\"Hello from ACI!\")\n\nif __name__ == \"__main__\":\n    my_flow.deploy(\n        name=\"aci-deployment\",\n        image=DeploymentImage(\n            name=\"&lt;registry-name&gt;.azurecr.io/example:latest\",\n            platform=\"linux/amd64\",\n        ),\n        work_pool_name=\"&lt;work-pool-name&gt;\",\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/aci_worker/#3-find-the-deployment-in-the-ui-and-click-the-quick-run-button","title":"3. Find the deployment in the UI and click the Quick Run button!","text":""},{"location":"integrations/prefect-azure/blob_storage/","title":"Blob Storage","text":""},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage","title":"<code>prefect_azure.blob_storage</code>","text":"<p>Integrations for interacting with Azure Blob Storage</p>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer","title":"<code>AzureBlobStorageContainer</code>","text":"<p>               Bases: <code>ObjectStorageBlock</code>, <code>WritableFileSystem</code>, <code>WritableDeploymentStorage</code></p> <p>Represents a container in Azure Blob Storage.</p> <p>This class provides methods for downloading and uploading files and folders to and from the Azure Blob Storage container.</p> <p>Attributes:</p> Name Type Description <code>container_name</code> <code>str</code> <p>The name of the Azure Blob Storage container.</p> <code>credentials</code> <code>AzureBlobStorageCredentials</code> <p>The credentials to use for authentication with Azure.</p> <code>base_folder</code> <code>Optional[str]</code> <p>A base path to a folder within the container to use for reading and writing objects.</p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>class AzureBlobStorageContainer(\n    ObjectStorageBlock, WritableFileSystem, WritableDeploymentStorage\n):\n    \"\"\"\n    Represents a container in Azure Blob Storage.\n\n    This class provides methods for downloading and uploading files and folders\n    to and from the Azure Blob Storage container.\n\n    Attributes:\n        container_name: The name of the Azure Blob Storage container.\n        credentials: The credentials to use for authentication with Azure.\n        base_folder: A base path to a folder within the container to use\n            for reading and writing objects.\n    \"\"\"\n\n    _block_type_name = \"Azure Blob Storage Container\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/blob_storage/#prefect_azure.blob_storabe.AzureBlobStorageContainer\"  # noqa\n\n    container_name: str = Field(\n        default=..., description=\"The name of a Azure Blob Storage container.\"\n    )\n    credentials: AzureBlobStorageCredentials = Field(\n        default_factory=AzureBlobStorageCredentials,\n        description=\"The credentials to use for authentication with Azure.\",\n    )\n    base_folder: Optional[str] = Field(\n        default=None,\n        description=(\n            \"A base path to a folder within the container to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    def _get_path_relative_to_base_folder(self, path: Optional[str] = None) -&gt; str:\n        if path is None and self.base_folder is None:\n            return \"\"\n        if path is None:\n            return self.base_folder\n        if self.base_folder is None:\n            return path\n        return (Path(self.base_folder) / Path(path)).as_posix()\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Union[str, Path],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, Path]:\n        \"\"\"Download a folder from the container to a local path.\n\n        Args:\n            from_folder: The folder path in the container to download.\n            to_folder: The local path to download the folder to.\n            **download_kwargs: Additional keyword arguments passed into\n                `BlobClient.download_blob`.\n\n        Returns:\n            The local path where the folder was downloaded.\n\n        Example:\n            Download the contents of container folder `folder` from the container\n                to the local folder `local_folder`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.download_folder_to_path(\n                from_folder=\"folder\",\n                to_folder=\"local_folder\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading folder from container %s to path %s\",\n            self.container_name,\n            to_folder,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_folder)\n        async with self.credentials.get_container_client(\n            self.container_name\n        ) as container_client:\n            try:\n                async for blob in container_client.list_blobs(\n                    name_starts_with=full_container_path\n                ):\n                    blob_path = blob.name\n                    local_path = Path(to_folder) / Path(blob_path).relative_to(\n                        full_container_path\n                    )\n                    local_path.parent.mkdir(parents=True, exist_ok=True)\n                    async with container_client.get_blob_client(\n                        blob_path\n                    ) as blob_client:\n                        blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                    with local_path.open(mode=\"wb\") as to_file:\n                        await blob_obj.readinto(to_file)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return Path(to_folder)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, BinaryIO]:\n        \"\"\"\n        Downloads an object from the container to a file object.\n\n        Args:\n            from_path : The path of the object to download within the container.\n            to_file_object: The file object to download the object to.\n            **download_kwargs: Additional keyword arguments for the download\n                operation.\n\n        Returns:\n            The file object that the object was downloaded to.\n\n        Example:\n            Download the object `object` from the container to a file object:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            with open(\"file.txt\", \"wb\") as f:\n                block.download_object_to_file_object(\n                    from_path=\"object\",\n                    to_file_object=f\n                )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading object from container %s to file object\", self.container_name\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                blob_obj = await blob_client.download_blob(**download_kwargs)\n                await blob_obj.download_to_stream(to_file_object)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_file_object\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Union[str, Path],\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, Path]:\n        \"\"\"\n        Downloads an object from a container to a specified path.\n\n        Args:\n            from_path: The path of the object in the container.\n            to_path: The path where the object will be downloaded to.\n            **download_kwargs (Dict[str, Any]): Additional keyword arguments\n                for the download operation.\n\n        Returns:\n            The path where the object was downloaded to.\n\n        Example:\n            Download the object `object` from the container to the local path\n                `file.txt`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.download_object_to_path(\n                from_path=\"object\",\n                to_path=\"file.txt\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Downloading object from container %s to path %s\",\n            self.container_name,\n            to_path,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(from_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                path = Path(to_path)\n\n                path.parent.mkdir(parents=True, exist_ok=True)\n\n                with path.open(mode=\"wb\") as to_file:\n                    await blob_obj.readinto(to_file)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to download from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n        return Path(to_path)\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads an object from a file object to the specified path in the blob\n            storage container.\n\n        Args:\n            from_file_object: The file object to upload.\n            to_path: The path in the blob storage container to upload the\n                object to.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                upload_blob method.\n\n        Returns:\n            The path where the object was uploaded to.\n\n        Example:\n            Upload a file object to the container at the path `object`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            with open(\"file.txt\", \"rb\") as f:\n                block.upload_from_file_object(\n                    from_file_object=f,\n                    to_path=\"object\"\n                )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading object to container %s with key %s\", self.container_name, to_path\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                await blob_client.upload_blob(from_file_object, **upload_kwargs)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to upload from container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_path\n\n    @sync_compatible\n    async def upload_from_path(\n        self, from_path: Union[str, Path], to_path: str, **upload_kwargs: Dict[str, Any]\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads an object from a local path to the specified destination path in the\n            blob storage container.\n\n        Args:\n            from_path: The local path of the object to upload.\n            to_path: The destination path in the blob storage container.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                `upload_blob` method.\n\n        Returns:\n            The destination path in the blob storage container.\n\n        Example:\n            Upload a file from the local path `file.txt` to the container\n                at the path `object`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.upload_from_path(\n                from_path=\"file.txt\",\n                to_path=\"object\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading object to container %s with key %s\", self.container_name, to_path\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_path)\n        async with self.credentials.get_blob_client(\n            self.container_name, full_container_path\n        ) as blob_client:\n            try:\n                with open(from_path, \"rb\") as f:\n                    await blob_client.upload_blob(f, **upload_kwargs)\n            except ResourceNotFoundError as exc:\n                raise RuntimeError(\n                    \"An error occurred when attempting to upload to container\"\n                    f\" {self.container_name}: {exc.reason}\"\n                ) from exc\n\n        return to_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: str,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; Coroutine[Any, Any, str]:\n        \"\"\"\n        Uploads files from a local folder to a specified folder in the Azure\n            Blob Storage container.\n\n        Args:\n            from_folder: The path to the local folder containing the files to upload.\n            to_folder: The destination folder in the Azure Blob Storage container.\n            **upload_kwargs: Additional keyword arguments to pass to the\n                `upload_blob` method.\n\n        Returns:\n            The full path of the destination folder in the container.\n\n        Example:\n            Upload the contents of the local folder `local_folder` to the container\n                folder `folder`:\n\n            ```python\n            from prefect_azure import AzureBlobStorageCredentials\n            from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n            credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            block = AzureBlobStorageContainer(\n                container_name=\"container\",\n                credentials=credentials,\n            )\n            block.upload_from_folder(\n                from_folder=\"local_folder\",\n                to_folder=\"folder\"\n            )\n            ```\n        \"\"\"\n        self.logger.info(\n            \"Uploading folder to container %s with key %s\",\n            self.container_name,\n            to_folder,\n        )\n        full_container_path = self._get_path_relative_to_base_folder(to_folder)\n        async with self.credentials.get_container_client(\n            self.container_name\n        ) as container_client:\n            if not Path(from_folder).is_dir():\n                raise ValueError(f\"{from_folder} is not a directory\")\n            for path in Path(from_folder).rglob(\"*\"):\n                if path.is_file():\n                    blob_path = Path(full_container_path) / path.relative_to(\n                        from_folder\n                    )\n                    async with container_client.get_blob_client(\n                        blob_path.as_posix()\n                    ) as blob_client:\n                        try:\n                            await blob_client.upload_blob(\n                                path.read_bytes(), **upload_kwargs\n                            )\n                        except ResourceNotFoundError as exc:\n                            raise RuntimeError(\n                                \"An error occurred when attempting to upload to \"\n                                f\"container {self.container_name}: {exc.reason}\"\n                            ) from exc\n        return full_container_path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: str = None, local_path: str = None\n    ) -&gt; None:\n        \"\"\"\n        Downloads the contents of a direry from the blob storage to a local path.\n\n        Used to enable flow code storage for deployments.\n\n        Args:\n            from_path: The path of the directory in the blob storage.\n            local_path: The local path where the directory will be downloaded.\n        \"\"\"\n        await self.download_folder_to_path(from_path, local_path)\n\n    @sync_compatible\n    async def put_directory(\n        self, local_path: str = None, to_path: str = None, ignore_file: str = None\n    ) -&gt; None:\n        \"\"\"\n        Uploads a directory to the blob storage.\n\n        Used to enable flow code storage for deployments.\n\n        Args:\n            local_path: The local path of the directory to upload. Defaults to\n                current directory.\n            to_path: The destination path in the blob storage. Defaults to\n                root directory.\n            ignore_file: The path to a file containing patterns to ignore\n                during upload.\n        \"\"\"\n        to_path = \"\" if to_path is None else to_path\n\n        if local_path is None:\n            local_path = \".\"\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n\n            included_files = filter_files(local_path, ignore_patterns)\n\n        for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(to_path) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as local_file:\n                    local_file_content = local_file.read()\n\n                await self.write_path(\n                    remote_file_path.as_posix(), content=local_file_content\n                )\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Reads the contents of a file at the specified path and returns it as bytes.\n\n        Used to enable results storage.\n\n        Args:\n            path: The path of the file to read.\n\n        Returns:\n            The contents of the file as bytes.\n        \"\"\"\n        file_obj = BytesIO()\n        await self.download_object_to_file_object(path, file_obj)\n        return file_obj.getvalue()\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; None:\n        \"\"\"\n        Writes the content to the specified path in the blob storage.\n\n        Used to enable results storage.\n\n        Args:\n            path: The path where the content will be written.\n            content: The content to be written.\n        \"\"\"\n        await self.upload_from_file_object(BytesIO(content), path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Download a folder from the container to a local path.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The folder path in the container to download.</p> required <code>to_folder</code> <code>Union[str, Path]</code> <p>The local path to download the folder to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments passed into <code>BlobClient.download_blob</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, Path]</code> <p>The local path where the folder was downloaded.</p> Example <p>Download the contents of container folder <code>folder</code> from the container     to the local folder <code>local_folder</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.download_folder_to_path(\n    from_folder=\"folder\",\n    to_folder=\"local_folder\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Union[str, Path],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, Path]:\n    \"\"\"Download a folder from the container to a local path.\n\n    Args:\n        from_folder: The folder path in the container to download.\n        to_folder: The local path to download the folder to.\n        **download_kwargs: Additional keyword arguments passed into\n            `BlobClient.download_blob`.\n\n    Returns:\n        The local path where the folder was downloaded.\n\n    Example:\n        Download the contents of container folder `folder` from the container\n            to the local folder `local_folder`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.download_folder_to_path(\n            from_folder=\"folder\",\n            to_folder=\"local_folder\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading folder from container %s to path %s\",\n        self.container_name,\n        to_folder,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_folder)\n    async with self.credentials.get_container_client(\n        self.container_name\n    ) as container_client:\n        try:\n            async for blob in container_client.list_blobs(\n                name_starts_with=full_container_path\n            ):\n                blob_path = blob.name\n                local_path = Path(to_folder) / Path(blob_path).relative_to(\n                    full_container_path\n                )\n                local_path.parent.mkdir(parents=True, exist_ok=True)\n                async with container_client.get_blob_client(\n                    blob_path\n                ) as blob_client:\n                    blob_obj = await blob_client.download_blob(**download_kwargs)\n\n                with local_path.open(mode=\"wb\") as to_file:\n                    await blob_obj.readinto(to_file)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return Path(to_folder)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the container to a file object.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <p>The path of the object to download within the container.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file object to download the object to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments for the download operation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, BinaryIO]</code> <p>The file object that the object was downloaded to.</p> Example <p>Download the object <code>object</code> from the container to a file object:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nwith open(\"file.txt\", \"wb\") as f:\n    block.download_object_to_file_object(\n        from_path=\"object\",\n        to_file_object=f\n    )\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, BinaryIO]:\n    \"\"\"\n    Downloads an object from the container to a file object.\n\n    Args:\n        from_path : The path of the object to download within the container.\n        to_file_object: The file object to download the object to.\n        **download_kwargs: Additional keyword arguments for the download\n            operation.\n\n    Returns:\n        The file object that the object was downloaded to.\n\n    Example:\n        Download the object `object` from the container to a file object:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        with open(\"file.txt\", \"wb\") as f:\n            block.download_object_to_file_object(\n                from_path=\"object\",\n                to_file_object=f\n            )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading object from container %s to file object\", self.container_name\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            blob_obj = await blob_client.download_blob(**download_kwargs)\n            await blob_obj.download_to_stream(to_file_object)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from a container to a specified path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path of the object in the container.</p> required <code>to_path</code> <code>Union[str, Path]</code> <p>The path where the object will be downloaded to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments for the download operation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, Path]</code> <p>The path where the object was downloaded to.</p> Example <p>Download the object <code>object</code> from the container to the local path     <code>file.txt</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.download_object_to_path(\n    from_path=\"object\",\n    to_path=\"file.txt\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Union[str, Path],\n    **download_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, Path]:\n    \"\"\"\n    Downloads an object from a container to a specified path.\n\n    Args:\n        from_path: The path of the object in the container.\n        to_path: The path where the object will be downloaded to.\n        **download_kwargs (Dict[str, Any]): Additional keyword arguments\n            for the download operation.\n\n    Returns:\n        The path where the object was downloaded to.\n\n    Example:\n        Download the object `object` from the container to the local path\n            `file.txt`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.download_object_to_path(\n            from_path=\"object\",\n            to_path=\"file.txt\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Downloading object from container %s to path %s\",\n        self.container_name,\n        to_path,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(from_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            blob_obj = await blob_client.download_blob(**download_kwargs)\n\n            path = Path(to_path)\n\n            path.parent.mkdir(parents=True, exist_ok=True)\n\n            with path.open(mode=\"wb\") as to_file:\n                await blob_obj.readinto(to_file)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to download from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Downloads the contents of a direry from the blob storage to a local path.</p> <p>Used to enable flow code storage for deployments.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path of the directory in the blob storage.</p> <code>None</code> <code>local_path</code> <code>str</code> <p>The local path where the directory will be downloaded.</p> <code>None</code> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: str = None, local_path: str = None\n) -&gt; None:\n    \"\"\"\n    Downloads the contents of a direry from the blob storage to a local path.\n\n    Used to enable flow code storage for deployments.\n\n    Args:\n        from_path: The path of the directory in the blob storage.\n        local_path: The local path where the directory will be downloaded.\n    \"\"\"\n    await self.download_folder_to_path(from_path, local_path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory to the blob storage.</p> <p>Used to enable flow code storage for deployments.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>str</code> <p>The local path of the directory to upload. Defaults to current directory.</p> <code>None</code> <code>to_path</code> <code>str</code> <p>The destination path in the blob storage. Defaults to root directory.</p> <code>None</code> <code>ignore_file</code> <code>str</code> <p>The path to a file containing patterns to ignore during upload.</p> <code>None</code> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self, local_path: str = None, to_path: str = None, ignore_file: str = None\n) -&gt; None:\n    \"\"\"\n    Uploads a directory to the blob storage.\n\n    Used to enable flow code storage for deployments.\n\n    Args:\n        local_path: The local path of the directory to upload. Defaults to\n            current directory.\n        to_path: The destination path in the blob storage. Defaults to\n            root directory.\n        ignore_file: The path to a file containing patterns to ignore\n            during upload.\n    \"\"\"\n    to_path = \"\" if to_path is None else to_path\n\n    if local_path is None:\n        local_path = \".\"\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(local_path, ignore_patterns)\n\n    for local_file_path in Path(local_path).expanduser().rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = Path(to_path) / local_file_path.relative_to(\n                local_path\n            )\n            with open(local_file_path, \"rb\") as local_file:\n                local_file_content = local_file.read()\n\n            await self.write_path(\n                remote_file_path.as_posix(), content=local_file_content\n            )\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Reads the contents of a file at the specified path and returns it as bytes.</p> <p>Used to enable results storage.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path of the file to read.</p> required <p>Returns:</p> Type Description <code>bytes</code> <p>The contents of the file as bytes.</p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Reads the contents of a file at the specified path and returns it as bytes.\n\n    Used to enable results storage.\n\n    Args:\n        path: The path of the file to read.\n\n    Returns:\n        The contents of the file as bytes.\n    \"\"\"\n    file_obj = BytesIO()\n    await self.download_object_to_file_object(path, file_obj)\n    return file_obj.getvalue()\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object from a file object to the specified path in the blob     storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file object to upload.</p> required <code>to_path</code> <code>str</code> <p>The path in the blob storage container to upload the object to.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the upload_blob method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The path where the object was uploaded to.</p> Example <p>Upload a file object to the container at the path <code>object</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nwith open(\"file.txt\", \"rb\") as f:\n    block.upload_from_file_object(\n        from_file_object=f,\n        to_path=\"object\"\n    )\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads an object from a file object to the specified path in the blob\n        storage container.\n\n    Args:\n        from_file_object: The file object to upload.\n        to_path: The path in the blob storage container to upload the\n            object to.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            upload_blob method.\n\n    Returns:\n        The path where the object was uploaded to.\n\n    Example:\n        Upload a file object to the container at the path `object`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        with open(\"file.txt\", \"rb\") as f:\n            block.upload_from_file_object(\n                from_file_object=f,\n                to_path=\"object\"\n            )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading object to container %s with key %s\", self.container_name, to_path\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            await blob_client.upload_blob(from_file_object, **upload_kwargs)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to upload from container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files from a local folder to a specified folder in the Azure     Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the local folder containing the files to upload.</p> required <code>to_folder</code> <code>str</code> <p>The destination folder in the Azure Blob Storage container.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>upload_blob</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The full path of the destination folder in the container.</p> Example <p>Upload the contents of the local folder <code>local_folder</code> to the container     folder <code>folder</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.upload_from_folder(\n    from_folder=\"local_folder\",\n    to_folder=\"folder\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: str,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads files from a local folder to a specified folder in the Azure\n        Blob Storage container.\n\n    Args:\n        from_folder: The path to the local folder containing the files to upload.\n        to_folder: The destination folder in the Azure Blob Storage container.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            `upload_blob` method.\n\n    Returns:\n        The full path of the destination folder in the container.\n\n    Example:\n        Upload the contents of the local folder `local_folder` to the container\n            folder `folder`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.upload_from_folder(\n            from_folder=\"local_folder\",\n            to_folder=\"folder\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading folder to container %s with key %s\",\n        self.container_name,\n        to_folder,\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_folder)\n    async with self.credentials.get_container_client(\n        self.container_name\n    ) as container_client:\n        if not Path(from_folder).is_dir():\n            raise ValueError(f\"{from_folder} is not a directory\")\n        for path in Path(from_folder).rglob(\"*\"):\n            if path.is_file():\n                blob_path = Path(full_container_path) / path.relative_to(\n                    from_folder\n                )\n                async with container_client.get_blob_client(\n                    blob_path.as_posix()\n                ) as blob_client:\n                    try:\n                        await blob_client.upload_blob(\n                            path.read_bytes(), **upload_kwargs\n                        )\n                    except ResourceNotFoundError as exc:\n                        raise RuntimeError(\n                            \"An error occurred when attempting to upload to \"\n                            f\"container {self.container_name}: {exc.reason}\"\n                        ) from exc\n    return full_container_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a local path to the specified destination path in the     blob storage container.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The local path of the object to upload.</p> required <code>to_path</code> <code>str</code> <p>The destination path in the blob storage container.</p> required <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>upload_blob</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Coroutine[Any, Any, str]</code> <p>The destination path in the blob storage container.</p> Example <p>Upload a file from the local path <code>file.txt</code> to the container     at the path <code>object</code>:</p> <pre><code>from prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import AzureBlobStorageContainer\n\ncredentials = AzureBlobStorageCredentials(\n    connection_string=\"connection_string\",\n)\nblock = AzureBlobStorageContainer(\n    container_name=\"container\",\n    credentials=credentials,\n)\nblock.upload_from_path(\n    from_path=\"file.txt\",\n    to_path=\"object\"\n)\n</code></pre> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self, from_path: Union[str, Path], to_path: str, **upload_kwargs: Dict[str, Any]\n) -&gt; Coroutine[Any, Any, str]:\n    \"\"\"\n    Uploads an object from a local path to the specified destination path in the\n        blob storage container.\n\n    Args:\n        from_path: The local path of the object to upload.\n        to_path: The destination path in the blob storage container.\n        **upload_kwargs: Additional keyword arguments to pass to the\n            `upload_blob` method.\n\n    Returns:\n        The destination path in the blob storage container.\n\n    Example:\n        Upload a file from the local path `file.txt` to the container\n            at the path `object`:\n\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import AzureBlobStorageContainer\n\n        credentials = AzureBlobStorageCredentials(\n            connection_string=\"connection_string\",\n        )\n        block = AzureBlobStorageContainer(\n            container_name=\"container\",\n            credentials=credentials,\n        )\n        block.upload_from_path(\n            from_path=\"file.txt\",\n            to_path=\"object\"\n        )\n        ```\n    \"\"\"\n    self.logger.info(\n        \"Uploading object to container %s with key %s\", self.container_name, to_path\n    )\n    full_container_path = self._get_path_relative_to_base_folder(to_path)\n    async with self.credentials.get_blob_client(\n        self.container_name, full_container_path\n    ) as blob_client:\n        try:\n            with open(from_path, \"rb\") as f:\n                await blob_client.upload_blob(f, **upload_kwargs)\n        except ResourceNotFoundError as exc:\n            raise RuntimeError(\n                \"An error occurred when attempting to upload to container\"\n                f\" {self.container_name}: {exc.reason}\"\n            ) from exc\n\n    return to_path\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.AzureBlobStorageContainer.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes the content to the specified path in the blob storage.</p> <p>Used to enable results storage.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The path where the content will be written.</p> required <code>content</code> <code>bytes</code> <p>The content to be written.</p> required Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; None:\n    \"\"\"\n    Writes the content to the specified path in the blob storage.\n\n    Used to enable results storage.\n\n    Args:\n        path: The path where the content will be written.\n        content: The content to be written.\n    \"\"\"\n    await self.upload_from_file_object(BytesIO(content), path)\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_download","title":"<code>blob_storage_download</code>  <code>async</code>","text":"<p>Downloads a blob with a given key from a given Blob Storage container. Args:     blob: Name of the blob within this container to retrieve.     container: Name of the Blob Storage container to retrieve from.     blob_storage_credentials: Credentials to use for authentication with Azure. Returns:     A <code>bytes</code> representation of the downloaded blob. Example:     Download a file from a Blob Storage container     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_download\n\n@flow\ndef example_blob_storage_download_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    data = blob_storage_download(\n        container=\"prefect\",\n        blob=\"prefect.txt\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_download_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_download(\n    container: str,\n    blob: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n) -&gt; bytes:\n    \"\"\"\n    Downloads a blob with a given key from a given Blob Storage container.\n    Args:\n        blob: Name of the blob within this container to retrieve.\n        container: Name of the Blob Storage container to retrieve from.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n    Returns:\n        A `bytes` representation of the downloaded blob.\n    Example:\n        Download a file from a Blob Storage container\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_download\n\n        @flow\n        def example_blob_storage_download_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            data = blob_storage_download(\n                container=\"prefect\",\n                blob=\"prefect.txt\",\n                blob_storage_credentials=blob_storage_credentials,\n            )\n            return data\n\n        example_blob_storage_download_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading blob from container %s with key %s\", container, blob)\n\n    async with blob_storage_credentials.get_blob_client(container, blob) as blob_client:\n        blob_obj = await blob_client.download_blob()\n        output = await blob_obj.content_as_bytes()\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_list","title":"<code>blob_storage_list</code>  <code>async</code>","text":"<p>List objects from a given Blob Storage container. Args:     container: Name of the Blob Storage container to retrieve from.     blob_storage_credentials: Credentials to use for authentication with Azure.     name_starts_with: Filters the results to return only blobs whose names         begin with the specified prefix.     include: Specifies one or more additional datasets to include in the response.         Options include: 'snapshots', 'metadata', 'uncommittedblobs', 'copy',         'deleted', 'deletedwithversions', 'tags', 'versions', 'immutabilitypolicy',         'legalhold'.     **kwargs: Additional kwargs passed to <code>ContainerClient.list_blobs()</code> Returns:     A <code>list</code> of <code>dict</code>s containing metadata about the blob. Example:     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_list\n\n@flow\ndef example_blob_storage_list_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=\"connection_string\",\n    )\n    data = blob_storage_list(\n        container=\"container\",\n        blob_storage_credentials=blob_storage_credentials,\n    )\n    return data\n\nexample_blob_storage_list_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_list(\n    container: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    name_starts_with: str = None,\n    include: Union[str, List[str]] = None,\n    **kwargs,\n) -&gt; List[\"BlobProperties\"]:\n    \"\"\"\n    List objects from a given Blob Storage container.\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n        name_starts_with: Filters the results to return only blobs whose names\n            begin with the specified prefix.\n        include: Specifies one or more additional datasets to include in the response.\n            Options include: 'snapshots', 'metadata', 'uncommittedblobs', 'copy',\n            'deleted', 'deletedwithversions', 'tags', 'versions', 'immutabilitypolicy',\n            'legalhold'.\n        **kwargs: Additional kwargs passed to `ContainerClient.list_blobs()`\n    Returns:\n        A `list` of `dict`s containing metadata about the blob.\n    Example:\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_list\n\n        @flow\n        def example_blob_storage_list_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=\"connection_string\",\n            )\n            data = blob_storage_list(\n                container=\"container\",\n                blob_storage_credentials=blob_storage_credentials,\n            )\n            return data\n\n        example_blob_storage_list_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Listing blobs from container %s\", container)\n\n    async with blob_storage_credentials.get_container_client(\n        container\n    ) as container_client:\n        blobs = [\n            blob\n            async for blob in container_client.list_blobs(\n                name_starts_with=name_starts_with, include=include, **kwargs\n            )\n        ]\n\n    return blobs\n</code></pre>"},{"location":"integrations/prefect-azure/blob_storage/#prefect_azure.blob_storage.blob_storage_upload","title":"<code>blob_storage_upload</code>  <code>async</code>","text":"<p>Uploads data to an Blob Storage container. Args:     data: Bytes representation of data to upload to Blob Storage.     container: Name of the Blob Storage container to upload to.     blob_storage_credentials: Credentials to use for authentication with Azure.     blob: Name of the blob within this container to retrieve.     overwrite: If <code>True</code>, an existing blob with the same name will be overwritten.         Defaults to <code>False</code> and an error will be thrown if the blob already exists. Returns:     The blob name of the uploaded object Example:     Read and upload a file to a Blob Storage container     <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureBlobStorageCredentials\nfrom prefect_azure.blob_storage import blob_storage_upload\n\n@flow\ndef example_blob_storage_upload_flow():\n    connection_string = \"connection_string\"\n    blob_storage_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    with open(\"data.csv\", \"rb\") as f:\n        blob = blob_storage_upload(\n            data=f.read(),\n            container=\"container\",\n            blob=\"data.csv\",\n            blob_storage_credentials=blob_storage_credentials,\n            overwrite=False,\n        )\n    return blob\n\nexample_blob_storage_upload_flow()\n</code></pre></p> Source code in <code>prefect_azure/blob_storage.py</code> <pre><code>@task\nasync def blob_storage_upload(\n    data: bytes,\n    container: str,\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    blob: str = None,\n    overwrite: bool = False,\n) -&gt; str:\n    \"\"\"\n    Uploads data to an Blob Storage container.\n    Args:\n        data: Bytes representation of data to upload to Blob Storage.\n        container: Name of the Blob Storage container to upload to.\n        blob_storage_credentials: Credentials to use for authentication with Azure.\n        blob: Name of the blob within this container to retrieve.\n        overwrite: If `True`, an existing blob with the same name will be overwritten.\n            Defaults to `False` and an error will be thrown if the blob already exists.\n    Returns:\n        The blob name of the uploaded object\n    Example:\n        Read and upload a file to a Blob Storage container\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureBlobStorageCredentials\n        from prefect_azure.blob_storage import blob_storage_upload\n\n        @flow\n        def example_blob_storage_upload_flow():\n            connection_string = \"connection_string\"\n            blob_storage_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            with open(\"data.csv\", \"rb\") as f:\n                blob = blob_storage_upload(\n                    data=f.read(),\n                    container=\"container\",\n                    blob=\"data.csv\",\n                    blob_storage_credentials=blob_storage_credentials,\n                    overwrite=False,\n                )\n            return blob\n\n        example_blob_storage_upload_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob to container %s with key %s\", container, blob)\n\n    # create key if not provided\n    if blob is None:\n        blob = str(uuid.uuid4())\n\n    async with blob_storage_credentials.get_blob_client(container, blob) as blob_client:\n        await blob_client.upload_blob(data, overwrite=overwrite)\n\n    return blob\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/","title":"Container Instance Block","text":""},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance","title":"<code>prefect_azure.container_instance</code>","text":"<p>Integrations with the Azure Container Instances service. Note this module is experimental. The interfaces within may change without notice.</p> <p>The <code>AzureContainerInstanceJob</code> infrastructure block in this module is ideally configured via the Prefect UI and run via a Prefect agent, but it can be called directly as demonstrated in the following examples.</p> <p>Examples:</p> <p>Run a command using an Azure Container Instances container. <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"]).run()\n</code></pre></p> <p>Run a command and stream the container's output to the local terminal. <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello world\"],\n    stream_output=True,\n)\n</code></pre></p> <p>Run a command with a specific image <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], image=\"alpine:latest\")\n</code></pre></p> <p>Run a task with custom memory and CPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0)\n</code></pre></p> <p>Run a task with custom memory and CPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0)\n</code></pre></p> <p>Run a task with custom memory, CPU, and GPU requirements <pre><code>AzureContainerInstanceJob(command=[\"echo\", \"hello world\"], memory=1.0, cpu=1.0,\ngpu_count=1, gpu_sku=\"V100\")\n</code></pre></p> <p>Run a task with custom environment variables <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello $PLANET\"],\n    env={\"PLANET\": \"earth\"}\n)\n</code></pre></p> <p>Run a task that uses a private ACR registry with a managed identity <pre><code>AzureContainerInstanceJob(\n    command=[\"echo\", \"hello $PLANET\"],\n    image=\"my-registry.azurecr.io/my-image\",\n    image_registry=ACRManagedIdentity(\n        registry_url=\"my-registry.azurecr.io\",\n        identity=\"/my/managed/identity/123abc\"\n    )\n)\n</code></pre></p>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ACRManagedIdentity","title":"<code>ACRManagedIdentity</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Use a Managed Identity to access Azure Container registry. Requires the user-assigned managed identity be available to the ACI container group.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ACRManagedIdentity(BaseModel):\n    \"\"\"\n    Use a Managed Identity to access Azure Container registry. Requires the\n    user-assigned managed identity be available to the ACI container group.\n    \"\"\"\n\n    registry_url: str = Field(\n        default=...,\n        title=\"Registry URL\",\n        description=(\n            \"The URL to the registry, such as myregistry.azurecr.io. Generally, 'http' \"\n            \"or 'https' can be omitted.\"\n        ),\n    )\n    identity: str = Field(\n        default=...,\n        description=(\n            \"The user-assigned Azure managed identity for the private registry.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob","title":"<code>AzureContainerInstanceJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Run a command using a container on Azure Container Instances. Note this block is experimental. The interface may change without notice.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=\"Use the AzureContainerWorker instead.\"\n    \" Refer to the upgrade guide for more information:\"\n    \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\",\n)\nclass AzureContainerInstanceJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Run a command using a container on Azure Container Instances.\n    Note this block is experimental. The interface may change without notice.\n    \"\"\"\n\n    _block_type_name = \"Azure Container Instance Job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob\"  # noqa\n\n    type: Literal[\"container-instance-job\"] = Field(\n        default=\"container-instance-job\", description=\"The slug for this task type.\"\n    )\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        default_factory=AzureContainerInstanceCredentials,\n        description=(\n            \"Credentials for Azure Container Instances; \"\n            \"if not provided will attempt to use DefaultAzureCredentials.\"\n        ),\n    )\n    resource_group_name: str = Field(\n        default=...,\n        title=\"Azure Resource Group Name\",\n        description=(\n            \"The name of the Azure Resource Group in which to run Prefect ACI tasks.\"\n        ),\n    )\n    subscription_id: SecretStr = Field(\n        default=...,\n        title=\"Azure Subscription ID\",\n        description=\"The ID of the Azure subscription to create containers under.\",\n    )\n    identities: Optional[List[str]] = Field(\n        title=\"Identities\",\n        default=None,\n        description=(\n            \"A list of user-assigned identities to associate with the container group. \"\n            \"The identities should be an ARM resource IDs in the form: \"\n            \"'/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.\"  # noqa\n        ),\n    )\n    image: Optional[str] = Field(\n        default_factory=get_prefect_image_name,\n        description=(\n            \"The image to use for the Prefect container in the task. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=DEFAULT_CONTAINER_ENTRYPOINT,\n        description=(\n            \"The entrypoint of the container you wish you run. This value \"\n            \"defaults to the entrypoint used by Prefect images and should only be \"\n            \"changed when using a custom image that is not based on an official \"\n            \"Prefect image. Any commands set on deployments will be passed \"\n            \"to the entrypoint as parameters.\"\n        ),\n    )\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(\n        default=None,\n        title=\"Image Registry (Optional)\",\n        description=(\n            \"To use any private container registry with a username and password, \"\n            \"choose DockerRegistry. To use a private Azure Container Registry \"\n            \"with a managed identity, choose ACRManagedIdentity.\"\n        ),\n    )\n    cpu: float = Field(\n        title=\"CPU\",\n        default=ACI_DEFAULT_CPU,\n        description=(\n            \"The number of virtual CPUs to assign to the task container. \"\n            f\"If not provided, a default value of {ACI_DEFAULT_CPU} will be used.\"\n        ),\n    )\n    gpu_count: Optional[int] = Field(\n        title=\"GPU Count\",\n        default=None,\n        description=(\n            \"The number of GPUs to assign to the task container. \"\n            \"If not provided, no GPU will be used.\"\n        ),\n    )\n    gpu_sku: Optional[str] = Field(\n        title=\"GPU SKU\",\n        default=None,\n        description=(\n            \"The Azure GPU SKU to use. See the ACI documentation for a list of \"\n            \"GPU SKUs available in each Azure region.\"\n        ),\n    )\n    memory: float = Field(\n        default=ACI_DEFAULT_MEMORY,\n        description=(\n            \"The amount of memory in gigabytes to provide to the ACI task. Valid \"\n            \"amounts are specified in the Azure documentation. If not provided, a \"\n            f\"default value of  {ACI_DEFAULT_MEMORY} will be used unless present \"\n            \"on the task definition.\"\n        ),\n    )\n    subnet_ids: Optional[List[str]] = Field(\n        default=None,\n        title=\"Subnet IDs\",\n        description=\"A list of Azure subnet IDs the container should be connected to.\",\n    )\n    dns_servers: Optional[List[str]] = Field(\n        default=None,\n        title=\"DNS Servers\",\n        description=\"A list of custom DNS Servers the container should use.\",\n    )\n    stream_output: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console.\"\n        ),\n    )\n    env: Dict[str, Optional[str]] = Field(\n        title=\"Environment Variables\",\n        default_factory=dict,\n        description=(\n            \"Environment variables to provide to the task run. These variables are set \"\n            \"on the Prefect container at task runtime. These will not be set on the \"\n            \"task definition.\"\n        ),\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=240,\n        description=(\n            \"The amount of time to watch for the start of the ACI container. \"\n            \"before marking it as failed.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The number of seconds to wait between Azure API calls while monitoring \"\n            \"the state of an Azure Container Instances task.\"\n        ),\n    )\n\n    @sync_compatible\n    async def run(\n        self, task_status: Optional[TaskStatus] = None\n    ) -&gt; AzureContainerInstanceJobResult:\n        \"\"\"\n        Runs the configured task using an ACI container.\n\n        Args:\n            task_status: An optional `TaskStatus` to update when the container starts.\n\n        Returns:\n            An `AzureContainerInstanceJobResult` with the container's exit code.\n        \"\"\"\n\n        run_start_time = datetime.datetime.now(datetime.timezone.utc)\n\n        container = self._configure_container()\n        container_group = self._configure_container_group(container)\n        created_container_group = None\n\n        aci_client = self.aci_credentials.get_container_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        self.logger.info(\n            f\"{self._log_prefix}: Preparing to run command {' '.join(self.command)!r} \"\n            f\"in container {container.name!r} ({self.image})...\"\n        )\n        try:\n            self.logger.info(f\"{self._log_prefix}: Waiting for container creation...\")\n            # Create the container group and wait for it to start\n            creation_status_poller = await run_sync_in_worker_thread(\n                aci_client.container_groups.begin_create_or_update,\n                self.resource_group_name,\n                container.name,\n                container_group,\n            )\n            created_container_group = await run_sync_in_worker_thread(\n                self._wait_for_task_container_start, creation_status_poller\n            )\n\n            # If creation succeeded, group provisioning state should be 'Succeeded'\n            # and the group should have a single container\n            if self._provisioning_succeeded(created_container_group):\n                self.logger.info(f\"{self._log_prefix}: Running command...\")\n                if task_status:\n                    task_status.started(value=created_container_group.name)\n                status_code = await run_sync_in_worker_thread(\n                    self._watch_task_and_get_exit_code,\n                    aci_client,\n                    created_container_group,\n                    run_start_time,\n                )\n                self.logger.info(f\"{self._log_prefix}: Completed command run.\")\n            else:\n                raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n        finally:\n            if created_container_group:\n                await self._wait_for_container_group_deletion(\n                    aci_client, created_container_group\n                )\n\n        return AzureContainerInstanceJobResult(\n            identifier=created_container_group.name, status_code=status_code\n        )\n\n    async def kill(\n        self,\n        container_group_name: str,\n        grace_seconds: int = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS,\n    ):\n        \"\"\"\n        Kill a flow running in an ACI container group.\n\n        Args:\n            container_group_name: The container group name yielded by\n                `AzureContainerInstanceJob.run`.\n        \"\"\"\n        # ACI does not provide a way to specify grace period, but it gives\n        # applications ~30 seconds to gracefully terminate before killing\n        # a container group.\n        if grace_seconds != CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS:\n            self.logger.warning(\n                f\"{self._log_prefix}: Kill grace period of {grace_seconds}s requested, \"\n                f\"but ACI does not support grace period configuration.\"\n            )\n\n        aci_client = self.aci_credentials.get_container_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        # get the container group to check that it still exists\n        try:\n            container_group = aci_client.container_groups.get(\n                resource_group_name=self.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        except ResourceNotFoundError as exc:\n            # the container group no longer exists, so there's nothing to cancel\n            raise InfrastructureNotFound(\n                f\"Cannot stop ACI job: container group {container_group_name} \"\n                \"no longer exists.\"\n            ) from exc\n\n        # get the container state to check if the container has terminated\n        container = self._get_container(container_group)\n        container_state = container.instance_view.current_state.state\n\n        # the container group needs to be deleted regardless of whether the container\n        # already terminated\n        await self._wait_for_container_group_deletion(aci_client, container_group)\n\n        # if the container had already terminated, raise an exception to let the agent\n        # know the flow was not cancelled\n        if container_state == ContainerRunState.TERMINATED:\n            raise InfrastructureNotAvailable(\n                f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n                f\"but container {container.name} has already terminated.\"\n            )\n\n    def preview(self) -&gt; str:\n        \"\"\"\n        Provides a summary of how the container will be created when `run` is called.\n\n        Returns:\n           A string containing the summary.\n        \"\"\"\n        preview = {\n            \"container_name\": \"&lt;generated when run&gt;\",\n            \"resource_group_name\": self.resource_group_name,\n            \"memory\": self.memory,\n            \"cpu\": self.cpu,\n            \"gpu_count\": self.gpu_count,\n            \"gpu_sku\": self.gpu_sku,\n            \"env\": self._get_environment(),\n        }\n\n        return json.dumps(preview)\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        from prefect_azure.workers.container_instance import AzureContainerWorker\n\n        return AzureContainerWorker.type\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for an `Azure Container Instance` work pool\n        with the same configuration as this block.\n\n        Returns:\n            - dict: a base job template for an `Azure Container Instance` work pool\n        \"\"\"\n        from prefect_azure.workers.container_instance import AzureContainerWorker\n\n        base_job_template = deepcopy(\n            AzureContainerWorker.get_default_base_job_template()\n        )\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"subscription_id\":\n                base_job_template[\"variables\"][\"properties\"][\"subscription_id\"][\n                    \"default\"\n                ] = value.get_secret_value()\n            elif key == \"aci_credentials\":\n                if not self.aci_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"aci_credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.aci_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"image_registry\":\n                if not self.image_registry._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"image_registry\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.image_registry._block_document_id)\n                    }\n                }\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by `Azure Container Instance`\"\n                    \" work pools. Skipping.\"\n                )\n\n        return base_job_template\n\n    def _configure_container(self) -&gt; Container:\n        \"\"\"\n        Configures an Azure `Container` using data from the block's fields.\n\n        Returns:\n            An instance of `Container` ready to submit to Azure.\n        \"\"\"\n\n        # setup container environment variables\n        environment = [\n            EnvironmentVariable(name=k, secure_value=v)\n            if k in ENV_SECRETS\n            else EnvironmentVariable(name=k, value=v)\n            for (k, v) in self._get_environment().items()\n        ]\n\n        # all container names in a resource group must be unique\n        if self.name:\n            slugified_name = slugify(\n                self.name,\n                max_length=52,\n                regex_pattern=r\"[^a-zA-Z0-9-]+\",\n            )\n            random_suffix = \"\".join(\n                random.choices(string.ascii_lowercase + string.digits, k=10)\n            )\n            container_name = slugified_name + \"-\" + random_suffix\n        else:\n            container_name = str(uuid.uuid4())\n\n        container_resource_requirements = self._configure_container_resources()\n\n        # add the entrypoint if provided, because creating an ACI container with a\n        # command overrides the container's built-in entrypoint.\n        if self.entrypoint:\n            self.command.insert(0, self.entrypoint)\n\n        return Container(\n            name=container_name,\n            image=self.image,\n            command=self.command,\n            resources=container_resource_requirements,\n            environment_variables=environment,\n        )\n\n    def _configure_container_resources(self) -&gt; ResourceRequirements:\n        \"\"\"\n        Configures the container's memory, CPU, and GPU resources.\n\n        Returns:\n            A `ResourceRequirements` instance initialized with data from this\n            `AzureContainerInstanceJob` block.\n        \"\"\"\n\n        gpu_resource = (\n            GpuResource(count=self.gpu_count, sku=self.gpu_sku)\n            if self.gpu_count and self.gpu_sku\n            else None\n        )\n        container_resource_requests = ResourceRequests(\n            memory_in_gb=self.memory, cpu=self.cpu, gpu=gpu_resource\n        )\n\n        return ResourceRequirements(requests=container_resource_requests)\n\n    def _configure_container_group(self, container: Container) -&gt; ContainerGroup:\n        \"\"\"\n        Configures the container group needed to start a container on ACI.\n\n        Args:\n            container: An initialized instance of `Container`.\n\n        Returns:\n            An initialized `ContainerGroup` ready to submit to Azure.\n        \"\"\"\n\n        # Load the resource group, so we can set the container group location\n        # correctly.\n\n        resource_group_client = self.aci_credentials.get_resource_client(\n            self.subscription_id.get_secret_value()\n        )\n\n        resource_group = resource_group_client.resource_groups.get(\n            self.resource_group_name\n        )\n\n        image_registry_credentials = self._create_image_registry_credentials(\n            self.image_registry\n        )\n\n        identity = (\n            ContainerGroupIdentity(\n                type=\"UserAssigned\",\n                # The Azure API only uses the dict keys and ignores values when\n                # creating a container group. Using empty `UserAssignedIdentities`\n                # instances as dict values satisfies Python type checkers.\n                user_assigned_identities={\n                    identity: UserAssignedIdentities() for identity in self.identities\n                },\n            )\n            if self.identities\n            else None\n        )\n\n        subnet_ids = (\n            [ContainerGroupSubnetId(id=subnet_id) for subnet_id in self.subnet_ids]\n            if self.subnet_ids\n            else None\n        )\n\n        dns_config = (\n            DnsConfiguration(name_servers=self.dns_servers)\n            if self.dns_servers\n            else None\n        )\n\n        return ContainerGroup(\n            location=resource_group.location,\n            identity=identity,\n            containers=[container],\n            os_type=OperatingSystemTypes.linux,\n            restart_policy=ContainerGroupRestartPolicy.never,\n            image_registry_credentials=image_registry_credentials,\n            subnet_ids=subnet_ids,\n            dns_config=dns_config,\n        )\n\n    @staticmethod\n    def _create_image_registry_credentials(\n        image_registry: Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n            None,\n        ],\n    ):\n        \"\"\"\n        Create image registry credentials based on the type of image_registry provided.\n\n        Args:\n            image_registry: An instance of a DockerRegistry or\n            ACRManagedIdentity object.\n\n        Returns:\n            A list containing an ImageRegistryCredential object if the input is a\n            `DockerRegistry` or `ACRManagedIdentity`, or None if the\n            input doesn't match any of the expected types.\n        \"\"\"\n        if image_registry and isinstance(\n            image_registry, prefect.infrastructure.container.DockerRegistry\n        ):\n            return [\n                ImageRegistryCredential(\n                    server=image_registry.registry_url,\n                    username=image_registry.username,\n                    password=image_registry.password.get_secret_value(),\n                )\n            ]\n        elif image_registry and isinstance(image_registry, ACRManagedIdentity):\n            return [\n                ImageRegistryCredential(\n                    server=image_registry.registry_url,\n                    identity=image_registry.identity,\n                )\n            ]\n        else:\n            return None\n\n    def _wait_for_task_container_start(\n        self, creation_status_poller: LROPoller[ContainerGroup]\n    ) -&gt; ContainerGroup:\n        \"\"\"\n        Wait for the result of group and container creation.\n\n        Args:\n            creation_status_poller: Poller returned by the Azure SDK.\n\n        Raises:\n            RuntimeError: Raised if the timeout limit is exceeded before the\n            container starts.\n\n        Returns:\n            A `ContainerGroup` representing the current status of the group being\n            watched.\n        \"\"\"\n\n        t0 = time.time()\n        timeout = self.task_start_timeout_seconds\n\n        while not creation_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while watching waiting for \"\n                        \"container start.\"\n                    )\n                )\n            time.sleep(self.task_watch_poll_interval)\n\n        return creation_status_poller.result()\n\n    def _watch_task_and_get_exit_code(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        run_start_time: datetime.datetime,\n    ) -&gt; int:\n        \"\"\"\n        Waits until the container finishes running and obtains its exit code.\n\n        Args:\n            client: An initialized Azure `ContainerInstanceManagementClient`\n            container_group: The `ContainerGroup` in which the container resides.\n\n        Returns:\n            An `int` representing the container's exit code.\n        \"\"\"\n\n        status_code = -1\n        running_container = self._get_container(container_group)\n        current_state = running_container.instance_view.current_state.state\n\n        # get any logs the container has already generated\n        last_log_time = run_start_time\n        if self.stream_output:\n            last_log_time = self._get_and_stream_output(\n                client, container_group, last_log_time\n            )\n\n        # set exit code if flow run already finished:\n        if current_state == ContainerRunState.TERMINATED:\n            status_code = running_container.instance_view.current_state.exit_code\n\n        while current_state != ContainerRunState.TERMINATED:\n            try:\n                container_group = client.container_groups.get(\n                    resource_group_name=self.resource_group_name,\n                    container_group_name=container_group.name,\n                )\n            except ResourceNotFoundError:\n                self.logger.exception(\n                    f\"{self._log_prefix}: Container group was deleted before flow run \"\n                    \"completed, likely due to flow cancellation.\"\n                )\n\n                # since the flow was cancelled, exit early instead of raising an\n                # exception\n                return status_code\n\n            container = self._get_container(container_group)\n            current_state = container.instance_view.current_state.state\n\n            if current_state == ContainerRunState.TERMINATED:\n                status_code = container.instance_view.current_state.exit_code\n                # break instead of waiting for next loop iteration because\n                # trying to read logs from a terminated container raises an exception\n                break\n\n            if self.stream_output:\n                last_log_time = self._get_and_stream_output(\n                    client, container_group, last_log_time\n                )\n\n            time.sleep(self.task_watch_poll_interval)\n\n        return status_code\n\n    async def _wait_for_container_group_deletion(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n    ):\n        self.logger.info(f\"{self._log_prefix}: Deleting container...\")\n\n        deletion_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_delete,\n            resource_group_name=self.resource_group_name,\n            container_group_name=container_group.name,\n        )\n\n        t0 = time.time()\n        timeout = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS\n\n        while not deletion_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while waiting for deletion of\"\n                        f\" container group {container_group.name}. To verify the group \"\n                        \"has been deleted, check the Azure Portal or run \"\n                        f\"az container show --name {container_group.name} --resource-group {self.resource_group_name}\"  # noqa\n                    )\n                )\n            await anyio.sleep(self.task_watch_poll_interval)\n\n        self.logger.info(f\"{self._log_prefix}: Container deleted.\")\n\n    def _get_container(self, container_group: ContainerGroup) -&gt; Container:\n        \"\"\"\n        Extracts the job container from a container group.\n        \"\"\"\n        return container_group.containers[0]\n\n    def _get_and_stream_output(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        last_log_time: datetime.datetime,\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Fetches logs output from the job container and writes all entries after\n        a given time to stderr.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        logs = self._get_logs(client, container_group)\n        return self._stream_output(logs, last_log_time)\n\n    def _get_logs(\n        self,\n        client: ContainerInstanceManagementClient,\n        container_group: ContainerGroup,\n        max_lines: int = 100,\n    ) -&gt; str:\n        \"\"\"\n        Gets the most container logs up to a given maximum.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            max_lines: The number of log lines to pull. Defaults to 100.\n\n        Returns:\n            A string containing the requested log entries, one per line.\n        \"\"\"\n        container = self._get_container(container_group)\n\n        logs: Union[Logs, None] = None\n        try:\n            logs = client.containers.list_logs(\n                resource_group_name=self.resource_group_name,\n                container_group_name=container_group.name,\n                container_name=container.name,\n                tail=max_lines,\n                timestamps=True,\n            )\n        except HttpResponseError:\n            # Trying to get logs when the container is under heavy CPU load sometimes\n            # results in an error, but we won't want to raise an exception and stop\n            # monitoring the flow. Instead, log the error and carry on so we can try to\n            # get all missed logs on the next check.\n            self.logger.warning(\n                f\"{self._log_prefix}: Unable to retrieve logs from container \"\n                f\"{container.name}. Trying again in {self.task_watch_poll_interval}s\"\n            )\n\n        return logs.content if logs else \"\"\n\n    def _stream_output(\n        self, log_content: Union[str, None], last_log_time: datetime.datetime\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Writes each entry from a string of log lines to stderr.\n\n        Args:\n            log_content: A string containing Azure container logs.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        if not log_content:\n            # nothing to stream\n            return last_log_time\n\n        log_lines = log_content.split(\"\\n\")\n\n        last_written_time = last_log_time\n\n        for log_line in log_lines:\n            # skip if the line is blank or whitespace\n            if not log_line.strip():\n                continue\n\n            line_parts = log_line.split(\" \")\n            # timestamp should always be before first space in line\n            line_timestamp = line_parts[0]\n            line = \" \".join(line_parts[1:])\n\n            try:\n                line_time = dateutil.parser.parse(line_timestamp)\n                if line_time &gt; last_written_time:\n                    self._write_output_line(line)\n                    last_written_time = line_time\n            except dateutil.parser.ParserError as e:\n                self.logger.debug(\n                    (\n                        f\"{self._log_prefix}: Unable to parse timestamp from Azure \"\n                        \"log line: %s\"\n                    ),\n                    log_line,\n                    exc_info=e,\n                )\n\n        return last_written_time\n\n    def _get_environment(self):\n        \"\"\"\n        Generates a dictionary of all environment variables to send to the\n        ACI container.\n        \"\"\"\n        return {**self._base_environment(), **self.env}\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"AzureContainerInstanceJob {self.name!r}\"\n        else:\n            return \"AzureContainerInstanceJob\"\n\n    @staticmethod\n    def _provisioning_succeeded(container_group: ContainerGroup) -&gt; bool:\n        \"\"\"\n        Determines whether ACI container group provisioning was successful.\n\n        Args:\n            container_group: a container group returned by the Azure SDK.\n\n        Returns:\n            True if provisioning was successful, False otherwise.\n        \"\"\"\n        if not container_group:\n            return False\n\n        return (\n            container_group.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n            and len(container_group.containers) == 1\n        )\n\n    @staticmethod\n    def _write_output_line(line: str):\n        \"\"\"\n        Writes a line of output to stderr.\n        \"\"\"\n        print(line, file=sys.stderr)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for an <code>Azure Container Instance</code> work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for an <code>Azure Container Instance</code> work pool</li> </ul> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for an `Azure Container Instance` work pool\n    with the same configuration as this block.\n\n    Returns:\n        - dict: a base job template for an `Azure Container Instance` work pool\n    \"\"\"\n    from prefect_azure.workers.container_instance import AzureContainerWorker\n\n    base_job_template = deepcopy(\n        AzureContainerWorker.get_default_base_job_template()\n    )\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n        ]:\n            continue\n        elif key == \"subscription_id\":\n            base_job_template[\"variables\"][\"properties\"][\"subscription_id\"][\n                \"default\"\n            ] = value.get_secret_value()\n        elif key == \"aci_credentials\":\n            if not self.aci_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"aci_credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.aci_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"image_registry\":\n            if not self.image_registry._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"image_registry\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(self.image_registry._block_document_id)\n                }\n            }\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by `Azure Container Instance`\"\n                \" work pools. Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    from prefect_azure.workers.container_instance import AzureContainerWorker\n\n    return AzureContainerWorker.type\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a flow running in an ACI container group.</p> <p>Parameters:</p> Name Type Description Default <code>container_group_name</code> <code>str</code> <p>The container group name yielded by <code>AzureContainerInstanceJob.run</code>.</p> required Source code in <code>prefect_azure/container_instance.py</code> <pre><code>async def kill(\n    self,\n    container_group_name: str,\n    grace_seconds: int = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS,\n):\n    \"\"\"\n    Kill a flow running in an ACI container group.\n\n    Args:\n        container_group_name: The container group name yielded by\n            `AzureContainerInstanceJob.run`.\n    \"\"\"\n    # ACI does not provide a way to specify grace period, but it gives\n    # applications ~30 seconds to gracefully terminate before killing\n    # a container group.\n    if grace_seconds != CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS:\n        self.logger.warning(\n            f\"{self._log_prefix}: Kill grace period of {grace_seconds}s requested, \"\n            f\"but ACI does not support grace period configuration.\"\n        )\n\n    aci_client = self.aci_credentials.get_container_client(\n        self.subscription_id.get_secret_value()\n    )\n\n    # get the container group to check that it still exists\n    try:\n        container_group = aci_client.container_groups.get(\n            resource_group_name=self.resource_group_name,\n            container_group_name=container_group_name,\n        )\n    except ResourceNotFoundError as exc:\n        # the container group no longer exists, so there's nothing to cancel\n        raise InfrastructureNotFound(\n            f\"Cannot stop ACI job: container group {container_group_name} \"\n            \"no longer exists.\"\n        ) from exc\n\n    # get the container state to check if the container has terminated\n    container = self._get_container(container_group)\n    container_state = container.instance_view.current_state.state\n\n    # the container group needs to be deleted regardless of whether the container\n    # already terminated\n    await self._wait_for_container_group_deletion(aci_client, container_group)\n\n    # if the container had already terminated, raise an exception to let the agent\n    # know the flow was not cancelled\n    if container_state == ContainerRunState.TERMINATED:\n        raise InfrastructureNotAvailable(\n            f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n            f\"but container {container.name} has already terminated.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.preview","title":"<code>preview</code>","text":"<p>Provides a summary of how the container will be created when <code>run</code> is called.</p> <p>Returns:</p> Type Description <code>str</code> <p>A string containing the summary.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"\n    Provides a summary of how the container will be created when `run` is called.\n\n    Returns:\n       A string containing the summary.\n    \"\"\"\n    preview = {\n        \"container_name\": \"&lt;generated when run&gt;\",\n        \"resource_group_name\": self.resource_group_name,\n        \"memory\": self.memory,\n        \"cpu\": self.cpu,\n        \"gpu_count\": self.gpu_count,\n        \"gpu_sku\": self.gpu_sku,\n        \"env\": self._get_environment(),\n    }\n\n    return json.dumps(preview)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs the configured task using an ACI container.</p> <p>Parameters:</p> Name Type Description Default <code>task_status</code> <code>Optional[TaskStatus]</code> <p>An optional <code>TaskStatus</code> to update when the container starts.</p> <code>None</code> <p>Returns:</p> Type Description <code>AzureContainerInstanceJobResult</code> <p>An <code>AzureContainerInstanceJobResult</code> with the container's exit code.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>@sync_compatible\nasync def run(\n    self, task_status: Optional[TaskStatus] = None\n) -&gt; AzureContainerInstanceJobResult:\n    \"\"\"\n    Runs the configured task using an ACI container.\n\n    Args:\n        task_status: An optional `TaskStatus` to update when the container starts.\n\n    Returns:\n        An `AzureContainerInstanceJobResult` with the container's exit code.\n    \"\"\"\n\n    run_start_time = datetime.datetime.now(datetime.timezone.utc)\n\n    container = self._configure_container()\n    container_group = self._configure_container_group(container)\n    created_container_group = None\n\n    aci_client = self.aci_credentials.get_container_client(\n        self.subscription_id.get_secret_value()\n    )\n\n    self.logger.info(\n        f\"{self._log_prefix}: Preparing to run command {' '.join(self.command)!r} \"\n        f\"in container {container.name!r} ({self.image})...\"\n    )\n    try:\n        self.logger.info(f\"{self._log_prefix}: Waiting for container creation...\")\n        # Create the container group and wait for it to start\n        creation_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_create_or_update,\n            self.resource_group_name,\n            container.name,\n            container_group,\n        )\n        created_container_group = await run_sync_in_worker_thread(\n            self._wait_for_task_container_start, creation_status_poller\n        )\n\n        # If creation succeeded, group provisioning state should be 'Succeeded'\n        # and the group should have a single container\n        if self._provisioning_succeeded(created_container_group):\n            self.logger.info(f\"{self._log_prefix}: Running command...\")\n            if task_status:\n                task_status.started(value=created_container_group.name)\n            status_code = await run_sync_in_worker_thread(\n                self._watch_task_and_get_exit_code,\n                aci_client,\n                created_container_group,\n                run_start_time,\n            )\n            self.logger.info(f\"{self._log_prefix}: Completed command run.\")\n        else:\n            raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n    finally:\n        if created_container_group:\n            await self._wait_for_container_group_deletion(\n                aci_client, created_container_group\n            )\n\n    return AzureContainerInstanceJobResult(\n        identifier=created_container_group.name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.AzureContainerInstanceJobResult","title":"<code>AzureContainerInstanceJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>The result of an <code>AzureContainerInstanceJob</code> run.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class AzureContainerInstanceJobResult(InfrastructureResult):\n    \"\"\"\n    The result of an `AzureContainerInstanceJob` run.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ContainerGroupProvisioningState","title":"<code>ContainerGroupProvisioningState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal provisioning states for ACI container groups. Per the Azure docs, the states in this Enum are the only ones that can be relied on as dependencies.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ContainerGroupProvisioningState(str, Enum):\n    \"\"\"\n    Terminal provisioning states for ACI container groups. Per the Azure docs,\n    the states in this Enum are the only ones that can be relied on as dependencies.\n    \"\"\"\n\n    SUCCEEDED = \"Succeeded\"\n    FAILED = \"Failed\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance/#prefect_azure.container_instance.ContainerRunState","title":"<code>ContainerRunState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal run states for ACI containers.</p> Source code in <code>prefect_azure/container_instance.py</code> <pre><code>class ContainerRunState(str, Enum):\n    \"\"\"\n    Terminal run states for ACI containers.\n    \"\"\"\n\n    RUNNING = \"Running\"\n    TERMINATED = \"Terminated\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/","title":"Container Instance Worker","text":""},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance","title":"<code>prefect_azure.workers.container_instance</code>","text":"<p>Module containing the Azure Container Instances worker used for executing flow runs in ACI containers.</p> <p>To start an ACI worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type azure-container-instance\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>Using a custom ARM template</p> <p>To facilitate easy customization, the Azure Container worker provisions a containing group using an ARM template. The default ARM template is represented in YAML as follows: <pre><code>---\narm_template:\n  \"$schema\": https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#\n  contentVersion: 1.0.0.0\n  parameters:\n    location:\n      type: string\n      defaultValue: \"[resourceGroup().location]\"\n      metadata:\n        description: Location for all resources.\n    container_group_name:\n      type: string\n      defaultValue: \"[uniqueString(resourceGroup().id)]\"\n      metadata:\n        description: The name of the container group to create.\n    container_name:\n      type: string\n      defaultValue: \"[uniqueString(resourceGroup().id)]\"\n      metadata:\n        description: The name of the container to create.\n  resources:\n  - type: Microsoft.ContainerInstance/containerGroups\n    apiVersion: '2022-09-01'\n    name: \"[parameters('container_group_name')]\"\n    location: \"[parameters('location')]\"\n    properties:\n      containers:\n      - name: \"[parameters('container_name')]\"\n        properties:\n          image: rpeden/my-aci-flow:latest\n          command: \"{{ command }}\"\n          resources:\n            requests:\n              cpu: \"{{ cpu }}\"\n              memoryInGB: \"{{ memory }}\"\n          environmentVariables: []\n      osType: Linux\n      restartPolicy: Never\n</code></pre></p> <p>Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job manifest and available variables can be customized on a work pool by work pool basis. These customizations can be made via the Prefect UI when creating or editing a work pool.</p> <p>Using an ARM template makes the worker flexible; you're not limited to using the features the worker provides out of the box. Instead, you can modify the ARM template to use any features available in Azure Container Instances.</p>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerJobConfiguration","title":"<code>AzureContainerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration for an Azure Container Instance flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration for an Azure Container Instance flow run.\n    \"\"\"\n\n    image: str = Field(default_factory=get_prefect_image_name)\n    resource_group_name: str = Field(default=...)\n    subscription_id: SecretStr = Field(default=...)\n    identities: Optional[List[str]] = Field(default=None)\n    entrypoint: Optional[str] = Field(default=DEFAULT_CONTAINER_ENTRYPOINT)\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(default=None)\n    cpu: float = Field(default=ACI_DEFAULT_CPU)\n    gpu_count: Optional[int] = Field(default=None)\n    gpu_sku: Optional[str] = Field(default=None)\n    memory: float = Field(default=ACI_DEFAULT_MEMORY)\n    subnet_ids: Optional[List[str]] = Field(default=None)\n    dns_servers: Optional[List[str]] = Field(default=None)\n    stream_output: bool = Field(default=False)\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        # default to an empty credentials object that will use\n        # `DefaultAzureCredential` to authenticate.\n        default_factory=AzureContainerInstanceCredentials\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(default=240)\n    task_watch_poll_interval: float = Field(default=5.0)\n    arm_template: Dict[str, Any] = Field(template=_get_default_arm_template())\n    keep_container_group: bool = Field(default=False)\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        # expectations:\n        # - the first resource in the template is the container group\n        # - the container group has a single container\n        container_group = self.arm_template[\"resources\"][0]\n        container = container_group[\"properties\"][\"containers\"][0]\n\n        # set the container's environment variables\n        container[\"properties\"][\"environmentVariables\"] = self._get_arm_environment()\n\n        # convert the command from a string to a list, because that's what ACI expects\n        if self.command:\n            container[\"properties\"][\"command\"] = self.command.split(\" \")\n\n        self._add_image()\n\n        # Add the entrypoint if provided. Creating an ACI container with a\n        # command overrides the container's built-in entrypoint. Prefect base images\n        # use entrypoint.sh as the entrypoint, so we need to add to the beginning of\n        # the command list to avoid breaking EXTRA_PIP_PACKAGES installation on\n        # container startup.\n        if self.entrypoint:\n            container[\"properties\"][\"command\"].insert(0, self.entrypoint)\n\n        if self.image_registry:\n            self._add_image_registry_credentials(self.image_registry)\n\n        if self.identities:\n            self._add_identities(self.identities)\n\n        if self.subnet_ids:\n            self._add_subnets(self.subnet_ids)\n\n        if self.dns_servers:\n            self._add_dns_servers(self.dns_servers)\n\n    def _add_image(self):\n        \"\"\"\n        Add the image to the arm template.\n        \"\"\"\n        try:\n            self.arm_template[\"resources\"][0][\"properties\"][\"containers\"][0][\n                \"properties\"\n            ][\"image\"] = self.image\n        except KeyError:\n            raise ValueError(\"Unable to add image due to invalid job ARM template.\")\n\n    def _add_image_registry_credentials(\n        self,\n        image_registry: Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n            None,\n        ],\n    ):\n        \"\"\"\n        Create image registry credentials based on the type of image_registry provided.\n\n        Args:\n            image_registry: An instance of a DockerRegistry or\n            ACRManagedIdentity object.\n        \"\"\"\n        if image_registry and isinstance(\n            image_registry, prefect.infrastructure.container.DockerRegistry\n        ):\n            self.arm_template[\"resources\"][0][\"properties\"][\n                \"imageRegistryCredentials\"\n            ] = [\n                {\n                    \"server\": image_registry.registry_url,\n                    \"username\": image_registry.username,\n                    \"password\": image_registry.password.get_secret_value(),\n                }\n            ]\n        elif image_registry and isinstance(image_registry, ACRManagedIdentity):\n            self.arm_template[\"resources\"][0][\"properties\"][\n                \"imageRegistryCredentials\"\n            ] = [\n                {\n                    \"server\": image_registry.registry_url,\n                    \"identity\": image_registry.identity,\n                }\n            ]\n\n    def _add_identities(self, identities: List[str]):\n        \"\"\"\n        Add identities to the container group.\n\n        Args:\n            identities: A list of user-assigned identities to add to\n            the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"identity\"] = {\n            \"type\": \"UserAssigned\",\n            \"userAssignedIdentities\": {\n                # note: For user-assigned identities, the key is the resource ID\n                # of the identity and the value is an empty object. See:\n                # https://docs.microsoft.com/en-us/azure/templates/microsoft.containerinstance/containergroups?tabs=bicep#identity-object # noqa\n                identity: {}\n                for identity in identities\n            },\n        }\n\n    def _add_subnets(self, subnet_ids: List[str]):\n        \"\"\"\n        Add subnets to the container group.\n\n        Args:\n            subnet_ids: A list of subnet ids to add to the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"properties\"][\"subnetIds\"] = [\n            {\"id\": subnet_id} for subnet_id in subnet_ids\n        ]\n\n    def _add_dns_servers(self, dns_servers: List[str]):\n        \"\"\"\n        Add dns servers to the container group.\n\n        Args:\n            dns_servers: A list of dns servers to add to the container group.\n        \"\"\"\n        self.arm_template[\"resources\"][0][\"properties\"][\"dnsConfig\"] = {\n            \"nameServers\": dns_servers\n        }\n\n    def _get_arm_environment(self):\n        \"\"\"\n        Returns the environment variables to pass to the ARM template.\n        \"\"\"\n        env = {**self._base_environment(), **self.env}\n\n        azure_env = [\n            {\"name\": key, \"secureValue\": value}\n            if key in ENV_SECRETS\n            else {\"name\": key, \"value\": value}\n            for key, value in env.items()\n        ]\n        return azure_env\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    # expectations:\n    # - the first resource in the template is the container group\n    # - the container group has a single container\n    container_group = self.arm_template[\"resources\"][0]\n    container = container_group[\"properties\"][\"containers\"][0]\n\n    # set the container's environment variables\n    container[\"properties\"][\"environmentVariables\"] = self._get_arm_environment()\n\n    # convert the command from a string to a list, because that's what ACI expects\n    if self.command:\n        container[\"properties\"][\"command\"] = self.command.split(\" \")\n\n    self._add_image()\n\n    # Add the entrypoint if provided. Creating an ACI container with a\n    # command overrides the container's built-in entrypoint. Prefect base images\n    # use entrypoint.sh as the entrypoint, so we need to add to the beginning of\n    # the command list to avoid breaking EXTRA_PIP_PACKAGES installation on\n    # container startup.\n    if self.entrypoint:\n        container[\"properties\"][\"command\"].insert(0, self.entrypoint)\n\n    if self.image_registry:\n        self._add_image_registry_credentials(self.image_registry)\n\n    if self.identities:\n        self._add_identities(self.identities)\n\n    if self.subnet_ids:\n        self._add_subnets(self.subnet_ids)\n\n    if self.dns_servers:\n        self._add_dns_servers(self.dns_servers)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerVariables","title":"<code>AzureContainerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Variables for an Azure Container Instance flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerVariables(BaseVariables):\n    \"\"\"\n    Variables for an Azure Container Instance flow run.\n    \"\"\"\n\n    image: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The image to use for the Prefect container in the task. This value \"\n            \"defaults to a Prefect base image matching your local versions.\"\n        ),\n    )\n    resource_group_name: str = Field(\n        default=...,\n        title=\"Azure Resource Group Name\",\n        description=(\n            \"The name of the Azure Resource Group in which to run Prefect ACI tasks.\"\n        ),\n    )\n    subscription_id: SecretStr = Field(\n        default=...,\n        title=\"Azure Subscription ID\",\n        description=\"The ID of the Azure subscription to create containers under.\",\n    )\n    identities: Optional[List[str]] = Field(\n        title=\"Identities\",\n        default=None,\n        description=(\n            \"A list of user-assigned identities to associate with the container group. \"\n            \"The identities should be an ARM resource IDs in the form: \"\n            \"'/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.\"  # noqa\n        ),\n    )\n    entrypoint: Optional[str] = Field(\n        default=DEFAULT_CONTAINER_ENTRYPOINT,\n        description=(\n            \"The entrypoint of the container you wish you run. This value \"\n            \"defaults to the entrypoint used by Prefect images and should only be \"\n            \"changed when using a custom image that is not based on an official \"\n            \"Prefect image. Any commands set on deployments will be passed \"\n            \"to the entrypoint as parameters.\"\n        ),\n    )\n    image_registry: Optional[\n        Union[\n            prefect.infrastructure.container.DockerRegistry,\n            ACRManagedIdentity,\n        ]\n    ] = Field(\n        default=None,\n        title=\"Image Registry (Optional)\",\n        description=(\n            \"To use any private container registry with a username and password, \"\n            \"choose DockerRegistry. To use a private Azure Container Registry \"\n            \"with a managed identity, choose ACRManagedIdentity.\"\n        ),\n    )\n    cpu: float = Field(\n        title=\"CPU\",\n        default=ACI_DEFAULT_CPU,\n        description=(\n            \"The number of virtual CPUs to assign to the task container. \"\n            f\"If not provided, a default value of {ACI_DEFAULT_CPU} will be used.\"\n        ),\n    )\n    gpu_count: Optional[int] = Field(\n        title=\"GPU Count\",\n        default=None,\n        description=(\n            \"The number of GPUs to assign to the task container. \"\n            \"If not provided, no GPU will be used.\"\n        ),\n    )\n    gpu_sku: Optional[str] = Field(\n        title=\"GPU SKU\",\n        default=None,\n        description=(\n            \"The Azure GPU SKU to use. See the ACI documentation for a list of \"\n            \"GPU SKUs available in each Azure region.\"\n        ),\n    )\n    memory: float = Field(\n        default=ACI_DEFAULT_MEMORY,\n        description=(\n            \"The amount of memory in gigabytes to provide to the ACI task. Valid \"\n            \"amounts are specified in the Azure documentation. If not provided, a \"\n            f\"default value of  {ACI_DEFAULT_MEMORY} will be used unless present \"\n            \"on the task definition.\"\n        ),\n    )\n    subnet_ids: Optional[List[str]] = Field(\n        title=\"Subnet IDs\",\n        default=None,\n        description=(\"A list of subnet IDs to associate with the container group. \"),\n    )\n    dns_servers: Optional[List[str]] = Field(\n        title=\"DNS Servers\",\n        default=None,\n        description=(\"A list of DNS servers to associate with the container group.\"),\n    )\n    aci_credentials: AzureContainerInstanceCredentials = Field(\n        default_factory=AzureContainerInstanceCredentials,\n        description=(\"The credentials to use to authenticate with Azure.\"),\n    )\n    stream_output: bool = Field(\n        default=False,\n        description=(\n            \"If `True`, logs will be streamed from the Prefect container to the local \"\n            \"console.\"\n        ),\n    )\n    # Execution settings\n    task_start_timeout_seconds: int = Field(\n        default=240,\n        description=(\n            \"The amount of time to watch for the start of the ACI container. \"\n            \"before marking it as failed.\"\n        ),\n    )\n    task_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The number of seconds to wait between Azure API calls while monitoring \"\n            \"the state of an Azure Container Instances task.\"\n        ),\n    )\n    keep_container_group: bool = Field(\n        default=False,\n        title=\"Keep Container Group After Completion\",\n        description=\"Keep the completed container group on Azure.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker","title":"<code>AzureContainerWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>A Prefect worker that runs flows in an Azure Container Instance.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerWorker(BaseWorker):\n    \"\"\"\n    A Prefect worker that runs flows in an Azure Container Instance.\n    \"\"\"\n\n    type = \"azure-container-instance\"\n    job_configuration = AzureContainerJobConfiguration\n    job_configuration_variables = AzureContainerVariables\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _display_name = \"Azure Container Instances\"\n    _description = (\n        \"Execute flow runs within containers on Azure's Container Instances \"\n        \"service. Requires an Azure account.\"\n    )\n    _documentation_url = (\n        \"https://prefecthq.github.io/prefect-azure/container_instance_worker/\"\n    )\n\n    async def run(\n        self,\n        flow_run: FlowRun,\n        configuration: AzureContainerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ):\n        \"\"\"\n        Run a flow in an Azure Container Instance.\n        Args:\n            flow_run: The flow run to run.\n            configuration: The configuration for the flow run.\n            task_status: The task status object for the current task. Used\n            to provide an identifier that can be used to cancel the task.\n\n        Returns:\n            The result of the flow run.\n        \"\"\"\n        run_start_time = datetime.datetime.now(datetime.timezone.utc)\n        prefect_client = get_client()\n\n        # Get the flow, so we can use its name in the container group name\n        # to make it easier to identify and debug.\n        flow = await prefect_client.read_flow(flow_run.flow_id)\n        container_group_name = f\"{flow.name}-{flow_run.id}\"\n\n        # Slugify flow.name if the generated name will be too long for the\n        # max deployment name length (64) including \"prefect-\"\n        if len(container_group_name) &gt; 55:\n            slugified_flow_name = slugify(\n                flow.name,\n                max_length=55 - len(str(flow_run.id)),\n                regex_pattern=r\"[^a-zA-Z0-9-]+\",\n            )\n            container_group_name = f\"{slugified_flow_name}-{flow_run.id}\"\n\n        self._logger.info(\n            f\"{self._log_prefix}: Preparing to run command {configuration.command} \"\n            f\"in container  {configuration.image})...\"\n        )\n\n        aci_client = configuration.aci_credentials.get_container_client(\n            configuration.subscription_id.get_secret_value()\n        )\n        resource_client = configuration.aci_credentials.get_resource_client(\n            configuration.subscription_id.get_secret_value()\n        )\n\n        created_container_group: Union[ContainerGroup, None] = None\n        try:\n            self._logger.info(f\"{self._log_prefix}: Creating container group...\")\n\n            created_container_group = await self._provision_container_group(\n                aci_client,\n                resource_client,\n                configuration,\n                container_group_name,\n            )\n            # Both the flow ID and container group name will be needed to\n            # cancel the flow run if needed.\n            identifier = f\"{flow_run.id}:{container_group_name}\"\n\n            if self._provisioning_succeeded(created_container_group):\n                self._logger.info(f\"{self._log_prefix}: Running command...\")\n                if task_status is not None:\n                    task_status.started(value=identifier)\n\n                status_code = await run_sync_in_worker_thread(\n                    self._watch_task_and_get_exit_code,\n                    aci_client,\n                    configuration,\n                    created_container_group,\n                    run_start_time,\n                )\n\n                self._logger.info(f\"{self._log_prefix}: Completed command run.\")\n\n            else:\n                raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n        finally:\n            if configuration.keep_container_group:\n                self._logger.info(f\"{self._log_prefix}: Stopping container group...\")\n                aci_client.container_groups.stop(\n                    resource_group_name=configuration.resource_group_name,\n                    container_group_name=container_group_name,\n                )\n            else:\n                await self._wait_for_container_group_deletion(\n                    aci_client, configuration, container_group_name\n                )\n\n        return AzureContainerWorkerResult(\n            identifier=created_container_group.name, status_code=status_code\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: AzureContainerJobConfiguration,\n    ):\n        \"\"\"\n        Kill a flow running in an ACI container group.\n\n        Args:\n            infrastructure_pid: The container group identification data yielded by\n                `AzureContainerInstanceJob.run`.\n            configuration: The job configuration.\n        \"\"\"\n        (flow_run_id, container_group_name) = infrastructure_pid.split(\":\")\n\n        aci_client = configuration.aci_credentials.get_container_client(\n            configuration.subscription_id.get_secret_value()\n        )\n\n        # get the container group to check that it still exists\n        try:\n            container_group = aci_client.container_groups.get(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        except ResourceNotFoundError as exc:\n            # the container group no longer exists, so there's nothing to cancel\n            raise InfrastructureNotFound(\n                f\"Cannot stop ACI job: container group \"\n                f\"{container_group_name} no longer exists.\"\n            ) from exc\n\n        # get the container state to check if the container has terminated\n        container = self._get_container(container_group)\n        container_state = container.instance_view.current_state.state\n\n        # the container group needs to be deleted regardless of whether the container\n        # already terminated\n        await self._wait_for_container_group_deletion(\n            aci_client, configuration, container_group_name\n        )\n\n        # if the container has already terminated, raise an exception to let the agent\n        # know the flow was not cancelled\n        if container_state == ContainerRunState.TERMINATED:\n            raise InfrastructureNotAvailable(\n                f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n                f\"but container {container.name} has already terminated.\"\n            )\n\n    def _wait_for_task_container_start(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n        creation_status_poller: LROPoller[DeploymentExtended],\n    ) -&gt; Optional[ContainerGroup]:\n        \"\"\"\n        Wait for the result of group and container creation.\n\n        Args:\n            creation_status_poller: Poller returned by the Azure SDK.\n\n        Raises:\n            RuntimeError: Raised if the timeout limit is exceeded before the\n            container starts.\n\n        Returns:\n            A `ContainerGroup` representing the current status of the group being\n            watched, or None if creation failed.\n        \"\"\"\n        t0 = time.time()\n        timeout = configuration.task_start_timeout_seconds\n\n        while not creation_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while watching waiting for \"\n                        \"container start.\"\n                    )\n                )\n            time.sleep(configuration.task_watch_poll_interval)\n\n        deployment = creation_status_poller.result()\n\n        provisioning_succeeded = (\n            deployment.properties.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n        )\n\n        if provisioning_succeeded:\n            return self._get_container_group(\n                client, configuration.resource_group_name, container_group_name\n            )\n        else:\n            return None\n\n    async def _provision_container_group(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        resource_client: ResourceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n    ):\n        \"\"\"\n        Create a container group and wait for it to start.\n        Args:\n            aci_client: An authenticated ACI client.\n            resource_client: An authenticated resource client.\n            configuration: The job configuration.\n            container_group_name: The name of the container group to create.\n\n        Returns:\n            A `ContainerGroup` representing the container group that was created.\n        \"\"\"\n        properties = DeploymentProperties(\n            mode=DeploymentMode.INCREMENTAL,\n            template=configuration.arm_template,\n            parameters={\"container_group_name\": {\"value\": container_group_name}},\n        )\n        deployment = Deployment(properties=properties)\n\n        creation_status_poller = await run_sync_in_worker_thread(\n            resource_client.deployments.begin_create_or_update,\n            resource_group_name=configuration.resource_group_name,\n            deployment_name=f\"prefect-{container_group_name}\",\n            parameters=deployment,\n        )\n\n        created_container_group = await run_sync_in_worker_thread(\n            self._wait_for_task_container_start,\n            aci_client,\n            configuration,\n            container_group_name,\n            creation_status_poller,\n        )\n\n        return created_container_group\n\n    def _watch_task_and_get_exit_code(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        run_start_time: datetime.datetime,\n    ) -&gt; int:\n        \"\"\"\n        Waits until the container finishes running and obtains its exit code.\n\n        Args:\n            client: An initialized Azure `ContainerInstanceManagementClient`\n            container_group: The `ContainerGroup` in which the container resides.\n\n        Returns:\n            An `int` representing the container's exit code.\n        \"\"\"\n        status_code = -1\n        running_container = self._get_container(container_group)\n        current_state = running_container.instance_view.current_state.state\n\n        # get any logs the container has already generated\n        last_log_time = run_start_time\n        if configuration.stream_output:\n            last_log_time = self._get_and_stream_output(\n                client=client,\n                configuration=configuration,\n                container_group=container_group,\n                last_log_time=last_log_time,\n            )\n\n        # set exit code if flow run already finished:\n        if current_state == ContainerRunState.TERMINATED:\n            status_code = running_container.instance_view.current_state.exit_code\n\n        while current_state != ContainerRunState.TERMINATED:\n            try:\n                container_group = self._get_container_group(\n                    client,\n                    configuration.resource_group_name,\n                    container_group.name,\n                )\n            except ResourceNotFoundError:\n                self._logger.exception(\n                    f\"{self._log_prefix}: Container group was deleted before flow run \"\n                    \"completed, likely due to flow cancellation.\"\n                )\n\n                # since the flow was cancelled, exit early instead of raising an\n                # exception\n                return status_code\n\n            container = self._get_container(container_group)\n            current_state = container.instance_view.current_state.state\n\n            if current_state == ContainerRunState.TERMINATED:\n                status_code = container.instance_view.current_state.exit_code\n                # break instead of waiting for next loop iteration because\n                # trying to read logs from a terminated container raises an exception\n                break\n\n            if configuration.stream_output:\n                last_log_time = self._get_and_stream_output(\n                    client=client,\n                    configuration=configuration,\n                    container_group=container_group,\n                    last_log_time=last_log_time,\n                )\n\n            time.sleep(configuration.task_watch_poll_interval)\n\n        return status_code\n\n    async def _wait_for_container_group_deletion(\n        self,\n        aci_client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group_name: str,\n    ):\n        \"\"\"\n        Wait for the container group to be deleted.\n        Args:\n            aci_client: An authenticated ACI client.\n            configuration: The job configuration.\n            container_group_name: The name of the container group to delete.\n        \"\"\"\n        self._logger.info(f\"{self._log_prefix}: Deleting container...\")\n\n        deletion_status_poller = await run_sync_in_worker_thread(\n            aci_client.container_groups.begin_delete,\n            resource_group_name=configuration.resource_group_name,\n            container_group_name=container_group_name,\n        )\n\n        t0 = time.time()\n        timeout = CONTAINER_GROUP_DELETION_TIMEOUT_SECONDS\n\n        while not deletion_status_poller.done():\n            elapsed_time = time.time() - t0\n\n            if timeout and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    (\n                        f\"Timed out after {elapsed_time}s while waiting for deletion of\"\n                        f\" container group {container_group_name}. To verify the group \"\n                        \"has been deleted, check the Azure Portal or run \"\n                        f\"az container show --name {container_group_name} --resource-group {configuration.resource_group_name}\"  # noqa\n                    )\n                )\n            await anyio.sleep(configuration.task_watch_poll_interval)\n\n        self._logger.info(f\"{self._log_prefix}: Container deleted.\")\n\n    def _get_container(self, container_group: ContainerGroup) -&gt; Container:\n        \"\"\"\n        Extracts the job container from a container group.\n        \"\"\"\n        return container_group.containers[0]\n\n    @staticmethod\n    def _get_container_group(\n        client: ContainerInstanceManagementClient,\n        resource_group_name: str,\n        container_group_name: str,\n    ) -&gt; ContainerGroup:\n        \"\"\"\n        Gets the container group from Azure.\n        \"\"\"\n        return client.container_groups.get(\n            resource_group_name=resource_group_name,\n            container_group_name=container_group_name,\n        )\n\n    def _get_and_stream_output(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        last_log_time: datetime.datetime,\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Fetches logs output from the job container and writes all entries after\n        a given time to stderr.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        logs = self._get_logs(\n            client=client, configuration=configuration, container_group=container_group\n        )\n        return self._stream_output(logs, last_log_time)\n\n    def _get_logs(\n        self,\n        client: ContainerInstanceManagementClient,\n        configuration: AzureContainerJobConfiguration,\n        container_group: ContainerGroup,\n        max_lines: int = 100,\n    ) -&gt; str:\n        \"\"\"\n        Gets the most container logs up to a given maximum.\n\n        Args:\n            client: An initialized `ContainerInstanceManagementClient`\n            container_group: The container group that holds the job container.\n            max_lines: The number of log lines to pull. Defaults to 100.\n\n        Returns:\n            A string containing the requested log entries, one per line.\n        \"\"\"\n        container = self._get_container(container_group)\n\n        logs: Union[Logs, None] = None\n        try:\n            logs = client.containers.list_logs(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group.name,\n                container_name=container.name,\n                tail=max_lines,\n                timestamps=True,\n            )\n        except HttpResponseError:\n            # Trying to get logs when the container is under heavy CPU load sometimes\n            # results in an error, but we won't want to raise an exception and stop\n            # monitoring the flow. Instead, log the error and carry on so we can try to\n            # get all missed logs on the next check.\n            self._logger.warning(\n                f\"{self._log_prefix}: Unable to retrieve logs from container \"\n                f\"{container.name}. Trying again in \"\n                f\"{configuration.task_watch_poll_interval}s\"\n            )\n\n        return logs.content if logs else \"\"\n\n    def _stream_output(\n        self, log_content: Union[str, None], last_log_time: datetime.datetime\n    ) -&gt; datetime.datetime:\n        \"\"\"\n        Writes each entry from a string of log lines to stderr.\n\n        Args:\n            log_content: A string containing Azure container logs.\n            last_log_time: The timestamp of the last output line already streamed.\n\n        Returns:\n            The time of the most recent output line written by this call.\n        \"\"\"\n        if not log_content:\n            # nothing to stream\n            return last_log_time\n\n        log_lines = log_content.split(\"\\n\")\n\n        last_written_time = last_log_time\n\n        for log_line in log_lines:\n            # skip if the line is blank or whitespace\n            if not log_line.strip():\n                continue\n\n            line_parts = log_line.split(\" \")\n            # timestamp should always be before first space in line\n            line_timestamp = line_parts[0]\n            line = \" \".join(line_parts[1:])\n\n            try:\n                line_time = dateutil.parser.parse(line_timestamp)\n                if line_time &gt; last_written_time:\n                    self._write_output_line(line)\n                    last_written_time = line_time\n            except dateutil.parser.ParserError as e:\n                self._logger.debug(\n                    (\n                        f\"{self._log_prefix}: Unable to parse timestamp from Azure \"\n                        \"log line: %s\"\n                    ),\n                    log_line,\n                    exc_info=e,\n                )\n\n        return last_written_time\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"AzureContainerInstanceJob {self.name!r}\"\n        else:\n            return \"AzureContainerInstanceJob\"\n\n    @staticmethod\n    def _provisioning_succeeded(container_group: Union[ContainerGroup, None]) -&gt; bool:\n        \"\"\"\n        Determines whether ACI container group provisioning was successful.\n\n        Args:\n            container_group: a container group returned by the Azure SDK.\n\n        Returns:\n            True if provisioning was successful, False otherwise.\n        \"\"\"\n        if not container_group:\n            return False\n\n        return (\n            container_group.provisioning_state\n            == ContainerGroupProvisioningState.SUCCEEDED\n            and len(container_group.containers) == 1\n        )\n\n    @staticmethod\n    def _write_output_line(line: str):\n        \"\"\"\n        Writes a line of output to stderr.\n        \"\"\"\n        print(line, file=sys.stderr)\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Kill a flow running in an ACI container group.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>The container group identification data yielded by <code>AzureContainerInstanceJob.run</code>.</p> required <code>configuration</code> <code>AzureContainerJobConfiguration</code> <p>The job configuration.</p> required Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: AzureContainerJobConfiguration,\n):\n    \"\"\"\n    Kill a flow running in an ACI container group.\n\n    Args:\n        infrastructure_pid: The container group identification data yielded by\n            `AzureContainerInstanceJob.run`.\n        configuration: The job configuration.\n    \"\"\"\n    (flow_run_id, container_group_name) = infrastructure_pid.split(\":\")\n\n    aci_client = configuration.aci_credentials.get_container_client(\n        configuration.subscription_id.get_secret_value()\n    )\n\n    # get the container group to check that it still exists\n    try:\n        container_group = aci_client.container_groups.get(\n            resource_group_name=configuration.resource_group_name,\n            container_group_name=container_group_name,\n        )\n    except ResourceNotFoundError as exc:\n        # the container group no longer exists, so there's nothing to cancel\n        raise InfrastructureNotFound(\n            f\"Cannot stop ACI job: container group \"\n            f\"{container_group_name} no longer exists.\"\n        ) from exc\n\n    # get the container state to check if the container has terminated\n    container = self._get_container(container_group)\n    container_state = container.instance_view.current_state.state\n\n    # the container group needs to be deleted regardless of whether the container\n    # already terminated\n    await self._wait_for_container_group_deletion(\n        aci_client, configuration, container_group_name\n    )\n\n    # if the container has already terminated, raise an exception to let the agent\n    # know the flow was not cancelled\n    if container_state == ContainerRunState.TERMINATED:\n        raise InfrastructureNotAvailable(\n            f\"Cannot stop ACI job: container group {container_group.name} exists, \"\n            f\"but container {container.name} has already terminated.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run a flow in an Azure Container Instance. Args:     flow_run: The flow run to run.     configuration: The configuration for the flow run.     task_status: The task status object for the current task. Used     to provide an identifier that can be used to cancel the task.</p> <p>Returns:</p> Type Description <p>The result of the flow run.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>async def run(\n    self,\n    flow_run: FlowRun,\n    configuration: AzureContainerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n):\n    \"\"\"\n    Run a flow in an Azure Container Instance.\n    Args:\n        flow_run: The flow run to run.\n        configuration: The configuration for the flow run.\n        task_status: The task status object for the current task. Used\n        to provide an identifier that can be used to cancel the task.\n\n    Returns:\n        The result of the flow run.\n    \"\"\"\n    run_start_time = datetime.datetime.now(datetime.timezone.utc)\n    prefect_client = get_client()\n\n    # Get the flow, so we can use its name in the container group name\n    # to make it easier to identify and debug.\n    flow = await prefect_client.read_flow(flow_run.flow_id)\n    container_group_name = f\"{flow.name}-{flow_run.id}\"\n\n    # Slugify flow.name if the generated name will be too long for the\n    # max deployment name length (64) including \"prefect-\"\n    if len(container_group_name) &gt; 55:\n        slugified_flow_name = slugify(\n            flow.name,\n            max_length=55 - len(str(flow_run.id)),\n            regex_pattern=r\"[^a-zA-Z0-9-]+\",\n        )\n        container_group_name = f\"{slugified_flow_name}-{flow_run.id}\"\n\n    self._logger.info(\n        f\"{self._log_prefix}: Preparing to run command {configuration.command} \"\n        f\"in container  {configuration.image})...\"\n    )\n\n    aci_client = configuration.aci_credentials.get_container_client(\n        configuration.subscription_id.get_secret_value()\n    )\n    resource_client = configuration.aci_credentials.get_resource_client(\n        configuration.subscription_id.get_secret_value()\n    )\n\n    created_container_group: Union[ContainerGroup, None] = None\n    try:\n        self._logger.info(f\"{self._log_prefix}: Creating container group...\")\n\n        created_container_group = await self._provision_container_group(\n            aci_client,\n            resource_client,\n            configuration,\n            container_group_name,\n        )\n        # Both the flow ID and container group name will be needed to\n        # cancel the flow run if needed.\n        identifier = f\"{flow_run.id}:{container_group_name}\"\n\n        if self._provisioning_succeeded(created_container_group):\n            self._logger.info(f\"{self._log_prefix}: Running command...\")\n            if task_status is not None:\n                task_status.started(value=identifier)\n\n            status_code = await run_sync_in_worker_thread(\n                self._watch_task_and_get_exit_code,\n                aci_client,\n                configuration,\n                created_container_group,\n                run_start_time,\n            )\n\n            self._logger.info(f\"{self._log_prefix}: Completed command run.\")\n\n        else:\n            raise RuntimeError(f\"{self._log_prefix}: Container creation failed.\")\n\n    finally:\n        if configuration.keep_container_group:\n            self._logger.info(f\"{self._log_prefix}: Stopping container group...\")\n            aci_client.container_groups.stop(\n                resource_group_name=configuration.resource_group_name,\n                container_group_name=container_group_name,\n            )\n        else:\n            await self._wait_for_container_group_deletion(\n                aci_client, configuration, container_group_name\n            )\n\n    return AzureContainerWorkerResult(\n        identifier=created_container_group.name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.AzureContainerWorkerResult","title":"<code>AzureContainerWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class AzureContainerWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.ContainerGroupProvisioningState","title":"<code>ContainerGroupProvisioningState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal provisioning states for ACI container groups. Per the Azure docs, the states in this Enum are the only ones that can be relied on as dependencies.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class ContainerGroupProvisioningState(str, Enum):\n    \"\"\"\n    Terminal provisioning states for ACI container groups. Per the Azure docs,\n    the states in this Enum are the only ones that can be relied on as dependencies.\n    \"\"\"\n\n    SUCCEEDED = \"Succeeded\"\n    FAILED = \"Failed\"\n</code></pre>"},{"location":"integrations/prefect-azure/container_instance_worker/#prefect_azure.workers.container_instance.ContainerRunState","title":"<code>ContainerRunState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Terminal run states for ACI containers.</p> Source code in <code>prefect_azure/workers/container_instance.py</code> <pre><code>class ContainerRunState(str, Enum):\n    \"\"\"\n    Terminal run states for ACI containers.\n    \"\"\"\n\n    RUNNING = \"Running\"\n    TERMINATED = \"Terminated\"\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/","title":"Cosmos DB","text":""},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db","title":"<code>prefect_azure.cosmos_db</code>","text":"<p>Tasks for interacting with Azure Cosmos DB</p>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_create_item","title":"<code>cosmos_db_create_item</code>  <code>async</code>","text":"<p>Create an item in the container.</p> <p>To update or replace an existing item, use the upsert_item method.</p> <p>Parameters:</p> Name Type Description Default <code>body</code> <code>Dict[str, Any]</code> <p>A dict-like object representing the item to create.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict representing the new item.</p> Example <p>Create an item in the container.</p> <p>To update or replace an existing item, use the upsert_item method. <pre><code>import uuid\n\nfrom prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_create_item\n\n@flow\ndef example_cosmos_db_create_item_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    body = {\n        \"firstname\": \"Olivia\",\n        \"age\": 3,\n        \"id\": str(uuid.uuid4())\n    }\n    container = \"Persons\"\n    database = \"SampleDB\"\n\n    result = cosmos_db_create_item(\n        body,\n        container,\n        database,\n        cosmos_db_credentials\n    )\n    return result\n\nexample_cosmos_db_create_item_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_create_item(\n    body: Dict[str, Any],\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    **kwargs: Any,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Create an item in the container.\n\n    To update or replace an existing item, use the upsert_item method.\n\n    Args:\n        body: A dict-like object representing the item to create.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        A dict representing the new item.\n\n    Example:\n        Create an item in the container.\n\n        To update or replace an existing item, use the upsert_item method.\n        ```python\n        import uuid\n\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_create_item\n\n        @flow\n        def example_cosmos_db_create_item_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            body = {\n                \"firstname\": \"Olivia\",\n                \"age\": 3,\n                \"id\": str(uuid.uuid4())\n            }\n            container = \"Persons\"\n            database = \"SampleDB\"\n\n            result = cosmos_db_create_item(\n                body,\n                container,\n                database,\n                cosmos_db_credentials\n            )\n            return result\n\n        example_cosmos_db_create_item_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Creating the item within container %s under %s database\",\n        container,\n        database,\n    )\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    create_item = partial(container_client.create_item, body, **kwargs)\n    result = await to_thread.run_sync(create_item)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_query_items","title":"<code>cosmos_db_query_items</code>  <code>async</code>","text":"<p>Return all results matching the given query.</p> <p>You can use any value for the container name in the FROM clause, but often the container name is used. In the examples below, the container name is \"products,\" and is aliased as \"p\" for easier referencing in the WHERE clause.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The Azure Cosmos DB SQL query to execute.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>parameters</code> <code>Optional[List[Dict[str, object]]]</code> <p>Optional array of parameters to the query. Each parameter is a dict() with 'name' and 'value' keys.</p> <code>None</code> <code>partition_key</code> <code>Optional[Any]</code> <p>Partition key for the item to retrieve.</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Union[str, dict]]</code> <p>An <code>list</code> of results.</p> Example <p>Query SampleDB Persons container where age &gt;= 44 <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_query_items\n\n@flow\ndef example_cosmos_db_query_items_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    query = \"SELECT * FROM c where c.age &gt;= @age\"\n    container = \"Persons\"\n    database = \"SampleDB\"\n    parameters = [dict(name=\"@age\", value=44)]\n\n    results = cosmos_db_query_items(\n        query,\n        container,\n        database,\n        cosmos_db_credentials,\n        parameters=parameters,\n        enable_cross_partition_query=True,\n    )\n    return results\n\nexample_cosmos_db_query_items_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_query_items(\n    query: str,\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    parameters: Optional[List[Dict[str, object]]] = None,\n    partition_key: Optional[Any] = None,\n    **kwargs: Any,\n) -&gt; List[Union[str, dict]]:\n    \"\"\"\n    Return all results matching the given query.\n\n    You can use any value for the container name in the FROM clause,\n    but often the container name is used.\n    In the examples below, the container name is \"products,\"\n    and is aliased as \"p\" for easier referencing in the WHERE clause.\n\n    Args:\n        query: The Azure Cosmos DB SQL query to execute.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        parameters: Optional array of parameters to the query.\n            Each parameter is a dict() with 'name' and 'value' keys.\n        partition_key: Partition key for the item to retrieve.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        An `list` of results.\n\n    Example:\n        Query SampleDB Persons container where age &gt;= 44\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_query_items\n\n        @flow\n        def example_cosmos_db_query_items_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            query = \"SELECT * FROM c where c.age &gt;= @age\"\n            container = \"Persons\"\n            database = \"SampleDB\"\n            parameters = [dict(name=\"@age\", value=44)]\n\n            results = cosmos_db_query_items(\n                query,\n                container,\n                database,\n                cosmos_db_credentials,\n                parameters=parameters,\n                enable_cross_partition_query=True,\n            )\n            return results\n\n        example_cosmos_db_query_items_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Running query from container %s in %s database\", container, database)\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    partial_query_items = partial(\n        container_client.query_items,\n        query,\n        parameters=parameters,\n        partition_key=partition_key,\n        **kwargs,\n    )\n    results = await to_thread.run_sync(partial_query_items)\n    return results\n</code></pre>"},{"location":"integrations/prefect-azure/cosmos_db/#prefect_azure.cosmos_db.cosmos_db_read_item","title":"<code>cosmos_db_read_item</code>  <code>async</code>","text":"<p>Get the item identified by item.</p> <p>Parameters:</p> Name Type Description Default <code>item</code> <code>Union[str, Dict[str, Any]]</code> <p>The ID (name) or dict representing item to retrieve.</p> required <code>partition_key</code> <code>Any</code> <p>Partition key for the item to retrieve.</p> required <code>container</code> <code>Union[str, ContainerProxy, Dict[str, Any]]</code> <p>The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.</p> required <code>database</code> <code>Union[str, DatabaseProxy, Dict[str, Any]]</code> <p>The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.</p> required <code>cosmos_db_credentials</code> <code>AzureCosmosDbCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>**kwargs</code> <code>Any</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Union[str, dict]]</code> <p>Dict representing the item to be retrieved.</p> Example <p>Read an item using a partition key from Cosmos DB. <pre><code>from prefect import flow\n\nfrom prefect_azure import AzureCosmosDbCredentials\nfrom prefect_azure.cosmos_db import cosmos_db_read_item\n\n@flow\ndef example_cosmos_db_read_item_flow():\n    connection_string = \"connection_string\"\n    cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n    item = \"item\"\n    partition_key = \"partition_key\"\n    container = \"container\"\n    database = \"database\"\n\n    result = cosmos_db_read_item(\n        item,\n        partition_key,\n        container,\n        database,\n        cosmos_db_credentials\n    )\n    return result\n\nexample_cosmos_db_read_item_flow()\n</code></pre></p> Source code in <code>prefect_azure/cosmos_db.py</code> <pre><code>@task\nasync def cosmos_db_read_item(\n    item: Union[str, Dict[str, Any]],\n    partition_key: Any,\n    container: Union[str, \"ContainerProxy\", Dict[str, Any]],\n    database: Union[str, \"DatabaseProxy\", Dict[str, Any]],\n    cosmos_db_credentials: AzureCosmosDbCredentials,\n    **kwargs: Any,\n) -&gt; List[Union[str, dict]]:\n    \"\"\"\n    Get the item identified by item.\n\n    Args:\n        item: The ID (name) or dict representing item to retrieve.\n        partition_key: Partition key for the item to retrieve.\n        container: The ID (name) of the container, a ContainerProxy instance,\n            or a dict representing the properties of the container to be retrieved.\n        database: The ID (name), dict representing the properties\n            or DatabaseProxy instance of the database to read.\n        cosmos_db_credentials: Credentials to use for authentication with Azure.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        Dict representing the item to be retrieved.\n\n    Example:\n        Read an item using a partition key from Cosmos DB.\n        ```python\n        from prefect import flow\n\n        from prefect_azure import AzureCosmosDbCredentials\n        from prefect_azure.cosmos_db import cosmos_db_read_item\n\n        @flow\n        def example_cosmos_db_read_item_flow():\n            connection_string = \"connection_string\"\n            cosmos_db_credentials = AzureCosmosDbCredentials(connection_string)\n\n            item = \"item\"\n            partition_key = \"partition_key\"\n            container = \"container\"\n            database = \"database\"\n\n            result = cosmos_db_read_item(\n                item,\n                partition_key,\n                container,\n                database,\n                cosmos_db_credentials\n            )\n            return result\n\n        example_cosmos_db_read_item_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Reading item %s with partition_key %s from container %s in %s database\",\n        item,\n        partition_key,\n        container,\n        database,\n    )\n\n    container_client = cosmos_db_credentials.get_container_client(container, database)\n    read_item = partial(container_client.read_item, item, partition_key, **kwargs)\n    result = await to_thread.run_sync(read_item)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials","title":"<code>prefect_azure.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with Azure</p>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials","title":"<code>AzureBlobStorageCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores credentials for authenticating with Azure Blob Storage.</p> <p>Parameters:</p> Name Type Description Default <code>account_url</code> <p>The URL for your Azure storage account. If provided, the account URL will be used to authenticate with the discovered default Azure credentials.</p> required <code>connection_string</code> <p>The connection string to your Azure storage account. If provided, the connection string will take precedence over the account URL.</p> required Example <p>Load stored Azure Blob Storage credentials and retrieve a blob service client: <pre><code>from prefect_azure import AzureBlobStorageCredentials\n\nazure_credentials_block = AzureBlobStorageCredentials.load(\"BLOCK_NAME\")\n\nblob_service_client = azure_credentials_block.get_blob_client()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureBlobStorageCredentials(Block):\n    \"\"\"\n    Stores credentials for authenticating with Azure Blob Storage.\n\n    Args:\n        account_url: The URL for your Azure storage account. If provided, the account\n            URL will be used to authenticate with the discovered default Azure\n            credentials.\n        connection_string: The connection string to your Azure storage account. If\n            provided, the connection string will take precedence over the account URL.\n\n    Example:\n        Load stored Azure Blob Storage credentials and retrieve a blob service client:\n        ```python\n        from prefect_azure import AzureBlobStorageCredentials\n\n        azure_credentials_block = AzureBlobStorageCredentials.load(\"BLOCK_NAME\")\n\n        blob_service_client = azure_credentials_block.get_blob_client()\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure Blob Storage Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials\"  # noqa\n\n    connection_string: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The connection string to your Azure storage account. If provided, the \"\n            \"connection string will take precedence over the account URL.\"\n        ),\n    )\n    account_url: Optional[str] = Field(\n        default=None,\n        title=\"Account URL\",\n        description=(\n            \"The URL for your Azure storage account. If provided, the account \"\n            \"URL will be used to authenticate with the discovered default \"\n            \"Azure credentials.\"\n        ),\n    )\n\n    @root_validator\n    def check_connection_string_or_account_url(\n        cls, values: Dict[str, Any]\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Checks that either a connection string or account URL is provided, not both.\n        \"\"\"\n        has_account_url = values.get(\"account_url\") is not None\n        has_conn_str = values.get(\"connection_string\") is not None\n        if not has_account_url and not has_conn_str:\n            raise ValueError(\n                \"Must provide either a connection string or an account URL.\"\n            )\n        if has_account_url and has_conn_str:\n            raise ValueError(\n                \"Must provide either a connection string or account URL, but not both.\"\n            )\n        return values\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_client(self) -&gt; \"BlobServiceClient\":\n        \"\"\"\n        Returns an authenticated base Blob Service client that can be used to create\n        other clients for Azure services.\n\n        Example:\n            Create an authorized Blob Service session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_client() as blob_service_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return BlobServiceClient(\n                account_url=self.account_url,\n                credential=ADefaultAzureCredential(),\n            )\n\n        return BlobServiceClient.from_connection_string(\n            self.connection_string.get_secret_value()\n        )\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_blob_client(self, container, blob) -&gt; \"BlobClient\":\n        \"\"\"\n        Returns an authenticated Blob client that can be used to\n        download and upload blobs.\n\n        Args:\n            container: Name of the Blob Storage container to retrieve from.\n            blob: Name of the blob within this container to retrieve.\n\n        Example:\n            Create an authorized Blob session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_blob_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_blob_client(\n                    \"container\", \"blob\"\n                ) as blob_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_blob_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return BlobClient(\n                account_url=self.account_url,\n                container_name=container,\n                credential=ADefaultAzureCredential(),\n                blob_name=blob,\n            )\n\n        blob_client = BlobClient.from_connection_string(\n            self.connection_string.get_secret_value(), container, blob\n        )\n        return blob_client\n\n    @_raise_help_msg(\"blob_storage\")\n    def get_container_client(self, container) -&gt; \"ContainerClient\":\n        \"\"\"\n        Returns an authenticated Container client that can be used to create clients\n        for Azure services.\n\n        Args:\n            container: Name of the Blob Storage container to retrieve from.\n\n        Example:\n            Create an authorized Container session\n            ```python\n            import os\n            import asyncio\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            async def example_get_container_client_flow():\n                connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n                azure_credentials = AzureBlobStorageCredentials(\n                    connection_string=connection_string,\n                )\n                async with azure_credentials.get_container_client(\n                    \"container\"\n                ) as container_client:\n                    # run other code here\n                    pass\n\n            asyncio.run(example_get_container_client_flow())\n            ```\n        \"\"\"\n        if self.connection_string is None:\n            return ContainerClient(\n                account_url=self.account_url,\n                container_name=container,\n                credential=ADefaultAzureCredential(),\n            )\n\n        container_client = ContainerClient.from_connection_string(\n            self.connection_string.get_secret_value(), container\n        )\n        return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.check_connection_string_or_account_url","title":"<code>check_connection_string_or_account_url</code>","text":"<p>Checks that either a connection string or account URL is provided, not both.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@root_validator\ndef check_connection_string_or_account_url(\n    cls, values: Dict[str, Any]\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Checks that either a connection string or account URL is provided, not both.\n    \"\"\"\n    has_account_url = values.get(\"account_url\") is not None\n    has_conn_str = values.get(\"connection_string\") is not None\n    if not has_account_url and not has_conn_str:\n        raise ValueError(\n            \"Must provide either a connection string or an account URL.\"\n        )\n    if has_account_url and has_conn_str:\n        raise ValueError(\n            \"Must provide either a connection string or account URL, but not both.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_blob_client","title":"<code>get_blob_client</code>","text":"<p>Returns an authenticated Blob client that can be used to download and upload blobs.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <p>Name of the Blob Storage container to retrieve from.</p> required <code>blob</code> <p>Name of the blob within this container to retrieve.</p> required Example <p>Create an authorized Blob session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_blob_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_blob_client(\n        \"container\", \"blob\"\n    ) as blob_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_blob_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_blob_client(self, container, blob) -&gt; \"BlobClient\":\n    \"\"\"\n    Returns an authenticated Blob client that can be used to\n    download and upload blobs.\n\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n        blob: Name of the blob within this container to retrieve.\n\n    Example:\n        Create an authorized Blob session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_blob_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_blob_client(\n                \"container\", \"blob\"\n            ) as blob_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_blob_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return BlobClient(\n            account_url=self.account_url,\n            container_name=container,\n            credential=ADefaultAzureCredential(),\n            blob_name=blob,\n        )\n\n    blob_client = BlobClient.from_connection_string(\n        self.connection_string.get_secret_value(), container, blob\n    )\n    return blob_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated base Blob Service client that can be used to create other clients for Azure services.</p> Example <p>Create an authorized Blob Service session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_client() as blob_service_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_client(self) -&gt; \"BlobServiceClient\":\n    \"\"\"\n    Returns an authenticated base Blob Service client that can be used to create\n    other clients for Azure services.\n\n    Example:\n        Create an authorized Blob Service session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_client() as blob_service_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return BlobServiceClient(\n            account_url=self.account_url,\n            credential=ADefaultAzureCredential(),\n        )\n\n    return BlobServiceClient.from_connection_string(\n        self.connection_string.get_secret_value()\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureBlobStorageCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Returns an authenticated Container client that can be used to create clients for Azure services.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <p>Name of the Blob Storage container to retrieve from.</p> required Example <p>Create an authorized Container session <pre><code>import os\nimport asyncio\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\nasync def example_get_container_client_flow():\n    connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n    azure_credentials = AzureBlobStorageCredentials(\n        connection_string=connection_string,\n    )\n    async with azure_credentials.get_container_client(\n        \"container\"\n    ) as container_client:\n        # run other code here\n        pass\n\nasyncio.run(example_get_container_client_flow())\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"blob_storage\")\ndef get_container_client(self, container) -&gt; \"ContainerClient\":\n    \"\"\"\n    Returns an authenticated Container client that can be used to create clients\n    for Azure services.\n\n    Args:\n        container: Name of the Blob Storage container to retrieve from.\n\n    Example:\n        Create an authorized Container session\n        ```python\n        import os\n        import asyncio\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        async def example_get_container_client_flow():\n            connection_string = os.getenv(\"AZURE_STORAGE_CONNECTION_STRING\")\n            azure_credentials = AzureBlobStorageCredentials(\n                connection_string=connection_string,\n            )\n            async with azure_credentials.get_container_client(\n                \"container\"\n            ) as container_client:\n                # run other code here\n                pass\n\n        asyncio.run(example_get_container_client_flow())\n        ```\n    \"\"\"\n    if self.connection_string is None:\n        return ContainerClient(\n            account_url=self.account_url,\n            container_name=container,\n            credential=ADefaultAzureCredential(),\n        )\n\n    container_client = ContainerClient.from_connection_string(\n        self.connection_string.get_secret_value(), container\n    )\n    return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials","title":"<code>AzureContainerInstanceCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Azure Container Instances authentication. Stores Azure Service Principal authentication data.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureContainerInstanceCredentials(Block):\n    \"\"\"\n    Block used to manage Azure Container Instances authentication. Stores Azure Service\n    Principal authentication data.\n    \"\"\"\n\n    _block_type_name = \"Azure Container Instance Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials\"  # noqa\n\n    client_id: Optional[str] = Field(\n        default=None,\n        title=\"Client ID\",\n        description=(\n            \"The service principal client ID. \"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    tenant_id: Optional[str] = Field(\n        default=None,\n        title=\"Tenant ID\",\n        description=(\n            \"The service principal tenant ID.\"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    client_secret: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The service principal client secret.\"\n            \"If none of client_id, tenant_id, and client_secret are provided, \"\n            \"will use DefaultAzureCredential; else will need to provide all three to \"\n            \"use ClientSecretCredential.\"\n        ),\n    )\n    credential_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional Credential Keyword Arguments\",\n        description=(\n            \"Additional keyword arguments to pass to \"\n            \"`ClientSecretCredential` or `DefaultAzureCredential`.\"\n        ),\n    )\n\n    @root_validator\n    def validate_credential_kwargs(cls, values):\n        \"\"\"\n        Validates that if any of `client_id`, `tenant_id`, or `client_secret` are\n        provided, all must be provided.\n        \"\"\"\n        auth_args = (\"client_id\", \"tenant_id\", \"client_secret\")\n        has_any = any(values.get(key) is not None for key in auth_args)\n        has_all = all(values.get(key) is not None for key in auth_args)\n        if has_any and not has_all:\n            raise ValueError(\n                \"If any of `client_id`, `tenant_id`, or `client_secret` are provided, \"\n                \"all must be provided.\"\n            )\n        return values\n\n    def get_container_client(self, subscription_id: str):\n        \"\"\"\n        Creates an Azure Container Instances client initialized with data from\n        this block's fields and a provided Azure subscription ID.\n\n        Args:\n            subscription_id: A valid Azure subscription ID.\n\n        Returns:\n            An initialized `ContainerInstanceManagementClient`\n        \"\"\"\n\n        return ContainerInstanceManagementClient(\n            credential=self._create_credential(),\n            subscription_id=subscription_id,\n        )\n\n    def get_resource_client(self, subscription_id: str):\n        \"\"\"\n        Creates an Azure resource management client initialized with data from\n        this block's fields and a provided Azure subscription ID.\n\n        Args:\n            subscription_id: A valid Azure subscription ID.\n\n        Returns:\n            An initialized `ResourceManagementClient`\n        \"\"\"\n\n        return ResourceManagementClient(\n            credential=self._create_credential(),\n            subscription_id=subscription_id,\n        )\n\n    def _create_credential(self):\n        \"\"\"\n        Creates an Azure credential initialized with data from this block's fields.\n\n        Returns:\n            An initialized Azure `TokenCredential` ready to use with Azure SDK client\n            classes.\n        \"\"\"\n        auth_args = (self.client_id, self.tenant_id, self.client_secret)\n        if auth_args == (None, None, None):\n            return DefaultAzureCredential(**self.credential_kwargs)\n\n        return ClientSecretCredential(\n            tenant_id=self.tenant_id,\n            client_id=self.client_id,\n            client_secret=self.client_secret.get_secret_value(),\n            **self.credential_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Creates an Azure Container Instances client initialized with data from this block's fields and a provided Azure subscription ID.</p> <p>Parameters:</p> Name Type Description Default <code>subscription_id</code> <code>str</code> <p>A valid Azure subscription ID.</p> required <p>Returns:</p> Type Description <p>An initialized <code>ContainerInstanceManagementClient</code></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_container_client(self, subscription_id: str):\n    \"\"\"\n    Creates an Azure Container Instances client initialized with data from\n    this block's fields and a provided Azure subscription ID.\n\n    Args:\n        subscription_id: A valid Azure subscription ID.\n\n    Returns:\n        An initialized `ContainerInstanceManagementClient`\n    \"\"\"\n\n    return ContainerInstanceManagementClient(\n        credential=self._create_credential(),\n        subscription_id=subscription_id,\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.get_resource_client","title":"<code>get_resource_client</code>","text":"<p>Creates an Azure resource management client initialized with data from this block's fields and a provided Azure subscription ID.</p> <p>Parameters:</p> Name Type Description Default <code>subscription_id</code> <code>str</code> <p>A valid Azure subscription ID.</p> required <p>Returns:</p> Type Description <p>An initialized <code>ResourceManagementClient</code></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_resource_client(self, subscription_id: str):\n    \"\"\"\n    Creates an Azure resource management client initialized with data from\n    this block's fields and a provided Azure subscription ID.\n\n    Args:\n        subscription_id: A valid Azure subscription ID.\n\n    Returns:\n        An initialized `ResourceManagementClient`\n    \"\"\"\n\n    return ResourceManagementClient(\n        credential=self._create_credential(),\n        subscription_id=subscription_id,\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureContainerInstanceCredentials.validate_credential_kwargs","title":"<code>validate_credential_kwargs</code>","text":"<p>Validates that if any of <code>client_id</code>, <code>tenant_id</code>, or <code>client_secret</code> are provided, all must be provided.</p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@root_validator\ndef validate_credential_kwargs(cls, values):\n    \"\"\"\n    Validates that if any of `client_id`, `tenant_id`, or `client_secret` are\n    provided, all must be provided.\n    \"\"\"\n    auth_args = (\"client_id\", \"tenant_id\", \"client_secret\")\n    has_any = any(values.get(key) is not None for key in auth_args)\n    has_all = all(values.get(key) is not None for key in auth_args)\n    if has_any and not has_all:\n        raise ValueError(\n            \"If any of `client_id`, `tenant_id`, or `client_secret` are provided, \"\n            \"all must be provided.\"\n        )\n    return values\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials","title":"<code>AzureCosmosDbCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Cosmos DB authentication with Azure. Azure authentication is handled via the <code>azure</code> module through a connection string.</p> <p>Parameters:</p> Name Type Description Default <code>connection_string</code> <p>Includes the authorization information required.</p> required Example <p>Load stored Azure Cosmos DB credentials: <pre><code>from prefect_azure import AzureCosmosDbCredentials\nazure_credentials_block = AzureCosmosDbCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureCosmosDbCredentials(Block):\n    \"\"\"\n    Block used to manage Cosmos DB authentication with Azure.\n    Azure authentication is handled via the `azure` module through\n    a connection string.\n\n    Args:\n        connection_string: Includes the authorization information required.\n\n    Example:\n        Load stored Azure Cosmos DB credentials:\n        ```python\n        from prefect_azure import AzureCosmosDbCredentials\n        azure_credentials_block = AzureCosmosDbCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Azure Cosmos DB Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials\"  # noqa\n\n    connection_string: SecretStr = Field(\n        default=..., description=\"Includes the authorization information required.\"\n    )\n\n    @_raise_help_msg(\"cosmos_db\")\n    def get_client(self) -&gt; \"CosmosClient\":\n        \"\"\"\n        Returns an authenticated Cosmos client that can be used to create\n        other clients for Azure services.\n\n        Example:\n            Create an authorized Cosmos session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureCosmosDbCredentials\n\n            @flow\n            def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                cosmos_client = azure_credentials.get_client()\n                return cosmos_client\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        return CosmosClient.from_connection_string(\n            self.connection_string.get_secret_value()\n        )\n\n    def get_database_client(self, database: str) -&gt; \"DatabaseProxy\":\n        \"\"\"\n        Returns an authenticated Database client.\n\n        Args:\n            database: Name of the database.\n\n        Example:\n            Create an authorized Cosmos session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureCosmosDbCredentials\n\n            @flow\n            def example_get_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                cosmos_client = azure_credentials.get_database_client()\n                return cosmos_client\n\n            example_get_database_client_flow()\n            ```\n        \"\"\"\n        cosmos_client = self.get_client()\n        database_client = cosmos_client.get_database_client(database=database)\n        return database_client\n\n    def get_container_client(self, container: str, database: str) -&gt; \"ContainerProxy\":\n        \"\"\"\n        Returns an authenticated Container client used for querying.\n\n        Args:\n            container: Name of the Cosmos DB container to retrieve from.\n            database: Name of the Cosmos DB database.\n\n        Example:\n            Create an authorized Container session\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureBlobStorageCredentials\n\n            @flow\n            def example_get_container_client_flow():\n                connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n                azure_credentials = AzureCosmosDbCredentials(\n                    connection_string=connection_string,\n                )\n                container_client = azure_credentials.get_container_client(container)\n                return container_client\n\n            example_get_container_client_flow()\n            ```\n        \"\"\"\n        database_client = self.get_database_client(database)\n        container_client = database_client.get_container_client(container=container)\n        return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated Cosmos client that can be used to create other clients for Azure services.</p> Example <p>Create an authorized Cosmos session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureCosmosDbCredentials\n\n@flow\ndef example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    cosmos_client = azure_credentials.get_client()\n    return cosmos_client\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"cosmos_db\")\ndef get_client(self) -&gt; \"CosmosClient\":\n    \"\"\"\n    Returns an authenticated Cosmos client that can be used to create\n    other clients for Azure services.\n\n    Example:\n        Create an authorized Cosmos session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureCosmosDbCredentials\n\n        @flow\n        def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            cosmos_client = azure_credentials.get_client()\n            return cosmos_client\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    return CosmosClient.from_connection_string(\n        self.connection_string.get_secret_value()\n    )\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_container_client","title":"<code>get_container_client</code>","text":"<p>Returns an authenticated Container client used for querying.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>Name of the Cosmos DB container to retrieve from.</p> required <code>database</code> <code>str</code> <p>Name of the Cosmos DB database.</p> required Example <p>Create an authorized Container session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureBlobStorageCredentials\n\n@flow\ndef example_get_container_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    container_client = azure_credentials.get_container_client(container)\n    return container_client\n\nexample_get_container_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_container_client(self, container: str, database: str) -&gt; \"ContainerProxy\":\n    \"\"\"\n    Returns an authenticated Container client used for querying.\n\n    Args:\n        container: Name of the Cosmos DB container to retrieve from.\n        database: Name of the Cosmos DB database.\n\n    Example:\n        Create an authorized Container session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureBlobStorageCredentials\n\n        @flow\n        def example_get_container_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            container_client = azure_credentials.get_container_client(container)\n            return container_client\n\n        example_get_container_client_flow()\n        ```\n    \"\"\"\n    database_client = self.get_database_client(database)\n    container_client = database_client.get_container_client(container=container)\n    return container_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureCosmosDbCredentials.get_database_client","title":"<code>get_database_client</code>","text":"<p>Returns an authenticated Database client.</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>str</code> <p>Name of the database.</p> required Example <p>Create an authorized Cosmos session <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureCosmosDbCredentials\n\n@flow\ndef example_get_client_flow():\n    connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n    azure_credentials = AzureCosmosDbCredentials(\n        connection_string=connection_string,\n    )\n    cosmos_client = azure_credentials.get_database_client()\n    return cosmos_client\n\nexample_get_database_client_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>def get_database_client(self, database: str) -&gt; \"DatabaseProxy\":\n    \"\"\"\n    Returns an authenticated Database client.\n\n    Args:\n        database: Name of the database.\n\n    Example:\n        Create an authorized Cosmos session\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureCosmosDbCredentials\n\n        @flow\n        def example_get_client_flow():\n            connection_string = os.getenv(\"AZURE_COSMOS_CONNECTION_STRING\")\n            azure_credentials = AzureCosmosDbCredentials(\n                connection_string=connection_string,\n            )\n            cosmos_client = azure_credentials.get_database_client()\n            return cosmos_client\n\n        example_get_database_client_flow()\n        ```\n    \"\"\"\n    cosmos_client = self.get_client()\n    database_client = cosmos_client.get_database_client(database=database)\n    return database_client\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials","title":"<code>AzureMlCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage authentication with AzureML. Azure authentication is handled via the <code>azure</code> module.</p> <p>Parameters:</p> Name Type Description Default <code>tenant_id</code> <p>The active directory tenant that the service identity belongs to.</p> required <code>service_principal_id</code> <p>The service principal ID.</p> required <code>service_principal_password</code> <p>The service principal password/key.</p> required <code>subscription_id</code> <p>The Azure subscription ID containing the workspace.</p> required <code>resource_group</code> <p>The resource group containing the workspace.</p> required <code>workspace_name</code> <p>The existing workspace name.</p> required Example <p>Load stored AzureML credentials: <pre><code>from prefect_azure import AzureMlCredentials\nazure_ml_credentials_block = AzureMlCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>class AzureMlCredentials(Block):\n    \"\"\"\n    Block used to manage authentication with AzureML. Azure authentication is\n    handled via the `azure` module.\n\n    Args:\n        tenant_id: The active directory tenant that the service identity belongs to.\n        service_principal_id: The service principal ID.\n        service_principal_password: The service principal password/key.\n        subscription_id: The Azure subscription ID containing the workspace.\n        resource_group: The resource group containing the workspace.\n        workspace_name: The existing workspace name.\n\n    Example:\n        Load stored AzureML credentials:\n        ```python\n        from prefect_azure import AzureMlCredentials\n        azure_ml_credentials_block = AzureMlCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"AzureML Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/54e3fa7e00197a4fbd1d82ed62494cb58d08c96a-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials\"  # noqa\n\n    tenant_id: str = Field(\n        default=...,\n        description=\"The active directory tenant that the service identity belongs to.\",\n    )\n    service_principal_id: str = Field(\n        default=..., description=\"The service principal ID.\"\n    )\n    service_principal_password: SecretStr = Field(\n        default=..., description=\"The service principal password/key.\"\n    )\n    subscription_id: str = Field(\n        default=...,\n        description=\"The Azure subscription ID containing the workspace, in format: '00000000-0000-0000-0000-000000000000'.\",  # noqa\n    )\n    resource_group: str = Field(\n        default=..., description=\"The resource group containing the workspace.\"\n    )\n    workspace_name: str = Field(default=..., description=\"The existing workspace name.\")\n\n    @_raise_help_msg(\"ml_datastore\")\n    def get_workspace(self) -&gt; \"Workspace\":\n        \"\"\"\n        Returns an authenticated base Workspace that can be used in\n        Azure's Datasets and Datastores.\n\n        Example:\n            Create an authorized workspace\n            ```python\n            import os\n            from prefect import flow\n            from prefect_azure import AzureMlCredentials\n            @flow\n            def example_get_workspace_flow():\n                azure_credentials = AzureMlCredentials(\n                    tenant_id=\"tenant_id\",\n                    service_principal_id=\"service_principal_id\",\n                    service_principal_password=\"service_principal_password\",\n                    subscription_id=\"subscription_id\",\n                    resource_group=\"resource_group\",\n                    workspace_name=\"workspace_name\"\n                )\n                workspace_client = azure_credentials.get_workspace()\n                return workspace_client\n            example_get_workspace_flow()\n            ```\n        \"\"\"\n        service_principal_password = self.service_principal_password.get_secret_value()\n        service_principal_authentication = ServicePrincipalAuthentication(\n            tenant_id=self.tenant_id,\n            service_principal_id=self.service_principal_id,\n            service_principal_password=service_principal_password,\n        )\n\n        workspace = Workspace(\n            subscription_id=self.subscription_id,\n            resource_group=self.resource_group,\n            workspace_name=self.workspace_name,\n            auth=service_principal_authentication,\n        )\n\n        return workspace\n</code></pre>"},{"location":"integrations/prefect-azure/credentials/#prefect_azure.credentials.AzureMlCredentials.get_workspace","title":"<code>get_workspace</code>","text":"<p>Returns an authenticated base Workspace that can be used in Azure's Datasets and Datastores.</p> Example <p>Create an authorized workspace <pre><code>import os\nfrom prefect import flow\nfrom prefect_azure import AzureMlCredentials\n@flow\ndef example_get_workspace_flow():\n    azure_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\"\n    )\n    workspace_client = azure_credentials.get_workspace()\n    return workspace_client\nexample_get_workspace_flow()\n</code></pre></p> Source code in <code>prefect_azure/credentials.py</code> <pre><code>@_raise_help_msg(\"ml_datastore\")\ndef get_workspace(self) -&gt; \"Workspace\":\n    \"\"\"\n    Returns an authenticated base Workspace that can be used in\n    Azure's Datasets and Datastores.\n\n    Example:\n        Create an authorized workspace\n        ```python\n        import os\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        @flow\n        def example_get_workspace_flow():\n            azure_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\"\n            )\n            workspace_client = azure_credentials.get_workspace()\n            return workspace_client\n        example_get_workspace_flow()\n        ```\n    \"\"\"\n    service_principal_password = self.service_principal_password.get_secret_value()\n    service_principal_authentication = ServicePrincipalAuthentication(\n        tenant_id=self.tenant_id,\n        service_principal_id=self.service_principal_id,\n        service_principal_password=service_principal_password,\n    )\n\n    workspace = Workspace(\n        subscription_id=self.subscription_id,\n        resource_group=self.resource_group,\n        workspace_name=self.workspace_name,\n        auth=service_principal_authentication,\n    )\n\n    return workspace\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/","title":"ML Datastore","text":""},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore","title":"<code>prefect_azure.ml_datastore</code>","text":"<p>Tasks for interacting with Azure ML Datastore</p>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_get_datastore","title":"<code>ml_get_datastore</code>  <code>async</code>","text":"<p>Gets the Datastore within the Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>datastore_name</code> <code>str</code> <p>The name of the Datastore. If <code>None</code>, then the default Datastore of the Workspace is returned.</p> <code>None</code> Example <p>Get Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_get_datastore\n\n@flow\ndef example_ml_get_datastore_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    results = ml_get_datastore(ml_credentials, datastore_name=\"datastore_name\")\n    return results\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_get_datastore(\n    ml_credentials: \"AzureMlCredentials\", datastore_name: str = None\n) -&gt; Datastore:\n    \"\"\"\n    Gets the Datastore within the Workspace.\n\n    Args:\n        ml_credentials: Credentials to use for authentication with Azure.\n        datastore_name: The name of the Datastore. If `None`, then the\n            default Datastore of the Workspace is returned.\n\n    Example:\n        Get Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_get_datastore\n\n        @flow\n        def example_ml_get_datastore_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            results = ml_get_datastore(ml_credentials, datastore_name=\"datastore_name\")\n            return results\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Getting datastore %s\", datastore_name)\n\n    result = await _get_datastore(ml_credentials, datastore_name)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_list_datastores","title":"<code>ml_list_datastores</code>","text":"<p>Lists the Datastores in the Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required Example <p>List Datastore objects <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_list_datastores\n\n@flow\ndef example_ml_list_datastores_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    results = ml_list_datastores(ml_credentials)\n    return results\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\ndef ml_list_datastores(ml_credentials: \"AzureMlCredentials\") -&gt; Dict:\n    \"\"\"\n    Lists the Datastores in the Workspace.\n\n    Args:\n        ml_credentials: Credentials to use for authentication with Azure.\n\n    Example:\n        List Datastore objects\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_list_datastores\n\n        @flow\n        def example_ml_list_datastores_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            results = ml_list_datastores(ml_credentials)\n            return results\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Listing datastores\")\n\n    workspace = ml_credentials.get_workspace()\n    results = workspace.datastores\n    return results\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_register_datastore_blob_container","title":"<code>ml_register_datastore_blob_container</code>  <code>async</code>","text":"<p>Registers a Azure Blob Storage container as a Datastore in a Azure ML service Workspace.</p> <p>Parameters:</p> Name Type Description Default <code>container_name</code> <code>str</code> <p>The name of the container.</p> required <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure ML.</p> required <code>blob_storage_credentials</code> <code>AzureBlobStorageCredentials</code> <p>Credentials to use for authentication with Azure Blob Storage.</p> required <code>datastore_name</code> <code>str</code> <p>The name of the datastore. If not defined, the container name will be used.</p> <code>None</code> <code>create_container_if_not_exists</code> <code>bool</code> <p>Create a container, if one does not exist with the given name.</p> <code>False</code> <code>overwrite</code> <code>bool</code> <p>Overwrite an existing datastore. If the datastore does not exist, it will be created.</p> <code>False</code> <code>set_as_default</code> <code>bool</code> <p>Set the created Datastore as the default datastore for the Workspace.</p> <code>False</code> Example <p>Upload Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_register_datastore_blob_container\n\n@flow\ndef example_ml_register_datastore_blob_container_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    blob_storage_credentials = AzureBlobStorageCredentials(\"connection_string\")\n    result = ml_register_datastore_blob_container(\n        \"container\",\n        ml_credentials,\n        blob_storage_credentials,\n        datastore_name=\"datastore_name\"\n    )\n    return result\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_register_datastore_blob_container(\n    container_name: str,\n    ml_credentials: \"AzureMlCredentials\",\n    blob_storage_credentials: \"AzureBlobStorageCredentials\",\n    datastore_name: str = None,\n    create_container_if_not_exists: bool = False,\n    overwrite: bool = False,\n    set_as_default: bool = False,\n) -&gt; \"AzureBlobDatastore\":\n    \"\"\"\n    Registers a Azure Blob Storage container as a\n    Datastore in a Azure ML service Workspace.\n\n    Args:\n        container_name: The name of the container.\n        ml_credentials: Credentials to use for authentication with Azure ML.\n        blob_storage_credentials: Credentials to use for authentication\n            with Azure Blob Storage.\n        datastore_name: The name of the datastore. If not defined, the\n            container name will be used.\n        create_container_if_not_exists: Create a container, if one does not\n            exist with the given name.\n        overwrite: Overwrite an existing datastore. If\n            the datastore does not exist, it will be created.\n        set_as_default: Set the created Datastore as the default datastore\n            for the Workspace.\n\n    Example:\n        Upload Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_register_datastore_blob_container\n\n        @flow\n        def example_ml_register_datastore_blob_container_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            blob_storage_credentials = AzureBlobStorageCredentials(\"connection_string\")\n            result = ml_register_datastore_blob_container(\n                \"container\",\n                ml_credentials,\n                blob_storage_credentials,\n                datastore_name=\"datastore_name\"\n            )\n            return result\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    if datastore_name is None:\n        datastore_name = container_name\n\n    logger.info(\n        \"Registering %s container into %s datastore\", container_name, datastore_name\n    )\n\n    workspace = ml_credentials.get_workspace()\n    async with blob_storage_credentials.get_client() as blob_service_client:\n        credential = blob_service_client.credential\n        account_name = credential.account_name\n        account_key = credential.account_key\n\n    partial_register = partial(\n        Datastore.register_azure_blob_container,\n        workspace=workspace,\n        datastore_name=datastore_name,\n        container_name=container_name,\n        account_name=account_name,\n        account_key=account_key,\n        overwrite=overwrite,\n        create_if_not_exists=create_container_if_not_exists,\n    )\n    result = await to_thread.run_sync(partial_register)\n\n    if set_as_default:\n        result.set_as_default()\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/ml_datastore/#prefect_azure.ml_datastore.ml_upload_datastore","title":"<code>ml_upload_datastore</code>  <code>async</code>","text":"<p>Uploads local files to a Datastore.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Union[str, Path, List[Union[str, Path]]]</code> <p>The path to a single file, single directory, or a list of path to files to be uploaded.</p> required <code>ml_credentials</code> <code>AzureMlCredentials</code> <p>Credentials to use for authentication with Azure.</p> required <code>target_path</code> <code>Union[str, Path]</code> <p>The location in the blob container to upload to. If None, then upload to root.</p> <code>None</code> <code>relative_root</code> <code>Union[str, Path]</code> <p>The root from which is used to determine the path of the files in the blob. For example, if we upload /path/to/file.txt, and we define base path to be /path, when file.txt is uploaded to the blob storage, it will have the path of /to/file.txt.</p> <code>None</code> <code>datastore_name</code> <code>str</code> <p>The name of the Datastore. If <code>None</code>, then the default Datastore of the Workspace is returned.</p> <code>None</code> <code>overwrite</code> <code>bool</code> <p>Overwrite existing file(s).</p> <code>False</code> Example <p>Upload Datastore object <pre><code>from prefect import flow\nfrom prefect_azure import AzureMlCredentials\nfrom prefect_azure.ml_datastore import ml_upload_datastore\n\n@flow\ndef example_ml_upload_datastore_flow():\n    ml_credentials = AzureMlCredentials(\n        tenant_id=\"tenant_id\",\n        service_principal_id=\"service_principal_id\",\n        service_principal_password=\"service_principal_password\",\n        subscription_id=\"subscription_id\",\n        resource_group=\"resource_group\",\n        workspace_name=\"workspace_name\",\n    )\n    result = ml_upload_datastore(\n        \"path/to/dir/or/file\",\n        ml_credentials,\n        datastore_name=\"datastore_name\"\n    )\n    return result\n</code></pre></p> Source code in <code>prefect_azure/ml_datastore.py</code> <pre><code>@task\nasync def ml_upload_datastore(\n    path: Union[str, Path, List[Union[str, Path]]],\n    ml_credentials: \"AzureMlCredentials\",\n    target_path: Union[str, Path] = None,\n    relative_root: Union[str, Path] = None,\n    datastore_name: str = None,\n    overwrite: bool = False,\n) -&gt; \"DataReference\":\n    \"\"\"\n    Uploads local files to a Datastore.\n\n    Args:\n        path: The path to a single file, single directory,\n            or a list of path to files to be uploaded.\n        ml_credentials: Credentials to use for authentication with Azure.\n        target_path: The location in the blob container to upload to. If\n            None, then upload to root.\n        relative_root: The root from which is used to determine the path of\n            the files in the blob. For example, if we upload /path/to/file.txt,\n            and we define base path to be /path, when file.txt is uploaded\n            to the blob storage, it will have the path of /to/file.txt.\n        datastore_name: The name of the Datastore. If `None`, then the\n            default Datastore of the Workspace is returned.\n        overwrite: Overwrite existing file(s).\n\n    Example:\n        Upload Datastore object\n        ```python\n        from prefect import flow\n        from prefect_azure import AzureMlCredentials\n        from prefect_azure.ml_datastore import ml_upload_datastore\n\n        @flow\n        def example_ml_upload_datastore_flow():\n            ml_credentials = AzureMlCredentials(\n                tenant_id=\"tenant_id\",\n                service_principal_id=\"service_principal_id\",\n                service_principal_password=\"service_principal_password\",\n                subscription_id=\"subscription_id\",\n                resource_group=\"resource_group\",\n                workspace_name=\"workspace_name\",\n            )\n            result = ml_upload_datastore(\n                \"path/to/dir/or/file\",\n                ml_credentials,\n                datastore_name=\"datastore_name\"\n            )\n            return result\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading %s into %s datastore\", path, datastore_name)\n\n    datastore = await _get_datastore(ml_credentials, datastore_name)\n\n    if isinstance(path, Path):\n        path = str(path)\n    elif isinstance(path, list) and isinstance(path[0], Path):\n        path = [str(p) for p in path]\n\n    if isinstance(target_path, Path):\n        target_path = str(target_path)\n\n    if isinstance(relative_root, Path):\n        relative_root = str(relative_root)\n\n    if isinstance(path, str) and os.path.isdir(path):\n        partial_upload = partial(\n            datastore.upload,\n            src_dir=path,\n            target_path=target_path,\n            overwrite=overwrite,\n            show_progress=False,\n        )\n    else:\n        partial_upload = partial(\n            datastore.upload_files,\n            files=path if isinstance(path, list) else [path],\n            relative_root=relative_root,\n            target_path=target_path,\n            overwrite=overwrite,\n            show_progress=False,\n        )\n\n    result = await to_thread.run_sync(partial_upload)\n    return result\n</code></pre>"},{"location":"integrations/prefect-azure/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps","title":"<code>prefect_azure.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage and retrieval in Azure Blob Storage.</p> <p>These steps can be used in a <code>prefect.yaml</code> file to define the default  push and pull steps for a group of deployments, or they can be used to  define the push and pull steps for a specific deployment.</p> <p>Example</p> <p>Sample <code>prefect.yaml</code> file that is configured to push and pull to and  from an Azure Blob Storage container:</p> <pre><code>prefect_version: ...\nname: ...\n\npush:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n\npull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: \"{{ container }}\"\n        folder: \"{{ folder }}\"\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre> <p>Note</p> <p>Azure Storage account needs to have Hierarchical Namespace disabled.</p> <p>For more information about using deployment steps, check out out the Prefect docs.</p>"},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps.pull_from_azure_blob_storage","title":"<code>pull_from_azure_blob_storage</code>","text":"<p>Pulls from an Azure Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>The name of the container to pull files from</p> required <code>folder</code> <code>str</code> <p>The folder within the container to pull from</p> required <code>credentials</code> <code>Dict[str, str]</code> <p>A dictionary of credentials with keys <code>connection_string</code> or <code>account_url</code> and values of the corresponding connection string or account url. If both are provided, <code>connection_string</code> will be used.</p> required Note <p>Azure Storage account needs to have Hierarchical Namespace disabled.</p> Example <p>Pull from an Azure Blob Storage container using credentials stored in a block: <pre><code>pull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre></p> <p>Pull from an Azure Blob Storage container using an account URL and default credentials: <pre><code>pull:\n    - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials:\n            account_url: https://myaccount.blob.core.windows.net/\n</code></pre></p> Source code in <code>prefect_azure/deployments/steps.py</code> <pre><code>def pull_from_azure_blob_storage(\n    container: str,\n    folder: str,\n    credentials: Dict[str, str],\n):\n    \"\"\"\n    Pulls from an Azure Blob Storage container.\n\n    Args:\n        container: The name of the container to pull files from\n        folder: The folder within the container to pull from\n        credentials: A dictionary of credentials with keys `connection_string` or\n            `account_url` and values of the corresponding connection string or\n            account url. If both are provided, `connection_string` will be used.\n\n    Note:\n        Azure Storage account needs to have Hierarchical Namespace disabled.\n\n    Example:\n        Pull from an Azure Blob Storage container using credentials stored in\n        a block:\n        ```yaml\n        pull:\n            - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n        ```\n\n        Pull from an Azure Blob Storage container using an account URL and\n        default credentials:\n        ```yaml\n        pull:\n            - prefect_azure.deployments.steps.pull_from_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials:\n                    account_url: https://myaccount.blob.core.windows.net/\n        ```\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    if credentials.get(\"connection_string\") is not None:\n        container_client = ContainerClient.from_connection_string(\n            credentials[\"connection_string\"], container_name=container\n        )\n    elif credentials.get(\"account_url\") is not None:\n        container_client = ContainerClient(\n            account_url=credentials[\"account_url\"],\n            container_name=container,\n            credential=DefaultAzureCredential(),\n        )\n    else:\n        raise ValueError(\n            \"Credentials must contain either connection_string or account_url\"\n        )\n\n    with container_client as client:\n        for blob in client.list_blobs(name_starts_with=folder):\n            target = PurePosixPath(\n                local_path\n                / relative_path_to_current_platform(blob.name).relative_to(folder)\n            )\n            Path.mkdir(Path(target.parent), parents=True, exist_ok=True)\n            with open(target, \"wb\") as f:\n                client.download_blob(blob).readinto(f)\n\n    return {\n        \"container\": container,\n        \"folder\": folder,\n        \"directory\": local_path,\n    }\n</code></pre>"},{"location":"integrations/prefect-azure/deployments/steps/#prefect_azure.deployments.steps.push_to_azure_blob_storage","title":"<code>push_to_azure_blob_storage</code>","text":"<p>Pushes to an Azure Blob Storage container.</p> <p>Parameters:</p> Name Type Description Default <code>container</code> <code>str</code> <p>The name of the container to push files to</p> required <code>folder</code> <code>str</code> <p>The folder within the container to push to</p> required <code>credentials</code> <code>Dict[str, str]</code> <p>A dictionary of credentials with keys <code>connection_string</code> or <code>account_url</code> and values of the corresponding connection string or account url. If both are provided, <code>connection_string</code> will be used.</p> required <code>ignore_file</code> <code>Optional[str]</code> <p>The path to a file containing patterns of files to ignore when pushing to Azure Blob Storage. If not provided, the default <code>.prefectignore</code> file will be used.</p> <code>'.prefectignore'</code> Example <p>Push to an Azure Blob Storage container using credentials stored in a block: <pre><code>push:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n</code></pre></p> <p>Push to an Azure Blob Storage container using an account URL and default credentials: <pre><code>push:\n    - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n        requires: prefect-azure[blob_storage]\n        container: my-container\n        folder: my-folder\n        credentials:\n            account_url: https://myaccount.blob.core.windows.net/\n</code></pre></p> Source code in <code>prefect_azure/deployments/steps.py</code> <pre><code>def push_to_azure_blob_storage(\n    container: str,\n    folder: str,\n    credentials: Dict[str, str],\n    ignore_file: Optional[str] = \".prefectignore\",\n):\n    \"\"\"\n    Pushes to an Azure Blob Storage container.\n\n    Args:\n        container: The name of the container to push files to\n        folder: The folder within the container to push to\n        credentials: A dictionary of credentials with keys `connection_string` or\n            `account_url` and values of the corresponding connection string or\n            account url. If both are provided, `connection_string` will be used.\n        ignore_file: The path to a file containing patterns of files to ignore when\n            pushing to Azure Blob Storage. If not provided, the default `.prefectignore`\n            file will be used.\n\n    Example:\n        Push to an Azure Blob Storage container using credentials stored in a\n        block:\n        ```yaml\n        push:\n            - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.azure-blob-storage-credentials.dev-credentials }}\"\n        ```\n\n        Push to an Azure Blob Storage container using an account URL and\n        default credentials:\n        ```yaml\n        push:\n            - prefect_azure.deployments.steps.push_to_azure_blob_storage:\n                requires: prefect-azure[blob_storage]\n                container: my-container\n                folder: my-folder\n                credentials:\n                    account_url: https://myaccount.blob.core.windows.net/\n        ```\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    if credentials.get(\"connection_string\") is not None:\n        container_client = ContainerClient.from_connection_string(\n            credentials[\"connection_string\"], container_name=container\n        )\n    elif credentials.get(\"account_url\") is not None:\n        container_client = ContainerClient(\n            account_url=credentials[\"account_url\"],\n            container_name=container,\n            credential=DefaultAzureCredential(),\n        )\n    else:\n        raise ValueError(\n            \"Credentials must contain either connection_string or account_url\"\n        )\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    with container_client as client:\n        for local_file_path in local_path.expanduser().rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = Path(folder) / local_file_path.relative_to(\n                    local_path\n                )\n                with open(local_file_path, \"rb\") as f:\n                    client.upload_blob(str(remote_file_path), f, overwrite=True)\n\n    return {\n        \"container\": container,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-bitbucket/","title":"prefect-bitbucket","text":"<p>The prefect-bitbucket library makes it easy to interact with Bitbucket repositories and credentials.</p>"},{"location":"integrations/prefect-bitbucket/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-bitbucket/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A Bitbucket account.</li> </ul>"},{"location":"integrations/prefect-bitbucket/#install-prefect-bitbucket","title":"Install prefect-bitbucket","text":"<pre><code>pip install -U prefect-bitbucket\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-bitbucket module to make them available for use.</p> <pre><code>prefect block register -m prefect_bitbucket\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-bitbucket/#store-deployment-flow-code-in-a-private-bitbucket-repository","title":"Store deployment flow code in a private Bitbucket repository","text":"<p>To create a deployment and run a deployment where the flow code is stored in a private Bitbucket repository, you can use the <code>BitbucketCredentials</code> block.</p> <p>A deployment can use flow code stored in a Bitbucket repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Create a Bitbucket Credentials block:</p> <pre><code>from prefect_bitbucket import BitbucketCredentials\n\nbitbucket_credentials_block = BitbucketCredentials(token=\"x-token-auth:my-token\")\n\nbitbucket_credentials_block.save(name=\"my-bitbucket-credentials-block\")\n</code></pre> <p>Difference between Bitbucket Server and Bitbucket Cloud authentication</p> <p>If using a token to authenticate to Bitbucket Cloud, only set the <code>token</code> to authenticate. Do not include a value in the <code>username</code> field or authentication will fail. If using Bitbucket Server, provide both the <code>token</code> and <code>username</code> values.</p>"},{"location":"integrations/prefect-bitbucket/#access-flow-code-stored-in-a-private-bitbucket-repository-in-a-deployment","title":"Access flow code stored in a private Bitbucket repository in a deployment","text":"<p>Use the credentials block you created above to pass the Bitbucket access token during deployment creation. The code below assumes there's flow code stored in a private Bitbucket repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_bitbucket import BitbucketCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n            url=\"https://bitbucket.com/org/private-repo.git\",\n            credentials=BitbucketCredentials.load(\"my-bitbucket-credentials-block\")\n        ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-bitbucket-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the Bitbucket Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        credentials: https://bitbucket.org/org/private-repo.git\n        credentials: \"{{ prefect.blocks.bitbucket-credentials.my-bitbucket-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#interact-with-a-bitbucket-repository","title":"Interact with a Bitbucket repository","text":"<p>The code below shows how to reference a particular branch or tag of a Bitbucket repository.</p> <pre><code>from prefect_bitbucket import BitbucketRepository\n\ndef save_bitbucket_block():\n    bitbucket_block = BitbucketRepository(\n        repository=\"https://bitbucket.org/testing/my-repository.git\",\n        reference=\"branch-or-tag-name\",\n    )\n\n    bitbucket_block.save(\"my-bitbucket-block\")\n\n\nif __name__ == \"__main__\":\n    save_bitbucket_block()\n</code></pre> <p>Exclude the <code>reference</code> field to use the default branch. Reference a BitbucketCredentials block for authentication if the repository is private.</p> <p>Use the newly created block to interact with the Bitbucket repository.</p> <p>For example, download the repository contents with the <code>.get_directory()</code> method like this:</p> <pre><code>from prefect_bitbucket.repositories import BitbucketRepository\n\ndef fetch_repo():\n    bitbucket_block = BitbucketRepository.load(\"my-bitbucket-block\")\n    bitbucket_block.get_directory()\n\nif __name__ == \"__main__\":\n    fetch_repo()\n</code></pre>"},{"location":"integrations/prefect-bitbucket/#resources","title":"Resources","text":"<p>For assistance using Bitbucket, consult the Bitbucket documentation.</p> <p>Refer to the prefect-bitbucket API documentation linked in the sidebar to explore all the capabilities of the prefect-bitbucket library.</p>"},{"location":"integrations/prefect-bitbucket/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials","title":"<code>prefect_bitbucket.credentials</code>","text":"<p>Module to enable authenticate interactions with BitBucket.</p>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.BitBucketCredentials","title":"<code>BitBucketCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Store BitBucket credentials to interact with private BitBucket repositories.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>Optional[SecretStr]</code> <p>An access token to authenticate with BitBucket. This is required for accessing private repositories.</p> <code>username</code> <code>Optional[str]</code> <p>Identification name unique across entire BitBucket site.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password to authenticate to BitBucket.</p> <code>url</code> <code>str</code> <p>The base URL of your BitBucket instance.</p> <p>Examples:</p> <p>Load stored BitBucket credentials: <pre><code>from prefect_bitbucket import BitBucketCredentials\nbitbucket_credentials_block = BitBucketCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>class BitBucketCredentials(CredentialsBlock):\n    \"\"\"Store BitBucket credentials to interact with private BitBucket repositories.\n\n    Attributes:\n        token: An access token to authenticate with BitBucket. This is required\n            for accessing private repositories.\n        username: Identification name unique across entire BitBucket site.\n        password: The password to authenticate to BitBucket.\n        url: The base URL of your BitBucket instance.\n\n\n    Examples:\n        Load stored BitBucket credentials:\n        ```python\n        from prefect_bitbucket import BitBucketCredentials\n        bitbucket_credentials_block = BitBucketCredentials.load(\"BLOCK_NAME\")\n        ```\n\n\n    \"\"\"\n\n    _block_type_name = \"BitBucket Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/5d729f7355fb6828c4b605268ded9cfafab3ae4f-250x250.png\"  # noqa\n    token: Optional[SecretStr] = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=(\n            \"A BitBucket Personal Access Token - required for private repositories.\"\n        ),\n        example=\"x-token-auth:my-token\",\n    )\n    username: Optional[str] = Field(\n        default=None,\n        description=\"Identification name unique across entire BitBucket site.\",\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password to authenticate to BitBucket.\"\n    )\n    url: str = Field(\n        default=\"https://api.bitbucket.org/\",\n        description=\"The base URL of your BitBucket instance.\",\n        title=\"URL\",\n    )\n\n    @validator(\"username\")\n    def _validate_username(cls, value: str) -&gt; str:\n        \"\"\"When username provided, will validate it.\"\"\"\n        pattern = \"^[A-Za-z0-9_-]*$\"\n\n        if not re.match(pattern, value):\n            raise ValueError(\n                \"Username must be alpha, num, dash and/or underscore only.\"\n            )\n        if not len(value) &lt;= 30:\n            raise ValueError(\"Username cannot be longer than 30 chars.\")\n        return value\n\n    def get_client(\n        self, client_type: Union[str, ClientType], **client_kwargs\n    ) -&gt; Union[Cloud, Bitbucket]:\n        \"\"\"Get an authenticated local or cloud Bitbucket client.\n\n        Args:\n            client_type: Whether to use a local or cloud client.\n\n        Returns:\n            An authenticated Bitbucket client.\n\n        \"\"\"\n        # ref: https://atlassian-python-api.readthedocs.io/\n        if isinstance(client_type, str):\n            client_type = ClientType(client_type.lower())\n\n        password = self.password.get_secret_value()\n        input_client_kwargs = dict(\n            url=self.url, username=self.username, password=password\n        )\n        input_client_kwargs.update(**client_kwargs)\n\n        if client_type == ClientType.CLOUD:\n            client = Cloud(**input_client_kwargs)\n        else:\n            client = Bitbucket(**input_client_kwargs)\n        return client\n</code></pre>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.BitBucketCredentials.get_client","title":"<code>get_client</code>","text":"<p>Get an authenticated local or cloud Bitbucket client.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>Whether to use a local or cloud client.</p> required <p>Returns:</p> Type Description <code>Union[Cloud, Bitbucket]</code> <p>An authenticated Bitbucket client.</p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>def get_client(\n    self, client_type: Union[str, ClientType], **client_kwargs\n) -&gt; Union[Cloud, Bitbucket]:\n    \"\"\"Get an authenticated local or cloud Bitbucket client.\n\n    Args:\n        client_type: Whether to use a local or cloud client.\n\n    Returns:\n        An authenticated Bitbucket client.\n\n    \"\"\"\n    # ref: https://atlassian-python-api.readthedocs.io/\n    if isinstance(client_type, str):\n        client_type = ClientType(client_type.lower())\n\n    password = self.password.get_secret_value()\n    input_client_kwargs = dict(\n        url=self.url, username=self.username, password=password\n    )\n    input_client_kwargs.update(**client_kwargs)\n\n    if client_type == ClientType.CLOUD:\n        client = Cloud(**input_client_kwargs)\n    else:\n        client = Bitbucket(**input_client_kwargs)\n    return client\n</code></pre>"},{"location":"integrations/prefect-bitbucket/credentials/#prefect_bitbucket.credentials.ClientType","title":"<code>ClientType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>The client type to use.</p> Source code in <code>prefect_bitbucket/credentials.py</code> <pre><code>class ClientType(Enum):\n    \"\"\"The client type to use.\"\"\"\n\n    LOCAL = \"local\"\n    CLOUD = \"cloud\"\n</code></pre>"},{"location":"integrations/prefect-bitbucket/repository/","title":"Repository","text":""},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository","title":"<code>prefect_bitbucket.repository</code>","text":"<p>Allows for interaction with a BitBucket repository.</p> <p>The <code>BitBucket</code> class in this collection is a storage block that lets Prefect agents pull Prefect flow code from BitBucket repositories.</p> <p>The <code>BitBucket</code> block is ideally configured via the Prefect UI, but can also be used in Python as the following examples demonstrate.</p> <p>Examples ```python from prefect_bitbucket.repository import BitBucketRepository</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--public-bitbucket-repository","title":"public BitBucket repository","text":"<p>public_bitbucket_block = BitBucketRepository(     repository=\"https://bitbucket.com/my-project/my-repository.git\" )</p> <p>public_bitbucket_block.save(name=\"my-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--specific-branch-or-tag","title":"specific branch or tag","text":"<p>branch_bitbucket_block = BitBucketRepository(     reference=\"branch-or-tag-name\",     repository=\"https://bitbucket.com/my-project/my-repository.git\" )</p> <p>branch_bitbucket_block.save(name=\"my-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository--private-bitbucket-repository","title":"private BitBucket repository","text":"<p>private_bitbucket_block = BitBucketRepository(     repository=\"https://bitbucket.com/my-project/my-repository.git\",     bitbucket_credentials=BitBucketCredentials.load(\"my-bitbucket-credentials-block\") )</p> <p>private_bitbucket_block.save(name=\"my-private-bitbucket-block\")</p>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository.BitBucketRepository","title":"<code>BitBucketRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored in BitBucket repositories.</p> <p>An accessible installation of git is required for this block to function properly.</p> Source code in <code>prefect_bitbucket/repository.py</code> <pre><code>class BitBucketRepository(ReadableDeploymentStorage):\n    \"\"\"Interact with files stored in BitBucket repositories.\n\n    An accessible installation of git is required for this block to function\n    properly.\n    \"\"\"\n\n    _block_type_name = \"BitBucket Repository\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/5d729f7355fb6828c4b605268ded9cfafab3ae4f-250x250.png\"  # noqa\n    _description = \"Interact with files stored in BitBucket repositories.\"\n\n    repository: str = Field(\n        default=...,\n        description=\"The URL of a BitBucket repository to read from in HTTPS format\",\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch or tag.\",\n    )\n    bitbucket_credentials: Optional[BitBucketCredentials] = Field(\n        default=None,\n        description=(\n            \"An optional BitBucketCredentials block for authenticating with \"\n            \"private BitBucket repos.\"\n        ),\n    )\n\n    @validator(\"bitbucket_credentials\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict) -&gt; str:\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted BitBucket URLs.\n\n        Validators are by default only called on provided arguments.\n\n        Note: validates `credentials` specifically so that it only fires when private\n        repositories are used.\n        \"\"\"\n        if v is not None:\n            if urlparse(values[\"repository\"]).scheme != \"https\":\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Credentials can only be used with BitBucket repositories \"\n                        \"using the 'HTTPS' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"URL to the 'HTTPS' format.\"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos in the cloud:\n        https://x-token-auth:&lt;access-token&gt;@bitbucket.org/&lt;user&gt;/&lt;repo&gt;.git\n        For private repos with a local bitbucket server:\n        https://&lt;username&gt;:&lt;access-token&gt;@&lt;server&gt;/scm/&lt;project&gt;/&lt;repo&gt;.git\n\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urlparse(self.repository)\n        token_is_set = (\n            self.bitbucket_credentials is not None and self.bitbucket_credentials.token\n        )\n\n        # Need a token for private repos\n        if url_components.scheme == \"https\" and token_is_set:\n            token = self.bitbucket_credentials.token.get_secret_value()\n            username = self.bitbucket_credentials.username\n            if username is None:\n                username = \"x-token-auth\"\n            updated_components = url_components._replace(\n                netloc=f\"{username}:{token}@{url_components.netloc}\"\n            )\n            full_url = urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: Optional[str]\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Return the fully formed paths for BitBucketRepository contents.\n\n        Return will take the form of (content_source, content_destination).\n\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"Clones a BitBucket project within `from_path` to the provided `local_path`.\n\n        This defaults to cloning the repository reference configured on the\n        Block to the present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n\n        \"\"\"\n        # Construct command\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        cmd += [\"--depth\", \"1\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-bitbucket/repository/#prefect_bitbucket.repository.BitBucketRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a BitBucket project within <code>from_path</code> to the provided <code>local_path</code>.</p> <p>This defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect_bitbucket/repository.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"Clones a BitBucket project within `from_path` to the provided `local_path`.\n\n    This defaults to cloning the repository reference configured on the\n    Block to the present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n\n    \"\"\"\n    # Construct command\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    cmd += [\"--depth\", \"1\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-dask/","title":"prefect-dask","text":"<p>Dask helps you run your flow in parallel and distribute runs over multiple machines. The <code>prefect-dask</code> integration makes it easy speed up your flow runs by integrating Dask into your code.</p>"},{"location":"integrations/prefect-dask/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-dask/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> </ul>"},{"location":"integrations/prefect-dask/#install-prefect-dask","title":"Install prefect-dask","text":"<pre><code>pip install -U prefect-dask\n</code></pre>"},{"location":"integrations/prefect-dask/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Say your flow downloads many images to train a machine learning model. It can take longer than you'd like for the code to run because the code runs sequentially.</p> <p>Parallelize your flow code with <code>prefect-dask</code> in three steps:</p> <ol> <li>Add the import: <code>from prefect_dask import DaskTaskRunner</code></li> <li>Specify the task runner in the flow decorator: <code>@flow(task_runner=DaskTaskRunner)</code></li> <li>Submit tasks to the flow's task runner: <code>a_task.submit(*args, **kwargs)</code></li> </ol> <p>Below is code with and without the DaskTaskRunner:</p> SequentialParallel <pre><code># Completed in 15.2 seconds\n\nfrom typing import List\nfrom pathlib import Path\n\nimport httpx\nfrom prefect import flow, task\n\nURL_FORMAT = (\n    \"https://www.cpc.ncep.noaa.gov/products/NMME/archive/\"\n    \"{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png\"\n)\n\n@task\ndef download_image(year: int, month: int, directory: Path) -&gt; Path:\n    # download image from URL\n    url = URL_FORMAT.format(year=year, month=month)\n    resp = httpx.get(url)\n\n    # save content to directory/YYYYMM.png\n    file_path = (directory / url.split(\"/\")[-1]).with_stem(f\"{year:04d}{month:02d}\")\n    file_path.write_bytes(resp.content)\n    return file_path\n\n@flow\ndef download_nino_34_plumes_from_year(year: int) -&gt; List[Path]:\n    # create a directory to hold images\n    directory = Path(\"data\")\n    directory.mkdir(exist_ok=True)\n\n    # download all images\n    file_paths = []\n    for month in range(1, 12 + 1):\n        file_path = download_image(year, month, directory)\n        file_paths.append(file_path)\n    return file_paths\n\nif __name__ == \"__main__\":\n    download_nino_34_plumes_from_year(2022)\n</code></pre> <pre><code># Completed in 5.7 seconds\n\nfrom typing import List\nfrom pathlib import Path\n\nimport httpx\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\nURL_FORMAT = (\n    \"https://www.cpc.ncep.noaa.gov/products/NMME/archive/\"\n    \"{year:04d}{month:02d}0800/current/images/nino34.rescaling.ENSMEAN.png\"\n)\n\n@task\ndef download_image(year: int, month: int, directory: Path) -&gt; Path:\n    # download image from URL\n    url = URL_FORMAT.format(year=year, month=month)\n    resp = httpx.get(url)\n\n    # save content to directory/YYYYMM.png\n    file_path = (directory / url.split(\"/\")[-1]).with_stem(f\"{year:04d}{month:02d}\")\n    file_path.write_bytes(resp.content)\n    return file_path\n\n@flow(task_runner=DaskTaskRunner(cluster_kwargs={\"processes\": False}))\ndef download_nino_34_plumes_from_year(year: int) -&gt; List[Path]:\n    # create a directory to hold images\n    directory = Path(\"data\")\n    directory.mkdir(exist_ok=True)\n\n    # download all images\n    file_paths = []\n    for month in range(1, 12 + 1):\n        file_path = download_image.submit(year, month, directory)\n        file_paths.append(file_path)\n    return file_paths\n\nif __name__ == \"__main__\":\n    download_nino_34_plumes_from_year(2022)\n</code></pre> <p>In our tests, the sequential flow run took 15.2 seconds. The version with <code>DaskTaskRunner</code> reduced the runtime to 5.7 seconds!</p> <p>For additional time savings with Dask, you could distribute large workloads over multiple machines.</p>"},{"location":"integrations/prefect-dask/#integrate-with-dask-clientcluster","title":"Integrate with Dask client/cluster","text":"<p>Suppose you have an existing Dask client/cluster such as a <code>dask.dataframe.DataFrame</code>, and you want to add observability.</p> <p>With <code>prefect-dask</code>, it takes just a few steps:</p> <ol> <li>Add imports</li> <li>Add <code>task</code> and <code>flow</code> decorators</li> <li>Use <code>get_dask_client</code> context manager to distribute work across Dask workers</li> <li>Specify the task runner and client's address in the flow decorator</li> <li>Submit the tasks to the flow's task runner</li> </ol> SequentialParallel <pre><code>import dask.dataframe\nimport dask.distributed\n\n\nclient = dask.distributed.Client()\n\ndef read_data(start: str, end: str) -&gt; dask.dataframe.DataFrame:\n    df = dask.datasets.timeseries(start, end, partition_freq=\"4w\")\n    return df\n\n\ndef process_data(df: dask.dataframe.DataFrame) -&gt; dask.dataframe.DataFrame:\n\n    df_yearly_avg = df.groupby(df.index.year).mean()\n    return df_yearly_avg.compute()\n\n\ndef dask_pipeline():\n    df = read_data(\"1988\", \"2022\")\n    df_yearly_average = process_data(df)\n    return df_yearly_average\n\nif __name__ == \"__main__\":\n    dask_pipeline()\n</code></pre> <pre><code>import dask.dataframe\nimport dask.distributed\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\nclient = dask.distributed.Client()\n\n@task\ndef read_data(start: str, end: str) -&gt; dask.dataframe.DataFrame:\n    df = dask.datasets.timeseries(start, end, partition_freq=\"4w\")\n    return df\n\n@task\ndef process_data(df: dask.dataframe.DataFrame) -&gt; dask.dataframe.DataFrame:\n    with get_dask_client():\n        df_yearly_avg = df.groupby(df.index.year).mean()\n        return df_yearly_avg.compute()\n\n@flow(task_runner=DaskTaskRunner(address=client.scheduler.address))\ndef dask_pipeline():\n    df = read_data.submit(\"1988\", \"2022\")\n    df_yearly_average = process_data.submit(df)\n    return df_yearly_average\n\nif __name__ == \"__main__\":\n    dask_pipeline()\n</code></pre> <p>Run the code and check how long it takes each task to complete.</p>"},{"location":"integrations/prefect-dask/#resources","title":"Resources","text":"<p>For additional examples, check out the Usage Guide. Refer to the prefect-dask API documentation linked in the sidebar to explore all the capabilities of the prefect-dask library.</p> <p>For assistance using Dask, consult the Dask documentation.</p>"},{"location":"integrations/prefect-dask/task_runners/","title":"Task Runners","text":""},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners","title":"<code>prefect_dask.task_runners</code>","text":"<p>Interface and implementations of the Dask Task Runner. Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>import time\n\nfrom prefect import flow, task\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#0\n#1\n#2\n#3\n#4\n#5\n#6\n#7\n#8\n#9\n</code></pre> <p>Switching to a <code>DaskTaskRunner</code>: <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=DaskTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre></p>"},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners.DaskTaskRunner","title":"<code>DaskTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A parallel task_runner that submits tasks to the <code>dask.distributed</code> scheduler. By default a temporary <code>distributed.LocalCluster</code> is created (and subsequently torn down) within the <code>start()</code> contextmanager. To use a different cluster class (e.g. <code>dask_kubernetes.KubeCluster</code>), you can specify <code>cluster_class</code>/<code>cluster_kwargs</code>.</p> <p>Alternatively, if you already have a dask cluster running, you can provide the cluster object via the <code>cluster</code> kwarg or the address of the scheduler via the <code>address</code> kwarg.</p> <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or warnings will be displayed.</p> <p>Parameters:</p> Name Type Description Default <code>cluster</code> <code>Cluster</code> <p>Currently running dask cluster; if one is not provider (or specified via <code>address</code> kwarg), a temporary cluster will be created in <code>DaskTaskRunner.start()</code>. Defaults to <code>None</code>.</p> <code>None</code> <code>address</code> <code>string</code> <p>Address of a currently running dask scheduler. Defaults to <code>None</code>.</p> <code>None</code> <code>cluster_class</code> <code>string or callable</code> <p>The cluster class to use when creating a temporary dask cluster. Can be either the full class name (e.g. <code>\"distributed.LocalCluster\"</code>), or the class itself.</p> <code>None</code> <code>cluster_kwargs</code> <code>dict</code> <p>Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary dask cluster.</p> <code>None</code> <code>adapt_kwargs</code> <code>dict</code> <p>Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided.</p> <code>None</code> <code>client_kwargs</code> <code>dict</code> <p>Additional kwargs to use when creating a <code>dask.distributed.Client</code>.</p> <code>None</code> <p>Examples:</p> <p>Using a temporary local dask cluster: <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner)\ndef my_flow():\n    ...\n</code></pre></p> <p>Using a temporary cluster running elsewhere. Any Dask cluster class should work, here we use dask-cloudprovider: <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.FargateCluster\",\n    cluster_kwargs={\n        \"image\": \"prefecthq/prefect:latest\",\n        \"n_workers\": 5,\n    },\n)\n</code></pre></p> <p>Connecting to an existing dask cluster: <pre><code>DaskTaskRunner(address=\"192.0.2.255:8786\")\n</code></pre></p> Source code in <code>prefect_dask/task_runners.py</code> <pre><code>class DaskTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A parallel task_runner that submits tasks to the `dask.distributed` scheduler.\n    By default a temporary `distributed.LocalCluster` is created (and\n    subsequently torn down) within the `start()` contextmanager. To use a\n    different cluster class (e.g.\n    [`dask_kubernetes.KubeCluster`](https://kubernetes.dask.org/)), you can\n    specify `cluster_class`/`cluster_kwargs`.\n\n    Alternatively, if you already have a dask cluster running, you can provide\n    the cluster object via the `cluster` kwarg or the address of the scheduler\n    via the `address` kwarg.\n    !!! warning \"Multiprocessing safety\"\n        Note that, because the `DaskTaskRunner` uses multiprocessing, calls to flows\n        in scripts must be guarded with `if __name__ == \"__main__\":` or warnings will\n        be displayed.\n\n    Args:\n        cluster (distributed.deploy.Cluster, optional): Currently running dask cluster;\n            if one is not provider (or specified via `address` kwarg), a temporary\n            cluster will be created in `DaskTaskRunner.start()`. Defaults to `None`.\n        address (string, optional): Address of a currently running dask\n            scheduler. Defaults to `None`.\n        cluster_class (string or callable, optional): The cluster class to use\n            when creating a temporary dask cluster. Can be either the full\n            class name (e.g. `\"distributed.LocalCluster\"`), or the class itself.\n        cluster_kwargs (dict, optional): Additional kwargs to pass to the\n            `cluster_class` when creating a temporary dask cluster.\n        adapt_kwargs (dict, optional): Additional kwargs to pass to `cluster.adapt`\n            when creating a temporary dask cluster. Note that adaptive scaling\n            is only enabled if `adapt_kwargs` are provided.\n        client_kwargs (dict, optional): Additional kwargs to use when creating a\n            [`dask.distributed.Client`](https://distributed.dask.org/en/latest/api.html#client).\n\n    Examples:\n        Using a temporary local dask cluster:\n        ```python\n        from prefect import flow\n        from prefect_dask.task_runners import DaskTaskRunner\n\n        @flow(task_runner=DaskTaskRunner)\n        def my_flow():\n            ...\n        ```\n\n        Using a temporary cluster running elsewhere. Any Dask cluster class should\n        work, here we use [dask-cloudprovider](https://cloudprovider.dask.org):\n        ```python\n        DaskTaskRunner(\n            cluster_class=\"dask_cloudprovider.FargateCluster\",\n            cluster_kwargs={\n                \"image\": \"prefecthq/prefect:latest\",\n                \"n_workers\": 5,\n            },\n        )\n        ```\n\n        Connecting to an existing dask cluster:\n        ```python\n        DaskTaskRunner(address=\"192.0.2.255:8786\")\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        cluster: Optional[distributed.deploy.Cluster] = None,\n        address: str = None,\n        cluster_class: Union[str, Callable] = None,\n        cluster_kwargs: dict = None,\n        adapt_kwargs: dict = None,\n        client_kwargs: dict = None,\n    ):\n        # Validate settings and infer defaults\n        if address:\n            if cluster or cluster_class or cluster_kwargs or adapt_kwargs:\n                raise ValueError(\n                    \"Cannot specify `address` and \"\n                    \"`cluster`/`cluster_class`/`cluster_kwargs`/`adapt_kwargs`\"\n                )\n        elif cluster:\n            if cluster_class or cluster_kwargs:\n                raise ValueError(\n                    \"Cannot specify `cluster` and `cluster_class`/`cluster_kwargs`\"\n                )\n            if not cluster.asynchronous:\n                raise ValueError(\n                    \"The cluster must have `asynchronous=True` to be \"\n                    \"used with `DaskTaskRunner`.\"\n                )\n        else:\n            if isinstance(cluster_class, str):\n                cluster_class = from_qualified_name(cluster_class)\n            else:\n                cluster_class = cluster_class\n\n        # Create a copies of incoming kwargs since we may mutate them\n        cluster_kwargs = cluster_kwargs.copy() if cluster_kwargs else {}\n        adapt_kwargs = adapt_kwargs.copy() if adapt_kwargs else {}\n        client_kwargs = client_kwargs.copy() if client_kwargs else {}\n\n        # Update kwargs defaults\n        client_kwargs.setdefault(\"set_as_default\", False)\n\n        # The user cannot specify async/sync themselves\n        if \"asynchronous\" in client_kwargs:\n            raise ValueError(\n                \"`client_kwargs` cannot set `asynchronous`. \"\n                \"This option is managed by Prefect.\"\n            )\n        if \"asynchronous\" in cluster_kwargs:\n            raise ValueError(\n                \"`cluster_kwargs` cannot set `asynchronous`. \"\n                \"This option is managed by Prefect.\"\n            )\n\n        # Store settings\n        self.address = address\n        self.cluster_class = cluster_class\n        self.cluster_kwargs = cluster_kwargs\n        self.adapt_kwargs = adapt_kwargs\n        self.client_kwargs = client_kwargs\n\n        # Runtime attributes\n        self._client: \"distributed.Client\" = None\n        self._cluster: \"distributed.deploy.Cluster\" = cluster\n        self._dask_futures: Dict[str, \"distributed.Future\"] = {}\n\n        super().__init__()\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return (\n            TaskConcurrencyType.PARALLEL\n            if self.cluster_kwargs.get(\"processes\")\n            else TaskConcurrencyType.CONCURRENT\n        )\n\n    def duplicate(self):\n        \"\"\"\n        Create a new instance of the task runner with the same settings.\n        \"\"\"\n        return type(self)(\n            address=self.address,\n            cluster_class=self.cluster_class,\n            cluster_kwargs=self.cluster_kwargs,\n            adapt_kwargs=self.adapt_kwargs,\n            client_kwargs=self.client_kwargs,\n        )\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Check if an instance has the same settings as this task runner.\n        \"\"\"\n        if type(self) == type(other):\n            return (\n                self.address == other.address\n                and self.cluster_class == other.cluster_class\n                and self.cluster_kwargs == other.cluster_kwargs\n                and self.adapt_kwargs == other.adapt_kwargs\n                and self.client_kwargs == other.client_kwargs\n            )\n        else:\n            return NotImplemented\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        # unpack the upstream call in order to cast Prefect futures to Dask futures\n        # where possible to optimize Dask task scheduling\n        call_kwargs = self._optimize_futures(call.keywords)\n\n        if \"task_run\" in call_kwargs:\n            task_run = call_kwargs[\"task_run\"]\n            flow_run = FlowRunContext.get().flow_run\n            # Dask displays the text up to the first '-' as the name; the task run key\n            # should include the task run name for readability in the Dask console.\n            # For cases where the task run fails and reruns for a retried flow run,\n            # the flow run count is included so that the new key will not match\n            # the failed run's key, therefore not retrieving from the Dask cache.\n            dask_key = f\"{task_run.name}-{task_run.id.hex}-{flow_run.run_count}\"\n        else:\n            dask_key = str(key)\n\n        self._dask_futures[key] = self._client.submit(\n            call.func,\n            key=dask_key,\n            # Dask defaults to treating functions are pure, but we set this here for\n            # explicit expectations. If this task run is submitted to Dask twice, the\n            # result of the first run should be returned. Subsequent runs would return\n            # `Abort` exceptions if they were submitted again.\n            pure=True,\n            **call_kwargs,\n        )\n\n    def _get_dask_future(self, key: UUID) -&gt; \"distributed.Future\":\n        \"\"\"\n        Retrieve the dask future corresponding to a Prefect future.\n        The Dask future is for the `run_fn`, which should return a `State`.\n        \"\"\"\n        return self._dask_futures[key]\n\n    def _optimize_futures(self, expr):\n        def visit_fn(expr):\n            if isinstance(expr, PrefectFuture):\n                dask_future = self._dask_futures.get(expr.key)\n                if dask_future is not None:\n                    return dask_future\n            # Fallback to return the expression unaltered\n            return expr\n\n        return visit_collection(expr, visit_fn=visit_fn, return_data=True)\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        future = self._get_dask_future(key)\n        try:\n            return await future.result(timeout=timeout)\n        except distributed.TimeoutError:\n            return None\n        except BaseException as exc:\n            return await exception_to_crashed_state(exc)\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the task runner and prep for context exit.\n        - Creates a cluster if an external address is not set.\n        - Creates a client to connect to the cluster.\n        - Pushes a call to wait for all running futures to complete on exit.\n        \"\"\"\n\n        if self._cluster:\n            self.logger.info(f\"Connecting to existing Dask cluster {self._cluster}\")\n            self._connect_to = self._cluster\n            if self.adapt_kwargs:\n                self._cluster.adapt(**self.adapt_kwargs)\n        elif self.address:\n            self.logger.info(\n                f\"Connecting to an existing Dask cluster at {self.address}\"\n            )\n            self._connect_to = self.address\n        else:\n            self.cluster_class = self.cluster_class or distributed.LocalCluster\n\n            self.logger.info(\n                f\"Creating a new Dask cluster with \"\n                f\"`{to_qualified_name(self.cluster_class)}`\"\n            )\n            self._connect_to = self._cluster = await exit_stack.enter_async_context(\n                self.cluster_class(asynchronous=True, **self.cluster_kwargs)\n            )\n            if self.adapt_kwargs:\n                adapt_response = self._cluster.adapt(**self.adapt_kwargs)\n                if inspect.isawaitable(adapt_response):\n                    await adapt_response\n\n        self._client = await exit_stack.enter_async_context(\n            distributed.Client(\n                self._connect_to, asynchronous=True, **self.client_kwargs\n            )\n        )\n\n        if self._client.dashboard_link:\n            self.logger.info(\n                f\"The Dask dashboard is available at {self._client.dashboard_link}\",\n            )\n\n    def __getstate__(self):\n        \"\"\"\n        Allow the `DaskTaskRunner` to be serialized by dropping\n        the `distributed.Client`, which contains locks.\n        Must be deserialized on a dask worker.\n        \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_client\", \"_cluster\", \"_connect_to\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"\n        Restore the `distributed.Client` by loading the client on a dask worker.\n        \"\"\"\n        self.__dict__.update(data)\n        self._client = distributed.get_client()\n</code></pre>"},{"location":"integrations/prefect-dask/task_runners/#prefect_dask.task_runners.DaskTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Create a new instance of the task runner with the same settings.</p> Source code in <code>prefect_dask/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Create a new instance of the task runner with the same settings.\n    \"\"\"\n    return type(self)(\n        address=self.address,\n        cluster_class=self.cluster_class,\n        cluster_kwargs=self.cluster_kwargs,\n        adapt_kwargs=self.adapt_kwargs,\n        client_kwargs=self.client_kwargs,\n    )\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/","title":"Usage Guide","text":"<p>Use <code>prefect-dask</code> to speed up code with parallelization.</p>"},{"location":"integrations/prefect-dask/usage_guide/#run-tasks-on-dask","title":"Run tasks on Dask","text":"<p>The <code>DaskTaskRunner</code> is a parallel task runner that submits tasks to the <code>dask.distributed</code> scheduler.</p> <p>By default, a temporary Dask cluster is created for the duration of the flow run.</p> <p>For example, this flow counts up to 10 in parallel (note that the output is not sequential).</p> <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=DaskTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre> <p>If you already have a Dask cluster running, either local or cloud hosted, you can provide the connection URL via an <code>address</code> argument.</p> <p>To configure your flow to use the <code>DaskTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-dask</code> collection is installed as described earlier: <code>pip install prefect-dask</code>.</li> <li>In your flow code, import <code>DaskTaskRunner</code> from <code>prefect_dask.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=DaskTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>DaskTaskRunner</code> configured to access an existing Dask cluster at <code>http://my-dask-cluster</code>.</p> <pre><code>from prefect import flow\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@flow(task_runner=DaskTaskRunner(address=\"http://my-dask-cluster\"))\ndef my_flow():\n    ...\n</code></pre> <p><code>DaskTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Dask scheduler. cluster_class The cluster class to use when creating a temporary Dask cluster. It can be either the full class name (for example, <code>\"distributed.LocalCluster\"</code>), or the class itself. cluster_kwargs Additional kwargs to pass to the <code>cluster_class</code> when creating a temporary Dask cluster. adapt_kwargs Additional kwargs to pass to <code>cluster.adapt</code> when creating a temporary Dask cluster. Note that adaptive scaling is only enabled if <code>adapt_kwargs</code> are provided. client_kwargs Additional kwargs to use when creating a <code>dask.distributed.Client</code>. <p>Multiprocessing safety</p> <p>Note that, because the <code>DaskTaskRunner</code> uses multiprocessing, calls to flows in scripts must be guarded with <code>if __name__ == \"__main__\":</code> or you will encounter warnings and errors.</p> <p>If you don't provide the <code>address</code> of a Dask scheduler, Prefect creates a temporary local cluster automatically. The number of workers used is based on the number of cores available to your execution environment. The default provides a mix of processes and threads that should work well for most workloads. If you want to specify this explicitly, you can pass values for <code>n_workers</code> or <code>threads_per_worker</code> to <code>cluster_kwargs</code>.</p> <pre><code># Use 4 worker processes, each with 2 threads\nDaskTaskRunner(\n    cluster_kwargs={\"n_workers\": 4, \"threads_per_worker\": 2}\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#distributing-dask-collections-across-workers","title":"Distributing Dask collections across workers","text":"<p>If you use a Dask collection, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>, to distribute the work across workers and achieve parallel computations, use one of the context managers <code>get_dask_client</code> or <code>get_async_dask_client</code>:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\n@task\ndef compute_task():\n    with get_dask_client() as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = df.describe().compute()\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_flow():\n    prefect_future = compute_task.submit()\n    return prefect_future.result()\n\ndask_flow()\n</code></pre> <p>The context managers can be used the same way in both <code>flow</code> run contexts and <code>task</code> run contexts.</p> <p>Resolving futures in sync client</p> <p>Note, by default, <code>dask_collection.compute()</code> returns concrete values while <code>client.compute(dask_collection)</code> returns Dask Futures. Therefore, if you call <code>client.compute</code>, you must resolve all futures before exiting out of the context manager by either:</p> <ol> <li> <p>setting <code>sync=True</code> <pre><code>with get_dask_client() as client:\n    df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n    summary_df = client.compute(df.describe(), sync=True)\n</code></pre></p> </li> <li> <p>calling <code>result()</code> <pre><code>with get_dask_client() as client:\n    df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n    summary_df = client.compute(df.describe()).result()\n</code></pre> For more information, visit the docs on Waiting on Futures.</p> </li> </ol> <p>There is also an equivalent context manager for asynchronous tasks and flows: <code>get_async_dask_client</code>.</p> <pre><code>import asyncio\n\nimport dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_async_dask_client\n\n@task\nasync def compute_task():\n    async with get_async_dask_client() as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = await client.compute(df.describe())\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\nasync def dask_flow():\n    prefect_future = await compute_task.submit()\n    return await prefect_future.result()\n\nasyncio.run(dask_flow())\n</code></pre> <p>Resolving futures in async client</p> <p>With the async client, you do not need to set <code>sync=True</code> or call <code>result()</code>.</p> <p>However, you must <code>await client.compute(dask_collection)</code> before exiting the context manager.</p> <p>To invoke <code>compute</code> from the Dask collection, set <code>sync=False</code> and call <code>result()</code> before exiting out of the context manager: <code>await dask_collection.compute(sync=False)</code>.</p>"},{"location":"integrations/prefect-dask/usage_guide/#use-a-temporary-cluster","title":"Use a temporary cluster","text":"<p>The <code>DaskTaskRunner</code> is capable of creating a temporary cluster using any of Dask's cluster-manager options. This can be useful when you want each flow run to have its own Dask cluster, allowing for per-flow adaptive scaling.</p> <p>To configure, you need to provide a <code>cluster_class</code>. This can be:</p> <ul> <li>A string specifying the import path to the cluster class (for example, <code>\"dask_cloudprovider.aws.FargateCluster\"</code>)</li> <li>The cluster class itself</li> <li>A function for creating a custom cluster</li> </ul> <p>You can also configure <code>cluster_kwargs</code>, which takes a dictionary of keyword arguments to pass to <code>cluster_class</code> when starting the flow run.</p> <p>For example, to configure a flow to use a temporary <code>dask_cloudprovider.aws.FargateCluster</code> with 4 workers running with an image named <code>my-prefect-image</code>:</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    cluster_kwargs={\"n_workers\": 4, \"image\": \"my-prefect-image\"},\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#connect-to-an-existing-cluster","title":"Connect to an existing cluster","text":"<p>Multiple Prefect flow runs can all use the same existing Dask cluster. You might manage a single long-running Dask cluster (maybe using the Dask Helm Chart) and configure flows to connect to it during execution. This has a few downsides when compared to using a temporary cluster (as described above):</p> <ul> <li>All workers in the cluster must have dependencies installed for all flows you intend to run.</li> <li>Multiple flow runs may compete for resources. Dask tries to do a good job sharing resources between tasks, but you may still run into issues.</li> </ul> <p>That said, you may prefer managing a single long-running cluster.</p> <p>To configure a <code>DaskTaskRunner</code> to connect to an existing cluster, pass in the address of the scheduler to the <code>address</code> argument:</p> <pre><code># Connect to an existing cluster running at a specified address\nDaskTaskRunner(address=\"tcp://...\")\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#adaptive-scaling","title":"Adaptive scaling","text":"<p>One nice feature of using a <code>DaskTaskRunner</code> is the ability to scale adaptively to the workload. Instead of specifying <code>n_workers</code> as a fixed number, this lets you specify a minimum and maximum number of workers to use, and the dask cluster will scale up and down as needed.</p> <p>To do this, you can pass <code>adapt_kwargs</code> to <code>DaskTaskRunner</code>. This takes the following fields:</p> <ul> <li><code>maximum</code> (<code>int</code> or <code>None</code>, optional): the maximum number of workers to scale to. Set to <code>None</code> for no maximum.</li> <li><code>minimum</code> (<code>int</code> or <code>None</code>, optional): the minimum number of workers to scale to. Set to <code>None</code> for no minimum.</li> </ul> <p>For example, here we configure a flow to run on a <code>FargateCluster</code> scaling up to at most 10 workers.</p> <pre><code>DaskTaskRunner(\n    cluster_class=\"dask_cloudprovider.aws.FargateCluster\",\n    adapt_kwargs={\"maximum\": 10}\n)\n</code></pre>"},{"location":"integrations/prefect-dask/usage_guide/#dask-annotations","title":"Dask annotations","text":"<p>Dask annotations can be used to further control the behavior of tasks.</p> <p>For example, we can set the priority of tasks in the Dask scheduler:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n\n@flow(task_runner=DaskTaskRunner())\ndef my_flow():\n    with dask.annotate(priority=-10):\n        future = show(1)  # low priority task\n\n    with dask.annotate(priority=10):\n        future = show(2)  # high priority task\n</code></pre> <p>Another common use case is resource annotations:</p> <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask.task_runners import DaskTaskRunner\n\n@task\ndef show(x):\n    print(x)\n\n# Create a `LocalCluster` with some resource annotations\n# Annotations are abstract in dask and not inferred from your system.\n# Here, we claim that our system has 1 GPU and 1 process available per worker\n@flow(\n    task_runner=DaskTaskRunner(\n        cluster_kwargs={\"n_workers\": 1, \"resources\": {\"GPU\": 1, \"process\": 1}}\n    )\n)\ndef my_flow():\n    with dask.annotate(resources={'GPU': 1}):\n        future = show(0)  # this task requires 1 GPU resource on a worker\n\n    with dask.annotate(resources={'process': 1}):\n        # These tasks each require 1 process on a worker; because we've \n        # specified that our cluster has 1 process per worker and 1 worker,\n        # these tasks will run sequentially\n        future = show(1)\n        future = show(2)\n        future = show(3)\n</code></pre>"},{"location":"integrations/prefect-dask/utils/","title":"Utils","text":""},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils","title":"<code>prefect_dask.utils</code>","text":"<p>Utils to use alongside prefect-dask.</p>"},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils.get_async_dask_client","title":"<code>get_async_dask_client</code>  <code>async</code>","text":"<p>Yields a temporary asynchronous dask client; this is useful for parallelizing operations on dask collections, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p> <p>Without invoking this, workers do not automatically get a client to connect to the full cluster. Therefore, it will attempt perform work within the worker itself serially, and potentially overwhelming the single worker.</p> <p>Parameters:</p> Name Type Description Default <code>timeout</code> <code>Optional[Union[int, float, str, timedelta]]</code> <p>Timeout after which to error out; has no effect in flow run contexts because the client has already started; Defaults to the <code>distributed.comm.timeouts.connect</code> configuration value.</p> <code>None</code> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>distributed.Client</code>, and overwrites inherited keyword arguments from the task runner, if any.</p> <code>{}</code> <p>Yields:</p> Type Description <code>AsyncGenerator[Client, None]</code> <p>A temporary asynchronous dask client.</p> <p>Examples:</p> <p>Use <code>get_async_dask_client</code> to distribute work across workers. <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_async_dask_client\n\n@task\nasync def compute_task():\n    async with get_async_dask_client(timeout=\"120s\") as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = await client.compute(df.describe())\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\nasync def dask_flow():\n    prefect_future = await compute_task.submit()\n    return await prefect_future.result()\n\nasyncio.run(dask_flow())\n</code></pre></p> Source code in <code>prefect_dask/utils.py</code> <pre><code>@asynccontextmanager\nasync def get_async_dask_client(\n    timeout: Optional[Union[int, float, str, timedelta]] = None,\n    **client_kwargs: Dict[str, Any],\n) -&gt; AsyncGenerator[Client, None]:\n    \"\"\"\n    Yields a temporary asynchronous dask client; this is useful\n    for parallelizing operations on dask collections,\n    such as a `dask.DataFrame` or `dask.Bag`.\n\n    Without invoking this, workers do not automatically get a client to connect\n    to the full cluster. Therefore, it will attempt perform work within the\n    worker itself serially, and potentially overwhelming the single worker.\n\n    Args:\n        timeout: Timeout after which to error out; has no effect in\n            flow run contexts because the client has already started;\n            Defaults to the `distributed.comm.timeouts.connect`\n            configuration value.\n        client_kwargs: Additional keyword arguments to pass to\n            `distributed.Client`, and overwrites inherited keyword arguments\n            from the task runner, if any.\n\n    Yields:\n        A temporary asynchronous dask client.\n\n    Examples:\n        Use `get_async_dask_client` to distribute work across workers.\n        ```python\n        import dask\n        from prefect import flow, task\n        from prefect_dask import DaskTaskRunner, get_async_dask_client\n\n        @task\n        async def compute_task():\n            async with get_async_dask_client(timeout=\"120s\") as client:\n                df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n                summary_df = await client.compute(df.describe())\n            return summary_df\n\n        @flow(task_runner=DaskTaskRunner())\n        async def dask_flow():\n            prefect_future = await compute_task.submit()\n            return await prefect_future.result()\n\n        asyncio.run(dask_flow())\n        ```\n    \"\"\"\n    client_kwargs = _generate_client_kwargs(\n        async_client=True, timeout=timeout, **client_kwargs\n    )\n    async with Client(**client_kwargs) as client:\n        yield client\n</code></pre>"},{"location":"integrations/prefect-dask/utils/#prefect_dask.utils.get_dask_client","title":"<code>get_dask_client</code>","text":"<p>Yields a temporary synchronous dask client; this is useful for parallelizing operations on dask collections, such as a <code>dask.DataFrame</code> or <code>dask.Bag</code>.</p> <p>Without invoking this, workers do not automatically get a client to connect to the full cluster. Therefore, it will attempt perform work within the worker itself serially, and potentially overwhelming the single worker.</p> <p>When in an async context, we recommend using <code>get_async_dask_client</code> instead.</p> <p>Parameters:</p> Name Type Description Default <code>timeout</code> <code>Optional[Union[int, float, str, timedelta]]</code> <p>Timeout after which to error out; has no effect in flow run contexts because the client has already started; Defaults to the <code>distributed.comm.timeouts.connect</code> configuration value.</p> <code>None</code> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>distributed.Client</code>, and overwrites inherited keyword arguments from the task runner, if any.</p> <code>{}</code> <p>Yields:</p> Type Description <code>Client</code> <p>A temporary synchronous dask client.</p> <p>Examples:</p> <p>Use <code>get_dask_client</code> to distribute work across workers. <pre><code>import dask\nfrom prefect import flow, task\nfrom prefect_dask import DaskTaskRunner, get_dask_client\n\n@task\ndef compute_task():\n    with get_dask_client(timeout=\"120s\") as client:\n        df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n        summary_df = client.compute(df.describe()).result()\n    return summary_df\n\n@flow(task_runner=DaskTaskRunner())\ndef dask_flow():\n    prefect_future = compute_task.submit()\n    return prefect_future.result()\n\ndask_flow()\n</code></pre></p> Source code in <code>prefect_dask/utils.py</code> <pre><code>@contextmanager\ndef get_dask_client(\n    timeout: Optional[Union[int, float, str, timedelta]] = None,\n    **client_kwargs: Dict[str, Any],\n) -&gt; Generator[Client, None, None]:\n    \"\"\"\n    Yields a temporary synchronous dask client; this is useful\n    for parallelizing operations on dask collections,\n    such as a `dask.DataFrame` or `dask.Bag`.\n\n    Without invoking this, workers do not automatically get a client to connect\n    to the full cluster. Therefore, it will attempt perform work within the\n    worker itself serially, and potentially overwhelming the single worker.\n\n    When in an async context, we recommend using `get_async_dask_client` instead.\n\n    Args:\n        timeout: Timeout after which to error out; has no effect in\n            flow run contexts because the client has already started;\n            Defaults to the `distributed.comm.timeouts.connect`\n            configuration value.\n        client_kwargs: Additional keyword arguments to pass to\n            `distributed.Client`, and overwrites inherited keyword arguments\n            from the task runner, if any.\n\n    Yields:\n        A temporary synchronous dask client.\n\n    Examples:\n        Use `get_dask_client` to distribute work across workers.\n        ```python\n        import dask\n        from prefect import flow, task\n        from prefect_dask import DaskTaskRunner, get_dask_client\n\n        @task\n        def compute_task():\n            with get_dask_client(timeout=\"120s\") as client:\n                df = dask.datasets.timeseries(\"2000\", \"2001\", partition_freq=\"4w\")\n                summary_df = client.compute(df.describe()).result()\n            return summary_df\n\n        @flow(task_runner=DaskTaskRunner())\n        def dask_flow():\n            prefect_future = compute_task.submit()\n            return prefect_future.result()\n\n        dask_flow()\n        ```\n    \"\"\"\n    client_kwargs = _generate_client_kwargs(\n        async_client=False, timeout=timeout, **client_kwargs\n    )\n    with Client(**client_kwargs) as client:\n        yield client\n</code></pre>"},{"location":"integrations/prefect-databricks/","title":"prefect-databricks","text":"<p>Prefect integrations for interacting with Databricks</p> <p>The tasks within this collection were created by a code generator using the service's OpenAPI spec.</p> <p>The service's REST API documentation can be found here.</p>"},{"location":"integrations/prefect-databricks/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-databricks/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>A Databricks account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-databricks/#install-prefect-databricks","title":"Install <code>prefect-databricks</code>","text":"<pre><code>pip install prefect-databricks\n</code></pre>"},{"location":"integrations/prefect-databricks/#list-jobs-on-the-databricks-instance","title":"List jobs on the Databricks instance","text":"<pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.jobs import jobs_list\n\n\n@flow\ndef example_execute_endpoint_flow():\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n    jobs = jobs_list(\n        databricks_credentials,\n        limit=5\n    )\n    return jobs\n\nexample_execute_endpoint_flow()\n</code></pre>"},{"location":"integrations/prefect-databricks/#use-with_options-to-customize-options-on-any-existing-task-or-flow","title":"Use <code>with_options</code> to customize options on any existing task or flow","text":"<pre><code>custom_example_execute_endpoint_flow = example_execute_endpoint_flow.with_options(\n    name=\"My custom flow name\",\n    retries=2,\n    retry_delay_seconds=10,\n)\n</code></pre>"},{"location":"integrations/prefect-databricks/#launch-a-new-cluster-and-run-a-databricks-notebook","title":"Launch a new cluster and run a Databricks notebook","text":"<p>Notebook named <code>example.ipynb</code> on Databricks which accepts a name parameter:</p> <pre><code>name = dbutils.widgets.get(\"name\")\nmessage = f\"Don't worry {name}, I got your request! Welcome to prefect-databricks!\"\nprint(message)\n</code></pre> <p>Prefect flow that launches a new cluster to run <code>example.ipynb</code>:</p> <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.jobs import jobs_runs_submit\nfrom prefect_databricks.models.jobs import (\n    AutoScale,\n    AwsAttributes,\n    JobTaskSettings,\n    NotebookTask,\n    NewCluster,\n)\n\n\n@flow\ndef jobs_runs_submit_flow(notebook_path, **base_parameters):\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n\n    # specify new cluster settings\n    aws_attributes = AwsAttributes(\n        availability=\"SPOT\",\n        zone_id=\"us-west-2a\",\n        ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n        ebs_volume_count=3,\n        ebs_volume_size=100,\n    )\n    auto_scale = AutoScale(min_workers=1, max_workers=2)\n    new_cluster = NewCluster(\n        aws_attributes=aws_attributes,\n        autoscale=auto_scale,\n        node_type_id=\"m4.large\",\n        spark_version=\"10.4.x-scala2.12\",\n        spark_conf={\"spark.speculation\": True},\n    )\n\n    # specify notebook to use and parameters to pass\n    notebook_task = NotebookTask(\n        notebook_path=notebook_path,\n        base_parameters=base_parameters,\n    )\n\n    # compile job task settings\n    job_task_settings = JobTaskSettings(\n        new_cluster=new_cluster,\n        notebook_task=notebook_task,\n        task_key=\"prefect-task\"\n    )\n\n    run = jobs_runs_submit(\n        databricks_credentials=databricks_credentials,\n        run_name=\"prefect-job\",\n        tasks=[job_task_settings]\n    )\n\n    return run\n\n\njobs_runs_submit_flow(\"/Users/username@gmail.com/example.ipynb\", name=\"Marvin\")\n</code></pre> <p>Note, instead of using the built-in models, you may also input valid JSON. For example, <code>AutoScale(min_workers=1, max_workers=2)</code> is equivalent to <code>{\"min_workers\": 1, \"max_workers\": 2}</code>.</p>"},{"location":"integrations/prefect-databricks/#resources","title":"Resources","text":"<p>For assistance using Databricks, consult the Databricks documentation.</p> <p>Refer to the prefect-databricks API documentation linked in the sidebar to explore all the capabilities of the prefect-databricks library.</p>"},{"location":"integrations/prefect-databricks/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials","title":"<code>prefect_databricks.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with Databricks</p>"},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials.DatabricksCredentials","title":"<code>DatabricksCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage Databricks authentication.</p> <p>Attributes:</p> Name Type Description <code>databricks_instance</code> <code>str</code> <p>Databricks instance used in formatting the endpoint URL.</p> <code>token</code> <code>SecretStr</code> <p>The token to authenticate with Databricks.</p> <code>client_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to AsyncClient.</p> <p>Examples:</p> <p>Load stored Databricks credentials: <pre><code>from prefect_databricks import DatabricksCredentials\ndatabricks_credentials_block = DatabricksCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_databricks/credentials.py</code> <pre><code>class DatabricksCredentials(Block):\n    \"\"\"\n    Block used to manage Databricks authentication.\n\n    Attributes:\n        databricks_instance:\n            Databricks instance used in formatting the endpoint URL.\n        token: The token to authenticate with Databricks.\n        client_kwargs: Additional keyword arguments to pass to AsyncClient.\n\n    Examples:\n        Load stored Databricks credentials:\n        ```python\n        from prefect_databricks import DatabricksCredentials\n        databricks_credentials_block = DatabricksCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Databricks Credentials\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5GTHI1PH2dTiantfps6Fnc/1c750fab7f4c14ea1b93a62b9fea6a94/databricks_logo_icon_170295.png?h=250\"  # noqa\n\n    databricks_instance: str = Field(\n        default=...,\n        description=\"Databricks instance used in formatting the endpoint URL.\",\n    )\n    token: SecretStr = Field(\n        default=..., description=\"The token to authenticate with Databricks.\"\n    )\n    client_kwargs: Optional[Dict[str, Any]] = Field(\n        default=None, description=\"Additional keyword arguments to pass to AsyncClient.\"\n    )\n\n    def get_client(self) -&gt; AsyncClient:\n        \"\"\"\n        Gets an Databricks REST AsyncClient.\n\n        Returns:\n            An Databricks REST AsyncClient.\n\n        Example:\n            Gets a Databricks REST AsyncClient.\n            ```python\n            from prefect import flow\n            from prefect_databricks import DatabricksCredentials\n\n            @flow\n            def example_get_client_flow():\n                token = \"consumer_key\"\n                databricks_credentials = DatabricksCredentials(token=token)\n                client = databricks_credentials.get_client()\n                return client\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        base_url = f\"https://{self.databricks_instance}/api/\"\n\n        client_kwargs = self.client_kwargs or {}\n        client_kwargs[\"headers\"] = {\n            \"Authorization\": f\"Bearer {self.token.get_secret_value()}\"\n        }\n        client = AsyncClient(base_url=base_url, **client_kwargs)\n        return client\n</code></pre>"},{"location":"integrations/prefect-databricks/credentials/#prefect_databricks.credentials.DatabricksCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an Databricks REST AsyncClient.</p> <p>Returns:</p> Type Description <code>AsyncClient</code> <p>An Databricks REST AsyncClient.</p> Example <p>Gets a Databricks REST AsyncClient. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\n\n@flow\ndef example_get_client_flow():\n    token = \"consumer_key\"\n    databricks_credentials = DatabricksCredentials(token=token)\n    client = databricks_credentials.get_client()\n    return client\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_databricks/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncClient:\n    \"\"\"\n    Gets an Databricks REST AsyncClient.\n\n    Returns:\n        An Databricks REST AsyncClient.\n\n    Example:\n        Gets a Databricks REST AsyncClient.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n\n        @flow\n        def example_get_client_flow():\n            token = \"consumer_key\"\n            databricks_credentials = DatabricksCredentials(token=token)\n            client = databricks_credentials.get_client()\n            return client\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    base_url = f\"https://{self.databricks_instance}/api/\"\n\n    client_kwargs = self.client_kwargs or {}\n    client_kwargs[\"headers\"] = {\n        \"Authorization\": f\"Bearer {self.token.get_secret_value()}\"\n    }\n    client = AsyncClient(base_url=base_url, **client_kwargs)\n    return client\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/","title":"Flows","text":""},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows","title":"<code>prefect_databricks.flows</code>","text":"<p>Module containing flows for interacting with Databricks</p>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobInternalError","title":"<code>DatabricksJobInternalError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit encounters internal error</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobInternalError(Exception):\n    \"\"\"Raised when Databricks jobs runs submit encounters internal error\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobRunTimedOut","title":"<code>DatabricksJobRunTimedOut</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs does not complete in the configured max wait seconds</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobRunTimedOut(Exception):\n    \"\"\"\n    Raised when Databricks jobs runs does not complete in the configured max\n    wait seconds\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobSkipped","title":"<code>DatabricksJobSkipped</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit skips</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobSkipped(Exception):\n    \"\"\"Raised when Databricks jobs runs submit skips\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.DatabricksJobTerminated","title":"<code>DatabricksJobTerminated</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when Databricks jobs runs submit terminates</p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>class DatabricksJobTerminated(Exception):\n    \"\"\"Raised when Databricks jobs runs submit terminates\"\"\"\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_submit_and_wait_for_completion","title":"<code>jobs_runs_submit_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>tasks</code> <code>Optional[List[RunSubmitTaskSettings]]</code> <p>Tasks to run, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n    },\n]\n</code></pre></p> <code>None</code> <code>run_name</code> <code>Optional[str]</code> <p>An optional name for the run. The default value is <code>Untitled</code>, e.g. <code>A multitask job run</code>.</p> <code>None</code> <code>git_source</code> <code>Optional[GitSource]</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks. Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>return_metadata</code> <code>bool</code> <p>When True, method will return a tuple of notebook output as well as job run metadata; by default though, the method only returns notebook output</p> <code>False</code> <code>job_submission_handler</code> <code>Optional[Callable]</code> <p>An optional callable to intercept job submission.</p> <code>None</code> <code>**jobs_runs_submit_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>jobs_runs_submit</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata], None]</code> <p>Either a dict or a tuple (depends on <code>return_metadata</code>) comprised of</p> <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata], None]</code> <ul> <li>task_notebook_outputs: dictionary of task keys to its corresponding notebook output; this is the only object returned by default from this method</li> </ul> <code>Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata], None]</code> <ul> <li>jobs_runs_metadata: dictionary containing IDs of the jobs runs tasks; this is only returned if <code>return_metadata=True</code>.</li> </ul> <p>Examples:</p> <p>Submit jobs runs and wait. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import jobs_runs_submit_and_wait_for_completion\nfrom prefect_databricks.models.jobs import (\n    AutoScale,\n    AwsAttributes,\n    JobTaskSettings,\n    NotebookTask,\n    NewCluster,\n)\n\n@flow\ndef jobs_runs_submit_and_wait_for_completion_flow(notebook_path, **base_parameters):\n    databricks_credentials = await DatabricksCredentials.load(\"BLOCK_NAME\")\n\n    # specify new cluster settings\n    aws_attributes = AwsAttributes(\n        availability=\"SPOT\",\n        zone_id=\"us-west-2a\",\n        ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n        ebs_volume_count=3,\n        ebs_volume_size=100,\n    )\n    auto_scale = AutoScale(min_workers=1, max_workers=2)\n    new_cluster = NewCluster(\n        aws_attributes=aws_attributes,\n        autoscale=auto_scale,\n        node_type_id=\"m4.large\",\n        spark_version=\"10.4.x-scala2.12\",\n        spark_conf={\"spark.speculation\": True},\n    )\n\n    # specify notebook to use and parameters to pass\n    notebook_task = NotebookTask(\n        notebook_path=notebook_path,\n        base_parameters=base_parameters,\n    )\n\n    # compile job task settings\n    job_task_settings = JobTaskSettings(\n        new_cluster=new_cluster,\n        notebook_task=notebook_task,\n        task_key=\"prefect-task\"\n    )\n\n    multi_task_runs = jobs_runs_submit_and_wait_for_completion(\n        databricks_credentials=databricks_credentials,\n        run_name=\"prefect-job\",\n        tasks=[job_task_settings]\n    )\n\n    return multi_task_runs\n</code></pre></p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Submit jobs runs and wait for completion\",\n    description=(\n        \"Triggers a Databricks jobs runs and waits for the \"\n        \"triggered runs to complete.\"\n    ),\n)\nasync def jobs_runs_submit_and_wait_for_completion(\n    databricks_credentials: DatabricksCredentials,\n    tasks: Optional[List[RunSubmitTaskSettings]] = None,\n    run_name: Optional[str] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    git_source: Optional[GitSource] = None,\n    timeout_seconds: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    access_control_list: Optional[List[AccessControlRequest]] = None,\n    return_metadata: bool = False,\n    job_submission_handler: Optional[Callable] = None,\n    **jobs_runs_submit_kwargs: Dict[str, Any],\n) -&gt; Union[NotebookOutput, Tuple[NotebookOutput, JobMetadata], None]:\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        tasks: Tasks to run, e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                },\n            ]\n            ```\n        run_name:\n            An optional name for the run. The default value is `Untitled`, e.g. `A\n            multitask job run`.\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks. Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        access_control_list:\n            List of permissions to set on the job.\n        max_wait_seconds: Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        return_metadata: When True, method will return a tuple of notebook output as well as\n            job run metadata; by default though, the method only returns notebook output\n        job_submission_handler: An optional callable to intercept job submission.\n        **jobs_runs_submit_kwargs: Additional keyword arguments to pass to `jobs_runs_submit`.\n\n    Returns:\n        Either a dict or a tuple (depends on `return_metadata`) comprised of\n        * task_notebook_outputs: dictionary of task keys to its corresponding notebook output;\n          this is the only object returned by default from this method\n        * jobs_runs_metadata: dictionary containing IDs of the jobs runs tasks; this is only\n          returned if `return_metadata=True`.\n\n    Examples:\n        Submit jobs runs and wait.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import jobs_runs_submit_and_wait_for_completion\n        from prefect_databricks.models.jobs import (\n            AutoScale,\n            AwsAttributes,\n            JobTaskSettings,\n            NotebookTask,\n            NewCluster,\n        )\n\n        @flow\n        def jobs_runs_submit_and_wait_for_completion_flow(notebook_path, **base_parameters):\n            databricks_credentials = await DatabricksCredentials.load(\"BLOCK_NAME\")\n\n            # specify new cluster settings\n            aws_attributes = AwsAttributes(\n                availability=\"SPOT\",\n                zone_id=\"us-west-2a\",\n                ebs_volume_type=\"GENERAL_PURPOSE_SSD\",\n                ebs_volume_count=3,\n                ebs_volume_size=100,\n            )\n            auto_scale = AutoScale(min_workers=1, max_workers=2)\n            new_cluster = NewCluster(\n                aws_attributes=aws_attributes,\n                autoscale=auto_scale,\n                node_type_id=\"m4.large\",\n                spark_version=\"10.4.x-scala2.12\",\n                spark_conf={\"spark.speculation\": True},\n            )\n\n            # specify notebook to use and parameters to pass\n            notebook_task = NotebookTask(\n                notebook_path=notebook_path,\n                base_parameters=base_parameters,\n            )\n\n            # compile job task settings\n            job_task_settings = JobTaskSettings(\n                new_cluster=new_cluster,\n                notebook_task=notebook_task,\n                task_key=\"prefect-task\"\n            )\n\n            multi_task_runs = jobs_runs_submit_and_wait_for_completion(\n                databricks_credentials=databricks_credentials,\n                run_name=\"prefect-job\",\n                tasks=[job_task_settings]\n            )\n\n            return multi_task_runs\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    # submit the jobs runs\n    multi_task_jobs_runs_future = await jobs_runs_submit.submit(\n        databricks_credentials=databricks_credentials,\n        tasks=tasks,\n        run_name=run_name,\n        git_source=git_source,\n        timeout_seconds=timeout_seconds,\n        idempotency_token=idempotency_token,\n        access_control_list=access_control_list,\n        **jobs_runs_submit_kwargs,\n    )\n    multi_task_jobs_runs = await multi_task_jobs_runs_future.result()\n    if job_submission_handler:\n        result = job_submission_handler(multi_task_jobs_runs)\n        if inspect.isawaitable(result):\n            await result\n    multi_task_jobs_runs_id = multi_task_jobs_runs[\"run_id\"]\n\n    # wait for all the jobs runs to complete in a separate flow\n    # for a cleaner radar interface\n    jobs_runs_state, jobs_runs_metadata = await jobs_runs_wait_for_completion(\n        multi_task_jobs_runs_id=multi_task_jobs_runs_id,\n        databricks_credentials=databricks_credentials,\n        run_name=run_name,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    # fetch the state results\n    jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n    jobs_runs_state_message = jobs_runs_state[\"state_message\"]\n\n    # return results or raise error\n    if jobs_runs_life_cycle_state == RunLifeCycleState.terminated.value:\n        jobs_runs_result_state = jobs_runs_state.get(\"result_state\", None)\n        if jobs_runs_result_state == RunResultState.success.value:\n            task_notebook_outputs = {}\n            for task in jobs_runs_metadata[\"tasks\"]:\n                task_key = task[\"task_key\"]\n                task_run_id = task[\"run_id\"]\n                task_run_output_future = await jobs_runs_get_output.submit(\n                    run_id=task_run_id,\n                    databricks_credentials=databricks_credentials,\n                )\n                task_run_output = await task_run_output_future.result()\n                task_run_notebook_output = task_run_output.get(\"notebook_output\", {})\n                task_notebook_outputs[task_key] = task_run_notebook_output\n            logger.info(\n                \"Databricks Jobs Runs Submit (%s ID %s) completed successfully!\",\n                run_name,\n                multi_task_jobs_runs_id,\n            )\n            if return_metadata:\n                return task_notebook_outputs, jobs_runs_metadata\n            return task_notebook_outputs\n        else:\n            raise DatabricksJobTerminated(\n                f\"Databricks Jobs Runs Submit \"\n                f\"({run_name} ID {multi_task_jobs_runs_id}) \"\n                f\"terminated with result state, {jobs_runs_result_state}: \"\n                f\"{jobs_runs_state_message}\"\n            )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.skipped.value:\n        raise DatabricksJobSkipped(\n            f\"Databricks Jobs Runs Submit ({run_name} ID \"\n            f\"{multi_task_jobs_runs_id}) was skipped: {jobs_runs_state_message}.\",\n        )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.internalerror.value:\n        raise DatabricksJobInternalError(\n            f\"Databricks Jobs Runs Submit ({run_name} ID \"\n            f\"{multi_task_jobs_runs_id}) \"\n            f\"encountered an internal error: {jobs_runs_state_message}.\",\n        )\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_submit_by_id_and_wait_for_completion","title":"<code>jobs_runs_submit_by_id_and_wait_for_completion</code>  <code>async</code>","text":"<p>flow that triggers an existing job and waits for its completion</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>int</code> <p>Id of the databricks job.</p> required <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example \"jar_params\" : [\"john doe\", \"35\"]. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon run- now, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example {\"jar_params\": [\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example \"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The map is passed to the notebook and is accessible through the dbutils.widgets.get function. If not specified upon run-now, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params. Use Task parameter variables to set parameters containing information about job runs. The JSON representation of this field (for example {\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}) cannot exceed 10,000 bytes.</p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example \"python_params\" :[\"john doe\", \"35\"]. The parameters are passed to Python file as command- line parameters. If specified upon run-now, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes Use Task parameter variables to set parameters containing information about job runs. These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.</p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example \"spark_submit_params\": [\"--class\", \"org.apache.spark.examples.SparkPi\"]. The parameters are passed to spark-submit script as command-line parameters. If specified upon run-now, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes. Use Task parameter variables to set parameters containing information about job runs. These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.</p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example \"python_named_params\": {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}.</p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <p>If <code>full_refresh</code> is set to true, trigger a full refresh on the delta live table e.g. <pre><code>    \"pipeline_params\": {\"full_refresh\": true}\n</code></pre></p> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example \"sql_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The SQL alert task does not support custom parameters.</p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example \"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]</p> <code>None</code> <code>job_submission_handler</code> <code>Optional[Callable]</code> <p>An optional callable to intercept job submission</p> <code>None</code> <p>Raises:</p> Type Description <code>DatabricksJobTerminated</code> <p>Raised when the Databricks job run is terminated with a non-successful result state.</p> <code>DatabricksJobSkipped</code> <p>Raised when the Databricks job run is skipped.</p> <code>DatabricksJobInternalError</code> <p>Raised when the Databricks job run encounters an internal error.</p> <p>Returns:</p> Name Type Description <code>Dict</code> <code>Dict</code> <p>A dictionary containing information about the completed job run.</p> Example <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import (\n    jobs_runs_submit_by_id_and_wait_for_completion,\n)\n\n\n@flow\ndef submit_existing_job(block_name: str, job_id):\n    databricks_credentials = DatabricksCredentials.load(block_name)\n\n    run = jobs_runs_submit_by_id_and_wait_for_completion(\n        databricks_credentials=databricks_credentials, job_id=job_id\n    )\n\n    return run\n\n\nsubmit_existing_job(block_name=\"db-creds\", job_id=db_job_id)\n</code></pre> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Submit existing job runs and wait for completion\",\n    description=(\n        \"Triggers a Databricks jobs runs and waits for the \"\n        \"triggered runs to complete.\"\n    ),\n)\nasync def jobs_runs_submit_by_id_and_wait_for_completion(\n    databricks_credentials: DatabricksCredentials,\n    job_id: int,\n    idempotency_token: Optional[str] = None,\n    jar_params: Optional[List[str]] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n    job_submission_handler: Optional[Callable] = None,\n    **jobs_runs_submit_kwargs: Dict[str, Any],\n) -&gt; Dict:\n    \"\"\"flow that triggers an existing job and waits for its completion\n\n    Args:\n        databricks_credentials: Credentials to use for authentication with Databricks.\n        job_id: Id of the databricks job.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example \"jar_params\"\n            : [\"john doe\", \"35\"]. The parameters are used to invoke the main function of\n            the main class specified in the Spark JAR task. If not specified upon run-\n            now, it defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of this field (for\n            example {\"jar_params\": [\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.\n        max_wait_seconds:\n            Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            \"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}. The map is\n            passed to the notebook and is accessible through the dbutils.widgets.get\n            function. If not specified upon run-now, the triggered run uses the job\u2019s\n            base parameters. notebook_params cannot be specified in conjunction with\n            jar_params. Use Task parameter variables to set parameters containing\n            information about job runs. The JSON representation of this field\n            (for example {\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}) cannot\n            exceed 10,000 bytes.\n        python_params:\n            A list of parameters for jobs with Python tasks, for example \"python_params\"\n            :[\"john doe\", \"35\"]. The parameters are passed to Python file as command-\n            line parameters. If specified upon run-now, it would overwrite the\n            parameters specified in job setting. The JSON representation of this field\n            (for example {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes\n            Use Task parameter variables to set parameters containing information\n            about job runs. These parameters accept only Latin characters (ASCII\n            character set). Using non-ASCII characters returns an error. Examples of\n            invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            \"spark_submit_params\": [\"--class\", \"org.apache.spark.examples.SparkPi\"].\n            The parameters are passed to spark-submit script as command-line parameters.\n            If specified upon run-now, it would overwrite the parameters specified in\n            job setting. The JSON representation of this field (for example\n            {\"python_params\":[\"john doe\",\"35\"]}) cannot exceed 10,000 bytes.\n            Use Task parameter variables to set parameters containing information about\n            job runs. These parameters accept only Latin characters (ASCII character\n            set). Using non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and emojis.\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            \"python_named_params\": {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}.\n        pipeline_params:\n            If `full_refresh` is set to true, trigger a full refresh on the\n            delta live table e.g.\n            ```\n                \"pipeline_params\": {\"full_refresh\": true}\n            ```\n        sql_params:\n            A map from keys to values for SQL tasks, for example \"sql_params\":\n            {\"name\": \"john doe\", \"age\": \"35\"}. The SQL alert task does not support\n            custom parameters.\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task,\n            for example \"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n        job_submission_handler: An optional callable to intercept job submission\n\n    Raises:\n        DatabricksJobTerminated:\n            Raised when the Databricks job run is terminated with a non-successful\n            result state.\n        DatabricksJobSkipped: Raised when the Databricks job run is skipped.\n        DatabricksJobInternalError:\n            Raised when the Databricks job run encounters an internal error.\n\n    Returns:\n        Dict: A dictionary containing information about the completed job run.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import (\n            jobs_runs_submit_by_id_and_wait_for_completion,\n        )\n\n\n        @flow\n        def submit_existing_job(block_name: str, job_id):\n            databricks_credentials = DatabricksCredentials.load(block_name)\n\n            run = jobs_runs_submit_by_id_and_wait_for_completion(\n                databricks_credentials=databricks_credentials, job_id=job_id\n            )\n\n            return run\n\n\n        submit_existing_job(block_name=\"db-creds\", job_id=db_job_id)\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    # submit the jobs runs\n\n    jobs_runs_future = await jobs_run_now.submit(\n        databricks_credentials=databricks_credentials,\n        job_id=job_id,\n        idempotency_token=idempotency_token,\n        jar_params=jar_params,\n        notebook_params=notebook_params,\n        python_params=python_params,\n        spark_submit_params=spark_submit_params,\n        python_named_params=python_named_params,\n        pipeline_params=pipeline_params,\n        sql_params=sql_params,\n        dbt_commands=dbt_commands,\n        **jobs_runs_submit_kwargs,\n    )\n\n    jobs_runs = await jobs_runs_future.result()\n\n    if job_submission_handler:\n        result = job_submission_handler(jobs_runs)\n        if inspect.isawaitable(result):\n            await result\n    job_run_id = jobs_runs[\"run_id\"]\n\n    # wait for all the jobs runs to complete in a separate flow\n    # for a cleaner radar interface\n    jobs_runs_state, jobs_runs_metadata = await jobs_runs_wait_for_completion(\n        multi_task_jobs_runs_id=job_run_id,\n        databricks_credentials=databricks_credentials,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    # fetch the state results\n    jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n    jobs_runs_state_message = jobs_runs_state[\"state_message\"]\n\n    # return results or raise error\n    if jobs_runs_life_cycle_state == RunLifeCycleState.terminated.value:\n        jobs_runs_result_state = jobs_runs_state.get(\"result_state\", None)\n        if jobs_runs_result_state == RunResultState.success.value:\n            task_notebook_outputs = {}\n            for task in jobs_runs_metadata[\"tasks\"]:\n                task_key = task[\"task_key\"]\n                task_run_id = task[\"run_id\"]\n                task_run_output_future = await jobs_runs_get_output.submit(\n                    run_id=task_run_id,\n                    databricks_credentials=databricks_credentials,\n                )\n                task_run_output = await task_run_output_future.result()\n                task_run_notebook_output = task_run_output.get(\"notebook_output\", {})\n                task_notebook_outputs[task_key] = task_run_notebook_output\n            logger.info(\n                f\"Databricks Jobs Runs Submit {job_id} completed successfully!\",\n            )\n            return task_notebook_outputs\n        else:\n            raise DatabricksJobTerminated(\n                f\"Databricks Jobs Runs Submit ID {job_id} \"\n                f\"terminated with result state, {jobs_runs_result_state}: \"\n                f\"{jobs_runs_state_message}\"\n            )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.skipped.value:\n        raise DatabricksJobSkipped(\n            f\"Databricks Jobs Runs Submit ID \"\n            f\"{job_id} was skipped: {jobs_runs_state_message}.\",\n        )\n    elif jobs_runs_life_cycle_state == RunLifeCycleState.internalerror.value:\n        raise DatabricksJobInternalError(\n            f\"Databricks Jobs Runs Submit ID \"\n            f\"{job_id} \"\n            f\"encountered an internal error: {jobs_runs_state_message}.\",\n        )\n</code></pre>"},{"location":"integrations/prefect-databricks/flows/#prefect_databricks.flows.jobs_runs_wait_for_completion","title":"<code>jobs_runs_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>run_name</code> <code>Optional[str]</code> <p>The name of the jobs runs task.</p> <code>None</code> <code>multi_task_jobs_run_id</code> <p>The ID of the jobs runs task to watch.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for the entire flow to complete.</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <p>Returns:</p> Name Type Description <code>jobs_runs_state</code> <p>A dict containing the jobs runs life cycle state and message.</p> <code>jobs_runs_metadata</code> <p>A dict containing IDs of the jobs runs tasks.</p> Example <p>Waits for completion on jobs runs. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.flows import jobs_runs_wait_for_completion\n\n@flow\ndef jobs_runs_wait_for_completion_flow():\n    databricks_credentials = DatabricksCredentials.load(\"BLOCK_NAME\")\n    return jobs_runs_wait_for_completion(\n        multi_task_jobs_run_id=45429,\n        databricks_credentials=databricks_credentials,\n        run_name=\"my_run_name\",\n        max_wait_seconds=1800,  # 30 minutes\n        poll_frequency_seconds=120,  # 2 minutes\n    )\n</code></pre></p> Source code in <code>prefect_databricks/flows.py</code> <pre><code>@flow(\n    name=\"Wait for completion of jobs runs\",\n    description=\"Waits for the jobs runs to finish running\",\n)\nasync def jobs_runs_wait_for_completion(\n    multi_task_jobs_runs_id: int,\n    databricks_credentials: DatabricksCredentials,\n    run_name: Optional[str] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n):\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        run_name: The name of the jobs runs task.\n        multi_task_jobs_run_id: The ID of the jobs runs task to watch.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        max_wait_seconds:\n            Maximum number of seconds to wait for the entire flow to complete.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        jobs_runs_state: A dict containing the jobs runs life cycle state and message.\n        jobs_runs_metadata: A dict containing IDs of the jobs runs tasks.\n\n    Example:\n        Waits for completion on jobs runs.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.flows import jobs_runs_wait_for_completion\n\n        @flow\n        def jobs_runs_wait_for_completion_flow():\n            databricks_credentials = DatabricksCredentials.load(\"BLOCK_NAME\")\n            return jobs_runs_wait_for_completion(\n                multi_task_jobs_run_id=45429,\n                databricks_credentials=databricks_credentials,\n                run_name=\"my_run_name\",\n                max_wait_seconds=1800,  # 30 minutes\n                poll_frequency_seconds=120,  # 2 minutes\n            )\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    seconds_waited_for_run_completion = 0\n    wait_for = []\n\n    jobs_status = {}\n    tasks_status = {}\n    while seconds_waited_for_run_completion &lt;= max_wait_seconds:\n        jobs_runs_metadata_future = await jobs_runs_get.submit(\n            run_id=multi_task_jobs_runs_id,\n            databricks_credentials=databricks_credentials,\n            wait_for=wait_for,\n        )\n        wait_for = [jobs_runs_metadata_future]\n\n        jobs_runs_metadata = await jobs_runs_metadata_future.result()\n        jobs_status = _update_and_log_state_changes(\n            jobs_status, jobs_runs_metadata, logger, \"Job\"\n        )\n        jobs_runs_metadata_tasks = jobs_runs_metadata.get(\"tasks\", [])\n        for task_metadata in jobs_runs_metadata_tasks:\n            tasks_status = _update_and_log_state_changes(\n                tasks_status, task_metadata, logger, \"Task\"\n            )\n\n        jobs_runs_state = jobs_runs_metadata.get(\"state\", {})\n        jobs_runs_life_cycle_state = jobs_runs_state[\"life_cycle_state\"]\n        if jobs_runs_life_cycle_state in TERMINAL_STATUS_CODES:\n            return jobs_runs_state, jobs_runs_metadata\n\n        logger.info(\"Waiting for %s seconds.\", poll_frequency_seconds)\n        await asyncio.sleep(poll_frequency_seconds)\n        seconds_waited_for_run_completion += poll_frequency_seconds\n\n    raise DatabricksJobRunTimedOut(\n        f\"Max wait time of {max_wait_seconds} seconds exceeded while waiting \"\n        f\"for job run ({run_name} ID {multi_task_jobs_runs_id})\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs","title":"<code>prefect_databricks.jobs</code>","text":"<p>This is a module containing tasks for interacting with: Databricks jobs</p>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_create","title":"<code>jobs_create</code>  <code>async</code>","text":"<p>Create a new job.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>name</code> <code>str</code> <p>An optional name for the job, e.g. <code>A multitask job</code>.</p> <code>'Untitled'</code> <code>tags</code> <code>Dict</code> <p>A map of tags associated with the job. These are forwarded to the cluster as cluster tags for jobs clusters, and are subject to the same limitations as cluster tags. A maximum of 25 tags can be added to the job, e.g. <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre></p> <code>None</code> <code>tasks</code> <code>Optional[List[JobTaskSettings]]</code> <p>A list of task specifications to be executed by this job, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre></p> <code>None</code> <code>job_clusters</code> <code>Optional[List[JobCluster]]</code> <p>A list of job cluster specifications that can be shared and reused by tasks of this job. Libraries cannot be declared in a shared job cluster. You must declare dependent libraries in task settings, e.g. <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n    }\n]\n</code></pre></p> <code>None</code> <code>email_notifications</code> <code>JobEmailNotifications</code> <p>An optional set of email addresses that is notified when runs of this job begin or complete as well as when this job is deleted. The default behavior is to not send any emails. Key-values: - on_start:     A list of email addresses to be notified when a run begins.     If not specified on job creation, reset, or update, the list     is empty, and notifications are not sent, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - on_success:     A list of email addresses to be notified when a run     successfully completes. A run is considered to have     completed successfully if it ends with a <code>TERMINATED</code> <code>life_cycle_state</code> and a <code>SUCCESSFUL</code> result_state. If not     specified on job creation, reset, or update, the list is     empty, and notifications are not sent, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - on_failure:     A list of email addresses to notify when a run completes     unsuccessfully. A run is considered unsuccessful if it ends     with an <code>INTERNAL_ERROR</code> <code>life_cycle_state</code> or a <code>SKIPPED</code>,     <code>FAILED</code>, or <code>TIMED_OUT</code> <code>result_state</code>. If not specified on     job creation, reset, or update, or the list is empty, then     notifications are not sent. Job-level failure notifications     are sent only once after the entire job run (including all     of its retries) has failed. Notifications are not sent when     failed job runs are retried. To receive a failure     notification after every failed task (including every failed     retry), use task-level notifications instead, e.g.     <pre><code>[\"user.name@databricks.com\"]\n</code></pre> - no_alert_for_skipped_runs:     If true, do not send email to recipients specified in     <code>on_failure</code> if the run is skipped.</p> <code>None</code> <code>webhook_notifications</code> <code>WebhookNotifications</code> <p>A collection of system notification IDs to notify when runs of this job begin or complete. The default behavior is to not send any system notifications. Key-values: - on_start:     An optional list of notification IDs to call when the run     starts. A maximum of 3 destinations can be specified for the     <code>on_start</code> property, e.g.     <pre><code>[\n    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n]\n</code></pre> - on_success:     An optional list of notification IDs to call when the run     completes successfully. A maximum of 3 destinations can be     specified for the <code>on_success</code> property, e.g.     <pre><code>[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n</code></pre> - on_failure:     An optional list of notification IDs to call when the run     fails. A maximum of 3 destinations can be specified for the     <code>on_failure</code> property, e.g.     <pre><code>[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n</code></pre></p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>schedule</code> <code>CronSchedule</code> <p>An optional periodic schedule for this job. The default behavior is that the job only runs when triggered by clicking \u201cRun Now\u201d in the Jobs UI or sending an API request to <code>runNow</code>. Key-values: - quartz_cron_expression:     A Cron expression using Quartz syntax that describes the     schedule for a job. See Cron Trigger     for details. This field is required, e.g. <code>20 30 * * * ?</code>. - timezone_id:     A Java timezone ID. The schedule for a job is resolved with     respect to this timezone. See Java     TimeZone     for details. This field is required, e.g. <code>Europe/London</code>. - pause_status:     Indicate whether this schedule is paused or not, e.g.     <code>PAUSED</code>.</p> <code>None</code> <code>max_concurrent_runs</code> <code>Optional[int]</code> <p>An optional maximum allowed number of concurrent runs of the job.  Set this value if you want to be able to execute multiple runs of the same job concurrently. This is useful for example if you trigger your job on a frequent schedule and want to allow consecutive runs to overlap with each other, or if you want to trigger multiple runs which differ by their input parameters.  This setting affects only new runs. For example, suppose the job\u2019s concurrency is 4 and there are 4 concurrent active runs. Then setting the concurrency to 3 won\u2019t kill any of the active runs. However, from then on, new runs are skipped unless there are fewer than 3 active runs.  This value cannot exceed 1000. Setting this value to 0 causes all new runs to be skipped. The default behavior is to allow only 1 concurrent run, e.g. <code>10</code>.</p> <code>None</code> <code>git_source</code> <code>GitSource</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks, e.g. <code>{     \"git_url\": \"https://github.com/databricks/databricks-cli\",     \"git_branch\": \"main\",     \"git_provider\": \"gitHub\", }</code> Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>format</code> <code>Optional[str]</code> <p>Used to tell what is the format of the job. This field is ignored in Create/Update/Reset calls. When using the Jobs API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g. <code>MULTI_TASK</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/create</code></p> API Responses: Response Description 200 Job was created successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_create(\n    databricks_credentials: \"DatabricksCredentials\",\n    name: str = \"Untitled\",\n    tags: Dict = None,\n    tasks: Optional[List[\"models.JobTaskSettings\"]] = None,\n    job_clusters: Optional[List[\"models.JobCluster\"]] = None,\n    email_notifications: \"models.JobEmailNotifications\" = None,\n    webhook_notifications: \"models.WebhookNotifications\" = None,\n    timeout_seconds: Optional[int] = None,\n    schedule: \"models.CronSchedule\" = None,\n    max_concurrent_runs: Optional[int] = None,\n    git_source: \"models.GitSource\" = None,\n    format: Optional[str] = None,\n    access_control_list: Optional[List[\"models.AccessControlRequest\"]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Create a new job.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        name:\n            An optional name for the job, e.g. `A multitask job`.\n        tags:\n            A map of tags associated with the job. These are forwarded to the\n            cluster as cluster tags for jobs clusters, and are subject\n            to the same limitations as cluster tags. A maximum of 25\n            tags can be added to the job, e.g.\n            ```\n            {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n            ```\n        tasks:\n            A list of task specifications to be executed by this job, e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"job_cluster_key\": \"auto_scaling_cluster\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"source\": \"WORKSPACE\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                    \"max_retries\": 3,\n                    \"min_retry_interval_millis\": 2000,\n                    \"retry_on_timeout\": False,\n                },\n            ]\n            ```\n        job_clusters:\n            A list of job cluster specifications that can be shared and reused by\n            tasks of this job. Libraries cannot be declared in a shared\n            job cluster. You must declare dependent libraries in task\n            settings, e.g.\n            ```\n            [\n                {\n                    \"job_cluster_key\": \"auto_scaling_cluster\",\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                }\n            ]\n            ```\n        email_notifications:\n            An optional set of email addresses that is notified when runs of this\n            job begin or complete as well as when this job is deleted.\n            The default behavior is to not send any emails. Key-values:\n            - on_start:\n                A list of email addresses to be notified when a run begins.\n                If not specified on job creation, reset, or update, the list\n                is empty, and notifications are not sent, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - on_success:\n                A list of email addresses to be notified when a run\n                successfully completes. A run is considered to have\n                completed successfully if it ends with a `TERMINATED`\n                `life_cycle_state` and a `SUCCESSFUL` result_state. If not\n                specified on job creation, reset, or update, the list is\n                empty, and notifications are not sent, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - on_failure:\n                A list of email addresses to notify when a run completes\n                unsuccessfully. A run is considered unsuccessful if it ends\n                with an `INTERNAL_ERROR` `life_cycle_state` or a `SKIPPED`,\n                `FAILED`, or `TIMED_OUT` `result_state`. If not specified on\n                job creation, reset, or update, or the list is empty, then\n                notifications are not sent. Job-level failure notifications\n                are sent only once after the entire job run (including all\n                of its retries) has failed. Notifications are not sent when\n                failed job runs are retried. To receive a failure\n                notification after every failed task (including every failed\n                retry), use task-level notifications instead, e.g.\n                ```\n                [\"user.name@databricks.com\"]\n                ```\n            - no_alert_for_skipped_runs:\n                If true, do not send email to recipients specified in\n                `on_failure` if the run is skipped.\n        webhook_notifications:\n            A collection of system notification IDs to notify when runs of this job\n            begin or complete. The default behavior is to not send any\n            system notifications. Key-values:\n            - on_start:\n                An optional list of notification IDs to call when the run\n                starts. A maximum of 3 destinations can be specified for the\n                `on_start` property, e.g.\n                ```\n                [\n                    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n                    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n                ]\n                ```\n            - on_success:\n                An optional list of notification IDs to call when the run\n                completes successfully. A maximum of 3 destinations can be\n                specified for the `on_success` property, e.g.\n                ```\n                [{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n                ```\n            - on_failure:\n                An optional list of notification IDs to call when the run\n                fails. A maximum of 3 destinations can be specified for the\n                `on_failure` property, e.g.\n                ```\n                [{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n                ```\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        schedule:\n            An optional periodic schedule for this job. The default behavior is that\n            the job only runs when triggered by clicking \u201cRun Now\u201d in\n            the Jobs UI or sending an API request to `runNow`. Key-values:\n            - quartz_cron_expression:\n                A Cron expression using Quartz syntax that describes the\n                schedule for a job. See [Cron Trigger](http://www.quartz-\n                scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)\n                for details. This field is required, e.g. `20 30 * * * ?`.\n            - timezone_id:\n                A Java timezone ID. The schedule for a job is resolved with\n                respect to this timezone. See [Java\n                TimeZone](https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html)\n                for details. This field is required, e.g. `Europe/London`.\n            - pause_status:\n                Indicate whether this schedule is paused or not, e.g.\n                `PAUSED`.\n        max_concurrent_runs:\n            An optional maximum allowed number of concurrent runs of the job.  Set\n            this value if you want to be able to execute multiple runs\n            of the same job concurrently. This is useful for example if\n            you trigger your job on a frequent schedule and want to\n            allow consecutive runs to overlap with each other, or if you\n            want to trigger multiple runs which differ by their input\n            parameters.  This setting affects only new runs. For\n            example, suppose the job\u2019s concurrency is 4 and there are 4\n            concurrent active runs. Then setting the concurrency to 3\n            won\u2019t kill any of the active runs. However, from then on,\n            new runs are skipped unless there are fewer than 3 active\n            runs.  This value cannot exceed 1000\\. Setting this value to\n            0 causes all new runs to be skipped. The default behavior is\n            to allow only 1 concurrent run, e.g. `10`.\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks, e.g.\n            ```\n            {\n                \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                \"git_branch\": \"main\",\n                \"git_provider\": \"gitHub\",\n            }\n            ``` Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        format:\n            Used to tell what is the format of the job. This field is ignored in\n            Create/Update/Reset calls. When using the Jobs API 2.1 this\n            value is always set to `'MULTI_TASK'`, e.g. `MULTI_TASK`.\n        access_control_list:\n            List of permissions to set on the job.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/create`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was created successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/create\"  # noqa\n\n    responses = {\n        200: \"Job was created successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"name\": name,\n        \"tags\": tags,\n        \"tasks\": tasks,\n        \"job_clusters\": job_clusters,\n        \"email_notifications\": email_notifications,\n        \"webhook_notifications\": webhook_notifications,\n        \"timeout_seconds\": timeout_seconds,\n        \"schedule\": schedule,\n        \"max_concurrent_runs\": max_concurrent_runs,\n        \"git_source\": git_source,\n        \"format\": format,\n        \"access_control_list\": access_control_list,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_delete","title":"<code>jobs_delete</code>  <code>async</code>","text":"<p>Deletes a job.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to delete. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/delete</code></p> API Responses: Response Description 200 Job was deleted successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_delete(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deletes a job.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to delete. This field is required,\n            e.g. `11223344`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/delete`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was deleted successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/delete\"  # noqa\n\n    responses = {\n        200: \"Job was deleted successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_get","title":"<code>jobs_get</code>  <code>async</code>","text":"<p>Retrieves the details for a single job.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>The canonical identifier of the job to retrieve information about. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code>- <code>creator_user_name: str</code>- <code>run_as_user_name: str</code>- <code>settings: \"models.JobSettings\"</code>- <code>created_time: int</code></p> API Endpoint: <p><code>/2.1/jobs/get</code></p> API Responses: Response Description 200 Job was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_get(\n    job_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieves the details for a single job.\n\n    Args:\n        job_id:\n            The canonical identifier of the job to retrieve information about. This\n            field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;- `creator_user_name: str`&lt;/br&gt;- `run_as_user_name: str`&lt;/br&gt;- `settings: \"models.JobSettings\"`&lt;/br&gt;- `created_time: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/get`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/get\"  # noqa\n\n    responses = {\n        200: \"Job was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_list","title":"<code>jobs_list</code>  <code>async</code>","text":"<p>Retrieves a list of jobs.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>limit</code> <code>int</code> <p>The number of jobs to return. This value must be greater than 0 and less or equal to 25. The default value is 20.</p> <code>20</code> <code>offset</code> <code>int</code> <p>The offset of the first job to return, relative to the most recently created job.</p> <code>0</code> <code>name</code> <code>Optional[str]</code> <p>A filter on the list based on the exact (case insensitive) job name.</p> <code>None</code> <code>expand_tasks</code> <code>bool</code> <p>Whether to include task and cluster details in the response.</p> <code>False</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>jobs: List[\"models.Job\"]</code>- <code>has_more: bool</code></p> API Endpoint: <p><code>/2.1/jobs/list</code></p> API Responses: Response Description 200 List of jobs was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_list(\n    databricks_credentials: \"DatabricksCredentials\",\n    limit: int = 20,\n    offset: int = 0,\n    name: Optional[str] = None,\n    expand_tasks: bool = False,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieves a list of jobs.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        limit:\n            The number of jobs to return. This value must be greater than 0 and less\n            or equal to 25. The default value is 20.\n        offset:\n            The offset of the first job to return, relative to the most recently\n            created job.\n        name:\n            A filter on the list based on the exact (case insensitive) job name.\n        expand_tasks:\n            Whether to include task and cluster details in the response.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `jobs: List[\"models.Job\"]`&lt;/br&gt;- `has_more: bool`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/list`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | List of jobs was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/list\"  # noqa\n\n    responses = {\n        200: \"List of jobs was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"limit\": limit,\n        \"offset\": offset,\n        \"name\": name,\n        \"expand_tasks\": expand_tasks,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_reset","title":"<code>jobs_reset</code>  <code>async</code>","text":"<p>Overwrites all the settings for a specific job. Use the Update endpoint to update job settings partially.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to reset. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <code>new_settings</code> <code>JobSettings</code> <p>The new settings of the job. These settings completely replace the old settings.  Changes to the field <code>JobSettings.timeout_seconds</code> are applied to active runs. Changes to other fields are applied to future runs only. Key-values: - name:     An optional name for the job, e.g. <code>A multitask job</code>. - tags:     A map of tags associated with the job. These are forwarded     to the cluster as cluster tags for jobs clusters, and are     subject to the same limitations as cluster tags. A maximum     of 25 tags can be added to the job, e.g.     <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre> - tasks:     A list of task specifications to be executed by this job, e.g.     <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/order-data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\n                \"name\": \"John Doe\",\n                \"age\": \"35\",\n            },\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre> - job_clusters:     A list of job cluster specifications that can be shared and     reused by tasks of this job. Libraries cannot be declared in     a shared job cluster. You must declare dependent libraries     in task settings, e.g.     <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n    }\n]\n</code></pre> - email_notifications:     An optional set of email addresses that is notified when     runs of this job begin or complete as well as when this job     is deleted. The default behavior is to not send any emails. - webhook_notifications:     A collection of system notification IDs to notify when runs     of this job begin or complete. The default behavior is to     not send any system notifications. - timeout_seconds:     An optional timeout applied to each run of this job. The     default behavior is to have no timeout, e.g. <code>86400</code>. - schedule:     An optional periodic schedule for this job. The default     behavior is that the job only runs when triggered by     clicking \u201cRun Now\u201d in the Jobs UI or sending an API request     to <code>runNow</code>. - max_concurrent_runs:     An optional maximum allowed number of concurrent runs of the     job.  Set this value if you want to be able to execute     multiple runs of the same job concurrently. This is useful     for example if you trigger your job on a frequent schedule     and want to allow consecutive runs to overlap with each     other, or if you want to trigger multiple runs which differ     by their input parameters.  This setting affects only new     runs. For example, suppose the job\u2019s concurrency is 4 and     there are 4 concurrent active runs. Then setting the     concurrency to 3 won\u2019t kill any of the active runs. However,     from then on, new runs are skipped unless there are fewer     than 3 active runs.  This value cannot exceed 1000. Setting     this value to 0 causes all new runs to be skipped. The     default behavior is to allow only 1 concurrent run, e.g.     <code>10</code>. - git_source:     This functionality is in Public Preview.  An optional     specification for a remote repository containing the     notebooks used by this job's notebook tasks, e.g.     <pre><code>{\n    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n    \"git_branch\": \"main\",\n    \"git_provider\": \"gitHub\",\n}\n</code></pre> - format:     Used to tell what is the format of the job. This field is     ignored in Create/Update/Reset calls. When using the Jobs     API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g.     <code>MULTI_TASK</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/reset</code></p> API Responses: Response Description 200 Job was overwritten successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_reset(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    new_settings: \"models.JobSettings\" = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Overwrites all the settings for a specific job. Use the Update endpoint to\n    update job settings partially.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to reset. This field is required,\n            e.g. `11223344`.\n        new_settings:\n            The new settings of the job. These settings completely replace the old\n            settings.  Changes to the field\n            `JobSettings.timeout_seconds` are applied to active runs.\n            Changes to other fields are applied to future runs only. Key-values:\n            - name:\n                An optional name for the job, e.g. `A multitask job`.\n            - tags:\n                A map of tags associated with the job. These are forwarded\n                to the cluster as cluster tags for jobs clusters, and are\n                subject to the same limitations as cluster tags. A maximum\n                of 25 tags can be added to the job, e.g.\n                ```\n                {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n                ```\n            - tasks:\n                A list of task specifications to be executed by this job, e.g.\n                ```\n                [\n                    {\n                        \"task_key\": \"Sessionize\",\n                        \"description\": \"Extracts session data from events\",\n                        \"depends_on\": [],\n                        \"existing_cluster_id\": \"0923-164208-meows279\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.Sessionize\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Orders_Ingest\",\n                        \"description\": \"Ingests order data\",\n                        \"depends_on\": [],\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.OrdersIngest\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/order-data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Match\",\n                        \"description\": \"Matches orders with user sessions\",\n                        \"depends_on\": [\n                            {\"task_key\": \"Orders_Ingest\"},\n                            {\"task_key\": \"Sessionize\"},\n                        ],\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                        \"notebook_task\": {\n                            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                            \"source\": \"WORKSPACE\",\n                            \"base_parameters\": {\n                                \"name\": \"John Doe\",\n                                \"age\": \"35\",\n                            },\n                        },\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                ]\n                ```\n            - job_clusters:\n                A list of job cluster specifications that can be shared and\n                reused by tasks of this job. Libraries cannot be declared in\n                a shared job cluster. You must declare dependent libraries\n                in task settings, e.g.\n                ```\n                [\n                    {\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                    }\n                ]\n                ```\n            - email_notifications:\n                An optional set of email addresses that is notified when\n                runs of this job begin or complete as well as when this job\n                is deleted. The default behavior is to not send any emails.\n            - webhook_notifications:\n                A collection of system notification IDs to notify when runs\n                of this job begin or complete. The default behavior is to\n                not send any system notifications.\n            - timeout_seconds:\n                An optional timeout applied to each run of this job. The\n                default behavior is to have no timeout, e.g. `86400`.\n            - schedule:\n                An optional periodic schedule for this job. The default\n                behavior is that the job only runs when triggered by\n                clicking \u201cRun Now\u201d in the Jobs UI or sending an API request\n                to `runNow`.\n            - max_concurrent_runs:\n                An optional maximum allowed number of concurrent runs of the\n                job.  Set this value if you want to be able to execute\n                multiple runs of the same job concurrently. This is useful\n                for example if you trigger your job on a frequent schedule\n                and want to allow consecutive runs to overlap with each\n                other, or if you want to trigger multiple runs which differ\n                by their input parameters.  This setting affects only new\n                runs. For example, suppose the job\u2019s concurrency is 4 and\n                there are 4 concurrent active runs. Then setting the\n                concurrency to 3 won\u2019t kill any of the active runs. However,\n                from then on, new runs are skipped unless there are fewer\n                than 3 active runs.  This value cannot exceed 1000\\. Setting\n                this value to 0 causes all new runs to be skipped. The\n                default behavior is to allow only 1 concurrent run, e.g.\n                `10`.\n            - git_source:\n                This functionality is in Public Preview.  An optional\n                specification for a remote repository containing the\n                notebooks used by this job's notebook tasks, e.g.\n                ```\n                {\n                    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                    \"git_branch\": \"main\",\n                    \"git_provider\": \"gitHub\",\n                }\n                ```\n            - format:\n                Used to tell what is the format of the job. This field is\n                ignored in Create/Update/Reset calls. When using the Jobs\n                API 2.1 this value is always set to `'MULTI_TASK'`, e.g.\n                `MULTI_TASK`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/reset`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was overwritten successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/reset\"  # noqa\n\n    responses = {\n        200: \"Job was overwritten successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"new_settings\": new_settings,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_run_now","title":"<code>jobs_run_now</code>  <code>async</code>","text":"<p>Run a job and return the <code>run_id</code> of the triggered run.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The ID of the job to be executed, e.g. <code>11223344</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token.  This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example <code>'jar_params': ['john doe', '35']</code>. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon <code>run-now</code>, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example <code>{'jar_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs, e.g. <pre><code>[\"john\", \"doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example <code>'notebook_params': {'name': 'john doe', 'age': '35'}</code>. The map is passed to the notebook and is accessible through the dbutils.widgets.get function.  If not specified upon <code>run-now</code>, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params.  Use Task parameter variables to set parameters containing information about job runs.  The JSON representation of this field (for example <code>{'notebook_params':{'name':'john doe','age':'35'}}</code>) cannot exceed 10,000 bytes, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example <code>'python_params': ['john doe', '35']</code>. The parameters are passed to Python file as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"john doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example <code>'spark_submit_params': ['--class', 'org.apache.spark.examples.SparkPi']</code>. The parameters are passed to spark-submit script as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"--class\", \"org.apache.spark.examples.SparkPi\"]\n</code></pre></p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example <code>'python_named_params': {'name': 'task', 'data': 'dbfs:/path/to/data.json'}</code>, e.g. <pre><code>{\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n</code></pre></p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example <code>'sql_params': {'name': 'john doe', 'age': '35'}</code>. The SQL alert task does not support custom parameters, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example <code>'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']</code>, e.g. <pre><code>[\"dbt deps\", \"dbt seed\", \"dbt run\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>run_id: int</code>- <code>number_in_job: int</code></p> API Endpoint: <p><code>/2.1/jobs/run-now</code></p> API Responses: Response Description 200 Run was started successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_run_now(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    jar_params: Optional[List[str]] = None,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Run a job and return the `run_id` of the triggered run.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The ID of the job to be executed, e.g. `11223344`.\n        idempotency_token:\n            An optional token to guarantee the idempotency of job run requests. If a\n            run with the provided token already exists, the request does\n            not create a new run but returns the ID of the existing run\n            instead. If a run with the provided token is deleted, an\n            error is returned.  If you specify the idempotency token,\n            upon failure you can retry until the request succeeds.\n            Databricks guarantees that exactly one run is launched with\n            that idempotency token.  This token must have at most 64\n            characters.  For more information, see [How to ensure\n            idempotency for jobs](https://kb.databricks.com/jobs/jobs-\n            idempotency.html), e.g.\n            `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example\n            `'jar_params': ['john doe', '35']`. The parameters are used\n            to invoke the main function of the main class specified in\n            the Spark JAR task. If not specified upon `run-now`, it\n            defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of\n            this field (for example `{'jar_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs, e.g.\n            ```\n            [\"john\", \"doe\", \"35\"]\n            ```\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            `'notebook_params': {'name': 'john doe', 'age': '35'}`. The\n            map is passed to the notebook and is accessible through the\n            [dbutils.widgets.get](https://docs.databricks.com/dev-\n            tools/databricks-utils.html\n            dbutils-widgets) function.  If not specified upon `run-now`,\n            the triggered run uses the job\u2019s base parameters.\n            notebook_params cannot be specified in conjunction with\n            jar_params.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  The JSON representation of this\n            field (for example `{'notebook_params':{'name':'john\n            doe','age':'35'}}`) cannot exceed 10,000 bytes, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        python_params:\n            A list of parameters for jobs with Python tasks, for example\n            `'python_params': ['john doe', '35']`. The parameters are\n            passed to Python file as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"john doe\", \"35\"]\n            ```\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            `'spark_submit_params': ['--class',\n            'org.apache.spark.examples.SparkPi']`. The parameters are\n            passed to spark-submit script as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"--class\", \"org.apache.spark.examples.SparkPi\"]\n            ```\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            `'python_named_params': {'name': 'task', 'data':\n            'dbfs:/path/to/data.json'}`, e.g.\n            ```\n            {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n            ```\n        pipeline_params:\n\n        sql_params:\n            A map from keys to values for SQL tasks, for example `'sql_params':\n            {'name': 'john doe', 'age': '35'}`. The SQL alert task does\n            not support custom parameters, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task, for example\n            `'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']`, e.g.\n            ```\n            [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n            ```\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `run_id: int`&lt;/br&gt;- `number_in_job: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/run-now`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was started successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/run-now\"  # noqa\n\n    responses = {\n        200: \"Run was started successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"idempotency_token\": idempotency_token,\n        \"jar_params\": jar_params,\n        \"notebook_params\": notebook_params,\n        \"python_params\": python_params,\n        \"spark_submit_params\": spark_submit_params,\n        \"python_named_params\": python_named_params,\n        \"pipeline_params\": pipeline_params,\n        \"sql_params\": sql_params,\n        \"dbt_commands\": dbt_commands,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_cancel","title":"<code>jobs_runs_cancel</code>  <code>async</code>","text":"<p>Cancels a job run. The run is canceled asynchronously, so it may still be running when this request completes.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>This field is required, e.g. <code>455644833</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/cancel</code></p> API Responses: Response Description 200 Run was cancelled successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_cancel(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Cancels a job run. The run is canceled asynchronously, so it may still be\n    running when this request completes.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            This field is required, e.g. `455644833`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/cancel`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was cancelled successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/cancel\"  # noqa\n\n    responses = {\n        200: \"Run was cancelled successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_cancel_all","title":"<code>jobs_runs_cancel_all</code>  <code>async</code>","text":"<p>Cancels all active runs of a job. The runs are canceled asynchronously, so it doesn't prevent new runs from being started.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to cancel all runs of. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/cancel-all</code></p> API Responses: Response Description 200 All runs were cancelled successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_cancel_all(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Cancels all active runs of a job. The runs are canceled asynchronously, so it\n    doesn't prevent new runs from being started.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to cancel all runs of. This field is\n            required, e.g. `11223344`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/cancel-all`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | All runs were cancelled successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/cancel-all\"  # noqa\n\n    responses = {\n        200: \"All runs were cancelled successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_delete","title":"<code>jobs_runs_delete</code>  <code>async</code>","text":"<p>Deletes a non-active run. Returns an error if the run is active.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>The canonical identifier of the run for which to retrieve the metadata, e.g. <code>455644833</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/runs/delete</code></p> API Responses: Response Description 200 Run was deleted successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_delete(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deletes a non-active run. Returns an error if the run is active.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            The canonical identifier of the run for which to retrieve the metadata,\n            e.g. `455644833`.\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/delete`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was deleted successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/delete\"  # noqa\n\n    responses = {\n        200: \"Run was deleted successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_export","title":"<code>jobs_runs_export</code>  <code>async</code>","text":"<p>Export and retrieve the job run task.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier for the run. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>views_to_export</code> <code>Optional[ViewsToExport]</code> <p>Which views to export (CODE, DASHBOARDS, or ALL). Defaults to CODE.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>views: List[\"models.ViewItem\"]</code></p> API Endpoint: <p><code>/2.0/jobs/runs/export</code></p> API Responses: Response Description 200 Run was exported successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_export(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n    views_to_export: Optional[\"models.ViewsToExport\"] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Export and retrieve the job run task.\n\n    Args:\n        run_id:\n            The canonical identifier for the run. This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        views_to_export:\n            Which views to export (CODE, DASHBOARDS, or ALL). Defaults to CODE.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `views: List[\"models.ViewItem\"]`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.0/jobs/runs/export`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was exported successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.0/jobs/runs/export\"  # noqa\n\n    responses = {\n        200: \"Run was exported successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n        \"views_to_export\": views_to_export,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_get","title":"<code>jobs_runs_get</code>  <code>async</code>","text":"<p>Retrieve the metadata of a run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier of the run for which to retrieve the metadata. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>include_history</code> <code>Optional[bool]</code> <p>Whether to include the repair history in the response.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>job_id: int</code>- <code>run_id: int</code>- <code>number_in_job: int</code>- <code>creator_user_name: str</code>- <code>original_attempt_run_id: int</code>- <code>state: \"models.RunState\"</code>- <code>schedule: \"models.CronSchedule\"</code>- <code>tasks: List[\"models.RunTask\"]</code>- <code>job_clusters: List[\"models.JobCluster\"]</code>- <code>cluster_spec: \"models.ClusterSpec\"</code>- <code>cluster_instance: \"models.ClusterInstance\"</code>- <code>git_source: \"models.GitSource\"</code>- <code>overriding_parameters: \"models.RunParameters\"</code>- <code>start_time: int</code>- <code>setup_duration: int</code>- <code>execution_duration: int</code>- <code>cleanup_duration: int</code>- <code>end_time: int</code>- <code>trigger: \"models.TriggerType\"</code>- <code>run_name: str</code>- <code>run_page_url: str</code>- <code>run_type: \"models.RunType\"</code>- <code>attempt_number: int</code>- <code>repair_history: List[\"models.RepairHistoryItem\"]</code></p> API Endpoint: <p><code>/2.1/jobs/runs/get</code></p> API Responses: Response Description 200 Run was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_get(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n    include_history: Optional[bool] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieve the metadata of a run.\n\n    Args:\n        run_id:\n            The canonical identifier of the run for which to retrieve the metadata.\n            This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        include_history:\n            Whether to include the repair history in the response.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `job_id: int`&lt;/br&gt;- `run_id: int`&lt;/br&gt;- `number_in_job: int`&lt;/br&gt;- `creator_user_name: str`&lt;/br&gt;- `original_attempt_run_id: int`&lt;/br&gt;- `state: \"models.RunState\"`&lt;/br&gt;- `schedule: \"models.CronSchedule\"`&lt;/br&gt;- `tasks: List[\"models.RunTask\"]`&lt;/br&gt;- `job_clusters: List[\"models.JobCluster\"]`&lt;/br&gt;- `cluster_spec: \"models.ClusterSpec\"`&lt;/br&gt;- `cluster_instance: \"models.ClusterInstance\"`&lt;/br&gt;- `git_source: \"models.GitSource\"`&lt;/br&gt;- `overriding_parameters: \"models.RunParameters\"`&lt;/br&gt;- `start_time: int`&lt;/br&gt;- `setup_duration: int`&lt;/br&gt;- `execution_duration: int`&lt;/br&gt;- `cleanup_duration: int`&lt;/br&gt;- `end_time: int`&lt;/br&gt;- `trigger: \"models.TriggerType\"`&lt;/br&gt;- `run_name: str`&lt;/br&gt;- `run_page_url: str`&lt;/br&gt;- `run_type: \"models.RunType\"`&lt;/br&gt;- `attempt_number: int`&lt;/br&gt;- `repair_history: List[\"models.RepairHistoryItem\"]`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/get`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/get\"  # noqa\n\n    responses = {\n        200: \"Run was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n        \"include_history\": include_history,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_get_output","title":"<code>jobs_runs_get_output</code>  <code>async</code>","text":"<p>Retrieve the output and metadata of a single task run. When a notebook task returns a value through the dbutils.notebook.exit() call, you can use this endpoint to retrieve that value. Databricks restricts this API to return the first 5 MB of the output. To return a larger result, you can store job results in a cloud storage service. This endpoint validates that the run_id parameter is valid and returns an HTTP status code 400 if the run_id parameter is invalid. Runs are automatically removed after 60 days. If you to want to reference them beyond 60 days, you must save old run results before they expire. To export using the UI, see Export job run results. To export using the Jobs API, see Runs export.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The canonical identifier for the run. This field is required.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>notebook_output: \"models.NotebookOutput\"</code>- <code>sql_output: \"models.SqlOutput\"</code>- <code>dbt_output: \"models.DbtOutput\"</code>- <code>logs: str</code>- <code>logs_truncated: bool</code>- <code>error: str</code>- <code>error_trace: str</code>- <code>metadata: \"models.Run\"</code></p> API Endpoint: <p><code>/2.1/jobs/runs/get-output</code></p> API Responses: Response Description 200 Run output was retrieved successfully. 400 A job run with multiple tasks was provided. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_get_output(\n    run_id: int,\n    databricks_credentials: \"DatabricksCredentials\",\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Retrieve the output and metadata of a single task run. When a notebook task\n    returns a value through the dbutils.notebook.exit() call, you can use this\n    endpoint to retrieve that value. Databricks restricts this API to return the\n    first 5 MB of the output. To return a larger result, you can store job\n    results in a cloud storage service. This endpoint validates that the run_id\n    parameter is valid and returns an HTTP status code 400 if the run_id\n    parameter is invalid. Runs are automatically removed after 60 days. If you\n    to want to reference them beyond 60 days, you must save old run results\n    before they expire. To export using the UI, see Export job run results. To\n    export using the Jobs API, see Runs export.\n\n    Args:\n        run_id:\n            The canonical identifier for the run. This field is required.\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `notebook_output: \"models.NotebookOutput\"`&lt;/br&gt;- `sql_output: \"models.SqlOutput\"`&lt;/br&gt;- `dbt_output: \"models.DbtOutput\"`&lt;/br&gt;- `logs: str`&lt;/br&gt;- `logs_truncated: bool`&lt;/br&gt;- `error: str`&lt;/br&gt;- `error_trace: str`&lt;/br&gt;- `metadata: \"models.Run\"`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/get-output`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run output was retrieved successfully. |\n    | 400 | A job run with multiple tasks was provided. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/get-output\"  # noqa\n\n    responses = {\n        200: \"Run output was retrieved successfully.\",  # noqa\n        400: \"A job run with multiple tasks was provided.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"run_id\": run_id,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_list","title":"<code>jobs_runs_list</code>  <code>async</code>","text":"<p>List runs in descending order by start time.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>active_only</code> <code>bool</code> <p>If active_only is <code>true</code>, only active runs are included in the results; otherwise, lists both active and completed runs. An active run is a run in the <code>PENDING</code>, <code>RUNNING</code>, or <code>TERMINATING</code>. This field cannot be <code>true</code> when completed_only is <code>true</code>.</p> <code>False</code> <code>completed_only</code> <code>bool</code> <p>If completed_only is <code>true</code>, only completed runs are included in the results; otherwise, lists both active and completed runs. This field cannot be <code>true</code> when active_only is <code>true</code>.</p> <code>False</code> <code>job_id</code> <code>Optional[int]</code> <p>The job for which to list runs. If omitted, the Jobs service lists runs from all jobs.</p> <code>None</code> <code>offset</code> <code>int</code> <p>The offset of the first run to return, relative to the most recent run.</p> <code>0</code> <code>limit</code> <code>int</code> <p>The number of runs to return. This value must be greater than 0 and less than 25. The default value is 25. If a request specifies a limit of 0, the service instead uses the maximum limit.</p> <code>25</code> <code>run_type</code> <code>Optional[str]</code> <p>The type of runs to return. For a description of run types, see Run.</p> <code>None</code> <code>expand_tasks</code> <code>bool</code> <p>Whether to include task and cluster details in the response.</p> <code>False</code> <code>start_time_from</code> <code>Optional[int]</code> <p>Show runs that started at or after this value. The value must be a UTC timestamp in milliseconds. Can be combined with start_time_to to filter by a time range.</p> <code>None</code> <code>start_time_to</code> <code>Optional[int]</code> <p>Show runs that started at or before this value. The value must be a UTC timestamp in milliseconds. Can be combined with start_time_from to filter by a time range.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>runs: List[\"models.Run\"]</code>- <code>has_more: bool</code></p> API Endpoint: <p><code>/2.1/jobs/runs/list</code></p> API Responses: Response Description 200 List of runs was retrieved successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_list(\n    databricks_credentials: \"DatabricksCredentials\",\n    active_only: bool = False,\n    completed_only: bool = False,\n    job_id: Optional[int] = None,\n    offset: int = 0,\n    limit: int = 25,\n    run_type: Optional[str] = None,\n    expand_tasks: bool = False,\n    start_time_from: Optional[int] = None,\n    start_time_to: Optional[int] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List runs in descending order by start time.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        active_only:\n            If active_only is `true`, only active runs are included in the results;\n            otherwise, lists both active and completed runs. An active\n            run is a run in the `PENDING`, `RUNNING`, or `TERMINATING`.\n            This field cannot be `true` when completed_only is `true`.\n        completed_only:\n            If completed_only is `true`, only completed runs are included in the\n            results; otherwise, lists both active and completed runs.\n            This field cannot be `true` when active_only is `true`.\n        job_id:\n            The job for which to list runs. If omitted, the Jobs service lists runs\n            from all jobs.\n        offset:\n            The offset of the first run to return, relative to the most recent run.\n        limit:\n            The number of runs to return. This value must be greater than 0 and less\n            than 25\\. The default value is 25\\. If a request specifies a\n            limit of 0, the service instead uses the maximum limit.\n        run_type:\n            The type of runs to return. For a description of run types, see\n            [Run](https://docs.databricks.com/dev-\n            tools/api/latest/jobs.html\n            operation/JobsRunsGet).\n        expand_tasks:\n            Whether to include task and cluster details in the response.\n        start_time_from:\n            Show runs that started _at or after_ this value. The value must be a UTC\n            timestamp in milliseconds. Can be combined with\n            _start_time_to_ to filter by a time range.\n        start_time_to:\n            Show runs that started _at or before_ this value. The value must be a\n            UTC timestamp in milliseconds. Can be combined with\n            _start_time_from_ to filter by a time range.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `runs: List[\"models.Run\"]`&lt;/br&gt;- `has_more: bool`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/list`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | List of runs was retrieved successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/list\"  # noqa\n\n    responses = {\n        200: \"List of runs was retrieved successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    params = {\n        \"active_only\": active_only,\n        \"completed_only\": completed_only,\n        \"job_id\": job_id,\n        \"offset\": offset,\n        \"limit\": limit,\n        \"run_type\": run_type,\n        \"expand_tasks\": expand_tasks,\n        \"start_time_from\": start_time_from,\n        \"start_time_to\": start_time_to,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.GET,\n        params=params,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_repair","title":"<code>jobs_runs_repair</code>  <code>async</code>","text":"<p>Re-run one or more tasks. Tasks are re-run as part of the original job run, use the current job and task settings, and can be viewed in the history for the original job run.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>run_id</code> <code>Optional[int]</code> <p>The job run ID of the run to repair. The run must not be in progress, e.g. <code>455644833</code>.</p> <code>None</code> <code>rerun_tasks</code> <code>Optional[List[str]]</code> <p>The task keys of the task runs to repair, e.g. <pre><code>[\"task0\", \"task1\"]\n</code></pre></p> <code>None</code> <code>latest_repair_id</code> <code>Optional[int]</code> <p>The ID of the latest repair. This parameter is not required when repairing a run for the first time, but must be provided on subsequent requests to repair the same run, e.g. <code>734650698524280</code>.</p> <code>None</code> <code>rerun_all_failed_tasks</code> <code>bool</code> <p>If true, repair all failed tasks. Only one of rerun_tasks or rerun_all_failed_tasks can be used.</p> <code>False</code> <code>jar_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Spark JAR tasks, for example <code>'jar_params': ['john doe', '35']</code>. The parameters are used to invoke the main function of the main class specified in the Spark JAR task. If not specified upon <code>run-now</code>, it defaults to an empty list. jar_params cannot be specified in conjunction with notebook_params. The JSON representation of this field (for example <code>{'jar_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs, e.g. <pre><code>[\"john\", \"doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>notebook_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with notebook task, for example <code>'notebook_params': {'name': 'john doe', 'age': '35'}</code>. The map is passed to the notebook and is accessible through the dbutils.widgets.get function.  If not specified upon <code>run-now</code>, the triggered run uses the job\u2019s base parameters. notebook_params cannot be specified in conjunction with jar_params.  Use Task parameter variables to set parameters containing information about job runs.  The JSON representation of this field (for example <code>{'notebook_params':{'name':'john doe','age':'35'}}</code>) cannot exceed 10,000 bytes, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>python_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with Python tasks, for example <code>'python_params': ['john doe', '35']</code>. The parameters are passed to Python file as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"john doe\", \"35\"]\n</code></pre></p> <code>None</code> <code>spark_submit_params</code> <code>Optional[List[str]]</code> <p>A list of parameters for jobs with spark submit task, for example <code>'spark_submit_params': ['--class', 'org.apache.spark.examples.SparkPi']</code>. The parameters are passed to spark-submit script as command-line parameters. If specified upon <code>run-now</code>, it would overwrite the parameters specified in job setting. The JSON representation of this field (for example <code>{'python_params':['john doe','35']}</code>) cannot exceed 10,000 bytes.  Use Task parameter variables to set parameters containing information about job runs.  Important  These parameters accept only Latin characters (ASCII character set). Using non-ASCII characters returns an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis, e.g. <pre><code>[\"--class\", \"org.apache.spark.examples.SparkPi\"]\n</code></pre></p> <code>None</code> <code>python_named_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for jobs with Python wheel task, for example <code>'python_named_params': {'name': 'task', 'data': 'dbfs:/path/to/data.json'}</code>, e.g. <pre><code>{\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n</code></pre></p> <code>None</code> <code>pipeline_params</code> <code>Optional[str]</code> <code>None</code> <code>sql_params</code> <code>Optional[Dict]</code> <p>A map from keys to values for SQL tasks, for example <code>'sql_params': {'name': 'john doe', 'age': '35'}</code>. The SQL alert task does not support custom parameters, e.g. <pre><code>{\"name\": \"john doe\", \"age\": \"35\"}\n</code></pre></p> <code>None</code> <code>dbt_commands</code> <code>Optional[List]</code> <p>An array of commands to execute for jobs with the dbt task, for example <code>'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']</code>, e.g. <pre><code>[\"dbt deps\", \"dbt seed\", \"dbt run\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>repair_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/runs/repair</code></p> API Responses: Response Description 200 Run repair was initiated. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_repair(\n    databricks_credentials: \"DatabricksCredentials\",\n    run_id: Optional[int] = None,\n    rerun_tasks: Optional[List[str]] = None,\n    latest_repair_id: Optional[int] = None,\n    rerun_all_failed_tasks: bool = False,\n    jar_params: Optional[List[str]] = None,\n    notebook_params: Optional[Dict] = None,\n    python_params: Optional[List[str]] = None,\n    spark_submit_params: Optional[List[str]] = None,\n    python_named_params: Optional[Dict] = None,\n    pipeline_params: Optional[str] = None,\n    sql_params: Optional[Dict] = None,\n    dbt_commands: Optional[List] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Re-run one or more tasks. Tasks are re-run as part of the original job run, use\n    the current job and task settings, and can be viewed in the history for the\n    original job run.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        run_id:\n            The job run ID of the run to repair. The run must not be in progress,\n            e.g. `455644833`.\n        rerun_tasks:\n            The task keys of the task runs to repair, e.g.\n            ```\n            [\"task0\", \"task1\"]\n            ```\n        latest_repair_id:\n            The ID of the latest repair. This parameter is not required when\n            repairing a run for the first time, but must be provided on\n            subsequent requests to repair the same run, e.g.\n            `734650698524280`.\n        rerun_all_failed_tasks:\n            If true, repair all failed tasks. Only one of rerun_tasks or\n            rerun_all_failed_tasks can be used.\n        jar_params:\n            A list of parameters for jobs with Spark JAR tasks, for example\n            `'jar_params': ['john doe', '35']`. The parameters are used\n            to invoke the main function of the main class specified in\n            the Spark JAR task. If not specified upon `run-now`, it\n            defaults to an empty list. jar_params cannot be specified in\n            conjunction with notebook_params. The JSON representation of\n            this field (for example `{'jar_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs, e.g.\n            ```\n            [\"john\", \"doe\", \"35\"]\n            ```\n        notebook_params:\n            A map from keys to values for jobs with notebook task, for example\n            `'notebook_params': {'name': 'john doe', 'age': '35'}`. The\n            map is passed to the notebook and is accessible through the\n            [dbutils.widgets.get](https://docs.databricks.com/dev-\n            tools/databricks-utils.html\n            dbutils-widgets) function.  If not specified upon `run-now`,\n            the triggered run uses the job\u2019s base parameters.\n            notebook_params cannot be specified in conjunction with\n            jar_params.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  The JSON representation of this\n            field (for example `{'notebook_params':{'name':'john\n            doe','age':'35'}}`) cannot exceed 10,000 bytes, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        python_params:\n            A list of parameters for jobs with Python tasks, for example\n            `'python_params': ['john doe', '35']`. The parameters are\n            passed to Python file as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"john doe\", \"35\"]\n            ```\n        spark_submit_params:\n            A list of parameters for jobs with spark submit task, for example\n            `'spark_submit_params': ['--class',\n            'org.apache.spark.examples.SparkPi']`. The parameters are\n            passed to spark-submit script as command-line parameters. If\n            specified upon `run-now`, it would overwrite the parameters\n            specified in job setting. The JSON representation of this\n            field (for example `{'python_params':['john doe','35']}`)\n            cannot exceed 10,000 bytes.  Use [Task parameter\n            variables](https://docs.databricks.com/jobs.html\n            parameter-variables) to set parameters containing\n            information about job runs.  Important  These parameters\n            accept only Latin characters (ASCII character set). Using\n            non-ASCII characters returns an error. Examples of invalid,\n            non-ASCII characters are Chinese, Japanese kanjis, and\n            emojis, e.g.\n            ```\n            [\"--class\", \"org.apache.spark.examples.SparkPi\"]\n            ```\n        python_named_params:\n            A map from keys to values for jobs with Python wheel task, for example\n            `'python_named_params': {'name': 'task', 'data':\n            'dbfs:/path/to/data.json'}`, e.g.\n            ```\n            {\"name\": \"task\", \"data\": \"dbfs:/path/to/data.json\"}\n            ```\n        pipeline_params:\n\n        sql_params:\n            A map from keys to values for SQL tasks, for example `'sql_params':\n            {'name': 'john doe', 'age': '35'}`. The SQL alert task does\n            not support custom parameters, e.g.\n            ```\n            {\"name\": \"john doe\", \"age\": \"35\"}\n            ```\n        dbt_commands:\n            An array of commands to execute for jobs with the dbt task, for example\n            `'dbt_commands': ['dbt deps', 'dbt seed', 'dbt run']`, e.g.\n            ```\n            [\"dbt deps\", \"dbt seed\", \"dbt run\"]\n            ```\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `repair_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/repair`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run repair was initiated. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/repair\"  # noqa\n\n    responses = {\n        200: \"Run repair was initiated.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"run_id\": run_id,\n        \"rerun_tasks\": rerun_tasks,\n        \"latest_repair_id\": latest_repair_id,\n        \"rerun_all_failed_tasks\": rerun_all_failed_tasks,\n        \"jar_params\": jar_params,\n        \"notebook_params\": notebook_params,\n        \"python_params\": python_params,\n        \"spark_submit_params\": spark_submit_params,\n        \"python_named_params\": python_named_params,\n        \"pipeline_params\": pipeline_params,\n        \"sql_params\": sql_params,\n        \"dbt_commands\": dbt_commands,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_runs_submit","title":"<code>jobs_runs_submit</code>  <code>async</code>","text":"<p>Submit a one-time run. This endpoint allows you to submit a workload directly without creating a job. Use the <code>jobs/runs/get</code> API to check the run state after the job is submitted.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>tasks</code> <code>Optional[List[RunSubmitTaskSettings]]</code> <p>, e.g. <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n        },\n        \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n        \"timeout_seconds\": 86400,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n        },\n        \"timeout_seconds\": 86400,\n    },\n]\n</code></pre></p> <code>None</code> <code>run_name</code> <code>Optional[str]</code> <p>An optional name for the run. The default value is <code>Untitled</code>, e.g. <code>A multitask job run</code>.</p> <code>None</code> <code>webhook_notifications</code> <code>WebhookNotifications</code> <p>A collection of system notification IDs to notify when runs of this job begin or complete. The default behavior is to not send any system notifications. Key-values: - on_start:     An optional list of notification IDs to call when the run     starts. A maximum of 3 destinations can be specified for the     <code>on_start</code> property, e.g.     <pre><code>[\n    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n]\n</code></pre> - on_success:     An optional list of notification IDs to call when the run     completes successfully. A maximum of 3 destinations can be     specified for the <code>on_success</code> property, e.g.     <pre><code>[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n</code></pre> - on_failure:     An optional list of notification IDs to call when the run     fails. A maximum of 3 destinations can be specified for the     <code>on_failure</code> property, e.g.     <pre><code>[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n</code></pre></p> <code>None</code> <code>git_source</code> <code>GitSource</code> <p>This functionality is in Public Preview.  An optional specification for a remote repository containing the notebooks used by this job's notebook tasks, e.g. <code>{     \"git_url\": \"https://github.com/databricks/databricks-cli\",     \"git_branch\": \"main\",     \"git_provider\": \"gitHub\", }</code> Key-values: - git_url:     URL of the repository to be cloned by this job. The maximum     length is 300 characters, e.g.     <code>https://github.com/databricks/databricks-cli</code>. - git_provider:     Unique identifier of the service used to host the Git     repository. The value is case insensitive, e.g. <code>github</code>. - git_branch:     Name of the branch to be checked out and used by this job.     This field cannot be specified in conjunction with git_tag     or git_commit. The maximum length is 255 characters, e.g.     <code>main</code>. - git_tag:     Name of the tag to be checked out and used by this job. This     field cannot be specified in conjunction with git_branch or     git_commit. The maximum length is 255 characters, e.g.     <code>release-1.0.0</code>. - git_commit:     Commit to be checked out and used by this job. This field     cannot be specified in conjunction with git_branch or     git_tag. The maximum length is 64 characters, e.g.     <code>e0056d01</code>. - git_snapshot:     Read-only state of the remote repository at the time the job was run.                 This field is only included on job runs.</p> <code>None</code> <code>timeout_seconds</code> <code>Optional[int]</code> <p>An optional timeout applied to each run of this job. The default behavior is to have no timeout, e.g. <code>86400</code>.</p> <code>None</code> <code>idempotency_token</code> <code>Optional[str]</code> <p>An optional token that can be used to guarantee the idempotency of job run requests. If a run with the provided token already exists, the request does not create a new run but returns the ID of the existing run instead. If a run with the provided token is deleted, an error is returned.  If you specify the idempotency token, upon failure you can retry until the request succeeds. Databricks guarantees that exactly one run is launched with that idempotency token. This token must have at most 64 characters.  For more information, see How to ensure idempotency for jobs, e.g. <code>8f018174-4792-40d5-bcbc-3e6a527352c8</code>.</p> <code>None</code> <code>access_control_list</code> <code>Optional[List[AccessControlRequest]]</code> <p>List of permissions to set on the job.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, a dict of the response. - <code>run_id: int</code></p> API Endpoint: <p><code>/2.1/jobs/runs/submit</code></p> API Responses: Response Description 200 Run was created and started successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_runs_submit(\n    databricks_credentials: \"DatabricksCredentials\",\n    tasks: Optional[List[\"models.RunSubmitTaskSettings\"]] = None,\n    run_name: Optional[str] = None,\n    webhook_notifications: \"models.WebhookNotifications\" = None,\n    git_source: \"models.GitSource\" = None,\n    timeout_seconds: Optional[int] = None,\n    idempotency_token: Optional[str] = None,\n    access_control_list: Optional[List[\"models.AccessControlRequest\"]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Submit a one-time run. This endpoint allows you to submit a workload directly\n    without creating a job. Use the `jobs/runs/get` API to check the run state\n    after the job is submitted.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        tasks:\n            , e.g.\n            ```\n            [\n                {\n                    \"task_key\": \"Sessionize\",\n                    \"description\": \"Extracts session data from events\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.Sessionize\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Orders_Ingest\",\n                    \"description\": \"Ingests order data\",\n                    \"depends_on\": [],\n                    \"existing_cluster_id\": \"0923-164208-meows279\",\n                    \"spark_jar_task\": {\n                        \"main_class_name\": \"com.databricks.OrdersIngest\",\n                        \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                    },\n                    \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                    \"timeout_seconds\": 86400,\n                },\n                {\n                    \"task_key\": \"Match\",\n                    \"description\": \"Matches orders with user sessions\",\n                    \"depends_on\": [\n                        {\"task_key\": \"Orders_Ingest\"},\n                        {\"task_key\": \"Sessionize\"},\n                    ],\n                    \"new_cluster\": {\n                        \"spark_version\": \"7.3.x-scala2.12\",\n                        \"node_type_id\": \"i3.xlarge\",\n                        \"spark_conf\": {\"spark.speculation\": True},\n                        \"aws_attributes\": {\n                            \"availability\": \"SPOT\",\n                            \"zone_id\": \"us-west-2a\",\n                        },\n                        \"autoscale\": {\"min_workers\": 2, \"max_workers\": 16},\n                    },\n                    \"notebook_task\": {\n                        \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                        \"source\": \"WORKSPACE\",\n                        \"base_parameters\": {\"name\": \"John Doe\", \"age\": \"35\"},\n                    },\n                    \"timeout_seconds\": 86400,\n                },\n            ]\n            ```\n        run_name:\n            An optional name for the run. The default value is `Untitled`, e.g. `A\n            multitask job run`.\n        webhook_notifications:\n            A collection of system notification IDs to notify when runs of this job\n            begin or complete. The default behavior is to not send any\n            system notifications. Key-values:\n            - on_start:\n                An optional list of notification IDs to call when the run\n                starts. A maximum of 3 destinations can be specified for the\n                `on_start` property, e.g.\n                ```\n                [\n                    {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n                    {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n                ]\n                ```\n            - on_success:\n                An optional list of notification IDs to call when the run\n                completes successfully. A maximum of 3 destinations can be\n                specified for the `on_success` property, e.g.\n                ```\n                [{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}]\n                ```\n            - on_failure:\n                An optional list of notification IDs to call when the run\n                fails. A maximum of 3 destinations can be specified for the\n                `on_failure` property, e.g.\n                ```\n                [{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}]\n                ```\n        git_source:\n            This functionality is in Public Preview.  An optional specification for\n            a remote repository containing the notebooks used by this\n            job's notebook tasks, e.g.\n            ```\n            {\n                \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                \"git_branch\": \"main\",\n                \"git_provider\": \"gitHub\",\n            }\n            ``` Key-values:\n            - git_url:\n                URL of the repository to be cloned by this job. The maximum\n                length is 300 characters, e.g.\n                `https://github.com/databricks/databricks-cli`.\n            - git_provider:\n                Unique identifier of the service used to host the Git\n                repository. The value is case insensitive, e.g. `github`.\n            - git_branch:\n                Name of the branch to be checked out and used by this job.\n                This field cannot be specified in conjunction with git_tag\n                or git_commit. The maximum length is 255 characters, e.g.\n                `main`.\n            - git_tag:\n                Name of the tag to be checked out and used by this job. This\n                field cannot be specified in conjunction with git_branch or\n                git_commit. The maximum length is 255 characters, e.g.\n                `release-1.0.0`.\n            - git_commit:\n                Commit to be checked out and used by this job. This field\n                cannot be specified in conjunction with git_branch or\n                git_tag. The maximum length is 64 characters, e.g.\n                `e0056d01`.\n            - git_snapshot:\n                Read-only state of the remote repository at the time the job was run.\n                            This field is only included on job runs.\n        timeout_seconds:\n            An optional timeout applied to each run of this job. The default\n            behavior is to have no timeout, e.g. `86400`.\n        idempotency_token:\n            An optional token that can be used to guarantee the idempotency of job\n            run requests. If a run with the provided token already\n            exists, the request does not create a new run but returns\n            the ID of the existing run instead. If a run with the\n            provided token is deleted, an error is returned.  If you\n            specify the idempotency token, upon failure you can retry\n            until the request succeeds. Databricks guarantees that\n            exactly one run is launched with that idempotency token.\n            This token must have at most 64 characters.  For more\n            information, see [How to ensure idempotency for\n            jobs](https://kb.databricks.com/jobs/jobs-idempotency.html),\n            e.g. `8f018174-4792-40d5-bcbc-3e6a527352c8`.\n        access_control_list:\n            List of permissions to set on the job.\n\n    Returns:\n        Upon success, a dict of the response. &lt;/br&gt;- `run_id: int`&lt;/br&gt;\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/runs/submit`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Run was created and started successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/runs/submit\"  # noqa\n\n    responses = {\n        200: \"Run was created and started successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"tasks\": tasks,\n        \"run_name\": run_name,\n        \"webhook_notifications\": webhook_notifications,\n        \"git_source\": git_source,\n        \"timeout_seconds\": timeout_seconds,\n        \"idempotency_token\": idempotency_token,\n        \"access_control_list\": access_control_list,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/jobs/#prefect_databricks.jobs.jobs_update","title":"<code>jobs_update</code>  <code>async</code>","text":"<p>Add, update, or remove specific settings of an existing job. Use the Reset endpoint to overwrite all job settings.</p> <p>Parameters:</p> Name Type Description Default <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>job_id</code> <code>Optional[int]</code> <p>The canonical identifier of the job to update. This field is required, e.g. <code>11223344</code>.</p> <code>None</code> <code>new_settings</code> <code>JobSettings</code> <p>The new settings for the job. Any top-level fields specified in <code>new_settings</code> are completely replaced. Partially updating nested fields is not supported.  Changes to the field <code>JobSettings.timeout_seconds</code> are applied to active runs. Changes to other fields are applied to future runs only. Key-values: - name:     An optional name for the job, e.g. <code>A multitask job</code>. - tags:     A map of tags associated with the job. These are forwarded     to the cluster as cluster tags for jobs clusters, and are     subject to the same limitations as cluster tags. A maximum     of 25 tags can be added to the job, e.g.     <pre><code>{\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n</code></pre> - tasks:     A list of task specifications to be executed by this job, e.g.     <pre><code>[\n    {\n        \"task_key\": \"Sessionize\",\n        \"description\": \"Extracts session data from events\",\n        \"depends_on\": [],\n        \"existing_cluster_id\": \"0923-164208-meows279\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.Sessionize\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Orders_Ingest\",\n        \"description\": \"Ingests order data\",\n        \"depends_on\": [],\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"spark_jar_task\": {\n            \"main_class_name\": \"com.databricks.OrdersIngest\",\n            \"parameters\": [\n                \"--data\",\n                \"dbfs:/path/to/order-data.json\",\n            ],\n        },\n        \"libraries\": [\n            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n        ],\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n    {\n        \"task_key\": \"Match\",\n        \"description\": \"Matches orders with user sessions\",\n        \"depends_on\": [\n            {\"task_key\": \"Orders_Ingest\"},\n            {\"task_key\": \"Sessionize\"},\n        ],\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n        \"notebook_task\": {\n            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n            \"source\": \"WORKSPACE\",\n            \"base_parameters\": {\n                \"name\": \"John Doe\",\n                \"age\": \"35\",\n            },\n        },\n        \"timeout_seconds\": 86400,\n        \"max_retries\": 3,\n        \"min_retry_interval_millis\": 2000,\n        \"retry_on_timeout\": False,\n    },\n]\n</code></pre> - job_clusters:     A list of job cluster specifications that can be shared and     reused by tasks of this job. Libraries cannot be declared in     a shared job cluster. You must declare dependent libraries     in task settings, e.g.     <pre><code>[\n    {\n        \"job_cluster_key\": \"auto_scaling_cluster\",\n        \"new_cluster\": {\n            \"spark_version\": \"7.3.x-scala2.12\",\n            \"node_type_id\": \"i3.xlarge\",\n            \"spark_conf\": {\"spark.speculation\": True},\n            \"aws_attributes\": {\n                \"availability\": \"SPOT\",\n                \"zone_id\": \"us-west-2a\",\n            },\n            \"autoscale\": {\n                \"min_workers\": 2,\n                \"max_workers\": 16,\n            },\n        },\n    }\n]\n</code></pre> - email_notifications:     An optional set of email addresses that is notified when     runs of this job begin or complete as well as when this job     is deleted. The default behavior is to not send any emails. - webhook_notifications:     A collection of system notification IDs to notify when runs     of this job begin or complete. The default behavior is to     not send any system notifications. - timeout_seconds:     An optional timeout applied to each run of this job. The     default behavior is to have no timeout, e.g. <code>86400</code>. - schedule:     An optional periodic schedule for this job. The default     behavior is that the job only runs when triggered by     clicking \u201cRun Now\u201d in the Jobs UI or sending an API request     to <code>runNow</code>. - max_concurrent_runs:     An optional maximum allowed number of concurrent runs of the     job.  Set this value if you want to be able to execute     multiple runs of the same job concurrently. This is useful     for example if you trigger your job on a frequent schedule     and want to allow consecutive runs to overlap with each     other, or if you want to trigger multiple runs which differ     by their input parameters.  This setting affects only new     runs. For example, suppose the job\u2019s concurrency is 4 and     there are 4 concurrent active runs. Then setting the     concurrency to 3 won\u2019t kill any of the active runs. However,     from then on, new runs are skipped unless there are fewer     than 3 active runs.  This value cannot exceed 1000. Setting     this value to 0 causes all new runs to be skipped. The     default behavior is to allow only 1 concurrent run, e.g.     <code>10</code>. - git_source:     This functionality is in Public Preview.  An optional     specification for a remote repository containing the     notebooks used by this job's notebook tasks, e.g.     <pre><code>{\n    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n    \"git_branch\": \"main\",\n    \"git_provider\": \"gitHub\",\n}\n</code></pre> - format:     Used to tell what is the format of the job. This field is     ignored in Create/Update/Reset calls. When using the Jobs     API 2.1 this value is always set to <code>'MULTI_TASK'</code>, e.g.     <code>MULTI_TASK</code>.</p> <code>None</code> <code>fields_to_remove</code> <code>Optional[List[str]]</code> <p>Remove top-level fields in the job settings. Removing nested fields is not supported. This field is optional, e.g. <pre><code>[\"libraries\", \"schedule\"]\n</code></pre></p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Upon success, an empty dict.</p> API Endpoint: <p><code>/2.1/jobs/update</code></p> API Responses: Response Description 200 Job was updated successfully. 400 The request was malformed. See JSON response for error details. 401 The request was unauthorized. 500 The request was not handled correctly due to a server error. Source code in <code>prefect_databricks/jobs.py</code> <pre><code>@task\nasync def jobs_update(\n    databricks_credentials: \"DatabricksCredentials\",\n    job_id: Optional[int] = None,\n    new_settings: \"models.JobSettings\" = None,\n    fields_to_remove: Optional[List[str]] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Add, update, or remove specific settings of an existing job. Use the Reset\n    endpoint to overwrite all job settings.\n\n    Args:\n        databricks_credentials:\n            Credentials to use for authentication with Databricks.\n        job_id:\n            The canonical identifier of the job to update. This field is required,\n            e.g. `11223344`.\n        new_settings:\n            The new settings for the job. Any top-level fields specified in\n            `new_settings` are completely replaced. Partially updating\n            nested fields is not supported.  Changes to the field\n            `JobSettings.timeout_seconds` are applied to active runs.\n            Changes to other fields are applied to future runs only. Key-values:\n            - name:\n                An optional name for the job, e.g. `A multitask job`.\n            - tags:\n                A map of tags associated with the job. These are forwarded\n                to the cluster as cluster tags for jobs clusters, and are\n                subject to the same limitations as cluster tags. A maximum\n                of 25 tags can be added to the job, e.g.\n                ```\n                {\"cost-center\": \"engineering\", \"team\": \"jobs\"}\n                ```\n            - tasks:\n                A list of task specifications to be executed by this job, e.g.\n                ```\n                [\n                    {\n                        \"task_key\": \"Sessionize\",\n                        \"description\": \"Extracts session data from events\",\n                        \"depends_on\": [],\n                        \"existing_cluster_id\": \"0923-164208-meows279\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.Sessionize\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Orders_Ingest\",\n                        \"description\": \"Ingests order data\",\n                        \"depends_on\": [],\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"spark_jar_task\": {\n                            \"main_class_name\": \"com.databricks.OrdersIngest\",\n                            \"parameters\": [\n                                \"--data\",\n                                \"dbfs:/path/to/order-data.json\",\n                            ],\n                        },\n                        \"libraries\": [\n                            {\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}\n                        ],\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                    {\n                        \"task_key\": \"Match\",\n                        \"description\": \"Matches orders with user sessions\",\n                        \"depends_on\": [\n                            {\"task_key\": \"Orders_Ingest\"},\n                            {\"task_key\": \"Sessionize\"},\n                        ],\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                        \"notebook_task\": {\n                            \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                            \"source\": \"WORKSPACE\",\n                            \"base_parameters\": {\n                                \"name\": \"John Doe\",\n                                \"age\": \"35\",\n                            },\n                        },\n                        \"timeout_seconds\": 86400,\n                        \"max_retries\": 3,\n                        \"min_retry_interval_millis\": 2000,\n                        \"retry_on_timeout\": False,\n                    },\n                ]\n                ```\n            - job_clusters:\n                A list of job cluster specifications that can be shared and\n                reused by tasks of this job. Libraries cannot be declared in\n                a shared job cluster. You must declare dependent libraries\n                in task settings, e.g.\n                ```\n                [\n                    {\n                        \"job_cluster_key\": \"auto_scaling_cluster\",\n                        \"new_cluster\": {\n                            \"spark_version\": \"7.3.x-scala2.12\",\n                            \"node_type_id\": \"i3.xlarge\",\n                            \"spark_conf\": {\"spark.speculation\": True},\n                            \"aws_attributes\": {\n                                \"availability\": \"SPOT\",\n                                \"zone_id\": \"us-west-2a\",\n                            },\n                            \"autoscale\": {\n                                \"min_workers\": 2,\n                                \"max_workers\": 16,\n                            },\n                        },\n                    }\n                ]\n                ```\n            - email_notifications:\n                An optional set of email addresses that is notified when\n                runs of this job begin or complete as well as when this job\n                is deleted. The default behavior is to not send any emails.\n            - webhook_notifications:\n                A collection of system notification IDs to notify when runs\n                of this job begin or complete. The default behavior is to\n                not send any system notifications.\n            - timeout_seconds:\n                An optional timeout applied to each run of this job. The\n                default behavior is to have no timeout, e.g. `86400`.\n            - schedule:\n                An optional periodic schedule for this job. The default\n                behavior is that the job only runs when triggered by\n                clicking \u201cRun Now\u201d in the Jobs UI or sending an API request\n                to `runNow`.\n            - max_concurrent_runs:\n                An optional maximum allowed number of concurrent runs of the\n                job.  Set this value if you want to be able to execute\n                multiple runs of the same job concurrently. This is useful\n                for example if you trigger your job on a frequent schedule\n                and want to allow consecutive runs to overlap with each\n                other, or if you want to trigger multiple runs which differ\n                by their input parameters.  This setting affects only new\n                runs. For example, suppose the job\u2019s concurrency is 4 and\n                there are 4 concurrent active runs. Then setting the\n                concurrency to 3 won\u2019t kill any of the active runs. However,\n                from then on, new runs are skipped unless there are fewer\n                than 3 active runs.  This value cannot exceed 1000\\. Setting\n                this value to 0 causes all new runs to be skipped. The\n                default behavior is to allow only 1 concurrent run, e.g.\n                `10`.\n            - git_source:\n                This functionality is in Public Preview.  An optional\n                specification for a remote repository containing the\n                notebooks used by this job's notebook tasks, e.g.\n                ```\n                {\n                    \"git_url\": \"https://github.com/databricks/databricks-cli\",\n                    \"git_branch\": \"main\",\n                    \"git_provider\": \"gitHub\",\n                }\n                ```\n            - format:\n                Used to tell what is the format of the job. This field is\n                ignored in Create/Update/Reset calls. When using the Jobs\n                API 2.1 this value is always set to `'MULTI_TASK'`, e.g.\n                `MULTI_TASK`.\n        fields_to_remove:\n            Remove top-level fields in the job settings. Removing nested fields is\n            not supported. This field is optional, e.g.\n            ```\n            [\"libraries\", \"schedule\"]\n            ```\n\n    Returns:\n        Upon success, an empty dict.\n\n    &lt;h4&gt;API Endpoint:&lt;/h4&gt;\n    `/2.1/jobs/update`\n\n    &lt;h4&gt;API Responses:&lt;/h4&gt;\n    | Response | Description |\n    | --- | --- |\n    | 200 | Job was updated successfully. |\n    | 400 | The request was malformed. See JSON response for error details. |\n    | 401 | The request was unauthorized. |\n    | 500 | The request was not handled correctly due to a server error. |\n    \"\"\"  # noqa\n    endpoint = \"/2.1/jobs/update\"  # noqa\n\n    responses = {\n        200: \"Job was updated successfully.\",  # noqa\n        400: \"The request was malformed. See JSON response for error details.\",  # noqa\n        401: \"The request was unauthorized.\",  # noqa\n        500: \"The request was not handled correctly due to a server error.\",  # noqa\n    }\n\n    json_payload = {\n        \"job_id\": job_id,\n        \"new_settings\": new_settings,\n        \"fields_to_remove\": fields_to_remove,\n    }\n\n    response = await execute_endpoint.fn(\n        endpoint,\n        databricks_credentials,\n        http_method=HTTPMethod.POST,\n        json=json_payload,\n    )\n\n    contents = _unpack_contents(response, responses)\n    return contents\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/","title":"Rest","text":""},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest","title":"<code>prefect_databricks.rest</code>","text":"<p>This is a module containing generic REST tasks.</p>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.HTTPMethod","title":"<code>HTTPMethod</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Available HTTP request methods.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>class HTTPMethod(Enum):\n    \"\"\"\n    Available HTTP request methods.\n    \"\"\"\n\n    GET = \"get\"\n    POST = \"post\"\n    PUT = \"put\"\n    DELETE = \"delete\"\n    PATCH = \"patch\"\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.execute_endpoint","title":"<code>execute_endpoint</code>  <code>async</code>","text":"<p>Generic function for executing REST endpoints.</p> <p>Parameters:</p> Name Type Description Default <code>endpoint</code> <code>str</code> <p>The endpoint route.</p> required <code>databricks_credentials</code> <code>DatabricksCredentials</code> <p>Credentials to use for authentication with Databricks.</p> required <code>http_method</code> <code>HTTPMethod</code> <p>Either GET, POST, PUT, DELETE, or PATCH.</p> <code>GET</code> <code>params</code> <code>Dict[str, Any]</code> <p>URL query parameters in the request.</p> <code>None</code> <code>json</code> <code>Dict[str, Any]</code> <p>JSON serializable object to include in the body of the request.</p> <code>None</code> <code>**kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Response</code> <p>The httpx.Response from interacting with the endpoint.</p> <p>Examples:</p> <p>Lists jobs on the Databricks instance. <pre><code>from prefect import flow\nfrom prefect_databricks import DatabricksCredentials\nfrom prefect_databricks.rest import execute_endpoint\n@flow\ndef example_execute_endpoint_flow():\n    endpoint = \"/2.1/jobs/list\"\n    databricks_credentials = DatabricksCredentials.load(\"my-block\")\n    params = {\n        \"limit\": 5,\n        \"offset\": None,\n        \"expand_tasks\": True,\n    }\n    response = execute_endpoint(\n        endpoint,\n        databricks_credentials,\n        params=params\n    )\n    return response.json()\n</code></pre></p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>@task\nasync def execute_endpoint(\n    endpoint: str,\n    databricks_credentials: \"DatabricksCredentials\",\n    http_method: HTTPMethod = HTTPMethod.GET,\n    params: Dict[str, Any] = None,\n    json: Dict[str, Any] = None,\n    **kwargs: Dict[str, Any],\n) -&gt; httpx.Response:\n    \"\"\"\n    Generic function for executing REST endpoints.\n\n    Args:\n        endpoint: The endpoint route.\n        databricks_credentials: Credentials to use for authentication with Databricks.\n        http_method: Either GET, POST, PUT, DELETE, or PATCH.\n        params: URL query parameters in the request.\n        json: JSON serializable object to include in the body of the request.\n        **kwargs: Additional keyword arguments to pass.\n\n    Returns:\n        The httpx.Response from interacting with the endpoint.\n\n    Examples:\n        Lists jobs on the Databricks instance.\n        ```python\n        from prefect import flow\n        from prefect_databricks import DatabricksCredentials\n        from prefect_databricks.rest import execute_endpoint\n        @flow\n        def example_execute_endpoint_flow():\n            endpoint = \"/2.1/jobs/list\"\n            databricks_credentials = DatabricksCredentials.load(\"my-block\")\n            params = {\n                \"limit\": 5,\n                \"offset\": None,\n                \"expand_tasks\": True,\n            }\n            response = execute_endpoint(\n                endpoint,\n                databricks_credentials,\n                params=params\n            )\n            return response.json()\n        ```\n    \"\"\"\n    if isinstance(http_method, HTTPMethod):\n        http_method = http_method.value\n\n    if params is not None:\n        stripped_params = strip_kwargs(**params)\n    else:\n        stripped_params = None\n\n    if json is not None:\n        kwargs[\"json\"] = strip_kwargs(**json)\n\n    async with databricks_credentials.get_client() as client:\n        response = await getattr(client, http_method)(\n            endpoint, params=stripped_params, **kwargs\n        )\n\n    return response\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.serialize_model","title":"<code>serialize_model</code>","text":"<p>Recursively serializes <code>pydantic.BaseModel</code> into JSON; returns original obj if not a <code>BaseModel</code>.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Any</code> <p>Input object to serialize.</p> required <p>Returns:</p> Type Description <code>Any</code> <p>Serialized version of object.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>def serialize_model(obj: Any) -&gt; Any:\n    \"\"\"\n    Recursively serializes `pydantic.BaseModel` into JSON;\n    returns original obj if not a `BaseModel`.\n\n    Args:\n        obj: Input object to serialize.\n\n    Returns:\n        Serialized version of object.\n    \"\"\"\n    if isinstance(obj, list):\n        return [serialize_model(o) for o in obj]\n    elif isinstance(obj, Dict):\n        return {k: serialize_model(v) for k, v in obj.items()}\n\n    if isinstance(obj, MODELS):\n        return model_dump(obj, mode=\"json\")\n    elif isinstance(obj, Enum):\n        return obj.value\n    return obj\n</code></pre>"},{"location":"integrations/prefect-databricks/rest/#prefect_databricks.rest.strip_kwargs","title":"<code>strip_kwargs</code>","text":"<p>Recursively drops keyword arguments if value is None, and serializes any <code>pydantic.BaseModel</code> types.</p> <p>Parameters:</p> Name Type Description Default <code>**kwargs</code> <code>Dict</code> <p>Input keyword arguments.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict</code> <p>Stripped version of kwargs.</p> Source code in <code>prefect_databricks/rest.py</code> <pre><code>def strip_kwargs(**kwargs: Dict) -&gt; Dict:\n    \"\"\"\n    Recursively drops keyword arguments if value is None,\n    and serializes any `pydantic.BaseModel` types.\n\n    Args:\n        **kwargs: Input keyword arguments.\n\n    Returns:\n        Stripped version of kwargs.\n    \"\"\"\n    stripped_dict = {}\n    for k, v in kwargs.items():\n        v = serialize_model(v)\n        if isinstance(v, dict):\n            v = strip_kwargs(**v)\n        if v is not None:\n            stripped_dict[k] = v\n    return stripped_dict or {}\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs","title":"<code>prefect_databricks.models.jobs</code>","text":""},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlList","title":"<code>AccessControlList</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlList(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    access_control_list: Optional[List[AccessControlRequest]] = Field(\n        None, description=\"List of permissions to set on the job.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequest","title":"<code>AccessControlRequest</code>","text":"<p>               Bases: <code>AccessControlRequestForUser</code>, <code>AccessControlRequestForGroup</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequest(AccessControlRequestForUser, AccessControlRequestForGroup):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForGroup","title":"<code>AccessControlRequestForGroup</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForGroup(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    group_name: Optional[GroupName] = None\n    permission_level: Optional[PermissionLevelForGroup] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForServicePrincipal","title":"<code>AccessControlRequestForServicePrincipal</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForServicePrincipal(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    permission_level: Optional[PermissionLevel] = None\n    service_principal_name: Optional[ServicePrincipalName] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AccessControlRequestForUser","title":"<code>AccessControlRequestForUser</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AccessControlRequestForUser(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    permission_level: Optional[PermissionLevel] = None\n    user_name: Optional[UserName] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AutoScale","title":"<code>AutoScale</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AutoScale(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    max_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"The maximum number of workers to which the cluster can scale up when\"\n            \" overloaded. max_workers must be strictly greater than min_workers.\"\n        ),\n    )\n    min_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"The minimum number of workers to which the cluster can scale down when\"\n            \" underutilized. It is also the initial number of workers the cluster has\"\n            \" after creation.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.AwsAttributes","title":"<code>AwsAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class AwsAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    availability: Optional[Literal[\"SPOT\", \"ON_DEMAND\", \"SPOT_WITH_FALLBACK\"]] = Field(\n        None,\n        description=(\n            \"Availability type used for all subsequent nodes past the `first_on_demand`\"\n            \" ones. **Note:** If `first_on_demand` is zero, this availability type is\"\n            \" used for the entire cluster.\\n\\n`SPOT`: use spot instances.\\n`ON_DEMAND`:\"\n            \" use on-demand instances.\\n`SPOT_WITH_FALLBACK`: preferably use spot\"\n            \" instances, but fall back to on-demand instances if spot instances cannot\"\n            \" be acquired (for example, if AWS spot prices are too high).\"\n        ),\n    )\n    ebs_volume_count: Optional[int] = Field(\n        None,\n        description=(\n            \"The number of volumes launched for each instance. You can choose up to 10\"\n            \" volumes. This feature is only enabled for supported node types. Legacy\"\n            \" node types cannot specify custom EBS volumes. For node types with no\"\n            \" instance store, at least one EBS volume needs to be specified; otherwise,\"\n            \" cluster creation fails.\\n\\nThese EBS volumes are mounted at `/ebs0`,\"\n            \" `/ebs1`, and etc. Instance store volumes are mounted at `/local_disk0`,\"\n            \" `/local_disk1`, and etc.\\n\\nIf EBS volumes are attached, Databricks\"\n            \" configures Spark to use only the EBS volumes for scratch storage because\"\n            \" heterogeneously sized scratch devices can lead to inefficient disk\"\n            \" utilization. If no EBS volumes are attached, Databricks configures Spark\"\n            \" to use instance store volumes.\\n\\nIf EBS volumes are specified, then the\"\n            \" Spark configuration `spark.local.dir` is overridden.\"\n        ),\n    )\n    ebs_volume_iops: Optional[int] = Field(\n        None,\n        description=(\n            \"The number of IOPS per EBS gp3 volume.\\n\\nThis value must be between 3000\"\n            \" and 16000.\\n\\nThe value of IOPS and throughput is calculated based on AWS\"\n            \" documentation to match the maximum performance of a gp2 volume with the\"\n            \" same volume size.\\n\\nFor more information, see the [EBS volume limit\"\n            \" calculator](https://github.com/awslabs/aws-support-tools/tree/master/EBS/VolumeLimitCalculator).\"\n        ),\n    )\n    ebs_volume_size: Optional[int] = Field(\n        None,\n        description=(\n            \"The size of each EBS volume (in GiB) launched for each instance. For\"\n            \" general purpose SSD, this value must be within the range 100 - 4096\\\\.\"\n            \" For throughput optimized HDD, this value must be within the range 500 -\"\n            \" 4096\\\\. Custom EBS volumes cannot be specified for the legacy node types\"\n            \" (_memory-optimized_ and _compute-optimized_).\"\n        ),\n    )\n    ebs_volume_throughput: Optional[int] = Field(\n        None,\n        description=(\n            \"The throughput per EBS gp3 volume, in MiB per second.\\n\\nThis value must\"\n            \" be between 125 and 1000.\"\n        ),\n    )\n    ebs_volume_type: Optional[\n        Literal[\"GENERAL_PURPOSE_SSD\", \"THROUGHPUT_OPTIMIZED_HDD\"]\n    ] = Field(\n        None,\n        description=(\n            \"The type of EBS volume that is launched with this\"\n            \" cluster.\\n\\n`GENERAL_PURPOSE_SSD`: provision extra storage using AWS gp2\"\n            \" EBS volumes.\\n`THROUGHPUT_OPTIMIZED_HDD`: provision extra storage using\"\n            \" AWS st1 volumes.\"\n        ),\n    )\n    first_on_demand: Optional[int] = Field(\n        None,\n        description=(\n            \"The first first_on_demand nodes of the cluster are placed on on-demand\"\n            \" instances. If this value is greater than 0, the cluster driver node is\"\n            \" placed on an on-demand instance. If this value is greater than or equal\"\n            \" to the current cluster size, all nodes are placed on on-demand instances.\"\n            \" If this value is less than the current cluster size, first_on_demand\"\n            \" nodes are placed on on-demand instances and the remainder are placed on\"\n            \" `availability` instances. This value does not affect cluster size and\"\n            \" cannot be mutated over the lifetime of a cluster.\"\n        ),\n    )\n    instance_profile_arn: Optional[str] = Field(\n        None,\n        description=(\n            \"Nodes for this cluster are only be placed on AWS instances with this\"\n            \" instance profile. If omitted, nodes are placed on instances without an\"\n            \" instance profile. The instance profile must have previously been added to\"\n            \" the Databricks environment by an account administrator.\\n\\nThis feature\"\n            \" may only be available to certain customer plans.\"\n        ),\n    )\n    spot_bid_price_percent: Optional[int] = Field(\n        None,\n        description=(\n            \"The max price for AWS spot instances, as a percentage of the corresponding\"\n            \" instance type\u2019s on-demand price. For example, if this field is set to 50,\"\n            \" and the cluster needs a new `i3.xlarge` spot instance, then the max price\"\n            \" is half of the price of on-demand `i3.xlarge` instances. Similarly, if\"\n            \" this field is set to 200, the max price is twice the price of on-demand\"\n            \" `i3.xlarge` instances. If not specified, the default value is 100\\\\. When\"\n            \" spot instances are requested for this cluster, only spot instances whose\"\n            \" max price percentage matches this field is considered. For safety, we\"\n            \" enforce this field to be no more than 10000.\"\n        ),\n    )\n    zone_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Identifier for the availability zone/datacenter in which the cluster\"\n            \" resides. You have three options:\\n\\n**Specify an availability zone as a\"\n            \" string**, for example: \u201cus-west-2a\u201d. The provided availability zone must\"\n            \" be in the same region as the Databricks deployment. For example,\"\n            \" \u201cus-west-2a\u201d is not a valid zone ID if the Databricks deployment resides\"\n            \" in the \u201cus-east-1\u201d region.\\n\\n**Enable automatic availability zone\"\n            \" selection (\u201cAuto-AZ\u201d)**, by setting the value \u201cauto\u201d. Databricks selects\"\n            \" the AZ based on available IPs in the workspace subnets and retries in\"\n            \" other availability zones if AWS returns insufficient capacity\"\n            \" errors.\\n\\n**Do not specify a value**. If not specified, a default zone\"\n            \" is used.\\n\\nThe list of available zones as well as the default value can\"\n            \" be found by using the [List\"\n            \" zones](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-zones)\"\n            \" API.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanManage","title":"<code>CanManage</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to manage the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanManage(str, Enum):\n    \"\"\"\n    Permission to manage the job.\n    \"\"\"\n\n    canmanage = \"CAN_MANAGE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanManageRun","title":"<code>CanManageRun</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to run and/or manage runs for the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanManageRun(str, Enum):\n    \"\"\"\n    Permission to run and/or manage runs for the job.\n    \"\"\"\n\n    canmanagerun = \"CAN_MANAGE_RUN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CanView","title":"<code>CanView</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Permission to view the settings of the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CanView(str, Enum):\n    \"\"\"\n    Permission to view the settings of the job.\n    \"\"\"\n\n    canview = \"CAN_VIEW\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterAttributes","title":"<code>ClusterAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autotermination_minutes: Optional[int] = Field(\n        None,\n        description=(\n            \"Automatically terminates the cluster after it is inactive for this time in\"\n            \" minutes. If not set, this cluster is not be automatically terminated. If\"\n            \" specified, the threshold must be between 10 and 10000 minutes. You can\"\n            \" also set this value to 0 to explicitly disable automatic termination.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values are used.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs is delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-ID&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-ID&gt;/executor`.\"\n        ),\n    )\n    cluster_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Cluster name requested by the user. This doesn\u2019t have to be unique. If not\"\n            \" specified at creation, the cluster name is an empty string.\"\n        ),\n    )\n    cluster_source: Optional[ClusterSource] = Field(\n        None,\n        description=(\n            \"Determines whether the cluster was created by a user through the UI,\"\n            \" created by the Databricks Jobs scheduler, or through an API request.\"\n        ),\n    )\n    custom_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    docker_image: Optional[DockerImage] = Field(\n        None,\n        description=(\n            \"Docker image for a [custom\"\n            \" container](https://docs.databricks.com/clusters/custom-containers.html).\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly. Refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    enable_local_disk_encryption: Optional[bool] = Field(\n        None,\n        description=(\n            \"Determines whether encryption of the disks attached to the cluster locally\"\n            \" is enabled.\"\n        ),\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of destinations can\"\n            \" be specified. The scripts are executed sequentially in the order\"\n            \" provided. If `cluster_log_conf` is specified, init script logs are sent\"\n            \" to `&lt;destination&gt;/&lt;cluster-ID&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to which the cluster belongs. Refer\"\n            \" to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html)\"\n            \" for details.\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    policy_id: Optional[str] = Field(\n        None,\n        description=(\n            \"A [cluster\"\n            \" policy](https://docs.databricks.com/dev-tools/api/latest/policies.html) ID.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pairs of the form (X,Y) are exported\"\n            \" as is (that is, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nIn order to specify an additional set of\"\n            \" `SPARK_DAEMON_JAVA_OPTS`, we recommend appending them to\"\n            \" `$SPARK_DAEMON_JAVA_OPTS` as shown in the following example. This ensures\"\n            \" that all default databricks managed environmental variables are included\"\n            ' as well.\\n\\nExample Spark environment variables: `{\"SPARK_WORKER_MEMORY\":'\n            ' \"28000m\", \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or'\n            ' `{\"SPARK_DAEMON_JAVA_OPTS\": \"$SPARK_DAEMON_JAVA_OPTS'\n            ' -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: Optional[str] = Field(\n        None,\n        description=(\n            \"The runtime version of the cluster, for example \u201c5.0.x-scala2.11\u201d. You can\"\n            \" retrieve a list of available runtime versions by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that is added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterCloudProviderNodeInfo","title":"<code>ClusterCloudProviderNodeInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterCloudProviderNodeInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    available_core_quota: Optional[int] = Field(\n        None, description=\"Available CPU core quota.\"\n    )\n    status: Optional[ClusterCloudProviderNodeStatus] = Field(\n        None, description=\"Status as reported by the cloud provider.\"\n    )\n    total_core_quota: Optional[int] = Field(None, description=\"Total CPU core quota.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterCloudProviderNodeStatus","title":"<code>ClusterCloudProviderNodeStatus</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* NotEnabledOnSubscription: Node type not available for subscription.\n</code></pre> <ul> <li>NotAvailableInRegion: Node type not available in region.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterCloudProviderNodeStatus(str, Enum):\n    \"\"\"\n        * NotEnabledOnSubscription: Node type not available for subscription.\n    * NotAvailableInRegion: Node type not available in region.\n\n    \"\"\"\n\n    not_enabled_on_subscription = \"NotEnabledOnSubscription\"\n    not_available_in_region = \"NotAvailableInRegion\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterEvent","title":"<code>ClusterEvent</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterEvent(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: str = Field(\n        ..., description=\"Canonical identifier for the cluster. This field is required.\"\n    )\n    details: EventDetails = Field(\n        ..., description=\"The event details. This field is required.\"\n    )\n    timestamp: Optional[int] = Field(\n        None,\n        description=(\n            \"The timestamp when the event occurred, stored as the number of\"\n            \" milliseconds since the unix epoch. Assigned by the Timeline service.\"\n        ),\n    )\n    type: ClusterEventType = Field(\n        ..., description=\"The event type. This field is required.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterEventType","title":"<code>ClusterEventType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `CREATING`: Indicates that the cluster is being created.\n</code></pre> <ul> <li><code>DID_NOT_EXPAND_DISK</code>: Indicates that a disk is low on space, but adding disks would put it over the max capacity.</li> <li><code>EXPANDED_DISK</code>: Indicates that a disk was low on space and the disks were expanded.</li> <li><code>FAILED_TO_EXPAND_DISK</code>: Indicates that a disk was low on space and disk space could not be expanded.</li> <li><code>INIT_SCRIPTS_STARTING</code>: Indicates that the cluster scoped init script has started.</li> <li><code>INIT_SCRIPTS_FINISHED</code>: Indicates that the cluster scoped init script has finished.</li> <li><code>STARTING</code>: Indicates that the cluster is being started.</li> <li><code>RESTARTING</code>: Indicates that the cluster is being started.</li> <li><code>TERMINATING</code>: Indicates that the cluster is being terminated.</li> <li><code>EDITED</code>: Indicates that the cluster has been edited.</li> <li><code>RUNNING</code>: Indicates the cluster has finished being created. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.</li> <li><code>RESIZING</code>: Indicates a change in the target size of the cluster (upsize or downsize).</li> <li><code>UPSIZE_COMPLETED</code>: Indicates that nodes finished being added to the cluster. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.</li> <li><code>NODES_LOST</code>: Indicates that some nodes were lost from the cluster.</li> <li><code>DRIVER_HEALTHY</code>: Indicates that the driver is healthy and the cluster is ready for use.</li> <li><code>DRIVER_UNAVAILABLE</code>: Indicates that the driver is unavailable.</li> <li><code>SPARK_EXCEPTION</code>: Indicates that a Spark exception was thrown from the driver.</li> <li><code>DRIVER_NOT_RESPONDING</code>: Indicates that the driver is up but is not responsive, likely due to GC.</li> <li><code>DBFS_DOWN</code>: Indicates that the driver is up but DBFS is down.</li> <li><code>METASTORE_DOWN</code>: Indicates that the driver is up but the metastore is down.</li> <li><code>NODE_BLACKLISTED</code>: Indicates that a node is not allowed by Spark.</li> <li><code>PINNED</code>: Indicates that the cluster was pinned.</li> <li><code>UNPINNED</code>: Indicates that the cluster was unpinned.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterEventType(str, Enum):\n    \"\"\"\n        * `CREATING`: Indicates that the cluster is being created.\n    * `DID_NOT_EXPAND_DISK`: Indicates that a disk is low on space, but adding disks would put it over the max capacity.\n    * `EXPANDED_DISK`: Indicates that a disk was low on space and the disks were expanded.\n    * `FAILED_TO_EXPAND_DISK`: Indicates that a disk was low on space and disk space could not be expanded.\n    * `INIT_SCRIPTS_STARTING`: Indicates that the cluster scoped init script has started.\n    * `INIT_SCRIPTS_FINISHED`: Indicates that the cluster scoped init script has finished.\n    * `STARTING`: Indicates that the cluster is being started.\n    * `RESTARTING`: Indicates that the cluster is being started.\n    * `TERMINATING`: Indicates that the cluster is being terminated.\n    * `EDITED`: Indicates that the cluster has been edited.\n    * `RUNNING`: Indicates the cluster has finished being created. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.\n    * `RESIZING`: Indicates a change in the target size of the cluster (upsize or downsize).\n    * `UPSIZE_COMPLETED`: Indicates that nodes finished being added to the cluster. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.\n    * `NODES_LOST`: Indicates that some nodes were lost from the cluster.\n    * `DRIVER_HEALTHY`: Indicates that the driver is healthy and the cluster is ready for use.\n    * `DRIVER_UNAVAILABLE`: Indicates that the driver is unavailable.\n    * `SPARK_EXCEPTION`: Indicates that a Spark exception was thrown from the driver.\n    * `DRIVER_NOT_RESPONDING`: Indicates that the driver is up but is not responsive, likely due to GC.\n    * `DBFS_DOWN`: Indicates that the driver is up but DBFS is down.\n    * `METASTORE_DOWN`: Indicates that the driver is up but the metastore is down.\n    * `NODE_BLACKLISTED`: Indicates that a node is not allowed by Spark.\n    * `PINNED`: Indicates that the cluster was pinned.\n    * `UNPINNED`: Indicates that the cluster was unpinned.\n    \"\"\"\n\n    creating = \"CREATING\"\n    didnotexpanddisk = \"DID_NOT_EXPAND_DISK\"\n    expandeddisk = \"EXPANDED_DISK\"\n    failedtoexpanddisk = \"FAILED_TO_EXPAND_DISK\"\n    initscriptsstarting = \"INIT_SCRIPTS_STARTING\"\n    initscriptsfinished = \"INIT_SCRIPTS_FINISHED\"\n    starting = \"STARTING\"\n    restarting = \"RESTARTING\"\n    terminating = \"TERMINATING\"\n    edited = \"EDITED\"\n    running = \"RUNNING\"\n    resizing = \"RESIZING\"\n    upsizecompleted = \"UPSIZE_COMPLETED\"\n    nodeslost = \"NODES_LOST\"\n    driverhealthy = \"DRIVER_HEALTHY\"\n    driverunavailable = \"DRIVER_UNAVAILABLE\"\n    sparkexception = \"SPARK_EXCEPTION\"\n    drivernotresponding = \"DRIVER_NOT_RESPONDING\"\n    dbfsdown = \"DBFS_DOWN\"\n    metastoredown = \"METASTORE_DOWN\"\n    nodeblacklisted = \"NODE_BLACKLISTED\"\n    pinned = \"PINNED\"\n    unpinned = \"UNPINNED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterInfo","title":"<code>ClusterInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, parameters needed in order to automatically scale clusters\"\n            \" up and down based on load.\"\n        ),\n    )\n    autotermination_minutes: Optional[int] = Field(\n        None,\n        description=(\n            \"Automatically terminates the cluster after it is inactive for this time in\"\n            \" minutes. If not set, this cluster is not be automatically terminated. If\"\n            \" specified, the threshold must be between 10 and 10000 minutes. You can\"\n            \" also set this value to 0 to explicitly disable automatic termination.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values is used.\"\n        ),\n    )\n    cluster_cores: Optional[float] = Field(\n        None,\n        description=(\n            \"Number of CPU cores available for this cluster. This can be fractional\"\n            \" since certain node types are configured to share cores between Spark\"\n            \" nodes on the same instance.\"\n        ),\n    )\n    cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Canonical identifier for the cluster. This ID is retained during cluster\"\n            \" restarts and resizes, while each new cluster has a globally unique ID.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs are delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-ID&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-ID&gt;/executor`.\"\n        ),\n    )\n    cluster_log_status: Optional[LogSyncStatus] = Field(\n        None, description=\"Cluster log delivery status.\"\n    )\n    cluster_memory_mb: Optional[int] = Field(\n        None, description=\"Total amount of cluster memory, in megabytes.\"\n    )\n    cluster_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Cluster name requested by the user. This doesn\u2019t have to be unique. If not\"\n            \" specified at creation, the cluster name is an empty string.\"\n        ),\n    )\n    cluster_source: Optional[ClusterSource] = Field(\n        None,\n        description=(\n            \"Determines whether the cluster was created by a user through the UI, by\"\n            \" the Databricks Jobs scheduler, or through an API request.\"\n        ),\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"Creator user name. The field won\u2019t be included in the response if the user\"\n            \" has already been deleted.\"\n        ),\n    )\n    custom_tags: Optional[List[ClusterTag]] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    default_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags that are added by Databricks regardless\"\n            \" of any custom_tags, including:\\n\\n* Vendor: Databricks\\n* Creator:\"\n            \" &lt;username-of-creator&gt;\\n* ClusterName: &lt;name-of-cluster&gt;\\n* ClusterId:\"\n            \" &lt;id-of-cluster&gt;\\n* Name: &lt;Databricks internal use&gt;  \\nOn job clusters:\\n*\"\n            \" RunName: &lt;name-of-job&gt;\\n* JobId: &lt;id-of-job&gt;  \\nOn resources used by\"\n            \" Databricks SQL:\\n* SqlEndpointId: &lt;id-of-endpoint&gt;\"\n        ),\n    )\n    docker_image: Optional[DockerImage] = Field(\n        None,\n        description=(\n            \"Docker image for a [custom\"\n            \" container](https://docs.databricks.com/clusters/custom-containers.html).\"\n        ),\n    )\n    driver: Optional[SparkNode] = Field(\n        None,\n        description=(\n            \"Node on which the Spark driver resides. The driver node contains the Spark\"\n            \" master and the Databricks application that manages the per-notebook Spark\"\n            \" REPLs.\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly - refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    executors: Optional[List[SparkNode]] = Field(\n        None, description=\"Nodes on which the Spark executors reside.\"\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of destinations can\"\n            \" be specified. The scripts are executed sequentially in the order\"\n            \" provided. If `cluster_log_conf` is specified, init script logs are sent\"\n            \" to `&lt;destination&gt;/&lt;cluster-ID&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to which the cluster belongs. Refer\"\n            \" to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html)\"\n            \" for details.\"\n        ),\n    )\n    jdbc_port: Optional[int] = Field(\n        None,\n        description=(\n            \"Port on which Spark JDBC server is listening in the driver node. No\"\n            \" service listens on this port in executor nodes.\"\n        ),\n    )\n    last_activity_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster was last active. A cluster\"\n            \" is active if there is at least one command that has not finished on the\"\n            \" cluster. This field is available after the cluster has reached a\"\n            \" `RUNNING` state. Updates to this field are made as best-effort attempts.\"\n            \" Certain versions of Spark do not support reporting of cluster activity.\"\n            \" Refer to [Automatic\"\n            \" termination](https://docs.databricks.com/clusters/clusters-manage.html#automatic-termination)\"\n            \" for details.\"\n        ),\n    )\n    last_state_loss_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time when the cluster driver last lost its state (due to a restart or\"\n            \" driver failure).\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads. A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. **Note:** When reading the properties of a\"\n            \" cluster, this field reflects the desired number of workers rather than\"\n            \" the actual number of workers. For instance, if a cluster is resized from\"\n            \" 5 to 10 workers, this field is immediately updated to reflect the target\"\n            \" size of 10 workers, whereas the workers listed in `executors` gradually\"\n            \" increase from 5 to 10 as the new nodes are provisioned.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_context_id: Optional[int] = Field(\n        None,\n        description=(\n            \"A canonical SparkContext identifier. This value _does_ change when the\"\n            \" Spark driver restarts. The pair `(cluster_id, spark_context_id)` is a\"\n            \" globally unique identifier over all Spark contexts.\"\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pairs of the form (X,Y) are exported\"\n            \" as is (that is, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nTo specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we\"\n            \" recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the\"\n            \" following example. This ensures that all default databricks managed\"\n            \" environmental variables are included as well.\\n\\nExample Spark\"\n            ' environment variables: `{\"SPARK_WORKER_MEMORY\": \"28000m\",'\n            ' \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or `{\"SPARK_DAEMON_JAVA_OPTS\":'\n            ' \"$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: Optional[str] = Field(\n        None,\n        description=(\n            \"The runtime version of the cluster. You can retrieve a list of available\"\n            \" runtime versions by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that are added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster creation request was\"\n            \" received (when the cluster entered a `PENDING` state).\"\n        ),\n    )\n    state: Optional[ClusterState] = Field(None, description=\"State of the cluster.\")\n    state_message: Optional[str] = Field(\n        None,\n        description=(\n            \"A message associated with the most recent state transition (for example,\"\n            \" the reason why the cluster entered a `TERMINATED` state). This field is\"\n            \" unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    terminated_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when the cluster was terminated, if\"\n            \" applicable.\"\n        ),\n    )\n    termination_reason: Optional[TerminationReason] = Field(\n        None,\n        description=(\n            \"Information about why the cluster was terminated. This field only appears\"\n            \" when the cluster is in a `TERMINATING` or `TERMINATED` state.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterInstance","title":"<code>ClusterInstance</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterInstance(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The canonical identifier for the cluster used by a run. This field is\"\n            \" always available for runs on existing clusters. For runs on new clusters,\"\n            \" it becomes available once the cluster is created. This value can be used\"\n            \" to view logs by browsing to `/#setting/sparkui/$cluster_id/driver-logs`.\"\n            \" The logs continue to be available after the run completes.\\n\\nThe\"\n            \" response won\u2019t include this field if the identifier is not available yet.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    spark_context_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The canonical identifier for the Spark context used by a run. This field\"\n            \" is filled in once the run begins execution. This value can be used to\"\n            \" view the Spark UI by browsing to\"\n            \" `/#setting/sparkui/$cluster_id/$spark_context_id`. The Spark UI continues\"\n            \" to be available after the run has completed.\\n\\nThe response won\u2019t\"\n            \" include this field if the identifier is not available yet.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterLibraryStatuses","title":"<code>ClusterLibraryStatuses</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterLibraryStatuses(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cluster_id: Optional[str] = Field(\n        None, description=\"Unique identifier for the cluster.\"\n    )\n    library_statuses: Optional[List[LibraryFullStatus]] = Field(\n        None, description=\"Status of all libraries on the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterLogConf","title":"<code>ClusterLogConf</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterLogConf(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbfs: Optional[DbfsStorageInfo] = Field(\n        None,\n        description=(\n            \"DBFS location of cluster log. Destination must be provided. For example,\"\n            ' `{ \"dbfs\" : { \"destination\" : \"dbfs:/home/cluster_log\" } }`'\n        ),\n    )\n    s3: Optional[S3StorageInfo] = Field(\n        None,\n        description=(\n            \"S3 location of cluster log. `destination` and either `region` or\"\n            ' `endpoint` must be provided. For example, `{ \"s3\": { \"destination\" :'\n            ' \"s3://cluster_log_bucket/prefix\", \"region\" : \"us-west-2\" } }`'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSize","title":"<code>ClusterSize</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSize(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, parameters needed in order to automatically scale clusters\"\n            \" up and down based on load.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. When reading the properties of a cluster,\"\n            \" this field reflects the desired number of workers rather than the actual\"\n            \" number of workers. For instance, if a cluster is resized from 5 to 10\"\n            \" workers, this field is updated to reflect the target size of 10 workers,\"\n            \" whereas the workers listed in executors gradually increase from 5 to 10\"\n            \" as the new nodes are provisioned.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSource","title":"<code>ClusterSource</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* UI: Cluster created through the UI.\n</code></pre> <ul> <li>JOB: Cluster created by the Databricks job scheduler.</li> <li>API: Cluster created through an API call.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSource(str, Enum):\n    \"\"\"\n        * UI: Cluster created through the UI.\n    * JOB: Cluster created by the Databricks job scheduler.\n    * API: Cluster created through an API call.\n\n    \"\"\"\n\n    ui = \"UI\"\n    job = \"JOB\"\n    api = \"API\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterSpec","title":"<code>ClusterSpec</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterSpec(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this job. When running jobs on an existing cluster, you may need\"\n            \" to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the job. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterState","title":"<code>ClusterState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* PENDING: Indicates that a cluster is in the process of being created.\n</code></pre> <ul> <li>RUNNING: Indicates that a cluster has been started and is ready for use.</li> <li>RESTARTING: Indicates that a cluster is in the process of restarting.</li> <li>RESIZING: Indicates that a cluster is in the process of adding or removing nodes.</li> <li>TERMINATING: Indicates that a cluster is in the process of being destroyed.</li> <li>TERMINATED: Indicates that a cluster has been successfully destroyed.</li> <li>ERROR: This state is no longer used. It was used to indicate a cluster that failed to be created. <code>TERMINATING</code> and <code>TERMINATED</code> are used instead.</li> <li>UNKNOWN: Indicates that a cluster is in an unknown state. A cluster should never be in this state.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterState(str, Enum):\n    \"\"\"\n        * PENDING: Indicates that a cluster is in the process of being created.\n    * RUNNING: Indicates that a cluster has been started and is ready for use.\n    * RESTARTING: Indicates that a cluster is in the process of restarting.\n    * RESIZING: Indicates that a cluster is in the process of adding or removing nodes.\n    * TERMINATING: Indicates that a cluster is in the process of being destroyed.\n    * TERMINATED: Indicates that a cluster has been successfully destroyed.\n    * ERROR: This state is no longer used. It was used to indicate a cluster that failed to be created. `TERMINATING` and `TERMINATED` are used instead.\n    * UNKNOWN: Indicates that a cluster is in an unknown state. A cluster should never be in this state.\n\n    \"\"\"\n\n    pending = \"PENDING\"\n    running = \"RUNNING\"\n    restarting = \"RESTARTING\"\n    resizing = \"RESIZING\"\n    terminating = \"TERMINATING\"\n    terminated = \"TERMINATED\"\n    error = \"ERROR\"\n    unknown = \"UNKNOWN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ClusterTag","title":"<code>ClusterTag</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An object with key value pairs. The key length must be between 1 and 127 UTF-8 characters, inclusive. The value length must be less than or equal to 255 UTF-8 characters. For a list of all restrictions, see AWS Tag Restrictions: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ClusterTag(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An object with key value pairs. The key length must be between 1 and 127 UTF-8 characters, inclusive. The value length must be less than or equal to 255 UTF-8 characters. For a list of all restrictions, see AWS Tag Restrictions: &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions&gt;\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.CronSchedule","title":"<code>CronSchedule</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class CronSchedule(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    pause_status: Optional[Literal[\"PAUSED\", \"UNPAUSED\"]] = Field(\n        None,\n        description=\"Indicate whether this schedule is paused or not.\",\n        example=\"PAUSED\",\n    )\n    quartz_cron_expression: str = Field(\n        ...,\n        description=(\n            \"A Cron expression using Quartz syntax that describes the schedule for a\"\n            \" job. See [Cron\"\n            \" Trigger](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)\"\n            \" for details. This field is required.\"\n        ),\n        example=\"20 30 * * * ?\",\n    )\n    timezone_id: str = Field(\n        ...,\n        description=(\n            \"A Java timezone ID. The schedule for a job is resolved with respect to\"\n            \" this timezone. See [Java\"\n            \" TimeZone](https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html)\"\n            \" for details. This field is required.\"\n        ),\n        example=\"Europe/London\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbfsStorageInfo","title":"<code>DbfsStorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbfsStorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    destination: Optional[str] = Field(\n        None, description=\"DBFS destination. Example: `dbfs:/my/path`\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbtOutput","title":"<code>DbtOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbtOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    artifacts_headers: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"An optional map of headers to send when retrieving the artifact from the\"\n            \" `artifacts_link`.\"\n        ),\n    )\n    artifacts_link: Optional[str] = Field(\n        None,\n        description=(\n            \"A pre-signed URL to download the (compressed) dbt artifacts. This link is\"\n            \" valid for a limited time (30 minutes). This information is only available\"\n            \" after the run has finished.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DbtTask","title":"<code>DbtTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DbtTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    catalog: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional name of the catalog to use. The value is the top level in the\"\n            \" 3-level namespace of Unity Catalog (catalog / schema / relation). The\"\n            \" catalog value can only be specified if a warehouse_id is specified.\"\n            \" Requires dbt-databricks &gt;= 1.1.1.\"\n        ),\n        example=\"main\",\n    )\n    commands: List = Field(\n        ...,\n        description=(\n            \"A list of dbt commands to execute. All commands must start with `dbt`.\"\n            \" This parameter must not be empty. A maximum of up to 10 commands can be\"\n            \" provided.\"\n        ),\n        example=[\"dbt deps\", \"dbt seed\", \"dbt run --models 123\"],\n    )\n    profiles_directory: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional (relative) path to the profiles directory. Can only be specified\"\n            \" if no warehouse_id is specified. If no warehouse_id is specified and this\"\n            \" folder is unset, the root directory is used.\"\n        ),\n    )\n    project_directory: Optional[str] = Field(\n        None,\n        description=(\n            \"Optional (relative) path to the project directory, if no value is\"\n            \" provided, the root of the git repository is used.\"\n        ),\n    )\n    schema_: Optional[str] = Field(\n        None,\n        alias=\"schema\",\n        description=(\n            \"Optional schema to write to. This parameter is only used when a\"\n            \" warehouse_id is also provided. If not provided, the `default` schema is\"\n            \" used.\"\n        ),\n    )\n    warehouse_id: Optional[str] = Field(\n        None,\n        description=(\n            \"ID of the SQL warehouse to connect to. If provided, we automatically\"\n            \" generate and provide the profile and connection details to dbt. It can be\"\n            \" overridden on a per-command basis by using the `--profiles-dir` command\"\n            \" line argument.\"\n        ),\n        example=\"30dade0507d960d1\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DockerBasicAuth","title":"<code>DockerBasicAuth</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DockerBasicAuth(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    password: Optional[str] = Field(\n        None, description=\"Password for the Docker repository.\"\n    )\n    username: Optional[str] = Field(\n        None, description=\"User name for the Docker repository.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.DockerImage","title":"<code>DockerImage</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class DockerImage(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    basic_auth: Optional[DockerBasicAuth] = Field(\n        None, description=\"Basic authentication information for Docker repository.\"\n    )\n    url: Optional[str] = Field(None, description=\"URL for the Docker image.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Error","title":"<code>Error</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Error(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    error_code: Optional[str] = Field(\n        None, description=\"Error code\", example=\"INTERNAL_ERROR\"\n    )\n    message: Optional[str] = Field(\n        None,\n        description=(\n            \"Human-readable error message that describes the cause of the error.\"\n        ),\n        example=\"Unexpected error.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.EventDetails","title":"<code>EventDetails</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class EventDetails(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"* For created clusters, the attributes of the cluster.\\n* For edited\"\n            \" clusters, the new attributes of the cluster.\"\n        ),\n    )\n    cause: Optional[ResizeCause] = Field(\n        None, description=\"The cause of a change in target size.\"\n    )\n    cluster_size: Optional[ClusterSize] = Field(\n        None,\n        description=\"The cluster size that was set in the cluster creation or edit.\",\n    )\n    current_num_workers: Optional[int] = Field(\n        None, description=\"The number of nodes in the cluster.\"\n    )\n    previous_attributes: Optional[AwsAttributes] = Field(\n        None, description=\"The cluster attributes before a cluster was edited.\"\n    )\n    previous_cluster_size: Optional[ClusterSize] = Field(\n        None, description=\"The size of the cluster before an edit or resize.\"\n    )\n    reason: Optional[TerminationReason] = Field(\n        None,\n        description=(\n            \"A termination reason:\\n\\n* On a `TERMINATED` event, the reason for the\"\n            \" termination.\\n* On a `RESIZE_COMPLETE` event, indicates the reason that\"\n            \" we failed to acquire some nodes.\"\n        ),\n    )\n    target_num_workers: Optional[int] = Field(\n        None, description=\"The targeted number of nodes in the cluster.\"\n    )\n    user: Optional[str] = Field(\n        None,\n        description=(\n            \"The user that caused the event to occur. (Empty if it was done by\"\n            \" Databricks.)\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.FileStorageInfo","title":"<code>FileStorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class FileStorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    destination: Optional[str] = Field(\n        None, description=\"File destination. Example: `file:/my/file.sh`\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSnapshot","title":"<code>GitSnapshot</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>Read-only state of the remote repository at the time the job was run. This field is only included on job runs.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSnapshot(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    Read-only state of the remote repository at the time the job was run. This field is only included on job runs.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    used_commit: Optional[str] = Field(\n        None,\n        description=(\n            \"Commit that was used to execute the run. If git_branch was specified, this\"\n            \" points to the HEAD of the branch at the time of the run; if git_tag was\"\n            \" specified, this points to the commit the tag points to.\"\n        ),\n        example=\"4506fdf41e9fa98090570a34df7a5bce163ff15f\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSource","title":"<code>GitSource</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <pre><code>This functionality is in Public Preview.\n</code></pre> <p>An optional specification for a remote repository containing the notebooks used by this job's notebook tasks.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSource(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n        This functionality is in Public Preview.\n\n    An optional specification for a remote repository containing the notebooks used by this job's notebook tasks.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    git_branch: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the branch to be checked out and used by this job. This field\"\n            \" cannot be specified in conjunction with git_tag or git_commit.\\nThe\"\n            \" maximum length is 255 characters.\"\n        ),\n        example=\"main\",\n    )\n    git_commit: Optional[str] = Field(\n        None,\n        description=(\n            \"Commit to be checked out and used by this job. This field cannot be\"\n            \" specified in conjunction with git_branch or git_tag.\\nThe maximum length\"\n            \" is 64 characters.\"\n        ),\n        example=\"e0056d01\",\n    )\n    git_provider: Optional[\n        Literal[\n            \"gitHub\",\n            \"bitbucketCloud\",\n            \"azureDevOpsServices\",\n            \"gitHubEnterprise\",\n            \"bitbucketServer\",\n            \"gitLab\",\n            \"gitLabEnterpriseEdition\",\n            \"awsCodeCommit\",\n        ]\n    ] = Field(\n        None,\n        description=(\n            \"Unique identifier of the service used to host the Git repository. The\"\n            \" value is case insensitive.\"\n        ),\n        example=\"github\",\n    )\n    git_snapshot: Optional[GitSnapshot] = None\n    git_tag: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the tag to be checked out and used by this job. This field cannot\"\n            \" be specified in conjunction with git_branch or git_commit.\\nThe maximum\"\n            \" length is 255 characters.\"\n        ),\n        example=\"release-1.0.0\",\n    )\n    git_url: Optional[str] = Field(\n        None,\n        description=(\n            \"URL of the repository to be cloned by this job.\\nThe maximum length is 300\"\n            \" characters.\"\n        ),\n        example=\"https://github.com/databricks/databricks-cli\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GitSource1","title":"<code>GitSource1</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GitSource1(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[GitSource, Any, Any, Any] = Field(\n        ...,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.GroupName","title":"<code>GroupName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class GroupName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"Group name. There are two built-in groups: `users` for all users, and\"\n            \" `admins` for administrators.\"\n        ),\n        example=\"users\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.InitScriptInfo","title":"<code>InitScriptInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class InitScriptInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    s3: Optional[S3StorageInfo] = Field(\n        None,\n        alias=\"S3\",\n        description=(\n            \"S3 location of init script. Destination and either region or endpoint must\"\n            ' be provided. For example, `{ \"s3\": { \"destination\" :'\n            ' \"s3://init_script_bucket/prefix\", \"region\" : \"us-west-2\" } }`'\n        ),\n    )\n    dbfs: Optional[DbfsStorageInfo] = Field(\n        None,\n        description=(\n            \"DBFS location of init script. Destination must be provided. For example,\"\n            ' `{ \"dbfs\" : { \"destination\" : \"dbfs:/home/init_script\" } }`'\n        ),\n    )\n    file: Optional[FileStorageInfo] = Field(\n        None,\n        description=(\n            \"File location of init script. Destination must be provided. For example,\"\n            ' `{ \"file\" : { \"destination\" : \"file:/my/local/file.sh\" } }`'\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.IsOwner","title":"<code>IsOwner</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Perimssion that represents ownership of the job.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class IsOwner(str, Enum):\n    \"\"\"\n    Perimssion that represents ownership of the job.\n    \"\"\"\n\n    isowner = \"IS_OWNER\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Job","title":"<code>Job</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Job(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    created_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this job was created in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC).\"\n        ),\n        example=1601370337343,\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The creator user name. This field won\u2019t be included in the response if the\"\n            \" user has already been deleted.\"\n        ),\n        example=\"user.name@databricks.com\",\n    )\n    job_id: Optional[int] = Field(\n        None, description=\"The canonical identifier for this job.\", example=11223344\n    )\n    settings: Optional[JobSettings] = Field(\n        None,\n        description=(\n            \"Settings for this job and all of its runs. These settings can be updated\"\n            \" using the `resetJob` method.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobCluster","title":"<code>JobCluster</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobCluster(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    job_cluster_key: str = Field(\n        ...,\n        description=(\n            \"A unique name for the job cluster. This field is required and must be\"\n            \" unique within the job.\\n`JobTaskSettings` may refer to this field to\"\n            \" determine which cluster to launch for the task execution.\"\n        ),\n        example=\"auto_scaling_cluster\",\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n    new_cluster: Optional[NewCluster] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobEmailNotifications","title":"<code>JobEmailNotifications</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobEmailNotifications(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    no_alert_for_skipped_runs: Optional[bool] = Field(\n        None,\n        description=(\n            \"If true, do not send email to recipients specified in `on_failure` if the\"\n            \" run is skipped.\"\n        ),\n        example=False,\n    )\n    on_failure: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to notify when a run completes unsuccessfully. A\"\n            \" run is considered unsuccessful if it ends with an `INTERNAL_ERROR`\"\n            \" `life_cycle_state` or a `SKIPPED`, `FAILED`, or `TIMED_OUT`\"\n            \" `result_state`. If not specified on job creation, reset, or update, or\"\n            \" the list is empty, then notifications are not sent. Job-level failure\"\n            \" notifications are sent only once after the entire job run (including all\"\n            \" of its retries) has failed. Notifications are not sent when failed job\"\n            \" runs are retried. To receive a failure notification after every failed\"\n            \" task (including every failed retry), use task-level notifications\"\n            \" instead.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n    on_start: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to be notified when a run begins. If not\"\n            \" specified on job creation, reset, or update, the list is empty, and\"\n            \" notifications are not sent.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n    on_success: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of email addresses to be notified when a run successfully\"\n            \" completes. A run is considered to have completed successfully if it ends\"\n            \" with a `TERMINATED` `life_cycle_state` and a `SUCCESSFUL` result_state.\"\n            \" If not specified on job creation, reset, or update, the list is empty,\"\n            \" and notifications are not sent.\"\n        ),\n        example=[\"user.name@databricks.com\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobSettings","title":"<code>JobSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    email_notifications: Optional[JobEmailNotifications] = Field(\n        None,\n        description=(\n            \"An optional set of email addresses that is notified when runs of this job\"\n            \" begin or complete as well as when this job is deleted. The default\"\n            \" behavior is to not send any emails.\"\n        ),\n    )\n    format: Optional[Literal[\"SINGLE_TASK\", \"MULTI_TASK\"]] = Field(\n        None,\n        description=(\n            \"Used to tell what is the format of the job. This field is ignored in\"\n            \" Create/Update/Reset calls. When using the Jobs API 2.1 this value is\"\n            ' always set to `\"MULTI_TASK\"`.'\n        ),\n        example=\"MULTI_TASK\",\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    job_clusters: Optional[List[JobCluster]] = Field(\n        None,\n        description=(\n            \"A list of job cluster specifications that can be shared and reused by\"\n            \" tasks of this job. Libraries cannot be declared in a shared job cluster.\"\n            \" You must declare dependent libraries in task settings.\"\n        ),\n        example=[\n            {\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n            }\n        ],\n        max_items=100,\n    )\n    max_concurrent_runs: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional maximum allowed number of concurrent runs of the job.\\n\\nSet\"\n            \" this value if you want to be able to execute multiple runs of the same\"\n            \" job concurrently. This is useful for example if you trigger your job on a\"\n            \" frequent schedule and want to allow consecutive runs to overlap with each\"\n            \" other, or if you want to trigger multiple runs which differ by their\"\n            \" input parameters.\\n\\nThis setting affects only new runs. For example,\"\n            \" suppose the job\u2019s concurrency is 4 and there are 4 concurrent active\"\n            \" runs. Then setting the concurrency to 3 won\u2019t kill any of the active\"\n            \" runs. However, from then on, new runs are skipped unless there are fewer\"\n            \" than 3 active runs.\\n\\nThis value cannot exceed 1000\\\\. Setting this\"\n            \" value to 0 causes all new runs to be skipped. The default behavior is to\"\n            \" allow only 1 concurrent run.\"\n        ),\n        example=10,\n    )\n    name: Optional[str] = Field(\n        \"Untitled\",\n        description=\"An optional name for the job.\",\n        example=\"A multitask job\",\n    )\n    schedule: Optional[CronSchedule] = Field(\n        None,\n        description=(\n            \"An optional periodic schedule for this job. The default behavior is that\"\n            \" the job only runs when triggered by clicking \u201cRun Now\u201d in the Jobs UI or\"\n            \" sending an API request to `runNow`.\"\n        ),\n    )\n    tags: Optional[Dict[str, Any]] = Field(\n        \"{}\",\n        description=(\n            \"A map of tags associated with the job. These are forwarded to the cluster\"\n            \" as cluster tags for jobs clusters, and are subject to the same\"\n            \" limitations as cluster tags. A maximum of 25 tags can be added to the\"\n            \" job.\"\n        ),\n        example={\"cost-center\": \"engineering\", \"team\": \"jobs\"},\n    )\n    tasks: Optional[List[JobTaskSettings]] = Field(\n        None,\n        description=\"A list of task specifications to be executed by this job.\",\n        example=[\n            {\n                \"depends_on\": [],\n                \"description\": \"Extracts session data from events\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"retry_on_timeout\": False,\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.Sessionize\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                },\n                \"task_key\": \"Sessionize\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [],\n                \"description\": \"Ingests order data\",\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"retry_on_timeout\": False,\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.OrdersIngest\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                },\n                \"task_key\": \"Orders_Ingest\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"max_retries\": 3,\n                \"min_retry_interval_millis\": 2000,\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"base_parameters\": {\"age\": \"35\", \"name\": \"John Doe\"},\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"retry_on_timeout\": False,\n                \"task_key\": \"Match\",\n                \"timeout_seconds\": 86400,\n            },\n        ],\n        max_items=100,\n    )\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job. The default behavior\"\n            \" is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when runs of this job\"\n            \" begin or complete. The default behavior is to not send any system\"\n            \" notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobTask","title":"<code>JobTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this job must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this job must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None,\n        description=\"If spark_jar_task, indicates that this job must run a JAR.\",\n        example=\"\",\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this job must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this job must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.JobTaskSettings","title":"<code>JobTaskSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class JobTaskSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    description: Optional[TaskDescription] = None\n    email_notifications: Optional[JobEmailNotifications] = Field(\n        None,\n        description=(\n            \"An optional set of email addresses that is notified when runs of this task\"\n            \" begin or complete as well as when this task is deleted. The default\"\n            \" behavior is to not send any emails.\"\n        ),\n    )\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this task. When running tasks on an existing cluster, you may\"\n            \" need to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    job_cluster_key: Optional[str] = Field(\n        None,\n        description=(\n            \"If job_cluster_key, this task is executed reusing the cluster specified in\"\n            \" `job.settings.job_clusters`.\"\n        ),\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the task. The default value is an empty list.\"\n        ),\n    )\n    max_retries: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional maximum number of times to retry an unsuccessful run. A run is\"\n            \" considered to be unsuccessful if it completes with the `FAILED`\"\n            \" result_state or `INTERNAL_ERROR` `life_cycle_state`. The value -1 means\"\n            \" to retry indefinitely and the value 0 means to never retry. The default\"\n            \" behavior is to never retry.\"\n        ),\n        example=10,\n    )\n    min_retry_interval_millis: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional minimal interval in milliseconds between the start of the\"\n            \" failed run and the subsequent retry run. The default behavior is that\"\n            \" unsuccessful runs are immediately retried.\"\n        ),\n        example=2000,\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this task must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this task must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    retry_on_timeout: Optional[bool] = Field(\n        None,\n        description=(\n            \"An optional policy to specify whether to retry a task when it times out.\"\n            \" The default behavior is to not retry on timeout.\"\n        ),\n        example=True,\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this task must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this task must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this task must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    task_key: TaskKey\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job task. The default\"\n            \" behavior is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when the run begins or\"\n            \" completes. The default behavior is to not send any system notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Library","title":"<code>Library</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Library(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    cran: Optional[RCranLibrary] = Field(\n        None, description=\"If cran, specification of a CRAN library to be installed.\"\n    )\n    egg: Optional[str] = Field(\n        None,\n        description=(\n            \"If egg, URI of the egg to be installed. DBFS and S3 URIs are supported.\"\n            ' For example: `{ \"egg\": \"dbfs:/my/egg\" }` or `{ \"egg\":'\n            ' \"s3://my-bucket/egg\" }`. If S3 is used, make sure the cluster has read'\n            \" access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI.\"\n        ),\n        example=\"dbfs:/my/egg\",\n    )\n    jar: Optional[str] = Field(\n        None,\n        description=(\n            \"If jar, URI of the JAR to be installed. DBFS and S3 URIs are supported.\"\n            ' For example: `{ \"jar\": \"dbfs:/mnt/databricks/library.jar\" }` or `{ \"jar\":'\n            ' \"s3://my-bucket/library.jar\" }`. If S3 is used, make sure the cluster has'\n            \" read access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI.\"\n        ),\n        example=\"dbfs:/my-jar.jar\",\n    )\n    maven: Optional[MavenLibrary] = Field(\n        None,\n        description=(\n            \"If maven, specification of a Maven library to be installed. For example:\"\n            ' `{ \"coordinates\": \"org.jsoup:jsoup:1.7.2\" }`'\n        ),\n    )\n    pypi: Optional[PythonPyPiLibrary] = Field(\n        None,\n        description=(\n            \"If pypi, specification of a PyPI library to be installed. Specifying the\"\n            \" `repo` field is optional and if not specified, the default pip index is\"\n            ' used. For example: `{ \"package\": \"simplejson\", \"repo\":'\n            ' \"https://my-repo.com\" }`'\n        ),\n    )\n    whl: Optional[str] = Field(\n        None,\n        description=(\n            \"If whl, URI of the wheel or zipped wheels to be installed. DBFS and S3\"\n            ' URIs are supported. For example: `{ \"whl\": \"dbfs:/my/whl\" }` or `{ \"whl\":'\n            ' \"s3://my-bucket/whl\" }`. If S3 is used, make sure the cluster has read'\n            \" access on the library. You may need to launch the cluster with an\"\n            \" instance profile to access the S3 URI. Also the wheel file name needs to\"\n            \" use the [correct\"\n            \" convention](https://www.python.org/dev/peps/pep-0427/#file-format). If\"\n            \" zipped wheels are to be installed, the file name suffix should be\"\n            \" `.wheelhouse.zip`.\"\n        ),\n        example=\"dbfs:/my/whl\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LibraryFullStatus","title":"<code>LibraryFullStatus</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LibraryFullStatus(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    is_library_for_all_clusters: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether the library was set to be installed on all clusters via the\"\n            \" libraries UI.\"\n        ),\n    )\n    library: Optional[Library] = Field(\n        None, description=\"Unique identifier for the library.\"\n    )\n    messages: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"All the info and warning messages that have occurred so far for this\"\n            \" library.\"\n        ),\n    )\n    status: Optional[LibraryInstallStatus] = Field(\n        None, description=\"Status of installing the library on the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LibraryInstallStatus","title":"<code>LibraryInstallStatus</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PENDING`: No action has yet been taken to install the library. This state should be very short lived.\n</code></pre> <ul> <li><code>RESOLVING</code>: Metadata necessary to install the library is being retrieved from the provided repository. For Jar, Egg, and Whl libraries, this step is a no-op.</li> <li><code>INSTALLING</code>: The library is actively being installed, either by adding resources to Spark or executing system commands inside the Spark nodes.</li> <li><code>INSTALLED</code>: The library has been successfully instally.</li> <li><code>SKIPPED</code>: Installation on a Databricks Runtime 7.0 or above cluster was skipped due to Scala version incompatibility.</li> <li><code>FAILED</code>: Some step in installation failed. More information can be found in the messages field.</li> <li><code>UNINSTALL_ON_RESTART</code>: The library has been marked for removal. Libraries can be removed only when clusters are restarted, so libraries that enter this state remains until the cluster is restarted.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LibraryInstallStatus(str, Enum):\n    \"\"\"\n        * `PENDING`: No action has yet been taken to install the library. This state should be very short lived.\n    * `RESOLVING`: Metadata necessary to install the library is being retrieved from the provided repository. For Jar, Egg, and Whl libraries, this step is a no-op.\n    * `INSTALLING`: The library is actively being installed, either by adding resources to Spark or executing system commands inside the Spark nodes.\n    * `INSTALLED`: The library has been successfully instally.\n    * `SKIPPED`: Installation on a Databricks Runtime 7.0 or above cluster was skipped due to Scala version incompatibility.\n    * `FAILED`: Some step in installation failed. More information can be found in the messages field.\n    * `UNINSTALL_ON_RESTART`: The library has been marked for removal. Libraries can be removed only when clusters are restarted, so libraries that enter this state remains until the cluster is restarted.\n    \"\"\"\n\n    pending = \"PENDING\"\n    resolving = \"RESOLVING\"\n    installing = \"INSTALLING\"\n    installed = \"INSTALLED\"\n    skipped = \"SKIPPED\"\n    failed = \"FAILED\"\n    uninstallonrestart = \"UNINSTALL_ON_RESTART\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ListOrder","title":"<code>ListOrder</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `DESC`: Descending order.\n</code></pre> <ul> <li><code>ASC</code>: Ascending order.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ListOrder(str, Enum):\n    \"\"\"\n        * `DESC`: Descending order.\n    * `ASC`: Ascending order.\n    \"\"\"\n\n    desc = \"DESC\"\n    asc = \"ASC\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.LogSyncStatus","title":"<code>LogSyncStatus</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class LogSyncStatus(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    last_attempted: Optional[int] = Field(\n        None,\n        description=(\n            \"The timestamp of last attempt. If the last attempt fails, last_exception\"\n            \" contains the exception in the last attempt.\"\n        ),\n    )\n    last_exception: Optional[str] = Field(\n        None,\n        description=(\n            \"The exception thrown in the last attempt, it would be null (omitted in the\"\n            \" response) if there is no exception in last attempted.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.MavenLibrary","title":"<code>MavenLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class MavenLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    coordinates: str = Field(\n        ...,\n        description=(\n            \"Gradle-style Maven coordinates. For example: `org.jsoup:jsoup:1.7.2`. This\"\n            \" field is required.\"\n        ),\n        example=\"org.jsoup:jsoup:1.7.2\",\n    )\n    exclusions: Optional[List[str]] = Field(\n        None,\n        description=(\n            'List of dependences to exclude. For example: `[\"slf4j:slf4j\",'\n            ' \"*:hadoop-client\"]`.\\n\\nMaven dependency exclusions:'\n            \" &lt;https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html&gt;.\"\n        ),\n        example=[\"slf4j:slf4j\", \"*:hadoop-client\"],\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"Maven repo to install the Maven package from. If omitted, both Maven\"\n            \" Central Repository and Spark Packages are searched.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NewCluster","title":"<code>NewCluster</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NewCluster(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    autoscale: Optional[AutoScale] = Field(\n        None,\n        description=(\n            \"If autoscale, the required parameters to automatically scale clusters up\"\n            \" and down based on load.\"\n        ),\n    )\n    aws_attributes: Optional[AwsAttributes] = Field(\n        None,\n        description=(\n            \"Attributes related to clusters running on Amazon Web Services. If not\"\n            \" specified at cluster creation, a set of default values is used.\"\n        ),\n    )\n    cluster_log_conf: Optional[ClusterLogConf] = Field(\n        None,\n        description=(\n            \"The configuration for delivering Spark logs to a long-term storage\"\n            \" destination. Only one destination can be specified for one cluster. If\"\n            \" the conf is given, the logs are delivered to the destination every `5\"\n            \" mins`. The destination of driver logs is\"\n            \" `&lt;destination&gt;/&lt;cluster-id&gt;/driver`, while the destination of executor\"\n            \" logs is `&lt;destination&gt;/&lt;cluster-id&gt;/executor`.\"\n        ),\n    )\n    custom_tags: Optional[ClusterTag] = Field(\n        None,\n        description=(\n            \"An object containing a set of tags for cluster resources. Databricks tags\"\n            \" all cluster resources (such as AWS instances and EBS volumes) with these\"\n            \" tags in addition to default_tags.\\n\\n**Note**:\\n\\n* Tags are not\"\n            \" supported on legacy node types such as compute-optimized and\"\n            \" memory-optimized\\n* Databricks allows at most 45 custom tags\"\n        ),\n    )\n    driver_instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to use for the driver node. You must\"\n            \" also specify `instance_pool_id`. Refer to [Instance Pools\"\n            \" API](https://docs.databricks.com/dev-tools/api/latest/instance-pools.html)\"\n            \" for details.\"\n        ),\n    )\n    driver_node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The node type of the Spark driver. This field is optional; if unset, the\"\n            \" driver node type is set as the same value as `node_type_id` defined\"\n            \" above.\"\n        ),\n    )\n    enable_elastic_disk: Optional[bool] = Field(\n        None,\n        description=(\n            \"Autoscaling Local Storage: when enabled, this cluster dynamically acquires\"\n            \" additional disk space when its Spark workers are running low on disk\"\n            \" space. This feature requires specific AWS permissions to function\"\n            \" correctly - refer to [Autoscaling local\"\n            \" storage](https://docs.databricks.com/clusters/configure.html#autoscaling-local-storage)\"\n            \" for details.\"\n        ),\n    )\n    enable_local_disk_encryption: Optional[bool] = Field(\n        None,\n        description=(\n            \"Determines whether encryption of disks locally attached to the cluster is\"\n            \" enabled.\"\n        ),\n    )\n    init_scripts: Optional[List[InitScriptInfo]] = Field(\n        None,\n        description=(\n            \"The configuration for storing init scripts. Any number of scripts can be\"\n            \" specified. The scripts are executed sequentially in the order provided.\"\n            \" If `cluster_log_conf` is specified, init script logs are sent to\"\n            \" `&lt;destination&gt;/&lt;cluster-id&gt;/init_scripts`.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None,\n        description=(\n            \"The optional ID of the instance pool to use for cluster nodes. If\"\n            \" `driver_instance_pool_id` is present, `instance_pool_id` is used for\"\n            \" worker nodes only. Otherwise, it is used for both the driver node and\"\n            \" worker nodes. Refer to [Instance Pools\"\n            \" API](https://docs.databricks.com/dev-tools/api/latest/instance-pools.html)\"\n            \" for details.\"\n        ),\n    )\n    node_type_id: Optional[str] = Field(\n        None,\n        description=(\n            \"This field encodes, through a single value, the resources available to\"\n            \" each of the Spark nodes in this cluster. For example, the Spark nodes can\"\n            \" be provisioned and optimized for memory or compute intensive workloads A\"\n            \" list of available node types can be retrieved by using the [List node\"\n            \" types](https://docs.databricks.com/dev-tools/api/latest/clusters.html#list-node-types)\"\n            \" API call.\"\n        ),\n    )\n    num_workers: Optional[int] = Field(\n        None,\n        description=(\n            \"If num_workers, number of worker nodes that this cluster must have. A\"\n            \" cluster has one Spark driver and num_workers executors for a total of\"\n            \" num_workers + 1 Spark nodes. When reading the properties of a cluster,\"\n            \" this field reflects the desired number of workers rather than the actual\"\n            \" current number of workers. For example, if a cluster is resized from 5 to\"\n            \" 10 workers, this field immediately updates to reflect the target size of\"\n            \" 10 workers, whereas the workers listed in `spark_info` gradually increase\"\n            \" from 5 to 10 as the new nodes are provisioned.\"\n        ),\n    )\n    policy_id: Optional[str] = Field(\n        None,\n        description=(\n            \"A [cluster\"\n            \" policy](https://docs.databricks.com/dev-tools/api/latest/policies.html)\"\n            \" ID. Either `node_type_id` or `instance_pool_id` must be specified in the\"\n            \" cluster policy if they are not specified in this job cluster object.\"\n        ),\n    )\n    spark_conf: Optional[SparkConfPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified Spark configuration\"\n            \" key-value pairs. You can also pass in a string of extra JVM options to\"\n            \" the driver and the executors via `spark.driver.extraJavaOptions` and\"\n            \" `spark.executor.extraJavaOptions` respectively.\\n\\nExample Spark confs:\"\n            ' `{\"spark.speculation\": true, \"spark.streaming.ui.retainedBatches\": 5}` or'\n            ' `{\"spark.driver.extraJavaOptions\": \"-verbose:gc -XX:+PrintGCDetails\"}`'\n        ),\n    )\n    spark_env_vars: Optional[SparkEnvPair] = Field(\n        None,\n        description=(\n            \"An object containing a set of optional, user-specified environment\"\n            \" variable key-value pairs. Key-value pair of the form (X,Y) are exported\"\n            \" as is (for example, `export X='Y'`) while launching the driver and\"\n            \" workers.\\n\\nTo specify an additional set of `SPARK_DAEMON_JAVA_OPTS`, we\"\n            \" recommend appending them to `$SPARK_DAEMON_JAVA_OPTS` as shown in the\"\n            \" following example. This ensures that all default databricks managed\"\n            \" environmental variables are included as well.\\n\\nExample Spark\"\n            ' environment variables: `{\"SPARK_WORKER_MEMORY\": \"28000m\",'\n            ' \"SPARK_LOCAL_DIRS\": \"/local_disk0\"}` or `{\"SPARK_DAEMON_JAVA_OPTS\":'\n            ' \"$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true\"}`'\n        ),\n    )\n    spark_version: str = Field(\n        ...,\n        description=(\n            \"The Spark version of the cluster. A list of available Spark versions can\"\n            \" be retrieved by using the [Runtime\"\n            \" versions](https://docs.databricks.com/dev-tools/api/latest/clusters.html#runtime-versions)\"\n            \" API call.\"\n        ),\n    )\n    ssh_public_keys: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"SSH public key contents that are added to each Spark node in this cluster.\"\n            \" The corresponding private keys can be used to login with the user name\"\n            \" `ubuntu` on port `2200`. Up to 10 keys can be specified.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NodeType","title":"<code>NodeType</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NodeType(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    description: str = Field(\n        ...,\n        description=(\n            \"A string description associated with this node type. This field is\"\n            \" required.\"\n        ),\n    )\n    instance_type_id: str = Field(\n        ...,\n        description=(\n            \"An identifier for the type of hardware that this node runs on. This field\"\n            \" is required.\"\n        ),\n    )\n    is_deprecated: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether the node type is deprecated. Non-deprecated node types offer\"\n            \" greater performance.\"\n        ),\n    )\n    memory_mb: int = Field(\n        ...,\n        description=(\n            \"Memory (in MB) available for this node type. This field is required.\"\n        ),\n    )\n    node_info: Optional[ClusterCloudProviderNodeInfo] = Field(\n        None, description=\"Node type info reported by the cloud provider.\"\n    )\n    node_type_id: str = Field(\n        ..., description=\"Unique identifier for this node type. This field is required.\"\n    )\n    num_cores: Optional[float] = Field(\n        None,\n        description=(\n            \"Number of CPU cores available for this node type. This can be fractional\"\n            \" if the number of cores on a machine instance is not divisible by the\"\n            \" number of Spark nodes on that machine. This field is required.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NotebookOutput","title":"<code>NotebookOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NotebookOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    result: Optional[str] = Field(\n        None,\n        description=(\n            \"The value passed to\"\n            \" [dbutils.notebook.exit()](https://docs.databricks.com/notebooks/notebook-workflows.html#notebook-workflows-exit).\"\n            \" Databricks restricts this API to return the first 5 MB of the value. For\"\n            \" a larger result, your job can store the results in a cloud storage\"\n            \" service. This field is absent if `dbutils.notebook.exit()` was never\"\n            \" called.\"\n        ),\n        example=\"An arbitrary string passed by calling dbutils.notebook.exit(...)\",\n    )\n    truncated: Optional[bool] = Field(\n        None, description=\"Whether or not the result was truncated.\", example=False\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.NotebookTask","title":"<code>NotebookTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class NotebookTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    base_parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Base parameters to be used for each run of this job. If the run is\"\n            \" initiated by a call to\"\n            \" [`run-now`](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunNow)\"\n            \" with parameters specified, the two parameters maps are merged. If the\"\n            \" same key is specified in `base_parameters` and in `run-now`, the value\"\n            \" from `run-now` is used.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\\n\\nIf the notebook\"\n            \" takes a parameter that is not specified in the job\u2019s `base_parameters` or\"\n            \" the `run-now` override parameters, the default value from the notebook is\"\n            \" used.\\n\\nRetrieve these parameters in a notebook using\"\n            \" [dbutils.widgets.get](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-widgets).\"\n        ),\n        example={\"age\": 35, \"name\": \"John Doe\"},\n    )\n    notebook_path: str = Field(\n        ...,\n        description=(\n            \"The path of the notebook to be run in the Databricks workspace or remote\"\n            \" repository. For notebooks stored in the Databricks workspace, the path\"\n            \" must be absolute and begin with a slash. For notebooks stored in a remote\"\n            \" repository, the path must be relative. This field is required.\"\n        ),\n        example=\"/Users/user.name@databricks.com/notebook_to_run\",\n    )\n    source: Optional[Literal[\"WORKSPACE\", \"GIT\"]] = Field(\n        None,\n        description=(\n            \"Optional location type of the notebook. When set to `WORKSPACE`, the\"\n            \" notebook will be retrieved from the local Databricks workspace. When set\"\n            \" to `GIT`, the notebook will be retrieved from a Git repository defined in\"\n            \" `git_source`. If the value is empty, the task will use `GIT` if\"\n            \" `git_source` is defined and `WORKSPACE` otherwise.\"\n        ),\n        example=\"WORKSPACE\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnFailureItem","title":"<code>OnFailureItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnFailureItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnStartItem","title":"<code>OnStartItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnStartItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.OnSucces","title":"<code>OnSucces</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class OnSucces(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    id: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ParameterPair","title":"<code>ParameterPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An object with additional information about why a cluster was terminated. The object keys are one of <code>TerminationParameter</code> and the value is the termination information.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ParameterPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An object with additional information about why a cluster was terminated. The object keys are one of `TerminationParameter` and the value is the termination information.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PermissionLevel","title":"<code>PermissionLevel</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PermissionLevel(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[CanManage, CanManageRun, CanView, IsOwner] = Field(\n        ..., description=\"Permission level to grant.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PermissionLevelForGroup","title":"<code>PermissionLevelForGroup</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PermissionLevelForGroup(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: Union[CanManage, CanManageRun, CanView] = Field(\n        ..., description=\"Permission level to grant.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PipelineParams","title":"<code>PipelineParams</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PipelineParams(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    full_refresh: Optional[bool] = Field(\n        None, description=\"If true, triggers a full refresh on the delta live table.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PipelineTask","title":"<code>PipelineTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PipelineTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    full_refresh: Optional[bool] = Field(\n        False,\n        description=(\n            \"If true, a full refresh will be triggered on the delta live table.\"\n        ),\n    )\n    pipeline_id: Optional[str] = Field(\n        None,\n        description=\"The full name of the pipeline task to execute.\",\n        example=\"a12cd3e4-0ab1-1abc-1a2b-1a2bcd3e4fg5\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PoolClusterTerminationCode","title":"<code>PoolClusterTerminationCode</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.\n</code></pre> <ul> <li>INSTANCE_POOL_NOT_FOUND_FAILURE: The pool specified by the cluster is no longer active or doesn\u2019t exist.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PoolClusterTerminationCode(str, Enum):\n    \"\"\"\n        * INSTANCE_POOL_MAX_CAPACITY_FAILURE: The pool max capacity has been reached.\n    * INSTANCE_POOL_NOT_FOUND_FAILURE: The pool specified by the cluster is no longer active or doesn\u2019t exist.\n    \"\"\"\n\n    instancepoolmaxcapacityfailure = \"INSTANCE_POOL_MAX_CAPACITY_FAILURE\"\n    instancepoolnotfoundfailure = \"INSTANCE_POOL_NOT_FOUND_FAILURE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PythonPyPiLibrary","title":"<code>PythonPyPiLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PythonPyPiLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    package: str = Field(\n        ...,\n        description=(\n            \"The name of the PyPI package to install. An optional exact version\"\n            \" specification is also supported. Examples: `simplejson` and\"\n            \" `simplejson==3.8.0`. This field is required.\"\n        ),\n        example=\"simplejson==3.8.0\",\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"The repository where the package can be found. If not specified, the\"\n            \" default pip index is used.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.PythonWheelTask","title":"<code>PythonWheelTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class PythonWheelTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    entry_point: Optional[str] = Field(\n        None,\n        description=(\n            \"Named entry point to use, if it does not exist in the metadata of the\"\n            \" package it executes the function from the package directly using\"\n            \" `$packageName.$entryPoint()`\"\n        ),\n    )\n    named_parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to Python wheel task in the form of\"\n            ' `[\"--name=task\", \"--data=dbfs:/path/to/data.json\"]`. Leave it empty if'\n            \" `parameters` is not null.\"\n        ),\n        example={\"data\": \"dbfs:/path/to/data.json\", \"name\": \"task\"},\n    )\n    package_name: Optional[str] = Field(\n        None, description=\"Name of the package to execute\"\n    )\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to Python wheel task. Leave it empty if\"\n            \" `named_parameters` is not null.\"\n        ),\n        example=[\"--name=task\", \"one\", \"two\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RCranLibrary","title":"<code>RCranLibrary</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RCranLibrary(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    package: str = Field(\n        ...,\n        description=\"The name of the CRAN package to install. This field is required.\",\n        example=\"geojson\",\n    )\n    repo: Optional[str] = Field(\n        None,\n        description=(\n            \"The repository where the package can be found. If not specified, the\"\n            \" default CRAN repo is used.\"\n        ),\n        example=\"https://my-repo.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairHistory","title":"<code>RepairHistory</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairHistory(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    repair_history: Optional[List[RepairHistoryItem]] = Field(\n        None, description=\"The repair history of the run.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairHistoryItem","title":"<code>RepairHistoryItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairHistoryItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    end_time: Optional[int] = Field(\n        None, description=\"The end time of the (repaired) run.\", example=1625060863413\n    )\n    id: Optional[int] = Field(\n        None,\n        description=(\n            \"The ID of the repair. Only returned for the items that represent a repair\"\n            \" in `repair_history`.\"\n        ),\n        example=734650698524280,\n    )\n    start_time: Optional[int] = Field(\n        None, description=\"The start time of the (repaired) run.\", example=1625060460483\n    )\n    state: Optional[RunState] = None\n    task_run_ids: Optional[List[int]] = Field(\n        None,\n        description=(\n            \"The run IDs of the task runs that ran as part of this repair history item.\"\n        ),\n        example=[1106460542112844, 988297789683452],\n    )\n    type: Optional[Literal[\"ORIGINAL\", \"REPAIR\"]] = Field(\n        None,\n        description=(\n            \"The repair history item type. Indicates whether a run is the original run\"\n            \" or a repair run.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RepairRunInput","title":"<code>RepairRunInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RepairRunInput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    latest_repair_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The ID of the latest repair. This parameter is not required when repairing\"\n            \" a run for the first time, but must be provided on subsequent requests to\"\n            \" repair the same run.\"\n        ),\n        example=734650698524280,\n    )\n    rerun_all_failed_tasks: Optional[bool] = Field(\n        False,\n        description=(\n            \"If true, repair all failed tasks. Only one of rerun_tasks or\"\n            \" rerun_all_failed_tasks can be used.\"\n        ),\n    )\n    rerun_tasks: Optional[List[str]] = Field(\n        None,\n        description=\"The task keys of the task runs to repair.\",\n        example=[\"task0\", \"task1\"],\n    )\n    run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The job run ID of the run to repair. The run must not be in progress.\"\n        ),\n        example=455644833,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ResizeCause","title":"<code>ResizeCause</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `AUTOSCALE`: Automatically resized based on load.\n</code></pre> <ul> <li><code>USER_REQUEST</code>: User requested a new size.</li> <li><code>AUTORECOVERY</code>: Autorecovery monitor resized the cluster after it lost a node.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ResizeCause(str, Enum):\n    \"\"\"\n        * `AUTOSCALE`: Automatically resized based on load.\n    * `USER_REQUEST`: User requested a new size.\n    * `AUTORECOVERY`: Autorecovery monitor resized the cluster after it lost a node.\n    \"\"\"\n\n    autoscale = \"AUTOSCALE\"\n    userrequest = \"USER_REQUEST\"\n    autorecovery = \"AUTORECOVERY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.Run","title":"<code>Run</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class Run(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attempt_number: Optional[int] = Field(\n        None,\n        description=(\n            \"The sequence number of this run attempt for a triggered job run. The\"\n            \" initial attempt of a run has an attempt_number of 0\\\\. If the initial run\"\n            \" attempt fails, and the job has a retry policy (`max_retries` \\\\&gt; 0),\"\n            \" subsequent runs are created with an `original_attempt_run_id` of the\"\n            \" original attempt\u2019s ID and an incrementing `attempt_number`. Runs are\"\n            \" retried only until they succeed, and the maximum `attempt_number` is the\"\n            \" same as the `max_retries` value for the job.\"\n        ),\n        example=0,\n    )\n    cleanup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to terminate the cluster and clean up any\"\n            \" associated artifacts. The total duration of the run is the sum of the\"\n            \" setup_duration, the execution_duration, and the cleanup_duration.\"\n        ),\n        example=0,\n    )\n    cluster_instance: Optional[ClusterInstance] = Field(\n        None,\n        description=(\n            \"The cluster used for this run. If the run is specified to use a new\"\n            \" cluster, this field is set once the Jobs service has requested a cluster\"\n            \" for the run.\"\n        ),\n    )\n    cluster_spec: Optional[ClusterSpec] = Field(\n        None,\n        description=(\n            \"A snapshot of the job\u2019s cluster specification when this run was created.\"\n        ),\n    )\n    creator_user_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The creator user name. This field won\u2019t be included in the response if the\"\n            \" user has already been deleted.\"\n        ),\n        example=\"user.name@databricks.com\",\n    )\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run ended in epoch milliseconds (milliseconds since\"\n            \" 1/1/1970 UTC). This field is set to 0 if the job is still running.\"\n        ),\n        example=1625060863413,\n    )\n    execution_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to execute the commands in the JAR or\"\n            \" notebook until they completed, failed, timed out, were cancelled, or\"\n            \" encountered an unexpected error.\"\n        ),\n        example=0,\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    job_clusters: Optional[List[JobCluster]] = Field(\n        None,\n        description=(\n            \"A list of job cluster specifications that can be shared and reused by\"\n            \" tasks of this job. Libraries cannot be declared in a shared job cluster.\"\n            \" You must declare dependent libraries in task settings.\"\n        ),\n        example=[\n            {\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n            }\n        ],\n        max_items=100,\n    )\n    job_id: Optional[int] = Field(\n        None,\n        description=\"The canonical identifier of the job that contains this run.\",\n        example=11223344,\n    )\n    number_in_job: Optional[int] = Field(\n        None,\n        deprecated=True,\n        description=(\n            \"A unique identifier for this job run. This is set to the same value as\"\n            \" `run_id`.\"\n        ),\n        example=455644833,\n    )\n    original_attempt_run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"If this run is a retry of a prior run attempt, this field contains the\"\n            \" run_id of the original attempt; otherwise, it is the same as the run_id.\"\n        ),\n        example=455644833,\n    )\n    overriding_parameters: Optional[RunParameters] = Field(\n        None, description=\"The parameters used for this run.\"\n    )\n    run_id: Optional[int] = Field(\n        None,\n        description=(\n            \"The canonical identifier of the run. This ID is unique across all runs of\"\n            \" all jobs.\"\n        ),\n        example=455644833,\n    )\n    run_name: Optional[str] = Field(\n        \"Untitled\",\n        description=(\n            \"An optional name for the run. The maximum allowed length is 4096 bytes in\"\n            \" UTF-8 encoding.\"\n        ),\n        example=\"A multitask job run\",\n    )\n    run_page_url: Optional[str] = Field(\n        None,\n        description=\"The URL to the detail page of the run.\",\n        example=\"https://my-workspace.cloud.databricks.com/#job/11223344/run/123\",\n    )\n    run_type: Optional[RunType] = None\n    schedule: Optional[CronSchedule] = Field(\n        None,\n        description=(\n            \"The cron schedule that triggered this run if it was triggered by the\"\n            \" periodic scheduler.\"\n        ),\n    )\n    setup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time it took to set up the cluster in milliseconds. For runs that run\"\n            \" on new clusters this is the cluster creation time, for runs that run on\"\n            \" existing clusters this time should be very short.\"\n        ),\n        example=0,\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run was started in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC). This may not be the time when the job task starts\"\n            \" executing, for example, if the job is scheduled to run on a new cluster,\"\n            \" this is the time the cluster creation call is issued.\"\n        ),\n        example=1625060460483,\n    )\n    state: Optional[RunState] = Field(\n        None, description=\"The result and lifecycle states of the run.\"\n    )\n    tasks: Optional[List[RunTask]] = Field(\n        None,\n        description=(\n            \"The list of tasks performed by the run. Each task has its own `run_id`\"\n            \" which you can use to call `JobsGetOutput` to retrieve the run resutls.\"\n        ),\n        example=[\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\n                    \"cluster_id\": \"0923-164208-meows279\",\n                    \"spark_context_id\": \"4348585301701786933\",\n                },\n                \"description\": \"Ingests order data\",\n                \"end_time\": 1629989930171,\n                \"execution_duration\": 0,\n                \"job_cluster_key\": \"auto_scaling_cluster\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"run_id\": 2112892,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/20\"\n                ),\n                \"setup_duration\": 0,\n                \"spark_jar_task\": {\"main_class_name\": \"com.databricks.OrdersIngest\"},\n                \"start_time\": 1629989929660,\n                \"state\": {\n                    \"life_cycle_state\": \"INTERNAL_ERROR\",\n                    \"result_state\": \"FAILED\",\n                    \"state_message\": (\n                        \"Library installation failed for library due to user error.\"\n                        \" Error messages:\\n'Manage' permissions are required to install\"\n                        \" libraries on a cluster\"\n                    ),\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Orders_Ingest\",\n            },\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\"cluster_id\": \"0923-164208-meows279\"},\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"end_time\": 1629989930238,\n                \"execution_duration\": 0,\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"run_id\": 2112897,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/21\"\n                ),\n                \"setup_duration\": 0,\n                \"start_time\": 0,\n                \"state\": {\n                    \"life_cycle_state\": \"SKIPPED\",\n                    \"state_message\": \"An upstream task failed.\",\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Match\",\n            },\n            {\n                \"attempt_number\": 0,\n                \"cleanup_duration\": 0,\n                \"cluster_instance\": {\n                    \"cluster_id\": \"0923-164208-meows279\",\n                    \"spark_context_id\": \"4348585301701786933\",\n                },\n                \"description\": \"Extracts session data from events\",\n                \"end_time\": 1629989930144,\n                \"execution_duration\": 0,\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"run_id\": 2112902,\n                \"run_page_url\": (\n                    \"https://my-workspace.cloud.databricks.com/#job/39832/run/22\"\n                ),\n                \"setup_duration\": 0,\n                \"spark_jar_task\": {\"main_class_name\": \"com.databricks.Sessionize\"},\n                \"start_time\": 1629989929668,\n                \"state\": {\n                    \"life_cycle_state\": \"INTERNAL_ERROR\",\n                    \"result_state\": \"FAILED\",\n                    \"state_message\": (\n                        \"Library installation failed for library due to user error.\"\n                        \" Error messages:\\n'Manage' permissions are required to install\"\n                        \" libraries on a cluster\"\n                    ),\n                    \"user_cancelled_or_timedout\": False,\n                },\n                \"task_key\": \"Sessionize\",\n            },\n        ],\n        max_items=100,\n    )\n    trigger: Optional[TriggerType] = Field(\n        None, description=\"The type of trigger that fired this run.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunLifeCycleState","title":"<code>RunLifeCycleState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PENDING`: The run has been triggered. If there is not already an active run of the same job, the cluster and execution context are being prepared. If there is already an active run of the same job, the run immediately transitions into the `SKIPPED` state without preparing any resources.\n</code></pre> <ul> <li><code>RUNNING</code>: The task of this run is being executed.</li> <li><code>TERMINATING</code>: The task of this run has completed, and the cluster and execution context are being cleaned up.</li> <li><code>TERMINATED</code>: The task of this run has completed, and the cluster and execution context have been cleaned up. This state is terminal.</li> <li><code>SKIPPED</code>: This run was aborted because a previous run of the same job was already active. This state is terminal.</li> <li><code>INTERNAL_ERROR</code>: An exceptional state that indicates a failure in the Jobs service, such as network failure over a long period. If a run on a new cluster ends in the <code>INTERNAL_ERROR</code> state, the Jobs service terminates the cluster as soon as possible. This state is terminal.</li> <li><code>BLOCKED</code>: The run is blocked on an upstream dependency.</li> <li><code>WAITING_FOR_RETRY</code>: The run is waiting for a retry.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunLifeCycleState(str, Enum):\n    \"\"\"\n        * `PENDING`: The run has been triggered. If there is not already an active run of the same job, the cluster and execution context are being prepared. If there is already an active run of the same job, the run immediately transitions into the `SKIPPED` state without preparing any resources.\n    * `RUNNING`: The task of this run is being executed.\n    * `TERMINATING`: The task of this run has completed, and the cluster and execution context are being cleaned up.\n    * `TERMINATED`: The task of this run has completed, and the cluster and execution context have been cleaned up. This state is terminal.\n    * `SKIPPED`: This run was aborted because a previous run of the same job was already active. This state is terminal.\n    * `INTERNAL_ERROR`: An exceptional state that indicates a failure in the Jobs service, such as network failure over a long period. If a run on a new cluster ends in the `INTERNAL_ERROR` state, the Jobs service terminates the cluster as soon as possible. This state is terminal.\n    * `BLOCKED`: The run is blocked on an upstream dependency.\n    * `WAITING_FOR_RETRY`: The run is waiting for a retry.\n    \"\"\"\n\n    terminated = \"TERMINATED\"\n    pending = \"PENDING\"\n    running = \"RUNNING\"\n    terminating = \"TERMINATING\"\n    skipped = \"SKIPPED\"\n    internalerror = \"INTERNAL_ERROR\"\n    blocked = \"BLOCKED\"\n    waitingforretry = \"WAITING_FOR_RETRY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunNowInput","title":"<code>RunNowInput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunNowInput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    idempotency_token: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional token to guarantee the idempotency of job run requests. If a\"\n            \" run with the provided token already exists, the request does not create a\"\n            \" new run but returns the ID of the existing run instead. If a run with the\"\n            \" provided token is deleted, an error is returned.\\n\\nIf you specify the\"\n            \" idempotency token, upon failure you can retry until the request succeeds.\"\n            \" Databricks guarantees that exactly one run is launched with that\"\n            \" idempotency token.\\n\\nThis token must have at most 64 characters.\\n\\nFor\"\n            \" more information, see [How to ensure idempotency for\"\n            \" jobs](https://kb.databricks.com/jobs/jobs-idempotency.html).\"\n        ),\n        example=\"8f018174-4792-40d5-bcbc-3e6a527352c8\",\n    )\n    job_id: Optional[int] = Field(\n        None, description=\"The ID of the job to be executed\", example=11223344\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunParameters","title":"<code>RunParameters</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunParameters(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_commands: Optional[List] = Field(\n        None,\n        description=(\n            \"An array of commands to execute for jobs with the dbt task, for example\"\n            ' `\"dbt_commands\": [\"dbt deps\", \"dbt seed\", \"dbt run\"]`'\n        ),\n        example=[\"dbt deps\", \"dbt seed\", \"dbt run\"],\n    )\n    jar_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with Spark JAR tasks, for example\"\n            ' `\"jar_params\": [\"john doe\", \"35\"]`. The parameters are used to invoke the'\n            \" main function of the main class specified in the Spark JAR task. If not\"\n            \" specified upon `run-now`, it defaults to an empty list. jar_params cannot\"\n            \" be specified in conjunction with notebook_params. The JSON representation\"\n            ' of this field (for example `{\"jar_params\":[\"john doe\",\"35\"]}`) cannot'\n            \" exceed 10,000 bytes.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"john\", \"doe\", \"35\"],\n    )\n    notebook_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"A map from keys to values for jobs with notebook task, for example\"\n            ' `\"notebook_params\": {\"name\": \"john doe\", \"age\": \"35\"}`. The map is passed'\n            \" to the notebook and is accessible through the\"\n            \" [dbutils.widgets.get](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-widgets)\"\n            \" function.\\n\\nIf not specified upon `run-now`, the triggered run uses the\"\n            \" job\u2019s base parameters.\\n\\nnotebook_params cannot be specified in\"\n            \" conjunction with jar_params.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\\n\\nThe JSON\"\n            \" representation of this field (for example\"\n            ' `{\"notebook_params\":{\"name\":\"john doe\",\"age\":\"35\"}}`) cannot exceed'\n            \" 10,000 bytes.\"\n        ),\n        example={\"age\": \"35\", \"name\": \"john doe\"},\n    )\n    pipeline_params: Optional[PipelineParams] = None\n    python_named_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"A map from keys to values for jobs with Python wheel task, for example\"\n            ' `\"python_named_params\": {\"name\": \"task\", \"data\":'\n            ' \"dbfs:/path/to/data.json\"}`.'\n        ),\n        example={\"data\": \"dbfs:/path/to/data.json\", \"name\": \"task\"},\n    )\n    python_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with Python tasks, for example\"\n            ' `\"python_params\": [\"john doe\", \"35\"]`. The parameters are passed to'\n            \" Python file as command-line parameters. If specified upon `run-now`, it\"\n            \" would overwrite the parameters specified in job setting. The JSON\"\n            ' representation of this field (for example `{\"python_params\":[\"john'\n            ' doe\",\"35\"]}`) cannot exceed 10,000 bytes.\\n\\nUse [Task parameter'\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job\"\n            \" runs.\\n\\nImportant\\n\\nThese parameters accept only Latin characters\"\n            \" (ASCII character set). Using non-ASCII characters returns an error.\"\n            \" Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis,\"\n            \" and emojis.\"\n        ),\n        example=[\"john doe\", \"35\"],\n    )\n    spark_submit_params: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"A list of parameters for jobs with spark submit task, for example\"\n            ' `\"spark_submit_params\": [\"--class\",'\n            ' \"org.apache.spark.examples.SparkPi\"]`. The parameters are passed to'\n            \" spark-submit script as command-line parameters. If specified upon\"\n            \" `run-now`, it would overwrite the parameters specified in job setting.\"\n            \" The JSON representation of this field (for example\"\n            ' `{\"python_params\":[\"john doe\",\"35\"]}`) cannot exceed 10,000 bytes.\\n\\nUse'\n            \" [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job\"\n            \" runs.\\n\\nImportant\\n\\nThese parameters accept only Latin characters\"\n            \" (ASCII character set). Using non-ASCII characters returns an error.\"\n            \" Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis,\"\n            \" and emojis.\"\n        ),\n        example=[\"--class\", \"org.apache.spark.examples.SparkPi\"],\n    )\n    sql_params: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            'A map from keys to values for SQL tasks, for example `\"sql_params\":'\n            ' {\"name\": \"john doe\", \"age\": \"35\"}`. The SQL alert task does not support'\n            \" custom parameters.\"\n        ),\n        example={\"age\": \"35\", \"name\": \"john doe\"},\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunResultState","title":"<code>RunResultState</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `SUCCESS`: The task completed successfully.\n</code></pre> <ul> <li><code>FAILED</code>: The task completed with an error.</li> <li><code>TIMEDOUT</code>: The run was stopped after reaching the timeout.</li> <li><code>CANCELED</code>: The run was canceled at user request.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunResultState(str, Enum):\n    \"\"\"\n        * `SUCCESS`: The task completed successfully.\n    * `FAILED`: The task completed with an error.\n    * `TIMEDOUT`: The run was stopped after reaching the timeout.\n    * `CANCELED`: The run was canceled at user request.\n    \"\"\"\n\n    success = \"SUCCESS\"\n    failed = \"FAILED\"\n    timedout = \"TIMEDOUT\"\n    canceled = \"CANCELED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunState","title":"<code>RunState</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>The result and lifecycle state of the run.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunState(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    The result and lifecycle state of the run.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    life_cycle_state: Optional[RunLifeCycleState] = Field(\n        None,\n        description=(\n            \"A description of a run\u2019s current location in the run lifecycle. This field\"\n            \" is always available in the response.\"\n        ),\n    )\n    result_state: Optional[RunResultState] = None\n    state_message: Optional[str] = Field(\n        None,\n        description=(\n            \"A descriptive message for the current state. This field is unstructured,\"\n            \" and its exact format is subject to change.\"\n        ),\n        example=\"\",\n    )\n    user_cancelled_or_timedout: Optional[bool] = Field(\n        None,\n        description=(\n            \"Whether a run was canceled manually by a user or by the scheduler because\"\n            \" the run timed out.\"\n        ),\n        example=False,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunSubmitSettings","title":"<code>RunSubmitSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunSubmitSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    idempotency_token: Optional[str] = Field(\n        None,\n        description=(\n            \"An optional token that can be used to guarantee the idempotency of job run\"\n            \" requests. If a run with the provided token already exists, the request\"\n            \" does not create a new run but returns the ID of the existing run instead.\"\n            \" If a run with the provided token is deleted, an error is returned.\\n\\nIf\"\n            \" you specify the idempotency token, upon failure you can retry until the\"\n            \" request succeeds. Databricks guarantees that exactly one run is launched\"\n            \" with that idempotency token.\\n\\nThis token must have at most 64\"\n            \" characters.\\n\\nFor more information, see [How to ensure idempotency for\"\n            \" jobs](https://kb.databricks.com/jobs/jobs-idempotency.html).\"\n        ),\n        example=\"8f018174-4792-40d5-bcbc-3e6a527352c8\",\n    )\n    run_name: Optional[str] = Field(\n        None,\n        description=\"An optional name for the run. The default value is `Untitled`.\",\n        example=\"A multitask job run\",\n    )\n    tasks: Optional[List[RunSubmitTaskSettings]] = Field(\n        None,\n        example=[\n            {\n                \"depends_on\": [],\n                \"description\": \"Extracts session data from events\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/Sessionize.jar\"}],\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.Sessionize\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/data.json\"],\n                },\n                \"task_key\": \"Sessionize\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [],\n                \"description\": \"Ingests order data\",\n                \"existing_cluster_id\": \"0923-164208-meows279\",\n                \"libraries\": [{\"jar\": \"dbfs:/mnt/databricks/OrderIngest.jar\"}],\n                \"spark_jar_task\": {\n                    \"main_class_name\": \"com.databricks.OrdersIngest\",\n                    \"parameters\": [\"--data\", \"dbfs:/path/to/order-data.json\"],\n                },\n                \"task_key\": \"Orders_Ingest\",\n                \"timeout_seconds\": 86400,\n            },\n            {\n                \"depends_on\": [\n                    {\"task_key\": \"Orders_Ingest\"},\n                    {\"task_key\": \"Sessionize\"},\n                ],\n                \"description\": \"Matches orders with user sessions\",\n                \"new_cluster\": {\n                    \"autoscale\": {\"max_workers\": 16, \"min_workers\": 2},\n                    \"aws_attributes\": {\"availability\": \"SPOT\", \"zone_id\": \"us-west-2a\"},\n                    \"node_type_id\": \"i3.xlarge\",\n                    \"spark_conf\": {\"spark.speculation\": True},\n                    \"spark_version\": \"7.3.x-scala2.12\",\n                },\n                \"notebook_task\": {\n                    \"base_parameters\": {\"age\": \"35\", \"name\": \"John Doe\"},\n                    \"notebook_path\": \"/Users/user.name@databricks.com/Match\",\n                    \"source\": \"WORKSPACE\",\n                },\n                \"task_key\": \"Match\",\n                \"timeout_seconds\": 86400,\n            },\n        ],\n        max_items=100,\n    )\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job. The default behavior\"\n            \" is to have no timeout.\"\n        ),\n        example=86400,\n    )\n    webhook_notifications: Optional[WebhookNotifications] = Field(\n        None,\n        description=(\n            \"A collection of system notification IDs to notify when runs of this job\"\n            \" begin or complete. The default behavior is to not send any system\"\n            \" notifications.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunSubmitTaskSettings","title":"<code>RunSubmitTaskSettings</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunSubmitTaskSettings(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this task. When running tasks on an existing cluster, you may\"\n            \" need to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n        example=\"0923-164208-meows279\",\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the task. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this task must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this task must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this task must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this task must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this task must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    task_key: TaskKey\n    timeout_seconds: Optional[int] = Field(\n        None,\n        description=(\n            \"An optional timeout applied to each run of this job task. The default\"\n            \" behavior is to have no timeout.\"\n        ),\n        example=86400,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunTask","title":"<code>RunTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    attempt_number: Optional[int] = Field(\n        None,\n        description=(\n            \"The sequence number of this run attempt for a triggered job run. The\"\n            \" initial attempt of a run has an attempt_number of 0\\\\. If the initial run\"\n            \" attempt fails, and the job has a retry policy (`max_retries` \\\\&gt; 0),\"\n            \" subsequent runs are created with an `original_attempt_run_id` of the\"\n            \" original attempt\u2019s ID and an incrementing `attempt_number`. Runs are\"\n            \" retried only until they succeed, and the maximum `attempt_number` is the\"\n            \" same as the `max_retries` value for the job.\"\n        ),\n        example=0,\n    )\n    cleanup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to terminate the cluster and clean up any\"\n            \" associated artifacts. The total duration of the run is the sum of the\"\n            \" setup_duration, the execution_duration, and the cleanup_duration.\"\n        ),\n        example=0,\n    )\n    cluster_instance: Optional[ClusterInstance] = Field(\n        None,\n        description=(\n            \"The cluster used for this run. If the run is specified to use a new\"\n            \" cluster, this field is set once the Jobs service has requested a cluster\"\n            \" for the run.\"\n        ),\n    )\n    dbt_task: Optional[DbtTask] = Field(\n        None,\n        description=(\n            \"If dbt_task, indicates that this must execute a dbt task. It requires both\"\n            \" Databricks SQL and the ability to use a serverless or a pro SQL\"\n            \" warehouse.\"\n        ),\n    )\n    depends_on: Optional[TaskDependencies] = None\n    description: Optional[TaskDescription] = None\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run ended in epoch milliseconds (milliseconds since\"\n            \" 1/1/1970 UTC). This field is set to 0 if the job is still running.\"\n        ),\n        example=1625060863413,\n    )\n    execution_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time in milliseconds it took to execute the commands in the JAR or\"\n            \" notebook until they completed, failed, timed out, were cancelled, or\"\n            \" encountered an unexpected error.\"\n        ),\n        example=0,\n    )\n    existing_cluster_id: Optional[str] = Field(\n        None,\n        description=(\n            \"If existing_cluster_id, the ID of an existing cluster that is used for all\"\n            \" runs of this job. When running jobs on an existing cluster, you may need\"\n            \" to manually restart the cluster if it stops responding. We suggest\"\n            \" running jobs on new clusters for greater reliability.\"\n        ),\n    )\n    git_source: Optional[GitSource1] = Field(\n        None,\n        description=(\n            \"This functionality is in Public Preview.\\n\\nAn optional specification for\"\n            \" a remote repository containing the notebooks used by this job's notebook\"\n            \" tasks.\"\n        ),\n        example={\n            \"git_branch\": \"main\",\n            \"git_provider\": \"gitHub\",\n            \"git_url\": \"https://github.com/databricks/databricks-cli\",\n        },\n    )\n    libraries: Optional[List[Library]] = Field(\n        None,\n        description=(\n            \"An optional list of libraries to be installed on the cluster that executes\"\n            \" the job. The default value is an empty list.\"\n        ),\n    )\n    new_cluster: Optional[NewCluster] = Field(\n        None,\n        description=(\n            \"If new_cluster, a description of a cluster that is created for each run.\"\n        ),\n    )\n    notebook_task: Optional[NotebookTask] = Field(\n        None,\n        description=(\n            \"If notebook_task, indicates that this job must run a notebook. This field\"\n            \" may not be specified in conjunction with spark_jar_task.\"\n        ),\n    )\n    pipeline_task: Optional[PipelineTask] = Field(\n        None,\n        description=(\n            \"If pipeline_task, indicates that this job must execute a Pipeline.\"\n        ),\n    )\n    python_wheel_task: Optional[PythonWheelTask] = Field(\n        None,\n        description=(\n            \"If python_wheel_task, indicates that this job must execute a PythonWheel.\"\n        ),\n    )\n    run_id: Optional[int] = Field(\n        None, description=\"The ID of the task run.\", example=99887766\n    )\n    setup_duration: Optional[int] = Field(\n        None,\n        description=(\n            \"The time it took to set up the cluster in milliseconds. For runs that run\"\n            \" on new clusters this is the cluster creation time, for runs that run on\"\n            \" existing clusters this time should be very short.\"\n        ),\n        example=0,\n    )\n    spark_jar_task: Optional[SparkJarTask] = Field(\n        None, description=\"If spark_jar_task, indicates that this job must run a JAR.\"\n    )\n    spark_python_task: Optional[SparkPythonTask] = Field(\n        None,\n        description=(\n            \"If spark_python_task, indicates that this job must run a Python file.\"\n        ),\n    )\n    spark_submit_task: Optional[SparkSubmitTask] = Field(\n        None,\n        description=(\n            \"If spark_submit_task, indicates that this job must be launched by the\"\n            \" spark submit script.\"\n        ),\n    )\n    sql_task: Optional[SqlTask] = Field(\n        None,\n        description=(\n            \"If sql_task, indicates that this job must execute a SQL task. It requires\"\n            \" both Databricks SQL and a serverless or a pro SQL warehouse.\"\n        ),\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"The time at which this run was started in epoch milliseconds (milliseconds\"\n            \" since 1/1/1970 UTC). This may not be the time when the job task starts\"\n            \" executing, for example, if the job is scheduled to run on a new cluster,\"\n            \" this is the time the cluster creation call is issued.\"\n        ),\n        example=1625060460483,\n    )\n    state: Optional[RunState] = Field(\n        None, description=\"The result and lifecycle states of the run.\"\n    )\n    task_key: Optional[TaskKey] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.RunType","title":"<code>RunType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>The type of the run.\n</code></pre> <ul> <li><code>JOB_RUN</code> - Normal job run. A run created with Run now.</li> <li><code>WORKFLOW_RUN</code> - Workflow run. A run created with dbutils.notebook.run.</li> <li><code>SUBMIT_RUN</code> - Submit run. A run created with Run Submit.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class RunType(str, Enum):\n    \"\"\"\n        The type of the run.\n    * `JOB_RUN` \\- Normal job run. A run created with [Run now](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunNow).\n    * `WORKFLOW_RUN` \\- Workflow run. A run created with [dbutils.notebook.run](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-workflow).\n    * `SUBMIT_RUN` \\- Submit run. A run created with [Run Submit](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunsSubmit).\n    \"\"\"\n\n    jobrun = \"JOB_RUN\"\n    workflowrun = \"WORKFLOW_RUN\"\n    submitrun = \"SUBMIT_RUN\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.S3StorageInfo","title":"<code>S3StorageInfo</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class S3StorageInfo(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    canned_acl: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) Set canned access control list. For example:\"\n            \" `bucket-owner-full-control`. If canned_acl is set, the cluster instance\"\n            \" profile must have `s3:PutObjectAcl` permission on the destination bucket\"\n            \" and prefix. The full list of possible canned ACLs can be found at\"\n            \" &lt;https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl&gt;.\"\n            \" By default only the object owner gets full control. If you are using\"\n            \" cross account role for writing data, you may want to set\"\n            \" `bucket-owner-full-control` to make bucket owner able to read the logs.\"\n        ),\n    )\n    destination: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 destination. For example: `s3://my-bucket/some-prefix` You must\"\n            \" configure the cluster with an instance profile and the instance profile\"\n            \" must have write access to the destination. You _cannot_ use AWS keys.\"\n        ),\n    )\n    enable_encryption: Optional[bool] = Field(\n        None, description=\"(Optional)Enable server side encryption, `false` by default.\"\n    )\n    encryption_type: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) The encryption type, it could be `sse-s3` or `sse-kms`. It is\"\n            \" used only when encryption is enabled and the default type is `sse-s3`.\"\n        ),\n    )\n    endpoint: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 endpoint. For example: `https://s3-us-west-2.amazonaws.com`. Either\"\n            \" region or endpoint must be set. If both are set, endpoint is used.\"\n        ),\n    )\n    kms_key: Optional[str] = Field(\n        None,\n        description=(\n            \"(Optional) KMS key used if encryption is enabled and encryption type is\"\n            \" set to `sse-kms`.\"\n        ),\n    )\n    region: Optional[str] = Field(\n        None,\n        description=(\n            \"S3 region. For example: `us-west-2`. Either region or endpoint must be\"\n            \" set. If both are set, endpoint is used.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ServicePrincipalName","title":"<code>ServicePrincipalName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ServicePrincipalName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=\"Name of an Azure service principal.\",\n        example=\"9f0621ee-b52b-11ea-b3de-0242ac130004\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkConfPair","title":"<code>SparkConfPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An arbitrary object where the object key is a configuration property name and the value is a configuration property value.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkConfPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An arbitrary object where the object key is a configuration property name and the value is a configuration property value.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkEnvPair","title":"<code>SparkEnvPair</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <p>An arbitrary object where the object key is an environment variable name and the value is an environment variable value.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkEnvPair(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n    An arbitrary object where the object key is an environment variable name and the value is an environment variable value.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n\n        allow_mutation = False\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkJarTask","title":"<code>SparkJarTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkJarTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    jar_uri: Optional[str] = Field(\n        None,\n        deprecated=True,\n        description=(\n            \"Deprecated since 04/2016\\\\. Provide a `jar` through the `libraries` field\"\n            \" instead. For an example, see\"\n            \" [Create](https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsCreate).\"\n        ),\n    )\n    main_class_name: Optional[str] = Field(\n        None,\n        description=(\n            \"The full name of the class containing the main method to be executed. This\"\n            \" class must be contained in a JAR provided as a library.\\n\\nThe code must\"\n            \" use `SparkContext.getOrCreate` to obtain a Spark context; otherwise, runs\"\n            \" of the job fail.\"\n        ),\n        example=\"com.databricks.ComputeModels\",\n    )\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Parameters passed to the main method.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"--data\", \"dbfs:/path/to/data.json\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkNode","title":"<code>SparkNode</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkNode(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    host_private_ip: Optional[str] = Field(\n        None, description=\"The private IP address of the host instance.\"\n    )\n    instance_id: Optional[str] = Field(\n        None,\n        description=(\n            \"Globally unique identifier for the host instance from the cloud provider.\"\n        ),\n    )\n    node_aws_attributes: Optional[SparkNodeAwsAttributes] = Field(\n        None, description=\"Attributes specific to AWS for a Spark node.\"\n    )\n    node_id: Optional[str] = Field(\n        None, description=\"Globally unique identifier for this node.\"\n    )\n    private_ip: Optional[str] = Field(\n        None,\n        description=(\n            \"Private IP address (typically a 10.x.x.x address) of the Spark node. This\"\n            \" is different from the private IP address of the host instance.\"\n        ),\n    )\n    public_dns: Optional[str] = Field(\n        None,\n        description=(\n            \"Public DNS address of this node. This address can be used to access the\"\n            \" Spark JDBC server on the driver node. To communicate with the JDBC\"\n            \" server, traffic must be manually authorized by adding security group\"\n            \" rules to the \u201cworker-unmanaged\u201d security group via the AWS console.\"\n        ),\n    )\n    start_timestamp: Optional[int] = Field(\n        None,\n        description=\"The timestamp (in millisecond) when the Spark node is launched.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkNodeAwsAttributes","title":"<code>SparkNodeAwsAttributes</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkNodeAwsAttributes(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    is_spot: Optional[bool] = Field(\n        None, description=\"Whether this node is on an Amazon spot instance.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkPythonTask","title":"<code>SparkPythonTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkPythonTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command line parameters passed to the Python file.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\"--data\", \"dbfs:/path/to/data.json\"],\n    )\n    python_file: str = Field(\n        ...,\n        description=(\n            \"The Python file to be executed. Cloud file URIs (such as dbfs:/, s3:/,\"\n            \" adls:/, gcs:/) and workspace paths are supported. For python files stored\"\n            \" in the Databricks workspace, the path must be absolute and begin with\"\n            \" `/Repos`. This field is required.\"\n        ),\n        example=\"dbfs:/path/to/file.py\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkSubmitTask","title":"<code>SparkSubmitTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkSubmitTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    parameters: Optional[List[str]] = Field(\n        None,\n        description=(\n            \"Command-line parameters passed to spark submit.\\n\\nUse [Task parameter\"\n            \" variables](https://docs.databricks.com/jobs.html#parameter-variables) to\"\n            \" set parameters containing information about job runs.\"\n        ),\n        example=[\n            \"--class\",\n            \"org.apache.spark.examples.SparkPi\",\n            \"dbfs:/path/to/examples.jar\",\n            \"10\",\n        ],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SparkVersion","title":"<code>SparkVersion</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SparkVersion(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    key: Optional[str] = Field(\n        None,\n        description=(\n            \"[Databricks Runtime\"\n            \" version](https://docs.databricks.com/dev-tools/api/latest/index.html#programmatic-version)\"\n            \" key, for example `7.3.x-scala2.12`. The value that must be provided as\"\n            \" the `spark_version` when creating a new cluster. The exact runtime\"\n            \" version may change over time for a \u201cwildcard\u201d version (that is,\"\n            \" `7.3.x-scala2.12` is a \u201cwildcard\u201d version) with minor bug fixes.\"\n        ),\n    )\n    name: Optional[str] = Field(\n        None,\n        description=(\n            \"A descriptive name for the runtime version, for example \u201cDatabricks\"\n            \" Runtime 7.3 LTS\u201d.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlAlertOutput","title":"<code>SqlAlertOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlAlertOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    query_text: Optional[str] = Field(\n        None,\n        description=(\n            \"The text of the SQL query. Can Run permission of the SQL query associated\"\n            \" with the SQL alert is required to view this field.\"\n        ),\n    )\n    sql_statements: Optional[SqlStatementOutput] = Field(\n        None, description=\"Information about SQL statements executed in the run.\"\n    )\n    warehouse_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL warehouse.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlDashboardOutput","title":"<code>SqlDashboardOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlDashboardOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    widgets: Optional[SqlDashboardWidgetOutput] = Field(\n        None,\n        description=(\n            \"Widgets executed in the run. Only SQL query based widgets are listed.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlDashboardWidgetOutput","title":"<code>SqlDashboardWidgetOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlDashboardWidgetOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    end_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when execution of the SQL widget ends.\"\n        ),\n    )\n    error: Optional[SqlOutputError] = Field(\n        None, description=\"The information about the error when execution fails.\"\n    )\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    start_time: Optional[int] = Field(\n        None,\n        description=(\n            \"Time (in epoch milliseconds) when execution of the SQL widget starts.\"\n        ),\n    )\n    status: Optional[\n        Literal[\"PENDING\", \"RUNNING\", \"SUCCESS\", \"FAILED\", \"CANCELLED\"]\n    ] = Field(None, description=\"The execution status of the SQL widget.\")\n    widget_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL widget.\"\n    )\n    widget_title: Optional[str] = Field(\n        None, description=\"The title of the SQL widget.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlOutput","title":"<code>SqlOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert_output: Optional[SqlAlertOutput] = Field(\n        None, description=\"The output of a SQL alert task, if available.\"\n    )\n    dashboard_output: Optional[SqlDashboardOutput] = Field(\n        None, description=\"The output of a SQL dashboard task, if available.\"\n    )\n    query_output: Optional[SqlQueryOutput] = Field(\n        None, description=\"The output of a SQL query task, if available.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlOutputError","title":"<code>SqlOutputError</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlOutputError(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    message: Optional[str] = Field(\n        None, description=\"The error message when execution fails.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlQueryOutput","title":"<code>SqlQueryOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlQueryOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    output_link: Optional[str] = Field(\n        None, description=\"The link to find the output results.\"\n    )\n    query_text: Optional[str] = Field(\n        None,\n        description=(\n            \"The text of the SQL query. Can Run permission of the SQL query is required\"\n            \" to view this field.\"\n        ),\n    )\n    sql_statements: Optional[SqlStatementOutput] = Field(\n        None, description=\"Information about SQL statements executed in the run.\"\n    )\n    warehouse_id: Optional[str] = Field(\n        None, description=\"The canonical identifier of the SQL warehouse.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlStatementOutput","title":"<code>SqlStatementOutput</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlStatementOutput(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    lookup_key: Optional[str] = Field(\n        None, description=\"A key that can be used to look up query details.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTask","title":"<code>SqlTask</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTask(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert: Optional[SqlTaskAlert] = Field(\n        None, description=\"If alert, indicates that this job must refresh a SQL alert.\"\n    )\n    dashboard: Optional[SqlTaskDashboard] = Field(\n        None,\n        description=(\n            \"If dashboard, indicates that this job must refresh a SQL dashboard.\"\n        ),\n    )\n    parameters: Optional[Dict[str, Any]] = Field(\n        None,\n        description=(\n            \"Parameters to be used for each run of this job. The SQL alert task does\"\n            \" not support custom parameters.\"\n        ),\n        example={\"age\": 35, \"name\": \"John Doe\"},\n    )\n    query: Optional[SqlTaskQuery] = Field(\n        None, description=\"If query, indicates that this job must execute a SQL query.\"\n    )\n    warehouse_id: str = Field(\n        ...,\n        description=(\n            \"The canonical identifier of the SQL warehouse. Only serverless and pro SQL\"\n            \" warehouses are supported.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskAlert","title":"<code>SqlTaskAlert</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskAlert(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    alert_id: str = Field(..., description=\"The canonical identifier of the SQL alert.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskDashboard","title":"<code>SqlTaskDashboard</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskDashboard(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    dashboard_id: str = Field(\n        ..., description=\"The canonical identifier of the SQL dashboard.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.SqlTaskQuery","title":"<code>SqlTaskQuery</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class SqlTaskQuery(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    query_id: str = Field(..., description=\"The canonical identifier of the SQL query.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDependencies","title":"<code>TaskDependencies</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> <pre><code>An optional array of objects specifying the dependency graph of the task. All tasks specified in this field must complete successfully before executing this task.\n</code></pre> <p>The key is <code>task_key</code>, and the value is the name assigned to the dependent task. This field is required when a job consists of more than one task.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDependencies(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n\n        An optional array of objects specifying the dependency graph of the task. All tasks specified in this field must complete successfully before executing this task.\n    The key is `task_key`, and the value is the name assigned to the dependent task.\n    This field is required when a job consists of more than one task.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: List[TaskDependency] = Field(\n        ...,\n        description=(\n            \"An optional array of objects specifying the dependency graph of the task.\"\n            \" All tasks specified in this field must complete successfully before\"\n            \" executing this task.\\nThe key is `task_key`, and the value is the name\"\n            \" assigned to the dependent task.\\nThis field is required when a job\"\n            \" consists of more than one task.\"\n        ),\n        example=[{\"task_key\": \"Previous_Task_Key\"}, {\"task_key\": \"Other_Task_Key\"}],\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDependency","title":"<code>TaskDependency</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDependency(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    task_key: Optional[str] = None\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskDescription","title":"<code>TaskDescription</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskDescription(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"An optional description for this task.\\nThe maximum length is 4096 bytes.\"\n        ),\n        example=\"This is the description for this task.\",\n        max_length=4096,\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TaskKey","title":"<code>TaskKey</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TaskKey(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ...,\n        description=(\n            \"A unique name for the task. This field is used to refer to this task from\"\n            \" other tasks.\\nThis field is required and must be unique within its parent\"\n            \" job.\\nOn Update or Reset, this field is used to reference the tasks to be\"\n            \" updated or reset.\\nThe maximum length is 100 characters.\"\n        ),\n        example=\"Task_Key\",\n        max_length=100,\n        min_length=1,\n        regex=\"^[\\\\w\\\\-]+$\",\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationCode","title":"<code>TerminationCode</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* USER_REQUEST: A user terminated the cluster directly. Parameters should include a `username` field that indicates the specific user who terminated the cluster.\n</code></pre> <ul> <li>JOB_FINISHED: The cluster was launched by a job, and terminated when the job completed.</li> <li>INACTIVITY: The cluster was terminated since it was idle.</li> <li>CLOUD_PROVIDER_SHUTDOWN: The instance that hosted the Spark driver was terminated by the cloud provider. In AWS, for example, AWS may retire instances and directly shut them down. Parameters should include an <code>aws_instance_state_reason</code> field indicating the AWS-provided reason why the instance was terminated.</li> <li>COMMUNICATION_LOST: Databricks lost connection to services on the driver instance. For example, this can happen when problems arise in cloud networking infrastructure, or when the instance itself becomes unhealthy.</li> <li>CLOUD_PROVIDER_LAUNCH_FAILURE: Databricks experienced a cloud provider failure when requesting instances to launch clusters. For example, AWS limits the number of running instances and EBS volumes. If you ask Databricks to launch a cluster that requires instances or EBS volumes that exceed your AWS limit, the cluster fails with this status code. Parameters should include one of <code>aws_api_error_code</code>, <code>aws_instance_state_reason</code>, or <code>aws_spot_request_status</code> to indicate the AWS-provided reason why Databricks could not request the required instances for the cluster.</li> <li>SPARK_STARTUP_FAILURE: The cluster failed to initialize. Possible reasons may include failure to create the environment for Spark or issues launching the Spark master and worker processes.</li> <li>INVALID_ARGUMENT: Cannot launch the cluster because the user specified an invalid argument. For example, the user might specify an invalid runtime version for the cluster.</li> <li>UNEXPECTED_LAUNCH_FAILURE: While launching this cluster, Databricks failed to complete critical setup steps, terminating the cluster.</li> <li>INTERNAL_ERROR: Databricks encountered an unexpected error that forced the running cluster to be terminated. Contact Databricks support for additional details.</li> <li>SPARK_ERROR: The Spark driver failed to start. Possible reasons may include incompatible libraries and initialization scripts that corrupted the Spark container.</li> <li>METASTORE_COMPONENT_UNHEALTHY: The cluster failed to start because the external metastore could not be reached. Refer to Troubleshooting.</li> <li>DBFS_COMPONENT_UNHEALTHY: The cluster failed to start because Databricks File System (DBFS) could not be reached.</li> <li>DRIVER_UNREACHABLE: Databricks was not able to access the Spark driver, because it was not reachable.</li> <li>DRIVER_UNRESPONSIVE: Databricks was not able to access the Spark driver, because it was unresponsive.</li> <li>INSTANCE_UNREACHABLE: Databricks was not able to access instances in order to start the cluster. This can be a transient networking issue. If the problem persists, this usually indicates a networking environment misconfiguration.</li> <li>CONTAINER_LAUNCH_FAILURE: Databricks was unable to launch containers on worker nodes for the cluster. Have your admin check your network configuration.</li> <li>INSTANCE_POOL_CLUSTER_FAILURE: Pool backed cluster specific failure. Refer to Pools for details.</li> <li>REQUEST_REJECTED: Databricks cannot handle the request at this moment. Try again later and contact Databricks if the problem persists.</li> <li>INIT_SCRIPT_FAILURE: Databricks cannot load and run a cluster-scoped init script on one of the cluster\u2019s nodes, or the init script terminates with a non-zero exit code. Refer to Init script logs.</li> <li>TRIAL_EXPIRED: The Databricks trial subscription expired.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationCode(str, Enum):\n    \"\"\"\n        * USER_REQUEST: A user terminated the cluster directly. Parameters should include a `username` field that indicates the specific user who terminated the cluster.\n    * JOB_FINISHED: The cluster was launched by a job, and terminated when the job completed.\n    * INACTIVITY: The cluster was terminated since it was idle.\n    * CLOUD_PROVIDER_SHUTDOWN: The instance that hosted the Spark driver was terminated by the cloud provider. In AWS, for example, AWS may retire instances and directly shut them down. Parameters should include an `aws_instance_state_reason` field indicating the AWS-provided reason why the instance was terminated.\n    * COMMUNICATION_LOST: Databricks lost connection to services on the driver instance. For example, this can happen when problems arise in cloud networking infrastructure, or when the instance itself becomes unhealthy.\n    * CLOUD_PROVIDER_LAUNCH_FAILURE: Databricks experienced a cloud provider failure when requesting instances to launch clusters. For example, AWS limits the number of running instances and EBS volumes. If you ask Databricks to launch a cluster that requires instances or EBS volumes that exceed your AWS limit, the cluster fails with this status code. Parameters should include one of `aws_api_error_code`, `aws_instance_state_reason`, or `aws_spot_request_status` to indicate the AWS-provided reason why Databricks could not request the required instances for the cluster.\n    * SPARK_STARTUP_FAILURE: The cluster failed to initialize. Possible reasons may include failure to create the environment for Spark or issues launching the Spark master and worker processes.\n    * INVALID_ARGUMENT: Cannot launch the cluster because the user specified an invalid argument. For example, the user might specify an invalid runtime version for the cluster.\n    * UNEXPECTED_LAUNCH_FAILURE: While launching this cluster, Databricks failed to complete critical setup steps, terminating the cluster.\n    * INTERNAL_ERROR: Databricks encountered an unexpected error that forced the running cluster to be terminated. Contact Databricks support for additional details.\n    * SPARK_ERROR: The Spark driver failed to start. Possible reasons may include incompatible libraries and initialization scripts that corrupted the Spark container.\n    * METASTORE_COMPONENT_UNHEALTHY: The cluster failed to start because the external metastore could not be reached. Refer to [Troubleshooting](https://docs.databricks.com/data/metastores/external-hive-metastore.html#troubleshooting).\n    * DBFS_COMPONENT_UNHEALTHY: The cluster failed to start because Databricks File System (DBFS) could not be reached.\n    * DRIVER_UNREACHABLE: Databricks was not able to access the Spark driver, because it was not reachable.\n    * DRIVER_UNRESPONSIVE: Databricks was not able to access the Spark driver, because it was unresponsive.\n    * INSTANCE_UNREACHABLE: Databricks was not able to access instances in order to start the cluster. This can be a transient networking issue. If the problem persists, this usually indicates a networking environment misconfiguration.\n    * CONTAINER_LAUNCH_FAILURE: Databricks was unable to launch containers on worker nodes for the cluster. Have your admin check your network configuration.\n    * INSTANCE_POOL_CLUSTER_FAILURE: Pool backed cluster specific failure. Refer to [Pools](https://docs.databricks.com/clusters/instance-pools/index.html) for details.\n    * REQUEST_REJECTED: Databricks cannot handle the request at this moment. Try again later and contact Databricks if the problem persists.\n    * INIT_SCRIPT_FAILURE: Databricks cannot load and run a cluster-scoped init script on one of the cluster\u2019s nodes, or the init script terminates with a non-zero exit code. Refer to [Init script logs](https://docs.databricks.com/clusters/init-scripts.html#init-script-log).\n    * TRIAL_EXPIRED: The Databricks trial subscription expired.\n    \"\"\"\n\n    userrequest = \"USER_REQUEST\"\n    jobfinished = \"JOB_FINISHED\"\n    inactivity = \"INACTIVITY\"\n    cloudprovidershutdown = \"CLOUD_PROVIDER_SHUTDOWN\"\n    communicationlost = \"COMMUNICATION_LOST\"\n    cloudproviderlaunchfailure = \"CLOUD_PROVIDER_LAUNCH_FAILURE\"\n    sparkstartupfailure = \"SPARK_STARTUP_FAILURE\"\n    invalidargument = \"INVALID_ARGUMENT\"\n    unexpectedlaunchfailure = \"UNEXPECTED_LAUNCH_FAILURE\"\n    internalerror = \"INTERNAL_ERROR\"\n    sparkerror = \"SPARK_ERROR\"\n    metastorecomponentunhealthy = \"METASTORE_COMPONENT_UNHEALTHY\"\n    dbfscomponentunhealthy = \"DBFS_COMPONENT_UNHEALTHY\"\n    driverunreachable = \"DRIVER_UNREACHABLE\"\n    driverunresponsive = \"DRIVER_UNRESPONSIVE\"\n    instanceunreachable = \"INSTANCE_UNREACHABLE\"\n    containerlaunchfailure = \"CONTAINER_LAUNCH_FAILURE\"\n    instancepoolclusterfailure = \"INSTANCE_POOL_CLUSTER_FAILURE\"\n    requestrejected = \"REQUEST_REJECTED\"\n    initscriptfailure = \"INIT_SCRIPT_FAILURE\"\n    trialexpired = \"TRIAL_EXPIRED\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationParameter","title":"<code>TerminationParameter</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationParameter(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    aws_api_error_code: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided error code describing why cluster nodes could not be\"\n            \" provisioned. For example, `InstanceLimitExceeded` indicates that the\"\n            \" limit of EC2 instances for a specific instance type has been exceeded.\"\n            \" For reference, see:\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-api-troubleshooting.html&gt;.\"\n        ),\n    )\n    aws_error_message: Optional[str] = Field(\n        None,\n        description=(\n            \"Human-readable context of various failures from AWS. This field is\"\n            \" unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    aws_impaired_status_details: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided status check which failed and induced a node loss. This\"\n            \" status may correspond to a failed instance or system check. For\"\n            \" reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html&gt;.\"\n        ),\n    )\n    aws_instance_state_reason: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided state reason describing why the driver node was\"\n            \" terminated. For example, `Client.VolumeLimitExceeded` indicates that the\"\n            \" limit of EBS volumes or total EBS volume storage has been exceeded. For\"\n            \" reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StateReason.html&gt;.\"\n        ),\n    )\n    aws_instance_status_event: Optional[str] = Field(\n        None,\n        description=(\n            \"The AWS provided scheduled event (for example reboot) which induced a node\"\n            \" loss. For reference, see\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-instances-status-check_sched.html&gt;.\"\n        ),\n    )\n    aws_spot_request_fault_code: Optional[str] = Field(\n        None,\n        description=(\n            \"Provides additional details when a spot request fails. For example\"\n            \" `InsufficientFreeAddressesInSubnet` indicates the subnet does not have\"\n            \" free IP addresses to accommodate the new instance. For reference, see\"\n            \" &lt;https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-spot-instance-requests.html&gt;.\"\n        ),\n    )\n    aws_spot_request_status: Optional[str] = Field(\n        None,\n        description=(\n            \"Describes why a spot request could not be fulfilled. For example,\"\n            \" `price-too-low` indicates that the max price was lower than the current\"\n            \" spot price. For reference, see:\"\n            \" &lt;https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-bid-status.html#spot-instance-bid-status-understand&gt;.\"\n        ),\n    )\n    databricks_error_message: Optional[str] = Field(\n        None,\n        description=(\n            \"Additional context that may explain the reason for cluster termination.\"\n            \" This field is unstructured, and its exact format is subject to change.\"\n        ),\n    )\n    inactivity_duration_min: Optional[str] = Field(\n        None,\n        description=(\n            \"An idle cluster was shut down after being inactive for this duration.\"\n        ),\n    )\n    instance_id: Optional[str] = Field(\n        None, description=\"The ID of the instance that was hosting the Spark driver.\"\n    )\n    instance_pool_error_code: Optional[str] = Field(\n        None,\n        description=(\n            \"The [error\"\n            \" code](https://docs.databricks.com/dev-tools/api/latest/clusters.html#clusterterminationreasonpoolclusterterminationcode)\"\n            \" for cluster failures specific to a pool.\"\n        ),\n    )\n    instance_pool_id: Optional[str] = Field(\n        None, description=\"The ID of the instance pool the cluster is using.\"\n    )\n    username: Optional[str] = Field(\n        None, description=\"The username of the user who terminated the cluster.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationReason","title":"<code>TerminationReason</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationReason(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    code: Optional[TerminationCode] = Field(\n        None, description=\"Status code indicating why a cluster was terminated.\"\n    )\n    parameters: Optional[ParameterPair] = Field(\n        None,\n        description=(\n            \"Object containing a set of parameters that provide information about why a\"\n            \" cluster was terminated.\"\n        ),\n    )\n    type: Optional[TerminationType] = Field(\n        None, description=\"Reason indicating why a cluster was terminated.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TerminationType","title":"<code>TerminationType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* SUCCESS: Termination succeeded.\n</code></pre> <ul> <li>CLIENT_ERROR: Non-retriable. Client must fix parameters before reattempting the cluster creation.</li> <li>SERVICE_FAULT: Databricks service issue. Client can retry.</li> <li>CLOUD_FAILURECloud provider infrastructure issue. Client can retry after the underlying issue is resolved.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TerminationType(str, Enum):\n    \"\"\"\n        * SUCCESS: Termination succeeded.\n    * CLIENT_ERROR: Non-retriable. Client must fix parameters before reattempting the cluster creation.\n    * SERVICE_FAULT: Databricks service issue. Client can retry.\n    * CLOUD_FAILURECloud provider infrastructure issue. Client can retry after the underlying issue is resolved.\n\n    \"\"\"\n\n    success = \"SUCCESS\"\n    clienterror = \"CLIENT_ERROR\"\n    servicefault = \"SERVICE_FAULT\"\n    cloudfailure = \"CLOUD_FAILURE\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.TriggerType","title":"<code>TriggerType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler.\n</code></pre> <ul> <li><code>ONE_TIME</code>: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API.</li> <li><code>RETRY</code>: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class TriggerType(str, Enum):\n    \"\"\"\n        * `PERIODIC`: Schedules that periodically trigger runs, such as a cron scheduler.\n    * `ONE_TIME`: One time triggers that fire a single run. This occurs you triggered a single run on demand through the UI or the API.\n    * `RETRY`: Indicates a run that is triggered as a retry of a previously failed run. This occurs when you request to re-run the job in case of failures.\n    \"\"\"\n\n    periodic = \"PERIODIC\"\n    onetime = \"ONE_TIME\"\n    retry = \"RETRY\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.UserName","title":"<code>UserName</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class UserName(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    __root__: str = Field(\n        ..., description=\"Email address for the user.\", example=\"jsmith@example.com\"\n    )\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewItem","title":"<code>ViewItem</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewItem(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    content: Optional[str] = Field(None, description=\"Content of the view.\")\n    name: Optional[str] = Field(\n        None,\n        description=(\n            \"Name of the view item. In the case of code view, it would be the\"\n            \" notebook\u2019s name. In the case of dashboard view, it would be the\"\n            \" dashboard\u2019s name.\"\n        ),\n    )\n    type: Optional[ViewType] = Field(None, description=\"Type of the view item.\")\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewType","title":"<code>ViewType</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `NOTEBOOK`: Notebook view item.\n</code></pre> <ul> <li><code>DASHBOARD</code>: Dashboard view item.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewType(str, Enum):\n    \"\"\"\n        * `NOTEBOOK`: Notebook view item.\n    * `DASHBOARD`: Dashboard view item.\n    \"\"\"\n\n    notebook = \"NOTEBOOK\"\n    dashboard = \"DASHBOARD\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.ViewsToExport","title":"<code>ViewsToExport</code>","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <pre><code>* `CODE`: Code view of the notebook.\n</code></pre> <ul> <li><code>DASHBOARDS</code>: All dashboard views of the notebook.</li> <li><code>ALL</code>: All views of the notebook.</li> </ul> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class ViewsToExport(str, Enum):\n    \"\"\"\n        * `CODE`: Code view of the notebook.\n    * `DASHBOARDS`: All dashboard views of the notebook.\n    * `ALL`: All views of the notebook.\n    \"\"\"\n\n    code = \"CODE\"\n    dashboards = \"DASHBOARDS\"\n    all = \"ALL\"\n</code></pre>"},{"location":"integrations/prefect-databricks/models/jobs/#prefect_databricks.models.jobs.WebhookNotifications","title":"<code>WebhookNotifications</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>See source code for the fields' description.</p> Source code in <code>prefect_databricks/models/jobs.py</code> <pre><code>class WebhookNotifications(BaseModel):\n    \"\"\"\n    See source code for the fields' description.\n    \"\"\"\n\n    class Config:\n        extra = Extra.allow\n        allow_mutation = False\n\n    on_failure: Optional[List[OnFailureItem]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run fails. A maximum\"\n            \" of 3 destinations can be specified for the `on_failure` property.\"\n        ),\n        example=[{\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"}],\n    )\n    on_start: Optional[List[OnStartItem]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run starts. A\"\n            \" maximum of 3 destinations can be specified for the `on_start` property.\"\n        ),\n        example=[\n            {\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"},\n            {\"id\": \"0481e838-0a59-4eff-9541-a4ca6f149574\"},\n        ],\n    )\n    on_success: Optional[List[OnSucces]] = Field(\n        None,\n        description=(\n            \"An optional list of notification IDs to call when the run completes\"\n            \" successfully. A maximum of 3 destinations can be specified for the\"\n            \" `on_success` property.\"\n        ),\n        example=[{\"id\": \"03dd86e4-57ef-4818-a950-78e41a1d71ab\"}],\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/","title":"prefect-dbt","text":"<p>With prefect-dbt you can trigger and observe dbt Cloud jobs, execute dbt Core CLI commands, and incorporate other tools, such as Snowflake, into your dbt runs. Prefect provides a global view of the state of your workflows and allows you to take action based on state changes.</p>"},{"location":"integrations/prefect-dbt/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-dbt/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A dbt Cloud account if using dbt Cloud.</li> </ul>"},{"location":"integrations/prefect-dbt/#install-prefect-dbt","title":"Install prefect-dbt","text":"<p>Install <code>prefect-dbt</code>:</p> <pre><code>pip install -U prefect-dbt\n</code></pre> <p>If necessary, see additional installation options for dbt Core with BigQuery, Snowflake, and Postgres.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-dbt[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#register-newly-installed-blocks-types","title":"Register newly installed blocks types","text":"<p>Register the block types in the prefect-dbt module to make them available for use.</p> <pre><code>prefect block register -m prefect_dbt\n</code></pre> <p>Explore the examples below to use Prefect with dbt.</p>"},{"location":"integrations/prefect-dbt/#integrate-dbt-cloud-jobs-with-prefect-flows","title":"Integrate dbt Cloud jobs with Prefect flows","text":"<p>If you have an existing dbt Cloud job, use the pre-built flow <code>run_dbt_cloud_job</code> to trigger a job run and wait until the job run is finished.</p> <p>If some nodes fail, <code>run_dbt_cloud_job</code> efficiently retries the unsuccessful nodes.</p> <p>Prior to running this flow, save your dbt Cloud credentials to a DbtCloudCredentials block:</p> <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudJob\nfrom prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n@flow\ndef run_dbt_job_flow():\n    result = run_dbt_cloud_job(\n        dbt_cloud_job=DbtCloudJob.load(\"my-block-name\"),\n        targeted_retries=5,\n    )\n    return result\n\nrun_dbt_job_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#integrate-dbt-core-cli-commands-with-prefect-flows","title":"Integrate dbt Core CLI commands with Prefect flows","text":"<p>Prefect-dbt supports execution of dbt Core CLI commands. If you don't have a <code>DbtCoreOperation</code> block saved, create one and set the commands that you want to run.</p> <p>Optionally, specify the <code>project_dir</code>. If <code>profiles_dir</code> is not set, the <code>DBT_PROFILES_DIR</code> environment variable will be used. If <code>DBT_PROFILES_DIR</code> is not set, the default directory will be used <code>$HOME/.dbt/</code>.</p>"},{"location":"integrations/prefect-dbt/#use-an-existing-profile","title":"Use an existing profile","text":"<p>If you have an existing dbt profile, specify the <code>profiles_dir</code> where <code>profiles.yml</code> is located:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cli.commands import DbtCoreOperation\n\n\n@flow\ndef trigger_dbt_flow() -&gt; str:\n    result = DbtCoreOperation(\n        commands=[\"pwd\", \"dbt debug\", \"dbt run\"],\n        project_dir=\"PROJECT-DIRECTORY-PLACEHOLDER\",\n        profiles_dir=\"PROFILES-DIRECTORY-PLACEHOLDER\"\n    ).run()\n    return result\n\n\nif __name__ == \"__main__\":\n    trigger_dbt_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#set-up-a-new-profile","title":"Set up a new profile","text":"<p>To setup a new profile, first save and load a DbtCliProfile block and use it in <code>DbtCoreOperation</code>.</p> <p>Then, specify<code>profiles_dir</code> where <code>profiles.yml</code> will be written. Here's example code with placeholders:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cli import DbtCliProfile, DbtCoreOperation\n\n\n@flow\ndef trigger_dbt_flow():\n    dbt_cli_profile = DbtCliProfile.load(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n    with DbtCoreOperation(\n        commands=[\"dbt debug\", \"dbt run\"],\n        project_dir=\"PROJECT-DIRECTORY-PLACEHOLDER\",\n        profiles_dir=\"PROFILES-DIRECTORY-PLACEHOLDER\",\n        dbt_cli_profile=dbt_cli_profile,\n    ) as dbt_operation:\n        dbt_process = dbt_operation.trigger()\n        # do other things before waiting for completion\n        dbt_process.wait_for_completion()\n        result = dbt_process.fetch_result()\n    return result\n\nif __name__ == \"__main__\":\n    trigger_dbt_flow()\n</code></pre>"},{"location":"integrations/prefect-dbt/#save-credentials-to-a-block","title":"Save credentials to a block","text":"<p>Blocks can be created through code or through the UI.</p>"},{"location":"integrations/prefect-dbt/#dbt-cloud","title":"dbt Cloud","text":"<p>To create a dbt Cloud Credentials block do the following:</p> <ol> <li>Go to your dbt Cloud profile.</li> <li>Log in to your dbt Cloud account.</li> <li>Scroll to API or click API Access on the sidebar.</li> <li>Copy the API Key.</li> <li>Click Projects on the sidebar.</li> <li>Copy the account ID from the URL: <code>https://cloud.getdbt.com/settings/accounts/&lt;ACCOUNT_ID&gt;</code>.</li> <li>Create and run the following script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\nDbtCloudCredentials(\n    api_key=\"API-KEY-PLACEHOLDER\",\n    account_id=\"ACCOUNT-ID-PLACEHOLDER\"\n).save(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Then, to create a dbt Cloud job block do the following:</p> <ol> <li>Navigate to your dbt home page.</li> <li>On the top nav bar, click on Deploy -&gt; Jobs.</li> <li>Select a job.</li> <li>Copy the job ID from the URL: <code>https://cloud.getdbt.com/deploy/&lt;ACCOUNT_ID&gt;/projects/&lt;PROJECT_ID&gt;/jobs/&lt;JOB_ID&gt;</code></li> <li>Create and run the following script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\ndbt_cloud_credentials = DbtCloudCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\ndbt_cloud_job = DbtCloudJob(\n    dbt_cloud_credentials=dbt_cloud_credentials,\n    job_id=\"JOB-ID-PLACEHOLDER\"\n).save(\"JOB-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Load the saved block, which can access your credentials:</p> <pre><code>from prefect_dbt.cloud import DbtCloudJob\n\nDbtCloudJob.load(\"JOB-BLOCK-NAME-PLACEHOLDER\")\n</code></pre>"},{"location":"integrations/prefect-dbt/#dbt-core-cli","title":"dbt Core CLI","text":"<p>Available <code>TargetConfigs</code> blocks</p> <p>Visit the API Reference to see other built-in <code>TargetConfigs</code> blocks.</p> <p>If the desired service profile is not available, check out the Examples Catalog to see how you can  build one from the generic <code>TargetConfigs</code> class.</p> <p>To create dbt Core target config and profile blocks for BigQuery:</p> <ol> <li>Save and load a <code>GcpCredentials</code> block.</li> <li>Determine the schema / dataset you want to use in BigQuery.</li> <li>Create a short script, replacing the placeholders.</li> </ol> <pre><code>from prefect_gcp.credentials import GcpCredentials\nfrom prefect_dbt.cli import BigQueryTargetConfigs, DbtCliProfile\n\ncredentials = GcpCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\ntarget_configs = BigQueryTargetConfigs(\n    schema=\"SCHEMA-NAME-PLACEHOLDER\",  # also known as dataset\n    credentials=credentials,\n)\ntarget_configs.save(\"TARGET-CONFIGS-BLOCK-NAME-PLACEHOLDER\")\n\ndbt_cli_profile = DbtCliProfile(\n    name=\"PROFILE-NAME-PLACEHOLDER\",\n    target=\"TARGET-NAME-placeholder\",\n    target_configs=target_configs,\n)\ndbt_cli_profile.save(\"DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>To create a dbt Core operation block:</p> <ol> <li>Determine the dbt commands you want to run.</li> <li>Create a short script, replacing the placeholders.</li> </ol> <pre><code>from prefect_dbt.cli import DbtCliProfile, DbtCoreOperation\n\ndbt_cli_profile = DbtCliProfile.load(\"DBT-CLI-PROFILE-BLOCK-NAME-PLACEHOLDER\")\ndbt_core_operation = DbtCoreOperation(\n    commands=[\"DBT-CLI-COMMANDS-PLACEHOLDER\"],\n    dbt_cli_profile=dbt_cli_profile,\n    overwrite_profiles=True,\n)\ndbt_core_operation.save(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Load the saved block that holds your credentials:</p> <pre><code>from prefect_dbt.cloud import DbtCoreOperation\n\nDbtCoreOperation.load(\"DBT-CORE-OPERATION-BLOCK-NAME-PLACEHOLDER\")\n</code></pre>"},{"location":"integrations/prefect-dbt/#resources","title":"Resources","text":"<p>For assistance using dbt, consult the dbt documentation.</p> <p>Refer to the prefect-dbt API documentation linked in the sidebar to explore all the capabilities of the prefect-dbt library.</p>"},{"location":"integrations/prefect-dbt/#additional-installation-options","title":"Additional installation options","text":"<p>Additional installation options for dbt Core with BigQuery, Snowflake, and Postgres are shown below.</p>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-snowflake-profiles","title":"Additional functionality for dbt Core and Snowflake profiles","text":"<pre><code>pip install -U \"prefect-dbt[snowflake]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-bigquery-profiles","title":"Additional functionality for dbt Core and BigQuery profiles","text":"<pre><code>pip install -U \"prefect-dbt[bigquery]\"\n</code></pre>"},{"location":"integrations/prefect-dbt/#additional-functionality-for-dbt-core-and-postgres-profiles","title":"Additional functionality for dbt Core and Postgres profiles","text":"<pre><code>pip install -U \"prefect-dbt[postgres]\"\n</code></pre> <p>Some dbt Core profiles require additional installation</p> <p>According to dbt's Databricks setup page, users must first install the adapter:</p> <p> <pre><code>pip install dbt-databricks\n</code></pre> </p> <p>Check out the desired profile setup page on the sidebar for others.</p>"},{"location":"integrations/prefect-dbt/cli/commands/","title":"Commands","text":""},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands","title":"<code>prefect_dbt.cli.commands</code>","text":"<p>Module containing tasks and flows for interacting with dbt CLI</p>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.DbtCoreOperation","title":"<code>DbtCoreOperation</code>","text":"<p>               Bases: <code>ShellOperation</code></p> <p>A block representing a dbt operation, containing multiple dbt and shell commands.</p> <p>For long-lasting operations, use the trigger method and utilize the block as a context manager for automatic closure of processes when context is exited. If not, manually call the close method to close processes.</p> <p>For short-lasting operations, use the run method. Context is automatically managed with this method.</p> <p>Attributes:</p> Name Type Description <code>commands</code> <p>A list of commands to execute sequentially.</p> <code>stream_output</code> <p>Whether to stream output.</p> <code>env</code> <p>A dictionary of environment variables to set for the shell operation.</p> <code>working_directory</code> <p>The working directory context the commands will be executed within.</p> <code>shell</code> <p>The shell to use to execute the commands.</p> <code>extension</code> <p>The extension to use for the temporary file. if unset defaults to <code>.ps1</code> on Windows and <code>.sh</code> on other platforms.</p> <code>profiles_dir</code> <code>Optional[Path]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the dbt commands provided. If this is not set, will try using the DBT_PROFILES_DIR environment variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>project_dir</code> <code>Optional[Path]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <p>Examples:</p> <p>Load a configured block. <pre><code>from prefect_dbt import DbtCoreOperation\n\ndbt_op = DbtCoreOperation.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Execute short-lasting dbt debug and list with a custom DbtCliProfile. <pre><code>from prefect_dbt import DbtCoreOperation, DbtCliProfile\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake import SnowflakeConnector\n\nsnowflake_connector = await SnowflakeConnector.load(\"snowflake-connector\")\ntarget_configs = SnowflakeTargetConfigs(connector=snowflake_connector)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\ndbt_init = DbtCoreOperation(\n    commands=[\"dbt debug\", \"dbt list\"],\n    dbt_cli_profile=dbt_cli_profile,\n    overwrite_profiles=True\n)\ndbt_init.run()\n</code></pre></p> <p>Execute a longer-lasting dbt run as a context manager. <pre><code>with DbtCoreOperation(commands=[\"dbt run\"]) as dbt_run:\n    dbt_process = dbt_run.trigger()\n    # do other things\n    dbt_process.wait_for_completion()\n    dbt_output = dbt_process.fetch_result()\n</code></pre></p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>class DbtCoreOperation(ShellOperation):\n    \"\"\"\n    A block representing a dbt operation, containing multiple dbt and shell commands.\n\n    For long-lasting operations, use the trigger method and utilize the block as a\n    context manager for automatic closure of processes when context is exited.\n    If not, manually call the close method to close processes.\n\n    For short-lasting operations, use the run method. Context is automatically managed\n    with this method.\n\n    Attributes:\n        commands: A list of commands to execute sequentially.\n        stream_output: Whether to stream output.\n        env: A dictionary of environment variables to set for the shell operation.\n        working_directory: The working directory context the commands\n            will be executed within.\n        shell: The shell to use to execute the commands.\n        extension: The extension to use for the temporary file.\n            if unset defaults to `.ps1` on Windows and `.sh` on other platforms.\n        profiles_dir: The directory to search for the profiles.yml file.\n            Setting this appends the `--profiles-dir` option to the dbt commands\n            provided. If this is not set, will try using the DBT_PROFILES_DIR\n            environment variable, but if that's also not\n            set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error if profiles.yml already\n            exists under profile_dir and overwrite_profiles is set to False.\n\n    Examples:\n        Load a configured block.\n        ```python\n        from prefect_dbt import DbtCoreOperation\n\n        dbt_op = DbtCoreOperation.load(\"BLOCK_NAME\")\n        ```\n\n        Execute short-lasting dbt debug and list with a custom DbtCliProfile.\n        ```python\n        from prefect_dbt import DbtCoreOperation, DbtCliProfile\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake import SnowflakeConnector\n\n        snowflake_connector = await SnowflakeConnector.load(\"snowflake-connector\")\n        target_configs = SnowflakeTargetConfigs(connector=snowflake_connector)\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        dbt_init = DbtCoreOperation(\n            commands=[\"dbt debug\", \"dbt list\"],\n            dbt_cli_profile=dbt_cli_profile,\n            overwrite_profiles=True\n        )\n        dbt_init.run()\n        ```\n\n        Execute a longer-lasting dbt run as a context manager.\n        ```python\n        with DbtCoreOperation(commands=[\"dbt run\"]) as dbt_run:\n            dbt_process = dbt_run.trigger()\n            # do other things\n            dbt_process.wait_for_completion()\n            dbt_output = dbt_process.fetch_result()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Core Operation\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.DbtCoreOperation\"  # noqa\n\n    profiles_dir: Optional[Path] = Field(\n        default=None,\n        description=(\n            \"The directory to search for the profiles.yml file. \"\n            \"Setting this appends the `--profiles-dir` option to the dbt commands \"\n            \"provided. If this is not set, will try using the DBT_PROFILES_DIR \"\n            \"environment variable, but if that's also not \"\n            \"set, will use the default directory `$HOME/.dbt/`.\"\n        ),\n    )\n    project_dir: Optional[Path] = Field(\n        default=None,\n        description=(\n            \"The directory to search for the dbt_project.yml file. \"\n            \"Default is the current working directory and its parents.\"\n        ),\n    )\n    overwrite_profiles: bool = Field(\n        default=False,\n        description=(\n            \"Whether the existing profiles.yml file under profiles_dir \"\n            \"should be overwritten with a new profile.\"\n        ),\n    )\n    dbt_cli_profile: Optional[DbtCliProfile] = Field(\n        default=None,\n        description=(\n            \"Profiles class containing the profile written to profiles.yml. \"\n            \"Note! This is optional and will raise an error if profiles.yml already \"\n            \"exists under profile_dir and overwrite_profiles is set to False.\"\n        ),\n    )\n\n    @validator(\"commands\", always=True)\n    def _has_a_dbt_command(cls, commands):\n        \"\"\"\n        Check that the commands contain a dbt command.\n        \"\"\"\n        if not any(\"dbt \" in command for command in commands):\n            raise ValueError(\n                \"None of the commands are a valid dbt sub-command; see dbt --help, \"\n                \"or use prefect_shell.ShellOperation for non-dbt related \"\n                \"commands instead\"\n            )\n        return commands\n\n    def _find_valid_profiles_dir(self) -&gt; PosixPath:\n        \"\"\"\n        Ensure that there is a profiles.yml available for use.\n        \"\"\"\n        profiles_dir = self.profiles_dir\n        if profiles_dir is None:\n            if self.env.get(\"DBT_PROFILES_DIR\") is not None:\n                # get DBT_PROFILES_DIR from the user input env\n                profiles_dir = self.env[\"DBT_PROFILES_DIR\"]\n            else:\n                # get DBT_PROFILES_DIR from the system env, or default to ~/.dbt\n                profiles_dir = os.getenv(\"DBT_PROFILES_DIR\", Path.home() / \".dbt\")\n        profiles_dir = relative_path_to_current_platform(\n            Path(profiles_dir).expanduser()\n        )\n\n        # https://docs.getdbt.com/dbt-cli/configure-your-profile\n        # Note that the file always needs to be called profiles.yml,\n        # regardless of which directory it is in.\n        profiles_path = profiles_dir / \"profiles.yml\"\n        overwrite_profiles = self.overwrite_profiles\n        dbt_cli_profile = self.dbt_cli_profile\n        if not profiles_path.exists() or overwrite_profiles:\n            if dbt_cli_profile is None:\n                raise ValueError(\n                    \"Since overwrite_profiles is True or profiles_path is empty, \"\n                    \"need `dbt_cli_profile` to write a profile\"\n                )\n            profile = dbt_cli_profile.get_profile()\n            profiles_dir.mkdir(exist_ok=True)\n            with open(profiles_path, \"w+\") as f:\n                yaml.dump(profile, f, default_flow_style=False)\n        elif dbt_cli_profile is not None:\n            raise ValueError(\n                f\"Since overwrite_profiles is False and profiles_path {profiles_path} \"\n                f\"already exists, the profile within dbt_cli_profile couldn't be used; \"\n                f\"if the existing profile is satisfactory, do not set dbt_cli_profile\"\n            )\n        return profiles_dir\n\n    def _append_dirs_to_commands(self, profiles_dir) -&gt; List[str]:\n        \"\"\"\n        Append profiles_dir and project_dir options to dbt commands.\n        \"\"\"\n        project_dir = self.project_dir\n\n        commands = []\n        for command in self.commands:\n            command += f\" --profiles-dir {profiles_dir}\"\n            if project_dir is not None:\n                project_dir = Path(project_dir).expanduser()\n                command += f\" --project-dir {project_dir}\"\n            commands.append(command)\n        return commands\n\n    def _compile_kwargs(self, **open_kwargs: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Helper method to compile the kwargs for `open_process` so it's not repeated\n        across the run and trigger methods.\n        \"\"\"\n        profiles_dir = self._find_valid_profiles_dir()\n        commands = self._append_dirs_to_commands(profiles_dir=profiles_dir)\n\n        # _compile_kwargs is called within trigger() and run(), prior to execution.\n        # However _compile_kwargs directly uses self.commands, but here we modified\n        # the commands without saving back to self.commands so we need to create a copy.\n        # was also thinking of using env vars but DBT_PROJECT_DIR is not supported yet.\n        modified_self = self.copy()\n        modified_self.commands = commands\n        return super(type(self), modified_self)._compile_kwargs(**open_kwargs)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.create_summary_markdown","title":"<code>create_summary_markdown</code>","text":"<p>Creates a Prefect task artifact summarizing the results of the above predefined prefrect-dbt task.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>def create_summary_markdown(run_results: dict, command: str) -&gt; str:\n    \"\"\"\n    Creates a Prefect task artifact summarizing the results\n    of the above predefined prefrect-dbt task.\n    \"\"\"\n    markdown = f\"# dbt {command} Task Summary\\n\"\n    markdown += _create_node_summary_table_md(run_results=run_results)\n\n    if (\n        run_results[\"Error\"] != []\n        or run_results[\"Fail\"] != []\n        or run_results[\"Skipped\"] != []\n        or run_results[\"Warn\"] != []\n    ):\n        markdown += \"\\n\\n ## Unsuccessful Nodes \u274c\\n\\n\"\n        markdown += _create_unsuccessful_markdown(run_results=run_results)\n\n    if run_results[\"Success\"] != []:\n        successful_runs_str = \"\\n\".join(\n            [f\"* {r.node.name}\" for r in run_results[\"Success\"]]\n        )\n        markdown += f\"\"\"\\n## Successful Nodes \u2705\\n\\n{successful_runs_str}\\n\\n\"\"\"\n\n    return markdown\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_build","title":"<code>run_dbt_build</code>  <code>async</code>","text":"<p>Executes the 'dbt build' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-build-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt build command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_build_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_build_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_build(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-build-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt build' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-build-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt build command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_build_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_build_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"build\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_model","title":"<code>run_dbt_model</code>  <code>async</code>","text":"<p>Executes the 'dbt run' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt run results artifact in Prefect. Defaults to 'dbt-run-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt run command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_run_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_run_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_model(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-run-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt run' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt run results artifact in Prefect.\n            Defaults to 'dbt-run-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt run command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_run_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_run_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"run\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_seed","title":"<code>run_dbt_seed</code>  <code>async</code>","text":"<p>Executes the 'dbt seed' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-seed-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt seed command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_seed_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_seed_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--fail-fast\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_seed(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-seed-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt seed' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-seed-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt seed command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_seed_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_seed_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--fail-fast\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"seed\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_snapshot","title":"<code>run_dbt_snapshot</code>  <code>async</code>","text":"<p>Executes the 'dbt snapshot' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-snapshot-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt snapshot command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_snapshot_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_snapshot_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--fail-fast\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_snapshot(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-snapshot-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt snapshot' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-snapshot-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt snapshot command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_snapshot_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_snapshot_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--fail-fast\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"snapshot\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.run_dbt_test","title":"<code>run_dbt_test</code>  <code>async</code>","text":"<p>Executes the 'dbt test' command within a Prefect task, and optionally creates a Prefect artifact summarizing the dbt build results.</p> <p>Parameters:</p> Name Type Description Default <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR env variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt test results artifact in Prefect. Defaults to 'dbt-test-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt test command.</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <pre><code>    from prefect import flow\n    from prefect_dbt.cli.tasks import dbt_test_task\n\n    @flow\n    def dbt_test_flow():\n        dbt_test_task(\n            project_dir=\"/Users/test/my_dbt_project_dir\",\n            extra_command_args=[\"--model\", \"foo_model\"]\n        )\n</code></pre> <p>Raises:</p> Type Description <code>ValueError</code> <p>If required dbt_cli_profile is not provided         when needed for profile writing.</p> <code>RuntimeError</code> <p>If the dbt build fails for any reason,         it will be indicated by the exception raised.</p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def run_dbt_test(\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: str = \"dbt-test-task-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n):\n    \"\"\"\n    Executes the 'dbt test' command within a Prefect task,\n    and optionally creates a Prefect artifact summarizing the dbt build results.\n\n    Args:\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided.\n            If this is not set, will try using the DBT_PROFILES_DIR env variable,\n            but if that's also not set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error\n            if profiles.yml already exists under profile_dir\n            and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt test results artifact in Prefect.\n            Defaults to 'dbt-test-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt test command.\n        stream_output: Whether to stream output.\n\n    Example:\n    ```python\n        from prefect import flow\n        from prefect_dbt.cli.tasks import dbt_test_task\n\n        @flow\n        def dbt_test_flow():\n            dbt_test_task(\n                project_dir=\"/Users/test/my_dbt_project_dir\",\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n    ```\n\n    Raises:\n        ValueError: If required dbt_cli_profile is not provided\n                    when needed for profile writing.\n        RuntimeError: If the dbt build fails for any reason,\n                    it will be indicated by the exception raised.\n    \"\"\"\n\n    results = await trigger_dbt_cli_command.fn(\n        command=\"test\",\n        profiles_dir=profiles_dir,\n        project_dir=project_dir,\n        overwrite_profiles=overwrite_profiles,\n        dbt_cli_profile=dbt_cli_profile,\n        create_summary_artifact=create_summary_artifact,\n        summary_artifact_key=summary_artifact_key,\n        extra_command_args=extra_command_args,\n        stream_output=stream_output,\n    )\n\n    return results\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.trigger_dbt_cli_command","title":"<code>trigger_dbt_cli_command</code>  <code>async</code>","text":"<p>Task for running dbt commands.</p> <p>If no profiles.yml file is found or if overwrite_profiles flag is set to True, this will first generate a profiles.yml file in the profiles_dir directory. Then run the dbt CLI shell command.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>The dbt command to be executed.</p> required <code>profiles_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the profiles.yml file. Setting this appends the <code>--profiles-dir</code> option to the command provided. If this is not set, will try using the DBT_PROFILES_DIR environment variable, but if that's also not set, will use the default directory <code>$HOME/.dbt/</code>.</p> <code>None</code> <code>project_dir</code> <code>Optional[Union[Path, str]]</code> <p>The directory to search for the dbt_project.yml file. Default is the current working directory and its parents.</p> <code>None</code> <code>overwrite_profiles</code> <code>bool</code> <p>Whether the existing profiles.yml file under profiles_dir should be overwritten with a new profile.</p> <code>False</code> <code>dbt_cli_profile</code> <code>Optional[DbtCliProfile]</code> <p>Profiles class containing the profile written to profiles.yml. Note! This is optional and will raise an error if profiles.yml already exists under profile_dir and overwrite_profiles is set to False.</p> <code>None</code> <code>create_artifact</code> <p>If True, creates a Prefect artifact on the task run with the dbt build results using the specified artifact key. Defaults to True.</p> required <code>artifact_key</code> <p>The key under which to store the dbt build results artifact in Prefect. Defaults to 'dbt-seed-task-summary'.</p> required <code>extra_command_args</code> <code>Optional[List[str]]</code> <p>Additional command arguments to pass to the dbt command. These arguments get appended to the command that gets passed to the dbtRunner client. Example: extra_command_args=[\"--model\", \"foo_model\"]</p> <code>None</code> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>True</code> <p>Returns:</p> Name Type Description <code>last_line_cli_output</code> <code>str</code> <p>The last line of the CLI output will be returned if <code>return_all</code> in <code>shell_run_command_kwargs</code> is False. This is the default behavior.</p> <code>full_cli_output</code> <code>List[str]</code> <p>Full CLI output will be returned if <code>return_all</code> in <code>shell_run_command_kwargs</code> is True.</p> <p>Examples:</p> <p>Execute <code>dbt debug</code> with a pre-populated profiles.yml. <pre><code>from prefect import flow\nfrom prefect_dbt.cli.commands import trigger_dbt_cli_command\n\n@flow\ndef trigger_dbt_cli_command_flow():\n    result = trigger_dbt_cli_command(\"dbt debug\")\n    return result\n\ntrigger_dbt_cli_command_flow()\n</code></pre></p> <p>Execute <code>dbt debug</code> without a pre-populated profiles.yml. <pre><code>from prefect import flow\nfrom prefect_dbt.cli.credentials import DbtCliProfile\nfrom prefect_dbt.cli.commands import trigger_dbt_cli_command\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\n\n@flow\ndef trigger_dbt_cli_command_flow():\n    credentials = SnowflakeCredentials(\n        user=\"user\",\n        password=\"password\",\n        account=\"account.region.aws\",\n        role=\"role\",\n    )\n    connector = SnowflakeConnector(\n        schema=\"public\",\n        database=\"database\",\n        warehouse=\"warehouse\",\n        credentials=credentials,\n    )\n    target_configs = SnowflakeTargetConfigs(\n        connector=connector\n    )\n    dbt_cli_profile = DbtCliProfile(\n        name=\"jaffle_shop\",\n        target=\"dev\",\n        target_configs=target_configs,\n    )\n    result = trigger_dbt_cli_command(\n        \"dbt run\",\n        overwrite_profiles=True,\n        dbt_cli_profile=dbt_cli_profile,\n        extra_command_args=[\"--model\", \"foo_model\"]\n    )\n    return result\n\ntrigger_dbt_cli_command_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cli/commands.py</code> <pre><code>@task\nasync def trigger_dbt_cli_command(\n    command: str,\n    profiles_dir: Optional[Union[Path, str]] = None,\n    project_dir: Optional[Union[Path, str]] = None,\n    overwrite_profiles: bool = False,\n    dbt_cli_profile: Optional[DbtCliProfile] = None,\n    create_summary_artifact: bool = False,\n    summary_artifact_key: Optional[str] = \"dbt-cli-command-summary\",\n    extra_command_args: Optional[List[str]] = None,\n    stream_output: bool = True,\n) -&gt; Optional[dbtRunnerResult]:\n    \"\"\"\n    Task for running dbt commands.\n\n    If no profiles.yml file is found or if overwrite_profiles flag is set to True, this\n    will first generate a profiles.yml file in the profiles_dir directory. Then run the dbt\n    CLI shell command.\n\n    Args:\n        command: The dbt command to be executed.\n        profiles_dir: The directory to search for the profiles.yml file. Setting this\n            appends the `--profiles-dir` option to the command provided. If this is not set,\n            will try using the DBT_PROFILES_DIR environment variable, but if that's also not\n            set, will use the default directory `$HOME/.dbt/`.\n        project_dir: The directory to search for the dbt_project.yml file.\n            Default is the current working directory and its parents.\n        overwrite_profiles: Whether the existing profiles.yml file under profiles_dir\n            should be overwritten with a new profile.\n        dbt_cli_profile: Profiles class containing the profile written to profiles.yml.\n            Note! This is optional and will raise an error if profiles.yml already exists\n            under profile_dir and overwrite_profiles is set to False.\n        create_artifact: If True, creates a Prefect artifact on the task run\n            with the dbt build results using the specified artifact key.\n            Defaults to True.\n        artifact_key: The key under which to store\n            the dbt build results artifact in Prefect.\n            Defaults to 'dbt-seed-task-summary'.\n        extra_command_args: Additional command arguments to pass to the dbt command.\n            These arguments get appended to the command that gets passed to the dbtRunner client.\n            Example: extra_command_args=[\"--model\", \"foo_model\"]\n        stream_output: Whether to stream output.\n\n    Returns:\n        last_line_cli_output (str): The last line of the CLI output will be returned\n            if `return_all` in `shell_run_command_kwargs` is False. This is the default\n            behavior.\n        full_cli_output (List[str]): Full CLI output will be returned if `return_all`\n            in `shell_run_command_kwargs` is True.\n\n    Examples:\n        Execute `dbt debug` with a pre-populated profiles.yml.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cli.commands import trigger_dbt_cli_command\n\n        @flow\n        def trigger_dbt_cli_command_flow():\n            result = trigger_dbt_cli_command(\"dbt debug\")\n            return result\n\n        trigger_dbt_cli_command_flow()\n        ```\n\n        Execute `dbt debug` without a pre-populated profiles.yml.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cli.credentials import DbtCliProfile\n        from prefect_dbt.cli.commands import trigger_dbt_cli_command\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n\n        @flow\n        def trigger_dbt_cli_command_flow():\n            credentials = SnowflakeCredentials(\n                user=\"user\",\n                password=\"password\",\n                account=\"account.region.aws\",\n                role=\"role\",\n            )\n            connector = SnowflakeConnector(\n                schema=\"public\",\n                database=\"database\",\n                warehouse=\"warehouse\",\n                credentials=credentials,\n            )\n            target_configs = SnowflakeTargetConfigs(\n                connector=connector\n            )\n            dbt_cli_profile = DbtCliProfile(\n                name=\"jaffle_shop\",\n                target=\"dev\",\n                target_configs=target_configs,\n            )\n            result = trigger_dbt_cli_command(\n                \"dbt run\",\n                overwrite_profiles=True,\n                dbt_cli_profile=dbt_cli_profile,\n                extra_command_args=[\"--model\", \"foo_model\"]\n            )\n            return result\n\n        trigger_dbt_cli_command_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    if profiles_dir is None:\n        profiles_dir = os.getenv(\"DBT_PROFILES_DIR\", str(Path.home()) + \"/.dbt\")\n\n    if command.startswith(\"dbt\"):\n        command = command.split(\" \", 1)[1]\n\n    # https://docs.getdbt.com/dbt-cli/configure-your-profile\n    # Note that the file always needs to be called profiles.yml,\n    # regardless of which directory it is in.\n    profiles_path = profiles_dir + \"/profiles.yml\"\n    logger.debug(f\"Using this profiles path: {profiles_path}\")\n\n    # write the profile if overwrite or no profiles exist\n    if overwrite_profiles or not Path(profiles_path).expanduser().exists():\n        if dbt_cli_profile is None:\n            raise ValueError(\"Provide `dbt_cli_profile` keyword for writing profiles\")\n        profile = dbt_cli_profile.get_profile()\n        Path(profiles_dir).expanduser().mkdir(exist_ok=True)\n        with open(profiles_path, \"w+\") as f:\n            yaml.dump(profile, f, default_flow_style=False)\n        logger.info(f\"Wrote profile to {profiles_path}\")\n    elif dbt_cli_profile is not None:\n        raise ValueError(\n            f\"Since overwrite_profiles is False and profiles_path ({profiles_path}) \"\n            f\"already exists, the profile within dbt_cli_profile could not be used; \"\n            f\"if the existing profile is satisfactory, do not pass dbt_cli_profile\"\n        )\n\n    # append the options\n    cli_args = command.split(\" \")\n    cli_args.append(\"--profiles-dir\")\n    cli_args.append(profiles_dir)\n    if project_dir is not None:\n        project_dir = Path(project_dir).expanduser()\n        cli_args.append(\"--project-dir\")\n        cli_args.append(project_dir)\n\n    if extra_command_args:\n        for value in extra_command_args:\n            cli_args.append(value)\n\n    # Add the dbt event log callback if enabled\n    callbacks = []\n    if stream_output:\n\n        def _stream_output(event):\n            if event.info.level != \"debug\":\n                logger.info(event.info.msg)\n\n        callbacks.append(_stream_output)\n\n    # fix up empty shell_run_command_kwargs\n    dbt_runner_client = dbtRunner(callbacks=callbacks)\n    logger.info(f\"Running dbt command: {cli_args}\")\n    result: dbtRunnerResult = dbt_runner_client.invoke(cli_args)\n\n    if result.exception is not None:\n        logger.error(f\"dbt task failed with exception: {result.exception}\")\n        raise result.exception\n\n    # Creating the dbt Summary Markdown if enabled\n    if create_summary_artifact and isinstance(result.result, RunExecutionResult):\n        run_results = consolidate_run_results(result)\n        markdown = create_summary_markdown(run_results, command)\n        artifact_id = await create_markdown_artifact(\n            markdown=markdown,\n            key=summary_artifact_key,\n        )\n        if not artifact_id:\n            logger.error(f\"Summary Artifact was not created for dbt {command} task\")\n        else:\n            logger.info(\n                f\"dbt {command} task completed successfully with artifact {artifact_id}\"\n            )\n    else:\n        logger.debug(\n            f\"Artifacts were not created for dbt {command} this task \\\n                     due to create_artifact=False or the dbt command did not \\\n                     return any RunExecutionResults. \\\n                     See https://docs.getdbt.com/reference/programmatic-invocations \\\n                     for more details on dbtRunnerResult.\"\n        )\n    if isinstance(result.result, RunExecutionResult) and not result.success:\n        return Failed(\n            message=f\"dbt task result unsuccessful with exception: {result.exception}\"\n        )\n    return result\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials","title":"<code>prefect_dbt.cli.credentials</code>","text":"<p>Module containing credentials for interacting with dbt CLI</p>"},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile","title":"<code>DbtCliProfile</code>","text":"<p>               Bases: <code>Block</code></p> <p>Profile for use across dbt CLI tasks and flows.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Profile name used for populating profiles.yml.</p> <code>target</code> <code>str</code> <p>The default target your dbt project will use.</p> <code>target_configs</code> <code>TargetConfigs</code> <p>Target configs contain credentials and settings, specific to the warehouse you're connecting to. To find valid keys, head to the Available adapters page and click the desired adapter's \"Profile Setup\" hyperlink.</p> <code>global_configs</code> <code>GlobalConfigs</code> <p>Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model. Valid keys can be found here.</p> <p>Examples:</p> <p>Load stored dbt CLI profile: <pre><code>from prefect_dbt.cli import DbtCliProfile\ndbt_cli_profile = DbtCliProfile.load(\"BLOCK_NAME\").get_profile()\n</code></pre></p> <p>Get a dbt Snowflake profile from DbtCliProfile by using SnowflakeTargetConfigs: <pre><code>from prefect_dbt.cli import DbtCliProfile\nfrom prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\ncredentials = SnowflakeCredentials(\n    user=\"user\",\n    password=\"password\",\n    account=\"account.region.aws\",\n    role=\"role\",\n)\nconnector = SnowflakeConnector(\n    schema=\"public\",\n    database=\"database\",\n    warehouse=\"warehouse\",\n    credentials=credentials,\n)\ntarget_configs = SnowflakeTargetConfigs(\n    connector=connector\n)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\nprofile = dbt_cli_profile.get_profile()\n</code></pre></p> <p>Get a dbt Redshift profile from DbtCliProfile by using generic TargetConfigs: <pre><code>from prefect_dbt.cli import DbtCliProfile\nfrom prefect_dbt.cli.configs import GlobalConfigs, TargetConfigs\n\ntarget_configs_extras = dict(\n    host=\"hostname.region.redshift.amazonaws.com\",\n    user=\"username\",\n    password=\"password1\",\n    port=5439,\n    dbname=\"analytics\",\n)\ntarget_configs = TargetConfigs(\n    type=\"redshift\",\n    schema=\"schema\",\n    threads=4,\n    extras=target_configs_extras\n)\ndbt_cli_profile = DbtCliProfile(\n    name=\"jaffle_shop\",\n    target=\"dev\",\n    target_configs=target_configs,\n)\nprofile = dbt_cli_profile.get_profile()\n</code></pre></p> Source code in <code>prefect_dbt/cli/credentials.py</code> <pre><code>class DbtCliProfile(Block):\n    \"\"\"\n    Profile for use across dbt CLI tasks and flows.\n\n    Attributes:\n        name (str): Profile name used for populating profiles.yml.\n        target (str): The default target your dbt project will use.\n        target_configs (TargetConfigs): Target configs contain credentials and\n            settings, specific to the warehouse you're connecting to.\n            To find valid keys, head to the [Available adapters](\n            https://docs.getdbt.com/docs/available-adapters) page and\n            click the desired adapter's \"Profile Setup\" hyperlink.\n        global_configs (GlobalConfigs): Global configs control\n            things like the visual output of logs, the manner\n            in which dbt parses your project, and what to do when\n            dbt finds a version mismatch or a failing model.\n            Valid keys can be found [here](\n            https://docs.getdbt.com/reference/global-configs).\n\n    Examples:\n        Load stored dbt CLI profile:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        dbt_cli_profile = DbtCliProfile.load(\"BLOCK_NAME\").get_profile()\n        ```\n\n        Get a dbt Snowflake profile from DbtCliProfile by using SnowflakeTargetConfigs:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        credentials = SnowflakeCredentials(\n            user=\"user\",\n            password=\"password\",\n            account=\"account.region.aws\",\n            role=\"role\",\n        )\n        connector = SnowflakeConnector(\n            schema=\"public\",\n            database=\"database\",\n            warehouse=\"warehouse\",\n            credentials=credentials,\n        )\n        target_configs = SnowflakeTargetConfigs(\n            connector=connector\n        )\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        profile = dbt_cli_profile.get_profile()\n        ```\n\n        Get a dbt Redshift profile from DbtCliProfile by using generic TargetConfigs:\n        ```python\n        from prefect_dbt.cli import DbtCliProfile\n        from prefect_dbt.cli.configs import GlobalConfigs, TargetConfigs\n\n        target_configs_extras = dict(\n            host=\"hostname.region.redshift.amazonaws.com\",\n            user=\"username\",\n            password=\"password1\",\n            port=5439,\n            dbname=\"analytics\",\n        )\n        target_configs = TargetConfigs(\n            type=\"redshift\",\n            schema=\"schema\",\n            threads=4,\n            extras=target_configs_extras\n        )\n        dbt_cli_profile = DbtCliProfile(\n            name=\"jaffle_shop\",\n            target=\"dev\",\n            target_configs=target_configs,\n        )\n        profile = dbt_cli_profile.get_profile()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Profile\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile\"  # noqa\n\n    name: str = Field(\n        default=..., description=\"Profile name used for populating profiles.yml.\"\n    )\n    target: str = Field(\n        default=..., description=\"The default target your dbt project will use.\"\n    )\n    target_configs: Union[\n        SnowflakeTargetConfigs,\n        BigQueryTargetConfigs,\n        PostgresTargetConfigs,\n        TargetConfigs,\n    ] = Field(\n        default=...,\n        description=(\n            \"Target configs contain credentials and settings, specific to the \"\n            \"warehouse you're connecting to.\"\n        ),\n    )\n    global_configs: Optional[GlobalConfigs] = Field(\n        default=None,\n        description=(\n            \"Global configs control things like the visual output of logs, the manner \"\n            \"in which dbt parses your project, and what to do when dbt finds a version \"\n            \"mismatch or a failing model.\"\n        ),\n    )\n\n    def get_profile(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt profile, likely used for writing to profiles.yml.\n\n        Returns:\n            A JSON compatible dictionary with the expected format of profiles.yml.\n        \"\"\"\n        profile = {\n            \"config\": self.global_configs.get_configs() if self.global_configs else {},\n            self.name: {\n                \"target\": self.target,\n                \"outputs\": {self.target: self.target_configs.get_configs()},\n            },\n        }\n        return profile\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/credentials/#prefect_dbt.cli.credentials.DbtCliProfile.get_profile","title":"<code>get_profile</code>","text":"<p>Returns the dbt profile, likely used for writing to profiles.yml.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A JSON compatible dictionary with the expected format of profiles.yml.</p> Source code in <code>prefect_dbt/cli/credentials.py</code> <pre><code>def get_profile(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt profile, likely used for writing to profiles.yml.\n\n    Returns:\n        A JSON compatible dictionary with the expected format of profiles.yml.\n    \"\"\"\n    profile = {\n        \"config\": self.global_configs.get_configs() if self.global_configs else {},\n        self.name: {\n            \"target\": self.target,\n            \"outputs\": {self.target: self.target_configs.get_configs()},\n        },\n    }\n    return profile\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/","title":"Base","text":""},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base","title":"<code>prefect_dbt.cli.configs.base</code>","text":"<p>Module containing models for base configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs","title":"<code>DbtConfigs</code>","text":"<p>               Bases: <code>Block</code>, <code>ABC</code></p> <p>Abstract class for other dbt Configs.</p> <p>Attributes:</p> Name Type Description <code>extras</code> <code>Optional[Dict[str, Any]]</code> <p>Extra target configs' keywords, not yet exposed in prefect-dbt, but available in dbt; if there are duplicate keys between extras and TargetConfigs, an error will be raised.</p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class DbtConfigs(Block, abc.ABC):\n    \"\"\"\n    Abstract class for other dbt Configs.\n\n    Attributes:\n        extras: Extra target configs' keywords, not yet exposed\n            in prefect-dbt, but available in dbt; if there are\n            duplicate keys between extras and TargetConfigs,\n            an error will be raised.\n    \"\"\"\n\n    extras: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=(\n            \"Extra target configs' keywords, not yet exposed in prefect-dbt, \"\n            \"but available in dbt.\"\n        ),\n    )\n    allow_field_overrides: bool = Field(\n        default=False,\n        description=(\n            \"If enabled, fields from dbt target configs will override \"\n            \"fields provided in extras and credentials.\"\n        ),\n    )\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs\"  # noqa\n\n    def _populate_configs_json(\n        self,\n        configs_json: Dict[str, Any],\n        fields: Dict[str, Any],\n        model: BaseModel = None,\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Recursively populate configs_json.\n        \"\"\"\n        # if allow_field_overrides is True keys from TargetConfigs take precedence\n        override_configs_json = {}\n\n        for field_name, field in fields.items():\n            if model is not None:\n                # get actual value from model\n                try:\n                    field_value = getattr(model, field_name)\n                except AttributeError:\n                    field_value = getattr(model, field.alias)\n                # override the name with alias so dbt parser can recognize the keyword;\n                # e.g. schema_ -&gt; schema, returns the original name if no alias is set\n                field_name = field.alias\n            else:\n                field_value = field\n\n            if field_value is None or field_name == \"allow_field_overrides\":\n                # do not add to configs json if no value or default is set\n                continue\n\n            if isinstance(field_value, BaseModel):\n                configs_json = self._populate_configs_json(\n                    configs_json, field_value.__fields__, model=field_value\n                )\n            elif field_name == \"extras\":\n                configs_json = self._populate_configs_json(\n                    configs_json,\n                    field_value,\n                )\n                override_configs_json.update(configs_json)\n            else:\n                if field_name in configs_json.keys() and not self.allow_field_overrides:\n                    raise ValueError(\n                        f\"The keyword, {field_name}, has already been provided in \"\n                        f\"TargetConfigs; remove duplicated keywords to continue\"\n                    )\n                if isinstance(field_value, SecretField):\n                    field_value = field_value.get_secret_value()\n                elif isinstance(field_value, Path):\n                    field_value = str(field_value)\n                configs_json[field_name] = field_value\n\n                if self.allow_field_overrides and model is self or model is None:\n                    override_configs_json[field_name] = field_value\n\n        configs_json.update(override_configs_json)\n        return configs_json\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs, likely used eventually for writing to profiles.yml.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        return self._populate_configs_json({}, self.__fields__, model=self)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.DbtConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs, likely used eventually for writing to profiles.yml.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs, likely used eventually for writing to profiles.yml.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    return self._populate_configs_json({}, self.__fields__, model=self)\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.GlobalConfigs","title":"<code>GlobalConfigs</code>","text":"<p>               Bases: <code>DbtConfigs</code></p> <p>Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model. Docs can be found here.</p> <p>Attributes:</p> Name Type Description <code>send_anonymous_usage_stats</code> <code>Optional[bool]</code> <p>Whether usage stats are sent to dbt.</p> <code>use_colors</code> <code>Optional[bool]</code> <p>Colorize the output it prints in your terminal.</p> <code>partial_parse</code> <code>Optional[bool]</code> <p>When partial parsing is enabled, dbt will use an stored internal manifest to determine which files have been changed (if any) since it last parsed the project.</p> <code>printer_width</code> <code>Optional[int]</code> <p>Length of characters before starting a new line.</p> <code>write_json</code> <code>Optional[bool]</code> <p>Determines whether dbt writes JSON artifacts to the target/ directory.</p> <code>warn_error</code> <code>Optional[bool]</code> <p>Whether to convert dbt warnings into errors.</p> <code>log_format</code> <code>Optional[str]</code> <p>The LOG_FORMAT config specifies how dbt's logs should be formatted. If the value of this config is json, dbt will output fully structured logs in JSON format.</p> <code>debug</code> <code>Optional[bool]</code> <p>Whether to redirect dbt's debug logs to standard out.</p> <code>version_check</code> <code>Optional[bool]</code> <p>Whether to raise an error if a project's version is used with an incompatible dbt version.</p> <code>fail_fast</code> <code>Optional[bool]</code> <p>Make dbt exit immediately if a single resource fails to build.</p> <code>use_experimental_parser</code> <code>Optional[bool]</code> <p>Opt into the latest experimental version of the static parser.</p> <code>static_parser</code> <code>Optional[bool]</code> <p>Whether to use the static parser.</p> <p>Examples:</p> <p>Load stored GlobalConfigs: <pre><code>from prefect_dbt.cli.configs import GlobalConfigs\n\ndbt_cli_global_configs = GlobalConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class GlobalConfigs(DbtConfigs):\n    \"\"\"\n    Global configs control things like the visual output\n    of logs, the manner in which dbt parses your project,\n    and what to do when dbt finds a version mismatch\n    or a failing model. Docs can be found [here](\n    https://docs.getdbt.com/reference/global-configs).\n\n    Attributes:\n        send_anonymous_usage_stats: Whether usage stats are sent to dbt.\n        use_colors: Colorize the output it prints in your terminal.\n        partial_parse: When partial parsing is enabled, dbt will use an\n            stored internal manifest to determine which files have been changed\n            (if any) since it last parsed the project.\n        printer_width: Length of characters before starting a new line.\n        write_json: Determines whether dbt writes JSON artifacts to\n            the target/ directory.\n        warn_error: Whether to convert dbt warnings into errors.\n        log_format: The LOG_FORMAT config specifies how dbt's logs should\n            be formatted. If the value of this config is json, dbt will\n            output fully structured logs in JSON format.\n        debug: Whether to redirect dbt's debug logs to standard out.\n        version_check: Whether to raise an error if a project's version\n            is used with an incompatible dbt version.\n        fail_fast: Make dbt exit immediately if a single resource fails to build.\n        use_experimental_parser: Opt into the latest experimental version\n            of the static parser.\n        static_parser: Whether to use the [static parser](\n            https://docs.getdbt.com/reference/parsing#static-parser).\n\n    Examples:\n        Load stored GlobalConfigs:\n        ```python\n        from prefect_dbt.cli.configs import GlobalConfigs\n\n        dbt_cli_global_configs = GlobalConfigs.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Global Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.GlobalConfigs\"  # noqa\n\n    send_anonymous_usage_stats: Optional[bool] = Field(\n        default=None,\n        description=\"Whether usage stats are sent to dbt.\",\n    )\n    use_colors: Optional[bool] = Field(\n        default=None,\n        description=\"Colorize the output it prints in your terminal.\",\n    )\n    partial_parse: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"When partial parsing is enabled, dbt will use an \"\n            \"stored internal manifest to determine which files have been changed \"\n            \"(if any) since it last parsed the project.\"\n        ),\n    )\n    printer_width: Optional[int] = Field(\n        default=None,\n        description=\"Length of characters before starting a new line.\",\n    )\n    write_json: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Determines whether dbt writes JSON artifacts to \" \"the target/ directory.\"\n        ),\n    )\n    warn_error: Optional[bool] = Field(\n        default=None,\n        description=\"Whether to convert dbt warnings into errors.\",\n    )\n    log_format: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The LOG_FORMAT config specifies how dbt's logs should \"\n            \"be formatted. If the value of this config is json, dbt will \"\n            \"output fully structured logs in JSON format.\"\n        ),\n    )\n    debug: Optional[bool] = Field(\n        default=None,\n        description=\"Whether to redirect dbt's debug logs to standard out.\",\n    )\n    version_check: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether to raise an error if a project's version \"\n            \"is used with an incompatible dbt version.\"\n        ),\n    )\n    fail_fast: Optional[bool] = Field(\n        default=None,\n        description=(\"Make dbt exit immediately if a single resource fails to build.\"),\n    )\n    use_experimental_parser: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Opt into the latest experimental version \" \"of the static parser.\"\n        ),\n    )\n    static_parser: Optional[bool] = Field(\n        default=None,\n        description=(\n            \"Whether to use the [static parser](https://docs.getdbt.com/reference/parsing#static-parser).\"  # noqa\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.TargetConfigs","title":"<code>TargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to the warehouse you're connecting to. To find valid keys, head to the Available adapters page and click the desired adapter's \"Profile Setup\" hyperlink.</p> <p>Attributes:</p> Name Type Description <code>type</code> <p>The name of the database warehouse.</p> <code>schema</code> <p>The schema that dbt will build objects into; in BigQuery, a schema is actually a dataset.</p> <code>threads</code> <p>The number of threads representing the max number of paths through the graph dbt may work on at once.</p> <p>Examples:</p> <p>Load stored TargetConfigs: <pre><code>from prefect_dbt.cli.configs import TargetConfigs\n\ndbt_cli_target_configs = TargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/base.py</code> <pre><code>class TargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to the warehouse you're connecting to.\n    To find valid keys, head to the [Available adapters](\n    https://docs.getdbt.com/docs/available-adapters) page and\n    click the desired adapter's \"Profile Setup\" hyperlink.\n\n    Attributes:\n        type: The name of the database warehouse.\n        schema: The schema that dbt will build objects into;\n            in BigQuery, a schema is actually a dataset.\n        threads: The number of threads representing the max number\n            of paths through the graph dbt may work on at once.\n\n    Examples:\n        Load stored TargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import TargetConfigs\n\n        dbt_cli_target_configs = TargetConfigs.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/base/#prefect_dbt.cli.configs.base.TargetConfigs\"  # noqa\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/","title":"BigQuery","text":""},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery","title":"<code>prefect_dbt.cli.configs.bigquery</code>","text":"<p>Module containing models for BigQuery configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs","title":"<code>BigQueryTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to BigQuery. To find valid keys, head to the BigQuery Profile page.</p> <p>Attributes:</p> Name Type Description <code>credentials</code> <code>GcpCredentials</code> <p>The credentials to use to authenticate; if there are duplicate keys between credentials and TargetConfigs, e.g. schema, an error will be raised.</p> <p>Examples:</p> <p>Load stored BigQueryTargetConfigs. <pre><code>from prefect_dbt.cli.configs import BigQueryTargetConfigs\n\nbigquery_target_configs = BigQueryTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate BigQueryTargetConfigs. <pre><code>from prefect_dbt.cli.configs import BigQueryTargetConfigs\nfrom prefect_gcp.credentials import GcpCredentials\n\ncredentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\ntarget_configs = BigQueryTargetConfigs(\n    schema=\"schema\",  # also known as dataset\n    credentials=credentials,\n)\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/bigquery.py</code> <pre><code>class BigQueryTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to BigQuery.\n    To find valid keys, head to the [BigQuery Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/bigquery-profile)\n    page.\n\n    Attributes:\n        credentials: The credentials to use to authenticate; if there are\n            duplicate keys between credentials and TargetConfigs,\n            e.g. schema, an error will be raised.\n\n    Examples:\n        Load stored BigQueryTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import BigQueryTargetConfigs\n\n        bigquery_target_configs = BigQueryTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate BigQueryTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import BigQueryTargetConfigs\n        from prefect_gcp.credentials import GcpCredentials\n\n        credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n        target_configs = BigQueryTargetConfigs(\n            schema=\"schema\",  # also known as dataset\n            credentials=credentials,\n        )\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI BigQuery Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _description = \"dbt CLI target configs containing credentials and settings, specific to BigQuery.\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs\"  # noqa\n\n    type: Literal[\"bigquery\"] = Field(\n        default=\"bigquery\", description=\"The type of target.\"\n    )\n    project: Optional[str] = Field(default=None, description=\"The project to use.\")\n    credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=\"The credentials to use to authenticate.\",\n    )\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to BigQuery profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        # since GcpCredentials will always define a project\n        self_copy = self.copy()\n        if self_copy.project is not None:\n            self_copy.credentials.project = None\n        all_configs_json = self._populate_configs_json(\n            {}, self_copy.__fields__, model=self_copy\n        )\n\n        # decouple prefect-gcp from prefect-dbt\n        # by mapping all the keys dbt gcp accepts\n        # https://docs.getdbt.com/reference/warehouse-setups/bigquery-setup\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"dataset\": \"schema\",\n            \"method\": \"method\",\n            \"project\": \"project\",\n            # service-account\n            \"service_account_file\": \"keyfile\",\n            # service-account json\n            \"service_account_info\": \"keyfile_json\",\n            # oauth secrets\n            \"refresh_token\": \"refresh_token\",\n            \"client_id\": \"client_id\",\n            \"client_secret\": \"client_secret\",\n            \"token_uri\": \"token_uri\",\n            # optional\n            \"priority\": \"priority\",\n            \"timeout_seconds\": \"timeout_seconds\",\n            \"location\": \"location\",\n            \"maximum_bytes_billed\": \"maximum_bytes_billed\",\n            \"scopes\": \"scopes\",\n            \"impersonate_service_account\": \"impersonate_service_account\",\n            \"execution_project\": \"execution_project\",\n        }\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n\n        if \"keyfile_json\" in configs_json:\n            configs_json[\"method\"] = \"service-account-json\"\n        elif \"keyfile\" in configs_json:\n            configs_json[\"method\"] = \"service-account\"\n            configs_json[\"keyfile\"] = str(configs_json[\"keyfile\"])\n        else:\n            configs_json[\"method\"] = \"oauth-secrets\"\n            # through gcloud application-default login\n            google_credentials = (\n                self_copy.credentials.get_credentials_from_service_account()\n            )\n            if hasattr(google_credentials, \"token\"):\n                request = Request()\n                google_credentials.refresh(request)\n                configs_json[\"token\"] = google_credentials.token\n            else:\n                for key in (\"refresh_token\", \"client_id\", \"client_secret\", \"token_uri\"):\n                    configs_json[key] = getattr(google_credentials, key)\n\n        if \"project\" not in configs_json:\n            raise ValueError(\n                \"The keyword, project, must be provided in either \"\n                \"GcpCredentials or BigQueryTargetConfigs\"\n            )\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/bigquery/#prefect_dbt.cli.configs.bigquery.BigQueryTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to BigQuery profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/bigquery.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to BigQuery profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    # since GcpCredentials will always define a project\n    self_copy = self.copy()\n    if self_copy.project is not None:\n        self_copy.credentials.project = None\n    all_configs_json = self._populate_configs_json(\n        {}, self_copy.__fields__, model=self_copy\n    )\n\n    # decouple prefect-gcp from prefect-dbt\n    # by mapping all the keys dbt gcp accepts\n    # https://docs.getdbt.com/reference/warehouse-setups/bigquery-setup\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"dataset\": \"schema\",\n        \"method\": \"method\",\n        \"project\": \"project\",\n        # service-account\n        \"service_account_file\": \"keyfile\",\n        # service-account json\n        \"service_account_info\": \"keyfile_json\",\n        # oauth secrets\n        \"refresh_token\": \"refresh_token\",\n        \"client_id\": \"client_id\",\n        \"client_secret\": \"client_secret\",\n        \"token_uri\": \"token_uri\",\n        # optional\n        \"priority\": \"priority\",\n        \"timeout_seconds\": \"timeout_seconds\",\n        \"location\": \"location\",\n        \"maximum_bytes_billed\": \"maximum_bytes_billed\",\n        \"scopes\": \"scopes\",\n        \"impersonate_service_account\": \"impersonate_service_account\",\n        \"execution_project\": \"execution_project\",\n    }\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n\n    if \"keyfile_json\" in configs_json:\n        configs_json[\"method\"] = \"service-account-json\"\n    elif \"keyfile\" in configs_json:\n        configs_json[\"method\"] = \"service-account\"\n        configs_json[\"keyfile\"] = str(configs_json[\"keyfile\"])\n    else:\n        configs_json[\"method\"] = \"oauth-secrets\"\n        # through gcloud application-default login\n        google_credentials = (\n            self_copy.credentials.get_credentials_from_service_account()\n        )\n        if hasattr(google_credentials, \"token\"):\n            request = Request()\n            google_credentials.refresh(request)\n            configs_json[\"token\"] = google_credentials.token\n        else:\n            for key in (\"refresh_token\", \"client_id\", \"client_secret\", \"token_uri\"):\n                configs_json[key] = getattr(google_credentials, key)\n\n    if \"project\" not in configs_json:\n        raise ValueError(\n            \"The keyword, project, must be provided in either \"\n            \"GcpCredentials or BigQueryTargetConfigs\"\n        )\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/","title":"Postgres","text":""},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres","title":"<code>prefect_dbt.cli.configs.postgres</code>","text":"<p>Module containing models for Postgres configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs","title":"<code>PostgresTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to Postgres. To find valid keys, head to the Postgres Profile page.</p> <p>Attributes:</p> Name Type Description <code>credentials</code> <code>Union[SqlAlchemyConnector, DatabaseCredentials]</code> <p>The credentials to use to authenticate; if there are duplicate keys between credentials and TargetConfigs, e.g. schema, an error will be raised.</p> <p>Examples:</p> <p>Load stored PostgresTargetConfigs: <pre><code>from prefect_dbt.cli.configs import PostgresTargetConfigs\n\npostgres_target_configs = PostgresTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate PostgresTargetConfigs with DatabaseCredentials. <pre><code>from prefect_dbt.cli.configs import PostgresTargetConfigs\nfrom prefect_sqlalchemy import DatabaseCredentials, SyncDriver\n\ncredentials = DatabaseCredentials(\n    driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n    username=\"prefect\",\n    password=\"prefect_password\",\n    database=\"postgres\",\n    host=\"host\",\n    port=8080\n)\ntarget_configs = PostgresTargetConfigs(credentials=credentials, schema=\"schema\")\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/postgres.py</code> <pre><code>class PostgresTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to Postgres.\n    To find valid keys, head to the [Postgres Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/postgres-profile)\n    page.\n\n    Attributes:\n        credentials: The credentials to use to authenticate; if there are\n            duplicate keys between credentials and TargetConfigs,\n            e.g. schema, an error will be raised.\n\n    Examples:\n        Load stored PostgresTargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import PostgresTargetConfigs\n\n        postgres_target_configs = PostgresTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate PostgresTargetConfigs with DatabaseCredentials.\n        ```python\n        from prefect_dbt.cli.configs import PostgresTargetConfigs\n        from prefect_sqlalchemy import DatabaseCredentials, SyncDriver\n\n        credentials = DatabaseCredentials(\n            driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n            username=\"prefect\",\n            password=\"prefect_password\",\n            database=\"postgres\",\n            host=\"host\",\n            port=8080\n        )\n        target_configs = PostgresTargetConfigs(credentials=credentials, schema=\"schema\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Postgres Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _description = \"dbt CLI target configs containing credentials and settings specific to Postgres.\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs\"  # noqa\n\n    type: Literal[\"postgres\"] = Field(\n        default=\"postgres\", description=\"The type of the target.\"\n    )\n    credentials: Union[SqlAlchemyConnector, DatabaseCredentials] = Field(\n        default=...,\n        description=(\n            \"The credentials to use to authenticate; if there are duplicate keys \"\n            \"between credentials and TargetConfigs, e.g. schema, \"\n            \"an error will be raised.\"\n        ),\n    )  # noqa\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to Postgres profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        if isinstance(self.credentials, DatabaseCredentials):\n            warnings.warn(\n                \"Using DatabaseCredentials is deprecated and will be removed \"\n                \"on May 7th, 2023, use SqlAlchemyConnector instead.\",\n                DeprecationWarning,\n            )\n        all_configs_json = super().get_configs()\n\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"host\": \"host\",\n            \"username\": \"user\",\n            \"password\": \"password\",\n            \"port\": \"port\",\n            \"database\": \"dbname\",\n            # optional\n            \"keepalives_idle\": \"keepalives_idle\",\n            \"connect_timeout\": \"connect_timeout\",\n            \"retries\": \"retries\",\n            \"search_path\": \"search_path\",\n            \"role\": \"role\",\n            \"sslmode\": \"sslmode\",\n        }\n\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys, like fetch_size + poll_frequency_s\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n        port = configs_json.get(\"port\")\n        if port is not None:\n            configs_json[\"port\"] = int(port)\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/postgres/#prefect_dbt.cli.configs.postgres.PostgresTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to Postgres profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/postgres.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to Postgres profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    if isinstance(self.credentials, DatabaseCredentials):\n        warnings.warn(\n            \"Using DatabaseCredentials is deprecated and will be removed \"\n            \"on May 7th, 2023, use SqlAlchemyConnector instead.\",\n            DeprecationWarning,\n        )\n    all_configs_json = super().get_configs()\n\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"host\": \"host\",\n        \"username\": \"user\",\n        \"password\": \"password\",\n        \"port\": \"port\",\n        \"database\": \"dbname\",\n        # optional\n        \"keepalives_idle\": \"keepalives_idle\",\n        \"connect_timeout\": \"connect_timeout\",\n        \"retries\": \"retries\",\n        \"search_path\": \"search_path\",\n        \"role\": \"role\",\n        \"sslmode\": \"sslmode\",\n    }\n\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys, like fetch_size + poll_frequency_s\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n    port = configs_json.get(\"port\")\n    if port is not None:\n        configs_json[\"port\"] = int(port)\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/","title":"Snowflake","text":""},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake","title":"<code>prefect_dbt.cli.configs.snowflake</code>","text":"<p>Module containing models for Snowflake configs</p>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs","title":"<code>SnowflakeTargetConfigs</code>","text":"<p>               Bases: <code>BaseTargetConfigs</code></p> <p>Target configs contain credentials and settings, specific to Snowflake. To find valid keys, head to the Snowflake Profile page.</p> <p>Attributes:</p> Name Type Description <code>connector</code> <code>SnowflakeConnector</code> <p>The connector to use.</p> <p>Examples:</p> <p>Load stored SnowflakeTargetConfigs: <pre><code>from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n\nsnowflake_target_configs = SnowflakeTargetConfigs.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Instantiate SnowflakeTargetConfigs. <pre><code>from prefect_dbt.cli.configs import SnowflakeTargetConfigs\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\ncredentials = SnowflakeCredentials(\n    user=\"user\",\n    password=\"password\",\n    account=\"account.region.aws\",\n    role=\"role\",\n)\nconnector = SnowflakeConnector(\n    schema=\"public\",\n    database=\"database\",\n    warehouse=\"warehouse\",\n    credentials=credentials,\n)\ntarget_configs = SnowflakeTargetConfigs(\n    connector=connector,\n    extras={\"retry_on_database_errors\": True},\n)\n</code></pre></p> Source code in <code>prefect_dbt/cli/configs/snowflake.py</code> <pre><code>class SnowflakeTargetConfigs(BaseTargetConfigs):\n    \"\"\"\n    Target configs contain credentials and\n    settings, specific to Snowflake.\n    To find valid keys, head to the [Snowflake Profile](\n    https://docs.getdbt.com/reference/warehouse-profiles/snowflake-profile)\n    page.\n\n    Attributes:\n        connector: The connector to use.\n\n    Examples:\n        Load stored SnowflakeTargetConfigs:\n        ```python\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n\n        snowflake_target_configs = SnowflakeTargetConfigs.load(\"BLOCK_NAME\")\n        ```\n\n        Instantiate SnowflakeTargetConfigs.\n        ```python\n        from prefect_dbt.cli.configs import SnowflakeTargetConfigs\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        credentials = SnowflakeCredentials(\n            user=\"user\",\n            password=\"password\",\n            account=\"account.region.aws\",\n            role=\"role\",\n        )\n        connector = SnowflakeConnector(\n            schema=\"public\",\n            database=\"database\",\n            warehouse=\"warehouse\",\n            credentials=credentials,\n        )\n        target_configs = SnowflakeTargetConfigs(\n            connector=connector,\n            extras={\"retry_on_database_errors\": True},\n        )\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt CLI Snowflake Target Configs\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs\"  # noqa\n\n    type: Literal[\"snowflake\"] = Field(\n        default=\"snowflake\", description=\"The type of the target configs.\"\n    )\n    schema_: Optional[str] = Field(\n        default=None,\n        alias=\"schema\",\n        description=\"The schema to use for the target configs.\",\n    )\n    connector: SnowflakeConnector = Field(\n        default=..., description=\"The connector to use.\"\n    )\n\n    def get_configs(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Returns the dbt configs specific to Snowflake profile.\n\n        Returns:\n            A configs JSON.\n        \"\"\"\n        all_configs_json = super().get_configs()\n\n        # decouple prefect-snowflake from prefect-dbt\n        # by mapping all the keys dbt snowflake accepts\n        # https://docs.getdbt.com/reference/warehouse-setups/snowflake-setup\n        rename_keys = {\n            # dbt\n            \"type\": \"type\",\n            \"schema\": \"schema\",\n            \"threads\": \"threads\",\n            # general\n            \"account\": \"account\",\n            \"user\": \"user\",\n            \"role\": \"role\",\n            \"database\": \"database\",\n            \"warehouse\": \"warehouse\",\n            # user and password\n            \"password\": \"password\",\n            # duo mfa / sso\n            \"authenticator\": \"authenticator\",\n            # key pair\n            \"private_key_path\": \"private_key_path\",\n            \"private_key_passphrase\": \"private_key_passphrase\",\n            # optional\n            \"client_session_keep_alive\": \"client_session_keep_alive\",\n            \"query_tag\": \"query_tag\",\n            \"connect_retries\": \"connect_retries\",\n            \"connect_timeout\": \"connect_timeout\",\n            \"retry_on_database_errors\": \"retry_on_database_errors\",\n            \"retry_all\": \"retry_all\",\n        }\n        configs_json = {}\n        extras = self.extras or {}\n        for key in all_configs_json.keys():\n            if key not in rename_keys and key not in extras:\n                # skip invalid keys, like fetch_size + poll_frequency_s\n                continue\n            # rename key to something dbt profile expects\n            dbt_key = rename_keys.get(key) or key\n            configs_json[dbt_key] = all_configs_json[key]\n        return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cli/configs/snowflake/#prefect_dbt.cli.configs.snowflake.SnowflakeTargetConfigs.get_configs","title":"<code>get_configs</code>","text":"<p>Returns the dbt configs specific to Snowflake profile.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A configs JSON.</p> Source code in <code>prefect_dbt/cli/configs/snowflake.py</code> <pre><code>def get_configs(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Returns the dbt configs specific to Snowflake profile.\n\n    Returns:\n        A configs JSON.\n    \"\"\"\n    all_configs_json = super().get_configs()\n\n    # decouple prefect-snowflake from prefect-dbt\n    # by mapping all the keys dbt snowflake accepts\n    # https://docs.getdbt.com/reference/warehouse-setups/snowflake-setup\n    rename_keys = {\n        # dbt\n        \"type\": \"type\",\n        \"schema\": \"schema\",\n        \"threads\": \"threads\",\n        # general\n        \"account\": \"account\",\n        \"user\": \"user\",\n        \"role\": \"role\",\n        \"database\": \"database\",\n        \"warehouse\": \"warehouse\",\n        # user and password\n        \"password\": \"password\",\n        # duo mfa / sso\n        \"authenticator\": \"authenticator\",\n        # key pair\n        \"private_key_path\": \"private_key_path\",\n        \"private_key_passphrase\": \"private_key_passphrase\",\n        # optional\n        \"client_session_keep_alive\": \"client_session_keep_alive\",\n        \"query_tag\": \"query_tag\",\n        \"connect_retries\": \"connect_retries\",\n        \"connect_timeout\": \"connect_timeout\",\n        \"retry_on_database_errors\": \"retry_on_database_errors\",\n        \"retry_all\": \"retry_all\",\n    }\n    configs_json = {}\n    extras = self.extras or {}\n    for key in all_configs_json.keys():\n        if key not in rename_keys and key not in extras:\n            # skip invalid keys, like fetch_size + poll_frequency_s\n            continue\n        # rename key to something dbt profile expects\n        dbt_key = rename_keys.get(key) or key\n        configs_json[dbt_key] = all_configs_json[key]\n    return configs_json\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/","title":"Clients","text":""},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients","title":"<code>prefect_dbt.cloud.clients</code>","text":"<p>Module containing clients for interacting with the dbt Cloud API</p>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient","title":"<code>DbtCloudAdministrativeClient</code>","text":"<p>Client for interacting with the dbt cloud Administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>api_key</code> <code>str</code> <p>API key to authenticate with the dbt Cloud administrative API.</p> required <code>account_id</code> <code>int</code> <p>ID of dbt Cloud account with which to interact.</p> required <code>domain</code> <code>str</code> <p>Domain at which the dbt Cloud API is hosted.</p> <code>'cloud.getdbt.com'</code> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>class DbtCloudAdministrativeClient:\n    \"\"\"\n    Client for interacting with the dbt cloud Administrative API.\n\n    Args:\n        api_key: API key to authenticate with the dbt Cloud administrative API.\n        account_id: ID of dbt Cloud account with which to interact.\n        domain: Domain at which the dbt Cloud API is hosted.\n    \"\"\"\n\n    def __init__(self, api_key: str, account_id: int, domain: str = \"cloud.getdbt.com\"):\n        self._closed = False\n        self._started = False\n\n        self._admin_client = AsyncClient(\n            headers={\n                \"Authorization\": f\"Bearer {api_key}\",\n                \"user-agent\": f\"prefect-{prefect.__version__}\",\n                \"x-dbt-partner-source\": \"prefect\",\n            },\n            base_url=f\"https://{domain}/api/v2/accounts/{account_id}\",\n        )\n\n    async def call_endpoint(\n        self,\n        http_method: str,\n        path: str,\n        params: Optional[Dict[str, Any]] = None,\n        json: Optional[Dict[str, Any]] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Call an endpoint in the dbt Cloud API.\n\n        Args:\n            path: The partial path for the request (e.g. /projects/). Will be appended\n                onto the base URL as determined by the client configuration.\n            http_method: HTTP method to call on the endpoint.\n            params: Query parameters to include in the request.\n            json: JSON serializable body to send in the request.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"\n        response = await self._admin_client.request(\n            method=http_method, url=path, params=params, json=json\n        )\n\n        response.raise_for_status()\n\n        return response\n\n    async def get_job(\n        self,\n        job_id: int,\n        order_by: Optional[str] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Return job details for a job on an account.\n\n        Args:\n            job_id: Numeric ID of the job.\n            order_by: Field to order the result by. Use - to indicate reverse order.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"order_by\": order_by} if order_by else None\n        return await self.call_endpoint(\n            path=f\"/jobs/{job_id}/\", http_method=\"GET\", params=params\n        )\n\n    async def trigger_job_run(\n        self, job_id: int, options: Optional[TriggerJobRunOptions] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [trigger job run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun)\n        to initiate a job run.\n\n        Args:\n            job_id: The ID of the job to trigger.\n            options: An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        if options is None:\n            options = TriggerJobRunOptions()\n\n        return await self.call_endpoint(\n            path=f\"/jobs/{job_id}/run/\",\n            http_method=\"POST\",\n            json=options.dict(exclude_none=True),\n        )\n\n    async def get_run(\n        self,\n        run_id: int,\n        include_related: Optional[\n            List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n        ] = None,\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [get run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById)\n        to get details about a job run.\n\n        Args:\n            run_id: The ID of the run to get details for.\n            include_related: List of related fields to pull with the run.\n                Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n                If \"debug_logs\" is not provided in a request, then the included debug\n                logs will be truncated to the last 1,000 lines of the debug log output file.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"include_related\": include_related} if include_related else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/\", http_method=\"GET\", params=params\n        )\n\n    async def list_run_artifacts(\n        self, run_id: int, step: Optional[int] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [list run artifacts endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId)\n        to fetch a list of paths of artifacts generated for a completed run.\n\n        Args:\n            run_id: The ID of the run to list run artifacts for.\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"step\": step} if step else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/artifacts/\", http_method=\"GET\", params=params\n        )\n\n    async def get_run_artifact(\n        self, run_id: int, path: str, step: Optional[int] = None\n    ) -&gt; Response:\n        \"\"\"\n        Sends a request to the [get run artifact endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId)\n        to fetch an artifact generated for a completed run.\n\n        Args:\n            run_id: The ID of the run to list run artifacts for.\n            path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n                run_results.json)\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The response from the dbt Cloud administrative API.\n        \"\"\"  # noqa\n        params = {\"step\": step} if step else None\n        return await self.call_endpoint(\n            path=f\"/runs/{run_id}/artifacts/{path}\", http_method=\"GET\", params=params\n        )\n\n    async def __aenter__(self):\n        if self._closed:\n            raise RuntimeError(\n                \"The client cannot be started again after it has been closed.\"\n            )\n        if self._started:\n            raise RuntimeError(\"The client cannot be started more than once.\")\n\n        self._started = True\n\n        return self\n\n    async def __aexit__(self, *exc):\n        self._closed = True\n        await self._admin_client.__aexit__()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.call_endpoint","title":"<code>call_endpoint</code>  <code>async</code>","text":"<p>Call an endpoint in the dbt Cloud API.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The partial path for the request (e.g. /projects/). Will be appended onto the base URL as determined by the client configuration.</p> required <code>http_method</code> <code>str</code> <p>HTTP method to call on the endpoint.</p> required <code>params</code> <code>Optional[Dict[str, Any]]</code> <p>Query parameters to include in the request.</p> <code>None</code> <code>json</code> <code>Optional[Dict[str, Any]]</code> <p>JSON serializable body to send in the request.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def call_endpoint(\n    self,\n    http_method: str,\n    path: str,\n    params: Optional[Dict[str, Any]] = None,\n    json: Optional[Dict[str, Any]] = None,\n) -&gt; Response:\n    \"\"\"\n    Call an endpoint in the dbt Cloud API.\n\n    Args:\n        path: The partial path for the request (e.g. /projects/). Will be appended\n            onto the base URL as determined by the client configuration.\n        http_method: HTTP method to call on the endpoint.\n        params: Query parameters to include in the request.\n        json: JSON serializable body to send in the request.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"\n    response = await self._admin_client.request(\n        method=http_method, url=path, params=params, json=json\n    )\n\n    response.raise_for_status()\n\n    return response\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_job","title":"<code>get_job</code>  <code>async</code>","text":"<p>Return job details for a job on an account.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>Numeric ID of the job.</p> required <code>order_by</code> <code>Optional[str]</code> <p>Field to order the result by. Use - to indicate reverse order.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_job(\n    self,\n    job_id: int,\n    order_by: Optional[str] = None,\n) -&gt; Response:\n    \"\"\"\n    Return job details for a job on an account.\n\n    Args:\n        job_id: Numeric ID of the job.\n        order_by: Field to order the result by. Use - to indicate reverse order.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"order_by\": order_by} if order_by else None\n    return await self.call_endpoint(\n        path=f\"/jobs/{job_id}/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run","title":"<code>get_run</code>  <code>async</code>","text":"<p>Sends a request to the get run endpoint to get details about a job run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to get details for.</p> required <code>include_related</code> <code>Optional[List[Literal['trigger', 'job', 'debug_logs', 'run_steps']]]</code> <p>List of related fields to pull with the run. Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\". If \"debug_logs\" is not provided in a request, then the included debug logs will be truncated to the last 1,000 lines of the debug log output file.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_run(\n    self,\n    run_id: int,\n    include_related: Optional[\n        List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n    ] = None,\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [get run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getRunById)\n    to get details about a job run.\n\n    Args:\n        run_id: The ID of the run to get details for.\n        include_related: List of related fields to pull with the run.\n            Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n            If \"debug_logs\" is not provided in a request, then the included debug\n            logs will be truncated to the last 1,000 lines of the debug log output file.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"include_related\": include_related} if include_related else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.get_run_artifact","title":"<code>get_run_artifact</code>  <code>async</code>","text":"<p>Sends a request to the get run artifact endpoint to fetch an artifact generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>path</code> <code>str</code> <p>The relative path to the run artifact (e.g. manifest.json, catalog.json, run_results.json)</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def get_run_artifact(\n    self, run_id: int, path: str, step: Optional[int] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [get run artifact endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/getArtifactsByRunId)\n    to fetch an artifact generated for a completed run.\n\n    Args:\n        run_id: The ID of the run to list run artifacts for.\n        path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n            run_results.json)\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"step\": step} if step else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/artifacts/{path}\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.list_run_artifacts","title":"<code>list_run_artifacts</code>  <code>async</code>","text":"<p>Sends a request to the list run artifacts endpoint to fetch a list of paths of artifacts generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def list_run_artifacts(\n    self, run_id: int, step: Optional[int] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [list run artifacts endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Runs/operation/listArtifactsByRunId)\n    to fetch a list of paths of artifacts generated for a completed run.\n\n    Args:\n        run_id: The ID of the run to list run artifacts for.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    params = {\"step\": step} if step else None\n    return await self.call_endpoint(\n        path=f\"/runs/{run_id}/artifacts/\", http_method=\"GET\", params=params\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudAdministrativeClient.trigger_job_run","title":"<code>trigger_job_run</code>  <code>async</code>","text":"<p>Sends a request to the trigger job run endpoint to initiate a job run.</p> <p>Parameters:</p> Name Type Description Default <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Response</code> <p>The response from the dbt Cloud administrative API.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>async def trigger_job_run(\n    self, job_id: int, options: Optional[TriggerJobRunOptions] = None\n) -&gt; Response:\n    \"\"\"\n    Sends a request to the [trigger job run endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#tag/Jobs/operation/triggerRun)\n    to initiate a job run.\n\n    Args:\n        job_id: The ID of the job to trigger.\n        options: An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.\n\n    Returns:\n        The response from the dbt Cloud administrative API.\n    \"\"\"  # noqa\n    if options is None:\n        options = TriggerJobRunOptions()\n\n    return await self.call_endpoint(\n        path=f\"/jobs/{job_id}/run/\",\n        http_method=\"POST\",\n        json=options.dict(exclude_none=True),\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudMetadataClient","title":"<code>DbtCloudMetadataClient</code>","text":"<p>Client for interacting with the dbt cloud Administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>api_key</code> <code>str</code> <p>API key to authenticate with the dbt Cloud administrative API.</p> required <code>domain</code> <code>str</code> <p>Domain at which the dbt Cloud API is hosted.</p> <code>'metadata.cloud.getdbt.com'</code> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>class DbtCloudMetadataClient:\n    \"\"\"\n    Client for interacting with the dbt cloud Administrative API.\n\n    Args:\n        api_key: API key to authenticate with the dbt Cloud administrative API.\n        domain: Domain at which the dbt Cloud API is hosted.\n    \"\"\"\n\n    def __init__(self, api_key: str, domain: str = \"metadata.cloud.getdbt.com\"):\n        self._http_endpoint = HTTPEndpoint(\n            base_headers={\n                \"Authorization\": f\"Bearer {api_key}\",\n                \"user-agent\": f\"prefect-{prefect.__version__}\",\n                \"x-dbt-partner-source\": \"prefect\",\n                \"content-type\": \"application/json\",\n            },\n            url=f\"https://{domain}/graphql\",\n        )\n\n    def query(\n        self,\n        query: str,\n        variables: Optional[Dict] = None,\n        operation_name: Optional[str] = None,\n    ) -&gt; Dict[str, Any]:\n        \"\"\"\n        Run a GraphQL query against the dbt Cloud metadata API.\n\n        Args:\n            query: The GraphQL query to run.\n            variables: The values of any variables defined in the GraphQL query.\n            operation_name: The name of the operation to run if multiple operations\n                are defined in the provided query.\n\n        Returns:\n            The result of the GraphQL query.\n        \"\"\"\n        return self._http_endpoint(\n            query=query, variables=variables, operation_name=operation_name\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/clients/#prefect_dbt.cloud.clients.DbtCloudMetadataClient.query","title":"<code>query</code>","text":"<p>Run a GraphQL query against the dbt Cloud metadata API.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The GraphQL query to run.</p> required <code>variables</code> <code>Optional[Dict]</code> <p>The values of any variables defined in the GraphQL query.</p> <code>None</code> <code>operation_name</code> <code>Optional[str]</code> <p>The name of the operation to run if multiple operations are defined in the provided query.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The result of the GraphQL query.</p> Source code in <code>prefect_dbt/cloud/clients.py</code> <pre><code>def query(\n    self,\n    query: str,\n    variables: Optional[Dict] = None,\n    operation_name: Optional[str] = None,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Run a GraphQL query against the dbt Cloud metadata API.\n\n    Args:\n        query: The GraphQL query to run.\n        variables: The values of any variables defined in the GraphQL query.\n        operation_name: The name of the operation to run if multiple operations\n            are defined in the provided query.\n\n    Returns:\n        The result of the GraphQL query.\n    \"\"\"\n    return self._http_endpoint(\n        query=query, variables=variables, operation_name=operation_name\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials","title":"<code>prefect_dbt.cloud.credentials</code>","text":"<p>Module containing credentials for interacting with dbt Cloud</p>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials","title":"<code>DbtCloudCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Credentials block for credential use across dbt Cloud tasks and flows.</p> <p>Attributes:</p> Name Type Description <code>api_key</code> <code>SecretStr</code> <p>API key to authenticate with the dbt Cloud administrative API. Refer to the Authentication docs for retrieving the API key.</p> <code>account_id</code> <code>int</code> <p>ID of dbt Cloud account with which to interact.</p> <code>domain</code> <code>Optional[str]</code> <p>Domain at which the dbt Cloud API is hosted.</p> <p>Examples:</p> <p>Load stored dbt Cloud credentials: <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\ndbt_cloud_credentials = DbtCloudCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Use DbtCloudCredentials instance to trigger a job run: <pre><code>from prefect_dbt.cloud import DbtCloudCredentials\n\ncredentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\nasync with dbt_cloud_credentials.get_administrative_client() as client:\n    client.trigger_job_run(job_id=1)\n</code></pre></p> <p>Load saved dbt Cloud credentials within a flow: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials.load(\"my-dbt-credentials\")\n    trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\ntrigger_dbt_cloud_job_run_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>class DbtCloudCredentials(CredentialsBlock):\n    \"\"\"\n    Credentials block for credential use across dbt Cloud tasks and flows.\n\n    Attributes:\n        api_key (SecretStr): API key to authenticate with the dbt Cloud\n            administrative API. Refer to the [Authentication docs](\n            https://docs.getdbt.com/dbt-cloud/api-v2#section/Authentication)\n            for retrieving the API key.\n        account_id (int): ID of dbt Cloud account with which to interact.\n        domain (Optional[str]): Domain at which the dbt Cloud API is hosted.\n\n    Examples:\n        Load stored dbt Cloud credentials:\n        ```python\n        from prefect_dbt.cloud import DbtCloudCredentials\n\n        dbt_cloud_credentials = DbtCloudCredentials.load(\"BLOCK_NAME\")\n        ```\n\n        Use DbtCloudCredentials instance to trigger a job run:\n        ```python\n        from prefect_dbt.cloud import DbtCloudCredentials\n\n        credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            client.trigger_job_run(job_id=1)\n        ```\n\n        Load saved dbt Cloud credentials within a flow:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials.load(\"my-dbt-credentials\")\n            trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n        trigger_dbt_cloud_job_run_flow()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Cloud Credentials\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials\"  # noqa\n\n    api_key: SecretStr = Field(\n        default=...,\n        title=\"API Key\",\n        description=\"A dbt Cloud API key to use for authentication.\",\n    )\n    account_id: int = Field(\n        default=..., title=\"Account ID\", description=\"The ID of your dbt Cloud account.\"\n    )\n    domain: str = Field(\n        default=\"cloud.getdbt.com\",\n        description=\"The base domain of your dbt Cloud instance.\",\n    )\n\n    def get_administrative_client(self) -&gt; DbtCloudAdministrativeClient:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud\n        administrative API.\n\n        Returns:\n            An authenticated dbt Cloud administrative API client.\n        \"\"\"\n        return DbtCloudAdministrativeClient(\n            api_key=self.api_key.get_secret_value(),\n            account_id=self.account_id,\n            domain=self.domain,\n        )\n\n    def get_metadata_client(self) -&gt; DbtCloudMetadataClient:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud\n        metadata API.\n\n        Example:\n            Sending queries via the returned metadata client:\n            ```python\n            from prefect_dbt import DbtCloudCredentials\n\n            credentials_block = DbtCloudCredentials.load(\"test-account\")\n            metadata_client = credentials_block.get_metadata_client()\n            query = \\\"\\\"\\\"\n            {\n                metrics(jobId: 123) {\n                    uniqueId\n                    name\n                    packageName\n                    tags\n                    label\n                    runId\n                    description\n                    type\n                    sql\n                    timestamp\n                    timeGrains\n                    dimensions\n                    meta\n                    resourceType\n                    filters {\n                        field\n                        operator\n                        value\n                    }\n                    model {\n                        name\n                    }\n                }\n            }\n            \\\"\\\"\\\"\n            metadata_client.query(query)\n            # Result:\n            # {\n            #   \"data\": {\n            #     \"metrics\": [\n            #       {\n            #         \"uniqueId\": \"metric.tpch.total_revenue\",\n            #         \"name\": \"total_revenue\",\n            #         \"packageName\": \"tpch\",\n            #         \"tags\": [],\n            #         \"label\": \"Total Revenue ($)\",\n            #         \"runId\": 108952046,\n            #         \"description\": \"\",\n            #         \"type\": \"sum\",\n            #         \"sql\": \"net_item_sales_amount\",\n            #         \"timestamp\": \"order_date\",\n            #         \"timeGrains\": [\"day\", \"week\", \"month\"],\n            #         \"dimensions\": [\"status_code\", \"priority_code\"],\n            #         \"meta\": {},\n            #         \"resourceType\": \"metric\",\n            #         \"filters\": [],\n            #         \"model\": { \"name\": \"fct_orders\" }\n            #       }\n            #     ]\n            #   }\n            # }\n            ```\n\n        Returns:\n            An authenticated dbt Cloud metadata API client.\n        \"\"\"\n        return DbtCloudMetadataClient(\n            api_key=self.api_key.get_secret_value(),\n            domain=f\"metadata.{self.domain}\",\n        )\n\n    def get_client(\n        self, client_type: Literal[\"administrative\", \"metadata\"]\n    ) -&gt; Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]:\n        \"\"\"\n        Returns a newly instantiated client for working with the dbt Cloud API.\n\n        Args:\n            client_type: Type of client to return. Accepts either 'administrative'\n                or 'metadata'.\n\n        Returns:\n            The authenticated client of the requested type.\n        \"\"\"\n        get_client_method = getattr(self, f\"get_{client_type}_client\", None)\n        if get_client_method is None:\n            raise ValueError(f\"'{client_type}' is not a supported client type.\")\n        return get_client_method()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_administrative_client","title":"<code>get_administrative_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud administrative API.</p> <p>Returns:</p> Type Description <code>DbtCloudAdministrativeClient</code> <p>An authenticated dbt Cloud administrative API client.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_administrative_client(self) -&gt; DbtCloudAdministrativeClient:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud\n    administrative API.\n\n    Returns:\n        An authenticated dbt Cloud administrative API client.\n    \"\"\"\n    return DbtCloudAdministrativeClient(\n        api_key=self.api_key.get_secret_value(),\n        account_id=self.account_id,\n        domain=self.domain,\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud API.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['administrative', 'metadata']</code> <p>Type of client to return. Accepts either 'administrative' or 'metadata'.</p> required <p>Returns:</p> Type Description <code>Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]</code> <p>The authenticated client of the requested type.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_client(\n    self, client_type: Literal[\"administrative\", \"metadata\"]\n) -&gt; Union[DbtCloudAdministrativeClient, DbtCloudMetadataClient]:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud API.\n\n    Args:\n        client_type: Type of client to return. Accepts either 'administrative'\n            or 'metadata'.\n\n    Returns:\n        The authenticated client of the requested type.\n    \"\"\"\n    get_client_method = getattr(self, f\"get_{client_type}_client\", None)\n    if get_client_method is None:\n        raise ValueError(f\"'{client_type}' is not a supported client type.\")\n    return get_client_method()\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/credentials/#prefect_dbt.cloud.credentials.DbtCloudCredentials.get_metadata_client","title":"<code>get_metadata_client</code>","text":"<p>Returns a newly instantiated client for working with the dbt Cloud metadata API.</p> Example <p>Sending queries via the returned metadata client: <pre><code>from prefect_dbt import DbtCloudCredentials\n\ncredentials_block = DbtCloudCredentials.load(\"test-account\")\nmetadata_client = credentials_block.get_metadata_client()\nquery = \"\"\"\n{\n    metrics(jobId: 123) {\n        uniqueId\n        name\n        packageName\n        tags\n        label\n        runId\n        description\n        type\n        sql\n        timestamp\n        timeGrains\n        dimensions\n        meta\n        resourceType\n        filters {\n            field\n            operator\n            value\n        }\n        model {\n            name\n        }\n    }\n}\n\"\"\"\nmetadata_client.query(query)\n# Result:\n# {\n#   \"data\": {\n#     \"metrics\": [\n#       {\n#         \"uniqueId\": \"metric.tpch.total_revenue\",\n#         \"name\": \"total_revenue\",\n#         \"packageName\": \"tpch\",\n#         \"tags\": [],\n#         \"label\": \"Total Revenue ($)\",\n#         \"runId\": 108952046,\n#         \"description\": \"\",\n#         \"type\": \"sum\",\n#         \"sql\": \"net_item_sales_amount\",\n#         \"timestamp\": \"order_date\",\n#         \"timeGrains\": [\"day\", \"week\", \"month\"],\n#         \"dimensions\": [\"status_code\", \"priority_code\"],\n#         \"meta\": {},\n#         \"resourceType\": \"metric\",\n#         \"filters\": [],\n#         \"model\": { \"name\": \"fct_orders\" }\n#       }\n#     ]\n#   }\n# }\n</code></pre></p> <p>Returns:</p> Type Description <code>DbtCloudMetadataClient</code> <p>An authenticated dbt Cloud metadata API client.</p> Source code in <code>prefect_dbt/cloud/credentials.py</code> <pre><code>def get_metadata_client(self) -&gt; DbtCloudMetadataClient:\n    \"\"\"\n    Returns a newly instantiated client for working with the dbt Cloud\n    metadata API.\n\n    Example:\n        Sending queries via the returned metadata client:\n        ```python\n        from prefect_dbt import DbtCloudCredentials\n\n        credentials_block = DbtCloudCredentials.load(\"test-account\")\n        metadata_client = credentials_block.get_metadata_client()\n        query = \\\"\\\"\\\"\n        {\n            metrics(jobId: 123) {\n                uniqueId\n                name\n                packageName\n                tags\n                label\n                runId\n                description\n                type\n                sql\n                timestamp\n                timeGrains\n                dimensions\n                meta\n                resourceType\n                filters {\n                    field\n                    operator\n                    value\n                }\n                model {\n                    name\n                }\n            }\n        }\n        \\\"\\\"\\\"\n        metadata_client.query(query)\n        # Result:\n        # {\n        #   \"data\": {\n        #     \"metrics\": [\n        #       {\n        #         \"uniqueId\": \"metric.tpch.total_revenue\",\n        #         \"name\": \"total_revenue\",\n        #         \"packageName\": \"tpch\",\n        #         \"tags\": [],\n        #         \"label\": \"Total Revenue ($)\",\n        #         \"runId\": 108952046,\n        #         \"description\": \"\",\n        #         \"type\": \"sum\",\n        #         \"sql\": \"net_item_sales_amount\",\n        #         \"timestamp\": \"order_date\",\n        #         \"timeGrains\": [\"day\", \"week\", \"month\"],\n        #         \"dimensions\": [\"status_code\", \"priority_code\"],\n        #         \"meta\": {},\n        #         \"resourceType\": \"metric\",\n        #         \"filters\": [],\n        #         \"model\": { \"name\": \"fct_orders\" }\n        #       }\n        #     ]\n        #   }\n        # }\n        ```\n\n    Returns:\n        An authenticated dbt Cloud metadata API client.\n    \"\"\"\n    return DbtCloudMetadataClient(\n        api_key=self.api_key.get_secret_value(),\n        domain=f\"metadata.{self.domain}\",\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs","title":"<code>prefect_dbt.cloud.jobs</code>","text":"<p>Module containing tasks and flows for interacting with dbt Cloud jobs</p>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob","title":"<code>DbtCloudJob</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>Block that holds the information and methods to interact with a dbt Cloud job.</p> <p>Attributes:</p> Name Type Description <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>The credentials to use to authenticate with dbt Cloud.</p> <code>job_id</code> <code>int</code> <p>The id of the dbt Cloud job.</p> <code>timeout_seconds</code> <code>int</code> <p>The number of seconds to wait for the job to complete.</p> <code>interval_seconds</code> <code>int</code> <p>The number of seconds to wait between polling for job completion.</p> <code>trigger_job_run_options</code> <code>TriggerJobRunOptions</code> <p>The options to use when triggering a job run.</p> <p>Examples:</p> <p>Load a configured dbt Cloud job block. <pre><code>from prefect_dbt.cloud import DbtCloudJob\n\ndbt_cloud_job = DbtCloudJob.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Triggers a dbt Cloud job, waits for completion, and fetches the results. <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\n@flow\ndef dbt_cloud_job_flow():\n    dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n    dbt_cloud_job = DbtCloudJob.load(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=154217\n    )\n    dbt_cloud_job_run = dbt_cloud_job.trigger()\n    dbt_cloud_job_run.wait_for_completion()\n    dbt_cloud_job_run.fetch_result()\n    return dbt_cloud_job_run\n\ndbt_cloud_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>class DbtCloudJob(JobBlock):\n    \"\"\"\n    Block that holds the information and methods to interact with a dbt Cloud job.\n\n    Attributes:\n        dbt_cloud_credentials: The credentials to use to authenticate with dbt Cloud.\n        job_id: The id of the dbt Cloud job.\n        timeout_seconds: The number of seconds to wait for the job to complete.\n        interval_seconds:\n            The number of seconds to wait between polling for job completion.\n        trigger_job_run_options: The options to use when triggering a job run.\n\n    Examples:\n        Load a configured dbt Cloud job block.\n        ```python\n        from prefect_dbt.cloud import DbtCloudJob\n\n        dbt_cloud_job = DbtCloudJob.load(\"BLOCK_NAME\")\n        ```\n\n        Triggers a dbt Cloud job, waits for completion, and fetches the results.\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n\n        @flow\n        def dbt_cloud_job_flow():\n            dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n            dbt_cloud_job = DbtCloudJob.load(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                job_id=154217\n            )\n            dbt_cloud_job_run = dbt_cloud_job.trigger()\n            dbt_cloud_job_run.wait_for_completion()\n            dbt_cloud_job_run.fetch_result()\n            return dbt_cloud_job_run\n\n        dbt_cloud_job_flow()\n        ```\n    \"\"\"\n\n    _block_type_name = \"dbt Cloud Job\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/5zE9lxfzBHjw3tnEup4wWL/9a001902ed43a84c6c96d23b24622e19/dbt-bit_tm.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob\"  # noqa\n\n    dbt_cloud_credentials: DbtCloudCredentials = Field(\n        default=...,\n        description=\"The dbt Cloud credentials to use to authenticate with dbt Cloud.\",\n    )  # noqa: E501\n    job_id: int = Field(\n        default=..., description=\"The id of the dbt Cloud job.\", title=\"Job ID\"\n    )\n    timeout_seconds: int = Field(\n        default=900,\n        description=\"The number of seconds to wait for the job to complete.\",\n    )\n    interval_seconds: int = Field(\n        default=10,\n        description=\"The number of seconds to wait between polling for job completion.\",\n    )\n    trigger_job_run_options: TriggerJobRunOptions = Field(\n        default_factory=TriggerJobRunOptions,\n        description=\"The options to use when triggering a job run.\",\n    )\n\n    @sync_compatible\n    async def get_job(self, order_by: Optional[str] = None) -&gt; Dict[str, Any]:\n        \"\"\"\n        Retrieve information about a dbt Cloud job.\n\n        Args:\n            order_by: The field to order the results by.\n\n        Returns:\n            The job data.\n        \"\"\"\n        try:\n            async with self.dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_job(\n                    job_id=self.job_id,\n                    order_by=order_by,\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n        return response.json()[\"data\"]\n\n    @sync_compatible\n    async def trigger(\n        self, trigger_job_run_options: Optional[TriggerJobRunOptions] = None\n    ) -&gt; DbtCloudJobRun:\n        \"\"\"\n        Triggers a dbt Cloud job.\n\n        Returns:\n            A representation of the dbt Cloud job run.\n        \"\"\"\n        try:\n            trigger_job_run_options = (\n                trigger_job_run_options or self.trigger_job_run_options\n            )\n            async with self.dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.trigger_job_run(\n                    job_id=self.job_id, options=trigger_job_run_options\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n        run_data = response.json()[\"data\"]\n        run_id = run_data.get(\"id\")\n        run = DbtCloudJobRun(\n            dbt_cloud_job=self,\n            run_id=run_id,\n        )\n        self.logger.info(\n            f\"dbt Cloud job {self.job_id} run {run_id} successfully triggered. \"\n            f\"You can view the status of this run at \"\n            f\"https://{self.dbt_cloud_credentials.domain}/#/accounts/\"\n            f\"{self.dbt_cloud_credentials.account_id}/projects/\"\n            f\"{run_data['project_id']}/runs/{run_id}/\"\n        )\n        return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob.get_job","title":"<code>get_job</code>  <code>async</code>","text":"<p>Retrieve information about a dbt Cloud job.</p> <p>Parameters:</p> Name Type Description Default <code>order_by</code> <code>Optional[str]</code> <p>The field to order the results by.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The job data.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_job(self, order_by: Optional[str] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Retrieve information about a dbt Cloud job.\n\n    Args:\n        order_by: The field to order the results by.\n\n    Returns:\n        The job data.\n    \"\"\"\n    try:\n        async with self.dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_job(\n                job_id=self.job_id,\n                order_by=order_by,\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJob.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Triggers a dbt Cloud job.</p> <p>Returns:</p> Type Description <code>DbtCloudJobRun</code> <p>A representation of the dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def trigger(\n    self, trigger_job_run_options: Optional[TriggerJobRunOptions] = None\n) -&gt; DbtCloudJobRun:\n    \"\"\"\n    Triggers a dbt Cloud job.\n\n    Returns:\n        A representation of the dbt Cloud job run.\n    \"\"\"\n    try:\n        trigger_job_run_options = (\n            trigger_job_run_options or self.trigger_job_run_options\n        )\n        async with self.dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.trigger_job_run(\n                job_id=self.job_id, options=trigger_job_run_options\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n    run_data = response.json()[\"data\"]\n    run_id = run_data.get(\"id\")\n    run = DbtCloudJobRun(\n        dbt_cloud_job=self,\n        run_id=run_id,\n    )\n    self.logger.info(\n        f\"dbt Cloud job {self.job_id} run {run_id} successfully triggered. \"\n        f\"You can view the status of this run at \"\n        f\"https://{self.dbt_cloud_credentials.domain}/#/accounts/\"\n        f\"{self.dbt_cloud_credentials.account_id}/projects/\"\n        f\"{run_data['project_id']}/runs/{run_id}/\"\n    )\n    return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun","title":"<code>DbtCloudJobRun</code>","text":"<p>               Bases: <code>JobRun</code></p> <p>Class that holds the information and methods to interact with the resulting run of a dbt Cloud job.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>class DbtCloudJobRun(JobRun):  # NOT A BLOCK\n    \"\"\"\n    Class that holds the information and methods to interact\n    with the resulting run of a dbt Cloud job.\n    \"\"\"\n\n    def __init__(self, run_id: int, dbt_cloud_job: \"DbtCloudJob\"):\n        self.run_id = run_id\n        self._dbt_cloud_job = dbt_cloud_job\n        self._dbt_cloud_credentials = dbt_cloud_job.dbt_cloud_credentials\n\n    @property\n    def _log_prefix(self):\n        return f\"dbt Cloud job {self._dbt_cloud_job.job_id} run {self.run_id}.\"\n\n    async def _wait_until_state(\n        self,\n        in_final_state_fn: Awaitable[Callable],\n        get_state_fn: Awaitable[Callable],\n        log_state_fn: Callable = None,\n        timeout_seconds: int = 60,\n        interval_seconds: int = 1,\n    ):\n        \"\"\"\n        Wait until the job run reaches a specific state.\n\n        Args:\n            in_final_state_fn: An async function that accepts a run state\n                and returns a boolean indicating whether the job run is\n                in a final state.\n            get_state_fn: An async function that returns\n                the current state of the job run.\n            log_state_fn: A callable that accepts a run\n                state and makes it human readable.\n            timeout_seconds: The maximum amount of time, in seconds, to wait\n                for the job run to reach the final state.\n            interval_seconds: The number of seconds to wait between checks of\n                the job run's state.\n        \"\"\"\n        start_time = time.time()\n        last_state = run_state = None\n        while not in_final_state_fn(run_state):\n            run_state = await get_state_fn()\n            if run_state != last_state:\n                if self.logger is not None:\n                    self.logger.info(\n                        \"%s has new state: %s\",\n                        self._log_prefix,\n                        log_state_fn(run_state),\n                    )\n                last_state = run_state\n\n            elapsed_time_seconds = time.time() - start_time\n            if elapsed_time_seconds &gt; timeout_seconds:\n                raise DbtCloudJobRunTimedOut(\n                    f\"Max wait time of {timeout_seconds} \"\n                    \"seconds exceeded while waiting\"\n                )\n            await asyncio.sleep(interval_seconds)\n\n    @sync_compatible\n    async def get_run(self) -&gt; Dict[str, Any]:\n        \"\"\"\n        Makes a request to the dbt Cloud API to get the run data.\n\n        Returns:\n            The run data.\n        \"\"\"\n        try:\n            dbt_cloud_credentials = self._dbt_cloud_credentials\n            async with dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_run(self.run_id)\n        except HTTPStatusError as ex:\n            raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n        run_data = response.json()[\"data\"]\n        return run_data\n\n    @sync_compatible\n    async def get_status_code(self) -&gt; int:\n        \"\"\"\n        Makes a request to the dbt Cloud API to get the run status.\n\n        Returns:\n            The run status code.\n        \"\"\"\n        run_data = await self.get_run()\n        run_status_code = run_data.get(\"status\")\n        return run_status_code\n\n    @sync_compatible\n    async def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Waits for the job run to reach a terminal state.\n        \"\"\"\n        await self._wait_until_state(\n            in_final_state_fn=DbtCloudJobRunStatus.is_terminal_status_code,\n            get_state_fn=self.get_status_code,\n            log_state_fn=DbtCloudJobRunStatus,\n            timeout_seconds=self._dbt_cloud_job.timeout_seconds,\n            interval_seconds=self._dbt_cloud_job.interval_seconds,\n        )\n\n    @sync_compatible\n    async def fetch_result(self, step: Optional[int] = None) -&gt; Dict[str, Any]:\n        \"\"\"\n        Gets the results from the job run. Since the results\n        may not be ready, use wait_for_completion before calling this method.\n\n        Args:\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n        \"\"\"\n        run_data = await self.get_run()\n        run_status = DbtCloudJobRunStatus(run_data.get(\"status\"))\n        if run_status == DbtCloudJobRunStatus.SUCCESS:\n            try:\n                async with self._dbt_cloud_credentials.get_administrative_client() as client:  # noqa\n                    response = await client.list_run_artifacts(\n                        run_id=self.run_id, step=step\n                    )\n                run_data[\"artifact_paths\"] = response.json()[\"data\"]\n                self.logger.info(\"%s completed successfully!\", self._log_prefix)\n            except HTTPStatusError as ex:\n                raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n            return run_data\n        elif run_status == DbtCloudJobRunStatus.CANCELLED:\n            raise DbtCloudJobRunCancelled(f\"{self._log_prefix} was cancelled.\")\n        elif run_status == DbtCloudJobRunStatus.FAILED:\n            raise DbtCloudJobRunFailed(f\"{self._log_prefix} has failed.\")\n        else:\n            raise DbtCloudJobRunIncomplete(\n                f\"{self._log_prefix} is still running; \"\n                \"use wait_for_completion() to wait until results are ready.\"\n            )\n\n    @sync_compatible\n    async def get_run_artifacts(\n        self,\n        path: Literal[\"manifest.json\", \"catalog.json\", \"run_results.json\"],\n        step: Optional[int] = None,\n    ) -&gt; Union[Dict[str, Any], str]:\n        \"\"\"\n        Get an artifact generated for a completed run.\n\n        Args:\n            path: The relative path to the run artifact.\n            step: The index of the step in the run to query for artifacts. The\n                first step in the run has the index 1. If the step parameter is\n                omitted, then this method will return the artifacts compiled\n                for the last step in the run.\n\n        Returns:\n            The contents of the requested manifest. Returns a `Dict` if the\n                requested artifact is a JSON file and a `str` otherwise.\n        \"\"\"\n        try:\n            dbt_cloud_credentials = self._dbt_cloud_credentials\n            async with dbt_cloud_credentials.get_administrative_client() as client:\n                response = await client.get_run_artifact(\n                    run_id=self.run_id, path=path, step=step\n                )\n        except HTTPStatusError as ex:\n            raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n        if path.endswith(\".json\"):\n            artifact_contents = response.json()\n        else:\n            artifact_contents = response.text\n        return artifact_contents\n\n    def _select_unsuccessful_commands(\n        self,\n        run_results: List[Dict[str, Any]],\n        command_components: List[str],\n        command: str,\n        exe_command: str,\n    ) -&gt; List[str]:\n        \"\"\"\n        Select nodes that were not successful and rebuild a command.\n        \"\"\"\n        # note \"fail\" here instead of \"cancelled\" because\n        # nodes do not have a cancelled state\n        run_nodes = \" \".join(\n            run_result[\"unique_id\"].split(\".\")[2]\n            for run_result in run_results\n            if run_result[\"status\"] in (\"error\", \"skipped\", \"fail\")\n        )\n\n        select_arg = None\n        if \"-s\" in command_components:\n            select_arg = \"-s\"\n        elif \"--select\" in command_components:\n            select_arg = \"--select\"\n\n        # prevent duplicate --select/-s statements\n        if select_arg is not None:\n            # dbt --fail-fast run, -s, bad_mod --vars '{\"env\": \"prod\"}' to:\n            # dbt --fail-fast run -s other_mod bad_mod --vars '{\"env\": \"prod\"}'\n            command_start, select_arg, command_end = command.partition(select_arg)\n            modified_command = f\"{command_start} {select_arg} {run_nodes} {command_end}\"  # noqa\n        else:\n            # dbt --fail-fast, build, --vars '{\"env\": \"prod\"}' to:\n            # dbt --fail-fast build --select bad_model --vars '{\"env\": \"prod\"}'\n            dbt_global_args, exe_command, exe_args = command.partition(exe_command)\n            modified_command = (\n                f\"{dbt_global_args} {exe_command} -s {run_nodes} {exe_args}\"\n            )\n        return modified_command\n\n    async def _build_trigger_job_run_options(\n        self,\n        job: Dict[str, Any],\n        run: Dict[str, Any],\n    ) -&gt; TriggerJobRunOptions:\n        \"\"\"\n        Compiles a list of steps (commands) to retry, then either build trigger job\n        run options from scratch if it does not exist, else overrides the existing.\n        \"\"\"\n        generate_docs = job.get(\"generate_docs\", False)\n        generate_sources = job.get(\"generate_sources\", False)\n\n        steps_override = []\n        for run_step in run[\"run_steps\"]:\n            status = run_step[\"status_humanized\"].lower()\n            # Skipping cloning, profile setup, and dbt deps - always the first three\n            # steps in any run, and note, index starts at 1 instead of 0\n            if run_step[\"index\"] &lt;= 3 or status == \"success\":\n                continue\n            # get dbt build from \"Invoke dbt with `dbt build`\"\n            command = run_step[\"name\"].partition(\"`\")[2].partition(\"`\")[0]\n\n            # These steps will be re-run regardless if\n            # generate_docs or generate_sources are enabled for a given job\n            # so if we don't skip, it'll run twice\n            freshness_in_command = (\n                \"dbt source snapshot-freshness\" in command\n                or \"dbt source freshness\" in command\n            )\n            if \"dbt docs generate\" in command and generate_docs:\n                continue\n            elif freshness_in_command and generate_sources:\n                continue\n\n            # find an executable command like `build` or `run`\n            # search in a list so that there aren't false positives, like\n            # `\"run\" in \"dbt run-operation\"`, which is True; we actually want\n            # `\"run\" in [\"dbt\", \"run-operation\"]` which is False\n            command_components = shlex.split(command)\n            for exe_command in EXE_COMMANDS:\n                if exe_command in command_components:\n                    break\n            else:\n                exe_command = \"\"\n\n            is_exe_command = exe_command in EXE_COMMANDS\n            is_not_success = status in (\"error\", \"skipped\", \"cancelled\")\n            is_skipped = status == \"skipped\"\n            if (not is_exe_command and is_not_success) or (\n                is_exe_command and is_skipped\n            ):\n                # if no matches like `run-operation`, we will be rerunning entirely\n                # or if it's one of the expected commands and is skipped\n                steps_override.append(command)\n            else:\n                # errors and failures are when we need to inspect to figure\n                # out the point of failure\n                try:\n                    run_artifact = await self.get_run_artifacts(\n                        \"run_results.json\", run_step[\"index\"]\n                    )\n                except JSONDecodeError:\n                    # get the run results scoped to the step which had an error\n                    # an error here indicates that either:\n                    # 1) the fail-fast flag was set, in which case\n                    #    the run_results.json file was never created; or\n                    # 2) there was a problem on dbt Cloud's side saving\n                    #    this artifact\n                    steps_override.append(command)\n                else:\n                    # we only need to find the individual nodes\n                    # for those run commands\n                    run_results = run_artifact[\"results\"]\n                    modified_command = self._select_unsuccessful_commands(\n                        run_results=run_results,\n                        command_components=command_components,\n                        command=command,\n                        exe_command=exe_command,\n                    )\n                    steps_override.append(modified_command)\n\n        if self._dbt_cloud_job.trigger_job_run_options is None:\n            trigger_job_run_options_override = TriggerJobRunOptions(\n                steps_override=steps_override\n            )\n        else:\n            trigger_job_run_options_override = (\n                self._dbt_cloud_job.trigger_job_run_options.copy()\n            )\n            trigger_job_run_options_override.steps_override = steps_override\n        return trigger_job_run_options_override\n\n    @sync_compatible\n    async def retry_failed_steps(self) -&gt; \"DbtCloudJobRun\":  # noqa: F821\n        \"\"\"\n        Retries steps that did not complete successfully in a run.\n\n        Returns:\n            A representation of the dbt Cloud job run.\n        \"\"\"\n        job = await self._dbt_cloud_job.get_job()\n        run = await self.get_run()\n\n        trigger_job_run_options_override = await self._build_trigger_job_run_options(\n            job=job, run=run\n        )\n\n        num_steps = len(trigger_job_run_options_override.steps_override)\n        if num_steps == 0:\n            self.logger.info(f\"{self._log_prefix} does not have any steps to retry.\")\n        else:\n            self.logger.info(f\"{self._log_prefix} has {num_steps} steps to retry.\")\n            run = await self._dbt_cloud_job.trigger(\n                trigger_job_run_options=trigger_job_run_options_override,\n            )\n        return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Gets the results from the job run. Since the results may not be ready, use wait_for_completion before calling this method.</p> <p>Parameters:</p> Name Type Description Default <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self, step: Optional[int] = None) -&gt; Dict[str, Any]:\n    \"\"\"\n    Gets the results from the job run. Since the results\n    may not be ready, use wait_for_completion before calling this method.\n\n    Args:\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n    \"\"\"\n    run_data = await self.get_run()\n    run_status = DbtCloudJobRunStatus(run_data.get(\"status\"))\n    if run_status == DbtCloudJobRunStatus.SUCCESS:\n        try:\n            async with self._dbt_cloud_credentials.get_administrative_client() as client:  # noqa\n                response = await client.list_run_artifacts(\n                    run_id=self.run_id, step=step\n                )\n            run_data[\"artifact_paths\"] = response.json()[\"data\"]\n            self.logger.info(\"%s completed successfully!\", self._log_prefix)\n        except HTTPStatusError as ex:\n            raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n        return run_data\n    elif run_status == DbtCloudJobRunStatus.CANCELLED:\n        raise DbtCloudJobRunCancelled(f\"{self._log_prefix} was cancelled.\")\n    elif run_status == DbtCloudJobRunStatus.FAILED:\n        raise DbtCloudJobRunFailed(f\"{self._log_prefix} has failed.\")\n    else:\n        raise DbtCloudJobRunIncomplete(\n            f\"{self._log_prefix} is still running; \"\n            \"use wait_for_completion() to wait until results are ready.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run","title":"<code>get_run</code>  <code>async</code>","text":"<p>Makes a request to the dbt Cloud API to get the run data.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The run data.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_run(self) -&gt; Dict[str, Any]:\n    \"\"\"\n    Makes a request to the dbt Cloud API to get the run data.\n\n    Returns:\n        The run data.\n    \"\"\"\n    try:\n        dbt_cloud_credentials = self._dbt_cloud_credentials\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run(self.run_id)\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n    run_data = response.json()[\"data\"]\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_run_artifacts","title":"<code>get_run_artifacts</code>  <code>async</code>","text":"<p>Get an artifact generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Literal['manifest.json', 'catalog.json', 'run_results.json']</code> <p>The relative path to the run artifact.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[Dict[str, Any], str]</code> <p>The contents of the requested manifest. Returns a <code>Dict</code> if the requested artifact is a JSON file and a <code>str</code> otherwise.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_run_artifacts(\n    self,\n    path: Literal[\"manifest.json\", \"catalog.json\", \"run_results.json\"],\n    step: Optional[int] = None,\n) -&gt; Union[Dict[str, Any], str]:\n    \"\"\"\n    Get an artifact generated for a completed run.\n\n    Args:\n        path: The relative path to the run artifact.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The contents of the requested manifest. Returns a `Dict` if the\n            requested artifact is a JSON file and a `str` otherwise.\n    \"\"\"\n    try:\n        dbt_cloud_credentials = self._dbt_cloud_credentials\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run_artifact(\n                run_id=self.run_id, path=path, step=step\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n    if path.endswith(\".json\"):\n        artifact_contents = response.json()\n    else:\n        artifact_contents = response.text\n    return artifact_contents\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.get_status_code","title":"<code>get_status_code</code>  <code>async</code>","text":"<p>Makes a request to the dbt Cloud API to get the run status.</p> <p>Returns:</p> Type Description <code>int</code> <p>The run status code.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def get_status_code(self) -&gt; int:\n    \"\"\"\n    Makes a request to the dbt Cloud API to get the run status.\n\n    Returns:\n        The run status code.\n    \"\"\"\n    run_data = await self.get_run()\n    run_status_code = run_data.get(\"status\")\n    return run_status_code\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.retry_failed_steps","title":"<code>retry_failed_steps</code>  <code>async</code>","text":"<p>Retries steps that did not complete successfully in a run.</p> <p>Returns:</p> Type Description <code>DbtCloudJobRun</code> <p>A representation of the dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def retry_failed_steps(self) -&gt; \"DbtCloudJobRun\":  # noqa: F821\n    \"\"\"\n    Retries steps that did not complete successfully in a run.\n\n    Returns:\n        A representation of the dbt Cloud job run.\n    \"\"\"\n    job = await self._dbt_cloud_job.get_job()\n    run = await self.get_run()\n\n    trigger_job_run_options_override = await self._build_trigger_job_run_options(\n        job=job, run=run\n    )\n\n    num_steps = len(trigger_job_run_options_override.steps_override)\n    if num_steps == 0:\n        self.logger.info(f\"{self._log_prefix} does not have any steps to retry.\")\n    else:\n        self.logger.info(f\"{self._log_prefix} has {num_steps} steps to retry.\")\n        run = await self._dbt_cloud_job.trigger(\n            trigger_job_run_options=trigger_job_run_options_override,\n        )\n    return run\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.DbtCloudJobRun.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Waits for the job run to reach a terminal state.</p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Waits for the job run to reach a terminal state.\n    \"\"\"\n    await self._wait_until_state(\n        in_final_state_fn=DbtCloudJobRunStatus.is_terminal_status_code,\n        get_state_fn=self.get_status_code,\n        log_state_fn=DbtCloudJobRunStatus,\n        timeout_seconds=self._dbt_cloud_job.timeout_seconds,\n        interval_seconds=self._dbt_cloud_job.interval_seconds,\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.get_dbt_cloud_job_info","title":"<code>get_dbt_cloud_job_info</code>  <code>async</code>","text":"<p>A task to retrieve information about a dbt Cloud job.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to get.</p> required <p>Returns:</p> Type Description <code>Dict</code> <p>The job data returned by the dbt Cloud administrative API.</p> Example <p>Get status of a dbt Cloud job: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_job\n\n@flow\ndef get_job_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_job(\n        dbt_cloud_credentials=credentials,\n        job_id=42\n    )\n\nget_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job details\",\n    description=\"Retrieves details of a dbt Cloud job \"\n    \"for the job with the given job_id.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_job_info(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    order_by: Optional[str] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to retrieve information about a dbt Cloud job.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to get.\n\n    Returns:\n        The job data returned by the dbt Cloud administrative API.\n\n    Example:\n        Get status of a dbt Cloud job:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_job\n\n        @flow\n        def get_job_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_job(\n                dbt_cloud_credentials=credentials,\n                job_id=42\n            )\n\n        get_job_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_job(\n                job_id=job_id,\n                order_by=order_by,\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetJobFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.get_run_id","title":"<code>get_run_id</code>","text":"<p>Task that extracts the run ID from a trigger job run API response,</p> <p>This task is mainly used to maintain dependency tracking between the <code>trigger_dbt_cloud_job_run</code> task and downstream tasks/flows that use the run ID.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>Dict</code> <p>The JSON body from the trigger job run response.</p> required Example <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run, get_run_id\n\n\n@flow\ndef trigger_run_and_get_id():\n    dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        )\n\n    triggered_run_data = trigger_dbt_cloud_job_run(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        options=trigger_job_run_options,\n    )\n    run_id = get_run_id.submit(triggered_run_data)\n    return run_id\n\ntrigger_run_and_get_id()\n</code></pre> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job run ID\",\n    description=\"Extracts the run ID from a trigger job run API response\",\n)\ndef get_run_id(obj: Dict):\n    \"\"\"\n    Task that extracts the run ID from a trigger job run API response,\n\n    This task is mainly used to maintain dependency tracking between the\n    `trigger_dbt_cloud_job_run` task and downstream tasks/flows that use the run ID.\n\n    Args:\n        obj: The JSON body from the trigger job run response.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run, get_run_id\n\n\n        @flow\n        def trigger_run_and_get_id():\n            dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                )\n\n            triggered_run_data = trigger_dbt_cloud_job_run(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                job_id=job_id,\n                options=trigger_job_run_options,\n            )\n            run_id = get_run_id.submit(triggered_run_data)\n            return run_id\n\n        trigger_run_and_get_id()\n        ```\n    \"\"\"\n    id = obj.get(\"id\")\n    if id is None:\n        raise RuntimeError(\"Unable to determine run ID for triggered job.\")\n    return id\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.retry_dbt_cloud_job_run_subset_and_wait_for_completion","title":"<code>retry_dbt_cloud_job_run_subset_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that retrys a subset of dbt Cloud job run, filtered by select statuses, and waits for the triggered retry to complete.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>trigger_job_run_options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>run_id</code> <code>int</code> <p>The ID of the job run to retry.</p> required <p>Raises:</p> Type Description <code>ValueError</code> <p>If <code>trigger_job_run_options.steps_override</code> is set by the user.</p> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Retry a subset of models in a dbt Cloud job run and wait for completion: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import retry_dbt_cloud_job_run_subset_and_wait_for_completion\n\n@flow\ndef retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow():\n    credentials = DbtCloudCredentials.load(\"MY_BLOCK_NAME\")\n    retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n        dbt_cloud_credentials=credentials,\n        run_id=88640123,\n    )\n\nretry_dbt_cloud_job_run_subset_and_wait_for_completion_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow(\n    name=\"Retry subset of dbt Cloud job run and wait for completion\",\n    description=(\n        \"Retries a subset of dbt Cloud job run, filtered by select statuses, \"\n        \"and waits for the triggered retry to complete.\"\n    ),\n)\nasync def retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    trigger_job_run_options: Optional[TriggerJobRunOptions] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n) -&gt; Dict:\n    \"\"\"\n    Flow that retrys a subset of dbt Cloud job run, filtered by select statuses,\n    and waits for the triggered retry to complete.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        trigger_job_run_options: An optional TriggerJobRunOptions instance to\n            specify overrides for the triggered job run.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        run_id: The ID of the job run to retry.\n\n    Raises:\n        ValueError: If `trigger_job_run_options.steps_override` is set by the user.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Examples:\n        Retry a subset of models in a dbt Cloud job run and wait for completion:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import retry_dbt_cloud_job_run_subset_and_wait_for_completion\n\n        @flow\n        def retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow():\n            credentials = DbtCloudCredentials.load(\"MY_BLOCK_NAME\")\n            retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n                dbt_cloud_credentials=credentials,\n                run_id=88640123,\n            )\n\n        retry_dbt_cloud_job_run_subset_and_wait_for_completion_flow()\n        ```\n    \"\"\"  # noqa\n    if trigger_job_run_options and trigger_job_run_options.steps_override is not None:\n        raise ValueError(\n            \"Do not set `steps_override` in `trigger_job_run_options` \"\n            \"because this flow will automatically set it\"\n        )\n\n    run_info_future = await get_dbt_cloud_run_info.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        run_id=run_id,\n        include_related=[\"run_steps\"],\n    )\n    run_info = await run_info_future.result()\n\n    job_id = run_info[\"job_id\"]\n    job_info_future = await get_dbt_cloud_job_info.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n    )\n    job_info = await job_info_future.result()\n\n    trigger_job_run_options_override = await _build_trigger_job_run_options(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        trigger_job_run_options=trigger_job_run_options,\n        run_id=run_id,\n        run_info=run_info,\n        job_info=job_info,\n    )\n\n    # to circumvent `RuntimeError: The task runner is already started!`\n    flow_run_context = FlowRunContext.get()\n    task_runner_type = type(flow_run_context.task_runner)\n\n    run_data = await trigger_dbt_cloud_job_run_and_wait_for_completion.with_options(\n        task_runner=task_runner_type()\n    )(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        retry_filtered_models_attempts=0,\n        trigger_job_run_options=trigger_job_run_options_override,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.run_dbt_cloud_job","title":"<code>run_dbt_cloud_job</code>  <code>async</code>","text":"<p>Flow that triggers and waits for a dbt Cloud job run, retrying a subset of failed nodes if necessary.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_job</code> <code>DbtCloudJob</code> <p>Block that holds the information and methods to interact with a dbt Cloud job.</p> required <code>targeted_retries</code> <code>int</code> <p>The number of times to retry failed steps.</p> <code>3</code> <p>Examples:</p> <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\nfrom prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n@flow\ndef run_dbt_cloud_job_flow():\n    dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n    dbt_cloud_job = DbtCloudJob(\n        dbt_cloud_credentials=dbt_cloud_credentials, job_id=154217\n    )\n    return run_dbt_cloud_job(dbt_cloud_job=dbt_cloud_job)\n\nrun_dbt_cloud_job_flow()\n</code></pre> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow\nasync def run_dbt_cloud_job(\n    dbt_cloud_job: DbtCloudJob,\n    targeted_retries: int = 3,\n) -&gt; Dict[str, Any]:\n    \"\"\"\n    Flow that triggers and waits for a dbt Cloud job run, retrying a\n    subset of failed nodes if necessary.\n\n    Args:\n        dbt_cloud_job: Block that holds the information and\n            methods to interact with a dbt Cloud job.\n        targeted_retries: The number of times to retry failed steps.\n\n    Examples:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials, DbtCloudJob\n        from prefect_dbt.cloud.jobs import run_dbt_cloud_job\n\n        @flow\n        def run_dbt_cloud_job_flow():\n            dbt_cloud_credentials = DbtCloudCredentials.load(\"dbt-token\")\n            dbt_cloud_job = DbtCloudJob(\n                dbt_cloud_credentials=dbt_cloud_credentials, job_id=154217\n            )\n            return run_dbt_cloud_job(dbt_cloud_job=dbt_cloud_job)\n\n        run_dbt_cloud_job_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    run = await task(dbt_cloud_job.trigger.aio)(dbt_cloud_job)\n    while targeted_retries &gt; 0:\n        try:\n            await task(run.wait_for_completion.aio)(run)\n            result = await task(run.fetch_result.aio)(run)\n            return result\n        except DbtCloudJobRunFailed:\n            logger.info(\n                f\"Retrying job run with ID: {run.run_id} \"\n                f\"{targeted_retries} more times\"\n            )\n            run = await task(run.retry_failed_steps.aio)(run)\n            targeted_retries -= 1\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run","title":"<code>trigger_dbt_cloud_job_run</code>  <code>async</code>","text":"<p>A task to trigger a dbt Cloud job run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned from the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Trigger a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n\ntrigger_dbt_cloud_job_run_flow()\n</code></pre></p> <p>Trigger a dbt Cloud job run with overrides: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\nfrom prefect_dbt.cloud.models import TriggerJobRunOptions\n\n\n@flow\ndef trigger_dbt_cloud_job_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    trigger_dbt_cloud_job_run(\n        dbt_cloud_credentials=credentials,\n        job_id=1,\n        options=TriggerJobRunOptions(\n            git_branch=\"staging\",\n            schema_override=\"dbt_cloud_pr_123\",\n            dbt_version_override=\"0.18.0\",\n            target_name_override=\"staging\",\n            timeout_seconds_override=3000,\n            generate_docs_override=True,\n            threads_override=8,\n            steps_override=[\n                \"dbt seed\",\n                \"dbt run --fail-fast\",\n                \"dbt test --fail-fast\",\n            ],\n        ),\n    )\n\n\ntrigger_dbt_cloud_job_run()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@task(\n    name=\"Trigger dbt Cloud job run\",\n    description=\"Triggers a dbt Cloud job run for the job \"\n    \"with the given job_id and optional overrides.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def trigger_dbt_cloud_job_run(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    options: Optional[TriggerJobRunOptions] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to trigger a dbt Cloud job run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to trigger.\n        options: An optional TriggerJobRunOptions instance to specify overrides\n            for the triggered job run.\n\n    Returns:\n        The run data returned from the dbt Cloud administrative API.\n\n    Examples:\n        Trigger a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            trigger_dbt_cloud_job_run(dbt_cloud_credentials=credentials, job_id=1)\n\n\n        trigger_dbt_cloud_job_run_flow()\n        ```\n\n        Trigger a dbt Cloud job run with overrides:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run\n        from prefect_dbt.cloud.models import TriggerJobRunOptions\n\n\n        @flow\n        def trigger_dbt_cloud_job_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            trigger_dbt_cloud_job_run(\n                dbt_cloud_credentials=credentials,\n                job_id=1,\n                options=TriggerJobRunOptions(\n                    git_branch=\"staging\",\n                    schema_override=\"dbt_cloud_pr_123\",\n                    dbt_version_override=\"0.18.0\",\n                    target_name_override=\"staging\",\n                    timeout_seconds_override=3000,\n                    generate_docs_override=True,\n                    threads_override=8,\n                    steps_override=[\n                        \"dbt seed\",\n                        \"dbt run --fail-fast\",\n                        \"dbt test --fail-fast\",\n                    ],\n                ),\n            )\n\n\n        trigger_dbt_cloud_job_run()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    logger.info(f\"Triggering run for job with ID {job_id}\")\n\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.trigger_job_run(job_id=job_id, options=options)\n    except HTTPStatusError as ex:\n        raise DbtCloudJobRunTriggerFailed(extract_user_message(ex)) from ex\n\n    run_data = response.json()[\"data\"]\n\n    if \"project_id\" in run_data and \"id\" in run_data:\n        logger.info(\n            f\"Run successfully triggered for job with ID {job_id}. \"\n            \"You can view the status of this run at \"\n            f\"https://{dbt_cloud_credentials.domain}/#/accounts/\"\n            f\"{dbt_cloud_credentials.account_id}/projects/{run_data['project_id']}/\"\n            f\"runs/{run_data['id']}/\"\n        )\n\n    return run_data\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run_and_wait_for_completion","title":"<code>trigger_dbt_cloud_job_run_and_wait_for_completion</code>  <code>async</code>","text":"<p>Flow that triggers a job run and waits for the triggered run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>job_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>trigger_job_run_options</code> <code>Optional[TriggerJobRunOptions]</code> <p>An optional TriggerJobRunOptions instance to specify overrides for the triggered job run.</p> <code>None</code> <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <code>retry_filtered_models_attempts</code> <code>int</code> <p>Number of times to retry models selected by <code>retry_status_filters</code>.</p> <code>3</code> <p>Raises:</p> Type Description <code>DbtCloudJobRunCancelled</code> <p>The triggered dbt Cloud job run was cancelled.</p> <code>DbtCloudJobRunFailed</code> <p>The triggered dbt Cloud job run failed.</p> <code>RuntimeError</code> <p>The triggered dbt Cloud job run ended in an unexpected state.</p> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> <p>Examples:</p> <p>Trigger a dbt Cloud job and wait for completion as a stand alone flow: <pre><code>import asyncio\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\nasyncio.run(\n    trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1\n    )\n)\n</code></pre></p> <p>Trigger a dbt Cloud job and wait for completion as a sub-flow: <pre><code>from prefect import flow\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n@flow\ndef my_flow():\n    ...\n    run_result = trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1\n    )\n    ...\n\nmy_flow()\n</code></pre></p> <p>Trigger a dbt Cloud job with overrides: <pre><code>import asyncio\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\nfrom prefect_dbt.cloud.models import TriggerJobRunOptions\n\nasyncio.run(\n    trigger_dbt_cloud_job_run_and_wait_for_completion(\n        dbt_cloud_credentials=DbtCloudCredentials(\n            api_key=\"my_api_key\",\n            account_id=123456789\n        ),\n        job_id=1,\n        trigger_job_run_options=TriggerJobRunOptions(\n            git_branch=\"staging\",\n            schema_override=\"dbt_cloud_pr_123\",\n            dbt_version_override=\"0.18.0\",\n            target_name_override=\"staging\",\n            timeout_seconds_override=3000,\n            generate_docs_override=True,\n            threads_override=8,\n            steps_override=[\n                \"dbt seed\",\n                \"dbt run --fail-fast\",\n                \"dbt test --fail fast\",\n            ],\n        ),\n    )\n)\n</code></pre></p> Source code in <code>prefect_dbt/cloud/jobs.py</code> <pre><code>@flow(\n    name=\"Trigger dbt Cloud job run and wait for completion\",\n    description=\"Triggers a dbt Cloud job run and waits for the\"\n    \"triggered run to complete.\",\n)\nasync def trigger_dbt_cloud_job_run_and_wait_for_completion(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    job_id: int,\n    trigger_job_run_options: Optional[TriggerJobRunOptions] = None,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n    retry_filtered_models_attempts: int = 3,\n) -&gt; Dict:\n    \"\"\"\n    Flow that triggers a job run and waits for the triggered run to complete.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        job_id: The ID of the job to trigger.\n        trigger_job_run_options: An optional TriggerJobRunOptions instance to\n            specify overrides for the triggered job run.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n        retry_filtered_models_attempts: Number of times to retry models selected by `retry_status_filters`.\n\n    Raises:\n        DbtCloudJobRunCancelled: The triggered dbt Cloud job run was cancelled.\n        DbtCloudJobRunFailed: The triggered dbt Cloud job run failed.\n        RuntimeError: The triggered dbt Cloud job run ended in an unexpected state.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Examples:\n        Trigger a dbt Cloud job and wait for completion as a stand alone flow:\n        ```python\n        import asyncio\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n        asyncio.run(\n            trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1\n            )\n        )\n        ```\n\n        Trigger a dbt Cloud job and wait for completion as a sub-flow:\n        ```python\n        from prefect import flow\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n\n        @flow\n        def my_flow():\n            ...\n            run_result = trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1\n            )\n            ...\n\n        my_flow()\n        ```\n\n        Trigger a dbt Cloud job with overrides:\n        ```python\n        import asyncio\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import trigger_dbt_cloud_job_run_and_wait_for_completion\n        from prefect_dbt.cloud.models import TriggerJobRunOptions\n\n        asyncio.run(\n            trigger_dbt_cloud_job_run_and_wait_for_completion(\n                dbt_cloud_credentials=DbtCloudCredentials(\n                    api_key=\"my_api_key\",\n                    account_id=123456789\n                ),\n                job_id=1,\n                trigger_job_run_options=TriggerJobRunOptions(\n                    git_branch=\"staging\",\n                    schema_override=\"dbt_cloud_pr_123\",\n                    dbt_version_override=\"0.18.0\",\n                    target_name_override=\"staging\",\n                    timeout_seconds_override=3000,\n                    generate_docs_override=True,\n                    threads_override=8,\n                    steps_override=[\n                        \"dbt seed\",\n                        \"dbt run --fail-fast\",\n                        \"dbt test --fail fast\",\n                    ],\n                ),\n            )\n        )\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n\n    triggered_run_data_future = await trigger_dbt_cloud_job_run.submit(\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        job_id=job_id,\n        options=trigger_job_run_options,\n    )\n    run_id = (await triggered_run_data_future.result()).get(\"id\")\n    if run_id is None:\n        raise RuntimeError(\"Unable to determine run ID for triggered job.\")\n\n    final_run_status, run_data = await wait_for_dbt_cloud_job_run(\n        run_id=run_id,\n        dbt_cloud_credentials=dbt_cloud_credentials,\n        max_wait_seconds=max_wait_seconds,\n        poll_frequency_seconds=poll_frequency_seconds,\n    )\n\n    if final_run_status == DbtCloudJobRunStatus.SUCCESS:\n        try:\n            list_run_artifacts_future = await list_dbt_cloud_run_artifacts.submit(\n                dbt_cloud_credentials=dbt_cloud_credentials,\n                run_id=run_id,\n            )\n            run_data[\"artifact_paths\"] = await list_run_artifacts_future.result()\n        except DbtCloudListRunArtifactsFailed as ex:\n            logger.warning(\n                \"Unable to retrieve artifacts for job run with ID %s. Reason: %s\",\n                run_id,\n                ex,\n            )\n        logger.info(\n            \"dbt Cloud job run with ID %s completed successfully!\",\n            run_id,\n        )\n        return run_data\n    elif final_run_status == DbtCloudJobRunStatus.CANCELLED:\n        raise DbtCloudJobRunCancelled(\n            f\"Triggered job run with ID {run_id} was cancelled.\"\n        )\n    elif final_run_status == DbtCloudJobRunStatus.FAILED:\n        while retry_filtered_models_attempts &gt; 0:\n            logger.info(\n                f\"Retrying job run with ID: {run_id} \"\n                f\"{retry_filtered_models_attempts} more times\"\n            )\n            try:\n                retry_filtered_models_attempts -= 1\n                run_data = await retry_dbt_cloud_job_run_subset_and_wait_for_completion(\n                    dbt_cloud_credentials=dbt_cloud_credentials,\n                    run_id=run_id,\n                    trigger_job_run_options=trigger_job_run_options,\n                    max_wait_seconds=max_wait_seconds,\n                    poll_frequency_seconds=poll_frequency_seconds,\n                )\n                return run_data\n            except Exception:\n                pass\n        else:\n            raise DbtCloudJobRunFailed(f\"Triggered job run with ID: {run_id} failed.\")\n    else:\n        raise RuntimeError(\n            f\"Triggered job run with ID: {run_id} ended with unexpected\"\n            f\"status {final_run_status.value}.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/models/","title":"Models","text":""},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models","title":"<code>prefect_dbt.cloud.models</code>","text":"<p>Module containing models used for passing data to dbt Cloud</p>"},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models.TriggerJobRunOptions","title":"<code>TriggerJobRunOptions</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Defines options that can be defined when triggering a dbt Cloud job run.</p> Source code in <code>prefect_dbt/cloud/models.py</code> <pre><code>class TriggerJobRunOptions(BaseModel):\n    \"\"\"\n    Defines options that can be defined when triggering a dbt Cloud job run.\n    \"\"\"\n\n    cause: str = Field(\n        default_factory=default_cause_factory,\n        description=\"A text description of the reason for running this job.\",\n    )\n    git_sha: Optional[str] = Field(\n        default=None, description=\"The git sha to check out before running this job.\"\n    )\n    git_branch: Optional[str] = Field(\n        default=None, description=\"The git branch to check out before running this job.\"\n    )\n    schema_override: Optional[str] = Field(\n        default=None,\n        description=\"Override the destination schema in the configured \"\n        \"target for this job.\",\n    )\n    dbt_version_override: Optional[str] = Field(\n        default=None, description=\"Override the version of dbt used to run this job.\"\n    )\n    threads_override: Optional[int] = Field(\n        default=None, description=\"Override the number of threads used to run this job.\"\n    )\n    target_name_override: Optional[str] = Field(\n        default=None,\n        description=\"Override the target.name context variable used when \"\n        \"running this job\",\n    )\n    generate_docs_override: Optional[bool] = Field(\n        default=None,\n        description=\"Override whether or not this job generates docs \"\n        \"(true=yes, false=no).\",\n    )\n    timeout_seconds_override: Optional[int] = Field(\n        default=None, description=\"Override the timeout in seconds for this job.\"\n    )\n    steps_override: Optional[List[str]] = Field(\n        default=None, description=\"Override the list of steps for this job.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/models/#prefect_dbt.cloud.models.default_cause_factory","title":"<code>default_cause_factory</code>","text":"<p>Factory function to populate the default cause for a job run to include information from the Prefect run context.</p> Source code in <code>prefect_dbt/cloud/models.py</code> <pre><code>def default_cause_factory():\n    \"\"\"\n    Factory function to populate the default cause for a job run to include information\n    from the Prefect run context.\n    \"\"\"\n    cause = \"Triggered via Prefect\"\n\n    try:\n        context = get_run_context()\n        if isinstance(context, FlowRunContext):\n            cause = f\"{cause} in flow run {context.flow_run.name}\"\n        elif isinstance(context, TaskRunContext):\n            cause = f\"{cause} in task run {context.task_run.name}\"\n    except RuntimeError:\n        pass\n\n    return cause\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/","title":"Runs","text":""},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs","title":"<code>prefect_dbt.cloud.runs</code>","text":"<p>Module containing tasks and flows for interacting with dbt Cloud job runs</p>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.DbtCloudJobRunStatus","title":"<code>DbtCloudJobRunStatus</code>","text":"<p>               Bases: <code>Enum</code></p> <p>dbt Cloud Job statuses.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>class DbtCloudJobRunStatus(Enum):\n    \"\"\"dbt Cloud Job statuses.\"\"\"\n\n    QUEUED = 1\n    STARTING = 2\n    RUNNING = 3\n    SUCCESS = 10\n    FAILED = 20\n    CANCELLED = 30\n\n    @classmethod\n    def is_terminal_status_code(cls, status_code: Any) -&gt; bool:\n        \"\"\"\n        Returns True if a status code is terminal for a job run.\n        Returns False otherwise.\n        \"\"\"\n        return status_code in [cls.SUCCESS.value, cls.FAILED.value, cls.CANCELLED.value]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.DbtCloudJobRunStatus.is_terminal_status_code","title":"<code>is_terminal_status_code</code>  <code>classmethod</code>","text":"<p>Returns True if a status code is terminal for a job run. Returns False otherwise.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@classmethod\ndef is_terminal_status_code(cls, status_code: Any) -&gt; bool:\n    \"\"\"\n    Returns True if a status code is terminal for a job run.\n    Returns False otherwise.\n    \"\"\"\n    return status_code in [cls.SUCCESS.value, cls.FAILED.value, cls.CANCELLED.value]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.get_dbt_cloud_run_artifact","title":"<code>get_dbt_cloud_run_artifact</code>  <code>async</code>","text":"<p>A task to get an artifact generated for a completed run. The requested artifact is saved to a file in the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>path</code> <code>str</code> <p>The relative path to the run artifact (e.g. manifest.json, catalog.json, run_results.json)</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[Dict, str]</code> <p>The contents of the requested manifest. Returns a <code>Dict</code> if the requested artifact is a JSON file and a <code>str</code> otherwise.</p> <p>Examples:</p> <p>Get an artifact of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.runs import get_dbt_cloud_run_artifact\n\n@flow\ndef get_artifact_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_dbt_cloud_run_artifact(\n        dbt_cloud_credentials=credentials,\n        run_id=42,\n        path=\"manifest.json\"\n    )\n\nget_artifact_flow()\n</code></pre></p> <p>Get an artifact of a dbt Cloud job run and write it to a file: <pre><code>import json\n\nfrom prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_dbt_cloud_run_artifact\n\n@flow\ndef get_artifact_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    get_run_artifact_result = get_dbt_cloud_run_artifact(\n        dbt_cloud_credentials=credentials,\n        run_id=42,\n        path=\"manifest.json\"\n    )\n\n    with open(\"manifest.json\", \"w\") as file:\n        json.dump(get_run_artifact_result, file)\n\nget_artifact_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job artifact\",\n    description=\"Fetches an artifact from a completed run.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_run_artifact(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    path: str,\n    step: Optional[int] = None,\n) -&gt; Union[Dict, str]:\n    \"\"\"\n    A task to get an artifact generated for a completed run. The requested artifact\n    is saved to a file in the current working directory.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the run to list run artifacts for.\n        path: The relative path to the run artifact (e.g. manifest.json, catalog.json,\n            run_results.json)\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        The contents of the requested manifest. Returns a `Dict` if the\n            requested artifact is a JSON file and a `str` otherwise.\n\n    Examples:\n        Get an artifact of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.runs import get_dbt_cloud_run_artifact\n\n        @flow\n        def get_artifact_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_dbt_cloud_run_artifact(\n                dbt_cloud_credentials=credentials,\n                run_id=42,\n                path=\"manifest.json\"\n            )\n\n        get_artifact_flow()\n        ```\n\n        Get an artifact of a dbt Cloud job run and write it to a file:\n        ```python\n        import json\n\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_dbt_cloud_run_artifact\n\n        @flow\n        def get_artifact_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            get_run_artifact_result = get_dbt_cloud_run_artifact(\n                dbt_cloud_credentials=credentials,\n                run_id=42,\n                path=\"manifest.json\"\n            )\n\n            with open(\"manifest.json\", \"w\") as file:\n                json.dump(get_run_artifact_result, file)\n\n        get_artifact_flow()\n        ```\n    \"\"\"  # noqa\n\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run_artifact(\n                run_id=run_id, path=path, step=step\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunArtifactFailed(extract_user_message(ex)) from ex\n\n    if path.endswith(\".json\"):\n        artifact_contents = response.json()\n    else:\n        artifact_contents = response.text\n\n    return artifact_contents\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.get_dbt_cloud_run_info","title":"<code>get_dbt_cloud_run_info</code>  <code>async</code>","text":"<p>A task to retrieve information about a dbt Cloud job run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the job to trigger.</p> required <code>include_related</code> <code>Optional[List[Literal['trigger', 'job', 'debug_logs', 'run_steps']]]</code> <p>List of related fields to pull with the run. Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\". If \"debug_logs\" is not provided in a request, then the included debug logs will be truncated to the last 1,000 lines of the debug log output file.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict</code> <p>The run data returned by the dbt Cloud administrative API.</p> Example <p>Get status of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import get_run\n\n@flow\ndef get_run_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return get_run(\n        dbt_cloud_credentials=credentials,\n        run_id=42\n    )\n\nget_run_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"Get dbt Cloud job run details\",\n    description=\"Retrieves details of a dbt Cloud job run \"\n    \"for the run with the given run_id.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def get_dbt_cloud_run_info(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    run_id: int,\n    include_related: Optional[\n        List[Literal[\"trigger\", \"job\", \"debug_logs\", \"run_steps\"]]\n    ] = None,\n) -&gt; Dict:\n    \"\"\"\n    A task to retrieve information about a dbt Cloud job run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the job to trigger.\n        include_related: List of related fields to pull with the run.\n            Valid values are \"trigger\", \"job\", \"debug_logs\", and \"run_steps\".\n            If \"debug_logs\" is not provided in a request, then the included debug\n            logs will be truncated to the last 1,000 lines of the debug log output file.\n\n    Returns:\n        The run data returned by the dbt Cloud administrative API.\n\n    Example:\n        Get status of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import get_run\n\n        @flow\n        def get_run_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return get_run(\n                dbt_cloud_credentials=credentials,\n                run_id=42\n            )\n\n        get_run_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.get_run(\n                run_id=run_id, include_related=include_related\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudGetRunFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.list_dbt_cloud_run_artifacts","title":"<code>list_dbt_cloud_run_artifacts</code>  <code>async</code>","text":"<p>A task to list the artifact files generated for a completed run.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>run_id</code> <code>int</code> <p>The ID of the run to list run artifacts for.</p> required <code>step</code> <code>Optional[int]</code> <p>The index of the step in the run to query for artifacts. The first step in the run has the index 1. If the step parameter is omitted, then this method will return the artifacts compiled for the last step in the run.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>A list of paths to artifact files that can be used to retrieve the generated artifacts.</p> Example <p>List artifacts of a dbt Cloud job run: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.jobs import list_dbt_cloud_run_artifacts\n\n@flow\ndef list_artifacts_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    return list_dbt_cloud_run_artifacts(\n        dbt_cloud_credentials=credentials,\n        run_id=42\n    )\n\nlist_artifacts_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@task(\n    name=\"List dbt Cloud job artifacts\",\n    description=\"Fetches a list of artifact files generated for a completed run.\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def list_dbt_cloud_run_artifacts(\n    dbt_cloud_credentials: DbtCloudCredentials, run_id: int, step: Optional[int] = None\n) -&gt; List[str]:\n    \"\"\"\n    A task to list the artifact files generated for a completed run.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        run_id: The ID of the run to list run artifacts for.\n        step: The index of the step in the run to query for artifacts. The\n            first step in the run has the index 1. If the step parameter is\n            omitted, then this method will return the artifacts compiled\n            for the last step in the run.\n\n    Returns:\n        A list of paths to artifact files that can be used to retrieve the generated artifacts.\n\n    Example:\n        List artifacts of a dbt Cloud job run:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.jobs import list_dbt_cloud_run_artifacts\n\n        @flow\n        def list_artifacts_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            return list_dbt_cloud_run_artifacts(\n                dbt_cloud_credentials=credentials,\n                run_id=42\n            )\n\n        list_artifacts_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.list_run_artifacts(run_id=run_id, step=step)\n    except HTTPStatusError as ex:\n        raise DbtCloudListRunArtifactsFailed(extract_user_message(ex)) from ex\n    return response.json()[\"data\"]\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/runs/#prefect_dbt.cloud.runs.wait_for_dbt_cloud_job_run","title":"<code>wait_for_dbt_cloud_job_run</code>  <code>async</code>","text":"<p>Waits for the given dbt Cloud job run to finish running.</p> <p>Parameters:</p> Name Type Description Default <code>run_id</code> <code>int</code> <p>The ID of the run to wait for.</p> required <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>max_wait_seconds</code> <code>int</code> <p>Maximum number of seconds to wait for job to complete</p> <code>900</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>10</code> <p>Raises:</p> Type Description <code>DbtCloudJobRunTimedOut</code> <p>When the elapsed wait time exceeds <code>max_wait_seconds</code>.</p> <p>Returns:</p> Name Type Description <code>run_status</code> <code>DbtCloudJobRunStatus</code> <p>An enum representing the final dbt Cloud job run status</p> <code>run_data</code> <code>Dict</code> <p>A dictionary containing information about the run after completion.</p> Source code in <code>prefect_dbt/cloud/runs.py</code> <pre><code>@flow(\n    name=\"Wait for dbt Cloud job run\",\n    description=\"Waits for a dbt Cloud job run to finish running.\",\n)\nasync def wait_for_dbt_cloud_job_run(\n    run_id: int,\n    dbt_cloud_credentials: DbtCloudCredentials,\n    max_wait_seconds: int = 900,\n    poll_frequency_seconds: int = 10,\n) -&gt; Tuple[DbtCloudJobRunStatus, Dict]:\n    \"\"\"\n    Waits for the given dbt Cloud job run to finish running.\n\n    Args:\n        run_id: The ID of the run to wait for.\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        max_wait_seconds: Maximum number of seconds to wait for job to complete\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Raises:\n        DbtCloudJobRunTimedOut: When the elapsed wait time exceeds `max_wait_seconds`.\n\n    Returns:\n        run_status: An enum representing the final dbt Cloud job run status\n        run_data: A dictionary containing information about the run after completion.\n\n\n    Example:\n\n\n    \"\"\"\n    logger = get_run_logger()\n    seconds_waited_for_run_completion = 0\n    wait_for = []\n    while seconds_waited_for_run_completion &lt;= max_wait_seconds:\n        run_data_future = await get_dbt_cloud_run_info.submit(\n            dbt_cloud_credentials=dbt_cloud_credentials,\n            run_id=run_id,\n            wait_for=wait_for,\n        )\n        run_data = await run_data_future.result()\n        run_status_code = run_data.get(\"status\")\n\n        if DbtCloudJobRunStatus.is_terminal_status_code(run_status_code):\n            return DbtCloudJobRunStatus(run_status_code), run_data\n\n        wait_for = [run_data_future]\n        logger.debug(\n            \"dbt Cloud job run with ID %i has status %s. Waiting for %i seconds.\",\n            run_id,\n            DbtCloudJobRunStatus(run_status_code).name,\n            poll_frequency_seconds,\n        )\n        await asyncio.sleep(poll_frequency_seconds)\n        seconds_waited_for_run_completion += poll_frequency_seconds\n\n    raise DbtCloudJobRunTimedOut(\n        f\"Max wait time of {max_wait_seconds} seconds exceeded while waiting \"\n        \"for job run with ID {run_id}\"\n    )\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/","title":"Utils","text":""},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils","title":"<code>prefect_dbt.cloud.utils</code>","text":"<p>Utilities for common interactions with the dbt Cloud API</p>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.DbtCloudAdministrativeApiCallFailed","title":"<code>DbtCloudAdministrativeApiCallFailed</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when a call to dbt Cloud administrative API fails.</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>class DbtCloudAdministrativeApiCallFailed(Exception):\n    \"\"\"Raised when a call to dbt Cloud administrative API fails.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.call_dbt_cloud_administrative_api_endpoint","title":"<code>call_dbt_cloud_administrative_api_endpoint</code>  <code>async</code>","text":"<p>Task that calls a specified endpoint in the dbt Cloud administrative API. Use this task if a prebuilt one is not yet available.</p> <p>Parameters:</p> Name Type Description Default <code>dbt_cloud_credentials</code> <code>DbtCloudCredentials</code> <p>Credentials for authenticating with dbt Cloud.</p> required <code>path</code> <code>str</code> <p>The partial path for the request (e.g. /projects/). Will be appended onto the base URL as determined by the client configuration.</p> required <code>http_method</code> <code>str</code> <p>HTTP method to call on the endpoint.</p> required <code>params</code> <code>Optional[Dict[str, Any]]</code> <p>Query parameters to include in the request.</p> <code>None</code> <code>json</code> <code>Optional[Dict[str, Any]]</code> <p>JSON serializable body to send in the request.</p> <code>None</code> <p>Returns:</p> Type Description <code>Any</code> <p>The body of the response. If the body is JSON serializable, then the result of <code>json.loads</code> with the body as the input will be returned. Otherwise, the body will be returned directly.</p> <p>Examples:</p> <p>List projects for an account: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n@flow\ndef get_projects_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    result = call_dbt_cloud_administrative_api_endpoint(\n        dbt_cloud_credentials=credentials,\n        path=\"/projects/\",\n        http_method=\"GET\",\n    )\n    return result[\"data\"]\n\nget_projects_flow()\n</code></pre></p> <p>Create a new job: <pre><code>from prefect import flow\n\nfrom prefect_dbt.cloud import DbtCloudCredentials\nfrom prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n\n@flow\ndef create_job_flow():\n    credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n    result = call_dbt_cloud_administrative_api_endpoint(\n        dbt_cloud_credentials=credentials,\n        path=\"/jobs/\",\n        http_method=\"POST\",\n        json={\n            \"id\": None,\n            \"account_id\": 123456789,\n            \"project_id\": 100,\n            \"environment_id\": 10,\n            \"name\": \"Nightly run\",\n            \"dbt_version\": None,\n            \"triggers\": {\"github_webhook\": True, \"schedule\": True},\n            \"execute_steps\": [\"dbt run\", \"dbt test\", \"dbt source snapshot-freshness\"],\n            \"settings\": {\"threads\": 4, \"target_name\": \"prod\"},\n            \"state\": 1,\n            \"schedule\": {\n                \"date\": {\"type\": \"every_day\"},\n                \"time\": {\"type\": \"every_hour\", \"interval\": 1},\n            },\n        },\n    )\n    return result[\"data\"]\n\ncreate_job_flow()\n</code></pre></p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>@task(\n    name=\"Call dbt Cloud administrative API endpoint\",\n    description=\"Calls a dbt Cloud administrative API endpoint\",\n    retries=3,\n    retry_delay_seconds=10,\n)\nasync def call_dbt_cloud_administrative_api_endpoint(\n    dbt_cloud_credentials: DbtCloudCredentials,\n    path: str,\n    http_method: str,\n    params: Optional[Dict[str, Any]] = None,\n    json: Optional[Dict[str, Any]] = None,\n) -&gt; Any:\n    \"\"\"\n    Task that calls a specified endpoint in the dbt Cloud administrative API. Use this\n    task if a prebuilt one is not yet available.\n\n    Args:\n        dbt_cloud_credentials: Credentials for authenticating with dbt Cloud.\n        path: The partial path for the request (e.g. /projects/). Will be appended\n            onto the base URL as determined by the client configuration.\n        http_method: HTTP method to call on the endpoint.\n        params: Query parameters to include in the request.\n        json: JSON serializable body to send in the request.\n\n    Returns:\n        The body of the response. If the body is JSON serializable, then the result of\n            `json.loads` with the body as the input will be returned. Otherwise, the\n            body will be returned directly.\n\n    Examples:\n        List projects for an account:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n        @flow\n        def get_projects_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            result = call_dbt_cloud_administrative_api_endpoint(\n                dbt_cloud_credentials=credentials,\n                path=\"/projects/\",\n                http_method=\"GET\",\n            )\n            return result[\"data\"]\n\n        get_projects_flow()\n        ```\n\n        Create a new job:\n        ```python\n        from prefect import flow\n\n        from prefect_dbt.cloud import DbtCloudCredentials\n        from prefect_dbt.cloud.utils import call_dbt_cloud_administrative_api_endpoint\n\n\n        @flow\n        def create_job_flow():\n            credentials = DbtCloudCredentials(api_key=\"my_api_key\", account_id=123456789)\n\n            result = call_dbt_cloud_administrative_api_endpoint(\n                dbt_cloud_credentials=credentials,\n                path=\"/jobs/\",\n                http_method=\"POST\",\n                json={\n                    \"id\": None,\n                    \"account_id\": 123456789,\n                    \"project_id\": 100,\n                    \"environment_id\": 10,\n                    \"name\": \"Nightly run\",\n                    \"dbt_version\": None,\n                    \"triggers\": {\"github_webhook\": True, \"schedule\": True},\n                    \"execute_steps\": [\"dbt run\", \"dbt test\", \"dbt source snapshot-freshness\"],\n                    \"settings\": {\"threads\": 4, \"target_name\": \"prod\"},\n                    \"state\": 1,\n                    \"schedule\": {\n                        \"date\": {\"type\": \"every_day\"},\n                        \"time\": {\"type\": \"every_hour\", \"interval\": 1},\n                    },\n                },\n            )\n            return result[\"data\"]\n\n        create_job_flow()\n        ```\n    \"\"\"  # noqa\n    try:\n        async with dbt_cloud_credentials.get_administrative_client() as client:\n            response = await client.call_endpoint(\n                http_method=http_method, path=path, params=params, json=json\n            )\n    except HTTPStatusError as ex:\n        raise DbtCloudAdministrativeApiCallFailed(extract_developer_message(ex)) from ex\n    try:\n        return response.json()\n    except JSONDecodeError:\n        return response.text\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.extract_developer_message","title":"<code>extract_developer_message</code>","text":"<p>Extracts developer message from a error response from the dbt Cloud administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>ex</code> <code>HTTPStatusError</code> <p>An HTTPStatusError raised by httpx</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>developer_message from dbt Cloud administrative API response or None if a</p> <code>Optional[str]</code> <p>developer_message cannot be extracted</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>def extract_developer_message(ex: HTTPStatusError) -&gt; Optional[str]:\n    \"\"\"\n    Extracts developer message from a error response from the dbt Cloud\n    administrative API.\n\n    Args:\n        ex: An HTTPStatusError raised by httpx\n\n    Returns:\n        developer_message from dbt Cloud administrative API response or None if a\n        developer_message cannot be extracted\n    \"\"\"\n    response_payload = ex.response.json()\n    status = response_payload.get(\"status\", {})\n    return status.get(\"developer_message\")\n</code></pre>"},{"location":"integrations/prefect-dbt/cloud/utils/#prefect_dbt.cloud.utils.extract_user_message","title":"<code>extract_user_message</code>","text":"<p>Extracts user message from a error response from the dbt Cloud administrative API.</p> <p>Parameters:</p> Name Type Description Default <code>ex</code> <code>HTTPStatusError</code> <p>An HTTPStatusError raised by httpx</p> required <p>Returns:</p> Type Description <code>Optional[str]</code> <p>user_message from dbt Cloud administrative API response or None if a</p> <code>Optional[str]</code> <p>user_message cannot be extracted</p> Source code in <code>prefect_dbt/cloud/utils.py</code> <pre><code>def extract_user_message(ex: HTTPStatusError) -&gt; Optional[str]:\n    \"\"\"\n    Extracts user message from a error response from the dbt Cloud administrative API.\n\n    Args:\n        ex: An HTTPStatusError raised by httpx\n\n    Returns:\n        user_message from dbt Cloud administrative API response or None if a\n        user_message cannot be extracted\n    \"\"\"\n    response_payload = ex.response.json()\n    status = response_payload.get(\"status\", {})\n    return status.get(\"user_message\")\n</code></pre>"},{"location":"integrations/prefect-docker/","title":"prefect-docker","text":"<p>The prefect-docker library is required to create deployments that will submit runs to most Prefect work pool infrastructure types. See the Prefect tutorial and the Docker guide to learn how to create and run deployments that use Docker.</p>"},{"location":"integrations/prefect-docker/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-docker/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Docker installed and running.</li> </ul>"},{"location":"integrations/prefect-docker/#install-prefect-docker","title":"Install prefect-docker","text":"<pre><code>pip install prefect-docker\n</code></pre>"},{"location":"integrations/prefect-docker/#resources","title":"Resources","text":"<p>For assistance using Docker, consult the Docker documentation.</p> <p>Refer to the prefect-docker API documentation linked in the sidebar to explore all the capabilities of the prefect-docker library.</p>"},{"location":"integrations/prefect-docker/containers/","title":"Containers","text":""},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers","title":"<code>prefect_docker.containers</code>","text":"<p>Integrations with Docker Containers.</p>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.create_docker_container","title":"<code>create_docker_container</code>  <code>async</code>","text":"<p>Create a container without starting it. Similar to docker create.</p> <p>Parameters:</p> Name Type Description Default <code>image</code> <code>str</code> <p>The image to run.</p> required <code>command</code> <code>Optional[Union[str, List[str]]]</code> <p>The command(s) to run in the container.</p> <code>None</code> <code>name</code> <code>Optional[str]</code> <p>The name for this container.</p> <code>None</code> <code>detach</code> <code>Optional[bool]</code> <p>Run container in the background.</p> <code>None</code> <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>entrypoint</code> <code>Optional[Union[str, List[str]]]</code> <p>The entrypoint for the container.</p> <code>None</code> <code>environment</code> <code>Optional[Union[Dict[str, str], List[str]]]</code> <p>Environment variables to set inside the container, as a dictionary or a list of strings in the format [\"SOMEVARIABLE=xxx\"].</p> <code>None</code> <code>**create_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.create</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>A Docker Container object.</p> <p>Examples:</p> <p>Create a container with the Prefect image. <pre><code>from prefect import flow\nfrom prefect_docker.containers import create_docker_container\n\n@flow\ndef create_docker_container_flow():\n    container = create_docker_container(\n        image=\"prefecthq/prefect\",\n        command=\"echo 'hello world!'\"\n    )\n\ncreate_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def create_docker_container(\n    image: str,\n    command: Optional[Union[str, List[str]]] = None,\n    name: Optional[str] = None,\n    detach: Optional[bool] = None,\n    entrypoint: Optional[Union[str, List[str]]] = None,\n    environment: Optional[Union[Dict[str, str], List[str]]] = None,\n    docker_host: Optional[DockerHost] = None,\n    **create_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Create a container without starting it. Similar to docker create.\n\n    Args:\n        image: The image to run.\n        command: The command(s) to run in the container.\n        name: The name for this container.\n        detach: Run container in the background.\n        docker_host: Settings for interacting with a Docker host.\n        entrypoint: The entrypoint for the container.\n        environment: Environment variables to set inside the container,\n            as a dictionary or a list of strings in the format [\"SOMEVARIABLE=xxx\"].\n        **create_kwargs: Additional keyword arguments to pass to\n            [`client.containers.create`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.ContainerCollection.create).\n\n    Returns:\n        A Docker Container object.\n\n    Examples:\n        Create a container with the Prefect image.\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import create_docker_container\n\n        @flow\n        def create_docker_container_flow():\n            container = create_docker_container(\n                image=\"prefecthq/prefect\",\n                command=\"echo 'hello world!'\"\n            )\n\n        create_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        logger.info(f\"Creating container with {image!r} image.\")\n        container = await run_sync_in_worker_thread(\n            client.containers.create,\n            image=image,\n            command=command,\n            name=name,\n            detach=detach,\n            entrypoint=entrypoint,\n            environment=environment,\n            **create_kwargs,\n        )\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.get_docker_container_logs","title":"<code>get_docker_container_logs</code>  <code>async</code>","text":"<p>Get logs from this container. Similar to the docker logs command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to pull logs from.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**logs_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).logs</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The Container's logs.</p> <p>Examples:</p> <p>Gets logs from a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import get_docker_container_logs\n\n@flow\ndef get_docker_container_logs_flow():\n    logs = get_docker_container_logs(container_id=\"c157\")\n    return logs\n\nget_docker_container_logs_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def get_docker_container_logs(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **logs_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Get logs from this container. Similar to the docker logs command.\n\n    Args:\n        container_id: The container ID to pull logs from.\n        docker_host: Settings for interacting with a Docker host.\n        **logs_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).logs`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.logs).\n\n    Returns:\n        The Container's logs.\n\n    Examples:\n        Gets logs from a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import get_docker_container_logs\n\n        @flow\n        def get_docker_container_logs_flow():\n            logs = get_docker_container_logs(container_id=\"c157\")\n            return logs\n\n        get_docker_container_logs_flow()\n        ```\n\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Retrieving logs from {container.id!r} container.\")\n        logs = await run_sync_in_worker_thread(container.logs, **logs_kwargs)\n\n    return logs.decode()\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.remove_docker_container","title":"<code>remove_docker_container</code>  <code>async</code>","text":"<p>Remove this container. Similar to the docker rm command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to remove.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**remove_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).remove</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Removes a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import remove_docker_container\n\n@flow\ndef remove_docker_container_flow():\n    container = remove_docker_container(container_id=\"c157\")\n    return container\n\nremove_docker_container()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def remove_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **remove_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Remove this container. Similar to the docker rm command.\n\n    Args:\n        container_id: The container ID to remove.\n        docker_host: Settings for interacting with a Docker host.\n        **remove_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).remove`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.remove).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Removes a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import remove_docker_container\n\n        @flow\n        def remove_docker_container_flow():\n            container = remove_docker_container(container_id=\"c157\")\n            return container\n\n        remove_docker_container()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Removing container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.remove, **remove_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.start_docker_container","title":"<code>start_docker_container</code>  <code>async</code>","text":"<p>Start this container. Similar to the docker start command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to start.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**start_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).start</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Start a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import start_docker_container\n\n@flow\ndef start_docker_container_flow():\n    container = start_docker_container(container_id=\"c157\")\n    return container\n\nstart_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def start_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **start_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Start this container. Similar to the docker start command.\n\n    Args:\n        container_id: The container ID to start.\n        docker_host: Settings for interacting with a Docker host.\n        **start_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).start`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.start).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Start a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import start_docker_container\n\n        @flow\n        def start_docker_container_flow():\n            container = start_docker_container(container_id=\"c157\")\n            return container\n\n        start_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Starting container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.start, **start_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/containers/#prefect_docker.containers.stop_docker_container","title":"<code>stop_docker_container</code>  <code>async</code>","text":"<p>Stops a container. Similar to the docker stop command.</p> <p>Parameters:</p> Name Type Description Default <code>container_id</code> <code>str</code> <p>The container ID to stop.</p> required <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host.</p> <code>None</code> <code>**stop_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.containers.get(container_id).stop</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Container</code> <p>The Docker Container object.</p> <p>Examples:</p> <p>Stop a container with an ID that starts with \"c157\". <pre><code>from prefect import flow\nfrom prefect_docker.containers import stop_docker_container\n\n@flow\ndef stop_docker_container_flow():\n    container = stop_docker_container(container_id=\"c157\")\n    return container\n\nstop_docker_container_flow()\n</code></pre></p> Source code in <code>prefect_docker/containers.py</code> <pre><code>@task\nasync def stop_docker_container(\n    container_id: str,\n    docker_host: Optional[DockerHost] = None,\n    **stop_kwargs: Dict[str, Any],\n) -&gt; Container:\n    \"\"\"\n    Stops a container. Similar to the docker stop command.\n\n    Args:\n        container_id: The container ID to stop.\n        docker_host: Settings for interacting with a Docker host.\n        **stop_kwargs: Additional keyword arguments to pass to\n            [`client.containers.get(container_id).stop`](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.Container.stop).\n\n    Returns:\n        The Docker Container object.\n\n    Examples:\n        Stop a container with an ID that starts with \"c157\".\n        ```python\n        from prefect import flow\n        from prefect_docker.containers import stop_docker_container\n\n        @flow\n        def stop_docker_container_flow():\n            container = stop_docker_container(container_id=\"c157\")\n            return container\n\n        stop_docker_container_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    with (docker_host or DockerHost()).get_client() as client:\n        container = await run_sync_in_worker_thread(client.containers.get, container_id)\n        logger.info(f\"Stopping container {container.id!r}.\")\n        await run_sync_in_worker_thread(container.stop, **stop_kwargs)\n\n    return container\n</code></pre>"},{"location":"integrations/prefect-docker/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials","title":"<code>prefect_docker.credentials</code>","text":"<p>Module containing docker credentials.</p>"},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials.DockerRegistryCredentials","title":"<code>DockerRegistryCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage credentials for interacting with a Docker Registry.</p> <p>Examples:</p> <p>Log into Docker Registry. <pre><code>from prefect_docker import DockerHost, DockerRegistryCredentials\n\ndocker_host = DockerHost()\ndocker_registry_credentials = DockerRegistryCredentials(\n    username=\"my_username\",\n    password=\"my_password\",\n    registry_url=\"registry.hub.docker.com\",\n)\nwith docker_host.get_client() as client:\n    docker_registry_credentials.login(client)\n</code></pre></p> Source code in <code>prefect_docker/credentials.py</code> <pre><code>class DockerRegistryCredentials(Block):\n    \"\"\"\n    Block used to manage credentials for interacting with a Docker Registry.\n\n    Examples:\n        Log into Docker Registry.\n        ```python\n        from prefect_docker import DockerHost, DockerRegistryCredentials\n\n        docker_host = DockerHost()\n        docker_registry_credentials = DockerRegistryCredentials(\n            username=\"my_username\",\n            password=\"my_password\",\n            registry_url=\"registry.hub.docker.com\",\n        )\n        with docker_host.get_client() as client:\n            docker_registry_credentials.login(client)\n        ```\n    \"\"\"\n\n    _block_type_name = \"Docker Registry Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"  # noqa\n    _description = \"Store credentials for interacting with a Docker Registry.\"\n\n    username: str = Field(\n        default=..., description=\"The username to log into the registry with.\"\n    )\n    password: SecretStr = Field(\n        default=..., description=\"The password to log into the registry with.\"\n    )\n    registry_url: str = Field(\n        default=...,\n        description=(\n            'The URL to the registry. Generally, \"http\" or \"https\" can be omitted.'\n        ),\n        example=\"index.docker.io\",\n    )\n    reauth: bool = Field(\n        default=True,\n        description=\"Whether or not to reauthenticate on each interaction.\",\n    )\n\n    async def login(self, client: docker.DockerClient):\n        \"\"\"\n        Authenticates a given Docker client with the configured Docker registry.\n\n        Args:\n            client: A Docker Client.\n        \"\"\"\n        logger = get_run_logger()\n        logger.debug(f\"Logging into {self.registry_url}.\")\n        await run_sync_in_worker_thread(\n            client.login,\n            username=self.username,\n            password=self.password.get_secret_value(),\n            registry=self.registry_url,\n            # See https://github.com/docker/docker-py/issues/2256 for information on\n            # the default value for reauth.\n            reauth=self.reauth,\n        )\n</code></pre>"},{"location":"integrations/prefect-docker/credentials/#prefect_docker.credentials.DockerRegistryCredentials.login","title":"<code>login</code>  <code>async</code>","text":"<p>Authenticates a given Docker client with the configured Docker registry.</p> <p>Parameters:</p> Name Type Description Default <code>client</code> <code>DockerClient</code> <p>A Docker Client.</p> required Source code in <code>prefect_docker/credentials.py</code> <pre><code>async def login(self, client: docker.DockerClient):\n    \"\"\"\n    Authenticates a given Docker client with the configured Docker registry.\n\n    Args:\n        client: A Docker Client.\n    \"\"\"\n    logger = get_run_logger()\n    logger.debug(f\"Logging into {self.registry_url}.\")\n    await run_sync_in_worker_thread(\n        client.login,\n        username=self.username,\n        password=self.password.get_secret_value(),\n        registry=self.registry_url,\n        # See https://github.com/docker/docker-py/issues/2256 for information on\n        # the default value for reauth.\n        reauth=self.reauth,\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/host/","title":"Host","text":""},{"location":"integrations/prefect-docker/host/#prefect_docker.host","title":"<code>prefect_docker.host</code>","text":"<p>Module containing Docker host settings.</p>"},{"location":"integrations/prefect-docker/host/#prefect_docker.host.DockerHost","title":"<code>DockerHost</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage settings for interacting with a Docker host.</p> <p>Attributes:</p> Name Type Description <code>base_url</code> <code>Optional[str]</code> <p>URL to the Docker server, e.g. <code>unix:///var/run/docker.sock</code> or <code>tcp://127.0.0.1:1234</code>. If this is not set, the client will be configured from environment variables.</p> <code>version</code> <code>str</code> <p>The version of the API to use. Set to auto to automatically detect the server's version.</p> <code>timeout</code> <code>Optional[int]</code> <p>Default timeout for API calls, in seconds.</p> <code>max_pool_size</code> <code>Optional[int]</code> <p>The maximum number of connections to save in the pool.</p> <code>client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>docker.from_env()</code> or <code>DockerClient</code>.</p> <p>Examples:</p> <p>Get a Docker Host client. <pre><code>from prefect_docker import DockerHost\n\ndocker_host = DockerHost(\nbase_url=\"tcp://127.0.0.1:1234\",\n    max_pool_size=4\n)\nwith docker_host.get_client() as client:\n    ... # Use the client for Docker operations\n</code></pre></p> Source code in <code>prefect_docker/host.py</code> <pre><code>class DockerHost(Block):\n    \"\"\"\n    Block used to manage settings for interacting with a Docker host.\n\n    Attributes:\n        base_url: URL to the Docker server, e.g. `unix:///var/run/docker.sock`\n            or `tcp://127.0.0.1:1234`. If this is not set, the client will\n            be configured from environment variables.\n        version: The version of the API to use. Set to auto to\n            automatically detect the server's version.\n        timeout: Default timeout for API calls, in seconds.\n        max_pool_size: The maximum number of connections to save in the pool.\n        client_kwargs: Additional keyword arguments to pass to\n            `docker.from_env()` or `DockerClient`.\n\n    Examples:\n        Get a Docker Host client.\n        ```python\n        from prefect_docker import DockerHost\n\n        docker_host = DockerHost(\n        base_url=\"tcp://127.0.0.1:1234\",\n            max_pool_size=4\n        )\n        with docker_host.get_client() as client:\n            ... # Use the client for Docker operations\n        ```\n    \"\"\"\n\n    _block_type_name = \"Docker Host\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/14a315b79990200db7341e42553e23650b34bb96-250x250.png\"  # noqa\n    _description = \"Store settings for interacting with a Docker host.\"\n\n    base_url: Optional[str] = Field(\n        default=None,\n        description=\"URL to the Docker host.\",\n        title=\"Base URL\",\n        example=\"unix:///var/run/docker.sock\",\n    )\n    version: str = Field(default=\"auto\", description=\"The version of the API to use\")\n    timeout: Optional[int] = Field(\n        default=None, description=\"Default timeout for API calls, in seconds.\"\n    )\n    max_pool_size: Optional[int] = Field(\n        default=None,\n        description=\"The maximum number of connections to save in the pool.\",\n    )\n    client_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional Configuration\",\n        description=(\n            \"Additional keyword arguments to pass to \"\n            \"`docker.from_env()` or `DockerClient`.\"\n        ),\n    )\n\n    def get_client(self) -&gt; docker.DockerClient:\n        \"\"\"\n        Gets a Docker Client to communicate with a Docker host.\n\n        Returns:\n            A Docker Client.\n        \"\"\"\n        logger = get_run_logger()\n        client_kwargs = {\n            \"version\": self.version,\n            \"timeout\": self.timeout,\n            \"max_pool_size\": self.max_pool_size,\n            **self.client_kwargs,\n        }\n        client_kwargs = {\n            key: value for key, value in client_kwargs.items() if value is not None\n        }\n        if self.base_url is None:\n            logger.debug(\n                f\"Creating a Docker client from \"\n                f\"environment variables, using {self.version} version.\"\n            )\n            client = _ContextManageableDockerClient.from_env(**client_kwargs)\n        else:\n            logger.debug(\n                f\"Creating a Docker client to {self.base_url} \"\n                f\"using {self.version} version.\"\n            )\n            client = _ContextManageableDockerClient(\n                base_url=self.base_url, **client_kwargs\n            )\n        return client\n</code></pre>"},{"location":"integrations/prefect-docker/host/#prefect_docker.host.DockerHost.get_client","title":"<code>get_client</code>","text":"<p>Gets a Docker Client to communicate with a Docker host.</p> <p>Returns:</p> Type Description <code>DockerClient</code> <p>A Docker Client.</p> Source code in <code>prefect_docker/host.py</code> <pre><code>def get_client(self) -&gt; docker.DockerClient:\n    \"\"\"\n    Gets a Docker Client to communicate with a Docker host.\n\n    Returns:\n        A Docker Client.\n    \"\"\"\n    logger = get_run_logger()\n    client_kwargs = {\n        \"version\": self.version,\n        \"timeout\": self.timeout,\n        \"max_pool_size\": self.max_pool_size,\n        **self.client_kwargs,\n    }\n    client_kwargs = {\n        key: value for key, value in client_kwargs.items() if value is not None\n    }\n    if self.base_url is None:\n        logger.debug(\n            f\"Creating a Docker client from \"\n            f\"environment variables, using {self.version} version.\"\n        )\n        client = _ContextManageableDockerClient.from_env(**client_kwargs)\n    else:\n        logger.debug(\n            f\"Creating a Docker client to {self.base_url} \"\n            f\"using {self.version} version.\"\n        )\n        client = _ContextManageableDockerClient(\n            base_url=self.base_url, **client_kwargs\n        )\n    return client\n</code></pre>"},{"location":"integrations/prefect-docker/images/","title":"Images","text":""},{"location":"integrations/prefect-docker/images/#prefect_docker.images","title":"<code>prefect_docker.images</code>","text":"<p>Integrations with Docker Images.</p>"},{"location":"integrations/prefect-docker/images/#prefect_docker.images.pull_docker_image","title":"<code>pull_docker_image</code>  <code>async</code>","text":"<p>Pull an image of the given name and return it. Similar to the docker pull command.</p> <p>If all_tags is set, the tag parameter is ignored and all image tags will be pulled.</p> <p>Parameters:</p> Name Type Description Default <code>repository</code> <code>str</code> <p>The repository to pull.</p> required <code>tag</code> <code>Optional[str]</code> <p>The tag to pull; if not provided, it is set to latest.</p> <code>None</code> <code>platform</code> <code>Optional[str]</code> <p>Platform in the format os[/arch[/variant]].</p> <code>None</code> <code>all_tags</code> <code>bool</code> <p>Pull all image tags which will return a list of Images.</p> <code>False</code> <code>docker_host</code> <code>Optional[DockerHost]</code> <p>Settings for interacting with a Docker host; if not provided, will automatically instantiate a <code>DockerHost</code> from env.</p> <code>None</code> <code>docker_registry_credentials</code> <code>Optional[DockerRegistryCredentials]</code> <p>Docker credentials used to log in to a registry before pulling the image.</p> <code>None</code> <code>**pull_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.images.pull</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Image, List[Image]]</code> <p>The image that has been pulled, or a list of images if <code>all_tags</code> is <code>True</code>.</p> <p>Examples:</p> <p>Pull prefecthq/prefect image with the tag latest-python3.10. <pre><code>from prefect import flow\nfrom prefect_docker.images import pull_docker_image\n\n@flow\ndef pull_docker_image_flow():\n    image = pull_docker_image(\n        repository=\"prefecthq/prefect\",\n        tag=\"latest-python3.10\"\n    )\n    return image\n\npull_docker_image_flow()\n</code></pre></p> Source code in <code>prefect_docker/images.py</code> <pre><code>@task\nasync def pull_docker_image(\n    repository: str,\n    tag: Optional[str] = None,\n    platform: Optional[str] = None,\n    all_tags: bool = False,\n    docker_host: Optional[DockerHost] = None,\n    docker_registry_credentials: Optional[DockerRegistryCredentials] = None,\n    **pull_kwargs: Dict[str, Any],\n) -&gt; Union[Image, List[Image]]:\n    \"\"\"\n    Pull an image of the given name and return it. Similar to the docker pull command.\n\n    If all_tags is set, the tag parameter is ignored and all image tags will be pulled.\n\n    Args:\n        repository: The repository to pull.\n        tag: The tag to pull; if not provided, it is set to latest.\n        platform: Platform in the format os[/arch[/variant]].\n        all_tags: Pull all image tags which will return a list of Images.\n        docker_host: Settings for interacting with a Docker host; if not\n            provided, will automatically instantiate a `DockerHost` from env.\n        docker_registry_credentials: Docker credentials used to log in to\n            a registry before pulling the image.\n        **pull_kwargs: Additional keyword arguments to pass to `client.images.pull`.\n\n    Returns:\n        The image that has been pulled, or a list of images if `all_tags` is `True`.\n\n    Examples:\n        Pull prefecthq/prefect image with the tag latest-python3.10.\n        ```python\n        from prefect import flow\n        from prefect_docker.images import pull_docker_image\n\n        @flow\n        def pull_docker_image_flow():\n            image = pull_docker_image(\n                repository=\"prefecthq/prefect\",\n                tag=\"latest-python3.10\"\n            )\n            return image\n\n        pull_docker_image_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    if tag and all_tags:\n        raise ValueError(\"Cannot pass `tags` and `all_tags` together\")\n\n    pull_kwargs = {\n        \"repository\": repository,\n        \"tag\": tag,\n        \"platform\": platform,\n        \"all_tags\": all_tags,\n        **pull_kwargs,\n    }\n    pull_kwargs = {\n        key: value for key, value in pull_kwargs.items() if value is not None\n    }\n\n    with (docker_host or DockerHost()).get_client() as client:\n        if docker_registry_credentials is not None:\n            await docker_registry_credentials.login(client=client)\n\n        if tag:\n            logger.info(f\"Pulling image: {repository}:{tag}.\")\n        elif all_tags:\n            logger.info(f\"Pulling all images from: {repository}\")\n\n        image = await run_sync_in_worker_thread(client.images.pull, **pull_kwargs)\n\n    return image\n</code></pre>"},{"location":"integrations/prefect-docker/worker/","title":"Worker","text":""},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker","title":"<code>prefect_docker.worker</code>","text":"<p>Module containing the Docker worker used for executing flow runs as Docker containers.</p> <p>To start a Docker worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type docker\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker","title":"<code>DockerWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Docker containers.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Docker containers.\"\"\"\n\n    type = \"docker\"\n    job_configuration = DockerWorkerJobConfiguration\n    _description = (\n        \"Execute flow runs within Docker containers. Works well for managing flow \"\n        \"execution environments via Docker images. Requires access to a running \"\n        \"Docker daemon.\"\n    )\n    _display_name = \"Docker\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-docker/worker/\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/2IfXXfMq66mrzJBDFFCHTp/6d8f320d9e4fc4393f045673d61ab612/Moby-logo.png?h=250\"  # noqa\n\n    def __init__(self, *args: Any, test_mode: bool = None, **kwargs: Any) -&gt; None:\n        if test_mode is None:\n            self.test_mode = bool(os.getenv(\"PREFECT_DOCKER_TEST_MODE\", False))\n        else:\n            self.test_mode = test_mode\n        super().__init__(*args, **kwargs)\n\n    async def setup(self):\n        if not self.test_mode:\n            self._client = get_client()\n            if self._client.server_type == ServerType.EPHEMERAL:\n                raise RuntimeError(\n                    \"Docker worker cannot be used with an ephemeral server. Please set\"\n                    \" PREFECT_API_URL to the URL for your Prefect API instance. You\"\n                    \" can use a local Prefect API instance by running `prefect server\"\n                    \" start`.\"\n                )\n\n        return await super().setup()\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: BaseJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; BaseWorkerResult:\n        \"\"\"\n        Executes a flow run within a Docker container and waits for the flow run\n        to complete.\n        \"\"\"\n        # The `docker` library uses requests instead of an async http library so it must\n        # be run in a thread to avoid blocking the event loop.\n        container, created_event = await run_sync_in_worker_thread(\n            self._create_and_start_container, configuration\n        )\n        container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n        # Mark as started and return the infrastructure id\n        if task_status:\n            task_status.started(container_pid)\n\n        # Monitor the container\n        container = await run_sync_in_worker_thread(\n            self._watch_container_safe, container, configuration, created_event\n        )\n\n        exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n        return DockerWorkerResult(\n            status_code=exit_code if exit_code is not None else -1,\n            identifier=container_pid,\n        )\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: DockerWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a container for a cancelled flow run based on the provided infrastructure\n        PID.\n        \"\"\"\n        docker_client = self._get_client()\n\n        base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n        if docker_client.api.base_url != base_url:\n            raise InfrastructureNotAvailable(\n                \"\".join(\n                    [\n                        (\n                            f\"Unable to stop container {container_id!r}: the current\"\n                            \" Docker API \"\n                        ),\n                        (\n                            f\"URL {docker_client.api.base_url!r} does not match the\"\n                            \" expected \"\n                        ),\n                        f\"API base URL {base_url}.\",\n                    ]\n                )\n            )\n        await run_sync_in_worker_thread(\n            self._stop_container, container_id, docker_client, grace_seconds\n        )\n\n    def _stop_container(\n        self,\n        container_id: str,\n        client: \"DockerClient\",\n        grace_seconds: int = 30,\n    ):\n        try:\n            container = client.containers.get(container_id=container_id)\n        except docker.errors.NotFound:\n            raise InfrastructureNotFound(\n                f\"Unable to stop container {container_id!r}: The container was not\"\n                \" found.\"\n            )\n\n        container.stop(timeout=grace_seconds)\n\n    def _get_client(self):\n        \"\"\"Returns a docker client.\"\"\"\n        try:\n            with warnings.catch_warnings():\n                # Silence warnings due to use of deprecated methods within dockerpy\n                # See https://github.com/docker/docker-py/pull/2931\n                warnings.filterwarnings(\n                    \"ignore\",\n                    message=\"distutils Version classes are deprecated.*\",\n                    category=DeprecationWarning,\n                )\n\n                docker_client = docker.from_env()\n\n        except docker.errors.DockerException as exc:\n            raise RuntimeError(\"Could not connect to Docker.\") from exc\n\n        return docker_client\n\n    def _get_infrastructure_pid(self, container_id: str) -&gt; str:\n        \"\"\"Generates a Docker infrastructure_pid string in the form of\n        `&lt;docker_host_base_url&gt;:&lt;container_id&gt;`.\n        \"\"\"\n        docker_client = self._get_client()\n        base_url = docker_client.api.base_url\n        docker_client.close()\n        return f\"{base_url}:{container_id}\"\n\n    def _parse_infrastructure_pid(self, infrastructure_pid: str) -&gt; Tuple[str, str]:\n        \"\"\"Splits a Docker infrastructure_pid into its component parts\"\"\"\n\n        # base_url can contain `:` so we only want the last item of the split\n        base_url, container_id = infrastructure_pid.rsplit(\":\", 1)\n        return base_url, str(container_id)\n\n    def _build_container_settings(\n        self,\n        docker_client: \"DockerClient\",\n        configuration: DockerWorkerJobConfiguration,\n    ) -&gt; Dict:\n        \"\"\"Builds a dictionary of container settings to pass to the Docker API.\"\"\"\n        network_mode = configuration.get_network_mode()\n\n        container_create_kwargs = (\n            configuration.container_create_kwargs\n            if configuration.container_create_kwargs\n            else {}\n        )\n        container_create_kwargs = {\n            k: v\n            for k, v in container_create_kwargs.items()\n            if k not in configuration.__fields__\n        }\n\n        return dict(\n            image=configuration.image,\n            network=configuration.networks[0] if configuration.networks else None,\n            network_mode=network_mode,\n            command=configuration.command,\n            environment=configuration.env,\n            auto_remove=configuration.auto_remove,\n            labels=configuration.labels,\n            extra_hosts=configuration.get_extra_hosts(docker_client),\n            name=configuration.name,\n            volumes=configuration.volumes,\n            mem_limit=configuration.mem_limit,\n            memswap_limit=configuration.memswap_limit,\n            privileged=configuration.privileged,\n            **container_create_kwargs,\n        )\n\n    def _create_and_start_container(\n        self, configuration: DockerWorkerJobConfiguration\n    ) -&gt; Tuple[\"Container\", Event]:\n        \"\"\"Creates and starts a Docker container.\"\"\"\n        docker_client = self._get_client()\n        if configuration.registry_credentials:\n            self._logger.info(\"Logging into Docker registry...\")\n            docker_client.login(\n                username=configuration.registry_credentials.username,\n                password=configuration.registry_credentials.password.get_secret_value(),\n                registry=configuration.registry_credentials.registry_url,\n                reauth=configuration.registry_credentials.reauth,\n            )\n        container_settings = self._build_container_settings(\n            docker_client, configuration\n        )\n\n        if self._should_pull_image(docker_client, configuration=configuration):\n            self._logger.info(f\"Pulling image {configuration.image!r}...\")\n            self._pull_image(docker_client, configuration)\n\n        try:\n            container = self._create_container(docker_client, **container_settings)\n        except Exception as exc:\n            self._emit_container_creation_failed_event(configuration)\n            raise exc\n\n        created_event = self._emit_container_status_change_event(\n            container, configuration\n        )\n\n        # Add additional networks after the container is created; only one network can\n        # be attached at creation time\n        if len(configuration.networks) &gt; 1:\n            for network_name in configuration.networks[1:]:\n                network = docker_client.networks.get(network_name)\n                network.connect(container)\n\n        # Start the container\n        container.start()\n\n        docker_client.close()\n\n        return container, created_event\n\n    def _watch_container_safe(\n        self,\n        container: \"Container\",\n        configuration: DockerWorkerJobConfiguration,\n        created_event: Event,\n    ) -&gt; \"Container\":\n        \"\"\"Watches a container for completion, handling any errors that may occur.\"\"\"\n        # Monitor the container capturing the latest snapshot while capturing\n        # not found errors\n        docker_client = self._get_client()\n\n        try:\n            seen_statuses = {container.status}\n            last_event = created_event\n            for latest_container in self._watch_container(\n                docker_client, container.id, configuration\n            ):\n                container = latest_container\n                if container.status not in seen_statuses:\n                    seen_statuses.add(container.status)\n                    last_event = self._emit_container_status_change_event(\n                        container, configuration, last_event=last_event\n                    )\n\n        except docker.errors.NotFound:\n            # The container was removed during watching\n            self._logger.warning(\n                f\"Docker container {container.name} was removed before we could wait \"\n                \"for its completion.\"\n            )\n        finally:\n            docker_client.close()\n\n        return container\n\n    def _watch_container(\n        self,\n        docker_client: \"DockerClient\",\n        container_id: str,\n        configuration: DockerWorkerJobConfiguration,\n    ) -&gt; Generator[None, None, \"Container\"]:\n        \"\"\"\n        Watches a container for completion, yielding the latest container\n        snapshot on each iteration.\n        \"\"\"\n        container: \"Container\" = docker_client.containers.get(container_id)\n\n        status = container.status\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n        if configuration.stream_output:\n            try:\n                for log in container.logs(stream=True):\n                    log: bytes\n                    print(log.decode().rstrip())\n            except docker.errors.APIError as exc:\n                if \"marked for removal\" in str(exc):\n                    self._logger.warning(\n                        f\"Docker container {container.name} was marked for removal\"\n                        \" before logs could be retrieved. Output will not be\"\n                        \" streamed. \"\n                    )\n                else:\n                    self._logger.exception(\n                        \"An unexpected Docker API error occurred while streaming output \"\n                        f\"from container {container.name}.\"\n                    )\n\n            container.reload()\n            if container.status != status:\n                self._logger.info(\n                    f\"Docker container {container.name!r} has status\"\n                    f\" {container.status!r}\"\n                )\n            yield container\n\n        container.wait()\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        yield container\n\n    def _should_pull_image(\n        self, docker_client: \"DockerClient\", configuration: DockerWorkerJobConfiguration\n    ) -&gt; bool:\n        \"\"\"\n        Decide whether we need to pull the Docker image.\n        \"\"\"\n        image_pull_policy = configuration._determine_image_pull_policy()\n\n        if image_pull_policy is ImagePullPolicy.ALWAYS:\n            return True\n        elif image_pull_policy is ImagePullPolicy.NEVER:\n            return False\n        elif image_pull_policy is ImagePullPolicy.IF_NOT_PRESENT:\n            try:\n                # NOTE: images.get() wants the tag included with the image\n                # name, while images.pull() wants them split.\n                docker_client.images.get(configuration.image)\n            except docker.errors.ImageNotFound:\n                self._logger.debug(\n                    f\"Could not find Docker image locally: {configuration.image}\"\n                )\n                return True\n        return False\n\n    def _pull_image(\n        self, docker_client: \"DockerClient\", configuration: DockerWorkerJobConfiguration\n    ):\n        \"\"\"\n        Pull the image we're going to use to create the container.\n        \"\"\"\n        image, tag = parse_image_tag(configuration.image)\n\n        return docker_client.images.pull(image, tag)\n\n    def _create_container(self, docker_client: \"DockerClient\", **kwargs) -&gt; \"Container\":\n        \"\"\"\n        Create a docker container with retries on name conflicts.\n\n        If the container already exists with the given name, an incremented index is\n        added.\n        \"\"\"\n        # Create the container with retries on name conflicts (with an incremented idx)\n        index = 0\n        container = None\n        name = original_name = kwargs.pop(\"name\")\n\n        while not container:\n            try:\n                display_name = repr(name) if name else \"with auto-generated name\"\n                self._logger.info(f\"Creating Docker container {display_name}...\")\n                container = docker_client.containers.create(name=name, **kwargs)\n            except docker.errors.APIError as exc:\n                if \"Conflict\" in str(exc) and \"container name\" in str(exc):\n                    self._logger.info(\n                        f\"Docker container name {display_name} already exists; \"\n                        \"retrying...\"\n                    )\n                    index += 1\n                    name = f\"{original_name}-{index}\"\n                else:\n                    raise\n\n        self._logger.info(\n            f\"Docker container {container.name!r} has status {container.status!r}\"\n        )\n        return container\n\n    def _container_as_resource(self, container: \"Container\") -&gt; Dict[str, str]:\n        \"\"\"Convert a container to a resource dictionary\"\"\"\n        return {\n            \"prefect.resource.id\": f\"prefect.docker.container.{container.id}\",\n            \"prefect.resource.name\": container.name,\n        }\n\n    def _emit_container_creation_failed_event(\n        self, configuration: DockerWorkerJobConfiguration\n    ) -&gt; Event:\n        \"\"\"Emit a Prefect event when a docker container fails to be created.\"\"\"\n        return emit_event(\n            event=\"prefect.docker.container.creation-failed\",\n            resource=self._event_resource(),\n            related=self._event_related_resources(configuration=configuration),\n        )\n\n    def _emit_container_status_change_event(\n        self,\n        container: \"Container\",\n        configuration: DockerWorkerJobConfiguration,\n        last_event: Optional[Event] = None,\n    ) -&gt; Event:\n        \"\"\"Emit a Prefect event for a Docker container event.\"\"\"\n        related = self._event_related_resources(configuration=configuration)\n\n        worker_resource = self._event_resource()\n        worker_resource[\"prefect.resource.role\"] = \"worker\"\n        worker_related_resource = RelatedResource(__root__=worker_resource)\n\n        return emit_event(\n            event=f\"prefect.docker.container.{container.status.lower()}\",\n            resource=self._container_as_resource(container),\n            related=related + [worker_related_resource],\n            follows=last_event,\n        )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a container for a cancelled flow run based on the provided infrastructure PID.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: DockerWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a container for a cancelled flow run based on the provided infrastructure\n    PID.\n    \"\"\"\n    docker_client = self._get_client()\n\n    base_url, container_id = self._parse_infrastructure_pid(infrastructure_pid)\n    if docker_client.api.base_url != base_url:\n        raise InfrastructureNotAvailable(\n            \"\".join(\n                [\n                    (\n                        f\"Unable to stop container {container_id!r}: the current\"\n                        \" Docker API \"\n                    ),\n                    (\n                        f\"URL {docker_client.api.base_url!r} does not match the\"\n                        \" expected \"\n                    ),\n                    f\"API base URL {base_url}.\",\n                ]\n            )\n        )\n    await run_sync_in_worker_thread(\n        self._stop_container, container_id, docker_client, grace_seconds\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Docker container and waits for the flow run to complete.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: BaseJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; BaseWorkerResult:\n    \"\"\"\n    Executes a flow run within a Docker container and waits for the flow run\n    to complete.\n    \"\"\"\n    # The `docker` library uses requests instead of an async http library so it must\n    # be run in a thread to avoid blocking the event loop.\n    container, created_event = await run_sync_in_worker_thread(\n        self._create_and_start_container, configuration\n    )\n    container_pid = self._get_infrastructure_pid(container_id=container.id)\n\n    # Mark as started and return the infrastructure id\n    if task_status:\n        task_status.started(container_pid)\n\n    # Monitor the container\n    container = await run_sync_in_worker_thread(\n        self._watch_container_safe, container, configuration, created_event\n    )\n\n    exit_code = container.attrs[\"State\"].get(\"ExitCode\")\n    return DockerWorkerResult(\n        status_code=exit_code if exit_code is not None else -1,\n        identifier=container_pid,\n    )\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration","title":"<code>DockerWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Docker worker.</p> <p>An instance of this class is passed to the Docker worker's <code>run</code> method for each flow run. It contains all the information necessary to execute the flow run as a Docker container.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name to give to created Docker containers.</p> <code>command</code> <p>The command executed in created Docker containers to kick off flow run execution.</p> <code>env</code> <p>The environment variables to set in created Docker containers.</p> <code>labels</code> <p>The labels to set on created Docker containers.</p> <code>image</code> <code>str</code> <p>The image reference of a container image to use for created jobs. If not set, the latest Prefect image will be used.</p> <code>image_pull_policy</code> <code>Optional[Literal['IfNotPresent', 'Always', 'Never']]</code> <p>The image pull policy to use when pulling images.</p> <code>networks</code> <code>List[str]</code> <p>Docker networks that created containers should be connected to.</p> <code>network_mode</code> <code>Optional[str]</code> <p>The network mode for the created containers (e.g. host, bridge). If 'networks' is set, this cannot be set.</p> <code>auto_remove</code> <code>bool</code> <p>If set, containers will be deleted on completion.</p> <code>volumes</code> <code>List[str]</code> <p>Docker volumes that should be mounted in created containers.</p> <code>stream_output</code> <code>bool</code> <p>If set, the output from created containers will be streamed to local standard output.</p> <code>mem_limit</code> <code>Optional[str]</code> <p>Memory limit of created containers. Accepts a value with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) If a value is given without a unit, bytes are assumed.</p> <code>memswap_limit</code> <code>Optional[str]</code> <p>Total memory (memory + swap), -1 to disable swap. Should only be set if <code>mem_limit</code> is also set. If <code>mem_limit</code> is set, this defaults to allowing the container to use as much swap as memory. For example, if <code>mem_limit</code> is 300m and <code>memswap_limit</code> is not set, containers can use 600m in total of memory and swap.</p> <code>privileged</code> <code>bool</code> <p>Give extended privileges to created containers.</p> <code>container_create_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Extra args for docker py when creating container.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Docker worker.\n\n    An instance of this class is passed to the Docker worker's `run` method\n    for each flow run. It contains all the information necessary to execute the\n    flow run as a Docker container.\n\n    Attributes:\n        name: The name to give to created Docker containers.\n        command: The command executed in created Docker containers to kick off\n            flow run execution.\n        env: The environment variables to set in created Docker containers.\n        labels: The labels to set on created Docker containers.\n        image: The image reference of a container image to use for created jobs.\n            If not set, the latest Prefect image will be used.\n        image_pull_policy: The image pull policy to use when pulling images.\n        networks: Docker networks that created containers should be connected to.\n        network_mode: The network mode for the created containers (e.g. host, bridge).\n            If 'networks' is set, this cannot be set.\n        auto_remove: If set, containers will be deleted on completion.\n        volumes: Docker volumes that should be mounted in created containers.\n        stream_output: If set, the output from created containers will be streamed\n            to local standard output.\n        mem_limit: Memory limit of created containers. Accepts a value\n            with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) If a value is\n            given without a unit, bytes are assumed.\n        memswap_limit: Total memory (memory + swap), -1 to disable swap. Should only be\n            set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\n            allowing the container to use as much swap as memory. For example, if\n            `mem_limit` is 300m and `memswap_limit` is not set, containers can use\n            600m in total of memory and swap.\n        privileged: Give extended privileges to created containers.\n        container_create_kwargs: Extra args for docker py when creating container.\n    \"\"\"\n\n    image: str = Field(\n        default_factory=get_prefect_image_name,\n        description=\"The image reference of a container image to use for created jobs. \"\n        \"If not set, the latest Prefect image will be used.\",\n        example=\"docker.io/prefecthq/prefect:2-latest\",\n    )\n    registry_credentials: Optional[DockerRegistryCredentials] = Field(\n        default=None,\n        description=\"Credentials for logging into a Docker registry to pull\"\n        \" images from.\",\n    )\n    image_pull_policy: Optional[Literal[\"IfNotPresent\", \"Always\", \"Never\"]] = Field(\n        default=None,\n        description=\"The image pull policy to use when pulling images.\",\n    )\n    networks: List[str] = Field(\n        default_factory=list,\n        description=\"Docker networks that created containers should be connected to.\",\n    )\n    network_mode: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The network mode for the created containers (e.g. host, bridge). If\"\n            \" 'networks' is set, this cannot be set.\"\n        ),\n    )\n    auto_remove: bool = Field(\n        default=False,\n        description=\"If set, containers will be deleted on completion.\",\n    )\n    volumes: List[str] = Field(\n        default_factory=list,\n        description=\"A list of volume to mount into created containers.\",\n        example=[\"/my/local/path:/path/in/container\"],\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, the output from created containers will be streamed to local \"\n            \"standard output.\"\n        ),\n    )\n    mem_limit: Optional[str] = Field(\n        default=None,\n        title=\"Memory Limit\",\n        description=(\n            \"Memory limit of created containers. Accepts a value \"\n            \"with a unit identifier (e.g. 100000b, 1000k, 128m, 1g.) \"\n            \"If a value is given without a unit, bytes are assumed.\"\n        ),\n    )\n    memswap_limit: Optional[str] = Field(\n        default=None,\n        title=\"Memory Swap Limit\",\n        description=(\n            \"Total memory (memory + swap), -1 to disable swap. Should only be \"\n            \"set if `mem_limit` is also set. If `mem_limit` is set, this defaults to\"\n            \"allowing the container to use as much swap as memory. For example, if \"\n            \"`mem_limit` is 300m and `memswap_limit` is not set, containers can use \"\n            \"600m in total of memory and swap.\"\n        ),\n    )\n    privileged: bool = Field(\n        default=False,\n        description=\"Give extended privileges to created container.\",\n    )\n    container_create_kwargs: Optional[Dict[str, Any]] = Field(\n        default=None,\n        title=\"Container Configuration\",\n        description=(\n            \"Configuration for containers created by workers. See the [`docker-py` documentation](https://docker-py.readthedocs.io/en/stable/containers.html) for accepted values.\"\n        ),\n    )\n\n    @validator(\"volumes\")\n    def _validate_volume_format(cls, volumes):\n        \"\"\"Validates that provided volume strings are in the correct format.\"\"\"\n        for volume in volumes:\n            if \":\" not in volume:\n                raise ValueError(\n                    \"Invalid volume specification. \"\n                    f\"Expected format 'path:container_path', but got {volume!r}\"\n                )\n\n        return volumes\n\n    def _convert_labels_to_docker_format(self, labels: Dict[str, str]):\n        \"\"\"Converts labels to the format expected by Docker.\"\"\"\n        labels = labels or {}\n        new_labels = {}\n        for name, value in labels.items():\n            if \"/\" in name:\n                namespace, key = name.split(\"/\", maxsplit=1)\n                new_namespace = \".\".join(reversed(namespace.split(\".\")))\n                new_labels[f\"{new_namespace}.{key}\"] = value\n            else:\n                new_labels[name] = value\n        return new_labels\n\n    def _slugify_container_name(self) -&gt; Optional[str]:\n        \"\"\"\n        Generates a container name to match the configured name, ensuring it is Docker\n        compatible.\n        \"\"\"\n        # Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+` in the end\n        if not self.name:\n            return None\n\n        return (\n            slugify(\n                self.name,\n                lowercase=False,\n                # Docker does not limit length but URL limits apply eventually so\n                # limit the length for safety\n                max_length=250,\n                # Docker allows these characters for container names\n                regex_pattern=r\"[^a-zA-Z0-9_.-]+\",\n            ).lstrip(\n                # Docker does not allow leading underscore, dash, or period\n                \"_-.\"\n            )\n            # Docker does not allow 0 character names so cast to null if the name is\n            # empty after slufification\n            or None\n        )\n\n    def _base_environment(self):\n        \"\"\"\n        If the API URL has been set update the value to ensure connectivity\n        when using a bridge network by updating local connections to use the\n        docker internal host unless the network mode is \"host\" where localhost\n        is available already.\n        \"\"\"\n\n        base_env = super()._base_environment()\n        network_mode = self.get_network_mode()\n        if (\n            \"PREFECT_API_URL\" in base_env\n            and base_env[\"PREFECT_API_URL\"] is not None\n            and network_mode != \"host\"\n        ):\n            base_env[\"PREFECT_API_URL\"] = (\n                base_env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", \"host.docker.internal\")\n                .replace(\"127.0.0.1\", \"host.docker.internal\")\n            )\n        return base_env\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the agent for a flow run by setting the image, labels, and name\n        attributes.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self.image = self.image or get_prefect_image_name()\n        self.labels = self._convert_labels_to_docker_format(\n            {**self.labels, **CONTAINER_LABELS}\n        )\n        self.name = self._slugify_container_name()\n\n    def get_network_mode(self) -&gt; Optional[str]:\n        \"\"\"\n        Returns the network mode to use for the container based on the configured\n        options and the platform.\n        \"\"\"\n        # User's value takes precedence; this may collide with the incompatible options\n        # mentioned below.\n        if self.network_mode:\n            if sys.platform != \"linux\" and self.network_mode == \"host\":\n                warnings.warn(\n                    f\"{self.network_mode!r} network mode is not supported on platform \"\n                    f\"{sys.platform!r} and may not work as intended.\"\n                )\n            return self.network_mode\n\n        # Network mode is not compatible with networks or ports (we do not support ports\n        # yet though)\n        if self.networks:\n            return None\n\n        # Check for a local API connection\n        api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n        if api_url:\n            try:\n                _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n            except Exception as exc:\n                warnings.warn(\n                    f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                    f\"{exc}\\nThe network mode will not be inferred.\"\n                )\n                return None\n\n            host = netloc.split(\":\")[0]\n\n            # If using a locally hosted API, use a host network on linux\n            if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n                return \"host\"\n\n        # Default to unset\n        return None\n\n    def get_extra_hosts(self, docker_client) -&gt; Optional[Dict[str, str]]:\n        \"\"\"\n        A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n        with the API on Linux machines. Docker Desktop on macOS will automatically\n        already have this mapping.\n        \"\"\"\n        if sys.platform == \"linux\" and (\n            # Do not warn if the user has specified a host manually that does not use\n            # a local address\n            \"PREFECT_API_URL\" not in self.env\n            or re.search(\n                \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n                self.env[\"PREFECT_API_URL\"],\n            )\n        ):\n            user_version = packaging.version.parse(\n                format_outlier_version_name(docker_client.version()[\"Version\"])\n            )\n            required_version = packaging.version.parse(\"20.10.0\")\n\n            if user_version &lt; required_version:\n                warnings.warn(\n                    \"`host.docker.internal` could not be automatically resolved to\"\n                    \" your local ip address. This feature is not supported on Docker\"\n                    f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                    \" encounter issues.\"\n                )\n                return {}\n            else:\n                # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n                # Only supported by Docker v20.10.0+ which is our minimum recommend\n                # version\n                return {\"host.docker.internal\": \"host-gateway\"}\n\n    def _determine_image_pull_policy(self) -&gt; ImagePullPolicy:\n        \"\"\"\n        Determine the appropriate image pull policy.\n\n        1. If they specified an image pull policy, use that.\n\n        2. If they did not specify an image pull policy and gave us\n           the \"latest\" tag, use ImagePullPolicy.always.\n\n        3. If they did not specify an image pull policy and did not\n           specify a tag, use ImagePullPolicy.always.\n\n        4. If they did not specify an image pull policy and gave us\n           a tag other than \"latest\", use ImagePullPolicy.if_not_present.\n\n        This logic matches the behavior of Kubernetes.\n        See:https://kubernetes.io/docs/concepts/containers/images/#imagepullpolicy-defaulting\n        \"\"\"\n        if not self.image_pull_policy:\n            _, tag = parse_image_tag(self.image)\n            if tag == \"latest\" or not tag:\n                return ImagePullPolicy.ALWAYS\n            return ImagePullPolicy.IF_NOT_PRESENT\n        return ImagePullPolicy(self.image_pull_policy)\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.get_extra_hosts","title":"<code>get_extra_hosts</code>","text":"<p>A host.docker.internal -&gt; host-gateway mapping is necessary for communicating with the API on Linux machines. Docker Desktop on macOS will automatically already have this mapping.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def get_extra_hosts(self, docker_client) -&gt; Optional[Dict[str, str]]:\n    \"\"\"\n    A host.docker.internal -&gt; host-gateway mapping is necessary for communicating\n    with the API on Linux machines. Docker Desktop on macOS will automatically\n    already have this mapping.\n    \"\"\"\n    if sys.platform == \"linux\" and (\n        # Do not warn if the user has specified a host manually that does not use\n        # a local address\n        \"PREFECT_API_URL\" not in self.env\n        or re.search(\n            \".*(localhost)|(127.0.0.1)|(host.docker.internal).*\",\n            self.env[\"PREFECT_API_URL\"],\n        )\n    ):\n        user_version = packaging.version.parse(\n            format_outlier_version_name(docker_client.version()[\"Version\"])\n        )\n        required_version = packaging.version.parse(\"20.10.0\")\n\n        if user_version &lt; required_version:\n            warnings.warn(\n                \"`host.docker.internal` could not be automatically resolved to\"\n                \" your local ip address. This feature is not supported on Docker\"\n                f\" Engine v{user_version}, upgrade to v{required_version}+ if you\"\n                \" encounter issues.\"\n            )\n            return {}\n        else:\n            # Compatibility for linux -- https://github.com/docker/cli/issues/2290\n            # Only supported by Docker v20.10.0+ which is our minimum recommend\n            # version\n            return {\"host.docker.internal\": \"host-gateway\"}\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.get_network_mode","title":"<code>get_network_mode</code>","text":"<p>Returns the network mode to use for the container based on the configured options and the platform.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def get_network_mode(self) -&gt; Optional[str]:\n    \"\"\"\n    Returns the network mode to use for the container based on the configured\n    options and the platform.\n    \"\"\"\n    # User's value takes precedence; this may collide with the incompatible options\n    # mentioned below.\n    if self.network_mode:\n        if sys.platform != \"linux\" and self.network_mode == \"host\":\n            warnings.warn(\n                f\"{self.network_mode!r} network mode is not supported on platform \"\n                f\"{sys.platform!r} and may not work as intended.\"\n            )\n        return self.network_mode\n\n    # Network mode is not compatible with networks or ports (we do not support ports\n    # yet though)\n    if self.networks:\n        return None\n\n    # Check for a local API connection\n    api_url = self.env.get(\"PREFECT_API_URL\", PREFECT_API_URL.value())\n\n    if api_url:\n        try:\n            _, netloc, _, _, _, _ = urllib.parse.urlparse(api_url)\n        except Exception as exc:\n            warnings.warn(\n                f\"Failed to parse host from API URL {api_url!r} with exception: \"\n                f\"{exc}\\nThe network mode will not be inferred.\"\n            )\n            return None\n\n        host = netloc.split(\":\")[0]\n\n        # If using a locally hosted API, use a host network on linux\n        if sys.platform == \"linux\" and (host == \"127.0.0.1\" or host == \"localhost\"):\n            return \"host\"\n\n    # Default to unset\n    return None\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the agent for a flow run by setting the image, labels, and name attributes.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the agent for a flow run by setting the image, labels, and name\n    attributes.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    self.image = self.image or get_prefect_image_name()\n    self.labels = self._convert_labels_to_docker_format(\n        {**self.labels, **CONTAINER_LABELS}\n    )\n    self.name = self._slugify_container_name()\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.DockerWorkerResult","title":"<code>DockerWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about a completed Docker container</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class DockerWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about a completed Docker container\"\"\"\n</code></pre>"},{"location":"integrations/prefect-docker/worker/#prefect_docker.worker.ImagePullPolicy","title":"<code>ImagePullPolicy</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing the image pull policy options for a Docker container.</p> Source code in <code>prefect_docker/worker.py</code> <pre><code>class ImagePullPolicy(enum.Enum):\n    \"\"\"Enum representing the image pull policy options for a Docker container.\"\"\"\n\n    IF_NOT_PRESENT = \"IfNotPresent\"\n    ALWAYS = \"Always\"\n    NEVER = \"Never\"\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/","title":"Steps","text":""},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps","title":"<code>prefect_docker.deployments.steps</code>","text":"<p>Prefect deployment steps for building and pushing Docker images.</p> <p>These steps can be used in a <code>prefect.yaml</code> file to define the default build steps for a group of deployments, or they can be used to define the build step for a specific deployment.</p> <p>Example</p> <p>Build a Docker image before deploying a flow: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n</code></pre></p>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.BuildDockerImageResult","title":"<code>BuildDockerImageResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>build_docker_image</code> step.</p> <p>Attributes:</p> Name Type Description <code>image_name</code> <code>str</code> <p>The name of the built image.</p> <code>tag</code> <code>str</code> <p>The tag of the built image.</p> <code>image</code> <code>str</code> <p>The name and tag of the built image.</p> <code>image_id</code> <code>str</code> <p>The ID of the built image.</p> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>The additional tags on the image, in addition to <code>tag</code>.</p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>class BuildDockerImageResult(TypedDict):\n    \"\"\"\n    The result of a `build_docker_image` step.\n\n    Attributes:\n        image_name: The name of the built image.\n        tag: The tag of the built image.\n        image: The name and tag of the built image.\n        image_id: The ID of the built image.\n        additional_tags: The additional tags on the image, in addition to `tag`.\n    \"\"\"\n\n    image_name: str\n    tag: str\n    image: str\n    image_id: str\n    additional_tags: Optional[List[str]]\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.PushDockerImageResult","title":"<code>PushDockerImageResult</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The result of a <code>push_docker_image</code> step.</p> <p>Attributes:</p> Name Type Description <code>image_name</code> <code>str</code> <p>The name of the pushed image.</p> <code>tag</code> <code>Optional[str]</code> <p>The tag of the pushed image.</p> <code>image</code> <code>str</code> <p>The name and tag of the pushed image.</p> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>The additional tags on the image, in addition to <code>tag</code>.</p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>class PushDockerImageResult(TypedDict):\n    \"\"\"\n    The result of a `push_docker_image` step.\n\n    Attributes:\n        image_name: The name of the pushed image.\n        tag: The tag of the pushed image.\n        image: The name and tag of the pushed image.\n        additional_tags: The additional tags on the image, in addition to `tag`.\n    \"\"\"\n\n    image_name: str\n    tag: Optional[str]\n    image: str\n    additional_tags: Optional[List[str]]\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.build_docker_image","title":"<code>build_docker_image</code>","text":"<p>Builds a Docker image for a Prefect deployment.</p> <p>Can be used within a <code>prefect.yaml</code> file to build a Docker image prior to creating or updating a deployment.</p> <p>Parameters:</p> Name Type Description Default <code>image_name</code> <code>str</code> <p>The name of the Docker image to build, including the registry and repository.</p> required <code>dockerfile</code> <code>str</code> <p>The path to the Dockerfile used to build the image. If \"auto\" is passed, a temporary Dockerfile will be created to build the image.</p> <code>'Dockerfile'</code> <code>tag</code> <code>Optional[str]</code> <p>The tag to apply to the built image.</p> <code>None</code> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>Additional tags on the image, in addition to <code>tag</code>, to apply to the built image.</p> <code>None</code> <code>**build_kwargs</code> <p>Additional keyword arguments to pass to Docker when building the image. Available options can be found in the <code>docker-py</code> documentation.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BuildDockerImageResult</code> <p>A dictionary containing the image name and tag of the built image.</p> Example <p>Build a Docker image prior to creating a deployment: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n</code></pre></p> <p>Build a Docker image with multiple tags: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        additional_tags:\n            - v0.1.0,\n            - dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n</code></pre></p> <p>Build a Docker image using an auto-generated Dockerfile: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n</code></pre></p> <p>Build a Docker image for a different platform: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: Dockerfile\n        platform: amd64\n</code></pre></p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>@cacheable\ndef build_docker_image(\n    image_name: str,\n    dockerfile: str = \"Dockerfile\",\n    tag: Optional[str] = None,\n    additional_tags: Optional[List[str]] = None,\n    ignore_cache: bool = False,\n    **build_kwargs,\n) -&gt; BuildDockerImageResult:\n    \"\"\"\n    Builds a Docker image for a Prefect deployment.\n\n    Can be used within a `prefect.yaml` file to build a Docker\n    image prior to creating or updating a deployment.\n\n    Args:\n        image_name: The name of the Docker image to build, including the registry and\n            repository.\n        dockerfile: The path to the Dockerfile used to build the image. If \"auto\" is\n            passed, a temporary Dockerfile will be created to build the image.\n        tag: The tag to apply to the built image.\n        additional_tags: Additional tags on the image, in addition to `tag`, to apply to the built image.\n        **build_kwargs: Additional keyword arguments to pass to Docker when building\n            the image. Available options can be found in the [`docker-py`](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build)\n            documentation.\n\n    Returns:\n        A dictionary containing the image name and tag of the\n            built image.\n\n    Example:\n        Build a Docker image prior to creating a deployment:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n        ```\n\n        Build a Docker image with multiple tags:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                additional_tags:\n                    - v0.1.0,\n                    - dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n        ```\n\n        Build a Docker image using an auto-generated Dockerfile:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n        ```\n\n\n        Build a Docker image for a different platform:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: Dockerfile\n                platform: amd64\n        ```\n    \"\"\"  # noqa\n    auto_build = dockerfile == \"auto\"\n    if auto_build:\n        lines = []\n        base_image = get_prefect_image_name()\n        lines.append(f\"FROM {base_image}\")\n        dir_name = os.path.basename(os.getcwd())\n\n        if Path(\"requirements.txt\").exists():\n            lines.append(\n                f\"COPY requirements.txt /opt/prefect/{dir_name}/requirements.txt\"\n            )\n            lines.append(\n                f\"RUN python -m pip install -r /opt/prefect/{dir_name}/requirements.txt\"\n            )\n\n        lines.append(f\"COPY . /opt/prefect/{dir_name}/\")\n        lines.append(f\"WORKDIR /opt/prefect/{dir_name}/\")\n\n        temp_dockerfile = Path(\"Dockerfile\")\n        if Path(temp_dockerfile).exists():\n            raise ValueError(\"Dockerfile already exists.\")\n\n        with Path(temp_dockerfile).open(\"w\") as f:\n            f.writelines(line + \"\\n\" for line in lines)\n\n        dockerfile = str(temp_dockerfile)\n\n    build_kwargs[\"path\"] = build_kwargs.get(\"path\", os.getcwd())\n    build_kwargs[\"dockerfile\"] = dockerfile\n    build_kwargs[\"pull\"] = build_kwargs.get(\"pull\", True)\n    build_kwargs[\"decode\"] = True\n    build_kwargs[\"labels\"] = {**build_kwargs.get(\"labels\", {}), **IMAGE_LABELS}\n    image_id = None\n\n    with docker_client() as client:\n        try:\n            events = client.api.build(**build_kwargs)\n\n            try:\n                for event in events:\n                    if \"stream\" in event:\n                        sys.stdout.write(event[\"stream\"])\n                        sys.stdout.flush()\n                    elif \"aux\" in event:\n                        image_id = event[\"aux\"][\"ID\"]\n                    elif \"error\" in event:\n                        raise BuildError(event[\"error\"])\n                    elif \"message\" in event:\n                        raise BuildError(event[\"message\"])\n            except docker.errors.APIError as e:\n                raise BuildError(e.explanation) from e\n\n        finally:\n            if auto_build:\n                os.unlink(dockerfile)\n\n        if not isinstance(image_id, str):\n            raise BuildError(\"Docker did not return an image ID for built image.\")\n\n        if not tag:\n            tag = slugify(pendulum.now(\"utc\").isoformat())\n\n        image: Image = client.images.get(image_id)\n        image.tag(repository=image_name, tag=tag)\n\n        additional_tags = additional_tags or []\n        for tag_ in additional_tags:\n            image.tag(repository=image_name, tag=tag_)\n\n    return {\n        \"image_name\": image_name,\n        \"tag\": tag,\n        \"image\": f\"{image_name}:{tag}\",\n        \"image_id\": image_id,\n        \"additional_tags\": additional_tags,\n    }\n</code></pre>"},{"location":"integrations/prefect-docker/deployments/steps/#prefect_docker.deployments.steps.push_docker_image","title":"<code>push_docker_image</code>","text":"<p>Push a Docker image to a remote registry.</p> <p>Parameters:</p> Name Type Description Default <code>image_name</code> <code>str</code> <p>The name of the Docker image to push, including the registry and repository.</p> required <code>tag</code> <code>Optional[str]</code> <p>The tag of the Docker image to push.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the username, password, and URL for the registry to push the image to.</p> <code>None</code> <code>additional_tags</code> <code>Optional[List[str]]</code> <p>Additional tags on the image, in addition to <code>tag</code>, to apply to the built image.</p> <code>None</code> <p>Returns:</p> Type Description <code>PushDockerImageResult</code> <p>A dictionary containing the image name and tag of the pushed image.</p> <p>Examples:</p> <p>Build and push a Docker image to a private repository: <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n        credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n</code></pre></p> <p>Build and push a Docker image to a private repository with multiple tags <pre><code>build:\n    - prefect_docker.deployments.steps.build_docker_image:\n        id: build-image\n        requires: prefect-docker\n        image_name: repo-name/image-name\n        tag: dev\n        dockerfile: auto\n        additional_tags: [\n            v0.1.0,\n            dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n        ]\n\npush:\n    - prefect_docker.deployments.steps.push_docker_image:\n        requires: prefect-docker\n        image_name: \"{{ build-image.image_name }}\"\n        tag: \"{{ build-image.tag }}\"\n        credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n        additional_tags: \"{{ build-image.additional_tags }}\"\n</code></pre></p> Source code in <code>prefect_docker/deployments/steps.py</code> <pre><code>@cacheable\ndef push_docker_image(\n    image_name: str,\n    tag: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n    additional_tags: Optional[List[str]] = None,\n    ignore_cache: bool = False,\n) -&gt; PushDockerImageResult:\n    \"\"\"\n    Push a Docker image to a remote registry.\n\n    Args:\n        image_name: The name of the Docker image to push, including the registry and\n            repository.\n        tag: The tag of the Docker image to push.\n        credentials: A dictionary containing the username, password, and URL for the\n            registry to push the image to.\n        additional_tags: Additional tags on the image, in addition to `tag`, to apply to the built image.\n\n    Returns:\n        A dictionary containing the image name and tag of the\n            pushed image.\n\n    Examples:\n        Build and push a Docker image to a private repository:\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                id: build-image\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n\n        push:\n            - prefect_docker.deployments.steps.push_docker_image:\n                requires: prefect-docker\n                image_name: \"{{ build-image.image_name }}\"\n                tag: \"{{ build-image.tag }}\"\n                credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n        ```\n\n        Build and push a Docker image to a private repository with multiple tags\n        ```yaml\n        build:\n            - prefect_docker.deployments.steps.build_docker_image:\n                id: build-image\n                requires: prefect-docker\n                image_name: repo-name/image-name\n                tag: dev\n                dockerfile: auto\n                additional_tags: [\n                    v0.1.0,\n                    dac9ccccedaa55a17916eef14f95cc7bdd3c8199\n                ]\n\n        push:\n            - prefect_docker.deployments.steps.push_docker_image:\n                requires: prefect-docker\n                image_name: \"{{ build-image.image_name }}\"\n                tag: \"{{ build-image.tag }}\"\n                credentials: \"{{ prefect.blocks.docker-registry-credentials.dev-registry }}\"\n                additional_tags: \"{{ build-image.additional_tags }}\"\n        ```\n    \"\"\"  # noqa\n    with docker_client() as client:\n        if credentials is not None:\n            client.login(\n                username=credentials.get(\"username\"),\n                password=credentials.get(\"password\"),\n                registry=credentials.get(\"registry_url\"),\n                reauth=credentials.get(\"reauth\", True),\n            )\n        events = list(\n            client.api.push(repository=image_name, tag=tag, stream=True, decode=True)\n        )\n        additional_tags = additional_tags or []\n        for i, tag_ in enumerate(additional_tags):\n            event = list(\n                client.api.push(\n                    repository=image_name, tag=tag_, stream=True, decode=True\n                )\n            )\n            events = events + event\n\n        for event in events:\n            if \"status\" in event:\n                sys.stdout.write(event[\"status\"])\n                if \"progress\" in event:\n                    sys.stdout.write(\" \" + event[\"progress\"])\n                sys.stdout.write(\"\\n\")\n                sys.stdout.flush()\n            elif \"error\" in event:\n                raise OSError(event[\"error\"])\n\n    return {\n        \"image_name\": image_name,\n        \"tag\": tag,\n        \"image\": f\"{image_name}:{tag}\",\n        \"additional_tags\": additional_tags,\n    }\n</code></pre>"},{"location":"integrations/prefect-email/","title":"prefect-email","text":"<p>The <code>prefect-email</code> library helps you send emails from your Prefect flows.</p>"},{"location":"integrations/prefect-email/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-email/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Many email services, such as Gmail, require an App Password to successfully send emails.     If you encounter an error similar to <code>smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted...</code>, it's likely you are not using an App Password.</li> </ul>"},{"location":"integrations/prefect-email/#install-prefect-email","title":"Install prefect-email","text":"<pre><code>pip install -U prefect-email\n</code></pre>"},{"location":"integrations/prefect-email/#register-newly-installed-blocks-types","title":"Register newly installed blocks types","text":"<p>Register the block types in the prefect-email module to make them available for use.</p> <pre><code>prefect block register -m prefect_email\n</code></pre>"},{"location":"integrations/prefect-email/#save-credentials-to-an-emailservercredentials-block","title":"Save credentials to an EmailServerCredentials block","text":"<p>Save your email credentials to a block. Replace the placeholders with your email address and password.</p> <pre><code>from prefect_email import EmailServerCredentials\n\ncredentials = EmailServerCredentials(\n    username=\"EMAIL-ADDRESS-PLACEHOLDER\",\n    password=\"PASSWORD-PLACEHOLDER\",  # must be an app password\n)\ncredentials.save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>In the examples below you load a credentials block to authenticate with the email server.</p>"},{"location":"integrations/prefect-email/#send-emails","title":"Send emails","text":"<p>The code below shows how to send an email using the pre-built <code>email_send_message</code> task.</p> <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials, email_send_message\n\n@flow\ndef example_email_send_message_flow(email_addresses):\n    email_server_credentials = EmailServerCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    for email_address in email_addresses:\n        subject = email_send_message.with_options(name=f\"email {email_address}\").submit(\n            email_server_credentials=email_server_credentials,\n            subject=\"Example Flow Notification using Gmail\",\n            msg=\"This proves email_send_message works!\",\n            email_to=email_address,\n        )\n\nif __name__ == \"__main__\":\n    example_email_send_message_flow([\"EMAIL-ADDRESS-PLACEHOLDER\"])\n</code></pre>"},{"location":"integrations/prefect-email/#capture-exceptions-and-send-an-email","title":"Capture exceptions and send an email","text":"<p>This example demonstrates how to send an email notification with the details of the exception when a flow run fails.</p> <p><code>prefect-email</code> can be wrapped in an <code>except</code> statement to do just that!</p> <pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_email import EmailServerCredentials, email_send_message\n\ndef notify_exc_by_email(exc):\n    context = get_run_context()\n    flow_run_name = context.flow_run.name\n    email_server_credentials = EmailServerCredentials.load(\"email-server-credentials\")\n    email_send_message(\n        email_server_credentials=email_server_credentials,\n        subject=f\"Flow run {flow_run_name!r} failed\",\n        msg=f\"Flow run {flow_run_name!r} failed due to {exc}.\",\n        email_to=email_server_credentials.username,\n    )\n\n@flow\ndef example_flow():\n    try:\n        1 / 0\n    except Exception as exc:\n        notify_exc_by_email(exc)\n        raise\n\nif __name__ == \"__main__\":\n    example_flow()\n</code></pre>"},{"location":"integrations/prefect-email/#resources","title":"Resources","text":"<p>Refer to the prefect-email API documentation linked in the sidebar to explore all the capabilities of the prefect-email library.</p>"},{"location":"integrations/prefect-email/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials","title":"<code>prefect_email.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with email services</p>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials","title":"<code>EmailServerCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage generic email server authentication. It is recommended you use a Google App Password if you use Gmail.</p> <p>Attributes:</p> Name Type Description <code>username</code> <code>Optional[str]</code> <p>The username to use for authentication to the server. Unnecessary if SMTP login is not required.</p> <code>password</code> <code>SecretStr</code> <p>The password to use for authentication to the server. Unnecessary if SMTP login is not required.</p> <code>smtp_server</code> <code>Union[SMTPServer, str]</code> <p>Either the hostname of the SMTP server, or one of the keys from the built-in SMTPServer Enum members, like \"gmail\".</p> <code>smtp_type</code> <code>Union[SMTPType, str]</code> <p>Either \"SSL\", \"STARTTLS\", or \"INSECURE\".</p> <code>smtp_port</code> <code>Optional[int]</code> <p>If provided, overrides the smtp_type's default port number.</p> Example <p>Load stored email server credentials: <pre><code>from prefect_email import EmailServerCredentials\nemail_credentials_block = EmailServerCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class EmailServerCredentials(Block):\n    \"\"\"\n    Block used to manage generic email server authentication.\n    It is recommended you use a\n    [Google App Password](https://support.google.com/accounts/answer/185833)\n    if you use Gmail.\n\n    Attributes:\n        username: The username to use for authentication to the server.\n            Unnecessary if SMTP login is not required.\n        password: The password to use for authentication to the server.\n            Unnecessary if SMTP login is not required.\n        smtp_server: Either the hostname of the SMTP server, or one of the\n            keys from the built-in SMTPServer Enum members, like \"gmail\".\n        smtp_type: Either \"SSL\", \"STARTTLS\", or \"INSECURE\".\n        smtp_port: If provided, overrides the smtp_type's default port number.\n\n    Example:\n        Load stored email server credentials:\n        ```python\n        from prefect_email import EmailServerCredentials\n        email_credentials_block = EmailServerCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Email Server Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/82bc6ed16ca42a2252a5512c72233a253b8a58eb-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials\"  # noqa\n\n    username: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The username to use for authentication to the server. \"\n            \"Unnecessary if SMTP login is not required.\"\n        ),\n    )\n    password: SecretStr = Field(\n        default_factory=partial(SecretStr, \"\"),\n        description=(\n            \"The password to use for authentication to the server. \"\n            \"Unnecessary if SMTP login is not required.\"\n        ),\n    )\n    smtp_server: Union[SMTPServer, str] = Field(\n        default=SMTPServer.GMAIL,\n        description=(\n            \"Either the hostname of the SMTP server, or one of the \"\n            \"keys from the built-in SMTPServer Enum members, like 'gmail'.\"\n        ),\n        title=\"SMTP Server\",\n    )\n    smtp_type: Union[SMTPType, str] = Field(\n        default=SMTPType.SSL,\n        description=(\"Either 'SSL', 'STARTTLS', or 'INSECURE'.\"),\n        title=\"SMTP Type\",\n    )\n    smtp_port: Optional[int] = Field(\n        default=None,\n        description=(\"If provided, overrides the smtp_type's default port number.\"),\n        title=\"SMTP Port\",\n    )\n\n    @validator(\"smtp_server\", pre=True)\n    def _cast_smtp_server(cls, value):\n        \"\"\"\n        Cast the smtp_server to an SMTPServer Enum member, if valid.\n        \"\"\"\n        return _cast_to_enum(value, SMTPServer)\n\n    @validator(\"smtp_type\", pre=True)\n    def _cast_smtp_type(cls, value):\n        \"\"\"\n        Cast the smtp_type to an SMTPType Enum member, if valid.\n        \"\"\"\n        if isinstance(value, int):\n            return SMTPType(value)\n        return _cast_to_enum(value, SMTPType, restrict=True)\n\n    def get_server(self) -&gt; SMTP:\n        \"\"\"\n        Gets an authenticated SMTP server.\n\n        Returns:\n            SMTP: An authenticated SMTP server.\n\n        Example:\n            Gets a GMail SMTP server through defaults.\n            ```python\n            from prefect import flow\n            from prefect_email import EmailServerCredentials\n\n            @flow\n            def example_get_server_flow():\n                email_server_credentials = EmailServerCredentials(\n                    username=\"username@gmail.com\",\n                    password=\"password\",\n                )\n                server = email_server_credentials.get_server()\n                return server\n\n            example_get_server_flow()\n            ```\n        \"\"\"\n        smtp_server = self.smtp_server\n        if isinstance(smtp_server, SMTPServer):\n            smtp_server = smtp_server.value\n\n        smtp_type = self.smtp_type\n        smtp_port = self.smtp_port\n        if smtp_port is None:\n            smtp_port = smtp_type.value\n\n        if smtp_type == SMTPType.INSECURE:\n            server = SMTP(smtp_server, smtp_port)\n        else:\n            context = ssl.create_default_context()\n            if smtp_type == SMTPType.SSL:\n                server = SMTP_SSL(smtp_server, smtp_port, context=context)\n            elif smtp_type == SMTPType.STARTTLS:\n                server = SMTP(smtp_server, smtp_port)\n                server.starttls(context=context)\n            if self.username is not None:\n                server.login(self.username, self.password.get_secret_value())\n\n        return server\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.EmailServerCredentials.get_server","title":"<code>get_server</code>","text":"<p>Gets an authenticated SMTP server.</p> <p>Returns:</p> Name Type Description <code>SMTP</code> <code>SMTP</code> <p>An authenticated SMTP server.</p> Example <p>Gets a GMail SMTP server through defaults. <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials\n\n@flow\ndef example_get_server_flow():\n    email_server_credentials = EmailServerCredentials(\n        username=\"username@gmail.com\",\n        password=\"password\",\n    )\n    server = email_server_credentials.get_server()\n    return server\n\nexample_get_server_flow()\n</code></pre></p> Source code in <code>prefect_email/credentials.py</code> <pre><code>def get_server(self) -&gt; SMTP:\n    \"\"\"\n    Gets an authenticated SMTP server.\n\n    Returns:\n        SMTP: An authenticated SMTP server.\n\n    Example:\n        Gets a GMail SMTP server through defaults.\n        ```python\n        from prefect import flow\n        from prefect_email import EmailServerCredentials\n\n        @flow\n        def example_get_server_flow():\n            email_server_credentials = EmailServerCredentials(\n                username=\"username@gmail.com\",\n                password=\"password\",\n            )\n            server = email_server_credentials.get_server()\n            return server\n\n        example_get_server_flow()\n        ```\n    \"\"\"\n    smtp_server = self.smtp_server\n    if isinstance(smtp_server, SMTPServer):\n        smtp_server = smtp_server.value\n\n    smtp_type = self.smtp_type\n    smtp_port = self.smtp_port\n    if smtp_port is None:\n        smtp_port = smtp_type.value\n\n    if smtp_type == SMTPType.INSECURE:\n        server = SMTP(smtp_server, smtp_port)\n    else:\n        context = ssl.create_default_context()\n        if smtp_type == SMTPType.SSL:\n            server = SMTP_SSL(smtp_server, smtp_port, context=context)\n        elif smtp_type == SMTPType.STARTTLS:\n            server = SMTP(smtp_server, smtp_port)\n            server.starttls(context=context)\n        if self.username is not None:\n            server.login(self.username, self.password.get_secret_value())\n\n    return server\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.SMTPServer","title":"<code>SMTPServer</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Server used to send email.</p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class SMTPServer(Enum):\n    \"\"\"\n    Server used to send email.\n    \"\"\"\n\n    AOL = \"smtp.aol.com\"\n    ATT = \"smtp.mail.att.net\"\n    COMCAST = \"smtp.comcast.net\"\n    ICLOUD = \"smtp.mail.me.com\"\n    GMAIL = \"smtp.gmail.com\"\n    OUTLOOK = \"smtp-mail.outlook.com\"\n    YAHOO = \"smtp.mail.yahoo.com\"\n</code></pre>"},{"location":"integrations/prefect-email/credentials/#prefect_email.credentials.SMTPType","title":"<code>SMTPType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Protocols used to secure email transmissions.</p> Source code in <code>prefect_email/credentials.py</code> <pre><code>class SMTPType(Enum):\n    \"\"\"\n    Protocols used to secure email transmissions.\n    \"\"\"\n\n    SSL = 465\n    STARTTLS = 587\n    INSECURE = 25\n</code></pre>"},{"location":"integrations/prefect-email/message/","title":"Message","text":""},{"location":"integrations/prefect-email/message/#prefect_email.message","title":"<code>prefect_email.message</code>","text":"<p>Tasks for interacting with email message services</p>"},{"location":"integrations/prefect-email/message/#prefect_email.message.email_send_message","title":"<code>email_send_message</code>  <code>async</code>","text":"<p>Sends an email message from an authenticated email service over SMTP. Sending messages containing HTML code is supported - the default MIME type is set to the text/html.</p> <p>Parameters:</p> Name Type Description Default <code>subject</code> <code>str</code> <p>The subject line of the email.</p> required <code>msg</code> <code>str</code> <p>The contents of the email, added as html; can be used in combination with msg_plain.</p> required <code>msg_plain</code> <code>Optional[str]</code> <p>The contents of the email as plain text, can be used in combination with msg.</p> <code>None</code> <code>email_to</code> <code>Optional[Union[str, List[str]]]</code> <p>The email addresses to send the message to, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>email_to_cc</code> <code>Optional[Union[str, List[str]]]</code> <p>Additional email addresses to send the message to as cc, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>email_to_bcc</code> <code>Optional[Union[str, List[str]]]</code> <p>Additional email addresses to send the message to as bcc, separated by commas. If a list is provided, will join the items, separated by commas.</p> <code>None</code> <code>attachments</code> <code>Optional[List[str]]</code> <p>Names of files that should be sent as attachment.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>MimeText</code> <p>The MIME Multipart message of the email.</p> Example <p>Sends a notification email to someone@gmail.com. <pre><code>from prefect import flow\nfrom prefect_email import EmailServerCredentials, email_send_message\n\n@flow\ndef example_email_send_message_flow():\n    email_server_credentials = EmailServerCredentials(\n        username=\"username@email.com\",\n        password=\"password\",\n    )\n    subject = email_send_message(\n        email_server_credentials=email_server_credentials,\n        subject=\"Example Flow Notification\",\n        msg=\"This proves email_send_message works!\",\n        email_to=\"someone@email.com\",\n    )\n    return subject\n\nexample_email_send_message_flow()\n</code></pre></p> Source code in <code>prefect_email/message.py</code> <pre><code>@task\nasync def email_send_message(\n    subject: str,\n    msg: str,\n    email_server_credentials: \"EmailServerCredentials\",\n    msg_plain: Optional[str] = None,\n    email_from: Optional[str] = None,\n    email_to: Optional[Union[str, List[str]]] = None,\n    email_to_cc: Optional[Union[str, List[str]]] = None,\n    email_to_bcc: Optional[Union[str, List[str]]] = None,\n    attachments: Optional[List[str]] = None,\n):\n    \"\"\"\n    Sends an email message from an authenticated email service over SMTP.\n    Sending messages containing HTML code is supported - the default MIME\n    type is set to the text/html.\n\n    Args:\n        subject: The subject line of the email.\n        msg: The contents of the email, added as html; can be used in\n            combination with msg_plain.\n        msg_plain: The contents of the email as plain text,\n            can be used in combination with msg.\n        email_to: The email addresses to send the message to, separated by commas.\n            If a list is provided, will join the items, separated by commas.\n        email_to_cc: Additional email addresses to send the message to as cc,\n            separated by commas. If a list is provided, will join the items,\n            separated by commas.\n        email_to_bcc: Additional email addresses to send the message to as bcc,\n            separated by commas. If a list is provided, will join the items,\n            separated by commas.\n        attachments: Names of files that should be sent as attachment.\n\n    Returns:\n        MimeText: The MIME Multipart message of the email.\n\n    Example:\n        Sends a notification email to someone@gmail.com.\n        ```python\n        from prefect import flow\n        from prefect_email import EmailServerCredentials, email_send_message\n\n        @flow\n        def example_email_send_message_flow():\n            email_server_credentials = EmailServerCredentials(\n                username=\"username@email.com\",\n                password=\"password\",\n            )\n            subject = email_send_message(\n                email_server_credentials=email_server_credentials,\n                subject=\"Example Flow Notification\",\n                msg=\"This proves email_send_message works!\",\n                email_to=\"someone@email.com\",\n            )\n            return subject\n\n        example_email_send_message_flow()\n        ```\n    \"\"\"\n    message = MIMEMultipart()\n    message[\"Subject\"] = subject\n    message[\"From\"] = email_from or email_server_credentials.username\n\n    email_to_dict = {\"To\": email_to, \"Cc\": email_to_cc, \"Bcc\": email_to_bcc}\n    if all(val is None for val in email_to_dict.values()):\n        raise ValueError(\n            \"One of email_to, email_to_cc, or email_to_bcc must be specified\"\n        )\n\n    for key, val in email_to_dict.items():\n        if isinstance(val, list):\n            val = \", \".join(val)\n        message[key] = val\n\n    # First add the message in plain text, then the HTML version;\n    # email clients try to render the last part first\n    if msg_plain:\n        message.attach(MIMEText(msg_plain, \"plain\"))\n    if msg:\n        message.attach(MIMEText(msg, \"html\"))\n\n    for filepath in attachments or []:\n        with open(filepath, \"rb\") as attachment:\n            part = MIMEBase(\"application\", \"octet-stream\")\n            part.set_payload(attachment.read())\n\n        encoders.encode_base64(part)\n        filename = os.path.basename(filepath)\n        part.add_header(\n            \"Content-Disposition\",\n            f\"attachment; filename= {filename}\",\n        )\n        message.attach(part)\n\n    with email_server_credentials.get_server() as server:\n        partial_send_message = partial(server.send_message, message)\n        await to_thread.run_sync(partial_send_message)\n\n    return message\n</code></pre>"},{"location":"integrations/prefect-gcp/","title":"<code>prefect-gcp</code>","text":"<p><code>prefect-gcp</code> helps you leverage the capabilities of Google Cloud Platform (GCP) in your workflows. For example, you can run flow on Vertex AI or Cloud Run, read and write data to BigQuery and Cloud Storage, retrieve secrets with Secret Manager.</p>"},{"location":"integrations/prefect-gcp/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-gcp/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>An GCP account and the necessary permissions to access desired services.</li> </ul>"},{"location":"integrations/prefect-gcp/#install-prefect-gcp","title":"Install prefect-gcp","text":"<pre><code>pip install -U prefect-gcp\n</code></pre> <p>If using BigQuery, Cloud Storage, Secret Manager, or Vertex AI, see additional installation options.</p> <p>To install with all additional functionality, use the following command:</p> <pre><code>pip install -U \"prefect-gcp[all_extras]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the module to make them available for use.</p> <pre><code>prefect block register -m prefect_gcp\n</code></pre>"},{"location":"integrations/prefect-gcp/#authenticate-using-a-gcp-credentials-block","title":"Authenticate using a GCP Credentials block","text":"<p>Authenticate with a service account to use <code>prefect-gcp</code> services.</p> <ol> <li>Refer to the GCP service account documentation to create and download a service account key file.</li> <li>Copy the JSON contents.</li> <li>Use the Python code below, replace the placeholders with your information.</li> </ol> <pre><code>from prefect_gcp import GcpCredentials\n\n# replace this PLACEHOLDER dict with your own service account info\nservice_account_info = {\n  \"type\": \"service_account\",\n  \"project_id\": \"PROJECT_ID\",\n  \"private_key_id\": \"KEY_ID\",\n  \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nPRIVATE_KEY\\n-----END PRIVATE KEY-----\\n\",\n  \"client_email\": \"SERVICE_ACCOUNT_EMAIL\",\n  \"client_id\": \"CLIENT_ID\",\n  \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n  \"token_uri\": \"https://accounts.google.com/o/oauth2/token\",\n  \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n  \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL\"\n}\n\nGcpCredentials(\n    service_account_info=service_account_info\n).save(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p><code>service_account_info</code> vs <code>service_account_file</code></p> <p>The advantage of using <code>service_account_info</code>, instead of <code>service_account_file</code>, is that it is accessible across containers.</p> <p>If <code>service_account_file</code> is used, the provided file path must be available in the container executing the flow.</p> <p>Alternatively, GCP can authenticate without storing credentials in a block. See the Third-pary Screts Guide for an analogous example that uses AWS Secrets Manager and Snowflake.</p>"},{"location":"integrations/prefect-gcp/#run-flows-on-google-cloud-run-or-vertex-ai","title":"Run flows on Google Cloud Run or Vertex AI","text":"<p>Run flows on Google Cloud Run or Vertex AI to dynamically scale your infrastructure.</p> <p>See the Google Cloud Run Worker Guide for a walkthrough of using Google Cloud Run to run workflows with a hybrid work pool.</p> <p>If you're using Prefect Cloud, Google Cloud Run push work pools provide all the benefits of Google Cloud Run along with a quick setup and no worker needed.</p>"},{"location":"integrations/prefect-gcp/#use-prefect-with-google-bigquery","title":"Use Prefect with Google BigQuery","text":"<p>Read data from and write to Google BigQuery within your Prefect flows.</p> <p>Be sure to install <code>prefect-gcp</code> with the BigQuery extra.</p> <p>This code creates a new dataset in BigQuery, define a table, insert rows, and fetch data from the table:</p> <pre><code>from prefect import flow\nfrom prefect_gcp.bigquery import GcpCredentials, BigQueryWarehouse\n\n@flow\ndef bigquery_flow():\n    all_rows = []\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n\n    client = gcp_credentials.get_bigquery_client()\n    client.create_dataset(\"test_example\", exists_ok=True)\n\n    with BigQueryWarehouse(gcp_credentials=gcp_credentials) as warehouse:\n        warehouse.execute(\n            \"CREATE TABLE IF NOT EXISTS test_example.customers (name STRING, address STRING);\"\n        )\n        warehouse.execute_many(\n            \"INSERT INTO test_example.customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = warehouse.fetch_many(\"SELECT * FROM test_example.customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.extend(new_rows)\n    return all_rows\n\n\nif __name__ == \"__main__\":\n    bigquery_flow()\n</code></pre>"},{"location":"integrations/prefect-gcp/#use-prefect-with-google-cloud-storage","title":"Use Prefect with Google Cloud Storage","text":"<p>Interact with Google Cloud Storage.</p> <p>Be sure to install <code>prefect-gcp</code> with the Cloud Storage extra.</p> <p>The code below uses <code>prefect_gcp</code> to upload a file to a Google Cloud Storage bucket and download the same file under a different file name.</p> <pre><code>from pathlib import Path\nfrom prefect import flow\nfrom prefect_gcp import GcpCredentials, GcsBucket\n\n\n@flow\ndef cloud_storage_flow():\n    # create a dummy file to upload\n    file_path = Path(\"test-example.txt\")\n    file_path.write_text(\"Hello, Prefect!\")\n\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    gcs_bucket = GcsBucket(\n        bucket=\"BUCKET-NAME-PLACEHOLDER\",\n        gcp_credentials=gcp_credentials\n    )\n\n    gcs_bucket_path = gcs_bucket.upload_from_path(file_path)\n    downloaded_file_path = gcs_bucket.download_object_to_path(\n        gcs_bucket_path, \"downloaded-test-example.txt\"\n    )\n    return downloaded_file_path.read_text()\n\n\nif __name__ == \"__main__\":\n    cloud_storage_flow()\n</code></pre> <p>Upload and download directories</p> <p><code>GcsBucket</code> supports uploading and downloading entire directories. To view examples, check out the Examples Catalog!</p>"},{"location":"integrations/prefect-gcp/#save-secrets-with-google-secret-manager","title":"Save secrets with Google Secret Manager","text":"<p>Read and write secrets with Google Secret Manager.</p> <p>Be sure to install <code>prefect-gcp</code> with the Secret Manager extra.</p> <p>The code below writes a secret to the Secret Manager, reads the secret data, and deletes the secret.</p> <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials, GcpSecret\n\n\n@flow\ndef secret_manager_flow():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    gcp_secret = GcpSecret(secret_name=\"test-example\", gcp_credentials=gcp_credentials)\n    gcp_secret.write_secret(secret_data=b\"Hello, Prefect!\")\n    secret_data = gcp_secret.read_secret()\n    gcp_secret.delete_secret()\n    return secret_data\n\n\nif __name__ == \"__main__\":\n    secret_manager_flow()\n</code></pre>"},{"location":"integrations/prefect-gcp/#access-google-credentials-or-clients-from-gcpcredentials","title":"Access Google credentials or clients from GcpCredentials","text":"<p>You can instantiate a Google Cloud client, such as <code>bigquery.Client</code>.</p> <p>Note that a <code>GcpCredentials</code> object is NOT a valid input to the underlying BigQuery client - use the <code>get_credentials_from_service_account</code> method to access and pass a <code>google.auth.Credentials</code> object.</p> <pre><code>import google.cloud.bigquery\nfrom prefect import flow\nfrom prefect_gcp import GcpCredentials\n\n@flow\ndef create_bigquery_client():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    google_auth_credentials = gcp_credentials.get_credentials_from_service_account()\n    bigquery_client = bigquery.Client(credentials=google_auth_credentials)\n</code></pre> <p>To access the underlying client, use the <code>get_client</code> method from <code>GcpCredentials</code>.</p> <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\n\n@flow\ndef create_bigquery_client():\n    gcp_credentials = GcpCredentials.load(\"BLOCK-NAME-PLACEHOLDER\")\n    bigquery_client = gcp_credentials.get_client(\"bigquery\")\n</code></pre>"},{"location":"integrations/prefect-gcp/#resources","title":"Resources","text":"<p>For assistance using GCP, consult the Google Cloud documentation.</p> <p>Refer to the prefect-gcp API documentation linked in the sidebar to explore all the capabilities of the prefect-gcp library.</p>"},{"location":"integrations/prefect-gcp/#additional-installation-options","title":"Additional installation options","text":"<p>Additional installation options for GCP services are shown below.</p>"},{"location":"integrations/prefect-gcp/#to-use-cloud-storage","title":"To use Cloud Storage","text":"<pre><code>pip install \"prefect-gcp[cloud_storage]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-bigquery","title":"To use BigQuery","text":"<pre><code>pip install \"prefect-gcp[bigquery]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-secret-manager","title":"To use Secret Manager","text":"<pre><code>pip install \"prefect-gcp[secret_manager]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/#to-use-vertex-ai","title":"To use Vertex AI","text":"<pre><code>pip install \"prefect-gcp[aiplatform]\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/","title":"AI Platform","text":""},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform","title":"<code>prefect_gcp.aiplatform</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the Vertex AI worker, which offers enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with Google AI Platform.</p> <p>Examples:</p> <pre><code>Run a job using Vertex AI Custom Training:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.run()\n```\n\nRun a job that runs the command `echo hello world` using Google Cloud Run Jobs:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    command=[\"echo\", \"hello world\"],\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.run()\n```\n\nPreview job specs:\n```python\nfrom prefect_gcp.credentials import GcpCredentials\nfrom prefect_gcp.aiplatform import VertexAICustomTrainingJob\n\ngcp_credentials = GcpCredentials.load(\"BLOCK_NAME\")\njob = VertexAICustomTrainingJob(\n    command=[\"echo\", \"hello world\"],\n    region=\"us-east1\",\n    image=\"us-docker.pkg.dev/cloudrun/container/job:latest\",\n    gcp_credentials=gcp_credentials,\n)\njob.preview()\n```\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob","title":"<code>VertexAICustomTrainingJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p>Infrastructure block used to run Vertex AI custom training jobs.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the Vertex AI worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass VertexAICustomTrainingJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    Infrastructure block used to run Vertex AI custom training jobs.\n    \"\"\"\n\n    _block_type_name = \"Vertex AI Custom Training Job\"\n    _block_type_slug = \"vertex-ai-custom-training-job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob\"  # noqa: E501\n\n    type: Literal[\"vertex-ai-custom-training-job\"] = Field(\n        \"vertex-ai-custom-training-job\", description=\"The slug for this task type.\"\n    )\n\n    gcp_credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=(\n            \"GCP credentials to use when running the configured Vertex AI custom \"\n            \"training job. If not provided, credentials will be inferred from the \"\n            \"environment. See `GcpCredentials` for details.\"\n        ),\n    )\n    region: str = Field(\n        default=...,\n        description=\"The region where the Vertex AI custom training job resides.\",\n    )\n    image: str = Field(\n        default=...,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Vertex AI custom training job. This value must \"\n            \"refer to an image within either Google Container Registry \"\n            \"or Google Artifact Registry, like `gcr.io/&lt;project_name&gt;/&lt;repo&gt;/`.\"\n        ),\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to be passed to your Cloud Run Job.\",\n    )\n    machine_type: str = Field(\n        default=\"n1-standard-4\",\n        description=\"The machine type to use for the run, which controls the available \"\n        \"CPU and memory.\",\n    )\n    accelerator_type: Optional[str] = Field(\n        default=None, description=\"The type of accelerator to attach to the machine.\"\n    )\n    accelerator_count: Optional[int] = Field(\n        default=None, description=\"The number of accelerators to attach to the machine.\"\n    )\n    boot_disk_type: str = Field(\n        default=\"pd-ssd\",\n        title=\"Boot Disk Type\",\n        description=\"The type of boot disk to attach to the machine.\",\n    )\n    boot_disk_size_gb: int = Field(\n        default=100,\n        title=\"Boot Disk Size\",\n        description=\"The size of the boot disk to attach to the machine, in gigabytes.\",\n    )\n    maximum_run_time: datetime.timedelta = Field(\n        default=datetime.timedelta(days=7), description=\"The maximum job running time.\"\n    )\n    network: Optional[str] = Field(\n        default=None,\n        description=\"The full name of the Compute Engine network\"\n        \"to which the Job should be peered. Private services access must \"\n        \"already be configured for the network. If left unspecified, the job \"\n        \"is not peered with any network.\",\n    )\n    reserved_ip_ranges: Optional[List[str]] = Field(\n        default=None,\n        description=\"A list of names for the reserved ip ranges under the VPC \"\n        \"network that can be used for this job. If set, we will deploy the job \"\n        \"within the provided ip ranges. Otherwise, the job will be deployed to \"\n        \"any ip ranges under the provided VPC network.\",\n    )\n    service_account: Optional[str] = Field(\n        default=None,\n        description=(\n            \"Specifies the service account to use \"\n            \"as the run-as account in Vertex AI. The agent submitting jobs must have \"\n            \"act-as permission on this run-as account. If unspecified, the AI \"\n            \"Platform Custom Code Service Agent for the CustomJob's project is \"\n            \"used. Takes precedence over the service account found in gcp_credentials, \"\n            \"and required if a service account cannot be detected in gcp_credentials.\"\n        ),\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n\n    @property\n    def job_name(self):\n        \"\"\"\n        The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:\n        https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name\n        \"\"\"  # noqa\n        try:\n            base_name = self.name or self.image.split(\"/\")[2]\n            return f\"{base_name}-{uuid4().hex}\"\n        except IndexError:\n            raise ValueError(\n                \"The provided image must be from either Google Container Registry \"\n                \"or Google Artifact Registry\"\n            )\n\n    def _get_compatible_labels(self) -&gt; Dict[str, str]:\n        \"\"\"\n        Ensures labels are compatible with GCP label requirements.\n        https://cloud.google.com/resource-manager/docs/creating-managing-labels\n\n        Ex: the Prefect provided key of prefect.io/flow-name -&gt; prefect-io_flow-name\n        \"\"\"\n        compatible_labels = {}\n        for key, val in self.labels.items():\n            new_key = slugify(\n                key,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n            compatible_labels[new_key] = slugify(\n                val,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n        return compatible_labels\n\n    def preview(self) -&gt; str:\n        \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n        job_spec = self._build_job_spec()\n        custom_job = CustomJob(\n            display_name=self.job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(),\n        )\n        return str(custom_job)  # outputs a json string\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return \"vertex-ai\"\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a `Vertex AI` work pool with the same\n        configuration as this block.\n        Returns:\n            - dict: a base job template for a `Vertex AI` work pool\n        \"\"\"\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Cloud Run worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n            ]:\n                continue\n            elif key == \"gcp_credentials\":\n                if not self.gcp_credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(\n                            self.gcp_credentials._block_document_id\n                        )\n                    }\n                }\n            elif key == \"maximum_run_time\":\n                base_job_template[\"variables\"][\"properties\"][\"maximum_run_time_hours\"][\n                    \"default\"\n                ] = round(value.total_seconds() / 3600)\n            elif key == \"service_account\":\n                base_job_template[\"variables\"][\"properties\"][\"service_account_name\"][\n                    \"default\"\n                ] = value\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by `Vertex AI` work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n\n    def _build_job_spec(self) -&gt; \"CustomJobSpec\":\n        \"\"\"\n        Builds a job spec by gathering details.\n        \"\"\"\n        # gather worker pool spec\n        env_list = [\n            {\"name\": name, \"value\": value}\n            for name, value in {\n                **self._base_environment(),\n                **self.env,\n            }.items()\n        ]\n        container_spec = ContainerSpec(\n            image_uri=self.image, command=self.command, args=[], env=env_list\n        )\n        machine_spec = MachineSpec(\n            machine_type=self.machine_type,\n            accelerator_type=self.accelerator_type,\n            accelerator_count=self.accelerator_count,\n        )\n        worker_pool_spec = WorkerPoolSpec(\n            container_spec=container_spec,\n            machine_spec=machine_spec,\n            replica_count=1,\n            disk_spec=DiskSpec(\n                boot_disk_type=self.boot_disk_type,\n                boot_disk_size_gb=self.boot_disk_size_gb,\n            ),\n        )\n        # look for service account\n        service_account = (\n            self.service_account or self.gcp_credentials._service_account_email\n        )\n        if service_account is None:\n            raise ValueError(\n                \"A service account is required for the Vertex job. \"\n                \"A service account could not be detected in the attached credentials; \"\n                \"please set a service account explicitly, e.g. \"\n                '`VertexAICustomTrainingJob(service_acount=\"...\")`'\n            )\n\n        # build custom job specs\n        timeout = Duration().FromTimedelta(td=self.maximum_run_time)\n        scheduling = Scheduling(timeout=timeout)\n        job_spec = CustomJobSpec(\n            worker_pool_specs=[worker_pool_spec],\n            service_account=service_account,\n            scheduling=scheduling,\n            network=self.network,\n            reserved_ip_ranges=self.reserved_ip_ranges,\n        )\n        return job_spec\n\n    async def _create_and_begin_job(\n        self,\n        job_spec: \"CustomJobSpec\",\n        job_service_async_client: \"JobServiceAsyncClient\",\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Builds a custom job and begins running it.\n        \"\"\"\n        # create custom job\n        custom_job = CustomJob(\n            display_name=self.job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(),\n        )\n\n        # run job\n        self.logger.info(\n            f\"{self._log_prefix}: Creating job {self.job_name!r} \"\n            f\"with command {' '.join(self.command)!r} in region \"\n            f\"{self.region!r} using image {self.image!r}\"\n        )\n\n        project = self.gcp_credentials.project\n        resource_name = f\"projects/{project}/locations/{self.region}\"\n\n        async for attempt in AsyncRetrying(\n            stop=stop_after_attempt(3), wait=wait_fixed(1) + wait_random(0, 3)\n        ):\n            with attempt:\n                custom_job_run = await job_service_async_client.create_custom_job(\n                    parent=resource_name,\n                    custom_job=custom_job,\n                )\n\n        self.logger.info(\n            f\"{self._log_prefix}: Job {self.job_name!r} created. \"\n            f\"The full job name is {custom_job_run.name!r}\"\n        )\n\n        return custom_job_run\n\n    async def _watch_job_run(\n        self,\n        full_job_name: str,  # different from self.job_name\n        job_service_async_client: \"JobServiceAsyncClient\",\n        current_state: \"JobState\",\n        until_states: Tuple[\"JobState\"],\n        timeout: int = None,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Polls job run to see if status changed.\n\n        State changes reported by the Vertex AI API may sometimes be inaccurate\n        immediately upon startup, but should eventually report a correct running\n        and then terminal state. The minimum training duration for a custom job is\n        30 seconds, so short-lived jobs may be marked as successful some time\n        after a flow run has completed.\n        \"\"\"\n        state = JobState.JOB_STATE_UNSPECIFIED\n        last_state = current_state\n        t0 = time.time()\n\n        while state not in until_states:\n            job_run = await job_service_async_client.get_custom_job(\n                name=full_job_name,\n            )\n            state = job_run.state\n            if state != last_state:\n                state_label = (\n                    state.name.replace(\"_\", \" \")\n                    .lower()\n                    .replace(\"state\", \"state is now:\")\n                )\n                # results in \"New job state is now: succeeded\"\n                self.logger.debug(\n                    f\"{self._log_prefix}: {self.job_name} has new {state_label}\"\n                )\n                last_state = state\n            else:\n                # Intermittently, the job will not be described. We want to respect the\n                # watch timeout though.\n                self.logger.debug(f\"{self._log_prefix}: Job not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching job for states \"\n                    \"{until_states!r}\"\n                )\n            await asyncio.sleep(self.job_watch_poll_interval)\n\n        return job_run\n\n    @sync_compatible\n    async def run(\n        self, task_status: Optional[\"TaskStatus\"] = None\n    ) -&gt; VertexAICustomTrainingJobResult:\n        \"\"\"\n        Run the configured task on VertexAI.\n\n        Args:\n            task_status: An optional `TaskStatus` to update when the container starts.\n\n        Returns:\n            The `VertexAICustomTrainingJobResult`.\n        \"\"\"\n        client_options = ClientOptions(\n            api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n        )\n\n        job_spec = self._build_job_spec()\n        job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n        job_run = await self._create_and_begin_job(\n            job_spec,\n            job_service_async_client,\n        )\n\n        if task_status:\n            task_status.started(self.job_name)\n\n        final_job_run = await self._watch_job_run(\n            full_job_name=job_run.name,\n            job_service_async_client=job_service_async_client,\n            current_state=job_run.state,\n            until_states=(\n                JobState.JOB_STATE_SUCCEEDED,\n                JobState.JOB_STATE_FAILED,\n                JobState.JOB_STATE_CANCELLED,\n                JobState.JOB_STATE_EXPIRED,\n            ),\n            timeout=self.maximum_run_time.total_seconds(),\n        )\n\n        error_msg = final_job_run.error.message\n        if error_msg:\n            raise RuntimeError(f\"{self._log_prefix}: {error_msg}\")\n\n        status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n        return VertexAICustomTrainingJobResult(\n            identifier=final_job_run.display_name, status_code=status_code\n        )\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a job running Cloud Run.\n\n        Args:\n            identifier: The Vertex AI full job name, formatted like\n                \"projects/{project}/locations/{location}/customJobs/{custom_job}\".\n\n        Returns:\n            The `VertexAICustomTrainingJobResult`.\n        \"\"\"\n        client_options = ClientOptions(\n            api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n        )\n        job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n        await self._kill_job(\n            job_service_async_client=job_service_async_client,\n            full_job_name=identifier,\n        )\n        self.logger.info(f\"Requested to cancel {identifier}...\")\n\n    async def _kill_job(\n        self, job_service_async_client: \"JobServiceAsyncClient\", full_job_name: str\n    ) -&gt; None:\n        \"\"\"\n        Thin wrapper around Job.delete, wrapping a try/except since\n        Job is an independent class that doesn't have knowledge of\n        CloudRunJob and its associated logic.\n        \"\"\"\n        cancel_custom_job_request = CancelCustomJobRequest(name=full_job_name)\n        try:\n            await job_service_async_client.cancel_custom_job(\n                request=cancel_custom_job_request,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Vertex AI job; the job name {full_job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n\n    @property\n    def _log_prefix(self) -&gt; str:\n        \"\"\"\n        Internal property for generating a prefix for logs where `name` may be null\n        \"\"\"\n        if self.name is not None:\n            return f\"VertexAICustomTrainingJob {self.name!r}\"\n        else:\n            return \"VertexAICustomTrainingJob\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.job_name","title":"<code>job_name</code>  <code>property</code>","text":"<p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference: https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a <code>Vertex AI</code> work pool with the same configuration as this block. Returns:     - dict: a base job template for a <code>Vertex AI</code> work pool</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a `Vertex AI` work pool with the same\n    configuration as this block.\n    Returns:\n        - dict: a base job template for a `Vertex AI` work pool\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        self.get_corresponding_worker_type(),\n    )\n    assert (\n        base_job_template is not None\n    ), \"Failed to generate default base job template for Cloud Run worker.\"\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n        ]:\n            continue\n        elif key == \"gcp_credentials\":\n            if not self.gcp_credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(\n                        self.gcp_credentials._block_document_id\n                    )\n                }\n            }\n        elif key == \"maximum_run_time\":\n            base_job_template[\"variables\"][\"properties\"][\"maximum_run_time_hours\"][\n                \"default\"\n            ] = round(value.total_seconds() / 3600)\n        elif key == \"service_account\":\n            base_job_template[\"variables\"][\"properties\"][\"service_account_name\"][\n                \"default\"\n            ] = value\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by `Vertex AI` work pools.\"\n                \" Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return \"vertex-ai\"\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a job running Cloud Run.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>The Vertex AI full job name, formatted like \"projects/{project}/locations/{location}/customJobs/{custom_job}\".</p> required <p>Returns:</p> Type Description <code>None</code> <p>The <code>VertexAICustomTrainingJobResult</code>.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a job running Cloud Run.\n\n    Args:\n        identifier: The Vertex AI full job name, formatted like\n            \"projects/{project}/locations/{location}/customJobs/{custom_job}\".\n\n    Returns:\n        The `VertexAICustomTrainingJobResult`.\n    \"\"\"\n    client_options = ClientOptions(\n        api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n    )\n    job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n        client_options=client_options\n    )\n    await self._kill_job(\n        job_service_async_client=job_service_async_client,\n        full_job_name=identifier,\n    )\n    self.logger.info(f\"Requested to cancel {identifier}...\")\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the job definition that will be sent to GCP.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n    job_spec = self._build_job_spec()\n    custom_job = CustomJob(\n        display_name=self.job_name,\n        job_spec=job_spec,\n        labels=self._get_compatible_labels(),\n    )\n    return str(custom_job)  # outputs a json string\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured task on VertexAI.</p> <p>Parameters:</p> Name Type Description Default <code>task_status</code> <code>Optional[TaskStatus]</code> <p>An optional <code>TaskStatus</code> to update when the container starts.</p> <code>None</code> <p>Returns:</p> Type Description <code>VertexAICustomTrainingJobResult</code> <p>The <code>VertexAICustomTrainingJobResult</code>.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>@sync_compatible\nasync def run(\n    self, task_status: Optional[\"TaskStatus\"] = None\n) -&gt; VertexAICustomTrainingJobResult:\n    \"\"\"\n    Run the configured task on VertexAI.\n\n    Args:\n        task_status: An optional `TaskStatus` to update when the container starts.\n\n    Returns:\n        The `VertexAICustomTrainingJobResult`.\n    \"\"\"\n    client_options = ClientOptions(\n        api_endpoint=f\"{self.region}-aiplatform.googleapis.com\"\n    )\n\n    job_spec = self._build_job_spec()\n    job_service_async_client = self.gcp_credentials.get_job_service_async_client(\n        client_options=client_options\n    )\n    job_run = await self._create_and_begin_job(\n        job_spec,\n        job_service_async_client,\n    )\n\n    if task_status:\n        task_status.started(self.job_name)\n\n    final_job_run = await self._watch_job_run(\n        full_job_name=job_run.name,\n        job_service_async_client=job_service_async_client,\n        current_state=job_run.state,\n        until_states=(\n            JobState.JOB_STATE_SUCCEEDED,\n            JobState.JOB_STATE_FAILED,\n            JobState.JOB_STATE_CANCELLED,\n            JobState.JOB_STATE_EXPIRED,\n        ),\n        timeout=self.maximum_run_time.total_seconds(),\n    )\n\n    error_msg = final_job_run.error.message\n    if error_msg:\n        raise RuntimeError(f\"{self._log_prefix}: {error_msg}\")\n\n    status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n    return VertexAICustomTrainingJobResult(\n        identifier=final_job_run.display_name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/aiplatform/#prefect_gcp.aiplatform.VertexAICustomTrainingJobResult","title":"<code>VertexAICustomTrainingJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Result from a Vertex AI custom training job.</p> Source code in <code>prefect_gcp/aiplatform.py</code> <pre><code>class VertexAICustomTrainingJobResult(InfrastructureResult):\n    \"\"\"Result from a Vertex AI custom training job.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/","title":"BigQuery","text":""},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery","title":"<code>prefect_gcp.bigquery</code>","text":"<p>Tasks for interacting with GCP BigQuery</p>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse","title":"<code>BigQueryWarehouse</code>","text":"<p>               Bases: <code>DatabaseBlock</code></p> <p>A block for querying a database with BigQuery.</p> <p>Upon instantiating, a connection to BigQuery is established and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the connection and its cursors when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor could be lost.</p> <p>Attributes:</p> Name Type Description <code>gcp_credentials</code> <code>GcpCredentials</code> <p>The credentials to use to authenticate.</p> <code>fetch_size</code> <code>int</code> <p>The number of rows to fetch at a time when calling fetch_many. Note, this parameter is executed on the client side and is not passed to the database. To limit on the server side, add the <code>LIMIT</code> clause, or the dialect's equivalent clause, like <code>TOP</code>, to the query.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>class BigQueryWarehouse(DatabaseBlock):\n    \"\"\"\n    A block for querying a database with BigQuery.\n\n    Upon instantiating, a connection to BigQuery is established\n    and maintained for the life of the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the connection and its cursors when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor could be lost.\n\n    Attributes:\n        gcp_credentials: The credentials to use to authenticate.\n        fetch_size: The number of rows to fetch at a time when calling fetch_many.\n            Note, this parameter is executed on the client side and is not\n            passed to the database. To limit on the server side, add the `LIMIT`\n            clause, or the dialect's equivalent clause, like `TOP`, to the query.\n    \"\"\"  # noqa\n\n    _block_type_name = \"BigQuery Warehouse\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse\"  # noqa: E501\n\n    gcp_credentials: GcpCredentials\n    fetch_size: int = Field(\n        default=1, description=\"The number of rows to fetch at a time.\"\n    )\n\n    _connection: Optional[\"Connection\"] = None\n    _unique_cursors: Dict[str, \"Cursor\"] = None\n\n    def _start_connection(self):\n        \"\"\"\n        Starts a connection.\n        \"\"\"\n        with self.gcp_credentials.get_bigquery_client() as client:\n            self._connection = Connection(client=client)\n\n    def block_initialization(self) -&gt; None:\n        super().block_initialization()\n        if self._connection is None:\n            self._start_connection()\n\n        if self._unique_cursors is None:\n            self._unique_cursors = {}\n\n    def get_connection(self) -&gt; \"Connection\":\n        \"\"\"\n        Get the opened connection to BigQuery.\n        \"\"\"\n        return self._connection\n\n    def _get_cursor(self, inputs: Dict[str, Any]) -&gt; Tuple[bool, \"Cursor\"]:\n        \"\"\"\n        Get a BigQuery cursor.\n\n        Args:\n            inputs: The inputs to generate a unique hash, used to decide\n                whether a new cursor should be used.\n\n        Returns:\n            Whether a cursor is new and a BigQuery cursor.\n        \"\"\"\n        input_hash = hash_objects(inputs)\n        assert input_hash is not None, (\n            \"We were not able to hash your inputs, \"\n            \"which resulted in an unexpected data return; \"\n            \"please open an issue with a reproducible example.\"\n        )\n        if input_hash not in self._unique_cursors.keys():\n            new_cursor = self._connection.cursor()\n            self._unique_cursors[input_hash] = new_cursor\n            return True, new_cursor\n        else:\n            existing_cursor = self._unique_cursors[input_hash]\n            return False, existing_cursor\n\n    def reset_cursors(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened cursors.\n        \"\"\"\n        input_hashes = tuple(self._unique_cursors.keys())\n        for input_hash in input_hashes:\n            cursor = self._unique_cursors.pop(input_hash)\n            try:\n                cursor.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n                )\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; \"Row\":\n        \"\"\"\n        Fetch a single result from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A tuple containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching one new row at a time:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 3;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                for _ in range(0, 3):\n                    result = warehouse.fetch_one(operation, parameters=parameters)\n                    print(result)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        result = await run_sync_in_worker_thread(cursor.fetchone)\n        return result\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[\"Row\"]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching two new rows at a time:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 6;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                for _ in range(0, 3):\n                    result = warehouse.fetch_many(\n                        operation,\n                        parameters=parameters,\n                        size=2\n                    )\n                    print(result)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        size = size or self.fetch_size\n        result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n        return result\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[\"Row\"]:\n        \"\"\"\n        Fetch all results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Execute operation with parameters, fetching all rows:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    SELECT word, word_count\n                    FROM `bigquery-public-data.samples.shakespeare`\n                    WHERE corpus = %(corpus)s\n                    AND word_count &gt;= %(min_word_count)s\n                    ORDER BY word_count DESC\n                    LIMIT 3;\n                '''\n                parameters = {\n                    \"corpus\": \"romeoandjuliet\",\n                    \"min_word_count\": 250,\n                }\n                result = warehouse.fetch_all(operation, parameters=parameters)\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        new, cursor = self._get_cursor(inputs)\n        if new:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n        result = await run_sync_in_worker_thread(cursor.fetchall)\n        return result\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Additional options to pass to `connection.execute`.\n\n        Examples:\n            Execute operation with parameters:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n                operation = '''\n                    CREATE TABLE mydataset.trips AS (\n                    SELECT\n                        bikeid,\n                        start_time,\n                        duration_minutes\n                    FROM\n                        bigquery-public-data.austin_bikeshare.bikeshare_trips\n                    LIMIT %(limit)s\n                    );\n                '''\n                warehouse.execute(operation, parameters={\"limit\": 5})\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            parameters=parameters,\n            **execution_options,\n        )\n        cursor = self._get_cursor(inputs)[1]\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operations\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n\n        Examples:\n            Create mytable in mydataset and insert two rows into it:\n            ```python\n            from prefect_gcp.bigquery import BigQueryWarehouse\n\n            with BigQueryWarehouse.load(\"bigquery\") as warehouse:\n                create_operation = '''\n                CREATE TABLE IF NOT EXISTS mydataset.mytable (\n                    col1 STRING,\n                    col2 INTEGER,\n                    col3 BOOLEAN\n                )\n                '''\n                warehouse.execute(create_operation)\n                insert_operation = '''\n                INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n                '''\n                seq_of_parameters = [\n                    (\"a\", 1, True),\n                    (\"b\", 2, False),\n                ]\n                warehouse.execute_many(\n                    insert_operation,\n                    seq_of_parameters=seq_of_parameters\n                )\n            ```\n        \"\"\"\n        inputs = dict(\n            operation=operation,\n            seq_of_parameters=seq_of_parameters,\n        )\n        cursor = self._get_cursor(inputs)[1]\n        await run_sync_in_worker_thread(cursor.executemany, **inputs)\n\n    def close(self):\n        \"\"\"\n        Closes connection and its cursors.\n        \"\"\"\n        try:\n            self.reset_cursors()\n        finally:\n            if self._connection is not None:\n                self._connection.close()\n                self._connection = None\n\n    def __enter__(self):\n        \"\"\"\n        Start a connection upon entry.\n        \"\"\"\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Closes connection and its cursors upon exit.\n        \"\"\"\n        self.close()\n\n    def __getstate__(self):\n        \"\"\" \"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_connection\", \"_unique_cursors\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\" \"\"\"\n        self.__dict__.update(data)\n        self._unique_cursors = {}\n        self._start_connection()\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.close","title":"<code>close</code>","text":"<p>Closes connection and its cursors.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes connection and its cursors.\n    \"\"\"\n    try:\n        self.reset_cursors()\n    finally:\n        if self._connection is not None:\n            self._connection.close()\n            self._connection = None\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Examples:</p> <p>Execute operation with parameters: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        CREATE TABLE mydataset.trips AS (\n        SELECT\n            bikeid,\n            start_time,\n            duration_minutes\n        FROM\n            bigquery-public-data.austin_bikeshare.bikeshare_trips\n        LIMIT %(limit)s\n        );\n    '''\n    warehouse.execute(operation, parameters={\"limit\": 5})\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Examples:\n        Execute operation with parameters:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                CREATE TABLE mydataset.trips AS (\n                SELECT\n                    bikeid,\n                    start_time,\n                    duration_minutes\n                FROM\n                    bigquery-public-data.austin_bikeshare.bikeshare_trips\n                LIMIT %(limit)s\n                );\n            '''\n            warehouse.execute(operation, parameters={\"limit\": 5})\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    cursor = self._get_cursor(inputs)[1]\n    await run_sync_in_worker_thread(cursor.execute, **inputs)\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operations upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <p>Examples:</p> <p>Create mytable in mydataset and insert two rows into it: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"bigquery\") as warehouse:\n    create_operation = '''\n    CREATE TABLE IF NOT EXISTS mydataset.mytable (\n        col1 STRING,\n        col2 INTEGER,\n        col3 BOOLEAN\n    )\n    '''\n    warehouse.execute(create_operation)\n    insert_operation = '''\n    INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n    '''\n    seq_of_parameters = [\n        (\"a\", 1, True),\n        (\"b\", 2, False),\n    ]\n    warehouse.execute_many(\n        insert_operation,\n        seq_of_parameters=seq_of_parameters\n    )\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operations\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n\n    Examples:\n        Create mytable in mydataset and insert two rows into it:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"bigquery\") as warehouse:\n            create_operation = '''\n            CREATE TABLE IF NOT EXISTS mydataset.mytable (\n                col1 STRING,\n                col2 INTEGER,\n                col3 BOOLEAN\n            )\n            '''\n            warehouse.execute(create_operation)\n            insert_operation = '''\n            INSERT INTO mydataset.mytable (col1, col2, col3) VALUES (%s, %s, %s)\n            '''\n            seq_of_parameters = [\n                (\"a\", 1, True),\n                (\"b\", 2, False),\n            ]\n            warehouse.execute_many(\n                insert_operation,\n                seq_of_parameters=seq_of_parameters\n            )\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        seq_of_parameters=seq_of_parameters,\n    )\n    cursor = self._get_cursor(inputs)[1]\n    await run_sync_in_worker_thread(cursor.executemany, **inputs)\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Row]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching all rows: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 3;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    result = warehouse.fetch_all(operation, parameters=parameters)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[\"Row\"]:\n    \"\"\"\n    Fetch all results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching all rows:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 3;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            result = warehouse.fetch_all(operation, parameters=parameters)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    result = await run_sync_in_worker_thread(cursor.fetchall)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Row]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching two new rows at a time: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 6;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    for _ in range(0, 3):\n        result = warehouse.fetch_many(\n            operation,\n            parameters=parameters,\n            size=2\n        )\n        print(result)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[\"Row\"]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching two new rows at a time:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 6;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            for _ in range(0, 3):\n                result = warehouse.fetch_many(\n                    operation,\n                    parameters=parameters,\n                    size=2\n                )\n                print(result)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    size = size or self.fetch_size\n    result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Additional options to pass to <code>connection.execute</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Row</code> <p>A tuple containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Execute operation with parameters, fetching one new row at a time: <pre><code>from prefect_gcp.bigquery import BigQueryWarehouse\n\nwith BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n    operation = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = %(corpus)s\n        AND word_count &gt;= %(min_word_count)s\n        ORDER BY word_count DESC\n        LIMIT 3;\n    '''\n    parameters = {\n        \"corpus\": \"romeoandjuliet\",\n        \"min_word_count\": 250,\n    }\n    for _ in range(0, 3):\n        result = warehouse.fetch_one(operation, parameters=parameters)\n        print(result)\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; \"Row\":\n    \"\"\"\n    Fetch a single result from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Additional options to pass to `connection.execute`.\n\n    Returns:\n        A tuple containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Execute operation with parameters, fetching one new row at a time:\n        ```python\n        from prefect_gcp.bigquery import BigQueryWarehouse\n\n        with BigQueryWarehouse.load(\"BLOCK_NAME\") as warehouse:\n            operation = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = %(corpus)s\n                AND word_count &gt;= %(min_word_count)s\n                ORDER BY word_count DESC\n                LIMIT 3;\n            '''\n            parameters = {\n                \"corpus\": \"romeoandjuliet\",\n                \"min_word_count\": 250,\n            }\n            for _ in range(0, 3):\n                result = warehouse.fetch_one(operation, parameters=parameters)\n                print(result)\n        ```\n    \"\"\"\n    inputs = dict(\n        operation=operation,\n        parameters=parameters,\n        **execution_options,\n    )\n    new, cursor = self._get_cursor(inputs)\n    if new:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n\n    result = await run_sync_in_worker_thread(cursor.fetchone)\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.get_connection","title":"<code>get_connection</code>","text":"<p>Get the opened connection to BigQuery.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def get_connection(self) -&gt; \"Connection\":\n    \"\"\"\n    Get the opened connection to BigQuery.\n    \"\"\"\n    return self._connection\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.BigQueryWarehouse.reset_cursors","title":"<code>reset_cursors</code>","text":"<p>Tries to close all opened cursors.</p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>def reset_cursors(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened cursors.\n    \"\"\"\n    input_hashes = tuple(self._unique_cursors.keys())\n    for input_hash in input_hashes:\n        cursor = self._unique_cursors.pop(input_hash)\n        try:\n            cursor.close()\n        except Exception as exc:\n            self.logger.warning(\n                f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n            )\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_create_table","title":"<code>bigquery_create_table</code>  <code>async</code>","text":"<p>Creates table in BigQuery. Args:     dataset: Name of a dataset in that the table will be created.     table: Name of a table to create.     schema: Schema to use when creating the table.     gcp_credentials: Credentials to use for authentication with GCP.     clustering_fields: List of fields to cluster the table by.     time_partitioning: <code>bigquery.TimePartitioning</code> object specifying a partitioning         of the newly created table     project: Project to initialize the BigQuery Client with; if         not provided, will default to the one inferred from your credentials.     location: The location of the dataset that will be written to.     external_config: The external data source.  # noqa Returns:     Table name. Example:     <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_create_table\nfrom google.cloud.bigquery import SchemaField\n@flow\ndef example_bigquery_create_table_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    schema = [\n        SchemaField(\"number\", field_type=\"INTEGER\", mode=\"REQUIRED\"),\n        SchemaField(\"text\", field_type=\"STRING\", mode=\"REQUIRED\"),\n        SchemaField(\"bool\", field_type=\"BOOLEAN\")\n    ]\n    result = bigquery_create_table(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        schema=schema,\n        gcp_credentials=gcp_credentials\n    )\n    return result\nexample_bigquery_create_table_flow()\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_create_table(\n    dataset: str,\n    table: str,\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    clustering_fields: List[str] = None,\n    time_partitioning: \"TimePartitioning\" = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n    external_config: Optional[\"ExternalConfig\"] = None,\n) -&gt; str:\n    \"\"\"\n    Creates table in BigQuery.\n    Args:\n        dataset: Name of a dataset in that the table will be created.\n        table: Name of a table to create.\n        schema: Schema to use when creating the table.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        clustering_fields: List of fields to cluster the table by.\n        time_partitioning: `bigquery.TimePartitioning` object specifying a partitioning\n            of the newly created table\n        project: Project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: The location of the dataset that will be written to.\n        external_config: The [external data source](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#nested_external_data_configuration).  # noqa\n    Returns:\n        Table name.\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_create_table\n        from google.cloud.bigquery import SchemaField\n        @flow\n        def example_bigquery_create_table_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            schema = [\n                SchemaField(\"number\", field_type=\"INTEGER\", mode=\"REQUIRED\"),\n                SchemaField(\"text\", field_type=\"STRING\", mode=\"REQUIRED\"),\n                SchemaField(\"bool\", field_type=\"BOOLEAN\")\n            ]\n            result = bigquery_create_table(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                schema=schema,\n                gcp_credentials=gcp_credentials\n            )\n            return result\n        example_bigquery_create_table_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating %s.%s\", dataset, table)\n\n    if not external_config and not schema:\n        raise ValueError(\"Either a schema or an external config must be provided.\")\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    try:\n        partial_get_dataset = partial(client.get_dataset, dataset)\n        dataset_ref = await to_thread.run_sync(partial_get_dataset)\n    except NotFound:\n        logger.debug(\"Dataset %s not found, creating\", dataset)\n        partial_create_dataset = partial(client.create_dataset, dataset)\n        dataset_ref = await to_thread.run_sync(partial_create_dataset)\n\n    table_ref = dataset_ref.table(table)\n    try:\n        partial_get_table = partial(client.get_table, table_ref)\n        await to_thread.run_sync(partial_get_table)\n        logger.info(\"%s.%s already exists\", dataset, table)\n    except NotFound:\n        logger.debug(\"Table %s not found, creating\", table)\n        table_obj = Table(table_ref, schema=schema)\n\n        # external data configuration\n        if external_config:\n            table_obj.external_data_configuration = external_config\n\n        # cluster for optimal data sorting/access\n        if clustering_fields:\n            table_obj.clustering_fields = clustering_fields\n\n        # partitioning\n        if time_partitioning:\n            table_obj.time_partitioning = time_partitioning\n\n        partial_create_table = partial(client.create_table, table_obj)\n        await to_thread.run_sync(partial_create_table)\n\n    return table\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_insert_stream","title":"<code>bigquery_insert_stream</code>  <code>async</code>","text":"<p>Insert records in a Google BigQuery table via the streaming API.</p> <p>Parameters:</p> Name Type Description Default <code>dataset</code> <code>str</code> <p>Name of a dataset where the records will be written to.</p> required <code>table</code> <code>str</code> <p>Name of a table to write to.</p> required <code>records</code> <code>List[dict]</code> <p>The list of records to insert as rows into the BigQuery table; each item in the list should be a dictionary whose keys correspond to columns in the table.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>project</code> <code>Optional[str]</code> <p>The project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location of the dataset that will be written to.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>List</code> <p>List of inserted rows.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_insert_stream\nfrom google.cloud.bigquery import SchemaField\n\n@flow\ndef example_bigquery_insert_stream_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    records = [\n        {\"number\": 1, \"text\": \"abc\", \"bool\": True},\n        {\"number\": 2, \"text\": \"def\", \"bool\": False},\n    ]\n    result = bigquery_insert_stream(\n        dataset=\"integrations\",\n        table=\"test_table\",\n        records=records,\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_insert_stream_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_insert_stream(\n    dataset: str,\n    table: str,\n    records: List[dict],\n    gcp_credentials: GcpCredentials,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; List:\n    \"\"\"\n    Insert records in a Google BigQuery table via the [streaming\n    API](https://cloud.google.com/bigquery/streaming-data-into-bigquery).\n\n    Args:\n        dataset: Name of a dataset where the records will be written to.\n        table: Name of a table to write to.\n        records: The list of records to insert as rows into the BigQuery table;\n            each item in the list should be a dictionary whose keys correspond to\n            columns in the table.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        project: The project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: Location of the dataset that will be written to.\n\n    Returns:\n        List of inserted rows.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_insert_stream\n        from google.cloud.bigquery import SchemaField\n\n        @flow\n        def example_bigquery_insert_stream_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            records = [\n                {\"number\": 1, \"text\": \"abc\", \"bool\": True},\n                {\"number\": 2, \"text\": \"def\", \"bool\": False},\n            ]\n            result = bigquery_insert_stream(\n                dataset=\"integrations\",\n                table=\"test_table\",\n                records=records,\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_insert_stream_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Inserting into %s.%s as a stream\", dataset, table)\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    table_ref = client.dataset(dataset).table(table)\n    partial_insert = partial(\n        client.insert_rows_json, table=table_ref, json_rows=records\n    )\n    response = await to_thread.run_sync(partial_insert)\n\n    errors = []\n    output = []\n    for row in response:\n        output.append(row)\n        if \"errors\" in row:\n            errors.append(row[\"errors\"])\n\n    if errors:\n        raise ValueError(errors)\n\n    return output\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_load_cloud_storage","title":"<code>bigquery_load_cloud_storage</code>  <code>async</code>","text":"<p>Run method for this Task.  Invoked by calling this Task within a Flow context, after initialization. Args:     uri: GCS path to load data from.     dataset: The id of a destination dataset to write the records to.     table: The name of a destination table to write the records to.     gcp_credentials: Credentials to use for authentication with GCP.     schema: The schema to use when creating the table.     job_config: Dictionary of job configuration parameters;         note that the parameters provided here must be pickleable         (e.g., dataset references will be rejected).     project: The project to initialize the BigQuery Client with; if         not provided, will default to the one inferred from your credentials.     location: Location of the dataset that will be written to.</p> <p>Returns:</p> Type Description <code>LoadJob</code> <p>The response from <code>load_table_from_uri</code>.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_load_cloud_storage\n\n@flow\ndef example_bigquery_load_cloud_storage_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    result = bigquery_load_cloud_storage(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        uri=\"uri\",\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_load_cloud_storage_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_load_cloud_storage(\n    dataset: str,\n    table: str,\n    uri: str,\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    job_config: Optional[dict] = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; \"LoadJob\":\n    \"\"\"\n    Run method for this Task.  Invoked by _calling_ this\n    Task within a Flow context, after initialization.\n    Args:\n        uri: GCS path to load data from.\n        dataset: The id of a destination dataset to write the records to.\n        table: The name of a destination table to write the records to.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        schema: The schema to use when creating the table.\n        job_config: Dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        project: The project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: Location of the dataset that will be written to.\n\n    Returns:\n        The response from `load_table_from_uri`.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_load_cloud_storage\n\n        @flow\n        def example_bigquery_load_cloud_storage_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            result = bigquery_load_cloud_storage(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                uri=\"uri\",\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_load_cloud_storage_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Loading into %s.%s from cloud storage\", dataset, table)\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n    table_ref = client.dataset(dataset).table(table)\n\n    job_config = job_config or {}\n    if \"autodetect\" not in job_config:\n        job_config[\"autodetect\"] = True\n    job_config = LoadJobConfig(**job_config)\n    if schema:\n        job_config.schema = schema\n\n    result = None\n    try:\n        partial_load = partial(\n            _result_sync,\n            client.load_table_from_uri,\n            uri,\n            table_ref,\n            job_config=job_config,\n        )\n        result = await to_thread.run_sync(partial_load)\n    except Exception as exception:\n        logger.exception(exception)\n        if result is not None and result.errors is not None:\n            for error in result.errors:\n                logger.exception(error)\n        raise\n\n    if result is not None:\n        # remove unpickleable attributes\n        result._client = None\n        result._completion_lock = None\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_load_file","title":"<code>bigquery_load_file</code>  <code>async</code>","text":"<p>Loads file into BigQuery.</p> <p>Parameters:</p> Name Type Description Default <code>dataset</code> <code>str</code> <p>ID of a destination dataset to write the records to; if not provided here, will default to the one provided at initialization.</p> required <code>table</code> <code>str</code> <p>Name of a destination table to write the records to; if not provided here, will default to the one provided at initialization.</p> required <code>path</code> <code>Union[str, Path]</code> <p>A string or path-like object of the file to be loaded.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>schema</code> <code>Optional[List[SchemaField]]</code> <p>Schema to use when creating the table.</p> <code>None</code> <code>job_config</code> <code>Optional[dict]</code> <p>An optional dictionary of job configuration parameters; note that the parameters provided here must be pickleable (e.g., dataset references will be rejected).</p> <code>None</code> <code>rewind</code> <code>bool</code> <p>if True, seek to the beginning of the file handle before reading the file.</p> <code>False</code> <code>size</code> <code>Optional[int]</code> <p>Number of bytes to read from the file handle. If size is None or large, resumable upload will be used. Otherwise, multipart upload will be used.</p> <code>None</code> <code>project</code> <code>Optional[str]</code> <p>Project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>location</code> <code>str</code> <p>location of the dataset that will be written to.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>LoadJob</code> <p>The response from <code>load_table_from_file</code>.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_load_file\nfrom google.cloud.bigquery import SchemaField\n\n@flow\ndef example_bigquery_load_file_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    result = bigquery_load_file(\n        dataset=\"dataset\",\n        table=\"test_table\",\n        path=\"path\",\n        gcp_credentials=gcp_credentials\n    )\n    return result\n\nexample_bigquery_load_file_flow()\n</code></pre> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_load_file(\n    dataset: str,\n    table: str,\n    path: Union[str, Path],\n    gcp_credentials: GcpCredentials,\n    schema: Optional[List[\"SchemaField\"]] = None,\n    job_config: Optional[dict] = None,\n    rewind: bool = False,\n    size: Optional[int] = None,\n    project: Optional[str] = None,\n    location: str = \"US\",\n) -&gt; \"LoadJob\":\n    \"\"\"\n    Loads file into BigQuery.\n\n    Args:\n        dataset: ID of a destination dataset to write the records to;\n            if not provided here, will default to the one provided at initialization.\n        table: Name of a destination table to write the records to;\n            if not provided here, will default to the one provided at initialization.\n        path: A string or path-like object of the file to be loaded.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        schema: Schema to use when creating the table.\n        job_config: An optional dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        rewind: if True, seek to the beginning of the file handle\n            before reading the file.\n        size: Number of bytes to read from the file handle. If size is None or large,\n            resumable upload will be used. Otherwise, multipart upload will be used.\n        project: Project to initialize the BigQuery Client with; if\n            not provided, will default to the one inferred from your credentials.\n        location: location of the dataset that will be written to.\n\n    Returns:\n        The response from `load_table_from_file`.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_load_file\n        from google.cloud.bigquery import SchemaField\n\n        @flow\n        def example_bigquery_load_file_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            result = bigquery_load_file(\n                dataset=\"dataset\",\n                table=\"test_table\",\n                path=\"path\",\n                gcp_credentials=gcp_credentials\n            )\n            return result\n\n        example_bigquery_load_file_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Loading into %s.%s from file\", dataset, table)\n\n    if not os.path.exists(path):\n        raise ValueError(f\"{path} does not exist\")\n    elif not os.path.isfile(path):\n        raise ValueError(f\"{path} is not a file\")\n\n    client = gcp_credentials.get_bigquery_client(project=project)\n    table_ref = client.dataset(dataset).table(table)\n\n    job_config = job_config or {}\n    if \"autodetect\" not in job_config:\n        job_config[\"autodetect\"] = True\n        # TODO: test if autodetect is needed when schema is passed\n    job_config = LoadJobConfig(**job_config)\n    if schema:\n        # TODO: test if schema can be passed directly in job_config\n        job_config.schema = schema\n\n    try:\n        with open(path, \"rb\") as file_obj:\n            partial_load = partial(\n                _result_sync,\n                client.load_table_from_file,\n                file_obj,\n                table_ref,\n                rewind=rewind,\n                size=size,\n                location=location,\n                job_config=job_config,\n            )\n            result = await to_thread.run_sync(partial_load)\n    except IOError:\n        logger.exception(f\"Could not open and read from {path}\")\n        raise\n\n    if result is not None:\n        # remove unpickleable attributes\n        result._client = None\n        result._completion_lock = None\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-gcp/bigquery/#prefect_gcp.bigquery.bigquery_query","title":"<code>bigquery_query</code>  <code>async</code>","text":"<p>Runs a BigQuery query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>String of the query to execute.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>query_params</code> <code>Optional[List[tuple]]</code> <p>List of 3-tuples specifying BigQuery query parameters; currently only scalar query parameters are supported.  See the Google documentation for more details on how both the query and the query parameters should be formatted.</p> <code>None</code> <code>dry_run_max_bytes</code> <code>Optional[int]</code> <p>If provided, the maximum number of bytes the query is allowed to process; this will be determined by executing a dry run and raising a <code>ValueError</code> if the maximum is exceeded.</p> <code>None</code> <code>dataset</code> <code>Optional[str]</code> <p>Name of a destination dataset to write the query results to, if you don't want them returned; if provided, <code>table</code> must also be provided.</p> <code>None</code> <code>table</code> <code>Optional[str]</code> <p>Name of a destination table to write the query results to, if you don't want them returned; if provided, <code>dataset</code> must also be provided.</p> <code>None</code> <code>to_dataframe</code> <code>bool</code> <p>If provided, returns the results of the query as a pandas dataframe instead of a list of <code>bigquery.table.Row</code> objects.</p> <code>False</code> <code>job_config</code> <code>Optional[dict]</code> <p>Dictionary of job configuration parameters; note that the parameters provided here must be pickleable (e.g., dataset references will be rejected).</p> <code>None</code> <code>project</code> <code>Optional[str]</code> <p>The project to initialize the BigQuery Client with; if not provided, will default to the one inferred from your credentials.</p> <code>None</code> <code>result_transformer</code> <code>Optional[Callable[[List[Row]], Any]]</code> <p>Function that can be passed to transform the result of a query before returning. The function will be passed the list of rows returned by BigQuery for the given query.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location of the dataset that will be queried.</p> <code>'US'</code> <p>Returns:</p> Type Description <code>Any</code> <p>A list of rows, or pandas DataFrame if to_dataframe,</p> <code>Any</code> <p>matching the query criteria.</p> Example <p>Queries the public names database, returning 10 results. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.bigquery import bigquery_query\n\n@flow\ndef example_bigquery_query_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\",\n        project=\"project\"\n    )\n    query = '''\n        SELECT word, word_count\n        FROM `bigquery-public-data.samples.shakespeare`\n        WHERE corpus = @corpus\n        AND word_count &gt;= @min_word_count\n        ORDER BY word_count DESC;\n    '''\n    query_params = [\n        (\"corpus\", \"STRING\", \"romeoandjuliet\"),\n        (\"min_word_count\", \"INT64\", 250)\n    ]\n    result = bigquery_query(\n        query, gcp_credentials, query_params=query_params\n    )\n    return result\n\nexample_bigquery_query_flow()\n</code></pre></p> Source code in <code>prefect_gcp/bigquery.py</code> <pre><code>@task\nasync def bigquery_query(\n    query: str,\n    gcp_credentials: GcpCredentials,\n    query_params: Optional[List[tuple]] = None,  # 3-tuples\n    dry_run_max_bytes: Optional[int] = None,\n    dataset: Optional[str] = None,\n    table: Optional[str] = None,\n    to_dataframe: bool = False,\n    job_config: Optional[dict] = None,\n    project: Optional[str] = None,\n    result_transformer: Optional[Callable[[List[\"Row\"]], Any]] = None,\n    location: str = \"US\",\n) -&gt; Any:\n    \"\"\"\n    Runs a BigQuery query.\n\n    Args:\n        query: String of the query to execute.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        query_params: List of 3-tuples specifying BigQuery query parameters; currently\n            only scalar query parameters are supported.  See the\n            [Google documentation](https://cloud.google.com/bigquery/docs/parameterized-queries#bigquery-query-params-python)\n            for more details on how both the query and the query parameters should be formatted.\n        dry_run_max_bytes: If provided, the maximum number of bytes the query\n            is allowed to process; this will be determined by executing a dry run\n            and raising a `ValueError` if the maximum is exceeded.\n        dataset: Name of a destination dataset to write the query results to,\n            if you don't want them returned; if provided, `table` must also be provided.\n        table: Name of a destination table to write the query results to,\n            if you don't want them returned; if provided, `dataset` must also be provided.\n        to_dataframe: If provided, returns the results of the query as a pandas\n            dataframe instead of a list of `bigquery.table.Row` objects.\n        job_config: Dictionary of job configuration parameters;\n            note that the parameters provided here must be pickleable\n            (e.g., dataset references will be rejected).\n        project: The project to initialize the BigQuery Client with; if not\n            provided, will default to the one inferred from your credentials.\n        result_transformer: Function that can be passed to transform the result of a query before returning. The function will be passed the list of rows returned by BigQuery for the given query.\n        location: Location of the dataset that will be queried.\n\n    Returns:\n        A list of rows, or pandas DataFrame if to_dataframe,\n        matching the query criteria.\n\n    Example:\n        Queries the public names database, returning 10 results.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.bigquery import bigquery_query\n\n        @flow\n        def example_bigquery_query_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\",\n                project=\"project\"\n            )\n            query = '''\n                SELECT word, word_count\n                FROM `bigquery-public-data.samples.shakespeare`\n                WHERE corpus = @corpus\n                AND word_count &gt;= @min_word_count\n                ORDER BY word_count DESC;\n            '''\n            query_params = [\n                (\"corpus\", \"STRING\", \"romeoandjuliet\"),\n                (\"min_word_count\", \"INT64\", 250)\n            ]\n            result = bigquery_query(\n                query, gcp_credentials, query_params=query_params\n            )\n            return result\n\n        example_bigquery_query_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Running BigQuery query\")\n\n    client = gcp_credentials.get_bigquery_client(project=project, location=location)\n\n    # setup job config\n    job_config = QueryJobConfig(**job_config or {})\n    if query_params is not None:\n        job_config.query_parameters = [ScalarQueryParameter(*qp) for qp in query_params]\n\n    # perform dry_run if requested\n    if dry_run_max_bytes is not None:\n        saved_info = dict(\n            dry_run=job_config.dry_run, use_query_cache=job_config.use_query_cache\n        )\n        job_config.dry_run = True\n        job_config.use_query_cache = False\n        partial_query = partial(client.query, query, job_config=job_config)\n        response = await to_thread.run_sync(partial_query)\n        total_bytes_processed = response.total_bytes_processed\n        if total_bytes_processed &gt; dry_run_max_bytes:\n            raise RuntimeError(\n                f\"Query will process {total_bytes_processed} bytes which is above \"\n                f\"the set maximum of {dry_run_max_bytes} for this task.\"\n            )\n        job_config.dry_run = saved_info[\"dry_run\"]\n        job_config.use_query_cache = saved_info[\"use_query_cache\"]\n\n    # if writing to a destination table\n    if dataset is not None:\n        table_ref = client.dataset(dataset).table(table)\n        job_config.destination = table_ref\n\n    partial_query = partial(\n        _result_sync,\n        client.query,\n        query,\n        job_config=job_config,\n    )\n    result = await to_thread.run_sync(partial_query)\n\n    if to_dataframe:\n        return result.to_dataframe()\n    else:\n        if result_transformer:\n            return result_transformer(result)\n        else:\n            return list(result)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/","title":"Cloud Run","text":""},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run","title":"<code>prefect_gcp.cloud_run</code>","text":"<p>DEPRECATION WARNING:</p> <p>This module is deprecated as of March 2024 and will not be available after September 2024. It has been replaced by the Cloud Run and Cloud Run V2 workers, which offer enhanced functionality and better performance.</p> <p>For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.</p> <p>Integrations with Google Cloud Run Job.</p> <p>Examples:</p> <pre><code>Run a job using Google Cloud Run Jobs:\n```python\nCloudRunJob(\n    image=\"gcr.io/my-project/my-image\",\n    region=\"us-east1\",\n    credentials=my_gcp_credentials\n).run()\n```\n\nRun a job that runs the command `echo hello world` using Google Cloud Run Jobs:\n```python\nCloudRunJob(\n    image=\"gcr.io/my-project/my-image\",\n    region=\"us-east1\",\n    credentials=my_gcp_credentials\n    command=[\"echo\", \"hello world\"]\n).run()\n```\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob","title":"<code>CloudRunJob</code>","text":"<p>               Bases: <code>Infrastructure</code></p> <p>DEPRECATION WARNING:</p> <p>This block is deprecated along with Agents and all other Infrastructure blocks. It will be removed in prefect v3.</p> <p></p> <p>Infrastructure block used to run GCP Cloud Run Jobs.</p> <p>Project name information is provided by the Credentials object, and should always be correct as long as the Credentials object is for the correct project.</p> <p>Note this block is experimental. The interface may change without notice.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@deprecated_class(\n    start_date=\"Mar 2024\",\n    help=(\n        \"Use the Cloud Run or Cloud Run v2 worker instead.\"\n        \" Refer to the upgrade guide for more information:\"\n        \" https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.\"\n    ),\n)\nclass CloudRunJob(Infrastructure):\n    \"\"\"\n    DEPRECATION WARNING:\n\n    This block is deprecated along with Agents and all other Infrastructure blocks.\n    It will be removed in prefect v3.\n\n    &lt;span class=\"badge-api experimental\"/&gt;\n\n    Infrastructure block used to run GCP Cloud Run Jobs.\n\n    Project name information is provided by the Credentials object, and should always\n    be correct as long as the Credentials object is for the correct project.\n\n    Note this block is experimental. The interface may change without notice.\n    \"\"\"\n\n    _block_type_slug = \"cloud-run-job\"\n    _block_type_name = \"GCP Cloud Run Job\"\n    _description = \"Infrastructure block used to run GCP Cloud Run Jobs. Note this block is experimental. The interface may change without notice.\"  # noqa\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob\"  # noqa: E501\n\n    type: Literal[\"cloud-run-job\"] = Field(\n        \"cloud-run-job\", description=\"The slug for this task type.\"\n    )\n    image: str = Field(\n        ...,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Cloud Run Job. This value must \"\n            \"refer to an image within either Google Container Registry \"\n            \"or Google Artifact Registry, like `gcr.io/&lt;project_name&gt;/&lt;repo&gt;/`.\"\n        ),\n    )\n    region: str = Field(..., description=\"The region where the Cloud Run Job resides.\")\n    credentials: GcpCredentials  # cannot be Field; else it shows as Json\n\n    # Job settings\n    cpu: Optional[int] = Field(\n        default=None,\n        title=\"CPU\",\n        description=(\n            \"The amount of compute allocated to the Cloud Run Job. \"\n            \"The int must be valid based on the rules specified at \"\n            \"https://cloud.google.com/run/docs/configuring/cpu#setting-jobs .\"\n        ),\n    )\n    memory: Optional[int] = Field(\n        default=None,\n        title=\"Memory\",\n        description=\"The amount of memory allocated to the Cloud Run Job.\",\n    )\n    memory_unit: Optional[Literal[\"G\", \"Gi\", \"M\", \"Mi\"]] = Field(\n        default=None,\n        title=\"Memory Units\",\n        description=(\n            \"The unit of memory. See \"\n            \"https://cloud.google.com/run/docs/configuring/memory-limits#setting \"\n            \"for additional details.\"\n        ),\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run Job.\",\n    )\n    args: Optional[List[str]] = Field(\n        default=None,\n        description=(\n            \"Arguments to be passed to your Cloud Run Job's entrypoint command.\"\n        ),\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"Environment variables to be passed to your Cloud Run Job.\",\n    )\n\n    # Cleanup behavior\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job on Google Cloud Platform.\",\n    )\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"The length of time that Prefect will wait for a Cloud Run Job to complete \"\n            \"before raising an exception.\"\n        ),\n    )\n    max_retries: Optional[int] = Field(\n        default=3,\n        ge=0,\n        le=10,\n        title=\"Max Retries\",\n        description=(\n            \"The maximum retries setting specifies the number of times a task is \"\n            \"allowed to restart in case of failure before being failed permanently.\"\n        ),\n    )\n    # For private use\n    _job_name: str = None\n    _execution: Optional[Execution] = None\n\n    @property\n    def job_name(self):\n        \"\"\"Create a unique and valid job name.\"\"\"\n\n        if self._job_name is None:\n            # get `repo` from `gcr.io/&lt;project_name&gt;/repo/other`\n            components = self.image.split(\"/\")\n            image_name = components[2]\n            # only alphanumeric and '-' allowed for a job name\n            modified_image_name = image_name.replace(\":\", \"-\").replace(\".\", \"-\")\n            # make 50 char limit for final job name, which will be '&lt;name&gt;-&lt;uuid&gt;'\n            if len(modified_image_name) &gt; 17:\n                modified_image_name = modified_image_name[:17]\n            name = f\"{modified_image_name}-{uuid4().hex}\"\n            self._job_name = name\n\n        return self._job_name\n\n    @property\n    def memory_string(self):\n        \"\"\"Returns the string expected for memory resources argument.\"\"\"\n        if self.memory and self.memory_unit:\n            return str(self.memory) + self.memory_unit\n        return None\n\n    @validator(\"image\")\n    def _remove_image_spaces(cls, value):\n        \"\"\"Deal with spaces in image names.\"\"\"\n        if value is not None:\n            return value.strip()\n\n    @root_validator\n    def _check_valid_memory(cls, values):\n        \"\"\"Make sure memory conforms to expected values for API.\n        See: https://cloud.google.com/run/docs/configuring/memory-limits#setting\n        \"\"\"  # noqa\n        if (values.get(\"memory\") is not None and values.get(\"memory_unit\") is None) or (\n            values.get(\"memory_unit\") is not None and values.get(\"memory\") is None\n        ):\n            raise ValueError(\n                \"A memory value and unit must both be supplied to specify a memory\"\n                \" value other than the default memory value.\"\n            )\n        return values\n\n    def get_corresponding_worker_type(self) -&gt; str:\n        \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n        return \"cloud-run\"\n\n    async def generate_work_pool_base_job_template(self) -&gt; dict:\n        \"\"\"\n        Generate a base job template for a cloud-run work pool with the same\n        configuration as this block.\n\n        Returns:\n            - dict: a base job template for a cloud-run work pool\n        \"\"\"\n        base_job_template = await get_default_base_job_template_for_infrastructure_type(\n            self.get_corresponding_worker_type(),\n        )\n        assert (\n            base_job_template is not None\n        ), \"Failed to generate default base job template for Cloud Run worker.\"\n        for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n            if key == \"command\":\n                base_job_template[\"variables\"][\"properties\"][\"command\"][\n                    \"default\"\n                ] = shlex.join(value)\n            elif key in [\n                \"type\",\n                \"block_type_slug\",\n                \"_block_document_id\",\n                \"_block_document_name\",\n                \"_is_anonymous\",\n                \"memory_unit\",\n            ]:\n                continue\n            elif key == \"credentials\":\n                if not self.credentials._block_document_id:\n                    raise BlockNotSavedError(\n                        \"It looks like you are trying to use a block that\"\n                        \" has not been saved. Please call `.save` on your block\"\n                        \" before publishing it as a work pool.\"\n                    )\n                base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                    \"default\"\n                ] = {\n                    \"$ref\": {\n                        \"block_document_id\": str(self.credentials._block_document_id)\n                    }\n                }\n            elif key == \"memory\" and self.memory_string:\n                base_job_template[\"variables\"][\"properties\"][\"memory\"][\n                    \"default\"\n                ] = self.memory_string\n            elif key == \"cpu\" and self.cpu is not None:\n                base_job_template[\"variables\"][\"properties\"][\"cpu\"][\n                    \"default\"\n                ] = f\"{self.cpu * 1000}m\"\n            elif key == \"args\":\n                # Not a default variable, but we can add it to the template\n                base_job_template[\"variables\"][\"properties\"][\"args\"] = {\n                    \"title\": \"Arguments\",\n                    \"type\": \"string\",\n                    \"description\": \"Arguments to be passed to your Cloud Run Job's entrypoint command.\",  # noqa\n                    \"default\": value,\n                }\n                base_job_template[\"job_configuration\"][\"job_body\"][\"spec\"][\"template\"][\n                    \"spec\"\n                ][\"template\"][\"spec\"][\"containers\"][0][\"args\"] = \"{{ args }}\"\n            elif key in base_job_template[\"variables\"][\"properties\"]:\n                base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n            else:\n                self.logger.warning(\n                    f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                    \" Skipping.\"\n                )\n\n        return base_job_template\n\n    def _create_job_error(self, exc):\n        \"\"\"Provides a nicer error for 404s when trying to create a Cloud Run Job.\"\"\"\n        # TODO consider lookup table instead of the if/else,\n        # also check for documented errors\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{self.region}' is the correct region for your Cloud Run Job and\"\n                f\" that {self.credentials.project} is the correct GCP project. If\"\n                f\" your project ID is not correct, you are using a Credentials block\"\n                f\" with permissions for the wrong project.\"\n            ) from exc\n        raise exc\n\n    def _job_run_submission_error(self, exc):\n        \"\"\"Provides a nicer error for 404s when submitting job runs.\"\"\"\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n            # pat2 = (\n            #     r\"Resource '[^ ]+' of kind 'JOB' in region '[\\w\\-0-9]+' \"\n            #     r\"in project '[\\w\\-0-9]+' does not exist\"\n            # )\n            if re.findall(pat1, str(exc)):\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{self.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{self.credentials.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n        raise exc\n\n    def _cpu_as_k8s_quantity(self) -&gt; str:\n        \"\"\"Return the CPU integer in the format expected by GCP Cloud Run Jobs API.\n        See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/\n        See also: https://cloud.google.com/run/docs/configuring/cpu#setting-jobs\n        \"\"\"  # noqa\n        return str(self.cpu * 1000) + \"m\"\n\n    @sync_compatible\n    async def run(self, task_status: Optional[TaskStatus] = None):\n        \"\"\"Run the configured job on a Google Cloud Run Job.\"\"\"\n        with self._get_client() as client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration, client\n            )\n            job_execution = await run_sync_in_worker_thread(\n                self._begin_job_execution, client\n            )\n\n            if task_status:\n                task_status.started(self.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                client,\n                job_execution,\n                5,\n            )\n            return result\n\n    @sync_compatible\n    async def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n        \"\"\"\n        Kill a task running Cloud Run.\n\n        Args:\n            identifier: The Cloud Run Job name. This should match a\n                value yielded by CloudRunJob.run.\n        \"\"\"\n        if grace_seconds != 30:\n            self.logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client() as client:\n            await run_sync_in_worker_thread(\n                self._kill_job,\n                client=client,\n                namespace=self.credentials.project,\n                job_name=identifier,\n            )\n\n    def _kill_job(self, client: Resource, namespace: str, job_name: str) -&gt; None:\n        \"\"\"\n        Thin wrapper around Job.delete, wrapping a try/except since\n        Job is an independent class that doesn't have knowledge of\n        CloudRunJob and its associated logic.\n        \"\"\"\n        try:\n            Job.delete(client=client, namespace=namespace, job_name=job_name)\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n\n    def _create_job_and_wait_for_registration(self, client: Resource) -&gt; None:\n        \"\"\"Create a new job wait for it to finish registering.\"\"\"\n        try:\n            self.logger.info(f\"Creating Cloud Run Job {self.job_name}\")\n            Job.create(\n                client=client,\n                namespace=self.credentials.project,\n                body=self._jobs_body(),\n            )\n        except googleapiclient.errors.HttpError as exc:\n            self._create_job_error(exc)\n\n        try:\n            self._wait_for_job_creation(client=client, timeout=self.timeout)\n        except Exception:\n            self.logger.exception(\n                \"Encountered an exception while waiting for job run creation\"\n            )\n            if not self.keep_job:\n                self.logger.info(\n                    f\"Deleting Cloud Run Job {self.job_name} from Google Cloud Run.\"\n                )\n                try:\n                    Job.delete(\n                        client=client,\n                        namespace=self.credentials.project,\n                        job_name=self.job_name,\n                    )\n                except Exception:\n                    self.logger.exception(\n                        \"Received an unexpected exception while attempting to delete\"\n                        f\" Cloud Run Job {self.job_name!r}\"\n                    )\n            raise\n\n    def _begin_job_execution(self, client: Resource) -&gt; Execution:\n        \"\"\"Submit a job run for execution and return the execution object.\"\"\"\n        try:\n            self.logger.info(\n                f\"Submitting Cloud Run Job {self.job_name!r} for execution.\"\n            )\n            submission = Job.run(\n                client=client,\n                namespace=self.credentials.project,\n                job_name=self.job_name,\n            )\n\n            job_execution = Execution.get(\n                client=client,\n                namespace=submission[\"metadata\"][\"namespace\"],\n                execution_name=submission[\"metadata\"][\"name\"],\n            )\n\n            command = (\n                \" \".join(self.command) if self.command else \"default container command\"\n            )\n\n            self.logger.info(\n                f\"Cloud Run Job {self.job_name!r}: Running command {command!r}\"\n            )\n        except Exception as exc:\n            self._job_run_submission_error(exc)\n\n        return job_execution\n\n    def _watch_job_execution_and_get_result(\n        self, client: Resource, execution: Execution, poll_interval: int\n    ) -&gt; CloudRunJobResult:\n        \"\"\"Wait for execution to complete and then return result.\"\"\"\n        try:\n            job_execution = self._watch_job_execution(\n                client=client,\n                job_execution=execution,\n                timeout=self.timeout,\n                poll_interval=poll_interval,\n            )\n        except Exception:\n            self.logger.exception(\n                \"Received an unexpected exception while monitoring Cloud Run Job \"\n                f\"{self.job_name!r}\"\n            )\n            raise\n\n        if job_execution.succeeded():\n            status_code = 0\n            self.logger.info(f\"Job Run {self.job_name} completed successfully\")\n        else:\n            status_code = 1\n            error_msg = job_execution.condition_after_completion()[\"message\"]\n            self.logger.error(\n                f\"Job Run {self.job_name} did not complete successfully. {error_msg}\"\n            )\n\n        self.logger.info(\n            f\"Job Run logs can be found on GCP at: {job_execution.log_uri}\"\n        )\n\n        if not self.keep_job:\n            self.logger.info(\n                f\"Deleting completed Cloud Run Job {self.job_name!r} from Google Cloud\"\n                \" Run...\"\n            )\n            try:\n                Job.delete(\n                    client=client,\n                    namespace=self.credentials.project,\n                    job_name=self.job_name,\n                )\n            except Exception:\n                self.logger.exception(\n                    \"Received an unexpected exception while attempting to delete Cloud\"\n                    f\" Run Job {self.job_name}\"\n                )\n\n        return CloudRunJobResult(identifier=self.job_name, status_code=status_code)\n\n    def _jobs_body(self) -&gt; dict:\n        \"\"\"Create properly formatted body used for a Job CREATE request.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs\n        \"\"\"\n        jobs_metadata = {\"name\": self.job_name}\n\n        annotations = {\n            # See: https://cloud.google.com/run/docs/troubleshooting#launch-stage-validation  # noqa\n            \"run.googleapis.com/launch-stage\": \"BETA\",\n        }\n        # add vpc connector if specified\n        if self.vpc_connector_name:\n            annotations[\n                \"run.googleapis.com/vpc-access-connector\"\n            ] = self.vpc_connector_name\n\n        # env and command here\n        containers = [self._add_container_settings({\"image\": self.image})]\n\n        # apply this timeout to each task\n        timeout_seconds = str(self.timeout)\n\n        body = {\n            \"apiVersion\": \"run.googleapis.com/v1\",\n            \"kind\": \"Job\",\n            \"metadata\": jobs_metadata,\n            \"spec\": {  # JobSpec\n                \"template\": {  # ExecutionTemplateSpec\n                    \"metadata\": {\"annotations\": annotations},\n                    \"spec\": {  # ExecutionSpec\n                        \"template\": {  # TaskTemplateSpec\n                            \"spec\": {\n                                \"containers\": containers,\n                                \"timeoutSeconds\": timeout_seconds,\n                                \"maxRetries\": self.max_retries,\n                            }  # TaskSpec\n                        }\n                    },\n                }\n            },\n        }\n        return body\n\n    def preview(self) -&gt; str:\n        \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n        body = self._jobs_body()\n        container_settings = body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n            \"containers\"\n        ][0][\"env\"]\n        body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n            container_setting\n            for container_setting in container_settings\n            if container_setting[\"name\"] != \"PREFECT_API_KEY\"\n        ]\n        return json.dumps(body, indent=2)\n\n    def _watch_job_execution(\n        self, client, job_execution: Execution, timeout: int, poll_interval: int = 5\n    ):\n        \"\"\"\n        Update job_execution status until it is no longer running or timeout is reached.\n        \"\"\"\n        t0 = time.time()\n        while job_execution.is_running():\n            job_execution = Execution.get(\n                client=client,\n                namespace=job_execution.namespace,\n                execution_name=job_execution.name,\n            )\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while waiting for Cloud Run Job \"\n                    \"execution to complete. Your job may still be running on GCP.\"\n                )\n\n            time.sleep(poll_interval)\n\n        return job_execution\n\n    def _wait_for_job_creation(\n        self, client: Resource, timeout: int, poll_interval: int = 5\n    ):\n        \"\"\"Give created job time to register.\"\"\"\n        job = Job.get(\n            client=client, namespace=self.credentials.project, job_name=self.job_name\n        )\n\n        t0 = time.time()\n        while not job.is_ready():\n            ready_condition = (\n                job.ready_condition\n                if job.ready_condition\n                else \"waiting for condition update\"\n            )\n            self.logger.info(\n                f\"Job is not yet ready... Current condition: {ready_condition}\"\n            )\n            job = Job.get(\n                client=client,\n                namespace=self.credentials.project,\n                job_name=self.job_name,\n            )\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while waiting for Cloud Run Job \"\n                    \"execution to complete. Your job may still be running on GCP.\"\n                )\n\n            time.sleep(poll_interval)\n\n    def _get_client(self) -&gt; Resource:\n        \"\"\"Get the base client needed for interacting with GCP APIs.\"\"\"\n        # region needed for 'v1' API\n        api_endpoint = f\"https://{self.region}-run.googleapis.com\"\n        gcp_creds = self.credentials.get_credentials_from_service_account()\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return discovery.build(\n            \"run\", \"v1\", client_options=options, credentials=gcp_creds\n        ).namespaces()\n\n    # CONTAINER SETTINGS\n    def _add_container_settings(self, base_settings: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Add settings related to containers for Cloud Run Jobs to a dictionary.\n        Includes environment variables, entrypoint command, entrypoint arguments,\n        and cpu and memory limits.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        and https://cloud.google.com/run/docs/reference/rest/v1/Container#ResourceRequirements\n        \"\"\"  # noqa\n        container_settings = base_settings.copy()\n        container_settings.update(self._add_env())\n        container_settings.update(self._add_resources())\n        container_settings.update(self._add_command())\n        container_settings.update(self._add_args())\n        return container_settings\n\n    def _add_args(self) -&gt; dict:\n        \"\"\"Set the arguments that will be passed to the entrypoint for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        \"\"\"  # noqa\n        return {\"args\": self.args} if self.args else {}\n\n    def _add_command(self) -&gt; dict:\n        \"\"\"Set the command that a container will run for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container\n        \"\"\"  # noqa\n        return {\"command\": self.command}\n\n    def _add_resources(self) -&gt; dict:\n        \"\"\"Set specified resources limits for a Cloud Run Job.\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container#ResourceRequirements\n        See also: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/\n        \"\"\"  # noqa\n        resources = {\"limits\": {}, \"requests\": {}}\n\n        if self.cpu is not None:\n            cpu = self._cpu_as_k8s_quantity()\n            resources[\"limits\"][\"cpu\"] = cpu\n            resources[\"requests\"][\"cpu\"] = cpu\n        if self.memory_string is not None:\n            resources[\"limits\"][\"memory\"] = self.memory_string\n            resources[\"requests\"][\"memory\"] = self.memory_string\n\n        return {\"resources\": resources} if resources[\"requests\"] else {}\n\n    def _add_env(self) -&gt; dict:\n        \"\"\"Add environment variables for a Cloud Run Job.\n\n        Method `self._base_environment()` gets necessary Prefect environment variables\n        from the config.\n\n        See: https://cloud.google.com/run/docs/reference/rest/v1/Container#envvar for\n        how environment variables are specified for Cloud Run Jobs.\n        \"\"\"  # noqa\n        env = {**self._base_environment(), **self.env}\n        cloud_run_env = [{\"name\": k, \"value\": v} for k, v in env.items()]\n        return {\"env\": cloud_run_env}\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.job_name","title":"<code>job_name</code>  <code>property</code>","text":"<p>Create a unique and valid job name.</p>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.memory_string","title":"<code>memory_string</code>  <code>property</code>","text":"<p>Returns the string expected for memory resources argument.</p>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.generate_work_pool_base_job_template","title":"<code>generate_work_pool_base_job_template</code>  <code>async</code>","text":"<p>Generate a base job template for a cloud-run work pool with the same configuration as this block.</p> <p>Returns:</p> Type Description <code>dict</code> <ul> <li>dict: a base job template for a cloud-run work pool</li> </ul> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>async def generate_work_pool_base_job_template(self) -&gt; dict:\n    \"\"\"\n    Generate a base job template for a cloud-run work pool with the same\n    configuration as this block.\n\n    Returns:\n        - dict: a base job template for a cloud-run work pool\n    \"\"\"\n    base_job_template = await get_default_base_job_template_for_infrastructure_type(\n        self.get_corresponding_worker_type(),\n    )\n    assert (\n        base_job_template is not None\n    ), \"Failed to generate default base job template for Cloud Run worker.\"\n    for key, value in self.dict(exclude_unset=True, exclude_defaults=True).items():\n        if key == \"command\":\n            base_job_template[\"variables\"][\"properties\"][\"command\"][\n                \"default\"\n            ] = shlex.join(value)\n        elif key in [\n            \"type\",\n            \"block_type_slug\",\n            \"_block_document_id\",\n            \"_block_document_name\",\n            \"_is_anonymous\",\n            \"memory_unit\",\n        ]:\n            continue\n        elif key == \"credentials\":\n            if not self.credentials._block_document_id:\n                raise BlockNotSavedError(\n                    \"It looks like you are trying to use a block that\"\n                    \" has not been saved. Please call `.save` on your block\"\n                    \" before publishing it as a work pool.\"\n                )\n            base_job_template[\"variables\"][\"properties\"][\"credentials\"][\n                \"default\"\n            ] = {\n                \"$ref\": {\n                    \"block_document_id\": str(self.credentials._block_document_id)\n                }\n            }\n        elif key == \"memory\" and self.memory_string:\n            base_job_template[\"variables\"][\"properties\"][\"memory\"][\n                \"default\"\n            ] = self.memory_string\n        elif key == \"cpu\" and self.cpu is not None:\n            base_job_template[\"variables\"][\"properties\"][\"cpu\"][\n                \"default\"\n            ] = f\"{self.cpu * 1000}m\"\n        elif key == \"args\":\n            # Not a default variable, but we can add it to the template\n            base_job_template[\"variables\"][\"properties\"][\"args\"] = {\n                \"title\": \"Arguments\",\n                \"type\": \"string\",\n                \"description\": \"Arguments to be passed to your Cloud Run Job's entrypoint command.\",  # noqa\n                \"default\": value,\n            }\n            base_job_template[\"job_configuration\"][\"job_body\"][\"spec\"][\"template\"][\n                \"spec\"\n            ][\"template\"][\"spec\"][\"containers\"][0][\"args\"] = \"{{ args }}\"\n        elif key in base_job_template[\"variables\"][\"properties\"]:\n            base_job_template[\"variables\"][\"properties\"][key][\"default\"] = value\n        else:\n            self.logger.warning(\n                f\"Variable {key!r} is not supported by Cloud Run work pools.\"\n                \" Skipping.\"\n            )\n\n    return base_job_template\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.get_corresponding_worker_type","title":"<code>get_corresponding_worker_type</code>","text":"<p>Return the corresponding worker type for this infrastructure block.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def get_corresponding_worker_type(self) -&gt; str:\n    \"\"\"Return the corresponding worker type for this infrastructure block.\"\"\"\n    return \"cloud-run\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.kill","title":"<code>kill</code>  <code>async</code>","text":"<p>Kill a task running Cloud Run.</p> <p>Parameters:</p> Name Type Description Default <code>identifier</code> <code>str</code> <p>The Cloud Run Job name. This should match a value yielded by CloudRunJob.run.</p> required Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@sync_compatible\nasync def kill(self, identifier: str, grace_seconds: int = 30) -&gt; None:\n    \"\"\"\n    Kill a task running Cloud Run.\n\n    Args:\n        identifier: The Cloud Run Job name. This should match a\n            value yielded by CloudRunJob.run.\n    \"\"\"\n    if grace_seconds != 30:\n        self.logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client() as client:\n        await run_sync_in_worker_thread(\n            self._kill_job,\n            client=client,\n            namespace=self.credentials.project,\n            job_name=identifier,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.preview","title":"<code>preview</code>","text":"<p>Generate a preview of the job definition that will be sent to GCP.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def preview(self) -&gt; str:\n    \"\"\"Generate a preview of the job definition that will be sent to GCP.\"\"\"\n    body = self._jobs_body()\n    container_settings = body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n        \"containers\"\n    ][0][\"env\"]\n    body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n        container_setting\n        for container_setting in container_settings\n        if container_setting[\"name\"] != \"PREFECT_API_KEY\"\n    ]\n    return json.dumps(body, indent=2)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJob.run","title":"<code>run</code>  <code>async</code>","text":"<p>Run the configured job on a Google Cloud Run Job.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@sync_compatible\nasync def run(self, task_status: Optional[TaskStatus] = None):\n    \"\"\"Run the configured job on a Google Cloud Run Job.\"\"\"\n    with self._get_client() as client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration, client\n        )\n        job_execution = await run_sync_in_worker_thread(\n            self._begin_job_execution, client\n        )\n\n        if task_status:\n            task_status.started(self.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            client,\n            job_execution,\n            5,\n        )\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.CloudRunJobResult","title":"<code>CloudRunJobResult</code>","text":"<p>               Bases: <code>InfrastructureResult</code></p> <p>Result from a Cloud Run Job.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class CloudRunJobResult(InfrastructureResult):\n    \"\"\"Result from a Cloud Run Job.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution","title":"<code>Execution</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Utility class to call GCP <code>executions</code> API and interact with the returned objects.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class Execution(BaseModel):\n    \"\"\"\n    Utility class to call GCP `executions` API and\n    interact with the returned objects.\n    \"\"\"\n\n    name: str\n    namespace: str\n    metadata: dict\n    spec: dict\n    status: dict\n    log_uri: str\n\n    def is_running(self) -&gt; bool:\n        \"\"\"Returns True if Execution is not completed.\"\"\"\n        return self.status.get(\"completionTime\") is None\n\n    def condition_after_completion(self):\n        \"\"\"Returns Execution condition if Execution has completed.\"\"\"\n        for condition in self.status[\"conditions\"]:\n            if condition[\"type\"] == \"Completed\":\n                return condition\n\n    def succeeded(self):\n        \"\"\"Whether or not the Execution completed is a successful state.\"\"\"\n        completed_condition = self.condition_after_completion()\n        if completed_condition and completed_condition[\"status\"] == \"True\":\n            return True\n\n        return False\n\n    @classmethod\n    def get(cls, client: Resource, namespace: str, execution_name: str):\n        \"\"\"\n        Make a get request to the GCP executions API\n        and return an Execution instance.\n        \"\"\"\n        request = client.executions().get(\n            name=f\"namespaces/{namespace}/executions/{execution_name}\"\n        )\n        response = request.execute()\n\n        return cls(\n            name=response[\"metadata\"][\"name\"],\n            namespace=response[\"metadata\"][\"namespace\"],\n            metadata=response[\"metadata\"],\n            spec=response[\"spec\"],\n            status=response[\"status\"],\n            log_uri=response[\"status\"][\"logUri\"],\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.condition_after_completion","title":"<code>condition_after_completion</code>","text":"<p>Returns Execution condition if Execution has completed.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def condition_after_completion(self):\n    \"\"\"Returns Execution condition if Execution has completed.\"\"\"\n    for condition in self.status[\"conditions\"]:\n        if condition[\"type\"] == \"Completed\":\n            return condition\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.get","title":"<code>get</code>  <code>classmethod</code>","text":"<p>Make a get request to the GCP executions API and return an Execution instance.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@classmethod\ndef get(cls, client: Resource, namespace: str, execution_name: str):\n    \"\"\"\n    Make a get request to the GCP executions API\n    and return an Execution instance.\n    \"\"\"\n    request = client.executions().get(\n        name=f\"namespaces/{namespace}/executions/{execution_name}\"\n    )\n    response = request.execute()\n\n    return cls(\n        name=response[\"metadata\"][\"name\"],\n        namespace=response[\"metadata\"][\"namespace\"],\n        metadata=response[\"metadata\"],\n        spec=response[\"spec\"],\n        status=response[\"status\"],\n        log_uri=response[\"status\"][\"logUri\"],\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.is_running","title":"<code>is_running</code>","text":"<p>Returns True if Execution is not completed.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def is_running(self) -&gt; bool:\n    \"\"\"Returns True if Execution is not completed.\"\"\"\n    return self.status.get(\"completionTime\") is None\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Execution.succeeded","title":"<code>succeeded</code>","text":"<p>Whether or not the Execution completed is a successful state.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def succeeded(self):\n    \"\"\"Whether or not the Execution completed is a successful state.\"\"\"\n    completed_condition = self.condition_after_completion()\n    if completed_condition and completed_condition[\"status\"] == \"True\":\n        return True\n\n    return False\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job","title":"<code>Job</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Utility class to call GCP <code>jobs</code> API and interact with the returned objects.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>class Job(BaseModel):\n    \"\"\"\n    Utility class to call GCP `jobs` API and\n    interact with the returned objects.\n    \"\"\"\n\n    metadata: dict\n    spec: dict\n    status: dict\n    name: str\n    ready_condition: dict\n    execution_status: dict\n\n    def _is_missing_container(self):\n        \"\"\"\n        Check if Job status is not ready because\n        the specified container cannot be found.\n        \"\"\"\n        if (\n            self.ready_condition.get(\"status\") == \"False\"\n            and self.ready_condition.get(\"reason\") == \"ContainerMissing\"\n        ):\n            return True\n        return False\n\n    def is_ready(self) -&gt; bool:\n        \"\"\"Whether a job is finished registering and ready to be executed\"\"\"\n        if self._is_missing_container():\n            raise Exception(f\"{self.ready_condition['message']}\")\n        return self.ready_condition.get(\"status\") == \"True\"\n\n    def has_execution_in_progress(self) -&gt; bool:\n        \"\"\"See if job has a run in progress.\"\"\"\n        return (\n            self.execution_status == {}\n            or self.execution_status.get(\"completionTimestamp\") is None\n        )\n\n    @staticmethod\n    def _get_ready_condition(job: dict) -&gt; dict:\n        \"\"\"Utility to access JSON field containing ready condition.\"\"\"\n        if job[\"status\"].get(\"conditions\"):\n            for condition in job[\"status\"][\"conditions\"]:\n                if condition[\"type\"] == \"Ready\":\n                    return condition\n\n        return {}\n\n    @staticmethod\n    def _get_execution_status(job: dict):\n        \"\"\"Utility to access JSON field containing execution status.\"\"\"\n        if job[\"status\"].get(\"latestCreatedExecution\"):\n            return job[\"status\"][\"latestCreatedExecution\"]\n\n        return {}\n\n    @classmethod\n    def get(cls, client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a get request to the GCP jobs API and return a Job instance.\"\"\"\n        request = client.jobs().get(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n\n        return cls(\n            metadata=response[\"metadata\"],\n            spec=response[\"spec\"],\n            status=response[\"status\"],\n            name=response[\"metadata\"][\"name\"],\n            ready_condition=cls._get_ready_condition(response),\n            execution_status=cls._get_execution_status(response),\n        )\n\n    @staticmethod\n    def create(client: Resource, namespace: str, body: dict):\n        \"\"\"Make a create request to the GCP jobs API.\"\"\"\n        request = client.jobs().create(parent=f\"namespaces/{namespace}\", body=body)\n        response = request.execute()\n        return response\n\n    @staticmethod\n    def delete(client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a delete request to the GCP jobs API.\"\"\"\n        request = client.jobs().delete(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n        return response\n\n    @staticmethod\n    def run(client: Resource, namespace: str, job_name: str):\n        \"\"\"Make a run request to the GCP jobs API.\"\"\"\n        request = client.jobs().run(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n        response = request.execute()\n        return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.create","title":"<code>create</code>  <code>staticmethod</code>","text":"<p>Make a create request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef create(client: Resource, namespace: str, body: dict):\n    \"\"\"Make a create request to the GCP jobs API.\"\"\"\n    request = client.jobs().create(parent=f\"namespaces/{namespace}\", body=body)\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.delete","title":"<code>delete</code>  <code>staticmethod</code>","text":"<p>Make a delete request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef delete(client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a delete request to the GCP jobs API.\"\"\"\n    request = client.jobs().delete(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.get","title":"<code>get</code>  <code>classmethod</code>","text":"<p>Make a get request to the GCP jobs API and return a Job instance.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@classmethod\ndef get(cls, client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a get request to the GCP jobs API and return a Job instance.\"\"\"\n    request = client.jobs().get(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n\n    return cls(\n        metadata=response[\"metadata\"],\n        spec=response[\"spec\"],\n        status=response[\"status\"],\n        name=response[\"metadata\"][\"name\"],\n        ready_condition=cls._get_ready_condition(response),\n        execution_status=cls._get_execution_status(response),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.has_execution_in_progress","title":"<code>has_execution_in_progress</code>","text":"<p>See if job has a run in progress.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def has_execution_in_progress(self) -&gt; bool:\n    \"\"\"See if job has a run in progress.\"\"\"\n    return (\n        self.execution_status == {}\n        or self.execution_status.get(\"completionTimestamp\") is None\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.is_ready","title":"<code>is_ready</code>","text":"<p>Whether a job is finished registering and ready to be executed</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>def is_ready(self) -&gt; bool:\n    \"\"\"Whether a job is finished registering and ready to be executed\"\"\"\n    if self._is_missing_container():\n        raise Exception(f\"{self.ready_condition['message']}\")\n    return self.ready_condition.get(\"status\") == \"True\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run/#prefect_gcp.cloud_run.Job.run","title":"<code>run</code>  <code>staticmethod</code>","text":"<p>Make a run request to the GCP jobs API.</p> Source code in <code>prefect_gcp/cloud_run.py</code> <pre><code>@staticmethod\ndef run(client: Resource, namespace: str, job_name: str):\n    \"\"\"Make a run request to the GCP jobs API.\"\"\"\n    request = client.jobs().run(name=f\"namespaces/{namespace}/jobs/{job_name}\")\n    response = request.execute()\n    return response\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/","title":"Cloud Run","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run","title":"<code>prefect_gcp.workers.cloud_run</code>","text":"<p>Module containing the Cloud Run worker used for executing flow runs as Cloud Run jobs.</p> <p>Get started by creating a Cloud Run work pool:</p> <pre><code>prefect work-pool create 'my-cloud-run-pool' --type cloud-run\n</code></pre> <p>Then start a Cloud Run worker with the following command:</p> <pre><code>prefect worker start --pool 'my-cloud-run-pool'\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--configuration","title":"Configuration","text":"<p>Read more about configuring work pools here.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--advanced-configuration","title":"Advanced Configuration","text":"<p>Using a custom Cloud Run job template</p> <p>Below is the default job body template used by the Cloud Run Worker: <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"metadata\":\n        {\n            \"name\": \"{{ name }}\",\n            \"annotations\":\n            {\n                \"run.googleapis.com/launch-stage\": \"BETA\",\n            }\n        },\n        \"spec\":\n        {\n            \"template\":\n            {\n                \"spec\":\n                {\n                    \"template\":\n                    {\n                        \"spec\":\n                        {\n                            \"containers\":\n                            [\n                                {\n                                    \"image\": \"{{ image }}\",\n                                    \"args\": \"{{ args }}\",\n                                    \"resources\":\n                                    {\n                                        \"limits\":\n                                        {\n                                            \"cpu\": \"{{ cpu }}\",\n                                            \"memory\": \"{{ memory }}\"\n                                        },\n                                        \"requests\":\n                                        {\n                                            \"cpu\": \"{{ cpu }}\",\n                                            \"memory\": \"{{ memory }}\"\n                                        }\n                                    }\n                                }\n                            ],\n                            \"timeoutSeconds\": \"{{ timeout }}\",\n                            \"serviceAccountName\": \"{{ service_account_name }}\"\n                        }\n                    }\n                }\n                }\n            },\n            \"metadata\":\n            {\n                \"annotations\":\n                {\n                    \"run.googleapis.com/vpc-access-connector\": \"{{ vpc_connector_name }}\"\n                }\n            }\n        },\n    },\n    \"keep_job\": \"{{ keep_job }}\"\n}\n</code></pre> Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime on a per-deployment basis. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job body template and available variables can be customized on a work pool by work pool basis. By editing the default job body template you can:</p> <ul> <li>Add additional placeholders to the default job template</li> <li>Remove placeholders from the default job template</li> <li>Pass values to Cloud Run that are not defined in the <code>variables</code> schema</li> </ul>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run--adding-additional-placeholders","title":"Adding additional placeholders","text":"<p>For example, to allow for extra customization of a new annotation not described in the default job template, you can add the following: <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"metadata\":\n    {\n        \"name\": \"{{ name }}\",\n        \"annotations\":\n        {\n            \"run.googleapis.com/my-custom-annotation\": \"{{ my_custom_annotation }}\",\n            \"run.googleapis.com/launch-stage\": \"BETA\",\n        },\n      ...\n    },\n  ...\n}\n</code></pre> <code>my_custom_annotation</code> can now be used as a placeholder in the job template and set on a per-deployment basis.</p> <pre><code># deployment.yaml\n...\ninfra_overrides: {\"my_custom_annotation\": \"my-custom-value\"}\n</code></pre> <p>Additionally, fields can be set to prevent configuration at the deployment level. For example to configure the <code>vpc_connector_name</code> field, the placeholder can be removed and replaced with an actual value. Now all deployments that point to this work pool will use the same <code>vpc_connector_name</code> value.</p> <pre><code>{\n    \"apiVersion\": \"run.googleapis.com/v1\",\n    \"kind\": \"Job\",\n    \"spec\":\n    {\n        \"template\":\n        {\n            \"metadata\":\n            {\n                \"annotations\":\n                {\n                    \"run.googleapis.com/vpc-access-connector\": \"my-vpc-connector\"\n                }\n            },\n            ...\n        },\n        ...\n    }\n}\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker","title":"<code>CloudRunWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Cloud Run Jobs.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Cloud Run Jobs.\"\"\"\n\n    type = \"cloud-run\"\n    job_configuration = CloudRunWorkerJobConfiguration\n    job_configuration_variables = CloudRunWorkerVariables\n    _description = (\n        \"Execute flow runs within containers on Google Cloud Run. Requires \"\n        \"a Google Cloud Platform account.\"\n    )\n    _display_name = \"Google Cloud Run\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_run_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n\n    def _create_job_error(self, exc, configuration):\n        \"\"\"Provides a nicer error for 404s when trying to create a Cloud Run Job.\"\"\"\n        # TODO consider lookup table instead of the if/else,\n        # also check for documented errors\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{self.region}' is the correct region for your Cloud Run Job and\"\n                f\" that {configuration.project} is the correct GCP project. If\"\n                f\" your project ID is not correct, you are using a Credentials block\"\n                f\" with permissions for the wrong project.\"\n            ) from exc\n        raise exc\n\n    def _job_run_submission_error(self, exc, configuration):\n        \"\"\"Provides a nicer error for 404s when submitting job runs.\"\"\"\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n            # pat2 = (\n            #     r\"Resource '[^ ]+' of kind 'JOB' in region '[\\w\\-0-9]+' \"\n            #     r\"in project '[\\w\\-0-9]+' does not exist\"\n            # )\n            if re.findall(pat1, str(exc)):\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{self.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{configuration.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n        raise exc\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: CloudRunWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; CloudRunWorkerResult:\n        \"\"\"\n        Executes a flow run within a Cloud Run Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            CloudRunWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n\n        logger = self.get_flow_run_logger(flow_run)\n\n        with self._get_client(configuration) as client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration,\n                configuration,\n                client,\n                logger,\n            )\n            job_execution = await run_sync_in_worker_thread(\n                self._begin_job_execution, configuration, client, logger\n            )\n\n            if task_status:\n                task_status.started(configuration.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                configuration,\n                client,\n                job_execution,\n                logger,\n            )\n            return result\n\n    def _get_client(self, configuration: CloudRunWorkerJobConfiguration) -&gt; Resource:\n        \"\"\"Get the base client needed for interacting with GCP APIs.\"\"\"\n        # region needed for 'v1' API\n        api_endpoint = f\"https://{configuration.region}-run.googleapis.com\"\n        gcp_creds = configuration.credentials.get_credentials_from_service_account()\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return discovery.build(\n            \"run\", \"v1\", client_options=options, credentials=gcp_creds\n        ).namespaces()\n\n    def _create_job_and_wait_for_registration(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        logger: PrefectLogAdapter,\n    ) -&gt; None:\n        \"\"\"Create a new job wait for it to finish registering.\"\"\"\n        try:\n            logger.info(f\"Creating Cloud Run Job {configuration.job_name}\")\n\n            Job.create(\n                client=client,\n                namespace=configuration.credentials.project,\n                body=configuration.job_body,\n            )\n        except googleapiclient.errors.HttpError as exc:\n            self._create_job_error(exc, configuration)\n\n        try:\n            self._wait_for_job_creation(\n                client=client, configuration=configuration, logger=logger\n            )\n        except Exception:\n            logger.exception(\n                \"Encountered an exception while waiting for job run creation\"\n            )\n            if not configuration.keep_job:\n                logger.info(\n                    f\"Deleting Cloud Run Job {configuration.job_name} from \"\n                    \"Google Cloud Run.\"\n                )\n                try:\n                    Job.delete(\n                        client=client,\n                        namespace=configuration.credentials.project,\n                        job_name=configuration.job_name,\n                    )\n                except Exception:\n                    logger.exception(\n                        \"Received an unexpected exception while attempting to delete\"\n                        f\" Cloud Run Job {configuration.job_name!r}\"\n                    )\n            raise\n\n    def _begin_job_execution(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        logger: PrefectLogAdapter,\n    ) -&gt; Execution:\n        \"\"\"Submit a job run for execution and return the execution object.\"\"\"\n        try:\n            logger.info(\n                f\"Submitting Cloud Run Job {configuration.job_name!r} for execution.\"\n            )\n            submission = Job.run(\n                client=client,\n                namespace=configuration.project,\n                job_name=configuration.job_name,\n            )\n\n            job_execution = Execution.get(\n                client=client,\n                namespace=submission[\"metadata\"][\"namespace\"],\n                execution_name=submission[\"metadata\"][\"name\"],\n            )\n        except Exception as exc:\n            self._job_run_submission_error(exc, configuration)\n\n        return job_execution\n\n    def _watch_job_execution_and_get_result(\n        self,\n        configuration: CloudRunWorkerJobConfiguration,\n        client: Resource,\n        execution: Execution,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ) -&gt; CloudRunWorkerResult:\n        \"\"\"Wait for execution to complete and then return result.\"\"\"\n        try:\n            job_execution = self._watch_job_execution(\n                client=client,\n                job_execution=execution,\n                poll_interval=poll_interval,\n            )\n        except Exception:\n            logger.exception(\n                \"Received an unexpected exception while monitoring Cloud Run Job \"\n                f\"{configuration.job_name!r}\"\n            )\n            raise\n\n        if job_execution.succeeded():\n            status_code = 0\n            logger.info(f\"Job Run {configuration.job_name} completed successfully\")\n        else:\n            status_code = 1\n            error_msg = job_execution.condition_after_completion()[\"message\"]\n            logger.error(\n                f\"Job Run {configuration.job_name} did not complete successfully. \"\n                f\"{error_msg}\"\n            )\n\n        logger.info(f\"Job Run logs can be found on GCP at: {job_execution.log_uri}\")\n\n        if not configuration.keep_job:\n            logger.info(\n                f\"Deleting completed Cloud Run Job {configuration.job_name!r} \"\n                \"from Google Cloud Run...\"\n            )\n            try:\n                Job.delete(\n                    client=client,\n                    namespace=configuration.project,\n                    job_name=configuration.job_name,\n                )\n            except Exception:\n                logger.exception(\n                    \"Received an unexpected exception while attempting to delete Cloud\"\n                    f\" Run Job {configuration.job_name}\"\n                )\n\n        return CloudRunWorkerResult(\n            identifier=configuration.job_name, status_code=status_code\n        )\n\n    def _watch_job_execution(\n        self, client, job_execution: Execution, poll_interval: int = 5\n    ):\n        \"\"\"\n        Update job_execution status until it is no longer running.\n        \"\"\"\n        while job_execution.is_running():\n            job_execution = Execution.get(\n                client=client,\n                namespace=job_execution.namespace,\n                execution_name=job_execution.name,\n            )\n\n            time.sleep(poll_interval)\n\n        return job_execution\n\n    def _wait_for_job_creation(\n        self,\n        client: Resource,\n        configuration: CloudRunWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ):\n        \"\"\"Give created job time to register.\"\"\"\n        job = Job.get(\n            client=client,\n            namespace=configuration.project,\n            job_name=configuration.job_name,\n        )\n\n        while not job.is_ready():\n            ready_condition = (\n                job.ready_condition\n                if job.ready_condition\n                else \"waiting for condition update\"\n            )\n            logger.info(f\"Job is not yet ready... Current condition: {ready_condition}\")\n            job = Job.get(\n                client=client,\n                namespace=configuration.project,\n                job_name=configuration.job_name,\n            )\n\n            time.sleep(poll_interval)\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: CloudRunWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a job for a cancelled flow run based on the provided infrastructure PID\n        and run configuration.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client(configuration) as client:\n            await run_sync_in_worker_thread(\n                self._stop_job,\n                client=client,\n                namespace=configuration.project,\n                job_name=infrastructure_pid,\n            )\n\n    def _stop_job(self, client: Resource, namespace: str, job_name: str):\n        try:\n            Job.delete(client=client, namespace=namespace, job_name=job_name)\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a job for a cancelled flow run based on the provided infrastructure PID and run configuration.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: CloudRunWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a job for a cancelled flow run based on the provided infrastructure PID\n    and run configuration.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client(configuration) as client:\n        await run_sync_in_worker_thread(\n            self._stop_job,\n            client=client,\n            namespace=configuration.project,\n            job_name=infrastructure_pid,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Cloud Run Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>CloudRunWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>CloudRunWorkerResult</code> <code>CloudRunWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: CloudRunWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; CloudRunWorkerResult:\n    \"\"\"\n    Executes a flow run within a Cloud Run Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        CloudRunWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n\n    logger = self.get_flow_run_logger(flow_run)\n\n    with self._get_client(configuration) as client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration,\n            configuration,\n            client,\n            logger,\n        )\n        job_execution = await run_sync_in_worker_thread(\n            self._begin_job_execution, configuration, client, logger\n        )\n\n        if task_status:\n            task_status.started(configuration.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            configuration,\n            client,\n            job_execution,\n            logger,\n        )\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration","title":"<code>CloudRunWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Cloud Run Worker to create a Cloud Run Job.</p> <p>An instance of this class is passed to the Cloud Run worker's <code>run</code> method for each flow run. It contains all information necessary to execute the flow run as a Cloud Run Job.</p> <p>Attributes:</p> Name Type Description <code>region</code> <code>str</code> <p>The region where the Cloud Run Job resides.</p> <code>credentials</code> <code>Optional[GcpCredentials]</code> <p>The GCP Credentials used to connect to Cloud Run.</p> <code>job_body</code> <code>Dict[str, Any]</code> <p>The job body used to create the Cloud Run Job.</p> <code>timeout</code> <code>Optional[int]</code> <p>Max allowed duration the job may be active before Cloud Run will actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).</p> <code>keep_job</code> <code>Optional[bool]</code> <p>Whether to delete the Cloud Run Job after it completes.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Cloud Run Worker to create a Cloud Run Job.\n\n    An instance of this class is passed to the Cloud Run worker's `run` method\n    for each flow run. It contains all information necessary to execute\n    the flow run as a Cloud Run Job.\n\n    Attributes:\n        region: The region where the Cloud Run Job resides.\n        credentials: The GCP Credentials used to connect to Cloud Run.\n        job_body: The job body used to create the Cloud Run Job.\n        timeout: Max allowed duration the job may be active before Cloud Run\n            will actively try to mark it failed and kill associated containers\n            (maximum of 3600 seconds, 1 hour).\n        keep_job: Whether to delete the Cloud Run Job after it completes.\n    \"\"\"\n\n    region: str = Field(\n        default=\"us-central1\", description=\"The region where the Cloud Run Job resides.\"\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to connect to Cloud Run. \"\n        \"If not provided credentials will be inferred from \"\n        \"the local environment.\",\n    )\n    job_body: Dict[str, Any] = Field(template=_get_default_job_body_template())\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the Job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).\"\n        ),\n    )\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job on Google Cloud Platform.\",\n    )\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"property for accessing the project from the credentials.\"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"property for accessing the name from the job metadata.\"\"\"\n        return self.job_body[\"metadata\"][\"name\"]\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job body and that the\n        job body is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self._populate_envs()\n        self._populate_or_format_command()\n        self._format_args_if_present()\n        self._populate_image_if_not_present()\n        self._populate_name_if_not_present()\n\n    def _populate_envs(self):\n        \"\"\"Populate environment variables. BaseWorker.prepare_for_flow_run handles\n        putting the environment variables in the `env` attribute. This method\n        moves them into the jobs body\"\"\"\n        envs = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n        self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n            \"env\"\n        ] = envs\n\n    def _populate_name_if_not_present(self):\n        \"\"\"Adds the flow run name to the job if one is not already provided.\"\"\"\n        try:\n            if \"name\" not in self.job_body[\"metadata\"]:\n                base_job_name = slugify_name(self.name)\n                job_name = f\"{base_job_name}-{uuid4().hex}\"\n                self.job_body[\"metadata\"][\"name\"] = job_name\n        except KeyError:\n            raise ValueError(\"Unable to verify name due to invalid job body template.\")\n\n    def _populate_image_if_not_present(self):\n        \"\"\"Adds the latest prefect image to the job if one is not already provided.\"\"\"\n        try:\n            if (\n                \"image\"\n                not in self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0]\n            ):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"image\"] = f\"docker.io/{get_prefect_image_name()}\"\n        except KeyError:\n            raise ValueError(\"Unable to verify image due to invalid job body template.\")\n\n    def _populate_or_format_command(self):\n        \"\"\"\n        Ensures that the command is present in the job manifest. Populates the command\n        with the `prefect -m prefect.engine` if a command is not present.\n        \"\"\"\n        try:\n            command = self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                \"containers\"\n            ][0].get(\"command\")\n            if command is None:\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"command\"] = shlex.split(self._base_flow_run_command())\n            elif isinstance(command, str):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"command\"] = shlex.split(command)\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify command due to invalid job body template.\"\n            )\n\n    def _format_args_if_present(self):\n        try:\n            args = self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                \"containers\"\n            ][0].get(\"args\")\n            if args is not None and isinstance(args, str):\n                self.job_body[\"spec\"][\"template\"][\"spec\"][\"template\"][\"spec\"][\n                    \"containers\"\n                ][0][\"args\"] = shlex.split(args)\n        except KeyError:\n            raise ValueError(\"Unable to verify args due to invalid job body template.\")\n\n    @validator(\"job_body\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job body includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n\n    @validator(\"job_body\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        \"\"\"Ensure that the job body has compatible values.\"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>property for accessing the name from the job metadata.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>property for accessing the project from the credentials.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job body and that the job body is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job body and that the\n    job body is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n\n    self._populate_envs()\n    self._populate_or_format_command()\n    self._format_args_if_present()\n    self._populate_image_if_not_present()\n    self._populate_name_if_not_present()\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerResult","title":"<code>CloudRunWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker/#prefect_gcp.workers.cloud_run.CloudRunWorkerVariables","title":"<code>CloudRunWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Cloud Run worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run.py</code> <pre><code>class CloudRunWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Cloud Run worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region where the Cloud Run Job resides.\",\n        example=\"us-central1\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Cloud Run Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n    image: Optional[str] = Field(\n        default=None,\n        title=\"Image Name\",\n        description=(\n            \"The image to use for a new Cloud Run Job. \"\n            \"If not set, the latest Prefect image will be used. \"\n            \"See https://cloud.google.com/run/docs/deploying#images.\"\n        ),\n        example=\"docker.io/prefecthq/prefect:2-latest\",\n    )\n    cpu: Optional[str] = Field(\n        default=None,\n        title=\"CPU\",\n        description=(\n            \"The amount of compute allocated to the Cloud Run Job. \"\n            \"(1000m = 1 CPU). See \"\n            \"https://cloud.google.com/run/docs/configuring/cpu#setting-jobs.\"\n        ),\n        example=\"1000m\",\n        regex=r\"^(\\d*000)m$\",\n    )\n    memory: Optional[str] = Field(\n        default=None,\n        title=\"Memory\",\n        description=(\n            \"The amount of memory allocated to the Cloud Run Job. \"\n            \"Must be specified in units of 'G', 'Gi', 'M', or 'Mi'. \"\n            \"See https://cloud.google.com/run/docs/configuring/memory-limits#setting.\"\n        ),\n        example=\"512Mi\",\n        regex=r\"^\\d+(?:G|Gi|M|Mi)$\",\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run Job.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=\"The name of the service account to use for the task execution \"\n        \"of Cloud Run Job. By default Cloud Run jobs run as the default \"\n        \"Compute Engine Service Account. \",\n        example=\"service-account@example.iam.gserviceaccount.com\",\n    )\n    keep_job: Optional[bool] = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud Run Job after it has run.\",\n    )\n    timeout: Optional[int] = Field(\n        default=600,\n        gt=0,\n        le=3600,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the Job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 3600 seconds, 1 hour).\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/","title":"Cloud Run V2","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2","title":"<code>prefect_gcp.workers.cloud_run_v2</code>","text":""},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration","title":"<code>CloudRunWorkerJobV2Configuration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>The configuration for the Cloud Run worker V2.</p> <p>The schema for this class is used to populate the <code>job_body</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerJobV2Configuration(BaseJobConfiguration):\n    \"\"\"\n    The configuration for the Cloud Run worker V2.\n\n    The schema for this class is used to populate the `job_body` section of the\n    default base job template.\n    \"\"\"\n\n    credentials: GcpCredentials = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=(\n            \"The GCP Credentials used to connect to Cloud Run. \"\n            \"If not provided credentials will be inferred from \"\n            \"the local environment.\"\n        ),\n    )\n    job_body: Dict[str, Any] = Field(\n        template=_get_default_job_body_template(),\n    )\n    keep_job: bool = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud run job on Google Cloud Platform.\",\n    )\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region in which to run the Cloud Run job\",\n    )\n    timeout: int = Field(\n        default=600,\n        gt=0,\n        le=86400,\n        description=(\n            \"Max allowed duration the job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 86400 seconds, 1 day).\"\n        ),\n    )\n    _job_name: str = PrivateAttr(default=None)\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"\n        Returns the GCP project associated with the credentials.\n\n        Returns:\n            str: The GCP project associated with the credentials.\n        \"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"\n        Returns the name of the job.\n\n        Returns:\n            str: The name of the job.\n        \"\"\"\n        if self._job_name is None:\n            base_job_name = slugify_name(self.name)\n            job_name = f\"{base_job_name}-{uuid4().hex}\"\n            self._job_name = job_name\n\n        return self._job_name\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job body and that the\n        job body is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n        super().prepare_for_flow_run(\n            flow_run=flow_run,\n            deployment=deployment,\n            flow=flow,\n        )\n\n        self._populate_env()\n        self._populate_or_format_command()\n        self._format_args_if_present()\n        self._populate_image_if_not_present()\n        self._populate_timeout()\n        self._remove_vpc_access_if_unset()\n\n    def _populate_timeout(self):\n        \"\"\"\n        Populates the job body with the timeout.\n        \"\"\"\n        self.job_body[\"template\"][\"template\"][\"timeout\"] = f\"{self.timeout}s\"\n\n    def _populate_env(self):\n        \"\"\"\n        Populates the job body with environment variables.\n        \"\"\"\n        envs = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n\n        self.job_body[\"template\"][\"template\"][\"containers\"][0][\"env\"] = envs\n\n    def _populate_image_if_not_present(self):\n        \"\"\"\n        Populates the job body with the image if not present.\n        \"\"\"\n        if \"image\" not in self.job_body[\"template\"][\"template\"][\"containers\"][0]:\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"image\"\n            ] = f\"docker.io/{get_prefect_image_name()}\"\n\n    def _populate_or_format_command(self):\n        \"\"\"\n        Populates the job body with the command if not present.\n        \"\"\"\n        command = self.job_body[\"template\"][\"template\"][\"containers\"][0].get(\"command\")\n\n        if command is None:\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"command\"\n            ] = shlex.split(self._base_flow_run_command())\n        elif isinstance(command, str):\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"command\"\n            ] = shlex.split(command)\n\n    def _format_args_if_present(self):\n        \"\"\"\n        Formats the job body args if present.\n        \"\"\"\n        args = self.job_body[\"template\"][\"template\"][\"containers\"][0].get(\"args\")\n\n        if args is not None and isinstance(args, str):\n            self.job_body[\"template\"][\"template\"][\"containers\"][0][\n                \"args\"\n            ] = shlex.split(args)\n\n    def _remove_vpc_access_if_unset(self):\n        \"\"\"\n        Removes vpcAccess if unset.\n        \"\"\"\n\n        if \"vpcAccess\" not in self.job_body[\"template\"][\"template\"]:\n            return\n\n        vpc_access = self.job_body[\"template\"][\"template\"][\"vpcAccess\"]\n\n        # if vpcAccess is unset or connector is unset, remove the entire vpcAccess block\n        # otherwise leave the user provided value.\n        if not vpc_access or (\n            len(vpc_access) == 1\n            and \"connector\" in vpc_access\n            and vpc_access[\"connector\"] is None\n        ):\n            self.job_body[\"template\"][\"template\"].pop(\"vpcAccess\")\n\n    # noinspection PyMethodParameters\n    @validator(\"job_body\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job body includes all required components.\n\n        Args:\n            value: The job body to validate.\n        Returns:\n            The validated job body.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n\n        if missing_paths:\n            raise ValueError(\n                f\"Job body is missing required components: {', '.join(missing_paths)}\"\n            )\n\n        return value\n\n    # noinspection PyMethodParameters\n    @validator(\"job_body\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        \"\"\"Ensure that the job body has compatible values.\"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_body())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>Returns the name of the job.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The name of the job.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>Returns the GCP project associated with the credentials.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>The GCP project associated with the credentials.</p>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerJobV2Configuration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job body and that the job body is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job body and that the\n    job body is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n    super().prepare_for_flow_run(\n        flow_run=flow_run,\n        deployment=deployment,\n        flow=flow,\n    )\n\n    self._populate_env()\n    self._populate_or_format_command()\n    self._format_args_if_present()\n    self._populate_image_if_not_present()\n    self._populate_timeout()\n    self._remove_vpc_access_if_unset()\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2","title":"<code>CloudRunWorkerV2</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>The Cloud Run worker V2.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2(BaseWorker):\n    \"\"\"\n    The Cloud Run worker V2.\n    \"\"\"\n\n    type = \"cloud-run-v2\"\n    job_configuration = CloudRunWorkerJobV2Configuration\n    job_configuration_variables = CloudRunWorkerV2Variables\n    _description = \"Execute flow runs within containers on Google Cloud Run (V2 API). Requires a Google Cloud Platform account.\"  # noqa\n    _display_name = \"Google Cloud Run V2\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/worker_v2/\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/4SpnOBvMYkHp6z939MDKP6/549a91bc1ce9afd4fb12c68db7b68106/social-icon-google-cloud-1200-630.png?h=250\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: CloudRunWorkerJobV2Configuration,\n        task_status: Optional[TaskStatus] = None,\n    ) -&gt; CloudRunWorkerV2Result:\n        \"\"\"\n        Runs the flow run on Cloud Run and waits for it to complete.\n\n        Args:\n            flow_run: The flow run to run.\n            configuration: The configuration for the job.\n            task_status: The task status to update.\n\n        Returns:\n            The result of the job.\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n\n        with self._get_client(configuration=configuration) as cr_client:\n            await run_sync_in_worker_thread(\n                self._create_job_and_wait_for_registration,\n                configuration=configuration,\n                cr_client=cr_client,\n                logger=logger,\n            )\n\n            execution = await run_sync_in_worker_thread(\n                self._begin_job_execution,\n                configuration=configuration,\n                cr_client=cr_client,\n                logger=logger,\n            )\n\n            if task_status:\n                task_status.started(configuration.job_name)\n\n            result = await run_sync_in_worker_thread(\n                self._watch_job_execution_and_get_result,\n                configuration=configuration,\n                cr_client=cr_client,\n                execution=execution,\n                logger=logger,\n            )\n\n            return result\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: CloudRunWorkerJobV2Configuration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops the Cloud Run job.\n\n        Args:\n            infrastructure_pid: The ID of the infrastructure to stop.\n            configuration: The configuration for the job.\n            grace_seconds: The number of seconds to wait before stopping the job.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n            )\n\n        with self._get_client(configuration=configuration) as cr_client:\n            await run_sync_in_worker_thread(\n                self._stop_job,\n                cr_client=cr_client,\n                configuration=configuration,\n                job_name=infrastructure_pid,\n            )\n\n    @staticmethod\n    def _get_client(\n        configuration: CloudRunWorkerJobV2Configuration,\n    ) -&gt; ResourceWarning:\n        \"\"\"\n        Get the base client needed for interacting with GCP Cloud Run V2 API.\n\n        Returns:\n            Resource: The base client needed for interacting with GCP Cloud Run V2 API.\n        \"\"\"\n        api_endpoint = \"https://run.googleapis.com\"\n        gcp_creds = configuration.credentials.get_credentials_from_service_account()\n\n        options = ClientOptions(api_endpoint=api_endpoint)\n\n        return (\n            discovery.build(\n                \"run\",\n                \"v2\",\n                client_options=options,\n                credentials=gcp_creds,\n                num_retries=3,  # Set to 3 in case of intermittent/connection issues\n            )\n            .projects()\n            .locations()\n        )\n\n    def _create_job_and_wait_for_registration(\n        self,\n        configuration: CloudRunWorkerJobV2Configuration,\n        cr_client: Resource,\n        logger: PrefectLogAdapter,\n    ):\n        \"\"\"\n        Creates the Cloud Run job and waits for it to register.\n\n        Args:\n            configuration: The configuration for the job.\n            cr_client: The Cloud Run client.\n            logger: The logger to use.\n        \"\"\"\n        try:\n            logger.info(f\"Creating Cloud Run JobV2 {configuration.job_name}\")\n\n            JobV2.create(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_id=configuration.job_name,\n                body=configuration.job_body,\n            )\n        except HttpError as exc:\n            self._create_job_error(\n                exc=exc,\n                configuration=configuration,\n            )\n\n        try:\n            self._wait_for_job_creation(\n                cr_client=cr_client,\n                configuration=configuration,\n                logger=logger,\n            )\n        except Exception as exc:\n            logger.critical(\n                f\"Failed to create Cloud Run JobV2 {configuration.job_name}.\\n{exc}\"\n            )\n\n            if not configuration.keep_job:\n                try:\n                    JobV2.delete(\n                        cr_client=cr_client,\n                        project=configuration.project,\n                        location=configuration.region,\n                        job_name=configuration.job_name,\n                    )\n                except Exception as exc2:\n                    logger.critical(\n                        f\"Failed to delete Cloud Run JobV2 {configuration.job_name}.\"\n                        f\"\\n{exc2}\"\n                    )\n\n            raise\n\n    @staticmethod\n    def _wait_for_job_creation(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ):\n        \"\"\"\n        Waits for the Cloud Run job to be created.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            logger: The logger to use.\n            poll_interval: The interval to poll the Cloud Run job, defaults to 5\n                seconds.\n        \"\"\"\n        job = JobV2.get(\n            cr_client=cr_client,\n            project=configuration.project,\n            location=configuration.region,\n            job_name=configuration.job_name,\n        )\n\n        while not job.is_ready():\n            if not (ready_condition := job.get_ready_condition()):\n                ready_condition = \"waiting for condition update\"\n\n            logger.info(f\"Current Job Condition: {ready_condition}\")\n\n            job = JobV2.get(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=configuration.job_name,\n            )\n\n            time.sleep(poll_interval)\n\n    @staticmethod\n    def _create_job_error(\n        exc: HttpError,\n        configuration: CloudRunWorkerJobV2Configuration,\n    ):\n        \"\"\"\n        Creates a formatted error message for the Cloud Run V2 API errors\n        \"\"\"\n        # noinspection PyUnresolvedReferences\n        if exc.status_code == 404:\n            raise RuntimeError(\n                f\"Failed to find resources at {exc.uri}. Confirm that region\"\n                f\" '{configuration.region}' is the correct region for your Cloud\"\n                f\" Run Job and that {configuration.project} is the correct GCP \"\n                f\" project. If your project ID is not correct, you are using a \"\n                f\"Credentials block with permissions for the wrong project.\"\n            ) from exc\n\n        raise exc\n\n    def _begin_job_execution(\n        self,\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        logger: PrefectLogAdapter,\n    ) -&gt; ExecutionV2:\n        \"\"\"\n        Begins the Cloud Run job execution.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            logger: The logger to use.\n\n        Returns:\n            The Cloud Run job execution.\n        \"\"\"\n        try:\n            logger.info(\n                f\"Submitting Cloud Run Job V2 {configuration.job_name} for execution...\"\n            )\n\n            submission = JobV2.run(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=configuration.job_name,\n            )\n\n            job_execution = ExecutionV2.get(\n                cr_client=cr_client,\n                execution_id=submission[\"metadata\"][\"name\"],\n            )\n\n            command = (\n                \" \".join(configuration.command)\n                if configuration.command\n                else \"default container command\"\n            )\n\n            logger.info(\n                f\"Cloud Run Job V2 {configuration.job_name} submitted for execution \"\n                f\"with command: {command}\"\n            )\n\n            return job_execution\n        except Exception as exc:\n            self._job_run_submission_error(\n                exc=exc,\n                configuration=configuration,\n            )\n            raise\n\n    def _watch_job_execution_and_get_result(\n        self,\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        execution: ExecutionV2,\n        logger: PrefectLogAdapter,\n        poll_interval: int = 5,\n    ) -&gt; CloudRunWorkerV2Result:\n        \"\"\"\n        Watch the job execution and get the result.\n\n        Args:\n            cr_client (Resource): The base client needed for interacting with GCP\n                Cloud Run V2 API.\n            configuration (CloudRunWorkerJobV2Configuration): The configuration for\n                the job.\n            execution (ExecutionV2): The execution to watch.\n            logger (PrefectLogAdapter): The logger to use.\n            poll_interval (int): The number of seconds to wait between polls.\n                Defaults to 5 seconds.\n\n        Returns:\n            The result of the job.\n        \"\"\"\n        try:\n            execution = self._watch_job_execution(\n                cr_client=cr_client,\n                configuration=configuration,\n                execution=execution,\n                poll_interval=poll_interval,\n            )\n        except Exception as exc:\n            logger.critical(\n                f\"Encountered an exception while waiting for job run completion - \"\n                f\"{exc}\"\n            )\n            raise\n\n        if execution.succeeded():\n            status_code = 0\n            logger.info(f\"Cloud Run Job V2 {configuration.job_name} succeeded\")\n        else:\n            status_code = 1\n            error_mg = execution.condition_after_completion().get(\"message\")\n            logger.error(\n                f\"Cloud Run Job V2 {configuration.job_name} failed - {error_mg}\"\n            )\n\n        logger.info(f\"Job run logs can be found on GCP at: {execution.logUri}\")\n\n        if not configuration.keep_job:\n            logger.info(\n                f\"Deleting completed Cloud Run Job {configuration.job_name!r} from \"\n                \"Google Cloud Run...\"\n            )\n\n            try:\n                JobV2.delete(\n                    cr_client=cr_client,\n                    project=configuration.project,\n                    location=configuration.region,\n                    job_name=configuration.job_name,\n                )\n            except Exception as exc:\n                logger.critical(\n                    \"Received an exception while deleting the Cloud Run Job V2 \"\n                    f\"- {configuration.job_name} - {exc}\"\n                )\n\n        return CloudRunWorkerV2Result(\n            identifier=configuration.job_name,\n            status_code=status_code,\n        )\n\n    # noinspection DuplicatedCode\n    @staticmethod\n    def _watch_job_execution(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        execution: ExecutionV2,\n        poll_interval: int,\n    ) -&gt; ExecutionV2:\n        \"\"\"\n        Update execution status until it is no longer running.\n\n        Args:\n            cr_client (Resource): The base client needed for interacting with GCP\n                Cloud Run V2 API.\n            configuration (CloudRunWorkerJobV2Configuration): The configuration for\n                the job.\n            execution (ExecutionV2): The execution to watch.\n            poll_interval (int): The number of seconds to wait between polls.\n\n        Returns:\n            The execution.\n        \"\"\"\n\n        while execution.is_running():\n            execution = ExecutionV2.get(\n                cr_client=cr_client,\n                execution_id=execution.name,\n            )\n\n            time.sleep(poll_interval)\n\n        return execution\n\n    @staticmethod\n    def _job_run_submission_error(\n        exc: Exception,\n        configuration: CloudRunWorkerJobV2Configuration,\n    ):\n        \"\"\"\n        Creates a formatted error message for the Cloud Run V2 API errors\n\n        Args:\n            exc: The exception to format.\n            configuration: The configuration for the job.\n        \"\"\"\n        # noinspection PyUnresolvedReferences\n        if exc.status_code == 404:\n            pat1 = r\"The requested URL [^ ]+ was not found on this server\"\n\n            if re.findall(pat1, str(exc)):\n                # noinspection PyUnresolvedReferences\n                raise RuntimeError(\n                    f\"Failed to find resources at {exc.uri}. \"\n                    f\"Confirm that region '{configuration.region}' is \"\n                    f\"the correct region for your Cloud Run Job \"\n                    f\"and that '{configuration.project}' is the \"\n                    f\"correct GCP project. If your project ID is not \"\n                    f\"correct, you are using a Credentials \"\n                    f\"block with permissions for the wrong project.\"\n                ) from exc\n            else:\n                raise exc\n\n    @staticmethod\n    def _stop_job(\n        cr_client: Resource,\n        configuration: CloudRunWorkerJobV2Configuration,\n        job_name: str,\n    ):\n        \"\"\"\n        Stops/deletes the Cloud Run job.\n\n        Args:\n            cr_client: The Cloud Run client.\n            configuration: The configuration for the job.\n            job_name: The name of the job to stop.\n        \"\"\"\n        try:\n            JobV2.delete(\n                cr_client=cr_client,\n                project=configuration.project,\n                location=configuration.region,\n                job_name=job_name,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Cloud Run Job; the job name {job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops the Cloud Run job.</p> <p>Parameters:</p> Name Type Description Default <code>infrastructure_pid</code> <code>str</code> <p>The ID of the infrastructure to stop.</p> required <code>configuration</code> <code>CloudRunWorkerJobV2Configuration</code> <p>The configuration for the job.</p> required <code>grace_seconds</code> <code>int</code> <p>The number of seconds to wait before stopping the job.</p> <code>30</code> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: CloudRunWorkerJobV2Configuration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops the Cloud Run job.\n\n    Args:\n        infrastructure_pid: The ID of the infrastructure to stop.\n        configuration: The configuration for the job.\n        grace_seconds: The number of seconds to wait before stopping the job.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/run/docs/reference/rest/v1/namespaces.jobs/delete\"  # noqa\n        )\n\n    with self._get_client(configuration=configuration) as cr_client:\n        await run_sync_in_worker_thread(\n            self._stop_job,\n            cr_client=cr_client,\n            configuration=configuration,\n            job_name=infrastructure_pid,\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs the flow run on Cloud Run and waits for it to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to run.</p> required <code>configuration</code> <code>CloudRunWorkerJobV2Configuration</code> <p>The configuration for the job.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status to update.</p> <code>None</code> <p>Returns:</p> Type Description <code>CloudRunWorkerV2Result</code> <p>The result of the job.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: CloudRunWorkerJobV2Configuration,\n    task_status: Optional[TaskStatus] = None,\n) -&gt; CloudRunWorkerV2Result:\n    \"\"\"\n    Runs the flow run on Cloud Run and waits for it to complete.\n\n    Args:\n        flow_run: The flow run to run.\n        configuration: The configuration for the job.\n        task_status: The task status to update.\n\n    Returns:\n        The result of the job.\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n\n    with self._get_client(configuration=configuration) as cr_client:\n        await run_sync_in_worker_thread(\n            self._create_job_and_wait_for_registration,\n            configuration=configuration,\n            cr_client=cr_client,\n            logger=logger,\n        )\n\n        execution = await run_sync_in_worker_thread(\n            self._begin_job_execution,\n            configuration=configuration,\n            cr_client=cr_client,\n            logger=logger,\n        )\n\n        if task_status:\n            task_status.started(configuration.job_name)\n\n        result = await run_sync_in_worker_thread(\n            self._watch_job_execution_and_get_result,\n            configuration=configuration,\n            cr_client=cr_client,\n            execution=execution,\n            logger=logger,\n        )\n\n        return result\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Result","title":"<code>CloudRunWorkerV2Result</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>The result of a Cloud Run worker V2 job.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2Result(BaseWorkerResult):\n    \"\"\"\n    The result of a Cloud Run worker V2 job.\n    \"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_run_worker_v2/#prefect_gcp.workers.cloud_run_v2.CloudRunWorkerV2Variables","title":"<code>CloudRunWorkerV2Variables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Cloud Run worker V2.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/cloud_run_v2.py</code> <pre><code>class CloudRunWorkerV2Variables(BaseVariables):\n    \"\"\"\n    Default variables for the Cloud Run worker V2.\n\n    The schema for this class is used to populate the `variables` section of the\n    default base job template.\n    \"\"\"\n\n    credentials: GcpCredentials = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=(\n            \"The GCP Credentials used to connect to Cloud Run. \"\n            \"If not provided credentials will be inferred from \"\n            \"the local environment.\"\n        ),\n    )\n    region: str = Field(\n        default=\"us-central1\",\n        description=\"The region in which to run the Cloud Run job\",\n    )\n    image: Optional[str] = Field(\n        default=\"prefecthq/prefect:2-latest\",\n        title=\"Image Name\",\n        description=(\n            \"The image to use for the Cloud Run job. \"\n            \"If not provided the default Prefect image will be used.\"\n        ),\n    )\n    args: List[str] = Field(\n        default_factory=list,\n        description=(\n            \"The arguments to pass to the Cloud Run Job V2's entrypoint command.\"\n        ),\n    )\n    keep_job: bool = Field(\n        default=False,\n        title=\"Keep Job After Completion\",\n        description=\"Keep the completed Cloud run job on Google Cloud Platform.\",\n    )\n    launch_stage: Literal[\n        \"ALPHA\",\n        \"BETA\",\n        \"GA\",\n        \"DEPRECATED\",\n        \"EARLY_ACCESS\",\n        \"PRELAUNCH\",\n        \"UNIMPLEMENTED\",\n        \"LAUNCH_TAG_UNSPECIFIED\",\n    ] = Field(\n        \"BETA\",\n        description=(\n            \"The launch stage of the Cloud Run Job V2. \"\n            \"See https://cloud.google.com/run/docs/about-features-categories \"\n            \"for additional details.\"\n        ),\n    )\n    max_retries: int = Field(\n        default=0,\n        title=\"Max Retries\",\n        description=\"The number of times to retry the Cloud Run job.\",\n    )\n    cpu: str = Field(\n        default=\"1000m\",\n        title=\"CPU\",\n        description=\"The CPU to allocate to the Cloud Run job.\",\n    )\n    memory: str = Field(\n        default=\"512Mi\",\n        title=\"Memory\",\n        description=(\n            \"The memory to allocate to the Cloud Run job along with the units, which\"\n            \"could be: G, Gi, M, Mi.\"\n        ),\n        example=\"512Mi\",\n        pattern=r\"^\\d+(?:G|Gi|M|Mi)$\",\n    )\n    timeout: int = Field(\n        default=600,\n        gt=0,\n        le=86400,\n        title=\"Job Timeout\",\n        description=(\n            \"Max allowed duration the job may be active before Cloud Run will \"\n            \"actively try to mark it failed and kill associated containers (maximum of 86400 seconds, 1 day).\"\n        ),\n    )\n    vpc_connector_name: Optional[str] = Field(\n        default=None,\n        title=\"VPC Connector Name\",\n        description=\"The name of the VPC connector to use for the Cloud Run job.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=(\n            \"The name of the service account to use for the task execution \"\n            \"of Cloud Run Job. By default Cloud Run jobs run as the default \"\n            \"Compute Engine Service Account.\"\n        ),\n        example=\"service-account@example.iam.gserviceaccount.com\",\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/","title":"Cloud Storage","text":""},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage","title":"<code>prefect_gcp.cloud_storage</code>","text":"<p>Tasks for interacting with GCP Cloud Storage.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat","title":"<code>DataFrameSerializationFormat</code>","text":"<p>               Bases: <code>Enum</code></p> <p>An enumeration class to represent different file formats, compression options for upload_from_dataframe</p> <p>Attributes:</p> Name Type Description <code>CSV</code> <p>Representation for 'csv' file format with no compression and its related content type and suffix.</p> <code>CSV_GZIP</code> <p>Representation for 'csv' file format with 'gzip' compression and its related content type and suffix.</p> <code>PARQUET</code> <p>Representation for 'parquet' file format with no compression and its related content type and suffix.</p> <code>PARQUET_SNAPPY</code> <p>Representation for 'parquet' file format with 'snappy' compression and its related content type and suffix.</p> <code>PARQUET_GZIP</code> <p>Representation for 'parquet' file format with 'gzip' compression and its related content type and suffix.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>class DataFrameSerializationFormat(Enum):\n    \"\"\"\n    An enumeration class to represent different file formats,\n    compression options for upload_from_dataframe\n\n    Attributes:\n        CSV: Representation for 'csv' file format with no compression\n            and its related content type and suffix.\n\n        CSV_GZIP: Representation for 'csv' file format with 'gzip' compression\n            and its related content type and suffix.\n\n        PARQUET: Representation for 'parquet' file format with no compression\n            and its related content type and suffix.\n\n        PARQUET_SNAPPY: Representation for 'parquet' file format\n            with 'snappy' compression and its related content type and suffix.\n\n        PARQUET_GZIP: Representation for 'parquet' file format\n            with 'gzip' compression and its related content type and suffix.\n    \"\"\"\n\n    CSV = (\"csv\", None, \"text/csv\", \".csv\")\n    CSV_GZIP = (\"csv\", \"gzip\", \"application/x-gzip\", \".csv.gz\")\n    PARQUET = (\"parquet\", None, \"application/octet-stream\", \".parquet\")\n    PARQUET_SNAPPY = (\n        \"parquet\",\n        \"snappy\",\n        \"application/octet-stream\",\n        \".snappy.parquet\",\n    )\n    PARQUET_GZIP = (\"parquet\", \"gzip\", \"application/octet-stream\", \".gz.parquet\")\n\n    @property\n    def format(self) -&gt; str:\n        \"\"\"The file format of the current instance.\"\"\"\n        return self.value[0]\n\n    @property\n    def compression(self) -&gt; Union[str, None]:\n        \"\"\"The compression type of the current instance.\"\"\"\n        return self.value[1]\n\n    @property\n    def content_type(self) -&gt; str:\n        \"\"\"The content type of the current instance.\"\"\"\n        return self.value[2]\n\n    @property\n    def suffix(self) -&gt; str:\n        \"\"\"The suffix of the file format of the current instance.\"\"\"\n        return self.value[3]\n\n    def fix_extension_with(self, gcs_blob_path: str) -&gt; str:\n        \"\"\"Fix the extension of a GCS blob.\n\n        Args:\n            gcs_blob_path: The path to the GCS blob to be modified.\n\n        Returns:\n            The modified path to the GCS blob with the new extension.\n        \"\"\"\n        gcs_blob_path = PurePosixPath(gcs_blob_path)\n        folder = gcs_blob_path.parent\n        filename = PurePosixPath(gcs_blob_path.stem).with_suffix(self.suffix)\n        return str(folder.joinpath(filename))\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.compression","title":"<code>compression: Union[str, None]</code>  <code>property</code>","text":"<p>The compression type of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.content_type","title":"<code>content_type: str</code>  <code>property</code>","text":"<p>The content type of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.format","title":"<code>format: str</code>  <code>property</code>","text":"<p>The file format of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.suffix","title":"<code>suffix: str</code>  <code>property</code>","text":"<p>The suffix of the file format of the current instance.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.DataFrameSerializationFormat.fix_extension_with","title":"<code>fix_extension_with</code>","text":"<p>Fix the extension of a GCS blob.</p> <p>Parameters:</p> Name Type Description Default <code>gcs_blob_path</code> <code>str</code> <p>The path to the GCS blob to be modified.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The modified path to the GCS blob with the new extension.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>def fix_extension_with(self, gcs_blob_path: str) -&gt; str:\n    \"\"\"Fix the extension of a GCS blob.\n\n    Args:\n        gcs_blob_path: The path to the GCS blob to be modified.\n\n    Returns:\n        The modified path to the GCS blob with the new extension.\n    \"\"\"\n    gcs_blob_path = PurePosixPath(gcs_blob_path)\n    folder = gcs_blob_path.parent\n    filename = PurePosixPath(gcs_blob_path.stem).with_suffix(self.suffix)\n    return str(folder.joinpath(filename))\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket","title":"<code>GcsBucket</code>","text":"<p>               Bases: <code>WritableDeploymentStorage</code>, <code>WritableFileSystem</code>, <code>ObjectStorageBlock</code></p> <p>Block used to store data using GCP Cloud Storage Buckets.</p> <p>Note! <code>GcsBucket</code> in <code>prefect-gcp</code> is a unique block, separate from <code>GCS</code> in core Prefect. <code>GcsBucket</code> does not use <code>gcsfs</code> under the hood, instead using the <code>google-cloud-storage</code> package, and offers more configuration and functionality.</p> <p>Attributes:</p> Name Type Description <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> <code>gcp_credentials</code> <code>GcpCredentials</code> <p>The credentials to authenticate with GCP.</p> <code>bucket_folder</code> <code>str</code> <p>A default path to a folder within the GCS bucket to use for reading and writing objects.</p> Example <p>Load stored GCP Cloud Storage Bucket: <pre><code>from prefect_gcp.cloud_storage import GcsBucket\ngcp_cloud_storage_bucket_block = GcsBucket.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>class GcsBucket(WritableDeploymentStorage, WritableFileSystem, ObjectStorageBlock):\n    \"\"\"\n    Block used to store data using GCP Cloud Storage Buckets.\n\n    Note! `GcsBucket` in `prefect-gcp` is a unique block, separate from `GCS`\n    in core Prefect. `GcsBucket` does not use `gcsfs` under the hood,\n    instead using the `google-cloud-storage` package, and offers more configuration\n    and functionality.\n\n    Attributes:\n        bucket: Name of the bucket.\n        gcp_credentials: The credentials to authenticate with GCP.\n        bucket_folder: A default path to a folder within the GCS bucket to use\n            for reading and writing objects.\n\n    Example:\n        Load stored GCP Cloud Storage Bucket:\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n        gcp_cloud_storage_bucket_block = GcsBucket.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _block_type_name = \"GCS Bucket\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket\"  # noqa: E501\n\n    bucket: str = Field(..., description=\"Name of the bucket.\")\n    gcp_credentials: GcpCredentials = Field(\n        default_factory=GcpCredentials,\n        description=\"The credentials to authenticate with GCP.\",\n    )\n    bucket_folder: str = Field(\n        default=\"\",\n        description=(\n            \"A default path to a folder within the GCS bucket to use \"\n            \"for reading and writing objects.\"\n        ),\n    )\n\n    @property\n    def basepath(self) -&gt; str:\n        \"\"\"\n        Read-only property that mirrors the bucket folder.\n\n        Used for deployment.\n        \"\"\"\n        return self.bucket_folder\n\n    @validator(\"bucket_folder\", pre=True, always=True)\n    def _bucket_folder_suffix(cls, value):\n        \"\"\"\n        Ensures that the bucket folder is suffixed with a forward slash.\n        \"\"\"\n        if value != \"\" and not value.endswith(\"/\"):\n            value = f\"{value}/\"\n        return value\n\n    def _resolve_path(self, path: str) -&gt; str:\n        \"\"\"\n        A helper function used in write_path to join `self.bucket_folder` and `path`.\n\n        Args:\n            path: Name of the key, e.g. \"file1\". Each object in your\n                bucket has a unique key (or key name).\n\n        Returns:\n            The joined path.\n        \"\"\"\n        # If bucket_folder provided, it means we won't write to the root dir of\n        # the bucket. So we need to add it on the front of the path.\n        path = (\n            str(PurePosixPath(self.bucket_folder, path)) if self.bucket_folder else path\n        )\n        if path in [\"\", \".\", \"/\"]:\n            # client.bucket.list_blobs(prefix=None) is the proper way\n            # of specifying the root folder of the bucket\n            path = None\n        return path\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; List[Union[str, Path]]:\n        \"\"\"\n        Copies a folder from the configured GCS bucket to a local directory.\n        Defaults to copying the entire contents of the block's bucket_folder\n        to the current working directory.\n\n        Args:\n            from_path: Path in GCS bucket to download from. Defaults to the block's\n                configured bucket_folder.\n            local_path: Local path to download GCS bucket contents to.\n                Defaults to the current working directory.\n\n        Returns:\n            A list of downloaded file paths.\n        \"\"\"\n        from_path = (\n            self.bucket_folder if from_path is None else self._resolve_path(from_path)\n        )\n\n        if local_path is None:\n            local_path = os.path.abspath(\".\")\n        else:\n            local_path = os.path.abspath(os.path.expanduser(local_path))\n\n        project = self.gcp_credentials.project\n        client = self.gcp_credentials.get_cloud_storage_client(project=project)\n\n        blobs = await run_sync_in_worker_thread(\n            client.list_blobs, self.bucket, prefix=from_path\n        )\n\n        file_paths = []\n        for blob in blobs:\n            blob_path = blob.name\n            if blob_path[-1] == \"/\":\n                # object is a folder and will be created if it contains any objects\n                continue\n            relative_blob_path = os.path.relpath(blob_path, from_path)\n            local_file_path = os.path.join(local_path, relative_blob_path)\n            os.makedirs(os.path.dirname(local_file_path), exist_ok=True)\n\n            with disable_run_logger():\n                file_path = await cloud_storage_download_blob_to_file.fn(\n                    bucket=self.bucket,\n                    blob=blob_path,\n                    path=local_file_path,\n                    gcp_credentials=self.gcp_credentials,\n                )\n                file_paths.append(file_path)\n        return file_paths\n\n    @sync_compatible\n    async def put_directory(\n        self,\n        local_path: Optional[str] = None,\n        to_path: Optional[str] = None,\n        ignore_file: Optional[str] = None,\n    ) -&gt; int:\n        \"\"\"\n        Uploads a directory from a given local path to the configured GCS bucket in a\n        given folder.\n\n        Defaults to uploading the entire contents the current working directory to the\n        block's bucket_folder.\n\n        Args:\n            local_path: Path to local directory to upload from.\n            to_path: Path in GCS bucket to upload to. Defaults to block's configured\n                bucket_folder.\n            ignore_file: Path to file containing gitignore style expressions for\n                filepaths to ignore.\n\n        Returns:\n            The number of files uploaded.\n        \"\"\"\n        if local_path is None:\n            local_path = os.path.abspath(\".\")\n        else:\n            local_path = os.path.expanduser(local_path)\n\n        to_path = self.bucket_folder if to_path is None else self._resolve_path(to_path)\n\n        included_files = None\n        if ignore_file:\n            with open(ignore_file, \"r\") as f:\n                ignore_patterns = f.readlines()\n            included_files = filter_files(local_path, ignore_patterns)\n\n        uploaded_file_count = 0\n        for local_file_path in Path(local_path).rglob(\"*\"):\n            if (\n                included_files is not None\n                and str(local_file_path.relative_to(local_path)) not in included_files\n            ):\n                continue\n            elif not local_file_path.is_dir():\n                remote_file_path = str(\n                    PurePosixPath(to_path, local_file_path.relative_to(local_path))\n                )\n                local_file_content = local_file_path.read_bytes()\n                await self.write_path(remote_file_path, content=local_file_content)\n                uploaded_file_count += 1\n\n        return uploaded_file_count\n\n    @sync_compatible\n    async def read_path(self, path: str) -&gt; bytes:\n        \"\"\"\n        Read specified path from GCS and return contents. Provide the entire\n        path to the key in GCS.\n\n        Args:\n            path: Entire path to (and including) the key.\n\n        Returns:\n            A bytes or string representation of the blob object.\n        \"\"\"\n        path = self._resolve_path(path)\n        with disable_run_logger():\n            contents = await cloud_storage_download_blob_as_bytes.fn(\n                bucket=self.bucket, blob=path, gcp_credentials=self.gcp_credentials\n            )\n        return contents\n\n    @sync_compatible\n    async def write_path(self, path: str, content: bytes) -&gt; str:\n        \"\"\"\n        Writes to an GCS bucket.\n\n        Args:\n            path: The key name. Each object in your bucket has a unique\n                key (or key name).\n            content: What you are uploading to GCS Bucket.\n\n        Returns:\n            The path that the contents were written to.\n        \"\"\"\n        path = self._resolve_path(path)\n        with disable_run_logger():\n            await cloud_storage_upload_blob_from_string.fn(\n                data=content,\n                bucket=self.bucket,\n                blob=path,\n                gcp_credentials=self.gcp_credentials,\n            )\n        return path\n\n    # NEW BLOCK INTERFACE METHODS BELOW\n    def _join_bucket_folder(self, bucket_path: str = \"\") -&gt; str:\n        \"\"\"\n        Joins the base bucket folder to the bucket path.\n\n        NOTE: If a method reuses another method in this class, be careful to not\n        call this  twice because it'll join the bucket folder twice.\n        See https://github.com/PrefectHQ/prefect-aws/issues/141 for a past issue.\n        \"\"\"\n        bucket_path = str(bucket_path)\n        if self.bucket_folder != \"\" and bucket_path.startswith(self.bucket_folder):\n            self.logger.info(\n                f\"Bucket path {bucket_path!r} is already prefixed with \"\n                f\"bucket folder {self.bucket_folder!r}; is this intentional?\"\n            )\n\n        bucket_path = str(PurePosixPath(self.bucket_folder) / bucket_path)\n        if bucket_path in [\"\", \".\", \"/\"]:\n            # client.bucket.list_blobs(prefix=None) is the proper way\n            # of specifying the root folder of the bucket\n            bucket_path = None\n        return bucket_path\n\n    @sync_compatible\n    async def create_bucket(\n        self, location: Optional[str] = None, **create_kwargs\n    ) -&gt; \"Bucket\":\n        \"\"\"\n        Creates a bucket.\n\n        Args:\n            location: The location of the bucket.\n            **create_kwargs: Additional keyword arguments to pass to the\n                `create_bucket` method.\n\n        Returns:\n            The bucket object.\n\n        Examples:\n            Create a bucket.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket(bucket=\"my-bucket\")\n            gcs_bucket.create_bucket()\n            ```\n        \"\"\"\n        self.logger.info(f\"Creating bucket {self.bucket!r}.\")\n        client = self.gcp_credentials.get_cloud_storage_client()\n        bucket = await run_sync_in_worker_thread(\n            client.create_bucket, self.bucket, location=location, **create_kwargs\n        )\n        return bucket\n\n    @sync_compatible\n    async def get_bucket(self) -&gt; \"Bucket\":\n        \"\"\"\n        Returns the bucket object.\n\n        Returns:\n            The bucket object.\n\n        Examples:\n            Get the bucket object.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.get_bucket()\n            ```\n        \"\"\"\n        self.logger.info(f\"Getting bucket {self.bucket!r}.\")\n        client = self.gcp_credentials.get_cloud_storage_client()\n        bucket = await run_sync_in_worker_thread(client.get_bucket, self.bucket)\n        return bucket\n\n    @sync_compatible\n    async def list_blobs(self, folder: str = \"\") -&gt; List[\"Blob\"]:\n        \"\"\"\n        Lists all blobs in the bucket that are in a folder.\n        Folders are not included in the output.\n\n        Args:\n            folder: The folder to list blobs from.\n\n        Returns:\n            A list of Blob objects.\n\n        Examples:\n            Get all blobs from a folder named \"prefect\".\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_blobs(\"prefect\")\n            ```\n        \"\"\"\n        client = self.gcp_credentials.get_cloud_storage_client()\n\n        bucket_path = self._join_bucket_folder(folder)\n        if bucket_path is None:\n            self.logger.info(f\"Listing blobs in bucket {self.bucket!r}.\")\n        else:\n            self.logger.info(\n                f\"Listing blobs in folder {bucket_path!r} in bucket {self.bucket!r}.\"\n            )\n        blobs = await run_sync_in_worker_thread(\n            client.list_blobs, self.bucket, prefix=bucket_path\n        )\n\n        # Ignore folders\n        return [blob for blob in blobs if not blob.name.endswith(\"/\")]\n\n    @sync_compatible\n    async def list_folders(self, folder: str = \"\") -&gt; List[str]:\n        \"\"\"\n        Lists all folders and subfolders in the bucket.\n\n        Args:\n            folder: List all folders and subfolders inside given folder.\n\n        Returns:\n            A list of folders.\n\n        Examples:\n            Get all folders from a bucket named \"my-bucket\".\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_folders()\n            ```\n\n            Get all folders from a folder called years\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.list_folders(\"years\")\n            ```\n        \"\"\"\n\n        # Beware of calling _join_bucket_folder twice, see note in method.\n        # However, we just want to use it to check if we are listing the root folder\n        bucket_path = self._join_bucket_folder(folder)\n        if bucket_path is None:\n            self.logger.info(f\"Listing folders in bucket {self.bucket!r}.\")\n        else:\n            self.logger.info(\n                f\"Listing folders in {bucket_path!r} in bucket {self.bucket!r}.\"\n            )\n\n        blobs = await self.list_blobs(folder)\n        # gets all folders with full path\n        folders = {str(PurePosixPath(blob.name).parent) for blob in blobs}\n\n        return [folder for folder in folders if folder != \".\"]\n\n    @sync_compatible\n    async def download_object_to_path(\n        self,\n        from_path: str,\n        to_path: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads an object from the object storage service to a path.\n\n        Args:\n            from_path: The path to the blob to download; this gets prefixed\n                with the bucket_folder.\n            to_path: The path to download the blob to. If not provided, the\n                blob's name will be used.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_filename`.\n\n        Returns:\n            The absolute path that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to notes.txt.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        # making path absolute, but converting back to str here\n        # since !r looks nicer that way and filename arg expects str\n        to_path = str(Path(to_path).absolute())\n\n        bucket = await self.get_bucket()\n        bucket_path = self._join_bucket_folder(from_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n            f\"to {to_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.download_to_filename, filename=to_path, **download_kwargs\n        )\n        return Path(to_path)\n\n    @sync_compatible\n    async def download_object_to_file_object(\n        self,\n        from_path: str,\n        to_file_object: BinaryIO,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; BinaryIO:\n        \"\"\"\n        Downloads an object from the object storage service to a file-like object,\n        which can be a BytesIO object or a BufferedWriter.\n\n        Args:\n            from_path: The path to the blob to download from; this gets prefixed\n                with the bucket_folder.\n            to_file_object: The file-like object to download the blob to.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_file`.\n\n        Returns:\n            The file-like object that the object was downloaded to.\n\n        Examples:\n            Download my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with BytesIO() as buf:\n                gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n            ```\n\n            Download my_folder/notes.txt object to a BufferedWriter.\n            ```python\n                from prefect_gcp.cloud_storage import GcsBucket\n\n                gcs_bucket = GcsBucket.load(\"my-bucket\")\n                with open(\"notes.txt\", \"wb\") as f:\n                    gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n            ```\n        \"\"\"\n        bucket = await self.get_bucket()\n\n        bucket_path = self._join_bucket_folder(from_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n            f\"to file object.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.download_to_file, file_obj=to_file_object, **download_kwargs\n        )\n        return to_file_object\n\n    @sync_compatible\n    async def download_folder_to_path(\n        self,\n        from_folder: str,\n        to_folder: Optional[Union[str, Path]] = None,\n        **download_kwargs: Dict[str, Any],\n    ) -&gt; Path:\n        \"\"\"\n        Downloads objects *within* a folder (excluding the folder itself)\n        from the object storage service to a folder.\n\n        Args:\n            from_folder: The path to the folder to download from; this gets prefixed\n                with the bucket_folder.\n            to_folder: The path to download the folder to. If not provided, will default\n                to the current directory.\n            **download_kwargs: Additional keyword arguments to pass to\n                `Blob.download_to_filename`.\n\n        Returns:\n            The absolute path that the folder was downloaded to.\n\n        Examples:\n            Download my_folder to a local folder named my_folder.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n            ```\n        \"\"\"\n        if to_folder is None:\n            to_folder = \"\"\n        to_folder = Path(to_folder).absolute()\n\n        blobs = await self.list_blobs(folder=from_folder)\n        if len(blobs) == 0:\n            self.logger.warning(\n                f\"No blobs were downloaded from \"\n                f\"bucket {self.bucket!r} path {from_folder!r}.\"\n            )\n            return to_folder\n\n        # do not call self._join_bucket_folder for list_blobs\n        # because it's built-in to that method already!\n        # however, we still need to do it because we're using relative_to\n        bucket_folder = self._join_bucket_folder(from_folder)\n\n        async_coros = []\n        for blob in blobs:\n            bucket_path = PurePosixPath(blob.name).relative_to(bucket_folder)\n            if str(bucket_path).endswith(\"/\"):\n                continue\n            to_path = to_folder / bucket_path\n            to_path.parent.mkdir(parents=True, exist_ok=True)\n            self.logger.info(\n                f\"Downloading blob from bucket {self.bucket!r} path \"\n                f\"{str(bucket_path)!r} to {to_path}.\"\n            )\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    blob.download_to_filename, filename=str(to_path), **download_kwargs\n                )\n            )\n        await asyncio.gather(*async_coros)\n\n        return to_folder\n\n    @sync_compatible\n    async def upload_from_path(\n        self,\n        from_path: Union[str, Path],\n        to_path: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object from a path to the object storage service.\n\n        Args:\n            from_path: The path to the file to upload from.\n            to_path: The path to upload the file to. If not provided, will use\n                the file name of from_path; this gets prefixed\n                with the bucket_folder.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_filename`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload notes.txt to my_folder/notes.txt.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n            ```\n        \"\"\"\n        if to_path is None:\n            to_path = Path(from_path).name\n\n        bucket_path = self._join_bucket_folder(to_path)\n        bucket = await self.get_bucket()\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Uploading from {from_path!r} to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.upload_from_filename, filename=from_path, **upload_kwargs\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_file_object(\n        self, from_file_object: BinaryIO, to_path: str, **upload_kwargs\n    ) -&gt; str:\n        \"\"\"\n        Uploads an object to the object storage service from a file-like object,\n        which can be a BytesIO object or a BufferedReader.\n\n        Args:\n            from_file_object: The file-like object to upload from.\n            to_path: The path to upload the object to; this gets prefixed\n                with the bucket_folder.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_file`.\n\n        Returns:\n            The path that the object was uploaded to.\n\n        Examples:\n            Upload my_folder/notes.txt object to a BytesIO object.\n            ```python\n            from io import BytesIO\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n            ```\n\n            Upload BufferedReader object to my_folder/notes.txt.\n            ```python\n            from io import BufferedReader\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"rb\") as f:\n                gcs_bucket.upload_from_file_object(\n                    BufferedReader(f), \"my_folder/notes.txt\"\n                )\n            ```\n        \"\"\"\n        bucket = await self.get_bucket()\n\n        bucket_path = self._join_bucket_folder(to_path)\n        blob = bucket.blob(bucket_path)\n        self.logger.info(\n            f\"Uploading from file object to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n\n        await run_sync_in_worker_thread(\n            blob.upload_from_file, from_file_object, **upload_kwargs\n        )\n        return bucket_path\n\n    @sync_compatible\n    async def upload_from_folder(\n        self,\n        from_folder: Union[str, Path],\n        to_folder: Optional[str] = None,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"\n        Uploads files *within* a folder (excluding the folder itself)\n        to the object storage service folder.\n\n        Args:\n            from_folder: The path to the folder to upload from.\n            to_folder: The path to upload the folder to. If not provided, will default\n                to bucket_folder or the base directory of the bucket.\n            **upload_kwargs: Additional keyword arguments to pass to\n                `Blob.upload_from_filename`.\n\n        Returns:\n            The path that the folder was uploaded to.\n\n        Examples:\n            Upload local folder my_folder to the bucket's folder my_folder.\n            ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            gcs_bucket.upload_from_folder(\"my_folder\")\n            ```\n        \"\"\"\n        from_folder = Path(from_folder)\n        # join bucket folder expects string for the first input\n        # when it returns None, we need to convert it back to empty string\n        # so relative_to works\n        bucket_folder = self._join_bucket_folder(to_folder or \"\") or \"\"\n\n        num_uploaded = 0\n        bucket = await self.get_bucket()\n\n        async_coros = []\n        for from_path in from_folder.rglob(\"**/*\"):\n            if from_path.is_dir():\n                continue\n            bucket_path = str(Path(bucket_folder) / from_path.relative_to(from_folder))\n            self.logger.info(\n                f\"Uploading from {str(from_path)!r} to the bucket \"\n                f\"{self.bucket!r} path {bucket_path!r}.\"\n            )\n            blob = bucket.blob(bucket_path)\n            async_coros.append(\n                run_sync_in_worker_thread(\n                    blob.upload_from_filename, filename=from_path, **upload_kwargs\n                )\n            )\n            num_uploaded += 1\n        await asyncio.gather(*async_coros)\n        if num_uploaded == 0:\n            self.logger.warning(f\"No files were uploaded from {from_folder}.\")\n        return bucket_folder\n\n    @sync_compatible\n    async def upload_from_dataframe(\n        self,\n        df: \"DataFrame\",\n        to_path: str,\n        serialization_format: Union[\n            str, DataFrameSerializationFormat\n        ] = DataFrameSerializationFormat.CSV_GZIP,\n        **upload_kwargs: Dict[str, Any],\n    ) -&gt; str:\n        \"\"\"Upload a Pandas DataFrame to Google Cloud Storage in various formats.\n\n        This function uploads the data in a Pandas DataFrame to Google Cloud Storage\n        in a specified format, such as .csv, .csv.gz, .parquet,\n        .parquet.snappy, and .parquet.gz.\n\n        Args:\n            df: The Pandas DataFrame to be uploaded.\n            to_path: The destination path for the uploaded DataFrame.\n            serialization_format: The format to serialize the DataFrame into.\n                When passed as a `str`, the valid options are:\n                'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'.\n                Defaults to `DataFrameSerializationFormat.CSV_GZIP`.\n            **upload_kwargs: Additional keyword arguments to pass to the underlying\n            `Blob.upload_from_dataframe` method.\n\n        Returns:\n            The path that the object was uploaded to.\n        \"\"\"\n        if isinstance(serialization_format, str):\n            serialization_format = DataFrameSerializationFormat[\n                serialization_format.upper()\n            ]\n\n        with BytesIO() as bytes_buffer:\n            if serialization_format.format == \"parquet\":\n                df.to_parquet(\n                    path=bytes_buffer,\n                    compression=serialization_format.compression,\n                    index=False,\n                )\n            elif serialization_format.format == \"csv\":\n                df.to_csv(\n                    path_or_buf=bytes_buffer,\n                    compression=serialization_format.compression,\n                    index=False,\n                )\n\n            bytes_buffer.seek(0)\n            to_path = serialization_format.fix_extension_with(gcs_blob_path=to_path)\n\n            return await self.upload_from_file_object(\n                from_file_object=bytes_buffer,\n                to_path=to_path,\n                **{\"content_type\": serialization_format.content_type, **upload_kwargs},\n            )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.basepath","title":"<code>basepath: str</code>  <code>property</code>","text":"<p>Read-only property that mirrors the bucket folder.</p> <p>Used for deployment.</p>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.create_bucket","title":"<code>create_bucket</code>  <code>async</code>","text":"<p>Creates a bucket.</p> <p>Parameters:</p> Name Type Description Default <code>location</code> <code>Optional[str]</code> <p>The location of the bucket.</p> <code>None</code> <code>**create_kwargs</code> <p>Additional keyword arguments to pass to the <code>create_bucket</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Bucket</code> <p>The bucket object.</p> <p>Examples:</p> <p>Create a bucket. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket(bucket=\"my-bucket\")\ngcs_bucket.create_bucket()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def create_bucket(\n    self, location: Optional[str] = None, **create_kwargs\n) -&gt; \"Bucket\":\n    \"\"\"\n    Creates a bucket.\n\n    Args:\n        location: The location of the bucket.\n        **create_kwargs: Additional keyword arguments to pass to the\n            `create_bucket` method.\n\n    Returns:\n        The bucket object.\n\n    Examples:\n        Create a bucket.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket(bucket=\"my-bucket\")\n        gcs_bucket.create_bucket()\n        ```\n    \"\"\"\n    self.logger.info(f\"Creating bucket {self.bucket!r}.\")\n    client = self.gcp_credentials.get_cloud_storage_client()\n    bucket = await run_sync_in_worker_thread(\n        client.create_bucket, self.bucket, location=location, **create_kwargs\n    )\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_folder_to_path","title":"<code>download_folder_to_path</code>  <code>async</code>","text":"<p>Downloads objects within a folder (excluding the folder itself) from the object storage service to a folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>str</code> <p>The path to the folder to download from; this gets prefixed with the bucket_folder.</p> required <code>to_folder</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the folder to. If not provided, will default to the current directory.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the folder was downloaded to.</p> <p>Examples:</p> <p>Download my_folder to a local folder named my_folder. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_folder_to_path(\n    self,\n    from_folder: str,\n    to_folder: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads objects *within* a folder (excluding the folder itself)\n    from the object storage service to a folder.\n\n    Args:\n        from_folder: The path to the folder to download from; this gets prefixed\n            with the bucket_folder.\n        to_folder: The path to download the folder to. If not provided, will default\n            to the current directory.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The absolute path that the folder was downloaded to.\n\n    Examples:\n        Download my_folder to a local folder named my_folder.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.download_folder_to_path(\"my_folder\", \"my_folder\")\n        ```\n    \"\"\"\n    if to_folder is None:\n        to_folder = \"\"\n    to_folder = Path(to_folder).absolute()\n\n    blobs = await self.list_blobs(folder=from_folder)\n    if len(blobs) == 0:\n        self.logger.warning(\n            f\"No blobs were downloaded from \"\n            f\"bucket {self.bucket!r} path {from_folder!r}.\"\n        )\n        return to_folder\n\n    # do not call self._join_bucket_folder for list_blobs\n    # because it's built-in to that method already!\n    # however, we still need to do it because we're using relative_to\n    bucket_folder = self._join_bucket_folder(from_folder)\n\n    async_coros = []\n    for blob in blobs:\n        bucket_path = PurePosixPath(blob.name).relative_to(bucket_folder)\n        if str(bucket_path).endswith(\"/\"):\n            continue\n        to_path = to_folder / bucket_path\n        to_path.parent.mkdir(parents=True, exist_ok=True)\n        self.logger.info(\n            f\"Downloading blob from bucket {self.bucket!r} path \"\n            f\"{str(bucket_path)!r} to {to_path}.\"\n        )\n        async_coros.append(\n            run_sync_in_worker_thread(\n                blob.download_to_filename, filename=str(to_path), **download_kwargs\n            )\n        )\n    await asyncio.gather(*async_coros)\n\n    return to_folder\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_object_to_file_object","title":"<code>download_object_to_file_object</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a file-like object, which can be a BytesIO object or a BufferedWriter.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the blob to download from; this gets prefixed with the bucket_folder.</p> required <code>to_file_object</code> <code>BinaryIO</code> <p>The file-like object to download the blob to.</p> required <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>BinaryIO</code> <p>The file-like object that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith BytesIO() as buf:\n    gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n</code></pre></p> <p>Download my_folder/notes.txt object to a BufferedWriter. <pre><code>    from prefect_gcp.cloud_storage import GcsBucket\n\n    gcs_bucket = GcsBucket.load(\"my-bucket\")\n    with open(\"notes.txt\", \"wb\") as f:\n        gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_file_object(\n    self,\n    from_path: str,\n    to_file_object: BinaryIO,\n    **download_kwargs: Dict[str, Any],\n) -&gt; BinaryIO:\n    \"\"\"\n    Downloads an object from the object storage service to a file-like object,\n    which can be a BytesIO object or a BufferedWriter.\n\n    Args:\n        from_path: The path to the blob to download from; this gets prefixed\n            with the bucket_folder.\n        to_file_object: The file-like object to download the blob to.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_file`.\n\n    Returns:\n        The file-like object that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with BytesIO() as buf:\n            gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", buf)\n        ```\n\n        Download my_folder/notes.txt object to a BufferedWriter.\n        ```python\n            from prefect_gcp.cloud_storage import GcsBucket\n\n            gcs_bucket = GcsBucket.load(\"my-bucket\")\n            with open(\"notes.txt\", \"wb\") as f:\n                gcs_bucket.download_object_to_file_object(\"my_folder/notes.txt\", f)\n        ```\n    \"\"\"\n    bucket = await self.get_bucket()\n\n    bucket_path = self._join_bucket_folder(from_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n        f\"to file object.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.download_to_file, file_obj=to_file_object, **download_kwargs\n    )\n    return to_file_object\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.download_object_to_path","title":"<code>download_object_to_path</code>  <code>async</code>","text":"<p>Downloads an object from the object storage service to a path.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>str</code> <p>The path to the blob to download; this gets prefixed with the bucket_folder.</p> required <code>to_path</code> <code>Optional[Union[str, Path]]</code> <p>The path to download the blob to. If not provided, the blob's name will be used.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Path</code> <p>The absolute path that the object was downloaded to.</p> <p>Examples:</p> <p>Download my_folder/notes.txt object to notes.txt. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def download_object_to_path(\n    self,\n    from_path: str,\n    to_path: Optional[Union[str, Path]] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Path:\n    \"\"\"\n    Downloads an object from the object storage service to a path.\n\n    Args:\n        from_path: The path to the blob to download; this gets prefixed\n            with the bucket_folder.\n        to_path: The path to download the blob to. If not provided, the\n            blob's name will be used.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The absolute path that the object was downloaded to.\n\n    Examples:\n        Download my_folder/notes.txt object to notes.txt.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.download_object_to_path(\"my_folder/notes.txt\", \"notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    # making path absolute, but converting back to str here\n    # since !r looks nicer that way and filename arg expects str\n    to_path = str(Path(to_path).absolute())\n\n    bucket = await self.get_bucket()\n    bucket_path = self._join_bucket_folder(from_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Downloading blob from bucket {self.bucket!r} path {bucket_path!r}\"\n        f\"to {to_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.download_to_filename, filename=to_path, **download_kwargs\n    )\n    return Path(to_path)\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.get_bucket","title":"<code>get_bucket</code>  <code>async</code>","text":"<p>Returns the bucket object.</p> <p>Returns:</p> Type Description <code>Bucket</code> <p>The bucket object.</p> <p>Examples:</p> <p>Get the bucket object. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.get_bucket()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def get_bucket(self) -&gt; \"Bucket\":\n    \"\"\"\n    Returns the bucket object.\n\n    Returns:\n        The bucket object.\n\n    Examples:\n        Get the bucket object.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.get_bucket()\n        ```\n    \"\"\"\n    self.logger.info(f\"Getting bucket {self.bucket!r}.\")\n    client = self.gcp_credentials.get_cloud_storage_client()\n    bucket = await run_sync_in_worker_thread(client.get_bucket, self.bucket)\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Copies a folder from the configured GCS bucket to a local directory. Defaults to copying the entire contents of the block's bucket_folder to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>Path in GCS bucket to download from. Defaults to the block's configured bucket_folder.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>Local path to download GCS bucket contents to. Defaults to the current working directory.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Union[str, Path]]</code> <p>A list of downloaded file paths.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; List[Union[str, Path]]:\n    \"\"\"\n    Copies a folder from the configured GCS bucket to a local directory.\n    Defaults to copying the entire contents of the block's bucket_folder\n    to the current working directory.\n\n    Args:\n        from_path: Path in GCS bucket to download from. Defaults to the block's\n            configured bucket_folder.\n        local_path: Local path to download GCS bucket contents to.\n            Defaults to the current working directory.\n\n    Returns:\n        A list of downloaded file paths.\n    \"\"\"\n    from_path = (\n        self.bucket_folder if from_path is None else self._resolve_path(from_path)\n    )\n\n    if local_path is None:\n        local_path = os.path.abspath(\".\")\n    else:\n        local_path = os.path.abspath(os.path.expanduser(local_path))\n\n    project = self.gcp_credentials.project\n    client = self.gcp_credentials.get_cloud_storage_client(project=project)\n\n    blobs = await run_sync_in_worker_thread(\n        client.list_blobs, self.bucket, prefix=from_path\n    )\n\n    file_paths = []\n    for blob in blobs:\n        blob_path = blob.name\n        if blob_path[-1] == \"/\":\n            # object is a folder and will be created if it contains any objects\n            continue\n        relative_blob_path = os.path.relpath(blob_path, from_path)\n        local_file_path = os.path.join(local_path, relative_blob_path)\n        os.makedirs(os.path.dirname(local_file_path), exist_ok=True)\n\n        with disable_run_logger():\n            file_path = await cloud_storage_download_blob_to_file.fn(\n                bucket=self.bucket,\n                blob=blob_path,\n                path=local_file_path,\n                gcp_credentials=self.gcp_credentials,\n            )\n            file_paths.append(file_path)\n    return file_paths\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.list_blobs","title":"<code>list_blobs</code>  <code>async</code>","text":"<p>Lists all blobs in the bucket that are in a folder. Folders are not included in the output.</p> <p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>The folder to list blobs from.</p> <code>''</code> <p>Returns:</p> Type Description <code>List[Blob]</code> <p>A list of Blob objects.</p> <p>Examples:</p> <p>Get all blobs from a folder named \"prefect\". <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_blobs(\"prefect\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def list_blobs(self, folder: str = \"\") -&gt; List[\"Blob\"]:\n    \"\"\"\n    Lists all blobs in the bucket that are in a folder.\n    Folders are not included in the output.\n\n    Args:\n        folder: The folder to list blobs from.\n\n    Returns:\n        A list of Blob objects.\n\n    Examples:\n        Get all blobs from a folder named \"prefect\".\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_blobs(\"prefect\")\n        ```\n    \"\"\"\n    client = self.gcp_credentials.get_cloud_storage_client()\n\n    bucket_path = self._join_bucket_folder(folder)\n    if bucket_path is None:\n        self.logger.info(f\"Listing blobs in bucket {self.bucket!r}.\")\n    else:\n        self.logger.info(\n            f\"Listing blobs in folder {bucket_path!r} in bucket {self.bucket!r}.\"\n        )\n    blobs = await run_sync_in_worker_thread(\n        client.list_blobs, self.bucket, prefix=bucket_path\n    )\n\n    # Ignore folders\n    return [blob for blob in blobs if not blob.name.endswith(\"/\")]\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.list_folders","title":"<code>list_folders</code>  <code>async</code>","text":"<p>Lists all folders and subfolders in the bucket.</p> <p>Parameters:</p> Name Type Description Default <code>folder</code> <code>str</code> <p>List all folders and subfolders inside given folder.</p> <code>''</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>A list of folders.</p> <p>Examples:</p> <p>Get all folders from a bucket named \"my-bucket\". <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_folders()\n</code></pre></p> <p>Get all folders from a folder called years <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.list_folders(\"years\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def list_folders(self, folder: str = \"\") -&gt; List[str]:\n    \"\"\"\n    Lists all folders and subfolders in the bucket.\n\n    Args:\n        folder: List all folders and subfolders inside given folder.\n\n    Returns:\n        A list of folders.\n\n    Examples:\n        Get all folders from a bucket named \"my-bucket\".\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_folders()\n        ```\n\n        Get all folders from a folder called years\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.list_folders(\"years\")\n        ```\n    \"\"\"\n\n    # Beware of calling _join_bucket_folder twice, see note in method.\n    # However, we just want to use it to check if we are listing the root folder\n    bucket_path = self._join_bucket_folder(folder)\n    if bucket_path is None:\n        self.logger.info(f\"Listing folders in bucket {self.bucket!r}.\")\n    else:\n        self.logger.info(\n            f\"Listing folders in {bucket_path!r} in bucket {self.bucket!r}.\"\n        )\n\n    blobs = await self.list_blobs(folder)\n    # gets all folders with full path\n    folders = {str(PurePosixPath(blob.name).parent) for blob in blobs}\n\n    return [folder for folder in folders if folder != \".\"]\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.put_directory","title":"<code>put_directory</code>  <code>async</code>","text":"<p>Uploads a directory from a given local path to the configured GCS bucket in a given folder.</p> <p>Defaults to uploading the entire contents the current working directory to the block's bucket_folder.</p> <p>Parameters:</p> Name Type Description Default <code>local_path</code> <code>Optional[str]</code> <p>Path to local directory to upload from.</p> <code>None</code> <code>to_path</code> <code>Optional[str]</code> <p>Path in GCS bucket to upload to. Defaults to block's configured bucket_folder.</p> <code>None</code> <code>ignore_file</code> <code>Optional[str]</code> <p>Path to file containing gitignore style expressions for filepaths to ignore.</p> <code>None</code> <p>Returns:</p> Type Description <code>int</code> <p>The number of files uploaded.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def put_directory(\n    self,\n    local_path: Optional[str] = None,\n    to_path: Optional[str] = None,\n    ignore_file: Optional[str] = None,\n) -&gt; int:\n    \"\"\"\n    Uploads a directory from a given local path to the configured GCS bucket in a\n    given folder.\n\n    Defaults to uploading the entire contents the current working directory to the\n    block's bucket_folder.\n\n    Args:\n        local_path: Path to local directory to upload from.\n        to_path: Path in GCS bucket to upload to. Defaults to block's configured\n            bucket_folder.\n        ignore_file: Path to file containing gitignore style expressions for\n            filepaths to ignore.\n\n    Returns:\n        The number of files uploaded.\n    \"\"\"\n    if local_path is None:\n        local_path = os.path.abspath(\".\")\n    else:\n        local_path = os.path.expanduser(local_path)\n\n    to_path = self.bucket_folder if to_path is None else self._resolve_path(to_path)\n\n    included_files = None\n    if ignore_file:\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(local_path, ignore_patterns)\n\n    uploaded_file_count = 0\n    for local_file_path in Path(local_path).rglob(\"*\"):\n        if (\n            included_files is not None\n            and str(local_file_path.relative_to(local_path)) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = str(\n                PurePosixPath(to_path, local_file_path.relative_to(local_path))\n            )\n            local_file_content = local_file_path.read_bytes()\n            await self.write_path(remote_file_path, content=local_file_content)\n            uploaded_file_count += 1\n\n    return uploaded_file_count\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.read_path","title":"<code>read_path</code>  <code>async</code>","text":"<p>Read specified path from GCS and return contents. Provide the entire path to the key in GCS.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Entire path to (and including) the key.</p> required <p>Returns:</p> Type Description <code>bytes</code> <p>A bytes or string representation of the blob object.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def read_path(self, path: str) -&gt; bytes:\n    \"\"\"\n    Read specified path from GCS and return contents. Provide the entire\n    path to the key in GCS.\n\n    Args:\n        path: Entire path to (and including) the key.\n\n    Returns:\n        A bytes or string representation of the blob object.\n    \"\"\"\n    path = self._resolve_path(path)\n    with disable_run_logger():\n        contents = await cloud_storage_download_blob_as_bytes.fn(\n            bucket=self.bucket, blob=path, gcp_credentials=self.gcp_credentials\n        )\n    return contents\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_dataframe","title":"<code>upload_from_dataframe</code>  <code>async</code>","text":"<p>Upload a Pandas DataFrame to Google Cloud Storage in various formats.</p> <p>This function uploads the data in a Pandas DataFrame to Google Cloud Storage in a specified format, such as .csv, .csv.gz, .parquet, .parquet.snappy, and .parquet.gz.</p> <p>Parameters:</p> Name Type Description Default <code>df</code> <code>DataFrame</code> <p>The Pandas DataFrame to be uploaded.</p> required <code>to_path</code> <code>str</code> <p>The destination path for the uploaded DataFrame.</p> required <code>serialization_format</code> <code>Union[str, DataFrameSerializationFormat]</code> <p>The format to serialize the DataFrame into. When passed as a <code>str</code>, the valid options are: 'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'. Defaults to <code>DataFrameSerializationFormat.CSV_GZIP</code>.</p> <code>CSV_GZIP</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the underlying</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_dataframe(\n    self,\n    df: \"DataFrame\",\n    to_path: str,\n    serialization_format: Union[\n        str, DataFrameSerializationFormat\n    ] = DataFrameSerializationFormat.CSV_GZIP,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"Upload a Pandas DataFrame to Google Cloud Storage in various formats.\n\n    This function uploads the data in a Pandas DataFrame to Google Cloud Storage\n    in a specified format, such as .csv, .csv.gz, .parquet,\n    .parquet.snappy, and .parquet.gz.\n\n    Args:\n        df: The Pandas DataFrame to be uploaded.\n        to_path: The destination path for the uploaded DataFrame.\n        serialization_format: The format to serialize the DataFrame into.\n            When passed as a `str`, the valid options are:\n            'csv', 'csv_gzip',  'parquet', 'parquet_snappy', 'parquet_gzip'.\n            Defaults to `DataFrameSerializationFormat.CSV_GZIP`.\n        **upload_kwargs: Additional keyword arguments to pass to the underlying\n        `Blob.upload_from_dataframe` method.\n\n    Returns:\n        The path that the object was uploaded to.\n    \"\"\"\n    if isinstance(serialization_format, str):\n        serialization_format = DataFrameSerializationFormat[\n            serialization_format.upper()\n        ]\n\n    with BytesIO() as bytes_buffer:\n        if serialization_format.format == \"parquet\":\n            df.to_parquet(\n                path=bytes_buffer,\n                compression=serialization_format.compression,\n                index=False,\n            )\n        elif serialization_format.format == \"csv\":\n            df.to_csv(\n                path_or_buf=bytes_buffer,\n                compression=serialization_format.compression,\n                index=False,\n            )\n\n        bytes_buffer.seek(0)\n        to_path = serialization_format.fix_extension_with(gcs_blob_path=to_path)\n\n        return await self.upload_from_file_object(\n            from_file_object=bytes_buffer,\n            to_path=to_path,\n            **{\"content_type\": serialization_format.content_type, **upload_kwargs},\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_file_object","title":"<code>upload_from_file_object</code>  <code>async</code>","text":"<p>Uploads an object to the object storage service from a file-like object, which can be a BytesIO object or a BufferedReader.</p> <p>Parameters:</p> Name Type Description Default <code>from_file_object</code> <code>BinaryIO</code> <p>The file-like object to upload from.</p> required <code>to_path</code> <code>str</code> <p>The path to upload the object to; this gets prefixed with the bucket_folder.</p> required <code>**upload_kwargs</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_file</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload my_folder/notes.txt object to a BytesIO object. <pre><code>from io import BytesIO\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n</code></pre></p> <p>Upload BufferedReader object to my_folder/notes.txt. <pre><code>from io import BufferedReader\nfrom prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\nwith open(\"notes.txt\", \"rb\") as f:\n    gcs_bucket.upload_from_file_object(\n        BufferedReader(f), \"my_folder/notes.txt\"\n    )\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_file_object(\n    self, from_file_object: BinaryIO, to_path: str, **upload_kwargs\n) -&gt; str:\n    \"\"\"\n    Uploads an object to the object storage service from a file-like object,\n    which can be a BytesIO object or a BufferedReader.\n\n    Args:\n        from_file_object: The file-like object to upload from.\n        to_path: The path to upload the object to; this gets prefixed\n            with the bucket_folder.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_file`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload my_folder/notes.txt object to a BytesIO object.\n        ```python\n        from io import BytesIO\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            gcs_bucket.upload_from_file_object(f, \"my_folder/notes.txt\")\n        ```\n\n        Upload BufferedReader object to my_folder/notes.txt.\n        ```python\n        from io import BufferedReader\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        with open(\"notes.txt\", \"rb\") as f:\n            gcs_bucket.upload_from_file_object(\n                BufferedReader(f), \"my_folder/notes.txt\"\n            )\n        ```\n    \"\"\"\n    bucket = await self.get_bucket()\n\n    bucket_path = self._join_bucket_folder(to_path)\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Uploading from file object to the bucket \"\n        f\"{self.bucket!r} path {bucket_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.upload_from_file, from_file_object, **upload_kwargs\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_folder","title":"<code>upload_from_folder</code>  <code>async</code>","text":"<p>Uploads files within a folder (excluding the folder itself) to the object storage service folder.</p> <p>Parameters:</p> Name Type Description Default <code>from_folder</code> <code>Union[str, Path]</code> <p>The path to the folder to upload from.</p> required <code>to_folder</code> <code>Optional[str]</code> <p>The path to upload the folder to. If not provided, will default to bucket_folder or the base directory of the bucket.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the folder was uploaded to.</p> <p>Examples:</p> <p>Upload local folder my_folder to the bucket's folder my_folder. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.upload_from_folder(\"my_folder\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_folder(\n    self,\n    from_folder: Union[str, Path],\n    to_folder: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads files *within* a folder (excluding the folder itself)\n    to the object storage service folder.\n\n    Args:\n        from_folder: The path to the folder to upload from.\n        to_folder: The path to upload the folder to. If not provided, will default\n            to bucket_folder or the base directory of the bucket.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_filename`.\n\n    Returns:\n        The path that the folder was uploaded to.\n\n    Examples:\n        Upload local folder my_folder to the bucket's folder my_folder.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.upload_from_folder(\"my_folder\")\n        ```\n    \"\"\"\n    from_folder = Path(from_folder)\n    # join bucket folder expects string for the first input\n    # when it returns None, we need to convert it back to empty string\n    # so relative_to works\n    bucket_folder = self._join_bucket_folder(to_folder or \"\") or \"\"\n\n    num_uploaded = 0\n    bucket = await self.get_bucket()\n\n    async_coros = []\n    for from_path in from_folder.rglob(\"**/*\"):\n        if from_path.is_dir():\n            continue\n        bucket_path = str(Path(bucket_folder) / from_path.relative_to(from_folder))\n        self.logger.info(\n            f\"Uploading from {str(from_path)!r} to the bucket \"\n            f\"{self.bucket!r} path {bucket_path!r}.\"\n        )\n        blob = bucket.blob(bucket_path)\n        async_coros.append(\n            run_sync_in_worker_thread(\n                blob.upload_from_filename, filename=from_path, **upload_kwargs\n            )\n        )\n        num_uploaded += 1\n    await asyncio.gather(*async_coros)\n    if num_uploaded == 0:\n        self.logger.warning(f\"No files were uploaded from {from_folder}.\")\n    return bucket_folder\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.upload_from_path","title":"<code>upload_from_path</code>  <code>async</code>","text":"<p>Uploads an object from a path to the object storage service.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Union[str, Path]</code> <p>The path to the file to upload from.</p> required <code>to_path</code> <code>Optional[str]</code> <p>The path to upload the file to. If not provided, will use the file name of from_path; this gets prefixed with the bucket_folder.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The path that the object was uploaded to.</p> <p>Examples:</p> <p>Upload notes.txt to my_folder/notes.txt. <pre><code>from prefect_gcp.cloud_storage import GcsBucket\n\ngcs_bucket = GcsBucket.load(\"my-bucket\")\ngcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def upload_from_path(\n    self,\n    from_path: Union[str, Path],\n    to_path: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads an object from a path to the object storage service.\n\n    Args:\n        from_path: The path to the file to upload from.\n        to_path: The path to upload the file to. If not provided, will use\n            the file name of from_path; this gets prefixed\n            with the bucket_folder.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_filename`.\n\n    Returns:\n        The path that the object was uploaded to.\n\n    Examples:\n        Upload notes.txt to my_folder/notes.txt.\n        ```python\n        from prefect_gcp.cloud_storage import GcsBucket\n\n        gcs_bucket = GcsBucket.load(\"my-bucket\")\n        gcs_bucket.upload_from_path(\"notes.txt\", \"my_folder/notes.txt\")\n        ```\n    \"\"\"\n    if to_path is None:\n        to_path = Path(from_path).name\n\n    bucket_path = self._join_bucket_folder(to_path)\n    bucket = await self.get_bucket()\n    blob = bucket.blob(bucket_path)\n    self.logger.info(\n        f\"Uploading from {from_path!r} to the bucket \"\n        f\"{self.bucket!r} path {bucket_path!r}.\"\n    )\n\n    await run_sync_in_worker_thread(\n        blob.upload_from_filename, filename=from_path, **upload_kwargs\n    )\n    return bucket_path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.GcsBucket.write_path","title":"<code>write_path</code>  <code>async</code>","text":"<p>Writes to an GCS bucket.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The key name. Each object in your bucket has a unique key (or key name).</p> required <code>content</code> <code>bytes</code> <p>What you are uploading to GCS Bucket.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The path that the contents were written to.</p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@sync_compatible\nasync def write_path(self, path: str, content: bytes) -&gt; str:\n    \"\"\"\n    Writes to an GCS bucket.\n\n    Args:\n        path: The key name. Each object in your bucket has a unique\n            key (or key name).\n        content: What you are uploading to GCS Bucket.\n\n    Returns:\n        The path that the contents were written to.\n    \"\"\"\n    path = self._resolve_path(path)\n    with disable_run_logger():\n        await cloud_storage_upload_blob_from_string.fn(\n            data=content,\n            bucket=self.bucket,\n            blob=path,\n            gcp_credentials=self.gcp_credentials,\n        )\n    return path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_copy_blob","title":"<code>cloud_storage_copy_blob</code>  <code>async</code>","text":"<p>Copies data from one Google Cloud Storage bucket to another, without downloading it locally.</p> <p>Parameters:</p> Name Type Description Default <code>source_bucket</code> <code>str</code> <p>Source bucket name.</p> required <code>dest_bucket</code> <code>str</code> <p>Destination bucket name.</p> required <code>source_blob</code> <code>str</code> <p>Source blob name.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>dest_blob</code> <code>Optional[str]</code> <p>Destination blob name; if not provided, defaults to source_blob.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**copy_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Bucket.copy_blob</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>Destination blob name.</p> Example <p>Copies blob from one bucket to another. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_copy_blob\n\n@flow()\ndef example_cloud_storage_copy_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_copy_blob(\n        \"source_bucket\",\n        \"dest_bucket\",\n        \"source_blob\",\n        gcp_credentials\n    )\n    return blob\n\nexample_cloud_storage_copy_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_copy_blob(\n    source_bucket: str,\n    dest_bucket: str,\n    source_blob: str,\n    gcp_credentials: GcpCredentials,\n    dest_blob: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **copy_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Copies data from one Google Cloud Storage bucket to another,\n    without downloading it locally.\n\n    Args:\n        source_bucket: Source bucket name.\n        dest_bucket: Destination bucket name.\n        source_blob: Source blob name.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        dest_blob: Destination blob name; if not provided, defaults to source_blob.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **copy_kwargs: Additional keyword arguments to pass to\n            `Bucket.copy_blob`.\n\n    Returns:\n        Destination blob name.\n\n    Example:\n        Copies blob from one bucket to another.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_copy_blob\n\n        @flow()\n        def example_cloud_storage_copy_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_copy_blob(\n                \"source_bucket\",\n                \"dest_bucket\",\n                \"source_blob\",\n                gcp_credentials\n            )\n            return blob\n\n        example_cloud_storage_copy_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Copying blob named %s from the %s bucket to the %s bucket\",\n        source_blob,\n        source_bucket,\n        dest_bucket,\n    )\n\n    source_bucket_obj = await _get_bucket(\n        source_bucket, gcp_credentials, project=project\n    )\n\n    dest_bucket_obj = await _get_bucket(dest_bucket, gcp_credentials, project=project)\n    if dest_blob is None:\n        dest_blob = source_blob\n\n    source_blob_obj = source_bucket_obj.blob(source_blob)\n    await run_sync_in_worker_thread(\n        source_bucket_obj.copy_blob,\n        blob=source_blob_obj,\n        destination_bucket=dest_bucket_obj,\n        new_name=dest_blob,\n        timeout=timeout,\n        **copy_kwargs,\n    )\n\n    return dest_blob\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_create_bucket","title":"<code>cloud_storage_create_bucket</code>  <code>async</code>","text":"<p>Creates a bucket.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>location</code> <code>Optional[str]</code> <p>Location of the bucket.</p> <code>None</code> <code>**create_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>client.create_bucket</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The bucket name.</p> Example <p>Creates a bucket named \"prefect\". <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_create_bucket\n\n@flow()\ndef example_cloud_storage_create_bucket_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    bucket = cloud_storage_create_bucket(\"prefect\", gcp_credentials)\n\nexample_cloud_storage_create_bucket_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_create_bucket(\n    bucket: str,\n    gcp_credentials: GcpCredentials,\n    project: Optional[str] = None,\n    location: Optional[str] = None,\n    **create_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Creates a bucket.\n\n    Args:\n        bucket: Name of the bucket.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        location: Location of the bucket.\n        **create_kwargs: Additional keyword arguments to pass to `client.create_bucket`.\n\n    Returns:\n        The bucket name.\n\n    Example:\n        Creates a bucket named \"prefect\".\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_create_bucket\n\n        @flow()\n        def example_cloud_storage_create_bucket_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            bucket = cloud_storage_create_bucket(\"prefect\", gcp_credentials)\n\n        example_cloud_storage_create_bucket_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating %s bucket\", bucket)\n\n    client = gcp_credentials.get_cloud_storage_client(project=project)\n    await run_sync_in_worker_thread(\n        client.create_bucket, bucket, location=location, **create_kwargs\n    )\n    return bucket\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_download_blob_as_bytes","title":"<code>cloud_storage_download_blob_as_bytes</code>  <code>async</code>","text":"<p>Downloads a blob as bytes.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>chunk_size</code> <code>int</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_as_bytes</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>bytes</code> <p>A bytes or string representation of the blob object.</p> Example <p>Downloads blob from bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_download_blob_as_bytes\n\n@flow()\ndef example_cloud_storage_download_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    contents = cloud_storage_download_blob_as_bytes(\n        \"bucket\", \"blob\", gcp_credentials)\n    return contents\n\nexample_cloud_storage_download_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_download_blob_as_bytes(\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; bytes:\n    \"\"\"\n    Downloads a blob as bytes.\n\n    Args:\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        chunk_size (int, optional): The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_as_bytes`.\n\n    Returns:\n        A bytes or string representation of the blob object.\n\n    Example:\n        Downloads blob from bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_download_blob_as_bytes\n\n        @flow()\n        def example_cloud_storage_download_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            contents = cloud_storage_download_blob_as_bytes(\n                \"bucket\", \"blob\", gcp_credentials)\n            return contents\n\n        example_cloud_storage_download_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Downloading blob named %s from the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    contents = await run_sync_in_worker_thread(\n        blob_obj.download_as_bytes, timeout=timeout, **download_kwargs\n    )\n    return contents\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_download_blob_to_file","title":"<code>cloud_storage_download_blob_to_file</code>  <code>async</code>","text":"<p>Downloads a blob to a file path.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>path</code> <code>Union[str, Path]</code> <p>Downloads the contents to the provided file path; if the path is a directory, automatically joins the blob name.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>chunk_size</code> <code>int</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**download_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.download_to_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[str, Path]</code> <p>The path to the blob object.</p> Example <p>Downloads blob from bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_download_blob_to_file\n\n@flow()\ndef example_cloud_storage_download_blob_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    path = cloud_storage_download_blob_to_file(\n        \"bucket\", \"blob\", \"file_path\", gcp_credentials)\n    return path\n\nexample_cloud_storage_download_blob_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_download_blob_to_file(\n    bucket: str,\n    blob: str,\n    path: Union[str, Path],\n    gcp_credentials: GcpCredentials,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **download_kwargs: Dict[str, Any],\n) -&gt; Union[str, Path]:\n    \"\"\"\n    Downloads a blob to a file path.\n\n    Args:\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        path: Downloads the contents to the provided file path;\n            if the path is a directory, automatically joins the blob name.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        chunk_size (int, optional): The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **download_kwargs: Additional keyword arguments to pass to\n            `Blob.download_to_filename`.\n\n    Returns:\n        The path to the blob object.\n\n    Example:\n        Downloads blob from bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_download_blob_to_file\n\n        @flow()\n        def example_cloud_storage_download_blob_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            path = cloud_storage_download_blob_to_file(\n                \"bucket\", \"blob\", \"file_path\", gcp_credentials)\n            return path\n\n        example_cloud_storage_download_blob_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\n        \"Downloading blob named %s from the %s bucket to %s\", blob, bucket, path\n    )\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    if os.path.isdir(path):\n        if isinstance(path, Path):\n            path = path.joinpath(blob)  # keep as Path if Path is passed\n        else:\n            path = os.path.join(path, blob)  # keep as str if a str is passed\n\n    await run_sync_in_worker_thread(\n        blob_obj.download_to_filename, path, timeout=timeout, **download_kwargs\n    )\n    return path\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_file","title":"<code>cloud_storage_upload_blob_from_file</code>  <code>async</code>","text":"<p>Uploads a blob from file path or file-like object. Usage for passing in file-like object is if the data was downloaded from the web; can bypass writing to disk and directly upload to Cloud Storage.</p> <p>Parameters:</p> Name Type Description Default <code>file</code> <code>Union[str, Path, BytesIO]</code> <p>Path to data or file like object to upload.</p> required <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>content_type</code> <code>Optional[str]</code> <p>Type of content being uploaded.</p> <code>None</code> <code>chunk_size</code> <code>Optional[int]</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_file</code> or <code>Blob.upload_from_filename</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The blob name.</p> Example <p>Uploads blob to bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_file\n\n@flow()\ndef example_cloud_storage_upload_blob_from_file_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_upload_blob_from_file(\n        \"/path/somewhere\", \"bucket\", \"blob\", gcp_credentials)\n    return blob\n\nexample_cloud_storage_upload_blob_from_file_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_upload_blob_from_file(\n    file: Union[str, Path, BytesIO],\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    content_type: Optional[str] = None,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads a blob from file path or file-like object. Usage for passing in\n    file-like object is if the data was downloaded from the web;\n    can bypass writing to disk and directly upload to Cloud Storage.\n\n    Args:\n        file: Path to data or file like object to upload.\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        content_type: Type of content being uploaded.\n        chunk_size: The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_file` or `Blob.upload_from_filename`.\n\n    Returns:\n        The blob name.\n\n    Example:\n        Uploads blob to bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_file\n\n        @flow()\n        def example_cloud_storage_upload_blob_from_file_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_upload_blob_from_file(\n                \"/path/somewhere\", \"bucket\", \"blob\", gcp_credentials)\n            return blob\n\n        example_cloud_storage_upload_blob_from_file_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob named %s to the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    if isinstance(file, BytesIO):\n        await run_sync_in_worker_thread(\n            blob_obj.upload_from_file,\n            file,\n            content_type=content_type,\n            timeout=timeout,\n            **upload_kwargs,\n        )\n    else:\n        await run_sync_in_worker_thread(\n            blob_obj.upload_from_filename,\n            file,\n            content_type=content_type,\n            timeout=timeout,\n            **upload_kwargs,\n        )\n    return blob\n</code></pre>"},{"location":"integrations/prefect-gcp/cloud_storage/#prefect_gcp.cloud_storage.cloud_storage_upload_blob_from_string","title":"<code>cloud_storage_upload_blob_from_string</code>  <code>async</code>","text":"<p>Uploads a blob from a string or bytes representation of data.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Union[str, bytes]</code> <p>String or bytes representation of data to upload.</p> required <code>bucket</code> <code>str</code> <p>Name of the bucket.</p> required <code>blob</code> <code>str</code> <p>Name of the Cloud Storage blob.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>content_type</code> <code>Optional[str]</code> <p>Type of content being uploaded.</p> <code>None</code> <code>chunk_size</code> <code>Optional[int]</code> <p>The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification.</p> <code>None</code> <code>encryption_key</code> <code>Optional[str]</code> <p>An encryption key.</p> <code>None</code> <code>timeout</code> <code>Union[float, Tuple[float, float]]</code> <p>The number of seconds the transport should wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <code>**upload_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>Blob.upload_from_string</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>str</code> <p>The blob name.</p> Example <p>Uploads blob to bucket. <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_string\n\n@flow()\ndef example_cloud_storage_upload_blob_from_string_flow():\n    gcp_credentials = GcpCredentials(\n        service_account_file=\"/path/to/service/account/keyfile.json\")\n    blob = cloud_storage_upload_blob_from_string(\n        \"data\", \"bucket\", \"blob\", gcp_credentials)\n    return blob\n\nexample_cloud_storage_upload_blob_from_string_flow()\n</code></pre></p> Source code in <code>prefect_gcp/cloud_storage.py</code> <pre><code>@task\nasync def cloud_storage_upload_blob_from_string(\n    data: Union[str, bytes],\n    bucket: str,\n    blob: str,\n    gcp_credentials: GcpCredentials,\n    content_type: Optional[str] = None,\n    chunk_size: Optional[int] = None,\n    encryption_key: Optional[str] = None,\n    timeout: Union[float, Tuple[float, float]] = 60,\n    project: Optional[str] = None,\n    **upload_kwargs: Dict[str, Any],\n) -&gt; str:\n    \"\"\"\n    Uploads a blob from a string or bytes representation of data.\n\n    Args:\n        data: String or bytes representation of data to upload.\n        bucket: Name of the bucket.\n        blob: Name of the Cloud Storage blob.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        content_type: Type of content being uploaded.\n        chunk_size: The size of a chunk of data whenever\n            iterating (in bytes). This must be a multiple of 256 KB\n            per the API specification.\n        encryption_key: An encryption key.\n        timeout: The number of seconds the transport should wait\n            for the server response. Can also be passed as a tuple\n            (connect_timeout, read_timeout).\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n        **upload_kwargs: Additional keyword arguments to pass to\n            `Blob.upload_from_string`.\n\n    Returns:\n        The blob name.\n\n    Example:\n        Uploads blob to bucket.\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.cloud_storage import cloud_storage_upload_blob_from_string\n\n        @flow()\n        def example_cloud_storage_upload_blob_from_string_flow():\n            gcp_credentials = GcpCredentials(\n                service_account_file=\"/path/to/service/account/keyfile.json\")\n            blob = cloud_storage_upload_blob_from_string(\n                \"data\", \"bucket\", \"blob\", gcp_credentials)\n            return blob\n\n        example_cloud_storage_upload_blob_from_string_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Uploading blob named %s to the %s bucket\", blob, bucket)\n\n    bucket_obj = await _get_bucket(bucket, gcp_credentials, project=project)\n    blob_obj = bucket_obj.blob(\n        blob, chunk_size=chunk_size, encryption_key=encryption_key\n    )\n\n    await run_sync_in_worker_thread(\n        blob_obj.upload_from_string,\n        data,\n        content_type=content_type,\n        timeout=timeout,\n        **upload_kwargs,\n    )\n    return blob\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials","title":"<code>prefect_gcp.credentials</code>","text":"<p>Module handling GCP credentials.</p>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials","title":"<code>GcpCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with GCP. Google authentication is handled via the <code>google.oauth2</code> module or through the CLI. Specify either one of service <code>account_file</code> or <code>service_account_info</code>; if both are not specified, the client will try to detect the credentials following Google's Application Default Credentials. See Google's Authentication documentation for details on inference and recommended authentication patterns.</p> <p>Attributes:</p> Name Type Description <code>service_account_file</code> <code>Optional[Path]</code> <p>Path to the service account JSON keyfile.</p> <code>service_account_info</code> <code>Optional[SecretDict]</code> <p>The contents of the keyfile as a dict.</p> Example <p>Load GCP credentials stored in a <code>GCP Credentials</code> Block: <pre><code>from prefect_gcp import GcpCredentials\ngcp_credentials_block = GcpCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>class GcpCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with GCP. Google authentication is\n    handled via the `google.oauth2` module or through the CLI.\n    Specify either one of service `account_file` or `service_account_info`; if both\n    are not specified, the client will try to detect the credentials following Google's\n    [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials).\n    See Google's [Authentication documentation](https://cloud.google.com/docs/authentication#service-accounts)\n    for details on inference and recommended authentication patterns.\n\n    Attributes:\n        service_account_file: Path to the service account JSON keyfile.\n        service_account_info: The contents of the keyfile as a dict.\n\n    Example:\n        Load GCP credentials stored in a `GCP Credentials` Block:\n        ```python\n        from prefect_gcp import GcpCredentials\n        gcp_credentials_block = GcpCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _block_type_name = \"GCP Credentials\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials\"  # noqa: E501\n\n    service_account_file: Optional[Path] = Field(\n        default=None, description=\"Path to the service account JSON keyfile.\"\n    )\n    service_account_info: Optional[SecretDict] = Field(\n        default=None, description=\"The contents of the keyfile as a dict.\"\n    )\n    project: Optional[str] = Field(\n        default=None, description=\"The GCP project to use for the client.\"\n    )\n\n    _service_account_email: Optional[str] = None\n\n    def __hash__(self):\n        return hash(\n            (\n                hash(self.service_account_file),\n                hash(frozenset(self.service_account_info.dict().items()))\n                if self.service_account_info\n                else None,\n                hash(self.project),\n                hash(self._service_account_email),\n            )\n        )\n\n    @root_validator\n    def _provide_one_service_account_source(cls, values):\n        \"\"\"\n        Ensure that only a service account file or service account info ias provided.\n        \"\"\"\n        both_service_account = (\n            values.get(\"service_account_info\") is not None\n            and values.get(\"service_account_file\") is not None\n        )\n        if both_service_account:\n            raise ValueError(\n                \"Only one of service_account_info or service_account_file \"\n                \"can be specified at once\"\n            )\n        return values\n\n    @validator(\"service_account_file\")\n    def _check_service_account_file(cls, file):\n        \"\"\"Get full path of provided file and make sure that it exists.\"\"\"\n        if not file:\n            return file\n\n        service_account_file = Path(file).expanduser()\n        if not service_account_file.exists():\n            raise ValueError(\"The provided path to the service account is invalid\")\n        return service_account_file\n\n    @validator(\"service_account_info\", pre=True)\n    def _convert_json_string_json_service_account_info(cls, value):\n        \"\"\"\n        Converts service account info provided as a json formatted string\n        to a dictionary\n        \"\"\"\n        if isinstance(value, str):\n            try:\n                service_account_info = json.loads(value)\n                return service_account_info\n            except Exception:\n                raise ValueError(\"Unable to decode service_account_info\")\n        else:\n            return value\n\n    def block_initialization(self):\n        credentials = self.get_credentials_from_service_account()\n        if self.project is None:\n            if self.service_account_info or self.service_account_file:\n                credentials_project = credentials.project_id\n            # google.auth.default using gcloud auth application-default login\n            elif credentials.quota_project_id:\n                credentials_project = credentials.quota_project_id\n            # compute-assigned service account via GCP metadata server\n            else:\n                _, credentials_project = google.auth.default()\n            self.project = credentials_project\n\n        if hasattr(credentials, \"service_account_email\"):\n            self._service_account_email = credentials.service_account_email\n\n    def get_credentials_from_service_account(self) -&gt; Credentials:\n        \"\"\"\n        Helper method to serialize credentials by using either\n        service_account_file or service_account_info.\n        \"\"\"\n        if self.service_account_info:\n            credentials = Credentials.from_service_account_info(\n                self.service_account_info.get_secret_value(),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif self.service_account_file:\n            credentials = Credentials.from_service_account_file(\n                self.service_account_file,\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        else:\n            credentials, _ = google.auth.default()\n        return credentials\n\n    @sync_compatible\n    async def get_access_token(self):\n        \"\"\"\n        See: https://stackoverflow.com/a/69107745\n        Also: https://www.jhanley.com/google-cloud-creating-oauth-access-tokens-for-rest-api-calls/\n        \"\"\"  # noqa\n        request = google.auth.transport.requests.Request()\n        credentials = self.get_credentials_from_service_account()\n        await run_sync_in_worker_thread(credentials.refresh, request)\n        return credentials.token\n\n    def get_client(\n        self,\n        client_type: Union[str, ClientType],\n        **get_client_kwargs: Dict[str, Any],\n    ) -&gt; Any:\n        \"\"\"\n        Helper method to dynamically get a client type.\n\n        Args:\n            client_type: The name of the client to get.\n            **get_client_kwargs: Additional keyword arguments to pass to the\n                `get_*_client` method.\n\n        Returns:\n            An authenticated client.\n\n        Raises:\n            ValueError: if the client is not supported.\n        \"\"\"\n        if isinstance(client_type, str):\n            client_type = ClientType(client_type)\n        client_type = client_type.value\n        get_client_method = getattr(self, f\"get_{client_type}_client\")\n        return get_client_method(**get_client_kwargs)\n\n    @_raise_help_msg(\"cloud_storage\")\n    def get_cloud_storage_client(\n        self, project: Optional[str] = None\n    ) -&gt; \"StorageClient\":\n        \"\"\"\n        Gets an authenticated Cloud Storage client.\n\n        Args:\n            project: Name of the project to use; overrides the base\n                class's project if provided.\n\n        Returns:\n            An authenticated Cloud Storage client.\n\n        Examples:\n            Gets a GCP Cloud Storage client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_cloud_storage_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_cloud_storage_client()\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # override class project if method project is provided\n        project = project or self.project\n        storage_client = StorageClient(credentials=credentials, project=project)\n        return storage_client\n\n    @_raise_help_msg(\"bigquery\")\n    def get_bigquery_client(\n        self, project: str = None, location: str = None\n    ) -&gt; \"BigQueryClient\":\n        \"\"\"\n        Gets an authenticated BigQuery client.\n\n        Args:\n            project: Name of the project to use; overrides the base\n                class's project if provided.\n            location: Location to use.\n\n        Returns:\n            An authenticated BigQuery client.\n\n        Examples:\n            Gets a GCP BigQuery client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_bigquery_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP BigQuery client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_bigquery_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # override class project if method project is provided\n        project = project or self.project\n        big_query_client = BigQueryClient(\n            credentials=credentials, project=project, location=location\n        )\n        return big_query_client\n\n    @_raise_help_msg(\"secret_manager\")\n    def get_secret_manager_client(self) -&gt; \"SecretManagerServiceClient\":\n        \"\"\"\n        Gets an authenticated Secret Manager Service client.\n\n        Returns:\n            An authenticated Secret Manager Service client.\n\n        Examples:\n            Gets a GCP Secret Manager client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_secret_manager_client()\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_secret_manager_client()\n            example_get_client_flow()\n            ```\n        \"\"\"\n        credentials = self.get_credentials_from_service_account()\n\n        # doesn't accept project; must pass in project in tasks\n        secret_manager_client = SecretManagerServiceClient(credentials=credentials)\n        return secret_manager_client\n\n    @_raise_help_msg(\"aiplatform\")\n    def get_job_service_client(\n        self, client_options: Union[Dict[str, Any], ClientOptions] = None\n    ) -&gt; \"JobServiceClient\":\n        \"\"\"\n        Gets an authenticated Job Service client for Vertex AI.\n\n        Returns:\n            An authenticated Job Service client.\n\n        Examples:\n            Gets a GCP Job Service client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_job_service_client()\n\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_job_service_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        if isinstance(client_options, dict):\n            client_options = from_dict(client_options)\n\n        credentials = self.get_credentials_from_service_account()\n        return JobServiceClient(credentials=credentials, client_options=client_options)\n\n    @_raise_help_msg(\"aiplatform\")\n    def get_job_service_async_client(\n        self, client_options: Union[Dict[str, Any], ClientOptions] = None\n    ) -&gt; \"JobServiceAsyncClient\":\n        \"\"\"\n        Gets an authenticated Job Service async client for Vertex AI.\n\n        Returns:\n            An authenticated Job Service async client.\n\n        Examples:\n            Gets a GCP Job Service client from a path.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_file = \"~/.secrets/prefect-service-account.json\"\n                client = GcpCredentials(\n                    service_account_file=service_account_file\n                ).get_job_service_async_client()\n\n            example_get_client_flow()\n            ```\n\n            Gets a GCP Cloud Storage client from a dictionary.\n            ```python\n            from prefect import flow\n            from prefect_gcp.credentials import GcpCredentials\n\n            @flow()\n            def example_get_client_flow():\n                service_account_info = {\n                    \"type\": \"service_account\",\n                    \"project_id\": \"project_id\",\n                    \"private_key_id\": \"private_key_id\",\n                    \"private_key\": \"private_key\",\n                    \"client_email\": \"client_email\",\n                    \"client_id\": \"client_id\",\n                    \"auth_uri\": \"auth_uri\",\n                    \"token_uri\": \"token_uri\",\n                    \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                    \"client_x509_cert_url\": \"client_x509_cert_url\"\n                }\n                client = GcpCredentials(\n                    service_account_info=service_account_info\n                ).get_job_service_async_client()\n\n            example_get_client_flow()\n            ```\n        \"\"\"\n        if isinstance(client_options, dict):\n            client_options = from_dict(client_options)\n\n        return _get_job_service_async_client_cached(\n            self, tuple(client_options.__dict__.items())\n        )\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_access_token","title":"<code>get_access_token</code>  <code>async</code>","text":"Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@sync_compatible\nasync def get_access_token(self):\n    \"\"\"\n    See: https://stackoverflow.com/a/69107745\n    Also: https://www.jhanley.com/google-cloud-creating-oauth-access-tokens-for-rest-api-calls/\n    \"\"\"  # noqa\n    request = google.auth.transport.requests.Request()\n    credentials = self.get_credentials_from_service_account()\n    await run_sync_in_worker_thread(credentials.refresh, request)\n    return credentials.token\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_bigquery_client","title":"<code>get_bigquery_client</code>","text":"<p>Gets an authenticated BigQuery client.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>str</code> <p>Name of the project to use; overrides the base class's project if provided.</p> <code>None</code> <code>location</code> <code>str</code> <p>Location to use.</p> <code>None</code> <p>Returns:</p> Type Description <code>Client</code> <p>An authenticated BigQuery client.</p> <p>Examples:</p> <p>Gets a GCP BigQuery client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_bigquery_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP BigQuery client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_bigquery_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"bigquery\")\ndef get_bigquery_client(\n    self, project: str = None, location: str = None\n) -&gt; \"BigQueryClient\":\n    \"\"\"\n    Gets an authenticated BigQuery client.\n\n    Args:\n        project: Name of the project to use; overrides the base\n            class's project if provided.\n        location: Location to use.\n\n    Returns:\n        An authenticated BigQuery client.\n\n    Examples:\n        Gets a GCP BigQuery client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_bigquery_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP BigQuery client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_bigquery_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # override class project if method project is provided\n    project = project or self.project\n    big_query_client = BigQueryClient(\n        credentials=credentials, project=project, location=location\n    )\n    return big_query_client\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_client","title":"<code>get_client</code>","text":"<p>Helper method to dynamically get a client type.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Union[str, ClientType]</code> <p>The name of the client to get.</p> required <code>**get_client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to the <code>get_*_client</code> method.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Any</code> <p>An authenticated client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>if the client is not supported.</p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>def get_client(\n    self,\n    client_type: Union[str, ClientType],\n    **get_client_kwargs: Dict[str, Any],\n) -&gt; Any:\n    \"\"\"\n    Helper method to dynamically get a client type.\n\n    Args:\n        client_type: The name of the client to get.\n        **get_client_kwargs: Additional keyword arguments to pass to the\n            `get_*_client` method.\n\n    Returns:\n        An authenticated client.\n\n    Raises:\n        ValueError: if the client is not supported.\n    \"\"\"\n    if isinstance(client_type, str):\n        client_type = ClientType(client_type)\n    client_type = client_type.value\n    get_client_method = getattr(self, f\"get_{client_type}_client\")\n    return get_client_method(**get_client_kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_cloud_storage_client","title":"<code>get_cloud_storage_client</code>","text":"<p>Gets an authenticated Cloud Storage client.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the base class's project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>Client</code> <p>An authenticated Cloud Storage client.</p> <p>Examples:</p> <p>Gets a GCP Cloud Storage client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_cloud_storage_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_cloud_storage_client()\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"cloud_storage\")\ndef get_cloud_storage_client(\n    self, project: Optional[str] = None\n) -&gt; \"StorageClient\":\n    \"\"\"\n    Gets an authenticated Cloud Storage client.\n\n    Args:\n        project: Name of the project to use; overrides the base\n            class's project if provided.\n\n    Returns:\n        An authenticated Cloud Storage client.\n\n    Examples:\n        Gets a GCP Cloud Storage client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_cloud_storage_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_cloud_storage_client()\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # override class project if method project is provided\n    project = project or self.project\n    storage_client = StorageClient(credentials=credentials, project=project)\n    return storage_client\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_credentials_from_service_account","title":"<code>get_credentials_from_service_account</code>","text":"<p>Helper method to serialize credentials by using either service_account_file or service_account_info.</p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>def get_credentials_from_service_account(self) -&gt; Credentials:\n    \"\"\"\n    Helper method to serialize credentials by using either\n    service_account_file or service_account_info.\n    \"\"\"\n    if self.service_account_info:\n        credentials = Credentials.from_service_account_info(\n            self.service_account_info.get_secret_value(),\n            scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n        )\n    elif self.service_account_file:\n        credentials = Credentials.from_service_account_file(\n            self.service_account_file,\n            scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n        )\n    else:\n        credentials, _ = google.auth.default()\n    return credentials\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_job_service_async_client","title":"<code>get_job_service_async_client</code>","text":"<p>Gets an authenticated Job Service async client for Vertex AI.</p> <p>Returns:</p> Type Description <code>JobServiceAsyncClient</code> <p>An authenticated Job Service async client.</p> <p>Examples:</p> <p>Gets a GCP Job Service client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_job_service_async_client()\n\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_job_service_async_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"aiplatform\")\ndef get_job_service_async_client(\n    self, client_options: Union[Dict[str, Any], ClientOptions] = None\n) -&gt; \"JobServiceAsyncClient\":\n    \"\"\"\n    Gets an authenticated Job Service async client for Vertex AI.\n\n    Returns:\n        An authenticated Job Service async client.\n\n    Examples:\n        Gets a GCP Job Service client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_job_service_async_client()\n\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_job_service_async_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    if isinstance(client_options, dict):\n        client_options = from_dict(client_options)\n\n    return _get_job_service_async_client_cached(\n        self, tuple(client_options.__dict__.items())\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_job_service_client","title":"<code>get_job_service_client</code>","text":"<p>Gets an authenticated Job Service client for Vertex AI.</p> <p>Returns:</p> Type Description <code>JobServiceClient</code> <p>An authenticated Job Service client.</p> <p>Examples:</p> <p>Gets a GCP Job Service client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_job_service_client()\n\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_job_service_client()\n\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"aiplatform\")\ndef get_job_service_client(\n    self, client_options: Union[Dict[str, Any], ClientOptions] = None\n) -&gt; \"JobServiceClient\":\n    \"\"\"\n    Gets an authenticated Job Service client for Vertex AI.\n\n    Returns:\n        An authenticated Job Service client.\n\n    Examples:\n        Gets a GCP Job Service client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_job_service_client()\n\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_job_service_client()\n\n        example_get_client_flow()\n        ```\n    \"\"\"\n    if isinstance(client_options, dict):\n        client_options = from_dict(client_options)\n\n    credentials = self.get_credentials_from_service_account()\n    return JobServiceClient(credentials=credentials, client_options=client_options)\n</code></pre>"},{"location":"integrations/prefect-gcp/credentials/#prefect_gcp.credentials.GcpCredentials.get_secret_manager_client","title":"<code>get_secret_manager_client</code>","text":"<p>Gets an authenticated Secret Manager Service client.</p> <p>Returns:</p> Type Description <code>SecretManagerServiceClient</code> <p>An authenticated Secret Manager Service client.</p> <p>Examples:</p> <p>Gets a GCP Secret Manager client from a path. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_file = \"~/.secrets/prefect-service-account.json\"\n    client = GcpCredentials(\n        service_account_file=service_account_file\n    ).get_secret_manager_client()\nexample_get_client_flow()\n</code></pre></p> <p>Gets a GCP Cloud Storage client from a dictionary. <pre><code>from prefect import flow\nfrom prefect_gcp.credentials import GcpCredentials\n\n@flow()\ndef example_get_client_flow():\n    service_account_info = {\n        \"type\": \"service_account\",\n        \"project_id\": \"project_id\",\n        \"private_key_id\": \"private_key_id\",\n        \"private_key\": \"private_key\",\n        \"client_email\": \"client_email\",\n        \"client_id\": \"client_id\",\n        \"auth_uri\": \"auth_uri\",\n        \"token_uri\": \"token_uri\",\n        \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n        \"client_x509_cert_url\": \"client_x509_cert_url\"\n    }\n    client = GcpCredentials(\n        service_account_info=service_account_info\n    ).get_secret_manager_client()\nexample_get_client_flow()\n</code></pre></p> Source code in <code>prefect_gcp/credentials.py</code> <pre><code>@_raise_help_msg(\"secret_manager\")\ndef get_secret_manager_client(self) -&gt; \"SecretManagerServiceClient\":\n    \"\"\"\n    Gets an authenticated Secret Manager Service client.\n\n    Returns:\n        An authenticated Secret Manager Service client.\n\n    Examples:\n        Gets a GCP Secret Manager client from a path.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_file = \"~/.secrets/prefect-service-account.json\"\n            client = GcpCredentials(\n                service_account_file=service_account_file\n            ).get_secret_manager_client()\n        example_get_client_flow()\n        ```\n\n        Gets a GCP Cloud Storage client from a dictionary.\n        ```python\n        from prefect import flow\n        from prefect_gcp.credentials import GcpCredentials\n\n        @flow()\n        def example_get_client_flow():\n            service_account_info = {\n                \"type\": \"service_account\",\n                \"project_id\": \"project_id\",\n                \"private_key_id\": \"private_key_id\",\n                \"private_key\": \"private_key\",\n                \"client_email\": \"client_email\",\n                \"client_id\": \"client_id\",\n                \"auth_uri\": \"auth_uri\",\n                \"token_uri\": \"token_uri\",\n                \"auth_provider_x509_cert_url\": \"auth_provider_x509_cert_url\",\n                \"client_x509_cert_url\": \"client_x509_cert_url\"\n            }\n            client = GcpCredentials(\n                service_account_info=service_account_info\n            ).get_secret_manager_client()\n        example_get_client_flow()\n        ```\n    \"\"\"\n    credentials = self.get_credentials_from_service_account()\n\n    # doesn't accept project; must pass in project in tasks\n    secret_manager_client = SecretManagerServiceClient(credentials=credentials)\n    return secret_manager_client\n</code></pre>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/","title":"Google Cloud Run Worker Guide","text":""},{"location":"integrations/prefect-gcp/gcp-worker-guide/#why-use-google-cloud-run-for-flow-run-execution","title":"Why use Google Cloud Run for flow run execution?","text":"<p>Google Cloud Run is a fully managed compute platform that automatically scales your containerized applications.</p> <ol> <li> <p>Serverless architecture: Cloud Run follows a serverless architecture, which means you don't need to manage any underlying infrastructure. Google Cloud Run automatically handles the scaling and availability of your flow run infrastructure, allowing you to focus on developing and deploying your code.</p> </li> <li> <p>Scalability: Cloud Run can automatically scale your pipeline to handle varying workloads and traffic. It can quickly respond to increased demand and scale back down during low activity periods, ensuring efficient resource utilization.</p> </li> <li> <p>Integration with Google Cloud services: Google Cloud Run easily integrates with other Google Cloud services, such as Google Cloud Storage, Google Cloud Pub/Sub, and Google Cloud Build. This interoperability enables you to build end-to-end data pipelines that use a variety of services.</p> </li> <li> <p>Portability: Since Cloud Run uses container images, you can develop your pipelines locally using Docker and then deploy them on Google Cloud Run without significant modifications. This portability allows you to run the same pipeline in different environments.</p> </li> </ol>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#google-cloud-run-guide","title":"Google Cloud Run guide","text":"<p>After completing this guide, you will have:</p> <ol> <li>Created a Google Cloud Service Account</li> <li>Created a Prefect Work Pool</li> <li>Deployed a Prefect Worker as a Cloud Run Service</li> <li>Deployed a Flow</li> <li>Executed the Flow as a Google Cloud Run Job</li> </ol> <p>If you're looking for a general introduction to workers, work pools, and deployments, check out the workers and work pools tutorial.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#prerequisites","title":"Prerequisites","text":"<p>Before starting this guide, make sure you have:</p> <ul> <li>A Google Cloud Platform (GCP) account.</li> <li>A project on your GCP account where you have the necessary permissions to create Cloud Run Services and Service Accounts.</li> <li>The <code>gcloud</code> CLI installed on your local machine. You can follow Google Cloud's installation guide. If you're using Apple (or a Linux system) you can also use Homebrew for installation.</li> <li>Docker installed on your local machine.</li> <li>A Prefect server instance. You can sign up for a forever free Prefect Cloud Account or, alternatively, self-host a Prefect server.</li> </ul>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-1-create-a-google-cloud-service-account","title":"Step 1. Create a Google Cloud service account","text":"<p>First, open a terminal or command prompt on your local machine where <code>gcloud</code> is installed. If you haven't already authenticated with <code>gcloud</code>, run the following command and follow the instructions to log in to your GCP account.</p> <pre><code>gcloud auth login\n</code></pre> <p>Next, you'll set your project where you'd like to create the service account. Use the following command and replace <code>&lt;PROJECT_ID&gt;</code> with your GCP project's ID.</p> <pre><code>gcloud config set project &lt;PROJECT-ID&gt;\n</code></pre> <p>For example, if your project's ID is <code>prefect-project</code> the command will look like this:</p> <pre><code>gcloud config set project prefect-project\n</code></pre> <p>Now you're ready to make the service account. To do so, you'll need to run this command:</p> <pre><code>gcloud iam service-accounts create &lt;SERVICE-ACCOUNT-NAME&gt; --display-name=\"&lt;DISPLAY-NAME&gt;\"\n</code></pre> <p>Here's an example of the command above which you can use which already has the service account name and display name provided. An additional option to describe the service account has also been added:</p> <pre><code>gcloud iam service-accounts create prefect-service-account \\\n    --description=\"service account to use for the prefect worker\" \\\n    --display-name=\"prefect-service-account\"\n</code></pre> <p>The last step of this process is to make sure the service account has the proper permissions to execute flow runs as Cloud Run jobs. Run the following commands to grant the necessary permissions:</p> <p><pre><code>gcloud projects add-iam-policy-binding &lt;PROJECT-ID&gt; \\\n    --member=\"serviceAccount:&lt;SERVICE-ACCOUNT-NAME&gt;@&lt;PROJECT-ID&gt;.iam.gserviceaccount.com\" \\\n    --role=\"roles/iam.serviceAccountUser\"\n</code></pre> <pre><code>gcloud projects add-iam-policy-binding &lt;PROJECT-ID&gt; \\\n    --member=\"serviceAccount:&lt;SERVICE-ACCOUNT-NAME&gt;@&lt;PROJECT-ID&gt;.iam.gserviceaccount.com\" \\\n    --role=\"roles/run.admin\"\n</code></pre></p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-2-create-a-cloud-run-work-pool","title":"Step 2. Create a Cloud Run work pool","text":"<p>Let's walk through the process of creating a Cloud Run work pool.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#fill-out-the-work-pool-base-job-template","title":"Fill out the work pool base job template","text":"<p>You can create a new work pool using the Prefect UI or CLI. The following command creates a work pool of type <code>cloud-run</code> via the CLI (you'll want to replace the <code>&lt;WORK-POOL-NAME&gt;</code> with the name of your work pool): <pre><code>prefect work-pool create --type cloud-run &lt;WORK-POOL-NAME&gt;\n</code></pre></p> <p>Once the work pool is created, find the work pool in the UI and edit it.</p> <p>There are many ways to customize the base job template for the work pool. Modifying the template influences the infrastructure configuration that the worker provisions for flow runs submitted to the work pool. For this guide we are going to modify just a few of the available fields.</p> <p>Specify the region for the cloud run job.</p> <p></p> <p>Save the name of the service account created in first step of this guide.</p> <p></p> <p>Your work pool is now ready to receive scheduled flow runs!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-3-deploy-a-cloud-run-worker","title":"Step 3. Deploy a Cloud Run worker","text":"<p>Now you can launch a Cloud Run service to host the Cloud Run worker. This worker will poll the work pool that you created in the previous step.</p> <p>Navigate back to your terminal and run the following commands to set your Prefect API key and URL as environment variables. Be sure to replace <code>&lt;ACCOUNT-ID&gt;</code> and <code>&lt;WORKSPACE-ID&gt;</code> with your Prefect account and workspace IDs (both will be available in the URL of the UI when previewing the workspace dashboard). You'll want to replace <code>&lt;YOUR-API-KEY&gt;</code> with an active API key as well.</p> <pre><code>export PREFECT_API_URL='https://api.prefect.cloud/api/accounts/&lt;ACCOUNT-ID&gt;/workspaces/&lt;WORKSPACE-ID&gt;'\nexport PREFECT_API_KEY='&lt;YOUR-API-KEY&gt;'\n</code></pre> <p>Once those variables are set, run the following shell command to deploy your worker as a service. Don't forget to replace <code>&lt;YOUR-SERVICE-ACCOUNT-NAME&gt;</code> with the name of the service account you created in the first step of this guide, and replace <code>&lt;WORK-POOL-NAME&gt;</code> with the name of the work pool you created in the second step.</p> <pre><code>gcloud run deploy prefect-worker --image=prefecthq/prefect:2-latest \\\n--set-env-vars PREFECT_API_URL=$PREFECT_API_URL,PREFECT_API_KEY=$PREFECT_API_KEY \\\n--service-account &lt;YOUR-SERVICE-ACCOUNT-NAME&gt; \\\n--no-cpu-throttling \\\n--min-instances 1 \\\n--args \"prefect\",\"worker\",\"start\",\"--install-policy\",\"always\",\"--with-healthcheck\",\"-p\",\"&lt;WORK-POOL-NAME&gt;\",\"-t\",\"cloud-run\"\n</code></pre> <p>After running this command, you'll be prompted to specify a region. Choose the same region that you selected when creating the Cloud Run work pool in the second step of this guide. The next prompt will ask if you'd like to allow unauthentiated invocations to your worker. For this guide, you can select \"No\".</p> <p>After a few seconds, you'll be able to see your new <code>prefect-worker</code> service by navigating to the Cloud Run page of your Google Cloud console. Additionally, you should be able to see a record of this worker in the Prefect UI on the work pool's page by navigating to the <code>Worker</code> tab. Let's not leave our worker hanging, it's time to give it a job.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-4-deploy-a-flow","title":"Step 4. Deploy a flow","text":"<p>Let's prepare a flow to run as a Cloud Run job. In this section of the guide, we'll \"bake\" our code into a Docker image, and push that image to Google Artifact Registry.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#create-a-registry","title":"Create a registry","text":"<p>Let's create a docker repository in your Google Artifact Registry to host your custom image. If you already have a registry, and are authenticated to it, skip ahead to the Write a flow section.</p> <p>The following command creates a repository using the gcloud CLI. You'll want to replace the <code>&lt;REPOSITORY-NAME&gt;</code> with your own value. : <pre><code>gcloud artifacts repositories create &lt;REPOSITORY-NAME&gt; \\\n--repository-format=docker --location=us\n</code></pre></p> <p>Now you can authenticate to artifact registry: <pre><code>gcloud auth configure-docker us-docker.pkg.dev\n</code></pre></p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#write-a-flow","title":"Write a flow","text":"<p>First, create a new directory. This will serve as the root of your project's repository. Within the directory, create a sub-directory called <code>flows</code>. Navigate to the <code>flows</code> subdirectory and create a new file for your flow. Feel free to write your own flow, but here's a ready-made one for your convenience:</p> <pre><code>import httpx\nfrom prefect import flow, task\nfrom prefect.artifacts import create_markdown_artifact\n\n@task\ndef mark_it_down(temp):\n    markdown_report = f\"\"\"# Weather Report\n## Recent weather\n\n| Time        | Temperature |\n|:--------------|-------:|\n| Now | {temp} |\n| In 1 hour       | {temp + 2} |\n\"\"\"\n    create_markdown_artifact(\n        key=\"weather-report\",\n        markdown=markdown_report,\n        description=\"Very scientific weather report\",\n    )\n\n\n@flow\ndef fetch_weather(lat: float, lon: float):\n    base_url = \"https://api.open-meteo.com/v1/forecast/\"\n    weather = httpx.get(\n        base_url,\n        params=dict(latitude=lat, longitude=lon, hourly=\"temperature_2m\"),\n    )\n    most_recent_temp = float(weather.json()[\"hourly\"][\"temperature_2m\"][0])\n    mark_it_down(most_recent_temp)\n\n\nif __name__ == \"__main__\":\n    fetch_weather(38.9, -77.0)\n</code></pre> <p>In the remainder of this guide, this script will be referred to as <code>weather_flow.py</code>, but you can name yours whatever you'd like.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#creating-a-prefectyaml-file","title":"Creating a <code>prefect.yaml</code> file","text":"<p>Now we're ready to make a <code>prefect.yaml</code> file, which will be responsible for managing the deployments of this repository. Navigate back to the root of your directory, and run the following command to create a <code>prefect.yaml</code> file using Prefect's docker deployment recipe.</p> <pre><code>prefect init --recipe docker\n</code></pre> <p>You'll receive a prompt to put in values for the image name and tag. Since we will be pushing the image to Google Artifact Registry, the name of your image should be prefixed with the path to the docker repository you created within the registry. For example: <code>us-docker.pkg.dev/&lt;PROJECT-ID&gt;/&lt;REPOSITORY-NAME&gt;/</code>. You'll want to replace <code>&lt;PROJECT-ID&gt;</code> with the ID of your project in GCP. This should match the ID of the project you used in first step of this guide. Here is an example of what this could look like:</p> <pre><code>image_name: us-docker.pkg.dev/prefect-project/my-artifact-registry/gcp-weather-image\ntag: latest\n</code></pre> <p>At this point, there will be a new <code>prefect.yaml</code> file available at the root of your project. The contents will look similar to the example below, however, I've added in a combination of yaml templating options and prefect deployment actions to build out a simple CI/CD process. Feel free to copy the contents and paste them in your prefect.yaml:</p> <pre><code># Welcome to your prefect.yaml file! You can you this file for storing and managing\n# configuration for deploying your flows. We recommend committing this file to source\n# control along with your flow code.\n\n# Generic metadata about this project\nname: &lt;WORKING-DIRECTORY&gt;\nprefect-version: 2.13.4\n\n# build section allows you to manage and build docker image\nbuild:\n- prefect_docker.deployments.steps.build_docker_image:\n    id: build_image\n    requires: prefect-docker&gt;=0.3.1\n    image_name: &lt;PATH-TO-ARTIFACT-REGISTRY&gt;/gcp-weather-image\n    tag: latest\n    dockerfile: auto\n    platform: linux/amd64\n\n# push section allows you to manage if and how this project is uploaded to remote locations\npush:\n- prefect_docker.deployments.steps.push_docker_image:\n    requires: prefect-docker&gt;=0.3.1\n    image_name: '{{ build_image.image_name }}'\n    tag: '{{ build_image.tag }}'\n\n# pull section allows you to provide instructions for cloning this project in remote locations\npull:\n- prefect.deployments.steps.set_working_directory:\n    directory: /opt/prefect/&lt;WORKING-DIRECTORY&gt;\n\n# the deployments section allows you to provide configuration for deploying flows\ndeployments:\n- name: gcp-weather-deploy\n  version: null\n  tags: []\n  description: null\n  schedule: {}\n  flow_name: null\n  entrypoint: flows/weather_flow.py:fetch_weather\n  parameters:\n    lat: 14.5994\n    lon: 28.6731\n  work_pool:\n    name: my-cloud-run-pool\n    work_queue_name: default\n    job_variables:\n      image: '{{ build_image.image }}'\n</code></pre> <p>Tip</p> <p>After copying the example above, don't forget to replace <code>&lt;WORKING-DIRECTORY&gt;</code> with the name of the directory where your flow folder and <code>prefect.yaml</code> live. You'll also need to replace <code>&lt;PATH-TO-ARTIFACT-REGISTRY&gt;</code> with the path to the Docker repository in your Google Artifact Registry. </p> <p>To get a better understanding of the different components of the <code>prefect.yaml</code> file above and what they do, feel free to read this next section. Otherwise, you can skip ahead to Flow Deployment.</p> <p>In the <code>build</code> section of the <code>prefect.yaml</code> the following step is executed at deployment build time:</p> <ol> <li><code>prefect_docker.deployments.steps.build_docker_image</code> : builds a Docker image automatically which uses the name and tag chosen previously.</li> </ol> <p>Warning</p> <p>If you are using an ARM-based chip (such as an M1 or M2 Mac), you'll want to ensure that you add <code>platform: linux/amd64</code> to your <code>build_docker_image</code> step to ensure that your docker image uses an AMD architecture. For example:</p> <pre><code>- prefect_docker.deployments.steps.build_docker_image:\nid: build_image\nrequires: prefect-docker&gt;=0.3.1\nimage_name: us-docker.pkg.dev/prefect-project/my-docker-repository/gcp-weather-image\ntag: latest\ndockerfile: auto\nplatform: linux/amd64\n</code></pre> <p>The <code>push</code> section sends the Docker image to the Docker repository in your Google Artifact Registry, so that it can be easily accessed by the worker for flow run execution.</p> <p>The <code>pull</code> section sets the working directory for the process prior to importing your flow.</p> <p>In the <code>deployments</code> section of the <code>prefect.yaml</code> file above, you'll see that there is a deployment declaration named <code>gcp-weather-deploy</code>. Within the declaration, the entrypoint for the flow is specified along with some default parameters which will be passed to the flow at runtime. Last but not least, the name of the workpool that we created in step 2 of this guide is specified.</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#flow-deployment","title":"Flow deployment","text":"<p>Once you're happy with the specifications in the <code>prefect.yaml</code> file, run the following command in the terminal to deploy your flow:</p> <pre><code>prefect deploy --name gcp-weather-deploy\n</code></pre> <p>Once the flow is deployed to Prefect Cloud or your local Prefect Server, it's time to queue up a flow run!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#step-5-flow-execution","title":"Step 5. Flow execution","text":"<p>Find your deployment in the UI, and hit the Quick Run button. You have now successfully submitted a flow run to your Cloud Run worker! If you used the flow script provided in this guide, check the Artifacts tab for the flow run once it completes. You'll have a nice little weather report waiting for you there. Hope your day is a sunny one!</p>"},{"location":"integrations/prefect-gcp/gcp-worker-guide/#recap-and-next-steps","title":"Recap and next steps","text":"<p>Congratulations on completing this guide! Looking back on our journey, you have:</p> <ol> <li>Created a Google Cloud service account</li> <li>Created a Cloud Run work pool</li> <li>Deployed a Cloud Run worker</li> <li>Deployed a flow</li> <li>Executed a flow</li> </ol> <p>For next steps, you could:</p> <ul> <li>Take a look at some of the other work pools Prefect has to offer</li> <li>Do a deep drive on Prefect concepts</li> <li>Try out another guide to explore new deployment patterns and recipes</li> </ul> <p>The world is your oyster \ud83e\uddaa\u2728.</p>"},{"location":"integrations/prefect-gcp/secret_manager/","title":"Secret Manager","text":""},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager","title":"<code>prefect_gcp.secret_manager</code>","text":""},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret","title":"<code>GcpSecret</code>","text":"<p>               Bases: <code>SecretBlock</code></p> <p>Manages a secret in Google Cloud Platform's Secret Manager.</p> <p>Attributes:</p> Name Type Description <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> <code>secret_name</code> <code>str</code> <p>Name of the secret to manage.</p> <code>secret_version</code> <code>str</code> <p>Version number of the secret to use, or \"latest\".</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>class GcpSecret(SecretBlock):\n    \"\"\"\n    Manages a secret in Google Cloud Platform's Secret Manager.\n\n    Attributes:\n        gcp_credentials: Credentials to use for authentication with GCP.\n        secret_name: Name of the secret to manage.\n        secret_version: Version number of the secret to use, or \"latest\".\n    \"\"\"\n\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret\"  # noqa: E501\n\n    gcp_credentials: GcpCredentials\n    secret_name: str = Field(default=..., description=\"Name of the secret to manage.\")\n    secret_version: str = Field(\n        default=\"latest\", description=\"Version number of the secret to use.\"\n    )\n\n    @sync_compatible\n    async def read_secret(self) -&gt; bytes:\n        \"\"\"\n        Reads the secret data from the secret storage service.\n\n        Returns:\n            The secret data as bytes.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n        name = f\"projects/{project}/secrets/{self.secret_name}/versions/{self.secret_version}\"  # noqa\n        request = AccessSecretVersionRequest(name=name)\n\n        self.logger.debug(f\"Preparing to read secret data from {name!r}.\")\n        response = await run_sync_in_worker_thread(\n            client.access_secret_version, request=request\n        )\n        secret = response.payload.data\n        self.logger.info(f\"The secret {name!r} data was successfully read.\")\n        return secret\n\n    @sync_compatible\n    async def write_secret(self, secret_data: bytes) -&gt; str:\n        \"\"\"\n        Writes the secret data to the secret storage service; if it doesn't exist\n        it will be created.\n\n        Args:\n            secret_data: The secret to write.\n\n        Returns:\n            The path that the secret was written to.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n        parent = f\"projects/{project}/secrets/{self.secret_name}\"\n        payload = SecretPayload(data=secret_data)\n        add_request = AddSecretVersionRequest(parent=parent, payload=payload)\n\n        self.logger.debug(f\"Preparing to write secret data to {parent!r}.\")\n        try:\n            response = await run_sync_in_worker_thread(\n                client.add_secret_version, request=add_request\n            )\n        except NotFound:\n            self.logger.info(\n                f\"The secret {parent!r} does not exist yet, creating it now.\"\n            )\n            create_parent = f\"projects/{project}\"\n            secret_id = self.secret_name\n            secret = Secret(replication=Replication(automatic=Replication.Automatic()))\n            create_request = CreateSecretRequest(\n                parent=create_parent, secret_id=secret_id, secret=secret\n            )\n            await run_sync_in_worker_thread(\n                client.create_secret, request=create_request\n            )\n\n            self.logger.debug(f\"Preparing to write secret data to {parent!r} again.\")\n            response = await run_sync_in_worker_thread(\n                client.add_secret_version, request=add_request\n            )\n\n        self.logger.info(f\"The secret data was written successfully to {parent!r}.\")\n        return response.name\n\n    @sync_compatible\n    async def delete_secret(self) -&gt; str:\n        \"\"\"\n        Deletes the secret from the secret storage service.\n\n        Returns:\n            The path that the secret was deleted from.\n        \"\"\"\n        client = self.gcp_credentials.get_secret_manager_client()\n        project = self.gcp_credentials.project\n\n        name = f\"projects/{project}/secrets/{self.secret_name}\"\n        request = DeleteSecretRequest(name=name)\n\n        self.logger.debug(f\"Preparing to delete the secret {name!r}.\")\n        await run_sync_in_worker_thread(client.delete_secret, request=request)\n        self.logger.info(f\"The secret {name!r} was successfully deleted.\")\n        return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the secret from the secret storage service.</p> <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was deleted from.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def delete_secret(self) -&gt; str:\n    \"\"\"\n    Deletes the secret from the secret storage service.\n\n    Returns:\n        The path that the secret was deleted from.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{self.secret_name}\"\n    request = DeleteSecretRequest(name=name)\n\n    self.logger.debug(f\"Preparing to delete the secret {name!r}.\")\n    await run_sync_in_worker_thread(client.delete_secret, request=request)\n    self.logger.info(f\"The secret {name!r} was successfully deleted.\")\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the secret data from the secret storage service.</p> <p>Returns:</p> Type Description <code>bytes</code> <p>The secret data as bytes.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def read_secret(self) -&gt; bytes:\n    \"\"\"\n    Reads the secret data from the secret storage service.\n\n    Returns:\n        The secret data as bytes.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n    name = f\"projects/{project}/secrets/{self.secret_name}/versions/{self.secret_version}\"  # noqa\n    request = AccessSecretVersionRequest(name=name)\n\n    self.logger.debug(f\"Preparing to read secret data from {name!r}.\")\n    response = await run_sync_in_worker_thread(\n        client.access_secret_version, request=request\n    )\n    secret = response.payload.data\n    self.logger.info(f\"The secret {name!r} data was successfully read.\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.GcpSecret.write_secret","title":"<code>write_secret</code>  <code>async</code>","text":"<p>Writes the secret data to the secret storage service; if it doesn't exist it will be created.</p> <p>Parameters:</p> Name Type Description Default <code>secret_data</code> <code>bytes</code> <p>The secret to write.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The path that the secret was written to.</p> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@sync_compatible\nasync def write_secret(self, secret_data: bytes) -&gt; str:\n    \"\"\"\n    Writes the secret data to the secret storage service; if it doesn't exist\n    it will be created.\n\n    Args:\n        secret_data: The secret to write.\n\n    Returns:\n        The path that the secret was written to.\n    \"\"\"\n    client = self.gcp_credentials.get_secret_manager_client()\n    project = self.gcp_credentials.project\n    parent = f\"projects/{project}/secrets/{self.secret_name}\"\n    payload = SecretPayload(data=secret_data)\n    add_request = AddSecretVersionRequest(parent=parent, payload=payload)\n\n    self.logger.debug(f\"Preparing to write secret data to {parent!r}.\")\n    try:\n        response = await run_sync_in_worker_thread(\n            client.add_secret_version, request=add_request\n        )\n    except NotFound:\n        self.logger.info(\n            f\"The secret {parent!r} does not exist yet, creating it now.\"\n        )\n        create_parent = f\"projects/{project}\"\n        secret_id = self.secret_name\n        secret = Secret(replication=Replication(automatic=Replication.Automatic()))\n        create_request = CreateSecretRequest(\n            parent=create_parent, secret_id=secret_id, secret=secret\n        )\n        await run_sync_in_worker_thread(\n            client.create_secret, request=create_request\n        )\n\n        self.logger.debug(f\"Preparing to write secret data to {parent!r} again.\")\n        response = await run_sync_in_worker_thread(\n            client.add_secret_version, request=add_request\n        )\n\n    self.logger.info(f\"The secret data was written successfully to {parent!r}.\")\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.create_secret","title":"<code>create_secret</code>  <code>async</code>","text":"<p>Creates a secret in Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the created secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import create_secret\n\n@flow()\ndef example_cloud_storage_create_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = create_secret(\"secret_name\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_create_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def create_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Creates a secret in Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the created secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import create_secret\n\n        @flow()\n        def example_cloud_storage_create_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = create_secret(\"secret_name\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_create_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Creating the %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    parent = f\"projects/{project}\"\n    secret_settings = {\"replication\": {\"automatic\": {}}}\n\n    partial_create = partial(\n        client.create_secret,\n        parent=parent,\n        secret_id=secret_name,\n        secret=secret_settings,\n        timeout=timeout,\n    )\n    response = await to_thread.run_sync(partial_create)\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.delete_secret","title":"<code>delete_secret</code>  <code>async</code>","text":"<p>Deletes the specified secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to delete.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the deleted secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import delete_secret\n\n@flow()\ndef example_cloud_storage_delete_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = delete_secret(\"secret_name\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_delete_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def delete_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Deletes the specified secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to delete.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the deleted secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import delete_secret\n\n        @flow()\n        def example_cloud_storage_delete_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = delete_secret(\"secret_name\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_delete_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Deleting %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{secret_name}/\"\n    partial_delete = partial(client.delete_secret, name=name, timeout=timeout)\n    await to_thread.run_sync(partial_delete)\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.delete_secret_version","title":"<code>delete_secret_version</code>  <code>async</code>","text":"<p>Deletes a version of a given secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>version_id</code> <code>int</code> <p>Version number of the secret to use; \"latest\" can NOT be used.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the deleted secret version.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import delete_secret_version\n\n@flow()\ndef example_cloud_storage_delete_secret_version_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_value = delete_secret_version(\"secret_name\", 1, gcp_credentials)\n    return secret_value\n\nexample_cloud_storage_delete_secret_version_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def delete_secret_version(\n    secret_name: str,\n    version_id: int,\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Deletes a version of a given secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        version_id: Version number of the secret to use; \"latest\" can NOT be used.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the deleted secret version.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import delete_secret_version\n\n        @flow()\n        def example_cloud_storage_delete_secret_version_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_value = delete_secret_version(\"secret_name\", 1, gcp_credentials)\n            return secret_value\n\n        example_cloud_storage_delete_secret_version_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Reading %s version of %s secret\", version_id, secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    if version_id == \"latest\":\n        raise ValueError(\"The version_id cannot be 'latest'\")\n\n    name = f\"projects/{project}/secrets/{secret_name}/versions/{version_id}\"\n    partial_destroy = partial(client.destroy_secret_version, name=name, timeout=timeout)\n    await to_thread.run_sync(partial_destroy)\n    return name\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.read_secret","title":"<code>read_secret</code>  <code>async</code>","text":"<p>Reads the value of a given secret from Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>Contents of the specified secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import read_secret\n\n@flow()\ndef example_cloud_storage_read_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_value = read_secret(\"secret_name\", gcp_credentials, version_id=1)\n    return secret_value\n\nexample_cloud_storage_read_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def read_secret(\n    secret_name: str,\n    gcp_credentials: \"GcpCredentials\",\n    version_id: Union[str, int] = \"latest\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Reads the value of a given secret from Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        Contents of the specified secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import read_secret\n\n        @flow()\n        def example_cloud_storage_read_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_value = read_secret(\"secret_name\", gcp_credentials, version_id=1)\n            return secret_value\n\n        example_cloud_storage_read_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Reading %s version of %s secret\", version_id, secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    name = f\"projects/{project}/secrets/{secret_name}/versions/{version_id}\"\n    partial_access = partial(client.access_secret_version, name=name, timeout=timeout)\n    response = await to_thread.run_sync(partial_access)\n    secret = response.payload.data.decode(\"UTF-8\")\n    return secret\n</code></pre>"},{"location":"integrations/prefect-gcp/secret_manager/#prefect_gcp.secret_manager.update_secret","title":"<code>update_secret</code>  <code>async</code>","text":"<p>Updates a secret in Google Cloud Platform's Secret Manager.</p> <p>Parameters:</p> Name Type Description Default <code>secret_name</code> <code>str</code> <p>Name of the secret to retrieve.</p> required <code>secret_value</code> <code>Union[str, bytes]</code> <p>Desired value of the secret. Can be either <code>str</code> or <code>bytes</code>.</p> required <code>gcp_credentials</code> <code>GcpCredentials</code> <p>Credentials to use for authentication with GCP.</p> required <code>timeout</code> <code>float</code> <p>The number of seconds the transport should wait for the server response.</p> <code>60</code> <code>project</code> <code>Optional[str]</code> <p>Name of the project to use; overrides the gcp_credentials project if provided.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The path of the updated secret.</p> Example <pre><code>from prefect import flow\nfrom prefect_gcp import GcpCredentials\nfrom prefect_gcp.secret_manager import update_secret\n\n@flow()\ndef example_cloud_storage_update_secret_flow():\n    gcp_credentials = GcpCredentials(project=\"project\")\n    secret_path = update_secret(\"secret_name\", \"secret_value\", gcp_credentials)\n    return secret_path\n\nexample_cloud_storage_update_secret_flow()\n</code></pre> Source code in <code>prefect_gcp/secret_manager.py</code> <pre><code>@task\nasync def update_secret(\n    secret_name: str,\n    secret_value: Union[str, bytes],\n    gcp_credentials: \"GcpCredentials\",\n    timeout: float = 60,\n    project: Optional[str] = None,\n) -&gt; str:\n    \"\"\"\n    Updates a secret in Google Cloud Platform's Secret Manager.\n\n    Args:\n        secret_name: Name of the secret to retrieve.\n        secret_value: Desired value of the secret. Can be either `str` or `bytes`.\n        gcp_credentials: Credentials to use for authentication with GCP.\n        timeout: The number of seconds the transport should wait\n            for the server response.\n        project: Name of the project to use; overrides the\n            gcp_credentials project if provided.\n\n    Returns:\n        The path of the updated secret.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_gcp import GcpCredentials\n        from prefect_gcp.secret_manager import update_secret\n\n        @flow()\n        def example_cloud_storage_update_secret_flow():\n            gcp_credentials = GcpCredentials(project=\"project\")\n            secret_path = update_secret(\"secret_name\", \"secret_value\", gcp_credentials)\n            return secret_path\n\n        example_cloud_storage_update_secret_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n    logger.info(\"Updating the %s secret\", secret_name)\n\n    client = gcp_credentials.get_secret_manager_client()\n    project = project or gcp_credentials.project\n\n    parent = f\"projects/{project}/secrets/{secret_name}\"\n    if isinstance(secret_value, str):\n        secret_value = secret_value.encode(\"UTF-8\")\n    partial_add = partial(\n        client.add_secret_version,\n        parent=parent,\n        payload={\"data\": secret_value},\n        timeout=timeout,\n    )\n    response = await to_thread.run_sync(partial_add)\n    return response.name\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/","title":"Vertex AI","text":""},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex","title":"<code>prefect_gcp.workers.vertex</code>","text":"<p>Module containing the custom worker used for executing flow runs as Vertex AI Custom Jobs.</p> <p>Get started by creating a Cloud Run work pool:</p> <pre><code>prefect work-pool create 'my-vertex-pool' --type vertex-ai\n</code></pre> <p>Then start a Cloud Run worker with the following command:</p> <pre><code>prefect worker start --pool 'my-vertex-pool'\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex--configuration","title":"Configuration","text":"<p>Read more about configuring work pools here.</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker","title":"<code>VertexAIWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Vertex AI Jobs.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Vertex AI Jobs.\"\"\"\n\n    type = \"vertex-ai\"\n    job_configuration = VertexAIWorkerJobConfiguration\n    job_configuration_variables = VertexAIWorkerVariables\n    _description = (\n        \"Execute flow runs within containers on Google Vertex AI. Requires \"\n        \"a Google Cloud Platform account.\"\n    )\n    _display_name = \"Google Vertex AI\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-gcp/vertex_worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/10424e311932e31c477ac2b9ef3d53cefbaad708-250x250.png\"  # noqa\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: VertexAIWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; VertexAIWorkerResult:\n        \"\"\"\n        Executes a flow run within a Vertex AI Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            VertexAIWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n\n        client_options = ClientOptions(\n            api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n        )\n\n        job_name = configuration.job_name\n\n        job_spec = self._build_job_spec(configuration)\n        job_service_async_client = (\n            configuration.credentials.get_job_service_async_client(\n                client_options=client_options\n            )\n        )\n\n        job_run = await self._create_and_begin_job(\n            job_name,\n            job_spec,\n            job_service_async_client,\n            configuration,\n            logger,\n        )\n\n        if task_status:\n            task_status.started(job_run.name)\n\n        final_job_run = await self._watch_job_run(\n            job_name=job_name,\n            full_job_name=job_run.name,\n            job_service_async_client=job_service_async_client,\n            current_state=job_run.state,\n            until_states=(\n                JobState.JOB_STATE_SUCCEEDED,\n                JobState.JOB_STATE_FAILED,\n                JobState.JOB_STATE_CANCELLED,\n                JobState.JOB_STATE_EXPIRED,\n            ),\n            configuration=configuration,\n            logger=logger,\n            timeout=int(\n                datetime.timedelta(\n                    hours=configuration.job_spec[\"maximum_run_time_hours\"]\n                ).total_seconds()\n            ),\n        )\n\n        error_msg = final_job_run.error.message\n\n        # Vertex will include an error message upon valid\n        # flow cancellations, so we'll avoid raising an error in that case\n        if error_msg and \"CANCELED\" not in error_msg:\n            raise RuntimeError(error_msg)\n\n        status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n        return VertexAIWorkerResult(\n            identifier=final_job_run.display_name, status_code=status_code\n        )\n\n    def _build_job_spec(\n        self, configuration: VertexAIWorkerJobConfiguration\n    ) -&gt; \"CustomJobSpec\":\n        \"\"\"\n        Builds a job spec by gathering details.\n        \"\"\"\n        # here, we extract the `worker_pool_specs` out of the job_spec\n        worker_pool_specs = [\n            WorkerPoolSpec(\n                container_spec=ContainerSpec(**spec[\"container_spec\"]),\n                machine_spec=MachineSpec(**spec[\"machine_spec\"]),\n                replica_count=spec[\"replica_count\"],\n                disk_spec=DiskSpec(**spec[\"disk_spec\"]),\n            )\n            for spec in configuration.job_spec.pop(\"worker_pool_specs\", [])\n        ]\n\n        timeout = Duration().FromTimedelta(\n            td=datetime.timedelta(\n                hours=configuration.job_spec[\"maximum_run_time_hours\"]\n            )\n        )\n        scheduling = Scheduling(timeout=timeout)\n\n        if \"service_account_name\" in configuration.job_spec:\n            service_account_name = configuration.job_spec.pop(\"service_account_name\")\n            configuration.job_spec[\"service_account\"] = service_account_name\n\n        # construct the final job spec that we will provide to Vertex AI\n        job_spec = CustomJobSpec(\n            worker_pool_specs=worker_pool_specs,\n            scheduling=scheduling,\n            ignore_unknown_fields=True,\n            **configuration.job_spec,\n        )\n        return job_spec\n\n    async def _create_and_begin_job(\n        self,\n        job_name: str,\n        job_spec: \"CustomJobSpec\",\n        job_service_async_client: \"JobServiceAsyncClient\",\n        configuration: VertexAIWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Builds a custom job and begins running it.\n        \"\"\"\n        # create custom job\n        custom_job = CustomJob(\n            display_name=job_name,\n            job_spec=job_spec,\n            labels=self._get_compatible_labels(configuration=configuration),\n        )\n\n        # run job\n        logger.info(f\"Creating job {job_name!r}\")\n\n        project = configuration.project\n        resource_name = f\"projects/{project}/locations/{configuration.region}\"\n\n        async for attempt in AsyncRetrying(\n            stop=stop_after_attempt(3), wait=wait_fixed(1) + wait_random(0, 3)\n        ):\n            with attempt:\n                custom_job_run = await job_service_async_client.create_custom_job(\n                    parent=resource_name,\n                    custom_job=custom_job,\n                )\n\n        logger.info(\n            f\"Job {job_name!r} created. \"\n            f\"The full job name is {custom_job_run.name!r}\"\n        )\n\n        return custom_job_run\n\n    async def _watch_job_run(\n        self,\n        job_name: str,\n        full_job_name: str,  # different from job_name\n        job_service_async_client: \"JobServiceAsyncClient\",\n        current_state: \"JobState\",\n        until_states: Tuple[\"JobState\"],\n        configuration: VertexAIWorkerJobConfiguration,\n        logger: PrefectLogAdapter,\n        timeout: int = None,\n    ) -&gt; \"CustomJob\":\n        \"\"\"\n        Polls job run to see if status changed.\n\n        State changes reported by the Vertex AI API may sometimes be inaccurate\n        immediately upon startup, but should eventually report a correct running\n        and then terminal state. The minimum training duration for a custom job is\n        30 seconds, so short-lived jobs may be marked as successful some time\n        after a flow run has completed.\n        \"\"\"\n        state = JobState.JOB_STATE_UNSPECIFIED\n        last_state = current_state\n        t0 = time.time()\n\n        while state not in until_states:\n            job_run = await job_service_async_client.get_custom_job(\n                name=full_job_name,\n            )\n            state = job_run.state\n            if state != last_state:\n                state_label = (\n                    state.name.replace(\"_\", \" \")\n                    .lower()\n                    .replace(\"state\", \"state is now:\")\n                )\n                # results in \"New job state is now: succeeded\"\n                logger.debug(f\"{job_name} has new {state_label}\")\n                last_state = state\n            else:\n                # Intermittently, the job will not be described. We want to respect the\n                # watch timeout though.\n                logger.debug(f\"Job {job_name} not found.\")\n\n            elapsed_time = time.time() - t0\n            if timeout is not None and elapsed_time &gt; timeout:\n                raise RuntimeError(\n                    f\"Timed out after {elapsed_time}s while watching job for states \"\n                    \"{until_states!r}\"\n                )\n            await asyncio.sleep(configuration.job_watch_poll_interval)\n\n        return job_run\n\n    def _get_compatible_labels(\n        self, configuration: VertexAIWorkerJobConfiguration\n    ) -&gt; Dict[str, str]:\n        \"\"\"\n        Ensures labels are compatible with GCP label requirements.\n        https://cloud.google.com/resource-manager/docs/creating-managing-labels\n\n        Ex: the Prefect provided key of prefect.io/flow-name -&gt; prefect-io_flow-name\n        \"\"\"\n        compatible_labels = {}\n        for key, val in configuration.labels.items():\n            new_key = slugify(\n                key,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n            compatible_labels[new_key] = slugify(\n                val,\n                lowercase=True,\n                replacements=[(\"/\", \"_\"), (\".\", \"-\")],\n                max_length=63,\n                regex_pattern=_DISALLOWED_GCP_LABEL_CHARACTERS,\n            )\n        return compatible_labels\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: VertexAIWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n        Stops a job running in Vertex AI upon flow cancellation,\n        based on the provided infrastructure PID + run configuration.\n        \"\"\"\n        if grace_seconds != 30:\n            self._logger.warning(\n                f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n                \"support dynamic grace period configuration. See here for more info: \"\n                \"https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.customJobs/cancel\"  # noqa\n            )\n\n        client_options = ClientOptions(\n            api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n        )\n        job_service_async_client = (\n            configuration.credentials.get_job_service_async_client(\n                client_options=client_options\n            )\n        )\n        await self._stop_job(\n            client=job_service_async_client,\n            vertex_job_name=infrastructure_pid,\n        )\n\n    async def _stop_job(self, client: \"JobServiceAsyncClient\", vertex_job_name: str):\n        \"\"\"\n        Calls the `cancel_custom_job` method on the Vertex AI Job Service Client.\n        \"\"\"\n        cancel_custom_job_request = CancelCustomJobRequest(name=vertex_job_name)\n        try:\n            await client.cancel_custom_job(\n                request=cancel_custom_job_request,\n            )\n        except Exception as exc:\n            if \"does not exist\" in str(exc):\n                raise InfrastructureNotFound(\n                    f\"Cannot stop Vertex AI job; the job name {vertex_job_name!r} \"\n                    \"could not be found.\"\n                ) from exc\n            raise\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<p>Stops a job running in Vertex AI upon flow cancellation, based on the provided infrastructure PID + run configuration.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: VertexAIWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n    Stops a job running in Vertex AI upon flow cancellation,\n    based on the provided infrastructure PID + run configuration.\n    \"\"\"\n    if grace_seconds != 30:\n        self._logger.warning(\n            f\"Kill grace period of {grace_seconds}s requested, but GCP does not \"\n            \"support dynamic grace period configuration. See here for more info: \"\n            \"https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.customJobs/cancel\"  # noqa\n        )\n\n    client_options = ClientOptions(\n        api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n    )\n    job_service_async_client = (\n        configuration.credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n    )\n    await self._stop_job(\n        client=job_service_async_client,\n        vertex_job_name=infrastructure_pid,\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Vertex AI Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>VertexAIWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>VertexAIWorkerResult</code> <code>VertexAIWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: VertexAIWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; VertexAIWorkerResult:\n    \"\"\"\n    Executes a flow run within a Vertex AI Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        VertexAIWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n\n    client_options = ClientOptions(\n        api_endpoint=f\"{configuration.region}-aiplatform.googleapis.com\"\n    )\n\n    job_name = configuration.job_name\n\n    job_spec = self._build_job_spec(configuration)\n    job_service_async_client = (\n        configuration.credentials.get_job_service_async_client(\n            client_options=client_options\n        )\n    )\n\n    job_run = await self._create_and_begin_job(\n        job_name,\n        job_spec,\n        job_service_async_client,\n        configuration,\n        logger,\n    )\n\n    if task_status:\n        task_status.started(job_run.name)\n\n    final_job_run = await self._watch_job_run(\n        job_name=job_name,\n        full_job_name=job_run.name,\n        job_service_async_client=job_service_async_client,\n        current_state=job_run.state,\n        until_states=(\n            JobState.JOB_STATE_SUCCEEDED,\n            JobState.JOB_STATE_FAILED,\n            JobState.JOB_STATE_CANCELLED,\n            JobState.JOB_STATE_EXPIRED,\n        ),\n        configuration=configuration,\n        logger=logger,\n        timeout=int(\n            datetime.timedelta(\n                hours=configuration.job_spec[\"maximum_run_time_hours\"]\n            ).total_seconds()\n        ),\n    )\n\n    error_msg = final_job_run.error.message\n\n    # Vertex will include an error message upon valid\n    # flow cancellations, so we'll avoid raising an error in that case\n    if error_msg and \"CANCELED\" not in error_msg:\n        raise RuntimeError(error_msg)\n\n    status_code = 0 if final_job_run.state == JobState.JOB_STATE_SUCCEEDED else 1\n\n    return VertexAIWorkerResult(\n        identifier=final_job_run.display_name, status_code=status_code\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration","title":"<code>VertexAIWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Vertex AI Worker to create a Job.</p> <p>An instance of this class is passed to the Vertex AI Worker's <code>run</code> method for each flow run. It contains all information necessary to execute the flow run as a Vertex AI Job.</p> <p>Attributes:</p> Name Type Description <code>region</code> <code>str</code> <p>The region where the Vertex AI Job resides.</p> <code>credentials</code> <code>Optional[GcpCredentials]</code> <p>The GCP Credentials used to connect to Vertex AI.</p> <code>job_spec</code> <code>Dict[str, Any]</code> <p>The Vertex AI Job spec used to create the Job.</p> <code>job_watch_poll_interval</code> <code>float</code> <p>The interval between GCP API calls to check Job state.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Vertex AI Worker to create a Job.\n\n    An instance of this class is passed to the Vertex AI Worker's `run` method\n    for each flow run. It contains all information necessary to execute\n    the flow run as a Vertex AI Job.\n\n    Attributes:\n        region: The region where the Vertex AI Job resides.\n        credentials: The GCP Credentials used to connect to Vertex AI.\n        job_spec: The Vertex AI Job spec used to create the Job.\n        job_watch_poll_interval: The interval between GCP API calls to check Job state.\n    \"\"\"\n\n    region: str = Field(\n        description=\"The region where the Vertex AI Job resides.\",\n        example=\"us-central1\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Vertex AI Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n\n    job_spec: Dict[str, Any] = Field(\n        template={\n            \"service_account_name\": \"{{ service_account_name }}\",\n            \"network\": \"{{ network }}\",\n            \"reserved_ip_ranges\": \"{{ reserved_ip_ranges }}\",\n            \"maximum_run_time_hours\": \"{{ maximum_run_time_hours }}\",\n            \"worker_pool_specs\": [\n                {\n                    \"replica_count\": 1,\n                    \"container_spec\": {\n                        \"image_uri\": \"{{ image }}\",\n                        \"command\": \"{{ command }}\",\n                        \"args\": [],\n                    },\n                    \"machine_spec\": {\n                        \"machine_type\": \"{{ machine_type }}\",\n                        \"accelerator_type\": \"{{ accelerator_type }}\",\n                        \"accelerator_count\": \"{{ accelerator_count }}\",\n                    },\n                    \"disk_spec\": {\n                        \"boot_disk_type\": \"{{ boot_disk_type }}\",\n                        \"boot_disk_size_gb\": \"{{ boot_disk_size_gb }}\",\n                    },\n                }\n            ],\n        }\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        title=\"Poll Interval (Seconds)\",\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n\n    @property\n    def project(self) -&gt; str:\n        \"\"\"property for accessing the project from the credentials.\"\"\"\n        return self.credentials.project\n\n    @property\n    def job_name(self) -&gt; str:\n        \"\"\"\n        The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference:\n        https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name\n        \"\"\"  # noqa\n        unique_suffix = uuid4().hex\n        job_name = f\"{self.name}-{unique_suffix}\"\n        return job_name\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n\n        self._inject_formatted_env_vars()\n        self._inject_formatted_command()\n        self._ensure_existence_of_service_account()\n\n    def _inject_formatted_env_vars(self):\n        \"\"\"Inject environment variables in the Vertex job_spec configuration,\n        in the correct format, which is sourced from the BaseJobConfiguration.\n        This method is invoked by `prepare_for_flow_run()`.\"\"\"\n        worker_pool_specs = self.job_spec[\"worker_pool_specs\"]\n        formatted_env_vars = [\n            {\"name\": key, \"value\": value} for key, value in self.env.items()\n        ]\n        worker_pool_specs[0][\"container_spec\"][\"env\"] = formatted_env_vars\n\n    def _inject_formatted_command(self):\n        \"\"\"Inject shell commands in the Vertex job_spec configuration,\n        in the correct format, which is sourced from the BaseJobConfiguration.\n        Here, we'll ensure that the default string format\n        is converted to a list of strings.\"\"\"\n        worker_pool_specs = self.job_spec[\"worker_pool_specs\"]\n\n        existing_command = worker_pool_specs[0][\"container_spec\"].get(\"command\")\n        if existing_command is None:\n            worker_pool_specs[0][\"container_spec\"][\"command\"] = shlex.split(\n                self._base_flow_run_command()\n            )\n        elif isinstance(existing_command, str):\n            worker_pool_specs[0][\"container_spec\"][\"command\"] = shlex.split(\n                existing_command\n            )\n\n    def _ensure_existence_of_service_account(self):\n        \"\"\"Verify that a service account was provided, either in the credentials\n        or as a standalone service account name override.\"\"\"\n\n        provided_service_account_name = self.job_spec.get(\"service_account_name\")\n        credential_service_account = self.credentials._service_account_email\n\n        service_account_to_use = (\n            provided_service_account_name or credential_service_account\n        )\n\n        if service_account_to_use is None:\n            raise ValueError(\n                \"A service account is required for the Vertex job. \"\n                \"A service account could not be detected in the attached credentials \"\n                \"or in the service_account_name input. \"\n                \"Please pass in valid GCP credentials or a valid service_account_name\"\n            )\n\n        self.job_spec[\"service_account_name\"] = service_account_to_use\n\n    @validator(\"job_spec\")\n    def _ensure_job_spec_includes_required_attributes(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job spec includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_spec())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.job_name","title":"<code>job_name: str</code>  <code>property</code>","text":"<p>The name can be up to 128 characters long and can be consist of any UTF-8 characters. Reference: https://cloud.google.com/python/docs/reference/aiplatform/latest/google.cloud.aiplatform.CustomJob#google_cloud_aiplatform_CustomJob_display_name</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerJobConfiguration.project","title":"<code>project: str</code>  <code>property</code>","text":"<p>property for accessing the project from the credentials.</p>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerResult","title":"<code>VertexAIWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/vertex_worker/#prefect_gcp.workers.vertex.VertexAIWorkerVariables","title":"<code>VertexAIWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Vertex AI worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_gcp/workers/vertex.py</code> <pre><code>class VertexAIWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Vertex AI worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    region: str = Field(\n        description=\"The region where the Vertex AI Job resides.\",\n        example=\"us-central1\",\n    )\n    image: str = Field(\n        title=\"Image Name\",\n        description=(\n            \"The URI of a container image in the Container or Artifact Registry, \"\n            \"used to run your Vertex AI Job. Note that Vertex AI will need access\"\n            \"to the project and region where the container image is stored. See \"\n            \"https://cloud.google.com/vertex-ai/docs/training/create-custom-container\"\n        ),\n        example=\"gcr.io/your-project/your-repo:latest\",\n    )\n    credentials: Optional[GcpCredentials] = Field(\n        title=\"GCP Credentials\",\n        default_factory=GcpCredentials,\n        description=\"The GCP Credentials used to initiate the \"\n        \"Vertex AI Job. If not provided credentials will be \"\n        \"inferred from the local environment.\",\n    )\n    machine_type: str = Field(\n        title=\"Machine Type\",\n        description=(\n            \"The machine type to use for the run, which controls \"\n            \"the available CPU and memory. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        default=\"n1-standard-4\",\n    )\n    accelerator_type: Optional[str] = Field(\n        title=\"Accelerator Type\",\n        description=(\n            \"The type of accelerator to attach to the machine. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        example=\"NVIDIA_TESLA_K80\",\n        default=None,\n    )\n    accelerator_count: Optional[int] = Field(\n        title=\"Accelerator Count\",\n        description=(\n            \"The number of accelerators to attach to the machine. \"\n            \"See https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec\"\n        ),\n        example=1,\n        default=None,\n    )\n    boot_disk_type: str = Field(\n        title=\"Boot Disk Type\",\n        description=\"The type of boot disk to attach to the machine.\",\n        default=\"pd-ssd\",\n    )\n    boot_disk_size_gb: int = Field(\n        title=\"Boot Disk Size (GB)\",\n        description=\"The size of the boot disk to attach to the machine, in gigabytes.\",\n        default=100,\n    )\n    maximum_run_time_hours: int = Field(\n        default=1,\n        title=\"Maximum Run Time (Hours)\",\n        description=\"The maximum job running time, in hours\",\n    )\n    network: Optional[str] = Field(\n        default=None,\n        title=\"Network\",\n        description=\"The full name of the Compute Engine network\"\n        \"to which the Job should be peered. Private services access must \"\n        \"already be configured for the network. If left unspecified, the job \"\n        \"is not peered with any network. \"\n        \"For example: projects/12345/global/networks/myVPC\",\n    )\n    reserved_ip_ranges: Optional[List[str]] = Field(\n        default=None,\n        title=\"Reserved IP Ranges\",\n        description=\"A list of names for the reserved ip ranges under the VPC \"\n        \"network that can be used for this job. If set, we will deploy the job \"\n        \"within the provided ip ranges. Otherwise, the job will be deployed to \"\n        \"any ip ranges under the provided VPC network.\",\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        title=\"Service Account Name\",\n        description=(\n            \"Specifies the service account to use \"\n            \"as the run-as account in Vertex AI. The worker submitting jobs must have \"\n            \"act-as permission on this run-as account. If unspecified, the AI \"\n            \"Platform Custom Code Service Agent for the CustomJob's project is \"\n            \"used. Takes precedence over the service account found in GCP credentials, \"\n            \"and required if a service account cannot be detected in GCP credentials.\"\n        ),\n    )\n    job_watch_poll_interval: float = Field(\n        default=5.0,\n        title=\"Poll Interval (Seconds)\",\n        description=(\n            \"The amount of time to wait between GCP API calls while monitoring the \"\n            \"state of a Vertex AI Job.\"\n        ),\n    )\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/","title":"Deployment Steps","text":""},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps","title":"<code>prefect_gcp.deployments.steps</code>","text":"<p>Prefect deployment steps for code storage in and retrieval from Google Cloud Storage.</p>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PullFromGcsOutput","title":"<code>PullFromGcsOutput</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>pull_from_gcs</code> step.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>class PullFromGcsOutput(TypedDict):\n    \"\"\"\n    The output of the `pull_from_gcs` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n    directory: str\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PullProjectFromGcsOutput","title":"<code>PullProjectFromGcsOutput</code>","text":"<p>               Bases: <code>PullFromGcsOutput</code></p> <p>Deprecated. Use <code>PullFromGcsOutput</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PullFromGcsOutput` instead.\")\nclass PullProjectFromGcsOutput(PullFromGcsOutput):\n    \"\"\"Deprecated. Use `PullFromGcsOutput` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PushProjectToGcsOutput","title":"<code>PushProjectToGcsOutput</code>","text":"<p>               Bases: <code>PushToGcsOutput</code></p> <p>Deprecated. Use <code>PushToGcsOutput</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `PushToGcsOutput` instead.\")\nclass PushProjectToGcsOutput(PushToGcsOutput):\n    \"\"\"Deprecated. Use `PushToGcsOutput` instead.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.PushToGcsOutput","title":"<code>PushToGcsOutput</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>The output of the <code>push_to_gcs</code> step.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>class PushToGcsOutput(TypedDict):\n    \"\"\"\n    The output of the `push_to_gcs` step.\n    \"\"\"\n\n    bucket: str\n    folder: str\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.pull_from_gcs","title":"<code>pull_from_gcs</code>","text":"<p>Pulls the contents of a project from an GCS bucket to the current working directory.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the GCS bucket where files are stored.</p> required <code>folder</code> <code>str</code> <p>The folder in the GCS bucket where files are stored.</p> required <code>project</code> <code>Optional[str]</code> <p>The GCP project the bucket belongs to. If not provided, the project will be inferred from the credentials or the local environment.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the service account information and project used for authentication. If not provided, the application default credentials will be used.</p> <code>None</code> <p>Returns:</p> Type Description <code>PullProjectFromGcsOutput</code> <p>A dictionary containing the bucket, folder, and local directory where files were downloaded.</p> <p>Examples:</p> <p>Pull from GCS using the default environment credentials: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n</code></pre></p> <p>Pull from GCS using credentials stored in a block: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n</code></pre></p> <p>Pull from to an GCS bucket using credentials stored in a service account file: <pre><code>build:\n    - prefect_gcp.deployments.steps.pull_from_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials:\n            project: my-project\n            service_account_file: /path/to/service_account.json\n</code></pre></p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>def pull_from_gcs(\n    bucket: str,\n    folder: str,\n    project: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n) -&gt; PullProjectFromGcsOutput:\n    \"\"\"\n    Pulls the contents of a project from an GCS bucket to the current working directory.\n\n    Args:\n        bucket: The name of the GCS bucket where files are stored.\n        folder: The folder in the GCS bucket where files are stored.\n        project: The GCP project the bucket belongs to. If not provided, the project will be\n            inferred from the credentials or the local environment.\n        credentials: A dictionary containing the service account information and project\n            used for authentication. If not provided, the application default\n            credentials will be used.\n\n    Returns:\n        A dictionary containing the bucket, folder, and local directory where files were downloaded.\n\n    Examples:\n        Pull from GCS using the default environment credentials:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n        ```\n\n        Pull from GCS using credentials stored in a block:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n        ```\n\n        Pull from to an GCS bucket using credentials stored in a service account file:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.pull_from_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials:\n                    project: my-project\n                    service_account_file: /path/to/service_account.json\n        ```\n\n    \"\"\"  # noqa\n    local_path = Path.cwd()\n    project = credentials.get(\"project\") if credentials else None\n\n    gcp_creds = None\n    if credentials is not None:\n        if credentials.get(\"service_account_info\") is not None:\n            gcp_creds = Credentials.from_service_account_info(\n                credentials.get(\"service_account_info\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif credentials.get(\"service_account_file\") is not None:\n            gcp_creds = Credentials.from_service_account_file(\n                credentials.get(\"service_account_file\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n\n    gcp_creds = gcp_creds or google.auth.default()[0]\n\n    storage_client = StorageClient(credentials=gcp_creds, project=project)\n\n    blobs = storage_client.list_blobs(bucket, prefix=folder)\n\n    for blob in blobs:\n        if blob.name.endswith(\"/\"):\n            # object is a folder and will be created if it contains any objects\n            continue\n        local_blob_download_path = PurePosixPath(\n            local_path\n            / relative_path_to_current_platform(blob.name).relative_to(folder)\n        )\n        Path.mkdir(Path(local_blob_download_path.parent), parents=True, exist_ok=True)\n\n        blob.download_to_filename(local_blob_download_path)\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n        \"directory\": str(local_path),\n    }\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.pull_project_from_gcs","title":"<code>pull_project_from_gcs</code>","text":"<p>Deprecated. Use <code>pull_from_gcs</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `pull_from_gcs` instead.\")\ndef pull_project_from_gcs(*args, **kwargs) -&gt; PullProjectFromGcsOutput:\n    \"\"\"\n    Deprecated. Use `pull_from_gcs` instead.\n    \"\"\"\n    return pull_from_gcs(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.push_project_to_gcs","title":"<code>push_project_to_gcs</code>","text":"<p>Deprecated. Use <code>push_to_gcs</code> instead.</p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>@deprecated_callable(start_date=\"Jun 2023\", help=\"Use `push_to_gcs` instead.\")\ndef push_project_to_gcs(*args, **kwargs) -&gt; PushToGcsOutput:\n    \"\"\"\n    Deprecated. Use `push_to_gcs` instead.\n    \"\"\"\n    return push_to_gcs(*args, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-gcp/deployments/steps/#prefect_gcp.deployments.steps.push_to_gcs","title":"<code>push_to_gcs</code>","text":"<p>Pushes the contents of the current working directory to a GCS bucket, excluding files and folders specified in the ignore_file.</p> <p>Parameters:</p> Name Type Description Default <code>bucket</code> <code>str</code> <p>The name of the GCS bucket where files will be uploaded.</p> required <code>folder</code> <code>str</code> <p>The folder in the GCS bucket where files will be uploaded.</p> required <code>project</code> <code>Optional[str]</code> <p>The GCP project the bucket belongs to. If not provided, the project will be inferred from the credentials or the local environment.</p> <code>None</code> <code>credentials</code> <code>Optional[Dict]</code> <p>A dictionary containing the service account information and project used for authentication. If not provided, the application default credentials will be used.</p> <code>None</code> <code>ignore_file</code> <p>The name of the file containing ignore patterns.</p> <code>'.prefectignore'</code> <p>Returns:</p> Type Description <code>PushToGcsOutput</code> <p>A dictionary containing the bucket and folder where files were uploaded.</p> <p>Examples:</p> <p>Push to a GCS bucket: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-project\n</code></pre></p> <p>Push  to a GCS bucket using credentials stored in a block: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n</code></pre></p> <p>Push to a GCS bucket using credentials stored in a service account file: <pre><code>build:\n    - prefect_gcp.deployments.steps.push_to_gcs:\n        requires: prefect-gcp\n        bucket: my-bucket\n        folder: my-folder\n        credentials:\n            project: my-project\n            service_account_file: /path/to/service_account.json\n</code></pre></p> Source code in <code>prefect_gcp/deployments/steps.py</code> <pre><code>def push_to_gcs(\n    bucket: str,\n    folder: str,\n    project: Optional[str] = None,\n    credentials: Optional[Dict] = None,\n    ignore_file=\".prefectignore\",\n) -&gt; PushToGcsOutput:\n    \"\"\"\n    Pushes the contents of the current working directory to a GCS bucket,\n    excluding files and folders specified in the ignore_file.\n\n    Args:\n        bucket: The name of the GCS bucket where files will be uploaded.\n        folder: The folder in the GCS bucket where files will be uploaded.\n        project: The GCP project the bucket belongs to. If not provided, the project\n            will be inferred from the credentials or the local environment.\n        credentials: A dictionary containing the service account information and project\n            used for authentication. If not provided, the application default\n            credentials will be used.\n        ignore_file: The name of the file containing ignore patterns.\n\n    Returns:\n        A dictionary containing the bucket and folder where files were uploaded.\n\n    Examples:\n        Push to a GCS bucket:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-project\n        ```\n\n        Push  to a GCS bucket using credentials stored in a block:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials: \"{{ prefect.blocks.gcp-credentials.dev-credentials }}\"\n        ```\n\n        Push to a GCS bucket using credentials stored in a service account\n        file:\n        ```yaml\n        build:\n            - prefect_gcp.deployments.steps.push_to_gcs:\n                requires: prefect-gcp\n                bucket: my-bucket\n                folder: my-folder\n                credentials:\n                    project: my-project\n                    service_account_file: /path/to/service_account.json\n        ```\n\n    \"\"\"\n    project = credentials.get(\"project\") if credentials else None\n\n    gcp_creds = None\n    if credentials is not None:\n        if credentials.get(\"service_account_info\") is not None:\n            gcp_creds = Credentials.from_service_account_info(\n                credentials.get(\"service_account_info\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n        elif credentials.get(\"service_account_file\") is not None:\n            gcp_creds = Credentials.from_service_account_file(\n                credentials.get(\"service_account_file\"),\n                scopes=[\"https://www.googleapis.com/auth/cloud-platform\"],\n            )\n\n    gcp_creds = gcp_creds or google.auth.default()[0]\n\n    storage_client = StorageClient(credentials=gcp_creds, project=project)\n    bucket_resource = storage_client.bucket(bucket)\n\n    local_path = Path.cwd()\n\n    included_files = None\n    if ignore_file and Path(ignore_file).exists():\n        with open(ignore_file, \"r\") as f:\n            ignore_patterns = f.readlines()\n        included_files = filter_files(str(local_path), ignore_patterns)\n\n    for local_file_path in local_path.expanduser().rglob(\"*\"):\n        relative_local_file_path = local_file_path.relative_to(local_path)\n        if (\n            included_files is not None\n            and str(relative_local_file_path) not in included_files\n        ):\n            continue\n        elif not local_file_path.is_dir():\n            remote_file_path = (folder / relative_local_file_path).as_posix()\n\n            blob_resource = bucket_resource.blob(remote_file_path)\n            blob_resource.upload_from_filename(local_file_path)\n\n    return {\n        \"bucket\": bucket,\n        \"folder\": folder,\n    }\n</code></pre>"},{"location":"integrations/prefect-github/","title":"prefect-github","text":"<p>Prefect-github makes it easy to interact with GitHub repositories and credentials.</p>"},{"location":"integrations/prefect-github/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-github/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A GitHub account.</li> </ul>"},{"location":"integrations/prefect-github/#install-prefect-github","title":"Install prefect-github","text":"<pre><code>pip install prefect-github\n</code></pre>"},{"location":"integrations/prefect-github/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-github module to make them available for use.</p> <pre><code>prefect block register -m prefect_github\n</code></pre>"},{"location":"integrations/prefect-github/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p> <p>To create a deployment and run a deployment where the flow code is stored in a private GitHub repository, you can use the <code>GitHubCredentials</code> block.</p> <p>A deployment can use flow code stored in a GitHub repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Code to create a GitHub Credentials block:</p> <pre><code>from prefect_github import GitHubCredentials\n\ngithub_credentials_block = GitHubCredentials(token=\"my_token\")\ngithub_credentials_block.save(name=\"my-github-credentials-block\")\n</code></pre>"},{"location":"integrations/prefect-github/#access-flow-code-stored-in-a-private-github-repository-in-a-deployment","title":"Access flow code stored in a private GitHub repository in a deployment","text":"<p>Use the credentials block you created above to pass the GitHub access token during deployment creation. The code below assumes there's flow code stored in a private GitHub repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_github import GitHubCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://github.com/org/private-repo.git\",\n        credentials=GitHubCredentials.load(\"my-github-credentials-block\")\n    ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-github-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the GitHub Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.github-credentials.my-github-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-github/#interact-with-a-github-repository","title":"Interact with a GitHub repository","text":"<p>You can use prefect-github to create and retrieve issues and PRs from a repository. Here's an example of adding a star to a GitHub repository:</p> <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.repository import query_repository\nfrom prefect_github.mutations import add_star_starrable\n\n\n@flow()\ndef github_add_star_flow():\n    github_credentials = GitHubCredentials.load(\"github-token\")\n    repository_id = query_repository(\n        \"PrefectHQ\",\n        \"Prefect\",\n        github_credentials=github_credentials,\n        return_fields=\"id\"\n    )[\"id\"]\n    starrable = add_star_starrable(\n        repository_id,\n        github_credentials\n    )\n    return starrable\n\n\nif __name__ == \"__main__\":\n    github_add_star_flow()\n</code></pre>"},{"location":"integrations/prefect-github/#resources","title":"Resources","text":"<p>For assistance using GitHub, consult the GitHub documentation.</p> <p>Refer to the prefect-github API documentation linked in the sidebar to explore all the capabilities of the prefect-github library.</p>"},{"location":"integrations/prefect-github/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials","title":"<code>prefect_github.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with GitHub</p>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials","title":"<code>GitHubCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage GitHub authentication.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>SecretStr</code> <p>the token to authenticate into GitHub.</p> <p>Examples:</p> <p>Load stored GitHub credentials: <pre><code>from prefect_github import GitHubCredentials\ngithub_credentials_block = GitHubCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>class GitHubCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage GitHub authentication.\n\n    Attributes:\n        token: the token to authenticate into GitHub.\n\n    Examples:\n        Load stored GitHub credentials:\n        ```python\n        from prefect_github import GitHubCredentials\n        github_credentials_block = GitHubCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"GitHub Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials\"  # noqa\n\n    token: SecretStr = Field(\n        default=None, description=\"A GitHub personal access token (PAT).\"\n    )\n\n    def get_client(self) -&gt; HTTPEndpoint:\n        \"\"\"\n        Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n\n        Returns:\n            An authenticated GitHub GraphQL HTTPEndpoint client.\n\n        Example:\n            Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n            ```python\n            from prefect_github import GitHubCredentials\n\n            github_credentials = GitHubCredentials(token=token)\n            client = github_credentials.get_client()\n            ```\n        \"\"\"\n\n        if self.token is not None:\n            base_headers = {\"Authorization\": f\"Bearer {self.token.get_secret_value()}\"}\n        else:\n            base_headers = None\n\n        endpoint = HTTPEndpoint(\n            \"https://api.github.com/graphql\", base_headers=base_headers\n        )\n        return endpoint\n\n    def get_endpoint(self) -&gt; HTTPEndpoint:\n        \"\"\"\n        Gets an authenticated GitHub GraphQL HTTPEndpoint.\n\n        Returns:\n            An authenticated GitHub GraphQL HTTPEndpoint\n\n        Example:\n            Gets an authenticated GitHub GraphQL HTTPEndpoint.\n            ```python\n            from prefect import flow\n            from prefect_github import GitHubCredentials\n\n            @flow\n            def example_get_endpoint_flow():\n                token = \"token_xxxxxxx\"\n                github_credentials = GitHubCredentials(token=token)\n                endpoint = github_credentials.get_endpoint()\n                return endpoint\n\n            example_get_endpoint_flow()\n            ```\n        \"\"\"\n        warnings.warn(\n            \"`get_endpoint` is deprecated and will be removed March 31st, 2023, \"\n            \"use `get_client` instead.\",\n            DeprecationWarning,\n        )\n        return self.get_client()\n</code></pre>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an authenticated GitHub GraphQL HTTPEndpoint client.</p> <p>Returns:</p> Type Description <code>HTTPEndpoint</code> <p>An authenticated GitHub GraphQL HTTPEndpoint client.</p> Example <p>Gets an authenticated GitHub GraphQL HTTPEndpoint client. <pre><code>from prefect_github import GitHubCredentials\n\ngithub_credentials = GitHubCredentials(token=token)\nclient = github_credentials.get_client()\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>def get_client(self) -&gt; HTTPEndpoint:\n    \"\"\"\n    Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n\n    Returns:\n        An authenticated GitHub GraphQL HTTPEndpoint client.\n\n    Example:\n        Gets an authenticated GitHub GraphQL HTTPEndpoint client.\n        ```python\n        from prefect_github import GitHubCredentials\n\n        github_credentials = GitHubCredentials(token=token)\n        client = github_credentials.get_client()\n        ```\n    \"\"\"\n\n    if self.token is not None:\n        base_headers = {\"Authorization\": f\"Bearer {self.token.get_secret_value()}\"}\n    else:\n        base_headers = None\n\n    endpoint = HTTPEndpoint(\n        \"https://api.github.com/graphql\", base_headers=base_headers\n    )\n    return endpoint\n</code></pre>"},{"location":"integrations/prefect-github/credentials/#prefect_github.credentials.GitHubCredentials.get_endpoint","title":"<code>get_endpoint</code>","text":"<p>Gets an authenticated GitHub GraphQL HTTPEndpoint.</p> <p>Returns:</p> Type Description <code>HTTPEndpoint</code> <p>An authenticated GitHub GraphQL HTTPEndpoint</p> Example <p>Gets an authenticated GitHub GraphQL HTTPEndpoint. <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\n\n@flow\ndef example_get_endpoint_flow():\n    token = \"token_xxxxxxx\"\n    github_credentials = GitHubCredentials(token=token)\n    endpoint = github_credentials.get_endpoint()\n    return endpoint\n\nexample_get_endpoint_flow()\n</code></pre></p> Source code in <code>prefect_github/credentials.py</code> <pre><code>def get_endpoint(self) -&gt; HTTPEndpoint:\n    \"\"\"\n    Gets an authenticated GitHub GraphQL HTTPEndpoint.\n\n    Returns:\n        An authenticated GitHub GraphQL HTTPEndpoint\n\n    Example:\n        Gets an authenticated GitHub GraphQL HTTPEndpoint.\n        ```python\n        from prefect import flow\n        from prefect_github import GitHubCredentials\n\n        @flow\n        def example_get_endpoint_flow():\n            token = \"token_xxxxxxx\"\n            github_credentials = GitHubCredentials(token=token)\n            endpoint = github_credentials.get_endpoint()\n            return endpoint\n\n        example_get_endpoint_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"`get_endpoint` is deprecated and will be removed March 31st, 2023, \"\n        \"use `get_client` instead.\",\n        DeprecationWarning,\n    )\n    return self.get_client()\n</code></pre>"},{"location":"integrations/prefect-github/graphql/","title":"Graphql","text":""},{"location":"integrations/prefect-github/graphql/#prefect_github.graphql","title":"<code>prefect_github.graphql</code>","text":"<p>This is a module containing generic GraphQL tasks</p>"},{"location":"integrations/prefect-github/graphql/#prefect_github.graphql.execute_graphql","title":"<code>execute_graphql</code>  <code>async</code>","text":"<p>Generic function for executing GraphQL operations.</p> <p>Parameters:</p> Name Type Description Default <code>op</code> <code>Union[Operation, str]</code> <p>The operation, either as a valid GraphQL string or sgqlc.Operation.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>error_key</code> <code>str</code> <p>The key name to look out for in the response that indicates an error has occurred with the request.</p> <code>'errors'</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> <p>Examples:</p> <p>Queries the first three issues from the Prefect repository using a string query. <pre><code>from prefect import flow\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.graphql import execute_graphql\n\n@flow()\ndef example_execute_graphql_flow():\n    op = '''\n        query GitHubRepoIssues($owner: String!, $name: String!) {\n            repository(owner: $owner, name: $name) {\n                issues(last: 3) {\n                    nodes {\n                        number\n                        title\n                    }\n                }\n            }\n        }\n    '''\n    token = \"ghp_...\"\n    github_credentials = GitHubCredentials(token=token)\n    params = dict(owner=\"PrefectHQ\", name=\"Prefect\")\n    result = execute_graphql(op, github_credentials, **params)\n    return result\n\nexample_execute_graphql_flow()\n</code></pre></p> <p>Queries the first three issues from Prefect repository using a sgqlc.Operation. <pre><code>from prefect import flow\nfrom sgqlc.operation import Operation\nfrom prefect_github import GitHubCredentials\nfrom prefect_github.schemas import graphql_schema\nfrom prefect_github.graphql import execute_graphql\n\n@flow()\ndef example_execute_graphql_flow():\n    op = Operation(graphql_schema.Query)\n    op_settings = op.repository(\n        owner=\"PrefectHQ\", name=\"Prefect\"\n    ).issues(\n        first=3\n    ).nodes()\n    op_settings.__fields__(\"id\", \"title\")\n    token = \"ghp_...\"\n    github_credentials = GitHubCredentials(token=token)\n    result = execute_graphql(\n        op,\n        github_credentials,\n    )\n    return result\n\nexample_execute_graphql_flow()\n</code></pre></p> Source code in <code>prefect_github/graphql.py</code> <pre><code>@task\nasync def execute_graphql(\n    op: Union[Operation, str],\n    github_credentials: GitHubCredentials,\n    error_key: str = \"errors\",\n    **vars,\n) -&gt; Dict[str, Any]:\n    # NOTE: Maintainers can update these examples to match their collection!\n    \"\"\"\n    Generic function for executing GraphQL operations.\n\n    Args:\n        op: The operation, either as a valid GraphQL string or sgqlc.Operation.\n        github_credentials: Credentials to use for authentication with GitHub.\n        error_key: The key name to look out for in the response\n            that indicates an error has occurred with the request.\n\n    Returns:\n        A dict of the returned fields.\n\n    Examples:\n        Queries the first three issues from the Prefect repository\n        using a string query.\n        ```python\n        from prefect import flow\n        from prefect_github import GitHubCredentials\n        from prefect_github.graphql import execute_graphql\n\n        @flow()\n        def example_execute_graphql_flow():\n            op = '''\n                query GitHubRepoIssues($owner: String!, $name: String!) {\n                    repository(owner: $owner, name: $name) {\n                        issues(last: 3) {\n                            nodes {\n                                number\n                                title\n                            }\n                        }\n                    }\n                }\n            '''\n            token = \"ghp_...\"\n            github_credentials = GitHubCredentials(token=token)\n            params = dict(owner=\"PrefectHQ\", name=\"Prefect\")\n            result = execute_graphql(op, github_credentials, **params)\n            return result\n\n        example_execute_graphql_flow()\n        ```\n\n        Queries the first three issues from Prefect repository\n        using a sgqlc.Operation.\n        ```python\n        from prefect import flow\n        from sgqlc.operation import Operation\n        from prefect_github import GitHubCredentials\n        from prefect_github.schemas import graphql_schema\n        from prefect_github.graphql import execute_graphql\n\n        @flow()\n        def example_execute_graphql_flow():\n            op = Operation(graphql_schema.Query)\n            op_settings = op.repository(\n                owner=\"PrefectHQ\", name=\"Prefect\"\n            ).issues(\n                first=3\n            ).nodes()\n            op_settings.__fields__(\"id\", \"title\")\n            token = \"ghp_...\"\n            github_credentials = GitHubCredentials(token=token)\n            result = execute_graphql(\n                op,\n                github_credentials,\n            )\n            return result\n\n        example_execute_graphql_flow()\n        ```\n    \"\"\"\n    result = await _execute_graphql_op(\n        op, github_credentials, error_key=error_key, **vars\n    )\n    return result\n</code></pre>"},{"location":"integrations/prefect-github/mutations/","title":"Mutations","text":""},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations","title":"<code>prefect_github.mutations</code>","text":"<p>This is a module containing: GitHub mutation tasks</p>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_comment_subject","title":"<code>add_comment_subject</code>  <code>async</code>","text":"<p>Adds a comment to an Issue or Pull Request.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>body</code> <code>str</code> <p>The contents of the comment.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_comment_subject(  # noqa\n    subject_id: str,\n    body: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a comment to an Issue or Pull Request.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        body: The contents of the comment.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_comment(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                body=body,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"addComment\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addComment\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_pull_request_review","title":"<code>add_pull_request_review</code>  <code>async</code>","text":"<p>Adds a review to a Pull Request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>commit_oid</code> <code>datetime</code> <p>The commit OID the review pertains to.</p> <code>None</code> <code>body</code> <code>str</code> <p>The contents of the review body comment.</p> <code>None</code> <code>event</code> <code>PullRequestReviewEvent</code> <p>The event to perform on the pull request review.</p> <code>None</code> <code>comments</code> <code>Iterable[DraftPullRequestReviewComment]</code> <p>The review line comments.</p> <code>None</code> <code>threads</code> <code>Iterable[DraftPullRequestReviewThread]</code> <p>The review line comment threads.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_pull_request_review(  # noqa\n    pull_request_id: str,\n    github_credentials: GitHubCredentials,\n    commit_oid: datetime = None,\n    body: str = None,\n    event: graphql_schema.PullRequestReviewEvent = None,\n    comments: Iterable[graphql_schema.DraftPullRequestReviewComment] = None,\n    threads: Iterable[graphql_schema.DraftPullRequestReviewThread] = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a review to a Pull Request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        github_credentials: Credentials to use for authentication with GitHub.\n        commit_oid: The commit OID the review pertains to.\n        body: The contents of the review body comment.\n        event: The event to perform on the pull request review.\n        comments: The review line comments.\n        threads: The review line comment threads.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_pull_request_review(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                commit_oid=commit_oid,\n                body=body,\n                event=event,\n                comments=comments,\n                threads=threads,\n            )\n        )\n    ).pull_request_review(**strip_kwargs())\n\n    op_stack = (\n        \"addPullRequestReview\",\n        \"pullRequestReview\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addPullRequestReview\"][\"pullRequestReview\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_reaction","title":"<code>add_reaction</code>  <code>async</code>","text":"<p>Adds a reaction to a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji to react with.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_reaction(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a reaction to a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji to react with.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).reaction(**strip_kwargs())\n\n    op_stack = (\n        \"addReaction\",\n        \"reaction\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addReaction\"][\"reaction\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_reaction_subject","title":"<code>add_reaction_subject</code>  <code>async</code>","text":"<p>Adds a reaction to a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji to react with.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_reaction_subject(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a reaction to a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji to react with.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"addReaction\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addReaction\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.add_star_starrable","title":"<code>add_star_starrable</code>  <code>async</code>","text":"<p>Adds a star to a Starrable.</p> <p>Parameters:</p> Name Type Description Default <code>starrable_id</code> <code>str</code> <p>The Starrable ID to star.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def add_star_starrable(  # noqa\n    starrable_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Adds a star to a Starrable.\n\n    Args:\n        starrable_id: The Starrable ID to star.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.add_star(\n        **strip_kwargs(\n            input=dict(\n                starrable_id=starrable_id,\n            )\n        )\n    ).starrable(**strip_kwargs())\n\n    op_stack = (\n        \"addStar\",\n        \"starrable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"addStar\"][\"starrable\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.close_issue","title":"<code>close_issue</code>  <code>async</code>","text":"<p>Close an issue.</p> <p>Parameters:</p> Name Type Description Default <code>issue_id</code> <code>str</code> <p>ID of the issue to be closed.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>state_reason</code> <code>IssueClosedStateReason</code> <p>The reason the issue is to be closed.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def close_issue(  # noqa\n    issue_id: str,\n    github_credentials: GitHubCredentials,\n    state_reason: graphql_schema.IssueClosedStateReason = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Close an issue.\n\n    Args:\n        issue_id: ID of the issue to be closed.\n        github_credentials: Credentials to use for authentication with GitHub.\n        state_reason: The reason the issue is to be closed.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.close_issue(\n        **strip_kwargs(\n            input=dict(\n                issue_id=issue_id,\n                state_reason=state_reason,\n            )\n        )\n    ).issue(**strip_kwargs())\n\n    op_stack = (\n        \"closeIssue\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"closeIssue\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.close_pull_request","title":"<code>close_pull_request</code>  <code>async</code>","text":"<p>Close a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>ID of the pull request to be closed.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def close_pull_request(  # noqa\n    pull_request_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Close a pull request.\n\n    Args:\n        pull_request_id: ID of the pull request to be closed.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.close_pull_request(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"closePullRequest\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"closePullRequest\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.create_issue","title":"<code>create_issue</code>  <code>async</code>","text":"<p>Creates a new issue.</p> <p>Parameters:</p> Name Type Description Default <code>repository_id</code> <code>str</code> <p>The Node ID of the repository.</p> required <code>title</code> <code>str</code> <p>The title for the issue.</p> required <code>assignee_ids</code> <code>Iterable[str]</code> <p>The Node ID for the user assignee for this issue.</p> required <code>label_ids</code> <code>Iterable[str]</code> <p>An array of Node IDs of labels for this issue.</p> required <code>project_ids</code> <code>Iterable[str]</code> <p>An array of Node IDs for projects associated with this issue.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>body</code> <code>str</code> <p>The body for the issue description.</p> <code>None</code> <code>milestone_id</code> <code>str</code> <p>The Node ID of the milestone for this issue.</p> <code>None</code> <code>issue_template</code> <code>str</code> <p>The name of an issue template in the repository, assigns labels and assignees from the template to the issue.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def create_issue(  # noqa\n    repository_id: str,\n    title: str,\n    assignee_ids: Iterable[str],\n    label_ids: Iterable[str],\n    project_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    body: str = None,\n    milestone_id: str = None,\n    issue_template: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Creates a new issue.\n\n    Args:\n        repository_id: The Node ID of the repository.\n        title: The title for the issue.\n        assignee_ids: The Node ID for the user assignee for this issue.\n        label_ids: An array of Node IDs of labels for this issue.\n        project_ids: An array of Node IDs for projects associated with this\n            issue.\n        github_credentials: Credentials to use for authentication with GitHub.\n        body: The body for the issue description.\n        milestone_id: The Node ID of the milestone for this issue.\n        issue_template: The name of an issue template in the repository, assigns\n            labels and assignees from the template to the issue.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.create_issue(\n        **strip_kwargs(\n            input=dict(\n                repository_id=repository_id,\n                title=title,\n                assignee_ids=assignee_ids,\n                label_ids=label_ids,\n                project_ids=project_ids,\n                body=body,\n                milestone_id=milestone_id,\n                issue_template=issue_template,\n            )\n        )\n    ).issue(**strip_kwargs())\n\n    op_stack = (\n        \"createIssue\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"createIssue\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.create_pull_request","title":"<code>create_pull_request</code>  <code>async</code>","text":"<p>Create a new pull request.</p> <p>Parameters:</p> Name Type Description Default <code>repository_id</code> <code>str</code> <p>The Node ID of the repository.</p> required <code>base_ref_name</code> <code>str</code> <p>The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository.</p> required <code>head_ref_name</code> <code>str</code> <p>The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace <code>head_ref_name</code> with a user like this: <code>username:branch</code>.</p> required <code>title</code> <code>str</code> <p>The title of the pull request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>body</code> <code>str</code> <p>The contents of the pull request.</p> <code>None</code> <code>maintainer_can_modify</code> <code>bool</code> <p>Indicates whether maintainers can modify the pull request.</p> <code>None</code> <code>draft</code> <code>bool</code> <p>Indicates whether this pull request should be a draft.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def create_pull_request(  # noqa\n    repository_id: str,\n    base_ref_name: str,\n    head_ref_name: str,\n    title: str,\n    github_credentials: GitHubCredentials,\n    body: str = None,\n    maintainer_can_modify: bool = None,\n    draft: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Create a new pull request.\n\n    Args:\n        repository_id: The Node ID of the repository.\n        base_ref_name: The name of the branch you want your changes pulled into.\n            This should be an existing branch on the current repository.\n            You cannot update the base branch on a pull request to point\n            to another repository.\n        head_ref_name: The name of the branch where your changes are\n            implemented. For cross-repository pull requests in the same\n            network, namespace `head_ref_name` with a user like this:\n            `username:branch`.\n        title: The title of the pull request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        body: The contents of the pull request.\n        maintainer_can_modify: Indicates whether maintainers can modify the pull\n            request.\n        draft: Indicates whether this pull request should be a draft.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.create_pull_request(\n        **strip_kwargs(\n            input=dict(\n                repository_id=repository_id,\n                base_ref_name=base_ref_name,\n                head_ref_name=head_ref_name,\n                title=title,\n                body=body,\n                maintainer_can_modify=maintainer_can_modify,\n                draft=draft,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"createPullRequest\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"createPullRequest\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_reaction","title":"<code>remove_reaction</code>  <code>async</code>","text":"<p>Removes a reaction from a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji reaction to remove.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_reaction(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a reaction from a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji reaction to remove.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).reaction(**strip_kwargs())\n\n    op_stack = (\n        \"removeReaction\",\n        \"reaction\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeReaction\"][\"reaction\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_reaction_subject","title":"<code>remove_reaction_subject</code>  <code>async</code>","text":"<p>Removes a reaction from a subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject_id</code> <code>str</code> <p>The Node ID of the subject to modify.</p> required <code>content</code> <code>ReactionContent</code> <p>The name of the emoji reaction to remove.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_reaction_subject(  # noqa\n    subject_id: str,\n    content: graphql_schema.ReactionContent,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a reaction from a subject.\n\n    Args:\n        subject_id: The Node ID of the subject to modify.\n        content: The name of the emoji reaction to remove.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_reaction(\n        **strip_kwargs(\n            input=dict(\n                subject_id=subject_id,\n                content=content,\n            )\n        )\n    ).subject(**strip_kwargs())\n\n    op_stack = (\n        \"removeReaction\",\n        \"subject\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeReaction\"][\"subject\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.remove_star_starrable","title":"<code>remove_star_starrable</code>  <code>async</code>","text":"<p>Removes a star from a Starrable.</p> <p>Parameters:</p> Name Type Description Default <code>starrable_id</code> <code>str</code> <p>The Starrable ID to unstar.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def remove_star_starrable(  # noqa\n    starrable_id: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Removes a star from a Starrable.\n\n    Args:\n        starrable_id: The Starrable ID to unstar.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.remove_star(\n        **strip_kwargs(\n            input=dict(\n                starrable_id=starrable_id,\n            )\n        )\n    ).starrable(**strip_kwargs())\n\n    op_stack = (\n        \"removeStar\",\n        \"starrable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"removeStar\"][\"starrable\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.request_reviews","title":"<code>request_reviews</code>  <code>async</code>","text":"<p>Set review requests on a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>user_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the user to request.</p> required <code>team_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the team to request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>union</code> <code>bool</code> <p>Add users to the set rather than replace.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def request_reviews(  # noqa\n    pull_request_id: str,\n    user_ids: Iterable[str],\n    team_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    union: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Set review requests on a pull request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        user_ids: The Node IDs of the user to request.\n        team_ids: The Node IDs of the team to request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        union: Add users to the set rather than replace.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.request_reviews(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                user_ids=user_ids,\n                team_ids=team_ids,\n                union=union,\n            )\n        )\n    )\n\n    op_stack = (\"requestReviews\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"requestReviews\"]\n</code></pre>"},{"location":"integrations/prefect-github/mutations/#prefect_github.mutations.request_reviews_pull_request","title":"<code>request_reviews_pull_request</code>  <code>async</code>","text":"<p>Set review requests on a pull request.</p> <p>Parameters:</p> Name Type Description Default <code>pull_request_id</code> <code>str</code> <p>The Node ID of the pull request to modify.</p> required <code>user_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the user to request.</p> required <code>team_ids</code> <code>Iterable[str]</code> <p>The Node IDs of the team to request.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>union</code> <code>bool</code> <p>Add users to the set rather than replace.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/mutation/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/mutations.py</code> <pre><code>@task\nasync def request_reviews_pull_request(  # noqa\n    pull_request_id: str,\n    user_ids: Iterable[str],\n    team_ids: Iterable[str],\n    github_credentials: GitHubCredentials,\n    union: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Set review requests on a pull request.\n\n    Args:\n        pull_request_id: The Node ID of the pull request to modify.\n        user_ids: The Node IDs of the user to request.\n        team_ids: The Node IDs of the team to request.\n        github_credentials: Credentials to use for authentication with GitHub.\n        union: Add users to the set rather than replace.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/mutation/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Mutation)\n    op_selection = op.request_reviews(\n        **strip_kwargs(\n            input=dict(\n                pull_request_id=pull_request_id,\n                user_ids=user_ids,\n                team_ids=team_ids,\n                union=union,\n            )\n        )\n    ).pull_request(**strip_kwargs())\n\n    op_stack = (\n        \"requestReviews\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"requestReviews\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/","title":"Organization","text":""},{"location":"integrations/prefect-github/organization/#prefect_github.organization","title":"<code>prefect_github.organization</code>","text":"<p>This is a module containing: GitHub query_organization* tasks</p>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization","title":"<code>query_organization</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"organization\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_audit_log","title":"<code>query_organization_audit_log</code>  <code>async</code>","text":"<p>Audit log entries of the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>The query string to filter audit entries.</p> <code>None</code> <code>order_by</code> <code>AuditLogOrder</code> <p>Ordering options for the returned audit log entries.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_audit_log(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    order_by: graphql_schema.AuditLogOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Audit log entries of the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: The query string to filter audit entries.\n        order_by: Ordering options for the returned audit log entries.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).audit_log(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"auditLog\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"auditLog\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_domains","title":"<code>query_organization_domains</code>  <code>async</code>","text":"<p>A list of domains owned by the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_verified</code> <code>bool</code> <p>Filter by if the domain is verified.</p> <code>None</code> <code>is_approved</code> <code>bool</code> <p>Filter by if the domain is approved.</p> <code>None</code> <code>order_by</code> <code>VerifiableDomainOrder</code> <p>Ordering options for verifiable domains returned.</p> <code>{'field': 'DOMAIN', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_domains(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_verified: bool = None,\n    is_approved: bool = None,\n    order_by: graphql_schema.VerifiableDomainOrder = {\n        \"field\": \"DOMAIN\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of domains owned by the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_verified: Filter by if the domain is verified.\n        is_approved: Filter by if the domain is approved.\n        order_by: Ordering options for verifiable domains returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).domains(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_verified=is_verified,\n            is_approved=is_approved,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"domains\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"domains\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_enterprise_owners","title":"<code>query_organization_enterprise_owners</code>  <code>async</code>","text":"<p>A list of owners of the organization's enterprise account.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>The search string to look for.</p> <code>None</code> <code>organization_role</code> <code>RoleInOrganization</code> <p>The organization role to filter by.</p> <code>None</code> <code>order_by</code> <code>OrgEnterpriseOwnerOrder</code> <p>Ordering options for enterprise owners returned from the connection.</p> <code>{'field': 'LOGIN', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_enterprise_owners(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    organization_role: graphql_schema.RoleInOrganization = None,\n    order_by: graphql_schema.OrgEnterpriseOwnerOrder = {\n        \"field\": \"LOGIN\",\n        \"direction\": \"ASC\",\n    },\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of owners of the organization's enterprise account.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: The search string to look for.\n        organization_role: The organization role to filter by.\n        order_by: Ordering options for enterprise owners\n            returned from the connection.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).enterprise_owners(\n        **strip_kwargs(\n            query=query,\n            organization_role=organization_role,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"enterpriseOwners\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"enterpriseOwners\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_interaction_ability","title":"<code>query_organization_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_interaction_ability(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_ip_allow_list_entries","title":"<code>query_organization_ip_allow_list_entries</code>  <code>async</code>","text":"<p>The IP addresses that are allowed to access resources owned by the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>IpAllowListEntryOrder</code> <p>Ordering options for IP allow list entries returned.</p> <code>{'field': 'ALLOW_LIST_VALUE', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_ip_allow_list_entries(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.IpAllowListEntryOrder = {\n        \"field\": \"ALLOW_LIST_VALUE\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The IP addresses that are allowed to access resources owned by the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for IP allow list\n            entries returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).ip_allow_list_entries(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"ipAllowListEntries\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"ipAllowListEntries\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_item_showcase","title":"<code>query_organization_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_item_showcase(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_member_statuses","title":"<code>query_organization_member_statuses</code>  <code>async</code>","text":"<p>Get the status messages members of this entity have set that are either public or visible only to the organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>UserStatusOrder</code> <p>Ordering options for user statuses returned from the connection.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_member_statuses(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.UserStatusOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Get the status messages members of this entity have set that are either public\n    or visible only to the organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for user statuses returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).member_statuses(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"memberStatuses\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"memberStatuses\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_members_with_role","title":"<code>query_organization_members_with_role</code>  <code>async</code>","text":"<p>A list of users who are members of this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_members_with_role(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who are members of this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).members_with_role(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"membersWithRole\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"membersWithRole\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_packages","title":"<code>query_organization_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_packages(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pending_members","title":"<code>query_organization_pending_members</code>  <code>async</code>","text":"<p>A list of users who have been invited to join this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pending_members(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who have been invited to join this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pending_members(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pendingMembers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pendingMembers\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pinnable_items","title":"<code>query_organization_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pinnable_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        login: The organization's login.\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_pinned_items","title":"<code>query_organization_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_pinned_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        login: The organization's login.\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project","title":"<code>query_organization_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        login: The organization's login.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project_next","title":"<code>query_organization_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project_next(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        login: The organization's login.\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_project_v2","title":"<code>query_organization_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_project_v2(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        login: The organization's login.\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects","title":"<code>query_organization_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The organization's login.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects_next","title":"<code>query_organization_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects_next(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_projects_v2","title":"<code>query_organization_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_projects_v2(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_recent_projects","title":"<code>query_organization_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_recent_projects(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repositories","title":"<code>query_organization_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository","title":"<code>query_organization_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The organization's login.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_discussion_comments","title":"<code>query_organization_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_discussion_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_discussions","title":"<code>query_organization_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_discussions(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_repository_migrations","title":"<code>query_organization_repository_migrations</code>  <code>async</code>","text":"<p>A list of all repository migrations for this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>state</code> <code>MigrationState</code> <p>Filter repository migrations by state.</p> <code>None</code> <code>repository_name</code> <code>str</code> <p>Filter repository migrations by repository name.</p> <code>None</code> <code>order_by</code> <code>RepositoryMigrationOrder</code> <p>Ordering options for repository migrations returned.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_repository_migrations(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    state: graphql_schema.MigrationState = None,\n    repository_name: str = None,\n    order_by: graphql_schema.RepositoryMigrationOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"ASC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of all repository migrations for this organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        state: Filter repository migrations by state.\n        repository_name: Filter repository migrations by\n            repository name.\n        order_by: Ordering options for repository\n            migrations returned.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_migrations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            state=state,\n            repository_name=repository_name,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"repositoryMigrations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"repositoryMigrations\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_saml_identity_provider","title":"<code>query_organization_saml_identity_provider</code>  <code>async</code>","text":"<p>The Organization's SAML identity providers.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_saml_identity_provider(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The Organization's SAML identity providers.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).saml_identity_provider(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"samlIdentityProvider\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"samlIdentityProvider\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsoring","title":"<code>query_organization_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsoring(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors","title":"<code>query_organization_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors_activities","title":"<code>query_organization_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors_activities(  # noqa\n    login: str,\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        login: The organization's login.\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsors_listing","title":"<code>query_organization_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsors_listing(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_for_viewer_as_sponsor","title":"<code>query_organization_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_for_viewer_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsor(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_for_viewer_as_sponsorable","title":"<code>query_organization_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_for_viewer_as_sponsorable(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsorable(**strip_kwargs())\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorship_newsletters","title":"<code>query_organization_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorship_newsletters(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorships_as_maintainer","title":"<code>query_organization_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorships_as_maintainer(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_sponsorships_as_sponsor","title":"<code>query_organization_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_sponsorships_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        login: The organization's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_team","title":"<code>query_organization_team</code>  <code>async</code>","text":"<p>Find an organization's team by its slug.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>slug</code> <code>str</code> <p>The name or slug of the team to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_team(  # noqa\n    login: str,\n    slug: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization's team by its slug.\n\n    Args:\n        login: The organization's login.\n        slug: The name or slug of the team to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).team(\n        **strip_kwargs(\n            slug=slug,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"team\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"team\"]\n</code></pre>"},{"location":"integrations/prefect-github/organization/#prefect_github.organization.query_organization_teams","title":"<code>query_organization_teams</code>  <code>async</code>","text":"<p>A list of teams in this organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The organization's login.</p> required <code>user_logins</code> <code>Iterable[str]</code> <p>User logins to filter by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>TeamPrivacy</code> <p>If non-null, filters teams according to privacy.</p> <code>None</code> <code>role</code> <code>TeamRole</code> <p>If non-null, filters teams according to whether the viewer is an admin or member on team.</p> <code>None</code> <code>query</code> <code>str</code> <p>If non-null, filters teams with query on team name and team slug.</p> <code>None</code> <code>order_by</code> <code>TeamOrder</code> <p>Ordering options for teams returned from the connection.</p> <code>None</code> <code>ldap_mapped</code> <code>bool</code> <p>If true, filters teams that are mapped to an LDAP Group (Enterprise only).</p> <code>None</code> <code>root_teams_only</code> <code>bool</code> <p>If true, restrict to only root teams.</p> <code>False</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/organization.py</code> <pre><code>@task\nasync def query_organization_teams(  # noqa\n    login: str,\n    user_logins: Iterable[str],\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.TeamPrivacy = None,\n    role: graphql_schema.TeamRole = None,\n    query: str = None,\n    order_by: graphql_schema.TeamOrder = None,\n    ldap_mapped: bool = None,\n    root_teams_only: bool = False,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of teams in this organization.\n\n    Args:\n        login: The organization's login.\n        user_logins: User logins to filter by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters teams according to privacy.\n        role: If non-null, filters teams according to whether the viewer\n            is an admin or member on team.\n        query: If non-null, filters teams with query on team name and team\n            slug.\n        order_by: Ordering options for teams returned from the connection.\n        ldap_mapped: If true, filters teams that are mapped to an LDAP\n            Group (Enterprise only).\n        root_teams_only: If true, restrict to only root teams.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.organization(\n        **strip_kwargs(\n            login=login,\n        )\n    ).teams(\n        **strip_kwargs(\n            user_logins=user_logins,\n            privacy=privacy,\n            role=role,\n            query=query,\n            order_by=order_by,\n            ldap_mapped=ldap_mapped,\n            root_teams_only=root_teams_only,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"organization\",\n        \"teams\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"organization\"][\"teams\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/","title":"Repository","text":""},{"location":"integrations/prefect-github/repository/#prefect_github.repository","title":"<code>prefect_github.repository</code>","text":"<p>This is a module containing: GitHub query_repository* tasks and the GitHub storage block.</p>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.GitHubRepository","title":"<code>GitHubRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored on GitHub repositories.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>class GitHubRepository(ReadableDeploymentStorage):\n    \"\"\"\n    Interact with files stored on GitHub repositories.\n    \"\"\"\n\n    _block_type_name = \"GitHub Repository\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/41971cfecfea5f79ff334164f06ecb34d1038dd4-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-github/repository/#prefect_github.repository.GitHubRepository\"  # noqa\n\n    repository_url: str = Field(\n        default=...,\n        title=\"Repository URL\",\n        description=(\n            \"The URL of a GitHub repository to read from, in either HTTPS or SSH \"\n            \"format. If you are using a private repo, it must be in the HTTPS format.\"\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    credentials: Optional[GitHubCredentials] = Field(\n        default=None,\n        description=\"An optional GitHubCredentials block for using private GitHub repos.\",  # noqa: E501\n    )\n\n    @validator(\"credentials\")\n    def _ensure_credentials_go_with_https(cls, v: str, values: dict):\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted GitHub URLs.\"\"\"\n        if v is not None:\n            if urlparse(values[\"repository_url\"]).scheme != \"https\":\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Crendentials can only be used with GitHub repositories \"\n                        \"using the 'HTTPS' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"url to the 'HTTPS' format. \"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n\n        For private repos: https://&lt;oauth-key&gt;@github.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urlparse(self.repository_url)\n        if url_components.scheme == \"https\" and self.credentials is not None:\n            token_value = self.credentials.token.get_secret_value()\n            updated_components = url_components._replace(\n                netloc=f\"{token_value}@{url_components.netloc}\"\n            )\n            full_url = urlunparse(updated_components)\n        else:\n            full_url = self.repository_url\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: str\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitHubRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitHub project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = f\"git clone {self._create_repo_url()}\"\n        if self.reference:\n            cmd += f\" -b {self.reference}\"\n\n        # Limit git history\n        cmd += \" --depth 1\"\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            tmp_path_str = tmp_dir\n            cmd += f\" {tmp_path_str}\"\n            cmd = shlex.split(cmd)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise RuntimeError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_path_str, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.GitHubRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitHub project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory.</p> <p>Parameters:</p> Name Type Description Default <code>from_path</code> <code>Optional[str]</code> <p>If provided, interpreted as a subdirectory of the underlying repository that will be copied to the provided local path.</p> <code>None</code> <code>local_path</code> <code>Optional[str]</code> <p>A local path to clone to; defaults to present working directory.</p> <code>None</code> Source code in <code>prefect_github/repository.py</code> <pre><code>@sync_compatible\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitHub project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = f\"git clone {self._create_repo_url()}\"\n    if self.reference:\n        cmd += f\" -b {self.reference}\"\n\n    # Limit git history\n    cmd += \" --depth 1\"\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        tmp_path_str = tmp_dir\n        cmd += f\" {tmp_path_str}\"\n        cmd = shlex.split(cmd)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise RuntimeError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_path_str, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository","title":"<code>query_repository</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a repository\n            referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\"repository\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_assignable_users","title":"<code>query_repository_assignable_users</code>  <code>async</code>","text":"<p>A list of users that can be assigned to issues in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_assignable_users(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users that can be assigned to issues in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).assignable_users(\n        **strip_kwargs(\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"assignableUsers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"assignableUsers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_branch_protection_rules","title":"<code>query_repository_branch_protection_rules</code>  <code>async</code>","text":"<p>A list of branch protection rules for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_branch_protection_rules(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of branch protection rules for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).branch_protection_rules(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"branchProtectionRules\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"branchProtectionRules\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_code_of_conduct","title":"<code>query_repository_code_of_conduct</code>  <code>async</code>","text":"<p>Returns the code of conduct for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_code_of_conduct(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns the code of conduct for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).code_of_conduct(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"codeOfConduct\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"codeOfConduct\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_collaborators","title":"<code>query_repository_collaborators</code>  <code>async</code>","text":"<p>A list of collaborators associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>affiliation</code> <code>CollaboratorAffiliation</code> <p>Collaborators affiliation level with a repository.</p> <code>None</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_collaborators(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    affiliation: graphql_schema.CollaboratorAffiliation = None,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of collaborators associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        affiliation: Collaborators affiliation level with a\n            repository.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).collaborators(\n        **strip_kwargs(\n            affiliation=affiliation,\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"collaborators\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"collaborators\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_commit_comments","title":"<code>query_repository_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_commit_comments(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_contact_links","title":"<code>query_repository_contact_links</code>  <code>async</code>","text":"<p>Returns a list of contact links associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_contact_links(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of contact links associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).contact_links(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"contactLinks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"contactLinks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_default_branch_ref","title":"<code>query_repository_default_branch_ref</code>  <code>async</code>","text":"<p>The Ref associated with the repository's default branch.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_default_branch_ref(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The Ref associated with the repository's default branch.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).default_branch_ref(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"defaultBranchRef\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"defaultBranchRef\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_deploy_keys","title":"<code>query_repository_deploy_keys</code>  <code>async</code>","text":"<p>A list of deploy keys that are on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_deploy_keys(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of deploy keys that are on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).deploy_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"deployKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"deployKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_deployments","title":"<code>query_repository_deployments</code>  <code>async</code>","text":"<p>Deployments associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>environments</code> <code>Iterable[str]</code> <p>Environments to list deployments for.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>DeploymentOrder</code> <p>Ordering options for deployments returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_deployments(  # noqa\n    owner: str,\n    name: str,\n    environments: Iterable[str],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.DeploymentOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"ASC\",\n    },\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Deployments associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        environments: Environments to list deployments for.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for deployments returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).deployments(\n        **strip_kwargs(\n            environments=environments,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"deployments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"deployments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion","title":"<code>query_repository_discussion</code>  <code>async</code>","text":"<p>Returns a single discussion from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the discussion to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single discussion from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the discussion to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussion\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussion\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion_categories","title":"<code>query_repository_discussion_categories</code>  <code>async</code>","text":"<p>A list of discussion categories that are available in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>filter_by_assignable</code> <code>bool</code> <p>Filter by categories that are assignable by the viewer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion_categories(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    filter_by_assignable: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussion categories that are available in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        filter_by_assignable: Filter by categories that\n            are assignable by the viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion_categories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            filter_by_assignable=filter_by_assignable,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussionCategories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussionCategories\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussion_category","title":"<code>query_repository_discussion_category</code>  <code>async</code>","text":"<p>A discussion category by slug.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>slug</code> <code>str</code> <p>The slug of the discussion category to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussion_category(  # noqa\n    owner: str,\n    name: str,\n    slug: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A discussion category by slug.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        slug: The slug of the discussion category to be\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussion_category(\n        **strip_kwargs(\n            slug=slug,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussionCategory\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussionCategory\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_discussions","title":"<code>query_repository_discussions</code>  <code>async</code>","text":"<p>A list of discussions that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>category_id</code> <code>str</code> <p>Only include discussions that belong to the category with this ID.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_discussions(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    category_id: str = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussions that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        category_id: Only include discussions that belong to the\n            category with this ID.\n        order_by: Ordering options for discussions returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            category_id=category_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"discussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"discussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_environment","title":"<code>query_repository_environment</code>  <code>async</code>","text":"<p>Returns a single active environment from the current repository by name.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>environment_name</code> <code>str</code> <p>The name of the environment to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_environment(  # noqa\n    owner: str,\n    name: str,\n    environment_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single active environment from the current repository by name.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        environment_name: The name of the environment to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).environment(\n        **strip_kwargs(\n            name=environment_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"environment\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"environment\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_environments","title":"<code>query_repository_environments</code>  <code>async</code>","text":"<p>A list of environments that are in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_environments(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of environments that are in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).environments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"environments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"environments\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_forks","title":"<code>query_repository_forks</code>  <code>async</code>","text":"<p>A list of direct forked repositories.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_forks(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of direct forked repositories.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to whether\n            they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).forks(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"forks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"forks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_funding_links","title":"<code>query_repository_funding_links</code>  <code>async</code>","text":"<p>The funding links for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_funding_links(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The funding links for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).funding_links(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"fundingLinks\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"fundingLinks\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_interaction_ability","title":"<code>query_repository_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_interaction_ability(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue","title":"<code>query_repository_issue</code>  <code>async</code>","text":"<p>Returns a single issue from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the issue to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single issue from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the issue to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issue\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issue\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue_or_pull_request","title":"<code>query_repository_issue_or_pull_request</code>  <code>async</code>","text":"<p>Returns a single issue-like object from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the issue to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue_or_pull_request(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single issue-like object from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the issue to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue_or_pull_request(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issueOrPullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issueOrPullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issue_templates","title":"<code>query_repository_issue_templates</code>  <code>async</code>","text":"<p>Returns a list of issue templates associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issue_templates(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of issue templates associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issue_templates(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"issueTemplates\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issueTemplates\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_issues","title":"<code>query_repository_issues</code>  <code>async</code>","text":"<p>A list of issues that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_issues(  # noqa\n    owner: str,\n    name: str,\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_label","title":"<code>query_repository_label</code>  <code>async</code>","text":"<p>Returns a single label by name.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>label_name</code> <code>str</code> <p>Label name.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_label(  # noqa\n    owner: str,\n    name: str,\n    label_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single label by name.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        label_name: Label name.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).label(\n        **strip_kwargs(\n            name=label_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"label\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"label\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_labels","title":"<code>query_repository_labels</code>  <code>async</code>","text":"<p>A list of labels associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>LabelOrder</code> <p>Ordering options for labels returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'ASC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>If provided, searches labels by name and description.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_labels(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.LabelOrder = {\"field\": \"CREATED_AT\", \"direction\": \"ASC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of labels associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for labels returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: If provided, searches labels by name and description.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).labels(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"labels\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"labels\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_languages","title":"<code>query_repository_languages</code>  <code>async</code>","text":"<p>A list containing a breakdown of the language composition of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>LanguageOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_languages(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.LanguageOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list containing a breakdown of the language composition of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).languages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"languages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"languages\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_latest_release","title":"<code>query_repository_latest_release</code>  <code>async</code>","text":"<p>Get the latest release for the repository if one exists.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_latest_release(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Get the latest release for the repository if one exists.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).latest_release(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"latestRelease\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"latestRelease\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_license_info","title":"<code>query_repository_license_info</code>  <code>async</code>","text":"<p>The license associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_license_info(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The license associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).license_info(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"licenseInfo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"licenseInfo\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_mentionable_users","title":"<code>query_repository_mentionable_users</code>  <code>async</code>","text":"<p>A list of Users that can be mentioned in the context of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters users with query on user name and login.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_mentionable_users(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of Users that can be mentioned in the context of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters users with query on user name and login.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).mentionable_users(\n        **strip_kwargs(\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"mentionableUsers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"mentionableUsers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_milestone","title":"<code>query_repository_milestone</code>  <code>async</code>","text":"<p>Returns a single milestone from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the milestone to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_milestone(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single milestone from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the milestone to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).milestone(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"milestone\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"milestone\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_milestones","title":"<code>query_repository_milestones</code>  <code>async</code>","text":"<p>A list of milestones associated with the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[MilestoneState]</code> <p>Filter by the state of the milestones.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>MilestoneOrder</code> <p>Ordering options for milestones.</p> <code>None</code> <code>query</code> <code>str</code> <p>Filters milestones with a query on the title.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_milestones(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.MilestoneState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.MilestoneOrder = None,\n    query: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of milestones associated with the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: Filter by the state of the milestones.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for milestones.\n        query: Filters milestones with a query on the title.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).milestones(\n        **strip_kwargs(\n            states=states,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            query=query,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"milestones\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"milestones\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_object","title":"<code>query_repository_object</code>  <code>async</code>","text":"<p>A Git object in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>oid</code> <code>datetime</code> <p>The Git object ID.</p> <code>None</code> <code>expression</code> <code>str</code> <p>A Git revision expression suitable for rev-parse.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_object(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    oid: datetime = None,\n    expression: str = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A Git object in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        oid: The Git object ID.\n        expression: A Git revision expression suitable for rev-parse.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).object(\n        **strip_kwargs(\n            oid=oid,\n            expression=expression,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"object\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"object\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_owner","title":"<code>query_repository_owner</code>  <code>async</code>","text":"<p>The User owner of the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_owner(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The User owner of the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).owner(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"owner\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"owner\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_packages","title":"<code>query_repository_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_packages(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pinned_discussions","title":"<code>query_repository_pinned_discussions</code>  <code>async</code>","text":"<p>A list of discussions that have been pinned in this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pinned_discussions(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of discussions that have been pinned in this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pinned_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pinnedDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pinnedDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pinned_issues","title":"<code>query_repository_pinned_issues</code>  <code>async</code>","text":"<p>A list of pinned issues for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pinned_issues(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pinned issues for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pinned_issues(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pinnedIssues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pinnedIssues\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_primary_language","title":"<code>query_repository_primary_language</code>  <code>async</code>","text":"<p>The primary language of the repository's code.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_primary_language(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The primary language of the repository's code.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).primary_language(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"primaryLanguage\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"primaryLanguage\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project","title":"<code>query_repository_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project_next","title":"<code>query_repository_project_next</code>  <code>async</code>","text":"<p>Finds and returns the Project (beta) according to the provided Project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The ProjectNext number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project_next(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Finds and returns the Project (beta) according to the provided Project (beta)\n    number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The ProjectNext number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_project_v2","title":"<code>query_repository_project_v2</code>  <code>async</code>","text":"<p>Finds and returns the Project according to the provided Project number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The Project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_project_v2(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Finds and returns the Project according to the provided Project number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The Project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects","title":"<code>query_repository_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects_next","title":"<code>query_repository_projects_next</code>  <code>async</code>","text":"<p>List of projects (beta) linked to this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>A project (beta) to search for linked to the repo.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned project (beta) objects.</p> <code>'TITLE'</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects_next(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of projects (beta) linked to this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: A project (beta) to search for linked to the repo.\n        sort_by: How to order the returned project (beta) objects.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            sort_by=sort_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_projects_v2","title":"<code>query_repository_projects_v2</code>  <code>async</code>","text":"<p>List of projects linked to this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>query</code> <code>str</code> <p>A project to search for linked to the repo.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_projects_v2(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of projects linked to this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        query: A project to search for linked to the repo.\n        order_by: How to order the returned projects.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            query=query,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_request","title":"<code>query_repository_pull_request</code>  <code>async</code>","text":"<p>Returns a single pull request from the current repository by number.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>number</code> <code>int</code> <p>The number for the pull request to be returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_request(  # noqa\n    owner: str,\n    name: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a single pull request from the current repository by number.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        number: The number for the pull request to be returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_request(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pullRequest\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequest\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_request_templates","title":"<code>query_repository_pull_request_templates</code>  <code>async</code>","text":"<p>Returns a list of pull request templates associated to the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_request_templates(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of pull request templates associated to the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_request_templates(**strip_kwargs())\n\n    op_stack = (\n        \"repository\",\n        \"pullRequestTemplates\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequestTemplates\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_pull_requests","title":"<code>query_repository_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests that have been opened in the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_pull_requests(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests that have been opened in the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_recent_projects","title":"<code>query_repository_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_recent_projects(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_ref","title":"<code>query_repository_ref</code>  <code>async</code>","text":"<p>Fetch a given ref from the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>qualified_name</code> <code>str</code> <p>The ref to retrieve. Fully qualified matches are checked in order (<code>refs/heads/master</code>) before falling back onto checks for short name matches (<code>master</code>).</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_ref(  # noqa\n    owner: str,\n    name: str,\n    qualified_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Fetch a given ref from the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        qualified_name: The ref to retrieve. Fully qualified matches are\n            checked in order (`refs/heads/master`) before falling back\n            onto checks for short name matches (`master`).\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).ref(\n        **strip_kwargs(\n            qualified_name=qualified_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"ref\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"ref\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_refs","title":"<code>query_repository_refs</code>  <code>async</code>","text":"<p>Fetch a list of refs from the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>ref_prefix</code> <code>str</code> <p>A ref name prefix like <code>refs/heads/</code>, <code>refs/tags/</code>, etc.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>query</code> <code>str</code> <p>Filters refs with query on name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>direction</code> <code>OrderDirection</code> <code>None</code> <code>order_by</code> <code>RefOrder</code> <p>Ordering options for refs returned from the connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_refs(  # noqa\n    owner: str,\n    name: str,\n    ref_prefix: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    query: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    direction: graphql_schema.OrderDirection = None,\n    order_by: graphql_schema.RefOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Fetch a list of refs from the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        ref_prefix: A ref name prefix like `refs/heads/`, `refs/tags/`,\n            etc.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        query: Filters refs with query on name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        direction: DEPRECATED: use orderBy. The ordering direction.\n        order_by: Ordering options for refs returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).refs(\n        **strip_kwargs(\n            ref_prefix=ref_prefix,\n            query=query,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            direction=direction,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"refs\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"refs\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_release","title":"<code>query_repository_release</code>  <code>async</code>","text":"<p>Lookup a single release given various criteria.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>tag_name</code> <code>str</code> <p>The name of the Tag the Release was created from.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_release(  # noqa\n    owner: str,\n    name: str,\n    tag_name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Lookup a single release given various criteria.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        tag_name: The name of the Tag the Release was created from.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).release(\n        **strip_kwargs(\n            tag_name=tag_name,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"release\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"release\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_releases","title":"<code>query_repository_releases</code>  <code>async</code>","text":"<p>List of releases which are dependent on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>ReleaseOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_releases(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.ReleaseOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of releases which are dependent on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).releases(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"releases\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"releases\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_repository_topics","title":"<code>query_repository_repository_topics</code>  <code>async</code>","text":"<p>A list of applied repository-topic associations for this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_repository_topics(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of applied repository-topic associations for this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).repository_topics(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"repositoryTopics\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"repositoryTopics\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_stargazers","title":"<code>query_repository_stargazers</code>  <code>async</code>","text":"<p>A list of users who have starred this starrable.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_stargazers(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users who have starred this starrable.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).stargazers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"stargazers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"stargazers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_submodules","title":"<code>query_repository_submodules</code>  <code>async</code>","text":"<p>Returns a list of all submodules in this repository parsed from the .gitmodules file as of the default branch's HEAD commit.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_submodules(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Returns a list of all submodules in this repository parsed from the .gitmodules\n    file as of the default branch's HEAD commit.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).submodules(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"submodules\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"submodules\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_vulnerability_alerts","title":"<code>query_repository_vulnerability_alerts</code>  <code>async</code>","text":"<p>A list of vulnerability alerts that are on this repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>states</code> <code>Iterable[RepositoryVulnerabilityAlertState]</code> <p>Filter by the state of the alert.</p> required <code>dependency_scopes</code> <code>Iterable[RepositoryVulnerabilityAlertDependencyScope]</code> <p>Filter by the scope of the alert's dependency.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_vulnerability_alerts(  # noqa\n    owner: str,\n    name: str,\n    states: Iterable[graphql_schema.RepositoryVulnerabilityAlertState],\n    dependency_scopes: Iterable[\n        graphql_schema.RepositoryVulnerabilityAlertDependencyScope\n    ],\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of vulnerability alerts that are on this repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        states: Filter by the state of the alert.\n        dependency_scopes: Filter by the scope of the\n            alert's dependency.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).vulnerability_alerts(\n        **strip_kwargs(\n            states=states,\n            dependency_scopes=dependency_scopes,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"vulnerabilityAlerts\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"vulnerabilityAlerts\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository/#prefect_github.repository.query_repository_watchers","title":"<code>query_repository_watchers</code>  <code>async</code>","text":"<p>A list of users watching the repository.</p> <p>Parameters:</p> Name Type Description Default <code>owner</code> <code>str</code> <p>The login field of a user or organization.</p> required <code>name</code> <code>str</code> <p>The name of the repository.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository.py</code> <pre><code>@task\nasync def query_repository_watchers(  # noqa\n    owner: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users watching the repository.\n\n    Args:\n        owner: The login field of a user or organization.\n        name: The name of the repository.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository(\n        **strip_kwargs(\n            owner=owner,\n            name=name,\n            follow_renames=follow_renames,\n        )\n    ).watchers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"repository\",\n        \"watchers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repository\"][\"watchers\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/","title":"Repository Owner","text":""},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner","title":"<code>prefect_github.repository_owner</code>","text":"<p>This is a module containing: GitHub query_repository_owner* tasks</p>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner","title":"<code>query_repository_owner</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The username to lookup the owner by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"repositoryOwner\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner_repositories","title":"<code>query_repository_owner_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The username to lookup the owner by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"repositoryOwner\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/repository_owner/#prefect_github.repository_owner.query_repository_owner_repository","title":"<code>query_repository_owner_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The username to lookup the owner by.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/repository_owner.py</code> <pre><code>@task\nasync def query_repository_owner_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The username to lookup the owner by.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.repository_owner(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"repositoryOwner\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"repositoryOwner\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/","title":"User","text":""},{"location":"integrations/prefect-github/user/#prefect_github.user","title":"<code>prefect_github.user</code>","text":"<p>This is a module containing: GitHub query_user* tasks</p>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user","title":"<code>query_user</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\"user\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_commit_comments","title":"<code>query_user_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_commit_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_contributions_collection","title":"<code>query_user_contributions_collection</code>  <code>async</code>","text":"<p>The collection of contributions this user has made to different repositories.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>organization_id</code> <code>str</code> <p>The ID of the organization used to filter contributions.</p> <code>None</code> <code>from_</code> <code>datetime</code> <p>Only contributions made at this time or later will be counted. If omitted, defaults to a year ago.</p> <code>None</code> <code>to</code> <code>datetime</code> <p>Only contributions made before and up to (including) this time will be counted. If omitted, defaults to the current time or one year from the provided from argument.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_contributions_collection(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    organization_id: str = None,\n    from_: datetime = None,\n    to: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The collection of contributions this user has made to different repositories.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        organization_id: The ID of the organization\n            used to filter contributions.\n        from_: Only contributions made at this time or\n            later will be counted. If omitted, defaults to a year ago.\n        to: Only contributions made before and up to\n            (including) this time will be counted. If omitted, defaults\n            to the current time or one year from the provided from\n            argument.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).contributions_collection(\n        **strip_kwargs(\n            organization_id=organization_id,\n            from_=from_,\n            to=to,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"contributionsCollection\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"contributionsCollection\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_followers","title":"<code>query_user_followers</code>  <code>async</code>","text":"<p>A list of users the given user is followed by.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_followers(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is followed by.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).followers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"followers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"followers\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_following","title":"<code>query_user_following</code>  <code>async</code>","text":"<p>A list of users the given user is following.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_following(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is following.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).following(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"following\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"following\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gist","title":"<code>query_user_gist</code>  <code>async</code>","text":"<p>Find gist by repo name.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>name</code> <code>str</code> <p>The gist name to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gist(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find gist by repo name.\n\n    Args:\n        login: The user's login.\n        name: The gist name to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gist(\n        **strip_kwargs(\n            name=name,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gist\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gist\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gist_comments","title":"<code>query_user_gist_comments</code>  <code>async</code>","text":"<p>A list of gist comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gist_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of gist comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gist_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gistComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gistComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_gists","title":"<code>query_user_gists</code>  <code>async</code>","text":"<p>A list of the Gists the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>GistPrivacy</code> <p>Filters Gists according to privacy.</p> <code>None</code> <code>order_by</code> <code>GistOrder</code> <p>Ordering options for gists returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_gists(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.GistPrivacy = None,\n    order_by: graphql_schema.GistOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of the Gists the user has created.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: Filters Gists according to privacy.\n        order_by: Ordering options for gists returned from the connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).gists(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"gists\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"gists\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_interaction_ability","title":"<code>query_user_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_interaction_ability(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_issue_comments","title":"<code>query_user_issue_comments</code>  <code>async</code>","text":"<p>A list of issue comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueCommentOrder</code> <p>Ordering options for issue comments returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_issue_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueCommentOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issue comments made by this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issue comments returned\n            from the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).issue_comments(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"issueComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"issueComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_issues","title":"<code>query_user_issues</code>  <code>async</code>","text":"<p>A list of issues associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_issues(  # noqa\n    login: str,\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues associated with this user.\n\n    Args:\n        login: The user's login.\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_item_showcase","title":"<code>query_user_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_item_showcase(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_organization","title":"<code>query_user_organization</code>  <code>async</code>","text":"<p>Find an organization by its login that the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>organization_login</code> <code>str</code> <p>The login of the organization to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_organization(  # noqa\n    login: str,\n    organization_login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization by its login that the user belongs to.\n\n    Args:\n        login: The user's login.\n        organization_login: The login of the organization to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).organization(\n        **strip_kwargs(\n            login=organization_login,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"organization\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_organizations","title":"<code>query_user_organizations</code>  <code>async</code>","text":"<p>A list of organizations the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_organizations(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of organizations the user belongs to.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).organizations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"organizations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"organizations\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_packages","title":"<code>query_user_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_packages(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pinnable_items","title":"<code>query_user_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pinnable_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        login: The user's login.\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pinned_items","title":"<code>query_user_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pinned_items(  # noqa\n    login: str,\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        login: The user's login.\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project","title":"<code>query_user_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        login: The user's login.\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project_next","title":"<code>query_user_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project_next(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        login: The user's login.\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_project_v2","title":"<code>query_user_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_project_v2(  # noqa\n    login: str,\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        login: The user's login.\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects","title":"<code>query_user_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The user's login.\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects_next","title":"<code>query_user_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects_next(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_projects_v2","title":"<code>query_user_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_projects_v2(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_public_keys","title":"<code>query_user_public_keys</code>  <code>async</code>","text":"<p>A list of public keys associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_public_keys(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of public keys associated with this user.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).public_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"publicKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"publicKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_pull_requests","title":"<code>query_user_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_pull_requests(  # noqa\n    login: str,\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests associated with this user.\n\n    Args:\n        login: The user's login.\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_recent_projects","title":"<code>query_user_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_recent_projects(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repositories","title":"<code>query_user_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repositories_contributed_to","title":"<code>query_user_repositories_contributed_to</code>  <code>async</code>","text":"<p>A list of repositories that the user recently contributed to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>include_user_repositories</code> <code>bool</code> <p>If true, include user repositories.</p> <code>None</code> <code>contribution_types</code> <code>Iterable[RepositoryContributionType]</code> <p>If non-null, include only the specified types of contributions. The GitHub.com UI uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repositories_contributed_to(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    is_locked: bool = None,\n    include_user_repositories: bool = None,\n    contribution_types: Iterable[graphql_schema.RepositoryContributionType] = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user recently contributed to.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories\n            according to privacy.\n        order_by: Ordering options for repositories\n            returned from the connection.\n        is_locked: If non-null, filters repositories\n            according to whether they have been locked.\n        include_user_repositories: If true, include\n            user repositories.\n        contribution_types: If non-null, include\n            only the specified types of contributions. The GitHub.com UI\n            uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repositories_contributed_to(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            is_locked=is_locked,\n            include_user_repositories=include_user_repositories,\n            contribution_types=contribution_types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoriesContributedTo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoriesContributedTo\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository","title":"<code>query_user_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository(  # noqa\n    login: str,\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        login: The user's login.\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository_discussion_comments","title":"<code>query_user_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository_discussion_comments(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_repository_discussions","title":"<code>query_user_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_repository_discussions(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_saved_replies","title":"<code>query_user_saved_replies</code>  <code>async</code>","text":"<p>Replies this user has saved.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SavedReplyOrder</code> <p>The field to order saved replies by.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_saved_replies(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SavedReplyOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Replies this user has saved.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: The field to order saved replies by.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).saved_replies(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"savedReplies\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"savedReplies\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsoring","title":"<code>query_user_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsoring(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors","title":"<code>query_user_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors_activities","title":"<code>query_user_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors_activities(  # noqa\n    login: str,\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        login: The user's login.\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsors_listing","title":"<code>query_user_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsors_listing(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_for_viewer_as_sponsor","title":"<code>query_user_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_for_viewer_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsor(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_for_viewer_as_sponsorable","title":"<code>query_user_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_for_viewer_as_sponsorable(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_for_viewer_as_sponsorable(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorship_newsletters","title":"<code>query_user_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorship_newsletters(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorships_as_maintainer","title":"<code>query_user_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorships_as_maintainer(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_sponsorships_as_sponsor","title":"<code>query_user_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_sponsorships_as_sponsor(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_starred_repositories","title":"<code>query_user_starred_repositories</code>  <code>async</code>","text":"<p>Repositories the user has starred.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>owned_by_viewer</code> <code>bool</code> <p>Filters starred repositories to only return repositories owned by the viewer.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_starred_repositories(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    owned_by_viewer: bool = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has starred.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        owned_by_viewer: Filters starred repositories to\n            only return repositories owned by the viewer.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).starred_repositories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            owned_by_viewer=owned_by_viewer,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"starredRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"starredRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_status","title":"<code>query_user_status</code>  <code>async</code>","text":"<p>The user's description of what they're currently doing.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_status(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The user's description of what they're currently doing.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).status(**strip_kwargs())\n\n    op_stack = (\n        \"user\",\n        \"status\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"status\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_top_repositories","title":"<code>query_user_top_repositories</code>  <code>async</code>","text":"<p>Repositories the user has contributed to, ordered by contribution rank, plus repositories the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>since</code> <code>datetime</code> <p>How far back in time to fetch contributed repositories.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_top_repositories(  # noqa\n    login: str,\n    order_by: graphql_schema.RepositoryOrder,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    since: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has contributed to, ordered by contribution rank, plus\n    repositories the user has created.\n\n    Args:\n        login: The user's login.\n        order_by: Ordering options for repositories returned\n            from the connection.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        since: How far back in time to fetch contributed\n            repositories.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).top_repositories(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            since=since,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"topRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"topRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/user/#prefect_github.user.query_user_watching","title":"<code>query_user_watching</code>  <code>async</code>","text":"<p>A list of repositories the given user is watching.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The user's login.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Affiliation options for repositories returned from the connection. If none specified, the results will include repositories for which the current viewer is an owner or collaborator, or member.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/user.py</code> <pre><code>@task\nasync def query_user_watching(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories the given user is watching.\n\n    Args:\n        login: The user's login.\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Affiliation options for repositories returned\n            from the connection. If none specified, the results will\n            include repositories for which the current viewer is an\n            owner or collaborator, or member.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.user(\n        **strip_kwargs(\n            login=login,\n        )\n    ).watching(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"user\",\n        \"watching\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"user\"][\"watching\"]\n</code></pre>"},{"location":"integrations/prefect-github/utils/","title":"Utils","text":""},{"location":"integrations/prefect-github/utils/#prefect_github.utils","title":"<code>prefect_github.utils</code>","text":"<p>Utilities to assist with using generated collections.</p>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.camel_to_snake_case","title":"<code>camel_to_snake_case</code>","text":"<p>Converts CamelCase and lowerCamelCase to snake_case. Args:     string: The string in CamelCase or lowerCamelCase to convert. Returns:     A snake_case version of the string.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def camel_to_snake_case(string: str) -&gt; str:\n    \"\"\"\n    Converts CamelCase and lowerCamelCase to snake_case.\n    Args:\n        string: The string in CamelCase or lowerCamelCase to convert.\n    Returns:\n        A snake_case version of the string.\n    \"\"\"\n    string = SNAKE_CASE_REGEX1.sub(r\"\\1_\\2\", string)\n    return SNAKE_CASE_REGEX2.sub(r\"\\1_\\2\", string).lower()\n</code></pre>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.initialize_return_fields_defaults","title":"<code>initialize_return_fields_defaults</code>","text":"<p>Reads config_path to parse out the desired default fields to return. Args:     config_path: The path to the config file.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def initialize_return_fields_defaults(config_path: Union[Path, str]) -&gt; List:\n    \"\"\"\n    Reads config_path to parse out the desired default fields to return.\n    Args:\n        config_path: The path to the config file.\n    \"\"\"\n    with open(config_path, \"r\") as f:\n        config = json.load(f)\n\n    return_fields_defaults = defaultdict(lambda: [])\n    for op_type, sub_op_types in config.items():\n        for sub_op_type in sub_op_types:\n            if isinstance(sub_op_type, str):\n                return_fields_defaults[(op_type,)].append(\n                    camel_to_snake_case(sub_op_type)\n                )\n            elif isinstance(sub_op_type, dict):\n                sub_op_type_key = list(sub_op_type.keys())[0]\n                return_fields_defaults[(op_type, sub_op_type_key)] = [\n                    camel_to_snake_case(field) for field in sub_op_type[sub_op_type_key]\n                ]\n    return return_fields_defaults\n</code></pre>"},{"location":"integrations/prefect-github/utils/#prefect_github.utils.strip_kwargs","title":"<code>strip_kwargs</code>","text":"<p>Drops keyword arguments if value is None because sgqlc.Operation errors out if a keyword argument is provided, but set to None.</p> <p>Parameters:</p> Name Type Description Default <code>**kwargs</code> <code>Dict</code> <p>Input keyword arguments.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Dict</code> <p>Stripped version of kwargs.</p> Source code in <code>prefect_github/utils.py</code> <pre><code>def strip_kwargs(**kwargs: Dict) -&gt; Dict:\n    \"\"\"\n    Drops keyword arguments if value is None because sgqlc.Operation\n    errors out if a keyword argument is provided, but set to None.\n\n    Args:\n        **kwargs: Input keyword arguments.\n\n    Returns:\n        Stripped version of kwargs.\n    \"\"\"\n    stripped_dict = {}\n    for k, v in kwargs.items():\n        if isinstance(v, dict):\n            v = strip_kwargs(**v)\n        if v is not None:\n            stripped_dict[k] = v\n    return stripped_dict or {}\n</code></pre>"},{"location":"integrations/prefect-github/viewer/","title":"Viewer","text":""},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer","title":"<code>prefect_github.viewer</code>","text":"<p>This is a module containing: GitHub query_viewer* tasks</p>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer","title":"<code>query_viewer</code>  <code>async</code>","text":"<p>The query root of GitHub's GraphQL interface.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The query root of GitHub's GraphQL interface.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs())\n\n    op_stack = (\"viewer\",)\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_commit_comments","title":"<code>query_viewer_commit_comments</code>  <code>async</code>","text":"<p>A list of commit comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_commit_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of commit comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).commit_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"commitComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"commitComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_contributions_collection","title":"<code>query_viewer_contributions_collection</code>  <code>async</code>","text":"<p>The collection of contributions this user has made to different repositories.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>organization_id</code> <code>str</code> <p>The ID of the organization used to filter contributions.</p> <code>None</code> <code>from_</code> <code>datetime</code> <p>Only contributions made at this time or later will be counted. If omitted, defaults to a year ago.</p> <code>None</code> <code>to</code> <code>datetime</code> <p>Only contributions made before and up to (including) this time will be counted. If omitted, defaults to the current time or one year from the provided from argument.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_contributions_collection(  # noqa\n    github_credentials: GitHubCredentials,\n    organization_id: str = None,\n    from_: datetime = None,\n    to: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The collection of contributions this user has made to different repositories.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        organization_id: The ID of the organization\n            used to filter contributions.\n        from_: Only contributions made at this time or\n            later will be counted. If omitted, defaults to a year ago.\n        to: Only contributions made before and up to\n            (including) this time will be counted. If omitted, defaults\n            to the current time or one year from the provided from\n            argument.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).contributions_collection(\n        **strip_kwargs(\n            organization_id=organization_id,\n            from_=from_,\n            to=to,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"contributionsCollection\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"contributionsCollection\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_followers","title":"<code>query_viewer_followers</code>  <code>async</code>","text":"<p>A list of users the given user is followed by.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_followers(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is followed by.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).followers(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"followers\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"followers\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_following","title":"<code>query_viewer_following</code>  <code>async</code>","text":"<p>A list of users the given user is following.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_following(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of users the given user is following.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).following(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"following\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"following\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gist","title":"<code>query_viewer_gist</code>  <code>async</code>","text":"<p>Find gist by repo name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The gist name to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gist(  # noqa\n    name: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find gist by repo name.\n\n    Args:\n        name: The gist name to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gist(\n        **strip_kwargs(\n            name=name,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gist\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gist\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gist_comments","title":"<code>query_viewer_gist_comments</code>  <code>async</code>","text":"<p>A list of gist comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gist_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of gist comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gist_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gistComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gistComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_gists","title":"<code>query_viewer_gists</code>  <code>async</code>","text":"<p>A list of the Gists the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>GistPrivacy</code> <p>Filters Gists according to privacy.</p> <code>None</code> <code>order_by</code> <code>GistOrder</code> <p>Ordering options for gists returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_gists(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.GistPrivacy = None,\n    order_by: graphql_schema.GistOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of the Gists the user has created.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: Filters Gists according to privacy.\n        order_by: Ordering options for gists returned from the connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).gists(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"gists\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"gists\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_interaction_ability","title":"<code>query_viewer_interaction_ability</code>  <code>async</code>","text":"<p>The interaction ability settings for this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_interaction_ability(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The interaction ability settings for this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).interaction_ability(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"interactionAbility\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"interactionAbility\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_issue_comments","title":"<code>query_viewer_issue_comments</code>  <code>async</code>","text":"<p>A list of issue comments made by this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueCommentOrder</code> <p>Ordering options for issue comments returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_issue_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueCommentOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issue comments made by this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issue comments returned\n            from the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).issue_comments(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"issueComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"issueComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_issues","title":"<code>query_viewer_issues</code>  <code>async</code>","text":"<p>A list of issues associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>states</code> <code>Iterable[IssueState]</code> <p>A list of states to filter the issues by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for issues returned from the connection.</p> <code>None</code> <code>filter_by</code> <code>IssueFilters</code> <p>Filtering options for issues returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_issues(  # noqa\n    labels: Iterable[str],\n    states: Iterable[graphql_schema.IssueState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.IssueOrder = None,\n    filter_by: graphql_schema.IssueFilters = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of issues associated with this user.\n\n    Args:\n        labels: A list of label names to filter the pull requests by.\n        states: A list of states to filter the issues by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for issues returned from the\n            connection.\n        filter_by: Filtering options for issues returned from the\n            connection.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).issues(\n        **strip_kwargs(\n            labels=labels,\n            states=states,\n            order_by=order_by,\n            filter_by=filter_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"issues\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"issues\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_item_showcase","title":"<code>query_viewer_item_showcase</code>  <code>async</code>","text":"<p>Showcases a selection of repositories and gists that the profile owner has either curated or that have been selected automatically based on popularity.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_item_showcase(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Showcases a selection of repositories and gists that the profile owner has\n    either curated or that have been selected automatically based on popularity.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).item_showcase(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"itemShowcase\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"itemShowcase\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_organization","title":"<code>query_viewer_organization</code>  <code>async</code>","text":"<p>Find an organization by its login that the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>login</code> <code>str</code> <p>The login of the organization to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_organization(  # noqa\n    login: str,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find an organization by its login that the user belongs to.\n\n    Args:\n        login: The login of the organization to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).organization(\n        **strip_kwargs(\n            login=login,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"organization\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"organization\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_organizations","title":"<code>query_viewer_organizations</code>  <code>async</code>","text":"<p>A list of organizations the user belongs to.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_organizations(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of organizations the user belongs to.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).organizations(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"organizations\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"organizations\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_packages","title":"<code>query_viewer_packages</code>  <code>async</code>","text":"<p>A list of packages under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>names</code> <code>Iterable[str]</code> <p>Find packages by their names.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Find packages in a repository by ID.</p> <code>None</code> <code>package_type</code> <code>PackageType</code> <p>Filter registry package by type.</p> <code>None</code> <code>order_by</code> <code>PackageOrder</code> <p>Ordering of the returned packages.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_packages(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    names: Iterable[str] = None,\n    repository_id: str = None,\n    package_type: graphql_schema.PackageType = None,\n    order_by: graphql_schema.PackageOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of packages under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        names: Find packages by their names.\n        repository_id: Find packages in a repository by ID.\n        package_type: Filter registry package by type.\n        order_by: Ordering of the returned packages.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).packages(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            names=names,\n            repository_id=repository_id,\n            package_type=package_type,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"packages\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"packages\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pinnable_items","title":"<code>query_viewer_pinnable_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner can pin to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinnable items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pinnable_items(  # noqa\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner can pin to their profile.\n\n    Args:\n        types: Filter the types of pinnable items that are\n            returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pinnable_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pinnableItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pinnableItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pinned_items","title":"<code>query_viewer_pinned_items</code>  <code>async</code>","text":"<p>A list of repositories and gists this profile owner has pinned to their profile.</p> <p>Parameters:</p> Name Type Description Default <code>types</code> <code>Iterable[PinnableItemType]</code> <p>Filter the types of pinned items that are returned.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pinned_items(  # noqa\n    types: Iterable[graphql_schema.PinnableItemType],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories and gists this profile owner has pinned to their profile.\n\n    Args:\n        types: Filter the types of pinned items that are returned.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pinned_items(\n        **strip_kwargs(\n            types=types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pinnedItems\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pinnedItems\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project","title":"<code>query_viewer_project</code>  <code>async</code>","text":"<p>Find project by number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project number to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find project by number.\n\n    Args:\n        number: The project number to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"project\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"project\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project_next","title":"<code>query_viewer_project_next</code>  <code>async</code>","text":"<p>Find a project by project (beta) number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project (beta) number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project_next(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by project (beta) number.\n\n    Args:\n        number: The project (beta) number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project_next(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_project_v2","title":"<code>query_viewer_project_v2</code>  <code>async</code>","text":"<p>Find a project by number.</p> <p>Parameters:</p> Name Type Description Default <code>number</code> <code>int</code> <p>The project number.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_project_v2(  # noqa\n    number: int,\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find a project by number.\n\n    Args:\n        number: The project number.\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).project_v2(\n        **strip_kwargs(\n            number=number,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects","title":"<code>query_viewer_projects</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>states</code> <code>Iterable[ProjectState]</code> <p>A list of states to filter the projects by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>order_by</code> <code>ProjectOrder</code> <p>Ordering options for projects returned from the connection.</p> <code>None</code> <code>search</code> <code>str</code> <p>Query to search projects by, currently only searching by name.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects(  # noqa\n    states: Iterable[graphql_schema.ProjectState],\n    github_credentials: GitHubCredentials,\n    order_by: graphql_schema.ProjectOrder = None,\n    search: str = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        states: A list of states to filter the projects by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        order_by: Ordering options for projects returned from the\n            connection.\n        search: Query to search projects by, currently only searching\n            by name.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects(\n        **strip_kwargs(\n            states=states,\n            order_by=order_by,\n            search=search,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projects\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects_next","title":"<code>query_viewer_projects_next</code>  <code>async</code>","text":"<p>A list of projects (beta) under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project (beta) to search for under the the owner.</p> <code>None</code> <code>sort_by</code> <code>ProjectNextOrderField</code> <p>How to order the returned projects (beta).</p> <code>'TITLE'</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects_next(  # noqa\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    sort_by: graphql_schema.ProjectNextOrderField = \"TITLE\",\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects (beta) under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project (beta) to search for under the the owner.\n        sort_by: How to order the returned projects (beta).\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects_next(\n        **strip_kwargs(\n            query=query,\n            sort_by=sort_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectsNext\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectsNext\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_projects_v2","title":"<code>query_viewer_projects_v2</code>  <code>async</code>","text":"<p>A list of projects under the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>query</code> <code>str</code> <p>A project to search for under the the owner.</p> <code>None</code> <code>order_by</code> <code>ProjectV2Order</code> <p>How to order the returned projects.</p> <code>{'field': 'NUMBER', 'direction': 'DESC'}</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_projects_v2(  # noqa\n    github_credentials: GitHubCredentials,\n    query: str = None,\n    order_by: graphql_schema.ProjectV2Order = {\"field\": \"NUMBER\", \"direction\": \"DESC\"},\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of projects under the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        query: A project to search for under the the owner.\n        order_by: How to order the returned projects.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).projects_v2(\n        **strip_kwargs(\n            query=query,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"projectsV2\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"projectsV2\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_public_keys","title":"<code>query_viewer_public_keys</code>  <code>async</code>","text":"<p>A list of public keys associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_public_keys(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of public keys associated with this user.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).public_keys(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"publicKeys\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"publicKeys\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_pull_requests","title":"<code>query_viewer_pull_requests</code>  <code>async</code>","text":"<p>A list of pull requests associated with this user.</p> <p>Parameters:</p> Name Type Description Default <code>states</code> <code>Iterable[PullRequestState]</code> <p>A list of states to filter the pull requests by.</p> required <code>labels</code> <code>Iterable[str]</code> <p>A list of label names to filter the pull requests by.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>head_ref_name</code> <code>str</code> <p>The head ref name to filter the pull requests by.</p> <code>None</code> <code>base_ref_name</code> <code>str</code> <p>The base ref name to filter the pull requests by.</p> <code>None</code> <code>order_by</code> <code>IssueOrder</code> <p>Ordering options for pull requests returned from the connection.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_pull_requests(  # noqa\n    states: Iterable[graphql_schema.PullRequestState],\n    labels: Iterable[str],\n    github_credentials: GitHubCredentials,\n    head_ref_name: str = None,\n    base_ref_name: str = None,\n    order_by: graphql_schema.IssueOrder = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of pull requests associated with this user.\n\n    Args:\n        states: A list of states to filter the pull requests by.\n        labels: A list of label names to filter the pull requests\n            by.\n        github_credentials: Credentials to use for authentication with GitHub.\n        head_ref_name: The head ref name to filter the pull\n            requests by.\n        base_ref_name: The base ref name to filter the pull\n            requests by.\n        order_by: Ordering options for pull requests returned from\n            the connection.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).pull_requests(\n        **strip_kwargs(\n            states=states,\n            labels=labels,\n            head_ref_name=head_ref_name,\n            base_ref_name=base_ref_name,\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"pullRequests\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"pullRequests\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_recent_projects","title":"<code>query_viewer_recent_projects</code>  <code>async</code>","text":"<p>Recent projects that this user has modified in the context of the owner.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_recent_projects(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Recent projects that this user has modified in the context of the owner.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).recent_projects(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"recentProjects\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"recentProjects\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repositories","title":"<code>query_viewer_repositories</code>  <code>async</code>","text":"<p>A list of repositories that the user owns.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of viewer's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the current viewer owns.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>is_fork</code> <code>bool</code> <p>If non-null, filters repositories according to whether they are forks of another repository.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repositories(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    is_fork: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user owns.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to\n            privacy.\n        order_by: Ordering options for repositories returned from\n            the connection.\n        affiliations: Array of viewer's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the current viewer\n            owns.\n        owner_affiliations: Array of owner's affiliation options\n            for repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        is_fork: If non-null, filters repositories according to\n            whether they are forks of another repository.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repositories(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            is_fork=is_fork,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repositories_contributed_to","title":"<code>query_viewer_repositories_contributed_to</code>  <code>async</code>","text":"<p>A list of repositories that the user recently contributed to.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>include_user_repositories</code> <code>bool</code> <p>If true, include user repositories.</p> <code>None</code> <code>contribution_types</code> <code>Iterable[RepositoryContributionType]</code> <p>If non-null, include only the specified types of contributions. The GitHub.com UI uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repositories_contributed_to(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    is_locked: bool = None,\n    include_user_repositories: bool = None,\n    contribution_types: Iterable[graphql_schema.RepositoryContributionType] = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories that the user recently contributed to.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories\n            according to privacy.\n        order_by: Ordering options for repositories\n            returned from the connection.\n        is_locked: If non-null, filters repositories\n            according to whether they have been locked.\n        include_user_repositories: If true, include\n            user repositories.\n        contribution_types: If non-null, include\n            only the specified types of contributions. The GitHub.com UI\n            uses [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY].\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repositories_contributed_to(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            is_locked=is_locked,\n            include_user_repositories=include_user_repositories,\n            contribution_types=contribution_types,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoriesContributedTo\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoriesContributedTo\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository","title":"<code>query_viewer_repository</code>  <code>async</code>","text":"<p>Find Repository.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of Repository to find.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>follow_renames</code> <code>bool</code> <p>Follow repository renames. If disabled, a repository referenced by its old name will return an error.</p> <code>True</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository(  # noqa\n    name: str,\n    github_credentials: GitHubCredentials,\n    follow_renames: bool = True,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Find Repository.\n\n    Args:\n        name: Name of Repository to find.\n        github_credentials: Credentials to use for authentication with GitHub.\n        follow_renames: Follow repository renames. If disabled, a\n            repository referenced by its old name will return an error.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository(\n        **strip_kwargs(\n            name=name,\n            follow_renames=follow_renames,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repository\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repository\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository_discussion_comments","title":"<code>query_viewer_repository_discussion_comments</code>  <code>async</code>","text":"<p>Discussion comments this user has authored.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>repository_id</code> <code>str</code> <p>Filter discussion comments to only those in a specific repository.</p> <code>None</code> <code>only_answers</code> <code>bool</code> <p>Filter discussion comments to only those that were marked as the answer.</p> <code>False</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository_discussion_comments(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    repository_id: str = None,\n    only_answers: bool = False,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussion comments this user has authored.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list\n            that come after the specified cursor.\n        before: Returns the elements in the list\n            that come before the specified cursor.\n        first: Returns the first _n_ elements\n            from the list.\n        last: Returns the last _n_ elements from\n            the list.\n        repository_id: Filter discussion comments\n            to only those in a specific repository.\n        only_answers: Filter discussion comments\n            to only those that were marked as the answer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository_discussion_comments(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            repository_id=repository_id,\n            only_answers=only_answers,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoryDiscussionComments\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoryDiscussionComments\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_repository_discussions","title":"<code>query_viewer_repository_discussions</code>  <code>async</code>","text":"<p>Discussions this user has started.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>DiscussionOrder</code> <p>Ordering options for discussions returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>repository_id</code> <code>str</code> <p>Filter discussions to only those in a specific repository.</p> <code>None</code> <code>answered</code> <code>bool</code> <p>Filter discussions to only those that have been answered or not. Defaults to including both answered and unanswered discussions.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_repository_discussions(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.DiscussionOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    repository_id: str = None,\n    answered: bool = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Discussions this user has started.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for discussions\n            returned from the connection.\n        repository_id: Filter discussions to only those\n            in a specific repository.\n        answered: Filter discussions to only those that\n            have been answered or not. Defaults to including both\n            answered and unanswered discussions.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).repository_discussions(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n            repository_id=repository_id,\n            answered=answered,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"repositoryDiscussions\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"repositoryDiscussions\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_saved_replies","title":"<code>query_viewer_saved_replies</code>  <code>async</code>","text":"<p>Replies this user has saved.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SavedReplyOrder</code> <p>The field to order saved replies by.</p> <code>{'field': 'UPDATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_saved_replies(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SavedReplyOrder = {\n        \"field\": \"UPDATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Replies this user has saved.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come before\n            the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: The field to order saved replies by.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).saved_replies(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"savedReplies\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"savedReplies\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsoring","title":"<code>query_viewer_sponsoring</code>  <code>async</code>","text":"<p>List of users and organizations this entity is sponsoring.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for the users and organizations returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsoring(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of users and organizations this entity is sponsoring.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        order_by: Ordering options for the users and organizations\n            returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsoring(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsoring\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsoring\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors","title":"<code>query_viewer_sponsors</code>  <code>async</code>","text":"<p>List of sponsors for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>tier_id</code> <code>str</code> <p>If given, will filter for sponsors at the given tier. Will only return sponsors whose tier the viewer is permitted to see.</p> <code>None</code> <code>order_by</code> <code>SponsorOrder</code> <p>Ordering options for sponsors returned from the connection.</p> <code>{'field': 'RELEVANCE', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    tier_id: str = None,\n    order_by: graphql_schema.SponsorOrder = {\"field\": \"RELEVANCE\", \"direction\": \"DESC\"},\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsors for this user or organization.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        tier_id: If given, will filter for sponsors at the given tier.\n            Will only return sponsors whose tier the viewer is permitted\n            to see.\n        order_by: Ordering options for sponsors returned from the\n            connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            tier_id=tier_id,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsors\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsors\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors_activities","title":"<code>query_viewer_sponsors_activities</code>  <code>async</code>","text":"<p>Events involving this sponsorable, such as new sponsorships.</p> <p>Parameters:</p> Name Type Description Default <code>actions</code> <code>Iterable[SponsorsActivityAction]</code> <p>Filter activities to only the specified actions.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>period</code> <code>SponsorsActivityPeriod</code> <p>Filter activities returned to only those that occurred in the most recent specified time period. Set to ALL to avoid filtering by when the activity occurred.</p> <code>'MONTH'</code> <code>order_by</code> <code>SponsorsActivityOrder</code> <p>Ordering options for activity returned from the connection.</p> <code>{'field': 'TIMESTAMP', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors_activities(  # noqa\n    actions: Iterable[graphql_schema.SponsorsActivityAction],\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    period: graphql_schema.SponsorsActivityPeriod = \"MONTH\",\n    order_by: graphql_schema.SponsorsActivityOrder = {\n        \"field\": \"TIMESTAMP\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Events involving this sponsorable, such as new sponsorships.\n\n    Args:\n        actions: Filter activities to only the specified\n            actions.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        period: Filter activities returned to only those\n            that occurred in the most recent specified time period. Set\n            to ALL to avoid filtering by when the activity occurred.\n        order_by: Ordering options for activity returned\n            from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors_activities(\n        **strip_kwargs(\n            actions=actions,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            period=period,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorsActivities\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorsActivities\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsors_listing","title":"<code>query_viewer_sponsors_listing</code>  <code>async</code>","text":"<p>The GitHub Sponsors listing for this user or organization.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsors_listing(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The GitHub Sponsors listing for this user or organization.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsors_listing(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorsListing\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorsListing\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsor","title":"<code>query_viewer_sponsorship_for_viewer_as_sponsor</code>  <code>async</code>","text":"<p>The sponsorship from the viewer to this user/organization; that is, the sponsorship where you're the sponsor. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_for_viewer_as_sponsor(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from the viewer to this user/organization; that is, the\n    sponsorship where you're the sponsor. Only returns a sponsorship if it is\n    active.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_for_viewer_as_sponsor(\n        **strip_kwargs()\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipForViewerAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipForViewerAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_for_viewer_as_sponsorable","title":"<code>query_viewer_sponsorship_for_viewer_as_sponsorable</code>  <code>async</code>","text":"<p>The sponsorship from this user/organization to the viewer; that is, the sponsorship you're receiving. Only returns a sponsorship if it is active.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_for_viewer_as_sponsorable(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The sponsorship from this user/organization to the viewer; that is, the\n    sponsorship you're receiving. Only returns a sponsorship if it is active.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_for_viewer_as_sponsorable(\n        **strip_kwargs()\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipForViewerAsSponsorable\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipForViewerAsSponsorable\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorship_newsletters","title":"<code>query_viewer_sponsorship_newsletters</code>  <code>async</code>","text":"<p>List of sponsorship updates sent from this sponsorable to sponsors.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipNewsletterOrder</code> <p>Ordering options for sponsorship updates returned from the connection.</p> <code>{'field': 'CREATED_AT', 'direction': 'DESC'}</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorship_newsletters(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipNewsletterOrder = {\n        \"field\": \"CREATED_AT\",\n        \"direction\": \"DESC\",\n    },\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    List of sponsorship updates sent from this sponsorable to sponsors.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorship\n            updates returned from the connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorship_newsletters(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipNewsletters\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipNewsletters\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorships_as_maintainer","title":"<code>query_viewer_sponsorships_as_maintainer</code>  <code>async</code>","text":"<p>This object's sponsorships as the maintainer.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>include_private</code> <code>bool</code> <p>Whether or not to include private sponsorships in the result set.</p> <code>False</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorships_as_maintainer(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    include_private: bool = False,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the maintainer.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from\n            the list.\n        last: Returns the last _n_ elements from the\n            list.\n        include_private: Whether or not to include\n            private sponsorships in the result set.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorships_as_maintainer(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            include_private=include_private,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipsAsMaintainer\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipsAsMaintainer\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_sponsorships_as_sponsor","title":"<code>query_viewer_sponsorships_as_sponsor</code>  <code>async</code>","text":"<p>This object's sponsorships as the sponsor.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>order_by</code> <code>SponsorshipOrder</code> <p>Ordering options for sponsorships returned from this connection. If left blank, the sponsorships will be ordered based on relevancy to the viewer.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_sponsorships_as_sponsor(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    order_by: graphql_schema.SponsorshipOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    This object's sponsorships as the sponsor.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that\n            come after the specified cursor.\n        before: Returns the elements in the list that\n            come before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the\n            list.\n        order_by: Ordering options for sponsorships\n            returned from this connection. If left blank, the\n            sponsorships will be ordered based on relevancy to the\n            viewer.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).sponsorships_as_sponsor(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"sponsorshipsAsSponsor\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"sponsorshipsAsSponsor\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_starred_repositories","title":"<code>query_viewer_starred_repositories</code>  <code>async</code>","text":"<p>Repositories the user has starred.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>owned_by_viewer</code> <code>bool</code> <p>Filters starred repositories to only return repositories owned by the viewer.</p> <code>None</code> <code>order_by</code> <code>StarOrder</code> <p>Order for connection.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_starred_repositories(  # noqa\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    owned_by_viewer: bool = None,\n    order_by: graphql_schema.StarOrder = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has starred.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come\n            after the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the\n            list.\n        last: Returns the last _n_ elements from the list.\n        owned_by_viewer: Filters starred repositories to\n            only return repositories owned by the viewer.\n        order_by: Order for connection.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).starred_repositories(\n        **strip_kwargs(\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            owned_by_viewer=owned_by_viewer,\n            order_by=order_by,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"starredRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"starredRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_status","title":"<code>query_viewer_status</code>  <code>async</code>","text":"<p>The user's description of what they're currently doing.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_status(  # noqa\n    github_credentials: GitHubCredentials,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    The user's description of what they're currently doing.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).status(**strip_kwargs())\n\n    op_stack = (\n        \"viewer\",\n        \"status\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"status\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_top_repositories","title":"<code>query_viewer_top_repositories</code>  <code>async</code>","text":"<p>Repositories the user has contributed to, ordered by contribution rank, plus repositories the user has created.</p> <p>Parameters:</p> Name Type Description Default <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> required <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>since</code> <code>datetime</code> <p>How far back in time to fetch contributed repositories.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_top_repositories(  # noqa\n    order_by: graphql_schema.RepositoryOrder,\n    github_credentials: GitHubCredentials,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    since: datetime = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    Repositories the user has contributed to, ordered by contribution rank, plus\n    repositories the user has created.\n\n    Args:\n        order_by: Ordering options for repositories returned\n            from the connection.\n        github_credentials: Credentials to use for authentication with GitHub.\n        after: Returns the elements in the list that come after\n            the specified cursor.\n        before: Returns the elements in the list that come\n            before the specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        since: How far back in time to fetch contributed\n            repositories.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).top_repositories(\n        **strip_kwargs(\n            order_by=order_by,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n            since=since,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"topRepositories\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"topRepositories\"]\n</code></pre>"},{"location":"integrations/prefect-github/viewer/#prefect_github.viewer.query_viewer_watching","title":"<code>query_viewer_watching</code>  <code>async</code>","text":"<p>A list of repositories the given user is watching.</p> <p>Parameters:</p> Name Type Description Default <code>github_credentials</code> <code>GitHubCredentials</code> <p>Credentials to use for authentication with GitHub.</p> required <code>privacy</code> <code>RepositoryPrivacy</code> <p>If non-null, filters repositories according to privacy.</p> <code>None</code> <code>order_by</code> <code>RepositoryOrder</code> <p>Ordering options for repositories returned from the connection.</p> <code>None</code> <code>affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Affiliation options for repositories returned from the connection. If none specified, the results will include repositories for which the current viewer is an owner or collaborator, or member.</p> <code>None</code> <code>owner_affiliations</code> <code>Iterable[RepositoryAffiliation]</code> <p>Array of owner's affiliation options for repositories returned from the connection. For example, OWNER will include only repositories that the organization or user being viewed owns.</p> <code>('OWNER', 'COLLABORATOR')</code> <code>is_locked</code> <code>bool</code> <p>If non-null, filters repositories according to whether they have been locked.</p> <code>None</code> <code>after</code> <code>str</code> <p>Returns the elements in the list that come after the specified cursor.</p> <code>None</code> <code>before</code> <code>str</code> <p>Returns the elements in the list that come before the specified cursor.</p> <code>None</code> <code>first</code> <code>int</code> <p>Returns the first n elements from the list.</p> <code>None</code> <code>last</code> <code>int</code> <p>Returns the last n elements from the list.</p> <code>None</code> <code>return_fields</code> <code>Iterable[str]</code> <p>Subset the return fields (as snake_case); defaults to fields listed in configs/query/*.json.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of the returned fields.</p> Source code in <code>prefect_github/viewer.py</code> <pre><code>@task\nasync def query_viewer_watching(  # noqa\n    github_credentials: GitHubCredentials,\n    privacy: graphql_schema.RepositoryPrivacy = None,\n    order_by: graphql_schema.RepositoryOrder = None,\n    affiliations: Iterable[graphql_schema.RepositoryAffiliation] = None,\n    owner_affiliations: Iterable[graphql_schema.RepositoryAffiliation] = (\n        \"OWNER\",\n        \"COLLABORATOR\",\n    ),\n    is_locked: bool = None,\n    after: str = None,\n    before: str = None,\n    first: int = None,\n    last: int = None,\n    return_fields: Iterable[str] = None,\n) -&gt; Dict[str, Any]:  # pragma: no cover\n    \"\"\"\n    A list of repositories the given user is watching.\n\n    Args:\n        github_credentials: Credentials to use for authentication with GitHub.\n        privacy: If non-null, filters repositories according to privacy.\n        order_by: Ordering options for repositories returned from the\n            connection.\n        affiliations: Affiliation options for repositories returned\n            from the connection. If none specified, the results will\n            include repositories for which the current viewer is an\n            owner or collaborator, or member.\n        owner_affiliations: Array of owner's affiliation options for\n            repositories returned from the connection. For example,\n            OWNER will include only repositories that the organization\n            or user being viewed owns.\n        is_locked: If non-null, filters repositories according to\n            whether they have been locked.\n        after: Returns the elements in the list that come after the\n            specified cursor.\n        before: Returns the elements in the list that come before the\n            specified cursor.\n        first: Returns the first _n_ elements from the list.\n        last: Returns the last _n_ elements from the list.\n        return_fields: Subset the return fields (as snake_case); defaults to\n            fields listed in configs/query/*.json.\n\n    Returns:\n        A dict of the returned fields.\n    \"\"\"\n    op = Operation(graphql_schema.Query)\n    op_selection = op.viewer(**strip_kwargs()).watching(\n        **strip_kwargs(\n            privacy=privacy,\n            order_by=order_by,\n            affiliations=affiliations,\n            owner_affiliations=owner_affiliations,\n            is_locked=is_locked,\n            after=after,\n            before=before,\n            first=first,\n            last=last,\n        )\n    )\n\n    op_stack = (\n        \"viewer\",\n        \"watching\",\n    )\n    op_selection = _subset_return_fields(\n        op_selection, op_stack, return_fields, return_fields_defaults\n    )\n\n    result = await _execute_graphql_op(op, github_credentials)\n    return result[\"viewer\"][\"watching\"]\n</code></pre>"},{"location":"integrations/prefect-gitlab/","title":"prefect-gitlab","text":"<p>The prefect-gitlab library makes it easy to interact with GitLab repositories and credentials.</p>"},{"location":"integrations/prefect-gitlab/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-gitlab/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> <li>A GitLab account.</li> </ul>"},{"location":"integrations/prefect-gitlab/#install-prefect-gitlab","title":"Install prefect-gitlab","text":"<pre><code>pip install -U prefect-gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-gitlab module to make them available for use.</p> <pre><code>prefect block register -m prefect_gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/#examples","title":"Examples","text":"<p>In the examples below, you create blocks with Python code. Alternatively, blocks can be created through the Prefect UI.</p>"},{"location":"integrations/prefect-gitlab/#store-deployment-flow-code-in-a-private-gitlab-repository","title":"Store deployment flow code in a private GitLab repository","text":"<p>To create a deployment where the flow code is stored in a private GitLab repository, you can use the <code>GitLabCredentials</code> block.</p> <p>A deployment can use flow code stored in a GitLab repository without using this library in either of the following cases:</p> <ul> <li>The repository is public</li> <li>The deployment uses a Secret block to store the token</li> </ul> <p>Code to create a GitLab Credentials block:</p> <pre><code>from prefect_gitlab import GitLabCredentials\n\n\ngitlab_credentials_block = GitLabCredentials(token=\"my_token\")\ngitlab_credentials_block.save(name=\"my-gitlab-credentials-block\")\n</code></pre>"},{"location":"integrations/prefect-gitlab/#access-flow-code-stored-in-a-private-gitlab-repository-in-a-deployment","title":"Access flow code stored in a private GitLab repository in a deployment","text":"<p>Use the credentials block you created above to pass the GitLab access token during deployment creation. The code below assumes there's flow code in your private GitLab repository.</p> <pre><code>from prefect import flow\nfrom prefect.runner.storage import GitRepository\nfrom prefect_gitlab import GitLabCredentials\n\n\nif __name__ == \"__main__\":\n    flow.from_source(\n        source=GitRepository(\n        url=\"https://gitlab.com/org/private-repo.git\",\n        credentials=GitLabCredentials.load(\"my-gitlab-credentials-block\")\n    ),\n    entrypoint=\"my_file.py:my_flow\",\n    ).deploy(\n        name=\"private-gitlab-deploy\",\n        work_pool_name=\"my_pool\",\n        build=False\n    )\n</code></pre> <p>Alternatively, if you use a <code>prefect.yaml</code> file to create the deployment, reference the GitLab Credentials block in the <code>pull</code> step:</p> <pre><code>pull:\n    - prefect.deployments.steps.git_clone:\n        repository: https://github.com/org/repo.git\n        credentials: \"{{ prefect.blocks.gitlab-credentials.my-gitlab-credentials-block }}\"\n</code></pre>"},{"location":"integrations/prefect-gitlab/#interact-with-a-gitlab-repository","title":"Interact with a GitLab repository","text":"<p>The code below shows how to reference a particular branch or tag of a GitLab repository.</p> <pre><code>from prefect_gitlab import GitLabRepository\n\ndef save_private_gitlab_block():\n    private_gitlab_block = GitLabRepository(\n        repository=\"https://gitlab.com/testing/my-repository.git\",\n        access_token=\"YOUR_GITLAB_PERSONAL_ACCESS_TOKEN\",\n        reference=\"branch-or-tag-name\",\n    )\n\n    private_gitlab_block.save(\"my-private-gitlab-block\")\n\n\nif __name__ == \"__main__\":\n    save_private_gitlab_block()\n</code></pre> <p>Exclude the <code>access_token</code> field if the repository is public and exclude the <code>reference</code> field to use the default branch.</p> <p>Use the newly created block to interact with the GitLab repository.</p> <p>For example, download the repository contents with the <code>.get_directory()</code> method like this:</p> <pre><code>from prefect_gitlab.repositories import GitLabRepository\n\ndef fetch_repo():\n    private_gitlab_block = GitLabRepository.load(\"my-gitlab-block\")\n    private_gitlab_block.get_directory()\n\nif __name__ == \"__main__\":\n    fetch_repo()\n</code></pre>"},{"location":"integrations/prefect-gitlab/#resources","title":"Resources","text":"<p>For assistance using GitLab, consult the GitLab documentation.</p> <p>Refer to the prefect-gitlab API documentation linked in the sidebar to explore all the capabilities of the prefect-gitlab library.</p>"},{"location":"integrations/prefect-gitlab/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials","title":"<code>prefect_gitlab.credentials</code>","text":"<p>Module used to enable authenticated interactions with GitLab</p>"},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials.GitLabCredentials","title":"<code>GitLabCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Store a GitLab personal access token to interact with private GitLab repositories.</p> <p>Attributes:</p> Name Type Description <code>token</code> <code>SecretStr</code> <p>The personal access token to authenticate with GitLab.</p> <code>url</code> <code>str</code> <p>URL to self-hosted GitLab instances.</p> <p>Examples:</p> <p>Load stored GitLab credentials: <pre><code>from prefect_gitlab import GitLabCredentials\ngitlab_credentials_block = GitLabCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_gitlab/credentials.py</code> <pre><code>class GitLabCredentials(Block):\n    \"\"\"\n    Store a GitLab personal access token to interact with private GitLab\n    repositories.\n\n    Attributes:\n        token: The personal access token to authenticate with GitLab.\n        url: URL to self-hosted GitLab instances.\n\n    Examples:\n        Load stored GitLab credentials:\n        ```python\n        from prefect_gitlab import GitLabCredentials\n        gitlab_credentials_block = GitLabCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"GitLab Credentials\"\n    _logo_url = HttpUrl(\n        url=\"https://images.ctfassets.net/gm98wzqotmnx/55edIimT4g9gbjhkh5a3Sp/dfdb9391d8f45c2e93e72e3a4d350771/gitlab-logo-500.png?h=250\",  # noqa\n        scheme=\"https\",\n    )\n\n    token: SecretStr = Field(\n        name=\"Personal Access Token\",\n        default=None,\n        description=\"A GitLab Personal Access Token with read_repository scope.\",\n    )\n    url: str = Field(\n        default=None, title=\"URL\", description=\"URL to self-hosted GitLab instances.\"\n    )\n\n    def get_client(self) -&gt; Gitlab:\n        \"\"\"\n        Gets an authenticated GitLab client.\n\n        Returns:\n            An authenticated GitLab client.\n        \"\"\"\n        # ref: https://python-gitlab.readthedocs.io/en/stable/\n        gitlab = Gitlab(url=self.url, oauth_token=self.token.get_secret_value())\n        gitlab.auth()\n        return gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/credentials/#prefect_gitlab.credentials.GitLabCredentials.get_client","title":"<code>get_client</code>","text":"<p>Gets an authenticated GitLab client.</p> <p>Returns:</p> Type Description <code>Gitlab</code> <p>An authenticated GitLab client.</p> Source code in <code>prefect_gitlab/credentials.py</code> <pre><code>def get_client(self) -&gt; Gitlab:\n    \"\"\"\n    Gets an authenticated GitLab client.\n\n    Returns:\n        An authenticated GitLab client.\n    \"\"\"\n    # ref: https://python-gitlab.readthedocs.io/en/stable/\n    gitlab = Gitlab(url=self.url, oauth_token=self.token.get_secret_value())\n    gitlab.auth()\n    return gitlab\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/","title":"Repositories","text":""},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories","title":"<code>prefect_gitlab.repositories</code>","text":"<p>Integrations with GitLab.</p> <p>The <code>GitLab</code> class in this collection is a storage block that lets Prefect agents pull Prefect flow code from GitLab repositories.</p> <p>The <code>GitLab</code> block is ideally configured via the Prefect UI, but can also be used in Python as the following examples demonstrate.</p> <p>Examples:</p> <pre><code>    from prefect_gitlab.repositories import GitLabRepository\n\n    # public GitLab repository\n    public_gitlab_block = GitLabRepository(\n        name=\"my-gitlab-block\",\n        repository=\"https://gitlab.com/testing/my-repository.git\"\n    )\n\n    public_gitlab_block.save()\n\n\n    # specific branch or tag of a GitLab repository\n    branch_gitlab_block = GitLabRepository(\n        name=\"my-gitlab-block\",\n        reference=\"branch-or-tag-name\"\n        repository=\"https://gitlab.com/testing/my-repository.git\"\n    )\n\n    branch_gitlab_block.save()\n\n\n    # private GitLab repository\n    private_gitlab_block = GitLabRepository(\n        name=\"my-private-gitlab-block\",\n        repository=\"https://gitlab.com/testing/my-repository.git\",\n        access_token=\"YOUR_GITLAB_PERSONAL_ACCESS_TOKEN\"\n    )\n\n    private_gitlab_block.save()\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories.GitLabRepository","title":"<code>GitLabRepository</code>","text":"<p>               Bases: <code>ReadableDeploymentStorage</code></p> <p>Interact with files stored in GitLab repositories.</p> <p>An accessible installation of git is required for this block to function properly.</p> Source code in <code>prefect_gitlab/repositories.py</code> <pre><code>class GitLabRepository(ReadableDeploymentStorage):\n    \"\"\"\n    Interact with files stored in GitLab repositories.\n\n    An accessible installation of git is required for this block to function\n    properly.\n    \"\"\"\n\n    _block_type_name = \"GitLab Repository\"\n    _logo_url = HttpUrl(\n        url=\"https://images.ctfassets.net/gm98wzqotmnx/55edIimT4g9gbjhkh5a3Sp/dfdb9391d8f45c2e93e72e3a4d350771/gitlab-logo-500.png?h=250\",  # noqa\n        scheme=\"https\",\n    )\n    _description = \"Interact with files stored in GitLab repositories.\"\n\n    repository: str = Field(\n        default=...,\n        description=(\n            \"The URL of a GitLab repository to read from, in either HTTP/HTTPS or SSH format.\"  # noqa\n        ),\n    )\n    reference: Optional[str] = Field(\n        default=None,\n        description=\"An optional reference to pin to; can be a branch name or tag.\",\n    )\n    git_depth: Optional[int] = Field(\n        default=1,\n        gte=1,\n        description=\"The number of commits that Git history is truncated to \"\n        \"during cloning. Set to None to fetch the entire history.\",\n    )\n    credentials: Optional[GitLabCredentials] = Field(\n        default=None,\n        description=\"An optional GitLab Credentials block for authenticating with \"\n        \"private GitLab repos.\",\n    )\n\n    @validator(\"credentials\")\n    def _ensure_credentials_go_with_http(cls, v: str, values: dict) -&gt; str:\n        \"\"\"Ensure that credentials are not provided with 'SSH' formatted GitLub URLs.\n        Note: validates `access_token` specifically so that it only fires when\n        private repositories are used.\n        \"\"\"\n        if v is not None:\n            if urllib.parse.urlparse(values[\"repository\"]).scheme not in [\n                \"https\",\n                \"http\",\n            ]:\n                raise InvalidRepositoryURLError(\n                    (\n                        \"Credentials can only be used with GitLab repositories \"\n                        \"using the 'HTTPS'/'HTTP' format. You must either remove the \"\n                        \"credential if you wish to use the 'SSH' format and are not \"\n                        \"using a private repository, or you must change the repository \"\n                        \"URL to the 'HTTPS'/'HTTP' format.\"\n                    )\n                )\n\n        return v\n\n    def _create_repo_url(self) -&gt; str:\n        \"\"\"Format the URL provided to the `git clone` command.\n        For private repos: https://&lt;oauth-key&gt;@gitlab.com/&lt;username&gt;/&lt;repo&gt;.git\n        All other repos should be the same as `self.repository`.\n        \"\"\"\n        url_components = urllib.parse.urlparse(self.repository)\n        if url_components.scheme in [\"https\", \"http\"] and self.credentials is not None:\n            token = self.credentials.token.get_secret_value()\n            updated_components = url_components._replace(\n                netloc=f\"oauth2:{token}@{url_components.netloc}\"\n            )\n            full_url = urllib.parse.urlunparse(updated_components)\n        else:\n            full_url = self.repository\n\n        return full_url\n\n    @staticmethod\n    def _get_paths(\n        dst_dir: Union[str, None], src_dir: str, sub_directory: Optional[str]\n    ) -&gt; Tuple[str, str]:\n        \"\"\"Returns the fully formed paths for GitLabRepository contents in the form\n        (content_source, content_destination).\n        \"\"\"\n        if dst_dir is None:\n            content_destination = Path(\".\").absolute()\n        else:\n            content_destination = Path(dst_dir)\n\n        content_source = Path(src_dir)\n\n        if sub_directory:\n            content_destination = content_destination.joinpath(sub_directory)\n            content_source = content_source.joinpath(sub_directory)\n\n        return str(content_source), str(content_destination)\n\n    @sync_compatible\n    @retry(\n        stop=stop_after_attempt(MAX_CLONE_ATTEMPTS),\n        wait=wait_fixed(CLONE_RETRY_MIN_DELAY_SECONDS)\n        + wait_random(\n            CLONE_RETRY_MIN_DELAY_JITTER_SECONDS,\n            CLONE_RETRY_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    async def get_directory(\n        self, from_path: Optional[str] = None, local_path: Optional[str] = None\n    ) -&gt; None:\n        \"\"\"\n        Clones a GitLab project specified in `from_path` to the provided `local_path`;\n        defaults to cloning the repository reference configured on the Block to the\n        present working directory.\n        Args:\n            from_path: If provided, interpreted as a subdirectory of the underlying\n                repository that will be copied to the provided local path.\n            local_path: A local path to clone to; defaults to present working directory.\n        \"\"\"\n        # CONSTRUCT COMMAND\n        cmd = [\"git\", \"clone\", self._create_repo_url()]\n        if self.reference:\n            cmd += [\"-b\", self.reference]\n\n        # Limit git history\n        if self.git_depth is not None:\n            cmd += [\"--depth\", f\"{self.git_depth}\"]\n\n        # Clone to a temporary directory and move the subdirectory over\n        with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n            cmd.append(tmp_dir)\n\n            err_stream = io.StringIO()\n            out_stream = io.StringIO()\n            process = await run_process(cmd, stream_output=(out_stream, err_stream))\n            if process.returncode != 0:\n                err_stream.seek(0)\n                raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n            content_source, content_destination = self._get_paths(\n                dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n            )\n\n            shutil.copytree(\n                src=content_source, dst=content_destination, dirs_exist_ok=True\n            )\n</code></pre>"},{"location":"integrations/prefect-gitlab/repositories/#prefect_gitlab.repositories.GitLabRepository.get_directory","title":"<code>get_directory</code>  <code>async</code>","text":"<p>Clones a GitLab project specified in <code>from_path</code> to the provided <code>local_path</code>; defaults to cloning the repository reference configured on the Block to the present working directory. Args:     from_path: If provided, interpreted as a subdirectory of the underlying         repository that will be copied to the provided local path.     local_path: A local path to clone to; defaults to present working directory.</p> Source code in <code>prefect_gitlab/repositories.py</code> <pre><code>@sync_compatible\n@retry(\n    stop=stop_after_attempt(MAX_CLONE_ATTEMPTS),\n    wait=wait_fixed(CLONE_RETRY_MIN_DELAY_SECONDS)\n    + wait_random(\n        CLONE_RETRY_MIN_DELAY_JITTER_SECONDS,\n        CLONE_RETRY_MAX_DELAY_JITTER_SECONDS,\n    ),\n    reraise=True,\n)\nasync def get_directory(\n    self, from_path: Optional[str] = None, local_path: Optional[str] = None\n) -&gt; None:\n    \"\"\"\n    Clones a GitLab project specified in `from_path` to the provided `local_path`;\n    defaults to cloning the repository reference configured on the Block to the\n    present working directory.\n    Args:\n        from_path: If provided, interpreted as a subdirectory of the underlying\n            repository that will be copied to the provided local path.\n        local_path: A local path to clone to; defaults to present working directory.\n    \"\"\"\n    # CONSTRUCT COMMAND\n    cmd = [\"git\", \"clone\", self._create_repo_url()]\n    if self.reference:\n        cmd += [\"-b\", self.reference]\n\n    # Limit git history\n    if self.git_depth is not None:\n        cmd += [\"--depth\", f\"{self.git_depth}\"]\n\n    # Clone to a temporary directory and move the subdirectory over\n    with TemporaryDirectory(suffix=\"prefect\") as tmp_dir:\n        cmd.append(tmp_dir)\n\n        err_stream = io.StringIO()\n        out_stream = io.StringIO()\n        process = await run_process(cmd, stream_output=(out_stream, err_stream))\n        if process.returncode != 0:\n            err_stream.seek(0)\n            raise OSError(f\"Failed to pull from remote:\\n {err_stream.read()}\")\n\n        content_source, content_destination = self._get_paths(\n            dst_dir=local_path, src_dir=tmp_dir, sub_directory=from_path\n        )\n\n        shutil.copytree(\n            src=content_source, dst=content_destination, dirs_exist_ok=True\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/","title":"prefect-kubernetes","text":"<p><code>prefect-kubernetes</code> contains Prefect tasks, flows, and blocks enabling orchestration, observation and management of Kubernetes resources.</p> <p>This library is most commonly used to installation with a Kubernetes worker. See the Kubernetes guide to learn how to create and run deployments in Kubernetes. As noted in that guide, Prefect also provides a Helm chart for deploying a worker, a self-hosted server instance, and other resources to a Kubernetes cluster. See the Prefect Helm chart for more information.</p>"},{"location":"integrations/prefect-kubernetes/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-kubernetes/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> <li>Kubernetes installed.</li> </ul>"},{"location":"integrations/prefect-kubernetes/#install-prefect-kubernetes","title":"Install <code>prefect-kubernetes</code>","text":"<pre><code> pip install prefect-kubernetes\n ```\n &lt;/div&gt;\n\n### Register newly installed block types\n\nRegister the block types in the prefect-aws module to make them available for use.\n\n&lt;div class=\"terminal\"&gt;\n```bash\nprefect block register -m prefect_kubernetes\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#examples","title":"Examples","text":""},{"location":"integrations/prefect-kubernetes/#use-with_options-to-customize-options-on-an-existing-task-or-flow","title":"Use <code>with_options</code> to customize options on an existing task or flow","text":"<pre><code>from prefect_kubernetes.flows import run_namespaced_job\n\ncustomized_run_namespaced_job = run_namespaced_job.with_options(\n    name=\"My flow running a Kubernetes Job\",\n    retries=2,\n    retry_delay_seconds=10,\n) # this is now a new flow object that can be called\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#specify-and-run-a-kubernetes-job-from-a-yaml-file","title":"Specify and run a Kubernetes Job from a YAML file","text":"<pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.flows import run_namespaced_job # this is a flow\nfrom prefect_kubernetes.jobs import KubernetesJob\n\nk8s_creds = KubernetesCredentials.load(\"k8s-creds\")\n\njob = KubernetesJob.from_yaml_file( # or create in the UI with a dict manifest\n    credentials=k8s_creds,\n    manifest_path=\"path/to/job.yaml\",\n)\n\njob.save(\"my-k8s-job\", overwrite=True)\n\nif __name__ == \"__main__\":\n    # run the flow\n    run_namespaced_job(job)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#generate-a-resource-specific-client-from-kubernetesclusterconfig","title":"Generate a resource-specific client from <code>KubernetesClusterConfig</code>","text":"<pre><code># with minikube / docker desktop &amp; a valid ~/.kube/config this should ~just work~\nfrom prefect.blocks.kubernetes import KubernetesClusterConfig\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\nk8s_config = KubernetesClusterConfig.from_file('~/.kube/config')\n\nk8s_credentials = KubernetesCredentials(cluster_config=k8s_config)\n\nwith k8s_credentials.get_client(\"core\") as v1_core_client:\n    for namespace in v1_core_client.list_namespace().items:\n        print(namespace.metadata.name)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#list-jobs-in-a-namespace","title":"List jobs in a namespace","text":"<pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import list_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_list = list_namespaced_job(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        namespace=\"my-namespace\",\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/#patch-an-existing-kubernetes-deployment","title":"Patch an existing Kubernetes deployment","text":"<pre><code>from kubernetes.client.models import V1Deployment\n\nfrom prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import patch_namespaced_deployment\nfrom prefect_kubernetes.utilities import convert_manifest_to_model\n\n@flow\ndef kubernetes_orchestrator():\n\n    v1_deployment_updates = convert_manifest_to_model(\n        manifest=\"path/to/manifest.yaml\",\n        v1_model_name=\"V1Deployment\",\n    )\n\n    v1_deployment = patch_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"my-deployment\",\n        deployment_updates=v1_deployment_updates,\n        namespace=\"my-namespace\"\n    )\n</code></pre> <p>For assistance using Kubernetes, consult the Kubernetes documentation.</p> <p>Refer to the prefect-kubernetes API documentation linked in the sidebar to explore all the capabilities of the prefect-kubernetes library.</p>"},{"location":"integrations/prefect-kubernetes/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials","title":"<code>prefect_kubernetes.credentials</code>","text":"<p>Module for defining Kubernetes credential handling and client generation.</p>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig","title":"<code>KubernetesClusterConfig</code>","text":"<p>               Bases: <code>Block</code></p> <p>Stores configuration for interaction with Kubernetes clusters.</p> <p>See <code>from_file</code> for creation.</p> <p>Attributes:</p> Name Type Description <code>config</code> <code>Dict</code> <p>The entire loaded YAML contents of a kubectl config file</p> <code>context_name</code> <code>str</code> <p>The name of the kubectl context to use</p> Example <p>Load a saved Kubernetes cluster config: <pre><code>from prefect_kubernetes.credentials import import KubernetesClusterConfig\n\ncluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>class KubernetesClusterConfig(Block):\n    \"\"\"\n    Stores configuration for interaction with Kubernetes clusters.\n\n    See `from_file` for creation.\n\n    Attributes:\n        config: The entire loaded YAML contents of a kubectl config file\n        context_name: The name of the kubectl context to use\n\n    Example:\n        Load a saved Kubernetes cluster config:\n        ```python\n        from prefect_kubernetes.credentials import import KubernetesClusterConfig\n\n        cluster_config_block = KubernetesClusterConfig.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Cluster Config\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig\"  # noqa\n    config: Dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n\n    @validator(\"config\", pre=True)\n    @classmethod\n    def parse_yaml_config(cls, value):\n        if isinstance(value, str):\n            return yaml.safe_load(value)\n        return value\n\n    @classmethod\n    def from_file(\n        cls: Type[Self], path: Optional[Path] = None, context_name: Optional[str] = None\n    ) -&gt; Self:\n        \"\"\"\n        Create a cluster config from the a Kubernetes config file.\n\n        By default, the current context in the default Kubernetes config file will be\n        used.\n\n        An alternative file or context may be specified.\n\n        The entire config file will be loaded and stored.\n        \"\"\"\n\n        path = Path(path or config.kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n        path = path.expanduser().resolve()\n\n        # Determine the context\n        (\n            existing_contexts,\n            current_context,\n        ) = config.kube_config.list_kube_config_contexts(config_file=str(path))\n        context_names = {ctx[\"name\"] for ctx in existing_contexts}\n        if context_name:\n            if context_name not in context_names:\n                raise ValueError(\n                    f\"Context {context_name!r} not found. \"\n                    f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n                )\n        else:\n            context_name = current_context[\"name\"]\n\n        # Load the entire config file\n        config_file_contents = path.read_text()\n        config_dict = yaml.safe_load(config_file_contents)\n        return cls(config=config_dict, context_name=context_name)\n\n    async def get_api_client(self) -&gt; \"ApiClient\":\n        \"\"\"\n        Returns a Kubernetes API client for this cluster config.\n        \"\"\"\n        return await config.kube_config.new_client_from_config_dict(\n            config_dict=self.config, context=self.context_name\n        )\n\n    async def configure_client(self) -&gt; None:\n        \"\"\"\n        Activates this cluster configuration by loading the configuration into the\n        Kubernetes Python client. After calling this, Kubernetes API clients can use\n        this config's context.\n        \"\"\"\n        await config.kube_config.load_kube_config_from_dict(\n            config_dict=self.config, context=self.context_name\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.configure_client","title":"<code>configure_client</code>  <code>async</code>","text":"<p>Activates this cluster configuration by loading the configuration into the Kubernetes Python client. After calling this, Kubernetes API clients can use this config's context.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def configure_client(self) -&gt; None:\n    \"\"\"\n    Activates this cluster configuration by loading the configuration into the\n    Kubernetes Python client. After calling this, Kubernetes API clients can use\n    this config's context.\n    \"\"\"\n    await config.kube_config.load_kube_config_from_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.from_file","title":"<code>from_file</code>  <code>classmethod</code>","text":"<p>Create a cluster config from the a Kubernetes config file.</p> <p>By default, the current context in the default Kubernetes config file will be used.</p> <p>An alternative file or context may be specified.</p> <p>The entire config file will be loaded and stored.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>@classmethod\ndef from_file(\n    cls: Type[Self], path: Optional[Path] = None, context_name: Optional[str] = None\n) -&gt; Self:\n    \"\"\"\n    Create a cluster config from the a Kubernetes config file.\n\n    By default, the current context in the default Kubernetes config file will be\n    used.\n\n    An alternative file or context may be specified.\n\n    The entire config file will be loaded and stored.\n    \"\"\"\n\n    path = Path(path or config.kube_config.KUBE_CONFIG_DEFAULT_LOCATION)\n    path = path.expanduser().resolve()\n\n    # Determine the context\n    (\n        existing_contexts,\n        current_context,\n    ) = config.kube_config.list_kube_config_contexts(config_file=str(path))\n    context_names = {ctx[\"name\"] for ctx in existing_contexts}\n    if context_name:\n        if context_name not in context_names:\n            raise ValueError(\n                f\"Context {context_name!r} not found. \"\n                f\"Specify one of: {listrepr(context_names, sep=', ')}.\"\n            )\n    else:\n        context_name = current_context[\"name\"]\n\n    # Load the entire config file\n    config_file_contents = path.read_text()\n    config_dict = yaml.safe_load(config_file_contents)\n    return cls(config=config_dict, context_name=context_name)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesClusterConfig.get_api_client","title":"<code>get_api_client</code>  <code>async</code>","text":"<p>Returns a Kubernetes API client for this cluster config.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def get_api_client(self) -&gt; \"ApiClient\":\n    \"\"\"\n    Returns a Kubernetes API client for this cluster config.\n    \"\"\"\n    return await config.kube_config.new_client_from_config_dict(\n        config_dict=self.config, context=self.context_name\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials","title":"<code>KubernetesCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Credentials block for generating configured Kubernetes API clients.</p> <p>Attributes:</p> Name Type Description <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>A <code>KubernetesClusterConfig</code> block holding a JSON kube config for a specific kubernetes context.</p> Example <p>Load stored Kubernetes credentials: <pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\n\nkubernetes_credentials = KubernetesCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>class KubernetesCredentials(Block):\n    \"\"\"Credentials block for generating configured Kubernetes API clients.\n\n    Attributes:\n        cluster_config: A `KubernetesClusterConfig` block holding a JSON kube\n            config for a specific kubernetes context.\n\n    Example:\n        Load stored Kubernetes credentials:\n        ```python\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        kubernetes_credentials = KubernetesCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Kubernetes Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials\"  # noqa\n\n    cluster_config: Optional[KubernetesClusterConfig] = None\n\n    @asynccontextmanager\n    async def get_client(\n        self,\n        client_type: Literal[\"apps\", \"batch\", \"core\", \"custom_objects\"],\n        configuration: Optional[Configuration] = None,\n    ) -&gt; AsyncGenerator[KubernetesClient, None]:\n        \"\"\"Convenience method for retrieving a Kubernetes API client for deployment resources.\n\n        Args:\n            client_type: The resource-specific type of Kubernetes client to retrieve.\n\n        Yields:\n            An authenticated, resource-specific Kubernetes API client.\n\n        Example:\n            ```python\n            from prefect_kubernetes.credentials import KubernetesCredentials\n\n            async with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n                pods = await core_v1_client.list_namespaced_pod()\n                for pod in pods.items:\n                    print(pod.metadata.name)\n            ```\n        \"\"\"\n        client_configuration = configuration or Configuration()\n        if self.cluster_config:\n            config_dict = self.cluster_config.config\n            context = self.cluster_config.context_name\n\n            # Use Configuration to load configuration from a dictionary\n\n            await config.load_kube_config_from_dict(\n                config_dict=config_dict,\n                context=context,\n                client_configuration=client_configuration,\n            )\n        async with ApiClient(configuration=client_configuration) as api_client:\n            try:\n                yield await self.get_resource_specific_client(\n                    client_type, api_client=api_client\n                )\n            finally:\n                await api_client.close()\n\n    async def get_resource_specific_client(\n        self,\n        client_type: str,\n        api_client: ApiClient,\n    ) -&gt; Union[AppsV1Api, BatchV1Api, CoreV1Api]:\n        \"\"\"\n        Utility function for configuring a generic Kubernetes client.\n        It will attempt to connect to a Kubernetes cluster in three steps with\n        the first successful connection attempt becoming the mode of communication with\n        a cluster:\n\n        1. It will first attempt to use a `KubernetesCredentials` block's\n        `cluster_config` to configure a client using\n        `KubernetesClusterConfig.configure_client`.\n\n        2. Attempt in-cluster connection (will only work when running on a pod).\n\n        3. Attempt out-of-cluster connection using the default location for a\n        kube config file.\n\n        Args:\n            client_type: The Kubernetes API client type for interacting with specific\n                Kubernetes resources.\n\n        Returns:\n            KubernetesClient: An authenticated, resource-specific Kubernetes Client.\n\n        Raises:\n            ValueError: If `client_type` is not a valid Kubernetes API client type.\n        \"\"\"\n\n        if self.cluster_config:\n            await self.cluster_config.configure_client()\n        else:\n            try:\n                config.load_incluster_config()\n            except ConfigException:\n                await config.load_kube_config()\n\n        try:\n            return K8S_CLIENT_TYPES[client_type](api_client)\n        except KeyError:\n            raise ValueError(\n                f\"Invalid client type provided '{client_type}'.\"\n                f\" Must be one of {listrepr(K8S_CLIENT_TYPES.keys())}.\"\n            )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials.get_client","title":"<code>get_client</code>  <code>async</code>","text":"<p>Convenience method for retrieving a Kubernetes API client for deployment resources.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['apps', 'batch', 'core', 'custom_objects']</code> <p>The resource-specific type of Kubernetes client to retrieve.</p> required <p>Yields:</p> Type Description <code>AsyncGenerator[KubernetesClient, None]</code> <p>An authenticated, resource-specific Kubernetes API client.</p> Example <pre><code>from prefect_kubernetes.credentials import KubernetesCredentials\n\nasync with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n    pods = await core_v1_client.list_namespaced_pod()\n    for pod in pods.items:\n        print(pod.metadata.name)\n</code></pre> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>@asynccontextmanager\nasync def get_client(\n    self,\n    client_type: Literal[\"apps\", \"batch\", \"core\", \"custom_objects\"],\n    configuration: Optional[Configuration] = None,\n) -&gt; AsyncGenerator[KubernetesClient, None]:\n    \"\"\"Convenience method for retrieving a Kubernetes API client for deployment resources.\n\n    Args:\n        client_type: The resource-specific type of Kubernetes client to retrieve.\n\n    Yields:\n        An authenticated, resource-specific Kubernetes API client.\n\n    Example:\n        ```python\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        async with KubernetesCredentials.get_client(\"core\") as core_v1_client:\n            pods = await core_v1_client.list_namespaced_pod()\n            for pod in pods.items:\n                print(pod.metadata.name)\n        ```\n    \"\"\"\n    client_configuration = configuration or Configuration()\n    if self.cluster_config:\n        config_dict = self.cluster_config.config\n        context = self.cluster_config.context_name\n\n        # Use Configuration to load configuration from a dictionary\n\n        await config.load_kube_config_from_dict(\n            config_dict=config_dict,\n            context=context,\n            client_configuration=client_configuration,\n        )\n    async with ApiClient(configuration=client_configuration) as api_client:\n        try:\n            yield await self.get_resource_specific_client(\n                client_type, api_client=api_client\n            )\n        finally:\n            await api_client.close()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/credentials/#prefect_kubernetes.credentials.KubernetesCredentials.get_resource_specific_client","title":"<code>get_resource_specific_client</code>  <code>async</code>","text":"<p>Utility function for configuring a generic Kubernetes client. It will attempt to connect to a Kubernetes cluster in three steps with the first successful connection attempt becoming the mode of communication with a cluster:</p> <ol> <li> <p>It will first attempt to use a <code>KubernetesCredentials</code> block's <code>cluster_config</code> to configure a client using <code>KubernetesClusterConfig.configure_client</code>.</p> </li> <li> <p>Attempt in-cluster connection (will only work when running on a pod).</p> </li> <li> <p>Attempt out-of-cluster connection using the default location for a kube config file.</p> </li> </ol> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>str</code> <p>The Kubernetes API client type for interacting with specific Kubernetes resources.</p> required <p>Returns:</p> Name Type Description <code>KubernetesClient</code> <code>Union[AppsV1Api, BatchV1Api, CoreV1Api]</code> <p>An authenticated, resource-specific Kubernetes Client.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If <code>client_type</code> is not a valid Kubernetes API client type.</p> Source code in <code>prefect_kubernetes/credentials.py</code> <pre><code>async def get_resource_specific_client(\n    self,\n    client_type: str,\n    api_client: ApiClient,\n) -&gt; Union[AppsV1Api, BatchV1Api, CoreV1Api]:\n    \"\"\"\n    Utility function for configuring a generic Kubernetes client.\n    It will attempt to connect to a Kubernetes cluster in three steps with\n    the first successful connection attempt becoming the mode of communication with\n    a cluster:\n\n    1. It will first attempt to use a `KubernetesCredentials` block's\n    `cluster_config` to configure a client using\n    `KubernetesClusterConfig.configure_client`.\n\n    2. Attempt in-cluster connection (will only work when running on a pod).\n\n    3. Attempt out-of-cluster connection using the default location for a\n    kube config file.\n\n    Args:\n        client_type: The Kubernetes API client type for interacting with specific\n            Kubernetes resources.\n\n    Returns:\n        KubernetesClient: An authenticated, resource-specific Kubernetes Client.\n\n    Raises:\n        ValueError: If `client_type` is not a valid Kubernetes API client type.\n    \"\"\"\n\n    if self.cluster_config:\n        await self.cluster_config.configure_client()\n    else:\n        try:\n            config.load_incluster_config()\n        except ConfigException:\n            await config.load_kube_config()\n\n    try:\n        return K8S_CLIENT_TYPES[client_type](api_client)\n    except KeyError:\n        raise ValueError(\n            f\"Invalid client type provided '{client_type}'.\"\n            f\" Must be one of {listrepr(K8S_CLIENT_TYPES.keys())}.\"\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/","title":"Custom Objects","text":""},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects","title":"<code>prefect_kubernetes.custom_objects</code>","text":""},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.create_namespaced_custom_object","title":"<code>create_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for creating a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create the custom object in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource created by this task.</p> Example <p>Create a custom object in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import create_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = create_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'crd-name',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def create_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    body: Dict[str, Any],\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for creating a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        body: A Dict containing the custom resource object's specification.\n        namespace: The Kubernetes namespace to create the custom object in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing the custom resource created by this task.\n\n    Example:\n        Create a custom object in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import create_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = create_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'crd-name',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.create_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.delete_namespaced_custom_object","title":"<code>delete_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for deleting a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to delete.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this custom object in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource deleted by this task.</p> Example <p>Delete \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import delete_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = delete_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def delete_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for deleting a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to delete.\n        namespace: The Kubernetes namespace to create this custom object in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n\n    Returns:\n        object containing the custom resource deleted by this task.\n\n    Example:\n        Delete \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import delete_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = delete_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.delete_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.get_namespaced_custom_object","title":"<code>get_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for reading a namespaced Kubernetes custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace the custom resource is in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification.</p> Example <p>Read \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import get_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = get_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def get_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for reading a namespaced Kubernetes custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to read.\n        namespace: The Kubernetes namespace the custom resource is in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `name` is `None`.\n\n    Returns:\n        object containing the custom resource specification.\n\n    Example:\n        Read \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import get_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = get_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.get_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.get_namespaced_custom_object_status","title":"<code>get_namespaced_custom_object_status</code>  <code>async</code>","text":"<p>Task for fetching status of a namespaced custom object.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to read.</p> required <code>namespace</code> <code>str</code> <p>The Kubernetes namespace the custom resource is in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom-object specification with status.</p> Example <p>Fetch status of \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import (\n    get_namespaced_custom_object_status,\n)\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = get_namespaced_custom_object_status(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def get_namespaced_custom_object_status(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for fetching status of a namespaced custom object.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to read.\n        namespace: The Kubernetes namespace the custom resource is in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing the custom-object specification with status.\n\n    Example:\n        Fetch status of \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import (\n            get_namespaced_custom_object_status,\n        )\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = get_namespaced_custom_object_status(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.get_namespaced_custom_object_status(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.list_namespaced_custom_object","title":"<code>list_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for listing namespaced custom objects.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>namespace</code> <code>str</code> <p>The Kubernetes namespace to list custom resources for.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>object</code> <p>object containing a list of custom resources.</p> Example <p>List custom resources in \"my-namespace\": <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import list_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    namespaced_custom_objects_list = list_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        namespace=\"my-namespace\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def list_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for listing namespaced custom objects.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        namespace: The Kubernetes namespace to list custom resources for.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        object containing a list of custom resources.\n\n    Example:\n        List custom resources in \"my-namespace\":\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import list_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            namespaced_custom_objects_list = list_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.list_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.patch_namespaced_custom_object","title":"<code>patch_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for patching a namespaced custom resource.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to patch.</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's patch.</p> required <code>namespace</code> <code>str</code> <p>The custom resource's Kubernetes namespace.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>body</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification</p> <code>object</code> <p>after the patch gets applied.</p> Example <p>Patch \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import (\n    patch_namespaced_custom_object,\n)\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = patch_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'my-custom-object',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def patch_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    body: Dict[str, Any],\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for patching a namespaced custom resource.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to patch.\n        body: A Dict containing the custom resource object's patch.\n        namespace: The custom resource's Kubernetes namespace.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `body` is `None`.\n\n    Returns:\n        object containing the custom resource specification\n        after the patch gets applied.\n\n    Example:\n        Patch \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import (\n            patch_namespaced_custom_object,\n        )\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = patch_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'my-custom-object',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.patch_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/custom_objects/#prefect_kubernetes.custom_objects.replace_namespaced_custom_object","title":"<code>replace_namespaced_custom_object</code>  <code>async</code>","text":"<p>Task for replacing a namespaced custom resource.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>group</code> <code>str</code> <p>The custom resource object's group</p> required <code>version</code> <code>str</code> <p>The custom resource object's version</p> required <code>plural</code> <code>str</code> <p>The custom resource object's plural</p> required <code>name</code> <code>str</code> <p>The name of a custom object to replace.</p> required <code>body</code> <code>Dict[str, Any]</code> <p>A Dict containing the custom resource object's specification.</p> required <code>namespace</code> <code>str</code> <p>The custom resource's Kubernetes namespace.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>body</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>object</code> <p>object containing the custom resource specification after the replacement.</p> Example <p>Replace \"my-custom-object\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.custom_objects import replace_namespaced_custom_object\n\n@flow\ndef kubernetes_orchestrator():\n    custom_object_metadata = replace_namespaced_custom_object(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        group=\"crd-group\",\n        version=\"crd-version\",\n        plural=\"crd-plural\",\n        name=\"my-custom-object\",\n        body={\n            'api': 'crd-version',\n            'kind': 'crd-kind',\n            'metadata': {\n                'name': 'my-custom-object',\n            },\n        },\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/custom_objects.py</code> <pre><code>@task\nasync def replace_namespaced_custom_object(\n    kubernetes_credentials: KubernetesCredentials,\n    group: str,\n    version: str,\n    plural: str,\n    name: str,\n    body: Dict[str, Any],\n    namespace: str = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; object:\n    \"\"\"Task for replacing a namespaced custom resource.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        group: The custom resource object's group\n        version: The custom resource object's version\n        plural: The custom resource object's plural\n        name: The name of a custom object to replace.\n        body: A Dict containing the custom resource object's specification.\n        namespace: The custom resource's Kubernetes namespace.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `body` is `None`.\n\n    Returns:\n        object containing the custom resource specification after the replacement.\n\n    Example:\n        Replace \"my-custom-object\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.custom_objects import replace_namespaced_custom_object\n\n        @flow\n        def kubernetes_orchestrator():\n            custom_object_metadata = replace_namespaced_custom_object(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                group=\"crd-group\",\n                version=\"crd-version\",\n                plural=\"crd-plural\",\n                name=\"my-custom-object\",\n                body={\n                    'api': 'crd-version',\n                    'kind': 'crd-kind',\n                    'metadata': {\n                        'name': 'my-custom-object',\n                    },\n                },\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\n        \"custom_objects\"\n    ) as custom_objects_client:\n        return await custom_objects_client.replace_namespaced_custom_object(\n            group=group,\n            version=version,\n            plural=plural,\n            name=name,\n            body=body,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/","title":"Deployments","text":""},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments","title":"<code>prefect_kubernetes.deployments</code>","text":"<p>Module for interacting with Kubernetes deployments from Prefect flows.</p>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.create_namespaced_deployment","title":"<code>create_namespaced_deployment</code>  <code>async</code>","text":"<p>Create a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>new_deployment</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Create a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import create_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = create_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_deployment=V1Deployment(metadata={\"name\": \"test-deployment\"}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def create_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    new_deployment: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Create a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        new_deployment: A Kubernetes `V1Deployment` specification.\n        namespace: The Kubernetes namespace to create this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Create a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import create_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = create_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_deployment=V1Deployment(metadata={\"name\": \"test-deployment\"}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.create_namespaced_deployment(\n            namespace=namespace,\n            body=new_deployment,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.delete_namespaced_deployment","title":"<code>delete_namespaced_deployment</code>  <code>async</code>","text":"<p>Delete a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this deployment from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Delete a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import delete_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1DeleteOptions\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = delete_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        delete_options=V1DeleteOptions(grace_period_seconds=0),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def delete_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Delete a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this deployment from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Delete a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import delete_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = delete_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                delete_options=V1DeleteOptions(grace_period_seconds=0),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.delete_namespaced_deployment(\n            deployment_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.list_namespaced_deployment","title":"<code>list_namespaced_deployment</code>  <code>async</code>","text":"<p>List all deployments in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list deployments from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1DeploymentList</code> <p>A Kubernetes <code>V1DeploymentList</code> object.</p> Example <p>List all deployments in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import list_namespaced_deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_list = list_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def list_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1DeploymentList:\n    \"\"\"List all deployments in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The Kubernetes namespace to list deployments from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1DeploymentList` object.\n\n    Example:\n        List all deployments in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import list_namespaced_deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_list = list_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.list_namespaced_deployment(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.patch_namespaced_deployment","title":"<code>patch_namespaced_deployment</code>  <code>async</code>","text":"<p>Patch a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to patch.</p> required <code>deployment_updates</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Patch a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import patch_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = patch_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        deployment_updates=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def patch_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    deployment_updates: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Patch a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to patch.\n        deployment_updates: A Kubernetes `V1Deployment` object.\n        namespace: The Kubernetes namespace to patch this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Patch a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import patch_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = patch_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                deployment_updates=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.patch_namespaced_deployment(\n            name=deployment_name,\n            namespace=namespace,\n            body=deployment_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.read_namespaced_deployment","title":"<code>read_namespaced_deployment</code>  <code>async</code>","text":"<p>Read information on a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this deployment from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Read a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = read_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\"\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def read_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Read information on a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to read.\n        namespace: The Kubernetes namespace to read this deployment from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Read a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = read_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\"\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.read_namespaced_deployment(\n            name=deployment_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/deployments/#prefect_kubernetes.deployments.replace_namespaced_deployment","title":"<code>replace_namespaced_deployment</code>  <code>async</code>","text":"<p>Replace a Kubernetes deployment in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>deployment_name</code> <code>str</code> <p>The name of the deployment to replace.</p> required <code>new_deployment</code> <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this deployment in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Deployment</code> <p>A Kubernetes <code>V1Deployment</code> object.</p> Example <p>Replace a deployment in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.deployments import replace_namespaced_deployment\nfrom kubernetes_asyncio.client.models import V1Deployment\n\n@flow\ndef kubernetes_orchestrator():\n    v1_deployment_metadata = replace_namespaced_deployment(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        deployment_name=\"test-deployment\",\n        new_deployment=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}})\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/deployments.py</code> <pre><code>@task\nasync def replace_namespaced_deployment(\n    kubernetes_credentials: KubernetesCredentials,\n    deployment_name: str,\n    new_deployment: V1Deployment,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Deployment:\n    \"\"\"Replace a Kubernetes deployment in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        deployment_name: The name of the deployment to replace.\n        new_deployment: A Kubernetes `V1Deployment` object.\n        namespace: The Kubernetes namespace to replace this deployment in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Deployment` object.\n\n    Example:\n        Replace a deployment in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.deployments import replace_namespaced_deployment\n        from kubernetes_asyncio.client.models import V1Deployment\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_deployment_metadata = replace_namespaced_deployment(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                deployment_name=\"test-deployment\",\n                new_deployment=V1Deployment(metadata={\"labels\": {\"foo\": \"bar\"}})\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"apps\") as apps_v1_client:\n        return await apps_v1_client.replace_namespaced_deployment(\n            body=new_deployment,\n            name=deployment_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/","title":"Exceptions","text":""},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions","title":"<code>prefect_kubernetes.exceptions</code>","text":"<p>Module to define common exceptions within <code>prefect_kubernetes</code>.</p>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobDefinitionError","title":"<code>KubernetesJobDefinitionError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job definition is invalid.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobDefinitionError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job definition is invalid.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobFailedError","title":"<code>KubernetesJobFailedError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job fails.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobFailedError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job fails.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesJobTimeoutError","title":"<code>KubernetesJobTimeoutError</code>","text":"<p>               Bases: <code>OpenApiException</code></p> <p>An exception for when a Kubernetes job times out.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesJobTimeoutError(OpenApiException):\n    \"\"\"An exception for when a Kubernetes job times out.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/exceptions/#prefect_kubernetes.exceptions.KubernetesResourceNotFoundError","title":"<code>KubernetesResourceNotFoundError</code>","text":"<p>               Bases: <code>ApiException</code></p> <p>An exception for when a Kubernetes resource cannot be found by a client.</p> Source code in <code>prefect_kubernetes/exceptions.py</code> <pre><code>class KubernetesResourceNotFoundError(ApiException):\n    \"\"\"An exception for when a Kubernetes resource cannot be found by a client.\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/flows/","title":"Flows","text":""},{"location":"integrations/prefect-kubernetes/flows/#prefect_kubernetes.flows","title":"<code>prefect_kubernetes.flows</code>","text":"<p>A module to define flows interacting with Kubernetes resources.</p>"},{"location":"integrations/prefect-kubernetes/flows/#prefect_kubernetes.flows.run_namespaced_job","title":"<code>run_namespaced_job</code>  <code>async</code>","text":"<p>Flow for running a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_job</code> <code>KubernetesJob</code> <p>The <code>KubernetesJob</code> block that specifies the job to run.</p> required <code>print_func</code> <code>Optional[Callable]</code> <p>A function to print the logs from the job pods.</p> <code>None</code> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>A dict of logs from each pod in the job, e.g. {'pod_name': 'pod_log_str'}.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the created Kubernetes job attains a failed status.</p> <pre><code>```python\nfrom prefect_kubernetes import KubernetesJob, run_namespaced_job\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\nrun_namespaced_job(\n    kubernetes_job=KubernetesJob.from_yaml_file(\n        credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        manifest_path=\"path/to/job.yaml\",\n    )\n)\n```\n</code></pre> Source code in <code>prefect_kubernetes/flows.py</code> <pre><code>@flow\nasync def run_namespaced_job(\n    kubernetes_job: KubernetesJob, print_func: Optional[Callable] = None\n) -&gt; Dict[str, Any]:\n    \"\"\"Flow for running a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_job: The `KubernetesJob` block that specifies the job to run.\n        print_func: A function to print the logs from the job pods.\n\n    Returns:\n        A dict of logs from each pod in the job, e.g. {'pod_name': 'pod_log_str'}.\n\n    Raises:\n        RuntimeError: If the created Kubernetes job attains a failed status.\n\n    Example:\n\n        ```python\n        from prefect_kubernetes import KubernetesJob, run_namespaced_job\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        run_namespaced_job(\n            kubernetes_job=KubernetesJob.from_yaml_file(\n                credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                manifest_path=\"path/to/job.yaml\",\n            )\n        )\n        ```\n    \"\"\"\n    kubernetes_job_run = task(kubernetes_job.trigger)()\n\n    await task(kubernetes_job_run.wait_for_completion.aio)(\n        kubernetes_job_run, print_func\n    )\n\n    return task(kubernetes_job_run.fetch_result)()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/","title":"Jobs","text":""},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs","title":"<code>prefect_kubernetes.jobs</code>","text":"<p>Module to define tasks for interacting with Kubernetes jobs.</p>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob","title":"<code>KubernetesJob</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>A block representing a Kubernetes job configuration.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>class KubernetesJob(JobBlock):\n    \"\"\"A block representing a Kubernetes job configuration.\"\"\"\n\n    v1_job: Dict[str, Any] = Field(\n        default=...,\n        title=\"Job Manifest\",\n        description=(\n            \"The Kubernetes job manifest to run. This dictionary can be produced \"\n            \"using `yaml.safe_load`.\"\n        ),\n    )\n    api_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        title=\"Additional API Arguments\",\n        description=\"Additional arguments to include in Kubernetes API calls.\",\n        examples=[{\"pretty\": \"true\"}],\n    )\n    credentials: KubernetesCredentials = Field(\n        default=..., description=\"The credentials to configure a client from.\"\n    )\n    delete_after_completion: bool = Field(\n        default=True,\n        description=\"Whether to delete the job after it has completed.\",\n    )\n    interval_seconds: int = Field(\n        default=5,\n        description=\"The number of seconds to wait between job status checks.\",\n    )\n    namespace: str = Field(\n        default=\"default\",\n        description=\"The namespace to create and run the job in.\",\n    )\n    timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=\"The number of seconds to wait for the job run before timing out.\",\n    )\n\n    _block_type_name = \"Kubernetes Job\"\n    _block_type_slug = \"k8s-job\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob\"  # noqa\n\n    @sync_compatible\n    async def trigger(self):\n        \"\"\"Create a Kubernetes job and return a `KubernetesJobRun` object.\"\"\"\n\n        await create_namespaced_job.fn(\n            kubernetes_credentials=self.credentials,\n            new_job=self.v1_job,\n            namespace=self.namespace,\n            **self.api_kwargs,\n        )\n\n        return KubernetesJobRun(kubernetes_job=self, v1_job_model=self.v1_job)\n\n    @classmethod\n    def from_yaml_file(\n        cls: Type[Self], manifest_path: Union[Path, str], **kwargs\n    ) -&gt; Self:\n        \"\"\"Create a `KubernetesJob` from a YAML file.\n\n        Args:\n            manifest_path: The YAML file to create the `KubernetesJob` from.\n\n        Returns:\n            A KubernetesJob object.\n        \"\"\"\n        with open(manifest_path, \"r\") as yaml_stream:\n            yaml_dict = yaml.safe_load(yaml_stream)\n\n        return cls(v1_job=yaml_dict, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob.from_yaml_file","title":"<code>from_yaml_file</code>  <code>classmethod</code>","text":"<p>Create a <code>KubernetesJob</code> from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>manifest_path</code> <code>Union[Path, str]</code> <p>The YAML file to create the <code>KubernetesJob</code> from.</p> required <p>Returns:</p> Type Description <code>Self</code> <p>A KubernetesJob object.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@classmethod\ndef from_yaml_file(\n    cls: Type[Self], manifest_path: Union[Path, str], **kwargs\n) -&gt; Self:\n    \"\"\"Create a `KubernetesJob` from a YAML file.\n\n    Args:\n        manifest_path: The YAML file to create the `KubernetesJob` from.\n\n    Returns:\n        A KubernetesJob object.\n    \"\"\"\n    with open(manifest_path, \"r\") as yaml_stream:\n        yaml_dict = yaml.safe_load(yaml_stream)\n\n    return cls(v1_job=yaml_dict, **kwargs)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJob.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Create a Kubernetes job and return a <code>KubernetesJobRun</code> object.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def trigger(self):\n    \"\"\"Create a Kubernetes job and return a `KubernetesJobRun` object.\"\"\"\n\n    await create_namespaced_job.fn(\n        kubernetes_credentials=self.credentials,\n        new_job=self.v1_job,\n        namespace=self.namespace,\n        **self.api_kwargs,\n    )\n\n    return KubernetesJobRun(kubernetes_job=self, v1_job_model=self.v1_job)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun","title":"<code>KubernetesJobRun</code>","text":"<p>               Bases: <code>JobRun[Dict[str, Any]]</code></p> <p>A container representing a run of a Kubernetes job.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@deprecated_class(\n    start_date=\"Jun 2024\", help=\"Will be removed in Prefect 3. Use Workers instead.\"\n)\nclass KubernetesJobRun(JobRun[Dict[str, Any]]):\n    \"\"\"A container representing a run of a Kubernetes job.\"\"\"\n\n    def __init__(\n        self,\n        kubernetes_job: \"KubernetesJob\",\n        v1_job_model: Union[V1Job, Dict[str, Any]],\n    ):\n        self.pod_logs = None\n\n        self._completed = False\n        self._kubernetes_job = kubernetes_job\n        self._v1_job_model = v1_job_model\n\n    async def _cleanup(self):\n        \"\"\"Deletes the Kubernetes job resource.\"\"\"\n        job_name = self._v1_job_model.get(\"metadata\", {}).get(\"name\")\n\n        delete_options = V1DeleteOptions(propagation_policy=\"Foreground\")\n\n        deleted_v1_job = await delete_namespaced_job.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            job_name=job_name,\n            delete_options=delete_options,\n            namespace=self._kubernetes_job.namespace,\n            **self._kubernetes_job.api_kwargs,\n        )\n        self.logger.info(f\"Job {job_name} deleted \" f\"with {deleted_v1_job.status!r}.\")\n\n    @sync_compatible\n    async def wait_for_completion(self, print_func: Optional[Callable] = None):\n        \"\"\"Waits for the job to complete.\n\n        If the job has `delete_after_completion` set to `True`,\n        the job will be deleted if it is observed by this method\n        to enter a completed state.\n\n        Raises:\n            RuntimeError: If the Kubernetes job fails.\n            KubernetesJobTimeoutError: If the Kubernetes job times out.\n            ValueError: If `wait_for_completion` is never called.\n        \"\"\"\n        self.pod_logs = {}\n\n        elapsed_time = 0\n\n        while not self._completed:\n            job_expired = (\n                elapsed_time &gt; self._kubernetes_job.timeout_seconds\n                if self._kubernetes_job.timeout_seconds\n                else False\n            )\n            if job_expired:\n                raise KubernetesJobTimeoutError(\n                    f\"Job timed out after {elapsed_time} seconds.\"\n                )\n\n            v1_job_status = await read_namespaced_job_status.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                job_name=self._v1_job_model.get(\"metadata\", {}).get(\"name\"),\n                namespace=self._kubernetes_job.namespace,\n                **self._kubernetes_job.api_kwargs,\n            )\n            pod_selector = (\n                \"controller-uid=\" f\"{v1_job_status.metadata.labels['controller-uid']}\"\n            )\n            v1_pod_list = await list_namespaced_pod.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                namespace=self._kubernetes_job.namespace,\n                label_selector=pod_selector,\n                **self._kubernetes_job.api_kwargs,\n            )\n\n            for pod in v1_pod_list.items:\n                pod_name = pod.metadata.name\n\n                if pod.status.phase == \"Pending\" or pod_name in self.pod_logs.keys():\n                    continue\n\n                self.logger.info(f\"Capturing logs for pod {pod_name!r}.\")\n\n                self.pod_logs[pod_name] = await read_namespaced_pod_log.fn(\n                    kubernetes_credentials=self._kubernetes_job.credentials,\n                    pod_name=pod_name,\n                    container=v1_job_status.spec.template.spec.containers[0].name,\n                    namespace=self._kubernetes_job.namespace,\n                    print_func=print_func,\n                    **self._kubernetes_job.api_kwargs,\n                )\n\n            if v1_job_status.status.active:\n                await sleep(self._kubernetes_job.interval_seconds)\n                if self._kubernetes_job.timeout_seconds:\n                    elapsed_time += self._kubernetes_job.interval_seconds\n            elif v1_job_status.status.conditions:\n                final_completed_conditions = [\n                    condition.type == \"Complete\"\n                    for condition in v1_job_status.status.conditions\n                    if condition.status == \"True\"\n                ]\n                if final_completed_conditions and any(final_completed_conditions):\n                    self._completed = True\n                    self.logger.info(\n                        f\"Job {v1_job_status.metadata.name!r} has \"\n                        f\"completed with {v1_job_status.status.succeeded} pods.\"\n                    )\n                elif final_completed_conditions:\n                    failed_conditions = [\n                        condition.reason\n                        for condition in v1_job_status.status.conditions\n                        if condition.type == \"Failed\"\n                    ]\n                    raise RuntimeError(\n                        f\"Job {v1_job_status.metadata.name!r} failed due to \"\n                        f\"{failed_conditions}, check the Kubernetes pod logs \"\n                        f\"for more information.\"\n                    )\n\n        if self._kubernetes_job.delete_after_completion:\n            await self._cleanup()\n\n    @sync_compatible\n    async def fetch_result(self) -&gt; Dict[str, Any]:\n        \"\"\"Fetch the results of the job.\n\n        Returns:\n            The logs from each of the pods in the job.\n\n        Raises:\n            ValueError: If this method is called when the job has\n                a non-terminal state.\n        \"\"\"\n\n        if not self._completed:\n            raise ValueError(\n                \"The Kubernetes Job run is not in a completed state - \"\n                \"be sure to call `wait_for_completion` before attempting \"\n                \"to fetch the result.\"\n            )\n        return self.pod_logs\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Fetch the results of the job.</p> <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>The logs from each of the pods in the job.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If this method is called when the job has a non-terminal state.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self) -&gt; Dict[str, Any]:\n    \"\"\"Fetch the results of the job.\n\n    Returns:\n        The logs from each of the pods in the job.\n\n    Raises:\n        ValueError: If this method is called when the job has\n            a non-terminal state.\n    \"\"\"\n\n    if not self._completed:\n        raise ValueError(\n            \"The Kubernetes Job run is not in a completed state - \"\n            \"be sure to call `wait_for_completion` before attempting \"\n            \"to fetch the result.\"\n        )\n    return self.pod_logs\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.KubernetesJobRun.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Waits for the job to complete.</p> <p>If the job has <code>delete_after_completion</code> set to <code>True</code>, the job will be deleted if it is observed by this method to enter a completed state.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the Kubernetes job fails.</p> <code>KubernetesJobTimeoutError</code> <p>If the Kubernetes job times out.</p> <code>ValueError</code> <p>If <code>wait_for_completion</code> is never called.</p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self, print_func: Optional[Callable] = None):\n    \"\"\"Waits for the job to complete.\n\n    If the job has `delete_after_completion` set to `True`,\n    the job will be deleted if it is observed by this method\n    to enter a completed state.\n\n    Raises:\n        RuntimeError: If the Kubernetes job fails.\n        KubernetesJobTimeoutError: If the Kubernetes job times out.\n        ValueError: If `wait_for_completion` is never called.\n    \"\"\"\n    self.pod_logs = {}\n\n    elapsed_time = 0\n\n    while not self._completed:\n        job_expired = (\n            elapsed_time &gt; self._kubernetes_job.timeout_seconds\n            if self._kubernetes_job.timeout_seconds\n            else False\n        )\n        if job_expired:\n            raise KubernetesJobTimeoutError(\n                f\"Job timed out after {elapsed_time} seconds.\"\n            )\n\n        v1_job_status = await read_namespaced_job_status.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            job_name=self._v1_job_model.get(\"metadata\", {}).get(\"name\"),\n            namespace=self._kubernetes_job.namespace,\n            **self._kubernetes_job.api_kwargs,\n        )\n        pod_selector = (\n            \"controller-uid=\" f\"{v1_job_status.metadata.labels['controller-uid']}\"\n        )\n        v1_pod_list = await list_namespaced_pod.fn(\n            kubernetes_credentials=self._kubernetes_job.credentials,\n            namespace=self._kubernetes_job.namespace,\n            label_selector=pod_selector,\n            **self._kubernetes_job.api_kwargs,\n        )\n\n        for pod in v1_pod_list.items:\n            pod_name = pod.metadata.name\n\n            if pod.status.phase == \"Pending\" or pod_name in self.pod_logs.keys():\n                continue\n\n            self.logger.info(f\"Capturing logs for pod {pod_name!r}.\")\n\n            self.pod_logs[pod_name] = await read_namespaced_pod_log.fn(\n                kubernetes_credentials=self._kubernetes_job.credentials,\n                pod_name=pod_name,\n                container=v1_job_status.spec.template.spec.containers[0].name,\n                namespace=self._kubernetes_job.namespace,\n                print_func=print_func,\n                **self._kubernetes_job.api_kwargs,\n            )\n\n        if v1_job_status.status.active:\n            await sleep(self._kubernetes_job.interval_seconds)\n            if self._kubernetes_job.timeout_seconds:\n                elapsed_time += self._kubernetes_job.interval_seconds\n        elif v1_job_status.status.conditions:\n            final_completed_conditions = [\n                condition.type == \"Complete\"\n                for condition in v1_job_status.status.conditions\n                if condition.status == \"True\"\n            ]\n            if final_completed_conditions and any(final_completed_conditions):\n                self._completed = True\n                self.logger.info(\n                    f\"Job {v1_job_status.metadata.name!r} has \"\n                    f\"completed with {v1_job_status.status.succeeded} pods.\"\n                )\n            elif final_completed_conditions:\n                failed_conditions = [\n                    condition.reason\n                    for condition in v1_job_status.status.conditions\n                    if condition.type == \"Failed\"\n                ]\n                raise RuntimeError(\n                    f\"Job {v1_job_status.metadata.name!r} failed due to \"\n                    f\"{failed_conditions}, check the Kubernetes pod logs \"\n                    f\"for more information.\"\n                )\n\n    if self._kubernetes_job.delete_after_completion:\n        await self._cleanup()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.create_namespaced_job","title":"<code>create_namespaced_job</code>  <code>async</code>","text":"<p>Task for creating a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>new_job</code> <code>Union[V1Job, Dict[str, Any]]</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Create a job in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import create_namespaced_job\nfrom kubernetes_asyncio.client.models import V1Job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = create_namespaced_job(\n        new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def create_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    new_job: Union[V1Job, Dict[str, Any]],\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for creating a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        new_job: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to create this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Create a job in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import create_namespaced_job\n        from kubernetes_asyncio.client.models import V1Job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = create_namespaced_job(\n                new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.create_namespaced_job(\n            namespace=namespace,\n            body=new_job,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.delete_namespaced_job","title":"<code>delete_namespaced_job</code>  <code>async</code>","text":"<p>Task for deleting a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Status</code> <p>A Kubernetes <code>V1Status</code> object.</p> Example <p>Delete \"my-job\" in the default namespace: <pre><code>from kubernetes_asyncio.client.models import V1DeleteOptions\nfrom prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import delete_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_status = delete_namespaced_job(\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        delete_options=V1DeleteOptions(propagation_policy=\"Foreground\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def delete_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Status:\n    \"\"\"Task for deleting a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n\n    Returns:\n        A Kubernetes `V1Status` object.\n\n    Example:\n        Delete \"my-job\" in the default namespace:\n        ```python\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import delete_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_status = delete_namespaced_job(\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                delete_options=V1DeleteOptions(propagation_policy=\"Foreground\"),\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.delete_namespaced_job(\n            name=job_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.list_namespaced_job","title":"<code>list_namespaced_job</code>  <code>async</code>","text":"<p>Task for listing namespaced Kubernetes jobs.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list jobs from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1JobList</code> <p>A Kubernetes <code>V1JobList</code> object.</p> Example <p>List jobs in \"my-namespace\": <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import list_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    namespaced_job_list = list_namespaced_job(\n        namespace=\"my-namespace\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def list_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1JobList:\n    \"\"\"Task for listing namespaced Kubernetes jobs.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        namespace: The Kubernetes namespace to list jobs from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1JobList` object.\n\n    Example:\n        List jobs in \"my-namespace\":\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import list_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            namespaced_job_list = list_namespaced_job(\n                namespace=\"my-namespace\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.list_namespaced_job(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.patch_namespaced_job","title":"<code>patch_namespaced_job</code>  <code>async</code>","text":"<p>Task for patching a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>KubernetesCredentials block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to patch.</p> required <code>job_updates</code> <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>job_name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Patch \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import patch_namespaced_job\n\nfrom kubernetes_asyncio.client.models import V1Job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = patch_namespaced_job(\n        job_name=\"my-job\",\n        job_updates=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}}),\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def patch_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    job_updates: V1Job,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for patching a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: KubernetesCredentials block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to patch.\n        job_updates: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to patch this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `job_name` is `None`.\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Patch \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import patch_namespaced_job\n\n        from kubernetes_asyncio.client.models import V1Job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = patch_namespaced_job(\n                job_name=\"my-job\",\n                job_updates=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}}),\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.patch_namespaced_job(\n            name=job_name,\n            namespace=namespace,\n            body=job_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.read_namespaced_job","title":"<code>read_namespaced_job</code>  <code>async</code>","text":"<p>Task for reading a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>if <code>job_name</code> is <code>None</code>.</p> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Read \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import read_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = read_namespaced_job(\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def read_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for reading a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to read.\n        namespace: The Kubernetes namespace to read this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Raises:\n        ValueError: if `job_name` is `None`.\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Read \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import read_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = read_namespaced_job(\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.read_namespaced_job(\n            name=job_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.read_namespaced_job_status","title":"<code>read_namespaced_job_status</code>  <code>async</code>","text":"<p>Task for fetching status of a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to fetch status for.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to fetch status of job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1JobStatus</code> object.</p> Example <p>Fetch status of a job in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import read_namespaced_job_status\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_status = read_namespaced_job_status(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        job_name=\"my-job\",\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def read_namespaced_job_status(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for fetching status of a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to fetch status for.\n        namespace: The Kubernetes namespace to fetch status of job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1JobStatus` object.\n\n    Example:\n        Fetch status of a job in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import read_namespaced_job_status\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_status = read_namespaced_job_status(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                job_name=\"my-job\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.read_namespaced_job_status(\n            name=job_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/jobs/#prefect_kubernetes.jobs.replace_namespaced_job","title":"<code>replace_namespaced_job</code>  <code>async</code>","text":"<p>Task for replacing a namespaced Kubernetes job.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block holding authentication needed to generate the required API client.</p> required <code>job_name</code> <code>str</code> <p>The name of a job to replace.</p> required <code>new_job</code> <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this job in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API (e.g. <code>{\"pretty\": \"...\", \"dry_run\": \"...\"}</code>).</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Job</code> <p>A Kubernetes <code>V1Job</code> object.</p> Example <p>Replace \"my-job\" in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.jobs import replace_namespaced_job\n\n@flow\ndef kubernetes_orchestrator():\n    v1_job_metadata = replace_namespaced_job(\n        new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n        job_name=\"my-job\",\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/jobs.py</code> <pre><code>@task\nasync def replace_namespaced_job(\n    kubernetes_credentials: KubernetesCredentials,\n    job_name: str,\n    new_job: V1Job,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Job:\n    \"\"\"Task for replacing a namespaced Kubernetes job.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block\n            holding authentication needed to generate the required API client.\n        job_name: The name of a job to replace.\n        new_job: A Kubernetes `V1Job` specification.\n        namespace: The Kubernetes namespace to replace this job in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the\n            Kubernetes API (e.g. `{\"pretty\": \"...\", \"dry_run\": \"...\"}`).\n\n    Returns:\n        A Kubernetes `V1Job` object.\n\n    Example:\n        Replace \"my-job\" in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.jobs import replace_namespaced_job\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_job_metadata = replace_namespaced_job(\n                new_job=V1Job(metadata={\"labels\": {\"foo\": \"bar\"}}),\n                job_name=\"my-job\",\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"batch\") as batch_v1_client:\n        return await batch_v1_client.replace_namespaced_job(\n            name=job_name,\n            body=new_job,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/","title":"Pods","text":""},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods","title":"<code>prefect_kubernetes.pods</code>","text":"<p>Module for interacting with Kubernetes pods from Prefect flows.</p>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.create_namespaced_pod","title":"<code>create_namespaced_pod</code>  <code>async</code>","text":"<p>Create a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>new_pod</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> specification.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to create this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Create a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import create_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = create_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_pod=V1Pod(metadata={\"name\": \"test-pod\"}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def create_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    new_pod: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Create a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        new_pod: A Kubernetes `V1Pod` specification.\n        namespace: The Kubernetes namespace to create this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Create a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import create_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = create_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_pod=V1Pod(metadata={\"name\": \"test-pod\"}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.create_namespaced_pod(\n            namespace=namespace,\n            body=new_pod,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.delete_namespaced_pod","title":"<code>delete_namespaced_pod</code>  <code>async</code>","text":"<p>Delete a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A Kubernetes <code>V1DeleteOptions</code> object.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to delete this pod from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Delete a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import delete_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1DeleteOptions\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = delete_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        delete_options=V1DeleteOptions(grace_period_seconds=0),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def delete_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Delete a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to delete.\n        delete_options: A Kubernetes `V1DeleteOptions` object.\n        namespace: The Kubernetes namespace to delete this pod from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Delete a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import delete_namespaced_pod\n        from kubernetes_asyncio.client.models import V1DeleteOptions\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = delete_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                delete_options=V1DeleteOptions(grace_period_seconds=0),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.delete_namespaced_pod(\n            pod_name,\n            body=delete_options,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.list_namespaced_pod","title":"<code>list_namespaced_pod</code>  <code>async</code>","text":"<p>List all pods in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to list pods from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1PodList</code> <p>A Kubernetes <code>V1PodList</code> object.</p> Example <p>List all pods in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import list_namespaced_pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_list = list_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def list_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1PodList:\n    \"\"\"List all pods in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The Kubernetes namespace to list pods from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1PodList` object.\n\n    Example:\n        List all pods in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import list_namespaced_pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_list = list_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\")\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.list_namespaced_pod(\n            namespace=namespace, **kube_kwargs\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.patch_namespaced_pod","title":"<code>patch_namespaced_pod</code>  <code>async</code>","text":"<p>Patch a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to patch.</p> required <code>pod_updates</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to patch this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Patch a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import patch_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = patch_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        pod_updates=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}}),\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def patch_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    pod_updates: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Patch a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to patch.\n        pod_updates: A Kubernetes `V1Pod` object.\n        namespace: The Kubernetes namespace to patch this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Patch a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import patch_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = patch_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                pod_updates=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.patch_namespaced_pod(\n            name=pod_name,\n            namespace=namespace,\n            body=pod_updates,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.read_namespaced_pod","title":"<code>read_namespaced_pod</code>  <code>async</code>","text":"<p>Read information on a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this pod from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Read a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = read_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\"\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def read_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Read information on a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to read.\n        namespace: The Kubernetes namespace to read this pod from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Read a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = read_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\"\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.read_namespaced_pod(\n            name=pod_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.read_namespaced_pod_log","title":"<code>read_namespaced_pod_log</code>  <code>async</code>","text":"<p>Read logs from a Kubernetes pod in a given namespace.</p> <p>If <code>print_func</code> is provided, the logs will be streamed using that function. If the pod is no longer running, logs generated up to that point will be returned.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to read logs from.</p> required <code>container</code> <code>str</code> <p>The name of the container to read logs from.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to read this pod from.</p> <code>'default'</code> <code>print_func</code> <code>Optional[Callable]</code> <p>If provided, it will stream the pod logs by calling <code>print_func</code> for every line and returning <code>None</code>. If not provided, the current pod logs will be returned immediately.</p> <code>None</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[str, None]</code> <p>A string containing the logs from the pod's container.</p> Example <p>Read logs from a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect.logging import get_run_logger\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import read_namespaced_pod_logs\n\n@flow\ndef kubernetes_orchestrator():\n    logger = get_run_logger()\n\n    pod_logs = read_namespaced_pod_logs(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        container=\"test-container\",\n        print_func=logger.info\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def read_namespaced_pod_log(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    container: str,\n    namespace: Optional[str] = \"default\",\n    print_func: Optional[Callable] = None,\n    **kube_kwargs: Dict[str, Any],\n) -&gt; Union[str, None]:\n    \"\"\"Read logs from a Kubernetes pod in a given namespace.\n\n    If `print_func` is provided, the logs will be streamed using that function.\n    If the pod is no longer running, logs generated up to that point will be returned.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to read logs from.\n        container: The name of the container to read logs from.\n        namespace: The Kubernetes namespace to read this pod from.\n        print_func: If provided, it will stream the pod logs by calling `print_func`\n            for every line and returning `None`. If not provided, the current pod\n            logs will be returned immediately.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A string containing the logs from the pod's container.\n\n    Example:\n        Read logs from a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect.logging import get_run_logger\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import read_namespaced_pod_logs\n\n        @flow\n        def kubernetes_orchestrator():\n            logger = get_run_logger()\n\n            pod_logs = read_namespaced_pod_logs(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                container=\"test-container\",\n                print_func=logger.info\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        if print_func is not None:\n            # should no longer need to manually refresh on ApiException.status == 410\n            # as of https://github.com/kubernetes-client/python-base/pull/133\n            async with Watch() as watch:\n                async for log_line in watch.stream(\n                    core_v1_client.read_namespaced_pod_log,\n                    name=pod_name,\n                    namespace=namespace,\n                    container=container,\n                ):\n                    print_func(log_line)\n\n        return await core_v1_client.read_namespaced_pod_log(\n            name=pod_name,\n            namespace=namespace,\n            container=container,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/pods/#prefect_kubernetes.pods.replace_namespaced_pod","title":"<code>replace_namespaced_pod</code>  <code>async</code>","text":"<p>Replace a Kubernetes pod in a given namespace.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>pod_name</code> <code>str</code> <p>The name of the pod to replace.</p> required <code>new_pod</code> <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The Kubernetes namespace to replace this pod in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Dict[str, Any]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Pod</code> <p>A Kubernetes <code>V1Pod</code> object.</p> Example <p>Replace a pod in the default namespace: <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.pods import replace_namespaced_pod\nfrom kubernetes_asyncio.client.models import V1Pod\n\n@flow\ndef kubernetes_orchestrator():\n    v1_pod_metadata = replace_namespaced_pod(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        pod_name=\"test-pod\",\n        new_pod=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}})\n    )\n</code></pre></p> Source code in <code>prefect_kubernetes/pods.py</code> <pre><code>@task\nasync def replace_namespaced_pod(\n    kubernetes_credentials: KubernetesCredentials,\n    pod_name: str,\n    new_pod: V1Pod,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Dict[str, Any],\n) -&gt; V1Pod:\n    \"\"\"Replace a Kubernetes pod in a given namespace.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        pod_name: The name of the pod to replace.\n        new_pod: A Kubernetes `V1Pod` object.\n        namespace: The Kubernetes namespace to replace this pod in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A Kubernetes `V1Pod` object.\n\n    Example:\n        Replace a pod in the default namespace:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.pods import replace_namespaced_pod\n        from kubernetes_asyncio.client.models import V1Pod\n\n        @flow\n        def kubernetes_orchestrator():\n            v1_pod_metadata = replace_namespaced_pod(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                pod_name=\"test-pod\",\n                new_pod=V1Pod(metadata={\"labels\": {\"foo\": \"bar\"}})\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.replace_namespaced_pod(\n            body=new_pod,\n            name=pod_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/","title":"Services","text":""},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services","title":"<code>prefect_kubernetes.services</code>","text":"<p>Tasks for working with Kubernetes services.</p>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.create_namespaced_service","title":"<code>create_namespaced_service</code>  <code>async</code>","text":"<p>Create a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p>A <code>KubernetesCredentials</code> block used to generate a <code>CoreV1Api</code> client.</p> required <code>new_service</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing the service to create.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to create the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Additional keyword arguments to pass to the <code>CoreV1Api</code> method call.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the created service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import create_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef create_service_flow():\n    v1_service = create_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        new_service=V1Service(metadata={...}, spec={...}),\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def create_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    new_service: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Create a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: A `KubernetesCredentials` block used to generate a\n            `CoreV1Api` client.\n        new_service: A `V1Service` object representing the service to create.\n        namespace: The namespace to create the service in.\n        **kube_kwargs: Additional keyword arguments to pass to the `CoreV1Api`\n            method call.\n\n    Returns:\n        A `V1Service` representing the created service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import create_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def create_service_flow():\n            v1_service = create_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                new_service=V1Service(metadata={...}, spec={...}),\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.create_namespaced_service(\n            body=new_service,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.delete_namespaced_service","title":"<code>delete_namespaced_service</code>  <code>async</code>","text":"<p>Delete a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to delete.</p> required <code>delete_options</code> <code>Optional[V1DeleteOptions]</code> <p>A <code>V1DeleteOptions</code> object representing the options to delete the service with.</p> <code>None</code> <code>namespace</code> <code>Optional[str]</code> <p>The namespace to delete the service from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the deleted service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import delete_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    delete_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def delete_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    delete_options: Optional[V1DeleteOptions] = None,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Delete a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to delete.\n        delete_options: A `V1DeleteOptions` object representing the options to\n            delete the service with.\n        namespace: The namespace to delete the service from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the deleted service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import delete_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            delete_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.delete_namespaced_service(\n            name=service_name,\n            namespace=namespace,\n            body=delete_options,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.list_namespaced_service","title":"<code>list_namespaced_service</code>  <code>async</code>","text":"<p>List namespaced Kubernetes services.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to list services from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1ServiceList</code> <p>A <code>V1ServiceList</code> representing the list of services in the given namespace.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import list_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    list_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def list_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1ServiceList:\n    \"\"\"List namespaced Kubernetes services.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        namespace: The namespace to list services from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1ServiceList` representing the list of services in the given namespace.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import list_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            list_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.list_namespaced_service(\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.patch_namespaced_service","title":"<code>patch_namespaced_service</code>  <code>async</code>","text":"<p>Patch a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to patch.</p> required <code>service_updates</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing patches to <code>service_name</code>.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to patch the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the patched service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import patch_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef kubernetes_orchestrator():\n    patch_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        new_service=V1Service(metadata={...}, spec={...}),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def patch_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    service_updates: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Patch a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to patch.\n        service_updates: A `V1Service` object representing patches to `service_name`.\n        namespace: The namespace to patch the service in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the patched service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import patch_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def kubernetes_orchestrator():\n            patch_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                new_service=V1Service(metadata={...}, spec={...}),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.patch_namespaced_service(\n            name=service_name,\n            body=service_updates,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.read_namespaced_service","title":"<code>read_namespaced_service</code>  <code>async</code>","text":"<p>Read a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to read.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to read the service from.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> object representing the service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import read_namespaced_service\n\n@flow\ndef kubernetes_orchestrator():\n    read_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def read_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Read a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to read.\n        namespace: The namespace to read the service from.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` object representing the service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import read_namespaced_service\n\n        @flow\n        def kubernetes_orchestrator():\n            read_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.read_namespaced_service(\n            name=service_name,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/services/#prefect_kubernetes.services.replace_namespaced_service","title":"<code>replace_namespaced_service</code>  <code>async</code>","text":"<p>Replace a namespaced Kubernetes service.</p> <p>Parameters:</p> Name Type Description Default <code>kubernetes_credentials</code> <code>KubernetesCredentials</code> <p><code>KubernetesCredentials</code> block for creating authenticated Kubernetes API clients.</p> required <code>service_name</code> <code>str</code> <p>The name of the service to replace.</p> required <code>new_service</code> <code>V1Service</code> <p>A <code>V1Service</code> object representing the new service.</p> required <code>namespace</code> <code>Optional[str]</code> <p>The namespace to replace the service in.</p> <code>'default'</code> <code>**kube_kwargs</code> <code>Optional[Dict[str, Any]]</code> <p>Optional extra keyword arguments to pass to the Kubernetes API.</p> <code>{}</code> <p>Returns:</p> Type Description <code>V1Service</code> <p>A <code>V1Service</code> representing the new service.</p> Example <pre><code>from prefect import flow\nfrom prefect_kubernetes.credentials import KubernetesCredentials\nfrom prefect_kubernetes.services import replace_namespaced_service\nfrom kubernetes_asyncio.client.models import V1Service\n\n@flow\ndef kubernetes_orchestrator():\n    replace_namespaced_service(\n        kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n        service_name=\"my-service\",\n        new_service=V1Service(metadata={...}, spec={...}),\n        namespace=\"my-namespace\",\n    )\n</code></pre> Source code in <code>prefect_kubernetes/services.py</code> <pre><code>@task\nasync def replace_namespaced_service(\n    kubernetes_credentials: KubernetesCredentials,\n    service_name: str,\n    new_service: V1Service,\n    namespace: Optional[str] = \"default\",\n    **kube_kwargs: Optional[Dict[str, Any]],\n) -&gt; V1Service:\n    \"\"\"Replace a namespaced Kubernetes service.\n\n    Args:\n        kubernetes_credentials: `KubernetesCredentials` block for creating\n            authenticated Kubernetes API clients.\n        service_name: The name of the service to replace.\n        new_service: A `V1Service` object representing the new service.\n        namespace: The namespace to replace the service in.\n        **kube_kwargs: Optional extra keyword arguments to pass to the Kubernetes API.\n\n    Returns:\n        A `V1Service` representing the new service.\n\n    Example:\n        ```python\n        from prefect import flow\n        from prefect_kubernetes.credentials import KubernetesCredentials\n        from prefect_kubernetes.services import replace_namespaced_service\n        from kubernetes_asyncio.client.models import V1Service\n\n        @flow\n        def kubernetes_orchestrator():\n            replace_namespaced_service(\n                kubernetes_credentials=KubernetesCredentials.load(\"k8s-creds\"),\n                service_name=\"my-service\",\n                new_service=V1Service(metadata={...}, spec={...}),\n                namespace=\"my-namespace\",\n            )\n        ```\n    \"\"\"\n    async with kubernetes_credentials.get_client(\"core\") as core_v1_client:\n        return await core_v1_client.replace_namespaced_service(\n            name=service_name,\n            body=new_service,\n            namespace=namespace,\n            **kube_kwargs,\n        )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/utilities/","title":"Utilities","text":""},{"location":"integrations/prefect-kubernetes/utilities/#prefect_kubernetes.utilities","title":"<code>prefect_kubernetes.utilities</code>","text":"<p>Utilities for working with the Python Kubernetes API.</p>"},{"location":"integrations/prefect-kubernetes/utilities/#prefect_kubernetes.utilities.enable_socket_keep_alive","title":"<code>enable_socket_keep_alive</code>","text":"<p>Setting the keep-alive flags on the kubernetes client object. Unfortunately neither the kubernetes library nor the urllib3 library which kubernetes is using internally offer the functionality to enable keep-alive messages. Thus the flags are added to be used on the underlying sockets.</p> Source code in <code>prefect_kubernetes/utilities.py</code> <pre><code>def enable_socket_keep_alive(client: ApiClient) -&gt; None:\n    \"\"\"\n    Setting the keep-alive flags on the kubernetes client object.\n    Unfortunately neither the kubernetes library nor the urllib3 library which\n    kubernetes is using internally offer the functionality to enable keep-alive\n    messages. Thus the flags are added to be used on the underlying sockets.\n    \"\"\"\n\n    socket_options = [(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)]\n\n    if hasattr(socket, \"TCP_KEEPINTVL\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 30))\n\n    if hasattr(socket, \"TCP_KEEPCNT\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 6))\n\n    if hasattr(socket, \"TCP_KEEPIDLE\"):\n        socket_options.append((socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 6))\n\n    if sys.platform == \"darwin\":\n        # TCP_KEEP_ALIVE not available on socket module in macOS, but defined in\n        # https://github.com/apple/darwin-xnu/blob/2ff845c2e033bd0ff64b5b6aa6063a1f8f65aa32/bsd/netinet/tcp.h#L215\n        TCP_KEEP_ALIVE = 0x10\n        socket_options.append((socket.IPPROTO_TCP, TCP_KEEP_ALIVE, 30))\n\n    client.rest_client.pool_manager.connection_pool_kw[\n        \"socket_options\"\n    ] = socket_options\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/","title":"Worker","text":""},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker","title":"<code>prefect_kubernetes.worker</code>","text":"<p>Module containing the Kubernetes worker used for executing flow runs as Kubernetes jobs.</p> <p>To start a Kubernetes worker, run the following command:</p> <pre><code>prefect worker start --pool 'my-work-pool' --type kubernetes\n</code></pre> <p>Replace <code>my-work-pool</code> with the name of the work pool you want the worker to poll for flow runs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker--securing-your-prefect-cloud-api-key","title":"Securing your Prefect Cloud API key","text":"<p>If you are using Prefect Cloud and would like to pass your Prefect Cloud API key to created jobs via a Kubernetes secret, set the <code>PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET</code> environment variable before starting your worker:</p> <pre><code>export PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET=\"true\"\nprefect worker start --pool 'my-work-pool' --type kubernetes\n</code></pre> <p>Note that your work will need permission to create secrets in the same namespace(s) that Kubernetes jobs are created in to execute flow runs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker--using-a-custom-kubernetes-job-manifest-template","title":"Using a custom Kubernetes job manifest template","text":"<p>The default template used for Kubernetes job manifests looks like this: <pre><code>---\napiVersion: batch/v1\nkind: Job\nmetadata:\nlabels: \"{{ labels }}\"\nnamespace: \"{{ namespace }}\"\ngenerateName: \"{{ name }}-\"\nspec:\nttlSecondsAfterFinished: \"{{ finished_job_ttl }}\"\ntemplate:\n    spec:\n    parallelism: 1\n    completions: 1\n    restartPolicy: Never\n    serviceAccountName: \"{{ service_account_name }}\"\n    containers:\n    - name: prefect-job\n        env: \"{{ env }}\"\n        image: \"{{ image }}\"\n        imagePullPolicy: \"{{ image_pull_policy }}\"\n        args: \"{{ command }}\"\n</code></pre></p> <p>Each values enclosed in <code>{{ }}</code> is a placeholder that will be replaced with a value at runtime. The values that can be used a placeholders are defined by the <code>variables</code> schema defined in the base job template.</p> <p>The default job manifest and available variables can be customized on a work pool by work pool basis. These customizations can be made via the Prefect UI when creating or editing a work pool.</p> <p>For example, if you wanted to allow custom memory requests for a Kubernetes work pool you could update the job manifest template to look like this:</p> <pre><code>---\napiVersion: batch/v1\nkind: Job\nmetadata:\nlabels: \"{{ labels }}\"\nnamespace: \"{{ namespace }}\"\ngenerateName: \"{{ name }}-\"\nspec:\nttlSecondsAfterFinished: \"{{ finished_job_ttl }}\"\ntemplate:\n    spec:\n    parallelism: 1\n    completions: 1\n    restartPolicy: Never\n    serviceAccountName: \"{{ service_account_name }}\"\n    containers:\n    - name: prefect-job\n        env: \"{{ env }}\"\n        image: \"{{ image }}\"\n        imagePullPolicy: \"{{ image_pull_policy }}\"\n        args: \"{{ command }}\"\n        resources:\n            requests:\n                memory: \"{{ memory }}Mi\"\n            limits:\n                memory: 128Mi\n</code></pre> <p>In this new template, the <code>memory</code> placeholder allows customization of the memory allocated to Kubernetes jobs created by workers in this work pool, but the limit is hard-coded and cannot be changed by deployments.</p> <p>For more information about work pools and workers, checkout out the Prefect docs.</p>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.HashableKubernetesClusterConfig","title":"<code>HashableKubernetesClusterConfig</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A hashable version of the KubernetesClusterConfig class. Used for caching.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class HashableKubernetesClusterConfig(BaseModel, allow_mutation=False):\n    \"\"\"\n    A hashable version of the KubernetesClusterConfig class.\n    Used for caching.\n    \"\"\"\n\n    config: dict = Field(\n        default=..., description=\"The entire contents of a kubectl config file.\"\n    )\n    context_name: str = Field(\n        default=..., description=\"The name of the kubectl context to use.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesImagePullPolicy","title":"<code>KubernetesImagePullPolicy</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enum representing the image pull policy options for a Kubernetes job.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesImagePullPolicy(enum.Enum):\n    \"\"\"Enum representing the image pull policy options for a Kubernetes job.\"\"\"\n\n    IF_NOT_PRESENT = \"IfNotPresent\"\n    ALWAYS = \"Always\"\n    NEVER = \"Never\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker","title":"<code>KubernetesWorker</code>","text":"<p>               Bases: <code>BaseWorker</code></p> <p>Prefect worker that executes flow runs within Kubernetes Jobs.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorker(BaseWorker):\n    \"\"\"Prefect worker that executes flow runs within Kubernetes Jobs.\"\"\"\n\n    type: str = \"kubernetes\"\n    job_configuration = KubernetesWorkerJobConfiguration\n    job_configuration_variables = KubernetesWorkerVariables\n    _description = (\n        \"Execute flow runs within jobs scheduled on a Kubernetes cluster. Requires a \"\n        \"Kubernetes cluster.\"\n    )\n    _display_name = \"Kubernetes\"\n    _documentation_url = \"https://prefecthq.github.io/prefect-kubernetes/worker/\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/2d0b896006ad463b49c28aaac14f31e00e32cfab-250x250.png\"  # noqa\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self._created_secrets = {}\n\n    async def run(\n        self,\n        flow_run: \"FlowRun\",\n        configuration: KubernetesWorkerJobConfiguration,\n        task_status: Optional[anyio.abc.TaskStatus] = None,\n    ) -&gt; KubernetesWorkerResult:\n        \"\"\"\n        Executes a flow run within a Kubernetes Job and waits for the flow run\n        to complete.\n\n        Args:\n            flow_run: The flow run to execute\n            configuration: The configuration to use when executing the flow run.\n            task_status: The task status object for the current flow run. If provided,\n                the task will be marked as started.\n\n        Returns:\n            KubernetesWorkerResult: A result object containing information about the\n                final state of the flow run\n        \"\"\"\n        logger = self.get_flow_run_logger(flow_run)\n        async with self._get_configured_kubernetes_client(configuration) as client:\n            logger.info(\"Creating Kubernetes job...\")\n\n            job = await self._create_job(configuration, client)\n\n            pid = await self._get_infrastructure_pid(job, client)\n            # Indicate that the job has started\n            if task_status is not None:\n                task_status.started(pid)\n\n            # Monitor the job until completion\n            events_replicator = KubernetesEventsReplicator(\n                client=client,\n                job_name=job.metadata.name,\n                namespace=configuration.namespace,\n                worker_resource=self._event_resource(),\n                related_resources=self._event_related_resources(\n                    configuration=configuration\n                ),\n                timeout_seconds=configuration.pod_watch_timeout_seconds,\n            )\n            async with events_replicator:\n                status_code = await self._watch_job(\n                    logger, job.metadata.name, configuration, client\n                )\n\n            return KubernetesWorkerResult(identifier=pid, status_code=status_code)\n\n    async def kill_infrastructure(\n        self,\n        infrastructure_pid: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"\n                Stops a job for a cancelled flow run based on the provided infrastructure PID\n                and run configuration.\n        att\"\"\"\n        await self._stop_job(infrastructure_pid, configuration, grace_seconds)\n\n    async def teardown(self, *exc_info):\n        await super().teardown(*exc_info)\n\n        await self._clean_up_created_secrets()\n\n    async def _clean_up_created_secrets(self):\n        \"\"\"Deletes any secrets created during the worker's operation.\"\"\"\n        for key, configuration in self._created_secrets.items():\n            async with self._get_configured_kubernetes_client(configuration) as client:\n                v1 = CoreV1Api(client)\n                result = await v1.delete_namespaced_secret(\n                    name=key[0],\n                    namespace=key[1],\n                )\n\n                if isinstance(result, Exception):\n                    self._logger.warning(\n                        \"Failed to delete created secret with exception: %s\", result\n                    )\n\n    async def _stop_job(\n        self,\n        infrastructure_pid: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        grace_seconds: int = 30,\n    ):\n        \"\"\"Removes the given Job from the Kubernetes cluster\"\"\"\n        async with self._get_configured_kubernetes_client(configuration) as client:\n            job_cluster_uid, job_namespace, job_name = self._parse_infrastructure_pid(\n                infrastructure_pid\n            )\n\n            if job_namespace != configuration.namespace:\n                raise InfrastructureNotAvailable(\n                    f\"Unable to kill job {job_name!r}: The job is running in namespace \"\n                    f\"{job_namespace!r} but this worker expected jobs to be running in \"\n                    f\"namespace {configuration.namespace!r} based on the work pool and \"\n                    \"deployment configuration.\"\n                )\n\n            current_cluster_uid = await self._get_cluster_uid(client)\n            if job_cluster_uid != current_cluster_uid:\n                raise InfrastructureNotAvailable(\n                    f\"Unable to kill job {job_name!r}: The job is running on another \"\n                    \"cluster than the one specified by the infrastructure PID.\"\n                )\n\n            async with self._get_batch_client(client) as batch_client:\n                try:\n                    await batch_client.delete_namespaced_job(\n                        name=job_name,\n                        namespace=job_namespace,\n                        grace_period_seconds=grace_seconds,\n                        # Foreground propagation deletes dependent objects before deleting # noqa\n                        # owner objects. This ensures that the pods are cleaned up before # noqa\n                        # the job is marked as deleted.\n                        # See: https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion # noqa\n                        propagation_policy=\"Foreground\",\n                    )\n                except kubernetes_asyncio.client.exceptions.ApiException as exc:\n                    if exc.status == 404:\n                        raise InfrastructureNotFound(\n                            f\"Unable to kill job {job_name!r}: The job was not found.\"\n                        ) from exc\n                    else:\n                        raise\n\n    @asynccontextmanager\n    async def _get_configured_kubernetes_client(\n        self, configuration: KubernetesWorkerJobConfiguration\n    ) -&gt; AsyncGenerator[\"ApiClient\", None]:\n        \"\"\"\n        Returns a configured Kubernetes client.\n        \"\"\"\n        client = None\n\n        if configuration.cluster_config:\n            config_dict = configuration.cluster_config.config\n            context = configuration.cluster_config.context_name\n            client = await config.new_client_from_config_dict(\n                config_dict=config_dict,\n                context=context,\n            )\n        else:\n            # Try to load in-cluster configuration\n            try:\n                config.load_incluster_config()\n                client = ApiClient()\n            except config.ConfigException:\n                # If in-cluster config fails, load the local kubeconfig\n                client = await config.new_client_from_config()\n        try:\n            yield client\n        finally:\n            await client.close()\n\n    async def _replace_api_key_with_secret(\n        self, configuration: KubernetesWorkerJobConfiguration, client: \"ApiClient\"\n    ):\n        \"\"\"Replaces the PREFECT_API_KEY environment variable with a Kubernetes secret\"\"\"\n        manifest_env = configuration.job_manifest[\"spec\"][\"template\"][\"spec\"][\n            \"containers\"\n        ][0].get(\"env\")\n        manifest_api_key_env = next(\n            (\n                env_entry\n                for env_entry in manifest_env\n                if env_entry.get(\"name\") == \"PREFECT_API_KEY\"\n            ),\n            {},\n        )\n        api_key = manifest_api_key_env.get(\"value\")\n        if api_key:\n            secret_name = f\"prefect-{_slugify_name(self.name)}-api-key\"\n            secret = await self._upsert_secret(\n                name=secret_name,\n                value=api_key,\n                namespace=configuration.namespace,\n                client=client,\n            )\n            # Store configuration so that we can delete the secret when the worker shuts\n            # down\n            self._created_secrets[\n                (secret.metadata.name, secret.metadata.namespace)\n            ] = configuration\n            new_api_env_entry = {\n                \"name\": \"PREFECT_API_KEY\",\n                \"valueFrom\": {\"secretKeyRef\": {\"name\": secret_name, \"key\": \"value\"}},\n            }\n            manifest_env = [\n                entry if entry.get(\"name\") != \"PREFECT_API_KEY\" else new_api_env_entry\n                for entry in manifest_env\n            ]\n            configuration.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                \"env\"\n            ] = manifest_env\n\n    @retry(\n        stop=stop_after_attempt(MAX_ATTEMPTS),\n        wait=wait_fixed(RETRY_MIN_DELAY_SECONDS)\n        + wait_random(\n            RETRY_MIN_DELAY_JITTER_SECONDS,\n            RETRY_MAX_DELAY_JITTER_SECONDS,\n        ),\n        reraise=True,\n    )\n    async def _create_job(\n        self, configuration: KubernetesWorkerJobConfiguration, client: \"ApiClient\"\n    ) -&gt; \"V1Job\":\n        \"\"\"\n        Creates a Kubernetes job from a job manifest.\n        \"\"\"\n        if os.environ.get(\n            \"PREFECT_KUBERNETES_WORKER_STORE_PREFECT_API_IN_SECRET\", \"\"\n        ).strip().lower() in (\"true\", \"1\"):\n            await self._replace_api_key_with_secret(\n                configuration=configuration, client=client\n            )\n\n        try:\n            batch_client = BatchV1Api(client)\n            job = await batch_client.create_namespaced_job(\n                configuration.namespace,\n                configuration.job_manifest,\n            )\n        except kubernetes_asyncio.client.exceptions.ApiException as exc:\n            # Parse the reason and message from the response if feasible\n            message = \"\"\n            if exc.reason:\n                message += \": \" + exc.reason\n            if exc.body and \"message\" in (body := json.loads(exc.body)):\n                message += \": \" + body[\"message\"]\n\n            raise InfrastructureError(\n                f\"Unable to create Kubernetes job{message}\"\n            ) from exc\n\n        return job\n\n    async def _upsert_secret(\n        self, name: str, value: str, namespace: str, client: \"ApiClient\"\n    ):\n        encoded_value = base64.b64encode(value.encode(\"utf-8\")).decode(\"utf-8\")\n        core_client = CoreV1Api(client)\n        try:\n            # Get the current version of the Secret and update it with the\n            # new value\n            current_secret = await core_client.read_namespaced_secret(\n                name=name, namespace=namespace\n            )\n            current_secret.data = {\"value\": encoded_value}\n            secret = await core_client.replace_namespaced_secret(\n                name=name, namespace=namespace, body=current_secret\n            )\n        except ApiException as exc:\n            if exc.status != 404:\n                raise\n            # Create the secret if it doesn't already exist\n            metadata = V1ObjectMeta(name=name, namespace=namespace)\n            secret = V1Secret(\n                api_version=\"v1\",\n                kind=\"Secret\",\n                metadata=metadata,\n                data={\"value\": encoded_value},\n            )\n            secret = await core_client.create_namespaced_secret(\n                namespace=namespace, body=secret\n            )\n        return secret\n\n    @asynccontextmanager\n    async def _get_batch_client(\n        self, client: \"ApiClient\"\n    ) -&gt; AsyncGenerator[\"BatchV1Api\", None]:\n        \"\"\"\n        Context manager for retrieving a Kubernetes batch client.\n        \"\"\"\n        try:\n            yield BatchV1Api(api_client=client)\n        finally:\n            await client.close()\n\n    async def _get_infrastructure_pid(self, job: \"V1Job\", client: \"ApiClient\") -&gt; str:\n        \"\"\"\n        Generates a Kubernetes infrastructure PID.\n\n        The PID is in the format: \"&lt;cluster uid&gt;:&lt;namespace&gt;:&lt;job name&gt;\".\n        \"\"\"\n        cluster_uid = await self._get_cluster_uid(client)\n        pid = f\"{cluster_uid}:{job.metadata.namespace}:{job.metadata.name}\"\n        return pid\n\n    def _parse_infrastructure_pid(\n        self, infrastructure_pid: str\n    ) -&gt; Tuple[str, str, str]:\n        \"\"\"\n        Parse a Kubernetes infrastructure PID into its component parts.\n\n        Returns a cluster UID, namespace, and job name.\n        \"\"\"\n        cluster_uid, namespace, job_name = infrastructure_pid.split(\":\", 2)\n        return cluster_uid, namespace, job_name\n\n    async def _get_cluster_uid(self, client: \"ApiClient\") -&gt; str:\n        \"\"\"\n        Gets a unique id for the current cluster being used.\n\n        There is no real unique identifier for a cluster. However, the `kube-system`\n        namespace is immutable and has a persistence UID that we use instead.\n\n        PREFECT_KUBERNETES_CLUSTER_UID can be set in cases where the `kube-system`\n        namespace cannot be read e.g. when a cluster role cannot be created. If set,\n        this variable will be used and we will not attempt to read the `kube-system`\n        namespace.\n\n        See https://github.com/kubernetes/kubernetes/issues/44954\n        \"\"\"\n        # Default to an environment variable\n        env_cluster_uid = os.environ.get(\"PREFECT_KUBERNETES_CLUSTER_UID\")\n        if env_cluster_uid:\n            return env_cluster_uid\n\n        # Read the UID from the cluster namespace\n        v1 = CoreV1Api(client)\n        namespace = await v1.read_namespace(\"kube-system\")\n        cluster_uid = namespace.metadata.uid\n        return cluster_uid\n\n    async def _stream_job_logs(\n        self,\n        logger: logging.Logger,\n        pod_name: str,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client,\n    ):\n        timeout = aiohttp.ClientTimeout(total=None)\n        core_client = CoreV1Api(client)\n\n        logs = await core_client.read_namespaced_pod_log(\n            pod_name,\n            configuration.namespace,\n            follow=True,\n            _preload_content=False,\n            container=\"prefect-job\",\n            _request_timeout=timeout,\n        )\n        try:\n            async for line in logs.content:\n                if not line:\n                    break\n                print(line.decode().rstrip())\n        except Exception:\n            logger.warning(\n                (\n                    \"Error occurred while streaming logs - \"\n                    \"Job will continue to run but logs will \"\n                    \"no longer be streamed to stdout.\"\n                ),\n                exc_info=True,\n            )\n\n    async def _job_events(\n        self,\n        batch_client: BatchV1Api,\n        job_name: str,\n        namespace: str,\n        watch_kwargs: dict,\n    ):\n        \"\"\"\n        Stream job events.\n\n        Pick up from the current resource version returned by the API\n        in the case of a 410.\n\n        See https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes  # noqa\n        \"\"\"\n        watch = kubernetes_asyncio.watch.Watch()\n        resource_version = None\n        async with watch:\n            while True:\n                try:\n                    async for event in watch.stream(\n                        func=batch_client.list_namespaced_job,\n                        namespace=namespace,\n                        field_selector=f\"metadata.name={job_name}\",\n                        **watch_kwargs,\n                    ):\n                        yield event\n                except ApiException as e:\n                    if e.status == 410:\n                        job_list = await batch_client.list_namespaced_job(\n                            namespace=namespace,\n                            field_selector=f\"metadata.name={job_name}\",\n                        )\n\n                        resource_version = job_list.metadata.resource_version\n                        watch_kwargs[\"resource_version\"] = resource_version\n                    else:\n                        raise\n\n    async def _monitor_job_events(self, batch_client, job_name, logger, configuration):\n        job = await batch_client.read_namespaced_job(\n            name=job_name, namespace=configuration.namespace\n        )\n        completed = job.status.completion_time is not None\n        watch_kwargs = (\n            {\"timeout_seconds\": configuration.job_watch_timeout_seconds}\n            if configuration.job_watch_timeout_seconds\n            else {}\n        )\n\n        while not completed:\n            async for event in self._job_events(\n                batch_client,\n                job_name,\n                configuration.namespace,\n                watch_kwargs,\n            ):\n                if event[\"type\"] == \"DELETED\":\n                    logger.error(f\"Job {job_name!r}: Job has been deleted.\")\n                    completed = True\n                elif event[\"object\"].status.completion_time:\n                    if not event[\"object\"].status.succeeded:\n                        # Job failed, exit while loop and return pod exit code\n                        logger.error(f\"Job {job_name!r}: Job failed.\")\n                    completed = True\n                # Check if the job has reached its backoff limit\n                # and stop watching if it has\n                elif (\n                    event[\"object\"].spec.backoff_limit is not None\n                    and event[\"object\"].status.failed is not None\n                    and event[\"object\"].status.failed\n                    &gt; event[\"object\"].spec.backoff_limit\n                ):\n                    logger.error(f\"Job {job_name!r}: Job reached backoff limit.\")\n                    completed = True\n                # If the job has no backoff limit, check if it has failed\n                # and stop watching if it has\n                elif (\n                    not event[\"object\"].spec.backoff_limit\n                    and event[\"object\"].status.failed\n                ):\n                    completed = True\n                if completed:\n                    break\n\n    async def _watch_job(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; int:\n        \"\"\"\n        Watch a job.\n\n        Return the final status code of the first container.\n        \"\"\"\n\n        logger.debug(f\"Job {job_name!r}: Monitoring job...\")\n\n        job = await self._get_job(logger, job_name, configuration, client)\n        if not job:\n            return -1\n\n        pod = await self._get_job_pod(logger, job_name, configuration, client)\n        if not pod:\n            return -1\n\n        # Create a list of tasks to run concurrently\n        async with self._get_batch_client(client) as batch_client:\n            tasks = [\n                self._monitor_job_events(\n                    batch_client,\n                    job_name,\n                    logger,\n                    configuration,\n                )\n            ]\n            try:\n                with timeout_async(seconds=configuration.job_watch_timeout_seconds):\n                    if configuration.stream_output:\n                        tasks.append(\n                            self._stream_job_logs(\n                                logger,\n                                pod.metadata.name,\n                                job_name,\n                                configuration,\n                                client,\n                            )\n                        )\n\n                    results = await asyncio.gather(*tasks, return_exceptions=True)\n                    if any(isinstance(result, Exception) for result in results):\n                        for result in results:\n                            if isinstance(result, Exception):\n                                logger.error(\n                                    f\"Error during task execution: {result}\",\n                                    exc_info=True,\n                                )\n            except TimeoutError:\n                logger.error(\n                    f\"Job {job_name!r}: Job did not complete within \"\n                    f\"timeout of {configuration.job_watch_timeout_seconds}s.\"\n                )\n                return -1\n\n            core_client = CoreV1Api(client)\n            # Get all pods for the job\n            pods = await core_client.list_namespaced_pod(\n                namespace=configuration.namespace, label_selector=f\"job-name={job_name}\"\n            )\n            # Get the status for only the most recently used pod\n            pods.items.sort(\n                key=lambda pod: pod.metadata.creation_timestamp, reverse=True\n            )\n            most_recent_pod = pods.items[0] if pods.items else None\n            first_container_status = (\n                most_recent_pod.status.container_statuses[0]\n                if most_recent_pod\n                else None\n            )\n\n        if not first_container_status:\n            logger.error(f\"Job {job_name!r}: No pods found for job.\")\n            return -1\n        # In some cases, such as spot instance evictions, the pod will be forcibly\n        # terminated and not report a status correctly.\n        elif (\n            first_container_status.state is None\n            or first_container_status.state.terminated is None\n            or first_container_status.state.terminated.exit_code is None\n        ):\n            logger.error(\n                f\"Could not determine exit code for {job_name!r}.\"\n                \"Exit code will be reported as -1.\"\n                f\"First container status info did not report an exit code.\"\n                f\"First container info: {first_container_status}.\"\n            )\n            return -1\n\n        return first_container_status.state.terminated.exit_code\n\n    async def _get_job(\n        self,\n        logger: logging.Logger,\n        job_id: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; Optional[\"V1Job\"]:\n        \"\"\"Get a Kubernetes job by id.\"\"\"\n\n        try:\n            batch_client = BatchV1Api(client)\n            job = await batch_client.read_namespaced_job(\n                name=job_id, namespace=configuration.namespace\n            )\n        except kubernetes_asyncio.client.exceptions.ApiException:\n            logger.error(f\"Job {job_id!r} was removed.\", exc_info=True)\n            return None\n        return job\n\n    async def _get_job_pod(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; Optional[\"V1Pod\"]:\n        \"\"\"Get the first running pod for a job.\"\"\"\n\n        watch = kubernetes_asyncio.watch.Watch()\n        logger.info(f\"Job {job_name!r}: Starting watch for pod start...\")\n        last_phase = None\n        last_pod_name: Optional[str] = None\n        core_client = CoreV1Api(client)\n        async with watch:\n            async for event in watch.stream(\n                func=core_client.list_namespaced_pod,\n                namespace=configuration.namespace,\n                label_selector=f\"job-name={job_name}\",\n                timeout_seconds=configuration.pod_watch_timeout_seconds,\n            ):\n                pod: V1Pod = event[\"object\"]\n                last_pod_name = pod.metadata.name\n                logger.info(f\"Job {job_name!r}: Pod {last_pod_name!r} has started.\")\n                phase = pod.status.phase\n                if phase != last_phase:\n                    logger.info(f\"Job {job_name!r}: Pod has status {phase!r}.\")\n\n                if phase != \"Pending\":\n                    return pod\n\n                last_phase = phase\n            # If we've gotten here, we never found the Pod that was created for the flow run\n            # Job, so let's inspect the situation and log what we can find.  It's possible\n            # that the Job ran into scheduling constraints it couldn't satisfy, like\n            # memory/CPU requests, or a volume that wasn't available, or a node with an\n            # available GPU.\n            logger.error(f\"Job {job_name!r}: Pod never started.\")\n            await self._log_recent_events(\n                logger, job_name, last_pod_name, configuration, client\n            )\n\n    async def _log_recent_events(\n        self,\n        logger: logging.Logger,\n        job_name: str,\n        pod_name: Optional[str],\n        configuration: KubernetesWorkerJobConfiguration,\n        client: \"ApiClient\",\n    ) -&gt; None:\n        \"\"\"Look for reasons why a Job may not have been able to schedule a Pod, or why\n        a Pod may not have been able to start and log them to the provided logger.\"\"\"\n\n        def best_event_time(event: CoreV1Event) -&gt; datetime:\n            \"\"\"Choose the best timestamp from a Kubernetes event\"\"\"\n            return event.event_time or event.last_timestamp\n\n        def log_event(event: CoreV1Event):\n            \"\"\"Log an event in one of a few formats to the provided logger\"\"\"\n            if event.count and event.count &gt; 1:\n                logger.info(\n                    \"%s event %r (%s times) at %s: %s\",\n                    event.involved_object.kind,\n                    event.reason,\n                    event.count,\n                    best_event_time(event),\n                    event.message,\n                )\n            else:\n                logger.info(\n                    \"%s event %r at %s: %s\",\n                    event.involved_object.kind,\n                    event.reason,\n                    best_event_time(event),\n                    event.message,\n                )\n\n        core_client = CoreV1Api(client)\n\n        events: CoreV1EventList = await core_client.list_namespaced_event(\n            configuration.namespace\n        )\n\n        event: CoreV1Event\n        for event in sorted(events.items, key=best_event_time):\n            if (\n                event.involved_object.api_version == \"batch/v1\"\n                and event.involved_object.kind == \"Job\"\n                and event.involved_object.namespace == configuration.namespace\n                and event.involved_object.name == job_name\n            ):\n                log_event(event)\n\n            if (\n                pod_name\n                and event.involved_object.api_version == \"v1\"\n                and event.involved_object.kind == \"Pod\"\n                and event.involved_object.namespace == configuration.namespace\n                and event.involved_object.name == pod_name\n            ):\n                log_event(event)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker.kill_infrastructure","title":"<code>kill_infrastructure</code>  <code>async</code>","text":"<pre><code>    Stops a job for a cancelled flow run based on the provided infrastructure PID\n    and run configuration.\n</code></pre> <p>att</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>async def kill_infrastructure(\n    self,\n    infrastructure_pid: str,\n    configuration: KubernetesWorkerJobConfiguration,\n    grace_seconds: int = 30,\n):\n    \"\"\"\n            Stops a job for a cancelled flow run based on the provided infrastructure PID\n            and run configuration.\n    att\"\"\"\n    await self._stop_job(infrastructure_pid, configuration, grace_seconds)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorker.run","title":"<code>run</code>  <code>async</code>","text":"<p>Executes a flow run within a Kubernetes Job and waits for the flow run to complete.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to execute</p> required <code>configuration</code> <code>KubernetesWorkerJobConfiguration</code> <p>The configuration to use when executing the flow run.</p> required <code>task_status</code> <code>Optional[TaskStatus]</code> <p>The task status object for the current flow run. If provided, the task will be marked as started.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>KubernetesWorkerResult</code> <code>KubernetesWorkerResult</code> <p>A result object containing information about the final state of the flow run</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>async def run(\n    self,\n    flow_run: \"FlowRun\",\n    configuration: KubernetesWorkerJobConfiguration,\n    task_status: Optional[anyio.abc.TaskStatus] = None,\n) -&gt; KubernetesWorkerResult:\n    \"\"\"\n    Executes a flow run within a Kubernetes Job and waits for the flow run\n    to complete.\n\n    Args:\n        flow_run: The flow run to execute\n        configuration: The configuration to use when executing the flow run.\n        task_status: The task status object for the current flow run. If provided,\n            the task will be marked as started.\n\n    Returns:\n        KubernetesWorkerResult: A result object containing information about the\n            final state of the flow run\n    \"\"\"\n    logger = self.get_flow_run_logger(flow_run)\n    async with self._get_configured_kubernetes_client(configuration) as client:\n        logger.info(\"Creating Kubernetes job...\")\n\n        job = await self._create_job(configuration, client)\n\n        pid = await self._get_infrastructure_pid(job, client)\n        # Indicate that the job has started\n        if task_status is not None:\n            task_status.started(pid)\n\n        # Monitor the job until completion\n        events_replicator = KubernetesEventsReplicator(\n            client=client,\n            job_name=job.metadata.name,\n            namespace=configuration.namespace,\n            worker_resource=self._event_resource(),\n            related_resources=self._event_related_resources(\n                configuration=configuration\n            ),\n            timeout_seconds=configuration.pod_watch_timeout_seconds,\n        )\n        async with events_replicator:\n            status_code = await self._watch_job(\n                logger, job.metadata.name, configuration, client\n            )\n\n        return KubernetesWorkerResult(identifier=pid, status_code=status_code)\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerJobConfiguration","title":"<code>KubernetesWorkerJobConfiguration</code>","text":"<p>               Bases: <code>BaseJobConfiguration</code></p> <p>Configuration class used by the Kubernetes worker.</p> <p>An instance of this class is passed to the Kubernetes worker's <code>run</code> method for each flow run. It contains all of the information necessary to execute the flow run as a Kubernetes job.</p> <p>Attributes:</p> Name Type Description <code>name</code> <p>The name to give to created Kubernetes job.</p> <code>command</code> <p>The command executed in created Kubernetes jobs to kick off flow run execution.</p> <code>env</code> <p>The environment variables to set in created Kubernetes jobs.</p> <code>labels</code> <p>The labels to set on created Kubernetes jobs.</p> <code>namespace</code> <code>str</code> <p>The Kubernetes namespace to create Kubernetes jobs in.</p> <code>job_manifest</code> <code>Dict[str, Any]</code> <p>The Kubernetes job manifest to use to create Kubernetes jobs.</p> <code>cluster_config</code> <code>Optional[KubernetesClusterConfig]</code> <p>The Kubernetes cluster configuration to use for authentication to a Kubernetes cluster.</p> <code>job_watch_timeout_seconds</code> <code>Optional[int]</code> <p>The number of seconds to wait for the job to complete before timing out. If <code>None</code>, the worker will wait indefinitely.</p> <code>pod_watch_timeout_seconds</code> <code>int</code> <p>The number of seconds to wait for the pod to complete before timing out.</p> <code>stream_output</code> <code>bool</code> <p>Whether or not to stream the job's output.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerJobConfiguration(BaseJobConfiguration):\n    \"\"\"\n    Configuration class used by the Kubernetes worker.\n\n    An instance of this class is passed to the Kubernetes worker's `run` method\n    for each flow run. It contains all of the information necessary to execute\n    the flow run as a Kubernetes job.\n\n    Attributes:\n        name: The name to give to created Kubernetes job.\n        command: The command executed in created Kubernetes jobs to kick off\n            flow run execution.\n        env: The environment variables to set in created Kubernetes jobs.\n        labels: The labels to set on created Kubernetes jobs.\n        namespace: The Kubernetes namespace to create Kubernetes jobs in.\n        job_manifest: The Kubernetes job manifest to use to create Kubernetes jobs.\n        cluster_config: The Kubernetes cluster configuration to use for authentication\n            to a Kubernetes cluster.\n        job_watch_timeout_seconds: The number of seconds to wait for the job to\n            complete before timing out. If `None`, the worker will wait indefinitely.\n        pod_watch_timeout_seconds: The number of seconds to wait for the pod to\n            complete before timing out.\n        stream_output: Whether or not to stream the job's output.\n    \"\"\"\n\n    namespace: str = Field(default=\"default\")\n    job_manifest: Dict[str, Any] = Field(template=_get_default_job_manifest_template())\n    cluster_config: Optional[KubernetesClusterConfig] = Field(default=None)\n    job_watch_timeout_seconds: Optional[int] = Field(default=None)\n    pod_watch_timeout_seconds: int = Field(default=60)\n    stream_output: bool = Field(default=True)\n\n    # internal-use only\n    _api_dns_name: Optional[str] = None  # Replaces 'localhost' in API URL\n\n    @validator(\"job_manifest\")\n    def _ensure_metadata_is_present(cls, value: Dict[str, Any]):\n        \"\"\"Ensures that the metadata is present in the job manifest.\"\"\"\n        if \"metadata\" not in value:\n            value[\"metadata\"] = {}\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_labels_is_present(cls, value: Dict[str, Any]):\n        \"\"\"Ensures that the metadata is present in the job manifest.\"\"\"\n        if \"labels\" not in value[\"metadata\"]:\n            value[\"metadata\"][\"labels\"] = {}\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_namespace_is_present(cls, value: Dict[str, Any], values):\n        \"\"\"Ensures that the namespace is present in the job manifest.\"\"\"\n        if \"namespace\" not in value[\"metadata\"]:\n            value[\"metadata\"][\"namespace\"] = values[\"namespace\"]\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_job_includes_all_required_components(cls, value: Dict[str, Any]):\n        \"\"\"\n        Ensures that the job manifest includes all required components.\n        \"\"\"\n        patch = JsonPatch.from_diff(value, _get_base_job_manifest())\n        missing_paths = sorted([op[\"path\"] for op in patch if op[\"op\"] == \"add\"])\n        if missing_paths:\n            raise ValueError(\n                \"Job is missing required attributes at the following paths: \"\n                f\"{', '.join(missing_paths)}\"\n            )\n        return value\n\n    @validator(\"job_manifest\")\n    def _ensure_job_has_compatible_values(cls, value: Dict[str, Any]):\n        patch = JsonPatch.from_diff(value, _get_base_job_manifest())\n        incompatible = sorted(\n            [\n                f\"{op['path']} must have value {op['value']!r}\"\n                for op in patch\n                if op[\"op\"] == \"replace\"\n            ]\n        )\n        if incompatible:\n            raise ValueError(\n                \"Job has incompatible values for the following attributes: \"\n                f\"{', '.join(incompatible)}\"\n            )\n        return value\n\n    @staticmethod\n    def _base_flow_run_labels(flow_run: \"FlowRun\") -&gt; Dict[str, str]:\n        \"\"\"\n        Generate a dictionary of labels for a flow run job.\n        \"\"\"\n        return {\n            \"prefect.io/flow-run-id\": str(flow_run.id),\n            \"prefect.io/flow-run-name\": flow_run.name,\n            \"prefect.io/version\": _slugify_label_value(\n                prefect.__version__.split(\"+\")[0]\n            ),\n        }\n\n    def prepare_for_flow_run(\n        self,\n        flow_run: \"FlowRun\",\n        deployment: Optional[\"DeploymentResponse\"] = None,\n        flow: Optional[\"Flow\"] = None,\n    ):\n        \"\"\"\n        Prepares the job configuration for a flow run.\n\n        Ensures that necessary values are present in the job manifest and that the\n        job manifest is valid.\n\n        Args:\n            flow_run: The flow run to prepare the job configuration for\n            deployment: The deployment associated with the flow run used for\n                preparation.\n            flow: The flow associated with the flow run used for preparation.\n        \"\"\"\n\n        super().prepare_for_flow_run(flow_run, deployment, flow)\n        # Update configuration env and job manifest env\n        self._update_prefect_api_url_if_local_server()\n        self._populate_env_in_manifest()\n        # Update labels in job manifest\n        self._slugify_labels()\n        # Add defaults to job manifest if necessary\n        self._populate_image_if_not_present()\n        self._populate_command_if_not_present()\n        self._populate_generate_name_if_not_present()\n\n    def _populate_env_in_manifest(self):\n        \"\"\"\n        Populates environment variables in the job manifest.\n\n        When `env` is templated as a variable in the job manifest it comes in as a\n        dictionary. We need to convert it to a list of dictionaries to conform to the\n        Kubernetes job manifest schema.\n\n        This function also handles the case where the user has removed the `{{ env }}`\n        placeholder and hard coded a value for `env`. In this case, we need to prepend\n        our environment variables to the list to ensure Prefect setting propagation.\n        An example reason the a user would remove the `{{ env }}` placeholder to\n        hardcode Kubernetes secrets in the base job template.\n        \"\"\"\n        transformed_env = [{\"name\": k, \"value\": v} for k, v in self.env.items()]\n\n        template_env = self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][\n            0\n        ].get(\"env\")\n\n        # If user has removed `{{ env }}` placeholder and hard coded a value for `env`,\n        # we need to prepend our environment variables to the list to ensure Prefect\n        # setting propagation.\n        if isinstance(template_env, list):\n            self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\"env\"] = [\n                *transformed_env,\n                *template_env,\n            ]\n        # Current templating adds `env` as a dict when the kubernetes manifest requires\n        # a list of dicts. Might be able to improve this in the future with a better\n        # default `env` value and better typing.\n        else:\n            self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                \"env\"\n            ] = transformed_env\n\n    def _update_prefect_api_url_if_local_server(self):\n        \"\"\"If the API URL has been set by the base environment rather than the by the\n        user, update the value to ensure connectivity when using a bridge network by\n        updating local connections to use the internal host\n        \"\"\"\n        if self.env.get(\"PREFECT_API_URL\") and self._api_dns_name:\n            self.env[\"PREFECT_API_URL\"] = (\n                self.env[\"PREFECT_API_URL\"]\n                .replace(\"localhost\", self._api_dns_name)\n                .replace(\"127.0.0.1\", self._api_dns_name)\n            )\n\n    def _slugify_labels(self):\n        \"\"\"Slugifies the labels in the job manifest.\"\"\"\n        all_labels = {**self.job_manifest[\"metadata\"].get(\"labels\", {}), **self.labels}\n        self.job_manifest[\"metadata\"][\"labels\"] = {\n            _slugify_label_key(k): _slugify_label_value(v)\n            for k, v in all_labels.items()\n        }\n\n    def _populate_image_if_not_present(self):\n        \"\"\"Ensures that the image is present in the job manifest. Populates the image\n        with the default Prefect image if it is not present.\"\"\"\n        try:\n            if (\n                \"image\"\n                not in self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0]\n            ):\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"image\"\n                ] = get_prefect_image_name()\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify image due to invalid job manifest template.\"\n            )\n\n    def _populate_command_if_not_present(self):\n        \"\"\"\n        Ensures that the command is present in the job manifest. Populates the command\n        with the `prefect -m prefect.engine` if a command is not present.\n        \"\"\"\n        try:\n            command = self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][\n                0\n            ].get(\"args\")\n            if command is None:\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"args\"\n                ] = shlex.split(self._base_flow_run_command())\n            elif isinstance(command, str):\n                self.job_manifest[\"spec\"][\"template\"][\"spec\"][\"containers\"][0][\n                    \"args\"\n                ] = shlex.split(command)\n            elif not isinstance(command, list):\n                raise ValueError(\n                    \"Invalid job manifest template: 'command' must be a string or list.\"\n                )\n        except KeyError:\n            raise ValueError(\n                \"Unable to verify command due to invalid job manifest template.\"\n            )\n\n    def _populate_generate_name_if_not_present(self):\n        \"\"\"Ensures that the generateName is present in the job manifest.\"\"\"\n        manifest_generate_name = self.job_manifest[\"metadata\"].get(\"generateName\", \"\")\n        has_placeholder = len(find_placeholders(manifest_generate_name)) &gt; 0\n        # if name wasn't present during template rendering, generateName will be\n        # just a hyphen\n\n        manifest_generate_name_templated_with_empty_string = (\n            manifest_generate_name == \"-\"\n        )\n        if (\n            not manifest_generate_name\n            or has_placeholder\n            or manifest_generate_name_templated_with_empty_string\n            or manifest_generate_name == \"None-\"\n        ):\n            generate_name = None\n            if self.name:\n                generate_name = _slugify_name(self.name)\n            # _slugify_name will return None if the slugified name in an exception\n            if not generate_name:\n                generate_name = \"prefect-job\"\n            self.job_manifest[\"metadata\"][\"generateName\"] = f\"{generate_name}-\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerJobConfiguration.prepare_for_flow_run","title":"<code>prepare_for_flow_run</code>","text":"<p>Prepares the job configuration for a flow run.</p> <p>Ensures that necessary values are present in the job manifest and that the job manifest is valid.</p> <p>Parameters:</p> Name Type Description Default <code>flow_run</code> <code>FlowRun</code> <p>The flow run to prepare the job configuration for</p> required <code>deployment</code> <code>Optional[DeploymentResponse]</code> <p>The deployment associated with the flow run used for preparation.</p> <code>None</code> <code>flow</code> <code>Optional[Flow]</code> <p>The flow associated with the flow run used for preparation.</p> <code>None</code> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>def prepare_for_flow_run(\n    self,\n    flow_run: \"FlowRun\",\n    deployment: Optional[\"DeploymentResponse\"] = None,\n    flow: Optional[\"Flow\"] = None,\n):\n    \"\"\"\n    Prepares the job configuration for a flow run.\n\n    Ensures that necessary values are present in the job manifest and that the\n    job manifest is valid.\n\n    Args:\n        flow_run: The flow run to prepare the job configuration for\n        deployment: The deployment associated with the flow run used for\n            preparation.\n        flow: The flow associated with the flow run used for preparation.\n    \"\"\"\n\n    super().prepare_for_flow_run(flow_run, deployment, flow)\n    # Update configuration env and job manifest env\n    self._update_prefect_api_url_if_local_server()\n    self._populate_env_in_manifest()\n    # Update labels in job manifest\n    self._slugify_labels()\n    # Add defaults to job manifest if necessary\n    self._populate_image_if_not_present()\n    self._populate_command_if_not_present()\n    self._populate_generate_name_if_not_present()\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerResult","title":"<code>KubernetesWorkerResult</code>","text":"<p>               Bases: <code>BaseWorkerResult</code></p> <p>Contains information about the final state of a completed process</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerResult(BaseWorkerResult):\n    \"\"\"Contains information about the final state of a completed process\"\"\"\n</code></pre>"},{"location":"integrations/prefect-kubernetes/worker/#prefect_kubernetes.worker.KubernetesWorkerVariables","title":"<code>KubernetesWorkerVariables</code>","text":"<p>               Bases: <code>BaseVariables</code></p> <p>Default variables for the Kubernetes worker.</p> <p>The schema for this class is used to populate the <code>variables</code> section of the default base job template.</p> Source code in <code>prefect_kubernetes/worker.py</code> <pre><code>class KubernetesWorkerVariables(BaseVariables):\n    \"\"\"\n    Default variables for the Kubernetes worker.\n\n    The schema for this class is used to populate the `variables` section of the default\n    base job template.\n    \"\"\"\n\n    namespace: str = Field(\n        default=\"default\", description=\"The Kubernetes namespace to create jobs within.\"\n    )\n    image: Optional[str] = Field(\n        default=None,\n        description=\"The image reference of a container image to use for created jobs. \"\n        \"If not set, the latest Prefect image will be used.\",\n        examples=[\"docker.io/prefecthq/prefect:3-latest\"],\n    )\n    service_account_name: Optional[str] = Field(\n        default=None,\n        description=\"The Kubernetes service account to use for job creation.\",\n    )\n    image_pull_policy: Literal[\"IfNotPresent\", \"Always\", \"Never\"] = Field(\n        default=KubernetesImagePullPolicy.IF_NOT_PRESENT,\n        description=\"The Kubernetes image pull policy to use for job containers.\",\n    )\n    finished_job_ttl: Optional[int] = Field(\n        default=None,\n        title=\"Finished Job TTL\",\n        description=\"The number of seconds to retain jobs after completion. If set, \"\n        \"finished jobs will be cleaned up by Kubernetes after the given delay. If not \"\n        \"set, jobs will be retained indefinitely.\",\n    )\n    job_watch_timeout_seconds: Optional[int] = Field(\n        default=None,\n        description=(\n            \"Number of seconds to wait for each event emitted by a job before \"\n            \"timing out. If not set, the worker will wait for each event indefinitely.\"\n        ),\n    )\n    pod_watch_timeout_seconds: int = Field(\n        default=60,\n        description=\"Number of seconds to watch for pod creation before timing out.\",\n    )\n    stream_output: bool = Field(\n        default=True,\n        description=(\n            \"If set, output will be streamed from the job to local standard output.\"\n        ),\n    )\n    cluster_config: Optional[KubernetesClusterConfig] = Field(\n        default=None,\n        description=\"The Kubernetes cluster config to use for job creation.\",\n    )\n</code></pre>"},{"location":"integrations/prefect-ray/","title":"prefect-ray","text":"<p>Ray can run the tasks in your flow in parallel by distributing them over multiple machines. The <code>prefect-ray</code> integration makes it easy speed up your flow runs by integrating Ray into your code.</p>"},{"location":"integrations/prefect-ray/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-ray/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed in a virtual environment.</li> </ul>"},{"location":"integrations/prefect-ray/#install-prefect-ray","title":"Install prefect-ray","text":"<pre><code>pip install prefect-ray\n</code></pre> <p>Ray environment limitations</p> <p>While we're excited about parallel task execution via Ray, there are a few limitations with Ray you should be aware of:</p> <ul> <li>Support for Python 3.11 is experimental.</li> <li>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</li> <li>Ray's Windows support is currently in beta.</li> </ul> <p>See the Ray installation documentation for further compatibility information.</p>"},{"location":"integrations/prefect-ray/#running-tasks-on-ray","title":"Running tasks on Ray","text":"<p>The <code>RayTaskRunner</code> is a Prefect task runner that submits tasks to Ray for parallel execution.</p> <p>By default, a temporary Ray instance is created for the duration of the flow run.</p> <p>For example, this flow counts to three in parallel.</p> <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_ray import RayTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=RayTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre> <p>If you already have a Ray instance running, you can provide the connection URL via an <code>address</code> argument.</p> <p>To configure your flow to use the <code>RayTaskRunner</code>:</p> <ol> <li>Make sure the <code>prefect-ray</code> collection is installed as described earlier: <code>pip install prefect-ray</code>.</li> <li>In your flow code, import <code>RayTaskRunner</code> from <code>prefect_ray.task_runners</code>.</li> <li>Assign it as the task runner when the flow is defined using the <code>task_runner=RayTaskRunner</code> argument.</li> </ol> <p>For example, this flow uses the <code>RayTaskRunner</code> with a local, temporary Ray instance created by Prefect at flow run time.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    ... \n</code></pre> <p>This flow uses the <code>RayTaskRunner</code> configured to access an existing Ray instance at <code>ray://192.0.2.255:8786</code>.</p> <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner(address=\"ray://192.0.2.255:8786\"))\ndef my_flow():\n    ... \n</code></pre> <p><code>RayTaskRunner</code> accepts the following optional parameters:</p> Parameter Description address Address of a currently running Ray instance, starting with the ray:// URI. init_kwargs Additional kwargs to use when calling <code>ray.init</code>. <p>Note that Ray Client uses the ray:// URI to indicate the address of a Ray instance. If you don't provide the <code>address</code> of a Ray instance, Prefect creates a temporary instance automatically.</p> <p>Ray environment limitations</p> <p>Ray support for non-x86/64 architectures such as ARM/M1 processors with installation from <code>pip</code> alone and will be skipped during installation of Prefect. It is possible to manually install the blocking component with <code>conda</code>. See the Ray documentation for instructions.</p> <p>See the Ray installation documentation for further compatibility information.</p>"},{"location":"integrations/prefect-ray/#running-tasks-on-a-ray-remote-cluster","title":"Running tasks on a Ray remote cluster","text":"<p>When using the <code>RayTaskRunner</code> with a remote Ray cluster, you may run into issues that are not seen when using a local Ray instance. To resolve these issues, we recommend taking the following steps when working with a remote Ray cluster:</p> <ol> <li>By default, Prefect will not persist any data to the filesystem of the remote ray worker. However, if you want to take advantage of Prefect's caching ability, you will need to configure a remote result storage to persist results across task runs.</li> </ol> <p>We recommend using the Prefect UI to configure a storage block to use for remote results storage.</p> <p>Here's an example of a flow that uses caching and remote result storage:</p> <pre><code>from typing import List\n\nfrom prefect import flow, get_run_logger, task\nfrom prefect.filesystems import S3\nfrom prefect.tasks import task_input_hash\nfrom prefect_ray.task_runners import RayTaskRunner\n\n\n# The result of this task will be cached in the configured result storage\n@task(cache_key_fn=task_input_hash)\ndef say_hello(name: str) -&gt; None:\n    logger = get_run_logger()\n    # This log statement will print only on the first run. Subsequent runs will be cached.\n    logger.info(f\"hello {name}!\")\n    return name\n\n\n@flow(\n    task_runner=RayTaskRunner(\n        address=\"ray://&lt;instance_public_ip_address&gt;:10001\",\n    ),\n    # Using an S3 block that has already been created via the Prefect UI\n    result_storage=\"s3/my-result-storage\",\n)\ndef greetings(names: List[str]) -&gt; None:\n    for name in names:\n        say_hello.submit(name)\n\n\nif __name__ == \"__main__\":\n    greetings([\"arthur\", \"trillian\", \"ford\", \"marvin\"])\n</code></pre> <ol> <li>If you get an error stating that the module 'prefect' cannot be found, ensure <code>prefect</code> is installed on the remote cluster, with:</li> </ol> <pre><code>pip install prefect\n</code></pre> <ol> <li>If you get an error with a message similar to \"File system created with scheme 's3' could not be created\", ensure the required Python modules are installed on both local and remote machines. The required prerequisite modules can be found in the Prefect documentation. For example, if using S3 for storage:</li> </ol> <pre><code>pip install s3fs\n</code></pre> <ol> <li>If you are seeing timeout or other connection errors, double check the address provided to the <code>RayTaskRunner</code>. The address should look similar to: <code>address='ray://&lt;head_node_ip_address&gt;:10001'</code>:</li> </ol> <pre><code>RayTaskRunner(address=\"ray://1.23.199.255:10001\")\n</code></pre>"},{"location":"integrations/prefect-ray/#specifying-remote-options","title":"Specifying remote options","text":"<p>The <code>remote_options</code> context can be used to control the task\u2019s remote options.</p> <p>For example, we can set the number of CPUs and GPUs to use for the <code>process</code> task:</p> <pre><code>from prefect import flow, task\nfrom prefect_ray.task_runners import RayTaskRunner\nfrom prefect_ray.context import remote_options\n\n@task\ndef process(x):\n    return x + 1\n\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    # equivalent to setting @ray.remote(num_cpus=4, num_gpus=2)\n    with remote_options(num_cpus=4, num_gpus=2):\n        process.submit(42)\n</code></pre>"},{"location":"integrations/prefect-ray/#resources","title":"Resources","text":"<p>Refer to the prefect-ray API documentation linked in the sidebar to explore all the capabilities of the prefect-ray library.</p> <p>For assistance using Dask, consult the Ray documentation.</p>"},{"location":"integrations/prefect-ray/task-runners/","title":"Task Runners","text":""},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners","title":"<code>prefect_ray.task_runners</code>","text":"<p>Interface and implementations of the Ray Task Runner. Task Runners in Prefect are responsible for managing the execution of Prefect task runs. Generally speaking, users are not expected to interact with task runners outside of configuring and initializing them for a flow.</p> Example <pre><code>import time\n\nfrom prefect import flow, task\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#0\n#1\n#2\n#3\n#4\n#5\n#6\n#7\n#8\n#9\n</code></pre> <p>Switching to a <code>RayTaskRunner</code>: <pre><code>import time\n\nfrom prefect import flow, task\nfrom prefect_ray import RayTaskRunner\n\n@task\ndef shout(number):\n    time.sleep(0.5)\n    print(f\"#{number}\")\n\n@flow(task_runner=RayTaskRunner)\ndef count_to(highest_number):\n    for number in range(highest_number):\n        shout.submit(number)\n\nif __name__ == \"__main__\":\n    count_to(10)\n\n# outputs\n#3\n#7\n#2\n#6\n#4\n#0\n#1\n#5\n#8\n#9\n</code></pre></p>"},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners.RayTaskRunner","title":"<code>RayTaskRunner</code>","text":"<p>               Bases: <code>BaseTaskRunner</code></p> <p>A parallel task_runner that submits tasks to <code>ray</code>. By default, a temporary Ray cluster is created for the duration of the flow run. Alternatively, if you already have a <code>ray</code> instance running, you can provide the connection URL via the <code>address</code> kwarg. Args:     address (string, optional): Address of a currently running <code>ray</code> instance; if         one is not provided, a temporary instance will be created.     init_kwargs (dict, optional): Additional kwargs to use when calling <code>ray.init</code>. Examples:     Using a temporary local ray cluster:     <pre><code>from prefect import flow\nfrom prefect_ray.task_runners import RayTaskRunner\n\n@flow(task_runner=RayTaskRunner())\ndef my_flow():\n    ...\n</code></pre>     Connecting to an existing ray instance:     <pre><code>RayTaskRunner(address=\"ray://192.0.2.255:8786\")\n</code></pre></p> Source code in <code>prefect_ray/task_runners.py</code> <pre><code>class RayTaskRunner(BaseTaskRunner):\n    \"\"\"\n    A parallel task_runner that submits tasks to `ray`.\n    By default, a temporary Ray cluster is created for the duration of the flow run.\n    Alternatively, if you already have a `ray` instance running, you can provide\n    the connection URL via the `address` kwarg.\n    Args:\n        address (string, optional): Address of a currently running `ray` instance; if\n            one is not provided, a temporary instance will be created.\n        init_kwargs (dict, optional): Additional kwargs to use when calling `ray.init`.\n    Examples:\n        Using a temporary local ray cluster:\n        ```python\n        from prefect import flow\n        from prefect_ray.task_runners import RayTaskRunner\n\n        @flow(task_runner=RayTaskRunner())\n        def my_flow():\n            ...\n        ```\n        Connecting to an existing ray instance:\n        ```python\n        RayTaskRunner(address=\"ray://192.0.2.255:8786\")\n        ```\n    \"\"\"\n\n    def __init__(\n        self,\n        address: str = None,\n        init_kwargs: dict = None,\n    ):\n        # Store settings\n        self.address = address\n        self.init_kwargs = init_kwargs.copy() if init_kwargs else {}\n\n        self.init_kwargs.setdefault(\"namespace\", \"prefect\")\n\n        # Runtime attributes\n        self._ray_refs: Dict[str, \"ray.ObjectRef\"] = {}\n\n        super().__init__()\n\n    def duplicate(self):\n        \"\"\"\n        Return a new instance of with the same settings as this one.\n        \"\"\"\n        return type(self)(address=self.address, init_kwargs=self.init_kwargs)\n\n    def __eq__(self, other: object) -&gt; bool:\n        \"\"\"\n        Check if an instance has the same settings as this task runner.\n        \"\"\"\n        if type(self) == type(other):\n            return (\n                self.address == other.address and self.init_kwargs == other.init_kwargs\n            )\n        else:\n            return NotImplemented\n\n    @property\n    def concurrency_type(self) -&gt; TaskConcurrencyType:\n        return TaskConcurrencyType.PARALLEL\n\n    async def submit(\n        self,\n        key: UUID,\n        call: Callable[..., Awaitable[State[R]]],\n    ) -&gt; None:\n        if not self._started:\n            raise RuntimeError(\n                \"The task runner must be started before submitting work.\"\n            )\n\n        call_kwargs, upstream_ray_obj_refs = self._exchange_prefect_for_ray_futures(\n            call.keywords\n        )\n\n        remote_options = RemoteOptionsContext.get().current_remote_options\n        # Ray does not support the submission of async functions and we must create a\n        # sync entrypoint\n        if remote_options:\n            ray_decorator = ray.remote(**remote_options)\n        else:\n            ray_decorator = ray.remote\n\n        self._ray_refs[key] = (\n            ray_decorator(self._run_prefect_task)\n            .options(name=call.keywords[\"task_run\"].name)\n            .remote(sync_compatible(call.func), *upstream_ray_obj_refs, **call_kwargs)\n        )\n\n    def _exchange_prefect_for_ray_futures(self, kwargs_prefect_futures):\n        \"\"\"Exchanges Prefect futures for Ray futures.\"\"\"\n\n        upstream_ray_obj_refs = []\n\n        def exchange_prefect_for_ray_future(expr):\n            \"\"\"Exchanges Prefect future for Ray future.\"\"\"\n            if isinstance(expr, PrefectFuture):\n                ray_future = self._ray_refs.get(expr.key)\n                if ray_future is not None:\n                    upstream_ray_obj_refs.append(ray_future)\n                    return ray_future\n            return expr\n\n        kwargs_ray_futures = visit_collection(\n            kwargs_prefect_futures,\n            visit_fn=exchange_prefect_for_ray_future,\n            return_data=True,\n        )\n\n        return kwargs_ray_futures, upstream_ray_obj_refs\n\n    @staticmethod\n    def _run_prefect_task(func, *upstream_ray_obj_refs, **kwargs):\n        \"\"\"Resolves Ray futures before calling the actual Prefect task function.\n\n        Passing upstream_ray_obj_refs directly as args enables Ray to wait for\n        upstream tasks before running this remote function.\n        This variable is otherwise unused as the ray object refs are also\n        contained in kwargs.\n        \"\"\"\n\n        def resolve_ray_future(expr):\n            \"\"\"Resolves Ray future.\"\"\"\n            if isinstance(expr, ray.ObjectRef):\n                return ray.get(expr)\n            return expr\n\n        kwargs = visit_collection(kwargs, visit_fn=resolve_ray_future, return_data=True)\n\n        return func(**kwargs)\n\n    async def wait(self, key: UUID, timeout: float = None) -&gt; Optional[State]:\n        ref = self._get_ray_ref(key)\n\n        result = None\n\n        with anyio.move_on_after(timeout):\n            # We await the reference directly instead of using `ray.get` so we can\n            # avoid blocking the event loop\n            try:\n                result = await ref\n            except RayTaskError as exc:\n                # unwrap the original exception that caused task failure, except for\n                # KeyboardInterrupt, which unwraps as TaskCancelledError\n                result = await exception_to_crashed_state(exc.cause)\n            except BaseException as exc:\n                result = await exception_to_crashed_state(exc)\n\n        return result\n\n    async def _start(self, exit_stack: AsyncExitStack):\n        \"\"\"\n        Start the task runner and prep for context exit.\n\n        - Creates a cluster if an external address is not set.\n        - Creates a client to connect to the cluster.\n        - Pushes a call to wait for all running futures to complete on exit.\n        \"\"\"\n        if self.address and self.address != \"auto\":\n            self.logger.info(\n                f\"Connecting to an existing Ray instance at {self.address}\"\n            )\n            init_args = (self.address,)\n        elif ray.is_initialized():\n            self.logger.info(\n                \"Local Ray instance is already initialized. \"\n                \"Using existing local instance.\"\n            )\n            return\n        else:\n            self.logger.info(\"Creating a local Ray instance\")\n            init_args = ()\n\n        context = ray.init(*init_args, **self.init_kwargs)\n        dashboard_url = getattr(context, \"dashboard_url\", None)\n        exit_stack.push(context)\n\n        # Display some information about the cluster\n        nodes = ray.nodes()\n        living_nodes = [node for node in nodes if node.get(\"alive\")]\n        self.logger.info(f\"Using Ray cluster with {len(living_nodes)} nodes.\")\n\n        if dashboard_url:\n            self.logger.info(\n                f\"The Ray UI is available at {dashboard_url}\",\n            )\n\n    async def _shutdown_ray(self):\n        \"\"\"\n        Shuts down the cluster.\n        \"\"\"\n        self.logger.debug(\"Shutting down Ray cluster...\")\n        ray.shutdown()\n\n    def _get_ray_ref(self, key: UUID) -&gt; \"ray.ObjectRef\":\n        \"\"\"\n        Retrieve the ray object reference corresponding to a prefect future.\n        \"\"\"\n        return self._ray_refs[key]\n</code></pre>"},{"location":"integrations/prefect-ray/task-runners/#prefect_ray.task_runners.RayTaskRunner.duplicate","title":"<code>duplicate</code>","text":"<p>Return a new instance of with the same settings as this one.</p> Source code in <code>prefect_ray/task_runners.py</code> <pre><code>def duplicate(self):\n    \"\"\"\n    Return a new instance of with the same settings as this one.\n    \"\"\"\n    return type(self)(address=self.address, init_kwargs=self.init_kwargs)\n</code></pre>"},{"location":"integrations/prefect-shell/","title":"prefect-shell","text":"<p>Execute shell commands from within Prefect flows.</p>"},{"location":"integrations/prefect-shell/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-shell/#prerequisites","title":"Prerequisites","text":"<ul> <li>Prefect installed.</li> </ul>"},{"location":"integrations/prefect-shell/#install-prefect-shell","title":"Install <code>prefect-shell</code>","text":"<pre><code>pip install -U prefect-shell\n</code></pre>"},{"location":"integrations/prefect-shell/#register-newly-installed-block-types","title":"Register newly installed block types","text":"<p>Register the block types in the prefect-aws module to make them available for use.</p> <pre><code>prefect block register -m prefect_shell\n</code></pre>"},{"location":"integrations/prefect-shell/#examples","title":"Examples","text":""},{"location":"integrations/prefect-shell/#integrate-shell-commands-with-prefect-flows","title":"Integrate shell commands with Prefect flows","text":"<p>With prefect-shell, you can use shell commands (and/or scripts) in Prefect flows to provide observability and resiliency. Prefect-shell can be a useful tool if you're transitioning your orchestration from shell scripts to Prefect.</p> <p>Let's get the shell-abration started!</p> <p>The Python code below has shell commands embedded in a Prefect flow:</p> <pre><code>from prefect import flow\nfrom datetime import datetime\nfrom prefect_shell import ShellOperation\n\n\n@flow\ndef download_data():\n    today = datetime.today().strftime(\"%Y%m%d\")\n\n    # for short running operations, you can use the `run` method\n    # which automatically manages the context\n    ShellOperation(\n        commands=[\n            \"mkdir -p data\",\n            \"mkdir -p data/${today}\"\n        ],\n        env={\"today\": today}\n    ).run()\n\n    # for long running operations, you can use a context manager\n    with ShellOperation(\n        commands=[\n            \"curl -O https://masie_web.apps.nsidc.org/pub/DATASETS/NOAA/G02135/north/daily/data/N_seaice_extent_daily_v3.0.csv\",\n        ],\n        working_dir=f\"data/{today}\",\n    ) as download_csv_operation:\n\n        # trigger runs the process in the background\n        download_csv_process = download_csv_operation.trigger()\n\n        # then do other things here in the meantime, like download another file\n        ...\n\n        # when you're ready, wait for the process to finish\n        download_csv_process.wait_for_completion()\n\n        # if you'd like to get the output lines, you can use the `fetch_result` method\n        output_lines = download_csv_process.fetch_result()\n\n\nif __name__ == \"__main__\":\n    download_data()\n</code></pre> <p>Running this script results in output like this:</p> <pre><code>14:48:16.550 | INFO    | prefect.engine - Created flow run 'tentacled-chachalaca' for flow 'download-data'\n14:48:17.977 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 triggered with 2 commands running inside the '.' directory.\n14:48:17.987 | INFO    | Flow run 'tentacled-chachalaca' - PID 19360 completed with return code 0.\n14:48:17.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 triggered with 1 commands running inside the PosixPath('data/20230201') directory.\n14:48:18.009 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                 Dl\n14:48:18.010 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\noad  Upload   Total   Spent    Left  Speed\n  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n14:48:18.840 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n 11 1630k   11  192k    0     0   229k      0  0:00:07 --:--:--  0:00:07  231k\n14:48:19.839 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n 83 1630k   83 1368k    0     0   745k      0  0:00:02  0:00:01  0:00:01  747k\n14:48:19.993 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n100 1630k  100 1630k    0     0   819k      0  0\n14:48:19.994 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 stream output:\n:00:01  0:00:01 --:--:--  821k\n14:48:19.996 | INFO    | Flow run 'tentacled-chachalaca' - PID 19363 completed with return code 0.\n14:48:19.998 | INFO    | Flow run 'tentacled-chachalaca' - Successfully closed all open processes.\n14:48:20.203 | INFO    | Flow run 'tentacled-chachalaca' - Finished in state Completed()\n</code></pre>"},{"location":"integrations/prefect-shell/#save-shell-commands-in-prefect-blocks","title":"Save shell commands in Prefect Blocks","text":"<p>You can save commands within a <code>ShellOperation</code> block, then reuse them across multiple flows.</p> <p>Save the block with desired commands:</p> <pre><code>from prefect_shell import ShellOperation\n\n\nping_op = ShellOperation(commands=[\"ping -t 1 prefect.io\"])\nping_op.save(\"block-name\")\n\n# Load the saved block:\nping_op = ShellOperation.load(\"block-name\")\n</code></pre>"},{"location":"integrations/prefect-shell/#resources","title":"Resources","text":"<p>Refer to the prefect-shell API documentation linked in the sidebar to explore all the capabilities of the prefect-shell library.</p>"},{"location":"integrations/prefect-shell/commands/","title":"Commands","text":""},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands","title":"<code>prefect_shell.commands</code>","text":"<p>Tasks for interacting with shell commands</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation","title":"<code>ShellOperation</code>","text":"<p>               Bases: <code>JobBlock</code></p> <p>A block representing a shell operation, containing multiple commands.</p> <p>For long-lasting operations, use the trigger method and utilize the block as a context manager for automatic closure of processes when context is exited. If not, manually call the close method to close processes.</p> <p>For short-lasting operations, use the run method. Context is automatically managed with this method.</p> <p>Attributes:</p> Name Type Description <code>commands</code> <code>List[str]</code> <p>A list of commands to execute sequentially.</p> <code>stream_output</code> <code>bool</code> <p>Whether to stream output.</p> <code>env</code> <code>Dict[str, str]</code> <p>A dictionary of environment variables to set for the shell operation.</p> <code>working_dir</code> <code>DirectoryPath</code> <p>The working directory context the commands will be executed within.</p> <code>shell</code> <code>str</code> <p>The shell to use to execute the commands.</p> <code>extension</code> <code>Optional[str]</code> <p>The extension to use for the temporary file. if unset defaults to <code>.ps1</code> on Windows and <code>.sh</code> on other platforms.</p> <p>Examples:</p> <p>Load a configured block: <pre><code>from prefect_shell import ShellOperation\n\nshell_operation = ShellOperation.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>class ShellOperation(JobBlock):\n    \"\"\"\n    A block representing a shell operation, containing multiple commands.\n\n    For long-lasting operations, use the trigger method and utilize the block as a\n    context manager for automatic closure of processes when context is exited.\n    If not, manually call the close method to close processes.\n\n    For short-lasting operations, use the run method. Context is automatically managed\n    with this method.\n\n    Attributes:\n        commands: A list of commands to execute sequentially.\n        stream_output: Whether to stream output.\n        env: A dictionary of environment variables to set for the shell operation.\n        working_dir: The working directory context the commands\n            will be executed within.\n        shell: The shell to use to execute the commands.\n        extension: The extension to use for the temporary file.\n            if unset defaults to `.ps1` on Windows and `.sh` on other platforms.\n\n    Examples:\n        Load a configured block:\n        ```python\n        from prefect_shell import ShellOperation\n\n        shell_operation = ShellOperation.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Shell Operation\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/0b47a017e1b40381de770c17647c49cdf6388d1c-250x250.png\"  # noqa: E501\n    _documentation_url = \"https://prefecthq.github.io/prefect-shell/commands/#prefect_shell.commands.ShellOperation\"  # noqa: E501\n\n    commands: List[str] = Field(\n        default=..., description=\"A list of commands to execute sequentially.\"\n    )\n    stream_output: bool = Field(default=True, description=\"Whether to stream output.\")\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        title=\"Environment Variables\",\n        description=\"Environment variables to use for the subprocess.\",\n    )\n    working_dir: DirectoryPath = Field(\n        default=None,\n        title=\"Working Directory\",\n        description=(\n            \"The absolute path to the working directory \"\n            \"the command will be executed within.\"\n        ),\n    )\n    shell: str = Field(\n        default=None,\n        description=(\n            \"The shell to run the command with; if unset, \"\n            \"defaults to `powershell` on Windows and `bash` on other platforms.\"\n        ),\n    )\n    extension: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The extension to use for the temporary file; if unset, \"\n            \"defaults to `.ps1` on Windows and `.sh` on other platforms.\"\n        ),\n    )\n\n    _exit_stack: AsyncExitStack = PrivateAttr(\n        default_factory=AsyncExitStack,\n    )\n\n    @contextmanager\n    def _prep_trigger_command(self) -&gt; Generator[str, None, None]:\n        \"\"\"\n        Write the commands to a temporary file, handling all the details of\n        creating the file and cleaning it up afterwards. Then, return the command\n        to run the temporary file.\n        \"\"\"\n        try:\n            extension = self.extension or (\".ps1\" if sys.platform == \"win32\" else \".sh\")\n            temp_file = tempfile.NamedTemporaryFile(\n                prefix=\"prefect-\",\n                suffix=extension,\n                delete=False,\n            )\n\n            joined_commands = os.linesep.join(self.commands)\n            self.logger.debug(\n                f\"Writing the following commands to \"\n                f\"{temp_file.name!r}:{os.linesep}{joined_commands}\"\n            )\n            temp_file.write(joined_commands.encode())\n\n            if self.shell is None and sys.platform == \"win32\" or extension == \".ps1\":\n                shell = \"powershell\"\n            elif self.shell is None:\n                shell = \"bash\"\n            else:\n                shell = self.shell.lower()\n\n            if shell == \"powershell\":\n                # if powershell, set exit code to that of command\n                temp_file.write(\"\\r\\nExit $LastExitCode\".encode())\n            temp_file.close()\n\n            trigger_command = [shell, temp_file.name]\n            yield trigger_command\n        finally:\n            if os.path.exists(temp_file.name):\n                os.remove(temp_file.name)\n\n    def _compile_kwargs(self, **open_kwargs: Dict[str, Any]) -&gt; Dict[str, Any]:\n        \"\"\"\n        Helper method to compile the kwargs for `open_process` so it's not repeated\n        across the run and trigger methods.\n        \"\"\"\n        trigger_command = self._exit_stack.enter_context(self._prep_trigger_command())\n        input_env = os.environ.copy()\n        input_env.update(self.env)\n        input_open_kwargs = dict(\n            command=trigger_command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.PIPE,\n            env=input_env,\n            cwd=self.working_dir,\n            **open_kwargs,\n        )\n        return input_open_kwargs\n\n    @sync_compatible\n    async def trigger(self, **open_kwargs: Dict[str, Any]) -&gt; ShellProcess:\n        \"\"\"\n        Triggers a shell command and returns the shell command run object\n        to track the execution of the run. This method is ideal for long-lasting\n        shell commands; for short-lasting shell commands, it is recommended\n        to use the `run` method instead.\n\n        Args:\n            **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n        Returns:\n            A `ShellProcess` object.\n\n        Examples:\n            Sleep for 5 seconds and then print \"Hello, world!\":\n            ```python\n            from prefect_shell import ShellOperation\n\n            with ShellOperation(\n                commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n            ) as shell_operation:\n                shell_process = shell_operation.trigger()\n                shell_process.wait_for_completion()\n                shell_output = shell_process.fetch_result()\n            ```\n        \"\"\"\n        input_open_kwargs = self._compile_kwargs(**open_kwargs)\n        process = await self._exit_stack.enter_async_context(\n            open_process(**input_open_kwargs)\n        )\n        num_commands = len(self.commands)\n        self.logger.info(\n            f\"PID {process.pid} triggered with {num_commands} commands running \"\n            f\"inside the {(self.working_dir or '.')!r} directory.\"\n        )\n        return ShellProcess(shell_operation=self, process=process)\n\n    @sync_compatible\n    async def run(self, **open_kwargs: Dict[str, Any]) -&gt; List[str]:\n        \"\"\"\n        Runs a shell command, but unlike the trigger method,\n        additionally waits and fetches the result directly, automatically managing\n        the context. This method is ideal for short-lasting shell commands;\n        for long-lasting shell commands, it is\n        recommended to use the `trigger` method instead.\n\n        Args:\n            **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n        Returns:\n            The lines output from the shell command as a list.\n\n        Examples:\n            Sleep for 5 seconds and then print \"Hello, world!\":\n            ```python\n            from prefect_shell import ShellOperation\n\n            shell_output = ShellOperation(\n                commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n            ).run()\n            ```\n        \"\"\"\n        input_open_kwargs = self._compile_kwargs(**open_kwargs)\n        async with open_process(**input_open_kwargs) as process:\n            shell_process = ShellProcess(shell_operation=self, process=process)\n            num_commands = len(self.commands)\n            self.logger.info(\n                f\"PID {process.pid} triggered with {num_commands} commands running \"\n                f\"inside the {(self.working_dir or '.')!r} directory.\"\n            )\n            await shell_process.wait_for_completion()\n            result = await shell_process.fetch_result()\n\n        return result\n\n    @sync_compatible\n    async def close(self):\n        \"\"\"\n        Close the job block.\n        \"\"\"\n        await self._exit_stack.aclose()\n        self.logger.info(\"Successfully closed all open processes.\")\n\n    async def aclose(self):\n        \"\"\"\n        Asynchronous version of the close method.\n        \"\"\"\n        await self.close()\n\n    async def __aenter__(self) -&gt; \"ShellOperation\":\n        \"\"\"\n        Asynchronous version of the enter method.\n        \"\"\"\n        return self\n\n    async def __aexit__(self, *exc_info):\n        \"\"\"\n        Asynchronous version of the exit method.\n        \"\"\"\n        await self.close()\n\n    def __enter__(self) -&gt; \"ShellOperation\":\n        \"\"\"\n        Enter the context of the job block.\n        \"\"\"\n        return self\n\n    def __exit__(self, *exc_info):\n        \"\"\"\n        Exit the context of the job block.\n        \"\"\"\n        self.close()\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.aclose","title":"<code>aclose</code>  <code>async</code>","text":"<p>Asynchronous version of the close method.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>async def aclose(self):\n    \"\"\"\n    Asynchronous version of the close method.\n    \"\"\"\n    await self.close()\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.close","title":"<code>close</code>  <code>async</code>","text":"<p>Close the job block.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def close(self):\n    \"\"\"\n    Close the job block.\n    \"\"\"\n    await self._exit_stack.aclose()\n    self.logger.info(\"Successfully closed all open processes.\")\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.run","title":"<code>run</code>  <code>async</code>","text":"<p>Runs a shell command, but unlike the trigger method, additionally waits and fetches the result directly, automatically managing the context. This method is ideal for short-lasting shell commands; for long-lasting shell commands, it is recommended to use the <code>trigger</code> method instead.</p> <p>Parameters:</p> Name Type Description Default <code>**open_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>open_process</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[str]</code> <p>The lines output from the shell command as a list.</p> <p>Examples:</p> <p>Sleep for 5 seconds and then print \"Hello, world!\": <pre><code>from prefect_shell import ShellOperation\n\nshell_output = ShellOperation(\n    commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n).run()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def run(self, **open_kwargs: Dict[str, Any]) -&gt; List[str]:\n    \"\"\"\n    Runs a shell command, but unlike the trigger method,\n    additionally waits and fetches the result directly, automatically managing\n    the context. This method is ideal for short-lasting shell commands;\n    for long-lasting shell commands, it is\n    recommended to use the `trigger` method instead.\n\n    Args:\n        **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n    Returns:\n        The lines output from the shell command as a list.\n\n    Examples:\n        Sleep for 5 seconds and then print \"Hello, world!\":\n        ```python\n        from prefect_shell import ShellOperation\n\n        shell_output = ShellOperation(\n            commands=[\"sleep 5\", \"echo 'Hello, world!'\"]\n        ).run()\n        ```\n    \"\"\"\n    input_open_kwargs = self._compile_kwargs(**open_kwargs)\n    async with open_process(**input_open_kwargs) as process:\n        shell_process = ShellProcess(shell_operation=self, process=process)\n        num_commands = len(self.commands)\n        self.logger.info(\n            f\"PID {process.pid} triggered with {num_commands} commands running \"\n            f\"inside the {(self.working_dir or '.')!r} directory.\"\n        )\n        await shell_process.wait_for_completion()\n        result = await shell_process.fetch_result()\n\n    return result\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellOperation.trigger","title":"<code>trigger</code>  <code>async</code>","text":"<p>Triggers a shell command and returns the shell command run object to track the execution of the run. This method is ideal for long-lasting shell commands; for short-lasting shell commands, it is recommended to use the <code>run</code> method instead.</p> <p>Parameters:</p> Name Type Description Default <code>**open_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to <code>open_process</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>ShellProcess</code> <p>A <code>ShellProcess</code> object.</p> <p>Examples:</p> <p>Sleep for 5 seconds and then print \"Hello, world!\": <pre><code>from prefect_shell import ShellOperation\n\nwith ShellOperation(\n    commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n) as shell_operation:\n    shell_process = shell_operation.trigger()\n    shell_process.wait_for_completion()\n    shell_output = shell_process.fetch_result()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def trigger(self, **open_kwargs: Dict[str, Any]) -&gt; ShellProcess:\n    \"\"\"\n    Triggers a shell command and returns the shell command run object\n    to track the execution of the run. This method is ideal for long-lasting\n    shell commands; for short-lasting shell commands, it is recommended\n    to use the `run` method instead.\n\n    Args:\n        **open_kwargs: Additional keyword arguments to pass to `open_process`.\n\n    Returns:\n        A `ShellProcess` object.\n\n    Examples:\n        Sleep for 5 seconds and then print \"Hello, world!\":\n        ```python\n        from prefect_shell import ShellOperation\n\n        with ShellOperation(\n            commands=[\"sleep 5\", \"echo 'Hello, world!'\"],\n        ) as shell_operation:\n            shell_process = shell_operation.trigger()\n            shell_process.wait_for_completion()\n            shell_output = shell_process.fetch_result()\n        ```\n    \"\"\"\n    input_open_kwargs = self._compile_kwargs(**open_kwargs)\n    process = await self._exit_stack.enter_async_context(\n        open_process(**input_open_kwargs)\n    )\n    num_commands = len(self.commands)\n    self.logger.info(\n        f\"PID {process.pid} triggered with {num_commands} commands running \"\n        f\"inside the {(self.working_dir or '.')!r} directory.\"\n    )\n    return ShellProcess(shell_operation=self, process=process)\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess","title":"<code>ShellProcess</code>","text":"<p>               Bases: <code>JobRun</code></p> <p>A class representing a shell process.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>class ShellProcess(JobRun):\n    \"\"\"\n    A class representing a shell process.\n    \"\"\"\n\n    def __init__(self, shell_operation: \"ShellOperation\", process: Process):\n        self._shell_operation = shell_operation\n        self._process = process\n        self._output = []\n\n    @property\n    def pid(self) -&gt; int:\n        \"\"\"\n        The PID of the process.\n\n        Returns:\n            The PID of the process.\n        \"\"\"\n        return self._process.pid\n\n    @property\n    def return_code(self) -&gt; Optional[int]:\n        \"\"\"\n        The return code of the process.\n\n        Returns:\n            The return code of the process, or `None` if the process is still running.\n        \"\"\"\n        return self._process.returncode\n\n    async def _capture_output(self, source):\n        \"\"\"\n        Capture output from source.\n        \"\"\"\n        async for output in TextReceiveStream(source):\n            text = output.rstrip()\n            if self._shell_operation.stream_output:\n                self.logger.info(f\"PID {self.pid} stream output:{os.linesep}{text}\")\n            self._output.extend(text.split(os.linesep))\n\n    @sync_compatible\n    async def wait_for_completion(self) -&gt; None:\n        \"\"\"\n        Wait for the shell command to complete after a process is triggered.\n        \"\"\"\n        self.logger.debug(f\"Waiting for PID {self.pid} to complete.\")\n\n        await asyncio.gather(\n            self._capture_output(self._process.stdout),\n            self._capture_output(self._process.stderr),\n        )\n        await self._process.wait()\n\n        if self.return_code != 0:\n            raise RuntimeError(\n                f\"PID {self.pid} failed with return code {self.return_code}.\"\n            )\n        self.logger.info(\n            f\"PID {self.pid} completed with return code {self.return_code}.\"\n        )\n\n    @sync_compatible\n    async def fetch_result(self) -&gt; List[str]:\n        \"\"\"\n        Retrieve the output of the shell operation.\n\n        Returns:\n            The lines output from the shell operation as a list.\n        \"\"\"\n        if self._process.returncode is None:\n            self.logger.info(\"Process is still running, result may be incomplete.\")\n        return self._output\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.pid","title":"<code>pid: int</code>  <code>property</code>","text":"<p>The PID of the process.</p> <p>Returns:</p> Type Description <code>int</code> <p>The PID of the process.</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.return_code","title":"<code>return_code: Optional[int]</code>  <code>property</code>","text":"<p>The return code of the process.</p> <p>Returns:</p> Type Description <code>Optional[int]</code> <p>The return code of the process, or <code>None</code> if the process is still running.</p>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.fetch_result","title":"<code>fetch_result</code>  <code>async</code>","text":"<p>Retrieve the output of the shell operation.</p> <p>Returns:</p> Type Description <code>List[str]</code> <p>The lines output from the shell operation as a list.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def fetch_result(self) -&gt; List[str]:\n    \"\"\"\n    Retrieve the output of the shell operation.\n\n    Returns:\n        The lines output from the shell operation as a list.\n    \"\"\"\n    if self._process.returncode is None:\n        self.logger.info(\"Process is still running, result may be incomplete.\")\n    return self._output\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.ShellProcess.wait_for_completion","title":"<code>wait_for_completion</code>  <code>async</code>","text":"<p>Wait for the shell command to complete after a process is triggered.</p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@sync_compatible\nasync def wait_for_completion(self) -&gt; None:\n    \"\"\"\n    Wait for the shell command to complete after a process is triggered.\n    \"\"\"\n    self.logger.debug(f\"Waiting for PID {self.pid} to complete.\")\n\n    await asyncio.gather(\n        self._capture_output(self._process.stdout),\n        self._capture_output(self._process.stderr),\n    )\n    await self._process.wait()\n\n    if self.return_code != 0:\n        raise RuntimeError(\n            f\"PID {self.pid} failed with return code {self.return_code}.\"\n        )\n    self.logger.info(\n        f\"PID {self.pid} completed with return code {self.return_code}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-shell/commands/#prefect_shell.commands.shell_run_command","title":"<code>shell_run_command</code>  <code>async</code>","text":"<p>Runs arbitrary shell commands.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>str</code> <p>Shell command to be executed; can also be provided post-initialization by calling this task instance.</p> required <code>env</code> <code>Optional[dict]</code> <p>Dictionary of environment variables to use for the subprocess; can also be provided at runtime.</p> <code>None</code> <code>helper_command</code> <code>Optional[str]</code> <p>String representing a shell command, which will be executed prior to the <code>command</code> in the same process. Can be used to change directories, define helper functions, etc. for different commands in a flow.</p> <code>None</code> <code>shell</code> <code>Optional[str]</code> <p>Shell to run the command with.</p> <code>None</code> <code>extension</code> <code>Optional[str]</code> <p>File extension to be appended to the command to be executed.</p> <code>None</code> <code>return_all</code> <code>bool</code> <p>Whether this task should return all lines of stdout as a list, or just the last line as a string.</p> <code>False</code> <code>stream_level</code> <code>int</code> <p>The logging level of the stream; defaults to 20 equivalent to <code>logging.INFO</code>.</p> <code>INFO</code> <code>cwd</code> <code>Union[str, bytes, PathLike, None]</code> <p>The working directory context the command will be executed within</p> <code>None</code> <p>Returns:</p> Type Description <code>Union[List, str]</code> <p>If return all, returns all lines as a list; else the last line as a string.</p> Example <p>List contents in the current directory. <pre><code>from prefect import flow\nfrom prefect_shell import shell_run_command\n\n@flow\ndef example_shell_run_command_flow():\n    return shell_run_command(command=\"ls .\", return_all=True)\n\nexample_shell_run_command_flow()\n</code></pre></p> Source code in <code>prefect_shell/commands.py</code> <pre><code>@task\nasync def shell_run_command(\n    command: str,\n    env: Optional[dict] = None,\n    helper_command: Optional[str] = None,\n    shell: Optional[str] = None,\n    extension: Optional[str] = None,\n    return_all: bool = False,\n    stream_level: int = logging.INFO,\n    cwd: Union[str, bytes, os.PathLike, None] = None,\n) -&gt; Union[List, str]:\n    \"\"\"\n    Runs arbitrary shell commands.\n\n    Args:\n        command: Shell command to be executed; can also be\n            provided post-initialization by calling this task instance.\n        env: Dictionary of environment variables to use for\n            the subprocess; can also be provided at runtime.\n        helper_command: String representing a shell command, which\n            will be executed prior to the `command` in the same process.\n            Can be used to change directories, define helper functions, etc.\n            for different commands in a flow.\n        shell: Shell to run the command with.\n        extension: File extension to be appended to the command to be executed.\n        return_all: Whether this task should return all lines of stdout as a list,\n            or just the last line as a string.\n        stream_level: The logging level of the stream;\n            defaults to 20 equivalent to `logging.INFO`.\n        cwd: The working directory context the command will be executed within\n\n    Returns:\n        If return all, returns all lines as a list; else the last line as a string.\n\n    Example:\n        List contents in the current directory.\n        ```python\n        from prefect import flow\n        from prefect_shell import shell_run_command\n\n        @flow\n        def example_shell_run_command_flow():\n            return shell_run_command(command=\"ls .\", return_all=True)\n\n        example_shell_run_command_flow()\n        ```\n    \"\"\"\n    logger = get_run_logger()\n\n    current_env = os.environ.copy()\n    current_env.update(env or {})\n\n    if shell is None:\n        # if shell is not specified:\n        # use powershell for windows\n        # use bash for other platforms\n        shell = \"powershell\" if sys.platform == \"win32\" else \"bash\"\n\n    extension = \".ps1\" if shell.lower() == \"powershell\" else extension\n\n    tmp = tempfile.NamedTemporaryFile(prefix=\"prefect-\", suffix=extension, delete=False)\n    try:\n        if helper_command:\n            tmp.write(helper_command.encode())\n            tmp.write(os.linesep.encode())\n        tmp.write(command.encode())\n        if shell.lower() == \"powershell\":\n            # if powershell, set exit code to that of command\n            tmp.write(\"\\r\\nExit $LastExitCode\".encode())\n        tmp.close()\n\n        shell_command = [shell, tmp.name]\n\n        lines = []\n        async with await anyio.open_process(\n            shell_command, env=current_env, cwd=cwd\n        ) as process:\n            async for text in TextReceiveStream(process.stdout):\n                logger.log(level=stream_level, msg=text)\n                lines.extend(text.rstrip().split(\"\\n\"))\n\n            await process.wait()\n            if process.returncode:\n                stderr = \"\\n\".join(\n                    [text async for text in TextReceiveStream(process.stderr)]\n                )\n                if not stderr and lines:\n                    stderr = f\"{lines[-1]}\\n\"\n                msg = (\n                    f\"Command failed with exit code {process.returncode}:\\n\" f\"{stderr}\"\n                )\n                raise RuntimeError(msg)\n    finally:\n        if os.path.exists(tmp.name):\n            os.remove(tmp.name)\n\n    line = lines[-1] if lines else \"\"\n    return lines if return_all else line\n</code></pre>"},{"location":"integrations/prefect-slack/","title":"prefect-slack","text":""},{"location":"integrations/prefect-slack/#welcome","title":"Welcome!","text":"<p><code>prefect-slack</code> is a collection of prebuilt Prefect tasks that can be used to quickly construct Prefect flows.</p>"},{"location":"integrations/prefect-slack/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-slack/#python-setup","title":"Python setup","text":"<p>Requires an installation of Python 3.8+</p> <p>We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.</p> <p>These tasks are designed to work with Prefect 2.0. For more information about how to use Prefect, please refer to the Prefect documentation.</p>"},{"location":"integrations/prefect-slack/#installation","title":"Installation","text":"<p>Install <code>prefect-slack</code></p> <pre><code>pip install prefect-slack\n</code></pre>"},{"location":"integrations/prefect-slack/#slack-setup","title":"Slack setup","text":"<p>In order to use tasks in the collection, you'll first need to create an Slack app and install it in your Slack workspace. You can create a Slack app by navigating to the apps page for your Slack account and selecting 'Create New App'.</p> <p>For tasks that require a Bot user OAuth token, you can get a token for your app by navigating to your apps OAuth &amp; Permissions page.</p> <p>For tasks that require and Webhook URL, you get generate new Webhook URLs by navigating to you apps Incoming Webhooks page.</p> <p>Slack's Basic app setup guide provides additional details on setting up a Slack app.</p>"},{"location":"integrations/prefect-slack/#write-and-run-a-flow","title":"Write and run a flow","text":"<pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_slack import SlackCredentials\nfrom prefect_slack.messages import send_chat_message\n\n\n@flow\ndef example_send_message_flow():\n   context = get_run_context()\n\n   # Run other tasks and subflows here\n\n   token = \"xoxb-your-bot-token-here\"\n   send_chat_message(\n         slack_credentials=SlackCredentials(token),\n         channel=\"#prefect\",\n         text=f\"Flow run {context.flow_run.name} completed :tada:\"\n   )\n\nexample_send_message_flow()\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials","title":"<code>prefect_slack.credentials</code>","text":"<p>Credential classes use to store Slack credentials.</p>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials","title":"<code>SlackCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block holding Slack credentials for use in tasks and flows.</p> <p>Parameters:</p> Name Type Description Default <code>token</code> <p>Bot user OAuth token for the Slack app used to perform actions.</p> required <p>Examples:</p> <p>Load stored Slack credentials: <pre><code>from prefect_slack import SlackCredentials\nslack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Get a Slack client: <pre><code>from prefect_slack import SlackCredentials\nslack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\nclient = slack_credentials_block.get_client()\n</code></pre></p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>class SlackCredentials(Block):\n    \"\"\"\n    Block holding Slack credentials for use in tasks and flows.\n\n    Args:\n        token: Bot user OAuth token for the Slack app used to perform actions.\n\n    Examples:\n        Load stored Slack credentials:\n        ```python\n        from prefect_slack import SlackCredentials\n        slack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n        ```\n\n        Get a Slack client:\n        ```python\n        from prefect_slack import SlackCredentials\n        slack_credentials_block = SlackCredentials.load(\"BLOCK_NAME\")\n        client = slack_credentials_block.get_client()\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Slack Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/c1965ecbf8704ee1ea20d77786de9a41ce1087d1-500x500.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials\"  # noqa\n\n    token: SecretStr = Field(\n        default=...,\n        description=\"Bot user OAuth token for the Slack app used to perform actions.\",\n    )\n\n    def get_client(self) -&gt; AsyncWebClient:\n        \"\"\"\n        Returns an authenticated `AsyncWebClient` to interact with the Slack API.\n        \"\"\"\n        return AsyncWebClient(token=self.token.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated <code>AsyncWebClient</code> to interact with the Slack API.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncWebClient:\n    \"\"\"\n    Returns an authenticated `AsyncWebClient` to interact with the Slack API.\n    \"\"\"\n    return AsyncWebClient(token=self.token.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook","title":"<code>SlackWebhook</code>","text":"<p>               Bases: <code>NotificationBlock</code></p> <p>Block holding a Slack webhook for use in tasks and flows.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <p>Slack webhook URL which can be used to send messages (e.g. <code>https://hooks.slack.com/XXX</code>).</p> required <p>Examples:</p> <p>Load stored Slack webhook: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Get a Slack webhook client: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nclient = slack_webhook_block.get_client()\n</code></pre></p> <p>Send a notification in Slack: <pre><code>from prefect_slack import SlackWebhook\nslack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\nslack_webhook_block.notify(\"Hello, world!\")\n</code></pre></p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>class SlackWebhook(NotificationBlock):\n    \"\"\"\n    Block holding a Slack webhook for use in tasks and flows.\n\n    Args:\n        url: Slack webhook URL which can be used to send messages\n            (e.g. `https://hooks.slack.com/XXX`).\n\n    Examples:\n        Load stored Slack webhook:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        ```\n\n        Get a Slack webhook client:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        client = slack_webhook_block.get_client()\n        ```\n\n        Send a notification in Slack:\n        ```python\n        from prefect_slack import SlackWebhook\n        slack_webhook_block = SlackWebhook.load(\"BLOCK_NAME\")\n        slack_webhook_block.notify(\"Hello, world!\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Slack Incoming Webhook\"\n    _logo_url = \"https://images.ctfassets.net/gm98wzqotmnx/7dkzINU9r6j44giEFuHuUC/85d4cd321ad60c1b1e898bc3fbd28580/5cb480cd5f1b6d3fbadece79.png?h=250\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook\"  # noqa\n\n    url: SecretStr = Field(\n        default=...,\n        title=\"Webhook URL\",\n        description=\"Slack webhook URL which can be used to send messages.\",\n        example=\"https://hooks.slack.com/XXX\",\n    )\n\n    def get_client(self) -&gt; AsyncWebhookClient:\n        \"\"\"\n        Returns an authenticated `AsyncWebhookClient` to interact with the configured\n        Slack webhook.\n        \"\"\"\n        return AsyncWebhookClient(url=self.url.get_secret_value())\n\n    @sync_compatible\n    async def notify(self, body: str, subject: Optional[str] = None):\n        \"\"\"\n        Sends a message to the Slack channel.\n        \"\"\"\n        client = self.get_client()\n\n        response = await client.send(text=body)\n\n        # prefect&gt;=2.17.2 added a means for notification blocks to raise errors on\n        # failures. This is not available in older versions, so we need to check if the\n        # private base class attribute exists before using it.\n        if getattr(self, \"_raise_on_failure\", False):  # pragma: no cover\n            try:\n                from prefect.blocks.abstract import NotificationError\n            except ImportError:\n                NotificationError = Exception\n\n            if response.status_code &gt;= 400:\n                raise NotificationError(f\"Failed to send message: {response.body}\")\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated <code>AsyncWebhookClient</code> to interact with the configured Slack webhook.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>def get_client(self) -&gt; AsyncWebhookClient:\n    \"\"\"\n    Returns an authenticated `AsyncWebhookClient` to interact with the configured\n    Slack webhook.\n    \"\"\"\n    return AsyncWebhookClient(url=self.url.get_secret_value())\n</code></pre>"},{"location":"integrations/prefect-slack/credentials/#prefect_slack.credentials.SlackWebhook.notify","title":"<code>notify</code>  <code>async</code>","text":"<p>Sends a message to the Slack channel.</p> Source code in <code>prefect_slack/credentials.py</code> <pre><code>@sync_compatible\nasync def notify(self, body: str, subject: Optional[str] = None):\n    \"\"\"\n    Sends a message to the Slack channel.\n    \"\"\"\n    client = self.get_client()\n\n    response = await client.send(text=body)\n\n    # prefect&gt;=2.17.2 added a means for notification blocks to raise errors on\n    # failures. This is not available in older versions, so we need to check if the\n    # private base class attribute exists before using it.\n    if getattr(self, \"_raise_on_failure\", False):  # pragma: no cover\n        try:\n            from prefect.blocks.abstract import NotificationError\n        except ImportError:\n            NotificationError = Exception\n\n        if response.status_code &gt;= 400:\n            raise NotificationError(f\"Failed to send message: {response.body}\")\n</code></pre>"},{"location":"integrations/prefect-slack/messages/","title":"Messages","text":""},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages","title":"<code>prefect_slack.messages</code>","text":"<p>Tasks for sending Slack messages.</p>"},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages.send_chat_message","title":"<code>send_chat_message</code>  <code>async</code>","text":"<p>Sends a message to a Slack channel.</p> <p>Parameters:</p> Name Type Description Default <code>channel</code> <code>str</code> <p>The name of the channel in which to post the chat message (e.g. #general).</p> required <code>slack_credentials</code> <code>SlackCredentials</code> <p>Instance of <code>SlackCredentials</code> initialized with a Slack bot token.</p> required <code>text</code> <code>Optional[str]</code> <p>Contents of the message. It's a best practice to always provide a <code>text</code> argument when posting a message. The <code>text</code> argument is used in places where content cannot be rendered such as: system push notifications, assistive technology such as screen readers, etc.</p> <code>None</code> <code>attachments</code> <code>Optional[Sequence[Union[Dict, Attachment]]]</code> <p>List of objects defining secondary context in the posted Slack message. The Slack API docs provide guidance on building attachments.</p> <code>None</code> <code>slack_blocks</code> <code>Optional[Sequence[Union[Dict, Block]]]</code> <p>List of objects defining the layout and formatting of the posted message. The Slack API docs provide guidance on building messages with blocks.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Dict</code> <code>Dict</code> <p>Response from the Slack API. Example response structures can be found in the Slack API docs.</p> Example <p>Post a message at the end of a flow run.</p> <pre><code>from prefect import flow\nfrom prefect.context import get_run_context\nfrom prefect_slack import SlackCredentials\nfrom prefect_slack.messages import send_chat_message\n\n\n@flow\ndef example_send_message_flow():\n    context = get_run_context()\n\n    # Run other tasks and subflows here\n\n    token = \"xoxb-your-bot-token-here\"\n    send_chat_message(\n        slack_credentials=SlackCredentials(token),\n        channel=\"#prefect\",\n        text=f\"Flow run {context.flow_run.name} completed :tada:\"\n    )\n\nexample_send_message_flow()\n</code></pre> Source code in <code>prefect_slack/messages.py</code> <pre><code>@task\nasync def send_chat_message(\n    channel: str,\n    slack_credentials: SlackCredentials,\n    text: Optional[str] = None,\n    attachments: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.attachments.Attachment\"]]\n    ] = None,\n    slack_blocks: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.blocks.Block\"]]\n    ] = None,\n) -&gt; Dict:\n    \"\"\"\n    Sends a message to a Slack channel.\n\n    Args:\n        channel: The name of the channel in which to post the chat message\n            (e.g. #general).\n        slack_credentials: Instance of `SlackCredentials` initialized with a Slack\n            bot token.\n        text: Contents of the message. It's a best practice to always provide a `text`\n            argument when posting a message. The `text` argument is used in places where\n            content cannot be rendered such as: system push notifications, assistive\n            technology such as screen readers, etc.\n        attachments: List of objects defining secondary context in the posted Slack\n            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)\n            provide guidance on building attachments.\n        slack_blocks: List of objects defining the layout and formatting of the posted\n            message. The [Slack API docs](https://api.slack.com/block-kit/building)\n            provide guidance on building messages with blocks.\n\n    Returns:\n        Dict: Response from the Slack API. Example response structures can be found in\n            the [Slack API docs](https://api.slack.com/methods/chat.postMessage#examples).\n\n    Example:\n        Post a message at the end of a flow run.\n\n        ```python\n        from prefect import flow\n        from prefect.context import get_run_context\n        from prefect_slack import SlackCredentials\n        from prefect_slack.messages import send_chat_message\n\n\n        @flow\n        def example_send_message_flow():\n            context = get_run_context()\n\n            # Run other tasks and subflows here\n\n            token = \"xoxb-your-bot-token-here\"\n            send_chat_message(\n                slack_credentials=SlackCredentials(token),\n                channel=\"#prefect\",\n                text=f\"Flow run {context.flow_run.name} completed :tada:\"\n            )\n\n        example_send_message_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Posting chat message to %s\", channel)\n\n    client = slack_credentials.get_client()\n    result = await client.chat_postMessage(\n        channel=channel, text=text, blocks=slack_blocks, attachments=attachments\n    )\n    return result.data\n</code></pre>"},{"location":"integrations/prefect-slack/messages/#prefect_slack.messages.send_incoming_webhook_message","title":"<code>send_incoming_webhook_message</code>  <code>async</code>","text":"<p>Sends a message via an incoming webhook.</p> <p>Parameters:</p> Name Type Description Default <code>slack_webhook</code> <code>SlackWebhook</code> <p>Instance of <code>SlackWebhook</code> initialized with a Slack webhook URL.</p> required <code>text</code> <code>Optional[str]</code> <p>Contents of the message. It's a best practice to always provide a <code>text</code> argument when posting a message. The <code>text</code> argument is used in places where content cannot be rendered such as: system push notifications, assistive technology such as screen readers, etc.</p> <code>None</code> <code>attachments</code> <code>Optional[Sequence[Union[Dict, Attachment]]]</code> <p>List of objects defining secondary context in the posted Slack message. The Slack API docs provide guidance on building attachments.</p> <code>None</code> <code>slack_blocks</code> <code>Optional[Sequence[Union[Dict, Block]]]</code> <p>List of objects defining the layout and formatting of the posted message. The Slack API docs provide guidance on building messages with blocks.</p> <code>None</code> Example <p>Post a message at the end of a flow run.</p> <pre><code>from prefect import flow\nfrom prefect_slack import SlackWebhook\nfrom prefect_slack.messages import send_incoming_webhook_message\n\n\n@flow\ndef example_send_message_flow():\n    # Run other tasks and subflows here\n\n    webhook_url = \"https://hooks.slack.com/XXX\"\n    send_incoming_webhook_message(\n        slack_webhook=SlackWebhook(\n            url=webhook_url\n        ),\n        text=\"Warehouse loading flow completed :sparkles:\"\n    )\n\nexample_send_message_flow()\n</code></pre> Source code in <code>prefect_slack/messages.py</code> <pre><code>@task\nasync def send_incoming_webhook_message(\n    slack_webhook: SlackWebhook,\n    text: Optional[str] = None,\n    attachments: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.attachments.Attachment\"]]\n    ] = None,\n    slack_blocks: Optional[\n        Sequence[Union[Dict, \"slack_sdk.models.blocks.Block\"]]\n    ] = None,\n) -&gt; None:\n    \"\"\"\n    Sends a message via an incoming webhook.\n\n    Args:\n        slack_webhook: Instance of `SlackWebhook` initialized with a Slack\n            webhook URL.\n        text: Contents of the message. It's a best practice to always provide a `text`\n            argument when posting a message. The `text` argument is used in places where\n            content cannot be rendered such as: system push notifications, assistive\n            technology such as screen readers, etc.\n        attachments: List of objects defining secondary context in the posted Slack\n            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)\n            provide guidance on building attachments.\n        slack_blocks: List of objects defining the layout and formatting of the posted\n            message. The [Slack API docs](https://api.slack.com/block-kit/building)\n            provide guidance on building messages with blocks.\n\n    Example:\n        Post a message at the end of a flow run.\n\n        ```python\n        from prefect import flow\n        from prefect_slack import SlackWebhook\n        from prefect_slack.messages import send_incoming_webhook_message\n\n\n        @flow\n        def example_send_message_flow():\n            # Run other tasks and subflows here\n\n            webhook_url = \"https://hooks.slack.com/XXX\"\n            send_incoming_webhook_message(\n                slack_webhook=SlackWebhook(\n                    url=webhook_url\n                ),\n                text=\"Warehouse loading flow completed :sparkles:\"\n            )\n\n        example_send_message_flow()\n        ```\n    \"\"\"  # noqa\n    logger = get_run_logger()\n    logger.info(\"Posting message to provided webhook\")\n\n    client = slack_webhook.get_client()\n    await client.send(text=text, attachments=attachments, blocks=slack_blocks)\n</code></pre>"},{"location":"integrations/prefect-snowflake/","title":"prefect-snowflake","text":""},{"location":"integrations/prefect-snowflake/#welcome","title":"Welcome!","text":"<p>The prefect-snowflake collection makes it easy to connect to a Snowflake database in your Prefect flows. Check out the examples below to get started!</p>"},{"location":"integrations/prefect-snowflake/#getting-started","title":"Getting Started","text":""},{"location":"integrations/prefect-snowflake/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Prefect works with Snowflake by providing dataflow automation for faster, more efficient data pipeline creation, execution, and monitoring.</p> <p>This results in reduced errors, increased confidence in your data, and ultimately, faster insights.</p> <p>To set up a table, use the <code>execute</code> and <code>execute_many</code> methods. Then, use the <code>fetch_many</code> method to retrieve data in a stream until there's no more data.</p> <p>By using the <code>SnowflakeConnector</code> as a context manager, you can make sure that the Snowflake connection and cursors are closed properly after you're done with them.</p> <p>Be sure to install prefect-snowflake, register the blocks, and create a credentials block to run the examples below!</p> SyncAsync <pre><code>from prefect import flow, task\nfrom prefect_snowflake import SnowflakeConnector\n\n\n@task\ndef setup_table(block_name: str) -&gt; None:\n    with SnowflakeConnector.load(block_name) as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n@task\ndef fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with SnowflakeConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\ndef snowflake_flow(block_name: str) -&gt; list:\n    setup_table(block_name)\n    all_rows = fetch_data(block_name)\n    return all_rows\n\n\nif __name__==\"__main__\":\n    snowflake_flow()\n</code></pre> <pre><code>from prefect import flow, task\nfrom prefect_snowflake import SnowflakeConnector\nimport asyncio\n\n@task\nasync def setup_table(block_name: str) -&gt; None:\n    with await SnowflakeConnector.load(block_name) as connector:\n        await connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        await connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Space\"},\n                {\"name\": \"Me\", \"address\": \"Myway 88\"},\n            ],\n        )\n\n@task\nasync def fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with await SnowflakeConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = await connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\nasync def snowflake_flow(block_name: str) -&gt; list:\n    await setup_table(block_name)\n    all_rows = await fetch_data(block_name)\n    return all_rows\n\n\nif __name__==\"__main__\":\n    asyncio.run(snowflake_flow(\"example\"))\n</code></pre>"},{"location":"integrations/prefect-snowflake/#access-underlying-snowflake-connection","title":"Access underlying Snowflake connection","text":"<p>If the native methods of the block don't meet your requirements, don't worry.</p> <p>You have the option to access the underlying Snowflake connection and utilize its built-in methods as well.</p> <pre><code>import pandas as pd\nfrom prefect import flow\nfrom prefect_snowflake.database import SnowflakeConnector\nfrom snowflake.connector.pandas_tools import write_pandas\n\n@flow\ndef snowflake_write_pandas_flow():\n    connector = SnowflakeConnector.load(\"my-block\")\n    with connector.get_connection() as connection:\n        table_name = \"TABLE_NAME\"\n        ddl = \"NAME STRING, NUMBER INT\"\n        statement = f'CREATE TABLE IF NOT EXISTS {table_name} ({ddl})'\n        with connection.cursor() as cursor:\n            cursor.execute(statement)\n\n        # case sensitivity matters here!\n        df = pd.DataFrame([('Marvin', 42), ('Ford', 88)], columns=['NAME', 'NUMBER'])\n        success, num_chunks, num_rows, _ = write_pandas(\n            conn=connection,\n            df=df,\n            table_name=table_name,\n            database=snowflake_connector.database,\n            schema=snowflake_connector.schema_  # note the \"_\" suffix\n        )\n</code></pre>"},{"location":"integrations/prefect-snowflake/#resources","title":"Resources","text":"<p>For more tips on how to use tasks and flows in an integration, check out Using Collections!</p>"},{"location":"integrations/prefect-snowflake/#installation","title":"Installation","text":"<p>Install <code>prefect-snowflake</code> with <code>pip</code>:</p> <pre><code>pip install prefect-snowflake\n</code></pre>"},{"location":"integrations/prefect-snowflake/#registering-blocks","title":"Registering blocks","text":"<p>Register blocks in this module to make them available for use.</p> <pre><code>prefect block register -m prefect_aws\n</code></pre>"},{"location":"integrations/prefect-snowflake/#saving-credentials-to-block","title":"Saving credentials to block","text":"<p>Note, to use the <code>load</code> method on a block, you must already have a block document saved through code or saved through the UI.</p> <p>Below is a walkthrough on saving a <code>SnowflakeCredentials</code> block through code.</p> <ol> <li>Head over to https://app.snowflake.com/.</li> <li>Login to your Snowflake account, e.g. nh12345.us-east-2.aws, with your username and password.</li> <li>Use those credentials to fill replace the placeholders below.</li> </ol> <pre><code>from prefect_snowflake import SnowflakeCredentials\n\ncredentials = SnowflakeCredentials(\n    account=\"ACCOUNT-PLACEHOLDER\",  # resembles nh12345.us-east-2.aws\n    user=\"USER-PLACEHOLDER\",\n    password=\"PASSWORD-PLACEHOLDER\"\n)\ncredentials.save(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Then, to create a <code>SnowflakeConnector</code> block:</p> <ol> <li>After logging in, click on any worksheet.</li> <li>On the left side, select a database and schema.</li> <li>On the top right, select a warehouse.</li> <li>Create a short script, replacing the placeholders below.</li> </ol> <pre><code>from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector\n\ncredentials = SnowflakeCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\n\nconnector = SnowflakeConnector(\n    credentials=credentials,\n    database=\"DATABASE-PLACEHOLDER\",\n    schema=\"SCHEMA-PLACEHOLDER\",\n    warehouse=\"COMPUTE_WH\",\n)\nconnector.save(\"CONNECTOR-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Congrats! You can now easily load the saved block, which holds your credentials and connection info:</p> <pre><code>from prefect_snowflake import SnowflakeCredentials, SnowflakeConnector\n\nSnowflakeCredentials.load(\"CREDENTIALS-BLOCK-NAME-PLACEHOLDER\")\nSnowflakeConnector.load(\"CONNECTOR-BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <p>Registering blocks</p> <p>Register blocks in this module to view and edit them on Prefect Cloud:</p> <pre><code>prefect block register -m prefect_snowflake\n</code></pre> <p>A list of available blocks in <code>prefect-snowflake</code> and their setup instructions can be found here.</p>"},{"location":"integrations/prefect-snowflake/#feedback","title":"Feedback","text":"<p>If you encounter any bugs while using <code>prefect-snowflake</code>, feel free to open an issue in the prefect repository.</p> <p>If you have any questions or issues while using <code>prefect-snowflake</code>, you can find help in the Prefect Slack community.</p>"},{"location":"integrations/prefect-snowflake/#contributing","title":"Contributing","text":"<p>If you'd like to help contribute to fix an issue or add a feature to <code>prefect-snowflake</code>, please propose changes through a pull request from a fork of the Prefect repository.</p>"},{"location":"integrations/prefect-snowflake/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials","title":"<code>prefect_snowflake.credentials</code>","text":"<p>Credentials block for authenticating with Snowflake.</p>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.InvalidPemFormat","title":"<code>InvalidPemFormat</code>","text":"<p>               Bases: <code>Exception</code></p> <p>Invalid PEM Format Certificate</p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>class InvalidPemFormat(Exception):\n    \"\"\"Invalid PEM Format Certificate\"\"\"\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials","title":"<code>SnowflakeCredentials</code>","text":"<p>               Bases: <code>CredentialsBlock</code></p> <p>Block used to manage authentication with Snowflake.</p> <p>Parameters:</p> Name Type Description Default <code>account</code> <code>str</code> <p>The snowflake account name.</p> required <code>user</code> <code>str</code> <p>The user name used to authenticate.</p> required <code>password</code> <code>SecretStr</code> <p>The password used to authenticate.</p> required <code>private_key</code> <code>SecretStr</code> <p>The PEM used to authenticate.</p> required <code>authenticator</code> <code>str</code> <p>The type of authenticator to use for initializing connection (oauth, externalbrowser, etc); refer to Snowflake documentation for details, and note that <code>externalbrowser</code> will only work in an environment where a browser is available.</p> required <code>token</code> <code>SecretStr</code> <p>The OAuth or JWT Token to provide when authenticator is set to OAuth.</p> required <code>endpoint</code> <code>str</code> <p>The Okta endpoint to use when authenticator is set to <code>okta_endpoint</code>, e.g. <code>https://&lt;okta_account_name&gt;.okta.com</code>.</p> required <code>role</code> <code>str</code> <p>The name of the default role to use.</p> required <code>autocommit</code> <code>bool</code> <p>Whether to automatically commit.</p> required Example <p>Load stored Snowflake credentials: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>class SnowflakeCredentials(CredentialsBlock):\n    \"\"\"\n    Block used to manage authentication with Snowflake.\n\n    Args:\n        account (str): The snowflake account name.\n        user (str): The user name used to authenticate.\n        password (SecretStr): The password used to authenticate.\n        private_key (SecretStr): The PEM used to authenticate.\n        authenticator (str): The type of authenticator to use for initializing\n            connection (oauth, externalbrowser, etc); refer to\n            [Snowflake documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect)\n            for details, and note that `externalbrowser` will only\n            work in an environment where a browser is available.\n        token (SecretStr): The OAuth or JWT Token to provide when\n            authenticator is set to OAuth.\n        endpoint (str): The Okta endpoint to use when authenticator is\n            set to `okta_endpoint`, e.g. `https://&lt;okta_account_name&gt;.okta.com`.\n        role (str): The name of the default role to use.\n        autocommit (bool): Whether to automatically commit.\n\n    Example:\n        Load stored Snowflake credentials:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"  # noqa E501\n\n    _block_type_name = \"Snowflake Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/bd359de0b4be76c2254bd329fe3a267a1a3879c2-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials\"  # noqa\n\n    account: str = Field(\n        ..., description=\"The snowflake account name.\", example=\"nh12345.us-east-2.aws\"\n    )\n    user: str = Field(..., description=\"The user name used to authenticate.\")\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    private_key: Optional[SecretBytes] = Field(\n        default=None, description=\"The PEM used to authenticate.\"\n    )\n    private_key_path: Optional[Path] = Field(\n        default=None, description=\"The path to the private key.\"\n    )\n    private_key_passphrase: Optional[SecretStr] = Field(\n        default=None, description=\"The password to use for the private key.\"\n    )\n    authenticator: Literal[\n        \"snowflake\",\n        \"snowflake_jwt\",\n        \"externalbrowser\",\n        \"okta_endpoint\",\n        \"oauth\",\n        \"username_password_mfa\",\n    ] = Field(  # noqa\n        default=\"snowflake\",\n        description=(\"The type of authenticator to use for initializing connection.\"),\n    )\n    token: Optional[SecretStr] = Field(\n        default=None,\n        description=(\n            \"The OAuth or JWT Token to provide when authenticator is set to `oauth`.\"\n        ),\n    )\n    endpoint: Optional[str] = Field(\n        default=None,\n        description=(\n            \"The Okta endpoint to use when authenticator is set to `okta_endpoint`.\"\n        ),\n    )\n    role: Optional[str] = Field(\n        default=None, description=\"The name of the default role to use.\"\n    )\n    autocommit: Optional[bool] = Field(\n        default=None, description=\"Whether to automatically commit.\"\n    )\n\n    @root_validator(pre=True)\n    def _validate_auth_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        auth_params = (\n            \"password\",\n            \"private_key\",\n            \"private_key_path\",\n            \"authenticator\",\n            \"token\",\n        )\n        if not any(values.get(param) for param in auth_params):\n            auth_str = \", \".join(auth_params)\n            raise ValueError(\n                f\"One of the authentication keys must be provided: {auth_str}\\n\"\n            )\n        elif values.get(\"private_key\") and values.get(\"private_key_path\"):\n            raise ValueError(\n                \"Do not provide both private_key and private_key_path; select one.\"\n            )\n        elif values.get(\"password\") and values.get(\"private_key_passphrase\"):\n            raise ValueError(\n                \"Do not provide both password and private_key_passphrase; \"\n                \"specify private_key_passphrase only instead.\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def _validate_token_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        authenticator = values.get(\"authenticator\")\n        token = values.get(\"token\")\n        if authenticator == \"oauth\" and not token:\n            raise ValueError(\n                \"If authenticator is set to `oauth`, `token` must be provided\"\n            )\n        return values\n\n    @root_validator(pre=True)\n    def _validate_okta_kwargs(cls, values):\n        \"\"\"\n        Ensure an authorization value has been provided by the user.\n        \"\"\"\n        authenticator = values.get(\"authenticator\")\n\n        # did not want to make a breaking change so we will allow both\n        # see https://github.com/PrefectHQ/prefect-snowflake/issues/44\n        if \"okta_endpoint\" in values.keys():\n            warnings.warn(\n                \"Please specify `endpoint` instead of `okta_endpoint`; \"\n                \"`okta_endpoint` will be removed March 31, 2023.\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n            # remove okta endpoint from fields\n            okta_endpoint = values.pop(\"okta_endpoint\")\n            if \"endpoint\" not in values.keys():\n                values[\"endpoint\"] = okta_endpoint\n\n        endpoint = values.get(\"endpoint\")\n        if authenticator == \"okta_endpoint\" and not endpoint:\n            raise ValueError(\n                \"If authenticator is set to `okta_endpoint`, \"\n                \"`endpoint` must be provided\"\n            )\n        return values\n\n    def resolve_private_key(self) -&gt; Optional[bytes]:\n        \"\"\"\n        Converts a PEM encoded private key into a DER binary key.\n\n        Returns:\n            DER encoded key if private_key has been provided otherwise returns None.\n\n        Raises:\n            InvalidPemFormat: If private key is not in PEM format.\n        \"\"\"\n        if self.private_key_path is None and self.private_key is None:\n            return None\n        elif self.private_key_path:\n            private_key = self.private_key_path.read_bytes()\n        else:\n            private_key = self._decode_secret(self.private_key)\n\n        if self.private_key_passphrase is not None:\n            password = self._decode_secret(self.private_key_passphrase)\n        elif self.password is not None:\n            warnings.warn(\n                \"Using the password field for private_key is deprecated \"\n                \"and will not work after March 31, 2023; please use \"\n                \"private_key_passphrase instead\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n            password = self._decode_secret(self.password)\n        else:\n            password = None\n\n        composed_private_key = self._compose_pem(private_key)\n        return load_pem_private_key(\n            data=composed_private_key,\n            password=password,\n            backend=default_backend(),\n        ).private_bytes(\n            encoding=Encoding.DER,\n            format=PrivateFormat.PKCS8,\n            encryption_algorithm=NoEncryption(),\n        )\n\n    @staticmethod\n    def _decode_secret(secret: Union[SecretStr, SecretBytes]) -&gt; Optional[bytes]:\n        \"\"\"\n        Decode the provided secret into bytes. If the secret is not a\n        string or bytes, or it is whitespace, then return None.\n\n        Args:\n            secret: The value to decode.\n\n        Returns:\n            The decoded secret as bytes.\n\n        \"\"\"\n        if isinstance(secret, (SecretBytes, SecretStr)):\n            secret = secret.get_secret_value()\n\n        if not isinstance(secret, (bytes, str)) or len(secret) == 0 or secret.isspace():\n            return None\n\n        return secret if isinstance(secret, bytes) else secret.encode()\n\n    @staticmethod\n    def _compose_pem(private_key: bytes) -&gt; bytes:\n        \"\"\"Validate structure of PEM certificate.\n\n        The original key passed from Prefect is sometimes malformed.\n        This function recomposes the key into a valid key that will\n        pass the serialization step when resolving the key to a DER.\n\n        Args:\n            private_key: A valid PEM format byte encoded string.\n\n        Returns:\n            byte encoded certificate.\n\n        Raises:\n            InvalidPemFormat: if private key is an invalid format.\n        \"\"\"\n        pem_parts = re.match(_SIMPLE_PEM_CERTIFICATE_REGEX, private_key.decode())\n        if pem_parts is None:\n            raise InvalidPemFormat()\n\n        body = \"\\n\".join(re.split(r\"\\s+\", pem_parts[2].strip()))\n        # reassemble header+body+footer\n        return f\"{pem_parts[1]}\\n{body}\\n{pem_parts[3]}\".encode()\n\n    def get_client(\n        self, **connect_kwargs: Any\n    ) -&gt; snowflake.connector.SnowflakeConnection:\n        \"\"\"\n        Returns an authenticated connection that can be used to query\n        Snowflake databases.\n\n        Any additional arguments passed to this method will be used to configure\n        the SnowflakeConnection. For available parameters, please refer to the\n        [Snowflake Python connector documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect).\n\n        Args:\n            **connect_kwargs: Additional arguments to pass to\n                `snowflake.connector.connect`.\n\n        Returns:\n            An authenticated Snowflake connection.\n\n        Example:\n            Get Snowflake connection with only block configuration:\n            ```python\n            from prefect_snowflake import SnowflakeCredentials\n\n            snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n            connection = snowflake_credentials_block.get_client()\n            ```\n\n            Get Snowflake connector scoped to a specified database:\n            ```python\n            from prefect_snowflake import SnowflakeCredentials\n\n            snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n            connection = snowflake_credentials_block.get_client(database=\"my_database\")\n            ```\n        \"\"\"  # noqa\n        connect_params = {\n            # required to track task's usage in the Snowflake Partner Network Portal\n            \"application\": \"Prefect_Snowflake_Collection\",\n            **self.dict(exclude_unset=True, exclude={\"block_type_slug\"}),\n            **connect_kwargs,\n        }\n\n        for key, value in connect_params.items():\n            if isinstance(value, SecretField):\n                connect_params[key] = connect_params[key].get_secret_value()\n\n        # set authenticator to the actual okta_endpoint\n        if connect_params.get(\"authenticator\") == \"okta_endpoint\":\n            endpoint = connect_params.pop(\"endpoint\", None) or connect_params.pop(\n                \"okta_endpoint\", None\n            )  # okta_endpoint is deprecated\n            connect_params[\"authenticator\"] = endpoint\n\n        private_der_key = self.resolve_private_key()\n        if private_der_key is not None:\n            connect_params[\"private_key\"] = private_der_key\n            connect_params.pop(\"password\", None)\n            connect_params.pop(\"private_key_passphrase\", None)\n\n        return snowflake.connector.connect(**connect_params)\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials.get_client","title":"<code>get_client</code>","text":"<p>Returns an authenticated connection that can be used to query Snowflake databases.</p> <p>Any additional arguments passed to this method will be used to configure the SnowflakeConnection. For available parameters, please refer to the Snowflake Python connector documentation.</p> <p>Parameters:</p> Name Type Description Default <code>**connect_kwargs</code> <code>Any</code> <p>Additional arguments to pass to <code>snowflake.connector.connect</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>SnowflakeConnection</code> <p>An authenticated Snowflake connection.</p> Example <p>Get Snowflake connection with only block configuration: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\nconnection = snowflake_credentials_block.get_client()\n</code></pre></p> <p>Get Snowflake connector scoped to a specified database: <pre><code>from prefect_snowflake import SnowflakeCredentials\n\nsnowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\nconnection = snowflake_credentials_block.get_client(database=\"my_database\")\n</code></pre></p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>def get_client(\n    self, **connect_kwargs: Any\n) -&gt; snowflake.connector.SnowflakeConnection:\n    \"\"\"\n    Returns an authenticated connection that can be used to query\n    Snowflake databases.\n\n    Any additional arguments passed to this method will be used to configure\n    the SnowflakeConnection. For available parameters, please refer to the\n    [Snowflake Python connector documentation](https://docs.snowflake.com/en/user-guide/python-connector-api.html#connect).\n\n    Args:\n        **connect_kwargs: Additional arguments to pass to\n            `snowflake.connector.connect`.\n\n    Returns:\n        An authenticated Snowflake connection.\n\n    Example:\n        Get Snowflake connection with only block configuration:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n        connection = snowflake_credentials_block.get_client()\n        ```\n\n        Get Snowflake connector scoped to a specified database:\n        ```python\n        from prefect_snowflake import SnowflakeCredentials\n\n        snowflake_credentials_block = SnowflakeCredentials.load(\"BLOCK_NAME\")\n\n        connection = snowflake_credentials_block.get_client(database=\"my_database\")\n        ```\n    \"\"\"  # noqa\n    connect_params = {\n        # required to track task's usage in the Snowflake Partner Network Portal\n        \"application\": \"Prefect_Snowflake_Collection\",\n        **self.dict(exclude_unset=True, exclude={\"block_type_slug\"}),\n        **connect_kwargs,\n    }\n\n    for key, value in connect_params.items():\n        if isinstance(value, SecretField):\n            connect_params[key] = connect_params[key].get_secret_value()\n\n    # set authenticator to the actual okta_endpoint\n    if connect_params.get(\"authenticator\") == \"okta_endpoint\":\n        endpoint = connect_params.pop(\"endpoint\", None) or connect_params.pop(\n            \"okta_endpoint\", None\n        )  # okta_endpoint is deprecated\n        connect_params[\"authenticator\"] = endpoint\n\n    private_der_key = self.resolve_private_key()\n    if private_der_key is not None:\n        connect_params[\"private_key\"] = private_der_key\n        connect_params.pop(\"password\", None)\n        connect_params.pop(\"private_key_passphrase\", None)\n\n    return snowflake.connector.connect(**connect_params)\n</code></pre>"},{"location":"integrations/prefect-snowflake/credentials/#prefect_snowflake.credentials.SnowflakeCredentials.resolve_private_key","title":"<code>resolve_private_key</code>","text":"<p>Converts a PEM encoded private key into a DER binary key.</p> <p>Returns:</p> Type Description <code>Optional[bytes]</code> <p>DER encoded key if private_key has been provided otherwise returns None.</p> <p>Raises:</p> Type Description <code>InvalidPemFormat</code> <p>If private key is not in PEM format.</p> Source code in <code>prefect_snowflake/credentials.py</code> <pre><code>def resolve_private_key(self) -&gt; Optional[bytes]:\n    \"\"\"\n    Converts a PEM encoded private key into a DER binary key.\n\n    Returns:\n        DER encoded key if private_key has been provided otherwise returns None.\n\n    Raises:\n        InvalidPemFormat: If private key is not in PEM format.\n    \"\"\"\n    if self.private_key_path is None and self.private_key is None:\n        return None\n    elif self.private_key_path:\n        private_key = self.private_key_path.read_bytes()\n    else:\n        private_key = self._decode_secret(self.private_key)\n\n    if self.private_key_passphrase is not None:\n        password = self._decode_secret(self.private_key_passphrase)\n    elif self.password is not None:\n        warnings.warn(\n            \"Using the password field for private_key is deprecated \"\n            \"and will not work after March 31, 2023; please use \"\n            \"private_key_passphrase instead\",\n            DeprecationWarning,\n            stacklevel=2,\n        )\n        password = self._decode_secret(self.password)\n    else:\n        password = None\n\n    composed_private_key = self._compose_pem(private_key)\n    return load_pem_private_key(\n        data=composed_private_key,\n        password=password,\n        backend=default_backend(),\n    ).private_bytes(\n        encoding=Encoding.DER,\n        format=PrivateFormat.PKCS8,\n        encryption_algorithm=NoEncryption(),\n    )\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/","title":"Database","text":""},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database","title":"<code>prefect_snowflake.database</code>","text":"<p>Module for querying against Snowflake databases.</p>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector","title":"<code>SnowflakeConnector</code>","text":"<p>               Bases: <code>DatabaseBlock</code></p> <p>Block used to manage connections with Snowflake.</p> <p>Upon instantiating, a connection is created and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the engine and its connections when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor will be lost.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <p>The credentials to authenticate with Snowflake.</p> required <code>database</code> <p>The name of the default database to use.</p> required <code>warehouse</code> <p>The name of the default warehouse to use.</p> required <code>schema</code> <p>The name of the default schema to use; this attribute is accessible through <code>SnowflakeConnector(...).schema_</code>.</p> required <code>fetch_size</code> <p>The number of rows to fetch at a time.</p> required <code>poll_frequency_s</code> <p>The number of seconds before checking query.</p> required <p>Examples:</p> <p>Load stored Snowflake connector as a context manager: <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nsnowflake_connector = SnowflakeConnector.load(\"BLOCK_NAME\")\n</code></pre></p> <p>Insert data into database and fetch results. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = conn.fetch_all(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Space\"}\n    )\n    print(results)\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>class SnowflakeConnector(DatabaseBlock):\n    \"\"\"\n    Block used to manage connections with Snowflake.\n\n    Upon instantiating, a connection is created and maintained for the life of\n    the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the engine and its connections when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor will be lost.\n\n    Args:\n        credentials: The credentials to authenticate with Snowflake.\n        database: The name of the default database to use.\n        warehouse: The name of the default warehouse to use.\n        schema: The name of the default schema to use;\n            this attribute is accessible through `SnowflakeConnector(...).schema_`.\n        fetch_size: The number of rows to fetch at a time.\n        poll_frequency_s: The number of seconds before checking query.\n\n    Examples:\n        Load stored Snowflake connector as a context manager:\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        snowflake_connector = SnowflakeConnector.load(\"BLOCK_NAME\")\n        ```\n\n        Insert data into database and fetch results.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = conn.fetch_all(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Space\"}\n            )\n            print(results)\n        ```\n    \"\"\"  # noqa\n\n    _block_type_name = \"Snowflake Connector\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/bd359de0b4be76c2254bd329fe3a267a1a3879c2-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector\"  # noqa\n    _description = \"Perform data operations against a Snowflake database.\"\n\n    credentials: SnowflakeCredentials = Field(\n        default=..., description=\"The credentials to authenticate with Snowflake.\"\n    )\n    database: str = Field(\n        default=..., description=\"The name of the default database to use.\"\n    )\n    warehouse: str = Field(\n        default=..., description=\"The name of the default warehouse to use.\"\n    )\n    schema_: str = Field(\n        default=...,\n        alias=\"schema\",\n        description=\"The name of the default schema to use.\",\n    )\n    fetch_size: int = Field(\n        default=1, description=\"The default number of rows to fetch at a time.\"\n    )\n    poll_frequency_s: int = Field(\n        default=1,\n        title=\"Poll Frequency [seconds]\",\n        description=(\n            \"The number of seconds between checking query \"\n            \"status for long running queries.\"\n        ),\n    )\n\n    _connection: Optional[SnowflakeConnection] = None\n    _unique_cursors: Dict[str, SnowflakeCursor] = None\n\n    def get_connection(self, **connect_kwargs: Any) -&gt; SnowflakeConnection:\n        \"\"\"\n        Returns an authenticated connection that can be\n        used to query from Snowflake databases.\n\n        Args:\n            **connect_kwargs: Additional arguments to pass to\n                `snowflake.connector.connect`.\n\n        Returns:\n            The authenticated SnowflakeConnection.\n\n        Examples:\n            ```python\n            from prefect_snowflake.credentials import SnowflakeCredentials\n            from prefect_snowflake.database import SnowflakeConnector\n\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            with snowflake_connector.get_connection() as connection:\n                ...\n            ```\n        \"\"\"\n        if self._connection is not None:\n            return self._connection\n\n        connect_params = {\n            \"database\": self.database,\n            \"warehouse\": self.warehouse,\n            \"schema\": self.schema_,\n        }\n        connection = self.credentials.get_client(**connect_kwargs, **connect_params)\n        self._connection = connection\n        self.logger.info(\"Started a new connection to Snowflake.\")\n        return connection\n\n    def _start_connection(self):\n        \"\"\"\n        Starts Snowflake database connection.\n        \"\"\"\n        self.get_connection()\n        if self._unique_cursors is None:\n            self._unique_cursors = {}\n\n    def _get_cursor(\n        self,\n        inputs: Dict[str, Any],\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    ) -&gt; Tuple[bool, SnowflakeCursor]:\n        \"\"\"\n        Get a Snowflake cursor.\n\n        Args:\n            inputs: The inputs to generate a unique hash, used to decide\n                whether a new cursor should be used.\n            cursor_type: The class of the cursor to use when creating a\n                Snowflake cursor.\n\n        Returns:\n            Whether a cursor is new and a Snowflake cursor.\n        \"\"\"\n        self._start_connection()\n\n        input_hash = hash_objects(inputs)\n        if input_hash is None:\n            raise RuntimeError(\n                \"We were not able to hash your inputs, \"\n                \"which resulted in an unexpected data return; \"\n                \"please open an issue with a reproducible example.\"\n            )\n        if input_hash not in self._unique_cursors.keys():\n            new_cursor = self._connection.cursor(cursor_type)\n            self._unique_cursors[input_hash] = new_cursor\n            return True, new_cursor\n        else:\n            existing_cursor = self._unique_cursors[input_hash]\n            return False, existing_cursor\n\n    async def _execute_async(self, cursor: SnowflakeCursor, inputs: Dict[str, Any]):\n        \"\"\"Helper method to execute operations asynchronously.\"\"\"\n        response = await run_sync_in_worker_thread(cursor.execute_async, **inputs)\n        self.logger.info(\n            f\"Executing the operation, {inputs['command']!r}, asynchronously; \"\n            f\"polling for the result every {self.poll_frequency_s} seconds.\"\n        )\n\n        query_id = response[\"queryId\"]\n        while self._connection.is_still_running(\n            await run_sync_in_worker_thread(\n                self._connection.get_query_status_throw_if_error, query_id\n            )\n        ):\n            await asyncio.sleep(self.poll_frequency_s)\n        await run_sync_in_worker_thread(cursor.get_results_from_sfqid, query_id)\n\n    def reset_cursors(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened cursors.\n\n        Examples:\n            Reset the cursors to refresh cursor position.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n                conn.reset_cursors()\n                print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n            ```\n        \"\"\"  # noqa\n        if not self._unique_cursors:\n            self.logger.info(\"There were no cursors to reset.\")\n            return\n\n        input_hashes = tuple(self._unique_cursors.keys())\n        for input_hash in input_hashes:\n            cursor = self._unique_cursors.pop(input_hash)\n            try:\n                cursor.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n                )\n        self.logger.info(\"Successfully reset the cursors.\")\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; Tuple[Any]:\n        \"\"\"\n        Fetch a single result from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A tuple containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Fetch one row from the database where address is Space.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                result = conn.fetch_one(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Space\"}\n                )\n                print(result)\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type=cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        self.logger.debug(\"Preparing to fetch a row.\")\n        result = await run_sync_in_worker_thread(cursor.fetchone)\n        return result\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Repeatedly fetch two rows from the database where address is Highway 42.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Me\", \"address\": \"Highway 42\"},\n                    ],\n                )\n                result = conn.fetch_many(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                    size=2\n                )\n                print(result)  # Marvin, Ford\n                result = conn.fetch_many(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                    size=2\n                )\n                print(result)  # Unknown, Me\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        size = size or self.fetch_size\n        self.logger.debug(f\"Preparing to fetch {size} rows.\")\n        result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n        return result\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch all results from the database.\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Fetch all rows from the database where address is Highway 42.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                result = conn.fetch_all(\n                    \"SELECT * FROM customers WHERE address = %(address)s\",\n                    parameters={\"address\": \"Highway 42\"},\n                )\n                print(result)  # Marvin, Ford, Unknown\n            ```\n        \"\"\"  # noqa\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        new, cursor = self._get_cursor(inputs, cursor_type)\n        if new:\n            await self._execute_async(cursor, inputs)\n        self.logger.debug(\"Preparing to fetch all rows.\")\n        result = await run_sync_in_worker_thread(cursor.fetchall)\n        return result\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n        **execute_kwargs: Any,\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n            **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n        Examples:\n            Create table named customers with two columns, name and address.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n            ```\n        \"\"\"  # noqa\n        self._start_connection()\n\n        inputs = dict(\n            command=operation,\n            params=parameters,\n            **execute_kwargs,\n        )\n        with self._connection.cursor(cursor_type) as cursor:\n            await run_sync_in_worker_thread(cursor.execute, **inputs)\n        self.logger.info(f\"Executed the operation, {operation!r}.\")\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n        Unlike the fetch methods, this method will always execute the operations\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n\n        Examples:\n            Create table and insert three rows into it.\n            ```python\n            from prefect_snowflake.database import SnowflakeConnector\n\n            with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n                conn.execute(\n                    \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n                )\n                conn.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    ],\n                )\n            ```\n        \"\"\"  # noqa\n        self._start_connection()\n\n        inputs = dict(\n            command=operation,\n            seqparams=seq_of_parameters,\n        )\n        with self._connection.cursor() as cursor:\n            await run_sync_in_worker_thread(cursor.executemany, **inputs)\n        self.logger.info(\n            f\"Executed {len(seq_of_parameters)} operations off {operation!r}.\"\n        )\n\n    def close(self):\n        \"\"\"\n        Closes connection and its cursors.\n        \"\"\"\n        try:\n            self.reset_cursors()\n        finally:\n            if self._connection is None:\n                self.logger.info(\"There was no connection open to be closed.\")\n                return\n            self._connection.close()\n            self._connection = None\n            self.logger.info(\"Successfully closed the Snowflake connection.\")\n\n    def __enter__(self):\n        \"\"\"\n        Start a connection upon entry.\n        \"\"\"\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Closes connection and its cursors upon exit.\n        \"\"\"\n        self.close()\n\n    def __getstate__(self):\n        \"\"\"Allows block to be pickled and dumped.\"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_connection\", \"_unique_cursors\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"Reset connection and cursors upon loading.\"\"\"\n        self.__dict__.update(data)\n        self._start_connection()\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.close","title":"<code>close</code>","text":"<p>Closes connection and its cursors.</p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes connection and its cursors.\n    \"\"\"\n    try:\n        self.reset_cursors()\n    finally:\n        if self._connection is None:\n            self.logger.info(\"There was no connection open to be closed.\")\n            return\n        self._connection.close()\n        self._connection = None\n        self.logger.info(\"Successfully closed the Snowflake connection.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE. Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create table named customers with two columns, name and address. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Examples:\n        Create table named customers with two columns, name and address.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n        ```\n    \"\"\"  # noqa\n    self._start_connection()\n\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    with self._connection.cursor(cursor_type) as cursor:\n        await run_sync_in_worker_thread(cursor.execute, **inputs)\n    self.logger.info(f\"Executed the operation, {operation!r}.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE. Unlike the fetch methods, this method will always execute the operations upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <p>Examples:</p> <p>Create table and insert three rows into it. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n        ],\n    )\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n    Unlike the fetch methods, this method will always execute the operations\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n\n    Examples:\n        Create table and insert three rows into it.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                ],\n            )\n        ```\n    \"\"\"  # noqa\n    self._start_connection()\n\n    inputs = dict(\n        command=operation,\n        seqparams=seq_of_parameters,\n    )\n    with self._connection.cursor() as cursor:\n        await run_sync_in_worker_thread(cursor.executemany, **inputs)\n    self.logger.info(\n        f\"Executed {len(seq_of_parameters)} operations off {operation!r}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Fetch all rows from the database where address is Highway 42. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    result = conn.fetch_all(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n    )\n    print(result)  # Marvin, Ford, Unknown\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch all results from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Fetch all rows from the database where address is Highway 42.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            result = conn.fetch_all(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n            )\n            print(result)  # Marvin, Ford, Unknown\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    self.logger.debug(\"Preparing to fetch all rows.\")\n    result = await run_sync_in_worker_thread(cursor.fetchall)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Repeatedly fetch two rows from the database where address is Highway 42. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            {\"name\": \"Me\", \"address\": \"Highway 42\"},\n        ],\n    )\n    result = conn.fetch_many(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n        size=2\n    )\n    print(result)  # Marvin, Ford\n    result = conn.fetch_many(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Highway 42\"},\n        size=2\n    )\n    print(result)  # Unknown, Me\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Repeatedly fetch two rows from the database where address is Highway 42.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Me\", \"address\": \"Highway 42\"},\n                ],\n            )\n            result = conn.fetch_many(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n                size=2\n            )\n            print(result)  # Marvin, Ford\n            result = conn.fetch_many(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Highway 42\"},\n                size=2\n            )\n            print(result)  # Unknown, Me\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    size = size or self.fetch_size\n    self.logger.debug(f\"Preparing to fetch {size} rows.\")\n    result = await run_sync_in_worker_thread(cursor.fetchmany, size=size)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database. Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The class of the cursor to use when creating a Snowflake cursor.</p> <code>SnowflakeCursor</code> <code>**execute_kwargs</code> <code>Any</code> <p>Additional options to pass to <code>cursor.execute_async</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Tuple[Any]</code> <p>A tuple containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Fetch one row from the database where address is Space. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    result = conn.fetch_one(\n        \"SELECT * FROM customers WHERE address = %(address)s\",\n        parameters={\"address\": \"Space\"}\n    )\n    print(result)\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    **execute_kwargs: Any,\n) -&gt; Tuple[Any]:\n    \"\"\"\n    Fetch a single result from the database.\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        cursor_type: The class of the cursor to use when creating a Snowflake cursor.\n        **execute_kwargs: Additional options to pass to `cursor.execute_async`.\n\n    Returns:\n        A tuple containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Fetch one row from the database where address is Space.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            result = conn.fetch_one(\n                \"SELECT * FROM customers WHERE address = %(address)s\",\n                parameters={\"address\": \"Space\"}\n            )\n            print(result)\n        ```\n    \"\"\"  # noqa\n    inputs = dict(\n        command=operation,\n        params=parameters,\n        **execute_kwargs,\n    )\n    new, cursor = self._get_cursor(inputs, cursor_type=cursor_type)\n    if new:\n        await self._execute_async(cursor, inputs)\n    self.logger.debug(\"Preparing to fetch a row.\")\n    result = await run_sync_in_worker_thread(cursor.fetchone)\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.get_connection","title":"<code>get_connection</code>","text":"<p>Returns an authenticated connection that can be used to query from Snowflake databases.</p> <p>Parameters:</p> Name Type Description Default <code>**connect_kwargs</code> <code>Any</code> <p>Additional arguments to pass to <code>snowflake.connector.connect</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>SnowflakeConnection</code> <p>The authenticated SnowflakeConnection.</p> <p>Examples:</p> <pre><code>from prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector\n\nsnowflake_credentials = SnowflakeCredentials(\n    account=\"account\",\n    user=\"user\",\n    password=\"password\",\n)\nsnowflake_connector = SnowflakeConnector(\n    database=\"database\",\n    warehouse=\"warehouse\",\n    schema=\"schema\",\n    credentials=snowflake_credentials\n)\nwith snowflake_connector.get_connection() as connection:\n    ...\n</code></pre> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def get_connection(self, **connect_kwargs: Any) -&gt; SnowflakeConnection:\n    \"\"\"\n    Returns an authenticated connection that can be\n    used to query from Snowflake databases.\n\n    Args:\n        **connect_kwargs: Additional arguments to pass to\n            `snowflake.connector.connect`.\n\n    Returns:\n        The authenticated SnowflakeConnection.\n\n    Examples:\n        ```python\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector\n\n        snowflake_credentials = SnowflakeCredentials(\n            account=\"account\",\n            user=\"user\",\n            password=\"password\",\n        )\n        snowflake_connector = SnowflakeConnector(\n            database=\"database\",\n            warehouse=\"warehouse\",\n            schema=\"schema\",\n            credentials=snowflake_credentials\n        )\n        with snowflake_connector.get_connection() as connection:\n            ...\n        ```\n    \"\"\"\n    if self._connection is not None:\n        return self._connection\n\n    connect_params = {\n        \"database\": self.database,\n        \"warehouse\": self.warehouse,\n        \"schema\": self.schema_,\n    }\n    connection = self.credentials.get_client(**connect_kwargs, **connect_params)\n    self._connection = connection\n    self.logger.info(\"Started a new connection to Snowflake.\")\n    return connection\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.SnowflakeConnector.reset_cursors","title":"<code>reset_cursors</code>","text":"<p>Tries to close all opened cursors.</p> <p>Examples:</p> <p>Reset the cursors to refresh cursor position. <pre><code>from prefect_snowflake.database import SnowflakeConnector\n\nwith SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n    conn.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n    )\n    conn.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n    conn.reset_cursors()\n    print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>def reset_cursors(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened cursors.\n\n    Examples:\n        Reset the cursors to refresh cursor position.\n        ```python\n        from prefect_snowflake.database import SnowflakeConnector\n\n        with SnowflakeConnector.load(\"BLOCK_NAME\") as conn:\n            conn.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n            )\n            conn.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (%(name)s, %(address)s);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            print(conn.fetch_one(\"SELECT * FROM customers\"))  # Ford\n            conn.reset_cursors()\n            print(conn.fetch_one(\"SELECT * FROM customers\"))  # should be Ford again\n        ```\n    \"\"\"  # noqa\n    if not self._unique_cursors:\n        self.logger.info(\"There were no cursors to reset.\")\n        return\n\n    input_hashes = tuple(self._unique_cursors.keys())\n    for input_hash in input_hashes:\n        cursor = self._unique_cursors.pop(input_hash)\n        try:\n            cursor.close()\n        except Exception as exc:\n            self.logger.warning(\n                f\"Failed to close cursor for input hash {input_hash!r}: {exc}\"\n            )\n    self.logger.info(\"Successfully reset the cursors.\")\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_multiquery","title":"<code>snowflake_multiquery</code>  <code>async</code>","text":"<p>Executes multiple queries against a Snowflake database in a shared session. Allows execution in a transaction.</p> <p>Parameters:</p> Name Type Description Default <code>queries</code> <code>List[str]</code> <p>The list of queries to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <code>as_transaction</code> <code>bool</code> <p>If True, queries are executed in a transaction.</p> <code>False</code> <code>return_transaction_control_results</code> <code>bool</code> <p>Determines if the results of queries controlling the transaction (BEGIN/COMMIT) should be returned.</p> <code>False</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>1</code> <p>Returns:</p> Type Description <code>List[List[Tuple[Any]]]</code> <p>List of the outputs of <code>response.fetchall()</code> for each query.</p> <p>Examples:</p> <p>Query Snowflake table with the ID value parameterized. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_multiquery\n\n\n@flow\ndef snowflake_multiquery_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_multiquery(\n        [\"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\", \"SELECT 1,2\"],\n        snowflake_connector,\n        params={\"id_param\": 1},\n        as_transaction=True\n    )\n    return result\n\nsnowflake_multiquery_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_multiquery(\n    queries: List[str],\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    as_transaction: bool = False,\n    return_transaction_control_results: bool = False,\n    poll_frequency_seconds: int = 1,\n) -&gt; List[List[Tuple[Any]]]:\n    \"\"\"\n    Executes multiple queries against a Snowflake database in a shared session.\n    Allows execution in a transaction.\n\n    Args:\n        queries: The list of queries to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n        as_transaction: If True, queries are executed in a transaction.\n        return_transaction_control_results: Determines if the results of queries\n            controlling the transaction (BEGIN/COMMIT) should be returned.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        List of the outputs of `response.fetchall()` for each query.\n\n    Examples:\n        Query Snowflake table with the ID value parameterized.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_multiquery\n\n\n        @flow\n        def snowflake_multiquery_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_multiquery(\n                [\"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\", \"SELECT 1,2\"],\n                snowflake_connector,\n                params={\"id_param\": 1},\n                as_transaction=True\n            )\n            return result\n\n        snowflake_multiquery_flow()\n        ```\n    \"\"\"\n    with snowflake_connector.get_connection() as connection:\n        if as_transaction:\n            queries.insert(0, BEGIN_TRANSACTION_STATEMENT)\n            queries.append(END_TRANSACTION_STATEMENT)\n\n        with connection.cursor(cursor_type) as cursor:\n            results = []\n            for query in queries:\n                response = cursor.execute_async(query, params=params)\n                query_id = response[\"queryId\"]\n                while connection.is_still_running(\n                    connection.get_query_status_throw_if_error(query_id)\n                ):\n                    await asyncio.sleep(poll_frequency_seconds)\n                cursor.get_results_from_sfqid(query_id)\n                result = cursor.fetchall()\n                results.append(result)\n\n    # cut off results from BEGIN/COMMIT queries\n    if as_transaction and not return_transaction_control_results:\n        return results[1:-1]\n    else:\n        return results\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_query","title":"<code>snowflake_query</code>  <code>async</code>","text":"<p>Executes a query against a Snowflake database.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <code>poll_frequency_seconds</code> <code>int</code> <p>Number of seconds to wait in between checks for run completion.</p> <code>1</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The output of <code>response.fetchall()</code>.</p> <p>Examples:</p> <p>Query Snowflake table with the ID value parameterized. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n@flow\ndef snowflake_query_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_query(\n        \"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\",\n        snowflake_connector,\n        params={\"id_param\": 1}\n    )\n    return result\n\nsnowflake_query_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_query(\n    query: str,\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n    poll_frequency_seconds: int = 1,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a query against a Snowflake database.\n\n    Args:\n        query: The query to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n        poll_frequency_seconds: Number of seconds to wait in between checks for\n            run completion.\n\n    Returns:\n        The output of `response.fetchall()`.\n\n    Examples:\n        Query Snowflake table with the ID value parameterized.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n        @flow\n        def snowflake_query_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_query(\n                \"SELECT * FROM table WHERE id=%{id_param}s LIMIT 8;\",\n                snowflake_connector,\n                params={\"id_param\": 1}\n            )\n            return result\n\n        snowflake_query_flow()\n        ```\n    \"\"\"\n    # context manager automatically rolls back failed transactions and closes\n    with snowflake_connector.get_connection() as connection:\n        with connection.cursor(cursor_type) as cursor:\n            response = cursor.execute_async(query, params=params)\n            query_id = response[\"queryId\"]\n            while connection.is_still_running(\n                connection.get_query_status_throw_if_error(query_id)\n            ):\n                await asyncio.sleep(poll_frequency_seconds)\n            cursor.get_results_from_sfqid(query_id)\n            result = cursor.fetchall()\n    return result\n</code></pre>"},{"location":"integrations/prefect-snowflake/database/#prefect_snowflake.database.snowflake_query_sync","title":"<code>snowflake_query_sync</code>  <code>async</code>","text":"<p>Executes a query in sync mode against a Snowflake database.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>params</code> <code>Union[Tuple[Any], Dict[str, Any]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>snowflake_connector</code> <code>SnowflakeConnector</code> <p>The credentials to use to authenticate.</p> required <code>cursor_type</code> <code>Type[SnowflakeCursor]</code> <p>The type of database cursor to use for the query.</p> <code>SnowflakeCursor</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The output of <code>response.fetchall()</code>.</p> <p>Examples:</p> <p>Execute a put statement. <pre><code>from prefect import flow\nfrom prefect_snowflake.credentials import SnowflakeCredentials\nfrom prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n@flow\ndef snowflake_query_sync_flow():\n    snowflake_credentials = SnowflakeCredentials(\n        account=\"account\",\n        user=\"user\",\n        password=\"password\",\n    )\n    snowflake_connector = SnowflakeConnector(\n        database=\"database\",\n        warehouse=\"warehouse\",\n        schema=\"schema\",\n        credentials=snowflake_credentials\n    )\n    result = snowflake_query_sync(\n        \"put file://a_file.csv @mystage;\",\n        snowflake_connector,\n    )\n    return result\n\nsnowflake_query_sync_flow()\n</code></pre></p> Source code in <code>prefect_snowflake/database.py</code> <pre><code>@task\nasync def snowflake_query_sync(\n    query: str,\n    snowflake_connector: SnowflakeConnector,\n    params: Union[Tuple[Any], Dict[str, Any]] = None,\n    cursor_type: Type[SnowflakeCursor] = SnowflakeCursor,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a query in sync mode against a Snowflake database.\n\n    Args:\n        query: The query to execute against the database.\n        params: The params to replace the placeholders in the query.\n        snowflake_connector: The credentials to use to authenticate.\n        cursor_type: The type of database cursor to use for the query.\n\n    Returns:\n        The output of `response.fetchall()`.\n\n    Examples:\n        Execute a put statement.\n        ```python\n        from prefect import flow\n        from prefect_snowflake.credentials import SnowflakeCredentials\n        from prefect_snowflake.database import SnowflakeConnector, snowflake_query\n\n\n        @flow\n        def snowflake_query_sync_flow():\n            snowflake_credentials = SnowflakeCredentials(\n                account=\"account\",\n                user=\"user\",\n                password=\"password\",\n            )\n            snowflake_connector = SnowflakeConnector(\n                database=\"database\",\n                warehouse=\"warehouse\",\n                schema=\"schema\",\n                credentials=snowflake_credentials\n            )\n            result = snowflake_query_sync(\n                \"put file://a_file.csv @mystage;\",\n                snowflake_connector,\n            )\n            return result\n\n        snowflake_query_sync_flow()\n        ```\n    \"\"\"\n    # context manager automatically rolls back failed transactions and closes\n    with snowflake_connector.get_connection() as connection:\n        with connection.cursor(cursor_type) as cursor:\n            cursor.execute(query, params=params)\n            result = cursor.fetchall()\n    return result\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/","title":"prefect-sqlalchemy","text":"<p>Visit the full docs here to see additional examples and the API reference.</p> <p>The prefect-sqlalchemy collection makes it easy to connect to a database in your Prefect flows. Check out the examples below to get started!</p>"},{"location":"integrations/prefect-sqlalchemy/#getting-started","title":"Getting started","text":""},{"location":"integrations/prefect-sqlalchemy/#integrate-with-prefect-flows","title":"Integrate with Prefect flows","text":"<p>Prefect and SQLAlchemy are a data powerhouse duo. With Prefect, your workflows are orchestratable and observable, and with SQLAlchemy, your databases are a snap to handle! Get ready to experience the ultimate data \"flow-chemistry\"!</p> <p>To set up a table, use the <code>execute</code> and <code>execute_many</code> methods. Then, use the <code>fetch_many</code> method to retrieve data in a stream until there's no more data.</p> <p>By using the <code>SqlAlchemyConnector</code> as a context manager, you can make sure that the SQLAlchemy engine and any connected resources are closed properly after you're done with them.</p> <p>Be sure to install prefect-sqlalchemy and save your credentials to a Prefect block to run the examples below!</p> <p>Async support</p> <p><code>SqlAlchemyConnector</code> also supports async workflows! Just be sure to save, load, and use an async driver as in the example below.</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"DATABASE-PLACEHOLDER.db\"\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> SyncAsync <pre><code>from prefect import flow, task\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\n\n@task\ndef setup_table(block_name: str) -&gt; None:\n    with SqlAlchemyConnector.load(block_name) as connector:\n        connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        connector.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n        )\n        connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n\n@task\ndef fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    with SqlAlchemyConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\ndef sqlalchemy_flow(block_name: str) -&gt; list:\n    setup_table(block_name)\n    all_rows = fetch_data(block_name)\n    return all_rows\n\n\nsqlalchemy_flow(\"BLOCK-NAME-PLACEHOLDER\")\n</code></pre> <pre><code>from prefect import flow, task\nfrom prefect_sqlalchemy import SqlAlchemyConnector\nimport asyncio\n\n@task\nasync def setup_table(block_name: str) -&gt; None:\n    async with await SqlAlchemyConnector.load(block_name) as connector:\n        await connector.execute(\n            \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\"\n        )\n        await connector.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n        )\n        await connector.execute_many(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            seq_of_parameters=[\n                {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                {\"name\": \"Unknown\", \"address\": \"Highway 42\"},\n            ],\n        )\n\n@task\nasync def fetch_data(block_name: str) -&gt; list:\n    all_rows = []\n    async with await SqlAlchemyConnector.load(block_name) as connector:\n        while True:\n            # Repeated fetch* calls using the same operation will\n            # skip re-executing and instead return the next set of results\n            new_rows = await connector.fetch_many(\"SELECT * FROM customers\", size=2)\n            if len(new_rows) == 0:\n                break\n            all_rows.append(new_rows)\n    return all_rows\n\n@flow\nasync def sqlalchemy_flow(block_name: str) -&gt; list:\n    await setup_table(block_name)\n    all_rows = await fetch_data(block_name)\n    return all_rows\n\n\nasyncio.run(sqlalchemy_flow(\"BLOCK-NAME-PLACEHOLDER\"))\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/#resources","title":"Resources","text":"<p>For more tips on how to use tasks and flows provided in a Prefect integration library, check out the Prefect docs on using integrations.</p>"},{"location":"integrations/prefect-sqlalchemy/#installation","title":"Installation","text":"<p>Install <code>prefect-sqlalchemy</code> with <code>pip</code>:</p> <pre><code>pip install prefect-sqlalchemy\n</code></pre> <p>Requires an installation of Python 3.8 or higher.</p> <p>We recommend using a Python virtual environment manager such as pipenv, conda, or virtualenv.</p> <p>The tasks in this library are designed to work with Prefect 2. For more information about how to use Prefect, please refer to the Prefect documentation.</p>"},{"location":"integrations/prefect-sqlalchemy/#saving-credentials-to-a-block","title":"Saving credentials to a block","text":"<p>To use the <code>load</code> method on Blocks, you must have a block document saved through code or saved through the UI.</p> <p>Below is a walkthrough on saving block documents through code; simply create a short script, replacing the placeholders.</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.POSTGRESQL_PSYCOPG2,\n        username=\"USERNAME-PLACEHOLDER\",\n        password=\"PASSWORD-PLACEHOLDER\",\n        host=\"localhost\",\n        port=5432,\n        database=\"DATABASE-PLACEHOLDER\",\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>Congrats! You can now easily load the saved block, which holds your credentials:</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nSqlAlchemyConnector.load(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>The required keywords depend upon the desired driver. For example, SQLite requires only the <code>driver</code> and <code>database</code> arguments:</p> <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector, ConnectionComponents, SyncDriver\n\nconnector = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.SQLITE_PYSQLITE,\n        database=\"DATABASE-PLACEHOLDER.db\"\n    )\n)\n\nconnector.save(\"BLOCK_NAME-PLACEHOLDER\")\n</code></pre> <p>Registering blocks</p> <p>Register blocks in this module to view and edit them on Prefect Cloud:</p> <pre><code>prefect block register -m prefect_sqlalchemy\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/#feedback","title":"Feedback","text":"<p>If you encounter any bugs while using <code>prefect-sqlalchemy</code>, please open an issue in the prefect repository.</p> <p>If you have any questions or issues while using <code>prefect-sqlalchemy</code>, you can find help in the Prefect Community Slack .</p>"},{"location":"integrations/prefect-sqlalchemy/#contributing","title":"Contributing","text":"<p>If you'd like to help contribute to fix an issue or add a feature to <code>prefect-sqlalchemy</code>, please propose changes through a pull request from a fork of the repository.</p> <p>Here are the steps:</p> <ol> <li>Fork the repository</li> <li>Clone the forked repository</li> <li>Install the repository and its dependencies: <pre><code>pip install -e \".[dev]\"\n</code></pre></li> <li>Make desired changes</li> <li>Add tests</li> <li>Install <code>pre-commit</code> to perform quality checks prior to commit: <pre><code>pre-commit install\n</code></pre></li> <li><code>git commit</code>, <code>git push</code>, and create a pull request</li> </ol>"},{"location":"integrations/prefect-sqlalchemy/credentials/","title":"Credentials","text":""},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials","title":"<code>prefect_sqlalchemy.credentials</code>","text":"<p>Credential classes used to perform authenticated interactions with SQLAlchemy</p>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.AsyncDriver","title":"<code>AsyncDriver</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Known dialects with their corresponding async drivers.</p> <p>Attributes:</p> Name Type Description <code>POSTGRESQL_ASYNCPG</code> <code>Enum</code> <p>postgresql+asyncpg</p> <code>SQLITE_AIOSQLITE</code> <code>Enum</code> <p>sqlite+aiosqlite</p> <code>MYSQL_ASYNCMY</code> <code>Enum</code> <p>mysql+asyncmy</p> <code>MYSQL_AIOMYSQL</code> <code>Enum</code> <p>mysql+aiomysql</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class AsyncDriver(Enum):\n    \"\"\"\n    Known dialects with their corresponding async drivers.\n\n    Attributes:\n        POSTGRESQL_ASYNCPG (Enum): [postgresql+asyncpg](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.asyncpg)\n\n        SQLITE_AIOSQLITE (Enum): [sqlite+aiosqlite](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.aiosqlite)\n\n        MYSQL_ASYNCMY (Enum): [mysql+asyncmy](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.asyncmy)\n        MYSQL_AIOMYSQL (Enum): [mysql+aiomysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.aiomysql)\n    \"\"\"  # noqa\n\n    POSTGRESQL_ASYNCPG = \"postgresql+asyncpg\"\n\n    SQLITE_AIOSQLITE = \"sqlite+aiosqlite\"\n\n    MYSQL_ASYNCMY = \"mysql+asyncmy\"\n    MYSQL_AIOMYSQL = \"mysql+aiomysql\"\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.ConnectionComponents","title":"<code>ConnectionComponents</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Parameters to use to create a SQLAlchemy engine URL.</p> <p>Attributes:</p> Name Type Description <code>driver</code> <code>Union[AsyncDriver, SyncDriver, str]</code> <p>The driver name to use.</p> <code>database</code> <code>str</code> <p>The name of the database to use.</p> <code>username</code> <code>Optional[str]</code> <p>The user name used to authenticate.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password used to authenticate.</p> <code>host</code> <code>Optional[str]</code> <p>The host address of the database.</p> <code>port</code> <code>Optional[str]</code> <p>The port to connect to the database.</p> <code>query</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class ConnectionComponents(BaseModel):\n    \"\"\"\n    Parameters to use to create a SQLAlchemy engine URL.\n\n    Attributes:\n        driver: The driver name to use.\n        database: The name of the database to use.\n        username: The user name used to authenticate.\n        password: The password used to authenticate.\n        host: The host address of the database.\n        port: The port to connect to the database.\n        query: A dictionary of string keys to string values to be passed to the dialect\n            and/or the DBAPI upon connect.\n    \"\"\"\n\n    driver: Union[AsyncDriver, SyncDriver, str] = Field(\n        default=..., description=\"The driver name to use.\"\n    )\n    database: str = Field(default=..., description=\"The name of the database to use.\")\n    username: Optional[str] = Field(\n        default=None, description=\"The user name used to authenticate.\"\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    host: Optional[str] = Field(\n        default=None, description=\"The host address of the database.\"\n    )\n    port: Optional[str] = Field(\n        default=None, description=\"The port to connect to the database.\"\n    )\n    query: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"A dictionary of string keys to string values to be passed to the dialect \"\n            \"and/or the DBAPI upon connect. To specify non-string parameters to a \"\n            \"Python DBAPI directly, use connect_args.\"\n        ),\n    )\n\n    def create_url(self) -&gt; URL:\n        \"\"\"\n        Create a fully formed connection URL.\n\n        Returns:\n            The SQLAlchemy engine URL.\n        \"\"\"\n        driver = self.driver\n        drivername = driver.value if isinstance(driver, Enum) else driver\n        password = self.password.get_secret_value() if self.password else None\n        url_params = dict(\n            drivername=drivername,\n            username=self.username,\n            password=password,\n            database=self.database,\n            host=self.host,\n            port=self.port,\n            query=self.query,\n        )\n        return URL.create(\n            **{\n                url_key: url_param\n                for url_key, url_param in url_params.items()\n                if url_param is not None\n            }\n        )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.ConnectionComponents.create_url","title":"<code>create_url</code>","text":"<p>Create a fully formed connection URL.</p> <p>Returns:</p> Type Description <code>URL</code> <p>The SQLAlchemy engine URL.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def create_url(self) -&gt; URL:\n    \"\"\"\n    Create a fully formed connection URL.\n\n    Returns:\n        The SQLAlchemy engine URL.\n    \"\"\"\n    driver = self.driver\n    drivername = driver.value if isinstance(driver, Enum) else driver\n    password = self.password.get_secret_value() if self.password else None\n    url_params = dict(\n        drivername=drivername,\n        username=self.username,\n        password=password,\n        database=self.database,\n        host=self.host,\n        port=self.port,\n        query=self.query,\n    )\n    return URL.create(\n        **{\n            url_key: url_param\n            for url_key, url_param in url_params.items()\n            if url_param is not None\n        }\n    )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials","title":"<code>DatabaseCredentials</code>","text":"<p>               Bases: <code>Block</code></p> <p>Block used to manage authentication with a database.</p> <p>Attributes:</p> Name Type Description <code>driver</code> <code>Optional[Union[AsyncDriver, SyncDriver, str]]</code> <p>The driver name, e.g. \"postgresql+asyncpg\"</p> <code>database</code> <code>Optional[str]</code> <p>The name of the database to use.</p> <code>username</code> <code>Optional[str]</code> <p>The user name used to authenticate.</p> <code>password</code> <code>Optional[SecretStr]</code> <p>The password used to authenticate.</p> <code>host</code> <code>Optional[str]</code> <p>The host address of the database.</p> <code>port</code> <code>Optional[str]</code> <p>The port to connect to the database.</p> <code>query</code> <code>Optional[Dict[str, str]]</code> <p>A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect. To specify non-string parameters to a Python DBAPI directly, use connect_args.</p> <code>url</code> <code>Optional[AnyUrl]</code> <p>Manually create and provide a URL to create the engine, this is useful for external dialects, e.g. Snowflake, because some of the params, such as \"warehouse\", is not directly supported in the vanilla <code>sqlalchemy.engine.URL.create</code> method; do not provide this alongside with other URL params as it will raise a <code>ValueError</code>.</p> <code>connect_args</code> <code>Optional[Dict[str, Any]]</code> <p>The options which will be passed directly to the DBAPI's connect() method as additional keyword arguments.</p> Example <p>Load stored database credentials: <pre><code>from prefect_sqlalchemy import DatabaseCredentials\ndatabase_block = DatabaseCredentials.load(\"BLOCK_NAME\")\n</code></pre></p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class DatabaseCredentials(Block):\n    \"\"\"\n    Block used to manage authentication with a database.\n\n    Attributes:\n        driver: The driver name, e.g. \"postgresql+asyncpg\"\n        database: The name of the database to use.\n        username: The user name used to authenticate.\n        password: The password used to authenticate.\n        host: The host address of the database.\n        port: The port to connect to the database.\n        query: A dictionary of string keys to string values to be passed to\n            the dialect and/or the DBAPI upon connect. To specify non-string\n            parameters to a Python DBAPI directly, use connect_args.\n        url: Manually create and provide a URL to create the engine,\n            this is useful for external dialects, e.g. Snowflake, because some\n            of the params, such as \"warehouse\", is not directly supported in\n            the vanilla `sqlalchemy.engine.URL.create` method; do not provide\n            this alongside with other URL params as it will raise a `ValueError`.\n        connect_args: The options which will be passed directly to the\n            DBAPI's connect() method as additional keyword arguments.\n\n    Example:\n        Load stored database credentials:\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials\n        database_block = DatabaseCredentials.load(\"BLOCK_NAME\")\n        ```\n    \"\"\"\n\n    _block_type_name = \"Database Credentials\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/fb3f4debabcda1c5a3aeea4f5b3f94c28845e23e-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials\"  # noqa\n\n    driver: Optional[Union[AsyncDriver, SyncDriver, str]] = Field(\n        default=None, description=\"The driver name to use.\"\n    )\n    username: Optional[str] = Field(\n        default=None, description=\"The user name used to authenticate.\"\n    )\n    password: Optional[SecretStr] = Field(\n        default=None, description=\"The password used to authenticate.\"\n    )\n    database: Optional[str] = Field(\n        default=None, description=\"The name of the database to use.\"\n    )\n    host: Optional[str] = Field(\n        default=None, description=\"The host address of the database.\"\n    )\n    port: Optional[str] = Field(\n        default=None, description=\"The port to connect to the database.\"\n    )\n    query: Optional[Dict[str, str]] = Field(\n        default=None,\n        description=(\n            \"A dictionary of string keys to string values to be passed to the dialect \"\n            \"and/or the DBAPI upon connect. To specify non-string parameters to a \"\n            \"Python DBAPI directly, use connect_args.\"\n        ),\n    )\n    url: Optional[AnyUrl] = Field(\n        default=None,\n        description=(\n            \"Manually create and provide a URL to create the engine, this is useful \"\n            \"for external dialects, e.g. Snowflake, because some of the params, \"\n            \"such as 'warehouse', is not directly supported in the vanilla \"\n            \"`sqlalchemy.engine.URL.create` method; do not provide this \"\n            \"alongside with other URL params as it will raise a `ValueError`.\"\n        ),\n    )\n    connect_args: Optional[Dict[str, Any]] = Field(\n        default=None,\n        description=(\n            \"The options which will be passed directly to the DBAPI's connect() \"\n            \"method as additional keyword arguments.\"\n        ),\n    )\n\n    def block_initialization(self):\n        \"\"\"\n        Initializes the engine.\n        \"\"\"\n        warnings.warn(\n            \"DatabaseCredentials is now deprecated and will be removed March 2023; \"\n            \"please use SqlAlchemyConnector instead.\",\n            DeprecationWarning,\n        )\n        if isinstance(self.driver, AsyncDriver):\n            drivername = self.driver.value\n            self._driver_is_async = True\n        elif isinstance(self.driver, SyncDriver):\n            drivername = self.driver.value\n            self._driver_is_async = False\n        else:\n            drivername = self.driver\n            self._driver_is_async = drivername in AsyncDriver._value2member_map_\n\n        url_params = dict(\n            drivername=drivername,\n            username=self.username,\n            password=self.password.get_secret_value() if self.password else None,\n            database=self.database,\n            host=self.host,\n            port=self.port,\n            query=self.query,\n        )\n        if not self.url:\n            required_url_keys = (\"drivername\", \"database\")\n            if not all(url_params[key] for key in required_url_keys):\n                required_url_keys = (\"driver\", \"database\")\n                raise ValueError(\n                    f\"If the `url` is not provided, \"\n                    f\"all of these URL params are required: \"\n                    f\"{required_url_keys}\"\n                )\n            self.rendered_url = URL.create(\n                **{\n                    url_key: url_param\n                    for url_key, url_param in url_params.items()\n                    if url_param is not None\n                }\n            )  # from params\n        else:\n            if any(val for val in url_params.values()):\n                raise ValueError(\n                    f\"The `url` should not be provided \"\n                    f\"alongside any of these URL params: \"\n                    f\"{url_params.keys()}\"\n                )\n            self.rendered_url = make_url(str(self.url))\n\n    def get_engine(self) -&gt; Union[\"Connection\", \"AsyncConnection\"]:\n        \"\"\"\n        Returns an authenticated engine that can be\n        used to query from databases.\n\n        Returns:\n            The authenticated SQLAlchemy Connection / AsyncConnection.\n\n        Examples:\n            Create an asynchronous engine to PostgreSQL using URL params.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                sqlalchemy_credentials = DatabaseCredentials(\n                    driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                    username=\"prefect\",\n                    password=\"prefect_password\",\n                    database=\"postgres\"\n                )\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n\n            Create a synchronous engine to Snowflake using the `url` kwarg.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                url = (\n                    \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                    \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                    \"?warehouse=&lt;warehouse_name&gt;\"\n                )\n                sqlalchemy_credentials = DatabaseCredentials(url=url)\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n        \"\"\"\n        engine_kwargs = dict(\n            url=self.rendered_url,\n            connect_args=self.connect_args or {},\n            poolclass=NullPool,\n        )\n        if self._driver_is_async:\n            engine = create_async_engine(**engine_kwargs)\n        else:\n            engine = create_engine(**engine_kwargs)\n        return engine\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'URL' type\n        arbitrary_types_allowed = True\n        json_encoders = {URL: lambda u: u.render_as_string()}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'URL' type\n        d = super().dict(*args, **kwargs)\n        d[\"rendered_url\"] = SecretStr(\n            self.rendered_url.render_as_string(hide_password=False)\n        )\n        return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'URL' type\n    arbitrary_types_allowed = True\n    json_encoders = {URL: lambda u: u.render_as_string()}\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.block_initialization","title":"<code>block_initialization</code>","text":"<p>Initializes the engine.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def block_initialization(self):\n    \"\"\"\n    Initializes the engine.\n    \"\"\"\n    warnings.warn(\n        \"DatabaseCredentials is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector instead.\",\n        DeprecationWarning,\n    )\n    if isinstance(self.driver, AsyncDriver):\n        drivername = self.driver.value\n        self._driver_is_async = True\n    elif isinstance(self.driver, SyncDriver):\n        drivername = self.driver.value\n        self._driver_is_async = False\n    else:\n        drivername = self.driver\n        self._driver_is_async = drivername in AsyncDriver._value2member_map_\n\n    url_params = dict(\n        drivername=drivername,\n        username=self.username,\n        password=self.password.get_secret_value() if self.password else None,\n        database=self.database,\n        host=self.host,\n        port=self.port,\n        query=self.query,\n    )\n    if not self.url:\n        required_url_keys = (\"drivername\", \"database\")\n        if not all(url_params[key] for key in required_url_keys):\n            required_url_keys = (\"driver\", \"database\")\n            raise ValueError(\n                f\"If the `url` is not provided, \"\n                f\"all of these URL params are required: \"\n                f\"{required_url_keys}\"\n            )\n        self.rendered_url = URL.create(\n            **{\n                url_key: url_param\n                for url_key, url_param in url_params.items()\n                if url_param is not None\n            }\n        )  # from params\n    else:\n        if any(val for val in url_params.values()):\n            raise ValueError(\n                f\"The `url` should not be provided \"\n                f\"alongside any of these URL params: \"\n                f\"{url_params.keys()}\"\n            )\n        self.rendered_url = make_url(str(self.url))\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'URL' type\n    d = super().dict(*args, **kwargs)\n    d[\"rendered_url\"] = SecretStr(\n        self.rendered_url.render_as_string(hide_password=False)\n    )\n    return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.DatabaseCredentials.get_engine","title":"<code>get_engine</code>","text":"<p>Returns an authenticated engine that can be used to query from databases.</p> <p>Returns:</p> Type Description <code>Union[Connection, AsyncConnection]</code> <p>The authenticated SQLAlchemy Connection / AsyncConnection.</p> <p>Examples:</p> <p>Create an asynchronous engine to PostgreSQL using URL params. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n        username=\"prefect\",\n        password=\"prefect_password\",\n        database=\"postgres\"\n    )\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> <p>Create a synchronous engine to Snowflake using the <code>url</code> kwarg. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    url = (\n        \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n        \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n        \"?warehouse=&lt;warehouse_name&gt;\"\n    )\n    sqlalchemy_credentials = DatabaseCredentials(url=url)\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>def get_engine(self) -&gt; Union[\"Connection\", \"AsyncConnection\"]:\n    \"\"\"\n    Returns an authenticated engine that can be\n    used to query from databases.\n\n    Returns:\n        The authenticated SQLAlchemy Connection / AsyncConnection.\n\n    Examples:\n        Create an asynchronous engine to PostgreSQL using URL params.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                username=\"prefect\",\n                password=\"prefect_password\",\n                database=\"postgres\"\n            )\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n\n        Create a synchronous engine to Snowflake using the `url` kwarg.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            url = (\n                \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                \"?warehouse=&lt;warehouse_name&gt;\"\n            )\n            sqlalchemy_credentials = DatabaseCredentials(url=url)\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n    \"\"\"\n    engine_kwargs = dict(\n        url=self.rendered_url,\n        connect_args=self.connect_args or {},\n        poolclass=NullPool,\n    )\n    if self._driver_is_async:\n        engine = create_async_engine(**engine_kwargs)\n    else:\n        engine = create_engine(**engine_kwargs)\n    return engine\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/credentials/#prefect_sqlalchemy.credentials.SyncDriver","title":"<code>SyncDriver</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Known dialects with their corresponding sync drivers.</p> <p>Attributes:</p> Name Type Description <code>POSTGRESQL_PSYCOPG2</code> <code>Enum</code> <p>postgresql+psycopg2</p> <code>POSTGRESQL_PG8000</code> <code>Enum</code> <p>postgresql+pg8000</p> <code>POSTGRESQL_PSYCOPG2CFFI</code> <code>Enum</code> <p>postgresql+psycopg2cffi</p> <code>POSTGRESQL_PYPOSTGRESQL</code> <code>Enum</code> <p>postgresql+pypostgresql</p> <code>POSTGRESQL_PYGRESQL</code> <code>Enum</code> <p>postgresql+pygresql</p> <code>MYSQL_MYSQLDB</code> <code>Enum</code> <p>mysql+mysqldb</p> <code>MYSQL_PYMYSQL</code> <code>Enum</code> <p>mysql+pymysql</p> <code>MYSQL_MYSQLCONNECTOR</code> <code>Enum</code> <p>mysql+mysqlconnector</p> <code>MYSQL_CYMYSQL</code> <code>Enum</code> <p>mysql+cymysql</p> <code>MYSQL_OURSQL</code> <code>Enum</code> <p>mysql+oursql</p> <code>MYSQL_PYODBC</code> <code>Enum</code> <p>mysql+pyodbc</p> <code>SQLITE_PYSQLITE</code> <code>Enum</code> <p>sqlite+pysqlite</p> <code>SQLITE_PYSQLCIPHER</code> <code>Enum</code> <p>sqlite+pysqlcipher</p> <code>ORACLE_CX_ORACLE</code> <code>Enum</code> <p>oracle+cx_oracle</p> <code>MSSQL_PYODBC</code> <code>Enum</code> <p>mssql+pyodbc</p> <code>MSSQL_MXODBC</code> <code>Enum</code> <p>mssql+mxodbc</p> <code>MSSQL_PYMSSQL</code> <code>Enum</code> <p>mssql+pymssql</p> Source code in <code>prefect_sqlalchemy/credentials.py</code> <pre><code>class SyncDriver(Enum):\n    \"\"\"\n    Known dialects with their corresponding sync drivers.\n\n    Attributes:\n        POSTGRESQL_PSYCOPG2 (Enum): [postgresql+psycopg2](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg2)\n        POSTGRESQL_PG8000 (Enum): [postgresql+pg8000](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pg8000)\n        POSTGRESQL_PSYCOPG2CFFI (Enum): [postgresql+psycopg2cffi](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg2cffi)\n        POSTGRESQL_PYPOSTGRESQL (Enum): [postgresql+pypostgresql](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pypostgresql)\n        POSTGRESQL_PYGRESQL (Enum): [postgresql+pygresql](https://docs.sqlalchemy.org/en/14/dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.pygresql)\n\n        MYSQL_MYSQLDB (Enum): [mysql+mysqldb](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.mysqldb)\n        MYSQL_PYMYSQL (Enum): [mysql+pymysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.pymysql)\n        MYSQL_MYSQLCONNECTOR (Enum): [mysql+mysqlconnector](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.mysqlconnector)\n        MYSQL_CYMYSQL (Enum): [mysql+cymysql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.cymysql)\n        MYSQL_OURSQL (Enum): [mysql+oursql](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.oursql)\n        MYSQL_PYODBC (Enum): [mysql+pyodbc](https://docs.sqlalchemy.org/en/14/dialects/mysql.html#module-sqlalchemy.dialects.mysql.pyodbc)\n\n        SQLITE_PYSQLITE (Enum): [sqlite+pysqlite](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.pysqlite)\n        SQLITE_PYSQLCIPHER (Enum): [sqlite+pysqlcipher](https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#module-sqlalchemy.dialects.sqlite.pysqlcipher)\n\n        ORACLE_CX_ORACLE (Enum): [oracle+cx_oracle](https://docs.sqlalchemy.org/en/14/dialects/oracle.html#module-sqlalchemy.dialects.oracle.cx_oracle)\n\n        MSSQL_PYODBC (Enum): [mssql+pyodbc](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.pyodbc)\n        MSSQL_MXODBC (Enum): [mssql+mxodbc](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.mxodbc)\n        MSSQL_PYMSSQL (Enum): [mssql+pymssql](https://docs.sqlalchemy.org/en/14/dialects/mssql.html#module-sqlalchemy.dialects.mssql.pymssql)\n    \"\"\"  # noqa\n\n    POSTGRESQL_PSYCOPG2 = \"postgresql+psycopg2\"\n    POSTGRESQL_PG8000 = \"postgresql+pg8000\"\n    POSTGRESQL_PSYCOPG2CFFI = \"postgresql+psycopg2cffi\"\n    POSTGRESQL_PYPOSTGRESQL = \"postgresql+pypostgresql\"\n    POSTGRESQL_PYGRESQL = \"postgresql+pygresql\"\n\n    MYSQL_MYSQLDB = \"mysql+mysqldb\"\n    MYSQL_PYMYSQL = \"mysql+pymysql\"\n    MYSQL_MYSQLCONNECTOR = \"mysql+mysqlconnector\"\n    MYSQL_CYMYSQL = \"mysql+cymysql\"\n    MYSQL_OURSQL = \"mysql+oursql\"\n    MYSQL_PYODBC = \"mysql+pyodbc\"\n\n    SQLITE_PYSQLITE = \"sqlite+pysqlite\"\n    SQLITE_PYSQLCIPHER = \"sqlite+pysqlcipher\"\n\n    ORACLE_CX_ORACLE = \"oracle+cx_oracle\"\n\n    MSSQL_PYODBC = \"mssql+pyodbc\"\n    MSSQL_MXODBC = \"mssql+mxodbc\"\n    MSSQL_PYMSSQL = \"mssql+pymssql\"\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/","title":"Database","text":""},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database","title":"<code>prefect_sqlalchemy.database</code>","text":"<p>Tasks for querying a database with SQLAlchemy</p>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector","title":"<code>SqlAlchemyConnector</code>","text":"<p>               Bases: <code>CredentialsBlock</code>, <code>DatabaseBlock</code></p> <p>Block used to manage authentication with a database.</p> <p>Upon instantiating, an engine is created and maintained for the life of the object until the close method is called.</p> <p>It is recommended to use this block as a context manager, which will automatically close the engine and its connections when the context is exited.</p> <p>It is also recommended that this block is loaded and consumed within a single task or flow because if the block is passed across separate tasks and flows, the state of the block's connection and cursor could be lost.</p> <p>Attributes:</p> Name Type Description <code>connection_info</code> <code>Union[ConnectionComponents, AnyUrl]</code> <p>SQLAlchemy URL to create the engine; either create from components or create from a string.</p> <code>connect_args</code> <code>Optional[Dict[str, Any]]</code> <p>The options which will be passed directly to the DBAPI's connect() method as additional keyword arguments.</p> <code>fetch_size</code> <code>int</code> <p>The number of rows to fetch at a time.</p> Example <p>Load stored database credentials and use in context manager: <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\ndatabase_block = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith database_block:\n    ...\n</code></pre></p> <p>Create table named customers and insert values; then fetch the first 10 rows. <pre><code>from prefect_sqlalchemy import (\n    SqlAlchemyConnector, SyncDriver, ConnectionComponents\n)\n\nwith SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n        driver=SyncDriver.SQLITE_PYSQLITE,\n        database=\"prefect.db\"\n    )\n) as database:\n    database.execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n    )\n    for i in range(1, 42):\n        database.execute(\n            \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n            parameters={\"name\": \"Marvin\", \"address\": f\"Highway {i}\"},\n        )\n    results = database.fetch_many(\n        \"SELECT * FROM customers WHERE name = :name;\",\n        parameters={\"name\": \"Marvin\"},\n        size=10\n    )\nprint(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>class SqlAlchemyConnector(CredentialsBlock, DatabaseBlock):\n    \"\"\"\n    Block used to manage authentication with a database.\n\n    Upon instantiating, an engine is created and maintained for the life of\n    the object until the close method is called.\n\n    It is recommended to use this block as a context manager, which will automatically\n    close the engine and its connections when the context is exited.\n\n    It is also recommended that this block is loaded and consumed within a single task\n    or flow because if the block is passed across separate tasks and flows,\n    the state of the block's connection and cursor could be lost.\n\n    Attributes:\n        connection_info: SQLAlchemy URL to create the engine;\n            either create from components or create from a string.\n        connect_args: The options which will be passed directly to the\n            DBAPI's connect() method as additional keyword arguments.\n        fetch_size: The number of rows to fetch at a time.\n\n    Example:\n        Load stored database credentials and use in context manager:\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        database_block = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with database_block:\n            ...\n        ```\n\n        Create table named customers and insert values; then fetch the first 10 rows.\n        ```python\n        from prefect_sqlalchemy import (\n            SqlAlchemyConnector, SyncDriver, ConnectionComponents\n        )\n\n        with SqlAlchemyConnector(\n            connection_info=ConnectionComponents(\n                driver=SyncDriver.SQLITE_PYSQLITE,\n                database=\"prefect.db\"\n            )\n        ) as database:\n            database.execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n            )\n            for i in range(1, 42):\n                database.execute(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    parameters={\"name\": \"Marvin\", \"address\": f\"Highway {i}\"},\n                )\n            results = database.fetch_many(\n                \"SELECT * FROM customers WHERE name = :name;\",\n                parameters={\"name\": \"Marvin\"},\n                size=10\n            )\n        print(results)\n        ```\n    \"\"\"\n\n    _block_type_name = \"SQLAlchemy Connector\"\n    _logo_url = \"https://cdn.sanity.io/images/3ugk85nk/production/3c7dff04f70aaf4528e184a3b028f9e40b98d68c-250x250.png\"  # noqa\n    _documentation_url = \"https://prefecthq.github.io/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector\"  # noqa\n\n    connection_info: Union[ConnectionComponents, AnyUrl] = Field(\n        default=...,\n        description=(\n            \"SQLAlchemy URL to create the engine; either create from components \"\n            \"or create from a string.\"\n        ),\n    )\n    connect_args: Optional[Dict[str, Any]] = Field(\n        default=None,\n        title=\"Additional Connection Arguments\",\n        description=(\n            \"The options which will be passed directly to the DBAPI's connect() \"\n            \"method as additional keyword arguments.\"\n        ),\n    )\n    fetch_size: int = Field(\n        default=1, description=\"The number of rows to fetch at a time.\"\n    )\n\n    _engine: Optional[Union[AsyncEngine, Engine]] = None\n    _exit_stack: Union[ExitStack, AsyncExitStack] = None\n    _unique_results: Dict[str, CursorResult] = None\n\n    class Config:\n        \"\"\"Configuration of pydantic.\"\"\"\n\n        # Support serialization of the 'URL' type\n        arbitrary_types_allowed = True\n        json_encoders = {URL: lambda u: u.render_as_string()}\n\n    def dict(self, *args, **kwargs) -&gt; Dict:\n        \"\"\"\n        Convert to a dictionary.\n        \"\"\"\n        # Support serialization of the 'URL' type\n        d = super().dict(*args, **kwargs)\n        d[\"_rendered_url\"] = SecretStr(\n            self._rendered_url.render_as_string(hide_password=False)\n        )\n        return d\n\n    def block_initialization(self):\n        \"\"\"\n        Initializes the engine.\n        \"\"\"\n        super().block_initialization()\n\n        if isinstance(self.connection_info, ConnectionComponents):\n            self._rendered_url = self.connection_info.create_url()\n        else:\n            # make rendered url from string\n            self._rendered_url = make_url(str(self.connection_info))\n        drivername = self._rendered_url.drivername\n\n        try:\n            AsyncDriver(drivername)\n            self._driver_is_async = True\n        except ValueError:\n            self._driver_is_async = False\n\n        if self._unique_results is None:\n            self._unique_results = {}\n\n        if self._exit_stack is None:\n            self._start_exit_stack()\n\n    def _start_exit_stack(self):\n        \"\"\"\n        Starts an AsyncExitStack or ExitStack depending on whether driver is async.\n        \"\"\"\n        self._exit_stack = AsyncExitStack() if self._driver_is_async else ExitStack()\n\n    def get_engine(\n        self, **create_engine_kwargs: Dict[str, Any]\n    ) -&gt; Union[Engine, AsyncEngine]:\n        \"\"\"\n        Returns an authenticated engine that can be\n        used to query from databases.\n\n        If an existing engine exists, return that one.\n\n        Returns:\n            The authenticated SQLAlchemy Engine / AsyncEngine.\n\n        Examples:\n            Create an asynchronous engine to PostgreSQL using URL params.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import (\n                SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n            )\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                sqlalchemy_credentials = SqlAlchemyConnector(\n                connection_info=ConnectionComponents(\n                        driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                        username=\"prefect\",\n                        password=\"prefect_password\",\n                        database=\"postgres\"\n                    )\n                )\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n\n            Create a synchronous engine to Snowflake using the `url` kwarg.\n            ```python\n            from prefect import flow\n            from prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n            @flow\n            def sqlalchemy_credentials_flow():\n                url = (\n                    \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                    \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                    \"?warehouse=&lt;warehouse_name&gt;\"\n                )\n                sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n                print(sqlalchemy_credentials.get_engine())\n\n            sqlalchemy_credentials_flow()\n            ```\n        \"\"\"\n        if self._engine is not None:\n            self.logger.debug(\"Reusing existing engine.\")\n            return self._engine\n\n        engine_kwargs = dict(\n            url=self._rendered_url,\n            connect_args=self.connect_args or {},\n            **create_engine_kwargs,\n        )\n        if self._driver_is_async:\n            # no need to await here\n            engine = create_async_engine(**engine_kwargs)\n        else:\n            engine = create_engine(**engine_kwargs)\n        self.logger.info(\"Created a new engine.\")\n\n        if self._engine is None:\n            self._engine = engine\n\n        return engine\n\n    def get_connection(\n        self, begin: bool = True, **connect_kwargs: Dict[str, Any]\n    ) -&gt; Union[Connection, AsyncConnection]:\n        \"\"\"\n        Returns a connection that can be used to query from databases.\n\n        Args:\n            begin: Whether to begin a transaction on the connection; if True, if\n                any operations fail, the entire transaction will be rolled back.\n            **connect_kwargs: Additional keyword arguments to pass to either\n                `engine.begin` or engine.connect`.\n\n        Returns:\n            The SQLAlchemy Connection / AsyncConnection.\n\n        Examples:\n            Create an synchronous connection as a context-managed transaction.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            with sqlalchemy_connector.get_connection(begin=False) as connection:\n                connection.execute(\"SELECT * FROM table LIMIT 1;\")\n            ```\n\n            Create an asynchronous connection as a context-managed transacation.\n            ```python\n            import asyncio\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            async with sqlalchemy_connector.get_connection(begin=False) as connection:\n                asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n            ```\n        \"\"\"  # noqa: E501\n        engine = self.get_engine()\n        if begin:\n            connection = engine.begin(**connect_kwargs)\n        else:\n            connection = engine.connect(**connect_kwargs)\n        self.logger.info(\"Created a new connection.\")\n        return connection\n\n    def get_client(\n        self,\n        client_type: Literal[\"engine\", \"connection\"],\n        **get_client_kwargs: Dict[str, Any],\n    ) -&gt; Union[Engine, AsyncEngine, Connection, AsyncConnection]:\n        \"\"\"\n        Returns either an engine or connection that can be used to query from databases.\n\n        Args:\n            client_type: Select from either 'engine' or 'connection'.\n            **get_client_kwargs: Additional keyword arguments to pass to\n                either `get_engine` or `get_connection`.\n\n        Returns:\n            The authenticated SQLAlchemy engine or connection.\n\n        Examples:\n            Create an engine.\n            ```python\n            from prefect_sqlalchemy import SqlalchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            engine = sqlalchemy_connector.get_client(client_type=\"engine\")\n            ```\n\n            Create a context managed connection.\n            ```python\n            from prefect_sqlalchemy import SqlalchemyConnector\n\n            sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n            with sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n                ...\n            ```\n        \"\"\"  # noqa: E501\n        if client_type == \"engine\":\n            client = self.get_engine(**get_client_kwargs)\n        elif client_type == \"connection\":\n            client = self.get_connection(**get_client_kwargs)\n        else:\n            raise ValueError(\n                f\"{client_type!r} is not supported; choose from engine or connection.\"\n            )\n        return client\n\n    async def _async_sync_execute(\n        self,\n        connection: Union[Connection, AsyncConnection],\n        *execute_args: Tuple[Any],\n        **execute_kwargs: Dict[str, Any],\n    ) -&gt; CursorResult:\n        \"\"\"\n        Execute the statement asynchronously or synchronously.\n        \"\"\"\n        # can't use run_sync_in_worker_thread:\n        # ProgrammingError: (sqlite3.ProgrammingError) SQLite objects created in a\n        # thread can only be used in that same thread.\n        result_set = connection.execute(*execute_args, **execute_kwargs)\n\n        if self._driver_is_async:\n            result_set = await result_set\n            await connection.commit()  # very important\n        elif SQLALCHEMY_VERSION.startswith(\"2.\"):\n            connection.commit()\n        return result_set\n\n    @asynccontextmanager\n    async def _manage_connection(self, **get_connection_kwargs: Dict[str, Any]):\n        if self._driver_is_async:\n            async with self.get_connection(**get_connection_kwargs) as connection:\n                yield connection\n        else:\n            with self.get_connection(**get_connection_kwargs) as connection:\n                yield connection\n\n    async def _get_result_set(\n        self, *execute_args: Tuple[Any], **execute_kwargs: Dict[str, Any]\n    ) -&gt; CursorResult:\n        \"\"\"\n        Returns a new or existing result set based on whether the inputs\n        are unique.\n\n        Args:\n            *execute_args: Args to pass to execute.\n            **execute_kwargs: Keyword args to pass to execute.\n\n        Returns:\n            The result set from the operation.\n        \"\"\"  # noqa: E501\n        input_hash = hash_objects(*execute_args, **execute_kwargs)\n        assert input_hash is not None, (\n            \"We were not able to hash your inputs, \"\n            \"which resulted in an unexpected data return; \"\n            \"please open an issue with a reproducible example.\"\n        )\n\n        if input_hash not in self._unique_results.keys():\n            if self._driver_is_async:\n                connection = await self._exit_stack.enter_async_context(\n                    self.get_connection()\n                )\n            else:\n                connection = self._exit_stack.enter_context(self.get_connection())\n            result_set = await self._async_sync_execute(\n                connection, *execute_args, **execute_kwargs\n            )\n            # implicitly store the connection by storing the result set\n            # which points to its parent connection\n            self._unique_results[input_hash] = result_set\n        else:\n            result_set = self._unique_results[input_hash]\n        return result_set\n\n    def _reset_cursor_results(self) -&gt; None:\n        \"\"\"\n        Closes all the existing cursor results.\n        \"\"\"\n        input_hashes = tuple(self._unique_results.keys())\n        for input_hash in input_hashes:\n            try:\n                cursor_result = self._unique_results.pop(input_hash)\n                cursor_result.close()\n            except Exception as exc:\n                self.logger.warning(\n                    f\"Failed to close connection for input hash {input_hash!r}: {exc}\"\n                )\n\n    @sync_compatible\n    async def reset_connections(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened connections and their results.\n\n        Examples:\n            Resets connections so `fetch_*` methods return new results.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                results = database.fetch_one(\"SELECT * FROM customers\")\n                database.reset_connections()\n                results = database.fetch_one(\"SELECT * FROM customers\")\n            ```\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} has no synchronous connections. \"\n                f\"Please use the `reset_async_connections` method instead.\"\n            )\n\n        if self._exit_stack is None:\n            self.logger.info(\"There were no connections to reset.\")\n            return\n\n        self._reset_cursor_results()\n        self._exit_stack.close()\n        self.logger.info(\"Reset opened connections and their results.\")\n\n    async def reset_async_connections(self) -&gt; None:\n        \"\"\"\n        Tries to close all opened connections and their results.\n\n        Examples:\n            Resets connections so `fetch_*` methods return new results.\n            ```python\n            import asyncio\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            async def example_run():\n                async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                    results = await database.fetch_one(\"SELECT * FROM customers\")\n                    await database.reset_async_connections()\n                    results = await database.fetch_one(\"SELECT * FROM customers\")\n\n            asyncio.run(example_run())\n            ```\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} has no asynchronous connections. \"\n                f\"Please use the `reset_connections` method instead.\"\n            )\n\n        if self._exit_stack is None:\n            self.logger.info(\"There were no connections to reset.\")\n            return\n\n        self._reset_cursor_results()\n        await self._exit_stack.aclose()\n        self.logger.info(\"Reset opened connections and their results.\")\n\n    @sync_compatible\n    async def fetch_one(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; Tuple[Any]:\n        \"\"\"\n        Fetch a single result from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch a row repeatedly.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = True\n                while results:\n                    results = database.fetch_one(\"SELECT * FROM customers\")\n                    print(results)\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        self.logger.debug(\"Preparing to fetch one row.\")\n        row = result_set.fetchone()\n        return row\n\n    @sync_compatible\n    async def fetch_many(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        size: Optional[int] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch a limited number of results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            size: The number of results to return; if None or 0, uses the value of\n                `fetch_size` configured on the block.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch two rows repeatedly.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n                print(results)\n                results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n                print(results)\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        size = size or self.fetch_size\n        self.logger.debug(f\"Preparing to fetch {size} rows.\")\n        rows = result_set.fetchmany(size=size)\n        return rows\n\n    @sync_compatible\n    async def fetch_all(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; List[Tuple[Any]]:\n        \"\"\"\n        Fetch all results from the database.\n\n        Repeated calls using the same inputs to *any* of the fetch methods of this\n        block will skip executing the operation again, and instead,\n        return the next set of results from the previous execution,\n        until the reset_cursors method is called.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Returns:\n            A list of tuples containing the data returned by the database,\n                where each row is a tuple and each column is a value in the tuple.\n\n        Examples:\n            Create a table, insert three rows into it, and fetch all where name is 'Me'.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n                results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n            ```\n        \"\"\"  # noqa\n        result_set = await self._get_result_set(\n            text(operation), parameters, execution_options=execution_options\n        )\n        self.logger.debug(\"Preparing to fetch all rows.\")\n        rows = result_set.fetchall()\n        return rows\n\n    @sync_compatible\n    async def execute(\n        self,\n        operation: str,\n        parameters: Optional[Dict[str, Any]] = None,\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes an operation on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            parameters: The parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Examples:\n            Create a table and insert one row into it.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n                )\n            ```\n        \"\"\"  # noqa\n        async with self._manage_connection(begin=False) as connection:\n            await self._async_sync_execute(\n                connection,\n                text(operation),\n                parameters,\n                execution_options=execution_options,\n            )\n        self.logger.info(f\"Executed the operation, {operation!r}\")\n\n    @sync_compatible\n    async def execute_many(\n        self,\n        operation: str,\n        seq_of_parameters: List[Dict[str, Any]],\n        **execution_options: Dict[str, Any],\n    ) -&gt; None:\n        \"\"\"\n        Executes many operations on the database. This method is intended to be used\n        for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n        Unlike the fetch methods, this method will always execute the operation\n        upon calling.\n\n        Args:\n            operation: The SQL query or other operation to be executed.\n            seq_of_parameters: The sequence of parameters for the operation.\n            **execution_options: Options to pass to `Connection.execution_options`.\n\n        Examples:\n            Create a table and insert two rows into it.\n            ```python\n            from prefect_sqlalchemy import SqlAlchemyConnector\n\n            with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n                database.execute_many(\n                    \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                    seq_of_parameters=[\n                        {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                        {\"name\": \"Unknown\", \"address\": \"Space\"},\n                        {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                    ],\n                )\n            ```\n        \"\"\"  # noqa\n        async with self._manage_connection(begin=False) as connection:\n            await self._async_sync_execute(\n                connection,\n                text(operation),\n                seq_of_parameters,\n                execution_options=execution_options,\n            )\n        self.logger.info(\n            f\"Executed {len(seq_of_parameters)} operations based off {operation!r}.\"\n        )\n\n    async def __aenter__(self):\n        \"\"\"\n        Start an asynchronous database engine upon entry.\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} cannot be run asynchronously. \"\n                f\"Please use the `with` syntax.\"\n            )\n        return self\n\n    async def __aexit__(self, *args):\n        \"\"\"\n        Dispose the asynchronous database engine upon exit.\n        \"\"\"\n        await self.aclose()\n\n    async def aclose(self):\n        \"\"\"\n        Closes async connections and its cursors.\n        \"\"\"\n        if not self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} is not asynchronous. \"\n                f\"Please use the `close` method instead.\"\n            )\n        try:\n            await self.reset_async_connections()\n        finally:\n            if self._engine is not None:\n                await self._engine.dispose()\n                self._engine = None\n                self.logger.info(\"Disposed the engine.\")\n\n    def __enter__(self):\n        \"\"\"\n        Start an synchronous database engine upon entry.\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} cannot be run synchronously. \"\n                f\"Please use the `async with` syntax.\"\n            )\n        return self\n\n    def __exit__(self, *args):\n        \"\"\"\n        Dispose the synchronous database engine upon exit.\n        \"\"\"\n        self.close()\n\n    def close(self):\n        \"\"\"\n        Closes sync connections and its cursors.\n        \"\"\"\n        if self._driver_is_async:\n            raise RuntimeError(\n                f\"{self._rendered_url.drivername} is not synchronous. \"\n                f\"Please use the `aclose` method instead.\"\n            )\n\n        try:\n            self.reset_connections()\n        finally:\n            if self._engine is not None:\n                self._engine.dispose()\n                self._engine = None\n                self.logger.info(\"Disposed the engine.\")\n\n    def __getstate__(self):\n        \"\"\"Allows the block to be pickleable.\"\"\"\n        data = self.__dict__.copy()\n        data.update({k: None for k in {\"_engine\", \"_exit_stack\", \"_unique_results\"}})\n        return data\n\n    def __setstate__(self, data: dict):\n        \"\"\"Upon loading back, restart the engine and results.\"\"\"\n        self.__dict__.update(data)\n\n        if self._unique_results is None:\n            self._unique_results = {}\n\n        if self._exit_stack is None:\n            self._start_exit_stack()\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.Config","title":"<code>Config</code>","text":"<p>Configuration of pydantic.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>class Config:\n    \"\"\"Configuration of pydantic.\"\"\"\n\n    # Support serialization of the 'URL' type\n    arbitrary_types_allowed = True\n    json_encoders = {URL: lambda u: u.render_as_string()}\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.aclose","title":"<code>aclose</code>  <code>async</code>","text":"<p>Closes async connections and its cursors.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>async def aclose(self):\n    \"\"\"\n    Closes async connections and its cursors.\n    \"\"\"\n    if not self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} is not asynchronous. \"\n            f\"Please use the `close` method instead.\"\n        )\n    try:\n        await self.reset_async_connections()\n    finally:\n        if self._engine is not None:\n            await self._engine.dispose()\n            self._engine = None\n            self.logger.info(\"Disposed the engine.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.block_initialization","title":"<code>block_initialization</code>","text":"<p>Initializes the engine.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def block_initialization(self):\n    \"\"\"\n    Initializes the engine.\n    \"\"\"\n    super().block_initialization()\n\n    if isinstance(self.connection_info, ConnectionComponents):\n        self._rendered_url = self.connection_info.create_url()\n    else:\n        # make rendered url from string\n        self._rendered_url = make_url(str(self.connection_info))\n    drivername = self._rendered_url.drivername\n\n    try:\n        AsyncDriver(drivername)\n        self._driver_is_async = True\n    except ValueError:\n        self._driver_is_async = False\n\n    if self._unique_results is None:\n        self._unique_results = {}\n\n    if self._exit_stack is None:\n        self._start_exit_stack()\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.close","title":"<code>close</code>","text":"<p>Closes sync connections and its cursors.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def close(self):\n    \"\"\"\n    Closes sync connections and its cursors.\n    \"\"\"\n    if self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} is not synchronous. \"\n            f\"Please use the `aclose` method instead.\"\n        )\n\n    try:\n        self.reset_connections()\n    finally:\n        if self._engine is not None:\n            self._engine.dispose()\n            self._engine = None\n            self.logger.info(\"Disposed the engine.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.dict","title":"<code>dict</code>","text":"<p>Convert to a dictionary.</p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def dict(self, *args, **kwargs) -&gt; Dict:\n    \"\"\"\n    Convert to a dictionary.\n    \"\"\"\n    # Support serialization of the 'URL' type\n    d = super().dict(*args, **kwargs)\n    d[\"_rendered_url\"] = SecretStr(\n        self._rendered_url.render_as_string(hide_password=False)\n    )\n    return d\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.execute","title":"<code>execute</code>  <code>async</code>","text":"<p>Executes an operation on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create a table and insert one row into it. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n    )\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def execute(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes an operation on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Examples:\n        Create a table and insert one row into it.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                parameters={\"name\": \"Marvin\", \"address\": \"Highway 42\"},\n            )\n        ```\n    \"\"\"  # noqa\n    async with self._manage_connection(begin=False) as connection:\n        await self._async_sync_execute(\n            connection,\n            text(operation),\n            parameters,\n            execution_options=execution_options,\n        )\n    self.logger.info(f\"Executed the operation, {operation!r}\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.execute_many","title":"<code>execute_many</code>  <code>async</code>","text":"<p>Executes many operations on the database. This method is intended to be used for operations that do not return data, such as INSERT, UPDATE, or DELETE.</p> <p>Unlike the fetch methods, this method will always execute the operation upon calling.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>seq_of_parameters</code> <code>List[Dict[str, Any]]</code> <p>The sequence of parameters for the operation.</p> required <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Examples:</p> <p>Create a table and insert two rows into it. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def execute_many(\n    self,\n    operation: str,\n    seq_of_parameters: List[Dict[str, Any]],\n    **execution_options: Dict[str, Any],\n) -&gt; None:\n    \"\"\"\n    Executes many operations on the database. This method is intended to be used\n    for operations that do not return data, such as INSERT, UPDATE, or DELETE.\n\n    Unlike the fetch methods, this method will always execute the operation\n    upon calling.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        seq_of_parameters: The sequence of parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Examples:\n        Create a table and insert two rows into it.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n        ```\n    \"\"\"  # noqa\n    async with self._manage_connection(begin=False) as connection:\n        await self._async_sync_execute(\n            connection,\n            text(operation),\n            seq_of_parameters,\n            execution_options=execution_options,\n        )\n    self.logger.info(\n        f\"Executed {len(seq_of_parameters)} operations based off {operation!r}.\"\n    )\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_all","title":"<code>fetch_all</code>  <code>async</code>","text":"<p>Fetch all results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch all where name is 'Me'. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_all(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch all results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch all where name is 'Me'.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = database.fetch_all(\"SELECT * FROM customers WHERE name = :name\", parameters={\"name\": \"Me\"})\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    self.logger.debug(\"Preparing to fetch all rows.\")\n    rows = result_set.fetchall()\n    return rows\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_many","title":"<code>fetch_many</code>  <code>async</code>","text":"<p>Fetch a limited number of results from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>size</code> <code>Optional[int]</code> <p>The number of results to return; if None or 0, uses the value of <code>fetch_size</code> configured on the block.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch two rows repeatedly. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n    print(results)\n    results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n    print(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_many(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    size: Optional[int] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Fetch a limited number of results from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        size: The number of results to return; if None or 0, uses the value of\n            `fetch_size` configured on the block.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch two rows repeatedly.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n            print(results)\n            results = database.fetch_many(\"SELECT * FROM customers\", size=2)\n            print(results)\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    size = size or self.fetch_size\n    self.logger.debug(f\"Preparing to fetch {size} rows.\")\n    rows = result_set.fetchmany(size=size)\n    return rows\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.fetch_one","title":"<code>fetch_one</code>  <code>async</code>","text":"<p>Fetch a single result from the database.</p> <p>Repeated calls using the same inputs to any of the fetch methods of this block will skip executing the operation again, and instead, return the next set of results from the previous execution, until the reset_cursors method is called.</p> <p>Parameters:</p> Name Type Description Default <code>operation</code> <code>str</code> <p>The SQL query or other operation to be executed.</p> required <code>parameters</code> <code>Optional[Dict[str, Any]]</code> <p>The parameters for the operation.</p> <code>None</code> <code>**execution_options</code> <code>Dict[str, Any]</code> <p>Options to pass to <code>Connection.execution_options</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Tuple[Any]</code> <p>A list of tuples containing the data returned by the database, where each row is a tuple and each column is a value in the tuple.</p> <p>Examples:</p> <p>Create a table, insert three rows into it, and fetch a row repeatedly. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n    database.execute_many(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        seq_of_parameters=[\n            {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n            {\"name\": \"Unknown\", \"address\": \"Space\"},\n            {\"name\": \"Me\", \"address\": \"Myway 88\"},\n        ],\n    )\n    results = True\n    while results:\n        results = database.fetch_one(\"SELECT * FROM customers\")\n        print(results)\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def fetch_one(\n    self,\n    operation: str,\n    parameters: Optional[Dict[str, Any]] = None,\n    **execution_options: Dict[str, Any],\n) -&gt; Tuple[Any]:\n    \"\"\"\n    Fetch a single result from the database.\n\n    Repeated calls using the same inputs to *any* of the fetch methods of this\n    block will skip executing the operation again, and instead,\n    return the next set of results from the previous execution,\n    until the reset_cursors method is called.\n\n    Args:\n        operation: The SQL query or other operation to be executed.\n        parameters: The parameters for the operation.\n        **execution_options: Options to pass to `Connection.execution_options`.\n\n    Returns:\n        A list of tuples containing the data returned by the database,\n            where each row is a tuple and each column is a value in the tuple.\n\n    Examples:\n        Create a table, insert three rows into it, and fetch a row repeatedly.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            database.execute(\"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\")\n            database.execute_many(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                seq_of_parameters=[\n                    {\"name\": \"Ford\", \"address\": \"Highway 42\"},\n                    {\"name\": \"Unknown\", \"address\": \"Space\"},\n                    {\"name\": \"Me\", \"address\": \"Myway 88\"},\n                ],\n            )\n            results = True\n            while results:\n                results = database.fetch_one(\"SELECT * FROM customers\")\n                print(results)\n        ```\n    \"\"\"  # noqa\n    result_set = await self._get_result_set(\n        text(operation), parameters, execution_options=execution_options\n    )\n    self.logger.debug(\"Preparing to fetch one row.\")\n    row = result_set.fetchone()\n    return row\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_client","title":"<code>get_client</code>","text":"<p>Returns either an engine or connection that can be used to query from databases.</p> <p>Parameters:</p> Name Type Description Default <code>client_type</code> <code>Literal['engine', 'connection']</code> <p>Select from either 'engine' or 'connection'.</p> required <code>**get_client_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to either <code>get_engine</code> or <code>get_connection</code>.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Engine, AsyncEngine, Connection, AsyncConnection]</code> <p>The authenticated SQLAlchemy engine or connection.</p> <p>Examples:</p> <p>Create an engine. <pre><code>from prefect_sqlalchemy import SqlalchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nengine = sqlalchemy_connector.get_client(client_type=\"engine\")\n</code></pre></p> <p>Create a context managed connection. <pre><code>from prefect_sqlalchemy import SqlalchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n    ...\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_client(\n    self,\n    client_type: Literal[\"engine\", \"connection\"],\n    **get_client_kwargs: Dict[str, Any],\n) -&gt; Union[Engine, AsyncEngine, Connection, AsyncConnection]:\n    \"\"\"\n    Returns either an engine or connection that can be used to query from databases.\n\n    Args:\n        client_type: Select from either 'engine' or 'connection'.\n        **get_client_kwargs: Additional keyword arguments to pass to\n            either `get_engine` or `get_connection`.\n\n    Returns:\n        The authenticated SQLAlchemy engine or connection.\n\n    Examples:\n        Create an engine.\n        ```python\n        from prefect_sqlalchemy import SqlalchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        engine = sqlalchemy_connector.get_client(client_type=\"engine\")\n        ```\n\n        Create a context managed connection.\n        ```python\n        from prefect_sqlalchemy import SqlalchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with sqlalchemy_connector.get_client(client_type=\"connection\") as conn:\n            ...\n        ```\n    \"\"\"  # noqa: E501\n    if client_type == \"engine\":\n        client = self.get_engine(**get_client_kwargs)\n    elif client_type == \"connection\":\n        client = self.get_connection(**get_client_kwargs)\n    else:\n        raise ValueError(\n            f\"{client_type!r} is not supported; choose from engine or connection.\"\n        )\n    return client\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_connection","title":"<code>get_connection</code>","text":"<p>Returns a connection that can be used to query from databases.</p> <p>Parameters:</p> Name Type Description Default <code>begin</code> <code>bool</code> <p>Whether to begin a transaction on the connection; if True, if any operations fail, the entire transaction will be rolled back.</p> <code>True</code> <code>**connect_kwargs</code> <code>Dict[str, Any]</code> <p>Additional keyword arguments to pass to either <code>engine.begin</code> or engine.connect`.</p> <code>{}</code> <p>Returns:</p> Type Description <code>Union[Connection, AsyncConnection]</code> <p>The SQLAlchemy Connection / AsyncConnection.</p> <p>Examples:</p> <p>Create an synchronous connection as a context-managed transaction. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nwith sqlalchemy_connector.get_connection(begin=False) as connection:\n    connection.execute(\"SELECT * FROM table LIMIT 1;\")\n</code></pre></p> <p>Create an asynchronous connection as a context-managed transacation. <pre><code>import asyncio\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\nsqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\nasync with sqlalchemy_connector.get_connection(begin=False) as connection:\n    asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_connection(\n    self, begin: bool = True, **connect_kwargs: Dict[str, Any]\n) -&gt; Union[Connection, AsyncConnection]:\n    \"\"\"\n    Returns a connection that can be used to query from databases.\n\n    Args:\n        begin: Whether to begin a transaction on the connection; if True, if\n            any operations fail, the entire transaction will be rolled back.\n        **connect_kwargs: Additional keyword arguments to pass to either\n            `engine.begin` or engine.connect`.\n\n    Returns:\n        The SQLAlchemy Connection / AsyncConnection.\n\n    Examples:\n        Create an synchronous connection as a context-managed transaction.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        with sqlalchemy_connector.get_connection(begin=False) as connection:\n            connection.execute(\"SELECT * FROM table LIMIT 1;\")\n        ```\n\n        Create an asynchronous connection as a context-managed transacation.\n        ```python\n        import asyncio\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        sqlalchemy_connector = SqlAlchemyConnector.load(\"BLOCK_NAME\")\n        async with sqlalchemy_connector.get_connection(begin=False) as connection:\n            asyncio.run(connection.execute(\"SELECT * FROM table LIMIT 1;\"))\n        ```\n    \"\"\"  # noqa: E501\n    engine = self.get_engine()\n    if begin:\n        connection = engine.begin(**connect_kwargs)\n    else:\n        connection = engine.connect(**connect_kwargs)\n    self.logger.info(\"Created a new connection.\")\n    return connection\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.get_engine","title":"<code>get_engine</code>","text":"<p>Returns an authenticated engine that can be used to query from databases.</p> <p>If an existing engine exists, return that one.</p> <p>Returns:</p> Type Description <code>Union[Engine, AsyncEngine]</code> <p>The authenticated SQLAlchemy Engine / AsyncEngine.</p> <p>Examples:</p> <p>Create an asynchronous engine to PostgreSQL using URL params. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import (\n    SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n)\n\n@flow\ndef sqlalchemy_credentials_flow():\n    sqlalchemy_credentials = SqlAlchemyConnector(\n    connection_info=ConnectionComponents(\n            driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n            username=\"prefect\",\n            password=\"prefect_password\",\n            database=\"postgres\"\n        )\n    )\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> <p>Create a synchronous engine to Snowflake using the <code>url</code> kwarg. <pre><code>from prefect import flow\nfrom prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n@flow\ndef sqlalchemy_credentials_flow():\n    url = (\n        \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n        \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n        \"?warehouse=&lt;warehouse_name&gt;\"\n    )\n    sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n    print(sqlalchemy_credentials.get_engine())\n\nsqlalchemy_credentials_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>def get_engine(\n    self, **create_engine_kwargs: Dict[str, Any]\n) -&gt; Union[Engine, AsyncEngine]:\n    \"\"\"\n    Returns an authenticated engine that can be\n    used to query from databases.\n\n    If an existing engine exists, return that one.\n\n    Returns:\n        The authenticated SQLAlchemy Engine / AsyncEngine.\n\n    Examples:\n        Create an asynchronous engine to PostgreSQL using URL params.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import (\n            SqlAlchemyConnector, ConnectionComponents, AsyncDriver\n        )\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            sqlalchemy_credentials = SqlAlchemyConnector(\n            connection_info=ConnectionComponents(\n                    driver=AsyncDriver.POSTGRESQL_ASYNCPG,\n                    username=\"prefect\",\n                    password=\"prefect_password\",\n                    database=\"postgres\"\n                )\n            )\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n\n        Create a synchronous engine to Snowflake using the `url` kwarg.\n        ```python\n        from prefect import flow\n        from prefect_sqlalchemy import SqlAlchemyConnector, AsyncDriver\n\n        @flow\n        def sqlalchemy_credentials_flow():\n            url = (\n                \"snowflake://&lt;user_login_name&gt;:&lt;password&gt;\"\n                \"@&lt;account_identifier&gt;/&lt;database_name&gt;\"\n                \"?warehouse=&lt;warehouse_name&gt;\"\n            )\n            sqlalchemy_credentials = SqlAlchemyConnector(url=url)\n            print(sqlalchemy_credentials.get_engine())\n\n        sqlalchemy_credentials_flow()\n        ```\n    \"\"\"\n    if self._engine is not None:\n        self.logger.debug(\"Reusing existing engine.\")\n        return self._engine\n\n    engine_kwargs = dict(\n        url=self._rendered_url,\n        connect_args=self.connect_args or {},\n        **create_engine_kwargs,\n    )\n    if self._driver_is_async:\n        # no need to await here\n        engine = create_async_engine(**engine_kwargs)\n    else:\n        engine = create_engine(**engine_kwargs)\n    self.logger.info(\"Created a new engine.\")\n\n    if self._engine is None:\n        self._engine = engine\n\n    return engine\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.reset_async_connections","title":"<code>reset_async_connections</code>  <code>async</code>","text":"<p>Tries to close all opened connections and their results.</p> <p>Examples:</p> <p>Resets connections so <code>fetch_*</code> methods return new results. <pre><code>import asyncio\nfrom prefect_sqlalchemy import SqlAlchemyConnector\n\nasync def example_run():\n    async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n        results = await database.fetch_one(\"SELECT * FROM customers\")\n        await database.reset_async_connections()\n        results = await database.fetch_one(\"SELECT * FROM customers\")\n\nasyncio.run(example_run())\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>async def reset_async_connections(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened connections and their results.\n\n    Examples:\n        Resets connections so `fetch_*` methods return new results.\n        ```python\n        import asyncio\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        async def example_run():\n            async with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n                results = await database.fetch_one(\"SELECT * FROM customers\")\n                await database.reset_async_connections()\n                results = await database.fetch_one(\"SELECT * FROM customers\")\n\n        asyncio.run(example_run())\n        ```\n    \"\"\"\n    if not self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} has no asynchronous connections. \"\n            f\"Please use the `reset_connections` method instead.\"\n        )\n\n    if self._exit_stack is None:\n        self.logger.info(\"There were no connections to reset.\")\n        return\n\n    self._reset_cursor_results()\n    await self._exit_stack.aclose()\n    self.logger.info(\"Reset opened connections and their results.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.SqlAlchemyConnector.reset_connections","title":"<code>reset_connections</code>  <code>async</code>","text":"<p>Tries to close all opened connections and their results.</p> <p>Examples:</p> <p>Resets connections so <code>fetch_*</code> methods return new results. <pre><code>from prefect_sqlalchemy import SqlAlchemyConnector\n\nwith SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n    results = database.fetch_one(\"SELECT * FROM customers\")\n    database.reset_connections()\n    results = database.fetch_one(\"SELECT * FROM customers\")\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@sync_compatible\nasync def reset_connections(self) -&gt; None:\n    \"\"\"\n    Tries to close all opened connections and their results.\n\n    Examples:\n        Resets connections so `fetch_*` methods return new results.\n        ```python\n        from prefect_sqlalchemy import SqlAlchemyConnector\n\n        with SqlAlchemyConnector.load(\"MY_BLOCK\") as database:\n            results = database.fetch_one(\"SELECT * FROM customers\")\n            database.reset_connections()\n            results = database.fetch_one(\"SELECT * FROM customers\")\n        ```\n    \"\"\"\n    if self._driver_is_async:\n        raise RuntimeError(\n            f\"{self._rendered_url.drivername} has no synchronous connections. \"\n            f\"Please use the `reset_async_connections` method instead.\"\n        )\n\n    if self._exit_stack is None:\n        self.logger.info(\"There were no connections to reset.\")\n        return\n\n    self._reset_cursor_results()\n    self._exit_stack.close()\n    self.logger.info(\"Reset opened connections and their results.\")\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.sqlalchemy_execute","title":"<code>sqlalchemy_execute</code>  <code>async</code>","text":"<p>Executes a SQL DDL or DML statement; useful for creating tables and inserting rows since this task does not return any objects.</p> <p>Parameters:</p> Name Type Description Default <code>statement</code> <code>str</code> <p>The statement to execute against the database.</p> required <code>sqlalchemy_credentials</code> <code>DatabaseCredentials</code> <p>The credentials to use to authenticate.</p> required <code>params</code> <code>Optional[Union[Tuple[Any], Dict[str, Any]]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <p>Examples:</p> <p>Create table named customers and insert values. <pre><code>from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\nfrom prefect_sqlalchemy.database import sqlalchemy_execute\nfrom prefect import flow\n\n@flow\ndef sqlalchemy_execute_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"prefect.db\",\n    )\n    sqlalchemy_execute(\n        \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n        sqlalchemy_credentials,\n    )\n    sqlalchemy_execute(\n        \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n        sqlalchemy_credentials,\n        params={\"name\": \"Marvin\", \"address\": \"Highway 42\"}\n    )\n\nsqlalchemy_execute_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@task\nasync def sqlalchemy_execute(\n    statement: str,\n    sqlalchemy_credentials: \"DatabaseCredentials\",\n    params: Optional[Union[Tuple[Any], Dict[str, Any]]] = None,\n):\n    \"\"\"\n    Executes a SQL DDL or DML statement; useful for creating tables and inserting rows\n    since this task does not return any objects.\n\n    Args:\n        statement: The statement to execute against the database.\n        sqlalchemy_credentials: The credentials to use to authenticate.\n        params: The params to replace the placeholders in the query.\n\n    Examples:\n        Create table named customers and insert values.\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n        from prefect_sqlalchemy.database import sqlalchemy_execute\n        from prefect import flow\n\n        @flow\n        def sqlalchemy_execute_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.SQLITE_AIOSQLITE,\n                database=\"prefect.db\",\n            )\n            sqlalchemy_execute(\n                \"CREATE TABLE IF NOT EXISTS customers (name varchar, address varchar);\",\n                sqlalchemy_credentials,\n            )\n            sqlalchemy_execute(\n                \"INSERT INTO customers (name, address) VALUES (:name, :address);\",\n                sqlalchemy_credentials,\n                params={\"name\": \"Marvin\", \"address\": \"Highway 42\"}\n            )\n\n        sqlalchemy_execute_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"sqlalchemy_query is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector execute_* methods instead.\",\n        DeprecationWarning,\n    )\n    # do not return anything or else results in the error:\n    # This result object does not return rows. It has been closed automatically\n    engine = sqlalchemy_credentials.get_engine()\n    async_supported = sqlalchemy_credentials._driver_is_async\n    async with _connect(engine, async_supported) as connection:\n        await _execute(connection, statement, params, async_supported)\n</code></pre>"},{"location":"integrations/prefect-sqlalchemy/database/#prefect_sqlalchemy.database.sqlalchemy_query","title":"<code>sqlalchemy_query</code>  <code>async</code>","text":"<p>Executes a SQL query; useful for querying data from existing tables.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>The query to execute against the database.</p> required <code>sqlalchemy_credentials</code> <code>DatabaseCredentials</code> <p>The credentials to use to authenticate.</p> required <code>params</code> <code>Optional[Union[Tuple[Any], Dict[str, Any]]]</code> <p>The params to replace the placeholders in the query.</p> <code>None</code> <code>limit</code> <code>Optional[int]</code> <p>The number of rows to fetch. Note, this parameter is executed on the client side, i.e. passed to <code>fetchmany</code>. To limit on the server side, add the <code>LIMIT</code> clause, or the dialect's equivalent clause, like <code>TOP</code>, to the query.</p> <code>None</code> <p>Returns:</p> Type Description <code>List[Tuple[Any]]</code> <p>The fetched results.</p> <p>Examples:</p> <p>Query postgres table with the ID value parameterized. <pre><code>from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\nfrom prefect_sqlalchemy.database import sqlalchemy_query\nfrom prefect import flow\n\n@flow\ndef sqlalchemy_query_flow():\n    sqlalchemy_credentials = DatabaseCredentials(\n        driver=AsyncDriver.SQLITE_AIOSQLITE,\n        database=\"prefect.db\",\n    )\n    result = sqlalchemy_query(\n        \"SELECT * FROM customers WHERE name = :name;\",\n        sqlalchemy_credentials,\n        params={\"name\": \"Marvin\"},\n    )\n    return result\n\nsqlalchemy_query_flow()\n</code></pre></p> Source code in <code>prefect_sqlalchemy/database.py</code> <pre><code>@task\nasync def sqlalchemy_query(\n    query: str,\n    sqlalchemy_credentials: \"DatabaseCredentials\",\n    params: Optional[Union[Tuple[Any], Dict[str, Any]]] = None,\n    limit: Optional[int] = None,\n) -&gt; List[Tuple[Any]]:\n    \"\"\"\n    Executes a SQL query; useful for querying data from existing tables.\n\n    Args:\n        query: The query to execute against the database.\n        sqlalchemy_credentials: The credentials to use to authenticate.\n        params: The params to replace the placeholders in the query.\n        limit: The number of rows to fetch. Note, this parameter is\n            executed on the client side, i.e. passed to `fetchmany`.\n            To limit on the server side, add the `LIMIT` clause, or\n            the dialect's equivalent clause, like `TOP`, to the query.\n\n    Returns:\n        The fetched results.\n\n    Examples:\n        Query postgres table with the ID value parameterized.\n        ```python\n        from prefect_sqlalchemy import DatabaseCredentials, AsyncDriver\n        from prefect_sqlalchemy.database import sqlalchemy_query\n        from prefect import flow\n\n        @flow\n        def sqlalchemy_query_flow():\n            sqlalchemy_credentials = DatabaseCredentials(\n                driver=AsyncDriver.SQLITE_AIOSQLITE,\n                database=\"prefect.db\",\n            )\n            result = sqlalchemy_query(\n                \"SELECT * FROM customers WHERE name = :name;\",\n                sqlalchemy_credentials,\n                params={\"name\": \"Marvin\"},\n            )\n            return result\n\n        sqlalchemy_query_flow()\n        ```\n    \"\"\"\n    warnings.warn(\n        \"sqlalchemy_query is now deprecated and will be removed March 2023; \"\n        \"please use SqlAlchemyConnector fetch_* methods instead.\",\n        DeprecationWarning,\n    )\n    engine = sqlalchemy_credentials.get_engine()\n    async_supported = sqlalchemy_credentials._driver_is_async\n    async with _connect(engine, async_supported) as connection:\n        result = await _execute(connection, query, params, async_supported)\n        # some databases, like sqlite, require a connection still open to fetch!\n        rows = result.fetchall() if limit is None else result.fetchmany(limit)\n    return rows\n</code></pre>"},{"location":"recipes/recipes/","title":"Prefect Recipes","text":"<p>Prefect recipes are common, extensible examples for setting up Prefect in your execution environment with ready-made ingredients such as Dockerfiles, Terraform files, and GitHub Actions.</p> <p>Recipes are useful when you are looking for tutorials on how to deploy a worker, use event-driven flows, set up unit testing, and more.</p> <p>The following are Prefect recipes specific to Prefect 2. You can find a full repository of recipes at https://github.com/PrefectHQ/prefect-recipes and additional recipes at Prefect Discourse.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#recipe-catalog","title":"Recipe catalog","text":"Agent on Azure with Kubernetes <p>                 Configure Prefect on Azure with Kubernetes, running a Prefect agent to execute deployment flow runs.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on ECS Fargate with AWS CLI <p>                 Run a Prefect 2 agent on ECS Fargate using the AWS CLI.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on ECS Fargate with Terraform <p>                 Run a Prefect 2 agent on ECS Fargate using Terraform.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Agent on an Azure VM <p>                 Set up an Azure VM and run a Prefect agent.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Deploy a dlt pipeline on Prefect <p>                 dlt is an open-source Python library that enables the declarative loading of data sources into well-structured tables or datasets by automatically inferring and evolving schemas.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Flow Deployment with GitHub Actions <p>                 Deploy a Prefect flow with storage and infrastructure blocks, update and push Docker image to container registry.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Flow Deployment with GitHub Storage and Docker Infrastructure <p>                 Create a deployment with GitHub as a storage and Docker Container as an infrastructure             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Prefect server on an AKS Cluster <p>                 Deploy a Prefect server to an Azure Kubernetes Service (AKS) Cluster with Azure Blob Storage.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Serverless Prefect with AWS Chalice <p>                 Execute Prefect flows in an AWS Lambda function managed by Chalice.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p> Serverless Workflows with ECSTask Blocks <p>                 Deploy a Prefect agent to AWS ECS Fargate using GitHub Actions and ECSTask infrastructure blocks.             </p> <p>                 Maintained by Prefect </p> <p>                 This recipe uses:             </p> <p> </p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#contributing-recipes","title":"Contributing recipes","text":"<p>We're always looking for new recipe contributions! See the Prefect Recipes repository for details on how you can add your Prefect recipe, share best practices with fellow Prefect users, and earn some swag.</p> <p>Prefect recipes provide a vital cookbook where users can find helpful code examples and, when appropriate, common steps for specific Prefect use cases.</p> <p>We love recipes from anyone who has example code that another Prefect user can benefit from (e.g. a Prefect flow that loads data into Snowflake).</p> <p>Have a blog post, Discourse article, or tutorial you\u2019d like to share as a recipe? All submissions are welcome. Clone the prefect-recipes repo, create a branch, add a link to your recipe to the README, and submit a PR. Have more questions? Read on.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-is-a-recipe","title":"What is a recipe?","text":"<p>A Prefect recipe is like a cookbook recipe: it tells you what you need \u2014 the ingredients \u2014 and some basic steps, but assumes you can put the pieces together. Think of the Hello Fresh meal experience, but for dataflows.</p> <p>A tutorial, on the other hand, is Julia Child holding your hand through the entire cooking process: explaining each ingredient and procedure, demonstrating best practices, pointing out potential problems, and generally making sure you can\u2019t stray from the happy path to a delicious meal.</p> <p>We love Julia, and we love tutorials. But we don\u2019t expect that a Prefect recipe should handhold users through every step and possible contingency of a solution. A recipe can start from an expectation of more expertise and problem-solving ability on the part of the reader.</p> <p>To see an example of a high quality recipe, check out Serverless with AWS Chalice. This recipe includes all of the elements we like to see.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#steps-to-add-your-recipe","title":"Steps to add your recipe","text":"<p>Here\u2019s our guide to creating a recipe:</p> <pre><code># Clone the repository\ngit clone git@github.com:PrefectHQ/prefect-recipes.git\ncd prefect-recipes\n\n# Create and checkout a new branch\n\ngit checkout -b new_recipe_branch_name\n</code></pre> <ol> <li>Add your recipe. Your code may simply be a copy/paste of a single Python file or an entire folder. Unsure of where to add your file or folder? Just add under the <code>flows-advanced/</code> folder. A Prefect Recipes maintainer will help you find the best place for your recipe. Just want to direct others to a project you made, whether it be a repo or a blogpost? Simply link to it in the Prefect Recipes README!</li> <li>(Optional) Write a README.</li> <li>Include a dependencies file, if applicable.</li> <li>Push your code and make a PR to the repository.</li> </ol> <p>That\u2019s it! </p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-makes-a-good-recipe","title":"What makes a good recipe?","text":"<p>Every recipe is useful, as other Prefect users can adapt the recipe to their needs. Particularly good ones help a Prefect user bake a great dataflow solution! Take a look at the prefect-recipes repo to see some examples.</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-are-the-common-ingredients-of-a-good-recipe","title":"What are the common ingredients of a good recipe?","text":"<ul> <li>Easy to understand: Can a user easily follow your recipe? Would a README or code comments help? A simple explanation providing context on how to use the example code is useful, but not required. A good README can set a recipe apart, so we have some additional suggestions for README files below.</li> <li>Code and more: Sometimes a use case is best represented in Python code or shell scripts. Sometimes a configuration file is the most important artifact \u2014 think of a Dockerfile or Terraform file for configuring infrastructure.</li> <li>All-inclusive: Share as much code as you can. Even boilerplate code like Dockerfiles or Terraform or Helm files are useful. Just don\u2019t share company secrets or IP.</li> <li>Specific: Don't worry about generalizing your code, aside from removing anything internal/secret! Other users will extrapolate their own unique solutions from your example.</li> </ul>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#what-are-some-tips-for-a-good-recipe-readme","title":"What are some tips for a good recipe README?","text":"<p>A thoughtful README can take a recipe from good to great. Here are some best practices that we\u2019ve found make for a great recipe README:</p> <ul> <li>Provide a brief explanation of what your recipe demonstrates. This helps users determine quickly whether the recipe is relevant to their needs or answers their questions.</li> <li>List which files are included and what each is meant to do. Each explanation can contain only a few words.</li> <li>Describe any dependencies and prerequisites (in addition to any dependencies you include in a requirements file). This includes both libraries or modules and any services your recipes depends on.</li> <li>If steps are involved or there\u2019s an order to do things, a simple list of steps is helpful.</li> <li>Bonus: troubleshooting steps you encountered to get here or tips where other users might get tripped up.</li> </ul>","tags":["recipes","best practices","examples"],"boost":2},{"location":"recipes/recipes/#next-steps","title":"Next steps","text":"<p>We hope you\u2019ll feel comfortable sharing your Prefect solutions as recipes in the prefect-recipes repo. Collaboration and knowledge sharing are defining attributes of our Prefect Community! </p> <p>Have questions about sharing or using recipes? Reach out on our active Prefect Slack Community!</p> <p>Happy engineering!</p>","tags":["recipes","best practices","examples"],"boost":2},{"location":"tutorial/","title":"Tutorial Overview","text":"<p>Prefect orchestrates workflows \u2014 it simplifies the creation, scheduling, and monitoring of complex data pipelines. You define workflows as Python code and Prefect handles the rest.</p> <p>Prefect also provides error handling, retry mechanisms, and a user-friendly dashboard for monitoring. It's the easiest way to transform any Python function into a unit of work that can be observed and orchestrated.</p> <p>This tutorial provides a guided walk-through of Prefect's core concepts and instructions on how to use them.</p> <p>You will:</p> <ol> <li>Create a flow</li> <li>Add tasks to it</li> <li>Deploy and run the flow locally</li> <li>Create a work pool and run the flow on remote infrastructure</li> </ol> <p>These four topics will get most users to their first production deployment.</p> <p>Advanced users that need more governance and control of their workflow infrastructure can go one step further by:</p> <p>5.Using a worker-based deployment</p> <p>If you're looking for examples of more advanced operations (such as deploying on Kubernetes), check out Prefect's guides.</p> <p>Compared to the Quickstart, this tutorial is a more in-depth guide to Prefect's functionality. You will also see how to customize the Docker image where your flow runs and learn how to run flows on your own infrastructure.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/#prerequisites","title":"Prerequisites","text":"<p>Before you start, make sure you have Python installed in a virtual environment. Then install Prefect:</p> <pre><code>pip install -U prefect\n</code></pre> <p>See the install guide for more detailed instructions.</p> <p>To get the most out of Prefect, you need to connect to a forever-free Prefect Cloud account.</p> <ol> <li>Create a new account or sign in at https://app.prefect.cloud/.</li> <li>Use the <code>prefect cloud login</code> CLI command to authenticate to Prefect Cloud from your environment.</li> </ol> <pre><code>prefect cloud login\n</code></pre> <p>Choose Log in with a web browser and click the Authorize button in the browser window that opens.</p> <p>If you have any issues with browser-based authentication, see the Prefect Cloud docs to learn how to authenticate with a manually created API key.</p> <p>As an alternative to using Prefect Cloud, you can self-host a Prefect server instance. If you choose this option, run <code>prefect server start</code> to start a local Prefect server instance.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/#first-steps-flows","title":"First steps: Flows","text":"<p>Let's begin by learning how to create your first Prefect flow - click here to get started.</p>","tags":["tutorial","getting started","basics","tasks","flows","subflows","deployments","workers","work pools"],"boost":2},{"location":"tutorial/deployments/","title":"Deploying Flows","text":"<p>Reminder to connect to Prefect Cloud or a self-hosted Prefect server instance</p> <p>Some features in this tutorial, such as scheduling, require you to be connected to a Prefect server. If using a self-hosted setup, run <code>prefect server start</code> to run both the webserver and UI. If using Prefect Cloud, make sure you have successfully authenticated your local environment.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#why-deployments","title":"Why deployments?","text":"<p>Some of the most common reasons to use an orchestration tool such as Prefect are for scheduling and event-based triggering. Up to this point, we\u2019ve demonstrated running Prefect flows as scripts, but this means you have been the one triggering and managing flow runs. You can certainly continue to trigger your workflows in this way and use Prefect as a monitoring layer for other schedulers or systems, but you will miss out on many of the other benefits and features that Prefect offers.</p> <p>Deploying a flow exposes an API and UI so that you can:</p> <ul> <li>trigger new runs, cancel active runs, pause scheduled runs, customize parameters, and more</li> <li>remotely configure schedules and automation rules for your deployments</li> <li>dynamically provision infrastructure using workers</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#what-is-a-deployment","title":"What is a deployment?","text":"<p>Deploying a flow is the act of specifying where and how it will run. This information is encapsulated and sent to Prefect as a deployment that contains the crucial metadata needed for remote orchestration. Deployments elevate workflows from functions that you call manually to API-managed entities.</p> <p>Attributes of a deployment include (but are not limited to):</p> <ul> <li>Flow entrypoint: path to your flow function</li> <li>Schedule or Trigger: optional schedule or triggering rules for this deployment</li> <li>Tags: optional text labels for organizing your deployments</li> </ul>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#create-a-deployment","title":"Create a deployment","text":"<p>Using our <code>get_repo_info</code> flow from the previous sections, we can easily create a deployment for it by calling a single method on the flow object: <code>flow.serve</code>.</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.serve(name=\"my-first-deployment\")\n</code></pre> <p>Running this script will do two things:</p> <ul> <li>create a deployment called \"my-first-deployment\" for your flow in the Prefect API</li> <li>stay running to listen for flow runs for this deployment; when a run is found, it will be asynchronously executed within a subprocess</li> </ul> <p>Deployments must be defined in static files</p> <p>Flows can be defined and run interactively, that is, within REPLs or Notebooks. Deployments, on the other hand, require that your flow definition be in a known file (which can be located on a remote filesystem in certain setups, as we'll see in the next section of the tutorial).  </p> <p>Because this deployment has no schedule or triggering automation, you will need to use the UI or API to create runs for it. Let's use the CLI (in a separate terminal window) to create a run for this deployment:</p> <pre><code>prefect deployment run 'get-repo-info/my-first-deployment'\n</code></pre> <p>If you are watching either your terminal or your UI, you should see the newly created run execute successfully! Let's take this example further by adding a schedule and additional metadata.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#additional-options","title":"Additional options","text":"<p>The <code>serve</code> method on flows exposes many options for the deployment. Let's use a few of these options now:</p> <ul> <li><code>cron</code>: a keyword that allows us to set a cron string schedule for the deployment; see schedules for more advanced scheduling options</li> <li><code>tags</code>: a keyword that allows us to tag this deployment and its runs for bookkeeping and filtering purposes</li> <li><code>description</code>: a keyword that allows us to document what this deployment does; by default the description is set from the docstring of the flow function, but we did not document our flow function</li> <li><code>version</code>: a keyword that allows us to track changes to our deployment; by default a hash of the file containing the flow is used; popular options include semver tags or git commit hashes</li> </ul> <p>Let's add these options to our deployment:</p> <pre><code>if __name__ == \"__main__\":\n    get_repo_info.serve(\n        name=\"my-first-deployment\",\n        cron=\"* * * * *\",\n        tags=[\"testing\", \"tutorial\"],\n        description=\"Given a GitHub repository, logs repository statistics for that repo.\",\n        version=\"tutorial/deployments\",\n    )\n</code></pre> <p>When you rerun this script, you will find an updated deployment in the UI that is actively scheduling work! Stop the script in the CLI using <code>CTRL+C</code> and your schedule will be automatically paused.</p> <p><code>.serve</code> is a long-running process</p> <p>For remotely triggered or scheduled runs to be executed, your script with <code>flow.serve</code> must be actively running.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#running-multiple-deployments-at-once","title":"Running multiple deployments at once","text":"<p>This method is useful for creating deployments for single flows, but what if we have two or more flows?  This situation only requires a few additional method calls and imports to get up and running:</p> multi_flow_deployment.py<pre><code>import time\nfrom prefect import flow, serve\n\n\n@flow\ndef slow_flow(sleep: int = 60):\n    \"Sleepy flow - sleeps the provided amount of time (in seconds).\"\n    time.sleep(sleep)\n\n\n@flow\ndef fast_flow():\n    \"Fastest flow this side of the Mississippi.\"\n    return\n\n\nif __name__ == \"__main__\":\n    slow_deploy = slow_flow.to_deployment(name=\"sleeper\", interval=45)\n    fast_deploy = fast_flow.to_deployment(name=\"fast\")\n    serve(slow_deploy, fast_deploy)\n</code></pre> <p>A few observations:</p> <ul> <li>the <code>flow.to_deployment</code> interface exposes the exact same options as <code>flow.serve</code>; this method produces a deployment object</li> <li>the deployments are only registered with the API once <code>serve(...)</code> is called</li> <li>when serving multiple deployments, the only requirement is that they share a Python environment; they can be executed and scheduled independently of each other</li> </ul> <p>Spend some time experimenting with this setup. A few potential next steps for exploration include:</p> <ul> <li>pausing and unpausing the schedule for the \"sleeper\" deployment</li> <li>using the UI to submit ad-hoc runs for the \"sleeper\" deployment with different values for <code>sleep</code></li> <li>cancelling an active run for the \"sleeper\" deployment from the UI (good luck cancelling the \"fast\" one \ud83d\ude09)</li> </ul> <p>Hybrid execution option</p> <p>Another implication of Prefect's deployment interface is that you can choose to use our hybrid execution model. Whether you use Prefect Cloud or host a Prefect server instance yourself, you can run work flows in the environments best suited to their execution. This model allows you efficient use of your infrastructure resources while maintaining the privacy of your code and data. There is no ingress required. For more information read more about our hybrid model.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/deployments/#next-steps","title":"Next steps","text":"<p>Congratulations! You now have your first working deployment.</p> <p>Deploying flows through the <code>serve</code> method is a fast way to start scheduling flows with Prefect. However, if your team has more complex infrastructure requirements or you'd like to have Prefect manage flow execution, you can deploy flows to a work pool.</p> <p>Learn about work pools and how Prefect Cloud can handle infrastructure configuration for you in the next step of the tutorial.</p>","tags":["orchestration","flow runs","deployments","schedules","triggers","tutorial"],"boost":2},{"location":"tutorial/flows/","title":"Flows","text":"<p>Prerequisites</p> <p>This tutorial assumes you have already installed Prefect and connected to Prefect Cloud or a self-hosted server instance. See the prerequisites section of the tutorial for more details.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#what-is-a-flow","title":"What is a flow?","text":"<p>Flows are like functions. They can take inputs, perform work, and return an output. In fact, you can turn any function into a Prefect flow by adding the <code>@flow</code> decorator. When a function becomes a flow, its behavior changes, giving it the following advantages:</p> <ul> <li>All runs of the flow have persistent state. Transitions between states are recorded, allowing for flow execution to be observed and acted upon.</li> <li>Input arguments can be type validated as workflow parameters.</li> <li>Retries can be performed on failure.</li> <li>Timeouts can be enforced to prevent unintentional, long-running workflows.</li> <li>Metadata about flow runs, such as run time and final state, is automatically tracked.</li> <li>They can easily be elevated to a deployment, which exposes a remote API for interacting with it</li> </ul>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#run-your-first-flow","title":"Run your first flow","text":"<p>The simplest way to get started with Prefect is to annotate a Python function with the\u00a0<code>@flow</code>\u00a0decorator. The script below fetches statistics about the main Prefect repository. Note that httpx is an HTTP client library and a dependency of Prefect. Let's turn this function into a Prefect flow and run the script:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow\ndef get_repo_info():\n    url = \"https://api.github.com/repos/PrefectHQ/prefect\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(\"PrefectHQ/prefect repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Running this file will result in some interesting output:</p> <pre><code>12:47:42.792 | INFO | prefect.engine - Created flow run 'ludicrous-warthog' for flow 'get-repo-info'\nPrefectHQ/prefect repository statistics \ud83e\udd13:\nStars \ud83c\udf20 : 12146\nForks \ud83c\udf74 : 1245\n12:47:45.008 | INFO | Flow run 'ludicrous-warthog' - Finished in state Completed()\n</code></pre> <p>Flows can contain arbitrary Python</p> <p>As we can see above, flow definitions can contain arbitrary Python logic.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#parameters","title":"Parameters","text":"<p>As with any Python function, you can pass arguments to a flow. The positional and keyword arguments defined on your flow function are called parameters. Prefect will automatically perform type conversion using any provided type hints. Let's make the repository a string parameter with a default value:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info(repo_name=\"PrefectHQ/marvin\")\n</code></pre> <p>We can call our flow with varying values for the <code>repo_name</code> parameter (including \"bad\" values):</p> <pre><code>python repo_info.py\n</code></pre> <p>Try passing <code>repo_name=\"missing-org/missing-repo\"</code>.</p> <p>You should see</p> <pre><code>HTTPStatusError: Client error '404 Not Found' for url '&lt;https://api.github.com/repos/missing-org/missing-repo&gt;'\n</code></pre> <p>Now navigate to your Prefect dashboard and compare the displays for these two runs.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#logging","title":"Logging","text":"<p>Prefect enables you to log a variety of useful information about your flow and task runs, capturing information about your workflows for purposes such as monitoring, troubleshooting, and auditing. If we navigate to our dashboard and explore the runs we created above, we will notice that the repository statistics are not captured in the flow run logs. Let's fix that by adding some logging to our flow:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow, get_run_logger\n\n\n@flow\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    logger = get_run_logger()\n    logger.info(\"%s repository statistics \ud83e\udd13:\", repo_name)\n    logger.info(f\"Stars \ud83c\udf20 : %d\", repo[\"stargazers_count\"])\n    logger.info(f\"Forks \ud83c\udf74 : %d\", repo[\"forks_count\"])\n</code></pre> <p>Now the output looks more consistent and, more importantly, our statistics are stored in the Prefect backend and displayed in the UI for this flow run:</p> <pre><code>12:47:42.792 | INFO    | prefect.engine - Created flow run 'ludicrous-warthog' for flow 'get-repo-info'\n12:47:43.016 | INFO    | Flow run 'ludicrous-warthog' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n12:47:43.016 | INFO    | Flow run 'ludicrous-warthog' - Stars \ud83c\udf20 : 12146\n12:47:43.042 | INFO    | Flow run 'ludicrous-warthog' - Forks \ud83c\udf74 : 1245\n12:47:45.008 | INFO    | Flow run 'ludicrous-warthog' - Finished in state Completed()\n</code></pre> <p><code>log_prints=True</code></p> <p>We could have achieved the exact same outcome by using Prefect's convenient <code>log_prints</code> keyword argument in the <code>flow</code> decorator:</p> <pre><code>@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    ...\n</code></pre> <p>Logging vs Artifacts</p> <p>The example above is for educational purposes. In general, it is better to use Prefect artifacts for storing metrics and output. Logs are best for tracking progress and debugging errors.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#retries","title":"Retries","text":"<p>So far our script works, but in the future unexpected errors may occur. For example the GitHub API may be temporarily unavailable or rate limited. Retries help make our flow more resilient. Let's add retry functionality to our example above:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/flows/#next-tasks","title":"Next: Tasks","text":"<p>As you have seen, adding a flow decorator converts our Python function to a resilient and observable workflow. In the next section, you'll supercharge this flow by using tasks to break down the workflow's complexity and make it more performant and observable - click here to continue.</p>","tags":["tutorial","getting started","basics","flows","logging","parameters","retries"]},{"location":"tutorial/tasks/","title":"Tasks","text":"","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#what-is-a-task","title":"What is a task?","text":"<p>A task is any Python function decorated with a <code>@task</code> decorator. You can think of a flow as a recipe for connecting a known sequence of tasks together. Tasks, and the dependencies between them, are displayed in the flow run graph, enabling you to break down a complex flow into something you can observe, understand and control at a more granular level. When a function becomes a task, it can be executed concurrently and its return value can be cached.</p> <p>Flows and tasks share some common features:</p> <ul> <li>Both are defined easily using their respective decorator, which accepts settings for that flow / task (see all task settings / flow settings).</li> <li>Each can be given a <code>name</code>, <code>description</code> and <code>tags</code> for organization and bookkeeping.</li> <li>Both provide functionality for retries, timeouts, and other hooks to handle failure and completion events.</li> </ul> <p>Network calls (such as our <code>GET</code> requests to the GitHub API) are particularly useful as tasks because they take advantage of task features such as retries, caching, and concurrency.</p> <p>Tasks may be called from other tasks</p> <p>As of <code>prefect 2.18.x</code>, tasks can be called from within other tasks. This removes the need to use subflows for simple task composition.</p> <p>When to use tasks</p> <p>Not all functions in a flow need be tasks. Use them only when their features are useful.</p> <p>Let's take our flow from before and move the request into a task:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow, task\nfrom typing import Optional\n\n\n@task\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    repo_stats = get_url(url)\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo_stats['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo_stats['forks_count']}\")\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Running the flow in your terminal will result in something like this:</p> <pre><code>09:55:55.412 | INFO    | prefect.engine - Created flow run 'great-ammonite' for flow 'get-repo-info'\n09:55:55.499 | INFO    | Flow run 'great-ammonite' - Created task run 'get_url-0' for task 'get_url'\n09:55:55.500 | INFO    | Flow run 'great-ammonite' - Executing 'get_url-0' immediately...\n09:55:55.825 | INFO    | Task run 'get_url-0' - Finished in state Completed()\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - Stars \ud83c\udf20 : 12157\n09:55:55.827 | INFO    | Flow run 'great-ammonite' - Forks \ud83c\udf74 : 1251\n09:55:55.849 | INFO    | Flow run 'great-ammonite' - Finished in state Completed('All states completed.')\n</code></pre> <p>And you should now see this task run tracked in the UI as well.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#caching","title":"Caching","text":"<p>Tasks support the ability to cache their return value. Caching allows you to efficiently reuse results of tasks that may be expensive to reproduce with every flow run, or reuse cached results if the inputs to a task have not changed.</p> <p>To enable caching, specify a <code>cache_key_fn</code> \u2014 a function that returns a cache key \u2014 on your task. You may optionally provide a <code>cache_expiration</code> timedelta indicating when the cache expires. You can define a task that is cached based on its inputs by using the Prefect <code>task_input_hash</code>. Let's add caching to our <code>get_url</code> task:</p> <pre><code>import httpx\nfrom datetime import timedelta\nfrom prefect import flow, task, get_run_logger\nfrom prefect.tasks import task_input_hash\nfrom typing import Optional\n\n\n@task(cache_key_fn=task_input_hash, \n      cache_expiration=timedelta(hours=1),\n      )\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n</code></pre> <p>You can test this caching behavior by using a personal repository as your workflow parameter - give it a star, or remove a star and see how the output of this task changes (or doesn't) by running your flow multiple times.</p> <p>Task results and caching</p> <p>Task results are cached in memory during a flow run and persisted to your home directory by default. Prefect Cloud only stores the cache key, not the data itself.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#concurrency","title":"Concurrency","text":"<p>Tasks enable concurrency, allowing you to execute multiple tasks asynchronously. This concurrency can greatly enhance the efficiency and performance of your workflows. Let's expand our script to calculate the average open issues per user. This will require making more requests:</p> repo_info.py<pre><code>import httpx\nfrom datetime import timedelta\nfrom prefect import flow, task\nfrom prefect.tasks import task_input_hash\nfrom typing import Optional\n\n\n@task(cache_key_fn=task_input_hash, cache_expiration=timedelta(hours=1))\ndef get_url(url: str, params: Optional[dict[str, any]] = None):\n    response = httpx.get(url, params=params)\n    response.raise_for_status()\n    return response.json()\n\n\ndef get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p]\n\n\n@flow(retries=3, retry_delay_seconds=5, log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    repo_stats = get_url(f\"https://api.github.com/repos/{repo_name}\")\n    issues = get_open_issues(repo_name, repo_stats[\"open_issues_count\"])\n    issues_per_user = len(issues) / len(set([i[\"user\"][\"id\"] for i in issues]))\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo_stats['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo_stats['forks_count']}\")\n    print(f\"Average open issues per user \ud83d\udc8c : {issues_per_user:.2f}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info()\n</code></pre> <p>Now we're fetching the data we need, but the requests are happening sequentially. Tasks expose a <code>submit</code> method that changes the execution from sequential to concurrent. In our specific example, we also need to use the <code>result</code> method because we are unpacking a list of return values:</p> <pre><code>def get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url.submit(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p.result()]\n</code></pre> <p>The logs show that each task is running concurrently:</p> <pre><code>12:45:28.241 | INFO    | prefect.engine - Created flow run 'intrepid-coua' for flow 'get-repo-info'\n12:45:28.311 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-0' for task 'get_url'\n12:45:28.312 | INFO    | Flow run 'intrepid-coua' - Executing 'get_url-0' immediately...\n12:45:28.543 | INFO    | Task run 'get_url-0' - Finished in state Completed()\n12:45:28.583 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-1' for task 'get_url'\n12:45:28.584 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-1' for execution.\n12:45:28.594 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-2' for task 'get_url'\n12:45:28.594 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-2' for execution.\n12:45:28.609 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-4' for task 'get_url'\n12:45:28.610 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-4' for execution.\n12:45:28.624 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-5' for task 'get_url'\n12:45:28.625 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-5' for execution.\n12:45:28.640 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-6' for task 'get_url'\n12:45:28.641 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-6' for execution.\n12:45:28.708 | INFO    | Flow run 'intrepid-coua' - Created task run 'get_url-3' for task 'get_url'\n12:45:28.708 | INFO    | Flow run 'intrepid-coua' - Submitted task run 'get_url-3' for execution.\n12:45:29.096 | INFO    | Task run 'get_url-6' - Finished in state Completed()\n12:45:29.565 | INFO    | Task run 'get_url-2' - Finished in state Completed()\n12:45:29.721 | INFO    | Task run 'get_url-5' - Finished in state Completed()\n12:45:29.749 | INFO    | Task run 'get_url-4' - Finished in state Completed()\n12:45:29.801 | INFO    | Task run 'get_url-3' - Finished in state Completed()\n12:45:29.817 | INFO    | Task run 'get_url-1' - Finished in state Completed()\n12:45:29.820 | INFO    | Flow run 'intrepid-coua' - PrefectHQ/prefect repository statistics \ud83e\udd13:\n12:45:29.820 | INFO    | Flow run 'intrepid-coua' - Stars \ud83c\udf20 : 12159\n12:45:29.821 | INFO    | Flow run 'intrepid-coua' - Forks \ud83c\udf74 : 1251\nAverage open issues per user \ud83d\udc8c : 2.27\n12:45:29.838 | INFO    | Flow run 'intrepid-coua' - Finished in state Completed('All states completed.')\n</code></pre>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#subflows","title":"Subflows","text":"<p>Not only can you call tasks within a flow, but you can also call other flows! Child flows are called\u00a0subflows\u00a0and allow you to efficiently manage, track, and version common multi-task logic.</p> <p>Subflows are a great way to organize your workflows and offer more visibility within the UI.</p> <p>Let's add a <code>flow</code> decorator to our <code>get_open_issues</code> function:</p> <pre><code>@flow\ndef get_open_issues(repo_name: str, open_issues_count: int, per_page: int = 100):\n    issues = []\n    pages = range(1, -(open_issues_count // -per_page) + 1)\n    for page in pages:\n        issues.append(\n            get_url.submit(\n                f\"https://api.github.com/repos/{repo_name}/issues\",\n                params={\"page\": page, \"per_page\": per_page, \"state\": \"open\"},\n            )\n        )\n    return [i for p in issues for i in p.result()]\n</code></pre> <p>Whenever we run the parent flow, a new run will be generated for related functions within that as well. Not only is this run tracked as a subflow run of the main flow, but you can also inspect it independently in the UI!</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/tasks/#next-deployments","title":"Next: Deployments","text":"<p>We now have a flow with tasks, subflows, retries, logging, caching, and concurrent execution. In the next section, we'll see how we can deploy this flow in order to run it on a schedule and/or external infrastructure - click here to learn how to create your first deployment.</p>","tags":["tutorial","getting started","basics","tasks","caching","concurrency","subflows"]},{"location":"tutorial/work-pools/","title":"Work Pools","text":"","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#why-work-pools","title":"Why work pools?","text":"<p>Work pools are a bridge between the Prefect orchestration layer and infrastructure for flow runs that can be dynamically provisioned. To transition from persistent infrastructure to dynamic infrastructure, use <code>flow.deploy</code> instead of <code>flow.serve</code>.</p> <p>Choosing Between <code>flow.deploy()</code> and <code>flow.serve()</code></p> <p>Earlier in the tutorial you used <code>serve</code> to deploy your flows. For many use cases, <code>serve</code> is sufficient to meet scheduling and orchestration needs. Work pools are optional. If infrastructure needs escalate, work pools can become a handy tool. The best part? You're not locked into one method. You can seamlessly combine approaches as needed.</p> <p>Deployment definition methods differ slightly for work pools</p> <p>When you use work-pool-based execution, you define deployments differently. Deployments for workers are configured with <code>deploy</code>, which requires additional configuration. A deployment created with <code>serve</code> cannot be used with a work pool.</p> <p>The primary reason to use work pools is for dynamic infrastructure provisioning and configuration. For example, you might have a workflow that has expensive infrastructure requirements and is run infrequently. In this case, you don't want an idle process running within that infrastructure.</p> <p>Other advantages to using work pools include:</p> <ul> <li>You can configure default infrastructure configurations on your work pools that all jobs inherit and can override.</li> <li>Platform teams can use work pools to expose opinionated (and enforced!) interfaces to the infrastructure that they oversee.</li> <li>Work pools can be used to prioritize (or limit) flow runs through the use of work queues.</li> </ul> <p>Prefect provides several types of work pools. Prefect Cloud provides a Prefect Managed work pool option that is the simplest way to run workflows remotely. A cloud-provider account, such as AWS, is not required with a Prefect Managed work pool.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#set-up-a-work-pool","title":"Set up a work pool","text":"<p>Prefect Cloud</p> <p>This tutorial uses Prefect Cloud to deploy flows to work pools. Managed execution and push work pools are available in Prefect Cloud only. If you are not using Prefect Cloud, please learn about work pools below and then proceed to the next tutorial that uses worker-based work pools.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-a-prefect-managed-work-pool","title":"Create a Prefect Managed work pool","text":"<p>In your terminal, run the following command to set up a work pool named <code>my-managed-pool</code> of type <code>prefect:managed</code>.</p> <pre><code>prefect work-pool create my-managed-pool --type prefect:managed \n</code></pre> <p>Let\u2019s confirm that the work pool was successfully created by running the following command.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>You should see your new <code>my-managed-pool</code> in the output list.</p> <p>Finally, let\u2019s double check that you can see this work pool in the UI.</p> <p>Navigate to the Work Pools tab and verify that you see <code>my-managed-pool</code> listed.</p> <p>Feel free to select Edit from the three-dot menu on right of the work pool card to view the details of your work pool.</p> <p>Work pools contain configuration that is used to provision infrastructure for flow runs. For example, you can specify additional Python packages or environment variables that should be set for all deployments that use this work pool. Note that individual deployments can override the work pool configuration.</p> <p>Now that you\u2019ve set up your work pool, we can deploy a flow to this work pool. Let's deploy your tutorial flow to <code>my-managed-pool</code>.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-the-deployment","title":"Create the deployment","text":"<p>From our previous steps, we now have:</p> <ol> <li>A flow</li> <li>A work pool</li> </ol> <p>Let's update our <code>repo_info.py</code> file to create a deployment in Prefect Cloud.</p> <p>The updates that we need to make to <code>repo_info.py</code> are:</p> <ol> <li>Change <code>flow.serve</code> to <code>flow.deploy</code>.</li> <li>Tell <code>flow.deploy</code> which work pool to deploy to.</li> </ol> <p>Here's what the updated <code>repo_info.py</code> looks like:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.from_source(\n        source=\"https://github.com/prefecthq/demos.git\", \n        entrypoint=\"repo_info.py:get_repo_info\"\n    ).deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-managed-pool\", \n    )\n</code></pre> <p>In the <code>from_source</code> method, we specify the source of our flow code.</p> <p>In the <code>deploy</code> method, we specify the name of our deployment and the name of the work pool that we created earlier.</p> <p>You can store your flow code in any of several types of remote storage. In this example, we use a GitHub repository, but you could use a Docker image, as you'll see in an upcoming section of the tutorial. Alternatively, you could store your flow code in cloud provider storage such as AWS S3, or within a different git-based cloud provider such as GitLab or Bitbucket.</p> <p>Note</p> <p>In the example above, we store our code in a GitHub repository. If you make changes to the flow code, you will need to push those changes to your own GitHub account and update the <code>source</code> argument of <code>from_source</code> to point to your repository.</p> <p>Now that you've updated your script, you can run it to register your deployment on Prefect Cloud:</p> <pre><code>python repo_info.py\n</code></pre> <p>You should see a message in the CLI that your deployment was created with instructions for how to run it.</p> <pre><code>Successfully created/updated all deployments!\n\n                       Deployments                       \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Name                              \u2503 Status  \u2503 Details \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 get-repo-info/my-first-deployment | applied \u2502         \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nTo schedule a run for this deployment, use the following command:\n\n        $ prefect deployment run 'get-repo-info/my-first-deployment'\n\n\nYou can also run your flow via the Prefect UI: https://app.prefect.cloud/account/\nabc/workspace/123/deployments/deployment/xyz\n</code></pre> <p>Navigate to your Prefect Cloud UI and view your new deployment. Click the Run button to trigger a run of your deployment.</p> <p>Because this deployment was configured with a Prefect Managed work pool, Prefect Cloud will run your flow on your behalf.</p> <p>View the logs in the UI.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#schedule-a-deployment-run","title":"Schedule a deployment run","text":"<p>Now everything is set up for us to submit a flow-run to the work pool. Go ahead and run the deployment from the CLI or the UI.</p> <pre><code>prefect deployment run 'get_repo_info/my-deployment'\n</code></pre> <p>Prefect Managed work pools are a great way to get started with Prefect. See the Managed Execution guide for more details.</p> <p>Many users will find that they need more control over the infrastructure that their flows run on. Prefect Cloud's push work pools are a popular option in those cases.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#push-work-pools-with-automatic-infrastructure-provisioning","title":"Push work pools with automatic infrastructure provisioning","text":"<p>Serverless push work pools scale infinitely and provide more configuration options than Prefect Managed work pools.</p> <p>Prefect provides push work pools for AWS ECS on Fargate, Azure Container Instances, Google Cloud Run, and Modal. To use a push work pool, you will need an account with sufficient permissions on the cloud provider that you want to use. We'll use GCP for this example.</p> <p>Setting up the cloud provider pieces for infrastructure can be tricky and time consuming. Fortunately, Prefect can automatically provision infrastructure for you and wire it all together to work with your push work pool.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#create-a-push-work-pool-with-automatic-infrastructure-provisioning","title":"Create a push work pool with automatic infrastructure provisioning","text":"<p>In your terminal, run the following command to set up a push work pool.</p> <p>Install the gcloud CLI and authenticate with your GCP project.</p> <p>If you already have the gcloud CLI installed, be sure to update to the latest version with <code>gcloud components update</code>.</p> <p>You will need the following permissions in your GCP project:</p> <ul> <li>resourcemanager.projects.list</li> <li>serviceusage.services.enable</li> <li>iam.serviceAccounts.create</li> <li>iam.serviceAccountKeys.create</li> <li>resourcemanager.projects.setIamPolicy</li> <li>artifactregistry.repositories.create</li> </ul> <p>Docker is also required to build and push images to your registry. You can install Docker here.</p> <p>Run the following command to set up a work pool named <code>my-cloud-run-pool</code> of type <code>cloud-run:push</code>.</p> <pre><code>prefect work-pool create --type cloud-run:push --provision-infra my-cloud-run-pool \n</code></pre> <p>Using the <code>--provision-infra</code> flag allows you to select a GCP project to use for your work pool and automatically configure it to be ready to execute flows via Cloud Run. In your GCP project, this command will activate the Cloud Run API, create a service account, and create a key for the service account, if they don't already exist. In your Prefect workspace, this command will create a <code>GCPCredentials</code> block for storing the service account key.</p> <p>Here's an abbreviated example output from running the command:</p> <pre><code>\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Provisioning infrastructure for your work pool my-cloud-run-pool will require:                           \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in GCP project central-kit-405415 in region us-central1                                      \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Activate the Cloud Run API for your project                                                    \u2502\n\u2502         - Activate the Artifact Registry API for your project                                            \u2502\n\u2502         - Create an Artifact Registry repository named prefect-images                                    \u2502\n\u2502         - Create a service account for managing Cloud Run jobs: prefect-cloud-run                        \u2502\n\u2502             - Service account will be granted the following roles:                                       \u2502\n\u2502                 - Service Account User                                                                   \u2502\n\u2502                 - Cloud Run Developer                                                                    \u2502\n\u2502         - Create a key for service account prefect-cloud-run                                             \u2502\n\u2502                                                                                                          \u2502\n\u2502     Updates in Prefect workspace                                                                         \u2502\n\u2502                                                                                                          \u2502\n\u2502         - Create GCP credentials block my--pool-push-pool-credentials to store the service account key   \u2502\n\u2502                                                                                                          \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\nProceed with infrastructure provisioning? [y/n]: y\nActivating Cloud Run API\nActivating Artifact Registry API\nCreating Artifact Registry repository\nConfiguring authentication to Artifact Registry\nSetting default Docker build namespace\nCreating service account\nAssigning roles to service account\nCreating service account key\nCreating GCP credentials block\nProvisioning Infrastructure \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 100% 0:00:00\nInfrastructure successfully provisioned!\nCreated work pool 'my-cloud-run-pool'!\n</code></pre> <p>After infrastructure provisioning completes, you will be logged into your new Artifact Registry repository and the default Docker build namespace will be set to the URL of the repository.</p> <p>While the default namespace is set, any images you build without specifying a registry or username/organization will be pushed to the repository.</p> <p>To take advantage of this functionality, you can write your deploy script like this:</p> example_deploy_script.py<pre><code>from prefect import flow                                                       \nfrom prefect.deployments import DeploymentImage                                \n\n\n@flow(log_prints=True)\ndef my_flow(name: str = \"world\"):\n    print(f\"Hello {name}! I'm a flow running on Cloud Run!\")\n\n\nif __name__ == \"__main__\":                                                     \n    my_flow.deploy(                                                            \n        name=\"my-deployment\",\n        work_pool_name=\"above-ground\",\n        cron=\"0 1 * * *\",\n        image=DeploymentImage(\n            name=\"my-image:latest\",\n            platform=\"linux/amd64\",\n        )\n    )\n</code></pre> <p>Run the script to create the deployment on the Prefect Cloud server.</p> <p>Running this script will build a Docker image with the tag <code>&lt;region&gt;-docker.pkg.dev/&lt;project&gt;/&lt;repository-name&gt;/my-image:latest</code> and push it to your repository.</p> <p>Tip</p> <p>Make sure you have Docker running locally before running this script.</p> <p>Note that you only need to include an object of the <code>DeploymentImage</code> class with the argument <code>platform=\"linux/amd64</code> if you're building your image on a machine with an ARM-based processor. Otherwise, you could just pass <code>image=\"my-image:latest\"</code> to <code>deploy</code>.</p> <p>Also note that the <code>cron</code> argument will schedule the deployment to run at 1am every day. See the schedules docs for more information on scheduling options.</p> <p>See the Push Work Pool guide for more details and example commands for each cloud provider.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/work-pools/#next-step","title":"Next step","text":"<p>Congratulations! You've learned how to deploy flows to work pools. If these work pool options meet all of your needs, we encourage you to go deeper with the concepts docs or explore our how-to guides to see examples of particular Prefect use cases.</p> <p>However, if you need more control over your infrastructure, want to run your workflows in Kubernetes, or are running a self-hosted Prefect server instance, we encourage you to see the next section of the tutorial. There you'll learn how to use work pools that rely on a worker and see how to customize Docker images for container-based infrastructure.</p>","tags":["work pools","orchestration","flow runs","deployments","tutorial"],"boost":2},{"location":"tutorial/workers/","title":"Workers","text":"","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#prerequisites","title":"Prerequisites","text":"<p>Docker installed and running on your machine.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#why-workers","title":"Why workers","text":"<p>In the previous section of the tutorial, you learned how work pools are a bridge between the Prefect orchestration layer and infrastructure for flow runs that can be dynamically provisioned. You saw how you can transition from persistent infrastructure to dynamic infrastructure by using <code>flow.deploy</code> instead of <code>flow.serve</code>.</p> <p>Work pools that rely on client-side workers take this a step further by enabling you to run work flows in your own Docker containers, Kubernetes clusters, and serverless environments such as AWS ECS, Azure Container Instances, and GCP Cloud Run.</p> <p>The architecture of a worker-based work pool deployment can be summarized with the following diagram:</p> <pre><code>graph TD\n    subgraph your_infra[\"Your Execution Environment\"]\n        worker[\"Worker\"]\n    subgraph flow_run_infra[Flow Run Infra]\n     flow_run_a((\"Flow Run A\"))\n    end\n    subgraph flow_run_infra_2[Flow Run Infra]\n     flow_run_b((\"Flow Run B\"))\n    end      \n    end\n\n    subgraph api[\"Prefect API\"]\n    Deployment --&gt; |assigned to| work_pool\n        work_pool([\"Work Pool\"])\n    end\n\n    worker --&gt; |polls| work_pool\n    worker --&gt; |creates| flow_run_infra\n    worker --&gt; |creates| flow_run_infra_2</code></pre> <p><sup>Notice above that the worker is in charge of provisioning the flow run infrastructure. In context of this tutorial, that flow run infrastructure is an ephemeral Docker container to host each flow run. Different worker types create different types of flow run infrastructure.</sup></p> <p>Now that we\u2019ve reviewed the concepts of a work pool and worker, let\u2019s create them so that you can deploy your tutorial flow, and execute it later using the Prefect API.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#set-up-a-work-pool-and-worker","title":"Set up a work pool and worker","text":"<p>For this tutorial you will create a Docker type work pool via the CLI.</p> <p>Using the Docker work pool type means that all work sent to this work pool will run within a dedicated Docker container using a Docker client available to the worker.</p> <p>Other work pool types</p> <p>There are work pool types for serverless computing environments such as AWS ECS, Azure Container Instances, Google Cloud Run, and Vertex AI. Kubernetes is also a popular work pool type.</p> <p>These options are expanded upon in various How-to Guides.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#create-a-work-pool","title":"Create a work pool","text":"<p>In your terminal, run the following command to set up a Docker type work pool.</p> <pre><code>prefect work-pool create --type docker my-docker-pool\n</code></pre> <p>Let\u2019s confirm that the work pool was successfully created by running the following command in the same terminal.</p> <pre><code>prefect work-pool ls\n</code></pre> <p>You should see your new <code>my-docker-pool</code> listed in the output.</p> <p>Finally, let\u2019s double check that you can see this work pool in your Prefect UI.</p> <p>Navigate to the Work Pools tab and verify that you see <code>my-docker-pool</code> listed.</p> <p>When you click into <code>my-docker-pool</code> you should see a red status icon signifying that this work pool is not ready.</p> <p>To make the work pool ready, you need to start a worker.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#start-a-worker","title":"Start a worker","text":"<p>Workers are a lightweight polling process that kick off scheduled flow runs on a specific type of infrastructure (such as Docker). To start a worker on your local machine, open a new terminal and confirm that your virtual environment has <code>prefect</code> installed.</p> <p>Run the following command in this new terminal to start the worker:</p> <pre><code>prefect worker start --pool my-docker-pool\n</code></pre> <p>You should see the worker start. It's now polling the Prefect API to check for any scheduled flow runs it should pick up and then submit for execution. You\u2019ll see your new worker listed in the UI under the Workers tab of the Work Pools page with a recent last polled date.</p> <p>You should also be able to see a <code>Ready</code> status indicator on your work pool - progress!</p> <p>You will need to keep this terminal session active for the worker to continue to pick up jobs. Since you are running this worker locally, the worker will terminate if you close the terminal. Therefore, in a production setting this worker should run as a daemonized or managed process.</p> <p>Now that you\u2019ve set up your work pool and worker, we have what we need to kick off and execute flow runs of flows deployed to this work pool. Let's deploy your tutorial flow to <code>my-docker-pool</code>.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#create-the-deployment","title":"Create the deployment","text":"<p>From our previous steps, we now have:</p> <ol> <li>A flow</li> <li>A work pool</li> <li>A worker</li> </ol> <p>Now it\u2019s time to put it all together. We're going to update our <code>repo_info.py</code> file to build a Docker image and update our deployment so our worker can execute it.</p> <p>The updates that you need to make to <code>repo_info.py</code> are:</p> <ol> <li>Change <code>flow.serve</code> to <code>flow.deploy</code>.</li> <li>Tell <code>flow.deploy</code> which work pool to deploy to.</li> <li>Tell <code>flow.deploy</code> the name to use for the Docker image that will be built.</li> </ol> <p>Here's what the updated <code>repo_info.py</code> looks like:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=\"my-first-deployment-image:tutorial\",\n        push=False\n    )\n</code></pre> <p>Why the <code>push=False</code>?</p> <p>For this tutorial, your Docker worker is running on your machine, so we don't need to push the image built by <code>flow.deploy</code> to a registry. When your worker is running on a remote machine, you will need to push the image to a registry that the worker can access.</p> <p>Remove the <code>push=False</code> argument, include your registry name, and ensure you've authenticated with the Docker CLI to push the image to a registry.</p> <p>Now that you've updated your script, you can run it to deploy your flow to the work pool:</p> <pre><code>python repo_info.py\n</code></pre> <p>Prefect will build a custom Docker image containing your workflow code that the worker can use to dynamically spawn Docker containers whenever this workflow needs to run.</p> <p>What Dockerfile?</p> <p>In this example, Prefect generates a Dockerfile for you that will build an image based off of one of Prefect's published images. The generated Dockerfile will copy the current directory into the Docker image and install any dependencies listed in a <code>requirements.txt</code> file.</p> <p>If you want to use a custom Dockerfile, you can specify the path to the Dockerfile using the <code>DeploymentImage</code> class:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\nfrom prefect.deployments import DeploymentImage\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        image=DeploymentImage(\n            name=\"my-first-deployment-image\",\n            tag=\"tutorial\",\n            dockerfile=\"Dockerfile\"\n        ),\n        push=False\n    )\n</code></pre>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#modify-the-deployment","title":"Modify the deployment","text":"<p>If you need to make updates to your deployment, you can do so by modifying your script and rerunning it. You'll need to make one update to specify a value for <code>job_variables</code> to ensure your Docker worker can successfully execute scheduled runs for this flow. See the example below.</p> <p>The <code>job_variables</code> section allows you to fine-tune the infrastructure settings for a specific deployment. These values override default values in the specified work pool's base job template.</p> <p>When testing images locally without pushing them to a registry (to avoid potential errors like docker.errors.NotFound), it's recommended to include an <code>image_pull_policy</code> job_variable set to <code>Never</code>. However, for production workflows, always consider pushing images to a remote registry for more reliability and accessibility.</p> <p>Here's how you can quickly set the <code>image_pull_policy</code> to be <code>Never</code> for this tutorial deployment without affecting the default value set on your work pool:</p> repo_info.py<pre><code>import httpx\nfrom prefect import flow\n\n\n@flow(log_prints=True)\ndef get_repo_info(repo_name: str = \"PrefectHQ/prefect\"):\n    url = f\"https://api.github.com/repos/{repo_name}\"\n    response = httpx.get(url)\n    response.raise_for_status()\n    repo = response.json()\n    print(f\"{repo_name} repository statistics \ud83e\udd13:\")\n    print(f\"Stars \ud83c\udf20 : {repo['stargazers_count']}\")\n    print(f\"Forks \ud83c\udf74 : {repo['forks_count']}\")\n\n\nif __name__ == \"__main__\":\n    get_repo_info.deploy(\n        name=\"my-first-deployment\", \n        work_pool_name=\"my-docker-pool\", \n        job_variables={\"image_pull_policy\": \"Never\"},\n        image=\"my-first-deployment-image:tutorial\",\n        push=False\n    )\n</code></pre> <p>To register this update to your deployment's parameters with Prefect's API, run:</p> <pre><code>python repo_info.py\n</code></pre> <p>Now everything is set for us to submit a flow-run to the work pool:</p> <pre><code>prefect deployment run 'get_repo_info/my-deployment'\n</code></pre> <p>Common Pitfall</p> <ul> <li>Store and run your deploy scripts at the root of your repo, otherwise the built Docker file may be missing files that it needs to execute!</li> </ul> <p>Did you know?</p> <p>A Prefect flow can have more than one deployment.  This pattern can be useful if you want your flow to run in different execution environments.</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2},{"location":"tutorial/workers/#next-steps","title":"Next steps","text":"<ul> <li>Go deeper with deployments and learn about configuring deployments in YAML with <code>prefect.yaml</code>.</li> <li>Concepts contain deep dives into Prefect components.</li> <li>Guides provide step-by-step recipes for common Prefect operations including:</li> <li>Deploying flows on Kubernetes</li> <li>Deploying flows in Docker</li> <li>Deploying flows on serverless infrastructure</li> <li>Daemonizing workers</li> </ul> <p>Happy building!</p>","tags":["workers","orchestration","flow runs","deployments","triggers","tutorial"],"boost":2}]}
\ No newline at end of file
diff --git a/versions/unreleased/sitemap.xml b/versions/unreleased/sitemap.xml
index 59c3b350a8..f3b733639d 100644
--- a/versions/unreleased/sitemap.xml
+++ b/versions/unreleased/sitemap.xml
@@ -2,1682 +2,1682 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://docs.prefect.io/latest/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/faq/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/rest-api-reference/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/agent/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/artifacts/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/automations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/context/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/engine/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/events/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/exceptions/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/filesystems/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/flow_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/futures/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/infrastructure/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/manifests/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/serializers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/settings/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/software/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/task-runners/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/tasks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/testing/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/variables/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/core/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/fields/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/kubernetes/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/notifications/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/system/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/blocks/webhook/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/agent/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/artifact/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/block/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/cloud-webhook/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/cloud/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/concurrency_limit/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/config/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/deploy/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/deployment/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/dev/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/events/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/flow/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/flow_run/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/kubernetes/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/profile/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/root/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/shell/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/variable/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/work_pool/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/work_queue/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/cli/worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/client/base/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/client/cloud/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/client/orchestration/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/client/schemas/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/client/utilities/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/concurrency/asyncio/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/concurrency/events/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/concurrency/services/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/concurrency/sync/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/base/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/runner/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/steps/core/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/steps/pull/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/deployments/steps/utility/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/input/actions/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/input/run_input/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/logging/configuration/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/logging/formatters/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/logging/handlers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/logging/highlighters/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/logging/loggers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runner/runner/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runner/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runner/storage/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runner/utils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runtime/deployment/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runtime/flow_run/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/runtime/task_run/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/annotations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/asyncutils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/callables/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/collections/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/compat/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/context/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/dispatch/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/dockerutils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/filesystem/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/hashing/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/importtools/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/math/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/names/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/processutils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/pydantic/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/render_swagger/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/services/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/slugify/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/templating/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/text/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/utilities/visualization/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/workers/base/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/workers/block/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/workers/process/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/workers/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/prefect/workers/utilities/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/python/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/rest-api/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/admin/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/csrf_token/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/dependencies/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/flow_run_states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/flow_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/middleware/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/run_history/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/saved_searches/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/task_run_states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/api/task_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/csrf_token/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/flow_run_states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/flow_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/saved_searches/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/task_run_states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/models/task_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/orchestration/core_policy/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/orchestration/global_policy/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/orchestration/policies/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/orchestration/rules/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/actions/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/core/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/filters/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/responses/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/schedules/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/sorting/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/schemas/states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/services/late_runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/services/loop_service/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/services/scheduler/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/utilities/database/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/utilities/schemas/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/api-ref/server/utilities/server/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/connecting/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/events/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/incidents/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/rate-limits/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/workspaces/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/api-keys/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/audit-log/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/object-access-control-lists/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/roles/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/service-accounts/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/sso/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/cloud/users/teams/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/community/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/agents/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/artifacts/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/automations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/blocks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/deployments-block-based/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/filesystems/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/infrastructure/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/results/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/schedules/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/states/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/storage/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/task-runners/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/tasks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/concepts/work-pools/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/contributing/overview/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/contributing/style/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/contributing/versioning/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/getting-started/installation/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/getting-started/quickstart/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/automations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/big-data/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/ci-cd/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/cli-shell/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/creating-interactive-workflows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/dask-ray-task-runners/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/docker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/global-concurrency-limits/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/host/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/logs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/managed-execution/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/migration-guide/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/moving-data/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/prefect-deploy/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/runtime-context/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/secrets/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/settings/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/specifying-upstream-dependencies/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/state-change-hooks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/testing/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/troubleshooting/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/using-the-client/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/variables/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/webhooks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/aci/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/daemonize/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/developing-a-new-worker-type/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/kubernetes/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/overriding-job-variables/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/push-work-pools/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/serverless-workers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/guides/deployment/storage-guide/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/contribute/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/usage/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/batch/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/client_waiter/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/ecs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/ecs_guide/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/ecs_worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/glue_job/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/lambda_function/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/s3/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/secrets_manager/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-aws/deployments/steps/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/aci_worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/blob_storage/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/container_instance/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/container_instance_worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/cosmos_db/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/ml_datastore/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-azure/deployments/steps/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-bitbucket/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-bitbucket/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-bitbucket/repository/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dask/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dask/task_runners/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dask/usage_guide/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dask/utils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/jobs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/rest/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-databricks/models/jobs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/commands/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/configs/base/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/configs/bigquery/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/configs/postgres/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cli/configs/snowflake/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/clients/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/jobs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/models/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/runs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-dbt/cloud/utils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/containers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/host/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/images/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-docker/deployments/steps/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-email/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-email/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-email/message/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/aiplatform/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/bigquery/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/cloud_run/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/cloud_run_worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/cloud_run_worker_v2/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/cloud_storage/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/gcp-worker-guide/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/secret_manager/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/vertex_worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gcp/deployments/steps/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/graphql/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/mutations/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/organization/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/repository/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/repository_owner/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/user/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/utils/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-github/viewer/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gitlab/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gitlab/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-gitlab/repositories/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/custom_objects/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/exceptions/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/jobs/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/pods/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/services/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/utilities/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-kubernetes/worker/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-ray/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-ray/task-runners/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-shell/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-shell/commands/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-slack/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-slack/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-slack/messages/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-snowflake/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-snowflake/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-snowflake/database/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-sqlalchemy/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-sqlalchemy/credentials/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/integrations/prefect-sqlalchemy/database/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/recipes/recipes/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/deployments/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/flows/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/tasks/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/work-pools/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://docs.prefect.io/latest/tutorial/workers/</loc>
-         <lastmod>2024-08-30</lastmod>
+         <lastmod>2024-09-03</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/versions/unreleased/sitemap.xml.gz b/versions/unreleased/sitemap.xml.gz
index 6a1e28bdf12d0f5a2136229d79e347791f5e3c62..8724cde80f0c37991616c7617f446c58791e2e3e 100644
GIT binary patch
delta 33
pcmZn{ZWm^k@8;n6<$Zl3`+1ht?eUj4-df7RVR>ar^UwDT3;^4{4lMux

delta 33
pcmZn{ZWm^k@8;l0mb)~O{XEO6c=<~kZ!P8ExZl7z;pck>1^~jL49)-m

diff --git a/versions/unreleased/tutorial/deployments/index.html b/versions/unreleased/tutorial/deployments/index.html
index e200ef9c36..7b243463c2 100644
--- a/versions/unreleased/tutorial/deployments/index.html
+++ b/versions/unreleased/tutorial/deployments/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/tutorial/flows/index.html b/versions/unreleased/tutorial/flows/index.html
index 780497750b..06f59674f3 100644
--- a/versions/unreleased/tutorial/flows/index.html
+++ b/versions/unreleased/tutorial/flows/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/tutorial/index.html b/versions/unreleased/tutorial/index.html
index 3de5a24d89..4ca1ee0a5d 100644
--- a/versions/unreleased/tutorial/index.html
+++ b/versions/unreleased/tutorial/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/tutorial/tasks/index.html b/versions/unreleased/tutorial/tasks/index.html
index b2af4770de..5dcbb3a8dd 100644
--- a/versions/unreleased/tutorial/tasks/index.html
+++ b/versions/unreleased/tutorial/tasks/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/tutorial/work-pools/index.html b/versions/unreleased/tutorial/work-pools/index.html
index aa59c6596d..ef4db5f8bd 100644
--- a/versions/unreleased/tutorial/work-pools/index.html
+++ b/versions/unreleased/tutorial/work-pools/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>
 
diff --git a/versions/unreleased/tutorial/workers/index.html b/versions/unreleased/tutorial/workers/index.html
index 7c702d8f97..b02da0aef1 100644
--- a/versions/unreleased/tutorial/workers/index.html
+++ b/versions/unreleased/tutorial/workers/index.html
@@ -210,7 +210,8 @@
             
 <div style="text-align:center">
     <strong>
-        Prefect 3 is live! See the docs at <a href="https://docs-3.prefect.io" target="_blank" rel="noopener"> docs-3.prefect.io </a>
+        Prefect 3 is Generally Available! See the docs at <a href="https://docs.prefect.io" target="_blank" rel="noopener">
+            docs.prefect.io </a>
     </strong>
 </div>